@cordfuse/crosstalk 7.0.0-alpha.8 → 7.0.0-beta.1

package/GUIDE-CLI.md

@@ -0,0 +1,322 @@
+# Crosstalk CLI Guide
+
+Reference for the `crosstalk` CLI. Run `crosstalk <noun> --help` (or `crosstalk <noun> <verb> --help`) for inline flags.
+
+Requires: Node.js ≥ 20 + git on PATH. alpha.18 is a single-package install — `npm install -g @cordfuse/crosstalk`. The daemon lives as `crosstalk daemon …` inside the same package; there's no separate `crosstalkd` binary anymore.
+
+The surface is strict **noun-verb**, mirroring [`@cordfuse/llmux`](https://www.npmjs.com/package/@cordfuse/llmux):
+
+| Noun | Verbs |
+|---|---|
+| `auth` | `login` · `logout` · `whoami` · `list` · `use` |
+| `token` | `create` · `list` · `revoke` · `rename` |
+| `server` | `start` · `stop` · `restart` · `status` · `logs` |
+| `transport` | `init` · `rm` |
+| `channel` | `list` · `create` · `rename` · `delete` |
+| `message` | `send` · `replies` |
+| `workflow` | `compose` · `run` · `status` |
+| `chat` | `<agent>` (positional) · `--shell` |
+| `agent` | `list` |
+| `logs` | `list` · `tail` |
+| `settings` | `show` |
+| `daemon` | `dispatch` · `init` · `stop` (internal — spawned by `server start` + systemd) |
+| `status` | (no verb — transport-level snapshot) |
+| `version` | (no verb — print client + engine versions) |
+
+**Addressing.** Each transport on the machine is identified by a name — the operator picks it at `crosstalk transport init` (default: `crosstalk`). Every verb that operates on an existing transport takes an optional `--containername <name>` flag (or `-c <name>`).
+
+```sh
+crosstalk transport init                            # default 'crosstalk' transport
+crosstalk transport init --containername uat        # second transport 'uat'
+crosstalk transport init -c prod --remote git@...   # third, with upstream at init
+```
+
+**Profiles.** The CLI holds credentials for multiple engines (e.g. local loopback + hosted prod) at `~/.config/crosstalk/credentials.json`. `--profile <name>` overrides the active profile per-invocation; `--server <url>` overrides the target server URL when logging in. See [Auth](#auth).
+
+---
+
+## Transport
+
+### `crosstalk transport init [--containername <name>] [--remote <url>]`
+
+Scaffold a new transport on this machine (or repair an incomplete one — phases are independent and idempotent).
+
+`<base>` defaults to system mode (`/var/lib/crosstalk`, runs as the `crosstalk` service user). Set `CROSSTALK_USER_MODE=1` to switch to user mode:
+- Linux: `$XDG_DATA_HOME/crosstalk/` (= `~/.local/share/crosstalk/` if unset)
+- macOS: `~/Library/Application Support/crosstalk/`
+- Windows: `%LOCALAPPDATA%\crosstalk\`
+
+Mechanics: copies the template into `<base>/<name>/transport/` (via `crosstalk daemon init`), `git init --initial-branch=main` + initial commit, allocates a free API port (`crosstalk` default → 7000; named transports search from 7001), records the port at `<base>/<name>/api-port`.
+
+```sh
+crosstalk transport init
+# → Transport 'crosstalk' ready
+# →   api port:   7000 (allocated)
+
+crosstalk transport init --containername uat --remote git@github.com:me/transport.git
+# → Transport 'uat' ready
+# →   api port:   7001 (allocated)
+# →   remote:     git@github.com:me/transport.git (added)
+```
+
+### `crosstalk transport rm [--containername <name>] [--force]`
+
+Full teardown: stops the engine (if running), then deletes the entire `<base>/<name>/` tree (transport git repo, dispatcher state, pid/log/port files). Prompts with an explicit enumeration of what gets deleted; `--force` / `-f` skips for scripted use. **Cannot undo — all message history is lost.**
+
+---
+
+## Server (engine lifecycle)
+
+User mode (`CROSSTALK_USER_MODE=1`): the engine runs as a detached host process owned by the operator. PID at `<base>/<name>/crosstalk-state/crosstalk.pid`, log at `<base>/<name>/crosstalk-state/crosstalk.log`.
+
+System mode (default): the engine runs as the `crosstalk` service user under systemd. The `crosstalk server` verbs in this mode print a hint redirecting to `sudo systemctl <verb> crosstalk@<name>` — that's the right lifecycle when systemd owns the process.
+
+### `crosstalk server start [--containername <name>]`
+
+Spawn the engine (`crosstalk daemon dispatch …`) as a detached host process for the named transport. Brief 150ms liveness check catches immediate spawn failures (broken tsx resolution, missing transport dir) before returning success. Output includes the PID + the API loopback URL.
+
+### `crosstalk server stop [--containername <name>]`
+
+SIGTERM the running engine. SIGKILL after a 5s grace if it doesn't shut down cleanly. Idempotent — reports `was not running` and exits 0 if there's no live PID.
+
+### `crosstalk server restart [--containername <name>]`
+
+Stop + start. State at `<base>/<name>/` is preserved across the restart.
+
+### `crosstalk server status [--containername <name>] [--probe]`
+
+Reports PID + API port + uptime (Linux only). With `--probe`, also pings `/healthz` on the API loopback.
+
+### `crosstalk server logs [--containername <name>] [-f|--follow]`
+
+Tails `<base>/<name>/crosstalk-state/crosstalk.log`. Last 200 lines by default; `-f` follows.
+
+---
+
+## Auth
+
+The engine enforces bearer-token auth on every operational endpoint. Once the engine is up:
+
+1. Visit the `/setup?token=…` URL printed at engine boot to create the first admin user (one-time web wizard).
+2. Run `crosstalk auth login` — interactive prompts for username + passphrase. The engine returns a bearer token; the CLI stores it as the `default` profile in `~/.config/crosstalk/credentials.json` (mode 0600). All subsequent CLI calls send `Authorization: Bearer …` automatically.
+
+`/healthz` and `/version` stay open as monitoring probes; everything else needs a valid token.
+
+### `crosstalk auth login [--server <url>] [--username <name>] [--passphrase <pp>] [--profile <name>]`
+
+Prompts interactively if either credential flag is omitted (no-echo passphrase). Saves a profile in credentials.json and sets it active. `--profile` defaults to `default`; pass a different name to keep multiple profiles side-by-side (one CLI can talk to several engines). `--server` records the engine URL for the profile (default: `http://127.0.0.1:7000`).
+
+### `crosstalk auth logout [--profile <name>] [--no-revoke]`
+
+Best-effort revocation via `POST /api/auth/logout` + removes the active profile from credentials.json. `--no-revoke` skips the server-side call (useful when the engine is offline). `--profile` targets a specific profile instead of the active one.
+
+### `crosstalk auth whoami [--profile <name>]`
+
+Prints username / display name / role / createdAt from `GET /api/account`. Exits 1 if not logged in.
+
+### `crosstalk auth list`
+
+Tabular list of saved profiles with their server URL + username + active marker.
+
+```
+  PROFILE  USERNAME          SERVER
+* default  stevekrisjanovs   http://127.0.0.1:7000
+  prod     ops               https://crosstalk.cordfuse.io
+```
+
+### `crosstalk auth use <profile>`
+
+Switch the active profile. Subsequent commands use that profile's server + token until you switch again (or pass `--profile <other>` per-invocation).
+
+---
+
+## Token
+
+API tokens for non-CLI clients (CI, scripts, HTTP). The CLI's own bearer lives in the credentials profile from `auth login` — `token` operations are for additional tokens you want to hand out.
+
+### `crosstalk token list`
+
+Lists your own tokens (id, name, created-rel-time, last-used-rel-time, expires if set). You only ever see tokens you own.
+
+### `crosstalk token create <name>`
+
+Creates a new bearer token. The plaintext secret is printed once; copy it immediately for use in non-CLI contexts (HTTP clients, CI). The CLI does NOT swap to the new token — that's `auth login`.
+
+### `crosstalk token revoke <tokenId>`
+
+Revokes a token by id (use `token list` to find ids). Engine refuses to revoke tokens you don't own.
+
+### `crosstalk token rename <tokenId> --name <label>`
+
+Renames an existing token's label. Ownership-checked.
+
+---
+
+## Channel
+
+All channel operations talk to the engine's HTTP API on `127.0.0.1:<port>` (or the active profile's `server` URL for remote engines).
+
+### `crosstalk channel list`
+
+Lists every channel on the transport with its UUID + name + optional parent.
+
+### `crosstalk channel create <name>`
+
+Creates a new top-level channel.
+
+### `crosstalk channel rename <handle> <new-name>`
+
+Renames a channel. `<handle>` is either the current name or the UUID.
+
+### `crosstalk channel delete <handle>`
+
+Deletes a channel. The CLI resolves the channel's current name first and passes it as the typed-confirmation token — the verb itself is the operator's explicit consent.
+
+---
+
+## Message
+
+### `crosstalk message send --to <model>[@<machine>] [--as <persona>] [--fanout <n>] [--channel <name|uuid>] [--from <name>] <body|file|->`
+
+Write a primitive sub-message. `<body>` can be an inline string, a file path, or `-` (stdin).
+
+```sh
+crosstalk message send --to sonnet "summarise CROSSTALK.md"
+crosstalk message send --to sonnet --fanout 3 --as junior-developer "draft a release codename"
+crosstalk message send --to opus@cachy --channel mctest "review these drafts" < drafts.md
+```
+
+Flags:
+- `--to <model>[@<machine>]` (required) — model identity in qualified `<provider>/<model>` form (or a bare model name when claimed uniquely); optional `@machine` for scoped routing. See `data/crosstalk.yaml`.
+- `--fanout <n>` — dispatch N identical sub-primitives in parallel (each becomes a separate worker reply)
+- `--as <persona>` — invoke the model with `local/actors/<persona>.md` prepended as system prompt
+- `--channel <name|uuid>` — explicit channel (default: auto-pick if exactly one exists)
+- `--from <name>` — override the `from:` identity
+
+### `crosstalk message replies <relPath>...`
+
+Poll reply status for one or more dispatched messages. Exits 0 when every target is REPLIED or FAILED, exit 2 while anything is PENDING — agents can poll cheaply in a loop.
+
+```sh
+crosstalk message replies 2026/06/13/130218231Z-15387115.md
+# → REPLIED 2026/06/13/130218231Z-15387115.md <- sonnet@laptop (2026/06/13/130218252Z-5f54c697.md)
+```
+
+---
+
+## Workflow
+
+### `crosstalk workflow compose <prompt> [--channel <name|uuid>] [--compiler <model>]`
+
+Interactive: engine compiles `<prompt>` into a workflow plan, prints the YAML for review, then prompts `[y]es / [e]dit / [n]o`. Choosing `e` opens `$VISUAL` / `$EDITOR` / `vi` on a temp file; on save the edited YAML is reviewed again. On `y`, the plan is submitted.
+
+```sh
+crosstalk workflow compose "Fan out 3 sonnet drafts. Have opus pick the strongest."
+```
+
+`--compiler <model>` overrides the default compiler agent (the first claimed model otherwise).
+
+### `crosstalk workflow run <file> [--channel <name|uuid>] [--from <name>]`
+
+Submit an already-authored workflow YAML (or markdown body) file. The runtime handles execution end-to-end: compile pass (prose → JSON plan) → fanout → synthesize → route. See [transport/CROSSTALK.md § Workflows](transport/CROSSTALK.md#workflows) for the protocol.
+
+```sh
+crosstalk workflow run workflows/review-and-synthesize.md
+```
+
+### `crosstalk workflow status [--id <childUuid>]`
+
+Without `--id`: tabular list of every workflow on the transport — child uuid prefix, parent channel name, phase, fanout completion ratio.
+
+With `--id <childUuid>`: detailed snapshot of one workflow (uuid, parent, marker path, phase, fanout/synth state, complete flag).
+
+---
+
+## Chat (interactive PTY)
+
+### `crosstalk chat <agent> [--cwd <path>]`
+
+Spawn an interactive agent CLI as a foreground child of the operator's shell. Supported agents: `claude`, `codex`, `gemini`, `qwen`, `opencode`, `agy`.
+
+`<agent>` is required (the host may have multiple agent CLIs installed; operator picks explicitly). `--cwd <path>` chdir's the child before exec — useful for pinning the session to a specific project root.
+
+**Lifecycle:** agent owns stdin/stdout/stderr while running. When the operator exits the agent (Ctrl-D / `/quit` / agent finishes), the child is reaped and `crosstalk chat` exits with the same status. There is no persistent live agent — crosstalk is async-by-design, no detach/reattach model. SIGINT/SIGTERM are forwarded for clean shutdown; defensive SIGKILL fallback on the rare case where an agent CLI forks a holding subprocess.
+
+Auth setup is per-agent and lives in `data/crosstalk.yaml`'s per-provider `env_file:` (env-injected at dispatch spawn) plus the agent's own one-time login command (e.g. `codex login --with-api-key`). Recipes in `transport/auth/README.md`.
+
+```sh
+crosstalk chat claude
+crosstalk chat codex --cwd ~/Repos/myproject
+```
+
+### `crosstalk chat --shell`
+
+Drop into your `$SHELL` (or bash if unset) — useful for one-time setup commands. No agent positional needed.
+
+```sh
+crosstalk chat --shell
+  npm install -g @anthropic-ai/claude-code
+  exit
+```
+
+**After installing a new CLI**, run `crosstalk server restart` so the dispatcher rescans PATH and claims it. The dispatcher reads PATH only at startup; CLIs installed while the engine is running don't appear in `claimed_models` until the next restart. `crosstalk status` will say so explicitly.
+
+---
+
+## Agent / Logs / Settings
+
+These three nouns surface engine introspection that mirrors what the web UI shows on `/agents`, `/logs`, and `/settings`.
+
+### `crosstalk agent list [--installed] [--json]`
+
+Catalog of agent CLIs on this host. Default columns: `name`, `installed` (on PATH yes/no), `yaml` (referenced in `data/crosstalk.yaml`), `claimed` (engine has at least one claimed model on this CLI). `--installed` filters to only the present ones. `--json` for raw JSON.
+
+### `crosstalk logs list [--limit N] [--json]`
+
+Snapshot of recent engine log entries (the structured event stream — same source as the `/logs` web page). `--limit N` trims to the last N entries; `--json` emits raw JSON instead of one human line per entry.
+
+### `crosstalk logs tail [--since <iso>]`
+
+Live SSE stream — Ctrl-C to stop. `--since <iso>` replays everything newer than the given ISO-8601 timestamp before switching to live updates.
+
+### `crosstalk settings show [--json]`
+
+Current engine settings snapshot: alias, version, transportRoot, claimedModels, apiPort, pollSeconds.
+
+---
+
+## Meta
+
+### `crosstalk status [--containername <name>]`
+
+Prints transport name, host storage path (escape hatch for power users who want to poke around with raw git), engine alias + version, claimed models, dispatch heartbeat + age, cursor, channel list, errors-logged count.
+
+### `crosstalk version`
+
+Prints client + engine versions side-by-side. Engine is queried over the HTTP API; reports `(unreachable)` if the engine isn't running.
+
+Version skew (client and engine on different versions) triggers a `[WARN]` block to stderr on the first API call. Fix by `npm install -g @cordfuse/crosstalk` to update. One-shot per process.
+
+---
+
+## Environment variables
+
+| Env | Default | Effect |
+|---|---|---|
+| `CROSSTALK_USER_MODE` | unset (system mode) | Set to `1` for user mode — engine runs as the operator, paths under the operator's home. |
+| `CROSSTALK_API_PORT` | `7000` | Engine HTTP port. Honored by both the CLI (when talking to a non-default loopback) and the engine itself (when binding). |
+| `CROSSTALK_API_BIND` | `127.0.0.1` | Engine bind address. Loopback by default; only change if you understand what you're exposing. |
+| `CROSSTALK_ALIAS` | `<transport-name>` | Override the dispatcher's machine identity in the bus. |
+| `DISPATCH_POLL_SECONDS` | `30` | Engine main-loop tick interval. |
+| `XDG_CONFIG_HOME` | per-OS default | Where `credentials.json` lives. |
+| `XDG_DATA_HOME` | per-OS default | Where transport storage lives (user mode). |
+| `VISUAL` / `EDITOR` | `vi` | Used by `workflow compose` when editing the YAML preview. |
+
+---
+
+## Where to go next
+
+- Protocol spec: [transport/CROSSTALK.md](transport/CROSSTALK.md)
+- Natural-language pattern (agent drives crosstalk for you): [GUIDE-PROMPTS.md](GUIDE-PROMPTS.md)
+- alpha.18 design rationale + full old→new migration table: [V8-CLI-ALIGN.md](V8-CLI-ALIGN.md)
+- Architecture overview: [README.md](README.md)

package/GUIDE-PROMPTS.md

@@ -0,0 +1,118 @@
+# Crosstalk Natural-Language Guide
+
+You don't have to memorise the `crosstalk` CLI to use Crosstalk. You can just **talk to it.**
+
+The interactive Crosstalk pattern: **`crosstalk chat <agent>`** spawns the named agent CLI as a foreground process attached to your terminal. The transport's `PROTOCOL.md` orients the agent — it learns the layout, the six core nouns, and which `crosstalk` commands it can run on your behalf. From there you speak in plain language; the agent translates into commands, waits for answers, and tells you what came back.
+
+`<agent>` is required (positional) — the host may have multiple agent CLIs installed, and there's no implicit default. When you exit the agent (Ctrl-D / `/quit` / agent finishes), the process is gone — crosstalk is async-by-design, no persistent live agent.
+
+```sh
+crosstalk chat claude
+> ask sonnet on cachy to summarise report.md
+```
+
+The agent CLI owns your terminal while running; Crosstalk owns the bus on disk; they meet at the transport git repo.
+
+> **New to Crosstalk?** The [main README](README.md) has the six-word glossary (Transport / Machine / Message / Model / Actor / Channel) plus a local-only quickstart. Worth a 60-second read first.
+
+This is the companion to the **[CLI guide](GUIDE-CLI.md)**. Same system, two front doors: type commands, or just speak.
+
+> The natural-language interface is **agent-agnostic**, like the rest of Crosstalk. Whatever coding agent you already run — Claude Code, Codex, Gemini, Qwen Code, opencode, Antigravity — can be your interactive front door, as long as it can read `PROTOCOL.md` and run shell commands.
+
+---
+
+## Starting an interactive session
+
+```sh
+crosstalk chat claude           # or: crosstalk chat codex, crosstalk chat gemini, ...
+```
+
+This spawns the named agent CLI as a foreground child of your shell — the agent owns stdin/stdout/stderr while running. Use `--cwd <path>` to pin the session to a specific project root if your agent needs the transport's `PROTOCOL.md` and `CLAUDE.md` for cwd-based orientation.
+
+You don't need to teach the agent anything. Start talking.
+
+> **Interactive ≠ being a model.** When you're talking to the agent this way, *you* (through the agent) are the human's front door. You are not a model in the bus and you do not process incoming messages. The engine (started via `crosstalk server start` or systemd) handles incoming traffic via its internal `crosstalk daemon dispatch` loop. Don't start a second dispatcher from inside the chat session — it would compete with the one already running.
+
+---
+
+## The phrasebook
+
+Say it however feels natural; these are the intents the interactive agent recognises and the commands it runs on your behalf. There's one CLI — `crosstalk` — and it talks to the engine over HTTP. The daemon lives as `crosstalk daemon …` inside the same binary but is internal; the agent never invokes it directly.
+
+| You say… | What the agent does |
+|---|---|
+| "ask sonnet to summarise `report.md`" | `crosstalk message send --to sonnet "..."`, polls with `crosstalk message replies <path>`, surfaces the reply |
+| "ask sonnet on cachy to look for typos" | `crosstalk message send --to sonnet@cachy "..."`, waits, reports back |
+| "fan out three drafts running sonnet" | `crosstalk message send --to sonnet --fanout 3 "..."`, surfaces all three replies when they arrive |
+| "in the *sprint-42* channel, ask opus to plan the work" | adds `--channel sprint-42` to the `message send` |
+| "run this workflow" (with file path) | `crosstalk workflow run <file>` — the runtime auto-creates a child channel and runs compile → fanout → synthesize → route deterministically |
+| "fan out three drafts then have opus pick one" (free-form prose) | `crosstalk workflow compose "<your prose>"` — the engine compiles, surfaces the YAML plan for your `[y]es / [e]dit / [n]o` review, then dispatches |
+| "how's that workflow going?" / "show the workflow status" | `crosstalk workflow status` (all) or `--id <childUuid>` for a specific one |
+| "is the dispatcher alive?" / "check status" | `crosstalk server status --probe` (local lifecycle) or `crosstalk status` (transport snapshot — heartbeat, channels, claimed models) |
+| "what failed?" | scans the current channel for `failed: true` replies and summarises |
+| "make a channel called *release-7*" | `crosstalk channel create release-7`, tells you the UUID |
+| "what channels exist?" | `crosstalk channel list` |
+| "rename this channel to *release-8*" | `crosstalk channel rename <current> release-8` |
+| "delete the *batch-old* channel" | `crosstalk channel delete batch-old` (the verb is your explicit consent — no extra typed confirmation needed) |
+| "what agent CLIs are installed here?" | `crosstalk agent list` |
+| "show the recent engine logs" / "tail the logs" | `crosstalk logs list` (snapshot) or `crosstalk logs tail` (live SSE) |
+| "what's the engine configured with?" | `crosstalk settings show` |
+| "add a new model called fable" | edits `data/crosstalk.yaml`, commits, then `crosstalk server restart` so the dispatcher rescans PATH and claims it |
+| "pull the latest" | `git pull --rebase` in the transport directory |
+
+There is no "what's in the DLQ?" — v7 has no DLQ. Failures land in the channel as normal messages with `failed: true` + `error:` in frontmatter; "what failed?" asks the agent to grep the current channel for those.
+
+---
+
+## Coordinating a team in plain language
+
+The real power is workflows. Describe the goal and let the runtime dispatch — no model plays an orchestration role; the runtime drives it deterministically.
+
+> **You:** "Fan out three drafts of the release notes via sonnet, then have opus pick the strongest unified version."
+
+The interactive agent runs `crosstalk workflow compose "<your prose>"`. The engine takes over:
+
+1. One LLM call compiles the prose to a structured workflow plan (`fanout: {to: sonnet, count: 3, ...}`, `synthesize: {to: opus, ...}`) and prints the YAML for review.
+2. You confirm with `[y]es`, tweak with `[e]dit` (opens `$VISUAL`/`$EDITOR`), or abort with `[n]o`. On `y`, the plan is submitted and a child channel is auto-created.
+3. Three sub-primitives addressed to scoped recipients (`sonnet@<alias>`, round-robined across the dispatcher registry) fire into the child channel.
+4. Once all three replies are in, one synthesis sub-primitive with the candidates concatenated dispatches to opus.
+5. The synthesis reply gets routed back to you in the parent channel.
+
+You see:
+
+> *(running workflow…)*
+> **workflow@cachy:** *(final synthesis — the chosen unified release-notes draft.)*
+
+You never see the orchestration — only the result. To drill into how the work happened, ask "show me the child channel for that workflow."
+
+---
+
+## What to expect
+
+- **It's asynchronous.** Each round-trip is roughly 5–30 seconds — your message is committed and pushed, the recipient's dispatcher polls, the agent runs, its reply is committed and pulled back. The interactive agent will say something like *"(waiting for sonnet…)"* and surface the answer when it arrives.
+- **Replies are matched by fact, not by claim.** Crosstalk records which message each reply answers via the `re:` field, so "has it replied yet?" is always answered from ground truth — a busy or confused model can't fake completion.
+- **At-least-once delivery.** For anything with side effects (sending an email, deploying), the interactive agent — and the models — check the channel for prior completion before repeating. For lookups and advice, the occasional duplicate is harmless.
+- **Failures are loud.** A failed dispatch lands as a normal reply with `failed: true` + `error: <text>`. The interactive agent will surface failures the same way it surfaces successes — no separate place to check.
+- **If nothing comes back** (~10 minutes), the interactive agent will offer to check `crosstalk server status --probe` (local) or `crosstalk status` (engine API) for the dispatcher heartbeat. Usually it's a remote dispatcher that's down or a model whose CLI isn't wired correctly in `data/crosstalk.yaml`.
+
+---
+
+## Tips for good results
+
+- **Name the machine when it matters.** "ask sonnet" reaches sonnet on whichever dispatcher claims it first; "ask sonnet on cachy" pins it to one machine. Use the machine when *where* the work runs is part of the ask.
+- **Name the channel for threaded work.** If you don't, and there's more than one channel, the agent will ask which one rather than guess.
+- **Be explicit for non-idempotent actions.** "deploy to staging" is a side effect; say so clearly and the model will verify it hasn't already happened.
+- **You don't need to know UUIDs or paths — ever.** If the agent starts showing you raw file paths or git output, tell it to "talk to me like a person"; hiding that machinery is its job.
+
+---
+
+## When to drop to the CLI
+
+Natural language covers day-to-day operation. Reach for the **[CLI guide](GUIDE-CLI.md)** when you're:
+
+- scripting or automating (cron jobs, CI),
+- editing `data/crosstalk.yaml` to wire a new agent (and follow with `crosstalk server restart` to reload it),
+- managing the engine lifecycle (`crosstalk server start` / `stop` / `restart`), or
+- inspecting state at a low level (cursor SHA, heartbeat freshness via `crosstalk status`).
+
+Both drive the exact same transport — use whichever is faster for the task in front of you.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cordfuse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.