guide

Adopting Leji

This guide takes a repository from scaffold to a useful context layer. You will map existing writing, connect entrypoints, add checks, and choose where it lives. Everyone has one dependable place to begin.

01Scaffold#

leji adopt reuses docs/, doc/, or documentation/ without moving your work. It writes:

• A leji.json with name from the directory, rootPath set, and owners from an available git identity.
• A boot profile, category indexes, onboarding brief, and complete first decision with status: accepted.
• An AGENTS.md pointer when none exists.

leji adopt --dry-run       # preview every write; nothing is written
leji adopt                 # existing repo: scaffold around what you already have
leji init                  # new repo: scaffold leji.json, a boot profile, category seeds, a first decision
leji adopt --wire-adapters # finish an adoption over a vendor entrypoint (CLAUDE.md, AGENTS.md)

Map lived paths instead of renaming them. docs/engineering/START-HERE.md conforms as a boot profile; new layers should use the lowercase-kebab defaults.

02Make it yours#

First, classify what you have already written. The seeded index files govern only the placeholders the scaffold itself wrote, so nothing you wrote earlier is governed until someone lists it. Hand the onboarding brief to your agent and approve the mapping it proposes, or edit the index files yourself.

Nothing needs to move. A category maps to curated index files, and an entry there selects either a single file or a whole directory, so an existing docs/ tree can stay exactly where it is (content categories).

Bring your decision history along. An existing ADR directory fits once its records carry the frontmatter the decision-record schema requires; the scaffold has already written <rootPath>/decisions/0001-adopt-leji.md as the first one.

Next, wire discovery. Adopting over an existing CLAUDE.md, GEMINI.md, .cursor/rules, or AGENTS.md leaves that file untouched by design, which means the adoption is still a draft: the old entrypoint does not redirect yet, leji validate reports vendor-adapter-redirect, and leji conformance verifies none against the core you claimed.

leji adopt --wire-adapters migrates that content into the context layer and replaces the entrypoint with: Read ./<bootProfilePath> first. It is the canonical context entrypoint for this repository. Validation can then pass at core.

AGENTS.md is the portable adapter, read natively by most hosts. init and adopt create a pointer-only file when absent; --no-agents skips it. Single-vendor entrypoints are never created.

For manual adoption, copy templates/leji.json and templates/boot-profile.md, create indexes, and use templates/decision-record.md. Remove every placeholder named by leji validate before claiming core; drop unneeded agents entries or categories.

03Put it to work#

The layer earns its keep when an agent reads it before the task, not after. leji start opens your coding agent from the context root, so it begins with the boot profile instead of whatever it inferred.

leji start                                  # detect a host and open it in the context layer
leji start --agent codex                    # pin the host instead of detecting
leji start --agent claude-code -- --chrome  # pass flags through to that host

leji detect lists hosts; leji start --help explains pass-through. Scripts use bootProfilePath. An agents binding, even default, records profiles but never loads them; only boot-profile instructions do.

04Keep it honest#

An honest context layer describes the repository now. These checks fail on broken references and an index that no longer matches its sources. Unindexed markdown and leftover placeholders are reported, not rejected, so you can see drift before agents follow stale guidance.

leji validate --content finds placeholder and thin content. leji status finds unindexed, dangling, or stale material. leji conformance reports progress.

At indexed, leji index generates context-index.json; leji index --check fails when it is stale. leji changelog check verifies the machine changelog.

Without CI conventions, leji ci generates a workflow; leji ci --hooks installs the gates as a pre-commit. leji ci --help explains CLI resolution.

In an established pipeline, run leji validate and leji index --check in required jobs and hooks. Pin @leji-org/leji as a lockfile devDependency.

At governed, add reviewed changes, valid agent profiles, freshness checks, and required CI.

05Where it lives#

One repository keeps one context layer beside its work.

When many repositories consume one layer, use a docs-only submodule. Create its repository, mount it in each consumer at context/, and pin it per repository. Raise reviewable, scripted pin updates. Builds and runtime must not depend on it.

Point agents at context/docs/boot-profile.md; retained vendor files redirect there. See the multi-repo example and distribution specification.

Federation is for teams that each own a layer. Its guide covers declarations, hydration, status, routing, and federated checks.

06Optional cases#

```leji-index record
- path: docs/operations/
```

```leji-index intent
- path: docs/operations/escalation-policy.md
```

leji viewer serve      # localhost preview at http://127.0.0.1:5354/
leji viewer build      # export a self-contained static folder for internal hosting

Next: the manifest reference for every field, or the specification for the rules behind them.