@slope-dev/slope 1.58.4 → 1.59.0

package/dist/cli/registry.js

@@ -4,32 +4,46 @@ export const CLI_INTERNAL_MODULES = ['phase', 'review-state', 'review-run', 'spr
 export const CLI_COMMAND_REGISTRY = [
     // ── Lifecycle ──────────────────────────────────────────────────
     {
-        cmd: 'init', desc: 'Initialize .slope/ directory', category: 'lifecycle',
+        cmd: 'init', desc: 'Initialize .slope/ directory', category: 'lifecycle', audience: 'human',
         flags: [
             { flag: '--metaphor=<id>', desc: 'Set metaphor theme (golf, gaming, dnd, etc.)' },
             { flag: '--interactive', desc: 'Rich interactive setup wizard' },
         ],
     },
     {
-        cmd: 'interview', desc: 'Run project interview (human or agent JSON mode)', category: 'lifecycle',
+        cmd: 'interview', desc: 'Run project interview (human or agent JSON mode)', category: 'lifecycle', audience: 'advanced',
         flags: [
             { flag: '--agent', desc: 'JSON I/O mode for agent harnesses' },
             { flag: '--force', desc: 'Re-interview even if project already initialized' },
         ],
     },
     {
-        cmd: 'help', desc: 'Show detailed per-command usage', category: 'lifecycle',
+        cmd: 'help', desc: 'Show detailed per-command usage', category: 'lifecycle', audience: 'human',
         flags: [{ flag: '<command>', desc: 'Command name to show details for' }],
     },
     {
-        cmd: 'quickstart', desc: 'Interactive tutorial for new users', category: 'lifecycle',
+        cmd: 'now', desc: 'Compact current-state cockpit', category: 'lifecycle', audience: 'human',
+        flags: [
+            { flag: '--sprint=<N>', desc: 'Override inferred current sprint' },
+            { flag: '--json', desc: 'Output as JSON' },
+        ],
     },
     {
-        cmd: 'doctor', desc: 'Check repo health and auto-fix issues', category: 'lifecycle',
+        cmd: 'start', desc: 'Human start-of-work cockpit', category: 'lifecycle', audience: 'human',
+        flags: [
+            { flag: '--sprint=<N>', desc: 'Override inferred current sprint' },
+            { flag: '--ticket=<key>', desc: 'Claim and begin a ticket' },
+        ],
+    },
+    {
+        cmd: 'quickstart', desc: 'Interactive tutorial for new users', category: 'lifecycle', audience: 'human',
+    },
+    {
+        cmd: 'doctor', desc: 'Check repo health and auto-fix issues', category: 'lifecycle', audience: 'human',
         flags: [{ flag: '--fix', desc: 'Auto-fix detected issues' }],
     },
     {
-        cmd: 'version', desc: 'Show version or bump with automated PR workflow', category: 'lifecycle',
+        cmd: 'version', desc: 'Show version or bump with automated PR workflow', category: 'lifecycle', audience: 'advanced',
         subcommands: [
             { name: 'bump', desc: 'Bump version with automated PR workflow', flags: [
                     { flag: '<version>', desc: 'Explicit version (e.g. 1.28.0)' },
@@ -41,7 +55,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'session', desc: 'Manage live sessions', category: 'lifecycle',
+        cmd: 'session', desc: 'Manage live sessions', category: 'lifecycle', audience: 'agent',
         subcommands: [
             { name: 'start', desc: 'Start a new session', flags: [
                     { flag: '--role=<role>', desc: 'Session role (primary, secondary, observer)' },
@@ -62,7 +76,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'claim', desc: 'Claim a ticket or area for the sprint', category: 'lifecycle',
+        cmd: 'claim', desc: 'Claim a ticket or area for the sprint', category: 'lifecycle', audience: 'agent',
         flags: [
             { flag: '--target=<path>', desc: 'File or directory to claim' },
             { flag: '--ticket=<key>', desc: 'Ticket key (e.g. S48-1)' },
@@ -70,19 +84,19 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'release', desc: 'Release a claim by ID or target', category: 'lifecycle',
+        cmd: 'release', desc: 'Release a claim by ID or target', category: 'lifecycle', audience: 'agent',
         flags: [
             { flag: '--id=<id>', desc: 'Claim ID to release' },
             { flag: '--target=<path>', desc: 'Release claim by target path' },
         ],
     },
     {
-        cmd: 'status', desc: 'Show sprint course status and conflicts', category: 'lifecycle',
+        cmd: 'status', desc: 'Show sprint course status and conflicts', category: 'lifecycle', audience: 'human',
         flags: [{ flag: '--json', desc: 'Output as JSON' }],
     },
-    { cmd: 'next', desc: 'Show next sprint number (auto-detect)', category: 'lifecycle' },
+    { cmd: 'next', desc: 'Show next sprint number (auto-detect)', category: 'lifecycle', audience: 'advanced' },
     {
-        cmd: 'resume', desc: 'Portable sprint resume from tracked artifacts', category: 'lifecycle',
+        cmd: 'resume', desc: 'Portable sprint resume from tracked artifacts', category: 'lifecycle', audience: 'agent',
         flags: [
             { flag: '--from=<path>', desc: 'Resume pointer path (default: docs/backlog/.sprint-active.json)' },
             { flag: '--sprint=<N>', desc: 'Explicit sprint number when no pointer exists' },
@@ -92,7 +106,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'sprint', desc: 'Manage sprint lifecycle state and gates', category: 'lifecycle',
+        cmd: 'sprint', desc: 'Manage sprint lifecycle state and gates', category: 'lifecycle', audience: 'agent',
         subcommands: [
             { name: 'start', desc: 'Start a new sprint', flags: [
                     { flag: '--number=<N>', desc: 'Sprint number (required)' },
@@ -100,6 +114,10 @@ export const CLI_COMMAND_REGISTRY = [
                     { flag: '--touches=<paths>', desc: 'Comma-separated paths to check against sibling worktrees' },
                     { flag: '--force', desc: 'Override pre-sprint reality-check blockers' },
                 ] },
+            { name: 'begin', desc: 'Bundled start + claim + briefing + prep flow', flags: [
+                    { flag: '--sprint=<N>', desc: 'Sprint number (required)' },
+                    { flag: '--ticket=<key>', desc: 'Ticket key to claim and prep' },
+                ] },
             { name: 'gate', desc: 'Mark a gate as complete', flags: [
                     { flag: '<name>', desc: 'Gate name to complete' },
                 ] },
@@ -118,7 +136,7 @@ export const CLI_COMMAND_REGISTRY = [
     },
     // ── Scoring ────────────────────────────────────────────────────
     {
-        cmd: 'card', desc: 'Display handicap card', category: 'scoring',
+        cmd: 'card', desc: 'Display handicap card', category: 'scoring', audience: 'human',
         flags: [
             { flag: '--metaphor=<id>', desc: 'Display theme override' },
             { flag: '--player=<name>', desc: 'Filter to a specific player' },
@@ -127,14 +145,14 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'validate', desc: 'Validate scorecard(s)', category: 'scoring',
+        cmd: 'validate', desc: 'Validate scorecard(s)', category: 'scoring', audience: 'agent',
         flags: [
             { flag: '<path>', desc: 'Scorecard JSON file to validate' },
             { flag: '--skills', desc: 'Check scorecard skill references against .slope/skills.json' },
         ],
     },
     {
-        cmd: 'review', desc: 'Format sprint review or manage review state', category: 'scoring',
+        cmd: 'review', desc: 'Format sprint review or manage review state', category: 'scoring', audience: 'human',
         subcommands: [
             { name: 'start', desc: 'Start a plan review', flags: [
                     { flag: '--tier=<tier>', desc: 'Review tier (skip, light, standard, deep)' },
@@ -162,7 +180,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'auto-card', desc: 'Generate scorecard from git + CI signals', category: 'scoring',
+        cmd: 'auto-card', desc: 'Generate scorecard from git + CI signals', category: 'scoring', audience: 'agent',
         flags: [
             { flag: '--sprint=<N>', desc: 'Sprint number (required)' },
             { flag: '--since=<date>', desc: 'Start date for git log' },
@@ -176,7 +194,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'classify', desc: 'Classify a shot from execution trace', category: 'scoring',
+        cmd: 'classify', desc: 'Classify a shot from execution trace', category: 'scoring', audience: 'agent',
         flags: [
             { flag: '--scope=<files>', desc: 'Comma-separated file scope' },
             { flag: '--modified=<files>', desc: 'Comma-separated modified files' },
@@ -186,7 +204,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'tournament', desc: 'Build tournament review from sprints', category: 'scoring',
+        cmd: 'tournament', desc: 'Build tournament review from sprints', category: 'scoring', audience: 'advanced',
         flags: [
             { flag: '--id=<id>', desc: 'Tournament identifier' },
             { flag: '--name=<name>', desc: 'Tournament display name' },
@@ -196,7 +214,7 @@ export const CLI_COMMAND_REGISTRY = [
     },
     // ── Analysis ───────────────────────────────────────────────────
     {
-        cmd: 'briefing', desc: 'Pre-round briefing with hazards and nutrition', category: 'analysis',
+        cmd: 'briefing', desc: 'Pre-round briefing with hazards and nutrition', category: 'analysis', audience: 'human',
         flags: [
             { flag: '--categories=<list>', desc: 'Filter by issue categories (comma-separated)' },
             { flag: '--keywords=<list>', desc: 'Filter by keywords (comma-separated)' },
@@ -209,7 +227,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'plan', desc: 'Pre-shot advisor (club + training + hazards)', category: 'analysis',
+        cmd: 'plan', desc: 'Pre-shot advisor (club + training + hazards)', category: 'analysis', audience: 'agent',
         flags: [
             { flag: '--complexity=<level>', desc: 'Complexity (trivial, small, medium, large)' },
             { flag: '--slope-factors=<list>', desc: 'Comma-separated slope factors' },
@@ -218,14 +236,14 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'report', desc: 'Generate HTML performance report', category: 'analysis',
+        cmd: 'report', desc: 'Generate HTML performance report', category: 'analysis', audience: 'advanced',
         flags: [
             { flag: '--html', desc: 'Generate HTML report' },
             { flag: '--output=<path>', desc: 'Output file path' },
         ],
     },
     {
-        cmd: 'dashboard', desc: 'Live local performance dashboard', category: 'analysis',
+        cmd: 'dashboard', desc: 'Live local performance dashboard', category: 'analysis', audience: 'advanced',
         flags: [
             { flag: '--port=<N>', desc: 'HTTP port (default: 3000)' },
             { flag: '--no-open', desc: 'Don\'t auto-open browser' },
@@ -235,7 +253,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'standup', desc: 'Generate or ingest standup report', category: 'analysis',
+        cmd: 'standup', desc: 'Generate or ingest standup report', category: 'analysis', audience: 'agent',
         flags: [
             { flag: '--session=<id>', desc: 'Session ID for standup generation' },
             { flag: '--role=<id>', desc: 'Agent role filter' },
@@ -246,7 +264,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'analyze', desc: 'Scan repo and generate profile', category: 'analysis',
+        cmd: 'analyze', desc: 'Scan repo and generate profile', category: 'analysis', audience: 'advanced',
         flags: [
             { flag: '--analyzers=<list>', desc: 'Run specific analyzers (comma-separated: stack, git, etc.)' },
             { flag: '--json', desc: 'Output full profile as JSON' },
@@ -254,7 +272,7 @@ export const CLI_COMMAND_REGISTRY = [
     },
     // ── Tooling ────────────────────────────────────────────────────
     {
-        cmd: 'hook', desc: 'Manage lifecycle hooks', category: 'tooling',
+        cmd: 'hook', desc: 'Manage lifecycle hooks', category: 'tooling', audience: 'internal',
         subcommands: [
             { name: 'add', desc: 'Install guard hooks', flags: [
                     { flag: '--level=<level>', desc: 'Hook level (full, scoring)' },
@@ -267,7 +285,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'guard', desc: 'Run guard handler or manage guard activation', category: 'tooling',
+        cmd: 'guard', desc: 'Run guard handler or manage guard activation', category: 'tooling', audience: 'internal',
         subcommands: [
             { name: '<name>', desc: 'Run a guard (reads hook JSON from stdin)' },
             { name: 'list', desc: 'Show all available guards' },
@@ -285,7 +303,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'extract', desc: 'Extract events into SLOPE store', category: 'tooling',
+        cmd: 'extract', desc: 'Extract events into SLOPE store', category: 'tooling', audience: 'internal',
         flags: [
             { flag: '--file=<path>', desc: 'Event file to extract' },
             { flag: '--session-id=<id>', desc: 'Session ID to tag events' },
@@ -293,7 +311,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'distill', desc: 'Promote event patterns to common issues', category: 'tooling',
+        cmd: 'distill', desc: 'Promote event patterns to common issues', category: 'tooling', audience: 'agent',
         flags: [
             { flag: '--auto', desc: 'Auto-promote patterns above threshold' },
             { flag: '--dry-run', desc: 'Preview without writing' },
@@ -302,14 +320,14 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'map', desc: 'Generate/update codebase map', category: 'tooling',
+        cmd: 'map', desc: 'Generate/update codebase map', category: 'tooling', audience: 'agent',
         flags: [
             { flag: '--check', desc: 'Check staleness (exit 1 if stale)' },
             { flag: '--output=<path>', desc: 'Custom output path (default: CODEBASE.md)' },
         ],
     },
     {
-        cmd: 'workflow', desc: 'Manage workflow definitions', category: 'tooling',
+        cmd: 'workflow', desc: 'Manage workflow definitions', category: 'tooling', audience: 'internal',
         subcommands: [
             { name: 'validate', desc: 'Parse and validate a workflow definition' },
             { name: 'list', desc: 'List all available workflows (project + built-in)' },
@@ -317,7 +335,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'flows', desc: 'Manage user flow definitions', category: 'tooling',
+        cmd: 'flows', desc: 'Manage user flow definitions', category: 'tooling', audience: 'advanced',
         subcommands: [
             { name: 'init', desc: 'Create .slope/flows.json with example template' },
             { name: 'list', desc: 'List all flows with staleness indicators' },
@@ -325,7 +343,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'inspirations', desc: 'Track external OSS inspiration sources', category: 'tooling',
+        cmd: 'inspirations', desc: 'Track external OSS inspiration sources', category: 'tooling', audience: 'advanced',
         subcommands: [
             { name: 'add', desc: 'Add an inspiration source', flags: [
                     { flag: '--url=<url>', desc: 'Source URL (required)' },
@@ -343,7 +361,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'skills', desc: 'Manage repo-local Agent Skills registry', category: 'tooling',
+        cmd: 'skills', desc: 'Manage repo-local Agent Skills registry', category: 'tooling', audience: 'advanced',
         subcommands: [
             { name: 'scan', desc: 'Scan configured skill roots into .slope/skills.json', flags: [
                     { flag: '--root=<path>', desc: 'Skill root to scan (repeatable or comma-separated)' },
@@ -359,7 +377,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'issue', desc: 'Detect and triage SLOPE-driven product issues', category: 'tooling',
+        cmd: 'issue', desc: 'Detect and triage SLOPE-driven product issues', category: 'tooling', audience: 'agent',
         subcommands: [
             { name: 'scout', desc: 'Scan common issues/transcripts and propose GitHub issues', flags: [
                     { flag: '--source=<path>', desc: 'File or directory to scan (repeatable)' },
@@ -380,7 +398,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'metaphor', desc: 'Manage metaphor display themes', category: 'tooling',
+        cmd: 'metaphor', desc: 'Manage metaphor display themes', category: 'tooling', audience: 'advanced',
         subcommands: [
             { name: 'list', desc: 'Show all available metaphors' },
             { name: 'set', desc: 'Set the active metaphor', flags: [
@@ -392,7 +410,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'plugin', desc: 'Manage custom plugins', category: 'tooling',
+        cmd: 'plugin', desc: 'Manage custom plugins', category: 'tooling', audience: 'advanced',
         subcommands: [
             { name: 'list', desc: 'Show all plugins (built-in + custom)' },
             { name: 'validate', desc: 'Validate a plugin file', flags: [
@@ -401,7 +419,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'store', desc: 'Store diagnostics and management', category: 'tooling',
+        cmd: 'store', desc: 'Store diagnostics and management', category: 'tooling', audience: 'internal',
         subcommands: [
             { name: 'status', desc: 'Show store type, schema version, and stats', flags: [
                     { flag: '--json', desc: 'Output as JSON' },
@@ -412,7 +430,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'escalate', desc: 'Escalate issues based on severity triggers', category: 'tooling',
+        cmd: 'escalate', desc: 'Escalate issues based on severity triggers', category: 'tooling', audience: 'agent',
         flags: [
             { flag: '--reason=<text>', desc: 'Manual escalation reason' },
             { flag: '--session-id=<id>', desc: 'Session ID context' },
@@ -421,7 +439,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'transcript', desc: 'View session transcript data', category: 'tooling',
+        cmd: 'transcript', desc: 'View session transcript data', category: 'tooling', audience: 'internal',
         subcommands: [
             { name: 'list', desc: 'List available transcripts' },
             { name: 'show', desc: 'Show turn-by-turn summary', flags: [
@@ -434,7 +452,7 @@ export const CLI_COMMAND_REGISTRY = [
     },
     // ── Planning ───────────────────────────────────────────────────
     {
-        cmd: 'roadmap', desc: 'Strategic planning and roadmap tools', category: 'planning',
+        cmd: 'roadmap', desc: 'Strategic planning and roadmap tools', category: 'planning', audience: 'human',
         subcommands: [
             { name: 'validate', desc: 'Schema + dependency graph checks', flags: [
                     { flag: '--path=<file>', desc: 'Roadmap file path' },
@@ -459,7 +477,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'retro', desc: 'Retrospective scorecard utilities', category: 'planning',
+        cmd: 'retro', desc: 'Retrospective scorecard utilities', category: 'planning', audience: 'agent',
         subcommands: [
             { name: 'backfill', desc: 'Generate scorecard from git history (#318)', flags: [
                     { flag: '--sprint=<N>', desc: 'Sprint number (or use --all-missing)' },
@@ -480,7 +498,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'vision', desc: 'Display project vision document', category: 'planning',
+        cmd: 'vision', desc: 'Display project vision document', category: 'planning', audience: 'human',
         subcommands: [
             { name: 'create', desc: 'Create a new vision document', flags: [
                     { flag: '--purpose=<text>', desc: 'Project purpose' },
@@ -494,7 +512,7 @@ export const CLI_COMMAND_REGISTRY = [
         flags: [{ flag: '--json', desc: 'Output as JSON' }],
     },
     {
-        cmd: 'initiative', desc: 'Multi-sprint initiative orchestration', category: 'planning',
+        cmd: 'initiative', desc: 'Multi-sprint initiative orchestration', category: 'planning', audience: 'advanced',
         subcommands: [
             { name: 'create', desc: 'Create a new initiative' },
             { name: 'status', desc: 'Show current initiative state' },
@@ -511,7 +529,7 @@ export const CLI_COMMAND_REGISTRY = [
     },
     // ── Loop ─────────────────────────────────────────────
     {
-        cmd: 'loop', desc: 'Autonomous sprint execution loop', category: 'tooling',
+        cmd: 'loop', desc: 'Autonomous sprint execution loop', category: 'tooling', audience: 'advanced',
         subcommands: [
             { name: 'run', desc: 'Single sprint execution', flags: [
                     { flag: '--sprint=<ID>', desc: 'Sprint ID to execute' },
@@ -557,7 +575,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'worktree', desc: 'Manage git worktrees', category: 'tooling',
+        cmd: 'worktree', desc: 'Manage git worktrees', category: 'tooling', audience: 'agent',
         subcommands: [
             { name: 'status', desc: 'Show sibling worktree dirty/ahead/migration state', flags: [
                     { flag: '--base=<ref>', desc: 'Base ref for ahead/behind and changed-file detection' },
@@ -572,7 +590,7 @@ export const CLI_COMMAND_REGISTRY = [
     },
     // ── Indexing ──────────────────────────────────────────────────────
     {
-        cmd: 'index-cmd', desc: 'Semantic embedding index management', category: 'tooling',
+        cmd: 'index-cmd', desc: 'Semantic embedding index management', category: 'tooling', audience: 'internal',
         flags: [
             { flag: '--full', desc: 'Full reindex (drop + rebuild)' },
             { flag: '--status', desc: 'Show index stats' },
@@ -581,7 +599,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'context', desc: 'Semantic context search for agents', category: 'tooling',
+        cmd: 'context', desc: 'Semantic context search for agents', category: 'tooling', audience: 'agent',
         flags: [
             { flag: '<query>', desc: 'Free-text semantic search query' },
             { flag: '--ticket=<key>', desc: 'Use ticket title as query' },
@@ -591,7 +609,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'prep', desc: 'Generate execution plan for a ticket', category: 'tooling',
+        cmd: 'prep', desc: 'Generate execution plan for a ticket', category: 'tooling', audience: 'agent',
         flags: [
             { flag: '<ticket-id>', desc: 'Ticket ID to prepare' },
             { flag: '--json', desc: 'Output as JSON' },
@@ -600,7 +618,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'enrich', desc: 'Batch-enrich backlog with file context', category: 'tooling',
+        cmd: 'enrich', desc: 'Batch-enrich backlog with file context', category: 'tooling', audience: 'agent',
         flags: [
             { flag: '<backlog-path>', desc: 'Path to backlog file' },
             { flag: '--output=<path>', desc: 'Output path for enriched backlog' },
@@ -609,7 +627,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'stats', desc: 'Export stats JSON for slope-web live dashboard', category: 'tooling',
+        cmd: 'stats', desc: 'Export stats JSON for slope-web live dashboard', category: 'tooling', audience: 'internal',
         subcommands: [
             { name: 'export', desc: 'Compute SlopeStats JSON from local scorecards + registries', flags: [
                     { flag: '--pretty', desc: 'Pretty-print JSON output' },
@@ -618,7 +636,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'docs', desc: 'Generate documentation manifest and changelog', category: 'tooling',
+        cmd: 'docs', desc: 'Generate documentation manifest and changelog', category: 'tooling', audience: 'agent',
         subcommands: [
             { name: 'generate', desc: 'Build manifest JSON from registries + git history', flags: [
                     { flag: '--output=<path>', desc: 'Write manifest to path (default: .slope/docs.json)' },
@@ -642,7 +660,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'org', desc: 'Multi-repo aggregation and org-level metrics', category: 'analysis',
+        cmd: 'org', desc: 'Multi-repo aggregation and org-level metrics', category: 'analysis', audience: 'advanced',
         subcommands: [
             { name: 'init', desc: 'Create .slope/org.json template' },
             { name: 'status', desc: 'Show all repos with handicaps and sprint counts', flags: [
@@ -654,7 +672,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'memory', desc: 'Cross-session memory management', category: 'analysis',
+        cmd: 'memory', desc: 'Cross-session memory management', category: 'analysis', audience: 'advanced',
         subcommands: [
             { name: 'add', desc: 'Add a memory', flags: [
                     { flag: '--category=<cat>', desc: 'Category: workflow, style, project, hazard, other' },
@@ -675,7 +693,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'agent', desc: 'Machine-readable operational primitives for AI agents', category: 'tooling',
+        cmd: 'agent', desc: 'Machine-readable operational primitives for AI agents', category: 'tooling', audience: 'agent',
         subcommands: [
             { name: 'status', desc: 'Show current state (human or JSON)', flags: [
                     { flag: '--json', desc: 'Emit AgentStatus JSON' },
@@ -686,7 +704,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'ticket', desc: 'Per-ticket lifecycle commands', category: 'lifecycle',
+        cmd: 'ticket', desc: 'Per-ticket lifecycle commands', category: 'lifecycle', audience: 'agent',
         subcommands: [
             { name: 'done', desc: 'Mark ticket complete; release claim', flags: [
                     { flag: '<key>', desc: 'Ticket key (e.g. S1-1)' },
@@ -696,14 +714,14 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'commit-ready', desc: 'Pre-commit checklist for agents', category: 'tooling',
+        cmd: 'commit-ready', desc: 'Pre-commit checklist for agents', category: 'tooling', audience: 'agent',
         flags: [
             { flag: '--json', desc: 'Emit CommitReadyResult JSON' },
             { flag: '--strict', desc: 'Exit non-zero when blockers exist' },
         ],
     },
     {
-        cmd: 'gate', desc: 'Initiative review gate aliases (agent-friendly)', category: 'tooling',
+        cmd: 'gate', desc: 'Initiative review gate aliases (agent-friendly)', category: 'tooling', audience: 'agent',
         subcommands: [
             { name: 'status', desc: 'Pending plan/pr gates per sprint', flags: [
                     { flag: '--json', desc: 'Emit pending list as JSON' },
@@ -721,7 +739,7 @@ export const CLI_COMMAND_REGISTRY = [
         ],
     },
     {
-        cmd: 'pr', desc: 'Pull request helpers (auto-close, finalize, closeout)', category: 'tooling',
+        cmd: 'pr', desc: 'Pull request helpers (auto-close, finalize, closeout)', category: 'tooling', audience: 'agent',
         subcommands: [
             { name: 'finalize', desc: 'Inject Closes #N for issue refs in commit messages (#321)', flags: [
                     { flag: '--pr=<N>', desc: 'PR number (default: resolved from current branch)' },