docs: daily maintenance loop — 2026-05-10

site-docs/DOC_STATUS.md

@@ -1,5 +1,5 @@
-<!-- last_run_commit: e0675da9f57694de2e6857eec0784bce5137b864 -->
-<!-- last_run_date: 2026-04-16 -->
+<!-- last_run_commit: 615a871d519a1f393af7d56c215e2d9e77d3225e -->
+<!-- last_run_date: 2026-05-10 -->
 
 # 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-05-10 | |
+| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-05-10 | 24/24 match |
+| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-05-10 | |
+| `ruff check src/ tests/` passes | 2026-05-10 | |
+| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-05-10 | 28 errors, all `import-untyped` or `no-any-return` pre-existing |
+| All CLI commands with poor/partial docstrings have been enriched | 2026-05-10 | |
+| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-05-10 | |
+| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-05-10 | |
+| All interactive CLI commands (e.g., `credentials add`) have documented non-interactive equivalents for agent/CI use | 2026-05-10 | `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-05-10 | 13 groups enriched this run (bot, inspect, manual, setup, test, config, memory, arc, decision, draft, media, snapshot, logs); all 24 groups now have descriptive help |
 
 ## Backlog (waiting_approval)
 

site-docs/cli/arc.md

@@ -1,6 +1,6 @@
 # social-hook arc
 
-Manage narrative arcs.
+Manage narrative arcs — multi-post story threads that give a series of drafts a coherent throughline.
 
 ---
 

site-docs/cli/bot.md

@@ -1,6 +1,6 @@
 # social-hook bot
 
-Bot daemon management.
+Start, stop, and check status of the messaging bot daemon (Telegram, Discord).
 
 ---
 

site-docs/cli/config.md

@@ -1,6 +1,6 @@
 # social-hook config
 
-View and modify configuration.
+Show, get, or set configuration values in config.yaml.
 
 ---
 

site-docs/cli/decision.md

@@ -1,6 +1,6 @@
 # social-hook decision
 
-Decision management.
+View and manage evaluator decisions — the per-strategy draft/skip/hold verdicts from each evaluation cycle.
 
 ---
 

site-docs/cli/draft.md

@@ -1,6 +1,6 @@
 # social-hook draft
 
-Draft lifecycle management.
+Manage the draft lifecycle: approve, reject, schedule, edit, redraft, cancel, and post content drafts.
 
 ---
 

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 — multi-post story threads that give a series of drafts a coherent throughline. |
+| [`bot`](bot.md) | Start, stop, and check status of the messaging bot daemon (Telegram, Discord). |
 | [`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) | Show, get, or set configuration values in config.yaml. |
 | [`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) | View and manage evaluator decisions — the per-strategy draft/skip/hold verdicts from each evaluation cycle. |
+| [`draft`](draft.md) | Manage the draft lifecycle: approve, reject, schedule, edit, redraft, cancel, and post content drafts. |
+| [`inspect`](inspect.md) | Inspect system internals: recent log entries, pending drafts, LLM token usage, and platform connection status. |
 | [`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 structured log entries, tail live output, clear old logs, and check system health. |
+| [`manual`](manual.md) | Run pipeline steps manually — evaluate a commit, draft content, consolidate holds, or post a draft — bypassing the scheduler. |
+| [`media`](media.md) | Manage generated media assets: garbage-collect orphaned files. |
+| [`memory`](memory.md) | Manage voice memories — persistent style hints the drafter uses to shape tone and content. |
 | [`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 for backup, testing, or rollback. |
 | [`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. |
@@ -54,8 +54,8 @@ 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. |
-| [`test`](root-commands.md#social-hook-test) | Test commit evaluation. |
+| [`setup`](root-commands.md#social-hook-setup) | Interactive setup wizard for social-hook: platforms, credentials, accounts, targets, and strategies. |
+| [`test`](root-commands.md#social-hook-test) | Dry-run commit evaluation without creating drafts. Use --output/--compare to test evaluation consistency. |
 | [`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. |

site-docs/cli/inspect.md

@@ -1,6 +1,6 @@
 # social-hook inspect
 
-Inspect system state.
+Inspect system internals: recent log entries, pending drafts, LLM token usage, and platform connection status.
 
 ---
 

site-docs/cli/logs.md

@@ -1,6 +1,6 @@
 # social-hook logs
 
-Log queries, tailing, and health.
+Query structured log entries, tail live output, clear old logs, and check system health.
 
 **Group options:**
 

site-docs/cli/manual.md

@@ -1,6 +1,6 @@
 # social-hook manual
 
-Manual operations.
+Run pipeline steps manually — evaluate a commit, draft content, consolidate holds, or post a draft — bypassing the scheduler.
 
 ---
 

site-docs/cli/media.md

@@ -1,6 +1,6 @@
 # social-hook media
 
-Media management.
+Manage generated media assets: garbage-collect orphaned files.
 
 ---
 

site-docs/cli/memory.md

@@ -1,6 +1,6 @@
 # social-hook memory
 
-Manage voice memories.
+Manage voice memories — persistent style hints the drafter uses to shape tone and content.
 
 ---
 

site-docs/cli/root-commands.md

@@ -138,7 +138,7 @@ Example: social-hook --dry-run scheduler-tick
 
 ### `social-hook setup`
 
-Configure social-hook.
+Interactive setup wizard for social-hook: platforms, credentials, accounts, targets, and strategies.
 
 **Options:**
 
@@ -152,7 +152,7 @@ Configure social-hook.
 
 ### `social-hook test`
 
-Test commit evaluation.
+Dry-run commit evaluation without creating drafts. Use --output/--compare to test evaluation consistency.
 
 **Options:**
 

site-docs/cli/snapshot.md

@@ -1,6 +1,6 @@
 # social-hook snapshot
 
-DB snapshot management.
+Save, restore, and manage database snapshots for backup, testing, or rollback.
 
 ---
 

src/social_hook/cli/__init__.py

@@ -527,7 +527,11 @@ def _kill_port(p: int) -> None:
 # Bot subcommand group
 # =============================================================================
 
-bot_app = typer.Typer(name="bot", help="Bot daemon management.", no_args_is_help=True)
+bot_app = typer.Typer(
+    name="bot",
+    help="Start, stop, and check status of the messaging bot daemon (Telegram, Discord).",
+    no_args_is_help=True,
+)
 app.add_typer(bot_app, name="bot")
 
 
@@ -970,16 +974,32 @@ def narrative_capture():
 )
 
 # Inspection commands: log, pending, usage
-app.add_typer(inspect_app, name="inspect", help="Inspect system state.")
+app.add_typer(
+    inspect_app,
+    name="inspect",
+    help="Inspect system internals: recent log entries, pending drafts, LLM token usage, and platform connection status.",
+)
 
 # 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 manually — evaluate a commit, draft content, consolidate holds, or post a draft — bypassing the scheduler.",
+)
 
 # Setup wizard
-app.add_typer(setup_app, name="setup", help=f"Configure {PROJECT_SLUG}.")
+app.add_typer(
+    setup_app,
+    name="setup",
+    help=f"Interactive setup wizard for {PROJECT_SLUG}: platforms, credentials, accounts, targets, and strategies.",
+)
 
 # Test command
-app.add_typer(test_app, name="test", help="Test commit evaluation.")
+app.add_typer(
+    test_app,
+    name="test",
+    help="Dry-run commit evaluation without creating drafts. Use --output/--compare to test evaluation consistency.",
+)
 
 # Journey capture commands: on, off, status
 app.add_typer(
@@ -989,32 +1009,60 @@ def narrative_capture():
 )
 
 # Config commands: show, get, set
-app.add_typer(config_app, name="config", help="View and modify configuration.")
+app.add_typer(
+    config_app,
+    name="config",
+    help="Show, get, or set configuration values in config.yaml.",
+)
 
 # Memory commands: list, add, delete, clear
-app.add_typer(memory_app, name="memory", help="Manage voice memories.")
+app.add_typer(
+    memory_app,
+    name="memory",
+    help="Manage voice memories — persistent style hints the drafter uses to shape tone and content.",
+)
 
 # Arc commands: list, create, complete, abandon
-app.add_typer(arc_app, name="arc", help="Manage narrative arcs.")
+app.add_typer(
+    arc_app,
+    name="arc",
+    help="Manage narrative arcs — multi-post story threads that give a series of drafts a coherent throughline.",
+)
 
 from social_hook.cli.decision import app as decision_app
 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 and manage evaluator decisions — the per-strategy draft/skip/hold verdicts from each evaluation cycle.",
+)
 
 # Draft lifecycle: approve, reject, schedule, cancel, retry, edit, etc.
-app.add_typer(draft_app, name="draft", help="Draft lifecycle management.")
+app.add_typer(
+    draft_app,
+    name="draft",
+    help="Manage the draft lifecycle: approve, reject, schedule, edit, redraft, cancel, and post content drafts.",
+)
 
 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: garbage-collect orphaned files.",
+)
 
 from social_hook.cli.snapshot import app as snapshot_app
 
 # DB snapshot management: save, restore, reset, list, delete
-app.add_typer(snapshot_app, name="snapshot", help="DB snapshot management.")
+app.add_typer(
+    snapshot_app,
+    name="snapshot",
+    help="Save, restore, and manage database snapshots for backup, testing, or rollback.",
+)
 
 from social_hook.cli.account import app as account_app
 from social_hook.cli.advisory import app as advisory_app
@@ -1091,7 +1139,11 @@ def narrative_capture():
 )
 
 # Log queries, tailing, and health
-app.add_typer(logs_app, name="logs", help="Log queries, tailing, and health.")
+app.add_typer(
+    logs_app,
+    name="logs",
+    help="Query structured log entries, tail live output, clear old logs, and check system health.",
+)
 
 from social_hook.cli.events import events as events_cmd
 from social_hook.cli.quickstart import quickstart as quickstart_cmd