@first-tree-ai/context-tree 0.1.6-alpha.202608310559 → 0.1.7

package/dist/cli/index.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-import path, { basename, dirname, isAbsolute, join, parse, posix, relative, resolve } from "node:path";
+import path, { basename, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
 import { EventEmitter } from "node:events";
 import childProcess, { spawnSync } from "node:child_process";
-import fs, { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import fs, { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import process$1 from "node:process";
 import { stripVTControlCharacters } from "node:util";
-import { fileURLToPath } from "node:url";
 import { homedir, tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
@@ -7240,6 +7240,448 @@ function refine(fn, _params = {}) {
 function superRefine(fn, params) {
 	return /* @__PURE__ */ _superRefine(fn, params);
 }
+const CONTEXT_TREE_ROOT_NODE_MAX_BYTES = 16 * 1024;
+const VALIDATION_CODES = {
+	rootMissing: "TREE_ROOT_MISSING",
+	rootNodeInvalid: "TREE_ROOT_NODE_INVALID",
+	rootOnlyFields: "TREE_ROOT_ONLY_FIELDS",
+	directoryNodeMissing: "TREE_DIRECTORY_NODE_MISSING",
+	frontmatterMissing: "TREE_FRONTMATTER_MISSING",
+	frontmatterParse: "TREE_FRONTMATTER_PARSE",
+	titleMissing: "TREE_TITLE_MISSING",
+	titleInvalid: "TREE_TITLE_INVALID",
+	descriptionInvalid: "TREE_DESCRIPTION_INVALID",
+	softLinksInvalid: "TREE_SOFT_LINKS_INVALID",
+	softLinkBroken: "TREE_SOFT_LINK_BROKEN",
+	softLinkPathEscape: "TREE_SOFT_LINK_PATH_ESCAPE",
+	markdownPathEscape: "TREE_MARKDOWN_LINK_PATH_ESCAPE",
+	markdownFileSymlinkBroken: "TREE_MARKDOWN_FILE_SYMLINK_BROKEN",
+	markdownFileSymlinkUnsupported: "TREE_MARKDOWN_FILE_SYMLINK_UNSUPPORTED",
+	markdownFilePathEscape: "TREE_MARKDOWN_FILE_PATH_ESCAPE",
+	markdownFileContentClassMismatch: "TREE_MARKDOWN_FILE_CONTENT_CLASS_MISMATCH",
+	directorySymlinkUnsupported: "TREE_DIRECTORY_SYMLINK_UNSUPPORTED",
+	directorySymlinkPathEscape: "TREE_DIRECTORY_SYMLINK_PATH_ESCAPE"
+};
+const CLI_ERROR_CODES = {
+	corruptConnection: "CORRUPT_CONNECTION",
+	dirtyTree: "DIRTY_TREE",
+	failed: "CONTEXT_TREE_FAILED",
+	githubAuth: "GITHUB_AUTH",
+	invalidTree: "INVALID_TREE",
+	noConnection: "NO_CONNECTION",
+	publishIncomplete: "PUBLISH_INCOMPLETE",
+	repositoryExists: "REPOSITORY_EXISTS",
+	staleConnection: "STALE_CONNECTION",
+	writeOutdated: "WRITE_OUTDATED"
+};
+function hasUnsafeCharacter(value) {
+	return [...value].some((character) => {
+		const code = character.codePointAt(0);
+		return code !== void 0 && (code <= 31 || code === 127 || code === 8232 || code === 8233);
+	});
+}
+const absoluteSingleLinePathSchema = string$2().superRefine((value, context) => {
+	if (!isAbsolute(value) || value.trim() !== value || hasUnsafeCharacter(value)) context.addIssue({
+		code: "custom",
+		message: "Paths must be absolute single-line values."
+	});
+});
+const credentialFreeRepositoryUrlSchema = string$2().superRefine((value, context) => {
+	if (value.trim() !== value || hasUnsafeCharacter(value) || value.includes("\\")) {
+		context.addIssue({
+			code: "custom",
+			message: "Repository URLs must be canonical single-line values."
+		});
+		return;
+	}
+	if (value.includes("?") || value.includes("#")) {
+		context.addIssue({
+			code: "custom",
+			message: "Repository URLs must not contain a query or fragment."
+		});
+		return;
+	}
+	if (/^(?:[a-z\d._-]+@)?[a-z\d.-]+:[^\s/][^\s]*$/iu.test(value)) return;
+	try {
+		const parsed = new URL(value);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:" && parsed.protocol !== "ssh:" || !parsed.hostname || parsed.pathname.split("/").every((part) => part.length === 0) || parsed.password || (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.username) throw new Error("invalid transport");
+	} catch {
+		context.addIssue({
+			code: "custom",
+			message: "Repository URLs must use credential-free HTTP(S), ssh://, or scp-like SSH syntax."
+		});
+	}
+});
+const treeNameSchema = string$2().superRefine((value, context) => {
+	if (!/^[A-Za-z\d][A-Za-z\d._-]{0,99}$/u.test(value) || /\.git$/iu.test(value)) context.addIssue({
+		code: "custom",
+		message: "Tree name must be a safe single path segment."
+	});
+});
+const githubRepositoryIdentitySchema = string$2().superRefine((value, context) => {
+	const parts = value.split("/");
+	const [owner, name] = parts;
+	if (parts.length !== 2 || owner === void 0 || name === void 0 || !/^[A-Za-z\d](?:[A-Za-z\d-]{0,37}[A-Za-z\d])?$/u.test(owner) || !treeNameSchema.safeParse(name).success) context.addIssue({
+		code: "custom",
+		message: "Repository must be an explicit GitHub OWNER/REPO identity."
+	});
+});
+const contextTreeRootNodeSchema = object({
+	frontmatter: object({
+		schemaVersion: literal(1),
+		title: string$2().trim().min(1),
+		description: string$2().trim().min(1).optional(),
+		soft_links: array(string$2().trim().min(1)).min(1).optional()
+	}).loose(),
+	body: string$2().trim().min(1, "Root NODE.md must contain repository-wide context.")
+});
+const contextContentClassSchema = _enum([
+	"normal",
+	"member",
+	"repo-infra"
+]);
+const treeValidationFindingSchema = object({
+	code: _enum(VALIDATION_CODES),
+	message: string$2(),
+	path: string$2(),
+	target: string$2().optional()
+}).strict();
+const contextContentClassCountsSchema = object({
+	normal: number().int().nonnegative(),
+	member: number().int().nonnegative(),
+	"repo-infra": number().int().nonnegative()
+}).strict();
+const SKILL_HOSTS = ["claude", "codex"];
+const skillHostSchema = _enum(SKILL_HOSTS);
+const skillInstallationSchema = object({
+	host: skillHostSchema,
+	path: absoluteSingleLinePathSchema,
+	skills: array(string$2().trim().min(1))
+}).strict();
+const skillInstallSkipSchema = object({
+	host: skillHostSchema,
+	reason: string$2().trim().min(1)
+}).strict();
+object({
+	installed: array(skillInstallationSchema),
+	schemaVersion: literal(1),
+	skipped: array(skillInstallSkipSchema),
+	version: string$2().trim().min(1)
+}).strict();
+const contextTreeReadCommonFields = {
+	contentClass: contextContentClassSchema,
+	kind: _enum(["directory", "file"]),
+	path: string$2()
+};
+const contextTreeReadNodeSchema = object({
+	body: string$2(),
+	frontmatter: record(string$2(), unknown()),
+	...contextTreeReadCommonFields
+}).strict();
+object({
+	children: array(object({
+		description: string$2().optional(),
+		title: string$2(),
+		...contextTreeReadCommonFields
+	}).strict()),
+	node: contextTreeReadNodeSchema,
+	root: string$2(),
+	schemaVersion: literal(1),
+	target: string$2()
+}).strict();
+object({
+	findings: array(treeValidationFindingSchema),
+	ok: boolean(),
+	root: string$2(),
+	scannedByContentClass: contextContentClassCountsSchema,
+	schemaVersion: literal(1)
+}).strict();
+const contextTreeStateSchema = discriminatedUnion("kind", [object({
+	kind: literal("local"),
+	path: absoluteSingleLinePathSchema
+}).strict(), object({
+	kind: literal("github"),
+	path: absoluteSingleLinePathSchema,
+	repository: githubRepositoryIdentitySchema
+}).strict()]);
+const contextTreeConnectionSchema = object({
+	projectPath: absoluteSingleLinePathSchema,
+	tree: contextTreeStateSchema
+}).strict();
+object({
+	schemaVersion: literal(1),
+	tree: contextTreeStateSchema
+}).strict();
+/** Whether the project's AGENTS.md pointer was created, rewritten, or left alone. */
+const projectPointerOutcomeSchema = _enum([
+	"written",
+	"updated",
+	"skipped"
+]);
+object({
+	branch: string$2().trim().min(1),
+	commitSha: string$2(),
+	created: boolean(),
+	pointer: projectPointerOutcomeSchema,
+	schemaVersion: literal(1),
+	title: string$2().trim().min(1),
+	treePath: absoluteSingleLinePathSchema
+}).strict();
+object({
+	pointer: projectPointerOutcomeSchema,
+	schemaVersion: literal(1),
+	tree: contextTreeStateSchema
+}).strict();
+const managedTreeListingEntrySchema = object({
+	name: treeNameSchema,
+	tree: contextTreeStateSchema
+}).strict();
+object({
+	schemaVersion: literal(1),
+	trees: array(managedTreeListingEntrySchema)
+}).strict();
+object({
+	branch: string$2().trim().min(1),
+	schemaVersion: literal(1),
+	sha: string$2(),
+	tree: contextTreeStateSchema
+}).strict();
+object({
+	schemaVersion: literal(1),
+	worktreePath: absoluteSingleLinePathSchema
+}).strict();
+object({
+	branch: string$2().trim().min(1),
+	schemaVersion: literal(1),
+	sha: string$2()
+}).strict();
+object({
+	branch: string$2().trim().min(1),
+	repository: githubRepositoryIdentitySchema,
+	schemaVersion: literal(1),
+	sha: string$2(),
+	url: credentialFreeRepositoryUrlSchema
+}).strict();
+object({
+	error: object({
+		code: _enum(CLI_ERROR_CODES),
+		message: string$2()
+	}).strict(),
+	ok: literal(false),
+	schemaVersion: literal(1)
+}).strict();
+//#endregion
+//#region src/core/internal/errors.ts
+/**
+* A failure the CLI reports with a specific machine-readable code. Anything
+* thrown as a plain Error is reported as CONTEXT_TREE_FAILED instead.
+*/
+var ContextTreeError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "ContextTreeError";
+		this.code = code;
+	}
+};
+//#endregion
+//#region src/core/internal/git.ts
+function defaultRunner(command, args) {
+	const result = spawnSync(command, args, {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		]
+	});
+	return {
+		status: result.status,
+		stderr: typeof result.stderr === "string" ? result.stderr : "",
+		stdout: typeof result.stdout === "string" ? result.stdout : ""
+	};
+}
+/** A failed Git or `gh` operation. Messages never include the argv. */
+var CommandError = class extends Error {
+	command;
+	status;
+	stderr;
+	constructor(command, status, stderr, message) {
+		const detail = sanitizeCommandOutput(stderr).trim();
+		super(detail.length > 0 ? `${message}: ${detail}` : message);
+		this.name = "CommandError";
+		this.command = command;
+		this.status = status;
+		this.stderr = detail;
+	}
+};
+/** Remove credentials and common access-token shapes before surfacing subprocess output. */
+function sanitizeCommandOutput(value) {
+	return value.replace(/((?:https?|ssh):\/\/)[^\s/@]+@/giu, "$1<redacted>@").replace(/\b(?:gh[opsu]_[A-Za-z\d_]{20,}|github_pat_[A-Za-z\d_]{20,})\b/gu, "<redacted>").replace(/(authorization\s*:\s*(?:bearer|token)\s+)[^\s]+/giu, "$1<redacted>");
+}
+function trimOutput(value) {
+	return value.trim();
+}
+function execute(runner, command, args, message) {
+	const result = runner(command, args);
+	if (result.status !== 0) throw new CommandError(command, result.status, result.stderr, message);
+	return trimOutput(result.stdout);
+}
+/** Run a Git command that is not scoped by `-C`, such as `git init <path>`. */
+function gitCommand(args, options = {}) {
+	return execute(options.runner ?? defaultRunner, "git", args, options.message ?? "A Git operation failed.");
+}
+/** Run `git -C <root> <args>` and return trimmed stdout, throwing on failure. */
+function git(root, args, options = {}) {
+	return execute(options.runner ?? defaultRunner, "git", [
+		"-C",
+		root,
+		...args
+	], options.message ?? "A Git operation failed.");
+}
+/** Run `git -C <root> <args>` and return trimmed stdout, or undefined on failure. */
+function optionalGit(root, args, runner = defaultRunner) {
+	const result = runner("git", [
+		"-C",
+		root,
+		...args
+	]);
+	if (result.status !== 0) return void 0;
+	return trimOutput(result.stdout);
+}
+/** Run `gh <args>` and return trimmed stdout, throwing on failure. */
+function gh(args, options = {}) {
+	return execute(options.runner ?? defaultRunner, "gh", args, options.message ?? "A GitHub CLI operation failed.");
+}
+//#endregion
+//#region src/core/internal/github-repository.ts
+const ORIGIN_MESSAGE = "Context Tree origin must identify a credential-free GitHub OWNER/REPO repository.";
+function canonicalGitHubRepositoryUrl(repository) {
+	githubRepositoryIdentitySchema.parse(repository);
+	return `https://github.com/${repository}.git`;
+}
+/** Derive OWNER/REPO from a github.com origin, rejecting anything else. */
+function gitHubRepositoryFromOriginUrl(origin) {
+	if (!credentialFreeRepositoryUrlSchema.safeParse(origin).success) throw new Error(ORIGIN_MESSAGE);
+	let owner;
+	let name;
+	const scp = /^(?:git@)?github\.com:([^/]+)\/(.+)$/iu.exec(origin);
+	if (scp !== null) [, owner, name] = scp;
+	else {
+		const url = URL.parse(origin);
+		if (url === null || url.hostname.toLowerCase() !== "github.com") throw new Error(ORIGIN_MESSAGE);
+		[owner, name] = url.pathname.replace(/^\/+|\/+$/gu, "").split("/");
+	}
+	const repository = `${owner ?? ""}/${(name ?? "").replace(/\.git$/iu, "")}`;
+	if (!githubRepositoryIdentitySchema.safeParse(repository).success) throw new Error(ORIGIN_MESSAGE);
+	return repository;
+}
+//#endregion
+//#region src/core/path.ts
+function isPathInside(root, target) {
+	const path = relative(root, target);
+	return path === "" || !path.startsWith("..") && !isAbsolute(path);
+}
+function resolveTreeRoot(path) {
+	const absolute = resolve(path);
+	const entry = lstatSync(absolute);
+	if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`Context Tree root must be a real directory: ${path}`);
+	return realpathSync(absolute);
+}
+/** Resolve a directory while rejecting symlinks in user-controlled path components. */
+function realDirectoryWithoutSymlinks(path, label) {
+	const absolute = resolve(path);
+	const parsed = parse(absolute);
+	const parts = absolute.slice(parsed.root.length).split(sep).filter(Boolean);
+	let current = parsed.root;
+	for (const [index, part] of parts.entries()) {
+		current = resolve(current, part);
+		if (lstatSync(current).isSymbolicLink()) if (index === 0) current = realpathSync(current);
+		else throw new Error(`${label} must contain no symlink component.`);
+	}
+	if (!lstatSync(current).isDirectory()) throw new Error(`${label} must be a directory.`);
+	return realpathSync(current);
+}
+function toPosixPath(path) {
+	return path.replace(/\\/gu, "/");
+}
+//#endregion
+//#region src/core/internal/project.ts
+/**
+* Projects are identified solely by their canonical local root. A Git
+* repository without an origin, a non-Git directory, a Git worktree, and a
+* separate clone are all independent checkouts with their own canonical root.
+*/
+function canonicalProjectRoot(path, runner) {
+	const directory = realDirectoryWithoutSymlinks(path, "Project path");
+	const toplevel = optionalGit(directory, ["rev-parse", "--show-toplevel"], runner);
+	if (toplevel === void 0 || toplevel.length === 0) return directory;
+	return realpathSync(toplevel);
+}
+//#endregion
+//#region src/core/internal/project-pointer.ts
+const BEGIN = "<!-- context-tree:begin -->";
+const END = "<!-- context-tree:end -->";
+function pointerBlock(treePath) {
+	return [
+		BEGIN,
+		"## Context Tree",
+		"",
+		`This project is connected to a Context Tree at \`${treePath}\`.`,
+		"",
+		"Read the decisions and constraints that bear on a task before planning or",
+		"changing code, and record durable decisions there. Use the `context-tree-read`",
+		"and `context-tree-write` skills rather than editing the tree by hand.",
+		END
+	].join("\n");
+}
+/** A real regular file, a real absent path, or a refusal. */
+function regularFileContent(path) {
+	const entry = lstatSync(path, { throwIfNoEntry: false });
+	if (entry === void 0) return void 0;
+	if (entry.isSymbolicLink() || !entry.isFile()) throw new Error(`Refusing to write the Context Tree pointer through a symlink or non-file: ${path}`);
+	return readFileSync(path, "utf8");
+}
+/**
+* Record the connected tree in the project's own `AGENTS.md`, so any agent that reads
+* instruction files knows the tree exists without a host-specific session hook.
+*
+* Idempotent: a delimited block is rewritten in place, never appended twice, so
+* switching the connected tree updates the existing pointer. All other content is
+* preserved, and an existing regular `CLAUDE.md` is left alone.
+*/
+function writeProjectPointer(projectPath, treePath) {
+	const agentsPath = join(projectPath, "AGENTS.md");
+	const block = pointerBlock(treePath);
+	const existing = regularFileContent(agentsPath);
+	if (existing === void 0) {
+		writeFileSync(agentsPath, `# AGENTS.md\n\n${block}\n`, {
+			encoding: "utf8",
+			mode: 420
+		});
+		linkClaudeMarkdown(projectPath);
+		return "written";
+	}
+	const start = existing.indexOf(BEGIN);
+	const end = existing.indexOf(END);
+	if (start !== -1 && end > start) {
+		const replaced = `${existing.slice(0, start)}${block}${existing.slice(end + 25)}`;
+		if (replaced === existing) return "skipped";
+		writeFileSync(agentsPath, replaced, { encoding: "utf8" });
+		return "updated";
+	}
+	writeFileSync(agentsPath, `${existing}${existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n"}${block}\n`, { encoding: "utf8" });
+	linkClaudeMarkdown(projectPath);
+	return "written";
+}
+/** Point CLAUDE.md at AGENTS.md only when the project has no CLAUDE.md of its own. */
+function linkClaudeMarkdown(projectPath) {
+	const claudePath = join(projectPath, "CLAUDE.md");
+	if (lstatSync(claudePath, { throwIfNoEntry: false }) !== void 0) return;
+	try {
+		symlinkSync("AGENTS.md", claudePath, "file");
+	} catch {}
+}
 //#endregion
 //#region node_modules/.pnpm/yaml@2.9.0/node_modules/yaml/dist/nodes/identity.js
 var require_identity = /* @__PURE__ */ __commonJSMin(((exports) => {
@@ -13912,90 +14354,20 @@ function parseMarkdownFrontmatter(source) {
 		};
 	}
 }
-const CONTEXT_TREE_ROOT_NODE_MAX_BYTES = 16 * 1024;
-const VALIDATION_CODES = {
-	rootMissing: "TREE_ROOT_MISSING",
-	rootNodeInvalid: "TREE_ROOT_NODE_INVALID",
-	rootOnlyFields: "TREE_ROOT_ONLY_FIELDS",
-	directoryNodeMissing: "TREE_DIRECTORY_NODE_MISSING",
-	frontmatterMissing: "TREE_FRONTMATTER_MISSING",
-	frontmatterParse: "TREE_FRONTMATTER_PARSE",
-	titleMissing: "TREE_TITLE_MISSING",
-	titleInvalid: "TREE_TITLE_INVALID",
-	descriptionInvalid: "TREE_DESCRIPTION_INVALID",
-	softLinksInvalid: "TREE_SOFT_LINKS_INVALID",
-	softLinkBroken: "TREE_SOFT_LINK_BROKEN",
-	softLinkPathEscape: "TREE_SOFT_LINK_PATH_ESCAPE",
-	markdownPathEscape: "TREE_MARKDOWN_LINK_PATH_ESCAPE",
-	markdownFileSymlinkBroken: "TREE_MARKDOWN_FILE_SYMLINK_BROKEN",
-	markdownFileSymlinkUnsupported: "TREE_MARKDOWN_FILE_SYMLINK_UNSUPPORTED",
-	markdownFilePathEscape: "TREE_MARKDOWN_FILE_PATH_ESCAPE",
-	markdownFileContentClassMismatch: "TREE_MARKDOWN_FILE_CONTENT_CLASS_MISMATCH",
-	directorySymlinkUnsupported: "TREE_DIRECTORY_SYMLINK_UNSUPPORTED",
-	directorySymlinkPathEscape: "TREE_DIRECTORY_SYMLINK_PATH_ESCAPE"
-};
-const CLI_ERROR_CODES = {
-	ambiguousLink: "AMBIGUOUS_LINK",
-	corruptLink: "CORRUPT_LINK",
-	failed: "CONTEXT_TREE_FAILED",
-	noLink: "NO_LINK",
-	staleLink: "STALE_LINK"
-};
-function hasUnsafeCharacter(value) {
-	return [...value].some((character) => {
-		const code = character.codePointAt(0);
-		return code !== void 0 && (code <= 31 || code === 127 || code === 8232 || code === 8233);
-	});
+//#endregion
+//#region src/core/internal/filesystem.ts
+function readUtf8File(path) {
+	return new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path));
 }
-const absoluteSingleLinePathSchema = string$2().superRefine((value, context) => {
-	if (!isAbsolute(value) || value.trim() !== value || hasUnsafeCharacter(value)) context.addIssue({
-		code: "custom",
-		message: "Paths must be absolute single-line values."
-	});
-});
-const credentialFreeRepositoryUrlSchema = string$2().superRefine((value, context) => {
-	if (value.trim() !== value || hasUnsafeCharacter(value) || value.includes("\\")) {
-		context.addIssue({
-			code: "custom",
-			message: "Repository URLs must be canonical single-line values."
-		});
-		return;
-	}
-	if (value.includes("?") || value.includes("#")) {
-		context.addIssue({
-			code: "custom",
-			message: "Repository URLs must not contain a query or fragment."
-		});
-		return;
-	}
-	if (/^(?:[a-z\d._-]+@)?[a-z\d.-]+:[^\s/][^\s]*$/iu.test(value)) return;
-	try {
-		const parsed = new URL(value);
-		if (parsed.protocol !== "http:" && parsed.protocol !== "https:" && parsed.protocol !== "ssh:" || !parsed.hostname || parsed.pathname.split("/").every((part) => part.length === 0) || parsed.password || (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.username) throw new Error("invalid transport");
-	} catch {
-		context.addIssue({
-			code: "custom",
-			message: "Repository URLs must use credential-free HTTP(S), ssh://, or scp-like SSH syntax."
-		});
-	}
-});
-const githubRepositoryIdentitySchema = string$2().superRefine((value, context) => {
-	const parts = value.split("/");
-	const [owner, name] = parts;
-	if (parts.length !== 2 || owner === void 0 || name === void 0 || !/^[A-Za-z\d](?:[A-Za-z\d-]{0,37}[A-Za-z\d])?$/u.test(owner) || !/^[A-Za-z\d._-]{1,100}$/u.test(name) || name === "." || name === ".." || /\.git$/iu.test(name)) context.addIssue({
-		code: "custom",
-		message: "Repository must be an explicit GitHub OWNER/REPO identity."
-	});
-});
-const contextTreeRootNodeSchema = object({
-	frontmatter: object({
-		schemaVersion: literal(1),
-		title: string$2().trim().min(1),
-		description: string$2().trim().min(1).optional(),
-		soft_links: array(string$2().trim().min(1)).min(1).optional()
-	}).loose(),
-	body: string$2().trim().min(1, "Root NODE.md must contain repository-wide context.")
-});
+//#endregion
+//#region src/core/internal/root-node.ts
+/**
+* The one root NODE.md reader. Verification and tree-state resolution both need
+* it, and they must agree on the fail-closed file guard, so it lives here rather
+* than in either caller: tree-state already imports verify, so a shared helper
+* in verify would close a cycle.
+*/
+/** Parse root NODE.md content, bounding size before any YAML or Markdown work. */
 function parseContextTreeRootNode(markdown) {
 	if (Buffer.byteLength(markdown, "utf8") > 16384) throw new Error(`Root NODE.md exceeds the ${CONTEXT_TREE_ROOT_NODE_MAX_BYTES}-byte limit.`);
 	const document = parseMarkdownFrontmatter(markdown);
@@ -14006,214 +14378,12 @@ function parseContextTreeRootNode(markdown) {
 		body: document.body
 	});
 }
-const contextContentClassSchema = _enum([
-	"normal",
-	"member",
-	"repo-infra"
-]);
-const treeValidationFindingSchema = object({
-	code: _enum(VALIDATION_CODES),
-	message: string$2(),
-	path: string$2(),
-	target: string$2().optional()
-}).strict();
-const contextContentClassCountsSchema = object({
-	normal: number().int().nonnegative(),
-	member: number().int().nonnegative(),
-	"repo-infra": number().int().nonnegative()
-}).strict();
-object({
-	content: string$2(),
-	schemaVersion: literal(1)
-}).strict();
-const contextTreeReadCommonFields = {
-	contentClass: contextContentClassSchema,
-	kind: _enum(["directory", "file"]),
-	path: string$2()
-};
-const contextTreeReadNodeSchema = object({
-	body: string$2(),
-	frontmatter: record(string$2(), unknown()),
-	...contextTreeReadCommonFields
-}).strict();
-object({
-	children: array(object({
-		description: string$2().optional(),
-		title: string$2(),
-		...contextTreeReadCommonFields
-	}).strict()),
-	node: contextTreeReadNodeSchema,
-	root: string$2(),
-	schemaVersion: literal(1),
-	target: string$2()
-}).strict();
-const verifyTreeReportSchema = object({
-	findings: array(treeValidationFindingSchema),
-	ok: boolean(),
-	root: string$2(),
-	scannedByContentClass: contextContentClassCountsSchema,
-	schemaVersion: literal(1)
-}).strict();
-object({
-	files: array(string$2()),
-	root: string$2(),
-	schemaVersion: literal(1),
-	verification: verifyTreeReportSchema
-}).strict();
-const contextTreeLinkSchema = object({
-	project: discriminatedUnion("kind", [object({
-		kind: literal("git"),
-		origin: credentialFreeRepositoryUrlSchema
-	}).strict(), object({
-		kind: literal("directory"),
-		path: absoluteSingleLinePathSchema
-	}).strict()]),
-	tree: object({
-		path: absoluteSingleLinePathSchema,
-		repository: githubRepositoryIdentitySchema
-	}).strict()
-}).strict();
-object({
-	link: contextTreeLinkSchema,
-	schemaVersion: literal(1)
-}).strict();
-object({
-	link: contextTreeLinkSchema,
-	defaultBranch: string$2().trim().min(1),
-	refreshed: boolean(),
-	schemaVersion: literal(1),
-	sha: string$2()
-}).strict();
-object({
-	link: contextTreeLinkSchema,
-	defaultBranch: string$2().trim().min(1),
-	baseSha: string$2(),
-	schemaVersion: literal(1),
-	taskBranch: string$2().trim().min(1),
-	worktreePath: string$2()
-}).strict();
-object({
-	base: string$2(),
-	files: array(object({
-		path: string$2(),
-		status: _enum([
-			"added",
-			"deleted",
-			"modified",
-			"renamed",
-			"untracked"
-		])
-	}).strict()).max(4096),
-	patch: string$2(),
-	schemaVersion: literal(1),
-	treePath: string$2()
-}).strict();
-object({
-	error: object({
-		code: _enum(CLI_ERROR_CODES),
-		message: string$2()
-	}).strict(),
-	ok: literal(false),
-	schemaVersion: literal(1)
-}).strict();
-//#endregion
-//#region src/core/internal/github-repository.ts
-function parseGitHubRepositoryIdentity(repository) {
-	githubRepositoryIdentitySchema.parse(repository);
-	return repository.split("/")[1] ?? "";
-}
-function repositoryIdentityFromGitHubUrl(repositoryUrl) {
-	try {
-		credentialFreeRepositoryUrlSchema.parse(repositoryUrl);
-	} catch {
-		throw new Error("Context Tree origin must be a safe credential-free github.com repository URL.");
-	}
-	let host;
-	let path;
-	const scp = /^(?:git@)?([^:]+):(.+)$/u.exec(repositoryUrl);
-	if (scp !== null && !repositoryUrl.includes("://")) {
-		host = scp[1] ?? "";
-		path = scp[2] ?? "";
-	} else {
-		let parsed;
-		try {
-			parsed = new URL(repositoryUrl);
-		} catch {
-			throw new Error("Context Tree origin must be a safe credential-free github.com repository URL.");
-		}
-		if (parsed.password || (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.username) throw new Error("Context Tree origin must be a safe credential-free github.com repository URL.");
-		host = parsed.hostname;
-		path = parsed.pathname;
-	}
-	if (host.toLowerCase() !== "github.com") throw new Error("Context Tree origin must use github.com.");
-	const identity = path.replace(/^\/+|\/+$/gu, "").replace(/\.git$/iu, "");
-	try {
-		parseGitHubRepositoryIdentity(identity);
-	} catch {
-		throw new Error("Context Tree origin must identify a safe GitHub OWNER/REPO repository.");
-	}
-	return identity;
-}
-function canonicalGitHubRepositoryUrl(repository) {
-	parseGitHubRepositoryIdentity(repository);
-	return `https://github.com/${repository}.git`;
-}
-//#endregion
-//#region src/core/internal/packaged-resource.ts
-const PACKAGE_NAME = "@first-tree-ai/context-tree";
-function isPackageRoot(path) {
-	const manifestPath = join(path, "package.json");
-	if (!existsSync(manifestPath)) return false;
-	try {
-		const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
-		return isRecord(manifest) && manifest.name === PACKAGE_NAME;
-	} catch {
-		return false;
-	}
-}
-function resolvePackagedResource(...segments) {
-	let candidate = dirname(fileURLToPath(import.meta.url));
-	const filesystemRoot = parse(candidate).root;
-	while (true) {
-		if (isPackageRoot(candidate)) {
-			const resource = resolve(candidate, ...segments);
-			if (existsSync(resource)) return resource;
-			throw new Error(`Packaged resource is missing: ${segments.join("/")}`);
-		}
-		if (candidate === filesystemRoot) break;
-		candidate = dirname(candidate);
-	}
-	throw new Error(`Package root is missing while resolving: ${segments.join("/")}`);
-}
-function readPackageManifest() {
-	const parsed = JSON.parse(readFileSync(resolvePackagedResource("package.json"), "utf8"));
-	if (!isRecord(parsed)) throw new Error("Package metadata is invalid.");
-	return parsed;
-}
-function readPackageVersion() {
-	const manifest = readPackageManifest();
-	if (typeof manifest.version !== "string") throw new Error("Package version is missing or invalid.");
-	return manifest.version;
-}
-//#endregion
-//#region src/core/internal/filesystem.ts
-function readUtf8File(path) {
-	return new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path));
-}
-//#endregion
-//#region src/core/path.ts
-function isPathInside(root, target) {
-	const path = relative(root, target);
-	return path === "" || !path.startsWith("..") && !isAbsolute(path);
-}
-function resolveTreeRoot(path) {
-	const absolute = resolve(path);
-	const entry = lstatSync(absolute);
-	if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`Context Tree root must be a real directory: ${path}`);
-	return realpathSync(absolute);
-}
-function toPosixPath(path) {
-	return path.replace(/\\/gu, "/");
+/** Read and parse a tree's root NODE.md, refusing symlinked or irregular files. */
+function readRootNode(root) {
+	const path = join(root, "NODE.md");
+	const entry = lstatSync(path);
+	if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("Root NODE.md must be a regular file and must not be a symlink.");
+	return parseContextTreeRootNode(readUtf8File(path));
 }
 //#endregion
 //#region src/core/internal/content-class.ts
@@ -25199,16 +25369,13 @@ function collectNodeValidationFindings(treeRoot) {
 //#endregion
 //#region src/core/verify.ts
 function rootNodeFindings(root) {
-	const path = join(root, "NODE.md");
-	if (!existsSync(path)) return [{
+	if (!existsSync(join(root, "NODE.md"))) return [{
 		code: VALIDATION_CODES.rootMissing,
 		message: "root NODE.md is missing",
 		path: "NODE.md"
 	}];
 	try {
-		const entry = lstatSync(path);
-		if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("Root NODE.md must be a regular file and must not be a symlink.");
-		parseContextTreeRootNode(readUtf8File(path));
+		readRootNode(root);
 		return [];
 	} catch (error) {
 		return [{
@@ -25240,417 +25407,720 @@ function verifyTree(treePath) {
 	};
 }
 //#endregion
-//#region src/core/links.ts
-const contextTreeLinksFileSchema = object({
-	links: array(contextTreeLinkSchema),
+//#region src/core/internal/tree-state.ts
+/**
+* The one tree-state resolver shared by create, connect, sync, publish, and
+* writes. It validates a checkout exactly once and reports the discriminated
+* tree state: a local-only tree, or a published tree with its GitHub
+* OWNER/REPO identity. Resolution never backfills or mutates stored state.
+*/
+/** Require a real directory with no symlink component that is an exact Git root. */
+function exactGitRoot(treePath, runner) {
+	const root = realDirectoryWithoutSymlinks(treePath, "Context Tree path");
+	const toplevel = optionalGit(root, ["rev-parse", "--show-toplevel"], runner);
+	if (toplevel === void 0 || toplevel.length === 0) throw new Error("Context Tree path must be a Git repository.");
+	if (realpathSync(toplevel) !== root) throw new Error("Context Tree path must be the real Git root.");
+	return root;
+}
+/**
+* Validate a clean checkout without inferring state from mutable Git remotes.
+* Uncommitted changes and invalid content each get their own code so callers
+* can tell "commit your edits" apart from "this path is gone".
+*/
+function validateTreeCheckout(treePath, runner) {
+	const root = exactGitRoot(treePath, runner);
+	if (git(root, [
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
+	], {
+		message: "Failed to inspect Context Tree cleanliness.",
+		runner
+	}).trim().length !== 0) throw new ContextTreeError(CLI_ERROR_CODES.dirtyTree, `The Context Tree at ${root} has uncommitted changes; commit or discard them.`);
+	if (!verifyTree(root).ok) throw new ContextTreeError(CLI_ERROR_CODES.invalidTree, `The Context Tree at ${root} is invalid; run context-tree verify --tree-path ${root}.`);
+	return root;
+}
+/** Validate a stored state without reclassifying it from mutable Git remotes. */
+function validateStoredTreeState(state, runner) {
+	const path = validateTreeCheckout(state.path, runner);
+	return state.kind === "local" ? {
+		kind: "local",
+		path
+	} : {
+		kind: "github",
+		path,
+		repository: state.repository
+	};
+}
+//#endregion
+//#region src/core/connections.ts
+const connectionsFileSchema = object({
+	connections: array(contextTreeConnectionSchema),
 	schemaVersion: literal(1)
 }).strict();
-var LinkError = class extends Error {
-	code;
-	constructor(code, message) {
-		super(message);
-		this.name = "LinkError";
-		this.code = code;
+const DUPLICATE_MESSAGE = "Duplicate Context Tree connection records exist for this project.";
+const NO_CONNECTION_MESSAGE = "No Context Tree connection exists for this project; run context-tree create or connect.";
+function realHome$1() {
+	try {
+		return realpathSync(homedir());
+	} catch {
+		return homedir();
 	}
-};
-function git$1(path, args) {
-	const result = spawnSync("git", [
-		"-C",
-		path,
-		...args
-	], {
-		encoding: "utf8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"ignore"
-		]
-	});
-	if (result.error !== void 0 || result.status !== 0) return void 0;
-	return result.stdout.replace(/\r?\n$/u, "");
 }
-function requireGit$1(path, args, message, allowEmpty = false) {
-	const value = git$1(path, args);
-	if (value === void 0 || !allowEmpty && value.length === 0) throw new Error(message);
-	return value;
-}
-function normalizeRepositoryUrl(repositoryUrl) {
-	try {
-		credentialFreeRepositoryUrlSchema.parse(repositoryUrl);
-	} catch {
-		throw new Error("Git origin must be a canonical credential-free repository URL.");
+/** Create a managed application directory below the home directory, failing closed on symlinks. */
+function ensureManagedDirectory(...segments) {
+	let current = realHome$1();
+	for (const segment of segments) {
+		current = join(current, segment);
+		const entry = lstatSync(current, { throwIfNoEntry: false });
+		if (entry === void 0) {
+			mkdirSync(current, { mode: 448 });
+			continue;
+		}
+		if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`Context Tree managed directory must be a real directory: ${current}`);
 	}
-	try {
-		return canonicalGitHubRepositoryUrl(repositoryIdentityFromGitHubUrl(repositoryUrl).toLowerCase());
-	} catch {}
-	const scp = /^(?:([^@]+)@)?([^:]+):(.+)$/u.exec(repositoryUrl);
-	if (scp !== null && !repositoryUrl.includes("://")) return `${scp[1] === void 0 ? "" : `${scp[1].toLowerCase()}@`}${(scp[2] ?? "").toLowerCase()}:${(scp[3] ?? "").replace(/\/+$/gu, "").replace(/\.git$/iu, "")}.git`;
-	const parsed = new URL(repositoryUrl);
-	parsed.hostname = parsed.hostname.toLowerCase();
-	parsed.pathname = `${parsed.pathname.replace(/\/+$/gu, "").replace(/\.git$/iu, "")}.git`;
-	return parsed.toString();
-}
-function realDirectory(path) {
-	const absolute = resolve(path);
-	if (!lstatSync(absolute).isDirectory()) throw new Error("Project path must be a directory.");
-	return realpathSync(absolute);
+	return current;
 }
-function identifyProject(projectPath) {
-	const path = realDirectory(projectPath);
-	const gitRoot = git$1(path, ["rev-parse", "--show-toplevel"]);
-	if (gitRoot === void 0) return {
-		kind: "directory",
-		path
-	};
-	return {
-		kind: "git",
-		origin: normalizeRepositoryUrl(requireGit$1(realpathSync(gitRoot), [
-			"remote",
-			"get-url",
-			"origin"
-		], "Git project must have an origin remote."))
-	};
+/** The managed namespace without creating it; listing must not create an absent directory. */
+function managedTreesPath() {
+	return join(realHome$1(), ".context-tree", "trees");
 }
-function linksPath() {
-	return join(homedir(), ".context-tree", "connections.json");
+function connectionsPath() {
+	return join(realHome$1(), ".context-tree", "connections.json");
 }
-function emptyLinks() {
-	return {
-		links: [],
-		schemaVersion: 1
-	};
+function managedTreesRoot() {
+	return ensureManagedDirectory(".context-tree", "trees");
 }
-function loadLinks(required) {
-	const path = linksPath();
+function loadConnections(required) {
+	const path = connectionsPath();
 	if (!existsSync(path)) {
-		if (required) throw new LinkError(CLI_ERROR_CODES.noLink, "No Context Tree link exists for this project.");
-		return emptyLinks();
+		if (required) throw new ContextTreeError(CLI_ERROR_CODES.noConnection, NO_CONNECTION_MESSAGE);
+		return {
+			connections: [],
+			schemaVersion: 1
+		};
 	}
 	try {
 		const entry = lstatSync(path);
 		if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("not a regular file");
-		return contextTreeLinksFileSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+		return connectionsFileSchema.parse(JSON.parse(readFileSync(path, "utf8")));
 	} catch {
-		throw new LinkError(CLI_ERROR_CODES.corruptLink, "Context Tree links are corrupt; run link after repairing or removing the internal links file.");
+		throw new ContextTreeError(CLI_ERROR_CODES.corruptConnection, "Context Tree connections are corrupt; remove connections.json and run context-tree connect again.");
 	}
 }
-function saveLinks(value) {
-	const path = linksPath();
-	const directory = dirname(path);
-	mkdirSync(directory, {
-		recursive: true,
-		mode: 448
-	});
-	const directoryEntry = lstatSync(directory);
-	if (directoryEntry.isSymbolicLink() || !directoryEntry.isDirectory()) throw new Error("Context Tree links directory must be a real directory.");
-	const temporary = join(directory, `.links-${process.pid}-${Date.now()}.tmp`);
-	writeFileSync(temporary, `${JSON.stringify(contextTreeLinksFileSchema.parse(value), null, 2)}\n`, {
+function saveConnections(value) {
+	const directory = ensureManagedDirectory(".context-tree");
+	const path = join(directory, "connections.json");
+	const temporary = join(directory, `.connections-${process.pid}-${Date.now()}.tmp`);
+	writeFileSync(temporary, `${JSON.stringify(connectionsFileSchema.parse(value), null, 2)}\n`, {
 		encoding: "utf8",
 		flag: "wx",
 		mode: 384
 	});
-	renameSync(temporary, path);
-	chmodSync(path, 384);
-}
-function exactCheckoutRoot(treePath) {
-	const absolute = resolve(treePath);
-	const entry = lstatSync(absolute);
-	const root = realpathSync(absolute);
-	if (!entry.isDirectory() || entry.isSymbolicLink() || absolute !== root) throw new Error("Context Tree checkout path must be a real directory with no symlink component.");
-	if (realpathSync(requireGit$1(root, ["rev-parse", "--show-toplevel"], "Context Tree checkout must be a Git repository.")) !== root) throw new Error("Context Tree checkout must be the real Git root.");
-	return root;
+	try {
+		renameSync(temporary, path);
+		chmodSync(path, 384);
+	} finally {
+		rmSync(temporary, { force: true });
+	}
 }
-function checkoutRepository(root) {
-	return repositoryIdentityFromGitHubUrl(requireGit$1(root, [
-		"remote",
-		"get-url",
-		"origin"
-	], "Context Tree checkout must have an origin remote."));
+/** Exactly one record may exist per project; more than one is corruption. */
+function singleConnection(stored, canonical) {
+	const matches = stored.connections.filter((connection) => connection.projectPath === canonical);
+	if (matches.length > 1) throw new ContextTreeError(CLI_ERROR_CODES.corruptConnection, DUPLICATE_MESSAGE);
+	return matches[0];
 }
-function requireCheckoutClean(root, mode) {
-	const status = requireGit$1(root, [
-		"status",
-		"--porcelain",
-		"--untracked-files=all"
-	], "Failed to inspect Context Tree cleanliness.", true);
-	if (status.length === 0) return;
-	if (mode === "scaffold") {
-		const lines = status.split("\n").sort();
-		if (git$1(root, [
-			"rev-parse",
-			"--verify",
-			"HEAD"
-		]) === void 0 && JSON.stringify(lines) === JSON.stringify([
-			"?? .github/workflows/validate-context-tree.yml",
-			"?? AGENTS.md",
-			"?? CLAUDE.md",
-			"?? NODE.md"
-		])) return;
-	}
-	throw new Error("Context Tree checkout must be clean.");
+function isManagedName(value) {
+	return treeNameSchema.safeParse(value).success && value === value.toLowerCase();
 }
-function parseRootNode(root) {
-	const path = join(root, "NODE.md");
-	const entry = lstatSync(path);
-	if (entry.isSymbolicLink() || !entry.isFile()) throw new Error("Context Tree root NODE.md must be a regular file.");
-	return parseContextTreeRootNode(readUtf8File(path));
+function managedName(value) {
+	if (!isManagedName(value)) throw new Error(`Managed Context Tree names must be safe lowercase path segments: ${value}`);
+	return value;
 }
-function verifyCheckout(treePath, mode) {
-	const root = exactCheckoutRoot(treePath);
-	requireCheckoutClean(root, mode);
-	const repository = checkoutRepository(root);
-	if (!verifyTree(root).ok) throw new Error("Context Tree checkout is invalid; run context-tree verify.");
+/** List valid, clean managed trees, excluding unsafe or invalid candidates without failing the listing. */
+function listManagedTrees(runner) {
+	const root = managedTreesPath();
+	if (!existsSync(root)) return {
+		schemaVersion: 1,
+		trees: []
+	};
+	const rootEntry = lstatSync(root);
+	if (rootEntry.isSymbolicLink() || !rootEntry.isDirectory()) throw new Error("Context Tree managed directory must be a real directory.");
+	const trees = [];
+	for (const candidate of readdirSync(root, { withFileTypes: true })) {
+		if (!candidate.isDirectory() || !isManagedName(candidate.name)) continue;
+		try {
+			trees.push({
+				name: candidate.name,
+				tree: classifyCheckout(join(root, candidate.name), runner)
+			});
+		} catch {}
+	}
+	trees.sort((left, right) => left.name.localeCompare(right.name));
 	return {
-		path: root,
-		repository
+		schemaVersion: 1,
+		trees
 	};
 }
-function sameProject(left, right) {
-	return left.kind === "git" && right.kind === "git" ? left.origin === right.origin : left.kind === "directory" && right.kind === "directory" && left.path === right.path;
+function findConnectionRecord(projectPath, runner) {
+	return singleConnection(loadConnections(false), canonicalProjectRoot(projectPath, runner));
 }
-function projectMatches(candidate, current) {
-	if (candidate.kind === "git" && current.kind === "git") return candidate.origin === current.origin;
-	if (candidate.kind === "directory" && current.kind === "directory") return isPathInside(candidate.path, current.path);
-	return false;
+function validateManagedTreeState(tree, runner) {
+	const validated = validateStoredTreeState(tree, runner);
+	if (dirname(validated.path) === managedTreesPath() && !isManagedName(basename(validated.path))) throw new Error(`Managed Context Tree names must be safe lowercase path segments: ${basename(validated.path)}`);
+	return validated;
 }
-function liveStoredCheckout(link) {
+function resolveConnectionRecord(projectPath, runner) {
+	const canonical = canonicalProjectRoot(projectPath, runner);
+	const connection = singleConnection(loadConnections(true), canonical);
+	if (connection === void 0) throw new ContextTreeError(CLI_ERROR_CODES.noConnection, NO_CONNECTION_MESSAGE);
 	try {
-		const path = exactCheckoutRoot(link.tree.path);
 		return {
-			path,
-			repository: checkoutRepository(path)
+			projectPath: connection.projectPath,
+			tree: validateManagedTreeState(connection.tree, runner)
 		};
-	} catch {
-		return;
+	} catch (error) {
+		if (error instanceof ContextTreeError) throw error;
+		const detail = error instanceof Error ? error.message : "unknown failure";
+		throw new ContextTreeError(CLI_ERROR_CODES.staleConnection, `The connected Context Tree is no longer usable at ${connection.tree.path}; run context-tree connect to point this project at its current location. ${detail}`);
 	}
 }
-function linkWithMode(projectPath, treePath, mode) {
-	const project = identifyProject(projectPath);
-	const tree = verifyCheckout(treePath, mode);
-	const stored = loadLinks(false);
-	const existing = stored.links.filter((link) => sameProject(link.project, project));
-	if (existing.length > 1) throw new LinkError(CLI_ERROR_CODES.ambiguousLink, "Multiple Context Tree links match this project.");
-	const previous = existing[0];
-	if (previous !== void 0) {
-		if (previous.tree.repository.toLowerCase() !== tree.repository.toLowerCase()) throw new Error("A project cannot link to a different Context Tree repository.");
-		if (previous.tree.path !== tree.path) {
-			const live = liveStoredCheckout(previous);
-			if (live !== void 0 && live.repository.toLowerCase() === previous.tree.repository.toLowerCase()) throw new Error("The existing Context Tree checkout is still live; replacement is allowed only when it is stale.");
-		}
-	}
-	const link = {
-		project,
-		tree
+function resolveConnection(projectPath, runner) {
+	return {
+		schemaVersion: 1,
+		tree: resolveConnectionRecord(projectPath, runner).tree
 	};
-	saveLinks({
-		links: [...stored.links.filter((candidate) => !sameProject(candidate.project, project)), link],
+}
+function upsertConnection(connection, runner) {
+	const canonical = canonicalProjectRoot(connection.projectPath, runner);
+	const record = {
+		projectPath: canonical,
+		tree: validateManagedTreeState(contextTreeStateSchema.parse(connection.tree), runner)
+	};
+	const stored = loadConnections(false);
+	const previous = singleConnection(stored, canonical);
+	if (previous !== void 0 && JSON.stringify(previous.tree) === JSON.stringify(record.tree)) return {
+		schemaVersion: 1,
+		tree: record.tree
+	};
+	saveConnections({
+		connections: [...stored.connections.filter((candidate) => candidate.projectPath !== canonical), record],
 		schemaVersion: 1
 	});
 	return {
-		link,
+		schemaVersion: 1,
+		tree: record.tree
+	};
+}
+function updateConnectionTree(projectPath, tree, runner) {
+	const canonical = canonicalProjectRoot(projectPath, runner);
+	const stored = loadConnections(true);
+	if (singleConnection(stored, canonical) === void 0) throw new ContextTreeError(CLI_ERROR_CODES.noConnection, NO_CONNECTION_MESSAGE);
+	const validatedTree = validateManagedTreeState(contextTreeStateSchema.parse(tree), runner);
+	saveConnections({
+		connections: stored.connections.map((connection) => connection.projectPath === canonical ? {
+			...connection,
+			tree: validatedTree
+		} : connection),
 		schemaVersion: 1
+	});
+}
+/**
+* Validate an exact checkout and classify it from a safe origin: no origin
+* is local state, a credential-free GitHub origin is GitHub state, and any
+* other origin is rejected as unsafe or unsupported.
+*/
+function classifyCheckout(path, runner) {
+	const root = validateTreeCheckout(path, runner);
+	const origin = optionalGit(root, [
+		"remote",
+		"get-url",
+		"origin"
+	], runner);
+	if (origin === void 0) return {
+		kind: "local",
+		path: root
+	};
+	return {
+		kind: "github",
+		path: root,
+		repository: gitHubRepositoryFromOriginUrl(origin)
 	};
 }
-function linkProject(projectPath, treePath) {
-	return linkWithMode(projectPath, treePath, "link");
+function sameRepository(left, right) {
+	return left.toLowerCase() === right.toLowerCase();
 }
-function linkScaffoldedProject(projectPath, treePath) {
-	return linkWithMode(projectPath, treePath, "scaffold");
+/** An existing managed directory that must be a real directory, not a symlinked alias. */
+function realManagedDirectory(name, destination) {
+	const entry = lstatSync(destination);
+	if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`Managed Context Tree name ${name} is occupied by an unsafe destination.`);
 }
-function resolveLink(projectPath) {
-	const project = identifyProject(projectPath);
-	const matches = loadLinks(true).links.filter((link) => projectMatches(link.project, project));
-	if (matches.length === 0) throw new LinkError(CLI_ERROR_CODES.noLink, "No Context Tree link exists for this project.");
-	if (matches.length > 1) throw new LinkError(CLI_ERROR_CODES.ambiguousLink, "Multiple Context Tree links match this project.");
-	const link = matches[0];
-	if (link === void 0) throw new Error("Link lookup failed.");
-	try {
-		const root = exactCheckoutRoot(link.tree.path);
-		requireCheckoutClean(root, "link");
-		const repository = checkoutRepository(root);
-		if (repository.toLowerCase() !== link.tree.repository.toLowerCase()) throw new Error("The linked path now contains a different Context Tree repository.");
-		parseRootNode(root);
+/**
+* Connect by exact managed name or GitHub OWNER/REPO, or attach an exact,
+* clean, fully valid Git checkout at an explicit disk path in place.
+*/
+function connectProject(options, runner) {
+	/** Store the connection, then record it in the project so any agent can find it. */
+	const connect = (tree) => {
+		const result = upsertConnection({
+			projectPath: options.projectPath,
+			tree
+		}, runner);
 		return {
-			link: {
-				project: link.project,
-				tree: {
-					path: root,
-					repository
-				}
-			},
-			schemaVersion: 1
+			pointer: writeProjectPointer(canonicalProjectRoot(options.projectPath, runner), result.tree.path),
+			schemaVersion: 1,
+			tree: result.tree
 		};
+	};
+	if ("treePath" in options) return connect(classifyCheckout(options.treePath, runner));
+	const treesRoot = managedTreesRoot();
+	if (!options.target.includes("/")) {
+		const name = managedName(options.target);
+		const destination = join(treesRoot, name);
+		if (!existsSync(destination)) throw new Error(`No managed Context Tree named ${name} exists.`);
+		realManagedDirectory(name, destination);
+		return connect(classifyCheckout(destination, runner));
+	}
+	const repository = githubRepositoryIdentitySchema.parse(options.target);
+	const repositoryName = repository.split("/")[1];
+	if (repositoryName === void 0) throw new Error("Repository must be OWNER/REPO.");
+	const name = managedName(repositoryName.toLowerCase());
+	const destination = join(treesRoot, name);
+	if (existsSync(destination)) {
+		realManagedDirectory(name, destination);
+		const tree = classifyCheckout(destination, runner);
+		if (tree.kind !== "github" || !sameRepository(tree.repository, repository)) throw new Error(`Managed Context Tree name ${name} is already used by a different tree.`);
+		return connect(tree);
+	}
+	mkdirSync(destination, { mode: 448 });
+	try {
+		git(treesRoot, [
+			"clone",
+			"--quiet",
+			"--origin",
+			"origin",
+			"--",
+			canonicalGitHubRepositoryUrl(repository),
+			destination
+		], {
+			message: "Cloning the Context Tree repository failed.",
+			runner
+		});
+		const tree = classifyCheckout(destination, runner);
+		if (tree.kind !== "github" || !sameRepository(tree.repository, repository)) throw new Error("The cloned Context Tree origin does not match the requested repository.");
+		return connect(tree);
 	} catch (error) {
-		const message = error instanceof Error && error.message === "The linked path now contains a different Context Tree repository." ? error.message : "The linked Context Tree checkout is no longer a valid clean candidate; run link when its stored path is stale.";
-		throw new LinkError(CLI_ERROR_CODES.staleLink, message);
+		rmSync(destination, {
+			force: true,
+			recursive: true
+		});
+		throw error;
 	}
 }
 //#endregion
-//#region src/core/live.ts
-function git(root, args) {
-	const result = spawnSync("git", [
-		"-C",
-		root,
-		...args
+//#region src/core/internal/packaged-resource.ts
+const PACKAGE_NAME = "@first-tree-ai/context-tree";
+function isPackageRoot(path) {
+	const manifestPath = join(path, "package.json");
+	if (!existsSync(manifestPath)) return false;
+	try {
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+		return isRecord(manifest) && manifest.name === PACKAGE_NAME;
+	} catch {
+		return false;
+	}
+}
+function resolvePackagedResource(...segments) {
+	let candidate = dirname(fileURLToPath(import.meta.url));
+	const filesystemRoot = parse(candidate).root;
+	while (true) {
+		if (isPackageRoot(candidate)) {
+			const resource = resolve(candidate, ...segments);
+			if (existsSync(resource)) return resource;
+			throw new Error(`Packaged resource is missing: ${segments.join("/")}`);
+		}
+		if (candidate === filesystemRoot) break;
+		candidate = dirname(candidate);
+	}
+	throw new Error(`Package root is missing while resolving: ${segments.join("/")}`);
+}
+function readPackageManifest() {
+	const parsed = JSON.parse(readFileSync(resolvePackagedResource("package.json"), "utf8"));
+	if (!isRecord(parsed)) throw new Error("Package metadata is invalid.");
+	return parsed;
+}
+function readPackageVersion() {
+	const manifest = readPackageManifest();
+	if (typeof manifest.version !== "string") throw new Error("Package version is missing or invalid.");
+	return manifest.version;
+}
+//#endregion
+//#region src/core/scaffold.ts
+function template(name, values) {
+	let result = readFileSync(resolvePackagedResource("templates", name), "utf8");
+	for (const [key, value] of Object.entries(values)) result = result.replaceAll(`{{${key}}}`, value);
+	return result;
+}
+/** Templated regular files, written before the CLAUDE.md -> AGENTS.md symlink. */
+const TEMPLATED_FILES = [
+	["NODE.md", "root-node.md"],
+	["AGENTS.md", "AGENTS.md"],
+	[".github/workflows/validate-context-tree.yml", "validate-context-tree.yml"]
+];
+const SCAFFOLD_FILES = [
+	"NODE.md",
+	"AGENTS.md",
+	"CLAUDE.md",
+	".github/workflows/validate-context-tree.yml"
+];
+function initializeGitRepository(root, runner) {
+	gitCommand([
+		"init",
+		"--quiet",
+		"--",
+		root
 	], {
-		encoding: "utf8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"ignore"
-		]
+		message: "Failed to initialize Git repository.",
+		runner
 	});
-	if (result.error !== void 0 || result.status !== 0) throw new Error("A Git operation failed while preparing the Context Tree.");
-	return typeof result.stdout === "string" ? result.stdout : "";
-}
-function requireGit(root, args, allowEmpty = false) {
-	const output = git(root, args).trim();
-	if (output.length === 0 && !allowEmpty) throw new Error("Unexpected empty Git output.");
-	return output;
-}
-function discoverDefaultBranch(root) {
-	const refs = git(root, [
-		"ls-remote",
-		"--symref",
-		"origin",
-		"HEAD"
-	]).split("\n").map((line) => /^ref: refs\/heads\/([^\s\t]+)\tHEAD$/u.exec(line)?.[1]).filter((value) => value !== void 0 && value.length > 0);
-	if (refs.length !== 1) throw new Error("The Context Tree origin must report exactly one live default branch.");
-	return refs[0] ?? "";
-}
-function refreshProject(projectPath) {
-	const result = resolveLink(projectPath);
-	const root = result.link.tree.path;
-	const defaultBranch = discoverDefaultBranch(root);
-	if (requireGit(root, [
+	return git(root, [
 		"symbolic-ref",
 		"--short",
 		"HEAD"
-	]) !== defaultBranch) throw new Error(`The Context Tree checkout must be on the live default branch "${defaultBranch}".`);
-	const before = requireGit(root, ["rev-parse", "HEAD"]);
-	requireGit(root, [
-		"pull",
-		"--ff-only",
-		"origin",
-		defaultBranch
-	]);
-	const after = requireGit(root, ["rev-parse", "HEAD"]);
-	return {
-		link: {
-			...result.link,
-			tree: {
-				...result.link.tree,
-				path: realpathSync(root)
-			}
-		},
-		defaultBranch,
-		refreshed: before !== after,
-		schemaVersion: 1,
-		sha: after
-	};
+	], {
+		message: "Failed to resolve the initial Git branch during repository initialization.",
+		runner
+	});
 }
-function createIsolatedWorktree(treePath, baseSha) {
-	const destination = mkdtempSync(join(tmpdir(), "context-tree-stage-"));
-	const taskBranch = `context-tree/write/${basename(destination)}`;
-	git(treePath, [
-		"worktree",
+function commitScaffold(root, runner) {
+	for (const file of SCAFFOLD_FILES) git(root, [
 		"add",
-		"-b",
-		taskBranch,
-		destination,
-		baseSha
-	]);
+		"--",
+		file
+	], {
+		message: "Failed to stage the scaffold files.",
+		runner
+	});
+	git(root, [
+		"-c",
+		"user.name=Context Tree",
+		"-c",
+		"user.email=context-tree@localhost",
+		"-c",
+		"commit.gpgsign=false",
+		"commit",
+		"--quiet",
+		"-m",
+		"Initialize Context Tree"
+	], {
+		message: "Failed to commit the scaffold.",
+		runner
+	});
+	return git(root, ["rev-parse", "HEAD"], {
+		message: "Failed to resolve the scaffold commit.",
+		runner
+	});
+}
+function scaffoldTree(options) {
+	const name = treeNameSchema.parse(options.name);
+	const root = resolve(options.path);
+	const destination = lstatSync(root, { throwIfNoEntry: false });
+	if (destination !== void 0) {
+		if (destination.isSymbolicLink() || !destination.isDirectory()) throw new Error(`Refusing to scaffold into a symlink or non-directory destination: ${root}`);
+		if (readdirSync(root).length > 0) throw new Error(`Refusing to scaffold into a non-empty directory: ${root}`);
+	}
+	const initialBranch = initializeGitRepository(root, options.runner);
+	const values = {
+		branchJson: JSON.stringify(initialBranch),
+		packageVersion: readPackageVersion(),
+		title: name,
+		titleJson: JSON.stringify(name)
+	};
+	for (const [relativePath, source] of TEMPLATED_FILES) {
+		const path = join(root, relativePath);
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, template(source, values), {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 420
+		});
+	}
+	symlinkSync("AGENTS.md", join(root, "CLAUDE.md"), "file");
+	if (!verifyTree(root).ok) throw new Error("Refusing to commit an invalid Context Tree scaffold.");
 	return {
-		taskBranch,
-		worktreePath: realpathSync(destination)
+		branch: initialBranch,
+		commit: commitScaffold(root, options.runner),
+		root
 	};
 }
-function stageContextWrite(projectPath) {
-	const result = resolveLink(projectPath);
-	const treePath = result.link.tree.path;
-	const ownerRepository = result.link.tree.repository;
-	const defaultBranch = discoverDefaultBranch(treePath);
-	if (requireGit(treePath, [
-		"symbolic-ref",
-		"--short",
-		"HEAD"
-	]) !== defaultBranch) throw new Error(`The Context Tree checkout must be on the live default branch "${defaultBranch}".`);
-	requireGit(treePath, [
-		"fetch",
-		"origin",
-		defaultBranch
-	], true);
-	const baseSha = requireGit(treePath, ["rev-parse", `origin/${defaultBranch}`]);
-	const { taskBranch, worktreePath } = createIsolatedWorktree(treePath, baseSha);
+//#endregion
+//#region src/core/create.ts
+function projectName(canonicalRoot) {
+	const normalized = basename(canonicalRoot).toLowerCase().replace(/[^a-z\d._-]+/gu, "-").replace(/-{2,}/gu, "-").replace(/^[-.]+/u, "").replace(/[-.]+$/u, "").slice(0, 40);
+	return /^[a-z\d]/u.test(normalized) ? normalized : "project";
+}
+function existingCreateResult(canonical, destination, runner) {
 	return {
-		baseSha,
-		link: {
-			project: result.link.project,
-			tree: {
-				path: treePath,
-				repository: ownerRepository
-			}
-		},
-		defaultBranch,
+		branch: git(destination, [
+			"symbolic-ref",
+			"--short",
+			"HEAD"
+		], {
+			message: "Failed to resolve the managed tree branch.",
+			runner
+		}),
+		commitSha: git(destination, ["rev-parse", "HEAD"], {
+			message: "Failed to resolve the managed tree commit.",
+			runner
+		}),
+		created: false,
+		pointer: writeProjectPointer(canonical, destination),
 		schemaVersion: 1,
-		taskBranch,
-		worktreePath
+		title: readRootNode(destination).frontmatter.title,
+		treePath: destination
 	};
 }
-const DIFF_STATUS = {
-	A: "added",
-	D: "deleted",
-	M: "modified",
-	R: "renamed"
-};
-function changedFiles(root, base) {
-	const output = git(root, [
-		"diff",
-		"--name-status",
-		base
-	]);
-	const files = [];
-	for (const line of output.split("\n")) {
-		const match = /^([ADMR])\s+(.+)$/u.exec(line);
-		if (match === null) continue;
-		const status = DIFF_STATUS[match[1]];
-		if (status === void 0) continue;
-		files.push({
-			path: match[2] ?? "",
-			status
+/** Create and connect the project's uniquely named managed local Context Tree. */
+function createProject(projectPath, runner) {
+	const canonical = canonicalProjectRoot(projectPath, runner);
+	const name = treeNameSchema.parse(`${projectName(canonical)}-context-tree`);
+	const destination = join(managedTreesRoot(), name);
+	const current = findConnectionRecord(canonical, runner);
+	if (current !== void 0 && current.tree.path !== destination) throw new Error(`This project is already connected to a Context Tree at ${current.tree.path}; run context-tree connect ${name} to switch.`);
+	if (existsSync(destination)) {
+		const entry = lstatSync(destination);
+		if (entry.isSymbolicLink() || !entry.isDirectory() || current === void 0) throw new Error(`Managed Context Tree name ${name} is occupied; run context-tree connect ${name}.`);
+		return existingCreateResult(canonical, destination, runner);
+	}
+	mkdirSync(destination, { mode: 448 });
+	try {
+		const scaffold = scaffoldTree({
+			name,
+			path: destination,
+			runner
 		});
+		upsertConnection({
+			projectPath: canonical,
+			tree: {
+				kind: "local",
+				path: scaffold.root
+			}
+		}, runner);
+		return {
+			branch: scaffold.branch,
+			commitSha: scaffold.commit,
+			created: true,
+			pointer: writeProjectPointer(canonical, scaffold.root),
+			schemaVersion: 1,
+			title: name,
+			treePath: scaffold.root
+		};
+	} catch (error) {
+		rmSync(destination, {
+			force: true,
+			recursive: true
+		});
+		throw error;
 	}
-	const porcelain = git(root, [
-		"status",
-		"--porcelain",
-		"--untracked-files=all"
-	]);
-	for (const line of porcelain.split("\n")) {
-		const path = /^\?\?\s+(.+)$/u.exec(line)?.[1];
-		if (path !== void 0 && path.length > 0) files.push({
-			path,
-			status: "added"
+}
+//#endregion
+//#region src/core/install.ts
+/** Per-host configuration directory, relative to the home directory or to a project root. */
+const HOST_CONFIG_DIRECTORY = {
+	claude: ".claude",
+	codex: ".codex"
+};
+/** Every supported host keeps user skills in the same subdirectory of its configuration directory. */
+const SKILLS_DIRECTORY = "skills";
+/** Only directories carrying this prefix are ever replaced or removed. */
+const OWNED_SKILL_PREFIX = "context-tree-";
+function realHome() {
+	try {
+		return realpathSync(homedir());
+	} catch {
+		return homedir();
+	}
+}
+/** Create a directory below `root`, failing closed on symlinks and non-directories. */
+function ensureRealDirectory(root, segments) {
+	let current = root;
+	for (const segment of segments) {
+		current = join(current, segment);
+		const entry = lstatSync(current, { throwIfNoEntry: false });
+		if (entry === void 0) {
+			mkdirSync(current, { mode: 448 });
+			continue;
+		}
+		if (entry.isSymbolicLink() || !entry.isDirectory()) throw new Error(`Context Tree skill directory must be a real directory: ${current}`);
+	}
+	return current;
+}
+/** Copy a packaged skill tree, refusing to read or write through symlinks. Skills are never executable. */
+function copyRealTree(source, destination) {
+	const entry = lstatSync(source);
+	if (entry.isSymbolicLink()) throw new Error(`Refusing to install a symlinked skill entry: ${source}`);
+	if (entry.isDirectory()) {
+		mkdirSync(destination, {
+			mode: 448,
+			recursive: true
 		});
+		for (const child of readdirSync(source)) copyRealTree(join(source, child), join(destination, child));
+		return;
+	}
+	if (!entry.isFile()) throw new Error(`Refusing to install a non-regular skill entry: ${source}`);
+	copyFileSync(source, destination);
+	chmodSync(destination, 420);
+}
+/** Packaged skill directory names, e.g. `context-tree-read`. */
+function packagedSkillNames(skillsRoot) {
+	return readdirSync(skillsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && entry.name.startsWith(OWNED_SKILL_PREFIX)).map((entry) => entry.name).sort();
+}
+/** Resolve one host's destination, or the reason it was skipped. */
+function hostDestination(host, root, isProjectInstall) {
+	const configDirectory = HOST_CONFIG_DIRECTORY[host];
+	if (!isProjectInstall) {
+		const hostRoot = join(root, configDirectory);
+		const entry = lstatSync(hostRoot, { throwIfNoEntry: false });
+		if (entry === void 0) return { reason: `${hostRoot} does not exist; install ${host} first, then run context-tree install.` };
+		if (entry.isSymbolicLink() || !entry.isDirectory()) return { reason: `${hostRoot} is not a real directory.` };
 	}
-	return files;
+	return { destination: ensureRealDirectory(root, [configDirectory, SKILLS_DIRECTORY]) };
 }
-function inspectContextTreeDiff(treePath, base) {
-	const root = realpathSync(treePath);
-	const reference = base ?? "HEAD";
+/**
+* Copy the packaged skills into each requested host's skill directory.
+*
+* Existing `context-tree-*` directories are replaced; that is the upgrade path. Skill
+* directories the package does not own are never touched. A project install always
+* creates its target, because the caller named it.
+*/
+function installSkills(options = {}) {
+	const skillsRoot = resolvePackagedResource("skills");
+	const skills = packagedSkillNames(skillsRoot);
+	if (skills.length === 0) throw new Error("Packaged skills are missing; reinstall @first-tree-ai/context-tree.");
+	const hosts = options.hosts === void 0 || options.hosts.length === 0 ? SKILL_HOSTS : options.hosts;
+	const projectRoot = options.projectPath === void 0 ? void 0 : resolve(options.projectPath);
+	const root = projectRoot ?? realHome();
+	const installed = [];
+	const skipped = [];
+	for (const host of hosts) {
+		const resolved = hostDestination(host, root, projectRoot !== void 0);
+		if ("reason" in resolved) {
+			skipped.push({
+				host,
+				reason: resolved.reason
+			});
+			continue;
+		}
+		for (const skill of skills) {
+			const target = join(resolved.destination, skill);
+			if (lstatSync(target, { throwIfNoEntry: false }) !== void 0) rmSync(target, {
+				force: true,
+				recursive: true
+			});
+			copyRealTree(join(skillsRoot, skill), target);
+		}
+		installed.push({
+			host,
+			path: resolved.destination,
+			skills
+		});
+	}
 	return {
-		base: reference,
-		files: changedFiles(root, reference),
-		patch: git(root, ["diff", reference]),
+		installed,
 		schemaVersion: 1,
-		treePath: root
+		skipped,
+		version: readPackageVersion()
 	};
 }
 //#endregion
-//#region src/core/policy.ts
-function readContextTreePolicy() {
+//#region src/core/publish.ts
+function authenticatedAccount(runner) {
+	let login;
+	try {
+		login = gh([
+			"api",
+			"user",
+			"--jq",
+			".login"
+		], {
+			message: "GitHub account lookup failed.",
+			runner
+		});
+	} catch (error) {
+		if (error instanceof CommandError && /gh auth login|not logged|authentication failed|http 401|bad credentials/iu.test(error.stderr)) throw new ContextTreeError(CLI_ERROR_CODES.githubAuth, "GitHub authentication failed; run gh auth login before publishing.");
+		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub account lookup failed; publication did not start and must not be retried automatically.");
+	}
+	if (login.trim().length === 0) throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub account lookup returned no repository owner.");
+	return login.trim();
+}
+function classifyCreationFailure(stderr) {
+	if (/already exists/iu.test(stderr)) return new ContextTreeError(CLI_ERROR_CODES.repositoryExists, "A GitHub repository with this name already exists; choose an explicit OWNER/REPO override.");
+	return new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub repository creation has an uncertain or partial result; do not retry automatically.");
+}
+/**
+* Publish a clean, valid local tree as a private GitHub repository. The
+* default repository name derives from the authenticated account and managed
+* tree name; OWNER/REPO is accepted only as an explicit override. The initial
+* publication is one gh repo create operation, and the stored connection is
+* updated atomically to the published tree state.
+*/
+function publishProject(projectPath, options = {}, runner) {
+	const connection = resolveConnectionRecord(projectPath, runner);
+	const root = connection.tree.path;
+	if (connection.tree.kind === "github") throw new ContextTreeError(CLI_ERROR_CODES.failed, `The Context Tree is already published as ${connection.tree.repository}; writes publish new commits automatically.`);
+	if (optionalGit(root, [
+		"remote",
+		"get-url",
+		"origin"
+	], runner) !== void 0) throw new ContextTreeError(CLI_ERROR_CODES.failed, "A local Context Tree must not already have an origin before publication.");
+	const branch = git(root, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	], {
+		message: "Failed to resolve the checked-out branch.",
+		runner
+	});
+	const sha = git(root, ["rev-parse", "HEAD"], {
+		message: "Failed to resolve the Context Tree commit.",
+		runner
+	});
+	const repository = options.repository === void 0 ? `${authenticatedAccount(runner)}/${basename(root)}` : githubRepositoryIdentitySchema.parse(options.repository);
+	const url = canonicalGitHubRepositoryUrl(repository);
+	try {
+		gh([
+			"repo",
+			"create",
+			repository,
+			"--private",
+			"--source",
+			root,
+			"--remote",
+			"origin",
+			"--push"
+		], {
+			message: "GitHub repository creation failed.",
+			runner
+		});
+	} catch (error) {
+		if (error instanceof CommandError) throw classifyCreationFailure(error.stderr);
+		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "GitHub publication ended with an uncertain result.");
+	}
+	try {
+		updateConnectionTree(connection.projectPath, {
+			kind: "github",
+			path: root,
+			repository
+		}, runner);
+	} catch {
+		throw new ContextTreeError(CLI_ERROR_CODES.publishIncomplete, "The private repository was created, but updating the local connection failed.");
+	}
 	return {
-		content: readFileSync(resolvePackagedResource("policy", "context-tree-policy.md"), "utf8"),
-		schemaVersion: 1
+		branch,
+		repository,
+		schemaVersion: 1,
+		sha,
+		url
 	};
 }
 //#endregion
@@ -25724,98 +26194,271 @@ function readTree(treePath, path) {
 	};
 }
 //#endregion
-//#region src/core/scaffold.ts
-function template(name, values) {
-	let result = readFileSync(resolvePackagedResource("templates", name), "utf8");
-	for (const [key, value] of Object.entries(values)) result = result.replaceAll(`{{${key}}}`, value);
-	return result;
-}
-function initializeGitRepository(root, repository) {
-	const initialized = spawnSync("git", [
-		"init",
-		"--quiet",
-		root
-	], { stdio: "ignore" });
-	if (initialized.error !== void 0 || initialized.status !== 0) throw new Error("Failed to initialize Git repository.");
-	const branch = spawnSync("git", [
-		"-C",
-		root,
+//#region src/core/sync.ts
+/**
+* Local trees report their checked-out state without network access. GitHub
+* trees fast-forward the exact checked-out branch once, then revalidate.
+*/
+function syncProject(projectPath, runner) {
+	const connection = resolveConnectionRecord(projectPath, runner);
+	const root = connection.tree.path;
+	const branch = git(root, [
 		"symbolic-ref",
 		"--short",
 		"HEAD"
 	], {
-		encoding: "utf8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"ignore"
-		]
+		message: "Failed to resolve the checked-out branch.",
+		runner
 	});
-	const name = branch.stdout.replace(/\r?\n$/u, "");
-	if (branch.error !== void 0 || branch.status !== 0 || name.length === 0) throw new Error("Failed to resolve the initial Git branch during repository initialization.");
-	const remote = spawnSync("git", [
-		"-C",
-		root,
-		"remote",
-		"add",
-		"origin",
-		canonicalGitHubRepositoryUrl(repository)
-	], { stdio: "ignore" });
-	if (remote.error !== void 0 || remote.status !== 0) throw new Error("Failed to configure the credential-free Context Tree origin.");
-	return name;
-}
-function scaffoldTree(options) {
-	const title = parseGitHubRepositoryIdentity(options.repository);
-	const root = resolve(options.path);
-	const destination = lstatSync(root, { throwIfNoEntry: false });
-	if (destination !== void 0) {
-		if (destination.isSymbolicLink() || !destination.isDirectory()) throw new Error(`Refusing to scaffold into a symlink or non-directory destination: ${root}`);
-		if (readdirSync(root).length > 0) throw new Error(`Refusing to scaffold into a non-empty directory: ${root}`);
+	if (connection.tree.kind === "github") {
+		git(root, [
+			"pull",
+			"--ff-only",
+			"origin",
+			branch
+		], {
+			message: "Fast-forwarding the Context Tree failed.",
+			runner
+		});
+		validateStoredTreeState(connection.tree, runner);
 	}
-	const initialBranch = initializeGitRepository(root, options.repository);
-	const values = {
-		branchJson: JSON.stringify(initialBranch),
-		packageVersion: readPackageVersion(),
-		title,
-		titleJson: JSON.stringify(title)
+	return {
+		branch,
+		schemaVersion: 1,
+		sha: git(root, ["rev-parse", "HEAD"], {
+			message: "Failed to resolve the Context Tree commit.",
+			runner
+		}),
+		tree: connection.tree
 	};
-	const regularFiles = [
-		["NODE.md", "root-node.md"],
-		["AGENTS.md", "AGENTS.md"],
-		[".github/workflows/validate-context-tree.yml", "validate-context-tree.yml"]
-	];
-	const files = [
-		"NODE.md",
-		"AGENTS.md",
-		"CLAUDE.md",
-		".github/workflows/validate-context-tree.yml"
-	];
-	for (const [relativePath, source] of regularFiles.slice(0, 2)) {
-		const path = join(root, relativePath);
-		mkdirSync(dirname(path), { recursive: true });
-		writeFileSync(path, template(source, values), {
-			encoding: "utf8",
-			flag: "wx",
-			mode: 420
+}
+//#endregion
+//#region src/core/write.ts
+const TASK_BRANCH_PREFIX = "context-tree/write/";
+/** A prepared worktree left untouched for longer than this is treated as abandoned. */
+const ABANDONED_WRITE_AGE_MS = 1440 * 60 * 1e3;
+/** Synchronize first, then create an isolated task worktree at the exact HEAD. */
+function prepareContextWrite(projectPath, runner) {
+	const synchronized = syncProject(projectPath, runner);
+	const root = synchronized.tree.path;
+	reclaimAbandonedWrites(root, synchronized.branch, runner);
+	const destination = mkdtempSync(join(tmpdir(), "context-tree-write-"));
+	const taskBranch = `${TASK_BRANCH_PREFIX}${basename(destination)}`;
+	try {
+		git(root, [
+			"worktree",
+			"add",
+			"--quiet",
+			"-b",
+			taskBranch,
+			destination,
+			synchronized.sha
+		], {
+			message: "Creating the isolated write worktree failed.",
+			runner
+		});
+		return {
+			schemaVersion: 1,
+			worktreePath: realDirectoryWithoutSymlinks(destination, "Write worktree")
+		};
+	} catch (error) {
+		rmSync(destination, {
+			force: true,
+			recursive: true
 		});
+		throw error;
 	}
-	symlinkSync("AGENTS.md", join(root, "CLAUDE.md"), "file");
-	for (const [relativePath, source] of regularFiles.slice(2)) {
-		const path = join(root, relativePath);
-		mkdirSync(dirname(path), { recursive: true });
-		writeFileSync(path, template(source, values), {
-			encoding: "utf8",
-			flag: "wx",
-			mode: 420
+}
+/** Commit every pending change, then fast-forward locally or push once. */
+function finishContextWrite(options, runner) {
+	const connection = resolveConnectionRecord(options.projectPath, runner);
+	const root = connection.tree.path;
+	const { taskBranch, worktreePath } = validatePreparedWorktree(root, options.worktreePath, runner);
+	const branch = git(root, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	], {
+		message: "Failed to resolve the connected checkout branch.",
+		runner
+	});
+	if (git(worktreePath, [
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
+	], {
+		message: "Failed to inspect the prepared worktree.",
+		runner
+	}).length === 0) throw new Error("The prepared worktree has no pending changes.");
+	if (!verifyTree(worktreePath).ok) throw new ContextTreeError(CLI_ERROR_CODES.invalidTree, `Refusing to commit an invalid Context Tree; run context-tree verify --tree-path ${worktreePath}.`);
+	git(worktreePath, ["add", "--all"], {
+		message: "Staging the Context Tree changes failed.",
+		runner
+	});
+	git(worktreePath, [
+		"-c",
+		"commit.gpgsign=false",
+		"commit",
+		"--quiet",
+		"-m",
+		options.message
+	], {
+		message: "Committing the Context Tree changes failed.",
+		runner
+	});
+	const sha = git(worktreePath, ["rev-parse", "HEAD"], {
+		message: "Failed to resolve the write commit.",
+		runner
+	});
+	try {
+		if (connection.tree.kind === "local") git(root, [
+			"merge",
+			"--ff-only",
+			taskBranch
+		], {
+			message: "Fast-forwarding the local Context Tree failed.",
+			runner
 		});
+		else git(worktreePath, [
+			"push",
+			"origin",
+			`HEAD:refs/heads/${branch}`
+		], {
+			message: "Publishing the Context Tree write failed.",
+			runner
+		});
+	} catch (error) {
+		if (isNonFastForward(error)) throw new ContextTreeError(CLI_ERROR_CODES.writeOutdated, `The Context Tree advanced; the prepared worktree is preserved at ${worktreePath}.`);
+		throw error;
 	}
+	removeWorktree(root, worktreePath, taskBranch, runner);
 	return {
-		files,
-		root,
+		branch,
 		schemaVersion: 1,
-		verification: verifyTree(root)
+		sha
 	};
 }
+function gitCommonDirectory(root, runner) {
+	const value = git(root, ["rev-parse", "--git-common-dir"], {
+		message: "Failed to resolve the Git common directory.",
+		runner
+	});
+	return realDirectoryWithoutSymlinks(isAbsolute(value) ? value : resolve(root, value), "Git common directory");
+}
+function validatePreparedWorktree(root, suppliedPath, runner) {
+	const worktreePath = realDirectoryWithoutSymlinks(suppliedPath, "Prepared worktree");
+	if (gitCommonDirectory(worktreePath, runner) !== gitCommonDirectory(root, runner)) throw new Error("The prepared worktree does not belong to the connected Context Tree.");
+	const taskBranch = git(worktreePath, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	], {
+		message: "Failed to resolve the worktree branch.",
+		runner
+	});
+	if (!taskBranch.startsWith(TASK_BRANCH_PREFIX)) throw new Error("The prepared worktree is not on a reserved Context Tree write branch.");
+	return {
+		taskBranch,
+		worktreePath
+	};
+}
+function isNonFastForward(error) {
+	return error instanceof CommandError && /non-fast-forward|fetch first|tip of your current branch is behind|not possible to fast-forward|diverg/i.test(error.stderr);
+}
+function removeWorktree(root, worktreePath, taskBranch, runner) {
+	git(root, [
+		"worktree",
+		"remove",
+		worktreePath
+	], {
+		message: "Removing the write worktree failed.",
+		runner
+	});
+	git(root, [
+		"branch",
+		"-D",
+		taskBranch
+	], {
+		message: "Deleting the write branch failed.",
+		runner
+	});
+}
+/** Map every reserved write branch that still has a registered worktree to its path. */
+function listWriteWorktrees(root, runner) {
+	const paths = /* @__PURE__ */ new Map();
+	const output = optionalGit(root, [
+		"worktree",
+		"list",
+		"--porcelain"
+	], runner);
+	if (output === void 0) return paths;
+	let path;
+	for (const record of output.split("\n")) {
+		if (record.startsWith("worktree ")) {
+			path = record.slice(9).trim();
+			continue;
+		}
+		if (!record.startsWith("branch refs/heads/")) continue;
+		const branch = record.slice(18).trim();
+		if (path !== void 0 && branch.startsWith(TASK_BRANCH_PREFIX)) paths.set(branch, path);
+	}
+	return paths;
+}
+function millisecondsSinceModification(path) {
+	try {
+		return Date.now() - statSync(path).mtimeMs;
+	} catch {
+		return;
+	}
+}
+/**
+* A preparation is abandoned only when it carries no commit the connected
+* checkout lacks, has no pending edits, and has gone untouched. Every unknown
+* answer preserves the worktree, so a `WRITE_OUTDATED` commit awaiting its
+* retry and a concurrent preparation both survive.
+*/
+function isAbandonedWrite(root, branch, checkoutBranch, path, runner) {
+	if (optionalGit(root, [
+		"rev-list",
+		"--count",
+		branch,
+		"--not",
+		checkoutBranch
+	], runner) !== "0") return false;
+	if (path === void 0) return true;
+	const age = millisecondsSinceModification(path);
+	if (age === void 0 || age < ABANDONED_WRITE_AGE_MS) return false;
+	return optionalGit(path, [
+		"status",
+		"--porcelain",
+		"--untracked-files=all"
+	], runner) === "";
+}
+/** Reclaim earlier preparations that were never finished. Every step is best effort. */
+function reclaimAbandonedWrites(root, checkoutBranch, runner) {
+	optionalGit(root, ["worktree", "prune"], runner);
+	const paths = listWriteWorktrees(root, runner);
+	const branches = optionalGit(root, [
+		"for-each-ref",
+		"--format=%(refname:short)",
+		`refs/heads/${TASK_BRANCH_PREFIX}`
+	], runner);
+	if (branches === void 0) return;
+	for (const branch of branches.split("\n").filter((value) => value.length > 0)) {
+		const path = paths.get(branch);
+		if (!isAbandonedWrite(root, branch, checkoutBranch, path, runner)) continue;
+		if (path !== void 0) optionalGit(root, [
+			"worktree",
+			"remove",
+			path
+		], runner);
+		optionalGit(root, [
+			"branch",
+			"-D",
+			branch
+		], runner);
+	}
+}
 //#endregion
 //#region src/cli/api.ts
 const defaultIo = {
@@ -25826,57 +26469,72 @@ function line(io, value) {
 	io.stdout(`${value}\n`);
 }
 function createContextTreeCli(io = defaultIo) {
-	const program = new Command().name("context-tree").description("Portable tools for linking, resolving, scaffolding, reading, and validating Context Trees.").addHelpCommand(false).version(readPackageVersion()).exitOverride().configureOutput({
+	const program = new Command().name("context-tree").description("Create, connect, list, read, write, and publish Context Trees.").addHelpCommand(false).version(readPackageVersion()).exitOverride().configureOutput({
 		writeErr: () => void 0,
 		writeOut: io.stdout
 	});
-	program.command("link").description("Link a project to a verified Context Tree checkout.").requiredOption("--project-path <path>", "Git project or non-Git project directory").requiredOption("--tree-path <path>", "Context Tree checkout").action((options) => {
-		line(io, JSON.stringify(linkProject(resolve(io.cwd(), options.projectPath), resolve(io.cwd(), options.treePath))));
+	program.command("create").description("Create and connect one uniquely named managed Context Tree for the current project.").option("--project-path <path>", "project directory", ".").action((options) => {
+		line(io, JSON.stringify(createProject(resolve(io.cwd(), options.projectPath))));
+	});
+	program.command("connect").description("Connect the project by managed tree name, GitHub OWNER/REPO, or exact disk path.").argument("[name-or-repository]", "managed tree name or GitHub OWNER/REPO").option("--project-path <path>", "project directory", ".").option("--tree-path <path>", "exact Context Tree Git root to connect in place").action((target, options) => {
+		const projectPath = resolve(io.cwd(), options.projectPath);
+		if (target !== void 0 && options.treePath !== void 0) throw new Error("Connect requires exactly one of a name/repository or --tree-path.");
+		if (target !== void 0) {
+			line(io, JSON.stringify(connectProject({
+				projectPath,
+				target
+			})));
+			return;
+		}
+		if (options.treePath !== void 0) {
+			line(io, JSON.stringify(connectProject({
+				projectPath,
+				treePath: resolve(io.cwd(), options.treePath)
+			})));
+			return;
+		}
+		throw new Error("Connect requires a managed tree name, GitHub OWNER/REPO, or --tree-path.");
 	});
-	program.command("policy").description("Print the canonical packaged Context Tree policy.").action(() => {
-		line(io, JSON.stringify(readContextTreePolicy()));
+	program.command("list").description("List valid clean managed Context Trees.").action(() => {
+		line(io, JSON.stringify(listManagedTrees()));
 	});
-	program.command("resolve").description("Resolve the linked Context Tree for a project.").option("--project-path <path>", "Git project or non-Git project directory", ".").action((options) => {
-		line(io, JSON.stringify(resolveLink(resolve(io.cwd(), options.projectPath))));
+	program.command("resolve").description("Resolve the connected Context Tree for a project.").option("--project-path <path>", "project directory", ".").action((options) => {
+		line(io, JSON.stringify(resolveConnection(resolve(io.cwd(), options.projectPath))));
 	});
-	program.command("refresh").description("Refresh a linked Context Tree to its live default branch.").option("--project-path <path>", "Git Tree or non-Git project directory", ".").action((options) => {
-		line(io, JSON.stringify(refreshProject(resolve(io.cwd(), options.projectPath))));
+	program.command("sync").description("Synchronize the connected Context Tree for a project.").option("--project-path <path>", "project directory", ".").action((options) => {
+		line(io, JSON.stringify(syncProject(resolve(io.cwd(), options.projectPath))));
 	});
-	program.command("stage").description("Prepare an isolated Context Tree worktree at the live default branch for a write.").option("--project-path <path>", "Git Tree or non-Git project directory", ".").action((options) => {
-		line(io, JSON.stringify(stageContextWrite(resolve(io.cwd(), options.projectPath))));
+	program.command("prepare-write").description("Prepare an isolated Context Tree worktree for a write.").option("--project-path <path>", "project directory", ".").action((options) => {
+		line(io, JSON.stringify(prepareContextWrite(resolve(io.cwd(), options.projectPath))));
 	});
-	program.command("diff").description("Inspect the pending changes of a prepared Context Tree worktree.").argument("[tree-path]", "Context Tree root", ".").option("--base <ref>", "Base ref or commit to diff against (default HEAD)").action((treePath, options) => {
-		line(io, JSON.stringify(inspectContextTreeDiff(resolve(io.cwd(), treePath), options.base)));
+	program.command("finish-write").description("Commit all pending changes in a prepared worktree and publish them.").requiredOption("--worktree-path <path>", "prepared worktree path").requiredOption("--message <message>", "commit message for the pending changes").option("--project-path <path>", "project directory", ".").action((options) => {
+		line(io, JSON.stringify(finishContextWrite({
+			message: options.message,
+			projectPath: resolve(io.cwd(), options.projectPath),
+			worktreePath: resolve(io.cwd(), options.worktreePath)
+		})));
 	});
-	program.command("init").description("Scaffold a new Context Tree.").requiredOption("--repository <owner/repo>", "GitHub repository identity").option("--tree-path <path>", "destination directory").action((options) => {
-		const repositoryName = parseGitHubRepositoryIdentity(options.repository);
-		const projectPath = resolve(io.cwd());
-		let project;
-		try {
-			project = identifyProject(projectPath);
-		} catch {}
-		const result = scaffoldTree({
-			path: resolve(io.cwd(), options.treePath ?? repositoryName),
-			repository: options.repository
-		});
-		if (project !== void 0) linkScaffoldedProject(projectPath, result.root);
-		line(io, JSON.stringify(result));
+	program.command("publish").description("Publish the local tree as a new private GitHub repository.").argument("[repository]", "GitHub OWNER/REPO override; defaults to the authenticated account and tree name").option("--project-path <path>", "project directory", ".").action((repository, options) => {
+		line(io, JSON.stringify(publishProject(resolve(io.cwd(), options.projectPath), { repository })));
 	});
 	program.command("read").description("Read an indexed Context Tree directory or Markdown leaf.").argument("[path]", "tree-relative path", ".").option("--tree-path <path>", "Context Tree root", ".").action((path, options) => {
-		if (!verifyTree(resolve(io.cwd(), options.treePath)).ok) throw new Error("Refusing to read an invalid Context Tree; run context-tree verify.");
-		const result = readTree(resolve(io.cwd(), options.treePath), path);
-		line(io, JSON.stringify(result));
+		const treePath = resolve(io.cwd(), options.treePath);
+		if (!verifyTree(treePath).ok) throw new ContextTreeError(CLI_ERROR_CODES.invalidTree, `Refusing to read an invalid Context Tree; run context-tree verify --tree-path ${treePath}.`);
+		line(io, JSON.stringify(readTree(treePath, path)));
 	});
 	program.command("verify").description("Validate Context Tree structure and safety.").option("--tree-path <path>", "Context Tree root", ".").action((options) => {
 		const result = verifyTree(resolve(io.cwd(), options.treePath));
 		line(io, JSON.stringify(result));
 		if (!result.ok) process.exitCode = 1;
 	});
+	program.command("install").description("Install the packaged Context Tree skills into each agent's skill directory.").option("--host <host>", "restrict to one host: claude, codex, or all", "all").option("--project <path>", "install below this project root instead of the home directory").action((options) => {
+		const request = {};
+		if (options.host !== "all") request.hosts = [skillHostSchema.parse(options.host)];
+		if (options.project !== void 0) request.projectPath = resolve(io.cwd(), options.project);
+		line(io, JSON.stringify(installSkills(request)));
+	});
 	return program;
 }
-function sanitizeError(message) {
-	return message.replace(/(?:https?|ssh):\/\/[^\s/@]+@/giu, "<redacted>@");
-}
 async function runContextTreeCli(argv = process.argv, io = defaultIo) {
 	const program = createContextTreeCli(io);
 	try {
@@ -25886,8 +26544,8 @@ async function runContextTreeCli(argv = process.argv, io = defaultIo) {
 		if (error instanceof CommanderError && error.exitCode === 0) return 0;
 		const envelope = {
 			error: {
-				code: error instanceof LinkError ? error.code : CLI_ERROR_CODES.failed,
-				message: sanitizeError(error instanceof Error ? error.message : String(error))
+				code: error instanceof ContextTreeError ? error.code : CLI_ERROR_CODES.failed,
+				message: sanitizeCommandOutput(error instanceof Error ? error.message : String(error))
 			},
 			ok: false,
 			schemaVersion: 1