okstra 0.13.2 → 0.14.0

package/docs/kr/architecture.md

@@ -18,7 +18,7 @@
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, 9개 render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
 - **Required team contract**: `Claude lead` + `Claude worker` · `Codex worker` · `Gemini worker` · `Report writer worker`의 필수 구성과 Agent Teams 우선 시도를 강제합니다.
-- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin}`) + 스킬 마크다운(`~/.claude/skills/<name>/SKILL.md`) 을 모두 깐다. 대상 프로젝트에는 task bundle 과 discovery metadata 만 `.project-docs/okstra/` 아래 저장됩니다 — 사용자의 `~/.claude/settings.json` 이나 프로젝트 `.claude/settings.local.json` 은 건드리지 않으며, per-session permission 은 `claude --settings` 로 런타임 주입합니다. (개발용으로는 `okstra-install.sh` 가 `--link` 모드 symlink 설치를 제공합니다.)
+- **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`) + 스킬 마크다운(`~/.claude/skills/<name>/SKILL.md`) 을 모두 깐다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.project-docs/okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않으며 별도 `--settings` CLI 주입도 필요 없습니다. (개발용으로는 `okstra-install.sh` 가 `--link` 모드 symlink 설치를 제공합니다.)
 - **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
 - **Optional integrations**: worker error sidecar, token usage / cost accounting을 옵션으로 제공합니다.
 
@@ -213,7 +213,7 @@ per-process 환경 변수에 task 정체성·경로·workflow 상태를 보관
 **Mode A — `okstra.sh` 가 새 claude 프로세스를 띄움**
 - `--render-only`를 사용하면 Claude를 실행하지 않고 instruction-set 만 만든 뒤 종료합니다.
 - `--render-only`가 없으면 prepare 단계가 Claude session ID 를 선할당하고 current run 의 `sessions/` 아래에 `claude-resume-<task-type>-<seq>.sh` 를 생성합니다.
-- 이후 대상 프로젝트 루트에서 resolved `Claude lead` model execution value 로 `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" --settings <runtime-settings> "$PROMPT"` 를 `exec` 합니다.
+- 이후 대상 프로젝트 루트에서 resolved `Claude lead` model execution value 로 `claude --model <lead> --session-id "$CLAUDE_SESSION_ID" "$PROMPT"` 를 `exec` 합니다. (이전 버전의 `--settings <runtime-settings>` 인자는 0.14.0 부터 제거됨 — 권한은 `<PROJECT_ROOT>/.claude/settings.local.json` symlink 가 담당.)
 - `okstra.sh` 는 handoff 까지만 수행하고, 최종 보고서 저장과 run/task 상태 갱신은 Claude lead 가 이어서 수행합니다.
 
 **Mode B — `okstra-run` skill 이 현재 claude 세션 안에서 인계**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.13.2",
-  "builtAt": "2026-05-13T02:07:39.150Z",
+  "package": "0.14.0",
+  "builtAt": "2026-05-13T02:55:11.516Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra.sh

@@ -152,17 +152,20 @@ if [[ -z "$LAUNCH_JSON" ]]; then
 fi
 
 # Read fields via python (jq not assumed available).
-read -r CLAUDE_SESSION_ID LEAD_MODEL_EXECUTION_VALUE PROJECT_ROOT_FROM_PY OKSTRA_RUNTIME_SETTINGS_FILE PROMPT_FILE < <(
+read -r CLAUDE_SESSION_ID LEAD_MODEL_EXECUTION_VALUE PROJECT_ROOT_FROM_PY PROMPT_FILE < <(
   okstra_py - "$LAUNCH_JSON" <<'PY'
 import json, sys
 d = json.loads(sys.argv[1])
-print(d["claudeSessionId"], d["leadModelExecutionValue"], d["projectRoot"], d["runtimeSettingsFile"], d["promptFile"])
+print(d["claudeSessionId"], d["leadModelExecutionValue"], d["projectRoot"], d["promptFile"])
 PY
 )
 
+# Note: per-session --settings injection was removed. okstra-ctl prepare
+# provisions <PROJECT_ROOT>/.claude/settings.local.json as a symlink to
+# ~/.okstra/templates/settings.local.json, which Claude Code auto-loads
+# whenever it runs inside that project — no CLI flag required.
 PROMPT="$(cat "$PROMPT_FILE")"
 cd "$PROJECT_ROOT_FROM_PY"
 CLAUDE_COMMAND=(claude --model "$LEAD_MODEL_EXECUTION_VALUE" --session-id "$CLAUDE_SESSION_ID")
-[[ -n "$OKSTRA_RUNTIME_SETTINGS_FILE" ]] && CLAUDE_COMMAND+=(--settings "$OKSTRA_RUNTIME_SETTINGS_FILE")
 CLAUDE_COMMAND+=("$PROMPT")
 exec "${CLAUDE_COMMAND[@]}"

package/runtime/python/okstra_ctl/run.py

@@ -23,7 +23,6 @@ import subprocess
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Optional
 
 from okstra_project import upsert_project_json
 from .material import (
@@ -47,8 +46,9 @@ from .render import (
 )
 from .run_context import compute_and_write_run_context, write_run_inputs
 from .seeding import (
+    SettingsLinkError,
     cleanup_obsolete_generated_docs,
-    render_runtime_settings_file,
+    ensure_project_settings_symlink,
     verify_installation,
 )
 from .session import (
@@ -102,7 +102,6 @@ class PrepareInputs:
 class PrepareOutputs:
     ctx: dict
     prompt_text: str
-    runtime_settings_path: Optional[Path]
     extras: dict = field(default_factory=dict)
 
 
@@ -764,16 +763,26 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
             file=__import__("sys").stderr,
         )
 
-    runtime_settings_path = None
     if not inp.render_only:
-        runtime_settings_path = render_runtime_settings_file(
-            workspace_root=workspace_root, run_dir=Path(ctx["RUN_DIR"]),
-        )
+        try:
+            link = ensure_project_settings_symlink(project_root=Path(inp.project_root))
+        except SettingsLinkError as exc:
+            print(
+                f"okstra-settings: failed to provision project settings symlink — "
+                f"worker dispatch may be blocked by Claude Code permissions. ({exc})",
+                file=__import__("sys").stderr,
+            )
+        else:
+            if link is None:
+                print(
+                    "okstra-settings: ~/.okstra/templates/settings.local.json missing — "
+                    "re-run 'npx okstra@latest install' (0.14.0+) to provision the symlink target.",
+                    file=__import__("sys").stderr,
+                )
 
     return PrepareOutputs(
         ctx=ctx,
         prompt_text=prompt_text,
-        runtime_settings_path=runtime_settings_path,
         extras={"profile_content": profile_content},
     )
 
@@ -919,7 +928,6 @@ def main(argv: list[str]) -> int:
             "claudeSessionId": ctx["CLAUDE_SESSION_ID"],
             "leadModelExecutionValue": ctx["LEAD_MODEL_EXECUTION_VALUE"],
             "projectRoot": ctx["PROJECT_ROOT"],
-            "runtimeSettingsFile": str(out.runtime_settings_path) if out.runtime_settings_path else "",
             "promptFile": str(Path(ctx["INSTRUCTION_SET_DIR"]) / "claude-execution-prompt.md"),
         }
         print(f"__OKSTRA_LAUNCH__ {json.dumps(machine)}")

package/runtime/python/okstra_ctl/seeding.py

@@ -1,13 +1,16 @@
-"""okstra runtime asset verification + per-run runtime settings.
+"""okstra runtime asset verification + project settings provisioning.
 
 okstra 가 깔아둔 런타임(`~/.okstra/lib/python`, `~/.okstra/bin`,
 `~/.okstra/version`) 이 있는지 확인하고, 누락 시 InstallationError 로
-surface 한다. 또한 claude 런치 때 사용할 휘발성 settings 파일을 현재 run
-디렉토리에 만든다.
+surface 한다. 또한 대상 프로젝트의 `.claude/settings.local.json` 을
+`~/.okstra/templates/settings.local.json` 으로 가리키는 symlink 로
+provision 해서, host Claude Code 세션이 같은 프로젝트에서 일하는 동안
+okstra worker wrapper 호출이 자동 허용되도록 한다.
 """
 from __future__ import annotations
 
-import shutil
+import os
+import time
 from pathlib import Path
 from typing import Optional
 
@@ -16,6 +19,10 @@ class InstallationError(Exception):
     """okstra 가 깔아둔 런타임 자산이 누락됨."""
 
 
+class SettingsLinkError(Exception):
+    """`<project>/.claude/settings.local.json` symlink provisioning 실패."""
+
+
 def required_install_paths() -> list[Path]:
     """okstra install 이 채워야 하는 최소 자산 경로."""
     okstra_home = Path.home() / ".okstra"
@@ -82,16 +89,90 @@ def cleanup_obsolete_generated_docs(
             pass
 
 
-def render_runtime_settings_file(
-    *, workspace_root: Path, run_dir: Path,
-) -> Optional[Path]:
-    """`templates/reports/settings.template.json` 을 `<run-dir>/okstra-runtime-settings.json`
-    으로 복사한다. 템플릿 부재 시 None 반환(상위에서 `--settings` 인자 skip).
+def _okstra_home() -> Path:
+    """`~/.okstra` 의 절대경로. 테스트에서 `OKSTRA_HOME` 으로 override 가능."""
+    override = os.environ.get("OKSTRA_HOME", "").strip()
+    if override:
+        return Path(override)
+    return Path.home() / ".okstra"
+
+
+def installed_settings_template_path() -> Path:
+    """okstra install 이 만들어 둔 settings.local.json template 의 절대경로."""
+    return _okstra_home() / "templates" / "settings.local.json"
+
+
+def ensure_project_settings_symlink(*, project_root: Path) -> Optional[Path]:
+    """`<project_root>/.claude/settings.local.json` 을
+    `~/.okstra/templates/settings.local.json` 으로 가리키는 symlink 로
+    provisioning 한다.
+
+    Claude Code 가 그 프로젝트에서 host 세션으로 실행될 때 이 파일을
+    자동으로 로드하므로, okstra worker wrapper 호출(`okstra-codex-exec.sh`,
+    `okstra-gemini-exec.sh`) 이 별도 `--settings` 인자 없이도 허용된다.
+
+    반환값:
+      - target Path: symlink 가 새로 생성되었거나 이미 올바른 위치를
+        가리키고 있을 때.
+      - None: install 이 아직 settings template 을 깔지 않았을 때
+        (구버전 okstra install 등). 상위에서 경고로 흘려보낸다.
+
+    상위 호출자는 `SettingsLinkError` 만 처리하면 된다 — symlink target
+    의 dangling 여부, regular 파일 충돌, 사용자가 직접 만든 다른
+    symlink 등 의도된 boundary error 만 발생한다.
     """
-    template = Path(workspace_root) / "templates" / "reports" / "settings.template.json"
-    if not template.is_file():
+    project_root = Path(project_root)
+    template = installed_settings_template_path()
+    if not template.exists():
+        # install 이 0.13.x 이전 버전이면 templates/ 가 깔리지 않았을 수 있다.
+        # 상위에서 안내 메시지로 처리.
         return None
-    target = Path(run_dir) / "okstra-runtime-settings.json"
-    target.parent.mkdir(parents=True, exist_ok=True)
-    shutil.copyfile(template, target)
+
+    claude_dir = project_root / ".claude"
+    target = claude_dir / "settings.local.json"
+    claude_dir.mkdir(parents=True, exist_ok=True)
+
+    # idempotent: 이미 올바른 target 을 가리키는 symlink 면 no-op.
+    if target.is_symlink():
+        try:
+            current = os.readlink(target)
+        except OSError as exc:
+            raise SettingsLinkError(
+                f"failed to read existing symlink {target}: {exc}"
+            ) from exc
+        if Path(current) == template or (claude_dir / current).resolve() == template.resolve():
+            return target
+        # okstra 가 관리하지 않는 다른 symlink 였으면 backup 후 교체.
+        _backup_and_replace(target, template)
+        return target
+
+    if target.exists():
+        # 일반 파일이 있으면 사용자 작성물일 가능성이 높다 — 손실 방지 backup.
+        _backup_and_replace(target, template)
+        return target
+
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise SettingsLinkError(
+            f"failed to create symlink {target} -> {template}: {exc}"
+        ) from exc
     return target
+
+
+def _backup_and_replace(target: Path, template: Path) -> None:
+    """기존 파일/심볼릭링크를 timestamped backup 으로 옮기고 새 symlink 생성."""
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    backup = target.with_name(f"{target.name}.bak.{stamp}")
+    try:
+        target.rename(backup)
+    except OSError as exc:
+        raise SettingsLinkError(
+            f"failed to back up existing {target} to {backup}: {exc}"
+        ) from exc
+    try:
+        target.symlink_to(template)
+    except OSError as exc:
+        raise SettingsLinkError(
+            f"failed to create symlink {target} -> {template} after backup: {exc}"
+        ) from exc

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

@@ -142,6 +142,37 @@ field → built-in default. Only edit when defaults don't cover the
 project's working files (e.g. additional cache or local-config dirs
 that must follow the executor into the worktree).
 
+## Step 4.6 (automatic): project-local Claude settings symlink
+
+`okstra setup` (and `okstra run` on its first invocation per project)
+provisions `<PROJECT_ROOT>/.claude/settings.local.json` as a symlink to
+`~/.okstra/templates/settings.local.json`. The template is installed
+by `okstra install` 0.14.0+ and contains the Bash permission rules
+required for the codex/gemini worker wrappers:
+
+- `Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)`
+- `Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)`
+
+Claude Code automatically loads `.claude/settings.local.json` whenever
+it operates inside that project, so okstra workers dispatched from
+**any** Claude Code session (host or okstra.sh-spawned) are allowed to
+run their wrapper scripts without further configuration.
+
+This replaces the previous per-run `--settings` injection model
+(`<run-dir>/okstra-runtime-settings.json`) and the earlier guidance to
+modify the user's global `~/.claude/settings.json`.
+
+If a non-symlink `.claude/settings.local.json` already exists, the
+setup step backs it up to `.claude/settings.local.json.bak.<timestamp>`
+before installing the symlink — surface that to the user so they can
+merge any project-specific rules back into a downstream file (the
+symlinked template is okstra-owned and gets refreshed when okstra
+updates).
+
+To opt out (advanced): replace the symlink with a regular file. okstra
+will detect that it is no longer a symlink on its next setup call and
+back it up as `.bak.<timestamp>` rather than overwriting silently.
+
 ## Step 5: Verify
 
 ```bash

package/src/install.mjs

@@ -10,6 +10,11 @@ const AGENTS_MANIFEST_REL = "installed-agents.json";
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const CLAUDE_AGENTS_DIR = join(homedir(), ".claude", "agents");
 
+// Source template (relative to runtime root in copy mode, or repo root in link mode).
+const SETTINGS_TEMPLATE_SRC_REL = ["templates", "reports", "settings.template.json"];
+// Destination under ~/.okstra/. Project-local .claude/settings.local.json symlinks here.
+const SETTINGS_TEMPLATE_DST_REL = ["templates", "settings.local.json"];
+
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "lib"];
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
@@ -33,6 +38,7 @@ Usage:
 Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/bin           <- runtime/bin
+  ${"$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
   ${"$HOME"}/.okstra/installed-skills.json   <- manifest of installed skills
@@ -42,11 +48,17 @@ Effect (copy mode):
 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"}/.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
   ${"$HOME"}/.okstra/version          <- installed package version stamp
 
+The settings.local.json file is the symlink target referenced by every
+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.
+
 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/
@@ -228,6 +240,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 });
+
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -376,6 +390,51 @@ async function installAgentsLink(repoAbs, opts) {
   return { installed: names };
 }
 
+async function installSettingsTemplate(srcRoot, paths, opts) {
+  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);
+
+  if (!(await fileExists(src))) {
+    if (!quiet) process.stdout.write(`  settings template: source missing — skipped (${src})\n`);
+    return { installed: false };
+  }
+
+  if (!dryRun) await fs.mkdir(join(dst, ".."), { recursive: true });
+
+  if (mode === "link") {
+    const action = await ensureSymlink(src, dst, { dryRun });
+    if (!quiet) process.stdout.write(`  settings template: ${action} (${dst} -> ${src})\n`);
+    return { installed: action !== "skipped" };
+  }
+
+  // copy mode — hash-skip mirrors copyTreeIfChanged behavior for a single file.
+  let needsCopy = refresh;
+  if (!needsCopy) {
+    try {
+      await fs.access(dst);
+      const [srcHash, dstHash] = await Promise.all([hashFile(src), hashFile(dst)]);
+      needsCopy = srcHash !== dstHash;
+    } catch {
+      needsCopy = true;
+    }
+  }
+
+  if (!needsCopy) {
+    if (!quiet) process.stdout.write(`  settings template: skipped (hash match)\n`);
+    return { installed: false };
+  }
+
+  if (dryRun) {
+    process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
+  } else {
+    const buf = await fs.readFile(src);
+    await writeFileAtomic(dst, buf, 0o644);
+  }
+  if (!quiet) process.stdout.write(`  settings template: copied -> ${dst}\n`);
+  return { installed: true };
+}
+
 async function installSkillsCopy(runtimeRoot, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
@@ -507,6 +566,8 @@ 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 });
+
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
   }

package/src/setup.mjs

@@ -2,7 +2,7 @@ import { promises as fs } from "node:fs";
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { homedir } from "node:os";
-import { resolve as resolvePath } from "node:path";
+import { join, resolve as resolvePath } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 
 const USAGE = `okstra setup — register the current project with okstra
@@ -283,6 +283,68 @@ export async function run(args) {
     return 1;
   }
 
-  process.stdout.write(JSON.stringify({ ok: true, ...result, projectJsonPath }, null, 2) + "\n");
+  let settingsSymlink = null;
+  try {
+    settingsSymlink = await ensureProjectSettingsSymlink(projectRoot);
+  } catch (err) {
+    process.stderr.write(
+      `warning: failed to provision .claude/settings.local.json symlink — ` +
+        `host Claude Code sessions in this project may need to add wrapper permissions manually. (${err.message})\n`,
+    );
+  }
+
+  process.stdout.write(
+    JSON.stringify(
+      { ok: true, ...result, projectJsonPath, settingsLocalJson: settingsSymlink },
+      null,
+      2,
+    ) + "\n",
+  );
   return 0;
 }
+
+async function ensureProjectSettingsSymlink(projectRoot) {
+  const template = join(homedir(), ".okstra", "templates", "settings.local.json");
+  try {
+    await fs.access(template);
+  } catch {
+    return null; // install hasn't provisioned the template yet (pre-0.14 install)
+  }
+
+  const claudeDir = join(projectRoot, ".claude");
+  const target = join(claudeDir, "settings.local.json");
+  await fs.mkdir(claudeDir, { 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(claudeDir, current);
+    if (resolved === template) return target;
+    await backupAndReplace(target, template);
+    return target;
+  }
+  if (existingStat) {
+    await backupAndReplace(target, template);
+    return target;
+  }
+
+  await fs.symlink(template, target);
+  return target;
+}
+
+async function backupAndReplace(target, template) {
+  const stamp = new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\..*/, "")
+    .replace("T", "-");
+  const backup = `${target}.bak.${stamp}`;
+  await fs.rename(target, backup);
+  await fs.symlink(template, target);
+}

package/src/uninstall.mjs

@@ -180,6 +180,21 @@ export async function runUninstall(args) {
   }
   await removePath(join(paths.home, AGENTS_MANIFEST_REL), opts);
 
+  await removePath(join(paths.home, "templates", "settings.local.json"), opts);
+  // Remove templates/ if now empty.
+  const templatesDir = join(paths.home, "templates");
+  if (await pathExists(templatesDir)) {
+    try {
+      const entries = await fs.readdir(templatesDir);
+      if (entries.length === 0) {
+        if (!opts.dryRun) await fs.rmdir(templatesDir);
+        if (!opts.quiet) process.stdout.write(`  removed empty: ${templatesDir}\n`);
+      }
+    } catch {
+      /* ignore */
+    }
+  }
+
   await removePath(join(paths.home, "version"), opts);
   await removePath(join(paths.home, "dev-link"), opts);