"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.HELP_TOPICS = void 0;
// biome-ignore lint/nursery/noExcessiveLinesPerFile: CLI help topics stay centralized so `help --all` and man page generation share one registry.
const branding_1 = require("../core/branding");
const approval_instructions_1 = require("../workflows/approval-instructions");
const help_options_1 = require("./help-options");
const help_topics_event_hook_1 = require("./help-topics-event-hook");
exports.HELP_TOPICS = [
    {
        path: ["init"],
        root: true,
        usages: [
            "init [--cwd <path>] [--create-repo] [--repo-provider <provider>] [--repo <project-ref>]\n     [--remote-name <name>] [--base-branch <name>]\n     [--tracker-provider <provider>] [--tracker <project-ref>]\n     [--poll-interval <seconds>] [--max-workers <count>] [--max-issues <count>]\n     [--parallelism-mode <balance|greedy>]\n     [--max-ai-runs <count>] [--max-ai-hours <hours|off>] [--reviewer <name> ...]",
            "init [--language <en|ja|zh>] [--display-time-zone <IANA time zone>]",
        ],
        summary: "Create or update alpaca.config.json, register repo/tracker settings, tune service limits, language, and worker run caps, then resolve missing sign-in requirements.",
        docs: ["config"],
        options: [
            "--cwd <path>: Repository directory to initialize or register. Relative paths are resolved from the current directory.",
            "--create-repo: Create the missing Gitea repository before writing local setup. Requires --repo-provider gitea.",
            "--repo-provider <provider>: Repository host provider such as github, gitlab, or gitea.",
            "--repo <project-ref>: Repository project reference. If omitted, AlpacaLoop tries to infer it from git remotes.",
            "--remote-name <name>: Git remote to use for repository discovery and branch operations.",
            "--base-branch <name>: Default branch for top-level workflow state and pull-request merge targets.",
            "--tracker-provider <provider>: Ticket tracker provider.",
            "--tracker <project-ref>: Ticket tracker project reference.",
            "--poll-interval <seconds>: Background service polling interval.",
            "--max-workers <count>: Maximum repo-wide AI worker slots.",
            "--max-issues <count>: Maximum active worker issues.",
            "--parallelism-mode <balance|greedy>: Worker slot allocation mode.",
            "--max-ai-runs <count>: Default maximum AI runs before human input is required.",
            "--max-ai-hours <hours|off>: Default maximum AI work hours before human input is required.",
            "--reviewer <name>: Add a default PR reviewer. Can be repeated.",
            "--language <en|ja|zh>: Default output language for CLI text, managed comments, and worker-generated human-facing text.",
            "--display-time-zone <IANA time zone>: Display and schedule input time zone.",
        ],
        notes: [
            `Creates or updates ${branding_1.CONFIG_FILENAME} in the target repository.`,
            "May prompt interactively for missing repository, tracker, or sign-in settings.",
            "--create-repo is Gitea-only in this version; tracker provider and project must match the repository project.",
            "Existing remotes must already contain the configured base branch. New empty Gitea repos created by this command are seeded from local HEAD when possible.",
        ],
    },
    {
        path: ["doctor"],
        root: true,
        usages: ["doctor"],
        summary: "Audit local setup readiness by checking config, worker binaries, auth profiles, cooldowns, managed labels, repository registration, and service state.",
        notes: [
            "Remote base branch checks are failures because managed issues and service workspaces cannot run without that branch.",
        ],
        docs: ["config"],
    },
    {
        path: ["docs"],
        root: true,
        usages: [
            "docs",
            "docs list [--with-description]",
            "docs show <topic-id|docs-path> [--web]",
            "docs search <query...> [--context <lines>] [--view matches|headings]",
        ],
        summary: "List, read, open, or search packaged AlpacaLoop concept docs; use command help for option syntax and docs for conceptual behavior.",
        notes: [
            "Use docs for conceptual explanations such as alpaca.config.json behavior.",
            "Use <command> --help for command-specific options.",
        ],
        subcommandHint: "Use `alpaca docs list --help`, `alpaca docs show --help`, or `alpaca docs search --help` for docs command details.",
    },
    {
        path: ["docs", "list"],
        usages: ["docs list [--with-description]"],
        summary: "List AlpacaLoop docs paths.",
        options: [
            "--with-description: Include topic, title, description, and path.",
        ],
    },
    {
        path: ["docs", "show"],
        usages: ["docs show <topic-id|docs-path> [--web]"],
        summary: "Read one AlpacaLoop docs topic ID or docs path.",
        options: ["--web: Open the docs page in a browser."],
        notes: [
            "Topic IDs are references-relative paths without .md, such as config or command-flows.",
            "Docs paths can be references/config.md or skills/alpaca/references/config.md.",
        ],
    },
    {
        path: ["docs", "search"],
        usages: [
            "docs search <query...> [--context <lines>] [--view matches|headings]",
        ],
        summary: "Search AlpacaLoop docs topics.",
        options: [
            "--context <lines>: Include N context lines around matches. Ignored with --view headings. Default: 2.",
            "--view matches|headings: Choose match snippets or matching docs with heading outlines. Default: matches.",
        ],
    },
    {
        path: ["eject"],
        root: true,
        usages: ["eject <workflows|system-prompts|catalog|all> [--force]"],
        summary: "Copy packaged workflow, system-prompt, or catalog assets into .alpaca for repository-local editing, overwriting only with --force.",
        options: [
            "--force: Overwrite existing ejected files with the packaged versions.",
        ],
        notes: [
            "workflows writes packaged system workflows, including no_template default workflows, to .alpaca/workflows/__system/.",
            "system-prompts writes .alpaca/system-prompts/.",
            "catalog writes .alpaca/catalog/__system/{skill.json,mcp.json,metadata.json}.",
            "all ejects workflows first, then system prompts, then the catalog.",
        ],
    },
    {
        path: ["auth"],
        usages: ["auth <setup|list|order|clear>"],
        summary: "Manage machine-local worker authentication profiles.",
        notes: ["Use a subcommand help page for action-specific options."],
    },
    {
        path: ["auth", "setup"],
        root: true,
        usages: ["auth setup"],
        summary: "Start interactive Codex and Claude worker sign-in setup, covering browser, device-code, CLI, stored API key, and environment fallback flows.",
        notes: [
            "Interactive only. Codex sign-in supports browser, device-code, API key, and OPENAI_API_KEY fallback flows. Claude sign-in supports CLI, stored API key, and ANTHROPIC_API_KEY fallback flows.",
            "Custom workers do not use auth setup; configure their OpenAI-compatible endpoint and environment-variable secrets in alpaca.config.json.",
        ],
    },
    {
        path: ["auth", "list"],
        root: true,
        usages: ["auth list"],
        summary: "Show machine-local worker auth profiles, provider coverage, invalid or cooled-down entries, and rotation readiness without changing sign-ins.",
    },
    {
        path: ["auth", "order"],
        root: true,
        usages: ["auth order"],
        summary: "Show the built-in worker authentication preference order AlpacaLoop will try when selecting Codex or Claude profiles for issue runs.",
    },
    {
        path: ["auth", "clear"],
        root: true,
        usages: [
            "auth clear [--all | [--for codex|claude] [--invalid]] [-y|--yes]",
        ],
        summary: "Remove machine-local worker auth profiles by provider, invalid-only, or all profiles, with confirmation unless -y or --yes is supplied.",
        options: [
            "--all: Clear all auth profiles instead of the selected/default scope.",
            "--for codex|claude: Clear only sign-ins for one worker provider.",
            "--invalid: Clear only sign-ins already excluded from rotation by an auth error.",
            "-y, --yes: Skip the confirmation prompt.",
        ],
        notes: ["Without -y or --yes, auth clear asks for confirmation."],
    },
    {
        path: ["detach"],
        root: true,
        usages: ["detach [--cwd <path>] [--purge] [--force]"],
        summary: "Unregister a repository from service management; with --purge, delete managed files, repo-local .alpaca assets, and workspaces after confirmation.",
        options: [
            "--cwd <path>: Repository directory to detach. Relative paths are resolved from the current directory.",
            "--purge: Delete AlpacaLoop-managed repository files and workspaces after unregistering.",
            "--force: Purge managed files even when local contents differ from the packaged copy.",
        ],
        notes: [
            "Without --purge, detach unregisters the repo but leaves local files in place.",
            "With --purge, detach asks for confirmation in an interactive terminal before unregistering and deleting managed files, repo-local .alpaca files, and the project workspace root.",
            "With --purge --force, the confirmation also calls out that modified managed files can be deleted.",
            "--force should only be used when local managed-file edits are disposable.",
        ],
    },
    {
        path: ["cleanup"],
        root: true,
        usages: ["cleanup [--workspaces]"],
        summary: "Remove machine-local AlpacaLoop service state by default, or clean eligible closed-issue worker workspaces when --workspaces is supplied.",
        options: ["--workspaces: Clean eligible worker workspaces."],
        notes: [
            "In an interactive terminal, cleanup asks for confirmation before removing local state or closed issue workspaces.",
        ],
    },
    {
        path: ["run"],
        root: true,
        usages: ["run [--issue <id[,id...]>]"],
        summary: "Process runnable workflow issues once in the foreground, optionally restricted by issue id; use for manual runs, not while the service is active.",
        options: [
            "--issue <id[,id...]>: Restrict the run to one or more tracker issue ids.",
        ],
        notes: [
            "AI: Running means AlpacaLoop is running or has accepted a continuation; it does not guarantee an actively executing worker at every moment.",
            "Missing workflow templates, workflow template fit gaps, skills, or MCP servers may create blocking setup issues with localized Required Action checklists before launching a worker.",
        ],
    },
    {
        path: ["publish"],
        root: true,
        usages: [
            "publish [--path <path> ...] [-m|--message <text>] [--reviewer <name[,name...]> ...] [--no-merge] [--restart-service] [-y|--yes]",
        ],
        summary: "Publish selected local changes by committing, pushing, opening a pull request, and merging to the base branch unless reviewers or --no-merge are requested.",
        options: [
            "--path <path>: Commit only local changes under this repository-relative path. Repeat to include multiple paths. Existing unpublished commits on the branch are still pushed and included in the pull request.",
            "-m, --message <text>: Commit message and pull request title. Defaults to a short publish message.",
            "--reviewer <name[,name...]>: Request pull request review from one or more users. Repeat or use comma-separated names. When set, publish leaves the pull request unmerged.",
            "--no-merge: Leave the pull request unmerged after committing, pushing, and opening or reusing it.",
            "--restart-service: Usually unnecessary; safely restart the background service after publishing when the running service must reload an AlpacaLoop package update.",
            "-y, --yes: Skip the confirmation prompt.",
        ],
        notes: [
            "Publishes the current repository working tree explicitly; the background service never runs this command automatically.",
            "Publish assigns the pull request to the authenticated tracker user while preserving existing assignees.",
            "When creating a pull request, publish asks a configured worker to draft the pull request body from the changes and falls back to a fixed publish note when no worker can do so.",
            "Ignored files are not force-added.",
        ],
    },
    {
        path: ["issue"],
        usages: [
            "issue <approve|start|disable|enable|create|followup|list|search|show|broadcast|log|unlock>",
        ],
        summary: "Create, inspect, pause, re-enable, update, and unlock AlpacaLoop-managed issues.",
        notes: ["Use a subcommand help page for option details."],
    },
    {
        path: ["issue", "approve"],
        root: true,
        usages: [approval_instructions_1.ISSUE_APPROVE_CLI_USAGE],
        summary: "Post `/alpaca approve` to one AlpacaLoop-managed issue as its assignee; the next service scan records the approval.",
        options: ["--issue <id>: Issue id. Required."],
        notes: [
            "The command only posts `/alpaca approve`; the next service scan records the approval.",
            "The authenticated tracker user must match the issue's single assignee.",
        ],
    },
    {
        path: ["issue", "start"],
        root: true,
        usages: [approval_instructions_1.ISSUE_START_CLI_USAGE],
        summary: "Post `/alpaca start` to one issue waiting for start approval as its assignee; the next service scan records the approval.",
        options: ["--issue <id>: Issue id. Required."],
        notes: [
            "The command only posts `/alpaca start`; the next service scan records the start approval.",
            "The authenticated tracker user must match the issue's single assignee.",
            "The issue must be waiting for start approval.",
        ],
    },
    {
        path: ["issue", "disable"],
        root: true,
        usages: ["issue disable --issue <id[,id...]>"],
        summary: "Add the disabled workflow rule to one or more open issues without changing their workflow status.",
        options: ["--issue <id[,id...]>: One or more issue ids. Required."],
        notes: [
            "This pauses AI processing for the issue by adding the AI: Disabled rule while preserving statuses such as AI: Ready, AI: Running, or AI: Needs Human.",
        ],
    },
    {
        path: ["issue", "enable"],
        root: true,
        usages: ["issue enable --issue <id[,id...]>"],
        summary: "Remove the disabled workflow rule from one or more open issues without changing their workflow status.",
        options: ["--issue <id[,id...]>: One or more issue ids. Required."],
        notes: [
            "This only removes the AI: Disabled rule. It does not approve, start, unlock, or move a waiting issue to AI: Ready.",
        ],
    },
    {
        path: ["issue", "create"],
        root: true,
        usages: [
            "issue create (--prompt <text> | --title <text> (--body <text> | --body-file <path|->)) [--save-draft] [--assignee <name> ...] [--label <label> ...] [--milestone <ref>] [--project <ref>] [--disabled] [workflow options]",
            "issue create --apply-draft <path|->",
        ],
        summary: "Create an AlpacaLoop-managed issue from worker-drafted prompt input or manual title/body input, with optional workflow overrides and reviewed drafts.",
        optionSections: [
            {
                heading: "Issue creation options:",
                options: [
                    "--prompt <text>: Ask the worker to draft the issue from a natural-language request.",
                    "--title <text>: Manual issue title. Use with exactly one of --body or --body-file.",
                    "--body <text>: Manual issue body text.",
                    "--body-file <path|->: Read the manual issue body from a file or stdin.",
                    "--assignee <name>: Assign a tracker user. Can be repeated. If omitted, the current authenticated tracker user is assigned.",
                    "--label <label>: Add a tracker label. Can be repeated.",
                    "--milestone <ref>: Attach a tracker milestone.",
                    "--project <ref>: Attach a tracker project when supported by the provider.",
                    "--disabled: Create with the disabled workflow rule.",
                    ...help_options_1.SAVE_DRAFT_OPTIONS,
                    help_options_1.ISSUE_REVIEWED_DRAFT_OPTION,
                ],
            },
            {
                heading: "Initial workflow options:",
                description: "These use the same option keys as `/alpaca ...` issue comments, applied when the new issue is created. Issue create accepts option tokens only; tracker comment body text after `/alpaca ...` is separate same-issue replan context.",
                options: help_options_1.WORKFLOW_OVERRIDE_OPTIONS,
            },
        ],
        notes: [
            "Prompt mode discovers provider issue templates before drafting.",
            "Prompt mode drafts issue content, then runs workflow setup for explicit selector, schedule, worker, follow-up, and autofill options. Explicit template/no_template workflow selections skip workflow_select; no_template uses the built-in default workflow for the target. Auto and auto_select workflow selections are saved unresolved and handled during normal workflow setup after the issue exists.",
            "--save-draft stores explicit workflowOptions and setup/autofill workflowOptions; --apply-draft uses the saved JSON without rerunning workers.",
            "Prompt and manual modes create the issue immediately unless --save-draft is set.",
            "--save-draft writes the review JSON under machine-local ~/.alpaca/drafts/ and does not create the issue. Draft labels exclude managed workflow labels.",
            "GitHub and Gitea support --project. GitLab project binding is not supported yet.",
        ],
        examples: [
            'alpaca issue create --prompt "Fix flaky login tests"',
            'alpaca issue create --prompt "Fix flaky login tests" --save-draft',
            'alpaca issue create --title "Investigate queue delay" --body "Find the cause and propose a fix."',
            'alpaca issue create --prompt "This repository is a TypeScript CLI for task automation. Create reusable workflows for bug fixes, PR reviews, unplanned maintenance, and follow-up work." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off',
            'alpaca issue create --prompt "Refresh workflow templates for this repository based on recent issue history and current docs." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off --every 30d --first-run-now',
            'alpaca issue create --prompt "Maintain workflow templates for weekly platform work." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off --cron "0 9 * * 1" --first-run-after 1h --stop-after-runs 5',
            'alpaca issue create --prompt "Create initial workflow templates for a small web app with frontend, backend, PR review, and follow-up maintenance flows." --workflow __system/workflow-maintenance.md --pr-workflow no_template --unplanned-workflow no_template --followup-proposal off --default-worker claude --max-ai-runs 10',
            "alpaca issue create --apply-draft ~/.alpaca/drafts/.../issue-create-....json",
        ],
    },
    {
        path: ["issue", "followup"],
        root: true,
        usages: [
            "issue followup --issue <id> [--prompt <text>] [--workflow <auto|auto_select|no_template|path>] [--dry-run]",
        ],
        summary: "Create or dry-run an independent post-completion follow-up issue from an existing issue, carrying an optional request prompt and workflow selector for later follow-up execution.",
        options: [
            "--issue <id>: Source issue id. Required.",
            "--prompt <text>: Store the follow-up request in the created issue body. Timing or cadence written here can be picked up by normal workflow setup/autofill.",
            "--workflow <auto|auto_select|no_template|path>: Store the follow-up workflow selector. auto may request a missing template when the follow-up issue runs; auto_select chooses an existing candidate, or falls back to no_template without workflow_select when no candidates exist; no_template uses the built-in default follow-up workflow.",
            "--dry-run: Preview without creating the follow-up issue.",
        ],
    },
    {
        path: ["issue", "list"],
        root: true,
        usages: [
            "issue list [--web] [--state open|closed|all] [--days <number>] [--limit <number>] [--label <label> ...] [--me] [--assignee <login> ...] [--view compact|detailed] [--format text|markdown]",
        ],
        summary: "List tracker issues for triage with state, age, label, assignee, compact/detailed, markdown/text, or browser filters.",
        options: [
            "--web: Open the matching tracker issue list in a browser instead of printing the CLI report.",
            "--state open|closed|all: Filter by tracker state.",
            "--days <number>: Limit the recency window.",
            "--limit <number>: Limit the printed report to the N most recently updated matching issues. Not valid with --web.",
            "--label <label>: Filter by label. Can be repeated.",
            "--me: Filter to issues assigned to the authenticated tracker user. Not valid with --web.",
            "--assignee <login>: Filter to issues assigned to a tracker user. Can be repeated. Not valid with --web.",
            "--view compact|detailed: Choose the amount of issue detail for text output. Markdown output uses report tables. Default: detailed.",
            "--format text|markdown: Choose output format. Default: markdown.",
        ],
        notes: [
            `Text detailed output displays active ${branding_1.ISSUE_COMMENT_COMMAND_PREFIX} overrides and workflow selections when present.`,
            "Markdown output summarizes human attention and current issue status in tables.",
            "Repeated assignee filters match issues assigned to any listed user.",
            "--limit applies after state, recency, label, and assignee filters, before loading issue details.",
            "--view and --format are not valid with --web.",
            "--me and --assignee are not valid with --web.",
            "Gitea issue list pages do not support --days with --web.",
        ],
    },
    {
        path: ["issue", "search"],
        root: true,
        usages: [
            "issue search (--title <text> | --query <text>) [--state open|closed|all] [--limit <number>] [--include-prs] [--format text|markdown]",
        ],
        summary: "Search tracker issues by title or portable provider-backed text query without loading comments, dependencies, or workflow details.",
        options: [
            "--title <text>: Search issue titles. GitHub uses title search; GitLab and Gitea use provider search then title-filter results.",
            "--query <text>: Search broader provider text. GitHub searches title, body, and comments; GitLab searches title and description for issues and merge requests; Gitea uses its repository issue search string.",
            "--state open|closed|all: Filter by tracker state. Default: open.",
            "--limit <number>: Limit the report to the N most recently updated matching items. Default: 10.",
            "--include-prs: Include pull requests or merge requests in addition to issues.",
            "--format text|markdown: Choose output format. Default: text.",
        ],
        notes: [
            "Use this as a fallback when compact issue list and bounded issue show output do not identify the relevant issue.",
            "--query is portable AlpacaLoop search text, not raw provider query syntax.",
            "Provider search scopes differ; comments are only guaranteed in GitHub query mode.",
        ],
        examples: [
            'alpaca issue search --title "memory" --state all --limit 10 --format text',
            'alpaca issue search --query "history cache" --include-prs --limit 5 --format markdown',
        ],
    },
    {
        path: ["issue", "show"],
        root: true,
        usages: [
            "issue show --issue <id> [--view default|followup|full] [--parents 0|number|all] [--children 0|number|all] [--limit number|all] [--comments none|post-completion|all] [--pr none|summary|changes|commits|all] [--format text|markdown]",
        ],
        summary: "Show one AlpacaLoop-managed issue with workflow status, parent/source chain, related children, PR details, and relevant comments.",
        options: [
            "--issue <id>: Issue id. Required.",
            "--view default|followup|full: Choose preset defaults. Default: default.",
            "--parents 0|number|all: Include parent/source chain depth.",
            "--children 0|number|all: Include child/downstream relation depth.",
            "--limit number|all: Cap unordered related issue/file/commit output. Default: 20.",
            "--comments none|post-completion|all: Choose comment timeline. followup view defaults to post-completion.",
            "--pr none|summary|changes|commits|all: Choose PR detail level.",
            "--format text|markdown: Choose output format. Default: markdown.",
        ],
        notes: [
            "Presets: default = parents 1, children 1, limit 20, comments all, pr summary.",
            "followup = parents all, children 1, limit 20, comments post-completion, pr changes.",
            "full = parents all, children all, limit 20, comments all, pr all. Add --limit all for exhaustive output.",
        ],
    },
    {
        path: ["issue", "broadcast"],
        root: true,
        usages: [
            "issue broadcast (--message <text> | --message-file <path|->) (--issue <id[,id...]> | --open [--status <bucket> ...] [--label <label> ...]) [--dry-run]",
        ],
        summary: "Post or dry-run one shared tracker comment to explicit issue ids or filtered open AlpacaLoop queue issues.",
        options: [
            "--message <text>: Comment text.",
            "--message-file <path|->: Read comment text from a file or stdin.",
            "--issue <id[,id...]>: Target explicit issue ids.",
            "--open: Target open AlpacaLoop queue issues.",
            "--status <bucket>: With --open, restrict target statuses. Can be repeated.",
            "--label <label>: With --open, restrict target labels. Can be repeated.",
            "--dry-run: Preview selected targets without posting.",
        ],
        notes: [
            "Specify exactly one message source: --message or --message-file.",
            "Specify exactly one selector: --issue or --open.",
            "--open defaults to ai-ready, ai-running, and ai-needs-human.",
            "--status and --label are only valid with --open.",
        ],
    },
    {
        path: ["issue", "log"],
        usages: ["issue log <list|show|search>"],
        summary: "Inspect local issue run logs.",
        notes: ["Use a subcommand help page for option details."],
    },
    {
        path: ["issue", "log", "list"],
        root: true,
        usages: ["issue log list"],
        summary: "List machine-local issue run log files captured from worker executions for later inspection or debugging.",
    },
    {
        path: ["issue", "log", "show"],
        root: true,
        usages: ["issue log show --issue <id> [--tail <lines>]"],
        summary: "Show machine-local worker logs for one issue, with optional tailing to inspect recent execution output.",
        options: [
            "--issue <id>: Issue id. Required.",
            "--tail <lines>: Show only the last N lines.",
        ],
    },
    {
        path: ["issue", "log", "search"],
        root: true,
        usages: ["issue log search --query <text> [--context <lines>]"],
        summary: "Search machine-local issue run logs for text and optionally include surrounding context lines.",
        options: [
            "--query <text>: Search text. Required.",
            "--context <lines>: Include N context lines around matches. Default: 0.",
        ],
    },
    {
        path: ["issue", "unlock"],
        root: true,
        usages: ["issue unlock --issue <id[,id...]>"],
        summary: "Request release of AI: Running ownership for one or more issues so they can return to AI: Ready after the worker stops or ownership expires.",
        options: ["--issue <id[,id...]>: One or more issue ids. Required."],
        notes: [
            "The next worker starts after the current worker stops or ownership expires.",
        ],
    },
    {
        path: ["state"],
        usages: ["state <patch|restore>"],
        summary: "Maintain canonical workflow state comments.",
    },
    {
        path: ["state", "patch"],
        root: true,
        usages: [
            "state patch [--issue <id[,id...]>] [--state open|closed|all] [--dry-run]",
        ],
        summary: "Preview or apply canonical workflow state comment schema migrations across selected issues, writing backups before non-dry-run updates.",
        options: [
            "--issue <id[,id...]>: Check or patch one or more tracker issue ids.",
            "--state open|closed|all: Filter target issues by tracker state. Default: open.",
            "--dry-run: Preview whether canonical workflow state comments can migrate without updating tracker comments.",
        ],
        notes: [
            "Use --dry-run --state open before publishing workflow state schema or patch changes that could affect existing open issues.",
            "--issue is for targeted checks; --state is for list-wide checks.",
            "Non-dry-run patch asks for confirmation in an interactive terminal before updating tracker comments.",
            "Only the latest canonical workflow state comment on each issue is patched; successful non-dry-run updates write a JSONL backup before changing tracker comments.",
        ],
    },
    {
        path: ["state", "restore"],
        root: true,
        usages: [
            "state restore --backup-file <path> [--issue <id[,id...]>] [--dry-run] [--force]",
        ],
        summary: "Restore canonical workflow state comments from a JSONL backup, with dry-run and hash-safety controls for targeted recovery.",
        options: [
            "--backup-file <path>: JSONL backup file created by state patch or state restore. Required.",
            "--issue <id[,id...]>: Restrict restore to one or more tracker issue ids.",
            "--dry-run: Preview restore results without updating comments.",
            "--force: Restore even when the current comment body hash differs from the backup.",
        ],
        notes: [
            "Non-dry-run restore asks for confirmation in an interactive terminal before updating tracker comments.",
            "--force only ignores body hash mismatches; restore still skips when a newer canonical workflow state comment exists. Successful non-dry-run restores write a .restore.jsonl backup before changing tracker comments.",
        ],
    },
    {
        path: ["labels"],
        usages: ["labels <sync>"],
        summary: "Manage configured tracker labels.",
        docs: ["config"],
    },
    {
        path: ["labels", "sync"],
        root: true,
        usages: ["labels sync"],
        summary: "Create or reconcile the configured AlpacaLoop-managed labels in the tracker for the current repository.",
        docs: ["config"],
    },
    {
        path: ["catalog"],
        usages: ["catalog <topics>"],
        summary: "Inspect shared catalog metadata used by skill and MCP search.",
        notes: ["Use a subcommand help page for option details."],
    },
    {
        path: ["catalog", "topics"],
        usages: ["catalog topics <list>"],
        summary: "Inspect shared catalog topics.",
        notes: ["Use a subcommand help page for option details."],
    },
    {
        path: ["catalog", "topics", "list"],
        root: true,
        usages: ["catalog topics list"],
        summary: "Print shared skill and MCP catalog topic metadata as JSON, combining active system topics with repo-local user topics.",
        notes: [
            "Topics are the shared vocabulary stored in catalog metadata.json and used by skill and MCP catalog entries.",
            "The command always includes active system topics and repo-local user topics.",
        ],
    },
    {
        path: ["capability"],
        usages: ["capability <list|search>"],
        summary: "Inspect skills and MCP servers through one read-only discovery view.",
        notes: [
            "Use capability for cross-type discovery before deciding whether a workflow requires a skill or MCP server.",
            "Use skill or mcp commands for install, create, catalog, or verify operations.",
        ],
    },
    {
        path: ["capability", "list"],
        root: true,
        usages: ["capability list [--for <worker-id>|all] [--include-excluded]"],
        summary: "List installed skill and MCP capabilities as JSON, hiding refs excluded from workflow requires by default.",
        options: [
            "--for <worker-id>|all: Limit the result to one worker runtime or all configured workers.",
            "--include-excluded: Include candidates that are visible but excluded from workflow requires, with exclusion reason metadata.",
        ],
        notes: [
            "Capability list is read-only and does not install, create, or verify anything.",
            "Use skill list or mcp verify/list for final requires.skills / requires.mcp refs.",
        ],
    },
    {
        path: ["capability", "search"],
        root: true,
        usages: [
            "capability search <query> [--for <worker-id>|all] [--installed-only|--installable-only] [--include-excluded]",
        ],
        summary: "Search installed, catalog-backed, discovery-only, and provider candidates across skill and MCP sources as JSON.",
        options: [
            "--for <worker-id>|all: Search capabilities for one worker runtime or all configured workers.",
            "--installed-only: Return only capabilities already visible in installed inventory.",
            "--installable-only: Return only install candidates.",
            "--include-excluded: Include candidates that are visible but excluded from workflow requires, with exclusion reason metadata.",
        ],
        notes: [
            "Search results are discovery candidates; they are not automatically valid workflow requirements.",
            "Use skill install/create/list and mcp install/create/verify/list for the actual resolution path.",
        ],
    },
    {
        path: ["skill"],
        usages: ["skill <list|search|install|create|catalog>"],
        summary: "Inspect worker skills and repo-visible installable skill catalog entries.",
        notes: ["Use a subcommand help page for option details."],
    },
    {
        path: ["skill", "list"],
        root: true,
        usages: ["skill list [--for <worker-id>] [--include-excluded]"],
        summary: "List installed worker skills as JSON, including whether each ref is usable in workflow requires.skills for a configured worker.",
        options: [
            "--for <worker-id>: Limit the result to one worker runtime.",
            "--include-excluded: Include skills excluded from workflow requires, with exclusion reason metadata.",
        ],
        notes: [
            "Use the JSON ref field in workflow requires.skills only when usableForRequiredSkills is true.",
            "This command is read-only and does not install or create skills.",
        ],
    },
    {
        path: ["skill", "search"],
        root: true,
        usages: [
            "skill search <query> [--for <worker-id>|all] [--installed-only|--installable-only] [--with-worker] [--include-excluded]",
        ],
        summary: "Search installed skills, repo/system catalog entries, and provider marketplaces as JSON, optionally asking a worker to rank matches.",
        options: [
            "--for <worker-id>|all: Search skills for one worker runtime or all configured workers.",
            "--installed-only: Return only skills already visible in alpaca skill list.",
            "--installable-only: Return only catalog or marketplace install candidates.",
            "--with-worker: Ask a configured worker to inspect read-only catalog/search commands and prioritize semantic matches.",
            "--include-excluded: Include skills excluded from workflow requires, with exclusion reason metadata.",
        ],
        notes: [
            "Search results are install and discovery candidates; use alpaca skill list to inspect refs usable in workflow requires.skills.",
            "Installable results come from the effective skill catalog and Claude/Codex provider plugin marketplace search.",
            "Provider plugin results are install mechanisms for enabling skills, not plugin requirements to store in workflows.",
            "This command is read-only and does not install or create skills.",
            "--with-worker never calls search recursively with --with-worker; if the worker cannot run, normal search results are returned with worker fallback metadata.",
        ],
    },
    {
        path: ["skill", "install"],
        root: true,
        usages: [
            "skill install --source <source-uri> --for <worker-id> [--overwrite] [--plugin-scope project|user|local]",
            "skill install --search <query> --for <worker-id> [--overwrite] [--plugin-scope project|user|local] [--include-excluded]",
        ],
        summary: "Install a selected file, GitHub, Claude plugin, or Codex plugin skill candidate for one worker runtime, then print install results as JSON.",
        options: [
            "--source <source-uri>: Use a file://, github+https://, claude-plugin://, or codex-plugin:// source URI.",
            "--search <query>: Search first; if multiple installable candidates remain, an interactive terminal prompts you to choose one.",
            "--for <worker-id>: Install for one worker runtime.",
            "--overwrite: Replace an existing repo-local skill directory.",
            "--plugin-scope project|user|local: Claude plugin install scope. Defaults to project.",
            "--include-excluded: Allow --search to select candidates excluded from workflow requires. Installed results can still be unusable as requires.skills.",
        ],
        notes: [
            "File and GitHub sources write repo-local worker skill directories.",
            "Install does not automatically install npm packages, CLI tools, companion skills, OAuth credentials, browser login, or other runtime setup.",
            "Claude plugin sources require --for claude, are installed through claude plugin install, and are not repo-local skill directories.",
            "Codex plugin sources require --for codex, are installed through codex app-server plugin/install, and are not repo-local skill directories.",
            "AlpacaLoop has no alpaca plugin command, plugin catalog, plugin DB, or requires.plugin workflow field.",
            "When --search cannot select exactly one candidate outside an interactive terminal, the command prints alpaca.skillInstallSelectionRequired without installing.",
            "When --search selects a catalog-backed file or GitHub source, the catalog id becomes the repo-local install directory and requires.skills ref.",
            "Direct --source installs are allowed even when the source matches a requires exclusion; the JSON result includes excludedFromRequires and excludeReason when the installed skill must not be used in requires.skills.",
            "After install, inspect the skill docs for dependencies and auth requirements, complete safe non-interactive setup, then run alpaca skill list --for <worker> and a documented help, version, or smoke command when possible.",
        ],
    },
    {
        path: ["skill", "create"],
        root: true,
        usages: [
            "skill create --prompt <text> [--for <worker-id>|all] [--save-draft]",
            "skill create --apply-draft <path|->",
        ],
        summary: "Create a skill-resolution tracker issue, or save/apply reviewed draft JSON, without writing SKILL.md directly.",
        options: [
            "--prompt <text>: Ask a worker to draft a short title and capability summary for the skill-resolution issue.",
            "--for <worker-id>|all: Target one worker runtime or all configured workers. Defaults to all.",
            ...help_options_1.SAVE_DRAFT_OPTIONS,
            "--apply-draft <path|->: Create the issue from a reviewed draft.",
        ],
        notes: [
            "This command creates an issue for skill resolution; it does not write SKILL.md directly.",
            "By default it drafts with a worker first, then creates the issue immediately. Use --save-draft to save the final review JSON under machine-local ~/.alpaca/drafts/ instead.",
            "The issue is bound to __system/skill-resolution.md using the ejected workflow when present, otherwise the packaged system workflow.",
        ],
    },
    {
        path: ["skill", "catalog"],
        usages: ["skill catalog <list|add|import-github|remove>"],
        summary: "Manage repo-visible installable skill catalog entries.",
        notes: [
            "User entries live in .alpaca/catalog/skill.json; packaged system entries live in package-assets/system/catalog/skill.json.",
            "Ejected system entries live in .alpaca/catalog/__system/skill.json and replace packaged system entries for that repository.",
            "Packaged and ejected system catalogs are AlpacaLoop-curated install candidates. Provider marketplaces are searched separately by skill search.",
            "Catalog entries are install candidates; usable workflow requires.skills refs still come from alpaca skill list.",
            "Use a subcommand help page for option details.",
        ],
    },
    {
        path: ["skill", "catalog", "list"],
        root: true,
        usages: ["skill catalog list [--include-system]"],
        summary: "List repo-visible installable skill catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.",
        options: [
            "--include-system: Include packaged system catalog entries in the JSON items when the system catalog has not been ejected.",
        ],
        notes: [
            "Ejected system catalog entries are repo-visible and shown by default; packaged system entries stay hidden by default to keep this command focused on repo-local catalog entries.",
            "Claude/Codex provider marketplace search is resolved by skill search and is not synchronized into system or user catalog files.",
            "Sources are install candidates for alpaca skill install --source, not requires.skills refs.",
        ],
    },
    {
        path: ["skill", "catalog", "add"],
        root: true,
        usages: [
            "skill catalog add --id <id> --description <text> [--source <source-uri>] [--codex-source <source-uri>] [--claude-source <source-uri>]",
        ],
        summary: "Add or replace one repo-local user skill catalog entry with worker-specific or default install sources.",
        options: [
            "--id <id>: Stable catalog entry id.",
            "--description <text>: Short capability description.",
            "--source <source-uri>: Default install source for compatible workers.",
            "--codex-source <source-uri>: Codex-specific install source.",
            "--claude-source <source-uri>: Claude-specific install source.",
        ],
        notes: [
            "At least one source option is required.",
            "Adding an existing user entry replaces the user entry.",
            "System entry ids cannot be added as user entries; run alpaca eject catalog to edit them.",
        ],
    },
    {
        path: ["skill", "catalog", "import-github"],
        root: true,
        usages: [
            "skill catalog import-github --repo <owner/repo> --path <dir> [--ref <git-ref>] [--for <worker-id>|all] [--overwrite]",
        ],
        summary: "Import every SKILL.md under a GitHub repository directory as repo-local installable skill catalog entries for selected worker runtimes.",
        options: [
            "--repo <owner/repo>: GitHub repository containing skills.",
            "--path <dir>: Directory to scan for SKILL.md files.",
            "--ref <git-ref>: Git ref to read. Defaults to main.",
            "--for <worker-id>|all: Store imported sources for one worker or as default sources. Defaults to all.",
            "--overwrite: Replace existing user entries with imported entries.",
        ],
        notes: [
            "Imported ids come from SKILL.md frontmatter name when valid, otherwise the skill directory name.",
            "System entry ids cannot be imported as user entries; run alpaca eject catalog to edit them.",
        ],
    },
    {
        path: ["skill", "catalog", "remove"],
        root: true,
        usages: ["skill catalog remove --id <id>"],
        summary: "Remove one repo-local user skill catalog entry by id; packaged or ejected system entries are not removed.",
        options: ["--id <id>: User catalog entry id to remove."],
        notes: ["System entries are not removed by this command."],
    },
    {
        path: ["mcp"],
        usages: ["mcp <list|search|install|create|verify|catalog>"],
        summary: "Inspect, install, resolve, verify, and catalog worker MCP servers.",
        notes: ["Use a subcommand help page for option details."],
    },
    {
        path: ["mcp", "list"],
        root: true,
        usages: ["mcp list [--for <worker-id>|all] [--include-excluded]"],
        summary: "List MCP servers visible to worker runtimes as JSON, including diagnostics about usable server and tool refs.",
        options: [
            "--for <worker-id>|all: Limit the result to one worker runtime or all configured workers.",
            "--include-excluded: Include MCP refs excluded from workflow requires, with exclusion reason metadata.",
        ],
        notes: [
            "Codex entries are inspected through codex app-server MCP status and must expose tools before they can satisfy required MCP refs.",
            "Claude worker entries are inspected with claude mcp list when CLAUDE_CONFIG_DIR is available; .mcp.json project entries are shown as shared config but are not treated as worker-usable by themselves.",
            "Custom worker entries read .mcp.json and .pi/mcp.json through the Pi MCP adapter; cached tool metadata is shown when available.",
        ],
    },
    {
        path: ["mcp", "search"],
        root: true,
        usages: [
            "mcp search <query> [--for <worker-id>|all] [--installed-only|--installable-only] [--with-worker] [--include-excluded]",
        ],
        summary: "Search installed MCP servers and catalog entries as JSON, optionally asking a worker to rank matches.",
        options: [
            "--for <worker-id>|all: Search MCP servers for one worker runtime or all configured workers.",
            "--installed-only: Return only MCP servers already returned by alpaca mcp list.",
            "--installable-only: Return only safe catalog entries with an install server spec.",
            "--with-worker: Ask a configured worker to inspect read-only catalog/search commands and prioritize semantic matches.",
            "--include-excluded: Include MCP candidates excluded from workflow requires, with exclusion reason metadata.",
        ],
        notes: [
            "Installed inspection diagnostics are included in diagnostics; catalog candidates can still be returned when runtime inspection fails.",
            "Catalog entries without servers are discovery-only search leads and are hidden by --installable-only.",
            "--with-worker never calls search recursively with --with-worker; if the worker cannot run, normal search results are returned with worker fallback metadata.",
        ],
    },
    {
        path: ["mcp", "install"],
        root: true,
        usages: [
            "mcp install --id <catalog-id> --for <worker-id> [--name <server-name>] [--profile <auth-profile-id>] [--overwrite]",
            "mcp install --search <query> --for <worker-id> [--name <server-name>] [--profile <auth-profile-id>] [--overwrite] [--include-excluded]",
        ],
        summary: "Install one safe catalog-backed MCP server into a worker runtime.",
        options: [
            "--id <catalog-id>: Install a specific MCP catalog entry.",
            "--search <query>: Search installable catalog entries first; installs only when one candidate is selected.",
            "--for <worker-id>: Install for one worker runtime.",
            "--name <server-name>: Override the configured MCP server name.",
            "--profile <auth-profile-id>: Use one saved worker auth profile environment.",
            "--overwrite: Remove an existing MCP server with the same name before adding it.",
            "--include-excluded: Allow --search to select candidates excluded from workflow requires. Installed refs still need mcp verify before use in requires.mcp.",
        ],
        notes: [
            "Codex installs use codex mcp add with the selected worker CODEX_HOME. Claude installs use claude mcp add-json --scope user with the selected worker CLAUDE_CONFIG_DIR. Custom worker installs merge into project .mcp.json.",
            "Catalog entries must declare setup.safeAutoInstall: true and include a server spec for the selected worker target. Discovery-only catalog entries must be completed before install.",
            "Install does not complete OAuth, token, admin approval, or browser login steps. Follow nextSteps in the JSON result.",
            "Direct --id installs are allowed even when the catalog entry matches a requires exclusion; the JSON result includes excludedFromRequires and excludeReason when the installed ref must not be used in requires.mcp.",
            "The returned ref is a candidate value; declare requires.mcp only after alpaca mcp verify reports the server or tool as usable by the worker.",
        ],
    },
    {
        path: ["mcp", "create"],
        root: true,
        usages: [
            "mcp create --prompt <text> [--for <worker-id>|all] [--save-draft]",
            "mcp create --apply-draft <path|->",
        ],
        summary: "Create an MCP-resolution tracker issue, or save/apply reviewed draft JSON, without editing MCP catalog or worker config directly.",
        options: [
            "--prompt <text>: Ask a worker to draft a short title and capability summary for the MCP-resolution issue.",
            "--for <worker-id>|all: Target one worker runtime or all configured workers. Defaults to all.",
            ...help_options_1.SAVE_DRAFT_OPTIONS,
            "--apply-draft <path|->: Create the issue from a reviewed draft.",
        ],
        notes: [
            "This command creates an issue for MCP resolution; it does not write MCP catalog entries or worker MCP config directly.",
            "By default it drafts with a worker first, then creates the issue immediately. Use --save-draft to save the final review JSON under machine-local ~/.alpaca/drafts/ instead.",
            "The issue is bound to __system/mcp-resolution.md using the ejected workflow when present, otherwise the packaged system workflow.",
        ],
    },
    {
        path: ["mcp", "verify"],
        root: true,
        usages: ["mcp verify [--for <worker-id>|all] [--ref <mcp-ref> ...]"],
        summary: "Verify configured MCP server or tool refs against configured workers before declaring workflow requires.mcp.",
        options: [
            "--for <worker-id>|all: Verify against one worker runtime or all configured workers.",
            "--ref <mcp-ref>: Verify a specific ref such as github, github/list_issues, codex:github, claude:github/list_issues, or lmstudio-coder:github. Can be repeated.",
        ],
        notes: [
            "Codex verification requires codex app-server MCP status to expose at least one tool for the target server.",
            "Claude verification uses worker CLAUDE_CONFIG_DIR when available and treats connected servers as usable for server refs; tool refs still require tool names.",
            "Custom worker verification uses .mcp.json and .pi/mcp.json server config plus Pi MCP adapter cache when tool names are known.",
        ],
    },
    {
        path: ["mcp", "catalog"],
        usages: ["mcp catalog <list|add|remove>"],
        summary: "Manage repo-visible MCP catalog entries.",
        notes: [
            "Catalog entries may be install candidates or discovery-only setup leads; workflow requires.mcp refs still come from alpaca mcp verify/list.",
            "Installable catalog entries require a server spec plus setup.safeAutoInstall: true.",
            "Use a subcommand help page for option details.",
        ],
    },
    {
        path: ["mcp", "catalog", "list"],
        root: true,
        usages: ["mcp catalog list [--include-system]"],
        summary: "List repo-visible MCP install catalog entries as JSON, with optional packaged system entries when the system catalog is not ejected.",
        options: [
            "--include-system: Include packaged system catalog entries in the JSON items when the system catalog has not been ejected.",
        ],
        notes: [
            "Ejected system catalog entries are repo-visible and shown by default.",
            "Packaged system entries may include discovery-only MCP leads without servers; those are searchable but not installable until a reviewed server spec is added.",
        ],
    },
    {
        path: ["mcp", "catalog", "add"],
        root: true,
        usages: ["mcp catalog add --entry <path|-> [--overwrite]"],
        summary: "Add or replace one repo-local MCP catalog entry from a JSON object read from a file or stdin.",
        options: [
            "--entry <path|->: Read a single MCP catalog entry JSON object from a file or stdin.",
            "--overwrite: Replace an existing user entry with the same id.",
        ],
    },
    {
        path: ["mcp", "catalog", "remove"],
        root: true,
        usages: ["mcp catalog remove --id <id>"],
        summary: "Remove one repo-local MCP catalog entry by id; packaged or ejected system entries are not removed.",
        options: ["--id <id>: User catalog entry id to remove."],
        notes: ["System entries are not removed by this command."],
    },
    {
        path: ["workflow"],
        usages: ["workflow <create|update|delete|lint|list>"],
        summary: "Create, update, delete, validate, and list reusable workflow templates.",
        notes: ["Use a subcommand help page for option details."],
    },
    {
        path: ["workflow", "create"],
        root: true,
        usages: [
            "workflow create --prompt <text> [--path <path>] [--description <text>] [--target <target> ...] [--no-auto-select] [--required-skill <ref> ...] [--required-mcp <ref> ...] [--save-draft]",
            "workflow create --prompt <text> --template-set [--save-draft]",
            "workflow create --path <path> [--description <text>] [--target <target> ...] [--no-auto-select] [--required-skill <ref> ...] [--required-mcp <ref> ...] [--body <text> | --body-file <path|->] [--save-draft]",
            "workflow create --apply-draft <path|->",
        ],
        summary: "Draft reusable workflow template decisions from prompt/template-set input, or create one from manual body/scaffold, with optional required skills/MCP and reviewed drafts.",
        options: [
            "--prompt <text>: Ask the worker to inspect the catalog and choose create/update/reuse template action.",
            "--template-set: With --prompt, draft the smallest cohesive set of create/update/reuse template changes.",
            "--path <path>: Template path. Required in manual mode; optional override in prompt mode.",
            "--description <text>: Template description override.",
            "--target issue|pull_request|unplanned|followup: Declare where this template can be selected. `recurring` is schedule state, not a target. Can be repeated. Default: issue.",
            "--no-auto-select: Keep the template listed and valid, but exclude it from automatic selection.",
            "--required-skill <ref>: Declare a requires.skills ref from alpaca skill list. Can be repeated.",
            "--required-mcp <ref>: Declare a requires.mcp ref from alpaca mcp verify/list. Can be repeated.",
            "--body <text>: Manual template body.",
            "--body-file <path|->: Read manual template body from a file or stdin.",
            ...help_options_1.SAVE_DRAFT_OPTIONS,
            help_options_1.WORKFLOW_CREATE_REVIEWED_DRAFT_OPTION,
        ],
        notes: [
            "Prompt mode inspects the existing catalog and may reuse an existing template, update a close template, or create a new template only for a missing reusable workflow type.",
            "Prompt mode drafts path, description, targets, automatic selection eligibility, required skills/MCP refs, and body unless overridden.",
            "Prefer <domain>/<role>-<scope>.md paths; reuse an existing domain folder for the same purpose before creating a new folder, and avoid synonym folders for the same domain.",
            "Template-set mode cannot be combined with template overrides or manual body input, may move update_existing paths, and should not create one template per issue step, file, bullet, phase, or generic checklist item.",
            "Use @workflow only when the referenced template should become a nested workflow step; use a plain .alpaca/workflows/foo.md path for reference-only guidance.",
            "Recurring behavior uses issue workflow templates plus schedule state such as --every or --cron.",
            "Manual mode without --body or --body-file writes a generic scaffold.",
            "New templates explicitly write updateMode: flexible.",
            "Prompt and manual modes write templates immediately unless --save-draft is set.",
            "--save-draft writes the review JSON under machine-local ~/.alpaca/drafts/ and does not write templates.",
            "--apply-draft applies reviewed draft JSON without rerunning the worker.",
        ],
    },
    {
        path: ["workflow", "update"],
        root: true,
        usages: [
            "workflow update [--path <template.md>] --prompt <text> [--template-set] [--save-draft]",
            "workflow update --apply-draft <path|->",
        ],
        summary: "Update a fixed workflow template from a prompt, or use template-set mode for related create/update/reuse changes with reviewed draft application.",
        options: [
            "--path <template.md>: Existing template path. If omitted in an interactive terminal, AlpacaLoop prompts you to choose a template.",
            "--prompt <text>: Requested improvement. Required in prompt mode.",
            "--template-set: Allow the worker to split the target into the smallest cohesive create/update/reuse template changes.",
            ...help_options_1.SAVE_DRAFT_OPTIONS,
            help_options_1.WORKFLOW_UPDATE_REVIEWED_DRAFT_OPTION,
        ],
        notes: [
            "Updates the template file, not workflow target selections stored on tracker items.",
            "Plain prompt mode updates only the fixed target path; use --template-set when the request may split responsibilities or require related create/reuse decisions.",
            "Template-set mode uses the target path as an anchor and may create, update, reuse, or move related reusable templates without creating one template per issue step.",
            "Prefer <domain>/<role>-<scope>.md paths; reuse an existing domain folder for the same purpose before creating a new folder, and avoid synonym folders for the same domain.",
            "Use @workflow only when the referenced template should become a nested workflow step; use a plain .alpaca/workflows/foo.md path for reference-only guidance.",
            "New templates created by template-set updates explicitly write updateMode: flexible.",
            "Prompt mode writes templates immediately unless --save-draft is set.",
            "--save-draft writes the review JSON under machine-local ~/.alpaca/drafts/ and does not write templates.",
            "--apply-draft applies reviewed draft JSON without rerunning the worker and checks update base digests before writing.",
        ],
    },
    {
        path: ["workflow", "delete"],
        root: true,
        usages: [
            "workflow delete --path <template.md> [--dry-run]",
            "workflow delete --path <template.md> [--save-draft]",
            "workflow delete --path <template.md> --cleanup-references --save-draft",
            "workflow delete --apply-draft <path|->",
        ],
        summary: "Delete one repo-local workflow template, blocking when references remain unless a reviewed cleanup draft is saved and applied.",
        options: [
            "--path <template.md>: Repo-local workflow template to delete. System templates cannot be deleted.",
            "--dry-run: Show the delete action or remaining references without deleting files.",
            "--cleanup-references: Ask the worker to update editable referring templates before deleting the target. Must be combined with --save-draft.",
            ...help_options_1.SAVE_DRAFT_OPTIONS,
            help_options_1.WORKFLOW_DELETE_REVIEWED_DRAFT_OPTION,
        ],
        notes: [
            "Delete checks workflow template references from @workflow, Markdown links, plain .alpaca/workflows/foo.md paths, and workflow template config selectors.",
            "Use `workflow list --references-to <template.md>` to inspect references before deleting.",
            "--dry-run is a preview mode and cannot be combined with --save-draft.",
            "Without --cleanup-references, --save-draft saves a reviewed single-template delete draft.",
            "--cleanup-references removes references to the target template; it does not cascade-delete other templates.",
            "Config selectors, system templates, strict templates, and disabled templates are not edited by cleanup drafts.",
        ],
    },
    {
        path: ["workflow", "lint"],
        root: true,
        usages: ["workflow lint [--path <path>]"],
        summary: "Validate one or all workflow templates locally, including structure, nested references, section order, and required capability availability.",
        options: ["--path <path>: Validate one template instead of all templates."],
        notes: [
            "With --path, required skill/MCP availability is strict for the selected template tree.",
            "Without --path, required capability availability is reported as warnings so unselected templates do not fail full-catalog checks.",
        ],
    },
    {
        path: ["workflow", "list"],
        root: true,
        usages: [
            "workflow list [--include-system] [--target issue|pull_request|unplanned|followup] [--format text|json]",
            "workflow list --references-to <template.md> [--format text|json]",
        ],
        summary: "List workflow templates or references to one template, optionally including system templates and printing text or JSON output.",
        options: [
            "--include-system: Include system workflows under __system/ in template-list mode. Reference-list mode always includes system sources so it matches delete checks.",
            "--target issue|pull_request|unplanned|followup: Filter by workflow target.",
            "--references-to <template.md>: List workflow templates or config selectors that reference the target template. Cannot be combined with --target.",
            "--format text|json: Choose output format. Default: text.",
        ],
    },
    ...help_topics_event_hook_1.EVENT_HOOK_HELP_TOPICS,
    {
        path: ["service"],
        usages: ["service <enable|disable|restart|status|log>"],
        summary: "Manage the background polling service.",
        notes: ["Use a subcommand help page for option details."],
    },
    {
        path: ["service", "enable"],
        root: true,
        usages: ["service enable"],
        summary: `Install and start the ${branding_1.SERVICE_DISPLAY_NAME} background polling service so it watches registered repositories for runnable work.`,
        notes: [
            "Stop it with service disable before using alpaca run.",
            "Linux and WSL2 require a working systemd user session (`systemctl --user`). WSL2 support assumes systemd is enabled.",
            "If the user service is unavailable on Linux/WSL2, use alpaca run as the foreground fallback.",
        ],
    },
    {
        path: ["service", "disable"],
        root: true,
        usages: ["service disable [--force]"],
        summary: "Stop and remove the background polling service after current service work finishes, or immediately with --force.",
        options: [
            "--force: Stop immediately without waiting for current service work to finish.",
        ],
    },
    {
        path: ["service", "restart"],
        root: true,
        usages: ["service restart [--force]"],
        summary: "Restart the background polling service after current service work finishes so it reloads configuration or package updates.",
        options: [
            "--force: Restart immediately without waiting for current service work to finish.",
        ],
    },
    {
        path: ["service", "status"],
        root: true,
        usages: ["service status"],
        summary: "Show background service state, registered repositories, active work, and whether the service is installed or running.",
    },
    {
        path: ["service", "log"],
        usages: ["service log <show>"],
        summary: "Inspect background service logs.",
    },
    {
        path: ["service", "log", "show"],
        root: true,
        usages: ["service log show [--tail <lines>]"],
        summary: "Show machine-local background service logs, with optional tailing for recent polling and worker-launch diagnostics.",
        options: ["--tail <lines>: Show only the last N lines."],
    },
];
