Fieldguide

Fieldguide is a CLI that crawls your project, reasons about it with local ModelHitch, and generates the documentation needed to navigate, extend, and verify it—including the README, feature map, agent instructions, and project-specific verification skills.

It does not scrape the marketing site. It reads the checkout, then asks ModelHitch to write current-state docs from that inventory.

Why

Most generated READMEs are wishful. Feature lists copy the pitch. Agent files invent commands. Verify docs assume a test suite that was never wired.

Fieldguide writes current-state docs:

| Artifact | Path | Job | | --- | --- | --- | | Product README | README.md | Install, purpose, commands, layout — with badges | | Feature Map | docs/FEATURE_MAP.md | What the product actually does, graded by evidence | | Agent instructions | AGENT.md | How an agent should navigate and what it must not claim | | Verify skill | .agents/skills/verify-<project>/SKILL.md | The no-secrets path that proves the map still holds |

The Feature Map and verify skill follow the same contract as a hand-written pair: evidence grades, env-gated rows, explicit gaps, and a default command that must exit 0 without secrets.

Install

npm install -g @genoventures-labs/fieldguide
fieldguide

Or once:

npx @genoventures-labs/fieldguide

Node 18.18+ is required.

Usage

Run from the project root (or pass a directory):

fieldguide
fieldguide ./path/to/app
fieldguide --dry-run
fieldguide --only map,skill
fieldguide --force          # overwrite a README that was not generated by Fieldguide
fieldguide --json           # dump the inferred model (no ModelHitch call)
fieldguide --provider ollama --model llama3.2
fieldguide --no-llm         # inventory templates only; no reasoning pass

ModelHitch is required for the default command. Fieldguide uses ~/.modelhitch/config.json when present, otherwise ollama. Start a local runtime or npx modelhitch status. Override with --provider / --model or FIELDGUIDE_PROVIDER / FIELDGUIDE_MODEL.

Existing README.md files without a <!-- fieldguide:readme --> marker are left alone unless you pass --force. Feature maps, AGENT.md, and verify skills are regenerated on every run — they are inventories, not essays.

What it reads

A gitignore-aware crawl of the tree, then a capped read of manifests and source:

• package.json, metadata.json, lockfiles, pyproject.toml, go.mod, Cargo.toml
• scripts, bins, engines, dependencies
• HTTP route strings, process.env / .env.example keys
• CI workflows, test file layout, common integrations (Firebase, Stripe, Gemini, …)

That inventory is the fact base. ModelHitch writes the four docs. It must not invent routes, scripts, or env keys that are not in the inventory. --json dumps the inventory without a model call. --no-llm writes templates for debugging. Default verify never calls a live model.

Evidence grades

Copied in spirit from a production feature map, because that is the point:

| Grade | Meaning | | --- | --- | | Proven (verify) | Asserted by the default verify path with no secret env | | Code-inspected | Present in source; not exercised by default verify | | Unverified (env-gated) | Needs credentials or a live vendor call | | Gap | Copy or helpers hint at work that is not shipped |

Docs for this repo

• docs/FEATURE_MAP.md
• AGENT.md
• .agents/skills/verify-fieldguide/SKILL.md

License

MIT © Bobby Backlogs