docs(mcp): add onboarding workflow guides

[Q00]

Summary

• Fixes docs: MCP use cases, best practices, and demo content for user onboarding #365 by adding MCP onboarding docs for upstream server configuration and external QA backend usage.
• Adds workflow examples for Research -> Deliverable and Design -> Code -> Verify.
• Links the new guides from the docs index.

Changes

• docs/guides/mcp-best-practices.md: server roles, safe config patterns, security, reliability, workflow mapping.
• docs/guides/qa-backends.md: external QA backend guidance, including OpenCron-style synthetic checks.
• docs/examples/workflows/: two concrete workflow examples with seed shapes and QA notes.

Tests

• git diff --cached --check

[ouroboros-agent]

Review — ouroboros-agent[bot]

Verdict: REQUEST_CHANGES

Reviewing commit 2146a7d for PR #466

Review record: ce46b9d4-5b13-48f4-b149-fcd6ceb5f831

Blocking Findings

| # | File:Line | Severity | Finding |
|### Recovery Notes
First recoverable review artifact generated from codex analysis log.

---|-----------|----------|---------|
| 1 | docs/examples/workflows/research-to-deliverable.md:38 | BLOCKING | The research workflow example never sets task_type: research. In Ouroboros, task_type defaults to "code" (docs/guides/seed-authoring.md, src/ouroboros/core/seed.py), so a user copying this seed would get code-oriented execution/evaluation instead of research behavior. That changes runtime behavior, not just documentation wording. |

Follow-up Findings

• docs/examples/workflows/design-code-verify.md:45 [warning] The Seed Shape snippet is not a valid seed as written: it omits the required ontology_schema and metadata sections. That contradicts the documented seed schema in docs/guides/seed-authoring.md and the actual Seed model, which requires both fields (src/ouroboros/core/seed.py, src/ouroboros/core/seed.py). Users copying this example for manual authoring will hit validation errors immediately.
• docs/examples/workflows/research-to-deliverable.md:37 [warning] This Seed Shape example has the same schema problem: it omits required ontology_schema and metadata, so the example cannot be used as an actual seed despite being presented as one. The mismatch is against both the seed-authoring guide (docs/guides/seed-authoring.md) and the runtime model (src/ouroboros/core/seed.py, src/ouroboros/core/seed.py).

Non-blocking Suggestions

None.

Design Notes

The new docs are directionally useful and consistent with the MCP config surface, but the workflow examples currently blur “illustrative snippet” and “valid seed.” For docs that present YAML under Seed Shape, the bar should be that the snippet is executable against the real schema.

---

Reviewed by ouroboros-agent[bot] via Codex deep analysis

[ouroboros-agent]

Review — ouroboros-agent[bot]

Verdict: APPROVE

Reviewing commit 65aa18e for PR #466

Review record: 4f1c0b91-c72c-473c-9ed0-c3330af0025f

Blocking Findings

No in-scope blocking findings remained after policy filtering.

Non-blocking Suggestions

None.

Design Notes

The changes are documentation-only and stay aligned with the existing MCP configuration surface (mcp_servers.yaml, connection.*, tool_prefix). The new guides/examples are coherent with the current bridge/config docs and do not appear to introduce misleading or unsupported instructions.

Recovery Notes

First recoverable review artifact generated from codex analysis log.

---

Reviewed by ouroboros-agent[bot] via Codex deep analysis