@devport-kr/portki 0.1.1 → 0.2.2

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
@@ -90,7 +90,7 @@ var resolvedIngestRefSchema = z.object({
 var ingestRunInputSchema = z.object({
   repo_ref: repoRefInputSchema,
   force_rebuild: z.boolean().default(false),
-  snapshot_root: z.string().trim().min(1).default("devport-output/snapshots"),
+  snapshot_root: z.string().trim().min(1).default("portki-output/snapshots"),
   now: z.function().args().returns(z.string()).optional(),
   fixture_commit: z.string().trim().min(4).optional()
 }).strict();
@@ -363,7 +363,7 @@ var RepoSnapshotManager = class {
     this.config = config;
     this.now = config.now || (() => (/* @__PURE__ */ new Date()).toISOString());
     this.forceRebuild = Boolean(config.forceRebuild);
-    this.rootPath = path2.resolve(config.snapshotRoot || "devport-output/snapshots");
+    this.rootPath = path2.resolve(config.snapshotRoot || "portki-output/snapshots");
     this.gitShell = config.gitShell || (config.sourcePath ? new LocalSourceShell(config.sourcePath) : defaultGitShell);
   }
   now;
@@ -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",
@@ -3575,7 +3575,7 @@ function validateSection(section, options) {
 import { promises as fs7 } from "node:fs";
 import path10 from "node:path";
 import crypto from "node:crypto";
-function sessionPathForRepo(repoFullName, rootDir = "devport-output/chunked") {
+function sessionPathForRepo(repoFullName, rootDir = "portki-output/chunked") {
   const [owner, repo] = repoFullName.split("/");
   if (!owner || !repo) {
     throw new Error(`Invalid repoFullName: ${repoFullName}`);
@@ -3742,7 +3742,7 @@ function renderSectionMarkdown(section, sectionIndex, sourcePaths) {
   return lines.join("\n").trimEnd();
 }
 async function writeMarkdownBundle(acceptedOutput, options = {}) {
-  const outputDir = buildOutputDir(options.outDir ?? "devport-output/wiki", acceptedOutput.repo_ref);
+  const outputDir = buildOutputDir(options.outDir ?? "portki-output/wiki", acceptedOutput.repo_ref);
   await mkdir(outputDir, { recursive: true });
   const files = [];
   const sectionFiles = acceptedOutput.draft.sections.map((section, index) => ({
@@ -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 = `portki-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 portki-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 \`portki-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 `portki-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"] ?? "portki-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 = `portki-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("portki-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"} portki-output/ ${existsSync6(outputDir) ? "writable" : "will be created on first run"}
+`
+  );
+  if (!writable) allOk = false;
+  const chunkedDir = path16.resolve("portki-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;
@@ -3984,13 +4580,13 @@ function resolveQualityGateLevel(flags, defaultLevel) {
 }
 async function ingestCommand(flags) {
   const { repo, ref } = parseRepo(requireFlag(flags, "repo"), flags["ref"]);
-  const snapshotRoot = flags["snapshot_root"] ?? "devport-output/snapshots";
+  const snapshotRoot = flags["snapshot_root"] ?? "portki-output/snapshots";
   const outFile = flags["out"];
   process.stderr.write(`[devport-agent] ingest: ${repo}${ref ? `@${ref}` : ""}
 `);
   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 {
@@ -4019,7 +4615,7 @@ async function detectCommand(flags) {
     throw new Error(`--repo must be owner/repo, got: ${repoFlag}`);
   }
   const repoRef = `${parts[0]}/${parts[1]}`;
-  const statePath = flags["state_path"] ?? "devport-output/freshness/state.json";
+  const statePath = flags["state_path"] ?? "portki-output/freshness/state.json";
   process.stderr.write(`[devport-agent] detect: ${repoRef}
 `);
   const state = await loadFreshnessState(statePath);
@@ -4090,14 +4686,14 @@ async function detectCommand(flags) {
   );
 }
 async function packageCommand(flags) {
-  const outDir = flags["out_dir"] ?? "devport-output/wiki";
+  const outDir = flags["out_dir"] ?? "portki-output/wiki";
   const inputFile = flags["input"];
   const advanceBaseline = flags["advance_baseline"] === "true";
-  const statePath = flags["state_path"] ?? "devport-output/freshness/state.json";
+  const statePath = flags["state_path"] ?? "portki-output/freshness/state.json";
   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,
@@ -4279,12 +4875,12 @@ async function finalizeCommand(flags) {
   const planFile = requireFlag(flags, "plan");
   const sessionFile = flags["session"];
   const advanceBaseline = flags["advance_baseline"] === "true";
-  const statePath = flags["state_path"] ?? "devport-output/freshness/state.json";
+  const statePath = flags["state_path"] ?? "portki-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 outDir = flags["out_dir"] ?? "portki-output/wiki";
+  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: portki-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: portki-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: portki-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;