# ALNEAS Documentation Governance Policy Status: Active (2026-10-17) Scope: `eaos-workspace` (public/private), `tools`, `web-framework`, `github-docs` `github-docs` is the centralized public portal aggregating navigation, documentation, search, and architectural showcases across the entire ALNEAS ecosystem. This policy formalizes our documentation standard to ensure exceptional readability for humans, unambiguous context for AI agents, and complete prevention of confidential information leaks. --- ## 1. Single Source of Truth (SSOT) and One-Way Ingestion | Content Category | Canonical SSOT Location | Treatment in `github-docs` | | :--- | :--- | :--- | | **Global Navigation, Showcase, Governance Policies** | `github-docs` | Maintained and edited directly here | | **Technical Guides & Project Documentation** | Respective Owning Projects | Ingested one-way from approved public manifests | | **Extracted API Reference (JSDoc / TypeDoc)** | Upstream Source Code | Generated via `docgen` and merged with translation dictionaries | | **Private Enterprise Guides & Internal Plugins** | Private Repositories | **Strictly excluded** (Provide standalone public summaries if needed) | | **Customer Configs, Receipts, Secret Runbooks** | Private Host Environments | **Strictly excluded** | | **Drafts, Research Notes, Migration Scratchpads** | Upstream `docs/` | **Excluded by default** unless promoted to official guides | | **AI Action Skills (`SKILL.md`)** | Owning Repositories | Kept distinct from human API references | ### Core Rules 1. **No Reverse Syncing**: If an error is spotted in an ingested guide, fix it in the upstream repository, never in `github-docs`. 2. **Never Edit Generated Artifacts**: Files under `src/content/docs/**/api.md` or `generated/` are overwritten during builds. 3. **Audit Trails**: Sync tools track upstream commit SHA, relative path, and SHA-256 content hashes to detect drift. 4. **AI Roadmaps (`llms.txt`)**: Files like `llms.txt` serve as navigational roadmaps to detailed documents, never as duplicate silos of type definitions. --- ## 2. Diátaxis Framework Every page must strictly fulfill exactly one of the four Diátaxis archetypes: ``` [Practical / Task-Oriented] ▲ Tutorials (Learning)│ How-To Guides (Problem-Solving) ─────────────────────────┼──────────────────────────────── Explanation (Theory)│ Reference (Information-Oriented) ▼ [Theoretical / Understanding] ``` 1. **Tutorials**: Step-by-step beginner onboarding taking a newcomer from 0 to 1 in under 10 minutes without branching. 2. **How-To Guides**: Practical recipes solving specific real-world tasks with prerequisites. 3. **Reference**: Machine-precise specifications, parameters, and card-style examples. 4. **Explanation**: High-level architecture, design rationale, and ecosystem context. ### 2.1 The 5-Section Project Landing Standard Every project top-level page (`index.md` / README) must strictly adhere to this structure: 1. **Elevator Pitch**: One sentence clearly articulating who it is for and what problem it solves. 2. **Why & Value Proposition**: Key differentiators and architectural motivation in 3-4 sentences. 3. **Key Highlights**: Bullet points or card-style feature highlights. 4. **Quickstart**: Installation command (`bun add ...`) and a minimal, self-contained, copy-pasteable example under 30 lines. 5. **Next Steps**: Explicit links directing users to Guides, API Reference, and Architecture docs. ### 2.2 Sub-page Standards - **How-To Guides (`/guides/.md`)**: Prerequisites, step-by-step code, expected output/verification, and common pitfalls. - **API Reference (`/api.md`)**: Card-style Swagger layout (Badge, Signature, Parameters table, Returns, Copy-pasteable snippet). - **Architecture (`/architecture.md`)**: Motivation, Mermaid diagrams, and explicit trade-off explanations. --- ## 3. Bilingual Routing and English-First Architecture - **English Canonical Root (`/`)**: All root paths are in English (e.g. `/eaos-workspace/api/`). This is the global open-source standard. - **Japanese Mirror Subpath (`/ja/`)**: Japanese versions are mirrored under `/ja/` (e.g. `/ja/eaos-workspace/api/`). - **Graceful Fallback**: - If a Japanese translation does not exist yet, the build succeeds and serves the English canonical version seamlessly. - Translations are generated via local AI CLIs (`bun run translate`) without blocking CI or PR merges. - Translation dictionaries (`src/data/translations/api-ja.json`) isolate translated strings so upstream code updates do not discard existing translations. --- ## 4. API Specification Standards (Swagger / Card Layout) All public APIs, functions, classes, and endpoints follow this structured presentation: - **Badges**: `[FUNCTION]`, `[CLASS]`, `[INTERFACE]`, `[GET]`, `[POST]` - **Signature**: Exact TypeScript declaration block. - **Parameters Table**: Parameter name, type, required/optional, and concise description. - **Returns**: Return type and description. - **Self-Contained Example**: Working code snippet with complete `import` statements. --- ## 5. Security Gates & Zero-Leak Audits Only files explicitly declared in `governance/sources.json` or approved manifests are ingested: 1. **Absolute Path Elimination**: Absolute filesystem paths (`/Volumes/...`, `/Users/...`, `file://`) fail verification. 2. **Secret Redaction**: Environment variables, tenant IDs, tokens, private hostnames, and customer data are blocked. 3. **Separation of Concerns**: Automated structural validation (broken links, SHA-256 integrity) is decoupled from semantic content review. --- ## 6. Upstream Ingestion Interface (`docs.manifest.json`) Upstream projects integrate with `github-docs` via a standardized interface: 1. **Manifest File**: Upstream repositories place `docs.manifest.json` in their root defining document titles, slugs, source paths, and archetypes. 2. **Ingestion Engine (`scripts/ingest.ts`)**: Rewrites relative links into web routes and organizes content into Starlight directories. 3. **Local Preflight (`bun run ingest --verify`)**: Run locally in upstream repos before pushing to ensure compliance. --- ## 7. Cloudflare Pages Direct Git Integration & Dual Deployment Architecture 1. **Direct Git Integration**: The private GitHub repository (`dataarthub/docs`) is directly connected to Cloudflare Pages. 2. **Automatic Build on `main` Push**: Pushing or committing to `main` instantly initiates an automated edge build (`bun install && bun run build`) with Node 24 runtime. GitHub Actions are entirely bypassed. 3. **Dual-Target Deployment (Public vs Internal)**: - **Public Portal (`docs-d1x.pages.dev`)**: Built with standard configuration (no `INTERNAL` variable). Private internal pages (`/internal/*`) are physically excluded from the generated static bundle. Bandwidth and requests are completely unlimited and free. - **Internal Super-Portal (`internal.alneas.org`)**: Built with environment variable `INTERNAL=true`. Generates the full superset including operational runbooks and is strictly gated behind Cloudflare Zero Trust (Access) SSO authentication. 4. **Redirect Contract (`public/_redirects`)**: Path migrations and legacy routes are maintained via `public/_redirects` to preserve SEO and incoming backlinks. --- ## 8. Open-Core Model vs Private Separation - **Open-Core Public Showroom**: Enterprise features, commercial plugins, and extension interfaces are fully documented publicly to maximize visibility and developer discovery. Packages and binaries are protected at the package registry layer, not by hiding docs. - **Strictly Confidential Material**: Real production infrastructure, internal receipts, database schemas, and customer credentials must never be included in this repository. They are maintained in dedicated private environments behind Cloudflare Zero Trust (Access).