@theplato/tiro-cli 0.1.0

package/README.md

@@ -0,0 +1,294 @@
+# tiro CLI
+
+> 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.
+
+---
+
+## Quick start
+
+```bash
+npm install -g @theplato/tiro-cli
+tiro auth login                           # browser opens; OAuth + PKCE
+tiro notes search --speaker "김철수" --since 7d --json
+```
+
+Already authenticated through MCP? Reuse your token:
+
+```bash
+TIRO_TOKEN="$(your_token)" tiro notes list
+```
+
+---
+
+## Why tiro CLI
+
+Tiro already ships an [MCP server](https://mcp.tiro.ooo/mcp) for Claude Desktop, Cursor, and Code. So why a CLI?
+
+| | MCP | tiro CLI |
+|---|---|---|
+| Result lands in | Agent **context window** | **Filesystem** (or stdout pipe) |
+| Token cost / session | thousands (schema injected) | dozens (per call) |
+| Hosts | MCP-aware only | Any shell — CI, cron, ad-hoc agents |
+| Best for | small reads, multi-turn reasoning | bulk export, file ops, scripting |
+
+The CLI is **not a replacement for MCP**. It's the same data through a different surface optimized for filesystem-heavy and shell-native workflows.
+
+→ Background reading: [MCP vs API vs CLI — the hands and feet of agents](https://github.com/plato-corp/tiro/blob/main/docs/mcp-vs-api-vs-cli-agent-hands-feet.md) (TBD)
+
+---
+
+## Features
+
+- 🔐 **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.
+- 🧵 **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
+tiro --version
+```
+
+### From source (during alpha)
+```bash
+git clone git@github.com:plato-corp/tiro-cli.git
+cd tiro-cli
+npm install
+npm run build
+npm link
+tiro --help
+```
+
+### Homebrew *(planned for v1.0)*
+```bash
+brew install plato-corp/tap/tiro
+```
+
+**System requirements**: Node.js 20+. macOS / Linux / Windows.
+
+---
+
+## Authentication
+
+```bash
+tiro auth login           # opens browser, OAuth Authorization Code + PKCE
+tiro auth status          # shows current account + token expiry
+tiro auth logout          # clears keychain + DCR client cache
+```
+
+Tokens are stored in the OS-native credential manager:
+- **macOS** — Keychain
+- **Linux** — Secret Service (requires `gnome-keyring` or `kwallet`)
+- **Windows** — Credential Manager
+
+For CI / headless / agent use, set `TIRO_TOKEN`:
+```bash
+export TIRO_TOKEN=...      # overrides keychain
+tiro notes list
+```
+
+---
+
+## Usage
+
+### List recent notes
+```bash
+tiro notes list                                       # pretty table in TTY
+tiro notes list --json                                # NDJSON for pipes
+tiro notes list --folder <id> --limit 100 --cursor <token>
+```
+
+### Search by speaker, date, folder
+```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'
+```
+
+`--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
+```
+
+### Get one note → file (agent-friendly)
+```bash
+tiro notes get <guid> --output ./meeting.md --include transcript
+# stdout: {"ok":true,"data":{"saved":"./meeting.md","size":12450,"format":"md","guid":"...","title":"..."}}
+```
+
+This is the killer pattern for agents — **the actual content goes to disk; only metadata returns to the context window**.
+
+### Raw transcript only
+```bash
+tiro notes transcript <guid>                           # txt by default
+tiro notes transcript <guid> --output ./transcript.md
+tiro notes transcript <guid> --format json --output ./paragraphs.json
+```
+
+---
+
+## Commands
+
+```
+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 get             Get a single note (stdout or file)
+tiro notes transcript      Get raw transcript paragraphs
+
+# Coming in v0.3 / 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
+tiro folders search        Search user / team folders
+tiro schema [<command>]    Print JSON Schema (for agents)
+```
+
+Full sample of every command: `tiro <command> --help`.
+Full design spec: [`SPEC.md`](./SPEC.md).
+
+---
+
+## Global options
+
+```
+--hostname <url>     API base URL (default: https://api.tiro.ooo)
+--json               Force JSON output (NDJSON for lists)
+--pretty             Force pretty (human) output
+--quiet              Suppress non-error output
+--verbose            Verbose logging to stderr
+--no-color           Disable ANSI colors
+-h, --help           Show help
+-v, --version        Print version
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `TIRO_TOKEN` | Bearer token (overrides keychain — for CI / agents) |
+| `TIRO_HOSTNAME` | API base URL |
+| `TIRO_OUTPUT_DIR` | Default `--output-dir` for export commands |
+| `NO_COLOR` | Disable colors ([no-color.org](https://no-color.org/)) |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | success |
+| `1` | generic error |
+| `2` | usage error |
+| `4` | auth required |
+| `64` | EX_USAGE |
+| `65` | EX_DATAERR |
+| `78` | EX_CONFIG (no token, run `tiro auth login`) |
+
+---
+
+## For AI agents
+
+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.
+
+Example agent flow:
+```bash
+# 1. Search → metadata only
+tiro notes search --speaker "김철수" --since 30d --output ./april.jsonl
+# 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.
+```
+
+---
+
+## Development
+
+```bash
+npm install
+npm run dev -- --help            # tsx live-reload
+npm run typecheck                # tsc --noEmit
+npm run test                     # vitest run
+npm run build                    # tsup → dist/bin/tiro.js
+```
+
+Stack: TypeScript ESM (Node 20+), [`commander`](https://github.com/tj/commander.js) for parsing, [`zod`](https://zod.dev) for response validation, [`@napi-rs/keyring`](https://github.com/napi-rs/node-rs/tree/main/packages/keyring) for OS keychain, [`open`](https://github.com/sindresorhus/open) for browser launch.
+
+See [`CLAUDE.md`](./CLAUDE.md) for working with this repo via Claude Code.
+
+---
+
+## Architecture
+
+The CLI sits on the public Tiro API alongside the MCP server, sharing the same OAuth provider:
+
+```
+                    ┌──────────────────────────────┐
+                    │ Tiro Backend (Kotlin)         │
+                    │  /v1/external/* + /v1/mcp/*   │
+                    └──────────────┬────────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              ▼                    ▼                    ▼
+       ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+       │ tiro CLI     │    │ Tiro MCP     │    │  Web app     │
+       │ (this repo)  │    │ (mcp.tiro)   │    │              │
+       └──────────────┘    └──────────────┘    └──────────────┘
+       (filesystem,         (in-context,           (humans)
+        bulk, pipe)          schema-typed)
+```
+
+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
+5. Same token works on `/v1/external/*` and `/v1/mcp/*` (audience-list overlap)
+
+---
+
+## Roadmap
+
+- ✅ **v0.1** — Auth (`login`, `status`, `logout`) + `--help`
+- 🚧 **v0.2** — Notes core (`list`, `search`, `get`, `transcript`)
+- ⏳ **v0.3** — `notes export` (bulk → directory + manifest.jsonl)
+- ⏳ **v0.4** — Templates, share-links, folders, `schema`
+- ⏳ **v1.0** — Stable. Tests, docs polish, npm publish.
+- 🔮 **v1.x** — Device Flow (RFC 8628), shell completions, self-update
+
+See [`SPEC.md`](./SPEC.md) for the full v1 design.
+
+---
+
+## Contributing
+
+This repo is currently private alpha. Feedback and bug reports go to the internal Slack `#tiro-backend` channel; once we open up, this section will list public contribution guidelines.
+
+---
+
+## License
+
+Proprietary. © ThePlato. All rights reserved.
+
+> Once we ship v1.0, the license decision (MIT / Apache 2.0 / proprietary) will be revisited.

package/SPEC.md

@@ -0,0 +1,364 @@
+# tiro-cli v1 SPEC
+
+> Status: **Active design** (2026-05-06) — backend OAuth 인프라 조사 완료, 변경 0으로 진행 가능 확인됨
+> Owner: yeoul / @theplato
+
+## 0. 한 줄 정체성
+
+> **tiro-cli 는 에이전트의 발이다.** MCP가 컨텍스트 안에서 작은 데이터를 다루는 손이라면, CLI는 큰 데이터를 disk로 옮기고 shell pipe 로 흘려보내는 발.
+
+## 1. 정체성 / 비정체성
+
+### 정체성
+- **Agent-first** read/export/share tool. 인간 power user 도 동시 만족
+- **Filesystem-first**: 결과물을 disk에 떨어뜨리고 metadata 만 stdout으로
+- **MCP feature parity**: tiro-mcp-server 의 14개 도구를 모두 동등하게 노출 + filesystem 확장
+- **Self-describing**: agent 가 docs 없이 `tiro schema` 로 자기 발견
+
+### 비정체성
+- 음성 파일 업로드/다운로드 (MCP 에서 PR #21로 제거됨, 일관성 유지) — v2 검토
+- 인간 GUI 의 대체재 (folder CRUD 등 interactive task 는 web)
+- Backoffice / admin 도구 (별도 surface)
+
+## 2. 아키텍처
+
+```
+tiro Backend (Kotlin) — /v1/external/* 40+ endpoints, OpenAPI 3.1 SSoT
+                          (external-api-docs/openapi.yaml)
+                                    │
+        ┌─────────────────┬─────────┼─────────────────┐
+        ▼                 ▼                           ▼
+   ┌──────────┐    ┌──────────────┐            ┌──────────┐
+   │ MCP      │    │ tiro-cli     │            │ Web UI   │
+   │ 14 tools │    │ 17 commands  │            │          │
+   │  (no     │    │ (MCP parity  │            │          │
+   │  voice)  │    │  + file ops) │            │          │
+   └──────────┘    └──────────────┘            └──────────┘
+```
+
+## 3. 패키지 / 배포
+
+| 항목 | 값 |
+|---|---|
+| npm package | **`@theplato/tiro-cli`** |
+| bin name | **`tiro`** |
+| 언어 | TypeScript (Node 20+, ESM) |
+| 배포 채널 | npm (1차), Homebrew tap (2차) |
+| 설치 | `npm install -g @theplato/tiro-cli` |
+
+**근거**: `tiro` 단일 이름은 npm에 squatted (Zyao89, abandoned v0.0.0). `@tiro` / `@theplato` 모두 가용. **product brand 가 user-facing 인 경우 product 이름 우선** (Stripe `@stripe/*`, Bolta `@bolta-io/cli` 패턴). 향후 `@tiro/sdk`, `@tiro/mcp-server` (rename 후) 등 자연 확장.
+
+## 4. 인증
+
+### 흐름 (3-tier)
+```
+1. TIRO_TOKEN env var 있음? → 그것 사용 (CI / agent 비대화 컨텍스트)
+2. OS Keychain에 토큰 있음? → 그것 사용
+3. 둘 다 없음? → "tiro auth login" 안내, exit code 78 (EX_CONFIG)
+```
+
+### `tiro auth login` — Authorization Code Flow + PKCE + loopback redirect
+
+```
+1. POST /v1/mcp/oauth/register (RFC 7591 Dynamic Client Registration)
+   body: { client_name: "tiro-cli", redirect_uris: ["http://127.0.0.1:<port>/callback"],
+           grant_types: ["authorization_code"], response_types: ["code"],
+           token_endpoint_auth_method: "none" }
+   → { client_id }
+
+2. PKCE 생성: code_verifier (43~128자 랜덤), code_challenge = base64url(sha256(code_verifier))
+3. state 생성 (32바이트 랜덤)
+4. 임시 HTTP 서버 시작 (ephemeral port)
+5. 브라우저 자동 오픈:
+   GET /v1/mcp/oauth/authorize?response_type=code&client_id=...
+       &redirect_uri=http://127.0.0.1:<port>/callback&state=...
+       &code_challenge=...&code_challenge_method=S256
+
+6. 사용자 Google OAuth → backend google/callback → tiro-client web callback
+   → 최종 http://127.0.0.1:<port>/callback?code=...&state=... 으로 리다이렉트
+
+7. CLI 의 임시 서버가 callback 수신 → state 검증
+
+8. POST /v1/mcp/oauth/token (form-encoded)
+   body: grant_type=authorization_code&code=...&redirect_uri=...
+        &client_id=...&code_verifier=...
+   → { access_token: <JWT 180일>, token_type: "Bearer", expires_in: ... }
+
+9. JWT 디코드 → sub (userId), exp 추출
+10. OS Keychain 에 토큰 저장 (service: "io.tiro.cli", account: "default")
+```
+
+### Headless / SSH / CI 환경
+- `TIRO_TOKEN` env var 사용 (별도 머신에서 로그인 후 토큰 복사)
+- Device Flow (RFC 8628) 는 백엔드 미지원 → v1.x follow-up
+
+### 토큰 저장
+- macOS Keychain / Linux Secret Service / Windows Credential Manager via `@napi-rs/keyring`
+- Fallback: `~/.config/tiro/auth.json` (perm 600), 평문 경고 표시
+
+## 5. 명령 트리 (v1, 17개)
+
+### 5.1 Auth (3) — 모든 환경에서 작동
+```
+tiro auth login    [--no-browser]        # Authorization Code + loopback
+tiro auth status   [--json]              # 현재 계정 / scope / expires
+tiro auth logout                         # Keychain 정리
+```
+
+### 5.2 Notes (5) — read-heavy 본진 (MCP `list_notes`, `search_notes`, `get_note`, `get_note_transcript` + 파일 export)
+```
+tiro notes list                          # GET /v1/external/notes
+  --folder <id> --limit <n> --cursor <c> --json|--pretty
+
+tiro notes search [query]                # POST /v1/external/notes/search
+  --speaker <name> --since <date> --until <date>
+  --folder <id> --limit <n> --cursor <c>
+  → NDJSON output (1 line = 1 note metadata)
+
+tiro notes get <guid>                    # GET /v1/external/notes/{guid} + paragraphs
+  --output <path>                        # 파일 저장 (stdout = path만, agent 컨텍스트 절약)
+  --format md|json|txt                   # default: md (TTY) / json (pipe)
+  --include transcript,summary,documents,participants
+
+tiro notes transcript <guid>             # GET /v1/external/notes/{guid}/paragraphs
+  --output <path> --format md|json|txt
+
+tiro notes export                        # bulk 다운로드 — CLI 킬러 명령
+  --query <q> --speaker <n> --since <d> --until <d> --folder <id>
+  --output-dir <dir>                     # 필수
+  --include transcript,summary,documents,share-link
+  --format md|json --concurrency <n>
+  → 디렉토리 + manifest.jsonl
+```
+
+### 5.3 Document Templates (2) — MCP `list_document_templates`, `get_document_template`
+```
+tiro templates list                      # GET /v1/external/note-document-templates
+  --json|--pretty
+
+tiro templates get <id>                  # GET /v1/external/note-document-templates/{id}
+  --output <path> --format md|json
+```
+
+### 5.4 Share Links (3) — MCP `create_share_link`, `get_share_link`, `delete_share_link`
+```
+tiro share-links create <noteGuid>       # PUT /v1/external/notes/{guid}/share-link
+  --password <pw>                        # 옵션: 비밀번호 보호
+  --no-password                          # 기존 비밀번호 제거
+
+tiro share-links get <noteGuid>          # GET .../share-link
+  --password <pw>                        # 비밀번호 검증
+
+tiro share-links delete <noteGuid>       # DELETE .../share-link
+```
+
+### 5.5 Folders (2) — MCP `search_user_folders`, `search_team_folders`
+```
+tiro folders search [query]              # search_user_folders + search_team_folders 통합
+  --scope user|team|all                  # default: all
+  --limit <n>
+  --json|--pretty
+```
+
+### 5.6 Self-describe (1)
+```
+tiro schema [<command>]                  # 명령 트리 + 입출력 JSON Schema (agent self-introspection)
+```
+
+### 5.7 ChatGPT Deep Research aliases (2) — MCP `search`, `fetch`
+> MCP에 있지만 CLI 에는 별도 명령 안 만듦. `notes search` 와 `notes get` 이 같은 기능 제공.
+> 호환 필요 시 `tiro search` / `tiro fetch` 별칭 추가 검토 (v1.x).
+
+## 6. `tiro --help`
+
+```
+tiro — AI notes & transcripts CLI
+
+USAGE
+  tiro <command> [options]
+
+COMMANDS
+  auth login            Sign in via OAuth (browser-based, PKCE)
+  auth status           Show current account and scopes
+  auth logout           Sign out and clear stored token
+
+  notes list            List recent notes
+  notes search          Search notes by speaker / date / folder
+  notes get             Get a single note (stdout or file)
+  notes transcript      Get raw transcript paragraphs
+  notes export          Bulk-export notes to a directory
+
+  templates list        List note document templates
+  templates get         Get a specific template
+
+  share-links create    Create or update a share link for a note
+  share-links get       Get the share link of a note
+  share-links delete    Delete a share link
+
+  folders search        Search user or team folders by keyword
+
+  schema                Print JSON Schema of a command (for agents)
+
+GLOBAL OPTIONS
+  --hostname <url>      API base URL (default: https://api.tiro.ooo)
+  --json                Force JSON output
+  --pretty              Force pretty (human) output
+  --quiet               Suppress non-error output
+  --verbose             Verbose logging to stderr
+  --no-color            Disable ANSI colors
+  --help                Show help for a command
+  --version             Print version
+
+ENVIRONMENT
+  TIRO_TOKEN            Bearer token (overrides keychain)
+  TIRO_HOSTNAME         API base URL
+  TIRO_OUTPUT_DIR       Default --output-dir for export commands
+  NO_COLOR              Disable colors (https://no-color.org/)
+
+EXAMPLES
+  tiro auth login
+  tiro notes search --speaker "김철수" --since 7d --json
+  tiro notes get <guid> --output ./meeting.md --include transcript,summary
+  tiro notes export --query "..." --output-dir ./backup --include transcript,summary
+```
+
+## 7. 출력 / 파일 / 에러 계약
+
+### 7.1 형식 자동 선택
+- `process.stdout.isTTY` true → pretty
+- `process.stdout.isTTY` false (pipe / file redirect) → JSON
+- `--json` / `--pretty` 로 강제
+
+### 7.2 파일 저장 시 stdout 계약
+파일 저장 (`--output`, `--output-dir`) 시 stdout 은 metadata 만:
+```json
+{"saved":"./meeting.md","size":5234,"format":"md","guid":"note-guid-123"}
+```
+
+### 7.3 파일 형식
+- **`.md`**: 인간 친화. YAML frontmatter + 마크다운 본문 + 화자별 단락
+- **`.json`**: 구조화. 전체 객체 그대로 (agent 파싱 친화)
+- **`.txt`**: 토큰 절약 / embedding 친화. `[화자] 텍스트` 만
+
+### 7.4 NDJSON streaming
+list / search 결과는 line-delimited (한 줄에 한 객체) — agent 가 `head` / `jq` 로 점진 처리
+
+### 7.5 Manifest (`manifest.jsonl`)
+bulk export 자동 생성. 한 줄에 한 항목:
+```jsonl
+{"guid":"note-guid-123","title":"주간 미팅","path":"./n1.md","size":5234,"status":"ok"}
+{"guid":"note-guid-789","path":null,"error":{"code":"not_found","message":"..."}}
+```
+
+### 7.6 에러 계약 (Bolta 패턴)
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "auth_required",
+    "message": "Token expired. Run `tiro auth login` to refresh.",
+    "suggestion": "tiro auth login",
+    "errorType": "unauthorized",
+    "httpStatus": 401,
+    "requestId": "req_abc123"
+  }
+}
+```
+
+### 7.7 Exit codes (sysexits.h)
+| Code | 의미 |
+|---|---|
+| 0 | 성공 |
+| 1 | generic error |
+| 2 | usage error |
+| 4 | auth required |
+| 64 | EX_USAGE |
+| 65 | EX_DATAERR |
+| 78 | EX_CONFIG (자격증명 부재) |
+
+### 7.8 토큰 노출 방지
+- 절대 stdout 에 토큰 직접 출력 금지
+- 로그 (`--verbose`) 에 토큰 prefix 4글자만
+- error message 에 token 헤더 echo 금지
+
+## 8. 의존성
+
+| | 패키지 | 이유 |
+|---|---|---|
+| runtime | `commander@12` | 인자 파싱, 자동 help |
+| runtime | `@napi-rs/keyring@1` | OS keychain (keytar 보다 모던, prebuild 안정) |
+| runtime | `conf@13` | XDG 호환 config 파일 |
+| runtime | `open@10` | 브라우저 자동 오픈 |
+| runtime | `zod@3` | 응답 런타임 검증 (mcp-server 와 일관) |
+| dev | `typescript@5.6+` | 타입 |
+| dev | `tsup@8` | esbuild 기반 번들 |
+| dev | `tsx@4` | TS 직접 실행 (dev) |
+| dev | `vitest@2` | 단위 테스트 |
+| dev | `@types/node@20` | Node 타입 |
+
+> HTTP 는 Node 20 내장 fetch — 추가 dep 0
+> Color 는 ANSI 코드 + isTTY 체크 자체 구현 — chalk/ora 미사용
+
+## 9. 프로젝트 구조
+
+```
+tiro-cli/
+├── src/
+│   ├── bin/tiro.ts                 # entry + commander setup
+│   ├── commands/
+│   │   ├── auth/{login,logout,status}.ts
+│   │   ├── notes/{list,search,get,transcript,export}.ts
+│   │   ├── templates/{list,get}.ts
+│   │   ├── share-links/{create,get,delete}.ts
+│   │   ├── folders/search.ts
+│   │   └── schema.ts
+│   └── lib/
+│       ├── api/{client,types}.ts
+│       ├── auth/{flow,keychain,pkce,loopback,browser}.ts
+│       ├── output/{format,tty,manifest}.ts
+│       ├── error.ts
+│       └── config.ts
+├── test/
+├── package.json
+├── tsconfig.json
+└── SPEC.md / README.md
+```
+
+## 10. 출시 마일스톤
+
+**v0.1 (이번 작업)** — auth 흐름 작동 + `tiro --help`
+- `tiro auth login` (Authorization Code + PKCE + loopback)
+- `tiro auth status`
+- `tiro auth logout`
+- `tiro --help`, `tiro --version`
+
+**v0.2** — notes core
+- `tiro notes list / search / get / transcript`
+- `--output`, `--format md|json|txt`
+
+**v0.3** — bulk export (킬러)
+- `tiro notes export` (manifest.jsonl)
+
+**v0.4** — 나머지
+- `tiro templates / share-links / folders / schema`
+
+**v1.0** — 안정화
+- 단위 테스트 ≥80%, e2e (assert_cmd 패턴), npm publish
+
+## 11. 미결 (다음 회차)
+
+- [ ] OAuth `client_id` 캐싱 정책 (DCR 30일 TTL — 재등록 자동화?)
+- [ ] Homebrew tap (`plato-corp/tiro`) — npm 단독 vs 병행
+- [ ] 텔레메트리 정책 (opt-out by default? GitHub CLI 백래시 사례)
+- [ ] Device Flow (RFC 8628) 백엔드 추가 — headless/SSH 지원 시점
+- [ ] `tiro completion bash|zsh|fish` 셸 자동완성
+- [ ] OpenAPI codegen (`openapi-typescript` + `openapi-fetch`) 도입 시점
+
+## 12. 참고
+
+- 1차 회차 결정: project memory `project_tiro_cli_design.md`
+- 위키 분석: `mcp-vs-api-vs-cli-agent-hands-feet.md` (yeoul, blog raw material)
+- API SSoT: `external-api-docs/openapi.yaml`
+- MCP 현재: tiro-mcp-server PR #21 머지 후 14 tools (voice 제거됨)
+- Backend OAuth: `api/.../McpOAuthController.kt`, `core/.../McpJwtService.kt`, `DynamicClient.kt`
+- 레퍼런스: gh CLI (Auth Code + GH_TOKEN), Stripe CLI (Device Flow), Bolta (`@bolta-io/cli`, agent-first)