Merge pull request #62 from nj-io/docs-maintenance/maintenance-2026-03-25

chore(docs-maintenance): maintenance run 2026-03-25

Author: nj-io

.claude/agents/maintenance-loop.md

@@ -39,10 +39,16 @@ approval_required:                    # Work that needs PR comment approval firs
 
 ### Step 1: Setup
 
+Always start from the latest target branch:
+
 ```bash
-git checkout <branch> && git pull origin <branch>
+git fetch origin <branch>
+git checkout <branch>
+git pull origin <branch>
 ```
 
+All maintenance branches are created from the target branch (step 8), never from a worktree's working branch.
+
 Run any `setup` commands from config. Then detect environment:
 
 ```bash
@@ -90,7 +96,7 @@ For each change in the diff:
 - If it falls under `autonomous` rules — do it
 - If it needs new content — check if previously approved (from step 4 or state file)
   - If approved — do it
-  - If not — add to "Waiting for review" in the PR
+  - If not — add to "Backlog" in the PR
 
 ### Step 6: Run checks
 
@@ -134,7 +140,7 @@ Create manually: gh pr create --base <branch> --head <loop_name>/maintenance-<da
 ## Summary
 - <bullet per change made>
 
-## Waiting for review
+## Backlog
 - [ ] <item> — <what it is and why it needs approval>
 
 ## State

mkdocs.yml

@@ -67,9 +67,14 @@ nav:
   - CLI Reference:
     - Overview: cli/index.md
     - Commands: cli/root-commands.md
+    - account: cli/account.md
     - arc: cli/arc.md
     - bot: cli/bot.md
+    - brief: cli/brief.md
     - config: cli/config.md
+    - content: cli/content.md
+    - credentials: cli/credentials.md
+    - cycles: cli/cycles.md
     - decision: cli/decision.md
     - draft: cli/draft.md
     - inspect: cli/inspect.md
@@ -79,6 +84,10 @@ nav:
     - memory: cli/memory.md
     - project: cli/project.md
     - snapshot: cli/snapshot.md
+    - strategy: cli/strategy.md
+    - logs: cli/logs.md
+    - target: cli/target.md
+    - topics: cli/topics.md
   - Concepts:
     - Overview: concepts/index.md
     - How the Pipeline Works: concepts/pipeline.md

site-docs/DOC_STATUS.md

@@ -1,5 +1,5 @@
-<!-- last_run_commit: 21c6a1ffe50cdf762497b4b5c0b0879ddc1fdc56 -->
-<!-- last_run_date: 2026-03-24 -->
+<!-- last_run_commit: 6688d91b2ee4da630f9dec8dae1d776ae89b5a4c -->
+<!-- last_run_date: 2026-03-30 -->
 
 # Documentation Status
 
@@ -9,72 +9,105 @@ Tracks coverage of external docs against the codebase. Used by the docs maintena
 
 | Command | Coverage | Notes |
 |---------|----------|-------|
-| `quickstart` | poor | "Run the quickstart flow" — says nothing about what it does |
-| `consolidation-tick` | poor | No context on when/why to run |
-| `scheduler-tick` | poor | No context on when/why to run |
-| `discover` | poor | "Two-pass project discovery" is jargon |
-| `setup` | partial | `--only` component values unexplained |
-| `test` | poor | No explanation of `--compare`/`--output` workflow |
-| `trigger` | poor | Doesn't explain how it differs from `test` |
+| `quickstart` | ok | Enriched: explains full onboarding flow |
+| `consolidation-tick` | ok | Enriched: explains hold processing, modes, cron usage |
+| `scheduler-tick` | ok | Enriched: explains posting, deferred promotion, cron |
+| `discover` | ok | Enriched: explains two-pass LLM analysis |
+| `setup` | partial | `--only` component values still unexplained |
+| `test` | ok | Enriched: explains dry-run, --output/--compare |
+| `trigger` | ok | Enriched: explains full pipeline, contrasts with test |
 | `init` | ok | |
 | `events` | ok | Has examples |
 | `help` | ok | Has examples |
 | `rate-limits` | ok | Has examples |
 | `version` | ok | |
-| `web` | poor | "Start the web dashboard" — no detail on what it offers |
-| `draft approve` | poor | Just restates the command name |
-| `draft cancel` | poor | Just restates the command name |
-| `draft retry` | poor | Just restates the command name |
-| `draft quick-approve` | poor | No explanation of what "optimal time" means |
-| `draft schedule` | partial | Doesn't explain auto-scheduling behavior |
-| `draft edit` | ok | Has example |
+| `web` | ok | Enriched: explains dashboard capabilities |
+| `account *` | ok | Group help enriched; subcommand docstrings already good |
+| `brief *` | ok | Group help enriched; subcommand docstrings already good |
+| `content *` | ok | Group help enriched; subcommand docstrings already good |
+| `credentials *` | ok | Group help enriched; subcommand docstrings already good |
+| `cycles *` | ok | Group help enriched; subcommand docstrings already good |
+| `strategy *` | ok | `show` enriched with displayed fields |
+| `logs *` | ok | Replaced `system *`; query, tail, clear, health subcommands |
+| `target *` | ok | `enable` enriched with re-enable behavior |
+| `topics *` | ok | Group help enriched; subcommand docstrings already good |
+| `decision *` | ok | `list` and `delete` enriched with decision context |
+| `inspect *` | ok | `log`, `pending`, `usage`, `platforms` all enriched with detail and examples |
+| `manual *` | ok | `draft`, `consolidate`, `post` enriched with LLM context and examples |
+| `draft approve` | ok | Enriched: explains scheduler interaction |
+| `draft cancel` | ok | Enriched: explains queue removal |
+| `draft retry` | ok | Enriched: explains re-queuing |
+| `draft quick-approve` | ok | Enriched: explains combined approve + optimal scheduling |
+| `draft schedule` | ok | Enriched: explains auto-scheduling vs explicit --time |
+| `draft edit` | ok | Enriched: change history, thread re-split |
 | `draft list` | ok | Has examples |
-| `draft media-edit` | ok | Has example |
-| `draft media-regen` | ok | |
+| `draft media-edit` | ok | Enriched: media spec structure explanation |
+| `draft media-regen` | ok | Enriched: media spec workflow |
 | `draft media-remove` | ok | |
 | `draft post-now` | ok | |
 | `draft promote` | ok | Has example |
-| `draft redraft` | ok | Has example |
-| `draft reject` | ok | Has example |
-| `draft reopen` | ok | |
+| `draft redraft` | ok | Enriched: Expert agent, LLM op, change history |
+| `draft reject` | ok | Enriched: cascading re-draft, voice memory |
+| `draft reopen` | ok | Enriched: intro restriction, resulting status |
 | `draft show` | ok | |
-| `draft unapprove` | ok | |
-| `draft unschedule` | ok | |
+| `draft unapprove` | ok | Enriched: resulting status, when to use |
+| `draft connect` | ok | New: links preview draft to an account |
+| `draft unschedule` | ok | Enriched: resulting status, when to use |
 
 ## Conceptual Docs (site-docs/concepts/)
 
 | Page | Status | Notes |
 |------|--------|-------|
-| pipeline.md | complete | 298 lines, thorough stage-by-stage walkthrough |
-| narrative-arcs.md | complete | |
+| pipeline.md | complete | Rewritten: two-stage eval (analyzer+evaluator), batch evaluation, interval gating, per-strategy decisions, target routing, evaluation cycles, preview mode |
+| narrative-arcs.md | complete | Updated: strategy-scoped arcs, `episode_tags` (was `episode_type`) |
 | voice-memory.md | complete | |
 | media-generation.md | complete | |
+| targets.md | missing | New core concept — waiting_approval |
+| topics.md | missing | New content source system — waiting_approval |
+| routing.md | missing | New target routing system — waiting_approval |
 | web-dashboard.md | missing | No page exists — waiting_approval |
 | scheduling.md | missing | Covered briefly in config.md — waiting_approval |
 
 ## Configuration Docs (site-docs/configuration/)
 
 | Page | Status | Notes |
 |------|--------|-------|
-| config.md | complete | Full field-by-field reference |
+| config.md | stale | OAuth 2.0 env vars correct; missing sections: rate_limits, identities, content_strategies, platform_credentials, accounts, targets, platform_settings, max_targets, logging/LogBus |
 | content-config.md | complete | |
 | social-context.md | complete | |
 
 ## Getting Started (site-docs/getting-started/)
 
 | Page | Status | Notes |
 |------|--------|-------|
-| installation.md | complete | Leads with quickstart |
-| quickstart.md | complete | Step-by-step guide |
+| installation.md | complete | Accurate for current quickstart flow; targets workflow addendum in backlog |
+| quickstart.md | complete | Preview draft → promote flow still valid; targets onboarding in backlog |
 
 ## Recurring Checks
 
 | Check | Last passed | Notes |
 |-------|-------------|-------|
+| CLI docs are fresh (`generate_cli_docs.py` output matches committed) | 2026-03-30 | |
+| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-03-30 | Fixed: `system` → `logs` |
+| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-03-30 | |
+| `ruff check src/ tests/` passes | 2026-03-30 | |
+| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-03-30 | 28 errors, all `import-untyped` or pre-existing |
+| All CLI commands with poor/partial docstrings have been enriched | 2026-03-30 | 16 commands across 6 files enriched |
+| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-03-30 | |
+| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-03-30 | |
 
 ## Backlog (waiting_approval)
 
+- [ ] Targets concept page — how accounts, targets, and strategies work
+- [ ] Topics concept page — content sources, topic queue, suggestions
+- [ ] Routing concept page — how drafts get routed to targets
 - [ ] Web dashboard usage guide (#19)
 - [ ] Workflow tutorials (#20)
 - [ ] examples/ directory (#22)
 - [ ] Scheduling deep-dive (how optimal times are calculated, posting windows, rate limits)
+- [ ] Agent-first CLI equivalents — interactive commands like `setup` need non-interactive agent equivalents, then documented
+- [x] ~~Enrich docstrings for partial/poor CLI commands~~ (done — 16 commands enriched across inspect, decision, manual, draft, strategy, target)
+- [ ] config.md expansion — add sections for rate_limits, identities, content_strategies, platform_credentials, accounts, targets, platform_settings, max_targets, logging/LogBus
+- [x] ~~pipeline.md rewrite~~ (done — two-stage evaluation, commit analyzer, batch evaluation, interval gating, per-strategy decisions, target routing)
+- [ ] Testing guide — unit tests, E2E test suite, snapshots, VCR cassettes, verification scripts (source: docs/E2E_TESTING.md, docs/CLAUDE.md E2E section)
+- [ ] E2E test reference — sections, scenarios, three-dimension protocol, --pause mode, harness helpers (source: docs/E2E_TESTING.md, scripts/e2e/)

site-docs/cli/account.md

@@ -1,6 +1,6 @@
 # social-hook account
 
-Platform account management.
+Manage OAuth-authenticated platform accounts (X, LinkedIn).
 
 ---
 

site-docs/cli/brief.md

@@ -1,6 +1,6 @@
 # social-hook brief
 
-Project brief management.
+View and edit the project brief used by the evaluator and drafter.
 
 ---
 

site-docs/cli/content.md

@@ -1,6 +1,6 @@
 # social-hook content
 
-Content suggestions and operations.
+Submit content ideas, combine topics, and trigger hero launch drafts.
 
 ---
 

site-docs/cli/credentials.md

@@ -1,6 +1,6 @@
 # social-hook credentials
 
-Platform credential management.
+Manage API keys and secrets in ~/.social-hook/.env.
 
 ---
 

site-docs/cli/cycles.md

@@ -1,6 +1,6 @@
 # social-hook cycles
 
-Evaluation cycle history.
+Inspect evaluation cycle history and per-strategy outcomes.
 
 ---
 

site-docs/cli/decision.md

@@ -8,6 +8,10 @@ Decision management.
 
 Delete a decision and its associated drafts.
 
+A decision is the evaluator's verdict on a commit (draft, skip, or defer).
+This permanently removes the decision and all linked drafts from the
+database. This action cannot be undone.
+
 Example: social-hook decision delete decision-abc123
 
 **Arguments:**
@@ -29,7 +33,13 @@ Example: social-hook decision delete decision-abc123
 
 List decisions for a project.
 
-Example: social-hook decision list --project .
+Decisions are evaluator outcomes for commits (draft, skip, or defer).
+Each row shows the decision ID, commit hash, type, media tool, content
+angle, and date.
+
+Examples:
+    social-hook decision list --project .
+    social-hook decision list --limit 50 --json
 
 **Options:**
 

site-docs/cli/draft.md

@@ -64,6 +64,9 @@ Example: social-hook draft connect draft-abc123 --account my-x-account
 
 Edit draft content.
 
+Records the change in the draft's change history (visible in draft show).
+If the draft is a thread, tweet boundaries are automatically re-split.
+
 Example: social-hook draft edit draft-abc123 --content "Updated post text here"
 
 **Arguments:**
@@ -107,6 +110,10 @@ Example: social-hook draft list --tag auth
 
 Edit the media spec for a draft.
 
+The media spec is a JSON object that controls media generation (e.g.,
+code snippet, language, theme). After editing, run media-regen to
+produce a new media file from the updated spec.
+
 Example: social-hook draft media-edit draft-abc123 --spec '{"code": "print(42)", "language": "python"}'
 
 **Arguments:**
@@ -127,6 +134,10 @@ Example: social-hook draft media-edit draft-abc123 --spec '{"code": "print(42)",
 
 Regenerate media for a draft using its stored media spec.
 
+The media spec is a JSON object describing what to generate (e.g., code
+snippet image, diagram). Edit the spec first with media-edit, then run
+this command to produce a new file from the updated spec.
+
 Example: social-hook draft media-regen draft-abc123
 
 **Arguments:**
@@ -219,6 +230,10 @@ Example: social-hook draft quick-approve draft_abc123
 
 Redraft content using the Expert agent with a new angle.
 
+Calls the Expert LLM agent to rewrite the draft with a different
+direction. May also update the media spec. Changes are recorded
+in the draft's change history.
+
 Example: social-hook draft redraft draft-abc123 --angle "focus on the performance gains"
 
 **Arguments:**
@@ -237,7 +252,11 @@ Example: social-hook draft redraft draft-abc123 --angle "focus on the performanc
 
 ### `social-hook draft reject`
 
-Reject a draft (saves reason as voice memory when --reason provided).
+Reject a draft and optionally record feedback as voice memory.
+
+When --reason is provided, the feedback is saved to voice memory so the
+drafter learns from it in future runs. If the draft is an intro draft,
+rejection cascades to re-draft the introduction for that platform.
 
 Example: social-hook draft reject draft-abc123 --reason "too technical for the audience"
 
@@ -257,7 +276,10 @@ Example: social-hook draft reject draft-abc123 --reason "too technical for the a
 
 ### `social-hook draft reopen`
 
-Reopen a cancelled or rejected draft.
+Reopen a cancelled or rejected draft, returning it to 'draft' status.
+
+Intro drafts cannot be reopened -- create a new draft instead.
+Clears any previous error message on the draft.
 
 Example: social-hook draft reopen draft-abc123
 
@@ -334,7 +356,10 @@ Example: social-hook draft show draft-abc123
 
 ### `social-hook draft unapprove`
 
-Revert approval on a draft.
+Revert approval on a draft, returning it to 'draft' status.
+
+Use when you approved a draft prematurely and want to make further
+edits before scheduling or posting.
 
 Example: social-hook draft unapprove draft-abc123
 
@@ -348,7 +373,10 @@ Example: social-hook draft unapprove draft-abc123
 
 ### `social-hook draft unschedule`
 
-Revert scheduling on a draft.
+Revert scheduling on a draft, returning it to 'draft' status.
+
+Clears the scheduled time. Use when you need to edit or reschedule
+a draft that was already queued for posting.
 
 Example: social-hook draft unschedule draft-abc123