guide

Build a context layer, check it conforms.

Five commands, install to conformance. Everything ships in the package, so it runs offline.

Supported runtimes Node.js 22+ Python 3.10+ Go 1.23+

01Install the tooling

All three pass the same fixture suite, so flags, JSON output and exit codes are identical whichever one your CI installs.

In a Node repository, add it as a devDependency (npm i -D @leji-org/leji) so CI, the hook and every contributor run the pinned version.

$ npm install -g @leji-org/leji

02Bootstrap a new context layer, or adopt an existing repo

You get a leji.json manifest at the repository root, a boot profile, seeded category documents, a first decision record, and an onboarding brief. None of it requires an agent.

The scaffold starts as placeholder. Accept the offer and the agent reads your repository, proposes the mapping for you to approve, then deletes the brief. Decline and you get the command to run later; --yes skips it, so CI stays unattended.

Working alone? --mode solo seeds identity and writing-style starters and points the brief at an owner interview; answers can be typed, attached, or dropped in a folder. Only the synthesis you approve becomes context, and your raw files never enter git: init and adopt refuse to run while anything under <rootPath>/.leji/ is tracked, and the agent deletes the artifacts once the context layer is populated.

Already have a docs/ tree?adopt scaffolds alongside it and moves nothing. Your existing entrypoint is left untouched, so until --wire-adapters runs you have an adoption draft rather than a conformant layer.

leji adopt --dry-run    # the exact write plan; nothing is written
leji adopt              # adopt an existing repo (leji init for a new one)
                        # then offers to open Claude Code or Codex

leji adopt --wire-adapters  # adopt over an existing CLAUDE.md / AGENTS.md

03Validate

Schema-checked: the manifest, the index, the changelog, and agent-profile and decision-record frontmatter.
Structure and lint: boot profiles, index files and ordinary documents have no schema. Declared files must exist, and the changelog is append-only against HEAD. At indexed and above, a stale index fails hard.

After a plain adopt over an existing CLAUDE.md or AGENTS.md, expect one failure, vendor-adapter-redirect, until --wire-adapters runs.

leji validate           # schemas + lint rules
leji validate --content # + placeholder / thin-content warnings
leji index              # generate the index

04Claim a level, then check it

Partial adoption is by design: start at core, and each level contains the last. The manifest declares the claim; leji conformance scores the context layer against it.

core → indexed → governed → federated

What each level asks of you

leji conformance        # score the claim

05See your context layer

The same layer your agents read, rendered for people.

leji view               # open the human-readable viewer in your browser
leji viewer build       # export a static folder to host behind internal auth

Keep it honest in CI

The provider is inferred from your origin remote, falling back to GitHub when the remote names none.

leji ci                 # generate the workflow
leji ci --hooks         # the same gates as a local pre-commit

# what the generated job runs:
leji validate           # schemas + lint rules
leji index --check      # stale index fails

# add at indexed and above:
leji changelog check    # append-only

Exit codes are CI-native: 0 clean, 1 findings, 2 usage error.

Enter the context layer

The layer becomes the agent's first context, with no vendor file in between.

leji start              # or --agent claude-code | codex to pin one

Several hosts detected? It asks. None detected, or a scripted / CI run? It prints the command to run instead of guessing. The adoption guide covers host pass-through flags and the vendor-file fallback table.

Give your agent the tools, not just the context

Entering the context layer gives your agent the context. The MCP server gives it the tooling: a local, read-only server that runs validation and conformance against the context layer on disk, so the agent never needs a shell. It reads and reports; it never writes.

# Claude Code (available in every project)
claude mcp add leji --scope user -- npx -y @leji-org/mcp

# Codex
codex mcp add leji -- npx -y @leji-org/mcp

init and adopt offer to register it for you: project-scoped for Claude Code, user-level for Codex. The commands above are for anyone who skipped that prompt. Any MCP client works; the MCP server page has the full tool list.

Then adopt for your situation

Monorepo	One repository, one context layer, initialized once at the repository root.
Many repos, one layer	A dedicated context repository, mounted docs-only in each consuming repo, pinned per repository.
Several owned layers	Teams that each already own a context layer. Mount each as a sibling; ownership and workflow stay unchanged.

From a script

Every command is also a library call, for hooks, bots and build steps. Source at leji-org/leji, Apache-2.0.

import { validateLayer, writeIndex, conformanceReport } from '@leji-org/leji';

const { findings } = validateLayer('.');

Next: the adoption guide for an existing repository, or federation when several teams each own a context layer.