Docs Migration Map
What still needs to be migrated from the original Coven docs, and which diagrams should be added next.
1 min read
This page tracks the gap between the original OpenCoven/coven/docs corpus and the public docs site.
The goal is to keep the docs honest: current runtime behavior should be documented as current, while future hosted APIs, distributed orchestration, and harness handoffs should be labeled as roadmap work until shipped.
Current first-class migrations now include Daemon, CLI Reference, Harnesses, and Memory + Models.
Current Stack to Show
The public homepage should expose the actual Coven runtime stack, not only the familiar-facing abstraction.
Already Migrated
These areas are present in the docs site and should now be polished, not duplicated:
| Source docs | Site location | Status |
|---|---|---|
GETTING-STARTED.md | Guide / Getting Started | Migrated |
CONCEPTS.md, GLOSSOLALIA.md | Guide / Concepts, Reference / Glossolalia | Migrated |
ARCHITECTURE.md | Guide / Architecture | Migrated |
SESSION-LIFECYCLE.md | Familiars / Sessions | Migrated |
HARNESS-ADAPTERS.md | Familiars / Harnesses | Migrated |
CLIENT-INTEGRATION.md | Familiars / Clients | Migrated |
API-CONTRACT.md, API.md | Reference / API | Migrated |
AUTH.md, SAFETY-MODEL.md | Reference / Auth, Reference / Safety | Migrated |
ROADMAP.md | Reference / Roadmap | Migrated |
TROUBLESHOOTING.md | Reference / Troubleshooting | Migrated |
Add Next
| Source doc | Target section | Status |
|---|---|---|
install/index.md | Guide / Install | Migrated |
install/macos.md | Guide / Install | Migrated |
install/linux.md | Guide / Install | Migrated |
install/windows.md | Guide / Install | Migrated |
install/wsl2.md | Guide / Install | Migrated |
install/docker.md | Guide / Install | Planned / experimental |
install/podman.md | Guide / Install | Planned / experimental |
install/nix.md | Guide / Install | Planned / experimental |
install/from-source.md | Guide / Install | Migrated |
install/cargo.md | Guide / Install | Migrated |
install/npm.md | Guide / Install | Migrated |
install/coven-home.md | Guide / Install | Migrated |
install/updating.md | Guide / Install | Migrated |
install/uninstall.md | Guide / Install | Migrated |
API Naming Note
The current Future Hosted API section is intentionally hidden from the main docs nav until it has a real auth and product contract. Current API docs should point to the local daemon API only.
| Decision | Status | Reason |
|---|---|---|
| Keep Reference / API as the shipped local daemon API | Current | The current API is HTTP over Unix socket, /api/v1, with no OAuth/JWT/API keys. |
| Hide hosted-style pages from the main nav | Applied | Hosted auth and remote access are future-facing, not the shipped daemon contract. |
| Replace hosted-style pages with daemon endpoint pages when possible | Preferred next step | Health, capabilities, sessions, events, input, kill, archive, summon, and sacrifice are the useful current reference targets. |
Diagram Backlog
Runtime Topology
Trust Boundary
Session Lifecycle
Client Handshake
Cast Codes Intent Mapping
Cast Agent Substrate Flow
Harness Adapter Lifecycle
Troubleshooting Flow
Migration Order
| Step | Work | Dependency |
|---|---|---|
| 1 | Expand the homepage stack and link it to real docs. | Foundation |
| 2 | Add this migration map so future work has a checklist. | Foundation |
| 3 | Add Install. | Foundation |
| 4 | Add Daemon. | Foundation |
| 5 | Split Harnesses into overview plus per-harness pages. | Core runtime |
| 6 | Expand Familiars. | Core runtime |
| 7 | Add Memory and Models. | Core runtime stable |
| 8 | Add Automation, Capabilities, and Help. | Core runtime stable |
| 9 | Revisit Spanish docs after the English information architecture is stable. | English IA stable |
Last updated on