📝 Documentation drift detected — `compile` command's optional path/auto-discovery mode undocumented

[github-actions]

Documentation Freshness Audit

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

Findings

Area	Issue	File(s)
CLI Commands	compile (path) documented with required path, but path is optional; auto-discovery mode is completely undocumented	AGENTS.md, src/main.rs

Details

compile command — optional path / auto-discovery mode

The documentation currently shows:

- `compile (path)` - Compile a markdown file to Azure DevOps pipeline YAML
  - `--output, -o (path)` - Optional output path for generated YAML

This implies (path) is a required argument. However, in src/main.rs the path field is declared as Option(String):

/// Compile markdown to pipeline definition (or recompile all detected pipelines)
Compile {
    /// Path to the input markdown file. If omitted, auto-discovers and
    /// recompiles all existing agentic pipelines in the current directory.
    path: Option(String),
    /// Optional output path for the generated YAML file
    output: Option(String),
},

When path is omitted, the command calls compile::compile_all_pipelines() to auto-discover and recompile all detected agentic pipelines in the current directory. This is a useful batch workflow that is entirely missing from the docs.

The "Common Tasks" example also only shows the single-file form:

cargo run -- compile ./path/to/agent.md

Suggested Fixes

• Update the compile command documentation to show (path) as optional: compile [(path)]
• Update the command description to mention the auto-discovery behavior: "Compile a markdown file to Azure DevOps pipeline YAML. If no path is given, auto-discovers and recompiles all detected agentic pipelines in the current directory."
• Add an example of the no-argument invocation to the "Common Tasks" section:

  # Recompile all agentic pipelines in the current directory
  cargo run -- compile

---

This issue was created by the automated documentation freshness check.

Generated by Documentation Freshness Check · ◷