Docs website IA restructuring (Option A): real /docs hub, dissolve guides/, dedupe FAQ/packaging, extend staleness gate

[rucka]

Story Statement

As a Pair docs reader (first-run user, adopting team, contributor)
I want the documentation website restructured per the IA assessment (Option A — targeted consolidation): a real hub at /docs, resolvable section URLs, the guides/ grab-bag dissolved into the sections its pages belong to, duplicated FAQ/packaging content merged, and the docs-staleness gate extended
So that every audience journey reaches its content in ≤2 clicks, duplicated pages stop drifting apart, and stale skill counts fail CI instead of shipping

Where: apps/website docs site (content/docs/**, next.config.mjs, scripts/docs-staleness-check.js, e2e/docs.e2e.test.ts)

Epic Context

Parent Epic: None — standalone documentation story (source: IA assessment .pair/adoption/decision-log/2026-07-12-docs-website-ia-restructuring-assessment.md, branch docs/website-structure-assessment)
Status: Refined
Priority: P2 (Could-Have)

Status Workflow

• Refined: Story is detailed, estimated, and ready for development
• In Progress: Story is actively being developed
• Done: Story delivered and accepted

Acceptance Criteria

Functional Requirements

Given-When-Then Format:

1. Given a reader landing on /docs (the landing page's docs CTA target)
   When the page renders
   Then it is a real hub — cards/links to the 4 journeys (getting-started, tutorials, customization, reference) and top tasks — not the current 15-line dead end (F1).

2. Given any top-level docs section (concepts/, reference/)
   When its direct URL is visited
   Then it resolves to an index page (no Fumadocs 404), and the 8 internal links currently pointing at index-less section URLs (/docs/concepts ×3, /docs/guides ×4, /docs/reference ×1 — all from tutorials/*.mdx) resolve (F2/F11).

3. Given a docs page stating the number of skills
   When the docs-staleness gate runs in CI
   Then every count matches the real catalog (35 today — currently 30/32/34 hardcoded in 6 places) because the gate's skill-count check scans all of content/docs/**/*.mdx, not just reference/skills-catalog.mdx (F5).

4. Given a reader with an install/setup problem
   When they look for help
   Then there is exactly one troubleshooting page (support/troubleshooting.mdx, merge of support/faq.mdx + guides/troubleshooting.mdx, conflicting fixes reconciled) and the old URLs redirect to it (F4).

5. Given the guides/ section
   When the restructure lands
   Then the section no longer exists: 4 pages moved (adopter-checklist→getting-started/checklist, cli-workflows→reference/cli/workflows, install-from-url→customization/install-from-url, update-link→reference/cli/update-link), 2 merged (customize-kb→customization/team.mdx as "Quick recipe" section; packaging→customization/organization.mdx, deduped keeping the layout-modes detail), root meta.json drops guides and promotes tutorials next to getting-started (13→12 nav entries) (F3/F7/F8/F13).

6. Given the sidebar
   When scanned
   Then no duplicate titles: quickstart variants retitled "Quickstart: Solo/Team/Organization" (vs. tutorial "Team Setup") and the developer-journey sidebar label and index title are unified (F6/F10).

7. Given any URL changed by this story
   When the old URL is visited
   Then a permanent redirect serves the new location, per the redirect table below (a redirects() block added to next.config.mjs — none exists today).

8. Given the full change set
   When CI runs
   Then quality gates (incl. extended docs-staleness), the docs e2e suite (sidebar-title assertions updated for the retitles), and link checks are green; llms.txt/llms-full.txt regenerate from the source loader (no manual action).

Business Rules

• Frozen paths (docs-staleness gate anchors): reference/skills-catalog.mdx and reference/cli/commands.mdx must NOT move.
• Nothing is deleted outright: 7 moves/merges, 3 new/rewritten pages, 60 keeps — every current page accounted for; every changed URL gets a permanent redirect.
• Untouched (healthy): integrations/, pm-tools/, migrations/, contributing/, tutorials/ (content), developer-journey/ (content), the two-group sidebar split.
• Landing-page links (/docs, /docs/customization/team, /docs/customization/organization) keep working unchanged.

Edge Cases and Error Handling

• Inbound links to moved pages: repo-wide grep for /docs/guides and /docs/support/faq (≈15 + 9 inbound links) — all updated to the new targets; redirects are a safety net for external links only.
• Merge conflicts between duplicated pages (faq vs. troubleshooting recommend different fixes, e.g. npm-permissions vs. nvm): reconcile on merge — keep one recommended fix, note the alternative.
• concepts/llms-txt.mdx orphan: add inbound links from concepts/index.mdx (new) and reference/kb-structure.mdx (F12).

Redirect table (permanent, next.config.mjs)

From	To
/docs/guides/adopter-checklist	/docs/getting-started/checklist
/docs/guides/cli-workflows	/docs/reference/cli/workflows
/docs/guides/customize-kb	/docs/customization/team
/docs/guides/install-from-url	/docs/customization/install-from-url
/docs/guides/packaging	/docs/customization/organization
/docs/guides/troubleshooting	/docs/support/troubleshooting
/docs/guides/update-link	/docs/reference/cli/update-link
/docs/support/faq	/docs/support/troubleshooting
/docs/guides	/docs

Definition of Done Checklist

Development Completion

• All acceptance criteria implemented and verified
• Delivered on a single PR per story (tasks are commits/checkboxes within it)
• Extended staleness gate proven: a wrong skill count in any docs page fails CI
• e2e docs suite updated (title assertions) and green
• Code review completed and approved

Quality Assurance

• Every redirect verified (old URL → new URL)
• Repo-wide grep confirms zero remaining /docs/guides or /docs/support/faq references
• llms.txt regenerated and consistent with the new tree

Story Sizing and Sprint Readiness

Refined Story Points

Final Story Points: 3 (M)
Confidence Level: High
Sizing Justification: ~2 days total across 3 mechanical, independently shippable batches; full page-by-page mapping, redirect table and link audit already produced by the assessment — no discovery left.

Sprint Capacity Validation

Sprint Fit Assessment: fits (3 small PRs).
Development Time Estimate: ~2 days (batch 1 ≈0.5d, batch 2 ≈0.5d, batch 3 ≈1d).
Total Effort Assessment: Fits: Yes.

Story Splitting Recommendations

Batches are the natural split; batch 1 (hygiene, no URL changes) is a strict subset of the plan and worth shipping even if batches 2–3 are deferred.

Dependencies and Coordination

Story Dependencies

Prerequisite Stories: none.
Dependent Stories: none.
Shared Components: apps/website/content/docs/**; touches getting-started/index.mdx, developer-journey/*, reference/kb-structure.mdx, reference/guidelines-catalog.mdx (skill counts) — no overlap with open PRs (#310 touches only reference/skills-catalog.mdx, frozen here).

Validation and Testing Strategy

Acceptance Testing Approach

Testing Methods: extended docs-staleness gate (negative test: seed a wrong count, expect CI failure); docs e2e suite; link check; manual redirect spot-check on preview deploy.
Test Data Requirements: none (real content tree).

Notes and Additional Context

Refinement Session Insights: derived from the IA assessment (69 pages, 12 sections + root, findings F1–F14, three options weighed). Option A chosen: removes every Major finding while changing only 7 URLs; Option B (hygiene-only) = batch 1, Option C (full Diátaxis re-org, 69-URL churn) rejected — current sections already map ~1:1 onto Diátaxis except guides/.
Out of scope (deferred, from batch 4): splitting reference/skill-management.mdx into explanation vs. reference; renaming support/general-faq.mdx → faq.mdx (F9 accepted as cosmetic).
Documentation Links: .pair/adoption/decision-log/2026-07-12-docs-website-ia-restructuring-assessment.md (full inventory, findings table, 69-page mapping; moved from apps/website/docs-structure-assessment.md during PR review — it is an analysis/decision artifact, not published site content).

Technical Analysis

Implementation Approach

Technical Strategy: three independently shippable batches — (1) hygiene with zero URL changes, (2) support consolidation, (3) dissolve guides/. Fumadocs nav is folder-based via per-folder meta.json; a folder without index.mdx is sidebar-only (its URL 404s) — hence the new index pages. Redirects live in next.config.mjs redirects().
Key Components: content/docs/** + meta.json files; scripts/docs-staleness-check.js; next.config.mjs; e2e/docs.e2e.test.ts; lib/get-llm-text.ts (read-only — regenerates llms.txt automatically).
Integration Points: docs-staleness quality gate (CI); landing page CTAs (unchanged).

Technical Risks and Mitigation

Risk	Impact	Probability	Mitigation Strategy
Missed inbound link to a moved page	Low	Medium	Repo-wide grep /docs/guides + /docs/support/faq; redirects as safety net
FAQ/troubleshooting merge loses an answer	Medium	Low	Merge is additive: union of Q&As, reconcile conflicting fixes explicitly
Gate extension false positives (counts in prose)	Low	Medium	Scope regex to (\d+)\s+(?:pair\s+)?skills; allowlist if needed

Task Breakdown

Tasks are documented inline per the task-template. No separate task issues. Delivered on a single PR per story (tasks are commits/checkboxes within it).

Checklist

• T1 — Batch 1: hygiene (no URL changes)
• T2 — Batch 2: support consolidation (faq + troubleshooting merge)
• T3 — Batch 3: dissolve guides/

Dependency Graph

T1 ─► T2 ─► T3   (order recommended, not strict: T2/T3 independent of T1;
                  T3 after T2 avoids touching guides/troubleshooting twice)

AC Coverage

Task	AC1	AC2	AC3	AC4	AC5	AC6	AC7	AC8
T1	✓	✓	✓			✓		✓
T2				✓			✓	✓
T3		✓			✓		✓	✓

Detailed Tasks

T1 — Batch 1: hygiene (no URL changes)

Task Information — Priority: P2 · Est: 0.5d · Bounded Context: Code & Documentation Generation
Type: Documentation
Description: Rewrite /docs root as a real hub; add concepts/index.mdx + reference/index.mdx; fix the 8 broken section links in tutorials/*.mdx; fix the 6 stale skill counts (30/32/34→actual); extend docs-staleness-check.js to scan skill counts across all content/docs/**/*.mdx (optionally add a dead-internal-link check resolving ](/docs/...) against the source loader); retitle quickstart variants "Quickstart: Solo/Team/Organization"; unify developer-journey label/title; update e2e sidebar-title assertions; add inbound links to concepts/llms-txt.mdx.
Acceptance Criteria: AC1, AC2 (index pages + links), AC3, AC6; gates green (AC8). Zero URL changes.
Files to Modify: content/docs/index.mdx, content/docs/concepts/index.mdx (new), content/docs/reference/index.mdx (new), content/docs/tutorials/{index,first-project,existing-project,team-setup,enterprise-adoption}.mdx, content/docs/getting-started/{index,quickstart-solo,quickstart-team,quickstart-org}.mdx, content/docs/developer-journey/{index,execution}.mdx, content/docs/reference/{kb-structure,guidelines-catalog}.mdx, scripts/docs-staleness-check.js, e2e/docs.e2e.test.ts.
Testing: staleness gate negative test (wrong count fails); e2e green.

T2 — Batch 2: support consolidation

Task Information — Priority: P2 · Est: 0.5d · Bounded Context: Code & Documentation Generation
Type: Documentation
Description: Merge support/faq.mdx ("Installation FAQ", 361 lines) + guides/troubleshooting.mdx (236 lines) into new support/troubleshooting.mdx (union of Q&As, reconcile conflicting fixes); add redirects /docs/support/faq and /docs/guides/troubleshooting → /docs/support/troubleshooting (creates the redirects() block); update ~9 inbound links; refresh support/index.mdx quick links.
Acceptance Criteria: AC4, AC7 (its rows); gates green.
Files to Modify: content/docs/support/{index,troubleshooting}.mdx (new), delete support/faq.mdx + guides/troubleshooting.mdx, next.config.mjs, inbound-link pages per grep.
Testing: redirect check; grep zero /docs/support/faq.

T3 — Batch 3: dissolve guides/

Task Information — Priority: P2 · Est: 1d · Bounded Context: Code & Documentation Generation
Type: Documentation
Description: 4 moves (adopter-checklist→getting-started/checklist, cli-workflows→reference/cli/workflows, install-from-url→customization/install-from-url, update-link→reference/cli/update-link) + 2 content merges (customize-kb→customization/team.mdx "Quick recipe"; packaging→customization/organization.mdx, deduped, keep layout-modes detail); delete guides/meta.json; remaining redirects incl. /docs/guides→/docs; update ~15 inbound links; update root meta.json (drop guides, promote tutorials; new order: index, getting-started, tutorials, concepts, developer-journey, customization, integrations, pm-tools, ---, reference, migrations, support, contributing); update affected section meta.json files.
Acceptance Criteria: AC5, AC2 (guides URL gone), AC7 (its rows); gates green.
Files to Modify: all content/docs/guides/*, content/docs/{getting-started,customization,reference/cli,support}/…, root + section meta.json, next.config.mjs, inbound-link pages per grep.
Testing: full redirect table verified; grep zero /docs/guides; e2e + staleness green.