@ours.network/cowork 0.2.0

package/docs/02-installation.md

@@ -0,0 +1,18 @@
+# Installation
+
+Install the package so its `ours-cowork` executable is on your `PATH`, then verify the offline help:
+
+```sh
+ours-cowork --help
+ours-cowork docs
+```
+
+Open the local console with:
+
+```sh
+ours-cowork web
+```
+
+This starts the background daemon when it is absent, waits for `http://127.0.0.1:3052/`, and opens the system browser. Use `ours-cowork start` when no browser should open, or `ours-cowork serve` in the foreground while diagnosing startup. `ours-cowork --json web` verifies readiness and returns the URL without opening a browser.
+
+The localhost HTTP console has no authentication. Do not proxy, forward, or expose its port to another host. The daemon hosts its own room packets and does not require another local ours process.

package/docs/03-configuration.md

@@ -0,0 +1,18 @@
+# Configuration
+
+The default config file is `~/.ours-cowork/config.json`. It is a strict document:
+
+```json
+{
+  "version": 1,
+  "brokerUrl": "wss://broker1.ours.network",
+  "stateDir": "/absolute/private/path",
+  "rest": { "enabled": true, "port": 3052 }
+}
+```
+
+Environment overrides are `OURS_COWORK_CONFIG`, `OURS_COWORK_BROKER_URL`, `OURS_COWORK_STATE_DIR`, and `OURS_COWORK_REST_PORT`. The default console URL is `http://127.0.0.1:3052/`. Setting the REST port enables the loopback listener on that port. Explicitly setting `rest.enabled` to `false` disables both the web console and HTTP room RPC. Configuration, private files, and the complete state directory must remain owned by the daemon account with the modes enforced at startup.
+
+CLI room commands always use `management.sock`; they do not switch to REST.
+
+The HTTP listener is unauthenticated and restricted to the `127.0.0.1` interface. The console works through both `http://127.0.0.1:<port>` and `http://localhost:<port>`. Do not expose it through port forwarding, a reverse proxy, or a non-loopback bind.

package/docs/04-daemon-lifecycle.md

@@ -0,0 +1,18 @@
+# Daemon lifecycle
+
+Use these commands:
+
+```sh
+ours-cowork start
+ours-cowork status
+ours-cowork restart
+ours-cowork stop
+ours-cowork serve
+ours-cowork web
+```
+
+`start` detaches the standalone CLI in `serve` mode and waits for the authenticated control session on `management.sock`. `serve` keeps the supervisor in the foreground. Status asks the responding worker to prove that its supervisor capability handshake completed. Stop sends a session-bound shutdown request to that worker; the worker asks its own supervisor over their existing authenticated IPC channel to enter the same bounded shutdown path used for signals. The CLI never signals a numeric PID. Stop reports success only after the accepted control session disappears. An occupied socket without this protocol blocks stop/restart with invalid state and is left untouched.
+
+`web` uses the same safe start path: an already-running daemon is retained, an absent daemon is started, and readiness is checked with `GET /` before a browser opens. It never retries a room mutation. With `--json`, it returns the URL with `opened: false` and has no browser side effect. If HTTP is explicitly disabled, `web` exits `1` and explains how to enable it.
+
+Exit codes are stable: `0` success, `1` web console disabled, `2` CLI usage, `3` not found, `4` invalid state or parameters, `5` unauthorized, `6` daemon unavailable, and `7` internal failure. With `--json`, stdout contains exactly one JSON value and stderr stays empty. This includes foreground `serve`: supervised worker output is suppressed, and its clean or failed terminal status becomes that one JSON result.

package/docs/05-room-workflow.md

@@ -0,0 +1,17 @@
+# Room workflow
+
+Create a room and inspect its host-owned identity:
+
+```sh
+ours-cowork room create --goal "Ship the fix" --briefing "Review evidence first"
+ours-cowork room list
+ours-cowork room show <room-id>
+```
+
+In the web console, choose Create room, enter Goal and Briefing, and submit once. The created room is selected automatically and its Invite panel opens. Add invitation requirements one at a time; the UI does not combine room creation and invites into a fabricated atomic operation.
+
+Update mutable mission fields with `room settings`. Inspect admitted seats with `room participants`. A room activates only when its recorded invite requirements are satisfied. Roles are display labels; participant identity CIDs, not roles, are authorization keys.
+
+Close with `ours-cowork room close <room-id>`. Close is forward-only and removes live room packet state while retaining the local archive. Archive deletion is a separate explicit operation described in the limitations topic.
+
+Every web action has an equivalent CLI fallback in the room commands above and in the invites and messaging topics.

package/docs/06-invites.md

@@ -0,0 +1,15 @@
+# Invites
+
+Create one-time or public invites:
+
+```sh
+ours-cowork room invite <room-id> --role reviewer
+ours-cowork room invite <room-id> --mode public --role observer --min-accepts 2
+ours-cowork room revoke <room-id> <invite-id>
+```
+
+The invite blob is returned only in an invite or recovery receipt. Store or transmit that receipt as needed; durable room metadata intentionally does not store the blob.
+
+The web console shows each returned invite secret once in a blocking receipt. Copy and save it before choosing Done: closing the receipt discards the browser copy. The secret is not placed in the URL, browser storage, logs, or room metadata. One-time and public receipts use the same handling.
+
+After restart, `room recover <room-id>` can mint replacements for durable invites marked as needing replacement. Preserve each returned replacement blob before confirming its exact old/new pair with `room recover <room-id> --confirm <old-invite-id> <new-invite-id>`. The web recovery receipt names both IDs and requires the same confirmation. Each invocation makes exactly one local management request.

package/docs/07-messaging-history.md

@@ -0,0 +1,24 @@
+# Messaging and history
+
+Post in the room's host-owned voice:
+
+```sh
+ours-cowork room message <room-id> --text "Decision recorded"
+```
+
+The daemon assigns authorship. Author, identity, display-name, and role flags are rejected for this command.
+
+An option value that begins with `--` uses the unambiguous inline form, for example `--text=--help` or `--text=--json`. A bare `--` ends option parsing for positional values. Only an exact standalone `--json` before `--` selects global JSON output; text inside `--text=VALUE` is never consumed as a global flag.
+
+Read the ordered archive with numeric paging:
+
+```sh
+ours-cowork room history <room-id>
+ours-cowork room history <room-id> --after 40 --limit 20
+```
+
+Participant messages are accepted only from durable seats in an active room. History records include messages and the durable relay intent/result trail used for restart recovery.
+
+The web console projects participant and room-authored messages plus the briefing into Communication. Relay, recovery, close, and failure records are excluded from chat and shown in Events; Archive retains the complete ordered record stream. Messages appear only after the authoritative history refresh observes them.
+
+Version one polls rather than receiving pushed updates: the room list refreshes every five seconds, while the selected room, participants, and history refresh every two seconds. Polling pauses in a hidden tab, coalesces overlap, and refreshes after confirmed mutations. CLI history remains the fallback when a browser is unavailable.

package/docs/08-backup-restore.md

@@ -0,0 +1,7 @@
+# Backup and restore
+
+Stop the daemon before taking a backup. A live copy can split metadata, append-only archive records, packet state, and filesystem durability boundaries across different moments.
+
+Back up the complete state directory as one unit, preserving ownership and file modes. Do not select only `rooms/` or only room JSON files.
+
+For restore, stop the daemon, replace the complete state directory with the complete backup, restore its original owner and `0700`/`0600` permissions, and then start the daemon. Do not merge individual room directories from different snapshots. Restore to a compatible package version and verify `ours-cowork status` plus representative `room show` and `room history` calls.

package/docs/09-service-management.md

@@ -0,0 +1,12 @@
+# Service management
+
+Install a per-user boot service with:
+
+```sh
+ours-cowork install-service
+ours-cowork uninstall-service
+```
+
+Linux uses `ours-cowork.service` under the systemd user directory. macOS uses the `network.ours.cowork` launchd agent. Both definitions execute the installed cowork CLI directly in `serve` mode and preserve the effective broker, state directory, and optional REST port settings.
+
+Installation rejects service values containing NUL, newline, carriage return, or other unsafe control characters before creating or replacing a definition. It then stops a manually detached daemon through the authenticated control session before the service takes ownership. Uninstall first requires systemd to disable/stop the unit or launchd to unload the agent. If that operation fails, uninstall reports failure and retains the service definition for inspection or retry. After a successful unload, uninstall removes only the service definition; it retains all cowork configuration, room archives, and packet state. Remove data only through the explicit closed-room deletion command or a separate, deliberate host-data operation.

package/docs/10-limitations.md

@@ -0,0 +1,13 @@
+# Limitations
+
+- The retained archive is plaintext on this host. Filesystem ownership and `0700`/`0600` modes limit local access, but the archive is not encrypted at rest by ours-cowork.
+- Invite secrets exist only for the process lifetime that minted them and in the receipt returned to the operator. Durable room metadata stores descriptors, not invite blobs. A prior one-time or public secret is not reconstructable; a durable invite marked as needing replacement requires explicit recovery to mint a new secret.
+- Relay recovery is at-least-once. A crash after transport acceptance but before the durable result can retry a send, so participants may observe duplicates. The system does not provide exactly once relay semantics.
+- The host records transport acceptance and failures; it does not observe delivery, reading, or remote processing. A successful operator command must not be interpreted as participant receipt.
+- Backups require a stopped daemon. Back up and restore the complete state directory as one unit, preserving ownership and modes; partial or live copies are unsupported.
+- Service uninstall retains data. It removes the systemd or launchd definition, not configuration, archives, room metadata, or packet state.
+- Closing and deleting are separate. First close the room explicitly with `ours-cowork room close <room-id>`. Only a closed room can then be deleted with `ours-cowork room delete <room-id> --yes`.
+- Confirmed deletion removes the retained archive and metadata from this host only. It does not claim remote purge, backup erasure, key wipe, or secure erase.
+- The web console and HTTP room RPC have no authentication. They bind only to `127.0.0.1` and must not be forwarded, proxied, or exposed remotely.
+- Web updates use periodic polling rather than push. A view can lag daemon state until its next refresh; confirmed mutations trigger an immediate refresh.
+- Browser state is transient apart from the selected-room URL hash. Invite receipts disappear when closed and are not recoverable from browser storage.

package/docs/11-web-console.md

@@ -0,0 +1,30 @@
+# Web console
+
+Open the production console with:
+
+```sh
+ours-cowork web
+```
+
+The command safely starts the daemon only when it is absent, waits for `GET /` readiness, then opens `http://127.0.0.1:3052/`. `ours-cowork --json web` performs the same readiness checks but returns `{ "url": "http://127.0.0.1:3052/", "opened": false }` inside the standard JSON result without opening a browser.
+
+The console and HTTP room RPC have no authentication. They bind only to `127.0.0.1`; both the `127.0.0.1` and `localhost` browser URLs are accepted. Do not use port forwarding, a reverse proxy, or another mechanism to expose this listener to other hosts.
+
+## Room setup
+
+1. Choose Create room and enter the Goal and Briefing.
+2. Submit once. The new room is selected and its Invite panel opens.
+3. Add one invitation requirement at a time. Choose one-time or public mode and set the minimum acceptances for a public invite.
+4. Copy every invite from its blocking receipt before choosing Done. The secret is shown once and is not retained in browser storage, the URL, logs, or durable room metadata.
+
+The room activates after its durable invitation requirements are satisfied. Participants shows admitted identities and their invite roles.
+
+## Communication and records
+
+Communication is the human-readable chat: room and participant messages plus the mission briefing. Messages are not inserted optimistically; a sent message appears after the daemon's ordered history includes it. Events contains relay, recovery, close, and failure details. Archive contains the complete sequence-numbered stream and can show earlier loaded rows.
+
+Room list and connection health poll every five seconds. The selected room, participants, and new history poll every two seconds. Polling pauses while the page is hidden, coalesces overlapping cycles, and refreshes after confirmed mutations. Version one does not use push updates.
+
+Close requires the room title or exact ID and leaves the plaintext local archive. Delete is available only after close, requires the exact room ID, and removes local state only as described in the limitations topic.
+
+Every operation remains available through `ours-cowork room ...` when no browser is available. Use `ours-cowork docs rooms`, `ours-cowork docs invites`, and `ours-cowork docs messaging` for the CLI workflows.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@ours.network/cowork",
+  "version": "0.2.0",
+  "description": "Standalone daemon for durable ours mission rooms.",
+  "type": "module",
+  "license": "FSL-1.1-Apache-2.0",
+  "bin": {
+    "ours-cowork": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "docs/*.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "compile:mufl": "scripts/compile-mufl.sh",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:web": "tsc -p web/tsconfig.json --noEmit",
+    "test": "node --import tsx --test --test-concurrency=1 tests/*.test.mjs",
+    "test:web": "vitest run",
+    "test:browser": "node --test tests/browser-smoke.test.mjs",
+    "test:release": "node --test tests/static-gates.test.mjs"
+  },
+  "dependencies": {
+    "@adapt-toolkit/sdk": "0.10.12",
+    "@adapt-toolkit/sdk-native": "0.10.12",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@adapt-toolkit/broker": "0.10.12",
+    "@adapt-toolkit/mufl": "0.10.12",
+    "@testing-library/jest-dom": "6.6.3",
+    "@testing-library/react": "16.1.0",
+    "@testing-library/user-event": "14.5.2",
+    "@types/node": "^20.14.0",
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "@vitejs/plugin-react": "4.7.0",
+    "esbuild": "0.25.0",
+    "jsdom": "25.0.1",
+    "playwright-core": "1.60.0",
+    "tsx": "4.23.1",
+    "typescript": "^5.5.4",
+    "vite": "6.4.3",
+    "vitest": "3.2.6"
+  }
+}