nj-io · nj-io · Jun 27, 2026 · Jun 28, 2026 · Jun 29, 2026 · Jun 30, 2026
diff --git a/scripts/generate_cli_docs.py b/scripts/generate_cli_docs.py
@@ -20,6 +20,7 @@
 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
@@ -30,6 +31,9 @@
 # Commands to exclude from docs (internal hooks)
 HIDDEN_COMMANDS = {"commit-hook", "git-hook", "narrative-capture"}
 
+_OPTION_TYPES = (click.Option, typer.core.TyperOption)
+_ARGUMENT_TYPES = (click.Argument, typer.core.TyperArgument)
+
 
 def get_click_app() -> click.Group:
     return typer.main.get_command(app)
@@ -76,7 +80,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 +97,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-07-08 -->
 
 # Documentation Status
 
@@ -96,16 +96,17 @@ 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-07-08 | Fixed Typer 0.26 compat — `TyperOption`/`TyperArgument` no longer inherit from Click classes |
+| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-07-08 | 24/24 |
+| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-07-08 | |
+| `ruff check src/ tests/` passes | 2026-07-08 | |
+| `ruff format --check src/ tests/` passes | 2026-07-08 | |
+| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-07-08 | 28 errors, all `import-untyped` or `no-any-return` pre-existing |
+| All CLI commands with poor/partial docstrings have been enriched | 2026-07-08 | |
+| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-07-08 | |
+| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-07-08 | |
+| All interactive CLI commands (e.g., `credentials add`) have documented non-interactive equivalents for agent/CI use | 2026-07-08 | `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-07-08 | All 24 groups + subgroups have descriptive help; `project intro` enriched this run |
 
 ## Backlog (waiting_approval)
 

diff --git a/site-docs/cli/arc.md b/site-docs/cli/arc.md
@@ -1,6 +1,6 @@
 # social-hook arc
 
-Manage narrative arcs.
+Manage narrative arcs. Arcs are multi-post storylines that group related content under a theme, giving your audience a coherent thread to follow across posts.
 
 ---
 

diff --git a/site-docs/cli/bot.md b/site-docs/cli/bot.md
@@ -1,6 +1,6 @@
 # social-hook bot
 
-Bot daemon management.
+Start, stop, and check status of the Telegram/Discord bot daemon. The bot provides an interactive chat interface for reviewing drafts, approving posts, and managing the pipeline.
 
 ---
 

diff --git a/site-docs/cli/config.md b/site-docs/cli/config.md
@@ -1,6 +1,6 @@
 # social-hook config
 
-View and modify configuration.
+View and modify the Social Hook configuration. Read the full config as YAML, get individual values by dotted key path, or set scalar values without editing files directly.
 
 ---
 

diff --git a/site-docs/cli/decision.md b/site-docs/cli/decision.md
@@ -1,6 +1,6 @@
 # social-hook decision
 
-Decision management.
+Manage evaluation decisions. Decisions record whether a commit was deemed post-worthy by the LLM evaluator. Use these commands to list, delete, retrigger, rewind, or batch-evaluate decisions.
 
 ---
 

diff --git a/site-docs/cli/draft.md b/site-docs/cli/draft.md
@@ -1,6 +1,6 @@
 # social-hook draft
 
-Draft lifecycle management.
+Manage the full draft lifecycle. Approve, reject, schedule, edit, redraft, promote, and post drafts. Also manage media attachments and view draft details and change history.
 
 ---
 

diff --git a/site-docs/cli/index.md b/site-docs/cli/index.md
@@ -21,23 +21,23 @@ These options can be placed before any command.
 |-------|-------------|
 | [`account`](account.md) | Manage OAuth-authenticated platform accounts (X, LinkedIn). |
 | [`advisory`](advisory.md) | Manage advisory items — operator action items for manual tasks. |
-| [`arc`](arc.md) | Manage narrative arcs. |
-| [`bot`](bot.md) | Bot daemon management. |
+| [`arc`](arc.md) | Manage narrative arcs. Arcs are multi-post storylines that group related content under a theme, giving your audience a coherent thread to follow across posts. |
+| [`bot`](bot.md) | Start, stop, and check status of the Telegram/Discord bot daemon. The bot provides an interactive chat interface for reviewing drafts, approving posts, and managing the pipeline. |
 | [`brief`](brief.md) | View and edit the project brief used by the evaluator and drafter. |
-| [`config`](config.md) | View and modify configuration. |
+| [`config`](config.md) | View and modify the Social Hook configuration. Read the full config as YAML, get individual values by dotted key path, or set scalar values without editing files directly. |
 | [`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. |
-| [`draft`](draft.md) | Draft lifecycle management. |
-| [`inspect`](inspect.md) | Inspect system state. |
+| [`decision`](decision.md) | Manage evaluation decisions. Decisions record whether a commit was deemed post-worthy by the LLM evaluator. Use these commands to list, delete, retrigger, rewind, or batch-evaluate decisions. |
+| [`draft`](draft.md) | Manage the full draft lifecycle. Approve, reject, schedule, edit, redraft, promote, and post drafts. Also manage media attachments and view draft details and change history. |
+| [`inspect`](inspect.md) | Inspect system state. View the event log, list pending drafts awaiting action, check LLM token usage, and see configured platform connections. |
 | [`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. |
-| [`memory`](memory.md) | Manage voice memories. |
+| [`logs`](logs.md) | Query, tail, and manage log entries. View recent errors and warnings, follow live log output, clear old entries, and check overall system health across all pipeline components. |
+| [`manual`](manual.md) | Run pipeline steps manually. Evaluate a commit, create drafts from a decision, consolidate multiple decisions into one draft, or post an approved draft — bypassing the automated scheduler. |
+| [`media`](media.md) | Manage generated media assets. Run garbage collection to remove orphaned files from the media cache that are no longer referenced by any draft. |
+| [`memory`](memory.md) | Manage voice memories. Voice memories are persistent style and tone instructions that the LLM drafter uses when generating content, such as 'avoid jargon' or 'use first person plural'. |
 | [`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. |
+| [`snapshot`](snapshot.md) | Save, restore, and manage database snapshots. Snapshots let you bookmark the full system state and roll back if needed. A safety backup is created automatically before any restore or reset. |
 | [`strategy`](strategy.md) | View and customize content strategies (voice, audience, editorial rules). |
 | [`target`](target.md) | Configure where content is distributed (account + destination + strategy). |
 | [`topics`](topics.md) | Manage the prioritised content topic queue per strategy. |
@@ -55,7 +55,7 @@ These options can be placed before any command.
 | [`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. |
-| [`test`](root-commands.md#social-hook-test) | Test commit evaluation. |
+| [`test`](root-commands.md#social-hook-test) | Dry-run commit evaluation with real LLM calls but no database writes. Tests whether the AI considers commits post-worthy, with options to save results as JSON (--output) and diff against a previous run for regression testing (--compare). |
 | [`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. |
 | [`web`](root-commands.md#social-hook-web) | Start the web dashboard for managing your social-hook workflow visually. |
diff --git a/site-docs/cli/inspect.md b/site-docs/cli/inspect.md
@@ -1,6 +1,6 @@
 # social-hook inspect
 
-Inspect system state.
+Inspect system state. View the event log, list pending drafts awaiting action, check LLM token usage, and see configured platform connections.
 
 ---
 

diff --git a/site-docs/cli/logs.md b/site-docs/cli/logs.md
@@ -1,6 +1,6 @@
 # social-hook logs
 
-Log queries, tailing, and health.
+Query, tail, and manage log entries. View recent errors and warnings, follow live log output, clear old entries, and check overall system health across all pipeline components.
 
 **Group options:**
 

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 manually. Evaluate a commit, create drafts from a decision, consolidate multiple decisions into one draft, or post an approved draft — bypassing the automated scheduler.
 
 ---
 

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 files from the media cache that are no longer referenced by any draft.
 
 ---
 

diff --git a/site-docs/cli/memory.md b/site-docs/cli/memory.md
@@ -1,6 +1,6 @@
 # social-hook memory
 
-Manage voice memories.
+Manage voice memories. Voice memories are persistent style and tone instructions that the LLM drafter uses when generating content, such as 'avoid jargon' or 'use first person plural'.
 
 ---
 

diff --git a/site-docs/cli/project.md b/site-docs/cli/project.md
@@ -73,7 +73,7 @@ Example: social-hook project install-hook /path/to/repo
 
 ### `social-hook project intro`
 
-Manage per-platform introduction status.
+Manage per-platform introduction status. Tracks whether a project has posted its first 'introduction' on each platform — the intro post establishes context before regular content begins. Use 'status' to see which platforms have been introduced, 'set' to mark a platform as introduced, and 'reset' to clear introduction state.
 
 **Options:**
 

diff --git a/site-docs/cli/root-commands.md b/site-docs/cli/root-commands.md
@@ -152,7 +152,7 @@ Configure social-hook.
 
 ### `social-hook test`
 
-Test commit evaluation.
+Dry-run commit evaluation with real LLM calls but no database writes. Tests whether the AI considers commits post-worthy, with options to save results as JSON (--output) and diff against a previous run for regression testing (--compare).
 
 **Options:**
 

diff --git a/site-docs/cli/snapshot.md b/site-docs/cli/snapshot.md
@@ -1,6 +1,6 @@
 # social-hook snapshot
 
-DB snapshot management.
+Save, restore, and manage database snapshots. Snapshots let you bookmark the full system state and roll back if needed. A safety backup is created automatically before any restore or reset.
 
 ---