grounded 1.1.0

Executable project memory with single-owner specs, generated views, and drift checks.

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

Command	What it does
grounded init	Adds Grounded project memory to an existing repo.
grounded validate	Checks that specs are well-formed and references resolve.
grounded render	Generates human docs and LLM context from the specs.
grounded render --check	Fails if generated outputs are stale.
grounded search QUERY	Searches project memory by ID, name, aliases, text, and relationships.
grounded context START	Builds focused LLM context around a spec ID or search query.
grounded entities	Lists entity-like specs for discovery before creating new facts.
grounded specs --uses QUERY	Shows specs related to a matching entity or spec.
grounded check-new NAME	Checks whether a proposed entity or concept probably already exists.
grounded registry	Lists merged registry types and authored specs.
grounded verify	Runs active verification spec commands.
grounded verify --include-test-bindings	Also runs executable test_binding commands.
grounded audit	Checks for drift and missing coverage.
grounded graph SPEC-ID	Shows a documentation-oriented Graphviz relationship diagram around one durable fact.

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