From 57f93e86c91fb102cc1e34be4ec87e58e0d2908e Mon Sep 17 00:00:00 2001
From: Eugene Kalinin <e.v.kalinin@gmail.com>
Date: Sun, 27 Sep 2026 22:05:01 +0300
Subject: [PATCH 1/4] docs(openspec): archive fix-remote-first-heading change

---
 .../.openspec.yaml                            |  0
 .../design.md                                 |  0
 .../proposal.md                               |  0
 .../specs/remote-toc/spec.md                  |  0
 .../tasks.md                                  |  0
 openspec/specs/remote-toc/spec.md             | 59 +++++++++++++++++++
 6 files changed, 59 insertions(+)
 rename openspec/changes/{fix-remote-first-heading => archive/2026-09-27-fix-remote-first-heading}/.openspec.yaml (100%)
 rename openspec/changes/{fix-remote-first-heading => archive/2026-09-27-fix-remote-first-heading}/design.md (100%)
 rename openspec/changes/{fix-remote-first-heading => archive/2026-09-27-fix-remote-first-heading}/proposal.md (100%)
 rename openspec/changes/{fix-remote-first-heading => archive/2026-09-27-fix-remote-first-heading}/specs/remote-toc/spec.md (100%)
 rename openspec/changes/{fix-remote-first-heading => archive/2026-09-27-fix-remote-first-heading}/tasks.md (100%)
 create mode 100644 openspec/specs/remote-toc/spec.md

diff --git a/openspec/changes/fix-remote-first-heading/.openspec.yaml b/openspec/changes/archive/2026-09-27-fix-remote-first-heading/.openspec.yaml
similarity index 100%
rename from openspec/changes/fix-remote-first-heading/.openspec.yaml
rename to openspec/changes/archive/2026-09-27-fix-remote-first-heading/.openspec.yaml
diff --git a/openspec/changes/fix-remote-first-heading/design.md b/openspec/changes/archive/2026-09-27-fix-remote-first-heading/design.md
similarity index 100%
rename from openspec/changes/fix-remote-first-heading/design.md
rename to openspec/changes/archive/2026-09-27-fix-remote-first-heading/design.md
diff --git a/openspec/changes/fix-remote-first-heading/proposal.md b/openspec/changes/archive/2026-09-27-fix-remote-first-heading/proposal.md
similarity index 100%
rename from openspec/changes/fix-remote-first-heading/proposal.md
rename to openspec/changes/archive/2026-09-27-fix-remote-first-heading/proposal.md
diff --git a/openspec/changes/fix-remote-first-heading/specs/remote-toc/spec.md b/openspec/changes/archive/2026-09-27-fix-remote-first-heading/specs/remote-toc/spec.md
similarity index 100%
rename from openspec/changes/fix-remote-first-heading/specs/remote-toc/spec.md
rename to openspec/changes/archive/2026-09-27-fix-remote-first-heading/specs/remote-toc/spec.md
diff --git a/openspec/changes/fix-remote-first-heading/tasks.md b/openspec/changes/archive/2026-09-27-fix-remote-first-heading/tasks.md
similarity index 100%
rename from openspec/changes/fix-remote-first-heading/tasks.md
rename to openspec/changes/archive/2026-09-27-fix-remote-first-heading/tasks.md
diff --git a/openspec/specs/remote-toc/spec.md b/openspec/specs/remote-toc/spec.md
new file mode 100644
index 0000000..6854371
--- /dev/null
+++ b/openspec/specs/remote-toc/spec.md
@@ -0,0 +1,59 @@
+# remote-toc Specification
+
+## Purpose
+
+Generates a table of contents for a remote GitHub page (a file or a wiki page) given by
+its URL, with anchors identical to the ones GitHub renders for that page.
+
+## Requirements
+
+### Requirement: TOC for a remote GitHub page
+
+For a GitHub file (`/blob/`) URL or a GitHub wiki page URL, the TOC SHALL contain one
+entry per heading of the rendered document, in document order, including the first
+heading when the document starts with a heading. Each entry SHALL have the form
+`* [<heading text>](#<anchor>)`, indented by `(level - 1) * indent` spaces (indent is
+3 by default). No entry SHALL contain markup of the GitHub page around the document or
+link to anything other than a heading anchor of the document.
+
+#### Scenario: File that starts with a heading
+
+- **WHEN** the user runs `gh-md-toc https://github.com/ekalinin/sitemap.js/blob/6bc3eb12c898c1037a35a11b2eb24ababdeb3580/README.md`
+- **THEN** the output is `Table of Contents`, `=================`,
+  `* [sitemap.js](#sitemapjs)`, `   * [Installation](#installation)`,
+  `   * [Usage](#usage)`, `   * [License](#license)`, and
+  `<!-- Created by https://github.com/ekalinin/github-markdown-toc -->` (ignoring empty
+  lines)
+
+#### Scenario: File with non-English headings
+
+- **WHEN** the user runs `gh-md-toc https://github.com/ekalinin/envirius/blob/f939d3b6882bfb6ecb28ef7b6e62862f934ba945/README.ru.md`
+- **THEN** the first entries are `* [envirius](#envirius)`, `   * [Идея](#идея)`,
+  `   * [Особенности](#особенности)`, `* [Установка](#установка)`
+
+#### Scenario: File that does not start with a heading
+
+- **WHEN** the user runs `gh-md-toc https://github.com/jlevy/the-art-of-command-line/blob/217da3b4fa751014ecc122fd9fede2328a7eeb3e/README-pt.md`
+- **THEN** the first entries are
+  `* [A arte da linha de comando](#a-arte-da-linha-de-comando)`, `   * [Meta](#meta)`,
+  `   * [Básico](#básico)`, `   * [Uso diário](#uso-diário)`
+
+#### Scenario: Wiki page
+
+- **WHEN** the user runs `gh-md-toc https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv`
+- **THEN** the first entries are `* [Who Uses Nodeenv?](#who-uses-nodeenv)`,
+  `   * [edx](#edx)`, `   * [OpenStack](#openstack)`
+
+### Requirement: Remote page among multiple inputs
+
+When more than one input is given, the entries of a remote page SHALL follow the same
+rules, with each link prefixed by the page URL: `* [<heading text>](<URL>#<anchor>)`.
+
+#### Scenario: Local file and remote file
+
+- **WHEN** the user runs `gh-md-toc README.md https://github.com/ekalinin/sitemap.js/blob/6bc3eb12c898c1037a35a11b2eb24ababdeb3580/README.md`
+- **THEN** the README entries are followed by
+  `* [sitemap.js](https://github.com/ekalinin/sitemap.js/blob/6bc3eb12c898c1037a35a11b2eb24ababdeb3580/README.md#sitemapjs)`,
+  `   * [Installation](https://github.com/ekalinin/sitemap.js/blob/6bc3eb12c898c1037a35a11b2eb24ababdeb3580/README.md#installation)`,
+  `   * [Usage](https://github.com/ekalinin/sitemap.js/blob/6bc3eb12c898c1037a35a11b2eb24ababdeb3580/README.md#usage)`,
+  `   * [License](https://github.com/ekalinin/sitemap.js/blob/6bc3eb12c898c1037a35a11b2eb24ababdeb3580/README.md#license)`

From 6a690cdba9631eccdbd79f169caaf31af819b234 Mon Sep 17 00:00:00 2001
From: Eugene Kalinin <e.v.kalinin@gmail.com>
Date: Sun, 27 Sep 2026 22:09:52 +0300
Subject: [PATCH 2/4] docs(openspec): add landing spec and add-landing-page
 archive

---
 .../.openspec.yaml                            |   2 +
 .../2026-09-27-add-landing-page/design.md     | 234 ++++++++++++++
 .../2026-09-27-add-landing-page/proposal.md   |  69 +++++
 .../specs/landing/spec.md                     | 291 ++++++++++++++++++
 .../2026-09-27-add-landing-page/tasks.md      |  56 ++++
 openspec/specs/landing/spec.md                | 291 ++++++++++++++++++
 6 files changed, 943 insertions(+)
 create mode 100644 openspec/changes/archive/2026-09-27-add-landing-page/.openspec.yaml
 create mode 100644 openspec/changes/archive/2026-09-27-add-landing-page/design.md
 create mode 100644 openspec/changes/archive/2026-09-27-add-landing-page/proposal.md
 create mode 100644 openspec/changes/archive/2026-09-27-add-landing-page/specs/landing/spec.md
 create mode 100644 openspec/changes/archive/2026-09-27-add-landing-page/tasks.md
 create mode 100644 openspec/specs/landing/spec.md

diff --git a/openspec/changes/archive/2026-09-27-add-landing-page/.openspec.yaml b/openspec/changes/archive/2026-09-27-add-landing-page/.openspec.yaml
new file mode 100644
index 0000000..7f2ad57
--- /dev/null
+++ b/openspec/changes/archive/2026-09-27-add-landing-page/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-27
diff --git a/openspec/changes/archive/2026-09-27-add-landing-page/design.md b/openspec/changes/archive/2026-09-27-add-landing-page/design.md
new file mode 100644
index 0000000..9b12820
--- /dev/null
+++ b/openspec/changes/archive/2026-09-27-add-landing-page/design.md
@@ -0,0 +1,234 @@
+# Design
+
+## Context
+
+See proposal.md for motivation and specs/landing/spec.md for requirements.
+
+Current state that shapes the approach:
+
+- GitHub Pages is not enabled for the repository; there is no `docs/`, no `gh-pages`
+  branch, and no user site repository, so the page is a project site under
+  `/github-markdown-toc/`.
+- The version is single-sourced in `gh_toc_version` (`gh-md-toc`). `make release`
+  and the `--version` bats test both depend on it.
+- README installs from `master` (`raw.githubusercontent.com/.../master/gh-md-toc`),
+  so what a visitor downloads is always master's version.
+- Releases are created by hand; `dockerimage.yml` pushes `evkalinin/gh-md-toc:<tag>`
+  when a release is published. Docker Hub tags equal the release tags, which equal
+  `gh_toc_version`.
+- Remote mode is broken for GitHub file URLs (#166); wiki URLs work. Checked with
+  0.10.0: `./gh-md-toc README.md https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv`
+  produces a correct TOC for both inputs.
+- `tests/tests.bats` pins README's headings, so README-based example output stays
+  valid while the tests pass.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- No build tooling in the repository: two hand-written files plus one workflow.
+- Deployment needs only the default `GITHUB_TOKEN`, with no extra secrets.
+- Every version on the page comes from `gh_toc_version`, with no second copy in the
+  repository.
+
+**Non-Goals:**
+
+- A local build target in `Makefile`; local preview is a plain static file.
+- Automated checks of the page in CI (link checking, HTML validation).
+- Automatic refresh of example outputs or action versions shown on the page.
+
+## Decisions
+
+### Deploy through GitHub Actions, not from a branch
+
+The workflow uploads the built `site/` as a Pages artifact and deploys it with
+`actions/deploy-pages`.
+
+- Alternative: "Deploy from a branch" with `master:/docs`. Rejected: it serves files
+  as-is, so the version would have to be copied into the HTML and bumped by hand,
+  which breaks single-sourcing.
+- Alternative: a `gh-pages` branch. Rejected: same version problem, and page changes
+  would bypass pull requests on `master`.
+- Alternative: fetch the version in the browser at runtime. Rejected: an external
+  request, which the spec forbids.
+
+### Source folder `site/`
+
+- Alternative: `docs/`. Rejected: implies documentation (README remains the docs)
+  and is the folder name for branch-based deploys, which this design does not use.
+- Alternative: repository root. Rejected: mixes page files with the tool.
+
+Files: `site/index.html` (content, sidebar, inline copy script) and
+`site/styles.css`. No separate JavaScript file: the copy script is a few lines.
+
+### Version substitution at deploy time
+
+`site/index.html` contains the placeholder `{{VERSION}}` (hero, Docker section). The
+workflow:
+
+1. `VERSION="$(./gh-md-toc --version | head -n 1)"`
+2. copies `site/` to `_site/` and writes `_site/index.html` with
+   `sed "s|{{VERSION}}|$VERSION|g" site/index.html > _site/index.html` (a pipe, not
+   `sed -i`, to stay portable between GNU and BSD sed when run locally)
+3. fails if `grep -n '{{' _site/index.html` finds anything
+
+- Why `--version`: it is the tool's public interface and is covered by the
+  `--version` bats test.
+- Alternative: parse the `gh_toc_version=` line with a regex. Rejected: it depends on
+  the assignment's formatting, and the `Makefile` regex already requires a
+  two-digit minor.
+
+### Triggers track `master`, not releases
+
+`on: push` to `master` with `paths: [site/**, gh-md-toc, .github/workflows/pages.yml]`,
+plus `workflow_dispatch`. No `pull_request` trigger.
+
+- Why: installation downloads master's `gh-md-toc`, so the page shows the version a
+  visitor actually gets. A version bump changes `gh-md-toc` and redeploys the page.
+- Alternative: `on: release`. Rejected: between a bump and the release, the page
+  would show an older version than the installation commands download.
+
+Workflow settings: `permissions: {contents: read, pages: write, id-token: write}`;
+`concurrency: {group: pages, cancel-in-progress: false}`; the deploy job uses the
+`github-pages` environment. Actions (checked 2026-09-27): `actions/checkout@v7`,
+`actions/configure-pages@v6`, `actions/upload-pages-artifact@v5`,
+`actions/deploy-pages@v5`.
+
+### Pages is enabled once by hand
+
+Pages is enabled manually with Source "GitHub Actions" (Settings -> Pages, or
+`gh api -X POST repos/ekalinin/github-markdown-toc/pages -f build_type=workflow`).
+
+- Alternative: `configure-pages` with `enablement: true`. Rejected: per its
+  `action.yml`, it requires a token other than `GITHUB_TOKEN` (a PAT or GitHub App),
+  which would add a secret.
+
+### Page structure and headings
+
+One `h1` and `h2`/`h3` sections, so the sidebar matches gh-md-toc's output for a
+markdown document with the same headings:
+
+```
+* [gh-md-toc](#gh-md-toc)
+   * [Installation](#installation)
+   * [Why](#why)
+   * [Usage](#usage)
+      * [STDIN](#stdin)
+      * [Local files](#local-files)
+      * [Remote files](#remote-files)
+      * [Multiple files](#multiple-files)
+   * [Auto insert and update TOC](#auto-insert-and-update-toc)
+   * [GitHub Actions](#github-actions)
+   * [GitHub token](#github-token)
+   * [Docker](#docker)
+   * [Windows](#windows)
+```
+
+Heading `id`s equal these anchors. The hero is the `h1` "gh-md-toc". Landmarks:
+`header` (hero), `nav` (table of contents), `main` (sections), `footer`.
+
+### Sidebar rendering
+
+Each TOC line is one `<a href="#anchor">` rendered with `white-space: pre` in a
+monospace font. Its visible text is the full markdown line. The markdown syntax
+(`* [`, `](#anchor)`) is wrapped in `<span aria-hidden="true">`, so screen readers
+announce only the title.
+
+- Alternative: a nested `<ul>` styled to look like markdown. Rejected: the visible
+  text would no longer be the tool's literal output.
+
+### Example inputs
+
+Outputs are captured by running 0.10.0 at implementation time:
+
+| Section        | Command                                                                          |
+|----------------|----------------------------------------------------------------------------------|
+| STDIN          | `cat README.md \| ./gh-md-toc -`                                                  |
+| Local files    | `./gh-md-toc README.md`                                                          |
+| Remote files   | `./gh-md-toc https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv`          |
+| Multiple files | `./gh-md-toc README.md https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv` |
+| Auto insert    | `./gh-md-toc --insert` on a scratch file with the two markers                     |
+| Docker (URL)   | `docker run ... evkalinin/gh-md-toc:{{VERSION}} <the wiki URL>`                  |
+
+README output is pinned by the bats tests. Long outputs are shortened with a `...`
+line.
+
+### GitHub Actions snippet
+
+Based on README's snippet, updated to `actions/checkout@v7` and
+`stefanzweifel/git-auto-commit-action@v7`, with job-level
+`permissions: contents: write`. The action's README documents this as required for
+the default `GITHUB_TOKEN`.
+
+### Styling
+
+`styles.css` uses system font stacks: sans-serif for prose, monospace for code and the
+sidebar. Colors are CSS custom properties with a light default and a
+`@media (prefers-color-scheme: dark)` override. Layout is a two-column CSS grid with a
+sticky sidebar. Below a breakpoint it becomes a single column with the TOC first.
+`pre` blocks use `overflow-x: auto`, and there are visible `:focus-visible` outlines.
+
+### Copy buttons
+
+An inline script at the end of `body` adds a button to every `pre` marked
+`data-copy`. The button copies the block's text with `navigator.clipboard.writeText`.
+Copyable blocks contain commands only, with no `$` prompt, so the copied text is the
+visible text. Blocks with command output are not marked. Because the buttons are
+created by the script, no-JS visitors see no dead buttons.
+
+### Syntax highlighting
+
+A small regex-based highlighter in the same inline script. Each `pre` declares its
+kind with `data-lang`:
+
+| `data-lang` | Blocks                                    | Highlighted                                              |
+|-------------|-------------------------------------------|----------------------------------------------------------|
+| `sh`        | command-only blocks (Installation, token, Docker) | command names, flags, quoted strings                |
+| `console`   | `$ command` + output (Usage, Auto insert) | first line as `sh` with a muted `$`; the rest as `output` |
+| `yaml`      | GitHub Actions snippet                    | keys, quoted strings, comments                           |
+| `output`    | markers, file contents                    | TOC lines like the sidebar, HTML comments muted          |
+
+The script reads `code.textContent`, escapes it, wraps tokens in `<span class="tok-*">`,
+and writes it back, so the text is unchanged: copy buttons, the example checks, and
+`{{VERSION}}` substitution work as before. Blocks without `data-lang` stay plain.
+Colors reuse `--muted` and `--accent`, plus two new custom properties for strings and
+flags, with light and dark values.
+
+- Alternative: vendored Prism.js. Rejected: a ~20 KB third-party file to keep up to
+  date, and it would not style TOC output like the sidebar.
+- Alternative: static `<span>` markup in the HTML. Rejected: works without JS, but
+  every example edit would need hand-written markup.
+
+## Risks / Trade-offs
+
+- [After a version bump is merged, the Docker section names a tag that Docker Hub
+  gets only when the release is published] -> Publish the release right after the
+  bump; the gap is accepted.
+- [Example outputs go stale if GitHub changes its HTML or the wiki page changes] ->
+  README-based outputs are guarded by the bats tests; re-capture the wiki outputs
+  whenever the page is edited or a release changes output.
+- [Action versions in the snippet age] -> Update them when the page is touched; no
+  automation.
+- [The first deploy fails if Pages is not enabled yet] -> Enable Pages before merging;
+  otherwise enable it and re-run through `workflow_dispatch`.
+- [Once #166 is fixed, the page still avoids file URLs] -> A follow-up change can add
+  a `/blob/` example and drop the requirement "No GitHub file URLs in examples".
+- [Every change to `gh-md-toc` redeploys the page, not only version bumps] ->
+  Harmless: the deploy is idempotent and takes under a minute.
+
+## Migration Plan
+
+1. Before merge: enable Pages with Source "GitHub Actions".
+2. Merge the PR into `master`; the push triggers the first deploy.
+3. Verify `https://ekalinin.github.io/github-markdown-toc/` returns 200 and shows
+   `v0.10.0`.
+4. Set the repository homepage to the page URL.
+
+Rollback: revert the merge commit and disable Pages (Settings -> Pages, or
+`gh api -X DELETE repos/ekalinin/github-markdown-toc/pages`). The tool, its tests, and
+the Docker image are not affected either way.
+
+## Open Questions
+
+- Exact palette and accent color: chosen during implementation within the WCAG AA
+  requirement.
diff --git a/openspec/changes/archive/2026-09-27-add-landing-page/proposal.md b/openspec/changes/archive/2026-09-27-add-landing-page/proposal.md
new file mode 100644
index 0000000..44f10ca
--- /dev/null
+++ b/openspec/changes/archive/2026-09-27-add-landing-page/proposal.md
@@ -0,0 +1,69 @@
+# Proposal
+
+## Why
+
+The project has no web page: GitHub Pages is not enabled
+(`https://ekalinin.github.io/github-markdown-toc/` returns 404) and the repository
+homepage field is empty. A static one-page site on github.io gives the tool a
+landing page that explains what it does, shows how to install and use it, and routes
+visitors to the repository.
+
+## What Changes
+
+- Add a static, single-page, English-only site in `site/`, published at
+  `https://ekalinin.github.io/github-markdown-toc/`.
+- Page content covers seven blocks, based on README but with current facts:
+  - A. Why: TOC without installing additional software; link to github/issues/215
+  - B. Inputs: stdin, local files, remote files, multiple files. Remote examples use a
+    GitHub wiki page URL: for file (blob) URLs the first entry is currently broken
+    (#166), so they are not shown until that is fixed
+  - C. Auto insert and update TOC (`<!--ts-->` / `<!--te-->` markers, `--insert`)
+  - D. GitHub Actions snippet (current major versions of the actions)
+  - E. GitHub token (`GH_TOC_TOKEN` / `token.txt`)
+  - F. Docker (image tag equal to the current version)
+  - G. Windows: link to github-markdown-toc.go
+- Current facts instead of README's outdated ones: example output produced by the
+  current version (default `--indent 3`), `actions/checkout@v7`,
+  `stefanzweifel/git-auto-commit-action@v7`, Docker tag equal to `gh_toc_version`.
+  README itself is updated separately in #165.
+- Document-style layout with a sidebar table of contents written in gh-md-toc's own
+  output format (`* [Title](#anchor)`, 3-space indent per level).
+- Syntax highlighting of code blocks by a small inline script: shell, YAML, and TOC
+  output (styled like the sidebar). No external resources; without JavaScript the
+  blocks stay plain text.
+- The displayed version comes from `gh_toc_version` and is substituted at deploy time,
+  so the version stays single-sourced.
+- Add a GitHub Actions workflow that deploys `site/` to GitHub Pages on pushes to
+  `master` that touch the site, `gh-md-toc`, or the workflow itself.
+- One-time manual steps after merge: enable Pages with Source "GitHub Actions" and set
+  the repository homepage to the page URL.
+
+Non-goals:
+
+- Live in-browser demo or any call to the GitHub API from the page.
+- Documentation hub or multiple pages (README stays the documentation).
+- Localization, custom domain, analytics, web fonts, CDN, or any other external
+  resource.
+- Social preview image (`og:image`).
+- Changes to README, `gh-md-toc`, tests, `Makefile`, or `ci.yml`.
+
+## Capabilities
+
+### New Capabilities
+
+- `landing`: the project's static landing page on GitHub Pages - content, layout,
+  version display, and deployment.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+- New files: `site/index.html`, `site/styles.css`, `.github/workflows/pages.yml`.
+- Unchanged: `gh-md-toc`, `tests/`, `README.md`, `Makefile`,
+  `.github/workflows/ci.yml`, `.github/workflows/dockerimage.yml`.
+- Repository settings: GitHub Pages enabled with the GitHub Actions source (creates
+  the `github-pages` environment); homepage field set to the page URL.
+- `ci.yml` has no path filter, so commits that touch only `site/` still run the bats
+  suite. This is accepted and left as is.
diff --git a/openspec/changes/archive/2026-09-27-add-landing-page/specs/landing/spec.md b/openspec/changes/archive/2026-09-27-add-landing-page/specs/landing/spec.md
new file mode 100644
index 0000000..4937927
--- /dev/null
+++ b/openspec/changes/archive/2026-09-27-add-landing-page/specs/landing/spec.md
@@ -0,0 +1,291 @@
+# Spec Delta
+
+## Purpose
+
+A static one-page landing site for gh-md-toc on GitHub Pages that explains what the
+tool does, shows how to install and use it with current facts, and routes visitors to
+the repository.
+
+## ADDED Requirements
+
+### Requirement: Published location
+
+The landing page SHALL be served at `https://ekalinin.github.io/github-markdown-toc/`
+from the latest successful deployment of the `master` branch.
+
+#### Scenario: Page is reachable after deployment
+- **WHEN** a deployment of `master` has completed
+- **THEN** a GET request to `https://ekalinin.github.io/github-markdown-toc/` returns
+  HTTP 200 with the landing page
+
+### Requirement: Single static English page
+
+The site SHALL consist of one HTML page in English. All text, code examples, and
+navigation SHALL be present in the HTML itself, so the page is fully readable and
+navigable with JavaScript disabled.
+
+#### Scenario: JavaScript disabled
+- **WHEN** the page is opened in a browser with JavaScript disabled
+- **THEN** every section, code example, and navigation link is visible and works
+
+### Requirement: No external resources
+
+The page SHALL NOT load any resource from another origin: no scripts, stylesheets,
+fonts, images, or analytics. Outbound links to other sites are allowed.
+
+#### Scenario: Network requests stay on the page origin
+- **WHEN** the page is loaded with the browser's network inspector open
+- **THEN** every request goes to `ekalinin.github.io`
+
+### Requirement: Page metadata
+
+The page SHALL define a `<title>`, a meta description, `og:title`, `og:description`,
+`og:url`, and a canonical link pointing to the published URL. The page SHALL NOT
+define `og:image`.
+
+#### Scenario: Link preview uses page metadata
+- **WHEN** the page URL is inspected by a link-preview tool
+- **THEN** the preview shows the page title and description and no image
+
+### Requirement: Hero
+
+The page SHALL start with the project name `gh-md-toc`, the repository description
+"Easy TOC creation for GitHub README.md", the current version prefixed with `v`, and
+a link to `https://github.com/ekalinin/github-markdown-toc`.
+
+#### Scenario: Hero shows the current version
+- **WHEN** the deployed commit has `gh_toc_version="0.10.0"` in `gh-md-toc`
+- **THEN** the hero shows `v0.10.0`
+
+### Requirement: Sections and order
+
+After the hero, the page SHALL contain these sections in this order: Installation,
+Why, Usage (with subsections STDIN, Local files, Remote files, Multiple files), Auto
+insert and update TOC, GitHub Actions, GitHub token, Docker, Windows. A footer SHALL
+link to the repository and to its MIT license.
+
+#### Scenario: Reading the page top to bottom
+- **WHEN** a visitor scrolls from the top of the page to the bottom
+- **THEN** the sections appear in the order listed above, followed by the footer
+
+### Requirement: Installation section
+
+The Installation section SHALL show manual download of
+`https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc`
+with `curl` and with `wget`, each followed by `chmod a+x gh-md-toc`, and installation
+with Basher (`basher install ekalinin/github-markdown-toc`).
+
+#### Scenario: Manual installation with curl
+- **WHEN** a visitor runs the curl commands from the Installation section on Linux or
+  macOS
+- **THEN** an executable `gh-md-toc` appears in the current directory and
+  `./gh-md-toc --version` prints the version shown in the hero
+
+### Requirement: Why section
+
+The Why section SHALL state that gh-md-toc generates a TOC for a README.md or a GitHub
+wiki page without installing additional software, list the tools it needs (curl or
+wget, awk, grep, sed), and link to `https://github.com/isaacs/github/issues/215`.
+
+#### Scenario: Visitor checks requirements
+- **WHEN** a visitor reads the Why section
+- **THEN** they see the list of required tools and the link to the original GitHub
+  issue
+
+### Requirement: Examples reflect the current version
+
+Every command example that shows output (Usage subsections and Auto insert and update
+TOC) SHALL show output produced by running that command with the version shown on the
+page. A shortened output SHALL keep its shown lines verbatim and mark the cut with a
+line containing `...`.
+
+#### Scenario: Reproducing an example
+- **WHEN** a visitor runs an example command with the version shown on the page
+- **THEN** the output matches the output shown on the page, up to any `...` cut
+
+#### Scenario: Current indentation
+- **WHEN** an example output contains nested entries
+- **THEN** top-level entries have no indent and each nested level adds 3 spaces
+
+### Requirement: No GitHub file URLs in examples
+
+While issue #166 (broken first entry for GitHub file URLs) is open, no example on the
+page SHALL use a GitHub file (`/blob/`) URL. Remote examples SHALL use a GitHub wiki
+page URL instead.
+
+#### Scenario: Remote files example
+- **WHEN** a visitor reads the Remote files, Multiple files, or Docker examples
+- **THEN** every remote input is a GitHub wiki page URL, and none contains `/blob/`
+
+### Requirement: Auto insert and update TOC section
+
+The section SHALL show the `<!--ts-->` and `<!--te-->` markers, the `--insert`
+command with its output as printed by the current version, and describe the
+`--no-backup` and `--hide-footer` options.
+
+#### Scenario: Visitor sets up auto insert
+- **WHEN** a visitor adds the two markers to a local markdown file and runs the shown
+  `--insert` command
+- **THEN** the TOC is written between the markers and the printed messages match the
+  ones shown on the page
+
+### Requirement: GitHub Actions section
+
+The section SHALL show a workflow snippet that downloads gh-md-toc, runs
+`./gh-md-toc --insert --no-backup --hide-footer` on a markdown file, and commits the
+result. The snippet SHALL use `actions/checkout@v7` and
+`stefanzweifel/git-auto-commit-action@v7` and SHALL grant the permissions the commit
+step needs under the default read-only `GITHUB_TOKEN`.
+
+#### Scenario: Snippet works in a new repository
+- **WHEN** a visitor copies the snippet into a repository with default workflow
+  permissions and pushes a change to the watched markdown file
+- **THEN** the workflow updates the TOC and commits it back
+
+### Requirement: GitHub token section
+
+The section SHALL explain that a token is read from the `GH_TOC_TOKEN` environment
+variable or from a `token.txt` file next to the script, link to
+`https://github.com/settings/tokens`, and show the rate-limit error message as printed
+by the current version.
+
+#### Scenario: Visitor hits the rate limit
+- **WHEN** a visitor sees the rate-limit error from gh-md-toc
+- **THEN** the same message is shown in the GitHub token section, next to both ways of
+  passing a token
+
+### Requirement: Docker section
+
+The section SHALL show pulling and running `evkalinin/gh-md-toc:<version>`, where
+`<version>` equals the version shown in the hero, and building and running the image
+locally from the repository's `Dockerfile`, both on a URL and on a local file mounted
+as a volume.
+
+#### Scenario: Docker tag follows the version
+- **WHEN** the deployed commit has `gh_toc_version="0.10.0"`
+- **THEN** the Docker section shows `evkalinin/gh-md-toc:0.10.0`
+
+### Requirement: Windows section
+
+The Windows section SHALL point Windows users to
+`https://github.com/ekalinin/github-markdown-toc.go`.
+
+#### Scenario: Windows visitor
+- **WHEN** a Windows user reads the Windows section
+- **THEN** they find a link to github-markdown-toc.go
+
+### Requirement: Version is single-sourced
+
+Every version shown on the page SHALL equal `gh_toc_version` in `gh-md-toc` at the
+deployed commit. A deployment SHALL fail, leaving the previous deployment live, if any
+version placeholder remains unsubstituted.
+
+#### Scenario: Version bump
+- **WHEN** a commit that changes `gh_toc_version` from `0.10.0` to `0.11.0` is pushed
+  to `master`
+- **THEN** after the resulting deployment the hero shows `v0.11.0` and the Docker
+  section shows `evkalinin/gh-md-toc:0.11.0`
+
+#### Scenario: Unsubstituted placeholder
+- **WHEN** the built page still contains a version placeholder
+- **THEN** the deployment fails and the previously deployed page stays online
+
+### Requirement: Table of contents in gh-md-toc format
+
+The page SHALL have a table of contents whose lines are exactly the entry lines that
+gh-md-toc produces for a markdown document with the page's headings at the same
+levels: `* [Title](#anchor)`, with 3 spaces of indent per level below the first. Each
+entry SHALL link to its section, and each section's anchor SHALL equal the anchor
+GitHub generates for that heading.
+
+#### Scenario: Entry format and navigation
+- **WHEN** the page has a level-2 heading "Auto insert and update TOC"
+- **THEN** the table of contents contains the line
+  `   * [Auto insert and update TOC](#auto-insert-and-update-toc)`, and activating it
+  moves to that section
+
+#### Scenario: Matches the tool's own output
+- **WHEN** the page's headings are written as a markdown document at the same levels
+  and passed to gh-md-toc
+- **THEN** the entry lines of its output equal the lines of the page's table of
+  contents
+
+### Requirement: Responsive document layout
+
+On wide screens the table of contents SHALL be shown in a sidebar next to the content.
+On narrow screens it SHALL be shown above the content. Code blocks SHALL scroll
+horizontally instead of overflowing the page.
+
+#### Scenario: Wide screen
+- **WHEN** the page is viewed on a desktop-width window
+- **THEN** the table of contents is a sidebar next to the content
+
+#### Scenario: Narrow screen
+- **WHEN** the page is viewed on a phone-width window
+- **THEN** the table of contents appears above the content and the page does not
+  scroll horizontally
+
+### Requirement: Color scheme follows the system
+
+The page SHALL use a light or dark color scheme according to the visitor's system
+preference (`prefers-color-scheme`), with no manual toggle. Text SHALL meet WCAG AA
+contrast in both schemes.
+
+#### Scenario: Dark system theme
+- **WHEN** the visitor's system uses a dark theme
+- **THEN** the page renders in its dark scheme
+
+### Requirement: Copy buttons
+
+Command-only blocks (Installation, GitHub Actions snippet, Docker commands) SHALL have
+a copy button that copies text runnable as-is: no prompt characters and no output
+lines. Without JavaScript the buttons SHALL NOT be shown.
+
+#### Scenario: Copying installation commands
+- **WHEN** a visitor clicks the copy button of the curl installation block
+- **THEN** the clipboard contains the curl and chmod commands without a leading `$`
+
+#### Scenario: No JavaScript
+- **WHEN** the page is opened with JavaScript disabled
+- **THEN** no copy buttons are shown
+
+### Requirement: Syntax highlighting
+
+With JavaScript enabled, code blocks SHALL be highlighted: in shell commands the
+prompt, command names, flags, and quoted strings; in YAML the keys, strings, and
+comments; in TOC output the markdown syntax muted and the titles in the accent color,
+as in the table of contents; HTML comments muted. Highlighting SHALL NOT change the
+text of any block and SHALL NOT load external resources. Without JavaScript the
+blocks SHALL be shown as plain text. Highlight colors SHALL meet WCAG AA contrast in
+both color schemes.
+
+#### Scenario: Shell command
+- **WHEN** the curl installation block is shown with JavaScript enabled
+- **THEN** `curl` and `chmod` are highlighted as commands and `-o` as a flag
+
+#### Scenario: TOC output
+- **WHEN** an example output contains the line `   * [STDIN](#stdin)`
+- **THEN** `* [` and `](#stdin)` are muted and `STDIN` is in the accent color
+
+#### Scenario: Text is unchanged
+- **WHEN** highlighting has been applied
+- **THEN** the text of every code block equals its text in the HTML source, and copy
+  buttons copy the same text as before
+
+#### Scenario: No JavaScript
+- **WHEN** the page is opened with JavaScript disabled
+- **THEN** code blocks are shown as plain text
+
+### Requirement: Deployment triggers
+
+The page SHALL be deployed on pushes to `master` that change files under `site/`,
+`gh-md-toc`, or the deployment workflow, and on manual dispatch. Other pushes and
+pull requests SHALL NOT deploy.
+
+#### Scenario: Unrelated change
+- **WHEN** a commit that changes only `tests/` is pushed to `master`
+- **THEN** no deployment runs
+
+#### Scenario: Pull request
+- **WHEN** a pull request that changes `site/` is opened
+- **THEN** no deployment runs
diff --git a/openspec/changes/archive/2026-09-27-add-landing-page/tasks.md b/openspec/changes/archive/2026-09-27-add-landing-page/tasks.md
new file mode 100644
index 0000000..603c906
--- /dev/null
+++ b/openspec/changes/archive/2026-09-27-add-landing-page/tasks.md
@@ -0,0 +1,56 @@
+# Tasks
+
+## 1. Setup
+
+- [x] 1.1 Create branch `feat/landing-page` from `master` and verify `git branch --show-current` prints `feat/landing-page`
+
+## 2. Page skeleton
+
+- [x] 2.1 Create `site/index.html` with `<head>` metadata (title, meta description, `og:title`, `og:description`, `og:url`, canonical link to `https://ekalinin.github.io/github-markdown-toc/`, stylesheet `styles.css`) and the landmarks `header`, `nav`, `main`, `footer`; verify every tag is present and `grep -c 'og:image' site/index.html` prints `0`
+- [x] 2.2 Add the hero: `h1` "gh-md-toc" with `id="gh-md-toc"`, the description "Easy TOC creation for GitHub README.md", `v{{VERSION}}`, and a link to the repository; verify the placeholder appears in the hero
+- [x] 2.3 Add the `h2`/`h3` section headings with `id`s from design.md "Page structure and headings", in the order from the spec; verify the list of `id`s extracted with grep equals the anchors in design.md
+- [x] 2.4 Add the `nav` table of contents: one `<a>` per line with `white-space: pre` text in gh-md-toc format and the markdown syntax wrapped in `<span aria-hidden="true">`; verify each link targets an existing `id` (full check in 6.1)
+- [x] 2.5 Add the footer with links to the repository and its MIT `LICENSE`; verify both links open the right pages
+
+## 3. Content
+
+- [x] 3.1 Installation: curl + chmod, wget + chmod, and Basher blocks, marked `data-copy`, without `$` prompts; verify the commands match README's Installation section
+- [x] 3.2 Why: the "without installing additional software" statement for README.md and wiki pages, the tool list (curl or wget, awk, grep, sed), and the link to `https://github.com/isaacs/github/issues/215`; verify the link resolves
+- [x] 3.3 STDIN and Local files: run `cat README.md | ./gh-md-toc -` and `./gh-md-toc README.md` with 0.10.0 and paste the commands and outputs verbatim (shorten with a `...` line if needed); verify the shown lines equal the README assertions in `tests/tests.bats`
+- [x] 3.4 Remote files and Multiple files: run `./gh-md-toc https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv` and `./gh-md-toc README.md https://github.com/ekalinin/nodeenv/wiki/Who-Uses-Nodeenv` and paste commands and outputs verbatim; verify no `<pre>` block on the page contains `/blob/`
+- [x] 3.5 Auto insert and update TOC: in a temp dir (`mktemp -d`), create a file with `<!--ts-->` / `<!--te-->`, run `--insert`, and paste the markers, the command, its messages, and the resulting block; describe `--no-backup` and `--hide-footer`; verify the messages match `gh-md-toc` lines 207-210
+- [x] 3.6 GitHub Actions: README's snippet with `actions/checkout@v7`, `stefanzweifel/git-auto-commit-action@v7`, and job-level `permissions: contents: write`, marked `data-copy`; verify it parses as YAML and matches the permissions shown in the action's README
+- [x] 3.7 GitHub token: `GH_TOC_TOKEN` and `token.txt` usage, the link to `https://github.com/settings/tokens`, and the rate-limit message; verify the message text equals `gh-md-toc` lines 163-164
+- [x] 3.8 Docker: `docker pull` / `docker run` of `evkalinin/gh-md-toc:{{VERSION}}` on the wiki URL, plus local `docker build` and `docker run` on the wiki URL and on a mounted local file, command blocks marked `data-copy`; verify both commands use `{{VERSION}}` and no block contains `/blob/`
+- [x] 3.9 Windows: a link to `https://github.com/ekalinin/github-markdown-toc.go`; verify the link resolves
+
+## 4. Styles and behavior
+
+- [x] 4.1 Create `site/styles.css`: system font stacks (sans for prose, mono for code and the sidebar), color custom properties with a light default and a `prefers-color-scheme: dark` override, a two-column grid with a sticky sidebar, a single column with the TOC first below the breakpoint, `pre { overflow-x: auto }`, and `:focus-visible` outlines; verify in a browser at desktop width and at 375px that the page does not scroll horizontally
+- [x] 4.2 Pick the palette and verify every text/background pair meets WCAG AA (at least 4.5:1) in both schemes with a contrast checker
+- [x] 4.3 Add the inline copy script that adds a button to each `pre[data-copy]` and copies its text with `navigator.clipboard.writeText`; verify that clicking the curl block's button puts the commands without `$` in the clipboard
+- [x] 4.4 Mark every code block with `data-lang` (`sh`, `console`, `yaml`, `output`) per design.md "Syntax highlighting"; verify each `pre` except the rate-limit message has one
+- [x] 4.5 Add the highlighter to the inline script and the `tok-*` styles with two new color properties (strings, flags) for both schemes; verify in the browser that `curl`/`chmod` are commands, `-o` is a flag, and `   * [STDIN](#stdin)` has muted syntax and an accent title
+- [x] 4.6 Verify that after highlighting every block's `textContent` equals the source text, the copy buttons still copy the same text, blocks are plain with JavaScript disabled, and the new colors meet WCAG AA in both schemes
+
+## 5. Deploy workflow
+
+- [x] 5.1 Create `.github/workflows/pages.yml`: `push` to `master` with `paths: [site/**, gh-md-toc, .github/workflows/pages.yml]`, `workflow_dispatch`, permissions `contents: read`, `pages: write`, `id-token: write`, concurrency group `pages` without cancel, steps `actions/checkout@v7`, `actions/configure-pages@v6`, version from `./gh-md-toc --version | head -n 1`, copy `site/` to `_site/` with `sed` substitution of `{{VERSION}}`, a `grep '{{'` guard, `actions/upload-pages-artifact@v5` with `path: _site`, and `actions/deploy-pages@v5` in the `github-pages` environment; verify the file parses as YAML (and passes `actionlint` if it is installed)
+- [x] 5.2 Run the workflow's build commands locally into a temp dir; verify the result contains `v0.10.0` and `evkalinin/gh-md-toc:0.10.0` and no `{{`
+- [x] 5.3 Run the guard on the unsubstituted `site/index.html`; verify it exits non-zero
+
+## 6. Verification
+
+- [x] 6.1 Write the page's headings as a markdown file at the same levels in a temp dir, run `./gh-md-toc` on it, and compare its entry lines with the sidebar's text; verify they are identical
+- [x] 6.2 Serve the built page locally (`python3 -m http.server`) and open it with the network inspector; verify every request stays on the page's origin
+- [x] 6.3 Open the built page with JavaScript disabled; verify all sections and TOC links work and no copy buttons are shown
+- [x] 6.4 Verify `make test` passes in CI on the PR (`ci.yml` runs it on pull requests; bats is not installed locally), and run `make lint`; verify its output is identical to `master` (the tool is unchanged; the existing warnings are tracked in #167)
+- [x] 6.5 Run `openspec validate add-landing-page --strict`; verify it reports the change as valid
+
+## 7. Delivery (each outward step needs the user's confirmation)
+
+- [x] 7.1 Commit `site/` and `.github/workflows/pages.yml` as `feat(landing): add GitHub Pages landing page` (whether to commit `openspec/` is the user's call); verify with `git log -1 --stat`
+- [x] 7.2 Push `feat/landing-page` as a separate command and open a PR to `master`; verify the PR URL
+- [x] 7.3 Enable Pages with Source "GitHub Actions" (Settings -> Pages, or `gh api -X POST repos/ekalinin/github-markdown-toc/pages -f build_type=workflow`); verify `gh api repos/ekalinin/github-markdown-toc/pages --jq .build_type` prints `workflow`
+- [x] 7.4 After the merge, check the deploy run; verify it succeeded, `https://ekalinin.github.io/github-markdown-toc/` returns 200, and the hero shows `v0.10.0`
+- [x] 7.5 Set the repository homepage with `gh repo edit ekalinin/github-markdown-toc --homepage https://ekalinin.github.io/github-markdown-toc/`; verify `gh repo view --json homepageUrl` shows the URL
diff --git a/openspec/specs/landing/spec.md b/openspec/specs/landing/spec.md
new file mode 100644
index 0000000..98c34ab
--- /dev/null
+++ b/openspec/specs/landing/spec.md
@@ -0,0 +1,291 @@
+# landing Specification
+
+## Purpose
+
+A static one-page landing site for gh-md-toc on GitHub Pages that explains what the
+tool does, shows how to install and use it with current facts, and routes visitors to
+the repository.
+
+## Requirements
+
+### Requirement: Published location
+
+The landing page SHALL be served at `https://ekalinin.github.io/github-markdown-toc/`
+from the latest successful deployment of the `master` branch.
+
+#### Scenario: Page is reachable after deployment
+- **WHEN** a deployment of `master` has completed
+- **THEN** a GET request to `https://ekalinin.github.io/github-markdown-toc/` returns
+  HTTP 200 with the landing page
+
+### Requirement: Single static English page
+
+The site SHALL consist of one HTML page in English. All text, code examples, and
+navigation SHALL be present in the HTML itself, so the page is fully readable and
+navigable with JavaScript disabled.
+
+#### Scenario: JavaScript disabled
+- **WHEN** the page is opened in a browser with JavaScript disabled
+- **THEN** every section, code example, and navigation link is visible and works
+
+### Requirement: No external resources
+
+The page SHALL NOT load any resource from another origin: no scripts, stylesheets,
+fonts, images, or analytics. Outbound links to other sites are allowed.
+
+#### Scenario: Network requests stay on the page origin
+- **WHEN** the page is loaded with the browser's network inspector open
+- **THEN** every request goes to `ekalinin.github.io`
+
+### Requirement: Page metadata
+
+The page SHALL define a `<title>`, a meta description, `og:title`, `og:description`,
+`og:url`, and a canonical link pointing to the published URL. The page SHALL NOT
+define `og:image`.
+
+#### Scenario: Link preview uses page metadata
+- **WHEN** the page URL is inspected by a link-preview tool
+- **THEN** the preview shows the page title and description and no image
+
+### Requirement: Hero
+
+The page SHALL start with the project name `gh-md-toc`, the repository description
+"Easy TOC creation for GitHub README.md", the current version prefixed with `v`, and
+a link to `https://github.com/ekalinin/github-markdown-toc`.
+
+#### Scenario: Hero shows the current version
+- **WHEN** the deployed commit has `gh_toc_version="0.10.0"` in `gh-md-toc`
+- **THEN** the hero shows `v0.10.0`
+
+### Requirement: Sections and order
+
+After the hero, the page SHALL contain these sections in this order: Installation,
+Why, Usage (with subsections STDIN, Local files, Remote files, Multiple files), Auto
+insert and update TOC, GitHub Actions, GitHub token, Docker, Windows. A footer SHALL
+link to the repository and to its MIT license.
+
+#### Scenario: Reading the page top to bottom
+- **WHEN** a visitor scrolls from the top of the page to the bottom
+- **THEN** the sections appear in the order listed above, followed by the footer
+
+### Requirement: Installation section
+
+The Installation section SHALL show manual download of
+`https://raw.githubusercontent.com/ekalinin/github-markdown-toc/master/gh-md-toc`
+with `curl` and with `wget`, each followed by `chmod a+x gh-md-toc`, and installation
+with Basher (`basher install ekalinin/github-markdown-toc`).
+
+#### Scenario: Manual installation with curl
+- **WHEN** a visitor runs the curl commands from the Installation section on Linux or
+  macOS
+- **THEN** an executable `gh-md-toc` appears in the current directory and
+  `./gh-md-toc --version` prints the version shown in the hero
+
+### Requirement: Why section
+
+The Why section SHALL state that gh-md-toc generates a TOC for a README.md or a GitHub
+wiki page without installing additional software, list the tools it needs (curl or
+wget, awk, grep, sed), and link to `https://github.com/isaacs/github/issues/215`.
+
+#### Scenario: Visitor checks requirements
+- **WHEN** a visitor reads the Why section
+- **THEN** they see the list of required tools and the link to the original GitHub
+  issue
+
+### Requirement: Examples reflect the current version
+
+Every command example that shows output (Usage subsections and Auto insert and update
+TOC) SHALL show output produced by running that command with the version shown on the
+page. A shortened output SHALL keep its shown lines verbatim and mark the cut with a
+line containing `...`.
+
+#### Scenario: Reproducing an example
+- **WHEN** a visitor runs an example command with the version shown on the page
+- **THEN** the output matches the output shown on the page, up to any `...` cut
+
+#### Scenario: Current indentation
+- **WHEN** an example output contains nested entries
+- **THEN** top-level entries have no indent and each nested level adds 3 spaces
+
+### Requirement: No GitHub file URLs in examples
+
+While issue #166 (broken first entry for GitHub file URLs) is open, no example on the
+page SHALL use a GitHub file (`/blob/`) URL. Remote examples SHALL use a GitHub wiki
+page URL instead.
+
+#### Scenario: Remote files example
+- **WHEN** a visitor reads the Remote files, Multiple files, or Docker examples
+- **THEN** every remote input is a GitHub wiki page URL, and none contains `/blob/`
+
+### Requirement: Auto insert and update TOC section
+
+The section SHALL show the `<!--ts-->` and `<!--te-->` markers, the `--insert`
+command with its output as printed by the current version, and describe the
+`--no-backup` and `--hide-footer` options.
+
+#### Scenario: Visitor sets up auto insert
+- **WHEN** a visitor adds the two markers to a local markdown file and runs the shown
+  `--insert` command
+- **THEN** the TOC is written between the markers and the printed messages match the
+  ones shown on the page
+
+### Requirement: GitHub Actions section
+
+The section SHALL show a workflow snippet that downloads gh-md-toc, runs
+`./gh-md-toc --insert --no-backup --hide-footer` on a markdown file, and commits the
+result. The snippet SHALL use `actions/checkout@v7` and
+`stefanzweifel/git-auto-commit-action@v7` and SHALL grant the permissions the commit
+step needs under the default read-only `GITHUB_TOKEN`.
+
+#### Scenario: Snippet works in a new repository
+- **WHEN** a visitor copies the snippet into a repository with default workflow
+  permissions and pushes a change to the watched markdown file
+- **THEN** the workflow updates the TOC and commits it back
+
+### Requirement: GitHub token section
+
+The section SHALL explain that a token is read from the `GH_TOC_TOKEN` environment
+variable or from a `token.txt` file next to the script, link to
+`https://github.com/settings/tokens`, and show the rate-limit error message as printed
+by the current version.
+
+#### Scenario: Visitor hits the rate limit
+- **WHEN** a visitor sees the rate-limit error from gh-md-toc
+- **THEN** the same message is shown in the GitHub token section, next to both ways of
+  passing a token
+
+### Requirement: Docker section
+
+The section SHALL show pulling and running `evkalinin/gh-md-toc:<version>`, where
+`<version>` equals the version shown in the hero, and building and running the image
+locally from the repository's `Dockerfile`, both on a URL and on a local file mounted
+as a volume.
+
+#### Scenario: Docker tag follows the version
+- **WHEN** the deployed commit has `gh_toc_version="0.10.0"`
+- **THEN** the Docker section shows `evkalinin/gh-md-toc:0.10.0`
+
+### Requirement: Windows section
+
+The Windows section SHALL point Windows users to
+`https://github.com/ekalinin/github-markdown-toc.go`.
+
+#### Scenario: Windows visitor
+- **WHEN** a Windows user reads the Windows section
+- **THEN** they find a link to github-markdown-toc.go
+
+### Requirement: Version is single-sourced
+
+Every version shown on the page SHALL equal `gh_toc_version` in `gh-md-toc` at the
+deployed commit. A deployment SHALL fail, leaving the previous deployment live, if any
+version placeholder remains unsubstituted.
+
+#### Scenario: Version bump
+- **WHEN** a commit that changes `gh_toc_version` from `0.10.0` to `0.11.0` is pushed
+  to `master`
+- **THEN** after the resulting deployment the hero shows `v0.11.0` and the Docker
+  section shows `evkalinin/gh-md-toc:0.11.0`
+
+#### Scenario: Unsubstituted placeholder
+- **WHEN** the built page still contains a version placeholder
+- **THEN** the deployment fails and the previously deployed page stays online
+
+### Requirement: Table of contents in gh-md-toc format
+
+The page SHALL have a table of contents whose lines are exactly the entry lines that
+gh-md-toc produces for a markdown document with the page's headings at the same
+levels: `* [Title](#anchor)`, with 3 spaces of indent per level below the first. Each
+entry SHALL link to its section, and each section's anchor SHALL equal the anchor
+GitHub generates for that heading.
+
+#### Scenario: Entry format and navigation
+- **WHEN** the page has a level-2 heading "Auto insert and update TOC"
+- **THEN** the table of contents contains the line
+  `   * [Auto insert and update TOC](#auto-insert-and-update-toc)`, and activating it
+  moves to that section
+
+#### Scenario: Matches the tool's own output
+- **WHEN** the page's headings are written as a markdown document at the same levels
+  and passed to gh-md-toc
+- **THEN** the entry lines of its output equal the lines of the page's table of
+  contents
+
+### Requirement: Responsive document layout
+
+On wide screens the table of contents SHALL be shown in a sidebar next to the content.
+On narrow screens it SHALL be shown above the content. Code blocks SHALL scroll
+horizontally instead of overflowing the page.
+
+#### Scenario: Wide screen
+- **WHEN** the page is viewed on a desktop-width window
+- **THEN** the table of contents is a sidebar next to the content
+
+#### Scenario: Narrow screen
+- **WHEN** the page is viewed on a phone-width window
+- **THEN** the table of contents appears above the content and the page does not
+  scroll horizontally
+
+### Requirement: Color scheme follows the system
+
+The page SHALL use a light or dark color scheme according to the visitor's system
+preference (`prefers-color-scheme`), with no manual toggle. Text SHALL meet WCAG AA
+contrast in both schemes.
+
+#### Scenario: Dark system theme
+- **WHEN** the visitor's system uses a dark theme
+- **THEN** the page renders in its dark scheme
+
+### Requirement: Copy buttons
+
+Command-only blocks (Installation, GitHub Actions snippet, Docker commands) SHALL have
+a copy button that copies text runnable as-is: no prompt characters and no output
+lines. Without JavaScript the buttons SHALL NOT be shown.
+
+#### Scenario: Copying installation commands
+- **WHEN** a visitor clicks the copy button of the curl installation block
+- **THEN** the clipboard contains the curl and chmod commands without a leading `$`
+
+#### Scenario: No JavaScript
+- **WHEN** the page is opened with JavaScript disabled
+- **THEN** no copy buttons are shown
+
+### Requirement: Syntax highlighting
+
+With JavaScript enabled, code blocks SHALL be highlighted: in shell commands the
+prompt, command names, flags, and quoted strings; in YAML the keys, strings, and
+comments; in TOC output the markdown syntax muted and the titles in the accent color,
+as in the table of contents; HTML comments muted. Highlighting SHALL NOT change the
+text of any block and SHALL NOT load external resources. Without JavaScript the
+blocks SHALL be shown as plain text. Highlight colors SHALL meet WCAG AA contrast in
+both color schemes.
+
+#### Scenario: Shell command
+- **WHEN** the curl installation block is shown with JavaScript enabled
+- **THEN** `curl` and `chmod` are highlighted as commands and `-o` as a flag
+
+#### Scenario: TOC output
+- **WHEN** an example output contains the line `   * [STDIN](#stdin)`
+- **THEN** `* [` and `](#stdin)` are muted and `STDIN` is in the accent color
+
+#### Scenario: Text is unchanged
+- **WHEN** highlighting has been applied
+- **THEN** the text of every code block equals its text in the HTML source, and copy
+  buttons copy the same text as before
+
+#### Scenario: No JavaScript
+- **WHEN** the page is opened with JavaScript disabled
+- **THEN** code blocks are shown as plain text
+
+### Requirement: Deployment triggers
+
+The page SHALL be deployed on pushes to `master` that change files under `site/`,
+`gh-md-toc`, or the deployment workflow, and on manual dispatch. Other pushes and
+pull requests SHALL NOT deploy.
+
+#### Scenario: Unrelated change
+- **WHEN** a commit that changes only `tests/` is pushed to `master`
+- **THEN** no deployment runs
+
+#### Scenario: Pull request
+- **WHEN** a pull request that changes `site/` is opened
+- **THEN** no deployment runs

From 3d8f247ca95e90611369fb6bba31970d7a0540a3 Mon Sep 17 00:00:00 2001
From: Eugene Kalinin <e.v.kalinin@gmail.com>
Date: Sun, 27 Sep 2026 22:10:54 +0300
Subject: [PATCH 3/4] chore(openspec): add config

---
 openspec/config.yaml | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 openspec/config.yaml

diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 0000000..c4d34ac
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,32 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours
+
+# Per-operation guidance (optional)
+# Add advisory guidance for how apply and archive work should be conducted.
+# This is separate from artifact rules above.
+# Example:
+#   operations:
+#     apply:
+#       guidance:
+#         - Keep test summaries concise
+#     archive:
+#       guidance:
+#         - Summarize the archive outcome before finishing

From e07eb5299b0f83af2161c5a66d703781bc0c8f07 Mon Sep 17 00:00:00 2001
From: Eugene Kalinin <e.v.kalinin@gmail.com>
Date: Sun, 27 Sep 2026 22:14:25 +0300
Subject: [PATCH 4/4] chore(gitignore): ignore .claude

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 29ff363..5352b6c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,3 @@
 *.swp
 token.txt
+.claude
\ No newline at end of file