# GPUaaS Docs Workspace ## Read This First - Contracts: - `api/openapi.draft.yaml` - `api/asyncapi.draft.yaml` - Product baseline: - `product/PRD.md` - `product/UX_Journeys.md` - `product/UX_Implementation_Spec.md` - Architecture baseline: - `architecture/platform-foundation/Documentation_Source_Of_Truth_Map_v1.md` - `architecture/Architecture_v1.md` - `architecture/ERD.md` - `architecture/db_schema_v1.sql` - `architecture/Domain_Ownership_Map.md` - Governance baseline: - `Governance_Overview.md` - `governance/Coding_Standards.md` - `governance/Testing_Standards.md` - `governance/production_enforcement_policy.yaml` - Active execution state: - `../.fairway/platform-foundation-implementation-track.yaml` - `../.fairway/platform-foundation-config.toml` - `Execution_Progress.md` - `Phase_Readiness_Tracker.md` - Documentation portal sync: - `PORTAL_SYNC.md` - `product/GPUaaS_Documentation_and_Developer_Portal_Docusaurus_v1.md` ## Source-of-Truth Precedence 1. API/event contracts in `doc/api/*` 2. Physical schema in `architecture/db_schema_v1.sql` 3. Canonical architecture/product/governance docs 4. Active execution state in Fairway queues and progress/readiness docs 5. Historical reference docs (prototype extracts, parity reports, handoff notes) ## Before Creating A New Doc Check the existing corpus first. This repo has already thought through many designs, and the preferred action is to extend, correct, or cross-link an existing canonical doc before creating a parallel spec. Minimum check: 1. Search `doc/**` for the domain terms, product names, table names, route families, event subjects, and known decision IDs. 2. Check `doc/README.md`, `doc/PORTAL_SYNC.md`, relevant platform-foundation docs, ADRs, and active gap/register docs for the current source of truth. 3. If a relevant doc exists, update that doc or add a related-doc cross-link. 4. Create a new doc only when the existing corpus has no clear owner, or when the work needs a distinct artifact such as an ADR, execution backlog, readiness matrix, or runbook. 5. When creating a new doc, state the source docs it builds from and whether it supersedes, complements, or operationalizes them. ## Docusaurus Portal Relationship The Docusaurus portal under `packages/docs/` is the curated audience front door. This `doc/` tree remains the canonical source corpus. Use this rule: - update `doc/**` when a contract, architecture, product, operations, or governance source changes; - update `packages/docs/docs/**` when that source change affects a reader-facing journey, API consumer path, security posture, operator practice, or product explanation; - run `make docs-portal-check` before treating portal changes as complete. See `PORTAL_SYNC.md` for the standing sync contract. ## Folder Layout - `governance/`: Standards, policy, enforcement, CI gates, security, testing, pipeline. - `product/`: PRD, UX journeys, gap analysis. - `architecture/`: target architecture, ERD, physical schema, initialization/migration plan, state/event/compensation models, stack, ownership map, ADRs, and prototype module mapping. - `api/`: OpenAPI and AsyncAPI contracts plus API surface. - `operations/`: local-dev stack, promotion policy, SRE runbook index, incident model, observability baseline, detailed runbooks, and prototype extracts. ## Start Here - Governance: `Governance_Overview.md` - Coding Agent Prep Guide: `governance/How_We_Prepared_For_Coding_Agents.md` - Multi-Agent Execution: `governance/Multi_Agent_Execution_Playbook.md` - Active Fairway queue: `../.fairway/platform-foundation-implementation-track.yaml` - Legacy queue archive: `governance/archive/` - Active execution ledger: `Execution_Progress.md` - Readiness: `Phase_Readiness_Tracker.md` - Sequence: `Implementation_Roadmap.md` - Product: `product/PRD.md` - UX Spec: `product/UX_Implementation_Spec.md` - UX Mocks: `product/ux-mocks/README.md` - Architecture: `architecture/Architecture_v1.md` - Source of Truth Map: `architecture/platform-foundation/Documentation_Source_Of_Truth_Map_v1.md` - Tenant Ownership Baseline: `architecture/Tenant_Project_Ownership_Baseline.md` - Service Account Baseline: `architecture/Service_Account_Model.md` - App Platform Builder Guide: `architecture/Build_an_App_for_GPUaaS_v1.md` - App Platform Quickstart: `architecture/App_Platform_Quickstart_v1.md` - App Platform OCI Registry Baseline: `architecture/App_Platform_OCI_Registry_Baseline_v1.md` - App Artifact Trust and Promotion: `architecture/App_Artifact_Trust_and_Promotion_v1.md` - App Non-OCI Artifact Lifecycle: `architecture/App_Non_OCI_Artifact_Lifecycle_v1.md` - Launchable OCI Workload Profile Contract: `architecture/Launchable_OCI_Workload_Profile_Contract_v1.md` - Launchable OCI Workload Profile Schema: `architecture/schemas/launchable_oci_workload_profile.v1.schema.json` - Platform Vault Secrets Baseline: `architecture/Platform_Vault_Secrets_Baseline_v1.md` - Node Task Signing Lifecycle: `architecture/Node_Task_Signing_Lifecycle_v1.md` - Platform DNS Cert Endpoint Model: `architecture/Platform_DNS_Cert_Endpoint_Model_v1.md` - Node Bootstrap Trust Delivery: `architecture/Node_Bootstrap_Trust_Delivery_v1.md` - Node Agent OCI Distribution: `architecture/Node_Agent_OCI_Distribution_v1.md` - Node Bootstrap Script and Token: `architecture/Node_Bootstrap_Script_and_Token_v1.md` - Resource Identifier Spec: `architecture/Resource_Identifier_Spec.md` - API (HTTP): `api/openapi.draft.yaml` - API (Realtime/Event): `api/asyncapi.draft.yaml` - Local Dev: `operations/local-dev/README.md` - Production Platform Baseline: `operations/Production_Platform_Baseline.md` - Parallel Ops Track: `operations/Parallel_Ops_Track.md` - Scale/Security watchlist: `operations/Scalability_Security_Watchlist.md` ## Canonical Docs - `Implementation_Roadmap.md` - `Phase_Readiness_Tracker.md` - `Release_Go_NoGo_Checklist.md` - `Feedback_Resolution_Log.md` - `product/PRD.md` - `product/UX_Journeys.md` - `product/UX_Implementation_Spec.md` - `product/ux-mocks/*` - `architecture/Architecture_v1.md` - `architecture/Tenant_Project_Ownership_Baseline.md` - `architecture/Service_Account_Model.md` - `architecture/App_Control_Plane_v1.md` - `architecture/Build_an_App_for_GPUaaS_v1.md` - `architecture/App_Platform_Quickstart_v1.md` - `architecture/App_Platform_OCI_Registry_Baseline_v1.md` - `architecture/App_Artifact_Trust_and_Promotion_v1.md` - `architecture/App_Non_OCI_Artifact_Lifecycle_v1.md` - `architecture/Launchable_OCI_Workload_Profile_Contract_v1.md` - `architecture/schemas/launchable_oci_workload_profile.v1.schema.json` - `architecture/Platform_Vault_Secrets_Baseline_v1.md` - `architecture/Node_Task_Signing_Lifecycle_v1.md` - `architecture/Platform_DNS_Cert_Endpoint_Model_v1.md` - `architecture/Node_Bootstrap_Trust_Delivery_v1.md` - `architecture/Node_Agent_OCI_Distribution_v1.md` - `architecture/Node_Bootstrap_Script_and_Token_v1.md` - `architecture/Resource_Identifier_Spec.md` - `architecture/ERD.md` - `architecture/db_schema_v1.sql` - `architecture/Schema_Migration_Plan.md` - `architecture/Partitioning_and_Retention_Strategy.md` - `architecture/Domain_Ownership_Map.md` - `architecture/adrs/*` - `architecture/Event_Taxonomy.md` - `architecture/Compensation_Matrix.md` - `api/API_Surface.md` - `api/openapi.draft.yaml` - `api/asyncapi.draft.yaml` - `governance/*` - `governance/Assumptions_Register.md` - `governance/How_We_Prepared_For_Coding_Agents.md` - `governance/Multi_Agent_Execution_Playbook.md` - `governance/ci_workflow_github_actions.yaml` - `governance/ci_workflow_gitlab_ci.yaml` - `operations/local-dev/*` - `operations/Environment_Promotion_Policy.md` - `operations/Production_Platform_Baseline.md` - `operations/Parallel_Ops_Track.md` - `operations/QA_Disposable_Test_Session_Guide.md` - `operations/SRE_Runbook_Index.md` - `operations/Incident_Severity_Model.md` - `operations/Observability_Baseline.md` - `operations/Scalability_Security_Watchlist.md` - `operations/runbooks/*` ## Execution Docs - `../.fairway/platform-foundation-implementation-track.yaml` - `../.fairway/platform-foundation-config.toml` - `Execution_Progress.md` - `Phase_Readiness_Tracker.md` - `governance/IAM_AppPlatform_MaaS_Execution_Plan.md` - `operations/Parallel_Ops_Track.md` - `Release_Go_NoGo_Checklist.md` ## Historical / Reference Docs - `governance/Agent_Work_Queue.yaml` - `governance/archive/Agent_Work_Queue_2026-03-09.yaml` - `Detailed_Implementation_Plan.md` - `product/Prototype_UX_Parity_Report.md` - `operations/Handoff_2026-02-25.md` - `operations/prototype_current_behavior_spec.md` - `operations/prototype_data_dictionary.md` - `operations/prototype_env_config.md` - `architecture/prototype_module_map.md` ## Quick Canonical Set (Minimal Read Path) - `product/PRD.md` - `architecture/Architecture_v1.md` - `api/openapi.draft.yaml` - `api/asyncapi.draft.yaml` - `Governance_Overview.md` - `governance/How_We_Prepared_For_Coding_Agents.md` - `governance/Assumptions_Register.md` - `governance/production_enforcement_policy.yaml` - `governance/CI_Pipeline_Implementation.md` - `Phase_Readiness_Tracker.md` - `Feedback_Resolution_Log.md` ## Working Rules - Keep current behavior and target behavior explicitly separated. - Update contracts/policies before implementation changes. - Prefer machine-readable policy updates where possible.