first-tree 0.0.4 → 0.0.6

package/README.md

@@ -36,7 +36,8 @@ Although the npm package is named `first-tree`, the installed CLI command is
 ## Quick Start
 
 Recommended workflow: start from your source or workspace repo and let
-`context-tree init` create a sibling dedicated tree repo.
+`context-tree init` install local source/workspace integration and create a
+sibling dedicated tree repo.
 
 ```bash
 cd my-app
@@ -52,15 +53,28 @@ 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/` in the current source/workspace repo, appends a
+  single `FIRST-TREE-SOURCE-INTEGRATION:` line to root `AGENTS.md` and
+  `CLAUDE.md`, then creates `NODE.md`, tree-scoped `AGENTS.md`,
+  `members/NODE.md`, and a checklist in the dedicated tree repo at
+  `.agents/skills/first-tree/progress.md`.
+- Never create `NODE.md`, `members/`, or tree-scoped `AGENTS.md` in the
+  source/workspace repo. Those files live only in the dedicated `*-context`
+  repo.
+- After creating the dedicated tree repo, prefer pushing it to the same GitHub
+  organization as the source repo, add it back as a git submodule, and open a
+  PR to the source/workspace repo's default branch instead of merging
+  automatically.
 - `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`.
+  running `first-tree` npm package. In a source/workspace repo it refreshes
+  only the local installed skill plus the
+  `FIRST-TREE-SOURCE-INTEGRATION:` line; use `--tree-path` to upgrade the
+  dedicated tree repo. 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
@@ -70,20 +84,26 @@ runtime.
 
 | Command | What it does |
 | --- | --- |
-| `context-tree init` | Create or refresh a dedicated context tree repo; use `--here` to initialize the current repo in place |
+| `context-tree init` | Install source/workspace integration locally and 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 upgrade` | Refresh the installed skill from the current `first-tree` npm package; in a source/workspace repo it updates only local integration, while tree repos also get 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
 
-- 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 +117,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.
 
@@ -125,6 +147,7 @@ live in `skills/first-tree/`.
 
 - User-facing overview: `skills/first-tree/references/about.md`
 - User onboarding: `skills/first-tree/references/onboarding.md`
+- Source/workspace install contract: `skills/first-tree/references/source-workspace-installation.md`
 - Maintainer entrypoint: `skills/first-tree/references/source-map.md`
 
 If you are maintaining this repo, start with the source map instead of relying

package/dist/cli.js

@@ -7,7 +7,7 @@ const USAGE = `usage: context-tree <command>
   New to context-tree? Run \`context-tree help onboarding\` first.
 
 Commands:
-  init      Create or refresh a dedicated context tree repo
+  init      Install source/workspace integration and 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\`)
@@ -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-BgGH2_yC.js");
 			return runInit(args.slice(1));
 		}
 		case "verify": {
-			const { runVerify } = await import("./verify-mC9ZTd1f.js");
+			const { runVerify } = await import("./verify-G8gNXzDX.js");
 			return runVerify(args.slice(1));
 		}
 		case "upgrade": {
-			const { runUpgrade } = await import("./upgrade-Cgx_K2HM.js");
+			const { runUpgrade } = await import("./upgrade-BvA9oKmi.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-DV9-AaFp.js")).runHelp(args.slice(1), write);
 		default:
 			write(`Unknown command: ${command}`);
 			write(USAGE);

package/dist/{help-Dtdj91HJ.js → help-DV9-AaFp.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-lASHHmgO.js");
 			return runOnboarding(output);
 		}
 		default:

package/dist/{init--VepFe6N.js → init-BgGH2_yC.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 { D as SOURCE_INTEGRATION_MARKER, O as installedSkillRootsDisplay, _ as LEGACY_EXAMPLES_DIR, d as FRAMEWORK_TEMPLATES_DIR, f as FRAMEWORK_VERSION, g as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, l as FRAMEWORK_ASSET_ROOT, m as INSTALLED_PROGRESS, n as Repo, o as CLAUDE_FRAMEWORK_EXAMPLES_DIR, p as FRAMEWORK_WORKFLOWS_DIR, r as AGENT_INSTRUCTIONS_FILE, s as CLAUDE_INSTRUCTIONS_FILE, t as FRAMEWORK_END_MARKER, u as FRAMEWORK_EXAMPLES_DIR, x as LEGACY_SKILL_EXAMPLES_DIR, y as LEGACY_REPO_SKILL_EXAMPLES_DIR } from "./repo-Cc5U4DWT.js";
+import { n as onboarding_default } from "./onboarding-D7fGGOMN.js";
+import { i as resolveBundledPackageRoot, n as copyCanonicalSkill, r as renderTemplateFile, t as upsertSourceIntegrationFiles } from "./source-integration-CuKjoheT.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,
@@ -193,8 +205,10 @@ function evaluateAll(repo) {
 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\`.
+By default, running \`context-tree init\` inside a source or workspace repo installs
+the first-tree skill in the current repo, updates \`AGENTS.md\` and \`CLAUDE.md\`
+with a \`${SOURCE_INTEGRATION_MARKER}\` line, and creates a sibling dedicated tree
+repo named \`<repo>-context\`.
 
 Options:
   --here             Initialize the current repo in place
@@ -219,7 +233,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);
@@ -234,6 +248,14 @@ function formatTaskList(groups, context) {
 	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}\``, "");
+		if (context.sourceRepoName) {
+			lines.push(`**Source/workspace contract:** Keep \`${context.sourceRepoName}\` limited to the installed skill plus the \`${SOURCE_INTEGRATION_MARKER}\` lines in \`${AGENT_INSTRUCTIONS_FILE}\` and \`${CLAUDE_INSTRUCTIONS_FILE}\`. Never add \`NODE.md\`, \`members/\`, or tree-scoped \`${AGENT_INSTRUCTIONS_FILE}\` there.`, "");
+			lines.push("## Source Workspace Workflow");
+			lines.push(`- [ ] Publish this dedicated tree repo to the same GitHub organization as \`${context.sourceRepoName}\``);
+			lines.push(`- [ ] Add this tree repo back to \`${context.sourceRepoName}\` as a git submodule after the remote exists`);
+			lines.push(`- [ ] Open a PR against the source/workspace repo's default branch with only the installed skill, the \`${SOURCE_INTEGRATION_MARKER}\` marker lines in \`${AGENT_INSTRUCTIONS_FILE}\` / \`${CLAUDE_INSTRUCTIONS_FILE}\`, and the new submodule pointer`);
+			lines.push("");
+		}
 		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`);
@@ -271,20 +293,44 @@ function runInit(repo, options) {
 	const r = initTarget.repo;
 	const taskListContext = initTarget.dedicatedTreeRepo ? {
 		dedicatedTreeRepo: true,
+		sourceRepoName: sourceRepo.repoName(),
 		sourceRepoPath: relativePathFrom(r.root, sourceRepo.root)
 	} : void 0;
+	let sourceRoot = null;
+	const resolveSourceRoot = () => {
+		if (sourceRoot !== null) return sourceRoot;
+		sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+		return sourceRoot;
+	};
 	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(`  The source/workspace repo should keep only the installed skill and the ${SOURCE_INTEGRATION_MARKER} lines in ${AGENT_INSTRUCTIONS_FILE} and ${CLAUDE_INSTRUCTIONS_FILE}.`);
+		console.log(`  Never add NODE.md, members/, or tree-scoped ${AGENT_INSTRUCTIONS_FILE} to the source/workspace repo.`);
 		console.log();
 	}
-	if (!r.hasFramework()) try {
-		const sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+	if (initTarget.dedicatedTreeRepo) try {
+		const resolvedSourceRoot = resolveSourceRoot();
+		if (!sourceRepo.hasCurrentInstalledSkill()) {
+			console.log("Installing the first-tree skill into the source/workspace repo...");
+			installSkill(resolvedSourceRoot, sourceRepo.root);
+		}
+		const changedFiles = upsertSourceIntegrationFiles(sourceRepo.root, r.repoName()).filter((update) => update.action !== "unchanged").map((update) => update.file);
+		if (changedFiles.length > 0) console.log(`  Updated source/workspace instructions in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}`);
+		else console.log(`  Source/workspace instructions already contain ${SOURCE_INTEGRATION_MARKER}`);
+		console.log();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : "unknown error";
+		console.error(`Error: ${message}`);
+		return 1;
+	}
+	if (!r.hasCurrentInstalledSkill()) try {
+		const resolvedSourceRoot = resolveSourceRoot();
 		console.log("Installing the framework skill bundled with this first-tree package...");
 		console.log("Installing skill and scaffolding...");
-		installSkill(sourceRoot, r.root);
+		installSkill(resolvedSourceRoot, r.root);
 		renderTemplates(r.root);
 		console.log();
 	} catch (err) {

package/dist/onboarding-D7fGGOMN.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 install the bundled skill in the current repo, update root\n`AGENTS.md` and `CLAUDE.md` with a `FIRST-TREE-SOURCE-INTEGRATION:` line, and\ncreate a sibling dedicated tree repo named `<repo>-context` by default. Tree\nfiles are scaffolded only in the dedicated tree repo.\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\nHard boundary: do **not** create `NODE.md`, `members/`, or tree-scoped\n`AGENTS.md` in the source/workspace repo. Those files belong only in the\ndedicated `*-context` repo.\n\nDefault agent workflow after initialization:\n\n1. Create and push the dedicated `*-context` repo in the same GitHub\n   organization as the source repo.\n2. Add the dedicated tree repo back to the source/workspace repo as a `git submodule`.\n3. Open a PR against the source/workspace repo's default branch for the local\n   skill integration plus the new submodule pointer. Do not merge it\n   automatically.\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\nDo not run `context-tree verify` in the source/workspace repo itself. That repo\nonly carries the installed skill plus the\n`FIRST-TREE-SOURCE-INTEGRATION:` line.\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` | Install local source/workspace integration and 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 you run `context-tree upgrade` in the source/workspace repo, it refreshes\nonly the local installed skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines.\nRun `context-tree upgrade --tree-path ../my-org-context` to upgrade the\ndedicated tree repo itself.\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/source-workspace-installation.md` — Source/workspace install contract\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/onboarding-lASHHmgO.js

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

package/dist/{repo-DY57bMqr.js → repo-Cc5U4DWT.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,32 @@ 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";
+const CLAUDE_INSTRUCTIONS_FILE = "CLAUDE.md";
+const SOURCE_INTEGRATION_MARKER = "FIRST-TREE-SOURCE-INTEGRATION:";
+const SOURCE_INTEGRATION_FILES = [AGENT_INSTRUCTIONS_FILE, CLAUDE_INSTRUCTIONS_FILE];
+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 +53,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 +61,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 +70,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 +88,8 @@ function frameworkVersionCandidates() {
 function progressFileCandidates() {
 	return [
 		INSTALLED_PROGRESS,
+		CLAUDE_INSTALLED_PROGRESS,
+		LEGACY_REPO_SKILL_PROGRESS,
 		LEGACY_SKILL_PROGRESS,
 		LEGACY_PROGRESS
 	];
@@ -64,6 +103,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;
@@ -74,7 +115,9 @@ const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
 const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
 const TITLE_RE = /^title:\s*['"]?(.+?)['"]?\s*$/m;
 const EMPTY_REPO_ENTRY_ALLOWLIST = new Set([
+	".agents",
 	".DS_Store",
+	".claude",
 	".editorconfig",
 	".gitattributes",
 	".github",
@@ -188,6 +231,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 +262,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() {
@@ -240,6 +296,15 @@ var Repo = class {
 		if (text === null) return false;
 		return text.includes("<!-- BEGIN CONTEXT-TREE FRAMEWORK") && text.includes("<!-- END CONTEXT-TREE FRAMEWORK -->");
 	}
+	hasSourceIntegrationFile(relPath) {
+		return this.fileContains(relPath, SOURCE_INTEGRATION_MARKER);
+	}
+	hasSourceWorkspaceIntegration() {
+		return SOURCE_INTEGRATION_FILES.some((file) => this.hasSourceIntegrationFile(file));
+	}
+	hasTreeContent() {
+		return this.progressPath() !== null || this.hasAgentInstructionsMarkers() || this.pathExists("members/NODE.md") || this.frontmatter("NODE.md") !== null;
+	}
 	hasMembers() {
 		const membersDir = join(this.root, "members");
 		try {
@@ -287,13 +352,19 @@ var Repo = class {
 	}
 	looksLikeTreeRepo() {
 		if (this.pathExists("package.json") && this.pathExists("src/cli.ts") && this.pathExists("skills/first-tree/SKILL.md") && this.progressPath() === null && this.frontmatter("NODE.md") === null && !this.hasAgentInstructionsMarkers() && !this.pathExists("members/NODE.md")) return false;
-		return this.progressPath() !== null || this.hasFramework() || this.hasAgentInstructionsMarkers() || this.pathExists("members/NODE.md") || this.frontmatter("NODE.md") !== null;
+		if (this.hasTreeContent()) return true;
+		if (this.hasFramework() && this.hasSourceWorkspaceIntegration()) return false;
+		if (this.hasFramework()) return !this.hasLikelySourceRepoSignals();
+		return false;
 	}
 	isLikelyEmptyRepo() {
 		return this.topLevelEntries().filter((entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry)).length === 0;
 	}
 	isLikelySourceRepo() {
 		if (this.looksLikeTreeRepo()) return false;
+		return this.hasLikelySourceRepoSignals();
+	}
+	hasLikelySourceRepoSignals() {
 		const entries = this.topLevelEntries().filter((entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry));
 		if (entries.length === 0) return false;
 		let directoryCount = 0;
@@ -315,4 +386,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 { LEGACY_SKILL_ROOT as C, SOURCE_INTEGRATION_MARKER as D, SOURCE_INTEGRATION_FILES as E, installedSkillRootsDisplay as O, LEGACY_SKILL_NAME as S, SKILL_ROOT as T, LEGACY_EXAMPLES_DIR as _, BUNDLED_SKILL_ROOT as a, LEGACY_REPO_SKILL_ROOT as b, CLAUDE_SKILL_ROOT as c, FRAMEWORK_TEMPLATES_DIR as d, FRAMEWORK_VERSION as f, LEGACY_AGENT_INSTRUCTIONS_FILE as g, INSTALLED_SKILL_ROOTS as h, AGENT_INSTRUCTIONS_TEMPLATE as i, FRAMEWORK_ASSET_ROOT as l, INSTALLED_PROGRESS as m, Repo as n, CLAUDE_FRAMEWORK_EXAMPLES_DIR as o, FRAMEWORK_WORKFLOWS_DIR as p, AGENT_INSTRUCTIONS_FILE as r, CLAUDE_INSTRUCTIONS_FILE as s, FRAMEWORK_END_MARKER as t, FRAMEWORK_EXAMPLES_DIR as u, LEGACY_FRAMEWORK_ROOT as v, SKILL_NAME as w, LEGACY_SKILL_EXAMPLES_DIR as x, LEGACY_REPO_SKILL_EXAMPLES_DIR as y };

package/dist/source-integration-CuKjoheT.js

@@ -0,0 +1,84 @@
+import { C as LEGACY_SKILL_ROOT, D as SOURCE_INTEGRATION_MARKER, E as SOURCE_INTEGRATION_FILES, a as BUNDLED_SKILL_ROOT, b as LEGACY_REPO_SKILL_ROOT, h as INSTALLED_SKILL_ROOTS } from "./repo-Cc5U4DWT.js";
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } 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, BUNDLED_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, 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);
+	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);
+	const dst = join(targetRoot, targetPath);
+	if (existsSync(dst) || !existsSync(src)) return false;
+	mkdirSync(dirname(dst), { recursive: true });
+	copyFileSync(src, dst);
+	return true;
+}
+//#endregion
+//#region skills/first-tree/engine/runtime/source-integration.ts
+function buildSourceIntegrationLine(treeRepoName) {
+	return `${SOURCE_INTEGRATION_MARKER} Use the installed \`first-tree\` skill here; keep all Context Tree files only in the sibling dedicated \`${treeRepoName}\` repo/submodule and update that tree when decisions or constraints change.`;
+}
+function upsertSourceIntegrationFiles(root, treeRepoName) {
+	return SOURCE_INTEGRATION_FILES.map((file) => upsertSourceIntegrationFile(root, file, treeRepoName));
+}
+function upsertSourceIntegrationFile(root, file, treeRepoName) {
+	const fullPath = join(root, file);
+	const exists = existsSync(fullPath);
+	const nextLine = buildSourceIntegrationLine(treeRepoName);
+	const normalized = (exists ? readFileSync(fullPath, "utf-8") : null)?.replaceAll("\r\n", "\n") ?? "";
+	const lines = normalized === "" ? [] : normalized.split("\n");
+	const markerIndex = lines.findIndex((line) => line.startsWith(SOURCE_INTEGRATION_MARKER));
+	if (markerIndex >= 0) {
+		if (lines[markerIndex] === nextLine) return {
+			action: "unchanged",
+			file
+		};
+		lines[markerIndex] = nextLine;
+	} else {
+		if (lines.length > 0 && lines.at(-1) !== "") lines.push("");
+		lines.push(nextLine);
+	}
+	let nextText = lines.join("\n");
+	if (nextText !== "" && !nextText.endsWith("\n")) nextText += "\n";
+	writeFileSync(fullPath, nextText);
+	return {
+		action: exists ? "updated" : "created",
+		file
+	};
+}
+//#endregion
+export { resolveCanonicalSkillRoot as a, resolveBundledPackageRoot as i, copyCanonicalSkill as n, renderTemplateFile as r, upsertSourceIntegrationFiles as t };