Docs: add @readme comments for primitives and foundation APIs

[artiphishle]

Goal

Add Paradox @readme doc comments to the Surface exports that should appear in the generated README.

Scope

Prioritize foundation-level public surface:

• primitives
• layout primitives
• theme/provider APIs
• responsive helpers
• icon/render foundation exports
• metadata/registry exports when useful

Do not over-document raw internal helper types for now.

Acceptance criteria

• Important Surface primitives and foundation APIs have useful @readme comments.
• Generated README clearly positions Surface as the render foundation below ZORA.
• bun run docs updates generated docs cleanly.
• bun run build, bun run lint:fix, and bun run test pass.