@zvndev/darkmown 2.3.1-next.5.g6f7d03c → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to Darkmown are documented here. Versions follow [semver](https://semver.org); pre-1.0 minor versions may contain breaking changes.
 
+## 2.4.0 (2026-08-09)
+
+A discoverability release, in both senses. Search engines can now index the site correctly, and coding agents working in a Darkmown project finally get the directive reference where they will actually read it. No runtime change (7654 B gzipped, unchanged) and no breaking changes.
+
+- **`darkmown init` now writes agent context into the project.** Darkmown has always shipped a complete build-with-Darkmown guide, but only at the *package* root, so an installed copy landed in `node_modules/@zvndev/darkmown/AGENTS.md` where no coding agent reads it. Every scaffolded project therefore began each session with the agent guessing at directive syntax. `init` now writes `AGENTS.md` at the project root (copied byte-for-byte from the package, so a scaffolded project and the framework can never teach different syntax), a short `CLAUDE.md` pointing at it, and a `.gitignore` covering `node_modules/` and `dist/`. All three respect the existing never-overwrite rule. This matters because Darkmown's directive vocabulary is small and closed: an agent that has it in context writes valid `.wd` on the first attempt, and an agent that does not reaches for JSX and JavaScript idioms the compiler rejects.
+- **Canonical URLs and `og:url`.** Neither existed. Every page with a `site_url` now emits `<link rel="canonical">` and `og:url`, both derived from the same route string the sitemap is built from, so the three can never disagree. A paginated page canonicalizes to itself, never to page one. No `site_url` means no canonical tag, never an invented origin. Two related bugs fell out: `og:title` was gated on `description || image`, so a titled page with neither shared as a bare URL, and `og:type` was hardcoded to `website`, so every blog post claimed to be one.
+- **Opt-in JSON-LD structured data.** A new `schema:` frontmatter key emits `Article`, `BlogPosting`, `TechArticle`, `WebSite`, or `Organization`, plus an automatic `BreadcrumbList` built only from routes that actually exist. Driven by frontmatter rather than a directive, so a page with `html: false` can describe itself without a line of raw HTML. There is deliberately **no code path** to `aggregateRating`, `review`, or `offers`: fabricated ratings are a manual-action risk and the framework cannot know them. A key you did not write produces no property at all, never a blank one and never a guess. Verified to emit no CSP violation under `script-src 'self'` with no `unsafe-inline`.
+- **`llms-full.txt`.** `llms.txt` becomes a true index (cheatsheet, one line per page, a pointer onward) and `llms-full.txt` carries the corpus: the full directive reference, every error code with its cause and fix, and the complete source of every page. Both come from one generator, so neither can drift from the compiler.
+- **Explicit AI-crawler rules in `robots.txt`.** Fifteen user-agent tokens across OpenAI, Anthropic, Google, Apple, Perplexity and others, each verified against the operator's own published documentation, with the docs URL and a purpose comment written into the generated file. The distinctions are recorded rather than flattened: `OAI-SearchBot` governs ChatGPT Search crawling and citations while `GPTBot` governs training access, and `Google-Extended` is a control token that never affects Search ranking. A new `ai_crawlers: deny` config flips them all, and a typo fails the build (`WD907`) instead of failing open.
+- **BUGFIX: `darkmown deploy vercel` no longer makes every internal link redirect.** The generated Vercel config set `trailingSlash: false` while Darkmown's route model is trailing-slashed end to end (`routeFromFile`, `routes.json`, `_headers`, the sitemap, the dev server, and the `dist/docs/index.html` layout the build writes). The result was a `308` on every single internal navigation. Now `true`, so the deployed config agrees with the routes the framework actually emits. Note that this also applies to extensionless `/api/*` paths: point `:fetch` and `:form action=` at the slashed form to avoid a redirect hop. The redirect is a `308`, so a form POST still arrives intact either way, and this is documented in the backends section.
+
 ## 2.3.0 — 2026-08-09
 
 A trust release. Every compile error now carries a stable, searchable code; the dependency tree carries zero known advisories; and CI proves the framework on three operating systems and three browser engines instead of one of each. The new coverage found real bugs, including one that had silently broken every Windows user since the project started. No runtime change (7654 B gzipped, unchanged) and no breaking changes.

package/README.md

@@ -58,7 +58,7 @@ npm run dev     # live demo site — the same site that runs darkmown.com
 
 ## Commands
 
-- `darkmown init [dir] [--template <name>]` scaffolds a new site from a template (`starter`, `blog`, `store`, `dashboard`, `landing`).
+- `darkmown init [dir] [--template <name>]` scaffolds a new site from a template (`starter`, `blog`, `store`, `dashboard`, `landing`). It also drops `AGENTS.md` (the full directive reference), a `CLAUDE.md` pointing at it, and a `.gitignore` into the project root, so a coding agent working in your new project has the directive vocabulary in context from the first prompt.
 - `darkmown dev` starts the live compiler with browser reload, an in-browser error overlay, and a local runner for `api/*` functions. Rebuilds are incremental: each dev build records a per-route dependency map (page file, includes, colocated assets, loop data, collections), so editing one file recompiles only the routes that depend on it — with a full rebuild on any uncertainty (a new/deleted/renamed file, or a framework `src/` change). Rebuilds run one at a time; edits landing mid-build batch into the next one.
 - `darkmown build [--target cloudflare] [--drafts]` writes static output to `dist` (plus `sitemap.xml`/`rss.xml`/`robots.txt`); `--drafts` includes `draft: true` pages for staging.
 - `darkmown deploy <vercel|cloudflare> [--prod]` builds and deploys via the platform CLI.

package/docs/cli.md

@@ -34,6 +34,8 @@ Scaffolds a Darkmown site from a template (default: `starter`). Available templa
 darkmown init my-site --template store
 ```
 
+Every scaffold also writes agent context at the project root: `AGENTS.md` (the full directive reference, copied byte-for-byte from the installed package so it can never teach different syntax than the compiler accepts), a short `CLAUDE.md` pointing at it, and a `.gitignore` covering `node_modules/` and `dist/`. Coding agents read instruction files from the project root, so without this a new project starts every session with the agent guessing at directive syntax.
+
 Existing files are never overwritten. The generated `package.json` is private, sets `"type": "module"` (so `api/*.js` import as ESM), includes `dev`/`build`/`preview` scripts, and names the app after the target directory.
 
 After scaffolding:

package/docs/spec-alignment.md

@@ -21,6 +21,8 @@ The 1.3.0 cycle shipped the crawler *files* (sitemap, rss, robots). This closes
 - **Zero known advisories, and one fewer runtime dependency.** `image-size` carried a high-severity advisory affecting every published version with no upgrade path, so its single build-time call site is now served by an inlined header reader (PNG/JPEG/GIF/WebP/SVG) with explicitly bounded parse loops. This keeps the project's "few runtime dependencies" posture honest rather than deferring to an unfixable upstream.
 - **BUGFIX — CRLF sources lost their frontmatter.** `parseFrontmatter` tested an LF-shaped `---\n` opener, so any file authored on Windows or checked out with `core.autocrlf` had its whole frontmatter block silently reclassified as body text: no error, but the page lost its title, layout, `draft` flag, and collection schema fields. Newline normalization now happens at the reader boundary and in `parseFrontmatter`. This had been latent since the first commit; it surfaced within minutes of adding a Windows CI job.
 - **Platform coverage is now part of the contract.** CI runs the suite on Linux, Windows, and macOS, and the browser e2e suite against Chromium, Firefox, and WebKit (sharded, so three engines cost roughly one engine's wall-clock). The reactive runtime had only ever been proven in one engine; the CLI's path handling had never executed on Windows at all.
+- **A scaffolded project now carries its own agent context.** The package has always shipped a full build-with-Darkmown guide, but only at the package root, so a consumer's copy landed in `node_modules/@zvndev/darkmown/AGENTS.md` where no coding agent reads it. `darkmown init` now copies that same file to the project root (byte-identical, so a scaffolded project and this repo can never teach different syntax), plus a short `CLAUDE.md` pointing at it and a `.gitignore`. This matters because the directive vocabulary is small and closed: an agent that has it in context writes valid `.wd` on the first try, and an agent that does not reaches for JSX and JavaScript idioms the compiler rejects. A pack test keeps `AGENTS.md` in the tarball, since dropping it would make `init` silently scaffold a project with no agent context and no error.
+
 - **Types resolve for modern TypeScript consumers.** The `exports` map lacked `types` conditions, so `moduleResolution: node16`/`nodenext`/`bundler` consumers got no types from either entrypoint. Fixed, `types/catalog.d.ts` authored, and the declaration build itself repaired (it had been failing silently under TypeScript 6, leaving the committed `.d.ts` stale).
 - **Property tests extended to the skin compiler and the router,** in the existing seeded/reproducible style. They found a real defect on the first run: `.skin` token modifiers quoted the attribute value but never validated the attribute *name*, letting `tokens [{=v]` emit an unbalanced `:root[{="v"]` selector that a CSS parser would use to swallow every following rule.
 - **Release channels:** merges to `master` publish a prerelease to the `next` dist-tag; the tag-triggered stable path is unchanged and the canary job verifies after publishing that it did not take `latest`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zvndev/darkmown",
-  "version": "2.3.1-next.5.g6f7d03c",
+  "version": "2.4.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/site/pages/docs/index.wd

@@ -694,7 +694,7 @@ A shipped code is a public contract: never renumbered, never reused. The full re
 
 The `darkmown` command (installed by `npx @zvndev/darkmown`) is the whole tool — every command is one word:
 
-- `darkmown init [dir] [--template <name>]` — scaffold a new site from a template (`starter`, `blog`, `store`, `dashboard`, `landing`). Existing files are never overwritten.
+- `darkmown init [dir] [--template <name>]` scaffolds a new site from a template (`starter`, `blog`, `store`, `dashboard`, `landing`). It also writes agent context at the project root: `AGENTS.md` (the full directive reference, copied from the installed package so it can never teach syntax the compiler rejects), a `CLAUDE.md` pointing at it, and a `.gitignore`. Existing files are never overwritten.
 - `darkmown dev` — the live compiler: browser reload, an in-browser error overlay, incremental rebuilds, and a local runner for `api/*` functions.
 - `darkmown build [--target cloudflare] [--drafts]` — write 100% static output to `dist/` (plus `sitemap.xml` / `rss.xml` / `robots.txt`); `--drafts` includes `draft: true` pages for a staging deploy.
 - `darkmown serve` — preview the built `dist/` locally (static only; use `dev` to exercise `api/*`).

package/src/scaffold.js

@@ -27,7 +27,9 @@ export function availableTemplates() {
  * Scaffold a new Darkmown project into `root` from a template, creating files
  * that don't already exist (never overwriting). `package.json` is generated (so
  * the name tracks the directory and the `@zvndev/darkmown` dep pins the installed
- * version); every other file is copied verbatim from the chosen template.
+ * version); `AGENTS.md` is copied from the package so coding agents find the
+ * directive reference at the project root; `CLAUDE.md` and `.gitignore` are
+ * generated; every other file is copied verbatim from the chosen template.
  * @param {string} root Absolute path to the target project directory.
  * @param {{ template?: string }} [options] `template` defaults to `"starter"`.
  * @returns {{ root: string, template: string }}
@@ -71,6 +73,37 @@ export function initProject(root, options = {}) {
     )}\n`
   );
 
+  // Agent context. The package already carries a full build-with-Darkmown
+  // guide, but at the PACKAGE root — so a consumer's copy lands in
+  // node_modules/@zvndev/darkmown/AGENTS.md, where no coding agent looks. Agents
+  // read instruction files from the PROJECT root, so the guide is copied there
+  // and the scaffolded project starts with the directive vocabulary in context
+  // instead of the agent guessing at it.
+  //
+  // Copied rather than generated: it is one maintained file, so a scaffolded
+  // project and this repo can never teach different syntax.
+  copyNew(path.join(moduleDir, "..", "AGENTS.md"), path.join(root, "AGENTS.md"));
+
+  // Claude Code reads CLAUDE.md; most other agents read AGENTS.md. A pointer,
+  // not a second copy, so there is exactly one file to keep true.
+  writeNew(
+    root,
+    "CLAUDE.md",
+    "# Project instructions\n\n" +
+      "This project is built with [Darkmown](https://darkmown.com). " +
+      "The directive reference, project layout, and build rules are in " +
+      "[AGENTS.md](./AGENTS.md). Read it before writing or editing any " +
+      "`.md`/`.wd` file.\n\n" +
+      "Refresh the directive reference at any time with " +
+      "`npx darkmown catalog --llms` (cheatsheet) or " +
+      "`npx darkmown catalog --llms-full` (full reference). Both are generated " +
+      "from the compiler's own tables, so they cannot drift from what compiles.\n"
+  );
+
+  // Without this a first `git init` stages the build output and the whole
+  // dependency tree, which is the first thing anyone does after `init`.
+  writeNew(root, ".gitignore", "node_modules/\ndist/\n.DS_Store\n");
+
   for (const rel of walk(templateDir)) {
     copyNew(path.join(templateDir, rel), path.join(root, rel));
   }