okstra 0.117.0 → 0.118.0

package/docs/project-structure-overview.md

@@ -1,6 +1,6 @@
 # Okstra — 폴더 구조 및 기능 요약
 
-> 현재 저장소 기준의 living map입니다. 빠른 사용법은 [`README.kr.md`](../README.kr.md), 내부 실행 계약은 [`docs/kr/architecture.md`](kr/architecture.md), CLI 세부 옵션은 [`docs/kr/cli.md`](kr/cli.md)를 함께 보세요.
+> 현재 저장소 기준의 living map입니다. 빠른 사용법은 [`README.md`](../README.md), 내부 실행 계약은 [`docs/architecture.md`](architecture.md), 저장 구조는 [`docs/architecture/storage-model.md`](architecture/storage-model.md), CLI 세부 옵션은 [`docs/cli.md`](cli.md)를 함께 보세요.
 
 ---
 
@@ -54,19 +54,21 @@ okstra/
 │   ├── okstra_vendor/               vendored Jinja2 / MarkupSafe + graphify / networkx (okstra-graphify skill)
 │   ├── lib/okstra/                  Bash helpers for okstra.sh
 │   └── lib/okstra-ctl/              Bash control-center subcommands
-├── skills/                          Claude Code skills (10)
+├── skills/                          Claude Code skills (11)
 ├── agents/                          lead SKILL.md + worker agent specs
 ├── prompts/                         launch template, phase profiles, wizard prompt JSON
 ├── schemas/                         JSON schema for final-report data.json
 ├── templates/                       report, setup, PR, project-doc templates/assets
 ├── validators/                      run / brief / schedule / view validators
 ├── tools/build.mjs                  source → runtime sync
+├── tools/docs_publication/          public-manual publication pipeline (build-time only; not shipped)
+├── config/docs-publication.json     publication inventory: every tracked Markdown path + classification
 ├── runtime/                         generated install payload; do not edit directly
 ├── tests/                           pytest unit suite
 ├── tests-e2e/                       Bash end-to-end scenarios
 ├── docs/                            architecture, CLI, plans/specs
 ├── package.json                     npm metadata and published file list
-├── README.md / README.kr.md         user manuals
+├── README.md                        public user manual
 ├── CHANGES.md / CHANGELOG.md        human-authored and generated changelogs
 └── RELEASING.md                     release process
 ```
@@ -84,9 +86,13 @@ okstra/
 - `bin/`
 - `src/`
 - `runtime/`
-- `docs/`
+- `docs/architecture.md`
+- `docs/architecture/`
+- `docs/cli.md`
+- `docs/container.md`
+- `docs/performance-improvement-plan-v2.md`
+- selected contributor, follow-up, AI, and task-process documentation paths
 - `README.md`
-- `README.kr.md`
 
 So `runtime/` is not the only npm-published content. It is the install payload copied into `~/.okstra`.
 
@@ -142,7 +148,7 @@ Runtime/install asset changes follow this checklist:
 
 `bin/okstra` is a thin dynamic-import router. Every command module exports `run(args) -> Promise<number>` or a named install/uninstall runner.
 
-`src/` is layered: the dispatch table (`src/cli-registry.mjs`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory}/`.
+`src/` is layered: the dispatch table (`src/cli-registry.mjs`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory,pr}/`.
 
 | Command | Module | Role |
 |---|---|---|
@@ -175,6 +181,7 @@ Runtime/install asset changes follow this checklist:
 | `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
 | `spawn-followups`, `error-log` | `src/commands/execute/*.mjs` | Follow-up task bundle creation and run error-log append helpers |
 | `memory` | `src/commands/memory/memory.mjs` | Store/find global conversation memory under `~/.okstra/memory-book` |
+| `pr` | `src/commands/pr/pr.mjs` | `okstra pr <template\|branches\|gen>` — PR body template store under `~/.okstra/template/pr/` (bundled fallback `src/commands/pr/default.md`), base-branch recommendation, and the `gen` JSON bundle (template + `<base>..HEAD` commits + `<base>...HEAD` diffstat) backing the okstra-pr-gen skill. Git-only; no project registration required |
 | `recap` | `src/commands/inspect/recap.mjs` | `okstra recap <assemble\|record>` Node wrapper backing the okstra-inspect `recap` facet |
 | `rollup` | `src/commands/inspect/rollup.mjs` | `okstra rollup` thin shim into `scripts/okstra_ctl/rollup.py` — read-only cross-task roll-up backing the okstra-rollup skill |
 | `container` | `src/commands/inspect/container.mjs` | `bin okstra container` thin shim into `scripts/okstra_ctl/container.py` for the okstra-container-build skill |
@@ -313,7 +320,7 @@ Optional (v1.0 하위호환) 최상위 키:
 
 ### 4.10 `skills/`
 
-9 user-facing skills (the only skills `okstra install` copies):
+11 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mjs`; the Claude plugin manifest and the installer both derive from it:
 
 | Skill | User-invocable | Role |
 |---|---:|---|
@@ -324,6 +331,8 @@ Optional (v1.0 하위호환) 최상위 키:
 | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
 | `okstra-schedule` | yes | Generate task-group schedule |
 | `okstra-container-build` | yes | Non-linear deploy tool — deploy a verified task's code as a docker compose group and watch each container (sub-commands `up` / `status` / `logs` / `stop-watcher` / `down`) |
+| `okstra-graphify` | yes | Knowledge graph over the project's own `.okstra/` memory — final reports, `decisions/*.md`, `glossary.md`; scope restricted to `.okstra/`, output under `.okstra/graph/` (sub-commands `build` / `query` / `path` / `explain` / `mcp` / `wiki`) |
+| `okstra-pr-gen` | yes | Register PR body templates under `~/.okstra/template/pr/` and generate a PR description from a branch diff (drives `okstra pr template` / `branches` / `gen`). **Global skill** — needs a Git repo, not `<PROJECT_ROOT>/.okstra/project.json` |
 | `okstra-manager` | yes | Coordinate cross-project okstra tasks through manager-owned plans, assignments, sync snapshots, status, and child launch context packets |
 | `okstra-setup` | yes | Install/check runtime and register project |
 
@@ -488,11 +497,13 @@ Final report artifacts live under `runs/<task-type>/reports/`. Human responses f
 
 When changing code, keep these docs in sync:
 
-- New Node command: update `bin/okstra` usage, `README*`, this file, and `docs/kr/cli.md`.
+- New Node command: update `bin/okstra` usage, `README.md`, this file, and `docs/cli.md`.
 - New runtime source copied to users: update `tools/build.mjs`, install/uninstall manifests if applicable, and this file.
-- New skill/agent: update `README*`, this file, install/uninstall fallback lists, and `CHANGES.md`.
+- New skill/agent: update `README.md`, this file, install/uninstall fallback lists, and `CHANGES.md`.
 - New report field/section: update schema, template, report-writer worker, validator tests, this file's report model if user-visible.
-- New phase/profile behavior: update `prompts/profiles/*`, `docs/kr/architecture.md`, `docs/kr/cli.md`, and `README*` if user-facing.
+- New phase/profile behavior: update `prompts/profiles/*`, `docs/architecture.md`, `docs/cli.md`, and `README.md` if user-facing.
+
+`README.md`, `docs/cli.md`, `docs/architecture.md`, `docs/architecture/storage-model.md`, `docs/container.md`, and `docs/performance-improvement-plan-v2.md` are `translated` outputs in `config/docs-publication.json` — do **not** hand-edit them. Author the Korean source under the maintainer's Git-ignored `.project-docs/ko-source/`, then run the publication pipeline (`python3 -m tools.docs_publication prepare|validate|apply|record`), which keeps the source/output hashes in `.project-docs/doc-publishing/state.json` in step. Files classified `pending` — including this one, `CHANGES.md`, and `CHANGELOG.md` — are edited directly.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.117.0",
+  "version": "0.118.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -16,14 +16,18 @@
     "bin/",
     "src/",
     "runtime/",
+    "docs/architecture.md",
+    "docs/architecture/",
+    "docs/cli.md",
+    "docs/container.md",
     "docs/contributor-change-matrix.md",
+    "docs/follow-ups/2026-07-10-final-report-option-3.md",
     "docs/for-ai/",
-    "docs/kr/",
+    "docs/performance-improvement-plan-v2.md",
     "docs/pr-template-usage.md",
     "docs/project-structure-overview.md",
     "docs/task-process/",
-    "README.md",
-    "README.kr.md"
+    "README.md"
   ],
   "engines": {
     "node": ">=18"
@@ -31,9 +35,10 @@
   "scripts": {
     "build": "node tools/build.mjs",
     "prepack": "node tools/build.mjs",
+    "docs:validate": "python3 -m tools.docs_publication validate --repo .",
     "test:js": "node --test tests-js/*.test.mjs",
     "test:py": "python3 -m pytest tests/",
     "test:workflow": "bash validators/validate-workflow.sh",
-    "check": "npm run build && npm run test:js && npm run test:py && npm run test:workflow"
+    "check": "npm run docs:validate && npm run build && npm run test:js && npm run test:py && npm run test:workflow"
   }
 }

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.117.0",
-  "builtAt": "2026-07-14T11:54:12.876Z",
+  "package": "0.118.0",
+  "builtAt": "2026-07-15T06:18:58.589Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/recap.py

@@ -1,6 +1,7 @@
-"""Read-side recap for a task: assemble run-to-run phase transitions and
-append a recap Q&A log. Mutates only <task-root>/recap/recap-log.jsonl;
-never touches task-manifest / catalog / timeline.
+"""Read-side recap for a task: assemble run-to-run phase transitions, append a
+recap Q&A log, and write agent-authored notes. Writes only under
+<task-root>/recap/recap-log.jsonl and <task-root>/notes/; never touches
+task-manifest / catalog / timeline.
 """
 from __future__ import annotations
 
@@ -10,9 +11,12 @@ import json
 import sys
 from pathlib import Path
 
+from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.run_context import dir_flock
 from okstra_ctl.task_target import resolve_task_root, project_rel
 
+NOTE_KINDS = ("verification-evidence", "decision-draft", "analysis-note")
+
 
 def _load_timeline(task_root: Path) -> list[dict]:
     path = task_root / "history" / "timeline.json"
@@ -91,6 +95,56 @@ def append_recap_entry(task_root, project_root, *, kind, mode, question,
     return {"logPath": project_rel(log_path, project_root), "entry": entry}
 
 
+def _note_path(notes_dir: Path, slug: str, date: str) -> Path:
+    # 같은 날 같은 slug 로 노트를 여러 개 남기면 덮어쓰지 않도록 -2, -3 을 붙인다.
+    base = notes_dir / f"{slug}-{date}.md"
+    if not base.exists():
+        return base
+    seq = 2
+    while (candidate := notes_dir / f"{slug}-{date}-{seq}.md").exists():
+        seq += 1
+    return candidate
+
+
+def _note_frontmatter(*, task_key, kind, created_at, purpose, scope_note) -> str:
+    return (
+        "---\n"
+        f"task-key: {task_key}\n"
+        f"kind: {kind}\n"
+        "author: agent\n"
+        f"created-at: {created_at}\n"
+        f"purpose: {purpose}\n"
+        f"scope-note: {scope_note}\n"
+        "---\n\n"
+    )
+
+
+def write_note(task_root, project_root, *, kind, slug, purpose, scope_note,
+               body, now) -> dict:
+    notes_dir = task_root / "notes"
+    notes_dir.mkdir(parents=True, exist_ok=True)
+    created_at = now.date().isoformat()
+    slug_seg = slugify_task_segment(slug)
+    if not slug_seg:
+        raise ValueError("slug must contain at least one alphanumeric character")
+    path = _note_path(notes_dir, slug_seg, created_at)
+    task_key = _task_key(task_root)
+    frontmatter = _note_frontmatter(
+        task_key=task_key, kind=kind, created_at=created_at,
+        purpose=purpose, scope_note=scope_note)
+    path.write_text(frontmatter + body.rstrip("\n") + "\n", encoding="utf-8")
+    note_rel = project_rel(path, project_root)
+    return {
+        "notePath": note_rel,
+        "taskKey": task_key,
+        "kind": kind,
+        "createdAt": created_at,
+        # 노트는 inert — 다음 run 이 자동으로 읽지 않는다. 이 인자를 그대로
+        # `okstra run ...` 에 붙여야만 instruction-set 에 주입된다.
+        "clarificationResponseArg": f"--clarification-response {note_rel}",
+    }
+
+
 def _add_common(sp) -> None:
     # skill 이 쓰는 `<verb> <target> --project-root <root>` 형태를 받으려면
     # 공통 옵션을 부모가 아닌 각 서브파서에 등록해야 한다.
@@ -115,12 +169,35 @@ def main(argv: list[str] | None = None) -> int:
     p_rec.add_argument("--answer", required=True)
     p_rec.add_argument("--citation", action="append", default=[])
 
+    p_note = sub.add_parser(
+        "note", help="write an agent-authored note into <task-root>/notes/")
+    p_note.add_argument("target", help="task root path or task-key")
+    _add_common(p_note)
+    p_note.add_argument("--kind", choices=NOTE_KINDS, required=True)
+    p_note.add_argument("--slug", required=True,
+                        help="short topic slug for the filename")
+    p_note.add_argument("--purpose", required=True,
+                        help="one line — what it is and which run/decision it feeds")
+    p_note.add_argument("--scope-note", required=True, dest="scope_note",
+                        help="one line — what it is NOT (e.g. not a user decision)")
+    body_src = p_note.add_mutually_exclusive_group(required=True)
+    body_src.add_argument("--body", help="inline markdown body")
+    body_src.add_argument("--body-file", dest="body_file",
+                          help="path to a file holding the markdown body")
+
     args = parser.parse_args(argv)
     task_root, project_root = resolve_task_root(
         args.target, args.project_root, args.cwd)
 
     if args.command == "assemble":
         result = assemble_recap(task_root, project_root)
+    elif args.command == "note":
+        body = (Path(args.body_file).read_text(encoding="utf-8")
+                if args.body_file else args.body)
+        result = write_note(
+            task_root, project_root, kind=args.kind, slug=args.slug,
+            purpose=args.purpose, scope_note=args.scope_note, body=body,
+            now=dt.datetime.now(dt.timezone.utc))
     else:
         result = append_recap_entry(
             task_root, project_root, kind=args.kind, mode=args.mode,

package/runtime/skills/okstra-inspect/SKILL.md

@@ -18,7 +18,7 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `cost` | Estimate file/read context cost for a task bundle. |
 | `errors` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
 | `error-zip` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
-| `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`. |
+| `recap` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`, and writes agent-authored notes to `notes/` for feeding into later runs. |
 
 ## Step 0: Preflight (shared)
 
@@ -690,7 +690,7 @@ stdout JSON 을 파싱해 보고:
 
 Trigger phrases: "okstra recap", "recap", "작업 요약", "이 task 요약", "전후 요약", "이 작업 설명해줘", "task 질문".
 
-task-id 하나에 쌓인 `.okstra` 산출물 위에서 (a) 처리 전/후 요약을 내고, (b) 그 작업에 대한 자유 질문에 답한다. 기본은 `.okstra/` 서브트리만 읽는다(artifact 모드). 사용자가 명시적으로 코드 변경까지 봐 달라고 요청할 때만 code 모드로 확장한다. 이 sub-command 는 `recap/recap-log.jsonl` 만 append 하고 `task-manifest.json` / catalog / timeline 은 절대 mutate 하지 않는다.
+task-id 하나에 쌓인 `.okstra` 산출물 위에서 (a) 처리 전/후 요약을 내고, (b) 그 작업에 대한 자유 질문에 답한다. 기본은 `.okstra/` 서브트리만 읽는다(artifact 모드). 사용자가 명시적으로 코드 변경까지 봐 달라고 요청할 때만 code 모드로 확장한다. 이 sub-command 는 `recap/recap-log.jsonl` append 와 `notes/` 노트 작성(recap.5)만 수행하고 `task-manifest.json` / catalog / timeline 은 절대 mutate 하지 않는다.
 
 ### recap.1 — Resolve target
 
@@ -748,6 +748,41 @@ okstra recap record <resolved-target> --project-root <projectRoot> \
 <이후 자유 질문을 받습니다. 코드 변경까지 보려면 "diff 까지 봐줘" 라고 요청하세요.>
 ```
 
+### recap.5 — Agent 저작 노트 (`notes/`)
+
+recap 중에 네가 **okstra task 를 위해** 만든 산출물 — 검증 증거, 설계·decision 초안, 분석 노트 — 이 앞으로의 run 에 근거로 쓰일 수 있고, 그 내용이 **렌더된 report 도 아니고 사용자 결정도 아닐 때**만 `notes/` 에 남긴다.
+
+**소유권으로 라우팅한다.** 지금 쓰려는 것이 아래 어디에 해당하는지 먼저 판별한다:
+
+| 내용 | 레인(경로) | 저작 주체 |
+|---|---|---|
+| final report 본문 | `runs/<type>/reports/*.md` (`*.data.json` 에서 렌더) | okstra 렌더러 — 절대 수기 편집 금지 |
+| clarification 에 대한 사용자 답변 | `runs/<type>/user-responses/*.md` (`created-by: user`) | 사용자만 |
+| 확정된 ADR | `.okstra/decisions/NNNN-*.md` | 승격·관리됨 |
+| **Agent 증거 / 설계 초안 / 분석** | **`.okstra/tasks/<group>/<id>/notes/`** | 너(AI) |
+
+렌더 산출물도, 사용자 결정도 아닌 **너 자신의 근거·초안**이면 `notes/` 로 간다. 노트는 손으로 찍지 말고 CLI 로 쓴다 — 경로·frontmatter·날짜를 코드가 보장하고, 다음 run 에 넘길 인자를 출력해 준다:
+
+```bash
+okstra recap note <resolved-target> --project-root <projectRoot> \
+  --kind <verification-evidence|decision-draft|analysis-note> \
+  --slug <short-topic-slug> \
+  --purpose "<한 줄 — 무엇이며 어느 run/decision 에 투입되는지>" \
+  --scope-note "<한 줄 — 무엇이 아닌지, 예: C-00x 에 대한 사용자 결정이 아님>" \
+  --body-file <노트 본문 마크다운 경로>
+```
+
+본문은 먼저 scratchpad 에 마크다운으로 쓴 뒤 `--body-file` 로 넘긴다(짧으면 `--body "<md>"` 인라인도 가능). CLI 는 `.okstra/tasks/<group>/<id>/notes/<slug>-<YYYY-MM-DD>.md` 를 생성하고 stdout JSON 으로 `notePath` 와 `clarificationResponseArg` 를 돌려준다.
+
+**self-check 규칙 (validator 가 없으니 스스로 지킨다):**
+
+1. **렌더된 report 를 수기 편집하지 않는다** (`runs/*/reports/` 아래 `*.md` / `*.data.json` / `*.html`). `data.json` 에서 재생성되므로 편집은 덮어써지고 SSOT 와 어긋난다. 발견 내용은 `notes/` 에 쓴다.
+2. **`user-responses/` 파일을 작성하거나 `created-by: user` 를 달지 않는다.** 그건 사용자의 결정이며, 대신 쓰면 사용자가 내리지 않은 결정을 위조하는 것이다. 네 증거가 특정 답을 뒷받침하면 `notes/` 에 그렇게 적고 결정은 사용자에게 맡긴다.
+3. **okstra 관리 디렉토리에 쓰지 않는다** (`runs/`, `instruction-set/`, `history/`, `recap/`, `.okstra/decisions/`). `notes/` 만이 agent 소유 레인이다. `recap/recap-log.jsonl` 은 예외적으로 쓰되 손으로 편집하지 말고 `okstra recap record` CLI 로만 남긴다.
+4. **`notes/` 는 okstra 에 inert 하다** — 어떤 run 도 자동으로 읽지 않는다. 작성 후 CLI 가 출력한 `clarificationResponseArg`(예: `--clarification-response <notePath>`)를 사용자에게 그대로 알려, 다음 run 을 그 인자와 함께 실행해야만 반영된다는 것을 전한다.
+
+**Guardrail:** `.okstra/` 는 gitignored 다 — `notes/` 는 로컬 scratch 로 취급하고 절대 `git add` 하지 않는다. 새 노트 생성은 되돌리기 쉬우니(파일 삭제), 생성물이나 사용자 소유 파일을 편집하는 것보다 항상 이쪽을 택한다.
+
 ---
 
 ## Output Rules (shared)

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: okstra-pr-gen
-description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}. Trigger words include "okstra pr", "PR 템플릿 등록", "PR 본문 생성", "PR 메시지 만들어", "generate PR", "pr gen", "템플릿 등록".
+description: Use when the user wants to register a PR body template or generate a PR description from a branch diff using a stored (or default) template. Manages templates under ~/.okstra/template/pr and drives okstra pr {template,branches,gen}. Trigger words include "okstra pr", "register PR template", "generate PR body", "generate PR message", "generate PR", "pr gen", and "register template".
 ---
 
 # okstra-pr-gen
@@ -31,11 +31,11 @@ If `okstra` is not on PATH, tell the user:
 
 Present a 3-option picker (`AskUserQuestion`):
 
-1. `PR 생성` — generate a PR body from a branch diff.
-2. `템플릿 등록` — save a new PR body template.
-3. `직접 입력` — always the last option (okstra picker convention).
+1. `Generate PR` — generate a PR body from a branch diff.
+2. `Register template` — save a new PR body template.
+3. `Enter manually` — always the last option (okstra picker convention).
 
-## Mode A — PR 생성
+## Mode A — Generate PR
 
 ### A1. Pick a template
 
@@ -44,7 +44,8 @@ okstra pr template list --json
 ```
 
 - If `templates` is non-empty, present a picker: 1–2 recommended templates from
-  the list, plus `기본 템플릿`(the bundled default), plus `직접 입력` last.
+  the list, plus `Default template` (the bundled default), plus `Enter manually`
+  last.
 - If empty, tell the user the bundled default template will be used.
 
 Carry the chosen template name as `<template>` (`default` for the bundled one).
@@ -55,7 +56,7 @@ Carry the chosen template name as `<template>` (`default` for the bundled one).
 okstra pr branches --json
 ```
 
-Present a 3-option base picker from `recommended` (top entries) plus `직접 입력`
+Present a 3-option base picker from `recommended` (top entries) plus `Enter manually`
 last. Carry the choice as `<base>`.
 
 ### A3. Build the generation bundle and fill the template
@@ -91,7 +92,7 @@ or not authenticated (`gh auth status` fails), leave the text in chat and tell
 the user to create the PR manually. Do not push or create the PR without the
 user's explicit confirmation.
 
-## Mode B — 템플릿 등록
+## Mode B — Register template
 
 1. Ask for a template name (`AskUserQuestion`, free text). It must match
    `^[A-Za-z0-9._-]+$`; re-ask on invalid input.

package/src/commands/inspect/recap.mjs

@@ -1,15 +1,20 @@
 import { runPythonModule } from "../../lib/python-helper.mjs";
 
-const USAGE = `okstra recap — assemble a task's run-to-run phase recap, or append a recap log entry
+const USAGE = `okstra recap — assemble a task's run-to-run phase recap, append a recap log entry, or write an agent note
 
 Usage:
   okstra recap assemble <task-root|task-key> [--project-root <dir>] [--cwd <dir>]
   okstra recap record <task-root|task-key> --kind <summary|qa> --mode <artifact|code> \\
     [--question <text>] --answer <text> [--citation <path:line> ...]
+  okstra recap note <task-root|task-key> \\
+    --kind <verification-evidence|decision-draft|analysis-note> --slug <topic> \\
+    --purpose <text> --scope-note <text> (--body <markdown> | --body-file <path>)
 
 \`assemble\` is read-only and prints a JSON summary of phase transitions across runs.
 \`record\` appends one line to <task-root>/recap/recap-log.jsonl; it never mutates
 other task artifacts.
+\`note\` writes an agent-authored markdown note to <task-root>/notes/ and prints its
+path plus the \`--clarification-response\` argument for feeding it into a later run.
 `;
 
 export async function run(args) {