Index of everything under docs/. Start with the root README for the product overview and quick start.
Something won't start? Run npm run doctor — a read-only report of every install prerequisite (Node/npm floors, submodule, workspace deps, PostgreSQL + pgvector, migrations, seeded data/, pm2, media toolchain, cert, ports). It runs before npm install and prints one pasteable block; add --json for machine-readable output. Then see TROUBLESHOOTING.md.
| Doc | Covers |
|---|---|
| ARCHITECTURE.md | System design: React client, Express server, PM2 satellites, PostgreSQL + data/ files |
| API.md | REST endpoints, complete route-domain index, Socket.IO events |
| API_TOOL_CONTRACT.md | Unified semantic tool, Persistent Mind, and Agent Tools MCP contract |
| COMPANION_APP_API.md | PortDeck native iOS companion client discovery and HTTP API contract |
| SETUP.md | First install: Tailscale, MagicDNS, trusted HTTPS, exact launch URL, and AI-provider readiness |
| REMOTE_DESKTOP.md | PortDeck VNC broker security, host setup, and session flow |
| FEDERATED_MEDIA_PROVIDERS.md | Authenticated, capacity-aware peer audio provider wire contract and setup |
| STORAGE.md | Storage classification contract — PostgreSQL vs filesystem, new-data-store checklist |
| BACKUP.md | Filesystem snapshots + PostgreSQL dumps, restore semantics |
| PORTS.md | Port allocation (5553–5561) and how 5555/5553/5554 relate |
| PM2.md | Recommended PM2 ecosystem patterns for sub-projects |
| QUOTA-BURN.md | Quota-burn automation — spending subscription-backed CLI quota before expiry |
| THREEJS_MODELS.md | Three.js procedural 3D model generation and trust boundary |
| features/music-renderer-benchmarks.md | Technical and full-length listening evidence for local music renderer profiles |
| CONTRIBUTING.md | Dev setup (PostgreSQL required), code conventions |
| GITHUB_ACTIONS.md | CI and release workflows |
| VERSIONING.md | SemVer + release process (/do:release) |
| SELF_UPDATE.md | Fork-aware self-update flow — release polling, FORK_SYNC_REQUIRED, fork sync, running a customized fork |
| MANAGED_APP_UPDATES.md | Safe managed-app update default and the opt-in app lifecycle contract |
| DEPS.md | Dependency audit — every third-party package and its verdict |
| TROUBLESHOOTING.md | Common runtime issues, known issues |
| WINDOWS_CONSOLE.md | Why console windows flash and steal focus on Windows, and the two fixes |
| GOALS_OPERATIONAL.md | Runtime operating principles the CoS agent reads (parsed by goalProgress.js) |
| METRICS.md | The METRICS.md convention — how a managed app exposes its own success metrics so agents (incl. Layered Intelligence) can evaluate it against its goals |
Start with the product surface map for a complete, user-facing inventory of the application. The focused guides below explain the features with their own operating contracts.
App management: app-wizard · autofixer · browser · error-handling · jira-sprint-manager
Chief of Staff: chief-of-staff · cos-agent-runner · cos-enhancement · agent-context · agent-skills · memory-system · claude-ollama · fleet-llm-host · mtplx · slotstream · dflash2 (DSpark vs DFlash 2) · qwen38-rtx3090 (3090 bring-up) · sglang-qwen38 (SGLang Hopper/Blackwell evaluation) · prompt-manager
Identity & self: digital-twin · identity-system · soul-system · privacy-center · post (insights design spike: plans/2026-06-03)
Knowledge: brain-system · messages-security
Create: writers-room · fableloom · Eidoverse Worlds integration · OpenWorld historical reference · sprite-export-contract · video-text-encoders · video-speed-profiles
Comms & voice: openclaw-operator-chat (pre-build audit) · stacker-news · voice
- plans/ — dated design plans (
YYYY-MM-DD-<slug>.md), archived on approval before implementation. Historical records, not living docs. - decisions/ — ADRs (
YYYY-MM-DD-<slug>.md), e.g. the Postgres-as-primary-datastore decision and what may cross the federation layer (privacy records machine-local, federated visual prompts, conditioning crosses to an allowlisted peer, AI usage metrics federate on by default), and why H3 ships the draft-decode gates without an asset. - research/ — dated investigation and incident write-ups (e.g. the mflux GPU-watchdog panic and the local LLM performance audit).
- superpowers/ — plan/spec pairs from superpowers-driven builds:
specs/<date>-<slug>-design.md(design) +plans/<date>-<slug>.md(implementation plan).
- themes/ — UI theme specs and the theme integration contract.
- examples/ — copy-ready config examples (e.g. Claude Code → Ollama settings).
.changelog/README.md— how/do:releasesynthesizes release notes from the commit log, and the versioned-file format.- media/ — screenshots and logo used by the root README.