docs: refine GitBook product docs — clearer user path

[Lythaeon]

Description

Refine the GitBook docs so the user-facing path reads like product documentation instead of repository documentation.

This pass adds missing product-level pages, improves reader tone and consistency across the onboarding flow, introduces a Mermaid system overview, and corrects the comparison material so it stays neutral and technically accurate.

Changes

Detailed list of what changed:

• docs/gitbook/use-sof/why-sof-exists.md: adds a product-level explanation of why SOF exists and what problem it solves
• docs/gitbook/use-sof/sof-compared.md: adds a neutral comparison page covering RPC-first apps, managed stream/Geyser providers, self-operated validator+Geyser, and SOF
• docs/gitbook/architecture/system-overview.md: adds a diagram-first architecture page using Mermaid
• docs/gitbook/_layouts/website/page.html: adds Mermaid rendering support for GitBook pages
• docs/gitbook/styles/website.css: styles Mermaid output and improves sidebar readability with larger navigation text
• docs/gitbook/README.md, docs/gitbook/SUMMARY.md, docs/gitbook/use-sof/README.md, docs/gitbook/architecture/README.md: rewires entry points so the new product-level pages are discoverable early
• docs/gitbook/getting-started/*, docs/gitbook/crates/*, docs/gitbook/operations/*: rewrites user-facing wording to remove maintainer/meta-doc phrasing and make the path read as product guidance
• No runtime, architecture, or infrastructure code paths changed

For slice-related changes, include:

• Affected slices: docs only (docs/gitbook)
• Cross-slice communication changes (if any) and why: none
• Migration requirements (if any): none

Motivation

Business motivation:

• Improve the docs for external users evaluating SOF as a product rather than as a repository
• Reduce the gap between understanding SOF conceptually and understanding when and why to choose it

Technical motivation:

• The docs still had inconsistent voice, several repository/meta-doc phrases, and a comparison page that was not neutral enough
• The docs were missing a short system overview diagram and a direct explanation of why SOF exists in the first place

Alternative approaches considered:

• Keep iterating only on the existing getting-started pages without adding new product-level pages
• Add more low-level technical detail first instead of improving the user-facing shape of the docs
• Both were weaker than tightening the overall user path and adding the missing product-level material

Scope and impact

• Affected slices: docs/gitbook
• Data/API changes: none
• Backward compatibility: additive docs-only change
• Performance impact: none
• Security impact: none

Testing

• Unit tests
• Integration tests
• Manual verification
• Performance checks (if applicable)
• Security checks (if applicable)

Commands/results:

cd docs/gitbook && npm run build

Build completed successfully.

Related issues and documentation

• Fixes:
• Related:
• Architecture docs: docs/architecture/README.md
• Relevant ARD/ADR:
• Operations/runbook updates: docs/gitbook/operations/README.md, docs/gitbook/operations/relay-repair-and-traffic.md, docs/gitbook/operations/knob-registry.md

Reviewer checklist

• Code follows project standards and architecture constraints
• Slice boundaries are respected (docs/architecture/ard/0003-slice-dependency-contracts.md)
• Tests added/updated and passing
• Documentation updated (README/docs/operations as needed)
• No undocumented breaking change
• Performance trade-offs documented where relevant
• Security considerations addressed where relevant

Additional notes

This pass intentionally stays in the docs/product layer. It does not add new runtime capabilities; it improves how the current product surface is explained and navigated.