Skip to content

D1097 — initialize carries the operating guide; a provisioned client marks itself

Decision. Every connection that is not marked provisioned receives, as the instructions of initialize and of server/discover, a guide built from one server-side generator: per KB of the connection's effective set its routing sentence and the archives the caller may see, the client-neutral operational bullets once, then each KB's instructions.md behind its scope sentence. A client that has the managed instructions block says so with ?provisioned=1 on the routed URL and gets exactly what it got before. cartographer connect/sync/reconnect write the marker into every routed entry and mcpbridge adds it when it forwards.

Why. The server alone must be usable by an MCP client with no Cartographer client side (an SDK loop, a desktop client): initialize.instructions is the only protocol channel for "how to use this server", and the text existed only client-side. The guide is produced by editing the initialize and discover results per handshake, not at build time, because the SDK server is memoised and its routed views are shared by every URL that resolves to the same set, while the text depends on the caller and on files read from disk (an artifact_write or a pull shows up at the next handshake, no restart). The marker travels on the request context, not in the view cache key: the guide is per handshake, the doctor nudge of plan #1101 runs on the target KB's server where only the context reaches, and a flag in the key would double the cached views.

Alternatives rejected. Setting Instructions when the SDK server is built: stale and caller-blind. A marker in the view cache key: doubles views for no gain. A /health capability field or a response header for the marker: the server ignores unknown query parameters, so a client can always send it, and an older server has no guide to suppress. Sending the guide to everyone: a provisioned client would read the same text twice. Counting pages per archive: nothing read the count, and it walked every archive on each sync_pull. Two generators: they would drift.

Consequences. The managed block is byte-identical (golden tests pin text and ContentHash), so no client re-syncs because of this. The neutral part has a byte budget pinned by a test (paid by every handshake); curated bodies are not capped. A guide never names a KB the caller cannot read nor an archive it cannot see; the one whole-KB file it carries is instructions.md, a deliberate choice (the KB's own directions to whoever works in it). instructions.md and data/ that are symlinks are not read. An older client against this server sends no marker and receives the guide on top of its block until it syncs with this release's binary (the SessionStart hook's sync heals it). The block's own reader still follows a symlinked instructions.md; not changed here because the block must stay byte-identical.