fellow-agents 0.0.19 → 0.0.22

package/README.md

@@ -12,6 +12,20 @@ fellow-agents
 
 That's it. Creates a workspace, downloads what it needs, opens your browser — three agents ready to collaborate.
 
+## What you get
+
+![fellow-agents in action — multiple AI sessions talking to each other in one browser tab](https://raw.githubusercontent.com/rajan-chari/fellow-agents/main/docs/screenshot.png)
+
+A team of AI agents working together in one browser. Each session is an autonomous agent — they message each other, coordinate on tasks, and track shared work. All running locally, all visible at once.
+
+- **(1) CLI sessions are agents.** Each one has its own identity, system prompt, and workspace.
+- **(2) Bring your own AI.** Claude Code, GitHub Copilot CLI, pi, or any compatible CLI — mix and match per agent.
+- **(3) Agents talk to each other.** Built-in async messaging (emcom) lets agents hand off tasks, request reviews, escalate questions — no shared context window, no token limits.
+- **(4) Run one or many per tab.** Group agents by team or project. Switch between tabs like browser tabs.
+- **(5) Built-in work tracker.** Every agent sees the same queue. File items, assign work, track status across sessions.
+
+If you've ever wished Claude could send a sub-task to another instance and get an answer back while you keep working — this is that.
+
 ---
 
 ## What happens when you run it

package/dist/cli.js

@@ -4,8 +4,9 @@ const args = process.argv.slice(2);
 const command = args[0] === "stop" ? "stop"
     : args[0] === "clean" ? "clean"
         : args[0] === "uninstall" ? "uninstall"
-            : (args[0] === "--help" || args[0] === "-h") ? "help"
-                : "start";
+            : args[0] === "config" ? "config"
+                : (args[0] === "--help" || args[0] === "-h") ? "help"
+                    : "start";
 function getFlag(name, fallback) {
     const idx = args.indexOf(name);
     return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
@@ -38,23 +39,44 @@ else if (command === "uninstall") {
         yes: hasFlag("--yes"),
     });
 }
+else if (command === "config") {
+    const { config } = await import("./commands/config.js");
+    config(args.slice(1));
+}
 else {
-    console.log(`fellow-agents — multi-agent system for Claude Code
+    console.log(`fellow-agents — multi-agent system for Claude Code, Copilot CLI, and pi
+
+  Multiple AI sessions on one machine, collaborating via email-style
+  messaging (emcom). Type fellow-agents to download binaries, scaffold
+  three sample agents (coder, coordinator, reviewer), and open the
+  browser UI. Each agent runs in its own pty-win pane.
 
-Usage:
-  fellow-agents [options]            Start services (default)
-  fellow-agents stop                 Stop all running services
-  fellow-agents clean                Wipe cached binaries + pty-win, preserve logs
-  fellow-agents uninstall [--yes]    Remove all fellow-agents state (data dir + workspaces)
+Commands:
+  fellow-agents [options]            Start services (the usual command)
+  fellow-agents stop                 Stop running services
+  fellow-agents clean                Wipe cached binaries + pty-win install (preserves logs and preferences)
+  fellow-agents uninstall [--yes]    Remove all state, including scaffolded workspaces
+  fellow-agents config <get|set>     Read or write user preferences (see 'config --help')
 
-Options:
+Start options:
   --port <number>       pty-win port (default: 3700)
   --emcom-port <number> emcom-server port (default: 8800)
-  --dir <path>          Working directory (default: current)
-  --no-browser          Don't open browser
-  --update              Force re-download binaries
-  --yes                 Skip confirmation prompt (uninstall only)
+  --dir <path>          Working directory for agent workspaces (default: current)
+  --no-browser          Don't open browser after services start
+  --update              Force re-download platform binaries
+
+Uninstall options:
+  --yes                 Actually perform the uninstall (default is dry-run preview)
+  --dir <path>          Workspace location (default: current — use if you ran start elsewhere)
+
+Config:
+  fellow-agents config get [key]            Print all preferences, or one value
+  fellow-agents config set <key> <value>    Write a preference (e.g. cliPreference claude)
+
+General:
+  -h, --help            Show this help
 
-  -h, --help            Show this help`);
+First time? Just run \`fellow-agents\` and follow the prompts.
+Docs: https://github.com/rajan-chari/fellow-agents`);
 }
 export {};

package/dist/commands/clean.js

@@ -67,6 +67,7 @@ export function clean() {
     console.log("");
     console.log(`  Cleaned ${formatBytes(totalFreed)} from ${dataDir}`);
     console.log(`  Logs preserved at ${join(dataDir, "logs")}`);
+    console.log(`  Preferences preserved at ${join(dataDir, "preferences.json")} (if set)`);
     console.log(`  Run 'fellow-agents' to reinstall.`);
     console.log("");
 }

package/dist/commands/config.js

@@ -0,0 +1,109 @@
+import { readPreferences, writePreferences, lookupCli, preferencesFile, KNOWN_KEYS, } from "../lib/preferences.js";
+function printHelp() {
+    console.log(`fellow-agents config — read or write user preferences
+
+Usage:
+  fellow-agents config get                Print all preferences as JSON
+  fellow-agents config get <key>          Print the value of a single key
+  fellow-agents config set <key> <value>  Write a value (creates the file if missing)
+
+Known keys:
+  cliPreference   The CLI launched by pty-win's play button.
+                  Bare command (claude | copilot | pi) or full path to an executable.
+
+File: ${preferencesFile}
+
+Examples:
+  fellow-agents config set cliPreference claude
+  fellow-agents config set cliPreference "C:\\Program Files\\claude\\claude.exe"
+  fellow-agents config get cliPreference`);
+}
+function isKnownKey(key) {
+    return KNOWN_KEYS.includes(key);
+}
+export function config(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printHelp();
+        return;
+    }
+    const sub = args[0];
+    if (sub === "get") {
+        handleGet(args.slice(1));
+        return;
+    }
+    if (sub === "set") {
+        handleSet(args.slice(1));
+        return;
+    }
+    console.error(`Unknown config subcommand: ${sub}`);
+    console.error(`Run 'fellow-agents config --help' for usage.`);
+    process.exit(1);
+}
+function handleGet(args) {
+    const prefs = readPreferences();
+    if (args.length === 0) {
+        if (prefs === null) {
+            console.log("No preferences set.");
+            console.log(`Run 'fellow-agents' or 'fellow-agents config set <key> <value>' to create them.`);
+            return;
+        }
+        console.log(JSON.stringify(prefs, null, 2));
+        return;
+    }
+    const key = args[0];
+    if (!isKnownKey(key)) {
+        console.error(`Unknown key: ${key}`);
+        console.error(`Known keys: ${KNOWN_KEYS.join(", ")}`);
+        process.exit(1);
+    }
+    if (prefs === null) {
+        console.log("No preferences set.");
+        console.log(`Run 'fellow-agents' or 'fellow-agents config set ${key} <value>' to set it.`);
+        return;
+    }
+    const value = prefs[key];
+    if (value === undefined || value === null || value === "") {
+        console.log(`${key} is not set.`);
+        return;
+    }
+    console.log(String(value));
+}
+function handleSet(args) {
+    if (args.length < 2) {
+        console.error("Usage: fellow-agents config set <key> <value>");
+        console.error(`Known keys: ${KNOWN_KEYS.join(", ")}`);
+        process.exit(1);
+    }
+    const key = args[0];
+    const value = args.slice(1).join(" ");
+    if (!isKnownKey(key)) {
+        console.error(`Unknown key: ${key}`);
+        console.error(`Known keys: ${KNOWN_KEYS.join(", ")}`);
+        process.exit(1);
+    }
+    if (!value.trim()) {
+        console.error(`Value for '${key}' cannot be empty.`);
+        process.exit(1);
+    }
+    // cliPreference: warn (don't fail) if where.exe / which doesn't find it.
+    // Real use case: user pre-configures before installing the CLI, or the CLI
+    // is in a non-default location PATH doesn't see yet. Reject would block valid flows.
+    if (key === "cliPreference") {
+        const looksLikePath = value.includes("\\") || value.includes("/");
+        const resolved = lookupCli(value);
+        if (resolved === null && !looksLikePath) {
+            const tool = process.platform === "win32" ? "where.exe" : "which";
+            console.error(`  WARNING: '${tool} ${value}' returned no matches.`);
+            console.error(`  Writing the preference anyway — pty-win will fall back if the CLI is missing at launch time.`);
+            console.error(`  Fix later with: fellow-agents config set cliPreference <name-or-path>`);
+        }
+    }
+    const existing = readPreferences();
+    const written = writePreferences({
+        ...(existing ?? {}),
+        [key]: value,
+        updatedBy: "config-set",
+    });
+    console.log(`Set ${key} = ${value}`);
+    console.log(`Wrote ${preferencesFile} (schema ${written.schema}, updatedAt ${written.updatedAt}).`);
+}

package/dist/commands/start.js

@@ -1,13 +1,16 @@
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from "fs";
 import http from "http";
 import { join, resolve } from "path";
 import { execSync } from "child_process";
-import { binDir, ptyWinDir, logsDir } from "../lib/paths.js";
+import * as readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { binDir, ptyWinDir, logsDir, dataDir } from "../lib/paths.js";
 import { downloadBinaries } from "../lib/download.js";
 import { startEmcomServer, startPtyWin, stopAll, logPath } from "../lib/services.js";
 import { scaffoldWorkspaces, registerAgents, writeHooks } from "../lib/workspaces.js";
 import { installSkills } from "../lib/skills.js";
 import { binarySuffix } from "../lib/platform.js";
+import { readPreferences, writePreferences, autoDetectClis, lookupCli, } from "../lib/preferences.js";
 // Minimal engines.node range check — handles ">=N", "<N", and combinations.
 function nodeInRange(version, range) {
     const major = parseInt(version.split(".")[0], 10);
@@ -17,11 +20,129 @@ function nodeInRange(version, range) {
     const max = maxMatch ? parseInt(maxMatch[1], 10) : Infinity;
     return major >= min && major < max;
 }
+/**
+ * First-run CLI preference prompt. Returns the chosen value (bare command or full path),
+ * or null if we should skip (non-interactive, or user declined).
+ *
+ * Design (locked 5/27 with milo):
+ * - Native readline (no inquirer dep — start.ts is a setup pipeline, not a chat UI)
+ * - Auto-detected CLIs from PATH shown as numbered choices, plus a "Custom path" option
+ * - If user types a custom value not on PATH, single confirm: "Use it anyway? [y/N]"
+ * - Non-interactive stdin (CI, piped) → return null, caller logs a hint
+ */
+async function promptForCliPreference() {
+    if (!input.isTTY)
+        return null;
+    const detected = autoDetectClis();
+    const rl = readline.createInterface({ input, output });
+    try {
+        console.log("");
+        console.log("  Pick your preferred CLI — pty-win's play button will launch this in each new tab.");
+        console.log("  (You can change it later with 'fellow-agents config set cliPreference <name>'.)");
+        console.log("");
+        const choices = [...detected];
+        if (detected.length > 0) {
+            for (let i = 0; i < detected.length; i++) {
+                console.log(`    [${i + 1}] ${detected[i]}`);
+            }
+        }
+        else {
+            console.log("    (None of claude/copilot/pi found on PATH — pick Custom path to specify your own)");
+        }
+        const customIdx = choices.length + 1;
+        console.log(`    [${customIdx}] Custom path or other command`);
+        console.log(`    [s] Skip for now`);
+        console.log("");
+        const answer = (await rl.question("  Choice: ")).trim().toLowerCase();
+        if (answer === "s" || answer === "skip" || answer === "") {
+            console.log("  Skipped — pty-win will pick a default until you set one.");
+            return null;
+        }
+        const num = parseInt(answer, 10);
+        if (!isNaN(num) && num >= 1 && num <= detected.length) {
+            return detected[num - 1];
+        }
+        if (!isNaN(num) && num === customIdx) {
+            const value = (await rl.question("  Enter command or full path: ")).trim();
+            if (!value) {
+                console.log("  Empty input — skipped.");
+                return null;
+            }
+            // Confirm step if value doesn't resolve and doesn't look like a path
+            const looksLikePath = value.includes("\\") || value.includes("/");
+            const resolved = lookupCli(value);
+            if (resolved === null && !looksLikePath) {
+                const tool = process.platform === "win32" ? "where.exe" : "which";
+                console.log(`  '${tool} ${value}' returned no matches.`);
+                const confirm = (await rl.question("  Use it anyway? [y/N]: ")).trim().toLowerCase();
+                if (confirm !== "y" && confirm !== "yes") {
+                    console.log("  Skipped.");
+                    return null;
+                }
+            }
+            return value;
+        }
+        console.log(`  Unrecognised choice '${answer}' — skipped.`);
+        return null;
+    }
+    finally {
+        rl.close();
+    }
+}
 export async function start(opts) {
     console.log("");
     console.log("  fellow-agents");
     console.log("  =============");
     console.log("");
+    // First-run welcome — show a brief orientation the very first time someone
+    // types `fellow-agents`. Marker lives in dataDir so it survives across
+    // sessions but resets if the user runs `fellow-agents uninstall`.
+    const firstRunMarker = join(dataDir, ".first-run");
+    if (!existsSync(firstRunMarker)) {
+        console.log("  Welcome! This is your first run. Here's what's about to happen:");
+        console.log("");
+        console.log("    [1] Download platform binaries (emcom, tracker, emcom-server)");
+        console.log("    [2] Install pty-win (the browser-based terminal multiplexer)");
+        console.log("    [3] Scaffold three agent workspaces (coder, coordinator, reviewer)");
+        console.log("    [4] Install agent skills into ~/.claude/, ~/.copilot/, ~/.agents/");
+        console.log("    [5] Start emcom-server and pty-win, open the browser UI");
+        console.log("");
+        console.log("  Press Ctrl+C any time to stop. `fellow-agents --help` shows options.");
+        console.log("");
+        try {
+            mkdirSync(dataDir, { recursive: true });
+            writeFileSync(firstRunMarker, new Date().toISOString());
+        }
+        catch { }
+    }
+    // CLI preference prompt — fires when preferences.json is missing or has no cliPreference.
+    // Independent of the first-run marker so a user who wipes preferences.json (or upgrades from
+    // a pre-0.0.22 install) gets prompted on the next run. Non-interactive sessions skip silently.
+    const existingPrefs = readPreferences();
+    if (existingPrefs === null || !existingPrefs.cliPreference) {
+        const chosen = await promptForCliPreference();
+        if (chosen) {
+            try {
+                writePreferences({
+                    ...(existingPrefs ?? {}),
+                    cliPreference: chosen,
+                    updatedBy: "first-run-prompt",
+                });
+                console.log(`  CLI preference set: ${chosen}`);
+                console.log("");
+            }
+            catch (err) {
+                console.error(`  Failed to write preferences: ${err.message}`);
+                console.error(`  Continuing without a stored preference.`);
+                console.log("");
+            }
+        }
+        else if (!input.isTTY) {
+            console.log("  (non-interactive — skipping CLI preference setup)");
+            console.log(`  Set later with: fellow-agents config set cliPreference <name-or-path>`);
+            console.log("");
+        }
+    }
     // Auto-create fellow-agents/ subdirectory if CWD doesn't already have workspaces/
     let workDir = resolve(opts.dir);
     if (!existsSync(join(workDir, "workspaces"))) {

package/dist/lib/preferences.js

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, unlinkSync } from "fs";
+import { join } from "path";
+import { execSync } from "child_process";
+import { dataDir } from "./paths.js";
+/** ~/.fellow-agents/preferences.json */
+export const preferencesFile = join(dataDir, "preferences.json");
+export const CURRENT_SCHEMA = 1;
+/** Known CLI names — used by autoDetectClis() and as the default preset list for first-run prompt. */
+export const KNOWN_CLIS = ["claude", "copilot", "pi"];
+/** Known preference keys (for config get/set validation + --help listing). */
+export const KNOWN_KEYS = ["cliPreference"];
+export const KEY_SCHEMAS = {
+    cliPreference: {
+        type: "select",
+        label: "Default CLI",
+        description: "The CLI launched by pty-win's play button in each new tab.",
+        options: [...KNOWN_CLIS],
+        allowCustom: true,
+        customLabel: "Custom path…",
+    },
+};
+/**
+ * Read preferences from disk.
+ * Returns null if file is missing.
+ * Returns { schema: CURRENT_SCHEMA } with a warning on the console if file exists but is malformed —
+ * caller can decide whether to re-prompt.
+ */
+export function readPreferences() {
+    if (!existsSync(preferencesFile))
+        return null;
+    try {
+        const raw = readFileSync(preferencesFile, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null)
+            throw new Error("not an object");
+        if (typeof parsed.schema !== "number")
+            throw new Error("missing schema");
+        return parsed;
+    }
+    catch (err) {
+        console.error(`  WARNING: ${preferencesFile} is malformed (${err.message}). Treating as unset.`);
+        return null;
+    }
+}
+/**
+ * Write preferences atomically (temp + renameSync — atomic on Windows from Node 10+).
+ * Always stamps `updatedAt` to now and `updatedBy` to the supplied value.
+ * Ensures dataDir exists. Cleans up the temp file on failure.
+ */
+export function writePreferences(prefs) {
+    mkdirSync(dataDir, { recursive: true });
+    const next = {
+        schema: prefs.schema ?? CURRENT_SCHEMA,
+        cliPreference: prefs.cliPreference,
+        updatedAt: new Date().toISOString(),
+        updatedBy: prefs.updatedBy,
+    };
+    const tmp = `${preferencesFile}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(next, null, 2) + "\n", "utf-8");
+        renameSync(tmp, preferencesFile);
+    }
+    catch (err) {
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch { }
+        throw err;
+    }
+    return next;
+}
+/**
+ * Look up a CLI on PATH. Returns the resolved full path (first hit), or null if not found.
+ * Uses `where.exe` on Windows and `which -a` on Unix. Never throws.
+ */
+export function lookupCli(name) {
+    const cmd = process.platform === "win32" ? `where.exe ${name}` : `which ${name}`;
+    try {
+        const out = execSync(cmd, { stdio: ["ignore", "pipe", "ignore"] })
+            .toString()
+            .split(/\r?\n/)
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return out.length > 0 ? out[0] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Auto-detect which of the KNOWN_CLIS are on PATH.
+ * Returns the subset that resolved, preserving the KNOWN_CLIS priority order.
+ */
+export function autoDetectClis() {
+    return KNOWN_CLIS.filter((name) => lookupCli(name) !== null);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fellow-agents",
-  "version": "0.0.19",
+  "version": "0.0.22",
   "description": "Multi-agent system — multiple Claude Code instances collaborating via messaging",
   "type": "module",
   "bin": {
@@ -18,7 +18,8 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "node -e \"process.env.npm_config_global && console.log('\\nfellow-agents installed. Run \\\"fellow-agents\\\" to start, or \\\"fellow-agents --help\\\" for options.\\n')\""
   },
   "engines": {
     "node": ">=18"

package/skills/tracker/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: tracker
+description: |
+  Use this skill when the user wants to interact with the team task tracker,
+  or when the agent itself needs to view its own work queue or file/update
+  tracker items.
+  Triggers: check queue, my work, what's next, file a tracker item,
+  open issue, update status, mark merged, close item, decisions pending,
+  blocked items, stale items, list bugs, list PRs, work item history,
+  link items, or arrival of an emcom auto-inject prompt that references
+  tracker work.
+tools:
+  - Bash
+  - Read
+  - Write
+---
+
+# tracker Skill
+
+The team **tracker** is a cross-session, cross-agent record of in-flight work: bugs, PRs, investigations, and decisions. It is the source of truth for "what work is open right now" — distinct from briefing.md (per-session narrative) and field-notes.md (persistent gotchas).
+
+A tracker item exists when work spans sessions or involves more than one agent. A briefing entry covers what your current self did. A field-note captures a one-shot gotcha you want to remember forever. If you can't answer "is this still in flight" or "who's working on this" by reading just your briefing, the work belongs in tracker.
+
+## Mental model
+
+- **Items** have status, severity, labels, and assignment.
+- **Queue** is your slice — `tracker queue` shows items assigned to you, or referenced in ways you should act on.
+- **Statuses** drive workflow — items move through a defined lifecycle (see below). The status field is **strictly validated**: generic terms (`in_progress`, `done`, `completed`) are rejected. Use the canonical set.
+- **History** is append-only — every status change, decision, and comment is preserved.
+
+## When to file a tracker item
+
+File a tracker item when ANY of:
+- The work is likely to span more than one session.
+- More than one agent will touch it.
+- It needs an owner and a status that other agents will check.
+- It's a decision that future-you should be able to find via `tracker decisions`.
+
+Don't file when:
+- You're capturing a personal note → use briefing.md or field-notes.md.
+- The work completes in this session → just do it and log in briefing.
+- It's a coding gotcha you want to remember → field-notes.md.
+
+When in doubt, file. Tracker entries are cheap; missed coordination is expensive.
+
+## Daily flow
+
+```
+tracker queue                          # what's assigned to me
+tracker view <id>                      # full details + history
+tracker update <id> --status <next>    # advance the workflow
+tracker comment <id> "<note>"          # add context without status change
+```
+
+Reference forms (all accepted):
+- UUID prefix (first 8 hex chars work for `view`/`update`)
+- `repo#number` (e.g. `banana#42`)
+- Bare number when there's no ambiguity
+
+## Status lifecycle
+
+The canonical 11 statuses, in typical workflow order:
+
+| Status | Meaning |
+|--------|---------|
+| `new` | Just filed; no triage yet |
+| `triaged` | Reviewed, has owner + severity, waiting to start |
+| `investigating` | Actively working on understanding the problem |
+| `findings-reported` | Investigation done, findings documented in --notes |
+| `decision-pending` | Needs a call from Rajan or another agent before proceeding |
+| `pr-up` | Code change opened as a PR, awaiting review |
+| `testing` | PR merged or staged, validating in real env |
+| `ready-to-merge` | Reviewed + approved, awaiting merge |
+| `merged` | Code is in the target branch |
+| `deferred` | Real item, intentionally postponed (`--blocker` should explain) |
+| `closed` | Resolved, no further action |
+
+**Critical gotcha**: generic terms like `in_progress`, `done`, `completed`, `wip`, `fixed` are **rejected** by `tracker update --status`. If you mean "actively working on it" use `investigating`. If you mean "code is in" use `merged`. If you mean "fully done" use `closed`.
+
+`tracker list --status open` shows everything non-closed (anything except `merged`, `deferred`, `closed`).
+
+## Filing a new item
+
+```bash
+tracker create --repo banana \
+  --title "verify-window too tight for Copilot hooks" \
+  --type investigation \
+  --severity normal \
+  --assigned milo \
+  --opened-by Rajan \
+  --notes "Copilot's PowerShell hook stack takes ~200ms × 3 steps. Current 5s verify often expires."
+```
+
+Required: `--repo`, `--title`. Type defaults to `issue`; alternatives are `pr`, `investigation`, `decision`. Severity defaults to `normal`; alternatives `low`, `high`, `critical`. Status defaults to `new`.
+
+`--opened-by` is the person/agent who originally reported the issue (distinct from `--assigned`, which is who works it). Useful when an emcom thread or external party flagged something and you're filing on their behalf.
+
+## Updating an item
+
+```bash
+tracker update banana#42 --status investigating --assigned milo --append-notes "Started looking at session.ts verify path."
+tracker update <id> --findings "Root cause: ..." --status findings-reported
+tracker update <id> --decision "Bump VERIFY_WINDOW_MS to 8s for Copilot only" --decision-rationale "..." --status decision-pending
+tracker update <id> --status pr-up --pr 142
+```
+
+Notes vs append-notes:
+- `--notes <text>` **replaces** the entire notes field.
+- `--append-notes <text>` **appends** a timestamped entry. Prefer this.
+
+If something is blocking progress: `--status deferred --blocker "Waiting on upstream node-pty Node 26 prebuilts"`.
+
+## Comments vs notes
+
+- `--append-notes` lives on the item, shown in `view`. Use for substantive findings, status reasoning, links to PRs.
+- `tracker comment <id> "<text>"` adds a separate comment record (also shown in history). Use for lightweight chatter that doesn't change the item's state.
+
+## Linking items
+
+```bash
+tracker link <id1> <id2> --type related        # default
+tracker link <id1> <id2> --type blocks         # id1 blocks id2
+tracker link <id1> <id2> --type blocked-by     # id1 blocked by id2
+tracker link <id1> <id2> --type duplicate      # id1 duplicates id2
+```
+
+Use links instead of restating context across items. Especially `blocks` / `blocked-by` for chains where one decision unblocks several follow-ups.
+
+## Useful queries
+
+| Need | Command |
+|------|---------|
+| My open items | `tracker queue` |
+| Another agent's queue | `tracker queue <agent-name>` |
+| Everything not closed | `tracker list --status open` |
+| Items needing decision | `tracker list --needs-decision` (alias for `--status decision-pending`) |
+| Blocked items | `tracker blocked` |
+| Stale items (>24h no update) | `tracker stale` or `tracker stale --hours 48` |
+| Decisions made | `tracker decisions` |
+| Find by text | `tracker search "<query>"` |
+| Item history | `tracker history <id>` |
+| Team activity | `tracker report --period 7d` |
+| Per-person breakdown | `tracker report people` |
+| SLA on open items | `tracker report sla` |
+| GitHub-linked activity | `tracker github --period 7d` |
+| Summary counts | `tracker stats` |
+
+## Labels and severity
+
+- Labels are freeform comma-separated tags. Use sparingly and consistently — `tracker list --label <name>` finds items by label. Conventional labels: `regression`, `flake`, `infra`, `docs`, `breaking-change`.
+- Severity: `low` / `normal` / `high` / `critical`. Default normal. Use `critical` only for production-impacting or blocking-the-team issues.
+
+## Permission-friendly invocation
+
+(Matters in CLIs that gate command execution.)
+
+- **One command per Bash call.** Do NOT chain with `&&`, `;`, or `||`.
+- Do NOT assign the binary path to a variable. Use the bare command.
+- **Independent** queries (e.g. `queue` + `blocked` + `stale`): parallel Bash calls.
+- **Sequential** updates (e.g. create then assign): separate sequential calls.
+
+## Error recovery
+
+**Auth error** ("Missing X-Tracker-Name header"): identical pattern to emcom — register via the team's identity flow. In most workspaces, the `identity.json` registered for emcom also identifies you to tracker, so the fix is usually `cd` to a workspace where you have an identity, not re-registering.
+
+**Connection error** ("Connection refused"): the tracker shares a server with emcom on port 8800. Start it:
+```bash
+emcom-server &
+sleep 2
+```
+Then retry the tracker command.
+
+**Validation error on status**: you used a generic term. Map to the canonical 11:
+- `in_progress`, `working`, `wip` → `investigating`
+- `done`, `fixed`, `complete` → either `merged` (code is in) or `closed` (resolved)
+- `waiting`, `pending` → either `decision-pending` (waiting on decision) or `deferred` (intentionally postponed)
+- `review` → `pr-up` (PR open) or `ready-to-merge` (approved, awaiting merge)
+
+**Missing repo on create**: `--repo` is required. Use the short name from the user's workspace (e.g. `banana`, `fellow-agents`, `pty-cld`).
+
+## Running commands
+
+```bash
+tracker <subcommand> [args]
+```
+
+`tracker` is on PATH when fellow-agents has been installed (`npm install -g fellow-agents`) — the npm shim wraps `~/.fellow-agents/bin/<platform>/tracker`. Use the bare command. Do not prepend any skills-directory path.
+
+If a CLI environment can't find `tracker` on PATH, that means fellow-agents isn't installed (or its bin shim isn't picked up by the shell). Tell the user to run `npm install -g fellow-agents` rather than guessing at a skill-bundled path — fellow-agents does not ship binaries inside `~/.claude/skills/`, `~/.copilot/skills/`, or `~/.agents/skills/`.
+
+## Output
+
+Tracker output is structured — tables for lists, key/value blocks for `view`, chronological lists for `history`. Present output as-returned; don't reformat. For one item view, show the full structure. For lists, show as-is (already paginated/abbreviated by tracker itself).
+
+## Notes
+
+- Item IDs are UUIDs; first 8 hex chars work as prefix everywhere.
+- Server: port 8800 (shared with emcom), data in `~/.emcom/` alongside emcom state.
+- Always use `127.0.0.1` rather than `localhost` (avoids IPv6 DNS resolution penalty on Windows).
+- `tracker history` shows every state change with timestamp and the agent that made it — useful for "who decided what when".
+- Backtick-containing notes via `--notes "..."` get shell-expanded — single-quote when the body contains backticks or `$`.