@etiquekit/etq 0.0.1 → 1.0.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,100 @@
+# Architecture Boundary
+
+Etiquette is the governance substrate for agentic engineering work.
+
+It should not become a single runner, hosted dashboard, chat product, or model
+vendor wrapper. Those can all consume Etiquette, but they do not own its truth.
+
+## Layers
+
+```text
+Core          contracts, schemas, validators, ledgers, receipts, audit
+Local runtime repo-local CLI, event log, task packets, memory search
+Harness       teammate UX, context presets, skills, dashboards, canvases
+Adapters      Codex, Claude Code, Gemini, managed runners, GitHub, MCP
+Reactors      optional tighten-only listeners for revocation and sync
+```
+
+```text
+Core records, validates, gates, and dispatches.
+Full remembers, consolidates, marinates, and projects.
+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.
+
+## Authority
+
+Authority lives in repo-local records and explicit grants.
+
+- A seat can propose or execute only inside its envelope.
+- A runner session is not a lane.
+- A permission prompt is not a grant lease.
+- A memory object is not truth.
+- A dashboard is not the board.
+- A reactor may tighten access, never loosen it.
+
+Consequential mutations need receipt context:
+
+```text
+actor -> seat -> grant/ref -> allowed writes -> validation -> receipt
+```
+
+Authentication gives standing to occupy a seat. Authorization is checked at the
+protected action and is conditional on current standing.
+
+For managed or remote surfaces, requests should resolve through an authority
+policy, not a hardcoded person, model, or runtime. The resolver maps actions to
+role occupants or composite gates and fails closed.
+
+## Consumers
+
+Consumers may read, render, route bounded work, spawn 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.
+
+## Package Boundary
+
+```text
+packages/protocol  kernel contracts; no runtime or adapter imports
+packages/control   local runtime and public CLI; may use protocol only
+legacy bridges     dbt-core and adapter-* stay source-only until a consumer
+apps/*             UX surfaces; consume core through public commands or APIs
+```
+
+Known bridge exceptions must stay named in conformance tests until removed.
+Adding a reverse import is an architectural change. The public 0.2.x package ships only
+`control`, `protocol`, docs, templates, and scripts; legacy DBT and old slice
+adapters stay source-only until a consumer exists.
+
+For 0.2.x, only two product boundaries are hard enforcement surfaces:
+
+- Core excludes Full command families and optional runtime, hosted, memory,
+  console, sync, adapter, MCP, release, and remote provisioning surfaces.
+- Exec remains authority-false: it may run, observe, verify, and return
+  evidence, but it cannot grant, close, merge, promote, mutate canonical truth,
+  or mint access outside Core grants and envelopes.
+
+Exec evidence is boundary evidence, not process surveillance. Runners return scope, write
+boundaries, candidates, validation, failures, refusals, and stop conditions; internal retries need
+trace-mode only when requested. Managed or
+opaque providers must return audit-self-sufficient evidence reconstructable without provider session
+logs, while avoiding raw event-log mirrors.
+
+The richer Core/Exec/Full module map is documentation-only until a named trigger
+appears. Split packages or repos only for license divergence, release cadence,
+security blast radius, maturity/churn mismatch, or dependency growth.
+
+Never split the authority gate from the evidence ledger, and never move the
+authority gate out of Core.
+
+## Distribution Profiles
+
+The same core supports `open`, `secure`, and `hosted` distribution profiles.
+
+Do not fork doctrine by profile. Profiles change admission and packaging, not truth.

package/docs/CODEX_CLIENT_COMPATIBILITY.md

@@ -0,0 +1,83 @@
+# Codex Client Compatibility
+
+Etiquette Core does not require Codex to install, run local ledger commands, or
+cut a package release. Codex is a consumer/runner surface: useful, first-class,
+and replaceable.
+
+As of 2026-06-18, operators should use Codex CLI `0.141.0` or newer for
+Etiquette lanes that exercise remote execution, plugin-scoped MCP, or hook
+resume behavior. That floor comes from the official Codex changelog for
+`0.140.0` and `0.141.0`, which added or fixed surfaces we actively consume:
+remote executor relay hardening, app-server/exec-server path preservation,
+plugin/MCP routing, hook trust/resume behavior, SQLite recovery, and large
+tool-session performance.
+
+Source: https://developers.openai.com/codex/changelog
+
+## Compatibility Matrix
+
+| Etiquette surface | Codex floor | Gate posture |
+| --- | --- | --- |
+| Core CLI, package tarball, ledger, receipts | none | Core must remain usable without Codex. |
+| Local Codex coding seat | `0.141.0` recommended | Warn if older; do not block Core. |
+| 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. |
+
+## Operator Check
+
+Before a remote-runtime, plugin-MCP, or hook/action-auth canary:
+
+```sh
+codex --version
+codex mcp list
+codex features list
+```
+
+If the CLI is older than `0.141.0`, update it before the canary:
+
+```sh
+codex update
+codex --version
+```
+
+The update command is an operator action, not an Etiquette release action.
+Running `etiquette release readiness` must never update Codex, publish a package,
+or create a distribution channel.
+
+## Post-Update Smoke
+
+After updating Codex, run one low-risk local smoke before routing remote or MCP
+work:
+
+```sh
+codex --version
+codex mcp list
+codex exec "Report the current working directory and do not edit files."
+```
+
+For plugin-scoped MCP work, prefer activating the needed plugin or MCP server in
+the thread/adapter that needs it. Avoid turning every MCP server into a global
+startup dependency.
+
+## Runner Glitches
+
+If Codex reports a client/rendering error such as `Unsupported content type`
+while a shell command or edit actually completed, treat it as runner evidence,
+not Etiquette truth. Re-run the underlying `etiquette ...` command directly in
+the terminal, record the result in the repo-local session runbook, and continue
+only if `doctor`, `typecheck`, tests, or the requested validation pass.
+
+```sh
+etiquette diagnostics runner-glitch --runner codex --symptom '{"detail":"Unsupported content type"}' --session <session-id>
+```
+
+## Authority Boundary
+
+Codex permissions, plugin installs, MCP approvals, and `/usage` reports are
+runtime signals. They are not Etiquette grants.
+
+Codex memories can help an operator recall preferences. They are not workflow
+truth. Etiquette truth remains the ledger, task envelopes, explicit grants,
+receipts, and release artifacts.

package/docs/CONCEPTS.md

@@ -0,0 +1,128 @@
+# Core Concepts
+
+Etiquette is a governance and evidence layer for agent-assisted engineering
+work. It does not try to be the agent, the IDE, the chat room, or the cloud
+runtime.
+
+## The Loop
+
+```text
+seat -> task envelope -> session -> execution -> receipt -> promotion gate
+```
+
+Core records, validates, gates, and dispatches. Exec runs and returns evidence.
+Full remembers, consolidates, marinates, and projects.
+
+## Seat
+
+A seat is a durable work identity. A human, agent, or runtime can occupy it, but
+the seat is the thing the workflow routes to.
+
+Do not confuse:
+
+| Concept | Answers |
+| --- | --- |
+| Operator principal | Who is accountable for intent or approval? |
+| Seat | What durable work role or capability is acting? |
+| Runtime | Which tool or model executed? |
+| Session | Which bounded run produced evidence? |
+
+## Task Envelope
+
+A task envelope says what work is allowed: owner, mode, allowed writes,
+forbidden writes, validation, stop conditions, expected receipt, and next owner.
+
+If a task does not name the write boundary and validation, it is not ready for
+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.
+
+## Receipt
+
+A receipt proves what happened: changed files, validation, runbook refs,
+blockers, risks, and next owner. It is evidence; it does not approve itself.
+
+## Ledger
+
+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.
+
+## Promotion Gate
+
+The promotion gate is where candidate work becomes accepted truth.
+
+The gate is resolved by policy: owner, role, quorum, risk class, changed
+surface, and current standing. It should not be hardcoded to one person unless
+policy says that person owns the action class.
+
+## Authority Lease
+
+An authority lease is a narrow, expiring permission to spend an existing grant.
+Spend can nest, bounded. Mint never nests.
+
+V0 leases cover reversible work, tool use, validation, candidate return, and
+local orchestration. They never cover auto-merge, signing, release, protected
+branch push, secret rotation, cloud activation, or policy mutation.
+
+Every lease check happens at the canonical point of effect, not from a stale
+local cache. Telemetry can observe the action. It is not the audit log.
+`can_auto_merge_in_v0: false` is required in V0.
+
+## Node Delegation
+
+Node delegation is topology, not authority.
+
+A parent seat, runner, or orchestrator may delegate bounded work to a child
+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.
+
+Children return to their immediate parent. The parent synthesizes one upstream
+receipt and remains accountable for child cleanup. A child or headless node is
+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.
+
+Exec may run, observe, retry safe work, and return evidence. Exec must not
+grant, merge, close, promote, or mutate canonical truth.
+
+## Memory
+
+Memory is cited context. It helps a seat find prior decisions, receipts, risks,
+and patterns.
+
+Memory proposes. Ledgers authorize. Receipts prove. Audit logs account.
+
+Evidence consolidation creates compact rollups from recorded evidence.
+Marination is a separate reflective practice over doctrine, drift, and repeated
+failure patterns. Both produce proposals, not silent truth changes.
+
+## Integrations
+
+External tools keep their native jobs: chat is conversation, planning tools are
+planning, code hosts are review, observability is incident evidence, and
+identity systems are identity.
+
+Etiquette is the accountability spine. External "Done" is not acceptance.
+Authentication is not authorization.
+
+## Short Rules
+
+```text
+Receipts prove work.
+Grants authorize consequential action.
+Sessions bound execution noise.
+Portals display and coordinate.
+Integrations project refs.
+Execution returns evidence; it never mints authority.
+```

package/docs/CONCEPT_STATUS.md

@@ -0,0 +1,67 @@
+# Concept Status Matrix
+
+Etiquette uses a few strong workflow concepts. Some are core behavior today,
+some belong to the optional secure plane, and some are still operating patterns
+that need a concrete consumer before they become default workflow.
+
+Use this page when writing portal copy, onboarding material, release notes, or
+manager runbooks. Do not promote a concept beyond the status shown here.
+
+## Edition Boundary
+
+| Surface | Purpose | Authority Posture |
+| --- | --- | --- |
+| Etiquette Core | Repo-local coordination, task envelopes, receipts, allowed writes, read models, manuals, and canaries. | Transparent by default; authority comes from tracked task/grant records and receipts. |
+| Etiquette Secure | Restricted-seat admission, external assurance claims, revocation, policy state, and optional tightening reactor. | Tightens standing and eligibility; it must not grant workflow authority by itself. |
+| Hosted/portal plane | Setup passes, workspace visibility, onboarding, board/read-model display, and operational observability. | Portal RBAC authorizes portal operations only. Workflow authority stays local and grant-backed. |
+
+## Concept Matrix
+
+| Concept | Core Status | Secure Status | Portal Surface | Caveat |
+| --- | --- | --- | --- | --- |
+| Ledger | Shipped. Repo-local task records, events, and receipts carry durable workflow truth. | May receive signed or protected replication later. | Board and console render ledger-derived read models. | Git-backed truth is durable and auditable; call it cryptographic only when signing/protected append-only is actually configured. |
+| Receipts | Shipped. Work returns must cite changed files, validation, blockers, and next owner. | May include action authorization stamps and external verifier receipts. | Evidence drawers and manager views point to receipts. | A receipt proves evidence; it does not grant, merge, close, or promote by itself. |
+| Seats and agents | Shipped. A seat is a stable responsibility; an occupant/runtime can change. Owner cards derive accountability, diet, boundaries, review cadence, and failure modes from source contracts plus live readiness. | Restricted seats may require assurance claims before admission. | Roster and owner cards show lifecycle, readiness, ownership, and posture. | Model cards, owner cards, and roster posture help routing but do not authorize work or transfer ownership. |
+| Task envelopes | Shipped. Tasks declare owner, mode, allowed writes, forbidden writes, validation, stop conditions, and receipt expectations. | Secure admission can refuse restricted seats before task execution. | Manager manuals and pickup surfaces show the envelope. | Allowed writes are a cooperative boundary unless paired with OS/container enforcement or audit gates. |
+| Rubrics and validation | Shipped as acceptance criteria and conformance gates. | Can be bound to restricted workflows and verifier receipts. | Manager/operator docs list required validation and stop conditions. | Do not claim every runtime is hard-blocked from returning unless the specific flow enforces that gate. |
+| Authorization | Shipped as grant-backed workflow discipline: authentication seats an actor; authorization gates consequential action. | Access assurance, grant leases, kill-switch state, and action stamps compose at admission time. | Hosted pass docs and workspace authority contracts describe the boundary. | A verified occupant has standing, not blanket authority. Grants are effective only while standing is current. |
+| Access screening | Not required for open Core. | Optional Secure surface using derived claims from providers such as Persona, Scandit, and Supabase. | Restricted-seat policy docs and secure onboarding should expose pass/fail status, not raw identity data. | Raw documents, scans, full document numbers, ethnicity, and provider secrets do not belong in Git. |
+| Portal / management console | Core read model, docs site, screenshots, and read-only `console serve` are shipped. | Secure portal may manage policy state and revocation signals. | Console and board are read-only by default. | Portal RBAC is not workflow authority. Browser actions remain out of scope in Core. |
+| Distribution and plugins | Core CLI, docs, templates, MCP resources/prompts, and outbox-backed proposal staging are portable. | Secure can ship as an optional add-on. | Codex and Claude Code plugins may launch workflows and portal views. | Plugins are convenience packaging, not authority. MCP proposal tools must not mutate the ledger directly. |
+| Remote execution | Supported as evidence-first design. | Secure runtimes may require admission, revocation, and verifier identity before execution. Org-remote workspaces use session outboxes, sharded drains, candidate imports, and authority promotion gates. | Manager docs should treat remote receipts as evidence. | Start remote as witness, not worker. Remote receipts and drain imports do not authorize promotion. |
+| Managed-agent parity | Parity map exists for agents, environments, sessions, events, tools, MCP, memory, outcomes, and scheduling. | Secure can add restricted runtime admission and revocation. | Docs site and portal docs may expose the map. | Compatibility is not dependency. The runner executes; Etiquette governs and records. |
+| Architecture boundary | Core, runtime, harness, adapter, and reactor roles are documented and import-boundary tested. | Secure adds admission policy without forking doctrine. | Hosted consumes projected views without becoming authority. | New reverse imports are architectural changes, not convenience edits. |
+| Memory | Shipped as cited context, filesystem-shaped candidate stores, SQLite FTS recall, and `memory status` capability reporting. Evidence consolidation/rollup is the memory compaction lifecycle; it is not doctrine marination. | Secure deployments may restrict what crosses org/workspace boundaries. | Docs may surface references, summaries, archive pointers, and shipped/reserved memory status. | Memory proposes; ledger authorizes. Do not claim full semantic/vector memory parity until the adapter ships. Do not rewrite shared truth through background consolidation. |
+| Marination | Operating pattern. Use for doctrine sabbaticals: scheduled fresh-attention review of rules, errata, and proposed revisions. | Can be run under Secure as an advisory process with cited evidence. | Not yet a default portal workflow. | Deltas only. It produces proposals, not silent lane mutations. |
+| Sabbaticals / parking | Partially reflected as `park`, `held`, and deferred dispositions. | Secure deployments may freeze standing or grants while work is parked. | Manager cadence can show parked/held work. | Do not promise automatic stash/cleanup unless the workspace implements that runbook. |
+| Tightening reactor | Not part of default Core. | Optional off-by-default listener that writes only fail-closed signals such as revocation or kill-switch state. | Secure operations may show reactor health. | It may tighten, never loosen. If it stops, local admission still fails or proceeds from last known policy according to the configured gate. |
+
+## Primitive Loop
+
+Core records, validates, gates, and dispatches. Full remembers, consolidates,
+marinates, and projects. Execution is not the gate: Core execution is the local
+shell/worktree, Full execution is a runtime cell or managed runner, and both
+remain authority-false until the promotion gate accepts evidence.
+
+| Layer | Core | Full |
+| --- | --- | --- |
+| Record | identity, seats, task envelopes, session runbooks, ledger, receipts | memory stores, recall capsules, org/workspace projections |
+| Reflect | rubrics, local validation, reconciliation by review | consolidation rollups, marination, drift and failure trend review |
+| Gate | human/Git promotion gate over receipts and grants | same gate, enriched by secure admission and policy checks |
+| Execute | local shell, local worktree, local runner | runtime cells, EKS/kind sandboxes, managed runners |
+| Act | dispatch, receipt return, next-owner routing | hosted portal views, observability, adapter projections |
+
+## Writing Rule
+
+Use shipped language for shipped behavior, design language for parked behavior,
+and edition language for Secure behavior:
+
+```text
+Core records, validates, gates, and dispatches.
+Full remembers, consolidates, marinates, and projects.
+Secure admits and revokes restricted standing.
+Portals display and coordinate.
+Grants authorize consequential actions.
+Receipts prove what happened.
+Execution returns evidence; it never mints authority.
+```

package/docs/CORE_PROFILE.md

@@ -0,0 +1,70 @@
+# Etiquette Core Profile
+
+Etiquette Core is the bare-bones governance flavor for senior engineers who
+want the original promise without the managed runtime surface.
+
+Core includes:
+
+- seat readiness and heartbeat;
+- workflow mode validation and checks;
+- rubric validation, local sandbox receipts, and promotion checks;
+- operational dispatch check and record;
+- local ledger indexing, search, and show;
+- vanilla kernel docs, task cards, receipts, and the local ledger.
+
+Core excludes by default:
+
+- hosted runtime and EKS provisioning;
+- MCP server;
+- Linear adapter;
+- memory-store lifecycle and drains;
+- agent-plane profiles;
+- console/site;
+- remote sync joins and merge-driver setup;
+- auth screening and enterprise rollout surfaces.
+
+## Primitive Map
+
+Core records, validates, gates, and dispatches:
+
+| Layer | Core primitive |
+| --- | --- |
+| Record | seats, owner/readiness, task envelopes, ledger, receipts |
+| Reflect | rubrics, local validation, reconciliation by review |
+| Gate | human/Git promotion over grants, receipts, and validation |
+| Execute | local shell, local worktree, local runner; authority-false |
+| Act | dispatch advice, receipt return, next-owner routing |
+
+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.
+
+Use:
+
+```sh
+./bin/etiquette-core help
+./bin/etiquette-core workflow explain mixed --json
+./bin/etiquette-core seat status --project .
+```
+
+The full `./bin/etiquette` CLI still exposes optional runtime, hosted,
+adapter, memory, console, sync, and release surfaces.
+
+## Authority Gate
+
+Core keeps authority explicit without adding a daemon or remote plane.
+
+The Core promotion path is:
+
+1. An agent or developer writes candidate work under the task boundary.
+2. The candidate includes receipts and validation evidence.
+3. A human reviews the diff and receipts.
+4. Git merge is the canonical promotion gate.
+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.
+
+Core commands may advise, check, and record evidence. They do not authorize
+work, attach grants, merge, close lanes, or promote candidates without the
+human review and Git gate.

package/docs/LANE_PROVISIONING.md

@@ -0,0 +1,157 @@
+# Lane Provisioning Cookbook
+
+Use this when a manager, lead seat, or returning agent needs to open work
+without relying on chat memory.
+
+A lane is a bounded work container. It can describe active work, review work,
+or parked future work. It is not authority by itself.
+
+## Manager Bulletin
+
+Every routed lane should start with a bulletin that a new agent can act on
+without reading private chat history.
+
+```yaml
+lane: APP-001-domain-foundation
+task_id: APP-001
+repo: github.com/org/app
+project_ref: .
+current_owner: codex-seat
+review_owner: cc-seat
+mode: product-implementation | read-only-audit | docs-only
+startup_docs:
+  - AGENTS.md
+  - docs/work/runbooks/SESSION_PICKUP.md
+  - docs/work/manuals/SEAT_OPERATING_MANUAL.md
+  - docs/work/tasks/APP-001.yaml
+allowed_writes:
+  - src/domain/**
+forbidden_writes:
+  - secrets
+  - release keys
+  - deployment credentials
+validation:
+  - npm test
+stop_conditions:
+  - validation cannot run
+  - task needs writes outside allowed_writes
+  - authority, secrets, or release posture is unclear
+expected_return:
+  - changed files
+  - validation evidence
+  - receipt path
+  - next owner
+```
+
+Do not route a lane that lacks owner, mode, allowed writes, validation, stop
+conditions, and expected return.
+
+## Lane Classes
+
+Use the smallest lane class that fits the work.
+
+| Class | Use For | Required Return |
+| --- | --- | --- |
+| `active` | Current implementation, docs, review, or validation | receipt or counter |
+| `review` | Pressure-test a claim, branch, packet, or release posture | review-return |
+| `parked` | Known future work with no grant today | trigger conditions |
+| `blocked` | Work cannot proceed without a decision or external state | blocker and next owner |
+| `closed` | Work has been accepted or deliberately abandoned | close receipt |
+
+Parked lanes are useful for items like CI signing. They must name the exact
+prerequisites that make the lane admissible later.
+
+Example:
+
+```yaml
+lane: release-ci-signing-v1
+status: parked
+trigger_conditions:
+  - protected release-signing environment exists with required reviewers
+  - explicit decision allows GitHub Secret custody for the signing key
+forbidden_until_triggered:
+  - set release signing secret
+  - sign in CI
+  - publish release assets
+```
+
+## Agent Join Routine
+
+When a new seat joins a repo, start from the repo-local truth:
+
+```sh
+etiquette whereami --project . --seat <seat> --task <task>
+etiquette doctor --project .
+etiquette status --project .
+etiquette join --project . --seat <seat>
+etiquette pickup --project . --seat <seat> --task <task> --text
+```
+
+Then read only the startup docs named by the bulletin. Do not scrape old chat
+or a global bus to infer project state.
+
+Inside a session, the agent should confirm:
+
+- seat id and operator principal;
+- task envelope;
+- allowed and forbidden writes;
+- validation commands;
+- runbook path;
+- expected receipt;
+- stop conditions.
+
+If any item is missing, return a narrow ask before editing product files.
+
+## During Work
+
+Keep detailed execution in the repo-local session runbook:
+
+```sh
+etiquette session note --project . --session <session> --section plan --message "..."
+etiquette session note --project . --session <session> --section evidence --message "..."
+```
+
+Use receipts for compact shared evidence. A receipt should cite validation,
+changed files, blockers, and next owner. It should not paste raw transcripts or
+private scratch logs.
+
+## Reviewers
+
+Review seats are evidence producers. They may confirm, counter, or propose
+amendments. They must not merge, promote, close, widen allowed writes, or grant
+authority unless policy explicitly grants that action.
+
+Reviewers should check:
+
+- hidden authority changes;
+- missing validation;
+- oversized write sets;
+- stale or ambiguous task context;
+- evidence that cannot be reproduced;
+- claims that should be receipts.
+
+## Worktrees And Sessions
+
+Use a separate worktree for implementation lanes when more than one seat may
+touch the repo:
+
+```text
+lane/APP-001-domain-foundation
+lane/APP-002-checkout
+lane/APP-003-driver-dispatch
+```
+
+The worktree isolates changes. The session runbook records execution. The
+receipt connects both back to the lane.
+
+Do not use one session for the whole product, whole quarter, or unrelated repos.
+Use one session for one task or a tight cluster of related tasks.
+
+## Forbidden Shortcuts
+
+- Do not treat chat as source of truth.
+- Do not treat `whereami`, `join`, `pickup`, or readiness as authority.
+- Do not use a global handshake bus for routine repo-local execution.
+- Do not sign, publish, merge, close, or promote from a lane bulletin.
+- Do not set secrets or release keys from a parked lane.
+- Do not keep working after a stop condition fires.

package/docs/README.md

@@ -0,0 +1,29 @@
+# Etiquette Docs
+
+Start with [CONCEPTS.md](CONCEPTS.md), [CORE_PROFILE.md](CORE_PROFILE.md),
+[SEAT_PROVISIONING.md](SEAT_PROVISIONING.md), [SEAT_DISCIPLINE.md](SEAT_DISCIPLINE.md),
+[LANE_PROVISIONING.md](LANE_PROVISIONING.md), [WORKTREE_QOL.md](WORKTREE_QOL.md),
+and [ARCHITECTURE.md](ARCHITECTURE.md).
+For private manager-to-developer rollout, use
+[TEAM_HANDOFF.md](TEAM_HANDOFF.md).
+
+References:
+
+- [CONCEPT_STATUS.md](CONCEPT_STATUS.md)
+- [CODEX_CLIENT_COMPATIBILITY.md](CODEX_CLIENT_COMPATIBILITY.md)
+- [RELEASE_SURFACE_AUDIT.md](RELEASE_SURFACE_AUDIT.md)
+
+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.
+
+Integration profile:
+Slack/Teams are conversation, Jira/Linear are planning, GitHub/GitLab are code
+review, Sentry/Datadog/OpenTelemetry are incident evidence, and SSO/SCIM/OIDC
+are identity. Etiquette is the accountability spine: chat is not source of
+truth, external Done is not acceptance, and authentication is not authorization.
+
+Current release posture: Core is the default local-first product, Exec is
+authority-false and swappable, Full/hosted surfaces are optional scale layers,
+and public hosted distribution is parked until organizational approval.
+
+Maintainer history and prior workflow notes are not part of new-seat onboarding.