Skip to content
foxctl foxctl

Documentation map

The foxctl documentation spans the production docs site, the repository docs/ directory, and generated artifacts. This page maps the structure, explains lifecycle categories, and shows how to find what you need.

Repository docs structure

Section titled “Repository docs structure”

The canonical docs live in docs/ at the repository root:

Current behavior

Section titled “Current behavior”
DirectoryContents
docs/general/Subsystem guides and operational references (skills, hooks, memory, storage, sessions, events)
docs/architecture/Current architecture boundaries (runtime, storage, context, auth, package topology)
docs/spec/Protocol and behavior contracts
docs/spec/v1/Stable v1 protocol docs; non-v1 specs may still be evolving
docs/guides/How-to guides (Kubernetes deployment, feature design)
docs/start/Fast orientation for common workflows

Planning

Section titled “Planning”
DirectoryContents
docs/plans/Active implementation plans and roadmaps
docs/plans/features/Individual feature plans and design documents

Plan content is not production behavior until promoted into current docs.

Historical and generated material

Section titled “Historical and generated material”
DirectoryContents
docs/archive/Superseded or historical material
docs/codemaps/Generated analysis artifacts
docs/changelogs/Historical change notes
docs/designs/Design proposals (mixed status)
docs/research/Exploratory research notes
docs/notes/Working notes (non-canonical)
docs/examples/Example workflows and configuration
docs/ci/CI-specific documentation

Lifecycle categories

Section titled “Lifecycle categories”

Docs are organized by lifecycle class, defined in docs/DOC_LIFECYCLE.md:

ClassLocationMeaningMaintenance expectation
Currentdocs/general/, docs/architecture/, docs/spec/Represents current behavior and contractsMust be kept accurate with code changes
Active Plandocs/plans/Forward-looking implementation workUpdate as plans evolve; archive when complete or superseded
Legacy Plandocs/impl_plan/Historical phased plansKeep for provenance; avoid using as canonical guidance
Historicaldocs/archive/Superseded or legacy materialRead-only except link hygiene and provenance notes
Generateddocs/codemaps/Generated analysis artifactsRegenerate when needed; not canonical
Working Notesdocs/notes/, docs/research/, docs/designs/Exploratory or non-final materialPromote stable decisions into current docs

Rules

Section titled “Rules”
  1. New canonical behavior docs go in docs/general/, docs/architecture/, or docs/spec/.
  2. New planning docs go in docs/plans/ (not docs/impl_plan/).
  3. Completed or superseded plans and designs move to docs/archive/.
  4. Historical docs may keep legacy content, but links must remain navigable.
  5. When behavior changes, update the matching canonical doc in the same PR.
  6. Markdown links in repo docs must pass make check-doc-links.

Docs-site sections

Section titled “Docs-site sections”

This Starlight site organizes content into browsable sections:

Site areaPurposeExample pages
Start HereFirst-run path and docs taxonomyOverview, Install, Docs map
GuidesFeature design, skill authoring, workflow walkthroughsDesign a feature, Add a skill
Core WorkflowsSkills, retrieval, repoindex, ACA, context engine, memorySkills runtime, Search and index
Agents and RoomsAgent daemon, overseer, rooms, collaborationAgent lifecycle, Orchestration, Rooms
IntegrationsMCP, OpenAPI, hooks, chat platforms, Obsidian, and integration maturityIntegration status, Providers and MCP, Hooks
ReferenceCommand map, CLI, Protocol v1, storageCLI, Command map, Protocol v1
ArchitectureSystem, design principles, runtime, API, authSystem, Design principles, Runtime
OperationsGotchas, observability, CI/evals, benchmarks, KubernetesGotchas, Troubleshooting, Benchmarks
Roadmap and ArchiveProgress, in-progress work, planned, experimental, generated, and historical materialProgress, Planned and archive

Reading order for new contributors

Section titled “Reading order for new contributors”
  1. AGENTS.md — Contributor and AI assistant operating rules
  2. README.md — Product overview and quick start
  3. docs/start/README.md — Fast orientation for common workflows
  4. docs/architecture/package-topology.md — Read before introducing a new internal/* root
  5. docs/DOC_LIFECYCLE.md — Documentation lifecycle and maintenance policy

Current runtime reading order

Section titled “Current runtime reading order”

For understanding the full system architecture:

  1. docs/architecture/system-architecture.md
  2. docs/architecture/package-topology.md
  3. docs/architecture/context-architecture.md
  4. docs/architecture/rlm-gather-context.md
  5. docs/architecture/jido-hybrid-runtime.md
  6. docs/architecture/go-native-runtime-and-optional-jido.md
  7. docs/general/runtime-orchestration.md
  8. docs/general/agent-daemon.md
  9. docs/spec/agent_hierarchy.md
  10. docs/spec/overseer_profile.md

Automated checks

Section titled “Automated checks”
  • Local: make check-doc-links
  • CI: .github/workflows/docs.yml

Canonical sources

Section titled “Canonical sources”