open-claude-p 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,260 @@
+# Changelog
+
+All notable changes to **open-claude-p** are documented here.
+
+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).
+
+---
+
+## [1.1.1] — 2026-05-19
+
+Post-1.1.0 fixes driven by Cosmica integration testing. Several of
+these are essentially the 1.1.0 release "actually working" — the
+1.1.0 surface was correct on paper but a handful of subtle parser
+and default-value bugs kept the new behaviour from landing in
+practice.
+
+### Fixed
+
+- **Trust dialog auto-accept regressed silently for two distinct
+  reasons.**
+  - The driver's `❯` chevron pattern matched both the real input
+    box and the trust dialog's "currently-selected" row
+    (`❯ 1. Yes, I trust this folder`). `prompt-box-shown` fired
+    on the dialog row, the await chain proceeded to the prompt
+    write, and the trailing `\r` confirmed whichever option was
+    highlighted — silently dropping the user message. Pattern is
+    now `/^[❯›❮‹](?:$|\s(?!\d+\.\s))/` and a write-time guard
+    refuses to send when `dialogState` is in a blocked state.
+  - The trust dialog text is rendered with cursor-positioning
+    escapes between words rather than real space bytes; after the
+    ANSI strip the buffer reads `Quicksafetycheck` (no spaces) and
+    the `/Quick safety check/i` pattern never matched. Result: the
+    dialog rendered in ~250 ms but the watcher never fired, the
+    driver fell back to writing the prompt after
+    `OCP_PROMPT_BOX_WAIT_MS`, and the trailing CR confirmed "Yes"
+    in the still-open dialog. The watcher now strips ANSI before
+    pattern-matching and the patterns accept `\s*` between every
+    word.
+- **`OCP_PROMPT_BOX_WAIT_MS` default 6 s → 30 s.** Environments
+  with many MCP servers or plugins need 8–25 s before the input
+  box renders. 6 s was tripping the timeout before claude had
+  even shown the trust dialog. Short-circuited the moment
+  `prompt-box-shown` fires, so the common-case latency is
+  unchanged.
+- **`dangerouslySkipPermissions` is now ON by default across
+  EVERY surface** — not just the CLI. The 1.1.0 commit only
+  flipped the CLI's default and left `createDriver().runOneShot()`
+  and `createChatClient()` on the pre-1.1 `false`, so anything
+  using the SDK directly (the bundled sample chat, third-party
+  wrappers) still hung on the first tool call. Sample server's
+  redundant env-gate is dropped accordingly.
+- **End-of-reply marker no longer flagged as
+  "prompt-injection".** The 1.0/1.1 instruction text used the
+  word "token": `Append the literal token ⟦OCP_END:xxx⟧ ...`.
+  The model's safety classifier treated "include this token in
+  your reply" as an access-token / API-key exfiltration attempt
+  and sometimes appended a `prompt injection attempt detected`
+  warning to the user-facing reply. Reworded to "end-of-reply
+  marker" and framed as `ocp wrapper's plumbing` so claude
+  recognises it as harness infrastructure rather than hostile
+  injection.
+
+### Changed
+
+- **postinstall skips the shebang rewrite when running inside a
+  git checkout** (detected by the presence of `.git/` next to
+  `package.json`). The rewrite is meant for end-user installs from
+  the npm tarball; in a dev `git clone + npm link` setup it
+  otherwise overwrote `#!/usr/bin/env node` with the developer's
+  absolute node path on every `npm install` / `npm test`, showing
+  up as a noisy working-tree diff. Consumer installs unaffected.
+
+---
+
+## [1.1.0] — 2026-05-18
+
+`ocp` 1.1 reshapes the CLI defaults around the assumption that
+**callers are programs, not humans**, and adds a JSONL-first
+extraction path so PTY chrome can no longer leak into responses.
+
+### Added
+
+- **JSONL-first response extraction.** `claude` writes the completed
+  assistant turn to `~/.claude/projects/<cwd>/<sid>.jsonl`. The driver
+  now reads that authoritative source first and falls back to
+  PTY-extracted text only when the JSONL is unavailable
+  (`--no-session-persistence`, missing file, etc.). Cleans up
+  statusline / HUD plugin / `[Pasted text #N]` leakage at the source.
+  Result: `diagnostics.textSource` is `"jsonl"` or `"pty"`,
+  `diagnostics.recoveredFromJsonl` is `true` when a PTY-side abort
+  was overridden by a successful JSONL read.
+- **Paste-mode handling for large prompts.** New driver option
+  `pasteMode` (`auto` | `chunk` | `bracket` | `raw`) with env
+  `OCP_PASTE_MODE`. Prompts above `OCP_PASTE_THRESHOLD` bytes
+  (default 1024) are written in ~256-char chunks with brief delays
+  so the upstream TUI's paste detector does not coalesce them into
+  a `[Pasted text]` placeholder that swallows the trailing
+  carriage-return. New exported helper `writePromptToSession`.
+- **Stall-cause detector.** New `src/diagnostics/stall-cause.js`
+  scans the captured PTY tail at abort time and returns a stable
+  machine-readable identifier (`mcp-auth-required`,
+  `trust-required`, `theme-picker`, `login-expired`,
+  `tool-permission`, `paste-not-submitted`) plus an actionable
+  English hint, surfaced as `detected: <kind>` on stderr.
+- **`TUI_CHROME_PATTERNS` / `TUI_CHROME_INLINE_PATTERNS`** exported
+  from `open-claude-p/chat`. Line-anchored vs inline-fragment
+  pattern lists used by `cleanResponse`. External callers building
+  alternative scrubbers can reuse the list.
+- **`OCP_NO_SESSION_PERSISTENCE` env binding** on the CLI. Previously
+  only the flag `--no-session-persistence` was honoured.
+- **`OCP_DUMP_STALL=1` opt-in** for the PTY screen tail in abort
+  errors. The default suppresses the tail because it can echo the
+  caller's prompt (a real concern for RAG-injected prompts containing
+  user data).
+- **`OCP_NO_AUTO_ACCEPT_TRUST=1` opt-out** for folder-trust
+  auto-accept.
+- **`OCP_NO_SKIP_PERMS=1` opt-out** for the new default
+  `--dangerously-skip-permissions`.
+- **CHANGELOG.md** (this file).
+- **`ocp-sample` companion CLI.** Downloads the demo chat-UI app
+  (the `sample/` subtree) from the upstream git repo on demand so
+  the published tarball stays small. Subcommands `init` (clone +
+  npm install into a user-chosen directory), `start` (detached server
+  with PID/log file), `stop`, `status`. Pretty TTY output (braille
+  spinner, success/failure marks, end-of-init banner with the running
+  URL); auto-falls-back to plain text when `NO_COLOR=1` or stderr
+  isn't a TTY. Designed for npx-first use:
+  `npx -p open-claude-p ocp-sample init demo`.
+
+### Changed
+
+- **`--dangerously-skip-permissions` / `dangerouslySkipPermissions`
+  is now the default ON across EVERY surface** — `ocp` CLI,
+  `createDriver().runOneShot()`, `createChatClient()`, and the
+  `sample/` server. Rationale: `ocp` is a PTY automation library; an
+  interactive permission prompt that wants a human y/n hangs forever
+  — every Bash / Edit / Write / MCP / WebSearch call breaks without
+  this flag. The pre-1.1 library default of `false` was the cause
+  of nearly every "the SDK silently hangs on tool use" report.
+  Opt out per surface:
+  - CLI: `OCP_NO_SKIP_PERMS=1` (env)
+  - `createChatClient({ dangerouslySkipPermissions: false })`
+  - `runOneShot({ dangerouslySkipPermissions: false })`
+  Pre-1.1 users with `OCP_DEFAULT_SKIP_PERMS=1` exported see no
+  change; the env is now a no-op.
+- **Folder-trust dialog is auto-accepted by default.** Same
+  rationale: a `claude` dialog asking "Do you trust this folder?"
+  is unanswerable from PTY automation. Opt out via
+  `OCP_NO_AUTO_ACCEPT_TRUST=1`.
+- **Abort completions no longer leak PTY noise.**
+  When `completionReason` is in
+  `{timeout, interactive-required, trust-required, cancelled, write-failed, upstream-exited}`:
+  - The `text` adapter writes nothing to stdout (was: accumulated
+    PTY junk).
+  - The `stream-json` adapter emits only `system/init` +
+    `result.subtype=error` (was: also an `assistant` frame with the
+    PTY-extracted blob).
+  - The `printStalledOutput` PTY tail is omitted by default
+    (was: emitted to stderr including the caller's prompt back-echo).
+- **`cleanResponse` scrubs HUD chrome.** Additional patterns added
+  for claude-hud counters, MCP-auth banners, paste placeholders,
+  and `Context ░░░░ N%` meters. Inline fragments are removed
+  without dropping the surrounding line.
+- **Permissive CLI defaults note in README** — `Recommended one-time
+  setup` reduced to "None required". The post-1.0 opt-in envs
+  (`OCP_AUTO_ACCEPT_TRUST=1`, `OCP_DEFAULT_SKIP_PERMS=1`) are now
+  effectively no-ops; users keep them in `~/.zshrc` without effect,
+  or remove them.
+
+### Fixed
+
+- **macOS realpath in `~/.claude/projects/<encoded-cwd>/` lookup.**
+  Earlier versions used `path.resolve(cwd)` which is a string
+  operation that does not follow symlinks. On macOS `/var`, `/tmp`,
+  and other launchd-owned paths redirect to `/private/<…>`; `claude`
+  itself resolves symlinks when picking its JSONL directory, so the
+  driver was looking up a directory the upstream never wrote to.
+  Net effect: any session under a `/var/` or `/tmp/` cwd had its
+  session id capture fail silently, so `claudeSessionId` stayed
+  `null`, `--resume` was never threaded between turns, and every
+  call spawned a fresh conversation with no memory of the previous
+  one. Fixed via `realpath` in `src/index.js` (driver), 
+  `src/chat/index.js` (`readSessionText`), and `src/print-mode.js`.
+- **Stale daemon socket on launch.** A SIGKILL'd daemon left
+  `~/.ocp/d-*.sock` behind; the next launch's `server.listen` failed
+  with `EADDRINUSE` and the client gave up and fell back to direct
+  mode. The daemon now pre-unlinks the path before binding.
+- **`readSessionText` strict-mode fallback.** When the caller passes
+  a `sessionId`, the function no longer scans neighbouring JSONLs in
+  the project dir on miss. Under concurrent load (another claude
+  session active in the same cwd, an editor's built-in agent, …)
+  the scan picked the most-recently-modified file and returned
+  someone else's transcript as the "model's response". Strict mode
+  returns `null` on miss instead.
+- **GUI-app install of `ocp`.** The postinstall script rewrites the
+  shebang in `bin/cli.js` from `#!/usr/bin/env node` to the absolute
+  path of the node binary that ran the install (`process.execPath`).
+  Without this, launching `ocp` from a launchd-managed GUI process
+  (Electron, Tauri, native Cocoa) — which gets `/usr/bin:/bin` as
+  PATH and never sees nvm / homebrew node — fails with
+  `env: node: No such file or directory` before our code runs.
+- **`stream-json` adapter** now opens with `system/init` even when
+  no session id was captured (regression-proofs consumer parsers
+  expecting the init line as the first event regardless of
+  completion outcome).
+
+### Security
+
+- **Default CLI permission posture is permissive.** Documented
+  prominently in README under "Recommended one-time setup". The
+  flip is correct for personal workstations and controlled service
+  accounts whose prompts are authored by the operator, but the
+  CLI is unsafe to wire up to untrusted prompt input (public
+  chatbots, prompt-injection-prone RAG, …) without
+  `--allowed-tools`, `OCP_NO_SKIP_PERMS=1`, or per-call validation
+  on top.
+- **`printStalledOutput` redacts prompt back-echo** when emitted.
+  When the captured PTY tail is included (now opt-in via
+  `OCP_DUMP_STALL=1` or `--debug`), lines that overlap the caller's
+  prompt by ≥24 characters are replaced with
+  `[prompt echo redacted]` so RAG context glued into the prompt
+  does not leak into error logs.
+
+---
+
+## [1.0.0] — 2026-XX-XX
+
+Initial release.
+
+### Added
+
+- `ocp` CLI binary — argv-compatible shim for `claude -p`. `-p` /
+  `--print` are implicit; `ocp "…"` is equivalent to
+  `claude -p "…"`.
+- Output adapters: `text` (default), `json`, `stream-json` (NDJSON).
+- Driver (`createDriver`, `runOneShot`) — node-pty-backed PTY layer
+  that drives the interactive `claude` CLI and parses the output
+  stream to produce headless-mode-equivalent results.
+- Chat SDK (`createChatClient`) — high-level wrapper with
+  per-conversation state, file-backed transcript store, skill
+  invocation, and JSONL session-file extraction.
+- Warm daemon under `~/.ocp/d-<hash>.sock` so subsequent calls in
+  the same cwd skip the 2.5 s PTY warmup. Idle timeout via
+  `OCP_DAEMON_IDLE_MS` (default 10 min).
+- Hard timeout via `OCP_MAX_RESPONSE_MS` (default 24 h).
+- First-response watchdog `OCP_FIRST_RESPONSE_MS` (default 20 s)
+  for fast `interactive-required` failure when an unrecognised
+  dialog blocks the prompt box.
+- Folder-trust auto-accept opt-in via `OCP_AUTO_ACCEPT_TRUST=1`.
+- Permission-bypass opt-in via `OCP_DEFAULT_SKIP_PERMS=1`.
+- Default `--allowed-tools` pre-approval for `WebSearch` and
+  `WebFetch` (opt out: `OCP_NO_DEFAULT_TOOLS=1`).
+- Default `--append-system-prompt` encouraging tool use (opt out:
+  `OCP_NO_DEFAULT_PROMPT=1`).
+- Localised READMEs: Korean, Japanese, Chinese.
+
+[1.1.1]: https://github.com/empty-user77/open-claude-p/releases/tag/v1.1.1
+[1.1.0]: https://github.com/empty-user77/open-claude-p/releases/tag/v1.1.0
+[1.0.0]: https://github.com/empty-user77/open-claude-p/releases/tag/v1.0.0

package/README.ja.md

@@ -14,11 +14,15 @@
 
 > **核心的な違い**：`claude -p` は Claude Code の非対話モードで内部 API を通じて動作しますが、特定のプラン/環境では使用できません。`open-claude-p` は実際の TUI クライアントを PTY で実行し、出力ストリームを解析することで同じ結果を得ます。
 
+**バージョン履歴**: [CHANGELOG.md](./CHANGELOG.md) を参照。
+
 ---
 
 ## 目次
 
 - [インストール](#インストール)
+- [推奨ワンタイム設定](#推奨ワンタイム設定)
+- [`claude -p` との既知の差分](#claude--p-との既知の差分)
 - [CLI の使い方](#cli-の使い方)
 - [デーモン（セッション持続）](#デーモンセッション持続)
 - [ライブラリ API](#ライブラリ-api)
@@ -68,6 +72,88 @@ claude --version
 
 ---
 
+## 推奨ワンタイム設定
+
+**1.1+ では不要です。** CLI のデフォルトは既に permissive：
+フォルダ信頼ダイアログの自動承認 ON、`--dangerously-skip-permissions` ON。
+`npm install -g open-claude-p` の後、そのまま `ocp "..."` が動きます。
+
+claude の通常のパーミッションプロンプトを戻したい場合（PTY 自動化では
+答えられないので全てのツール呼び出しが hang します）、opt-out 環境変数で
+無効化：
+
+```bash
+export OCP_NO_AUTO_ACCEPT_TRUST=1   # "Do you trust this folder?" ダイアログで abort
+export OCP_NO_SKIP_PERMS=1          # claude の通常パーミッションプロンプトを復元
+```
+
+> ⚠️ デフォルト CLI 設定では、`ocp "…"` 呼び出し 1 回でプロンプトの内容に
+> 従って Bash、Write、Edit などのツールを確認なしで実行できます。個人の
+> ワークステーションや、運用者がプロンプトを直接書く管理されたサービス
+> アカウントには適切ですが、**信頼できない入力**（公開チャットボット、
+> プロンプトインジェクションを受けやすい RAG など）がプロンプトに混ざる
+> 環境では絶対にそのまま使わないでください。`--allowed-tools`、
+> `OCP_NO_SKIP_PERMS=1`、または呼び出しごとの検証で表面を絞ってください。
+>
+> ライブラリのデフォルト（`createDriver` / `createChatClient`）は引き続き
+> 保守的 — ライブラリ呼び出し元が明示的に権限スキップを opt-in します。
+
+全環境変数一覧は [docs/cli-reference.md](./docs/cli-reference.md) 参照。
+
+---
+
+## `claude -p` との既知の差分
+
+`ocp` は argv 互換の shim であり、`claude -p` とバイト単位で同一の出力を
+保証するわけではありません。同じフラグでも以下のケースでは動作が異なるため、
+コンシューマパイプラインに統合する際は事前に考慮してください：
+
+- **`~/.claude.json` の状態に敏感.** PTY レイヤーは spawn ごとに完全な
+  TUI バナーを描画するため、"1 MCP server needs auth · /mcp" や
+  "auto mode unavailable"、プラグイン更新通知なども表示されます。
+  `claude -p` はこういうのは描画しませんが、`ocp` は通り抜けるだけです
+  （`⏺` か spinner イベントが見えるまで待機）。通知が多いと
+  first-response latency が `OCP_FIRST_RESPONSE_MS`（デフォルト 20s）を
+  超えて spurious な `interactive-required` abort が出ることがあります。
+  env を増やすか、使わない MCP/プラグインを `~/.claude.json` から
+  削除してください。
+
+- **1KB 超のプロンプトは chunked write 経路.** 単一の多 KB write は claude
+  の paste 検出を起動し、末尾の CR が paste content として消費されて
+  プロンプトが永遠に送信されない回帰がありました。1.1+ では約 256 文字
+  単位で短い delay 付き chunked write — 50–500 ms の追加 latency。
+  以前の動作が必要なら `OCP_PASTE_MODE=raw`、TUI 入力ボックス自体を回避
+  したいなら `--input-format=stream-json`。
+
+- **セッション永続化はデフォルト ON.** 各ターンで `~/.claude/projects/<encoded-cwd>/`
+  に JSONL セッションファイルを書きます。サーバ側で毎ターン会話履歴を
+  再構築するステートレス統合では `OCP_NO_SESSION_PERSISTENCE=1`
+  （または `--no-session-persistence`）で無効化してください。無効化しないと
+  dead JSONL が溜まり `--continue` の探索が無関係な隣接ファイルを掴むことが
+  あります。
+
+- **デーモンは呼び出し元終了後も残る.** `~/.ocp/d-<hash>.sock` でデーモンが
+  detach され、同じ cwd の次回呼び出しが 2.5s warmup をスキップ。
+  `OCP_DAEMON_IDLE_MS`（デフォルト 10 分）で idle 時に自動終了。
+  「子プロセスは親と一緒に死ぬべき」と期待するコンシューマアプリは
+  `OCP_NO_DAEMON=1` か idle タイムアウトを短くしてください。
+
+- **Print mode（`--print-mode` / `OCP_PRINT_MODE=1`）のみ PTY を完全に
+  バイパス** し、実質 `claude --print` + argv pass-through。MCP サーバ、
+  ツール権限プロンプト、その他あらゆるインタラクティブ surface は使えません
+  — fallback や upstream parity テスト用途のみ。
+
+- **Abort 時、出力アダプタは PTY ノイズを通さない.** completionReason が
+  `timeout` / `interactive-required` / `trust-required` / `cancelled` /
+  `write-failed` / `upstream-exited` のいずれかなら、`text`・`stream-json`
+  アダプタは累積された PTY コンテンツをモデル応答として emit しません。
+  `stream-json` は `result.subtype=error` + `completion=<reason>` のみを
+  emit、短い stderr エラーメッセージに `detected: <kind>` のヒントを出力。
+  `claude -p` は黙って失敗するか手元のテキストを echo していた部分とは
+  異なります。
+
+---
+
 ## CLI の使い方
 
 このパッケージは単一バイナリ **`ocp`** をインストールします。
@@ -493,7 +579,26 @@ const nextPrompt = `前の回答：${result.text}\n\n次のステップに進ん
 
 ## 環境変数
 
-### ドライバーオプション
+### よく使うもの
+
+| 変数 | 説明 |
+|------|------|
+| `OCP_NO_AUTO_ACCEPT_TRUST=1` | 1.1 デフォルト（フォルダ信頼の自動承認）を無効化。ダイアログが出たら abort させたいとき。 |
+| `OCP_NO_SKIP_PERMS=1` | 1.1 CLI デフォルト（`--dangerously-skip-permissions`）を無効化。claude の通常の権限プロンプトが復活しますが、PTY 自動化では答えられず全ツール呼び出しが hang します。 |
+| `OCP_NO_SESSION_PERSISTENCE=1` | ターンごとの JSONL セッションファイル書き込みを無効化。毎ターンサーバ側で履歴を再構築するステートレス統合用。 |
+| `OCP_NO_LIVE=1` | stderr のライブスピナーを無効化 |
+| `OCP_NO_META=1` | 末尾の meta フッター（`⏱ … · 🔧 …`）を非表示 |
+| `OCP_NO_DAEMON=1` | 毎回新しい PTY（warm デーモンを使わない） |
+| `OCP_DAEMON_IDLE_MS` | warm デーモンが呼び出しの間に生き残る時間。デフォルト `600000`（10 分）。 |
+| `OCP_MAX_RESPONSE_MS` | ハードタイムアウト、デフォルト `86400000`（24 時間） |
+| `OCP_FIRST_RESPONSE_MS` | プロンプト送信後 N ms 以内に進展がなければ fail-fast、デフォルト `20000` |
+| `OCP_PROMPT_BOX_WAIT_MS` | 入力 chevron(`❯`) の出現を待つ最大時間、デフォルト `15000`（heavy hook/MCP ロード時は増やす） |
+| `OCP_PASTE_MODE` | 大きいプロンプトを TUI に送る方法：`auto`（デフォルト、しきい値超で chunked）、`chunk`（常に chunk）、`bracket`（xterm bracketed paste マーカー）、`raw`（1.1 以前の atomic write） |
+| `OCP_PASTE_THRESHOLD` | `auto` モードでの chunked write 発動バイト数しきい値。デフォルト `1024` |
+| `OCP_DUMP_STALL=1` | abort stderr メッセージに PTY 画面 tail を含める。デフォルトでは含めません（呼び出し側プロンプトが echo される可能性のため opt-in）。 |
+| `OCP_CLAUDE_BIN` | upstream `claude` バイナリのパス、デフォルト `'claude'` |
+
+### ドライバーオプション（ライブラリ呼び出し元向け）
 
 | 変数 | 対応オプション | デフォルト |
 |------|-------------|-----------|
@@ -502,7 +607,6 @@ const nextPrompt = `前の回答：${result.text}\n\n次のステップに進ん
 | `OCP_REUSE_WARMUP_MS` | `reuseWarmupMs` | `200` |
 | `OCP_IDLE_MS` | `idleMs` | `1500` |
 | `OCP_PRE_IDLE_MS` | `preIdleMs` | `8000` |
-| `OCP_MAX_RESPONSE_MS` | `maxResponseMs` | `60000` |
 | `OCP_POOL_SIZE` | `poolSize` | `0` |
 | `OCP_POOL_MAX_AGE_MS` | `poolMaxAgeMs` | `600000` |
 
@@ -560,114 +664,80 @@ OCP_NO_DAEMON=1 ocp "一度だけ実行"
 
 ## サンプルアプリ
 
-`sample/` ディレクトリには ocp を使って構築した Web ベースのチャット UI が含まれています。
+`open-claude-p/chat` を使った小さな Web チャット UI です。ソースは
+upstream の git repo の `sample/` 配下にあり、**npm tarball には
+バンドルされません** — 代わりにパッケージが `ocp-sample` というコンパニオン
+CLI を一緒に配布し、必要なときにオンデマンドでダウンロードします。これにより
+publish された install を軽量に保ちつつ、デモは 1 行で試せます。
 
-### 実行
+### クイックスタート
 
 ```bash
-cd sample
-node server.js
-# → http://localhost:3000
-```
-
-### サンプルアプリの構造
+npm install -g open-claude-p          # 1 回だけ
+ocp-sample init demo                   # ダウンロード + npm install
+cd demo
+ocp-sample start                       # → http://localhost:3000
 
-```
-sample/
-  server.js        Express サーバー — ocp ドライバーをラップ、SSE ストリーミング
-  data/
-    conversations.json  会話履歴（自動生成）
-  public/
-    index.html     チャット UI
-    app.js         クライアントサイド JavaScript
-    style.css      スタイルシート
+# 終わったら:
+ocp-sample stop
 ```
 
-### サンプルサーバー API
+### `init` の動作
 
-| エンドポイント | メソッド | 説明 |
-|------------|--------|------|
-| `/api/conversations` | GET | 会話一覧 |
-| `/api/conversations/:id` | GET | 会話詳細（全メッセージ） |
-| `/api/conversations/:id` | DELETE | 会話を削除 |
-| `/api/chat` | POST | メッセージ送信（SSE ストリーミング） |
-| `/api/monitor` | GET | PTY イベントモニター（SSE） |
-| `/api/skills` | GET | `~/.claude/skills/` のスキル一覧 |
-| `/api/processes` | GET | 進行中のリクエスト一覧（`id`、`prompt`、`elapsedMs`） |
-| `/api/processes/:id` | DELETE | 特定のリクエストを中断（`all` で全て中断） |
+1. upstream repo を一時ディレクトリに shallow-clone。
+2. `sample/` サブツリーを `./<name>/`（デフォルト `./ocp-sample/`）にコピー。
+3. コピーされた `package.json` の dev 用 `"open-claude-p": "file:.."` dep
+   を実際の semver 範囲に書き換え — この CLI 自身のバージョンに pin する
+   ので `ocp-sample` が scaffold したデモは常に同梱バージョンと一致します。
+4. `npm install --no-audit --no-fund` を実行。
+5. `npm link open-claude-p` を試行 — グローバル link が無ければ silent
+   no-op、ある場合は registry のコピー代わりにローカル dev ソースを link
+   で使います。
 
-### `/api/chat` SSE イベント
+### サブコマンド
 
-チャットリクエスト（`POST /api/chat`）は Server-Sent Events でレスポンスをストリーミングします：
+| コマンド | 説明 |
+|----------|------|
+| `ocp-sample init [name]` | `./<name>/`（デフォルト `ocp-sample`）にデモをダウンロード + install。ディレクトリが存在して空でない場合は拒否。 |
+| `ocp-sample start [--port=N]` | CWD から `node server.js` を detached で起動。PID を `.ocp-sample.pid` に、stdout/stderr を `.ocp-sample.log` に append。`PORT` env でも指定可。 |
+| `ocp-sample stop` | 実行中の PID に SIGTERM（5 秒猶予の後 SIGKILL）。 |
+| `ocp-sample status` | `running` / `stopped` + PID + URL を出力。 |
 
-```js
-// クライアントリクエスト
-const resp = await fetch('/api/chat', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({
-    message: '東京の天気を教えて',
-    conversationId: null,    // null で新しい会話を開始
-    skillName: 'my-skill',   // オプション：~/.claude/skills/ のスキル名
-  }),
-});
+### cwd に作られるファイル
 
-// SSE イベントの種類
-{ type: 'spinner', label: 'Searching the web...' }  // 処理中の状態
-{ type: 'text', text: 'こんにちは...' }              // ストリーミングテキスト（チャンク）
-{ type: 'error', error: 'エラーメッセージ' }          // エラー
-{
-  type: 'done',
-  conversationId: 'uuid',   // 会話 ID（保存済み）
-  text: '完全な最終レスポンス',  // 完全な最終テキスト（JSONL からのクリーンな markdown）
-  isNew: true,              // 新しい会話かどうか
-  meta: {
-    elapsedMs: 4200,        // 経過時間（ms）
-    inputTokens: 1500,      // 入力トークン（キャッシュ含む）
-    outputTokens: 320,      // 出力トークン
-    costUsd: 0.0042,        // コスト（USD）
-    tools: ['WebSearch'],   // 使用したツール
-  }
-}
+```
+demo/
+├── .ocp-sample.pid    実行中サーバの PID（start が書き込み、stop が削除）
+├── .ocp-sample.log    detach されたサーバの stdout/stderr（append）
+├── server.js          Express + ocp/chat
+├── package.json
+├── public/            静的チャット UI（index.html, app.js, style.css）
+└── node_modules/      `npm install` の結果
 ```
 
-### サンプルの Markdown パース
-
-サンプルアプリ（`sample/public/app.js`）は `renderMarkdown()` 関数を通じて `result.text` を HTML に変換します。
-
-**このパースコードはサンプル専用です。** 実際のプロジェクトでは：
-- Web：`marked`、`markdown-it` など
-- ターミナル：`cli-markdown`、`terminal-link` など
-- React：`react-markdown`
-- LLM 入力：そのまま使用
-
-### プロセスマネージャー（`ocp-ps`）
-
-サンプルアプリには `/api/processes` API を使って進行中のリクエストを一覧表示・キャンセルできる CLI ツールが含まれています。
-
-```bash
-cd sample
+### 環境変数
 
-node ocp-ps.js              # 進行中のリクエスト一覧
-node ocp-ps.js kill <id>    # 特定のリクエストを中断
-node ocp-ps.js kill all     # 全て中断
-node ocp-ps.js watch        # 1 秒ごとに自動更新
-```
+| 変数 | 効果 |
+|------|------|
+| `PORT` | `start` のデフォルトポート(3000)を変更。`--port=N` と同じ。 |
+| `NO_COLOR=1` | ANSI 色とスピナーを無効化 — CI やログ取得に有用。 |
+| `OCP_SAMPLE_NO_TTY=1` | `NO_COLOR=1` と同じ。 |
+| `OCP_SAMPLE_REPO` | `init` が clone する upstream git URL を変更。テスト用。 |
 
-> **注意**：`ocp-ps` はサンプルアプリの HTTP API（`/api/processes`）を使うサンプル実装です。  
-> ocp ライブラリを使って独自のサーバーを構築する際は、同じパターンでプロセス管理 API を実装できます。
+### デモが見せる機能
 
-### スキル呼び出し（`/スキル名`）
+デモは意図的に小さく作られていますが、ほとんどのコンシューマアプリが必要と
+する SDK の部分を実際に通過させています：
 
-チャット入力欄で `/` を入力すると `~/.claude/skills/` のスキルがドロップダウンで表示されます。
+- **会話の永続化** — `chat.send` + `~/.claude/projects/<cwd>/<sid>.jsonl`
+- **SSE ストリーミング** — `assistant-text` / `spinner` / `done` をブラウザへ
+- **スキル呼び出し** — `/<skill-name>` を打つと `~/.claude/skills/` の `SKILL.md` を注入
+- **プロセス管理** — 進行中のリクエスト一覧・abort を `/api/processes` 経由で
+- **Markdown レンダリング** — チャットバブルで fenced code、見出し、リストなどを処理する小さいクライアントサイドレンダラ
 
-```
-ユーザー入力：/my-skill この PRD を分析して関連リポジトリを見つけて
-             ↓
-サーバー：SKILL.md の内容を appendSystemPrompt として注入
-             ↓
-Claude：スキルの指示に従って実行
-```
+`init` 後の `demo/server.js` を見ると全 surface があります — 「Express
+アプリに `open-claude-p/chat` をラップする方法」 の正式な参考実装として
+扱ってください。
 
 ---