@devport-kr/portki 0.1.1 → 0.2.0

package/README.md

@@ -10,18 +10,19 @@
 - **청크 기반 생성 (Chunked Generation)**: 저장소의 규모가 클 경우, 문서를 여러 섹션으로 나누고 각 섹션 단위로 상세한 문서를 생성 및 검증한 뒤 로컬 세션 상태에 반영합니다.
 - **순수 Markdown 출력**: 최종 위키를 데이터베이스가 아니라 `README.md`와 섹션별 `.md` 파일로 출력합니다.
 - **증분 업데이트 (Incremental Update)**: 전체 코드를 매번 다시 분석하지 않고, 마지막 위키 생성 커밋 이후 변경된 파일과 영향을 받는 섹션만 추적하여 위키를 효율적으로 갱신합니다.
+- **AI 에이전트 원클릭 통합**: Claude Code, Codex, Gemini CLI에서 한 줄의 명령으로 위키를 생성할 수 있습니다.
 
-## 설치
-
-Node.js 환경이 필요합니다.
+## 빠른 시작 (Quick Start)
 
 ```bash
-npm install
+npx @devport-kr/portki facebook/react
 ```
 
-공개 버전에서는 `.env`를 만들 필요가 없습니다.
+이 한 줄이면 저장소를 분석하고 `handoff.md`를 생성합니다. AI 에이전트가 이 파일을 읽고 위키를 완성합니다.
+
+## 설치
 
-출시 후에는 로컬 clone 없이도 사용할 수 있습니다.
+Node.js 20 이상이 필요합니다. `.env` 설정은 필요 없습니다.
 
 ```bash
 npx @devport-kr/portki help
@@ -34,31 +35,88 @@ npm install -g @devport-kr/portki
 portki help
 ```
 
-## GitHub Releases
+환경 상태를 확인하려면:
+
+```bash
+portki doctor
+```
 
-`public` 브랜치에서는 GitHub Release를 만들 수 있습니다.
+## AI 에이전트에서 사용하기
+
+portki는 AI 코딩 에이전트와 함께 사용하도록 설계되었습니다. `portki owner/repo`를 실행하면 에이전트가 따라갈 수 있는 `handoff.md`가 생성됩니다. 각 에이전트 환경에 맞는 어댑터를 설치하면 더 편리하게 사용할 수 있습니다.
+
+### Claude Code
+
+```bash
+# 1. 어댑터 설치 (프로젝트 루트에서 한 번만)
+portki install --agent claude
+
+# 2. Claude Code에서 슬래시 명령으로 실행
+/portki facebook/react
+```
 
-- `v*` 태그를 `public` 브랜치 커밋에 push하면 Release가 자동으로 생성됩니다.
-- Actions의 수동 실행(`workflow_dispatch`)으로도 Release를 만들 수 있습니다.
-- Release에는 자동 생성된 노트와 함께 소스 아카이브(`.tar.gz`, `.zip`), npm 패키지 tarball(`devport-kr-portki-<version>.tgz`), SHA256 체크섬 파일이 첨부됩니다.
-- npm publish workflow를 함께 켜두면 같은 `v*` 태그에서 npm 패키지도 배포할 수 있습니다.
+`portki install --agent claude`는 `.claude/commands/portki.md`를 생성합니다. 이후 Claude Code에서 `/portki owner/repo`를 입력하면 portki가 저장소를 분석하고 handoff.md를 생성한 뒤, Claude가 그 지침에 따라 위키를 완성합니다.
+
+어댑터 없이 직접 사용할 수도 있습니다:
+
+```bash
+# Claude Code 터미널에서 직접 실행
+portki facebook/react
+# → handoff.md 경로가 출력됨. Claude에게 해당 파일을 읽고 따라달라고 요청
+```
+
+### Codex (OpenAI)
+
+```bash
+# 1. 어댑터 설치 (프로젝트 루트에서 한 번만)
+portki install --agent codex
+```
+
+이 명령은 현재 프로젝트의 `AGENTS.md`에 portki 사용법 섹션을 추가합니다. Codex가 해당 파일을 자동으로 읽어 portki 명령어를 사용할 수 있게 됩니다.
+
+Codex에서 사용 예시:
+
+```
+portki facebook/react 실행하고 handoff.md 따라서 위키 만들어줘
+```
 
-기본 절차:
+### Gemini CLI
 
 ```bash
-git checkout public
-git pull origin public
+# 1. 어댑터 설치 (프로젝트 루트에서 한 번만)
+portki install --agent gemini
 
-# package.json version과 태그는 일치해야 합니다.
-git tag v0.1.1
-git push origin public --follow-tags
+# 2. Gemini에서 슬래시 명령으로 실행
+/portki facebook/react
 ```
 
-npm 배포까지 하려면 저장소 Secrets에 `NPM_TOKEN`을 추가해야 합니다.
+`portki install --agent gemini`는 `.gemini/commands/portki.md`를 생성합니다. 이후 Gemini CLI에서 `/portki owner/repo`를 입력하면 동일한 handoff 흐름이 시작됩니다.
+
+### 공통 워크플로우
+
+어떤 에이전트를 사용하든 내부 흐름은 동일합니다:
+
+1. `portki owner/repo` — 저장소 스냅샷 수집 + 분석 컨텍스트 생성 + `handoff.md` 생성
+2. AI 에이전트가 `handoff.md`를 읽고 단계별 지침을 따름
+3. 에이전트가 `section-plan.json` 작성 → `validate-plan` 실행
+4. 각 섹션을 작성하고 `persist-section`으로 검증
+5. `finalize`로 최종 Markdown 위키 조립
 
-## 권장 실행 환경 
+진행 상황은 언제든 확인할 수 있습니다:
+
+```bash
+portki status owner/repo
+```
+
+중단된 작업을 이어서 하려면:
+
+```bash
+portki resume owner/repo
+```
+
+## 권장 실행 환경
 **(2026년 3월 7일 기준)**
-| 환경 | 권장 모델 | (Effort (Thinking) Level) | 설정 지침 |
+| 환경 | 권장 모델 | Effort (Thinking) Level | 설정 지침 |
 |------|-----------|--------------------------|------------------|
 | **Claude Code** | `Opus 4.6` | High | [`CLAUDE.md`](./CLAUDE.md)|
 | **Codex** | `GPT-5.4` | xHigh | [`AGENTS.md`](./AGENTS.md)|
@@ -66,11 +124,17 @@ npm 배포까지 하려면 저장소 Secrets에 `NPM_TOKEN`을 추가해야 합
 
 ## 명령어 (Commands)
 
-모든 명령은 프로젝트 루트에서 실행합니다.
+### 상위 명령어 (High-level)
 
-```bash
-npx tsx src/agent.ts <command> [flags]
-```
+| 명령 | 설명 |
+|------|------|
+| `portki owner/repo` | 저장소를 분석하고 AI 에이전트용 handoff.md를 생성합니다. |
+| `portki status owner/repo` | 파이프라인 진행 상황을 표시합니다. |
+| `portki resume owner/repo` | 마지막 유효 단계에서 handoff를 재생성합니다. |
+| `portki doctor` | 실행 환경 상태를 점검합니다. |
+| `portki install --agent <name>` | AI 에이전트 어댑터를 설치합니다. (`claude`, `codex`, `gemini`) |
+
+### 하위 명령어 (Low-level)
 
 | 명령 | 설명 |
 |------|------|
@@ -84,48 +148,66 @@ npx tsx src/agent.ts <command> [flags]
 
 ## 워크플로우
 
-이 도구는 AI 에이전트가 위키 문서를 더 정확하고 꼼꼼하게 작성하도록 **청크 단위 작업**을 권장합니다. 
+이 도구는 AI 에이전트가 위키 문서를 더 정확하고 꼼꼼하게 작성하도록 **청크 단위 작업**을 권장합니다.
+
+### 1. AI 에이전트 워크플로우 (권장)
+
+가장 간단한 방식입니다. portki가 분석을 자동화하고, AI 에이전트가 handoff.md를 따라 문서를 작성합니다.
+
+```bash
+# 1. 저장소 분석 + handoff 생성
+portki owner/repo
+
+# 2. AI 에이전트가 handoff.md를 읽고 위키 완성
+#    (에이전트가 validate-plan, persist-section, finalize를 자동으로 실행)
+
+# 3. 진행 상황 확인 (선택)
+portki status owner/repo
+
+# 4. 중단 시 복구 (선택)
+portki resume owner/repo
+```
 
-### 1. 청크 단위 위키 생성 (권장)
+### 2. 수동 청크 단위 위키 생성
 
 저장소를 분석하여 여러 섹션으로 분리한 후 각 섹션별로 코드를 깊이 있게 확인하고 작성하는 방식입니다.
 
 ```bash
 # 1. 저장소 스냅샷 수집
-npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
+portki ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
 
 # 2. 분석 및 섹션 계획 수립 준비 (컨텍스트 생성)
-npx tsx src/agent.ts plan-sections --artifact devport-output/workspace/{repo-slug}-artifact.json --out devport-output/workspace/{repo-slug}-plan-context.json
+portki plan-sections --artifact devport-output/workspace/{repo-slug}-artifact.json --out devport-output/workspace/{repo-slug}-plan-context.json
 
 # (AI 작업: plan-context.json과 주요 코드를 바탕으로 {repo-slug}-section-plan.json 생성)
 
 # 3. 플랜 검증
-npx tsx src/agent.ts validate-plan --input devport-output/workspace/{repo-slug}-section-plan.json --context devport-output/workspace/{repo-slug}-plan-context.json --out devport-output/workspace/{repo-slug}-section-plan.json
+portki validate-plan --input devport-output/workspace/{repo-slug}-section-plan.json --context devport-output/workspace/{repo-slug}-plan-context.json --out devport-output/workspace/{repo-slug}-section-plan.json
 
 # 4. 각 섹션별 작성 및 세션 반영 (전체 섹션 완료 시까지 반복)
 # (AI 작업: 해당 섹션의 코드를 분석하고 {repo-slug}-section-1-output.json 생성)
-npx tsx src/agent.ts persist-section --plan devport-output/workspace/{repo-slug}-section-plan.json --section sec-1 --input devport-output/workspace/{repo-slug}-section-1-output.json
+portki persist-section --plan devport-output/workspace/{repo-slug}-section-plan.json --section sec-1 --input devport-output/workspace/{repo-slug}-section-1-output.json
 
 # 5. 최종 완성 및 증분 베이스라인 갱신
-npx tsx src/agent.ts finalize --plan devport-output/workspace/{repo-slug}-section-plan.json --advance_baseline
+portki finalize --plan devport-output/workspace/{repo-slug}-section-plan.json --advance_baseline
 ```
 
 `finalize`가 완료되면 `devport-output/wiki/{owner}/{repo}/README.md`와 섹션별 Markdown 파일이 생성됩니다.
 
-### 2. 증분 업데이트 (Incremental Update)
+### 3. 증분 업데이트 (Incremental Update)
 
 이전에 작성 완료된 위키를 바탕으로 변경된 파일들만 식별하여 최신화합니다.
 
 ```bash
 # 1. 변경사항 감지
-npx tsx src/agent.ts detect --repo owner/repo
+portki detect --repo owner/repo
 # 반환된 JSON의 status에 따라 분기:
 # - noop: 변경점 없음 (수정 불필요)
 # - incremental: 변경된 코드와 영향을 받는 섹션(impacted_section_ids)만 재생성
 # - full-rebuild: 너무 많은 변화로 인해 전체 위키 재작성 필요
 
 # 2. 재생성 필요 시 최신 코드로 스냅샷 다시 수집
-npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
+portki ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
 
 # (이후 영향을 받는 섹션만 다시 작성하여 persist-section 후 finalize 수행)
 ```

package/dist/cli.js

@@ -1,6 +1,6 @@
 // src/agent.ts
-import path13 from "node:path";
-import { mkdir as mkdir2, writeFile as writeFile2, readFile as readFile2 } from "node:fs/promises";
+import path18 from "node:path";
+import { mkdir as mkdir4, writeFile as writeFile5, readFile as readFile4 } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 
 // src/shared/load-env.ts
@@ -2848,8 +2848,8 @@ function compareDeterministic(left, right) {
 }
 function toOrderedUniquePaths(paths) {
   const unique = /* @__PURE__ */ new Set();
-  for (const path14 of paths) {
-    const normalized = normalizeRepoPath(path14);
+  for (const path19 of paths) {
+    const normalized = normalizeRepoPath(path19);
     if (normalized.length > 0) {
       unique.add(normalized);
     }
@@ -2873,15 +2873,15 @@ function mapChangedPathsToImpactedSections(input) {
   }));
   for (const section of normalizedSectionPaths) {
     const sectionPaths = section.repoPaths;
-    for (const path14 of changedPaths) {
-      if (sectionPaths.has(path14)) {
+    for (const path19 of changedPaths) {
+      if (sectionPaths.has(path19)) {
         impacted.add(section.sectionId);
-        matchedPaths.add(path14);
+        matchedPaths.add(path19);
       }
     }
   }
   const impacted_section_ids = [...impacted].sort(compareDeterministic);
-  const unmatched_changed_paths = changedPaths.filter((path14) => !matchedPaths.has(path14));
+  const unmatched_changed_paths = changedPaths.filter((path19) => !matchedPaths.has(path19));
   if (impacted_section_ids.length === 0) {
     return {
       mode: "full-rebuild-required",
@@ -3933,6 +3933,602 @@ async function finalize(session, plan, options) {
   return result;
 }
 
+// src/commands/wiki.ts
+import path13 from "node:path";
+import { mkdir as mkdir2, writeFile as writeFile2 } from "node:fs/promises";
+
+// src/commands/handoff.ts
+function renderHandoff(opts) {
+  const {
+    ownerRepo,
+    slug,
+    artifactPath,
+    planContextPath,
+    artifact,
+    planContext: ctx,
+    stepOverrides,
+    persistedSections
+  } = opts;
+  const step = (name, fallback) => stepOverrides?.[name] ?? fallback;
+  const persistedSet = new Set(persistedSections ?? []);
+  const sectionPlanPath = `devport-output/workspace/${slug}-section-plan.json`;
+  const profileLines = [
+    `- **Repo**: ${ownerRepo}`,
+    `- **Commit**: ${artifact.commit_sha.slice(0, 7)}`,
+    `- **Language**: ${ctx.profile.primaryLanguage}`,
+    `- **Type**: ${ctx.profile.projectType}`,
+    `- **Domain**: ${ctx.profile.domainHint}`,
+    `- **Files scanned**: ${artifact.files_scanned.toLocaleString("en-US")}`,
+    `- **Snapshot**: ${artifact.snapshot_path}`
+  ];
+  const keyPathsList = ctx.keyPaths.slice(0, 20).map((p) => `  - \`${p}\``).join("\n");
+  const sectionExample = JSON.stringify(
+    {
+      sectionId: "sec-1",
+      titleKo: "\uD504\uB85C\uC81D\uD2B8 \uAC1C\uC694 \uBC0F \uC544\uD0A4\uD14D\uCC98",
+      summaryKo: "\uC774 \uC139\uC158\uC5D0\uC11C\uB294 \uD504\uB85C\uC81D\uD2B8\uC758 \uBAA9\uC801\uACFC \uC804\uCCB4 \uAD6C\uC870\uB97C \uC124\uBA85\uD569\uB2C8\uB2E4.",
+      sourcePaths: ["README.md", "src/main.ts"],
+      subsections: [
+        {
+          subsectionId: "sub-1-1",
+          titleKo: "\uD504\uB85C\uC81D\uD2B8 \uC18C\uAC1C",
+          bodyKo: "(3000\uC790 \uC774\uC0C1\uC758 \uD55C\uAD6D\uC5B4 \uC124\uBA85...)",
+          sourcePaths: ["README.md"]
+        }
+      ]
+    },
+    null,
+    2
+  );
+  const lines = [
+    `# Handoff: ${ownerRepo}`,
+    "",
+    "This file was generated by `portki`. Follow the steps below to complete the wiki generation.",
+    "",
+    "## Pipeline Status",
+    "",
+    `| Step | Status |`,
+    `|------|--------|`,
+    `| ingest | ${step("ingest", "DONE")} |`,
+    `| plan-sections | ${step("plan-sections", "DONE")} |`,
+    `| write section-plan.json | ${step("write-plan", "PENDING")} |`,
+    `| validate-plan | ${step("validate-plan", "PENDING")} |`,
+    `| write & persist sections | ${step("persist-sections", "PENDING")} |`,
+    `| finalize | ${step("finalize", "PENDING")} |`,
+    "",
+    "## Repo Profile",
+    "",
+    ...profileLines,
+    "",
+    "## Key Paths to Read",
+    "",
+    keyPathsList,
+    "",
+    "## Artifact Files",
+    "",
+    `- Artifact: \`${artifactPath}\``,
+    `- Plan context: \`${planContextPath}\``,
+    `- Section plan (you write this): \`${sectionPlanPath}\``,
+    "",
+    "## Steps",
+    "",
+    "### Step 1: Read the plan context",
+    "",
+    `Read \`${planContextPath}\` to understand the repo structure, profile, and constraints.`,
+    `Also read the README and key source files under \`${artifact.snapshot_path}\`.`,
+    "",
+    "### Step 2: Write section-plan.json",
+    "",
+    `Create \`${sectionPlanPath}\` with 4-6 sections. Each section needs:`,
+    "- `sectionId`: sec-1, sec-2, ...",
+    "- `titleKo`: Korean title (3+ chars)",
+    "- `summaryKo`: Korean summary (10+ chars)",
+    "- `focusPaths`: real paths from the snapshot",
+    "- `subsections`: array of 3+ subsections with subsectionId, titleKo, objectiveKo, targetEvidenceKinds, targetCharacterCount",
+    "",
+    "### Step 3: Validate the plan",
+    "",
+    "```bash",
+    `portki validate-plan --input ${sectionPlanPath} --context ${planContextPath} --out ${sectionPlanPath}`,
+    "```",
+    "",
+    "### Step 4: Write and persist each section",
+    "",
+    "For each section in the plan:",
+    "",
+    "1. Read the focus files listed in the section plan",
+    "2. Write a section output JSON file:",
+    "",
+    "```json",
+    sectionExample,
+    "```",
+    "",
+    "3. Persist it:",
+    "",
+    "```bash",
+    `portki persist-section --plan ${sectionPlanPath} --section sec-N --input devport-output/workspace/${slug}-section-N-output.json`,
+    "```",
+    ""
+  ];
+  if (persistedSections && persistedSections.length > 0) {
+    lines.push("**Section progress:**", "");
+    for (const secId of persistedSections) {
+      lines.push(`- [x] ${secId} (persisted)`);
+    }
+    lines.push("");
+  }
+  lines.push(
+    "### Step 5: Finalize",
+    "",
+    "```bash",
+    `portki finalize --plan ${sectionPlanPath} --advance_baseline`,
+    "```",
+    "",
+    `Output will be written to \`devport-output/wiki/${ownerRepo}/\`.`,
+    "",
+    "## Writing Rules",
+    "",
+    "- All Korean prose must use formal `\uD569\uB2C8\uB2E4` style",
+    "- Each `bodyKo` must be at least 3,000 characters",
+    "- Include at least one Mermaid architecture block across all sections",
+    "- `sourcePaths` must be real snapshot paths",
+    "- `sub-1-1` is the project introduction summary (purpose, problem space, getting-started, section map)",
+    "- Code call-flow analysis should begin in `sub-1-2` or later",
+    "- Do not use repetitive filler blocks",
+    ""
+  );
+  return lines.join("\n");
+}
+
+// src/commands/wiki.ts
+function repoSlug(ownerRepo) {
+  const parts = ownerRepo.split("/");
+  return parts[parts.length - 1] ?? ownerRepo;
+}
+function workspacePath(ownerRepo, suffix) {
+  const slug = repoSlug(ownerRepo);
+  return `devport-output/workspace/${slug}-${suffix}`;
+}
+async function wikiCommand(ownerRepo, flags) {
+  const parts = ownerRepo.toLowerCase().split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(`Invalid repo format: ${ownerRepo}. Use owner/repo.`);
+  }
+  const repo = `${parts[0]}/${parts[1]}`;
+  const slug = repoSlug(repo);
+  const snapshotRoot = flags["snapshot_root"] ?? "devport-output/snapshots";
+  process.stderr.write(`[portki] ${repo} \u2014 ingesting...
+`);
+  const ref = flags["ref"];
+  const artifact = await runIngest({
+    repo_ref: { repo, ...ref ? { ref } : {} },
+    snapshot_root: path13.resolve(snapshotRoot),
+    force_rebuild: flags["force_rebuild"] === "true"
+  });
+  const cacheLabel = artifact.idempotent_hit ? "cache hit" : "downloaded";
+  process.stderr.write(
+    `  ingest: ${artifact.commit_sha.slice(0, 7)} \u2014 ${artifact.files_scanned.toLocaleString("en-US")} files (${cacheLabel})
+`
+  );
+  const artifactPath = workspacePath(repo, "artifact.json");
+  await mkdir2(path13.dirname(path13.resolve(artifactPath)), { recursive: true });
+  await writeFile2(
+    path13.resolve(artifactPath),
+    `${JSON.stringify(artifact, null, 2)}
+`,
+    "utf8"
+  );
+  process.stderr.write(`  plan-sections: analyzing...
+`);
+  const ctx = await planContext(artifact);
+  const planContextPath = workspacePath(repo, "plan-context.json");
+  await writeFile2(
+    path13.resolve(planContextPath),
+    `${JSON.stringify(ctx, null, 2)}
+`,
+    "utf8"
+  );
+  process.stderr.write(
+    `  plan-sections: ${ctx.profile.projectType}, ${ctx.profile.primaryLanguage}, ${ctx.profile.domainHint}
+`
+  );
+  const handoffPath = workspacePath(repo, "handoff.md");
+  const handoff = renderHandoff({
+    ownerRepo: repo,
+    slug,
+    artifactPath,
+    planContextPath,
+    artifact,
+    planContext: ctx
+  });
+  await writeFile2(path13.resolve(handoffPath), handoff, "utf8");
+  process.stderr.write(
+    `
+  Done. Follow the handoff to complete wiki generation:
+  ${handoffPath}
+
+`
+  );
+  process.stdout.write(`${path13.resolve(handoffPath)}
+`);
+}
+
+// src/commands/status.ts
+import { existsSync as existsSync4 } from "node:fs";
+import path14 from "node:path";
+async function statusCommand(argv) {
+  const ownerRepo = argv[0];
+  if (!ownerRepo || !ownerRepo.includes("/")) {
+    throw new Error("Usage: portki status owner/repo");
+  }
+  const repo = ownerRepo.toLowerCase();
+  const slug = repoSlug(repo);
+  process.stderr.write(`[portki] status: ${repo}
+
+`);
+  const checks = [
+    { label: "ingest (artifact)", path: workspacePath(repo, "artifact.json"), done: false },
+    { label: "plan-sections (context)", path: workspacePath(repo, "plan-context.json"), done: false },
+    { label: "section-plan.json", path: workspacePath(repo, "section-plan.json"), done: false },
+    { label: "handoff.md", path: workspacePath(repo, "handoff.md"), done: false }
+  ];
+  for (const check of checks) {
+    check.done = existsSync4(path14.resolve(check.path));
+    const icon = check.done ? "+" : "-";
+    process.stderr.write(`  [${icon}] ${check.label}
+`);
+  }
+  const sessionPath = sessionPathForRepo(repo);
+  const session = await loadSession(sessionPath);
+  if (session) {
+    process.stderr.write(`
+  Session: ${session.sessionId}
+`);
+    const sectionIds = Object.keys(session.sections).sort();
+    let persisted = 0;
+    for (const secId of sectionIds) {
+      const sec = session.sections[secId];
+      const icon = sec.status === "persisted" ? "+" : "-";
+      process.stderr.write(`    [${icon}] ${secId}: ${sec.status}
+`);
+      if (sec.status === "persisted") persisted++;
+    }
+    process.stderr.write(`
+  Sections: ${persisted}/${sectionIds.length} persisted
+`);
+  } else {
+    process.stderr.write(`
+  No session found yet.
+`);
+  }
+  const wikiReadme = `devport-output/wiki/${repo}/README.md`;
+  const finalized = existsSync4(path14.resolve(wikiReadme));
+  const fIcon = finalized ? "+" : "-";
+  process.stderr.write(`  [${fIcon}] finalized (wiki output)
+`);
+  process.stderr.write("\n");
+}
+
+// src/commands/resume.ts
+import { existsSync as existsSync5 } from "node:fs";
+import { readFile as readFile2, writeFile as writeFile3 } from "node:fs/promises";
+import path15 from "node:path";
+async function resumeCommand(argv) {
+  const ownerRepo = argv[0];
+  if (!ownerRepo || !ownerRepo.includes("/")) {
+    throw new Error("Usage: portki resume owner/repo");
+  }
+  const repo = ownerRepo.toLowerCase();
+  const slug = repoSlug(repo);
+  process.stderr.write(`[portki] resume: ${repo}
+`);
+  const artifactPath = workspacePath(repo, "artifact.json");
+  if (!existsSync5(path15.resolve(artifactPath))) {
+    throw new Error(
+      `No artifact found at ${artifactPath}. Run \`portki ${repo}\` first.`
+    );
+  }
+  const artifactRaw = await readFile2(path15.resolve(artifactPath), "utf8");
+  const artifact = ingestRunArtifactSchema.parse(JSON.parse(artifactRaw));
+  const planContextPath = workspacePath(repo, "plan-context.json");
+  let ctx;
+  if (existsSync5(path15.resolve(planContextPath))) {
+    const raw = await readFile2(path15.resolve(planContextPath), "utf8");
+    ctx = PlanContextSchema.parse(JSON.parse(raw));
+    process.stderr.write(`  plan-context: loaded from cache
+`);
+  } else {
+    process.stderr.write(`  plan-context: regenerating...
+`);
+    ctx = await planContext(artifact);
+    await writeFile3(
+      path15.resolve(planContextPath),
+      `${JSON.stringify(ctx, null, 2)}
+`,
+      "utf8"
+    );
+  }
+  const sessionPath = sessionPathForRepo(repo);
+  const session = await loadSession(sessionPath);
+  const persistedSections = [];
+  const stepOverrides = {
+    ingest: "DONE",
+    "plan-sections": "DONE"
+  };
+  if (session) {
+    for (const [secId, sec] of Object.entries(session.sections)) {
+      if (sec.status === "persisted") {
+        persistedSections.push(secId);
+      }
+    }
+    const sectionPlanPath = workspacePath(repo, "section-plan.json");
+    if (existsSync5(path15.resolve(sectionPlanPath))) {
+      stepOverrides["write-plan"] = "DONE";
+      stepOverrides["validate-plan"] = "DONE";
+    }
+    if (persistedSections.length > 0) {
+      const total = Object.keys(session.sections).length;
+      if (persistedSections.length >= total) {
+        stepOverrides["persist-sections"] = "DONE";
+      }
+    }
+  }
+  const handoffPath = workspacePath(repo, "handoff.md");
+  const handoff = renderHandoff({
+    ownerRepo: repo,
+    slug,
+    artifactPath,
+    planContextPath,
+    artifact,
+    planContext: ctx,
+    stepOverrides,
+    persistedSections
+  });
+  await writeFile3(path15.resolve(handoffPath), handoff, "utf8");
+  if (persistedSections.length > 0) {
+    process.stderr.write(
+      `  ${persistedSections.length} section(s) already persisted: ${persistedSections.join(", ")}
+`
+    );
+  }
+  process.stderr.write(
+    `
+  Handoff regenerated:
+  ${handoffPath}
+
+`
+  );
+  process.stdout.write(`${path15.resolve(handoffPath)}
+`);
+}
+
+// src/commands/doctor.ts
+import { existsSync as existsSync6 } from "node:fs";
+import { access, readdir, constants } from "node:fs/promises";
+import path16 from "node:path";
+async function doctorCommand() {
+  process.stderr.write(`[portki] doctor
+
+`);
+  let allOk = true;
+  const nodeVersion = process.versions.node;
+  const major = parseInt(nodeVersion.split(".")[0], 10);
+  const nodeOk = major >= 20;
+  process.stderr.write(
+    `  ${nodeOk ? "ok" : "FAIL"} Node.js ${nodeVersion}${nodeOk ? "" : " (requires >= 20)"}
+`
+  );
+  if (!nodeOk) allOk = false;
+  const outputDir = path16.resolve("devport-output");
+  let writable = false;
+  if (existsSync6(outputDir)) {
+    try {
+      await access(outputDir, constants.W_OK);
+      writable = true;
+    } catch {
+    }
+  } else {
+    writable = true;
+  }
+  process.stderr.write(
+    `  ${writable ? "ok" : "FAIL"} devport-output/ ${existsSync6(outputDir) ? "writable" : "will be created on first run"}
+`
+  );
+  if (!writable) allOk = false;
+  const chunkedDir = path16.resolve("devport-output/chunked");
+  let sessionCount = 0;
+  if (existsSync6(chunkedDir)) {
+    try {
+      const owners = await readdir(chunkedDir, { withFileTypes: true });
+      for (const owner of owners) {
+        if (!owner.isDirectory()) continue;
+        const repos = await readdir(path16.join(chunkedDir, owner.name), { withFileTypes: true });
+        for (const repo of repos) {
+          if (!repo.isDirectory()) continue;
+          const sessionPath = path16.join(chunkedDir, owner.name, repo.name, "session.json");
+          if (existsSync6(sessionPath)) sessionCount++;
+        }
+      }
+    } catch {
+    }
+  }
+  process.stderr.write(`  ok Active sessions: ${sessionCount}
+`);
+  const hasToken = !!process.env["GITHUB_TOKEN"];
+  process.stderr.write(
+    `  ${hasToken ? "ok" : "info"} GITHUB_TOKEN: ${hasToken ? "set" : "not set (optional, public repos work without it)"}
+`
+  );
+  process.stderr.write(`
+  ${allOk ? "All checks passed." : "Some checks failed."}
+
+`);
+  if (!allOk) {
+    process.exitCode = 1;
+  }
+}
+
+// src/commands/install.ts
+import { mkdir as mkdir3, writeFile as writeFile4, readFile as readFile3, appendFile } from "node:fs/promises";
+import { existsSync as existsSync7 } from "node:fs";
+import path17 from "node:path";
+var CLAUDE_TEMPLATE = `# portki \u2014 Generate Korean Wiki
+
+GitHub \uC800\uC7A5\uC18C\uC758 \uD55C\uAD6D\uC5B4 \uC704\uD0A4\uB97C \uC0DD\uC131\uD569\uB2C8\uB2E4.
+
+## \uC2E4\uD589
+
+\`\`\`
+portki $ARGUMENTS
+\`\`\`
+
+## \uC2E4\uD589 \uD6C4 \uD574\uC57C \uD560 \uC77C
+
+portki\uB97C \uC2E4\uD589\uD558\uBA74 stdout\uC5D0 handoff.md \uACBD\uB85C\uAC00 \uCD9C\uB825\uB429\uB2C8\uB2E4. \uBC18\uB4DC\uC2DC \uC544\uB798 \uC21C\uC11C\uB97C \uB530\uB974\uC138\uC694:
+
+1. **handoff.md\uB97C \uC77D\uC2B5\uB2C8\uB2E4.** \uD30C\uC774\uD504\uB77C\uC778 \uC0C1\uD0DC, \uC800\uC7A5\uC18C \uD504\uB85C\uD544, \uC2A4\uB0C5\uC0F7 \uACBD\uB85C, \uC791\uC131 \uADDC\uCE59\uC774 \uBAA8\uB450 \uB4E4\uC5B4 \uC788\uC2B5\uB2C8\uB2E4.
+2. **\uC2A4\uB0C5\uC0F7\uC758 \uC8FC\uC694 \uC18C\uC2A4 \uD30C\uC77C\uC744 \uC77D\uC2B5\uB2C8\uB2E4.** handoff.md\uC758 "Key Paths to Read" \uC139\uC158\uC5D0 \uB098\uC5F4\uB41C \uD30C\uC77C\uB4E4\uC744 \uC6B0\uC120\uC73C\uB85C \uC77D\uC73C\uC138\uC694.
+3. **section-plan.json\uC744 \uC791\uC131\uD569\uB2C8\uB2E4.** handoff.md\uC758 \uACBD\uB85C\uC640 \uC2A4\uD0A4\uB9C8\uB97C \uB530\uB974\uC138\uC694. 4~6\uAC1C \uC139\uC158, \uAC01 \uC139\uC158 3\uAC1C \uC774\uC0C1\uC758 \uC11C\uBE0C\uC139\uC158.
+4. **\`portki validate-plan\`\uC744 \uC2E4\uD589\uD569\uB2C8\uB2E4.** handoff.md\uC5D0 \uC801\uD78C \uC815\uD655\uD55C \uBA85\uB839\uC5B4\uB97C \uC0AC\uC6A9\uD558\uC138\uC694.
+5. **\uAC01 \uC139\uC158\uC744 \uC791\uC131\uD569\uB2C8\uB2E4.** \uC139\uC158 \uD50C\uB79C\uC758 focusPaths\uC5D0 \uC788\uB294 \uD30C\uC77C\uB4E4\uC744 \uC77D\uACE0, section output JSON\uC744 \uC791\uC131\uD55C \uB4A4 \`portki persist-section\`\uC73C\uB85C \uAC80\uC99D\uD569\uB2C8\uB2E4. \uBAA8\uB4E0 \uC139\uC158\uC744 \uBC18\uBCF5\uD569\uB2C8\uB2E4.
+6. **\`portki finalize\`\uB97C \uC2E4\uD589\uD569\uB2C8\uB2E4.** handoff.md\uC5D0 \uC801\uD78C \uC815\uD655\uD55C \uBA85\uB839\uC5B4\uB97C \uC0AC\uC6A9\uD558\uC138\uC694.
+
+## \uC791\uC131 \uADDC\uCE59
+
+- \uBAA8\uB4E0 \uD55C\uAD6D\uC5B4 \uBB38\uC7A5\uC740 \`\uD569\uB2C8\uB2E4\` \uCCB4\uB97C \uC0AC\uC6A9\uD569\uB2C8\uB2E4.
+- \uAC01 bodyKo\uB294 \uCD5C\uC18C 3,000\uC790 \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.
+- \uC804\uCCB4 \uC704\uD0A4\uC5D0 \uCD5C\uC18C \uD558\uB098\uC758 Mermaid \uC544\uD0A4\uD14D\uCC98 \uBE14\uB85D\uC744 \uD3EC\uD568\uD569\uB2C8\uB2E4.
+- sourcePaths\uB294 \uBC18\uB4DC\uC2DC \uC2A4\uB0C5\uC0F7\uC5D0 \uC2E4\uC81C\uB85C \uC874\uC7AC\uD558\uB294 \uACBD\uB85C\uC5EC\uC57C \uD569\uB2C8\uB2E4.
+- sub-1-1\uC740 \uD504\uB85C\uC81D\uD2B8 \uC18C\uAC1C \uC694\uC57D\uC785\uB2C8\uB2E4 (\uBAA9\uC801, \uBB38\uC81C \uC601\uC5ED, \uC2DC\uC791 \uAC00\uC774\uB4DC, \uB098\uBA38\uC9C0 \uC139\uC158 \uC548\uB0B4).
+- \uCF54\uB4DC \uCF5C\uD50C\uB85C\uC6B0 \uBD84\uC11D\uC740 sub-1-2\uBD80\uD130 \uC2DC\uC791\uD569\uB2C8\uB2E4.
+- \uBC18\uBCF5\uC801\uC778 \uD544\uB7EC \uBB38\uC7A5\uC744 \uC0AC\uC6A9\uD558\uC9C0 \uB9C8\uC138\uC694.
+`;
+var CODEX_TEMPLATE = `
+## portki \u2014 Korean Wiki Generator
+
+GitHub \uC800\uC7A5\uC18C\uC758 \uD55C\uAD6D\uC5B4 \uC704\uD0A4\uB97C \uC0DD\uC131\uD569\uB2C8\uB2E4.
+
+### \uC2E4\uD589
+
+\`\`\`bash
+portki owner/repo
+\`\`\`
+
+### \uC2E4\uD589 \uD6C4 \uD574\uC57C \uD560 \uC77C
+
+portki\uB97C \uC2E4\uD589\uD558\uBA74 stdout\uC5D0 handoff.md \uACBD\uB85C\uAC00 \uCD9C\uB825\uB429\uB2C8\uB2E4. \uBC18\uB4DC\uC2DC \uC544\uB798 \uC21C\uC11C\uB97C \uB530\uB974\uC138\uC694:
+
+1. **handoff.md\uB97C \uC77D\uC2B5\uB2C8\uB2E4.** \uD30C\uC774\uD504\uB77C\uC778 \uC0C1\uD0DC, \uC800\uC7A5\uC18C \uD504\uB85C\uD544, \uC2A4\uB0C5\uC0F7 \uACBD\uB85C, \uC791\uC131 \uADDC\uCE59\uC774 \uBAA8\uB450 \uB4E4\uC5B4 \uC788\uC2B5\uB2C8\uB2E4.
+2. **\uC2A4\uB0C5\uC0F7\uC758 \uC8FC\uC694 \uC18C\uC2A4 \uD30C\uC77C\uC744 \uC77D\uC2B5\uB2C8\uB2E4.** handoff.md\uC758 "Key Paths to Read" \uC139\uC158\uC5D0 \uB098\uC5F4\uB41C \uD30C\uC77C\uB4E4\uC744 \uC6B0\uC120\uC73C\uB85C \uC77D\uC73C\uC138\uC694.
+3. **section-plan.json\uC744 \uC791\uC131\uD569\uB2C8\uB2E4.** handoff.md\uC758 \uACBD\uB85C\uC640 \uC2A4\uD0A4\uB9C8\uB97C \uB530\uB974\uC138\uC694. 4~6\uAC1C \uC139\uC158, \uAC01 \uC139\uC158 3\uAC1C \uC774\uC0C1\uC758 \uC11C\uBE0C\uC139\uC158.
+4. **\`portki validate-plan\`\uC744 \uC2E4\uD589\uD569\uB2C8\uB2E4.** handoff.md\uC5D0 \uC801\uD78C \uC815\uD655\uD55C \uBA85\uB839\uC5B4\uB97C \uC0AC\uC6A9\uD558\uC138\uC694.
+5. **\uAC01 \uC139\uC158\uC744 \uC791\uC131\uD569\uB2C8\uB2E4.** \uC139\uC158 \uD50C\uB79C\uC758 focusPaths\uC5D0 \uC788\uB294 \uD30C\uC77C\uB4E4\uC744 \uC77D\uACE0, section output JSON\uC744 \uC791\uC131\uD55C \uB4A4 \`portki persist-section\`\uC73C\uB85C \uAC80\uC99D\uD569\uB2C8\uB2E4. \uBAA8\uB4E0 \uC139\uC158\uC744 \uBC18\uBCF5\uD569\uB2C8\uB2E4.
+6. **\`portki finalize\`\uB97C \uC2E4\uD589\uD569\uB2C8\uB2E4.** handoff.md\uC5D0 \uC801\uD78C \uC815\uD655\uD55C \uBA85\uB839\uC5B4\uB97C \uC0AC\uC6A9\uD558\uC138\uC694.
+
+### \uBCF4\uC870 \uBA85\uB839\uC5B4
+
+- \`portki status owner/repo\` \u2014 \uC9C4\uD589 \uC0C1\uD669 \uD655\uC778
+- \`portki resume owner/repo\` \u2014 \uC911\uB2E8\uB41C \uC791\uC5C5 \uC774\uC5B4\uC11C \uD558\uAE30
+
+### \uC791\uC131 \uADDC\uCE59
+
+- \uBAA8\uB4E0 \uD55C\uAD6D\uC5B4 \uBB38\uC7A5\uC740 \`\uD569\uB2C8\uB2E4\` \uCCB4\uB97C \uC0AC\uC6A9\uD569\uB2C8\uB2E4.
+- \uAC01 bodyKo\uB294 \uCD5C\uC18C 3,000\uC790 \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.
+- \uC804\uCCB4 \uC704\uD0A4\uC5D0 \uCD5C\uC18C \uD558\uB098\uC758 Mermaid \uC544\uD0A4\uD14D\uCC98 \uBE14\uB85D\uC744 \uD3EC\uD568\uD569\uB2C8\uB2E4.
+- sourcePaths\uB294 \uBC18\uB4DC\uC2DC \uC2A4\uB0C5\uC0F7\uC5D0 \uC2E4\uC81C\uB85C \uC874\uC7AC\uD558\uB294 \uACBD\uB85C\uC5EC\uC57C \uD569\uB2C8\uB2E4.
+- sub-1-1\uC740 \uD504\uB85C\uC81D\uD2B8 \uC18C\uAC1C \uC694\uC57D\uC785\uB2C8\uB2E4 (\uBAA9\uC801, \uBB38\uC81C \uC601\uC5ED, \uC2DC\uC791 \uAC00\uC774\uB4DC, \uB098\uBA38\uC9C0 \uC139\uC158 \uC548\uB0B4).
+- \uCF54\uB4DC \uCF5C\uD50C\uB85C\uC6B0 \uBD84\uC11D\uC740 sub-1-2\uBD80\uD130 \uC2DC\uC791\uD569\uB2C8\uB2E4.
+- \uBC18\uBCF5\uC801\uC778 \uD544\uB7EC \uBB38\uC7A5\uC744 \uC0AC\uC6A9\uD558\uC9C0 \uB9C8\uC138\uC694.
+`;
+var GEMINI_TEMPLATE = `# portki \u2014 Generate Korean Wiki
+
+GitHub \uC800\uC7A5\uC18C\uC758 \uD55C\uAD6D\uC5B4 \uC704\uD0A4\uB97C \uC0DD\uC131\uD569\uB2C8\uB2E4.
+
+## \uC2E4\uD589
+
+\`\`\`
+portki $ARGUMENTS
+\`\`\`
+
+## \uC2E4\uD589 \uD6C4 \uD574\uC57C \uD560 \uC77C
+
+portki\uB97C \uC2E4\uD589\uD558\uBA74 stdout\uC5D0 handoff.md \uACBD\uB85C\uAC00 \uCD9C\uB825\uB429\uB2C8\uB2E4. \uBC18\uB4DC\uC2DC \uC544\uB798 \uC21C\uC11C\uB97C \uB530\uB974\uC138\uC694:
+
+1. **handoff.md\uB97C \uC77D\uC2B5\uB2C8\uB2E4.** \uD30C\uC774\uD504\uB77C\uC778 \uC0C1\uD0DC, \uC800\uC7A5\uC18C \uD504\uB85C\uD544, \uC2A4\uB0C5\uC0F7 \uACBD\uB85C, \uC791\uC131 \uADDC\uCE59\uC774 \uBAA8\uB450 \uB4E4\uC5B4 \uC788\uC2B5\uB2C8\uB2E4.
+2. **\uC2A4\uB0C5\uC0F7\uC758 \uC8FC\uC694 \uC18C\uC2A4 \uD30C\uC77C\uC744 \uC77D\uC2B5\uB2C8\uB2E4.** handoff.md\uC758 "Key Paths to Read" \uC139\uC158\uC5D0 \uB098\uC5F4\uB41C \uD30C\uC77C\uB4E4\uC744 \uC6B0\uC120\uC73C\uB85C \uC77D\uC73C\uC138\uC694.
+3. **section-plan.json\uC744 \uC791\uC131\uD569\uB2C8\uB2E4.** handoff.md\uC758 \uACBD\uB85C\uC640 \uC2A4\uD0A4\uB9C8\uB97C \uB530\uB974\uC138\uC694. 4~6\uAC1C \uC139\uC158, \uAC01 \uC139\uC158 3\uAC1C \uC774\uC0C1\uC758 \uC11C\uBE0C\uC139\uC158.
+4. **\`portki validate-plan\`\uC744 \uC2E4\uD589\uD569\uB2C8\uB2E4.** handoff.md\uC5D0 \uC801\uD78C \uC815\uD655\uD55C \uBA85\uB839\uC5B4\uB97C \uC0AC\uC6A9\uD558\uC138\uC694.
+5. **\uAC01 \uC139\uC158\uC744 \uC791\uC131\uD569\uB2C8\uB2E4.** \uC139\uC158 \uD50C\uB79C\uC758 focusPaths\uC5D0 \uC788\uB294 \uD30C\uC77C\uB4E4\uC744 \uC77D\uACE0, section output JSON\uC744 \uC791\uC131\uD55C \uB4A4 \`portki persist-section\`\uC73C\uB85C \uAC80\uC99D\uD569\uB2C8\uB2E4. \uBAA8\uB4E0 \uC139\uC158\uC744 \uBC18\uBCF5\uD569\uB2C8\uB2E4.
+6. **\`portki finalize\`\uB97C \uC2E4\uD589\uD569\uB2C8\uB2E4.** handoff.md\uC5D0 \uC801\uD78C \uC815\uD655\uD55C \uBA85\uB839\uC5B4\uB97C \uC0AC\uC6A9\uD558\uC138\uC694.
+
+## \uC791\uC131 \uADDC\uCE59
+
+- \uBAA8\uB4E0 \uD55C\uAD6D\uC5B4 \uBB38\uC7A5\uC740 \`\uD569\uB2C8\uB2E4\` \uCCB4\uB97C \uC0AC\uC6A9\uD569\uB2C8\uB2E4.
+- \uAC01 bodyKo\uB294 \uCD5C\uC18C 3,000\uC790 \uC774\uC0C1\uC774\uC5B4\uC57C \uD569\uB2C8\uB2E4.
+- \uC804\uCCB4 \uC704\uD0A4\uC5D0 \uCD5C\uC18C \uD558\uB098\uC758 Mermaid \uC544\uD0A4\uD14D\uCC98 \uBE14\uB85D\uC744 \uD3EC\uD568\uD569\uB2C8\uB2E4.
+- sourcePaths\uB294 \uBC18\uB4DC\uC2DC \uC2A4\uB0C5\uC0F7\uC5D0 \uC2E4\uC81C\uB85C \uC874\uC7AC\uD558\uB294 \uACBD\uB85C\uC5EC\uC57C \uD569\uB2C8\uB2E4.
+- sub-1-1\uC740 \uD504\uB85C\uC81D\uD2B8 \uC18C\uAC1C \uC694\uC57D\uC785\uB2C8\uB2E4 (\uBAA9\uC801, \uBB38\uC81C \uC601\uC5ED, \uC2DC\uC791 \uAC00\uC774\uB4DC, \uB098\uBA38\uC9C0 \uC139\uC158 \uC548\uB0B4).
+- \uCF54\uB4DC \uCF5C\uD50C\uB85C\uC6B0 \uBD84\uC11D\uC740 sub-1-2\uBD80\uD130 \uC2DC\uC791\uD569\uB2C8\uB2E4.
+- \uBC18\uBCF5\uC801\uC778 \uD544\uB7EC \uBB38\uC7A5\uC744 \uC0AC\uC6A9\uD558\uC9C0 \uB9C8\uC138\uC694.
+`;
+async function installCommand(flags) {
+  const agent = flags["agent"];
+  if (!agent) {
+    throw new Error("Usage: portki install --agent claude|codex|gemini");
+  }
+  const normalized = agent.toLowerCase();
+  switch (normalized) {
+    case "claude": {
+      const dir = path17.resolve(".claude", "commands");
+      const filePath = path17.join(dir, "portki.md");
+      await mkdir3(dir, { recursive: true });
+      await writeFile4(filePath, CLAUDE_TEMPLATE, "utf8");
+      process.stderr.write(`[portki] Installed Claude adapter:
+  ${filePath}
+`);
+      process.stderr.write(`  Use /portki owner/repo in Claude Code.
+
+`);
+      break;
+    }
+    case "codex": {
+      const agentsFile = path17.resolve("AGENTS.md");
+      if (existsSync7(agentsFile)) {
+        const existing = await readFile3(agentsFile, "utf8");
+        if (existing.includes("portki")) {
+          process.stderr.write(`[portki] AGENTS.md already contains portki section. Skipping.
+
+`);
+          return;
+        }
+        await appendFile(agentsFile, CODEX_TEMPLATE, "utf8");
+      } else {
+        await writeFile4(agentsFile, CODEX_TEMPLATE.trimStart(), "utf8");
+      }
+      process.stderr.write(`[portki] Installed Codex adapter:
+  ${agentsFile}
+
+`);
+      break;
+    }
+    case "gemini": {
+      const dir = path17.resolve(".gemini", "commands");
+      const filePath = path17.join(dir, "portki.md");
+      await mkdir3(dir, { recursive: true });
+      await writeFile4(filePath, GEMINI_TEMPLATE, "utf8");
+      process.stderr.write(`[portki] Installed Gemini adapter:
+  ${filePath}
+`);
+      process.stderr.write(`  Use /portki owner/repo in Gemini.
+
+`);
+      break;
+    }
+    default:
+      throw new Error(`Unknown agent: ${agent}. Supported: claude, codex, gemini`);
+  }
+}
+
 // src/agent.ts
 function getQualityGateLevel(env) {
   const val = env.DEVPORT_QUALITY_GATE_LEVEL;
@@ -3990,7 +4586,7 @@ async function ingestCommand(flags) {
 `);
   const artifact = await runIngest({
     repo_ref: { repo, ...ref ? { ref } : {} },
-    snapshot_root: path13.resolve(snapshotRoot),
+    snapshot_root: path18.resolve(snapshotRoot),
     force_rebuild: flags["force_rebuild"] === "true"
   });
   const cacheLabel = artifact.idempotent_hit ? "cache hit" : "downloaded";
@@ -4003,9 +4599,9 @@ async function ingestCommand(flags) {
   const json = `${JSON.stringify(artifact, null, 2)}
 `;
   if (outFile) {
-    const outPath = path13.resolve(outFile);
-    await mkdir2(path13.dirname(outPath), { recursive: true });
-    await writeFile2(outPath, json, "utf8");
+    const outPath = path18.resolve(outFile);
+    await mkdir4(path18.dirname(outPath), { recursive: true });
+    await writeFile5(outPath, json, "utf8");
     process.stderr.write(`  artifact \u2192 ${outPath}
 `);
   } else {
@@ -4097,7 +4693,7 @@ async function packageCommand(flags) {
   const qualityGateLevel = resolveQualityGateLevel(flags, getQualityGateLevel(process.env));
   let raw;
   if (inputFile) {
-    raw = await readFile2(path13.resolve(inputFile), "utf8");
+    raw = await readFile4(path18.resolve(inputFile), "utf8");
   } else {
     raw = await readStdin();
   }
@@ -4150,7 +4746,7 @@ async function packageCommand(flags) {
 async function planSectionsCommand(flags) {
   const artifactFile = requireFlag(flags, "artifact");
   const outFile = flags["out"];
-  const raw = await readFile2(path13.resolve(artifactFile), "utf8");
+  const raw = await readFile4(path18.resolve(artifactFile), "utf8");
   const artifact = ingestRunArtifactSchema.parse(JSON.parse(raw));
   process.stderr.write(
     `[devport-agent] plan-sections: ${artifact.repo_ref} (${fmtNum(artifact.files_scanned)} files)
@@ -4167,9 +4763,9 @@ async function planSectionsCommand(flags) {
   const json = `${JSON.stringify(context, null, 2)}
 `;
   if (outFile) {
-    const outPath = path13.resolve(outFile);
-    await mkdir2(path13.dirname(outPath), { recursive: true });
-    await writeFile2(outPath, json, "utf8");
+    const outPath = path18.resolve(outFile);
+    await mkdir4(path18.dirname(outPath), { recursive: true });
+    await writeFile5(outPath, json, "utf8");
     process.stderr.write(`  context \u2192 ${outPath}
 `);
   } else {
@@ -4180,9 +4776,9 @@ async function validatePlanCommand(flags) {
   const inputFile = requireFlag(flags, "input");
   const contextFile = requireFlag(flags, "context");
   const outFile = flags["out"];
-  const contextRaw = await readFile2(path13.resolve(contextFile), "utf8");
+  const contextRaw = await readFile4(path18.resolve(contextFile), "utf8");
   const context = PlanContextSchema.parse(JSON.parse(contextRaw));
-  const planRaw = await readFile2(path13.resolve(inputFile), "utf8");
+  const planRaw = await readFile4(path18.resolve(inputFile), "utf8");
   const planJson = JSON.parse(planRaw);
   process.stderr.write(
     `[devport-agent] validate-plan: ${context.repoFullName}
@@ -4204,9 +4800,9 @@ async function validatePlanCommand(flags) {
   const json = `${JSON.stringify(validated, null, 2)}
 `;
   if (outFile) {
-    const outPath = path13.resolve(outFile);
-    await mkdir2(path13.dirname(outPath), { recursive: true });
-    await writeFile2(outPath, json, "utf8");
+    const outPath = path18.resolve(outFile);
+    await mkdir4(path18.dirname(outPath), { recursive: true });
+    await writeFile5(outPath, json, "utf8");
     process.stderr.write(`  validated plan \u2192 ${outPath}
 `);
   } else {
@@ -4218,9 +4814,9 @@ async function persistSectionCommand(flags) {
   const sectionId = requireFlag(flags, "section");
   const inputFile = requireFlag(flags, "input");
   const sessionFile = flags["session"];
-  const planRaw = await readFile2(path13.resolve(planFile), "utf8");
+  const planRaw = await readFile4(path18.resolve(planFile), "utf8");
   const plan = SectionPlanOutputSchema.parse(JSON.parse(planRaw));
-  const sectionRaw = await readFile2(path13.resolve(inputFile), "utf8");
+  const sectionRaw = await readFile4(path18.resolve(inputFile), "utf8");
   const sectionOutput = SectionOutputSchema.parse(JSON.parse(sectionRaw));
   if (sectionOutput.sectionId !== sectionId) {
     throw new Error(
@@ -4244,7 +4840,7 @@ async function persistSectionCommand(flags) {
   }
   process.stderr.write(`  \u2713 section validation passed
 `);
-  const sessionPath = sessionFile ? path13.resolve(sessionFile) : sessionPathForRepo(plan.repoFullName);
+  const sessionPath = sessionFile ? path18.resolve(sessionFile) : sessionPathForRepo(plan.repoFullName);
   let session = await loadSession(sessionPath);
   if (!session) {
     session = initSession(plan, planFile);
@@ -4256,7 +4852,7 @@ async function persistSectionCommand(flags) {
     koreanChars += sub.bodyKo.length;
   }
   session = markSectionPersisted(session, sectionId, {
-    sectionOutputPath: path13.resolve(inputFile),
+    sectionOutputPath: path18.resolve(inputFile),
     chunksInserted: 0,
     claimCount: 0,
     citationCount: 0,
@@ -4282,9 +4878,9 @@ async function finalizeCommand(flags) {
   const statePath = flags["state_path"] ?? "devport-output/freshness/state.json";
   const deleteSnapshot = flags["delete_snapshot"] === "true";
   const outDir = flags["out_dir"] ?? "devport-output/wiki";
-  const planRaw = await readFile2(path13.resolve(planFile), "utf8");
+  const planRaw = await readFile4(path18.resolve(planFile), "utf8");
   const plan = SectionPlanOutputSchema.parse(JSON.parse(planRaw));
-  const sessionPath = sessionFile ? path13.resolve(sessionFile) : sessionPathForRepo(plan.repoFullName);
+  const sessionPath = sessionFile ? path18.resolve(sessionFile) : sessionPathForRepo(plan.repoFullName);
   const session = await loadSession(sessionPath);
   if (!session) {
     throw new Error(
@@ -4327,72 +4923,57 @@ function printHelp() {
       "portki \u2014 public CLI for generating Korean Markdown wikis from GitHub repositories",
       "Run as an installed package with `portki <command>` or from source with `npx tsx src/agent.ts <command>`.",
       "",
-      "Commands:",
-      "  ingest   Snapshot a GitHub repo and emit the ingest artifact",
-      "           --repo owner/repo     (required)",
-      "           --ref  branch|sha     (optional, uses default branch if omitted)",
-      "           --out  artifact.json  (optional, prints to stdout if omitted)",
-      "           --snapshot_root       (default: devport-output/snapshots)",
-      "           --force_rebuild       (re-download even if cache is valid)",
+      "Quick start:",
+      "  portki owner/repo              Ingest repo + generate handoff.md for AI agents",
+      "",
+      "High-level commands:",
+      "  owner/repo     Ingest a repo, generate plan context and handoff.md",
+      "  status         Show pipeline progress          portki status owner/repo",
+      "  resume         Regenerate handoff from state    portki resume owner/repo",
+      "  doctor         Environment health check         portki doctor",
+      "  install        Install agent adapter            portki install --agent claude|codex|gemini",
+      "",
+      "Low-level commands:",
+      "  ingest           Snapshot a GitHub repo and emit the ingest artifact",
+      "                   --repo owner/repo     (required)",
+      "                   --ref  branch|sha     (optional, uses default branch if omitted)",
+      "                   --out  artifact.json  (optional, prints to stdout if omitted)",
+      "                   --snapshot_root       (default: devport-output/snapshots)",
+      "                   --force_rebuild       (re-download even if cache is valid)",
       "",
-      "  detect   Detect what changed since the last delivery",
-      "           --repo owner/repo     (required)",
-      "           --state_path          (default: devport-output/freshness/state.json)",
-      "           stdout: { status, changed_paths, impacted_section_ids, ... }",
-      "           status values: noop | incremental | full-rebuild",
+      "  detect           Detect what changed since the last delivery",
+      "                   --repo owner/repo     (required)",
+      "                   --state_path          (default: devport-output/freshness/state.json)",
       "",
-      "  package  Validate AI-generated GroundedAcceptedOutput, write markdown wiki files",
-      "           --input accepted-output.json  (optional, reads stdin if omitted)",
-      "           --out_dir                     (default: devport-output/wiki)",
-      "           --quality_gate_level          standard|strict (default from DEVPORT_QUALITY_GATE_LEVEL)",
-      "           --advance_baseline            save freshness state for future detect",
-      "           --state_path                  (default: devport-output/freshness/state.json)",
+      "  package          Validate AI-generated output, write markdown wiki files",
+      "                   --input accepted-output.json  (optional, reads stdin if omitted)",
+      "                   --out_dir                     (default: devport-output/wiki)",
+      "                   --quality_gate_level          standard|strict",
+      "                   --advance_baseline            save freshness state for future detect",
       "",
-      "  plan-sections  Analyze repo and produce planning context for AI section generation",
-      "                 --artifact artifact.json  (required)",
-      "                 --out plan-context.json   (optional, prints to stdout if omitted)",
+      "  plan-sections    Analyze repo and produce planning context",
+      "                   --artifact artifact.json  (required)",
+      "                   --out plan-context.json   (optional, prints to stdout if omitted)",
       "",
-      "  validate-plan  Validate an AI-generated section plan against the schema",
-      "                 --input section-plan.json    (required)",
-      "                 --context plan-context.json  (required)",
-      "                 --out section-plan.json      (optional, prints to stdout if omitted)",
+      "  validate-plan    Validate an AI-generated section plan",
+      "                   --input section-plan.json    (required)",
+      "                   --context plan-context.json  (required)",
+      "                   --out section-plan.json      (optional)",
       "",
-      "  persist-section  Validate a single section and register it in the local session",
+      "  persist-section  Validate a single section and register in session",
       "                   --plan section-plan.json   (required)",
       "                   --section sec-1            (required)",
       "                   --input section-1.json     (required)",
-      "                   --quality_gate_level       standard|strict (default from DEVPORT_QUALITY_GATE_LEVEL)",
-      "                   --session session.json     (optional, auto-derived from repo name)",
       "",
-      "  finalize  Cross-validate all sections and write the final markdown wiki bundle",
-      "            --plan section-plan.json   (required)",
-      "            --session session.json     (optional, auto-derived from repo name)",
-      "            --out_dir                  (default: devport-output/wiki)",
-      "            --advance_baseline         save freshness state for future detect",
-      "            --state_path               (default: devport-output/freshness/state.json)",
-      "            --delete_snapshot          delete snapshot directory after successful finalize",
-      "",
-      "First-run workflow (monolithic):",
-      "  1. portki ingest --repo owner/repo --out artifact.json",
-      "  2. AI reads artifact.json + files under snapshot_path, generates GroundedAcceptedOutput",
-      "  3. portki package --input accepted-output.json --advance_baseline",
-      "",
-      "Chunked workflow (higher quality, section-at-a-time):",
-      "  1. portki ingest --repo owner/repo --out artifact.json",
-      "  2. portki plan-sections --artifact artifact.json --out plan-context.json",
-      "  3. AI reads plan-context.json + README + code, generates section-plan.json",
-      "  4. portki validate-plan --input section-plan.json --context plan-context.json --out section-plan.json",
-      "  5. For each section: AI reads focus files, writes section-N.json",
-      "     portki persist-section --plan section-plan.json --section sec-N --input section-N.json",
-      "  6. portki finalize --plan section-plan.json --advance_baseline",
-      "     \u2192 writes README.md + section markdown files under devport-output/wiki/{owner}/{repo}/",
+      "  finalize         Cross-validate all sections and write final wiki",
+      "                   --plan section-plan.json   (required)",
+      "                   --advance_baseline         save freshness state",
       "",
-      "Incremental update workflow:",
-      "  1. portki detect --repo owner/repo",
-      "     \u2192 noop: done. incremental/full-rebuild: continue below",
-      "  2. portki ingest --repo owner/repo --out artifact.json",
-      "  3. AI regenerates (all or only impacted sections) \u2192 accepted-output.json",
-      "  4. portki package --input accepted-output.json --advance_baseline",
+      "Recommended workflow:",
+      "  1. portki owner/repo                          \u2192 generates handoff.md",
+      "  2. AI reads handoff.md and follows step-by-step instructions",
+      "  3. portki status owner/repo                   \u2192 check progress anytime",
+      "  4. portki resume owner/repo                   \u2192 recover from interruptions",
       ""
     ].join("\n")
   );
@@ -4407,6 +4988,22 @@ async function main() {
     return;
   }
   const flags = parseFlags(argv.slice(1));
+  if (command === "install") {
+    await installCommand(flags);
+    return;
+  }
+  if (command === "doctor") {
+    await doctorCommand();
+    return;
+  }
+  if (command === "status") {
+    await statusCommand(argv.slice(1));
+    return;
+  }
+  if (command === "resume") {
+    await resumeCommand(argv.slice(1));
+    return;
+  }
   if (command === "ingest") {
     await ingestCommand(flags);
     return;
@@ -4435,7 +5032,11 @@ async function main() {
     await finalizeCommand(flags);
     return;
   }
-  process.stderr.write(`[devport-agent] unknown command: ${command}
+  if (command.includes("/")) {
+    await wikiCommand(command, flags);
+    return;
+  }
+  process.stderr.write(`[portki] unknown command: ${command}
 `);
   printHelp();
   process.exitCode = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devport-kr/portki",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Public markdown-only CLI for generating Korean repository wikis from GitHub codebases",
   "type": "module",
   "private": false,