[docs] - document the real-repo-run-plan two-stage cloud-plan recipe

[cgfixit]

Proposed changes

The "cloud model plans once, local Qwen implements iteratively" design in agentic/real_repo_loop.py is real and functional — generate_plan()'s output, saved and passed via --plan-file, is read into run_real_repo_loop's plan parameter and folded into every iteration's prompt ahead of any GitHub context (pinned by tests/test_agentic_plan_handoff.py). But it was undocumented anywhere operator-facing: docs/agentic/AGENTIC_README.md's Commands section and its full "Governed GitHub coding harness" write-up (§9) never mentioned the real-repo-run-plan subcommand or --plan-file at all, and CLAUDE.md's module-table row named only the bare fact of "an optional cloud planner behind --provider/--confirm-online" with no disambiguation.

That disambiguation matters: --provider means something different depending on which subcommand carries it —

• on real-repo-run-plan, it drives only the one-shot plan call;
• on real-repo-run itself, it drives every iteration of the whole loop — the cloud model proposes every patch attempt, not just the plan.

The two flags are read independently with zero cross-check. Passing --provider to both calls is allowed and does something real (the plan text still reaches the prompt) but silently defeats the two-stage economics generate_plan()'s own docstring states as the whole point ("frontier reasoning is worth paying for once per task, not once per failed iteration") — with no warning from the CLI either way.

Adds:

1. A real-repo-run-plan example to AGENTIC_README.md's Commands block, alongside the existing plain real-repo-run example.
2. A "Two-stage: plan with cloud, implement locally" explainer in §9, paraphrasing generate_plan()'s own docstring (previously the only place this design rationale existed anywhere), plus the explicit --provider-on-both-calls warning above.
3. An updated CLAUDE.md module-table row naming real-repo-run-plan and pointing to the new explainer instead of just naming the shared --provider/--confirm-online vocabulary.

Invariant / Governance Impact: None. Pure documentation; no code, config, or graph topology touched. Does not claim any wiring exists that doesn't — the recipe is confirmed CLI-only as of this writing (the harness console's /api/agent/run has no --provider/--plan-file equivalent), and the doc says so rather than implying otherwise.

Types of changes

• Documentation Update

Scope note: Docs only.

Benefits / why

Makes a real, already-working capability actually discoverable and usable correctly. Before this, an operator would have to read generate_plan()'s Python docstring directly to learn this design exists at all, and had no warning against the one combination (--provider on both calls) that silently defeats its entire economic rationale.

Risks to monitor

None expected — additive documentation only, no behavior change. If a future change alters --provider's per-subcommand semantics or removes the orthogonality between --plan-file/--provider, this doc (and CLAUDE.md's pointer to it) will need a matching update.

Checklist

• Full sandbox validation: doc_sync.py (0 drift) + invariant-guard (33/0) both clean; not a Python change so no pytest run required.
• No new external network dependencies or online LLM assumptions introduced.
• Commit messages follow the title prefix convention above.

---

Generated by Claude Code