# V1 Documentation Guide This guide is the curated front door to the complete V1 documentation set. It explains which artifact answers which question, how release and implementation status are represented, and where to go from product intent to architecture, code, tests, operations, and evidence without treating a plan as shipped truth. V1 is the Oshun platform release behind the consumer product **Lilith**. The V1 line covers member experiences, authoring and workbenches, the Eve builder and operator assistant, Telegram and other channels, platform substrates, safety, data, operations, and release evidence. The V3 Lilith handbook is linked where the name refers to the embodied metaverse rather than the V1 member persona. ## The documentation model ```mermaid mindmap root((V1 documentation)) Product intent Product promise Features Release scope Brand and naming System design Architecture Domains and substrates Data and security Integrations Cross-cutting handbooks Eve Workbenches Yemaya Study Workspace Telegram Lilith relationship Delivery truth Backlog Dependencies Audits and decisions Walkthroughs and tests Runbooks and release gates Generated reference Systems catalog API and contracts Data schemas Diagrams Owners and testing map ``` The branches are complementary, not interchangeable. Feature prose explains the user and operator contract. Architecture explains runtime ownership and boundaries. Handbooks join concerns that cross many feature or architecture pages. Backlogs and dated evidence record completion state. Generated reference is authoritative for the source inventory it derives, but it cannot prove that a journey is deployed or supported. ## Start with the question you have | Question | Canonical starting point | What to expect | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | What is V1 and what does each release promise? | [Product feature map](../features.md), [feature index](../features/README.md), and [brand/release scope](../BRAND.md) | Product behavior, V1.0/V1.1/V1.2 boundaries, surfaces, domains, and member/operator expectations. | | How is the system assembled? | [Architecture hub](../ARCHITECTURE.md) and [architecture index](../architecture/README.md) | Surfaces, BFF, domains, substrates, data, communication, integrations, safety, operations, and launch topology. | | What is actually complete? | [V1 backlog](../TODOS.md), current dated audits, walkthrough results, generated inventories, and passing release gates | Evidence and known gaps. A feature or architecture page is not a completion ledger. | | How does Eve work? | [Eve handbook](./eve/README.md) | Builder/operator identity, invocation, runtime/tools, context, trust, models/evaluation, operations, and change ownership. | | What are all the workbenches? | [Workbenches handbook](./workbenches/README.md) | Shared Workbench Kit plus Isis, Metis, Yemaya, Veritas, Euterpe, Aja, and Bellona. | | Where is the Yemaya Study Workbench? | [Yemaya Study & Deconstruction Workspace](./workbenches/yemaya-study-workspace.md) | Product journeys, film/game study, evidence, learning, data, rights, evaluation, and operations. | | What does Telegram support? | [Telegram handbook](./telegram/README.md) | Bot, commands, Mini App, linking/auth, rooms, reminders, voice, channels, inline, media, payments, trust, architecture, and operations. | | What does “Lilith” mean here? | [Lilith member experience](../../V3/docs/lilith/member-persona-and-experience.md) and [Lilith handbook](../../V3/docs/lilith/README.md) | V1 member persona, V1 policy substrate, standalone service domain, and V3 metaverse—kept explicitly distinct. | | Where are the visuals? | [V1 diagram atlas](./diagram-atlas.md) and the generated Docs Center diagram gallery | Curated V1 mental models plus every authored Mermaid diagram linked to its source heading. | ## Release and truth model ```mermaid stateDiagram-v2 [*] --> Proposed Proposed --> Designed: approved product or architecture decision Designed --> Implemented: real code or schema plus direct tests Implemented --> Wired: supported surface reaches the implementation Wired --> Deployed: target configuration and runtime composition exist Deployed --> Evidenced: current end-to-end and operational proof Implemented --> Withheld: required provider or evidence absent Wired --> Gated: release tenant role consent or entitlement boundary Gated --> Evidenced: enabled cohort proves the journey Evidenced --> Regressed: current verification or production evidence fails Regressed --> Implemented: repair may remain below deployment readiness ``` Use the most conservative state supported by current evidence: - **Proposed** describes intent, not availability. - **Designed** means the governing decision and boundaries are explicit. - **Implemented** means real code/schema and direct verification exist. - **Wired** means the supported product entry point reaches the real effect. - **Deployed** means the target environment actually runs and configures it. - **Evidenced** means current end-to-end and operational checks prove the claim. - **Gated** names the exact release, tenant, role, consent, entitlement, provider, or rollout condition. - **Withheld** is an honest result when required evidence or capability is unavailable. - **Regressed** means newer evidence contradicts the prior supported claim. Do not infer a higher state from route existence, a polished fixture, a typed port, a response planner, an in-memory store, a checked backlog box, a stale test artifact, or generated documentation. ## V1 release scope The feature documents describe the whole V1 line, not only launch day: | Release | Product scope | | -------- | ---------------------------------------------------------------------------------- | | **V1.0** | Customer web app and PWA; Tara, Nyx, Arete, and Nisaba rooms; crypto payment rail. | | **V1.1** | Native mobile/watch surfaces and fiat payment rails. | | **V1.2** | Veritas and Metis member rooms. | Pages covering later releases remain useful because authoring, governance, data, and review often precede a member launch. They must carry their release boundary and must not be used to advertise a deferred member surface. ## Recommended reading journeys ```mermaid journey title From question to verified V1 change section Orient Open this guide: 5: Reader Choose product architecture or handbook path: 5: Reader section Understand Read the focused page and companion boundary: 5: Reader Inspect canonical contracts code and generated reference: 4: Engineer section Establish truth Check release scope backlog and dated evidence: 5: Product, Engineer Reproduce the relevant journey or gate: 5: QA, Engineer section Change safely Update behavior contracts docs and diagrams together: 4: Engineer Run targeted and end-to-end verification: 5: Engineer, QA section Release Record deployment operational and rollback evidence: 5: SRE, Governance ``` ### Product and design Read the [feature index](../features/README.md), the affected domain or surface, the companion architecture page, and the relevant member/operator walkthrough. Check the release banner before treating a designed capability as customer scope. ### Engineering Read the [architecture index](../architecture/README.md), the owning handbook change map, and generated system/API/data references. Follow the contract into its real service, persistence, provider, surface, and tests. Use the backlog and dated evidence to identify unfinished seams. ### QA and accessibility Begin with the user journey and route/view walkthrough, then verify the real surface through success, empty, long, denied, partial, offline, error, retry, conflict, version, accessibility, and recovery states as applicable. A route test or component snapshot is not a complete cross-service journey. ### SRE, security, privacy, and governance Read the relevant trust and operations pages, then the deployment manifests, dashboards, alerts, runbooks, data lifecycle, recovery evidence, and threat model. Verify external provider readback and durable receipts instead of relying on configuration declarations. ## Page-set organization ### Product features The [feature index](../features/README.md) organizes the complete feature set by orientation, customer domains, authoring/curation, assistant and embodiment, grounding/generation/search, Living Scenes, Agentic AI Studio, admin/tenant, governance/privacy, messaging, and platform/launch. ### Architecture The [architecture index](../architecture/README.md) organizes the runtime by orientation, customer domains, platform substrates, foundations/data/ communication, experiences/systems, and governance/operations/launch. ### Cross-cutting handbooks - [Eve](./eve/README.md) — eight maintained topics. - [Workbenches](./workbenches/README.md) — eight maintained topics including two dedicated Yemaya Study Workspace guides. - [Telegram](./telegram/README.md) — eight maintained topics. - [Lilith](../../V3/docs/lilith/README.md) — eight maintained topics covering the related identities/products without conflation. ### Planning and evidence Planning documents hold capacity, child-safety, regulatory, infrastructure, launch, risk, SLO, and disaster-recovery decisions. Date-stamped audits and remediation records describe a revision and must state their date/source. The backlog is the execution ledger; current tests, deployment state, provider readback, and operational evidence decide whether an older claim still holds. ## Visual language Diagrams are used when relationships are materially clearer than prose: - flowcharts for routing, dependency, and effect pipelines; - sequence diagrams for request/provider and cross-service interactions; - state diagrams for lifecycle, release, review, safety, and recovery; - ER diagrams for durable identities and references; - class diagrams for shared contract composition; - mind maps for taxonomy and ownership; - journeys for multi-actor user and delivery paths; - timelines for release or incident chronology. Every diagram remains adjacent to explanatory prose, uses the same status and ownership vocabulary as the page, and is indexed in the generated diagram gallery. A diagram is a mental model, not independent proof of deployment. ## Documentation quality contract V1 documentation changes are complete when: - the focused feature, architecture, or handbook page is substantial and readable, with purpose, boundaries, status, failure behavior, canonical sources, and related reading where applicable; - every focused feature and architecture topic remains reachable from its canonical index exactly once; - every cross-cutting handbook topic is reachable from its handbook overview; - complex request, state, data, ownership, or operational relationships include an appropriate diagram and accessible surrounding prose; - links, source paths, headings, search entries, sibling navigation, and diagram rendering are generated and verified; - changes to behavior update contracts, tests, walkthroughs, runbooks, and evidence—not documentation alone; - Docs Center generation, integrity, freshness, unit, and desktop/mobile browser checks pass. ## Generated Docs Center reference From the Docs Center portal, use: - **V1 documentation guide** for this curated reading layer; - **Products** for V1 feature/architecture libraries and V1–V10 comparison; - **Systems** and **Repo map** for code ownership and dependency discovery; - **API & contracts**, **Data**, and **Lifecycle** for generated technical reference; - **Diagram gallery** for every authored visual; - **Journeys** and **Testing map** for user-flow and verification evidence; - **Owners**, **Observability**, **Performance**, and **Meta** for operation and coverage posture. The portal and HTML are generated. Edit the Markdown source, generator, or canonical code/evidence—not generated reader files.