vagejs 0.3.5 → 0.5.0

package/dist/core/site.js

@@ -7,7 +7,7 @@ import { copySource, htmlToMarkdown, markdownCopy, markdownCopyPath } from "../d
 import { robotsTxt } from "../discovery/robots.js";
 import { SITEMAP_URL_LIMIT, sitemapXml } from "../discovery/sitemap.js";
 import { copyCanonicalsFit, headersFile } from "../deploy/headers.js";
-import { cloudflareRedirects } from "../deploy/redirects.js";
+import { cloudflareRedirects, netlifyRedirects } from "../deploy/redirects.js";
 import { findSecrets } from "../deploy/secrets.js";
 import { rulePack } from "../guidelines/pack.js";
 import { absoluteUrl } from "../seo/urls.js";
@@ -17,7 +17,8 @@ import { escapeHtml } from "./html.js";
 import { renderPage } from "./render.js";
 import { parseFrontmatter } from "../content/markdown.js";
 import { sharpResize } from "../content/optimize.js";
-import { collectPages } from "./pages.js";
+import { scheduledFor } from "./dates.js";
+import { collection, collectPages, tagList } from "./pages.js";
 import { discoverRoutes, findNotFoundPage, normalizeRequestPath } from "./routes.js";
 /** Renders every page and derives discovery files from the same data, without writing anything. */
 export async function renderSite(root, load, options = {}) {
@@ -31,7 +32,7 @@ export async function renderSite(root, load, options = {}) {
         throw new VageError(`This project pins rule pack ${pinned}, but the installed vagejs ships ${rulePack.version}. ` +
             `Review what changed with "vage guidelines", then update guidelines.rulePack in vage.config.ts.`);
     }
-    const model = { site, pageErrors: [], pages: [], skippedDrafts: [], draftRoutes: [], redirects: [], files: new Map(), warnings: [] };
+    const model = { site, pageErrors: [], pages: [], skippedDrafts: [], draftRoutes: [], skippedScheduled: [], redirects: [], files: new Map(), warnings: [] };
     const collect = options.collectErrors === true;
     const attempt = async (file, route, work) => {
         try {
@@ -51,16 +52,37 @@ export async function renderSite(root, load, options = {}) {
     for (const entry of discoverRoutes(pagesDir)) {
         const source = path.relative(root, entry.file);
         await attempt(entry.file, entry.route, async () => {
-            // Drafts are skipped before rendering, so their fields can't fail a build.
-            if (parseFrontmatter(fs.readFileSync(entry.file, "utf8"), entry.file).frontmatter.draft) {
+            // Drafts and scheduled pages are skipped before rendering, so their fields can't fail a build.
+            const { frontmatter } = parseFrontmatter(fs.readFileSync(entry.file, "utf8"), entry.file);
+            if (frontmatter.draft) {
                 model.skippedDrafts.push(source);
                 model.draftRoutes.push(entry.route);
                 return;
             }
+            const date = scheduledFor(frontmatter.datePublished);
+            if (date) {
+                model.skippedScheduled.push({ source, route: entry.route, date });
+                return;
+            }
             const page = await renderPage({ root, file: entry.file, route: entry.route, site, load, analytics: true, pages, resize });
             model.pages.push({ ...page, route: entry.route, source, outFile: entry.outFile });
         });
     }
+    if (site.tags.pages) {
+        // Only published pages can clash: a draft or scheduled page at a tag address isn't in the build.
+        const taken = new Map(model.pages.map((p) => [p.route, p.source]));
+        for (const tag of tagList(pages)) {
+            const file = path.join(pagesDir, "tags", `${tag.slug}.md`);
+            const source = `(tag "${tag.name}")`;
+            await attempt(file, tag.route, async () => {
+                if (taken.has(tag.route)) {
+                    throw new VageError(`${taken.get(tag.route)} and the tag "${tag.name}" both make ${tag.route}. Rename one, or set tags.pages: false in vage.config.ts.`);
+                }
+                const page = await renderPage({ root, file, route: tag.route, site, load, analytics: true, pages, resize, source: tagPageSource(site, tag.name, collection(pages, { tag: tag.name, sort: "date" })) });
+                model.pages.push({ ...page, route: tag.route, source, outFile: `${tag.route.slice(1)}index.html` });
+            });
+        }
+    }
     const notFound = findNotFoundPage(pagesDir);
     if (notFound) {
         await attempt(notFound, undefined, async () => {
@@ -79,6 +101,23 @@ export async function renderSite(root, load, options = {}) {
     addDiscoveryFiles(root, model, markdown);
     return model;
 }
+/** A tag page's Markdown: a heading and the tagged pages, newest first. Written as HTML so tag and page names can't become Markdown. */
+export function tagPageSource(site, name, tagged) {
+    const items = tagged.map((p) => `<li><a href="${escapeHtml(p.route)}">${escapeHtml(p.title)}</a>${p.description ? `: ${escapeHtml(p.description)}` : ""}</li>`);
+    const description = `Pages${site.title ? ` on ${site.title}` : ""} tagged ${name}.`;
+    return [
+        "---",
+        `title: ${JSON.stringify(`Tagged: ${name}`)}`,
+        `description: ${JSON.stringify(description)}`,
+        ...(site.tags.layout ? [`layout: ${site.tags.layout}`] : []),
+        "---",
+        "",
+        `<h1>Tagged: ${escapeHtml(name)}</h1>`,
+        "",
+        `<ul>\n${items.join("\n")}\n</ul>`,
+        "",
+    ].join("\n");
+}
 /** Pages that should appear in sitemap.xml and llms.txt: indexable and canonical to themselves. */
 export function listedPages(model) {
     return model.pages.filter((p) => !p.meta.noindex && p.meta.canonical === absoluteUrl(model.site.site, p.route));
@@ -134,11 +173,14 @@ function addDiscoveryFiles(root, model, markdown) {
     const indexNow = site.integrations.indexNow;
     if (indexNow)
         generate(`${indexNow.key}.txt`, () => `${indexNow.key}\n`);
-    // Cloudflare Pages and Workers static assets both read _redirects and _headers.
+    // Cloudflare Pages, Workers static assets and Netlify all read _redirects and _headers.
+    const netlify = site.deploy.target === "netlify";
     const cloudflare = site.deploy.target === "cloudflare-pages" || site.deploy.target === "cloudflare-workers";
     if (cloudflare && model.redirects.length)
         generate("_redirects", () => cloudflareRedirects(model.redirects));
-    if (cloudflare && site.security.headers) {
+    if (netlify && model.redirects.length)
+        generate("_redirects", () => netlifyRedirects(model.redirects));
+    if ((cloudflare || netlify) && site.security.headers) {
         const html = [...model.pages, ...(model.notFound ? [model.notFound] : []), ...model.redirects].map((p) => p.html);
         // Each Markdown copy names its HTML page as canonical, so search engines don't index both.
         const copies = site.seo.markdownCopies && site.site ? listed.map((p) => ({ path: `/${markdownCopyPath(p.route)}`, canonical: p.meta.canonical })).filter((c) => /^\/[A-Za-z0-9._~\/-]+$/.test(c.path) && /^[^\s<>]+$/.test(c.canonical)) : [];

package/dist/deploy/netlify.d.ts

@@ -0,0 +1,22 @@
+import type { DeployStatus, Runner } from "./github-pages.js";
+/** Pinned so deploys are reproducible; checked 2026-10-25. */
+export declare const NETLIFY_CLI = "netlify-cli@27.12.1";
+export interface NetlifyDeployment extends DeployStatus {
+    site: string;
+    deployId?: string;
+}
+/**
+ * Uploads dist/ to a Netlify site's production deploy with netlify-cli (no Netlify build:
+ * vagejs already built it). Auth comes from NETLIFY_AUTH_TOKEN or a prior `netlify login`,
+ * never a command-line flag. The build wrote Netlify's _headers and _redirects (forced
+ * 301s, so they win over the HTML forwarding pages). Success needs netlify-cli to
+ * succeed AND the live site to answer 200: `siteUrl` when set, else the site's Netlify URL.
+ */
+export declare function deployNetlify(root: string, options: {
+    site: string;
+    siteUrl?: string;
+    run?: Runner;
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    env?: Record<string, string | undefined>;
+}): Promise<NetlifyDeployment>;

package/dist/deploy/netlify.js

@@ -0,0 +1,48 @@
+import { redact } from "../integrations/http.js";
+import { runCommand } from "./github-pages.js";
+/** Pinned so deploys are reproducible; checked 2026-10-25. */
+export const NETLIFY_CLI = "netlify-cli@27.12.1";
+/**
+ * Uploads dist/ to a Netlify site's production deploy with netlify-cli (no Netlify build:
+ * vagejs already built it). Auth comes from NETLIFY_AUTH_TOKEN or a prior `netlify login`,
+ * never a command-line flag. The build wrote Netlify's _headers and _redirects (forced
+ * 301s, so they win over the HTML forwarding pages). Success needs netlify-cli to
+ * succeed AND the live site to answer 200: `siteUrl` when set, else the site's Netlify URL.
+ */
+export async function deployNetlify(root, options) {
+    const run = options.run ?? runCommand;
+    const doFetch = options.fetch ?? fetch;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const secrets = [(options.env ?? process.env).NETLIFY_AUTH_TOKEN];
+    const { site } = options;
+    const res = await run("npx", ["--yes", NETLIFY_CLI, "deploy", "--dir", "dist", "--prod", "--no-build", "--site", site, "--json"], root);
+    const output = redact(`${res.stdout}\n${res.stderr}`, secrets);
+    if (res.code !== 0) {
+        const auth = /auth|log ?in|token|unauthori[sz]ed|401/i.test(output) ? " Set NETLIFY_AUTH_TOKEN, or run `npx netlify-cli login`." : "";
+        const missing = /not found|404|no (?:project|site)/i.test(output) ? ` Check that the Netlify site "${site}" exists (deploy.netlifySite is its name or ID).` : "";
+        return { status: "failure", site, reason: `netlify-cli failed (exit ${res.code}).${auth}${missing}\n${tail(output)}` };
+    }
+    let data = {};
+    try {
+        data = JSON.parse(res.stdout.slice(res.stdout.indexOf("{")));
+    }
+    catch {
+        // Older or newer netlify-cli output; the live check below still decides.
+    }
+    const deployId = typeof data.deploy_id === "string" ? data.deploy_id : undefined;
+    const netlifyUrl = typeof data.url === "string" && /^https:\/\//.test(data.url) ? data.url : undefined;
+    const pageUrl = options.siteUrl ?? netlifyUrl;
+    if (!pageUrl)
+        return { status: "unconfirmed", site, deployId, reason: `Uploaded, but there is no URL to check: set \`site\` in vage.config.ts.\n${tail(output)}` };
+    for (let i = 0; i < 5; i++) {
+        const page = await doFetch(pageUrl, { signal: AbortSignal.timeout(20_000) }).catch(() => undefined);
+        if (page?.ok)
+            return { status: "success", site, deployId, pageUrl };
+        await sleep(3000);
+    }
+    const own = netlifyUrl && netlifyUrl !== pageUrl ? ` The site itself is at ${netlifyUrl}. If ${pageUrl} is your own domain, add it in Netlify under Domain management.` : "";
+    return { status: "unconfirmed", site, deployId, pageUrl, reason: `Deployed, but ${pageUrl} did not respond with 200 yet. Check it in a minute.${own}` };
+}
+function tail(text) {
+    return text.trim().split("\n").slice(-8).join("\n");
+}

package/dist/deploy/redirects.d.ts

@@ -5,3 +5,8 @@ import type { SiteRedirect } from "../core/site.js";
  * Both "/old" and "/old/" are listed so either form redirects.
  */
 export declare function cloudflareRedirects(redirects: SiteRedirect[]): string;
+/**
+ * Netlify `_redirects`: the same rules, forced ("301!"). Netlify serves an existing file
+ * before a redirect, and vagejs writes an HTML forwarding page at each old address.
+ */
+export declare function netlifyRedirects(redirects: SiteRedirect[]): string;

package/dist/deploy/redirects.js

@@ -16,3 +16,11 @@ export function cloudflareRedirects(redirects) {
         throw new VageError(`_redirects would have ${lines.length} rules; Cloudflare Pages allows ${maxStaticRules}.`);
     return `# Generated by vagejs from redirects in vage.config.ts\n${lines.join("\n")}\n`;
 }
+/**
+ * Netlify `_redirects`: the same rules, forced ("301!"). Netlify serves an existing file
+ * before a redirect, and vagejs writes an HTML forwarding page at each old address.
+ */
+export function netlifyRedirects(redirects) {
+    const lines = redirects.flatMap((r) => (r.from === "/" ? ["/"] : [r.from, r.from.replace(/\/$/, "")]).map((from) => `${from} ${r.to} 301!`));
+    return `# Generated by vagejs from redirects in vage.config.ts\n${lines.join("\n")}\n`;
+}

package/dist/dev/guard.js

@@ -46,7 +46,7 @@ export function allowed(url, publicDir, allowedFiles) {
     if (allowedFiles.has(pathname))
         return true;
     // Optimized images (images.optimize), served from the cache by the dev server.
-    if (/^\/_vage\/img\/[\w-]+\.webp$/.test(pathname))
+    if (/^\/_vage\/img\/[\w-]+\.(webp|avif)$/.test(pathname))
         return true;
     // Generated files (seo.feeds, seo.markdownCopies) never exist on disk in dev. If a real file
     // sits at that path, it's a project source (e.g. /src/pages/about.md): Vite would serve it, so refuse.

package/dist/dev/server.js

@@ -7,8 +7,8 @@ import { escapeHtml } from "../core/html.js";
 import { baseViteConfig, viteLoader } from "../core/loader.js";
 import { renderPage } from "../core/render.js";
 import { cacheDir } from "../content/optimize.js";
-import { collectPages } from "../core/pages.js";
-import { renderSite } from "../core/site.js";
+import { collection, collectPages, tagList } from "../core/pages.js";
+import { renderSite, tagPageSource } from "../core/site.js";
 import { discoverRoutes, findNotFoundPage, normalizeRequestPath } from "../core/routes.js";
 import { devAccessGuard } from "./guard.js";
 import { listenOrExplain } from "./listen.js";
@@ -48,12 +48,12 @@ export async function startDevServer(root, options = {}) {
         const urlPath = req.url ?? "/";
         const pathname = urlPath.split(/[?#]/)[0];
         try {
-            const optimized = /^\/_vage\/img\/([\w-]+\.webp)$/.exec(pathname);
+            const optimized = /^\/_vage\/img\/([\w-]+\.(webp|avif))$/.exec(pathname);
             if (optimized) {
                 const file = path.join(cacheDir(root), optimized[1]);
                 if (!fs.existsSync(file))
                     return send(res, 404, plainPage("404 — Not found", `No optimized image at ${pathname}`));
-                res.setHeader("Content-Type", "image/webp");
+                res.setHeader("Content-Type", `image/${optimized[2]}`);
                 return res.end(fs.readFileSync(file));
             }
             const isFeed = /^\/(?:[\w.-]+\/)*feed\.xml$/.test(pathname) && !pathname.includes("..");
@@ -91,6 +91,17 @@ export async function startDevServer(root, options = {}) {
             if (entry && !pathname.endsWith("/") && !pathname.endsWith(".html")) {
                 return redirect(res, entry.route + urlPath.slice(pathname.length));
             }
+            if (!entry && site.tags.pages && route.startsWith("/tags/")) {
+                const pages = await collectPages(root, site, load, { skipInvalid: true });
+                const tag = tagList(pages).find((t) => t.route === route);
+                if (tag) {
+                    if (!pathname.endsWith("/"))
+                        return redirect(res, tag.route + urlPath.slice(pathname.length));
+                    const source = tagPageSource(site, tag.name, collection(pages, { tag: tag.name, sort: "date" }));
+                    const page = await renderPage({ root, file: path.join(pagesDir, "tags", `${tag.slug}.md`), route, site, load, pages, source });
+                    return send(res, 200, await server.transformIndexHtml(urlPath, page.html));
+                }
+            }
             const notFound = findNotFoundPage(pagesDir);
             if (!entry && !notFound) {
                 return send(res, 404, await server.transformIndexHtml(urlPath, plainPage("404 — Not found", `No page for ${route}`)));

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { escapeHtml, html, raw, type SafeHtml } from "./core/html.js";
 export { z } from "zod";
 export type { Layout, LayoutProps } from "./core/render.js";
 export type { Frontmatter } from "./content/markdown.js";
-export { breadcrumbs, collection, flatten, neighbors, tree, type CollectionOptions, type PageSummary, type TreeNode } from "./core/pages.js";
+export { breadcrumbs, collection, flatten, neighbors, tagList, tagSlug, tree, type CollectionOptions, type PageSummary, type TagSummary, type TreeNode } from "./core/pages.js";
 export { build, type BuildResult } from "./core/build.js";
 export { startDevServer } from "./dev/server.js";
 export { startPreviewServer } from "./dev/preview.js";

package/dist/index.js

@@ -2,7 +2,7 @@ export { defineConfig } from "./core/config.js";
 export { escapeHtml, html, raw } from "./core/html.js";
 /** Zod, for layout field schemas: `export const frontmatter = z.object({ ... })`. Same instance vagejs validates with. */
 export { z } from "zod";
-export { breadcrumbs, collection, flatten, neighbors, tree } from "./core/pages.js";
+export { breadcrumbs, collection, flatten, neighbors, tagList, tagSlug, tree } from "./core/pages.js";
 export { build } from "./core/build.js";
 export { startDevServer } from "./dev/server.js";
 export { startPreviewServer } from "./dev/preview.js";

package/dist/mcp/server.d.ts

@@ -0,0 +1,27 @@
+/** Published pages, drafts and scheduled pages, without writing anything. */
+export declare function listPages(root: string): Promise<{
+    pages: {
+        route: string;
+        source: string;
+        title: string;
+        description: string | undefined;
+        layout: string;
+        noindex: boolean;
+    }[];
+    drafts: string[];
+    scheduled: {
+        source: string;
+        date: string;
+    }[];
+    errors: import("../core/site.js").PageError[];
+}>;
+/**
+ * `vage mcp`: an MCP server over stdio for the project at `root`. Every tool is
+ * read-only; approving links and deploying stay with people, through the CLI.
+ * stdout carries the protocol, so anything else that prints goes to stderr.
+ */
+export declare function startMcpServer(root: string, options: {
+    version: string;
+    info: () => unknown;
+    transport?: unknown;
+}): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,81 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { check } from "../checks/check.js";
+import { linkStatus } from "../checks/links.js";
+import { VageError } from "../core/errors.js";
+import { createBuildLoader } from "../core/loader.js";
+import { renderSite } from "../core/site.js";
+/** The MCP SDK is optional: only people who run `vage mcp` install it. */
+const SDK = "@modelcontextprotocol/sdk";
+const INSTALL = `vage mcp needs the "${SDK}" package. Install it in your project with: npm install --save-dev ${SDK}`;
+/** Loads the SDK from the project first, then from wherever vagejs itself is installed. */
+async function loadSdk(root) {
+    for (const from of [path.join(root, "package.json"), import.meta.url]) {
+        try {
+            const req = createRequire(from);
+            const mcp = await import(pathToFileURL(req.resolve(`${SDK}/server/mcp.js`)).href);
+            const stdio = await import(pathToFileURL(req.resolve(`${SDK}/server/stdio.js`)).href);
+            return { McpServer: mcp.McpServer, StdioServerTransport: stdio.StdioServerTransport };
+        }
+        catch {
+            // try the next location
+        }
+    }
+    throw new VageError(INSTALL);
+}
+/** Published pages, drafts and scheduled pages, without writing anything. */
+export async function listPages(root) {
+    const loader = await createBuildLoader(root);
+    try {
+        const model = await renderSite(root, loader.load, { collectErrors: true });
+        return {
+            pages: model.pages.map((p) => ({
+                route: p.route,
+                source: p.source,
+                title: p.frontmatter.title,
+                description: p.frontmatter.description,
+                layout: p.frontmatter.layout ?? "default",
+                noindex: Boolean(p.meta.noindex),
+            })),
+            drafts: model.skippedDrafts,
+            scheduled: model.skippedScheduled.map(({ source, date }) => ({ source, date })),
+            errors: model.pageErrors,
+        };
+    }
+    finally {
+        await loader.close();
+    }
+}
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const text = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+/** Runs a tool; a failure (a broken layout, an invalid config) becomes a readable error result, without terminal colors. */
+const tool = (fn) => async () => {
+    try {
+        return text(await fn());
+    }
+    catch (err) {
+        // eslint-disable-next-line no-control-regex
+        const message = String(err?.message ?? err).replace(/\u001b\[[0-9;]*m/g, "");
+        return { isError: true, content: [{ type: "text", text: message }] };
+    }
+};
+/**
+ * `vage mcp`: an MCP server over stdio for the project at `root`. Every tool is
+ * read-only; approving links and deploying stay with people, through the CLI.
+ * stdout carries the protocol, so anything else that prints goes to stderr.
+ */
+export async function startMcpServer(root, options) {
+    root = path.resolve(root);
+    const sdk = await loadSdk(root);
+    if (!options.transport)
+        console.log = console.info = (...args) => console.error(...args);
+    const server = new sdk.McpServer({ name: "vagejs", version: options.version }, {
+        instructions: "Tools for a vagejs website project. Use vage_info for commands, settings and page fields; vage_check after every change (fix every error it reports; each finding names the file); vage_pages to see what exists; vage_links for outbound domains. Never approve link domains or deploy without the site owner: those stay CLI commands (npx vage links approve, npx vage deploy).",
+    });
+    server.registerTool("vage_info", { title: "Describe vagejs", description: "Commands, configuration options and page frontmatter fields, with their JSON Schemas (the same as `vage info --json`).", annotations: READ_ONLY }, tool(async () => options.info()));
+    server.registerTool("vage_check", { title: "Check the site", description: "Checks every page for broken links, missing titles and descriptions, structured data, accessibility basics and unapproved outbound links (the same as `vage check --json`). Writes nothing.", annotations: READ_ONLY }, tool(() => check(root)));
+    server.registerTool("vage_pages", { title: "List pages", description: "Every published page (route, source file, title, description, layout, noindex), the drafts and scheduled pages that are skipped, and pages that fail to render.", annotations: READ_ONLY }, tool(() => listPages(root)));
+    server.registerTool("vage_links", { title: "List outbound domains", description: "External domains the site links to, which pages link there, and whether each is approved in links.lock.json. Only the site owner approves new domains.", annotations: READ_ONLY }, tool(() => linkStatus(root)));
+    await server.connect(options.transport ?? new sdk.StdioServerTransport());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vagejs",
-  "version": "0.3.5",
+  "version": "0.5.0",
   "description": "A free static site generator for AI website development: Markdown pages with built-in SEO, llms.txt, checks, spam protection and safe deploys.",
   "keywords": [
     "static-site-generator",
@@ -57,6 +57,7 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^1.1.0",
+    "@modelcontextprotocol/sdk": "^1.32.2",
     "@types/jsdom": "^28.0.3",
     "@types/node": "^26.6.5",
     "@types/turndown": "^5.0.6",

package/templates/starter/AGENTS.md

@@ -16,21 +16,35 @@ This website uses **vagejs** (pre-release). Only the features listed here exist
 Add `--json` to `npx vage build`, `check` or `audit` for machine-readable output (`{ ok: false, error }` on failure).
 Run `npm run check` after every change and fix all errors before finishing.
 
+## Windows
+
+vagejs is tested on Windows on every change.
+
+- Node.js **22.12 or newer** is needed. Check with `node --version` in a new PowerShell or Command Prompt window.
+- The `npm` and `npx` commands in this file work in PowerShell and Command Prompt. In Command Prompt, leave out any `# …` notes after a command: it doesn't treat `#` as a comment.
+- Windows usually saves files with **CRLF** line endings. vagejs handles them; don't convert line endings.
+- If a browser shows **HTTP 431** on `localhost`, open the direct `[::1]` or `127.0.0.1` address that `npm start` and `npm run dev` print.
+
 ## Machine-readable reference
 
 `npx vage info --json` prints every command and option plus JSON Schemas for `vage.config.ts` and page frontmatter. Prefer it over guessing.
 
+**MCP server (optional):** `npx vage mcp` runs an MCP server over stdio with four read-only tools: `vage_info`, `vage_check`, `vage_pages` and `vage_links`. It needs `npm install --save-dev @modelcontextprotocol/sdk` in the project. For Claude Code, run in the project folder: `claude mcp add --transport stdio --scope project vagejs -- npx -p vagejs vage mcp` (saved in `.mcp.json`). Other assistants: `{ "mcpServers": { "vagejs": { "command": "npx", "args": ["-p", "vagejs", "vage", "mcp", "--root", "/absolute/path/to/the/site"] } } }`. `-p vagejs` makes npx run the vagejs installed in the project, and never a different package that happens to be called `vage`. Approving link domains and deploying are not MCP tools; they stay CLI commands the site owner approves. Layouts must not write to `process.stdout` directly: in MCP mode stdout carries the protocol (vagejs moves `console.log` to stderr).
+
 ## Recipes
 
-- **Add a page:** create `src/pages/<slug>.md` with `title` and `description` frontmatter; link to it as `/<slug>/` (trailing slash).
-- **Add a blog post:** `src/pages/blog/<slug>.md`; it appears on `/blog/` automatically (`src/layouts/blog.ts`). For Article data add `type: article`, plus `author` / `datePublished` only if the owner provided them.
+- **Add a page:** `npx vage new page <slug>` (folders allowed: `docs/setup`; options `--title`, `--description`) creates `src/pages/<slug>.md` as a draft with valid frontmatter, or create the file yourself with `title` and `description`. Link to it as `/<slug>/` (trailing slash). Remove `draft: true` when it's ready, then run `npm run check`.
+- **Add a blog post:** `npx vage new post "<Title>"` creates `src/pages/blog/<slug>.md` as a draft with `type: article` and today's `datePublished` (`--date`, `--under <folder>`, and `--author` only with a real name from the owner). It appears on `/blog/` automatically (`src/layouts/blog.ts`) once `draft: true` is removed.
 - **Add a layout:** `src/layouts/<name>.ts`, then `layout: <name>` in frontmatter. Keep `<html lang>`, one `<title>` and `</head>`.
 - **List pages (blog index, "latest posts", a sidebar):** in a layout, `collection(pages, { under: "/blog/", sort: "date" })` from `vagejs`. Never keep a hand-written list of pages.
 - **Give a layout its own frontmatter fields:** `export const frontmatter = z.object({ ... })` in the layout (`import { z } from "vagejs"`). Pages using it are then checked strictly: unknown or mistyped fields fail the build.
-- **Add an image:** put it in `public/images/` and write `![Describe the image](/images/name.jpg)`. Width and height are filled in from the file; write real alt text. For resized WebP copies, the owner can turn on `images: { optimize: true }` (needs `npm install --save-dev sharp`). Only images in page content are optimized, not images a layout writes.
+- **Add an image:** put it in `public/images/` and write `![Describe the image](/images/name.jpg)`. Width and height are filled in from the file; write real alt text. For resized WebP copies, the owner can turn on `images: { optimize: true }` (needs `npm install --save-dev sharp`), and `avif: true` for AVIF copies offered first through `<picture>`. Only images in page content are optimized, not images a layout writes.
 - **Order a menu or sidebar:** set `order:` (lower first) and optionally a short `navTitle:` in each page's frontmatter (shown as `p.label`), then build the menu in a layout with `tree(pages, "/docs/")`. For previous/next links in the same order use `neighbors(flatten(tree(pages, "/docs/")), page.route)`. For a flat section, `collection(pages, { under: "/docs/", sort: "order", includeIndex: true })` works too. `breadcrumbs(pages, page.route)` gives the trail from the home page.
 - **Add an RSS feed for the blog:** `seo: { feeds: [{ under: "/blog/" }] }` in `vage.config.ts` writes `/blog/feed.xml`, newest `datePublished` first (undated posts last, without a date).
 - **Help AI tools read the site:** `seo: { markdownCopies: true }` publishes a Markdown copy of every listed page (`/docs/cli/` becomes `/docs/cli.md`), converted from the page's `<main>`, so it contains exactly what the page shows (including content a layout builds from frontmatter), and `llms.txt` links to them. In layouts, add `data-vage-copy="skip"` to repeated extras such as share links or a call to action to leave them out of the copy. On Cloudflare, each copy gets a canonical `Link` header pointing to its page. `seo: { lastmod: "git" }` dates the sitemap from git history (needs full history in CI: `fetch-depth: 0`).
+- **Link to a section:** every `##` and `###` heading gets an id from its text (`## Quick start` becomes `id="quick-start"`), so link to `/docs/setup/#quick-start`. `npm run check` warns when a `#section` matches no id on the target page (`link-fragment`). Write `<h2 id="...">` in Markdown for an id of your own. Ids are only kept unique within the page content, so avoid headings that repeat an id the layout uses (such as `main`); `markdown: { headingIds: false }` turns automatic ids off.
+- **Schedule a post:** give it a future `datePublished` (and no `draft: true`). It stays out of builds, lists, feeds and the sitemap until a build on or after that day; `npm run build` lists it as `(scheduled for <date>, skipped)`. A date goes live on that day in the build machine's time zone (UTC on most CI); use a datetime such as `2026-11-01T09:00:00+05:30` for an exact time. Nothing rebuilds the site by itself: the owner needs a deploy on that day (for example a scheduled GitHub Actions workflow). `vage indexnow --changed-since` skips drafts and scheduled pages; once the page is live, submit it with `--urls`.
+- **Tag pages:** `tags: [SEO, AI]` in frontmatter. Each tag gets a page at `/tags/<tag>/` listing its pages, newest first (`tags: { layout: "<name>" }` picks its layout, `tags: { pages: false }` turns them off). In layouts, `collection(pages, { tag: "SEO" })` picks tagged pages and `tagList(pages)` lists every tag with its `route` and `count`. Tags are matched by their address, so "SEO" and "seo" are the same tag.
 - **Rename a page:** move the file, then add `redirects: { "/old-slug/": "/new-slug/" }` to `vage.config.ts`.
 - **Hide a page from search:** `noindex: true` (it stays published). To unpublish, use `draft: true` or delete it.
 - **AI crawler policy:** set `seo.robots.aiTraining` / `aiSearch` only on the owner's instruction.
@@ -64,10 +78,11 @@ canonical: /other/       # canonical override (path or absolute URL); page then
 image: /images/og.png    # og:image (made absolute using `site`)
 type: article            # og:type + Article JSON-LD (default: website)
 author: Jane Doe         # Article author
-datePublished: 2026-01-31
+datePublished: 2026-01-31  # a future date schedules the page: it's skipped until a build on or after that day
 dateModified: 2026-02-15 # also the sitemap <lastmod> (otherwise datePublished, or git with seo.lastmod: "git")
 order: 2                 # position in menus built with tree() or sort: "order" (lower first)
 navTitle: Pricing        # shorter label for menus and breadcrumbs (PageSummary.label)
+tags: [SEO, AI]          # each tag gets a page at /tags/<tag>/
 ---
 ```
 
@@ -88,7 +103,7 @@ Hacked sites are usually abused for hidden spam links and doorway pages. vagejs
 
 HTML inside Markdown is sanitized: scripts, event handlers, `javascript:` links, iframes and forms are removed. Embeds (e.g. video) belong in a layout, which is trusted code. The owner can trust all authors with `markdown: { html: "allow" }`; don't set that yourself. Values inside `{ }` in frontmatter that contain a comma or colon must be quoted; `vage check` warns about empty values (`frontmatter-empty`). Never put secrets in `public/` (it is published, and the build refuses secret-looking files and symlinks there). `npm run dev -- --host` exposes the dev server to your network; it serves only pages and `public/`, but use it only on trusted networks.
 
-With `deploy.target: "cloudflare-workers"` or `"cloudflare-pages"`, the build writes `_headers` with security headers and a Content-Security-Policy computed from the pages (inline scripts are allowed by hash). Don't use inline event handlers (`onclick=`); add sources the site really needs to `security.cspSources`.
+With `deploy.target: "cloudflare-workers"`, `"cloudflare-pages"` or `"netlify"`, the build writes `_headers` with security headers and a Content-Security-Policy computed from the pages (inline scripts are allowed by hash). Don't use inline event handlers (`onclick=`); add sources the site really needs to `security.cspSources`.
 
 ## Layouts
 
@@ -113,14 +128,14 @@ From the published pages and config (never from `public/`; a hand-written `publi
 - `sitemap.xml`: indexable, self-canonical, non-draft pages. Needs `site`.
 - `llms.txt` (+ `llms-full.txt` with `llmsTxt: { full: true }`): same pages. An emerging convention; not a guarantee that AI tools use it.
 - Redirects: `redirects: { "/old/": "/new/" }` become noindex meta-refresh pages (dev server answers 301).
-- With `seo.feeds`: `<section>/feed.xml` (RSS). With `seo.markdownCopies`: `/<path>.md` copies of listed pages. With `images.optimize`: resized images in `/_vage/img/`.
+- Tag pages at `/tags/<tag>/` for every tag in frontmatter (`tags.pages`). With `seo.feeds`: `<section>/feed.xml` (RSS). With `seo.markdownCopies`: `/<path>.md` copies of listed pages. With `images.optimize`: resized images in `/_vage/img/`.
 
 
 ## Config
 
 `vage.config.ts` keys: `site` (origin only, no path), `title`, `description`, `lang`,
-`seo: { robots, sitemap, llmsTxt, structuredData, feeds, markdownCopies, lastmod }`, `redirects`, `markdown`,
-`images: { optimize, widths, quality, sizes }`, `performance`, `deploy: { target, cloudflareWorker, cloudflareProject }`,
+`seo: { robots, sitemap, llmsTxt, structuredData, feeds, markdownCopies, lastmod }`, `redirects`, `markdown: { html, inlineStyles, headingIds }`, `tags: { pages, layout }`,
+`images: { optimize, widths, quality, sizes }`, `performance`, `deploy: { target, cloudflareWorker, cloudflareProject, netlifySite }`,
 `security: { headers, csp, cspSources, outboundLinks, spamPatterns }`, `integrations`, `guidelines`.
 Keys not in this list are an error; `npx vage info --json` has the full schema.
 
@@ -140,13 +155,14 @@ Always ask the site owner before publishing or deploying. Show them the plan fir
 - `npx vage deploy` with `deploy: { target: "cloudflare-workers", cloudflareWorker: "<name>" }`: Cloudflare's current way to host static sites. Uploads a new version and switches all traffic to it, so custom domains stay up. For custom domains or routes, the owner adds a `wrangler.jsonc` (vagejs then uses it). Config redirects become real 301s (`_redirects`).
 - `npx vage deploy --target cloudflare-pages --project <name>`: older Cloudflare Pages projects. Non-production branches get preview URLs. Cloudflare now turns new Pages projects into Workers; use `cloudflare-workers` for new sites.
 - Both Cloudflare targets report success only when Wrangler succeeds and the site responds. They need `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` or `npx wrangler login`.
+- `npx vage deploy` with `deploy: { target: "netlify", netlifySite: "<site name or ID>" }`: uploads `dist/` to the Netlify site's production deploy (create the site in Netlify first). The build writes Netlify's `_headers` (security headers) and `_redirects` (config redirects as forced 301s). It reports success only when netlify-cli succeeds and the site responds. Needs `NETLIFY_AUTH_TOKEN` or `npx netlify-cli login`.
 - `npx vage deploy`: GitHub Pages (default target). Adds `.github/workflows/deploy.yml` (if missing), publishes, enables Pages via `gh` if needed, then waits for the Actions run. It says "deployed" only when GitHub reports success.
 
 After deploying, `npx vage indexnow --changed-since HEAD~1` (needs `integrations.indexNow.key`) tells IndexNow search engines about changed pages. It's a hint, not a guarantee of indexing; ask the owner first.
 
 GitHub Pages needs a custom domain or a `<user>.github.io` repository, because vagejs does not support base paths yet; `vage deploy` stops before pushing when the site would land in a subfolder.
 
-Other static hosts (Vercel, Netlify and the like) work without a vagejs deploy command: build command `npm run build`, output folder `dist`, no framework preset. Config redirects become small forwarding pages there, and the `_headers` security headers apply only on Cloudflare.
+Other static hosts (Vercel and the like) work without a vagejs deploy command: build command `npm run build`, output folder `dist`, no framework preset. Config redirects become small forwarding pages there, and the `_headers` security headers apply only on Cloudflare and Netlify.
 `.github/workflows/ci.yml` runs check, build and audit on every push and PR, and uploads `dist/` as a downloadable preview artifact.
 
 ## Analytics and search reports
@@ -166,7 +182,7 @@ Off unless configured in `vage.config.ts` under `integrations`. Ask the site own
 
 ## Not implemented yet
 
-Bing Webmaster Tools API, Netlify/Vercel adapters, CMS content sources, multi-language sites, base paths, AVIF images. Do not use or document them as available. A passing `check` does not guarantee indexing, rankings or AI citations.
+Bing Webmaster Tools API, a Vercel adapter, CMS content sources, multi-language sites, base paths. Do not use or document them as available. A passing `check` does not guarantee indexing, rankings or AI citations.
 
 ## Favicon
 

package/templates/starter/package.json

@@ -12,6 +12,6 @@
     "preview": "vage preview"
   },
   "devDependencies": {
-    "vagejs": "^0.3.5"
+    "vagejs": "^0.5.0"
   }
 }