@appsoftwareltd/etherpk-mcp 0.14.1 → 0.15.0

package/dist/main.js

@@ -717,7 +717,7 @@ function looksLikeAgentSetupCode(value) {
 }
 var package_default = {
 	name: "@appsoftwareltd/etherpk-mcp",
-	version: "0.14.1",
+	version: "0.15.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",
@@ -4201,8 +4201,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);
@@ -11258,8 +11258,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 +11269,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 +11629,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 +11647,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 +11675,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 +12613,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",
@@ -14464,7 +14913,7 @@ async function runPublish(publication, deps) {
 	return {
 		report,
 		bundle,
-		seeded: seededFiles(publication),
+		seeded: seededFiles(publication, deps.destination),
 		agentsMd: (existing) => agentsMdWithManagedSection(existing, publication)
 	};
 }
@@ -14987,14 +15436,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 +15484,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 +15524,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 +15590,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 +18619,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 +18687,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 +18703,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 +18721,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 +18769,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 +18794,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 +18835,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 +18871,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 +18905,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 +18967,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 +20342,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({
@@ -25818,7 +26377,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 +26448,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 +26458,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 +26875,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 +26912,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 +26920,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 +26949,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 +27487,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" },