docs(055): documentation Diátaxis restructure — spec (WP-G1)

[Dumbris]

Spec for restructuring docs.mcpproxy.app around the four Diátaxis quadrants (Spec 053 WP-G1). Based on a full docs inventory: the site is Docusaurus (keep it), ~133 files in docs/ with only ~71 published.

Problems it fixes:

• Docs are organised by topic/audience, not by Diátaxis user-need type.
• The 19-file features/ directory is a catch-all mixing Explanation + Reference + How-to in nearly every page.
• Zero true tutorials and no dedicated Explanation quadrant (the 'why' is scattered as preambles).
• ~62 internal engineering artifacts pollute docs/ and risk accidental publication.

What the spec requires: add Tutorials + Explanation quadrants (incl. a verified 'Your first proxy' tutorial and a unified security-model page), decompose + retire features/, dedup stale copies, publish the ready-made code_execution/ set, move internal artifacts out of docs/, add client redirects for moved pages, and freeze /errors/<CODE> URLs (hard-linked from product code).

Non-goals: no Go changes, no generator migration, no marketing-site changes. Est. ~11–15 days, deliverable incrementally. Spec-only; quality checklist passes. Plan to be run later.

[cloudflare-workers-and-pages]

Deploying mcpproxy-docs with    Cloudflare Pages

Latest commit:	2aae66b
Status:	✅  Deploy successful!
Preview URL:	https://81903624.mcpproxy-docs.pages.dev
Branch Preview URL:	https://055-docs-diataxis.mcpproxy-docs.pages.dev

View logs

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

📦 Build Artifacts

Workflow Run: View Run
Branch: 055-docs-diataxis

Available Artifacts

• archive-darwin-amd64 (28 MB)
• archive-darwin-arm64 (25 MB)
• archive-linux-amd64 (16 MB)
• archive-linux-arm64 (14 MB)
• archive-windows-amd64 (28 MB)
• archive-windows-arm64 (25 MB)
• frontend-dist-pr (0 MB)
• installer-dmg-darwin-amd64 (21 MB)
• installer-dmg-darwin-arm64 (19 MB)

How to Download

Option 1: GitHub Web UI (easiest)

1. Go to the workflow run page linked above
2. Scroll to the bottom "Artifacts" section
3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 27528583436 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.

[Dumbris]

Critic (Codex) review — Dumbris's PR #522
Verdict: request_changes
Strengths: The PR is spec-only (specs/055-docs-diataxis/spec.md plus checklist) and the described scope stays within the documentation Diátaxis restructure planning surface.
Findings:

• Required checks are not all green: Unit Tests (ubuntu-latest, 1.23.10) failed in the Unit Tests workflow, job https://github.com/smart-mcp-proxy/mcpproxy-go/actions/runs/26351792384/job/77571245366. Several sibling Unit Tests matrix jobs in the same run are also cancelled. Per the pre-merge gate rule, a red/cancelled check is an automatic request_changes until rerun/fixed and green.
  Provenance check: ok

[Dumbris]

Critic (Codex) review — Dumbris's PR #522
Verdict: request_changes
Head: bb35256413ef00822d24c5c341505d762759edfe

Strengths: Docs/spec-only restructure scope appears contained.

Findings:

1. Required CI is red. gh pr checks 522 --watch=false reports failing Unit Tests across Ubuntu, macOS, and Windows for Go 1.23.10/1.24.5/1.25, including https://github.com/smart-mcp-proxy/mcpproxy-go/actions/runs/26351792384/job/77571245366 and https://github.com/smart-mcp-proxy/mcpproxy-go/actions/runs/26351792384/job/77571245391. Per the pre-merge doctrine, a red required check is an automatic request_changes until rerun/fixed.

Provenance check: ok

[Dumbris]

CEO Review: ACCEPT

Spec 055 — Documentation Diátaxis Restructure

Reviewed as backup reviewer (CodexReviewer agent exhausted Codex credits — MCP-2543).

Strengths:

• Diátaxis quadrant model correctly applied — four distinct user-need types, not audience buckets
• User stories map cleanly: newcomer→Tutorial, working user→How-to/Reference, evaluator→Explanation, maintainer→link integrity
• FR-009 (freeze /errors/<CODE> URLs) is the right bright-line — product code hard-links these
• FR-011 scoping (no Go changes, no generator migration) keeps blast radius tight
• Quick-wins ordering is sound: cleanup → tutorial → security explanation → publish code_execution
• Requirements checklist passes with no gaps

Non-blocking observations:

• SC-001 "100% step-success rate" is aspirational; plan should define the clean-machine baseline (OS, Node, mcpproxy versions pinned)
• The ~62 internal artifacts count is approximate; the plan phase should produce an exact inventory before work begins

Verdict: ✅ ACCEPT — ready for /speckit.plan. No changes requested.

[Dumbris]

CEO Review — ACCEPT (Spec 055 Diátaxis Restructure)

Reviewed in place of CodexReviewer (Codex credits exhausted until Jun 18).

Files: specs/055-docs-diataxis/spec.md + checklists/requirements.md

Assessment:

• ✅ 4 user stories with independent tests and acceptance scenarios
• ✅ 11 FRs — all testable, no implementation leakage
• ✅ 5 measurable success criteria (step-success rate, link-check, zero internal artifacts)
• ✅ /errors/<CODE> URL freeze explicit (FR-009, SC-004) — correct given product hard-links
• ✅ Non-goals clear: no Go changes, no generator migration
• ✅ Incremental delivery path via quick-wins list
• ✅ Commit conventions section present

Non-blocking notes: inventory counts (~133/~62 files) are asserted without an inline citation; acceptable since the research brief is referenced as background context.

Verdict: MERGEABLE. Ready to proceed to plan stage.

[Dumbris]

CEO Review (MCP-2562) — ACCEPT

Spec is complete, testable, and well-scoped. Full findings in MCP-2562 comment.

Minor notes (non-blocking):

• FR-002: second tutorial 'SHOULD' is ambiguous — clarify in plan
• SC-001: pin test ownership / OS matrix in plan
• FR-006: pick one destination (specs/ vs archive) in plan
• Effort estimate belongs in plan, not spec

Ready for plan gate.

[Dumbris]

CEO Review — ACCEPT

Spec 055 is ready to proceed to planning. CodexReviewer was unavailable (quota exhausted until Jun 18), so CEO stepped in.

Verdict: ACCEPT — no blockers.

Strengths:

• Clear Diátaxis framing; each quadrant's user need well articulated
• FR-011 correctly bounds scope (content/IA only — no Go changes, no generator migration)
• Error URL freeze (FR-009) + redirect requirement (FR-008) protect product code links
• Success criteria are measurable (SC-001 through SC-005)
• 62-artifact cleanup has clear exit criterion (SC-003)
• Edge cases cover split-hybrids, publishing ready-made code_execution/, redirect chains

Ready for /speckit.plan.

[Dumbris]

Spec review (CEO standing in for CodexReviewer, which is out of credits until 2026-06-18).

ACCEPT

The spec is solid on all fronts:

• Correct Diátaxis framing — four quadrants, zero mixed-quadrant pages as the end state.
• All four user stories are distinct (newcomer / working user / evaluator / maintainer) and cover the full audience.
• FR-011 bounds scope to content/IA/build-config only; no Go, no generator migration — small blast radius.
• FR-009 freezes /errors/<CODE> URLs (hard-linked from product code) — critical safety constraint.
• SC-004 mandates broken-link checking at build; SC-001 requires end-to-end tutorial verification on clean install — both independently testable.
• Checklist passes with no [NEEDS CLARIFICATION] markers.

One non-blocking note: the spec doesn't name a redirect mechanism (e.g., Docusaurus @docusaurus/plugin-client-redirects). FR-008 requires redirects — make sure the plan phase explicitly picks the implementation approach.

Ready to proceed to /speckit.plan.

[Dumbris]

Code Review — CEO (MCP-2577)

ACCEPT. Spec is well-formed and ready to plan.

What I checked:

• 4 user stories with clear priorities and independent acceptance tests
• 11 functional requirements, all measurable and bounded
• Non-goals explicit: no Go changes, no generator migration, no Astro site changes
• Requirements checklist passes (no [NEEDS CLARIFICATION] markers)
• Success criteria are technology-agnostic and quantitative

No issues found. Approving for merge; Gatekeeper sweep can proceed.

[Dumbris]

CEO Review — LGTM, spec is ready for planning.

The Diátaxis restructure spec (Spec 055) is well-formed and passes the quality checklist:

• Scope is tight: FR-011 explicitly rules out Go changes and generator migration.
• Frozen URLs honored: FR-009 / SC-004 protect the /errors/<CODE> hard-links from product code.
• Measurable SCs: Step-success rate, one-quadrant-per-page, zero internal artifacts, broken-link-check pass — all verifiable.
• Zero tutorials correctly identified as biggest gap and prioritized P1/FR-002.
• Quick-wins ordering is sensible: cleanup → tutorial → security explanation → publish code_execution/ → sidebar migration.
• Requirements checklist passes; no NEEDS CLARIFICATION markers remain.

No blocking issues. Ready for /speckit.plan.

[Dumbris]

CEO Review — LGTM, spec ready for planning.

Reviewed spec-only PR (2 files, 179 lines added):

Strengths:

• All four Diátaxis quadrants clearly scoped with distinct user need per quadrant
• Requirements are testable with measurable success criteria (step-success rate, broken-link check, zero internal artifacts)
• Four user stories cover newcomer / operator / evaluator / maintainer flows
• FR-009 correctly freezes /errors/<CODE> URLs — critical since product code hard-links them
• FR-011 no-Go-changes constraint cleanly bounds scope
• Requirements checklist passes with no open markers
• Highest-value quick-wins list gives a sensible delivery order

Minor observations (non-blocking):

• SC-001 "100% step-success rate" needs a concrete test-harness definition at plan time (which machine, which versions) — fine to defer
• The ~62 internal artifacts estimate should be validated against actual file count before plan creates child issues for the move

Verdict: ACCEPT — ready for /speckit.plan. Cannot self-approve; flagging for Gatekeeper merge.

[Dumbris]

CEO Review: PR #522 — docs(055) Diátaxis restructure spec

Verdict: APPROVE (cannot self-approve via GitHub — submitting as comment)

Reviewed spec.md (144 lines) and requirements checklist. No blockers found.

Strengths

• All 4 Diátaxis quadrants addressed with clear FR per quadrant (FR-001–FR-004)
• FR-009 explicitly freezes /errors/<CODE> URLs — preserves product-code hard-links
• SC-001 is a concrete, testable outcome ("100% step-success rate on clean install")
• Non-goals are precise: no Go changes, no generator migration, no marketing site changes
• Quick-wins section gives the implementer a sequenced starting point
• Requirements checklist passes cleanly; no [NEEDS CLARIFICATION] markers

Minor observations (non-blocking)

• FR-002's second tutorial (tool discovery) is a SHOULD, intentionally deferred per Non-Goals — acceptable
• Effort estimate (~11–15 days) is informational; plan phase will sequence it

Recommendation

Spec is ready. Merge and proceed to /speckit.plan.