rgctl documentation

Agent-first docs: index once, query with -f json, deepen in the User Guide when a human needs the full walkthrough.

Feature guides (docs/guides/ historically) now live in rgctl-website (docs/guides/) and are published at shaaf.dev/rgctl/docs/guides/. This repo keeps a pointer stub.

Primary (start here)

Goal	Canon
Install rgctl + choose operating mode	Installation
Step-by-step feature how-tos (CoolStore)	Guides
Full CLI taxonomy (canonical vs aliases)	CLI command reference
Per-language AST coverage (website from JSON)	Languages · `*-ast-coverage.json`
Contribute to rgctl (agent README)	AGENTS.md — rules, cold profiles, tests/benches
Use rgctl with LLM IDEs	Agent pack · USER_AGENTS_TEMPLATE
JSON shapes (`schema_version`, fields)	JSON API
CLI walkthrough (ecommerce-java)	User Guide
Concepts (what / why)	Introduction

Use rgctl (consumer agent loop): install the agent pack (--skill) → discover once → find / callers / blast-radius / cpg with -f json (agent-skill).
Contribute to this repo: AGENTS.md.
First hour (human): Install → User Guide §1–4 on ecommerce-java, then a Guide for the feature you need.
Latest release: v0.4.21 release notes.

Upgrading from v0.4.9: no breaking changes — PHP is additive (discover -l php). Ruby is additive (discover -l ruby).

Upgrading from v0.4.8: v0.4.9 release notes (daemon/MCP removed; Kantra; in-repo .rgctl/ only).

Secondary

Goal	Doc
Supported languages	Languages (SSOT: coverage JSON)
Dependency Injection & Frameworks	Dependency Injection and Frameworks — routes (`ExposesRoute`), DI (`Injects`), reflection, semantic tags, and `frameworks.bin`
Markdown / doc context graph	Guide (step-by-step) — `.md` / `.mdx`, structured queries, Obsidian export, doc semantic index
HTTP server + dashboard	HTTP Server and Dashboard
CI blast-radius policy	Policy format
Monolith migration (how-to)	Migration planning
Research map	Further reading

Optional browser UI (nice-to-have, not required for agents): HTTP server and dashboard after discover --with-dashboard.

For contributors

Internals and contribution bars — not the default agent reading path.

Document	Topic
Contributor checklist	End-to-end workflow: add language, update feature, tests, PR
Language testing guide	Where to add language tests, what to assert, Tier 1 matrix
Feature designs	Per-capability engineering notes
Tier 1 language support	Layer A–F bar for Tier 1 languages
Code structure	Crate layout
Analysis architecture	CFG / PDG / taint
Graph storage architecture	Snapshots, blast cache
Integration test matrix	Tier A/B/C — in-repo artifacts, HTTP serve, CLI subprocess · golden CLI: `tests/cli_output/`
HTTP server and dashboard	Serve / dashboard UI
Migration planner design · Migration algorithms	Migration internals
Releasing	Versioned binaries
CONTRIBUTING.md	Dev setup

Terminology

Term	Meaning
Tier-1 deep-analysis languages	Custom plugins with `*-ast-coverage.json` + CFG/PDG (single-pass `ScopeStack` + `KindDispatchTable`); distinct from the ~60 language/config plugins in `languages.toml`
Default graph artifact	`.rgctl/graph.snapshot.bin` (`RGCL` v2 columnar mmap); `graph.db` / `graph.json` only with `--write-json-graph`
`--with-cfg`	Whole-repo CFG/PDG archive (needed for `taint --sink`, `cpg mutations`); `slice` / `cpg flows` lazy-build one function without it
Communities	Fast-Leiden (local moving + BFS refinement + coarsening) with $\mu+4\sigma$ `HubStripPolicy`; JSON field `louvain_community_id` is historical schema name only
Canonical query / policy CLI	`find` / `callers` / `callees` / `relations` / `inventory`; `review check` (`query` / `pr-check` are compatibility aliases)
Dashboard / migration JSON	Opt-in (`--with-dashboard` / `--export-migration-hints`)
First-hour fixture	In-tree ecommerce-java

Redirects (historical names)

cli-getting-started.md → Installation / User Guide
cli-output-schemas.md → JSON API
LANGUAGE_GUIDE.md → languages/README.md

Docs match the CLI in this repository — verify with rgctl --version.

Maintainer scratch: internal/ (not public).