Documentation Structure

This page defines the current documentation structure and the intent of each lane.

Audience: Documentation maintainers and contributors.

Context: Use this map before adding new pages, moving concepts, or expanding a section.

Top-Level Structure

The documentation system is split into four top-level areas:

Area	Purpose	Content status
Open Source	Complete public documentation for the open-source runtime and codebase	Active content
SDK	Future SDK documentation for client libraries and integration flows	Structure only
Enterprise	Public enterprise user-facing navigation only	Placeholder only
Documentation System	Rules, structure, and future authoring standards	Active content

Open Source Structure

Open-source documentation is split by audience first, then by depth.

Overview

• Open Source Overview Explains the runtime model, the host-versus-runtime split, and how the rest of the docs are organized.

End Users

• Open Source End Users Landing page for operators using the runtime.
• Installation Prerequisites, install path, and runtime setup expectations.
• Quickstart Shortest successful path to a working runtime.
• Concepts Core public concepts: workspaces, principals, policies, mandates, delegation, ledgers, providers.
• CLI Host command model, in-container CLI model, and restricted shell behavior.
• TUI Flow navigation, onboarding, and screen model.
• Configuration Workspace config, environment variables, secrets, and provider configuration.
• Commands Grouped reference for the user-visible command surface.
• Workflows End-to-end operational flows across workspace, providers, policy, mandate, backup, and recovery tasks.
• Security Public security model, fail-closed behavior, secrets handling, and runtime boundary explanations.
• Troubleshooting Startup, runtime, workspace, database, Redis, and provider diagnostics.

Developers

• Open Source Developers Landing page for contributors and repository readers.
• Architecture System-level map of the repository and runtime.
• Runtime Model Entrypoints, Docker Compose runtime, restricted shell, and command-surface boundaries.
• Core Authority System Principal, policy, mandate, delegation, intent, validation, and ledger behavior.
• Storage and Data Workspace layout, configuration loading, PostgreSQL models, Redis cache, Merkle integrity, and migrations.
• Services and Integrations MCP service, monitoring, provider catalog, deployment helpers, and integration boundaries.
• Flow TUI Internals Flow app orchestration, persisted state, onboarding, and screen organization.
• Development Setup Local setup for contributors.
• Contributing Contribution workflow and expectations.
• Testing Test suite layout and strategy.
• Releases Versioning, release scripts, and packaging surfaces.
• Changelog Scope and responsibility of change summaries.
• Enterprise Connector Public open-source boundary to enterprise behavior.

SDK Structure

SDK documentation is present in navigation but intentionally deferred for content.

• SDK Overview
• SDK Concepts
• SDK Authentication
• Python SDK
• TypeScript SDK
• SDK Workflows
• SDK Reference

These pages exist so the information architecture is stable before SDK content is written.

Enterprise Structure

Enterprise remains public and high-level only.

• Overview
• Getting Started
• Configuration
• Administration
• Access / Auth
• Deployment
• Monitoring
• Troubleshooting
• Reference

No enterprise implementation internals belong in this documentation system.

Page Ownership Rules

• End-user pages own operational guidance.
• Developer pages own internals and codebase behavior.
• Overview pages own orientation, not detailed reference.
• Reference pages own grouped command or API lookup material.
• Workflow pages own ordered task sequences.
• Concept pages own shared mental models.

Expansion Rules

Add a new page only when one of these is true:

• A concept has become too large for its current page.
• Two audiences need materially different explanations.
• The same explanation is being repeated in multiple places.
• A module boundary needs a canonical internal explanation.

Do not add a page just to mirror a directory in the repo. Add it only when the reader benefits from a stable conceptual boundary.