diff --git a/site-docs/DOC_STATUS.md b/site-docs/DOC_STATUS.md index 383d019..6d1f8af 100644 --- a/site-docs/DOC_STATUS.md +++ b/site-docs/DOC_STATUS.md @@ -1,5 +1,5 @@ - - + + # 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-21 | | +| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-05-21 | 24/24 match | +| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-05-21 | | +| `ruff check src/ tests/` passes | 2026-05-21 | | +| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-05-21 | 28 errors, all `import-untyped` or `no-any-return` pre-existing | +| All CLI commands with poor/partial docstrings have been enriched | 2026-05-21 | | +| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-05-21 | | +| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-05-21 | | +| All interactive CLI commands (e.g., `credentials add`) have documented non-interactive equivalents for agent/CI use | 2026-05-21 | `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-21 | 12 remaining terse 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) diff --git a/site-docs/cli/arc.md b/site-docs/cli/arc.md index d6e82cc..8436c31 100644 --- 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 — multi-episode story threads the drafter weaves across posts within a strategy. --- diff --git a/site-docs/cli/bot.md b/site-docs/cli/bot.md index de2b1de..19f44fc 100644 --- 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 the status of the bot daemon that listens for chat commands. --- diff --git a/site-docs/cli/config.md b/site-docs/cli/config.md index db771a0..6d00599 100644 --- 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 configuration values. Use 'show' for the full config, 'get' for a single key, or 'set' to update a value. --- diff --git a/site-docs/cli/decision.md b/site-docs/cli/decision.md index 9b5141b..8facb2c 100644 --- 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 from the pipeline log. --- diff --git a/site-docs/cli/draft.md b/site-docs/cli/draft.md index 90b62d6..e10e1f6 100644 --- a/site-docs/cli/draft.md +++ b/site-docs/cli/draft.md @@ -1,6 +1,6 @@ # social-hook draft -Draft lifecycle management. +Draft lifecycle — approve, reject, schedule, edit, redraft, cancel, and post content drafts. --- diff --git a/site-docs/cli/index.md b/site-docs/cli/index.md index 8e35199..ce28ef6 100644 --- 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 — multi-episode story threads the drafter weaves across posts within a strategy. | +| [`bot`](bot.md) | Start, stop, and check the status of the bot daemon that listens for chat commands. | | [`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 values. Use 'show' for the full config, 'get' for a single key, or 'set' to update a value. | | [`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, delete, retrigger, or rewind evaluation decisions from the pipeline log. | +| [`draft`](draft.md) | Draft lifecycle — approve, reject, schedule, edit, redraft, cancel, and post content drafts. | +| [`inspect`](inspect.md) | View decision log, pending drafts, LLM token usage, and connected platform capabilities. | | [`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 clear application event logs. Includes a health check for pipeline and LogBus status. | +| [`manual`](manual.md) | Manually trigger pipeline stages — evaluate a commit, create a draft, consolidate holds, or post a scheduled draft. | +| [`media`](media.md) | Manage generated media assets. Use 'gc' to garbage-collect orphaned media files. | +| [`memory`](memory.md) | Manage voice memories — persistent style and tone notes the drafter references when composing 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, list, and delete database snapshots for backup and experimentation. | | [`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) | Run the interactive setup wizard to configure social-hook — credentials, accounts, projects, and strategies. Use --only to configure a single component. | +| [`test`](root-commands.md#social-hook-test) | Dry-run commit evaluation without creating drafts. Supports --output to save results and --compare to diff against a previous run. | | [`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 index 40ff3e8..2c79eb9 100644 --- a/site-docs/cli/inspect.md +++ b/site-docs/cli/inspect.md @@ -1,6 +1,6 @@ # social-hook inspect -Inspect system state. +View decision log, pending drafts, LLM token usage, and connected platform capabilities. --- diff --git a/site-docs/cli/logs.md b/site-docs/cli/logs.md index bf4c4e3..42861c4 100644 --- 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 clear application event logs. Includes a health check for pipeline and LogBus status. **Group options:** diff --git a/site-docs/cli/manual.md b/site-docs/cli/manual.md index c77cccb..68b2eb7 100644 --- a/site-docs/cli/manual.md +++ b/site-docs/cli/manual.md @@ -1,6 +1,6 @@ # social-hook manual -Manual operations. +Manually trigger pipeline stages — evaluate a commit, create a draft, consolidate holds, or post a scheduled draft. --- diff --git a/site-docs/cli/media.md b/site-docs/cli/media.md index b0b1bd6..fc2fd9b 100644 --- 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. Use 'gc' to garbage-collect orphaned media files. --- diff --git a/site-docs/cli/memory.md b/site-docs/cli/memory.md index e857b7d..0a112d2 100644 --- 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 — persistent style and tone notes the drafter references when composing content. --- diff --git a/site-docs/cli/root-commands.md b/site-docs/cli/root-commands.md index 695e40a..1611fbc 100644 --- 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 to configure social-hook — credentials, accounts, projects, and strategies. Use --only to configure a single component. **Options:** @@ -152,7 +152,7 @@ Configure social-hook. ### `social-hook test` -Test commit evaluation. +Dry-run commit evaluation without creating drafts. Supports --output to save results and --compare to diff against a previous run. **Options:** diff --git a/site-docs/cli/snapshot.md b/site-docs/cli/snapshot.md index 5ad19e9..e90835e 100644 --- a/site-docs/cli/snapshot.md +++ b/site-docs/cli/snapshot.md @@ -1,6 +1,6 @@ # social-hook snapshot -DB snapshot management. +Save, restore, list, and delete database snapshots for backup and experimentation. --- diff --git a/src/social_hook/cli/__init__.py b/src/social_hook/cli/__init__.py index 4f40f21..cb806b1 100644 --- a/src/social_hook/cli/__init__.py +++ b/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 the status of the bot daemon that listens for chat commands.", + 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="View decision log, pending drafts, LLM token usage, and connected platform capabilities.", +) # 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 pipeline stages — evaluate a commit, create a draft, consolidate holds, or post a scheduled draft.", +) # Setup wizard -app.add_typer(setup_app, name="setup", help=f"Configure {PROJECT_SLUG}.") +app.add_typer( + setup_app, + name="setup", + help=f"Run the interactive setup wizard to configure {PROJECT_SLUG} — credentials, accounts, projects, and strategies. Use --only to configure a single component.", +) # 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. Supports --output to save results and --compare to diff against a previous run.", +) # 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="View and modify configuration values. Use 'show' for the full config, 'get' for a single key, or 'set' to update a value.", +) # 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 and tone notes the drafter references when composing 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-episode story threads the drafter weaves across posts within a strategy.", +) 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, delete, retrigger, or rewind evaluation decisions from the pipeline log.", +) # 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 — 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. Use 'gc' to garbage-collect orphaned media 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, list, and delete database snapshots for backup and experimentation.", +) 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, tail, and clear application event logs. Includes a health check for pipeline and LogBus status.", +) from social_hook.cli.events import events as events_cmd from social_hook.cli.quickstart import quickstart as quickstart_cmd diff --git a/src/social_hook/cli/media.py b/src/social_hook/cli/media.py index d5d7a3f..4fb4eee 100644 --- 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", + help="Manage generated media assets. Use 'gc' to garbage-collect orphaned media files.", + no_args_is_help=True, +) @app.command("gc")