chore(docs): Phase 2 — Restructure for clarity (Diátaxis cleanup)

[beonde]

Phase 2: Restructure for Clarity

Part of the docs audit remediation plan. Phase 1 (fix critical code drift) was merged in PR #26.

What this PR does

Structural cleanup following the Diátaxis documentation framework — concept pages should explain, not instruct. Tutorial content belongs in Getting Started, how-to content in How-To Guides.

Changes

Navigation (mkdocs.yml)

• Move Samples from top-level nav → under Getting Started
• Removes redundant nav entry

Landing page (docs/index.md)

• Restore navigation and TOC visibility (removed hide: navigation / hide: toc)
• Remove redundant "CapiscIO Stack" section (duplicates Overview page)
• Remove redundant "Quick Links" grid (duplicates top navigation)
• Keep: hero, task-oriented "What Do You Want to Do" grid, "Developers Love CapiscIO" code tabs

Getting Started (docs/getting-started/index.md)

• Remove competing "Choose Your Setup Path" card grid (duplicates the "Fastest Path" tabbed section above it)
• Single linear flow: install → one command → what you get → next steps

Concept pages — enforce explanation mode:

• identity/index.md: Remove tutorial duplication (setup path cards, "Using Your Identity" section) — add cross-reference to Getting Started
• trust/index.md: Remove "Developer Experience" section containing ghost APIs (badge_path param, guard.client(), @guard.protect — none exist on SimpleGuard)
• scoring.md: Replace verbose CLI/Python how-to sections and stale migration guide with compact cross-references to CLI and SDK reference pages
• validation.md: Remove non-existent "Conservative Mode" section (only progressive and strict modes exist in source code — verified in capiscio-core/pkg/scoring/engine.go)

Net effect

• 7 files changed, 6 insertions, 393 deletions
• Cleaner separation of tutorial/concept/reference/how-to content
• Landing page now participates in site navigation instead of being an island
• No new pages created — only removed redundant/incorrect content

Verification

• mkdocs build passes cleanly (no new warnings)
• All removed APIs verified against source code as non-existent or duplicated

[github-actions]

✅ Documentation Build Successful

The documentation build completed successfully and passed validation checks.

• ✅ Build completed without errors
• ✅ Critical files present (index.html, sitemap.xml, robots.txt)
• ✅ Link validation completed

This PR will deploy to dev-docs.capisc.io when merged to main.