docs(site): refine SDD messaging and overhaul comparison page

[ryderstorm]

Why?

Improves the public-facing documentation site in two connected ways: a balanced, factual rewrite of the competitor comparison page, and a broader refresh of the docs experience so the workflow story is easier to follow from page to page. The updates also sharpen the message that SDD is a teachable, inspectable workflow - not just a productivity tool.

What Changed?

Comparison Page Overhaul (docs/comparison.html)

• Reframed the narrative: Changed the hero heading from "Why Not Other Structured Development Tools?" to "Comparing SDD to Other Structured Development Tools" - shifting from dismissive framing to factual comparison.
• Expanded the comparison table from 2 columns to 4: Each competitor (Kiro, SpecKit, Taskmaster) now has its own column with specific, sourced assessments instead of being grouped into a single "others" bucket.
• Added hyperlinks to competitor docs: Setup, installation, and workflow claims now link directly to official competitor documentation so readers can verify claims themselves.
• Replaced blanket red/green ratings with nuanced assessments: Uses a mix of green/yellow/red indicators with explanatory text instead of binary pass/fail judgments.
• Added transparency as a comparison dimension: New row highlights SDD's distinguishing trait - workflow logic is in readable markdown, not hidden behind product behavior.
• Rewrote the setup and conclusion sections: Renamed "Getting Started" to "Repo-Native Setup" and reframed "The Bottom Line" around adoption cost, operating model fit, and teachability.
• Added a next-step CTA: The page now routes readers into the developer-experience and FAQ content instead of ending with a simple back-link.

Docs Messaging and Layout Refresh (docs/index.html, docs/developer-experience.html, docs/common-questions.html, docs/reference-materials.html, docs/video-overview.html)

• "Teachable workflow" theme: Added language across the site emphasizing that SDD exposes its method in readable prompts and artifacts, so engineers learn effective AI collaboration patterns rather than depending on a product to manage them.
• Homepage refresh (docs/index.html): Updated hero copy, strengthened the four-step explanation, clarified the cspell example references, emphasized that Steps 1 and 2 are the highest-leverage part of the workflow, added a new spec lifecycle section explaining where SDD fits in the broader delivery process, improved audit-trail framing, redesigned the directory-structure section, and added a next-step CTA that moves readers deeper into the site.
• Developer experience page: Added visibility/teachability language, linked the cspell case study more clearly, introduced new supporting callouts such as "Teachable AI Collaboration" and "Visible Working Method," and added a next-step CTA.
• Common questions page: Expanded messaging around visible workflow logic, clarified the cspell example links, strengthened the shift-left argument for upfront planning, added a new FAQ on spec/task/proof lifecycle and PR feedback types, refined the technical background/non-goals presentation, and added a next-step CTA toward the walkthrough and reference materials.
• Reference materials page: Reframed artifacts as both evidence and teaching material, clarified that the preserved cspell run is illustrative rather than a required retention model, balanced the card grids, and added a next-step CTA toward quickstart and the walkthrough.
• Video overview page: Expanded the hero copy so the video is framed as both an overview of the flow and an explanation of the reasoning patterns SDD makes visible.

Shared Docs UI Refinements (docs/assets/css/styles.css)

• Added reusable next-step CTA styles used across multiple pages.
• Refined the comparison table styling, including header treatment, row striping, spacing, and link presentation.
• Added page-specific layout improvements for the homepage directory structure, developer-experience cards/sections, common-questions non-goals and technical background blocks, and reference-materials grid balance.
• Added a distinct background treatment for the homepage's From Reactive Art to Predictable Engineering section so it stays visually separated after the new lifecycle section was introduced.
• Added several hover, spacing, and responsive layout improvements to make the docs pages feel more intentional and easier to scan.

Notes

• Ordering: Independent, no merge dependency on other split PRs
• Process: Split from feat/add-pre-commit-for-cspell using two-phase branch surgery; 5 WIP commits squashed into clean history
• Companion PR: ci: add cspell spell-check for public documentation #48 (cspell CI tooling setup)

[gdsmith1]

LGTM!

Much more approachable reading experience without sacrificing content, looks great.