@aiaiai-pt/manda-cli 0.1.2 → 0.3.0

package/README.md

@@ -10,6 +10,17 @@ npm i -g @aiaiai-pt/manda-cli
 
 Requires Node.js 22 or later.
 
+## Give it to an agent
+
+The CLI ships its own skill, the operational reference a coding agent reads instead of `--help`:
+
+```sh
+mkdir -p ~/.claude/skills/manda-cli && npx -y @aiaiai-pt/manda-cli@latest skill > ~/.claude/skills/manda-cli/SKILL.md   # Claude Code
+mkdir -p ~/.agents/skills/manda-cli && npx -y @aiaiai-pt/manda-cli@latest skill > ~/.agents/skills/manda-cli/SKILL.md   # Codex
+```
+
+`manda instructions` prints a shorter block for a CLAUDE.md or AGENTS.md. Neither needs credentials.
+
 ## Auth
 
 Set environment variables (preferred for agents):
@@ -36,7 +47,9 @@ Credentials are saved to `${XDG_CONFIG_HOME:-~/.config}/manda/config.json` with
 | `manda projects` | List projects |
 | `manda inbox [filters]` | List submissions |
 | `manda next [--project <id>]` | What to work on next: open reports you own or nobody owns, owned first, new first, then linked-topic roadmap order |
+| `manda skill` | Print the agent skill (`skills/manda-cli/SKILL.md`), the full reference for a harness |
 | `manda instructions` | Print a block for CLAUDE.md or AGENTS.md describing the loop and commit trailers |
+| `manda watch [--since <cursor>] [--project <id>] [--interval <s>] [--once]` | Print changes as they land, one JSON object per line when piped: reports, report updates (customer replies carry `author_kind: customer`), topic updates, announcements. Starts from now without `--since`; `--once` polls one time and ends with a `cursor` line to resume from. The cursor is opaque; a bare `YYYY-MM-DD HH:MM:SS` (UTC) is also accepted as a starting point |
 | `manda report show <id>` | Show a report |
 | `manda report capture --project <id> --type bug\|feature\|other --message <text> [--name] [--email] [--source-label]` | Create a report |
 | `manda report assign <id> --to <email\|me\|none>` | Assign a report |
@@ -108,3 +121,11 @@ topic=$(manda topic create --project proj-1 --title "Widget focus trap" --json |
 manda topic link-report "$topic" --report "$id"
 manda topic transition "$topic" plan
 ```
+
+# Wake on changes (one JSON line per event; a customer reply on a resolved report reopens it)
+manda watch --since "$cursor" | while read -r event; do
+  if [ "$(jq -r .author_kind <<<"$event")" = customer ]; then
+    manda report reopen "$(jq -r .report_id <<<"$event")"
+  fi
+done
+```

package/dist/bin.js

@@ -3,48 +3,9 @@ import { parseArgs } from "node:util";
 import { resolveConfig, saveConfigFile } from "./config.js";
 import { api, exitCodeForStatus } from "./client.js";
 import { printError, printJson, printKeyValue, isJsonMode } from "./output.js";
-import { whoami, projects, inbox, next, instructions, reportShow, reportCapture, reportAssign, reportAck, reportResolve, reportReopen, reportLink, reportComment, topicList, topicShow, topicCreate, topicTransition, topicNote, topicEdit, topicLinkReport, topicUnlinkReport, topicLinkWork, topicUnlinkWork, topicPublish, topicUnpublish, topicEditPublic, topicReorder, topicAnnounce, topicUnannounce, } from "./commands.js";
-const USAGE = `Usage: manda <command> [options]
-
-Commands:
-  whoami                         Show authenticated identity
-  projects                       List projects
-  inbox                          List submissions (inbox)
-  next                           What to work on next, in priority order (--project)
-  instructions                   Print a CLAUDE.md / AGENTS.md block for this loop
-  report show <id>               Show a report
-  report capture                 Create a new report
-  report assign <id>             Assign a report
-  report ack <id>                Acknowledge a report
-  report resolve <id>            Resolve a report
-  report reopen <id>             Reopen a report
-  report link <id>               Link external work to a report (--work-url)
-  report comment <id>            Add a comment to a report
-  topic list                     List topics
-  topic show <id>                Show a topic
-  topic create                   Create a topic
-  topic transition <id> <event>  Transition a topic
-  topic note <id>                Add a note to a topic
-  topic edit <id>                Edit a topic
-  topic link-report <id>         Link a report to a topic
-  topic unlink-report <id>       Unlink a report from a topic
-  topic link-work <id>           Link external work to a topic (--issue-url)
-  topic unlink-work <id>         Unlink external work from a topic
-  topic publish <id>             Publish a topic
-  topic unpublish <id>           Unpublish a topic
-  topic edit-public <id>         Edit a topic's public view
-  topic reorder                  Reorder topics
-  topic announce <id>            Add an announcement to a topic
-  topic unannounce <id>          Remove an announcement (--announcement <id>)
-  auth login                     Save credentials
-  auth status                    Show credential source and verify
-
-Global options:
-  --url <url>        Server URL (overrides env/config)
-  --token <token>    Agent token (overrides env/config)
-  --json             Force JSON output
-  --help             Show help
-`;
+import { USAGE } from "./usage.js";
+import { skill } from "./skill.js";
+import { whoami, projects, inbox, next, watch, instructions, reportShow, reportCapture, reportAssign, reportAck, reportResolve, reportReopen, reportLink, reportComment, topicList, topicShow, topicCreate, topicTransition, topicNote, topicEdit, topicLinkReport, topicUnlinkReport, topicLinkWork, topicUnlinkWork, topicPublish, topicUnpublish, topicEditPublic, topicReorder, topicAnnounce, topicUnannounce, } from "./commands.js";
 function usageError(message) {
     printError(0, message, 1);
     process.stderr.write(USAGE);
@@ -92,6 +53,10 @@ const parseOptions = {
         "public-title": { type: "string" },
         "public-summary": { type: "string" },
         announcement: { type: "string" },
+        // watch flags
+        since: { type: "string" },
+        interval: { type: "string" },
+        once: { type: "boolean", default: false },
     },
     // Strict: an unknown or misspelled flag is a usage error, never silently ignored.
     strict: true,
@@ -114,7 +79,11 @@ const subcommand = positionals[1];
 if (!command) {
     usageError("No command provided");
 }
-// instructions needs neither a server nor credentials
+// skill and instructions need neither a server nor credentials
+if (command === "skill") {
+    skill();
+    process.exit(0);
+}
 if (command === "instructions") {
     instructions();
     process.exit(0);
@@ -199,6 +168,9 @@ try {
         case "next":
             await next(config, flags);
             break;
+        case "watch":
+            await watch(config, flags);
+            break;
         case "report": {
             const reportId = positionals[2];
             switch (subcommand) {

package/dist/commands.d.ts

@@ -4,8 +4,31 @@ export declare function whoami(config: Config, flags: Flags): Promise<void>;
 export declare function projects(config: Config, flags: Flags): Promise<void>;
 export declare function inbox(config: Config, flags: Flags): Promise<void>;
 export declare function next(config: Config, flags: Flags): Promise<void>;
+export interface WatchEvent {
+    id: string;
+    at: string;
+    type: string;
+    kind: string;
+    project_id: string;
+    report_id: string | null;
+    topic_id: string | null;
+    author_email: string | null;
+    author_kind: string | null;
+    author_agent: string | null;
+    body: string;
+}
+/** Keeps the events not yet seen, in order, and remembers them. The feed is at-least-once
+ * at the cursor boundary, so the same id can arrive on consecutive polls. */
+export declare function unseenEvents(seen: Set<string>, events: WatchEvent[]): WatchEvent[];
+export declare function formatEvent(e: WatchEvent): string;
+/** `manda watch`: print each change as it lands, one JSON object per line when piped, so a
+ * harness can wake on stdout. Without --since it starts from now. --once polls one time and
+ * ends with a `cursor` line to resume from. The cursor is opaque to the client; a bare
+ * `YYYY-MM-DD HH:MM:SS` is also accepted as a starting point. Dedupe by id covers the
+ * inclusive boundary of that bare form. */
+export declare function watch(config: Config, flags: Flags): Promise<void>;
 /** A block for CLAUDE.md or AGENTS.md: the loop a harness runs with manda as its coordination layer. */
-export declare const INSTRUCTIONS = "## Manda: customer feedback and work coordination\n\nManda is the ledger of what customers reported and what they have been told. Use the `manda`\nCLI (`npm i -g @aiaiai-pt/manda-cli`, `MANDA_TOKEN` set) as the coordination layer while\nworking in this codebase, alone or with a person. Every call prints JSON when piped; exit codes:\n0 ok, 1 usage, 2 auth, 3 conflict (reload and decide again), 4 not found, 5 other.\n\nThe loop:\n\n1. `manda next --json` lists open reports you own or nobody owns, in priority order. Take the first.\n2. `manda report show <id> --json` reads the report and its timeline. `manda report assign <id> --to me` takes it\n   (owned reports rank first in `next`; an unowned one you are working on will sink below fresh reports), then\n   `manda report ack <id>` starts review.\n3. Group it: `manda topic list --json` to find the topic it belongs to, then\n   `manda topic link-report <topic> --report <id>`; or `manda topic create --project <project> --title \"<customer intent>\"`\n   and `manda topic transition <topic> plan` then `start` when you begin.\n4. Do the work in the repository. Put `Manda-Report: <id>` and `Manda-Topic: <topic>` as commit trailers\n   and `manda topic link-work <topic> --tracker github --issue <pr number> --issue-url <pr url>` once a PR exists.\n5. Tell the customer only when it is true, and \"true\" means you exercised their path, not the artefact:\n   load the page or call the entry point they use (the hosted script, the endpoint, the screen) on the\n   deployed version and watch it work. A green suite, a merged PR or a file read back are not that.\n   Then `manda report comment <id> --audience customer --outcome resolved --body \"<what changed, in their words>\"`.\n   Internal notes use `--audience internal`. Never resolve without a customer-facing explanation.\n6. `manda topic transition <topic> complete` when the change is available to customers; `manda topic announce <topic> --body \"<progress>\"` for public progress.\n\nRules: read before you write (every write checks the revision); do not reprioritise by editing reports, reorder topics\n(`manda topic reorder`) with the person who owns the roadmap; a 3 exit means someone else changed it, re-read and decide again.\n";
+export declare const INSTRUCTIONS = "## Manda: customer feedback and work coordination\n\nManda is the ledger of what customers reported and what they have been told. Use the `manda`\nCLI (`npm i -g @aiaiai-pt/manda-cli`, `MANDA_TOKEN` set) as the coordination layer while\nworking in this codebase, alone or with a person. Every call prints JSON when piped; exit codes:\n0 ok, 1 usage, 2 auth, 3 conflict (reload and decide again), 4 not found, 5 other.\n\nThe loop:\n\n1. `manda next --json` lists open reports you own or nobody owns, in priority order. Take the first.\n2. `manda report show <id> --json` reads the report and its timeline. `manda report assign <id> --to me` takes it\n   (owned reports rank first in `next`; an unowned one you are working on will sink below fresh reports), then\n   `manda report ack <id>` starts review.\n3. Group it: `manda topic list --json` to find the topic it belongs to, then\n   `manda topic link-report <topic> --report <id>`; or `manda topic create --project <project> --title \"<customer intent>\"`\n   and `manda topic transition <topic> plan` then `start` when you begin.\n4. Do the work in the repository. Put `Manda-Report: <id>` and `Manda-Topic: <topic>` as commit trailers\n   and `manda topic link-work <topic> --tracker github --issue <pr number> --issue-url <pr url>` once a PR exists.\n5. Tell the customer only when it is true, and \"true\" means you exercised their path, not the artefact:\n   load the page or call the entry point they use (the hosted script, the endpoint, the screen) on the\n   deployed version and watch it work. A green suite, a merged PR or a file read back are not that.\n   Then `manda report comment <id> --audience customer --outcome resolved --body \"<what changed, in their words>\"`.\n   Internal notes use `--audience internal`. Never resolve without a customer-facing explanation.\n6. `manda topic transition <topic> complete` when the change is available to customers; `manda topic announce <topic> --body \"<progress>\"` for public progress.\n7. Between tasks, `manda watch` prints one JSON line per change as it lands: new reports, customer replies\n   (`type` report_update with `author_kind` customer), topic changes. `manda watch --once` polls once and ends with\n   a `cursor` line; resume later with `manda watch --since <cursor>`. A customer reply on a report you resolved\n   means it is not done: `manda report reopen <id>` and go back to step 2.\n\nRules: read before you write (every write checks the revision); do not reprioritise by editing reports, reorder topics\n(`manda topic reorder`) with the person who owns the roadmap; a 3 exit means someone else changed it, re-read and decide again.\n";
 export declare function instructions(): void;
 export declare function reportShow(config: Config, id: string, flags: Flags): Promise<void>;
 export declare function reportCapture(config: Config, flags: Flags): Promise<void>;

package/dist/commands.js

@@ -163,6 +163,60 @@ export async function next(config, flags) {
         ]);
     }
 }
+/** Keeps the events not yet seen, in order, and remembers them. The feed is at-least-once
+ * at the cursor boundary, so the same id can arrive on consecutive polls. */
+export function unseenEvents(seen, events) {
+    const fresh = [];
+    for (const e of events) {
+        if (seen.has(e.id))
+            continue;
+        seen.add(e.id);
+        fresh.push(e);
+    }
+    return fresh;
+}
+export function formatEvent(e) {
+    const subject = e.report_id ? `report ${e.report_id}` : `topic ${e.topic_id}`;
+    const who = e.author_agent ? `${e.author_agent} (agent for ${e.author_email})` : e.author_email ?? "";
+    const by = e.author_kind === "customer" ? `customer ${who}` : who;
+    const body = e.body.replace(/\s+/g, " ");
+    return `${e.at}  ${e.type}/${e.kind}  ${subject}  ${by}: ${body.length > 120 ? body.slice(0, 117) + "..." : body}`;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** `manda watch`: print each change as it lands, one JSON object per line when piped, so a
+ * harness can wake on stdout. Without --since it starts from now. --once polls one time and
+ * ends with a `cursor` line to resume from. The cursor is opaque to the client; a bare
+ * `YYYY-MM-DD HH:MM:SS` is also accepted as a starting point. Dedupe by id covers the
+ * inclusive boundary of that bare form. */
+export async function watch(config, flags) {
+    const once = flags["once"] === true;
+    const intervalRaw = flags["interval"] === undefined ? "15" : String(flags["interval"]);
+    const interval = Number(intervalRaw);
+    if (!Number.isFinite(interval) || interval < 1)
+        die(400, "--interval must be a number of seconds, at least 1");
+    let since = flags["since"] === undefined ? undefined : String(flags["since"]);
+    const seen = new Set();
+    const jsonMode = isJsonMode(flags);
+    for (;;) {
+        const query = { since, project_id: flags["project"] ? String(flags["project"]) : undefined };
+        if (flags["limit"])
+            query["limit"] = String(flags["limit"]);
+        const res = await api(config, "/api/agent/v1/changes", { query });
+        if (!res.ok)
+            return handleError(res);
+        for (const e of unseenEvents(seen, res.data.events)) {
+            process.stdout.write(jsonMode ? JSON.stringify(e) + "\n" : formatEvent(e) + "\n");
+        }
+        since = res.data.cursor;
+        if (seen.size > 10_000)
+            seen.clear();
+        if (once) {
+            process.stdout.write(jsonMode ? JSON.stringify({ type: "cursor", cursor: since }) + "\n" : `cursor ${since}\n`);
+            return;
+        }
+        await sleep(interval * 1000);
+    }
+}
 // --- instructions ---
 /** A block for CLAUDE.md or AGENTS.md: the loop a harness runs with manda as its coordination layer. */
 export const INSTRUCTIONS = `## Manda: customer feedback and work coordination
@@ -189,6 +243,10 @@ The loop:
    Then \`manda report comment <id> --audience customer --outcome resolved --body "<what changed, in their words>"\`.
    Internal notes use \`--audience internal\`. Never resolve without a customer-facing explanation.
 6. \`manda topic transition <topic> complete\` when the change is available to customers; \`manda topic announce <topic> --body "<progress>"\` for public progress.
+7. Between tasks, \`manda watch\` prints one JSON line per change as it lands: new reports, customer replies
+   (\`type\` report_update with \`author_kind\` customer), topic changes. \`manda watch --once\` polls once and ends with
+   a \`cursor\` line; resume later with \`manda watch --since <cursor>\`. A customer reply on a report you resolved
+   means it is not done: \`manda report reopen <id>\` and go back to step 2.
 
 Rules: read before you write (every write checks the revision); do not reprioritise by editing reports, reorder topics
 (\`manda topic reorder\`) with the person who owns the roadmap; a 3 exit means someone else changed it, re-read and decide again.

package/dist/skill.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `manda skill`: print the bundled SKILL.md. The file ships in the npm tarball at
+ * `<package>/skills/manda-cli/SKILL.md` (see package.json "files"); dist/skill.js and
+ * src/skill.ts both sit one level below the package root, so one relative path serves
+ * the installed package and a development checkout.
+ */
+export declare function skillPath(): string | null;
+export declare function readSkill(): string;
+export declare function skill(): void;

package/dist/skill.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * `manda skill`: print the bundled SKILL.md. The file ships in the npm tarball at
+ * `<package>/skills/manda-cli/SKILL.md` (see package.json "files"); dist/skill.js and
+ * src/skill.ts both sit one level below the package root, so one relative path serves
+ * the installed package and a development checkout.
+ */
+export function skillPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidate = join(here, "..", "skills", "manda-cli", "SKILL.md");
+    return existsSync(candidate) ? candidate : null;
+}
+export function readSkill() {
+    const path = skillPath();
+    if (!path) {
+        throw new Error("SKILL.md is missing from this install. Reinstall: npx -y @aiaiai-pt/manda-cli@latest skill");
+    }
+    return readFileSync(path, "utf8");
+}
+export function skill() {
+    process.stdout.write(readSkill());
+}

package/dist/usage.d.ts

@@ -0,0 +1,3 @@
+export declare const USAGE = "Usage: manda <command> [options]\n\nCommands:\n  skill                          Print the agent skill (SKILL.md) for Claude Code, Codex or any harness\n  instructions                   Print a CLAUDE.md / AGENTS.md block for this loop\n  whoami                         Show authenticated identity\n  projects                       List projects\n  inbox                          List submissions (inbox)\n  next                           What to work on next, in priority order (--project)\n  watch                          Print changes as they land (--since, --project, --interval, --once)\n  report show <id>               Show a report\n  report capture                 Create a new report\n  report assign <id>             Assign a report\n  report ack <id>                Acknowledge a report\n  report resolve <id>            Resolve a report\n  report reopen <id>             Reopen a report\n  report link <id>               Link external work to a report (--work-url)\n  report comment <id>            Add a comment to a report\n  topic list                     List topics\n  topic show <id>                Show a topic\n  topic create                   Create a topic\n  topic transition <id> <event>  Transition a topic\n  topic note <id>                Add a note to a topic\n  topic edit <id>                Edit a topic\n  topic link-report <id>         Link a report to a topic\n  topic unlink-report <id>       Unlink a report from a topic\n  topic link-work <id>           Link external work to a topic (--issue-url)\n  topic unlink-work <id>         Unlink external work from a topic\n  topic publish <id>             Publish a topic\n  topic unpublish <id>           Unpublish a topic\n  topic edit-public <id>         Edit a topic's public view\n  topic reorder                  Reorder topics\n  topic announce <id>            Add an announcement to a topic\n  topic unannounce <id>          Remove an announcement (--announcement <id>)\n  auth login                     Save credentials\n  auth status                    Show credential source and verify\n\nGlobal options:\n  --url <url>        Server URL (overrides env/config)\n  --token <token>    Agent token (overrides env/config)\n  --json             Force JSON output\n  --help             Show help\n";
+/** The command names USAGE lists, e.g. "report show", "auth login". */
+export declare function usageCommands(): string[];

package/dist/usage.js

@@ -0,0 +1,53 @@
+export const USAGE = `Usage: manda <command> [options]
+
+Commands:
+  skill                          Print the agent skill (SKILL.md) for Claude Code, Codex or any harness
+  instructions                   Print a CLAUDE.md / AGENTS.md block for this loop
+  whoami                         Show authenticated identity
+  projects                       List projects
+  inbox                          List submissions (inbox)
+  next                           What to work on next, in priority order (--project)
+  watch                          Print changes as they land (--since, --project, --interval, --once)
+  report show <id>               Show a report
+  report capture                 Create a new report
+  report assign <id>             Assign a report
+  report ack <id>                Acknowledge a report
+  report resolve <id>            Resolve a report
+  report reopen <id>             Reopen a report
+  report link <id>               Link external work to a report (--work-url)
+  report comment <id>            Add a comment to a report
+  topic list                     List topics
+  topic show <id>                Show a topic
+  topic create                   Create a topic
+  topic transition <id> <event>  Transition a topic
+  topic note <id>                Add a note to a topic
+  topic edit <id>                Edit a topic
+  topic link-report <id>         Link a report to a topic
+  topic unlink-report <id>       Unlink a report from a topic
+  topic link-work <id>           Link external work to a topic (--issue-url)
+  topic unlink-work <id>         Unlink external work from a topic
+  topic publish <id>             Publish a topic
+  topic unpublish <id>           Unpublish a topic
+  topic edit-public <id>         Edit a topic's public view
+  topic reorder                  Reorder topics
+  topic announce <id>            Add an announcement to a topic
+  topic unannounce <id>          Remove an announcement (--announcement <id>)
+  auth login                     Save credentials
+  auth status                    Show credential source and verify
+
+Global options:
+  --url <url>        Server URL (overrides env/config)
+  --token <token>    Agent token (overrides env/config)
+  --json             Force JSON output
+  --help             Show help
+`;
+/** The command names USAGE lists, e.g. "report show", "auth login". */
+export function usageCommands() {
+    const block = USAGE.slice(USAGE.indexOf("Commands:"), USAGE.indexOf("Global options:"));
+    return block
+        .split("\n")
+        .slice(1)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => line.split(/\s{2,}/)[0].replace(/ <[^>]+>/g, ""));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/manda-cli",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "CLI for the Manda feedback service",
   "license": "MIT",
   "type": "module",
@@ -20,6 +20,7 @@
   },
   "files": [
     "dist",
+    "skills/manda-cli/SKILL.md",
     "README.md"
   ],
   "scripts": {

package/skills/manda-cli/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: manda-cli
+description: Complete reference for the Manda CLI. Use this whenever you need to work customer feedback from the command line - read the inbox, pick what to do next, acknowledge, assign, comment and resolve reports, group them into roadmap topics, link pull requests, publish progress to the public portal, or run the report-to-release loop as a coding agent.
+---
+
+# Manda CLI Reference
+
+Manda is the ledger of what customers reported and what they have been told. Reports arrive
+through the hosted widget on a product's own pages; staff and coding agents work them through
+this CLI. One command per staff action, JSON on stdout when piped, no runtime dependencies.
+This skill is the operational reference: assume you have shell access and never need `--help`.
+
+```sh
+npx -y @aiaiai-pt/manda-cli@latest <command>   # no install
+npm i -g @aiaiai-pt/manda-cli                   # then: manda <command>
+```
+
+Requires Node.js 22 or later.
+
+## Conceptual model
+
+| Object | What it is | Lifecycle |
+|---|---|---|
+| Project | one product surface (a site, an app); owns reports and topics | created by an admin in the web UI |
+| Report (submission) | one thing a customer said: `bug`, `feature` or `other`, with a message and an optional reporter email | `new` -> `acknowledged` -> `resolved` (and back via reopen) |
+| Update | an entry on a report's timeline: an internal note or a customer-facing comment, optionally closing (`resolved`) or reopening (`open`) the report | append-only |
+| Topic | a roadmap item that groups reports by customer intent; has a public view on the portal when published | `considering` -> `planned` -> `in_progress` -> `available`; `not_planned` from any of the first three |
+| Announcement | a public progress note on a topic | append-only |
+| Agent token | a bearer token minted by an org admin that acts **as that admin** on the agent lane; every write records the agent name beside the owner's email | revocable; dies with the owner |
+
+Priority is the topic order on the roadmap, never a column on the report. `manda next` derives
+it; nothing on a report says "P1".
+
+## Authentication
+
+An org admin mints a token at `https://manda.aiaiai.pt/admin/org` (section **Agents**, button
+ADD AGENT). The secret (`mn_agent_...`) is shown once. It is its owner: same organisation,
+same checks, same assignee rules.
+
+```sh
+export MANDA_TOKEN=mn_agent_...
+export MANDA_URL=https://manda.aiaiai.pt   # optional, this is the default
+manda whoami                               # email, domain, agent name
+```
+
+Or save it once:
+
+```sh
+manda auth login --token mn_agent_...      # --url to point at another server
+manda auth status                          # prints the credential source and verifies it
+```
+
+Credentials live in `${XDG_CONFIG_HOME:-~/.config}/manda/config.json`, mode 0600.
+Precedence: `--url`/`--token` flags, then `MANDA_TOKEN`/`MANDA_URL`, then the file.
+`manda skill` and `manda instructions` need no credentials and no server.
+
+## Global options and output
+
+| Option | Effect |
+|---|---|
+| `--json` | JSON on stdout even on a TTY |
+| `--url <url>` | server, overrides env and file |
+| `--token <token>` | token, overrides env and file |
+| `--help` | usage, anywhere on the line |
+
+- stdout: JSON when piped or with `--json`; a human table on a TTY.
+- stderr: errors as JSON, `{ "error": { "status", "message", "exit" } }`. On a 409 the error
+  carries `"current"`, the freshly fetched resource, so you can decide again without a second call.
+- Flags are strict: an unknown or misspelled flag is a usage error (exit 1), never ignored.
+- Text flags (`--message`, `--body`, `--resolution`, `--title`, `--description`, `--public-title`,
+  `--public-summary`) accept `-` to read stdin. One `-` per call.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Usage error: missing or unknown flag, unknown command, stdin used for two flags |
+| 2 | Auth: 401, 403, or no credentials configured |
+| 3 | Conflict: 409, the revision you wrote against is stale |
+| 4 | Not found: 404 |
+| 5 | Server or network error: 400, 415, 429, 5xx, no connection |
+
+Branch on the code, not on the message.
+
+## The revision rule
+
+Every write (`assign`, `ack`, `resolve`, `reopen`, `link`, `comment`, every `topic` mutation)
+reads the resource first to learn its current `revision`, unless you pass `--revision N`.
+On 409 the CLI does not retry: it refetches, prints the current state under `error.current`,
+and exits 3. Re-read, decide again, write again. Someone else changed it, and that is
+information, not noise.
+
+`manda report comment` always sends a `request_id` (a random UUID, or `--request-id <uuid>`),
+so a retried comment is idempotent.
+
+## Commands
+
+### Identity and projects
+
+| Command | Does |
+|---|---|
+| `manda whoami` | the admin this token acts for: `email`, `domain`, `agent.name` |
+| `manda projects` | projects in the organisation: `id`, `name` |
+| `manda skill` | prints this file |
+| `manda watch [--since <cursor>] [--project <id>] [--interval <s>] [--once]` | change feed, see below |
+| `manda instructions` | prints a short CLAUDE.md / AGENTS.md block describing the loop below |
+| `manda auth login --token <t> [--url <u>]` | saves credentials |
+| `manda auth status` | credential source, server, and a live identity check |
+
+### Reading the inbox
+
+```sh
+manda inbox                                   # every report, newest first
+manda inbox --project <id> --state new        # filters: --state new|acknowledged|resolved
+manda inbox --assignee me                     # --assignee me|unassigned|<email>
+manda inbox --q "login"                       # text search; --page N --limit N
+manda next                                    # what to work on, in priority order
+manda next --project <id>
+manda report show <id>                        # the report and its timeline (updates)
+```
+
+`manda next` lists open reports you own or nobody owns: owned first, then `new` before
+`acknowledged`, then by the roadmap order of the linked topic (unlinked last), then oldest
+first. Take the first one. An unowned report you are working on sinks below fresh reports,
+so assign it to yourself.
+
+JSON shapes: `inbox` returns `{ submissions: [...], total }`; `next` returns
+`{ items: [...], email }` where each item carries `assignee_email` and `topics: [{ title }]`;
+`report show` returns `{ submission: { id, type, status, message, revision, ... }, updates: [...] }`.
+
+### Waking on changes
+
+```sh
+manda watch                                   # from now on, one event per line, polls every 15 s
+manda watch --since "$cursor" --project <id>  # resume from a cursor; --interval <seconds>
+manda watch --once --json                     # one poll, then a final {"type":"cursor","cursor":...} line
+```
+
+Events: new reports, report updates (a customer reply carries `author_kind: customer`), topic
+updates and announcements, as JSON objects when piped. Without `--since` it starts from now.
+The cursor is opaque; keep the last one and pass it back to resume without gaps. A bare
+`YYYY-MM-DD HH:MM:SS` (UTC) is also accepted as a starting point.
+
+### Working a report
+
+```sh
+manda report capture --project <id> --type bug|feature|other --message "<text>" \
+  [--name "<reporter>"] [--email <reporter email>] [--source-label "<where it came from>"]
+manda report assign <id> --to me               # --to <email> | me | none (unassign)
+manda report ack <id>                          # new -> acknowledged: review has started
+manda report comment <id> --body "<text>"      # internal note (default --audience internal)
+manda report comment <id> --audience customer --outcome resolved --body "<what changed, in their words>"
+manda report comment <id> --audience customer --outcome open --body "<why it is back open>"
+manda report resolve <id> --resolution "<text>"
+manda report reopen <id>
+manda report link <id> --work-url <url>        # the PR, issue or commit that carries the fix
+manda report link <id> --none                  # clear it
+```
+
+`--audience customer` is the only thing the reporter sees. A report that asked for
+follow-through gets that comment by mail. Never resolve a report without a customer-facing
+explanation; `resolve` alone closes it silently.
+
+### Topics: the roadmap
+
+```sh
+manda topic list [--project <id>]
+manda topic show <id>
+manda topic create --project <id> --title "<customer intent>" [--description "<text>"]
+manda topic transition <id> plan|start|complete|decline|reconsider|reopen [--body "<text>"]
+manda topic note <id> --body "<internal note>"
+manda topic edit <id> --title "<text>" --description "<text>"
+manda topic link-report <id> --report <report id>
+manda topic unlink-report <id> --report <report id>
+manda topic link-work <id> --tracker github --issue <number> --issue-url <url>
+manda topic unlink-work <id> --tracker github --issue <number>
+manda topic reorder --project <id> <topic id> <topic id> ...   # the full order, first is top
+```
+
+The topic state machine, the only place a topic's state changes:
+
+| Event | From | To |
+|---|---|---|
+| `plan` | considering | planned |
+| `start` | planned | in_progress |
+| `complete` | in_progress | available |
+| `decline` | considering, planned, in_progress | not_planned (`--body` with the reason is required) |
+| `reconsider` | not_planned | considering |
+| `reopen` | available | in_progress |
+
+An event from a state not in its `from` column is refused by the server (exit 5 with the message);
+read `manda topic show <id>` first when in doubt.
+
+### The public portal
+
+```sh
+manda topic publish <id> [--public-title "<text>"] [--public-summary "<text>"]
+manda topic edit-public <id> --public-title "<text>" --public-summary "<text>"
+manda topic unpublish <id>
+manda topic announce <id> --body "<progress, for customers>"
+manda topic unannounce <id> --announcement <announcement id>
+```
+
+Public wording is separate from the internal title and description: write it for the customer,
+not for the team.
+
+## The loop
+
+Use Manda as the coordination layer while working in a codebase, alone or with a person.
+
+1. `manda next --json` and take the first item.
+2. `manda report show <id> --json`, then `manda report assign <id> --to me` and
+   `manda report ack <id>`.
+3. Group it: `manda topic list --json` to find the topic it belongs to, then
+   `manda topic link-report <topic> --report <id>`; or create one
+   (`manda topic create --project <project> --title "<customer intent>"`), `transition <topic> plan`,
+   then `start` when you begin.
+4. Do the work in the repository. Put `Manda-Report: <id>` and `Manda-Topic: <topic>` as commit
+   trailers, and `manda topic link-work <topic> --tracker github --issue <pr number> --issue-url <pr url>`
+   once a PR exists. `manda report link <id> --work-url <pr url>` ties the report to it too.
+5. Tell the customer only when it is true, and "true" means you exercised their path on the
+   deployed version, not the artefact: load the page, call the endpoint, watch it work. A green
+   suite, a merged PR or a file read back are not that. Then
+   `manda report comment <id> --audience customer --outcome resolved --body "<what changed, in their words>"`.
+6. `manda topic transition <topic> complete` when the change is available to customers;
+   `manda topic announce <topic> --body "<progress>"` for public progress along the way.
+
+Rules: read before you write (every write checks the revision). Do not reprioritise by editing
+reports; reorder topics (`manda topic reorder`) with the person who owns the roadmap. Exit 3
+means someone else changed it: re-read and decide again.
+
+## Patterns
+
+```sh
+# Triage everything new in one project
+for id in $(manda inbox --project "$P" --state new --json | jq -r '.submissions[].id'); do
+  manda report ack "$id"
+  manda report comment "$id" --body "Triaged by automation." --audience internal
+done
+
+# Group a report under a new topic and plan it
+topic=$(manda topic create --project "$P" --title "Widget loses the draft on a network error" --json | jq -r .id)
+manda topic link-report "$topic" --report "$id"
+manda topic transition "$topic" plan
+
+# Wake on changes: a customer reply on a resolved report reopens it
+manda watch --since "$cursor" | while read -r event; do
+  if [ "$(jq -r .author_kind <<<"$event")" = customer ]; then
+    manda report reopen "$(jq -r .report_id <<<"$event")"
+  fi
+done
+
+# A long customer-facing comment from a file
+manda report comment "$id" --audience customer --outcome resolved --body - < reply.md
+
+# Idempotent retry of a comment after a flaky network
+manda report comment "$id" --body "Shipped in 0.4.1." --request-id 2f1e5c3a-0b9d-4b7a-9e2c-1d8f6a4b3c21
+
+# Decide again after a conflict
+manda report resolve "$id" --resolution "Fixed" || {
+  [ $? -eq 3 ] && manda report show "$id" --json
+}
+```
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `No credentials configured` (exit 2) | no `MANDA_TOKEN`, no config file, no `--token` | set `MANDA_TOKEN` or `manda auth login --token ...` |
+| 401 or 403 (exit 2) | token revoked, owner left the organisation, or the wrong server | `manda auth status`; mint a new token at `/admin/org` |
+| exit 3 | stale revision | the error's `current` field is the fresh state; decide again |
+| exit 4 | wrong id, or an object in another organisation | `manda inbox` / `manda topic list` to find it |
+| `Unknown option` (exit 1) | a flag this command does not take, or a typo | the flags above are the whole set; stdin `-` feeds one flag only |
+| transition refused (exit 5) | event not allowed from the current state | `manda topic show <id>`, then the table above |
+| no table, only JSON | stdout is a pipe | that is the contract; `--json` makes it explicit |
+
+## Conventions
+
+- Ids are UUIDs. Keep them in variables; never retype them.
+- Internal notes stay `--audience internal`; the customer reads only `--audience customer`.
+- Write the customer-facing comment in the customer's words: what they can now do, not what you changed in the code.
+- One source of priority: the topic order. Reorder with the roadmap owner, not alone.
+- Commit trailers `Manda-Report:` and `Manda-Topic:` on every commit that serves a report.