The Context Layer

A Leji context layer is a versioned, governed set of human-readable documents that encodes how a team thinks about its work: domain language, system invariants, conventions, guardrails, and decision records. People and agents both read it in the course of real work, and both propose changes to it through the same review gate. It lives under version control so that history, currency, and approval stay verifiable; the mechanics are in Requirements below, and who takes part and how is in Participation.

Participation#

Participation in a context layer is role-based, not tool-based. Reading, proposing, reviewing, and approving happen through whatever interface preserves the repository’s review and approval semantics; direct git or command-line knowledge is not required to take part.

  • Everyone with access reads. Access means practical access through the team’s normal tools, not shell access to the repository.
  • Anyone proposes; people approve. A proposal is an intentional request to change the context layer. It MAY be authored directly by a person, generated by an agent from a person’s request, or generated by an agent from observed work. In practice agents draft most context changes; the irreducibly human contribution is governance: proposing intent and approving what becomes canonical. A person approving a change is accountable for its meaning and consequence, not for personally operating the version control system.
  • Human meaning, machine-readable surface. The human-readable documents are the normative source of a team’s operating context. The machine-readable files (manifest, index, changelog) exist so tools can locate, index, validate, and synchronize that meaning; they never replace it.

The normative form of these flows, the circle (everyone reads, anyone proposes, people approve), is defined in governance.md.

Requirements#

  1. The context layer MUST live in a git repository and MUST be versioned with the work it describes (same repo, or a dedicated context repository consumed per distribution.md). The git repository is what makes the context layer’s history, checkout currency, and append-only changelog integrity verifiable; conforming tooling derives all three from it. Reading the context layer without that repository is a supported but degraded mode, defined in Reading modes.
  2. A repository adopting Leji MUST carry a manifest file, leji.json, at the repository root, valid against context-manifest.schema.json. The manifest is the machine entrypoint: it declares the spec version (the self-naming leji key), the context root, the boot profile path, the category mappings, the conformance claim, and ownership. It MAY also carry an agents map binding role identifiers (e.g. thought-partner, reviewer) to agent profile documents: protocols engage roles; the map decides who fills them.
  3. The manifest MUST declare a context root (rootPath). The RECOMMENDED default is docs/. All context layer paths are POSIX-style, relative to the repository root. rootPath declares where the context layer lives; it does not re-base other paths: every path in every Leji artifact resolves from the repository root, including those that repeat the rootPath prefix. Category and machine paths SHOULD fall under rootPath; validators warn when they don’t.
  4. The context layer MUST have a boot profile per boot-profile.md. The RECOMMENDED default location is docs/boot-profile.md; the manifest’s bootProfilePath declares the actual location.
  5. Context layer content MUST be human-readable first. Markdown is the RECOMMENDED format for prose; structured metadata uses YAML frontmatter or the JSON artifacts defined in machine-readable-surface.md. A document that only a machine can read doesn’t belong in the context layer.
  6. The context layer MUST have a named owner (owners.primary in the manifest): a person accountable for its currency. Ownerless context layers rot.

Reading modes: canonical and degraded#

A context layer is read in two modes; a reader MUST know which mode it is in, because the guarantees differ:

  1. Canonical. The reader resolves the context layer through its git repository: a checkout, or the repository view of the host platform. History, checkout currency, and changelog integrity are verifiable, and approved content is known current to the revision read.
  2. Degraded. The reader reaches the context layer as plain file content with no accessible git working tree or version metadata: files uploaded, synced, or copied into another interface without the repository. Plain-file reading is first-class for reading (the documents are human-readable by requirement, and the machine-readable changelog still conveys declared recency), but a degraded reader MUST treat checkout currency and approval state as unknown, never as current (see governance.md, Freshness). The changelog is the portable declared-recency surface in this mode; it does not by itself establish that the copy matches the canonical repository.

Degraded reading widens who and what can consume a context layer; it is never a path to canonical authority. A change becomes canonical only through the git-backed review gate, and a degraded copy cannot satisfy the canonical-mode checks federation depends on (pin currency, stale-pin status, ownership intactness, and restricted-mount access per distribution.md).

The vendor-adapter rule#

Agent-host configuration files (for example CLAUDE.md, AGENTS.md, .cursor/rules, .github/copilot-instructions.md):

  1. MUST NOT hold canonical context layer content.
  2. If present, MUST redirect to the boot profile (typically a one-line pointer).
  3. MAY carry host-specific mechanics that have no meaning outside that agent host (model selection, runner settings), provided no team knowledge lives there.

The entrypoint conventions that exist tell an agent host where to look; Leji defines what the agent finds there. One source of truth, every participant reading it.

What the context layer is not (non-normative)#

  • Not a wiki. Nothing forces a wiki current. The context layer stays alive because agents read it on every task (wrong context produces wrong output that is felt immediately), changes ride review like code, and tooling makes staleness visible.
  • Not documentation in the traditional sense. Documentation describes what the system does, after the fact. The context layer describes how the team thinks, in the present tense, and is read constantly by people and agents alike.
  • Not a template to import. Borrowed context goes stale immediately. The value of a context layer is that it is the team’s own representation; Leji standardizes the shape and the governance, not the contents.