okstra 0.123.0 → 0.124.0

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

@@ -1,81 +1,81 @@
 # okstra-inspect AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
+- Skill source: [`skills/okstra-inspect/SKILL.md`](../../../skills/okstra-inspect/SKILL.md)
 - CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
 - context-cost CLI: `src/commands/inspect/context-cost.mjs`
 - time-report CLI: `src/commands/inspect/time-report.mjs`
 - log-report CLI: `src/commands/inspect/log-report.mjs`
 - error-report CLI: `src/commands/inspect/error-report.mjs`
-- container는 별도 스킬: [`okstra-container-build.md`](okstra-container-build.md)
+- container is a separate skill: [`okstra-container-build.md`](okstra-container-build.md)
 
-## 목적
+## Purpose
 
-`okstra-inspect`는 okstra read-side 작업의 단일 진입점이다. 대부분은 읽기 전용이지만 두 예외가 있다.
+`okstra-inspect` is the single entry point for okstra read-side work. Most of it is read-only, with two exceptions.
 
-- `status.4`: 사용자가 요청한 `workStatus`를 `task-manifest.json`에 기록한다.
-- `errors`, `error-zip`, `recap record`: 읽은 정보를 바탕으로 report/zip/log 산출물을 만든다.
+- `status.4`: writes the user-requested `workStatus` into `task-manifest.json`.
+- `errors`, `error-zip`, `recap record`: produce report/zip/log artifacts from the information read.
 
-## sub-command 목록
+## sub-command list
 
-| Sub-command | 역할 | 쓰기 여부 |
+| Sub-command | Role | Writes? |
 |---|---|---|
-| `status` | task/phase/workflow 상태 확인, workStatus 변경 | `status.4`에서 manifest 수정 |
-| `history` | 과거 run 목록, rerun/resume command 조립 | 기본 읽기 |
-| `report` | final-report 경로 해석 및 선택적 읽기 | 읽기 |
-| `time` | task type/worker별 소요 시간 집계 | 읽기 |
-| `logs` | wrapper `.log` sidecar inventory와 cleanup command 제안 | 읽기 |
-| `cost` | task bundle context/read cost 추정 | 읽기 |
-| `errors` | task error logs를 timestamped markdown report로 집계 | report 생성 |
-| `error-zip` | cross-project error logs 익명화 zip 생성 | zip 생성 |
-| `recap` | task run 전후 요약과 Q&A 기록 | `recap-log.jsonl` append |
+| `status` | check task/phase/workflow status, change workStatus | manifest edit in `status.4` |
+| `history` | list past runs, assemble rerun/resume command | read by default |
+| `report` | resolve final-report path and optionally read | read |
+| `time` | aggregate elapsed time per task type/worker | read |
+| `logs` | inventory wrapper `.log` sidecars and suggest cleanup commands | read |
+| `cost` | estimate task bundle context/read cost | read |
+| `errors` | aggregate task error logs into a timestamped markdown report | generates report |
+| `error-zip` | build an anonymized zip of cross-project error logs | generates zip |
+| `recap` | summarize a task's before/after runs and record Q&A | appends `recap-log.jsonl` |
 
 ## Preflight
 
-모든 sub-command 전에 한 번만 실행한다.
+Run once before any sub-command.
 
 ```bash
 okstra preflight --runtime claude-code --json
 ```
 
-프로젝트 확인은 Bash 호출의 cwd만 본다. cwd가 아닌 프로젝트(형제 repo·monorepo 하위·요청에 명시된 프로젝트)에서 `ok:false`는 setup 부재가 아니라 false negative다 — 바로 멈추지 말고 `okstra preflight --runtime claude-code --cwd <that-dir> --json`으로 재시도한다(`--cwd`는 leading `cd` 없이 프로젝트를 지정하는 sanctioned 방식). 그것도 `ok:false`일 때만 `/okstra-setup` 안내 후 멈춘다. 이후 `projectRoot`를 literal 값으로 사용하고, 이를 받는 sub-command CLI(`recap`, `context-cost` 등)에는 `--cwd`/`--project-root <projectRoot>`로 전달한다.
+The project check only sees the cwd of the Bash call. For a project that is not the cwd (a sibling repo, a monorepo subdir, or a project named in the request), `ok:false` is a false negative, not a missing setup — do not stop immediately; retry with `okstra preflight --runtime claude-code --cwd <that-dir> --json` (`--cwd` is the sanctioned way to target a project without a leading `cd`). Only when that also returns `ok:false` do you guide the user to `/okstra-setup` and stop. Then use `projectRoot` as a literal value, and pass it to the sub-command CLIs that accept it (`recap`, `context-cost`, etc.) via `--cwd`/`--project-root <projectRoot>`.
 
 ## intent routing
 
-사용자 요청을 하나 이상의 facet으로 분류한다. 애매하면 sub-command 표 전체를 보여주고 번호/이름으로 선택하게 한다. AskUserQuestion option 제한 때문에 facet을 숨기지 않는다.
+Classify the user request into one or more facets. If ambiguous, show the entire sub-command table and let the user pick by number/name. Do not hide a facet because of AskUserQuestion's option limit.
 
-여러 facet이 한 메시지에 있으면 순차 실행한다. Step 0은 한 번만 실행한다.
+If several facets appear in one message, execute them sequentially. Step 0 runs only once.
 
-## task-key 해석 공통 규칙
+## task-key resolution — shared rule
 
-많은 facet은 다음 target 형식을 받는다.
+Many facets accept the following target forms.
 
 1. full task-key: `<project-id>:<task-group>:<task-id>`
 2. bare task-id
 3. task root path
 
-bare task-id는 shared resolver를 사용한다.
+A bare task-id uses the shared resolver.
 
 ```bash
 okstra resolve-task-key <task-id> --project-root <projectRoot> --json
 ```
 
-`matches[]` 처리:
+Handling `matches[]`:
 
-- 0개: 찾을 수 없다고 말하고 추측하지 않는다.
-- 1개: 해당 `taskKey` 사용.
-- N개: 후보 `taskKey`와 `updatedAt`를 보여주고 disambiguation을 받는다.
+- 0: say it cannot be found; do not guess.
+- 1: use that `taskKey`.
+- N: show the candidate `taskKey`s and `updatedAt`, and take a disambiguation.
 
 ## status
 
 ### Project overview
 
-`.okstra/discovery/task-catalog.json`을 읽는다. overview에서는 개별 manifest를 다시 열지 않는다. catalog가 projected source다.
+Read `.okstra/discovery/task-catalog.json`. Do not re-open individual manifests for the overview. The catalog is the projected source.
 
-정렬: `updatedAt` desc, `taskKey`.
+Sort: `updatedAt` desc, then `taskKey`.
 
-표는 좁게 유지한다.
+Keep the table narrow.
 
 - Task Key
 - Category
@@ -83,13 +83,13 @@ okstra resolve-task-key <task-id> --project-root <projectRoot> --json
 - workStatus
 - Next
 
-`awaitingApproval` 또는 `routingStatus == "pending"`이면 Next cell에 marker를 붙이고 설명한다.
+If `awaitingApproval` or `routingStatus == "pending"`, add a marker to the Next cell and explain it.
 
 ### Specific task
 
-task 하나의 detail은 catalog를 먼저 보고, 필요하면 `.okstra/tasks/<group>/<id>/task-manifest.json`, `history/timeline.json`, latest run manifest를 읽는다.
+For a single task's detail, check the catalog first, then if needed read `.okstra/tasks/<group>/<id>/task-manifest.json`, `history/timeline.json`, and the latest run manifest.
 
-보여줄 정보:
+Information to show:
 
 - work category
 - current phase/state
@@ -105,70 +105,70 @@ task 하나의 detail은 catalog를 먼저 보고, 필요하면 `.okstra/tasks/<
 
 ### workStatus update
 
-사용자가 명시적으로 상태 변경을 요청할 때만 쓴다.
+Write only when the user explicitly requests a status change.
 
-허용값:
+Allowed values:
 
 - `todo`
 - `in-progress`
 - `blocked`
 - `done`
 
-절차: `okstra set-work-status <token> <status> [--note <text>] --project-root <projectRoot> --json` 단일 호출로 갱신한다 — manifest 를 손으로 편집하지 않는다. `stage:"ambiguous"` 면 `matches[]` 로 되묻고, `stage:"not-found"` 면 못 찾았다고 답한다.
+Procedure: update via a single `okstra set-work-status <token> <status> [--note <text>] --project-root <projectRoot> --json` call — do not edit the manifest by hand. On `stage:"ambiguous"`, re-ask with `matches[]`; on `stage:"not-found"`, answer that it cannot be found.
 
-읽기 표시에서 `workStatus`가 없으면 lifecycle state로 추론하되, 읽기만으로 back-fill하지 않는다.
+When `workStatus` is absent in a read display, infer it from the lifecycle state, but do not back-fill on read alone.
 
 ## history
 
-첫 분기: re-run과 resume을 구분한다.
+First branch: distinguish re-run from resume.
 
-- Re-run: 이전 run parameters로 새 run을 만든다. 새 run-seq가 생긴다.
-- Resume: 중단된 기존 run을 이어간다. 새 run-seq를 만들지 않는다.
+- Re-run: create a new run from previous run parameters. A new run-seq is created.
+- Resume: continue an interrupted existing run. No new run-seq is created.
 
-catalog가 없으면 `.okstra/tasks/*/*/task-manifest.json` glob으로 fallback한다. disk manifest가 source of truth다.
+If the catalog is absent, fall back to the `.okstra/tasks/*/*/task-manifest.json` glob. The disk manifest is the source of truth.
 
-Re-run은 source run-manifest에서 `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, relatedTasks, model overrides 등을 뽑아 command를 조립한다. `implementation`의 `--base-ref`는 run-manifest에 없고 worktree registry에 있으므로 상황에 따라 묻는다.
+Re-run extracts `projectId`, `taskGroup`, `taskId`, `taskType`, `taskBriefPath`, workers, relatedTasks, model overrides, and so on from the source run-manifest to assemble the command. `implementation`'s `--base-ref` is not in the run-manifest but in the worktree registry, so ask for it as the situation requires.
 
-Resume은 `latestResumeCommandPath` 또는 timeline entry의 `resumeCommandPath`를 확인하고 파일이 있으면 `bash <resume-command-path>`를 안내/실행한다. 경로가 비었거나 파일이 없으면 "resume 없음"으로 선언하고 history.3(re-run)을 안내한다.
+Resume checks `latestResumeCommandPath` or the timeline entry's `resumeCommandPath`, and if the file exists, guides/runs `bash <resume-command-path>`. If the path is empty or the file is missing, declare "no resume" and guide to history.3 (re-run).
 
 ## report
 
-report path 해석 우선순위:
+report path resolution priority:
 
-1. `.okstra/discovery/task-catalog.json`의 `latestReportPath`
-2. direct `task-manifest.json`의 `latestReportPath`
-3. `history/timeline.json`의 특정 run `reportPath`
-4. 특정 task-type fallback: `runs/<task-type>/reports/final-report-*.md`, stage-isolated path 포함
+1. `latestReportPath` in `.okstra/discovery/task-catalog.json`
+2. `latestReportPath` in the direct `task-manifest.json`
+3. a specific run's `reportPath` in `history/timeline.json`
+4. specific task-type fallback: `runs/<task-type>/reports/final-report-*.md`, including stage-isolated paths
 
-읽기 깊이를 요청에 맞춘다(final report는 300+줄/50K+ 토큰). 요약/결론/통과 여부 질문("요약", "핵심만", "결론", "통과했어?")은 전체를 읽지 말고 `runs/<task-type-segment>/status/final-<task-type-segment>-<NNN>.status`(stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) sidecar의 판정 + report 선두 요약 블록만 읽는다. "전체/다 읽어/본문"일 때만 전체 ingest한다. 완료 signal은 있는데 file이 없으면 missing report로 말하고, 아직 완료되지 않았으면 current status와 workStatus를 보여준다.
+Match read depth to the request (a final report is 300+ lines / 50K+ tokens). For summary/conclusion/pass questions ("summary", "just the key points", "conclusion", "did it pass?"), do not read the whole thing — read only the verdict in the `runs/<task-type-segment>/status/final-<task-type-segment>-<NNN>.status` (stage-isolated: `runs/<task-type-segment>/stage-<N>/status/`) sidecar plus the report's leading summary block. Ingest the whole file only for "the whole thing / read it all / full body". If a completion signal exists but the file does not, report it as a missing report; if it is not yet complete, show the current status and workStatus.
 
 ## time
 
-시간 계산은 CLI가 한다. AI가 duration을 직접 recompute하지 않는다.
+The CLI does the time computation. The AI does not recompute duration by hand.
 
 ```bash
 okstra time-report <task-key> --project-root <projectRoot> --json
 ```
 
-모든 `*Ms`는 `HH:MM:SS`로 변환해 보여준다. `CPU sum`은 lead와 workers 시간을 합친 overlapping cost이며 wall-clock이 아니다. wall-clock은 사용자가 명시적으로 물을 때만 `perRunWallClock`에서 보여준다. `단계별`/`stage별`/`어느 단계가 오래`는 task-type 뷰(By task type 표)가 기본 답이다 — '측정 불가'로 처리하지 않는다. intra-run `phaseTimelines`는 'Phase 1~7'·'어느 phase가' 같은 명시적 요청일 때만 렌더하고, 비어 있으면 헤드라인이 아니라 각주로만 언급한다.
+Convert every `*Ms` to `HH:MM:SS` for display. `CPU sum` is the overlapping cost of lead and workers time combined, not wall-clock. Show wall-clock from `perRunWallClock` only when the user explicitly asks. For `by stage`/`per stage`/`which stage took longest`, the task-type view (the By task type table) is the default answer — do not treat it as 'not measurable'. Render the intra-run `phaseTimelines` only on an explicit request like 'Phase 1–7' / 'which phase', and when it is empty, mention it only as a footnote rather than a headline.
 
-`unavailable[]`은 totals에 합치지 않고 별도 note로 표시한다.
+`unavailable[]` is not summed into totals; show it as a separate note.
 
 ## cost
 
-context/read cost는 CLI output이 source of truth다.
+For context/read cost, the CLI output is the source of truth.
 
 ```bash
 okstra context-cost <task-key> --project-root <projectRoot>
 ```
 
-해석 포인트:
+Interpretation points:
 
-- token estimate는 heuristic이지 billing 수치가 아니다.
-- `leadPhase1.mode == "active-run-context"`면 compact lead intake가 primary다.
-- `analysisWorker.mode == "analysis-packet-primary"`면 worker는 analysis-packet을 먼저 읽고 필요할 때 full source를 연다.
-- `skillAssets`가 크면 prompt diet 대상이다.
-- legacy timestamp artifacts가 많으면 destructive delete가 아니라 current-view/cold-artifact 분리를 제안한다.
+- the token estimate is a heuristic, not a billing figure.
+- if `leadPhase1.mode == "active-run-context"`, the compact lead intake is primary.
+- if `analysisWorker.mode == "analysis-packet-primary"`, the worker reads the analysis-packet first and opens the full source only when needed.
+- if `skillAssets` is large, it is a prompt-diet target.
+- if there are many legacy timestamp artifacts, propose current-view/cold-artifact separation rather than a destructive delete.
 
 ## logs
 
@@ -178,33 +178,33 @@ wrapper sidecar log inventory:
 okstra log-report --project-root <projectRoot> --json
 ```
 
-`.okstra/tasks/**/runs/*/prompts/*.log`를 스캔한다. 삭제하지 않는다. cleanup command는 dry-run과 `-delete` pair를 fenced bash로 제시할 뿐이다.
+Scans `.okstra/tasks/**/runs/*/prompts/*.log`. Does not delete. The cleanup command merely presents a dry-run and `-delete` pair as fenced bash.
 
-active run의 log를 지우면 live trace를 잃으므로 먼저 `status` 확인을 권한다.
+Deleting an active run's log loses the live trace, so recommend checking `status` first.
 
 ## errors
 
-task error logs를 markdown report로 집계한다.
+Aggregate task error logs into a markdown report.
 
 ```bash
 okstra error-report <task-key> --project-root <projectRoot>
 ```
 
-stdout JSON에서 `reportPath`, totals, byPhase, byAgent, parseSkipped를 읽어 요약한다. `reportPath`가 없고 errorCount가 0이면 기록된 error log가 없다고 말한다. `parseSkipped > 0`은 숨기지 않는다.
+Read `reportPath`, totals, byPhase, byAgent, parseSkipped from the stdout JSON and summarize. If `reportPath` is absent and errorCount is 0, say there are no recorded error logs. Do not hide `parseSkipped > 0`.
 
 ## error-zip
 
-머신 내 cross-project okstra errors를 익명화 zip으로 묶는다.
+Bundle the machine's cross-project okstra errors into an anonymized zip.
 
-출력 경로는 `~/.okstra/error-zip.json`의 `lastOutputPath`를 우선 추천하고, 없으면 `~/okstra-error-feedback-<YYYY-MM-DD>.zip`을 제안한다.
+For the output path, recommend `lastOutputPath` from `~/.okstra/error-zip.json` first, and if absent, propose `~/okstra-error-feedback-<YYYY-MM-DD>.zip`.
 
-실행:
+Run:
 
 ```bash
 okstra error-zip --out <path>
 ```
 
-요약 필드:
+Summary fields:
 
 - `outPath`
 - `errorCount`
@@ -213,11 +213,11 @@ okstra error-zip --out <path>
 - `clusterCount`
 - `projectCount`
 
-마지막에 `/okstra-brief-gen`의 error-feedback variant로 brief를 만든 뒤 okstra repo에서 `error-analysis`를 실행하라고 안내한다.
+At the end, guide the user to build a brief with the error-feedback variant of `/okstra-brief-gen`, then run `error-analysis` in the okstra repo.
 
 ## recap
 
-기본은 artifact mode다. `.okstra/` 산출물만 근거로 전후 요약과 질문 답변을 만든다.
+The default is artifact mode. It builds the before/after summary and answers questions using only `.okstra/` artifacts.
 
 assemble:
 
@@ -231,22 +231,22 @@ record:
 okstra recap record <task-key> --project-root <projectRoot> --kind <summary|qa> --mode <artifact|code> --question "<question>" --answer "<summary>" --citation "<path:line>"
 ```
 
-code mode는 사용자가 "diff까지", "코드 변경까지"처럼 명시적으로 요청할 때만 진입한다. recap 진입만으로 code diff를 읽지 않는다.
+Enter code mode only when the user explicitly requests it, such as "including the diff" or "the code changes too". Entering recap alone does not read the code diff.
 
-## 출력 규칙
+## Output rules
 
-- 한국어로 간결히 답한다.
-- project-relative path를 우선 표시한다.
-- disk field 값은 normalize하지 않고 그대로 보여준다.
-- approval 대기 상태는 명확히 표시한다.
-- 최신 report가 없으면 `--`로 표시한다.
-- 날짜는 `YYYY-MM-DD HH:MM`로 표시한다.
+- Answer concisely in Korean.
+- Prefer project-relative paths.
+- Show disk field values as-is without normalizing.
+- Clearly indicate an awaiting-approval state.
+- If there is no recent report, show `--`.
+- Display dates in `YYYY-MM-DD HH:MM`.
 
-## 금지 패턴
+## Forbidden patterns
 
-- catalog가 없다고 바로 실패하기. manifest fallback이 있다.
-- `workStatus`와 `currentStatus`를 혼동하기.
-- time duration을 CLI 없이 손계산하기.
-- cleanup command를 직접 실행하기.
-- `errors`/`cost`/`time`에서 CLI output 대신 raw files를 임의로 재해석하기.
-- recap artifact mode에서 코드 변경까지 자동으로 읽기.
+- Failing immediately because the catalog is absent. There is a manifest fallback.
+- Confusing `workStatus` with `currentStatus`.
+- Hand-computing time duration without the CLI.
+- Running a cleanup command directly.
+- Arbitrarily reinterpreting raw files instead of CLI output in `errors`/`cost`/`time`.
+- Automatically reading code changes in recap artifact mode.

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

@@ -1,25 +1,25 @@
 # okstra-manager
 
-여러 프로젝트에 걸친 okstra task 를 하나의 manager-owned context 로 묶을 때 사용한다. 원문 계약은 [`skills/okstra-manager/SKILL.md`](../../../skills/okstra-manager/SKILL.md), CLI 구현은 [`src/commands/manager.mjs`](../../../src/commands/manager.mjs) 와 [`scripts/okstra_ctl/manager_cli.py`](../../../scripts/okstra_ctl/manager_cli.py) 이다.
+Use this to bundle okstra tasks across multiple projects into a single manager-owned context. The authoritative contract is [`skills/okstra-manager/SKILL.md`](../../../skills/okstra-manager/SKILL.md); the CLI implementation is [`src/commands/manager.mjs`](../../../src/commands/manager.mjs) and [`scripts/okstra_ctl/manager_cli.py`](../../../scripts/okstra_ctl/manager_cli.py).
 
-## 언제 쓰나
+## When to Use
 
-- 사용자가 "여러 프로젝트", "cross-project", "okstra manager", "프로젝트 묶어서" 같은 의도를 말한다.
-- manager 아래에 프로젝트를 등록하거나 후보 프로젝트를 찾는다.
-- 공통 task-group/task-id 아래 child project task 를 계획하고 역할/지시를 배정한다.
-- child project `.okstra` 상태를 manager snapshot 으로 동기화하거나 status 를 본다.
-- 특정 child task 실행을 위한 launch packet 과 manager child context 를 준비한다.
+- The user says something like "multiple projects", "cross-project", "okstra manager", or "group projects together".
+- Register projects under a manager, or discover candidate projects.
+- Plan child project tasks under a shared task-group/task-id and assign roles/directives.
+- Sync child project `.okstra` state into the manager snapshot, or view status.
+- Prepare a launch packet and a manager child context for running a specific child task.
 
-## 실행 규칙
+## Execution Rules
 
-1. 모든 명령은 literal `okstra` 로 시작한다. 셸 변수, `$(...)`, `&&`, `eval`, 선행 env assignment 로 감싸지 않는다.
-2. JSON stdout 이 source of truth 다. manager 상태나 child launch args 를 문서/메모리에서 재구성하지 않는다.
-3. `--workspace-root` 는 Node wrapper 가 소유한다. 사용자가 넘기면 CLI 가 거부한다.
-4. `new project` 의 `--project-root` 는 이미 존재하는 디렉터리여야 한다. 그 안의 `.okstra/project.json` 이 없을 때만 setup-equivalent registration 을 수행한다.
-5. public child task identity 는 `project-id:task-group:task-id` 이다. `new task --task` 예시는 full key form 을 우선 보여준다.
-6. 같은 manager task id 아래 실제 child task id 가 다르면 `task assign` 과 `task run` 에 `--child-task-id <id>` 를 같이 넘긴다.
+1. Every command starts with the literal `okstra`. Do not wrap it in shell variables, `$(...)`, `&&`, `eval`, or a leading env assignment.
+2. JSON stdout is the source of truth. Do not reconstruct manager state or child launch args from docs/memory.
+3. `--workspace-root` is owned by the Node wrapper. The CLI rejects it if the user passes it.
+4. `new project`'s `--project-root` must be an already-existing directory. It performs setup-equivalent registration only when there is no `.okstra/project.json` inside it.
+5. The public child task identity is `project-id:task-group:task-id`. The `new task --task` example shows the full key form first.
+6. When the actual child task id differs under the same manager task id, pass `--child-task-id <id>` to both `task assign` and `task run`.
 
-## 명령 표면
+## Command Surface
 
 ```bash
 okstra manager init --manager-id <manager-id> --json
@@ -34,35 +34,35 @@ okstra manager task status --manager-id <manager-id> --task-group <task-group> -
 okstra manager task run --manager-id <manager-id> --project-id <project-id> --task-group <task-group> --task-id <task-id> [--child-task-id <child-task-id>] --json
 ```
 
-## 저장 모델
+## Storage Model
 
-Manager state 는 `~/.okstra/managers/<manager-id>/` 아래에 저장되며, manager 루트와 task 디렉터리 두 계층으로 나뉜다.
+Manager state is stored under `~/.okstra/managers/<manager-id>/`, split into two layers: the manager root and the task directory.
 
-manager 루트 직하:
+Directly under the manager root:
 
 - `manager.json`: manager id / schema / createdAt
-- `projects.json`: 등록된 projectId, projectRoot, role, tags
+- `projects.json`: registered projectId, projectRoot, role, tags
 
-task 디렉터리 `task-groups/<safe-group>/<safe-task>/` 아래:
+Under the task directory `task-groups/<safe-group>/<safe-task>/`:
 
 - `manifest.json`: manager task objective, common brief, progress mode
 - `children.json`: child task plan, assignment, launch metadata
 - `directives.jsonl`: shared/project directive rows
-- `snapshots.json`: `task sync` 가 project-local `.okstra` 에서 읽어온 read-side snapshot
-- `events.jsonl`: `task-created`, `child-launch-prepared` 같은 manager event
-- `child-context/<safe-project>-<safe-task>.md`: `task run` 이 만든 child lead context
+- `snapshots.json`: the read-side snapshot `task sync` read from the project-local `.okstra`
+- `events.jsonl`: manager events such as `task-created` and `child-launch-prepared`
+- `child-context/<safe-project>-<safe-task>.md`: the child lead context `task run` produced
 
-비 ASCII task-group/task-id 처럼 slug 가 비는 segment 는 `u-<sha1-prefix>` path segment 를 사용하지만, manifest 와 child `taskKey` 는 원래 입력값을 보존한다.
+A segment whose slug is empty (e.g. a non-ASCII task-group/task-id) uses a `u-<sha1-prefix>` path segment, but the manifest and the child `taskKey` preserve the original input value.
 
 ## Child launch
 
-`task run` 은 child 작업을 직접 실행하지 않고 launch packet 을 준비한다. 반환 packet 의 핵심 필드는:
+`task run` does not run the child work directly; it prepares a launch packet. The key fields of the returned packet:
 
-- `taskKey`: child 의 `project-id:task-group:task-id` (child 식별 공개 키 — `child-launch-prepared` event 에도 기록)
-- `backend`: `$TMUX` 가 있으면 `tmux-child-lead`, 없으면 `subagent-child-lead`
-- `workerDispatchBackend`: v1 에서는 항상 `subagent`
-- `projectRoot`: child project root
-- `contextPath`: manager child context markdown
-- `runArgs`: host launcher 가 사용할 `okstra run ... --directive "Read manager child context: ..."` 인자
+- `taskKey`: the child's `project-id:task-group:task-id` (the public child-identity key — also recorded on the `child-launch-prepared` event)
+- `backend`: `tmux-child-lead` if `$TMUX` is present, otherwise `subagent-child-lead`
+- `workerDispatchBackend`: always `subagent` in v1
+- `projectRoot`: the child project root
+- `contextPath`: the manager child context markdown
+- `runArgs`: the `okstra run ... --directive "Read manager child context: ..."` args for the host launcher to use
 
-packet 생성이 성공하면 `children.json` 의 해당 child launch 상태가 `prepared` 로 갱신되고, `events.jsonl` 에 `child-launch-prepared` 가 append 된다. 실패해도 project-local task state 는 수정하지 않는다.
+When packet creation succeeds, that child launch's status in `children.json` is updated to `prepared`, and a `child-launch-prepared` is appended to `events.jsonl`. On failure it does not modify the project-local task state.

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

@@ -1,82 +1,82 @@
 # okstra-memory AI Manual
 
-## 원천
+## Source
 
-- 스킬 원문: [`skills/okstra-memory/SKILL.md`](../../../skills/okstra-memory/SKILL.md)
+- Skill source: [`skills/okstra-memory/SKILL.md`](../../../skills/okstra-memory/SKILL.md)
 - CLI registry: [`src/cli-registry.mjs`](../../../src/cli-registry.mjs)
 - memory CLI: [`src/commands/memory/memory.mjs`](../../../src/commands/memory/memory.mjs)
 
-## 목적
+## Purpose
 
-`okstra-memory`는 사용자 홈의 Memory Book을 관리한다.
+`okstra-memory` manages the Memory Book in the user's home.
 
 ```text
 ~/.okstra/memory-book/
 ```
 
-프로젝트 local `.okstra/` artifact가 아니다. `<PROJECT_ROOT>/.okstra/project.json`이 없어도 사용할 수 있다.
+It is not a project-local `.okstra/` artifact. It can be used even without `<PROJECT_ROOT>/.okstra/project.json`.
 
-## 사용 조건
+## When to use
 
-사용한다:
+Use it when:
 
-- 사용자가 "기억해둬", "대화 저장", "okstra에 정리해서 보관", "remember this", "save this decision"처럼 명시적으로 저장을 요청한다.
-- 저장된 memory를 검색, 목록화, 읽기, archive하려고 한다.
+- The user explicitly asks to save, e.g. "remember this", "save the conversation", "organize and store this in okstra", "remember this", "save this decision".
+- The user wants to search, list, read, or archive stored memory.
 
-사용하지 않는다:
+Do not use it when:
 
-- 사용자가 단순 brainstorming 중이고 저장 요청이 없다. 이때는 확인 질문을 먼저 한다.
-- project task artifact로 남겨야 하는 내용. 이 경우 해당 okstra task의 brief/report/decision 경로를 사용한다.
+- The user is only brainstorming with no save request. In that case, ask a confirmation question first.
+- The content should be kept as a project task artifact. In that case, use the brief/report/decision path of the relevant okstra task.
 
 ## safety rule
 
-명시적 저장 요청 없이 저장하지 않는다. credentials, API keys, tokens, private personal data, secrets는 저장하지 않는다. 대화에 민감한 내용이 있으면 summary에서 제외하고 omission을 기록한다.
+Do not save without an explicit save request. Do not store credentials, API keys, tokens, private personal data, or secrets. If the conversation includes sensitive material, exclude it from the summary and note the omission.
 
-CLI도 high-confidence secret shape를 감지해 `memory add`를 거부할 수 있다. 거부되면 내용을 redact하고 재시도한다.
+The CLI can also detect high-confidence secret shapes and refuse `memory add`. If refused, redact the content and retry.
 
 ## CLI availability
 
-먼저 help를 확인한다.
+Check the help first.
 
 ```bash
 okstra memory --help
 ```
 
-`okstra`가 PATH에 없으면 `npx okstra@latest install`을 직접 실행하지 말고, 한 번 설치 후 재시도하라고 안내한다.
+If `okstra` is not on PATH, do not run `npx okstra@latest install` directly; tell the user to install it once and then retry.
 
-## project-group 선택
+## project-group selection
 
-모든 memory entry는 project-group에 속한다. 저장/검색 전에 group을 먼저 고른다.
+Every memory entry belongs to a project-group. Pick the group before storing or searching.
 
-기존 group 조회:
+Enumerate existing groups:
 
 ```bash
 okstra memory groups --json
 ```
 
-추천:
+Recommendations:
 
-- 가장 많이 쓰인 existing group
-- 두 번째 existing group
-- 직접 입력
+- the most-used existing group
+- the second existing group
+- Enter directly
 
-개인 메모리는 `private`를 우선 추천한다. group이 없거나 선택이 없으면 CLI default인 `global`을 쓴다.
+For a personal note, recommend `private` first. If there is no group or no selection, use the CLI default `global`.
 
-선택 group은 `add`, `search`, `list`에 `--project-group <group>`으로 전달한다. 사용자가 cross-group search를 명시한 경우에만 flag를 생략한다.
+Pass the chosen group to `add`, `search`, and `list` as `--project-group <group>`. Omit the flag only when the user explicitly wants a cross-group search.
 
-## 저장 절차
+## Store procedure
 
-대화 전체 transcript를 저장하지 않는다. 오래 남길 durable memory만 추출해 concise Markdown summary로 만든다.
+Do not store the full conversation transcript. Extract only durable memory worth keeping long-term and turn it into a concise Markdown summary.
 
-포함할 것:
+Include:
 
-- 저장 이유
+- the reason for storing
 - source: `conversation`
-- 관련 project id가 명확하면 `--project`
-- 검색용 tags
+- `--project` when the related project id is clear
+- tags for search
 - memory type
 
-type 값은 `okstra memory --help` 출력이 권위다. 원문 기준 category:
+The `okstra memory --help` output is authoritative for the type values. Categories per the source:
 
 - `decision`
 - `preference`
@@ -86,19 +86,19 @@ type 값은 `okstra memory --help` 출력이 권위다. 원문 기준 category:
 - `follow-up`
 - `context`
 
-저장 명령 형태:
+Store command shape:
 
 ```bash
 okstra memory add --content "<summary markdown>" --title "<short title>" --type <type> --project-group <group> --tag <tag> --project <id> --source conversation --yes
 ```
 
-필요하면 `--tag`, `--project`를 반복한다. 관련 project가 명확하지 않으면 `--project`를 생략한다.
+Repeat `--tag` and `--project` as needed. Omit `--project` when no related project is clear.
 
-`--yes`는 사용자가 저장을 명시했을 때만 사용한다.
+Use `--yes` only when the user explicitly asked to save.
 
-## 검색/읽기/archive
+## search / read / archive
 
-기본은 선택한 project-group scope다.
+The default scope is the chosen project-group.
 
 ```bash
 okstra memory search "<query>" --project-group "<group>"
@@ -108,20 +108,19 @@ okstra memory show "<memory-id>"
 okstra memory archive "<memory-id>"
 ```
 
-ID parsing이 필요하면 `--json`을 선호한다. 사용자에게는 짧은 요약과 entry id/path 정도만 보여준다.
+Prefer `--json` when you need to parse IDs. Show the user only a short summary plus the entry id/path.
 
-## 출력 규칙
+## Output rules
 
-- 저장 시 title, type, project-group, tags, generated id를 요약한다.
-- 검색 시 match count와 가장 관련 높은 entry를 먼저 보여준다.
-- archive는 사용자 의도가 명확할 때만 실행한다.
-- project `.okstra/`에 쓰지 않는다.
+- On store, summarize title, type, project-group, tags, and the generated id.
+- On search, show the match count and the most relevant entry first.
+- Run archive only when the user's intent is clear.
+- Do not write into a project `.okstra/`.
 
-## 금지 패턴
-
-- 명시 요청 없이 자동 저장.
-- secret/token/key를 저장.
-- full transcript를 그대로 저장.
-- project-local task memory처럼 `.okstra/`에 쓰기.
-- cross-group search를 사용자가 요청하지 않았는데 기본으로 수행하기.
+## Forbidden patterns
 
+- Auto-saving without an explicit request.
+- Storing a secret/token/key.
+- Storing the full transcript verbatim.
+- Writing into `.okstra/` as if it were project-local task memory.
+- Performing a cross-group search by default when the user did not ask for it.