Documentation Hub

Documentation Hub

Last reviewed: 2026-06-20

This is the single entry point for FractalOps documentation. Human-facing documentation is an Astro/Starlight site under docs/src/content/docs/. Location-sensitive agent instructions and scaffolder template seed files are classified here so operators and agents do not pick stale scattered notes.

Read Order

1. FractalOps Constitution
2. FractalOps Canonical Architecture
3. Current Stack, Solution, and IA Map
4. Architecture Overview
5. Engineering Handoff
6. Requirements Index

Canonical Docs

Topic	Canonical File	Status
Product law	FractalOps Constitution	Canonical
Product identity	Canonical Architecture	Canonical
Current stack and IA	Current Stack, Solution, and IA Map	Canonical
Execution and platform topology	Architecture Overview	Canonical detail
Execution naming	Execution Naming Glossary	Canonical glossary
Architecture linting	Tach DDD / Feature Slice Boundary Standard	Cross-solution standard
Engineering handoff	Engineering Handoff	Operator detail
AgentSquad runtime operations	AgentSquad Runtime Operations	Operator runbook
Build and error observability	Build Plane Observability	Observability detail
Dev preview plane	Dev Preview Plane	Bare-process preview + signed URL + monstore.io routing
Project dev service plane	Project Development Service Plane	Workspace vs Dokploy backing-service boundary
Agent PR delivery	Agent PR Submission Pipeline	Delivery detail
Harness runtime	Harness Runtime	Lifecycle detail
DataHub projection	Harness DataHub Projection	Lineage detail
Ontology and lineage	Lineage Ontology v1	Semantics detail
Feature plane	Feature Plane	Agent context detail
Portal delivery	Portal Delivery Flow	Portal detail
Copilot module	Portal Copilot Module	Portal detail
Research mode	Research Astro/Starlight Workspaces	Research detail
Build/cache plane	Build & Package Cache Topology (Nexus)	Cache detail
Nexus docker mirror cutover	Nexus Docker Mirror Cutover	Cache cutover runbook
K3s node hygiene	K3s Node Hygiene	Node runbook
AgentSquad PARA	AgentSquad PARA	AgentSquad runtime overview
Cloudflare/OpenBao	Cloudflared OpenBao	Edge detail
Notifications	Novu Notifications	Notification detail
Korean operator manual	Operations Manual KO	Operator mirror

Requirements Docs

The Requirements Index owns the requirements routing table. The current stack map is higher priority when legacy stack pages disagree.

Topic	File
Common contract	requirements/common-contract.md
MCP E2E scenarios	requirements/e2e-scenarios-mcp.md
Stack pages	requirements/stacks/

Co-Located Docs Under colocated/

These files used to live near code. They are now physically centralized under docs/src/content/docs/colocated/ and are not allowed to redefine product architecture.

Location	Role	Canonical Parent
README.md	Repository landing page	This hub
AGENT.md	Repository coding rules	Constitution/current stack map
CLAUDE.md	Claude-local agent notes	AGENT.md
yamonco/fractalops-frontend	Portal and static frontend source	Portal delivery docs
docs/colocated/ops/infra/README.md	Infra SSOT and topology operations	Current stack map
docs/colocated/ops/infra/tofu/README.md	OpenTofu infra declaration notes	Infra SSOT
ops/AGENT.md	Ops-local rules	Infra SSOT
platform/k8s/AGENT.md	Kubernetes-local rules	Infra SSOT
docs/colocated/contracts/README.md	Contract package index	Constitution/contracts
docs/colocated/packages/workspace-shims/README.md	Workspace shim usage	Daytona Template GitOps
docs/colocated/plugins/README.md	Plugin package index	Armory/runtime docs
docs/colocated/scripts/README.md	Script package index	Operations docs
docs/colocated/ops/codexgate/scenarios/README.md	CodexGate scenario notes	GitHub App delivery docs
tests/AGENT.md	Test-local rules	Validation docs
docs/colocated/tests/contracts/README.md	Contract test usage	Validation docs
docs/colocated/tests/e2e/README.md	E2E test usage	Test scenarios
docs/colocated/tests/integration/shared/README.md	Shared integration test usage	Validation docs

Agent Context Docs

These are agent harness context files, not operator docs. They must be regenerated or updated from canonical docs when drift is found.

Location	Role
.agent-os/context/canonical-summary.md	Condensed canonical summary
.agent-os/context/ddd-context-map.md	DDD context map
.agent-os/context/e2e-manifest.md	E2E routing
.agent-os/context/fractal-plan-l0-l3.md	L0-L3 plan
.claude/agents/STUDIO.md	Claude Studio agent local profile

Template Seed Docs

These files intentionally remain outside docs/ because they are copied into generated repositories or packages. They are template payload, not FractalOps operator docs.

Location	Role	Canonical Parent
ops/scaffolder/templates/create-package/README.md	Package template operator notes	Scaffolder templates
ops/scaffolder/templates/create-package/skeleton/README.md	Generated package README seed	Scaffolder templates
ops/scaffolder/templates/create-project/README.md	Project template operator notes	Scaffolder templates
ops/scaffolder/templates/create-project/skeleton/README.md	Generated project README seed	Scaffolder templates
ops/scaffolder/templates/create-project/skeleton/docs/index.md	Generated project docs seed	Scaffolder templates

Deprecation Lane

The following document groups are legacy, generated, or local-only. Keep them out of operator read order unless a specific task names them.

Location	Treatment
.serena/memories/*	Tool memory, not product docs
.pytest_cache/README.md	Pytest generated note
output/*	Run artifact output, not canonical docs
docs/src/content/docs/architecture/*todo*	Historical planning only unless promoted here

Maintenance Rules

• New human-facing docs go under docs/ and must be linked from this hub.
• Template seed READMEs may stay outside docs/ only when the scaffolder copies them into generated repositories or packages.
• README.md stays a landing page and points here.
• docs/src/content/docs/index.md stays a short route map and points here.
• Old stack pages must start by deferring to Current Stack, Solution, and IA Map.
• If a file is not linked here, agents should treat it as local context or legacy until it is classified.

Verification Commands

find . -maxdepth 3 \( -path './.git' -o -path './node_modules' -o -path './.state' \) -prune -o \( -name '*.md' -o -name '*.mdx' \) -print | sort
fops stacks list --compact