first-tree 0.0.6 → 0.0.7

package/README.md

@@ -53,6 +53,10 @@ git init
 context-tree init --here
 ```
 
+Only use `--here` after you have already switched into the dedicated tree repo.
+Do not use it inside the source/workspace repo unless you intentionally want
+that repo itself to become the Context Tree.
+
 - `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
@@ -84,7 +88,7 @@ runtime.
 
 | Command | What it does |
 | --- | --- |
-| `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 init` | Install source/workspace integration locally and create or refresh a dedicated context tree repo; use `--here` only when you are already inside the dedicated tree repo |
 | `context-tree verify` | Run verification checks against the current tree |
 | `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 |

package/dist/cli.js

@@ -18,9 +18,12 @@ Options:
 
 Common examples:
   context-tree init
-  context-tree init --here
+  mkdir my-org-context && cd my-org-context && git init && context-tree init --here
   context-tree verify --tree-path ../my-org-context
   context-tree upgrade --tree-path ../my-org-context
+
+Note:
+  \`--here\` is for when the current repo is already the dedicated tree repo.
 `;
 function isDirectExecution(argv1, metaUrl = import.meta.url) {
 	if (argv1 === void 0) return false;
@@ -44,18 +47,18 @@ async function runCli(args, output = console.log) {
 	const command = args[0];
 	switch (command) {
 		case "init": {
-			const { runInit } = await import("./init-BgGH2_yC.js");
+			const { runInit } = await import("./init-BSs0ILp_.js");
 			return runInit(args.slice(1));
 		}
 		case "verify": {
-			const { runVerify } = await import("./verify-G8gNXzDX.js");
+			const { runVerify } = await import("./verify-DRt5mCqO.js");
 			return runVerify(args.slice(1));
 		}
 		case "upgrade": {
-			const { runUpgrade } = await import("./upgrade-BvA9oKmi.js");
+			const { runUpgrade } = await import("./upgrade-DvBdbph3.js");
 			return runUpgrade(args.slice(1));
 		}
-		case "help": return (await import("./help-DV9-AaFp.js")).runHelp(args.slice(1), write);
+		case "help": return (await import("./help-BRO4mTG6.js")).runHelp(args.slice(1), write);
 		default:
 			write(`Unknown command: ${command}`);
 			write(USAGE);

package/dist/{help-DV9-AaFp.js → help-BRO4mTG6.js}

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

package/dist/{init-BgGH2_yC.js → init-BSs0ILp_.js}

@@ -1,6 +1,6 @@
-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 { T 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, w as SOURCE_INTEGRATION_MARKER, y as LEGACY_REPO_SKILL_EXAMPLES_DIR } from "./repo-0z7N9r17.js";
+import { n as onboarding_default } from "./onboarding-D3hnxIie.js";
+import { i as resolveBundledPackageRoot, n as copyCanonicalSkill, r as renderTemplateFile, t as upsertSourceIntegrationFiles } from "./source-integration-C2iiN4k_.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";
@@ -53,7 +53,6 @@ function claudeCodeExampleCandidates() {
 		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")
 	];
 }
@@ -210,8 +209,11 @@ 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\`.
 
+Do not use \`--here\` inside a source/workspace repo unless you explicitly want
+that repo itself to become the Context Tree.
+
 Options:
-  --here             Initialize the current repo in place
+  --here             Initialize the current repo in place after you are already in the dedicated tree repo
   --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
@@ -291,6 +293,10 @@ function runInit(repo, options) {
 		return 1;
 	}
 	const r = initTarget.repo;
+	if (options?.here && sourceRepo.isLikelySourceRepo() && !sourceRepo.looksLikeTreeRepo()) {
+		console.log(`Warning: \`context-tree init --here\` is initializing this source/workspace repo in place. This will create \`NODE.md\`, \`members/\`, and tree-scoped ${AGENT_INSTRUCTIONS_FILE} here. Use plain \`context-tree init\` to create a sibling dedicated tree repo instead.`);
+		console.log();
+	}
 	const taskListContext = initTarget.dedicatedTreeRepo ? {
 		dedicatedTreeRepo: true,
 		sourceRepoName: sourceRepo.repoName(),

package/dist/onboarding-BS8btkG4.js

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

package/dist/onboarding-D3hnxIie.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\nOnly use `--here` after you have already switched into the dedicated tree repo.\nDo not use it inside the source/workspace repo unless you intentionally want\nthat repo itself to become the Context Tree.\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` only when you are already inside the dedicated tree repo. |\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/` 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/{repo-Cc5U4DWT.js → repo-0z7N9r17.js}

@@ -46,15 +46,6 @@ 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");
-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");
-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");
 const LEGACY_PROGRESS = join(LEGACY_FRAMEWORK_ROOT, "progress.md");
@@ -81,7 +72,6 @@ function frameworkVersionCandidates() {
 		FRAMEWORK_VERSION,
 		CLAUDE_FRAMEWORK_VERSION,
 		LEGACY_REPO_SKILL_VERSION,
-		LEGACY_SKILL_VERSION,
 		LEGACY_VERSION
 	];
 }
@@ -90,7 +80,6 @@ function progressFileCandidates() {
 		INSTALLED_PROGRESS,
 		CLAUDE_INSTALLED_PROGRESS,
 		LEGACY_REPO_SKILL_PROGRESS,
-		LEGACY_SKILL_PROGRESS,
 		LEGACY_PROGRESS
 	];
 }
@@ -105,7 +94,6 @@ 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;
 }
@@ -261,7 +249,6 @@ var Repo = class {
 	preferredProgressPath() {
 		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;
@@ -269,7 +256,6 @@ var Repo = class {
 	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;
@@ -386,4 +372,4 @@ function isDirectory(root, relPath) {
 	}
 }
 //#endregion
-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 };
+export { SOURCE_INTEGRATION_FILES as C, SKILL_ROOT as S, installedSkillRootsDisplay 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, SOURCE_INTEGRATION_MARKER as w, SKILL_NAME as x, LEGACY_REPO_SKILL_EXAMPLES_DIR as y };

package/dist/{source-integration-CuKjoheT.js → source-integration-C2iiN4k_.js}

@@ -1,4 +1,4 @@
-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 { C as SOURCE_INTEGRATION_FILES, a as BUNDLED_SKILL_ROOT, b as LEGACY_REPO_SKILL_ROOT, h as INSTALLED_SKILL_ROOTS, w as SOURCE_INTEGRATION_MARKER } from "./repo-0z7N9r17.js";
 import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
@@ -22,11 +22,7 @@ function resolveCanonicalSkillRoot(sourceRoot) {
 }
 function copyCanonicalSkill(sourceRoot, targetRoot) {
 	const src = resolveCanonicalSkillRoot(sourceRoot);
-	for (const relPath of [
-		...INSTALLED_SKILL_ROOTS,
-		LEGACY_REPO_SKILL_ROOT,
-		LEGACY_SKILL_ROOT
-	]) {
+	for (const relPath of [...INSTALLED_SKILL_ROOTS, LEGACY_REPO_SKILL_ROOT]) {
 		const fullPath = join(targetRoot, relPath);
 		if (existsSync(fullPath)) rmSync(fullPath, {
 			recursive: true,

package/dist/{upgrade-BvA9oKmi.js → upgrade-DvBdbph3.js}

@@ -1,5 +1,5 @@
-import { C as LEGACY_SKILL_ROOT, D as SOURCE_INTEGRATION_MARKER, O as installedSkillRootsDisplay, T as SKILL_ROOT, b as LEGACY_REPO_SKILL_ROOT, c as CLAUDE_SKILL_ROOT, d as FRAMEWORK_TEMPLATES_DIR, f as FRAMEWORK_VERSION, g as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, m as INSTALLED_PROGRESS, n as Repo, p as FRAMEWORK_WORKFLOWS_DIR, r as AGENT_INSTRUCTIONS_FILE, s as CLAUDE_INSTRUCTIONS_FILE, v as LEGACY_FRAMEWORK_ROOT } from "./repo-Cc5U4DWT.js";
-import { a as resolveCanonicalSkillRoot, i as resolveBundledPackageRoot, n as copyCanonicalSkill, t as upsertSourceIntegrationFiles } from "./source-integration-CuKjoheT.js";
+import { S as SKILL_ROOT, T as installedSkillRootsDisplay, b as LEGACY_REPO_SKILL_ROOT, c as CLAUDE_SKILL_ROOT, d as FRAMEWORK_TEMPLATES_DIR, f as FRAMEWORK_VERSION, g as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, m as INSTALLED_PROGRESS, n as Repo, p as FRAMEWORK_WORKFLOWS_DIR, r as AGENT_INSTRUCTIONS_FILE, s as CLAUDE_INSTRUCTIONS_FILE, v as LEGACY_FRAMEWORK_ROOT, w as SOURCE_INTEGRATION_MARKER } from "./repo-0z7N9r17.js";
+import { a as resolveCanonicalSkillRoot, i as resolveBundledPackageRoot, n as copyCanonicalSkill, t as upsertSourceIntegrationFiles } from "./source-integration-C2iiN4k_.js";
 import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 //#region skills/first-tree/engine/runtime/upgrader.ts
@@ -46,7 +46,6 @@ function formatUpgradeTaskList(repo, localVersion, packagedVersion, layout) {
 	const migrationTasks = [];
 	if (layout === "legacy") migrationTasks.push("- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files");
 	if (layout === "legacy-repo-skill") lines.push("## Migration", `- [ ] Remove any stale \`${LEGACY_REPO_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`, "");
-	if (layout === "legacy-skill") migrationTasks.push(`- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`);
 	if (repo.hasCanonicalAgentInstructionsFile() && repo.hasLegacyAgentInstructionsFile()) migrationTasks.push(`- [ ] Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`);
 	else if (repo.hasLegacyAgentInstructionsFile()) migrationTasks.push(`- [ ] Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\` to use the canonical agent instructions filename`);
 	if (migrationTasks.length > 0) lines.push("## Migration", ...migrationTasks, "");
@@ -125,7 +124,6 @@ function runUpgrade(repo, options) {
 		});
 		console.log(`Migrated legacy .context-tree/ layout to ${installedSkillRootsDisplay()}.`);
 	} else if (layout === "legacy-repo-skill") console.log(`Migrated legacy ${LEGACY_REPO_SKILL_ROOT}/ layout to ${installedSkillRootsDisplay()}.`);
-	else if (layout === "legacy-skill") console.log(`Migrated ${LEGACY_SKILL_ROOT}/ to ${installedSkillRootsDisplay()}.`);
 	else if (missingInstalledRoots.length > 0) console.log(`Repaired missing installed skill roots (${missingInstalledRoots.map((root) => `${root}/`).join(", ")}) and refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`);
 	else console.log(`Refreshed ${installedSkillRootsDisplay()} from the bundled first-tree package.`);
 	const output = formatUpgradeTaskList(workingRepo, localVersion, packagedVersion, layout);

package/dist/{verify-G8gNXzDX.js → verify-DRt5mCqO.js}

@@ -1,4 +1,4 @@
-import { C as LEGACY_SKILL_ROOT, T as SKILL_ROOT, g as LEGACY_AGENT_INSTRUCTIONS_FILE, n as Repo, r as AGENT_INSTRUCTIONS_FILE } from "./repo-Cc5U4DWT.js";
+import { S as SKILL_ROOT, g as LEGACY_AGENT_INSTRUCTIONS_FILE, n as Repo, r as AGENT_INSTRUCTIONS_FILE, x as SKILL_NAME } from "./repo-0z7N9r17.js";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 //#region skills/first-tree/engine/validators/members.ts
@@ -186,14 +186,14 @@ function rel(path) {
 	return relative(treeRoot, path);
 }
 function isInstalledSkillPath(relPath) {
-	return relPath === SKILL_ROOT || relPath.startsWith(`${SKILL_ROOT}/`) || relPath === LEGACY_SKILL_ROOT || relPath.startsWith(`${LEGACY_SKILL_ROOT}/`);
+	return relPath === SKILL_ROOT || relPath.startsWith(`${SKILL_ROOT}/`);
 }
 function isFrameworkContainerDir(relPath, fullPath) {
 	if (relPath !== "skills") return false;
 	try {
 		const entries = readdirSync(fullPath).filter((entry) => !entry.startsWith("."));
 		if (entries.length === 0) return false;
-		return entries.every((entry) => entry === "first-tree" || entry === "first-tree-cli-framework");
+		return entries.every((entry) => entry === SKILL_NAME);
 	} catch {
 		return false;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "first-tree",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "CLI tools for Context Tree — the living source of truth for your organization.",
   "homepage": "https://github.com/agent-team-foundation/first-tree#readme",
   "bugs": {

package/skills/first-tree/SKILL.md

@@ -59,6 +59,10 @@ repos.
 
 ### Working In A User Tree Repo
 
+- When the task is to "install and use first-tree" in an existing
+  source/workspace repo, start with
+  `references/source-workspace-installation.md` and follow that workflow
+  end-to-end before improvising.
 - When a user asks to install first-tree for an existing source/workspace repo,
   the current repo keeps only the installed skill plus a
   `FIRST-TREE-SOURCE-INTEGRATION:` line in `AGENTS.md` and `CLAUDE.md`. Do not
@@ -68,6 +72,9 @@ repos.
   into the source/workspace repo and scaffolds tree files only in the
   dedicated tree repo. Use `--here` to initialize the current repo in place
   when you are already inside the tree repo.
+- Never run `context-tree init --here` in a source/workspace repo unless the
+  user explicitly wants that repo itself to become the dedicated Context Tree.
+  `--here` is for when you have already switched into the `*-context` repo.
 - `context-tree init` installs this skill into the target tree repo and
   scaffolds `.agents/skills/first-tree/`, `.claude/skills/first-tree/`,
   `NODE.md`, `AGENTS.md`, and `members/NODE.md`.
@@ -75,13 +82,16 @@ repos.
   prefer pushing it in the same GitHub organization as the source repo, add it
   back to the source/workspace repo as a git submodule, and open a PR to the
   source/workspace repo's default branch instead of merging automatically.
+- If permissions, auth, or local filesystem constraints block the dedicated
+  repo workflow, stop and report the blocker. Do not fall back to in-place tree
+  bootstrap in the source/workspace repo.
 - `context-tree upgrade` refreshes the installed skill from the copy bundled
   with the currently running `first-tree` package. In a source/workspace repo
   it refreshes only the local skill plus the
   `FIRST-TREE-SOURCE-INTEGRATION:` line; upgrade the dedicated tree repo
   separately with `--tree-path`. To pick up a newer framework, run a newer
   package version first. It also migrates older repos that still use
-  `skills/first-tree/` or `skills/first-tree-cli-framework/`.
+  `skills/first-tree/`.
 - The user's tree content lives outside the skill; the skill only carries the
   reusable framework payload plus maintenance guidance.
 - The tree still stores decisions, constraints, and ownership; execution detail

package/skills/first-tree/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "First Tree"
   short_description: "Maintain the First Tree skill and thin Context Tree CLI"
-  default_prompt: "Use $first-tree to maintain the canonical first-tree skill, its thin context-tree CLI, or its build, packaging, test, eval, and CI wiring. When a source/workspace repo installs first-tree, keep that repo limited to local skill integration plus the FIRST-TREE-SOURCE-INTEGRATION marker lines, and keep all NODE.md/tree content only in a dedicated sibling *-context repo."
+  default_prompt: "Use $first-tree to maintain the canonical first-tree skill, its thin context-tree CLI, or its build, packaging, test, eval, and CI wiring. When a source/workspace repo installs first-tree, read references/source-workspace-installation.md first, keep that repo limited to local skill integration plus the FIRST-TREE-SOURCE-INTEGRATION marker lines, and keep all NODE.md/tree content only in a dedicated sibling *-context repo. Never choose context-tree init --here in the source/workspace repo unless the user explicitly wants that repo itself to become the tree."

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

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

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

@@ -42,8 +42,11 @@ 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\`.
 
+Do not use \`--here\` inside a source/workspace repo unless you explicitly want
+that repo itself to become the Context Tree.
+
 Options:
-  --here             Initialize the current repo in place
+  --here             Initialize the current repo in place after you are already in the dedicated tree repo
   --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
@@ -202,6 +205,15 @@ export function runInit(repo?: Repo, options?: InitOptions): number {
     return 1;
   }
   const r = initTarget.repo;
+  if (options?.here && sourceRepo.isLikelySourceRepo() && !sourceRepo.looksLikeTreeRepo()) {
+    console.log(
+      "Warning: `context-tree init --here` is initializing this source/workspace" +
+        " repo in place. This will create `NODE.md`, `members/`, and tree-scoped" +
+        ` ${AGENT_INSTRUCTIONS_FILE} here. Use plain \`context-tree init\` to create` +
+        " a sibling dedicated tree repo instead.",
+    );
+    console.log();
+  }
   const taskListContext = initTarget.dedicatedTreeRepo
     ? {
         dedicatedTreeRepo: true,

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

@@ -10,8 +10,6 @@ import {
   LEGACY_PROGRESS,
   LEGACY_REPO_SKILL_PROGRESS,
   LEGACY_REPO_SKILL_VERSION,
-  LEGACY_SKILL_PROGRESS,
-  LEGACY_SKILL_VERSION,
   LEGACY_VERSION,
   agentInstructionsFileCandidates,
   installedSkillRoots,
@@ -220,9 +218,6 @@ export class Repo {
     if (layout === "legacy") {
       return LEGACY_PROGRESS;
     }
-    if (layout === "legacy-skill") {
-      return LEGACY_SKILL_PROGRESS;
-    }
     if (layout === "legacy-repo-skill") {
       return LEGACY_REPO_SKILL_PROGRESS;
     }
@@ -237,9 +232,6 @@ export class Repo {
     if (layout === "legacy") {
       return LEGACY_VERSION;
     }
-    if (layout === "legacy-skill") {
-      return LEGACY_SKILL_VERSION;
-    }
     if (layout === "legacy-repo-skill") {
       return LEGACY_REPO_SKILL_VERSION;
     }

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

@@ -4,7 +4,6 @@ import {
   CLAUDE_FRAMEWORK_HELPERS_DIR,
   FRAMEWORK_EXAMPLES_DIR,
   LEGACY_REPO_SKILL_EXAMPLES_DIR,
-  LEGACY_SKILL_EXAMPLES_DIR,
   LEGACY_EXAMPLES_DIR,
 } from "#skill/engine/runtime/asset-loader.js";
 
@@ -16,7 +15,6 @@ export function claudeCodeExampleCandidates(): string[] {
     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"),
   ];
 }

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

@@ -115,32 +115,6 @@ export const LEGACY_REPO_SKILL_PROGRESS = join(
   "progress.md",
 );
 
-export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
-export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
-export const LEGACY_SKILL_ASSET_ROOT = join(
-  LEGACY_SKILL_ROOT,
-  "assets",
-  "framework",
-);
-export const LEGACY_SKILL_VERSION = join(LEGACY_SKILL_ASSET_ROOT, "VERSION");
-export const LEGACY_SKILL_TEMPLATES_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "templates",
-);
-export const LEGACY_SKILL_WORKFLOWS_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "workflows",
-);
-export const LEGACY_SKILL_PROMPTS_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "prompts",
-);
-export const LEGACY_SKILL_EXAMPLES_DIR = join(
-  LEGACY_SKILL_ASSET_ROOT,
-  "examples",
-);
-export const LEGACY_SKILL_PROGRESS = join(LEGACY_SKILL_ROOT, "progress.md");
-
 export const LEGACY_FRAMEWORK_ROOT = ".context-tree";
 export const LEGACY_VERSION = join(LEGACY_FRAMEWORK_ROOT, "VERSION");
 export const LEGACY_PROGRESS = join(LEGACY_FRAMEWORK_ROOT, "progress.md");
@@ -153,7 +127,6 @@ export type FrameworkLayout =
   | "skill"
   | "claude-skill"
   | "legacy-repo-skill"
-  | "legacy-skill"
   | "legacy";
 
 function pathExists(root: string, relPath: string): boolean {
@@ -180,7 +153,6 @@ export function frameworkVersionCandidates(): string[] {
     FRAMEWORK_VERSION,
     CLAUDE_FRAMEWORK_VERSION,
     LEGACY_REPO_SKILL_VERSION,
-    LEGACY_SKILL_VERSION,
     LEGACY_VERSION,
   ];
 }
@@ -190,7 +162,6 @@ export function progressFileCandidates(): string[] {
     INSTALLED_PROGRESS,
     CLAUDE_INSTALLED_PROGRESS,
     LEGACY_REPO_SKILL_PROGRESS,
-    LEGACY_SKILL_PROGRESS,
     LEGACY_PROGRESS,
   ];
 }
@@ -204,7 +175,6 @@ export function frameworkTemplateDirCandidates(): string[] {
     FRAMEWORK_TEMPLATES_DIR,
     CLAUDE_FRAMEWORK_TEMPLATES_DIR,
     LEGACY_REPO_SKILL_TEMPLATES_DIR,
-    LEGACY_SKILL_TEMPLATES_DIR,
     LEGACY_TEMPLATES_DIR,
   ];
 }
@@ -214,7 +184,6 @@ export function frameworkWorkflowDirCandidates(): string[] {
     FRAMEWORK_WORKFLOWS_DIR,
     CLAUDE_FRAMEWORK_WORKFLOWS_DIR,
     LEGACY_REPO_SKILL_WORKFLOWS_DIR,
-    LEGACY_SKILL_WORKFLOWS_DIR,
     LEGACY_WORKFLOWS_DIR,
   ];
 }
@@ -224,7 +193,6 @@ export function frameworkPromptDirCandidates(): string[] {
     FRAMEWORK_PROMPTS_DIR,
     CLAUDE_FRAMEWORK_PROMPTS_DIR,
     LEGACY_REPO_SKILL_PROMPTS_DIR,
-    LEGACY_SKILL_PROMPTS_DIR,
     LEGACY_PROMPTS_DIR,
   ];
 }
@@ -234,7 +202,6 @@ export function frameworkExampleDirCandidates(): string[] {
     FRAMEWORK_EXAMPLES_DIR,
     CLAUDE_FRAMEWORK_EXAMPLES_DIR,
     LEGACY_REPO_SKILL_EXAMPLES_DIR,
-    LEGACY_SKILL_EXAMPLES_DIR,
     LEGACY_EXAMPLES_DIR,
   ];
 }
@@ -261,9 +228,6 @@ export function detectFrameworkLayout(root: string): FrameworkLayout | null {
   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";
   }

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

@@ -5,7 +5,6 @@ import {
   BUNDLED_SKILL_ROOT,
   INSTALLED_SKILL_ROOTS,
   LEGACY_REPO_SKILL_ROOT,
-  LEGACY_SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
 
 export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
@@ -57,7 +56,6 @@ export function copyCanonicalSkill(sourceRoot: string, targetRoot: string): void
   for (const relPath of [
     ...INSTALLED_SKILL_ROOTS,
     LEGACY_REPO_SKILL_ROOT,
-    LEGACY_SKILL_ROOT,
   ]) {
     const fullPath = join(targetRoot, relPath);
     if (existsSync(fullPath)) {

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

@@ -13,7 +13,6 @@ import {
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_FRAMEWORK_ROOT,
   LEGACY_REPO_SKILL_ROOT,
-  LEGACY_SKILL_ROOT,
   SKILL_ROOT,
   SOURCE_INTEGRATION_MARKER,
   installedSkillRootsDisplay,
@@ -73,12 +72,6 @@ function formatUpgradeTaskList(
     );
   }
 
-  if (layout === "legacy-skill") {
-    migrationTasks.push(
-      `- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
-    );
-  }
-
   if (repo.hasCanonicalAgentInstructionsFile() && repo.hasLegacyAgentInstructionsFile()) {
     migrationTasks.push(
       `- [ ] Merge any remaining user-authored content from \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` into \`${AGENT_INSTRUCTIONS_FILE}\`, then delete the legacy file`,
@@ -269,10 +262,6 @@ export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
     console.log(
       `Migrated legacy ${LEGACY_REPO_SKILL_ROOT}/ layout to ${installedSkillRootsDisplay()}.`,
     );
-  } else if (layout === "legacy-skill") {
-    console.log(
-      `Migrated ${LEGACY_SKILL_ROOT}/ to ${installedSkillRootsDisplay()}.`,
-    );
   } else {
     if (missingInstalledRoots.length > 0) {
       console.log(

package/skills/first-tree/engine/validators/nodes.ts

@@ -3,8 +3,6 @@ import { join, relative, posix } from "node:path";
 import {
   AGENT_INSTRUCTIONS_FILE,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
-  LEGACY_SKILL_NAME,
-  LEGACY_SKILL_ROOT,
   SKILL_NAME,
   SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -88,12 +86,7 @@ function rel(path: string): string {
 }
 
 function isInstalledSkillPath(relPath: string): boolean {
-  return (
-    relPath === SKILL_ROOT ||
-    relPath.startsWith(`${SKILL_ROOT}/`) ||
-    relPath === LEGACY_SKILL_ROOT ||
-    relPath.startsWith(`${LEGACY_SKILL_ROOT}/`)
-  );
+  return relPath === SKILL_ROOT || relPath.startsWith(`${SKILL_ROOT}/`);
 }
 
 function isFrameworkContainerDir(relPath: string, fullPath: string): boolean {
@@ -106,9 +99,7 @@ function isFrameworkContainerDir(relPath: string, fullPath: string): boolean {
     if (entries.length === 0) {
       return false;
     }
-    return entries.every(
-      (entry) => entry === SKILL_NAME || entry === LEGACY_SKILL_NAME,
-    );
+    return entries.every((entry) => entry === SKILL_NAME);
   } catch {
     return false;
   }

package/skills/first-tree/references/onboarding.md

@@ -84,6 +84,10 @@ git init
 context-tree init --here
 ```
 
+Only use `--here` after you have already switched into the dedicated tree repo.
+Do not use it inside the source/workspace repo unless you intentionally want
+that repo itself to become the Context Tree.
+
 Either way, the framework installs into `.agents/skills/first-tree/` and
 `.claude/skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENTS.md`,
 `members/NODE.md`), and generates a task list in
@@ -177,7 +181,7 @@ The tree doesn't duplicate source code — it captures what connects things and
 
 | Command | Description |
 |---------|-------------|
-| `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. |
+| `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` only when you are already inside the dedicated tree repo. |
 | `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. Use `--tree-path` when invoking from another working directory. |
 | `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. |
 | `context-tree help onboarding` | Print this onboarding guide. |
@@ -202,8 +206,7 @@ only the local installed skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines.
 Run `context-tree upgrade --tree-path ../my-org-context` to upgrade the
 dedicated tree repo itself.
 
-If your repo still uses the older `skills/first-tree/`,
-`skills/first-tree-cli-framework/`, or `.context-tree/` layouts,
+If your repo still uses the older `skills/first-tree/` or `.context-tree/` layouts,
 `context-tree upgrade` will migrate it to the current installed layout first.
 
 To pick up a newer framework release, first run a newer package version, for

package/skills/first-tree/references/source-workspace-installation.md

@@ -21,6 +21,18 @@ existing source or workspace repository.
   the dedicated tree repo rather than copying that material into the source
   repo.
 
+## Agent Decision Rule
+
+- Treat "install and use first-tree" in a source/workspace repo as a two-repo
+  workflow: local integration in the current repo plus tree bootstrap in a
+  sibling `*-context` repo.
+- Do not run `context-tree init --here` in the source/workspace repo unless the
+  user explicitly says that repo itself should become the Context Tree.
+- If you cannot create the sibling repo locally, cannot push it to GitHub, or
+  cannot add the submodule yet, pause and report the blocker. Do not fall back
+  to creating `NODE.md`, `members/`, or tree-scoped `AGENTS.md` in the
+  source/workspace repo.
+
 ## Default Agent Workflow
 
 When an agent is asked to install first-tree for a source/workspace repo, the

package/skills/first-tree/references/upgrade-contract.md

@@ -1,8 +1,7 @@
 # Upgrade Contract
 
 This file describes the current installed-layout contract and the compatibility
-rules we keep for legacy `skills/first-tree/`,
-`skills/first-tree-cli-framework/`, and `.context-tree/` repos.
+rules we keep for legacy `skills/first-tree/` and `.context-tree/` repos.
 
 ## Canonical Source
 
@@ -92,9 +91,6 @@ skill discovery and hooks.
     skill plus the `FIRST-TREE-SOURCE-INTEGRATION:` lines
   - migrates repos that still use the previous `skills/first-tree/` path onto
     `.agents/skills/first-tree/` and `.claude/skills/first-tree/`
-  - migrates repos that still use the previous
-    `skills/first-tree-cli-framework/` path onto `.agents/skills/first-tree/`
-    and `.claude/skills/first-tree/`
   - migrates legacy `.context-tree/` repos onto the installed skill layout
   - preserves user-authored sections such as the editable part of `AGENTS.md`
 
@@ -111,9 +107,9 @@ skill discovery and hooks.
 - Normal `context-tree init` and `context-tree upgrade` flows do not clone the
   source repo or require network access.
 - `context-tree verify` may still read a legacy
-  `.claude/skills/first-tree/...`, `skills/first-tree/...`,
-  `skills/first-tree-cli-framework/...`, or `.context-tree/...` layout in an
-  existing user repo so the repo can be repaired or upgraded in place.
+  `.claude/skills/first-tree/...`, `skills/first-tree/...`, or
+  `.context-tree/...` layout in an existing user repo so the repo can be
+  repaired or upgraded in place.
 - `context-tree upgrade` must migrate either legacy layout onto
   `.agents/skills/first-tree/` and `.claude/skills/first-tree/`, and remove
   old skill directories afterward.

package/skills/first-tree/scripts/check-skill-sync.sh

@@ -91,7 +91,6 @@ for legacy_path in \
   ".claude" \
   ".context-tree" \
   "docs" \
-  "skills/first-tree-cli-framework" \
   "tests" \
   "skills/first-tree/references/repo-snapshot"
 do

package/skills/first-tree/tests/asset-loader.test.ts

@@ -7,8 +7,6 @@ import {
   INSTALLED_PROGRESS,
   LEGACY_REPO_SKILL_PROGRESS,
   LEGACY_REPO_SKILL_VERSION,
-  LEGACY_SKILL_PROGRESS,
-  LEGACY_SKILL_VERSION,
   LEGACY_PROGRESS,
   LEGACY_VERSION,
   detectFrameworkLayout,
@@ -57,37 +55,15 @@ describe("asset-loader", () => {
     ).toBe(LEGACY_REPO_SKILL_VERSION);
   });
 
-  it("detects the previous installed skill name before the .context-tree layout", () => {
-    const tmp = useTmpDir();
-    mkdirSync(
-      join(tmp.path, "skills", "first-tree-cli-framework", "assets", "framework"),
-      {
-        recursive: true,
-      },
-    );
-    mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
-    writeFileSync(join(tmp.path, LEGACY_SKILL_VERSION), "0.2.0\n");
-    writeFileSync(join(tmp.path, LEGACY_VERSION), "0.1.0\n");
-
-    expect(detectFrameworkLayout(tmp.path)).toBe("legacy-skill");
-    expect(
-      resolveFirstExistingPath(tmp.path, frameworkVersionCandidates()),
-    ).toBe(LEGACY_SKILL_VERSION);
-  });
-
   it("prefers the installed progress file candidate", () => {
     const tmp = useTmpDir();
     mkdirSync(join(tmp.path, ".agents", "skills", "first-tree"), { recursive: true });
     mkdirSync(join(tmp.path, ".claude", "skills", "first-tree"), { recursive: true });
     mkdirSync(join(tmp.path, "skills", "first-tree"), { recursive: true });
-    mkdirSync(join(tmp.path, "skills", "first-tree-cli-framework"), {
-      recursive: true,
-    });
     mkdirSync(join(tmp.path, ".context-tree"), { recursive: true });
     writeFileSync(join(tmp.path, INSTALLED_PROGRESS), "new");
     writeFileSync(join(tmp.path, CLAUDE_INSTALLED_PROGRESS), "claude");
     writeFileSync(join(tmp.path, LEGACY_REPO_SKILL_PROGRESS), "old-repo-skill");
-    writeFileSync(join(tmp.path, LEGACY_SKILL_PROGRESS), "old-skill");
     writeFileSync(join(tmp.path, LEGACY_PROGRESS), "old");
 
     expect(resolveFirstExistingPath(tmp.path, progressFileCandidates())).toBe(

package/skills/first-tree/tests/helpers.ts

@@ -9,7 +9,6 @@ import {
   FRAMEWORK_VERSION,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_REPO_SKILL_VERSION,
-  LEGACY_SKILL_VERSION,
   LEGACY_VERSION,
   SKILL_ROOT,
 } from "#skill/engine/runtime/asset-loader.js";
@@ -74,19 +73,6 @@ export function makeLegacyRepoFramework(root: string, version = "0.1.0"): void {
   writeFileSync(join(root, LEGACY_REPO_SKILL_VERSION), `${version}\n`);
 }
 
-export function makeLegacyNamedFramework(
-  root: string,
-  version = "0.1.0",
-): void {
-  mkdirSync(
-    join(root, "skills", "first-tree-cli-framework", "assets", "framework"),
-    {
-      recursive: true,
-    },
-  );
-  writeFileSync(join(root, LEGACY_SKILL_VERSION), `${version}\n`);
-}
-
 export function makeSourceSkill(root: string, version = "0.2.0"): void {
   const skillRoot = join(root, "skills", "first-tree");
   mkdirSync(join(skillRoot, "agents"), { recursive: true });

package/skills/first-tree/tests/init.test.ts

@@ -3,6 +3,7 @@ import { basename, dirname, join } from "node:path";
 import { describe, expect, it } from "vitest";
 import {
   formatTaskList,
+  INIT_USAGE,
   parseInitArgs,
   writeProgress,
   runInit,
@@ -302,6 +303,11 @@ describe("runInit", () => {
 });
 
 describe("parseInitArgs", () => {
+  it("documents that --here is only for dedicated tree repos", () => {
+    expect(INIT_USAGE).toContain("Do not use `--here` inside a source/workspace repo");
+    expect(INIT_USAGE).toContain("already in the dedicated tree repo");
+  });
+
   it("parses dedicated repo options", () => {
     expect(parseInitArgs(["--tree-name", "acme-context"])).toEqual({
       treeName: "acme-context",

package/skills/first-tree/tests/repo.test.ts

@@ -11,8 +11,6 @@ import {
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_REPO_SKILL_PROGRESS,
   LEGACY_REPO_SKILL_VERSION,
-  LEGACY_SKILL_PROGRESS,
-  LEGACY_SKILL_VERSION,
   LEGACY_PROGRESS,
   LEGACY_VERSION,
   SOURCE_INTEGRATION_MARKER,
@@ -23,7 +21,6 @@ import {
   makeGitRepo,
   makeLegacyFramework,
   makeLegacyRepoFramework,
-  makeLegacyNamedFramework,
   makeSourceRepo,
   makeSourceSkill,
 } from "./helpers.js";
@@ -181,13 +178,6 @@ describe("hasFramework", () => {
     expect(repo.hasFramework()).toBe(true);
   });
 
-  it("returns true with the previous installed skill name", () => {
-    const tmp = useTmpDir();
-    makeLegacyNamedFramework(tmp.path);
-    const repo = new Repo(tmp.path);
-    expect(repo.hasFramework()).toBe(true);
-  });
-
   it("returns true with the previous workspace skill path", () => {
     const tmp = useTmpDir();
     makeLegacyRepoFramework(tmp.path);
@@ -219,13 +209,6 @@ describe("readVersion", () => {
     expect(repo.readVersion()).toBe("0.3.0");
   });
 
-  it("reads the previous installed skill version", () => {
-    const tmp = useTmpDir();
-    makeLegacyNamedFramework(tmp.path, "0.2.5");
-    const repo = new Repo(tmp.path);
-    expect(repo.readVersion()).toBe("0.2.5");
-  });
-
   it("reads the previous workspace skill version", () => {
     const tmp = useTmpDir();
     makeLegacyRepoFramework(tmp.path, "0.2.4");
@@ -258,14 +241,6 @@ describe("path preferences", () => {
     expect(repo.frameworkVersionPath()).toBe(LEGACY_VERSION);
   });
 
-  it("switches path preferences for repos using the previous skill name", () => {
-    const tmp = useTmpDir();
-    makeLegacyNamedFramework(tmp.path);
-    const repo = new Repo(tmp.path);
-    expect(repo.preferredProgressPath()).toBe(LEGACY_SKILL_PROGRESS);
-    expect(repo.frameworkVersionPath()).toBe(LEGACY_SKILL_VERSION);
-  });
-
   it("switches path preferences for repos using the previous workspace skill path", () => {
     const tmp = useTmpDir();
     makeLegacyRepoFramework(tmp.path);

package/skills/first-tree/tests/skill-artifacts.test.ts

@@ -139,7 +139,6 @@ describe("skill artifacts", () => {
     expect(isTrackedInGit(".claude")).toBe(false);
     expect(isTrackedInGit(".context-tree")).toBe(false);
     expect(existsSync(join(ROOT, "AGENT.md"))).toBe(false);
-    expect(isTrackedInGit("skills/first-tree-cli-framework")).toBe(false);
     expect(isTrackedInGit("docs")).toBe(false);
     expect(isTrackedInGit("tests")).toBe(false);
     expect(existsSync(join(ROOT, "evals"))).toBe(true);
@@ -231,6 +230,7 @@ describe("skill artifacts", () => {
     expect(read("README.md")).toContain("dedicated tree repo");
     expect(read("README.md")).toContain("FIRST-TREE-SOURCE-INTEGRATION:");
     expect(read("README.md")).toContain("`first-tree` skill");
+    expect(read("README.md")).toContain("Only use `--here` after you have already switched into the dedicated tree repo.");
     expect(read("AGENTS.md")).toContain("references/source-map.md");
     expect(read("AGENTS.md")).toContain("source-workspace-installation.md");
     expect(read("AGENTS.md")).toContain("bundled skill path");
@@ -251,6 +251,7 @@ describe("skill artifacts", () => {
     expect(onboarding).toContain("FIRST-TREE-SOURCE-INTEGRATION:");
     expect(onboarding).toContain("source/workspace repo");
     expect(onboarding).toContain("git submodule");
+    expect(onboarding).toContain("Only use `--here` after you have already switched into the dedicated tree repo.");
     expect(onboarding).not.toContain("This clones the framework into `.context-tree/`");
     expect(onboarding).not.toContain("from upstream");
 
@@ -265,6 +266,7 @@ describe("skill artifacts", () => {
     expect(skillMd).toContain(".claude/skills/first-tree/");
     expect(skillMd).toContain("source-workspace-installation.md");
     expect(skillMd).toContain("FIRST-TREE-SOURCE-INTEGRATION:");
+    expect(skillMd).toContain("Never run `context-tree init --here` in a source/workspace repo");
     expect(skillMd).not.toContain("canonical eval harness");
 
     const sourceMap = read("skills/first-tree/references/source-map.md");
@@ -290,6 +292,7 @@ describe("skill artifacts", () => {
     expect(sourceWorkspaceInstall).toContain("FIRST-TREE-SOURCE-INTEGRATION:");
     expect(sourceWorkspaceInstall).toContain("git submodule");
     expect(sourceWorkspaceInstall).toContain("Do not run `context-tree verify`");
+    expect(sourceWorkspaceInstall).toContain("Do not run `context-tree init --here` in the source/workspace repo");
 
     const maintainerArchitecture = read(
       "skills/first-tree/references/maintainer-architecture.md",

package/skills/first-tree/tests/thin-cli.test.ts

@@ -39,6 +39,11 @@ afterEach(() => {
 });
 
 describe("thin CLI shell", () => {
+  it("documents the dedicated-repo meaning of --here", () => {
+    expect(USAGE).toContain("git init && context-tree init --here");
+    expect(USAGE).toContain("`--here` is for when the current repo is already the dedicated tree repo.");
+  });
+
   it("treats a symlinked npm bin path as direct execution", () => {
     const dir = makeTempDir();
     const target = join(dir, "cli.js");

package/skills/first-tree/tests/upgrade.test.ts

@@ -18,7 +18,6 @@ import {
   makeSourceRepo,
   makeLegacyFramework,
   makeLegacyRepoFramework,
-  makeLegacyNamedFramework,
   makeSourceSkill,
   useTmpDir,
 } from "./helpers.js";
@@ -63,26 +62,6 @@ describe("runUpgrade", () => {
     expect(existsSync(join(repoDir.path, INSTALLED_PROGRESS))).toBe(false);
   });
 
-  it("migrates repos that still use the previous installed skill name", () => {
-    const repoDir = useTmpDir();
-    const sourceDir = useTmpDir();
-    makeLegacyNamedFramework(repoDir.path, "0.2.0");
-    makeSourceSkill(sourceDir.path, "0.2.0");
-
-    const result = runUpgrade(new Repo(repoDir.path), {
-      sourceRoot: sourceDir.path,
-    });
-
-    expect(result).toBe(0);
-    expect(existsSync(join(repoDir.path, "skills", "first-tree-cli-framework"))).toBe(
-      false,
-    );
-    expect(readFileSync(join(repoDir.path, FRAMEWORK_VERSION), "utf-8").trim()).toBe("0.2.0");
-    expect(readFileSync(join(repoDir.path, INSTALLED_PROGRESS), "utf-8")).toContain(
-      "skills/first-tree-cli-framework/",
-    );
-  });
-
   it("migrates repos that still use the previous workspace skill path", () => {
     const repoDir = useTmpDir();
     const sourceDir = useTmpDir();

package/dist/onboarding-D7fGGOMN.js

@@ -1,10 +0,0 @@
-//#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

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