@indigo-gr/claude-code-station 0.3.3 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] — 2026-11-14
+
+### Added
+- **repos.yml is a documented contract** — [`docs/design/repos-yml-schema.md`](docs/design/repos-yml-schema.md) now says which keys other tools may rely on, what they mean under `version: 1`, and how the format may change: while `version: 1` holds, keys are only added (never removed or given a new meaning) and readers ignore keys they do not know; a breaking change moves to `version: 2` with a transition period. Other tools keep their own values under `repos[].custom`. The recommended form is a block list with `name:` and `path:` directly under each item, which line-based readers can parse too; ccs always writes that form.
+- **`ccs doctor [--json]`** — tells a script or a GUI launcher whether ccs works here, without a terminal: Node (at least 22), tsx, ccs's own modules, better-sqlite3, fzf (at least 0.42.0), `claude` on `PATH`, `repos.yml` through ccs's checks, the layout line-based readers need, the cache and its schema version. Exit 0 works, 1 does not, 2 bad arguments, 3 could not tell; with `--json`, one JSON object with `schema_version`, `status`, `reasons` and every check's `name`, `status` and `code`. It prints no repo name or path and goes to no network. It writes nothing to ccs's config or cache folders — not even the `repos.yml` template or the cache when they are missing — and the temporary folder it uses in `TMPDIR` (for its time limit, and for tsx) is removed before it ends. It answers even when Node cannot load ccs's modules (a broken `package.json` above a copy install: exit 1, `invalid_package_config`).
+- **`ccs list --json [--with-paths]`** — the entries of `repos.yml` after ccs's checks, in file order, for tools that would otherwise parse the file themselves: name, label, description, icon, kind (`repo` or `group`), launch, lead, disabled, parent (the nesting the list shows), tags, and whether the folder exists. Paths only with `--with-paths`; never the launch commands or `custom`. No `repos.yml` is exit 4 (`config_missing`), a broken one exit 4 (`config_invalid`, with the check's word in `detail`).
+- **`ccs sessions --json [--project NAME] [--limit N] [--with-titles] [--no-scan]`** — past conversations per project, newest first, at most `N` each (default 5, up to 50): the UUID, when it was last active, and how many were left out. The first request's line (one line, at most 80 characters, secrets masked) only with `--with-titles`; never the summary, the folder or the conversation. It refreshes the cache the way opening the list does (not with `--no-scan`, not without a `repos.yml`).
+- **`ccs repo add PATH [--name NAME] [--description TEXT]` and `ccs repo remove NAME`** — add a folder under `$HOME` to `repos.yml`, or take an entry out, without editing the file. `add` checks the folder (under `$HOME` also after symlinks, exists, a folder, no shell metacharacters, not registered yet), names it after the folder unless `--name` is given (`-2`, `-3`… when taken), writes it at the end in the block form with the path as `~/…`, and creates a minimal `repos.yml` when there is none. `remove` never touches the folder, its conversations or the cache, and keeps at least one entry.
+- **`ccs config get` and `ccs config set [--repo NAME] KEY VALUE`** — read and change the settings a screen can offer: `defaults.ui`, `defaults.terminal`, `defaults.update_check`, and an entry's `label` and `description`. Launch commands and paths are not settable this way.
+- **`ccs open (--repo NAME | --session UUID) [--here | --new-window]`** — start Claude Code without the list, through the same checks as a picked row. `--here` (the default) runs it in this terminal and passes arguments after `--` on; `--new-window` (macOS) hands a one-shot launcher file to the terminal app named by `defaults.terminal` (for now `terminal`, the macOS Terminal) and returns at once. Unlike the list, `open` refuses a folder outside `$HOME` or one that is gone instead of starting in the current folder.
+- **`defaults.update_check: false`** in `repos.yml` stops the update check like `CCS_NO_UPDATE_CHECK` (the variable wins). For installs whose updates another tool manages.
+- **`defaults.terminal`** in `repos.yml`: the terminal app `ccs open --new-window` opens. Only `terminal` is accepted for now; other apps are added once their way of opening has been tried. `ccs doctor` checks it.
+- **`defaults.groups_dir`** (off unless set): a folder of group definition files kept by another tool. ccs reads five keys from each `*.json` in it (`version`, `id`, `label`, `kind`, `members[].path`), uses only `version: 1` and `kind: "logical"`, and lists the `repos.yml` entries whose `path` matches under a display-only header — after all projects in the classic look, after the `launch: false` headers in the simple look. ccs never writes there; broken files are skipped and counted by `ccs doctor` (`groups_dir`), and `ccs list --json` returns the groups in `groups[]`.
+- **Writing `repos.yml` is one path** for `repo add`, `repo remove`, `config set` and `ccs init --auto-discover`: one writer at a time (`repos.yml.lock`), the file checked before and after, the previous text in `repos.yml.bak`, written in place (a symlink stays a symlink), and put back when the written file fails ccs's checks. Ctrl-C during a write puts the previous text back (exit 130).
+- The JSON shape, exit codes and reason words of these commands are documented in [`docs/design/machine-interface.md`](docs/design/machine-interface.md) and versioned by `schema_version` (now `1.0.0`). Exit codes: 0 ok, 1 failed, 2 bad arguments, 3 could not tell, 4 missing prerequisite, 5 not found, 6 refused by a check, 7 partly done, 130 interrupted.
+
+### Changed
+- **`doctor`, `list`, `sessions`, `repo`, `config` and `open` are ccs commands when they come first.** Until now `ccs doctor` opened the list and started `claude doctor` in the picked project (the same for the other words). To pass one of these words on to the launched command, put a flag before it: `ccs --new doctor`. Only the first argument counts; everything else passes through as before.
+- **`disabled` and `scan` take only `true` or `false`**, like `launch` and `lead`. Any other value, a quoted string included, is now an error naming the key. **Check your repos.yml**: until now a quoted `disabled: "false"` or `scan: "false"` was read as *true*, so such an entry was hidden or not scanned; it now stops ccs with a message until the quotes are removed. A blank value (`disabled:` with nothing after it) is an error too.
+- **`ccs init --auto-discover` now takes a lock and checks `repos.yml` before adding to it**, through the same write path as `ccs repo add`: a file that already fails ccs's checks is no longer appended to (it used to be appended to, then put back).
+- **`ccs list --json` under a broken `package.json`** (a copy install below one Node cannot parse) answers exit 1 with the reason word `invalid_package_config`, the same word `doctor` and the list use (it said `internal_error`). The same for `sessions`, `repo`, `config` and `open`.
+- **`ccs init --auto-discover` refuses a one-line `repos:` list** (YAML flow style, for example `repos: [{name: a, path: ~/a}]`) before scanning, ends with exit code 1 and leaves the file unchanged. After the usual `🔍 Scanning $HOME for git repositories...` line it prints one line starting `[ccs-init] flow_style_repos:`. Rewrite the list in the block form and run it again.
+
+### Fixed
+- **ccs installed under a folder whose name has a space** (an app's `Application Support`, for example) did nothing: the list opened with no rows and exited 0. Each module compared its own URL with its path, and a space is written `%20` in a URL. The list, the preview, the scan, `ccs init` and the new commands now start from such a folder.
+- **The YAML parser's own warnings** (an unknown tag such as `!made-up` on a value) printed the offending line of `repos.yml` on stderr. The commands for scripts and tools no longer print them (the list prints them as before).
+- **No usable `TMPDIR`** (missing, or not writable): the commands for scripts and tools use `/tmp` instead, and answer with the usual JSON (before: empty stdout, exit 1, and `mktemp`'s message with the path).
+- **A check that timed out** in `ccs doctor` (`fzf --version` that never answers) printed bash's own `Terminated` line with the install path; it is no longer printed.
+- **ccs run in a folder below a broken `package.json`** stopped with `invalid_package_config` even when ccs itself was fine (Node read that file for tsx's preload). ccs's modules now start from ccs's own folder, so the list opens anywhere; only a broken `package.json` above ccs's own files still stops it. The line naming that file leaves the path out when it holds control characters or text-direction marks.
+- **A value that refers to itself** (a YAML anchor used inside itself, such as `disabled: &x [*x]`) crashed with a TypeError; it is now an error naming the entry (`entry_invalid`), like any other wrong value.
+- **A blank `description:` or `icon:`** (YAML null) showed the word `null`; it now counts as not set (no description, the default icon).
+- **The `custom` size error** says what is measured: the limit is 64,000 characters of the JSON form, not 64KB of bytes.
+- **A broken `package.json` above ccs** — Node refused to load ccs's modules, and ccs opened an empty list (or suggested `ccs --refresh`, which could not help) and exited 0. The package now carries its own `bin/package.json`, so a `package.json` above it is never read. A copy install (`install.sh`) can still sit under one; then ccs stops with exit code 1 and one line naming the file, with the reason word `invalid_package_config`, in both looks.
+
+### Security
+- **Release tags are signed** — from this version on, each `vX.Y.Z` tag in this repository carries an SSH signature, and a release is not published unless the tag it is built from is signed by an expected key.
+
+## [0.4.1] — 2026-11-08
+
+0.4.0 was tagged in the work repository but never published; its changes ship in 0.4.1.
+
+### Added
+- **Version and copyright on screen** — both looks show `ccs v<version>` and `Copyright © INDIGO GROUP LLC.` in the frame's top border (fzf's border label: after the title in the simple look, new in the classic look). The label costs no list row and survives `change-header`. On a narrow terminal the label shortens instead of running over the frame's corners: the title goes first (simple), then the word `Copyright` (`© INDIGO GROUP LLC.`), and the version stays. `ccs --help` prints the copyright too.
+- **Update notice** — when npm's latest is newer than the running version, the classic look prints one line with the upgrade command above the picker. The simple look says so in the list's frame and prints the command after the picker closes. No notice for a prerelease on either side, or when nothing is known about the latest version.
+  - **What goes over the network**: at most once a day (an hour after a failed attempt), a background process sends one HTTPS GET to `https://registry.npmjs.org/-/package/%40indigo-gr%2Fclaude-code-station/dist-tags`. It carries no ccs version, repo, session or machine details. See "Update check" in the README.
+  - **It cannot slow or stop ccs**: the launcher only reads the last answer from `~/.cache/ccs/update-check` and never waits for the request, which has a 3-second limit. Offline, ccs behaves as before.
+  - **Turn it off** with `CCS_NO_UPDATE_CHECK=1` (no request, the cache is not read). `CCS_UPDATE_REGISTRY` points the check at another registry.
+- `author` in `package.json`.
+
+### Changed
+- The copyright holder is now INDIGO GROUP LLC. (`LICENSE`, `package.json`, README, on screen). The license stays MIT.
+- `tput` is no longer required.
+- **Works on npm 12 as is, and needs Node 22** — npm 12 blocks dependency install scripts by default, also for a global install, so with `better-sqlite3` 11 the plain `npm install -g` reported success and left a `ccs` that could not start (this applies to earlier versions of ccs). `better-sqlite3` 13 ships prebuilt native modules, so no script is needed. It requires Node 22 or newer, and so does ccs now (`engines`, `install.sh`, README). On a platform with no prebuilt module, `ccs` says so. An existing `state.db` is reused.
+
+### Fixed
+- **Terminal width** — `tput cols 2>/dev/null` inside `$()` answered 80 at any width, so the classic look's short guide line for narrow terminals never appeared. ccs now asks the terminal with `stty size` (an exported `COLUMNS` wins), so terminals under 80 columns get that short guide line.
+- **Copy install** — without a `package.json` next to `bin/` (`install.sh`, the README's manual install), `ccs` exited with code 2 and no message before doing anything. It now runs as `ccs v0.0.0-dev`, and a copy install gets no update check or notice.
+- **Another package's version** — `ccs` took its version from whatever `package.json` sat above `bin/`, so a copy install could show another project's version. It now reads the file only when its `name` is this package; otherwise, or when the file cannot be read or parsed, it runs as `ccs v0.0.0-dev`.
+- **Simple look**: the no-match message stayed only some of the time, because the guide line overwrote it; it now stays until the search matches again.
+- A scan that fails on opening the cache no longer leaves its lock behind (later scans said "another scan is in progress" for 5 minutes and hid the real error).
+- The install instructions add `~/.claude/scripts` to the end of `PATH`, so it cannot shadow system commands. If you followed the earlier instruction, you may want to change that line in your shell profile.
+
+### Security
+- **A repos.yml field can no longer choose the command** — a tab, newline or unit separator in `icon` moved the row's columns, so picking that repo (or one of its sessions) ran what the field named instead of the repo's command. Icons are now cleaned wherever they are drawn, `ccs-list` drops a row of the wrong shape, and `bin/ccs` refuses a command with shell metacharacters or control characters.
+- **Wildcards in `command`** are passed as written (`claude *` gets the argument `*`). Splitting into words is unchanged.
+- **A session's cwd** with a `..` segment is no longer taken from the session file, so it can neither open outside `$HOME` nor reach the clipboard through `^Y`.
+- **The preview hides secrets before cutting text**, so a key across the cut no longer shows its beginning (messages, `cwd`, `gitBranch`, `version`).
+- **The scan stays inside a repo**: a file in `handoff/` or `pendings/`, or the folder itself, is not read when it is a symlink out of the repo. A symlink that stays inside the repo still works.
+- **The scan runs nothing a repo configures**: git runs with `core.fsmonitor` off and no hooks, and a scan no longer rewrites a repo's index.
+- **Display text** loses C1 controls and text-direction marks too; `description`, `tags` and `icon` are now cleaned in the classic preview as well. Emoji and Japanese text are unchanged.
+
 ## [0.3.3] — 2026-11-06
 
 ### Changed

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Daiske Watanabe
+Copyright (c) 2026 INDIGO GROUP LLC.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,7 +1,7 @@
 # Claude Code Station — ccs
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Node 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
+[![Node 22+](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
 
 A fast, fzf-powered launcher and session picker for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Pick a project to launch fresh **or** resume any past session — all from a single fuzzy finder, across every repo you own.
 
@@ -38,7 +38,7 @@ A fast, fzf-powered launcher and session picker for [Claude Code](https://docs.a
 
 ### Prerequisites / 前提条件
 
-- [Node.js](https://nodejs.org/) **20+**
+- [Node.js](https://nodejs.org/) **22+**. `better-sqlite3` ships prebuilt modules for macOS and Linux (glibc, musl) on x64 and arm64; anywhere else it has to be built from source (not tested) / それ以外の環境はソースから作る必要がある（未確認）
 - [fzf](https://github.com/junegunn/fzf) **≥ 0.42.0** — fuzzy finder (the `change-header` binding used by the copy-toast requires 0.42+; released Aug 2023). With **0.45+** Enter on a group header (`launch: false`) keeps the list open; on older fzf it just closes ccs without launching anything / 0.45 以上なら、グループ見出しの上で Enter を押してもリストは開いたまま（それより古い fzf では何も起動せずに閉じる）
   - The friendlier look (`ui: simple`, below) needs **fzf ≥ 0.61.0** (`--ghost`; the frame and labels need 0.58+). On an older fzf ccs opens the classic look and says so in one line / やさしい見た目（`ui: simple`）は fzf 0.61.0 以上。古い fzf ではいつもの見た目で開き、1 行で知らせる
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI (`claude`)
@@ -62,7 +62,7 @@ npm install -g @indigo-gr/claude-code-station
 #### From GitHub (latest unreleased) / GitHub直接（未リリース版を使いたい時）
 
 ```bash
-npm install -g github:indigo-gr/claude-code-station
+npm install -g --allow-git=root github:indigo-gr/claude-code-station
 ```
 
 ### Copy install (checkout) / コピーインストール
@@ -84,7 +84,7 @@ cp bin/ccs bin/ccs-*.ts bin/ccs-*.sh ~/.claude/scripts/
 chmod +x ~/.claude/scripts/ccs ~/.claude/scripts/ccs-delete.sh
 
 # Add to ~/.zshrc or ~/.bashrc
-export PATH="$HOME/.claude/scripts:$PATH"
+export PATH="$PATH:$HOME/.claude/scripts"
 ```
 
 ---
@@ -205,6 +205,27 @@ repos:
   └ 🌐 Web team  ‹Studio› │    Website web/
 ```
 
+### Groups from other tools (`groups_dir`) / ほかの道具のグループ定義
+
+Projects that live in unrelated folders can be listed together under one header, following group definition files another tool keeps. Off unless you set it. / フォルダがばらばらのプロジェクトを、ほかの道具が持つグループの定義ファイルに従って 1 つの見出しの下に並べる。書かなければ使わない。
+
+```yaml
+defaults:
+  groups_dir: ~/tools/groups   # a folder of *.json files; must be under $HOME
+```
+
+Each `*.json` directly in that folder (in name order, at most 200, each up to 256 KB) is read for five keys only, and nothing is ever written there: / フォルダの直下の `*.json` から 5 つのキーだけを読み、ccs はこのフォルダに書かない。
+
+```json
+{ "version": 1, "id": "team-x", "label": "Team X", "kind": "logical",
+  "members": [{ "path": "~/x/beta" }, { "path": "~/w/alpha" }] }
+```
+
+- Only `version: 1` and `kind: "logical"` are used. A `physical` group is skipped: its projects already nest by `path` (`launch: false` headers). / 使うのは `version: 1` と `kind: "logical"` だけ。`physical` はフォルダの入れ子で並ぶので読まない
+- `members[].path` (`~` expanded) is matched to the `path` of your `repos.yml` entries; the header lists the matches in the file's order, with their own names and icons. Members not in `repos.yml` are not shown. A project may appear both in its own place and under the header. / `members[].path` を `repos.yml` の `path` と比べ、当たった項目をその順に並べる（名前とアイコンは `repos.yml` の物）
+- In the classic look the headers come after all projects; in the simple look after the `launch: false` headers. Enter on a header does nothing. / classic は全部のプロジェクトの後、simple は `launch: false` の見出しの後
+- Broken or unknown files are skipped, never stopping the list; `ccs doctor` counts them (`groups_dir`: `group_files_skipped`), and `ccs list --json` gives the groups in `groups[]`. The scan reads the folder, so changes show after the next scan (`ccs --refresh` or `Ctrl-R`). / 読めないファイルは飛ばす（一覧は止めない）。`ccs doctor` が数を出す
+
 ### Friendlier look (`ui: simple`) / やさしい見た目
 
 For people who are new to the terminal, `defaults.ui: simple` switches ccs to a full-screen look with rounded frames and plain Japanese words. The default (`classic`) does not change. / ターミナルに慣れていない人向けに、`defaults.ui: simple` で全画面・角の丸い枠・日本語の言葉の見た目に切り替わる。既定（`classic`）は変わらない。
@@ -266,6 +287,7 @@ Notion:   ✅ abc123
 | `--ui=simple` / `--ui=classic` | Friendlier look / classic look for this launch (wins over `CCS_UI` and `defaults.ui`) / この起動だけ見た目を切り替える |
 | `--help` / `-h` | Help / ヘルプ |
 | `--version` / `-v` | Version / バージョン |
+| `doctor` / `list` / `sessions` / `repo` / `config` / `open` as the first argument | Commands for scripts and tools, see [below](#for-scripts-and-tools--スクリプトや道具から呼ぶ) / スクリプト向けの口（最初の引数の時だけ） |
 | _anything else_ | Passed through to the launched command / 起動コマンドへパススルー |
 
 ### Keyboard / キーボード
@@ -317,6 +339,50 @@ ccs .
 
 ---
 
+## For scripts and tools / スクリプトや道具から呼ぶ
+
+Commands for GUI launchers, scripts and other tools. They never open fzf, read stdin or ask anything, so they run without a terminal (`ccs open --here` alone starts Claude Code in the terminal it runs in). They do not go to the network (no update check) and never create the `repos.yml` template. The read commands (`doctor`, `list`, `config get`) write nothing to ccs's config or cache folders; they may put a temporary file in `TMPDIR` and remove it before they end. `sessions` refreshes the cache the way opening the list does; `repo add`, `repo remove` and `config set` write `repos.yml`. The full contract is [`docs/design/machine-interface.md`](docs/design/machine-interface.md). / GUI のランチャー・スクリプト・ほかの道具が呼ぶ口。fzf を開かず、標準入力を読まず、問いかけないので、端末が無くても動く（`ccs open --here` だけは、走らせた端末で Claude Code を起こす）。ネットに出ず（更新の確認もしない）、`repos.yml` のひな形を作らない。読む口（`doctor`・`list`・`config get`）は設定とキャッシュの置き場に何も書かない（`TMPDIR` に一時の物を作ることがあり、終わる時に消す）。`sessions` は一覧を開く時と同じにキャッシュを更新し、`repo add`・`repo remove`・`config set` は `repos.yml` を書く。約束の全体は上の資料。
+
+| Command | What it does |
+|---|---|
+| `ccs doctor [--json]` | Does ccs work here? Checks Node, tsx, ccs's own modules, better-sqlite3, fzf, `claude`, `repos.yml`, the cache and the terminal app for `open --new-window`. Exit 0 works, 1 does not, 2 bad arguments, 3 could not tell. / ccs がここで動くか。終了コード 0 動く・1 動かない・2 引数の誤り・3 確かめられない |
+| `ccs list --json [--with-paths]` | The entries of `repos.yml` after ccs's checks, in file order: name, label, description, icon, kind (`repo` / `group`), launch, lead, disabled, parent, tags, and whether the folder exists. Paths only with `--with-paths`. / ccs の検証を通した `repos.yml` の一覧。パスは `--with-paths` の時だけ |
+| `ccs sessions --json [--project NAME] [--limit N] [--with-titles] [--no-scan]` | Past conversations per project, newest first, at most `N` (default 5, up to 50) each: the session UUID and when it was last active, plus `more` (how many were left out). Titles (the first request, one line, at most 80 characters) only with `--with-titles`; never the summary, the folder or the conversation. / プロジェクトごとの前の会話（新しい順・既定 5 件）。題は `--with-titles` の時だけ |
+| `ccs repo add PATH [--name NAME] [--description TEXT] [--with-paths] [--json]` | Adds a folder under `$HOME` to `repos.yml` (at the end, in the block form, the path written as `~/…`). The name defaults to the folder's name (`-2`, `-3`… when taken). Creates a minimal `repos.yml` when there is none. / `$HOME` の下のフォルダを `repos.yml` に足す |
+| `ccs repo remove NAME [--json]` | Takes the entry out of `repos.yml`. The folder, its conversations and the cache are not touched. The last entry cannot be removed. / 台帳から外す（フォルダは消さない） |
+| `ccs config get [--with-paths] [--json]` | The settings `config set` can change, with their current values and the values allowed. / 変えられる設定の今の値と、受ける値 |
+| `ccs config set [--repo NAME] KEY VALUE [--json]` | Changes one setting: `defaults.ui` (`classic` / `simple`), `defaults.terminal` (`terminal`, or `""` to unset), `defaults.update_check` (`true` / `false`), or with `--repo` an entry's `label` / `description` (`""` removes it). Launch commands, paths and the other keys are not settable here — edit the file for those. / 決まった値から選ぶ設定と、項目の表示名・説明だけを変える |
+| `ccs open (--repo NAME \| --session UUID) [--here \| --new-window] [--terminal APP] [--json] [-- ARGS…]` | Starts Claude Code without the list, through the same checks as a picked row (the folder under `$HOME`, the command's characters, the session ID's form). `--here` (the default) runs it in this terminal; `--new-window` (macOS) opens a new window of `defaults.terminal` and returns at once. Unlike the list, `open` never falls back to the current folder: it refuses. / 一覧を開かずに起こす。`--here` はこの端末で、`--new-window`（macOS）は新しいウィンドウで |
+
+- **These words are commands only as the first argument**: `doctor`, `list`, `sessions`, `repo`, `config`, `open`. Until 0.4.x they went to the launched command (`ccs doctor` opened the list and started `claude doctor`). To pass one on, put a flag first: `ccs --new doctor`. / 最初の引数の時だけ ccs の口になる。起動するコマンドに渡したい時は前にフラグを置く
+- **With `--json`**, stdout carries exactly one JSON object, on failure too, with `schema_version`, `product_version`, `command`, `status` and `reasons` (`[{ "vocab", "code" }]`). Match on the exit code and on those words; messages on stderr are for people and may change. Without `--json`, `repo` and `config set` print nothing on stdout and one line on stderr. / `--json` の時は標準出力に JSON を 1 つだけ出す（失敗の時も）。機械は終了コードと語で分ける
+- **What is never printed**: secrets, the commands repos launch with, `custom`, user and host names. `doctor` prints no repo name or path at all — only words, counts and versions. Paths only with `--with-paths`, conversation titles only with `--with-titles`. / 秘密・起動コマンド・`custom`・ユーザー名とホスト名は出さない。パスは `--with-paths`、会話の題は `--with-titles` の時だけ
+- **How `repos.yml` is written** — one writer at a time (`repos.yml.lock`), the previous text kept in `repos.yml.bak`, the file written in place (a symlinked `repos.yml` stays a symlink), checked again, and put back when that check fails. A one-line `repos:` list (`repos: [ … ]`) is not added to (`flow_style_repos`). Names and paths are written only when they need no YAML quotes (`needs_quoting` otherwise). Comments and the order of keys are kept; spaces before an end-of-line comment may be reduced to one. / 書く時はロック・`.bak`・その場で書く・書いた後に検証・落ちたら元に戻す
+- **`ccs open --new-window`** writes a one-shot launcher file in `TMPDIR` (it deletes itself when it starts) and hands it to the terminal app with `open -a`; no AppleScript, so no Automation permission is asked for. The new window runs `ccs open --here` with the same checks. Choose the app first: `ccs config set defaults.terminal terminal` (macOS Terminal; other apps are added once their way of opening has been tried). The exit code of `--here` after Claude Code started is Claude Code's own; scripts should use `--new-window`. / 端末のアプリは先に `defaults.terminal` で決める。`--here` の起こした後の終了コードは Claude Code の物
+- **Called from a GUI app**, `PATH` is often short and `node` or `claude` is not found (`dependency_missing`). Pass the user's shell `PATH` to ccs. / GUI のアプリから呼ぶと `PATH` が短く `node` が見つからないことがある。利用者のシェルの `PATH` を渡す
+
+| Exit | `status` | Meaning |
+|:---:|---|---|
+| 0 | `ok` | Done (`doctor`: ccs works) |
+| 1 | `failed` | Failed (`doctor`: ccs does not work); also `config_locked`, `config_changed` — try again |
+| 2 | `usage` | Bad arguments (`list` / `sessions` without `--json` too) |
+| 3 | `unverifiable` | Could not tell (no permission, a check timed out) |
+| 4 | `missing_prerequisite` | Not run: something it needs is missing (no `repos.yml`, a broken one, no cache, no terminal, no Node) — not used by `doctor` |
+| 5 | `not_found` | No such entry or session |
+| 6 | `rejected` | Refused by a check (outside `$HOME`, a name already taken, a value not allowed, …) |
+| 7 | `partial` | Written, failed the check, and could not be put back: the previous text is in `repos.yml.bak` |
+| 130 | `interrupted` | Stopped by Ctrl-C (a write in progress is undone) |
+
+```bash
+ccs doctor --json | jq -r '.status, (.checks[] | select(.status != "ok") | "\(.name): \(.code)")'
+ccs list --json | jq -r '.repos[] | select(.kind == "repo" and (.disabled | not)) | .name'
+ccs sessions --json --project studio-web --limit 3 | jq -r '.projects[].sessions[].uuid'
+ccs repo add ~/projects/studio/web --json | jq -r '.status'
+ccs open --repo studio-web --new-window
+```
+
+---
+
 ## State cache / 状態キャッシュ
 
 ccs keeps a SQLite cache at `~/.cache/ccs/state.db` (or `$XDG_CACHE_HOME/ccs/state.db`) with repo metadata, git state badges, session summaries, and handoff/pending file lists.
@@ -331,6 +397,18 @@ Schema details: [`docs/design/sqlite-schema.md`](docs/design/sqlite-schema.md).
 
 ---
 
+## Update check / 更新の確認
+
+ccs tells you when npm has a newer version. The classic look prints one line with the upgrade command above the picker. The simple look says so in the list's frame and prints the command after the picker closes. / npm に新しいバージョンがあると知らせる。classic は一覧の上に上げ方を 1 行、simple は枠に知らせを出し、閉じた後に上げ方を出す。
+
+- **What is sent, and where** — one HTTPS `GET https://registry.npmjs.org/-/package/%40indigo-gr%2Fclaude-code-station/dist-tags`, at most once a day (an hour after a failed attempt). It carries no ccs version, repo, session or machine details; the registry sees only the request itself, your IP address and Node's default User-Agent. / 送るのは公開情報を読む GET が 1 日に 1 回まで（失敗の後は 1 時間後）。ccs のバージョン・リポジトリ・会話・マシンの情報は送らない。npm が受け取るのはリクエストそのもの・IP アドレス・Node の既定の User-Agent だけ
+- **Never in the way** — the check runs in the background with a 3-second limit and its answer is used on the next launch; startup only reads `~/.cache/ccs/update-check` (or `$XDG_CACHE_HOME/ccs/update-check`). Offline, or when the answer is unusable, ccs behaves as before. HTTP proxy settings are not used, so behind a proxy the check simply fails quietly. / 確認は裏で行い、結果は次の起動で使う。起動を遅らせず、オフラインでも止まらない。プロキシの設定は使わないので、プロキシの内側では確認が静かに失敗する
+- **When there is no notice** — when you are on the latest version or newer, when npm's latest is a prerelease, and when your own version is a prerelease or a copy install (`0.0.0-dev`). A failed check shows no notice of its own, but a version found by an earlier check is still reported. / 最新かそれより新しい時・npm の latest がプレリリースの時・手元がプレリリースかコピーインストールの時は知らせない。確認の失敗だけでは知らせないが、前回までに見つけたバージョンは知らせる
+- **Turn it off** — set `CCS_NO_UPDATE_CHECK=1` (any non-empty value), or put `update_check: false` under `defaults:` in `repos.yml` (`ccs config set defaults.update_check false`): no request, and the cache is not read. The variable wins over the file (`update_check: true` does not turn a set variable back on). Useful when another tool manages ccs's updates. / `CCS_NO_UPDATE_CHECK=1`（空でない値）か `repos.yml` の `defaults.update_check: false` で止まる。通信せず、キャッシュも読まない
+- **Another registry** — `CCS_UPDATE_REGISTRY=https://registry.example.com` asks that server instead. / `CCS_UPDATE_REGISTRY` で問い合わせ先を替えられる
+
+---
+
 ## Migration from ccr v0.1.x / ccr v0.1.x からの移行
 
 Existing sessions are stored under `~/.claude/projects/*/*.jsonl` — **nothing to migrate manually**. ccs auto-discovers them on first scan.
@@ -403,4 +481,10 @@ Issues and PRs welcome. See [`REVIEW.md`](REVIEW.md) for review standards and [`
 
 ## License / ライセンス
 
-MIT. See [LICENSE](LICENSE).
+MIT. Copyright © INDIGO GROUP LLC. See [LICENSE](LICENSE). / ライセンスは MIT、著作権者は INDIGO GROUP LLC.
+
+The version on screen leads to everything about that release / 画面のバージョンから、そのリリースの中身をたどれる:
+
+- **Source** — git tag `vX.Y.Z` in [indigo-gr/claude-code-station](https://github.com/indigo-gr/claude-code-station/tags) / ソースは同じ番号の tag
+- **Changes** — the `[X.Y.Z]` section of [CHANGELOG.md](CHANGELOG.md) / 変更点は CHANGELOG の同じ番号の節
+- **Terms** — [LICENSE](LICENSE) at that tag / 配布条件はその tag の LICENSE