first-tree 0.0.4 → 0.0.5

package/README.md

@@ -52,9 +52,10 @@ git init
 context-tree init --here
 ```
 
-- `context-tree init` installs `skills/first-tree/`, creates `NODE.md`,
-  `AGENTS.md`, `members/NODE.md`, and writes a checklist to
-  `skills/first-tree/progress.md`.
+- `context-tree init` installs `.agents/skills/first-tree/` and
+  `.claude/skills/first-tree/`, creates `NODE.md`, `AGENTS.md`,
+  `members/NODE.md`, and writes a checklist to
+  `.agents/skills/first-tree/progress.md`.
 - `context-tree verify` checks both the progress checklist and deterministic
   tree validation. It is expected to fail until the required onboarding tasks
   are complete.
@@ -79,11 +80,17 @@ runtime.
 
 ## Package Name vs Command
 
-- npm package name: `first-tree`
-- installed CLI command: `context-tree`
-- installed skill directory inside a user tree: `skills/first-tree/`
-- when maintainer docs mention "the `first-tree` skill", they mean that
-  bundled skill directory, not the npm package name
+- The npm package is `first-tree`.
+- The installed CLI command is `context-tree`.
+- The installed skill directories inside a user tree are
+  `.agents/skills/first-tree/` and `.claude/skills/first-tree/`.
+- The published package keeps its bundled canonical source under
+  `skills/first-tree/`.
+- When maintainer docs say "the `first-tree` skill", they mean that bundled
+  skill directory, not the npm package name.
+- `npx first-tree init` is the quickest one-off entrypoint.
+- `npm install -g first-tree` adds `context-tree` to your PATH for repeated
+  use.
 
 ## Runtime And Maintainer Prerequisites
 
@@ -97,6 +104,8 @@ runtime.
   bundled skill.
 - `skills/first-tree/` is the canonical source for framework behavior, shipped
   templates, maintainer references, and validation logic.
+- `context-tree init` installs that bundled skill into `.agents/skills/first-tree/`
+  and `.claude/skills/first-tree/` inside user repos.
 - `evals/` is maintainer-only developer tooling for the source repo. It is
   intentionally not part of the published package.
 

package/dist/cli.js

@@ -44,18 +44,18 @@ async function runCli(args, output = console.log) {
 	const command = args[0];
 	switch (command) {
 		case "init": {
-			const { runInit } = await import("./init--VepFe6N.js");
+			const { runInit } = await import("./init-CAq0Uhq6.js");
 			return runInit(args.slice(1));
 		}
 		case "verify": {
-			const { runVerify } = await import("./verify-mC9ZTd1f.js");
+			const { runVerify } = await import("./verify-C0IUSkMZ.js");
 			return runVerify(args.slice(1));
 		}
 		case "upgrade": {
-			const { runUpgrade } = await import("./upgrade-Cgx_K2HM.js");
+			const { runUpgrade } = await import("./upgrade-DYzuvv1k.js");
 			return runUpgrade(args.slice(1));
 		}
-		case "help": return (await import("./help-Dtdj91HJ.js")).runHelp(args.slice(1), write);
+		case "help": return (await import("./help-5-WG9QFm.js")).runHelp(args.slice(1), write);
 		default:
 			write(`Unknown command: ${command}`);
 			write(USAGE);

package/dist/{help-Dtdj91HJ.js → help-5-WG9QFm.js}

@@ -12,7 +12,7 @@ async function runHelp(args, output = console.log) {
 	}
 	switch (topic) {
 		case "onboarding": {
-			const { runOnboarding } = await import("./onboarding-C9cYSE6F.js");
+			const { runOnboarding } = await import("./onboarding-3zYUeYQb.js");
 			return runOnboarding(output);
 		}
 		default:

package/dist/{init--VepFe6N.js → init-CAq0Uhq6.js}

@@ -1,6 +1,6 @@
-import { a as FRAMEWORK_ASSET_ROOT, c as FRAMEWORK_VERSION, d as LEGACY_AGENT_INSTRUCTIONS_FILE, g as SKILL_ROOT, i as AGENT_INSTRUCTIONS_TEMPLATE, l as FRAMEWORK_WORKFLOWS_DIR, n as Repo, o as FRAMEWORK_EXAMPLES_DIR, r as AGENT_INSTRUCTIONS_FILE, s as FRAMEWORK_TEMPLATES_DIR, t as FRAMEWORK_END_MARKER, u as INSTALLED_PROGRESS } from "./repo-DY57bMqr.js";
-import { n as onboarding_default } from "./onboarding-CPP8fF4D.js";
-import { n as renderTemplateFile, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-cH7N4RNj.js";
+import { T as installedSkillRootsDisplay, b as LEGACY_SKILL_EXAMPLES_DIR, c as FRAMEWORK_ASSET_ROOT, d as FRAMEWORK_VERSION, f as FRAMEWORK_WORKFLOWS_DIR, g as LEGACY_EXAMPLES_DIR, h as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, l as FRAMEWORK_EXAMPLES_DIR, n as Repo, o as CLAUDE_FRAMEWORK_EXAMPLES_DIR, p as INSTALLED_PROGRESS, r as AGENT_INSTRUCTIONS_FILE, t as FRAMEWORK_END_MARKER, u as FRAMEWORK_TEMPLATES_DIR, v as LEGACY_REPO_SKILL_EXAMPLES_DIR } from "./repo-DkR12VUv.js";
+import { n as onboarding_default } from "./onboarding-Dd63N-V1.js";
+import { n as renderTemplateFile, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-UgNasLjl.js";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { dirname, join, relative, resolve } from "node:path";
@@ -47,12 +47,24 @@ function evaluate$6(repo) {
 	};
 }
 //#endregion
+//#region skills/first-tree/engine/runtime/adapters.ts
+function claudeCodeExampleCandidates() {
+	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")
+	];
+}
+//#endregion
 //#region skills/first-tree/engine/rules/agent-integration.ts
 var agent_integration_exports = /* @__PURE__ */ __exportAll({ evaluate: () => evaluate$5 });
 function evaluate$5(repo) {
 	const tasks = [];
+	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/\`)`);
+		if (!repo.fileContains(".claude/settings.json", "inject-tree-context")) tasks.push(`Add SessionStart hook to \`.claude/settings.json\` (see \`${claudeExamplePath}/\`)`);
 	} else if (!repo.anyAgentConfig()) tasks.push(`No agent configuration detected. Configure your agent to load tree context at session start. See \`${FRAMEWORK_EXAMPLES_DIR}/\` for supported agents. You can skip this and set it up later.`);
 	return {
 		group: "Agent Integration",
@@ -106,7 +118,7 @@ If (1): ask the user to provide the key, then run \`gh secret set\` with the sec
 var framework_exports = /* @__PURE__ */ __exportAll({ evaluate: () => evaluate$3 });
 function evaluate$3(repo) {
 	const tasks = [];
-	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`);
+	if (!repo.hasFramework()) tasks.push(`${installedSkillRootsDisplay()} not found — run \`context-tree init\` to install the framework skill bundled with the current \`first-tree\` package`);
 	return {
 		group: "Framework",
 		order: 1,
@@ -219,7 +231,7 @@ const TEMPLATE_MAP = [
 ];
 function installSkill(source, target) {
 	copyCanonicalSkill(source, target);
-	console.log("  Installed skills/first-tree/ from the bundled first-tree package");
+	console.log(`  Installed ${installedSkillRootsDisplay()} from the bundled first-tree package`);
 }
 function renderTemplates(target) {
 	const frameworkDir = join(target, FRAMEWORK_ASSET_ROOT);
@@ -280,7 +292,7 @@ function runInit(repo, options) {
 		if (initTarget.createdGitRepo) console.log("  Initialized a new git repo for the tree.");
 		console.log();
 	}
-	if (!r.hasFramework()) try {
+	if (!r.hasCurrentInstalledSkill()) try {
 		const sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
 		console.log("Installing the framework skill bundled with this first-tree package...");
 		console.log("Installing skill and scaffolding...");

package/dist/{installer-cH7N4RNj.js → installer-UgNasLjl.js}

@@ -1,4 +1,4 @@
-import { g as SKILL_ROOT, m as LEGACY_SKILL_ROOT } from "./repo-DY57bMqr.js";
+import { S as LEGACY_SKILL_ROOT, a as BUNDLED_SKILL_ROOT, m as INSTALLED_SKILL_ROOTS, y as LEGACY_REPO_SKILL_ROOT } from "./repo-DkR12VUv.js";
 import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -6,7 +6,7 @@ import { dirname, join } from "node:path";
 function resolveBundledPackageRoot(startUrl = import.meta.url) {
 	let dir = dirname(fileURLToPath(startUrl));
 	while (true) {
-		if (existsSync(join(dir, "package.json")) && existsSync(join(dir, SKILL_ROOT, "SKILL.md"))) return dir;
+		if (existsSync(join(dir, "package.json")) && existsSync(join(dir, BUNDLED_SKILL_ROOT, "SKILL.md"))) return dir;
 		const parent = dirname(dir);
 		if (parent === dir) break;
 		dir = parent;
@@ -16,24 +16,28 @@ function resolveBundledPackageRoot(startUrl = import.meta.url) {
 function resolveCanonicalSkillRoot(sourceRoot) {
 	const directSkillRoot = sourceRoot;
 	if (existsSync(join(directSkillRoot, "SKILL.md")) && existsSync(join(directSkillRoot, "assets", "framework", "VERSION"))) 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"))) return nestedSkillRoot;
 	throw new Error(`Canonical skill not found under ${sourceRoot}. Reinstall the \`first-tree\` package and try again.`);
 }
 function copyCanonicalSkill(sourceRoot, targetRoot) {
 	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
-	});
-	if (legacyDst !== dst && existsSync(legacyDst)) rmSync(legacyDst, {
-		recursive: true,
-		force: true
-	});
-	mkdirSync(dirname(dst), { recursive: true });
-	cpSync(src, dst, { recursive: 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
+		});
+	}
+	for (const relPath of INSTALLED_SKILL_ROOTS) {
+		const dst = join(targetRoot, relPath);
+		mkdirSync(dirname(dst), { recursive: true });
+		cpSync(src, dst, { recursive: true });
+	}
 }
 function renderTemplateFile(frameworkRoot, templateName, targetRoot, targetPath) {
 	const src = join(frameworkRoot, "templates", templateName);

package/dist/onboarding-3zYUeYQb.js

@@ -0,0 +1,2 @@
+import { t as runOnboarding } from "./onboarding-Dd63N-V1.js";
+export { runOnboarding };

package/dist/onboarding-Dd63N-V1.js

@@ -0,0 +1,10 @@
+//#region skills/first-tree/references/onboarding.md
+var onboarding_default = "# Context Tree Onboarding\n\nYou are setting up a **Context Tree** — the living source of truth for an organization. This document tells you what it is and how to bootstrap one.\n\n---\n\n## What Is a Context Tree\n\nA Context Tree is a Git repository where every directory is a **domain** and every file is a **node**. Each node captures decisions, designs, and cross-domain relationships — the knowledge that would otherwise scatter across PRs, documents, and people's heads.\n\nKey properties:\n\n- **Nodes are markdown files.** Each directory has a `NODE.md` that describes the domain. Leaf `.md` files capture specific decisions or designs.\n- **Every node has an owner.** Declared in YAML frontmatter. Owners approve changes to their nodes.\n- **Organized by concern, not by repo or team.** An agent working on \"add SSO\" finds all auth context in one place — not split across 4 repos.\n- **The tree is never a snapshot — it's the current state.** When decisions change, the tree updates. Stale nodes are bugs.\n\n### Frontmatter Format\n\nEvery node has frontmatter:\n\n```yaml\n---\ntitle: \"Auth Architecture\"\nowners: [alice, bob]\nsoft_links: [/infrastructure/deployments]\n---\n```\n\n- `owners` — who can approve changes. `owners: []` inherits from parent. `owners: [*]` means anyone.\n- `soft_links` — cross-references to related nodes in other domains.\n\n### What Belongs in the Tree\n\nInformation an agent needs to **decide** on an approach — not to execute it.\n\n**Yes:** \"Auth spans 4 repos: backend issues JWTs, frontend uses Better Auth, extension uses OAuth popup, desktop uses localhost callback.\"\n\n**No:** The function signature of `auth_service.verify()` — that's in the code.\n\n---\n\n## Four Principles\n\n1. **Source of truth for decisions, not execution.** The tree captures the *what* and *why*. Execution details stay in source systems.\n2. **Agents are first-class participants.** The tree is designed for agents to navigate and update.\n3. **Transparency by default.** Reading is open to all. Writing requires owner approval.\n4. **Git-native.** Nodes are files, domains are directories. History, ownership, and review follow Git conventions.\n\n---\n\n## How to Set Up a Context Tree\n\n### Prerequisites\n\n- A source/workspace Git repository, or an already-created dedicated tree repo\n- Node.js 18+\n- The npm package is `first-tree`, the installed CLI command is\n  `context-tree`.\n- `context-tree init` installs the framework skill into\n  `.agents/skills/first-tree/` and `.claude/skills/first-tree/`.\n- Use `npx first-tree init` for one-off runs, or `npm install -g first-tree`\n  to add the `context-tree` command to your PATH\n\n### Step 1: Initialize\n\nRecommended workflow: run `context-tree init` from your source or workspace repo.\nThe CLI will create a sibling dedicated tree repo named `<repo>-context` by\ndefault and install the framework there.\n\n```bash\ncd my-org\ncontext-tree init\ncd ../my-org-context\n```\n\nIf you already created a dedicated tree repo manually, initialize it in place:\n\n```bash\nmkdir my-org-context && cd my-org-context\ngit init\ncontext-tree init --here\n```\n\nEither way, the framework installs into `.agents/skills/first-tree/` and\n`.claude/skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENTS.md`,\n`members/NODE.md`), and generates a task list in\n`.agents/skills/first-tree/progress.md`.\n\nPublishing tip: keep the tree repo in the same GitHub organization as the\nsource repo unless you have a reason not to.\n\n### Step 2: Work Through the Task List\n\nRead `.agents/skills/first-tree/progress.md`. It contains a checklist tailored\nto the current state of the repo. Complete each task:\n\n- Fill in `NODE.md` with your organization name, owners, and domains\n- Add project-specific instructions to `AGENTS.md` below the framework markers\n- Create member nodes under `members/`\n- Optionally configure agent integration (for Claude Code, the installed hook\n  assets live under `.claude/skills/first-tree/`)\n- Copy validation workflows from\n  `.agents/skills/first-tree/assets/framework/workflows/` to\n  `.github/workflows/`\n\nAs you complete each task, check it off in\n`.agents/skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.\n\n### Step 3: Verify\n\n```bash\ncontext-tree verify\n```\n\nOr, from your source/workspace repo:\n\n```bash\ncontext-tree verify --tree-path ../my-org-context\n```\n\nThis fails if any items in `.agents/skills/first-tree/progress.md` remain\nunchecked, and runs deterministic checks (valid frontmatter, node structure,\nmember nodes exist).\n\n### Step 4: Design Your Domains\n\nCreate top-level directories for your organization's primary concerns. Each needs a `NODE.md`:\n\n```\nmy-org-tree/\n  NODE.md              # root — lists all domains\n  engineering/\n    NODE.md            # decisions about architecture, infra, tooling\n  product/\n    NODE.md            # strategy, roadmap, user research\n  marketing/\n    NODE.md            # positioning, campaigns\n  members/\n    NODE.md            # team members and agents\n    alice/\n      NODE.md          # individual member node\n```\n\n### Step 5: Populate from Existing Work\n\nFor each domain, extract knowledge from existing repos, docs, and systems:\n\n- Decisions and their rationale\n- Cross-domain relationships and dependencies\n- Constraints that aren't obvious from the code\n\nThe tree doesn't duplicate source code — it captures what connects things and why they were built that way.\n\n---\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `context-tree init` | Create or refresh a dedicated tree repo. By default, running in a source/workspace repo creates a sibling `<repo>-context`; use `--here` to initialize the current repo in place. |\n| `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. Use `--tree-path` when invoking from another working directory. |\n| `context-tree upgrade` | Refresh the installed framework skill from the currently running `first-tree` npm package and generate follow-up tasks. Use `--tree-path` when invoking from another working directory. |\n| `context-tree help onboarding` | Print this onboarding guide. |\n\n---\n\n## Upgrading the Framework\n\nWhen the framework updates:\n\n```bash\ncontext-tree upgrade\n```\n\n`context-tree upgrade` refreshes `.agents/skills/first-tree/` and\n`.claude/skills/first-tree/` from the skill bundled with the currently running\n`first-tree` npm package, preserves your tree content, and generates follow-up\ntasks in `.agents/skills/first-tree/progress.md`.\n\nIf your repo still uses the older `skills/first-tree/`,\n`skills/first-tree-cli-framework/`, or `.context-tree/` layouts,\n`context-tree upgrade` will migrate it to the current installed layout first.\n\nTo pick up a newer framework release, first run a newer package version, for\nexample `npx first-tree@latest upgrade`, or update your global `first-tree`\ninstall before running `context-tree upgrade`.\n\n---\n\n## Further Reading\n\n- `.agents/skills/first-tree/references/principles.md` — Core principles with detailed examples\n- `.agents/skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned\n- `AGENTS.md` in your tree — The before/during/after workflow for every task\n";
+//#endregion
+//#region skills/first-tree/engine/onboarding.ts
+function runOnboarding(output = console.log) {
+	output(onboarding_default);
+	return 0;
+}
+//#endregion
+export { onboarding_default as n, runOnboarding as t };

package/dist/{repo-DY57bMqr.js → repo-DkR12VUv.js}

@@ -2,7 +2,10 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 //#region skills/first-tree/engine/runtime/asset-loader.ts
 const SKILL_NAME = "first-tree";
-const SKILL_ROOT = join("skills", SKILL_NAME);
+const BUNDLED_SKILL_ROOT = join("skills", SKILL_NAME);
+const SKILL_ROOT = join(".agents", "skills", SKILL_NAME);
+const CLAUDE_SKILL_ROOT = join(".claude", "skills", SKILL_NAME);
+const INSTALLED_SKILL_ROOTS = [SKILL_ROOT, CLAUDE_SKILL_ROOT];
 join(SKILL_ROOT, "agents");
 join(SKILL_ROOT, "references");
 const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
@@ -17,6 +20,29 @@ const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
 const AGENT_INSTRUCTIONS_FILE = "AGENTS.md";
 const LEGACY_AGENT_INSTRUCTIONS_FILE = "AGENT.md";
 const AGENT_INSTRUCTIONS_TEMPLATE = "agents.md.template";
+join(CLAUDE_SKILL_ROOT, "agents");
+join(CLAUDE_SKILL_ROOT, "references");
+const CLAUDE_FRAMEWORK_ASSET_ROOT = join(CLAUDE_SKILL_ROOT, "assets", "framework");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "manifest.json");
+const CLAUDE_FRAMEWORK_VERSION = join(CLAUDE_FRAMEWORK_ASSET_ROOT, "VERSION");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "templates");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "workflows");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "prompts");
+const CLAUDE_FRAMEWORK_EXAMPLES_DIR = join(CLAUDE_FRAMEWORK_ASSET_ROOT, "examples");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "helpers");
+const CLAUDE_INSTALLED_PROGRESS = join(CLAUDE_SKILL_ROOT, "progress.md");
+const LEGACY_REPO_SKILL_ROOT = join("skills", SKILL_NAME);
+join(LEGACY_REPO_SKILL_ROOT, "agents");
+join(LEGACY_REPO_SKILL_ROOT, "references");
+const LEGACY_REPO_SKILL_ASSET_ROOT = join(LEGACY_REPO_SKILL_ROOT, "assets", "framework");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "manifest.json");
+const LEGACY_REPO_SKILL_VERSION = join(LEGACY_REPO_SKILL_ASSET_ROOT, "VERSION");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "templates");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "workflows");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "prompts");
+const LEGACY_REPO_SKILL_EXAMPLES_DIR = join(LEGACY_REPO_SKILL_ASSET_ROOT, "examples");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "helpers");
+const LEGACY_REPO_SKILL_PROGRESS = join(LEGACY_REPO_SKILL_ROOT, "progress.md");
 const LEGACY_SKILL_NAME = "first-tree-cli-framework";
 const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
 const LEGACY_SKILL_ASSET_ROOT = join(LEGACY_SKILL_ROOT, "assets", "framework");
@@ -24,7 +50,7 @@ const LEGACY_SKILL_VERSION = join(LEGACY_SKILL_ASSET_ROOT, "VERSION");
 join(LEGACY_SKILL_ASSET_ROOT, "templates");
 join(LEGACY_SKILL_ASSET_ROOT, "workflows");
 join(LEGACY_SKILL_ASSET_ROOT, "prompts");
-join(LEGACY_SKILL_ASSET_ROOT, "examples");
+const LEGACY_SKILL_EXAMPLES_DIR = join(LEGACY_SKILL_ASSET_ROOT, "examples");
 const LEGACY_SKILL_PROGRESS = join(LEGACY_SKILL_ROOT, "progress.md");
 const LEGACY_FRAMEWORK_ROOT = ".context-tree";
 const LEGACY_VERSION = join(LEGACY_FRAMEWORK_ROOT, "VERSION");
@@ -32,7 +58,7 @@ const LEGACY_PROGRESS = join(LEGACY_FRAMEWORK_ROOT, "progress.md");
 join(LEGACY_FRAMEWORK_ROOT, "templates");
 join(LEGACY_FRAMEWORK_ROOT, "workflows");
 join(LEGACY_FRAMEWORK_ROOT, "prompts");
-join(LEGACY_FRAMEWORK_ROOT, "examples");
+const LEGACY_EXAMPLES_DIR = join(LEGACY_FRAMEWORK_ROOT, "examples");
 function pathExists(root, relPath) {
 	const fullPath = join(root, relPath);
 	try {
@@ -41,9 +67,17 @@ function pathExists(root, relPath) {
 		return false;
 	}
 }
+function installedSkillRoots() {
+	return [...INSTALLED_SKILL_ROOTS];
+}
+function installedSkillRootsDisplay() {
+	return installedSkillRoots().map((root) => `\`${root}/\``).join(" and ");
+}
 function frameworkVersionCandidates() {
 	return [
 		FRAMEWORK_VERSION,
+		CLAUDE_FRAMEWORK_VERSION,
+		LEGACY_REPO_SKILL_VERSION,
 		LEGACY_SKILL_VERSION,
 		LEGACY_VERSION
 	];
@@ -51,6 +85,8 @@ function frameworkVersionCandidates() {
 function progressFileCandidates() {
 	return [
 		INSTALLED_PROGRESS,
+		CLAUDE_INSTALLED_PROGRESS,
+		LEGACY_REPO_SKILL_PROGRESS,
 		LEGACY_SKILL_PROGRESS,
 		LEGACY_PROGRESS
 	];
@@ -64,6 +100,8 @@ function resolveFirstExistingPath(root, candidates) {
 }
 function detectFrameworkLayout(root) {
 	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";
 	if (pathExists(root, LEGACY_VERSION)) return "legacy";
 	return null;
@@ -188,6 +226,15 @@ var Repo = class {
 	anyAgentConfig() {
 		return [".claude/settings.json", ".codex/config.json"].some((c) => this.pathExists(c));
 	}
+	installedSkillRoots() {
+		return installedSkillRoots();
+	}
+	missingInstalledSkillRoots() {
+		return this.installedSkillRoots().filter((root) => !this.pathExists(join(root, "SKILL.md")) || !this.pathExists(join(root, "assets", "framework", "VERSION")));
+	}
+	hasCurrentInstalledSkill() {
+		return this.missingInstalledSkillRoots().length === 0;
+	}
 	isGitRepo() {
 		return hasGitMetadata(this.root);
 	}
@@ -210,12 +257,16 @@ var Repo = class {
 		const layout = this.frameworkLayout();
 		if (layout === "legacy") return LEGACY_PROGRESS;
 		if (layout === "legacy-skill") return LEGACY_SKILL_PROGRESS;
+		if (layout === "legacy-repo-skill") return LEGACY_REPO_SKILL_PROGRESS;
+		if (layout === "claude-skill") return CLAUDE_INSTALLED_PROGRESS;
 		return INSTALLED_PROGRESS;
 	}
 	frameworkVersionPath() {
 		const layout = this.frameworkLayout();
 		if (layout === "legacy") return LEGACY_VERSION;
 		if (layout === "legacy-skill") return LEGACY_SKILL_VERSION;
+		if (layout === "legacy-repo-skill") return LEGACY_REPO_SKILL_VERSION;
+		if (layout === "claude-skill") return CLAUDE_FRAMEWORK_VERSION;
 		return FRAMEWORK_VERSION;
 	}
 	agentInstructionsPath() {
@@ -315,4 +366,4 @@ function isDirectory(root, relPath) {
 	}
 }
 //#endregion
-export { FRAMEWORK_ASSET_ROOT as a, FRAMEWORK_VERSION as c, LEGACY_AGENT_INSTRUCTIONS_FILE as d, LEGACY_FRAMEWORK_ROOT as f, SKILL_ROOT as g, SKILL_NAME as h, AGENT_INSTRUCTIONS_TEMPLATE as i, FRAMEWORK_WORKFLOWS_DIR as l, LEGACY_SKILL_ROOT as m, Repo as n, FRAMEWORK_EXAMPLES_DIR as o, LEGACY_SKILL_NAME as p, AGENT_INSTRUCTIONS_FILE as r, FRAMEWORK_TEMPLATES_DIR as s, FRAMEWORK_END_MARKER as t, INSTALLED_PROGRESS as u };
+export { SKILL_NAME as C, LEGACY_SKILL_ROOT as S, installedSkillRootsDisplay as T, LEGACY_FRAMEWORK_ROOT as _, BUNDLED_SKILL_ROOT as a, LEGACY_SKILL_EXAMPLES_DIR as b, FRAMEWORK_ASSET_ROOT as c, FRAMEWORK_VERSION as d, FRAMEWORK_WORKFLOWS_DIR as f, LEGACY_EXAMPLES_DIR as g, LEGACY_AGENT_INSTRUCTIONS_FILE as h, AGENT_INSTRUCTIONS_TEMPLATE as i, FRAMEWORK_EXAMPLES_DIR as l, INSTALLED_SKILL_ROOTS as m, Repo as n, CLAUDE_FRAMEWORK_EXAMPLES_DIR as o, INSTALLED_PROGRESS as p, AGENT_INSTRUCTIONS_FILE as r, CLAUDE_SKILL_ROOT as s, FRAMEWORK_END_MARKER as t, FRAMEWORK_TEMPLATES_DIR as u, LEGACY_REPO_SKILL_EXAMPLES_DIR as v, SKILL_ROOT as w, LEGACY_SKILL_NAME as x, LEGACY_REPO_SKILL_ROOT as y };

package/dist/{upgrade-Cgx_K2HM.js → upgrade-DYzuvv1k.js}

@@ -1,5 +1,5 @@
-import { c as FRAMEWORK_VERSION, d as LEGACY_AGENT_INSTRUCTIONS_FILE, f as LEGACY_FRAMEWORK_ROOT, g as SKILL_ROOT, i as AGENT_INSTRUCTIONS_TEMPLATE, l as FRAMEWORK_WORKFLOWS_DIR, m as LEGACY_SKILL_ROOT, n as Repo, r as AGENT_INSTRUCTIONS_FILE, s as FRAMEWORK_TEMPLATES_DIR, u as INSTALLED_PROGRESS } from "./repo-DY57bMqr.js";
-import { i as resolveCanonicalSkillRoot, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-cH7N4RNj.js";
+import { S as LEGACY_SKILL_ROOT, T as installedSkillRootsDisplay, _ as LEGACY_FRAMEWORK_ROOT, d as FRAMEWORK_VERSION, f as FRAMEWORK_WORKFLOWS_DIR, h as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, n as Repo, p as INSTALLED_PROGRESS, r as AGENT_INSTRUCTIONS_FILE, s as CLAUDE_SKILL_ROOT, u as FRAMEWORK_TEMPLATES_DIR, w as SKILL_ROOT, y as LEGACY_REPO_SKILL_ROOT } from "./repo-DkR12VUv.js";
+import { i as resolveCanonicalSkillRoot, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-UgNasLjl.js";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 //#region skills/first-tree/engine/runtime/upgrader.ts
@@ -37,13 +37,15 @@ function formatUpgradeTaskList(repo, localVersion, packagedVersion, layout) {
 	const lines = [
 		`# 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/\``,
 		""
 	];
 	const migrationTasks = [];
 	if (layout === "legacy") migrationTasks.push("- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files");
+	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`);
 	if (repo.hasCanonicalAgentInstructionsFile() && repo.hasLegacyAgentInstructionsFile()) migrationTasks.push(`- [ ] Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`);
 	else if (repo.hasLegacyAgentInstructionsFile()) migrationTasks.push(`- [ ] Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\` to use the canonical agent instructions filename`);
@@ -87,7 +89,8 @@ function runUpgrade(repo, options) {
 		console.log("The installed framework is newer than the skill bundled with this `first-tree` package. Install a newer package version before running `context-tree upgrade`.");
 		return 1;
 	}
-	if (layout === "skill" && packagedVersion === localVersion) {
+	const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+	if (layout === "skill" && missingInstalledRoots.length === 0 && packagedVersion === localVersion) {
 		console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
 		return 0;
 	}
@@ -97,9 +100,11 @@ function runUpgrade(repo, options) {
 			recursive: true,
 			force: true
 		});
-		console.log("Migrated legacy .context-tree/ layout to skills/first-tree/.");
-	} else if (layout === "legacy-skill") console.log("Migrated skills/first-tree-cli-framework/ to skills/first-tree/.");
-	else console.log("Refreshed skills/first-tree/ from the bundled first-tree package.");
+		console.log(`Migrated legacy .context-tree/ layout to ${installedSkillRootsDisplay()}.`);
+	} else if (layout === "legacy-repo-skill") console.log(`Migrated legacy ${LEGACY_REPO_SKILL_ROOT}/ layout to ${installedSkillRootsDisplay()}.`);
+	else if (layout === "legacy-skill") console.log(`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(workingRepo, localVersion, packagedVersion, layout);
 	console.log(`\n${output}`);
 	writeProgress(workingRepo, output);

package/dist/{verify-mC9ZTd1f.js → verify-C0IUSkMZ.js}

@@ -1,4 +1,4 @@
-import { d as LEGACY_AGENT_INSTRUCTIONS_FILE, g as SKILL_ROOT, m as LEGACY_SKILL_ROOT, n as Repo, r as AGENT_INSTRUCTIONS_FILE } from "./repo-DY57bMqr.js";
+import { S as LEGACY_SKILL_ROOT, h as LEGACY_AGENT_INSTRUCTIONS_FILE, n as Repo, r as AGENT_INSTRUCTIONS_FILE, w as SKILL_ROOT } from "./repo-DkR12VUv.js";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 //#region skills/first-tree/engine/validators/members.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "first-tree",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "CLI tools for Context Tree — the living source of truth for your organization.",
   "homepage": "https://github.com/agent-team-foundation/first-tree#readme",
   "bugs": {
@@ -19,7 +19,7 @@
   ],
   "type": "module",
   "bin": {
-    "context-tree": "./dist/cli.js"
+    "context-tree": "dist/cli.js"
   },
   "imports": {
     "#skill/*": "./skills/first-tree/*",
@@ -30,6 +30,15 @@
     "dist",
     "skills/first-tree"
   ],
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "pnpm build",
+    "test": "vitest run",
+    "eval": "vitest run --config vitest.eval.config.ts",
+    "typecheck": "tsc --noEmit",
+    "validate:skill": "python3 ./skills/first-tree/scripts/quick_validate.py ./skills/first-tree && bash ./skills/first-tree/scripts/check-skill-sync.sh"
+  },
+  "packageManager": "pnpm@10.25.0",
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/node": "^25.5.0",
@@ -37,12 +46,5 @@
     "typescript": "^5.8.0",
     "vitest": "^3.2.0",
     "yaml": "^2.8.3"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "test": "vitest run",
-    "eval": "vitest run --config vitest.eval.config.ts",
-    "typecheck": "tsc --noEmit",
-    "validate:skill": "python3 ./skills/first-tree/scripts/quick_validate.py ./skills/first-tree && bash ./skills/first-tree/scripts/check-skill-sync.sh"
   }
-}
+}

package/skills/first-tree/SKILL.md

@@ -6,8 +6,9 @@ description: Maintain the canonical `first-tree` skill and the thin `context-tre
 # First Tree
 
 Use this skill when the task depends on the exact behavior of the
-`context-tree` CLI or the installed `skills/first-tree/` payload that
-`context-tree init` ships to user repos.
+`context-tree` CLI or the installed `.agents/skills/first-tree/` and
+`.claude/skills/first-tree/` payloads that `context-tree init` ships to user
+repos.
 
 ## Source Of Truth
 
@@ -17,9 +18,9 @@ Use this skill when the task depends on the exact behavior of the
   repos.
 - `engine/` holds the canonical framework and CLI behavior.
 - `scripts/` holds maintenance helpers for validating and running the skill.
-- In maintainer docs, use `context-tree` for the CLI and `skills/first-tree/`
-  for the installed skill path so it is not confused with the `first-tree`
-  npm package.
+- In maintainer docs, use `context-tree` for the CLI, `skills/first-tree/` for
+  the bundled source path, and `.agents/skills/first-tree/` /
+  `.claude/skills/first-tree/` for installed user-repo paths.
 
 ## When To Read What
 
@@ -61,11 +62,12 @@ Use this skill when the task depends on the exact behavior of the
   repo when invoked from a source/workspace repo. Use `--here` to initialize
   the current repo in place when you are already inside the tree repo.
 - `context-tree init` installs this skill into the target tree repo and
+  scaffolds `.agents/skills/first-tree/`, `.claude/skills/first-tree/`,
   `NODE.md`, `AGENTS.md`, and `members/NODE.md`.
 - `context-tree upgrade` refreshes the installed skill from the copy bundled
   with the currently running `first-tree` package. To pick up a newer
   framework, run a newer package version first. It also migrates older repos
-  that still use `skills/first-tree-cli-framework/`.
+  that still use `skills/first-tree/` or `skills/first-tree-cli-framework/`.
 - The user's tree content lives outside the skill; the skill only carries the
   reusable framework payload plus maintenance guidance.
 - The tree still stores decisions, constraints, and ownership; execution detail
@@ -79,6 +81,8 @@ Use this skill when the task depends on the exact behavior of the
 - Keep decision knowledge in the tree and execution detail in source systems.
 - Keep the skill as the only canonical knowledge source. The root CLI/package
   shell must not become a second source of framework semantics.
+- Keep the CLI name written as `context-tree` in maintainer and user-facing
+  docs so it is not confused with the `first-tree` package that ships it.
 - Keep normal `init` / `upgrade` flows self-contained. They must work from the
   skill bundled in the current package without cloning the source repo or
   relying on network access.

package/skills/first-tree/assets/framework/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

package/skills/first-tree/assets/framework/examples/claude-code/README.md

@@ -6,9 +6,9 @@ Copy `settings.json` to your tree repo's `.claude/` directory:
 
 ```bash
 mkdir -p .claude
-cp skills/first-tree/assets/framework/examples/claude-code/settings.json .claude/settings.json
+cp .claude/skills/first-tree/assets/framework/examples/claude-code/settings.json .claude/settings.json
 ```
 
 ## What It Does
 
-The `SessionStart` hook runs `./skills/first-tree/assets/framework/helpers/inject-tree-context.sh` when a Claude Code session begins. This injects the root `NODE.md` content as additional context, giving the agent an overview of the tree structure before any task.
+The `SessionStart` hook runs `./.claude/skills/first-tree/assets/framework/helpers/inject-tree-context.sh` when a Claude Code session begins. This injects the root `NODE.md` content as additional context, giving the agent an overview of the tree structure before any task.

package/skills/first-tree/assets/framework/examples/claude-code/settings.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./skills/first-tree/assets/framework/helpers/inject-tree-context.sh"
+            "command": "./.claude/skills/first-tree/assets/framework/helpers/inject-tree-context.sh"
           }
         ]
       }

package/skills/first-tree/assets/framework/helpers/generate-codeowners.ts

@@ -205,7 +205,7 @@ export function generate(
       return 0;
     }
     console.log(
-      "CODEOWNERS is out-of-date. Run: npx tsx skills/first-tree/assets/framework/helpers/generate-codeowners.ts",
+      "CODEOWNERS is out-of-date. Run: npx tsx .agents/skills/first-tree/assets/framework/helpers/generate-codeowners.ts",
     );
     return 1;
   }

package/skills/first-tree/assets/framework/helpers/run-review.ts

@@ -39,7 +39,7 @@ function buildPrompt(diffPath: string): string {
     ["Root NODE.md", "NODE.md"],
     [
       "Review Instructions",
-      "skills/first-tree/assets/framework/prompts/pr-review.md",
+      ".agents/skills/first-tree/assets/framework/prompts/pr-review.md",
     ],
   ];
   for (const [heading, path] of files) {

package/skills/first-tree/assets/framework/templates/agents.md.template

@@ -13,7 +13,7 @@ You are working in a **Context Tree** — the living source of truth for decisio
 
 4. **Git-native tree structure.** Each node is a file; each domain is a directory. Soft links allow cross-references without the complexity of a full graph. History, ownership, and review follow Git conventions.
 
-See `skills/first-tree/references/principles.md` for detailed explanations and examples.
+See `.agents/skills/first-tree/references/principles.md` for detailed explanations and examples.
 
 ## Before Every Task
 
@@ -41,7 +41,7 @@ Ask yourself: **Does the tree need updating?**
 
 ## Reference
 
-For ownership rules, tree structure, and key files, see [NODE.md](NODE.md) and `skills/first-tree/references/ownership-and-naming.md`.
+For ownership rules, tree structure, and key files, see [NODE.md](NODE.md) and `.agents/skills/first-tree/references/ownership-and-naming.md`.
 <!-- END CONTEXT-TREE FRAMEWORK -->
 
 # Project-Specific Instructions

package/skills/first-tree/assets/framework/templates/members-domain.md.template

@@ -34,7 +34,7 @@ domains:
 ---
 ```
 
-See `skills/first-tree/assets/framework/templates/member-node.md.template` for a full scaffold.
+See `.agents/skills/first-tree/assets/framework/templates/member-node.md.template` for a full scaffold.
 
 ---
 

package/skills/first-tree/assets/framework/templates/root-node.md.template

@@ -34,8 +34,8 @@ tree describes.
 
 See [AGENTS.md](AGENTS.md) for agent instructions — the before/during/after workflow, ownership model, and tree maintenance.
 
-See [about.md](skills/first-tree/references/about.md) for background — the problem, the idea, and who it's for.
+See [about.md](.agents/skills/first-tree/references/about.md) for background — the problem, the idea, and who it's for.
 
 See the installed framework documentation:
-- [principles.md](skills/first-tree/references/principles.md) — core principles with examples
-- [ownership-and-naming.md](skills/first-tree/references/ownership-and-naming.md) — node naming and ownership model
+- [principles.md](.agents/skills/first-tree/references/principles.md) — core principles with examples
+- [ownership-and-naming.md](.agents/skills/first-tree/references/ownership-and-naming.md) — node naming and ownership model

package/skills/first-tree/assets/framework/workflows/codeowners.yml

@@ -19,7 +19,7 @@ jobs:
         with:
           node-version: "22"
 
-      - run: npx tsx skills/first-tree/assets/framework/helpers/generate-codeowners.ts
+      - run: npx tsx .agents/skills/first-tree/assets/framework/helpers/generate-codeowners.ts
 
       - name: Commit if changed
         run: |