Quickstart

A first run on a repository you already have, in two routes. Quick is the shortest sequence that leaves a working, committed context. Guided is the same run with the plan previewed before anything is written and the diff read afterwards — take it if this is a repository you would rather not surprise.

Both end in the same place. Neither invents anything about your project: everything Syngraphe writes is listed in what init writes.

Install

npm install -g syngraphe

npx, project-local and from-source installs are on the installation page.

Run it

1. Initialize

cd my-project
syngraphe init

Actual outputPrinted by syngraphe init in a repository that has no AGENTS.md or CLAUDE.md yet.

Syngraphe initialization

CREATE
  .context/manifest.json
  .context/index.md
  .context/truth/architecture.md
  .context/truth/conventions.md
  .context/state/current.md
  .context/decisions/README.md
  .context/history/README.md
  AGENTS.md
    + Syngraphe repository-context bootstrap
  CLAUDE.md
    + @AGENTS.md compatibility import

9 files written.

2. Write the context

The generated documents are headings and nothing else. That is deliberate: Syngraphe knows nothing about your repository, and generated prose pretending otherwise is the exact failure the tool exists to prevent.

GeneratedThe whole of .context/state/current.md as syngraphe init writes it.

# Current State

## Current focus

## Recent relevant changes

## Next

## Blockers

Open .context/truth/architecture.md and .context/state/current.md and fill the headings in.

ExampleInvented, to show the level of detail — not a template, and not written by any command.

# Current State

## Current focus

Migrating billing off the legacy schema.

## Recent relevant changes

- `invoices` is now written by the worker, not the API.

## Next

- Backfill historical rows, then delete the legacy table.

## Blockers

- Waiting on the finance export before the backfill can run.

Keep the two directories apart: truth/ is what stays true, state/ is what is true this week. See writing the context for what belongs where.

3. Check it, then commit

syngraphe check
git add .context AGENTS.md CLAUDE.md
git commit -m "Add repository context"

check verifies the manifest, the directory structure, every path referenced from index.md, and both managed blocks. Until state/current.md says something, it ends on a STATE002 warning that the file contains only headings — the tool asking you to finish the job, not an error. It exits 0.

From here the context is ordinary repository content: reviewed in pull requests, versioned by Git, and read by anyone — or anything — that opens the repository.

1. See the plan first

cd my-project
syngraphe init --dry-run

Actual outputPrinted by syngraphe init --dry-run in a repository that already has AGENTS.md, CLAUDE.md and .cursor/rules/.

Syngraphe initialization plan

CREATE
  .context/manifest.json
  .context/index.md
  .context/truth/architecture.md
  .context/truth/conventions.md
  .context/state/current.md
  .context/decisions/README.md
  .context/history/README.md

PATCH
  AGENTS.md
    + Syngraphe repository-context bootstrap

  CLAUDE.md
    + @AGENTS.md compatibility import

UNCHANGED
  .cursor/rules/  (vendor configuration, left untouched)

No files were modified.

Three things are worth noticing:

• CREATE lists files that do not exist yet. A file already present is never listed there.
• PATCH shows which existing files gain a managed block. Only the block is added; the rest of the file is untouched.
• UNCHANGED is what Syngraphe found and deliberately left alone — here, Cursor's own rule files, which belong to you.

--dry-run builds the same plan the real run applies. It is not a separate code path.

2. Apply it

syngraphe init

The output is the same plan, with 9 files written. in place of the last line. Now read the diff:

git diff

Actual outputThe complete change init made to an existing AGENTS.md.

 # AGENTS.md

+<!-- syngraphe:start version="1" -->
+<!-- Managed by Syngraphe. Do not edit this block manually. -->
+
+This repository maintains shared project context in `.context/`.
+
+Before substantial work, read `.context/index.md` and the relevant context documents.
+Keep that context accurate: when a change makes it out of date, update it in the same change.
+If Syngraphe is available, run `syngraphe check` before completing substantial work.
+If `AGENT-POLICY.md` is present, read it before planning multi-step or expensive work.
+<!-- syngraphe:end -->
+
 ## Build

 - npm run build

Additive, small, and reviewable. That is the whole change to your existing files, and re-running init reproduces it rather than adding a second copy. See managed blocks for what happens when someone edits inside the markers.

3. Write the context

The generated templates are headings and nothing else — deliberately, so nobody is tempted to leave generated prose in place. Start with two files.

ExampleInvented content for both files, to show the level of detail. syngraphe init writes the headings and leaves them empty.

.context/truth/architecture.md

# Architecture

## Overview

A Fastify API in front of PostgreSQL, plus a worker that drains the outbox table.

## Major components

- `src/api/` — HTTP layer. Thin: validation and serialization only.
- `src/domain/` — business rules. No framework imports here.
- `src/worker/` — outbox drain, at-least-once delivery.

## Important constraints

- The API must stay stateless: any instance may serve any request.
- The outbox is the only path for outbound events.

.context/state/current.md

# Current State

## Current focus

Migrating billing off the legacy schema.

## Recent relevant changes

- `invoices` is now written by the worker, not the API.

## Next

- Backfill historical rows, then delete the legacy table.

## Blockers

- Waiting on the finance export before the backfill can run.

Keep the two apart: truth/ is what stays true, state/ is what is true this week. See writing the context for what belongs where.

4. Check it

syngraphe check

Actual outputPrinted by syngraphe check once state/current.md has been filled in.

Syngraphe context integrity

✓ manifest
✓ context structure
✓ internal references
✓ AGENTS.md
✓ Claude integration
✓ context state

No problems found.

Before you fill state/current.md, the last check reports a STATE002 warning saying the file contains only headings — that is the tool asking you to finish the job, not an error, and the command still exits 0.

5. Commit

git add .context AGENTS.md CLAUDE.md
git commit -m "Add repository context"

From here the context is ordinary repository content: reviewed in pull requests, versioned by Git, and read by anyone — or anything — that opens the repository.

6. Wire it into CI

- run: npx syngraphe check --strict

--strict makes warnings fail the build too. See continuous integration for the exit codes and the JSON output.

What init writes

Nine files, and nothing else. Seven are new files under .context/; two are the agent bootstrap files, created if they are missing and patched with a single managed block if they already exist.

Path	What is written into it
.context/manifest.json	protocol, schemaVersion and layout — three keys, listed in full below.
.context/index.md	The reading order, pointing at the files in this table. The one generated document that contains prose.
.context/truth/architecture.md	Empty headings: Overview · Major components · Data flow · External systems · Important constraints.
.context/truth/conventions.md	Empty headings: Repository conventions · Development workflow · Important rules.
.context/state/current.md	Empty headings: Current focus · Recent relevant changes · Next · Blockers.
.context/decisions/README.md	Two sentences saying what the directory is for.
.context/history/README.md	Two sentences saying what the directory is for.
AGENTS.md	One managed block pointing agents at .context/. Everything already in the file is preserved.
CLAUDE.md	One managed block containing @AGENTS.md, so Claude Code reads the same file every other agent does.

GeneratedThe complete manifest, byte for byte.

{
  "protocol": "repository-context",
  "schemaVersion": 1,
  "layout": "standard"
}

GeneratedThe whole of .context/truth/architecture.md. The other two documents under truth/ and state/ are the same shape: headings, no content.

# Architecture

## Overview

## Major components

## Data flow

## External systems

## Important constraints

Nothing outside that list is created, moved or rewritten. Vendor configuration that Syngraphe recognises — .cursor/rules/, .cursorrules, .codex/ — is reported under UNCHANGED and never written to; see agent integrations for why.

What to read next

• Writing the context — what goes in each file.
• Adopting an existing repository — when the documents you need already exist somewhere else.
• Agent integrations — how each agent finds the context.
• CLI reference — every command and flag, including truth new and the other document commands for adding context as it grows.