@theplato/tiro-cli 0.1.0 → 0.2.0

package/README.md

@@ -3,14 +3,17 @@
 > AI notes & transcripts — an **agent-first** command line for [Tiro](https://tiro.ooo).
 > The "feet" to MCP's "hands": filesystem-heavy, pipe-friendly, context-economical.
 
+[![npm version](https://img.shields.io/npm/v/@theplato/tiro-cli)](https://www.npmjs.com/package/@theplato/tiro-cli)
+[![Node.js](https://img.shields.io/node/v/@theplato/tiro-cli)](https://nodejs.org)
+
 ---
 
 ## Quick start
 
 ```bash
 npm install -g @theplato/tiro-cli
-tiro auth login                           # browser opens; OAuth + PKCE
-tiro notes search --speaker "김철수" --since 7d --json
+tiro auth login                                 # browser opens; OAuth + PKCE
+tiro notes search "Q3 Planning" --since 7d --json
 ```
 
 Already authenticated through MCP? Reuse your token:
@@ -42,18 +45,20 @@ The CLI is **not a replacement for MCP**. It's the same data through a different
 
 - 🔐 **OAuth Authorization Code + PKCE** — no copy-paste tokens, no secrets in shell history. Tokens live in OS Keychain.
 - 📁 **`--output` writes to disk** — stdout becomes a single line of metadata. Agents stay context-light.
+- 🪞 **Same JSON shape as MCP** — `tiro notes transcript --format json` mirrors `get_note_transcript` exactly. Switch surfaces without changing parsers.
 - 🧵 **NDJSON streams by default** — pipe to `jq`, `head`, `xargs`. No buffer-in-memory surprises.
 - 🤖 **Agent-aware** — TTY detection auto-selects pretty vs JSON. `error.suggestion` field for auto-recovery.
-- 🪞 **Self-describing** *(soon)* — `tiro schema notes export` returns input/output JSON Schema.
 - 🚫 **No voice in v1** — intentionally matches MCP feature parity (audio uploads belong elsewhere).
 
 ---
 
 ## Installation
 
-### npm (recommended)
 ```bash
-npm install -g @theplato/tiro-cli
+npm install -g @theplato/tiro-cli            # npm
+pnpm add -g @theplato/tiro-cli               # pnpm
+yarn global add @theplato/tiro-cli           # yarn
+bun add -g @theplato/tiro-cli                # bun
 tiro --version
 ```
 
@@ -101,25 +106,26 @@ tiro notes list
 
 ### List recent notes
 ```bash
-tiro notes list                                       # pretty table in TTY
-tiro notes list --json                                # NDJSON for pipes
+tiro notes list                                              # pretty table in TTY
+tiro notes list --json                                       # NDJSON for pipes
+tiro notes list --keyword "OKR" --since 30d                  # OpenSearch reorder by keyword
 tiro notes list --folder <id> --limit 100 --cursor <token>
 ```
 
-### Search by speaker, date, folder
+### Deep keyword search (returns notes + their primary documents)
 ```bash
-tiro notes search --speaker "김철수" --since 7d
-tiro notes search "quarterly review" --since 2026-04-01 --until 2026-05-01
-tiro notes search --speaker "이영희" --folder <id> --json | jq '.[] | .guid'
+tiro notes search "Q3 Planning"                              # positional keyword
+tiro notes search "OKR" --since 2026-04-01 --until 2026-05-01
+tiro notes search "Acme Corp" --folder <id> --json | jq '.[] | .guid'
 ```
 
 `--since` / `--until` accept ISO-8601 (`2026-04-01T10:00:00Z`) or relative (`7d`, `24h`, `30m`).
 
 ### Get one note → stdout
 ```bash
-tiro notes get <guid>                                  # markdown to TTY
-tiro notes get <guid> --format json                    # JSON to stdout
-tiro notes get <guid> --include transcript             # include paragraphs
+tiro notes get <guid>                                        # markdown to TTY
+tiro notes get <guid> --format json                          # JSON to stdout
+tiro notes get <guid> --include transcript                   # include speaker-attributed paragraphs
 ```
 
 ### Get one note → file (agent-friendly)
@@ -132,11 +138,13 @@ This is the killer pattern for agents — **the actual content goes to disk; onl
 
 ### Raw transcript only
 ```bash
-tiro notes transcript <guid>                           # txt by default
+tiro notes transcript <guid>                                 # md by default in TTY, txt in pipe
 tiro notes transcript <guid> --output ./transcript.md
-tiro notes transcript <guid> --format json --output ./paragraphs.json
+tiro notes transcript <guid> --format json --output ./paragraphs.json   # MCP-shape JSON
 ```
 
+`--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}`).
+
 ---
 
 ## Commands
@@ -146,10 +154,10 @@ tiro auth login            Sign in via OAuth (browser-based, PKCE)
 tiro auth status           Show current account and scopes
 tiro auth logout           Clear stored credentials
 
-tiro notes list            List recent notes (pretty | NDJSON)
-tiro notes search          Search by speaker / date / folder / keyword
+tiro notes list            List notes (lightweight metadata)
+tiro notes search          Deep keyword search (notes + documents hydrated)
 tiro notes get             Get a single note (stdout or file)
-tiro notes transcript      Get raw transcript paragraphs
+tiro notes transcript      Get the full transcript (matches MCP get_note_transcript)
 
 # Coming in v0.3 / v0.4:
 tiro notes export          Bulk-export search results to a directory
@@ -161,6 +169,7 @@ tiro schema [<command>]    Print JSON Schema (for agents)
 
 Full sample of every command: `tiro <command> --help`.
 Full design spec: [`SPEC.md`](./SPEC.md).
+Release history: [`CHANGELOG.md`](./CHANGELOG.md).
 
 ---
 
@@ -206,19 +215,31 @@ If you're an agent (Claude Code, Cursor, ChatGPT) calling tiro CLI from a shell:
 
 1. **Default to `--json`**: predictable shape, NDJSON for streams.
 2. **Always use `--output`** for `notes get` / `notes transcript` — keeps the actual content out of your context window. The stdout response is one line of metadata.
-3. **Pipe instead of buffer**: `tiro notes search ... --json | jq -c '.[] | select(.duration > 600)'`.
-4. **Read errors as JSON**: `error.code`, `error.errorType`, `error.suggestion` are stable. The `suggestion` field is designed for auto-recovery (e.g. `"tiro auth login"` → run that next).
-5. **Respect exit codes**: `4` = auth needed, `78` = no token configured.
+3. **`tiro notes transcript --format json`** matches MCP's `get_note_transcript` JSON exactly. Reuse your MCP parser.
+4. **Pipe instead of buffer**: `tiro notes search "..." --json | jq -c '.[] | select(.recordingDurationSeconds > 600)'`.
+5. **Read errors as JSON**: `error.code`, `error.errorType`, `error.suggestion` are stable. The `suggestion` field is designed for auto-recovery (e.g. `"tiro auth login"` → run that next).
+6. **Respect exit codes**: `4` = auth needed, `78` = no token configured.
 
-Example agent flow:
+Worked example — 30 days of "Acme Corp" meetings:
 ```bash
-# 1. Search → metadata only
-tiro notes search --speaker "김철수" --since 30d --output ./april.jsonl
+# 1. Search → metadata + hydrated documents (NDJSON)
+tiro notes search "Acme Corp" --since 30d --json > /tmp/acme.jsonl
+# stdout: ~12 lines of NDJSON, ~3KB total
+
 # 2. Pull guids without loading bodies
-cat ./april.jsonl | jq -r '.guid' > guids.txt
-# 3. Download transcripts to disk, manifest tracks status
-xargs -I{} tiro notes get {} --output ./notes/{}.md --include transcript < guids.txt
-# Total context cost: ~80 tokens for 100 notes.
+cat /tmp/acme.jsonl | jq -r '.guid' > /tmp/guids.txt
+
+# 3. Download transcripts to disk; agent reads paths instead of content
+xargs -I{} tiro notes transcript {} --output ./out/{}.md < /tmp/guids.txt
+
+# Context cost so far: ~80 tokens (paths + counts).
+# Disk: 12 markdown files ready for grep / Read tool.
+```
+
+Real participant names rendered in markdown will look like:
+```
+**[Yeoul, 00:12]** Let's start with the Acme deal pipeline.
+**[Evan, 00:18]** They just signed the LOI.
 ```
 
 ---
@@ -263,7 +284,7 @@ OAuth Authorization Code + PKCE flow:
 1. Dynamic Client Registration (RFC 7591) — no preconfigured client_id needed
 2. Loopback redirect on an ephemeral `127.0.0.1:<port>`
 3. PKCE S256 challenge, no client secret stored
-4. JWT (HS256) issued for 180 days, stored in OS Keychain
+4. JWT issued for 180 days, stored in OS Keychain
 5. Same token works on `/v1/external/*` and `/v1/mcp/*` (audience-list overlap)
 
 ---
@@ -271,13 +292,13 @@ OAuth Authorization Code + PKCE flow:
 ## Roadmap
 
 - ✅ **v0.1** — Auth (`login`, `status`, `logout`) + `--help`
-- 🚧 **v0.2** — Notes core (`list`, `search`, `get`, `transcript`)
+- ✅ **v0.2** — Notes core (`list`, `search`, `get`, `transcript`); MCP-shape transcript JSON; first test suite
 - ⏳ **v0.3** — `notes export` (bulk → directory + manifest.jsonl)
 - ⏳ **v0.4** — Templates, share-links, folders, `schema`
-- ⏳ **v1.0** — Stable. Tests, docs polish, npm publish.
+- ⏳ **v1.0** — Stable. Public docs, license decision, Homebrew tap.
 - 🔮 **v1.x** — Device Flow (RFC 8628), shell completions, self-update
 
-See [`SPEC.md`](./SPEC.md) for the full v1 design.
+See [`SPEC.md`](./SPEC.md) for the full v1 design and [`CHANGELOG.md`](./CHANGELOG.md) for release history.
 
 ---
 

package/SPEC.md

@@ -217,7 +217,7 @@ ENVIRONMENT
 
 EXAMPLES
   tiro auth login
-  tiro notes search --speaker "김철수" --since 7d --json
+  tiro notes search "Q3 Planning" --since 7d --json
   tiro notes get <guid> --output ./meeting.md --include transcript,summary
   tiro notes export --query "..." --output-dir ./backup --include transcript,summary
 ```
@@ -246,7 +246,7 @@ list / search 결과는 line-delimited (한 줄에 한 객체) — agent 가 `he
 ### 7.5 Manifest (`manifest.jsonl`)
 bulk export 자동 생성. 한 줄에 한 항목:
 ```jsonl
-{"guid":"note-guid-123","title":"주간 미팅","path":"./n1.md","size":5234,"status":"ok"}
+{"guid":"note-guid-123","title":"Weekly standup","path":"./n1.md","size":5234,"status":"ok"}
 {"guid":"note-guid-789","path":null,"error":{"code":"not_found","message":"..."}}
 ```