okstra 0.123.0 → 0.124.0

package/docs/for-ai/skills/okstra-container-build.md

@@ -1,89 +1,89 @@
 # okstra-container-build AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-container-build/SKILL.md`](../../../skills/okstra-container-build/SKILL.md)
+- Skill source: [`skills/okstra-container-build/SKILL.md`](../../../skills/okstra-container-build/SKILL.md)
 - container CLI wrapper: [`src/commands/inspect/container.mjs`](../../../src/commands/inspect/container.mjs)
 - container runtime: [`scripts/okstra_ctl/container.py`](../../../scripts/okstra_ctl/container.py)
 - container registry: [`scripts/okstra_ctl/container_registry.py`](../../../scripts/okstra_ctl/container_registry.py)
 - stage integration gate: [`scripts/okstra_ctl/stage_targets.py`](../../../scripts/okstra_ctl/stage_targets.py)
 
-## 목적
+## Purpose
 
-`okstra-container-build`는 implementation task worktree의 `docker-compose.yml`을 이용해 사용자 테스트용 container group을 관리한다. okstra는 compose group에 task/run trace label을 붙이고, tmux watcher pane으로 로그/상태를 관찰한다.
+`okstra-container-build` manages a user-test container group using the `docker-compose.yml` in an implementation task worktree. okstra labels the compose group with the task/run trace and observes logs/status through a tmux watcher pane.
 
 ## sub-command
 
-| Sub-command | 역할 | side effect |
+| Sub-command | Role | side effect |
 |---|---|---|
-| `up` | implementation stages를 task worktree에 통합하고 `docker compose up -d`, healthcheck poll, watcher pane attach | container 생성/시작, watcher pane 생성 |
-| `status` | label query 기반 running container와 watcher metadata 확인 | 읽기 |
-| `logs` | watcher findings dir와 watcher entries 안내 | 읽기 |
-| `stop-watcher` | watcher/tail tmux panes만 회수 | container 유지, pane 제거 |
-| `down` | label query로 container group 제거, orphan watcher panes 회수 | container 종료/제거 |
+| `up` | Integrate the implementation stages into the task worktree, then `docker compose up -d`, poll healthchecks, attach the watcher pane | create/start containers, create watcher pane |
+| `status` | Check running containers (by label query) plus watcher metadata | read |
+| `logs` | Point at the watcher findings dir and watcher entries | read |
+| `stop-watcher` | Reap the watcher/tail tmux panes only | keep containers, remove panes |
+| `down` | Remove the container group by label query, reap orphan watcher panes | stop/remove containers |
 
 ## Preflight
 
-단일 호출:
+Single call:
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-project setup이 없으면 `/okstra-setup` 안내 후 멈춘다. Docker daemon이 필요하다. Docker connection error가 나오면 Docker Desktop/daemon을 시작하라고 안내하고, 직접 Docker를 시작하지 않는다.
+If the project is not set up, point to `/okstra-setup` and stop. A Docker daemon is required. On a Docker connection error, tell the user to start Docker Desktop/daemon; do not start Docker yourself.
 
-## task-key 해석
+## task-key resolution
 
-대부분 sub-command는 full task-key가 필요하다.
+Most sub-commands need a full task-key.
 
-1. full task-key가 있으면 그대로 사용.
-2. bare task-id는 resolver 사용:
+1. If a full task-key is given, use it as-is.
+2. For a bare task-id, use the resolver:
 
 ```bash
 okstra resolve-task-key <task-id> --project-root <projectRoot> --json
 ```
 
-3. multiple match면 후보를 보여주고 선택 받는다.
-4. `down --all`만 task-key 없이 실행할 수 있다.
+3. On multiple matches, show the candidates and let the user pick.
+4. Only `down --all` can run without a task-key.
 
 ## intent routing
 
-명확한 동사:
+Clear verbs:
 
-- "띄워", "올려", "up": `up`
-- "상태", "status": `status`
-- "로그", "logs": `logs`
-- "watcher 멈춰", "stop-watcher": `stop-watcher`
-- "내려", "down", "종료": `down`
+- "bring up/deploy", "up": `up`
+- "status": `status`
+- "logs": `logs`
+- "stop watcher", "stop-watcher": `stop-watcher`
+- "tear down", "down": `down`
 
-애매하면 full facet list를 보여주고 직접 입력 option을 둔다. 여러 facet이 한 메시지에 있으면 Step 0은 한 번만 실행하고 sub-command를 순차 실행한다.
+If ambiguous, show the full facet list and offer an Enter directly option. When multiple facets are in one message, run Step 0 once and execute the sub-commands sequentially.
 
 ## up
 
-실행:
+Run:
 
 ```bash
 okstra container up --project-root <projectRoot> --task-key <task-key>
 ```
 
-전제:
+Preconditions:
 
-- task는 implementation worktree가 registry에 있어야 한다.
-- worktree root에 `docker-compose.yml`이 있어야 한다.
-- approved plan의 모든 stage가 `done`이어야 한다. partial stage 상태를 완성 task처럼 deploy하지 않는다.
+- The task must have an implementation worktree registered in the registry.
+- The worktree root must contain a `docker-compose.yml`.
+- Every stage of the approved plan must be `done`. Do not deploy a partial-stage state as if it were a complete task.
 
-실패 메시지 처리:
+Handling failure messages:
 
-- registry에 task worktree가 없다는 메시지: implementation phase를 먼저 실행하라고 말한다.
-- compose file 없음: CLI 메시지를 그대로 보여준다.
-- `final-verification(whole-task): stage N not done`: 해당 stage를 implementation으로 끝내야 한다고 말한다.
-- healthcheck 실패: failing service와 CLI가 제공한 `docker compose ... logs` line을 그대로 전달한다.
+- Message that the task worktree is not in the registry: tell the user to run the implementation phase first.
+- No compose file: show the CLI message verbatim.
+- `final-verification(whole-task): stage N not done`: tell the user to finish that stage via implementation.
+- healthcheck failure: relay the failing service and the `docker compose ... logs` line the CLI provides, verbatim.
 
-성공하면 stdout JSON을 파싱해 services, watcher pane, published ports를 요약한다. 이후 관리는 `okstra container status <task-key>`와 `down <task-key>`로 한다고 안내한다. 띄운 뒤 *무엇을 확인할지*는 implementation 리포트의 §5.7.9 Manual User Test (Draft)를 가리킨다 — 그 단계와 기대 결과가 이 빌드의 수동 테스트 스크립트다.
+On success, parse the stdout JSON and summarize services, watcher pane, and published ports. Tell the user that management from here is via `okstra container status <task-key>` and `down <task-key>`. For *what to verify* once it is up, point to the implementation report's §5.7.9 Manual User Test (Draft) — those steps and expected results are the manual test script for this build.
 
 ## status
 
-실행:
+Run:
 
 ```bash
 okstra container status --project-root <projectRoot> --task-key <task-key>
@@ -92,14 +92,14 @@ okstra container status --project-root <projectRoot> --task-key <task-key>
 stdout JSON:
 
 - `projectName`: compose project name
-- `containers`: run-trace label로 찾은 running containers
-- `watchers`: registry의 watcher metadata
+- `containers`: running containers found by run-trace label
+- `watchers`: watcher metadata from the registry
 
-alive 여부는 `containers` label query가 authoritative다. watcher registry는 lag할 수 있다. `containers`가 비어 있으면 group이 실행 중이 아니라고 말하고 `up`을 제안한다.
+The `containers` label query is authoritative for whether it is alive. The watcher registry can lag. If `containers` is empty, say the group is not running and offer `up`.
 
 ## logs
 
-실행:
+Run:
 
 ```bash
 okstra container logs --project-root <projectRoot> --task-key <task-key>
@@ -111,49 +111,49 @@ service scope:
 okstra container logs --project-root <projectRoot> --task-key <task-key> --service <service>
 ```
 
-stdout JSON의 `watchersDir`, `watchers`를 보여준다. live stream은 file이 아니라 tmux watcher pane에 있다. raw compose logs가 필요하면 `status`에서 `projectName`을 확인한 뒤 사용자가 `docker compose -p <projectName> logs -f <service>`를 실행할 수 있다고 안내한다.
+Show the stdout JSON's `watchersDir` and `watchers`. The live stream is in the tmux watcher pane, not a file. If raw compose logs are needed, get `projectName` from `status`, then tell the user they can run `docker compose -p <projectName> logs -f <service>`.
 
 ## stop-watcher
 
-실행:
+Run:
 
 ```bash
 okstra container stop-watcher --project-root <projectRoot> --task-key <task-key>
 ```
 
-watcher/tail panes만 제거하고 containers는 유지한다. stdout JSON의 `reapedPanes`, `note`를 요약한다. 사용자가 containers까지 내리려는 의도면 `down`으로 라우팅한다.
+Remove only the watcher/tail panes and keep the containers. Summarize the stdout JSON's `reapedPanes` and `note`. If the user actually intends to bring the containers down, route to `down`.
 
 ## down
 
-단일 task:
+Single task:
 
 ```bash
 okstra container down --project-root <projectRoot> --task-key <task-key>
 ```
 
-프로젝트 전체:
+Whole project:
 
 ```bash
 okstra container down --project-root <projectRoot> --all
 ```
 
-단일 task down은 task-key 해석 후 실행해도 된다. `--all`은 프로젝트의 모든 okstra container group을 내리므로 실행 전 사용자 확인을 받는다.
+A single-task down is fine to run after resolving the task-key. `--all` takes down every okstra container group in the project, so confirm with the user before running it.
 
-stdout JSON의 `downed`, `orphanPanesReaped`를 보고한다. 각 `projectName`과 회수된 panes를 표시한다.
+Report the stdout JSON's `downed` and `orphanPanesReaped`. Show each `projectName` and the reaped panes.
 
-## 출력 규칙
+## Output rules
 
-- stdout JSON이 source of truth다.
-- raw `docker` 명령으로 second-guess하지 않는다. CLI가 실패했고 사용자가 manual fallback을 요청한 경우만 예외다.
-- resolved task-key를 heading이나 첫 줄에 표시한다.
-- CLI failure message는 remediation line을 포함해 그대로 보여준다.
-- container/service state는 JSON 값을 normalize하지 않고 보여준다.
+- The stdout JSON is the source of truth.
+- Do not second-guess it with raw `docker` commands. The only exception is when the CLI failed and the user asked for a manual fallback.
+- Show the resolved task-key in the heading or on the first line.
+- Show CLI failure messages verbatim, including the remediation line.
+- Show container/service state as the JSON values, without normalizing.
 
-## 금지 패턴
+## Forbidden patterns
 
-- Docker daemon을 직접 시작하려고 하기.
-- `up` 실패 원인을 추측해서 compose를 수정하기.
-- partial stage task를 deploy 가능한 것으로 포장하기.
-- watcher registry만 보고 container alive라고 판단하기.
-- `down --all`을 사용자 확인 없이 실행하기.
-- raw docker query로 CLI 결과를 임의로 덮어쓰기.
+- Trying to start the Docker daemon yourself.
+- Guessing the cause of an `up` failure and editing the compose file.
+- Dressing up a partial-stage task as deployable.
+- Judging a container as alive from the watcher registry alone.
+- Running `down --all` without user confirmation.
+- Overriding the CLI result arbitrarily with a raw docker query.

package/docs/for-ai/skills/okstra-graphify.md

@@ -0,0 +1,64 @@
+# okstra-graphify AI Manual
+
+## Sources
+
+- Skill source: [`skills/okstra-graphify/SKILL.md`](../../../skills/okstra-graphify/SKILL.md)
+- Graph core (CLI): [`scripts/okstra_ctl/graphify_cmd.py`](../../../scripts/okstra_ctl/graphify_cmd.py)
+- Node wrapper: [`src/commands/graphify.mjs`](../../../src/commands/graphify.mjs)
+
+## Purpose
+
+`okstra-graphify` builds and queries a **knowledge graph** over the project's own okstra memory (the final reports, `decisions/*.md`, `glossary.md`, and briefs under `<projectRoot>/.okstra`). The corpus is **fixed** to `.okstra` and the outputs land at `<projectRoot>/.okstra/graph/` — the CLI enforces both, so this skill takes no user path argument and never touches files outside `.okstra/`.
+
+- Docs-only. There is no code AST extraction here (that is the standalone `/graphify`).
+- Distinguish it from the arbitrary-code / non-okstra folder graph (`/graphify`), single-task inspection (`okstra-inspect`), and rollup (`okstra-rollup`).
+
+## Sub-commands
+
+| Sub-command | What it does |
+|---|---|
+| `build` | Extract entities/relationships from `.okstra` docs (parallel subagent dispatch), then assemble the graph + report + HTML |
+| `query` | BFS/DFS traversal over the graph to answer a broad question |
+| `path` | Shortest path between two named concepts |
+| `explain` | Plain-language explanation of one node and its connections |
+| `wiki` | Agent-crawlable wiki (`index.md` + one article per community) |
+| `mcp` | A stdio MCP server exposing the graph to other agents (opt-in — additionally needs `pip install mcp`) |
+
+## Preflight
+
+A single Bash call starting with the literal token `okstra` (not wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=`/`||`/`&&`/`npx`):
+
+```bash
+okstra preflight --runtime claude-code --json
+```
+
+`ok:true` → carry `projectRoot` as a literal string. Every `okstra graphify` call passes `--project-root <projectRoot>` (**REQUIRED**, no cwd injection — a bare `okstra graphify build` is a usage error). `ok:false` → first check once whether the user pointed at a specific project directory; if it is still `ok:false`, point to `/okstra-setup` and stop. On `unknown command: preflight`, the `okstra` on PATH is older than the skill — point to `npm i -g okstra@latest` and stop.
+
+## build (the core division of labor)
+
+Two parts: **semantic extraction** (subagents read `.okstra` docs and write chunk JSON) → **assemble** (the CLI does clustering and output generation).
+
+1. Detect the corpus: `find <projectRoot>/.okstra -type f -name '*.md' -not -path '*/graph/*'`. If zero, stop.
+2. Semantic extraction: **you MUST use the Agent tool** (reading files one-by-one is forbidden — far slower). Split into chunks of 20-25 files and **dispatch in parallel, once per chunk in a single response**, with `subagent_type="general-purpose"` fixed (`Explore` is read-only, cannot write chunk files, and silently drops results). Each subagent writes `<projectRoot>/.okstra/graph/.chunks/chunk-NN.json`. It MUST fill in EXTRACTED/INFERRED/AMBIGUOUS + `confidence_score`.
+3. Assemble: `okstra graphify build --project-root <projectRoot>` — merges `graph/.chunks/*.json` and writes `graph.json`, `GRAPH_REPORT.md`, `graph.html`. On a `no extraction chunks` error, the subagents did not write their files — re-dispatch.
+
+After a successful build, paste **only** the God Nodes / Surprising Connections / Suggested Questions sections of `GRAPH_REPORT.md` (not the whole file), then offer to trace the single most interesting question via `query`.
+
+## query / path / explain / wiki / mcp
+
+```bash
+okstra graphify query "<question>" --project-root <projectRoot>
+okstra graphify path "<ConceptA>" "<ConceptB>" --project-root <projectRoot>
+okstra graphify explain "<NodeName>" --project-root <projectRoot>
+okstra graphify wiki --project-root <projectRoot>
+okstra graphify mcp --project-root <projectRoot>
+```
+
+`query`/`path`/`explain`/`wiki`/`mcp` **require a built graph** — if the CLI says none exists, run `build` first. `mcp` additionally needs `pip install mcp` and is long-running (the user stops it with Ctrl+C). After doc changes, re-run `build` to re-extract.
+
+## Output Rules
+
+- Be concise, in Korean, unless the user requests otherwise.
+- Outputs go under `<projectRoot>/.okstra/graph/`, in project-relative paths where possible.
+- **Never invent an edge** — if unsure, it is AMBIGUOUS. Never hide cohesion/confidence scores.
+- Say plainly when a fact is not in the graph. Quote `source_file`/`source_location`.