Getting started with ctxgrd

Lint your first structured-markdown record – an ADR, PRD, runbook, or any .md file with <NAMESPACE>-<number> frontmatter – in under five minutes.

Prerequisites

  • A repository with at least one markdown document you want to keep well-formed.
  • The ctxgrd binary on your PATH. Build it with cargo install --path . from a clone, or cargo build --release and copy target/release/ctxgrd.

Create a config

ctxgrd does nothing until a namespace claims a file. The fastest way to a working config is to apply a built-in pack:

ctxgrd pack add project-docs

This appends [ADR], [PRD], [ROADMAP], [RFC], [BUG], [TODO], and [README] blocks to ctxgrd.toml, each with sensible rules and required headings. To see what a pack writes before committing to it:

ctxgrd pack show project-docs    # the namespaces, rules, and shape it defines
ctxgrd pack add project-docs --dry-run    # print the blocks, touch nothing

To start from another domain instead of the software defaults, install the domain’s packs with ctxgrd pack install <path|git-url>, then run ctxgrd init --domain <name>. It applies every discovered pack that declares that domain. The default is software. A domain no pack declares exits 2 with init.domain.

Run the linter

ctxgrd            # lint the working tree, human-readable output
ctxgrd --format json | jq '.diagnostics[]'    # machine-readable, one diagnostic per object

--format json prints one JSON object. The findings are in its diagnostics array.

In a new repository, the first run after pack add project-docs reports errors like these:

error[core.min-docs]: namespace `PRD` requires at least one document but the run found none
  --> ctxgrd.toml

error[core.min-docs]: namespace `README` requires at least one document but the run found none
  --> ctxgrd.toml

error[core.min-docs]: namespace `ROADMAP` requires at least one document but the run found none
  --> ctxgrd.toml

The pack requires at least one PRD, one README and one ROADMAP initiative (ADR gets a warning). Clear them by writing those documents:

ctxgrd new PRD "First product requirement"
ctxgrd new ROADMAP "Now"

Create a README.md. The scaffolded files start with empty status, date and owner fields, and the linter reports each one until you fill it in. If you do not want a document type, open ctxgrd.toml and remove core.min-docs from that namespace’s rules.

The exit code tells an agent or CI how the run went without parsing text:

  • 0 – clean.
  • 1 – diagnostics were reported.
  • 2 – a kernel or config error (bad ctxgrd.toml, unreadable file).

Write a guide of your own

End-user documentation has its own pack. Apply it and drop a guide under docs/guides/:

ctxgrd pack add guide

Each guide carries a title and a diataxis.type from the Diátaxis taxonomy (tutorial, how-to, reference, explanation). The field is nested under diataxis rather than a top-level type, which static site generators reserve for their own use. The README links the entry guide so readers can find it.

Troubleshooting

cfg.rule-unknown: <rule> – the installed binary predates a rule in your config. Reinstall ctxgrd so the binary matches the config, or remove the rule.

No diagnostics and no files checked – no namespace claims your files. Add a paths glob to the namespace, or give the file an id: <NS>-<number>. A file that claims neither is silently skipped by design.

Next steps