yothere 1.5.2__tar.gz

yothere-1.5.2/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.pyc
+.venv/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+# runtime state (never committed)
+threads/
+threads-archive/
+*.log
+relay-board.html
+ping-state.json
+runner.lock

yothere-1.5.2/CHANGELOG.md

@@ -0,0 +1,227 @@
+# Changelog
+
+All notable changes to yothere (formerly `relay-cockpit`). Format loosely follows
+Keep a Changelog; versions follow semver.
+
+## [Unreleased]
+
+### Changed
+- **RENAME: the package, module, and PyPI distribution are now `yothere`**
+  (formerly `relay-cockpit`). Concretely: the import path `relay.*` -> `yothere.*`
+  (`src/relay/` -> `src/yothere/`); the PyPI dist name `relay-cockpit` -> `yothere`
+  (`pip install yothere`, extras `[voice]`/`[web]`/`[mcp]`/`[llm]`/`[postgres]`
+  unchanged); the MCP console script `relay-mcp` -> `yothere-mcp` and the MCP
+  server registration name `relay` -> `yothere`.
+- **CLI verb: `yothere` is now the canonical command (`yothere <verb>`); `relay`
+  is kept as a deprecated back-compat alias.** Both console scripts invoke the
+  same CLI, so `yothere init`/`yothere board`/... and the old `relay ...` forms
+  both work; help/usage and the printed next-step hints now say `yothere`.
+- **Default home: `~/.yothere`** (was `~/.relay`) when neither `YOTHERE_HOME` nor
+  `RELAY_HOME` is set. For back-compat, an existing `~/.relay` is used as a
+  deprecated fallback when `~/.yothere` does not yet exist, so a host running the
+  old default is not stranded. Any explicit `YOTHERE_HOME`/`RELAY_HOME` still
+  overrides. The `relay.env` file and the `com.*.relay-*` launchd/systemd unit
+  names are unchanged — a running host that pins `RELAY_HOME` keeps its wiring.
+- **Env vars: `YOTHERE_*` is the going-forward namespace; every legacy `RELAY_*`
+  name still works.** A back-compat shim (`yothere.envcompat`) mirrors the two
+  prefixes bidirectionally at package import (over `os.environ`) and inside the
+  env-file parsers, so a host still exporting `RELAY_HOME`, `RELAY_NOTIFIER`, etc.
+  is unaffected. The legacy `RELAY_*` names are supported for at least this
+  release; new configs should prefer `YOTHERE_*`.
+- **SECURITY-RELEVANT DEFAULT: `claude`-harness worker turns now run
+  `--permission-mode bypassPermissions` by default** (full capability), contained
+  by a relay-owned PreToolUse send-gate injected via `--settings` (denies
+  outward sends: send scripts, `git push`, HTTP/mail egress with a body, MCP
+  send tools; plain GET reads stay allowed). Self-hosters upgrading get this
+  posture change; opt out with `worker_permission_mode: default` in vt config or
+  `RELAY_WORKER_PERMISSION_MODE=default`. The gate fails CLOSED: if its settings
+  file cannot be written, the turn drops `--permission-mode` entirely. Hosted
+  tenants are clamped to `default` unless the operator sets
+  `RELAY_HOSTED_FULL_CAPABILITY=1`. The gate is best-effort argv inspection
+  (defense-in-depth), not an adversarial sandbox.
+
+Deferred, explicitly out of v1:
+- Brain-side token lifecycle: issue / rotate / revoke / scope.
+- Publish to PyPI (wheels currently ship via GitHub Releases).
+
+## [1.5.1] — 2026-07-01
+
+Version-integrity release. No runtime code changes.
+
+### Fixed
+- **Wheel version metadata** — the v1.5.0 tag was cut without bumping
+  `pyproject.toml`, so the published "v1.5.0" wheel self-reports 1.4.0. This
+  release restores tag == package version (1.5.0 is skipped as ambiguous).
+
+### Added
+- **`relay init` — zero-key first run** (`relay.cli`, new `relay.demo_brain`):
+  one idempotent command that creates the `RELAY_HOME` layout, detects any
+  existing brain (env url / `brains.yaml` / `claude` CLI), seeds a commented
+  `brains.yaml` with a bundled demo brain when the file doesn't exist (never
+  overwrites anything), and prints the exact next commands. `relay init --demo`
+  starts the bundled Brain Protocol v1 demo brain on a free localhost port and
+  drives one canned thread through the real runner -> worker -> brain path
+  (blocked -> reply -> done), filling the board with no API key.
+- Remote-brain `done` turns now also write `summary` (not just `last_result`),
+  so a remote brain's final answer actually renders on the board / `relay show`.
+- **Release guard** in `.github/workflows/release.yml`: the job fails early when
+  the pushed tag does not match the `pyproject.toml` version, so a metadata
+  mismatch can never publish again.
+- `docs/RELEASING.md` — the release checklist (bump + changelog + tag + verify).
+- Tester onboarding guide (`docs/ONBOARDING.md`) + tester-feedback issue
+  template (#12; merged after the v1.5.0 tag, so first shipped in this wheel).
+
+## [1.5.0] — 2026-06-30
+
+Customer-cockpit Session 4b: the locally-proven self-onboarding cockpit becomes a
+deployable single-box hosted service (Fly.io), with tenant agents advancing
+against a hosted brain over the Brain Protocol. (#11)
+
+> Note: the published v1.5.0 wheel self-reports version 1.4.0 (the tag was cut
+> without a `pyproject.toml` bump) — fixed in 1.5.1.
+
+### Added
+- **Postgres-backed AuthStore** (`[postgres]` extra) — a one-file driver seam in
+  `relay.voicecall.auth`: `DATABASE_URL` set → Postgres via lazily-imported
+  psycopg; unset → SQLite, byte-identical to before. Schema self-initialises on
+  first connect; public method surface unchanged.
+- **Per-tenant hosted brain** — accounts gain nullable `brain_url`/`brain_token`
+  + `auth.tenant_brain()` (per-account override, else deploy-wide
+  `RELAY_HOSTED_BRAIN_URL`/`TOKEN`); the tenant supervisor injects
+  `RELAY_REMOTE_BRAIN_URL`/`TOKEN` per tenant so each runner's `remote` harness
+  advances with that tenant's token.
+- **`relay.web` + `config.web_config()`** — boot the FastAPI cockpit without the
+  Twilio/Gemini required-keys gate (voice degrades to "unavailable"); lean
+  `[web]` extra (FastAPI/uvicorn only, no media stack).
+- **Container + deploy**: `deploy/{Dockerfile,entrypoint.sh,fly.toml}`
+  (python:3.12-slim, tini, one always-on machine, durable `/data` volume) +
+  `docs/DEPLOY-fly.md` runbook.
+- CI: dedicated Postgres parity job (`tests/test_auth_pg.py`) + off-mode parity
+  suite (`tests/test_offmode_parity.py`) locking the local-first invariant.
+
+## [1.4.0] — 2026-06-30
+
+### Added
+- **Opt-in keyless tailnet Connect (`RELAY_TRUST_TAILNET_IDENTITY=1`)** — the
+  bearer-gated cockpit routes accept the verified `tailscale-user-login` header
+  injected by `tailscale serve`, so a tailnet browser connects without the token
+  in the URL. Spoof-safe: the identity is trusted only when no cloudflare edge
+  marker (`cf-ray`/`cf-connecting-ip`) is present, so the public cloudflared
+  tunnel can never forge it. Default (flag unset) is byte-identical:
+  fully bearer-gated. (#10)
+
+## [1.3.0] — 2026-06-30
+
+Customer-cockpit Session 4: self-onboarding, local-first. A stranger redeems an
+invite, signs up, and is walked through a guided first task — zero terminal
+steps. All surfaces are hosted-mode-only; off mode stays byte-identical.
+
+### Added
+- **Self-onboarding (hosted mode)** — invite-gated `GET/POST /signup` +
+  guided `GET/POST /onboarding` (same spawn front door as `/dispatch`); invites
+  table with atomic single-use consume, per-account `budget_usd`, and a
+  `relay invite create` CLI. Both routes 404 in off mode. (#8)
+- **Runner-per-tenant supervisor** (`relay.tenant_supervisor`) — reconciles one
+  `relay.runner loop` per tenant with per-tenant `RELAY_HOME`/`RELAY_USER` and a
+  daily cost cap (`RELAY_DAILY_COST_CAP_USD`), so non-Phil tenants' threads
+  actually advance. (#8)
+- **MCP server surface** (`relay.mcp_server`, `relay-mcp` console script, `[mcp]`
+  extra) — drive a fleet from any MCP client over stdio: `spawn_thread`, `board`,
+  `reply`. Wraps the same spawn/store/reply front doors as the CLI/cockpit; the tool
+  logic is SDK-free `_*_impl` helpers so it imports + tests without `mcp` installed.
+  Single-user/local (drives `~/.relay`); orthogonal to the hosted cockpit. (#7)
+
+## [1.2.0] — 2026-06-30
+
+Customer-cockpit Session 3: real auth + multi-tenant isolation, gated entirely
+behind a deployment-mode flag so local single-user use is byte-identical to before.
+
+### Added
+- **Hosted mode (`RELAY_AUTH_MODE=hosted`)** — a Python-native, stdlib-only auth
+  layer (`relay.voicecall.auth`): scrypt password hashing, opaque session token in
+  SQLite (`RELAY_AUTH_DB`, WAL + busy_timeout, separate from fleet state), login
+  lockout, KDF-on-unknown-user (no existence timing leak), token rotation on login,
+  and a `Secure` cookie tied to the mode (not the request URL).
+- **Per-tenant isolation** — each account is scoped to its own `~/.relay-<tenant>`
+  home under `RELAY_TENANTS_ROOT`. The cockpit resolves the tenant per request and
+  threads an explicit `root=` into spawn/store/fleet_state — never the process
+  singleton — so two logins see two isolated fleets with no cross-tenant read.
+- `GET/POST /login` + `POST /logout` routes and a brand-consistent login page; the
+  workspace chip now renders the logged-in account (dynamic; off mode = static).
+- `fleet_state.load_fleet(root=…)`, `config.auth_mode`, `config.tenants_root`,
+  `config.auth_db`.
+
+### Changed
+- In hosted mode the tailnet/loopback public carve-out is removed: every route
+  except `/healthz` + `/login` requires a session. Off mode is unchanged (the gate
+  short-circuits to the original path; no auth/tenant code runs).
+
+## [1.1.0] — 2026-06-30
+
+Architecture-audit pass: re-applied the 84-finding relay audit (originally landed
+in the bob monorepo) against the package layout. Net ~1250 lines removed, runner
+reliability hardened, voicecall teardown made deterministic, test suite raised to
+231 (relay) + 177/3-skip (voicecall).
+
+### Removed
+- **The dead offline router + feedback-learning loop** — `router.py`,
+  `router_learn.py`, and the `relay feedback` CLI subcommand are deleted (the
+  cascade that called `router.decide()` was retired conceptually but never removed;
+  it never ran in production). The live spawn-path classifier is `scope.py`, which
+  is unaffected.
+- **`attention.should_ping` / `push_pings` / `maybe_llm_rerank`** and the divergent
+  fleet-ping interval constant — the live nudge gate lives in the runner; the
+  attention copies were dead and drifting.
+- Dead voicecall-brain probes (`connect()`/`hello()`), `dispatch` GREETING/GOODBYE
+  constants, and `scope.log_case`'s unwired logging sink.
+
+### Fixed (reliability)
+- **Stale-429 false hold** — the 429 scan is now scoped to the current turn, so a
+  prior turn's rate-limit no longer falsely holds a healthy thread.
+- **Silent cost-ledger overspend** — a record_cost write failure now emits a
+  rate-limited nudge / stderr signal instead of being swallowed, so the daily cap
+  can't be defeated with zero signal. The cost ledger is compacted by maintenance.
+- **Voicecall teardown leaks** — `SessionManager.cancel_all()` cancels in-flight
+  bg sessions and releases `worker.lock` fds on call-end/evict; `evict()` awaits
+  the cancelled runner; the sessions dict is bounded; `config.load` raises
+  `ConfigError` instead of `SystemExit`.
+- Quiet-hours honors the configured timezone (defensive `getattr` for callers
+  without a `timezone` field); PTT mode gets the transcribe watchdog; `listen`
+  uses `presence.runner_alive()` instead of the false-green pgrep probe.
+- `send_nudge` extracted into `relay.notify` so the watchdog stops importing the
+  whole runner engine.
+
+### Changed
+- `RELAY_THREADS_DIR` is `mkdir`-guarded; `runner.lock` records its PID; the
+  needs-eyes nudge count aligns to the freshly-changed subset; `_WAKE` regex and
+  the fleet state vocabulary are each single-sourced.
+
+## [1.0.0] — 2026-06-29
+
+First standalone release, extracted from the bob monorepo into `phios-ai/relay`.
+
+### Added
+- **Pip-installable package** `relay-cockpit` with the `relay` console script and
+  a `[voice]` extra for the Gemini-Live surface, `[llm]` for the optional routing
+  tiebreak.
+- **`relay.config.settings`** — one env-overridable config rooted at `~/.relay`,
+  replacing the bob monorepo path anchoring.
+- **`relay.thread_model`** — the de-vendored dir-per-thread Thread model, now a
+  first-class package (the old exec-based import landmine is gone).
+- **Brain registry** (`relay.brain.registry`) — config-driven named brains in
+  `~/.relay/brains.yaml`, so a thread can target a local Claude, a ubob daemon, or
+  any remote Brain-Protocol endpoint by name.
+- **Per-user scoping** (`RELAY_USER`) — a shared fleet no longer cross-shows
+  another person's threads.
+- **`sessionStatus`** — an additive Brain-Protocol v1 method + a remote fleet
+  source, so a client with no local thread filesystem (phone, web, another
+  machine) can render the board by querying the brain. This is the "use it
+  online" path.
+
+### Changed
+- The headless worker is spawned via `python -m relay.worker`; the notifier,
+  launchd label, and all paths are config seams.
+
+### Notes
+- Safety/permissions and real cost budgets live on the brain side for remote
+  brains — see [SECURITY.md](SECURITY.md).

yothere-1.5.2/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to yothere
+
+yothere is a shipped product that other systems (bob, SIDES) depend on. Two people
+build it, and neither should be able to break `main` alone. This is our working
+agreement.
+
+## Golden rule
+
+**Never commit to `main` directly.** Every change flows:
+
+```
+branch  →  pull request  →  the OTHER founder approves  →  CI green  →  merge
+```
+
+`main` is protected on GitHub: you cannot merge without one approval, and you
+cannot approve your own PR. So the review is mutual by construction. Either Oscar
+approves Phil's change, or Phil approves Oscar's, before more parts of the product
+get changed.
+
+## What needs a real review vs a glance
+
+Everything goes through a PR. How hard the reviewer looks depends on the change.
+
+**Bigger changes — read the whole diff.** Anything touching:
+- `src/yothere/` core (runner, watchdog, fleet, brain, auth, registry)
+- the brain protocol (`docs/brain-protocol-v1.md` and the wire code that implements it)
+- `deploy/` (Dockerfile, entrypoint, fly config)
+- DB schema, migrations, or the auth store
+- `.github/workflows/` (CI/release)
+- `pyproject.toml`, dependencies, or anything that cuts a release/tag
+
+For these, the reviewer reads the diff, checks that tests cover the change, and
+explicitly flags any breaking change to the Brain Protocol or to a consumer
+(bob, SIDES).
+
+**Trivial changes — fast-approve on sight.** Docs, comments, CHANGELOG, README,
+test-only additions. Still a PR (the gate always applies), but the review is a
+quick look.
+
+## Before you request review (author)
+
+- Tests pass locally:
+  ```bash
+  PYTHONPATH=src python tests/relay_test.py
+  # plus the feature suites you touched, e.g.
+  PYTHONPATH=src python tests/test_registry.py
+  ```
+- CHANGELOG updated if the change is notable.
+- PR is scoped small. Split unrelated changes into separate PRs.
+- Fill in the PR template (it loads automatically).
+
+## When you review (reviewer)
+
+Ask: does this break the Brain Protocol or another consumer? Are there tests?
+Are migrations safe and reversible? Then **Approve**, **Request changes**, or
+**Comment**. Resolve all conversations before merge (the gate requires it).
+
+## Merging
+
+Squash-merge. The branch is auto-deleted after merge. `main` must be up to date
+first (GitHub enforces this).
+
+## Emergency escape hatch
+
+Admins can bypass the gate (`enforce_admins` is off) — this exists **only** for a
+genuine emergency: prod is down, or a live security issue. If you bypass, you must:
+
+1. Post the diff to the other person immediately, and
+2. Open a retroactive PR the same day so the change is on the record.
+
+The escape hatch is never for skipping review out of impatience. If you are
+tempted to use it because the other person is asleep, wait or ping them.
+
+## Branch naming
+
+`feat/…`, `fix/…`, `chore/…`, `docs/…`.

yothere-1.5.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phil Wenger and Oscar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yothere-1.5.2/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: yothere
+Version: 1.5.2
+Summary: yothere — an ambient-agent cockpit: a voice loop + fleet board that drives any agent brain over the Brain Protocol and tells a human when to look.
+Project-URL: Homepage, https://github.com/phios-ai/yothere
+Project-URL: Repository, https://github.com/phios-ai/yothere
+Author: Phil Wenger, Oscar
+License: MIT
+License-File: LICENSE
+Keywords: agents,ambient-agent,claude-code,cockpit,fleet,voice
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: pywebpush>=1.14
+Requires-Dist: pyyaml>=6
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: pyflakes>=3; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.89; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: voice
+Requires-Dist: deepgram-sdk>=3.7; extra == 'voice'
+Requires-Dist: fastapi>=0.115; extra == 'voice'
+Requires-Dist: google-genai>=1.75; extra == 'voice'
+Requires-Dist: pipecat-ai-small-webrtc-prebuilt>=2.5; extra == 'voice'
+Requires-Dist: pipecat-ai[deepgram,google,silero,webrtc]>=1.4; extra == 'voice'
+Requires-Dist: twilio>=9.0; extra == 'voice'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'voice'
+Requires-Dist: wsproto>=1.2; extra == 'voice'
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115; extra == 'web'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'web'
+Requires-Dist: wsproto>=1.2; extra == 'web'
+Description-Content-Type: text/markdown
+
+# yothere
+
+**An ambient-agent cockpit.** yothere is the *interface* for long-running agents: a
+fleet board, a voice loop, and a headless runner that advances work and tells a
+human *when to look*. The agent that actually does the work, the **brain**, is
+anything you point yothere at, over one published wire contract:
+[`docs/brain-protocol-v1.md`](docs/brain-protocol-v1.md) (WebSocket + JSON-RPC 2.0).
+
+yothere is harness-agnostic by design. The same cockpit drives:
+
+- **Claude Code** running locally (`claude -p` per thread),
+- **ubob** or any model-agnostic harness over its WebSocket daemon,
+- a **remote brain** over the internet (a hosted sprite, a teammate's stack, a
+  work platform) — anything that speaks the Brain Protocol.
+
+It runs the same whether the brain is on this machine or behind a `wss://`
+endpoint, so you can start a thread at your desk and watch it from your phone.
+
+> **New here?** Start with [`docs/ONBOARDING.md`](docs/ONBOARDING.md): a 20-minute
+> walkthrough from install to a real task advancing, plus how to send feedback.
+
+## Why it exists
+
+A fleet of agents working in the background is only useful if a human knows which
+one needs them *now*. yothere is an **attention router for the human**, not a work
+router for the agents: pull-on-glance by default, one rate-limited nudge ("N
+threads need your eyes"), never a firehose, never interrupting your focus thread.
+
+## Install
+
+```bash
+pip install yothere          # core: fleet runner + board + remote-brain client
+pip install 'yothere[voice]' # + the Gemini-Live voice surface (WebRTC/Twilio)
+pip install 'yothere[llm]'   # + optional LLM tiebreak for routing (deterministic otherwise)
+```
+
+yothere keeps all of its state under `~/.yothere` (override with `YOTHERE_HOME`,
+or the legacy `RELAY_HOME`; an existing `~/.relay` is used as a fallback); see
+[`docs/configuration.md`](docs/configuration.md) for every env seam (each `RELAY_*`
+name also accepts its `YOTHERE_*` sibling).
+
+## Quickstart — drive the bundled reference brain
+
+```bash
+# 1. Start the conformance brain (the smallest valid Brain Protocol implementation).
+python -m yothere.voicecall.echo_brain --port 9999 &
+
+# 2. Point yothere at it and spawn a thread.
+export RELAY_REMOTE_BRAIN_URL=ws://127.0.0.1:9999
+export RELAY_THREAD_HARNESS=remote
+yothere spawn "research agentic commerce"
+
+# 3. Advance the fleet one tick, then glance at the board.
+python -m yothere.runner once   # or: python -m yothere.runner loop  (always-on engine)
+yothere board --open
+```
+
+Swap `RELAY_REMOTE_BRAIN_URL` for your real endpoint and yothere drives your brain.
+To run threads with a local Claude Code instead, set `RELAY_THREAD_HARNESS=claude`.
+
+## The contract
+
+A brain implements [`docs/brain-protocol-v1.md`](docs/brain-protocol-v1.md):
+`hello` / `streamSubscribe` / `prompt` / `cancel` / `close`, streaming back
+`delta` (text), and optionally `progress`, `status` (drives the attention
+router), and `cost`. The reference is
+[`src/yothere/voicecall/echo_brain.py`](src/yothere/voicecall/echo_brain.py), ~60
+lines. Two load-bearing caveats live in [`SECURITY.md`](SECURITY.md): a remote
+brain's cost cap is advisory, and **the brain owns its own safety/permissions**.
+
+## Architecture
+
+```
+            yothere (cockpit + voice + runner)            YOUR BRAIN
+  ┌───────────────────────────────────────────┐   ┌──────────────────┐
+  cli  ──► spawn ──► store (dir-per-thread) ◄── runner ─┐            │
+   │         │            │                       │     │  Brain     │
+  board ◄─ fleet_state ◄──┘                  brain_advance ──ws──►  Protocol  │
+   │     (attention router: rank · focus)          │     │  v1        │
+  voice ──► session_manager ──────────────────────┘     └──────────────────┘
+```
+
+- **store / thread_model** — the dir-per-thread state machine (atomic
+  `status.json`, session-id resume, the worker contract).
+- **attention** — deterministic ranking + the human-facing guardrails.
+- **runner / worker** — the headless advance engine (cost caps, stale sweep,
+  429 usage-cap hold, coalesced nudges).
+- **brain/** — the harness clients: local Claude, ubob daemon, any remote brain.
+- **board / card** — the glance UI (server-rendered, XSS-safe).
+
+## Hosted mode (multi-tenant cockpit)
+
+The `/overview` cockpit runs in one of two modes, selected by `RELAY_AUTH_MODE`:
+
+- **`off` (default) — local, single-user.** No login. The page, its SSE stream
+  (`/live`), and the plan-review reply are reachable over loopback/tailnet
+  (`_PUBLIC_PATHS`); the dangerous surface (WebRTC offer, `/harness`, `/start`,
+  `/client`) stays behind the `RELAY_VOICECALL_BEARER` gate with a loopback
+  exemption. This is byte-identical to the pre-auth cockpit — zero config.
+- **`hosted` — multi-tenant.** A login is required: the tailnet carve-out is gone,
+  every route except `/healthz` + `/login` needs a session cookie, and each account
+  is scoped to its **own** `~/.relay-<tenant>` home (separate threads/data/state),
+  so two logins see two isolated fleets with no cross-tenant read. Auth is
+  Python-native and stdlib-only (`yothere.voicecall.auth`): scrypt password hashing,
+  an opaque session token in SQLite (`RELAY_AUTH_DB`, WAL, separate from fleet
+  state), login lockout, and a `Secure` cookie tied to the mode (not the request
+  URL, so a TLS-terminating proxy can't drop it). Tenant homes live under
+  `RELAY_TENANTS_ROOT` (default: beside `~/.relay`).
+
+Hosted env: `RELAY_AUTH_MODE=hosted`, `RELAY_AUTH_DB=<path>`,
+`RELAY_TENANTS_ROOT=<dir>`. Seed users via `yothere.voicecall.auth.AuthStore.create_user`
+(public signup + hosted deployment are the next increment). The headless runner is
+still single-tenant in this increment: a non-default tenant's threads are created and
+isolated, but advancing them needs per-tenant runner orchestration (next increment).
+
+## MCP surface
+
+Drive a yothere fleet from any MCP client (Claude Desktop, etc.) — an orthogonal channel
+that exposes the same front doors as the CLI and cockpit over stdio MCP:
+
+- **`spawn_thread(task, mode, focus)`** — spawn fleet thread(s) from a natural-language
+  task (read/draft-only, blocks for your approval before any outward action).
+- **`board()`** — the fleet at a glance, needs-eyes first.
+- **`reply(thread_id, text)`** — approve / edit / reject a blocked thread.
+
+Single-user / local (drives this machine's `~/.relay` fleet). `mcp` is an optional
+extra; install + register:
+
+```bash
+pip install 'yothere[mcp]'
+```
+
+```jsonc
+// Claude Desktop: claude_desktop_config.json
+{ "mcpServers": { "yothere": { "command": "yothere-mcp" } } }
+```
+
+The tool logic lives in SDK-free `_*_impl` helpers (`yothere.mcp_server`), so it imports
+and tests without the `mcp` dependency installed.
+
+## Status
+
+v1.0.0. Fleet runner, board, voice surface, and the remote-brain path are tested
+(`python tests/relay_test.py`). The hosted web cockpit and brain-side token
+lifecycle are out of v1 (see [`CHANGELOG.md`](CHANGELOG.md)).
+
+## Contributing
+
+Two people build yothere and neither should break `main` alone. Every change goes
+through a PR that the other founder approves before it merges — see
+[`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## License
+
+MIT — see [`LICENSE`](LICENSE).

yothere-1.5.2/QUICKSTART.md

@@ -0,0 +1,80 @@
+# Quickstart
+
+Five minutes from install to a thread advancing against a brain.
+
+## 1. Install
+
+```bash
+pip install yothere
+```
+
+## 90-second start (no API key)
+
+`yothere init` sets up `~/.yothere` (override with `YOTHERE_HOME`/`RELAY_HOME`;
+an existing `~/.relay` is reused), detects any brain
+you already have (a remote `RELAY_REMOTE_BRAIN_URL`, a `brains.yaml`, or the
+`claude` CLI), and wires the bundled zero-key demo brain if you have none.
+It is idempotent and never overwrites existing config.
+
+```bash
+yothere init          # one-time setup + a status block with your next commands
+yothere init --demo   # watch a live fleet end to end (~30s, zero keys)
+yothere board --open  # the board it just filled
+```
+
+`--demo` starts a bundled Brain Protocol v1 brain on localhost, spawns one
+thread ("Demo: competitive scan"), and advances it through the real
+runner -> worker -> brain path: you'll see it stream progress, go **blocked**
+asking for your eyes (the attention router at work), get replied to the way
+you would (`yothere reply <id> "ship it"`), and finish **done** with a result
+summary on the board. Everything stays under `RELAY_HOME`; Ctrl-C is safe.
+
+## 2. Run against the bundled reference brain
+
+The `echo_brain` is the smallest valid Brain-Protocol implementation (~60 lines)
+and the conformance fixture. Use it to prove the loop before wiring a real brain.
+
+```bash
+# terminal 1 — the reference brain
+python -m yothere.voicecall.echo_brain --port 9999
+
+# terminal 2 — point yothere at it and drive a thread
+export RELAY_REMOTE_BRAIN_URL=ws://127.0.0.1:9999
+export RELAY_THREAD_HARNESS=remote
+yothere spawn "summarize the state of agentic commerce"
+python -m yothere.runner once          # advance one tick
+yothere board --open                    # glance at the fleet
+```
+
+## 3. Point at a real brain
+
+Either set `RELAY_REMOTE_BRAIN_URL` (+ `RELAY_REMOTE_BRAIN_TOKEN`) to your
+`wss://` endpoint, or register named brains in `~/.relay/brains.yaml` and select
+one with `RELAY_BRAIN` (see [docs/configuration.md](docs/configuration.md)).
+
+To run threads with a local Claude Code instead of a remote brain:
+
+```bash
+export RELAY_THREAD_HARNESS=claude    # needs the `claude` CLI on PATH
+yothere spawn "draft the Q3 update"
+python -m yothere.runner loop           # always-on advance engine
+```
+
+## 4. Implement your own brain
+
+Implement [docs/brain-protocol-v1.md](docs/brain-protocol-v1.md) (`hello`,
+`streamSubscribe`, `prompt`, streaming `delta` frames). Add `progress` / `status`
+/ `cost` to light up the fleet cockpit fully, and `sessionStatus` so a stateless
+client can render the board over the network. Read `echo_brain.py` for the shape.
+
+## Everyday commands
+
+```bash
+yothere spawn "<task>"        # create a thread (or `yothere preset <key> <arg>`)
+yothere list                  # live threads + state
+yothere show <id>             # status, plan, transcript
+yothere reply <id> "<text>"   # answer a blocked thread -> it re-advances
+yothere focus <id>            # pin the focus thread (never auto-interrupted)
+yothere board --open          # the glance board
+yothere note "<text>"         # capture a reminder (no thread)
+```