Product version: 1.1.8 — see root CHANGELOG.md and VERSION.
Hub for product, ops, and developer docs. Public name Oneirodex. Runtime env is ONEIRODEX_* only (ADR 0003). Package oneirodex/, Compose defaults oneirodex-*, preferred Hub image cephyrixzyth/oneirodex once published.
Root README.md includes badges, feature tour, screenshots (docs/assets/readme/), quick start, and troubleshooting.
| Audience | Go to |
|---|---|
| End users | user/getting-started.md · faq.md · troubleshooting.md · browser-play.md · desktop-companion.md · controllers-and-vr.md · translation-patches.md · free-games.md · social-and-voice.md · library-and-systems.md · preferences-themes.md · downloads.md |
| Operators / native install | runbooks/install-native.md — Linux · macOS · Windows installers, service units, upgrade; standalone preview with a bundled PostgreSQL (ADR 0011) |
| Operators / standalone to server | runbooks/standalone-move.md — move a standalone install onto a Docker/Unraid server: export, import into an empty database, verified row for row, saves re-encrypted |
| Operators / scan locations | runbooks/remote-scan-locations.md — ONEIRODEX_LIBRARY_ROOTS: NAS shares and extra disks, not just the server's own disk |
| Operators / single container, Unraid Community Apps, Docker Hub | runbooks/unraid-community-apps.md — one image with an embedded database, the CA template, release workflow, sidecar boundaries and submission checklist; challenge-solver-unraid.md — private TRAWL sidecar setup |
| Docker Hub listing | dockerhub-overview.md — release-stamped public overview synchronized after image publication |
| Operators / Unraid | runbooks/unraid-deploy.md · NAS-DEPLOY.md (portable checkout examples) |
| Operators / Docker Compose | runbooks/docker-compose-deploy.md — optional --profile livekit · --profile clamav · GPU art on a workstation: artwork-gpu-workstation.md |
| Operators / observability (optional) | runbooks/observability-profile.md — Prometheus stub; Admin Ops is default |
| Operators / LiveKit voice | runbooks/livekit-unraid.md |
| Households / VR runtime | runbooks/vr-byo-runtime.md — OpenXR runtime · OpenVR adapter · streamers · the wired USB-NCM link (0.7 ms / ~756 Mbps on a Quest 2) · tweaks as documentation, never distributed |
| Operators / achievements | runbooks/retroachievements.md — match ROMs to community achievement sets (opt-in key); nothing played in the browser unlocks |
| Maintainers / theme art | dev/theme-art-direction.md — what a theme is beyond a hue: room art, the accent sentinel, and how a generated backdrop lands |
| Operators / WebRetro cores | runbooks/webretro-cores.md · admin/webretro-core-clauses.md (non-commercial clauses — not counsel) |
| Operators / emulator BIOS | runbooks/emulator-bios.md — operator-supplied firmware; Admin scan/install, filenames only |
| Operators / ROM reference sets | runbooks/reference-sets.md |
| Operators / login rate limit (proxy) | runbooks/login-rate-limit-proxy.md |
| Operators / break-glass | runbooks/container-wont-start.md |
| Operators / security posture | Docker Compose deploy — Secure cookie defaults and chat storage limits · OIDC / SSO · Public ops: container-wont-start.md · themes-reset.md. Security audit notes are local-only. |
| Operators / release scrub (SCRUB-7) | runbooks/scrub-shipped-bundles.md |
| Maintainers / disk hygiene | runbooks/workspace-disk-hygiene.md — safe cache deletes vs WebRetro / .git |
| Maintainers / desktop installers | runbooks/local-installers.md — build Windows · macOS · Linux bundles without GitHub Actions; a .dmg still needs a Mac |
| Admins | admin/libraries-and-scans.md · members-and-invites.md (invites without email · local accounts) · privacy-data-handling.md (what the host stores · child ACL · optional outbound) · webretro-core-clauses.md (snes9x / genesis_plus_gx quotes — not counsel) · navigation.md (rail · top bar · Settings and Integrations sub-sections) · settings-modules.md · discover-sections.md (storefront shelves · layouts · timed events) · theme-fonts-and-images.md (fonts · batch artwork) · ops-summary.md · support-inbox.md · troubleshooting.md · themes-reset.md |
| Maintainers / architecture | dev/architecture.md · adr/README.md — nine accepted decisions, two superseded, and one proposal · CONTRIBUTING.md |
| Maintainers / database evaluation | adr/0012-evaluate-mariadb-before-engine-change.md — cost and compatibility gates; proposal only |
| CI gates (maintainers) | dev/ci-gates.md — current marker selection, explicit exclusions and coverage gate. Replaces ci-wishlist.md |
| Support triage (maintainers) | dev/ui-debt-log.md · dev/api-envelope-keeps.md |
| Test harness (maintainers) | dev/test-harness-2026-09-10.md — per-test SAVEPOINT isolation · savepoint-restart listener · database / slow markers. Older harness notes and the 2026-09-16 failure list are in dev/archive/ |
| Admin Jinja → React (maintainers) | dev/admin-jinja-inventory.md — which admin pages still render server-side, their handlers and APIs, and the port order (H-D.5) |
| Writing an API route (maintainers) | dev/pydantic-adoption.md — @validate_body request models · which routes are migrated · adoption backlog |
| Maintainers / browser engines | dev/browser-play-engines.md — WebRetro · Nostalgist/koin · EmulatorJS · webЯcade sidecar · runbooks/emulatorjs.md (bundled engine B) |
| OIDC / Authentik SSO | runbooks/oidc-sso.md, runbooks/oidc-authentik-unraid.md |
| API | openapi/openapi.json |
| How-to videos | media/video/howto/ — 20 narrated clips (AI voice, captions, WebVTT + transcripts), one worked example per feature, members + admins |
| README media | assets/readme/ · capture recipe CAPTURE.md |
User/admin guides describe implemented behavior; proposals and dated reports are not release verification. Local staging evidence is separate from production acceptance. Household PostgreSQL remains the supported server configuration; a serverless desktop migration is still a design/proof phase.
Operator host details, credentials, research exports, human responses and internal execution records belong in ignored local storage. Public docs use example addresses and paths. Never paste full database connection URLs into logs or support reports. Historical Git commits are not scrubbed by a working-tree documentation update.
docs/
README.md ← you are here
adr/ ← architecture decision records
user/ ← end-user guides + FAQ
admin/ ← admin guides
runbooks/ ← deploy & incident procedures
openapi/ ← HTTP contract
assets/readme/ ← root README icons & screenshots
dev/ ← engineering notes
*/archive/ ← Archive-status docs (see below)
Every doc carries > **Doc status:** Active | Reference | Archive under its title.
| Status | Meaning | Who reads it |
|---|---|---|
| Active | Maintained; matches current behavior | Agents and users, by default |
| Reference | Stable background (design notes, baselines) | When the topic comes up |
| Archive | Kept for provenance; superseded or finished | Nobody, unless directed. Agents skip archive/ folders and the links below |
Archive docs live in the area's archive/ folder, each with a README.md listing what is there and why. To archive a doc: git mv it into archive/, set its status line, add a row to archive/README.md, and fix inbound links.
Archives: dev/archive · superpowers/archive
Docker and cloud demo operations: Docker Compose deploy
| Surface | Value |
|---|---|
| Product (shipped today) | Oneirodex (public string) |
| Ops / code identifiers | Compose defaults oneirodex-*; npm @oneirodex/api-client; env ONEIRODEX_* only — ADR 0003 |
| Version | 1.1.8 |
| GitHub | cephyrixzyth/oneirodex |
| Containers | oneirodex-app (single-container or app role) · oneirodex-db (optional separate Postgres) |
| Optional voice | oneirodex-livekit (--profile livekit) |
| Python package | oneirodex |
| Default accent | #2fd67b (Style B+C glass) |