# JOE — Repository Agent Guidance

> Applies to coding agents working on the JOE (Json Object Editor) repository. Read `docs/JOE_MCP_Modernization_Plan.md` before making MCP changes, and the assigned story before writing code.

## Mission
JOE is a schema-first, extensible Node.js platform for structured objects, relationships, apps and audit history. Make JOE's existing capabilities accessible to standards-compliant AI clients without creating another source of truth or instance-specific integration code.

## Working rules
1. **Inspect before editing.** Confirm actual paths, runtime dependencies, server bootstrap, authentication middleware, tool handlers and test conventions; documentation may be older than the code. State discrepancies explicitly.
2. **Respect scope.** Implement only the assigned story and required supporting tests. Do not silently begin the OAuth, Skill, or ChatGPT integration epics during the transport story.
3. **Reuse JOE Core.** Keep business logic in `Schemas`, `Storage`, `Cache` and existing tool handlers. MCP is an adapter, not a new object engine.
4. **Schemas are authoritative.** Discover `itemtype` definitions and relationships dynamically. Do not hardcode instance-specific schema fields or copy database data into instructions.
5. **Never weaken security.** No unauthenticated fallback for protected tools in production; do not log tokens, user records or sensitive fields. Treat tool input and returned data as untrusted. Do not assume toolset labels are permissions.
6. **Safe mutation.** Preserve full objects and unknown legitimate fields, validate according to actual schemas and permissions, verify references, and do not set server-managed `joeUpdated`. Treat IDs as opaque strings (JOE may use CUID, UUID, Mongo ObjectId, etc.). Existing full-document save workflows are vulnerable to overwrite races; do not claim concurrency safety without enforcing it server-side. **Never sparse-save:** `saveObject` replaces the document — always `getObject`/`understandObject` → merge → save the complete object. Field-only payloads wipe omitted properties.
6b. **Deep links.** UI URLs are `{origin}{appBase}/#/{itemtype}/{_id}`. Hash is always `#/{itemtype}/{_id}`. `appBase` is instance-specific (often `/JOE`); never assume site root.
7. **Audit invariants.** Writes must continue through the canonical storage/event/history path. Never write directly to MongoDB from new MCP handlers. Reject invalid or unauthorized changes without altering data or history.
8. **Reviewable changes.** Use focused commits/diffs, clear error handling, tests and a short report of behavior changed, behavior preserved and known risks.
9. **Local first.** Use a disposable local database/records and MCP Inspector or an SDK test client. Never use production Haddens or P60 objects as fixtures.
10. **No invented API behavior.** Verify SDK and current protocol compatibility in the installed versions before implementing. Prefer official SDK over hand-written protocol parsing.

## Relevant code areas (verify against current checkout)
- `server/modules/MCP.js`: legacy direct JSON-RPC tool registry, manifest, `/mcp` route.
- `server/modules/McpV2.js`: stateless Streamable HTTP at `/mcp/v2`, agent-token bearer auth, and token mint/revoke routes.
- `server/modules/Schemas.js`: schema summaries and relationship metadata.
- `server/modules/Storage.js`: persistence, events and history. Read `docs/storage.md` before changing saves, ids, or Mongo.
- `server/modules/Mongo.js`: MongoDB interface (`mongodb` driver). `docs/storage.md` is the agent reference.
- `server/init.js`: module startup and route wiring.
- Instance `_schemas`, `_apps`, `_plugins`: instance-specific definitions; avoid modifying them for a generic core feature.

## Current versus target protocol
Current JOE still accepts `POST /mcp` with direct JSON-RPC method names like `getObject`, and exposes `GET /.well-known/mcp/manifest.json`. Those routes keep cookie or HTTP Basic auth. 0.11.0 adds stateless Streamable HTTP at `/mcp/v2` (`initialize`, `tools/list`, `tools/call`) authorized with `Authorization: Bearer` and a JOE agent token. Test it at `/mcp-modernization.html`. Do not replace `/mcp` in this slice. Skills and the ChatGPT OAuth handoff are later work.

## Agent operating behavior (later skill work)
- Prefer concise discovery (`getSchemas` summaries, `understandObject`), not an unconditional heavy `hydrate` call.
- Explore through cache when appropriate; use authoritative storage reads when making or verifying edits.
- Writes require user authorization/confirmation at the client workflow level **and** server enforcement regardless of instructions.
- Never invent references; verify target IDs and type constraints.
- Skill guidance does not confer access or replace authorization.

## Implementation protocol
For each story: (1) read plan and story, (2) inventory relevant code, (3) summarize plan/risks, (4) implement minimal change, (5) run targeted tests, (6) document migration impact and any unresolved dependencies. If security or data behavior is ambiguous, stop that unsafe portion and propose a safe alternative.

## Sources and precedence
1. Actual code and executable tests for implementation facts.
2. `docs/JOE_MCP_Modernization_Plan.md` for project decisions.
3. Assigned story for scope/acceptance criteria.
4. JOE Master Knowledge Export (October 2025) and CustomGPT instructions v2/v3 for historical intent, **not** unquestioned protocol/security guidance. In conflicts use this guide and the plan, and record the discrepancy.