@theplato/tiro-cli 0.2.1 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,90 @@
+# Tiro for Agents
+
+`@theplato/tiro-cli` is the agent's **feet** — a read-heavy CLI surface for Tiro
+notes & transcripts. For interactive **hands** (tool calls inside an agent
+loop), use the hosted Tiro MCP at `https://mcp.tiro.ooo/mcp`.
+
+## Install
+
+```bash
+npm install -g @theplato/tiro-cli
+tiro auth login
+```
+
+## Connect MCP to Claude Code
+
+```bash
+tiro mcp install
+# prints: claude mcp add --transport http tiro https://mcp.tiro.ooo/mcp
+```
+
+Or run that command directly to register the hosted MCP.
+
+## Discovery (machine-readable)
+
+```bash
+tiro --help
+tiro --version
+tiro mcp info --json
+tiro <group> <verb> --help
+```
+
+## Output contract
+
+| Context | stdout | stderr |
+|---|---|---|
+| TTY (pretty) | rendered markdown / text | progress, prompts |
+| pipe / `--json` | JSON envelope | progress, prompts |
+| `--output <path>` | single metadata JSON line | progress, prompts |
+
+The metadata line includes `saved`, `size`, `format`, `guid`. Agents can
+parse it line-by-line without buffering the file.
+
+## JSON envelope
+
+```json
+{ "ok": true, "data": <payload> }
+{ "ok": false, "error": { "code": "...", "message": "...", "errorType": "..." } }
+```
+
+`errorType` ∈ `bad_request | unauthorized | forbidden | not_found | conflict |
+internal_error`. Exit codes follow `sysexits.h` (`0` ok, `64` usage, `69`
+unauthorized, `70` internal).
+
+## Common flows
+
+| Goal | Command |
+|---|---|
+| List recent notes | `tiro notes list --since 7d --json` |
+| Search notes | `tiro notes search "Q3" --since 30d --json` |
+| Full note metadata | `tiro notes get <guid> --json` |
+| MCP-shape transcript JSON | `tiro notes transcript <guid> --format json` |
+| Save markdown for ingest | `tiro notes transcript <guid> --output ./n.md --no-timestamps` |
+| Save plain text | `tiro notes transcript <guid> --format txt --output ./n.txt` |
+
+The `--format json` output of `transcript` is byte-identical to the MCP
+`get_note_transcript` tool result, so agents can swap surfaces without
+changing parsers.
+
+## Surface separation
+
+- **CLI (this)** — synchronous, file-output-friendly, agent-controlled
+- **MCP** — interactive tool calls inside an agent loop
+  (https://mcp.tiro.ooo/mcp)
+- **HTTP API** — server-to-server; see the OpenAPI spec at
+  https://api-docs.tiro.ooo
+
+When in doubt: use **CLI for batch ingest** (download, write to disk,
+context-light); use **MCP for interactive lookups** during a conversation.
+
+## Authentication
+
+Two ways to authenticate:
+
+1. **Interactive** — `tiro auth login` opens a browser, completes OAuth, and
+   stores the token in the OS keychain.
+2. **Headless / CI** — set `TIRO_TOKEN=<bearer>` in the environment;
+   the keychain is bypassed and tokens are never written to disk.
+
+The CLI never prints tokens to stdout. `tiro auth status` shows only the
+first 4 characters of the access token.

package/README.md

@@ -140,11 +140,29 @@ This is the killer pattern for agents — **the actual content goes to disk; onl
 ```bash
 tiro notes transcript <guid>                                 # md by default in TTY, txt in pipe
 tiro notes transcript <guid> --output ./transcript.md
+tiro notes transcript <guid> --output ./clean.md --no-timestamps   # strip ### time headers
 tiro notes transcript <guid> --format json --output ./paragraphs.json   # MCP-shape JSON
 ```
 
+In markdown, the timestamp now appears once per paragraph as a `### mm:ss`
+header instead of being attached to every speaker line. Use
+`--no-timestamps` to omit them entirely (handy for raw saving / LLM ingest).
+
 `--format json` returns the exact shape MCP's `get_note_transcript` emits (`{noteGuid, title, participants, createdAt, recordingDurationSeconds, paragraphs[]}` with each paragraph carrying `segments[]` of `{content, speaker:{label,name}|null}`).
 
+### Connect to Claude Code (MCP)
+```bash
+tiro mcp install
+# prints: claude mcp add --transport http tiro https://mcp.tiro.ooo/mcp
+
+tiro mcp info --json   # endpoint, transport, install command
+```
+
+The CLI is the agent's *feet* (read, save, browse). The hosted MCP at
+[mcp.tiro.ooo](https://mcp.tiro.ooo/mcp) is the agent's *hands* (interactive
+tool calls inside the loop). See [`AGENTS.md`](./AGENTS.md) for the full
+agent contract.
+
 ---
 
 ## Commands
@@ -159,7 +177,10 @@ tiro notes search          Deep keyword search (notes + documents hydrated)
 tiro notes get             Get a single note (stdout or file)
 tiro notes transcript      Get the full transcript (matches MCP get_note_transcript)
 
-# Coming in v0.3 / v0.4:
+tiro mcp info              Show hosted MCP endpoint info
+tiro mcp install           Print one-line claude-mcp-add command
+
+# Coming in v0.4:
 tiro notes export          Bulk-export search results to a directory
 tiro templates list/get    Document templates
 tiro share-links {C/R/D}   Manage note share links
@@ -168,7 +189,7 @@ tiro schema [<command>]    Print JSON Schema (for agents)
 ```
 
 Full sample of every command: `tiro <command> --help`.
-Full design spec: [`SPEC.md`](./SPEC.md).
+Agent contract: [`AGENTS.md`](./AGENTS.md).
 Release history: [`CHANGELOG.md`](./CHANGELOG.md).
 
 ---