first-tree 0.0.5 → 0.0.7

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,
@@ -10,11 +11,13 @@ import {
 import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_INSTRUCTIONS_FILE,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   LEGACY_PROGRESS,
 } from "#skill/engine/runtime/asset-loader.js";
+import { buildSourceIntegrationLine } from "#skill/engine/runtime/source-integration.js";
 import {
   makeGitRepo,
   useTmpDir,
@@ -124,6 +127,10 @@ const fakeGitInitializer = (root: string): void => {
   makeGitRepo(root);
 };
 
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 describe("runInit", () => {
   it("errors when not a git repo", () => {
     const tmp = useTmpDir();
@@ -205,6 +212,18 @@ describe("runInit", () => {
     );
 
     expect(ret).toBe(0);
+    expect(
+      existsSync(join(sourceRepoDir.path, ".agents", "skills", "first-tree", "SKILL.md")),
+    ).toBe(true);
+    expect(
+      existsSync(join(sourceRepoDir.path, ".claude", "skills", "first-tree", "SKILL.md")),
+    ).toBe(true);
+    expect(
+      readFileSync(join(sourceRepoDir.path, AGENT_INSTRUCTIONS_FILE), "utf-8"),
+    ).toContain(buildSourceIntegrationLine(basename(treeRepo)));
+    expect(
+      readFileSync(join(sourceRepoDir.path, CLAUDE_INSTRUCTIONS_FILE), "utf-8"),
+    ).toContain(buildSourceIntegrationLine(basename(treeRepo)));
     expect(
       existsSync(join(treeRepo, ".agents", "skills", "first-tree", "SKILL.md")),
     ).toBe(true);
@@ -220,6 +239,49 @@ describe("runInit", () => {
     expect(existsSync(join(sourceRepoDir.path, INSTALLED_PROGRESS))).toBe(false);
   });
 
+  it("updates existing AGENTS.md and CLAUDE.md without duplicating the source integration line", () => {
+    const sourceRepoDir = useTmpDir();
+    const sourceSkillDir = useTmpDir();
+    makeSourceRepo(sourceRepoDir.path);
+    makeSourceSkill(sourceSkillDir.path, "0.2.0");
+    writeFileSync(join(sourceRepoDir.path, AGENT_INSTRUCTIONS_FILE), "# Repo Notes\n");
+    writeFileSync(join(sourceRepoDir.path, CLAUDE_INSTRUCTIONS_FILE), "# Claude Notes\n");
+
+    expect(
+      runInit(new Repo(sourceRepoDir.path), {
+        sourceRoot: sourceSkillDir.path,
+        gitInitializer: fakeGitInitializer,
+      }),
+    ).toBe(0);
+    expect(
+      runInit(new Repo(sourceRepoDir.path), {
+        sourceRoot: sourceSkillDir.path,
+        gitInitializer: fakeGitInitializer,
+      }),
+    ).toBe(0);
+
+    const treeRepo = join(
+      dirname(sourceRepoDir.path),
+      `${basename(sourceRepoDir.path)}-context`,
+    );
+    const expectedLine = buildSourceIntegrationLine(basename(treeRepo));
+    const agentText = readFileSync(
+      join(sourceRepoDir.path, AGENT_INSTRUCTIONS_FILE),
+      "utf-8",
+    );
+    const claudeText = readFileSync(
+      join(sourceRepoDir.path, CLAUDE_INSTRUCTIONS_FILE),
+      "utf-8",
+    );
+
+    expect(
+      agentText.match(new RegExp(escapeRegExp(expectedLine), "g")),
+    ).toHaveLength(1);
+    expect(
+      claudeText.match(new RegExp(escapeRegExp(expectedLine), "g")),
+    ).toHaveLength(1);
+  });
+
   it("keeps supporting in-place init with --here", () => {
     const sourceRepoDir = useTmpDir();
     const sourceSkillDir = useTmpDir();
@@ -241,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

@@ -5,15 +5,15 @@ import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
   CLAUDE_INSTALLED_PROGRESS,
+  CLAUDE_INSTRUCTIONS_FILE,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   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,
 } from "#skill/engine/runtime/asset-loader.js";
 import {
   useTmpDir,
@@ -21,7 +21,6 @@ import {
   makeGitRepo,
   makeLegacyFramework,
   makeLegacyRepoFramework,
-  makeLegacyNamedFramework,
   makeSourceRepo,
   makeSourceSkill,
 } from "./helpers.js";
@@ -179,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);
@@ -217,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");
@@ -256,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);
@@ -454,6 +431,24 @@ describe("init heuristics", () => {
     expect(repo.isLikelySourceRepo()).toBe(false);
   });
 
+  it("treats a source repo with installed skill and integration markers as a source repo", () => {
+    const tmp = useTmpDir();
+    makeSourceRepo(tmp.path);
+    makeFramework(tmp.path);
+    writeFileSync(
+      join(tmp.path, AGENT_INSTRUCTIONS_FILE),
+      `${SOURCE_INTEGRATION_MARKER} Use the installed \`first-tree\` skill here.\n`,
+    );
+    writeFileSync(
+      join(tmp.path, CLAUDE_INSTRUCTIONS_FILE),
+      `${SOURCE_INTEGRATION_MARKER} Use the installed \`first-tree\` skill here.\n`,
+    );
+    const repo = new Repo(tmp.path);
+    expect(repo.hasSourceWorkspaceIntegration()).toBe(true);
+    expect(repo.looksLikeTreeRepo()).toBe(false);
+    expect(repo.isLikelySourceRepo()).toBe(true);
+  });
+
   it("does not mistake the framework source repo for a user tree repo", () => {
     const tmp = useTmpDir();
     makeSourceRepo(tmp.path);

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

@@ -20,6 +20,17 @@ describe("skill artifacts", () => {
   it("keeps only the canonical skill in the source repo", () => {
     expect(existsSync(join(ROOT, "skills", "first-tree", "SKILL.md"))).toBe(true);
     expect(existsSync(join(ROOT, "skills", "first-tree", "references", "onboarding.md"))).toBe(true);
+    expect(
+      existsSync(
+        join(
+          ROOT,
+          "skills",
+          "first-tree",
+          "references",
+          "source-workspace-installation.md",
+        ),
+      ),
+    ).toBe(true);
     expect(existsSync(join(ROOT, "skills", "first-tree", "assets", "framework", "manifest.json"))).toBe(true);
     expect(existsSync(join(ROOT, "skills", "first-tree", "engine", "init.ts"))).toBe(true);
     expect(existsSync(join(ROOT, "AGENTS.md"))).toBe(true);
@@ -43,6 +54,18 @@ describe("skill artifacts", () => {
         ),
       ),
     ).toBe(true);
+    expect(
+      existsSync(
+        join(
+          ROOT,
+          "skills",
+          "first-tree",
+          "engine",
+          "runtime",
+          "source-integration.ts",
+        ),
+      ),
+    ).toBe(true);
     expect(
       existsSync(
         join(
@@ -116,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);
@@ -200,13 +222,17 @@ describe("skill artifacts", () => {
     expect(read("README.md")).toContain("Package Name vs Command");
     expect(read("README.md")).toContain("Canonical Documentation");
     expect(read("README.md")).toContain("references/source-map.md");
+    expect(read("README.md")).toContain("source-workspace-installation.md");
     expect(read("README.md")).toContain("skills/first-tree/");
     expect(read("README.md")).toContain(".agents/skills/first-tree/");
     expect(read("README.md")).toContain(".claude/skills/first-tree/");
     expect(read("README.md")).toContain("bundled canonical");
     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");
     expect(read("AGENTS.md")).not.toContain("### Running evals");
     expect(read("AGENTS.md")).not.toContain("EVALS_TREE_REPO");
@@ -222,6 +248,10 @@ describe("skill artifacts", () => {
     expect(onboarding).toContain("npx first-tree@latest upgrade");
     expect(onboarding).toContain(".agents/skills/first-tree/");
     expect(onboarding).toContain(".claude/skills/first-tree/");
+    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");
 
@@ -234,11 +264,15 @@ describe("skill artifacts", () => {
     expect(skillMd).toContain("so it is not confused with the `first-tree`");
     expect(skillMd).toContain(".agents/skills/first-tree/");
     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");
     expect(sourceMap).not.toContain("repo-snapshot");
     expect(sourceMap).not.toContain("sync-skill-artifacts.sh");
+    expect(sourceMap).toContain("source-workspace-installation.md");
     expect(sourceMap).toContain("maintainer-architecture.md");
     expect(sourceMap).toContain("maintainer-thin-cli.md");
     expect(sourceMap).toContain("maintainer-build-and-distribution.md");
@@ -252,6 +286,14 @@ describe("skill artifacts", () => {
     expect(sourceMap).not.toContain("vitest.eval.config.ts");
     expect(sourceMap).toContain(".github/workflows/ci.yml");
 
+    const sourceWorkspaceInstall = read(
+      "skills/first-tree/references/source-workspace-installation.md",
+    );
+    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

@@ -1,21 +1,23 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { Repo } from "#skill/engine/repo.js";
 import { runUpgrade } from "#skill/engine/upgrade.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_INSTRUCTIONS_FILE,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
+  SOURCE_INTEGRATION_MARKER,
 } from "#skill/engine/runtime/asset-loader.js";
+import { buildSourceIntegrationLine } from "#skill/engine/runtime/source-integration.js";
 import {
   makeAgentsMd,
   makeFramework,
   makeSourceRepo,
   makeLegacyFramework,
   makeLegacyRepoFramework,
-  makeLegacyNamedFramework,
   makeSourceSkill,
   useTmpDir,
 } from "./helpers.js";
@@ -60,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();
@@ -119,4 +101,37 @@ describe("runUpgrade", () => {
     const result = runUpgrade(new Repo(repoDir.path));
     expect(result).toBe(1);
   });
+
+  it("refreshes source/workspace integration without writing tree progress", () => {
+    const repoDir = useTmpDir();
+    const sourceDir = useTmpDir();
+    makeSourceRepo(repoDir.path);
+    makeFramework(repoDir.path, "0.1.0");
+    writeFileSync(
+      join(repoDir.path, AGENT_INSTRUCTIONS_FILE),
+      `${SOURCE_INTEGRATION_MARKER} old text\n`,
+    );
+    writeFileSync(
+      join(repoDir.path, CLAUDE_INSTRUCTIONS_FILE),
+      `${SOURCE_INTEGRATION_MARKER} old text\n`,
+    );
+    makeSourceSkill(sourceDir.path, "0.2.0");
+
+    const result = runUpgrade(new Repo(repoDir.path), {
+      sourceRoot: sourceDir.path,
+    });
+
+    const expectedLine = buildSourceIntegrationLine(
+      `${basename(repoDir.path)}-context`,
+    );
+    expect(result).toBe(0);
+    expect(readFileSync(join(repoDir.path, FRAMEWORK_VERSION), "utf-8").trim()).toBe("0.2.0");
+    expect(readFileSync(join(repoDir.path, AGENT_INSTRUCTIONS_FILE), "utf-8")).toContain(
+      expectedLine,
+    );
+    expect(readFileSync(join(repoDir.path, CLAUDE_INSTRUCTIONS_FILE), "utf-8")).toContain(
+      expectedLine,
+    );
+    expect(existsSync(join(repoDir.path, INSTALLED_PROGRESS))).toBe(false);
+  });
 });

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

@@ -6,8 +6,10 @@ import { check, checkProgress, runVerify } from "#skill/engine/verify.js";
 import { Repo } from "#skill/engine/repo.js";
 import {
   AGENT_INSTRUCTIONS_FILE,
+  CLAUDE_INSTRUCTIONS_FILE,
   INSTALLED_PROGRESS,
   LEGACY_PROGRESS,
+  SOURCE_INTEGRATION_MARKER,
 } from "#skill/engine/runtime/asset-loader.js";
 import {
   useTmpDir,
@@ -238,4 +240,20 @@ describe("runVerify failing", () => {
     const ret = runVerify(repo, passValidator);
     expect(ret).toBe(1);
   });
+
+  it("refuses to verify a source/workspace repo that only has local first-tree integration", () => {
+    const tmp = useTmpDir();
+    makeSourceRepo(tmp.path);
+    makeFramework(tmp.path);
+    writeFileSync(
+      join(tmp.path, AGENT_INSTRUCTIONS_FILE),
+      `${SOURCE_INTEGRATION_MARKER} Use the installed \`first-tree\` skill here.\n`,
+    );
+    writeFileSync(
+      join(tmp.path, CLAUDE_INSTRUCTIONS_FILE),
+      `${SOURCE_INTEGRATION_MARKER} Use the installed \`first-tree\` skill here.\n`,
+    );
+    const repo = new Repo(tmp.path);
+    expect(runVerify(repo, passValidator)).toBe(1);
+  });
 });

package/dist/installer-UgNasLjl.js

@@ -1,51 +0,0 @@
-import { S as LEGACY_SKILL_ROOT, a as BUNDLED_SKILL_ROOT, m as INSTALLED_SKILL_ROOTS, y as LEGACY_REPO_SKILL_ROOT } from "./repo-DkR12VUv.js";
-import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, join } from "node:path";
-//#region skills/first-tree/engine/runtime/installer.ts
-function resolveBundledPackageRoot(startUrl = import.meta.url) {
-	let dir = dirname(fileURLToPath(startUrl));
-	while (true) {
-		if (existsSync(join(dir, "package.json")) && existsSync(join(dir, 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
-export { resolveCanonicalSkillRoot as i, renderTemplateFile as n, resolveBundledPackageRoot as r, copyCanonicalSkill as t };

package/dist/onboarding-3zYUeYQb.js

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

package/dist/onboarding-Dd63N-V1.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 create a sibling dedicated tree repo named `<repo>-context` by\ndefault and install the framework there.\n\n```bash\ncd my-org\ncontext-tree init\ncd ../my-org-context\n```\n\nIf you already created a dedicated tree repo manually, initialize it in place:\n\n```bash\nmkdir my-org-context && cd my-org-context\ngit init\ncontext-tree init --here\n```\n\nEither way, the framework installs into `.agents/skills/first-tree/` and\n`.claude/skills/first-tree/`, renders scaffolding (`NODE.md`, `AGENTS.md`,\n`members/NODE.md`), and generates a task list in\n`.agents/skills/first-tree/progress.md`.\n\nPublishing tip: keep the tree repo in the same GitHub organization as the\nsource repo unless you have a reason not to.\n\n### Step 2: Work Through the Task List\n\nRead `.agents/skills/first-tree/progress.md`. It contains a checklist tailored\nto the current state of the repo. Complete each task:\n\n- Fill in `NODE.md` with your organization name, owners, and domains\n- Add project-specific instructions to `AGENTS.md` below the framework markers\n- Create member nodes under `members/`\n- Optionally configure agent integration (for Claude Code, the installed hook\n  assets live under `.claude/skills/first-tree/`)\n- Copy validation workflows from\n  `.agents/skills/first-tree/assets/framework/workflows/` to\n  `.github/workflows/`\n\nAs you complete each task, check it off in\n`.agents/skills/first-tree/progress.md` by changing `- [ ]` to `- [x]`.\n\n### Step 3: Verify\n\n```bash\ncontext-tree verify\n```\n\nOr, from your source/workspace repo:\n\n```bash\ncontext-tree verify --tree-path ../my-org-context\n```\n\nThis fails if any items in `.agents/skills/first-tree/progress.md` remain\nunchecked, and runs deterministic checks (valid frontmatter, node structure,\nmember nodes exist).\n\n### Step 4: Design Your Domains\n\nCreate top-level directories for your organization's primary concerns. Each needs a `NODE.md`:\n\n```\nmy-org-tree/\n  NODE.md              # root — lists all domains\n  engineering/\n    NODE.md            # decisions about architecture, infra, tooling\n  product/\n    NODE.md            # strategy, roadmap, user research\n  marketing/\n    NODE.md            # positioning, campaigns\n  members/\n    NODE.md            # team members and agents\n    alice/\n      NODE.md          # individual member node\n```\n\n### Step 5: Populate from Existing Work\n\nFor each domain, extract knowledge from existing repos, docs, and systems:\n\n- Decisions and their rationale\n- Cross-domain relationships and dependencies\n- Constraints that aren't obvious from the code\n\nThe tree doesn't duplicate source code — it captures what connects things and why they were built that way.\n\n---\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `context-tree init` | Create or refresh a dedicated tree repo. By default, running in a source/workspace repo creates a sibling `<repo>-context`; use `--here` to initialize the current repo in place. |\n| `context-tree verify` | Check the installed progress file for unchecked items + run deterministic validation. Use `--tree-path` when invoking from another working directory. |\n| `context-tree upgrade` | Refresh the installed framework skill from the currently running `first-tree` npm package and generate follow-up tasks. Use `--tree-path` when invoking from another working directory. |\n| `context-tree help onboarding` | Print this onboarding guide. |\n\n---\n\n## Upgrading the Framework\n\nWhen the framework updates:\n\n```bash\ncontext-tree upgrade\n```\n\n`context-tree upgrade` refreshes `.agents/skills/first-tree/` and\n`.claude/skills/first-tree/` from the skill bundled with the currently running\n`first-tree` npm package, preserves your tree content, and generates follow-up\ntasks in `.agents/skills/first-tree/progress.md`.\n\nIf your repo still uses the older `skills/first-tree/`,\n`skills/first-tree-cli-framework/`, or `.context-tree/` layouts,\n`context-tree upgrade` will migrate it to the current installed layout first.\n\nTo pick up a newer framework release, first run a newer package version, for\nexample `npx first-tree@latest upgrade`, or update your global `first-tree`\ninstall before running `context-tree upgrade`.\n\n---\n\n## Further Reading\n\n- `.agents/skills/first-tree/references/principles.md` — Core principles with detailed examples\n- `.agents/skills/first-tree/references/ownership-and-naming.md` — How nodes are named and owned\n- `AGENTS.md` in your tree — The before/during/after workflow for every task\n";
-//#endregion
-//#region skills/first-tree/engine/onboarding.ts
-function runOnboarding(output = console.log) {
-	output(onboarding_default);
-	return 0;
-}
-//#endregion
-export { onboarding_default as n, runOnboarding as t };