first-tree 0.0.4 → 0.0.6

package/skills/first-tree/engine/rules/agent-integration.ts

@@ -1,13 +1,15 @@
 import type { Repo } from "#skill/engine/repo.js";
 import type { RuleResult } from "#skill/engine/rules/index.js";
+import { claudeCodeExampleCandidates } from "#skill/engine/runtime/adapters.js";
 import { FRAMEWORK_EXAMPLES_DIR } from "#skill/engine/runtime/asset-loader.js";
 
 export function evaluate(repo: Repo): RuleResult {
   const tasks: string[] = [];
+  const [claudeExamplePath] = claudeCodeExampleCandidates();
   if (repo.pathExists(".claude/settings.json")) {
     if (!repo.fileContains(".claude/settings.json", "inject-tree-context")) {
       tasks.push(
-        `Add SessionStart hook to \`.claude/settings.json\` (see \`${FRAMEWORK_EXAMPLES_DIR}/claude-code/\`)`,
+        `Add SessionStart hook to \`.claude/settings.json\` (see \`${claudeExamplePath}/\`)`,
       );
     }
   } else if (!repo.anyAgentConfig()) {

package/skills/first-tree/engine/rules/framework.ts

@@ -1,12 +1,12 @@
 import type { Repo } from "#skill/engine/repo.js";
 import type { RuleResult } from "#skill/engine/rules/index.js";
-import { SKILL_ROOT } from "#skill/engine/runtime/asset-loader.js";
+import { installedSkillRootsDisplay } from "#skill/engine/runtime/asset-loader.js";
 
 export function evaluate(repo: Repo): RuleResult {
   const tasks: string[] = [];
   if (!repo.hasFramework()) {
     tasks.push(
-      `\`${SKILL_ROOT}/\` not found — run \`context-tree init\` to install the framework skill bundled with the current \`first-tree\` package`,
+      `${installedSkillRootsDisplay()} not found — run \`context-tree init\` to install the framework skill bundled with the current \`first-tree\` package`,
     );
   }
   return { group: "Framework", order: 1, tasks };

package/skills/first-tree/engine/runtime/adapters.ts

@@ -1,7 +1,9 @@
 import { join } from "node:path";
 import {
+  CLAUDE_FRAMEWORK_EXAMPLES_DIR,
+  CLAUDE_FRAMEWORK_HELPERS_DIR,
   FRAMEWORK_EXAMPLES_DIR,
-  FRAMEWORK_HELPERS_DIR,
+  LEGACY_REPO_SKILL_EXAMPLES_DIR,
   LEGACY_SKILL_EXAMPLES_DIR,
   LEGACY_EXAMPLES_DIR,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -11,12 +13,14 @@ export const CODEX_CONFIG_PATH = ".codex/config.json";
 
 export function claudeCodeExampleCandidates(): string[] {
   return [
+    join(CLAUDE_FRAMEWORK_EXAMPLES_DIR, "claude-code"),
     join(FRAMEWORK_EXAMPLES_DIR, "claude-code"),
+    join(LEGACY_REPO_SKILL_EXAMPLES_DIR, "claude-code"),
     join(LEGACY_SKILL_EXAMPLES_DIR, "claude-code"),
     join(LEGACY_EXAMPLES_DIR, "claude-code"),
   ];
 }
 
 export function injectTreeContextHint(): string {
-  return join(FRAMEWORK_HELPERS_DIR, "inject-tree-context.sh");
+  return join(CLAUDE_FRAMEWORK_HELPERS_DIR, "inject-tree-context.sh");
 }

package/skills/first-tree/engine/runtime/asset-loader.ts

@@ -2,7 +2,11 @@ import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 
 export const SKILL_NAME = "first-tree";
-export const SKILL_ROOT = join("skills", SKILL_NAME);
+export const BUNDLED_SKILL_ROOT = join("skills", SKILL_NAME);
+export const SKILL_ROOT = join(".agents", "skills", SKILL_NAME);
+export const CLAUDE_SKILL_ROOT = join(".claude", "skills", SKILL_NAME);
+export const INSTALLED_SKILL_ROOTS = [SKILL_ROOT, CLAUDE_SKILL_ROOT] as const;
+
 export const SKILL_AGENTS_DIR = join(SKILL_ROOT, "agents");
 export const SKILL_REFERENCES_DIR = join(SKILL_ROOT, "references");
 export const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
@@ -17,6 +21,99 @@ export const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
 export const AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
 export const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
 export const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
+export const CLAUDE_INSTRUCTIONS_FILE = "CLAUDE.md";
+export const SOURCE_INTEGRATION_MARKER = "FIRST-TREE-SOURCE-INTEGRATION:";
+export const SOURCE_INTEGRATION_FILES = [
+  AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_INSTRUCTIONS_FILE,
+] as const;
+
+export const CLAUDE_SKILL_AGENTS_DIR = join(CLAUDE_SKILL_ROOT, "agents");
+export const CLAUDE_SKILL_REFERENCES_DIR = join(CLAUDE_SKILL_ROOT, "references");
+export const CLAUDE_FRAMEWORK_ASSET_ROOT = join(
+  CLAUDE_SKILL_ROOT,
+  "assets",
+  "framework",
+);
+export const CLAUDE_FRAMEWORK_MANIFEST = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "manifest.json",
+);
+export const CLAUDE_FRAMEWORK_VERSION = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "VERSION",
+);
+export const CLAUDE_FRAMEWORK_TEMPLATES_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "templates",
+);
+export const CLAUDE_FRAMEWORK_WORKFLOWS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "workflows",
+);
+export const CLAUDE_FRAMEWORK_PROMPTS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "prompts",
+);
+export const CLAUDE_FRAMEWORK_EXAMPLES_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "examples",
+);
+export const CLAUDE_FRAMEWORK_HELPERS_DIR = join(
+  CLAUDE_FRAMEWORK_ASSET_ROOT,
+  "helpers",
+);
+export const CLAUDE_INSTALLED_PROGRESS = join(
+  CLAUDE_SKILL_ROOT,
+  "progress.md",
+);
+
+export const LEGACY_REPO_SKILL_ROOT = join("skills", SKILL_NAME);
+export const LEGACY_REPO_SKILL_AGENTS_DIR = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "agents",
+);
+export const LEGACY_REPO_SKILL_REFERENCES_DIR = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "references",
+);
+export const LEGACY_REPO_SKILL_ASSET_ROOT = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "assets",
+  "framework",
+);
+export const LEGACY_REPO_SKILL_MANIFEST = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "manifest.json",
+);
+export const LEGACY_REPO_SKILL_VERSION = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "VERSION",
+);
+export const LEGACY_REPO_SKILL_TEMPLATES_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "templates",
+);
+export const LEGACY_REPO_SKILL_WORKFLOWS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "workflows",
+);
+export const LEGACY_REPO_SKILL_PROMPTS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "prompts",
+);
+export const LEGACY_REPO_SKILL_EXAMPLES_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "examples",
+);
+export const LEGACY_REPO_SKILL_HELPERS_DIR = join(
+  LEGACY_REPO_SKILL_ASSET_ROOT,
+  "helpers",
+);
+export const LEGACY_REPO_SKILL_PROGRESS = join(
+  LEGACY_REPO_SKILL_ROOT,
+  "progress.md",
+);
 
 export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
 export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
@@ -52,7 +149,12 @@ export const LEGACY_WORKFLOWS_DIR = join(LEGACY_FRAMEWORK_ROOT, "workflows");
 export const LEGACY_PROMPTS_DIR = join(LEGACY_FRAMEWORK_ROOT, "prompts");
 export const LEGACY_EXAMPLES_DIR = join(LEGACY_FRAMEWORK_ROOT, "examples");
 
-export type FrameworkLayout = "skill" | "legacy-skill" | "legacy";
+export type FrameworkLayout =
+  | "skill"
+  | "claude-skill"
+  | "legacy-repo-skill"
+  | "legacy-skill"
+  | "legacy";
 
 function pathExists(root: string, relPath: string): boolean {
   const fullPath = join(root, relPath);
@@ -63,12 +165,34 @@ function pathExists(root: string, relPath: string): boolean {
   }
 }
 
+export function installedSkillRoots(): string[] {
+  return [...INSTALLED_SKILL_ROOTS];
+}
+
+export function installedSkillRootsDisplay(): string {
+  return installedSkillRoots()
+    .map((root) => `\`${root}/\``)
+    .join(" and ");
+}
+
 export function frameworkVersionCandidates(): string[] {
-  return [FRAMEWORK_VERSION, LEGACY_SKILL_VERSION, LEGACY_VERSION];
+  return [
+    FRAMEWORK_VERSION,
+    CLAUDE_FRAMEWORK_VERSION,
+    LEGACY_REPO_SKILL_VERSION,
+    LEGACY_SKILL_VERSION,
+    LEGACY_VERSION,
+  ];
 }
 
 export function progressFileCandidates(): string[] {
-  return [INSTALLED_PROGRESS, LEGACY_SKILL_PROGRESS, LEGACY_PROGRESS];
+  return [
+    INSTALLED_PROGRESS,
+    CLAUDE_INSTALLED_PROGRESS,
+    LEGACY_REPO_SKILL_PROGRESS,
+    LEGACY_SKILL_PROGRESS,
+    LEGACY_PROGRESS,
+  ];
 }
 
 export function agentInstructionsFileCandidates(): string[] {
@@ -78,6 +202,8 @@ export function agentInstructionsFileCandidates(): string[] {
 export function frameworkTemplateDirCandidates(): string[] {
   return [
     FRAMEWORK_TEMPLATES_DIR,
+    CLAUDE_FRAMEWORK_TEMPLATES_DIR,
+    LEGACY_REPO_SKILL_TEMPLATES_DIR,
     LEGACY_SKILL_TEMPLATES_DIR,
     LEGACY_TEMPLATES_DIR,
   ];
@@ -86,6 +212,8 @@ export function frameworkTemplateDirCandidates(): string[] {
 export function frameworkWorkflowDirCandidates(): string[] {
   return [
     FRAMEWORK_WORKFLOWS_DIR,
+    CLAUDE_FRAMEWORK_WORKFLOWS_DIR,
+    LEGACY_REPO_SKILL_WORKFLOWS_DIR,
     LEGACY_SKILL_WORKFLOWS_DIR,
     LEGACY_WORKFLOWS_DIR,
   ];
@@ -94,6 +222,8 @@ export function frameworkWorkflowDirCandidates(): string[] {
 export function frameworkPromptDirCandidates(): string[] {
   return [
     FRAMEWORK_PROMPTS_DIR,
+    CLAUDE_FRAMEWORK_PROMPTS_DIR,
+    LEGACY_REPO_SKILL_PROMPTS_DIR,
     LEGACY_SKILL_PROMPTS_DIR,
     LEGACY_PROMPTS_DIR,
   ];
@@ -102,6 +232,8 @@ export function frameworkPromptDirCandidates(): string[] {
 export function frameworkExampleDirCandidates(): string[] {
   return [
     FRAMEWORK_EXAMPLES_DIR,
+    CLAUDE_FRAMEWORK_EXAMPLES_DIR,
+    LEGACY_REPO_SKILL_EXAMPLES_DIR,
     LEGACY_SKILL_EXAMPLES_DIR,
     LEGACY_EXAMPLES_DIR,
   ];
@@ -123,6 +255,12 @@ export function detectFrameworkLayout(root: string): FrameworkLayout | null {
   if (pathExists(root, FRAMEWORK_VERSION)) {
     return "skill";
   }
+  if (pathExists(root, CLAUDE_FRAMEWORK_VERSION)) {
+    return "claude-skill";
+  }
+  if (pathExists(root, LEGACY_REPO_SKILL_VERSION)) {
+    return "legacy-repo-skill";
+  }
   if (pathExists(root, LEGACY_SKILL_VERSION)) {
     return "legacy-skill";
   }

package/skills/first-tree/engine/runtime/installer.ts

@@ -2,9 +2,10 @@ import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-  FRAMEWORK_ASSET_ROOT,
+  BUNDLED_SKILL_ROOT,
+  INSTALLED_SKILL_ROOTS,
+  LEGACY_REPO_SKILL_ROOT,
   LEGACY_SKILL_ROOT,
-  SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
 
 export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
@@ -12,7 +13,7 @@ export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
   while (true) {
     if (
       existsSync(join(dir, "package.json")) &&
-      existsSync(join(dir, SKILL_ROOT, "SKILL.md"))
+      existsSync(join(dir, BUNDLED_SKILL_ROOT, "SKILL.md"))
     ) {
       return dir;
     }
@@ -38,7 +39,7 @@ export function resolveCanonicalSkillRoot(sourceRoot: string): string {
     return directSkillRoot;
   }
 
-  const nestedSkillRoot = join(sourceRoot, SKILL_ROOT);
+  const nestedSkillRoot = join(sourceRoot, BUNDLED_SKILL_ROOT);
   if (
     existsSync(join(nestedSkillRoot, "SKILL.md")) &&
     existsSync(join(nestedSkillRoot, "assets", "framework", "VERSION"))
@@ -53,16 +54,21 @@ export function resolveCanonicalSkillRoot(sourceRoot: string): string {
 
 export function copyCanonicalSkill(sourceRoot: string, targetRoot: string): void {
   const src = resolveCanonicalSkillRoot(sourceRoot);
-  const dst = join(targetRoot, SKILL_ROOT);
-  const legacyDst = join(targetRoot, LEGACY_SKILL_ROOT);
-  if (existsSync(dst)) {
-    rmSync(dst, { recursive: true, force: true });
+  for (const relPath of [
+    ...INSTALLED_SKILL_ROOTS,
+    LEGACY_REPO_SKILL_ROOT,
+    LEGACY_SKILL_ROOT,
+  ]) {
+    const fullPath = join(targetRoot, relPath);
+    if (existsSync(fullPath)) {
+      rmSync(fullPath, { recursive: true, force: true });
+    }
   }
-  if (legacyDst !== dst && existsSync(legacyDst)) {
-    rmSync(legacyDst, { recursive: true, force: true });
+  for (const relPath of INSTALLED_SKILL_ROOTS) {
+    const dst = join(targetRoot, relPath);
+    mkdirSync(dirname(dst), { recursive: true });
+    cpSync(src, dst, { recursive: true });
   }
-  mkdirSync(dirname(dst), { recursive: true });
-  cpSync(src, dst, { recursive: true });
 }
 
 export function renderTemplateFile(

package/skills/first-tree/engine/runtime/source-integration.ts

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  SOURCE_INTEGRATION_FILES,
+  SOURCE_INTEGRATION_MARKER,
+} from "#skill/engine/runtime/asset-loader.js";
+
+export type SourceIntegrationFile = (typeof SOURCE_INTEGRATION_FILES)[number];
+
+export interface SourceIntegrationUpdate {
+  action: "created" | "updated" | "unchanged";
+  file: SourceIntegrationFile;
+}
+
+export function buildSourceIntegrationLine(treeRepoName: string): string {
+  return (
+    `${SOURCE_INTEGRATION_MARKER} Use the installed \`first-tree\` skill here;`
+    + ` keep all Context Tree files only in the sibling dedicated`
+    + ` \`${treeRepoName}\` repo/submodule and update that tree when decisions`
+    + " or constraints change."
+  );
+}
+
+export function hasSourceIntegrationMarker(text: string | null): boolean {
+  if (text === null) {
+    return false;
+  }
+  return text
+    .replaceAll("\r\n", "\n")
+    .split("\n")
+    .some((line) => line.startsWith(SOURCE_INTEGRATION_MARKER));
+}
+
+export function upsertSourceIntegrationFiles(
+  root: string,
+  treeRepoName: string,
+): SourceIntegrationUpdate[] {
+  return SOURCE_INTEGRATION_FILES.map((file) =>
+    upsertSourceIntegrationFile(root, file, treeRepoName),
+  );
+}
+
+function upsertSourceIntegrationFile(
+  root: string,
+  file: SourceIntegrationFile,
+  treeRepoName: string,
+): SourceIntegrationUpdate {
+  const fullPath = join(root, file);
+  const exists = existsSync(fullPath);
+  const nextLine = buildSourceIntegrationLine(treeRepoName);
+  const current = exists ? readFileSync(fullPath, "utf-8") : null;
+  const normalized = current?.replaceAll("\r\n", "\n") ?? "";
+  const lines = normalized === "" ? [] : normalized.split("\n");
+  const markerIndex = lines.findIndex((line) =>
+    line.startsWith(SOURCE_INTEGRATION_MARKER),
+  );
+
+  if (markerIndex >= 0) {
+    if (lines[markerIndex] === nextLine) {
+      return { action: "unchanged", file };
+    }
+    lines[markerIndex] = nextLine;
+  } else {
+    if (lines.length > 0 && lines.at(-1) !== "") {
+      lines.push("");
+    }
+    lines.push(nextLine);
+  }
+
+  let nextText = lines.join("\n");
+  if (nextText !== "" && !nextText.endsWith("\n")) {
+    nextText += "\n";
+  }
+  writeFileSync(fullPath, nextText);
+
+  return {
+    action: exists ? "updated" : "created",
+    file,
+  };
+}

package/skills/first-tree/engine/upgrade.ts

@@ -4,20 +4,26 @@ import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
   AGENT_INSTRUCTIONS_TEMPLATE,
+  CLAUDE_INSTRUCTIONS_FILE,
+  CLAUDE_SKILL_ROOT,
   FRAMEWORK_WORKFLOWS_DIR,
   FRAMEWORK_TEMPLATES_DIR,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_FRAMEWORK_ROOT,
+  LEGACY_REPO_SKILL_ROOT,
   LEGACY_SKILL_ROOT,
   SKILL_ROOT,
+  SOURCE_INTEGRATION_MARKER,
+  installedSkillRootsDisplay,
   type FrameworkLayout,
 } from "#skill/engine/runtime/asset-loader.js";
 import {
   copyCanonicalSkill,
   resolveBundledPackageRoot,
 } from "#skill/engine/runtime/installer.js";
+import { upsertSourceIntegrationFiles } from "#skill/engine/runtime/source-integration.js";
 import {
   compareFrameworkVersions,
   readSourceVersion,
@@ -45,9 +51,10 @@ function formatUpgradeTaskList(
   const lines: string[] = [
     `# Context Tree Upgrade — v${localVersion} -> v${packagedVersion}\n`,
     "## Installed Skill",
-    `- [ ] Review local customizations under \`${SKILL_ROOT}/\` and reapply them if needed`,
+    `- [ ] Review local customizations under ${installedSkillRootsDisplay()} and reapply them if needed`,
     `- [ ] Re-copy any workflow updates you want from \`${FRAMEWORK_WORKFLOWS_DIR}/\` into \`.github/workflows/\``,
-    `- [ ] Re-check any local agent setup that references \`${SKILL_ROOT}/assets/framework/examples/\` or \`${SKILL_ROOT}/assets/framework/helpers/\``,
+    `- [ ] Re-check any local agent setup that references \`${CLAUDE_SKILL_ROOT}/assets/framework/examples/\` or \`${CLAUDE_SKILL_ROOT}/assets/framework/helpers/\``,
+    `- [ ] Re-check any repo scripts or workflow files that reference \`${SKILL_ROOT}/assets/framework/\``,
     "",
   ];
 
@@ -58,6 +65,14 @@ function formatUpgradeTaskList(
     );
   }
 
+  if (layout === "legacy-repo-skill") {
+    lines.push(
+      "## Migration",
+      `- [ ] Remove any stale \`${LEGACY_REPO_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
+      "",
+    );
+  }
+
   if (layout === "legacy-skill") {
     migrationTasks.push(
       `- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
@@ -109,8 +124,10 @@ export interface UpgradeOptions {
 
 export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
   const workingRepo = repo ?? new Repo();
+  const workspaceOnlyIntegration =
+    workingRepo.hasSourceWorkspaceIntegration() && !workingRepo.looksLikeTreeRepo();
 
-  if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo()) {
+  if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo() && !workspaceOnlyIntegration) {
     console.error(
       "Error: no installed framework skill found here. This looks like a source/workspace repo. Run `context-tree init` to create a dedicated tree repo, or pass `--tree-path` to upgrade an existing tree repo.",
     );
@@ -165,7 +182,74 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
     return 1;
   }
 
-  if (layout === "skill" && packagedVersion === localVersion) {
+  const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+  const sourceRepoTreePathHint = `../${workingRepo.repoName()}-context`;
+
+  if (workspaceOnlyIntegration) {
+    if (
+      layout === "skill" &&
+      missingInstalledRoots.length === 0 &&
+      packagedVersion === localVersion
+    ) {
+      const updates = upsertSourceIntegrationFiles(
+        workingRepo.root,
+        `${workingRepo.repoName()}-context`,
+      );
+      const changedFiles = updates
+        .filter((update) => update.action !== "unchanged")
+        .map((update) => update.file);
+      if (changedFiles.length === 0) {
+        console.log(
+          `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
+        );
+        console.log(
+          `This repo only carries source/workspace integration. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`,
+        );
+        return 0;
+      }
+      console.log(
+        `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
+      );
+      console.log(
+        `Updated the ${SOURCE_INTEGRATION_MARKER} marker lines in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}.`,
+      );
+      console.log(
+        `This repo only carries source/workspace integration. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`,
+      );
+      return 0;
+    }
+
+    copyCanonicalSkill(sourceRoot, workingRepo.root);
+    const updates = upsertSourceIntegrationFiles(
+      workingRepo.root,
+      `${workingRepo.repoName()}-context`,
+    );
+    const changedFiles = updates
+      .filter((update) => update.action !== "unchanged")
+      .map((update) => update.file);
+    console.log(
+      `Refreshed ${installedSkillRootsDisplay()} in this source/workspace repo.`,
+    );
+    if (changedFiles.length > 0) {
+      console.log(
+        `Updated the ${SOURCE_INTEGRATION_MARKER} marker lines in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}.`,
+      );
+    } else {
+      console.log(
+        `The ${SOURCE_INTEGRATION_MARKER} marker lines in ${AGENT_INSTRUCTIONS_FILE} and ${CLAUDE_INSTRUCTIONS_FILE} were already current.`,
+      );
+    }
+    console.log(
+      `This repo is not the Context Tree. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`,
+    );
+    return 0;
+  }
+
+  if (
+    layout === "skill" &&
+    missingInstalledRoots.length === 0 &&
+    packagedVersion === localVersion
+  ) {
     console.log(
       `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
     );
@@ -179,16 +263,26 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
       force: true,
     });
     console.log(
-      "Migrated legacy .context-tree/ layout to skills/first-tree/.",
+      `Migrated legacy .context-tree/ layout to ${installedSkillRootsDisplay()}.`,
     );
-  } else if (layout === "legacy-skill") {
+  } else if (layout === "legacy-repo-skill") {
     console.log(
-      "Migrated skills/first-tree-cli-framework/ to skills/first-tree/.",
+      `Migrated legacy ${LEGACY_REPO_SKILL_ROOT}/ layout to ${installedSkillRootsDisplay()}.`,
     );
-  } else {
+  } else if (layout === "legacy-skill") {
     console.log(
-      "Refreshed skills/first-tree/ from the bundled first-tree package.",
+      `Migrated ${LEGACY_SKILL_ROOT}/ to ${installedSkillRootsDisplay()}.`,
     );
+  } else {
+    if (missingInstalledRoots.length > 0) {
+      console.log(
+        `Repaired missing installed skill roots (${missingInstalledRoots.map((root) => `${root}/`).join(", ")}) and refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`,
+      );
+    } else {
+      console.log(
+        `Refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`,
+      );
+    }
   }
 
   const output = formatUpgradeTaskList(

package/skills/first-tree/engine/verify.ts

@@ -50,6 +50,13 @@ export function runVerify(repo?: Repo, nodeValidator?: NodeValidator): number {
   const r = repo ?? new Repo();
   const validate = nodeValidator ?? defaultNodeValidator;
 
+  if (r.hasSourceWorkspaceIntegration() && !r.looksLikeTreeRepo()) {
+    console.error(
+      `Error: this repo only has the first-tree source/workspace integration installed. Verify the dedicated tree repo instead, for example \`context-tree verify --tree-path ../${r.repoName()}-context\`.`,
+    );
+    return 1;
+  }
+
   if (r.isLikelySourceRepo() && !r.looksLikeTreeRepo()) {
     console.error(
       "Error: no installed framework skill found here. This looks like a source/workspace repo. Run `context-tree init` to create a dedicated tree repo, or pass `--tree-path` to verify an existing tree repo.",

package/skills/first-tree/references/maintainer-architecture.md

@@ -13,6 +13,10 @@ This reference explains how to maintain the `first-tree` source repo itself.
 This repo is not a user context tree. User decision content lives in the repos
 that install the framework.
 
+When a source/workspace repo installs first-tree, that repo should keep only
+the local skill integration and marker lines. Tree content still belongs only
+in a dedicated `*-context` repo.
+
 ## Canonical Layers
 
 1. `SKILL.md` defines when to use the skill and the maintainer workflow.

package/skills/first-tree/references/maintainer-thin-cli.md

@@ -33,6 +33,9 @@ These root files are shell code, not canonical knowledge stores:
 - Keep root prose short. It should point to the skill, not duplicate the skill.
 - Keep command semantics, install layout rules, and maintainer guidance in the
   skill references.
+- If init/upgrade semantics change for source/workspace repos versus dedicated
+  tree repos, update `references/source-workspace-installation.md` and
+  `references/upgrade-contract.md` instead of expanding root shell prose.
 - If the shell gains behavior that is not obviously mechanical, move that
   behavior or its contract into the skill.
 - When in doubt, prefer adding a skill reference over expanding root docs.