@zvndev/darkmown 1.5.0 → 2.0.1

package/site/pages/blog/unfinished-thoughts.skin

@@ -0,0 +1,127 @@
+/* Colocated post styling — a .skin next to a .md attaches automatically, so
+   these prose pages stay static (zero JS) yet still read on-brand. A .md can't
+   @include /base.wd, so this reading skin carries the site's tokens itself.
+   Kept in sync with site/_/base.skin; copy it beside each new post. */
+
+tokens
+  ink #1c1814
+  ink-soft #4b4239
+  muted #756a5d
+  paper #faf8f3
+  panel #ffffff
+  sunk #efe9dc
+  line #e7e1d4
+  accent #0f6b5e
+  accent-deep #0a4f45
+  accent-soft #e3f0ec
+  code-bg #1b2420
+  code-ink #e9efe7
+  code-line #2c3b34
+  radius 12px
+
+tokens dark
+  ink #ece6db
+  ink-soft #c3bbab
+  muted #9a9081
+  paper #14110d
+  panel #1e1913
+  sunk #221d17
+  line #2f281f
+  accent #5ccab4
+  accent-deep #8fe0cf
+  accent-soft #16302a
+  code-bg #100d0a
+  code-ink #e4ebe2
+  code-line #2a231b
+
+html
+  bg $paper
+
+page
+  max-width 720px
+  margin 0 auto
+  padding 3rem 1.5rem 5rem
+  font-family ui-serif, "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, Cambria, serif
+  font-size 18px
+  line-height 1.7
+  color $ink
+  bg $paper
+  -webkit-font-smoothing antialiased
+  text-rendering optimizeLegibility
+
+h1
+  font-size clamp(2rem, 5vw, 2.8rem)
+  line-height 1.12
+  letter-spacing -.022em
+  margin 1rem 0 1.25rem
+  color $ink
+
+h2
+  font-size 1.5rem
+  line-height 1.2
+  letter-spacing -.012em
+  margin 2.4rem 0 .6rem
+  color $ink
+
+h3
+  font-size 1.2rem
+  margin 1.8rem 0 .4rem
+  color $ink
+
+p
+  margin 1.1rem 0
+
+a
+  color $accent
+  text-underline-offset 2px
+
+a:hover
+  color $accent-deep
+
+strong
+  font-weight 650
+  color $ink
+
+hr
+  border 0
+  border-top 1px solid $line
+  margin 2.5rem 0
+
+ul, ol
+  margin 1.1rem 0
+  padding-left 1.4rem
+
+li
+  margin .35rem 0
+
+code
+  font-family ui-monospace, "SF Mono", Menlo, Consolas, monospace
+  font-size .88em
+  bg $sunk
+  color $accent-deep
+  padding .12rem .36rem
+  radius 6px
+
+pre
+  bg $code-bg
+  color $code-ink
+  padding 1.2rem 1.35rem
+  margin 1.5rem 0
+  radius $radius
+  overflow-x auto
+  line-height 1.62
+  font-size .87rem
+  box-shadow inset 0 0 0 1px $code-line
+
+pre code
+  bg transparent
+  color inherit
+  padding 0
+  font-size 1em
+
+blockquote
+  margin 1.6rem 0
+  padding .6rem 1.3rem
+  border-left 3px solid $accent
+  color $ink-soft
+  font-style italic

package/site/pages/blog/zero-js-by-default.md

@@ -15,7 +15,7 @@ none of them pay for it.
 
 That is the whole bargain. A `.md` file is plain CommonMark. Rename it to `.wd`
 and you unlock directives — state, loops, conditionals — but you only ship the
-~7.4 KB runtime on the pages that actually use them. A listing built from a
+~7.5 KB runtime on the pages that actually use them. A listing built from a
 collection loop resolves entirely at build time, so it stays static HTML.
 
 ## The extension is the feature gate

package/site/pages/blog/zero-js-by-default.skin

@@ -0,0 +1,127 @@
+/* Colocated post styling — a .skin next to a .md attaches automatically, so
+   these prose pages stay static (zero JS) yet still read on-brand. A .md can't
+   @include /base.wd, so this reading skin carries the site's tokens itself.
+   Kept in sync with site/_/base.skin; copy it beside each new post. */
+
+tokens
+  ink #1c1814
+  ink-soft #4b4239
+  muted #756a5d
+  paper #faf8f3
+  panel #ffffff
+  sunk #efe9dc
+  line #e7e1d4
+  accent #0f6b5e
+  accent-deep #0a4f45
+  accent-soft #e3f0ec
+  code-bg #1b2420
+  code-ink #e9efe7
+  code-line #2c3b34
+  radius 12px
+
+tokens dark
+  ink #ece6db
+  ink-soft #c3bbab
+  muted #9a9081
+  paper #14110d
+  panel #1e1913
+  sunk #221d17
+  line #2f281f
+  accent #5ccab4
+  accent-deep #8fe0cf
+  accent-soft #16302a
+  code-bg #100d0a
+  code-ink #e4ebe2
+  code-line #2a231b
+
+html
+  bg $paper
+
+page
+  max-width 720px
+  margin 0 auto
+  padding 3rem 1.5rem 5rem
+  font-family ui-serif, "Iowan Old Style", "Palatino Linotype", Palatino, Georgia, Cambria, serif
+  font-size 18px
+  line-height 1.7
+  color $ink
+  bg $paper
+  -webkit-font-smoothing antialiased
+  text-rendering optimizeLegibility
+
+h1
+  font-size clamp(2rem, 5vw, 2.8rem)
+  line-height 1.12
+  letter-spacing -.022em
+  margin 1rem 0 1.25rem
+  color $ink
+
+h2
+  font-size 1.5rem
+  line-height 1.2
+  letter-spacing -.012em
+  margin 2.4rem 0 .6rem
+  color $ink
+
+h3
+  font-size 1.2rem
+  margin 1.8rem 0 .4rem
+  color $ink
+
+p
+  margin 1.1rem 0
+
+a
+  color $accent
+  text-underline-offset 2px
+
+a:hover
+  color $accent-deep
+
+strong
+  font-weight 650
+  color $ink
+
+hr
+  border 0
+  border-top 1px solid $line
+  margin 2.5rem 0
+
+ul, ol
+  margin 1.1rem 0
+  padding-left 1.4rem
+
+li
+  margin .35rem 0
+
+code
+  font-family ui-monospace, "SF Mono", Menlo, Consolas, monospace
+  font-size .88em
+  bg $sunk
+  color $accent-deep
+  padding .12rem .36rem
+  radius 6px
+
+pre
+  bg $code-bg
+  color $code-ink
+  padding 1.2rem 1.35rem
+  margin 1.5rem 0
+  radius $radius
+  overflow-x auto
+  line-height 1.62
+  font-size .87rem
+  box-shadow inset 0 0 0 1px $code-line
+
+pre code
+  bg transparent
+  color inherit
+  padding 0
+  font-size 1em
+
+blockquote
+  margin 1.6rem 0
+  padding .6rem 1.3rem
+  border-left 3px solid $accent
+  color $ink-soft
+  font-style italic

package/site/pages/carousel/index.wd

@@ -1,4 +1,5 @@
 ---
+html: true
 title: Swiper — a draggable carousel wired to wd.subscribe
 description: An image carousel with arrow-key nav, pointer drag / swipe, and a sliding transition — the things a deliberately tiny framework leaves to you. Darkmown owns the reactive slide state, the dots, and the readout declaratively; a colocated index.js adds the gestures through window.wd.subscribe and window.wd.set.
 image: https://darkmown.com/__wd/media/og-showcase.png

package/site/pages/compass/index.wd

@@ -1,4 +1,5 @@
 ---
+html: true
 title: Compass — find your match
 description: A guided product-finder quiz built in one Markdown file. Four questions advance a state machine with :if branching, accumulate scores with :button actions, and a :computed recommendation lands the perfect pick. Zero hand-written JavaScript.
 image: https://darkmown.com/__wd/media/og-compass.png

package/site/pages/data.wd

@@ -1,4 +1,5 @@
 ---
+html: true
 title: Data, forms, and persistence
 transitions: true
 ---
@@ -38,6 +39,8 @@ That loop also proves `:if` over loop items: the lead badge is decided per row.
 
 Every `:fetch` tracks the whole lifecycle — `loading`, `error`, `empty`, and data — so a page can answer each one. Here the same primitive shows an **error** (a missing URL 404s) and an **empty** result (a file that is just `[]`):
 
+*(Heads up: the browser console will log a `404` for `intentionally-missing.json` on this page — that failure is deliberate, so the error branch below has something real to show.)*
+
 :fetch broken from "/__wd/data/intentionally-missing.json"
 
 :if broken_error

package/site/pages/docs/-relative-note.wd

@@ -1,3 +1,7 @@
+---
+html: true
+---
+
 <section class="feature-card">
 
 **Relative include:** this hidden block lives beside the docs page as `-relative-note.wd`, so it can be included without becoming a route.

package/site/pages/docs/index.skin

@@ -17,6 +17,33 @@ main.docs
   color $ink-soft
   max-width 60ch
 
+/* On-page TOC — a compact multi-column block of plain # anchors. */
+.docs-toc
+  border 1px solid $line
+  bg $panel
+  radius $radius
+  padding 1.1rem 1.35rem
+  margin 1.25rem 0 .5rem
+
+.docs-toc ul
+  columns 2
+  column-gap 2.5rem
+  margin .55rem 0 0
+  padding 0
+  list-style none
+
+.docs-toc li
+  margin .18rem 0
+  break-inside avoid
+  font-size .95rem
+
+.docs-toc a
+  font-weight 500
+
+@media (max-width: 600px)
+  .docs-toc ul
+    columns 1
+
 /* Section headings get a quiet rule above them so the long page scans. */
 main.docs h2
   margin-top 3rem

package/site/pages/docs/index.wd

@@ -1,4 +1,5 @@
 ---
+html: true
 title: Darkmown docs
 description: Learn Darkmown routing, directives, state, loops, forms, and the static-to-reactive model.
 transitions: true
@@ -17,6 +18,41 @@ transitions: true
 Darkmown is a Markdown-native framework for mostly-static sites with tiny reactive islands. Pages are plain files: `.md` stays pure CommonMark, and `.wd` ("whateverdown") is the same Markdown plus first-party directives.
 </header>
 
+<nav class="docs-toc" aria-label="On this page">
+
+**On this page**
+
+- [Install](#install)
+- [The two formats](#the-two-formats)
+- [Routing rules](#routing-rules)
+- [Includes](#includes)
+- [Loops](#loops)
+- [Content collections](#content-collections)
+- [Interpolation](#interpolation)
+- [Frontmatter](#frontmatter)
+- [SEO & feeds](#seo--feeds)
+- [Drafts](#drafts)
+- [Instant navigation](#instant-navigation)
+- [Images](#images)
+- [Sections](#sections)
+- [Reactive directives](#reactive-directives)
+- [Fetching data](#fetching-data)
+- [Global state — `:store`](#global-state--store)
+- [Forms and persistence](#forms-and-persistence)
+- [Backends & deploy](#backends--deploy)
+- [Interactions](#interactions--slider-sortable-carousel)
+- [Theme toggle — `:theme`](#theme-toggle--theme)
+- [Scoped styles — `scoped`](#scoped-styles--scoped)
+- [Media directives](#media--video-audio-embed)
+- [Syntax highlighting](#syntax-highlighting)
+- [Trust boundary](#trust-boundary)
+- [Colocation](#colocation)
+- [CLI reference](#cli-reference)
+- [Spec status](#spec-status)
+</nav>
+
+Every heading on every page gets a stable, GitHub-style `id` at build time (lowercased, punctuation stripped, duplicates deduped), so the links above — and deep links into any Darkmown page — are plain `#` anchors with zero JavaScript.
+
 @include ./-relative-note.wd
 
 ## Install
@@ -30,6 +66,10 @@ npm run dev
 
 Or add Darkmown to an existing project with `npm install -D @zvndev/darkmown`. The package is scoped; the command it installs is plain `darkmown`.
 
+For editing, a [VS Code extension](https://github.com/ZVN-DEV/darkmown/tree/master/editors/vscode) gives `.wd` and `.skin` files syntax highlighting, snippets, and folding — install it from a `.vsix` built out of the framework repo (see its `editors/vscode` README; a Marketplace listing is pending).
+
+`darkmown dev` rebuilds incrementally: it tracks which routes depend on each file (includes, colocated assets, loop data, collections), so editing one page or include recompiles only the routes it affects — and falls back to a full rebuild whenever a file is added, removed, or renamed. `routes.json`, the sitemap, and the RSS feed are regenerated on every rebuild, so they always describe the whole site.
+
 ## The two formats
 
 - `.md` is strict CommonMark. Directives, includes, and `{ bindings }` stay plain text, and the build prints a hint if it spots `.wd` syntax in a `.md` file.
@@ -54,7 +94,7 @@ Or add Darkmown to an existing project with `npm install -D @zvndev/darkmown`. T
 
 `@loop <things> into <thing>` is the only loop. The body is normal Markdown (or more directives) and repeats once per row:
 
-```wd
+```wd-fragment
 @loop /features.json into card
 @include /feature-card.wd
 @endloop
@@ -72,7 +112,7 @@ Loops nest, and `{ card.title }` style dotted paths reach into each row.
 
 Add `where <predicate>` to filter a loop. Conditions join with `and` / `or`:
 
-```wd
+```wd-fragment
 @loop /products.json into p where p.featured == true and p.price < 80
 - { p.name }
 @endloop
@@ -100,12 +140,22 @@ The predicate decides reactivity exactly like the source does: read only the row
 A `:button` inside a reactive loop can act on its own row — the basis for carts and to-do lists:
 
 ```wd
+:state products = [{"id": 1, "name": "Aurora", "price": 49}]
+:state cart = []
+
 @loop products into product
+::: card
+**{ product.name }** — ${ product.price }
 :button "Add to cart" -> cart += product
 :::
+@endloop
+
 @loop cart into line
+::: card
+{ line.name }
 :button "Remove" -> cart remove line
 :::
+@endloop
 ```
 
 `cart += product` appends a copy of the current row to another `:state` list; `cart remove line` removes the current row from the list being looped. Both are checked against the enclosing loop at compile time — no JavaScript.
@@ -114,7 +164,7 @@ A `:button` inside a reactive loop can act on its own row — the basis for cart
 
 Shape a loop with clauses in a fixed order after `into`: `where`, then `sort by`, `reverse`, `offset`, `limit`.
 
-```wd
+```wd-fragment
 @loop /posts.json into post sort by post.date desc limit 5
 { $number }. { post.title }
 @endloop
@@ -125,7 +175,7 @@ Shape a loop with clauses in a fixed order after `into`: `where`, then `sort by`
 
 Every row exposes meta variables — `{ $index }` (0-based), `{ $number }` (1-based), `{ $first }`, `{ $last }`, `{ $count }` — usable in interpolation and `:if`:
 
-```wd
+```wd-fragment
 @loop products into product
 :if $first
 **Top pick:**
@@ -138,7 +188,7 @@ Every row exposes meta variables — `{ $index }` (0-based), `{ $number }` (1-ba
 
 Add an `@empty` branch to render a fallback when the loop produces no rows (after filtering and slicing):
 
-```wd
+```wd-fragment
 @loop todos into todo
 - { todo.title }
 @empty
@@ -146,13 +196,15 @@ Nothing left to do.
 @endloop
 ```
 
+A **missing** in-scope source is an empty list, not an error — `@loop meta.tags into tag` on a page whose frontmatter omits `tags` (an optional field) loops zero rows and renders the `@empty` branch. A value that is present but not a list is still a compile error with the file and line.
+
 These clauses stay build-time when the source and every argument are static — a sorted, limited loop over a JSON file ships zero JS. The loop turns reactive only when the source or a clause reads `:state`/`:store`/`:fetch` data.
 
 ## Content collections
 
 Any folder under `site/pages/` is a **collection** — loop it by its bare name. No `content/` root, no marker file: a `site/pages/blog/` folder of posts *is* the `blog` collection. The whole [blog on this site](/blog/) is one such loop.
 
-```wd
+```wd-fragment
 @loop blog into post sort by post.date desc
 - [{ post.title }]({ post.url }) — { post.date }
 @endloop
@@ -179,7 +231,7 @@ Closed types: `string`, `number`, `boolean`, `date`, `string[]`, each with `?` f
 
 Add `paginate N` (collections only) to split a listing into static pages. Page 1 keeps the listing route; pages 2+ are at `/<route>/page/2/`, `/page/3/`, … all static HTML.
 
-```wd
+```wd-fragment
 @loop blog into post sort by post.date desc paginate 5
 - [{ post.title }]({ post.url })
 @endloop
@@ -208,6 +260,8 @@ One syntax everywhere: `{ name }` or `{ name.path }`.
 
 Shape a value for display with a pipe: `{ price | money }`, `{ joinedAt | date:"medium" }`, `{ ratio | percent }`. Pipes chain (`{ name | trim | capitalize }`) and take literal arguments (`{ total | money:"EUR" }`, `{ bio | truncate:80 }`). The same syntax works on static values (folded at build time, zero-JS) and live bindings (re-applied on render).
 
+The value being piped must be **in scope** — a loop variable, `:state`/`:store`, an include argument, or `meta`. A bare literal like `{ 89 | money }` is not a name in scope, so it stays literal text (braces and all), exactly like any unresolved `{ … }`. A date-only value (`"2026-06-22"`) formats in UTC, so `date` prints the written calendar date on any build machine.
+
 The whitelist: `money`, `number`, `percent`, `round`, `date` / `time` / `datetime` (Intl-backed; `short` / `medium` / `long`), `upper` / `lower` / `capitalize`, `truncate:n` / `trim`, `pluralize:"item"`, and `default:"—"`. The five aggregates double as list pipes — `{ cart | count }`, `{ cart | sum:"price" | money }`, plus `avg` / `min` / `max`. No custom functions, nothing `eval`'d; an unknown pipe is a compile error. There is deliberately no relative "time ago" formatter, so builds stay reproducible.
 
 ## Frontmatter
@@ -223,6 +277,8 @@ tags: [sales, revenue, "q1, q2"]
 
 `{ meta.title }` prints a scalar and `{ meta.tags }` joins an array with `, `. You can loop a frontmatter array at build time — `@loop meta.tags into tag` — and the page stays static. Arrays are inline flow only (`[a, b]`); quoted items keep their commas.
 
+`lang:` sets the document language on `<html lang>` per page (`lang: fr`, `lang: pt-BR`, …); it defaults to `en`. Every page also ships a visually-hidden-until-focused **skip-to-content link** targeting the main landmark — your own `<main>` is reused (an existing `id` wins as the target; an id-less one gets `id="main"`), and a page without one is wrapped in `<main id="main">`. Restyle it via `.wd-skip-link` in a skin. All compile-time — static pages stay zero-JS.
+
 ## SEO & feeds
 
 `darkmown build` writes `sitemap.xml`, `rss.xml`, and `robots.txt` — all build-time, zero client JS. There's no config file: the **home page** frontmatter carries the site's identity. Add `site_url` (absolute origin, no trailing slash) and the sitemap and feed switch on, prefixed with that origin and titled with the home `title`/`description`.
@@ -253,9 +309,11 @@ You don't size images by hand. Every `<img>` the compiler emits gets its intrins
 
 `::: section #id .class` opens a container and `:::` closes it. Sections scope state: a `:state` declared inside a section belongs to that section, so two sections can both declare `count` without colliding. Bindings and buttons resolve to the nearest scope.
 
+A container named `nav` or `main` emits the real landmark element (`<nav class="nav">`, `<main class="main">`) so pages keep proper landmarks without raw HTML. Any other name stays a `<div>` with that class.
+
 ## Reactive directives
 
-Reactive pages opt into `/__wd/runtime.js` (~7.4 KB gzipped, under a CI-enforced 8 KB budget). Static pages do not.
+Reactive pages opt into `/__wd/runtime.js` (~7.5 KB gzipped, under a CI-enforced 8 KB budget). Static pages do not.
 
 ```wd
 :state count = 0
@@ -311,7 +369,7 @@ The aggregate's field is a bare row key (`price`, not `item.price`).
 
 A condition reads the same predicate grammar as `.class when` — a bare path (truthy), or the comparisons `==` `!=` `<` `<=` `>` `>=` `contains`, joined with `and`, `or`, and `not`. (`@loop … where` is the comparison-only subset.) Chain with `:else if` (any number; a bare `:else` must come last):
 
-```wd
+```wd-fragment
 :if plan == "pro" or seats >= 5
 Pro plan
 :else if trialDays > 0 and not expired
@@ -327,7 +385,7 @@ A whole chain compiles to nested conditional regions, so it folds at build time
 
 A container class can react to state or the loop item. Static `.class` tokens stay as-is; add `when <predicate>` for a reactive one:
 
-```wd
+```wd-fragment
 @loop products into p
 ::: card .product .on-sale when p.price < 50
 **{ p.name }** — ${ p.price }
@@ -362,7 +420,7 @@ A `:button "Label" -> action` mutates one `:state` or `:store` value. The vocabu
 
 Values are literals — a `"string"`, number, `true`/`false`/`null`, or inline JSON. Targets may be dotted paths (`cart.count++`), and one button can run several actions separated by `;` (applied in order, rendered once):
 
-```wd
+```wd-fragment
 :button "Add to cart" -> cart.count++ ; cart.total += 9
 ```
 
@@ -388,6 +446,8 @@ No team members yet.
 :endif
 ```
 
+The lifecycle regions announce themselves to assistive tech: a bare `:if name_loading` compiles with `role="status" aria-live="polite"` and `:if name_error` with `role="alert"` — compile-time attributes, no extra runtime JS. Write your own `role`/`aria-live` inside a region and nothing is added.
+
 Options after the URL: `method=` (default `GET`), `when=load|visible`, `timeout=<ms>`, `retry=<N>`, `headers=<key>`, and `body=<key>` (the last two name a `:state`/`:store` key). A URL can interpolate state (`"/api/users/{ userId }"`) and re-fetches automatically when that state changes; trigger a reload by hand with `:button "Reload" -> team refetch`. Loop a sub-path of fetched data with a dotted source — `@loop team.members into member`. URLs must be relative, `http(s)://`, or a leading `{ state }` interpolation — other schemes are rejected at compile time.
 
 ### Authenticated requests
@@ -530,10 +590,10 @@ The framework ships a small default `$code-*` set, so highlighting looks right o
 Darkmown is a trusted-author site generator: you compile content you wrote, the way you trust your own source. Three things define that boundary.
 
 - **Compile only content you authored.** Don't run `.md`/`.wd` you didn't write — user-generated content, third-party docs — through the compiler without sanitizing it first.
-- **Raw HTML passes through by default.** Markdown renders with `html: true`, so raw HTML is emitted verbatim and there is no built-in sanitizer. Set `html: false` in a page's frontmatter to drop raw HTML for untrusted content.
+- **Raw HTML is escaped by default.** Markdown renders with `html: false`, so a stray `<script>` in content becomes inert text — safe for multi-author collections out of the box. Set `html: true` in a page's frontmatter to pass your own raw HTML through verbatim; there is no built-in sanitizer, so keep it off pages with content you didn't write.
 - **`:fetch` and `:form action=` have no host allowlist, and reactive pages need `unsafe-eval`.** Fetch/form URLs come straight from the page source — the compiler rejects non-http(s) schemes but does not restrict which hosts you call, so SSRF/exfiltration protection is the author's responsibility. The runtime compiles `:computed` / `@loop … where` / `.class when` expressions via `new Function`, so a reactive page needs `script-src 'unsafe-eval'` in your CSP. Static pages need neither.
 
-See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/main/SECURITY.md) in the package for the full security model.
+See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/master/SECURITY.md) in the package for the full security model.
 
 ## Colocation
 
@@ -542,9 +602,20 @@ See [SECURITY.md](https://github.com/ZVN-DEV/darkmown/blob/main/SECURITY.md) in
 - Both work for included fragments too, by basename.
 - Any other file under `site/pages/` (an image, font, PDF — anything that isn't a `.md`/`.wd` route or a basename-matched `.skin`/`.js`) copies to `dist/` at its own path with the right content-type. So `site/pages/logo.svg` is served at `/logo.svg`. Assets below hidden path segments (`.`, `-`, or `_`) and symlinked page assets are skipped, matching the routing privacy rule. Use the `site/_/` shelf for assets shared across pages; colocate the ones a single page owns.
 
+## CLI reference
+
+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 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/*`).
+- `darkmown deploy <vercel|cloudflare> [--prod]` — build (target-aware) and deploy through the platform CLI, printing your URL; an unauthenticated CLI surfaces the login to run first.
+- `darkmown version` / `darkmown help` — print the installed version, or the full command summary and directive syntax.
+
 ## Spec status
 
-The implementation is faithful to the original core thesis: Markdown-first authoring, no component ceremony, zero runtime on static pages, and tiny direct-DOM reactivity only when declared. `:store`, the full `:fetch` lifecycle (loading/error/empty states, dynamic URLs, `refetch`, dotted loop sources, authenticated `headers=` + `refresh=` token renewal), `:form` (including server round-trips), loop ergonomics (`sort by`/`limit`/`offset`/`reverse`/`@empty` and `$index`/`$number`/`$first`/`$last`/`$count`), `:if … :else if … :else`, reactive `.class when …`, `:effect`, `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/) and the [Reactive page](/reactive/). Still on the roadmap: a first-party server runtime (`site/api/`) and HTML-fragment swaps. See `docs/spec-alignment.md` in the package for the full audit.
+The implementation is faithful to the original core thesis: Markdown-first authoring, no component ceremony, zero runtime on static pages, and tiny direct-DOM reactivity only when declared. `:store`, the full `:fetch` lifecycle (loading/error/empty states, dynamic URLs, `refetch`, dotted loop sources, authenticated `headers=` + `refresh=` token renewal), `:form` (including server round-trips), loop ergonomics (`sort by`/`limit`/`offset`/`reverse`/`@empty` and `$index`/`$number`/`$first`/`$last`/`$count`), `:if … :else if … :else`, reactive `.class when …`, `:effect`, `:computed`, and `persist` are all shipped and live — try them on the [Data & Forms page](/data/) and the [Reactive page](/reactive/). Still on the roadmap: HTML-fragment `swap` semantics and cart server sync. (The serverless `api/` model already shipped in 1.2.0 — see [Backends & deploy](#backends--deploy) above; a `.wd` backend DSL remains a deliberate non-goal.) See `docs/spec-alignment.md` in the package for the full audit.
 
 See these directives composed into real apps on the [showcase](/showcase/).
 

package/site/pages/folio/-style.wd

@@ -1,3 +1,7 @@
+---
+html: true
+---
+
 <!-- Folio — shared style carrier.
 
      Both the catalog (/folio/) and the cart (/folio/cart/) `@include ./style.wd`

package/site/pages/folio/cart.wd

@@ -1,4 +1,5 @@
 ---
+html: true
 title: Folio — your basket
 description: The Folio checkout. The same :store cart shared with the catalog, a per-row remove, and a form that round-trips to a server — all written in Markdown.
 image: https://darkmown.com/__wd/media/og-folio.png

package/site/pages/folio/index.wd

@@ -1,4 +1,5 @@
 ---
+html: true
 title: Folio — a boutique storefront
 description: A multi-page store written in pure Markdown. The cart persists across pages, reloads, and browser tabs; navigation is instant. No framework JavaScript written by hand.
 image: https://darkmown.com/__wd/media/og-folio.png

package/site/pages/forge/index.wd

@@ -1,4 +1,5 @@
 ---
+html: true
 title: Forge your plan — a live pricing configurator in Markdown
 description: Build your plan, toggle features, adjust the seat count, and watch the price, savings, and upsell hints update instantly. A classic "this needs React" interaction — written as one Markdown file with a reactive :computed pricing engine.
 image: https://darkmown.com/__wd/media/og-forge.png

package/site/pages/highlight/index.wd

@@ -1,4 +1,5 @@
 ---
+html: true
 title: Syntax highlighting — code that dark-modes for free
 description: Build-time syntax highlighting in plain Markdown. Fenced code blocks highlight at compile time (zero client JS) and recolor with your theme through the same tokens dark / :theme system — flip the toggle and watch every language recolor at once.
 image: https://darkmown.com/__wd/media/og-showcase.png

package/site/pages/index.js

@@ -1,3 +1,22 @@
+const copyBtn = document.querySelector("[data-copy-cmd]");
+
+if (copyBtn) {
+  copyBtn.addEventListener("click", async () => {
+    const cmd = copyBtn.previousElementSibling?.textContent ?? "";
+    try {
+      await navigator.clipboard.writeText(cmd);
+      copyBtn.textContent = "Copied";
+      copyBtn.classList.add("is-copied");
+      setTimeout(() => {
+        copyBtn.textContent = "Copy";
+        copyBtn.classList.remove("is-copied");
+      }, 1600);
+    } catch {
+      copyBtn.textContent = "Select + ⌘C";
+    }
+  });
+}
+
 const button = document.querySelector("[data-wd-demo]");
 
 if (button) {