talking-stick 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -2,7 +2,7 @@
 
 An MCP coordination server that lets multiple AI coding agents share a single workspace without stepping on each other. One agent holds the stick at a time; handoffs carry structured context so the next agent doesn't have to re-derive it.
 
-**Version:** 0.1.0-alpha. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
+**Version:** 0.1.0-alpha.2. Multi-process-safe (SQLite WAL), liveness-aware, no daemon. Supports Claude Code, Codex CLI, Gemini CLI, and OpenCode out of the box.
 
 ## Quickstart
 
@@ -27,7 +27,7 @@ That's it. The next time two agents `cd` into the same repo, they see each other
 
 | Method | Command | Notes |
 |---|---|---|
-| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha`. Requires Node ≥ 22. |
+| **From npm** | `npm i -g talking-stick` | Published as `0.1.0-alpha.2`. Requires Node ≥ 22. |
 | **From GitHub** | `npm i -g github:mostlydev/talking-stick` | Tracks the `master` branch; builds on install via the `prepare` hook. |
 | **From source** | `git clone … && npm install && npm link` | For contributors. |
 
@@ -49,6 +49,8 @@ tt install claude-code codex
 tt install-skill gemini
 ```
 
+During normal execution, install commands skip harnesses that are not present instead of failing or creating new harness config roots. For example, `tt install-skill codex` only creates `~/.codex/skills/` if `~/.codex/` already exists.
+
 ### Remove
 
 ```bash
@@ -70,6 +72,8 @@ pass_stick         — explicit handoff to a named agent
 takeover_stick     — deliberate claim when the prior holder is gone/stuck
 get_room_state     — authoritative state projection
 get_room_events    — audit log of turn transitions
+add_note           — leave an async observation for the current owner
+list_notes         — read notes left for the room
 ```
 
 A workspace maps to a room — usually the `git` root or nearest project marker — so two agents `cd`'d anywhere under the same repo join the same room automatically.
@@ -79,6 +83,14 @@ The skill complements the MCP tools:
 - MCP gives the harness the coordination surface
 - the global skill tells the model when to join, wait, heartbeat, take over, and hand off
 
+## Non-owner notes
+
+While you wait your turn you may still need to flag something to the current owner: a subtle invariant, a related bug, a pointer to a doc. Non-owner notes give you a durable channel without interrupting the turn.
+
+- Any joined member (owner or not) can `add_note` with a short plain-text body (≤ 16 KB). An optional `turn_id` scopes the note to a specific turn; omitted, the note is room-scoped and survives turn transitions.
+- `list_notes` returns notes for the room; readers can paginate with `after_note_id` and opt into resolved entries with `include_resolved`.
+- Notes are for observations and pointers, not for coordinating shared edits. Shared workspace changes still require holding the stick.
+
 ## How installation works per harness
 
 `tt install` prefers each harness's own `mcp add` subcommand when available (so the server ends up in the right user-global config with the right schema), and falls back to direct JSON editing when it isn't.
@@ -110,6 +122,7 @@ By default, `tt install-skill` links the bundled skill into each harness so loca
 The same `tt` binary also works as a human CLI, useful for watching or participating in a room from your terminal:
 
 ```text
+tt whoami [--explain]                                      # show the resolved CLI identity
 tt list [path]                                            # list rooms
 tt join [path] [--force-new]                              # join the room for path
 tt wait [path] [--timeout 30s]                            # block until your turn
@@ -119,6 +132,8 @@ tt events [path] [--after N] [--limit N]                  # room event log
 tt release [path] --status TEXT --next-action TEXT        # normal handoff
 tt pass [target] [path] --status TEXT --next-action TEXT  # explicit handoff
 tt takeover [path] --reason TEXT                          # deliberate takeover
+tt notes add <body> [--turn N] [--path DIR] [--stdin]     # leave an async note
+tt notes list [--all] [--after ID] [--limit N] [--path DIR] # read notes
 tt mcp                                                    # run the MCP stdio server
 tt install <harness...> | --all [--print]                 # register MCP server
 tt uninstall <harness...> | --all [--print]               # remove MCP server
@@ -128,6 +143,19 @@ tt uninstall-skill <harness...> | --all [--print]         # remove global talkin
 
 Human CLI commands use a stable identity like `human:<username>`. When `tt wait` or `tt takeover` wins the turn, a small background guardian keeps the lease alive on your behalf until you release or pass it.
 
+### CLI identity
+
+By default, `tt` behaves like a human CLI and resolves to `human:<username>`, even when you run it from a shell embedded inside Claude Code, Codex, Gemini, or OpenCode.
+
+Harness-aware CLI identity is now explicit:
+
+- Set `TT_HARNESS_EXPORT=1` if you want `tt` to derive a harness-style identity from the current environment and process ancestry.
+- Set `TT_HARNESS_AGENT_ID=<agent-id>` if the harness wants to export the exact agent id directly.
+
+If neither variable is set, `tt` stays on the human CLI path. That keeps ordinary shell usage predictable and avoids silently turning a human terminal into a harness participant.
+
+Use `tt whoami --explain` to see which identity path the CLI chose.
+
 ## Design highlights
 
 - **Workspace-root room resolution.** An agent at any depth under `/repo/` joins the `/repo/` room automatically. Nested rooms require explicit `force_new`.
@@ -155,10 +183,15 @@ npm run typecheck
 npm run build
 ```
 
+## Changelog
+
+See [`CHANGELOG.md`](CHANGELOG.md) for a per-version summary; full release notes live in [`docs/releases/`](docs/releases/).
+
 ## Read next
 
 - [`docs/talking-stick-plan.md`](docs/talking-stick-plan.md) — full protocol, state transitions, persistence model, design rationale, and open questions.
 - [`docs/ambient-presence.md`](docs/ambient-presence.md) — design sketch for shell-prompt awareness, event streaming, and agent skills that make room state ambient rather than appointment-only.
+- [`docs/non-owner-notes.md`](docs/non-owner-notes.md) — design backing the v1 notes feature; documents what shipped, what was deferred (`resolve_note`, wait_for_turn unread hints), and the rationale.
 - [`skills/talking-stick/SKILL.md`](skills/talking-stick/SKILL.md) — the portable skill installed into global harness skill directories.
 
 ## License