nj-io · nj-io · Jun 15, 2026 · Jun 18, 2026
diff --git a/scripts/generate_cli_docs.py b/scripts/generate_cli_docs.py
@@ -20,11 +20,16 @@
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
 
 import click
+import typer.core
 import typer.main
 
 from social_hook.cli import app
 from social_hook.constants import PROJECT_SLUG
 
+# Typer >=0.26 uses its own param classes that don't inherit from click.*
+_argument_types = (click.Argument, typer.core.TyperArgument)
+_option_types = (click.Option, typer.core.TyperOption)
+
 DOCS_DIR = Path(__file__).resolve().parent.parent / "site-docs" / "cli"
 
 # Commands to exclude from docs (internal hooks)
@@ -76,7 +81,7 @@ def render_params(cmd: click.Command) -> str:
     skip = {"install_completion", "show_completion", "help", "ctx"}
 
     # Arguments
-    args = [p for p in cmd.params if isinstance(p, click.Argument)]
+    args = [p for p in cmd.params if isinstance(p, _argument_types)]
     if args:
         lines.append("**Arguments:**")
         lines.append("")
@@ -93,7 +98,7 @@ def render_params(cmd: click.Command) -> str:
         lines.append("")
 
     # Options
-    opts = [p for p in cmd.params if isinstance(p, click.Option) and p.name not in skip]
+    opts = [p for p in cmd.params if isinstance(p, _option_types) and p.name not in skip]
     if opts:
         lines.append("**Options:**")
         lines.append("")

diff --git a/site-docs/DOC_STATUS.md b/site-docs/DOC_STATUS.md
@@ -1,5 +1,5 @@
-<!-- last_run_commit: e0675da9f57694de2e6857eec0784bce5137b864 -->
-<!-- last_run_date: 2026-04-16 -->
+<!-- last_run_commit: 1afe4f10d28bede2e584ead914465ebe9279dcb9 -->
+<!-- last_run_date: 2026-06-18 -->
 
 # Documentation Status
 
@@ -96,16 +96,16 @@ Tracks coverage of external docs against the codebase. Used by the docs maintena
 
 | Check | Last passed | Notes |
 |-------|-------------|-------|
-| CLI docs are fresh (`generate_cli_docs.py` output matches committed) | 2026-04-16 | |
-| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-04-16 | |
-| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-04-16 | |
-| `ruff check src/ tests/` passes | 2026-04-16 | |
-| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-04-16 | 28 errors, all `import-untyped` or `no-any-return` pre-existing; fixed new `assignment` error in `brief.py` |
-| All CLI commands with poor/partial docstrings have been enriched | 2026-04-16 | 16 commands across 6 files enriched |
-| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-04-16 | |
-| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-04-16 | |
-| All interactive CLI commands (e.g., `credentials add`) have documented non-interactive equivalents for agent/CI use | 2026-04-16 | `credentials add --set`, all destructive commands have `--yes`; `setup` wizard → write config.yaml directly |
-| All CLI command groups have enriched group-level help text (not just terse labels) | 2026-04-16 | `project` and `journey` enriched this run; all 24 groups now have descriptive help |
+| CLI docs are fresh (`generate_cli_docs.py` output matches committed) | 2026-06-18 | Fixed Typer 0.26 compat in generator; param tables restored |
+| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-06-18 | |
+| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-06-18 | |
+| `ruff check src/ tests/` passes | 2026-06-18 | |
+| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-06-18 | 28 errors, all `import-untyped` or `no-any-return` pre-existing |
+| All CLI commands with poor/partial docstrings have been enriched | 2026-06-18 | |
+| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-06-18 | |
+| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-06-18 | |
+| All interactive CLI commands (e.g., `credentials add`) have documented non-interactive equivalents for agent/CI use | 2026-06-18 | `credentials add --set`, all destructive commands have `--yes`; `setup` wizard → write config.yaml directly |
+| All CLI command groups have enriched group-level help text (not just terse labels) | 2026-06-18 | `manual`, `setup`, `decision`, `media` enriched this run; all groups now have descriptive help |
 
 ## Backlog (waiting_approval)
 

diff --git a/site-docs/cli/decision.md b/site-docs/cli/decision.md
@@ -1,6 +1,6 @@
 # social-hook decision
 
-Decision management.
+View, delete, retrigger, or rewind evaluation decisions. Decisions record why a commit was drafted or skipped and can be replayed to regenerate content.
 
 ---
 

diff --git a/site-docs/cli/index.md b/site-docs/cli/index.md
@@ -28,13 +28,13 @@ These options can be placed before any command.
 | [`content`](content.md) | Submit content ideas, combine topics, and trigger hero launch drafts. |
 | [`credentials`](credentials.md) | Manage API keys and secrets in ~/.social-hook/.env. |
 | [`cycles`](cycles.md) | Inspect evaluation cycle history and per-strategy outcomes. |
-| [`decision`](decision.md) | Decision management. |
+| [`decision`](decision.md) | View, delete, retrigger, or rewind evaluation decisions. Decisions record why a commit was drafted or skipped and can be replayed to regenerate content. |
 | [`draft`](draft.md) | Draft lifecycle management. |
 | [`inspect`](inspect.md) | Inspect system state. |
 | [`journey`](journey.md) | Control Development Journey capture. When enabled, Claude Code hooks record session narratives that feed into the evaluation pipeline as rich development context. |
 | [`logs`](logs.md) | Log queries, tailing, and health. |
-| [`manual`](manual.md) | Manual operations. |
-| [`media`](media.md) | Media management. |
+| [`manual`](manual.md) | Run pipeline steps by hand. Evaluate a commit, draft content, consolidate a thread, or post a draft — outside the normal automated flow. |
+| [`media`](media.md) | Manage generated media assets. Run garbage collection to remove orphaned images and other media files that are no longer referenced by any draft. |
 | [`memory`](memory.md) | Manage voice memories. |
 | [`project`](project.md) | Register and manage projects. A project links a git repository (or folder) to Social Hook so commits are evaluated, content is drafted, and briefs are maintained. |
 | [`snapshot`](snapshot.md) | DB snapshot management. |
@@ -54,7 +54,7 @@ These options can be placed before any command.
 | [`quickstart`](root-commands.md#social-hook-quickstart) | Run the quickstart flow. |
 | [`rate-limits`](root-commands.md#social-hook-rate-limits) | Show current rate limit status (daily cap, gap timer, queue, cost). |
 | [`scheduler-tick`](root-commands.md#social-hook-scheduler-tick) | Post scheduled drafts whose time has arrived and promote deferred drafts. |
-| [`setup`](root-commands.md#social-hook-setup) | Configure social-hook. |
+| [`setup`](root-commands.md#social-hook-setup) | Run the interactive setup wizard. Walks through API keys, voice, platforms, scheduling, and media configuration. Use --only to configure a single component, or --validate to check existing config. |
 | [`test`](root-commands.md#social-hook-test) | Test commit evaluation. |
 | [`trigger`](root-commands.md#social-hook-trigger) | Run the full evaluation-to-draft pipeline for a single commit. |
 | [`version`](root-commands.md#social-hook-version) | Show version information. |

diff --git a/site-docs/cli/manual.md b/site-docs/cli/manual.md
@@ -1,6 +1,6 @@
 # social-hook manual
 
-Manual operations.
+Run pipeline steps by hand. Evaluate a commit, draft content, consolidate a thread, or post a draft — outside the normal automated flow.
 
 ---
 

diff --git a/site-docs/cli/media.md b/site-docs/cli/media.md
@@ -1,6 +1,6 @@
 # social-hook media
 
-Media management.
+Manage generated media assets. Run garbage collection to remove orphaned images and other media files that are no longer referenced by any draft.
 
 ---
 

diff --git a/site-docs/cli/root-commands.md b/site-docs/cli/root-commands.md
@@ -138,7 +138,7 @@ Example: social-hook --dry-run scheduler-tick
 
 ### `social-hook setup`
 
-Configure social-hook.
+Run the interactive setup wizard. Walks through API keys, voice, platforms, scheduling, and media configuration. Use --only to configure a single component, or --validate to check existing config.
 
 **Options:**
 

diff --git a/src/social_hook/cli/__init__.py b/src/social_hook/cli/__init__.py
@@ -973,10 +973,18 @@ def narrative_capture():
 app.add_typer(inspect_app, name="inspect", help="Inspect system state.")
 
 # Manual commands: evaluate, draft, post
-app.add_typer(manual_app, name="manual", help="Manual operations.")
+app.add_typer(
+    manual_app,
+    name="manual",
+    help="Run pipeline steps by hand. Evaluate a commit, draft content, consolidate a thread, or post a draft — outside the normal automated flow.",
+)
 
 # Setup wizard
-app.add_typer(setup_app, name="setup", help=f"Configure {PROJECT_SLUG}.")
+app.add_typer(
+    setup_app,
+    name="setup",
+    help="Run the interactive setup wizard. Walks through API keys, voice, platforms, scheduling, and media configuration. Use --only to configure a single component, or --validate to check existing config.",
+)
 
 # Test command
 app.add_typer(test_app, name="test", help="Test commit evaluation.")
@@ -1001,15 +1009,23 @@ def narrative_capture():
 from social_hook.cli.draft import app as draft_app
 
 # Decision management: list, delete
-app.add_typer(decision_app, name="decision", help="Decision management.")
+app.add_typer(
+    decision_app,
+    name="decision",
+    help="View, delete, retrigger, or rewind evaluation decisions. Decisions record why a commit was drafted or skipped and can be replayed to regenerate content.",
+)
 
 # Draft lifecycle: approve, reject, schedule, cancel, retry, edit, etc.
 app.add_typer(draft_app, name="draft", help="Draft lifecycle management.")
 
 from social_hook.cli.media import app as media_app
 
 # Media commands: gc
-app.add_typer(media_app, name="media", help="Media management.")
+app.add_typer(
+    media_app,
+    name="media",
+    help="Manage generated media assets. Run garbage collection to remove orphaned images and other media files that are no longer referenced by any draft.",
+)
 
 from social_hook.cli.snapshot import app as snapshot_app
 

diff --git a/src/social_hook/cli/decision.py b/src/social_hook/cli/decision.py
@@ -7,7 +7,10 @@
 
 import typer
 
-app = typer.Typer(no_args_is_help=True)
+app = typer.Typer(
+    no_args_is_help=True,
+    help="View, delete, retrigger, or rewind evaluation decisions. Decisions record why a commit was drafted or skipped and can be replayed to regenerate content.",
+)
 
 
 def _get_conn():

diff --git a/src/social_hook/cli/manual.py b/src/social_hook/cli/manual.py
@@ -4,7 +4,9 @@
 
 from social_hook.models.enums import PENDING_STATUSES
 
-app = typer.Typer()
+app = typer.Typer(
+    help="Run pipeline steps by hand. Evaluate a commit, draft content, consolidate a thread, or post a draft — outside the normal automated flow."
+)
 
 
 @app.command()

diff --git a/src/social_hook/cli/media.py b/src/social_hook/cli/media.py
@@ -4,7 +4,11 @@
 
 import typer
 
-app = typer.Typer(name="media", help="Media management.", no_args_is_help=True)
+app = typer.Typer(
+    name="media",
+    no_args_is_help=True,
+    help="Manage generated media assets. Run garbage collection to remove orphaned images and other media files that are no longer referenced by any draft.",
+)
 
 
 @app.command("gc")

diff --git a/src/social_hook/cli/setup.py b/src/social_hook/cli/setup.py
@@ -2,7 +2,9 @@
 
 import typer
 
-app = typer.Typer()
+app = typer.Typer(
+    help="Run the interactive setup wizard. Walks through API keys, voice, platforms, scheduling, and media configuration. Use --only to configure a single component, or --validate to check existing config."
+)
 
 
 @app.callback(invoke_without_command=True)