docs: daily maintenance loop — 2026-06-26

scripts/generate_cli_docs.py

@@ -21,6 +21,7 @@
 
 import click
 import typer.main
+from typer.core import TyperArgument, TyperOption
 
 from social_hook.cli import app
 from social_hook.constants import PROJECT_SLUG
@@ -76,7 +77,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, (click.Argument, TyperArgument))]
     if args:
         lines.append("**Arguments:**")
         lines.append("")
@@ -93,7 +94,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, (click.Option, TyperOption)) and p.name not in skip]
     if opts:
         lines.append("**Options:**")
         lines.append("")

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-26 -->
 
 # 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-06-26 | |
+| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-06-26 | |
+| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-06-26 | |
+| `ruff check src/ tests/` passes | 2026-06-26 | |
+| `ruff format --check src/ tests/` passes | 2026-06-26 | |
+| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-06-26 | 28 errors, all `import-untyped` or `no-any-return` pre-existing |
+| All CLI commands with poor/partial docstrings have been enriched | 2026-06-26 | 16 commands across 6 files enriched |
+| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-06-26 | |
+| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-06-26 | |
+| All interactive CLI commands (e.g., `credentials add`) have documented non-interactive equivalents for agent/CI use | 2026-06-26 | `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-26 | 10 groups re-enriched this run (arc, bot, config, decision, draft, inspect, manual, media, memory, snapshot); 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. Create, complete, abandon, or resume multi-post story arcs that give the drafter thematic continuity across a series of posts.
 
 ---
 

site-docs/cli/bot.md

@@ -1,6 +1,6 @@
 # social-hook bot
 
-Bot daemon management.
+Bot daemon management. Start, stop, and check the status of the Telegram/Discord bot that lets you approve, reject, and schedule drafts from chat.
 
 ---
 

site-docs/cli/config.md

@@ -1,6 +1,6 @@
 # social-hook config
 
-View and modify configuration.
+View and modify configuration. Show the full config as YAML, get individual values by dotted key path, or set values at runtime.
 
 ---
 

site-docs/cli/decision.md

@@ -1,6 +1,6 @@
 # social-hook decision
 
-Decision management.
+Decision management. List, delete, retrigger, or rewind evaluation decisions. Supports batch evaluation and full pipeline re-runs from a commit.
 
 ---
 

site-docs/cli/draft.md

@@ -1,6 +1,6 @@
 # social-hook draft
 
-Draft lifecycle management.
+Draft lifecycle management. Approve, reject, schedule, edit, redraft, and post drafts. Covers the full workflow from initial draft through review to publication.
 
 ---
 

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. Create, complete, abandon, or resume multi-post story arcs that give the drafter thematic continuity across a series of posts. |
+| [`bot`](bot.md) | Bot daemon management. Start, stop, and check the status of the Telegram/Discord bot that lets you approve, reject, and schedule drafts from chat. |
 | [`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 configuration. Show the full config as YAML, get individual values by dotted key path, or set values at runtime. |
 | [`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) | Decision management. List, delete, retrigger, or rewind evaluation decisions. Supports batch evaluation and full pipeline re-runs from a commit. |
+| [`draft`](draft.md) | Draft lifecycle management. Approve, reject, schedule, edit, redraft, and post drafts. Covers the full workflow from initial draft through review to publication. |
+| [`inspect`](inspect.md) | Inspect system state. View the decision log, pending drafts, configured platforms, and LLM token usage across projects. |
 | [`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. |
+| [`manual`](manual.md) | Manual operations. Evaluate commits, create drafts, consolidate multiple decisions, and post approved drafts outside the automated pipeline. |
+| [`media`](media.md) | Media management. Clean up orphaned files from the media cache to reclaim disk space. |
+| [`memory`](memory.md) | Manage voice memories. Add, list, and delete per-project voice memories that guide the LLM's tone, style, and content preferences during drafting. |
 | [`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) | DB snapshot management. Save, restore, reset, list, and delete database snapshots for backup, testing, or recovery. |
 | [`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. |

site-docs/cli/inspect.md

@@ -1,6 +1,6 @@
 # social-hook inspect
 
-Inspect system state.
+Inspect system state. View the decision log, pending drafts, configured platforms, and LLM token usage across projects.
 
 ---
 

site-docs/cli/manual.md

@@ -1,6 +1,6 @@
 # social-hook manual
 
-Manual operations.
+Manual operations. Evaluate commits, create drafts, consolidate multiple decisions, and post approved drafts outside the automated pipeline.
 
 ---
 

site-docs/cli/media.md

@@ -1,6 +1,6 @@
 # social-hook media
 
-Media management.
+Media management. Clean up orphaned files from the media cache to reclaim disk space.
 
 ---
 

site-docs/cli/memory.md

@@ -1,6 +1,6 @@
 # social-hook memory
 
-Manage voice memories.
+Manage voice memories. Add, list, and delete per-project voice memories that guide the LLM's tone, style, and content preferences during drafting.
 
 ---
 

site-docs/cli/snapshot.md

@@ -1,6 +1,6 @@
 # social-hook snapshot
 
-DB snapshot management.
+DB snapshot management. Save, restore, reset, list, and delete database snapshots for backup, testing, or recovery.
 
 ---
 

src/social_hook/cli/__init__.py

@@ -161,6 +161,7 @@ def help_cmd(
     import json as json_mod
 
     import click
+    from typer.core import TyperArgument, TyperOption
 
     click_app = typer.main.get_command(app)
     # Handle --json appearing after command path (forgiving flag placement)
@@ -190,7 +191,7 @@ def _cmd_to_dict(cmd, name=None):
 
         args = []
         for param in cmd.params:
-            if isinstance(param, click.Argument):
+            if isinstance(param, (click.Argument, TyperArgument)):
                 args.append(
                     {
                         "name": param.name,
@@ -203,7 +204,7 @@ def _cmd_to_dict(cmd, name=None):
         opts = []
         skip_names = {"install_completion", "show_completion", "help", "ctx"}
         for param in cmd.params:
-            if isinstance(param, click.Option):
+            if isinstance(param, (click.Option, TyperOption)):
                 if param.name in skip_names:
                     continue
                 opt_info = {
@@ -260,7 +261,7 @@ def _resolve_command(parts):
             global_options = []
             skip_names = {"install_completion", "show_completion", "help", "ctx"}
             for param in click_app.params:
-                if isinstance(param, click.Option) and param.name not in skip_names:
+                if isinstance(param, (click.Option, TyperOption)) and param.name not in skip_names:
                     opt_info = {
                         "name": param.opts[0] if param.opts else f"--{param.name}",
                     }
@@ -527,7 +528,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="Bot daemon management. Start, stop, and check the status of the Telegram/Discord bot that lets you approve, reject, and schedule drafts from chat.",
+    no_args_is_help=True,
+)
 app.add_typer(bot_app, name="bot")
 
 
@@ -970,10 +975,18 @@ 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 state. View the decision log, pending drafts, configured platforms, and LLM token usage across projects.",
+)
 
 # Manual commands: evaluate, draft, post
-app.add_typer(manual_app, name="manual", help="Manual operations.")
+app.add_typer(
+    manual_app,
+    name="manual",
+    help="Manual operations. Evaluate commits, create drafts, consolidate multiple decisions, and post approved drafts outside the automated pipeline.",
+)
 
 # Setup wizard
 app.add_typer(setup_app, name="setup", help=f"Configure {PROJECT_SLUG}.")
@@ -989,32 +1002,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="View and modify configuration. Show the full config as YAML, get individual values by dotted key path, or set values at runtime.",
+)
 
 # 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. Add, list, and delete per-project voice memories that guide the LLM's tone, style, and content preferences during drafting.",
+)
 
 # 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. Create, complete, abandon, or resume multi-post story arcs that give the drafter thematic continuity across a series of posts.",
+)
 
 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="Decision management. List, delete, retrigger, or rewind evaluation decisions. Supports batch evaluation and full pipeline re-runs from a commit.",
+)
 
 # 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="Draft lifecycle management. Approve, reject, schedule, edit, redraft, and post drafts. Covers the full workflow from initial draft through review to publication.",
+)
 
 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="Media management. Clean up orphaned files from the media cache to reclaim disk space.",
+)
 
 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="DB snapshot management. Save, restore, reset, list, and delete database snapshots for backup, testing, or recovery.",
+)
 
 from social_hook.cli.account import app as account_app
 from social_hook.cli.advisory import app as advisory_app

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",
+    help="Media management. Clean up orphaned files from the media cache to reclaim disk space.",
+    no_args_is_help=True,
+)
 
 
 @app.command("gc")