@zvndev/darkmown 2.3.1-next.5.g6f7d03c → 2.3.1-next.6.gef54aba

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.3.1-next.6.gef54aba",
   "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));
   }