@etiquekit/etq 0.0.1 → 1.0.4

package/AGENTS.md

@@ -0,0 +1,28 @@
+# Etiquette Agent Guide
+
+This repo is the Etiquette source repo. Keep the all-developer onboarding path small.
+
+## Default Rule
+
+New engineers should start with:
+
+1. [README.md](README.md)
+2. [docs/SEAT_PROVISIONING.md](docs/SEAT_PROVISIONING.md)
+3. [templates/etiquette-vanilla-v0/README.md](templates/etiquette-vanilla-v0/README.md)
+
+Do not send new seats through internal history, old coordination lanes, or maintainer-only notes.
+
+## Ownership
+
+This repo owns:
+
+- the minimal vanilla seat scaffold;
+- optional runtime seat-pack scaffolds;
+- shared task, readiness, and receipt contracts;
+- validation scripts for release hygiene.
+
+This repo does not own product repos, product lane state, secrets, hosted services, or runtime vendor setup.
+
+## Editing Rule
+
+Release-facing docs must stay role-based and portable. Do not introduce person names, local machine paths, historical bus references, or project-specific lane IDs into the default onboarding surface.

package/QuickStart.md

@@ -0,0 +1,86 @@
+# Quick Start
+
+For a clean repo, a team canary, or a new Etiquette developer.
+
+Prereqs: `git >= 2.40` and `bun >= 1.3` on `PATH`. macOS and Linux.
+
+## 1. Get The CLI
+
+```sh
+npm install -g @etiquekit/etq                      # etq + etiquette on PATH
+curl -fsSL https://etiquekit.com/install.sh | sh   # or: native installer
+```
+
+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_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
+
+From the project repo:
+
+```sh
+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
+
+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
+```
+
+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).
+
+## 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" \
+  --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 \
+  --state docs/work/dispatch/APP-001/seat-readiness.json
+```
+
+`dispatch record` writes local metadata and receipt refs; it does not merge,
+close, publish, or grant.
+
+## 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.
+
+Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt

package/README.md

@@ -1,12 +1,80 @@
-# etq (reserved)
+# Etiquette
 
-This package name is reserved for **Etiquette** — a local-first CLI that
-governs agent-assisted engineering work with seats, evidence, and promotion
-gates. Your repo is the ledger, receipts are the proof, and no server ever
-sees your code.
+**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.
 
-Releases begin at **https://etiquekit.com** — including a signed installer
-that requires neither npm nor this package.
+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.
 
-Until a `1.x` version appears here, this package intentionally does nothing
-beyond printing a pointer.
+Docs: https://etiquekit.com/docs/ · Agents start at: https://etiquekit.com/llms.txt
+
+## Install
+
+```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.
+
+## Sixty seconds to a governed workspace
+
+```sh
+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
+```
+
+Per-runtime seat packs: `provision-seat claude-code` · `provision-seat codex`
+· `provision-seat gemini` · `provision-seat ollama` · `provision-seat openrouter`.
+
+The daily loop is three verbs:
+
+```sh
+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
+```
+
+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.
+
+## Concepts in one breath
+
+| 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? |
+
+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.
+
+## Verify releases
+
+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:
+
+```
+917fbced1d6a82897ec3441a1d12947803ca4d42a6bc63d3412dee8bf8c3ce31
+```
+
+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
+
+Proprietary; distributed as compiled bundles for convenience.