vagejs 0.3.0 → 0.3.2

package/README.md

@@ -29,10 +29,10 @@ Requires **Node.js 22.12 or newer**.
 npm create vagejs@latest my-site
 cd my-site
 npm install
-npm run dev
+npm start
 ```
 
-Open the URL it prints. Edit `src/pages/index.md` and the browser reloads.
+`npm start` opens the site in your browser. Edit `src/pages/index.md` and the page reloads. (`npm run dev` does the same without opening a browser, and prints the address.)
 
 ## Using vagejs
 
@@ -74,7 +74,7 @@ Images in `public/` used as `![Alt text](/images/photo.jpg)` get their `width` a
 
 - `order:` and `navTitle:` in frontmatter, with `tree()`, `breadcrumbs()` and `neighbors()` in layouts, build sidebars, breadcrumbs and previous/next links.
 - `seo: { feeds: [{ under: "/blog/" }] }` writes an RSS feed at `/blog/feed.xml`.
-- `seo: { markdownCopies: true }` publishes a Markdown copy of every listed page (`/docs/cli.md`) for AI tools, without comments or raw HTML; `seo: { lastmod: "git" }` dates the sitemap from git history (CI needs `fetch-depth: 0`).
+- `seo: { markdownCopies: true }` publishes a Markdown copy of every listed page (`/docs/cli.md`) for AI tools, made from the page's `<main>`, without comments or raw HTML (layouts leave extras out with `data-vage-copy="skip"`); `seo: { lastmod: "git" }` dates the sitemap from git history (CI needs `fetch-depth: 0`).
 
 ### Write a layout
 
@@ -103,7 +103,8 @@ export default layout;
 
 | Command | What it does |
 | --- | --- |
-| `npm run dev` | Dev server with live reload |
+| `npm start` | Dev server with live reload, opened in your browser |
+| `npm run dev` | The same, without opening a browser; prints the address (and a direct `[::1]` or `127.0.0.1` address to use if the browser shows HTTP 431) |
 | `npm run check` | Links, SEO, structured data and basic accessibility; writes nothing |
 | `npm run build` | Static site in `dist/`, plus `robots.txt`, `sitemap.xml`, `llms.txt` |
 | `npm run audit` | Page-weight budgets and automated accessibility (`-- --lighthouse` adds Lighthouse) |

package/dist/cli/index.js

@@ -9,6 +9,7 @@ import { VageError } from "../core/errors.js";
 import { assertBranchName, assertCloudflareProject, assertVageSpec, assertWorkerName } from "../core/validate.js";
 import { startDevServer } from "../dev/server.js";
 import { startPreviewServer } from "../dev/preview.js";
+import { directUrl, printUrls } from "../dev/listen.js";
 import { createInterface } from "node:readline/promises";
 import { createProject } from "./create.js";
 import { frameworkInfo } from "./info.js";
@@ -30,10 +31,14 @@ cli
     .option("--root <dir>", "Project root", { default: "." })
     .option("--port <port>", "Port (fails if taken; default picks a free port from 5173)")
     .option("--host [host]", "Expose on the network")
+    .option("--open", "Open the site in your browser (at the direct address, so localhost cookies can't cause HTTP 431)")
     .action((opts) => run(opts, async () => {
     const server = await startDevServer(opts.root, { port: parsePort(opts.port), host: opts.host });
-    console.log(`vagejs dev server running at ${server.resolvedUrls?.local[0]}`);
-    server.resolvedUrls?.network.forEach((url) => console.log(`  network: ${url}`));
+    const direct = directUrl(server.httpServer?.address());
+    printUrls("vagejs dev server", server.resolvedUrls?.local[0], direct, server.resolvedUrls?.network);
+    const target = direct ?? server.resolvedUrls?.local[0] ?? server.resolvedUrls?.network[0];
+    if (opts.open && target)
+        openBrowser(target);
 }));
 cli
     .command("build", "Build the static site into dist/")
@@ -128,10 +133,14 @@ cli
     .option("--root <dir>", "Project root", { default: "." })
     .option("--port <port>", "Port (fails if taken; default picks a free port from 4173)")
     .option("--host [host]", "Expose on the network")
+    .option("--open", "Open the site in your browser")
     .action((opts) => run(opts, async () => {
     const server = await startPreviewServer(opts.root, { port: parsePort(opts.port), host: opts.host });
-    console.log(`vagejs preview running at ${server.resolvedUrls?.local[0]}`);
-    server.resolvedUrls?.network.forEach((url) => console.log(`  network: ${url}`));
+    const direct = directUrl(server.httpServer?.address());
+    printUrls("vagejs preview", server.resolvedUrls?.local[0], direct, server.resolvedUrls?.network);
+    const target = direct ?? server.resolvedUrls?.local[0] ?? server.resolvedUrls?.network[0];
+    if (opts.open && target)
+        openBrowser(target);
 }));
 cli
     .command("info", "Describe commands, config and frontmatter (use --json for agents)")
@@ -493,7 +502,16 @@ try {
     }
 }
 catch (err) {
-    fail(err, Boolean(cli.options.json));
+    fail(usageError(err), Boolean(cli.options.json));
+}
+/** Mistakes in the command line itself (unknown option, extra value) get a clear message, not a stack trace. */
+function usageError(err) {
+    if (err?.name !== "CACError")
+        return err;
+    const name = cli.matchedCommand?.name;
+    const help = name ? `vage ${name} --help` : "vage --help";
+    const lists = /^Unused args/.test(err.message) ? ' Options that take a list want one comma-separated value, e.g. --urls "/a/,/b/".' : "";
+    return new VageError(`${err.message}.${lists} See "${help}".`);
 }
 async function run(opts, fn) {
     try {

package/dist/cli/info.js

@@ -61,7 +61,7 @@ export function frameworkInfo(cli, version) {
         },
         features: {
             feeds: 'seo.feeds: [{ under: "/blog/" }] writes /blog/feed.xml (RSS 2.0) and links it from that section\'s pages',
-            markdownCopies: "seo.markdownCopies: true publishes /<path>.md copies of listed pages, linked with rel=alternate type=text/markdown",
+            markdownCopies: "seo.markdownCopies: true publishes /<path>.md copies of listed pages, made from each page's <main> and linked with rel=alternate type=text/markdown; layouts mark repeated extras (share links, calls to action) with data-vage-copy=\"skip\". On Cloudflare, _headers gives each copy a canonical Link header to its page",
             lastmod: 'seo.lastmod: "git" takes sitemap <lastmod> from each page\'s last commit (dateModified wins; skipped in shallow clones)',
             images: 'images: { optimize: true } (needs the sharp package) makes resized WebP copies of content images in /_vage/img/ and adds srcset/sizes',
             navigation: "frontmatter order and navTitle; helpers tree(), breadcrumbs(), neighbors(); PageSummary.label",

package/dist/core/config.js

@@ -31,11 +31,11 @@ const robotsSchema = z.strictObject({
     aiTraining: z
         .enum(["allow", "disallow"])
         .optional()
-        .describe("Groups for documented AI training crawlers (GPTBot, ClaudeBot, Google-Extended). Unset: the * group applies."),
+        .describe("Groups for documented AI training crawlers (GPTBot, ClaudeBot, Google-Extended, Applebot-Extended). Google-Extended also covers grounding in Gemini Apps and Vertex AI. Unset: the * group applies."),
     aiSearch: z
         .enum(["allow", "disallow"])
         .optional()
-        .describe("Groups for documented AI search crawlers (OAI-SearchBot, Claude-SearchBot). Unset: the * group applies."),
+        .describe("Groups for documented AI search crawlers (OAI-SearchBot, Claude-SearchBot, PerplexityBot). Unset: the * group applies."),
 });
 const seoSchema = z.strictObject({
     robots: toggle(robotsSchema).describe("Generate robots.txt (true/false or options)."),

package/dist/core/site.js

@@ -3,10 +3,10 @@ import path from "node:path";
 import { llmsFullTxt, llmsTxt } from "../discovery/llms.js";
 import { feedPath, rssFeed } from "../discovery/feed.js";
 import { gitPageDates } from "../discovery/git-dates.js";
-import { htmlToMarkdown, markdownCopy, markdownCopyPath } from "../discovery/markdown-copy.js";
+import { copySource, htmlToMarkdown, markdownCopy, markdownCopyPath } from "../discovery/markdown-copy.js";
 import { robotsTxt } from "../discovery/robots.js";
 import { SITEMAP_URL_LIMIT, sitemapXml } from "../discovery/sitemap.js";
-import { headersFile } from "../deploy/headers.js";
+import { copyCanonicalsFit, headersFile } from "../deploy/headers.js";
 import { cloudflareRedirects } from "../deploy/redirects.js";
 import { findSecrets } from "../deploy/secrets.js";
 import { rulePack } from "../guidelines/pack.js";
@@ -73,7 +73,7 @@ export async function renderSite(root, load, options = {}) {
     const markdown = new Map();
     if (site.seo.markdownCopies || (site.seo.llmsTxt && site.seo.llmsTxt.full)) {
         for (const p of listedPages(model))
-            markdown.set(p.route, await htmlToMarkdown(p.content, { route: p.route, origin: site.site }));
+            markdown.set(p.route, await htmlToMarkdown(await copySource(p.html, p.content), { route: p.route, origin: site.site }));
     }
     model.redirects = buildRedirects(site, new Set(model.pages.map((p) => p.route)));
     addDiscoveryFiles(root, model, markdown);
@@ -140,7 +140,12 @@ function addDiscoveryFiles(root, model, markdown) {
         generate("_redirects", () => cloudflareRedirects(model.redirects));
     if (cloudflare && site.security.headers) {
         const html = [...model.pages, ...(model.notFound ? [model.notFound] : []), ...model.redirects].map((p) => p.html);
-        generate("_headers", () => headersFile(html, site));
+        // 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)) : [];
+        if (!copyCanonicalsFit(copies.length)) {
+            warnings.push(`_headers: ${copies.length} Markdown copies need more header rules than Cloudflare allows, so they're published without a canonical Link header.`);
+        }
+        generate("_headers", () => headersFile(html, site, copies));
     }
     if (site.seo.llmsTxt) {
         if (!site.title) {

package/dist/deploy/headers.d.ts

@@ -7,5 +7,16 @@ import type { SiteConfig } from "../core/config.js";
  * any https origin so ordinary sites don't break.
  */
 export declare function contentSecurityPolicy(pagesHtml: string[], site: SiteConfig): string;
-/** Cloudflare Pages / Netlify `_headers` for every path. */
-export declare function headersFile(pagesHtml: string[], site: SiteConfig): string;
+/**
+ * Markdown copies can name their HTML page as canonical with one rule each, while the
+ * file stays within Cloudflare's rule limit (the first rule covers every path).
+ */
+export declare const copyCanonicalsFit: (copies: number) => boolean;
+/**
+ * Cloudflare Pages / Netlify `_headers` for every path, plus a canonical Link header on
+ * each Markdown copy (`copies`: its path and its page's URL) when they fit.
+ */
+export declare function headersFile(pagesHtml: string[], site: SiteConfig, copies?: {
+    path: string;
+    canonical: string;
+}[]): string;

package/dist/deploy/headers.js

@@ -3,7 +3,7 @@ import { parse } from "node-html-parser";
 import { VageError } from "../core/errors.js";
 import { ruleData } from "../guidelines/pack.js";
 // https://developers.cloudflare.com/pages/configuration/headers/ (rule pack "cloudflare.headers", "csp.providers")
-const { maxLineLength } = ruleData("cloudflare.headers");
+const { maxLineLength, maxRules } = ruleData("cloudflare.headers");
 const PROVIDERS = ruleData("csp.providers");
 const EXECUTABLE = /^(|module|text\/javascript|application\/javascript)$/i;
 /**
@@ -87,8 +87,16 @@ export function contentSecurityPolicy(pagesHtml, site) {
     ];
     return directives.join("; ");
 }
-/** Cloudflare Pages / Netlify `_headers` for every path. */
-export function headersFile(pagesHtml, site) {
+/**
+ * Markdown copies can name their HTML page as canonical with one rule each, while the
+ * file stays within Cloudflare's rule limit (the first rule covers every path).
+ */
+export const copyCanonicalsFit = (copies) => copies + 1 <= maxRules;
+/**
+ * Cloudflare Pages / Netlify `_headers` for every path, plus a canonical Link header on
+ * each Markdown copy (`copies`: its path and its page's URL) when they fit.
+ */
+export function headersFile(pagesHtml, site, copies = []) {
     const lines = ["# Generated by vagejs (security in vage.config.ts)", "/*", "  X-Content-Type-Options: nosniff", "  Referrer-Policy: strict-origin-when-cross-origin", "  X-Frame-Options: SAMEORIGIN", "  Permissions-Policy: camera=(), microphone=(), geolocation=()"];
     if (site.security.csp !== "off") {
         const name = site.security.csp === "report-only" ? "Content-Security-Policy-Report-Only" : "Content-Security-Policy";
@@ -99,5 +107,9 @@ export function headersFile(pagesHtml, site) {
         throw new VageError(`The generated Content-Security-Policy is ${tooLong.length} characters; _headers lines are limited to ${maxLineLength}. ` +
             "Reduce distinct inline scripts/styles (move them to files in public/), or set security.csp to \"off\".");
     }
+    if (copyCanonicalsFit(copies.length)) {
+        for (const c of copies)
+            lines.push(c.path, `  Link: <${c.canonical}>; rel="canonical"`);
+    }
     return `${lines.join("\n")}\n`;
 }

package/dist/dev/listen.d.ts

@@ -1,6 +1,17 @@
+import type { AddressInfo } from "node:net";
 export interface ServeOptions {
     port?: number;
     host?: string | boolean;
 }
 /** Runs a Vite listen() call and turns a port conflict into an actionable message. */
 export declare function listenOrExplain<T>(listen: () => Promise<T>, port: number | undefined): Promise<T>;
+/**
+ * The address the server is really listening on, when it's a loopback address, e.g.
+ * http://[::1]:5173/ or http://127.0.0.1:5173/. Browsers keep cookies per host name, so
+ * this address doesn't carry the cookies other projects left on "localhost" (the usual
+ * cause of HTTP 431). A server on every interface (--host) is reached at 127.0.0.1;
+ * a specific network address has no direct loopback address.
+ */
+export declare function directUrl(address: AddressInfo | string | null | undefined): string | undefined;
+/** Prints where the server runs: the localhost URL, the direct address, and network URLs. */
+export declare function printUrls(label: string, local: string | undefined, direct: string | undefined, network?: string[]): void;

package/dist/dev/listen.js

@@ -11,3 +11,29 @@ export async function listenOrExplain(listen, port) {
         throw err;
     }
 }
+/**
+ * The address the server is really listening on, when it's a loopback address, e.g.
+ * http://[::1]:5173/ or http://127.0.0.1:5173/. Browsers keep cookies per host name, so
+ * this address doesn't carry the cookies other projects left on "localhost" (the usual
+ * cause of HTTP 431). A server on every interface (--host) is reached at 127.0.0.1;
+ * a specific network address has no direct loopback address.
+ */
+export function directUrl(address) {
+    if (!address || typeof address === "string")
+        return undefined;
+    if (address.address === "::1")
+        return `http://[::1]:${address.port}/`;
+    if (address.address === "0.0.0.0" || address.address === "::")
+        return `http://127.0.0.1:${address.port}/`;
+    if (address.address.startsWith("127."))
+        return `http://${address.address}:${address.port}/`;
+    return undefined;
+}
+/** Prints where the server runs: the localhost URL, the direct address, and network URLs. */
+export function printUrls(label, local, direct, network = []) {
+    console.log(`${label} running at ${local ?? direct ?? network[0]}`);
+    if (direct && direct !== local)
+        console.log(`  same server: ${direct} (use this if the browser shows HTTP 431)`);
+    for (const url of network)
+        console.log(`  network: ${url}`);
+}

package/dist/discovery/markdown-copy.d.ts

@@ -1,5 +1,11 @@
 /** "/" -> "index.md", "/docs/cli/" -> "docs/cli.md". */
 export declare function markdownCopyPath(route: string): string;
+/**
+ * The part of a rendered page the copy is made from: the inside of its one `<main>`, so
+ * content a layout builds from frontmatter (FAQ answers, post lists) is included. Pages
+ * without exactly one `<main>` fall back to the Markdown body.
+ */
+export declare function copySource(pageHtml: string, content: string): Promise<string>;
 /**
  * The page as Markdown, converted from its rendered, sanitized HTML: the copy contains
  * exactly what the page shows (no comments, no raw HTML the sanitizer removed, the same
@@ -9,5 +15,9 @@ export declare function htmlToMarkdown(html: string, options: {
     route: string;
     origin?: string;
 }): Promise<string>;
-/** The copy: the page's own H1 (or the title), the summary, then the content. */
+/**
+ * The copy: the page's own H1 (or the title), the summary, then the content. The H1 is
+ * moved to the top even when a layout puts something before it, but never taken from
+ * inside a code block.
+ */
 export declare function markdownCopy(title: string, description: string | undefined, markdown: string): string;

package/dist/discovery/markdown-copy.js

@@ -58,6 +58,17 @@ function converter() {
     service = td;
     return td;
 }
+/**
+ * The part of a rendered page the copy is made from: the inside of its one `<main>`, so
+ * content a layout builds from frontmatter (FAQ answers, post lists) is included. Pages
+ * without exactly one `<main>` fall back to the Markdown body.
+ */
+export async function copySource(pageHtml, content) {
+    jsdom ??= await import("jsdom");
+    // Parsed as HTML (scripts don't run), so "<main>" text in scripts, comments or attributes doesn't count.
+    const mains = new jsdom.JSDOM(pageHtml).window.document.querySelectorAll("main");
+    return mains.length === 1 ? mains[0].innerHTML : content;
+}
 /**
  * The page as Markdown, converted from its rendered, sanitized HTML: the copy contains
  * exactly what the page shows (no comments, no raw HTML the sanitizer removed, the same
@@ -81,8 +92,13 @@ export async function htmlToMarkdown(html, options) {
         }
     };
     // Hidden content isn't on the page for visitors, so it isn't in the copy either.
-    for (const el of template.content.querySelectorAll("[hidden], svg, math"))
+    // Layouts mark repeated extras (share links, calls to action) with data-vage-copy="skip";
+    // aria-hidden parts are decoration that screen readers skip too.
+    for (const el of template.content.querySelectorAll('[hidden], svg, math, [aria-hidden="true"], [data-vage-copy="skip"]'))
         el.remove();
+    // A heading split over two lines with <br> stays one Markdown heading.
+    for (const br of template.content.querySelectorAll("h1 br, h2 br, h3 br, h4 br, h5 br, h6 br"))
+        br.replaceWith(" ");
     for (const a of template.content.querySelectorAll("a[href]")) {
         const href = a.getAttribute("href").trim();
         // Script and data URLs never become links in the copy (trusted HTML can contain them).
@@ -103,10 +119,34 @@ export async function htmlToMarkdown(html, options) {
     wrapper.append(template.content);
     return converter().turndown(wrapper).trim();
 }
-/** The copy: the page's own H1 (or the title), the summary, then the content. */
+/**
+ * The copy: the page's own H1 (or the title), the summary, then the content. The H1 is
+ * moved to the top even when a layout puts something before it, but never taken from
+ * inside a code block.
+ */
 export function markdownCopy(title, description, markdown) {
-    const own = /^#\s+(.+?)\s*(?:\n+|$)/.exec(markdown);
-    const heading = `# ${own ? own[1] : title}`;
-    const rest = own ? markdown.slice(own[0].length) : markdown;
+    const lines = markdown.split("\n");
+    let fence = "";
+    let at = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const run = /^(`{3,}|~{3,})/.exec(line)?.[1];
+        if (fence) {
+            if (run && run[0] === fence[0] && run.length >= fence.length && !line.slice(run.length).trim())
+                fence = "";
+        }
+        else if (run) {
+            fence = run;
+        }
+        else if (/^#[ \t]+\S/.test(line)) {
+            at = i;
+            break;
+        }
+    }
+    const heading = `# ${at >= 0 ? lines[at].replace(/^#[ \t]+/, "").trim() : title}`;
+    let next = at + 1;
+    while (at >= 0 && next < lines.length && !lines[next].trim())
+        next++; // and the blank lines after it
+    const rest = at >= 0 ? [...lines.slice(0, at), ...lines.slice(next)].join("\n") : markdown;
     return `${heading}\n\n${description ? `> ${description}\n\n` : ""}${rest.trim()}\n`;
 }

package/dist/guidelines/rule-pack.json

@@ -1,6 +1,6 @@
 {
-    "version": "2026.10.1",
-    "released": "2026-10-23",
+    "version": "2026.10.2",
+    "released": "2026-10-24",
     "sources": [
         {
             "id": "google-search-essentials",
@@ -274,6 +274,14 @@
             "url": "https://docs.perplexity.ai/guides/bots",
             "category": "ai-crawlers",
             "cadence": "weekly"
+        },
+        {
+            "id": "apple-applebot",
+            "provider": "Apple",
+            "title": "About Applebot (incl. Applebot-Extended)",
+            "url": "https://support.apple.com/en-us/119829",
+            "category": "ai-crawlers",
+            "cadence": "weekly"
         }
     ],
     "rules": [
@@ -284,7 +292,9 @@
             "sources": [
                 "openai-bots",
                 "anthropic-crawlers",
-                "google-crawlers"
+                "google-crawlers",
+                "perplexity-bots",
+                "apple-applebot"
             ],
             "implementedIn": [
                 "src/discovery/crawlers.ts",
@@ -321,6 +331,18 @@
                         "provider": "Google",
                         "purpose": "training",
                         "source": "google-crawlers"
+                    },
+                    {
+                        "token": "PerplexityBot",
+                        "provider": "Perplexity",
+                        "purpose": "search",
+                        "source": "perplexity-bots"
+                    },
+                    {
+                        "token": "Applebot-Extended",
+                        "provider": "Apple",
+                        "purpose": "training",
+                        "source": "apple-applebot"
                     }
                 ]
             }
@@ -603,7 +625,8 @@
                 "src/deploy/headers.ts"
             ],
             "data": {
-                "maxLineLength": 2000
+                "maxLineLength": 2000,
+                "maxRules": 100
             }
         },
         {
@@ -705,6 +728,13 @@
             "summary": "Add crawlers.probes (search and AI crawler user agents and tokens for vage verify's crawlability check) and the Perplexity crawler source. Full user-agent strings copied verbatim on 2026-10-23 for Googlebot, GPTBot, ChatGPT-User, PerplexityBot and Perplexity-User; OAI-SearchBot, Anthropic's crawlers and bingbot are recorded by token (Anthropic's page lists only tokens, Bing's page couldn't be read, and OAI-SearchBot's full string couldn't be copied verbatim). No existing rule changed.",
             "reviewedBy": "Venkatesh A G E",
             "contentHash": "4d88418eb0b5425da970a1a30218a097783e117ce65376171d9a7f3ab7d9f658"
+        },
+        {
+            "version": "2026.10.2",
+            "date": "2026-10-24",
+            "summary": "robots.ai-crawlers: add PerplexityBot (search; Perplexity says it surfaces and links sites in its search results and is not used for foundation-model training) and Applebot-Extended (training; Apple says it does not crawl and only controls use of Applebot-crawled data for training its generative models). Google-Extended stays under training; its source also covers grounding in Gemini Apps and Vertex AI, which the docs now state. Perplexity-User is excluded as a user-initiated fetcher. CCBot and cohere-ai not added: no provider documentation describing them as AI-training robots.txt tokens was found. Checked against the cited sources on 2026-10-24. cloudflare.headers: record the documented limit of 100 rules as data (maxRules), used to add a canonical Link header to each Markdown copy only when the _headers file stays within it.",
+            "reviewedBy": "Venkatesh A G E",
+            "contentHash": "6b1d977ca79843dab0f6b03dc8b3448ca451eafb037bc6af112165fb5c1035c1"
         }
     ]
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vagejs",
-  "version": "0.3.0",
-  "description": "AI-native, static-first web framework: Markdown sites with built-in SEO, llms.txt, audits, security and safe deploys.",
+  "version": "0.3.2",
+  "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",
     "ssg",
@@ -9,9 +9,9 @@
     "seo",
     "llms-txt",
     "ai-agents",
-    "vite",
-    "cli",
-    "web-framework"
+    "agents-md",
+    "claude-code",
+    "cli"
   ],
   "homepage": "https://vagejs.com",
   "author": "vagejs.com",

package/templates/starter/AGENTS.md

@@ -6,7 +6,8 @@ This website uses **vagejs** (pre-release). Only the features listed here exist
 
 | Command           | What it does                                              |
 | ----------------- | --------------------------------------------------------- |
-| `npm run dev`     | Dev server with live reload. Prints the local URL.        |
+| `npm run dev`     | Dev server with live reload. Prints the local URL and the same server's direct address (e.g. `http://[::1]:5173/`): if a browser shows HTTP 431 on localhost (too many cookies from other projects), use the direct address. Use this one yourself; it doesn't open a browser. |
+| `npm start`       | For people: the dev server, opened in the default browser at the direct address. |
 | `npm run build`   | Static build into `dist/`. Exits non-zero on any error.   |
 | `npm run check`   | SEO, link, structured-data and basic a11y checks. Writes nothing. Exit 1 on errors (`--strict`: also on warnings). |
 | `npm run audit`   | Builds, then checks page-weight budgets and runs axe accessibility rules. `--lighthouse` adds a local Lighthouse run (install `lighthouse`; needs Chrome). `--url <https://...>` audits a deployed page via PageSpeed Insights (+ CrUX field data with `CRUX_API_KEY`). |
@@ -29,7 +30,7 @@ Run `npm run check` after every change and fix all errors before finishing.
 - **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.
 - **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 published HTML page, so it contains exactly what the page shows, and `llms.txt` links to them. `seo: { lastmod: "git" }` dates the sitemap from git history (needs full history in CI: `fetch-depth: 0`).
+- **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`).
 - **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.

package/templates/starter/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "start": "vage dev --open",
     "dev": "vage dev",
     "build": "vage build",
     "check": "vage check",
@@ -11,6 +12,6 @@
     "preview": "vage preview"
   },
   "devDependencies": {
-    "vagejs": "^0.3.0"
+    "vagejs": "^0.3.2"
   }
 }