Grounded

Grounded keeps durable project knowledge in typed source specs, then projects that knowledge into human docs, LLM context, validation, verification checks, and drift reports.

Docs are views over project knowledge. The README is intentionally hand-authored around one protected generated block so new adopters can see the low-risk path: keep the file people already read, generate one useful section from source specs, and let grounded render --check catch drift.

Why it exists

Most projects repeat the same important idea in README files, design docs, tests, prompts, comments, and source code. At first this is fine. Later, one copy changes and the others do not. Grounded treats that as drift by giving the durable fact one owner and making generated views cite that owner.

Start small

1. Run uv sync.
2. Run uv run grounded init.
3. Add one durable project fact: a domain term, business rule, architecture decision, workflow, or verification command.
4. Add one protected generated block to an existing Markdown file.
5. Run uv run grounded validate, uv run grounded render --check, uv run grounded audit, and uv run grounded verify.

Full-file generated docs are still supported, but they are best for mature pages whose durable claims already live in source specs. The first adoption path is a protected block, not a README takeover.

Protected block exemplar

This protected block is the default adoption exemplar: keep the surrounding README hand-authored, generate one useful section from source specs, and let grounded render --check catch drift.

Common commands

During local development, prefer uv run grounded ... so the command uses the checkout.

Sources: GROUNDED-DECISION-047, GROUNDED-DECISION-054, GROUNDED-DECISION-070, GROUNDED-DECISION-058

What Grounded gives you

• Stable IDs that docs, tests, code, prompts, and plans can reference.
• Structured JSON specs so important knowledge has a predictable shape.
• A small public vocabulary: Spec, Registry Type, Generated Artifact, and Verification.
• Generated docs for humans and generated context for LLM agents.
• Validation for broken references, verification commands for project checks, and audits for stale generated artifacts.

A tiny source spec

{
  "id": "REPORT-RULE-NNN",
  "type": "business_rule",
  "name": "Date-only reports use UTC",
  "owner": "reporting",
  "status": "active",
  "description": "Defines how date-only values are displayed in generated reports.",
  "statement": "Date-only report fields must be formatted using UTC semantics, not local browser timezone semantics.",
  "tests": ["REPORT-VERIFY-NNN"]
}

Docs, tests, generated LLM context, review comments, and implementation plans can point to the same rule ID instead of rewriting the rule in five places.

Learn more

• Getting started
• Core concepts
• Incremental adoption
• LLM workflows
• Drift checks
• CLI reference
• Publishing notes
• Changelog