@first-tree-ai/context-tree 0.1.5 → 0.1.7-alpha.202609010710

package/dist/index.mjs

@@ -1,57 +1,116 @@
-import { A as isRecord, C as githubRepositoryIdentitySchema, S as credentialFreeRepositoryUrlSchema, f as contextTreeLinkSchema, i as VALIDATION_CODES, k as parseMarkdownFrontmatter, t as CLI_ERROR_CODES, w as parseContextTreeRootNode } from "./schemas-BWM6Q6iz.mjs";
-import { spawnSync } from "node:child_process";
-import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { A as treeNameSchema, C as credentialFreeRepositoryUrlSchema, F as isRecord, O as parseContextTreeRootNode, P as parseMarkdownFrontmatter, T as githubRepositoryIdentitySchema, b as contextTreeStateSchema, f as contextTreeConnectionSchema, i as VALIDATION_CODES, t as CLI_ERROR_CODES } from "./schemas-DKHE1sWt.mjs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, parse, posix, relative, resolve, sep } from "node:path";
 import { z } from "zod";
+import { spawnSync } from "node:child_process";
 import { fromMarkdown } from "mdast-util-from-markdown";
 import { fileURLToPath } from "node:url";
-//#region src/core/internal/filesystem.ts
-function readUtf8File(path) {
-	return new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path));
-}
+//#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/github-repository.ts
-function parseGitHubRepositoryIdentity(repository) {
-	githubRepositoryIdentitySchema.parse(repository);
-	return repository.split("/")[1] ?? "";
+//#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 : ""
+	};
 }
-function repositoryIdentityFromGitHubUrl(repositoryUrl) {
-	try {
-		credentialFreeRepositoryUrlSchema.parse(repositoryUrl);
-	} catch {
-		throw new Error("Context Tree origin must be a safe credential-free github.com repository URL.");
+/** 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;
 	}
-	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;
+};
+/** 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) {
-	parseGitHubRepositoryIdentity(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) {
@@ -64,10 +123,42 @@ function resolveTreeRoot(path) {
 	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/filesystem.ts
+function readUtf8File(path) {
+	return new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(path));
+}
+//#endregion
 //#region src/core/internal/content-class.ts
 const GENERATED_DIRECTORY_NAMES = new Set([
 	"node_modules",
@@ -473,407 +564,326 @@ function verifyTree(treePath) {
 	};
 }
 //#endregion
-//#region src/core/links.ts
-const contextTreeLinksFileSchema = z.object({
-	links: z.array(contextTreeLinkSchema),
-	schemaVersion: z.literal(1)
-}).strict();
-var LinkError = class extends Error {
-	code;
-	constructor(code, message) {
-		super(message);
-		this.name = "LinkError";
-		this.code = code;
-	}
-};
-function git$1(path, args) {
-	const result = spawnSync("git", [
-		"-C",
-		path,
-		...args
+//#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;
+}
+/** Parse the root NODE.md, refusing symlinked or irregular files. */
+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));
+}
+/**
+* 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"
 	], {
-		encoding: "utf8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"ignore"
-		]
-	});
-	if (result.error !== void 0 || result.status !== 0) return void 0;
-	return result.stdout.replace(/\r?\n$/u, "");
+		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;
 }
-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;
+/** 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
+	};
 }
-function normalizeRepositoryUrl(repositoryUrl) {
+//#endregion
+//#region src/core/connections.ts
+const connectionsFileSchema = z.object({
+	connections: z.array(contextTreeConnectionSchema),
+	schemaVersion: z.literal(1)
+}).strict();
+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() {
 	try {
-		credentialFreeRepositoryUrlSchema.parse(repositoryUrl);
+		return realpathSync(homedir());
 	} catch {
-		throw new Error("Git origin must be a canonical credential-free repository URL.");
+		return homedir();
 	}
-	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);
 }
-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."))
-	};
+/** Create a managed application directory below the home directory, failing closed on symlinks. */
+function ensureManagedDirectory(...segments) {
+	let current = realHome();
+	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}`);
+	}
+	return current;
 }
-function linksPath() {
-	return join(homedir(), ".context-tree", "connections.json");
+/** The managed namespace without creating it; listing must not create an absent directory. */
+function managedTreesPath() {
+	return join(realHome(), ".context-tree", "trees");
 }
-function emptyLinks() {
-	return {
-		links: [],
-		schemaVersion: 1
-	};
+function connectionsPath() {
+	return join(realHome(), ".context-tree", "connections.json");
 }
-function loadLinks(required) {
-	const path = linksPath();
+function managedTreesRoot() {
+	return ensureManagedDirectory(".context-tree", "trees");
+}
+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;
-}
-function checkoutRepository(root) {
-	return repositoryIdentityFromGitHubUrl(requireGit$1(root, [
-		"remote",
-		"get-url",
-		"origin"
-	], "Context Tree checkout must have an origin remote."));
-}
-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;
+	try {
+		renameSync(temporary, path);
+		chmodSync(path, 384);
+	} finally {
+		rmSync(temporary, { force: true });
 	}
-	throw new Error("Context Tree checkout must be clean.");
 }
-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));
+/** 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 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.");
-	return {
-		path: root,
-		repository
-	};
+function isManagedName(value) {
+	return treeNameSchema.safeParse(value).success && value === value.toLowerCase();
 }
-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 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 liveStoredCheckout(link) {
-	try {
-		const path = exactCheckoutRoot(link.tree.path);
-		return {
-			path,
-			repository: checkoutRepository(path)
-		};
-	} catch {
-		return;
-	}
+function managedName(value) {
+	if (!isManagedName(value)) throw new Error(`Managed Context Tree names must be safe lowercase path segments: ${value}`);
+	return value;
 }
-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
+/** 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: []
 	};
-	saveLinks({
-		links: [...stored.links.filter((candidate) => !sameProject(candidate.project, project)), link],
-		schemaVersion: 1
-	});
+	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 {
-		link,
-		schemaVersion: 1
+		schemaVersion: 1,
+		trees
 	};
 }
-function linkProject(projectPath, treePath) {
-	return linkWithMode(projectPath, treePath, "link");
+function findConnectionRecord(projectPath, runner) {
+	return singleConnection(loadConnections(false), canonicalProjectRoot(projectPath, runner));
 }
-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.");
+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 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 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);
 		return {
-			link: {
-				project: link.project,
-				tree: {
-					path: root,
-					repository
-				}
-			},
-			schemaVersion: 1
+			projectPath: connection.projectPath,
+			tree: validateManagedTreeState(connection.tree, runner)
 		};
 	} 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);
+		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}`);
 	}
 }
-//#endregion
-//#region src/core/live.ts
-function git(root, args) {
-	const result = spawnSync("git", [
-		"-C",
-		root,
-		...args
-	], {
-		encoding: "utf8",
-		stdio: [
-			"ignore",
-			"pipe",
-			"ignore"
-		]
-	});
-	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, [
-		"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"]);
+function resolveConnection(projectPath, runner) {
 	return {
-		link: {
-			...result.link,
-			tree: {
-				...result.link.tree,
-				path: realpathSync(root)
-			}
-		},
-		defaultBranch,
-		refreshed: before !== after,
 		schemaVersion: 1,
-		sha: after
+		tree: resolveConnectionRecord(projectPath, runner).tree
 	};
 }
-function createIsolatedWorktree(treePath, baseSha) {
-	const destination = mkdtempSync(join(tmpdir(), "context-tree-stage-"));
-	const taskBranch = `context-tree/write/${basename(destination)}`;
-	git(treePath, [
-		"worktree",
-		"add",
-		"-b",
-		taskBranch,
-		destination,
-		baseSha
-	]);
+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 {
-		taskBranch,
-		worktreePath: realpathSync(destination)
+		schemaVersion: 1,
+		tree: record.tree
 	};
 }
-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);
+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 {
-		baseSha,
-		link: {
-			project: result.link.project,
-			tree: {
-				path: treePath,
-				repository: ownerRepository
-			}
-		},
-		defaultBranch,
-		schemaVersion: 1,
-		taskBranch,
-		worktreePath
+		kind: "github",
+		path: root,
+		repository: gitHubRepositoryFromOriginUrl(origin)
 	};
 }
-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
-		});
+function sameRepository(left, right) {
+	return left.toLowerCase() === right.toLowerCase();
+}
+/** 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.`);
+}
+/**
+* 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) {
+	if ("treePath" in options) {
+		const tree = classifyCheckout(options.treePath, runner);
+		return upsertConnection({
+			projectPath: options.projectPath,
+			tree
+		}, runner);
 	}
-	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"
+	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);
+		const tree = classifyCheckout(destination, runner);
+		return upsertConnection({
+			projectPath: options.projectPath,
+			tree
+		}, 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 upsertConnection({
+			projectPath: options.projectPath,
+			tree
+		}, runner);
+	}
+	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 upsertConnection({
+			projectPath: options.projectPath,
+			tree
+		}, runner);
+	} catch (error) {
+		rmSync(destination, {
+			force: true,
+			recursive: true
 		});
+		throw error;
 	}
-	return files;
-}
-function inspectContextTreeDiff(treePath, base) {
-	const root = realpathSync(treePath);
-	const reference = base ?? "HEAD";
-	return {
-		base: reference,
-		files: changedFiles(root, reference),
-		patch: git(root, ["diff", reference]),
-		schemaVersion: 1,
-		treePath: root
-	};
 }
 //#endregion
 //#region src/core/internal/packaged-resource.ts
@@ -913,6 +923,173 @@ function readPackageVersion() {
 	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
+	], {
+		message: "Failed to initialize Git repository.",
+		runner
+	});
+	return git(root, [
+		"symbolic-ref",
+		"--short",
+		"HEAD"
+	], {
+		message: "Failed to resolve the initial Git branch during repository initialization.",
+		runner
+	});
+}
+function commitScaffold(root, runner) {
+	for (const file of SCAFFOLD_FILES) git(root, [
+		"add",
+		"--",
+		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 {
+		branch: initialBranch,
+		commit: commitScaffold(root, options.runner),
+		root
+	};
+}
+//#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(destination, runner) {
+	return {
+		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,
+		schemaVersion: 1,
+		title: parseRootNode(destination).frontmatter.title,
+		treePath: destination
+	};
+}
+/** 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(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,
+			schemaVersion: 1,
+			title: name,
+			treePath: scaffold.root
+		};
+	} catch (error) {
+		rmSync(destination, {
+			force: true,
+			recursive: true
+		});
+		throw error;
+	}
+}
+//#endregion
 //#region src/core/policy.ts
 function readContextTreePolicy() {
 	return {
@@ -921,6 +1098,97 @@ function readContextTreePolicy() {
 	};
 }
 //#endregion
+//#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 {
+		branch,
+		repository,
+		schemaVersion: 1,
+		sha,
+		url
+	};
+}
+//#endregion
 //#region src/core/read.ts
 function normalizeTreeTarget(value) {
 	if (!value || value === ".") return "";
@@ -991,97 +1259,191 @@ 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/";
+/** 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;
+	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
+	});
+}
 //#endregion
-export { inspectContextTreeDiff, linkProject, readContextTreePolicy, readTree, refreshProject, resolveLink, scaffoldTree, stageContextWrite, verifyTree };
+export { connectProject, createProject, finishContextWrite, listManagedTrees, prepareContextWrite, publishProject, readContextTreePolicy, readTree, resolveConnection, syncProject, verifyTree };