stele · docs

curl -fsSL https://raw.githubusercontent.com/jgeschwendt/stele/main/scripts/install.sh | bash

# pin a version
curl -fsSL https://raw.githubusercontent.com/jgeschwendt/stele/main/scripts/install.sh | bash -s v0.3.0

# prereleases
curl -fsSL https://raw.githubusercontent.com/jgeschwendt/stele/main/scripts/install.sh | channel=canary bash

# from source
cargo install --git https://github.com/jgeschwendt/stele stele-cli

1. Install — one binary, pinned in CI to the version you tested against.
2. Scaffold — stele init from the repo root scaffolds AGENTS.md skeletons: a system node at the root, container nodes for candidate directories. Fill in purpose, real commands, and the claims worth enforcing; delete the skeletons that don't deserve a node. The graph follows interface boundaries, not the tree.
3. Anchor your claims — every invariant and hazard names an anchor: path#symbol for a definition or markdown heading, or ※ <slug> for a named landmark comment (// ※ refund-cap) that survives renames and moves — the anchor: field quotes that token verbatim. Anchors are what make a claim checkable.
4. Build — stele build compiles authored sources into .stele/graph.lock and .stele/index/. Build is the reconciliation point: it re-stamps each claim's verified mark against current code, so run it locally once you've reviewed that the claim still holds.
5. Emit — stele emit renders the router regions into AGENTS.md, the transpose indexes, and the shim. Anything outside a marker region stays yours.
6. Commit — the AGENTS.md files, the lock, the indexes. The lock is the canonical graph: queries and CI read it and never re-derive it. Paths the engine should never scan go in a root .steleignore, gitignore syntax.
7. Enforce — CI checks out full history (freshness walks blame), then runs stele check followed by stele emit --check. CI never runs stele build — that would launder staleness.
8. Query — agents and humans read the graph instead of grepping docs, over the CLI or MCP.

stele init                     # scaffold nodes
stele build && stele emit      # compile the lock, render the files
stele check                    # six assertion classes, exit 1 on violations
stele emit --check             # committed files vs what the lock renders

# the CI gate
- uses: actions/checkout@v5
  with:
    fetch-depth: 0        # full history — freshness checks use blame
- run: curl -fsSL https://raw.githubusercontent.com/jgeschwendt/stele/main/scripts/install.sh | bash -s v0.3.0
- run: ~/.local/bin/stele check
- run: ~/.local/bin/stele emit --check

• a non-matching glyph is prose — ※ is a common annotation mark in CJK comments, so ※ 注意 is silently ignored, never an error; a typo in a landmark a node references still fails referentially.
• ✻ is reserved for human notes, and CLI addresses stay ASCII: stele blame billing/refund-cap — no glyph is ever typed into a shell.
• upgrading from 0.2 is a hard cut — a version-1 lock fails every verb with run stele migrate, then stele build. stele migrate rewrites the old stele: grammar in place over build's scan scope, idempotently; there is no dual-read.

stele emit --check is the seventh gate in practice: it fails when committed AGENTS.md files diverge from what the lock would render.

stele root                                  # the system node — start here
stele unfold payments --depth 2             # a node with its children
stele invariants --touching src/charge.rs   # claims governing the file you're editing
stele hazards                               # every active hazard
stele nodes --kind container                # the graph by kind
stele blame payments/idempotent-charges     # provenance of one claim

For MCP-capable harnesses, stele serve exposes the same read verbs as tools:

{ "mcpServers": { "stele": { "command": "stele", "args": ["serve"] } } }

stele init --undercover

• the graph home is the parent of the git common dir — the repo root in a normal checkout, the shared bare root in a grove layout, so every linked worktree reads the same private graph and it survives worktree churn.
• node sources live in an untracked overlay — <home>/.stele/tree/<dir>/AGENTS.md, mirroring tree paths, alongside the private lock and transpose indexes.
• one materialized file — CLAUDE.local.md, a relative @-import of the overlay root that Claude Code auto-loads. Analogous to any other .local file: yours, never committed.
• git status stays clean — a managed block in the common dir's info/exclude hides the private paths. Only the marker's presence selects the mode; without it every command is byte-for-byte normal.
• the ladder trades its files rung for invisibility — no CI story, because nothing is committed for a pipeline to gate; stele check is yours to run locally, and your surface is CLI → MCP plus the shim.

stele v0.3.0 · SPEC Draft 0.10 · SPEC.md and GUIDE.md are the contract.