first-tree 0.0.5 → 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
@@ -53,15 +54,27 @@ context-tree init --here
 ```
 
 - `context-tree init` installs `.agents/skills/first-tree/` and
-  `.claude/skills/first-tree/`, creates `NODE.md`, `AGENTS.md`,
-  `members/NODE.md`, and writes a checklist to
+  `.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
@@ -71,9 +84,9 @@ 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 |
@@ -134,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-CAq0Uhq6.js");
+			const { runInit } = await import("./init-BgGH2_yC.js");
 			return runInit(args.slice(1));
 		}
 		case "verify": {
-			const { runVerify } = await import("./verify-C0IUSkMZ.js");
+			const { runVerify } = await import("./verify-G8gNXzDX.js");
 			return runVerify(args.slice(1));
 		}
 		case "upgrade": {
-			const { runUpgrade } = await import("./upgrade-DYzuvv1k.js");
+			const { runUpgrade } = await import("./upgrade-BvA9oKmi.js");
 			return runUpgrade(args.slice(1));
 		}
-		case "help": return (await import("./help-5-WG9QFm.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-5-WG9QFm.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-3zYUeYQb.js");
+			const { runOnboarding } = await import("./onboarding-lASHHmgO.js");
 			return runOnboarding(output);
 		}
 		default:

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

@@ -1,6 +1,6 @@
-import { T as installedSkillRootsDisplay, b as LEGACY_SKILL_EXAMPLES_DIR, c as FRAMEWORK_ASSET_ROOT, d as FRAMEWORK_VERSION, f as FRAMEWORK_WORKFLOWS_DIR, g as LEGACY_EXAMPLES_DIR, h as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, l as FRAMEWORK_EXAMPLES_DIR, n as Repo, o as CLAUDE_FRAMEWORK_EXAMPLES_DIR, p as INSTALLED_PROGRESS, r as AGENT_INSTRUCTIONS_FILE, t as FRAMEWORK_END_MARKER, u as FRAMEWORK_TEMPLATES_DIR, v as LEGACY_REPO_SKILL_EXAMPLES_DIR } from "./repo-DkR12VUv.js";
-import { n as onboarding_default } from "./onboarding-Dd63N-V1.js";
-import { n as renderTemplateFile, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-UgNasLjl.js";
+import { 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";
@@ -205,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
@@ -246,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`);
@@ -283,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 (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 sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+		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-DkR12VUv.js → repo-Cc5U4DWT.js}

@@ -20,6 +20,9 @@ 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");
@@ -112,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",
@@ -291,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 {
@@ -338,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;
@@ -366,4 +386,4 @@ function isDirectory(root, relPath) {
 	}
 }
 //#endregion
-export { SKILL_NAME as C, LEGACY_SKILL_ROOT as S, installedSkillRootsDisplay as T, LEGACY_FRAMEWORK_ROOT as _, BUNDLED_SKILL_ROOT as a, LEGACY_SKILL_EXAMPLES_DIR as b, FRAMEWORK_ASSET_ROOT as c, FRAMEWORK_VERSION as d, FRAMEWORK_WORKFLOWS_DIR as f, LEGACY_EXAMPLES_DIR as g, LEGACY_AGENT_INSTRUCTIONS_FILE as h, AGENT_INSTRUCTIONS_TEMPLATE as i, FRAMEWORK_EXAMPLES_DIR as l, INSTALLED_SKILL_ROOTS as m, Repo as n, CLAUDE_FRAMEWORK_EXAMPLES_DIR as o, INSTALLED_PROGRESS as p, AGENT_INSTRUCTIONS_FILE as r, CLAUDE_SKILL_ROOT as s, FRAMEWORK_END_MARKER as t, FRAMEWORK_TEMPLATES_DIR as u, LEGACY_REPO_SKILL_EXAMPLES_DIR as v, SKILL_ROOT as w, LEGACY_SKILL_NAME as x, LEGACY_REPO_SKILL_ROOT as y };
+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/{installer-UgNasLjl.js → source-integration-CuKjoheT.js}

@@ -1,5 +1,5 @@
-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 { 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
@@ -48,4 +48,37 @@ function renderTemplateFile(frameworkRoot, templateName, targetRoot, targetPath)
 	return true;
 }
 //#endregion
-export { resolveCanonicalSkillRoot as i, renderTemplateFile as n, resolveBundledPackageRoot as r, copyCanonicalSkill as t };
+//#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 };

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

@@ -1,5 +1,5 @@
-import { S as LEGACY_SKILL_ROOT, T as installedSkillRootsDisplay, _ as LEGACY_FRAMEWORK_ROOT, d as FRAMEWORK_VERSION, f as FRAMEWORK_WORKFLOWS_DIR, h as LEGACY_AGENT_INSTRUCTIONS_FILE, i as AGENT_INSTRUCTIONS_TEMPLATE, n as Repo, p as INSTALLED_PROGRESS, r as AGENT_INSTRUCTIONS_FILE, s as CLAUDE_SKILL_ROOT, u as FRAMEWORK_TEMPLATES_DIR, w as SKILL_ROOT, y as LEGACY_REPO_SKILL_ROOT } from "./repo-DkR12VUv.js";
-import { i as resolveCanonicalSkillRoot, r as resolveBundledPackageRoot, t as copyCanonicalSkill } from "./installer-UgNasLjl.js";
+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 { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 //#region skills/first-tree/engine/runtime/upgrader.ts
@@ -56,7 +56,8 @@ function formatUpgradeTaskList(repo, localVersion, packagedVersion, layout) {
 }
 function runUpgrade(repo, options) {
 	const workingRepo = repo ?? new Repo();
-	if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo()) {
+	const workspaceOnlyIntegration = workingRepo.hasSourceWorkspaceIntegration() && !workingRepo.looksLikeTreeRepo();
+	if (workingRepo.isLikelySourceRepo() && !workingRepo.looksLikeTreeRepo() && !workspaceOnlyIntegration) {
 		console.error("Error: no installed framework skill found here. This looks like a source/workspace repo. Run `context-tree init` to create a dedicated tree repo, or pass `--tree-path` to upgrade an existing tree repo.");
 		return 1;
 	}
@@ -90,6 +91,28 @@ function runUpgrade(repo, options) {
 		return 1;
 	}
 	const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+	const sourceRepoTreePathHint = `../${workingRepo.repoName()}-context`;
+	if (workspaceOnlyIntegration) {
+		if (layout === "skill" && missingInstalledRoots.length === 0 && packagedVersion === localVersion) {
+			const changedFiles = upsertSourceIntegrationFiles(workingRepo.root, `${workingRepo.repoName()}-context`).filter((update) => update.action !== "unchanged").map((update) => update.file);
+			if (changedFiles.length === 0) {
+				console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
+				console.log(`This repo only carries source/workspace integration. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`);
+				return 0;
+			}
+			console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
+			console.log(`Updated the ${SOURCE_INTEGRATION_MARKER} marker lines in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}.`);
+			console.log(`This repo only carries source/workspace integration. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`);
+			return 0;
+		}
+		copyCanonicalSkill(sourceRoot, workingRepo.root);
+		const changedFiles = upsertSourceIntegrationFiles(workingRepo.root, `${workingRepo.repoName()}-context`).filter((update) => update.action !== "unchanged").map((update) => update.file);
+		console.log(`Refreshed ${installedSkillRootsDisplay()} in this source/workspace repo.`);
+		if (changedFiles.length > 0) console.log(`Updated the ${SOURCE_INTEGRATION_MARKER} marker lines in ${changedFiles.map((file) => `\`${file}\``).join(" and ")}.`);
+		else console.log(`The ${SOURCE_INTEGRATION_MARKER} marker lines in ${AGENT_INSTRUCTIONS_FILE} and ${CLAUDE_INSTRUCTIONS_FILE} were already current.`);
+		console.log(`This repo is not the Context Tree. Upgrade the dedicated tree repo separately with \`context-tree upgrade --tree-path ${sourceRepoTreePathHint}\`.`);
+		return 0;
+	}
 	if (layout === "skill" && missingInstalledRoots.length === 0 && packagedVersion === localVersion) {
 		console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
 		return 0;

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

@@ -1,4 +1,4 @@
-import { S as LEGACY_SKILL_ROOT, h as LEGACY_AGENT_INSTRUCTIONS_FILE, n as Repo, r as AGENT_INSTRUCTIONS_FILE, w as SKILL_ROOT } from "./repo-DkR12VUv.js";
+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 { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 //#region skills/first-tree/engine/validators/members.ts
@@ -515,6 +515,10 @@ function defaultNodeValidator(root) {
 function runVerify(repo, nodeValidator) {
 	const r = repo ?? new Repo();
 	const validate = nodeValidator ?? defaultNodeValidator;
+	if (r.hasSourceWorkspaceIntegration() && !r.looksLikeTreeRepo()) {
+		console.error(`Error: this repo only has the first-tree source/workspace integration installed. Verify the dedicated tree repo instead, for example \`context-tree verify --tree-path ../${r.repoName()}-context\`.`);
+		return 1;
+	}
 	if (r.isLikelySourceRepo() && !r.looksLikeTreeRepo()) {
 		console.error("Error: no installed framework skill found here. This looks like a source/workspace repo. Run `context-tree init` to create a dedicated tree repo, or pass `--tree-path` to verify an existing tree repo.");
 		return 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "first-tree",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "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": {
@@ -19,7 +19,7 @@
   ],
   "type": "module",
   "bin": {
-    "context-tree": "dist/cli.js"
+    "context-tree": "./dist/cli.js"
   },
   "imports": {
     "#skill/*": "./skills/first-tree/*",

package/skills/first-tree/SKILL.md

@@ -28,6 +28,7 @@ repos.
 2. Read the user-facing reference that matches the task:
    - `references/onboarding.md`
    - `references/about.md`
+   - `references/source-workspace-installation.md`
    - `references/principles.md`
    - `references/ownership-and-naming.md`
    - `references/upgrade-contract.md`
@@ -58,16 +59,29 @@ repos.
 
 ### Working In A User Tree Repo
 
+- 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
+  create `NODE.md`, `members/`, or tree-scoped `AGENTS.md` there.
 - `context-tree init` defaults to creating or reusing a sibling dedicated tree
-  repo when invoked from a source/workspace repo. Use `--here` to initialize
-  the current repo in place when you are already inside the tree repo.
+  repo when invoked from a source/workspace repo. It installs the bundled skill
+  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.
 - `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`.
+- The default source/workspace workflow is: create or reuse `<repo>-context`,
+  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.
 - `context-tree upgrade` refreshes the installed skill from the copy bundled
-  with the currently running `first-tree` package. 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/`.
+  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/`.
 - 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
@@ -108,6 +122,8 @@ repos.
 - `engine/`: canonical framework and CLI behavior
 - `tests/`: canonical unit and structure validation
 - `references/source-map.md`: canonical reading index
+- `references/source-workspace-installation.md`: source/workspace install
+  contract
 - `references/maintainer-architecture.md`: source-repo architecture and
   invariants
 - `references/maintainer-thin-cli.md`: root shell contract

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."
+  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."

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

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

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

@@ -19,12 +19,15 @@ import {
 import {
   AGENT_INSTRUCTIONS_FILE,
   AGENT_INSTRUCTIONS_TEMPLATE,
+  CLAUDE_INSTRUCTIONS_FILE,
   FRAMEWORK_ASSET_ROOT,
   FRAMEWORK_VERSION,
   INSTALLED_PROGRESS,
   LEGACY_AGENT_INSTRUCTIONS_FILE,
   installedSkillRootsDisplay,
+  SOURCE_INTEGRATION_MARKER,
 } from "#skill/engine/runtime/asset-loader.js";
+import { upsertSourceIntegrationFiles } from "#skill/engine/runtime/source-integration.js";
 
 /**
  * The interactive prompt tool the agent should use to present choices.
@@ -34,8 +37,10 @@ import {
 export const INTERACTIVE_TOOL = "AskUserQuestion";
 export 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
@@ -62,6 +67,7 @@ const TEMPLATE_MAP: TemplateTarget[] = [
 
 interface TaskListContext {
   sourceRepoPath?: string;
+  sourceRepoName?: string;
   dedicatedTreeRepo?: boolean;
 }
 
@@ -106,6 +112,23 @@ export function formatTaskList(
     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.",
@@ -182,9 +205,19 @@ export function runInit(repo?: Repo, options?: InitOptions): number {
   const taskListContext = initTarget.dedicatedTreeRepo
     ? {
         dedicatedTreeRepo: true,
+        sourceRepoName: sourceRepo.repoName(),
         sourceRepoPath: relativePathFrom(r.root, sourceRepo.root),
       }
     : undefined;
+  let sourceRoot: string | null = null;
+
+  const resolveSourceRoot = (): string => {
+    if (sourceRoot !== null) {
+      return sourceRoot;
+    }
+    sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+    return sourceRoot;
+  };
 
   if (initTarget.dedicatedTreeRepo) {
     console.log(
@@ -196,17 +229,55 @@ export function runInit(repo?: Repo, options?: InitOptions): number {
     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 (initTarget.dedicatedTreeRepo) {
+    try {
+      const resolvedSourceRoot = resolveSourceRoot();
+      const hadSourceSkill = sourceRepo.hasCurrentInstalledSkill();
+      if (!hadSourceSkill) {
+        console.log(
+          "Installing the first-tree skill into the source/workspace repo...",
+        );
+        installSkill(resolvedSourceRoot, sourceRepo.root);
+      }
+      const updates = upsertSourceIntegrationFiles(sourceRepo.root, r.repoName());
+      const changedFiles = updates
+        .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 sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+      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) {