AI: propose dedicated documentation hosting section for Vale spec

[notactuallytreyanastasio]

Summary

This PR is entirely AI-authored. The spec section, commit message, decision graph analysis, and this PR description were all written by Claude (Opus 4.6). No human-written code or prose is included in this diff.

• Adds a new "Dedicated documentation hosting" section to the Vale specification, proposing a separate subdomain docs service (analogous to hexdocs.pm for Hex)
• Includes a 155-node decision graph capturing a full analysis of the Vale spec, a comparison with hex.pm, supply chain security learnings, and the docs hosting design process

What the new spec section covers

Why a separate service: Documentation hosting has fundamentally different operational characteristics than the registry -- read-heavy, rarely changes, benefits from CDN. Hex.pm learned this and split hexdocs.pm out. Vale should do the same.

Publication pipeline: 6-step async process triggered on version publish:

1. Extract locale-mapped docs from library sources
2. Extract structured Temper type data (signatures, doc comments, module structure)
3. Render per-backend HTML (Java dev sees Java types, Python dev sees Python types)
4. Package into documentation archive
5. Store in object storage keyed by library name + version
6. Notify docs service via message queue (non-blocking)

URL structure:

• docs.vale.example/[libraryname] -- latest non-prerelease
• docs.vale.example/[libraryname]/[semver] -- specific version
• docs.vale.example/[libraryname]/[semver]/b/[backendid] -- backend-specific docs

Private docs auth: Redirect-based auth dance with single-use short-lived tokens and encrypted session cookies (Secure, HttpOnly, SameSite=Lax). More complex than integrated routes but enables independent CDN scaling.

Search: Locale-aware full-text search across all visible documentation. Separate indices per visibility group for private docs. Cross-library search for discoverability.

Temper-specific features:

• Per-backend API docs (unique to multi-target languages -- no other registry does this)
• Literate .temper.md rendering (prose + code as documentation)
• Optional sandboxed JS playgrounds (speculative, gated on security review)

Context: decision graph analysis

This PR also includes a decision graph (viewable via deciduous serve) with 155 nodes analyzing:

• Full repository structure and spec layout
• Entity/type system analysis (Guarded<T>, Ken<T>, Pii<T>, Delta types)
• URL architecture and CDN caching strategy
• Access control and security model
• All 5 workflows
• Database and storage architecture
• Feature-by-feature comparison with hex.pm
• 12 supply chain security learnings from hex.pm
• 28 AI-generated observations (strengths, gaps, risks, suggestions)

Alternatives considered

Approach	Verdict
Integrated routes (/l/[name]/docs/...)	Simpler access control but docs traffic hits main app
Static site generation (docs.rs model)	Great for public, awkward for private docs auth
Separate subdomain (hexdocs model)	Chosen -- independent scaling, CDN-friendly, proven pattern

Test plan

• Review spec section for consistency with existing Vale spec voice and conventions
• Verify internal cross-references (#library-documentation, #libraryprofile) resolve correctly in mkdocs
• Review whether the auth dance for private docs is compatible with Vale's existing session model
• Consider whether the publication pipeline steps should be normative or informative

🤖 Generated with Claude Code