This walkthrough takes you from zero to a fully TRACE-enabled project. You'll install the tool, scan an existing codebase, and run your first session gate. Every code block shows real output.

1 Install

You need Node.js 18 or newer. Then:

npm install -g trace-coherence

That's it. One dependency (yaml), 48 KB total. Verify it works:

$ trace --version
trace v1.0.0

2 Scan your project

Navigate to your project and run:

$ cd my-project
$ trace scan

━━━ TRACE Scan ━━━

Phase 1: Scanning files...
  Found 47 source files

Phase 2: Detecting anchors...
  Found 5 potential anchors (files with 3+ importers)
  ✓ src/models/user.ts (8 consumers)
  ✓ src/config/database.ts (6 consumers)
  ✓ src/middleware/auth.ts (5 consumers)
  ✓ src/utils/validators.ts (4 consumers)
  ✓ src/types/index.ts (3 consumers)

Phase 3: Detecting test infrastructure...
  ✓ Jest detected (package.json)
  ✓ 23 test files found

Phase 4: Detecting quality tools...
  ✓ ESLint detected
  ✓ TypeScript compiler detected
  ✓ Prettier detected

Generated trace.yaml with:
  5 anchors, 26 consumer mappings
  Thresholds: 400 lines/file, 50 lines/function
  Quality checks: lint, typecheck, format
  Gates: warn mode (gradual adoption)

Open trace.yaml and review what TRACE found. Adjust if needed. Maybe add an anchor it missed, or remove a consumer mapping that doesn't apply. But the auto-detection gets you 80-90% of the way there.

3 Run your first gate

$ trace gate start

━━━ Start Gate — MyProject ━━━

✓ TRACE state exists
✓ Baseline tests passing (23/23)
✓ No unresolved debt (0/5)
✓ Integrity checksums verified
✓ Config validation passed
✓ AI context generated (.trace/AI_CONTEXT.md)

GATE PASSED — Session open.

Your AI tool can now read .trace/AI_CONTEXT.md for focused project context. It knows exactly which anchors exist, which consumers depend on them, and what's on the current plan.

4 Code normally, then close

Work on your project as usual. If your session might crash (long task, large token usage), drop a checkpoint:

$ trace checkpoint

This captures a git diff snapshot, classifies changes as anchor/consumer/other, and updates the session log. If you crash, the next trace gate start picks up where you left off.

When you're done, close the session:

$ trace gate end

━━━ End Gate — MyProject ━━━

Coherence check:
  ✓ All anchors verified (5/5)
  ✓ All consumers synced
  ✓ No orphaned references

Quality checks:
  ✓ Lint passed
  ✓ Typecheck passed
  ✓ Format passed

Planning:
  ✓ PLAN.yaml updated
  ✓ PROJECT_LOG.md updated

GATE PASSED — Session closed. Handoff ready.

If you had modified an anchor but forgotten to update a consumer, the gate would have caught it right here. That's the whole point.

5 Explore from here

Now that you have TRACE running, here are the commands worth trying next:

# See which files would break if you change an anchor
trace impact user_model

# Check project health without running a full gate
trace check

# Add work items to the built-in Kanban
trace plan add "Refactor auth middleware" --priority high

# See what's on the board
trace plan

# Run PR-scoped analysis in your CI pipeline
trace ci --json --comment-file /tmp/trace.md

The full command reference is in the README on GitHub.

Tips for existing projects

Start with 3 to 5 anchors. Don't try to map everything at once. Pick the files that cause the most pain when they change. Add more as you discover hidden dependencies.

Keep gates in warn mode initially. Let TRACE show you what it would block without actually blocking it. Once you trust the mappings, switch to block mode for new code.

Tell your AI tool about TRACE. Add a note to your project prompt: "Read .trace/AI_CONTEXT.md at the start of each session for project context." Most AI tools will pick it up and use it.

Commit the .trace/ directory. It's your project's structural memory. It should live in version control alongside your code.