mind-cli 0.24.0

//! The `mind` command-line surface.
//!
//! Verbs use a knowledge metaphor:
//!   meld   -> connect to a source repo
//!   learn  -> install an item
//!   forget -> remove an item
//!   sync   -> refresh source catalogs
//!   upgrade -> upgrade installed items
//!   evolve -> upgrade the mind binary itself
//!   recall -> show what's installed
//!   probe  -> find available items
//!   introspect -> diagnose drift

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

/// The lifecycle event for `mind hooks run --event`.
// spec: CLI-195
#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
pub enum HookEventArg {
    /// Run install hooks (default). Valid for source and item targets.
    Install,
    /// Run uninstall hooks. Valid for source and item targets.
    Uninstall,
    /// Re-install the item through the transactional build path (stage, build,
    /// swap). Valid for item targets only; a source has no build hook.
    Build,
}

use crate::error::ItemKind;

/// An item kind as accepted on the command line (`--kind skill|agent|rule|tool`).
#[derive(Debug, Clone, Copy, ValueEnum)]
pub enum KindArg {
    Skill,
    Agent,
    Rule,
    Tool,
}

impl KindArg {
    pub fn to_kind(self) -> ItemKind {
        match self {
            KindArg::Skill => ItemKind::Skill,
            KindArg::Agent => ItemKind::Agent,
            KindArg::Rule => ItemKind::Rule,
            KindArg::Tool => ItemKind::Tool,
        }
    }
}

// spec: CLI-207 -- with no arguments, print full help to stdout and exit 0
// (clap's default for a required subcommand with no arguments is a usage
// error on stderr at exit 2). `command` stays a required (non-Option) enum:
// bare `mind` still does not launch the TUI (TUI-1/TUI-2), it prints help.
#[derive(Debug, Parser)]
#[command(
    name = "mind",
    version,
    about = "A manager for agent tooling: skills, agents, rules, and tools.",
    propagate_version = true,
    arg_required_else_help = true
)]
pub struct Cli {
    /// Emit machine-readable JSON instead of formatted text. `dump`,
    /// `completions`, `man`, and `init-source` emit their own artifact
    /// (a TOML/script/roff/manifest document) regardless of this flag.
    #[arg(long, global = true, help_heading = "Global options")]
    pub json: bool,

    /// Skip confirmation prompts (assume yes).
    #[arg(short = 'y', long, global = true, help_heading = "Global options")]
    pub yes: bool,

    /// Force plain ASCII output (no color, no Unicode glyphs).
    #[arg(long, global = true, help_heading = "Global options")]
    pub ascii: bool,

    /// Emit extra advisory output (e.g. unguarded-reference warnings on meld).
    #[arg(short = 'v', long, global = true, help_heading = "Global options")]
    pub verbose: bool,

    #[command(subcommand)]
    pub command: Command,
}

#[derive(Debug, Subcommand)]
pub enum Command {
    /// Meld with a source repo and install its items (prompts to install; use `--register-only` to skip).
    // spec: CLI-173
    #[command(
        visible_alias = "add",
        after_help = "\
EXAMPLES:
    mind meld owner/repo
    mind meld https://github.com/owner/repo --namespace acme
    mind meld . --register-only"
    )]
    Meld {
        /// Repo spec to meld. Supported forms:
        ///
        /// - Local path:   `/path/to/repo`  or  `file:///path/to/repo`  or  `.`
        ///
        /// - GitHub HTTPS: `owner/repo`  or  `https://github.com/owner/repo`
        ///
        /// - GitHub SSH:   `git@github.com:owner/repo`
        ///
        /// - Any git URL:  `https://example.com/repo.git`
        ///
        /// - Item link:    `https://host/owner/repo/tree/<ref>/<path>` (or the
        ///   `blob/.../SKILL.md` form): registers a single-item source offering
        ///   just that skill
        ///
        /// Defaults to the current directory (`.`) when omitted.
        repo: Option<String>,

        /// Namespace every item from this source under this prefix
        /// (overrides the repo's own `[source].prefix`). The prefix is part of
        /// the source's identity: melding an already-melded repo under a
        /// different prefix registers a distinct `host/owner/repo@<prefix>`
        /// instance that coexists with the original, rather than re-prefixing it.
        /// `--as` is a hidden deprecated alias for backwards compatibility.
        // spec: CLI-163 - short moved to -N (uppercase); -n is reserved for --dry-run.
        #[arg(short = 'N', long = "namespace", alias = "as", value_name = "PREFIX")]
        alias: Option<String>,

        /// Set the version this source tracks (overrides the repo's [source] pin
        /// directive). Takes one required value. `HEAD` freezes the current
        /// resolved tip (the point that would otherwise be melded) to its commit.
        /// A bare `<tag|sha|branch>` resolves that ref to its current commit and
        /// freezes it (a snapshot, not a track). `branch=<name>` follows that
        /// branch (floating; `sync` advances it); `tag=<name>` follows that tag
        /// (re-points on `sync` if it moves). With no `--pin`, the repo's
        /// `[source]` pin directive (else the remote default branch) applies.
        /// Unlike the discovery flags below, this ALSO takes effect against an
        /// already-melded source: a re-meld with `--pin` re-pins it, re-checking
        /// out the clone if the resolved commit differs and reporting what changed.
        // spec: CLI-200, CLI-201, CLI-209
        #[arg(long, value_name = "HEAD|REF|branch=NAME|tag=NAME")]
        pin: Option<String>,

        /// Deprecated: use `--pin branch=<name>`.
        // spec: CLI-202
        #[arg(long, value_name = "BRANCH", hide = true)]
        follow_branch: Option<String>,

        /// Deprecated: use `--pin tag=<name>`.
        // spec: CLI-202
        #[arg(long, value_name = "TAG", hide = true)]
        pin_tag: Option<String>,

        /// Deprecated: use `--pin <commit>`.
        // spec: CLI-202
        #[arg(long, value_name = "COMMIT", hide = true)]
        pin_ref: Option<String>,

        /// Set the source's convention-scan roots to one or more repo-root-relative
        /// directories (repeatable). Overrides `[source].roots` in mind.toml.
        /// Persisted on the source and used by later scans and sync. Only takes
        /// effect at the meld that registers the source: passing it against an
        /// already-melded source is ignored (a note lists it and points at
        /// `unmeld` + `meld` to change it).
        // spec: CLI-206
        #[arg(long = "root", value_name = "DIR")]
        roots: Vec<String>,

        /// Add convention-scan roots that compose with the source's own
        /// discovery (repeatable): a plugin/marketplace manifest or an
        /// authoritative mind.toml keeps its items and each added root is
        /// convention-scanned in addition, so items the source does not
        /// declare become installable. Unlike --root, this does not override
        /// or suppress anything. Persisted on the source and used by later
        /// scans and sync. Only takes effect at the meld that registers the
        /// source: passing it against an already-melded source is ignored (a
        /// note lists it and points at `unmeld` + `meld` to change it).
        // spec: CLI-206
        #[arg(long = "add-root", value_name = "DIR")]
        add_roots: Vec<String>,

        /// Force-enable flat skill discovery: skills are bare-name directories at
        /// each scan root, with no `skills/` container. Turns the layout on for a
        /// source that did not declare `[source].flat-skills`; there is no way to
        /// disable a source's declared flat layout. Applies to skills only (agent,
        /// rule, and tool discovery are unaffected) and to convention discovery
        /// only (ignored for an authoritative `mind.toml`). Persisted on the source
        /// and used by later scans and sync. Only takes effect at the meld that
        /// registers the source: passing it against an already-melded source is
        /// ignored (a note lists it and points at `unmeld` + `meld` to change it).
        // spec: CLI-206
        #[arg(long)]
        flat_skills: bool,

        /// Supply or override the source's install hook: a shell command run
        /// after checkout to build the tooling its items rely on. Before it runs,
        /// a prompt offers three choices: run it (the default, a bare Enter),
        /// skip it but still install the source, or abort and install nothing.
        /// Overriding a declared `[source].install` is shown loudly in that
        /// prompt. Use `mind review <repo>` to see a source's declared hook
        /// before melding. Only takes effect at the meld that registers the
        /// source: passing it against an already-melded source is ignored (a
        /// note lists it and points at `unmeld` + `meld` to change it).
        // spec: CLI-206
        #[arg(long, value_name = "CMD")]
        install_hook: Option<String>,

        /// Run the install hook without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run (CI, scripts) skips the hook and just
        /// prints a note, so the tooling is not built; pass this to run it unattended.
        #[arg(long)]
        dangerously_skip_install_hook_check: bool,

        /// Run item build hooks without the safety prompt during the install-all
        /// pass. This executes arbitrary code from the source; only use it for a
        /// source you trust. Without this flag, a non-TTY run skips build hooks
        /// and prints a note, so the item's tooling is not built.
        #[arg(long)]
        dangerously_skip_build_hook_check: bool,

        /// Only register the source; do not prompt to install its items. By
        /// default, `meld` previews the source's items and offers to install them
        /// all (the interactive form of `learn '<source>#*'`).
        // spec: CLI-165 - canonical name; --link-only is a hidden deprecated alias.
        #[arg(long, alias = "link-only")]
        register_only: bool,

        /// Offer to install the items of every nested source a super-source
        /// curates (`[discover].sources`), not just the super-source's own items
        /// and the nested sources the curator marked `install = true`.
        #[arg(short = 'r', long)]
        recursive: bool,

        /// When installing, overwrite link targets that already exist and are not
        /// managed by mind. Without it, a conflict prompts on a TTY. On a re-meld
        /// of an already-melded source, `--force` ALSO re-offers every one of the
        /// source's install hooks, even those already run at the current commit
        /// (not just the pending ones an ordinary re-meld re-offers).
        // spec: HOOK-60
        #[arg(short = 'f', long)]
        force: bool,

        /// Install the source's item(s) into ONLY the current project's lobe --
        /// a registered lobe whose directory lives under the current working
        /// directory -- instead of fanning them into every configured agent
        /// home (the default). Errors when the current directory is not inside
        /// any registered project lobe.
        // spec: HARN-20 HARN-21
        #[arg(long)]
        local: bool,
    },

    /// Scaffold a `mind.toml` and report the references among a source's items.
    ///
    /// For source maintainers: discovers the items the repo offers, reports which
    /// items reference which siblings, and creates a starter `mind.toml` if none
    /// exists. With `--template`, also rewrites bare sibling references into
    /// `{{ns:}}` tokens so the source stays resolvable under a prefix.
    InitSource {
        /// The source repo directory (default the current directory).
        path: Option<String>,

        /// Rewrite bare sibling references into `{{ns:name}}` tokens. This edits
        /// the repo's item files; it is heuristic, so review the result.
        #[arg(long)]
        template: bool,

        /// Generate `.claude-plugin/marketplace.json` for Claude plugin
        /// compatibility. Skipped if the file already exists.
        #[arg(long)]
        marketplace: bool,

        /// Set `flat-skills = true` in `[source]` in `mind.toml` and use flat
        /// skill layout for discovery. With `--marketplace`, populates the
        /// `skills` array in the generated manifest.
        #[arg(long)]
        flat_skills: bool,

        /// Override the plugin name / `[source].prefix` written to `mind.toml`
        /// and the marketplace manifest `name` field.
        // spec: CLI-163 - short moved to -N (uppercase).
        #[arg(short = 'N', long)]
        namespace: Option<String>,
    },

    /// Unmeld a source, uninstalling every item the source installed.
    ///
    /// Unmelds a source and uninstalls every item the source installed; use
    /// `--keep-items` to keep them.
    ///
    /// `<name>` is a REF: it must resolve to exactly one source. It may be the
    /// full `host/owner/repo` or an unambiguous trailing suffix (e.g. `repo`
    /// or `owner/repo`); a non-glob name matching more than one source errors
    /// instead of guessing. A glob (`*`, `?`, `[`) removes every matching
    /// source. Contrast `sync`'s `[source]`, which is a FILTER: it may match
    /// several sources even without a glob, and every match is acted on.
    // spec: CLI-174 - long_about leads with the uninstall default.
    // spec: CLI-172 - the former `detach` alias is removed.
    // spec: CLI-230 - `remove`/`rm` visible aliases, for symmetry with learn's
    // install/uninstall aliases.
    #[command(visible_aliases = ["remove", "rm"], after_help = "\
EXAMPLES:
    mind unmeld github.com/acme/agents
    mind unmeld acme/agents --keep-items
    mind unmeld '*agents' --yes")]
    Unmeld {
        /// The source ref (see `mind recall --sources`): must resolve to
        /// exactly one source, unless it is a glob.
        name: String,

        /// Remove only the source, leaving its installed items in place (the
        /// opt-out from the default item removal, mirroring `meld --register-only`).
        // spec: CLI-166 - canonical name; --unlink-only is a hidden deprecated alias.
        #[arg(long, alias = "unlink-only")]
        keep_items: bool,

        /// Supply or override the source's uninstall hook: a shell command run
        /// in the clone before the source is removed. Replaces the source's
        /// declared uninstall hook(s); the override is shown loudly in the prompt.
        #[arg(long, value_name = "CMD")]
        uninstall_hook: Option<String>,

        /// Run uninstall hooks without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips the hook and prints a note.
        /// `--dangerously-skip-install-hook-check` is a deprecated alias kept for
        /// backwards compatibility.
        // spec: CLI-227 - renamed from --dangerously-skip-install-hook-check,
        // which gated an UNINSTALL hook despite its name; old spelling is a
        // hidden alias.
        #[arg(
            long = "dangerously-skip-hook-check",
            alias = "dangerously-skip-install-hook-check"
        )]
        dangerously_skip_install_hook_check: bool,
    },

    /// Install items into every configured agent home (default ~/.claude).
    ///
    /// The item ref may be exact, or a glob to install many: `'*'` for everything,
    /// `'skill:*'` for all skills, `'owner/repo#*'` for all of one source.
    ///
    /// When selecting a subset of a source's items, `learn` also installs the
    /// intra-source `{{ns:}}` dependencies those items reference (the closure),
    /// printing a dependency tree and prompting before installing; `--dry-run`
    /// previews the closure without installing anything and `--yes` skips the prompt.
    // spec: CLI-172
    #[command(
        visible_alias = "install",
        after_help = "\
EXAMPLES:
    mind learn review
    mind learn 'skill:*'
    mind learn owner/repo --all"
    )]
    Learn {
        /// Item ref or glob: `name`, `skill:name`, `owner/repo#name`, `'review*'`, `'*'`.
        /// Also accepts a deep tree/blob URL to one skill
        /// (`https://host/owner/repo/tree/<ref>/<path>`): the repo registers as a
        /// single-item source and the skill installs in one step.
        item: String,

        /// Install every item of the source named by the ref. Shorthand for the
        /// `<source>#*` selector; rejected if the ref already has a `#` selector.
        #[arg(long)]
        all: bool,

        /// For a deep tree/blob URL, freeze the link's branch ref to its current
        /// commit when registering the single-item source, so the instance is an
        /// immutable snapshot instead of tracking the branch. This is a bare flag
        /// that takes NO value (unlike `meld --pin <REF>`, which takes one): the
        /// ref to freeze comes from the URL itself, so there is nothing to
        /// supply. Ignored (with a note) for a non-URL item ref, which names an
        /// already-melded source.
        // spec: CLI-200 - learn's --pin is intentionally bare (arity 0), NOT
        // symmetric with meld's `--pin <value>`: learn resolves items from an
        // already-melded source or a URL whose ref is in the URL, so there is no
        // ref value for the flag to accept.
        #[arg(long)]
        pin: bool,

        /// Show what would be installed without installing anything.
        #[arg(short = 'n', long = "dry-run")]
        dry_run: bool,

        /// Overwrite a link target that already exists and is not managed by
        /// mind (a user's file/dir/foreign link). Without it, a conflict prompts
        /// on a TTY and otherwise refuses.
        #[arg(short = 'f', long)]
        force: bool,

        /// Run an item's install hook without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips the hook and prints a note.
        #[arg(long)]
        dangerously_skip_install_hook_check: bool,

        /// Run an item's build hook without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips the build hook and prints a
        /// note, so the item's tooling is not built.
        #[arg(long)]
        dangerously_skip_build_hook_check: bool,

        /// Install the item(s) into ONLY the current project's lobe -- a
        /// registered lobe whose directory lives under the current working
        /// directory -- instead of fanning them into every configured agent home
        /// (the default). Errors when the current directory is not inside any
        /// registered project lobe.
        // spec: HARN-20 HARN-21
        #[arg(long)]
        local: bool,
    },

    /// Remove an installed item, or many via a glob.
    ///
    /// With `--unmanaged`, the removal is scoped to unmanaged lobe items only
    /// (the deliberate inverse of the default, which matches managed items only).
    /// With no `<item>` and `--unmanaged`, every unmanaged item across all
    /// configured lobes is removed.
    // spec: CLI-172 - added `uninstall` visible alias; `unlearn` kept.
    #[command(
        visible_aliases = ["unlearn", "uninstall"],
        after_help = "\
EXAMPLES:
    mind forget review
    mind forget 'skill:*' --yes
    mind forget --unmanaged"
    )]
    Forget {
        /// The installed item ref or glob: `name`, `skill:name`, `'review*'`, `'*'`.
        /// With `--unmanaged`: the ref or glob scopes removal to unmanaged items only;
        /// omit to remove every unmanaged item across all lobes.
        #[arg(required_unless_present = "unmanaged")]
        item: Option<String>,

        /// Scope removal to unmanaged lobe items only (the deliberate inverse of the
        /// default, which matches managed items only). With no ref it removes every
        /// unmanaged item across all configured lobes.
        #[arg(long)]
        unmanaged: bool,

        /// Skip the dependents confirmation when removing a single item that
        /// other installed items depend on. Without this flag, `forget` warns
        /// and prompts; with it, removal proceeds immediately. The global
        /// `--yes` also skips this same prompt, but additionally skips the
        /// separate confirmation shown when a glob would remove more than one
        /// item; `--force` alone skips only the dependents prompt.
        // spec: DEP-60 CLI-42
        #[arg(short = 'f', long)]
        force: bool,

        /// Run an item's uninstall hook without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY run skips the hook and prints a note.
        /// `--dangerously-skip-install-hook-check` is a deprecated alias kept for
        /// backwards compatibility.
        // spec: CLI-227 - renamed from --dangerously-skip-install-hook-check,
        // which gated an UNINSTALL hook despite its name; old spelling is a
        // hidden alias.
        #[arg(
            long = "dangerously-skip-hook-check",
            alias = "dangerously-skip-install-hook-check"
        )]
        dangerously_skip_install_hook_check: bool,
    },

    /// Refresh melded source clones and catalogs (all, or only those matching
    /// `[source]`).
    ///
    /// `[source]` is a FILTER, not a ref (contrast `unmeld`'s source-name
    /// selection, which must resolve to exactly one source): it may match
    /// several sources with no ambiguity check, and every match is synced --
    /// that is intentional, since `sync` is a non-destructive refresh.
    // spec: CLI-172
    #[command(visible_alias = "update")]
    Sync {
        /// Only sync the source(s) matching this filter: an exact name, a
        /// trailing suffix like `repo` or `owner/repo` (every source it
        /// matches is synced -- unlike `unmeld`'s ref-style source
        /// selection, a filter is never ambiguous: more than one match is
        /// normal, not an error), or a glob. With no filter, every melded
        /// source is synced. A filter also skips the whole-set-only steps:
        /// managed-policy auto-meld provisioning and the nested-source
        /// re-walk run only on an unscoped `sync`.
        // spec: CLI-231 CLI-50
        source: Option<String>,

        /// After refreshing, run an `upgrade` pass (report + prompt) to apply
        /// upgrades, scoped to the source(s) the filter matched (every
        /// installed item when no filter is given). When the scope spans more
        /// than one source, a disclosure names every matched source before
        /// the install-hook re-run pass -- even when nothing is pending --
        /// since a filter's blast radius can exceed what the name alone
        /// suggests; unlike the `[Y/n]` confirmation itself, this disclosure
        /// is NOT suppressed by `--yes`. Deprecated: prefer `mind upgrade`,
        /// which now syncs first by default.
        // spec: CLI-169 CLI-232 CLI-233
        #[arg(long)]
        upgrade: bool,

        /// Run install-hook re-runs without the safety prompt during the
        /// `--upgrade` pass (executes arbitrary code; only with `--upgrade`).
        #[arg(long, requires = "upgrade")]
        dangerously_skip_install_hook_check: bool,

        /// Run item build hooks without the safety prompt during the `--upgrade`
        /// pass. This executes arbitrary code from the source; only use it for a
        /// source you trust. Without this flag, a non-TTY run skips build hooks
        /// and prints a note. Only valid with `--upgrade`.
        #[arg(long, requires = "upgrade")]
        dangerously_skip_build_hook_check: bool,
    },

    /// Upgrade installed items to their latest source version.
    ///
    /// By default, syncs each involved source first (fetches from remote), then
    /// reports pending upgrades and prompts before applying. Use `--no-sync` to
    /// skip the fetch and compute deltas from the current clone.
    // spec: CLI-169
    Upgrade {
        /// Only upgrade this item; default is every installed item. This is a
        /// filter over installed items: a glob may match several, and a bare
        /// non-glob name multi-matches only across kinds (the manifest is
        /// keyed `kind:name`, e.g. `upgrade greet` hitting both `skill:greet`
        /// and `agent:greet`) -- item names themselves are never
        /// suffix-matched. An embedded `owner/repo#` source qualifier is a
        /// filter too, not a ref like `unmeld`'s source name: it is a
        /// trailing-suffix match with no ambiguity check, so it can match
        /// several sources at once, upgrading every matched source's items
        /// and re-running each one's install hook. When the resolved scope
        /// spans more than one source, a disclosure names every matched
        /// source before the install-hook re-run pass -- even when nothing is
        /// pending -- and this disclosure is NOT suppressed by `--yes`.
        item: Option<String>,

        /// Skip the automatic source sync before computing deltas. By default,
        /// `upgrade` fetches each involved source before checking for changes.
        // spec: CLI-169
        #[arg(long)]
        no_sync: bool,

        /// Re-run a source's install hook without the safety prompt when its
        /// commit advanced. This executes arbitrary code from the source; only
        /// use it for a source you trust. Without this flag, a non-TTY upgrade
        /// (CI, scripts) skips the hook re-run and just prints a note; pass this
        /// to run it unattended.
        #[arg(long)]
        dangerously_skip_install_hook_check: bool,

        /// Run item build hooks without the safety prompt. This executes
        /// arbitrary code from the source; only use it for a source you trust.
        /// Without this flag, a non-TTY upgrade skips build hooks and prints a
        /// note, so the item's tooling is not rebuilt.
        #[arg(long)]
        dangerously_skip_build_hook_check: bool,
    },

    /// Upgrade the `mind` binary itself to the latest release (or a version
    /// pinned with `--to`). Distinct from `sync`'s `update` alias, which
    /// refreshes melded sources, not the binary.
    ///
    /// Downloads the release binary for this platform and replaces the running
    /// executable in place. `--check` reports whether a newer release is
    /// available and changes nothing. A prerelease running version (e.g. a
    /// `-dev` source build) is offered its own matching release even though
    /// the version numbers match. Without `--yes` it prompts before replacing.
    // Disable clap's auto `--version` flag on this subcommand so the explicit
    // `--to <VERSION>` argument below (pin a target release) owns the name
    // rather than shadowing the global `-V`/`--version` flag other verbs carry.
    // spec: CLI-172
    #[command(disable_version_flag = true, visible_alias = "self-update")]
    Evolve {
        /// Report whether a newer release is available, then exit without
        /// changing anything.
        #[arg(long)]
        check: bool,
        /// Upgrade to this exact version instead of the latest release. This
        /// is the only way to reach a prerelease (e.g. `--to 1.2.3-rc1`),
        /// since the latest-release lookup never surfaces one. A single
        /// leading `v` is accepted and stripped (`--to v1.2.3` works).
        /// `--version` is a deprecated alias kept for backwards compatibility.
        // spec: CLI-229 - renamed from --version, which shadowed the global
        // -V/--version flag other verbs carry; old spelling is a hidden alias.
        #[arg(long = "to", alias = "version", value_name = "VERSION")]
        version: Option<String>,
    },

    /// List installed items, or show one item's details.
    // spec: CLI-172 - added `list` visible alias; `status` kept.
    #[command(visible_aliases = ["status", "list"])]
    Recall {
        /// Show melded sources instead of installed items.
        #[arg(long)]
        sources: bool,

        /// Show details for a single installed item.
        item: Option<String>,

        /// Only list items of this kind (listing only).
        #[arg(long, value_enum)]
        kind: Option<KindArg>,

        /// Only list items from a source matching this filter: an exact
        /// name, a trailing suffix, or a glob (listing only; a multi-source
        /// match is normal, not an error).
        #[arg(long)]
        source: Option<String>,

        /// Render installed items as a dependency forest. With no item, shows
        /// the full forest; with an item ref, scopes to that item's subtree.
        // spec: DEP-61
        #[arg(long)]
        tree: bool,
    },

    /// Search melded catalogs for available items, or launch the interactive TUI.
    ///
    /// With a TTY and no opt-out, `probe` launches the interactive browser.
    /// Falls back to the catalog listing when `--no-tui`, `--json` (global), or
    /// stdout is not a TTY (piped or redirected). The query, `--kind`, and
    /// `--source` arguments seed the initial search/filter state in both modes.
    // spec: CLI-172
    #[command(visible_alias = "search")]
    Probe {
        /// Case-insensitive substring matched against item names and descriptions; empty lists everything.
        query: Option<String>,

        /// Only list items of this kind.
        #[arg(long, value_enum)]
        kind: Option<KindArg>,

        /// Only list items from a source matching this filter: an exact
        /// name, a trailing suffix, or a glob (a multi-source match is
        /// normal, not an error).
        #[arg(long)]
        source: Option<String>,

        /// Skip the interactive TUI and use the plain catalog listing.
        // spec: CLI-164, TUI-54 - long-only; former -n short removed (CLI-163 reserves -n for --dry-run).
        #[arg(long)]
        no_tui: bool,
    },

    /// Validate a source or a managed policy file (author-side, read-only).
    ///
    /// Source mode: `<target>` may be a local path, a melded-source selector
    /// (same forms as `unmeld`), or a repo spec (same forms as `meld`). A repo
    /// spec is shallow-cloned to a temp area and removed afterward. With no
    /// `<target>`, the current directory is validated.
    ///
    /// Policy mode: `--policy <path>` validates a managed policy TOML file at an
    /// explicit path without consulting the system policy path or env. Supplying
    /// both `<target>` and `--policy` is an error.
    Review {
        /// The source to validate: a local path, melded-source selector, or repo
        /// spec. Defaults to the current directory (`.`) when omitted.
        /// Cannot be used with `--policy`.
        #[arg(conflicts_with = "policy")]
        target: Option<String>,

        /// Evaluate the source under this prospective prefix (affects effective
        /// names, `{{ns:}}` expansion, and the unguarded-reference scan).
        /// Ignored when `--policy` is given. `--as` is a hidden deprecated
        /// alias for backwards compatibility.
        // spec: CLI-163 - short moved to -N (uppercase).
        #[arg(short = 'N', long = "namespace", alias = "as", value_name = "PREFIX")]
        alias: Option<String>,

        /// Validate a managed policy TOML file at this path instead of a source.
        /// Cannot be used with `<target>`; supply exactly one of the two.
        #[arg(long, value_name = "PATH", conflicts_with = "target")]
        policy: Option<std::path::PathBuf>,

        /// Rewrite the source in place: hardcoded install paths become tokens and
        /// bare sibling names become `{{ns:}}`. Local-path target only; the sole
        /// `review` mode that writes to disk. Ignored with `--policy`.
        #[arg(long, conflicts_with = "policy")]
        fix: bool,
    },

    /// Diagnose drift, broken symlinks, and unsynced sources.
    // spec: CLI-172
    #[command(visible_alias = "doctor")]
    Introspect {
        /// Repair what is fixable without changing versions (recreate missing links).
        #[arg(long)]
        fix: bool,
    },

    /// View and edit configuration (`~/.mind/config.toml`).
    Config {
        #[command(subcommand)]
        action: ConfigCmd,
    },

    /// Link installed skills into a project's harness skills directory.
    ///
    /// A shorthand for `config lobes add [dir] --preset <name>`. The project
    /// directory `dir` defaults to the current working directory; `--preset`
    /// defaults to `windsurf` (lobe at `<dir>/.windsurf`, skill-only). Existing
    /// installed skills are linked (or, with `--snapshot`, copied as real files)
    /// into the project dir immediately.
    ///
    /// For a managed (non-snapshot) add, gitignore guidance is printed: the skills
    /// directory contains symlinks into `~/.mind/store` and should be gitignored so
    /// the symlinks are not committed.
    // spec: CLI-198 HARN-11
    #[command(name = "link-project")]
    LinkProject {
        /// Project directory to link into (default: current working directory).
        dir: Option<String>,

        /// Harness preset to use (default: windsurf).
        #[arg(long, value_name = "NAME")]
        preset: Option<String>,

        /// Lobe subdirectory under the project dir instead of the preset default.
        /// Conflicts with `--preset`.
        #[arg(long, value_name = "REL", conflicts_with = "preset")]
        subdir: Option<String>,

        /// Write frozen real-file copies instead of registering a managed lobe.
        ///
        /// The copies are real files, not managed by mind: they are committable to
        /// the repo, but a later `mind learn` does not propagate into them (no
        /// auto-propagation). Managed (non-snapshot) lobes use symlinks instead.
        #[arg(long)]
        snapshot: bool,

        /// Overwrite a colliding target: a snapshot file, or a foreign file
        /// blocking backfill of already-installed items into a newly added lobe.
        #[arg(short = 'f', long)]
        force: bool,
    },

    /// Print a shell completion script to stdout.
    Completions {
        /// Shell to generate completions for.
        #[arg(value_enum)]
        shell: clap_complete::Shell,
    },

    /// Print the mind man page (roff) to stdout.
    Man,

    /// Run or list a source's or item's hooks on demand, outside the
    /// meld/learn/forget/upgrade flows.
    ///
    /// Lets you run hooks that were skipped earlier, re-run a hook whose effect
    /// was later lost (a deleted build output or side effect), or re-run an
    /// install or uninstall whose prior run failed for a transient reason.
    ///
    /// Subcommands:
    ///   `hooks run <target>`  -- run hooks with the same disclosure+consent model
    ///   `hooks list <target>` -- list declared hooks without running any
    // spec: CLI-194 CLI-195 CLI-196
    Hooks {
        #[command(subcommand)]
        action: HooksCmd,
    },

    /// Write a super-source `mind.toml` reproducing the current melded and
    /// installed state so melding the output recreates the same source set.
    ///
    /// By default, `dump` filters each source to the items actually installed
    /// and stamps the per-entry install directive accordingly. Pass
    /// `--whole-sources` to emit `install = true` for every source regardless
    /// of how many items are installed.
    Dump {
        /// Write to this file instead of stdout.
        #[arg(long, value_name = "PATH")]
        output: Option<std::path::PathBuf>,

        /// Emit `install = true` for every melded source, ignoring how many
        /// of its items are currently installed.
        #[arg(long = "whole-sources")]
        whole_sources: bool,
    },

    /// Claim an unmanaged lobe item into a version-controlled source and install
    /// it as a managed item (the constructive inverse of `forget --unmanaged`).
    ///
    /// Resolves <ref> to a single unmanaged item (an exact `kind:name`; a kind
    /// prefix disambiguates across kinds). Moves the item to the destination source
    /// at the convention path for its kind (`skills/<name>/`, `agents/<name>.md`,
    /// `rules/<name>.md`), commits it, melds the source if not yet registered, and
    /// installs it via `learn`. After absorb the item is an ordinary managed item.
    ///
    /// The destination source is resolved from, in precedence order:
    ///   1. `--to <path>` (this flag) takes precedence over all others
    ///   2. `MIND_ABSORB_TO` environment variable
    ///   3. `absorb-to` key in `~/.mind/config.toml` (the legacy `absorb_to`
    ///      spelling is still read)
    ///
    /// If none of these is set and the run is interactive, `absorb` prompts for
    /// a destination and offers `~/.mind/personal` as the built-in default,
    /// creating and `git init`-ing it on demand. Passing `--yes` with no configured
    /// destination automatically uses (and persists) `~/.mind/personal` without
    /// prompting. In a non-interactive (non-TTY) run with no destination configured,
    /// `absorb` refuses with an error.
    Absorb {
        /// The unmanaged item ref: `name`, `skill:name`, `agent:name`, or
        /// `rule:name`. A kind prefix disambiguates when the same name exists
        /// across kinds. Glob refs are rejected (absorb claims exactly one item).
        item_ref: String,

        /// Destination source directory. Takes precedence over `MIND_ABSORB_TO`
        /// and the `absorb-to` key in `config.toml`.
        #[arg(long, value_name = "PATH")]
        to: Option<String>,

        /// Overwrite the destination convention path if it already exists
        /// (a `kind:name` collision). Without `--force`, a collision is an error.
        #[arg(short = 'f', long)]
        force: bool,
    },
}

#[derive(Debug, Subcommand)]
pub enum ConfigCmd {
    /// Print the current config and where the file lives.
    Show,

    /// Manage agent homes ("lobes") - the directories items are linked into.
    // spec: CLI-172 - the former `target` alias is removed.
    Lobes {
        #[command(subcommand)]
        action: LobesCmd,
    },
}

#[derive(Debug, Subcommand)]
pub enum LobesCmd {
    /// Add an agent home, by path or by a `--preset <name>` harness preset.
    ///
    /// With `--preset`, the lobe path is `[base]/preset.rel_path`. For a global
    /// preset (gemini, codex, universal) the default base is `~`; for a project
    /// preset (windsurf) the default base is cwd. An explicit positional `base`
    /// overrides the default. With `--subdir <REL>` (no preset), the lobe path is
    /// `[base]/<REL>` with a skill-only kinds filter; base defaults to cwd.
    // spec: HARN-10 CLI-199
    Add {
        /// Base directory for the lobe. With `--preset`, the lobe lives at
        /// `base/preset.rel_path`; with `--subdir`, at `base/<REL>`; as a bare
        /// argument, the lobe IS the directory (all kinds, no filter). A leading
        /// `~` is expanded. Omitting this for a project preset defaults to cwd;
        /// omitting it with no preset and no `--subdir` is an error: `add` needs
        /// a path or `--preset <name>`.
        path: Option<String>,

        /// Add a known harness preset (gemini, codex, universal, windsurf).
        /// Resolves the lobe path and kinds filter from the preset definition.
        /// May be combined with a positional base directory.
        #[arg(long, value_name = "NAME")]
        preset: Option<String>,

        /// Lobe subdirectory under the base (or cwd when base is omitted).
        /// The lobe path is `base/<REL>` with a skill-only kinds filter.
        /// Conflicts with `--preset`.
        #[arg(long, value_name = "REL", conflicts_with = "preset")]
        subdir: Option<String>,

        /// Write frozen real-file copies of installed items instead of
        /// registering a managed lobe. No config entry is created. A colliding
        /// target blocks the copy unless `--force` is also given.
        #[arg(long)]
        snapshot: bool,

        /// Overwrite a colliding target: a snapshot file, or a foreign file
        /// blocking backfill of already-installed items into a newly added lobe.
        #[arg(short = 'f', long)]
        force: bool,
    },

    /// List configured agent homes.
    List,

    /// Detect installed agent homes (lobes) and offer to add their presets.
    /// Honors the global `-y`/`--yes` flag to add without prompting.
    Detect,

    /// Remove an agent home.
    Remove {
        /// The configured directory to drop.
        path: String,

        /// Before removing the config entry, convert symlinks confined under
        /// this lobe to frozen real-file copies of the store content (detach
        /// mode). The links are stripped from the manifest and the entry is
        /// dropped from config. Without this flag, symlinks are left in place
        /// and the lobe is simply unregistered.
        // spec: HARN-12 CLI-199
        #[arg(long)]
        snapshot: bool,
    },
}

/// Subcommands of `mind hooks`.
// spec: CLI-194 CLI-195 CLI-196
#[derive(Debug, Subcommand)]
pub enum HooksCmd {
    /// Run a source's or item's hooks on demand, outside meld/learn/forget/upgrade.
    ///
    /// `<target>` is a source FILTER (e.g. `repo`, `owner/repo`, or a glob
    /// like `'*'`) or an item ref `<source>#<item>` (e.g. `agents#skill:scan`).
    /// There is no ambiguity check: a filter matching several sources, or an
    /// item ref matching several items, runs the hook for each in turn.
    ///
    /// For a source or item target with `--event install` (the default), only
    /// *pending* hooks run by default -- those that never ran or did not run at
    /// the current commit. `--force` re-runs every install hook regardless, for
    /// both a source target and an item target. Uninstall hooks (source or item)
    /// carry no recorded run state and always run.
    ///
    /// Every hook goes through the same disclosure and consent prompt as an
    /// automatic run; it is never more silently than meld/learn would run it.
    // spec: CLI-194 CLI-195
    Run {
        /// The hook target: a source filter (e.g. `repo`, `owner/repo`, `'*'`)
        /// or an item ref `<source>#<item>` (e.g. `agents#skill:scan`).
        target: String,

        /// The lifecycle event to run (default: install).
        ///
        /// `install` and `uninstall` are valid for source and item targets.
        /// `build` is valid only for an item target and re-installs the item
        /// through the transactional path (stage, expand, build, swap), leaving
        /// the existing copy untouched if the build fails.
        #[arg(long, value_enum, default_value = "install")]
        event: HookEventArg,

        /// Re-run every install hook (source OR item target) even if it was
        /// already recorded at the current commit (for lost outputs or transient
        /// failures), mirroring `meld --force`. No effect on `--event uninstall`
        /// or `--event build`, neither of which filters by a recorded commit.
        /// `--rerun` is a visible alias that names this flag's actual meaning
        /// here more directly than the borrowed `--force`.
        // spec: CLI-228
        #[arg(long, visible_alias = "rerun")]
        force: bool,

        /// Run install hooks without the safety prompt. This executes arbitrary
        /// code from the source; only use it for a source you trust. Without this
        /// flag, a non-TTY run skips install hooks and prints a note.
        #[arg(long)]
        dangerously_skip_install_hook_check: bool,

        /// Run the item build hook without the safety prompt when `--event build`
        /// is given. This executes arbitrary code; only use it for a source
        /// you trust.
        #[arg(long)]
        dangerously_skip_build_hook_check: bool,
    },

    /// List the hooks for a source or item without running any.
    ///
    /// For a source target, shows all hooks declared in the source's `mind.toml`
    /// with their event, required/optional flag, and command; for source install
    /// hooks, also shows whether the hook is pending and the commit it last ran
    /// at. Also lists any hooks declared by the source's installed items.
    ///
    /// For an item ref `<source>#<item>`, shows only that item's hooks.
    // spec: CLI-196
    List {
        /// The hook target: a source filter or `<source>#<item>` item ref.
        target: String,
    },
}