hci-atrium 0.4.0 → 0.6.0

package/PARITY.md

@@ -0,0 +1,392 @@
+# Python ↔ TypeScript SDK parity ledger
+
+The workflow: **Python first, port in validated batches.** New surfaces land in the Python SDK,
+prove themselves in use (an example, a study, a live test), then get ported here in one
+well-scoped batch. This file is what keeps that honest — "port later" without a ledger is how
+drift becomes silent.
+
+Rules:
+- When a Python-SDK surface merges that TS lacks, **append a row here** in the same MR/commit.
+- When a batch is ported, check rows off (move to Done or delete — git remembers).
+- A gap that is *deliberate* goes to "Won't port (by design)" with the reason — exceptions are
+  decisions, not drift.
+- TS-first surfaces (browser-native capture etc.) get a row in reverse: Python owes the port.
+
+Canonical port decisions (Zod, camelCase, fixture corpus, browser API keys): see
+`docs/plans/typescript-sdk-port.md`.
+
+## Open gaps (Python has it, TS doesn't)
+
+None. Every Python-SDK surface is either ported (below) or a documented "won't port".
+
+> **Dated correction (2026-07-26).** This section read "None" while `library.add` was in fact
+> missing — TS had only `assets.upload` (files), so the **fileless** *description-as-content* asset
+> Python has offered since the description-as-content decision had no TS equivalent, and the guide's
+> TS tab carried a workaround comment saying so. The gap is closed below (ergonomics pass), but the
+> ledger was wrong for the whole window and that is worth recording: a "None" nobody re-derives is
+> how drift hides. The rule stands — a Python surface that lands without a TS twin gets a row here in
+> the same MR.
+
+## Ported (was open, now in TS)
+
+- **Ergonomics pass (breaking, 2026-07-26):** an API-shape round over the whole TS surface, driven by
+  an audit rather than a new Python surface. **`library.add({ file?, description?, modality?,
+  collection? })`** — the twin of Python's `library.add`, closing the fileless gap above (a plain form
+  body, no file part; `add()` with neither a file nor a description raises `InvalidArgumentError`).
+  New fixtures `assets/add_fileless` + `assets/add_fileless_full`, call-sited in **both** suites.
+  Everything else in the pass is TS-side shape, not new capability: `search` gained an options-only
+  overload (`search({ like })` replaces `search("", { like })`); `surveys.start` is options-only
+  (`start({ template, into })`); `chat` lost its `stream` flag to a separate `chatStream`;
+  `ChatOptions`/`AgentOptions` swapped their index signatures for an explicit `params` bag;
+  `sources.import(target, opts?)` and `sessions.event(id, type, payload?, opts?)` took their
+  load-bearing argument positional; `Session` became a bound class (see the micro-divergence note);
+  `Room` split into `Room` + `OwnedRoom`; `room.play`'s source is typed (`PlayTrack` / `PlaySource`);
+  `room.send` gained `replyTo` / `ackId`; `assetCapabilities` / `assetPlayback` became
+  `asset.capabilities` / `asset.playback` getters; `WebSocketCtor` → `webSocketCtor`; the root barrel
+  dropped its protocol internals. Wire-identical throughout — the shared fixture corpus passes
+  unchanged apart from the two deliberate new registrations. Type-level tests
+  (`tests/types.test-d.ts`, run by `pnpm test:types`) pin the soundness wins as compile errors.
+
+- **Template-ensure follow-up (2026-07-27):** `template()` gained a create-only
+  `description?` option and a `{changed, created}` pair in its return, mirroring the
+  same-day Python change — the server's copy-on-write versioning means the version
+  number alone can't distinguish a no-op from a write, so the ensure reports it
+  itself. `clients/wire-fixtures/surveys.json` grew a 12th request
+  (`template_create_described`), call-sited in both suites.
+
+- **Wave 6 (the last phase-2 bundle: surveys, direct models, chat streaming, `agent`, 2026-07-26):**
+  closes the open-gaps table. **`atrium.surveys`** (`Surveys` in `src/atrium.ts` + `src/shaping/surveys.ts`,
+  the `surveys.py` twin): `start(template?, { into, name?, returnTo? })` → a `Survey` (`token` / `url` /
+  the pinned `{name, version}` template, plus `open()` — `window.open`, throwing `InvalidArgumentError`
+  outside a browser rather than pretending); the idempotent `template(name, body, { project?, default? })`
+  ensure flow (POST → 409 → GET → `/versions` → PATCH `is_default`), whose "did it change?" test is a
+  key-order-insensitive compare of the **JSON-encoded** body (`sameJsonBody`) so a rerun never appends an
+  identical version; `templates()`; `responses(name, opts)` → `SurveyResponse[]` **and** `responsesCsv(name, opts)`
+  → `Uint8Array`; `uploadFile(file, { project?, role?, filename? })`. Project refs pass through **verbatim**
+  (a short_id must not trigger a projects read a scoped key is denied) and template names are
+  percent-encoded in every path. **Direct models** (`src/direct.ts`): `DirectEndpoint` / `DirectRegistry`,
+  `addDirectModel(s)` / `removeDirectModel` / `listDirectModels` / `discoverModels`, plus the
+  `AtriumOptions.directModels` constructor form; a registered name shadows an Atrium model and its chat
+  goes out on the **raw `fetch`** with only that endpoint's key — the Atrium credential never reaches a
+  third-party endpoint — while `embed` and everything else stay on Atrium. **`chat(messages, { stream: true })`**
+  → `AsyncIterable<string>` (returned synchronously, no `await` before `for await`) over the SSE
+  `[DONE]`-terminated delta wire, on the Atrium route and direct endpoints alike, reusing the room
+  transport's `sseFrames`. **`atrium.agent(prompt, { tools, maxTurns?, responseFormat? })`** with
+  explicit `ToolDescriptor`s (`src/tools.ts`) — see the micro-divergence below. `HttpMethod` gained
+  `PATCH`. Fixtures: `clients/wire-fixtures/surveys.json` (11 requests + 3 responses), call-sited in
+  **both** suites. Tests: `tests/surveys.test.ts` / `tests/direct.test.ts` / `tests/chat-stream.test.ts` /
+  `tests/agent.test.ts` (mirrors of `test_surveys.py` / `test_direct.py` / the Python `agent` cases).
+
+- **Wave 5 (the magical-dashboard baseline: `Dashboard` + `room.trace()` + `audioTranscripts`,
+  2026-07-26):** the three surfaces a hosted `/tools/dashboard` needs from a TS host.
+  **Host-side `Dashboard`** (`src/dash.ts`, the `dash.py` twin on the **v2 tile wire**): tiles keyed
+  by `kind` (`status`/`text`/`image`/`sound`/`decision`) with `col_span`/`row_span` (1..3, validated
+  → `InvalidArgumentError`) + `group`; first-class `decision(candidates, { picked, reasoning })`
+  (bare-label or `{label, detail?, score?}` candidates); **`components` is THE snapshot carrier**
+  (no `tiles` alias); `error(message, detail?)` broadcasts the sticky-strip `dash.error` signal
+  (`{message, detail?, at}`) and is **not** a tile; controls are `button(id, label, handler, opts)` /
+  `textInput(id, handler, opts)` (the `text` tile owns `text()`) + `onNote(handler)` — no decorator
+  form (TS takes the handler as an argument, chainable), no sidebar-sections API. Host-answers-join
+  (`presence.join` → a targeted ephemeral `dash.snapshot`), a `dash.delta` per mutation once
+  connected, `dash.action` replies through the room dispatcher. **`room.dashboard(opts)`** is the
+  recommended constructor: it publishes over the REST `/signal` POST so the dialect's "all `dash.*`
+  is ephemeral" actually holds (the WS inbound path forces `ephemeral: false` — same reason the
+  transcriber publishes over REST). `new Dashboard(roomLike, opts)` still works for a decoupled/test
+  room; `Room` gained a public `identity` getter (the snapshot's `host` fallback, Python parity).
+  **`room.trace()`** (`src/trace.ts`): the same envelope + type folding — `trace.<label>` for
+  `library.search` / `library.search_by_examples` / `library.enrich` / `chat` (client-wide, durable)
+  and `play` (room-scoped, ephemeral), `trace.state.<label>` for `recorder` / `transcriber` /
+  `offer.<name>` (ephemeral), identical summary strings + capped top-5 detail. Zero-cost when off
+  (the sink list is empty → the summarizer never runs), a failing emit never breaks the traced call,
+  a call that throws emits nothing, `stop()` unregisters from both the client and the room, and the
+  room's teardown stops every handle. **`room.audioTranscripts({model, language, partials, skipEmpty,
+  signal})`** — the raw per-snippet iterator on wave 3's shared engine, including Python's
+  per-snippet correlation on the degraded path (`transcript.raw.snippet = {sequence,
+  window_seconds}`, the clip's format taken from each frame's own MIME type), via a new
+  `TranscribeStreamOptions.fallback` seam (the twin of Python's `_transcribe_engine(fallback=…)`).
+  Tests: `tests/dash.test.ts` / `tests/trace.test.ts` / `tests/audio-transcripts.test.ts` (mirrors of
+  `test_dash.py` / `test_trace.py` / `test_audio_transcripts.py`), pinning the wire JSON a
+  `/tools/dashboard` parser reads rather than importing the tool's types.
+- **SDK surface expansion Rounds 1–2 (introspection + read-back, 2026-07-20):** the port of
+  `docs/plans/sdk-surface-expansion.md`. **Round 1:** per-asset vectors (`atrium.assets.vectors(assetOrId,
+  {space?, matchBy?})` — public by-id GET, space name-or-id resolution, mixed `matchedBy` tolerated) +
+  the bound-object migration — **`Asset` is now a class** (data fields stay own/enumerable/JSON-safe,
+  a truly-private `#binder`; `asset.vectors()`/`.segments()`/`.index()` on the prototype, threaded in
+  at parse via a new `ClientInternal.assetBinder`; an unbound asset rejects, naming the id-form call);
+  bulk `atrium.library.vectors(ids, {space, matchBy?, strict?})`; `atrium.assets.segments()` (reuses
+  `SegmentRef`) + `.index()` (server `via` → `matchedBy`); `search({includeVectors})` (`hit.vector`,
+  `include_vectors` omitted when falsy); `compare(a, b, {breakdown})` → `CompareResult.features`; tag
+  reads `atrium.library.tags()` / `.tag(nameOrId, {includeSnapshot?})`; the Round-1.6 `Asset` fields
+  (labels/rejectedLabels/proposedLabels/autoTagged/createdAt/updatedAt/status/descriptionSource/
+  homeCollectionId/externalId/origin/sourceId). Broker guard lifted: an `embed.resolve` **asset**
+  anchor now resolves through the per-asset vectors endpoint (`brokers.ts` + `room.ts`).
+  **Round 2:** `atrium.sessions.list({project?, phase?})` / `.get(id)` (read-model `SessionInfo`, twin
+  of `resume`'s live handle — same route, different shape; `Session` handle gained the identity
+  fields) / `.events(id, {after?, limit?})` / `.export(id, format?)` / `.exportBundle(ids)`. **Node/
+  browser choice:** exports return `Uint8Array` — no `path=` file-writing (the core never touches the
+  filesystem, `files.ts`); a Node caller writes the bytes itself. **Deliberate gap kept:** surveys
+  (see Open gaps). Tests: `tests/introspection.test.ts` + `tests/readback.test.ts` (mirror the Python
+  `test_introspection.py`/`test_readback.py` contract points), brokers test updated for asset anchors.
+- **Wave 4 (standing-service offers + capability brokers, 2026-07-18):** the third broker kind on the
+  **v2.1 armed-set wire**. `ArmedSet` state machine (`src/rooms/armed-set.ts`): explicit ∪ (all-arm −
+  exclusions-since), fresh all-arm resets exclusions, `isArmed(null)` only under all-arm, migrate on
+  same-name reconnect. `StandingSource` shared base (`src/rooms/standing-source.ts`) — armed set + cap
+  admission, the `active` roster built on the **armed set** (immediate-on-arm; all-arm enumerates every
+  connected `capture-source`; v1 unsourced → `{source: null}`), ephemeral `<service>.available`
+  broadcast (deduped, over the REST `/signal` POST), an **own point-in-time roster** folded in loop
+  order (seeded from the ready snapshot), presence/migration, one grace sweeper (not a timer per
+  departure), the scoped `start`/`stopRequest` shells. `room.offerTranscription({model?, language?, maxSources?})`
+  → `OfferedTranscription` (`src/rooms/offer-transcription.ts`): per-armed-source engines over wave 3's
+  `transcribeStream` (one bounded drop-oldest queue per source), publishing `source`/`source_name`-attributed
+  `transcript.*`. `room.offerAudioCapture({maxSources?})` → `OfferedCapture` (`src/rooms/offer-capture.ts`):
+  **session-less** — binds the FIRST active recorder's session via wave 2's `activeRecorders()` /
+  `onRecordersChanged` seam (disengage when it dies; one-recorder rule warns, no double-write), writes
+  via the chunked recording API (`POST …/recordings` → `PUT …/chunks` → `POST …/finalize`), collision-safe
+  keys (name-else-cid; same-name grace reconnect resumes the file; simultaneous same-name → full-cid-suffixed
+  files), grace finalize via the single sweeper, create-failure circuit breaker, 401/403 ends the bridge.
+  `offerService` wires sender-scoped `<service>.start`/`.stop`/`.status` with `{ok}`/`{error}` replies.
+  `room.offerEmbeds({spaces?, maxAnchors?})` / `room.offerChat({model?, maxTokens?})` brokers
+  (`src/rooms/brokers.ts` validators): the loginless-Unity requester pattern — requester picks the embed
+  space (per-anchor errors don't fail the batch; text embedded on the host's credential + cached), broker
+  pins the chat model. All four announce their discoverable role, merged into the presence announce
+  (`mergedAnnounce`), registered **before** `connect()`; stopped on room close. `ShapedRequest` gained a
+  raw-`content`/`contentType` channel for the binary chunk PUT.
+- **Wave 3 (live transcription, 2026-07-18):** `Atrium.transcribeLive(chunks, opts)` — the streaming
+  upgrade over the shared engine (`src/transcribe.ts`): a thin WS client to `WS
+  /v1/audio/transcriptions/stream` (`src/transcribe-stream.ts`, `TranscriptionStream`), container-clip
+  **or** `pcm16 + sampleRate` input, `partials` opt-in (finals-only default), and the **connect-time-only**
+  degradation ladder to per-clip batch POSTs (a mid-session drop / clean-close-without-`done` / 4401
+  **raises** — `AtriumError` / `AuthError` — never a silent success; PCM is re-windowed into ~5s WAV
+  clips for the fallback). `Transcript.final` added to the transcript model (`true` for every batch
+  transcript + finalized sentence, `false` for a live partial). `room.transcribe({model?, language?})`
+  → `Transcriber` (`src/rooms/transcriber.ts`) — the in-room broker: consumes the room's snippet stream
+  (wave-1 `snippetStream`) through the same engine and publishes `transcript.partial` (ephemeral) /
+  `transcript.final` (`{text, start, end, seq}`) as `source: "transcriber"`, so **wave 2's recorder
+  records the finals for free**. Handle mirrors Python's `_AsyncTranscriber`: `stop()` / `alive` /
+  `error`, stopped when the room closes, `await using`. Needs the authed client slice
+  (`RoomAudioClient.transcribeStream`); a loginless `joinRoom` handle throws.
+- **Wave 2 (durable & reactive surfaces, 2026-07-18):** `room.record(into)` → `Recorder`
+  (`src/rooms/recorder.ts`) — the single durable binding, over an SSE-**observe** `RoomEventStream`
+  (no presence connection): skips `ephemeral` + `presence.*` + the `room.code_rotated` advance-signal,
+  stamps `via` = `{room_id, room_name, from, to}`, reconnects on a drop, stops cleanly on a rotation
+  (`stoppedReason`) or terminal room-gone/bad-code (`stoppedReason` **and** `.error`); handle is
+  `stop()` + `alive` / `error` / `stoppedReason` + `await using`. The **recorder-registration seam** —
+  `room.activeRecorders()` (membership + liveness) and `room.onRecordersChanged(listener)` (mirror of
+  Python's `_notify_recorders_changed`) — is ported now so wave 4's `offerAudioCapture` binds to the
+  active recorder. `room.audioVectors({space?, model?, relay?})` — the zero-args embedding-vector
+  consumer (dedicated snippet-consumer socket, embeds each ~10s window against the resolved default
+  audio space/model, `relay` re-broadcasts each vector as an ephemeral `audio.vector`). `room.audioScores(anchors, {space?, model?, topN?, relay?})` — per-anchor `library.compare` fusion
+  (few-shot list anchors via `toAnchorMembers`/`by.*`, top-`N` mean, mix normalized to sum 1, concept
+  anchors preflighted), wired to the existing `Decider`. `audioVectors`/`audioScores` need the authed
+  client (injected as `RoomDeps.client`; a loginless `joinRoom` handle throws). `Space.model` now
+  surfaced. The recorder matches Python's write semantics exactly: each `session.event` POST is
+  awaited **inline** in the observe-stream read loop (backpressure — one write in flight, no unbounded
+  queue), a write refused with status < 500 (≠ 429) is **terminal** (`.error` set, the recorder-changed
+  seam fires so a bound capture offer disengages), and a transient 5xx/429/network write blip drops +
+  reconnects the stream (the gap is lost, capture continues).
+- **Wave 1 (consumers & transport, 2026-07-18):** SSE receive + POST-send room transport with the
+  WS→SSE fallback ladder (`transport: "auto" | "ws" | "sse"`, `src/rooms/sse.ts` — Python's
+  `_RoomDispatcher`/`_events` parity: code-auth, reconnect/backoff, `room.code_rotated` in-band
+  terminal, 403/404 terminal; **signals-only**, binary stays WS-only, and rooms have no replay so no
+  `Last-Event-ID` cursor); `audio.snippet` **v2 decode** (`decodeAudioSnippetFrame`, source-attributed,
+  v1 still decodes); `room.audioClips()` raw-clip async iterator (source/sourceName from the
+  subscribe-time roster snapshot); `room.participants()` / `room.has()` typed `Participant` roster
+  (merged `role`+`roles`, `connectedAt` as `Date`) over one short observe stream; `dashboardUrl()` /
+  `openDashboard()` / `captureUrl()` / `openCapture()` URL helpers.
+
+## Public surface notes (pre-release)
+
+- The default `hci-atrium` barrel exports only the two roster *types* an app touches: the parsed
+  `Participant` (merged roles / `name` / `connectedAt`, from `rooms/participant.ts`) and the raw
+  transport item `RosterEntry` (from `rooms/transport.ts`). Internal helpers — `mergeRoles`,
+  `parseParticipant`, `participantMatches`, `readObserveRoster`, `parseAnchorDescriptor` /
+  `AnchorDescriptor` — are **no longer re-exported** from the top-level entry (they stay importable
+  internally via `rooms/index`). Also on the record: the `Participant` export was re-pointed to the
+  parsed view and the raw roster item renamed to `RosterEntry`. Pre-release, no consumers.
+- **Barrel trim, 2026-07-26 (ergonomics pass).** The root `hci-atrium` entry now exports the two room
+  handles (`Room`, `OwnedRoom`), the values their methods hand back (`Recorder`, `Transcriber`,
+  `OfferedCapture`, `OfferedTranscription`, `RoomTrace`, `Dashboard`, `Decider`, …), the models, the
+  errors, and the option/event types an app names. **Demoted** (still importable from their modules,
+  just off the barrel): the audio/snippet frame codec and its `AUDIO_SNIPPET_MAGIC` / `*_VERSION`
+  constants, every role string (`AUDIO_ROLE`, `*_BROKER_ROLE`, `CAPTURE_*`, `TRANSCRIBER_SOURCE`, …),
+  the transport internals (`RoomEventStream`, `RoomTransport`, `RoomSignal`), the offers' machinery
+  (`ArmedSet`, `StandingSource`, `OFFER_MAX_SOURCES`), the dependency-injection bags (`RoomDeps`,
+  `OwnedRoomDeps`, `RoomAudioClient`, `OfferDeps`, `CaptureOfferDeps`, `TranscriberDeps`, …),
+  `validateChatMessages`, and the trace dialect helpers (`traceEnvelope`, `traceCallType`,
+  `traceStateType`, `TRACE_STATE`, `isTraceEphemeral`). These describe the wire, not the app; the
+  hosted tools import none of them.
+
+  **Demoted is not removed.** 0.3.x shipped these *on the barrel*, so this is a breaking change for
+  anyone who named one — the package is on npm and its download count is not zero. The migration path
+  is the `./internal/*` subpath export, which mirrors the source tree:
+
+  ```ts
+  import { decodeAudioFrame } from "hci-atrium/internal/rooms/codec.js" // extension optional
+  ```
+
+  It carries **no semver guarantee** — internals move without a major bump, by definition. It exists
+  so a 0.3 consumer has a one-line edit instead of a fork, not as a second public API.
+
+## Won't port (by design)
+
+| Surface | Reason |
+| --- | --- |
+| CLI (`atrium …`) | Documented parity exception — except `atrium guide`, which the npm package ships to print GUIDE.md. |
+| Home Assistant bridge | Documented parity exception. |
+| Sync client surface | JS is async-native; single-surface SDK is the idiom. |
+| Raw-PCM mic input à la `sounddevice` | Browser equivalent is `MediaRecorder`/AudioWorklet clips — same `transcribeLive` contract, different capture idiom. |
+
+## Known micro-divergences (documented, acceptable)
+
+- **Agent tools are descriptors, not decorated functions.** Python's `@client.tool` derives a tool's
+  OpenAI schema from the function's signature + docstring; TypeScript erases types and has no
+  docstrings, so a tool is an explicit `{ name, description, parameters, execute }` descriptor.
+  `parameters` is plain JSON Schema, or `{ jsonSchema, validate? }` where `validate` is any
+  [Standard Schema](https://standardschema.dev) object (Zod ≥3.24, Valibot, ArkType — the `~standard`
+  property) used to parse the model's arguments before `execute` runs. A **bare** schema object is
+  rejected with a message naming the fix: deriving JSON Schema from it would mean taking the library
+  as a runtime dependency, and the package is zero-dependency by design (Zod stays an *optional* peer,
+  loaded lazily only by structured output). One more small deviation inside the loop: a tool's return
+  value is JSON-encoded when it's an object (JS's `String({})` is the useless `"[object Object]"`,
+  where Python's `str(dict)` is readable).
+- **No `DirectTransports`.** Python caches one `httpx.Client` per direct endpoint and closes them with
+  the client; `fetch` is stateless, so TS has nothing to pool or close. The per-endpoint timeout
+  becomes an `AbortSignal.timeout` folded into each call's signal — and it is in **milliseconds**
+  (the JS unit), not Python's seconds.
+- **`surveys.responsesCsv` is its own method**, where Python has `responses(format="rows"|"csv")`.
+  The two return types have nothing in common (parsed rows vs raw bytes), so a union return would be
+  a type-level lie the caller has to narrow — the same call the `sessions.export` port already made.
+  Also, as there: no `path=` file-writing, since the core never touches the filesystem.
+- `surveys.start({ into })` takes a `Session` handle **or** a bare session id — unchanged. What
+  changed (2026-07-26, **overturning** the note that used to live here): TS's `Session` is no longer
+  an inert read model. It is a class with a truly-private `#binder`, exactly like `Asset`, carrying
+  `session.event(type, payload?, opts?)` bound to the client that produced it — the twin of Python's
+  `Session.event`. Python's instance offers *only* `event`, so that is all TS attaches; the id-based
+  `sessions.*` namespace (`sessions.event(id, …)`, `sessions.export(id)`, …) stays the complete
+  surface and is what an unbound session's error message names. A `Session` built by hand is now a
+  `parseSession({...})` call rather than an object literal — a class with a private field cannot be
+  satisfied structurally.
+- **`chatStream` is a separate method**, where Python has `chat(..., stream=True)`. A flag that swaps
+  the return type between `Promise<ChatReply>` and `AsyncIterable<string>` forces every call site to
+  narrow a union it already knows the answer to, and Python's dynamic `stream=True` has no such cost.
+  The behaviour is identical either way (the iterable is returned **synchronously** — nothing to
+  `await` before the `for await`, same as Python's generator), so this is a type-soundness divergence
+  only. It also retires a runtime error: "stream: true can't be combined with a schema
+  `responseFormat`" is now unrepresentable, since structured output lives on `chat` alone.
+- A **streamed** chat is traced at hand-off (one `trace.chat`, no reply preview, ~0 duration) —
+  mirroring Python, whose decorator emits when the generator is returned, before anything is consumed.
+- **`Room` / `OwnedRoom` split.** Python's `Room` carries its client, so its host-side verbs are
+  always callable and the loginless `join_room` handle is a different class already. TS used to hand
+  back one `Room` for both and refuse at runtime (`requireClient` → "no account credential"). The
+  ~14 credential-bound members now live on `OwnedRoom extends Room`, which `client.rooms.open/get/list`
+  return; `joinRoom(code)` **and** `client.rooms.join(code)` return the participant `Room`. Same
+  capability boundary, moved from the runtime to the type — `room.record(...)` on a code-joined handle
+  is a compile error, not a thrown one. `rooms.join` stays a plain `Room` deliberately: it is built
+  without the REST caller and capability slice (a code grants live transport, not the account), so
+  typing it `OwnedRoom` would advertise members that throw.
+- **`chat` / `agent` passthrough is an explicit `params` bag**, where Python takes `**kwargs`. TS's
+  equivalent was an index signature (`[key: string]: unknown`) on the options interface, which made
+  every misspelled SDK option — `responseFormatt`, `modle` — a silently-forwarded OpenAI param. The
+  bag keeps the capability (`params: { temperature: 0.3 }`) and gets the typo checking back; SDK-owned
+  keys are applied last and win a collision. Same wire.
+- **`room.send` carries `to` + `replyTo` only**, where Python's `Room.send` also takes `ephemeral`.
+  Python sends over the REST `/v1/rooms/{id}/signal` POST, which carries the flag; TS sends over the
+  room WebSocket, whose inbound path forces `ephemeral: false` server-side. An `ephemeral=` parameter
+  on the TS `send` would be a field the transport silently drops, so it isn't offered — the surfaces
+  that need ephemerality (`room.dashboard()`, `room.trace()`, `room.transcribe()`, the standing
+  offers, `audioVectors({relay: true})`) all publish through the REST POST instead, which is why they
+  are `OwnedRoom` members. `ackId` is likewise absent: a reply needs a registered pending entry, and
+  only `room.request(...)` creates one.
+- **Base-URL resolution is one helper** (`resolveBaseUrl`, `src/env.ts`) shared by the client,
+  `joinRoom`, and the React `useRoomConnection` hook: explicit `baseUrl` → `ATRIUM_BASE_URL` →
+  (hook only) the page's own origin → the deployed default. The hook's origin rung is the one
+  difference, deliberate — it is browser-only, and a hosted tool page served *by* an instance should
+  talk to that instance. **Behavior change (2026-07-26):** the hook previously hardcoded
+  `location.origin`, so a tool pointed elsewhere at build time via `ATRIUM_BASE_URL` silently ignored
+  it; env is now consulted first. A page that relied on origin-wins while also setting the env var
+  resolves differently.
+- `room.play` for byte-backed assets: TS sends compact `{asset_id}`, Python sends a playback
+  intent. Both shapes work at the Player.
+- **Player dialect arguments are typed in both spellings.** `room.play(track)` and
+  `room.configureLayers(layers)` accept the SDK's camelCase (`PlayTrack` / `LayerDeclaration`) *or*
+  the dialect's own snake_case (`WireTrack` / `LayerSpec`, from the `hci-atrium/player` subpath),
+  translating the former at the shaping seam. Python takes the wire dict directly and has no second
+  spelling. A key belonging to neither is a compile error, which is the point: the runtime always
+  accepted a hand-rolled wire descriptor, and before this the type didn't. The read-back
+  (`queryLayers` / `watchLayers`) still hands back the raw wire snapshot, snake_case — it is the
+  Player's payload, not an SDK model.
+- **One `PlaybackIntent`.** The `{source, ref, mode?}` intent is defined once in `models.ts` and
+  re-exported by `hci-atrium/player`'s `play-command`, so the type an app reads off `asset.playback`
+  is the exact type the Player runtime dispatches on. `ref` is therefore nullable there too (a
+  description-only asset has no target): `routePlayIntent` reads a missing ref as "nothing to play",
+  and narrows `mode` to the `"shuffle"` the Spotify resolver understands.
+- `room.play`'s `asset` track key (landed both sides 2026-07-26, together with the `gain` per-call
+  option: `play({asset: hit, gain: 2})` / `play(source, {gain: 2})`, per-track gain winning): what
+  counts as "an asset under `asset`" is decided differently. Python expands anything that isn't a
+  `dict` (an `Asset`/`SearchHit`/id string — anything else raises the usual `TypeError`) and leaves a
+  `dict` alone, since that's the wire's inline-asset descriptor; TS has no dict/object split, so it
+  expands only a value that *looks* like a parsed `Asset` (`isAssetLike`), a `SearchHit`
+  (`score` + `matchedBy`), or a string, and passes anything else through untouched. Same rule for
+  every SDK-object call, same wire; only a hand-rolled oddity under `asset` behaves differently
+  (Python throws where TS ships it as-is) — the same heuristic trade-off as the `isAssetLike` note above.
+- Live-transcription WS auth: Python rides an `Authorization: Bearer` header on the handshake; the TS
+  client can't (browsers forbid custom WS headers), so it carries the credential in-band as the
+  `start` frame's `api_key` field — the backend's browser-safe first-frame path (accept → read
+  `start` → pop `api_key` → validate). Same credential, different carrier; and unlike the legacy
+  `?api_key=` query the backend still tolerates, it never rides the URL into proxy/access logs. A
+  rejected key closes `4401` after the socket opened, still surfaced as `AuthError` (never a silent
+  degrade to the per-clip batch fallback).
+- `room.dashboard()` and `room.trace()` publish over the REST `/v1/rooms/{id}/signal` POST for the
+  same reason `room.transcribe()` does (below): the WS inbound path forces `ephemeral: false`, and
+  both dialects are ephemerality-sensitive (all `dash.*` is ephemeral; a trace is durable *unless* it
+  mirrors something already durable). Both therefore need an **owned** room — a loginless `joinRoom`
+  handle throws, where Python's `Dashboard(room)`/`room.trace()` ride its REST `send` unconditionally.
+  A bare `new Dashboard(roomLike)` (the decoupled/test path) still uses the room-like's own `send`.
+- Trace re-entrancy: Python needs a `contextvars` guard because its structured-output `chat` recurses
+  through the *traced* `chat`. The TS client's structured path calls the **untraced** private
+  `chatOnce` instead, so one logical call emits exactly one `trace.chat` with no task-local state.
+- `room.audioTranscripts()` teardown: a consumer's `break` can't cancel the engine's pending feeder
+  `await` the way Python cancels its feeder task, so the iterator holds its **own** `AbortController`
+  (chained to an optional `signal`), aborts it in a `finally` **before** winding the engine down —
+  closing the snippet socket is what unblocks the feeder — and pulls the engine by hand rather than
+  `yield*` (which would forward `return()` into a still-parked engine and deadlock). Same documented
+  limitation family as the transcription teardown note below.
+- `room.transcribe()` publishes its `transcript.*` signals over the REST `/v1/rooms/{id}/signal` POST
+  (like Python's `room.send`), **not** the room WebSocket — because the WS inbound path forces
+  `ephemeral: false`, and the recorder's finals-vs-partials split needs the partial's `ephemeral: true`
+  flag to survive on the wire. So the broker's ephemeral hint is honored identically to Python's.
+- Transcription teardown: JS can't hard-cancel a pending `await` the way Python cancels the feeder
+  task, so `stop()` aborts via an `AbortSignal` (closing the snippet socket + the stream WS) and the
+  feeder stops at its next resumption point / on the input iterator's `return()`. A well-behaved input
+  ends promptly; a pathological input blocked forever on its own `await` is the one case that can't be
+  force-unblocked (documented limitation, not reachable from the room snippet path, which ends on
+  socket close).
+- Offer source-name resolution: Python's `RoomWebSocket.frames(on_presence=…)` folds presence into a
+  roster on the *same* loop that yields binary frames, so each frame resolves its source against the
+  roster as it was when that frame was processed. The TS transport folds its live roster synchronously
+  on receipt (decoupled from the offer's async consumption), so a burst of presence + binary would race
+  the roster ahead. The offer therefore keeps its **own** point-in-time roster (`StandingSource` — name
+  + roles), seeded from the ready snapshot and folded in loop order, and resolves `source_name` /
+  all-arm enumeration off *that*, not the transport's live roster. Same observable behaviour, folded on
+  the offer's clock.
+- Offer engine teardown: a standing transcription offer holds a **per-source** `AbortController` (not
+  one shared signal). A per-source `transcription.stop` / a source's `presence.leave` — and the whole
+  `stop()` — abort that source's signal AND drop its buffered clips (`ClipQueue.clear()` + a `null`
+  end-sentinel), matching Python's `engine.cancel()`: buffered clips are discarded and nothing is
+  published past the disarm boundary (consent-relevant — no captions after a source stops/leaves). The
+  per-source `stopSource` runs under the offer's `Mutex`, like capture's.
+- The offer-capture chunked recording wire (`POST …/recordings` / `PUT …/chunks` / `POST …/finalize`)
+  is pinned by byte-exact assertions in `tests/offers.test.ts` (paths, `{source_name, content_type}`
+  body, chunk `Content-Type` + bytes) — mirroring Python's `test_offers.py` — rather than added to the
+  shared `wire-fixtures` golden corpus, which has no binary-body channel and whose Python side builds
+  these calls inline (no shaping-builder call-site to register). Same wire, pinned in both suites.
+
+## TS-first (Python owes the port)
+
+| Surface | Notes / porting trigger |
+| --- | --- |
+| `room.onEnd(cb)` — typed terminal-end hook | Fans the transport's already-classified terminal reason (`RoomEndReason`: `code-rotated` / `bad-code` / `room-gone`) out to a public listener, **exactly once** per handle, for a connect-time reject and a mid-session end alike, on the WS and SSE transports both. Returns an unsubscribe; a deliberate `close()` is not an end and never fires it. Added so a driver (the observation dashboard) maps a typed reason to its own UI state instead of string-matching a reject message — and so a mid-session `room-gone` (the room deleted out from under a live consumer) is caught rather than leaving the UI stuck on "live". Python's `Room` / `AsyncRoom` classify the same terminal reasons internally (e.g. the recorder's `stopped_reason`) but expose no public `on_end`. Trigger: the next Python-host consumer that needs the typed end; port as `room.on_end(callback)`. |
+| `atrium.data` — the participant-token tier under a survey (`GET /v1/data/resolve` · `GET`/`PUT /v1/data/content` · `POST /v1/data/submit`: read/write **one** data object with only its `atd_…` capability, no account) | The hosted survey tool speaks this tier over plain `fetch` today; nothing in either SDK wraps it. It belongs in TS **first**: the consumer is a browser page holding a per-object token, which is exactly the loginless shape TS already serves (`joinRoom`). Trigger: the `tools/` survey-runner migration onto the SDK — the same trigger the surveys row carried while it was open, and it was **wrong there**: `surveys.*` is the *researcher-side* surface (an API key, a project), which the SDK now has, and it never depended on that migration. Port to Python afterwards only if a Python host ever needs to fill a survey out. |
+| `hci-atrium/player` — audio-layers engine + `play` / `layer.*` dialect helpers | **TS-only by design — no port owed.** A browser WebAudio surface (named, independently-mixed layers with crossfades, reverb/echo/distance effects, and 3D positioning) behind the hosted Player tool, so SoundMuse 3 and other embedders can drive it. Python hosts drive the Player *over the room dialect*; they don't run the engine, so no Python equivalent is planned. See `docs/reference/audio-layers-dialect.md`. |
+
+*(browser mic-capture helpers for the recorder tool may also land here first.)*

package/README.md

@@ -18,6 +18,27 @@ pnpm add hci-atrium
 
 Or `npm install hci-atrium`.
 
+### For coding agents
+
+`pnpm exec atrium guide` prints the complete, task-oriented SDK guide —
+pipe it into your agent's context (`pnpm exec atrium guide > atrium-guide.md`, or just tell the
+agent to run it). Reading `node_modules/hci-atrium/GUIDE.md` directly works too. The deployed
+instance serves the same docs at `/llms.txt` for agents that browse.
+
+To make it automatic, add these lines to your project's `CLAUDE.md` / `AGENTS.md`:
+
+```markdown
+This project uses the hci-atrium SDK. Before writing Atrium code, run
+`atrium guide` and follow it — it is the authoritative API reference
+(`uv run atrium guide` in Python projects, `pnpm exec atrium guide` in
+TypeScript projects).
+```
+
+The guide is written against the Python SDK; its "Reading this from TypeScript" section covers the
+mechanical mapping, and [`PARITY.md`](PARITY.md) tracks the (few) deliberate gaps. `atrium guide` is
+the *only* subcommand this package ships — the full CLI (`login`, `whoami`, `search`, …) comes with
+the Python package.
+
 ## Register an app
 
 An app is registered on an Atrium **project**, next to its API keys (Capabilities → Apps). You
@@ -249,11 +270,17 @@ plus the hosted tool's `url`. Hand either to the participant-facing environment,
 a tab on the machine itself.
 
 `surveys.template(name, body)` is the code-first **ensure** flow: run it on every start-up. It
-creates the template if it's missing, appends a new immutable version only when the body actually
-changed, and flips `default` when asked — so your templates live in your repo, not in a UI.
+creates the template if it's missing, writes a new version only when the body actually changed, and
+flips `default` when asked — so your templates live in your repo, not in a UI. It returns
+`{name, version, isDefault, changed, created}`: read `changed`, not the version number, to tell a
+write from a no-op — the server is copy-on-write, so a real write keeps the current version number
+while no response is pinned to it. `description` is applied on **create** only.
 
 ```ts
-await atrium.surveys.template("post-study", postStudyBody, { default: true })
+await atrium.surveys.template("post-study", postStudyBody, {
+  default: true,
+  description: "the post-study questionnaire", // create only — ignored once it exists
+})
 
 const session = await atrium.sessions.start({ participantRef: "p-07" })
 await session.event("phase.start", { phase: "post-study" }) // bound to the session it came from
@@ -262,6 +289,7 @@ const survey = await atrium.surveys.start({
   template: "post-study",
   into: session,
   returnTo: "https://study.example/next",
+  linkParams: { modules: "build,test" }, // query params on survey.url, before its #token= fragment
 })
 survey.open() // …or send survey.url / survey.token to the participant's device
 

package/bin/atrium.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// `atrium guide` — print the SDK guide (GUIDE.md) for piping into a coding agent.
+// The TypeScript package ships only this one subcommand; the full CLI is Python-side.
+import { existsSync, readFileSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+
+const USAGE = `usage: atrium guide
+
+Prints the SDK guide (GUIDE.md) for piping into a coding agent.
+The TypeScript package ships only \`atrium guide\`; the full CLI
+(login, whoami, search, …) comes with the Python package —
+\`uv add hci-atrium\`, then \`uv run atrium --help\`.`
+
+const command = process.argv[2]
+
+if (command === "guide") {
+  // Source checkout first (clients/python/GUIDE.md is the canonical, always-current copy — a
+  // stale pack-time copy at the package root must never shadow it), then the packaged location.
+  const candidates = ["../../python/GUIDE.md", "../GUIDE.md"].map((rel) =>
+    fileURLToPath(new URL(rel, import.meta.url)),
+  )
+  const found = candidates.find((path) => existsSync(path))
+  if (!found) {
+    console.error("error: GUIDE.md not found (neither bundled nor in the source tree)")
+    process.exit(1)
+  }
+  process.stdout.write(readFileSync(found, "utf8"))
+} else if (["help", "--help", "-h"].includes(command)) {
+  console.log(USAGE)
+} else if (command === undefined) {
+  console.error(USAGE)
+} else {
+  console.error(`error: unknown command '${command}'\n\n${USAGE}`)
+  process.exit(1)
+}

package/dist/atrium.d.ts

@@ -508,12 +508,20 @@ export interface SurveyStartOptions {
     /** A url the survey's end page can send the participant back to — an ``app``-controlled return
      * button in the template resolves to it (the button's label stays template-controlled). */
     returnTo?: string;
+    /** Query parameters appended to the returned {@link Survey.url} (client-side only), inserted
+     * BEFORE its ``#token=`` fragment so the page actually reads them: ``{ modules: "build,test" }``
+     * to pick the template's page modules, or any question's ``param`` binding (see
+     * ``docs/reference/survey-template-dialect.md``). */
+    linkParams?: Record<string, string>;
     signal?: AbortSignal;
 }
 export interface SurveyTemplateOptions {
     project?: string;
     /** Make this the project's default template (the one ``start()`` picks with no template named). */
     default?: boolean;
+    /** The template's envelope description — applied on CREATE only, like the SPA's "load into a new
+     * template"; on a template that already exists it is ignored. */
+    description?: string;
     signal?: AbortSignal;
 }
 export interface SurveyResponsesOptions {
@@ -742,20 +750,31 @@ export declare class Surveys {
      * Start a survey on a session: creates the data object (pinning the template's current version —
      * or the project's DEFAULT template when ``template`` is omitted) and returns the handle with its
      * once-only token. Options-only — ``start({ template: "post-study", into: session })``, or just
-     * ``start({ into: session })`` for the default template.
+     * ``start({ into: session })`` for the default template. ``linkParams`` composes the returned
+     * ``url``'s query string (``modules``, a question's ``param``) — see {@link SurveyStartOptions}.
      */
     start(opts: SurveyStartOptions): Promise<Survey>;
     /**
      * Ensure a template exists with exactly this body (idempotent, code-first).
      *
-     * Create it if missing; if it exists and the CURRENT version's body differs, append a new
-     * immutable version; flip the default via PATCH when requested and not already set. Returns
-     * ``{name, version, isDefault}``. Safe to rerun on every start-up.
+     * Create it if missing; if it exists and the CURRENT version's body differs, save the new body
+     * (the server is copy-on-write: it overwrites the current version in place while no response is
+     * pinned to it, so a real write may keep the same version number, and forks the next version once
+     * one is); flip the default via PATCH when requested and not already set.
+     *
+     * ``description`` is the template's envelope description — applied on CREATE only, like the SPA's
+     * "load into a new template"; on an existing template it is ignored.
+     *
+     * Returns ``{name, version, isDefault, changed, created}`` — ``changed`` is false exactly when the
+     * stored body already matched, so the version number alone can't tell a no-op from a write. Safe
+     * to rerun on every start-up.
      */
     template(name: string, body: unknown, opts?: SurveyTemplateOptions): Promise<{
         name: string;
         version: number;
         isDefault: boolean;
+        changed: boolean;
+        created: boolean;
     }>;
     /** List the project's survey templates (``GET …/survey-templates``). */
     templates(opts?: {