Deterministic knowledge about your own workspace

Five commands, each with a shorter alias

The framework CLI ships as @happyvertical/smrt-cli and installs the smrt binary. Each knowledge command is registered under a dev: name with a knowledge: alias, so both spellings run the same handler.

• dev:knowledge-index builds the composed index for a scope.
• dev:knowledge-check runs the deterministic freshness and stale-reference checks.
• dev:knowledge-diff reports what changed against a git base ref.
• dev:knowledge-review-context and dev:knowledge-architecture-context return prompt bundles.

# Build the composed index for the whole project.
smrt dev:knowledge-index --format json

# Deterministic freshness check; non-zero exit when it is not ok.
smrt knowledge:check --strict --format markdown

# What changed against a git base ref.
smrt knowledge:diff --base main --format markdown

# Portable prompt bundles for review and architecture work.
smrt knowledge:review-context --scope package --package content --format markdown
smrt knowledge:architecture-context "tenant-aware publishing workflow" --format json

Options differ per command

--scope and --package are shared by all five commands. --scope defaults to project and accepts project, local, package, sdk, or installed. The remaining options belong to specific commands, so a flag copied between them will not always apply.

• --changed and --strict belong to dev:knowledge-check only.
• --base belongs to dev:knowledge-diff only and defaults to HEAD.
• --format is json by default for dev:knowledge-index and markdown for the other four.
• --json remains as a deprecated alias for --format json on every command except dev:knowledge-index.

Where objects come from, and why that is recorded

Package discovery reads the workspace globs rather than assuming a packages directory, so apps are indexed the same way packages are. Resolution runs in a fixed order: the packages list in pnpm-workspace.yaml, then workspaces in package.json, then packages/* as a last-resort fallback. Within each package, objects resolve from a domain artifact, a package-local manifest, or a source scan. objectSource records the selected source and reason.

• objectSource is one of domain-artifact, manifest, scanner, or none.
• The workspace root is indexed when it has a package.json, with member directories excluded.
• Manifest objects belonging to another package are rejected rather than counted.
• Scanner-provenance packages carry no column type, so some schema facts are absent by design.

Consumer apps can inspect what they installed

A consumer application may author no framework package of its own, so workspace discovery alone cannot describe the SMRT surface it runs. schemaVersion 3 adds installedPackages: an enumerated, deduplicated view of installed @happyvertical/smrt-* and known SDK packages, available directly through --scope installed.

• Each installed package records its version, isInstalledDependency, and agentDocSha256 for the shipped AGENTS.md.
• The documentation hash is the drift signal; a version change alone does not imply that the agent contract changed.
• Installed dependencies are indexed but skipped by the freshness gate, because a consumer cannot repair documentation inside a published package.
• Authored-package coverage remains separate, so installed objects cannot hide a broken workspace scan.

smrt dev:knowledge-index --scope installed --format json

Coverage and diagnostics instead of a silent empty answer

Coverage and diagnostics were added in schemaVersion 2. Coverage names the workspace globs, their source, and the package directories found. Coverage also identifies authored packages with and without objects and gives a reason and remedy. A zero-object result produces an error-grade diagnostic that names the checked roots and artifact paths. The tool never reports an unreadable project as a project with no model.

• Coverage and diagnostics are computed before scope filtering, because they describe discovery itself.
• Diagnostics propagate into the architecture, review, and reflection results.
• A response budget never trims diagnostics; only the objects payload is budgeted.

Authored documentation is part of the contract

AGENTS.md chains are additive: a package carries its own instructions and an agent loads the chain it sits in. A package nested inside another workspace package deliberately carries no AGENTS.md or CLAUDE.md. Otherwise, the agent would load the parent and child files together. Put that expertise in the linked module documentation for the parent.

• Authored docs are required even for private packages.
• A reappearing nested AGENTS.md raises a nested-agents-md error.
• Summary responses list authored docs by path; full responses embed them.

Generated artifacts and their discovery order

A package or app can publish its own scoped smrt-knowledge.json. Discovery prefers a local .smrt/smrt-knowledge.json, then dist/smrt-knowledge.json, then source manifest artifacts, before falling back to raw manifest and documentation scanning. The runtime manifest.json stays focused on object registration; smrt-knowledge.json is the artifact intended for developers and agents. doctor's agent-surface report reads this same artifact in this same order, so it names the same missing-build case: run the app build first if it has nothing to report.

Know what the evidence can prove

The index reports declared workspace and installed-package facts. It records the selected source and diagnostics so a coding agent can tell generated evidence from a fallback scan. It does not prove that a deployed process loaded the same artifact. It also does not prove that a caller has authority to use a generated operation.

• Package versions and AGENTS.md hashes identify the installed contract that the index read.
• Coverage and diagnostics identify missing or stale evidence instead of filling gaps with a model answer.
• Only an explicit runtime bridge can report observed process capabilities, and it must label them separately.
• Authentication, tenant scope, permission, and field policy remain runtime decisions.

When output looks stale

Stale output almost always means the artifact behind it is stale or was never built. Run the downstream build or dev server so the domain artifact exists, then re-run the checker. Because the checks are deterministic, the same workspace produces the same result, which makes a changed answer meaningful.

• Run the app build first so .smrt/smrt-knowledge.json exists.
• Re-run smrt knowledge:check --strict after editing package docs.
• A wrong package set usually means the workspace globs resolved from an unexpected source; coverage reports which one.
• Broad or repeated globstars can exhaust the shared directory-entry budget, which fails with a diagnostic instead of returning a partial package set. The limit counts work performed rather than depth, so a deeply nested workspace is still supported.

The same knowledge, two response sizes

CLI callers request the full detail level, so command output embeds authored documents and complete package records. MCP callers receive the budgeted summary by default and can opt into detail full. The underlying knowledge is identical; only the projection differs.