Docs Migration Map
What still needs to be migrated from the original Coven docs, and which diagrams should be added next.
Docs Migration Map
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 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