majordomus_cli/

cli.rs

//! The command line, declared with clap's derive API. Every command starts from the same
//! [`RepoArgs`]; `capabilities` reaches the registry through the registry's own
//! introspection capabilities, so no list of capabilities lives here.

use std::path::PathBuf;

use clap::{Args, Parser, Subcommand, ValueEnum};

use crate::capability::builtin::Checkouts;

/// The exit code for a usage error, per the exit-code contract.
pub const EXIT_USAGE: u8 = 2;

#[derive(Debug, Parser)]
#[command(
    name = "majordomus",
    version,
    about = "Majordomus control plane: a data-driven MCP server over the repository's .ai/ layer",
    long_about = "The Rust executable of Majordomus. It reads the repository's provider-neutral \
AI layer under .ai/ and serves it to MCP clients over stdio. Almost every capability is a \
query; the few that change anything declare themselves as commands and are listed by \
`capabilities list --kind command`.\n\n\
Most of the task lifecycle (init, start, check, finish, doctor, ...) is the shell tool \
bin/majordomus in the same repository. Development semantics are converging onto capabilities \
of this registry one at a time (ADR 0040); until one has, this executable does not implement \
that command."
)]
/// The command line: one of the commands below.
pub struct Cli {
    #[command(subcommand)]
    /// The command to run.
    pub command: Command,
}

#[derive(Debug, Subcommand)]
/// The commands. A command listed here is implemented; nothing is advertised ahead of its behaviour.
pub enum Command {
    /// Serve the repository's AI layer to an MCP client over stdio
    Mcp(McpArgs),
    /// Serve the same capabilities over HTTP on the loopback interface, with the home page, /openapi.json, /swagger and the documentation under /docs/
    Serve(ServeArgs),
    /// Introspect the capability registry: what exists, where it came from, how it is exposed
    Capabilities(CapabilitiesArgs),
    /// Write the committed projections of the registry (docs/generated), or check that they are current
    Generate(GenerateArgs),
    /// Time every externally callable operation (each capability directly, over MCP and over HTTP, and the transports' own operations), report coverage, compare with the accepted baseline
    Bench(BenchArgs),
    /// The repository scope: what a worker reads and what it never reads; with paths, whether each is in or out and why
    Scope(ScopeArgs),
    /// The repository's web surfaces: what is exposed, where it is mounted, what produced it, and whether the topology is valid
    Web(WebArgs),
    /// The operational moments this tool answers: the catalogue, one moment, the audiences and areas, a diagnosis of your own week, and the catalogue's own validation
    Why(WhyArgs),
    /// One issue or one milestone as an executable development scope: what was authored, where the plan graph puts it, what happened to it, whether a worker may start it — with the origin of every value on the value
    Devtask(DevtaskArgs),
    /// How this project is packaged, published and installed: the platforms, the artifact names, the installer, the releases
    Distribution(DistributionArgs),
    /// What this checkout is: the project, version control, the toolchains it declares, what the layer holds, the workflows, the provider projections and the local services
    Env(EnvArgs),
    /// Every command this repository offers, from whichever program offers it: the graph, one command, where each one is projected, and the workflow bridge derived from it
    Commands(CommandsArgs),
    /// Completion for any surface, answered from the command graph: the candidates a shell asks for, and the one-time integration that asks
    Completion(CompletionArgs),
    /// The branch-to-worktree topology: where every linked worktree belongs (`<repo>-wt/<branch>`), where each one is, and the lifecycle — create, migrate, repair, guard
    #[command(alias = "wt")]
    Worktree(WorktreeArgs),
    /// Pull-request integration: every open pull request classified against the current master with its evidence, the ranked plan, and the executor that merges the next provably safe one — one at a time, re-planning after each (ADR 0101)
    #[command(alias = "pr")]
    Prs(PrsArgs),
    /// A branch's derive run on another machine the repository declares (.ai/repo/offload/), in that machine's turn: the hosts and their limits, a probe that names the host a derive would take, and the derive itself — bundle in, a FIFO queue on the host, a build directory of its own, bundle back, staged and never committed
    Offload(OffloadArgs),
    /// Is any of this repository's work held where it can be lost? Every holding — a work tree with uncommitted files, a branch with commits, a stash — with the disposition read from git, and one verdict over them
    Convergence(ConvergenceArgs),
    /// The commit as a value: what the working tree would commit and how it divides, the scope vocabulary this repository's history yields, and the verdict on one message against the commit policy
    Commit(CommitArgs),
    /// The product: what this repository's tool does for a person, as the features under the layer declare it, with every surface, count and moment derived; the matrix of features against interfaces; the providers; and the model's own validation
    Product(ProductArgs),
    /// What this project has shipped and what it would ship next: the changelog derived from the layer's own records, the version authored in one place and projected for the shell tool, and the one command that raises it
    Release(ReleaseArgs),
    /// What this executable's own public surface is held to: documentation, executable examples, module coverage, and every command accounted for against the capability registry
    Quality(QualityArgs),
    /// Run a capability as an execution and follow it: its steps, its progress and its output as they happen
    Run(RunArgs),
    /// The executions of the server serving this repository: what has run, what is running, and what each one said
    Executions(ExecutionsArgs),
    /// The context a development session should be given, compiled from the repository: for an issue, a milestone, an intent or a set of paths, what is selected and why, what was left out and why, what collapsed into what, and the budget
    Devcontext(DevcontextArgs),
    /// The edit guard: whether a provider's tool may write a file of this checkout now, judged from the active task's scope and the writing session's live mesh claims
    Guard(GuardArgs),
    /// The mesh: the nodes this repository's running server has discovered on the network, this machine's node identity, and the self-check that proves the prerequisites on this machine alone
    Mesh(MeshArgs),
    /// Everything that happens around this repository, followed in one stream: mesh sessions, claims, handovers and reviews on every linked machine, the executor's merges and failures, and GitHub's pull requests and runs, with what is addressed to you marked
    Monitor(MonitorArgs),
    /// The model catalogue the distribution declares, and the explainable routing over it: vendors, canonical model references, typed capabilities, and which model a stated need selects — with why, for every candidate
    Models(ModelsArgs),
    /// Provider-independent reasoning: the optional advisors and what they can do now, what an uncertainty calls for, the session's reasoning records, their state and provenance, and the checks that keep reasoning independent of any advisor
    Reasoning(ReasoningArgs),
    /// What actually ran and what it proves: every claim of the matrix against the runs recorded for it, one claim's proof, one test's claims, and the recording of a run that happened
    Evidence(EvidenceArgs),
    /// Whether a deployment serves the commit it was meant to: observe the build identity it serves, judged by commit containment, and read each deployment's recorded standing against a commit
    Served(ServedArgs),
    /// Every rule against the proof there is for it: what each one names, whether it is in the tree, whether a runner drives it, whether anything ran, and whether what ran is older than what it is about
    Rules(RulesArgs),
    /// What must become true above the milestones: every intent with its stage derived from the plan and its satisfaction from the recorded evidence, one intent, the model's own validation, and which intent a piece of work serves
    Intent(IntentArgs),
    /// Whether each product feature exists: on master, deployed, publicly verified, tested, its evidence published and linked — every dimension computed, unknown never a pass
    Delivery(DeliveryArgs),
    /// Token economics, measured: matched runs with and without Majordomus, every metric with its measurement class and sample size, the statement the evidence allows, and the check that refuses an unsupported savings claim
    Economics(EconomicsArgs),
    /// Every object of the layer as an addressable node: the kinds and their routes, and one entity with its references, its backlinks, the surfaces that answer for it and the state of what it names
    Entity(EntityArgs),
    /// The repository's shell automation against the tracked migration inventory: every shell unit declared with an exemption, and every exemption naming a unit the tree still has
    Shell(ShellArgs),
    /// The tracked tree as token-bounded text shards for a language model's file search: plan what a profile carries and leaves out, build it under tmp/packs/, and verify a written pack against its manifest; never a binary, a worktree, a link or build output
    Pack(PackArgs),
    /// The Dashboard Suite: each page a projection of the capabilities that hold its facts, every card carrying its source capability, the JSON pointer its value was read from, the Cockpit page with the evidence and the command that acts on it
    Dashboard(DashboardArgs),
    /// What surrounds this session, in one line and in a few: its episode and task, the peers of every board, the mesh, the integration queue and the derive queue, asked of the server holding this checkout's lease
    Brief(BriefArgs),
    /// Every skill as a proven capability: the tests that name it and the evidence behind them, its page, the doctrine and gates that hold it, what invokes it, and the orphans
    Skills(SkillsArgs),
    /// What the knowledge deriver left for review and whether it is still writing: the candidate records awaiting promotion, one record by id with every reference it names resolved, and the derivation status of this checkout judged against the policy's freshness thresholds
    Knowledge(KnowledgeArgs),
    /// Continue work on another machine: publish this checkout's newest handover as a signed record in refs/majordomus/continuity, exchange records with a git remote, and plan and resume a handover another device published — with its source compatibility, lineage and trust decided before anything is written
    Continuity(ContinuityArgs),
}

#[derive(Debug, Args)]
/// `majordomus intent`. The output shape is global, so it reads where a person writes it.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, IntentArgs, IntentCommand};
///
/// let cli = Cli::try_parse_from(["majordomus", "intent", "preflight", "--issue", "I0001"]).unwrap();
/// let Command::Intent(args) = cli.command else { panic!("intent") };
/// let args: IntentArgs = args;
/// assert!(matches!(args.command, IntentCommand::Preflight { issue: Some(_), .. }));
/// // the group runs nothing of its own: every runnable path here is a capability's
/// assert!(Cli::try_parse_from(["majordomus", "intent"]).is_err());
/// ```
pub struct IntentArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `list`, `show`, `validate`, `coverage`, `preflight`, `binding`, `realization`,
    /// `explain` or `propose`.
    pub command: IntentCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus intent`: the command line of `intents.list`,
/// `intents.record`, `intents.validate` and `intents.preflight`.
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, IntentCommand};
/// use clap::Parser;
/// let cli = Cli::parse_from(["majordomus", "intent", "show", "intent-lifecycle"]);
/// let Command::Intent(args) = cli.command else { panic!("intent") };
/// let IntentCommand::Show { id } = args.command else { panic!("show") };
/// assert_eq!(id, "intent-lifecycle");
/// ```
pub enum IntentCommand {
    /// Every intent, with the stage derived from its milestones and its evidence
    List,
    /// One intent in full: each milestone's derived status and each criterion's evidence state
    Show {
        /// The intent's id, which is also its file name
        id: String,
    },
    /// Every finding over the intents; exit 10 when any is a failure
    Validate,
    /// Which work carries which criterion, and the reason every issue exists
    Coverage,
    /// Which intent the work on an issue, or on some paths, serves, whether it is maintenance,
    /// or why it may not proceed; exit 10 when refused
    Preflight {
        /// The issue the work executes
        #[arg(long)]
        issue: Option<String>,
        /// A path the work will touch; repeat for each
        #[arg(long = "path")]
        paths: Vec<String>,
    },
    /// What a piece of work is bound to before it starts: the issue, the intent or the
    /// paths it names resolved to the criteria it serves, or an exemption the policy
    /// declares, with the two pins a resumed worker compares; exit 10 when refused
    Binding {
        /// The issue the work executes
        #[arg(long)]
        issue: Option<String>,
        /// The intent the work serves, named directly
        #[arg(long)]
        intent: Option<String>,
        /// A path the work will touch; repeat for each
        #[arg(long = "path")]
        paths: Vec<String>,
        /// An exemption class the policy declares under intent.exemptions
        #[arg(long)]
        exempt: Option<String>,
        /// Why the exemption applies
        #[arg(long)]
        because: Option<String>,
    },
    /// Which work realises which intent — tasks, episodes, providers, handovers, peer claims —
    /// each link with its provenance, and each intent's unmet criteria and drift; exit 10 when
    /// an intent whose milestones are all DONE is contradicted by its evidence
    Realization {
        /// Only this intent and the work linked to it
        #[arg(long)]
        intent: Option<String>,
    },
    /// Why an intent stands where it stands: its stage, each criterion, the work realising it
    Explain {
        /// The intent's id
        id: String,
    },
    /// Write a new, unplanned intent: what must become true (ADR 0144)
    Propose {
        /// What must become true, kept verbatim
        #[arg(long)]
        statement: String,
        /// One line naming it; the statement's first line when absent
        #[arg(long)]
        title: Option<String>,
        /// The identity and file name; the title's slug when absent
        #[arg(long)]
        id: Option<String>,
    },
}

#[derive(Debug, Args)]
/// `majordomus dashboard`. Every subcommand is one page of the Dashboard Suite, run through
/// the capability that answers it.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, DashboardArgs, DashboardCommand, OutputFormat};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "dashboard", "overview", "--format", "json"]).unwrap();
/// let Command::Dashboard(args) = cli.command else { panic!("not the dashboard command") };
/// let args: DashboardArgs = args;
/// assert!(matches!(args.command, DashboardCommand::Overview));
/// assert!(matches!(args.format, OutputFormat::Json));
/// ```
pub struct DashboardArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `overview`. Required: the group runs nothing of its own.
    pub command: DashboardCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Args)]
/// `majordomus brief`: the `brief.session` capability on the command line (ADR 0136).
/// # Example
///
/// ```
/// use majordomus_cli::cli::{BriefArgs, Cli, Command, OutputFormat};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "brief", "--line", "--session", "abc"]).unwrap();
/// let Command::Brief(args) = cli.command else { panic!("not the brief command") };
/// let args: BriefArgs = args;
/// assert!(args.line && !args.keep_awake && !args.this_checkout);
/// assert_eq!(args.session.as_deref(), Some("abc"));
/// assert!(matches!(args.format, OutputFormat::Text));
/// ```
pub struct BriefArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[arg(long)]
    /// Print the one-line brief alone: the status line's text
    pub line: bool,

    #[arg(long)]
    /// Print what a session is told at its start about keeping itself awake, then the one-line brief
    pub keep_awake: bool,

    #[arg(long, value_name = "ID")]
    /// The provider's own session identity: the brief names the open episode it owns
    pub session: Option<String>,

    #[arg(long = "this-checkout")]
    /// Read this checkout's board alone instead of every checkout's
    pub this_checkout: bool,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus dashboard`: one per page of the suite.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, DashboardCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "dashboard", "overview"]).unwrap();
/// let Command::Dashboard(args) = cli.command else { panic!("not the dashboard command") };
/// assert!(matches!(args.command, DashboardCommand::Overview));
/// ```
pub enum DashboardCommand {
    /// Is it healthy, what changed, what is broken, what needs action: every card with its value, the source's verdict, and the capability and pointer it was read from; exit 10 when the overview is fail or unknown
    Overview,
}

#[derive(Debug, Args)]
/// `majordomus pack`. The output shape is global, so it reads where a person writes it.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, PackArgs, PackCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "pack", "plan", "chatgpt"]).unwrap();
/// let Command::Pack(args) = cli.command else { panic!("not the pack command") };
/// let args: PackArgs = args;
/// assert!(matches!(args.command, PackCommand::Plan { profile: Some(_) }));
/// ```
pub struct PackArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `plan`, `build` or `verify`. Required: the group runs nothing of its own.
    pub command: PackCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus pack`: `plan` is the verdict before anything is written,
/// `build` writes the pack and verifies what it wrote, and `verify` reads a written pack.
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, PackCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "pack", "build", "--out", "tmp/p", "--force"]).unwrap();
/// let Command::Pack(args) = cli.command else { panic!("not the pack command") };
/// assert!(matches!(args.command, PackCommand::Build { force: true, .. }));
/// ```
pub enum PackCommand {
    /// What a profile would pack: files carried, files left out by reason, the shards and every finding that refuses the build; exit 10 on a finding, 12 when the tree cannot be read
    Plan {
        /// A profile of share/archive.yaml (default: its `default`)
        profile: Option<String>,
    },
    /// Write the pack (index, shards, pack.json) and verify what was written; exit 10 when the plan or the written pack has a finding, and nothing is built from a plan with one
    Build {
        /// A profile of share/archive.yaml (default: its `default`)
        profile: Option<String>,
        /// Write here instead of `tmp/packs/<repo>-<profile>-<commit>`
        #[arg(long, value_name = "DIR")]
        out: Option<PathBuf>,
        /// Replace a pack already at the destination (never a directory that is not a pack)
        #[arg(long)]
        force: bool,
    },
    /// Verify a written pack against its manifest and the profile it names; exit 10 on a finding, 12 when the manifest cannot be read
    Verify {
        /// The pack's directory, inside the repository
        dir: String,
    },
}

#[derive(Debug, Args)]
/// `majordomus shell`. The output shape is global, so it reads the way a person writes it.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, OutputFormat, ShellArgs};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "shell", "check", "--format", "json"]).unwrap();
/// let Command::Shell(args) = cli.command else { panic!("not the shell command") };
/// let args: ShellArgs = args;
/// assert!(matches!(args.format, OutputFormat::Json));
/// ```
pub struct ShellArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `check`. Required: the group runs nothing of its own.
    pub command: ShellCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus shell`: `check` measures the repository's shell units
/// against the automation inventory, and `--canonical` puts the inventory's records back
/// in canonical order before it measures.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, ShellCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "shell", "check", "--canonical"]).unwrap();
/// let Command::Shell(args) = cli.command else { panic!("not the shell command") };
/// assert!(matches!(args.command, ShellCommand::Check { canonical: true }));
/// ```
pub enum ShellCommand {
    /// Refuse every shell unit the inventory does not declare, and every declaration whose unit is gone; exit 10 on a finding, 12 when the tree cannot be measured
    Check {
        /// Rewrite .ai/repo/automation/inventory.jsonl with its records in canonical order, then check
        #[arg(long)]
        canonical: bool,
    },
}

#[derive(Debug, Args)]
/// `majordomus skills`. The output shape is global, so it reads where a person writes it.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, OutputFormat, SkillsArgs, SkillsCommand};
///
/// let cli = Cli::try_parse_from(["majordomus", "skills", "explain", "implement"]).unwrap();
/// let Command::Skills(args) = cli.command else { panic!("skills") };
/// let args: SkillsArgs = args;
/// assert!(matches!(args.command, SkillsCommand::Explain { .. }));
/// assert_eq!(args.format, OutputFormat::Text, "text unless a person asks for json");
/// // `--format` is global, so it is read after the subcommand as well as before it
/// let cli = Cli::try_parse_from(["majordomus", "skills", "status", "--format", "json"]).unwrap();
/// let Command::Skills(SkillsArgs { format, .. }) = cli.command else { panic!("skills") };
/// assert_eq!(format, OutputFormat::Json);
/// // the group runs nothing of its own: every runnable path here is a capability's
/// assert!(Cli::try_parse_from(["majordomus", "skills"]).is_err());
/// ```
pub struct SkillsArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `status`, `explain` or `verify`.
    pub command: SkillsCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus skills`: the command line of `skills.status`,
/// `skills.explain` and `skills.verify`.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, SkillsCommand};
/// let cli = Cli::parse_from(["majordomus", "skills", "verify"]);
/// let Command::Skills(args) = cli.command else { panic!("skills") };
/// assert!(matches!(args.command, SkillsCommand::Verify));
/// ```
pub enum SkillsCommand {
    /// Every skill with its derived standing: tested, documented, enforced, used
    Status,
    /// One skill in full: each naming test and its evidence, its page, its gates, every invocation
    Explain {
        /// The skill's id, which is also its directory name
        id: String,
    },
    /// Every finding over the skills; exit 10 when any is a failure
    Verify,
}

#[derive(Debug, Args)]
/// `majordomus models`.
pub struct ModelsArgs {
    #[command(subcommand)]
    /// `list`, `route`.
    pub command: ModelsCommand,
}

#[derive(Debug, Subcommand)]
/// The `models` subcommands.
pub enum ModelsCommand {
    /// Every declared vendor and model, optionally narrowed; the order is the declaration's, which is routing's preference order
    List(ModelsListArgs),
    /// Which model a stated need selects, the fallback chain behind it, and why every excluded model fell out
    Route(ModelsRouteArgs),
}

#[derive(Debug, Args)]
/// `majordomus reasoning`: the command-line projection of the `reasoning` capabilities.
/// The repository arguments and the output shape are shared by every subcommand, and the
/// shape is global, so `--format` reads the same before or after the subcommand.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, OutputFormat, ReasoningArgs, ReasoningCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "reasoning", "plan", "--materiality", "high", "--format", "json"]).unwrap();
/// let Command::Reasoning(args) = cli.command else { panic!("not the reasoning command") };
/// let args: ReasoningArgs = args;
/// assert!(matches!(args.command, ReasoningCommand::Plan { .. }));
/// assert!(matches!(args.format, OutputFormat::Json));
/// ```
pub struct ReasoningArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `advisors`, `plan`, `record`, `status`, `explain`, `check`.
    pub command: ReasoningCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// `text` for a person, `json` for a machine; both render the same answer.
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The `reasoning` subcommands, one per capability: `advisors`, `plan` and `status` read,
/// `explain` traces one record, `check` gates, and `record` is the one that writes.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, ReasoningCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "reasoning", "plan"]).unwrap();
/// let Command::Reasoning(args) = cli.command else { panic!("not the reasoning command") };
/// let ReasoningCommand::Plan { materiality, confidence, capabilities } = args.command else {
///     panic!("not plan")
/// };
/// assert_eq!((materiality.as_str(), confidence.as_str()), ("material", "medium"));
/// assert!(capabilities.is_none());
/// let cli = Cli::try_parse_from(["majordomus", "reasoning", "status", "--task", "all", "--report"]).unwrap();
/// let Command::Reasoning(args) = cli.command else { panic!("not the reasoning command") };
/// assert!(matches!(args.command, ReasoningCommand::Status { report: true, .. }));
/// ```
pub enum ReasoningCommand {
    /// Every advisor with its status and why, the mode in force, and who can provide each advisory capability now; no advisor at all is an ordinary answer
    Advisors,
    /// Whether a stated uncertainty warrants independent review, how much, and from which available advisors — with every advisor left out and why; records nothing
    Plan {
        /// trivial, low, material, high or critical
        #[arg(long, default_value = "material")]
        materiality: String,
        /// low, medium or high
        #[arg(long, default_value = "medium")]
        confidence: String,
        /// Advisory capabilities review needs, comma-separated
        #[arg(long)]
        capabilities: Option<String>,
    },
    /// Record one reasoning step of the open task from JSON (`{"kind":"assessment",...}`) read from --file or standard input; a record that breaks a rule is refused and nothing is written
    Record {
        /// The JSON record; standard input when absent
        #[arg(long)]
        file: Option<std::path::PathBuf>,
    },
    /// The reasoning state of the open task — assessments, consultations, disagreements, conclusions, the timeline — and the report a handover carries
    Status {
        /// A task id, or `all`
        #[arg(long)]
        task: Option<String>,
        /// Print only the Markdown report (empty when there is nothing to report)
        #[arg(long)]
        report: bool,
    },
    /// One record with the whole chain of its assessment: why a decision was made
    Explain {
        /// The record id
        id: String,
    },
    /// Check that reasoning stays provider-independent and that every record is consistent; exit 10 on a finding
    Check,
}

#[derive(Debug, Args)]
/// `majordomus models list`.
pub struct ModelsListArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[arg(long)]
    /// Only this vendor.
    pub vendor: Option<String>,

    #[arg(long)]
    /// Only models declaring this capability word.
    pub capability: Option<String>,

    #[arg(long)]
    /// One model, by canonical id or alias.
    pub id: Option<String>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// `text` for a person, `json` for a machine; both render the same answer.
    pub format: OutputFormat,
}

#[derive(Debug, Args)]
/// `majordomus models route`.
pub struct ModelsRouteArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[arg(long)]
    /// Capability words the model must declare, comma-separated: `vision,tools`.
    pub require: Option<String>,

    #[arg(long)]
    /// The least context window, tokens.
    pub min_context: Option<u64>,

    #[arg(long)]
    /// Only this vendor.
    pub vendor: Option<String>,

    #[arg(long)]
    /// Only local inference.
    pub local_only: bool,

    #[arg(long)]
    /// A model named outright, by canonical id or alias; still checked against the other requirements.
    pub model: Option<String>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// `text` for a person, `json` for a machine; both render the same answer.
    pub format: OutputFormat,
}

#[derive(Debug, Args)]
/// `majordomus guard`: the edit guard (I2735).
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, GuardArgs, GuardCommand};
/// use clap::Parser;
///
/// let cli = Cli::try_parse_from(["majordomus", "guard", "hook", "--provider", "claude-code"]).unwrap();
/// let Command::Guard(guard) = cli.command else { panic!("expected `guard`") };
/// let GuardArgs { command: GuardCommand::Hook(hook) } = guard;
/// assert_eq!(hook.provider, "claude-code");
///
/// // the group has no behaviour of its own
/// assert!(Cli::try_parse_from(["majordomus", "guard"]).is_err());
/// ```
pub struct GuardArgs {
    #[command(subcommand)]
    /// `hook`.
    pub command: GuardCommand,
}

#[derive(Debug, Subcommand)]
/// The `guard` subcommands: one today, `hook`, which a provider's pre-tool hook runs before
/// every write; an unknown subcommand is refused rather than read as a path.
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, GuardCommand};
/// use clap::Parser;
///
/// let cli = Cli::try_parse_from(["majordomus", "guard", "hook"]).unwrap();
/// let Command::Guard(guard) = cli.command else { panic!("expected `guard`") };
/// assert!(matches!(guard.command, GuardCommand::Hook(_)));
/// assert!(Cli::try_parse_from(["majordomus", "guard", "docs/a.md"]).is_err());
/// ```
pub enum GuardCommand {
    /// Judge the edit a provider's pre-tool payload (on stdin) is about to make; exit 2 with the reason and the remedy when no claim covers it, 0 otherwise
    Hook(GuardHookArgs),
}

#[derive(Debug, Args)]
/// `guard hook`: the provider whose payload stdin carries, and the repository.
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, GuardCommand, GuardHookArgs};
/// use clap::Parser;
///
/// let cli = Cli::try_parse_from(["majordomus", "guard", "hook"]).unwrap();
/// let Command::Guard(guard) = cli.command else { panic!("expected `guard`") };
/// let GuardCommand::Hook(GuardHookArgs { provider, repo }) = guard.command;
/// assert_eq!(provider, "claude-code", "the provider whose payload shape is known");
/// assert_eq!(repo, None);
/// ```
pub struct GuardHookArgs {
    /// The provider whose payload stdin carries; its session id on the mesh is `<provider>-<session_id>`
    #[arg(long, default_value = "claude-code")]
    pub provider: String,
    /// Where a relative path in the payload is resolved from (default: the current directory); the checkout judged is the one the written file belongs to
    #[arg(long, value_name = "PATH")]
    pub repo: Option<PathBuf>,
}

#[derive(Debug, Args)]
/// `majordomus mesh`.
pub struct MeshArgs {
    #[command(subcommand)]
    /// `status`, `nodes`, `identity`, `doctor`.
    pub command: MeshCommand,
}

#[derive(Debug, Subcommand)]
/// The `mesh` subcommands.
pub enum MeshCommand {
    /// Whether the mesh runs in this checkout's server and why not when it does not, with every provider's state and the registry's tallies
    Status(MeshQueryArgs),
    /// Every node the running server has observed, deduplicated by node identity, with trust, presence, endpoints and provenance
    Nodes(MeshQueryArgs),
    /// This machine's node identity, public half only; absent is an answer, not an error
    Identity(MeshQueryArgs),
    /// Prove the mesh prerequisites on this machine alone: declaration, identity, sockets, multicast, broadcast, the protocol end to end, and the host firewall
    Doctor(MeshQueryArgs),
    /// What the host firewall must admit for the declared mesh and whether it does; `apply` admits it, as root
    Firewall(MeshFirewallArgs),
    /// Every machine and runtime this checkout's server cooperates with, each link's state, and the active sessions; --full for every session and claim
    Peers(MeshViewArgs),
    /// One runtime: its machine, liveness, link, sessions and claims; exits 10 when it is not known here
    Peer(MeshPeerArgs),
    /// The state every linked runtime converges on, summarised with its digest; --full for every session, claim, handover and review
    State(MeshViewArgs),
    /// The cooperation journal's events after a Lamport stamp, in Lamport order
    Events(MeshEventsArgs),
    /// Prove cooperation now: local health, a live round with every peer this server dials, and convergence; exits 10 when a check fails
    Verify(MeshQueryArgs),
    /// Claim repository paths for a session; exits 10 naming the claims it meets when an exclusive claim on any linked runtime holds them
    Claim(MeshClaimArgs),
    /// Release a claim this server's current run holds
    Release(MeshReleaseArgs),
    /// Open, update or close a session on the mesh
    Session(MeshSessionArgs),
    /// Publish a handover of this checkout to the mesh, or consume one another runtime published
    Handover(MeshHandoverArgs),
    /// Ask the mesh for a review, or answer a request
    Review(MeshReviewArgs),
}

#[derive(Debug, Args)]
/// `mesh firewall`: the inbound admissions the declared mesh needs on this host, which
/// firewall the host runs, the commands that admit them, and the firewall's own word —
/// a report, exit 10 when the host does not admit the mesh. `mesh firewall apply` runs
/// those commands, and needs root. `--port` names the port this checkout's server listens
/// on beyond loopback, when it does, because a peer dials it there.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshFirewallArgs, MeshFirewallCommand};
///
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "firewall", "--port", "8741"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Firewall(firewall) = mesh.command else { panic!("expected `firewall`") };
/// let firewall: MeshFirewallArgs = firewall;
/// assert_eq!(firewall.port, Some(8741));
/// assert!(firewall.command.is_none());
///
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "firewall", "apply", "--port", "8791"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Firewall(firewall) = mesh.command else { panic!("expected `firewall`") };
/// let Some(MeshFirewallCommand::Apply(apply)) = firewall.command else { panic!("expected `apply`") };
/// assert_eq!(apply.port, Some(8791));
/// ```
pub struct MeshFirewallArgs {
    #[command(subcommand)]
    /// `apply`, or nothing for the report.
    pub command: Option<MeshFirewallCommand>,
    #[arg(long)]
    /// The port this checkout's server listens on beyond loopback, when it does
    pub port: Option<u16>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Subcommand)]
/// The `mesh firewall` subcommands: only `apply`, because the report is the command
/// itself with nothing after it. `apply` is the one mesh operation offered on the command
/// line alone — it runs a privileged host tool, which nothing reachable over HTTP or MCP
/// may do — and it refuses without root rather than failing half-way.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshFirewallCommand};
///
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "firewall", "apply"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Firewall(firewall) = mesh.command else { panic!("expected `firewall`") };
/// assert!(matches!(firewall.command, Some(MeshFirewallCommand::Apply(_))));
///
/// // nothing else follows `firewall`
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "firewall", "remove"]).is_err());
/// ```
pub enum MeshFirewallCommand {
    /// Run the commands that admit the plan on this host's firewall; needs root, and exits 10 when it refuses or the firewall still does not admit the mesh
    Apply(MeshFirewallApplyArgs),
}

#[derive(Debug, Args)]
/// `mesh firewall apply`: the same `--port` the report takes, because the commands it
/// runs are the report's, and the same repository and output arguments, so that
/// `--format json` prints the apply report unchanged for a script that records what ran.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshFirewallApplyArgs, MeshFirewallCommand, OutputFormat};
///
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "firewall", "apply", "--port", "8791", "--format", "json"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Firewall(firewall) = mesh.command else { panic!("expected `firewall`") };
/// let Some(MeshFirewallCommand::Apply(apply)) = firewall.command else { panic!("expected `apply`") };
/// let apply: MeshFirewallApplyArgs = apply;
/// assert_eq!(apply.port, Some(8791));
/// assert_eq!(apply.query.format, OutputFormat::Json);
/// ```
pub struct MeshFirewallApplyArgs {
    #[arg(long)]
    /// The port this checkout's server listens on beyond loopback, when it does
    pub port: Option<u16>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh peer`: which single runtime of the mesh to describe. The runtime key is
/// `<node>-<runtime>`, and a bare node id is accepted as a shorthand for that node's first
/// runtime, because a machine running one server is the common case and spelling its
/// runtime out adds nothing. The key is positional and required: a `peer` question with no
/// subject is `peers`, which is a different command.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshPeerArgs};
///
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "peer", "a1b2c3d4-r1"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Peer(peer) = mesh.command else { panic!("expected `peer`") };
/// assert_eq!(peer.runtime, "a1b2c3d4-r1");
///
/// // the runtime is the whole question, so there is no answer without one
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "peer"]).is_err());
/// ```
pub struct MeshPeerArgs {
    /// The runtime key `<node>-<runtime>`, or a node id for its first runtime
    pub runtime: String,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh events`: a window onto the cooperation journal, in Lamport order. `--after` is a
/// resume point rather than a timestamp, so a caller that remembers the last stamp it saw
/// reads each event exactly once however the clocks of the machines involved disagree;
/// `--limit` bounds one answer. Both are optional, and saying neither asks for the newest
/// page under the server's own default.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshEventsArgs};
///
/// let cli =
///     Cli::try_parse_from(["majordomus", "mesh", "events", "--after", "42", "--limit", "10"])
///         .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Events(events) = mesh.command else { panic!("expected `events`") };
/// assert_eq!(events.after, Some(42));
/// assert_eq!(events.limit, Some(10));
///
/// // neither flag is the whole journal under the server's default page
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "events"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Events(events) = mesh.command else { panic!("expected `events`") };
/// assert_eq!((events.after, events.limit), (None, None));
/// assert!(!events.newest);
///
/// // the journal as it stands now: its newest events
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "events", "--newest"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Events(events) = mesh.command else { panic!("expected `events`") };
/// assert!(events.newest);
/// ```
pub struct MeshEventsArgs {
    /// Only events whose Lamport stamp is above this
    #[arg(long)]
    pub after: Option<u64>,
    /// At most this many (default 100, at most 1000)
    #[arg(long)]
    pub limit: Option<u64>,
    /// The newest events instead of the first ones after `--after`
    #[arg(long)]
    pub newest: bool,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh peers` and `mesh state`: how much of the mesh to show. Without a flag the answer is
/// the summary, which stays the same size however long the mesh's history grows; `--full`
/// is every session, claim, handover and review the fold holds. The filters narrow either.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshViewArgs};
///
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "state", "--full", "--live-claims",
///     "--after", "42", "--session", "s1", "--runtime", "a1b2", "--kind", "claims",
///     "--limit", "5", "--open", "--matching", "#905"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::State(view) = mesh.command else { panic!("expected `state`") };
/// let view: &MeshViewArgs = &view;
/// assert!(view.full && view.live_claims);
/// assert_eq!(view.pairs(), ["view=full", "claims=live", "after=42", "session=s1",
///     "runtime=a1b2", "kind=claims", "limit=5", "open=true", "matching=#905"]);
///
/// // no flag is the summary, asked for by asking for nothing
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "peers"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Peers(view) = mesh.command else { panic!("expected `peers`") };
/// assert!(view.pairs().is_empty());
/// ```
pub struct MeshViewArgs {
    /// Every session, claim, handover and review, not the summary
    #[arg(long)]
    pub full: bool,
    /// Only claims that are still held
    #[arg(long)]
    pub live_claims: bool,
    /// Only what moved after this Lamport stamp
    #[arg(long)]
    pub after: Option<u64>,
    /// Only this session: its key or its bare id
    #[arg(long)]
    pub session: Option<String>,
    /// Only this runtime (`<node>-<runtime>`), or every runtime of a node id
    #[arg(long)]
    pub runtime: Option<String>,
    /// Only this collection: sessions, claims, overlaps, handovers or reviews
    #[arg(long)]
    pub kind: Option<String>,
    /// At most this many of each collection, the newest first kept
    #[arg(long)]
    pub limit: Option<usize>,
    /// Only what is still open: active sessions, live claims, unanswered reviews, untaken handovers
    #[arg(long)]
    pub open: bool,
    /// Only what mentions this text: a path, a branch, an issue, a pull request, a word
    #[arg(long)]
    pub matching: Option<String>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

impl MeshViewArgs {
    /// The query string's pairs, unencoded, in the order the flags are declared: what `mesh
    /// state` and `mesh peers` send to the running server. No flag is no pair, which asks the
    /// server for its default, the summary.
    ///
    /// ```
    /// use clap::Parser;
    /// use majordomus_cli::cli::{Cli, Command, MeshCommand};
    ///
    /// let cli = Cli::try_parse_from(["majordomus", "mesh", "peers", "--open"]).unwrap();
    /// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
    /// let MeshCommand::Peers(view) = mesh.command else { panic!("expected `peers`") };
    /// assert_eq!(view.pairs(), ["open=true"]);
    /// ```
    pub fn pairs(&self) -> Vec<String> {
        let mut pairs = Vec::new();
        if self.full {
            pairs.push("view=full".to_string());
        }
        if self.live_claims {
            pairs.push("claims=live".to_string());
        }
        if let Some(after) = self.after {
            pairs.push(format!("after={after}"));
        }
        if let Some(session) = &self.session {
            pairs.push(format!("session={session}"));
        }
        if let Some(runtime) = &self.runtime {
            pairs.push(format!("runtime={runtime}"));
        }
        if let Some(kind) = &self.kind {
            pairs.push(format!("kind={kind}"));
        }
        if let Some(limit) = self.limit {
            pairs.push(format!("limit={limit}"));
        }
        if self.open {
            pairs.push("open=true".to_string());
        }
        if let Some(text) = &self.matching {
            pairs.push(format!("matching={text}"));
        }
        pairs
    }
}

#[derive(Debug, Args)]
/// `mesh claim`: the paths a session takes, the session taking them, and whether the claim
/// refuses an overlap or only reports one. The scope is positional and repeatable because
/// a claim over nothing is not a claim; `--session` is required because a claim belongs to
/// a session and ends with it, and `--advisory` is the difference between a claim that can
/// refuse another runtime's and one that only makes the overlap visible.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshClaimArgs, MeshCommand};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "claim", "src/mesh", "docs/MESH.md",
///     "--session", "s1", "--intent", "document the mesh",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Claim(claim) = mesh.command else { panic!("expected `claim`") };
/// assert_eq!(claim.scope, ["src/mesh", "docs/MESH.md"]);
/// assert_eq!(claim.session, "s1");
/// assert!(!claim.advisory, "a claim refuses an overlap unless it says otherwise");
///
/// // a claim over no path at all is a parse error, not an empty claim
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "claim", "--session", "s1"]).is_err());
/// ```
pub struct MeshClaimArgs {
    /// Repository-relative paths to claim
    #[arg(required = true)]
    pub scope: Vec<String>,
    /// The claiming session's id within this runtime (opened when new)
    #[arg(long)]
    pub session: String,
    /// What the claim is for
    #[arg(long)]
    pub intent: Option<String>,
    /// An advisory claim: overlaps are reported, never refused
    #[arg(long)]
    pub advisory: bool,
    /// The issue the claim is for
    #[arg(long)]
    pub issue: Option<String>,
    /// The task the session works under
    #[arg(long)]
    pub task: Option<String>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh release`: the one claim to give back, by the `<stream>/<claim>` key `mesh claim`
/// printed when it took it. The key names the stream that made the claim as well as the
/// claim itself, so a runtime can only release what it holds, and a person who kept the
/// line `mesh claim` printed needs nothing else.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshReleaseArgs};
///
/// let cli =
///     Cli::try_parse_from(["majordomus", "mesh", "release", "a1b2c3d4-r1/claim-7"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Release(release) = mesh.command else { panic!("expected `release`") };
/// assert_eq!(release.claim, "a1b2c3d4-r1/claim-7");
///
/// // releasing nothing in particular is not a release
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "release"]).is_err());
/// ```
pub struct MeshReleaseArgs {
    /// The claim's key, `<stream>/<claim>`, as `mesh claim` printed it
    pub claim: String,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh session`: the group that carries a session's lifecycle on the mesh. The group
/// itself runs nothing — every runnable path under it is `open` or `close` — so it refuses
/// to be invoked bare rather than guessing which half of a lifecycle was meant.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshSessionArgs, MeshSessionCommand};
///
/// let cli =
///     Cli::try_parse_from(["majordomus", "mesh", "session", "close", "--session", "s1"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Session(session) = mesh.command else { panic!("expected `session`") };
/// let session: MeshSessionArgs = session;
/// assert!(matches!(session.command, MeshSessionCommand::Close(_)));
///
/// // the group has no behaviour of its own
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "session"]).is_err());
/// ```
pub struct MeshSessionArgs {
    #[command(subcommand)]
    /// `open` or `close`.
    pub command: MeshSessionCommand,
}

#[derive(Debug, Subcommand)]
/// The two ends of a session's life on the mesh: `open`, which announces a session and
/// updates what it says about itself, and `close`, which ends it and with it every claim
/// it held on every linked runtime. There is no third verb, because everything a session
/// does between those two ends is a claim, a handover or a review.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshSessionCommand};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "session", "open", "--session", "s1", "--client", "claude-code",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Session(session) = mesh.command else { panic!("expected `session`") };
/// let MeshSessionCommand::Open(open) = session.command else { panic!("expected `open`") };
/// assert_eq!(open.client.as_deref(), Some("claude-code"));
/// ```
pub enum MeshSessionCommand {
    /// Open or update a session: what it is, what it does, where
    Open(MeshSessionOpenArgs),
    /// Close a session; its claims end with it on every linked runtime
    Close(MeshSessionCloseArgs),
}

#[derive(Debug, Args)]
/// `mesh session open`: everything a session says about itself, so that another runtime's
/// operator can tell who is here and what they are doing. Only `--session` is required;
/// the rest — client, worker, intent, task, issue, milestone, branch, head — are what the
/// session knows about its own work, and opening the same id twice updates the record
/// rather than refusing, which is what makes this usable from a hook that cannot know
/// whether it has run before.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshSessionCommand, MeshSessionOpenArgs};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "session", "open", "--session", "s1",
///     "--worker", "documenter", "--branch", "feature/mesh-cooperation",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Session(session) = mesh.command else { panic!("expected `session`") };
/// let MeshSessionCommand::Open(open) = session.command else { panic!("expected `open`") };
/// let open: MeshSessionOpenArgs = open;
/// assert_eq!(open.session, "s1");
/// assert_eq!(open.worker.as_deref(), Some("documenter"));
/// assert_eq!(open.branch.as_deref(), Some("feature/mesh-cooperation"));
/// assert_eq!(open.task, None, "what the session does not say stays unsaid");
///
/// // a session without an id is not a session
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "session", "open"]).is_err());
/// ```
pub struct MeshSessionOpenArgs {
    /// The session's id within this runtime
    #[arg(long)]
    pub session: String,
    /// The client (`claude-code`, `codex`, `cli`)
    #[arg(long)]
    pub client: Option<String>,
    /// The worker's name for itself
    #[arg(long)]
    pub worker: Option<String>,
    /// What the session is doing
    #[arg(long)]
    pub intent: Option<String>,
    /// The task id
    #[arg(long)]
    pub task: Option<String>,
    /// The issue
    #[arg(long)]
    pub issue: Option<String>,
    /// The milestone
    #[arg(long)]
    pub milestone: Option<String>,
    /// The branch
    #[arg(long)]
    pub branch: Option<String>,
    /// The head commit
    #[arg(long)]
    pub head: Option<String>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh session close`: the id of the session that has finished. Closing is the one act
/// that ends a session's claims everywhere at once, so it takes the session and nothing
/// else — there is no partial close, and no flag that could make one.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshSessionCloseArgs, MeshSessionCommand};
///
/// let cli =
///     Cli::try_parse_from(["majordomus", "mesh", "session", "close", "--session", "s1"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Session(session) = mesh.command else { panic!("expected `session`") };
/// let MeshSessionCommand::Close(close) = session.command else { panic!("expected `close`") };
/// let close: MeshSessionCloseArgs = close;
/// assert_eq!(close.session, "s1");
///
/// // and closing no session in particular is refused
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "session", "close"]).is_err());
/// ```
pub struct MeshSessionCloseArgs {
    /// The session's id within this runtime
    #[arg(long)]
    pub session: String,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh handover`: the group that moves a handover record between runtimes. Continuity
/// between two workers of one repository is otherwise a file one of them cannot see, and
/// the two verbs here are the two halves of that move; the group runs neither by itself.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshHandoverArgs, MeshHandoverCommand};
///
/// let cli = Cli::try_parse_from(["majordomus", "mesh", "handover", "publish"]).unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Handover(handover) = mesh.command else { panic!("expected `handover`") };
/// let handover: MeshHandoverArgs = handover;
/// assert!(matches!(handover.command, MeshHandoverCommand::Publish(_)));
///
/// // the group has no behaviour of its own
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "handover"]).is_err());
/// ```
pub struct MeshHandoverArgs {
    #[command(subcommand)]
    /// `publish` or `consume`.
    pub command: MeshHandoverCommand,
}

#[derive(Debug, Subcommand)]
/// The two halves of moving continuity across the mesh: `publish` offers this checkout's
/// handover to every linked runtime, and `consume` takes one another runtime offered and
/// writes it where `handover --resolve` will find it. Publishing does not choose a reader
/// and consuming does not ask the publisher, so neither side has to be running when the
/// other acts.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshHandoverCommand};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "handover", "consume", "h-7", "--session", "s1",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Handover(handover) = mesh.command else { panic!("expected `handover`") };
/// let MeshHandoverCommand::Consume(consume) = handover.command else { panic!("expected it") };
/// assert_eq!(consume.handover, "h-7");
/// ```
pub enum MeshHandoverCommand {
    /// Publish this checkout's newest handover record (or the one named) to every linked runtime
    Publish(MeshHandoverPublishArgs),
    /// Consume a handover another runtime published, writing it as a local record `handover --resolve` finds
    Consume(MeshHandoverConsumeArgs),
}

#[derive(Debug, Args)]
/// `mesh handover publish`: which record to offer, and what it belongs to. Every flag is
/// optional because the useful default is the newest handover this checkout wrote — the
/// one a worker has just finished — and `--path` exists for the case where that is not the
/// one meant. The issue and milestone travel with the record so that a runtime receiving
/// it can file it without reading it.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshHandoverCommand,
///     MeshHandoverPublishArgs};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "handover", "publish", "--issue", "I1703",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Handover(handover) = mesh.command else { panic!("expected `handover`") };
/// let MeshHandoverCommand::Publish(publish) = handover.command else { panic!("expected it") };
/// let publish: MeshHandoverPublishArgs = publish;
/// assert_eq!(publish.issue.as_deref(), Some("I1703"));
/// assert_eq!(publish.path, None, "no path means the newest record this checkout wrote");
/// ```
pub struct MeshHandoverPublishArgs {
    /// The record, relative to the repository root, under .ai/local/state/handovers/
    #[arg(long)]
    pub path: Option<String>,
    /// The issue the handover belongs to
    #[arg(long)]
    pub issue: Option<String>,
    /// The milestone it belongs to
    #[arg(long)]
    pub milestone: Option<String>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh handover consume`: which offered handover to take, and on whose behalf. The
/// consumption is recorded on the mesh so that two workers cannot silently pick up the
/// same handover, which is why the session is required and not inferred.
/// `--no-materialize` records the act without writing the local record, for a caller that
/// wants the claim on the handover but will read it some other way.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshHandoverCommand,
///     MeshHandoverConsumeArgs};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "handover", "consume", "h-7", "--session", "s1",
///     "--no-materialize",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Handover(handover) = mesh.command else { panic!("expected `handover`") };
/// let MeshHandoverCommand::Consume(consume) = handover.command else { panic!("expected it") };
/// let consume: MeshHandoverConsumeArgs = consume;
/// assert_eq!((consume.handover.as_str(), consume.session.as_str()), ("h-7", "s1"));
/// assert!(consume.no_materialize);
///
/// // the consuming session is what makes the consumption attributable, so it is required
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "handover", "consume", "h-7"]).is_err());
/// ```
pub struct MeshHandoverConsumeArgs {
    /// The handover's id, as `mesh state` lists it
    pub handover: String,
    /// The consuming session's id within this runtime
    #[arg(long)]
    pub session: String,
    /// Record the consumption without writing a local handover record
    #[arg(long)]
    pub no_materialize: bool,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh review`: the group that carries a review across runtimes, so that a worker can
/// have its branch read by a worker it cannot otherwise address. Asking and answering are
/// separate acts by separate runtimes, which is why they are separate subcommands and the
/// group itself runs nothing.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshReviewArgs, MeshReviewCommand};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "review", "request", "feature/x", "--session", "s1",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Review(review) = mesh.command else { panic!("expected `review`") };
/// let review: MeshReviewArgs = review;
/// assert!(matches!(review.command, MeshReviewCommand::Request(_)));
///
/// // the group has no behaviour of its own
/// assert!(Cli::try_parse_from(["majordomus", "mesh", "review"]).is_err());
/// ```
pub struct MeshReviewArgs {
    #[command(subcommand)]
    /// `request` or `answer`.
    pub command: MeshReviewCommand,
}

#[derive(Debug, Subcommand)]
/// The two sides of a review on the mesh: `request` puts a subject and its scope in front
/// of the other runtimes, and `answer` records one runtime's verdict on it. A request
/// names a reviewer only when it wants a particular one; unaddressed, it is an offer any
/// linked runtime may answer.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshReviewCommand};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "review", "answer", "a1b2c3d4-r1/rev-2",
///     "--session", "s1", "--verdict", "approved",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Review(review) = mesh.command else { panic!("expected `review`") };
/// let MeshReviewCommand::Answer(answer) = review.command else { panic!("expected `answer`") };
/// assert_eq!(answer.verdict, "approved");
/// ```
pub enum MeshReviewCommand {
    /// Ask for a review of a branch, commit or pull request
    Request(MeshReviewRequestArgs),
    /// Answer a review request
    Answer(MeshReviewAnswerArgs),
    /// Withdraw a review request this runtime asked for, with its result
    Withdraw(MeshReviewWithdrawArgs),
}

#[derive(Debug, Args)]
/// `mesh review request`: what is to be read, who is asking, and optionally who is asked.
/// The subject is a branch, a commit or a pull request, written as the requester refers to
/// it; `--scope` is repeatable and narrows the request to the paths that matter, which is
/// what makes an answer cheap enough to be worth asking for. Leaving `--reviewer` unsaid
/// offers the request to every linked runtime rather than to none.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshReviewCommand,
///     MeshReviewRequestArgs};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "review", "request", "feature/mesh-cooperation",
///     "--session", "s1", "--scope", "src/mesh", "--scope", "docs/MESH.md",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Review(review) = mesh.command else { panic!("expected `review`") };
/// let MeshReviewCommand::Request(request) = review.command else { panic!("expected it") };
/// let request: MeshReviewRequestArgs = request;
/// assert_eq!(request.subject, "feature/mesh-cooperation");
/// assert_eq!(request.scope, ["src/mesh", "docs/MESH.md"]);
/// assert_eq!(request.reviewer, None, "unaddressed: any linked runtime may answer");
/// ```
pub struct MeshReviewRequestArgs {
    /// What to review: a branch, a commit, a pull request
    pub subject: String,
    /// The requesting session's id within this runtime
    #[arg(long)]
    pub session: String,
    /// A path the review covers (repeatable)
    #[arg(long)]
    pub scope: Vec<String>,
    /// The issue
    #[arg(long)]
    pub issue: Option<String>,
    /// The runtime asked, `<node>-<runtime>`
    #[arg(long)]
    pub reviewer: Option<String>,
    /// What the reviewer needs beyond the subject: evidence, commands, the question (up to
    /// 8 KiB)
    #[arg(long)]
    pub body: Option<String>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `mesh review answer`: the request being answered, the session answering it, and the
/// verdict. The verdict is one of three declared words rather than free text, so that a
/// requester can act on an answer without reading it, and clap refuses anything else at
/// the boundary; the note is where the reasoning goes.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshReviewAnswerArgs, MeshReviewCommand};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "review", "answer", "a1b2c3d4-r1/rev-2", "--session", "s1",
///     "--verdict", "changes_requested", "--note", "the fold is not deterministic",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Review(review) = mesh.command else { panic!("expected `review`") };
/// let MeshReviewCommand::Answer(answer) = review.command else { panic!("expected `answer`") };
/// let answer: MeshReviewAnswerArgs = answer;
/// assert_eq!(answer.request, "a1b2c3d4-r1/rev-2");
/// assert_eq!(answer.verdict, "changes_requested");
/// assert_eq!(answer.note.as_deref(), Some("the fold is not deterministic"));
///
/// // a verdict outside the three declared words is refused before anything runs
/// assert!(Cli::try_parse_from([
///     "majordomus", "mesh", "review", "answer", "a1b2c3d4-r1/rev-2", "--session", "s1",
///     "--verdict", "lgtm",
/// ])
/// .is_err());
/// ```
pub struct MeshReviewAnswerArgs {
    /// The request's key, `<stream>/<review>`
    pub request: String,
    /// The answering session's id within this runtime
    #[arg(long)]
    pub session: String,
    /// What the reviewer decided
    #[arg(long, value_parser = [
        clap::builder::PossibleValue::new("approved")
            .help("the work is good as it stands and the requester may proceed"),
        clap::builder::PossibleValue::new("changes_requested")
            .help("the work needs changing before it proceeds; the note says what"),
        clap::builder::PossibleValue::new("commented")
            .help("an observation with no verdict: neither approval nor a request to change"),
    ])]
    pub verdict: String,
    /// The note
    #[arg(long)]
    pub note: Option<String>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// `monitor`: one page of the stream, or `--follow` to keep printing what is new. `--count`
/// and `--until` end a follow, so a script or an agent can wait for one event and go on;
/// `--match` keeps only the signals whose summary contains a text.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MonitorArgs};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "monitor", "--follow", "--for", "1b", "--match", "#885", "--until", "merged",
///     "--since", "30m", "--sources", "mesh,executor",
/// ])
/// .unwrap();
/// let Command::Monitor(m) = cli.command else { panic!("expected `monitor`") };
/// let m: MonitorArgs = m;
/// assert!(m.follow);
/// assert_eq!(m.reader.as_deref(), Some("1b"));
/// assert_eq!(m.until.as_deref(), Some("merged"));
/// assert_eq!(m.since, Some(1800));
/// assert_eq!(m.interval, 2);
///
/// // a duration is seconds, or a number with s, m, h or d
/// assert!(Cli::try_parse_from(["majordomus", "monitor", "--since", "soon"]).is_err());
/// ```
pub struct MonitorArgs {
    /// Keep following: ask again every `--interval` seconds and print only what is new
    #[arg(long)]
    pub follow: bool,
    /// Start after this cursor (a page's `cursor`), instead of the newest signals
    #[arg(long)]
    pub after: Option<String>,
    /// At most this many signals per page (default 50, at most 500)
    #[arg(long)]
    pub limit: Option<u64>,
    /// A comma-separated subset of mesh, executor and github (default: all three)
    #[arg(long)]
    pub sources: Option<String>,
    /// Your names, comma-separated (a worker such as 1b, a role, a login): what names them is marked for you; default $MAJORDOMUS_MONITOR_FOR
    #[arg(long = "for")]
    pub reader: Option<String>,
    /// How far back the first page reaches: seconds, or a number with s, m, h or d (default 1h)
    #[arg(long, value_parser = parse_duration)]
    pub since: Option<u64>,
    /// Keep only signals whose summary contains this text (case-insensitive)
    #[arg(long = "match")]
    pub pattern: Option<String>,
    /// Stop following after this many signals
    #[arg(long)]
    pub count: Option<u64>,
    /// Stop following at the first signal of this kind (e.g. merged, review_requested, run_failed)
    #[arg(long)]
    pub until: Option<String>,
    /// Give up following after this long, exiting 10: seconds, or a number with s, m, h or d
    #[arg(long, value_parser = parse_duration)]
    pub timeout: Option<u64>,
    /// Seconds between two asks while following
    #[arg(long, default_value_t = 2)]
    pub interval: u64,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

/// A duration as a person writes it: `90`, `90s`, `30m`, `2h`, `1d`, in seconds.
///
/// ```
/// use majordomus_cli::cli::parse_duration;
/// assert_eq!(parse_duration("90"), Ok(90));
/// assert_eq!(parse_duration("30m"), Ok(1800));
/// assert_eq!(parse_duration("2h"), Ok(7200));
/// assert_eq!(parse_duration("1d"), Ok(86400));
/// assert!(parse_duration("soon").is_err());
/// assert!(parse_duration("").is_err());
/// ```
pub fn parse_duration(text: &str) -> std::result::Result<u64, String> {
    let text = text.trim();
    let (number, unit) = match text.char_indices().last() {
        Some((i, c)) if c.is_ascii_alphabetic() => (&text[..i], c),
        _ => (text, 's'),
    };
    let n: u64 = number
        .parse()
        .map_err(|_| format!("{text:?} is not a duration: write 90, 90s, 30m, 2h or 1d"))?;
    let scale = match unit {
        's' => 1,
        'm' => 60,
        'h' => 3600,
        'd' => 86400,
        _ => return Err(format!("{text:?} has an unknown unit: use s, m, h or d")),
    };
    Ok(n.saturating_mul(scale))
}

#[derive(Debug, Args)]
/// `mesh review withdraw`: end a request this runtime asked for, because it is done, void
/// or superseded, with what came of it. Any session of the asking runtime may, no other
/// runtime may; the note is its own result, shown with the request, and never an answer.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, MeshCommand, MeshReviewCommand,
///     MeshReviewWithdrawArgs};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "mesh", "review", "withdraw", "a1b2c3d4-r1/r-1", "--session", "s1",
///     "--note", "superseded by the rebuilt head",
/// ])
/// .unwrap();
/// let Command::Mesh(mesh) = cli.command else { panic!("expected `mesh`") };
/// let MeshCommand::Review(review) = mesh.command else { panic!("expected `review`") };
/// let MeshReviewCommand::Withdraw(w) = review.command else { panic!("expected `withdraw`") };
/// let w: MeshReviewWithdrawArgs = w;
/// assert_eq!(w.request, "a1b2c3d4-r1/r-1");
/// assert_eq!(w.note.as_deref(), Some("superseded by the rebuilt head"));
/// ```
pub struct MeshReviewWithdrawArgs {
    /// The request's key, `<stream>/<review>`
    pub request: String,
    /// The withdrawing session, within the runtime that asked
    #[arg(long)]
    pub session: String,
    /// What came of it, or why it is void (up to 8 KiB)
    #[arg(long)]
    pub note: Option<String>,
    #[command(flatten)]
    /// Where the repository is and how to answer.
    pub query: MeshQueryArgs,
}

#[derive(Debug, Args)]
/// One read-only `mesh` question.
pub struct MeshQueryArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// `text` for a person, `json` for a machine; both render the same answer.
    pub format: OutputFormat,
}

#[derive(Debug, Args)]
/// `majordomus product`. The filters and the output shape are global, so they read the way
/// a person writes them — `product list --featured` — and are declared once.
pub struct ProductArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `list`, `show`, `domains`, `matrix`, `providers` or `validate`; none lists.
    pub command: Option<ProductCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,

    /// Only the features the homepage shows
    #[arg(long, global = true)]
    pub featured: bool,
    /// Include drafts and deprecated features, not only the stable ones
    #[arg(long, global = true)]
    pub all: bool,
    /// Only features serving this operational area of the why catalogue
    #[arg(long, global = true)]
    pub area: Option<String>,
    /// Only features filed under this product domain
    #[arg(long, global = true)]
    pub domain: Option<String>,
    /// Only features made of this capability module
    #[arg(long, global = true)]
    pub module: Option<String>,
    /// Only features made of this shell command
    #[arg(long = "names-command", global = true)]
    pub names_command: Option<String>,
    /// Only features exposed through this surface: cli, api, mcp, cockpit or docs
    #[arg(long, global = true)]
    pub surface: Option<String>,
    /// Case-insensitive text over identities, titles, headlines, summaries, tags and bodies
    #[arg(long, short = 'q', global = true)]
    pub query: Option<String>,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus product`.
pub enum ProductCommand {
    /// Every feature, narrowed by any filter, with the surfaces derived for each
    List,
    /// One feature in full: what it is made of, resolved, and everything derived from that
    Show {
        /// The feature's id, which is also its slug and its route
        id: String,
    },
    /// The domains of the product, each with the stable features that name it and what they add up to
    Domains,
    /// Every feature against every interface, and every module, command and kind against the features that name it
    Matrix,
    /// Every provider the tool has an adapter for, with what this repository does with it
    Providers,
    /// Every finding over the model; exit 10 when any is an error
    Validate,
}

#[derive(Debug, Args)]
/// `majordomus env`.
pub struct EnvArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// What to do with the snapshot; none prints it.
    pub command: Option<EnvCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus env`.
pub enum EnvCommand {
    /// The whole snapshot, resolved in full: what the layer holds is counted, and the cache the banner reads is written
    Status,
    /// Render the snapshot for a terminal. Goes to standard error, never standard output, because direnv reads standard output as the environment it is setting
    Banner {
        /// How much to show: `auto`, `full`, `compact` or `off`. Without it, MAJORDOMUS_BANNER decides, and without that, `auto` — which is silent when nothing is watching, shows the whole box when the repository has something new to say, and the two-line form when it does not
        #[arg(long, value_name = "MODE")]
        mode: Option<String>,
        /// Draw as if the terminal were this wide, whatever it is
        #[arg(long, value_name = "COLUMNS")]
        width: Option<usize>,
    },
    /// The variable assignments a shell in this repository benefits from, for `eval`. Assignments only: no command, no side effect
    Export {
        /// The shell to write for: `direnv`, `bash`, `zsh`, `sh`, `ksh` or `fish`
        #[arg(long = "shell", value_name = "SHELL", default_value = "direnv")]
        shell: String,
        /// Also draw the banner, to standard error, from the same snapshot. What an adapter asks for: one process on the path a shell takes on every entry, rather than two that each pay for a `git status`
        #[arg(long)]
        banner: bool,
        /// With --banner, how much to show; MAJORDOMUS_BANNER decides without it
        #[arg(long, value_name = "MODE", requires = "banner")]
        mode: Option<String>,
        /// Also refresh the workflow bridge under .ai/local/cache/ when a declaration behind it has changed. A few `stat` calls when nothing has; never a build, never a network call
        #[arg(long)]
        bridge: bool,
    },
    /// Enter the repository: the assignments a shell here benefits from on standard output, the banner on standard error, the workflow bridge refreshed when a declaration behind it moved, and the runtime ensured — the whole of what entering this repository is, as one call, so that no person and no agent has to remember a sequence. Never builds, never reaches a remote network, and never waits for a server it started to answer
    Enter {
        /// The shell to write for: `direnv`, `bash`, `zsh`, `sh`, `ksh` or `fish`
        #[arg(long = "shell", value_name = "SHELL", default_value = "direnv")]
        shell: String,
        /// How much banner to draw; MAJORDOMUS_BANNER decides without it
        #[arg(long, value_name = "MODE", conflicts_with = "no_banner")]
        mode: Option<String>,
        /// Do not draw the banner
        #[arg(long = "no-banner")]
        no_banner: bool,
        /// Do not refresh the workflow bridge
        #[arg(long = "no-bridge")]
        no_bridge: bool,
        /// Do not ensure the runtime: export, draw and refresh only. What MAJORDOMUS_RUNTIME=off says, as an argument
        #[arg(long = "no-runtime")]
        no_runtime: bool,
        /// Wait this many seconds for a server this call started to answer. Zero — the default, and what a shell prompt asks for — returns as soon as one has been started, and the entry file's watch over the lease brings the address in when it is published
        #[arg(long, value_name = "SECONDS", default_value_t = 0)]
        wait: u64,
    },
    /// Where each value came from: the file, command or constant that decided it, the resolver that read it, and how far it can be trusted
    Explain {
        /// One field in dotted form (`vcs.branch`, `layer.objects`), or a prefix; every field when absent
        #[arg(value_name = "FIELD")]
        field: Option<String>,
    },
    /// Whether Majordomus is in force in this checkout, claim by claim, with the evidence behind each verdict: git, the episode and its briefing, the task and handover, the policy, rules and ADRs, the shared server and the surfaces it serves, the peer board, recorded test runs, rule enforcement, provider projections and the deployment. A verdict that asserts something is in force always names its evidence. Resolves fast, from the rule tally a `--full` run cached; the HTTP route `/api/v1/environment/preflight` and the MCP tool `majordomus_preflight` answer the same value
    Preflight {
        /// The short form entering the repository draws: one line of claims and the most urgent thing to look at
        #[arg(long)]
        compact: bool,
        /// Build the index and count the rule proofs now, and leave the tally for entry to read
        #[arg(long)]
        full: bool,
    },
}

#[derive(Debug, Args)]
/// `majordomus release`. The read half is derived and the write half is one command, so
/// that raising a version is one edit to the one place it is authored, and the rest is derived.
pub struct ReleaseArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// What to answer; none prints the changelog.
    pub command: Option<ReleaseCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// How to render the answer.
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus release`.
pub enum ReleaseCommand {
    /// The changelog, composed from the layer's release records, the decisions dated inside each release's window, and the conventional commits in its range
    Changelog {
        /// One version or `unreleased`; every section when absent
        #[arg(value_name = "VERSION")]
        version: Option<String>,
    },
    /// The version the crate manifest declares, whether the projection the shell tool reads states it, any version written by hand where the tool's files live, and the bump the commits since the last release imply
    Version,
    /// What the public contract did since the last release, and the smallest version this tree may therefore declare
    Analyze {
        /// Measure against this ref instead of the last release
        #[arg(long, value_name = "REF")]
        since: Option<String>,
        /// Name every movement of the contract and the reason it counts for what it does
        #[arg(long)]
        explain: bool,
    },
    /// The version a landing of HEAD onto the trunk allocates, and why: the trunk's version, the measured movement, the policy floor and any exemption (ADR 0134)
    Next {
        /// The trunk the landing raises from
        #[arg(long, value_name = "REF", default_value = "origin/master")]
        base: String,
        /// What lands
        #[arg(long, value_name = "REF", default_value = "HEAD")]
        head: String,
    },
    /// Raise the version in the one place it is authored, to at least what the public contract requires; scripts/derive derives the rest
    Bump {
        /// Raise by this much instead of by the measured minimum; never below it
        #[arg(long, value_name = "LEVEL")]
        level: Option<String>,
        /// Set exactly this version; refused when it is below the measured minimum
        #[arg(long, value_name = "VERSION", conflicts_with = "level")]
        exact: Option<String>,
        /// Say what would change and write nothing
        #[arg(long)]
        dry_run: bool,
    },
}

#[derive(Debug, Args)]
/// `majordomus quality`. Declared as a group so that each measurement of the crate joins it
/// rather than crowding the root: the public surface's quality, and the tree rustdoc renders
/// from it.
pub struct QualityArgs {
    #[command(subcommand)]
    /// `report` or `rustdoc`.
    pub command: QualityCommand,
}

#[derive(Debug, Subcommand)]
/// The `quality` subcommands.
pub enum QualityCommand {
    /// Measure the crate and report every finding, with the rule it breaks and what to do about it
    Report(QualityReportArgs),
    /// Judge the crate's rustdoc tree against the crate: every page present, HEAD's, nothing broken or leaked
    Rustdoc(QualityRustdocArgs),
}

#[derive(Debug, Args)]
/// `majordomus quality rustdoc`: the tree rustdoc rendered from the crate, judged against the
/// crate's own inventory of exported items.
///
/// Without `--tree` the subject is the `rustdoc` web surface's artifact as the topology
/// resolves it, through the capability `quality.rustdoc`, exactly as HTTP and MCP ask. With
/// it, a person judges another copy of the same tree — the one `scripts/site-build` composed
/// into the site, say — by the same judgement; a path is an input of this terminal only and
/// never of the capability.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, QualityCommand, QualityRustdocArgs};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "quality", "rustdoc", "--tree", "site/public/rustdoc", "--kind", "link",
/// ])
/// .unwrap();
/// let args: QualityRustdocArgs = match cli.command {
///     Command::Quality(q) => match q.command {
///         QualityCommand::Rustdoc(args) => args,
///         other => panic!("expected `quality rustdoc`, parsed {other:?}"),
///     },
///     other => panic!("expected `quality`, parsed {other:?}"),
/// };
/// assert_eq!(args.tree.as_deref(), Some(std::path::Path::new("site/public/rustdoc")));
/// assert_eq!(args.kind.as_deref(), Some("link"));
/// assert!(!args.summary);
/// ```
pub struct QualityRustdocArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,

    /// Only findings of this kind, e.g. missing-page, orphan-page, stale, link, machine-path
    #[arg(long)]
    pub kind: Option<String>,

    /// Print the verdict and the counts and leave the findings out
    #[arg(long)]
    pub summary: bool,

    /// Judge this directory instead of the rustdoc surface's artifact, e.g. site/public/rustdoc
    #[arg(long, value_name = "DIR")]
    pub tree: Option<std::path::PathBuf>,
}

#[derive(Debug, Args)]
/// `majordomus convergence`: whether any of this repository's work is held where only one
/// disk can see it. It exits 10 when it is, so a hook or a script refuses on the verdict
/// rather than on a parsed report.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, ConvergenceArgs, OutputFormat};
///
/// let cli = Cli::try_parse_from(["majordomus", "convergence", "--format", "json", "--all"])
///     .unwrap();
/// let args: ConvergenceArgs = match cli.command {
///     Command::Convergence(args) => args,
///     other => panic!("expected `convergence`, parsed {other:?}"),
/// };
/// assert!(matches!(args.format, OutputFormat::Json));
/// assert!(args.all);
///
/// // a person asks the question with nothing after it, and reads only what is at risk
/// let bare = Cli::try_parse_from(["majordomus", "convergence"]).unwrap();
/// assert!(matches!(bare.command, Command::Convergence(ConvergenceArgs { all: false, .. })));
/// ```
pub struct ConvergenceArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// How to render the verdict
    pub format: OutputFormat,

    #[arg(long)]
    /// List every holding, not only the ones whose work exists on one disk
    pub all: bool,
}

#[derive(Debug, Args)]
/// `majordomus quality report`.
pub struct QualityReportArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,

    /// Only findings carrying this code, e.g. RUST_PUBLIC_MISSING_EXAMPLE
    #[arg(long)]
    pub code: Option<String>,

    /// Only findings under this repository-relative path prefix
    #[arg(long)]
    pub path: Option<String>,

    /// Print the counts and leave the findings out
    #[arg(long)]
    pub summary: bool,

    /// Show the findings the baseline already accepts, which are left out by default
    #[arg(long)]
    pub include_baselined: bool,

    /// Record today's findings as the accepted baseline, so the debt can shrink and cannot grow
    #[arg(long)]
    pub write_baseline: bool,
}

#[derive(Debug, Args)]
/// `majordomus economics`. A group with no action of its own: a subcommand is required,
/// and each one is either the command line of an `economics.*` capability or one of the
/// three producers of evidence that `cli::local` classifies as command-line-only.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EconomicsArgs, EconomicsCommand};
///
/// let cli = Cli::try_parse_from(["majordomus", "economics", "check"]).unwrap();
/// let args: EconomicsArgs = match cli.command {
///     Command::Economics(args) => args,
///     other => panic!("expected `economics`, parsed {other:?}"),
/// };
/// assert!(matches!(args.command, EconomicsCommand::Check(_)));
///
/// // naming no subcommand is a usage error, never a default that reads or spends
/// assert!(Cli::try_parse_from(["majordomus", "economics"]).is_err());
/// ```
pub struct EconomicsArgs {
    #[command(subcommand)]
    /// `summary`, `explain`, `runs`, `check`, `measure`, `run`, `references`.
    pub command: EconomicsCommand,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus economics`: four readers and three producers of evidence.
///
/// `summary`, `explain`, `runs` and `check` are the command line of the `economics.*`
/// capabilities, which compute every number once for every surface. `measure`, `run` and
/// `references` are the command line's own: they write records into the repository, spend
/// provider usage or build workspaces on this machine, which no read-only projection offers.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EconomicsCommand};
///
/// fn parse(argv: &[&str]) -> EconomicsCommand {
///     let cli = Cli::try_parse_from(argv.iter().copied()).unwrap();
///     let Command::Economics(args) = cli.command else { panic!("economics") };
///     args.command
/// }
///
/// assert!(matches!(parse(&["majordomus", "economics", "summary"]), EconomicsCommand::Summary(_)));
/// assert!(matches!(
///     parse(&["majordomus", "economics", "explain", "effective_token_reduction"]),
///     EconomicsCommand::Explain(e) if e.metric == "effective_token_reduction"
/// ));
/// assert!(matches!(parse(&["majordomus", "economics", "run"]), EconomicsCommand::Run(_)));
/// assert!(Cli::try_parse_from(["majordomus", "economics", "publish"]).is_err());
/// ```
pub enum EconomicsCommand {
    /// Every metric with its class, sample size and interval, the pairs, the segments, the state of the evidence, and the one statement the publication rule allows
    Summary(EconomicsSummaryArgs),
    /// One metric and everything it rests on: formula, class, pairs, runs, exclusions, and how to reproduce it
    Explain(EconomicsExplainArgs),
    /// The recorded runs every metric is computed from
    Runs(EconomicsRunsArgs),
    /// Refuse an unsupported savings claim: quantities next to the economics vocabulary in hand-written prose, and bound claims whose evidence does not stand
    Check(EconomicsCheckArgs),
    /// Run a deterministic suite (no model is called) and record its measurement
    Measure(EconomicsMeasureArgs),
    /// Run a live suite: real harness sessions with and without Majordomus, recorded as raw usage and gate verdicts. Spends provider usage
    Run(EconomicsRunArgs),
    /// Prove every task's hidden tests fail on its starting state and pass on its reference solution. No model is called
    References(EconomicsReferencesArgs),
}

#[derive(Debug, Args)]
/// `majordomus economics summary`. Every filter is optional and they combine as a
/// conjunction. They narrow the pairs and the metrics computed from them; the verdict is
/// always stated over all the live evidence, so a narrowed view cannot make publishable a
/// statement the whole evidence does not support.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{
///     Cli, Command, EconomicsCommand, EconomicsSummaryArgs, OutputFormat,
/// };
///
/// fn summary_of(argv: &[&str]) -> EconomicsSummaryArgs {
///     let cli = Cli::try_parse_from(argv.iter().copied()).unwrap();
///     let Command::Economics(args) = cli.command else { panic!("economics") };
///     let EconomicsCommand::Summary(summary) = args.command else { panic!("summary") };
///     summary
/// }
///
/// let s = summary_of(&[
///     "majordomus", "economics", "summary", "--suite", "pilot", "--category", "bug-fix",
///     "--format", "json",
/// ]);
/// assert_eq!(s.suite.as_deref(), Some("pilot"));
/// assert_eq!(s.category.as_deref(), Some("bug-fix"));
/// assert_eq!(s.format, OutputFormat::Json);
/// // a filter not named is no filter
/// assert!(s.task.is_none() && s.model.is_none());
/// ```
pub struct EconomicsSummaryArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,
    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,
    /// Only this suite
    #[arg(long)]
    pub suite: Option<String>,
    /// Only tasks of this category
    #[arg(long)]
    pub category: Option<String>,
    /// Only this task
    #[arg(long)]
    pub task: Option<String>,
    /// Only runs that asked for this model
    #[arg(long)]
    pub model: Option<String>,
}

#[derive(Debug, Args)]
/// `majordomus economics explain`. The metric is a required positional identifier, spelled
/// as the summary lists it; one the methodology does not declare is refused as not found,
/// with the declared metrics named, rather than answered with an empty explanation.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{
///     Cli, Command, EconomicsCommand, EconomicsExplainArgs, OutputFormat,
/// };
///
/// fn explain_of(argv: &[&str]) -> EconomicsExplainArgs {
///     let cli = Cli::try_parse_from(argv.iter().copied()).unwrap();
///     let Command::Economics(args) = cli.command else { panic!("economics") };
///     let EconomicsCommand::Explain(explain) = args.command else { panic!("explain") };
///     explain
/// }
///
/// let e = explain_of(&["majordomus", "economics", "explain", "effective_token_reduction"]);
/// assert_eq!(e.metric, "effective_token_reduction");
/// assert_eq!(e.format, OutputFormat::Text);
/// // there is no default metric to explain
/// assert!(Cli::try_parse_from(["majordomus", "economics", "explain"]).is_err());
/// ```
pub struct EconomicsExplainArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,
    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,
    /// The metric, e.g. effective_token_reduction
    pub metric: String,
}

#[derive(Debug, Args)]
/// `majordomus economics runs`. The recorded runs themselves, before any pairing or
/// statistics: the raw facts a disputed metric is checked against. The filters combine as a
/// conjunction and select whole records; they change no number inside one.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EconomicsCommand, EconomicsRunsArgs};
///
/// fn runs_of(argv: &[&str]) -> EconomicsRunsArgs {
///     let cli = Cli::try_parse_from(argv.iter().copied()).unwrap();
///     let Command::Economics(args) = cli.command else { panic!("economics") };
///     let EconomicsCommand::Runs(runs) = args.command else { panic!("runs") };
///     runs
/// }
///
/// let r = runs_of(&[
///     "majordomus", "economics", "runs", "--task", "vat-rounding", "--variant", "baseline",
/// ]);
/// assert_eq!(r.task.as_deref(), Some("vat-rounding"));
/// assert_eq!(r.variant.as_deref(), Some("baseline"));
/// assert!(r.suite.is_none(), "every suite's runs unless one is named");
/// ```
pub struct EconomicsRunsArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,
    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,
    /// Only this suite
    #[arg(long)]
    pub suite: Option<String>,
    /// Only this task
    #[arg(long)]
    pub task: Option<String>,
    /// Only this variant
    #[arg(long)]
    pub variant: Option<String>,
}

#[derive(Debug, Args)]
/// `majordomus economics check`. It takes no filter, because a gate that could be narrowed
/// could be narrowed past the claim it exists to refuse. It exits 10 when it finds a
/// quantity stated beside the economics vocabulary in hand-written prose, or a bound claim
/// whose evidence does not stand.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EconomicsCheckArgs, EconomicsCommand, OutputFormat};
///
/// fn check_of(argv: &[&str]) -> EconomicsCheckArgs {
///     let cli = Cli::try_parse_from(argv.iter().copied()).unwrap();
///     let Command::Economics(args) = cli.command else { panic!("economics") };
///     let EconomicsCommand::Check(check) = args.command else { panic!("check") };
///     check
/// }
///
/// assert_eq!(check_of(&["majordomus", "economics", "check"]).format, OutputFormat::Text);
/// let json = check_of(&["majordomus", "economics", "check", "--format", "json"]);
/// assert_eq!(json.format, OutputFormat::Json);
/// // nothing narrows the gate
/// assert!(Cli::try_parse_from(["majordomus", "economics", "check", "--suite", "x"]).is_err());
/// ```
pub struct EconomicsCheckArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,
    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Args)]
/// `majordomus economics measure`. Runs a deterministic suite, the context compiler over
/// the suite's seeds with no model called, and writes its record as
/// `runs/<suite>/<commit>.json` under the benchmark directory, so a second measurement at
/// the same commit replaces the first. A live suite is refused with the `run` command that
/// runs it; `--dry-run` measures, prints and writes nothing.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EconomicsCommand, EconomicsMeasureArgs};
///
/// fn measure_of(argv: &[&str]) -> EconomicsMeasureArgs {
///     let cli = Cli::try_parse_from(argv.iter().copied()).unwrap();
///     let Command::Economics(args) = cli.command else { panic!("economics") };
///     let EconomicsCommand::Measure(measure) = args.command else { panic!("measure") };
///     measure
/// }
///
/// let default = measure_of(&["majordomus", "economics", "measure"]);
/// assert_eq!(default.suite, "context");
/// assert!(!default.dry_run, "measuring records unless told otherwise");
/// assert!(measure_of(&["majordomus", "economics", "measure", "--dry-run"]).dry_run);
/// ```
pub struct EconomicsMeasureArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,
    /// The deterministic suite to measure
    #[arg(long, default_value = "context")]
    pub suite: String,
    /// Measure and print, write nothing
    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
/// `majordomus economics run`. Spends provider usage: each selected task runs as real
/// harness sessions with and without Majordomus installed, and each run is recorded as raw
/// usage and gate verdicts. Empty `tasks` and `repetitions` mean every one the suite
/// declares. `--dry-run` prepares each workspace, prints the harness command and removes the
/// workspace again without starting a session, so it spends nothing. A run already recorded
/// is skipped and never written over; `--force` is accepted only to be refused with the
/// reason, because a recorded run is evidence.
///
/// ```
/// use std::path::Path;
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EconomicsCommand, EconomicsRunArgs};
///
/// fn run_of(argv: &[&str]) -> EconomicsRunArgs {
///     let cli = Cli::try_parse_from(argv.iter().copied()).unwrap();
///     let Command::Economics(args) = cli.command else { panic!("economics") };
///     let EconomicsCommand::Run(run) = args.command else { panic!("run") };
///     run
/// }
///
/// let run = run_of(&[
///     "majordomus", "economics", "run", "--task", "a", "--task", "b", "--dry-run",
/// ]);
/// // repeated singular flags accumulate into the selection
/// assert_eq!(run.tasks, ["a", "b"]);
/// assert!(run.dry_run && !run.force);
/// // the pilot suite, every repetition, two runs at once, thirty minutes a session
/// assert_eq!(run.suite, "pilot");
/// assert!(run.repetitions.is_empty() && run.work_dir.is_none());
/// assert_eq!((run.parallel, run.session_timeout), (2, 1800));
/// assert_eq!(run.harness, Path::new("claude"));
/// ```
pub struct EconomicsRunArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,
    /// The live suite to run
    #[arg(long, default_value = "pilot")]
    pub suite: String,
    /// Only this task (repeatable)
    #[arg(long = "task")]
    pub tasks: Vec<String>,
    /// Only this repetition (repeatable)
    #[arg(long = "repetition")]
    pub repetitions: Vec<u32>,
    /// Where transcripts go; never inside the repository. Workspaces are fresh directories
    /// of the system temporary directory, removed when their run ends
    #[arg(long, value_name = "PATH")]
    pub work_dir: Option<PathBuf>,
    /// The harness executable
    #[arg(long, value_name = "PATH", default_value = "claude")]
    pub harness: PathBuf,
    /// Runs in flight at once
    #[arg(long, default_value_t = 2)]
    pub parallel: usize,
    /// Per-session wall-clock limit, in seconds
    #[arg(long, default_value_t = 1800)]
    pub session_timeout: u64,
    /// Refused: a recorded run is evidence and is never overwritten; exclude it in the
    /// methodology with a reason and record another repetition
    #[arg(long)]
    pub force: bool,
    /// Prepare every workspace and print the harness command; run nothing, spend nothing
    #[arg(long)]
    pub dry_run: bool,
}

#[derive(Debug, Args)]
/// `majordomus economics references`. Proves every task can fail: its hidden tests must
/// fail on the starting fixture and pass once the reference solution is applied, or a
/// failed run would say nothing about the agent. No model is called; the workspaces are
/// built on this machine, under the system temporary directory unless `--work-dir` names
/// another, and a task that breaks the rule makes the command exit 10.
///
/// ```
/// use std::path::Path;
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EconomicsCommand, EconomicsReferencesArgs};
///
/// fn references_of(argv: &[&str]) -> EconomicsReferencesArgs {
///     let cli = Cli::try_parse_from(argv.iter().copied()).unwrap();
///     let Command::Economics(args) = cli.command else { panic!("economics") };
///     let EconomicsCommand::References(r) = args.command else { panic!("references") };
///     r
/// }
///
/// assert!(references_of(&["majordomus", "economics", "references"]).work_dir.is_none());
/// let placed = references_of(&[
///     "majordomus", "economics", "references", "--work-dir", "scratch/refs",
/// ]);
/// assert_eq!(placed.work_dir.as_deref(), Some(Path::new("scratch/refs")));
/// ```
pub struct EconomicsReferencesArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,
    /// Where the workspaces go
    #[arg(long, value_name = "PATH")]
    pub work_dir: Option<PathBuf>,
}

#[derive(Debug, Args)]
/// `majordomus run`. One capability, run as an execution in this process, followed to its
/// end.
///
/// It runs here rather than on the shared server because following it is the point: the
/// steps and the progress are printed as the handler reports them, over a subscription to
/// this process's own store rather than by asking anything repeatedly. The capability, the
/// executor and the events are the same ones a browser sees; only the audience differs.
pub struct RunArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    /// The capability to run, by its canonical id (`health.report`, `objects.verify`)
    pub capability: String,

    /// Its input, as one JSON object; the capability's input schema is what validates it
    #[arg(long, value_name = "JSON")]
    pub input: Option<String>,

    /// Print the events as they arrive on stderr; on by default when stderr is a terminal
    #[arg(long)]
    pub follow: bool,

    /// Print nothing but the final output
    #[arg(long)]
    pub quiet: bool,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Args)]
/// `majordomus executions`. What the server serving this repository has run.
///
/// An execution lives in the process that accepted it, so these read the shared server
/// this repository's lease names, and fall back to this process — which, in a one-shot
/// command, has run nothing — when no server answers.
pub struct ExecutionsArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `list`, `show`, `events`, `cancel` or `protocol`; none lists.
    pub command: Option<ExecutionsCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus executions`.
pub enum ExecutionsCommand {
    /// Every execution the server remembers, newest first
    List {
        /// Only executions in this state (queued, running, cancelling, succeeded, failed, cancelled)
        #[arg(long)]
        state: Option<String>,
        /// Only executions of this capability
        #[arg(long)]
        capability: Option<String>,
    },
    /// One execution in full: its state, its steps, its diagnostics and what it produced
    Show {
        /// The execution's id
        id: String,
    },
    /// One execution's retained events, oldest first
    Events {
        /// The execution's id
        id: String,
        /// Only events after this sequence number
        #[arg(long)]
        after: Option<u64>,
    },
    /// Ask an execution to stop
    Cancel {
        /// The execution's id
        id: String,
    },
    /// The live channel's contract: where it is, what it writes, and the schema of each message
    Protocol,
}

#[derive(Debug, Args)]
/// `majordomus evidence`. The output shape is global, so it reads the way a person writes
/// it — `evidence show --findings --format json` — and is declared once.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EvidenceArgs, EvidenceCommand, OutputFormat};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "evidence", "show", "--findings", "--format", "json",
/// ])
/// .unwrap();
/// let args: EvidenceArgs = match cli.command {
///     Command::Evidence(args) => args,
///     other => panic!("expected `evidence`, parsed {other:?}"),
/// };
/// // `--format` is declared once and reaches every subcommand, so it parses where a
/// // person writes it rather than only before the subcommand
/// assert!(matches!(args.format, OutputFormat::Json));
/// assert!(matches!(args.command, EvidenceCommand::Show { findings: true, .. }));
///
/// // the group runs nothing of its own: every runnable path here is a capability's
/// assert!(Cli::try_parse_from(["majordomus", "evidence"]).is_err());
/// ```
pub struct EvidenceArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `show`, `claim`, `proves`, `record` or `stamp`. Required: the group runs nothing of its own,
    /// so that every runnable path here is one a capability declares
    /// rather than one classified command-line-only in `cli::local`.
    pub command: EvidenceCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus evidence`: the whole matrix, one claim, one test, and
/// the recorder.
///
/// `show`, `claim` and `proves` are the command line of `evidence.report`,
/// `evidence.claim` and `evidence.test`; `record` is the command line of
/// `evidence.record`, which is a command line and nothing else because it writes a tracked
/// file and this server is read-only; `stamp` is the command line of `evidence.stamp`, a
/// read offered only here because it reads a path its caller names. The capability is
/// `evidence.test` and the command is
/// `proves` — `test` is a word the fish completion adapter refuses, so the command line
/// spells the relation with the verb rather than renaming the identity.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, EvidenceCommand};
///
/// fn parse(args: &[&str]) -> EvidenceCommand {
///     let cli = Cli::try_parse_from(args.iter().copied()).unwrap();
///     let Command::Evidence(args) = cli.command else { panic!("evidence") };
///     args.command
/// }
///
/// assert!(matches!(
///     parse(&["majordomus", "evidence", "show", "--state", "stale"]),
///     EvidenceCommand::Show { state: Some(s), check: false, .. } if s == "stale"
/// ));
/// assert!(matches!(
///     parse(&["majordomus", "evidence", "claim", "evidence-both-directions"]),
///     EvidenceCommand::Claim { id } if id == "evidence-both-directions"
/// ));
/// assert!(matches!(
///     parse(&["majordomus", "evidence", "proves", "crate:why"]),
///     EvidenceCommand::Proves { id } if id == "crate:why"
/// ));
/// assert!(Cli::try_parse_from(["majordomus", "evidence", "test", "crate:why"]).is_err());
///
/// // recording reads a report a runner already wrote; it runs no test
/// assert!(matches!(
///     parse(&["majordomus", "evidence", "record", "--suite", "tmp/report.tsv"]),
///     EvidenceCommand::Record { suite: Some(p), origin: None, .. } if p.ends_with("report.tsv")
/// ));
///
/// // a run measures the checkout it left; the recording carries that measurement
/// assert!(matches!(
///     parse(&["majordomus", "evidence", "stamp", "--report", "suite.tsv", "--exclude", "dist"]),
///     EvidenceCommand::Stamp { report: Some(r), exclude, .. }
///         if r.ends_with("suite.tsv") && exclude == ["dist"]
/// ));
/// assert!(matches!(
///     parse(&[
///         "majordomus", "evidence", "record", "--suite", "s.tsv", "--provenance", "p.json",
///         "--provenance", "crate=c.json", "--ledger", "local",
///     ]),
///     EvidenceCommand::Record { provenance, ledger: Some(l), .. }
///         if provenance == ["p.json", "crate=c.json"] && l == "local"
/// ));
/// ```
pub enum EvidenceCommand {
    /// Every claim against the evidence recorded for it
    Show {
        /// Only claims in this proof state (proven, inputs_unchanged, stale, failing, not_run, unrunnable, no_test)
        #[arg(long)]
        state: Option<String>,
        /// Only claims declaring this status (guaranteed, advisory, planned, rejected)
        #[arg(long)]
        status: Option<String>,
        /// Only the claims whose declared status the evidence does not support
        #[arg(long)]
        findings: bool,
        /// Exit 10 when a claim declares a guarantee the evidence does not support
        #[arg(long)]
        check: bool,
        /// Judge at the checked-out commit as committed (HEAD, or any name of it), from the ledger that commit holds, instead of at the working tree
        #[arg(long, value_name = "REV")]
        presented: Option<String>,
        /// What you know about the presented commit's tree (clean, dirty, unknown); it can only weaken the measured state
        #[arg(
            long,
            value_name = "TREE",
            value_parser = clap::builder::PossibleValuesParser::new([
                clap::builder::PossibleValue::new("clean")
                    .help("Nothing you know of: the measured state stands"),
                clap::builder::PossibleValue::new("dirty")
                    .help("The build did not come from the commit as committed; nothing reads as proven"),
                clap::builder::PossibleValue::new("unknown")
                    .help("You cannot say whether it did; nothing reads as proven"),
            ])
        )]
        presented_tree: Option<String>,
    },
    /// One claim: its proof state, the execution behind it, and how to reproduce it
    Claim {
        /// The claim id, as docs/CLAIMS.yaml spells it
        id: String,
    },
    /// One test: its latest execution and every claim it proves
    Proves {
        /// `suite:<case>`, `crate:<binary>`, or the path a claim names it with
        id: String,
    },
    /// Record a run that happened into the ledger
    Record {
        /// The runner's TSV report (`MJ_TEST_REPORT=<file> bash test/run.sh`)
        #[arg(long)]
        suite: Option<PathBuf>,
        /// A file holding `cargo test`'s output, for the crate's own integration tests
        #[arg(long)]
        crate_output: Option<PathBuf>,
        /// Where the run happened: local (the default), ci or release
        #[arg(long)]
        origin: Option<String>,
        /// The file `evidence stamp --out` wrote; prefix `suite=`, `crate=` or `coverage=`
        /// when the file names no producer and several reports are given
        #[arg(long, value_name = "[PRODUCER=]FILE")]
        provenance: Vec<String>,
        /// The summary `scripts/rust-coverage --summary-json` wrote
        #[arg(long)]
        coverage: Option<PathBuf>,
        /// repo (the default) or local
        #[arg(long)]
        ledger: Option<String>,
        /// Also write the run record to this file
        #[arg(long)]
        run_record: Option<PathBuf>,
    },
    /// Measure the checkout as a run left it, for `record --provenance`
    Stamp {
        /// The producer whose run this is: suite, crate or coverage
        #[arg(long)]
        producer: Option<String>,
        /// The report the run wrote
        #[arg(long)]
        report: Option<PathBuf>,
        /// One of the run's own untracked outputs (a file, or a directory with everything under it)
        #[arg(long)]
        exclude: Vec<String>,
        /// Write the measurement to this file
        #[arg(long)]
        out: Option<PathBuf>,
    },
}

#[derive(Debug, Args)]
/// `majordomus delivery`: every product feature against the delivery invariant. The output
/// shape is global, so it reads the way a person writes it — `delivery report --format json`.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, DeliveryArgs, DeliveryCommand, OutputFormat};
///
/// let cli = Cli::try_parse_from(["majordomus", "delivery", "report", "--check", "--format", "json"])
///     .unwrap();
/// let args: DeliveryArgs = match cli.command {
///     Command::Delivery(args) => args,
///     other => panic!("expected `delivery`, parsed {other:?}"),
/// };
/// assert!(matches!(args.format, OutputFormat::Json));
/// assert!(matches!(args.command, DeliveryCommand::Report { check: true }));
///
/// // the group runs nothing of its own: every runnable path here is a capability's
/// assert!(Cli::try_parse_from(["majordomus", "delivery"]).is_err());
/// ```
pub struct DeliveryArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `report` or `show`. Required: the group runs nothing of its own.
    pub command: DeliveryCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus delivery`: the command line of `delivery.report` and
/// `delivery.feature`.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, DeliveryCommand};
///
/// fn parse(args: &[&str]) -> DeliveryCommand {
///     let cli = Cli::try_parse_from(args.iter().copied()).unwrap();
///     let Command::Delivery(args) = cli.command else { panic!("delivery") };
///     args.command
/// }
///
/// assert!(matches!(parse(&["majordomus", "delivery", "report"]), DeliveryCommand::Report { check: false }));
/// assert!(matches!(
///     parse(&["majordomus", "delivery", "show", "evidence", "--check"]),
///     DeliveryCommand::Show { id, check: true } if id == "evidence"
/// ));
/// assert!(Cli::try_parse_from(["majordomus", "delivery", "show"]).is_err());
/// ```
pub enum DeliveryCommand {
    /// Every feature against every dimension, with the development stage of what does not exist
    Report {
        /// Exit 10 when any feature does not exist
        #[arg(long)]
        check: bool,
    },
    /// One feature: every dimension with its reason and remediation
    Show {
        /// The feature's id, as `product list` gives it
        id: String,
        /// Exit 10 when the feature does not exist
        #[arg(long)]
        check: bool,
    },
}

#[derive(Debug, Args)]
/// `majordomus served`: what a deployment serves, observed from outside and judged against
/// a commit. `ServedArgs` carries the repository the question is asked of, the subcommand
/// and the output shape.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, ServedArgs, ServedCommand};
///
/// let cli = Cli::try_parse_from(["majordomus", "served", "show"]).unwrap();
/// let Command::Served(args) = cli.command else { panic!("served") };
/// let _: ServedArgs = args;   // the group's own arguments
///
/// fn parse(args: &[&str]) -> ServedCommand {
///     let Command::Served(a) = Cli::try_parse_from(args).unwrap().command else { panic!() };
///     a.command
/// }
/// assert!(matches!(
///     parse(&["majordomus", "served", "observe", "--commit", "origin/master", "--dry-run"]),
///     ServedCommand::Observe { commit: Some(c), dry_run: true, .. } if c == "origin/master"
/// ));
/// assert!(matches!(
///     parse(&["majordomus", "served", "show", "--deployment", "pages"]),
///     ServedCommand::Show { deployment: Some(d), commit: None } if d == "pages"
/// ));
/// assert!(Cli::try_parse_from(["majordomus", "served"]).is_err());
/// ```
pub struct ServedArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `observe`, `forge` or `show`.
    pub command: ServedCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus served`: `observe` is the command line of
/// `served.observe`, `forge` of `served.forge` and `show` of `served.show`. `observe` and
/// `forge` reach the network, and each is a command line and nothing else.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, ServedCommand};
/// let cli = Cli::try_parse_from(["majordomus", "served", "observe", "--dry-run"]).unwrap();
/// let Command::Served(args) = cli.command else { panic!("served") };
/// assert!(matches!(args.command, ServedCommand::Observe { dry_run: true, .. }));
/// let cli = Cli::try_parse_from(["majordomus", "served", "forge"]).unwrap();
/// let Command::Served(args) = cli.command else { panic!("served") };
/// assert!(matches!(args.command, ServedCommand::Forge));
/// ```
pub enum ServedCommand {
    /// Probe the build identity a deployment serves, judge it against a commit and record it
    Observe {
        /// The commit expected to be served (default HEAD)
        #[arg(long)]
        commit: Option<String>,
        /// The site's base URL (default: base_url of site/config.toml)
        #[arg(long)]
        url: Option<String>,
        /// The identity file under the base (default build.json)
        #[arg(long)]
        identity: Option<String>,
        /// The name the observation is recorded under (default pages)
        #[arg(long)]
        deployment: Option<String>,
        /// Bound on the probe, in seconds (default 10)
        #[arg(long)]
        timeout: Option<u64>,
        /// Judge without recording
        #[arg(long)]
        dry_run: bool,
    },
    /// Ask the forge which deployments and releases it recorded, and keep the answer for the readers
    Forge,
    /// Each deployment's newest record, re-judged against a commit
    Show {
        /// The commit to judge against (default HEAD)
        #[arg(long)]
        commit: Option<String>,
        /// Only this deployment
        #[arg(long)]
        deployment: Option<String>,
    },
}

#[derive(Debug, Args)]
/// `majordomus entity`. Every object of the layer as an addressable node.
///
/// The command-line half of the projection the Cockpit renders and the HTTP and MCP
/// surfaces answer: `kinds` is every kind with the route of its index, and `show` is one
/// entity with everything joined to it. Neither enumerates anything — both read the index.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, EntityArgs};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "entity", "kinds"]).unwrap();
/// let Command::Entity(args) = cli.command else { panic!("not the entity command") };
/// let _: EntityArgs = args;
/// ```
pub struct EntityArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `kinds` or `show`. Required: the group runs nothing of its own, so that every
    /// runnable path here is one a capability declares.
    pub command: EntityCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus entity`.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, EntityCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "entity", "show", "majordomus://adr/adr-0004"]).unwrap();
/// let Command::Entity(args) = cli.command else { panic!("not the entity command") };
/// assert!(matches!(args.command, EntityCommand::Show { .. }));
/// ```
pub enum EntityCommand {
    /// Every kind of the layer, the route of its index, and every route collision there is
    Kinds,
    /// One entity: its route, what it references, what references it, where it is served
    Show {
        /// The entity, as `majordomus://<kind>/<identity>` or as `<kind>/<slug>`
        address: String,
    },
}

#[derive(Debug, Args)]
/// `majordomus rules`. The rule corpus against the proof there is for it: what each rule
/// names, whether it is in the tree, whether a runner drives it, whether anything ran, and
/// whether what ran is older than what it is about.
///
/// Distinct from `majordomus doctrine`, which asks whether the repository satisfies a rule
/// right now. That is a question about the tree; this is a question about the rule.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, RulesArgs};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "rules", "report", "--findings"]).unwrap();
/// let Command::Rules(args) = cli.command else { panic!("not the rules command") };
/// let _: RulesArgs = args;
/// ```
pub struct RulesArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `report`, `show` or `proves`. Required: the group runs nothing of its own, so that
    /// every runnable path here is one a capability declares
    /// rather than one classified command-line-only in `cli::local`.
    pub command: RulesCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus rules`.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, RulesCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "rules", "show", "project.x"]).unwrap();
/// let Command::Rules(args) = cli.command else { panic!("not the rules command") };
/// assert!(matches!(args.command, RulesCommand::Show { .. }));
/// ```
pub enum RulesCommand {
    /// Every rule against the proof there is for it
    Report {
        /// Only rules in this proof state (proven, inputs_unchanged, stale, gated, failing, not_run, reviewed, unrunnable, dangling, unproven)
        #[arg(long)]
        state: Option<String>,
        /// Only rules of this class (blocking, advisory)
        #[arg(long)]
        class: Option<String>,
        /// Only rules of this namespace (project, majordomus)
        #[arg(long)]
        namespace: Option<String>,
        /// Only the rules whose declared class the proof does not support
        #[arg(long)]
        findings: bool,
        /// Exit 10 when a rule declares a class the proof does not support
        #[arg(long)]
        check: bool,
    },
    /// One rule: what proves it, what it depends on, and what is missing
    Show {
        /// The rule id, with or without its version
        id: String,
    },
    /// One test: every rule it proves, and the rules that would be left with none
    Proves {
        /// `suite:<case>`, `crate:<binary>`, or the path a rule names it with
        id: String,
    },
}

#[derive(Debug, Args)]
/// `majordomus knowledge`. What the knowledge deriver left for review and whether it is
/// still writing. The deriver itself is the shell tool's (`lib/knowledge.sh`); this reads
/// what it wrote — the candidate records under the tracked knowledge section, one record by
/// id with its references resolved, and the derivation status of this checkout — through the
/// `knowledge_base` capabilities, so the command line answers what HTTP and MCP answer.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, KnowledgeArgs};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "knowledge", "status", "--format", "json"]).unwrap();
/// let Command::Knowledge(args) = cli.command else { panic!("not the knowledge command") };
/// let _: KnowledgeArgs = args;
/// ```
pub struct KnowledgeArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `candidates`, `record` or `status`. Required: the group runs nothing of its own, so
    /// that every runnable path here is one a capability declares rather than one
    /// classified command-line-only in `cli::local`.
    pub command: KnowledgeCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus knowledge`.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, KnowledgeCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "knowledge", "record", "e1-0123456789ab"]).unwrap();
/// let Command::Knowledge(args) = cli.command else { panic!("not the knowledge command") };
/// assert!(matches!(args.command, KnowledgeCommand::Record { id } if id == "e1-0123456789ab"));
/// assert!(Cli::try_parse_from(["majordomus", "knowledge"]).is_err(), "a subcommand is required");
/// ```
pub enum KnowledgeCommand {
    /// The candidate records awaiting review, with the branch of the episode each came from and how long each has waited
    Candidates,
    /// One knowledge record by id: its front matter, and every reference it names resolved against the index, the ledger and git
    Record {
        /// The record id, which is also its file name
        id: String,
    },
    /// Whether the deriver is still writing: the last derivation, the newest closed episode, and the stopped-writer judgement against session.freshness
    Status,
}

#[derive(Debug, Args)]
/// `majordomus continuity`. The output shape is global, so it reads where a person writes
/// it, and the group runs nothing of its own.
///
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, ContinuityArgs, ContinuityCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "continuity", "resume", "--record", "a1b2"]).unwrap();
/// let Command::Continuity(args) = cli.command else { panic!("not the continuity command") };
/// let args: ContinuityArgs = args;
/// assert!(matches!(args.command, ContinuityCommand::Resume { record: Some(r) } if r == "a1b2"));
/// assert!(Cli::try_parse_from(["majordomus", "continuity"]).is_err(), "a subcommand is required");
/// ```
pub struct ContinuityArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `status`, `records`, `plan`, `publish`, `sync` or `resume`. Required, so that every
    /// runnable path is a capability's.
    pub command: ContinuityCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus continuity`: the command line of `continuity.status`,
/// `continuity.records`, `continuity.device`, `continuity.plan`, `continuity.publish`,
/// `continuity.sync` and `continuity.resume`.
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, ContinuityCommand};
/// use clap::Parser;
/// let cli = Cli::parse_from(["majordomus", "continuity", "publish", "--issue", "#184"]);
/// let Command::Continuity(args) = cli.command else { panic!("continuity") };
/// let ContinuityCommand::Publish { issue, handover, .. } = args.command else { panic!("publish") };
/// assert_eq!(issue.as_deref(), Some("#184"));
/// assert!(handover.is_none(), "the newest handover by default");
/// ```
pub enum ContinuityCommand {
    /// This device, the record this checkout continues, the store against its remote (no network), every line of work, and what other devices published that could be resumed here
    Status,
    /// Every published handover the local store admits, by line, and every file it refused
    Records,
    /// This device's identity — the mesh node key, created when absent — and its label; with --label, rename it
    Device {
        /// A label for this device (macbook-pro, mac-mini)
        #[arg(long)]
        label: Option<String>,
    },
    /// Decide, writing nothing, whether and how a published handover can be resumed here: trust, lineage, source compatibility, uncommitted work at the origin
    Plan {
        /// A record id or a unique prefix; the one resumable handover when absent
        #[arg(long)]
        record: Option<String>,
    },
    /// Publish this checkout's newest handover as a signed record for another machine; refused when it carries a secret or a machine path
    Publish {
        /// A handover record's file name under .ai/local/state/handovers/; the newest when absent
        #[arg(long)]
        handover: Option<String>,
        /// The issue the work belongs to
        #[arg(long)]
        issue: Option<String>,
        /// The milestone it belongs to
        #[arg(long)]
        milestone: Option<String>,
    },
    /// Exchange published handovers with a git remote: fetch, merge as a union, push; an unreachable remote leaves what is pending pending
    Sync {
        /// The git remote; the current branch's, else origin, when absent
        #[arg(long)]
        remote: Option<String>,
    },
    /// Resume a published handover when its plan is ready: write it into this checkout's handovers, carry its decisions, and continue its line
    Resume {
        /// A record id or a unique prefix; the one resumable handover when absent
        #[arg(long)]
        record: Option<String>,
    },
}

#[derive(Debug, Args)]
/// `majordomus why`. The facets and the output shape are global, so they read the way a
/// person writes them — `why list --audience solo-builder` — and are declared once.
pub struct WhyArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `list`, `show`, `audiences`, `areas`, `diagnose` or `validate`; none lists.
    pub command: Option<WhyCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,

    /// Only moments this audience recognises
    #[arg(long, global = true)]
    pub audience: Option<String>,
    /// Only moments in this operational area
    #[arg(long, global = true)]
    pub area: Option<String>,
    /// Only moments carrying this tag
    #[arg(long, global = true)]
    pub tag: Option<String>,
    /// Only moments of this severity
    #[arg(long, global = true)]
    pub severity: Option<String>,
    /// Only moments of this frequency
    #[arg(long, global = true)]
    pub frequency: Option<String>,
    /// Only moments at this stage of work
    #[arg(long, global = true)]
    pub lifecycle: Option<String>,
    /// Only moments naming this capability of the executable
    #[arg(long, global = true)]
    pub capability: Option<String>,
    /// Only moments naming this command
    #[arg(long = "names-command", global = true)]
    pub names_command: Option<String>,
    /// Only the moments the homepage features
    #[arg(long, global = true)]
    pub featured: bool,
    /// Include drafts and deprecated moments, not only the public ones
    #[arg(long, global = true)]
    pub all: bool,
    /// Case-insensitive text over identities, titles, hooks, summaries, tags, aliases, signals, examples and bodies
    #[arg(long, short = 'q', global = true)]
    pub query: Option<String>,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus why`.
pub enum WhyCommand {
    /// Every operational moment, narrowed by any facet the catalogue reports
    List,
    /// One moment in full, with every relation derived from its metadata
    Show {
        /// The moment's id, which is also its slug and its route
        id: String,
    },
    /// Every audience, with the moments that name it
    Audiences,
    /// Every operational area, with the moments that fall under it
    Areas,
    /// What the symptoms you recognise imply: the areas they weigh towards and the mechanisms that answer them
    Diagnose {
        /// A signal id or a moment id; repeat for each one you recognise. Without any, the questionnaire is printed.
        #[arg(long = "signal")]
        signals: Vec<String>,
    },
    /// Every finding over the catalogue; exit 10 when any is an error
    Validate,
}

#[derive(Debug, Args)]
/// `majordomus devtask`. The output shape is global, so a person writes it where it reads
/// naturally — `devtask issue I0901 --format json` — and it is declared once.
pub struct DevtaskArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `issue` or `milestone`.
    pub command: DevtaskCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus devtask`.
pub enum DevtaskCommand {
    /// One issue as an executable development task, every field carrying where it came from
    Issue {
        /// The issue id, as the canonical model spells it. An id the model does not declare is answered, not refused.
        id: String,
        /// Answer from the canonical records alone, without consulting git — a deterministic answer that is the same on every machine
        #[arg(long = "no-git")]
        no_git: bool,
    },
    /// One milestone as an executable dependency graph: ready, blocked, parallelizable, critical blockers, cycles
    Milestone {
        /// The milestone id, as the canonical model spells it
        id: String,
    },
}

#[derive(Debug, Args)]
/// `majordomus distribution`.
pub struct DistributionArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// What to ask of the model; none shows it.
    pub command: Option<DistributionCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus distribution`.
pub enum DistributionCommand {
    /// The model: the install command, where an installation goes, and every declared target
    Show,
    /// Whether the advertised one-line installation works right now, and what is missing when it does not
    Status,
    /// Every invariant of the model and of the release records; exit 10 with each violation named
    Validate,
    /// Every declared target, one line each, with the artifact name it derives
    Targets,
    /// The release build matrix, as the release workflow reads it
    Matrix,
    /// The archive name and root directory a target and a tag derive
    Artifact {
        /// A target's id or its Rust target triple
        #[arg(long, value_name = "TARGET")]
        target: String,
        /// The tag, `v` and a version
        #[arg(long, value_name = "TAG")]
        tag: String,
    },
    /// Every recorded release, newest first, and the one an unpinned installation resolves to
    Releases,
    /// The public metadata one release record publishes, rendered from the record alone
    Metadata {
        /// A release record; the file the release pipeline writes under .ai/repo/releases/
        #[arg(long, value_name = "FILE")]
        record: PathBuf,
    },
    /// What this executable is: version, target triple, profile, commit
    Build,
}

#[derive(Debug, Args)]
/// `majordomus web`.
pub struct WebArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// What to do with the topology; none lists it.
    pub command: Option<WebCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,

    /// Only these surfaces, by discovered id (repeat or separate with commas)
    #[arg(long, value_delimiter = ',', global = true)]
    pub only: Vec<String>,

    /// Every surface except these, by discovered id
    #[arg(long, value_delimiter = ',', global = true)]
    pub exclude: Vec<String>,
}

#[derive(Debug, Subcommand)]
/// The reports this executable can render. Each reads evidence a run already produced and
/// writes a surface; none of them runs anything or decides what passed.
pub enum ReportCommand {
    /// The test run: the behavioural cases' report, and the crate's own totals
    Tests {
        /// The runner's TSV report (`MJ_TEST_REPORT=<file> bash test/run.sh`)
        #[arg(long)]
        suite: PathBuf,
        /// The output of `cargo test`, for its totals
        #[arg(long)]
        crate_output: Option<PathBuf>,
    },
    /// The benchmark run: a results document, or the accepted baseline
    Benchmarks {
        /// A results document from `majordomus bench`, or a baseline under the layer
        #[arg(long)]
        from: PathBuf,
    },
    /// The UI conformance audit, rendered as a section of the test surface (/tests/ui)
    Ui {
        /// A results document from `scripts/ui audit`
        #[arg(long)]
        from: PathBuf,
    },
    /// The UI itself, read once at this commit and written as static pages a publication
    /// carries at /ui (ADR 0141)
    UiSnapshot {
        /// The most pages to write: every screen and panel first, then what they link to
        #[arg(long, default_value_t = crate::web::report::snapshot::DEFAULT_LIMIT)]
        limit: usize,
        /// The most seconds to spend on the pages the screens link to; the screens and
        /// panels are written whatever they cost
        #[arg(long, default_value_t = crate::web::report::snapshot::DEFAULT_BUDGET_SECONDS)]
        budget_seconds: u64,
    },
    /// The Cockpit itself, read once at this commit and written as static pages a
    /// publication carries at /cockpit (ADR 0147)
    CockpitSnapshot {
        /// The most pages to write: every static route first, then the pages the UI's
        /// snapshot links to, then what those link to
        #[arg(long, default_value_t = crate::web::report::snapshot::DEFAULT_LIMIT)]
        limit: usize,
        /// The most seconds to spend on the pages the static routes link to; the routes
        /// themselves are written whatever they cost
        #[arg(long, default_value_t = crate::web::report::snapshot::DEFAULT_BUDGET_SECONDS)]
        budget_seconds: u64,
    },
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus web`.
pub enum WebCommand {
    /// Every discovered surface: id, kind, mount, producer
    List,
    /// Why each surface exists and where each of its values came from
    Explain {
        /// Only this surface; none explains every one
        id: Option<String>,
    },
    /// Check the topology's invariants; exit 10 on any error finding
    Validate {
        /// Also require every static surface's directory and index to exist
        #[arg(long)]
        artifacts: bool,
    },
    /// Write the resolved topology to the generated manifest
    Manifest,
    /// Render a generated report into its own surface under the generated web root
    Report {
        #[command(subcommand)]
        /// Which report to render.
        report: ReportCommand,
    },
    /// Compose every published surface into one publishable tree
    Compose {
        /// Where to write it; the default is target/site
        #[arg(long)]
        destination: Option<String>,
    },
}

#[derive(Debug, Args)]
/// `majordomus scope`.
pub struct ScopeArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    /// Repository-relative paths to judge; none prints the declaration and the tally
    pub paths: Vec<String>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,

    /// Exit 10 when any path given is out of the scope
    #[arg(long)]
    pub check: bool,
}

#[derive(Debug, Args)]
#[command(args_conflicts_with_subcommands = true)]
/// `majordomus bench`.
pub struct BenchArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `coverage` or `baseline`; none runs the benchmarks.
    pub command: Option<BenchCommand>,

    /// Only targets of this capability id, or whose key starts with this text
    pub id: Option<String>,

    /// Only this transport
    #[arg(long, value_enum, default_value_t = TransportArg::All)]
    pub transport: TransportArg,

    /// How much to measure
    #[arg(long, value_enum, default_value_t = ProfileArg::Quick)]
    pub profile: ProfileArg,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    /// Output shape
    pub format: OutputFormat,

    /// Compare with the accepted baseline of this platform under .ai/repo/benchmarks/rust/policy.yaml; exit 10 on a regression
    #[arg(long)]
    pub check: bool,

    /// Do not write the result under .ai/local/benchmarks/
    #[arg(long)]
    pub no_write: bool,
}

#[derive(Debug, Subcommand)]
/// The `bench` subcommands.
pub enum BenchCommand {
    /// Every required target and whether it is covered; the denominator is generated from the registry
    Coverage {
        #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
        /// Output shape
        format: OutputFormat,
        /// Exit 10 when any required target is missing or waived
        #[arg(long)]
        check: bool,
    },
    /// The accepted baseline of this platform under .ai/repo/benchmarks/rust/
    Baseline {
        #[command(subcommand)]
        /// What to do with it.
        command: BaselineCommand,
    },
}

#[derive(Debug, Subcommand)]
/// The `bench baseline` subcommands.
pub enum BaselineCommand {
    /// Run the benchmarks and record them as this platform's baseline (a reviewable, tracked file)
    Update {
        /// How much to measure
        #[arg(long, value_enum, default_value_t = ProfileArg::Full)]
        profile: ProfileArg,
        /// Record even from a dirty work tree
        #[arg(long)]
        allow_dirty: bool,
    },
}

/// The transports `bench` can be limited to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Default)]
pub enum TransportArg {
    /// Every target.
    #[default]
    All,
    /// Capabilities through the executor, in process.
    Direct,
    /// Capabilities through a real `majordomus mcp` child.
    Mcp,
    /// Capabilities over a real loopback socket.
    Http,
    /// The transports' own operations only.
    System,
}

/// How much `bench` measures.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Default)]
pub enum ProfileArg {
    /// Fast developer feedback: few samples.
    #[default]
    Quick,
    /// Stable evidence: many samples, many cold spawns.
    Full,
    /// Conservative: structural gates plus a modest measurement.
    Ci,
}

impl ProfileArg {
    /// The name the benchmark module knows.
    pub fn name(self) -> &'static str {
        match self {
            ProfileArg::Quick => "quick",
            ProfileArg::Full => "full",
            ProfileArg::Ci => "ci",
        }
    }
}

/// Output shape for commands that print to a person or a script. `mcp` speaks its own
/// protocol and does not use it; `mcp --inspect` does.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Default)]
pub enum OutputFormat {
    #[default]
    /// Lines for a person.
    Text,
    /// One JSON document, deterministic.
    Json,
}

/// How files are enumerated.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Default)]
pub enum DiscoveryMode {
    /// Tracked files, through the version-control index (the layer's contract); a layer none
    /// of which is tracked is read from the work tree
    #[default]
    Vcs,
    /// A walk of the work tree with the same glob semantics; untracked files included
    Filesystem,
}

/// The transports available. One today; the option exists so that a second one is an
/// addition, not a redesign.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Default)]
pub enum Transport {
    #[default]
    /// One JSON-RPC frame per line on stdin and stdout.
    Stdio,
}

/// Where and how the repository is read; shared by every command that reads it.
#[derive(Debug, Args, Default, Clone)]
pub struct RepoArgs {
    /// Start the search for the repository root here (default: the current directory)
    #[arg(long, value_name = "PATH", global = true)]
    pub repo: Option<PathBuf>,

    /// How declarative files are enumerated
    #[arg(long, value_enum, default_value_t = DiscoveryMode::Vcs, global = true)]
    pub discovery: DiscoveryMode,

    /// Refuse to proceed when any file of the layer carries an error diagnostic
    #[arg(long, global = true)]
    pub strict: bool,

    /// The tool distribution's share directory (kinds.yaml, schemas/); default: $MAJORDOMUS_SHARE,
    /// then the repository's own share/, then the one beside the executable
    #[arg(long, value_name = "DIR", global = true)]
    pub share: Option<PathBuf>,
}

#[derive(Debug, Args)]
/// `majordomus prs` (alias `pr`). Every subcommand but `refresh`, `drain` and `cleanup`
/// reads the last recorded forge observation and never reaches the network.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, OutputFormat, PrsArgs, PrsCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "pr", "explain", "12", "--format", "json"]).unwrap();
/// let Command::Prs(args) = cli.command else { panic!("not the prs command") };
/// let args: PrsArgs = args;
/// assert!(matches!(args.command, Some(PrsCommand::Explain { number: 12 })));
/// assert!(matches!(args.format, OutputFormat::Json));
/// ```
pub struct PrsArgs {
    #[command(flatten)]
    /// Where the repository is found.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// The subcommand; none is `status`.
    pub command: Option<PrsCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus prs`. `status`, `plan`, `explain` and `events` render the
/// recorded observation offline; `refresh`, `drain` and `cleanup` reach the forge, and a
/// drain is bounded by `--max` merges and, without `--dry-run`, holds the base branch's
/// integration lease while it acts.
/// # Example
///
/// ```
/// use majordomus_cli::cli::{Cli, Command, PrsCommand};
/// use clap::Parser;
/// let cli = Cli::try_parse_from(["majordomus", "prs", "drain", "--max", "3", "--refresh"]).unwrap();
/// let Command::Prs(args) = cli.command else { panic!("not the prs command") };
/// assert!(matches!(
///     args.command,
///     Some(PrsCommand::Drain { max: 3, dry_run: false, refresh: true, continuous: false, .. })
/// ));
/// // continuous: drain, wait, drain again — never together with a dry run
/// let cli = Cli::try_parse_from(["majordomus", "prs", "drain", "--continuous", "--interval", "60"]).unwrap();
/// let Command::Prs(args) = cli.command else { panic!() };
/// assert!(matches!(args.command, Some(PrsCommand::Drain { continuous: true, interval: 60, .. })));
/// assert!(Cli::try_parse_from(["majordomus", "prs", "drain", "--continuous", "--dry-run"]).is_err());
/// assert!(Cli::try_parse_from(["majordomus", "prs", "drain", "--continuous", "--interval", "5"]).is_err());
/// // a repair is a dry run unless it is applied, and never both
/// let cli = Cli::try_parse_from(["majordomus", "prs", "repair", "137"]).unwrap();
/// let Command::Prs(args) = cli.command else { panic!() };
/// assert!(matches!(args.command, Some(PrsCommand::Repair { apply: false, .. })));
/// assert!(Cli::try_parse_from(["majordomus", "prs", "repair", "137", "--apply", "--dry-run"]).is_err());
/// // with no subcommand it is `status`
/// let cli = Cli::try_parse_from(["majordomus", "prs"]).unwrap();
/// let Command::Prs(args) = cli.command else { panic!() };
/// assert!(args.command.is_none());
/// ```
pub enum PrsCommand {
    /// Every open pull request with its disposition, risk and reason, in rank order, from the last recorded observation; exit 10 when the observation is stale or absent
    Status,
    /// What the executor would do next: the next merge, the pull requests that need master brought in, and the lanes; nothing is changed
    Plan,
    /// Why one pull request is where it is: the revisions it was decided against, every piece of evidence, its rank and the factors behind it
    Explain {
        /// The pull request number.
        number: u64,
    },
    /// Observe the forge now (the GitHub CLI and one `git fetch`) and record the observation; the only read that reaches the network
    Refresh,
    /// Merge the next ready pull request, verify it landed, observe again, and repeat — at most `--max` merges; `--dry-run` decides without acting
    Drain {
        /// At most this many merges.
        #[arg(long, default_value_t = 1)]
        max: usize,
        /// Observe and decide, change nothing.
        #[arg(long)]
        dry_run: bool,
        /// When nothing is ready, bring master into the first pull request that needs it (a merge commit with the derived driver and a fresh derive, pushed as a fast-forward), so that its checks run against the current master
        #[arg(long)]
        refresh: bool,
        /// Drain, wait `--interval` seconds, and drain again until stopped, holding the lease throughout; each cycle is bounded by `--max` and observes before every step. Ctrl-C or SIGTERM lets the step in progress finish, then releases the lease; a second signal ends it at once. Never with `--dry-run`, and refused (exit 10) until the audit trail holds five verified merges since the last one that could not be verified: the last stage of the rollout (ADR 0101 §13)
        #[arg(long, conflicts_with = "dry_run")]
        continuous: bool,
        /// With `--continuous`: seconds between cycles, 30 to 900
        #[arg(long, default_value_t = 300, value_parser = clap::value_parser!(u64).range(crate::integration::drain::INTERVAL_SECONDS))]
        interval: u64,
        /// A merge an earlier drain could not verify stops every drain until a person has looked at it: this records that someone has (`failure_acknowledged` on the trail), then drains. Never with `--dry-run`
        #[arg(long, conflicts_with = "dry_run")]
        resume_after_failure: bool,
    },
    /// Close the pull requests whose work is provably on master already; without `--apply` it only lists them
    Cleanup {
        /// Close them: each one observed again first and closed only if it is still superseded at the head that was decided on.
        #[arg(long)]
        apply: bool,
        /// List them and close nothing: the default, spelled out.
        #[arg(long, conflicts_with = "apply")]
        dry_run: bool,
    },
    /// Bring master into one named pull request whose only conflict with it is over derived (`merge=derived`) files. Eligible only when the classification says it is behind master and its merge conflicts on no authored path; an authored conflict is refused, naming the files. A dry run by default, decided offline on the last recorded observation, like `status`. With `--apply` it takes the integration lease, observes the forge again, records the act on the trail first, and merges master in a scratch worktree, derives, commits and pushes a fast-forward leased on the observed head; it never merges into master. Exit 10 on a refusal or an absent observation, 12 when it could not act
    Repair {
        /// The pull request: its number, or its head branch.
        target: String,
        /// Act: take the lease, observe the forge again, record the act, merge, derive, commit and push. Without it nothing is changed, fetched or recorded.
        #[arg(long)]
        apply: bool,
        /// Decide and change nothing: the default, spelled out.
        #[arg(long, conflicts_with = "apply")]
        dry_run: bool,
    },
    /// The audit trail: every selection, merge, refusal, stale decision and closure this checkout's executor recorded
    Events,
    /// The trains of stacked pull requests, in landing order: each link's disposition, relation to master, prepared head under `refs/prep/<n>` (pushed or pending) and turn. Offline and read-only, from the last recorded observation; exit 10 when it is stale or absent
    Trains,
    /// One line for a session briefing: the last queue built in this checkout (open, by lane, the next merge, the starving), who holds the integration lease and whether it reaches across machines, the last merge, and the last refresh, failure or stale decision. Offline, decides no relation, and prints nothing where the forge was never observed
    Brief,
    /// Prove the non-mutating cycle moves nothing: snapshot origin's refs, the open pull requests, the audit trail, the lease and the local refs, run refresh, plan, drain --dry-run and cleanup (listing), snapshot again and compare; the refresh's fetched mirrors must equal what origin serves. Exit 10 naming what moved. Takes no flag: there is nothing to turn on
    ProveDryRun,
}

#[derive(Debug, Args)]
/// `majordomus offload`. The declaration is the repository's own unless `--declaration`
/// names a file; the output shape is global, as for `worktree`.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, OffloadArgs, OffloadCommand, OutputFormat};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "offload", "probe", "--format", "json", "--declaration", "hosts.yaml",
/// ])
/// .unwrap();
/// let Command::Offload(offload) = cli.command else { panic!("expected `offload`") };
/// let offload: OffloadArgs = offload;
/// assert!(matches!(offload.command, OffloadCommand::Probe));
/// assert_eq!(offload.format, OutputFormat::Json);
/// assert_eq!(offload.declaration.unwrap().to_str(), Some("hosts.yaml"));
///
/// // there is no default subcommand: an offload names what it does
/// assert!(Cli::try_parse_from(["majordomus", "offload"]).is_err());
/// ```
pub struct OffloadArgs {
    #[command(flatten)]
    /// Where the repository is found; its index is read for the declaration.
    pub repo: RepoArgs,

    /// Read this derive-offload declaration file instead of the repository's
    #[arg(long, value_name = "FILE", global = true)]
    pub declaration: Option<PathBuf>,

    #[command(subcommand)]
    /// The subcommand.
    pub command: OffloadCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus offload`: `hosts` reads the declaration and contacts
/// nobody, `probe` measures every declared host over ssh and names the one a derive would
/// take, and `derive` sends a worktree there and stages what the derive changed.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, OffloadCommand};
///
/// // with nothing named, the current directory is derived on the host the probe chooses
/// let cli = Cli::try_parse_from(["majordomus", "offload", "derive"]).unwrap();
/// let Command::Offload(offload) = cli.command else { panic!("expected `offload`") };
/// let OffloadCommand::Derive { worktree, host, keep } = offload.command else { panic!() };
/// assert_eq!((worktree.to_str(), host, keep), (Some("."), None, false));
///
/// let cli = Cli::try_parse_from(["majordomus", "offload", "derive", "../wt", "--host", "lundra", "--keep"]).unwrap();
/// let Command::Offload(offload) = cli.command else { panic!("expected `offload`") };
/// let OffloadCommand::Derive { worktree, host, keep } = offload.command else { panic!() };
/// assert_eq!((worktree.to_str(), host.as_deref(), keep), (Some("../wt"), Some("lundra"), true));
/// ```
pub enum OffloadCommand {
    /// The declared hosts and their limits, the queue and the remote layout, as the declaration states them; reads no host. A repository that declares none says so and exits 0
    Hosts,
    /// Measure every declared host — free space, derives running or waiting — and name the one a derive would take; exit 12 when none can take one
    Probe,
    /// Derive a worktree on a declared host and stage what it changed; nothing is committed or pushed. Exit 2 on an untracked file or an unresolved merge, 10 when the derive fails, 11 when it deletes a tracked file, 12 when no host can take it, 75 when the queue's wait runs out
    Derive {
        /// The worktree to derive
        #[arg(default_value = ".")]
        worktree: PathBuf,
        /// A declared host, by id or address, instead of the one the probe chooses
        #[arg(long, value_name = "HOST")]
        host: Option<String>,
        /// Keep the host's worktree after the derive (it is removed by default; a failed derive's is always kept)
        #[arg(long)]
        keep: bool,
    },
}

#[derive(Debug, Args)]
/// `majordomus worktree` (alias `wt`). The output shape is global, so it reads the way a
/// person writes it — `worktree list --format json` — and is declared once.
pub struct WorktreeArgs {
    #[command(flatten)]
    /// Where the repository is found. The index is not built: nothing about the topology is in it.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// The subcommand; none is `status`.
    pub command: Option<WorktreeCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus worktree`.
pub enum WorktreeCommand {
    /// Where this call is — branch, worktree, canonical or not, uncommitted work — and how many errors the whole topology carries; exit 10 when this worktree is out of place
    Status,
    /// Every registered worktree with its standing, one line each; exit 10 when the topology has an error
    List,
    /// The whole topology: repository, container, trunk, every worktree, every branch without a worktree, every diagnostic; exit 10 when it has an error
    Topology,
    /// Print the container every linked worktree belongs under, and nothing else: `cd "$(majordomus worktree root)"`
    Root,
    /// Print the canonical path of a branch, and nothing else: `cd "$(majordomus worktree path feature/x)"`. Derived from the name; the branch need not exist
    Path {
        /// The branch, full name
        branch: String,
    },
    /// One branch: its canonical path, whether it exists, what occupies the path, the worktree holding it, and what stands in the way
    Inspect {
        /// The branch, full name
        branch: String,
    },
    /// Create the canonical worktree of a branch. A branch that does not exist here is fetched from the trunk's remote and taken up when the remote has it; otherwise it is created from --base, else from the remote's trunk fetched now (the local trunk only when the remote cannot be read, and then said, with how far behind). The path is derived; none may be given
    Create {
        /// The branch, full name (`feature/improve-cli`)
        #[arg(value_name = "BRANCH", required_unless_present = "issue")]
        branch: Option<String>,

        /// Start a new branch from this ref. Never fetched: it must resolve locally
        #[arg(long, value_name = "REF")]
        base: Option<String>,

        /// Name the branch after this issue of .ai/repo/project/issues: `feature/<id>-<slug>`, the form the topology reads the issue back from
        #[arg(long, value_name = "ID", conflicts_with = "branch")]
        issue: Option<String>,
    },
    /// The canonical worktree of a branch: created when absent, answered when present, refused when the branch is checked out somewhere else
    Ensure {
        /// The branch, full name
        branch: String,

        /// Start a new branch from this ref (default: the trunk)
        #[arg(long, value_name = "REF")]
        base: Option<String>,
    },
    /// Bring every misplaced worktree to its canonical path, dirty state included, with a fingerprint taken before and after each move; --plan shows the steps and changes nothing
    Migrate {
        /// Show the plan and change nothing
        #[arg(long)]
        plan: bool,

        /// The same as --plan
        #[arg(long)]
        dry_run: bool,

        /// When a move crosses filesystems, copy the tree, repair git's link, verify the copy against a manifest of every entry, and only then remove the original
        #[arg(long)]
        allow_copy: bool,

        /// Only these branches
        #[arg(long, value_name = "BRANCH")]
        only: Vec<String>,

        /// Also move the scratch checkouts of sessions (under the temporary directory or .claude/worktrees), which are otherwise reported and left alone
        #[arg(long)]
        include_ephemeral: bool,
    },
    /// Every error of the topology, and nothing else; exit 10 when there is one
    Validate,
    /// Every diagnostic of the topology, errors, warnings and facts, each with its code and remedy; exit 10 when there is an error
    Doctor,
    /// May a mutation proceed from here? Exit 0 in a canonical worktree, in the primary checkout on the trunk, or detached; exit 10 with the reason otherwise. What the pre-commit hook asks
    Guard {
        /// Print nothing on success
        #[arg(long, short)]
        quiet: bool,
    },
    /// Drop git's registrations of worktrees whose directories are gone, and repair the administrative links of the ones that exist. Deletes no directory
    Repair {
        /// Report what would be dropped and change nothing
        #[arg(long)]
        dry_run: bool,
    },
    /// Remove one linked worktree by branch or path. Never the primary checkout, never a branch, never uncommitted work without --force
    Remove {
        /// An exact branch name or an exact path
        selector: String,

        /// Remove it even though it holds uncommitted work or is locked
        #[arg(long)]
        force: bool,
    },
    /// The branches merged into the trunk whose worktree is clean or absent: what could be removed. Removes nothing without --remove
    Cleanup {
        /// Remove the worktrees listed, each re-measured immediately before it goes: a branch
        /// ahead of its remote, uncommitted work, or a process working inside is refused and
        /// named. Branches are never deleted; the listing still says how.
        #[arg(long)]
        remove: bool,
    },
    /// Every linked worktree holding uncommitted work: how many paths, how old the oldest change, what holds it (an active task, an open episode, a process inside) and whether it is abandoned, with the command that would put it on a remote ref. Reads every worktree and writes none
    Uncommitted {
        /// Judge against this age instead of the policy's session.stranded_after (90s, 30m, 12h, 1d)
        #[arg(long, value_name = "DURATION")]
        older_than: Option<String>,
    },
    /// Every local branch, one per line, for a shell completion that wants the live set
    Branches {
        /// Only branches with no worktree
        #[arg(long)]
        without_worktree: bool,
    },
}

#[derive(Debug, Args)]
/// `majordomus mcp`.
pub struct McpArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    /// Print what would be served, and every diagnostic, then exit without serving
    #[arg(long)]
    pub inspect: bool,

    /// Output shape of --inspect
    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    pub format: OutputFormat,

    /// The transport to serve on
    #[arg(long, value_enum, default_value_t = Transport::Stdio)]
    pub transport: Transport,

    /// Serve this client alone: no shared server, no HTTP, no Swagger UI, no peers, and
    /// nothing written anywhere. The default is the shared server (below)
    #[arg(long)]
    pub standalone: bool,

    /// Interface the shared server binds when this process is the one that starts it;
    /// without it, the one `MAJORDOMUS_HTTP_HOST` names on this machine, and loopback
    /// (`127.0.0.1`) when that is unset
    #[arg(long, value_name = "HOST")]
    pub http_host: Option<String>,

    /// Port the shared server binds when this process starts it; without it, the port this
    /// checkout derives (8741 for the primary checkout). When it is taken, a free port is
    /// used instead and the URL is logged on stderr either way
    #[arg(long, value_name = "PORT")]
    pub http_port: Option<u16>,
}

/// The port of the HTTP projection a repository's primary checkout asks for: `serve`, and the
/// shared server `mcp` starts. A linked worktree asks for one of its own ([`checkout_port`]).
pub const DEFAULT_PORT: u16 = 8741;

/// The first port a linked worktree may derive, and how many there are: the block right
/// above [`DEFAULT_PORT`], so a worktree's address reads as a sibling of its repository's.
const LINKED_PORT_BASE: u16 = DEFAULT_PORT + 1;
const LINKED_PORT_SPAN: u16 = 999;

/// The port this checkout's server asks for first, the same on every start (I2702).
///
/// The primary checkout asks for [`DEFAULT_PORT`]. A linked worktree asks for a port derived
/// from its own identity ([`crate::repository::identity`]) within the block above it, so
/// that two checkouts of one repository ask for different ports and neither depends on which
/// started first. A port that is taken is still replaced by a free one and both are logged
/// (`http::server::bind_or_fallback`); the derivation decides what is asked, not what is had.
/// A checkout git cannot describe is treated as primary.
///
/// ```
/// use majordomus_cli::cli::{checkout_port, linked_port, DEFAULT_PORT};
/// let dir = tempfile::tempdir().unwrap();
/// // not a git checkout at all: the documented default
/// assert_eq!(checkout_port(dir.path()), DEFAULT_PORT);
/// // a linked worktree's port is a function of its identity alone
/// let a = linked_port("0123456789abcdef0123456789abcdef");
/// assert_eq!(a, linked_port("0123456789abcdef0123456789abcdef"));
/// assert_ne!(a, linked_port("fedcba9876543210fedcba9876543210"));
/// assert!(a > DEFAULT_PORT && a < DEFAULT_PORT + 1000);
/// ```
pub fn checkout_port(root: &std::path::Path) -> u16 {
    match crate::repository::git_identity(root) {
        Some(git) if git.linked => linked_port(&crate::repository::identity(root)),
        _ => DEFAULT_PORT,
    }
}

/// The port a linked worktree with this identity asks for: the identity's leading 32 bits,
/// reduced into the block above [`DEFAULT_PORT`].
///
/// ```
/// use majordomus_cli::cli::{linked_port, DEFAULT_PORT};
/// // the leading 32 bits choose the port: the rest of the identity does not move it
/// assert_eq!(linked_port("00000001"), DEFAULT_PORT + 2);
/// assert_eq!(linked_port("00000001ffffffff"), DEFAULT_PORT + 2);
/// // the block wraps rather than leaving it
/// assert!(linked_port("ffffffff") < DEFAULT_PORT + 1000);
/// // an identity with no leading hexadecimal word asks for the block's first port
/// assert_eq!(linked_port("not-hex"), DEFAULT_PORT + 1);
/// ```
pub fn linked_port(identity: &str) -> u16 {
    let lead = identity
        .get(..8)
        .and_then(|h| u32::from_str_radix(h, 16).ok())
        .unwrap_or(0);
    // the remainder is below LINKED_PORT_SPAN, which fits a u16
    LINKED_PORT_BASE + u16::try_from(lead % u32::from(LINKED_PORT_SPAN)).unwrap_or(0)
}

/// The interface a local server binds when nothing says otherwise.
pub const LOOPBACK_HOST: &str = "127.0.0.1";

/// The variable that names, for one machine, the interface a local server binds.
///
/// It is the machine's fact and not the repository's: a tracked setting would make every
/// clone of a public repository listen on its network, and a flag would have to be repeated
/// by every caller that starts a server — the session-start hook, `serve ensure`, each
/// client's `majordomus mcp`. A variable is inherited by all of them, and an environment
/// that does not set it keeps loopback.
pub const HTTP_HOST_ENV: &str = "MAJORDOMUS_HTTP_HOST";

/// Where the interface a local server binds came from.
///
/// ```
/// use majordomus_cli::cli::{resolve_http_host, HostOrigin};
/// // only an address the environment supplied is announced in the log as the variable's
/// assert_eq!(resolve_http_host(None, Some("0.0.0.0")).1, HostOrigin::Environment);
/// assert_ne!(HostOrigin::Flag, HostOrigin::Default);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HostOrigin {
    /// `--host` or `--http-host` on this command line.
    Flag,
    /// [`HTTP_HOST_ENV`] in this process's environment.
    Environment,
    /// Neither: [`LOOPBACK_HOST`].
    Default,
    /// [`HTTP_HOST_ENV`] named one, and the checkout is a linked worktree, which does not
    /// take it: [`LOOPBACK_HOST`] ([`checkout_http_host`]).
    LinkedWorktree,
}

/// The interface a local server binds: the flag when one was given, else what
/// [`HTTP_HOST_ENV`] names, else loopback. A variable that is set and blank is unset.
///
/// ```
/// use majordomus_cli::cli::{resolve_http_host, HostOrigin};
/// assert_eq!(
///     resolve_http_host(Some("10.0.0.1"), Some("0.0.0.0")),
///     ("10.0.0.1".to_string(), HostOrigin::Flag)
/// );
/// assert_eq!(
///     resolve_http_host(None, Some(" 0.0.0.0 ")),
///     ("0.0.0.0".to_string(), HostOrigin::Environment)
/// );
/// assert_eq!(
///     resolve_http_host(None, Some("  ")),
///     ("127.0.0.1".to_string(), HostOrigin::Default)
/// );
/// assert_eq!(
///     resolve_http_host(None, None),
///     ("127.0.0.1".to_string(), HostOrigin::Default)
/// );
/// ```
pub fn resolve_http_host(flag: Option<&str>, environment: Option<&str>) -> (String, HostOrigin) {
    if let Some(host) = flag {
        return (host.to_string(), HostOrigin::Flag);
    }
    match environment.map(str::trim).filter(|h| !h.is_empty()) {
        Some(host) => (host.to_string(), HostOrigin::Environment),
        None => (LOOPBACK_HOST.to_string(), HostOrigin::Default),
    }
}

/// [`resolve_http_host`] against this process's environment: what `serve`, `mcp` and
/// `server.status` all read, so that the address a server binds and the address the status
/// calls desired cannot disagree.
///
/// ```
/// use majordomus_cli::cli::{local_http_host, HostOrigin};
/// // a flag is the answer whatever the environment holds
/// assert_eq!(
///     local_http_host(Some("127.0.0.1")),
///     ("127.0.0.1".to_string(), HostOrigin::Flag)
/// );
/// ```
pub fn local_http_host(flag: Option<&str>) -> (String, HostOrigin) {
    let environment = std::env::var(HTTP_HOST_ENV).ok();
    let (host, origin) = resolve_http_host(flag, environment.as_deref());
    if origin == HostOrigin::Environment {
        tracing::info!(
            host = %host,
            "binding {host}: {HTTP_HOST_ENV} names it for this machine"
        );
    }
    (host, origin)
}

/// The machine's interface for one checkout: a linked worktree does not take the one
/// [`HTTP_HOST_ENV`] names. The variable is the machine's face on its network, and that
/// face is the repository's primary server — the one other machines dial and whose mesh
/// the worktrees cooperate through; a worktree's own server serves its own sessions, and
/// a variable inherited by every shell would otherwise put each of them on the network
/// beside it. A flag still binds where it says, because a person typed it.
///
/// ```
/// use majordomus_cli::cli::{checkout_http_host, HostOrigin};
/// // a directory that is not a linked worktree reads the machine's resolution unchanged
/// let plain = tempfile::tempdir().unwrap();
/// assert_eq!(
///     checkout_http_host(Some("10.0.0.1"), plain.path()),
///     ("10.0.0.1".to_string(), HostOrigin::Flag)
/// );
/// ```
pub fn checkout_http_host(flag: Option<&str>, root: &std::path::Path) -> (String, HostOrigin) {
    let environment = std::env::var(HTTP_HOST_ENV).ok();
    let linked = crate::repository::git_identity(root).is_some_and(|g| g.linked);
    let (host, origin) = resolve_checkout_http_host(flag, environment.as_deref(), linked);
    match origin {
        HostOrigin::Environment => tracing::info!(
            host = %host,
            "binding {host}: {HTTP_HOST_ENV} names it for this machine"
        ),
        HostOrigin::LinkedWorktree => tracing::info!(
            "binding {LOOPBACK_HOST}: {HTTP_HOST_ENV} names the machine's interface, and a \
             linked worktree leaves it to the primary checkout's server (--host binds one)"
        ),
        _ => {}
    }
    (host, origin)
}

/// [`resolve_http_host`] for a checkout that is, or is not, a linked worktree: an
/// environment's interface becomes loopback in a linked worktree; a flag never changes.
///
/// ```
/// use majordomus_cli::cli::{resolve_checkout_http_host, HostOrigin};
/// assert_eq!(
///     resolve_checkout_http_host(None, Some("0.0.0.0"), true),
///     ("127.0.0.1".to_string(), HostOrigin::LinkedWorktree)
/// );
/// assert_eq!(
///     resolve_checkout_http_host(None, Some("0.0.0.0"), false),
///     ("0.0.0.0".to_string(), HostOrigin::Environment)
/// );
/// assert_eq!(
///     resolve_checkout_http_host(Some("0.0.0.0"), None, true),
///     ("0.0.0.0".to_string(), HostOrigin::Flag)
/// );
/// assert_eq!(
///     resolve_checkout_http_host(None, None, true),
///     ("127.0.0.1".to_string(), HostOrigin::Default)
/// );
/// ```
pub fn resolve_checkout_http_host(
    flag: Option<&str>,
    environment: Option<&str>,
    linked: bool,
) -> (String, HostOrigin) {
    match resolve_http_host(flag, environment) {
        (_, HostOrigin::Environment) if linked => {
            (LOOPBACK_HOST.to_string(), HostOrigin::LinkedWorktree)
        }
        resolved => resolved,
    }
}

#[derive(Debug, Args)]
/// `majordomus serve`.
pub struct ServeArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `status`, `ensure` or `stop`; none serves.
    pub command: Option<ServeCommand>,

    /// Interface to bind; without it, the one `MAJORDOMUS_HTTP_HOST` names on this machine,
    /// and loopback (`127.0.0.1`) when that is unset
    #[arg(long, value_name = "HOST")]
    pub host: Option<String>,

    /// Port to bind; without it, the port this checkout derives (8741 for the primary
    /// checkout); 0 picks a free one and the address is logged on stderr
    #[arg(long)]
    pub port: Option<u16>,

    /// When the port is taken, bind a free one instead and log both; without this a taken port is an error
    #[arg(long)]
    pub fallback: bool,

    /// Stop when no peer has been attached for this many seconds; 0 runs until stopped. What a server no client owns is started with
    #[arg(long, value_name = "SECONDS", default_value_t = 0)]
    pub idle: u64,

    /// Bind the address this deployment object declares (`.ai/repo/deployments/<ID>.yaml`)
    /// instead of the local default. What a hosted process is started with; the address is
    /// the object's, not this command line's
    #[arg(long, value_name = "ID", conflicts_with_all = ["host", "port"])]
    pub deployment: Option<String>,
}

/// How long a server started by `serve ensure` outlives its last peer, in seconds: long
/// enough that an agent's next attach finds it, short enough that a checkout nobody works
/// in does not keep a process. The default of `server.idle_seconds:` in
/// `.ai/repo/policy.yaml`, which a repository may declare beside the other server timings
/// (`lease::Timings::idle`); `--idle` on the command line overrides both (I2701).
pub const DEFAULT_IDLE_SECONDS: u64 = 900;

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus serve`: the server's lifecycle as something a person or a
/// hook converges on rather than remembers. `status` is the projection of `server.status`;
/// `ensure` and `stop` are process lifecycle, which no capability served by the process
/// could be.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::capability::builtin::Checkouts;
/// use majordomus_cli::cli::{Cli, Command, ServeCommand};
///
/// let cli = Cli::try_parse_from(["majordomus", "serve", "ensure", "--idle", "5"]).unwrap();
/// let Command::Serve(args) = cli.command else { panic!("serve") };
/// assert!(matches!(args.command, Some(ServeCommand::Ensure { idle: Some(5), .. })));
///
/// // without `--idle`, `ensure` names no idle life: the declared `server.idle_seconds:`
/// // decides, and `DEFAULT_IDLE_SECONDS` when nothing is declared (I2701)
/// let cli = Cli::try_parse_from(["majordomus", "serve", "ensure"]).unwrap();
/// let Command::Serve(args) = cli.command else { panic!("serve") };
/// assert!(matches!(args.command, Some(ServeCommand::Ensure { idle: None, .. })));
///
/// // without a subcommand, `serve` serves; the defaults are the documented ones
/// let cli = Cli::try_parse_from(["majordomus", "serve"]).unwrap();
/// let Command::Serve(args) = cli.command else { panic!("serve") };
/// assert!(args.command.is_none() && args.idle == 0 && !args.fallback);
///
/// // `status` asks the capability's own question, and the flag is that input's field:
/// // saying nothing asks about every checkout of the repository, as it always did
/// let cli = Cli::try_parse_from(["majordomus", "serve", "status"]).unwrap();
/// let Command::Serve(args) = cli.command else { panic!("serve") };
/// assert!(matches!(args.command, Some(ServeCommand::Status { checkouts: Checkouts::Repository, .. })));
/// let cli = Cli::try_parse_from(["majordomus", "serve", "status", "--checkouts", "this"]).unwrap();
/// let Command::Serve(args) = cli.command else { panic!("serve") };
/// assert!(matches!(args.command, Some(ServeCommand::Status { checkouts: Checkouts::This, .. })));
/// ```
pub enum ServeCommand {
    /// Where this checkout's server stands — absent, starting, ready, outdated or stale — and every server of the repository
    Status {
        /// Which checkouts to answer for: every checkout of the repository, or this one
        /// alone — which reads no other checkout's lease and probes no other server
        #[arg(long, value_enum, default_value_t = Checkouts::default())]
        checkouts: Checkouts,
        /// Output shape
        #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
        format: OutputFormat,
    },
    /// Make sure a ready server serves this checkout: start one when there is none or the lease is stale, wait for one that is starting, and report where it stands
    Ensure {
        /// The port the started server asks for first, without it the one this checkout
        /// derives (8741 for the primary checkout); a taken one is replaced by a free one
        #[arg(long)]
        port: Option<u16>,
        /// The started server stops when no peer has been attached for this many seconds;
        /// without it, the policy's declared `server.idle_seconds`, 900 when none is declared
        #[arg(long, value_name = "SECONDS")]
        idle: Option<u64>,
        /// How long to wait for a server to become ready before reporting what stands
        #[arg(long, value_name = "SECONDS", default_value_t = 20)]
        wait: u64,
        /// Output shape
        #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
        format: OutputFormat,
    },
    /// Stop this checkout's server — the one its lease names, when it answers for this checkout — and wait for that server's lease to go, which another process taking the checkout over does not undo
    Stop {
        /// How long to wait for the server to end
        #[arg(long, value_name = "SECONDS", default_value_t = 10)]
        wait: u64,
    },
}

#[derive(Debug, Args)]
/// `majordomus capabilities`.
pub struct CapabilitiesArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// Which introspection.
    pub command: CapabilitiesCommand,
}

/// Which schema of a capability to print.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Default)]
pub enum SchemaSide {
    #[default]
    /// The schema of the input.
    Input,
    /// The schema of the output.
    Output,
}

#[derive(Debug, Subcommand)]
/// The introspection commands; `list` and `describe` dispatch through the registry's CLI exposure.
pub enum CapabilitiesCommand {
    /// Every capability, one line each, with its projections
    List {
        /// Only this kind: query or resource
        #[arg(long)]
        kind: Option<String>,
        /// Only capabilities exposed through this projection: mcp, http or cli
        #[arg(long)]
        exposure: Option<String>,
        #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
        /// Output shape.
        format: OutputFormat,
    },
    /// One capability by canonical id: schemas, provenance, every projection
    Describe {
        /// The canonical id.
        id: String,
        #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
        /// Output shape.
        format: OutputFormat,
    },
    /// The canonical input or output JSON Schema of one capability
    Schema {
        /// The canonical id.
        id: String,
        #[arg(long, value_enum, default_value_t = SchemaSide::Input)]
        /// Input or output.
        side: SchemaSide,
    },
    /// Where each capability is projected, and every claim its surface does not answer
    Projections {
        /// Only capabilities composed in this module
        #[arg(long)]
        module: Option<String>,
        /// Only the capabilities whose declared exposures are not all answered
        #[arg(long)]
        unmet: bool,
        #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
        /// Output shape.
        format: OutputFormat,
    },
    /// Build the registry and every projection; exit 10 with every violation named
    Validate,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum, Default)]
/// What `generate` writes.
pub enum GenerateTarget {
    #[default]
    /// Every target.
    All,
    /// `docs/generated/openapi.{json,yaml}`.
    Openapi,
    /// `docs/generated/capabilities.md`, `docs/generated/modules/<id>.md` and
    /// `docs/generated/cli.{md,json,yaml}`.
    Docs,
    /// `docs/generated/benchmarks.{md,json,yaml}`: every benchmark target and the coverage
    Benchmarks,
    /// `docs/generated/registry.{json,yaml}`: the builtin registry as data
    Registry,
    /// The shell tool's allow-lists under share/allow, derived from the schemas
    Allow,
    /// The provider bootstraps the policy declares (AGENTS.md, CLAUDE.md, ...)
    Providers,
    /// The files Zed and Google Antigravity read: `.agents/skills/<id>/SKILL.md` for every
    /// active skill, and `.zed/tasks.json` from the tracked justfile
    Editors,
    /// site/data/registry/registry.json, the registry dataset the site renders
    Site,
    /// docs/generated/artifacts.{json,yaml,md}: the index of every generated artifact
    Manifest,
    /// The installer, the installation guide, the release build matrix and the public
    /// release metadata, from share/distribution.yaml and .ai/repo/releases/; and
    /// share/version.txt, the version the shell tool ships with, from the crate manifest
    Distribution,
    /// `docs/generated/web.json`: the resolved web topology the site's route reference renders
    Web,
    /// `docs/generated/changelog.{json,yaml,md}`: the changelog composed from the layer's
    /// release records, its decisions and the repository's commits
    Changelog,
    /// deploy/Dockerfile and .dockerignore, from the deployment objects
    Deployment,
    /// docs/generated/graph.json and its schema: the composed graph as data
    Graph,
    /// The design system's projections, from share/design/tokens.yaml: the stylesheets
    /// both Tailwind builds import, the tokens and the declaration compiled into the crate,
    /// every copy of the brand, site/data/registry/design.json and docs/generated/design.*
    Design,
    /// docs/generated/economics.{json,yaml,md}: the token-economics evidence and its report,
    /// computed from the recorded benchmark runs by the one calculator
    Economics,
}

#[derive(Debug, Args)]
/// `majordomus generate`.
pub struct GenerateArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    /// What to generate
    #[arg(value_enum, default_value_t = GenerateTarget::All)]
    pub target: GenerateTarget,

    /// Compare with what is on disk and exit 10 when stale; write nothing
    #[arg(long)]
    pub check: bool,

    /// Write under this directory instead of the repository root (docs/generated is appended)
    #[arg(long, value_name = "DIR")]
    pub out: Option<PathBuf>,
}

#[derive(Debug, Args)]
/// `majordomus commands`.
pub struct CommandsArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// What to ask of the graph; none lists it.
    pub command: Option<CommandsCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// What `majordomus commands` can be asked.
pub enum CommandsCommand {
    /// Every command, one line each: what it is, what running it changes, and where it is projected
    List(CommandsListArgs),
    /// One command in full: its arguments, its effect, what it needs, and every surface that carries it
    Show(CommandsShowArgs),
    /// Why one command appears where it does: the declaration it came from, the policy that placed it, and the reason for every surface that withholds it
    Explain(CommandsShowArgs),
    /// The whole graph as one document, with its fingerprint and every diagnostic
    Graph(CommandsGraphArgs),
    /// Materialise the workflow bridge from the graph, and refresh the cache the completion reads; writes nothing when the graph has not changed
    Bridge(CommandsBridgeArgs),
}

#[derive(Debug, Args)]
/// `majordomus commands list`.
pub struct CommandsListArgs {
    /// Only the commands of this program
    #[arg(long, value_enum)]
    pub origin: Option<CommandOrigin>,

    /// Only the commands whose effect is at most this
    #[arg(long, value_enum)]
    pub effect: Option<CommandEffect>,

    /// Only the commands matching this text, in their invocation, summary, tags or identity
    #[arg(long, value_name = "TEXT")]
    pub search: Option<String>,
}

#[derive(Debug, Args)]
/// `majordomus commands show` and `explain`.
pub struct CommandsShowArgs {
    /// The command's identity, `executable.worktree.status`
    pub id: String,
}

#[derive(Debug, Args)]
/// `majordomus commands graph`.
pub struct CommandsGraphArgs {
    /// Exit 10 when the graph carries an error
    #[arg(long)]
    pub check: bool,
}

#[derive(Debug, Args)]
/// `majordomus commands bridge`.
pub struct CommandsBridgeArgs {
    /// Exit 10 when the materialised bridge is not the one this graph projects; write nothing
    #[arg(long)]
    pub check: bool,
}

/// Which program a command belongs to, as a filter.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum CommandOrigin {
    /// This executable
    Executable,
    /// The shell tool, bin/majordomus
    Tool,
    /// A workflow the repository declares
    Workflow,
}

/// What running a command changes, as a filter.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum CommandEffect {
    /// Reads and answers
    ReadOnly,
    /// Writes only what no commit carries
    LocalMutation,
    /// Writes tracked files
    RepositoryMutation,
    /// Reaches the network with an effect
    NetworkMutation,
    /// Removes something
    Destructive,
}

#[derive(Debug, Args)]
/// `majordomus completion`.
pub struct CompletionArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// What to do; none prints the integration for the current shell.
    pub command: Option<CompletionCommand>,
}

#[derive(Debug, Subcommand)]
/// What `majordomus completion` can be asked.
pub enum CompletionCommand {
    /// The candidates for one command line, from the command graph. What a shell adapter calls on every TAB
    Query(CompletionQueryArgs),
    /// The shell integration to load once, which carries no command of its own and asks this executable for every candidate
    Init(CompletionInitArgs),
    /// Put that integration into the shell's startup file, between managed markers, so that no one maintains it by hand
    Install(CompletionInstallArgs),
}

#[derive(Debug, Args)]
/// `majordomus completion query`.
pub struct CompletionQueryArgs {
    /// Which surface the words are spelled for
    #[arg(long, value_enum, default_value_t = CompletionSurface::Cli)]
    pub surface: CompletionSurface,

    /// The index of the word the cursor is in; the default is a new word after the last
    #[arg(long, value_name = "N")]
    pub cursor: Option<usize>,

    /// Output shape
    #[arg(long, value_enum, default_value_t = OutputFormat::Text)]
    pub format: OutputFormat,

    /// The words of the command line, the program's own name first
    #[arg(trailing_var_arg = true, value_name = "WORD")]
    pub words: Vec<String>,
}

#[derive(Debug, Args)]
/// `majordomus completion init`.
pub struct CompletionInitArgs {
    /// Which shell to print the integration for
    #[arg(long, value_enum, default_value_t = CompletionShell::Zsh)]
    pub shell: CompletionShell,
}

/// The arguments of `completion install`.
#[derive(Debug, clap::Args)]
pub struct CompletionInstallArgs {
    /// Which shell to install for; decides the startup file when --rc is not given
    #[arg(long, value_enum, default_value_t = CompletionShell::Zsh)]
    pub shell: CompletionShell,
    /// The startup file to write, instead of the shell's usual one
    #[arg(long, value_name = "PATH")]
    pub rc: Option<std::path::PathBuf>,
    /// Take the block out again, leaving the rest of the file as it was
    #[arg(long)]
    pub remove: bool,
    /// Say what would change and write nothing
    #[arg(long)]
    pub dry_run: bool,
}

/// The surface a completion request is spelled for.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum CompletionSurface {
    /// The command line of either program
    Cli,
    /// The workflow runner
    Workflow,
}

/// A shell the integration is printed for.
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum CompletionShell {
    /// zsh
    Zsh,
    /// bash
    Bash,
    /// fish
    Fish,
}

#[derive(Debug, Args)]
/// `majordomus devcontext`. Every subcommand is the projection of one `devcontext.*`
/// capability; the request flags are declared once and shared by `compile` and `explain`.
///
/// `--format` is `global`, so it parses where a person writes it rather than only before
/// the subcommand, and the group itself runs nothing: every runnable path here is a
/// capability's.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, DevcontextArgs, DevcontextCommand, OutputFormat};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "devcontext", "compile", "--intent", "explain the budget",
///     "--budget-tokens", "4000", "--format", "json",
/// ])
/// .unwrap();
/// let args: DevcontextArgs = match cli.command {
///     Command::Devcontext(args) => args,
///     other => panic!("expected `devcontext`, parsed {other:?}"),
/// };
/// // written after the subcommand and picked up all the same
/// assert!(matches!(args.format, OutputFormat::Json));
/// let DevcontextCommand::Compile(request) = args.command else { panic!("compile") };
/// assert_eq!(request.intent.as_deref(), Some("explain the budget"));
/// assert_eq!(request.budget_tokens, Some(4000));
///
/// // the group has no behaviour of its own, so it refuses to be run bare
/// assert!(Cli::try_parse_from(["majordomus", "devcontext"]).is_err());
/// ```
pub struct DevcontextArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// `compile`, `explain` or `policy`.
    pub command: DevcontextCommand,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// What to ask of the context compiler: compile an answer, ask why one identifier is or is
/// not in it, or read the rules the compiler decides by.
///
/// `Explain` takes the identifier positionally and then the same request flags as
/// `Compile`, because the question it answers is *about* a compiled answer — "why is this
/// not in it" is only meaningful against the request that left it out. `Policy` takes
/// nothing: it is the compiler's own table, not a question about a repository.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, DevcontextCommand};
///
/// let parse = |argv: &[&str]| {
///     let cli = Cli::try_parse_from(argv).unwrap();
///     let Command::Devcontext(args) = cli.command else { panic!("devcontext") };
///     args.command
/// };
///
/// // the identifier is positional and the request flags follow it, so the budget the
/// // judgement is made under is part of the question
/// let explain = parse(&[
///     "majordomus", "devcontext", "explain", "majordomus://rule/x@1", "--max-depth", "1",
/// ]);
/// let DevcontextCommand::Explain { uri, request } = explain else { panic!("explain") };
/// assert_eq!(uri, "majordomus://rule/x@1");
/// assert_eq!(request.max_depth, Some(1));
///
/// // `policy` is about the compiler and not about a request, so it accepts no request flag
/// assert!(matches!(
///     parse(&["majordomus", "devcontext", "policy"]),
///     DevcontextCommand::Policy
/// ));
/// assert!(
///     Cli::try_parse_from(["majordomus", "devcontext", "policy", "--intent", "x"]).is_err(),
///     "the rules do not depend on what is being asked about"
/// );
/// ```
pub enum DevcontextCommand {
    /// Compile the context for a piece of work: every selected object with its provenance, the reason and the confidence, everything left out with the reason, what was deduplicated, and the per-tier budget; exit 10 when what may not be dropped already exceeds the budget
    Compile(DevcontextRequest),
    /// Why one canonical identifier is or is not in the context a request compiles to
    Explain {
        /// The canonical identifier, `majordomus://<kind>/<identity>`
        uri: String,
        #[command(flatten)]
        /// The request to judge it under.
        request: DevcontextRequest,
    },
    /// The compiler's own rules: the tiers, every edge of the composed graph and what is done with it, the selectors, the defaults
    Policy,
}

#[derive(Debug, Clone, Args)]
/// What to compile a context about; every flag is optional, and naming nothing is a
/// legitimate request.
///
/// This is the command-line half of
/// [`CompileInput`](crate::devcontext::CompileInput), field for field, which is why the
/// repeated flags are `--path` and `--uri` singular while the fields behind them are
/// plural: a person adds one path at a time, and the request holds the set. A request that
/// names nothing still compiles — to the governance the layer applies to everything, plus
/// what the last session left.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, DevcontextCommand, DevcontextRequest};
///
/// // one type behind both subcommands, which is why `explain` can judge an identifier
/// // under exactly the request `compile` would have used
/// let request_of = |argv: &[&str]| -> DevcontextRequest {
///     let cli = Cli::try_parse_from(argv).unwrap();
///     let Command::Devcontext(args) = cli.command else { panic!("devcontext") };
///     match args.command {
///         DevcontextCommand::Compile(request) => request,
///         DevcontextCommand::Explain { request, .. } => request,
///         DevcontextCommand::Policy => panic!("`policy` takes no request"),
///     }
/// };
///
/// let compiling = request_of(&[
///     "majordomus", "devcontext", "compile",
///     "--path", "apps/majordomus-cli/src", "--path", "lib",
///     "--uri", "majordomus://adr/0052",
///     "--floor", "0.4", "--all-blocking-rules",
/// ]);
///
/// // repeated singular flags accumulate into the set the compiler seeds from
/// assert_eq!(compiling.paths, ["apps/majordomus-cli/src", "lib"]);
/// assert_eq!(compiling.uris, ["majordomus://adr/0052"]);
/// assert_eq!(compiling.floor, Some(0.4));
/// assert!(compiling.all_blocking_rules);
///
/// // the same flags reach `explain`, after its positional identifier
/// let explaining = request_of(&[
///     "majordomus", "devcontext", "explain", "majordomus://adr/0052", "--max-depth", "1",
/// ]);
/// assert_eq!(explaining.max_depth, Some(1));
///
/// // and nothing is required: the smallest true context there is
/// let silent = request_of(&["majordomus", "devcontext", "compile"]);
/// assert!(silent.issue.is_none() && silent.paths.is_empty());
/// assert!(!silent.all_blocking_rules && silent.floor.is_none());
/// ```
pub struct DevcontextRequest {
    /// An issue id (`I0301`) or its canonical identifier
    #[arg(long)]
    pub issue: Option<String>,
    /// A milestone id or slug, or its canonical identifier
    #[arg(long)]
    pub milestone: Option<String>,
    /// What the session is trying to do, in words; the only input the compiler infers from
    #[arg(long)]
    pub intent: Option<String>,
    /// A repository-relative path the work touches; repeat for each
    #[arg(long = "path")]
    pub paths: Vec<String>,
    /// A canonical identifier to seed with directly; repeat for each
    #[arg(long = "uri")]
    pub uris: Vec<String>,
    /// The ceiling in estimated tokens
    #[arg(long)]
    pub budget_tokens: Option<u64>,
    /// How far from a seed the walk goes
    #[arg(long)]
    pub max_depth: Option<usize>,
    /// Relevance below which an entry is reported rather than given, between 0 and 1
    #[arg(long)]
    pub floor: Option<f64>,
    /// Every blocking rule of the layer, not only the ones the work reaches
    #[arg(long)]
    pub all_blocking_rules: bool,
}

// ------------------------------------------------------------------ the command line as data
//
// clap is the one declaration of the command line: every command, argument, default and
// value set above. What clap cannot carry — the examples a reader copies — is declared
// below, in the same file, in typed Rust. Both halves are walked into `CommandDoc` by
// `cli::tree()`, and every projection of the native command line is a rendering of that
// tree: `--help`, `docs/generated/cli.md`, `docs/generated/cli.json`, the site dataset and
// the routes under /docs/cli/. `cli::validate` is the contract that keeps the two halves
// complete, and the example tests execute exactly the argv shown below.

pub mod docs;
pub mod local;
mod validate;

pub use docs::tree;
pub use docs::{
    document, render, route, ArgDoc, CliDocument, CommandDoc, ExampleView, PossibleValueDoc,
    SetupView, DECLARATION, ROUTE_PREFIX, SCHEMA,
};
pub use validate::{parse, validate, Violation};

/// What an example's run must show for the example to be true. Small on purpose: enough to
/// prove that the command line printed in the documentation does what the documentation
/// says, and no more. A new variant is a new kind of evidence, not a new test framework.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Expect {
    /// The command exits 0.
    Success,
    /// The command exits with exactly this code.
    ExitCode(u8),
    /// The command exits 0 and its stdout contains every fragment.
    StdoutContains(&'static [&'static str]),
    /// The command exits 0 and its stdout is one JSON document in which every JSON Pointer
    /// resolves (RFC 6901, `/registry/fingerprint`).
    Json(&'static [&'static str]),
    /// A server: it starts, logs the address it bound, answers a GET on this path with a
    /// 2xx status, and exits 0 when it is asked to stop.
    HttpReady(&'static str),
    /// The stdio MCP server: it starts, answers `initialize` and `tools/list` with JSON-RPC
    /// frames on stdout and nothing else, and exits 0 at end of input.
    McpReady,
}

impl Expect {
    /// What the example test asserts, in one phrase, for the reference to print.
    pub fn describe(self) -> String {
        match self {
            Expect::Success => "exits 0".to_string(),
            Expect::ExitCode(c) => format!("exits {c}"),
            Expect::StdoutContains(f) => format!("exits 0; prints {}", f.join(", ")),
            Expect::Json(p) => format!(
                "exits 0; prints one JSON document carrying {}",
                p.join(", ")
            ),
            Expect::HttpReady(path) => {
                format!("binds a port, answers GET {path}, exits 0 when stopped")
            }
            Expect::McpReady => {
                "answers initialize and tools/list on stdio, and exits 0 at end of input"
                    .to_string()
            }
        }
    }
}

/// One documented example of one command: what it shows, the argument vector it runs, what
/// must happen when it runs, and anything that has to be done first. The argument vector is
/// the canonical form; the command line a reader copies is rendered from it, never written
/// out a second time.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ExampleDoc {
    /// Unique across the whole command line; the anchor of the example on its page.
    pub id: &'static str,
    /// One line: what this example shows.
    pub title: &'static str,
    /// What it does and what comes back.
    pub description: &'static str,
    /// The arguments, without the executable's own name.
    pub argv: &'static [&'static str],
    /// Commands run in the same repository before it, in order; usually empty.
    pub setup: &'static [&'static [&'static str]],
    /// What the run must show.
    pub expect: Expect,
}

/// The examples of one command, by the command's path without `majordomus`. The root is the
/// empty string. `cli::validate` refuses a set whose command the clap declaration does not
/// have, a command that can be run and has no set, and an example whose argv this crate's
/// own parser does not accept.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommandExamples {
    /// `bench baseline update`; the empty string is the root.
    pub command: &'static str,
    /// Its examples, in the order the reference prints them.
    pub examples: &'static [ExampleDoc],
}

/// Every documented example of the native command line.
///
/// This is the canonical declaration: `docs/generated/cli.md`, `docs/generated/cli.json`,
/// the site dataset and every page under `/docs/cli/` render these entries, and
/// `apps/majordomus-cli/tests/cli_examples.rs` runs them against the built executable in a
/// disposable repository. Adding a command without adding its example does not pass
/// `cli::validate`, and therefore does not pass the crate's tests or CI.
pub const EXAMPLES: &[CommandExamples] = &[
    CommandExamples {
        command: "commit",
        examples: &[ExampleDoc {
            id: "commit-default-plan",
            title: "What this tree would commit, and why",
            description: "`commit` with nothing after it plans, because that is what a person wants when they ask about committing. The branch, its upstream and divergence, what is staged and what is not, and the commits the history's own scoping supports — each with the evidence for it rather than an assertion. A clean tree says so.",
            argv: &["commit"],
            setup: &[],
            expect: Expect::StdoutContains(&["branch", "tree", "fingerprint"]),
        }],
    },
    CommandExamples {
        command: "commit plan",
        examples: &[
            ExampleDoc {
                id: "commit-plan",
                title: "The plan, with the fingerprint that makes it refusable",
                description: "The fingerprint is the repository, the worktree, HEAD and a hash over every change with its stage. A caller holding a plan compares it with the tree in front of it and is told what moved — `HEAD moved from a1b2c3d4e to e4f5a6b70` — rather than being told nothing and committing somebody else's staged work.",
                argv: &["commit", "plan"],
                setup: &[],
                expect: Expect::StdoutContains(&["fingerprint", "nothing staged"]),
            },
            ExampleDoc {
                id: "commit-plan-json",
                title: "The same answer, as the shape the API and MCP return",
                description: "One domain model behind every projection: this document is what `GET /api/v1/commit/plan` returns and what the `majordomus_commit_plan` tool answers, with the working tree, every group with its rationale, and the fingerprint.",
                argv: &["commit", "plan", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/fingerprint/repository", "/fingerprint/worktree", "/tree/changes"]),
            },
        ],
    },
    CommandExamples {
        command: "commit scopes",
        examples: &[ExampleDoc {
            id: "commit-scopes",
            title: "The scope vocabulary, learned rather than declared",
            description: "Every scope this repository's own commits use, how often, and the directories each one is written about — read from at most 1500 commits of the log. Nothing here is configured: a subsystem committed today is in the vocabulary today, and one nobody has touched sinks on its own. A repository whose history is not conventional yields an empty vocabulary and says how many commits it read.",
            argv: &["commit", "scopes"],
            setup: &[],
            expect: Expect::StdoutContains(&["learned from"]),
        }],
    },
    CommandExamples {
        command: "commit validate",
        examples: &[ExampleDoc {
            id: "commit-validate-rev",
            title: "The verdict on a commit that is already made",
            description: "`--rev` judges the message of any revision `git show` accepts; without it the message is read from a file or from standard input, which is the shape the `commit-msg` hook has. The exit code is the verdict: 0 when nothing of error severity was found, 10 when something was. Here the repository's first commit is subject `install`, which is not `type(scope): subject`, so the answer is 10 and the finding names the eleven type words.",
            argv: &["commit", "validate", "--rev", "HEAD"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "commit history",
        examples: &[ExampleDoc {
            id: "commit-history",
            title: "A whole range judged in one pass",
            description: "One process for the range rather than one per commit: this reads 1755 commits of this repository's own history in about three and a half seconds, which is what lets `scripts/ci/commit-policy` be a gate rather than a nightly job. It reports how many were read, how many git composed and are therefore exempt, and how many carry an error — and exits 10 when any does.",
            argv: &["commit", "history"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "product",
        examples: &[ExampleDoc {
            id: "product-default-list",
            title: "What the product does, as the layer declares it",
            description: "`product` with nothing after it lists the features, because listing is what a person wants when they ask what the tool is for. Every column is derived: the surfaces a feature is exposed through come from the modules, commands and kinds it names, never from the file.",
            argv: &["product"],
            setup: &[],
            expect: Expect::StdoutContains(&["SLUG", "SURFACES", "feature(s)"]),
        }],
    },
    CommandExamples {
        command: "product list",
        examples: &[
            ExampleDoc {
                id: "product-list",
                title: "Every stable feature, in presentation order",
                description: "Drafts are excluded unless `--all` is given; `--featured` narrows to the features the homepage shows. The filters are the facets the model derives — an area, a module, a command, a surface — so a module added to the executable is a filter without anything being registered.",
                argv: &["product", "list"],
                setup: &[],
                expect: Expect::StdoutContains(&["SLUG", "fixture-feature"]),
            },
            ExampleDoc {
                id: "product-list-json",
                title: "The same, as the shape the API and MCP answer with",
                description: "One domain model behind every projection: this document is what `GET /api/v1/product/features` returns and what the `majordomus_features` tool answers, with the counts, the fingerprint and the surfaces of every feature.",
                argv: &["product", "list", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/counts/features", "/features/0/surfaces", "/fingerprint"]),
            },
        ],
    },
    CommandExamples {
        command: "product show",
        examples: &[ExampleDoc {
            id: "product-show",
            title: "One feature, with everything derived from what it names",
            description: "The record as its file declares it, then what nobody authored: the capabilities of its modules with their tools and routes, the commands with their summaries, the objects of its kinds counted, the rules with their class, the documents, the decisions, the claims with their status, the moments it answers, and the interfaces all of that adds up to.",
            argv: &["product", "show", "fixture-feature"],
            setup: &[],
            expect: Expect::StdoutContains(&["fixture-feature", "surfaces", "derived"]),
        }],
    },
    CommandExamples {
        command: "product domains",
        examples: &[ExampleDoc {
            id: "product-domains",
            title: "The few things the product controls, and the features under each",
            description: "One block per domain in presentation order: its promise, the failure it answers, and the stable features that name it, with the interfaces, claims and use cases they add up to. A domain lists nothing itself; every member and count is derived from the features.",
            argv: &["product", "domains"],
            setup: &[],
            expect: Expect::StdoutContains(&["domain(s)"]),
        }],
    },
    CommandExamples {
        command: "product matrix",
        examples: &[ExampleDoc {
            id: "product-matrix",
            title: "Every feature against every interface, and what no feature names",
            description: "One row per feature with a mark per surface, then every module of the executable, every public command and every kind of the layer with the features that name it. A row with no feature is a gap the product page cannot hide.",
            argv: &["product", "matrix"],
            setup: &[],
            expect: Expect::StdoutContains(&["FEATURE", "cli", "MODULE"]),
        }],
    },
    CommandExamples {
        command: "product providers",
        examples: &[ExampleDoc {
            id: "product-providers",
            title: "Every provider the tool has an adapter for",
            description: "One line per template the distribution ships, with the bootstraps this repository's policy renders through it, the client configuration it carries for the shared MCP server, and the hooks the policy wires. The set is the templates; nothing here is a list of vendors.",
            argv: &["product", "providers"],
            setup: &[],
            expect: Expect::StdoutContains(&["PROVIDER", "agents"]),
        }],
    },
    CommandExamples {
        command: "product validate",
        examples: &[ExampleDoc {
            id: "product-validate",
            title: "Check the model before anything projects it",
            description: "A reference that resolves to nothing, with the nearest candidate; a duplicate identity; a file name that disagrees with its id; a draft that is featured; a stable feature under its floors; and every module, command or kind no feature names. Exit 10 on any error.",
            argv: &["product", "validate"],
            setup: &[],
            expect: Expect::StdoutContains(&["feature(s)", "valid"]),
        }],
    },
    CommandExamples {
        command: "release",
        examples: &[ExampleDoc {
            id: "release-changelog",
            title: "What has shipped, and what has not",
            description: "`release` with nothing after it renders the changelog. Every line of it is derived — a section per release the layer records, its decisions the ADRs dated inside that release's window, its changes the conventional commits in its range — so there is no file anyone can forget to update.",
            argv: &["release"],
            setup: &[],
            expect: Expect::StdoutContains(&["Changelog"]),
        }],
    },
    CommandExamples {
        command: "release changelog",
        examples: &[ExampleDoc {
            id: "release-changelog-json",
            title: "The same document every other surface answers with",
            description: "What `GET /api/v1/changelog` returns, what the MCP resource `majordomus://changelog` carries, and what `majordomus generate changelog` writes into the reference. One value, four renderings.",
            argv: &["release", "changelog", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/schema", "/current", "/sections"]),
        }],
    },
    CommandExamples {
        command: "release version",
        examples: &[ExampleDoc {
            id: "release-version",
            title: "The version, and the one the contract requires next",
            description: "The version is authored in one place, the crate manifest, and the shell tool reads its projection, share/version.txt, because an installed tree has no Cargo.toml. This says what the manifest declares, whether the projection states it, and — exit 10 — any version written down by hand where the tool's own files live. `next` is the public contract's answer, the version `release analyze` requires (the declared version when it already satisfies the contract, otherwise the smallest one it allows); `decided_by` names who answered, and the bump the commit subjects imply is carried as evidence. This fixture has published no release with a registry, so the contract cannot be measured: `next` is absent and `decided_by` is `undecided`, with the reason in `contract_unreadable` — an unmeasurable baseline is refused, not guessed.",
            argv: &["release", "version", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/declared", "/agree", "/bump", "/decided_by"]),
        }],
    },
    CommandExamples {
        command: "release analyze",
        examples: &[ExampleDoc {
            id: "release-analyze",
            title: "What the contract did, and the smallest version it allows",
            description: "The public capability surface of this tree against the one the last release published, and the smallest version this tree may therefore declare. The compatibility level is measured from the contract rather than read off the commit subjects: a capability, route, MCP tool, command or required field a caller could hold and cannot any more is breaking whatever the commit that removed it called itself. The same value answers `GET /api/v1/release/analysis`, the `majordomus_release_analysis` MCP tool, the Cockpit's Release page and the `version-surface` gate. A repository that has published nothing has no baseline to measure against, and says so with exit 12 rather than reporting an empty diff — which would read as \"nothing changed\".",
            argv: &["release", "analyze", "--format", "json"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "release next",
        examples: &[ExampleDoc {
            id: "release-next",
            title: "What a landing would raise the version to",
            description: "The version the integration executor allocates when it lands a head on the trunk (ADR 0134): the trunk's version, the head's movement of the public contract measured against the trunk's committed registry, the policy floor and any exemption, and the larger of the requirement and the floor — read from git at the two refs, never from the branch's own version. This fixture has no trunk to raise from, and says so with exit 12 rather than inventing a number.",
            argv: &["release", "next", "--format", "json"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "release bump",
        examples: &[ExampleDoc {
            id: "release-bump-dry-run",
            title: "Raising it, in the one place it is authored",
            description: "The one writer, and it computes nothing: it reads the plan `release analyze` prints and applies it, so the version it writes is the measured minimum rather than a judgement of its own. `--level` and `--exact` name a higher version when a person means more than the contract did, and are refused below the minimum with nothing written — an override that could undershoot would make the measurement decorative. It rewrites the manifest's one version line and the lock's record of it, reads both back, and leaves share/version.txt and the generator stamps to scripts/derive. A repository that has published nothing has no baseline to raise from — the example runs in one — and says so with exit 12 rather than inventing a number.",
            argv: &["release", "bump", "--dry-run"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "completion install",
        examples: &[ExampleDoc {
            id: "completion-install-dry-run",
            title: "The one line a person adds to their shell, added for them",
            description: "Writes the integration into the shell's startup file between `# >>> MAJORDOMUS >>>` markers: nothing outside them is touched, running it twice changes nothing, and `--remove` takes it out again. It is never a side effect of anything else — installing into a person's home directory is its own decision, so it is its own command. `--dry-run` says what would change and writes nothing.",
            argv: &["completion", "install", "--shell", "zsh", "--dry-run"],
            setup: &[],
            expect: Expect::Success,
        }],
    },
    CommandExamples {
        command: "env",
        examples: &[ExampleDoc {
            id: "env-status",
            title: "What this checkout is",
            description: "`env` with nothing after it resolves the whole snapshot: the project and its version, the repository and its layer, version control, the toolchains the repository declares, what the layer holds counted per kind, the workflows the runner describes, the provider projections against the policy that renders them, and the local services. This is the resolution that counts the layer, so it builds the index and writes the cache the banner reads.",
            argv: &["env"],
            setup: &[],
            expect: Expect::StdoutContains(&["project", "repository", "resolution"]),
        }],
    },
    CommandExamples {
        command: "env status",
        examples: &[ExampleDoc {
            id: "env-status-json",
            title: "The snapshot as one document",
            description: "The same value the HTTP route `/api/v1/environment` and the MCP resource `majordomus://environment` answer with, and the value the banner renders. Every field carries where it came from under `provenance`, and a value nothing could resolve is absent rather than zero.",
            argv: &["env", "status", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/schema", "/project/version", "/repository/name", "/provenance"]),
        }],
    },
    CommandExamples {
        command: "env banner",
        examples: &[ExampleDoc {
            id: "env-banner-compact",
            title: "The two-line form, at a width you choose",
            description: "What `direnv` renders on entering the repository. It resolves fast — it never builds the index — and it writes to standard error, because direnv reads the standard output of a `.envrc` as the environment it is applying. `--width` renders as if the terminal were that wide, which is what makes the layout testable.",
            argv: &["env", "banner", "--mode", "compact", "--width", "80"],
            setup: &[],
            expect: Expect::Success,
        }],
    },
    CommandExamples {
        command: "env export",
        examples: &[ExampleDoc {
            id: "env-export-direnv",
            title: "The assignments a shell in this repository wants",
            description: "Assignments and nothing else, safe to `eval`: no command runs, no file is touched, and every value is quoted so that a repository path holding a quote or a `$(...)` cannot become shell code. This is the whole of what `.envrc` needs from Majordomus.",
            argv: &["env", "export", "--shell", "direnv"],
            setup: &[],
            expect: Expect::StdoutContains(&["export MAJORDOMUS_ROOT="]),
        }],
    },
    CommandExamples {
        command: "env enter",
        examples: &[ExampleDoc {
            id: "env-enter",
            title: "Everything entering this repository is, as one call",
            description: "What the file a shell evaluates on entry runs, and the only call it makes (ADR 0043): the assignments on standard output for `eval`, the banner on standard error, the workflow bridge refreshed when a declaration behind it moved, and the repository's shared server ensured when nothing is serving this checkout. It never builds, never ensures from an executable older than its sources, never waits for a server it started to answer, and never exits non-zero — a non-zero exit here would make direnv report that the whole environment failed. `--no-runtime` is what this example passes, because an example is not the place to start a server.",
            argv: &["env", "enter", "--shell", "direnv", "--no-banner", "--no-bridge", "--no-runtime"],
            setup: &[],
            expect: Expect::StdoutContains(&["export MAJORDOMUS_ROOT="]),
        }],
    },
    CommandExamples {
        command: "env explain",
        examples: &[ExampleDoc {
            id: "env-explain-field",
            title: "Where one value came from",
            description: "An inferred system without provenance is magic. Every field of the snapshot can name the file, command or compile-time constant that decided it, the resolver that read it, and whether it was read now, taken from the cache, or not resolved at all.",
            argv: &["env", "explain", "project.version"],
            setup: &[],
            expect: Expect::StdoutContains(&["project.version", "source", "resolver"]),
        }],
    },
    CommandExamples {
        command: "env preflight",
        examples: &[ExampleDoc {
            id: "env-preflight-json",
            title: "What is in force here, and what proves it",
            description: "One verdict per claim — `verified`, `active`, `fresh`, `stale`, `degraded`, `unavailable`, `failed`, `unknown` or `not_applicable` — and the evidence it rests on: the file, command or loopback answer that was read. A rule file on disk is not a rule anything enforces, an address that accepts a connection is not a server of this version, and a recorded test run at another commit does not verify this tree, so none of them is reported as one. `attention` lists what needs a look, most urgent first.",
            argv: &["env", "preflight", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/schema", "/sections/0/checks/0/verdict", "/attention"]),
        }],
    },
    CommandExamples {
        command: "run",
        examples: &[ExampleDoc {
            id: "run-demonstrate",
            title: "Watch an execution happen",
            description: "`run` starts a capability as an execution and follows it to its end: every step, every line it logs and every advance of its progress, as the handler reports them. `executions.demonstrate` exists to make that visible without waiting for real work — it reads nothing and writes nothing, and its only effect is the events it produces. The same execution, started from the Cockpit, streams the same events to a browser.",
            argv: &["run", "executions.demonstrate", "--input", "{\"steps\":2,\"delay_ms\":0}", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/state", "/id", "/output/steps", "/steps/0/name"]),
        }],
    },
    CommandExamples {
        command: "executions",
        examples: &[ExampleDoc {
            id: "executions-default-list",
            title: "What has run",
            description: "`executions` with nothing after it lists what the server serving this repository has run, newest first. In a checkout where no server is running it says so rather than pretending: an execution lives in the process that accepted it.",
            argv: &["executions"],
            setup: &[],
            expect: Expect::StdoutContains(&["execution"]),
        }],
    },
    CommandExamples {
        command: "evidence show",
        examples: &[
            ExampleDoc {
                id: "evidence-show-json",
                title: "The whole join, as one document",
                description: "The same answer `GET /api/v1/evidence` and the MCP tool `majordomus_evidence` return: every claim with its proof state, the sentence that explains how that state was derived, the execution behind it, the files that have changed since, and the command that produces the proof again. The tallies count the whole matrix even when the claims are filtered, so a narrowed answer never misreports how much of it was examined.",
                argv: &["evidence", "show", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/claims", "/totals", "/ledger/path", "/findings"]),
            },
            ExampleDoc {
                id: "evidence-show-presented",
                title: "The checked-out commit, judged as committed",
                description: "The reading a site built from this commit needs: every claim judged from the ledger the commit holds rather than the working tree's, against the commit's own tree, measured without the ledger's working copy. The first line names what was judged. A run the working ledger holds that the commit's does not can only withhold `proven`, and is named when there is one; a revision other than the checked-out commit is refused.",
                argv: &["evidence", "show", "--presented", "HEAD"],
                setup: &[],
                expect: Expect::StdoutContains(&["judged at", "as committed"]),
            },
        ],
    },
    CommandExamples {
        command: "evidence claim",
        examples: &[ExampleDoc {
            id: "evidence-claim-absent",
            title: "A claim the matrix does not declare",
            description: "A claim id nothing declares is a not-found rather than an empty answer. A typo that read as `this claim has no evidence` is the one answer this command must never give, because it is indistinguishable from the finding the whole subsystem exists to report.",
            argv: &["evidence", "claim", "no-such-claim-exists"],
            setup: &[],
            expect: Expect::ExitCode(13),
        }],
    },
    CommandExamples {
        command: "evidence proves",
        examples: &[ExampleDoc {
            id: "evidence-proves-unknown",
            title: "Something that names no test",
            description: "A test is named by its identity (`suite:<case>`, `crate:<binary>`) or by the path a claim writes down, and the two resolve to the same thing. An argument that is neither is refused with the spellings it could have been, rather than answered with a test that proves nothing.",
            argv: &["evidence", "proves", "not-a-test"],
            setup: &[],
            expect: Expect::ExitCode(13),
        }],
    },
    CommandExamples {
        command: "delivery report",
        examples: &[ExampleDoc {
            id: "delivery-report-json",
            title: "Does each feature exist, dimension by dimension",
            description: "The same answer `GET /api/v1/delivery` and the MCP tool `majordomus_delivery` return: every feature ordered by id, each of the six dimensions with its verdict, reason and remediation, the development stage of a feature that does not exist, the paths it is implemented by, and the publication read once for all of them. A repository with no site and no trunk says unknown, and unknown is never a pass, so nothing here exists.",
            argv: &["delivery", "report", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/features/0/dimensions", "/tallies/exists", "/publication/identity/state"]),
        }],
    },
    CommandExamples {
        command: "delivery show",
        examples: &[ExampleDoc {
            id: "delivery-show",
            title: "One feature, and what stands between it and existing",
            description: "Every dimension of one feature with the sentence that decided it and what would change it. `--check` turns the conjunction into the exit code: 10 unless every dimension passes. An id the layer does not declare is not found, never reported as not delivered.",
            argv: &["delivery", "show", "fixture-feature"],
            setup: &[],
            expect: Expect::StdoutContains(&["fixture-feature", "on_master", "NOT DELIVERED"]),
        }],
    },
    CommandExamples {
        command: "entity kinds",
        examples: &[ExampleDoc {
            id: "entity-kinds-json",
            title: "Every kind of the layer, and whether every object of it has an address",
            description: "The catalogue the Cockpit's navigation and the site's indexes are both derived from. Nothing enumerates kinds: each one is here because the index holds an object of it, and each carries the route of its own listing. `collisions` is the one way an object can fail to be addressable — two identities of one kind that reduce to one route — and the healthy answer is none.",
            argv: &["entity", "kinds", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/kinds", "/count", "/routable"]),
        }],
    },
    CommandExamples {
        command: "entity show",
        examples: &[
            ExampleDoc {
                id: "entity-show-rule",
                title: "One entity at its own address",
                description: "The same answer `GET /api/v1/entity` and the MCP tool `majordomus_entity` return, and the same one the Cockpit lays out: the entity's route, the references it declares, the references that resolve to it — derived, never declared — the surfaces that answer for it, what can be said about the executable artefacts it names, and its public documentation page (`documentation`, null here because this fixture has no site/data/publication.toml). The address is the route's two segments, which is the shorter spelling of the URI and the one the Cockpit's address bar holds.",
                argv: &["entity", "show", "rule/project-alpha-1", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&[
                    "/uri",
                    "/route",
                    "/relations",
                    "/surfaces",
                    "/evidence/state",
                ]),
            },
            ExampleDoc {
                id: "entity-show-absent",
                title: "An address the layer does not serve",
                description: "An entity nothing declares is a not-found rather than an empty answer, for the reason `rules show` gives: a typo that read as `this entity is joined to nothing` is indistinguishable from the finding the page exists to show.",
                argv: &["entity", "show", "rule/no-such-rule"],
                setup: &[],
                expect: Expect::ExitCode(12),
            },
        ],
    },
    CommandExamples {
        command: "rules report",
        examples: &[ExampleDoc {
            id: "rules-report-json",
            title: "Every rule against the proof there is for it",
            description: "The same answer `GET /api/v1/rules` and the MCP tool `majordomus_rules` return: per rule, its class, the mode it declares, the validator and the cases it names, whether each is in the tree, the execution behind each, the gates that run them, and the sentence explaining how the state was derived. The tallies count the whole corpus even when the rules are filtered, and `review_only` is counted apart from `passing` so that a rule a person enforces is never added to a total that reads as proof.",
            argv: &["rules", "report", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/rules", "/states", "/coverage/rules", "/findings"]),
        }],
    },
    CommandExamples {
        command: "brief",
        examples: &[ExampleDoc {
            id: "brief-line",
            title: "The one-line brief, composed here when no server answers",
            description: "The same answer `GET /api/v1/brief` and the MCP tool `majordomus_brief` return, rendered as its one line: this session's task or episode and branch, the peers of the boards read, the mesh, the integration queue and the derive lock, every section present whatever its state. The command line asks the server holding this checkout's lease, which holds the board and the mesh; this fixture has no server, so the brief is composed by this process and says so in its multi-line form.",
            argv: &["brief", "--line", "--this-checkout"],
            setup: &[],
            expect: Expect::Success,
        }],
    },
    CommandExamples {
        command: "dashboard overview",
        examples: &[ExampleDoc {
            id: "dashboard-overview-json",
            title: "The four questions, every card with the answer it was read from",
            description: "The same answer `GET /api/v1/dashboard/overview`, the MCP tool `majordomus_dashboard_overview` and the first section of the Cockpit's overview return: is it healthy, what changed, what is broken, what needs action, each answered by cards read out of `health.report`, `release.version`, `plan.status`, `worktree.status`, `plan.next`, `continuity.state` and `peers.list`. Every card carries its source capability, the input it was asked with and the JSON pointer its value was read from, so `majordomus run <capability>` read at that pointer gives the same value. The exit code is the overview's own word: 0 for ok and warn, 10 for fail and unknown. This fixture commits no registry manifest, so `health.report` cannot decide one of its checks, the health card is `unknown` rather than ok, and the answer is 10.",
            argv: &["dashboard", "overview", "--format", "json"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "pack plan",
        examples: &[ExampleDoc {
            id: "pack-plan-chatgpt-json",
            title: "What the ChatGPT profile would pack, before anything is written",
            description: "The same answer `GET /api/v1/pack/plan?profile=chatgpt` and the MCP tool `majordomus_pack_plan` return: the files carried with their bytes and o200k_base tokens, every file left out by reason under `/dropped` and `/dropped_files`, the shards under `/shards`, and every finding that would refuse the build under `/findings`. The exit code is the verdict: 0 when the pack can be built, 10 on a finding, 12 when the tree cannot be read.",
            argv: &["pack", "plan", "chatgpt", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/dropped", "/shards", "/findings", "/passes"]),
        }],
    },
    CommandExamples {
        command: "pack build",
        examples: &[ExampleDoc {
            id: "pack-build-chatgpt",
            title: "Write the ChatGPT pack and read it back",
            description: "Plans with the profile, writes `00-INDEX.md`, the shards and `pack.json` under `tmp/packs/` only when the plan passes, then verifies what it wrote: every digest, no stray file, no binary, artifact, link or worktree, every file within the token budget. It prints the plan and the verdict; the files to upload are the index and the shards.",
            argv: &["pack", "build", "chatgpt"],
            setup: &[],
            expect: Expect::StdoutContains(&["pack verify: clean"]),
        }],
    },
    CommandExamples {
        command: "pack verify",
        examples: &[ExampleDoc {
            id: "pack-verify-absent",
            title: "A directory that holds no pack",
            description: "A directory without a `pack.json` cannot be verified, and that is reported as unmeasured with exit 12 rather than as a clean pack: a verifier that passed what it could not read would pass anything.",
            argv: &["pack", "verify", "tmp/packs/absent"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "shell check",
        examples: &[ExampleDoc {
            id: "shell-check-json",
            title: "Every shell unit against the automation inventory",
            description: "The shell units under the governed directories, how many records the inventory holds, the exemptions by disposition, and every finding with its remedy, as `/units`, `/exemptions`, `/findings` and `/passes`. The exit code is the verdict: 0 when every unit is declared and every record names a unit the tree still has, 10 on a finding, and 12 when the tree could not be measured, which is not a pass. Here the repository holds the bash library `lib/a.sh` and no inventory, so the answer is 10 and the finding names the file and the remedy.",
            argv: &["shell", "check", "--format", "json"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "rules show",
        examples: &[ExampleDoc {
            id: "rules-show-absent",
            title: "A rule the repository does not declare",
            description: "A rule id nothing declares is a not-found rather than an empty answer. A typo that read as `this rule has no proof` is the one answer this command must never give, because it is indistinguishable from the finding the whole subsystem exists to report.",
            argv: &["rules", "show", "project.no-such-rule"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "rules proves",
        examples: &[ExampleDoc {
            id: "rules-proves-case",
            title: "What a case proves, and what would lose its only proof",
            description: "The reverse of `rules show`, reading the same derivation so the two directions cannot disagree. It names every rule that names this test and, separately, the rules that would be left with no proof at all if it were deleted — the question to ask before renaming a case, and the one that could not be asked while the relation ran one way only.",
            argv: &["rules", "proves", "test/cases/125_rule_proof.sh", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/proves", "/sole_proof_of", "/path"]),
        }],
    },
    CommandExamples {
        command: "continuity status",
        examples: &[ExampleDoc {
            id: "continuity-status-json",
            title: "Where this device stands in the work published from every device",
            description: "The same value `GET /api/v1/continuity/status` and the MCP tool `majordomus_continuity_status` return: this repository's identity (a digest of its root commits, the same in every clone), this device, the record this checkout continues on its branch, how the local store stands towards the remote's — read from refs, with no network — and what other devices published that could be resumed here. A repository that has published nothing answers with an empty store, which is an answer and not an error.",
            argv: &["continuity", "status", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/repository", "/device/node", "/store/sync", "/resumable"]),
        }],
    },
    CommandExamples {
        command: "continuity device",
        examples: &[ExampleDoc {
            id: "continuity-device-json",
            title: "This device, as a published handover names it",
            description: "The node id and public key of this device's mesh key — created on first use in the user's state directory, never in a repository — and its label. `--label mac-mini` renames it without changing the key.",
            argv: &["continuity", "device", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/device/node", "/device/label", "/public_key"]),
        }],
    },
    CommandExamples {
        command: "continuity records",
        examples: &[ExampleDoc {
            id: "continuity-records-json",
            title: "Every published handover, by line",
            description: "Every record of refs/majordomus/continuity that passed admission, every line of work with its heads, and a diagnostic for each refused file. Empty in a repository that has published nothing.",
            argv: &["continuity", "records", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/records", "/lines", "/diagnostics"]),
        }],
    },
    CommandExamples {
        command: "continuity plan",
        examples: &[ExampleDoc {
            id: "continuity-plan-nothing",
            title: "A plan with nothing to resume",
            description: "With no handover published from another device, the plan says so — `nothing_to_resume` — and exits 0: absence is an answer. With one, the same command decides trust, lineage and source compatibility and lists the commands that resolve each blocker without running any of them.",
            argv: &["continuity", "plan", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/status", "/blockers", "/warnings", "/actions"]),
        }],
    },
    CommandExamples {
        command: "continuity publish",
        examples: &[ExampleDoc {
            id: "continuity-publish-nothing",
            title: "Nothing to publish without a handover",
            description: "A publication reads the newest handover record; a checkout that has written none is told to write one with `majordomus handover` and exits 10, before any device key is created.",
            argv: &["continuity", "publish"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "continuity sync",
        examples: &[ExampleDoc {
            id: "continuity-sync-no-remote",
            title: "A repository with no remote keeps its records",
            description: "Sync moves records only through a git remote. A repository with none answers `no_remote` and exits 0: the records stay in this clone, and that is a valid state rather than a failure.",
            argv: &["continuity", "sync", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/action", "/store/sync"]),
        }],
    },
    CommandExamples {
        command: "continuity resume",
        examples: &[ExampleDoc {
            id: "continuity-resume-nothing",
            title: "A resume with nothing to resume writes nothing",
            description: "Resume acts only on a ready plan. With no published handover it writes nothing and exits 10, printing the plan that declined.",
            argv: &["continuity", "resume"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "knowledge candidates",
        examples: &[ExampleDoc {
            id: "knowledge-candidates-json",
            title: "The review queue, as one document",
            description: "The same answer `GET /api/v1/knowledge/candidates`, the MCP tool `majordomus_knowledge_candidates` and the resource `majordomus://knowledge-candidates` serve: every record with status candidate under the candidates class, the branch of the episode each came from, how long each has waited, and the policy's cap beside the count. A repository whose deriver has not run yet answers with an empty queue, which is an answer and not an error.",
            argv: &["knowledge", "candidates", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/total", "/on_this_branch", "/branch", "/over_cap"]),
        }],
    },
    CommandExamples {
        command: "knowledge record",
        examples: &[ExampleDoc {
            id: "knowledge-record-absent",
            title: "A record the repository does not hold",
            description: "An id nothing carries is a not-found rather than an empty answer, with the exit code that says which: a typo that read as `this record names no evidence` would be indistinguishable from the dangling reference the integrity validator exists to report.",
            argv: &["knowledge", "record", "no-such-record"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "knowledge status",
        examples: &[ExampleDoc {
            id: "knowledge-status-json",
            title: "Whether the deriver is still writing",
            description: "The freshness half of the stopped-writer judgement: the newest derivation, the newest closed episode, how many closed episodes no derivation names, and — once a derivation has run in this checkout — whether the newest close went underived past the stale threshold. A fresh repository, in which no episode has closed, reports that it was not judged and why, and never a stopped writer.",
            argv: &["knowledge", "status", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/present", "/judged", "/stopped_writer", "/freshness"]),
        }],
    },
    CommandExamples {
        command: "evidence record",
        examples: &[ExampleDoc {
            id: "evidence-record-missing",
            title: "Recording a report that is not there",
            description: "The recorder reads what a run already wrote — the suite's TSV report, `cargo test`'s output — and stamps it with the provenance the run did not carry. A report it cannot read is refused: recording nothing would leave every claim reading `not run` after a run that ran, which is a lie in the safe direction and still a lie.",
            argv: &["evidence", "record", "--suite", "target/no-such-run.tsv"],
            setup: &[],
            expect: Expect::ExitCode(13),
        }],
    },
    CommandExamples {
        command: "evidence stamp",
        examples: &[ExampleDoc {
            id: "evidence-stamp-json",
            title: "What a run measured, as one document",
            description: "The measurement a runner takes when its run ends: the commit, the tree with the evidence ledger ignored and the run's own untracked outputs excluded, the producer, its toolchain, the recorder's version and the host. `evidence record --provenance` carries it into the executions of that run's report.",
            argv: &["evidence", "stamp", "--producer", "suite", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/producer", "/commit", "/working_tree", "/recorder", "/host"]),
        }],
    },
    CommandExamples {
        command: "served observe",
        examples: &[ExampleDoc {
            id: "served-observe-unreachable",
            title: "A deployment that could not be reached is not a deployment that is current",
            description: "One bounded probe of the build identity under the base URL, judged against HEAD. Nothing listens on the discard port, so nothing is received and the verdict is `unreachable` with exit 12 — the unanswered question, never the yes. `--dry-run` judges without recording. Against the public site the same command answers `served` (0) when the build contains the commit and `stale` (10) when it does not.",
            argv: &["served", "observe", "--url", "http://127.0.0.1:9", "--timeout", "1", "--dry-run"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "served forge",
        examples: &[ExampleDoc {
            id: "served-forge-unknown-repository",
            title: "A forge that cannot be asked is said, and what was recorded before stands",
            description: "Asks the forge, through its own command-line tool, for the newest deployments to every environment and the newest releases, and records the answer `deploy.observed` reads. Here the repository has no remote the forge knows, so nothing is asked and the command says why with exit 12 — not answered, never an empty list read as none. In a checkout of a repository on the forge, with a credential, it prints how many deployments, environments and releases the answer held and exits 0.",
            argv: &["served", "forge"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "served show",
        examples: &[ExampleDoc {
            id: "served-show-json",
            title: "What each deployment was last seen serving, judged against HEAD now",
            description: "The newest recorded observation of each deployment, re-judged against the commit asked about without probing anything. The same answer `GET /api/v1/served` and the MCP tool `majordomus_served` give. A checkout that has observed nothing answers with an empty list rather than a verdict.",
            argv: &["served", "show", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/expected", "/observations", "/unreadable", "/deployments"]),
        }],
    },
    CommandExamples {
        command: "executions list",
        examples: &[ExampleDoc {
            id: "executions-list-json",
            title: "Every execution, as one document",
            description: "The same answer `GET /api/v1/executions`, the MCP tool `majordomus_executions` and the Cockpit's Executions page render, with the counts beside it: how many are remembered, how many are active, how many are waiting for a worker and how many live channels are following them.",
            argv: &["executions", "list", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/count", "/active", "/queued", "/live_channels"]),
        }],
    },
    CommandExamples {
        command: "executions show",
        examples: &[ExampleDoc {
            id: "executions-show-absent",
            title: "An execution that is not there",
            description: "An execution lives in the process that accepted it and is remembered in bounded numbers, so asking for one nothing ran says so and exits with the missing-artifact code rather than inventing an empty answer. Against a running server, the same command prints that execution's state, its steps and what it produced.",
            argv: &["executions", "show", "x-20260101T120000Z-4c3b2a19"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "executions events",
        examples: &[ExampleDoc {
            id: "executions-events-absent",
            title: "The events of an execution that is not there",
            description: "The retained events of one execution, oldest first, after a sequence number — what a reconnecting client reads before it opens the live channel. For an execution nothing ran, the same refusal as `show`.",
            argv: &["executions", "events", "x-20260101T120000Z-4c3b2a19"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "executions cancel",
        examples: &[ExampleDoc {
            id: "executions-cancel-absent",
            title: "Asking an execution that is not there to stop",
            description: "Cancellation is cooperative: the flag is set and a task stops when it next looks at it. There is nothing to set for an execution nothing ran, and the command says so rather than reporting a success it did not have.",
            argv: &["executions", "cancel", "x-20260101T120000Z-4c3b2a19"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "executions protocol",
        examples: &[ExampleDoc {
            id: "executions-protocol",
            title: "The live channel's contract, from the types that implement it",
            description: "Where the WebSocket is, how a subscription and a reconnect are expressed, every message type, and the JSON Schema of each — derived from the Rust types, so a client validating against this is validating against the implementation. OpenAPI cannot describe a socket, which is why this is a capability and not a paragraph.",
            argv: &["executions", "protocol", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/protocol_version", "/websocket", "/event_types/0", "/stream_types/0", "/limits/max_events"]),
        }],
    },
    CommandExamples {
        command: "prs",
        examples: &[ExampleDoc {
            id: "prs-default-unobserved",
            title: "The queue, before the forge was ever observed",
            description: "`prs` with nothing after it is `prs status`. It reads the last recorded forge observation and never reaches the network, so in a checkout where `prs refresh` has never run it has nothing to rank: it says so, names the command that observes, and exits 10.",
            argv: &["prs"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "prs status",
        examples: &[ExampleDoc {
            id: "prs-status-json-unobserved",
            title: "The ranked queue as one document",
            description: "Every open pull request's assessment in rank order — disposition, lane, reasons, the master and head it was decided against, evidence, risk, overlaps — with the next merge and the tallies. The same value `GET /api/v1/pull-requests` and the MCP tool `majordomus_pull_requests` answer. With no observation recorded it exits 10.",
            argv: &["prs", "status", "--format", "json"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "prs plan",
        examples: &[ExampleDoc {
            id: "prs-plan-unobserved",
            title: "What the executor would do next",
            description: "The next merge, the pull requests that need master brought in, and the repair, cleanup and held lanes. The plan is void after any merge: the executor observes again before its next step. With no observation recorded it exits 10.",
            argv: &["prs", "plan"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "prs explain",
        examples: &[ExampleDoc {
            id: "prs-explain-unobserved",
            title: "Why one pull request is where it is",
            description: "The revisions it was decided against, every piece of evidence, its rank and the factors behind it. The same answer `GET /api/v1/pull-requests/explain?number=` gives. With no observation recorded it exits 10.",
            argv: &["prs", "explain", "1"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "prs events",
        examples: &[ExampleDoc {
            id: "prs-events-empty",
            title: "The audit trail of this checkout's executor",
            description: "Every selection, stale decision, merge with the master before and after, refusal, refresh and closure, oldest first. A checkout whose executor never ran has none, and says so.",
            argv: &["prs", "events"],
            setup: &[],
            expect: Expect::StdoutContains(&["no integration action"]),
        }],
    },
    CommandExamples {
        command: "prs trains",
        examples: &[ExampleDoc {
            id: "prs-trains-unobserved",
            title: "The trains of stacked pull requests, where nothing is observed",
            description: "Every open pull request stacked on another, grouped into trains in landing order, with each link's prepared head under refs/prep/<n> and whether it was pushed. The same answer `GET /api/v1/pull-requests/trains` gives and /cockpit/trains draws. With no observation recorded it says why and exits 10.",
            argv: &["prs", "trains"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "prs refresh",
        examples: &[ExampleDoc {
            id: "prs-refresh-no-forge",
            title: "Observing the forge, where there is none",
            description: "`refresh` is one of the three `prs` commands that reach the network: it asks the GitHub CLI about the repository, its branch protection and its open pull requests, and fetches their heads. A repository with no GitHub remote cannot be observed, and the answer is exit 12 — unusable, never an empty queue.",
            argv: &["prs", "refresh"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "prs drain",
        examples: &[ExampleDoc {
            id: "prs-drain-dry-run-no-forge",
            title: "A dry run starts from a fresh observation",
            description: "Even a dry run observes the forge first — a decision is never taken from the recorded observation — so where the forge cannot be reached it stops with exit 12 before deciding anything, and nothing is merged, refreshed or recorded.",
            argv: &["prs", "drain", "--dry-run"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "prs prove-dry-run",
        examples: &[ExampleDoc {
            id: "prs-prove-dry-run-no-forge",
            title: "The proof needs a forge to prove anything about",
            description: "The proof snapshots origin's refs and the forge's open pull requests around refresh, plan, drain --dry-run and cleanup, and compares them. A repository with no GitHub remote has nothing to snapshot, so it exits 12 before any step runs: a proof that could not look is not a proof that nothing moved.",
            argv: &["prs", "prove-dry-run"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "prs brief",
        examples: &[ExampleDoc {
            id: "prs-brief-unobserved",
            title: "The briefing line, where nothing was observed",
            description: "What `majordomus context` prints under INTEGRATION: the last queue this checkout built, the lease and the last merge, in one line, read from files and never from the network. A checkout whose forge was never observed has nothing to say, prints nothing, and exits 0 — a briefing does not grow a section about an empty queue.",
            argv: &["prs", "brief"],
            setup: &[],
            expect: Expect::ExitCode(0),
        }],
    },
    CommandExamples {
        command: "prs repair",
        examples: &[ExampleDoc {
            id: "prs-repair-unobserved",
            title: "A repair is decided on the recorded observation, or not at all",
            description: "The dry run, which is the default, is a read: it decides whether the named pull request may have master brought in from the queue the last recorded observation built, as `prs status` does, and reaches no network. Where nothing was ever observed there is no classification to decide from, so it exits 10 and names `prs refresh`; nothing is merged, pushed or recorded.",
            argv: &["prs", "repair", "1"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "prs cleanup",
        examples: &[ExampleDoc {
            id: "prs-cleanup-no-forge",
            title: "Cleanup lists before it closes, and observes before it lists",
            description: "Without `--apply` cleanup only lists the pull requests whose work is provably on master; either way it observes the forge first, so where there is none it exits 12.",
            argv: &["prs", "cleanup"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "convergence",
        examples: &[ExampleDoc {
            id: "convergence-report-json",
            title: "Is any work held where it can be lost?",
            description: "Every holding of this repository — a work tree with uncommitted files, a branch with commits, a stash — with the disposition read from git for each: integrated when the trunk reaches it, published when a remote-tracking ref does, local_only when nothing but this disk has it, uncommitted when it was never committed at all. The last two are at risk, and the verdict over them is what the completion invariant's `no-stale-topology` question reads. Measured offline: a remote-tracking ref is what this checkout last fetched, which is exactly the question — whether the work left this disk.",
            argv: &["convergence", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/schema", "/converged", "/at_risk", "/tallies"]),
        }],
    },
    CommandExamples {
        command: "worktree",
        examples: &[ExampleDoc {
            id: "worktree-default-status",
            title: "Where am I, and is that where I belong?",
            description: "`worktree` with nothing after it answers the question a worker asks before starting: which branch this is, whether this directory is that branch's canonical worktree (or the primary checkout on the trunk), what is uncommitted here, and how many errors the whole topology carries. The same answer from the primary checkout and from four directories deep inside a linked worktree.",
            argv: &["worktree"],
            setup: &[],
            expect: Expect::StdoutContains(&["branch", "worktree", "container"]),
        }],
    },
    CommandExamples {
        command: "worktree status",
        examples: &[ExampleDoc {
            id: "worktree-status-json",
            title: "The current worktree as one document",
            description: "The same answer as JSON: the repository, the container, the trunk and how it was decided, this worktree with its standing and diagnostics, and whether it is where it belongs. This is what the MCP tool `majordomus_worktree_status` and `GET /api/v1/worktrees/status` answer.",
            argv: &["worktree", "status", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/worktree/standing", "/container/path", "/trunk/source", "/canonical"]),
        }],
    },
    CommandExamples {
        command: "worktree list",
        examples: &[ExampleDoc {
            id: "worktree-list-text",
            title: "Every worktree, the misplaced ones obvious",
            description: "The primary checkout first, then every linked worktree with its standing, its branch, where it belongs when it is somewhere else, and its uncommitted work. The primary checkout is exempt from the path rule and held to the trunk rule instead.",
            argv: &["worktree", "list"],
            setup: &[&["worktree", "create", "feature/example"]],
            expect: Expect::StdoutContains(&["PRIMARY", "CANONICAL", "-wt/feature/example"]),
        }],
    },
    CommandExamples {
        command: "worktree topology",
        examples: &[ExampleDoc {
            id: "worktree-topology-json",
            title: "The whole topology as one document",
            description: "The repository, the container, the trunk, every worktree, every branch with or without a worktree, every diagnostic with its code and remedy, and the tallies. This is what the MCP resource `majordomus://worktrees`, the tool `majordomus_worktrees`, `GET /api/v1/worktrees` and the Cockpit all render.",
            argv: &["worktree", "topology", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/container/path", "/trunk/branch", "/worktrees/0/standing", "/branches/0/name", "/tallies/worktrees", "/valid"]),
        }],
    },
    CommandExamples {
        command: "worktree root",
        examples: &[ExampleDoc {
            id: "worktree-root-path",
            title: "The container, for the shell",
            description: "Prints the container and nothing else, so a shell can use it: `cd \"$(majordomus worktree root)\"`. It is the primary checkout's sibling named with `-wt`, derived from git's own identity and never from the current directory — which is why running this inside a linked worktree does not answer a container inside that worktree.",
            argv: &["worktree", "root"],
            setup: &[],
            expect: Expect::StdoutContains(&["-wt"]),
        }],
    },
    CommandExamples {
        command: "worktree path",
        examples: &[ExampleDoc {
            id: "worktree-path-branch",
            title: "The canonical path of a branch, for the shell",
            description: "A child process cannot change its parent shell's directory, so nothing here pretends to: this prints one path and the shell does the rest — `cd \"$(majordomus worktree path feature/x)\"`. The path is the branch name under the container, hierarchy kept; the branch need not exist yet.",
            argv: &["worktree", "path", "feature/providers/streaming"],
            setup: &[],
            expect: Expect::StdoutContains(&["-wt/feature/providers/streaming"]),
        }],
    },
    CommandExamples {
        command: "worktree inspect",
        examples: &[ExampleDoc {
            id: "worktree-inspect-branch",
            title: "One branch, before creating its worktree",
            description: "Where the branch's worktree belongs, whether the branch exists, whether anything occupies the path, and what would stand in the way. For a branch that does not exist yet, the answer is the path `worktree create` would use and the command to run.",
            argv: &["worktree", "inspect", "feature/new-dashboard"],
            setup: &[],
            expect: Expect::StdoutContains(&["-wt/feature/new-dashboard", "does not exist yet"]),
        }],
    },
    CommandExamples {
        command: "worktree create",
        examples: &[ExampleDoc {
            id: "worktree-create-branch",
            title: "Start work on a branch without deciding where it goes",
            description: "Creates the branch `feature/improve-cli` from the trunk and checks it out in a new worktree at `<repository>-wt/feature/improve-cli`. No path is given and none may be: the destination follows from the repository's identity and the branch name, so the same command in the same repository always produces the same path — from the primary checkout, and from inside another worktree.",
            argv: &["worktree", "create", "feature/improve-cli"],
            setup: &[],
            expect: Expect::StdoutContains(&["-wt/feature/improve-cli", "feature/improve-cli (new"]),
        }],
    },
    CommandExamples {
        command: "worktree ensure",
        examples: &[ExampleDoc {
            id: "worktree-ensure-existing",
            title: "The canonical worktree, whether or not it exists yet",
            description: "`ensure` is `create` for a caller that does not care whether the worktree is already there: it creates it when it is absent and answers the existing one when it is present. What a script or an agent runs before starting on a branch.",
            argv: &["worktree", "ensure", "feature/improve-cli"],
            setup: &[&["worktree", "create", "feature/improve-cli"]],
            expect: Expect::StdoutContains(&["exists", "-wt/feature/improve-cli"]),
        }],
    },
    CommandExamples {
        command: "worktree migrate",
        examples: &[ExampleDoc {
            id: "worktree-migrate-plan",
            title: "What it would take to bring every worktree home",
            description: "`--plan` shows each misplaced worktree with where it belongs, how it would move, the uncommitted work that moves with it, and what blocks it, and changes nothing. Without `--plan` the movable steps are carried out: each worktree is fingerprinted, moved with `git worktree move`, fingerprinted again at its new path, and reported as moved only when the two are equal.",
            argv: &["worktree", "migrate", "--plan"],
            setup: &[],
            expect: Expect::StdoutContains(&["nothing to migrate"]),
        }],
    },
    CommandExamples {
        command: "worktree validate",
        examples: &[ExampleDoc {
            id: "worktree-validate-clean",
            title: "Is the topology valid?",
            description: "Every error-level diagnostic and nothing else, then the verdict; exit 10 when there is an error. What a script gates on.",
            argv: &["worktree", "validate"],
            setup: &[],
            expect: Expect::StdoutContains(&["worktree topology: valid"]),
        }],
    },
    CommandExamples {
        command: "worktree doctor",
        examples: &[ExampleDoc {
            id: "worktree-doctor-clean",
            title: "Every diagnostic, with its code and its remedy",
            description: "Errors, warnings and facts — a misplaced worktree, a stale registration, a detached HEAD, the primary checkout off the trunk, an unknown trunk — each under a stable code the API and the Cockpit carry too, each with the command that addresses it.",
            argv: &["worktree", "doctor"],
            setup: &[],
            expect: Expect::StdoutContains(&["worktree topology: valid"]),
        }],
    },
    CommandExamples {
        command: "worktree guard",
        examples: &[ExampleDoc {
            id: "worktree-guard-ok",
            title: "May a commit proceed from here?",
            description: "The pre-commit hook's question. Exit 0 in a branch's canonical worktree, in the primary checkout on the trunk, or on a detached HEAD; exit 10 with the diagnostic and the remedy when a feature branch is being worked on somewhere it does not belong. The hook stays one line; this is the logic.",
            argv: &["worktree", "guard"],
            setup: &[],
            expect: Expect::StdoutContains(&["worktree guard: ok"]),
        }],
    },
    CommandExamples {
        command: "worktree repair",
        examples: &[ExampleDoc {
            id: "worktree-repair-dry-run",
            title: "What git would forget",
            description: "`repair` drops git's registrations of worktrees whose directories no longer exist and lets git repair the administrative links of the ones that do. It deletes no directory and touches no branch; `--dry-run` reports what it would drop and changes nothing.",
            argv: &["worktree", "repair", "--dry-run"],
            setup: &[],
            expect: Expect::StdoutContains(&["nothing to prune"]),
        }],
    },
    CommandExamples {
        command: "worktree remove",
        examples: &[ExampleDoc {
            id: "worktree-remove-clean",
            title: "Remove a worktree, and keep its branch",
            description: "Removes the worktree and nothing else. The branch it held still exists: worktree lifecycle and branch lifecycle are separate, and deleting a branch is a git command a person types deliberately. A worktree with uncommitted work is refused rather than removed.",
            argv: &["worktree", "remove", "feature/improve-cli"],
            setup: &[&["worktree", "create", "feature/improve-cli"]],
            expect: Expect::StdoutContains(&["removed", "feature/improve-cli still exists"]),
        }],
    },
    CommandExamples {
        command: "worktree cleanup",
        examples: &[ExampleDoc {
            id: "worktree-cleanup-nothing",
            title: "What could go, and what it would take",
            description: "Every branch merged into the trunk whose worktree is clean or absent, with the two commands that would remove the worktree and then the branch. Derived state only: nothing is deleted here, and a dirty or unmerged worktree is never listed.",
            argv: &["worktree", "cleanup"],
            setup: &[],
            expect: Expect::StdoutContains(&["cleanup-eligible"]),
        }],
    },
    CommandExamples {
        command: "worktree uncommitted",
        examples: &[ExampleDoc {
            id: "worktree-uncommitted-none",
            title: "Work no commit carries, and whether anything holds it",
            description: "Every linked worktree holding staged, unstaged, untracked or conflicted paths, with the count, the age of the oldest change, the task, episode or process that holds it, and `abandoned` when nothing does and it is older than the policy's session.stranded_after. A repository with no linked worktree has nothing to list; the reading writes nothing either way.",
            argv: &["worktree", "uncommitted"],
            setup: &[],
            expect: Expect::StdoutContains(&["0 with uncommitted work", "nothing was changed"]),
        }],
    },
    CommandExamples {
        command: "worktree branches",
        examples: &[ExampleDoc {
            id: "worktree-branches-list",
            title: "The live branch set, for completion",
            description: "Every local branch, one per line, nothing else. A shell completion for `worktree path`, `create` or `remove` reads this rather than a list kept anywhere, so a branch created a second ago completes.",
            argv: &["worktree", "branches"],
            setup: &[],
            expect: Expect::Success,
        }],
    },
    CommandExamples {
        command: "distribution",
        examples: &[ExampleDoc {
            id: "distribution-show-default",
            title: "How this project is installed",
            description: "`distribution` with nothing after it shows the model: the one-line install command, where an installation goes, and how many platforms a release builds. Every value comes from share/distribution.yaml, which is the only place any of them is written.",
            argv: &["distribution"],
            setup: &[],
            expect: Expect::StdoutContains(&["binary", "install", "targets"]),
        }],
    },
    CommandExamples {
        command: "distribution show",
        examples: &[ExampleDoc {
            id: "distribution-show-json",
            title: "The distribution model as one JSON document",
            description: "The same answer as a document a script can read: the install command, the default locations, and every declared target with the artifact name the naming function derives for it. This is what the website's install block and the cockpit's install card render.",
            argv: &["distribution", "show", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/install_command", "/targets"]),
        }],
    },
    CommandExamples {
        command: "distribution targets",
        examples: &[ExampleDoc {
            id: "distribution-targets",
            title: "Every platform, and whether a release builds it",
            description: "One line per declared target: its id, its Rust target triple, whether it is supported, experimental or unavailable, and how it is written in prose. The supported-platform table in the documentation and the installer's own refusal message are rendered from these same rows.",
            argv: &["distribution", "targets"],
            setup: &[],
            expect: Expect::StdoutContains(&["RUST TARGET", "supported"]),
        }],
    },
    CommandExamples {
        command: "distribution validate",
        examples: &[ExampleDoc {
            id: "distribution-validate",
            title: "Every invariant of the model and of the release records",
            description: "Refuses a duplicate target id or triple, two targets deriving one artifact name, a Linux target with no C library, a published target with nothing to build it on, an unbuilt target with no recorded reason, a base URL that is not HTTPS, and a release record that misses a supported target, renames an artifact or serves one from another host. Exits 10 with each violation named.",
            argv: &["distribution", "validate"],
            setup: &[],
            expect: Expect::StdoutContains(&["distribution"]),
        }],
    },
    CommandExamples {
        command: "distribution matrix",
        examples: &[ExampleDoc {
            id: "distribution-matrix",
            title: "The release build matrix the workflow runs",
            description: "One entry per published target, with the runner it is built on, the packages that runner needs, and the artifact name with `{tag}` where a release's tag goes. The release workflow reads this and states no platform of its own; adding a target to the model adds a build here and nowhere else.",
            argv: &["distribution", "matrix"],
            setup: &[],
            expect: Expect::Json(&["/include", "/binary"]),
        }],
    },
    CommandExamples {
        command: "distribution artifact",
        examples: &[ExampleDoc {
            id: "distribution-artifact",
            title: "What one target and one tag are called",
            description: "The one naming function, asked directly: the archive's name, the directory it unpacks into, and where a release publishes it. `scripts/release-package` asks this rather than composing a name, so a change to the naming function reaches the packaging without an edit.",
            argv: &["distribution", "artifact", "--target", "aarch64-apple-darwin", "--tag", "v0.2.0", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/name", "/root", "/url"]),
        }],
    },
    CommandExamples {
        command: "distribution status",
        examples: &[ExampleDoc {
            id: "distribution-status",
            title: "Whether the published one-line installation works right now",
            description: "The operator's question — *can a machine that has never seen this project install it with the advertised command?* — answered from the distribution model and the release records, without touching the network. Each check names what was observed; a failing one names its cause and the command that changes it. Shown here in a repository that has published nothing, where the answer is no and the exit code is 10, which is what makes it usable as a check rather than as prose. `distribution validate` is the gate over the model itself; this is the gate over the state a user meets.",
            argv: &["distribution", "status"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "distribution releases",
        examples: &[ExampleDoc {
            id: "distribution-releases",
            title: "What has been published, and what an unpinned install resolves to",
            description: "Every release record this repository holds, newest first, and which of them the stable pointer names: the highest version among the stable, unwithdrawn records. The pointer is derived on every read and is authored nowhere.",
            argv: &["distribution", "releases"],
            setup: &[],
            expect: Expect::Success,
        }],
    },
    CommandExamples {
        command: "distribution metadata",
        examples: &[ExampleDoc {
            id: "distribution-metadata",
            title: "What one release record publishes",
            description: "The public metadata a record turns into, rendered from the record and the model alone: the release pipeline prints this before it commits anything, and the installer's own tests serve it as a release that never existed. Shown here in a repository that has published nothing, where the record does not exist and the command says which file it wanted and exits 10 rather than inventing one.",
            argv: &["distribution", "metadata", "--record", ".ai/repo/releases/v0.2.0.yaml"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "distribution build",
        examples: &[ExampleDoc {
            id: "distribution-build",
            title: "What this executable is",
            description: "The crate version, the Rust target triple, the profile and the commit, all compiled in at build time. An installed binary answers this without a repository, a toolchain or git, which is what makes a support question answerable.",
            argv: &["distribution", "build"],
            setup: &[],
            expect: Expect::StdoutContains(&["version", "target", "commit"]),
        }],
    },
    CommandExamples {
        command: "mcp",
        examples: &[
            ExampleDoc {
                id: "mcp-inspect",
                title: "See what would be served, without serving it",
                description: "Builds the registry and the index of the repository in the working directory and prints the repository, the capabilities, the objects and every diagnostic, then exits. Nothing is served and nothing is written.",
                argv: &["mcp", "--inspect"],
                setup: &[],
                expect: Expect::StdoutContains(&["repository", "capabilities"]),
            },
            ExampleDoc {
                id: "mcp-inspect-json",
                title: "The same, as one JSON document for a script",
                description: "The shape `--inspect` prints for a person, as JSON: the repository, its discovery mode, the capabilities and the diagnostics, deterministic and safe to diff.",
                argv: &["mcp", "--inspect", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/repository/repository/root", "/tools"]),
            },
            ExampleDoc {
                id: "mcp-stdio",
                title: "Serve one MCP client on stdio",
                description: "The form an MCP client spawns: JSON-RPC frames in on stdin, frames out on stdout, logs on stderr, and the session ends at end of input. `--standalone` keeps this process to itself: no shared server, no HTTP, nothing written anywhere.",
                argv: &["mcp", "--standalone"],
                setup: &[],
                expect: Expect::McpReady,
            },
        ],
    },
    CommandExamples {
        command: "web list",
        examples: &[ExampleDoc {
            id: "web-list",
            title: "Every web surface this repository exposes",
            description: "The resolved topology, in route-precedence order: the routes the executable answers itself, the application's site, and every generated report that declared itself under the generated web root. Nothing is registered anywhere; each line was discovered.",
            argv: &["web", "list"],
            setup: &[],
            expect: Expect::StdoutContains(&["MOUNT", "/api/v1", "/swagger"]),
        }],
    },
    CommandExamples {
        command: "web",
        examples: &[ExampleDoc {
            id: "web-topology",
            title: "The topology, from the command with no subcommand",
            description: "`web` with nothing after it lists, because listing is what a person wants when they ask what this repository exposes.",
            argv: &["web"],
            setup: &[],
            expect: Expect::StdoutContains(&["ID", "MOUNT"]),
        }],
    },
    CommandExamples {
        command: "web explain",
        examples: &[ExampleDoc {
            id: "web-explain",
            title: "Why a surface exists and where each of its values came from",
            description: "For each field a reader could be surprised by — the mount, the kind, the directory — the source that decided it: a producer's own declaration, the site configuration, the capability registry, or the model's documented default.",
            argv: &["web", "explain", "swagger"],
            setup: &[],
            expect: Expect::StdoutContains(&["swagger", "came from"]),
        }],
    },
    CommandExamples {
        command: "web validate",
        examples: &[ExampleDoc {
            id: "web-validate",
            title: "Check the topology before anything serves or publishes it",
            description: "Two surfaces claiming one path, a surface nested inside another's subtree, a directory outside the generated root or one that walks out of the repository: each is a named finding with the surface, the value, its source and the fix. Exit 10 on any error finding. `--artifacts` also requires every static surface's directory and index to exist, which is what serving and publishing need.",
            argv: &["web", "validate"],
            setup: &[],
            expect: Expect::StdoutContains(&["no conflict"]),
        }],
    },
    CommandExamples {
        command: "web manifest",
        examples: &[ExampleDoc {
            id: "web-manifest",
            title: "Write the resolved topology down for another tool to read",
            description: "The manifest under the generated web root is derived state: a publisher or a CI job may read it instead of resolving the topology again, and nothing may edit it, because the next run overwrites it from the same discovery.",
            argv: &["web", "manifest"],
            setup: &[],
            expect: Expect::StdoutContains(&["web manifest", "surface"]),
        }],
    },
    CommandExamples {
        command: "web report tests",
        examples: &[ExampleDoc {
            id: "web-report-tests",
            title: "Render the suite's own results into the /tests surface",
            description: "The runner writes its report with `MJ_TEST_REPORT=<file> bash test/run.sh`; this renders it, keeps the machine-readable results beside the page, and declares the directory so discovery finds it. Without that file there is nothing to render and the command says so rather than publishing an empty page.",
            argv: &["web", "report", "tests", "--suite", "target/web/run.tsv"],
            setup: &[],
            expect: Expect::ExitCode(13),
        }],
    },
    CommandExamples {
        command: "web report benchmarks",
        examples: &[ExampleDoc {
            id: "web-report-benchmarks",
            title: "Render a benchmark run into the /benchmarks surface",
            description: "Reads a results document — a run's own output, or an accepted baseline under the layer's benchmarks section, which have the same shape — and renders every measured target ordered by median. It measures nothing itself: a figure on the page is a figure a run produced.",
            argv: &[
                "web", "report", "benchmarks",
                "--from", ".ai/repo/benchmarks/rust/baseline.macos-aarch64-debug.json",
            ],
            setup: &[],
            expect: Expect::ExitCode(13),
        }],
    },
    CommandExamples {
        command: "web report ui",
        examples: &[ExampleDoc {
            id: "web-report-ui",
            title: "Render the UI conformance audit into /tests/ui",
            description: "`scripts/ui audit` drives a browser over every page of the built site at every width the compiled stylesheet's breakpoints imply, and writes one results document; this renders it. The rendering is a section of the test surface rather than a surface of its own, because a conformance run is a test run and the topology refuses a surface mounted inside another's subtree. Without that document there is nothing to render and the command says so.",
            argv: &["web", "report", "ui", "--from", "target/web/run-ui.json"],
            setup: &[],
            expect: Expect::ExitCode(13),
        }],
    },
    CommandExamples {
        command: "web report ui-snapshot",
        examples: &[ExampleDoc {
            id: "web-report-ui-snapshot",
            title: "Read the UI once and write it as the pages a publication carries at /ui",
            description: "Asks the UI in-process for every screen and panel and then, one page per family in turn until `--limit` pages or `--budget-seconds` are reached, for the pages they link to, and writes each as a file under target/web/ui-snapshot: links between them relative, a link only a running process answers led to the snapshot's page about the live UI, the script told not to read again, and every page stamped with the commit, the time and the executable that read it. The declaration beside it makes the directory a surface of every publication and of no process.",
            argv: &["web", "report", "ui-snapshot", "--limit", "20"],
            setup: &[],
            expect: Expect::StdoutContains(&["web report", "ui-snapshot"]),
        }],
    },
    CommandExamples {
        command: "web report cockpit-snapshot",
        examples: &[ExampleDoc {
            id: "web-report-cockpit-snapshot",
            title: "Read the Cockpit once and write it as the pages a publication carries at /cockpit",
            description: "Asks the Cockpit in-process for every static route except the one page about this machine, then for the pages the UI's snapshot links to, then, one page per family in turn until `--limit` pages or `--budget-seconds` are reached, for the pages those link to, and writes each as a file under target/web/cockpit-snapshot. Links between them are relative; a link into the UI leads to the UI's snapshot when that holds the page; a form, a query or a page past the bound leads to the snapshot's page about the live Cockpit; no page carries a script, because the Cockpit's scripts talk to a process; and every page is stamped with the commit, the time and the executable that read it.",
            argv: &["web", "report", "cockpit-snapshot", "--limit", "12"],
            setup: &[],
            expect: Expect::StdoutContains(&["web report", "cockpit-snapshot"]),
        }],
    },
    CommandExamples {
        command: "web compose",
        examples: &[ExampleDoc {
            id: "web-compose",
            title: "Compose every published surface into one publishable tree",
            description: "Each producer owns its own output directory; publication needs one tree, and the mapping is the resolved mount and nothing else. A surface that is discovered is published without a copy step being written anywhere, and a repository with nothing generated yet composes an empty tree rather than an error. Where a surface exists and its directory does not, composition refuses and names the producer to run.",
            argv: &["web", "compose", "--destination", "target/site"],
            setup: &[],
            expect: Expect::Success,
        }],
    },
    CommandExamples {
        command: "devtask issue",
        examples: &[
            ExampleDoc {
                id: "devtask-issue",
                title: "One issue as work to be done, not as metadata",
                description: "Identity, intent, status, milestone, dependencies, blockers, branches, commits, sessions and readiness in one answer, composed from the derivations that already own each half — the plan for the graph, `trace` for git, the canonical record for everything a person wrote. Nothing is manufactured: a key the record does not carry is `unknown` with the reason, never an empty string that reads as authored.",
                argv: &["devtask", "issue", "I0001"],
                setup: &[],
                expect: Expect::StdoutContains(&["readiness", "explicit"]),
            },
            ExampleDoc {
                id: "devtask-issue-json",
                title: "The same, as the shape the API and MCP answer with",
                description: "One domain model behind every projection: this document is what `GET /api/v1/devtask/issue` returns and what the `majordomus_devtask` tool answers, with the four groups kept apart by the type — what a person authored, what the plan derives, what happened locally, and where the external projection stands — and a provenance on every field.",
                argv: &["devtask", "issue", "I0001", "--no-git", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&[
                    "/declaration/title/provenance",
                    "/position/status/provenance",
                    "/readiness/state",
                    "/attestation/explicit",
                ]),
            },
            ExampleDoc {
                id: "devtask-issue-undeclared",
                title: "An id the model does not declare is answered, not refused",
                description: "A typo that read as \"nothing has been authored\" is the one answer a work surface must never give, so an unknown id answers with `declared: false`, the readiness `undeclared`, and every canonical field `unknown` with the reason on it.",
                argv: &["devtask", "issue", "I9999", "--no-git"],
                setup: &[],
                expect: Expect::StdoutContains(&["undeclared"]),
            },
        ],
    },
    CommandExamples {
        command: "devtask milestone",
        examples: &[
            ExampleDoc {
                id: "devtask-milestone",
                title: "What to work on next in one outcome, and what to unblock first",
                description: "The issues partitioned by readiness, the critical blockers ordered by how much unfinished work each holds back, and the startable work partitioned into subsets that may genuinely run at the same time. A pure function of the canonical records — no git, no clock, no network — so two runs on two machines produce the same bytes and a reader derives nothing itself.",
                argv: &["devtask", "milestone", "foundation"],
                setup: &[],
                expect: Expect::StdoutContains(&["READINESS"]),
            },
            ExampleDoc {
                id: "devtask-milestone-json",
                title: "The graph, as the shape the API and MCP answer with",
                description: "Every partition the plan implies and no surface should recompute: `ready`, `blocked`, `waiting`, `active`, `review`, `completion_blocked`, `complete`, `cancelled`, plus `critical_blockers`, `parallelizable` with the scope path behind each serialisation, and `cycles` as strongly connected components.",
                argv: &["devtask", "milestone", "foundation", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/counts/total", "/ready", "/critical_blockers", "/parallelizable"]),
            },
        ],
    },
    CommandExamples {
        command: "why",
        examples: &[ExampleDoc {
            id: "why-catalogue",
            title: "The operational moments this repository holds",
            description: "`why` with nothing after it lists, because listing is what a person wants when they ask what this section is. The count on the last line is computed from the catalogue; no number anywhere is written down.",
            argv: &["why"],
            setup: &[],
            expect: Expect::StdoutContains(&["SLUG", "moment(s)"]),
        }],
    },
    CommandExamples {
        command: "skills status",
        examples: &[
            ExampleDoc {
                id: "skills-status",
                title: "Every skill, with its derived standing",
                description: "Tested, documented, enforced and used are derived on every read from the tests that name the skill, the evidence ledger, the site projection, the CI model and the invocation surfaces; no file stores them. A repository with no skill answers with none.",
                argv: &["skills", "status"],
                setup: &[],
                expect: Expect::StdoutContains(&["skill(s)"]),
            },
            ExampleDoc {
                id: "skills-status-json",
                title: "The same, as the shape the API and MCP answer with",
                description: "What `GET /api/v1/skills` returns and the `majordomus_skills` tool answers: the count, the tally by standing, and every skill with its four derived facts.",
                argv: &["skills", "status", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/count", "/standings", "/skills"]),
            },
        ],
    },
    CommandExamples {
        command: "skills explain",
        examples: &[ExampleDoc {
            id: "skills-explain-absent",
            title: "A skill the repository does not hold is a refusal, not an empty answer",
            description: "`skills explain <id>` answers one skill in full: each naming test with the state of its latest run and how to reproduce it, its page, its gates and every invocation by path and line. An id that names no skill exits 12 and names what was looked for.",
            argv: &["skills", "explain", "no-such-skill"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "skills verify",
        examples: &[ExampleDoc {
            id: "skills-verify",
            title: "Check every skill is a proven capability",
            description: "An active skill no test names or nothing invokes, a failing run, a contract violation, or a test or invocation naming a skill that does not exist: each a failure, and exit 10. Evidence that is not current, a missing page or a missing gate: a warning.",
            argv: &["skills", "verify"],
            setup: &[],
            expect: Expect::StdoutContains(&["skill(s)", "valid"]),
        }],
    },
    CommandExamples {
        command: "why list",
        examples: &[
            ExampleDoc {
                id: "why-list",
                title: "Every public moment, in presentation order",
                description: "Drafts are excluded unless `--all` is given. The facets a listing may be narrowed by are the ones the catalogue itself reports, so an audience or an area added as a file is a filter without anything being registered.",
                argv: &["why", "list"],
                setup: &[],
                expect: Expect::StdoutContains(&["SLUG"]),
            },
            ExampleDoc {
                id: "why-list-audience",
                title: "Only what one audience recognises",
                description: "Membership is declared by each moment and never listed in the audience's own file, so this answer is derived. An audience the catalogue does not have is an invalid input naming the ones it does, not an empty answer.",
                argv: &["why", "list", "--audience", "fixture-team"],
                setup: &[],
                expect: Expect::StdoutContains(&["SLUG"]),
            },
            ExampleDoc {
                id: "why-list-json",
                title: "The same, as the shape the API and MCP answer with",
                description: "One domain model behind every projection: this document is what `GET /api/v1/why` returns and what the `majordomus_why` tool answers, including the derived facets and the catalogue's fingerprint.",
                argv: &["why", "list", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/counts/moments", "/facets/audiences", "/fingerprint"]),
            },
        ],
    },
    CommandExamples {
        command: "why show",
        examples: &[ExampleDoc {
            id: "why-show",
            title: "One moment, with every relation derived from its metadata",
            description: "The record as its file declares it, then what nobody authored: the responsibilities its claims belong to, the moments that name it, and the moments nearest it by shared area, audience and tag.",
            argv: &["why", "show", "fixture-moment"],
            setup: &[],
            expect: Expect::StdoutContains(&["fixture-moment", "derived"]),
        }],
    },
    CommandExamples {
        command: "why audiences",
        examples: &[ExampleDoc {
            id: "why-audiences",
            title: "Who recognises what, with the counts derived",
            description: "Each audience with how many public moments name it. The number is computed from the moments; an audience's own file never lists one.",
            argv: &["why", "audiences"],
            setup: &[],
            expect: Expect::StdoutContains(&["SLUG", "TITLE"]),
        }],
    },
    CommandExamples {
        command: "why areas",
        examples: &[ExampleDoc {
            id: "why-areas",
            title: "The operational areas, with the counts derived",
            description: "The same relation read the other way: each area with the public moments that fall under it.",
            argv: &["why", "areas"],
            setup: &[],
            expect: Expect::StdoutContains(&["SLUG", "TITLE"]),
        }],
    },
    CommandExamples {
        command: "why diagnose",
        examples: &[
            ExampleDoc {
                id: "why-diagnose-questions",
                title: "The questionnaire, assembled from the catalogue's own signals",
                description: "With no selection there is nothing to diagnose, so the questions are printed instead of an empty answer. Every line is a signal a moment declares; nothing here is a list of questions.",
                argv: &["why", "diagnose"],
                setup: &[],
                expect: Expect::StdoutContains(&["Which of these happened to you this week?"]),
            },
            ExampleDoc {
                id: "why-diagnose",
                title: "What the symptoms you recognise imply",
                description: "A name is a signal id or a moment id. The answer is counting, not inference: each recommendation carries the moments that produced it, and there is no percentage because there is no model behind one.",
                argv: &["why", "diagnose", "--signal", "fixture-signal"],
                setup: &[],
                expect: Expect::StdoutContains(&["moment(s) matched", "fixture-moment"]),
            },
        ],
    },
    CommandExamples {
        command: "why validate",
        examples: &[ExampleDoc {
            id: "why-validate",
            title: "Check the catalogue before anything projects it",
            description: "A reference that resolves to nothing, with the nearest candidate; a duplicate identity; a file name that disagrees with its id; a public record that does not meet the floor its status promises. Exit 10 on any error.",
            argv: &["why", "validate"],
            setup: &[],
            expect: Expect::StdoutContains(&["moment(s)", "valid"]),
        }],
    },
    CommandExamples {
        command: "intent list",
        examples: &[
            ExampleDoc {
                id: "intent-list",
                title: "Every intent, with its derived stage",
                description: "The stage is derived on every read from the status the plan gives each milestone the intent names and from the evidence recorded for each criterion; no file stores it.",
                argv: &["intent", "list"],
                setup: &[],
                expect: Expect::StdoutContains(&["STAGE", "intent(s)"]),
            },
            ExampleDoc {
                id: "intent-list-json",
                title: "The same, as the shape the API and MCP answer with",
                description: "What `GET /api/v1/intents` returns and the `majordomus_intents` tool answers: the count, the tally by stage, and every intent with its milestones and criteria.",
                argv: &["intent", "list", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/count", "/stages", "/intents/0/stage", "/intents/0/satisfaction"]),
            },
        ],
    },
    CommandExamples {
        command: "intent show",
        examples: &[ExampleDoc {
            id: "intent-show",
            title: "One intent, with each milestone and criterion derived",
            description: "The statement and invariants as authored, each milestone with its derived status, and each criterion with the state of its evidence and the command that reproduces it.",
            argv: &["intent", "show", "fixture-intent"],
            setup: &[],
            expect: Expect::StdoutContains(&["fixture-intent", "stage"]),
        }],
    },
    CommandExamples {
        command: "intent validate",
        examples: &[ExampleDoc {
            id: "intent-validate",
            title: "Check the intents before anything relies on them",
            description: "An intent naming no milestone, a milestone or evidence reference that resolves to nothing, governance that names nothing: each a failure, and exit 10. A milestone no intent serves is a warning.",
            argv: &["intent", "validate"],
            setup: &[],
            expect: Expect::StdoutContains(&["intent(s)", "valid"]),
        }],
    },
    CommandExamples {
        command: "intent coverage",
        examples: &[
            ExampleDoc {
                id: "intent-coverage",
                title: "Which work carries which criterion, and why every issue exists",
                description: "Every criterion of every live intent with the issues that serve it and how strongly — covered, weakly covered, observed by the recorded gap, or uncovered — and every issue with the reason it exists: the criteria it serves, or maintenance under a milestone no intent names.",
                argv: &["intent", "coverage"],
                setup: &[],
                expect: Expect::StdoutContains(&["CRITERION", "criterion(s)"]),
            },
            ExampleDoc {
                id: "intent-coverage-json",
                title: "The same, as the shape the API and MCP answer with",
                description: "What `GET /api/v1/intents/coverage` returns and the `majordomus_intent_coverage` tool answers: each criterion with its strength and the issues serving it, and each issue with its origin.",
                argv: &["intent", "coverage", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/criteria/0/strength", "/criteria/0/issues", "/issues/0/origin"]),
            },
        ],
    },
    CommandExamples {
        command: "intent preflight",
        examples: &[ExampleDoc {
            id: "intent-preflight",
            title: "Which intent the work on an issue serves, or why it may not proceed",
            description: "The issue followed through the criteria it declares it serves to the intent each belongs to, with what that intent asks of the worker: its statement, the served criteria and their evidence, invariants, non-goals, governance, critique and gap. A broken link, or an intent whose plan was never critiqued or has a blocking finding open, is a refusal naming its cause, and exit 10; the example fixture's intent has no critique, so this is that refusal. Work under milestones no intent names is maintenance, and exits 0.",
            argv: &["intent", "preflight", "--issue", "I0001"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "intent binding",
        examples: &[ExampleDoc {
            id: "intent-binding",
            title: "What a task is bound to before it starts",
            description: "What `majordomus start --issue` asks: the issue resolved to the intent and the criteria it serves, with what the intent asks of the worker and the two pins a handover carries. The example fixture's intent has no critique, so the binding is refused naming that cause, and exits 10; a bound issue answers `bound`, an issue under a milestone no intent names `maintenance`, and `--exempt <class> --because <reason>` answers `exempt` when the policy declares the class.",
            argv: &["intent", "binding", "--issue", "I0001"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "intent realization",
        examples: &[
            ExampleDoc {
                id: "intent-realization",
                title: "Which work realises which intent, and what each still lacks",
                description: "Every intent with its unmet criteria and the work realising it, then every task, session record and peer claim with its strongest link — declared, observed, derived or inferred — or the first missing link. Exit 10 when an intent whose milestones are all DONE is contradicted by its evidence.",
                argv: &["intent", "realization"],
                setup: &[],
                expect: Expect::StdoutContains(&["fixture-intent", "unit(s) of work"]),
            },
            ExampleDoc {
                id: "intent-realization-json",
                title: "The same, as the shape the API and MCP answer with",
                description: "What `GET /api/v1/intents/realization` returns and the `majordomus_intent_realization` tool answers: each intent's unmet criteria, work and providers, and each unit of work with its links.",
                argv: &["intent", "realization", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/intents/0/stage", "/intents/0/unmet", "/work", "/orphans"]),
            },
        ],
    },
    CommandExamples {
        command: "intent explain",
        examples: &[ExampleDoc {
            id: "intent-explain",
            title: "Why an intent stands where it stands",
            description: "A sentence for the stage naming each milestone's derived status, one per criterion naming its evidence state and coverage, and one for the work realising it — all derived, none stored.",
            argv: &["intent", "explain", "fixture-intent"],
            setup: &[],
            expect: Expect::StdoutContains(&["fixture-intent", "the-case-passes"]),
        }],
    },
    CommandExamples {
        command: "intent propose",
        examples: &[ExampleDoc {
            id: "intent-propose",
            title: "Propose an intent: what must become true",
            description: "Writes a new record under `.ai/repo/project/intents/` holding the statement and nothing else yet (ADR 0144): no milestone, criterion or invariant. Its stage derives as `declared`, `intent validate` reports the two absences as warnings, and no work can serve it until it is planned. `--title` and `--id` default to the statement's first line and that line's slug; an identity that exists is refused, never overwritten.",
            argv: &["intent", "propose", "--statement", "Every page answers within 100 ms when warm"],
            setup: &[],
            expect: Expect::StdoutContains(&[
                "proposed every-page-answers-within-100-ms-when-warm",
                ".ai/repo/project/intents/every-page-answers-within-100-ms-when-warm.yaml",
            ]),
        }],
    },
    CommandExamples {
        command: "serve status",
        examples: &[ExampleDoc {
            id: "serve-status",
            title: "Where this checkout's server stands, and every server of the repository",
            description: "The standing of this checkout's server measured against what this executable would serve, the lease it holds, and every checkout git registers for the repository with its own server. Asked of the running server when there is one, so that the answer includes the lease that process holds; answered locally otherwise.",
            argv: &["serve", "status"],
            setup: &[],
            expect: Expect::StdoutContains(&["standing"]),
        }],
    },
    CommandExamples {
        command: "serve ensure",
        examples: &[ExampleDoc {
            id: "serve-ensure-idle",
            title: "Make sure a server serves this checkout, and let it end when idle",
            description: "Starts a server as a process of its own when none answers, waits until it is ready, and prints one line: the standing, the address, the pid. Run again, it finds the server ready and starts nothing. `--idle` is how long the started server outlives its last peer; one second here, so that the example leaves nothing behind.",
            argv: &["serve", "ensure", "--idle", "1", "--wait", "30"],
            setup: &[],
            expect: Expect::StdoutContains(&["ready"]),
        }],
    },
    CommandExamples {
        command: "serve stop",
        examples: &[ExampleDoc {
            id: "serve-stop-nothing",
            title: "Stop this checkout's server, when there is one",
            description: "Signals the server this checkout's lease names, when it answers for this checkout, and waits for that server's lease to go — the one it read, by its token, so a second process taking the checkout over in the same instant is reported rather than mistaken for a server that would not stop. A checkout with no lease has nothing to stop, and says so.",
            argv: &["serve", "stop"],
            setup: &[],
            expect: Expect::StdoutContains(&["nothing to stop"]),
        }],
    },
    CommandExamples {
        command: "serve",
        examples: &[ExampleDoc {
            id: "serve-ephemeral-port",
            title: "Serve the same capabilities over HTTP on a free port",
            description: "Port 0 asks the operating system for a free port; the address is logged on stderr. `/` is the home page, generated from the surfaces this process resolved; the document at /openapi.json is the same one `majordomus generate` commits; /swagger is the Swagger UI over it; /docs/ is this repository's documentation when it has been built for that mount.",
            argv: &["serve", "--port", "0"],
            setup: &[],
            expect: Expect::HttpReady("/openapi.json"),
        }],
    },
    CommandExamples {
        command: "capabilities list",
        examples: &[
            ExampleDoc {
                id: "capabilities-list-cli",
                title: "Which capabilities the command line itself dispatches to",
                description: "One line per capability exposed through the `cli` projection, with the projections of each. The registry answers this; no list of capabilities is written in the command line's own declaration.",
                argv: &["capabilities", "list", "--exposure", "cli"],
                setup: &[],
                expect: Expect::StdoutContains(&["capabilities.list", "capabilities.describe"]),
            },
            ExampleDoc {
                id: "capabilities-list-json",
                title: "Every capability as one JSON document",
                description: "The whole registry for a script: each capability with its kind, its provenance and every projection it has.",
                argv: &["capabilities", "list", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/capabilities"]),
            },
        ],
    },
    CommandExamples {
        command: "capabilities describe",
        examples: &[ExampleDoc {
            id: "capabilities-describe-objects-get",
            title: "One capability in full, by its canonical id",
            description: "Its kind, its input and output schemas, where it was composed, and every projection of it: the MCP tool or resource, the HTTP route, the CLI path.",
            argv: &["capabilities", "describe", "objects.get"],
            setup: &[],
            expect: Expect::StdoutContains(&["objects.get", "GET /api/v1/object"]),
        }],
    },
    CommandExamples {
        command: "capabilities schema",
        examples: &[ExampleDoc {
            id: "capabilities-schema-output",
            title: "The canonical output schema of a capability",
            description: "The JSON Schema the MCP and OpenAPI projections are derived from; `--side input` prints the schema of what the capability accepts.",
            argv: &["capabilities", "schema", "objects.get", "--side", "output"],
            setup: &[],
            expect: Expect::Json(&["/title"]),
        }],
    },
    CommandExamples {
        command: "capabilities projections",
        examples: &[
            ExampleDoc {
                id: "capabilities-projections-unmet",
                title: "Every exposure a capability claims that its surface does not answer",
                description: "`rows: 0` is the closure `project.interfaces-are-projections` asks for: every declared command line, route and tool is answered by the surface that carries it. The commands no capability claims are reported beside it, as the measure of how much of the command line is still hand-written.",
                argv: &["capabilities", "projections", "--unmet"],
                setup: &[],
                expect: Expect::Success,
            },
            ExampleDoc {
                id: "capabilities-projections-module",
                title: "Where one module's capabilities appear",
                description: "A row per capability with the command line, HTTP route and MCP tool it reaches, so a capability that exists but is reachable from nowhere is visible as one.",
                argv: &["capabilities", "projections", "--module", "worktree"],
                setup: &[],
                expect: Expect::StdoutContains(&["worktree.topology", "majordomus worktree topology"]),
            },
        ],
    },
    CommandExamples {
        command: "capabilities validate",
        examples: &[ExampleDoc {
            id: "capabilities-validate",
            title: "Prove the registry and every projection of it",
            description: "Builds the registry, the MCP and HTTP surfaces, the OpenAPI document, the command line's documentation and the benchmark coverage, and names every failure. Exit 10 when anything is unmet.",
            argv: &["capabilities", "validate"],
            setup: &[],
            expect: Expect::StdoutContains(&["validate: 0 failure(s)", "OK   cli"]),
        }],
    },
    CommandExamples {
        command: "generate",
        examples: &[
            ExampleDoc {
                id: "generate-all",
                title: "Write every committed projection",
                description: "The OpenAPI document, the capability reference, the command-line reference and its JSON, the registry manifest, the benchmark matrix, the shell tool's allow-lists, the provider bootstraps and the site's registry dataset — all from the one registry and the one clap declaration.",
                argv: &["generate"],
                setup: &[],
                expect: Expect::Success,
            },
            ExampleDoc {
                id: "generate-check",
                title: "Refuse a tree whose projections are stale",
                description: "Writes nothing and compares instead: exit 0 when every committed projection is what the sources produce, exit 10 with each stale file named. This is the form CI runs.",
                argv: &["generate", "--check"],
                setup: &[&["generate"]],
                expect: Expect::Success,
            },
            ExampleDoc {
                id: "generate-one-target",
                title: "One target only",
                description: "Each target can be written on its own while a change is iterated on; `majordomus generate` with no target writes all of them.",
                argv: &["generate", "openapi"],
                setup: &[],
                expect: Expect::Success,
            },
            ExampleDoc {
                id: "generate-site-check",
                title: "Check one target without writing it",
                description: "`--check` composes with a target: here only the registry dataset the site renders is compared with what the sources produce, exit 10 naming it when it is stale.",
                argv: &["generate", "site", "--check"],
                setup: &[&["generate", "site"]],
                expect: Expect::Success,
            },
        ],
    },
    CommandExamples {
        command: "bench",
        examples: &[ExampleDoc {
            id: "bench-direct-quick",
            title: "Time the capabilities in process",
            description: "The quick profile takes few samples, and `--transport direct` measures the executor without spawning a server. Nothing is written under .ai/local/ with `--no-write`.",
            argv: &[
                "bench",
                "--transport",
                "direct",
                "--profile",
                "quick",
                "--no-write",
                "--format",
                "json",
            ],
            setup: &[],
            expect: Expect::Json(&["/results", "/profile"]),
        }],
    },
    CommandExamples {
        command: "bench coverage",
        examples: &[
            ExampleDoc {
                id: "bench-coverage-json",
                title: "Every required benchmark target and whether it is covered",
                description: "The denominator is generated from the registry: every executable capability, on every transport it is exposed on, plus the transports' own operations.",
                argv: &["bench", "coverage", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/lines", "/tallies"]),
            },
            ExampleDoc {
                id: "bench-coverage-check",
                title: "Fail when a target is missing",
                description: "Exit 10 when any required target is uncovered or waived, so a capability that nothing times cannot be merged.",
                argv: &["bench", "coverage", "--check"],
                setup: &[],
                expect: Expect::Success,
            },
        ],
    },
    CommandExamples {
        command: "bench baseline update",
        examples: &[ExampleDoc {
            id: "bench-baseline-update-quick",
            title: "Record this platform's accepted baseline",
            description: "Runs the benchmarks and writes the result under .ai/repo/benchmarks/rust/ as a tracked, reviewable file. The full profile is the default; the quick profile is for trying the path out. A dirty work tree is refused unless --allow-dirty says otherwise.",
            argv: &[
                "bench",
                "baseline",
                "update",
                "--profile",
                "quick",
                "--allow-dirty",
            ],
            setup: &[],
            expect: Expect::Success,
        }],
    },
    CommandExamples {
        command: "scope",
        examples: &[
            ExampleDoc {
                id: "scope-declaration",
                title: "What a worker reads of this repository",
                description: "With no path, the declaration itself and the tally: how many tracked files are in the scope and how many are out.",
                argv: &["scope"],
                setup: &[],
                expect: Expect::Success,
            },
            ExampleDoc {
                id: "scope-paths-json",
                title: "Judge paths, and say which rule decided",
                description: "For each path: in or out, and the rule that decided it. `--check` exits 10 when any path given is out, which is how a hook refuses to read one.",
                argv: &["scope", "docs/CLI.md", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/0/verdict", "/0/rule"]),
            },
        ],
    },
    CommandExamples {
        command: "commands",
        examples: &[ExampleDoc {
            id: "commands-list",
            title: "Every command this repository offers",
            description: "The command graph, composed from the three declarations that already exist: the clap tree of this executable, the shipped command registry of the shell tool, and the recipes the workflow runner describes. One line per command, with the program that runs it and what running it changes.",
            argv: &["commands"],
            setup: &[],
            expect: Expect::StdoutContains(&["commands", "executable", "read-only"]),
        }],
    },
    CommandExamples {
        command: "commands list",
        examples: &[ExampleDoc {
            id: "commands-list-filtered",
            title: "Only what reads",
            description: "The filters are the graph's own vocabulary rather than a search over text: `--effect read-only` is every command that changes nothing anywhere, which is the same predicate the exposure policy uses to decide what a machine surface may call.",
            argv: &["commands", "list", "--effect", "read-only"],
            setup: &[],
            expect: Expect::StdoutContains(&["read-only"]),
        }],
    },
    CommandExamples {
        command: "commands show",
        examples: &[ExampleDoc {
            id: "commands-show",
            title: "One command, and every surface that carries it",
            description: "The arguments with the source of each one's values, the effect, and the projections: the command line, the workflow recipe, the MCP tool, the HTTP route, the Cockpit and the page. A surface that withholds it says why.",
            argv: &["commands", "show", "executable.worktree.status"],
            setup: &[],
            expect: Expect::StdoutContains(&["executable.worktree.status", "projections"]),
        }],
    },
    CommandExamples {
        command: "commands explain",
        examples: &[ExampleDoc {
            id: "commands-explain",
            title: "Why a command appears where it does",
            description: "The same command with its provenance: the file that declares it, the reader that found it, the capability behind it when there is one, what it requires, and the file the exposure policy lives in. Nothing about a command's placement is a mystery a grep has to solve.",
            argv: &["commands", "explain", "executable.serve"],
            setup: &[],
            expect: Expect::StdoutContains(&["declared in", "policy"]),
        }],
    },
    CommandExamples {
        command: "commands graph",
        examples: &[ExampleDoc {
            id: "commands-graph-json",
            title: "The whole graph as one document",
            description: "Deterministic and fingerprinted: two builds over one tree produce the same bytes, which is what lets the workflow bridge, the completion index and the Cockpit all key on the fingerprint instead of regenerating.",
            argv: &["commands", "graph", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/schema", "/fingerprint", "/commands"]),
        }],
    },
    CommandExamples {
        command: "commands bridge",
        examples: &[ExampleDoc {
            id: "commands-bridge",
            title: "The workflow runner's recipes, derived",
            description: "Every command of both programs, written as a recipe that runs the canonical program with the caller's own arguments. It goes under .ai/local/cache/, which no commit carries, and it is rewritten only when the graph's fingerprint changes.",
            argv: &["commands", "bridge"],
            setup: &[],
            expect: Expect::StdoutContains(&["bridge", "recipe"]),
        }],
    },
    CommandExamples {
        command: "completion",
        examples: &[ExampleDoc {
            id: "completion-default",
            title: "The integration a person installs once",
            description: "With no subcommand, the shell integration for zsh. It contains no command, no flag and no identifier: every candidate comes from a query against the command graph of the repository the shell is in, so one integration serves every checkout and never goes stale.",
            argv: &["completion"],
            setup: &[],
            expect: Expect::StdoutContains(&["completion query", "compdef"]),
        }],
    },
    CommandExamples {
        command: "completion init",
        examples: &[ExampleDoc {
            id: "completion-init-bash",
            title: "The same, for bash",
            description: "A different shell's protocol, the same question. Both adapters read the words being completed, find the cursor, ask this executable and print what comes back.",
            argv: &["completion", "init", "--shell", "bash"],
            setup: &[],
            expect: Expect::StdoutContains(&["completion query", "complete -F"]),
        }],
    },
    CommandExamples {
        command: "completion query",
        examples: &[ExampleDoc {
            id: "completion-query",
            title: "What a shell asks on every TAB",
            description: "The words of the command line and the position of the cursor; back come the candidates with their descriptions. The same call answers the workflow runner's completion with `--surface workflow`, resolving the recipe name to the command it bridges and then completing that command's own arguments.",
            argv: &["completion", "query", "--surface", "cli", "--", "majordomus", "work"],
            setup: &[],
            expect: Expect::StdoutContains(&["worktree"]),
        }],
    },
    CommandExamples {
        command: "quality report",
        examples: &[
            ExampleDoc {
                id: "quality-summary",
                title: "Where the crate's public surface stands",
                description: "The counts alone: how much of the exported surface is documented and exampled, how many modules something exercises, and how the canonical operations stand against the command line, HTTP, OpenAPI and MCP. Exits 10 when any finding stands outside the recorded baseline.",
                argv: &["quality", "report", "--summary"],
                setup: &[],
                // Success and not a fixed line: a repository that carries no Rust crate is
                // answered with the reason and exits 0, because a rule that cannot apply is
                // not a violation — and the examples run against exactly such a repository.
                expect: Expect::Success,
            },
            ExampleDoc {
                id: "quality-code-json",
                title: "One kind of finding, with the rule and the remedy",
                description: "Filtered to one violation code. Every finding carries the rule that requires it, where it is, why it matters and what to do — which is what lets a person and an agent act on the same report.",
                argv: &[
                    "quality",
                    "report",
                    "--code",
                    "RUST_MODULE_MISSING_EXAMPLE",
                    "--format",
                    "json",
                ],
                setup: &[],
                expect: Expect::Json(&["/measured", "/passes", "/report/schema"]),
            },
        ],
    },
    CommandExamples {
        command: "quality rustdoc",
        examples: &[
            ExampleDoc {
                id: "quality-rustdoc",
                title: "Whether the crate's rustdoc tree is complete, current and sound",
                description: "The rustdoc surface's tree judged against the crate's own inventory: every exported item's page at its route, no page without an item, built from HEAD, the index and its assets present, every relative link resolved, nothing naming the machine or shaped like a credential. Exits 0 clean, 10 with findings, and 12 when there is nothing to judge — as here, in a repository that carries no Rust crate, or wherever the producer (scripts/rust-check --doc) has not run. A check that cannot see its subject says so; it never reports clean.",
                argv: &["quality", "rustdoc"],
                setup: &[],
                expect: Expect::ExitCode(12),
            },
            ExampleDoc {
                id: "quality-rustdoc-tree-json",
                title: "Another copy of the tree, judged the same way",
                description: "A directory named on the command line — the tree scripts/site-build composed into the site — judged by the same judgement, as the document every transport answers with: the verdict, the counts, every exported module with its page, and one typed finding per defect. Only a person at their own terminal names a directory; over HTTP and MCP the subject is always the surface's artifact.",
                argv: &["quality", "rustdoc", "--tree", "site/public/rustdoc", "--format", "json"],
                setup: &[],
                expect: Expect::ExitCode(12),
            },
        ],
    },
    CommandExamples {
        command: "economics summary",
        examples: &[
            ExampleDoc {
                id: "economics-summary",
                title: "What the evidence allows to be said about tokens",
                description: "Every metric with its measurement class, sample size and interval, the state of each suite's evidence, and the one statement the publication rule allows. In a repository that declares no benchmark methodology — which is where the examples run — the statement is that no verified total-token-savings claim is available, and no number is printed.",
                argv: &["economics", "summary"],
                setup: &[],
                expect: Expect::StdoutContains(&["No verified total-token-savings claim"]),
            },
            ExampleDoc {
                id: "economics-summary-json",
                title: "The same answer as the API and MCP give it",
                description: "The typed summary: the verdict, the metrics, the pairs and the segments, exactly as GET /api/v1/economics and the majordomus_economics tool return them.",
                argv: &["economics", "summary", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/present", "/verdict/statement", "/metrics"]),
            },
        ],
    },
    CommandExamples {
        command: "economics explain",
        examples: &[ExampleDoc {
            id: "economics-explain",
            title: "Everything one metric rests on",
            description: "The metric's formula, class, pairs, runs, exclusions and the commands that reproduce it. In a repository that declares no benchmark methodology — which is where the examples run — there is no metric: any id is answered with the statement why, exit 0 and no number. A metric id a declared methodology does not have is refused with the list of those that do (exit 12).",
            argv: &["economics", "explain", "effective_token_reduction"],
            setup: &[],
            expect: Expect::StdoutContains(&["no benchmark methodology is declared"]),
        }],
    },
    CommandExamples {
        command: "economics runs",
        examples: &[ExampleDoc {
            id: "economics-runs-json",
            title: "The raw facts behind every number",
            description: "Every recorded run with its gate verdicts and the totals derived from its provider usage. None where nothing was run.",
            argv: &["economics", "runs", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/count", "/runs"]),
        }],
    },
    CommandExamples {
        command: "economics check",
        examples: &[ExampleDoc {
            id: "economics-check",
            title: "Refuse a savings claim nothing measured",
            description: "Scans the hand-written prose and claim sentences for a quantity next to the economics vocabulary, and checks every claim bound to a metric. Exits 10 naming each finding; exits 0 here, where nothing claims anything.",
            argv: &["economics", "check"],
            setup: &[],
            expect: Expect::StdoutContains(&["economics check:", "0 finding(s)"]),
        }],
    },
    CommandExamples {
        command: "economics measure",
        examples: &[ExampleDoc {
            id: "economics-measure-dry-run",
            title: "Count what the context compiler selects",
            description: "Runs the deterministic context suite: no model is called; every seed's candidates and selection are counted with a pinned tokenizer. Refused with exit 12 where no methodology is declared.",
            argv: &["economics", "measure", "--dry-run"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "economics run",
        examples: &[ExampleDoc {
            id: "economics-run-dry-run",
            title: "Prepare a live suite without spending anything",
            description: "Builds every control and treatment workspace and prints the harness command each session would run; nothing is sent to a provider. Refused with exit 12 where no methodology is declared.",
            argv: &["economics", "run", "--suite", "pilot", "--dry-run"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "economics references",
        examples: &[ExampleDoc {
            id: "economics-references",
            title: "Prove every task can be failed and can be passed",
            description: "Applies each task's reference solution to its fixture: the hidden tests must fail on the starting state and pass on the reference. Refused with exit 12 where no methodology is declared.",
            argv: &["economics", "references"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "devcontext compile",
        examples: &[
            ExampleDoc {
                id: "devcontext-compile-issue",
                title: "The context a session working on one issue should be given",
                description: "The issue is the seed. Its milestone follows along the `belongs_to` edge of the composed graph, the code and the cases under the scope it declares follow from the paths, and the policy and the scope are governance every session is held to. Every selected line names the selector that reached it and why; everything left out is listed with the reason.",
                argv: &["devcontext", "compile", "--issue", "I0001"],
                setup: &[],
                expect: Expect::StdoutContains(&["SELECTED", "majordomus://issue/I0001", "EXCLUDED"]),
            },
            ExampleDoc {
                id: "devcontext-compile-json",
                title: "The same, as the structure every other surface answers with",
                description: "The canonical form: `GET /api/v1/devcontext` and the `majordomus_devcontext` tool return this document. Entries keep their canonical identifier, the index's provenance, every discovery path with its confidence, and the cost in estimated tokens; nothing is flattened to prose.",
                argv: &["devcontext", "compile", "--issue", "I0001", "--format", "json"],
                setup: &[],
                expect: Expect::Json(&["/selected/0/uri", "/selected/0/discovered_by/0/reason", "/budget/limit_tokens", "/fingerprint"]),
            },
        ],
    },
    CommandExamples {
        command: "devcontext explain",
        examples: &[ExampleDoc {
            id: "devcontext-explain-seed",
            title: "Why one thing is in the context",
            description: "The identifier is judged under the same request `compile` takes: selected, excluded with the reason, folded into another identifier, held by the index and never reached, or unknown.",
            argv: &["devcontext", "explain", "majordomus://issue/I0001", "--issue", "I0001"],
            setup: &[],
            expect: Expect::StdoutContains(&["selected", "majordomus://issue/I0001"]),
        }],
    },
    CommandExamples {
        command: "devcontext policy",
        examples: &[ExampleDoc {
            id: "devcontext-policy",
            title: "The compiler's own rules",
            description: "The tiers in the order the budget spends in, every edge kind the composed graph declares with the weight it is followed by or the reason it is refused, and which selectors infer rather than read.",
            argv: &["devcontext", "policy"],
            setup: &[],
            expect: Expect::StdoutContains(&["TIER", "is_a", "REFUSED"]),
        }],
    },
    CommandExamples {
        command: "offload hosts",
        examples: &[ExampleDoc {
            id: "offload-hosts-json",
            title: "The declared hosts, or the answer that there are none",
            description: "Reads the repository's derive-offload declaration (.ai/repo/offload/*.yaml) and prints it with every default filled in: the hosts in tie-break order, each one's free-space minimum and ssh identity file, the queue's paths and the layout on a host. No host is contacted. This fixture declares none, which is an answer, not an error: `declared` is false and the declaration is null.",
            argv: &["offload", "hosts", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/declared", "/declaration"]),
        }],
    },
    CommandExamples {
        command: "offload probe",
        examples: &[ExampleDoc {
            id: "offload-probe-undeclared",
            title: "No declared host, no probe",
            description: "Measures every declared host over ssh — free space under its home, derives running or waiting in its queue — and names the one a derive would take: the eligible host with the fewest, ties to the one declared first. A repository that declares no host has nothing to measure, and the probe refuses with 12 rather than reporting an empty success.",
            argv: &["offload", "probe"],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "offload derive",
        examples: &[ExampleDoc {
            id: "offload-derive-undeclared",
            title: "A derive with nowhere to go is refused before anything travels",
            description: "Sends the worktree as it stands to a declared host as a git bundle, waits its turn in the host's FIFO queue, derives in a build directory of its own and stages the files the derive changed; nothing is committed or pushed. With no host declared it refuses with 12 before it reads the worktree, contacts anything or writes a ref.",
            argv: &["offload", "derive", "."],
            setup: &[],
            expect: Expect::ExitCode(12),
        }],
    },
    CommandExamples {
        command: "guard hook",
        examples: &[ExampleDoc {
            id: "guard-hook",
            title: "Judge the edit a provider's pre-tool payload names",
            description: "What a provider's pre-tool hook runs before an edit: the payload arrives on stdin, and the command exits 2 with the reason and the remedy when no claim covers the path it names, 0 otherwise. Here stdin is empty, so it names no path, and the command lets the tool run.",
            argv: &["guard", "hook", "--provider", "claude-code"],
            setup: &[],
            expect: Expect::Success,
        }],
    },
    CommandExamples {
        command: "mesh status",
        examples: &[ExampleDoc {
            id: "mesh-status",
            title: "Whether this checkout's server runs a mesh",
            description: "The mesh lives inside the shared server, so the command asks the running server for `mesh.status` and renders it. No server, or no mesh declaration, is an answer with its reason — never an error: the default posture is that nothing leaves the machine until a declaration says otherwise.",
            argv: &["mesh", "status"],
            setup: &[],
            expect: Expect::StdoutContains(&["mesh"]),
        }],
    },
    CommandExamples {
        command: "mesh nodes",
        examples: &[ExampleDoc {
            id: "mesh-nodes",
            title: "The nodes the running server has observed",
            description: "One row per node, deduplicated by node identity across every discovery source, in node-id order: trust, presence, endpoints and where each observation came from. The registry lives in the server's memory; without a running server there are no nodes to list, and the command says so.",
            argv: &["mesh", "nodes"],
            setup: &[],
            expect: Expect::StdoutContains(&["mesh"]),
        }],
    },
    CommandExamples {
        command: "mesh identity",
        examples: &[ExampleDoc {
            id: "mesh-identity",
            title: "This machine's node identity, public half only",
            description: "The node id is a digest of the machine's Ed25519 public key, kept under the user's state directory — never inside a repository, and the signing key appears in no output. Absent is an answer: the identity is created when a mesh first activates.",
            argv: &["mesh", "identity"],
            setup: &[],
            expect: Expect::StdoutContains(&["present"]),
        }],
    },
    CommandExamples {
        command: "mesh doctor",
        examples: &[ExampleDoc {
            id: "mesh-doctor",
            title: "Every mesh prerequisite, and the server's verdict on the declaration",
            description: "Deterministic checks in a fixed order — the declaration parses, the identity loads, a UDP socket binds, the multicast group joins, broadcast enables, and the protocol signs, encodes, parses and verifies in memory — then `runtime`: asked of this checkout's running server when one serves it, whether an enabled declaration actually activated the mesh. With no server, as here, the report is this process's and `runtime` says nothing was decided. Every check holds here, so the command exits 0; a failed check is a row that says why, and exits 10.",
            argv: &["mesh", "doctor"],
            setup: &[],
            expect: Expect::StdoutContains(&["protocol"]),
        }],
    },
    CommandExamples {
        command: "mesh firewall",
        examples: &[ExampleDoc {
            id: "mesh-firewall",
            title: "What the host firewall must admit for the declared mesh, and whether it does",
            description: "The admissions derived from the declaration and this machine's addresses — the multicast group's port, the hub ports whose address is this machine's, the server's port beyond loopback — the firewall front this host runs, the commands that admit them there, the firewall's own word about them, and what the kernel logged it dropping toward those ports in the last five minutes. Here, with no declaration, nothing is needed and the report says so; a rule observed missing or a logged drop exits 10.",
            argv: &["mesh", "firewall"],
            setup: &[],
            expect: Expect::StdoutContains(&["backend", "verdict"]),
        }],
    },
    CommandExamples {
        command: "mesh firewall apply",
        examples: &[ExampleDoc {
            id: "mesh-firewall-apply",
            title: "Admit the mesh through the host firewall, as root",
            description: "Runs the commands `mesh firewall` renders — one allow per rule and source network on ufw or nftables, the executable admitted on the macOS application firewall — and asks the firewall again, so the verdict is its own. It refuses, running nothing, without root or without a backend, and exits 10, as here, where nothing is declared and the example does not run as root.",
            argv: &["mesh", "firewall", "apply"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh peers",
        examples: &[ExampleDoc {
            id: "mesh-peers",
            title: "Who cooperates, machine by machine",
            description: "Machines, runtimes, sessions and claims, from this checkout's running server. With no server, or with cooperation off, the answer says so and why — the mesh lives in the server's memory.",
            argv: &["mesh", "peers"],
            setup: &[],
            expect: Expect::StdoutContains(&["cooperation inactive"]),
        }],
    },
    CommandExamples {
        command: "mesh peer",
        examples: &[ExampleDoc {
            id: "mesh-peer",
            title: "One runtime, by its key",
            description: "A runtime's machine, liveness, link, sessions and claims. A runtime the running server does not know is `not found`; with no server there is nobody to ask, and the answer says that rather than reporting an absence it never measured.",
            argv: &["mesh", "peer", "00000000000000000000000000000000-0000000000000000"],
            setup: &[],
            expect: Expect::StdoutContains(&["cooperation inactive"]),
        }],
    },
    CommandExamples {
        command: "mesh state",
        examples: &[ExampleDoc {
            id: "mesh-state",
            title: "The state every linked runtime converges on",
            description: "Sessions, claims with their standing, handovers, reviews and the digest two runtimes compare — or, with no running server, why there is none.",
            argv: &["mesh", "state"],
            setup: &[],
            expect: Expect::StdoutContains(&["cooperation inactive"]),
        }, ExampleDoc {
            id: "mesh-state-live-claims",
            title: "Every claim still held",
            description: "The whole state with only the claims still held, as docs/MESH.md lists it — or, with no running server, why there is none.",
            argv: &["mesh", "state", "--full", "--live-claims"],
            setup: &[],
            expect: Expect::StdoutContains(&["cooperation inactive"]),
        }],
    },
    CommandExamples {
        command: "monitor",
        examples: &[
            ExampleDoc {
                id: "monitor-page",
                title: "What happened in the last half hour",
                description: "One page of the stream — the mesh, the executor's trail and GitHub — with what names you listed first. With no running server the answer is the reason.",
                argv: &["monitor", "--since", "30m", "--for", "1b"],
                setup: &[],
                expect: Expect::StdoutContains(&["no running server"]),
            },
            ExampleDoc {
                id: "monitor-wait",
                title: "Wait for a pull request to merge",
                description: "Follow the stream and exit 0 at the first merge whose summary names #885; `--timeout` gives up with exit 10, as it does here within a second when no server answers.",
                argv: &["monitor", "--follow", "--match", "#885", "--until", "merged", "--timeout", "1s", "--interval", "1"],
                setup: &[],
                expect: Expect::ExitCode(10),
            },
        ],
    },
    CommandExamples {
        command: "mesh events",
        examples: &[ExampleDoc {
            id: "mesh-events",
            title: "One page of the cooperation journal",
            description: "The journal's signed events above a Lamport stamp; `--after` is the previous page's `lamport`. With no running server the answer is the reason.",
            argv: &["mesh", "events", "--after", "0", "--limit", "50"],
            setup: &[],
            expect: Expect::StdoutContains(&["cooperation inactive"]),
        }],
    },
    CommandExamples {
        command: "mesh verify",
        examples: &[ExampleDoc {
            id: "mesh-verify",
            title: "Prove cooperation now, or say why it cannot",
            description: "A live round with every peer the server dials and the local checks, each failure with its impact and remedy. It exits 10 when anything fails — here, because no server runs to verify.",
            argv: &["mesh", "verify"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh claim",
        examples: &[ExampleDoc {
            id: "mesh-claim",
            title: "Claim paths for a session across the mesh",
            description: "An exclusive claim that meets a live exclusive claim on any linked runtime exits 10 with claim_conflict naming it. A claim needs the running server that replicates it; without one the command exits 10 and says so.",
            argv: &["mesh", "claim", "docs", "--session", "s1", "--issue", "#184"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh release",
        examples: &[ExampleDoc {
            id: "mesh-release",
            title: "Release a claim this server holds",
            description: "Only the holder's current run releases a claim; a dead holder's claim expires instead. Without a running server there is nothing to release, and the command exits 10.",
            argv: &["mesh", "release", "stream/c-000000000000"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh session open",
        examples: &[ExampleDoc {
            id: "mesh-session-open",
            title: "Say what a session is doing, to every linked runtime",
            description: "Client, intent, issue and branch of a session, replicated to every linked runtime. It needs the running server; without one it exits 10.",
            argv: &["mesh", "session", "open", "--session", "s1", "--client", "codex", "--issue", "#184"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh session close",
        examples: &[ExampleDoc {
            id: "mesh-session-close",
            title: "Close a session and end its claims",
            description: "Every claim the session holds ends with it, on every linked runtime. It needs the running server; without one it exits 10.",
            argv: &["mesh", "session", "close", "--session", "s1"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh handover publish",
        examples: &[ExampleDoc {
            id: "mesh-handover-publish",
            title: "Publish this checkout's newest handover",
            description: "The newest record under .ai/local/state/handovers/ travels to every linked runtime, bounded and identified by its body's digest. It needs the running server; without one it exits 10.",
            argv: &["mesh", "handover", "publish", "--issue", "#184"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh handover consume",
        examples: &[ExampleDoc {
            id: "mesh-handover-consume",
            title: "Consume a handover another runtime published",
            description: "Records the consumption and writes the handover where `majordomus handover --resolve` finds it on the same branch. It needs the running server; without one it exits 10.",
            argv: &["mesh", "handover", "consume", "00000000000000000000000000000000", "--session", "s1"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh review request",
        examples: &[ExampleDoc {
            id: "mesh-review-request",
            title: "Ask the mesh for a review",
            description: "A named reviewer must be a linked runtime carrying the reviews feature, or the request exits 10 with feature_unsupported. It needs the running server; without one it exits 10.",
            argv: &["mesh", "review", "request", "feature/x", "--session", "s1"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh review answer",
        examples: &[ExampleDoc {
            id: "mesh-review-answer",
            title: "Answer a review request from any runtime",
            description: "approved, changes_requested or commented, with a note, replicated to every linked runtime. It needs the running server; without one it exits 10.",
            argv: &["mesh", "review", "answer", "stream/r-000000000000", "--session", "s1", "--verdict", "approved"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "mesh review withdraw",
        examples: &[ExampleDoc {
            id: "mesh-review-withdraw",
            title: "Withdraw a review request with its result",
            description: "Only the runtime that asked may withdraw its request, from any of its sessions; the note is the requester's own result and never an answer. It needs the running server; without one it exits 10.",
            argv: &["mesh", "review", "withdraw", "stream/r-000000000000", "--session", "s1", "--note", "superseded"],
            setup: &[],
            expect: Expect::ExitCode(10),
        }],
    },
    CommandExamples {
        command: "models list",
        examples: &[ExampleDoc {
            id: "models-list",
            title: "The declared model catalogue",
            description: "Every vendor and model share/models.yaml declares, in declaration order — which is also routing's preference order. Vendors show whether their named credential variable is set: presence only, never a value. An empty catalogue is an answer, not an error.",
            argv: &["models", "list"],
            setup: &[],
            expect: Expect::StdoutContains(&["model(s)"]),
        }],
    },
    CommandExamples {
        command: "models route",
        examples: &[ExampleDoc {
            id: "models-route",
            title: "Which model a need selects, and why",
            description: "The first declared model satisfying every requirement wins; the qualifying rest are the fallback chain, and every excluded model carries the first check it failed. Pure over the declared data — the same question always gets the same answer, and the reasons are in it.",
            argv: &["models", "route", "--require", "text"],
            setup: &[],
            expect: Expect::StdoutContains(&["selected"]),
        }],
    },
    CommandExamples {
        command: "reasoning advisors",
        examples: &[ExampleDoc {
            id: "reasoning-advisors",
            title: "The advisors, and what they can do now",
            description: "Every declared advisor with its status and why — available, unavailable, not_configured, disabled, temporarily_failed, rate_limited — from presence alone (an executable on PATH, a credential variable set, never a value), the mode in force and the recorded outcomes of earlier consultations; then who can provide each advisory capability now. Reasoning is operational whether or not any advisor is.",
            argv: &["reasoning", "advisors"],
            setup: &[],
            expect: Expect::StdoutContains(&["reasoning   operational"]),
        }, ExampleDoc {
            id: "reasoning-advisors-json",
            title: "The same answer as one document",
            description: "The report the API and the MCP tool return: `operational`, the mode and what decided it, every advisor with its status and reason, and the capacity per capability. A script reads this rather than the text form.",
            argv: &["reasoning", "advisors", "--format", "json"],
            setup: &[],
            expect: Expect::Json(&["/operational", "/mode", "/advisors", "/capacity"]),
        }],
    },
    CommandExamples {
        command: "reasoning plan",
        examples: &[ExampleDoc {
            id: "reasoning-plan",
            title: "What a material uncertainty calls for",
            description: "Whether independent review is worth having, how many advisors the mode allows, which available advisors a capability-driven selection asks, and why every other advisor is left out. With no suitable advisor the plan is the structured local review. Nothing is recorded.",
            argv: &["reasoning", "plan", "--materiality", "material"],
            setup: &[],
            expect: Expect::StdoutContains(&["outcome", "budget"]),
        }, ExampleDoc {
            id: "reasoning-plan-capabilities",
            title: "A high uncertainty that asks for named capabilities",
            description: "The selection covers the requested capabilities first, then prefers an advisor reached through a different adapter, then declaration order; every advisor not selected carries its reason. With none available the outcome is the structured local review.",
            argv: &["reasoning", "plan", "--materiality", "high", "--capabilities", "independent_reasoning,code_review"],
            setup: &[],
            expect: Expect::StdoutContains(&["outcome", "budget"]),
        }],
    },
    CommandExamples {
        command: "reasoning record",
        examples: &[ExampleDoc {
            id: "reasoning-record-refused",
            title: "Input that is not a record is refused",
            description: "The writer reads one JSON record (`{\"kind\":\"assessment\",...}`) from --file or standard input. Anything else — here a YAML file — is refused with exit 13 and nothing is written; so is a record that breaks a rule, such as a plan for an assessment nobody recorded.",
            argv: &["reasoning", "record", "--file", "share/advisors.yaml"],
            setup: &[],
            expect: Expect::ExitCode(13),
        }],
    },
    CommandExamples {
        command: "reasoning status",
        examples: &[ExampleDoc {
            id: "reasoning-status",
            title: "The reasoning state of the open task",
            description: "Assessments and where each stands, consultations and how each ended, disagreements and what settled them, conclusions with their computed review and validation, and the timeline — derived from the records alone.",
            argv: &["reasoning", "status", "--task", "all"],
            setup: &[],
            expect: Expect::StdoutContains(&["records"]),
        }],
    },
    CommandExamples {
        command: "reasoning explain",
        examples: &[ExampleDoc {
            id: "reasoning-explain-absent",
            title: "Why a decision was made",
            description: "One record with the whole chain of its assessment. An id nothing recorded is refused as not found.",
            argv: &["reasoning", "explain", "conclusion-absent"],
            setup: &[],
            expect: Expect::ExitCode(13),
        }],
    },
    CommandExamples {
        command: "reasoning check",
        examples: &[ExampleDoc {
            id: "reasoning-check",
            title: "Check that reasoning stays provider-independent",
            description: "The advisor catalogue's references, the transport adapters, the provider-independent sources, CI, the documents and every stored record; exit 10 on a finding.",
            argv: &["reasoning", "check"],
            setup: &[],
            expect: Expect::StdoutContains(&["checks"]),
        }],
    },
];

#[derive(Debug, clap::Args)]
/// `majordomus commit`: the commit as a value.
///
/// Three questions, all read-only: what the working tree would commit, which scopes the
/// history uses, and whether one message passes. Making the commit is `git commit`, which
/// the `commit-msg` hook puts the third of these in front of — the executable proposes and
/// judges, and a person commits.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, CommitArgs, CommitCommand, OutputFormat};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "commit", "history", "origin/master..HEAD", "--format", "json",
/// ])
/// .unwrap();
/// let args: CommitArgs = match cli.command {
///     Command::Commit(args) => args,
///     other => panic!("expected `commit`, parsed {other:?}"),
/// };
/// // `--format` is global, so it parses after the subcommand, where a person writes it
/// assert!(matches!(args.format, OutputFormat::Json));
/// assert!(matches!(
///     args.command,
///     Some(CommitCommand::History { range: Some(ref r) }) if r == "origin/master..HEAD"
/// ));
///
/// // unlike the other groups this one does answer bare, because planning is what somebody
/// // asking about committing wants; `None` is `plan` rather than a usage error
/// let bare = Cli::try_parse_from(["majordomus", "commit"]).unwrap();
/// assert!(matches!(bare.command, Command::Commit(CommitArgs { command: None, .. })));
/// ```
pub struct CommitArgs {
    #[command(flatten)]
    /// Where and how the repository is read.
    pub repo: RepoArgs,

    #[command(subcommand)]
    /// The subcommand; none is `plan`.
    pub command: Option<CommitCommand>,

    #[arg(long, value_enum, default_value_t = OutputFormat::Text, global = true)]
    /// Output shape
    pub format: OutputFormat,
}

#[derive(Debug, Subcommand)]
/// The subcommands of `majordomus commit`: `plan`, `scopes`, `history` and `validate`.
///
/// All four are read-only. `validate` is the one the `commit-msg` hook runs, and its shape
/// is the hook's: the file git will take the message from, and the paths that are staged,
/// so that a `fix` carrying no test among its files is judged rather than guessed at.
///
/// ```
/// use clap::Parser;
/// use majordomus_cli::cli::{Cli, Command, CommitCommand};
///
/// let cli = Cli::try_parse_from([
///     "majordomus", "commit", "validate", ".git/COMMIT_EDITMSG",
///     "--paths", "apps/majordomus-cli/src/commit/mod.rs,test/cases/274_commit_policy.sh",
/// ])
/// .unwrap();
/// let args = match cli.command {
///     Command::Commit(args) => args,
///     other => panic!("expected `commit`, parsed {other:?}"),
/// };
/// // `--paths` is comma-delimited, so the hook can hand over one `git diff --cached` line
/// assert!(matches!(
///     args.command,
///     Some(CommitCommand::Validate { file: Some(ref f), ref paths, rev: None })
///         if f == ".git/COMMIT_EDITMSG" && paths.len() == 2
/// ));
///
/// // a revision instead of a file judges a commit already made, and the two are exclusive
/// assert!(Cli::try_parse_from(["majordomus", "commit", "validate", "--rev", "HEAD"]).is_ok());
/// assert!(Cli::try_parse_from(["majordomus", "commit", "validate", "m.txt", "--rev", "HEAD"])
///     .is_err());
/// ```
pub enum CommitCommand {
    /// What the working tree would commit: branch, upstream, divergence, every staged, unstaged and untracked path, any merge or rebase in progress, and the commits the history's own scoping supports — under a fingerprint that makes the plan refusable once the tree moves
    Plan,
    /// Every scope this repository's commit history uses, how often, and the directories each one is written about
    Scopes,
    /// Judge every commit in a range of history against the commit policy, in one pass; exit 10 when any carries an error
    History {
        /// Anything `git log` accepts: `origin/master..HEAD`, `v0.6.0..`, a bare `HEAD`. None is `HEAD`
        #[arg(value_name = "RANGE")]
        range: Option<String>,
    },
    /// Judge one commit message against the repository's commit policy; exit 10 when a finding is an error
    Validate {
        /// The file holding the message; none reads standard input, which is what the `commit-msg` hook has
        #[arg(value_name = "FILE")]
        file: Option<String>,

        /// Judge it as a commit of these paths, comma-separated: what needs them — whether a fix carries a test — is otherwise not judged rather than guessed
        #[arg(long, value_name = "PATHS", value_delimiter = ',')]
        paths: Vec<String>,

        /// Judge the message of this commit instead of a file: any revision `git show` accepts
        #[arg(long, value_name = "REV", conflicts_with = "file")]
        rev: Option<String>,
    },
}

#[cfg(test)]
mod tests {
    use super::*;
    use clap::Parser;

    fn view(args: &[&str]) -> MeshViewArgs {
        let cli = Cli::try_parse_from(["majordomus", "mesh", "state"].iter().chain(args))
            .expect("the flags parse");
        let Command::Mesh(mesh) = cli.command else {
            panic!("expected `mesh`")
        };
        let MeshCommand::State(view) = mesh.command else {
            panic!("expected `state`")
        };
        view
    }

    /// Every flag of a mesh view is one pair of the query, in the order the flags are
    /// declared whatever order they were written in; no flag is no pair.
    #[test]
    fn every_mesh_view_flag_is_one_query_pair_in_declared_order() {
        let all = view(&[
            "--matching",
            "src/x.rs",
            "--open",
            "--limit",
            "5",
            "--kind",
            "claims",
            "--runtime",
            "n1-r1",
            "--session",
            "s-1",
            "--after",
            "42",
            "--live-claims",
            "--full",
        ]);
        assert_eq!(
            all.pairs(),
            [
                "view=full",
                "claims=live",
                "after=42",
                "session=s-1",
                "runtime=n1-r1",
                "kind=claims",
                "limit=5",
                "open=true",
                "matching=src/x.rs",
            ]
        );
        assert!(view(&[]).pairs().is_empty());
    }

    /// A duration is seconds when it names no unit, and each unit scales it; a number that
    /// is not one and a unit that is not known are refused in words that say which.
    #[test]
    fn a_duration_is_read_in_its_unit_and_refused_in_words() {
        assert_eq!(parse_duration(" 90 "), Ok(90));
        assert_eq!(parse_duration("2d"), Ok(172_800));
        let not_a_number = parse_duration("soon").unwrap_err();
        assert!(not_a_number.contains("is not a duration"), "{not_a_number}");
        let unknown = parse_duration("3w").unwrap_err();
        assert!(unknown.contains("unknown unit"), "{unknown}");
    }
}