@etiquekit/etq 1.0.10 → 1.0.12

package/QuickStart.md

@@ -64,7 +64,7 @@ envelope, and runbook. For branch hygiene, read [docs/WORKTREE_QOL.md](docs/WORK
 
 ## 4. Check And Record Evidence
 
-Completion gate: write the receipt at the path `pickup` names, post it
+Completion gate: write the receipt at the path `pickup` names (`etq receipt scaffold --task <ref> --seat <id>` writes a starter stub), post it
 (`etq post --role implementation-return --lane <task> --from <seat> --to <seat>`),
 then `etq return check`. Separately, `dispatch check` gates ROUTING before
 work begins — create checkable dispatch examples, then run the generated
@@ -91,4 +91,5 @@ Per-runtime integrations are explicit, never automatic: `provision-seat claude-c
 Stop when authority is unclear, validation cannot run, writes exceed the
 envelope, a secret appears, or the session is unbounded.
 
+Going further: `etq help advanced` catalogs the advanced subsystems — the memory journal, supervision sessions, release gates, sync outbox, and webhooks.
 Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt

package/README.md

@@ -10,7 +10,7 @@ and what proved it worked**. Etiquette gives each participant a *seat*, each
 unit of work a *task envelope*, each completion a *receipt*, and each merge a
 *promotion gate* — recorded as plain files and git history you can audit.
 
-Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt
+Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt · Going further (memory journal, supervision, release gates): `etq help advanced`
 
 ## Install
 
@@ -77,8 +77,4 @@ Then `openssl dgst -sha256 -verify <key> -signature SHA256SUMS.sig SHA256SUMS`
 and `shasum -a 256 -c SHA256SUMS`. If any step fails: stop, do not install.
 
 ## License
-
-Apache-2.0. Copyright (c) 2026 Leepick Inc, US. Distributed as compiled bundles for convenience.
-
-"Etiquette" and "etq" are trademarks of Leepick Inc, US.
-
+Apache-2.0 (see LICENSE); distributed as compiled bundles for convenience.

package/docs/AGENT_SPAWNING.md

@@ -0,0 +1,78 @@
+# Agent Spawning: inline runners vs provisioned seats
+
+Guidance for **implementing agents** (the seat doing the work): when to spawn a
+helper yourself, when to ask the operator to provision a durable seat, and how
+to bind either one to the workflow. (`OPERATOR_PLAYBOOK.md` is the operator's
+side of this; this file is yours.)
+
+## The two axes — never conflate them
+
+- **Seat** = durable identity + evidence trail. It survives processes, carries
+  the receipts, and owns tasks. Seats are cheap to keep and expensive to blur.
+- **Runner** = an execution process occupying a seat. Disposable by default.
+
+The default pattern is the **hybrid**: bind a *disposable runner* to a
+*durable seat*. The trail persists; the process is throwaway. Discard the
+runner after its return — the seat keeps everything that matters.
+
+## Spawn inline yourself (no operator needed) when ALL hold
+
+- The work is **bounded and one-off**: a single review, an audit, a read-only
+  probe, a parallel fan-out of readers.
+- It's **read-only toward your scope** — a spawned helper must never become a
+  second writer in your own `allowed_writes` (single-writer applies to your
+  spawns too).
+- It can **finish inside your session**: if your process dies, nothing of value
+  dies with it beyond a re-run.
+- You can bind it properly: seat + task + envelope + the same pickup/receipt
+  workflow you follow. An unbound helper produces unaccountable output.
+
+## Ask the operator to provision instead when ANY hold
+
+- The helper will own **repeated lanes over days** — recurring review, a
+  standing monitor, a specialist surface. Durable work deserves a durable
+  session the operator can see, resume, and audit.
+- It needs its **own vendor/model/credentials** (a different provider is often
+  *desirable* for review — and it's the operator's call to provision).
+- It must **outlive you**: long-running watches, anything that should survive
+  your session ending.
+- It would **write product code** anywhere. New writers are an operator
+  decision, always.
+
+Never be shy to ask. A well-formed ask is a sign of a healthy loop, not a
+failure. But ask with a complete provisioning card, not a vibe:
+
+```
+Requesting a provisioned seat:
+  seat:        <id> (new or existing)
+  why durable: <recurring lanes / credentials / outlives-me>
+  first task:  <ref> — envelope ready at <path>
+  worktree:    <prepared path + pinned base>
+  entry:       <the exact join/pickup commands>
+  boundaries:  <read-only? allowed_writes? never merge/push?>
+  vendor hint: <same or deliberately different model — and why>
+```
+
+## Binding rules (both kinds)
+
+- One seat, one active runner per task. If a second runner must take over,
+  it claims *explicitly* (exclusive claim, runner id recorded) — two runners
+  silently emitting as one seat corrupts the trail.
+- Every spawned runner follows the full loop: join → pickup → work → receipt →
+  return. No side-channel results; if it didn't post, it didn't happen.
+- Record provenance: the return should show which runner executed, especially
+  when it isn't the seat's usual occupant.
+- Reviewers return **evidence and proposed amendments — never edits, never
+  merges**. Your spawns inherit your boundaries; they do not inherit your
+  write scope.
+- Disposable means disposable: after the return is posted and verified, the
+  runner is gone. Anything worth keeping is in the receipt, not the process.
+
+## The sequencing instinct (learned from real runs)
+
+- **During implementation**: zero extra writers. Resist "help."
+- **Branch ready**: exactly one reviewer — read-only, ideally a different
+  model/vendor than you.
+- **Recurring specialization emerges** (per-provider adapters, standing
+  audits): *that* is the moment to request provisioned specialist seats —
+  not before.

package/docs/ARCHITECTURE.md

@@ -22,9 +22,9 @@ Execution returns evidence; it never mints authority.
 ```
 
 Execution is a substrate, not an authority layer. In Core it is the local shell,
-worktree, or runner. In Full it may be a runtime cell, EKS/kind sandbox, or
-managed runner. In every profile, execution remains authority-false until the
-promotion gate accepts evidence.
+worktree, or runner. In Full it may be a managed execution container,
+EKS/kind sandbox, or managed runner. In every profile, execution remains
+authority-false until the promotion gate accepts evidence.
 
 ## Authority
 
@@ -52,11 +52,11 @@ role occupants or composite gates and fails closed.
 
 ## Consumers
 
-Consumers may read, render, route bounded work, spawn bounded runners, and return
+Consumers may read, render, route bounded work, start bounded runners, and return
 receipts. They must not grant, close, merge, rewrite ledgers, or become the bus.
 
 Good first consumers are verification-first managed runners, local coding seats,
-context workbenches, dashboards, and MCP readers. Start remote as witness-only.
+context workbenches, dashboards, and MCP readers. Start remote as evidence-only.
 
 ## Package Boundary
 

package/docs/CODEX_CLIENT_COMPATIBILITY.md

@@ -23,7 +23,7 @@ Source: https://developers.openai.com/codex/changelog
 | Remote-runtime app-server/exec-server canaries | `0.141.0` required | Block that canary until upgraded. |
 | Plugin-scoped MCP adapter canaries | `0.141.0` required | Block that canary until upgraded. |
 | Hook/action-auth resume canaries | `0.141.0` required | Block that canary until upgraded. |
-| Usage-budget hygiene before long swarms | `0.140.0` minimum for `/usage` | Advisory only. |
+| Usage-budget hygiene before long multi-runner windows | `0.140.0` minimum for `/usage` | Advisory only. |
 
 ## Operator Check
 

package/docs/CONCEPTS.md

@@ -38,8 +38,8 @@ autonomous execution.
 ## Session
 
 A session is a bounded run inside one repo. Use one for a bug fix, feature
-slice, review, release canary, or short swarm; not for a product, quarter, or
-org.
+slice, review, release canary, or short parallel review window; not for a
+product, quarter, or org.
 
 ## Receipt
 
@@ -52,6 +52,23 @@ A ledger is the durable work record for a repo or workspace: decisions,
 receipts, state changes, and refs. Raw execution chatter belongs in session
 runbooks and scratch space.
 
+### Durable Record vs Query Index
+
+Two surfaces share the ledger name. They are different systems:
+
+| Surface | Path | When it populates |
+| --- | --- | --- |
+| Durable record | `docs/work/ledger/LEDGER.md` | Automatically, as the workflow appends event lines |
+| Query index | `.etiquette/state/ledger/index.db` | Only when you run `etiquette ledger index` |
+
+The durable record is canonical and append-only. The query index is a
+generated, regenerable SQLite cache read by `ledger search` and `ledger show`.
+It ingests typed `schema=ledger-entry.v0*` lines and scanned documents, not
+routine workflow event lines. `ledger_entries: 0` after a full workflow cycle
+means no typed entries exist yet; the durable record is intact. Deleting the
+index loses nothing. See
+`docs/contracts/ledger-entry/ledger-query-cli.v0.1.md`.
+
 ## Promotion Gate
 
 The promotion gate is where candidate work becomes accepted truth.
@@ -82,7 +99,8 @@ runner only through an explicit lease.
 
 A child lease must be a strict subset of the parent lease. The subset covers
 shorter or equal TTL, narrower or equal authority scope, subset write paths,
-subset tools, inherited prohibitions, reduced spawn budget, and reduced depth.
+subset tools, inherited prohibitions, reduced child-runner budget, and reduced
+depth.
 
 Children return to their immediate parent. The parent synthesizes one upstream
 receipt and remains accountable for child cleanup. A child or headless node is
@@ -91,7 +109,7 @@ not a durable seat unless it is separately enrolled and passes readiness.
 ## Exec
 
 Exec is any runtime that does work: a local shell, Codex, Claude Code, Gemini,
-Ollama, a script, a container, or a remote runtime cell.
+Ollama, a script, a container, or a managed execution container.
 
 Exec may run, observe, retry safe work, and return evidence. Exec must not
 grant, merge, close, promote, or mutate canonical truth.
@@ -126,4 +144,3 @@ Portals display and coordinate.
 Integrations project refs.
 Execution returns evidence; it never mints authority.
 ```
-

package/docs/CORE_PROFILE.md

@@ -37,7 +37,8 @@ Core records, validates, gates, and dispatches:
 
 Full remembers, consolidates, marinates, and projects. Memory stores,
 consolidation rollups, marination modules, hosted portals, secure screening,
-remote runtime cells, and sharded drains belong there unless explicitly enabled.
+managed execution containers, and sharded drains belong there unless explicitly
+enabled.
 
 Use:
 
@@ -63,7 +64,8 @@ The Core promotion path is:
 5. The ledger records the promoted result.
 
 At Core scale, Git is the promotion mechanism. Drains, sharded import, hosted
-planes, and runtime cells belong to the Full profile unless explicitly enabled.
+planes, and managed execution containers belong to the Full profile unless
+explicitly enabled.
 
 Core commands may advise, check, and record evidence. They do not authorize
 work, attach grants, merge, close lanes, or promote candidates without the

package/docs/INTEGRATION_UI.md

@@ -0,0 +1,215 @@
+# Integrating a UI/Consumer with the Event Log and Packets
+
+How to build a read-model or composer UI (inbox, thread view, approvals queue,
+seat roster) over an Etiquette project. Three file surfaces, all in one git
+repo. The consumer is a read-model plus composer over them, never a writer of
+record.
+
+```text
+<project>/
+├── .etiquette/events/local.ndjson   # the EVENT LOG (append-only, seq-ordered)
+├── docs/work/packets/*.json         # the PACKETS (one file per message)
+├── docs/work/ledger/LEDGER.md       # the durable record (see CONCEPTS.md)
+└── (ordinary git)                   # commits are durability; push is visibility
+```
+
+## 1. Event Schema (`local-event.v0`)
+
+Every emitted packet post appends exactly one event line (ndjson, one JSON
+object per line). Events are the index; packets are the content.
+
+| field | type | notes |
+| --- | --- | --- |
+| `seq` | int | global monotonic sequence. THE ordering key. Never reuse, never renumber. |
+| `schema` | string | `local-event.v0` |
+| `event_ref` | string | `local://event/<seq>` — the durable ref other records cite |
+| `created_at` | ISO8601 UTC | emit time |
+| `type` | string | event kind, e.g. `packet_posted` |
+| payload | spread | packet fields are spread into the event: `role`, `lane`, `from`, `to`, `next_owner`, `verdict`, `mode`, `packet_tier`, `packet_ref`, `changes_state`, and optionally `requires_ack`, `in_reply_to` |
+
+Reader rules (learned the hard way):
+
+- Track position by `seq` cursor, never by byte offset or `tail -F`. Git
+  operations can rewrite the file and replay it from line 1.
+- Read through the CLI where possible: `etiquette notify poll --seat <id>
+  --after-seq <n>`, `etiquette bus view`, `etiquette timeline view`,
+  `etiquette status`. The write side must go through `etiquette post` — it
+  owns field validation, the event append lock, and the ledger mirror.
+- Badge authority acts (decisions, grants) differently from routine traffic.
+  Key on the packet `role` and `verdict`, not on `changes_state` (see drift
+  note D5).
+
+## 2. Packet Spec (`local-packet.v0`)
+
+One JSON file per message, written by `etiquette post` to
+`docs/work/packets/<created_at>-<lane>-<role>.json`. With `--emit` (implied
+for return roles) the post also appends a `packet_posted` event and mirrors a
+line into the durable ledger record.
+
+```json
+{
+  "schema": "local-packet.v0",
+  "role": "dispatch",
+  "lane": "wire-real-search-01",
+  "from": "team-orchestrator",
+  "to": "team-implementer-1",
+  "verdict": "routed",
+  "packet_tier": "3",
+  "mode": "product-implementation",
+  "next_owner": "team-implementer-1",
+  "created_at": "2026-07-11T09:00:12.000Z",
+  "changes_state": true,
+  "authority_boundary": {
+    "packet_authorizes_work": false,
+    "can_merge": false,
+    "can_close": false,
+    "can_grant": false
+  }
+}
+```
+
+Field notes:
+
+- `role` — the message class. Conventional values: `dispatch`, `task-bundle`,
+  `implementation-return`, `review-return`, `counter`, `advisory`, `decision`,
+  `acknowledge`. Return roles always emit an event.
+- `mode` — the authority class of the referenced work (see section 5).
+- `next_owner` — who acts next; load-bearing for routing and wake queues.
+- `packet_tier` — a string (`"2"` or `"3"`); governs how much body discipline
+  the packet's narrative carries (section 3).
+- `authority_boundary` — always present, always false-by-default. A packet
+  never authorizes work by itself.
+
+The write-scope envelope (what a task may touch) does not live in the packet.
+It lives in the task bundle (`task-bundle.v1`): `allowed_writes` (required),
+`validation` (required), `stop_conditions`, `forbidden_sources`,
+`expected_return`, `evidence_sink`, `authority_boundary`. Packets reference
+the lane/task; the bundle carries the envelope.
+
+## 3. Body Discipline by Tier
+
+Packets shipped by this CLI are compact JSON. When a deployment pairs packets
+with markdown narrative bodies (correspondence artifacts), the tier rules
+below are the required section headings. Composers should emit them exactly;
+a suffix on a heading (`## Evidence Cited from X`) is the classic papercut.
+
+| tier | required `##` headings | extra rule |
+| --- | --- | --- |
+| 2 | `## Verdict` (or `## Disposition`) + `## Evidence` + `## Next owner` | body <= 50 lines |
+| 3 | tier-2 set plus `## Failure modes` + `## Confidence calibration` | — |
+
+Note: this package does not lint markdown bodies today (drift note D4). Treat
+the table as the portable packet-body convention a composer should enforce
+client-side.
+
+## 4. Sample Thread
+
+A synthetic six-event thread covering every UI moment (dispatch, ack with a
+runner swap, a stop-condition counter, an amended scope, a verified return,
+and a human decision) ships in source checkouts as
+`fixtures/ui-thread-example.json`. Fixtures are excluded from the published
+package; use a source checkout. The fixture carries a `summary` convenience
+field (extra payload, drift note D8) so list views have something to render.
+
+Render test for a consumer:
+
+- The thread reads as a conversation (`in_reply_to` chains to `event_ref`).
+- The runner-swap badge shows where `execution_seat` differs from
+  `durable_owner`.
+- The counter (a guardrail firing) is visually distinct — celebrate it, do
+  not bury it.
+- Exactly one event is an authority act (the `decision` role).
+
+## 5. The Envelope Model (what an approval UI must understand)
+
+Four separate axes — never collapse them into one "agent type":
+
+| axis | values | meaning |
+| --- | --- | --- |
+| coordination shape | `solo` \| `tango` \| `rig` \| `shadow` | one runner / pair-with-reviewer / fan-out / observe-only |
+| `mode` (authority class) | `read-only-audit` \| `docs-only` \| `product-implementation` | what the seat may WRITE |
+| perimeter | local \| sandboxed \| managed | WHERE it executes (never a topology) |
+| risk posture | derived | from mode + write breadth + irreversibility + credentials/network + data sensitivity |
+
+Authority doctrine the UI must encode, not just display:
+
+- Agent-produced artifacts are authority-false. They cross into effect only
+  via a human decision. An approval screen renders the authority-false
+  artifact plus its evidence and captures the human decision as a new packet.
+- Single-writer: one routed owner mutates a canonical surface at a time;
+  reviewers contribute evidence packets, never competing mutations.
+- Dynamic execution, static authority: automation may advance work; only the
+  principal crosses merge/promote/ratify/spend gates. No auto-approval, ever.
+  An adapter or app synthesizing a decision is the named number-one failure
+  mode.
+- Landing/merging is always the principal's act; seats hand branches back.
+
+## 6. Composer Requirements (where a consumer earns its keep)
+
+1. Emit valid packets: real `role`, valid `mode`, `next_owner` always set,
+   envelope present in the task bundle for `product-implementation` work.
+2. Post through the CLI. `etiquette post --emit` performs the packet write,
+   event append (under the event lock), and ledger mirror as one act. The git
+   commit remains the operator's act — surface uncommitted
+   `.etiquette/events/` and `docs/work/` state prominently; a dirty canonical
+   surface blocks other seats' workflow steps.
+3. Thread rendering: chain packets by `in_reply_to` / `event_ref` into a
+   conversation view (dispatch, counter, amend, return, confirm, decision).
+4. Badges: model/provider identity, runner-vs-seat occupancy, authority
+   (`role`, `mode`), and verification level (self-reported vs
+   second-party-verified — a return another seat re-ran is gold).
+5. Envelope-aware diff review: when reviewing a branch, show the diff against
+   the bundle's `allowed_writes` — out-of-scope files are instant red flags.
+6. Never write canon autonomously. The app composes; the human sends.
+
+## 7. Format Drift Notes
+
+This document descends from a spec written against a markdown-packet bus.
+Where that ancestor and this package disagree, this package's shipped formats
+win. Known drift, kept honest rather than papered over:
+
+- D1. Ancestor events carried `at`/`actor`/`action`/`packet_id`/`message`;
+  shipped `local-event.v0` uses `created_at`/`from`/`type` plus packet fields,
+  and has no self-contained `message` summary field.
+- D2. Ancestor refs used a bus URI scheme keyed by bare seq; shipped refs are
+  `local://event/<seq>` in `event_ref` and `in_reply_to`.
+- D3. Ancestor packets were markdown with YAML frontmatter named
+  `<timestamp>-<actor>-<slug>.md`; shipped packets are JSON
+  `local-packet.v0` files named `<created_at>-<lane>-<role>.json`.
+- D4. Ancestor tier headings were lint-enforced at post time; this package
+  does not lint markdown bodies. `packet_tier` is also a string here, not an
+  int.
+- D5. Ancestor `changes_state` meant "authority act". The shipped `post`
+  command sets `changes_state` to whether the packet was emitted to the event
+  log, so every `packet_posted` event carries `changes_state: true`. Until
+  this is reconciled, consumers must badge authority from `role`/`verdict`,
+  not `changes_state`.
+- D6. Ancestor `mode` enum had a fourth value, `dirty-tree-extraction`; this
+  package ships three modes.
+- D7. Ancestor envelopes (`repo`, `base_commit`, `branch`, `worktree_path`)
+  rode in packet frontmatter; the shipped envelope lives in `task-bundle.v1`
+  and does not include those four fields — base pinning and worktree layout
+  are handled at the git/CLI layer.
+- D8. `cc`, `workflow_id`, `slice_id`, `content_class` (on packets), `summary`,
+  and the provenance fields `durable_owner`, `execution_seat`, `executed_by`,
+  `actual_model`, `operator_principal` have no shipped writer in `post`.
+  Events tolerate them as extra payload; projections surface only some. Treat
+  them as optional until promoted.
+
+## 8. Glossary
+
+- **seat** — durable agent identity plus authority envelope; provider-agnostic.
+- **packet** — one message on the log; the unit of coordination.
+- **lane / slice** — a thread of work / one bounded task within it.
+- **envelope** — the write-scope + validation + stop-condition contract a task
+  runs under (carried by the task bundle).
+- **harvest** — a defect found out of scope: recorded and routed, never fixed
+  inline.
+- **receipt** — evidence attached to a return (commands run, output tails,
+  SHAs).
+- **landing** — principal-gated merge to the default branch.
+- **lease** — a seat's time-bounded authority to occupy a task.
+- **promotion gate** — the human decision point where an authority-false
+  artifact becomes effective.
+
+See `docs/CONCEPTS.md` for the core vocabulary these one-liners compress.

package/docs/OPERATOR_PLAYBOOK.md

@@ -0,0 +1,77 @@
+# Operator Playbook
+
+You are the principal. Agents execute; **you decide.** This is the when-X-do-Y
+card for running the workflow on the go. (`AGENTS.md` tells agents how to
+behave — this file tells *you* what move to make.)
+
+## Starting work
+
+- **Before dispatching, shape the task**: one agent or several? does review need
+  a separate mind? is checking cheap? If it's a judgment call — keep it yourself.
+- **Write the envelope, always**: `allowed_writes`, validation, stop conditions,
+  pinned base commit. The envelope *is* the speed — it's what lets an agent run
+  unattended and lets you trust the result.
+- **One task, one worktree, one branch.** Never work on a shared checkout.
+
+## While an agent works
+
+- **Don't add a second writer to the same scope.** Design can be parallel;
+  writing is single-writer. Resist "helping" in its files.
+- **Don't steer mid-run.** Post an amendment packet instead; the agent's
+  stop-conditions are your remote control.
+- Long silence ≠ progress. Check the session notes, not the vibe.
+
+## When a return arrives
+
+- **An agent STOPPED or COUNTERED? That is the system working.** Read its
+  evidence, then uphold or amend — never bulldoze past it. A lying green is
+  worse than an honest red.
+- **Self-reported evidence is a claim, not a proof.** Before landing anything
+  that matters, get a second party to re-run the checks — runtime proof beats
+  reading code beats trusting a summary.
+- **Review the diff against the envelope**: files outside `allowed_writes` are
+  red flags even when the code looks good.
+
+## The reviewer moment (the most-missed nudge)
+
+- **Branch ready → spin exactly one reviewer.** Read-only audit, a *different*
+  model/vendor than the implementer, returning evidence and proposed
+  amendments — never edits, never merges.
+- Never be shy to add **reviewers**; be very shy to add **writers**.
+- A good implementing agent will *ask* you for a reviewer at the right moment.
+  Honor the shape it proposes.
+
+## Gates (yours alone)
+
+- Merging, closing, promoting, granting scope, spending money, touching
+  credentials or production — these never delegate. An agent that "just did it"
+  is a defect, not initiative.
+- Before approving: read the evidence, not the summary line.
+- Anything needing secrets, network egress, or real user data is a *perimeter
+  decision*, not a task detail. Stop and decide it explicitly.
+
+## Hygiene, on the go
+
+- Lost? `etq whereami`. Broken? `etq doctor`.
+- Finish your posts: a half-committed event blocks every other seat.
+- Don't leave counters unanswered overnight — a stopped agent is parked
+  capacity waiting on *you*.
+- The urge to skip the envelope for "a quick fix" is how quick fixes become
+  incidents. Small task, small envelope — but an envelope.
+
+## The human gate ("what now?")
+
+- When an agent stops and waits, ask: **is this a stall or a gate?** A good
+  agent tells you; if it doesn't, ask "gate or stalled?" before nudging.
+- **"continue" / "proceed" are nudges, not authority.** Never let them double
+  as approval. A gated act needs its own *named phrase* — a good agent mints
+  one ("say 'accept and land' to merge"); echo it exactly or refuse it.
+- At a gate, demand the card: what's decided, the options, the evidence, the
+  phrase. Deciding from a summary line is how gates rubber-stamp themselves.
+
+## When you're the bottleneck
+
+- Triage by type: **decisions** (only you) → **reviews** (route one reviewer) →
+  **FYI** (skim). Work the decisions first.
+- If the same nudge keeps recurring, it belongs in a stop-condition or a
+  template — encode it once instead of remembering it nightly.

package/docs/README.md

@@ -11,6 +11,7 @@ References:
 
 - [CODEX_CLIENT_COMPATIBILITY.md](CODEX_CLIENT_COMPATIBILITY.md)
 - [RELEASE_SURFACE_AUDIT.md](RELEASE_SURFACE_AUDIT.md)
+- [INTEGRATION_UI.md](INTEGRATION_UI.md) — building a UI/consumer over the event log and packets
 
 Source checkouts also keep hosted parity, portal, managed-runtime parity, and root kernel notes for
 maintainers. They are not part of the local devkit tarball.

package/docs/SEAT_PROVISIONING.md

@@ -7,7 +7,7 @@ Start with one project owner and one review seat. Add runtime-specific seats onl
 1. Install project-local agent guidance with `setup`.
 2. Initialize the project with `bootstrap local`.
 3. Read `AGENTS.md`, `BOARD.md`, `SESSION_PICKUP.md`, and `SEAT_OPERATING_MANUAL.md`.
-4. Run `whereami`, `doctor`, and `status`.
+4. After resume or runner/model swaps, run `resume check`; otherwise run `whereami`, `doctor`, and `status`.
 5. Confirm the lead and review seats.
 6. Use `$etiquette-seat-lifecycle` before pickup after stale context, resume, runner/model/profile swaps, or workflow migration.
 7. Have the lead seat `join` and `pickup` the first generated task.
@@ -18,6 +18,7 @@ Start with one project owner and one review seat. Add runtime-specific seats onl
 ```sh
 etiquette setup --target codex --project "$PWD"
 etiquette bootstrap local --project "$PWD" --profile codex-cc-gemini --task-prefix APP
+etiquette resume check --project "$PWD" --seat codex-seat --task APP-001 --json
 etiquette whereami --project "$PWD" --seat codex-seat --task APP-001
 etiquette doctor --project "$PWD"
 etiquette status --project "$PWD"
@@ -96,5 +97,4 @@ Remote execution is a later layer. Plane provisioning is infra-admin scoped. Wor
 - Start with the smallest useful topology.
 - Add seats because work requires them.
 - Product-write authority requires a task, allowed writes, validation, and the right promotion gate.
-- Chat is not canonical record.
-- Runtime packs are adapters, not doctrine.
+- Chat is not canonical record; runtime packs are adapters, not doctrine.

package/docs/TAG_ROUTE.md

@@ -0,0 +1,95 @@
+# Tag-Route v0 — paste a thread, get a bounded draft card
+
+Tag-Route turns a pasted chat thread into a **draft task-bundle.v1 card**.
+It is an entry door into the existing card lifecycle, not a new lifecycle:
+drafts are non-canonical until promoted through normal pickup/return
+discipline, and nothing in this path grants authority.
+
+## Vocabulary: card vs bundle
+
+- **Task card** (`task-envelope.v0`) — the local work envelope under
+  `docs/work/tasks/`. Pickup, allowed writes, validation, receipts.
+- **Task bundle** (`task-bundle.v1`) — the same envelope lineage, extended
+  with namespaced interop fields (`strategy_policy`, `execution_hints`,
+  `requirements`, `preflight_refs`, `budgets`, `provenance_window`,
+  `requested_by`). Every shipped task card already validates as a bundle.
+- Bundles are **strictly declarative**. Script-bearing fields
+  (`pre_execute`, `run`, `shell`, `script`, `hooks`, ...) are rejected.
+  Bundles may only *reference* preflights the executor already holds
+  (`etq://preflights/<id>`); unknown refs refuse pickup.
+
+## Registries (declared, admin-signed, verified-never-authored)
+
+- `.etiquette/bindings.yaml` — `channel-binding-registry.v1`. Each
+  `channel-binding.v1` entry binds a chat channel to one repository, the
+  write envelope compiled cards may declare, and the seat to notify.
+- `.etiquette/roster/mappings.yaml` — `roster-mapping-registry.v1`. Each
+  `roster-mapping.v1` entry maps a chat user id to a seat card ref.
+
+Unknown channel and unknown requesting user are refusals, not fallbacks.
+
+## Walkthrough: paste a thread
+
+1. Declare the registries once (admin act):
+
+   ```yaml
+   # .etiquette/bindings.yaml
+   schema: channel-binding-registry.v1
+   bindings:
+     - schema: channel-binding.v1
+       channel_id: team-help
+       repository_ref: github.example/org/demo-app
+       allowed_writes: [src/checkout/**]
+       notify_ref: impl-seat
+       admin_signature: sha256:<hex>
+   ```
+
+2. Verify them any time:
+
+   ```sh
+   etiquette tag bindings verify --project .
+   etiquette tag roster resolve U12345 --project .
+   ```
+
+3. Save the chat thread as plain text, one `<user>: <message>` per line,
+   then compile (or pipe it via `-`):
+
+   ```sh
+   etiquette tag compile thread.txt --channel team-help --project .
+   ```
+
+4. The compiled draft lands under `docs/work/drafts/<task-id>.yaml` with
+   `content_class: draft` and `authority: "false"`. Compile is the
+   canonicalization moment: the card cites its `provenance_window`
+   (line range + sha256 of the transcript slice) so chat-sourced context
+   stays auditable without ever becoming a startup doc.
+
+5. The bound seat gets a wake notice on the existing notify queue
+   (`etiquette notify poll --seat impl-seat`). Promotion of the draft into
+   a real task card remains a separate, gated act by an authorized seat.
+
+## Refusals (machine-checked)
+
+- Channel not in `bindings.yaml` -> `unknown channel`.
+- Requesting user (first speaker, or `--user`) not in the roster ->
+  `unknown requesting user` plus an enrollment hint.
+- Execution content in the window (script-bearing directives, fenced
+  shell blocks) -> `execution content rejected`. The final card is also
+  re-validated against the bundle schema, which rejects script-bearing
+  fields wherever they nest.
+
+## Security contract: executor inertness
+
+The pickup/return executor treats the envelope as data. The only executable
+surfaces are `validation` (sanctioned gate commands) and executor-held
+`preflight_refs`. Every other field — `execution_strategy`, `rig_conductor`,
+`topology_constraints`, `expected_return`, and any nested script-bearing key —
+is inert: read, projected, printed, never executed. The executor spawns only
+hard-coded programs; no shell interprets a bundle string. Pinned by
+`contracts/tag-route-inertness.test.ts` (behavioral trap + static pin).
+
+## Out of scope in v0
+
+The always-on chat listener is a hosted-plane concern and ships
+separately. It will call this same compile path; nothing in v0 assumes it
+exists. A pasted transcript keeps the whole flow local and testable.