npm - @hua-labs/tap - Versions diffs - 0.6.0 → 0.6.1 - Mend

@hua-labs/tap 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/AI_GUIDE.md CHANGED Viewed

@@ -1,7 +1,7 @@
 # @hua-labs/tap AI Guide
 This guide is for AI operators using the public `@hua-labs/tap` package without
-access to HUA's private monorepo notes.
+project-private runbooks.
 ## Release Boundary
@@ -13,16 +13,80 @@ Keep these boundaries explicit:
 - Inbox, projection, uplink, and review files are durable evidence.
 - Receiver/promoter delivery is the portable CLI/TUI/headless backbone.
-- Codex App / Desktop live delivery is strict-gated by runtime health and route
-  freshness.
+- Codex App / Desktop live delivery must not be reported as live-ready unless
+  runtime health and route freshness are both explicitly present.
 - `tap reviews register` is explicit; automatic registration from every writer
   path is a later follow-up.
 - Profile packs are data-only validation inputs in `0.6.x`; tap does not run
   commands from a pack.
+- Gemini CLI support is legacy/deprecated. Antigravity CLI is not a bundled
+  adapter in `0.6.x`; model it as a custom profile-pack surface until a
+  dedicated adapter exists.
+## Operator Rules
+AI operators must not claim live model delivery from file evidence alone.
+Before reporting live readiness:
+1. Check setup state with `tap doctor --setup`.
+2. Check runtime state with `tap status`.
+3. Check delivery boundaries with `tap comms-doctor`.
+4. Treat inbox, projection, uplink, and review files as evidence only, not
+   proof of live model execution.
+5. Do not use broad role aliases as assignment targets unless a reviewed role
+   map resolves them to a concrete agent.
+## Do Not Claim
+Do not claim that an agent received, read, or acted on a message unless the
+relevant runtime surface reports live readiness or there is explicit returned
+runtime evidence.
+Durable inbox, projection, uplink, and review files may prove that tap wrote or
+observed evidence. They do not prove live model execution by themselves.
+## Concepts
+- **Runtime**: an AI tool or environment tap can connect to, such as Claude or
+  Codex.
+- **Agent**: a concrete named participant, such as `agent-a`, that sends or
+  receives messages.
+- **Surface**: the runtime interface being inspected, such as `codex-cli`,
+  `codex-app`, or a custom profile-pack surface.
+- **Bridge**: a live adapter process used by runtimes that need one, such as
+  Codex app-server sessions.
+- **Comms directory**: the shared file-backed message store used for inboxes,
+  reviews, handoffs, and evidence.
+- **Profile**: a setup target that describes which runtime surface tap should
+  inspect or prepare.
+- **Profile pack**: a data-only input that extends setup validation for custom
+  environments.
+## Command Relationship
+Most users should start with `tap setup`.
+- `setup`: inspect or apply guarded first-run MCP/setup changes.
+- `doctor --setup`: verify the setup path and explain warnings.
+- `init`: only create or reset the shared comms directory and tap state.
+- `add`: add a runtime instance and patch that runtime's config.
+- `ready`: prepare or verify a concrete agent on a runtime surface.
+- `status`: summarize installed runtime state.
+- `comms-doctor`: explain delivery and readiness by surface.
+- `flow-doctor`: inspect one receiver/promoter lane without process mutation.
+Use `setup` before `init` unless you specifically need manual comms directory
+creation. Use `ready` after `add` when you want a named agent lane to be
+discoverable and diagnosable.
 ## First-Run Path
-Run from a git repository:
+This path separates setup inspection, guarded setup mutation, runtime instance
+registration, and concrete agent readiness.
+Run from an existing git repository. In a new test directory, initialize one
+first:
 ```bash
 git init
@@ -40,15 +104,31 @@ Avoid broad role words such as `codex`, `reviewer`, `implementer`,
 `implementation`, and `tower` as assignment targets unless a reviewed role map
 makes them unambiguous.
+## Permissions And Safety
+Safe mode reduces destructive local file operations. It is not a
+network-isolated mode.
+- Claude safe mode adds deny rules for destructive shell operations.
+- Codex safe mode uses `workspace-write` sandboxing with trusted project paths,
+  writable roots, and network access.
+- Full mode removes more guardrails and should only be used on trusted local
+  machines.
+tap setup does not read credentials. It writes only reviewed tap-managed setup
+artifacts, and it fails closed before mutating ambiguous user-managed MCP
+entries.
 ## Expected Fresh-Install Results
-- `tap setup --apply --json` should return setup evidence without starting
-  receiver, projection, uplink, app-server, or remote-panel processes.
+- `tap setup --apply --json` should return setup evidence only. It should not
+  start receiver, projection, uplink, bridge, app-server, headless runner, or
+  remote-panel processes.
 - `tap status --json` may show zero installed instances until `tap add` runs.
 - `tap ready --surface codex-cli --agent agent-a --apply --json` should publish
   readiness for the concrete `agent-a` lane.
 - `tap comms-doctor --all-known --json` should diagnose locally installed or
-  observed agents. Bundled operator profile surfaces require explicit
+  observed agents. Bundled compatibility profile surfaces require explicit
   `--include-profile-pack`.
 - In an auth-free container or fresh desktop, app/live delivery can remain
   blocked while inbox/receiver evidence is healthy.
@@ -63,8 +143,15 @@ npx @hua-labs/tap setup --profile codex-cli --profile-pack ./tap-profile-pack.js
 npx @hua-labs/tap doctor --setup --profile codex-cli --profile-pack ./tap-profile-pack.json --json
 ```
-If you are using `npx` without a local install, create `tap-profile-pack.json`
-from the example shape below or install the package as a dev dependency first.
+When using `npx` without a local install, the example file under
+`node_modules/@hua-labs/tap/...` may not exist in the current repo. In that
+case, copy the minimal shape below or install the package locally as a dev
+dependency first.
+`--profile-pack <path>` validates a user-provided data file for `setup` and
+`doctor --setup`. `--include-profile-pack` is different: it asks
+`comms-doctor --all-known` to include bundled compatibility profile surfaces in
+its diagnostic target list.
 Profile-pack paths are not auto-corrected because each operator may keep the
 repo, comms directory, state directory, and runtime surfaces in different
@@ -78,6 +165,16 @@ places. Use paths that are valid on the machine where the command runs:
 If the pack is invalid, `tap setup --apply` blocks before writing setup
 artifacts. Repair the reported JSON path, or rerun without `--profile-pack`.
+## Custom And Deprecated Runtime Surfaces
+Gemini CLI remains in the package for legacy compatibility. New first-run
+docs should not use Gemini as a default runtime.
+If your workflow has moved to Antigravity CLI or another runtime, do not copy
+Gemini commands blindly. Use a profile pack to describe the local surface,
+paths, capabilities, and reviewed commands. In `0.6.x`, tap validates that data
+but does not execute profile-pack commands.
 ## Minimal Generic Profile Pack
 ```json
@@ -124,10 +221,15 @@ artifacts. Repair the reported JSON path, or rerun without `--profile-pack`.
 ### `tap doctor --setup` reports `.mcp.json` cwd warning
-Rerun current `tap setup --profile codex-cli --apply --json`. The reviewed
-setup apply path writes guarded tap-managed `.mcp.json` entries with a `cwd`
-field. If an existing user-managed MCP entry is ambiguous, tap fails closed
-instead of overwriting it.
+Rerun the current package version:
+```bash
+npx @hua-labs/tap setup --profile codex-cli --apply --json
+```
+The reviewed setup apply path writes guarded tap-managed `.mcp.json` entries
+with a `cwd` field. If an existing user-managed MCP entry is ambiguous, tap
+fails closed instead of overwriting it.
 ### `tap comms-doctor --all-known` shows app/live blockers
@@ -141,7 +243,10 @@ invent.
 That is expected in `0.6.x`. Profile packs are data-only. Commands in a pack
 must be reviewed manually and remain `defaultEnabled: false`.
-### A command lists a bundled operator profile you do not recognize
+### A command lists a bundled compatibility profile you do not recognize
+Some packages may expose compatibility profiles for existing operator
+environments. These are discoverable metadata, not recommended public defaults.
 Treat it as a compatibility profile, not a public default. Some legacy helper
 surfaces remain discoverable for operators who already own those local runbooks,
@@ -155,7 +260,7 @@ Edit the pack for the current machine. Prefer repo-relative paths when the
 comms directory is inside the repo, and absolute paths when the comms directory
 is shared outside the repo. Do not copy another machine's host paths blindly.
-### Source package says `0.6.0` but npm shows an older version
+### Source package says `0.6.x` but npm shows an older version
 Treat `package.json` version and public npm registry state separately. Verify
 the registry with:

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,19 @@
 # @hua-labs/tap
+## 0.6.1
+### Patch Changes
+- Restructure the npm README for first-run clarity: shorter quick start, early
+  preview boundary, explicit `ready` section, setup/init/add/ready relationship,
+  concise concepts, and npm badges.
+- Move advanced AX and operator-safety details into `AI_GUIDE.md`, including
+  "do not claim" live-delivery rules, profile-pack flag distinctions, safer
+  `git init` guidance, setup mutation boundaries, and troubleshooting notes.
+- Mark Gemini CLI support as legacy/deprecated in public docs. Antigravity CLI
+  should be modeled as a custom profile-pack surface until a dedicated adapter
+  exists.
 ## 0.6.0
 ### Minor Changes
@@ -30,10 +44,10 @@
 - `0.6.0` is an advanced operator preview, not a universal one-click runtime
   installer.
-- HUA machine topology, tmux sessions, one-character agent names, mission
-  governance, and private profile packs are examples or profile-pack inputs;
-  they are not public defaults.
-- Some advanced/HUA helper surfaces still expose existing named profiles for
+- Host-specific topology, local process managers, custom agent names,
+  governance docs, and external profile packs are examples or profile-pack
+  inputs; they are not public defaults.
+- Some advanced helper surfaces still expose existing named profiles for
   compatibility. Portable first-run docs use explicit neutral agents and
   profiles instead of relying on those helper defaults.
 - Codex App consent-drive / IPC remains experimental and strict-gated. A
@@ -59,7 +73,7 @@
 ### Patch Changes
-- c931481: Gen 25 trust-layer repair and delivery hardening.
+- c931481: Trust-layer repair and delivery hardening.
   - split shared state (`TAP_STATE_DIR`) from per-bridge runtime state (`TAP_RUNTIME_STATE_DIR`) so headless restarts and later attached TUI sessions keep the correct identity
   - rebind attached TUI identity from runtime heartbeat and agent-name files instead of relying on one-shot session env injection
   - align bridge status, runtime heartbeat, and presence surfaces so `tap status`, bridge state, and plugin-visible presence report the same runtime truth

package/README.md CHANGED Viewed

@@ -1,48 +1,83 @@
 # @hua-labs/tap
-Zero-dependency CLI for cross-model AI agent communication setup.
+[![npm version](https://img.shields.io/npm/v/@hua-labs/tap.svg)](https://www.npmjs.com/package/@hua-labs/tap)
+[![npm downloads](https://img.shields.io/npm/dm/@hua-labs/tap.svg)](https://www.npmjs.com/package/@hua-labs/tap)
+[![license](https://img.shields.io/npm/l/@hua-labs/tap.svg)](https://github.com/HUA-Labs/tap/blob/main/LICENSE)
-tap connects Claude, Codex, and other agent runtimes through a shared
-file-backed communication layer, with setup reports that keep runtime surfaces,
-durable evidence, and optional live adapters separate.
+`@hua-labs/tap` is a lightweight CLI that lets multiple AI agent runtimes, such
+as Claude and Codex, exchange messages through a shared file-backed
+communication directory.
+It focuses on safe setup, durable delivery evidence, and runtime-specific
+diagnostics without requiring a central daemon for every runtime.
+## Preview Status
+`0.6.x` is an advanced operator preview.
+- Public defaults use neutral concrete agents such as `agent-a` and `agent-b`.
+- `setup` is dry-run-first and only applies reviewed tap-managed changes.
+- Profile packs are data-only validation inputs; tap does not run commands from
+  a profile pack in `0.6.x`.
+- Codex App / Desktop live delivery is experimental and strict-gated by runtime
+  health and route freshness.
+- Gemini CLI support is legacy/deprecated in this release line. If your
+  workflow has moved to Antigravity CLI, treat it as a custom profile-pack
+  surface until tap ships a dedicated adapter.
+For detailed AI-operator troubleshooting, concepts, and advanced runtime notes,
+read [AI_GUIDE.md](./AI_GUIDE.md). AI operators should read it before claiming
+live delivery or runtime readiness.
 ## Requirements
-- **Node.js ≥ 22.6.0** — tap uses the global `WebSocket` API (stable in Node 22+). Node 20 and earlier are not supported; run with `fnm use 22` or `nvm use 22`.
+- Node.js `>=22.6.0`
+- A git repository for setup-managed MCP config
 ## Quick Start
-> `npx @hua-labs/tap` ships a bundled managed MCP server entry and runs that bundled `.mjs` with `node`. `bun` is only required when tap falls back to repo-local TypeScript sources during monorepo or local-dev workflows.
+Run inside an existing git repository. For a new test directory only:
 ```bash
-# 1. Start in a git repo
 git init
+```
+Then inspect and apply setup:
-# 2. Generate a dry-run setup report for your runtime surface
+```bash
+# 1. Inspect setup changes first
 npx @hua-labs/tap setup --profile codex-cli --dry-run --json
-# 3. Apply only reviewed setup-safe changes
+# 2. Apply only reviewed setup-safe changes
 npx @hua-labs/tap setup --profile codex-cli --apply --json
-# 4. Re-check setup readiness and surface status
+# 3. Check setup readiness
 npx @hua-labs/tap doctor --setup --profile codex-cli --json
 npx @hua-labs/tap status --json
+```
+To add and verify a concrete runtime lane later:
-# 5. Add a concrete runtime only when you are ready to patch that runtime
+```bash
 npx @hua-labs/tap add codex --name agent-a
 npx @hua-labs/tap ready --surface codex-cli --agent agent-a --apply --json
-# 6. Diagnose delivery separately from setup
 npx @hua-labs/tap comms-doctor --all-known --json
 ```
-`tap setup` is dry-run by default. The current reviewed apply path creates
-tap-owned directories, an initial tap state file, and guarded tap-managed repo
-`.mcp.json` entries. It does not start receiver, projection, uplink, bridge,
-app-server, headless runner, or remote panel processes, and it does not publish
-presence, repair route tuples, send messages, or read credentials.
+## What Setup Changes
+`tap setup` is dry-run by default. With `--apply`, the reviewed public setup
+path creates tap-owned directories, an initial tap state file, and guarded
+tap-managed repo `.mcp.json` entries.
+It does **not** start receiver, projection, uplink, bridge, app-server,
+headless runner, or remote panel processes. It does not publish presence,
+repair route tuples, send messages, or read credentials.
+Most users should start with `setup`. Use `init` only when you want to manually
+create or reset the shared communication directory and local tap state.
-Supported public setup profiles:
+## Supported Public Setup Profiles
 | Profile          | Use when                                                                |
 | ---------------- | ----------------------------------------------------------------------- |
@@ -50,104 +85,56 @@ Supported public setup profiles:
 | `codex-app`      | Codex App/Desktop route readiness should be inspected read-only.        |
 | `claude-channel` | Claude/channel readiness should be inspected read-only.                 |
-HUA-specific machine names, paths, tmux sessions, one-character Korean agent
-names, and private profile packs are examples, not package defaults.
-For the `0.6.x` preview, release-facing commands use neutral agents such as
-`agent-a` and `agent-b`. HUA profiles and paths can be supplied through a
-reviewed profile pack or HUA runbook, but they are not package defaults.
-## Commands
+## Common Commands
 ### `setup`
-Generate a dry-run-first setup report for public tap deployment.
+Inspect and optionally apply first-run public deployment changes.
 ```bash
 npx @hua-labs/tap setup --profile codex-cli --dry-run --json
 npx @hua-labs/tap setup --profile codex-cli --apply --json
-TAP_AGENT=agent-a
-npx @hua-labs/tap setup --profile codex-app --agent "$TAP_AGENT" --json
-npx @hua-labs/tap setup --profile claude-channel --agent "$TAP_AGENT" --json
 npx @hua-labs/tap setup --profile codex-cli --profile-pack ./tap-profile-pack.json --json
 ```
-`--apply` is intentionally narrow: create reviewed tap-owned directories, an
-initial tap state file, and guarded tap-managed repo `.mcp.json` changes only.
-User-managed or ambiguous MCP entries fail closed before mutation.
+tap refuses to mutate user-managed or ambiguous MCP entries.
-Profile packs are data-only validation inputs in `0.6.x`; tap reports their
-shape and blocks invalid packs before setup mutation, but it does not execute
-pack commands. A generic example is shipped at
-`examples/tap-profile-pack.example.json`.
+### `ready`
-### `init`
+Prepare or verify a concrete agent on a runtime surface.
-Initialize the comms directory and `.tap-comms/` state.
+```bash
+npx @hua-labs/tap ready --surface codex-cli --agent agent-a --json
+npx @hua-labs/tap ready --surface codex-cli --agent agent-a --apply --json
+```
+By default, `ready` reports the current or planned readiness state. With
+`--apply`, it applies reviewed readiness changes for the selected surface and
+agent.
+### `init`
-By default, the comms directory is created inside the current repo at `./tap-comms`.
+Create or reset the shared comms directory and `.tap-comms/` state.
 ```bash
 npx @hua-labs/tap init
 npx @hua-labs/tap init --comms-dir /path/to/comms
-npx @hua-labs/tap init --permissions safe    # default: deny destructive ops
-npx @hua-labs/tap init --permissions full    # no restrictions (use with caution)
-npx @hua-labs/tap init --force               # re-initialize
+npx @hua-labs/tap init --permissions safe
+npx @hua-labs/tap init --permissions full
 ```
 ### `add <runtime>`
-Add a runtime. Probes config, plans patches, applies, and verifies.
+Add a runtime instance and patch the runtime config when verification allows it.
 ```bash
 npx @hua-labs/tap add claude
-npx @hua-labs/tap add codex
-npx @hua-labs/tap add gemini
-npx @hua-labs/tap add claude --force                        # re-install
-npx @hua-labs/tap add codex --name agent-a --port 4520      # explicit port
-npx @hua-labs/tap add codex --name agent-b                  # portMap lookup, else auto-assign
-```
-For Codex app-server instances, `--name agent-a` is the concrete agent identity
-used by `tap ready --agent agent-a`; the managed instance id remains
-`codex-agent-a`.
-Codex instances bind to an app-server port. Resolution order:
-1. `--port <n>` — explicit override.
-2. `portMap[<instanceId>]` from `tap-config.json` / `tap-config.local.json` when the
-   entry is free (no state claim, TCP-available on loopback).
-3. Auto-assign — scan from 4501 upward for the first free port.
-`portMap` is a hint, not a hard requirement: a missing entry or a conflict
-silently drops through to auto-assign. Convention:
-| Port | Instance        | Role               |
-| ---- | --------------- | ------------------ |
-| 4510 | `codex-agent-a` | Agent A            |
-| 4511 | `codex-agent-b` | Agent B            |
-| 4512 | `codex-agent-c` | Agent C            |
-| 4520 | `codex-agent-d` | Agent D            |
-| 4530 | `codex-probe`   | Diagnostic / probe |
-```json
-{
-  "portMap": {
-    "codex-agent-a": 4510,
-    "codex-agent-b": 4511,
-    "codex-agent-d": 4520
-  }
-}
+npx @hua-labs/tap add codex --name agent-a
+npx @hua-labs/tap add codex --name agent-b --port 4520
 ```
-### `remove <runtime>`
-Remove a runtime and rollback config changes.
-```bash
-npx @hua-labs/tap remove claude
-npx @hua-labs/tap remove codex
-```
+`gemini` remains accepted for legacy compatibility, but new first-run docs do
+not recommend it as a default runtime.
 ### `status`
@@ -158,87 +145,57 @@ npx @hua-labs/tap status
 npx @hua-labs/tap status --json
 ```
-Output shows three status levels:
-- **installed** — config written but not verified
-- **configured** — config written and verified
-- **active** — runtime is running and connected
 ### `doctor`
-Diagnose config drift, bridge health, managed MCP wiring, and runtime state.
-Use `--setup` for setup/config/warm-up readiness. Use the plain doctor for
-broader infrastructure checks.
+Diagnose setup, config drift, bridge health, managed MCP wiring, and runtime
+state.
 ```bash
 npx @hua-labs/tap doctor
-npx @hua-labs/tap doctor --fix
 npx @hua-labs/tap doctor --setup --profile codex-cli --json
-npx @hua-labs/tap doctor --setup --profile codex-cli --profile-pack ./tap-profile-pack.json --json
 ```
-`tap doctor --setup --apply` reuses the same guarded setup apply plan as
-`tap setup --apply`. It does not run the broad infrastructure fixer.
 ### `comms-doctor`
-Explain delivery by runtime surface. Use this when you need to separate live
-delivery, durable inbox evidence, receiver/promoter paths, MCP/channel
-visibility, and fallback evidence.
+Explain delivery by runtime surface, including local inbox evidence and live
+adapter readiness.
 ```bash
 npx @hua-labs/tap comms-doctor --all-known --json
-TAP_AGENT=agent-b
-npx @hua-labs/tap comms-doctor --agent "$TAP_AGENT" --plan-send --json
+npx @hua-labs/tap comms-doctor --agent agent-a --plan-send --json
 ```
 ### `flow-doctor`
-Diagnose one receiver/promoter lane without mutating process state. Use this
-when an agent appears present but the operator needs one report for identity,
-receiver dry-run, return-uplink evidence, central presence freshness,
-active-turn queue state, and stale presence cleanup candidates.
+Diagnose one receiver/promoter lane without mutating process state.
 ```bash
-TAP_AGENT=agent-a
-npx @hua-labs/tap flow-doctor --agent "$TAP_AGENT" --json
-npx @hua-labs/tap flow-doctor --agent "$TAP_AGENT" --presence-source-comms-dir ./tap-comms --presence-target-comms-dir ./tap-comms --json
+npx @hua-labs/tap flow-doctor --agent agent-a --json
 ```
-`flow-doctor` is read-only by default. Its only reviewed cleanup mutation is
-`--apply-stale-presence-cleanup`, which archives stale non-lane presence
-records with a manifest and prunes matching stale heartbeat entries. It never
-publishes stale presence, restarts processes, changes route tuples, or deletes
-inbox/archive evidence.
+`flow-doctor` is read-only by default. Its reviewed cleanup mode only archives
+stale non-lane presence records with a manifest and prunes matching stale
+heartbeat entries.
 ### `reviews register`
-Register formal review outcomes into the review evidence stream. Use this when
-review results should be discoverable outside the ordinary inbox flow.
+Register formal review outcomes into a discoverable review evidence stream.
 ```bash
 npx @hua-labs/tap reviews register --source ./tap-comms --dry-run --json
 ```
-The explicit registration path is part of the `0.6.x` preview boundary.
-Automatic registration from every tap reply/review writer path is a future
-follow-up, so release notes should name the explicit command as the current
-workaround.
 ### `serve`
-Start the tap-comms MCP server (stdio). Convenience command for running the MCP server locally.
+Start the bundled tap MCP server on stdio.
 ```bash
 npx @hua-labs/tap serve
-npx @hua-labs/tap serve --comms-dir /path/to/comms
 ```
-For npm installs, `serve` runs the bundled `mcp-server.mjs` entry with `node`. In monorepos or local checkouts, tap may fall back to repo-local `.ts` sources, which still require `bun`.
 ### `bridge start|stop|restart`
-Manage the Codex app-server bridge lifecycle.
+Manage Codex app-server bridge lifecycle.
 ```bash
 npx @hua-labs/tap bridge start codex --agent-name agent-c
@@ -246,163 +203,76 @@ npx @hua-labs/tap bridge stop codex --keep-server
 npx @hua-labs/tap bridge restart codex
 ```
-`bridge stop --keep-server` leaves the managed app-server running and preserves its metadata in instance state so the next `bridge start` or `bridge restart` can reuse the existing session instead of forcing a fresh app-server.
-## Supported Runtimes
-| Runtime | Config                  | Bridge                 | Mode               |
-| ------- | ----------------------- | ---------------------- | ------------------ |
-| Claude  | `.mcp.json`             | native-push (fs.watch) | No daemon needed   |
-| Codex   | `~/.codex/config.toml`  | WebSocket bridge       | Daemon per session |
-| Gemini  | `.gemini/settings.json` | polling                | No daemon needed   |
-## `--json` Flag
-All commands support `--json` for machine-readable output. Returns a single JSON object to stdout with no human log noise.
-```bash
-npx @hua-labs/tap status --json
-```
-```json
-{
-  "ok": true,
-  "command": "status",
-  "code": "TAP_STATUS_OK",
-  "message": "2 runtime(s) installed",
-  "warnings": [],
-  "data": {
-    "version": "0.x.y",
-    "commsDir": "/path/to/comms",
-    "runtimes": {
-      "claude": { "status": "active", "bridgeMode": "native-push" },
-      "codex": { "status": "configured", "bridgeMode": "app-server" }
-    }
-  }
-}
-```
-Error codes use `TAP_*` prefix: `TAP_ADD_OK`, `TAP_NO_OP`, `TAP_PATCH_FAILED`, etc.
-Exit codes: `0` = ok, `1` = error.
+## Core Concepts
+- **Runtime**: an AI tool or environment tap can connect to, such as Claude or
+  Codex.
+- **Agent**: a named participant, such as `agent-a`, that sends or receives
+  messages.
+- **Surface**: a specific runtime interface, such as `codex-cli` or
+  `codex-app`.
+- **Comms directory**: the shared file-backed message store for inboxes,
+  reviews, handoffs, and evidence.
+- **Profile**: a setup target that describes which runtime surface tap should
+  inspect or prepare.
+- **Profile pack**: a data-only input for validating custom operator
+  environments.
 ## Permissions
-`tap init` auto-configures runtime permissions.
+Safe mode reduces destructive local file operations. It is not a
+network-isolated mode.
-### Safe mode (default)
+- `safe` is the default.
+- `full` enables less restricted local runtime settings and should only be used
+  on trusted machines.
-**Claude**: Adds deny rules to `.claude/settings.local.json` blocking destructive operations (force push, hard reset, rm -rf, etc.).
+See [AI_GUIDE.md](./AI_GUIDE.md#permissions-and-safety) for details.
-**Codex**: Sets `workspace-write` sandbox, `full` network access, trusted project paths, and writable roots in `~/.codex/config.toml`.
+## JSON Output
-### Full mode
+Most operational commands support `--json` for machine-readable output.
 ```bash
-npx @hua-labs/tap init --permissions full
-```
-**Claude**: Removes tap-managed deny rules. User-added rules preserved.
-**Codex**: Sets `danger-full-access` sandbox. Use on trusted local machines only.
-## How It Works
-Agents communicate through a shared directory (`comms/`) using markdown files:
-```
-comms/
-├── inbox/          # Agent-to-agent messages
-├── reviews/        # Code review results
-├── findings/       # Out-of-scope discoveries
-├── handoff/        # Session handoff documents
-├── retros/         # Retrospectives
-└── archive/        # Archived messages
+npx @hua-labs/tap status --json
 ```
-Each runtime has an adapter that:
-1. **Probes** — finds config files, checks runtime installation
-2. **Plans** — determines what patches to apply
-3. **Applies** — backs up and patches config files
-4. **Verifies** — confirms the runtime can read the config
+Exit codes use `0` for ok and `1` for error. Error codes use the `TAP_*`
+prefix.
-The adapter contract (`RuntimeAdapter`) is the extension point for adding new runtimes.
-## Surface-First Delivery Model
-tap does not route by display name alone. It asks which runtime surface is
-available and what evidence exists:
-- CLI/TUI surfaces use durable inbox files plus receiver/promoter loops.
-- Claude/channel surfaces use channel readiness and durable inbox fallback.
-- Codex App consent-drive / IPC is an experimental live adapter and must see
-  fresh explicit runtime health before it is treated as live-ready.
-- Inbox and projection files are durable evidence, not proof of live model
-  execution.
+## Supported Runtimes
-Use `tap comms-doctor` to inspect these boundaries before claiming live
-delivery.
+| Runtime | Status                    | Notes                                      |
+| ------- | ------------------------- | ------------------------------------------ |
+| Claude  | supported                 | Uses `.mcp.json` / channel-style delivery. |
+| Codex   | supported                 | Uses CLI, MCP, and app-server surfaces.    |
+| Gemini  | legacy / deprecated       | Kept for compatibility only.               |
+| Other   | custom profile-pack input | Use data-only profile packs in `0.6.x`.    |
-## 0.6 Preview Boundary
+Antigravity CLI is not a bundled adapter in `0.6.x`. Model it as a custom
+profile-pack surface until a dedicated integration is released.
-`0.6.x` should be described as an advanced operator preview:
+## Examples
-- Public defaults use neutral profile ids and concrete agents.
-- Receiver/promoter plus durable inbox/projection/uplink evidence is the
-  portable backbone for CLI/TUI/headless receive.
-- Codex App consent-drive / IPC remains experimental and strict-gated.
-- HUA machine topology, tmux sessions, one-character agent names, and
-  mission/devlog governance are examples or profile-pack inputs.
-- Broad role aliases such as `codex`, `reviewer`, `implementer`,
-  `implementation`, and `tower` are unsafe assignment targets unless a reviewed
-  role mapping makes them unambiguous.
-- Archive-audit commands remain preserved, but they are not part of the
-  first-run package story.
+- Generic profile pack:
+  [`examples/tap-profile-pack.example.json`](./examples/tap-profile-pack.example.json)
+- Narrative examples:
+  [`examples/`](./examples/)
-For AI-facing troubleshooting and first-run detail, read the package-local
-[AI Guide](./AI_GUIDE.md).
+The narrative examples are real collaboration stories, not setup defaults.
 ## Recent Changes
-### Config And Lifecycle
-- **Layered config resolution** — ConfigSource-based loading, instance config isolation, and runtime drift detection reduce cross-instance config bleed-through
-- **Managed lifecycle** — server lifecycle state, dual-session prevention, and health monitoring make bridge startup and recovery more predictable
-- **Repair path** — `tap doctor --fix` can now repair more managed config drift, including Codex MCP table mismatches
-### Identity And Routing
-- **Permission mode + routing** — permission mode support, qualified name routing, and the name-claim protocol tighten runtime identity semantics
-- **Claim safety** — same-instance claim stealing is blocked while a live claim is still valid, while expired claims can still be reclaimed safely
-### Bridge And Runtime Updates
-- **Bridge split and cleanup** — the legacy `bridge.ts` monolith was split into focused modules, then the old wrapper logic was removed
-- **Codex MCP defaults** — managed Codex installs now persist `[mcp_servers.tap] approval_mode = "auto"` and re-sync the runtime config hash when tap rewrites managed config
-- **Bundled MCP runtime** — bundled `.mjs` server entries now prefer `node`; repo-local TypeScript sources still use `bun`
-- **Hotfixes** — ESM `require()` breakage, temp file leaks in name claims, and claim-stealing edge cases were fixed during publish prep
-### Trust Layer And Delivery
-- **Shared vs runtime state split** — `TAP_STATE_DIR` remains the shared source of truth while `TAP_RUNTIME_STATE_DIR` is reserved for per-bridge runtime files, so headless restarts and later TUI attaches keep the same identity contract
-- **Attached TUI rebind** — Codex TUI attach can now recover `agentId` and `agentName` from runtime heartbeat and agent-name files without relying on per-session env injection
-- **State surface alignment** — bridge status, runtime heartbeat, and presence now read from the same state surfaces, reducing mismatches between `tap status`, bridge state, and plugin-visible presence
-- **Broadcast dedupe** — bridge-dispatched notifications are deduplicated so one broadcast does not fan out twice
-- **Ack storm prevention** — peer DM auto-replies are rate-limited to stop acknowledgement loops from flooding the inbox
-### Test Hardening
-- **CLI-path coverage** — integration tests now exercise the actual `bridge` and `up` command paths that patch Codex `approval_mode`
-- **Publish prep stabilization** — failing suites were fixed or quarantined so release-blocking regressions show up earlier in the main package tests
+See [CHANGELOG.md](./CHANGELOG.md) for full release history.
-## Migration Notes
+Highlights in `0.6.x`:
-- **No hard breaking API change is intended in this release train**, but managed runtime defaults changed. Treat this as an operational migration, especially for Codex setups.
-- **Bundled MCP command changed for packaged installs** — if your managed `config.toml` still points bundled tap MCP entries at `bun`, rerun `npx @hua-labs/tap add codex --force` or `npx @hua-labs/tap doctor --fix` so bundled `.mjs` entries switch to `node`.
-- **Repo-local source workflows still use `bun`** — local monorepo or source-checkout paths can still resolve to `.ts` server entries, so keep `bun` installed for development workflows.
-- **Codex approval mode should be `auto`** — managed Codex installs are expected to end up with `[mcp_servers.tap] approval_mode = "auto"`. `tap doctor --fix` will repair stale managed tables.
-- **Restart Codex bridges after upgrading** — managed bridge launches now export both `TAP_STATE_DIR` and `TAP_RUNTIME_STATE_DIR`; restart existing bridge processes so headless/runtime identity repair is active end-to-end.
+- dry-run-first public setup profiles;
+- `ready`, `comms-doctor`, and `flow-doctor` for surface-specific diagnostics;
+- explicit `tap reviews register` evidence registration;
+- profile-pack validation for custom environments;
+- stricter broad-role and stale-presence guards;
+- packaged AI operator guide and npm provenance publishing.
 ## License

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@hua-labs/tap",
-  "version": "0.6.0",
-  "description": "Zero-dependency CLI for cross-model AI agent communication setup",
+  "version": "0.6.1",
+  "description": "Lightweight file-backed CLI for cross-model AI agent communication setup",
   "bin": {
     "tap": "bin/tap.mjs",
     "tap-comms": "bin/tap.mjs"
@@ -68,7 +68,6 @@
     "mcp",
     "claude",
     "codex",
-    "gemini",
     "cli"
   ],
   "author": "HUA Labs",