okstra 0.34.1 → 0.36.0

package/src/install.mjs

@@ -15,6 +15,10 @@ const SETTINGS_TEMPLATE_SRC_REL = ["templates", "reports", "settings.template.js
 // Destination under ~/.okstra/. Project-local .claude/settings.local.json symlinks here.
 const SETTINGS_TEMPLATE_DST_REL = ["templates", "settings.local.json"];
 
+// okstra-managed CLAUDE.md template. Per-project <PROJECT>/.project-docs/okstra/CLAUDE.md
+// symlinks here; <PROJECT>/CLAUDE.md gets an `@.project-docs/okstra/CLAUDE.md` import line.
+const CLAUDE_MD_TEMPLATE_REL = ["templates", "okstra.CLAUDE.md"];
+
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "okstra_vendor", "lib"];
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
@@ -42,7 +46,7 @@ Usage:
 Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/bin           <- runtime/bin
-  ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
+  ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md / okstra.CLAUDE.md)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
   ${"$HOME"}/.claude/agents/<worker>.md <- runtime/agents/workers/<worker>.md
@@ -54,6 +58,7 @@ Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
   ${"$HOME"}/.okstra/templates/settings.local.json -> <repo>/templates/reports/settings.template.json
+  ${"$HOME"}/.okstra/templates/okstra.CLAUDE.md     -> <repo>/templates/okstra.CLAUDE.md
   ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name>   (symlink dir)
   ${"$HOME"}/.claude/agents/<worker>.md -> <repo>/agents/workers/<worker>.md
   ${"$HOME"}/.okstra/dev-link         <- <repo> path stamp
@@ -64,6 +69,11 @@ project-local <project>/.claude/settings.local.json that okstra-setup
 provisions, granting per-project Claude Code permissions for okstra
 worker wrapper scripts without modifying the user's global settings.
 
+The okstra.CLAUDE.md file is the symlink target referenced by every
+project-local <project>/.project-docs/okstra/CLAUDE.md that okstra-setup provisions;
+<project>/CLAUDE.md gets an "@.project-docs/okstra/CLAUDE.md" import block so Claude
+Code automatically picks up the okstra runtime guidance.
+
 Worker agent definitions are installed into ${"$HOME"}/.claude/agents/ so
 that Claude Code's subagent discovery picks them up; they cannot live
 inside the package alone because the harness only scans ~/.claude/agents/
@@ -245,7 +255,8 @@ async function installLinkMode(repoPath, paths, opts) {
   const agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
 
-  await installSettingsTemplate(repoAbs, paths, { mode: "link", dryRun, quiet });
+  await installNamedTemplate(repoAbs, paths, { mode: "link", dryRun, quiet }, SETTINGS_TEMPLATE_DESCRIPTOR);
+  await installNamedTemplate(repoAbs, paths, { mode: "link", dryRun, quiet }, CLAUDE_MD_TEMPLATE_DESCRIPTOR);
 
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
@@ -395,13 +406,14 @@ async function installAgentsLink(repoAbs, opts) {
   return { installed: names };
 }
 
-async function installSettingsTemplate(srcRoot, paths, opts) {
+async function installNamedTemplate(srcRoot, paths, opts, descriptor) {
   const { mode, refresh = false, dryRun = false, quiet = false } = opts;
-  const src = join(srcRoot, ...SETTINGS_TEMPLATE_SRC_REL);
-  const dst = join(paths.home, ...SETTINGS_TEMPLATE_DST_REL);
+  const { srcRel, dstRel, label } = descriptor;
+  const src = join(srcRoot, ...srcRel);
+  const dst = join(paths.home, ...dstRel);
 
   if (!(await fileExists(src))) {
-    if (!quiet) process.stdout.write(`  settings template: source missing — skipped (${src})\n`);
+    if (!quiet) process.stdout.write(`  ${label}: source missing — skipped (${src})\n`);
     return { installed: false };
   }
 
@@ -409,7 +421,7 @@ async function installSettingsTemplate(srcRoot, paths, opts) {
 
   if (mode === "link") {
     const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  settings template: ${action} (${dst} -> ${src})\n`);
+    if (!quiet) process.stdout.write(`  ${label}: ${action} (${dst} -> ${src})\n`);
     return { installed: action !== "skipped" };
   }
 
@@ -426,7 +438,7 @@ async function installSettingsTemplate(srcRoot, paths, opts) {
   }
 
   if (!needsCopy) {
-    if (!quiet) process.stdout.write(`  settings template: skipped (hash match)\n`);
+    if (!quiet) process.stdout.write(`  ${label}: skipped (hash match)\n`);
     return { installed: false };
   }
 
@@ -436,10 +448,22 @@ async function installSettingsTemplate(srcRoot, paths, opts) {
     const buf = await fs.readFile(src);
     await writeFileAtomic(dst, buf, 0o644);
   }
-  if (!quiet) process.stdout.write(`  settings template: copied -> ${dst}\n`);
+  if (!quiet) process.stdout.write(`  ${label}: copied -> ${dst}\n`);
   return { installed: true };
 }
 
+const SETTINGS_TEMPLATE_DESCRIPTOR = {
+  srcRel: SETTINGS_TEMPLATE_SRC_REL,
+  dstRel: SETTINGS_TEMPLATE_DST_REL,
+  label: "settings template",
+};
+
+const CLAUDE_MD_TEMPLATE_DESCRIPTOR = {
+  srcRel: CLAUDE_MD_TEMPLATE_REL,
+  dstRel: CLAUDE_MD_TEMPLATE_REL,
+  label: "claude.md template",
+};
+
 async function installSkillsCopy(runtimeRoot, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
@@ -553,10 +577,11 @@ export async function runInstall(args) {
     paths.bin,
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
   );
-  // templates/ tree — report.css / report.js / *.template.md are consumed at
-  // runtime by okstra-render-report-views.py and final-report assembly. They
-  // are NOT covered by installSettingsTemplate (which only handles the
-  // editable settings.local.json sidecar), so without this step copy-mode
+  // templates/ tree — report.css / report.js / *.template.md / okstra.CLAUDE.md
+  // are consumed at runtime by okstra-render-report-views.py, final-report
+  // assembly, and the per-project .project-docs/okstra/CLAUDE.md symlink provisioned by
+  // setup. They are NOT covered by installNamedTemplate (which only handles
+  // the renamed settings.local.json sidecar), so without this step copy-mode
   // installs miss every asset other than that single file. See
   // okstra-render-report-views.py _TEMPLATES_DIRS for the lookup path.
   const templatesResult = await copyTreeIfChanged(
@@ -588,7 +613,9 @@ export async function runInstall(args) {
   const agentResult = await installAgentsCopy(runtimeRoot, opts);
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
 
-  await installSettingsTemplate(runtimeRoot, paths, { mode: "copy", ...opts });
+  await installNamedTemplate(runtimeRoot, paths, { mode: "copy", ...opts }, SETTINGS_TEMPLATE_DESCRIPTOR);
+  // okstra.CLAUDE.md is already covered by the runtime/templates tree copy
+  // above (same src/dst path, no rename). No second call needed in copy mode.
 
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);

package/src/setup.mjs

@@ -293,9 +293,37 @@ export async function run(args) {
     );
   }
 
+  let claudeMd = { symlink: null, importInjected: false };
+  try {
+    claudeMd = await ensureProjectClaudeMd(projectRoot);
+  } catch (err) {
+    process.stderr.write(
+      `warning: failed to wire <PROJECT>/CLAUDE.md @ .project-docs/okstra/CLAUDE.md import — ` +
+        `Claude Code sessions in this project will not auto-load okstra guidance. (${err.message})\n`,
+    );
+  }
+
+  let agentsMdSymlink = null;
+  try {
+    agentsMdSymlink = await ensureProjectAgentsMd(projectRoot);
+  } catch (err) {
+    process.stderr.write(
+      `warning: failed to provision <PROJECT>/AGENTS.md symlink — ` +
+        `codex / aider sessions in this project will not auto-load okstra guidance. (${err.message})\n`,
+    );
+  }
+
   process.stdout.write(
     JSON.stringify(
-      { ok: true, ...result, projectJsonPath, settingsLocalJson: settingsSymlink },
+      {
+        ok: true,
+        ...result,
+        projectJsonPath,
+        settingsLocalJson: settingsSymlink,
+        claudeMdSymlink: claudeMd.symlink,
+        claudeMdImportInjected: claudeMd.importInjected,
+        agentsMdSymlink,
+      },
       null,
       2,
     ) + "\n",
@@ -348,3 +376,107 @@ async function backupAndReplace(target, template) {
   await fs.rename(target, backup);
   await fs.symlink(template, target);
 }
+
+const CLAUDE_MD_TEMPLATE_PATH = join(homedir(), ".okstra", "templates", "okstra.CLAUDE.md");
+const CLAUDE_MD_SYMLINK_REL = join(".project-docs", "okstra", "CLAUDE.md");
+const CLAUDE_MD_IMPORT_LINE = "@.project-docs/okstra/CLAUDE.md";
+const CLAUDE_MD_MARKER_BEGIN = "<!-- okstra:claude-md:begin (managed by okstra setup — do not edit) -->";
+const CLAUDE_MD_MARKER_END = "<!-- okstra:claude-md:end -->";
+
+async function ensureProjectClaudeMd(projectRoot) {
+  try {
+    await fs.access(CLAUDE_MD_TEMPLATE_PATH);
+  } catch {
+    return { symlink: null, importInjected: false };
+  }
+
+  const symlink = await ensureClaudeMdSymlink(projectRoot);
+  const importInjected = await ensureClaudeMdImport(projectRoot);
+  return { symlink, importInjected };
+}
+
+async function ensureClaudeMdSymlink(projectRoot) {
+  const target = join(projectRoot, CLAUDE_MD_SYMLINK_REL);
+  await fs.mkdir(join(target, ".."), { recursive: true });
+
+  let existingStat;
+  try {
+    existingStat = await fs.lstat(target);
+  } catch {
+    existingStat = null;
+  }
+
+  if (existingStat?.isSymbolicLink()) {
+    const current = await fs.readlink(target);
+    const resolved = current.startsWith("/") ? current : join(target, "..", current);
+    if (resolved === CLAUDE_MD_TEMPLATE_PATH) return target;
+    await backupAndReplace(target, CLAUDE_MD_TEMPLATE_PATH);
+    return target;
+  }
+  if (existingStat) {
+    await backupAndReplace(target, CLAUDE_MD_TEMPLATE_PATH);
+    return target;
+  }
+
+  await fs.symlink(CLAUDE_MD_TEMPLATE_PATH, target);
+  return target;
+}
+
+async function ensureClaudeMdImport(projectRoot) {
+  const claudeMdPath = join(projectRoot, "CLAUDE.md");
+  const block = `${CLAUDE_MD_MARKER_BEGIN}\n${CLAUDE_MD_IMPORT_LINE}\n${CLAUDE_MD_MARKER_END}\n`;
+
+  let existing;
+  try {
+    existing = await fs.readFile(claudeMdPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    await fs.writeFile(claudeMdPath, block, { mode: 0o644 });
+    return true;
+  }
+
+  if (existing.includes(CLAUDE_MD_MARKER_BEGIN) && existing.includes(CLAUDE_MD_MARKER_END)) {
+    return false;
+  }
+
+  const separator = blockSeparatorFor(existing);
+  await fs.writeFile(claudeMdPath, existing + separator + block, { mode: 0o644 });
+  return true;
+}
+
+function blockSeparatorFor(existing) {
+  if (existing.length === 0) return "";
+  if (existing.endsWith("\n\n")) return "";
+  if (existing.endsWith("\n")) return "\n";
+  return "\n\n";
+}
+
+async function ensureProjectAgentsMd(projectRoot) {
+  try {
+    await fs.access(CLAUDE_MD_TEMPLATE_PATH);
+  } catch {
+    return null;
+  }
+
+  const target = join(projectRoot, "AGENTS.md");
+
+  let existingStat;
+  try {
+    existingStat = await fs.lstat(target);
+  } catch {
+    existingStat = null;
+  }
+
+  if (existingStat?.isSymbolicLink()) {
+    const current = await fs.readlink(target);
+    const resolved = current.startsWith("/") ? current : join(target, "..", current);
+    if (resolved === CLAUDE_MD_TEMPLATE_PATH) return target;
+    return null;
+  }
+  if (existingStat) {
+    return null;
+  }
+
+  await fs.symlink(CLAUDE_MD_TEMPLATE_PATH, target);
+  return target;
+}

package/src/uninstall.mjs

@@ -11,14 +11,19 @@ const BIN_ENTRYPOINTS = [
   "okstra-central.sh",
   "okstra-token-usage.py",
   "okstra-error-log.py",
+  "okstra-render-report-views.py",
+  "okstra-render-final-report.py",
+  "okstra-wrapper-status.py",
 ];
 
 const FALLBACK_SKILL_NAMES = [
   "okstra-setup",
+  "okstra-brief",
   "okstra-run",
   "okstra-status",
   "okstra-history",
   "okstra-schedule",
+  "okstra-logs",
   "okstra-context-loader",
   "okstra-team-contract",
   "okstra-convergence",
@@ -44,7 +49,9 @@ const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra, ~/.
 Usage:
   okstra uninstall              Remove ~/.okstra/{lib, bin/<known>, version,
                                 dev-link, installed-skills.json,
-                                installed-agents.json} AND
+                                installed-agents.json,
+                                templates/settings.local.json,
+                                templates/okstra.CLAUDE.md} AND
                                 ~/.claude/skills/<name> AND
                                 ~/.claude/agents/<worker>.md for every
                                 entry in the install manifests (fallback:
@@ -52,6 +59,12 @@ Usage:
                                 Preserves user data: recent.jsonl,
                                 active.jsonl, projects/, archive/,
                                 state.json, .locks/
+                                Per-project artifacts created by 'okstra setup'
+                                (<PROJECT>/.project-docs/okstra/CLAUDE.md symlink,
+                                <PROJECT>/CLAUDE.md import block,
+                                <PROJECT>/AGENTS.md symlink,
+                                <PROJECT>/.claude/settings.local.json symlink)
+                                are NOT touched — remove them manually if needed.
   okstra uninstall --purge      Remove the entire ~/.okstra directory AND
                                 ~/.claude/skills/<okstra-*> AND
                                 ~/.claude/agents/<*-worker.md> (DESTRUCTIVE).
@@ -182,6 +195,13 @@ export async function runUninstall(args) {
   await removePath(join(paths.home, AGENTS_MANIFEST_REL), opts);
 
   await removePath(join(paths.home, "templates", "settings.local.json"), opts);
+  await removePath(join(paths.home, "templates", "okstra.CLAUDE.md"), opts);
+  // Per-project artifacts (<PROJECT>/.project-docs/okstra/CLAUDE.md symlink,
+  // <PROJECT>/AGENTS.md symlink, and the @.project-docs/okstra/CLAUDE.md import
+  // block inside <PROJECT>/CLAUDE.md) are NOT removed here — uninstall is
+  // machine-level and does not know which projects opted in. Symlinks will
+  // dangle until the user removes them manually or re-runs okstra install +
+  // okstra setup.
   // Remove templates/ if now empty.
   const templatesDir = join(paths.home, "templates");
   if (await pathExists(templatesDir)) {