diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
new file mode 100644
index 0000000..677bdf6
--- /dev/null
+++ b/.github/workflows/test.yml
@@ -0,0 +1,33 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Node ${{ matrix.node }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22, 24]
+        os: [ubuntu-latest]
+        include:
+          - node: 24
+            os: windows-latest
+          - node: 24
+            os: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npm pack --dry-run --ignore-scripts
diff --git a/README.md b/README.md
index 0be1a0b..3ff3648 100644
--- a/README.md
+++ b/README.md
@@ -7,6 +7,7 @@ npx pageleaf guide.md
 npx pageleaf ./docs --title "Project manual" --theme grove
 npx pageleaf ./docs --layout sidebar
 npx pageleaf notes.txt --out ./public --open
+npx pageleaf ./docs --upload my-org/my-docs
 ```
 
 Requires Node.js 20 or newer.
@@ -19,6 +20,7 @@ Requires Node.js 20 or newer.
 | `--theme <name>` | Use `paper`, `midnight`, `grove`, `ocean`, or `contrast` |
 | `--layout <name>` | Use `standard` (the default horizontal section navigation plus page sidebar) or `sidebar` (a single left hierarchy with non-clickable section groups and page links) |
 | `--out <folder>` | Choose the output folder |
+| `--upload <[owner/]repo>` | Upload the HTML file to a GitHub repository's root on its default branch |
 | `--open` | Open the generated site |
 | `--force` | Replace an existing output file |
 
@@ -26,6 +28,10 @@ A file named `guide.md` produces `guide.html`. A folder named `docs` produces `d
 
 Relative links and images remain unchanged, so they resolve from the generated HTML file. The site needs internet access to load its pinned Markdown-it dependency.
 
+For uploads, install [Git](https://git-scm.com/downloads) and [GitHub CLI](https://cli.github.com/), then run `gh auth login --hostname github.com`. Use `--upload my-docs` for the signed-in user's personal account, or `--upload my-org/my-docs` for an explicit owner. The repository must already exist and permit direct pushes; an empty repository is supported.
+
+Uploads keep the generated filename (`docs.html` in the example), replace that remote file automatically, and leave other files unchanged. Identical content creates no commit. Commits use the signed-in account's GitHub noreply identity. `--force` controls local output replacement only. If an upload fails, the local HTML remains available; fix the reported problem and rerun with `--force`. Uploading stores the file in GitHub; it does not configure GitHub Pages.
+
 ## License
 
 [MIT](LICENSE)
diff --git a/lib/errors.js b/lib/errors.js
new file mode 100644
index 0000000..194ee80
--- /dev/null
+++ b/lib/errors.js
@@ -0,0 +1,14 @@
+export class PageleafError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = 'PageleafError';
+    this.exitCode = exitCode;
+  }
+}
+
+export class UsageError extends PageleafError {
+  constructor(message) {
+    super(message, 2);
+    this.name = 'UsageError';
+  }
+}
diff --git a/lib/pageleaf.js b/lib/pageleaf.js
index 5e1ec0a..92a8a26 100644
--- a/lib/pageleaf.js
+++ b/lib/pageleaf.js
@@ -4,6 +4,10 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
+import { PageleafError, UsageError } from './errors.js';
+import { parseUploadTarget, uploadHtml } from './upload.js';
+
+export { PageleafError, UsageError } from './errors.js';
 
 const require = createRequire(import.meta.url);
 
@@ -14,21 +18,6 @@ export const LAYOUTS = ['standard', 'sidebar'];
 const MARKDOWN_OPEN = '<script id="markdown-source" type="text/plain">';
 const filenameCollator = new Intl.Collator('en', { numeric: true, sensitivity: 'base' });
 
-export class PageleafError extends Error {
-  constructor(message, exitCode = 1) {
-    super(message);
-    this.name = 'PageleafError';
-    this.exitCode = exitCode;
-  }
-}
-
-export class UsageError extends PageleafError {
-  constructor(message) {
-    super(message, 2);
-    this.name = 'UsageError';
-  }
-}
-
 export const HELP = `Usage: pageleaf <file-or-folder> [options]
 
 Turn one or more UTF-8 text files into a navigable HTML site.
@@ -38,6 +27,7 @@ Options:
   --theme <name>    Initial theme: ${THEMES.join(', ')}
   --layout <name>   Navigation layout: ${LAYOUTS.join(', ')} (default: standard)
   --out <folder>    Output folder (default: current directory)
+  --upload <[owner/]repo>  Upsert the HTML file in a GitHub repo's root on its default branch
   --open            Open the generated site in the default browser
   --force           Replace an existing output file
   -h, --help        Show this help
@@ -46,7 +36,14 @@ Options:
 Examples:
   pageleaf guide.md
   pageleaf ./docs --title "Project manual" --theme grove
-  pageleaf notes.txt --out ./public --open`;
+  pageleaf notes.txt --out ./public --open
+  pageleaf guide.md --upload my-docs
+  pageleaf ./docs --upload my-org/my-docs
+
+Upload requires git and gh, authenticated with "gh auth login --hostname github.com".
+Omit owner to use the signed-in user's personal account. The repository must exist
+and allow direct pushes. Remote files are replaced automatically; --force only
+controls replacing the local output. Unchanged uploads do not create a commit.`;
 
 function cleanTitle(value, label = 'Title') {
   const title = String(value ?? '').replace(/\s+/g, ' ').trim();
@@ -299,6 +296,7 @@ export function parseCommandLine(args) {
         theme: { type: 'string' },
         layout: { type: 'string', default: 'standard' },
         out: { type: 'string' },
+        upload: { type: 'string' },
         open: { type: 'boolean' },
         force: { type: 'boolean' },
         help: { type: 'boolean', short: 'h' },
@@ -313,6 +311,7 @@ export function parseCommandLine(args) {
   if (parsed.positionals.length !== 1) throw new UsageError('Provide exactly one input file or folder.');
   if (parsed.values.title !== undefined) cleanTitle(parsed.values.title);
   if (parsed.values.out !== undefined && !parsed.values.out.trim()) throw new UsageError('Output folder must contain visible text.');
+  if (parsed.values.upload !== undefined) parseUploadTarget(parsed.values.upload);
   if (parsed.values.theme !== undefined && !THEMES.includes(parsed.values.theme)) {
     throw new UsageError(`Unknown theme "${parsed.values.theme}". Choose one of: ${THEMES.join(', ')}.`);
   }
@@ -346,6 +345,14 @@ export async function run(args, io = console) {
 
   const result = await generateSite(parsed.positionals[0], parsed.values);
   io.log(`Created ${result.outputPath}`);
+  if (parsed.values.upload !== undefined) {
+    try {
+      result.upload = await uploadHtml(result.outputPath, parsed.values.upload);
+      io.log(`${result.upload.changed ? 'Uploaded' : 'Already up to date:'} ${result.upload.url}`);
+    } catch (error) {
+      throw new PageleafError(`${error.message}\nGenerated HTML remains at "${result.outputPath}". After fixing the problem, rerun the same command with --force to retry.`);
+    }
+  }
   if (parsed.values.open) {
     try {
       await openInBrowser(result.outputPath);
diff --git a/lib/upload.js b/lib/upload.js
new file mode 100644
index 0000000..8364bde
--- /dev/null
+++ b/lib/upload.js
@@ -0,0 +1,165 @@
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { PageleafError, UsageError } from './errors.js';
+
+const LOGIN_HELP = 'Run "gh auth login --hostname github.com" (or "gh auth switch --hostname github.com" to select another account), then retry.';
+const TARGET_HELP = 'Use --upload repo or --upload owner/repo, for example --upload my-org/my-docs. Supply a repository name, not a URL.';
+
+export function parseUploadTarget(target) {
+  const parts = typeof target === 'string' ? target.split('/') : [];
+  const repo = parts.at(-1);
+  const owner = parts.length === 2 ? parts[0] : undefined;
+  if (parts.length < 1 || parts.length > 2 || !/^[A-Za-z0-9_.-]+$/.test(repo ?? '')
+      || repo === '.' || repo === '..'
+      || (owner !== undefined && !/^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/.test(owner))) {
+    throw new UsageError(`Invalid upload target "${target}". ${TARGET_HELP}`);
+  }
+  return { owner, repo };
+}
+
+// No shell interpolation, interactive prompts, or unbounded child processes.
+export function executeUploadCommand(command, args, options = {}) {
+  const { input, ...childOptions } = options;
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, args, {
+      encoding: 'utf8', timeout: 120_000, maxBuffer: 2 * 1024 * 1024,
+      windowsHide: true, ...childOptions
+    }, (error, stdout, stderr) => {
+      if (error) reject(error);
+      else resolve({ stdout, stderr });
+    });
+    // A failed child can close stdin before consuming the HTML.
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}
+
+function errorDetail(error) {
+  const detail = error.killed ? 'The command timed out after two minutes.'
+    : String(error.stderr?.trim() || error.message || error);
+  return detail.replace(/(?:gh[pousr]_[A-Za-z0-9]+|github_pat_[A-Za-z0-9_]+)/g, '[redacted]')
+    .replace(/(https?:\/\/)[^\s/@]+@/g, '$1[redacted]@').slice(0, 2000);
+}
+
+function uploadEnvironment() {
+  const env = { ...process.env };
+  // Git may have launched Pageleaf from a hook or another worktree. Never inherit
+  // those repository/index/object locations into the temporary repository.
+  for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE',
+    'GIT_OBJECT_DIRECTORY', 'GIT_ALTERNATE_OBJECT_DIRECTORIES', 'GIT_NAMESPACE',
+    'GIT_SHALLOW_FILE', 'GIT_CONFIG', 'GIT_CONFIG_PARAMETERS', 'GIT_CONFIG_COUNT']) delete env[key];
+  return { ...env, GIT_TERMINAL_PROMPT: '0', GIT_LITERAL_PATHSPECS: '1', GH_PROMPT_DISABLED: '1', GH_HOST: 'github.com', GH_PAGER: 'cat' };
+}
+
+export async function uploadHtml(outputPath, target, { execute = executeUploadCommand, tempRoot = os.tmpdir() } = {}) {
+  const { owner, repo } = parseUploadTarget(target);
+  const env = uploadEnvironment();
+  let temporary;
+  let failure;
+  let stage = 'prepare the upload';
+  let nextSteps = 'Check local file permissions and available disk space, then retry.';
+
+  async function command(binary, args, options = {}) {
+    try {
+      return await execute(binary, args, { cwd: temporary, env, ...options });
+    } catch (error) {
+      if (error.code === 'ENOENT') {
+        throw new PageleafError(binary === 'gh'
+          ? 'GitHub CLI (gh) was not found. Install it from https://cli.github.com/, ensure gh is on PATH, then run "gh auth login --hostname github.com".'
+          : 'Git was not found. Install it from https://git-scm.com/downloads, ensure git is on PATH, and retry.');
+      }
+      throw error;
+    }
+  }
+
+  async function json(args) {
+    return JSON.parse((await command('gh', ['api', '--hostname', 'github.com', ...args])).stdout);
+  }
+
+  try {
+    temporary = await mkdtemp(path.join(tempRoot, 'pageleaf-upload-'));
+    await command('gh', ['--version']);
+    await command('git', ['--version']);
+    stage = 'identify the signed-in GitHub user';
+    nextSteps = `${LOGIN_HELP} Check your network connection if GitHub cannot be reached.`;
+    const user = await json(['user']);
+    if (!/^[A-Za-z0-9-]+$/.test(user.login ?? '') || !Number.isSafeInteger(user.id) || user.id <= 0) {
+      throw new Error('GitHub returned an invalid user profile.');
+    }
+    const requested = `${owner ?? user.login}/${repo}`;
+    stage = `access GitHub repository "${requested}"`;
+    nextSteps = `Check the repository name and your network connection. Run "gh repo view ${requested}" to verify access. If it does not exist, create it with "gh repo create ${requested} --private" (or --public), then retry. ${LOGIN_HELP}`;
+    const repository = await json([`repos/${requested}`]);
+    if (typeof repository.full_name !== 'string' || !parseUploadTarget(repository.full_name).owner
+        || typeof repository.default_branch !== 'string' || !repository.default_branch) {
+      throw new Error('GitHub returned invalid repository metadata. Update gh and retry.');
+    }
+    const fullName = repository.full_name;
+    if (repository.archived || repository.disabled) {
+      throw new PageleafError(`Repository "${fullName}" is archived or disabled. Ask its owner to restore write access, or choose another --upload repository.`);
+    }
+    if (repository.permissions?.push === false) {
+      throw new PageleafError(`You do not have push access to "${fullName}". Ask its owner for write access and authorize your gh credentials for this repository (including organization SSO, if required), or choose another repository.`);
+    }
+
+    const gitOptions = ['-c', 'credential.helper=', '-c', 'credential.https://github.com.helper=!gh auth git-credential',
+      '-c', `core.hooksPath=${path.join(temporary, 'no-hooks')}`, '-c', 'commit.gpgSign=false'];
+    const gitDirectory = path.join(temporary, 'repository.git');
+    const git = (args, options) => command('git', [...gitOptions, `--git-dir=${gitDirectory}`, ...args], options);
+    stage = `clone "${fullName}"`;
+    nextSteps = `Check your network connection and repository access with "gh repo view ${fullName}". ${LOGIN_HELP}`;
+    await command('git', [...gitOptions, 'clone', '--bare', '--depth=1', '--single-branch', '--',
+      `https://github.com/${fullName}.git`, gitDirectory]);
+
+    stage = 'prepare the HTML commit';
+    nextSteps = 'Check that the generated HTML is still readable, and check available disk space and temporary-directory permissions. Update Git and gh, then retry.';
+    let parent;
+    try {
+      parent = (await git(['rev-parse', '--verify', '--quiet', 'HEAD'])).stdout.trim();
+    } catch (error) {
+      if (error.code !== 1) throw error;
+    }
+    // An empty GitHub repository may not advertise HEAD; use its configured
+    // default branch for the initial commit instead of the local Git default.
+    const branch = parent ? (await git(['symbolic-ref', '--short', 'HEAD'])).stdout.trim() : repository.default_branch;
+    await git(['check-ref-format', `refs/heads/${branch}`]);
+    await git(parent ? ['read-tree', parent] : ['read-tree', '--empty']);
+    const filename = path.basename(outputPath);
+    if (parent && (await git(['ls-tree', '-z', parent, '--', filename])).stdout.startsWith('040000 tree ')) {
+      throw new PageleafError(`Remote path "${filename}" is a directory. Rename the input file or folder to produce a different HTML filename, or choose another --upload repository.`);
+    }
+    const html = await readFile(outputPath);
+    // Write the exact bytes directly into Git's index: no checkout, symlink
+    // traversal, attributes/filters, or changes to any other repository file.
+    const blob = (await git(['hash-object', '-w', '--stdin'], { input: html })).stdout.trim();
+    await git(['update-index', '--add', '--cacheinfo', '100644', blob, filename]);
+    const tree = (await git(['write-tree'])).stdout.trim();
+    const previousTree = parent ? (await git(['rev-parse', `${parent}^{tree}`])).stdout.trim() : null;
+    const url = `https://github.com/${fullName}/blob/${branch.split('/').map(encodeURIComponent).join('/')}/${encodeURIComponent(filename)}`;
+    if (tree === previousTree) return { changed: false, url, repository: fullName, branch };
+
+    const identity = { ...env, GIT_AUTHOR_NAME: user.login, GIT_COMMITTER_NAME: user.login,
+      GIT_AUTHOR_EMAIL: `${user.id}+${user.login}@users.noreply.github.com`,
+      GIT_COMMITTER_EMAIL: `${user.id}+${user.login}@users.noreply.github.com` };
+    const commit = (await git(['commit-tree', tree, ...(parent ? ['-p', parent] : []), '-m', `Update ${filename} with Pageleaf`], { env: identity })).stdout.trim();
+    stage = `push "${filename}" to "${fullName}" on branch "${branch}"`;
+    nextSteps = 'Check your network, write permissions, token repository access, and organization SSO authorization. If branch protection requires a pull request, upload to a repository that permits direct pushes or commit the generated file through a pull request manually. If the branch changed during upload, retry to include its latest changes. If the connection was lost, check GitHub first: the push may already have succeeded.';
+    await git(['push', 'origin', `${commit}:refs/heads/${branch}`]);
+    return { changed: true, url, repository: fullName, branch };
+  } catch (error) {
+    failure = error instanceof PageleafError ? error : new PageleafError(`Could not ${stage}: ${errorDetail(error)}\n${nextSteps}`);
+    throw failure;
+  } finally {
+    if (temporary) {
+      try {
+        await rm(temporary, { recursive: true, force: true });
+      } catch (error) {
+        const message = `Could not remove temporary upload directory "${temporary}": ${errorDetail(error)}. Remove this directory manually. The remote upload may already have completed; check GitHub before retrying.`;
+        if (failure) failure.message += `\n${message}`;
+        else throw new PageleafError(message);
+      }
+    }
+  }
+}
diff --git a/test/upload.test.js b/test/upload.test.js
new file mode 100644
index 0000000..bb72457
--- /dev/null
+++ b/test/upload.test.js
@@ -0,0 +1,213 @@
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import test from 'node:test';
+
+import { parseCommandLine, UsageError } from '../lib/pageleaf.js';
+import { executeUploadCommand, uploadHtml } from '../lib/upload.js';
+
+const execFileAsync = promisify(execFile);
+const executable = path.resolve(import.meta.dirname, '../bin/pageleaf.js');
+
+async function fixture(t, { empty = false, branch = 'docs/current' } = {}) {
+  const root = await mkdtemp(path.join(os.tmpdir(), 'pageleaf-upload-test-'));
+  t.after(() => rm(root, { recursive: true, force: true }));
+  const temporary = path.join(root, 'temporary');
+  const remote = path.join(root, 'remote.git');
+  const seed = path.join(root, 'seed');
+  const output = path.join(root, 'guide with spaces.html');
+  await mkdir(temporary);
+  const env = { ...process.env, GIT_CONFIG_GLOBAL: path.join(root, 'no-global-config'),
+    GIT_CONFIG_NOSYSTEM: '1', GIT_AUTHOR_NAME: 'Fixture', GIT_COMMITTER_NAME: 'Fixture',
+    GIT_AUTHOR_EMAIL: 'fixture@example.test', GIT_COMMITTER_EMAIL: 'fixture@example.test',
+    GIT_AUTHOR_DATE: '2026-09-12T10:00:00Z', GIT_COMMITTER_DATE: '2026-09-12T10:00:00Z' };
+  const git = async (args, cwd = seed) => (await executeUploadCommand('git', args, { cwd, env })).stdout.trim();
+  await git(['init', '--bare', `--initial-branch=${branch}`, remote], root);
+  await git(['init', `--initial-branch=${branch}`, seed], root);
+  await git(['remote', 'add', 'origin', remote]);
+  if (!empty) {
+    await writeFile(path.join(seed, 'keep.txt'), 'Keep this file unchanged.\n');
+    // Uploads must bypass .gitignore and clean filters, preserving exact bytes.
+    await writeFile(path.join(seed, '.gitignore'), '*.html\n');
+    await writeFile(path.join(seed, '.gitattributes'), '*.html text eol=lf\n');
+    await git(['add', '.']);
+    await git(['commit', '-m', 'Initial files']);
+    await git(['push', 'origin', branch]);
+  }
+  await writeFile(output, '<html>First version\r\n</html>\r\n');
+  const calls = [];
+  const execute = async (command, args, options) => {
+    calls.push({ command, args, options });
+    if (command === 'gh') {
+      if (args[0] === '--version') return { stdout: 'gh version fixture', stderr: '' };
+      if (args.at(-1) === 'user') return { stdout: JSON.stringify({ login: 'signed-in-user', id: 123 }), stderr: '' };
+      return { stdout: JSON.stringify({ full_name: 'team/docs', default_branch: branch, permissions: { push: true } }), stderr: '' };
+    }
+    const rewritten = [...args];
+    if (args.includes('clone')) rewritten[rewritten.length - 2] = pathToFileURL(remote).href;
+    return executeUploadCommand(command, rewritten, { ...options, env: { ...options.env,
+      GIT_CONFIG_GLOBAL: env.GIT_CONFIG_GLOBAL, GIT_CONFIG_NOSYSTEM: '1' } });
+  };
+  const upload = (target = 'team/docs', executor = execute, file = output) => uploadHtml(file, target, { execute: executor, tempRoot: temporary });
+  const remoteGit = (args) => git([`--git-dir=${remote}`, ...args], root);
+  const count = async () => Number(await remoteGit(['rev-list', '--count', `refs/heads/${branch}`]));
+  return { root, temporary, remote, seed, output, calls, execute, upload, git, remoteGit, count, branch };
+}
+
+test('upload target parsing accepts a repo or owner/repo and rejects malformed targets', () => {
+  for (const target of ['docs', 'my-org/docs.site', 'user/repo_name']) {
+    assert.equal(parseCommandLine(['guide.md', '--upload', target]).values.upload, target);
+  }
+  assert.equal(parseCommandLine(['guide.md', '--upload=-repo']).values.upload, '-repo');
+  for (const target of ['', ' ', '.', '..', '/repo', 'owner/', 'a/b/c', 'https://github.com/a/b',
+    'a b', 'a\\b', 'a/repo?x', 'a/repo#x', '-owner/repo', 'owner-/repo', '$(whoami)']) {
+    assert.throws(() => parseCommandLine(['guide.md', `--upload=${target}`]), UsageError, target);
+  }
+  assert.throws(() => parseCommandLine(['guide.md', '--upload']), UsageError);
+});
+
+test('Git upload inserts, overwrites, and skips unchanged bytes while preserving other files', async (t) => {
+  const f = await fixture(t);
+  // Dirty local files and the local index must survive every upload.
+  await writeFile(path.join(f.seed, 'keep.txt'), 'Local staged work');
+  await f.git(['add', 'keep.txt']);
+  const localStatus = await f.git(['status', '--porcelain']);
+  const first = await f.upload('docs');
+  assert.equal(first.changed, true);
+  assert.equal(first.branch, 'docs/current');
+  assert.match(first.url, /team\/docs\/blob\/docs\/current\/guide%20with%20spaces.html$/);
+  assert.ok(f.calls.some(({ args }) => args.at(-1) === 'repos/signed-in-user/docs'));
+  assert.equal(await f.count(), 2);
+  assert.equal(await f.remoteGit(['show', 'HEAD:keep.txt']), 'Keep this file unchanged.');
+  assert.equal(await f.remoteGit(['show', 'HEAD:guide with spaces.html']), '<html>First version\r\n</html>');
+  assert.equal(await f.remoteGit(['log', '-1', '--format=%ae']), '123+signed-in-user@users.noreply.github.com');
+  assert.equal(await f.remoteGit(['diff-tree', '--no-commit-id', '--name-only', '-r', 'HEAD']), 'guide with spaces.html');
+  assert.equal((await f.upload()).changed, false);
+  assert.equal(await f.count(), 2);
+
+  await writeFile(f.output, '<html>Replacement</html>');
+  assert.equal((await f.upload()).changed, true);
+  assert.equal(await f.remoteGit(['show', 'HEAD:guide with spaces.html']), '<html>Replacement</html>');
+  assert.equal(await f.count(), 3);
+  assert.equal(await f.git(['status', '--porcelain']), localStatus);
+  assert.equal(await f.git(['show', ':keep.txt']), 'Local staged work');
+  assert.deepEqual(await readdir(f.temporary), []);
+  for (const { command, args, options } of f.calls) {
+    assert.equal(options.env.GIT_TERMINAL_PROMPT, '0');
+    assert.equal(options.env.GH_PROMPT_DISABLED, '1');
+    if (command === 'git' && args.includes('push')) assert.ok(!args.includes('--force'));
+  }
+});
+
+test('an existing empty repository receives an initial commit on its configured default branch', async (t) => {
+  const f = await fixture(t, { empty: true, branch: 'site' });
+  assert.equal((await f.upload()).branch, 'site');
+  assert.equal(await f.count(), 1);
+  assert.equal(await f.remoteGit(['ls-tree', '--name-only', 'refs/heads/site']), 'guide with spaces.html');
+  assert.deepEqual(await readdir(f.temporary), []);
+});
+
+test('a remote symlink becomes a regular HTML file without changing its former target', async (t) => {
+  const f = await fixture(t);
+  const blob = (await executeUploadCommand('git', ['hash-object', '-w', '--stdin'], { cwd: f.seed, input: 'keep.txt' })).stdout.trim();
+  await f.git(['update-index', '--add', '--cacheinfo', '120000', blob, 'guide with spaces.html']);
+  await f.git(['commit', '-m', 'Add symlink']);
+  await f.git(['push', 'origin', f.branch]);
+  await f.upload();
+  assert.match(await f.remoteGit(['ls-tree', 'HEAD', 'guide with spaces.html']), /^100644 blob/);
+  assert.equal(await f.remoteGit(['show', 'HEAD:keep.txt']), 'Keep this file unchanged.');
+});
+
+test('concurrent remote commits cause a safe rejection; retry preserves the concurrent change', async (t) => {
+  const f = await fixture(t);
+  let concurrent = false;
+  await assert.rejects(() => f.upload('team/docs', async (command, args, options) => {
+    if (command === 'git' && args.includes('push') && !concurrent) {
+      concurrent = true;
+      await writeFile(path.join(f.seed, 'concurrent.txt'), 'Another contributor');
+      await f.git(['add', 'concurrent.txt']);
+      await f.git(['commit', '-m', 'Concurrent change']);
+      await f.git(['push', 'origin', f.branch]);
+    }
+    return f.execute(command, args, options);
+  }), /branch changed during upload, retry/);
+  assert.equal(await f.count(), 2);
+  assert.equal(await f.remoteGit(['show', 'HEAD:concurrent.txt']), 'Another contributor');
+  await f.upload();
+  assert.equal(await f.count(), 3);
+  assert.equal(await f.remoteGit(['show', 'HEAD:concurrent.txt']), 'Another contributor');
+  assert.deepEqual(await readdir(f.temporary), []);
+});
+
+test('a directory with the output filename is preserved and the error explains how to rename the output', async (t) => {
+  const f = await fixture(t);
+  await mkdir(path.join(f.seed, 'guide with spaces.html'));
+  await writeFile(path.join(f.seed, 'guide with spaces.html', 'keep.txt'), 'Keep this directory');
+  await f.git(['add', '-f', 'guide with spaces.html/keep.txt']);
+  await f.git(['commit', '-m', 'Directory at upload path']);
+  await f.git(['push', 'origin', f.branch]);
+  await assert.rejects(() => f.upload(), /is a directory.*Rename the input/);
+  assert.equal(await f.count(), 2);
+  assert.equal(await f.remoteGit(['show', 'HEAD:guide with spaces.html/keep.txt']), 'Keep this directory');
+  assert.deepEqual(await readdir(f.temporary), []);
+});
+
+test('missing tools, auth, repositories, permissions, transport, and unexpected errors have next steps', async (t) => {
+  const f = await fixture(t);
+  const scenarios = [
+    { match: (c, a) => c === 'gh' && a[0] === '--version', error: { code: 'ENOENT' }, expected: /GitHub CLI.*not found.*Install.*gh auth login/ },
+    { match: (c, a) => c === 'git' && a[0] === '--version', error: { code: 'ENOENT' }, expected: /Git was not found.*Install.*PATH/ },
+    { match: (c, a) => c === 'gh' && a.at(-1) === 'user', error: { code: 1, stderr: 'Bad credentials' }, expected: /identify.*Bad credentials[\s\S]*gh auth login/ },
+    { match: (c, a) => c === 'gh' && a.at(-1)?.startsWith('repos/'), error: { code: 1, stderr: 'HTTP 404' }, expected: /HTTP 404[\s\S]*gh repo create team\/docs --private/ },
+    { match: (c, a) => c === 'gh' && a.at(-1)?.startsWith('repos/'), json: { full_name: 'team/docs', default_branch: 'main', permissions: { push: false } }, expected: /do not have push access[\s\S]*write access/ },
+    { match: (c, a) => c === 'gh' && a.at(-1)?.startsWith('repos/'), json: { full_name: 'team/docs', default_branch: 'main', archived: true }, expected: /archived or disabled.*restore write access/ },
+    { match: (c, a) => c === 'git' && a.includes('clone'), error: { code: 128, stderr: 'Could not resolve host' }, expected: /clone.*Could not resolve host[\s\S]*network connection/ },
+    { match: (c, a) => c === 'git' && a.includes('push'), error: { code: 1, stderr: 'GH013: Repository rule violations' }, expected: /GH013[\s\S]*branch protection.*pull request/ },
+    { match: (c, a) => c === 'git' && a.includes('push'), error: { killed: true }, expected: /timed out[\s\S]*push may already have succeeded/ },
+    { match: (c, a) => c === 'git' && a.includes('write-tree'), error: { stderr: 'disk full' }, expected: /disk full[\s\S]*disk space/ },
+    { match: (c, a) => c === 'gh' && a.at(-1) === 'user', stdout: 'unexpected response', expected: /Could not identify[\s\S]*gh auth login/ }
+  ];
+  for (const scenario of scenarios) {
+    await assert.rejects(() => f.upload('team/docs', (command, args, options) => {
+      if (!scenario.match(command, args)) return f.execute(command, args, options);
+      if (scenario.error) throw Object.assign(new Error('Test command failed'), scenario.error);
+      return Promise.resolve({ stdout: scenario.stdout ?? JSON.stringify(scenario.json), stderr: '' });
+    }), scenario.expected);
+    assert.deepEqual(await readdir(f.temporary), []);
+  }
+  assert.equal(await f.count(), 1, 'failed uploads did not change the remote');
+});
+
+test('filesystem failures retain context and credentials are redacted from command errors', async (t) => {
+  const f = await fixture(t);
+  await assert.rejects(() => uploadHtml(f.output, 'team/docs', { tempRoot: path.join(f.root, 'missing') }), /prepare the upload[\s\S]*permissions/);
+  await assert.rejects(() => f.upload('team/docs', f.execute, path.join(f.root, 'missing.html')), /prepare the HTML commit[\s\S]*permissions/);
+  await assert.rejects(() => f.upload('team/docs', (command, args, options) => {
+    if (args.includes('clone')) throw new Error('Failed https://secret@github.com/team/docs.git ghp_secret github_pat_secret');
+    return f.execute(command, args, options);
+  }), (error) => !error.message.includes('secret') && error.message.includes('[redacted]'));
+  assert.deepEqual(await readdir(f.temporary), []);
+});
+
+test('the executable documents upload, validates usage, and preserves HTML after a missing-tool failure', async (t) => {
+  const f = await fixture(t);
+  const { stdout } = await execFileAsync(process.execPath, [executable, '--help']);
+  assert.match(stdout, /--upload <\[owner\/\]repo>/);
+  await assert.rejects(() => execFileAsync(process.execPath, [executable, 'missing.md', '--upload', 'a/b/c']),
+    (error) => error.code === 2 && /Invalid upload target/.test(error.stderr));
+  const input = path.join(f.root, 'guide.md');
+  await writeFile(input, '# Guide\n\nHello.');
+  const env = { ...process.env, PATH: f.temporary };
+  // Windows environment keys are case insensitive.
+  for (const key of Object.keys(env)) if (key.toUpperCase() === 'PATH' && key !== 'PATH') delete env[key];
+  await assert.rejects(() => execFileAsync(process.execPath, [executable, input, '--upload', 'docs'], { cwd: f.root, env }),
+    (error) => error.code === 1 && /GitHub CLI.*not found/.test(error.stderr)
+      && /Generated HTML remains/.test(error.stderr) && /--force/.test(error.stderr));
+  assert.match(await readFile(path.join(f.root, 'guide.html'), 'utf8'), /# Guide/);
+  // Normal generation must not require Git or gh.
+  await execFileAsync(process.execPath, [executable, input, '--force'], { cwd: f.root, env });
+});