📝 Documentation drift detected — `run` command undocumented in README, missing from AGENTS.md architecture tree

[github-actions]

Documentation Freshness Audit

The weekly documentation audit found the following inconsistencies between code and documentation:

Findings

Area	Issue	File(s)
CLI Reference	run command absent from CLI reference table	README.md
Architecture tree	src/run.rs not listed in the directory tree	AGENTS.md

Details

1. run command missing from README.md CLI Reference

src/main.rs defines eight subcommands via the Commands enum:
init, compile, check, mcp, mcp-http, execute, configure, run

The README.md CLI Reference block (around line 439) lists only seven — run is absent:

Commands:
  init          Initialize a repository for AI-first agentic pipeline authoring
  compile       Compile markdown to pipeline definition
  check         Verify a compiled pipeline matches its source
  mcp           Run as an MCP server (safe outputs)
  mcp-http      Run as an HTTP MCP server (for MCPG integration)
  execute       Execute safe outputs (Stage 3)
  configure     Detect agentic pipelines and update GITHUB_TOKEN on ADO definitions
  # ← run is missing
```

`AGENTS.md` *does* document the `run` command (lines 1007–1013) with full flag details — so the fix is to add a matching entry to `README.md`.

The `run` command is the primary local development tool (starts SafeOutputs + MCPG, runs copilot, executes safe outputs end-to-end), so its omission from the user-facing README is a meaningful gap.

#### 2. `src/run.rs` missing from `AGENTS.md` architecture tree

The architecture tree in `AGENTS.md` (lines 20–84) lists all source files but omits `src/run.rs`, which implements the `run` subcommand. All other top-level `src/*.rs` files are listed.

Actual top-level source files include:
```
src/agent_stats.rs  ✅ listed
src/allowed_hosts.rs  ✅ listed
src/configure.rs  ✅ listed
src/detect.rs  ✅ listed
src/ecosystem_domains.rs  ✅ listed
src/execute.rs  ✅ listed
src/fuzzy_schedule.rs  ✅ listed
src/init.rs  ✅ listed
src/logging.rs  ✅ listed
src/main.rs  ✅ listed
src/mcp.rs  ✅ listed
src/ndjson.rs  ✅ listed
src/run.rs  ❌ MISSING
src/sanitize.rs  ✅ listed

Suggested Fixes

• Add run entry to the README.md CLI Reference block with its flags (--pat, --org, --project, --dry-run, --skip-mcpg, --output-dir)
• Add src/run.rs to the architecture tree in AGENTS.md with a brief description (e.g., # Local development run orchestrator)

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ● 2M · ◷