okstra 0.4.0 → 0.5.0

package/docs/kr/cli.md

@@ -0,0 +1,400 @@
+# okstra — CLI 인자 / 옵션 매뉴얼 (한국어)
+
+> 이 문서는 [README.kr.md](../../README.kr.md) 의 보충 문서입니다. 내부 아키텍처와 storage / workflow 계약은 [architecture.md](architecture.md) 를 참고하세요.
+
+---
+
+## Command forms
+
+기본 명령(첫 진입 / full args):
+
+```bash
+scripts/okstra.sh [--render-only] [--yes] [--refresh-assets] --task-type <task-type> [--workers worker1,worker2] [--lead-model <model>] [--claude-model <model>] [--codex-model <model>] [--gemini-model <model>] [--report-writer-model <model>] [--related-tasks taskA,taskB] [--clarification-response <previous-final-report>] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>]
+```
+
+후속 phase 단축 형식(기존 task-manifest.json이 존재할 때):
+
+```bash
+scripts/okstra.sh --task-key <project-id>:<task-group>:<task-id> [--task-type <task-type>]
+```
+
+Clarification 답변 즉시 재실행:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>
+```
+
+interactive terminal에서 실행하면 다음 규칙이 추가로 적용됩니다.
+
+- 필수 인자가 비어 있으면 stdin으로 직접 입력을 받습니다.
+- 입력이 모두 준비되면 실행 전 요약을 보여줍니다.
+- `y` 또는 `yes`를 입력했을 때만 실제 생성 또는 실행 단계로 진행합니다.
+- interactive가 아닌 실행에서는 누락 인자를 prompt하지 않고 에러로 종료합니다.
+- `--yes`를 사용하면 prompt와 confirmation을 모두 건너뛰지만, 이때는 모든 필수 인자가 반드시 이미 채워져 있어야 합니다.
+- 우선순위는 `명시적 CLI 인자 > interactive prompt 또는 non-interactive 에러`입니다.
+
+## Required arguments
+
+### `--project-id`
+
+전역에서 고유해야 하는 프로젝트 ID입니다. 첫 실행 시 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 에 자기 등록(self-registration)되며, 동일 PROJECT_ROOT 에서 재실행할 때 인자값과 저장된 `projectId` 가 다르면 즉시 에러로 종료합니다.
+
+예:
+
+- `fontradar-v2-api`
+- `jobs`
+
+### `--task-group`
+
+관련 task를 묶는 논리 그룹입니다.
+
+예:
+
+- `feature-8858`
+- `bugfix-auth`
+- `tasks`
+
+### `--task-id`
+
+같은 그룹 안에서 안정적으로 재사용할 task 식별자입니다.
+
+예:
+
+- `email-recipient-loss`
+- `8852`
+
+### `--task-type`
+
+이번 run의 목적과 profile 선택, run directory 세그먼트, lifecycle phase 라우팅을 결정하는 단일 입력값입니다.
+표준 값과 phase별 책임은 위 [Task type](#task-type) 섹션을 참고합니다.
+
+### `--task-brief`
+
+분석의 기준이 되는 task brief 문서 경로입니다.
+상대 경로는 대상 프로젝트 루트를 기준으로 해석됩니다.
+
+예:
+
+- `.project-docs/linear/feature/8858/okstra-task-brief.md`
+- `.project-docs/tasks/8852/BUG_REPORT.md`
+
+### `--yes`
+
+interactive prompt와 confirmation을 생략합니다.
+
+대신 아래 조건이 강제됩니다.
+
+- `project-id`
+- `task-group`
+- `task-id`
+- `task-type`
+- `brief-path`
+
+즉, 필수 인자가 하나라도 비어 있으면 prompt하지 않고 즉시 종료합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --yes --render-only --task-type error-analysis --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+## Optional arguments and options
+
+### `--task-key`
+
+기존 task에 대한 후속 phase를 시작할 때 `--project-id`/`--task-group`/`--task-id`를 한 번에 전달하는 단축 형식입니다.
+
+- 입력 형식: `<project-id>:<task-group>:<task-id>`
+- 동작:
+  - 세 ID로 split하여 `PROJECT_ID`/`TASK_GROUP`/`TASK_ID`에 채웁니다.
+  - 명시적으로 같은 값들이 함께 들어오면 일치할 때만 허용하고, 충돌하면 즉시 에러로 종료합니다.
+  - 해당 task의 `task-manifest.json`이 존재하면 누락된 `--task-brief`를 manifest의 `taskBriefPath` 로, 누락된 `--task-type`을 `workflow.nextRecommendedPhase` 로 자동 채웁니다.
+  - manifest가 없으면(첫 진입) 기존 누락-인자 검증이 그대로 동작합니다(=full args 강제).
+- 명시적으로 전달된 인자가 항상 manifest 값보다 우선합니다.
+- `nextRecommendedPhase`가 `pending-routing-decision` 또는 `done-or-follow-up`이면 자동 채움하지 않고, 사용자가 명시적으로 `--task-type`을 주거나 brief을 보강한 뒤 다시 실행해야 합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852
+```
+
+```bash
+scripts/okstra.sh --task-key jobs:tasks:8852 --task-type final-verification
+```
+
+### `--clarification-response`
+
+이전 run의 final report(`Section 5. Clarification Requests for the Next Run`에 사용자가 답변을 inline으로 채운 파일)를 다음 run으로 carry-in합니다.
+
+- 입력: `<previous-run>/reports/final-report-<task-type>-<seq>.md` 경로
+- 동작: 파일을 현재 run의 `instruction-set/clarification-response.md`로 복사하고, lead가 Section 0에서 prior `Q*` 행의 `Status`(`resolved` / `obsolete`)를 갱신한 뒤 진행합니다.
+- 사용 시점: `requirements-discovery`, `error-analysis`처럼 미해결 질문을 남기는 phase 이후, 사용자가 답변을 채워 다음 phase로 넘길 때.
+
+예:
+
+```bash
+scripts/okstra.sh \
+  --task-type implementation-planning \
+  --project-id jobs --task-group tasks --task-id 8852 \
+  --task-brief .project-docs/tasks/8852/BUG_REPORT.md \
+  --clarification-response .project-docs/okstra/tasks/tasks/8852/runs/2026-04-29/error-analysis/reports/final-report-2026-04-29_10-15-30.md
+```
+
+### `--resume-clarification`
+
+직전 `requirements-discovery` 또는 `error-analysis` run의 final report를 즉시 편집하고, 같은 phase를 자동으로 재실행합니다. `--clarification-response` 경로를 사용자가 직접 들고 다닐 필요가 없습니다.
+
+- 입력: task identity (`--project-id` + `--task-group` + `--task-id`, 또는 `--task-key <p>:<g>:<i>`)
+- 동작 순서:
+  1. task의 `runs/{requirements-discovery,error-analysis}/reports/final-report-*.md` 중 가장 최신 timestamp 파일을 자동 선택합니다.
+  2. `$EDITOR`(미설정 시 `vi`)로 해당 파일을 엽니다. 사용자는 Section 5의 `Q*` 행에 답변을 inline으로 채운 뒤 저장하고 종료합니다.
+  3. okstra가 같은 task-type으로 자기 자신을 `exec` 재호출하면서 편집된 파일을 `--clarification-response`로 carry-in 합니다.
+  4. 이후 confirmation, render, Claude handoff 흐름은 일반 실행과 동일합니다.
+- 명시적 `--task-type`을 함께 주면 그 task type의 reports/ 만 검색합니다. 생략 시 `error-analysis` → `requirements-discovery` 순으로 검색하고 timestamp가 더 큰 보고서를 사용합니다.
+- 다음 옵션과 함께 쓸 수 없습니다: `--render-only`, `--clarification-response`, `--approved-plan`.
+- `EDITOR`를 비대화형 도구(예: `true`)로 설정하면 답변 편집을 건너뛴 채 곧바로 재실행됩니다. 디버깅용으로만 권장합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --resume-clarification --task-key jobs:tasks:8852
+```
+
+```bash
+EDITOR=code\ -w scripts/okstra.sh --resume-clarification --project-id jobs --task-group tasks --task-id 8852
+```
+
+내부적으로는 다음과 동등합니다.
+
+```bash
+$EDITOR <project-root>/.project-docs/okstra/tasks/<group>/<id>/runs/<task-type>/reports/final-report-<latest>.md
+scripts/okstra.sh --task-type <same-type> \
+  --project-id <p> --task-group <g> --task-id <i> \
+  --task-brief <from manifest> \
+  --clarification-response <edited final-report-<latest>.md>
+```
+
+### `--project-root`
+
+대상 프로젝트의 절대 경로입니다. 명시하지 않으면 `okstra.sh` 가 다음 우선순위로 자동 해석합니다.
+
+1. cwd 또는 그 조상 디렉토리 중 `.project-docs/okstra/project.json` 보유 위치를 찾아 PROJECT_ROOT 로 채택합니다.
+2. 위가 실패하면 `git rev-parse --show-toplevel` 결과를 사용합니다.
+3. 모두 실패하면 즉시 에러로 종료합니다.
+
+해석된 PROJECT_ROOT 에서 첫 실행이라면 `<PROJECT_ROOT>/.project-docs/okstra/project.json` 이 다음 스키마로 자동 생성됩니다.
+
+```json
+{
+  "projectId": "<--project-id 인자 값>",
+  "projectRoot": "<resolved absolute path>",
+  "createdAt": "<ISO8601 UTC>",
+  "updatedAt": "<ISO8601 UTC>"
+}
+```
+
+이미 존재하면 `projectId` 일치 검사 후 `projectRoot`/`updatedAt` 만 갱신합니다. `projectId` 가 다르면 즉시 에러로 종료해 동일 디렉토리에서 두 개의 ID 가 혼용되는 것을 막습니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --project-id jobs --project-root /Volumes/Workspaces/workspace/projects/jobs ...
+```
+
+### `--directive`
+
+사용자 의도를 자유 텍스트로 lead·worker·downstream skill에 전달하는 채널입니다. 값은 `instruction-set/analysis-material.md` 끝에 `## Directive` 섹션으로 임베딩되고, 동시에 `instruction-set/directive.txt`로 백업됩니다.
+
+용도:
+
+- 기본 heuristic을 뒤집고 싶을 때 — 예: "단일 XL task여도 Gantt 그려줘 (Phase 2개, 총 ~10d)", "Gantt 생략 사유를 명시해줘" (참고: `## Cumulative Timeline`은 schedule contract에서 제거되었으므로 더 이상 toggle 대상이 아닙니다)
+- 분석/계획의 강조점 지시 — 예: "rollout 리스크 우선 분석", "test 커버리지 부재를 별도 finding으로"
+- Phase/Step 분할이나 day 추정을 미리 제시 — 예: "Part 1: 4d, measure: 0.5d, Part 2: 4d, ops: 1d"
+
+해석 규칙:
+
+- lead·worker는 `analysis-material.md`를 이미 end-to-end로 읽으므로 별도 작업 없이 자동 전파됩니다.
+- skill 측은 자체 contract보다 user prompt를 **우선** 적용해야 하며 (예: `okstra-schedule` 스킬의 "Directive override (highest priority)" 절), heuristic을 뒤집은 경우 결과 문서에 그 사실을 한 줄로 표시합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning ... \
+  --directive "Phase 2개(Part 1 ~4d, Part 2 ~5d, 순차)로 총 ~10d. Gantt 꼭 그려줘 (임계 경로 표시)."
+```
+
+### `--workers`
+
+이번 run에서 사용할 worker 목록을 직접 지정합니다.
+생략하면 기본값 `claude,codex,gemini,report-writer`를 사용합니다.
+지정하면 전달한 worker subset만 dedupe 후 기록됩니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type implementation-planning --workers claude,codex --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+### `--claude-model`
+
+`Claude worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CLAUDE_MODEL` 또는 fallback `sonnet`을 사용합니다.
+
+### `--lead-model`
+
+`Claude lead`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_LEAD_MODEL` 또는 fallback `opus`를 사용합니다.
+
+### `--codex-model`
+
+`Codex worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_CODEX_MODEL` 또는 fallback `gpt-5.5`를 사용합니다.
+
+### `--gemini-model`
+
+`Gemini worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_GEMINI_MODEL` 또는 fallback `auto`를 사용합니다.
+
+### `--report-writer-model`
+
+`Report writer worker`에 사용할 모델을 지정합니다.
+지정하지 않으면 중앙 기본값 `OKSTRA_DEFAULT_REPORT_WRITER_MODEL` 또는 lead 기본값을 사용합니다.
+
+중앙 기본값 환경 변수는 아래와 같습니다.
+
+- `OKSTRA_DEFAULT_LEAD_MODEL`
+- `OKSTRA_DEFAULT_CLAUDE_MODEL`
+- `OKSTRA_DEFAULT_CODEX_MODEL`
+- `OKSTRA_DEFAULT_GEMINI_MODEL`
+- `OKSTRA_DEFAULT_REPORT_WRITER_MODEL`
+
+fallback 기본값은 아래와 같습니다.
+
+- `Claude lead`: `opus`
+- `Report writer worker`: `opus`
+- `Claude worker`: `sonnet`
+- `Codex worker`: `gpt-5.5`
+- `Gemini worker`: `auto`
+
+### `--related-tasks`
+
+간단한 연관 task 식별자 목록을 쉼표로 전달합니다.
+
+예:
+
+```bash
+scripts/okstra.sh --task-type error-analysis --related-tasks scanner-regression,reply-ui --project-id jobs --task-group tasks --task-id 8852 --task-brief .project-docs/tasks/8852/BUG_REPORT.md
+```
+
+연관 task는 참고용 메타데이터이며 현재 task key를 대체하지 않습니다.
+
+### `--render-only`
+
+실제 Claude 실행 없이 프롬프트와 task bundle만 생성합니다.
+
+이 모드에서는 아래를 수행하지 않습니다.
+
+- Claude 실행
+- `final-report-<task-type>-<seq>.md` 생성
+- `final-<task-type>-<seq>.status` 생성
+
+하지만 아래는 수행합니다.
+
+- stable task root 생성 또는 갱신
+- `task-manifest.json` 생성 또는 갱신
+- `task-index.md` 생성 또는 갱신
+- `instruction-set/` 생성 또는 갱신
+- `instruction-set/reference-expectations.md` 생성 또는 갱신
+- `instruction-set/final-report-template.md` 생성 또는 갱신
+- current `manifests/run-manifest-<task-type>-<seq>.json` 기록
+- `history/timeline.json` 갱신
+- project-level discovery pointer 생성 또는 갱신
+
+### `--refresh-assets`
+
+project-local `.claude/skills/`와 `.claude/agents/` 아래의 okstra mapped asset을 workspace source 기준으로 다시 생성합니다.
+기본 rerun에서는 기존 project-local asset을 유지합니다.
+
+
+## Interactive input flow
+
+interactive terminal에서 필수 인자 일부를 생략하면 `okstra`가 아래 항목을 순서대로 물을 수 있습니다.
+
+- `Project ID`
+- `Task Group`
+- `Task ID`
+- `Task Type`
+- `Task Brief Path`
+
+예를 들어 아래처럼 실행할 수 있습니다.
+
+```bash
+scripts/okstra.sh --render-only --task-type error-analysis
+```
+
+그러면 누락된 필수값을 stdin으로 입력받은 뒤, 최종 요약과 confirmation을 거쳐 진행합니다.
+
+## Confirmation flow
+
+interactive 실행에서는 실제 파일 생성 전에 아래 성격의 요약을 보여줍니다.
+
+- render-only 여부
+- task type
+- project id
+- task group
+- task id
+- task brief path
+- analysis target
+- related tasks
+- selected workers
+- lead model
+- configured worker models
+- task key
+- task root
+- current run dir
+
+이후 `Continue? [y/yes]:` 프롬프트가 표시되며, `y` 또는 `yes`가 아니면 실행하지 않고 종료합니다.
+
+`--yes`를 사용하면 이 confirmation flow 자체를 건너뜁니다.
+
+
+---
+
+## okstra Control Center — 설치 / 자주 쓰는 명령
+
+## okstra Control Center
+
+`okstra-ctl` 은 사용자 홈의 `~/.okstra/` 인덱스를 사용해 모든 타깃 프로젝트의 okstra run 을 가로질러 조회·모니터링·재실행할 수 있는 CLI 다.
+
+### 설치 (전역 wrapper)
+
+`okstra` 와 동일하게 `~/.local/bin/` 아래에 wrapper 를 두면 어디서든 호출 가능하다.
+
+```bash
+cat > ~/.local/bin/okstra-ctl <<'WRAPPER'
+#!/usr/bin/env bash
+exec /Volumes/Workspaces/workspace/projects/Okstra/scripts/okstra-ctl.sh "$@"
+WRAPPER
+chmod +x ~/.local/bin/okstra-ctl
+```
+
+(`~/.local/bin` 이 `PATH` 에 포함되어 있어야 한다.)
+
+### 자주 쓰는 명령
+
+| 목적 | 명령 |
+|---|---|
+| 작업한 프로젝트 목록 | `okstra-ctl projects` |
+| 최근 run 검색 | `okstra-ctl list --since 7d` |
+| 특정 프로젝트만 | `okstra-ctl list --project fontradar` |
+| 진행 중 run 보기 | `okstra-ctl tail active` |
+| 단일 run 결과 메타 | `okstra-ctl show <runId-or-prefix>` |
+| 결과 보고서 경로 | `okstra-ctl open <runId-or-prefix>` |
+| 단일 재실행 | `okstra-ctl rerun <runId-or-prefix> --yes` |
+| 다중 재실행 | `okstra-ctl rerun --filter --project X --status failed --yes` |
+| 가장 최근 재실행 | `okstra-ctl rerun last --project X --task-group Y --yes` |
+| 백필/재스캔 | `okstra-ctl reindex` |
+| 활성 run 재조정 | `okstra-ctl reconcile [--project <id|all>]` |
+| 배치 진행 | `okstra-ctl batch status <batch-id>` |
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -16,7 +16,9 @@
     "bin/",
     "src/",
     "runtime/",
-    "README.md"
+    "docs/",
+    "README.md",
+    "README.kr.md"
   ],
   "engines": {
     "node": ">=18"

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.4.0",
-  "builtAt": "2026-05-12T03:09:54.795Z",
+  "package": "0.5.0",
+  "builtAt": "2026-05-12T04:37:48.519Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/src/install.mjs

@@ -226,6 +226,13 @@ async function installLinkMode(repoPath, paths, opts) {
     process.stdout.write(`  dev-link stamp: ${repoAbs}\n`);
     process.stdout.write(`  version stamp: ${paths.package}\n`);
     process.stdout.write("done.\n");
+    process.stdout.write(
+      "\nNext step: register the current project.\n" +
+        "  cd <your project> && npx -y okstra@latest setup --project-id <id>\n" +
+        "  (or run /okstra-setup inside a Claude Code session)\n" +
+        "\nTip: to use a bare 'okstra' command instead of npx, run:\n" +
+        "  npm i -g okstra\n",
+    );
   }
   return 0;
 }
@@ -401,6 +408,13 @@ export async function runInstall(args) {
   if (!opts.quiet) {
     process.stdout.write(`  version stamp: ${paths.package}\n`);
     process.stdout.write("done.\n");
+    process.stdout.write(
+      "\nNext step: register the current project.\n" +
+        "  cd <your project> && npx -y okstra@latest setup --project-id <id>\n" +
+        "  (or run /okstra-setup inside a Claude Code session)\n" +
+        "\nTip: to use a bare 'okstra' command instead of npx, run:\n" +
+        "  npm i -g okstra\n",
+    );
   }
   return 0;
 }

package/src/setup.mjs

@@ -0,0 +1,243 @@
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra setup — register the current project with okstra
+
+Writes <PROJECT_ROOT>/.project-docs/okstra/project.json. This is the
+project-level companion to 'okstra install' (which is machine-level).
+Inside a Claude Code session this is also exposed as the /okstra-setup
+slash command.
+
+Usage:
+  okstra setup --project-id <id>          Register with explicit projectId
+  okstra setup                            Use existing project.json or
+                                          prompt for projectId (TTY only)
+  okstra setup --project-root <path>      Override PROJECT_ROOT resolution
+  okstra setup --yes                      Skip prompts; require all inputs
+                                          on the command line
+
+Behavior:
+  - If project.json already exists, the projectId must match (okstra refuses
+    to silently rename a project). Delete the file manually if you really
+    want to change projectId.
+  - If --project-id is omitted and stdin is a TTY, you are prompted.
+  - If --project-id is omitted and stdin is not a TTY, the command exits
+    with an error (use --project-id for CI / scripts).
+
+Exit codes:
+  0   project.json present and valid after the run
+  1   I/O / python failure or projectId mismatch
+  2   PROJECT_ROOT could not be resolved
+`;
+
+function runProcess(cmd, args, env) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, ...env },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString()));
+    child.stderr.on("data", (b) => (stderr += b.toString()));
+    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+function parseArgs(args) {
+  const opts = {
+    projectId: null,
+    projectRoot: null,
+    yes: false,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--project-id") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("--")) throw new Error("--project-id requires a value");
+      opts.projectId = next;
+      i++;
+    } else if (a === "--project-root") {
+      const next = args[i + 1];
+      if (!next || next.startsWith("--")) throw new Error("--project-root requires a path");
+      opts.projectRoot = next;
+      i++;
+    } else {
+      throw new Error(`unknown argument '${a}'`);
+    }
+  }
+  return opts;
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function validateProjectId(id) {
+  if (!id) return "project-id is empty";
+  if (!/[A-Za-z0-9]/.test(id)) return "project-id must contain at least one alphanumeric character";
+  return null;
+}
+
+async function resolveProjectRoot(paths, explicit) {
+  const probe = await runProcess(
+    "python3",
+    [
+      "-c",
+      [
+        "import sys",
+        "from okstra_project import resolve_project_root, project_json_path, ResolverError",
+        "try:",
+        "    pr = resolve_project_root(explicit_root=sys.argv[1], cwd=sys.argv[2])",
+        "    print('PROJECT_ROOT', pr)",
+        "    print('PROJECT_JSON', project_json_path(pr))",
+        "except ResolverError as e:",
+        "    print('RESOLVER_ERROR', e)",
+      ].join("\n"),
+      explicit || "",
+      process.cwd(),
+    ],
+    { PYTHONPATH: paths.pythonpath },
+  );
+  if (probe.code !== 0) {
+    throw new Error(`python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`);
+  }
+  const lines = probe.stdout.trim().split("\n");
+  const tagOf = (key) =>
+    lines
+      .find((l) => l.startsWith(key + " "))
+      ?.slice(key.length + 1)
+      .trim() ?? null;
+  const resolverError = tagOf("RESOLVER_ERROR");
+  if (resolverError) {
+    const err = new Error(resolverError);
+    err.code = "RESOLVER";
+    throw err;
+  }
+  return {
+    projectRoot: tagOf("PROJECT_ROOT"),
+    projectJsonPath: tagOf("PROJECT_JSON"),
+  };
+}
+
+async function upsert(paths, projectRoot, projectId) {
+  const probe = await runProcess(
+    "python3",
+    [
+      "-c",
+      [
+        "import json, sys",
+        "from pathlib import Path",
+        "from okstra_project import upsert_project_json, ResolverError",
+        "try:",
+        "    result = upsert_project_json(Path(sys.argv[1]), sys.argv[2])",
+        "    print('OK', json.dumps(result))",
+        "except ResolverError as e:",
+        "    print('ERROR', e)",
+      ].join("\n"),
+      projectRoot,
+      projectId,
+    ],
+    { PYTHONPATH: paths.pythonpath },
+  );
+  if (probe.code !== 0) {
+    throw new Error(`python invocation failed: ${probe.stderr.trim() || probe.stdout.trim()}`);
+  }
+  const out = probe.stdout.trim();
+  if (out.startsWith("OK ")) {
+    return JSON.parse(out.slice(3));
+  }
+  if (out.startsWith("ERROR ")) {
+    throw new Error(out.slice(6));
+  }
+  throw new Error(`unexpected upsert output: ${out}`);
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 1;
+  }
+
+  const paths = await resolvePaths();
+
+  let resolved;
+  try {
+    resolved = await resolveProjectRoot(paths, opts.projectRoot);
+  } catch (err) {
+    process.stderr.write(`error: could not resolve PROJECT_ROOT: ${err.message}\n`);
+    return err.code === "RESOLVER" ? 2 : 1;
+  }
+  const { projectRoot, projectJsonPath } = resolved;
+
+  let existing = null;
+  if (await fileExists(projectJsonPath)) {
+    try {
+      existing = JSON.parse(await fs.readFile(projectJsonPath, "utf8"));
+    } catch (err) {
+      process.stderr.write(`error: failed to parse ${projectJsonPath}: ${err.message}\n`);
+      return 1;
+    }
+  }
+
+  let projectId = opts.projectId;
+  if (!projectId && existing?.projectId) {
+    projectId = existing.projectId;
+  }
+
+  if (!projectId) {
+    if (opts.yes || !process.stdin.isTTY) {
+      process.stderr.write(
+        `error: --project-id is required (no existing project.json, not a TTY)\n`,
+      );
+      return 1;
+    }
+    process.stderr.write(`PROJECT_ROOT: ${projectRoot}\n`);
+    const answer = await prompt("project-id (e.g. INV-1234, fontsninja): ");
+    projectId = answer;
+  }
+
+  const invalid = validateProjectId(projectId);
+  if (invalid) {
+    process.stderr.write(`error: ${invalid}\n`);
+    return 1;
+  }
+
+  let result;
+  try {
+    result = await upsert(paths, projectRoot, projectId);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    return 1;
+  }
+
+  process.stdout.write(JSON.stringify({ ok: true, ...result, projectJsonPath }, null, 2) + "\n");
+  return 0;
+}