# waymark

MCP server exposing a codebase's OKF
knowledge bundle (`okf/`) to Claude Code — three schema-enforced query
tools instead of raw `Read`/`Grep` over hand-written docs.

## Tools

- `list_concepts(type?, tags?)` — frontmatter-only summaries. `tags` matches
  any-of the given tags.
- `read_concept(path)` — full frontmatter + body for one concept, by the
  `path` a `list_concepts` call returned.
- `find_concept_by_resource(file_path)` — reverse lookup: which concept(s)
  describe a given source file.

The server is stateless — it re-reads `okf/` from `process.cwd()` on every
call, so there's nothing to invalidate when concept files change.

## Setup (per project)

```bash
npx -y @aleburrascano/waymark init
```

This registers everything a repo needs in one step:

- Adds a `waymark` entry to `.mcp.json` (creating it if missing).
- Installs a pre-commit hook at `.git/hooks/pre-commit` that blocks commits
  when a `resource`-mapped file changes without its `okf/` concept being
  updated. Safe to re-run — it upgrades its own hook on later `waymark`
  versions but never overwrites a hook it didn't install.
- Installs two skills to `.claude/skills/`: `okf-staleness-fix` (the
  writer/judge playbook Claude Code uses to resolve a blocked commit) and
  `okf-bootstrap` (the propose/approve/generate/judge playbook Claude Code
  uses to seed an initial `okf/` bundle).
- Adds (or refreshes) an `## OKF context` section in the repo's `CLAUDE.md`.

Run it again any time to pick up updates from a newer `waymark` version.

## Bootstrapping an existing codebase

`okf/` bundles don't have to be hand-written from scratch. After running
`waymark init`, ask Claude Code to bootstrap one:

> "Bootstrap okf for this repo"

This invokes the `okf-bootstrap` skill, which:

1. Runs `waymark bootstrap` — a deterministic scan (`git ls-files`-based,
   respects `.gitignore`) that lists every candidate source file.
2. Proposes a candidate concept list grouped by domain (one concept per
   named unit you'd naturally ask "what is X" about) — nothing is written
   yet.
3. Waits for your approval, or feedback to re-group/rename/split candidates.
4. Generates each approved concept, verified by a judge subagent before it's
   written to disk.
5. Stages the new files with `git add` and reports what was generated —
   committing is left to you.

This is a one-time, human-supervised pass. Ongoing drift after that is
caught by the pre-commit hook and `okf-staleness-fix` skill, not by
re-running bootstrap.

## Local development

```bash
npm install
npm test
npm run build && npm link   # then `waymark` runs the built CLI
```

`npm test` runs vitest against TypeScript source directly — no build step
required for the test suite.