comitia 0.3.0 → 0.4.0

package/README.md

@@ -1,93 +1,117 @@
 # comitia
 
-회사 온톨로지를 **내가 쓰는 AI에서 꺼내 쓴다.** Comitia 웹을 안 열어도 된다.
+Ask anything about your company. Get the answer **and its source** — from the AI you already use.
+
+Comitia turns scattered company records (Slack, meeting notes, docs, email) into a linked wiki.
+This CLI puts that wiki inside Claude Code, Cursor, Codex, Gemini CLI — anything that can run a
+shell command. No per-app config, and the connection doesn't expire.
 
 ```bash
 npm i -g comitia
-comitia init z2o_live_...       # z2o.kr 프로필 → 「연결 토큰」에서 발급한 열쇠
+comitia init -g
 ```
 
-`init` 이 세 가지를 한 번에 한다 — **로그인 · 워크스페이스 지정 · AI 규칙 파일에 사용법 심기.**
+Node.js 18 or later. No dependencies.
+
+## What `init` does
+
+Three things at once — **sign in · pick a workspace · tell your AI that comitia exists.**
 
-마지막이 핵심이다: 명령어를 깔아 둬도 **AI 는 그게 있는 줄 모른다.** 규칙 파일에 한 번
-적어 두면 그다음부터 알아서 쓴다. 여러 번 돌려도 블록은 하나만 남고 기존 내용은 안 건드린다.
+1. Your browser opens Comitia's **"Connection request"** screen. Pick a workspace and a
+   permission level, click **Allow**, and the terminal says "connected". You never handle a
+   raw token.
+2. If you only have one workspace, it's chosen for you. If you have several, you pick — the
+   CLI won't guess, because writing to the wrong workspace is the worse mistake.
+3. It writes usage notes into your **AI rules files**.
 
-이미 있는 `CLAUDE.md` · `AGENTS.md` · `GEMINI.md` 에 전부 심고, 하나도 없으면
-`AGENTS.md` 와 `CLAUDE.md` 를 만든다. 다른 도구를 쓰면 **그 도구의 규칙 파일을 만들어 두고
-`comitia init` 을 다시 돌리면** 된다.
+That last step is the one that matters. Installing a command isn't enough: **your AI has no
+idea it's there.** One note in the rules file and it reaches for comitia on its own. Run `init`
+again and the block is replaced in place — never duplicated, and the rest of the file is left
+alone.
 
-**폴더마다 하기 싫으면 `comitia init -g`** — `~/.claude/CLAUDE.md` 처럼 도구의 전역 자리에
-심어 **모든 폴더에서** 통하게 한다. (깔린 도구의 자리에만 심는다.)
+It writes to whichever rules files you already have — `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` —
+and creates `AGENTS.md` and `CLAUDE.md` if you have none. Using a different tool? Create its
+rules file and run `comitia init` again.
 
-⚠️ 규칙 파일은 **편의**일 뿐이다. 없어도 CLI 는 셸을 쓸 수 있는 AI 라면 어디서든 돌아간다 —
-한 번 "comitia 로 찾아봐" 라고 말해 주면 그만이다.
+**`comitia init -g`** writes to each tool's global location (`~/.claude/CLAUDE.md` and friends)
+so it works in **every** folder instead of per project. It only touches tools you actually have
+installed.
+
+> The rules file is a convenience, not a requirement. The CLI works from any AI with a shell —
+> saying "look it up with comitia" once is enough.
 
 ```bash
-comitia recent                  # 최근 들어온 슬랙·메일
-comitia find 계약               # 원본에서 찾기
+comitia recent                  # Slack and email, as they came in
+comitia find contract           # search the raw sources
 ```
 
-Claude Code·Cursor·Codex 등 **셸을 쓸 수 있는 AI라면 무엇에서든** 된다.
-MCP 와 달리 앱마다 연동 설정이 필요 없고, 토큰이 만료되지 않아 한 번 연결해 두면 계속 이어진다.
-
-## Claude Code 스킬 — `/comitia:read` · `/comitia:ingest` · `/comitia:slack` · `/comitia:sync`
+## Claude Code skills
 
-`init` 은 Claude Code 가 깔려 있으면 **스킬 셋**도 `~/.claude/skills/comitia/` 에 넣는다.
+If Claude Code is installed, `init` also puts a skill set in `~/.claude/skills/comitia/`.
 
-| | 언제 |
+| | When |
 |---|---|
-| `/comitia:read` | 회사 맥락을 찾아 답할 때 — 슬랙·회의록·위키 |
-| `/comitia:ingest` | 자료를 위키에 넣고 정리할 때 — 넣기 → 뼈대 → 관련 문서 고쳐 쓰기 |
-| `/comitia:slack` | 슬랙에 올릴 때 — 초안을 보여 주고 **허락받은 뒤에만** 봇으로 올린다 |
-| `/comitia:sync` | 지금 당겨올 때 — 매시 정각 자동 수집을 기다리지 않고 `comitia sync`. `recent`·`find` 맨 위 「수집 상태」로 얼마나 최신인지 본다 |
+| `/comitia:read` | Answering from company context — Slack, meeting notes, the wiki |
+| `/comitia:ingest` | Adding material to the wiki — add → build the base → revise the related summaries |
+| `/comitia:problem` | Picking out what the records don't explain, and opening it in the Lab |
+| `/comitia:slack` | Posting to Slack — shows you the draft and posts **only once you approve** |
+| `/comitia:sync` | Pulling in right now rather than waiting for the hourly sync. The "sync status" line at the top of `recent`/`find` shows how fresh things are |
+
+Call them by name, or just say "organize this into the wiki" and Claude will reach for them.
+A skill carries only its one-line description (about 90 tokens) until it's actually used.
 
-직접 불러도 되고, **그냥 "이거 위키에 정리해"라고 말해도** Claude 가 알아서 꺼내 쓴다.
-평소에는 설명 한 줄(약 90토큰)만 들고 있다가 쓸 때 본문을 읽는다.
-새 판으로 올린 뒤에는 `comitia skills` 로 스킬만 바꿔 끼운다.
+After upgrading the package, run `comitia skills` to update the skills alone.
 
-## 명령
+## Commands
 
 | | |
 |---|---|
-| `comitia init [토큰]` | 한 번에 붙이기 — 로그인 + 워크스페이스 + AI 규칙 파일 |
-| `comitia init -g` | 규칙을 **모든 폴더**에 (`~/.claude` 등). 폴더마다 안 해도 된다 |
-| `comitia login <토큰>` | 토큰만 저장 (`~/.comitia/config.json`, 0600) |
-| `comitia whoami` | 지금 누구로 붙어 있나 |
-| `comitia companies` | 워크스페이스 목록 |
-| `comitia use <id 또는 이름>` | 기본 워크스페이스 |
-| `comitia list [접두어]` | 문서 목록 (`docs/`·`ledger/` 처럼 걸러서) |
-| `comitia search <낱말>` | 본문 검색 |
-| `comitia read <경로...>` | 문서 본문 |
-| `comitia graph` | 문서가 서로 어떻게 이어져 있는지 |
-| `comitia recent [개수]` | **정리 전 원본** — 슬랙·메일이 들어온 그대로 |
-| `comitia find <낱말>` | 원본에서 찾기 |
-| `comitia raw <id...>` | 원본 본문 |
-| `comitia rules` | 이 워크스페이스의 위키 규칙 — 쓰기 전에 먼저 |
-| `comitia skills` | Claude Code 스킬 설치·갱신 |
-| `comitia push <제목> <파일\|-\>` | 자료 넣기 — **쓰기 토큰 필요** |
-| `comitia build` | 원문·장부·표 만들기 (코드만, 0원) |
-| `comitia pending` | 요약이 필요한 원본 |
-| `comitia write <경로> <파일\|-\>` | 요약을 위키에 남기기 — **쓰기 토큰 필요** |
-| `comitia organize` | 정리 돌리기 — **쓰기 토큰 필요** |
-
-`-c <id>` 로 워크스페이스를 그때만 바꿀 수 있다.
-
-## 환경 변수
+| `comitia init [token]` | Connect in one go — sign-in + workspace + AI rules files |
+| `comitia init -g` | Put the rules in **every folder** (`~/.claude` and friends) |
+| `comitia login` | Connect by clicking Allow in the browser |
+| `comitia login --paste` | For a remote machine — paste the code shown in your browser |
+| `comitia login <token>` | Use an issued token directly (CI, scripts) |
+| `comitia logout` | Forget the stored token (`~/.comitia/config.json`, mode 0600) |
+| `comitia whoami` | How you're connected right now |
+| `comitia companies` | List your workspaces |
+| `comitia use <id or name>` | Set the default workspace |
+| `comitia list [prefix]` | List wiki documents (filter like `docs/`, `ledger/`) |
+| `comitia search <word>` | Search the wiki body text |
+| `comitia read <path...>` | Read documents |
+| `comitia graph` | How the documents link to each other |
+| `comitia recent [count]` | **Raw sources** — Slack and email exactly as they arrived |
+| `comitia find <word>` | Search the raw sources |
+| `comitia raw <id...>` | Full text of a source |
+| `comitia rules` | This workspace's wiki rules — **read these before writing** |
+| `comitia skills` | Install or update the Claude Code skills |
+| `comitia sync [slack\|tiro\|...]` | Pull in now, instead of waiting for the hourly sync — *write access* |
+| `comitia forget <id> <word...>` | Scrub a word from a source — it won't come back on the next sync — *write access* |
+| `comitia slack <channel> <file\|->` | Post to Slack through the connected bot — *write access* |
+| `comitia push <title> <file\|->` | Add a source — *write access* |
+| `comitia build` | Build the base — full texts, ledgers, tables (code only, no model cost) — *write access* |
+| `comitia pending` | Sources that still need summarizing |
+| `comitia write <path> <file\|->` | Save a summary to the wiki — *write access* |
+| `comitia organize` | Hand the organizing to Comitia's own AI — *write access* |
+
+`-c <id>` switches workspace for a single call. `comitia --help` lists everything, including the
+`--thread` / `--edit` / `--delete` flags on `comitia slack`.
+
+## Environment variables
 
 | | |
 |---|---|
-| `COMITIA_API` | 서버 주소 (기본 `https://z2o.kr/_/backend`) |
-| `COMITIA_TOKEN` | 토큰. 설정 파일보다 우선 — CI 에서 쓴다 |
-| `COMITIA_COMPANY` | 워크스페이스 id |
+| `COMITIA_API` | Server address (default `https://z2o.kr/_/backend`) |
+| `COMITIA_TOKEN` | Token. Takes priority over the config file — use this in CI |
+| `COMITIA_COMPANY` | Workspace id |
 
-옛 이름 `Z2O_API` · `Z2O_TOKEN` · `Z2O_COMPANY` 도 그대로 읽는다(새 이름이 우선).
+The old names `Z2O_API` · `Z2O_TOKEN` · `Z2O_COMPANY` are still read (the new ones win).
 
-## 옛 이름(z2o)에서 옮겨 올 때
+## Migrating from `z2o`
 
-`npm i -g comitia` 뒤 `comitia skills`(또는 `comitia init`) 한 번이면 된다. **다시 로그인할 필요는 없다.**
+`npm i -g comitia`, then `comitia skills` (or `comitia init`) once. **No need to sign in again.**
 
-- 설정은 `~/.comitia/` 에 둔다. 없으면 `~/.z2o/` · `~/.ztoo/` 를 읽어 그대로 옮겨 온다.
-- `z2o` 명령도 당분간 같은 것을 부른다 — 이미 심어 둔 규칙이 끊기지 않게.
-- 규칙 파일의 옛 `z2o:start` 블록은 `init` 이 새 블록으로 **갈아끼운다**(두 벌로 남지 않는다).
-- 스킬은 `~/.claude/skills/comitia/` 로 옮기고 옛 `~/.claude/skills/z2o/` 는 지운다 — `/z2o:*` 와 `/comitia:*` 가 함께 뜨지 않게.
-- 예전 `z2o-cli` 패키지는 `npm rm -g z2o-cli` 로 지운다. 안 지우면 `z2o` 명령이 두 패키지에 걸려 설치가 막힐 수 있다.
+- Config lives in `~/.comitia/`. If it isn't there, `~/.z2o/` and `~/.ztoo/` are read and carried over.
+- The `z2o` command still runs the same thing for now, so rules files you've already set up keep working.
+- `init` **swaps** an old `z2o:start` block for the new one — you won't end up with two.
+- Skills move to `~/.claude/skills/comitia/` and the old `~/.claude/skills/z2o/` is removed, so `/z2o:*` and `/comitia:*` don't both show up.
+- Remove the old package with `npm rm -g z2o-cli`. Leave it and the `z2o` command belongs to two packages, which can block the install.