docs: daily maintenance loop — 2026-05-28 through 2026-05-30

scripts/generate_cli_docs.py

@@ -20,11 +20,19 @@
 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
 
+_OPTION_TYPES = (click.Option,)
+_ARGUMENT_TYPES = (click.Argument,)
+if hasattr(typer.core, "TyperOption"):
+    _OPTION_TYPES = (click.Option, typer.core.TyperOption)
+if hasattr(typer.core, "TyperArgument"):
+    _ARGUMENT_TYPES = (click.Argument, typer.core.TyperArgument)
+
 DOCS_DIR = Path(__file__).resolve().parent.parent / "site-docs" / "cli"
 
 # Commands to exclude from docs (internal hooks)
@@ -60,7 +68,7 @@ def format_default(param: click.Parameter) -> str:
     return str(param.default)
 
 
-def option_flags(param: click.Option) -> str:
+def option_flags(param: click.Parameter) -> str:
     """Format option flags like --name, -n."""
     parts = []
     for opt in param.opts:
@@ -76,7 +84,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 +101,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("")

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-05-30 -->
 
 # 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-05-30 | Fixed generator for Typer 0.26 (`TyperOption`/`TyperArgument` no longer subclass `click.Option`/`click.Argument`) |
+| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-05-30 | 24/24 |
+| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-05-30 | |
+| `ruff check src/ tests/` passes | 2026-05-30 | |
+| `ruff format --check src/ tests/` passes | 2026-05-30 | |
+| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-05-30 | 28 errors, all `import-untyped` or `no-any-return` pre-existing |
+| All CLI commands with poor/partial docstrings have been enriched | 2026-05-30 | |
+| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-05-30 | |
+| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-05-30 | |
+| All interactive CLI commands (e.g., `credentials add`) have documented non-interactive equivalents for agent/CI use | 2026-05-30 | `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-30 | 10 groups 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 — multi-post storylines that group related commits into coherent threads over days or weeks.
 
 ---
 

site-docs/cli/bot.md

@@ -1,6 +1,6 @@
 # social-hook bot
 
-Bot daemon management.
+Control the background bot daemon that continuously runs scheduler-tick and consolidation-tick to automate posting.
 
 ---
 

site-docs/cli/config.md

@@ -1,6 +1,6 @@
 # social-hook config
 
-View and modify configuration.
+View and edit the YAML configuration. Use dotted key paths to read or update individual settings (e.g., social-hook config set posting.interval_hours 4).
 
 ---
 

site-docs/cli/decision.md

@@ -1,6 +1,6 @@
 # social-hook decision
 
-Decision management.
+Manage evaluator decisions on commits. Delete decisions and their associated drafts, re-trigger evaluation, or batch-evaluate grouped decisions.
 
 ---
 

site-docs/cli/draft.md

@@ -1,6 +1,6 @@
 # social-hook draft
 
-Draft lifecycle management.
+Manage the full draft lifecycle: approve, reject, schedule, cancel, edit content, manage attached media, and control posting.
 
 ---
 

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 storylines that group related commits into coherent threads over days or weeks. |
+| [`bot`](bot.md) | Control the background bot daemon that continuously runs scheduler-tick and consolidation-tick to automate posting. |
 | [`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 edit the YAML configuration. Use dotted key paths to read or update individual settings (e.g., social-hook config set posting.interval_hours 4). |
 | [`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 evaluator decisions on commits. Delete decisions and their associated drafts, re-trigger evaluation, or batch-evaluate grouped decisions. |
+| [`draft`](draft.md) | Manage the full draft lifecycle: approve, reject, schedule, cancel, edit content, manage attached media, and control posting. |
+| [`inspect`](inspect.md) | Query system state: view the decision log, list pending drafts, check LLM token usage and costs, and see platform configuration 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, tail, and manage application logs. Check system health and clear old log entries. |
+| [`manual`](manual.md) | Manually trigger individual pipeline steps outside automation: evaluate commits, create drafts, consolidate multi-commit posts, or post immediately. |
+| [`media`](media.md) | Manage generated media assets. Garbage-collect orphaned media files that are no longer referenced by any draft. |
+| [`memory`](memory.md) | Store and manage voice memories — short feedback snippets and editorial preferences that guide the drafting LLM's tone and style. |
 | [`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) | Create, restore, and manage point-in-time database snapshots for backup, recovery, or testing. |
 | [`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.
+Query system state: view the decision log, list pending drafts, check LLM token usage and costs, and see platform configuration status.
 
 ---
 

site-docs/cli/logs.md

@@ -1,6 +1,6 @@
 # social-hook logs
 
-Log queries, tailing, and health.
+Query, tail, and manage application logs. Check system health and clear old log entries.
 
 **Group options:**
 

site-docs/cli/manual.md

@@ -1,6 +1,6 @@
 # social-hook manual
 
-Manual operations.
+Manually trigger individual pipeline steps outside automation: evaluate commits, create drafts, consolidate multi-commit posts, or post immediately.
 
 ---
 

site-docs/cli/media.md

@@ -1,6 +1,6 @@
 # social-hook media
 
-Media management.
+Manage generated media assets. Garbage-collect orphaned media files that are no longer referenced by any draft.
 
 ---
 

site-docs/cli/memory.md

@@ -1,6 +1,6 @@
 # social-hook memory
 
-Manage voice memories.
+Store and manage voice memories — short feedback snippets and editorial preferences that guide the drafting LLM's tone and style.
 
 ---
 

site-docs/cli/snapshot.md

@@ -1,6 +1,6 @@
 # social-hook snapshot
 
-DB snapshot management.
+Create, restore, and manage point-in-time database snapshots for backup, recovery, or testing.
 
 ---
 

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="Control the background bot daemon that continuously runs scheduler-tick and consolidation-tick to automate posting.",
+    no_args_is_help=True,
+)
 app.add_typer(bot_app, name="bot")
 
 
@@ -970,10 +974,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="Query system state: view the decision log, list pending drafts, check LLM token usage and costs, and see platform configuration status.",
+)
 
 # Manual commands: evaluate, draft, post
-app.add_typer(manual_app, name="manual", help="Manual operations.")
+app.add_typer(
+    manual_app,
+    name="manual",
+    help="Manually trigger individual pipeline steps outside automation: evaluate commits, create drafts, consolidate multi-commit posts, or post immediately.",
+)
 
 # Setup wizard
 app.add_typer(setup_app, name="setup", help=f"Configure {PROJECT_SLUG}.")
@@ -989,32 +1001,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 edit the YAML configuration. Use dotted key paths to read or update individual settings (e.g., social-hook config set posting.interval_hours 4).",
+)
 
 # 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="Store and manage voice memories — short feedback snippets and editorial preferences that guide the drafting LLM's tone and style.",
+)
 
 # 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 storylines that group related commits into coherent threads over days or weeks.",
+)
 
 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="Manage evaluator decisions on commits. Delete decisions and their associated drafts, re-trigger evaluation, or batch-evaluate grouped decisions.",
+)
 
 # 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 full draft lifecycle: approve, reject, schedule, cancel, edit content, manage attached media, and control posting.",
+)
 
 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 media files that are no longer referenced by any draft.",
+)
 
 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="Create, restore, and manage point-in-time database snapshots for backup, recovery, or testing.",
+)
 
 from social_hook.cli.account import app as account_app
 from social_hook.cli.advisory import app as advisory_app
@@ -1091,7 +1131,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, tail, and manage application logs. Check system health and clear old log entries.",
+)
 
 from social_hook.cli.events import events as events_cmd
 from social_hook.cli.quickstart import quickstart as quickstart_cmd

src/social_hook/cli/arc.py

@@ -4,7 +4,10 @@
 
 import typer
 
-app = typer.Typer(no_args_is_help=True)
+app = typer.Typer(
+    help="Manage narrative arcs — multi-post storylines that group related commits into coherent threads over days or weeks.",
+    no_args_is_help=True,
+)
 
 
 def _resolve_project(project: str | None = None) -> str:

src/social_hook/cli/config.py

@@ -5,7 +5,10 @@
 import typer
 import yaml
 
-app = typer.Typer(no_args_is_help=True)
+app = typer.Typer(
+    help="View and edit the YAML configuration. Use dotted key paths to read or update individual settings (e.g., social-hook config set posting.interval_hours 4).",
+    no_args_is_help=True,
+)
 
 
 def _parse_value(value: str):

src/social_hook/cli/decision.py

@@ -7,7 +7,10 @@
 
 import typer
 
-app = typer.Typer(no_args_is_help=True)
+app = typer.Typer(
+    help="Manage evaluator decisions on commits. Delete decisions and their associated drafts, re-trigger evaluation, or batch-evaluate grouped decisions.",
+    no_args_is_help=True,
+)
 
 
 def _get_conn():

src/social_hook/cli/draft.py

@@ -9,7 +9,10 @@
 
 from social_hook.models.enums import PENDING_STATUSES, TERMINAL_STATUSES
 
-app = typer.Typer(no_args_is_help=True)
+app = typer.Typer(
+    help="Manage the full draft lifecycle: approve, reject, schedule, cancel, edit content, manage attached media, and control posting.",
+    no_args_is_help=True,
+)
 
 
 def _get_conn():

src/social_hook/cli/inspect.py

@@ -2,7 +2,9 @@
 
 import typer
 
-app = typer.Typer()
+app = typer.Typer(
+    help="Query system state: view the decision log, list pending drafts, check LLM token usage and costs, and see platform configuration status.",
+)
 
 
 @app.command()

src/social_hook/cli/logs.py

@@ -6,7 +6,10 @@
 
 import typer
 
-app = typer.Typer(invoke_without_command=True)
+app = typer.Typer(
+    help="Query, tail, and manage application logs. Check system health and clear old log entries.",
+    invoke_without_command=True,
+)
 
 VALID_LOG_COMPONENTS = (
     "trigger",