@etiquekit/etq 0.0.1 → 1.0.1

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,94 @@
+# 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).
+
+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.
+
+## 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"
+```
+
+If you only have the private `.tgz`, install it under a user-local prefix:
+
+```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
+```
+
+## 2. Initialize A Project
+
+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
+```
+
+`bootstrap local` creates repo-local state, seats, task envelopes, pickup docs,
+events, and runbooks. It does not grant, publish, merge, close, or promote.
+
+## 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).
+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" \
+  --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. Stop Conditions
+
+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.

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.
+Etiquette is a governance and evidence CLI for agent-assisted engineering work.
 
-Releases begin at **https://etiquekit.com** — including a signed installer
-that requires neither npm nor this package.
+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.
 
-Until a `1.x` version appears here, this package intentionally does nothing
-beyond printing a pointer.
+Default loop: `setup -> handoff -> bootstrap local -> whereami -> doctor -> join -> pickup -> receipt -> promotion gate`.
+
+Execution runtimes are optional; they return evidence and do not mint authority.
+
+## Start
+
+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:
+
+```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
+```
+
+`handoff` is a read-only guide: it prints install, bootstrap, and pickup commands without installing, bootstrapping, pushing, closing, or granting.
+
+`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:
+
+```sh
+./bin/etiquette-core help
+```
+
+Use repo-local commands for now. The hosted public installer is parked.
+
+## Core Concepts
+
+- 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.
+
+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).
+
+Provision runtime seats only after assignment:
+
+```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
+```
+
+## Validate
+
+```sh
+npm run release:scan
+bun test
+npm run typecheck
+```
+
+## Release Status
+
+```yaml
+default_surface: templates/etiquette-vanilla-v0
+optional_runtime_surface: templates/seat-packs-v0
+public_installer: held
+```