Index of everything under docs/. Start with the root README for the product overview and quick start, and ETHOS.md for the project's position on autonomy, digital-mind individuality, privacy boundaries, and why consent here is architecture rather than a service.
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 |
|---|---|
| HTML_COMPOSITIONS.md | Seekable HTML scenes rendered offline to MP4 through hidden managed-browser targets |
| SUPERCOLLIDER.md | Managed SuperCollider Docker runtime: setup:supercollider, readiness states, containment policy and platform evidence |
| CODE_ANIMATION_PACKAGES.md | Versioned portable Code Animation source/brief packages, non-executing validation, and contained production execution |
| ARCHITECTURE.md | System design: React client, Express server, PM2 satellites, PostgreSQL + data/ files |
| features/catalog-ingest.md | Catalog extraction graph, context budgets, coverage, and review draft contract |
| 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 |
| ITERM.md | The Shell page's iTerm2 view — requirements, status states and their fixes, why iTerm2 sessions stay separate from PortOS shells, the clean-room protocol rule |
| INSTANCE_FEATURES.md | Optional per-install features — registry, client-side nav gating, feature groups, reconcile-at-toggle |
| PM2.md | Recommended PM2 ecosystem patterns for sub-projects |
| DEEP-AUDITS.md | Persistent audit coverage, independent passes, checkpoint/resume and completion rules |
| QUOTA-BURN.md | Quota-burn automation — spending subscription-backed CLI quota before expiry |
| AI_PROVIDERS.md | The AI Providers page: a run composed from Harness × Method × Service × Model × Effort, its Presets / Harnesses / Services views, compatibility matrix, derived vs legacy presets, and what federates (nothing) |
| PROVIDER_COMPOSITION.md | Composite provider ids (harness.method@service[+bootstrap]): the grammar, per-harness enablement, bootstrap apps, how every run path resolves one, and the preset-only surfaces |
| MODEL_ACCESS.md | Scoping a provider to the models your plan entitles you to — free tiers, allow/deny globs, gateway inheritance |
| MODEL-COMPARISON.md | Sourced provider/model/effort comparisons, cost estimates and CoS research refresh |
| THREEJS_MODELS.md | Three.js procedural 3D model generation and trust boundary |
| features/music-video-autonomous.md | One-prompt autonomous music videos: brief → lyrics → mood board → Suno song → production, optional checkpoints, and the music-video-autopilot scheduled task that turns Brain ideas into videos |
| features/music-video-temporal-evidence.md | Performance source provenance, synchronized playback and optional local temporal analyzer protocol |
| features/music-renderer-benchmarks.md | Technical and full-length listening evidence for local music renderer profiles |
| CONTRIBUTING.md | Dev setup (PostgreSQL required), code conventions |
| CLI_REVIEW_OUTCOMES.md | Reviewer tiers, provider pins and bounded, authenticated CLI health reports |
| UX_DESIGN_GUIDE.md | Admin workspace design specification: icon navigation, responsive layouts, disclosure, visual hierarchy, and redesign acceptance |
| UX_DESIGN_AUDIT.md | Representative UX audit and Jev/Performance pilot content maps |
| 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, and the unattended idle-gated automatic update |
| MANAGED_APP_UPDATES.md | Safe managed-app update default and the opt-in app lifecycle contract |
| MANAGED_APP_FORGE_ACCOUNTS.md | Running managed apps under a second GitHub account — ssh Host aliases and the per-app forgeAccount pin |
| 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 |
- Music Video private sharing copy — source-bound 720p downloads strictly under 100 MB, private local export and media queue lifecycle
- Music Video making-of export — local multi-variant planning packages, inventory previews, source planning retention and publication boundaries
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 · self-improvement-audits · agent-context · agent-skills · memory-system · claude-ollama · grok-box-local-mind · fleet-llm-host · mtplx · slotstream · dflash2 (DSpark vs DFlash 2, Ternary Bonsai 2 27B) · qwen38-rtx3090 (3090 bring-up) · sglang-qwen38 (SGLang Hopper/Blackwell evaluation) · prompt-manager
- Persistent Mind continuous play + local context — explore/invent playbook and mind-adjustable
numCtxclamps
Identity & self: digital-twin · identity-system · soul-system · privacy-center · post (insights design spike: plans/2026-06-03)
Knowledge: brain-system · untrusted messages and GitHub automation · scope adherence
Create: writers-room · fableloom · Eidoverse Worlds integration · Eidoverse music-video renderer · OpenWorld historical reference · sprite-export-contract · video-text-encoders · video-speed-profiles · video-render-batches · video-upscale
Comms & voice: beeper · messages-browser-send · openclaw-operator-chat (pre-build audit) · stacker-news · voice (Jev feasibility)
-
Music Video render-grade validation — synthetic encoder parity, visual references, and remaining generated-shot acceptance.
-
Explicit Music Video render pools — proposed initial shot placement and supplied-audio conditioning; final composition export remains local.
-
CoS agent permission posture — why unattended agents keep full-bypass instead of vendor auto-approve modes, and where stricter modes apply.
-
plans/ — dated design plans (
YYYY-MM-DD-<slug>.md), archived on approval before implementation. Historical records, not living docs. See provider connections and harnesses for stable executable routes, migration and management flows. -
decisions/ — ADRs (
YYYY-MM-DD-<slug>.md), e.g. the Postgres-as-primary-datastore decision and what may cross the federation layer (user-controlled federation, Privacy Center storage, federated visual prompts, conditioning crosses to an allowlisted peer, AI usage metrics federate on by default, Eidoverse guest chat, numeric PortOS quality federation, federated Eidoverse foundations), why H3 ships the draft-decode gates without an asset, and why closed-set decisions run on a local entailment model that abstains. -
research/ — investigation tools and incident write-ups (e.g. the H3 scene-continuity comparison, H3 vision precision investigation, mflux GPU-watchdog panic and 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.
-
Local managed-app visitor broker — opt-in credential provisioning, versioned nonhumanoid scope and host negotiation.
-
Agent API key — opt-in local credential and
scripts/portos-api.jsCLI for agents PortOS did not spawn. -
Tool-free model delegation — approved API workers, context packets, and advisory fidelity evaluation for Persistent Mind.