Documentation Architecture
The live VitePress site and generated kartuli-llm.txt are discovery surfaces for humans and agents. Source lives in docs/. Organize by stable capabilities first; provider changes should not force capability pages to move.
| Section | Canonical responsibility |
|---|---|
| Apps | Independently deployed user/operator surfaces; app product, architecture and app-specific operations |
| Packages | Imported workspace libraries: responsibility, exports, consumers, dependency boundaries |
| Tools | Repository-maintained executables for building, testing, inspecting, documenting or operating |
| Design System | Shared visual/interaction contract; tokens, typography, theming, components and patterns |
| Engineering | Monorepo architecture, shared code, technologies and libraries |
| Quality | Testing, accessibility, review, static analysis, performance and web quality |
| Platform | Environments, CI, deployment, hosting, cache, observability, notifications and dependency operations |
| Security | Trust boundaries, authentication, authorization, secrets and vulnerability handling |
| Data & Privacy | Storage, identifiers, analytics policy, telemetry payloads, consent and retention |
| Services | External provider setup, account/project mapping, secrets by name and integration constraints |
| AI Development | Agent context hierarchy, instruction entry points and coding/validation workflow |
| Project | Documentation rules, contributing, Git/issue/project workflow, ownership and decisions |
An app is deployed because learners/operators use it. A package is imported by workspace code. A tool is executed to help develop or operate Kartuli. A hosted docs site can still be a tool. The Design System describes the contract; package docs describe its implementation/export boundary.
One canonical owner
Choose one page per concept and link to it elsewhere. For example, Quality owns accessibility requirements, Storybook owns its implementation, Design System links to the requirements. Platform owns hosting/deployment/cache; Vercel owns provider mapping. Data & Privacy owns analytics taxonomy; a future PostHog page would own its setup. Security owns authentication; a future Supabase page would not replace that architecture.
Keep app-specific product behavior in Apps. Git technical usage belongs in Engineering; branch/review conventions belong in Project. Source references are implementation evidence, not substitute copies of canonical prose.
Growth and maintenance
Each top-level area has an index.md hub. Add detailed pages when there is useful verified content, not merely a candidate heading. Library entries graduate to dedicated pages when they establish architectural boundaries or recurring Kartuli conventions. Future providers stay in the service catalog until adopted.
Every implementation PR that changes documented behavior updates its canonical page and affected links in the same PR, or explicitly explains why documentation is unaffected. Keep bootstrap agent files concise. Preserve URLs when possible; when moving a page, update all links and account for published links before removing it.
See Writing Guide for metadata/status rules and Web Docs Client for generation/validation.
Coverage inventory
The command reference explains script discovery and common workflows and the dependency inventory explains how to audit manifests and catalogs. Dedicated guides cover architectural technologies/libraries, quality layers, design contracts and current provider integrations.
The documentation coverage map connects workspaces, configuration, workflows and implementation patterns to those canonical owners and keeps known gaps visible. Use it during an audit; do not interpret a checked mapping as proof that a provider or incomplete capability works.
Before adding an app, tool or provider, update the relevant inventory and canonical guide in the same change. Depth means verified operating knowledge: configuration, common changes, expected outputs, failure diagnosis and known limits. It does not require fabricating missing provider settings or treating planned product behavior as shipped.