first-tree 0.0.1 → 0.0.3

package/README.md

@@ -1,68 +1,102 @@
-# seed-tree
+# first-tree
 
-Template source and CLI for [Context Tree](https://context-tree.ai) — the living source of truth for your organization.
+Thin distribution package for the `context-tree` CLI and the bundled canonical
+`first-tree` skill.
 
-## What is Context Tree?
+## Package Name vs Command
 
-A tree-structured knowledge base that agents and humans build and maintain together. Every node represents a domain, decision, or design. Every node has an owner. When things change, the tree updates. See [docs/about.md](docs/about.md) for the full story.
+- 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.
+
+## 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.
+- `evals/` is maintainer-only developer tooling for the source repo. It is
+  intentionally not part of the published package.
 
 ## Quick Start
 
+If you are starting a brand-new tree, create a git repo first:
+
 ```bash
-npx context-tree init
+mkdir my-org-tree && cd my-org-tree
+git init
+npx first-tree init
 ```
 
-Run this inside a git repo. It clones the framework, renders scaffolding, and generates a task list for your agent to work through.
+If you already have the command on your PATH:
+
+```bash
+context-tree init
+```
+
+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.
 
 ## Commands
 
 | Command | What it does |
-|---------|-------------|
+| --- | --- |
 | `context-tree init` | Bootstrap a new context tree in the current git repo |
-| `context-tree verify` | Run checks against the tree, report pass/fail |
-| `context-tree upgrade` | Compare local framework version to upstream, generate upgrade tasks |
+| `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 |
 
-## What `init` creates
+## Runtime And Maintainer Prerequisites
 
-```
-your-tree/
-  .context-tree/           # framework (upgradable from seed-tree)
-    VERSION
-    principles.md
-    ownership-and-naming.md
-    templates/
-    workflows/
-    examples/
-  NODE.md                  # root node — your domains (from template)
-  AGENT.md                 # agent instructions with framework markers (from template)
-  members/
-    NODE.md                # members domain (from template)
-```
+- User trees: the onboarding guide targets Node.js 18+.
+- This source repo: use Node.js 22 and pnpm 10 to match CI and the checked-in
+  package manager version.
 
-## Upgrades
+## Developing This Repo
 
-After init, seed-tree is added as a git remote (`context-tree-upstream`). To upgrade the framework:
+Run these commands from the repo root:
 
 ```bash
-context-tree upgrade      # shows what changed and what to do
+pnpm install --frozen-lockfile
+pnpm validate:skill
+pnpm typecheck
+pnpm test
+pnpm build
 ```
 
-## Documentation
-
-- [docs/onboarding.md](docs/onboarding.md) — Onboarding guide for setting up a context tree (for agents)
-- [docs/about.md](docs/about.md) — What is Context Tree and who it's for
-- [.context-tree/principles.md](.context-tree/principles.md) — Core principles with examples
-- [.context-tree/ownership-and-naming.md](.context-tree/ownership-and-naming.md) — Node naming and ownership model
-
-## Development
+When package contents or install/upgrade behavior changes, also run:
 
 ```bash
-pnpm install
-pnpm test              # run tests
-pnpm typecheck         # type check
-pnpm build             # build CLI
+pnpm pack
 ```
 
+## Canonical Documentation
+
+All framework documentation, maintainer guidance, and shipped runtime assets
+live in `skills/first-tree/`.
+
+- User-facing overview: `skills/first-tree/references/about.md`
+- User onboarding: `skills/first-tree/references/onboarding.md`
+- Maintainer entrypoint: `skills/first-tree/references/source-map.md`
+
+If you are maintaining this repo, start with the source map instead of relying
+on root-level prose.
+
+## Contributing And Security
+
+- Use the GitHub issue forms for bug reports and feature requests so maintainers
+  get reproducible context up front.
+- See `CONTRIBUTING.md` for local setup, validation expectations, and where
+  changes should live.
+- See `CODE_OF_CONDUCT.md` for community expectations.
+- See `SECURITY.md` for vulnerability reporting guidance.
+
 ## License
 
 Apache 2.0

package/dist/cli.js

@@ -1,41 +1,55 @@
 #!/usr/bin/env node
+import { pathToFileURL } 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 (clones seed-tree, copies framework files)
+  init      Bootstrap a new context tree (installs the framework skill)
   verify    Run verification checks against the current tree
-  upgrade   Generate an upgrade task list from upstream changes
+  upgrade   Refresh the installed skill from the current first-tree npm package and generate follow-up tasks
+  help      Show help for a topic (e.g. \`help onboarding\`)
 
 Options:
-  --help    Show this help message
+  --help       Show this help message
+  --version    Show version number
 `;
-async function main() {
-	const args = process.argv.slice(2);
+async function runCli(args, output = console.log) {
+	const write = (text) => output(text);
 	if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
-		console.log(USAGE);
+		write(USAGE);
+		return 0;
+	}
+	if (args[0] === "--version" || args[0] === "-v") {
+		const { createRequire } = await import("node:module");
+		write(createRequire(import.meta.url)("../package.json").version);
 		return 0;
 	}
 	const command = args[0];
 	switch (command) {
 		case "init": {
-			const { runInit } = await import("./init-CE_944sb.js");
+			const { runInit } = await import("./init-DtOjj0wc.js");
 			return runInit();
 		}
 		case "verify": {
-			const { runVerify } = await import("./verify-DIz6qmBX.js");
+			const { runVerify } = await import("./verify-CxN6JiV9.js");
 			return runVerify();
 		}
 		case "upgrade": {
-			const { runUpgrade } = await import("./upgrade-Chr7z0CY.js");
+			const { runUpgrade } = await import("./upgrade-COGgI7Rj.js");
 			return runUpgrade();
 		}
+		case "help": return (await import("./help-xEI-s9iN.js")).runHelp(args.slice(1), write);
 		default:
-			console.log(`Unknown command: ${command}`);
-			console.log(USAGE);
+			write(`Unknown command: ${command}`);
+			write(USAGE);
 			return 1;
 	}
 }
-main().then((code) => process.exit(code));
+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));
 //#endregion
-export {};
+export { USAGE, runCli };

package/dist/help-xEI-s9iN.js

@@ -0,0 +1,25 @@
+//#region skills/first-tree/engine/commands/help.ts
+const HELP_USAGE = `usage: context-tree help <topic>
+
+Topics:
+  onboarding   How to set up a context tree from scratch
+`;
+async function runHelp(args, output = console.log) {
+	const topic = args[0];
+	if (!topic || topic === "--help" || topic === "-h") {
+		output(HELP_USAGE);
+		return 0;
+	}
+	switch (topic) {
+		case "onboarding": {
+			const { runOnboarding } = await import("./onboarding-6Fr5Gkrk.js");
+			return runOnboarding(output);
+		}
+		default:
+			output(`Unknown help topic: ${topic}`);
+			output(HELP_USAGE);
+			return 1;
+	}
+}
+//#endregion
+export { runHelp };

package/dist/init-DtOjj0wc.js

@@ -0,0 +1,253 @@
+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 { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region skills/first-tree/engine/rules/agent-instructions.ts
+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");
+	else {
+		const afterMarker = (repo.readFile("AGENT.md") ?? "").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");
+		}
+	}
+	return {
+		group: "Agent Instructions",
+		order: 3,
+		tasks
+	};
+}
+//#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 = [];
+	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/\`)`);
+	} 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",
+		order: 5,
+		tasks
+	};
+}
+//#endregion
+//#region skills/first-tree/engine/rules/ci-validation.ts
+var ci_validation_exports = /* @__PURE__ */ __exportAll({ evaluate: () => evaluate$4 });
+function evaluate$4(repo) {
+	const tasks = [];
+	let hasValidation = false;
+	let hasPrReview = false;
+	let hasCodeowners = false;
+	const workflowsDir = join(repo.root, ".github", "workflows");
+	try {
+		if (statSync(workflowsDir).isDirectory()) for (const name of readdirSync(workflowsDir)) {
+			if (!name.endsWith(".yml") && !name.endsWith(".yaml")) continue;
+			const fullPath = join(workflowsDir, name);
+			try {
+				if (!statSync(fullPath).isFile()) continue;
+				const content = readFileSync(fullPath, "utf-8");
+				if (content.includes("validate_nodes") || content.includes("validate_members")) hasValidation = true;
+				if (content.includes("run-review")) hasPrReview = true;
+				if (content.includes("generate-codeowners")) hasCodeowners = true;
+			} catch {
+				continue;
+			}
+		}
+	} catch {}
+	if (!hasValidation) tasks.push(`No validation workflow found — copy \`${FRAMEWORK_WORKFLOWS_DIR}/validate.yml\` to \`.github/workflows/validate.yml\``);
+	if (!hasPrReview) {
+		tasks.push(`Use ${INTERACTIVE_TOOL} to ask whether the user wants AI-powered PR reviews. Options:\n  1. **OpenRouter** — use an OpenRouter API key
+  2. **Claude API** — use a Claude API key directly
+  3. **Skip** — do not set up PR reviews
+If (1): copy \`${FRAMEWORK_WORKFLOWS_DIR}/pr-review.yml\` to \`.github/workflows/pr-review.yml\` as-is; the repo secret name is \`OPENROUTER_API_KEY\`. If (2): copy the workflow and replace the \`env\` block with \`ANTHROPIC_API_KEY: \${{ secrets.ANTHROPIC_API_KEY }}\`, remove the \`ANTHROPIC_BASE_URL\`, \`ANTHROPIC_AUTH_TOKEN\`, and \`ANTHROPIC_DEFAULT_SONNET_MODEL\` lines; the repo secret name is \`ANTHROPIC_API_KEY\`. If (3): skip this and the next task.`);
+		tasks.push(`Use ${INTERACTIVE_TOOL} to ask how the user wants to configure the API secret. Options:\n  1. **Set it now** — provide the key and the agent will run \`gh secret set <SECRET_NAME> --body <KEY>\`
+  2. **I'll do it myself** — the agent will show manual instructions
+If (1): ask the user to provide the key, then run \`gh secret set\` with the secret name from the previous step. If (2): tell the user to go to their repo → Settings → Secrets and variables → Actions → New repository secret, and create the secret with the name from the previous step. Skip this task if the user chose Skip in the previous step.`);
+	}
+	if (!hasCodeowners) tasks.push(`No CODEOWNERS workflow found — copy \`${FRAMEWORK_WORKFLOWS_DIR}/codeowners.yml\` to \`.github/workflows/codeowners.yml\` to auto-generate CODEOWNERS from tree ownership on every PR.`);
+	return {
+		group: "CI / Validation",
+		order: 6,
+		tasks
+	};
+}
+//#endregion
+//#region skills/first-tree/engine/rules/framework.ts
+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`);
+	return {
+		group: "Framework",
+		order: 1,
+		tasks
+	};
+}
+//#endregion
+//#region skills/first-tree/engine/rules/members.ts
+var members_exports = /* @__PURE__ */ __exportAll({ evaluate: () => evaluate$2 });
+function evaluate$2(repo) {
+	const tasks = [];
+	if (!repo.pathExists("members")) tasks.push("`members/` directory is missing — create it with a NODE.md");
+	else if (!repo.pathExists("members/NODE.md")) tasks.push("`members/NODE.md` is missing — create it from the template");
+	if (repo.hasMembers() && repo.memberCount() === 0) tasks.push("Add at least one member node under `members/`. Analyze the user's code repositories (git history, CODEOWNERS, README contributors) to suggest members, then confirm with the user");
+	else if (!repo.hasMembers()) tasks.push("Add at least one member node under `members/`. Analyze the user's code repositories (git history, CODEOWNERS, README contributors) to suggest members, then confirm with the user");
+	return {
+		group: "Members",
+		order: 4,
+		tasks
+	};
+}
+//#endregion
+//#region skills/first-tree/engine/rules/populate-tree.ts
+var populate_tree_exports = /* @__PURE__ */ __exportAll({ evaluate: () => evaluate$1 });
+function evaluate$1(repo) {
+	const tasks = [];
+	tasks.push(`Ask the user whether they want to populate the full context tree now using the **${INTERACTIVE_TOOL}** tool. Present two options: (1) **Yes — populate the full tree**: the agent will analyze source repositories, create sub-domains, and populate NODE.md files for each domain and sub-domain; (2) **No — I'll do it later**: skip deep population and finish init with just the top-level structure. If the user selects No, check off all remaining items in this section and move on.`);
+	tasks.push("If the user selected Yes: analyze the codebase (and any additional repositories the user provides) to identify logical sub-domains within each top-level domain. For each sub-domain, create a directory with a NODE.md containing proper frontmatter (title, owners) and a description of the sub-domain's purpose, boundaries, and key decisions. Create deeper sub-domains when a domain is large enough to warrant further decomposition.");
+	tasks.push("Use **sub-tasks** (TaskCreate) to parallelize the population work — create one sub-task per top-level domain so each domain can be populated concurrently. Each sub-task should: read the relevant source code, identify sub-domains, create NODE.md files, and establish soft_links between related domains.");
+	tasks.push("After all domains are populated, update the root NODE.md to list every top-level domain with a one-line description. Ensure all NODE.md files pass `context-tree verify` — valid frontmatter, no placeholders, and soft_links that resolve correctly.");
+	return {
+		group: "Populate Tree",
+		order: 7,
+		tasks
+	};
+}
+//#endregion
+//#region skills/first-tree/engine/rules/root-node.ts
+var root_node_exports = /* @__PURE__ */ __exportAll({ evaluate: () => evaluate });
+function evaluate(repo) {
+	const tasks = [];
+	if (!repo.pathExists("NODE.md")) tasks.push(`NODE.md is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/root-node.md.template\`. Ask the user for their code repositories or project directories, then analyze the source to determine the project description and domain structure`);
+	else {
+		const fm = repo.frontmatter("NODE.md");
+		if (fm === null) tasks.push("NODE.md exists but has no frontmatter — add frontmatter with title and owners fields");
+		else {
+			if (!fm.title || fm.title.startsWith("<")) tasks.push("NODE.md has a placeholder title — replace with your organization name");
+			if (!fm.owners || fm.owners.length === 0 || fm.owners.length === 1 && fm.owners[0].startsWith("<")) tasks.push("NODE.md has placeholder owners — set owners to your GitHub username(s)");
+		}
+		if (repo.hasPlaceholderNode()) tasks.push("NODE.md has placeholder content — ask the user for their code repositories or project directories, then analyze the source to fill in the project description and domain structure");
+	}
+	return {
+		group: "Root Node",
+		order: 2,
+		tasks
+	};
+}
+//#endregion
+//#region skills/first-tree/engine/rules/index.ts
+const ALL_RULES = [
+	framework_exports,
+	root_node_exports,
+	agent_instructions_exports,
+	members_exports,
+	agent_integration_exports,
+	ci_validation_exports,
+	populate_tree_exports
+];
+function evaluateAll(repo) {
+	const results = [];
+	for (const rule of ALL_RULES) {
+		const result = rule.evaluate(repo);
+		if (result.tasks.length > 0) results.push(result);
+	}
+	return results.sort((a, b) => a.order - b.order);
+}
+//#endregion
+//#region skills/first-tree/engine/init.ts
+/**
+* The interactive prompt tool the agent should use to present choices.
+* Different agents may name this differently — change it here to update
+* all generated task text at once.
+*/
+const INTERACTIVE_TOOL = "AskUserQuestion";
+const TEMPLATE_MAP = [
+	["root-node.md.template", "NODE.md"],
+	["agent.md.template", "AGENT.md"],
+	["members-domain.md.template", "members/NODE.md"]
+];
+function installSkill(source, target) {
+	copyCanonicalSkill(source, target);
+	console.log("  Installed skills/first-tree/ 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}`);
+}
+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`];
+	for (const group of groups) {
+		lines.push(`## ${group.group}`);
+		for (const task of group.tasks) lines.push(`- [ ] ${task}`);
+		lines.push("");
+	}
+	lines.push("## Verification");
+	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("- [ ] `context-tree verify` passes with no errors");
+	lines.push("- [ ] At least one member node exists");
+	lines.push("");
+	lines.push("---");
+	lines.push("");
+	lines.push(`**Important:** As you complete each task, check it off in \`${INSTALLED_PROGRESS}\` by changing \`- [ ]\` to \`- [x]\`. Run \`context-tree verify\` when done — it will fail if any items remain unchecked.`);
+	lines.push("");
+	return lines.join("\n");
+}
+function writeProgress(repo, content) {
+	const progressPath = join(repo.root, repo.preferredProgressPath());
+	mkdirSync(dirname(progressPath), { recursive: true });
+	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");
+		return 1;
+	}
+	if (!r.hasFramework()) try {
+		const sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+		console.log("Installing the framework skill bundled with this first-tree package...");
+		console.log("Installing skill and scaffolding...");
+		installSkill(sourceRoot, r.root);
+		renderTemplates(r.root);
+		console.log();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : "unknown error";
+		console.error(`Error: ${message}`);
+		return 1;
+	}
+	console.log(onboarding_default);
+	console.log("---\n");
+	const groups = evaluateAll(r);
+	if (groups.length === 0) {
+		console.log("All checks passed. Your context tree is set up.");
+		return 0;
+	}
+	const output = formatTaskList(groups);
+	console.log(output);
+	writeProgress(r, output);
+	console.log(`Progress file written to ${r.preferredProgressPath()}`);
+	return 0;
+}
+//#endregion
+export { runInit };

package/dist/installer-rcZpGLnM.js

@@ -0,0 +1,47 @@
+import { d as SKILL_ROOT, u as LEGACY_SKILL_ROOT } from "./repo-BTJG8BU1.js";
+import { fileURLToPath } from "node:url";
+import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+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;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	throw new Error("Could not locate the bundled `first-tree` package root. Reinstall the package and try again.");
+}
+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);
+	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 });
+}
+function renderTemplateFile(frameworkRoot, templateName, targetRoot, targetPath) {
+	const src = join(frameworkRoot, "templates", templateName);
+	const dst = join(targetRoot, targetPath);
+	if (existsSync(dst) || !existsSync(src)) return false;
+	mkdirSync(dirname(dst), { recursive: true });
+	copyFileSync(src, dst);
+	return true;
+}
+//#endregion
+export { resolveCanonicalSkillRoot as i, renderTemplateFile as n, resolveBundledPackageRoot as r, copyCanonicalSkill as t };

package/dist/onboarding-6Fr5Gkrk.js

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

package/dist/onboarding-B9zPGvvG.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 Git repository for your tree (separate from your code repos)\n- Node.js 18+\n- The npm package is `first-tree`, the installed CLI command is\n  `context-tree`, and the installed skill directory in the tree is\n  `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\n```bash\nmkdir my-org-tree && cd my-org-tree\ngit init\ncontext-tree init\n```\n\nThis installs the framework skill into `skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENT.md`, `members/NODE.md`), and generates a task list in `skills/first-tree/progress.md`.\n\n### Step 2: Work Through the Task List\n\nRead `skills/first-tree/progress.md`. It contains a checklist tailored to 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 `AGENT.md` below the framework markers\n- Create member nodes under `members/`\n- Optionally configure agent integration (e.g., Claude Code session hooks)\n- Copy validation workflows from `skills/first-tree/assets/framework/workflows/` to `.github/workflows/`\n\nAs you complete each task, check it off in `skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.\n\n### Step 3: Verify\n\n```bash\ncontext-tree verify\n```\n\nThis fails if any items in `skills/first-tree/progress.md` remain unchecked, and runs deterministic checks (valid frontmatter, node structure, member 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` | Bootstrap a new tree. Installs the framework skill, renders templates, generates a task list. |\n| `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. |\n| `context-tree upgrade` | Refresh the installed framework skill from the currently running `first-tree` npm package and generate follow-up tasks. |\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 `skills/first-tree/` from the\nskill bundled with the currently running `first-tree` npm package, preserves your\ntree content, and generates follow-up tasks in\n`skills/first-tree/progress.md`.\n\nIf your repo still uses the older `skills/first-tree-cli-framework/` path,\n`context-tree upgrade` will migrate it to `skills/first-tree/` 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- `skills/first-tree/references/principles.md` — Core principles with detailed examples\n- `skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned\n- `AGENT.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 };