[P2-32] Make public documentation complete, accurate, and executable

[phranck]

Problem

Documentation contradicts current code and contains examples that do not compile or run:

• README/CONTRIBUTING/DocC promise pure Swift/no C dependencies while Package.swift contains CSTBImage.
• Multiple examples use nonexistent .foregroundColor; LazyStack docs use nonexistent ScrollView.
• Getting Started states an outdated deployment target.
• The documented composite renderOnce example crashes with missing StateStorage.
• AppStorage, localization, architecture, test-count, lint-limit, and dependency claims drift from implementation.
• Fresh symbol graphs show 335 public source-located symbols without documentation comments, only 92.96% comment presence; comment presence does not guarantee useful docs.
• DocC reports malformed links in Localization.md:501-503 and the catalog is treated as an unhandled SwiftPM resource.

Proposed solution

• Rewrite README, DocC, CONTRIBUTING, and architecture pages against the final public contracts and current package manifest.
• Compile every public code sample and run smoke tests for examples with runtime behavior.
• Document each public type/member with purpose, parameters, returns, state/lifecycle behavior, terminal adaptation, cross-platform notes, and a useful example where appropriate.
• Link compatibility-manifest classifications and explain intentional exclusions/Swift-6.0 compiler exceptions.
• Generate test/badge/version/dependency facts from one authoritative source.

Acceptance criteria

• Every fenced Swift example compiles; runtime examples produce/assert their documented result.
• DocC builds all public products with zero warnings and no unhandled catalog.
• Intended public symbols have complete, reviewed developer documentation, not placeholder comments.
• README, generated projects, Package.swift, and architecture docs agree on versions, platforms, dependencies, and commands.
• No documentation mentions an API before it is implemented, except clearly marked roadmap material.
• macOS/Linux SDK gates remain warning-free.

Dependencies

Documentation updates should accompany every implementation issue. Final closure depends on the API migrations, pure Swift decoder #16, generator #30, and compatibility manifest #7.

Parallelization

Page-by-page corrections can proceed with their owning implementation packages. Final API audit and executable example sweep happen after interfaces stabilize.

Commit structure

• Split this issue into small, thematic, independently revertible commits wherever the work can remain coherent.
• Every commit must build and keep its applicable tests/gates green. Do not commit an intentionally failing regression test; use local/known-issue characterization or land the test with the smallest fix.
• Keep characterization/fixtures, mechanical renames or moves, semantic changes, and documentation/migration updates separate when each step remains green.
• The issue boundary is not a commit boundary; multiple commits are expected for independently reversible changes.