first-tree 0.0.3 → 0.0.5

package/README.md

@@ -1,56 +1,96 @@
 # first-tree
 
-Thin distribution package for the `context-tree` CLI and the bundled canonical
-`first-tree` skill.
+`first-tree` publishes the `context-tree` CLI and bundles the canonical
+`first-tree` skill used to bootstrap and maintain Context Tree repos.
 
-## Package Name vs Command
+## Install And Run
 
-- The npm package is `first-tree`.
-- The installed CLI command is `context-tree`.
-- The installed skill directory inside a user tree is `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.
+- One-off use without installing globally:
 
-## What This Repo Ships
+  ```bash
+  npx first-tree init
+  ```
 
-- `src/` keeps the thin CLI shell that parses commands and dispatches to the
-  bundled skill.
-- `skills/first-tree/` is the canonical source for framework behavior, shipped
-  templates, maintainer references, and validation logic.
-- `evals/` is maintainer-only developer tooling for the source repo. It is
-  intentionally not part of the published package.
+- Global install:
+
+  ```bash
+  npm install -g first-tree
+  context-tree init
+  ```
+
+- Show the installed CLI version:
+
+  ```bash
+  context-tree --version
+  ```
+
+- Show the command list:
+
+  ```bash
+  context-tree --help
+  ```
+
+Although the npm package is named `first-tree`, the installed CLI command is
+`context-tree`.
 
 ## Quick Start
 
-If you are starting a brand-new tree, create a git repo first:
+Recommended workflow: start from your source or workspace repo and let
+`context-tree init` create a sibling dedicated tree repo.
 
 ```bash
-mkdir my-org-tree && cd my-org-tree
-git init
+cd my-app
 npx first-tree init
+cd ../my-app-context
 ```
 
-If you already have the command on your PATH:
+If you already created a dedicated tree repo yourself, initialize it in place:
 
 ```bash
-context-tree init
+mkdir my-org-context && cd my-org-context
+git init
+context-tree init --here
 ```
 
-The `first-tree` npm package carries the bundled canonical skill, and
-`context-tree init` / `context-tree upgrade` install from that bundled copy
-instead of cloning this source repo at runtime.
+- `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.
+- `context-tree upgrade` refreshes the installed skill from the currently
+  running `first-tree` npm package. To force the newest published package for a
+  one-off upgrade, run `npx first-tree@latest upgrade`.
+
+The package carries the bundled canonical skill, so `init` and `upgrade`
+install from the package payload instead of cloning this source repo at
+runtime.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `context-tree init` | Bootstrap a new context tree in the current git repo |
+| `context-tree init` | Create or refresh a dedicated context tree repo; use `--here` to initialize the current repo in place |
 | `context-tree verify` | Run verification checks against the current tree |
 | `context-tree upgrade` | Refresh the installed skill from the current `first-tree` npm package and write follow-up tasks |
 | `context-tree help onboarding` | Print the onboarding guide |
+| `context-tree --help` | Show the available commands |
+| `context-tree --version` | Print the installed CLI version |
+
+## Package Name vs Command
+
+- 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
 
@@ -58,6 +98,17 @@ instead of cloning this source repo at runtime.
 - This source repo: use Node.js 22 and pnpm 10 to match CI and the checked-in
   package manager version.
 
+## What This Repo Ships
+
+- `src/` keeps the thin CLI shell that parses commands and dispatches to the
+  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.
+
 ## Developing This Repo
 
 Run these commands from the repo root:

package/dist/cli.js

@@ -1,20 +1,35 @@
 #!/usr/bin/env node
-import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 //#region src/cli.ts
 const USAGE = `usage: context-tree <command>
 
   New to context-tree? Run \`context-tree help onboarding\` first.
 
 Commands:
-  init      Bootstrap a new context tree (installs the framework skill)
-  verify    Run verification checks against the current tree
-  upgrade   Refresh the installed skill from the current first-tree npm package and generate follow-up tasks
+  init      Create or refresh a dedicated context tree repo
+  verify    Run verification checks against a tree repo
+  upgrade   Refresh the installed skill in a tree repo
   help      Show help for a topic (e.g. \`help onboarding\`)
 
 Options:
   --help       Show this help message
   --version    Show version number
+
+Common examples:
+  context-tree init
+  context-tree init --here
+  context-tree verify --tree-path ../my-org-context
+  context-tree upgrade --tree-path ../my-org-context
 `;
+function isDirectExecution(argv1, metaUrl = import.meta.url) {
+	if (argv1 === void 0) return false;
+	try {
+		return realpathSync(argv1) === realpathSync(fileURLToPath(metaUrl));
+	} catch {
+		return false;
+	}
+}
 async function runCli(args, output = console.log) {
 	const write = (text) => output(text);
 	if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
@@ -29,18 +44,18 @@ async function runCli(args, output = console.log) {
 	const command = args[0];
 	switch (command) {
 		case "init": {
-			const { runInit } = await import("./init-DtOjj0wc.js");
-			return runInit();
+			const { runInit } = await import("./init-CAq0Uhq6.js");
+			return runInit(args.slice(1));
 		}
 		case "verify": {
-			const { runVerify } = await import("./verify-CxN6JiV9.js");
-			return runVerify();
+			const { runVerify } = await import("./verify-C0IUSkMZ.js");
+			return runVerify(args.slice(1));
 		}
 		case "upgrade": {
-			const { runUpgrade } = await import("./upgrade-COGgI7Rj.js");
-			return runUpgrade();
+			const { runUpgrade } = await import("./upgrade-DYzuvv1k.js");
+			return runUpgrade(args.slice(1));
 		}
-		case "help": return (await import("./help-xEI-s9iN.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);
@@ -50,6 +65,6 @@ async function runCli(args, output = console.log) {
 async function main() {
 	return runCli(process.argv.slice(2));
 }
-if (process.argv[1] !== void 0 && import.meta.url === pathToFileURL(process.argv[1]).href) main().then((code) => process.exit(code));
+if (isDirectExecution(process.argv[1])) main().then((code) => process.exit(code));
 //#endregion
-export { USAGE, runCli };
+export { USAGE, isDirectExecution, runCli };

package/dist/{help-xEI-s9iN.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-6Fr5Gkrk.js");
+			const { runOnboarding } = await import("./onboarding-3zYUeYQb.js");
 			return runOnboarding(output);
 		}
 		default:

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

@@ -1,8 +1,9 @@
-import { a as FRAMEWORK_TEMPLATES_DIR, c as INSTALLED_PROGRESS, d as SKILL_ROOT, i as FRAMEWORK_EXAMPLES_DIR, n as Repo, o as FRAMEWORK_VERSION, r as FRAMEWORK_ASSET_ROOT, s as FRAMEWORK_WORKFLOWS_DIR, t as FRAMEWORK_END_MARKER } from "./repo-BTJG8BU1.js";
-import { n as onboarding_default } from "./onboarding-B9zPGvvG.js";
-import { n as renderTemplateFile, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-rcZpGLnM.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 { dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { dirname, join, relative, resolve } from "node:path";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -19,12 +20,24 @@ var __exportAll = (all, no_symbols) => {
 var agent_instructions_exports = /* @__PURE__ */ __exportAll({ evaluate: () => evaluate$6 });
 function evaluate$6(repo) {
 	const tasks = [];
-	if (!repo.pathExists("AGENT.md")) tasks.push(`AGENT.md is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/agent.md.template\``);
-	else if (!repo.hasAgentMdMarkers()) tasks.push("AGENT.md exists but is missing framework markers — add `<!-- BEGIN CONTEXT-TREE FRAMEWORK -->` and `<!-- END CONTEXT-TREE FRAMEWORK -->` sections");
+	const hasCanonicalInstructions = repo.hasCanonicalAgentInstructionsFile();
+	const hasLegacyInstructions = repo.hasLegacyAgentInstructionsFile();
+	if (!hasCanonicalInstructions && !hasLegacyInstructions) {
+		tasks.push(`${AGENT_INSTRUCTIONS_FILE} is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/${AGENT_INSTRUCTIONS_TEMPLATE}\``);
+		return {
+			group: "Agent Instructions",
+			order: 3,
+			tasks
+		};
+	}
+	if (hasCanonicalInstructions && hasLegacyInstructions) tasks.push(`Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`);
+	else if (hasLegacyInstructions) tasks.push(`Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\` to use the canonical agent instructions filename`);
+	const instructionsPath = repo.agentInstructionsPath() ?? "AGENTS.md";
+	if (!repo.hasAgentInstructionsMarkers()) tasks.push(`\`${instructionsPath}\` exists but is missing framework markers — add \`<!-- BEGIN CONTEXT-TREE FRAMEWORK -->\` and \`<!-- END CONTEXT-TREE FRAMEWORK -->\` sections`);
 	else {
-		const afterMarker = (repo.readFile("AGENT.md") ?? "").split(FRAMEWORK_END_MARKER);
+		const afterMarker = (repo.readAgentInstructions() ?? "").split(FRAMEWORK_END_MARKER);
 		if (afterMarker.length > 1) {
-			if (afterMarker[1].trim().split("\n").filter((l) => l.trim() && !l.trim().startsWith("#") && !l.trim().startsWith("<!--")).length === 0) tasks.push("Add your project-specific instructions below the framework markers in AGENT.md");
+			if (afterMarker[1].trim().split("\n").filter((l) => l.trim() && !l.trim().startsWith("#") && !l.trim().startsWith("<!--")).length === 0) tasks.push(`Add your project-specific instructions below the framework markers in ${AGENT_INSTRUCTIONS_FILE}`);
 		}
 	}
 	return {
@@ -34,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",
@@ -93,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,
@@ -178,22 +203,52 @@ function evaluateAll(repo) {
 * all generated task text at once.
 */
 const INTERACTIVE_TOOL = "AskUserQuestion";
+const INIT_USAGE = `usage: context-tree init [--here] [--tree-name NAME] [--tree-path PATH]
+
+By default, running \`context-tree init\` inside a source or workspace repo creates
+a sibling dedicated tree repo named \`<repo>-context\`.
+
+Options:
+  --here             Initialize the current repo in place
+  --tree-name NAME   Name the dedicated sibling tree repo to create
+  --tree-path PATH   Use an explicit tree repo path
+  --help             Show this help message
+`;
 const TEMPLATE_MAP = [
-	["root-node.md.template", "NODE.md"],
-	["agent.md.template", "AGENT.md"],
-	["members-domain.md.template", "members/NODE.md"]
+	{
+		templateName: "root-node.md.template",
+		targetPath: "NODE.md"
+	},
+	{
+		templateName: AGENT_INSTRUCTIONS_TEMPLATE,
+		targetPath: AGENT_INSTRUCTIONS_FILE,
+		skipIfExists: [AGENT_INSTRUCTIONS_FILE, LEGACY_AGENT_INSTRUCTIONS_FILE]
+	},
+	{
+		templateName: "members-domain.md.template",
+		targetPath: "members/NODE.md"
+	}
 ];
 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);
-	for (const [templateName, targetPath] of TEMPLATE_MAP) if (existsSync(join(target, targetPath))) console.log(`  Skipped ${targetPath} (already exists)`);
-	else if (renderTemplateFile(frameworkDir, templateName, target, targetPath)) console.log(`  Created ${targetPath}`);
+	for (const { templateName, targetPath, skipIfExists } of TEMPLATE_MAP) {
+		const existingPath = (skipIfExists ?? [targetPath]).find((candidate) => existsSync(join(target, candidate)));
+		if (existingPath !== void 0) console.log(`  Skipped ${targetPath} (found existing ${existingPath})`);
+		else if (renderTemplateFile(frameworkDir, templateName, target, targetPath)) console.log(`  Created ${targetPath}`);
+	}
 }
-function formatTaskList(groups) {
-	const lines = ["# Context Tree Init\n", `**Agent instructions:** Before starting work, analyze the full task list below and identify all information you need from the user. Ask the user for their code repositories or project directories so you can analyze the source yourself — derive project descriptions, domains, and members from the code instead of asking the user to describe them. Collect everything upfront using the **${INTERACTIVE_TOOL}** tool with structured options — present selectable choices (with label and description) so the user can pick instead of typing free-form answers. You may batch up to 4 questions per ${INTERACTIVE_TOOL} call.\n`];
+function formatTaskList(groups, context) {
+	const lines = ["# Context Tree Init\n"];
+	if (context?.dedicatedTreeRepo) {
+		lines.push("This repository is the dedicated Context Tree. Keep decisions, rationale, cross-domain relationships, and ownership here; keep execution detail in your source repositories.", "");
+		if (context.sourceRepoPath) lines.push(`**Bootstrap source repo:** \`${context.sourceRepoPath}\``, "");
+		lines.push("When you publish this tree repo, keep it in the same GitHub organization as the source repo unless you have a reason not to.", "");
+	}
+	lines.push(`**Agent instructions:** Before starting work, analyze the full task list below and identify all information you need from the user. Ask the user for their code repositories or project directories so you can analyze the source yourself — derive project descriptions, domains, and members from the code instead of asking the user to describe them. Collect everything upfront using the **${INTERACTIVE_TOOL}** tool with structured options — present selectable choices (with label and description) so the user can pick instead of typing free-form answers. You may batch up to 4 questions per ${INTERACTIVE_TOOL} call.\n`);
 	for (const group of groups) {
 		lines.push(`## ${group.group}`);
 		for (const task of group.tasks) lines.push(`- [ ] ${task}`);
@@ -203,7 +258,7 @@ function formatTaskList(groups) {
 	lines.push("After completing the tasks above, run `context-tree verify` to confirm:");
 	lines.push(`- [ ] \`${FRAMEWORK_VERSION}\` exists`);
 	lines.push("- [ ] Root NODE.md has valid frontmatter (title, owners)");
-	lines.push("- [ ] AGENT.md exists with framework markers");
+	lines.push(`- [ ] \`${AGENT_INSTRUCTIONS_FILE}\` is the only agent instructions file and has framework markers`);
 	lines.push("- [ ] `context-tree verify` passes with no errors");
 	lines.push("- [ ] At least one member node exists");
 	lines.push("");
@@ -219,12 +274,25 @@ function writeProgress(repo, content) {
 	writeFileSync(progressPath, content);
 }
 function runInit(repo, options) {
-	const r = repo ?? new Repo();
-	if (!r.isGitRepo()) {
-		console.error("Error: not a git repository. Initialize one first:\n  git init");
+	const sourceRepo = repo ?? new Repo();
+	const initTarget = resolveInitTarget(sourceRepo, options);
+	if (initTarget.ok === false) {
+		console.error(`Error: ${initTarget.message}`);
 		return 1;
 	}
-	if (!r.hasFramework()) try {
+	const r = initTarget.repo;
+	const taskListContext = initTarget.dedicatedTreeRepo ? {
+		dedicatedTreeRepo: true,
+		sourceRepoPath: relativePathFrom(r.root, sourceRepo.root)
+	} : void 0;
+	if (initTarget.dedicatedTreeRepo) {
+		console.log("Recommended workflow: keep the Context Tree in a dedicated repo separate from your source/workspace repo.");
+		console.log(`  Source repo: ${sourceRepo.root}`);
+		console.log(`  Tree repo:   ${r.root}`);
+		if (initTarget.createdGitRepo) console.log("  Initialized a new git repo for the tree.");
+		console.log();
+	}
+	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...");
@@ -243,11 +311,105 @@ function runInit(repo, options) {
 		console.log("All checks passed. Your context tree is set up.");
 		return 0;
 	}
-	const output = formatTaskList(groups);
+	const output = formatTaskList(groups, taskListContext);
 	console.log(output);
 	writeProgress(r, output);
 	console.log(`Progress file written to ${r.preferredProgressPath()}`);
+	if (initTarget.dedicatedTreeRepo) console.log(`Continue in ${relativePathFrom(sourceRepo.root, r.root)} and keep your source repos available as additional working directories when you populate the tree.`);
 	return 0;
 }
+function parseInitArgs(args) {
+	const parsed = {};
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		switch (arg) {
+			case "--here":
+				parsed.here = true;
+				break;
+			case "--tree-name": {
+				const value = args[index + 1];
+				if (!value) return { error: "Missing value for --tree-name" };
+				parsed.treeName = value;
+				index += 1;
+				break;
+			}
+			case "--tree-path": {
+				const value = args[index + 1];
+				if (!value) return { error: "Missing value for --tree-path" };
+				parsed.treePath = value;
+				index += 1;
+				break;
+			}
+			default: return { error: `Unknown init option: ${arg}` };
+		}
+	}
+	if (parsed.here && parsed.treeName) return { error: "Cannot combine --here with --tree-name" };
+	if (parsed.here && parsed.treePath) return { error: "Cannot combine --here with --tree-path" };
+	if (parsed.treeName && parsed.treePath) return { error: "Cannot combine --tree-name with --tree-path" };
+	return parsed;
+}
+function runInitCli(args = []) {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(INIT_USAGE);
+		return 0;
+	}
+	const parsed = parseInitArgs(args);
+	if ("error" in parsed) {
+		console.error(parsed.error);
+		console.log(INIT_USAGE);
+		return 1;
+	}
+	return runInit(void 0, parsed);
+}
+function resolveInitTarget(sourceRepo, options) {
+	if (!sourceRepo.isGitRepo()) return {
+		ok: false,
+		message: "not a git repository. Run this from your source/workspace repo, or create a dedicated tree repo first:\n  git init\n  context-tree init --here"
+	};
+	const targetRoot = determineTargetRoot(sourceRepo, options);
+	const dedicatedTreeRepo = targetRoot !== sourceRepo.root;
+	let createdGitRepo = false;
+	try {
+		createdGitRepo = ensureGitRepo(targetRoot, options?.gitInitializer);
+	} catch (err) {
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : "unknown error"
+		};
+	}
+	return {
+		ok: true,
+		createdGitRepo,
+		dedicatedTreeRepo,
+		repo: new Repo(targetRoot)
+	};
+}
+function determineTargetRoot(sourceRepo, options) {
+	if (options?.treePath) return resolve(options.currentCwd ?? process.cwd(), options.treePath);
+	if (options?.here) return sourceRepo.root;
+	if (options?.treeName) return join(dirname(sourceRepo.root), options.treeName);
+	if (sourceRepo.looksLikeTreeRepo() || sourceRepo.isLikelyEmptyRepo() || !sourceRepo.isLikelySourceRepo()) return sourceRepo.root;
+	return join(dirname(sourceRepo.root), `${sourceRepo.repoName()}-context`);
+}
+function ensureGitRepo(targetRoot, gitInitializer) {
+	if (existsSync(targetRoot)) {
+		if (!statSync(targetRoot).isDirectory()) throw new Error(`Target path is not a directory: ${targetRoot}`);
+		if (new Repo(targetRoot).isGitRepo()) return false;
+		if (readdirSync(targetRoot).length !== 0) throw new Error(`Target path exists and is not a git repository: ${targetRoot}. Run \`git init\` there first or choose a different tree path.`);
+	} else mkdirSync(targetRoot, { recursive: true });
+	(gitInitializer ?? defaultGitInitializer)(targetRoot);
+	return true;
+}
+function defaultGitInitializer(root) {
+	execFileSync("git", ["init"], {
+		cwd: root,
+		stdio: "ignore"
+	});
+}
+function relativePathFrom(from, to) {
+	const rel = relative(from, to);
+	if (rel === "") return ".";
+	return rel.startsWith("..") ? rel : `./${rel}`;
+}
 //#endregion
-export { runInit };
+export { runInitCli as runInit };

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

@@ -1,12 +1,12 @@
-import { d as SKILL_ROOT, u as LEGACY_SKILL_ROOT } from "./repo-BTJG8BU1.js";
-import { fileURLToPath } from "node:url";
+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";
 //#region skills/first-tree/engine/runtime/installer.ts
 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 };