kiss-ssg 2.0.0 → 2.1.0

package/AIKB/build-report.md

@@ -6,7 +6,7 @@ Turns one settled build into data: the JSON-safe `BuildReport` that `Kiss.report
 
 ## Public interface
 
-- `buildReport({ stack, failures, manifest, buildDir, stagingDir, mode, startedAt, sitemap })` → `BuildReport`, whose keys are always in this order:
+- `buildReport({ stack, failures, manifest, buildDir, stagingDir, mode, startedAt, sitemap, pipeline, llms })` → `BuildReport`, whose keys are always in this order:
   - `ok` — `failures.length === 0`.
   - `mode` — `'build'` for a build that publishes, `'check'` for one that is staged and discarded.
   - `buildDir` — the folder the site asked for, never the staging sibling.
@@ -16,6 +16,7 @@ Turns one settled build into data: the JSON-safe `BuildReport` that `Kiss.report
   - `assets` — `{ source, target }` per asset-manifest entry: the build-relative path a template asks for, and the file that is actually there.
   - `sitemap` — the `sitemap.xml` this build wrote, or `null`.
   - `pipeline` — `{ name, ok, duration }` per `config.assets.pipeline` step this build ran, in order; `[]` when the site configured none.
+  - `llms` — the `llms.txt` this build wrote, or `null`. Appended after `pipeline` for the same reason `pipeline` was appended after `sitemap`: a consumer diffing two reports should see one new key, not a reshuffle.
 - `formatReport(report)` → the summary line `ok|FAIL <buildDir> (<mode>) — N pages, M failed, K assets, Xms`, followed by one indented `<buildTo|view>: <message>` line per failure. What `kiss-ssg check --summary` prints instead of the JSON.
 
 ## Depends on
@@ -28,7 +29,7 @@ Nothing.
 
 ## Non-obvious behavior
 
-- **Every path in the report is mapped out of the staging folder** — page `buildTo`, failure `buildTo` and `sitemap` all go through the same internal `reportedPath(target, buildDir, stagingDir)`. `Kiss._reportedPath` does the same thing for the failure _message_; this is the same rule somewhere a unit test can reach it, and it is why `buildReport` takes `stagingDir` as well as `buildDir`. A staged build's paths are otherwise a folder with a random suffix that, in check mode, no longer exists by the time anyone reads the report.
+- **Every path in the report is mapped out of the staging folder** — page `buildTo`, failure `buildTo`, `sitemap` and `llms` all go through the same internal `reportedPath(target, buildDir, stagingDir)`. `Kiss._reportedPath` does the same thing for the failure _message_; this is the same rule somewhere a unit test can reach it, and it is why `buildReport` takes `stagingDir` as well as `buildDir`. A staged build's paths are otherwise a folder with a random suffix that, in check mode, no longer exists by the time anyone reads the report.
 - **A failure's `Error` is reduced to its `message` on purpose.** `JSON.stringify(new Error('x'))` is `{}`, so a report carrying the object loses exactly the text that says what went wrong. The object itself stays on the `AggregateError` `complete()` rejects with — the report is the serialisable view of the same build, not a replacement for it.
 - **`assets` is the manifest, so it is keyed by the path a template writes**, not by the source file: a `.scss` appears under its compiled `css/site.css` name, and `target` is where cache busting put it (`css/site.a1b2c3d4.css`). See `AIKB/asset-manifest.md`.
 - **A failure with no output path (`buildTo: null`) marks no page as failed** — a `.pages()` item, a controller, a callback or the dev server never reached the stack, so no `pages` entry belongs to it. It is still in `failures`, and it still makes `ok` false.

package/AIKB/kiss.md

@@ -17,6 +17,7 @@ The orchestrator and public API. `Kiss` owns config, a per-instance Handlebars e
 - `.generate(callback)` — sets the `_generateRequested` latch, awaits `_promises`, renders every stack entry with `runCount === 0` once (each render caught, failures collected on `_failures`), awaits the writes, invokes `callback` through `_runCallback` (so a callback that throws, or returns a rejecting promise, is collected on `_failures` too); returns `this`.
 - `.complete(callback)` — awaits `_settle()` (drain, then render whatever the drain left unrendered, repeated until the stack is stable), then **rejects with an `AggregateError`** if `_failures` is non-empty and `_failuresReported` is not yet set; otherwise invokes `callback` with the resolved data (never on a failed build) and returns that data (a `Promise`, unlike the other chainable methods). Under `cleanBuild: 'atomic'` this is also the promotion point: a settle with no failures promotes the staging folder, a settle with failures discards it — and in check mode a settle with no failures discards it too. It is also where the build report is assembled (`_finishBuild()`), so `report()` and `err.report` are set by the time either outcome reaches the caller.
 - `.sitemap(options, callback)` — records the request on `_sitemapRequest` (so watch rebuilds re-run it), awaits `_promises`, writes `sitemap.xml` via `writeSitemap()`, invokes `callback` through `_runCallback`; returns `this`.
+- `.llms(options, callback)` — the same shape one file over: records `_llmsRequest`, awaits `_promises`, writes `llms.txt` via `writeLlms()` (`AIKB/llms.md`), records `_llmsPath` for the report's `llms` field, invokes `callback` (with the rendered text) through `_runCallback`; returns `this`. A missing `siteUrl`, `title` or `summary` is logged and skipped, and the callback does not fire.
 - `.getModelByID(id, data)` — looks up `{ id }` in a resolved-models array; returns `.data` or an error object.
 - `.watch({ entry = process.argv[1] } = {})` — starts (once) a `createWatcher()` wired to `_handleChange` (every `src` event), `_requestReplay()` (the entry script) and `copyAssets()` + a live reload (the assets tree); returns `this`. What each event means is decided in `_handleChange` — the dispatch table is below — and every rebuild it asks for goes through the serial queue.
 - `.report()` — the last settled build as data (`AIKB/build-report.md`), or `null` before the first `complete()` settles. The same object is on the rejection as `err.report`, and a watch rebuild replaces it with its own.
@@ -25,7 +26,7 @@ The orchestrator and public API. `Kiss` owns config, a per-instance Handlebars e
 
 ## Depends on
 
-`fs-extra`, `node:path`, `handlebars`, `handlebars-layouts`, `remarkable`; and `./utils.js`, `./logger.js`, `./config.js`, `./build-report.js`, `./handlebars-helpers.js`, `./partials.js`, `./dependency-graph.js`, `./assets.js`, `./asset-manifest.js`, `./pipeline.js`, `./model-resolver.js`, `./controller-resolver.js`, `./sitemap.js`, `./kiss-page.js`, `./dev-server.js`, `./watcher.js`.
+`fs-extra`, `node:path`, `handlebars`, `handlebars-layouts`, `remarkable`; and `./utils.js`, `./logger.js`, `./config.js`, `./build-report.js`, `./handlebars-helpers.js`, `./partials.js`, `./dependency-graph.js`, `./assets.js`, `./asset-manifest.js`, `./pipeline.js`, `./model-resolver.js`, `./controller-resolver.js`, `./sitemap.js`, `./llms.js`, `./kiss-page.js`, `./dev-server.js`, `./watcher.js`.
 
 ## Depended on by
 
@@ -34,7 +35,7 @@ Nothing in `lib/` — it is the entry point (`package.json`'s `main`). `bin/kiss
 ## Non-obvious behavior
 
 - Pipeline: `.page()`/`.pages()`/`.scan()` queue work (model → controller → `_preparePage`) as one caught promise per page on `_promises`; nothing renders until `.generate()`. `.generate()` awaits `_promises`, renders every stack entry whose `runCount` is 0, awaits the writes, then fires the callback. `_generating` tracks `generate()`/`sitemap()` runs, `_callbacks` the promises callbacks themselves returned. `complete()` drains all three lists repeatedly because callbacks may queue more work, and then renders anything the drain left unrendered.
-- **The build folder is written by four things, and `config.folders.build` is the single handle on all four.** Pages (`_preparePage` copies it onto each `KissPage.buildDir`, which `buildTo` is composed from — plus the dev-mode `.json` debug sibling beside each page), the asset copy (`copyAssets(folders.assets, folders.build)` at construction, and again on a watched asset change), `sitemap.xml` (`writeSitemap` reads `config.folders.build`), and `viewStats()`'s `debug.json`. Nothing writes into the build by any other route, which is what makes the staged build below a one-line redirection rather than four separate detours.
+- **The build folder is written by four things, and `config.folders.build` is the single handle on all four.** Pages (`_preparePage` copies it onto each `KissPage.buildDir`, which `buildTo` is composed from — plus the dev-mode `.json` debug sibling beside each page), the asset copy (`copyAssets(folders.assets, folders.build)` at construction, and again on a watched asset change), `sitemap.xml` (`writeSitemap` reads `config.folders.build`), `llms.txt` (`writeLlms`, same route), and `viewStats()`'s `debug.json`. Nothing writes into the build by any other route, which is what makes the staged build below a one-line redirection rather than four separate detours.
 - **`config.assets.pipeline` is wired at three points, and all three are one line each** (`AIKB/pipeline.md` has the runner). The constructor creates the pipeline and calls `_queuePipeline()` immediately before the construction-time `copyAssets()`; `_replay()` re-runs it (and re-queues the copy) when — and only when — the site configured a step, so a whole-site watch rebuild re-runs the tools an edited model or controller may have changed the input to; `close()` ends the watch processes. **Ordering needs no mechanism of its own**: the steps are chained onto `_assetQueue`, the promise every copy already chains onto, so "steps first, copy second" is the queue doing what it was built to do. The run is deliberately **not** pushed onto `_promises`: those entries are the `data` array `generate()`/`complete()` hand back, whose first entry is documented as the construction-time asset copy, so a site adding a pipeline would have silently renumbered its own `data`. It goes on `_generating`, which `_drain()` waits for just the same. A step that exits non-zero (or cannot be spawned) is recorded as `{ view: '<pipeline: name>', buildTo: null, error }` — the same shape as a controller or dev-server failure, since there is no output path to name it by — so `complete()` rejects while the copy and every page still run and the report still names everything else that was wrong. Scoped re-renders (a page view, a partial, a layout) never re-run the steps: a tool that must see those edits is what a step's `watch` command is for.
 - **A pipeline step runs before `cleanBuild` could matter, and writes wherever the site tells it to.** `KISS_BUILD`, `KISS_ASSETS` and `KISS_DEV` are handed to each command (read per run, so `KISS_BUILD` follows a staged build into its staging folder and back out again after `_promote()`), but nothing stops a step writing anywhere else. The idiom the feature is built for is a tool that writes into the **source** tree (`src/assets/css/site.css`), which is why `kiss-ssg check` can run the pipeline exactly like a build: the step's output is a source file the check has nothing to discard.
 - **`cleanBuild: 'atomic'` builds into a staging sibling and swaps it in on success.** `_setupFolders()` keeps the folder the consumer asked for in `_buildTarget` and points `config.folders.build` at `<build>.kiss-staging-<pid>-<random>`, so all four write paths above land there with no further plumbing; the real folder is not touched at all until the swap. `complete()` is the decision point: a settle with no failures calls `_promote()`, and a settle with failures calls `_discardStaging()`, which deletes the staging folder and leaves the previous output exactly as it was. Promotion happens **once**: `_buildSettled` latches, so the nested `complete()` pattern's second call is a no-op and, crucially, a second `complete()` after a failed build (which resolves rather than re-rejecting, see the report-once bullet) can never promote a build that failed. The failure message names the target path, not the staging path (`_reportedPath`), because the staging folder is an implementation detail the operator should not have to decode.
@@ -43,7 +44,7 @@ Nothing in `lib/` — it is the entry point (`package.json`'s `main`). `bin/kiss
 - **A `generate: false` page claims no output path.** `_preparePage`'s `buildTo` dedupe only counts entries that will be written, on both sides — a skipped page neither fails a real page registered after it nor fails itself when one came first — and the replay sweep's `current` set excludes them, so a page that turns `generate: false` between builds has its stale output removed. It still sits on `_stack` (so `.scan()`'s by-view dedupe and the `complete()` data array are unchanged) and is skipped by the sitemap.
 - **After a promotion the instance is an ordinary one.** `_promote()` points `config.folders.build` back at the real folder and re-points every stack entry's `buildDir`/`buildTo`, so a second build on the same instance — or a watch rebuild — writes into the promoted folder instead of a staging sibling nothing will ever swap in again. `_stagedPath()` covers the one write that does not read `folders.build`: a `copyAssets()` the consumer aimed explicitly at the build folder (or a subfolder of it, the metacarpus idiom) is rewritten into staging, or the promotion's `fs.remove(target)` would delete the files that copy had just made. A copy aimed anywhere else is left where it was asked for.
 - **`'atomic'` is a one-shot-build feature, and dev mode says so.** With `dev: true` the promotion point is the wrong shape — the dev server serves `folders.build` from construction and every rebuild would have to promote — so `_setupFolders()` degrades `'atomic'` to `true` (wipe at construction, build in place) and logs one `notice` saying that atomic promotion applies to one-shot builds. A **non-dev** `.watch()` is the one seam left: it stages, promotes at the first successful `complete()`, and behaves as an ordinary watch after that. A build that never calls `complete()` never promotes, and `close()` removes the staging folder — which is also what clears a discarded one that a later write recreated (`_discardStaging` deliberately keeps `_stagingDir` set for exactly that).
-- **Every settled build assembles exactly one report** (`_finishBuild()`, `AIKB/build-report.md`), after the staging folder has been promoted or discarded so every path in it names the folder the site asked for. It is latched on `_report` rather than on `_failuresReported`, because the nested-`complete()` pattern settles one build twice and `KISS_REPORT` takes one line per build, not per call; `_report` (and `_sitemapPath`, and `_startedAt`) reset in `_replay()` with `_failures`, so a watch rebuild reports itself rather than the first build, and `duration` measures that rebuild rather than the hours the dev server has been up. The report is deliberately additive: `complete()` still resolves with the `generate` data array and still rejects with the `AggregateError` — consumers documented in `llms.txt` rely on both — and the report rides along on `err.report`.
+- **Every settled build assembles exactly one report** (`_finishBuild()`, `AIKB/build-report.md`), after the staging folder has been promoted or discarded so every path in it names the folder the site asked for. It is latched on `_report` rather than on `_failuresReported`, because the nested-`complete()` pattern settles one build twice and `KISS_REPORT` takes one line per build, not per call; `_report` (and `_sitemapPath`, `_llmsPath`, and `_startedAt`) reset in `_replay()` with `_failures`, so a watch rebuild reports itself rather than the first build, and `duration` measures that rebuild rather than the hours the dev server has been up. The report is deliberately additive: `complete()` still resolves with the `generate` data array and still rejects with the `AggregateError` — consumers documented in `llms.txt` rely on both — and the report rides along on `err.report`.
 - **A production build starts loading the HTML minifier in the constructor.** `preloadMinifier()` (`AIKB/kiss-page.md`) is called, unawaited, as soon as the config is resolved and `config.dev` is known to be false — before `_setupFolders()`, the asset copy and partial registration — so the minifier's ~155ms import overlaps that work and model resolution instead of sitting on the critical path at the first render. Check mode forces `dev: false` first, so a check preloads too. Dev never minifies and never loads it.
 - **Check mode is the one place the engine reads process state.** `KISS_CHECK` is read once in the constructor (`checkModeRequested()`), never in `resolveConfig`, which stays pure. It forces `cleanBuild: 'atomic'` and `dev: false` over the resolved config before `_setupFolders()` runs — so every write goes to the staging sibling and the real build folder is neither emptied nor written — and at the settle it **discards** the staging folder on success as well as on failure. `dev` cannot survive it: `'atomic'` degrades to a wipe in place under a dev server, and a check has to exit. Any value counts as on except `''`, `'0'` and `'false'`: `KISS_CHECK=true` falling silently through to a real build over published output is the one outcome the feature exists to prevent. `KISS_REPORT=<file>` is the second half of the channel — each settled build appends its report as one JSON Lines row, because a script may build several sites (`examples/7-versioned-outputs.js` builds two) and `bin/kiss-ssg.js` wants them all. A report that cannot be written is logged, never fatal. Neither variable changes the script's own exit code; the bin decides that (`AIKB/check.md`). What check mode cannot make honest is a script that reads its own build folder back after `complete()`: example 7's archive index lists the season folders on disk, and under a check no season was published, so it reports none.
 - **A staged build's `folders.build` is genuinely the staging path while it runs**, so a template rendering `{{config.folders.build}}` (or a controller reading it) sees the staging name, not the target. Nothing in the engine surfaces it — `{{asset}}` renders build-relative paths and `{{canonical}}`/`sitemap.xml` are built from `siteUrl` — but a site that prints the raw folder into its output should not use `'atomic'` for that page.
@@ -71,6 +72,7 @@ Nothing in `lib/` — it is the entry point (`package.json`'s `main`). `bin/kiss
 - **A renamed asset is invisible to the orphan sweep, on purpose.** The sweep works from `_stack` `buildTo` paths (page outputs); assets have no stack entry. Stale hashed files are removed by `lib/assets.js` from the manifest's own record of the name it replaced, not here.
 - **Under a hashing policy an asset edit re-renders the pages.** `watch()`'s `assetsChanged` normally just re-copies and names the built file for a live-reload stylesheet swap. With `config.assets.hash`, and only for a file the policy actually renames (`isHashable`, i.e. the built `.css`/`.js`), the copy has changed the filename, so every page is linking one that no longer exists: the handler instead asks the rebuild queue for a scoped re-render of `_stack` (the same scoped path an edited partial takes, but every entry: a renamed asset can be linked from any page) and lets the queue's `.finally()` do the one reload, after every page has been rewritten. An edited image or `robots.txt` keeps its name, so it keeps the cheaper targeted reload. `_builtAssetPath` also resolves through the manifest, so the path it hands live reload is the file that is actually on disk.
 - `_replay()` (watch rebuilds only) discards `_stack`, `_promises` and `_generating` (and `_failures`, and resets `_assetQueue`), re-registers partials, then re-runs `page()` for every entry in `_registrations` with `_replaying = true`, and finally `generate()` + `complete()`. Because the whole pipeline re-runs, models are re-read from disk (and URL models are _re-fetched_ — a watch rebuild costs a network round trip per remote model, unless `config.fetch.cache` is set to a directory, in which case the cached body is read instead and no request is made: see `AIKB/fetch-policy.md`) and controllers re-run; `_replaying` also propagates as `fresh` into `applyController`, which busts Node's module caches so an edited controller file reloads (see `AIKB/controller-resolver.md`). The build dir is _not_ cleaned by a replay (that would blow away assets and leave the site briefly empty for the dev server); instead the replay snapshots the previous stack's `buildTo` paths up front and, in a `finally` around `complete()`, removes any that the new stack no longer contains — plus the same-named `.json` dev debug sibling. So a page whose slug changed, or one that vanished from a shrinking `.pages()` fan-out, no longer leaves stale output behind. The removal runs in a `finally` so a failed rebuild still cleans up — but only one that failed **after** it re-queued the site. The `try` now opens right after `previous` is captured and wraps the whole re-registration half (`registerPartials()`, the drop-vanished-registrations filter, the re-scan, the `page()` loop) as well as `complete()`, and a `requeued` flag flips once the `page()` loop has run. Two reasons. (1) A throw in that half used to skip the `finally` altogether, so `previous` was lost and every stale output stayed on disk for the life of the process — no later replay could see it, because each one snapshots `previous` from a `_stack` that no longer mentions those files, and in dev mode the server went on serving a page that had been deleted. (2) Simply widening the `try` is not enough on its own: with `requeued` still false the new stack is empty because the replay _failed_, not because the site shrank, so an unguarded sweep would delete the entire build. So a replay that throws before re-queuing sweeps nothing and parks `previous` on `_unswept`, which the next replay folds back into its own `previous` (deduped) and sweeps then; the last good build stays on disk in the meantime and the failure is reported as `Error rebuilding site` as before. Once the pages are re-queued the old contract holds unchanged: every page that should exist has a `buildTo` in the stack (`_preparePage` runs before the render), so `previous` minus the stack is genuinely stale even when the rebuild then fails while rendering. **The sweep is only atomic at the rebuild's edge, not per page**: it removes the output and then its `.json` sibling one `await` later, and works through `previous` one entry at a time, so between those awaits the build dir is legitimately half-swept. The completion signal is the rebuild queue settling (`_rebuildInFlight`), never an individual file disappearing — anything that reacts to one removal and then reads another (a test, a deploy step) is reading a state the engine never promised. That is what made `test/integration/watch.test.js`'s deleted-scanned-view test load-sensitive: it waited on `gone.html` and then asserted on `gone.json`.
+- A replay re-runs `llms()` on the same rule and right after the sitemap, from `_llmsRequest` — an entry's title, description or URL can all change with a model or controller edit, so a stale `llms.txt` is exactly as wrong as a stale `sitemap.xml` was.
 - A replay re-runs `sitemap()` when one was ever requested: `sitemap()` records `_sitemapRequest = { options, callback }` (idempotent — the replay's own call re-records the same request), and `_replay()` re-issues it right after `generate()` so `complete()` drains it and `sitemap.xml` matches the new stack. v1 (and v2 before this) left `sitemap.xml` stale after a slug change in watch mode. Like the `generate` callback, the `sitemap` callback re-fires on every watch rebuild — once per replay, with that rebuild's `urls`, not just on the original call.
 - `_replaying` is read _synchronously_ at the top of `page()` — both to skip re-logging the registration and to capture `fresh` for the async chain that runs later. That is why `_replay()` can reset the flag in a `finally` immediately after the registration loop, even though the chains it started are still pending.
 - `_promises` and `_generating` are push-only _within a build_ — never spliced, only reassigned wholesale by `_replay()`. So repeated `complete()` calls inside one build re-await every promise ever queued (all already settled, so cheap), and a long-running `watch()` session no longer grows them without bound: each rebuild starts from empty arrays.
@@ -81,7 +83,7 @@ Nothing in `lib/` — it is the entry point (`package.json`'s `main`). `bin/kiss
 - **The `slug` and `path` fallbacks in `page()` both guard on `.endsWith('.hbs')`.** Only a `.hbs` view is a filename: its folder is the page's path and its basename the slug. An inline template string gets a random `snippet-N` slug (with a logged error) and an _empty_ path — deriving one from the view would cut at the last `/` in the template's own markup, so `'<p>x</p>'` built into `public/-p-x-/…` and any closing tag became an output folder, with the sitemap inheriting the wrong `loc` (review finding C5). The `path` guard was missing while the `slug` one ten lines above was not.
 - `_prepareMultiplePages` builds a **fresh options object per fanned-out page** (`{ ...options, slug, model }`), and must keep doing so. It previously mutated and reused one object across the loop, which `_preparePage` then stored on each `KissPage` by reference (`kissPage.options = options`) — so every page in the fan-out aliased the same options. The visible symptom was `applyController`'s "title from `model.title`, unless already set" mapping: item one filled the title and the guard skipped the rest, so all pages rendered the first item's title. `{{model.x}}` stayed correct throughout, which is why the characterization tests missed it — they only ever asserted on `model`, never on an option derived from it.
 - **A bad item in a `.pages()` fan-out fails that item only** (`_prepareMultiplePages`): the per-item `applyController` + `_preparePage` step runs inside its own `try`, so a controller that throws for one item is recorded as `{ view: '<view> [item N: <slug>]', buildTo: null, error }` and the loop moves on to the next item. It used to let the throw unwind the whole loop into `page()`'s `try`, which recorded one `{ view, buildTo: null }` entry and abandoned every later item — unregistered, unrendered and unreported, so one failure entry stood for the entire tail of the fan-out (review finding F-E1; diploma-msc fans 64 catalogue pages from one call). N bad items now report N failures and the good items still build. The label is the only handle the operator has on _which_ record was malformed: there is no `buildTo` yet, and every item in a fan-out shares one `view`, so the position is always included and the item's own `slug` too when the model carries one. Because nothing escapes the loop, `page()`'s catch never records a second entry for the same item — that double-record is what a `throw` after the per-item catch would reintroduce.
-- `viewStats()`'s `debug.json` serialises a _projection_ of `_stack` (`{ view, buildTo, runCount, options }`), never the entries themselves: a stack entry's `page` holds the Handlebars environment (internally cyclic) and the logger, so `JSON.stringify` on the raw stack throws "Converting circular structure to JSON" and the file silently never gets written. The write is not awaited — `test/integration/view-stats.test.js` polls for the file with `waitFor`.
+- `viewStats()`'s `debug.json` serialises a _projection_ of `_stack` (`{ view, buildTo, runCount, options }`), never the entries themselves: a stack entry's `page` holds the Handlebars environment (internally cyclic) and the logger, so `JSON.stringify` on the raw stack throws "Converting circular structure to JSON" and the file silently never gets written. The write is not awaited — `test/integration/view-stats.test.js` polls for the file with `waitFor`, on it _parsing_ rather than on it existing: `fs.outputJson` creates the file truncated and fills it a tick later, so a `pathExists` poll wins the race often enough to fail the suite under load and reads back an empty string.
 - Watcher rebuilds are fire-and-forget from the watcher's point of view — nothing awaits what `_handleChange` returns — but they are still _tracked_: `_rebuild(entries)` pushes each `page.generate().catch(() => {})` onto `_generating` (caught there because `KissPage.generate()` now rethrows, and it has already logged; a scoped rebuild must not turn into an unhandled rejection or a `complete()` failure), so a replay's `allSettled` waits for it and `complete()` drains it. `_generating` accumulates one entry per re-rendered page until the next replay resets the array.
 - **All rebuild work goes through one serial queue** (`_runRebuildQueue()`): one in-flight slot and one pending slot, where the pending slot is a set of scoped targets (stack entries to re-render) plus a "replay" bit. `_requestReplay()` sets the bit and clears the set — a replay rebuilds everything, so it supersedes every scoped rebuild — and returns the in-flight promise, so N rapid watcher events (save-all, a formatter, a branch switch) produce at most one in-flight run plus one follow-up and the last replay reads the newest files. `_requestRebuild(entries)` adds to the set, or is a no-op while the bit is set. Two rebuilds must never overlap, for two distinct reasons: `_replay()` resets `_stack` synchronously, so two replays interleaved would let the older one's still-pending chains fill the new stack and the newer pages — the ones carrying the newest edit — would be rejected by `_preparePage`'s `buildTo` dedupe with a `Page already processed` error, leaving stale output; and scoped work in flight when a replay starts re-renders from a stack the replay is about to discard. Two scoped rebuilds racing each other are the same hazard in miniature, which is why the queue covers both kinds rather than only replays. The follow-up run is _not_ chained into the returned promise (the `.finally()` callback returns `undefined`), so awaiting `_requestReplay()` waits only for the run that was in flight. Errors from either kind of run are caught and logged as `Error rebuilding site`.
 - **Live reload is issued from here, once per settled build**, because nothing watches the build folder any more (review finding F-E4 — see `AIKB/dev-server.md` for what was removed and why). `_reload(changed = '/')` is the single call site of the dev server's `refresh`; it is a no-op when there is no dev server, and it swallows anything the call throws, because a live-reload socket that has gone away must never fail the rebuild that triggered it. There are exactly three places it fires:
@@ -117,7 +119,7 @@ Nothing in `lib/` — it is the entry point (`package.json`'s `main`). `bin/kiss
 
 `kiss-ssg` ships TypeScript declarations without being TypeScript. The public API's JSDoc lives beside the runtime it describes — the page/build typedefs at the top of this module, the config ones in `lib/config.js` — and `npm run types` generates `types/*.d.ts` from it. `package.json` points `types` and its `exports` map at `types/kiss.d.ts`, and `files` ships the folder, so a consumer gets full completion from plain JavaScript with `// @ts-check` and no TypeScript of their own.
 
-- **The typedefs declared here**: `PageOptionsKnown` (the documented page options) and `PageOptions` (those plus arbitrary extra keys, which render as top-level context); `PagesOptions`; `PageOptionsPatch` and the `KissController` callback that returns one; `BuildDatum`/`BuildData` (what `generate()`/`complete()` resolve with), `BuildFailure`, and `BuildError` — the `AggregateError & { failures }` `complete()` rejects with; `SitemapUrl`, `SitemapOptions`, `WatchOptions`. `KissConfig`, `KissConfigInput` and `KissFolders` are re-exported from `lib/config.js`, and `BuildReport`, `BuildPage`, `BuildAsset` and `BuildReportFailure` from `lib/build-report.js`, both with `@typedef {import('./x.js').X} X` — so a consumer reaches every one of them as `import('kiss-ssg').X` from a single entry.
+- **The typedefs declared here**: `PageOptionsKnown` (the documented page options) and `PageOptions` (those plus arbitrary extra keys, which render as top-level context); `PagesOptions`; `PageOptionsPatch` and the `KissController` callback that returns one; `BuildDatum`/`BuildData` (what `generate()`/`complete()` resolve with), `BuildFailure`, and `BuildError` — the `AggregateError & { failures }` `complete()` rejects with; `SitemapUrl`, `SitemapOptions`, `LlmsOptions`, `WatchOptions`. `KissConfig`, `KissConfigInput` and `KissFolders` are re-exported from `lib/config.js`, and `BuildReport`, `BuildPage`, `BuildAsset` and `BuildReportFailure` from `lib/build-report.js`, both with `@typedef {import('./x.js').X} X` — so a consumer reaches every one of them as `import('kiss-ssg').X` from a single entry.
 - **Every `_`-prefixed field and method is marked `@private`**, so the emitted class declaration carries them as `private _stack;` rather than as documented API. The public surface of `types/kiss.d.ts` is exactly the API llms.txt describes.
 - **`npm run types` is `node scripts/emit-types.mjs`, not a bare `tsc`, because of one TypeScript bug.** The declaration emitter drops the quotes from an arbitrary module namespace name when it reads it out of a `.js` file (from a `.ts` source they survive), so `export { Kiss as 'module.exports' }` — the line that makes `require('kiss-ssg')` return the class on Node ≥22.12 — comes out as `export { Kiss as module.exports }`, which is a **syntax error**: the whole declaration fails to parse, and every consumer silently falls back to `any`. The script runs `tsc -p tsconfig.types.json` and then puts the quotes back (`quoteStringExportNames`). Re-check this whenever TypeScript is upgraded; the fixup is a regex over the emitted text and `test/unit/types.test.js` asserts the line survives.
 - **`types/` is checked in and must not be hand-edited.** `test/unit/types.test.js` re-emits into a temp folder and byte-compares every file, so a JSDoc edit without a regeneration fails the suite naming the file and the command. `types/` is in `.prettierignore` — tsc owns its formatting, and the comparison is against exactly what tsc wrote.

package/AIKB/llms.md

@@ -0,0 +1,32 @@
+# llms.js
+
+## Responsibility
+
+Builds the [llmstxt.org](https://llmstxt.org) index — `llms.txt` — from the page stack and writes it to the build folder. The AI-facing sibling of `sitemap.js`: same registry, same titles, same URL derivation, a different file for a different reader.
+
+## Public interface
+
+- `resolveText(value)` → `Promise<string>`. A `summary`/`notes` option is either the text itself or a path (relative to `process.cwd()`) to a file holding it: if the string names an existing **file** its contents are returned, otherwise the string is. A `.md` file is used as-is — `llms.txt` is markdown. Only a single-line string of at most 512 characters is offered to `fs` at all; anything longer or multi-line is prose by construction. A non-string is `''`.
+- `sectionNameFor(segment, sections = {})` → the display name for one top-level path segment: `sections[segment]` if mapped, else the segment title-cased with `-`/`_` read as spaces. The empty segment is the root group: `sections.root`, else `'Pages'`.
+- `buildLlmsEntries(stack, { siteUrl, buildDir, sections })` → `{ title, url, description, section }[]` in registration order. Skips an entry whose `page.options` has `ignoreLlms`, `ignoreSitemap`, or `generate === false`. `url` is `toAbsoluteUrl(siteUrl, toCanonicalPath(buildTo.slice(buildDir.length)))` — the identical join `buildSitemapEntries` makes. `section` is `options.llmsSection` when set, else `sectionNameFor` over the first segment of the page's (sanitised) `path`.
+- `groupLlmsEntries(entries, rootSection)` → `{ name, entries }[]`, sections in first-seen order with the root section hoisted to the front when it is present.
+- `renderLlmsTxt({ title, summary, groups, notes })` → the file's text: `# title`, a `> ` blockquote summary, one `## Section` per group with a `- [title](url): description` line per page (`: description` omitted when there is none), an optional trailing `## Notes`. One trailing newline, a blank line under every heading.
+- `async writeLlms(stack, { config, logger, options, overwrite = true })` → `Promise<{ status, text }>`. `status` is `'no-site-url'`, `'no-title'`, `'no-summary'` (nothing written), `'skipped'` (`overwrite: false` and a file exists), or `'written'`.
+
+## Depends on
+
+`fs-extra`; `./utils.js` (`sanitizePath`, `toAbsoluteUrl`, `toCanonicalPath`, `toTitleCase`).
+
+## Depended on by
+
+`lib/kiss.js` (`Kiss.llms()`).
+
+## Non-obvious behavior
+
+- **The URL derivation is copied from `sitemap.js` on purpose, not shared by accident.** Both call the same two `utils` functions over the same `buildTo`, which is what makes an `llms.txt` entry, a `<loc>` and a page's own `{{canonical}}` one string — a directory index keeps its trailing slash in all three. `test/integration/llms.test.js` asserts the three agree under `extensionLess` both ways; changing the join here without changing it there breaks that.
+- **`ignoreSitemap` excludes a page from `llms.txt` too.** The AI index is a curated subset of the site the sitemap describes, never a superset: a page the author has already said should not be crawled has no business being recommended to an answer engine. `ignoreLlms` is the one-way opt-out — out of `llms.txt`, still in the sitemap.
+- **An untitled page arrives here titled `Index`.** `KissPage`'s constructor computes its default title from the _placeholder_ slug (`index`) before the real slug is set, so `prepare()` fills every untitled page's `title` with `'Index'`. That value is treated as unset and the page's own slug is title-cased instead (`puppy-classes` → `Puppy Classes`). It costs nothing for a page that really is the index — its slug title-cases to the same word — and it costs a page genuinely titled "Index" its title, which is the cheaper of the two mistakes.
+- Titles and descriptions are collapsed to one line (`\s+` → one space) before rendering: a description is what follows `: ` on the entry's own line, and a newline in it would silently end the list item. `[`/`]`/`\` in a title are backslash-escaped and `(`/`)` in a URL are percent-encoded, so a bracketed title or a parenthesised path stays a valid markdown link.
+- `writeLlms` deliberately does **not** catch its own write error (`fs.outputFile` can reject) — it propagates to `Kiss.llms()`'s `.catch()`, which logs it and does not invoke the callback. Same contract as `writeSitemap`.
+- Missing `siteUrl`, `title` or `summary` are reported as a status, never thrown: the rest of the build is still what the author asked for, minus this file. `Kiss.llms()` fires the callback for `'written'` and `'skipped'` only.
+- `overwrite: false` only has an observable effect with `cleanBuild: false` too — the default `cleanBuild: true` empties the build folder in the `Kiss` constructor, so there is never an existing `llms.txt` left to skip.

package/AIKB/sitemap.md

@@ -16,7 +16,7 @@ Builds `sitemap.xml` entries from the page stack and writes the file to the buil
 
 ## Depended on by
 
-`lib/kiss.js` (`Kiss.sitemap()`).
+`lib/kiss.js` (`Kiss.sitemap()`). `lib/llms.js` is its sibling rather than a consumer: it copies the same `buildTo` → `toCanonicalPath` → `toAbsoluteUrl` derivation, and honours `ignoreSitemap` as an exclusion of its own — a page kept out of the sitemap is kept out of `llms.txt` too.
 
 ## Non-obvious behavior
 

package/README.md

@@ -38,14 +38,14 @@ That file is the API contract: the pipeline, every method and option, the helper
 
 Give the agent a verdict it can act on: `npx kiss-ssg check site.js` runs your build script as a dry run and prints one JSON report per site built, exit 1 on any failure, without touching the published output (see [Checking a build](#checking-a-build)).
 
-If the agent is Claude Code, this repository is also a plugin marketplace:
+If the agent is Claude Code, this repository is also a plugin marketplace. In Claude Code, run:
 
 ```
 /plugin marketplace add cprobert/kiss-ssg
 /plugin install kiss-ssg@kiss-ssg
 ```
 
-That installs three skills — `/kiss-ssg:new-site` (build a site from a description), `/kiss-ssg:migrate-v1` (move a v1 project to v2) and `/kiss-ssg:check` (verify a build and read its report). They carry no copy of the API: each points at the docs installed in `node_modules/kiss-ssg/`, so the guidance cannot drift from the engine you have. The plugin source is [`plugins/kiss-ssg/`](plugins/kiss-ssg/).
+The first line registers this repository as a marketplace; the second installs the plugin from it. That installs four skills, all named `kiss-<something>` so they're easy to spot alongside skills from other plugins — `/kiss-ssg:kiss-new-site` (build a site from a description, or a whole new section on one), `/kiss-ssg:kiss-add-page` (add or update a single page on a site that's already set up), `/kiss-ssg:kiss-migrate-v1` (move a v1 project to v2) and `/kiss-ssg:kiss-check` (verify a build and read its report). They carry no copy of the API: each points at the docs installed in `node_modules/kiss-ssg/`, so the guidance cannot drift from the engine you have. You don't have to invoke them by name — each skill's description is written for automatic discovery, so a request like "add a page to this site" or "why is my kiss-ssg build failing" reaches for the matching skill on its own. The plugin source is [`plugins/kiss-ssg/`](plugins/kiss-ssg/).
 
 ## Usage
 
@@ -426,6 +426,51 @@ kiss.sitemap({ overwrite: false })
 
 **Note**: `overwrite: false` only has an effect if you also set `cleanBuild: false` on the Kiss config. With the default `cleanBuild: true`, the whole build folder — including any previous `sitemap.xml` — is emptied before generation starts, so there's never an existing file left for `.sitemap()` to find.
 
+### .llms()
+
+Writes an [`llms.txt`](https://llmstxt.org) into the root of the build folder: the curated, AI-facing index of your site, the file an answer engine reads before it crawls. It is `.sitemap()`'s sibling — same registry, same titles, same URLs, a different reader — so the two can never drift apart. It needs `siteUrl`, a `title` and a `summary`; without any of them it logs an error and skips the file rather than throwing.
+
+```js
+kiss
+  .page({
+    view: 'index.hbs',
+    title: 'A1K9 Training',
+    description: 'Dog training and behaviour work in South Wales',
+  })
+  .pages({ view: 'courses/course.hbs', model: 'courses', path: 'courses' })
+  .page({ view: 'rota.hbs', ignoreLlms: true }) // in the sitemap, out of the index
+  .generate()
+  .sitemap()
+  .llms({
+    title: 'A1K9 Training',
+    summary: 'Dog behaviour and obedience training in South Wales.',
+    sections: { root: 'Pages', courses: 'Courses' },
+    notes: 'src/content/llms-notes.md',
+  })
+```
+
+writes:
+
+```markdown
+# A1K9 Training
+
+> Dog behaviour and obedience training in South Wales.
+
+## Pages
+
+- [A1K9 Training](https://a1k9training.co.uk/): Dog training and behaviour work in South Wales
+
+## Courses
+
+- [Bronze obedience](https://a1k9training.co.uk/courses/bronze-obedience): Six weeks, group class
+```
+
+**The options**: `title` is the `# ` heading and `summary` the `> ` blockquote — and `summary` (like the optional `notes`, which becomes a trailing `## Notes` section) is either the text itself or a path, relative to your working directory, to a `.md`/`.txt` file holding it, so a long summary can live beside the rest of your content. `sections` maps a top-level path segment to a heading (`{ courses: 'Courses' }`); the key `root` names the section holding pages with no path (default `Pages`), and any segment you do not map is title-cased (`behavioural-consultations` → `Behavioural Consultations`). `overwrite` (default `true`) behaves exactly as the sitemap's.
+
+**Which pages are listed**: every registered page, grouped by the first segment of its `path` with the root group first, in registration order. A page opts out with `ignoreLlms: true`, and a page already out of the sitemap (`ignoreSitemap: true`) or not being built at all (`generate: false`) is out of `llms.txt` too — the index is a subset of the site the sitemap describes, never a superset. `llmsSection: 'Name'` puts one page under a heading of your choosing regardless of its path. Each entry is `- [title](url): description`, with the description omitted when the page has none and the title falling back to the page's slug, title-cased; each URL is the same string that page's own `{{canonical}}` renders.
+
+It is chainable, can be called before or after `.generate()`, and is re-run by a whole-site watch rebuild like `.sitemap()`. Its callback receives the rendered text (`kiss.llms(options, (text) => …)`), and the file it wrote is reported as the build report's `llms`.
+
 ### Waiting for the build
 
 `.generate()` is chainable and returns immediately; its callback fires once every page has been attempted — including any that failed to render or write. Failures don't surface through this callback; they surface via `.complete()` (below). The callback's `data` argument (and `.complete()`'s resolved value) is `[{ id, data }]`, **one entry per queued promise in registration order** — the assets copy that runs automatically at construction is queued before any page you register, so `data[0]` is that copy's result, not your first page. Use `.getModelByID(id, data)` (see "Other methods" below) to pull out a specific page's model rather than indexing by position. To wait for the whole build (including a `.sitemap()` call and anything queued from a callback):
@@ -483,7 +528,9 @@ npx kiss-ssg check menu.js 2026-spring # arguments after the script go to the sc
       }
     ],
     "assets": [{ "source": "css/site.css", "target": "css/site.605b52d7.css" }],
-    "sitemap": "./public/sitemap.xml"
+    "sitemap": "./public/sitemap.xml",
+    "pipeline": [{ "name": "tailwind", "ok": true, "duration": 420 }],
+    "llms": "./public/llms.txt"
   }
 ]
 ```
@@ -499,7 +546,7 @@ Two things a check cannot make true. A site that reads its own build folder back
 - `.registerPartials()` — re-registers every partial and layout from disk, unregistering any whose file has gone, and returns the registered names. Kiss runs it for you at start-up and on every watch rebuild; call it yourself if you add or remove partial files at runtime without `.watch()`.
 - `.viewStats()` — logs how many pages are queued and prepared, and with `verbose: true` writes a `debug.json` into the build folder listing every page as `{ view, buildTo, runCount, options }`. Chainable; handy from a `.generate()` callback to see what the build actually produced.
 - `.getModelByID(id, data)` — pulls one entry out of the `[{ id, data }]` array `.generate()`/`.complete()` hand back, returning its `data` (or `{ error }` if no entry has that id). The id is the model's filename or URL.
-- `.report()` — the last settled build as data, or `null` before the first `.complete()` has settled: `{ ok, mode, buildDir, duration, pages, failures, assets, sitemap }`, every value JSON-safe. `pages` is `{ view, buildTo, ok }` per queued page and `failures` is `{ view, buildTo, message }` — the same list as `err.failures`, with each `Error` reduced to its message. The same object is on the rejection as `err.report`, so a failed build can be read as data rather than parsed out of a log. See "Checking a build" above.
+- `.report()` — the last settled build as data, or `null` before the first `.complete()` has settled: `{ ok, mode, buildDir, duration, pages, failures, assets, sitemap, pipeline, llms }`, every value JSON-safe. `pages` is `{ view, buildTo, ok }` per queued page and `failures` is `{ view, buildTo, message }` — the same list as `err.failures`, with each `Error` reduced to its message. The same object is on the rejection as `err.report`, so a failed build can be read as data rather than parsed out of a log. See "Checking a build" above.
 
 ```js
 kiss.scan().generate(function (data) {

package/examples/10-asset-pipeline/assets/css/generated.css

@@ -1,4 +1,4 @@
-/* generated from styles/tokens.json at 2026-09-09T10:08:48.985Z — do not edit */
+/* generated from styles/tokens.json at 2026-09-10T12:32:52.196Z — do not edit */
 :root {
   --accent: #0f766e;
   --accent-ink: #ffffff;

package/examples/6-sitemap/README.md

@@ -1,10 +1,14 @@
-# 6 · sitemap
+# 6 · sitemap and llms.txt
 
 `.sitemap()` writes `sitemap.xml` from the pages already registered, using `config.siteUrl` —
 without which it logs an error and skips the file rather than guessing. Per-page
 `ignoreSitemap`, `sitemapPriority` and `sitemapChangefreq` tune the entries, and this is the one
 example that turns on `assets: { hash: true }` and `extensionLess: true`.
 
+`.llms()` writes `llms.txt` beside it from the same registry — an llmstxt.org index with a
+title, a `>` summary, one `##` section per top-level path and a `- [title](url): description`
+line per page. `rota` is out of both files from the one `ignoreSitemap` on its page.
+
 ## Run it
 
 ```bash
@@ -18,3 +22,5 @@ node 6-sitemap.js --dev  # live preview on http://127.0.0.1:3001
 The config block in `6-sitemap.js`: `siteUrl`, `extensionLess` and `assets: { hash: true }` are
 three decisions every published site has to make, and the layout's `{{asset 'css/site.css'}}`
 is unchanged by any of them — the template asks for a file, the config decides how it is cached.
+And the `.sitemap().llms()` pair at the end of the chain: two files, one registry, so a crawler
+and an answer engine are told the same thing.

package/examples/6-sitemap.js

@@ -50,6 +50,18 @@ const kiss = new Kiss({
     console.log('sitemap.xml lists:', urls)
   })
 
+  // The sitemap's sibling: llms.txt, the llmstxt.org index an answer engine
+  // reads first. Same registry, same URLs — `rota` is out of both, because a
+  // page kept out of the sitemap is kept out of this too. The summary is
+  // inline here; a path to a `.md` file would be read instead.
+  .llms({
+    title: 'Aster & Oak',
+    summary:
+      'A small-batch coffee roastery in Bristol. Beans, brewing notes and the shops that stock us.',
+    sections: { root: 'Pages' },
+    notes: 'Prices and opening hours change seasonally.',
+  })
+
 if (!dev) {
   await kiss.complete().catch(reportBuildFailure)
 }

package/examples/README.md

@@ -9,7 +9,7 @@ They come in two tiers.
 
 **Examples 1–6 and 10 are the feature reference: one idea each.** Scanning a folder of views,
 registering a page by hand, fanning out over an array, layouts and partials, the built-in
-helpers, the sitemap, an external tool in the asset pipeline. Each script is short enough to read in one sitting and each page explains,
+helpers, the sitemap and llms.txt, an external tool in the asset pipeline. Each script is short enough to read in one sitting and each page explains,
 in a "How this example works" panel, the feature it is demonstrating — with the script that built
 it printed underneath. Read one when you want to know how a single thing works.
 
@@ -27,7 +27,7 @@ the feature reference.
 | [3 · pages](3-pages/)                               | Reference | `.pages()` fans out one page per JSON file; the index reuses the same resolved array       | `npm run eg3` · `--dev`                                |
 | [4 · layouts and partials](4-layouts-and-partials/) | Reference | One layout, blocks and content, nested `.hbs`/`.html`/`.md` partials, a dynamic partial    | `npm run eg4` · `--dev`                                |
 | [5 · helpers](5-helpers/)                           | Reference | The six built-in helpers, all on one page, plus custom dev ports                           | `npm run eg5` · `--dev`                                |
-| [6 · sitemap](6-sitemap/)                           | Reference | `.sitemap()` with `siteUrl`, per-page tuning, `extensionLess`, hashed assets               | `npm run eg6` · `--dev`                                |
+| [6 · sitemap and llms.txt](6-sitemap/)              | Reference | `.sitemap()` and `.llms()` with `siteUrl`, per-page tuning, `extensionLess`, hashed assets | `npm run eg6` · `--dev`                                |
 | [7 · versioned outputs](7-versioned-outputs/)       | Exemplar  | One build per season into its own folder, atomically, with an archive index beside them    | `npm run eg7` · `node 7-versioned-outputs.js <season>` |
 | [8 · data-fed site](8-data-fed-site/)               | Exemplar  | A site built from a folder of records, validated in the controller — one record is broken  | `npm run eg8` · exits 1 · `--dev`                      |
 | [9 · migrated from v1](9-migrated-from-v1/)         | Exemplar  | Every v1 → v2 migration recipe as running code, in a site that builds clean                | `npm run eg9` · `--dev`                                |

package/lib/build-report.js

@@ -55,6 +55,7 @@
  * @property {BuildAsset[]} assets
  * @property {string|null} sitemap the `sitemap.xml` written, or `null` if none was
  * @property {BuildPipelineStep[]} pipeline every `config.assets.pipeline` step, in order; empty when there are none
+ * @property {string|null} llms the `llms.txt` written, or `null` if none was
  */
 
 // A staged build writes into `<build>.kiss-staging-<pid>-<random>`, which is an
@@ -100,6 +101,7 @@ function reportedView(view) {
  * @param {number} [input.startedAt] `Date.now()` at construction
  * @param {string|null} [input.sitemap] the sitemap written by this build
  * @param {import('./pipeline.js').PipelineResult[]} [input.pipeline] what the asset pipeline's steps did
+ * @param {string|null} [input.llms] the llms.txt written by this build
  * @returns {BuildReport}
  */
 export function buildReport({
@@ -112,6 +114,7 @@ export function buildReport({
   startedAt = Date.now(),
   sitemap = null,
   pipeline = [],
+  llms = null,
 }) {
   const real = (target) => reportedPath(target, buildDir, stagingDir)
   const failedPaths = new Set(
@@ -153,6 +156,10 @@ export function buildReport({
       ok,
       duration,
     })),
+    // Appended for the same reason `pipeline` was: a consumer diffing two
+    // reports should see one new key, not a reshuffle of the nine already
+    // there.
+    llms: real(llms),
   }
 }
 

package/lib/kiss.js

@@ -16,6 +16,7 @@ import { buildReport } from './build-report.js'
 import { resolveModel } from './model-resolver.js'
 import { applyController } from './controller-resolver.js'
 import { writeSitemap } from './sitemap.js'
+import { writeLlms } from './llms.js'
 import { KissPage, preloadMinifier } from './kiss-page.js'
 import { startDevServer } from './dev-server.js'
 import { createWatcher, isInside } from './watcher.js'
@@ -50,6 +51,8 @@ import { createWatcher, isInside } from './watcher.js'
  * @property {string} [sitemapPriority] default `'1.00'`
  * @property {string} [sitemapChangefreq] omitted from the XML unless set
  * @property {string} [sitemapLastmod] default: one timestamp shared by every page
+ * @property {boolean} [ignoreLlms] keep this page out of `llms.txt`
+ * @property {string} [llmsSection] the `llms.txt` section this page is listed under, overriding its path
  */
 
 /**
@@ -134,6 +137,19 @@ import { createWatcher, isInside } from './watcher.js'
  * @property {boolean} [overwrite] default `true`; `false` leaves an existing `sitemap.xml` alone
  */
 
+/**
+ * The options `.llms()` takes. `title` and `summary` are required — without
+ * either, kiss logs an error and writes nothing, exactly as it does for a
+ * sitemap with no `siteUrl`.
+ *
+ * @typedef {Object} LlmsOptions
+ * @property {string} title the site's name — the file's `# ` heading
+ * @property {string} summary what the site is, as a `> ` blockquote: the text itself, or a path (relative to `process.cwd()`) to a `.md`/`.txt` file holding it
+ * @property {string} [notes] a trailing `## Notes` section; same text-or-file rule as `summary`
+ * @property {Record<string, string>} [sections] top-level path segment → section heading (`{ courses: 'Courses' }`); the key `root` names the section holding pages with no path (default `Pages`). An unmapped segment is title-cased.
+ * @property {boolean} [overwrite] default `true`; `false` leaves an existing `llms.txt` alone
+ */
+
 /**
  * @typedef {Object} WatchOptions
  * @property {string} [entry] the script whose own change triggers a whole-site rebuild; defaults to `process.argv[1]`
@@ -221,6 +237,8 @@ class Kiss {
   /** @private */
   _sitemapRequest = null
   /** @private */
+  _llmsRequest = null
+  /** @private */
   _watcher = null
   /** @private */
   _devServer = null
@@ -262,6 +280,9 @@ class Kiss {
   // Where this build wrote sitemap.xml, if it wrote one.
   /** @private */
   _sitemapPath = null
+  // Where this build wrote llms.txt, if it wrote one.
+  /** @private */
+  _llmsPath = null
   // Whether KISS_CHECK asked for a dry run: build into staging, report, and
   // discard — the real build folder is neither emptied nor written.
   /** @private */
@@ -665,6 +686,7 @@ class Kiss {
       startedAt: this._startedAt,
       sitemap: this._sitemapPath,
       pipeline: this._pipelineResults,
+      llms: this._llmsPath,
     })
     // The graph as data, for a human to look at: which pages each partial
     // reaches. Dev only — a one-shot build has no watcher to use it — and
@@ -1267,6 +1289,49 @@ class Kiss {
     return this
   }
 
+  /**
+   * Writes `llms.txt` into the build folder — the llmstxt.org index an answer
+   * engine reads first — from the same registry, titles and URLs the sitemap is
+   * built from, so the two can never disagree. Requires `config.siteUrl`, and
+   * `options.title`/`options.summary`; without any of them this logs an error
+   * and skips. Like `.sitemap()`, it can be called before or after
+   * `.generate()`, and it is re-run by a whole-site watch rebuild.
+   *
+   * @param {LlmsOptions} options
+   * @param {(text: string) => void|Promise<void>} [callback] receives the
+   * rendered file; not fired when llms.txt was skipped for want of an option
+   * @returns {this}
+   */
+  llms(options, callback) {
+    // Remembered so a watch rebuild can re-run it against the new stack, the
+    // same way `_sitemapRequest` is — the replay's own call re-records it.
+    this._llmsRequest = { options, callback }
+    const overwrite = !options || options.overwrite !== false
+    const run = Promise.all(this._promises)
+      .then(async () => {
+        const { status, text } = await writeLlms(this._stack, {
+          config: this.config,
+          logger: this.logger,
+          options: options || {},
+          overwrite,
+        })
+        // A missing siteUrl, title or summary wrote nothing and there is
+        // nothing to hand a callback; a skip left an existing file in place,
+        // which is still the build's llms.txt.
+        if (status !== 'written' && status !== 'skipped') return
+        // A staged build records the staging path and the report maps it back
+        // to the real folder, like every other path in it.
+        this._llmsPath = `${this.config.folders.build}/llms.txt`
+        if (callback) this._runCallback('llms', callback, text)
+      })
+      .catch((err) => {
+        this.logger.error('Error creating llms.txt')
+        this.logger.warn(err)
+      })
+    this._generating.push(run)
+    return this
+  }
+
   /**
    * Pulls one resolved model out of the array `.generate()`/`.complete()` hand
    * back — the way to read a model without relying on its position.
@@ -1325,6 +1390,7 @@ class Kiss {
     // report the hours since the process started as its duration.
     this._report = null
     this._sitemapPath = null
+    this._llmsPath = null
     this._startedAt = Date.now()
     this._callbacks = []
     this._assetQueue = Promise.resolve()
@@ -1389,6 +1455,9 @@ class Kiss {
           this._sitemapRequest.callback,
         )
       }
+      if (this._llmsRequest) {
+        this.llms(this._llmsRequest.options, this._llmsRequest.callback)
+      }
       await this.complete()
     } finally {
       // A replay that threw before re-queuing has an empty stack because it

package/lib/llms.js

@@ -0,0 +1,249 @@
+import fs from 'fs-extra'
+import {
+  sanitizePath,
+  toAbsoluteUrl,
+  toCanonicalPath,
+  toTitleCase,
+} from './utils.js'
+
+/**
+ * One page as `llms.txt` lists it.
+ *
+ * @typedef {Object} LlmsEntry
+ * @property {string} title the page's `title`, or its slug title-cased
+ * @property {string} url the same absolute URL the sitemap and `{{canonical}}` emit
+ * @property {string} description the page's `description`, or `''` when it has none
+ * @property {string} section the display name of the group it belongs to
+ */
+
+/**
+ * One `##` section of the file: a display name and the pages under it.
+ *
+ * @typedef {Object} LlmsGroup
+ * @property {string} name
+ * @property {LlmsEntry[]} entries
+ */
+
+// The title `KissPage.prepare()` fills in for a page that was given none. It is
+// derived from the *placeholder* slug (`index`) in the constructor, before the
+// real slug is set, so every untitled page arrives here as "Index" — which is a
+// useless entry in a curated index. Treated as unset, and the page's own slug
+// title-cased instead. Harmless for a page that really is the index: its slug
+// title-cases to the same word.
+const UNTITLED = 'Index'
+
+// A summary or notes option is either the text itself or a path to a file
+// holding it. `fs` decides which — but only for a string that could plausibly be
+// a path: a multi-line or very long one is prose, and asking the filesystem
+// about it is a syscall that can only ever answer "no".
+const MAX_PATH_LENGTH = 512
+
+/**
+ * Resolves a `summary`/`notes` option: the contents of the file it names, or the
+ * string itself. A `.md` file is used as it is — `llms.txt` is markdown.
+ *
+ * @param {unknown} value
+ * @returns {Promise<string>} the resolved text, trailing whitespace trimmed
+ */
+export async function resolveText(value) {
+  if (typeof value !== 'string') return ''
+  const looksLikePath =
+    value.length > 0 && value.length <= MAX_PATH_LENGTH && !value.includes('\n')
+  if (looksLikePath) {
+    // Relative to process.cwd(), like every other path a build script hands the
+    // engine from the outside.
+    const stat = await fs.stat(value).catch(() => null)
+    if (stat?.isFile()) return (await fs.readFile(value, 'utf8')).trimEnd()
+  }
+  return value.trimEnd()
+}
+
+/**
+ * The display name for one top-level path segment: an explicit mapping, else the
+ * segment title-cased. The root group (a page with no `path`) is keyed `root`.
+ *
+ * @param {string} segment the sanitised first segment of a page's `path`, `''` for a root page
+ * @param {Record<string, string>} [sections]
+ * @returns {string}
+ */
+export function sectionNameFor(segment, sections = {}) {
+  if (sections[segment]) return sections[segment]
+  if (!segment) return sections.root || 'Pages'
+  return toTitleCase(segment.replace(/[-_]+/g, ' '))
+}
+
+// A title is link text and a description follows a colon on the same line, so
+// neither may carry a newline into the file.
+const oneLine = (value) =>
+  typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : ''
+
+// `[` and `]` would end the link text early; the URL's own parentheses would end
+// the target early. Percent-encoding the URL's is safe — it is the same URL — so
+// the entry stays a valid markdown link either way.
+const escapeText = (text) => text.replace(/([[\]\\])/g, '\\$1')
+const escapeUrl = (url) => url.replace(/\(/g, '%28').replace(/\)/g, '%29')
+
+function entryTitle(options) {
+  const slugTitle = toTitleCase(String(options.slug ?? '').replace(/-/g, ' '))
+  const title = oneLine(options.title)
+  return title && title !== UNTITLED ? title : slugTitle
+}
+
+/**
+ * One entry per page that belongs in `llms.txt`, in registration order. A page
+ * is left out by `ignoreLlms`, by `ignoreSitemap` (the AI index is a curated
+ * subset of the same site the sitemap describes, never a superset), or by
+ * `generate: false` (there is nothing at that URL).
+ *
+ * @param {{ buildTo: string, page: { options: Record<string, any> } }[]} stack
+ * @param {Object} context
+ * @param {string} context.siteUrl
+ * @param {string} context.buildDir
+ * @param {Record<string, string>} [context.sections] top-level path segment → display name
+ * @returns {LlmsEntry[]}
+ */
+export function buildLlmsEntries(stack, { siteUrl, buildDir, sections = {} }) {
+  return stack
+    .filter((entry) => {
+      const options = entry.page.options
+      return (
+        !options.ignoreLlms &&
+        !options.ignoreSitemap &&
+        options.generate !== false
+      )
+    })
+    .map((entry) => {
+      const options = entry.page.options
+      // Exactly the join `buildSitemapEntries` makes, and therefore exactly the
+      // one the `canonical` helper makes: an entry here can never name a URL
+      // the page itself does not claim.
+      const urlPath = toCanonicalPath(entry.buildTo.slice(buildDir.length))
+      const segment = String(sanitizePath(String(options.path ?? '')) || '')
+        .split('/')[0]
+        .trim()
+      return {
+        title: entryTitle(options),
+        url: toAbsoluteUrl(siteUrl, urlPath),
+        description: oneLine(options.description),
+        section:
+          oneLine(options.llmsSection) || sectionNameFor(segment, sections),
+      }
+    })
+}
+
+/**
+ * Groups entries by section, first-seen order, with the root section first
+ * wherever it appears — a reader meets the site's own top-level pages before its
+ * subsections.
+ *
+ * @param {LlmsEntry[]} entries
+ * @param {string} [rootSection] the display name the root group resolved to
+ * @returns {LlmsGroup[]}
+ */
+export function groupLlmsEntries(entries, rootSection) {
+  /** @type {Map<string, LlmsEntry[]>} */
+  const groups = new Map()
+  for (const entry of entries) {
+    if (!groups.has(entry.section)) groups.set(entry.section, [])
+    groups.get(entry.section)?.push(entry)
+  }
+  const names = [...groups.keys()]
+  if (rootSection && groups.has(rootSection))
+    names.sort((a, b) => (a === rootSection ? -1 : b === rootSection ? 1 : 0))
+  return names.map((name) => ({
+    name,
+    entries: /** @type {LlmsEntry[]} */ (groups.get(name)),
+  }))
+}
+
+// A blockquote line with nothing to quote is `>` and not `> `: a trailing space
+// is invisible in the file and noise in a diff.
+const quote = (text) =>
+  text
+    .split('\n')
+    .map((line) => (line.trim() ? `> ${line}` : '>'))
+    .join('\n')
+
+/**
+ * Renders the file: an H1 title, a blockquote summary, one `##` section per
+ * group and an optional trailing `## Notes` — the llmstxt.org shape.
+ *
+ * @param {Object} input
+ * @param {string} input.title
+ * @param {string} input.summary
+ * @param {LlmsGroup[]} [input.groups]
+ * @param {string} [input.notes]
+ * @returns {string} the file's text, one trailing newline
+ */
+export function renderLlmsTxt({ title, summary, groups = [], notes = '' }) {
+  const blocks = [`# ${oneLine(title)}`, quote(summary)]
+  for (const group of groups) {
+    const lines = group.entries.map((entry) => {
+      const link = `- [${escapeText(entry.title)}](${escapeUrl(entry.url)})`
+      return entry.description ? `${link}: ${entry.description}` : link
+    })
+    // A blank line under every `##`, the same shape `## Notes` has: the file
+    // is read as markdown as often as it is parsed as a list.
+    blocks.push([`## ${group.name}`, lines.join('\n')].join('\n\n'))
+  }
+  if (notes) blocks.push(['## Notes', notes].join('\n\n'))
+  return `${blocks.join('\n\n')}\n`
+}
+
+/**
+ * @typedef {Object} LlmsWriteResult
+ * @property {'no-site-url'|'no-title'|'no-summary'|'skipped'|'written'} status
+ * @property {string|null} text the rendered file, or `null` when nothing was written
+ */
+
+/**
+ * Writes `<build>/llms.txt`. Every reason not to write one is reported rather
+ * than thrown — a missing `siteUrl`, `title` or `summary` is a build the author
+ * still wants, minus this file.
+ *
+ * @param {{ buildTo: string, page: { options: Record<string, any> } }[]} stack
+ * @param {Object} deps
+ * @param {any} deps.config the resolved config — `siteUrl` and `folders.build`
+ * @param {any} deps.logger
+ * @param {Record<string, any>} [deps.options] the `.llms()` options
+ * @param {boolean} [deps.overwrite] default `true`
+ * @returns {Promise<LlmsWriteResult>}
+ */
+export async function writeLlms(
+  stack,
+  { config, logger, options = {}, overwrite = true },
+) {
+  if (!config.siteUrl) {
+    logger.error('Cannot generate llms.txt: config.siteUrl is not set')
+    return { status: 'no-site-url', text: null }
+  }
+  if (!options.title || typeof options.title !== 'string') {
+    logger.error('Cannot generate llms.txt: options.title is not set')
+    return { status: 'no-title', text: null }
+  }
+  if (!options.summary || typeof options.summary !== 'string') {
+    logger.error('Cannot generate llms.txt: options.summary is not set')
+    return { status: 'no-summary', text: null }
+  }
+  const buildDir = config.folders.build
+  const llmsPath = `${buildDir}/llms.txt`
+  if (!overwrite && fs.existsSync(llmsPath)) {
+    logger.info('Skipping llms.txt: already exists')
+    return { status: 'skipped', text: null }
+  }
+  const sections = options.sections || {}
+  const entries = buildLlmsEntries(stack, {
+    siteUrl: config.siteUrl,
+    buildDir,
+    sections,
+  })
+  const text = renderLlmsTxt({
+    title: options.title,
+    summary: await resolveText(options.summary),
+    notes: await resolveText(options.notes),
+    groups: groupLlmsEntries(entries, sectionNameFor('', sections)),
+  })
+  await fs.outputFile(llmsPath, text)
+  logger.success(llmsPath)
+  return { status: 'written', text }
+}

package/llms.txt

@@ -11,8 +11,9 @@ Install: `npm install kiss-ssg --save-dev`. `import Kiss from 'kiss-ssg'` (CJS `
 - `.scan()` — auto-discovers every `.hbs` under `config.folders.pages` you have not already registered (by `view`, so a `.page()` earlier in the same chain wins and the view is not built twice), and calls `.page()` on each with default options. The simplest way to build a whole site: `kiss.scan().generate()`. Under `.watch()` the scan is repeated on every whole-site rebuild, so page files you add or delete while the dev server runs are picked up.
 - `.generate(callback)` — waits for every queued page's model to resolve, then renders and writes each page exactly once (in a normal build HTML is minified via `html-minifier-terser`, comments included; under `dev: true` minification is skipped altogether, so dev output keeps its comments and whitespace and a dev build never loads the minifier). `callback(data)` fires after every page has been attempted — including any that failed to render or write; page failures don't surface here, they surface via `complete()`. `data` is `[{ id, data }]`, one entry per queued promise **in registration order** — the automatic construction-time asset copy is queued first, so `data[0]` is that copy's result (`{ id, data: 'Copied assets: …' }`), not your first page. Use `getModelByID(id, data)` (below) rather than indexing by position. An error thrown by the callback itself (or a rejection from a promise it returns) is a build failure of its own, recorded as `<generate callback>` and reported by `complete()`. Chainable — returns the `Kiss` instance. To await the whole build use `await kiss.complete()`.
 - `.complete(callback)` — resolves after every queued page and any `sitemap()` call has finished writing; resolves with the same `data` array `generate` receives. "Every queued page" includes pages queued from a `generate` callback, whether the callback queues them synchronously or after an `await` (the promise an `async` callback returns is part of what `complete()` waits for), and it includes any page queued after the last `generate()` call: `complete()` renders whatever no `generate()` pass reached, so a page whose model resolved late — or one a callback's `scan()` discovered — is never silently dropped from a build that reports success. It renders nothing if you never called `generate()` at all. Work a _synchronous_ callback defers to a later tick (a `setTimeout`-ed `.page()`) is still outside the build — queue pages synchronously, or from an `async` callback. Rejects with an `AggregateError` — `err.failures` = `[{ view, buildTo, error }]`, message `"N page(s) failed to build: <buildTo paths>"` (build paths, not views, since `.pages()` fan-out gives failed entries the same view; entries with no output path, such as a failing controller or callback, are named by `view` instead) — if any page failed to render or write, any controller failed, or a `generate`/`sitemap` callback threw; other pages still build, and the `generate` callback still fires. In `dev: true` a dev server that cannot bind `config.port` is a build failure too, reported as `<dev server>`. It rejects **once per build**: a second `complete()` in the same build resolves instead of rejecting again, so the pattern of calling `complete()` from inside a `generate` callback cannot leave a second, unhandled rejection behind. A failed build never runs `complete()`'s own callback. A model failure is not a build failure: it is logged and skipped, and shows up in the resolved data as `{ id, data: null, error }`. A `.hbs` view whose file cannot be read (missing or misspelled) **is** a build failure: that page fails and `complete()` rejects, rather than the filename being written into the output.
-- `.report()` — the last settled build as data, or `null` before the first `.complete()` has settled (a watch rebuild replaces it with its own). `{ ok, mode, buildDir, duration, pages, failures, assets, sitemap }`: `ok` is "nothing failed"; `mode` is `'build'`, or `'check'` when the build was staged and thrown away (see `## Checking a build`); `buildDir` is the folder you asked for, never the staging sibling a `'atomic'` build writes to; `duration` is ms from `new Kiss()`; `pages` is `{ view, buildTo, ok }` per queued page, in registration order (an inline template's `view` is elided to its first line); `failures` is `{ view, buildTo, message }` — the same list `err.failures` carries, with the `Error` reduced to its message so the whole thing survives `JSON.stringify`; `assets` is `{ source, target }` per emitted file (the path a template asks for, and the file that is actually there under `config.assets`); `sitemap` is the `sitemap.xml` this build wrote, or `null`; `pipeline` is `{ name, ok, duration }` per `config.assets.pipeline` step, in order, and `[]` when there are none. The same object is on the rejection as `err.report`, so a failed build is readable as data without catching and re-deriving anything. It is additive: `complete()` still resolves with the `data` array and still rejects with the `AggregateError`.
+- `.report()` — the last settled build as data, or `null` before the first `.complete()` has settled (a watch rebuild replaces it with its own). `{ ok, mode, buildDir, duration, pages, failures, assets, sitemap, pipeline, llms }`: `ok` is "nothing failed"; `mode` is `'build'`, or `'check'` when the build was staged and thrown away (see `## Checking a build`); `buildDir` is the folder you asked for, never the staging sibling a `'atomic'` build writes to; `duration` is ms from `new Kiss()`; `pages` is `{ view, buildTo, ok }` per queued page, in registration order (an inline template's `view` is elided to its first line); `failures` is `{ view, buildTo, message }` — the same list `err.failures` carries, with the `Error` reduced to its message so the whole thing survives `JSON.stringify`; `assets` is `{ source, target }` per emitted file (the path a template asks for, and the file that is actually there under `config.assets`); `sitemap` is the `sitemap.xml` this build wrote, or `null`; `pipeline` is `{ name, ok, duration }` per `config.assets.pipeline` step, in order, and `[]` when there are none; `llms` is the `llms.txt` this build wrote, or `null`. The same object is on the rejection as `err.report`, so a failed build is readable as data without catching and re-deriving anything. It is additive: `complete()` still resolves with the `data` array and still rejects with the `AggregateError`.
 - `.sitemap(options, callback)` — writes `sitemap.xml` to `config.folders.build`, derived from every registered page. Requires `config.siteUrl` (logs an error and skips, does not throw, if unset). Can be called before or after `.generate()` — both just wait on the same internal promise queue. Per-page opt-out: `ignoreSitemap: true` in that page's `.page()`/`.pages()` options; a `generate: false` page is left out too. Per-page overrides: `sitemapPriority` (default `'1.00'`), `sitemapChangefreq` (omitted from the XML unless set), `sitemapLastmod` (default: one timestamp shared by all pages, captured when `.sitemap()` runs). `options.overwrite` (default `true`) — set `false` to skip (re)writing if `sitemap.xml` already exists; only has an effect if `cleanBuild: false` too, since the default `cleanBuild: true` already empties the whole build dir — including any prior `sitemap.xml` — before `.sitemap()` ever runs.
+- `.llms(options, callback)` — writes `llms.txt` to `config.folders.build`: the [llmstxt.org](https://llmstxt.org) index an answer engine reads first, derived from the same registry the sitemap is. Same lifecycle as `.sitemap()` — chainable, callable before or after `.generate()`, waiting on the same internal queue, and re-run by every whole-site `watch` rebuild. `options.title` (required) is the file's `# ` heading; `options.summary` (required) is the `> ` blockquote, and is either the text itself or a path (relative to `process.cwd()`) to a `.md`/`.txt` file holding it; `options.notes` (optional, same text-or-file rule) becomes a trailing `## Notes` section; `options.sections` maps a top-level path segment to a heading (`{ courses: 'Courses' }`, the key `root` naming the section that holds pages with no path, default `Pages`), and an unmapped segment is title-cased; `options.overwrite` (default `true`) behaves exactly as the sitemap's. A missing `config.siteUrl`, `title` or `summary` logs an error and skips the file — it never throws, and the callback does not fire. Pages are grouped by the first segment of their `path` (root pages first) and listed in registration order as `- [title](url): description`, with the description omitted when the page has none and the title falling back to the page's slug, title-cased. Each URL is the **same string** the page's own `{{canonical}}` and its `<loc>` in `sitemap.xml` are, built by the same code. Per-page: `ignoreLlms: true` keeps a page out; `ignoreSitemap: true` and `generate: false` keep it out automatically; `llmsSection: 'Name'` overrides the group it lands in. `callback(text)` receives the rendered file.
 - `.watch(options)` — starts a `chokidar` watcher on `config.folders.src` (only meaningful with `dev: true`, which also starts a livereload dev server on `config.port`, default `3001`, bound to `config.devHost`, with live reload on `config.livereloadPort`); rebuilds just the affected page(s), or the whole site if a changed file can't be matched to a queued page. Editing a partial or a layout re-registers the partials and re-renders **only the pages that rendered it** — learned at render time, so a partial chosen with `lookup`, reached through another partial, or used as a layout all count — without re-resolving any model (URL models included) or re-running any controller; a partial no page has rendered yet re-renders every page and logs a notice naming it. With `verbose: true` a dev build also writes `dependency-graph.json` (`{ partial: [built pages…] }`) beside `debug.json`, and each page's `.json` sibling lists the `partials` it used. Every other non-page change is a whole-site rebuild. A whole-site rebuild replays every `.page()`/`.pages()`/`.scan()` registration from scratch, so edited models and controllers take effect (controller files are reloaded from disk, ESM and CommonJS alike) — which means every URL model is fetched again on every rebuild unless you set `config.fetch.cache`; a single-page rebuild is a template re-render. A whole-site rebuild also deletes output files the previous build wrote that the new one no longer produces (a removed fan-out model, a changed slug, or a page `.scan()` had discovered whose `.hbs` file you deleted — a page you registered by name instead keeps failing the build until you remove the call) and re-runs `.sitemap()` if you ever called it. Creating a file under `src/` rebuilds the whole site too, so a partial or layout you add mid-session is registered and usable straight away (a file created empty is picked up once it has content — an event on an empty file is ignored, which is also what keeps a slow truncate-then-write save from rebuilding against a half-written file), and a new page `.hbs` is built as well if you used `.scan()` (a rebuild scans the pages folder again; on an explicitly registered site you still add the `.page()` call yourself). Deleting a partial or layout unregisters it, so any page still referencing it fails the rebuild with `The partial <name> could not be found` instead of quietly rendering the deleted content until you restart. `options.entry` (default `process.argv[1]`): the script whose change triggers a full rebuild. The browser is told to reload **once per rebuild, after every page has been written** (and once when the first build finishes), never once per file — so a reload can never land on a page the rebuild has not re-rendered yet. An edited stylesheet reloads that stylesheet alone, leaving the page's state alone.
 - `.close()` — stops the file watcher and dev server (dev mode / after `.watch()`); returns a Promise that resolves once any in-flight rebuild has finished, so nothing is written after it.
 - `.copyAssets(sourceDir, targetDir)` — compiles every `*.scss`/`*.sass` under `sourceDir` to a sibling `.css` and copies everything else straight through to `targetDir`. Runs automatically once at construction time for `config.folders.assets` → `config.folders.build`; callable again for extra asset directories. Calls run one after another in registration order, not concurrently. Every emitted file is recorded in the instance's asset manifest — that is what `{{asset}}` reads, and what `config.assets` renames (see `## Config`).
@@ -114,6 +115,42 @@ Registered on `kiss.handlebars` for every instance; register your own on the sam
 - `asset` — the path of a file `.copyAssets()` put in the build, under whatever cache-busting policy `config.assets` sets: `{{asset "css/site.css"}}` renders `css/site.css` with no policy, `css/site.a1b2c3d4.css` under `assets: { hash: true }`, and `css/site.css?v=1.4.5` under `assets: { version: '1.4.5' }`. The template says which file it wants; the config says how it is cached, so changing the policy never touches a template. Ask for the path the file has when nothing is renaming it — a `.scss` source by its compiled `.css` name (`css/site.css`, not `css/site.scss`) — with or without a leading slash. It renders **no leading slash**, so the template picks the base: `href="/{{asset "css/site.css"}}"` for a root-relative link, `href="{{root}}{{asset "css/site.css"}}"` for one that also works opened off the file system, and `{{absUrl (asset "css/site.css")}}` for an absolute URL (the query string and the hashed extension both survive). A URL that already has a scheme is passed through untouched. A path that is not in the build renders as you wrote it and logs one warning per page naming it, rather than failing the page; a non-string path logs a warning and renders nothing.
 - `env` — block helper gated on `config.dev`: `{{#env is="dev"}}dev-only{{else}}prod-only{{/env}}`. Hash key: `is` (required string, case-insensitive substring match — `"dev"`/`"prod"`). A missing or non-string `is` logs an error and renders neither branch.
 
+## Writing llms.txt
+
+`llms.txt` is the curated, AI-facing index of a site — what an answer engine reads before it crawls. `.llms()` builds one from the pages already registered, so it cannot list a URL the site does not serve or a title the page does not carry. End to end:
+
+```js
+kiss
+  .page({ view: 'index.hbs', title: 'A1K9 Training', description: 'Dog training and behaviour work in South Wales' })
+  .pages({ view: 'courses/course.hbs', model: 'courses', path: 'courses' })
+  .page({ view: 'rota.hbs', ignoreLlms: true }) // in the sitemap, out of the index
+  .generate()
+  .sitemap()
+  .llms({
+    title: 'A1K9 Training',
+    // Inline text, or a path to a file: `summary: 'src/content/summary.md'`
+    summary: 'Dog behaviour and obedience training in South Wales, run by Gaynor Probert.',
+    sections: { root: 'Pages', courses: 'Courses' },
+    notes: 'src/content/llms-notes.md',
+  })
+```
+
+writes:
+
+```markdown
+# A1K9 Training
+
+> Dog behaviour and obedience training in South Wales, run by Gaynor Probert.
+
+## Pages
+
+- [A1K9 Training](https://a1k9training.co.uk/): Dog training and behaviour work in South Wales
+
+## Courses
+
+- [Bronze obedience](https://a1k9training.co.uk/courses/bronze-obedience): Six weeks, group class
+```
+
 ## Checking a build
 
 `npx kiss-ssg check <script> [args…]` runs a site's own build script as a dry run: the build is staged and then discarded, so the build folder is neither emptied nor written, and what you get back is the verdict instead of the output. Arguments after the script are passed through to it, so a site that takes a season or a cohort is checked the way it is run. It prints a JSON array with one report per `Kiss` instance the script created — a script that builds several outputs gets several reports:
@@ -135,7 +172,8 @@ Registered on `kiss.handlebars` for every instance; register your own on the sam
     ],
     "assets": [{ "source": "css/site.css", "target": "css/site.605b52d7.css" }],
     "sitemap": "./public/sitemap.xml",
-    "pipeline": [{ "name": "tailwind", "ok": true, "duration": 420 }]
+    "pipeline": [{ "name": "tailwind", "ok": true, "duration": 420 }],
+    "llms": "./public/llms.txt"
   }
 ]
 ```
@@ -151,10 +189,10 @@ Two things a check cannot make true. A site that **reads its own build folder ba
 ## Docs
 
 - [README.md](README.md): full usage docs, worked examples for `.page()`/`.pages()`/`.sitemap()`, the helpers list.
-- [examples/](examples/): ships in the package, so an agent working in a consuming project can read `node_modules/kiss-ssg/examples/README.md` and run a copy from there. Two tiers. Examples 1–6 are the feature reference, one idea each — scan, page/model/controller, `.pages()` fan-out, layouts and partials, helpers, sitemap. Examples 7–9 are exemplars, whole sites to copy by shape rather than a single feature: 7 is versioned outputs, one build per season; 8 is a site built from a folder of records with one broken one, fed and validated in the controller; 9 is every v1 → v2 migration recipe as running code, in a site that builds clean. Every example builds and exits by default (`node examples/<N>-name.js`, or `npm run eg<N>`); pass `--dev` to run examples 1–6, 8 and 9 as a live dev server instead (7 takes a season slug in place of `--dev`). Example 8 is the only one that exits non-zero, and it does so on purpose.
-- [types/](types/): TypeScript declarations, generated from the JSDoc in `lib/` and shipped in the package (`package.json`'s `types`, and an `exports` map whose `.` entry resolves `types` → `./types/kiss.d.ts` and both `import` and `require` → `./lib/kiss.js`). A plain-JavaScript site gets full completion and checking by putting `// @ts-check` at the top of its build script — no TypeScript, no `@types/` package. Every option type is reachable from the one entry: `/** @type {import('kiss-ssg').KissConfigInput} */` on the config object, `import('kiss-ssg').PageOptions` / `PagesOptions` on page options, `import('kiss-ssg').KissController` on a controller, and `import('kiss-ssg').BuildError` to cast the error `complete()` rejects with before reading `err.failures`. Also exported: `KissConfig` (the resolved config a view sees), `KissFolders`, `PageOptionsPatch` (what a controller returns), `BuildData`, `BuildFailure`, `BuildReport` (what `report()` returns) with `BuildPage`, `BuildAsset` and `BuildReportFailure`, `SitemapOptions`, `SitemapUrl`, `WatchOptions`. Arbitrary keys are allowed on the config and on page options — they reach the template — so only the documented keys are checked; `folders` is closed, so a misspelled folder name is an error.
-- [plugins/kiss-ssg/](plugins/kiss-ssg/): a Claude Code plugin, installed with `/plugin marketplace add cprobert/kiss-ssg` then `/plugin install kiss-ssg@kiss-ssg`. Three skills — `new-site`, `migrate-v1`, `check` — which sequence this file and the examples rather than restating them. The plugin does not ship in the npm tarball, only in the repository; a project's CLAUDE.md can import this file directly with `@node_modules/kiss-ssg/llms.txt`.
-- [lib/](lib/): the engine — `kiss.js` (orchestrator, public API), `kiss-page.js` (one page's render), and one module per concern (`config`, `logger`, `handlebars-helpers`, `partials`, `dependency-graph`, `assets`, `asset-manifest`, `sass`, `model-resolver`, `fetch-policy`, `controller-resolver`, `sitemap`, `dev-server`, `watcher`, `utils`, `build-report`, `check`, `pipeline`). Per-module notes: [AIKB/](AIKB/).
+- [examples/](examples/): ships in the package, so an agent working in a consuming project can read `node_modules/kiss-ssg/examples/README.md` and run a copy from there. Two tiers. Examples 1–6 are the feature reference, one idea each — scan, page/model/controller, `.pages()` fan-out, layouts and partials, helpers, sitemap and llms.txt. Examples 7–9 are exemplars, whole sites to copy by shape rather than a single feature: 7 is versioned outputs, one build per season; 8 is a site built from a folder of records with one broken one, fed and validated in the controller; 9 is every v1 → v2 migration recipe as running code, in a site that builds clean. Every example builds and exits by default (`node examples/<N>-name.js`, or `npm run eg<N>`); pass `--dev` to run examples 1–6, 8 and 9 as a live dev server instead (7 takes a season slug in place of `--dev`). Example 8 is the only one that exits non-zero, and it does so on purpose.
+- [types/](types/): TypeScript declarations, generated from the JSDoc in `lib/` and shipped in the package (`package.json`'s `types`, and an `exports` map whose `.` entry resolves `types` → `./types/kiss.d.ts` and both `import` and `require` → `./lib/kiss.js`). A plain-JavaScript site gets full completion and checking by putting `// @ts-check` at the top of its build script — no TypeScript, no `@types/` package. Every option type is reachable from the one entry: `/** @type {import('kiss-ssg').KissConfigInput} */` on the config object, `import('kiss-ssg').PageOptions` / `PagesOptions` on page options, `import('kiss-ssg').KissController` on a controller, and `import('kiss-ssg').BuildError` to cast the error `complete()` rejects with before reading `err.failures`. Also exported: `KissConfig` (the resolved config a view sees), `KissFolders`, `PageOptionsPatch` (what a controller returns), `BuildData`, `BuildFailure`, `BuildReport` (what `report()` returns) with `BuildPage`, `BuildAsset` and `BuildReportFailure`, `SitemapOptions`, `SitemapUrl`, `LlmsOptions`, `WatchOptions`. Arbitrary keys are allowed on the config and on page options — they reach the template — so only the documented keys are checked; `folders` is closed, so a misspelled folder name is an error.
+- [plugins/kiss-ssg/](plugins/kiss-ssg/): a Claude Code plugin, installed with `/plugin marketplace add cprobert/kiss-ssg` then `/plugin install kiss-ssg@kiss-ssg`. Four skills, each named `kiss-<something>` for easy discovery — `kiss-new-site`, `kiss-add-page`, `kiss-migrate-v1`, `kiss-check` — which sequence this file and the examples rather than restating them, and whose descriptions are written so Claude reaches for them on its own without being invoked by name. The plugin does not ship in the npm tarball, only in the repository; a project's CLAUDE.md can import this file directly with `@node_modules/kiss-ssg/llms.txt`.
+- [lib/](lib/): the engine — `kiss.js` (orchestrator, public API), `kiss-page.js` (one page's render), and one module per concern (`config`, `logger`, `handlebars-helpers`, `partials`, `dependency-graph`, `assets`, `asset-manifest`, `sass`, `model-resolver`, `fetch-policy`, `controller-resolver`, `sitemap`, `dev-server`, `watcher`, `utils`, `build-report`, `check`, `pipeline`, `llms`). Per-module notes: [AIKB/](AIKB/).
 
 ## Migrating from v1
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiss-ssg",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Simple Static Website Generator",
   "main": "lib/kiss.js",
   "types": "./types/kiss.d.ts",

package/types/build-report.d.ts

@@ -12,9 +12,10 @@
  * @param {number} [input.startedAt] `Date.now()` at construction
  * @param {string|null} [input.sitemap] the sitemap written by this build
  * @param {import('./pipeline.js').PipelineResult[]} [input.pipeline] what the asset pipeline's steps did
+ * @param {string|null} [input.llms] the llms.txt written by this build
  * @returns {BuildReport}
  */
-export function buildReport({ stack, failures, manifest, buildDir, stagingDir, mode, startedAt, sitemap, pipeline, }: {
+export function buildReport({ stack, failures, manifest, buildDir, stagingDir, mode, startedAt, sitemap, pipeline, llms, }: {
     stack?: {
         view: string;
         buildTo: string | null;
@@ -29,6 +30,7 @@ export function buildReport({ stack, failures, manifest, buildDir, stagingDir, m
     startedAt?: number;
     sitemap?: string | null;
     pipeline?: import("./pipeline.js").PipelineResult[];
+    llms?: string | null;
 }): BuildReport;
 /**
  * The one-line human rendering of a report, plus one line per failure — what
@@ -134,4 +136,8 @@ export type BuildReport = {
      * every `config.assets.pipeline` step, in order; empty when there are none
      */
     pipeline: BuildPipelineStep[];
+    /**
+     * the `llms.txt` written, or `null` if none was
+     */
+    llms: string | null;
 };

package/types/kiss.d.ts

@@ -67,6 +67,14 @@ export type PageOptionsKnown = {
      * default: one timestamp shared by every page
      */
     sitemapLastmod?: string;
+    /**
+     * keep this page out of `llms.txt`
+     */
+    ignoreLlms?: boolean;
+    /**
+     * the `llms.txt` section this page is listed under, overriding its path
+     */
+    llmsSection?: string;
 };
 /**
  * The options `.page()` takes: {@link PageOptionsKnown} plus any extra keys of
@@ -147,6 +155,33 @@ export type SitemapOptions = {
      */
     overwrite?: boolean;
 };
+/**
+ * The options `.llms()` takes. `title` and `summary` are required — without
+ * either, kiss logs an error and writes nothing, exactly as it does for a
+ * sitemap with no `siteUrl`.
+ */
+export type LlmsOptions = {
+    /**
+     * the site's name — the file's `# ` heading
+     */
+    title: string;
+    /**
+     * what the site is, as a `> ` blockquote: the text itself, or a path (relative to `process.cwd()`) to a `.md`/`.txt` file holding it
+     */
+    summary: string;
+    /**
+     * a trailing `## Notes` section; same text-or-file rule as `summary`
+     */
+    notes?: string;
+    /**
+     * top-level path segment → section heading (`{ courses: 'Courses' }`); the key `root` names the section holding pages with no path (default `Pages`). An unmapped segment is title-cased.
+     */
+    sections?: Record<string, string>;
+    /**
+     * default `true`; `false` leaves an existing `llms.txt` alone
+     */
+    overwrite?: boolean;
+};
 export type WatchOptions = {
     /**
      * the script whose own change triggers a whole-site rebuild; defaults to `process.argv[1]`
@@ -216,6 +251,8 @@ declare class Kiss {
     /** @private */
     private _sitemapRequest;
     /** @private */
+    private _llmsRequest;
+    /** @private */
     private _watcher;
     /** @private */
     private _devServer;
@@ -240,6 +277,8 @@ declare class Kiss {
     /** @private */
     private _sitemapPath;
     /** @private */
+    private _llmsPath;
+    /** @private */
     private _checkMode;
     /** @type {KissConfig} */
     config: KissConfig;
@@ -377,6 +416,20 @@ declare class Kiss {
      * @returns {this}
      */
     sitemap(options?: SitemapOptions | null, callback?: (urls: SitemapUrl[]) => void | Promise<void>): this;
+    /**
+     * Writes `llms.txt` into the build folder — the llmstxt.org index an answer
+     * engine reads first — from the same registry, titles and URLs the sitemap is
+     * built from, so the two can never disagree. Requires `config.siteUrl`, and
+     * `options.title`/`options.summary`; without any of them this logs an error
+     * and skips. Like `.sitemap()`, it can be called before or after
+     * `.generate()`, and it is re-run by a whole-site watch rebuild.
+     *
+     * @param {LlmsOptions} options
+     * @param {(text: string) => void|Promise<void>} [callback] receives the
+     * rendered file; not fired when llms.txt was skipped for want of an option
+     * @returns {this}
+     */
+    llms(options: LlmsOptions, callback?: (text: string) => void | Promise<void>): this;
     /**
      * Pulls one resolved model out of the array `.generate()`/`.complete()` hand
      * back — the way to read a model without relying on its position.

package/types/llms.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Resolves a `summary`/`notes` option: the contents of the file it names, or the
+ * string itself. A `.md` file is used as it is — `llms.txt` is markdown.
+ *
+ * @param {unknown} value
+ * @returns {Promise<string>} the resolved text, trailing whitespace trimmed
+ */
+export function resolveText(value: unknown): Promise<string>;
+/**
+ * The display name for one top-level path segment: an explicit mapping, else the
+ * segment title-cased. The root group (a page with no `path`) is keyed `root`.
+ *
+ * @param {string} segment the sanitised first segment of a page's `path`, `''` for a root page
+ * @param {Record<string, string>} [sections]
+ * @returns {string}
+ */
+export function sectionNameFor(segment: string, sections?: Record<string, string>): string;
+/**
+ * One entry per page that belongs in `llms.txt`, in registration order. A page
+ * is left out by `ignoreLlms`, by `ignoreSitemap` (the AI index is a curated
+ * subset of the same site the sitemap describes, never a superset), or by
+ * `generate: false` (there is nothing at that URL).
+ *
+ * @param {{ buildTo: string, page: { options: Record<string, any> } }[]} stack
+ * @param {Object} context
+ * @param {string} context.siteUrl
+ * @param {string} context.buildDir
+ * @param {Record<string, string>} [context.sections] top-level path segment → display name
+ * @returns {LlmsEntry[]}
+ */
+export function buildLlmsEntries(stack: {
+    buildTo: string;
+    page: {
+        options: Record<string, any>;
+    };
+}[], { siteUrl, buildDir, sections }: {
+    siteUrl: string;
+    buildDir: string;
+    sections?: Record<string, string>;
+}): LlmsEntry[];
+/**
+ * Groups entries by section, first-seen order, with the root section first
+ * wherever it appears — a reader meets the site's own top-level pages before its
+ * subsections.
+ *
+ * @param {LlmsEntry[]} entries
+ * @param {string} [rootSection] the display name the root group resolved to
+ * @returns {LlmsGroup[]}
+ */
+export function groupLlmsEntries(entries: LlmsEntry[], rootSection?: string): LlmsGroup[];
+/**
+ * Renders the file: an H1 title, a blockquote summary, one `##` section per
+ * group and an optional trailing `## Notes` — the llmstxt.org shape.
+ *
+ * @param {Object} input
+ * @param {string} input.title
+ * @param {string} input.summary
+ * @param {LlmsGroup[]} [input.groups]
+ * @param {string} [input.notes]
+ * @returns {string} the file's text, one trailing newline
+ */
+export function renderLlmsTxt({ title, summary, groups, notes }: {
+    title: string;
+    summary: string;
+    groups?: LlmsGroup[];
+    notes?: string;
+}): string;
+/**
+ * @typedef {Object} LlmsWriteResult
+ * @property {'no-site-url'|'no-title'|'no-summary'|'skipped'|'written'} status
+ * @property {string|null} text the rendered file, or `null` when nothing was written
+ */
+/**
+ * Writes `<build>/llms.txt`. Every reason not to write one is reported rather
+ * than thrown — a missing `siteUrl`, `title` or `summary` is a build the author
+ * still wants, minus this file.
+ *
+ * @param {{ buildTo: string, page: { options: Record<string, any> } }[]} stack
+ * @param {Object} deps
+ * @param {any} deps.config the resolved config — `siteUrl` and `folders.build`
+ * @param {any} deps.logger
+ * @param {Record<string, any>} [deps.options] the `.llms()` options
+ * @param {boolean} [deps.overwrite] default `true`
+ * @returns {Promise<LlmsWriteResult>}
+ */
+export function writeLlms(stack: {
+    buildTo: string;
+    page: {
+        options: Record<string, any>;
+    };
+}[], { config, logger, options, overwrite }: {
+    config: any;
+    logger: any;
+    options?: Record<string, any>;
+    overwrite?: boolean;
+}): Promise<LlmsWriteResult>;
+export type LlmsWriteResult = {
+    status: "no-site-url" | "no-title" | "no-summary" | "skipped" | "written";
+    /**
+     * the rendered file, or `null` when nothing was written
+     */
+    text: string | null;
+};
+/**
+ * One page as `llms.txt` lists it.
+ */
+export type LlmsEntry = {
+    /**
+     * the page's `title`, or its slug title-cased
+     */
+    title: string;
+    /**
+     * the same absolute URL the sitemap and `{{canonical}}` emit
+     */
+    url: string;
+    /**
+     * the page's `description`, or `''` when it has none
+     */
+    description: string;
+    /**
+     * the display name of the group it belongs to
+     */
+    section: string;
+};
+/**
+ * One `##` section of the file: a display name and the pages under it.
+ */
+export type LlmsGroup = {
+    name: string;
+    entries: LlmsEntry[];
+};