grounded 1.0.0

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

---

last_updated: 2026-05-30

Grounded

Grounded helps teams keep project knowledge from drifting by giving durable facts one source of truth and generating documentation, LLM context, validation, verification checks, and drift reports from that registry.

The problem

Most projects repeat the same important idea in many places: design docs, README files, 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.

Inspect the graph

• GROUNDED-DECISION-058 (decision): List registry types and specs from the CLI - Documents the registry inspection CLI command so maintainers and agents can see both registry types and authored specs from one entry point.

What Grounded gives you

These source specs describe the current Grounded value proposition without making README.md the durable owner of those claims.

• One canonical owner for each durable project fact.
• Stable IDs that docs, tests, code, prompts, and plans can reference.
• Structured JSON specs so important knowledge has a predictable shape.
• A small metamodel for registry types, value types, and generated views.
• A crisp split between registry_type definitions, registry_unit structure, knowledge_unit specs, and authored spec instances.
• Generated docs for humans and generated context for LLM agents.
• Validation for broken references, verification commands for project checks, and audits for stale generated views.

A tiny example

Instead of leaving an important rule only in prose, give it a stable Grounded ID.

{
  "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.

CLI workflows

• GROUNDED-DECISION-047 (decision): Generate Graphviz relationship graphs - Documents the Graphviz DOT CLI export so Grounded relationship graphs can be generated from the same canonical registry references used by rendered docs.
• GROUNDED-DECISION-054 (decision): Search project memory from the CLI - Documents the CLI search workflow so LLM agents can discover existing entities, concepts, and specs before creating new specs.
• GROUNDED-DECISION-058 (decision): List registry types and specs from the CLI - Documents the registry inspection CLI command so maintainers and agents can see both registry types and authored specs from one entry point.

Quick start

From a checkout today. After the first PyPI release, install with pipx install grounded or run one-off commands with uvx grounded.

1. Run uv sync.
2. Run uv run grounded init.
3. Run uv run grounded validate.
4. Run uv run grounded render.
5. Add one durable project fact: a domain term, business rule, architecture decision, workflow, or verification command.
6. Run uv run grounded validate, uv run grounded render --check, and uv run grounded audit.

Migration path

README.md is now a full-file generated_document output. The same path can be used for docs pages as their durable claims move into source specs and their document_section graphs become complete.

• GROUNDED-DECISION-037: Slice specs define explicit, scoped documentation views with their own metadata, generated index.html page, optional index template override, and optional stylesheet. Slice pages render only their declared members in navigation and search while preserving links into the full Grounded graph.
• GROUNDED-DECISION-060: Grounded documentation is generated from a documentation graph. Durable knowledge lives in source specs; generated_document specs define output artifacts; document_section specs define ordered projections over source specs; documentation_set specs group generated documents; asset specs govern static and generated media. README.md and docs pages should move toward generated views rather than independent sources of truth.
• GROUNDED-DECISION-061: Generated document specs support explicit write modes. protected_block mode updates a governed block inside an existing file for incremental migration, while full_file mode lets a generated_document own the entire output path once the source specs and section graph are mature enough. README.md is now generated in full_file mode from GROUNDED-DOC-001.

Your first useful spec

Good first candidates are facts that already cause confusion or repeated explanations:

• "Revenue means sales excluding tax."
• "Manual supplier-item aliases outrank fuzzy matches."
• "Date-only report fields use UTC semantics."
• "Generated docs must not be edited by hand."
• "A completed todo cannot be reopened without an explicit reopen action."

Start with one fact. Give it a stable ID. Link other docs, tests, plans, and prompts back to that ID.

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 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 project-specific verification commands declared in specs.
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.

Typed tags and constrained references

Plain string tags are useful for loose grouping. Use typed tags when the classification should be validated.

{
  "tags": [
    { "type": "EntityType", "value": "BusinessEntity" }
  ]
}

Projects can declare typed tag vocabularies in the type registry and require reference fields to point only at targets with a specific typed tag.

Adopt incrementally

You do not need to model your whole system on day one.

Adoption ladder

Level 1: Canonical glossary

Use Grounded for important project terms.

Good for domain language, renamed concepts, avoiding duplicate terminology, and giving LLMs stable vocabulary.

Level 2: Rules and decisions

Add business rules, architecture decisions, assumptions, examples, and workflows.

Good for keeping design intent visible and linking implementation plans to stable IDs.

Level 3: Generated docs and LLM context

Render human docs and LLM-readable context from the same specs.

Good for onboarding, code review, agent workflows, and reducing stale prompt instructions.

Level 4: Verification and drift checks

Use verification specs and audits to prove that important facts still have checks.

Good for CI, semantic contracts, executable documentation, and project governance.

When to use Grounded

Use Grounded when:

• project knowledge repeatedly drifts between docs, tests, code, and prompts
• LLM agents need reliable project context
• domain vocabulary matters
• business rules must stay linked to tests or checks
• generated docs should come from validated source material
• you want a small, incremental path toward executable documentation

Grounded is probably too much if your project has very little durable domain knowledge, your docs rarely affect implementation, or nobody will run validation, rendering, and audit commands.

Examples and deeper docs

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

Project layout

grounded.yml
.grounded/
  specs/
  registry/
  schemas/
  templates/
  renderers/
    templates/
  generated/
    docs/
    llm/

grounded init creates this layout. Use grounded init --grounded-dir path/to/memory to choose a different project directory. Use grounded init --update-agents to add a Grounded section to AGENTS.md.

Documentation publishing

The GitHub Pages deployment workflow builds the root generated Grounded docs at the Pages site root and the Todo example site under todo/, then publishes them from an assembled Pages artifact. Rendered site directories remain ignored by git.

• GROUNDED-DECISION-049: The GitHub Pages deployment workflow builds the root Grounded registry docs and the standalone Todo example docs during deployment, validates and audits the root registry, validates the Todo registry, verifies rendered outputs are current, assembles the generated root docs at the Pages site root and the generated Todo site under pages-site/todo, uploads that assembled site as a Pages artifact, and deploys it with the official GitHub Pages deployment action. Rendered site output remains out of version control.