@etiquekit/etq 1.0.1 → 1.0.5

package/QuickStart.md

@@ -1,42 +1,28 @@
 # Quick Start
 
-Use this for a clean repo, team canary, or new Etiquette developer. For private rollout, use [docs/TEAM_HANDOFF.md](docs/TEAM_HANDOFF.md).
+For a clean repo, a team canary, or a new Etiquette developer.
 
-Prereqs: Git and Bun `>=1.3.0`. The CLI shims refuse if `bun` is not on `PATH`.
-The public hosted installer is parked until approval and signing complete.
+Prereqs: `git >= 2.40` and `bun >= 1.3` on `PATH`. macOS and Linux.
 
 ## 1. Get The CLI
 
-Preferred private path is the signed native installer:
-
 ```sh
-sh install.sh --version 1.0.0 --base-url "$ETQ_RELEASES_URL" \
-  --public-key "$ETQ_PUBLIC_KEY" --install-root "$HOME/.etiquette"
-export PATH="$HOME/.etiquette/bin:$PATH"
+npm install -g @etiquekit/etq                      # etq + etiquette on PATH
+curl -fsSL https://etiquekit.com/install.sh | sh   # or: native installer
 ```
 
-If you only have the private `.tgz`, install it under a user-local prefix:
+The installer verifies every artifact against a pinned public key before
+anything executes and installs under `~/.etiquette`. Offline or air-gapped:
+download `etiquette-<version>.tgz` plus `SHA256SUMS` and `SHA256SUMS.sig`
+from `https://etiquekit.com/releases/`, verify them (see the README's
+"Verify releases"), then:
 
 ```sh
-ETQ_ROOT="$HOME/.etiquette"
-ETQ_LIB="$ETQ_ROOT/lib/etiquette-1.0.0"
-mkdir -p "$ETQ_LIB" "$ETQ_ROOT/bin" /tmp/etq-tgz
-tar -xzf etiquette-1.0.0.tgz -C /tmp/etq-tgz
-cp -R /tmp/etq-tgz/package/. "$ETQ_LIB/"
-(cd "$ETQ_LIB" && bun install --production)
-ln -sfn "$ETQ_LIB/bin/etiquette" "$ETQ_ROOT/bin/etiquette"
-ln -sfn "$ETQ_LIB/bin/etiquette-core" "$ETQ_ROOT/bin/etiquette-core"
-export PATH="$ETQ_ROOT/bin:$PATH"
-```
-
-Source checkout fallback; replace `<company-etiquette-git-url>` with the
-internal private repo URL supplied by your manager:
-
-```sh
-git clone <company-etiquette-git-url> etiquette
-cd etiquette
-./bin/etiquette help
-./bin/etiquette-core help
+ETQ_LIB="$HOME/.etiquette/lib/etiquette-<version>"
+mkdir -p "$ETQ_LIB" "$HOME/.etiquette/bin"
+tar -xzf etiquette-<version>.tgz --strip-components=1 -C "$ETQ_LIB"
+ln -sfn "$ETQ_LIB/bin/etiquette" "$HOME/.etiquette/bin/etiquette"
+export PATH="$HOME/.etiquette/bin:$PATH"
 ```
 
 ## 2. Initialize A Project
@@ -44,19 +30,20 @@ cd etiquette
 From the project repo:
 
 ```sh
-ETQ=${ETQ:-etiquette}
-"$ETQ" setup --target codex --project "$PWD"
-"$ETQ" handoff --project "$PWD" --profile codex-cc-gemini --task-prefix APP
-"$ETQ" bootstrap local --project "$PWD" --profile codex-cc-gemini --task-prefix APP
-"$ETQ" whereami --project "$PWD" --seat codex-seat --task APP-001
-"$ETQ" doctor --project "$PWD"
-"$ETQ" join --project "$PWD" --seat codex-seat
-"$ETQ" pickup --project "$PWD" --seat codex-seat --task APP-001 --allow-current-project --text
-"$ETQ" console board --project "$PWD" --text
+etq setup --target auto --project "$PWD"
+etq handoff --project "$PWD" --profile codex-cc-gemini --task-prefix APP
+etq bootstrap local --project "$PWD" --profile codex-cc-gemini --task-prefix APP
+etq whereami --project "$PWD" --seat codex-seat --task APP-001
+etq doctor --project "$PWD"
+etq join --project "$PWD" --seat codex-seat
+etq pickup --project "$PWD" --seat codex-seat --task APP-001 --allow-current-project --text
+etq console board --project "$PWD" --text
 ```
 
 `bootstrap local` creates repo-local state, seats, task envelopes, pickup docs,
 events, and runbooks. It does not grant, publish, merge, close, or promote.
+`handoff` is a read-only guide: it prints install, bootstrap, and pickup
+commands without changing anything.
 
 ## 3. Orient The Live Seat
 
@@ -64,21 +51,20 @@ Run `whereami` whenever a developer or agent resumes, changes directories, or
 inherits a worktree:
 
 ```sh
-"$ETQ" whereami --project "$PWD" --seat codex-seat --task APP-001
-"$ETQ" pickup --project "$PWD" --seat codex-seat --task APP-001 --allow-current-project --text
+etq whereami --project "$PWD" --seat codex-seat --task APP-001
+etq pickup --project "$PWD" --seat codex-seat --task APP-001 --allow-current-project --text
 ```
 
 Runner resume recovers chat context; `whereami` confirms the repo, branch, task
 envelope, and runbook. For branch hygiene, read [docs/WORKTREE_QOL.md](docs/WORKTREE_QOL.md).
-For in-session pickup UX, use the `seat-session-bootstrap` skill.
 
 ## 4. Check And Record Evidence
 
 Create checkable dispatch examples, then run the generated command:
 
 ```sh
-"$ETQ" dispatch scaffold --project "$PWD" --task-id APP-001 --seat codex-seat
-"$ETQ" dispatch check --project "$PWD" \
+etq dispatch scaffold --project "$PWD" --task-id APP-001 --seat codex-seat
+etq dispatch check --project "$PWD" \
   --mode docs/work/dispatch/APP-001/mode.yaml \
   --task docs/work/dispatch/APP-001/task.yaml \
   --sandbox-receipt docs/work/dispatch/APP-001/receipt.yaml \
@@ -88,7 +74,13 @@ Create checkable dispatch examples, then run the generated command:
 `dispatch record` writes local metadata and receipt refs; it does not merge,
 close, publish, or grant.
 
-## 5. Stop Conditions
+## 5. Seat Packs And Stop Conditions
+
+Per-runtime integrations are explicit, never automatic: `provision-seat claude-code`,
+`provision-seat codex`, `provision-seat gemini`, `provision-seat ollama`,
+`provision-seat openrouter`.
+
+Stop when authority is unclear, validation cannot run, writes exceed the
+envelope, a secret appears, or the session is unbounded.
 
-Seat packs: `provision-seat claude-code`, `provision-seat codex`, `provision-seat gemini`, `provision-seat ollama`, `provision-seat openrouter`.
-Stop when authority is unclear, validation cannot run, writes exceed the envelope, a secret appears, or the session is unbounded.
+Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt

package/README.md

@@ -1,80 +1,80 @@
 # Etiquette
 
-Etiquette is a governance and evidence CLI for agent-assisted engineering work.
+**Govern agent-assisted engineering work with seats, evidence, and promotion
+gates.** Local-first: your repo is the ledger, receipts are the proof, and no
+server ever sees your code.
 
-It answers the questions that matter when agents help write code: who acted,
-under which seat, inside what scope, with what evidence, and who accepted the
-result.
+When several coding agents (and humans) work the same repository, the hard
+part isn't running them — it's knowing **who did what, on whose authority,
+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.
 
-Default loop: `setup -> handoff -> bootstrap local -> whereami -> doctor -> join -> pickup -> receipt -> promotion gate`.
+Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt
 
-Execution runtimes are optional; they return evidence and do not mint authority.
+## Install
 
-## Start
+```sh
+npm install -g @etiquekit/etq        # etq, etiquette, etiquette-core on PATH
+curl -fsSL https://etiquekit.com/install.sh | sh   # or: native installer
+```
+
+Requires `bun >= 1.3` and `git >= 2.40`. macOS and Linux. The installer
+verifies signatures against a pinned public key before anything executes.
 
-Prereqs: Git and Bun `>=1.3.0`; the CLI shims require `bun` on `PATH`.
-For a clean repo or a new seat, read [QuickStart.md](QuickStart.md). For private team rollout, use [docs/TEAM_HANDOFF.md](docs/TEAM_HANDOFF.md), then:
+## Sixty seconds to a governed workspace
 
 ```sh
-./bin/etiquette setup --target codex --project /tmp/etiquette-start
-./bin/etiquette handoff --project /tmp/etiquette-start --profile codex-cc-gemini --task-prefix APP
-./bin/etiquette bootstrap local --project /tmp/etiquette-start --profile codex-cc-gemini --task-prefix APP
-./bin/etiquette whereami --project /tmp/etiquette-start --seat codex-seat --task APP-001
-./bin/etiquette doctor --project /tmp/etiquette-start
-./bin/etiquette status --project /tmp/etiquette-start
-./bin/etiquette join --project /tmp/etiquette-start --seat codex-seat
-./bin/etiquette pickup --project /tmp/etiquette-start --seat codex-seat --task APP-001 --allow-current-project --text
-./bin/etiquette console board --project /tmp/etiquette-start --text
+etq init --project .                  # provision folders, journal, roster
+etq doctor --project .                # readiness — green before work
+etq bootstrap local --project . \
+    --profile codex-cc-gemini --task-prefix APP
+etq setup --target auto --project .   # register your agent CLI (explicit)
+etq join --seat dev-a --project .
+etq console board --project . --text  # the live task board
 ```
 
-`handoff` is a read-only guide: it prints install, bootstrap, and pickup commands without installing, bootstrapping, pushing, closing, or granting.
+Per-runtime seat packs: `provision-seat claude-code` · `provision-seat codex`
+· `provision-seat gemini` · `provision-seat ollama` · `provision-seat openrouter`.
 
-`bootstrap local` creates repo-local seats, task envelopes, bounded runbooks,
-local packet events, and pickup docs without global bus writes or authority.
-`whereami` is the context readback: runner resume restores conversation
-history; `whereami` tells the seat which project, worktree, task, and runbook it
-is actually operating in.
-
-For the bare-bones Core surface:
+The daily loop is three verbs:
 
 ```sh
-./bin/etiquette-core help
+etq pickup --seat dev-a --task APP-001 --expect-project-id <id> --text
+# ... do the work (you, or your agent) ...
+etq return check --task APP-001 --seat dev-a   # the evidence gate
 ```
 
-Use repo-local commands for now. The hosted public installer is parked.
+Every step appends to the workspace journal — an append-only event log inside
+your repo. Nothing leaves your machine: no backend, no telemetry, no account.
 
-## Core Concepts
+## Concepts in one breath
 
-- Seat: durable work identity; the occupant or model can change.
-- Task envelope: scope, allowed writes, validation, and stop conditions.
-- Receipt: evidence of what happened; it proves but does not authorize.
-- Promotion gate: the human/Git gate where candidate work becomes truth.
-- Ledger: durable local record of sessions, receipts, and decisions.
+| Concept | Answers |
+| --- | --- |
+| Seat | What durable work role is acting? |
+| Task envelope | What writes, validation, and stop conditions are allowed? |
+| Session | Which bounded run produced the evidence? |
+| Receipt | What proves the work happened? |
+| Promotion gate | Where does candidate work become accepted truth? |
 
-Read next: [docs/README.md](docs/README.md), [docs/CONCEPTS.md](docs/CONCEPTS.md), [docs/CORE_PROFILE.md](docs/CORE_PROFILE.md), [docs/SEAT_PROVISIONING.md](docs/SEAT_PROVISIONING.md), and [docs/WORKTREE_QOL.md](docs/WORKTREE_QOL.md).
+Commands can initialize, check, record evidence, and project read models.
+They **do not** grant authority, merge, close work, publish, or promote truth.
+Execution returns evidence; it never mints authority.
 
-Provision runtime seats only after assignment:
+## Verify releases
 
-```sh
-sh templates/seat-packs-v0/bin/provision-seat codex /tmp/dev-codex-seat
-sh templates/seat-packs-v0/bin/provision-seat claude-code /tmp/dev-claude-code-seat
-sh templates/seat-packs-v0/bin/provision-seat gemini /tmp/dev-gemini-seat
-sh templates/seat-packs-v0/bin/provision-seat ollama /tmp/dev-ollama-seat
-sh templates/seat-packs-v0/bin/provision-seat openrouter /tmp/dev-openrouter-seat
-```
+The release signing public key has this SHA-256 fingerprint — cross-check it
+against the copy at https://etiquekit.com/docs/ before trusting a downloaded
+key:
 
-## Validate
-
-```sh
-npm run release:scan
-bun test
-npm run typecheck
+```
+917fbced1d6a82897ec3441a1d12947803ca4d42a6bc63d3412dee8bf8c3ce31
 ```
 
-## Release Status
+Then `openssl dgst -sha256 -verify <key> -signature SHA256SUMS.sig SHA256SUMS`
+and `shasum -a 256 -c SHA256SUMS`. If any step fails: stop, do not install.
 
-```yaml
-default_surface: templates/etiquette-vanilla-v0
-optional_runtime_surface: templates/seat-packs-v0
-public_installer: held
-```
+## License
+
+Proprietary; distributed as compiled bundles for convenience.