@appsoftwareltd/etherpk-mcp 0.14.1 → 0.16.0

package/dist/main.js

@@ -627,8 +627,8 @@ var ASSET_CHUNK_PLAINTEXT_BYTES = 4194304;
 function assetChunkCount(size) {
 	return Math.max(1, Math.ceil(size / ASSET_CHUNK_PLAINTEXT_BYTES));
 }
-var DAY = 864e5;
-365 * DAY, 30 * DAY, 7 * DAY;
+var DAY$1 = 864e5;
+365 * DAY$1, 30 * DAY$1, 7 * DAY$1;
 /** Whether `text` is a short link a Sync Server opens: one of Google's share links. */
 function isShortMapLink(text) {
 	let url;
@@ -717,7 +717,7 @@ function looksLikeAgentSetupCode(value) {
 }
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.14.1",
+	version: "0.16.0",
 	license: "Elastic-2.0",
 	description: "EtherPK Headless Client: an MCP server over a synced knowledge graph, run beside the agent on the user's own machine.",
 	type: "module",
@@ -863,7 +863,7 @@ function fromBase64Url(text) {
 * is indistinguishable from random, so the server can tell two assets in *one* graph are
 * identical and nothing more; the secret is per graph, so nothing compares across graphs.
 */
-var INFO = "etherpk/asset-dedup/v1";
+var INFO$1 = "etherpk/asset-dedup/v1";
 /** The graph's dedup secret (32 bytes) for its newest epoch. Derive once per epoch. */
 async function deriveAssetDedupSecret(keyring) {
 	const newest = keyring.epochs.at(-1);
@@ -873,7 +873,7 @@ async function deriveAssetDedupSecret(keyring) {
 		name: "HKDF",
 		hash: "SHA-256",
 		salt: utf8(keyring.graphId),
-		info: utf8(INFO)
+		info: utf8(INFO$1)
 	}, ikm, 256);
 	return new Uint8Array(bits);
 }
@@ -1542,6 +1542,50 @@ async function openVault(envelope, key) {
 	throw new EnvelopeError(`unexpected vault envelope kind ${envelope[1] ?? "none"}`);
 }
 contextAad("settings-vault", "v1");
+//#endregion
+//#region ../client/src/lib/crypto/journal-doc-id.ts
+/**
+* The **journal document id** (ADR 0157): a [[Journal Entry]]'s document id, derived from its day,
+* so two devices that start the same day before they hear of each other write into one document
+* and the CRDT merges their text, instead of leaving two documents behind one name.
+*
+*   secret = HKDF-SHA-256(ikm = epoch 1 key, salt = graph id, info = 'etherpk/journal-doc-id/v1')
+*   id     = HMAC-SHA-256(secret, 'YYYY-MM-DD'), first 128 bits, as a version 8 UUID
+*
+* The **epoch 1** key is the input, never the newest (unlike the asset dedup token): the id must
+* not change when the graph moves to a new Graph Key epoch (ADR 0127), or a day started before a
+* rotation and the same day started after it would get two documents. Every member holds every
+* epoch, so every member derives the same id. The server sees document ids already, and without
+* the key an id is indistinguishable from a random one, so it learns no day from it.
+*/
+var INFO = "etherpk/journal-doc-id/v1";
+var DAY = /^\d{4}-\d{2}-\d{2}$/;
+/** The graph's journal id secret (32 bytes). It never changes, so derive it once per session. */
+async function deriveJournalIdSecret(keyring) {
+	const first = keyForEpoch(keyring, 1);
+	if (!first) throw new Error("deriveJournalIdSecret: keyring has no epoch 1 key");
+	const ikm = await crypto.subtle.importKey("raw", first, "HKDF", false, ["deriveBits"]);
+	const bits = await crypto.subtle.deriveBits({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: utf8(keyring.graphId),
+		info: utf8(INFO)
+	}, ikm, 256);
+	return new Uint8Array(bits);
+}
+/** The document id of the journal entry for `day` (`YYYY-MM-DD`), under the graph's secret. */
+async function journalDocId(secret, day) {
+	if (!DAY.test(day)) throw new Error(`journalDocId: "${day}" is not a calendar day`);
+	const key = await crypto.subtle.importKey("raw", secret, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const bytes = new Uint8Array(await crypto.subtle.sign("HMAC", key, utf8(day))).slice(0, 16);
+	bytes[6] = bytes[6] & 15 | 128;
+	bytes[8] = bytes[8] & 63 | 128;
+	const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
 var PAD_TO = 64;
 var LENGTH_PREFIX = 2;
 function graphNameAad(graphId) {
@@ -4201,8 +4245,8 @@ function parseBlocks(markdown) {
 * does.
 */
 /** An extension's id or a name under it: lowercase letters, digits and hyphens, from a letter. */
-var NAME = "[a-z][a-z0-9-]*";
-var EXTENSION_FENCE_INFO = new RegExp(`^${NAME}\\.${NAME}$`);
+var NAME$1 = "[a-z][a-z0-9-]*";
+var EXTENSION_FENCE_INFO = new RegExp(`^${NAME$1}\\.${NAME$1}$`);
 /** Whether an info word names an Extension Fence: an extension's id, a dot and a name. */
 function isExtensionFenceInfo(info) {
 	return EXTENSION_FENCE_INFO.test(info);
@@ -7910,6 +7954,12 @@ var REMOTE = Symbol("etherpk-remote");
 var CACHE_SEED = Symbol("etherpk-cache-seed");
 /** Structural lifecycle changes which must never be mistaken for a user's edit. */
 var SUPPRESSED = Symbol("etherpk-suppressed");
+/**
+* A created document's text written again as this device's own insert, so it can be sent whole
+* to a generation that never held the structs it was first written with (ADR 0157). Local, so it
+* is sent, but no undo manager tracks it.
+*/
+var RECREATED = Symbol("etherpk-recreated");
 /** Health that says the bytes are not this document's, so neither text nor emptiness is real. */
 function contentBlocked(health) {
 	return health === "key-unavailable" || health === "ciphertext-corrupt";
@@ -8002,6 +8052,14 @@ function createDocSync(deps) {
 	let pendingSnapshot;
 	/** The newest epoch an update needed that the keyring does not hold (ADR 0127). */
 	let missingEpoch;
+	/** Set by `claimCreation` until the relay acknowledges this device's first text. */
+	let createdHere = false;
+	/**
+	* Set when the relay answered `stale_generation` to text this device created or resurrected:
+	* the next catch-up page tells which generation the relay holds, and that text is then
+	* written again and sent whole into it rather than cleared.
+	*/
+	let recreating = false;
 	/** Outbox operations the relay refused as sealed under an older epoch: sealed again on `keysChanged`. */
 	const refusedAsStale = /* @__PURE__ */ new Set();
 	/** A read-back failed: the next idle uploads a fresh snapshot whatever the tail size. */
@@ -8031,6 +8089,44 @@ function createDocSync(deps) {
 		catchupActive = false;
 		catchupCompletion.resolve();
 	}
+	/**
+	* The relay holds this document at a generation that the text this device created was not
+	* written in (ADR 0157). Move to that generation, and write the text again as one insert of
+	* this device's own, so it depends on no struct the generation never held (a deterministic
+	* Journal Template's among them). The next send carries the whole state: a `resurrect` into a
+	* deleted generation, an append into one that another device started first.
+	*/
+	function recreateInto(nextGeneration, state) {
+		recreating = false;
+		documentGeneration = nextGeneration;
+		lifecycleState = state;
+		lastSeq = 0;
+		syncHealth = "healthy";
+		const content = doc.getText("content");
+		const text = content.toString();
+		if (text === "") return;
+		doc.transact(() => {
+			content.delete(0, text.length);
+			content.insert(0, text);
+		}, RECREATED);
+	}
+	/**
+	* A catch-up has reached a newer active generation than this device's copy (ADR 0157): the
+	* document was deleted, and started again, while this device was away. The copy holds the
+	* deleted generation's text, so it is cleared, never merged into the new one. The new
+	* generation never held the structs that remain, so the next send carries the whole state.
+	*/
+	function discardOlderGeneration() {
+		const content = doc.getText("content");
+		seeding = true;
+		try {
+			if (content.length > 0) doc.transact(() => content.delete(0, content.length), SUPPRESSED);
+		} finally {
+			seeding = false;
+		}
+		lastSyncedStateVector = Y.encodeStateVector(new Y.Doc());
+		lastSyncedSnapshot = Y.snapshot(doc);
+	}
 	function failCatchup(error) {
 		const reported = asError(error);
 		firstCatchupPage.reject(reported);
@@ -8138,7 +8234,8 @@ function createDocSync(deps) {
 				epochId: epoch.epochId,
 				envelope: toBase64Url(await encrypt(plaintext)),
 				stateVector: operationStateVector,
-				createdAt: now()
+				createdAt: now(),
+				...createdHere ? { creates: true } : {}
 			};
 			const state = stateSnapshot();
 			await persistTask(() => persist.enqueue(operation, state, { settledDirtyTokens }));
@@ -8506,6 +8603,7 @@ function createDocSync(deps) {
 						}
 						lastSyncedStateVector = mergeStateVectors(lastSyncedStateVector, operation.stateVector);
 						lifecycleState = "active";
+						createdHere = false;
 						updatesSinceSnapshot += 1;
 						bytesSinceSnapshot += fromBase64Url(operation.envelope).byteLength;
 						scheduleAutomaticCompaction();
@@ -8529,6 +8627,21 @@ function createDocSync(deps) {
 					try {
 						const beforeBatch = indexMutationVersion;
 						if (message.generation < documentGeneration) break;
+						if (recreating) {
+							recreateInto(message.generation, message.state);
+							if (message.state === "deleted") {
+								await saveCurrent({ indexContentChanged: true });
+								futureUpdates.clear();
+								completeCatchup();
+								break;
+							}
+						} else if (message.state === "active" && message.generation > documentGeneration && lifecycleState === "active") discardOlderGeneration();
+						if (message.state === "deleted" && message.generation === documentGeneration && (lifecycleState === "deleted" || lifecycleState === "resurrecting")) {
+							lastSeq = 0;
+							futureUpdates.clear();
+							completeCatchup();
+							break;
+						}
 						if (message.state === "deleted") {
 							documentGeneration = message.generation;
 							lifecycleState = "deleted";
@@ -8635,10 +8748,21 @@ function createDocSync(deps) {
 			await transmit(durableQueue[0]);
 		},
 		lifecycle: () => lifecycleState,
+		generation: () => documentGeneration,
+		claimCreation() {
+			createdHere = true;
+		},
 		health: () => syncHealth,
 		async staleGeneration(currentGeneration) {
 			syncHealth = "generation-stale";
-			for (const operation of durableQueue.splice(0)) await persist.discard(operation.outboxId);
+			const discarded = durableQueue.splice(0);
+			if (createdHere || discarded.some((operation) => operation.kind === "resurrect" || operation.kind === "append" && operation.creates)) {
+				recreating = true;
+				createdHere = true;
+				lastSyncedStateVector = Y.encodeStateVector(new Y.Doc());
+				lastSyncedSnapshot = void 0;
+			} else if (currentGeneration > documentGeneration && lifecycleState === "active") discardOlderGeneration();
+			for (const operation of discarded) await persist.discard(operation.outboxId);
 			queueChanged();
 			boundarySnapshots.clear();
 			documentGeneration = currentGeneration;
@@ -9720,6 +9844,14 @@ function createGraphSync(deps) {
 	const foregroundCatchups = [];
 	const backgroundCatchups = [];
 	let catchupInFlight;
+	/**
+	* The request the in-flight one's document asked for again while it was in flight. The relay
+	* may have composed the in-flight answer before whatever prompted the second request: an ack
+	* naming a sequence that another device's concurrent first write took, for one. Dropped as a
+	* duplicate, that document stayed behind for good, so it runs once more if the answer leaves
+	* the document with a gap.
+	*/
+	let catchupRepeat;
 	let resolveFirstOpen;
 	const firstOpen = new Promise((resolve) => {
 		resolveFirstOpen = resolve;
@@ -9812,7 +9944,10 @@ function createGraphSync(deps) {
 	}
 	function queueCatchup(message) {
 		if (!open) return;
-		if (catchupInFlight?.docId === message.docId && catchupInFlight.generation === message.generation && catchupInFlight.afterSeq === message.afterSeq) return;
+		if (catchupInFlight?.docId === message.docId && catchupInFlight.generation === message.generation && catchupInFlight.afterSeq === message.afterSeq) {
+			catchupRepeat = message;
+			return;
+		}
 		const removeQueued = (queue) => {
 			const index = queue.findIndex((candidate) => candidate.docId === message.docId);
 			if (index >= 0) queue.splice(index, 1);
@@ -9826,6 +9961,9 @@ function createGraphSync(deps) {
 		if (!requestId || catchupInFlight?.requestId !== requestId) return;
 		const completedDocId = catchupInFlight.docId;
 		catchupInFlight = void 0;
+		const repeat = catchupRepeat?.docId === completedDocId ? catchupRepeat : void 0;
+		catchupRepeat = void 0;
+		if (repeat && engines.get(completedDocId)?.health() === "sequence-gap") queueCatchup(repeat);
 		pumpCatchups();
 		retireEngineIfIdle(completedDocId);
 	}
@@ -10125,7 +10263,10 @@ function createGraphSync(deps) {
 				return;
 			}
 			if (message.code === "stale_generation" && message.docId && message.currentGeneration !== void 0) {
-				if (catchupInFlight?.docId === message.docId) catchupInFlight = void 0;
+				if (catchupInFlight?.docId === message.docId) {
+					catchupInFlight = void 0;
+					catchupRepeat = void 0;
+				}
 				operationAnswered(message.docId);
 				engine(message.docId).staleGeneration(message.currentGeneration);
 				pumpCatchups();
@@ -10183,6 +10324,7 @@ function createGraphSync(deps) {
 		operationsInFlight.clear();
 		operationsWaiting.clear();
 		catchupInFlight = void 0;
+		catchupRepeat = void 0;
 		foregroundCatchups.length = 0;
 		backgroundCatchups.length = 0;
 		for (const pending of watermarkRequests.values()) {
@@ -10311,6 +10453,7 @@ function createGraphSync(deps) {
 		});
 	}
 	connect();
+	let journalIdSecret;
 	return {
 		rootDoc: root.doc,
 		docSync: (docId) => engine(docId),
@@ -10367,6 +10510,10 @@ function createGraphSync(deps) {
 		compactDoc: (docId) => deps.cache.docCache(docId).compact(),
 		uploadSnapshot: (docId) => engine(docId).compact(),
 		registry: () => registryMap,
+		journalDocId(date) {
+			journalIdSecret ??= deriveJournalIdSecret(keyring());
+			return journalIdSecret.then((secret) => journalDocId(secret, date));
+		},
 		getMeta() {
 			const name = metaMap.get("name");
 			const settings = metaMap.get("settings");
@@ -10623,6 +10770,7 @@ function createGraphSync(deps) {
 			foregroundCatchups.length = 0;
 			backgroundCatchups.length = 0;
 			catchupInFlight = void 0;
+			catchupRepeat = void 0;
 			for (const pending of watermarkRequests.values()) {
 				clearTimeout(pending.timer);
 				pending.reject(/* @__PURE__ */ new Error("the graph sync session was disposed"));
@@ -11258,8 +11406,10 @@ async function hostRequest(endpoint, request, options = {}) {
 /**
 * The settings a publish reads, which the command line decides even when the graph's host runs
 * the publish: where the publish folders are remembered, which browser draws diagrams and maps,
-* and which style a map's picture is drawn over. The host was started from another environment
-* (an agent's), and a scheduled publish may name its own browser or its own map host.
+* which style a map's picture is drawn over, and the GitHub token and API a [[Publish
+* Repository]] is committed with (ADR 0152). The host was started from another environment (an
+* agent's), and a scheduled publish may name its own browser, map host or token. The token goes
+* no further than this request: the host uses it for this publish and keeps nothing of it.
 */
 var PUBLISH_SETTINGS = [
 	"ETHERPK_MCP_PUBLISH_CONFIG",
@@ -11267,7 +11417,9 @@ var PUBLISH_SETTINGS = [
 	"ETHERPK_CHROMIUM",
 	"PLAYWRIGHT_BROWSERS_PATH",
 	"PLAYWRIGHT_CHROMIUM_EXECUTABLE",
-	"ETHERPK_MAP_STYLE_URL"
+	"ETHERPK_MAP_STYLE_URL",
+	"ETHERPK_GITHUB_TOKEN",
+	"ETHERPK_GITHUB_API_URL"
 ];
 /** The publish settings in `env`, for a `publish` request. */
 function publishSettings(env) {
@@ -11625,6 +11777,13 @@ function sameBytes(a, b) {
 	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
 	return true;
 }
+/** Whether the folder already holds `content` at `path`: compared where it can, read back where it cannot. */
+async function holds$1(folder, path, content) {
+	if (folder.sameContent) return folder.sameContent(path, content);
+	if (typeof content === "string") return await folder.readText(path) === content;
+	const existing = await folder.readBytes(path);
+	return existing !== null && sameBytes(existing, content);
+}
 /** Write a site into a folder under the rules above, whatever stands behind the folder. */
 async function writeSite(folder, bundle, options) {
 	const result = {
@@ -11636,17 +11795,9 @@ async function writeSite(folder, bundle, options) {
 	let done = 0;
 	for (const [path, content] of bundle) {
 		options.onProgress?.(done++, total);
-		if (typeof content === "string") {
-			if (await folder.readText(path) === content) {
-				result.unchanged++;
-				continue;
-			}
-		} else {
-			const existing = await folder.readBytes(path);
-			if (existing && sameBytes(existing, content)) {
-				result.unchanged++;
-				continue;
-			}
+		if (await holds$1(folder, path, content)) {
+			result.unchanged++;
+			continue;
 		}
 		await folder.writeFile(path, content);
 		result.written++;
@@ -11672,6 +11823,570 @@ async function writeSite(folder, bundle, options) {
 	options.onProgress?.(total, total);
 	return result;
 }
+var GitHubError = class extends Error {
+	code;
+	status;
+	detail;
+	constructor(code, message, status, detail) {
+		super(message);
+		this.code = code;
+		this.status = status;
+		this.detail = detail;
+		this.name = "GitHubError";
+	}
+};
+/** Writes GitHub asks to be spaced (its "best practices for using the REST API"). */
+var WRITE_SPACING_MS = 1e3;
+/** How many times a request GitHub failed on (5xx) is tried again. Creating git objects is idempotent. */
+var SERVER_ERROR_RETRIES = 2;
+var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** True for a 403 or 429 that GitHub sends as a rate limit, rather than a refusal. */
+function isRateLimit(status, headers, message) {
+	if (status === 429) return true;
+	if (status !== 403) return false;
+	return headers.has("retry-after") || headers.get("x-ratelimit-remaining") === "0" || /rate limit/i.test(message);
+}
+/** How long to wait before trying again, in GitHub's order: retry-after, the reset time, a doubling minute. */
+function waitFor(headers, attempt, now) {
+	const retryAfter = Number(headers.get("retry-after"));
+	if (Number.isFinite(retryAfter) && retryAfter > 0) return retryAfter * 1e3;
+	const reset = Number(headers.get("x-ratelimit-reset"));
+	if (headers.get("x-ratelimit-remaining") === "0" && Number.isFinite(reset) && reset * 1e3 > now) return reset * 1e3 - now;
+	return 6e4 * 2 ** attempt;
+}
+/** The code for a refusal GitHub sent, from its status and message. */
+function refusalCode(status, message) {
+	if (status === 401) return "bad-token";
+	if (/not a fast.?forward/i.test(message)) return "branch-moved";
+	if (/protected branch|pull request|GH006|signed/i.test(message)) return "branch-protected";
+	if (status === 409 && /empty/i.test(message)) return "empty-repository";
+	if (status === 403) return "read-only";
+	if (status === 404) return "no-access";
+	return "unexpected";
+}
+function createGitHubApi(options) {
+	const doFetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+	const baseUrl = (options.baseUrl ?? "https://api.github.com").replace(/\/+$/, "");
+	const sleep = options.sleep ?? realSleep;
+	const now = options.now ?? Date.now;
+	let lastWrite = Number.NEGATIVE_INFINITY;
+	let writeQueue = Promise.resolve();
+	async function send(method, path, body) {
+		try {
+			return await doFetch(`${baseUrl}${path}`, {
+				method,
+				headers: {
+					Accept: "application/vnd.github+json",
+					Authorization: `Bearer ${options.token}`,
+					"X-GitHub-Api-Version": "2022-11-28",
+					...body === void 0 ? {} : { "Content-Type": "application/json" }
+				},
+				body: body === void 0 ? void 0 : JSON.stringify(body),
+				credentials: "omit"
+			});
+		} catch (error) {
+			throw new GitHubError("offline", `GitHub could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	async function attempt(method, path, body, write) {
+		let rateLimited = 0;
+		let failed = 0;
+		for (;;) {
+			if (write) {
+				const wait = lastWrite + WRITE_SPACING_MS - now();
+				if (wait > 0) await sleep(wait);
+				lastWrite = now();
+			}
+			const response = await send(method, path, body);
+			if (response.ok) {
+				const text = await response.text();
+				return text === "" ? null : JSON.parse(text);
+			}
+			const message = await response.json().then((json) => typeof json?.message === "string" ? json.message : "").catch(() => "");
+			if (isRateLimit(response.status, response.headers, message)) {
+				const wait = waitFor(response.headers, rateLimited, now());
+				if (rateLimited >= 4) throw new GitHubError("rate-limited", `GitHub asked for a wait: ${message}`, response.status, { retryAt: now() + wait });
+				rateLimited++;
+				options.onWait?.(now() + wait);
+				await sleep(wait);
+				continue;
+			}
+			if (response.status >= 500 && failed < SERVER_ERROR_RETRIES) {
+				failed++;
+				await sleep(2e3 * failed);
+				continue;
+			}
+			throw new GitHubError(refusalCode(response.status, message), message || `${response.status} ${response.statusText}`, response.status);
+		}
+	}
+	return { request(method, path, body) {
+		if (method === "GET") return attempt(method, path, body, false);
+		const run = writeQueue.then(() => attempt(method, path, body, true));
+		writeQueue = run.catch(() => void 0);
+		return run;
+	} };
+}
+/** `/repos/{owner}/{name}`, each part escaped. */
+function repoPath(repo) {
+	return `/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.name)}`;
+}
+/** A branch name in a ref path: a branch may hold `/`, which stays a separator. */
+function branchPath(branch) {
+	return branch.split("/").map(encodeURIComponent).join("/");
+}
+/** Standard base64, as GitHub's blob and contents endpoints take and give it. */
+function bytesToBase64(bytes) {
+	let binary = "";
+	for (let i = 0; i < bytes.length; i += 32768) binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
+	return btoa(binary);
+}
+/** GitHub's base64 wraps lines; the line breaks are not part of it. */
+function base64ToBytes(text) {
+	const binary = atob(text.replace(/\s+/g, ""));
+	const bytes = new Uint8Array(binary.length);
+	for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+	return bytes;
+}
+//#endregion
+//#region ../client/src/lib/document/publish/host/github-repository.ts
+/**
+* A [[Publish Repository]] before any publish: reading what a person typed as a repository,
+* checking that their GitHub token can reach it, and starting the branch when they ask (ADR 0152).
+*
+* The check runs when the repository is saved in the Publish tab and before the first publish to
+* one that was never checked, rather than behind a button of its own. Write access is proven by
+* writing: a fine-grained token's own permissions are not in any answer GitHub gives (a
+* repository's `permissions` are the person's role), so the check uploads a tiny blob that no
+* commit refers to, which GitHub discards.
+*
+* A publish never creates a branch: a branch name mistyped would publish where no host looks.
+* The person asks for it (`createBranch`), after the check has said the branch is not there.
+*/
+var OWNER = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+var NAME = /^[A-Za-z0-9._-]{1,100}$/;
+/**
+* `owner/name` from what a person typed or pasted: `owner/name`, a github.com address, a clone
+* url or an ssh address. Null when it is none of those.
+*/
+function parseRepository(input) {
+	const parts = input.trim().replace(/^git@github\.com:/i, "").replace(/^(?:https?:\/\/)?(?:www\.)?github\.com\//i, "").replace(/\/+$/, "").replace(/\.git$/i, "").split("/");
+	if (parts.length !== 2) return null;
+	const [owner, name] = parts;
+	if (!OWNER.test(owner) || !NAME.test(name) || name === "." || name === "..") return null;
+	return {
+		owner,
+		name
+	};
+}
+/** Whether git takes `name` as a branch name (the rules of `git check-ref-format` a person can break by typing). */
+function isBranchName(name) {
+	if (name === "" || name.startsWith("/") || name.endsWith("/") || name.endsWith(".") || name.endsWith(".lock")) return false;
+	if (name.includes("..") || name.includes("//") || name.includes("@{")) return false;
+	if ([...name].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127)) return false;
+	return !/[\s~^:?*[\\]/.test(name);
+}
+function megabytes(bytes) {
+	return `${Math.round(bytes / 1048576)} MB`;
+}
+function clock(ms) {
+	return new Date(ms).toLocaleTimeString([], {
+		hour: "2-digit",
+		minute: "2-digit"
+	});
+}
+/**
+* An error from a check or a publish, worded for the person: what happened, why, and what to do.
+* `replaceToken` says where a new token goes: the Publish tab's GitHub section by default, an
+* environment variable at the Headless Client's command line.
+*/
+function describeGitHubError(error, repo, options = {}) {
+	if (!(error instanceof GitHubError)) return error instanceof Error ? error.message : String(error);
+	const where = `${repo.owner}/${repo.name}`;
+	switch (error.code) {
+		case "offline": return "GitHub could not be reached. Check the connection and try again.";
+		case "bad-token": return `GitHub refused the token. It has expired, been revoked or was mistyped. ${options.replaceToken ?? "Make a new one and replace it under GitHub above."}`;
+		case "no-access": return `GitHub found no repository ${where} for this token. Check the name, and that the token's Repository access includes it.`;
+		case "read-only": return `The token can read ${where} but not write to it. On GitHub, give the token the Contents permission with Read and write.`;
+		case "branch-missing": return `${where} has no branch "${repo.branch}". Check the name, or create the branch.`;
+		case "empty-repository": return `${where} is empty. Create the branch to make its first commit.`;
+		case "branch-moved": return `The branch "${repo.branch}" changed twice while EtherPK was publishing to it. Publish again.`;
+		case "branch-protected": return `A protection rule on "${repo.branch}" refused the commit, as it asks for a pull request or a signed commit. Publish to a branch of its own, such as gh-pages, and serve the site from that branch.`;
+		case "rate-limited": return `GitHub asked EtherPK to wait for longer than it will. Nothing was committed. Publish again after ${clock(error.detail?.retryAt ?? Date.now())}.`;
+		case "too-large": return `${error.detail?.path ?? "A file"} is ${megabytes(error.detail?.size ?? 0)}, and GitHub takes files up to 100 MB. Nothing was committed. Make the file smaller or link to it from elsewhere.`;
+		case "truncated": return `"${repo.branch}" holds more files than GitHub lists at once, so EtherPK cannot see which old files to remove. Publish to a branch of its own.`;
+		case "unexpected": return `GitHub refused the request${error.status ? ` (${error.status})` : ""}: ${error.message}`;
+	}
+}
+//#endregion
+//#region ../client/src/lib/document/publish/seeded.ts
+var PAGES_WORKFLOW_PATH = ".github/workflows/pages.yaml";
+var WRANGLER_PATH = "wrangler.jsonc";
+var ASSETS_IGNORE_PATH = ".assetsignore";
+var README_PATH = "README.md";
+var GITIGNORE_PATH = ".gitignore";
+/**
+* Files written when absent and left alone afterwards. A Publish Repository gets no Pages
+* workflow: GitHub refuses a commit that adds one unless the token may also change workflows,
+* and Pages serves a branch as it is without one ("Deploy from a branch"), so its README says
+* that instead.
+*/
+function seededFiles(publication, destination = "folder") {
+	const files = /* @__PURE__ */ new Map([
+		[PAGES_WORKFLOW_PATH, `# Publishes this folder to GitHub Pages as it is: the site is already built by EtherPK,
+# so there is no build step. In the repository's Settings → Pages, set the source to
+# "GitHub Actions" once - every push to main then deploys.
+name: Deploy to GitHub Pages
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: false
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: .
+      - id: deployment
+        uses: actions/deploy-pages@v4
+`],
+		[WRANGLER_PATH, `// Cloudflare Workers with static assets (Cloudflare's successor to Pages for new sites).
+// Deploy with \`npx wrangler deploy\`, or connect the repository in the dashboard under
+// Workers → Create → Import a repository and leave the build command empty. The Worker is
+// named after the publication - Cloudflare warns when this name and the Worker's differ.
+{
+    "name": "${publication.id}",
+    "compatibility_date": "2026-01-01",
+    "assets": {
+        "directory": ".",
+        "html_handling": "auto-trailing-slash",
+        "not_found_handling": "404-page"
+    }
+}
+`],
+		[README_PATH, `# ${publication.name}
+
+This folder is a website published by [EtherPK](https://etherpk.com) from the publication
+\`${publication.id}\`. Every file in it except \`CNAME\` and \`robots.txt\` is regenerated on each
+publish, so edit the notes, the publication page, its include pages and its theme in EtherPK,
+not here.
+
+- Preview: open \`index.html\` in a browser - search works from disk too.
+${destination === "repository" ? `- GitHub Pages: in the repository's Settings → Pages, set Source to "Deploy from a branch" and
+  choose this branch and \`/ (root)\`. Every publish then deploys.` : `- GitHub Pages: push this folder to a repository and set Settings → Pages → Source to
+  "GitHub Actions" - \`.github/workflows/pages.yaml\` deploys every push to \`main\`.`}
+- Cloudflare: \`npx wrangler deploy\` uses \`wrangler.jsonc\`, or connect the repository in the
+  Workers dashboard with no build command.
+- Netlify, GitLab Pages, Vercel, S3 or your own server: the folder is plain files, so any of
+  them serves it as it is. Step by step for each: https://docs.etherpk.com/hosting-a-published-site
+`],
+		[GITIGNORE_PATH, `.DS_Store\nThumbs.db\n`],
+		[ASSETS_IGNORE_PATH, `# Files in this folder that are not part of the website, kept out of the Worker's assets.
+# Written once by EtherPK - yours to edit.
+.git
+.github
+.gitignore
+.assetsignore
+.nojekyll
+wrangler.jsonc
+AGENTS.md
+README.md
+`]
+	]);
+	if (destination === "repository") files.delete(PAGES_WORKFLOW_PATH);
+	return files;
+}
+var AGENTS_START = "<!-- etherpk:start -->";
+var AGENTS_END = "<!-- etherpk:end -->";
+function managedSection(publication) {
+	return `${AGENTS_START}
+## EtherPK published site
+
+This folder is a website generated by [EtherPK](https://etherpk.com) from the publication
+\`${publication.id}\` ("${publication.name}"). It is **output**: every file except \`CNAME\`,
+\`robots.txt\` and the text outside this section of \`AGENTS.md\` is rewritten on each publish
+and files that are no longer produced are deleted.
+
+- Do not edit the HTML, the assets or \`theme/\` here - the change is lost on the next publish.
+- Content changes are made to the documents in EtherPK. A document is published when its
+  frontmatter says \`public: true\` and names this publication in \`publications: [${publication.id}]\`
+  (unless the publication takes every public document).
+- The navigation is the outline of the publication page in EtherPK - the theme and the include
+  slots (head, favicon, logo, header, footer, before-content, after-content, scripts, styles) are chosen
+  and edited there too, in the Publish settings and the Theme editor.
+- EtherPK publishes this site into a folder, or straight to its repository on GitHub, from any
+  device. A change made here to a file it writes is lost on the next publish, wherever that runs.
+- \`index.html\` opens from disk for a preview. On GitHub Pages the site deploys through
+  \`.github/workflows/pages.yaml\` where there is one, or with Pages set to "Deploy from a branch".
+  \`wrangler.jsonc\` deploys it to Cloudflare Workers, and any static host serves it as it is
+  (https://docs.etherpk.com/hosting-a-published-site).
+
+This section is rewritten by EtherPK on every publish. Put your own notes above or below it.
+${AGENTS_END}
+`;
+}
+/**
+* The publication whose site a folder's AGENTS.md says the folder holds, or null when it carries
+* no published-site section. A first publish to a [[Publish Repository]] asks before it replaces
+* files on a branch that does not say it holds this publication's site.
+*/
+function publishedPublicationOf(agentsMd) {
+	if (agentsMd === null) return null;
+	const start = agentsMd.indexOf(AGENTS_START);
+	const end = agentsMd.indexOf(AGENTS_END);
+	if (start === -1 || end <= start) return null;
+	const section = agentsMd.slice(start, end);
+	if (!section.includes("## EtherPK published site")) return null;
+	return /from the publication\s+`([a-z0-9-]+)`/.exec(section)?.[1] ?? null;
+}
+/** The folder's AGENTS.md with the managed section replaced or added, the user's text kept. */
+function agentsMdWithManagedSection(existing, publication) {
+	const section = managedSection(publication);
+	if (existing === null || existing.trim() === "") return section;
+	const start = existing.indexOf(AGENTS_START);
+	const end = existing.indexOf(AGENTS_END);
+	if (start !== -1 && end !== -1 && end > start) return existing.slice(0, start) + section.trimEnd() + existing.slice(end + 20);
+	return `${existing.trimEnd()}\n\n${section}`;
+}
+//#endregion
+//#region ../client/src/lib/document/publish/host/git-blob-sha.ts
+/**
+* The name git gives a file's content: the SHA-1 of `blob <byte length>\0` followed by the bytes,
+* as `git hash-object` prints it. A [[Publish Repository]] compares it with the names in the
+* branch's tree to find what a publish changed without downloading a single file, and an
+* unchanged image keeps its name, so a later publish never sends it again.
+*
+* WebCrypto, which the browser and Node both have, so the Client and the Headless Client share it.
+* SHA-1 here is git's object name, not a security measure.
+*/
+var encoder$1 = new TextEncoder();
+async function gitBlobSha(content) {
+	const bytes = typeof content === "string" ? encoder$1.encode(content) : content;
+	const header = encoder$1.encode(`blob ${bytes.byteLength}\0`);
+	const object = new Uint8Array(header.byteLength + bytes.byteLength);
+	object.set(header, 0);
+	object.set(bytes, header.byteLength);
+	const digest = new Uint8Array(await crypto.subtle.digest("SHA-1", object));
+	return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Tree entries sent in one request, and inline text in one request, before the next batch starts. */
+var TREE_BATCH_ENTRIES = 300;
+var TREE_BATCH_BYTES = 4194304;
+var decoder = new TextDecoder();
+var encoder = new TextEncoder();
+/** Read the branch: its head commit and every file in its tree. */
+async function openRepositoryBranch(api, repo) {
+	const base = repoPath(repo);
+	let head;
+	try {
+		head = (await api.request("GET", `${base}/git/ref/heads/${branchPath(repo.branch)}`)).object.sha;
+	} catch (error) {
+		if (error instanceof GitHubError && error.code === "no-access") {
+			await api.request("GET", base);
+			throw new GitHubError("branch-missing", error.message, error.status);
+		}
+		throw error;
+	}
+	const treeSha = (await api.request("GET", `${base}/git/commits/${head}`)).tree.sha;
+	const listing = await api.request("GET", `${base}/git/trees/${treeSha}?recursive=1`);
+	if (listing.truncated) throw new GitHubError("truncated", "GitHub listed the branch only in part.");
+	const tree = /* @__PURE__ */ new Map();
+	for (const entry of listing.tree) if (entry.type === "blob") tree.set(entry.path, {
+		mode: entry.mode,
+		sha: entry.sha
+	});
+	/** Path → new content, or null for a removal. */
+	const staged = /* @__PURE__ */ new Map();
+	const downloaded = /* @__PURE__ */ new Map();
+	async function bytesAt(path) {
+		const change = staged.get(path);
+		if (change !== void 0) return change === null ? null : typeof change === "string" ? encoder.encode(change) : change;
+		const entry = tree.get(path);
+		if (!entry) return null;
+		let bytes = downloaded.get(entry.sha);
+		if (!bytes) {
+			bytes = base64ToBytes((await api.request("GET", `${base}/git/blobs/${entry.sha}`)).content);
+			downloaded.set(entry.sha, bytes);
+		}
+		return bytes;
+	}
+	return {
+		head,
+		async readText(path) {
+			const bytes = await bytesAt(path);
+			return bytes === null ? null : decoder.decode(bytes);
+		},
+		readBytes: bytesAt,
+		async sameContent(path, content) {
+			const entry = tree.get(path);
+			return entry !== void 0 && entry.sha === await gitBlobSha(content);
+		},
+		async writeFile(path, content) {
+			staged.set(path, content);
+		},
+		async remove(path) {
+			if (tree.has(path)) staged.set(path, null);
+		},
+		async listFiles() {
+			return [...tree.keys()];
+		},
+		replaced() {
+			return [...staged.keys()].filter((path) => tree.has(path) && path !== "AGENTS.md").sort();
+		},
+		pendingChanges() {
+			return staged.size;
+		},
+		async commit(message, options = {}) {
+			if (staged.size === 0) return null;
+			const report = options.onProgress ?? (() => {});
+			const maxFileBytes = options.maxFileBytes ?? 104857600;
+			for (const [path, content] of staged) {
+				if (content === null) continue;
+				const size = typeof content === "string" ? encoder.encode(content).byteLength : content.byteLength;
+				if (size > maxFileBytes) throw new GitHubError("too-large", `${path} is over GitHub's file size limit.`, void 0, {
+					path,
+					size
+				});
+			}
+			const known = new Set([...tree.values()].map((entry) => entry.sha));
+			const binaries = [...staged].filter((change) => change[1] instanceof Uint8Array);
+			const blobShas = /* @__PURE__ */ new Map();
+			report("uploading", 0, binaries.length);
+			for (const [index, [path, bytes]] of binaries.entries()) {
+				let sha = await gitBlobSha(bytes);
+				if (!known.has(sha)) {
+					sha = (await api.request("POST", `${base}/git/blobs`, {
+						content: bytesToBase64(bytes),
+						encoding: "base64"
+					})).sha;
+					known.add(sha);
+				}
+				blobShas.set(path, sha);
+				report("uploading", index + 1, binaries.length);
+			}
+			const batches = batch([...staged].map(([path, content]) => {
+				const mode = tree.get(path)?.mode ?? "100644";
+				if (content === null) return {
+					path,
+					mode,
+					type: "blob",
+					sha: null
+				};
+				if (typeof content === "string") return {
+					path,
+					mode,
+					type: "blob",
+					content
+				};
+				return {
+					path,
+					mode,
+					type: "blob",
+					sha: blobShas.get(path)
+				};
+			}), options.treeBatch ?? TREE_BATCH_ENTRIES);
+			let root = treeSha;
+			for (const [index, entriesOfBatch] of batches.entries()) {
+				report("committing", index, batches.length + 2);
+				root = (await api.request("POST", `${base}/git/trees`, {
+					base_tree: root,
+					tree: entriesOfBatch
+				})).sha;
+			}
+			report("committing", batches.length, batches.length + 2);
+			const commit = await api.request("POST", `${base}/git/commits`, {
+				message,
+				tree: root,
+				parents: [head]
+			});
+			report("committing", batches.length + 1, batches.length + 2);
+			await api.request("PATCH", `${base}/git/refs/heads/${branchPath(repo.branch)}`, {
+				sha: commit.sha,
+				force: false
+			});
+			report("committing", batches.length + 2, batches.length + 2);
+			return {
+				sha: commit.sha,
+				url: commit.html_url
+			};
+		}
+	};
+}
+/** Tree entries in batches small enough for one request: by count, and by the text they carry. */
+function batch(entries, size) {
+	const out = [];
+	let current = [];
+	let bytes = 0;
+	for (const entry of entries) {
+		const weight = entry.content?.length ?? 0;
+		if (current.length > 0 && (current.length >= size || bytes + weight > TREE_BATCH_BYTES)) {
+			out.push(current);
+			current = [];
+			bytes = 0;
+		}
+		current.push(entry);
+		bytes += weight;
+	}
+	if (current.length > 0) out.push(current);
+	return out;
+}
+/** The graph's own AGENTS.md section (`storage/fs/agents-md-section.md`). */
+var GRAPH_AGENTS_HEADING = /^## EtherPK knowledge graph\s*$/m;
+/** True when the branch looks like a [[Graph Folder]], which a publish would gut. */
+async function holdsGraph(branch) {
+	const files = await branch.listFiles();
+	if (files.some((path) => path.startsWith("pages/")) && files.some((path) => path.startsWith("journals/"))) return true;
+	const agents = files.includes("AGENTS.md") ? await branch.readText("AGENTS.md") : null;
+	return agents !== null && GRAPH_AGENTS_HEADING.test(agents);
+}
+/** Publish a rendered site to the branch as one commit, under the rules at the top of this module. */
+async function publishToRepository(api, repo, input, options = {}) {
+	for (let attempt = 0;; attempt++) {
+		options.onProgress?.("reading", 0, 0);
+		const branch = await openRepositoryBranch(api, repo);
+		if (await holdsGraph(branch)) throw new Error(`${repo.owner}/${repo.name} holds a knowledge graph on "${repo.branch}", and a publish there would delete its files. Choose a repository or a branch of its own for the site.`);
+		const publishedHere = publishedPublicationOf(await branch.readText("AGENTS.md")) === input.publicationId;
+		const written = await writeSite(branch, input.bundle, {
+			seeded: input.seeded,
+			agentsMd: input.agentsMd
+		});
+		if (!options.confirmed && !publishedHere) {
+			const replaced = branch.replaced();
+			if (replaced.length > 0) return {
+				state: "needs-confirmation",
+				replaced
+			};
+		}
+		if (branch.pendingChanges() === 0) return {
+			state: "unchanged",
+			written
+		};
+		const message = `Publish ${input.publicationId}: ${written.written} written, ${written.deleted.length} removed`;
+		try {
+			return {
+				state: "committed",
+				written,
+				commit: await branch.commit(message, options),
+				retried: attempt > 0
+			};
+		} catch (error) {
+			if (error instanceof GitHubError && error.code === "branch-moved" && attempt === 0) continue;
+			throw error;
+		}
+	}
+}
 //#endregion
 //#region ../../packages/themes/src/index.ts
 var files = /* #__PURE__ */ Object.assign({
@@ -12046,124 +12761,6 @@ function withPublishing(text, patch, options = {}) {
 	}, options);
 }
 //#endregion
-//#region ../client/src/lib/document/publish/seeded.ts
-var PAGES_WORKFLOW_PATH = ".github/workflows/pages.yaml";
-var WRANGLER_PATH = "wrangler.jsonc";
-var ASSETS_IGNORE_PATH = ".assetsignore";
-var README_PATH = "README.md";
-var GITIGNORE_PATH = ".gitignore";
-/** Files written when absent and left alone afterwards. */
-function seededFiles(publication) {
-	return /* @__PURE__ */ new Map([
-		[PAGES_WORKFLOW_PATH, `# Publishes this folder to GitHub Pages as it is: the site is already built by EtherPK,
-# so there is no build step. In the repository's Settings → Pages, set the source to
-# "GitHub Actions" once - every push to main then deploys.
-name: Deploy to GitHub Pages
-on:
-  push:
-    branches: [main]
-  workflow_dispatch:
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-concurrency:
-  group: pages
-  cancel-in-progress: false
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: \${{ steps.deployment.outputs.page_url }}
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/configure-pages@v5
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: .
-      - id: deployment
-        uses: actions/deploy-pages@v4
-`],
-		[WRANGLER_PATH, `// Cloudflare Workers with static assets (Cloudflare's successor to Pages for new sites).
-// Deploy with \`npx wrangler deploy\`, or connect the repository in the dashboard under
-// Workers → Create → Import a repository and leave the build command empty. The Worker is
-// named after the publication - Cloudflare warns when this name and the Worker's differ.
-{
-    "name": "${publication.id}",
-    "compatibility_date": "2026-01-01",
-    "assets": {
-        "directory": ".",
-        "html_handling": "auto-trailing-slash",
-        "not_found_handling": "404-page"
-    }
-}
-`],
-		[README_PATH, `# ${publication.name}
-
-This folder is a website published by [EtherPK](https://etherpk.com) from the publication
-\`${publication.id}\`. Every file in it except \`CNAME\` and \`robots.txt\` is regenerated on each
-publish, so edit the notes, the publication page, its include pages and its theme in EtherPK,
-not here.
-
-- Preview: open \`index.html\` in a browser - search works from disk too.
-- GitHub Pages: push this folder to a repository and set Settings → Pages → Source to
-  "GitHub Actions" - \`.github/workflows/pages.yaml\` deploys every push to \`main\`.
-- Cloudflare: \`npx wrangler deploy\` uses \`wrangler.jsonc\`, or connect the repository in the
-  Workers dashboard with no build command.
-- Netlify, GitLab Pages, Vercel, S3 or your own server: the folder is plain files, so any of
-  them serves it as it is. Step by step for each: https://docs.etherpk.com/hosting-a-published-site
-`],
-		[GITIGNORE_PATH, `.DS_Store\nThumbs.db\n`],
-		[ASSETS_IGNORE_PATH, `# Files in this folder that are not part of the website, kept out of the Worker's assets.
-# Written once by EtherPK - yours to edit.
-.git
-.github
-.gitignore
-.assetsignore
-.nojekyll
-wrangler.jsonc
-AGENTS.md
-README.md
-`]
-	]);
-}
-var AGENTS_START = "<!-- etherpk:start -->";
-var AGENTS_END = "<!-- etherpk:end -->";
-function managedSection(publication) {
-	return `${AGENTS_START}
-## EtherPK published site
-
-This folder is a website generated by [EtherPK](https://etherpk.com) from the publication
-\`${publication.id}\` ("${publication.name}"). It is **output**: every file except \`CNAME\`,
-\`robots.txt\` and the text outside this section of \`AGENTS.md\` is rewritten on each publish
-and files that are no longer produced are deleted.
-
-- Do not edit the HTML, the assets or \`theme/\` here - the change is lost on the next publish.
-- Content changes are made to the documents in EtherPK. A document is published when its
-  frontmatter says \`public: true\` and names this publication in \`publications: [${publication.id}]\`
-  (unless the publication takes every public document).
-- The navigation is the outline of the publication page in EtherPK - the theme and the include
-  slots (head, favicon, logo, header, footer, before-content, after-content, scripts, styles) are chosen
-  and edited there too, in the Publish settings and the Theme editor.
-- \`index.html\` opens from disk for a preview. \`.github/workflows/pages.yaml\` deploys the folder
-  to GitHub Pages, \`wrangler.jsonc\` deploys it to Cloudflare Workers, and any static host serves it
-  as it is (https://docs.etherpk.com/hosting-a-published-site).
-
-This section is rewritten by EtherPK on every publish. Put your own notes above or below it.
-${AGENTS_END}
-`;
-}
-/** The folder's AGENTS.md with the managed section replaced or added, the user's text kept. */
-function agentsMdWithManagedSection(existing, publication) {
-	const section = managedSection(publication);
-	if (existing === null || existing.trim() === "") return section;
-	const start = existing.indexOf(AGENTS_START);
-	const end = existing.indexOf(AGENTS_END);
-	if (start !== -1 && end !== -1 && end > start) return existing.slice(0, start) + section.trimEnd() + existing.slice(end + 20);
-	return `${existing.trimEnd()}\n\n${section}`;
-}
-//#endregion
 //#region ../client/src/lib/document/fence-answer.ts
 var PICTURE_TYPES = /* @__PURE__ */ new Set([
 	"image/svg+xml",
@@ -13580,7 +14177,7 @@ async function publishedFence(asked, info, concept, pictures, warnings) {
 function assetHrefOf(name) {
 	return `assets/${encodeURIComponent(name)}`;
 }
-function bodyOf$1(doc) {
+function bodyOf$2(doc) {
 	return parseFrontmatter(doc.text).body;
 }
 /** Every `http(s)` resource a piece of HTML or CSS pulls in, for the report. */
@@ -13767,7 +14364,7 @@ async function publishPublication(source, publication, env, options = {}) {
 	});
 	const bodies = [...included, ...includeDocs.values()].map((d) => ({
 		doc: d,
-		body: bodyOf$1(d)
+		body: bodyOf$2(d)
 	}));
 	for (const { doc, body } of bodies) for (const fence of probe.fences(body)) {
 		const fenceKey = `${fence.lang}\n${fence.code}`;
@@ -13880,7 +14477,7 @@ async function publishPublication(source, publication, env, options = {}) {
 		progress("rendering", done++, included.length);
 		const slug = slugs.get(conceptKey$1(doc.concept));
 		scopeDiagrams(`mermaid_${slug}`);
-		const rendered = renderer.render(bodyOf$1(doc));
+		const rendered = renderer.render(bodyOf$2(doc));
 		const isHome = doc === homeDoc;
 		const page = {
 			doc,
@@ -13897,7 +14494,7 @@ async function publishPublication(source, publication, env, options = {}) {
 			if (dated.date !== void 0) page.date = dated.date;
 			take(dated.issues);
 		}
-		for (const link of linksOf(bodyOf$1(doc), resolver, doc)) report.missingLinks.push(link);
+		for (const link of linksOf(bodyOf$2(doc), resolver, doc)) report.missingLinks.push(link);
 		pages.push(page);
 		report.included.push({
 			concept: doc.concept,
@@ -13938,7 +14535,7 @@ async function publishPublication(source, publication, env, options = {}) {
 			});
 			continue;
 		}
-		const body = bodyOf$1(doc);
+		const body = bodyOf$2(doc);
 		if (cssSlots.has(slot)) {
 			const fence = renderer.fences(body).find((f) => f.lang === "css");
 			if (!fence) {
@@ -14109,7 +14706,7 @@ async function publishPublication(source, publication, env, options = {}) {
 	})));
 	const wanted = /* @__PURE__ */ new Map();
 	for (const page of pages) for (const name of page.rendered.assets) if (!wanted.has(name)) wanted.set(name, page.doc.concept);
-	for (const [, doc] of includeDocs) for (const name of renderer.render(bodyOf$1(doc)).assets) if (!wanted.has(name)) wanted.set(name, doc.concept);
+	for (const [, doc] of includeDocs) for (const name of renderer.render(bodyOf$2(doc)).assets) if (!wanted.has(name)) wanted.set(name, doc.concept);
 	let assetsDone = 0;
 	for (const [name, from] of wanted) {
 		progress("assets", assetsDone++, wanted.size);
@@ -14464,7 +15061,7 @@ async function runPublish(publication, deps) {
 	return {
 		report,
 		bundle,
-		seeded: seededFiles(publication),
+		seeded: seededFiles(publication, deps.destination),
 		agentsMd: (existing) => agentsMdWithManagedSection(existing, publication)
 	};
 }
@@ -14987,14 +15584,35 @@ function nodeSiteFolder(root) {
 //#endregion
 //#region src/publish-folders.ts
 /**
-* Where each [[Publication]]'s [[Publish Folder]] is on this machine (ADR 0086): configuration a
-* person sets with `etherpk-mcp publish … --out <dir>`, read by the `publish` tool and by the
-* command without `--out`. A file of its own beside the logins (`publish.json`), because it is
-* not a secret and outlives a login; keyed by the graph the way its cache directory is keyed -
-* the server's host and graph id for a synced graph, the folder's path hash for a served folder -
-* so two graphs with a publication both called `blog` never share a folder. Never written into a
-* graph folder, which is the user's content (ADR 0079).
-*/
+* Where each [[Publication]] publishes from this machine (ADR 0086, ADR 0152): its [[Publish
+* Folder]], set with `etherpk-mcp publish … --out <dir>`, or its [[Publish Repository]], set with
+* `--github owner/name[#branch]`. One or the other: setting one forgets the other, as in the
+* Client. Read by the `publish` tool and by the command run without either. A file of its own
+* beside the logins (`publish.json`), because it is not a secret and outlives a login (the GitHub
+* token is never in it: it comes from `ETHERPK_GITHUB_TOKEN`); keyed by the graph the way its
+* cache directory is keyed - the server's host and graph id for a synced graph, the folder's path
+* hash for a served folder - so two graphs with a publication both called `blog` never share a
+* destination. Never written into a graph folder, which is the user's content (ADR 0079).
+*/
+/**
+* `owner/name` or `owner/name#branch` (a github.com address works too), as `--github` takes it.
+* Null when it is not a repository, or the branch is not a name git takes.
+*/
+function parseRepositoryArgument(text) {
+	const [repository, branch, ...rest] = text.trim().split("#");
+	if (rest.length > 0) return null;
+	const parsed = parseRepository(repository);
+	const name = branch?.trim() || "main";
+	if (!parsed || !isBranchName(name)) return null;
+	return {
+		...parsed,
+		branch: name
+	};
+}
+/** How a repository is written for a person: `owner/name#branch`. */
+function repositoryLabel(repo) {
+	return `${repo.owner}/${repo.name}#${repo.branch}`;
+}
 function defaultPublishFoldersPath(env = process.env) {
 	const override = env.ETHERPK_MCP_PUBLISH_CONFIG?.trim();
 	if (override) return override;
@@ -15014,14 +15632,25 @@ function parsePublishFolders(raw) {
 	} catch {
 		return out;
 	}
+	const isMap = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 	const folders = parsed?.folders;
-	if (typeof folders !== "object" || folders === null || Array.isArray(folders)) return out;
-	for (const [graphKey, byPublication] of Object.entries(folders)) {
-		if (typeof byPublication !== "object" || byPublication === null || Array.isArray(byPublication)) continue;
+	if (isMap(folders)) for (const [graphKey, byPublication] of Object.entries(folders)) {
+		if (!isMap(byPublication)) continue;
 		const kept = {};
 		for (const [publication, path] of Object.entries(byPublication)) if (typeof path === "string" && isAbsolute(path)) kept[publication] = path;
 		if (Object.keys(kept).length > 0) out.folders[graphKey] = kept;
 	}
+	const repositories = parsed?.repositories;
+	if (isMap(repositories)) for (const [graphKey, byPublication] of Object.entries(repositories)) {
+		if (!isMap(byPublication)) continue;
+		const kept = {};
+		for (const [publication, repo] of Object.entries(byPublication)) {
+			if (!isMap(repo) || typeof repo.owner !== "string" || typeof repo.name !== "string" || typeof repo.branch !== "string") continue;
+			const checked = parseRepositoryArgument(`${repo.owner}/${repo.name}#${repo.branch}`);
+			if (checked) kept[publication] = checked;
+		}
+		if (Object.keys(kept).length > 0) (out.repositories ??= {})[graphKey] = kept;
+	}
 	return out;
 }
 async function readPublishFolders(path) {
@@ -15043,6 +15672,33 @@ async function writePublishFolders(path, folders) {
 function publishFolderOf(folders, graphKey, publicationId) {
 	return folders.folders[graphKey]?.[publicationId] ?? null;
 }
+/** The repository set for a publication on this machine, or null. */
+function publishRepositoryOf(folders, graphKey, publicationId) {
+	return folders.repositories?.[graphKey]?.[publicationId] ?? null;
+}
+/** `publications` with one entry dropped, and the graph's map dropped when it empties. */
+function without(byGraph, graphKey, publicationId) {
+	const out = { ...byGraph ?? {} };
+	const rest = { ...out[graphKey] ?? {} };
+	delete rest[publicationId];
+	if (Object.keys(rest).length > 0) out[graphKey] = rest;
+	else delete out[graphKey];
+	return out;
+}
+/** The same file with one publication's repository set, in place of any folder - the caller writes it. */
+function withPublishRepository(folders, graphKey, publicationId, repo) {
+	const repositories = folders.repositories ?? {};
+	return {
+		folders: without(folders.folders, graphKey, publicationId),
+		repositories: {
+			...repositories,
+			[graphKey]: {
+				...repositories[graphKey] ?? {},
+				[publicationId]: repo
+			}
+		}
+	};
+}
 /**
 * How two absolute folder paths relate, by the platform's own `relative` rather than by splitting
 * on `/` (Windows paths use `\`, and a shared prefix such as `notes` and `notes-site` is not a
@@ -15082,15 +15738,19 @@ async function canonicalFolder(folder) {
 async function publishFolderOverlap(graphFolder, publishFolder) {
 	return relateFolders(await canonicalFolder(graphFolder), await canonicalFolder(publishFolder));
 }
-/** The same file with one publication's folder set (made absolute) - the caller writes it. */
+/** The same file with one publication's folder set (made absolute), in place of any repository - the caller writes it. */
 function withPublishFolder(folders, graphKey, publicationId, folder) {
-	return { folders: {
-		...folders.folders,
-		[graphKey]: {
-			...folders.folders[graphKey] ?? {},
-			[publicationId]: resolve(folder)
-		}
-	} };
+	const repositories = without(folders.repositories, graphKey, publicationId);
+	return {
+		folders: {
+			...folders.folders,
+			[graphKey]: {
+				...folders.folders[graphKey] ?? {},
+				[publicationId]: resolve(folder)
+			}
+		},
+		...Object.keys(repositories).length > 0 ? { repositories } : {}
+	};
 }
 //#endregion
 //#region ../client/src/lib/document/protection/cipher-fence.ts
@@ -18107,9 +18767,12 @@ async function graphInfo(graph) {
 * which the Settings tab uses too, so a publication page an agent creates is the one a person
 * would have created.
 *
-* Two things are this host's own. The [[Publish Folder]] is configuration a person set on the
+* Three things are this host's own. The [[Publish Folder]] is configuration a person set on the
 * command line, never a tool argument: the site writer deletes strays from the paths it owns,
-* and a folder an agent inferred could lose real files to that rule. And a publish whose pages
+* and a folder an agent inferred could lose real files to that rule. A [[Publish Repository]] is
+* set the same way, and only the person's own `etherpk-mcp publish` commits to it, with the
+* token in `ETHERPK_GITHUB_TOKEN`: a commit there can deploy the site, so the agent's tool checks
+* such a publication (a dry run) and never publishes it (ADR 0152). And a publish whose pages
 * hold Mermaid needs the browser `diagrams setup` installed; without one it refuses rather than
 * publishing a site with its diagrams turned to text.
 */
@@ -18172,8 +18835,11 @@ async function settle$1(graph) {
 	const result = await graph.settle();
 	if (!result.settled) throw new ToolError("not_settled", result.message);
 }
-/** How a publication reads to an agent: its page's settings, and whether this machine can publish it. */
-function publicationView(publication, folder) {
+/**
+* How a publication reads to an agent: its page's settings, and where this machine publishes it.
+* A repository shows as `owner/name#branch`; it is not the agent's to publish to.
+*/
+function publicationView(publication, destination) {
 	return {
 		id: publication.id,
 		name: publication.name,
@@ -18185,13 +18851,17 @@ function publicationView(publication, folder) {
 		theme: publication.theme,
 		recent: publication.recent,
 		includes: publication.includes,
-		publishFolder: folder
+		publishFolder: destination.folder,
+		publishRepository: destination.repository ? repositoryLabel(destination.repository) : null
 	};
 }
-async function foldersFor(graph, env) {
+async function destinationsFor(graph, env) {
 	const folders = await readPublishFolders(defaultPublishFoldersPath(env));
 	const key = publishGraphKey(graph.backend, graph.graphId);
-	return (publicationId) => publishFolderOf(folders, key, publicationId);
+	return (publicationId) => ({
+		folder: publishFolderOf(folders, key, publicationId),
+		repository: publishRepositoryOf(folders, key, publicationId)
+	});
 }
 /** The publications the graph defines, the issues in their pages, and the public documents none takes. */
 async function listPublications(graph, host) {
@@ -18199,9 +18869,9 @@ async function listPublications(graph, host) {
 	await graph.store.refresh();
 	const { source, unsettled } = await graph.publishing.readSource();
 	const summary = summarisePublishing(source);
-	const folderOf = await foldersFor(graph, env);
+	const destinationOf = await destinationsFor(graph, env);
 	return {
-		publications: summary.publications.map((p) => publicationView(p, folderOf(p.id))),
+		publications: summary.publications.map((p) => publicationView(p, destinationOf(p.id))),
 		issues: summary.issues,
 		publicInNoPublication: summary.publicInNoPublication,
 		...unsettled.length > 0 ? { unsettled } : {}
@@ -18247,10 +18917,10 @@ async function createPublication(graph, args, host) {
 		await settle$1(graph);
 	}
 	const after = summarisePublishing((await graph.publishing.readSource()).source).publications.find((p) => p.id === id);
-	const folderOf = await foldersFor(graph, env);
+	const destinationOf = await destinationsFor(graph, env);
 	return {
 		created: true,
-		publication: after ? publicationView(after, folderOf(id)) : {
+		publication: after ? publicationView(after, destinationOf(id)) : {
 			id,
 			page: concept
 		}
@@ -18272,8 +18942,14 @@ async function updatePublication(graph, args, host) {
 	await updatePublicationPage(frontmatterStore(graph), current.concept, current, changes);
 	await settle$1(graph);
 	const after = summarisePublishing((await graph.publishing.readSource()).source).publications.find((p) => p.id === current.id);
-	const folderOf = await foldersFor(graph, env);
-	return { publication: publicationView(after ?? current, folderOf(current.id)) };
+	const destinationOf = await destinationsFor(graph, env);
+	return { publication: publicationView(after ?? current, destinationOf(current.id)) };
+}
+/** A GitHub refusal or a refused branch, as this host words it: the token is an environment variable here. */
+function repositoryRefusal(error, repo) {
+	if (error instanceof GitHubError) return new ToolError("github_refused", `${describeGitHubError(error, repo, { replaceToken: "Make a new one and set ETHERPK_GITHUB_TOKEN to it." })} Nothing was published.`);
+	if (error instanceof Error && /knowledge graph/.test(error.message)) return new ToolError("repository_holds_graph", `${error.message} Nothing was published.`);
+	return error;
 }
 /** How many items fall under each key. */
 function countBy(items, keyOf) {
@@ -18307,12 +18983,13 @@ async function publish(graph, args, host) {
 	const summary = summarisePublishing(source);
 	const publication = summary.publications.find((p) => p.id === args.id.trim());
 	if (!publication) throw publicationNotFound(args.id, summary.publications, via);
-	const folder = (await foldersFor(graph, env))(publication.id);
+	const { folder, repository } = (await destinationsFor(graph, env))(publication.id);
 	const dryRun = args.dryRun === true;
-	if (!folder && !dryRun) {
-		const where = graph.backend.kind === "folder" ? `--folder "${graph.backend.path}"` : `--graph "${graph.name}"`;
-		throw new ToolError("no_publish_folder", `No publish folder is set for "${publication.name}" on this machine. Ask the user to run: ${cmd} publish ${where} --publication ${publication.id} --out <dir> - that publishes once and remembers the folder for this tool.`);
-	}
+	const where = graph.backend.kind === "folder" ? `--folder "${graph.backend.path}"` : `--graph "${graph.name}"`;
+	if (repository && !dryRun && via === "agent") throw new ToolError("publishes_to_repository", `"${publication.name}" publishes to the GitHub repository ${repositoryLabel(repository)}, and an agent's publish never commits to a repository, because a commit there can deploy the site. Use dryRun to check it. To publish it, ask the user to run: ${cmd} publish ${where} --publication ${publication.id}`);
+	const token = env.ETHERPK_GITHUB_TOKEN?.trim();
+	if (repository && !dryRun && !token) throw new ToolError("no_github_token", `"${publication.name}" publishes to ${repositoryLabel(repository)}, and ETHERPK_GITHUB_TOKEN is not set. Set it to a GitHub token that may read and write the repository's Contents. Nothing was published.`);
+	if (!folder && !repository && !dryRun) throw new ToolError("no_publish_folder", via === "cli" ? `No publish folder or repository is set for "${publication.name}" on this machine. Run: ${cmd} publish ${where} --publication ${publication.id} --out <dir>, or --github <owner/name> - either is remembered.` : `No publish folder is set for "${publication.name}" on this machine. Ask the user to run: ${cmd} publish ${where} --publication ${publication.id} --out <dir> - that publishes once and remembers the folder for this tool.`);
 	if (folder && !dryRun) await checkPublishFolder(graph, publication.id, folder, host);
 	const selected = selectDocuments(source.documents, publication, summary.publications);
 	const includeTexts = Object.values(publication.includes).map((concept) => source.documents.find((d) => d.concept.toLowerCase() === concept.toLowerCase())?.text ?? "");
@@ -18342,12 +19019,33 @@ async function publish(graph, args, host) {
 				renderer,
 				maps
 			}),
-			unsettled
+			unsettled,
+			destination: repository ? "repository" : "folder"
 		});
+		let committed = null;
+		if (run.report.ok && repository && !dryRun) {
+			try {
+				committed = await publishToRepository(createGitHubApi({
+					token,
+					baseUrl: env.ETHERPK_GITHUB_API_URL?.trim() || void 0
+				}), repository, {
+					publicationId: publication.id,
+					bundle: run.bundle,
+					seeded: run.seeded,
+					agentsMd: run.agentsMd
+				}, { confirmed: args.replace === true });
+			} catch (error) {
+				throw repositoryRefusal(error, repository);
+			}
+			if (committed.state === "needs-confirmation") {
+				const listed = committed.replaced.slice(0, 10).join(", ") + (committed.replaced.length > 10 ? ` and ${committed.replaced.length - 10} more` : "");
+				throw new ToolError("repository_needs_confirmation", `${repositoryLabel(repository)} does not hold this site yet, and publishing would replace or delete ${committed.replaced.length} file${committed.replaced.length === 1 ? "" : "s"} there that it did not write: ${listed}. Nothing was committed. Run the command again with --replace to publish anyway. The old versions stay in the branch's history.`);
+			}
+		}
 		const written = run.report.ok && folder && !dryRun ? await writeSite(nodeSiteFolder(folder), run.bundle, {
 			seeded: run.seeded,
 			agentsMd: run.agentsMd
-		}) : null;
+		}) : committed?.written ?? null;
 		const excludedByReason = {};
 		for (const e of run.report.excluded) excludedByReason[e.reason] = (excludedByReason[e.reason] ?? 0) + 1;
 		return {
@@ -18355,6 +19053,10 @@ async function publish(graph, args, host) {
 			...dryRun ? { dryRun: true } : {},
 			publication: run.report.publication,
 			folder,
+			...repository ? {
+				repository: repositoryLabel(repository),
+				commit: committed?.state === "committed" ? committed.commit.url : null
+			} : {},
 			written: written ? {
 				written: written.written,
 				unchanged: written.unchanged,
@@ -18413,15 +19115,19 @@ function cliPublishOutput(result) {
 async function publishingInfo(graph, host) {
 	const { env, cmd } = hostOf$1(host);
 	const { source } = await graph.publishing.readSource();
-	const folderOf = await foldersFor(graph, env);
+	const destinationOf = await destinationsFor(graph, env);
 	const chromium = await chromiumStatus(env, cmd);
 	return {
-		publications: summarisePublishing(source).publications.map((p) => ({
-			id: p.id,
-			name: p.name,
-			kind: p.kind,
-			publishFolder: folderOf(p.id)
-		})),
+		publications: summarisePublishing(source).publications.map((p) => {
+			const { folder, repository } = destinationOf(p.id);
+			return {
+				id: p.id,
+				name: p.name,
+				kind: p.kind,
+				publishFolder: folder,
+				publishRepository: repository ? repositoryLabel(repository) : null
+			};
+		}),
 		mermaid: {
 			available: chromium.executable !== null,
 			...chromium.executable ? {} : { setup: chromium.setupCommand }
@@ -19784,6 +20490,7 @@ async function runGraphHost(deps) {
 				return startSession(socket, request, reply);
 			case "publish":
 			case "publish-check":
+			case "publish-github":
 				if (stopping) return answer({ etherpk: "stopping" });
 				return runPublish(request, answer);
 			default: return answer({
@@ -23295,7 +24002,7 @@ function describeFilesystemSaveFailure(error, concept) {
 //#endregion
 //#region src/headless-documents.ts
 /** The document's text after its frontmatter block, and where that block ends. */
-function bodyOf(text) {
+function bodyOf$1(text) {
 	const head = frontmatterSpan(text)?.end ?? 0;
 	return {
 		head,
@@ -23310,16 +24017,16 @@ function bodyOf(text) {
 function bodyView(handle) {
 	return {
 		id: handle.id,
-		getText: () => bodyOf(handle.getText()).body,
+		getText: () => bodyOf$1(handle.getText()).body,
 		applyChange(change, origin) {
-			const { head } = bodyOf(handle.getText());
+			const { head } = bodyOf$1(handle.getText());
 			handle.applyChange({
 				from: change.from + head,
 				to: change.to + head,
 				insert: change.insert
 			}, origin);
 		},
-		subscribe: (listener) => handle.subscribe((text) => listener(bodyOf(text).body))
+		subscribe: (listener) => handle.subscribe((text) => listener(bodyOf$1(text).body))
 	};
 }
 //#endregion
@@ -23445,6 +24152,34 @@ function createBreather(now = () => performance.now()) {
 	};
 }
 //#endregion
+//#region ../client/src/lib/storage/server/duplicate-names.ts
+/** A document's text below its [[Frontmatter]] block, if it has one. */
+function bodyOf(text) {
+	return text.slice(frontmatterSpan(text)?.end ?? 0);
+}
+/**
+* The text a Merge leaves in the first document: its own text whole, then each other document's
+* text below its block, after a blank line, in the order given. Every other document's identity is
+* already the first one's, and its aliases join in the registry, so its block adds nothing.
+*
+* Always the first text followed by an addition, so the store writes it as an append: an edit made
+* meanwhile on another device anywhere in the first document is kept.
+*/
+function mergedText(texts) {
+	let merged = texts[0] ?? "";
+	for (const other of texts.slice(1)) {
+		const body = bodyOf(other).replace(/^\s+/, "");
+		if (body === "") continue;
+		if (merged.trim() === "") {
+			merged += body;
+			continue;
+		}
+		const separator = merged.endsWith("\n\n") ? "" : merged.endsWith("\n") ? "\n" : "\n\n";
+		merged += separator + body;
+	}
+	return merged;
+}
+//#endregion
 //#region ../client/src/lib/storage/server/server-document-store.ts
 /**
 * ServerDocumentStore (plan Phase 3 Task 6): the DocumentStore seam over the E2EE sync
@@ -23462,6 +24197,12 @@ function createServerDocumentStore(graph, options) {
 	const ENGINE_BATCH = 100;
 	/** Longest a cold-empty document holds its loading state waiting for first catchup. */
 	const COLD_CONTENT_TIMEOUT_MS = 15e3;
+	/**
+	* Longest a create waits, while connected, for the registry (and a journal's own document) to
+	* catch up before it checks the name again (ADR 0157). Long enough for a reconnect's first
+	* pages, short enough that a slow relay does not hold up a person who is typing.
+	*/
+	const CREATE_CONFIRM_MS = 5e3;
 	const breathe = createBreather();
 	const changeListeners = /* @__PURE__ */ new Set();
 	const docsChangedListeners = /* @__PURE__ */ new Set();
@@ -23470,6 +24211,16 @@ function createServerDocumentStore(graph, options) {
 	/** docId to the name it had when first seen renamed from elsewhere, and its latest name. */
 	const renamesFromElsewhere = /* @__PURE__ */ new Map();
 	const resurrectionClaims = /* @__PURE__ */ new Map();
+	/**
+	* Journal entries this device started before its registry had caught up (ADR 0157). A derived
+	* id can already be a registry key that another device set and then deleted while this one was
+	* away. Two concurrent sets of one Y.Map key keep one of them, and when the kept one is the
+	* deleted one, this device's entry goes too: its text would be in the document but no name
+	* would reach it. A claim sets the entry again when that happens, until the registry has
+	* caught up once with this device connected, after which a delete is someone's decision.
+	*/
+	const creationClaims = /* @__PURE__ */ new Map();
+	const stopClaimWatches = /* @__PURE__ */ new Set();
 	let disposed = false;
 	/** Whether the encrypted registry has been read to its terminal relay page this session. */
 	let registryConfirmed = false;
@@ -23555,10 +24306,21 @@ function createServerDocumentStore(graph, options) {
 	/**
 	* Every name a document answers to, to its docId. A page's own name outranks another page's
 	* alias of the same name, whatever order the registry lists them in, as the index resolves it.
+	*
+	* A name that more than one document answers to (a [[Duplicate Name]], ADR 0157) keeps the
+	* document it opened before, while that document still answers to it. The registry lists a key
+	* that arrived by sync last, so without this a duplicate arriving would move every open tab
+	* and link of the name onto the other device's document, and two devices would each open the
+	* other's. A name moves only when its document leaves it: deleted, merged or renamed away.
 	*/
-	function currentDocIds() {
+	function currentDocIds(previous) {
 		const out = /* @__PURE__ */ new Map();
-		registry.forEach((entry, docId) => out.set(conceptKey(conceptOf(entry)), docId));
+		registry.forEach((entry, docId) => {
+			const key = conceptKey(conceptOf(entry));
+			const held = out.get(key);
+			if (held !== void 0 && previous?.get(key) === held) return;
+			out.set(key, docId);
+		});
 		registry.forEach((entry, docId) => {
 			for (const alias of entry.aliases ?? []) {
 				const key = conceptKey(alias);
@@ -23597,7 +24359,7 @@ function createServerDocumentStore(graph, options) {
 			const next = currentConcepts();
 			for (const [key, concept] of known) if (!next.has(key) && !renamedAway.has(key)) removedListeners.forEach((l) => l(concept));
 			known = next;
-			docIdsByConcept = currentDocIds();
+			docIdsByConcept = currentDocIds(docIdsByConcept);
 			knownRegistry = nextRegistry;
 			docsChangedListeners.forEach((l) => l());
 			if (!restored) {
@@ -23618,6 +24380,16 @@ function createServerDocumentStore(graph, options) {
 			}
 			for (const [docId, change] of event.changes.keys) {
 				if (change.action !== "delete") continue;
+				const created = creationClaims.get(docId);
+				if (created) queueMicrotask(() => {
+					if (registry.has(docId) || !creationClaims.has(docId)) return;
+					const engine = graph.docSync(docId);
+					if (engine.lifecycle() === "deleting" || engine.doc.getText("content").length === 0) {
+						creationClaims.delete(docId);
+						return;
+					}
+					registry.set(docId, created);
+				});
 				const claimed = resurrectionClaims.get(docId);
 				if (!claimed) continue;
 				queueMicrotask(() => {
@@ -23832,7 +24604,7 @@ function createServerDocumentStore(graph, options) {
 				registryConfirmed = true;
 			}
 			known = currentConcepts();
-			docIdsByConcept = currentDocIds();
+			docIdsByConcept = currentDocIds(docIdsByConcept);
 			knownRegistry = currentRegistryIdentities();
 		},
 		listDocuments() {
@@ -23856,6 +24628,9 @@ function createServerDocumentStore(graph, options) {
 			pages.sort((a, b) => a.concept.localeCompare(b.concept));
 			return [...journals, ...pages];
 		},
+		documentIdOf(target) {
+			return docIdFor(target);
+		},
 		listIdentities() {
 			const out = [];
 			registry.forEach((entry, docId) => {
@@ -24126,26 +24901,83 @@ function createServerDocumentStore(graph, options) {
 				materialised.release();
 			}
 		},
+		async mergeDuplicates(docIds, expected, mergeOptions) {
+			const timeoutMs = mergeOptions?.timeoutMs ?? COLD_CONTENT_TIMEOUT_MS;
+			const [first, ...others] = docIds;
+			if (!first || others.length === 0 || !oneName(docIds)) return "gone";
+			if (!graph.isConnected()) return "offline";
+			if (!await confirmRegistry(timeoutMs)) return "unconfirmed";
+			const materialised = await materialise(docIds, timeoutMs);
+			try {
+				if (!oneName(docIds)) return "gone";
+				if (materialised.unconfirmed.length > 0) return "unconfirmed";
+				const texts = docIds.map((id) => graph.docSync(id).doc.getText("content").toString());
+				if (texts.some((text) => documentProtection(text).kind === "document")) return "protected";
+				if (docIds.some((id, index) => texts[index] !== expected.get(id))) return "changed";
+				const firstText = texts[0];
+				const addition = mergedText(["", ...texts.slice(1)]);
+				if (addition !== "" && !firstText.endsWith(addition)) {
+					const merged = mergedText(texts);
+					const ytext = graph.docSync(first).doc.getText("content");
+					ytext.doc.transact(() => ytext.insert(firstText.length, merged.slice(firstText.length)), STORE);
+				}
+				const firstEntry = registry.get(first);
+				const aliases = others.reduce((union, id) => mergeDocuments({
+					body: "",
+					aliases: union
+				}, {
+					body: "",
+					aliases: registry.get(id)?.aliases ?? []
+				}).aliases, firstEntry.aliases ?? []);
+				if (aliases.length !== (firstEntry.aliases ?? []).length) writeAliases(first, firstEntry, aliases);
+				if (!await acknowledged(first, timeoutMs)) return "not-acknowledged";
+				if (others.filter((id, index) => graph.docSync(id).doc.getText("content").toString() !== texts[index + 1]).length > 0 || !oneName(docIds)) return "changed-after-append";
+				for (const id of others) {
+					creationClaims.delete(id);
+					await graph.deleteDoc(id);
+					registry.delete(id);
+				}
+				return "merged";
+			} finally {
+				materialised.release();
+			}
+		},
 		async reconcile() {},
 		async resolveConflict() {},
-		async createJournal(date, body = "") {
+		async createJournal(date, body = "", createOptions) {
 			const day = date.trim();
 			if (!isJournalConcept(day)) throw new Error(`"${date}" is not a calendar day.`);
+			await confirmBeforeCreate();
 			if (docIdFor(day)) throw new Error(`A document for "${day}" already exists`);
-			const docId = crypto.randomUUID();
-			registry.set(docId, {
+			const docId = await graph.journalDocId(day);
+			const engine = graph.docSync(docId);
+			await graph.whenReady(docId);
+			const connected = graph.isConnected();
+			const caughtUp = connected && await reachedWithin(graph.caughtUpDoc(docId), CREATE_CONFIRM_MS);
+			if (docIdFor(day)) throw new Error(`A document for "${day}" already exists`);
+			const entry = {
 				kind: "journal",
 				date: day
-			});
-			if (body !== "") {
-				const ytext = graph.docSync(docId).doc.getText("content");
-				ytext.doc.transact(() => ytext.insert(0, body));
-			}
+			};
+			registry.set(docId, entry);
+			engine.claimCreation();
+			if (!caughtUp) holdCreationClaim(docId, entry);
+			const ytext = engine.doc.getText("content");
+			if (!connected && ytext.length > 0) ytext.doc.transact(() => ytext.delete(0, ytext.length), STORE);
+			else if (connected && !caughtUp && ytext.length > 0) console.warn(`[sync] "${day}" was started before its document caught up; its earlier text is kept`);
+			const template = createOptions?.template ?? "";
+			if (template !== "" && body.startsWith(template)) {
+				await seedTemplate(docId, template);
+				const rest = body.slice(template.length);
+				if (rest !== "") ytext.doc.transact(() => ytext.insert(template.length, rest));
+			} else if (body !== "") ytext.doc.transact(() => ytext.insert(0, body));
 			return day;
 		},
 		async createPage(title, body = "") {
 			if (isJournalConcept(title)) throw new Error(dayIsNotAPageName(title));
 			if (docIdFor(title)) throw new Error(`A page for "${title}" already exists`);
+			await confirmBeforeCreate();
+			if (docIdFor(title)) throw new Error(`A page for "${title}" already exists`);
 			const docId = crypto.randomUUID();
 			registry.set(docId, {
 				kind: "page",
@@ -24232,6 +25064,7 @@ function createServerDocumentStore(graph, options) {
 		async deleteDocument(concept) {
 			const docId = docIdFor(concept);
 			if (!docId) return;
+			creationClaims.delete(docId);
 			await graph.deleteDoc(docId);
 			registry.delete(docId);
 		},
@@ -24241,10 +25074,90 @@ function createServerDocumentStore(graph, options) {
 			unobserveDocUpdates();
 			for (const stop of resurrectors.values()) stop();
 			resurrectors.clear();
+			for (const stop of stopClaimWatches) stop();
+			stopClaimWatches.clear();
 			await graph.flushAll();
 			graph.dispose();
 		}
 	};
+	/**
+	* Confirm before create (ADR 0157): while connected, wait (bounded) for the registry's current
+	* catch-up, so a name another device created moments ago is seen before a second document is
+	* made for it. A reconnect starts a new catch-up cycle a microtask after the socket opens,
+	* which the yield lets begin. Offline nothing can arrive, and the create goes ahead at once.
+	*/
+	async function confirmBeforeCreate() {
+		if (!graph.isConnected()) return;
+		await Promise.resolve();
+		await reachedWithin(graph.rootCaughtUp(), CREATE_CONFIRM_MS);
+	}
+	/**
+	* Seed a [[Journal Template]] as one Yjs update whose client id is derived from the document,
+	* its generation and the template's text (ADR 0157). Two devices that start the day with the
+	* same template produce the same struct, which the CRDT keeps once. The generation keeps a day
+	* started again after a delete from reusing the struct the deleted generation held. If the
+	* struct is already here and deleted (a device's cached copy of that generation), it adds
+	* nothing, and the template is inserted as an ordinary edit instead.
+	*/
+	async function seedTemplate(docId, template) {
+		const engine = graph.docSync(docId);
+		const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(`${docId}\n${engine.generation()}\n${template}`)));
+		const seed = new Y.Doc();
+		seed.clientID = new DataView(digest.buffer).getUint32(0);
+		seed.getText("content").insert(0, template);
+		Y.applyUpdate(engine.doc, Y.encodeStateAsUpdate(seed), STORE);
+		seed.destroy();
+		const ytext = engine.doc.getText("content");
+		if (!ytext.toString().startsWith(template)) ytext.doc.transact(() => ytext.insert(0, template), STORE);
+	}
+	/** Whether every one of `docIds` is still in the registry under one name. */
+	function oneName(docIds) {
+		const keys = /* @__PURE__ */ new Set();
+		for (const id of docIds) {
+			const entry = registry.get(id);
+			if (!entry) return false;
+			keys.add(conceptKey(conceptOf(entry)));
+		}
+		return keys.size === 1;
+	}
+	/**
+	* Send a document's pending edits and wait, bounded, until the relay has acknowledged every
+	* one of them: what a Merge waits for before it deletes anything. False when it has not.
+	*/
+	async function acknowledged(docId, timeoutMs) {
+		const engine = graph.docSync(docId);
+		await engine.flush();
+		const deadline = Date.now() + timeoutMs;
+		while (engine.unsentOperations() > 0) {
+			if (disposed || Date.now() >= deadline) return false;
+			await new Promise((resolve) => setTimeout(resolve, 50));
+		}
+		return true;
+	}
+	/**
+	* Keep a creation claim until the registry has caught up once with this device connected
+	* (`creationClaims`). Every concurrent set this device's entry could lose to is then here.
+	*/
+	function holdCreationClaim(docId, entry) {
+		creationClaims.set(docId, entry);
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			stop();
+			stopClaimWatches.delete(stop);
+			(async () => {
+				await Promise.resolve();
+				await graph.rootCaughtUp();
+				if (creationClaims.get(docId) === entry) creationClaims.delete(docId);
+			})().catch(() => {});
+		};
+		const stop = graph.onActivity((activity) => {
+			if (activity.connection === "open") release();
+		});
+		stopClaimWatches.add(stop);
+		if (graph.isConnected()) release();
+	}
 	async function confirmRegistry(timeoutMs = 5e3) {
 		if (registryConfirmed) return true;
 		if (!graph.isConnected()) return false;
@@ -24626,7 +25539,7 @@ async function openHeadlessGraph(deps) {
 						continue;
 					}
 					if (documentProtection(read.text).kind === "document") continue;
-					bodies.set(identity.concept, bodyOf(read.text).body);
+					bodies.set(identity.concept, bodyOf$1(read.text).body);
 				}
 				return {
 					bodies,
@@ -25818,7 +26731,7 @@ function bindServeLifetime(deps) {
 *   etherpk-mcp stop   [--graph <id or name> [--sync-server <url>] | --folder <path> | --all]
 *   etherpk-mcp logout [--sync-server <url> | --all]
 *   etherpk-mcp semantic setup | status | remove
-*   etherpk-mcp publish (--graph <id or name> | --folder <path>) --publication <id> [--out <dir> | --dry-run]
+*   etherpk-mcp publish (--graph <id or name> | --folder <path>) --publication <id> [--out <dir> | --github <owner/name[#branch]> | --dry-run] [--replace]
 *   etherpk-mcp diagrams setup | status
 *
 * One config file holds a login per Sync Server (ADR 0075). `--sync-server` names the one a
@@ -25889,8 +26802,9 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
       to a service to be embedded.
   ${CMD} semantic status | remove
       Whether it is set up here, or delete it (logout --all deletes it too).
-  ${CMD} publish (--graph <id or name> | --folder <path>) --publication <id> [--out <dir> | --dry-run]
-      Publish one publication of a graph to a folder on this machine and print the report.
+  ${CMD} publish (--graph <id or name> | --folder <path>) --publication <id> [--out <dir> | --github <owner/name[#branch]> | --dry-run] [--replace]
+      Publish one publication of a graph to a folder on this machine, or to a branch of a
+      GitHub repository, and print the report.
       --out sets the publish folder for that graph and publication and is remembered: from
       then on this command without --out, and the agent's publish tool, write to the same
       folder (the agent cannot choose one). It must be a folder of its own, outside the
@@ -25898,6 +26812,13 @@ var USAGE = `etherpk-mcp - EtherPK Headless Client (an MCP server over one synce
       and feed files) are rewritten and their strays removed - everything else in it is left
       alone. Publishing writes files - deploying them (a git push, say) is yours. Run it from
       cron for a site that republishes itself.
+      --github commits the site to the repository's branch (main unless #branch says) as one
+      commit, with the token in ETHERPK_GITHUB_TOKEN, and is remembered in place of a folder.
+      The host watching the branch then deploys it. The same files are owned and the rest of
+      the branch is left alone. A publish never creates the branch. The agent's publish tool
+      never commits to a repository: this command is how a publication there is published.
+      --replace lets a first publish replace files on a branch that does not hold this site
+      yet, which it otherwise lists and refuses.
       --dry-run renders and checks the publication and prints the whole report, with the
       names of the pages it mentions, but writes nothing and needs no folder. Keep its output
       out of public logs.
@@ -26308,19 +27229,32 @@ async function publishCommand(args) {
 	if (!publication) fail("publish needs --publication <id>. The agent's list_publications tool, or Settings → Publish in EtherPK, shows the ids.");
 	const dryRun = args["dry-run"] === true;
 	const out = args.out?.trim();
-	if (dryRun && out) fail("publish --dry-run writes nothing, so it takes no --out. Leave --out off, or drop --dry-run to publish.");
+	const githubArg = args.github?.trim();
+	if (dryRun && (out || githubArg)) fail("publish --dry-run writes nothing, so it takes no --out or --github. Leave them off, or drop --dry-run to publish.");
+	if (out && githubArg) fail("publish takes --out or --github, not both: a publication publishes to one place on this machine.");
+	const github = githubArg ? parseRepositoryArgument(githubArg) : null;
+	if (githubArg && !github) fail(`--github takes owner/name, or owner/name#branch, such as you/garden-site#main ("${githubArg}" is not one).`);
 	const found = await findGraph(request).catch((error) => fail(`etherpk-mcp: ${describeError(error)}`));
 	const env = publishSettings(process.env);
+	const replace = args.replace === true ? { replace: true } : {};
 	const { reply, socket } = await requestHost(launcherFor(found), dryRun ? {
 		etherpk: "publish-check",
 		protocol: 1,
 		publication,
 		env
+	} : github ? {
+		etherpk: "publish-github",
+		protocol: 1,
+		publication,
+		github,
+		...replace,
+		env
 	} : {
 		etherpk: "publish",
 		protocol: 1,
 		publication,
 		...out ? { out: resolve(out) } : {},
+		...replace,
 		env
 	}).catch((error) => fail(`etherpk-mcp: ${describeError(error)}`));
 	socket.destroy();
@@ -26332,7 +27266,7 @@ async function publishCommand(args) {
 			return;
 		case "refused": return fail(reply.message);
 		case "failed":
-			if (dryRun && reply.message === "The request was not understood.") return fail(`etherpk-mcp: this graph is served on this computer by an older etherpk-mcp, which cannot run a dry run. Run: ${CMD} stop, then try again.`);
+			if ((dryRun || github) && reply.message === "The request was not understood.") return fail(`etherpk-mcp: this graph is served on this computer by an older etherpk-mcp, which cannot ${dryRun ? "run a dry run" : "publish to a repository"}. Run: ${CMD} stop, then try again.`);
 			return fail(`etherpk-mcp: ${reply.message}`);
 		case "unsupported": return fail(`etherpk-mcp: this graph is served on this computer by etherpk-mcp ${reply.version}, which cannot run a publish for this version (${VERSION}). Run: ${CMD} stop, then publish again.`);
 		default: return fail(`etherpk-mcp: the graph's background process gave an answer this version does not know ("${reply.etherpk}").`);
@@ -26340,9 +27274,10 @@ async function publishCommand(args) {
 }
 /**
 * A command-line publish, as the graph's host runs it: the publication first, so a mistyped id is
-* never remembered as a publish folder, then `--out` checked against the graph's folder and
-* remembered, then the publish the agent's tool runs. The answer is what the command prints, in
-* its own words.
+* never remembered as a destination, then `--out` checked against the graph's folder, or
+* `--github` checked as a repository, and remembered, then the publish the agent's tool runs, as
+* the person (`via: 'cli'`), which may commit to a repository. The answer is what the command
+* prints, in its own words.
 */
 async function publishInHost(graph, request) {
 	const env = withPublishSettings(process.env, request.env ?? {});
@@ -26368,15 +27303,29 @@ async function publishInHost(graph, request) {
 		await findPublication(graph, request.publication, host);
 		const configPath = defaultPublishFoldersPath(env);
 		const key = publishGraphKey(graph.backend, graph.graphId);
-		if (request.out) {
+		if (request.etherpk === "publish-github") {
+			const repo = parseRepositoryArgument(`${request.github.owner}/${request.github.name}#${request.github.branch}`);
+			if (!repo) return {
+				etherpk: "refused",
+				message: "etherpk-mcp: --github takes owner/name, or owner/name#branch."
+			};
+			await writePublishFolders(configPath, withPublishRepository(await readPublishFolders(configPath), key, request.publication, repo));
+			notes.push(`etherpk-mcp: "${request.publication}" of "${graph.name}" now publishes to ${repositoryLabel(repo)} (remembered in ${configPath}, in place of any folder).`);
+		} else if (request.out) {
 			await checkPublishFolder(graph, request.publication, request.out, host);
 			await writePublishFolders(configPath, withPublishFolder(await readPublishFolders(configPath), key, request.publication, request.out));
 			notes.push(`etherpk-mcp: publish folder for "${request.publication}" of "${graph.name}" set to ${request.out} (remembered in ${configPath}).`);
-		} else if (!publishFolderOf(await readPublishFolders(configPath), key, request.publication)) return {
-			etherpk: "refused",
-			message: `No publish folder is set for "${request.publication}" of "${graph.name}" on this machine. Pass --out <dir> once - it is remembered.`
-		};
-		const result = await publish(graph, { id: request.publication }, host);
+		} else {
+			const remembered = await readPublishFolders(configPath);
+			if (!publishFolderOf(remembered, key, request.publication) && !publishRepositoryOf(remembered, key, request.publication)) return {
+				etherpk: "refused",
+				message: `No publish folder or repository is set for "${request.publication}" of "${graph.name}" on this machine. Pass --out <dir> or --github <owner/name> once - it is remembered.`
+			};
+		}
+		const result = await publish(graph, {
+			id: request.publication,
+			replace: request.replace === true
+		}, host);
 		return {
 			etherpk: "published",
 			output: cliPublishOutput(result),
@@ -26892,6 +27841,8 @@ async function main() {
 			"no-semantic": { type: "boolean" },
 			publication: { type: "string" },
 			out: { type: "string" },
+			github: { type: "string" },
+			replace: { type: "boolean" },
 			"dry-run": { type: "boolean" },
 			all: { type: "boolean" },
 			name: { type: "string" },