docs: daily maintenance loop — 2026-06-08

scripts/generate_cli_docs.py

@@ -20,6 +20,7 @@
 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
@@ -31,6 +32,14 @@
 HIDDEN_COMMANDS = {"commit-hook", "git-hook", "narrative-capture"}
 
 
+def _is_option(p: click.Parameter) -> bool:
+    return isinstance(p, (click.Option, typer.core.TyperOption))
+
+
+def _is_argument(p: click.Parameter) -> bool:
+    return isinstance(p, (click.Argument, typer.core.TyperArgument))
+
+
 def get_click_app() -> click.Group:
     return typer.main.get_command(app)
 
@@ -76,7 +85,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 _is_argument(p)]
     if args:
         lines.append("**Arguments:**")
         lines.append("")
@@ -93,7 +102,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 _is_option(p) 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-08 -->
 
 # 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-08 | Fixed Typer 0.26.7 compat in generator; enriched 4 draft docstrings (advisory flow) |
+| `mkdocs.yml` nav entries match files in `site-docs/cli/` | 2026-06-08 | 24/24 |
+| OAuth env vars in config.md use OAuth 2.0 names (`X_CLIENT_ID`, not `CONSUMER_KEY`) | 2026-06-08 | |
+| `ruff check src/ tests/` passes | 2026-06-08 | |
+| `ruff format src/ tests/` passes | 2026-06-08 | |
+| `mypy src/social_hook/` has no new errors (only pre-existing library stub issues) | 2026-06-08 | 28 errors, all `import-untyped` or `no-any-return` pre-existing |
+| All CLI commands with poor/partial docstrings have been enriched | 2026-06-08 | approve, schedule, post-now, quick-approve enriched with advisory flow note |
+| `pipeline.md` accurately describes the two-stage evaluation flow and targets path | 2026-06-08 | |
+| `narrative-arcs.md` uses `episode_tags` (not `episode_type`) and documents strategy-scoped arcs | 2026-06-08 | |
+| All interactive CLI commands (e.g., `credentials add`) have documented non-interactive equivalents for agent/CI use | 2026-06-08 | `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-08 | All 24 groups have descriptive help |
 
 ## Backlog (waiting_approval)
 

site-docs/cli/draft.md

@@ -10,6 +10,7 @@ Mark a draft as approved for posting.
 
 The scheduler will post it when its scheduled time arrives.
 Preview drafts must be promoted to a platform first.
+Non-auto-postable vehicles (e.g. articles) are redirected to advisory flow.
 
 Example: social-hook draft approve draft_abc123
 
@@ -168,6 +169,7 @@ Example: social-hook draft media-remove draft-abc123
 Post a draft immediately to its platform.
 
 Requires platform credentials in ~/.social-hook/.env.
+Non-auto-postable vehicles (e.g. articles) are redirected to advisory flow.
 
 Example: social-hook draft post-now draft_abc123
 Example: social-hook draft post-now draft_abc123 --yes  (skip confirmation)
@@ -217,6 +219,7 @@ Approve and schedule a draft for the next optimal posting time in one step.
 
 Combines approve + schedule. Considers your configured posting limits,
 preferred time windows, and minimum gap between posts to pick the best slot.
+Non-auto-postable vehicles (e.g. articles) are redirected to advisory flow.
 
 Example: social-hook draft quick-approve draft_abc123
 
@@ -317,6 +320,7 @@ Schedule a draft for posting at a specific or optimal time.
 With --time, posts at that exact ISO datetime. Without --time,
 automatically picks the next optimal slot based on your configured
 posting limits, time windows, and minimum gap between posts.
+Non-auto-postable vehicles (e.g. articles) are redirected to advisory flow.
 
 Example: social-hook draft schedule draft_abc123
 Example: social-hook draft schedule draft_abc123 --time 2026-03-25T10:00:00

src/social_hook/cli/draft.py

@@ -50,6 +50,7 @@ def approve(
 
     The scheduler will post it when its scheduled time arrives.
     Preview drafts must be promoted to a platform first.
+    Non-auto-postable vehicles (e.g. articles) are redirected to advisory flow.
 
     Example: social-hook draft approve draft_abc123
     """
@@ -151,6 +152,7 @@ def schedule(
     With --time, posts at that exact ISO datetime. Without --time,
     automatically picks the next optimal slot based on your configured
     posting limits, time windows, and minimum gap between posts.
+    Non-auto-postable vehicles (e.g. articles) are redirected to advisory flow.
 
     Example: social-hook draft schedule draft_abc123
     Example: social-hook draft schedule draft_abc123 --time 2026-03-25T10:00:00
@@ -528,6 +530,7 @@ def post_now(
     """Post a draft immediately to its platform.
 
     Requires platform credentials in ~/.social-hook/.env.
+    Non-auto-postable vehicles (e.g. articles) are redirected to advisory flow.
 
     Example: social-hook draft post-now draft_abc123
     Example: social-hook draft post-now draft_abc123 --yes  (skip confirmation)
@@ -651,6 +654,7 @@ def quick_approve(
 
     Combines approve + schedule. Considers your configured posting limits,
     preferred time windows, and minimum gap between posts to pick the best slot.
+    Non-auto-postable vehicles (e.g. articles) are redirected to advisory flow.
 
     Example: social-hook draft quick-approve draft_abc123
     """