init-generated guidance and project skills contradict MCP-first contract and emit stale tool calls

## Summary

Ruflo's current `ruflo init` and Codex init generators tell agents to use MCP tools, then direct routine MCP-capable operations back through raw `npx @claude-flow/cli...` Bash commands. This contradicts the active RuvNet Brain interface contract:

> Use Ruflo MCP tools first whenever the capability already has one. For a CLI-only gap, use `ruvnet_cli_help`, then `ruvnet_cli_run` with literal `argv`. Do not turn an MCP-capable operation back into a raw Bash string.

The same generated documents conflate source grounding with runtime capability discovery, present unregistered native subagents as a Ruflo-coordinated team, and emit stale/nonexistent MCP tool names and schemas.

This is not the duplicate-registration defect fixed in #2612, and it is narrower than the single-source divergence in #2638.

## Reproduction

Tested with published `ruflo@3.38.20`, then confirmed on `main` at `29f048fc3b556f857cf2b126d2a84c19d2daa0d0`.

1. Generate Claude instructions with `ruflo init`.
2. Generate Codex instructions with the Codex init path.
3. Compare both with the installed Ruflo MCP registry and the active Brain contract in [`plugin/skills/ruvnet-brain/SKILL.md`](https://github.com/stuinfla/ruvnet-brain/blob/cbca83bc7a72a8ee4552d50530e391694200b670/plugin/skills/ruvnet-brain/SKILL.md#L19-L27).

## Current contradictory output

### Claude Code generator

Source: [`claudemd-generator.ts`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/cli/src/init/claudemd-generator.ts)

- [`swarmConfig()`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/cli/src/init/claudemd-generator.ts#L119-L153) emits raw `npx ... swarm init`.
- [`memoryAndLearning()`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/cli/src/init/claudemd-generator.ts#L156-L195) emits raw memory/hook commands, then immediately lists their MCP equivalents.
- [`cliQuickRef()` / `setupAndBoundary()`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/cli/src/init/claudemd-generator.ts#L211-L240) repeat raw swarm/memory/hooks/security/performance operations and explicitly claim `CLI is the same via Bash`.
- [`securitySection()`, `performanceSection()`, and `hooksRef()`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/cli/src/init/claudemd-generator.ts#L254-L303) continue the same pattern.
- [`policyGovernedWorkflow()`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/cli/src/init/claudemd-generator.ts#L27-L68) does not distinguish source-grounded RuvNet claims (`search_ruvnet`, when installed) from local runtime availability/routing (`guidance_brain`).
- [`agentComms()`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/cli/src/init/claudemd-generator.ts#L71-L117) launches native Claude agents and labels the result coordinated without first registering a Ruflo swarm/agents. Native agents are valid executors; they are not automatically Ruflo-tracked.

Bootstrap operations such as installing Ruflo, initially registering MCP, `doctor --fix`, and an explicitly chosen daemon lifecycle are legitimate direct-shell exceptions.

### Codex generator

Source: [`agents-md.ts`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/codex/src/generators/agents-md.ts)

- The default template lists MCP tools, then sends memory, hooks, and swarm through raw CLI in [`Memory System` / `Quick Commands`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/codex/src/generators/agents-md.ts#L264-L341).
- The full template repeats raw hooks and workers in [`Hooks System` / `Background Workers`](https://github.com/ruvnet/ruflo/blob/29f048fc3b556f857cf2b126d2a84c19d2daa0d0/v3/%40claude-flow/codex/src/generators/agents-md.ts#L396-L499).
- It emits stale MCP examples: `task_orchestrate` is not exposed; `benchmark_run` should be `performance_benchmark`; and `agent_spawn({type,name})` does not match the live schema, which requires `agentType` and optionally accepts `agentId`.
- Enterprise output guesses raw flags for claims, stop-all, deployment/workflow, and restore operations rather than discovering a structured tool or using the managed CLI help/run bridge.

## Impact

- MCP uses the already-loaded, project-scoped server and validated schema.
- `npx ...@latest` resolves/fetches another package process and can select a different cache, dependency closure, cwd, driver, or version.
- In live memory workflows that can cross a writer/driver boundary and make a safely refused WAL access look like broken memory.
- Stale examples can silently call no real tool or simulate orchestration Ruflo never tracked.

## Related issues

- #1497 added global MCP discovery instructions.
- #1507 added a Codex MCP table and raw CLI quick commands.
- #1511 fixed stale Claude tool naming but not MCP-first interface selection.
- #2612 covers duplicate MCP registration only.
- #2638 covers structural divergence between generated CLAUDE.md and AGENTS.md.
- #2946, #2929, and #2968 show why ad-hoc npx execution is not equivalent to the running MCP plane.

No existing all-state title/body search found this exact interface-selection defect.

## Proposed implementation

### 1. One shared invocation-policy renderer

Both generators should consume one tested contract:

1. Use `search_ruvnet` for RuvNet source/capability claims when the Brain plugin is installed.
2. Use `guidance_brain` / `guidance_recommend` for local availability, health, and routing.
3. Use MCP first for an operation present in the live registry. Discover deferred tools (`ToolSearch` in Claude Code); never guess prefixes or schemas.
4. Register/coordinate through Ruflo MCP (`swarm_init`, `agent_spawn`, memory/hooks); execute through native Claude/Codex agents.
5. For a genuine CLI-only gap, use `ruvnet_cli_help`, then `ruvnet_cli_run` with literal `argv` when the managed bridge is installed. Otherwise report no proven interface instead of inventing flags.
6. Permit direct shell only for clearly labelled bootstrap/repair operations that cannot depend on a running MCP server.

### 2. Replace conflicting generated examples

- Replace raw swarm/memory/hooks/worker/security/performance examples with live MCP names.
- Correct or remove stale tool names and arguments.
- Do not describe native host agents as Ruflo-tracked until Ruflo records exist.
- Remove `CLI is the same via Bash`.
- Replace unconditional `3+ files => swarm` with the smallest-capable/dependency-risk decision already stated by the policy loop.
- Preserve the canonical `claude-flow` MCP server key required by #2206/#2612.

### 3. Validate prose against the live registry

Any static tool example must be tested against the MCP registry exported by the same build. Do not maintain a second guessed list inside Markdown templates.

### 4. Migrate existing files safely

`init --force` must not overwrite user-authored instructions. Migrate exact prior generated blocks only, preserve every other byte, and refuse ambiguous/edited blocks.

## Acceptance tests

Run across every Claude template (`minimal`, `standard`, `full`, `security`, `performance`, `solo`) and Codex template (`minimal`, `default`, `full`, `enterprise`):

1. No raw CLI example remains for an operation present in that build's MCP registry.
2. Bootstrap/repair shell remains labelled and does not create duplicate MCP.
3. Every named MCP tool exists and each example validates against its schema.
4. Source grounding is distinct from local runtime guidance.
5. Native workers execute; Ruflo MCP records coordination.
6. CLI-only examples use managed help then literal-argv run.
7. Custom instruction content survives bounded migration byte-for-byte.
8. Re-running generation/migration is idempotent.
9. Missing/renamed registry exports fail tests instead of blessing stale prose.

## Downstream mitigation

An exact-anchor reversible downstream patch is being prepared for the two installed generator files. It will patch only installed Ruflo generator bytes, apply atomically, preserve pristine backups, survive package refresh through the existing monitor, and retire only after an all-template behavioral proof. It will not patch Brain, MCP runtime, hooks, updater state, or any memory database.

Read v3/@claude-flow/cli/src/init/claudemd-generator.ts and v3/@claude-flow/codex/src/generators/agents-md.ts, then inspect the live MCP registry and existing generator tests. Validate every Claude and Codex template against the stated acceptance tests, including schema-checked tools, labelled shell exceptions, safe idempotent migration, and preservation of custom instruction content.

Written by the indexing model from the issue text.