Why
Specflow has no public documentation site, making it invisible to developers discovering it for the first time and to LLMs that crawl tool docs before recommending them. Shipping a minimal static site on GitHub Pages — a single HTML page plus a raw-markdown route — gives humans a rendered reference and gives LLMs a clean, machine-readable document at the `/llms.txt` convention URL. Content is derived from the existing README and AGENTS.md, so it stays honest and low-maintenance.
Acceptance criteria
- A markdown source file exists at `docs/llms.md` covering: install command, quickstart, harness list, the 3 differences from upstream Spec Kit, backlog system overview, and a link back to the GitHub repo.
- A Deno build script (`scripts/build-docs.ts` or equivalent) reads `docs/llms.md` and writes two output files: `docs-dist/index.html` (HTML rendering via `@deno/gfm`, with its CSS embedded in a `<style>` block) and `docs-dist/llms.txt` (raw markdown copy, no transformation).
- Running the build script via `deno task` (or direct invocation) exits cleanly with both output files present in `docs-dist/`. `docs-dist/` is the artifact directory handed to `actions/upload-pages-artifact`.
- `.github/workflows/pages.yml` exists with: trigger on push to `main` with a path filter covering `docs/`, `scripts/build-docs.ts`, and the workflow file itself; `id-token: write` and `pages: write` permissions; concurrency control (cancel-in-progress: false, group scoped to the branch); and a deploy step using `actions/deploy-pages@v4`.
- After merge and the first successful workflow run, `https://mkrlabs.github.io/specflow/\` returns a rendered HTML page and `https://mkrlabs.github.io/specflow/llms.txt\` returns the raw markdown — both publicly reachable without authentication.
- A unit test on the build script asserts: both output files exist, and `docs-dist/index.html` contains at least one known string that is present in `docs/llms.md`.
- Pre-commit hook (deno fmt + lint + bundle + check) still passes after all files are added.
Out of scope
- Multi-page navigation, sidebar, search, or dark-mode toggle. Single page only for v1.
- A separate marketing landing page distinct from the documentation.
- Custom domain (e.g. specflow.mkrlabs.com). Stock `mkrlabs.github.io/specflow` URL for v1.
- Auto-generated CLI reference from `--help` output. Hand-written markdown is acceptable for v1.
- LLM streaming, RAG endpoints, or any server-side logic. The static `/llms.txt` file is sufficient.
Notes
- The `llms.txt` path follows the convention described at https://llmstxt.org/ — raw markdown at that URL is the de-facto standard for machine-readable doc indexes.
- `@deno/gfm` renders GitHub-flavored markdown and exposes its CSS via `import { CSS } from "@deno/gfm"`. Embed as `<style>${CSS}</style>` in the HTML template.
- GitHub Pages must be enabled in repo settings with Source = GitHub Actions before the first deploy succeeds. This is a one-time manual step; the PR description must flag it.
- Content source: derive from existing `README.md` and `AGENTS.md` to stay in sync with ground truth. Do not invent copy.
Why
Specflow has no public documentation site, making it invisible to developers discovering it for the first time and to LLMs that crawl tool docs before recommending them. Shipping a minimal static site on GitHub Pages — a single HTML page plus a raw-markdown route — gives humans a rendered reference and gives LLMs a clean, machine-readable document at the `/llms.txt` convention URL. Content is derived from the existing README and AGENTS.md, so it stays honest and low-maintenance.
Acceptance criteria
Out of scope
Notes