Metadata-Version: 2.4
Name: grounded
Version: 1.1.0
Summary: Executable project memory with single-owner specs, generated views, and drift checks.
Project-URL: Homepage, https://github.com/adieyal/grounded
Project-URL: Repository, https://github.com/adieyal/grounded
Project-URL: Documentation, https://adieyal.github.io/grounded/
Project-URL: Issues, https://github.com/adieyal/grounded/issues
Project-URL: Changelog, https://github.com/adieyal/grounded/blob/master/CHANGELOG.md
Author: Grounded contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: documentation,knowledge-graph,llm,project-memory,software-governance
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1.0
Requires-Dist: jsonschema>=4.0.0
Description-Content-Type: text/markdown

# 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

<!-- grounded:generated:start GROUNDED-DOC-001 -->
<!-- This block is generated by Grounded. Edit the source specs, not this prose. -->
<!-- owner: GROUNDED-DOC-001 -->

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`
<!-- grounded:generated:end GROUNDED-DOC-001 -->

## 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

```json
{
  "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](docs/getting-started.md)
- [Core concepts](docs/concepts.md)
- [Incremental adoption](docs/incremental-adoption.md)
- [LLM workflows](docs/llm-workflows.md)
- [Drift checks](docs/drift-checks.md)
- [CLI reference](docs/cli-reference.md)
- [Publishing notes](docs/PUBLISHING.md)
- [Changelog](CHANGELOG.md)
