first-tree 0.0.3 → 0.0.5

package/dist/repo-DkR12VUv.js

@@ -0,0 +1,369 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+//#region skills/first-tree/engine/runtime/asset-loader.ts
+const SKILL_NAME = "first-tree";
+const BUNDLED_SKILL_ROOT = join("skills", SKILL_NAME);
+const SKILL_ROOT = join(".agents", "skills", SKILL_NAME);
+const CLAUDE_SKILL_ROOT = join(".claude", "skills", SKILL_NAME);
+const INSTALLED_SKILL_ROOTS = [SKILL_ROOT, CLAUDE_SKILL_ROOT];
+join(SKILL_ROOT, "agents");
+join(SKILL_ROOT, "references");
+const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
+join(FRAMEWORK_ASSET_ROOT, "manifest.json");
+const FRAMEWORK_VERSION = join(FRAMEWORK_ASSET_ROOT, "VERSION");
+const FRAMEWORK_TEMPLATES_DIR = join(FRAMEWORK_ASSET_ROOT, "templates");
+const FRAMEWORK_WORKFLOWS_DIR = join(FRAMEWORK_ASSET_ROOT, "workflows");
+join(FRAMEWORK_ASSET_ROOT, "prompts");
+const FRAMEWORK_EXAMPLES_DIR = join(FRAMEWORK_ASSET_ROOT, "examples");
+join(FRAMEWORK_ASSET_ROOT, "helpers");
+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";
+join(CLAUDE_SKILL_ROOT, "agents");
+join(CLAUDE_SKILL_ROOT, "references");
+const CLAUDE_FRAMEWORK_ASSET_ROOT = join(CLAUDE_SKILL_ROOT, "assets", "framework");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "manifest.json");
+const CLAUDE_FRAMEWORK_VERSION = join(CLAUDE_FRAMEWORK_ASSET_ROOT, "VERSION");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "templates");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "workflows");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "prompts");
+const CLAUDE_FRAMEWORK_EXAMPLES_DIR = join(CLAUDE_FRAMEWORK_ASSET_ROOT, "examples");
+join(CLAUDE_FRAMEWORK_ASSET_ROOT, "helpers");
+const CLAUDE_INSTALLED_PROGRESS = join(CLAUDE_SKILL_ROOT, "progress.md");
+const LEGACY_REPO_SKILL_ROOT = join("skills", SKILL_NAME);
+join(LEGACY_REPO_SKILL_ROOT, "agents");
+join(LEGACY_REPO_SKILL_ROOT, "references");
+const LEGACY_REPO_SKILL_ASSET_ROOT = join(LEGACY_REPO_SKILL_ROOT, "assets", "framework");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "manifest.json");
+const LEGACY_REPO_SKILL_VERSION = join(LEGACY_REPO_SKILL_ASSET_ROOT, "VERSION");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "templates");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "workflows");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "prompts");
+const LEGACY_REPO_SKILL_EXAMPLES_DIR = join(LEGACY_REPO_SKILL_ASSET_ROOT, "examples");
+join(LEGACY_REPO_SKILL_ASSET_ROOT, "helpers");
+const LEGACY_REPO_SKILL_PROGRESS = join(LEGACY_REPO_SKILL_ROOT, "progress.md");
+const LEGACY_SKILL_NAME = "first-tree-cli-framework";
+const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
+const LEGACY_SKILL_ASSET_ROOT = join(LEGACY_SKILL_ROOT, "assets", "framework");
+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");
+join(LEGACY_FRAMEWORK_ROOT, "templates");
+join(LEGACY_FRAMEWORK_ROOT, "workflows");
+join(LEGACY_FRAMEWORK_ROOT, "prompts");
+const LEGACY_EXAMPLES_DIR = join(LEGACY_FRAMEWORK_ROOT, "examples");
+function pathExists(root, relPath) {
+	const fullPath = join(root, relPath);
+	try {
+		return existsSync(fullPath);
+	} catch {
+		return false;
+	}
+}
+function installedSkillRoots() {
+	return [...INSTALLED_SKILL_ROOTS];
+}
+function installedSkillRootsDisplay() {
+	return installedSkillRoots().map((root) => `\`${root}/\``).join(" and ");
+}
+function frameworkVersionCandidates() {
+	return [
+		FRAMEWORK_VERSION,
+		CLAUDE_FRAMEWORK_VERSION,
+		LEGACY_REPO_SKILL_VERSION,
+		LEGACY_SKILL_VERSION,
+		LEGACY_VERSION
+	];
+}
+function progressFileCandidates() {
+	return [
+		INSTALLED_PROGRESS,
+		CLAUDE_INSTALLED_PROGRESS,
+		LEGACY_REPO_SKILL_PROGRESS,
+		LEGACY_SKILL_PROGRESS,
+		LEGACY_PROGRESS
+	];
+}
+function agentInstructionsFileCandidates() {
+	return [AGENT_INSTRUCTIONS_FILE, LEGACY_AGENT_INSTRUCTIONS_FILE];
+}
+function resolveFirstExistingPath(root, candidates) {
+	for (const candidate of candidates) if (pathExists(root, candidate)) return candidate;
+	return null;
+}
+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;
+}
+//#endregion
+//#region skills/first-tree/engine/repo.ts
+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([
+	".DS_Store",
+	".editorconfig",
+	".gitattributes",
+	".github",
+	".gitignore",
+	"AGENT.md",
+	"AGENTS.md",
+	"CLAUDE.md",
+	"LICENSE",
+	"LICENSE.md",
+	"LICENSE.txt",
+	"README",
+	"README.md",
+	"README.txt"
+]);
+const SOURCE_FILE_HINTS = new Set([
+	".gitmodules",
+	"Cargo.toml",
+	"Dockerfile",
+	"Gemfile",
+	"Makefile",
+	"bun.lock",
+	"bun.lockb",
+	"docker-compose.yml",
+	"go.mod",
+	"package-lock.json",
+	"package.json",
+	"pnpm-lock.yaml",
+	"pyproject.toml",
+	"requirements.txt",
+	"tsconfig.json",
+	"uv.lock",
+	"vite.config.ts",
+	"vite.config.js"
+]);
+const SOURCE_DIR_HINTS = new Set([
+	"app",
+	"apps",
+	"backend",
+	"cli",
+	"client",
+	"docs",
+	"e2e",
+	"frontend",
+	"lib",
+	"packages",
+	"scripts",
+	"server",
+	"src",
+	"test",
+	"tests"
+]);
+const FRAMEWORK_END_MARKER = "<!-- END CONTEXT-TREE FRAMEWORK -->";
+function hasGitMetadata(root) {
+	try {
+		const stat = statSync(join(root, ".git"));
+		return stat.isDirectory() || stat.isFile();
+	} catch {
+		return false;
+	}
+}
+function discoverGitRoot(start) {
+	let dir = start;
+	while (true) {
+		if (hasGitMetadata(dir)) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+var Repo = class {
+	root;
+	constructor(root) {
+		const start = resolve(root ?? process.cwd());
+		this.root = root === void 0 ? discoverGitRoot(start) ?? start : start;
+	}
+	pathExists(relPath) {
+		return existsSync(join(this.root, relPath));
+	}
+	fileContains(relPath, text) {
+		const fullPath = join(this.root, relPath);
+		try {
+			if (!statSync(fullPath).isFile()) return false;
+			return readFileSync(fullPath, "utf-8").includes(text);
+		} catch {
+			return false;
+		}
+	}
+	readFile(relPath) {
+		try {
+			return readFileSync(join(this.root, relPath), "utf-8");
+		} catch {
+			return null;
+		}
+	}
+	frontmatter(relPath) {
+		const text = this.readFile(relPath);
+		if (text === null) return null;
+		const m = text.match(FRONTMATTER_RE);
+		if (!m) return null;
+		const fm = m[1];
+		const result = {};
+		const titleM = fm.match(TITLE_RE);
+		if (titleM) result.title = titleM[1].trim();
+		const ownersM = fm.match(OWNERS_RE);
+		if (ownersM) {
+			const raw = ownersM[1].trim();
+			result.owners = raw ? raw.split(",").map((o) => o.trim()).filter(Boolean) : [];
+		}
+		return result.title !== void 0 || result.owners !== void 0 ? result : null;
+	}
+	anyAgentConfig() {
+		return [".claude/settings.json", ".codex/config.json"].some((c) => this.pathExists(c));
+	}
+	installedSkillRoots() {
+		return installedSkillRoots();
+	}
+	missingInstalledSkillRoots() {
+		return this.installedSkillRoots().filter((root) => !this.pathExists(join(root, "SKILL.md")) || !this.pathExists(join(root, "assets", "framework", "VERSION")));
+	}
+	hasCurrentInstalledSkill() {
+		return this.missingInstalledSkillRoots().length === 0;
+	}
+	isGitRepo() {
+		return hasGitMetadata(this.root);
+	}
+	hasFramework() {
+		return this.frameworkLayout() !== null;
+	}
+	frameworkLayout() {
+		return detectFrameworkLayout(this.root);
+	}
+	readVersion() {
+		const versionPath = resolveFirstExistingPath(this.root, frameworkVersionCandidates());
+		if (versionPath === null) return null;
+		const text = this.readFile(versionPath);
+		return text ? text.trim() : null;
+	}
+	progressPath() {
+		return resolveFirstExistingPath(this.root, progressFileCandidates());
+	}
+	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;
+	}
+	frameworkVersionPath() {
+		const layout = this.frameworkLayout();
+		if (layout === "legacy") return LEGACY_VERSION;
+		if (layout === "legacy-skill") return LEGACY_SKILL_VERSION;
+		if (layout === "legacy-repo-skill") return LEGACY_REPO_SKILL_VERSION;
+		if (layout === "claude-skill") return CLAUDE_FRAMEWORK_VERSION;
+		return FRAMEWORK_VERSION;
+	}
+	agentInstructionsPath() {
+		return resolveFirstExistingPath(this.root, agentInstructionsFileCandidates());
+	}
+	hasCanonicalAgentInstructionsFile() {
+		return this.pathExists(AGENT_INSTRUCTIONS_FILE);
+	}
+	hasLegacyAgentInstructionsFile() {
+		return this.pathExists(LEGACY_AGENT_INSTRUCTIONS_FILE);
+	}
+	hasDuplicateAgentInstructionsFiles() {
+		return this.hasCanonicalAgentInstructionsFile() && this.hasLegacyAgentInstructionsFile();
+	}
+	readAgentInstructions() {
+		const relPath = this.agentInstructionsPath();
+		if (relPath === null) return null;
+		return this.readFile(relPath);
+	}
+	hasAgentInstructionsMarkers() {
+		const text = this.readAgentInstructions();
+		if (text === null) return false;
+		return text.includes("<!-- BEGIN CONTEXT-TREE FRAMEWORK") && text.includes("<!-- END CONTEXT-TREE FRAMEWORK -->");
+	}
+	hasMembers() {
+		const membersDir = join(this.root, "members");
+		try {
+			if (!statSync(membersDir).isDirectory()) return false;
+		} catch {
+			return false;
+		}
+		return existsSync(join(membersDir, "NODE.md"));
+	}
+	memberCount() {
+		const membersDir = join(this.root, "members");
+		try {
+			if (!statSync(membersDir).isDirectory()) return 0;
+		} catch {
+			return 0;
+		}
+		let count = 0;
+		const walk = (dir) => {
+			for (const entry of readdirSync(dir)) {
+				const childPath = join(dir, entry);
+				try {
+					if (!statSync(childPath).isDirectory()) continue;
+				} catch {
+					continue;
+				}
+				if (existsSync(join(childPath, "NODE.md"))) count++;
+				walk(childPath);
+			}
+		};
+		walk(membersDir);
+		return count;
+	}
+	hasPlaceholderNode() {
+		return this.fileContains("NODE.md", "<!-- PLACEHOLDER");
+	}
+	repoName() {
+		return basename(this.root);
+	}
+	topLevelEntries() {
+		try {
+			return readdirSync(this.root).filter((entry) => entry !== ".git");
+		} catch {
+			return [];
+		}
+	}
+	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;
+	}
+	isLikelyEmptyRepo() {
+		return this.topLevelEntries().filter((entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry)).length === 0;
+	}
+	isLikelySourceRepo() {
+		if (this.looksLikeTreeRepo()) return false;
+		const entries = this.topLevelEntries().filter((entry) => !EMPTY_REPO_ENTRY_ALLOWLIST.has(entry));
+		if (entries.length === 0) return false;
+		let directoryCount = 0;
+		for (const entry of entries) {
+			if (SOURCE_FILE_HINTS.has(entry)) return true;
+			if (isDirectory(this.root, entry)) {
+				directoryCount += 1;
+				if (SOURCE_DIR_HINTS.has(entry)) return true;
+			}
+		}
+		return directoryCount >= 2 || entries.length >= 4;
+	}
+};
+function isDirectory(root, relPath) {
+	try {
+		return statSync(join(root, relPath)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+//#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 };

package/dist/upgrade-DYzuvv1k.js

@@ -0,0 +1,140 @@
+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 { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+//#region skills/first-tree/engine/runtime/upgrader.ts
+function compareFrameworkVersions(left, right) {
+	const result = left.localeCompare(right, void 0, {
+		numeric: true,
+		sensitivity: "base"
+	});
+	if (result < 0) return -1;
+	if (result > 0) return 1;
+	return 0;
+}
+function readSourceVersion(sourceRoot) {
+	const versionPath = join(resolveCanonicalSkillRoot(sourceRoot), "assets", "framework", "VERSION");
+	try {
+		return readFileSync(versionPath, "utf-8").trim();
+	} catch {
+		return null;
+	}
+}
+//#endregion
+//#region skills/first-tree/engine/upgrade.ts
+const UPGRADE_USAGE = `usage: context-tree upgrade [--tree-path PATH]
+
+Options:
+  --tree-path PATH   Upgrade a tree repo from another working directory
+  --help             Show this help message
+`;
+function writeProgress(repo, content) {
+	const progressPath = join(repo.root, repo.preferredProgressPath());
+	mkdirSync(dirname(progressPath), { recursive: true });
+	writeFileSync(progressPath, content);
+}
+function formatUpgradeTaskList(repo, localVersion, packagedVersion, layout) {
+	const lines = [
+		`# Context Tree Upgrade — v${localVersion} -> v${packagedVersion}\n`,
+		"## Installed Skill",
+		`- [ ] Review local customizations under ${installedSkillRootsDisplay()} and reapply them if needed`,
+		`- [ ] Re-copy any workflow updates you want from \`${FRAMEWORK_WORKFLOWS_DIR}/\` into \`.github/workflows/\``,
+		`- [ ] Re-check any local agent setup that references \`${CLAUDE_SKILL_ROOT}/assets/framework/examples/\` or \`${CLAUDE_SKILL_ROOT}/assets/framework/helpers/\``,
+		`- [ ] Re-check any repo scripts or workflow files that reference \`${SKILL_ROOT}/assets/framework/\``,
+		""
+	];
+	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, "");
+	if (repo.hasAgentInstructionsMarkers()) lines.push("## Agent Instructions", `- [ ] Compare the framework section in \`${AGENT_INSTRUCTIONS_FILE}\` with \`${FRAMEWORK_TEMPLATES_DIR}/${AGENT_INSTRUCTIONS_TEMPLATE}\` and update the content between the markers if needed`, "");
+	lines.push("## Verification", `- [ ] \`${FRAMEWORK_VERSION}\` reads \`${packagedVersion}\``, "- [ ] `context-tree verify` passes", "", "---", "", `**Important:** As you complete each task, check it off in \`${INSTALLED_PROGRESS}\` by changing \`- [ ]\` to \`- [x]\`. Run \`context-tree verify\` when done — it will fail if any items remain unchecked.`, "");
+	return lines.join("\n");
+}
+function runUpgrade(repo, options) {
+	const workingRepo = repo ?? new Repo();
+	if (workingRepo.isLikelySourceRepo() && !workingRepo.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 upgrade an existing tree repo.");
+		return 1;
+	}
+	if (!workingRepo.hasFramework()) {
+		console.error("Error: no installed framework skill found. Run `context-tree init` first.");
+		return 1;
+	}
+	const layout = workingRepo.frameworkLayout();
+	if (layout === null) {
+		console.error("Error: no installed framework skill found. Run `context-tree init` first.");
+		return 1;
+	}
+	const localVersion = workingRepo.readVersion() ?? "unknown";
+	console.log(`Local framework version: ${localVersion}\n`);
+	console.log("Checking the framework skill bundled with this first-tree package...");
+	let sourceRoot;
+	try {
+		sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+	} catch (err) {
+		const message = err instanceof Error ? err.message : "unknown error";
+		console.error(`Error: ${message}`);
+		return 1;
+	}
+	const packagedVersion = readSourceVersion(sourceRoot);
+	if (packagedVersion === null) {
+		console.log("Could not read the bundled framework version. Reinstall or update `first-tree` and try again.");
+		return 1;
+	}
+	if (localVersion !== "unknown" && compareFrameworkVersions(localVersion, packagedVersion) > 0) {
+		console.log("The installed framework is newer than the skill bundled with this `first-tree` package. Install a newer package version before running `context-tree upgrade`.");
+		return 1;
+	}
+	const missingInstalledRoots = workingRepo.missingInstalledSkillRoots();
+	if (layout === "skill" && missingInstalledRoots.length === 0 && packagedVersion === localVersion) {
+		console.log(`Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`);
+		return 0;
+	}
+	copyCanonicalSkill(sourceRoot, workingRepo.root);
+	if (layout === "legacy") {
+		rmSync(join(workingRepo.root, LEGACY_FRAMEWORK_ROOT), {
+			recursive: true,
+			force: true
+		});
+		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);
+	console.log(`\n${output}`);
+	writeProgress(workingRepo, output);
+	console.log(`Progress file written to ${workingRepo.preferredProgressPath()}`);
+	return 0;
+}
+function runUpgradeCli(args = []) {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(UPGRADE_USAGE);
+		return 0;
+	}
+	let treePath;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--tree-path") {
+			const value = args[index + 1];
+			if (!value) {
+				console.error("Missing value for --tree-path");
+				console.log(UPGRADE_USAGE);
+				return 1;
+			}
+			treePath = value;
+			index += 1;
+			continue;
+		}
+		console.error(`Unknown upgrade option: ${arg}`);
+		console.log(UPGRADE_USAGE);
+		return 1;
+	}
+	return runUpgrade(treePath ? new Repo(resolve(process.cwd(), treePath)) : void 0);
+}
+//#endregion
+export { runUpgradeCli as runUpgrade };

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

@@ -1,6 +1,6 @@
-import { n as Repo } from "./repo-BTJG8BU1.js";
+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 { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
+import { join, relative, resolve } from "node:path";
 //#region skills/first-tree/engine/validators/members.ts
 const FRONTMATTER_RE$1 = /^---\s*\n(.*?)\n---/s;
 const VALID_TYPES = new Set([
@@ -133,7 +133,11 @@ const SOFT_LINKS_BLOCK_RE = /^soft_links:\s*\n((?:\s+-\s+.+\n?)+)/m;
 const TITLE_RE = /^title:\s*['"]?(.+?)['"]?\s*$/m;
 const GITHUB_USER_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,37}[a-zA-Z0-9])?$/;
 const SKIP = new Set(["node_modules", "__pycache__"]);
-const SKIP_FILES = new Set(["AGENT.md", "CLAUDE.md"]);
+const SKIP_FILES = new Set([
+	AGENT_INSTRUCTIONS_FILE,
+	LEGACY_AGENT_INSTRUCTIONS_FILE,
+	"CLAUDE.md"
+]);
 const MIN_BODY_LENGTH = 20;
 var Findings = class {
 	errors = [];
@@ -181,8 +185,23 @@ function setTreeRoot(root) {
 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}/`);
+}
+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");
+	} catch {
+		return false;
+	}
+}
 function shouldSkip(path) {
-	return relative(treeRoot, path).split("/").some((part) => SKIP.has(part) || part.startsWith("."));
+	const relPath = relative(treeRoot, path);
+	if (relPath.split("/").some((part) => SKIP.has(part) || part.startsWith("."))) return true;
+	return isInstalledSkillPath(relPath) || isFrameworkContainerDir(relPath, path);
 }
 function readText(path) {
 	if (!textCache.has(path)) try {
@@ -469,6 +488,12 @@ function runValidateNodes(root) {
 //#endregion
 //#region skills/first-tree/engine/verify.ts
 const UNCHECKED_RE = /^- \[ \] (.+)$/gm;
+const VERIFY_USAGE = `usage: context-tree verify [--tree-path PATH]
+
+Options:
+  --tree-path PATH   Verify a tree repo from another working directory
+  --help             Show this help message
+`;
 function check(label, passed) {
 	console.log(`  ${passed ? "✓" : "✗"} [${passed ? "PASS" : "FAIL"}] ${label}`);
 	return passed;
@@ -490,6 +515,10 @@ function defaultNodeValidator(root) {
 function runVerify(repo, nodeValidator) {
 	const r = repo ?? new Repo();
 	const validate = nodeValidator ?? defaultNodeValidator;
+	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;
+	}
 	let allPassed = true;
 	const progressPath = r.progressPath() ?? r.preferredProgressPath();
 	const frameworkVersionPath = r.frameworkVersionPath();
@@ -506,7 +535,13 @@ function runVerify(repo, nodeValidator) {
 	allPassed = check(`${frameworkVersionPath} exists`, r.hasFramework()) && allPassed;
 	const fm = r.frontmatter("NODE.md");
 	allPassed = check("Root NODE.md has valid frontmatter (title, owners)", fm !== null && fm.title !== void 0 && fm.owners !== void 0) && allPassed;
-	allPassed = check("AGENT.md exists with framework markers", r.hasAgentMdMarkers()) && allPassed;
+	const hasCanonicalAgentInstructions = r.hasCanonicalAgentInstructionsFile();
+	const hasLegacyAgentInstructions = r.hasLegacyAgentInstructionsFile();
+	if (hasLegacyAgentInstructions) {
+		const followUp = hasCanonicalAgentInstructions ? `Remove legacy \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` after confirming its contents are in \`${AGENT_INSTRUCTIONS_FILE}\`.` : `Rename \`${LEGACY_AGENT_INSTRUCTIONS_FILE}\` to \`${AGENT_INSTRUCTIONS_FILE}\`.`;
+		console.log(`  Legacy agent instructions detected. ${followUp}\n`);
+	}
+	allPassed = check(`AGENTS.md is the only agent instructions file and has framework markers`, hasCanonicalAgentInstructions && !hasLegacyAgentInstructions && r.hasAgentInstructionsMarkers()) && allPassed;
 	const { exitCode } = validate(r.root);
 	allPassed = check("Node validation passes", exitCode === 0) && allPassed;
 	allPassed = check("Member validation passes", runValidateMembers(r.root).exitCode === 0) && allPassed;
@@ -515,5 +550,30 @@ function runVerify(repo, nodeValidator) {
 	else console.log("Some checks failed. See above for details.");
 	return allPassed ? 0 : 1;
 }
+function runVerifyCli(args = []) {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(VERIFY_USAGE);
+		return 0;
+	}
+	let treePath;
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg === "--tree-path") {
+			const value = args[index + 1];
+			if (!value) {
+				console.error("Missing value for --tree-path");
+				console.log(VERIFY_USAGE);
+				return 1;
+			}
+			treePath = value;
+			index += 1;
+			continue;
+		}
+		console.error(`Unknown verify option: ${arg}`);
+		console.log(VERIFY_USAGE);
+		return 1;
+	}
+	return runVerify(treePath ? new Repo(resolve(process.cwd(), treePath)) : void 0);
+}
 //#endregion
-export { runVerify };
+export { runVerifyCli as runVerify };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "first-tree",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "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/*",
@@ -30,6 +30,15 @@
     "dist",
     "skills/first-tree"
   ],
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "pnpm build",
+    "test": "vitest run",
+    "eval": "vitest run --config vitest.eval.config.ts",
+    "typecheck": "tsc --noEmit",
+    "validate:skill": "python3 ./skills/first-tree/scripts/quick_validate.py ./skills/first-tree && bash ./skills/first-tree/scripts/check-skill-sync.sh"
+  },
+  "packageManager": "pnpm@10.25.0",
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/node": "^25.5.0",
@@ -37,12 +46,5 @@
     "typescript": "^5.8.0",
     "vitest": "^3.2.0",
     "yaml": "^2.8.3"
-  },
-  "scripts": {
-    "build": "tsdown",
-    "test": "vitest run",
-    "eval": "vitest run --config vitest.eval.config.ts",
-    "typecheck": "tsc --noEmit",
-    "validate:skill": "python3 ./skills/first-tree/scripts/quick_validate.py ./skills/first-tree && bash ./skills/first-tree/scripts/check-skill-sync.sh"
   }
-}
+}