CompleteDotTech · CompleteDotTech · Aug 30, 2026 · Aug 30, 2026 · Aug 30, 2026 · Aug 30, 2026
diff --git a/README.md b/README.md
diff --git a/SECURITY.md b/SECURITY.md
diff --git a/docs/DOCS-MAINTENANCE.md b/docs/DOCS-MAINTENANCE.md
@@ -35,6 +35,49 @@ When moving a topic:
 4. Keep normative details here only when the public page links back to the
    source contract.
 
+## Public-doc directory boundary
+
+The repository's public-doc directories may contain only two kinds of pages:
+
+- **Canonical pointers** — a stable repository entry point whose body links to
+  the canonical `docs.opencoven.ai` route. Use this shape:
+
+  ```md
+  ---
+  title: "<existing page title>"
+  description: "Pointer to the canonical <topic> guidance."
+  ---
+
+  Canonical <topic> guidance: **https://docs.opencoven.ai/docs/<route>**
+
+  <optional one-line note retaining a source-adjacent contract link>
+  ```
+
+- **Source-adjacent exceptions** — a page that must evolve with the code
+  (contracts, maintainer source maps, verification procedures). Every retained
+  page states its source-adjacent ownership reason, either in the page itself
+  or in the ownership table in [`README.md`](../README.md) and
+  [`docs/index.md`](index.md).
+
+Public-doc directories today: `docs/install/`, `docs/platforms/`,
+`docs/start/`, `docs/help/`, `docs/harnesses/`, `docs/models/`,
+`docs/memory/`, `docs/guides/`, `docs/reference/`, and the public operation
+pages of `docs/daemon/`. Source-adjacent trees (`docs/design/`,
+`docs/development/`, `docs/superpowers/`, `docs/architecture/`,
+`docs/security/`) and the top-level normative contracts are exempt.
+
+Do not add a new public page to these directories, and do not restore
+duplicated prose. If a canonical target is missing, the local page stays
+unchanged until the canonical coverage lands in `coven-docs` — topical
+similarity alone is not duplication, and an absent canonical target blocks
+removal, never forces a rewrite here.
+
+Public user guidance pages that remain because their canonical target is still
+pending (for example the platform pages retained until
+`scripts/onboarding-docs-test.mjs` is migrated to canonical-pointer
+expectations) are listed as pending exceptions in the tracking issue, not
+silently kept.
+
 ## Public content stance
 
 All committed documentation is public. It should describe OpenCoven and Coven

diff --git a/docs/architecture/mobile-device-pairing-delivery-plan.md b/docs/architecture/mobile-device-pairing-delivery-plan.md
@@ -29,6 +29,8 @@ Exit criteria: language-level tests and cross-implementation vectors pass.
 
 ### PR 3 — TUI enrollment and device administration
 
+Detailed slice plan: [`mobile-device-pairing-tui-bootstrap-plan.md`](mobile-device-pairing-tui-bootstrap-plan.md) (issue #785).
+
 - `coven device pair`
 - scope selection and permission preview
 - terminal QR plus copyable fallback

diff --git a/docs/architecture/mobile-device-pairing-tui-bootstrap-plan.md b/docs/architecture/mobile-device-pairing-tui-bootstrap-plan.md
diff --git a/docs/design/mobile-assurance-step-up-v1.md b/docs/design/mobile-assurance-step-up-v1.md
diff --git a/docs/index.md b/docs/index.md
@@ -28,3 +28,5 @@ implementation:
   implementation decisions, plans, and historical records.
 
 See [`DOCS-MAINTENANCE.md`](DOCS-MAINTENANCE.md) before adding or moving a page.
+Its public-doc directory boundary defines which directories may contain only
+canonical pointers or source-adjacent exceptions.
diff --git a/docs/install/cargo.md b/docs/install/cargo.md
@@ -1,73 +1,10 @@
 ---
-summary: "Build and install Coven directly from crates.io with cargo."
-read_when:
-  - You prefer building Rust binaries yourself
 title: "Install via cargo"
-description: "Install Coven from source with cargo: build the Rust daemon and CLI, drop the binary on PATH, and verify the install with coven doctor."
+description: "Pointer to the canonical Coven install guidance."
 ---
 
-# Install via cargo
+Canonical install guidance, including the source-checkout route:
+**https://docs.opencoven.ai/docs/guide/install**
 
-Use this route when you want to build the Rust CLI yourself. For most users, [Install via npm](/install/npm) is the shorter path.
-
-## From a checkout
-
-```sh
-git clone https://github.com/OpenCoven/coven.git
-cd coven
-cargo build -p coven-cli --release
-mkdir -p "$HOME/.local/bin"
-cp target/release/coven "$HOME/.local/bin/coven"
-coven doctor
-```
-
-On Windows, copy `target\release\coven.exe` to a directory on `PATH`, then open a new terminal and run:
-
-```powershell
-coven doctor
-```
-
-## Running without copying
-
-From the repository checkout:
-
-```sh
-cargo run -p coven-cli -- doctor
-cargo run -p coven-cli -- daemon start
-cargo run -p coven-cli -- run codex "describe this repo"
-```
-
-## Harness setup
-
-Coven still needs a harness CLI for real agent work:
-
-```sh
-npm install -g @openai/codex
-codex login
-```
-
-```sh
-npm install -g @anthropic-ai/claude-code
-claude doctor
-```
-
-Run `coven doctor` after installing or changing harness auth.
-
-## Updating a cargo-built binary
-
-```sh
-cd /path/to/coven
-git pull --ff-only
-cargo build -p coven-cli --release
-cp target/release/coven "$HOME/.local/bin/coven"
-coven daemon restart
-coven doctor
-```
-
-Use the Windows binary name when updating a Windows install.
-
-## Related
-
-- [Install from source](/install/from-source)
-- [COVEN_HOME layout](/daemon/coven-home)
-- [Updating Coven](/install/updating)
+Contributor build and verification instructions remain in
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md).
diff --git a/docs/install/coven-home.md b/docs/install/coven-home.md
@@ -1,35 +1,10 @@
 ---
-summary: "What lives under COVEN_HOME and how to relocate it."
-read_when:
-  - Customizing where Coven keeps state
 title: "COVEN_HOME layout"
-description: "How to lay out COVEN_HOME on a fresh install: the SQLite ledger, append-only event log, sockets, and per-session directories the daemon expects."
+description: "Pointer to the canonical daemon configuration guidance."
 ---
 
-`COVEN_HOME` is Coven's local state directory. If you do not set it, Coven uses `<home>/.coven`.
+Canonical daemon configuration guidance, including relocating `COVEN_HOME`:
+**https://docs.opencoven.ai/docs/daemon/configuration**
 
-Coven resolves `<home>` from the normal platform home directory. On Windows this includes `USERPROFILE` and `HOMEDRIVE` + `HOMEPATH`, so `coven doctor` should not require a Unix-style `HOME` variable.
-
-The directory contains:
-
-- `coven.sqlite3` — the local session ledger;
-- `daemon.json` and daemon sockets/pipes — local daemon metadata;
-- `sessions/` and event logs — per-session artifacts;
-- `familiars.toml` — optional local familiar declarations;
-- `adapters/` — trusted local harness adapter manifests, including recipes created by `coven adapter install <id>`.
-
-Override it only when you want Coven state somewhere else:
-
-```sh
-export COVEN_HOME="$HOME/.coven"
-coven doctor
-```
-
-PowerShell:
-
-```powershell
-$env:COVEN_HOME="$env:USERPROFILE\.coven"
-coven doctor
-```
-
-See [Install overview](/install/index) for the broader install flow.
+The normative source-adjacent state-layout contract remains in
+[`../daemon/coven-home.md`](../daemon/coven-home.md).
diff --git a/docs/install/docker.md b/docs/install/docker.md
@@ -1,88 +1,7 @@
 ---
-summary: "Run the Coven daemon inside a Docker container."
-read_when:
-  - Containerizing Coven for CI or homelab use
 title: "Docker"
-description: "Run Coven in Docker: a containerized daemon plus harness CLIs, with bind mounts for COVEN_HOME and the project root for each session."
+description: "Pointer to the canonical Coven deployment guidance."
 ---
 
-# Docker
-
-Docker is an advanced setup path. This repository does not define a canonical Coven application image in the install docs; build your own image when you need container isolation for CI, demos, or a homelab.
-
-Use native installs for normal workstation use: [macOS](/install/macos), [Linux](/install/linux), [Windows](/install/windows), or [WSL2](/install/wsl2).
-
-## Minimal source-built image
-
-Create a Dockerfile in your own deployment repo:
-
-```Dockerfile
-FROM rust:1-bookworm AS build
-WORKDIR /src
-COPY . .
-RUN cargo build -p coven-cli --release
-
-FROM debian:bookworm-slim
-RUN apt-get update \
-  && apt-get install -y --no-install-recommends ca-certificates nodejs npm git \
-  && rm -rf /var/lib/apt/lists/*
-COPY --from=build /src/target/release/coven /usr/local/bin/coven
-ENV COVEN_HOME=/var/lib/coven
-WORKDIR /workspace
-CMD ["coven", "doctor"]
-```
-
-Build it from a Coven source checkout:
-
-```sh
-docker build -t coven-local .
-```
-
-## Run with explicit mounts
-
-```sh
-mkdir -p "$HOME/.coven-container"
-docker run --rm -it \
-  -e COVEN_HOME=/var/lib/coven \
-  -v "$HOME/.coven-container:/var/lib/coven" \
-  -v "$PWD:/workspace" \
-  -w /workspace \
-  coven-local coven doctor
-```
-
-For real harness work, the container must also contain and authenticate the harness CLI. Provider credentials remain owned by that harness, not by Coven.
-
-## First container session
-
-```sh
-docker run --rm -it \
-  -e COVEN_HOME=/var/lib/coven \
-  -v "$HOME/.coven-container:/var/lib/coven" \
-  -v "$PWD:/workspace" \
-  -w /workspace \
-  coven-local coven daemon start
-```
-
-Then run a session in the same mounted environment:
-
-```sh
-docker run --rm -it \
-  -e COVEN_HOME=/var/lib/coven \
-  -v "$HOME/.coven-container:/var/lib/coven" \
-  -v "$PWD:/workspace" \
-  -w /workspace \
-  coven-local coven run codex "describe this repo"
-```
-
-## Notes
-
-- Bind-mount `COVEN_HOME` if you want session history to survive container exits.
-- Bind-mount the project root you intend to run in.
-- Do not expose the Coven daemon socket over TCP by default.
-- Run `coven doctor` inside the same image and environment that will launch sessions.
-
-## Related
-
-- [Headless server](/install/headless-server)
-- [Podman](/install/podman)
-- [COVEN_HOME layout](/daemon/coven-home)
+Canonical deployment guidance, including manual container integrations:
+**https://docs.opencoven.ai/docs/guide/deployments**
diff --git a/docs/install/from-source.md b/docs/install/from-source.md
@@ -1,94 +1,10 @@
 ---
-summary: "Clone the repo and build coven with cargo."
-read_when:
-  - Developing Coven or running unreleased changes
 title: "Install from source"
-description: "Build and install Coven from source: clone the repo, build the Rust daemon and CLI with cargo, and drop the binary on PATH for daily use."
+description: "Pointer to the canonical Coven install guidance."
 ---
 
-# Install from source
+Canonical install guidance, including the source-checkout route:
+**https://docs.opencoven.ai/docs/guide/install**
 
-Use a source checkout when you are contributing to Coven, testing unreleased changes, or running on a platform where the npm native package is not available.
-
-## Requirements
-
-- Rust stable.
-- Git.
-- A supported shell for your platform.
-- At least one harness CLI if you want to launch real sessions.
-
-## Build and verify
-
-```sh
-git clone https://github.com/OpenCoven/coven.git
-cd coven
-cargo build --workspace
-cargo run -p coven-cli -- doctor
-```
-
-Run the binary through Cargo while developing:
-
-```sh
-cargo run -p coven-cli -- daemon start
-cargo run -p coven-cli -- run codex "describe this repo"
-cargo run -p coven-cli -- sessions
-```
-
-## Install the built binary
-
-After building, copy the release binary to a directory on `PATH`:
-
-```sh
-cargo build -p coven-cli --release
-mkdir -p "$HOME/.local/bin"
-cp target/release/coven "$HOME/.local/bin/coven"
-coven doctor
-```
-
-On Windows, copy `target\release\coven.exe` to a directory on `PATH`.
-
-## Harness setup
-
-Install and authenticate a harness in the same shell environment:
-
-```sh
-npm install -g @openai/codex
-codex login
-```
-
-```sh
-npm install -g @anthropic-ai/claude-code
-claude doctor
-```
-
-Then run:
-
-```sh
-coven doctor
-```
-
-## Development checks
-
-Before changing daemon, session, attach, or ritual behavior, run the workspace
-checks described in [CONTRIBUTING.md](../../CONTRIBUTING.md) and
-[Documentation maintenance](/DOCS-MAINTENANCE).
-
-For docs-only install work:
-
-```sh
-python scripts/check-secrets.py
-git diff --check
-```
-
-For code work:
-
-```sh
-cargo fmt --check
-cargo test --workspace --locked
-```
-
-## Related
-
-- [Install via npm](/install/npm)
-- [Install via cargo](/install/cargo)
-- [Linux install](/install/linux)
+Contributor build and verification instructions remain in
+[`CONTRIBUTING.md`](../../CONTRIBUTING.md).