uDOS v3.0.1 — Local-first demo (planning cut)

Name: uDos expands to Universal Device Operating Surface. The capital D is intentional (uDos, not udos or uDOS in new copy—see docs/dev-process-v4.md).

GitHub: https://github.com/fredporter/uDosGo — clone locally as ~/Code/uDosGo/ (family convention).

Integration release line: VERSION (0.1.0) + CHANGELOG.md describe Round 9 — integration tests, ops endpoints (/health, /ready, /metrics), Docker Compose under docker/, backup/restore scripts, monitoring templates, and doc set under docs/ (see docs/integration-architecture.md). This is demo / staging readiness, not a full production warranty.

Repo meta / dev standard: root package.json version 4.x tracks the family dev process (see docs/dev-process-v4.md). v3.0.1 below is the planning / demo release name for this integration monorepo — not the same axis as UniversalSurfaceXD’s release line or uDosDev governance versioning.

v3.0.1 is the first public-facing planning release for a single, runnable local loop: ThinUI submits and inspects work, Hivemind plans and routes it, Host executes and persists it, WordPress provides local identity, privacy, and restricted pages, and everything lands on a mounted vault/workspace.

This repository is the v3 monorepo target. Implementation may start empty; the planning pack lives under docs/ and packages/schemas/.

Family v4 — Cursor / VS Code: open uDosGo.code-workspace at the repo root (simple ../ paths to ~/Code/ siblings). The same folder set is also available as ~/Code/uDosGo.code-workspace when you open the workspace file next to your sibling clones (no ../ in paths). Focused lanes (same repos, paths from workspaces/): workspaces/README.md — uDOS-v4.code-workspace, Linkdown-v4.code-workspace, uMacDown-v4.code-workspace.

One sentence

A local-first orchestration demo where ThinUI submits and inspects work, Hivemind plans it, Host executes it, WordPress handles identity/privacy/restricted local pages, and all outputs persist to a mounted vault/workspace.

What ships in v3.0.1 (demo)

• Host — persistent node, storage root, HTTP API, job runner, event log, WordPress runtime wiring, health.
• Hivemind — feed intake, 4-role orchestration (Scout → Planner → Maker → Reviewer), provider routing, budget awareness, events via Host.
• ThinUI — Feed, Task graph/queue, Output/event log, manual triggers, links to restricted WP pages where needed.
• WordPress (localhost) — login, restricted pages, privacy export/erase hooks, Empire contact ↔ WP user bridge via udos-empire-local.
• Storage — /udos-data layout: vault, spool, events, exports, wordpress, backups.

Not the whole uDOS family. Not the full product vision. One clean loop.

Planning documents

Full index: docs/README.md — sections for start-here, system design, specifications, style guide, delivery, schemas.

Schemas (first draft)

JSON Schema drafts live in packages/schemas/: usxd-surface (usxd/0.1), feed, task, event, contact, user-link, provider-policy. Example surfaces: examples/usxd-surface-canonical.example.json, examples/usxd-surface-minimal.example.json (npm run validate:usxd checks all USXD surfaces under examples/).

Relation to sibling repos

The broader uDos family workspace may keep historical modules (uDOS-host, uDOS-thinui, …). v3.0.1 consolidates the demo into this monorepo shape first; split back to separate repos only after the demo is solid.

See also: ../uDosConnect/uDosDev/docs/v3-system-brief.md (bootstrap brief; sibling under ~/Code/).

Companion: UniversalSurfaceXD (design + interchange)

Portable surface vocabulary, interchange JSON, Figma handoff, and the browser UX designer live in the open-source repo github.com/fredporter/UniversalSurfaceXD (MIT). Optional local checkout: sibling ../UniversalSurfaceXD under ~/Code/ (same level as this repo). This monorepo is the runnable uDos integration; UniversalSurfaceXD is the composer + lab + interchange side. Keep packages/schemas and ThinUI copy aligned with UniversalSurfaceXD/interchange/ when contracts change.

Quick start

Use docs/QUICKSTART.md for complete first-time installation and setup.

Fast path:

npm install
npm run doctor
npm run launch:open

Round 9 checks: make test-all (workspace unit tests + integration), npm run health (Host liveness), docker compose -f docker/docker-compose.yaml config (validate stack file). Contributor setup: ./scripts/dev-setup.sh — see CONTRIBUTING.md.

• Host: http://127.0.0.1:8787
• ThinUI: http://127.0.0.1:5173

Optional WordPress (steps 8-9):

npm run wp:up
npm run demo:wp-bootstrap
npm run demo:wp-link

Convenience launchers:

• macOS: uDOS-Dev.command / uDOS-Dev+WP.command
• Windows: uDOS-Dev.cmd / uDOS-Dev+WP.cmd

Dev / prod without launchers

npm run dev            # Host + ThinUI (watch) — same as launch after install
npm run start          # build, then Host (node) + ThinUI (vite preview) — no watch
npm run host:dev       # Host only (tsx watch)
npm run thinui:dev     # ThinUI only
npm run host:start     # Host only (run `npm run build` first)
npm run demo:seed      # POST gold-path input to Host (needs Host running); --dry-run supported
npm run demo:seed:inbox   # POST inbox-thread sample → `thread-{id}.md` vault stem
npm run build          # sdk + hivemind + host + thinui (starts with validate:usxd)
npm run validate:usxd:verbose  # USXD validation + log skipped JSON under examples/

WordPress (Docker, optional): persistent tree matches Host at ./.udos-data/wordpress.

npm run wp:up          # WordPress http://127.0.0.1:8080 + MySQL (see infra/docker/README.md)
npm run wp:down

Requires Docker. Fast path (no browser wizard): after npm run wp:up, run npm run demo:wp-bootstrap then log in as Subscriber demo (password printed to the terminal; also in demo/.wp-demo.env). For the contact link, run npm run demo:wp-link. Alternatively, complete the WordPress install wizard in the browser and activate uDOS Empire Local under Plugins.

Bridge: Host probes WordPress at UDOS_WP_BASE_URL (default http://127.0.0.1:8080) via GET /api/v1/bridge/wordpress → GET /wp-json/udos-empire/v1/health. ThinUI shows the JSON when VITE_UDOS_WP_URL is set (see apps/thinui/.env.development).

Note: @udos/thinui depends on @udos/sdk via file:../../packages/sdk for broad npm compatibility.