D56 — instructions kind: KB imprinting via managed block in the global instruction files¶
Context. LLM agents connected via MCP have no way to discover that a KB exists: an
"imprinting" is needed in the global instructions file that every provider always reads at each session
(CLAUDE.md, AGENTS.md, Kiro's steering).
Decision. New instructions kind, one per KB. Unlike skill/agent/hook, the
content does not live on disk: it is generated by generateKBInstructions(kbName, kbRoot), a pure,
deterministic function that lists the KB's top-level archives and gives operational instructions
(search/kb_overview/concept_read/concept_write/log_append); ContentHash is the sha256 of the
generated content. Materialization as a marker-delimited block
(<!-- cartographer:instructions:begin/end -->) inside the user's file — never a dedicated
file (except Kiro, .kiro/steering/cartographer.md, which has no pre-existing generic
file) — so everything outside the markers is never touched. Managed as a
group (applyInstructionsGroup): a single file per provider contains the concatenation of
all current KB instructions, rebuilt in full when anything in the kind changes. Non-destructive
prune: removes only the block, deletes the file only if it ends up empty. Signature gate
unchanged: unsigned instructions artifacts stay in NeedsApproval like every other kind.
Rationale. The "never touch unmanaged content" rule must be applied inside a file, not at
the whole-file level, because the destination is by construction a file that may already belong to
the user. The marker block guarantees idempotence and non-destructiveness without semantic merge.
Discarded alternatives. A dedicated file for all providers (it would not be read automatically
unless already referenced by the main file); a runtime hook injecting the context (requires
session-hook support, not universal, and starts from scratch every time).
Details: docs/sync.md §Instructions.