@etiquekit/etq 0.0.1 → 1.0.4

package/templates/etiquette-vanilla-v0/source/control-seat/docs/work/access/workspace-secure-profile.v0.json

@@ -0,0 +1,53 @@
+{
+  "schema": "workspace-secure-profile.v0",
+  "workspace_id": "vanilla-control-seat",
+  "mode": "open",
+  "allowed_modes": [
+    "open",
+    "screening-warn",
+    "screening-enforced",
+    "enterprise-reactor"
+  ],
+  "mode_meanings": {
+    "open": "No access-assurance gate is required. Etiquette core remains local and unauthenticated.",
+    "screening-warn": "Restricted-seat claims are checked and reported, but missing or failed claims do not block local entry.",
+    "screening-enforced": "Restricted-seat claims are required before routing or entering restricted seats.",
+    "enterprise-reactor": "screening-enforced plus an optional tighten-only reactor for revocation sync, badge refresh, kill-switch writes, and outbox drain."
+  },
+  "identity_model": {
+    "authenticate": "operator_principals",
+    "assign_to": "seat_ids",
+    "authorize": "per_action_grants",
+    "workspace_role": "policy_scope",
+    "linear_role": "external_backlog_projection_only"
+  },
+  "claim_source": {
+    "kind": "none-required-for-open-mode",
+    "live_replacement": "Supabase Auth plus derived Persona and Scandit claim export",
+    "raw_pii_allowed_in_repo": false
+  },
+  "reactor": {
+    "required_for_mode": "enterprise-reactor",
+    "default_enabled": false,
+    "tighten_only": true,
+    "may_write": [
+      "kill_switch_entries",
+      "expired_assurance_markers",
+      "badge_refresh_cache",
+      "sync_outbox"
+    ],
+    "must_not": [
+      "grant_access",
+      "close_work",
+      "merge",
+      "rewrite_ledger",
+      "authorize_actions"
+    ]
+  },
+  "authority_boundary": {
+    "profile_can_authorize_work": false,
+    "profile_can_grant_seat": false,
+    "profile_can_merge_or_close": false,
+    "reactor_can_grant_or_loosen_access": false
+  }
+}

package/templates/etiquette-vanilla-v0/source/control-seat/docs/work/ledger/LEDGER.md

@@ -0,0 +1,7 @@
+# Control Seat Ledger
+
+| id | status | owner | title | validation |
+| --- | --- | --- | --- | --- |
+| CONTROL-001 | open | control-seat | Prove vanilla Etiquette startup | `sh bin/seat-doctor` |
+
+Receipts live under `docs/work/receipts/`.

package/templates/etiquette-vanilla-v0/source/control-seat/docs/work/playbacks/PLAYBACK_TEMPLATE.md

@@ -0,0 +1,31 @@
+# Manual Playback Template
+
+```yaml
+playback_id:
+timeframe:
+scope:
+operator_principal:
+execution_seat:
+inputs:
+  receipts: []
+  ledger_refs: []
+  commit_refs: []
+decisions:
+  - decision:
+    evidence_refs: []
+lessons:
+  - lesson:
+    evidence_refs: []
+deferred:
+  - item:
+    reason:
+proposed_actions:
+  - action:
+    type: no_change | docs_patch | memory_save | controlled_drill
+    evidence_refs: []
+operator_decision_required:
+  controlled_drill: true
+  batch_approval_allowed: false
+```
+
+Use this after meaningful workflow change. Keep it evidence-bound: cite receipts, ledger rows, commits, and validation output. Do not treat chat as proof.

package/templates/etiquette-vanilla-v0/source/control-seat/docs/work/receipts/.gitkeep

@@ -0,0 +1 @@
+

package/templates/etiquette-vanilla-v0/source/control-seat/docs/work/tasks/CONTROL-001.yaml

@@ -0,0 +1,13 @@
+id: CONTROL-001
+status: open
+owner: control-seat
+mode: docs-only
+title: Prove vanilla Etiquette startup
+purpose:
+  - validate the control seat without provisioning runtime-specific seats
+validation:
+  - sh bin/seat-doctor
+expected_return:
+  - readiness receipt
+  - decision whether more seats are needed
+

package/templates/etiquette-vanilla-v0/source/etiquette-kernel/README.md

@@ -0,0 +1,6 @@
+# Etiquette Kernel
+
+Shared contracts and validation vocabulary for Etiquette.
+
+The kernel is runtime-neutral. It does not assume Claude Code, Codex, Gemini, Slack, GitHub, or a hosted service.
+

package/templates/etiquette-vanilla-v0/source/etiquette-kernel/bin/kernel-doctor

@@ -0,0 +1,11 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+
+test -f "$ROOT/contracts/receipt.v0.md"
+test -f "$ROOT/contracts/playback.v0.md"
+test -f "$ROOT/contracts/seat-readiness.v0.md"
+test -f "$ROOT/contracts/task.v0.md"
+
+echo "etiquette-kernel: ok"

package/templates/etiquette-vanilla-v0/source/etiquette-kernel/contracts/playback.v0.md

@@ -0,0 +1,37 @@
+# Playback V0
+
+A playback is a manual review of evidence after meaningful workflow change.
+It interprets receipts; it does not replace receipts.
+
+```yaml
+playback_id:
+timeframe:
+scope:
+operator_principal:
+execution_seat:
+inputs:
+  receipts: []
+  ledger_refs: []
+  commit_refs: []
+decisions:
+  - decision:
+    evidence_refs: []
+lessons:
+  - lesson:
+    evidence_refs: []
+deferred:
+  - item:
+    reason:
+proposed_actions:
+  - action:
+    type: no_change | docs_patch | memory_save | controlled_drill
+    evidence_refs: []
+```
+
+Rules:
+
+- Receipts are evidence.
+- Playback interprets evidence.
+- Controlled drills require one operator approval per drill.
+- Advisory sources may be referenced, but they are not proof.
+- Automation waits until manual playback shows a repeated gap.

package/templates/etiquette-vanilla-v0/source/etiquette-kernel/contracts/receipt.v0.md

@@ -0,0 +1,25 @@
+# Receipt V0
+
+Every meaningful task returns a compact receipt.
+
+```yaml
+task_id:
+operator_principal:
+execution_seat:
+status: success | partial | blocked | failed
+sources_read: []
+files_changed: []
+validation: []
+risks: []
+next_owner:
+# Optional when compacting local events into a receipt:
+compaction:
+  scope: local-only
+  event_log:
+  event_count:
+  first_seq:
+  last_seq:
+  last_action:
+```
+
+Receipts are durable. Chat is not canonical evidence.

package/templates/etiquette-vanilla-v0/source/etiquette-kernel/contracts/seat-readiness.v0.md

@@ -0,0 +1,22 @@
+# Seat Readiness V0
+
+Each seat reports capability before receiving work.
+
+```yaml
+seat:
+seat_type: control_seat | execution_seat | review_seat | kernel_maintainer | seat_maintainer
+execution_surface:
+declared_by: operator_principal | config
+capability_source: config | local_validation
+operational_status: operational | degraded | blocked | offline
+worker_capacity:
+parallel_support: true | false
+supported_strategies: []
+blocked_strategies: []
+validation: []
+constraints: []
+last_checked_at:
+```
+
+Unsupported strategies hard-block only when `strategy_policy: required`.
+Agent confidence is not proof of capability. Capability is operator/config declared and backed by local validation.

package/templates/etiquette-vanilla-v0/source/etiquette-kernel/contracts/task.v0.md

@@ -0,0 +1,18 @@
+# Task V0
+
+A task says what to do, what may change, and how to validate completion.
+
+```yaml
+task_id:
+owner:
+mode: read-only | docs-only | implementation | review
+repo:
+allowed_writes: []
+forbidden_sources: []
+validation: []
+stop_conditions: []
+expected_return: []
+```
+
+Tasks should be small enough that a receipt can prove what happened.
+

package/templates/etiquette-vanilla-v0/validate-vanilla.sh

@@ -0,0 +1,43 @@
+#!/bin/sh
+set -eu
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+
+test -f "$ROOT/README.md"
+test -d "$ROOT/source/etiquette-kernel"
+test -d "$ROOT/source/control-seat"
+grep -Fq ".etiquette/events/*.ndjson" "$ROOT/source/control-seat/.gitignore"
+grep -q '"schema": "workspace-secure-profile.v0"' "$ROOT/source/control-seat/docs/work/access/workspace-secure-profile.v0.json"
+grep -q '"mode": "open"' "$ROOT/source/control-seat/docs/work/access/workspace-secure-profile.v0.json"
+grep -q "enterprise-reactor" "$ROOT/source/control-seat/docs/work/access/ACCESS-ASSURANCE.md"
+grep -q "Controlled drills require one operator approval per drill" "$ROOT/source/etiquette-kernel/contracts/playback.v0.md"
+grep -q "batch_approval_allowed: false" "$ROOT/source/control-seat/docs/work/playbacks/PLAYBACK_TEMPLATE.md"
+
+sh "$ROOT/source/etiquette-kernel/bin/kernel-doctor"
+sh "$ROOT/source/control-seat/bin/seat-doctor"
+sh "$ROOT/source/control-seat/bin/access-assurance-check" | grep -q "mode=open"
+
+tmp_root=$(mktemp -d "${TMPDIR:-/tmp}/etiquette-vanilla-compact.XXXXXX")
+trap 'rm -rf "$tmp_root"' EXIT
+
+cp -R "$ROOT/source/control-seat/." "$tmp_root/control-seat/"
+sh "$tmp_root/control-seat/bin/seat-init" --execution-seat control-seat >/dev/null
+sh "$tmp_root/control-seat/bin/access-assurance-check" | grep -q "mode=open"
+sh "$tmp_root/control-seat/bin/session-init" --task-id SESSION-INIT --operator local-operator >/tmp/session-init.out
+test -f "$tmp_root/control-seat/.etiquette/state/session.json"
+grep -q "session_opened" "$tmp_root/control-seat/docs/work/ledger/LEDGER.md"
+sh "$tmp_root/control-seat/bin/local-event" CONTROL-001 control-seat started "started local proof"
+sh "$tmp_root/control-seat/bin/local-event" CONTROL-001 control-seat validated "ran seat doctor"
+sh "$tmp_root/control-seat/bin/local-event" CONTROL-001 control-seat completed "ready to compact"
+sh "$tmp_root/control-seat/bin/compact-local-events" CONTROL-001 success
+
+receipt="$tmp_root/control-seat/docs/work/receipts/CONTROL-001-receipt.yaml"
+test -f "$receipt"
+grep -q "scope: local-only" "$receipt"
+grep -q "operator_principal: local-operator" "$receipt"
+grep -q "execution_seat: control-seat" "$receipt"
+grep -q "event_count: 3" "$receipt"
+grep -q "first_seq: 2" "$receipt"
+grep -q "last_seq: 4" "$receipt"
+
+echo "etiquette vanilla: ok"

package/templates/github-actions/README.md

@@ -0,0 +1,30 @@
+# GitHub Actions Templates
+
+These templates are opt-in canaries. Copy one into a disposable repository
+before using it on a production repo.
+
+## W1 Webhook Wake Canary
+
+`w1-webhook-wake-canary.yml` proves the W1 receiver loop inside GitHub Actions:
+
+1. read the GitHub push event payload;
+2. sign it with a canary HMAC secret;
+3. call `etiquette notify webhook github`;
+4. verify the emitted wake points at the pushed commit;
+5. fetch the commit from Git before treating the wake as useful.
+
+Required secret:
+
+- `ETIQUETTE_GITHUB_WEBHOOK_SECRET`: canary HMAC secret used only for this proof.
+
+Choose one CLI source:
+
+- set repository variable `ETIQUETTE_CLI` to an installed command such as
+  `etiquette`; or
+- set repository variable `ETIQUETTE_SOURCE_REPOSITORY` and secret
+  `ETIQUETTE_REPO_TOKEN` so the workflow can check out the Etiquette source
+  read-only.
+
+Boundary: the workflow emits a pointer-only wake artifact and step summary. It
+does not install a public webhook, call AWS/SNS/SQS, post to Slack, run remote
+agents, merge, close, publish, or grant authority.

package/templates/github-actions/w1-webhook-wake-canary.yml

@@ -0,0 +1,111 @@
+name: Etiquette W1 webhook wake canary
+
+on:
+  push:
+    branches:
+      - "**"
+
+permissions:
+  contents: read
+
+env:
+  ETIQUETTE_CLI: ${{ vars.ETIQUETTE_CLI }}
+
+jobs:
+  w1-webhook-wake:
+    name: Signed push payload to pointer-only wake
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout canary repo
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Setup Bun
+        if: ${{ env.ETIQUETTE_CLI == '' }}
+        uses: oven-sh/setup-bun@v2
+
+      - name: Check Etiquette source configuration
+        if: ${{ env.ETIQUETTE_CLI == '' }}
+        env:
+          ETIQUETTE_SOURCE_REPOSITORY: ${{ vars.ETIQUETTE_SOURCE_REPOSITORY }}
+        run: |
+          test -n "${ETIQUETTE_SOURCE_REPOSITORY:-}" || {
+            echo "Set ETIQUETTE_CLI, or set ETIQUETTE_SOURCE_REPOSITORY plus ETIQUETTE_REPO_TOKEN."
+            exit 1
+          }
+
+      - name: Checkout Etiquette source
+        if: ${{ env.ETIQUETTE_CLI == '' }}
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ vars.ETIQUETTE_SOURCE_REPOSITORY }}
+          ref: main
+          path: .etq/etiquette
+          token: ${{ secrets.ETIQUETTE_REPO_TOKEN }}
+
+      - name: Install Etiquette source dependencies
+        if: ${{ env.ETIQUETTE_CLI == '' }}
+        working-directory: .etq/etiquette
+        run: bun install --frozen-lockfile
+
+      - name: Verify signed wake and Git ref
+        env:
+          ETIQUETTE_GITHUB_WEBHOOK_SECRET: ${{ secrets.ETIQUETTE_GITHUB_WEBHOOK_SECRET }}
+        run: |
+          set -eu
+          test -n "${ETIQUETTE_GITHUB_WEBHOOK_SECRET:-}" || {
+            echo "ETIQUETTE_GITHUB_WEBHOOK_SECRET is required."
+            exit 1
+          }
+
+          ETQ_CMD="${ETIQUETTE_CLI:-bun $GITHUB_WORKSPACE/.etq/etiquette/packages/control/src/cli.ts}"
+          SIGNATURE="$(node <<'NODE'
+          const crypto = require('node:crypto');
+          const fs = require('node:fs');
+          const payload = fs.readFileSync(process.env.GITHUB_EVENT_PATH);
+          const secret = process.env.ETIQUETTE_GITHUB_WEBHOOK_SECRET;
+          process.stdout.write(`sha256=${crypto.createHmac('sha256', secret).update(payload).digest('hex')}`);
+          NODE
+          )"
+
+          ${ETQ_CMD} notify webhook github \
+            --payload "$GITHUB_EVENT_PATH" \
+            --delivery "$GITHUB_RUN_ID" \
+            --event push \
+            --signature-256 "$SIGNATURE" \
+            --json > w1-wake.json
+
+          node <<'NODE'
+          const fs = require('node:fs');
+          const wake = JSON.parse(fs.readFileSync('w1-wake.json', 'utf8'));
+          const sha = process.env.GITHUB_SHA;
+          if (wake.schema !== 'github-webhook-wake.v0') throw new Error('unexpected wake schema');
+          if (wake.after !== sha) throw new Error(`wake.after ${wake.after} did not match GITHUB_SHA ${sha}`);
+          if (wake.transport.webhook_payload_trusted_as_truth !== false) throw new Error('payload truth boundary drifted');
+          if (wake.transport.receiver_must_fetch_and_verify !== true) throw new Error('fetch/verify boundary missing');
+          if (wake.payload_boundary.pointers_only !== true) throw new Error('pointer-only boundary drifted');
+          if (wake.authority_boundary.notification_is_authority !== false) throw new Error('authority boundary drifted');
+          NODE
+
+          git fetch --no-tags --depth=1 origin "$GITHUB_SHA"
+          test "$(git rev-parse FETCH_HEAD)" = "$GITHUB_SHA"
+          git cat-file -e "$GITHUB_SHA^{commit}"
+
+          {
+            echo "### Etiquette W1 wake canary"
+            echo ""
+            echo "- schema: github-webhook-wake.v0"
+            echo "- repository: $(node -e "const w=require('./w1-wake.json'); console.log(w.repository.full_name)")"
+            echo "- ref: $(node -e "const w=require('./w1-wake.json'); console.log(w.ref)")"
+            echo "- after: $(node -e "const w=require('./w1-wake.json'); console.log(w.after)")"
+            echo "- signature_verified: true"
+            echo "- notification_is_authority: false"
+            echo "- next_action: receiver_fetch_and_verify_git_ref"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload pointer-only wake artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: etiquette-w1-wake
+          path: w1-wake.json

package/templates/hosted-receiver/README.md

@@ -0,0 +1,41 @@
+# Hosted Receiver Templates
+
+Opt-in templates for teams that want to expose Etiquette's W1 GitHub webhook
+receiver behind their own hosting layer.
+
+## W1 GitHub Receiver
+
+`w1-github-webhook-receiver.mjs` is a small Node HTTP server:
+
+- `GET /health` returns a readiness probe.
+- `POST /github` accepts GitHub `ping` and `push` webhook deliveries.
+- `ping` returns `200` only after the delivery is signature-verified.
+- `push` delegates to `etiquette notify webhook github`.
+- raw payloads are written only to a temporary file for the CLI call, then
+  removed.
+- emitted records stay pointer-only and authority-false.
+
+Run it with:
+
+```sh
+export ETIQUETTE_GITHUB_WEBHOOK_SECRET='<webhook-secret>'
+export ETIQUETTE_CLI='etiquette'
+node w1-github-webhook-receiver.mjs
+```
+
+Optional:
+
+```sh
+export PORT=8080
+export ETIQUETTE_WAKE_OUT_DIR=/var/lib/etiquette/wake
+```
+
+`ETIQUETTE_WAKE_OUT_DIR` stores only the verified pointer output, never the raw
+webhook body.
+
+## Boundary
+
+This template does not create a public endpoint, register repository webhooks,
+provision cloud infrastructure, start remote execution, or grant authority. Host
+selection, webhook registration, secret rotation, and retention policy remain
+operator decisions.

package/templates/hosted-receiver/w1-github-webhook-receiver.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const port = Number(process.env.PORT || '8080');
+const etiquetteCli = process.env.ETIQUETTE_CLI || 'etiquette';
+const secret = process.env.ETIQUETTE_GITHUB_WEBHOOK_SECRET;
+const outDir = process.env.ETIQUETTE_WAKE_OUT_DIR || '';
+
+if (!secret) throw new Error('ETIQUETTE_GITHUB_WEBHOOK_SECRET is required');
+
+function readRaw(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+function writeJson(res, status, value) {
+  res.writeHead(status, {
+    'content-type': 'application/json',
+    'cache-control': 'no-store',
+  });
+  res.end(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function publicRecord(record) {
+  return {
+    ok: true,
+    schema: record.schema,
+    event: record.event,
+    delivery_id: record.delivery_id,
+    repository: record.repository.full_name,
+    ref: record.ref || null,
+    after: record.after || null,
+    signature_verified: record.transport.signature_verified,
+    pointers_only: record.payload_boundary.pointers_only,
+    notification_is_authority: record.authority_boundary.notification_is_authority,
+    next_action: record.next_action,
+  };
+}
+
+async function verifyDelivery(req, event, delivery, signature) {
+  const raw = await readRaw(req);
+  const payloadPath = join(tmpdir(), `etiquette-webhook-${delivery}-${randomUUID()}.json`);
+  writeFileSync(payloadPath, raw);
+  try {
+    const result = spawnSync(etiquetteCli, [
+      'notify',
+      'webhook',
+      'github',
+      '--payload',
+      payloadPath,
+      '--delivery',
+      delivery,
+      '--event',
+      event,
+      '--signature-256',
+      signature,
+      '--json',
+    ], {
+      encoding: 'utf8',
+      env: {
+        ...process.env,
+        ETIQUETTE_GITHUB_WEBHOOK_SECRET: secret,
+      },
+    });
+    if (result.status !== 0) {
+      return {
+        ok: false,
+        status: 401,
+        body: {
+          ok: false,
+          error: 'signature_or_payload_rejected',
+          detail: result.stderr.trim().slice(0, 200),
+        },
+      };
+    }
+    const record = JSON.parse(result.stdout);
+    if (outDir) {
+      mkdirSync(outDir, { recursive: true });
+      writeFileSync(join(outDir, 'latest.json'), `${JSON.stringify(record, null, 2)}\n`);
+      writeFileSync(join(outDir, `${delivery}.json`), `${JSON.stringify(record, null, 2)}\n`);
+    }
+    return { ok: true, status: 200, body: publicRecord(record) };
+  } finally {
+    rmSync(payloadPath, { force: true });
+  }
+}
+
+const server = createServer(async (req, res) => {
+  try {
+    if (req.method === 'GET' && req.url === '/health') {
+      writeJson(res, 200, { ok: true, authority: false });
+      return;
+    }
+    if (req.method !== 'POST' || req.url !== '/github') {
+      writeJson(res, 404, { ok: false, error: 'not_found' });
+      return;
+    }
+
+    const event = String(req.headers['x-github-event'] || '');
+    const delivery = String(req.headers['x-github-delivery'] || randomUUID());
+    const signature = String(req.headers['x-hub-signature-256'] || '');
+    if (event !== 'push' && event !== 'ping') {
+      writeJson(res, 400, { ok: false, error: 'unsupported_event', event });
+      return;
+    }
+    if (!signature.startsWith('sha256=')) {
+      writeJson(res, 401, { ok: false, error: 'missing_signature' });
+      return;
+    }
+
+    const result = await verifyDelivery(req, event, delivery, signature);
+    writeJson(res, result.status, result.body);
+  } catch (error) {
+    writeJson(res, 500, { ok: false, error: String(error?.message || error) });
+  }
+});
+
+server.listen(port, '0.0.0.0', () => {
+  console.log(`etiquette_w1_receiver: listening on ${port}`);
+});

package/templates/seat-packs-v0/README.md

@@ -0,0 +1,72 @@
+# Seat Packs V0
+
+Optional runtime-specific seat templates for Etiquette.
+
+Vanilla Etiquette starts with one generic `control-seat`. Use these templates only after the control seat decides a runtime-specific seat is useful.
+
+## Available Seat Templates
+
+```yaml
+codex:
+  execution_surface: codex
+  template: source/codex-seat
+
+claude-code:
+  execution_surface: claude_code
+  template: source/claude-code-seat
+
+gemini:
+  execution_surface: gemini_cli
+  template: source/gemini-seat
+
+openrouter:
+  execution_surface: openrouter
+  template: source/openrouter-seat
+
+ollama:
+  execution_surface: ollama
+  template: source/ollama-seat
+```
+
+## Provision Explicitly
+
+```sh
+sh bin/provision-seat codex /tmp/dev-codex-seat
+sh bin/provision-seat claude-code /tmp/dev-claude-code-seat
+sh bin/provision-seat gemini /tmp/dev-gemini-seat
+sh bin/provision-seat openrouter /tmp/dev-openrouter-seat
+sh bin/provision-seat ollama /tmp/dev-ollama-seat
+```
+
+Seat packs do not bundle monitor skills. For bounded wake checks, every seat
+uses the portable core command `etiquette notify poll --seat <id> --after-seq <n>`,
+which is read-only, does not grant authority, and does not start a daemon.
+
+## Provision By Detection
+
+```sh
+sh bin/provision-seat auto /tmp/dev-seat
+```
+
+Auto-detect succeeds only when exactly one supported runtime is obvious. If several runtimes are available, choose explicitly.
+
+## Head-Start Discipline
+
+Runtime seat packs are not authority. After provisioning a seat into a project,
+the seat inherits the target project's ledger and task envelopes. Read the
+project head-start surfaces before pickup:
+
+- `AGENTS.md`
+- `docs/work/BOARD.md`
+- `docs/work/runbooks/SESSION_PICKUP.md`
+- `docs/work/manuals/SEAT_OPERATING_MANUAL.md`
+- `docs/work/cookbooks/ADD_A_LANE.md` when routing work
+
+Use `$etiquette-seat-lifecycle` before pickup after stale context, resume,
+runner/model/profile swaps, or workflow migration.
+
+## Validate Catalog
+
+```sh
+sh validate-seat-packs.sh
+```