@micropage-sh/cli 2.0.7 → 2.5.0

package/README.md

@@ -63,6 +63,40 @@ micropage copy-link
 
 When you create a project without `-d`, the API assigns `projects.domain` as the initial host for your site (for example `my-site.micropage.sh`). You can optionally attach a custom domain (such as `www.example.com`) in the web editor; when present, the CLI shows that custom domain as the site URL (otherwise the default host).
 
+### Authoring posts
+
+Posts live in the project's `posts/` folder as Markdown files with YAML front-matter:
+
+```markdown
+---
+title: Hello, world
+slug: hello
+description: A short summary for the archive, meta description, and og tags.
+visibility: listed
+hero: ./hello.jpg
+list: newsletter
+subject: Hello, world!
+preview: The first post on this site.
+---
+
+Body content goes here as standard Markdown.
+```
+
+`title` is required. `slug` defaults to the filename minus a leading `YYYY-MM-DD-` date prefix. `visibility` is `listed` (default, appears in the site's `/content` index) or `unlisted`. `list` names a newsletter form and is required to email the post on publish. Local image references in the body are auto-uploaded and rewritten to hosted URLs on `push`.
+
+```bash
+# Save posts/hello.md as a draft
+micropage posts push
+
+# Publish it (and email the `list:` target, if set)
+micropage posts publish hello
+
+# Take it back down (stays as a draft)
+micropage posts unpublish hello
+```
+
+See [`micropage posts`](#posts) below for the full command set.
+
 ## Commands reference
 
 ### Auth
@@ -116,6 +150,19 @@ When you create a new project, the CLI also scaffolds:
 | `micropage copy-link` | Copy the live URL to clipboard |
 | `micropage open-pricing` | Open the pricing page in the browser |
 
+### Posts
+
+| Command | Description |
+|---|---|
+| `micropage posts push` | Save local `posts/*.md` files as post drafts (or update already-published posts, which go live immediately) |
+| `micropage posts publish [slug] [-w]` | Publish a post (or all local posts) to the web; sends the newsletter email if the post has a `list:`. Re-running re-sends the email. Auto-queues a rebuild of the site so the `/content` archive updates — no separate `micropage publish` needed. Use `-w` to stream the rebuild's deploy events until it's live. |
+| `micropage posts unpublish <slug>` | Remove a post's `/content/<slug>` page; the post remains as a draft |
+| `micropage posts pull` | Pull remote posts down to local `posts/*.md` files |
+| `micropage posts list` | List the project's posts (slug, title, visibility, published/draft, emailed, send status, created). "Send status" is the newsletter send lifecycle and shows only for email posts — it does not reflect deploy state. |
+| `micropage posts rm <slug>` | Delete a post entirely (remote) |
+
+**Note:** `micropage posts publish` publishes a single *post* and automatically rebuilds the site so the post appears on the `/content` archive — you do **not** need to run `micropage publish` afterward. `micropage publish` is for deploying changes to the *site* content (`.page` files) itself.
+
 ### Files
 
 | Command | Description |
@@ -163,6 +210,10 @@ The CLI uses one or more `*.page` files in the working directory as the source o
 
 **Pulling** always writes to `landing.page` only.
 
+### `llms.txt`
+
+If the project folder contains a root-level `llms.txt`, its contents are published verbatim and served at `/llms.txt` (a curated map of the site for LLM agents). Remove the local file and re-publish to take it down.
+
 ## Project configuration
 
 Each project folder has a `.micropage/project.json` file that stores:

package/bin/micropage.js

@@ -1,3 +1,18 @@
 #!/usr/bin/env node
 
+// Suppress Node's "buffer.File is an experimental feature" warning that fires
+// when undici's FormData serializes a Blob upload. Stabilized in Node 22.
+const origEmit = process.emit;
+process.emit = function (name, data, ...rest) {
+  if (
+    name === 'warning' &&
+    data &&
+    data.name === 'ExperimentalWarning' &&
+    /buffer\.File/.test(String(data.message))
+  ) {
+    return false;
+  }
+  return origEmit.call(this, name, data, ...rest);
+};
+
 require('../src/index.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@micropage-sh/cli",
-  "version": "2.0.7",
+  "version": "2.5.0",
   "description": "CLI for micropage.sh - create, sync, and publish microsites",
   "main": "src/index.js",
   "bin": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node -e \"require('./src/index.js')\"",
+    "test": "node -e \"require('./src/index.js')\"; node --test test/",
     "build:bin": "pkg . --targets node18-linux-x64,node18-macos-x64,node18-macos-arm64 --output dist/micropage",
     "build:linux": "pkg . --target node18-linux-x64 --output dist/micropage-linux-amd64",
     "build:macos-amd64": "pkg . --target node18-macos-x64 --output dist/micropage-darwin-amd64",
@@ -57,6 +57,7 @@
   },
   "dependencies": {
     "commander": "^12.0.0",
+    "gray-matter": "^4.0.3",
     "open": "^10.1.0"
   },
   "devDependencies": {

package/src/commands/builds.js

@@ -14,7 +14,7 @@ const {
   uploadAssetsWithToken,
 } = require('../supabase');
 const { getProjectConfig, setProjectConfig } = require('../auth');
-const { readPageFilesFromDir } = require('../parser');
+const { readPageFilesFromDir, readLlmsTxtFromDir } = require('../parser');
 const { BUILD_COMPILER_URL } = require('../config');
 const { formatTable, formatDate } = require('../utils');
 
@@ -167,6 +167,13 @@ async function push(options = {}) {
     process.exit(1);
   }
 
+  const llmsTxt = readLlmsTxtFromDir(cwd);
+  if (llmsTxt != null) {
+    jsonContent.site = jsonContent.site || {};
+    jsonContent.site.llms_txt = llmsTxt;
+    console.log(`Including llms.txt (${Buffer.byteLength(llmsTxt, 'utf8')} bytes).`);
+  }
+
   // Decide whether to update existing draft or create new build
   let existingBuild = null;
   if (config.buildId) {

package/src/commands/forms.js

@@ -4,6 +4,25 @@ const { db, handleAuthError } = require('../supabase');
 const { getProjectConfig } = require('../auth');
 const { formatTable, formatDate } = require('../utils');
 
+const FORM_COLUMNS = 'id,form_name,page_url,is_footer,created_at';
+
+/** Occurrence number among same-named forms on the same page, 1-based. */
+function formLabel(form) {
+  const ordinal = Number(form.form_ordinal) || 0;
+  return ordinal > 0 ? `${form.form_name} (${ordinal + 1})` : form.form_name;
+}
+
+function fetchForms(projectId, withOrdinal) {
+  const q = db
+    .from('forms')
+    .select(withOrdinal ? `${FORM_COLUMNS},form_ordinal` : FORM_COLUMNS)
+    .eq('project_id', projectId);
+
+  return withOrdinal
+    ? q.order('page_url,form_ordinal', 'asc').get()
+    : q.order('created_at', 'asc').get();
+}
+
 async function list(options = {}) {
   const cwd = process.cwd();
   const config = getProjectConfig(cwd);
@@ -14,16 +33,18 @@ async function list(options = {}) {
 
   let forms;
   try {
-    forms = await db
-      .from('forms')
-      .select('id,form_name,page_url,is_footer,created_at')
-      .eq('project_id', config.projectId)
-      .order('created_at', 'asc')
-      .get();
+    forms = await fetchForms(config.projectId, true);
   } catch (err) {
     handleAuthError(err);
-    console.error('Failed to list forms:', err.message);
-    process.exit(1);
+    // form_ordinal is newer than some deployed databases; selecting a column
+    // that does not exist fails the whole request, so retry the older shape.
+    try {
+      forms = await fetchForms(config.projectId, false);
+    } catch (retryErr) {
+      handleAuthError(retryErr);
+      console.error('Failed to list forms:', retryErr.message);
+      process.exit(1);
+    }
   }
 
   if (!Array.isArray(forms) || forms.length === 0) {
@@ -53,13 +74,17 @@ async function list(options = {}) {
   }
 
   if (options.json) {
-    const out = forms.map((f) => ({ ...f, submission_count: counts[f.id] || 0 }));
+    const out = forms.map((f) => ({
+      ...f,
+      form_ordinal: Number(f.form_ordinal) || 0,
+      submission_count: counts[f.id] || 0,
+    }));
     console.log(JSON.stringify(out, null, 2));
     return;
   }
 
   const rows = forms.map((f) => [
-    f.form_name,
+    formLabel(f),
     f.page_url,
     f.is_footer ? 'footer' : 'inline',
     String(counts[f.id] || 0),

package/src/commands/posts.js

@@ -0,0 +1,625 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+
+const {
+  db,
+  fn,
+  handleAuthError,
+  getValidAccessToken,
+  getMaxDeployEventIdForBuild,
+  streamDeployEventsUntilDone,
+} = require('../supabase');
+const { getProjectConfig } = require('../auth');
+const { formatTable, formatDate } = require('../utils');
+const { fetchRemoteFileIndex, resolveHeroImage, resolveBodyImages } = require('../posts-assets');
+
+const POSTS_DIR = 'posts';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function requireProjectConfig(cwd) {
+  const config = getProjectConfig(cwd);
+  if (!config?.projectId) {
+    console.error('Not in a project folder. Run from a folder with .micropage/project.json');
+    process.exit(1);
+  }
+  return config;
+}
+
+function requirePostsDir(cwd) {
+  const dir = path.join(cwd, POSTS_DIR);
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    console.error(`No "${POSTS_DIR}/" folder found. Create one and add .md files, or run: micropage posts pull`);
+    process.exit(1);
+  }
+  return dir;
+}
+
+function listLocalPostFiles(postsDir) {
+  return fs
+    .readdirSync(postsDir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => path.join(postsDir, e.name))
+    .sort();
+}
+
+/** filename minus a leading date prefix (YYYY-MM-DD-) and the .md extension. */
+function defaultSlugFromFilename(filePath) {
+  const base = path.basename(filePath, '.md');
+  return base.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+}
+
+function slugify(s) {
+  return String(s)
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/** Resolve `list: <form name>` -> form_id via the `forms` table (case-insensitive, newsletter forms only). */
+async function resolveFormId(projectId, listName) {
+  const name = String(listName).trim();
+  let forms;
+  try {
+    forms = await db
+      .from('forms')
+      .select('id,form_name,is_newsletter')
+      .eq('project_id', projectId)
+      .eq('is_newsletter', true)
+      .get();
+  } catch (err) {
+    handleAuthError(err);
+    throw new Error(`Failed to look up form "${name}": ${err.message}`);
+  }
+
+  const matches = (forms || []).filter(
+    (f) => String(f.form_name || '').toLowerCase() === name.toLowerCase(),
+  );
+  if (matches.length === 0) {
+    throw new Error(
+      `No newsletter form named "${name}" found for this project. Check "micropage forms list".`,
+    );
+  }
+  if (matches.length > 1) {
+    throw new Error(`Multiple newsletter forms named "${name}" found — ambiguous. Rename one to disambiguate.`);
+  }
+  return matches[0].id;
+}
+
+function frontMatterFromPost(post) {
+  const fmData = {
+    title: post.title || '',
+  };
+  if (post.slug) fmData.slug = post.slug;
+  if (post.description) fmData.description = post.description;
+  if (post.web_visibility && post.web_visibility !== 'listed') fmData.visibility = post.web_visibility;
+  if (post.hero_image) fmData.hero = post.hero_image;
+  if (post.email_enabled) fmData.email = true;
+  if (post.subject && post.subject !== post.title) fmData.subject = post.subject;
+  if (post.preheader) fmData.preview = post.preheader;
+  return fmData;
+}
+
+// ---------------------------------------------------------------------------
+// posts push
+// ---------------------------------------------------------------------------
+
+async function push(options = {}) {
+  const cwd = process.cwd();
+  const config = requireProjectConfig(cwd);
+  const postsDir = requirePostsDir(cwd);
+
+  const localFiles = listLocalPostFiles(postsDir);
+  if (localFiles.length === 0) {
+    console.log(`No .md files found in "${POSTS_DIR}/". Nothing to push.`);
+    return;
+  }
+
+  let accessToken;
+  try {
+    accessToken = await getValidAccessToken();
+  } catch (err) {
+    handleAuthError(err);
+    console.error('Failed to authenticate:', err.message);
+    process.exit(1);
+  }
+
+  // Fetch remote posts once, both to report drift and to know created vs. updated.
+  let remotePosts = [];
+  try {
+    remotePosts = await db
+      .from('posts')
+      .select('id,slug,title,web_visibility,email_enabled,status,published_at,created_at')
+      .eq('project_id', config.projectId)
+      .order('created_at', 'desc')
+      .get();
+  } catch (err) {
+    handleAuthError(err);
+    console.error('Failed to fetch remote posts:', err.message);
+    process.exit(1);
+  }
+  const remoteBySlug = new Map((remotePosts || []).map((p) => [p.slug, p]));
+
+  let fileIndex;
+  try {
+    fileIndex = await fetchRemoteFileIndex(config.projectId);
+  } catch (err) {
+    handleAuthError(err);
+    console.error('Failed to list project files:', err.message);
+    process.exit(1);
+  }
+
+  const localSlugs = new Set();
+  const summary = [];
+  let hadError = false;
+
+  for (const filePath of localFiles) {
+    const relName = path.relative(cwd, filePath);
+    let raw;
+    try {
+      raw = fs.readFileSync(filePath, 'utf8');
+    } catch (err) {
+      console.error(`${relName}: failed to read (${err.message})`);
+      hadError = true;
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = matter(raw);
+    } catch (err) {
+      console.error(`${relName}: invalid front-matter (${err.message})`);
+      hadError = true;
+      continue;
+    }
+
+    const fm = parsed.data || {};
+    const title = typeof fm.title === 'string' ? fm.title.trim() : '';
+    if (!title) {
+      console.error(`${relName}: missing required front-matter field "title"`);
+      hadError = true;
+      continue;
+    }
+
+    const slug = fm.slug ? slugify(String(fm.slug)) : slugify(defaultSlugFromFilename(filePath));
+    if (!slug) {
+      console.error(`${relName}: could not derive a slug (set "slug:" in front-matter)`);
+      hadError = true;
+      continue;
+    }
+    localSlugs.add(slug);
+
+    const visibility = fm.visibility || 'listed';
+    if (!['listed', 'unlisted'].includes(visibility)) {
+      console.error(`${relName}: invalid "visibility" (${visibility}); use listed or unlisted`);
+      hadError = true;
+      continue;
+    }
+
+    const emailWanted = fm.email === true;
+    let formId = null;
+    if (emailWanted) {
+      if (!fm.list) {
+        console.error(`${relName}: "email: true" requires a "list:" front-matter field`);
+        hadError = true;
+        continue;
+      }
+      try {
+        formId = await resolveFormId(config.projectId, fm.list);
+      } catch (err) {
+        console.error(`${relName}: ${err.message}`);
+        hadError = true;
+        continue;
+      }
+    }
+
+    let heroUrl = null;
+    try {
+      const hero = await resolveHeroImage({
+        accessToken,
+        projectId: config.projectId,
+        postFilePath: filePath,
+        cwd,
+        heroFrontMatter: fm.hero,
+        fileIndex,
+      });
+      heroUrl = hero.url;
+    } catch (err) {
+      console.error(`${relName}: ${err.message}`);
+      hadError = true;
+      continue;
+    }
+
+    let bodyMarkdown;
+    try {
+      const resolvedBody = await resolveBodyImages({
+        accessToken,
+        projectId: config.projectId,
+        postFilePath: filePath,
+        cwd,
+        body: parsed.content || '',
+        fileIndex,
+      });
+      bodyMarkdown = resolvedBody.markdown;
+      if (resolvedBody.unresolved && resolvedBody.unresolved.length > 0) {
+        console.warn(
+          `${relName}: warning — ${resolvedBody.unresolved.length} body image(s) not found locally, shipped as-is (will 404 if unhosted): ${resolvedBody.unresolved.join(', ')}`,
+        );
+      }
+    } catch (err) {
+      console.error(`${relName}: failed to resolve body images (${err.message})`);
+      hadError = true;
+      continue;
+    }
+
+    const payload = {
+      project_id: config.projectId,
+      title,
+      slug,
+      body_markdown: bodyMarkdown,
+      description: fm.description || null,
+      web_visibility: visibility,
+      hero_image: heroUrl,
+      form_id: formId,
+      subject: fm.subject || null,
+      preheader: fm.preview || null,
+    };
+
+    try {
+      const result = await fn.invoke('upsert-post', payload);
+      const note = `${result.action}, saved (${result.published ? 'live' : 'draft'})`;
+      summary.push({ file: relName, slug, ok: true, note });
+      console.log(`${relName} -> "${slug}": ${note}`);
+    } catch (err) {
+      handleAuthError(err);
+      const msg = err.status === 409 ? 'slug already in use for another post' : err.message;
+      console.error(`${relName}: upsert failed (${msg})`);
+      summary.push({ file: relName, slug, ok: false, note: msg });
+      hadError = true;
+    }
+  }
+
+  // Drift report: remote posts with no matching local file. Never deleted here.
+  const driftSlugs = (remotePosts || [])
+    .map((p) => p.slug)
+    .filter((slug) => slug && !localSlugs.has(slug));
+  if (driftSlugs.length > 0) {
+    console.log('');
+    console.log(
+      `Note: ${driftSlugs.length} remote post(s) have no local file in "${POSTS_DIR}/" (not deleted): ${driftSlugs.join(', ')}`,
+    );
+    console.log('Run "micropage posts pull" to fetch them locally, or "micropage posts rm <slug>" to delete remotely.');
+  }
+
+  console.log('');
+  const okCount = summary.filter((s) => s.ok).length;
+  console.log(`Pushed ${okCount}/${summary.length} post(s).`);
+
+  if (hadError) process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// posts pull
+// ---------------------------------------------------------------------------
+
+async function pull(options = {}) {
+  const cwd = process.cwd();
+  const config = requireProjectConfig(cwd);
+  const postsDir = path.join(cwd, POSTS_DIR);
+  fs.mkdirSync(postsDir, { recursive: true });
+
+  let remotePosts;
+  try {
+    remotePosts = await db
+      .from('posts')
+      .select(
+        'id,slug,title,description,body_markdown,web_visibility,email_enabled,status,hero_image,published_at,created_at',
+      )
+      .eq('project_id', config.projectId)
+      .order('created_at', 'desc')
+      .get();
+  } catch (err) {
+    handleAuthError(err);
+    console.error('Failed to fetch remote posts:', err.message);
+    process.exit(1);
+  }
+
+  if (!Array.isArray(remotePosts) || remotePosts.length === 0) {
+    console.log('No remote posts to pull.');
+    return;
+  }
+
+  let rl = null;
+  const confirmOverwrite = async (filename) => {
+    if (options.force) return true;
+    if (!rl) {
+      const readline = require('readline');
+      rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    }
+    const answer = await new Promise((resolve) => {
+      rl.question(`Overwrite "${filename}"? [y/N] `, (a) => resolve((a || '').trim().toLowerCase()));
+    });
+    return answer === 'y' || answer === 'yes';
+  };
+
+  let written = 0;
+  let skipped = 0;
+
+  for (const post of remotePosts) {
+    if (!post.slug) {
+      console.warn(`Skipping post ${post.id}: no slug set.`);
+      skipped += 1;
+      continue;
+    }
+    const filename = `${post.slug}.md`;
+    const filePath = path.join(postsDir, filename);
+
+    if (fs.existsSync(filePath)) {
+      const ok = await confirmOverwrite(filename);
+      if (!ok) {
+        skipped += 1;
+        continue;
+      }
+    }
+
+    const fmData = frontMatterFromPost(post);
+    const content = matter.stringify(post.body_markdown || '', fmData);
+    fs.writeFileSync(filePath, content, 'utf8');
+    written += 1;
+    console.log(`Wrote ${path.relative(cwd, filePath)}`);
+  }
+
+  if (rl) rl.close();
+
+  console.log('');
+  console.log(`Pulled ${written} post(s)${skipped > 0 ? `, skipped ${skipped}` : ''}.`);
+}
+
+// ---------------------------------------------------------------------------
+// posts list
+// ---------------------------------------------------------------------------
+
+async function list(options = {}) {
+  const cwd = process.cwd();
+  const config = requireProjectConfig(cwd);
+
+  let posts;
+  try {
+    posts = await db
+      .from('posts')
+      .select(
+        'id,slug,title,web_visibility,email_enabled,status,published_at,created_at',
+      )
+      .eq('project_id', config.projectId)
+      .order('created_at', 'desc')
+      .get();
+  } catch (err) {
+    handleAuthError(err);
+    console.error('Failed to list posts:', err.message);
+    process.exit(1);
+  }
+
+  if (!Array.isArray(posts) || posts.length === 0) {
+    console.log('No posts for this project.');
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(posts, null, 2));
+    return;
+  }
+
+  const rows = posts.map((p) => [
+    p.slug || '-',
+    p.title || '-',
+    p.web_visibility || '-',
+    p.published_at ? 'Published' : 'Draft',
+    p.email_enabled ? 'yes' : 'no',
+    // `status` tracks the newsletter send lifecycle only; it says nothing about
+    // deploy state, so it's meaningless (and misleading — reads as "pending") for
+    // web-only posts. Show it only when the post actually emails.
+    p.email_enabled ? (p.status || '-') : '-',
+    formatDate(p.created_at),
+  ]);
+  formatTable(rows, ['Slug', 'Title', 'Visibility', 'Published', 'Emailed', 'Send status', 'Created']);
+}
+
+// ---------------------------------------------------------------------------
+// posts rm <slug>
+// ---------------------------------------------------------------------------
+
+async function rm(slug, options = {}) {
+  if (!slug) {
+    console.error('Usage: micropage posts rm <slug>');
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  const config = requireProjectConfig(cwd);
+
+  let result;
+  try {
+    result = await fn.invoke('delete-post', { project_id: config.projectId, slug });
+  } catch (err) {
+    handleAuthError(err);
+    console.error('Failed to delete post:', err.message);
+    process.exit(1);
+  }
+
+  if (result?.deleted) {
+    console.log(`Deleted post "${slug}" (remote rebuild triggered if the project is deployed).`);
+  } else {
+    console.log(`No post found with slug "${slug}" — nothing to delete.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// posts publish [slug]
+// ---------------------------------------------------------------------------
+
+/** Slugs to target when no explicit slug is given: every local posts/*.md file's resolved slug. */
+function localSlugsFromPostsDir(postsDir) {
+  const slugs = [];
+  for (const filePath of listLocalPostFiles(postsDir)) {
+    let fm = {};
+    try {
+      fm = matter(fs.readFileSync(filePath, 'utf8')).data || {};
+    } catch {
+      continue;
+    }
+    const slug = fm.slug ? slugify(String(fm.slug)) : slugify(defaultSlugFromFilename(filePath));
+    if (slug) slugs.push(slug);
+  }
+  return slugs;
+}
+
+async function publish(slugArg, options = {}) {
+  const cwd = process.cwd();
+  const config = requireProjectConfig(cwd);
+
+  let targetSlugs;
+  if (slugArg) {
+    targetSlugs = [slugify(String(slugArg))];
+  } else {
+    const postsDir = requirePostsDir(cwd);
+    targetSlugs = localSlugsFromPostsDir(postsDir);
+    if (targetSlugs.length === 0) {
+      console.log(`No .md files found in "${POSTS_DIR}/". Nothing to publish.`);
+      return;
+    }
+  }
+
+  console.warn(
+    'Publishing sends (or re-sends) email to the active subscriber list for any email-configured post.',
+  );
+
+  // Publishing a post makes the publisher auto-rebuild the site's active build so
+  // the /content archive picks it up — no separate `micropage publish` needed.
+  // Resolve that build up front so we can report accurately and (with --watch)
+  // capture an event cursor before the rebuild is queued.
+  let activeBuildId = null;
+  try {
+    const proj = await db
+      .from('projects')
+      .select('active_build_id')
+      .eq('id', config.projectId)
+      .single();
+    activeBuildId = proj?.active_build_id || null;
+  } catch {
+    // best-effort; treated as "unknown" below
+  }
+
+  let eventCursor = 0;
+  if (options.watch && activeBuildId) {
+    try {
+      eventCursor = await getMaxDeployEventIdForBuild(activeBuildId);
+    } catch {
+      eventCursor = 0;
+    }
+  }
+
+  let hadError = false;
+  let publishedCount = 0;
+
+  for (const slug of targetSlugs) {
+    try {
+      const result = await fn.invoke('publish-post', { project_id: config.projectId, slug });
+      const bits = [`published_at ${result.published_at}`];
+      bits.push(result.emailed ? `emailed ${result.recipient_count} recipient(s)` : 'no email');
+      console.log(`"${slug}": ${bits.join(', ')}`);
+      publishedCount += 1;
+    } catch (err) {
+      handleAuthError(err);
+      const msg = err.status === 404 ? 'post not found (push it first with "micropage posts push")' : err.message;
+      console.error(`"${slug}": publish failed (${msg})`);
+      hadError = true;
+    }
+  }
+
+  console.log('');
+  console.log(`Published ${publishedCount}/${targetSlugs.length} post(s).`);
+
+  if (publishedCount > 0) {
+    if (activeBuildId) {
+      console.log(
+        'A site rebuild was queued automatically; the /content archive updates once it deploys (usually a minute or two).',
+      );
+    } else {
+      console.log(
+        "Note: this project hasn't been published yet, so the post won't appear until you run 'micropage publish'.",
+      );
+    }
+
+    if (options.watch && activeBuildId) {
+      console.log('');
+      console.log('Build / deploy events:');
+      try {
+        const accessToken = await getValidAccessToken();
+        const { terminalEvent } = await streamDeployEventsUntilDone(
+          accessToken,
+          config.projectId,
+          activeBuildId,
+          { afterId: eventCursor },
+        );
+        if (terminalEvent?.event_type === 'build.failed') {
+          const msg =
+            (terminalEvent.payload && (terminalEvent.payload.error || terminalEvent.payload.message)) ||
+            'Build failed';
+          console.error(msg);
+          process.exit(1);
+        }
+      } catch (streamErr) {
+        console.error('Event stream failed:', streamErr.message);
+        process.exit(1);
+      }
+    }
+  }
+
+  if (hadError) process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// posts unpublish <slug>
+// ---------------------------------------------------------------------------
+
+async function unpublish(slug) {
+  if (!slug) {
+    console.error('Usage: micropage posts unpublish <slug>');
+    process.exit(1);
+  }
+  const cwd = process.cwd();
+  const config = requireProjectConfig(cwd);
+
+  let result;
+  try {
+    result = await fn.invoke('unpublish-post', { project_id: config.projectId, slug: slugify(String(slug)) });
+  } catch (err) {
+    handleAuthError(err);
+    const msg = err.status === 404 ? 'post not found' : err.message;
+    console.error(`Failed to unpublish post: ${msg}`);
+    process.exit(1);
+  }
+
+  if (result?.unpublished) {
+    console.log(`Unpublished post "${slug}" (removed from the site; remains as a draft).`);
+  } else {
+    console.log(`No post found with slug "${slug}" — nothing to unpublish.`);
+  }
+}
+
+module.exports = {
+  push,
+  pull,
+  list,
+  rm,
+  publish,
+  unpublish,
+  slugify,
+  defaultSlugFromFilename,
+  frontMatterFromPost,
+};

package/src/commands/projects.js

@@ -286,6 +286,7 @@ async function create(name, options = {}) {
     name: project.name || name,
   });
   fs.mkdirSync(path.join(dir, 'assets'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'posts'), { recursive: true });
 
   copyExamplesAndAssetsIntoProject(dir);
 

package/src/index.js

@@ -13,6 +13,7 @@ const submissions = require('./commands/submissions');
 const forms = require('./commands/forms');
 const files = require('./commands/files');
 const links = require('./commands/links');
+const posts = require('./commands/posts');
 
 const program = new Command();
 
@@ -241,4 +242,43 @@ subCmd
   )
   .action((opts) => submissions.exportSubmissions(opts));
 
+// ---------------------------------------------------------------------------
+// Posts  (micropage posts <subcommand>)
+// ---------------------------------------------------------------------------
+
+const postsCmd = program.command('posts').description('Manage posts (dual-channel web + email content)');
+
+postsCmd
+  .command('push')
+  .description('Save draft/update local posts/*.md as post rows (does not publish or email); reports remote-only posts as drift')
+  .action((opts) => posts.push(opts));
+
+postsCmd
+  .command('pull')
+  .description('Write remote posts to local posts/*.md files')
+  .option('-f, --force', 'Overwrite existing local files without prompting')
+  .action((opts) => posts.pull(opts));
+
+postsCmd
+  .command('list')
+  .description('List posts for the current project')
+  .option('--json', 'Output as JSON')
+  .action((opts) => posts.list(opts));
+
+postsCmd
+  .command('publish [slug]')
+  .description('Publish one post by slug, or all local posts if omitted; (re)sends email for email-configured posts. Auto-triggers a site rebuild so the /content archive updates')
+  .option('-w, --watch', 'Stream build/deploy events until the auto-triggered site rebuild deploys')
+  .action((slug, opts) => posts.publish(slug, opts));
+
+postsCmd
+  .command('unpublish <slug>')
+  .description('Take a post off the site (does not delete it; it remains as a draft)')
+  .action((slug, opts) => posts.unpublish(slug, opts));
+
+postsCmd
+  .command('rm <slug>')
+  .description('Delete a post by slug (remote only; does not touch local files)')
+  .action((slug, opts) => posts.rm(slug, opts));
+
 program.parse();

package/src/parser.js

@@ -48,6 +48,21 @@ function writePageFile(dir, content) {
   return dest;
 }
 
+/**
+ * Read a root-level llms.txt from the given directory.
+ *
+ * Returns the file's UTF-8 content verbatim, or null if the file is absent or
+ * whitespace-only. Content is preserved as-is so authors control the served
+ * `/llms.txt` exactly (only a trailing newline is dropped).
+ */
+function readLlmsTxtFromDir(dir) {
+  const file = path.join(dir, 'llms.txt');
+  if (!fs.existsSync(file)) return null;
+  const content = fs.readFileSync(file, 'utf8');
+  if (!content.trim()) return null;
+  return content.replace(/\n$/, '');
+}
+
 function listAssetsFromDir(dir) {
   const assetsDir = path.join(dir, 'assets');
   if (!fs.existsSync(assetsDir)) return [];
@@ -65,4 +80,5 @@ module.exports = {
   readPageFilesFromDir,
   writePageFile,
   listAssetsFromDir,
+  readLlmsTxtFromDir,
 };

package/src/posts-assets.js

@@ -0,0 +1,211 @@
+'use strict';
+
+/**
+ * Asset resolution helpers for `micropage posts push`.
+ *
+ * Reuses the exact same asset pipeline the editor uses: `upload-file` (via
+ * uploadAssetWithToken + hashFile + list-files dedup) to store the image, then
+ * `get-file-url` to resolve its URL. Nothing here is CLI-specific — it mirrors
+ * the editor's file-manager / image-picker flow.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { fn, hashFile, uploadAssetWithToken } = require('./supabase');
+
+const IMAGE_EXTS = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'];
+
+function isAbsoluteUrl(s) {
+  return typeof s === 'string' && /^https?:\/\//i.test(s.trim());
+}
+
+/**
+ * Find a companion image next to a post file: `<postbasename>.<imgext>`,
+ * e.g. `posts/2026-01-01-launch.md` -> `posts/2026-01-01-launch.png`.
+ */
+function findCompanionImage(postFilePath) {
+  const dir = path.dirname(postFilePath);
+  const base = path.basename(postFilePath, path.extname(postFilePath));
+  for (const ext of IMAGE_EXTS) {
+    const candidate = path.join(dir, `${base}${ext}`);
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Fetch the project's remote file list once and expose lookup-by-filename.
+ * Callers should fetch this once per push and reuse it across posts.
+ */
+async function fetchRemoteFileIndex(projectId) {
+  const data = await fn.invokeGet('list-files', { project_id: projectId });
+  const files = data?.files || [];
+  const byFilename = new Map();
+  const byHash = new Map();
+  for (const f of files) {
+    if (f.filename) byFilename.set(f.filename, f);
+    if (f.content_hash) byHash.set(f.content_hash, f);
+  }
+  return { byFilename, byHash };
+}
+
+/**
+ * Resolve a `file_id` to its URL via the `get-file-url` edge function — the same
+ * call the editor's image picker makes.
+ */
+async function fileUrlFor(fileId) {
+  const data = await fn.invokeGet('get-file-url', { file_id: fileId });
+  const url = data?.url;
+  if (!url) throw new Error(`get-file-url returned no url for file_id=${fileId}`);
+  return url;
+}
+
+/**
+ * Upload a local file if its content hash isn't already present remotely
+ * (dedup, mirrors uploadAssetsWithToken), then resolve its absolute URL.
+ * Mutates `fileIndex` in place so repeated calls within the same push reuse it.
+ */
+async function uploadLocalImageOnce(accessToken, projectId, filePath, fileIndex) {
+  const filename = path.basename(filePath);
+  const localHash = hashFile(filePath);
+
+  const existingByHash = fileIndex.byHash.get(localHash);
+  if (existingByHash) {
+    return { fileId: existingByHash.id, uploaded: false, filename: existingByHash.filename };
+  }
+
+  const uploadResult = await uploadAssetWithToken(accessToken, projectId, filePath, filename);
+  const file = uploadResult?.file;
+  if (!file?.id) throw new Error(`upload-file returned no file record for ${filename}`);
+
+  fileIndex.byFilename.set(file.filename, file);
+  if (file.content_hash) fileIndex.byHash.set(file.content_hash, file);
+
+  return { fileId: file.id, uploaded: true, filename: file.filename };
+}
+
+/**
+ * Resolve a post's hero image to an absolute URL.
+ *
+ * Priority: companion file next to the .md > front-matter `hero:` > none.
+ * `hero:` may be:
+ *   - an absolute http(s) URL (passthrough, no upload)
+ *   - a local file path (relative to the post file, or to assets/) that exists on disk (upload)
+ *   - an existing uploaded asset filename (resolve via list-files, no upload)
+ *
+ * @returns {Promise<{ url: string|null, uploaded: boolean, source: string|null }>}
+ */
+async function resolveHeroImage({ accessToken, projectId, postFilePath, cwd, heroFrontMatter, fileIndex }) {
+  const companion = findCompanionImage(postFilePath);
+  if (companion) {
+    const { fileId, uploaded, filename } = await uploadLocalImageOnce(accessToken, projectId, companion, fileIndex);
+    const url = await fileUrlFor(fileId);
+    return { url, uploaded, source: `companion:${filename}` };
+  }
+
+  const hero = typeof heroFrontMatter === 'string' ? heroFrontMatter.trim() : '';
+  if (!hero) return { url: null, uploaded: false, source: null };
+
+  if (isAbsoluteUrl(hero)) {
+    return { url: hero, uploaded: false, source: 'url' };
+  }
+
+  // Local file path: relative to the post file's directory, then to assets/, then to cwd.
+  const candidates = [
+    path.isAbsolute(hero) ? hero : path.join(path.dirname(postFilePath), hero),
+    path.join(cwd, 'assets', hero),
+    path.join(cwd, hero),
+  ];
+  const localPath = candidates.find((p) => fs.existsSync(p) && fs.statSync(p).isFile());
+  if (localPath) {
+    const { fileId, uploaded, filename } = await uploadLocalImageOnce(accessToken, projectId, localPath, fileIndex);
+    const url = await fileUrlFor(fileId);
+    return { url, uploaded, source: `local:${filename}` };
+  }
+
+  // Existing uploaded asset, referenced by filename only.
+  const existing = fileIndex.byFilename.get(hero) || fileIndex.byFilename.get(path.basename(hero));
+  if (existing) {
+    const url = await fileUrlFor(existing.id);
+    return { url, uploaded: false, source: `existing:${existing.filename}` };
+  }
+
+  throw new Error(`hero image not found: "${hero}" (not a URL, local file, or existing uploaded asset)`);
+}
+
+// Matches markdown image refs: ![alt](path "title"). Captures alt and the path only.
+const MD_IMAGE_RE = /!\[([^\]]*)\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g;
+
+/**
+ * Scan `body_markdown` for local image refs (`![alt](rel/path.png)`), upload each
+ * once (hash-dedup via `fileIndex`), and rewrite the markdown to use hosted
+ * absolute URLs. Absolute URLs and refs that don't resolve to a local file are
+ * left untouched.
+ *
+ * Refs that look local (relative, not a URL / root-absolute / anchor) but don't
+ * resolve to a file on disk are reported in `unresolved` so the caller can warn —
+ * otherwise a typo'd path would ship into body_markdown and 404 on the live page.
+ *
+ * @returns {Promise<{ markdown: string, uploaded: string[], mapping: Record<string,string>, unresolved: string[] }>}
+ */
+async function resolveBodyImages({ accessToken, projectId, postFilePath, cwd, body, fileIndex }) {
+  const refs = [];
+  let match;
+  MD_IMAGE_RE.lastIndex = 0;
+  while ((match = MD_IMAGE_RE.exec(body)) !== null) {
+    refs.push(match[2]);
+  }
+
+  const mapping = {};
+  const uploaded = [];
+  const unresolved = [];
+
+  for (const ref of refs) {
+    if (mapping[ref] || isAbsoluteUrl(ref) || ref.startsWith('/') || ref.startsWith('#')) continue;
+
+    const candidates = [
+      path.join(path.dirname(postFilePath), ref),
+      path.join(cwd, 'assets', ref),
+      path.join(cwd, ref),
+    ];
+    const localPath = candidates.find((p) => fs.existsSync(p) && fs.statSync(p).isFile());
+    if (!localPath) {
+      // Looks like a local ref but no file on disk — surface it, don't ship it silently.
+      if (!unresolved.includes(ref)) unresolved.push(ref);
+      continue;
+    }
+
+    const { fileId, uploaded: wasUploaded, filename } = await uploadLocalImageOnce(
+      accessToken,
+      projectId,
+      localPath,
+      fileIndex,
+    );
+    const url = await fileUrlFor(fileId);
+    mapping[ref] = url;
+    if (wasUploaded) uploaded.push(filename);
+  }
+
+  if (Object.keys(mapping).length === 0) {
+    return { markdown: body, uploaded, mapping, unresolved };
+  }
+
+  MD_IMAGE_RE.lastIndex = 0;
+  const rewritten = body.replace(MD_IMAGE_RE, (full, alt, ref) => {
+    const resolved = mapping[ref];
+    return resolved ? `![${alt}](${resolved})` : full;
+  });
+
+  return { markdown: rewritten, uploaded, mapping, unresolved };
+}
+
+module.exports = {
+  findCompanionImage,
+  fetchRemoteFileIndex,
+  fileUrlFor,
+  resolveHeroImage,
+  resolveBodyImages,
+};

package/src/supabase.js

@@ -299,6 +299,16 @@ const TERMINAL_DEPLOY_EVENTS = new Set([
   'archive.failed',
 ]);
 
+/**
+ * Collapse arbitrary text to a single bounded line. Keeps a Rails/HTML error
+ * body or backtrace that leaks into an event payload from flooding the deploy
+ * stream (the CLI is not the place to render a server stack trace).
+ */
+function truncateForConsole(str, max = 200) {
+  const oneLine = String(str).replace(/\s+/g, ' ').trim();
+  return oneLine.length > max ? `${oneLine.slice(0, max)}…` : oneLine;
+}
+
 /**
  * Human-readable line for deploy stream (falls back to event_type + JSON payload).
  * @param {{ event_type?: string, payload?: Record<string, unknown> }} ev
@@ -326,14 +336,14 @@ function formatDeployEventForConsole(ev) {
       case 'active':
         return `${eventType}: live — ${https}`;
       case 'failed':
-        return `${eventType}: failed — ${payload.error || 'unknown'}`;
+        return `${eventType}: failed — ${truncateForConsole(payload.error || 'unknown', 160)}`;
       case 'timeout':
         return `${eventType}: still pending after wait (try ${https || 'URL'} shortly)`;
       default:
         break;
     }
   }
-  const extra = ev.payload ? ` ${JSON.stringify(ev.payload)}` : '';
+  const extra = ev.payload ? ` ${truncateForConsole(JSON.stringify(ev.payload))}` : '';
   return `${eventType}${extra}`;
 }
 
@@ -418,7 +428,13 @@ async function streamDeployEventsUntilDone(bearerToken, projectId, buildId, opti
             }
           } catch (e) {
             if (e instanceof SyntaxError) {
-              console.log(json);
+              // A non-JSON data line usually means an HTML/error body leaked into
+              // the stream — summarize it instead of dumping the whole page.
+              if (/^\s*</.test(json)) {
+                console.log('[stream] skipped non-JSON response chunk');
+              } else {
+                console.log(truncateForConsole(json));
+              }
             } else {
               throw e;
             }
@@ -437,6 +453,12 @@ async function streamDeployEventsUntilDone(bearerToken, projectId, buildId, opti
   return { terminalEvent };
 }
 
+function hashFile(filePath) {
+  const crypto = require('crypto');
+  const fs = require('fs');
+  return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+
 /**
  * Upload a single asset file to the project via the upload-file Edge function.
  * Uses a pre-obtained Supabase access token.
@@ -447,10 +469,12 @@ async function uploadAssetWithToken(accessToken, projectId, filePath, filename)
 
   const bytes = fs.readFileSync(filePath);
   const mimeType = mime.fromFilename(filename);
+  const sha = hashFile(filePath);
 
   const formData = new FormData();
   formData.append('file', new Blob([bytes], { type: mimeType }), filename);
   formData.append('project_id', String(projectId));
+  formData.append('content_hash', sha);
 
   const res = await fetch(`${SUPABASE_URL}/functions/v1/upload-file`, {
     method: 'POST',
@@ -473,9 +497,33 @@ async function uploadAssetWithToken(accessToken, projectId, filePath, filename)
   return data;
 }
 
+async function deleteFileWithToken(accessToken, fileId) {
+  const res = await fetch(`${SUPABASE_URL}/functions/v1/delete-file`, {
+    method: 'POST',
+    headers: {
+      'apikey': SUPABASE_ANON_KEY,
+      'Authorization': `Bearer ${accessToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ file_id: fileId }),
+  });
+  const text = await res.text();
+  let data = null;
+  try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
+  if (!res.ok) {
+    const msg = (data && (data.error || data.message)) || `HTTP ${res.status}`;
+    const err = new Error(msg);
+    err.status = res.status;
+    throw err;
+  }
+  return data;
+}
+
 /**
  * Upload all assets from the local `assets/` directory for a project.
- * Skips files that already exist on the server (matched by filename).
+ * Compares each local file's SHA-256 hash against the server's stored hash.
+ * Skips files whose content is unchanged. Deletes and re-uploads files whose
+ * content has changed (or whose server hash is NULL from before hashing was added).
  * Returns the count of files uploaded.
  */
 async function uploadAssetsWithToken(accessToken, projectId, cwd, onProgress) {
@@ -485,7 +533,9 @@ async function uploadAssetsWithToken(accessToken, projectId, cwd, onProgress) {
   const assetFiles = listAssetsFromDir(cwd);
   if (assetFiles.length === 0) return 0;
 
-  // Fetch existing filenames so we can skip unchanged files
+  // Fetch existing files so we can skip unchanged ones. We MUST treat a
+  // non-OK response as fatal: continuing with an empty list would re-upload
+  // every asset and (when filenames collide) leave duplicate user_files rows.
   const listRes = await fetch(
     `${SUPABASE_URL}/functions/v1/list-files?project_id=${encodeURIComponent(projectId)}`,
     {
@@ -495,13 +545,28 @@ async function uploadAssetsWithToken(accessToken, projectId, cwd, onProgress) {
       },
     },
   );
-  const listData = listRes.ok ? await listRes.json() : null;
-  const existing = new Set((listData?.files || []).map((f) => f.filename));
+  if (!listRes.ok) {
+    const text = await listRes.text().catch(() => '');
+    const err = new Error(`Failed to list project files: HTTP ${listRes.status}${text ? ` — ${text}` : ''}`);
+    err.status = listRes.status;
+    throw err;
+  }
+  const listData = await listRes.json();
+  const existingByName = new Map(
+    (listData?.files || []).map((f) => [f.filename, { id: f.id, content_hash: f.content_hash }]),
+  );
 
   let uploaded = 0;
   for (const filename of assetFiles) {
-    if (existing.has(filename)) continue;
     const filePath = path.join(cwd, 'assets', filename);
+    const localHash = hashFile(filePath);
+    const existing = existingByName.get(filename);
+
+    if (existing && existing.content_hash === localHash) continue;
+
+    if (existing) {
+      await deleteFileWithToken(accessToken, existing.id);
+    }
     await uploadAssetWithToken(accessToken, projectId, filePath, filename);
     if (onProgress) onProgress(filename);
     uploaded++;
@@ -645,4 +710,5 @@ module.exports = {
   pushWithToken,
   invokePublishBuild,
   uploadAssetsWithToken,
+  hashFile,
 };

package/templates/PROJECT_AGENT.template.md

@@ -13,11 +13,59 @@ This project was created with the Micropage CLI and is designed to be friendly t
   - `components-hero-variants.page` — multiple hero section variants (single CTA, image + copy, centered hero).
   - `components-pricing-and-forms.page` — pricing table (three tiers) and a richer contact/quote form, including an `img: <- pricing-cards` example.
 - `assets/logo.svg` and `assets/favicon.svg` — default logo and favicon for new projects (uploaded on push). `.page` files reference the stored filename: `logo: <- logo.svg` / `favicon: <- favicon.svg`.
+- `posts/` — post files (blog/newsletter content), one Markdown file per post. See "Posts" below.
+
+## Posts
+
+Each file in `posts/*.md` is one post: YAML front-matter + a Markdown body, pushed with `micropage posts push`.
+
+```markdown
+---
+title: Launching our new dashboard
+slug: launching-new-dashboard   # optional; defaults to the filename minus a leading date prefix and .md
+description: A quick look at what's new.
+visibility: listed              # listed | unlisted | none (default: listed)
+hero: launch-hero.png           # optional; local file, existing uploaded asset filename, or absolute URL
+email: true                     # optional; send to a subscriber list (default: false)
+list: Newsletter                # required when email is true; must match a newsletter form name exactly
+subject: We just shipped something new
+preview: See what's new in this release
+---
+
+Body content in Markdown. Local image refs like `![alt](screenshot.png)` are
+uploaded automatically and rewritten to hosted URLs on push.
+```
+
+A companion image file next to the post (`posts/launch.md` + `posts/launch.png`) is used as the hero automatically, taking priority over `hero:` in front-matter.
+
+Commands:
+- `micropage posts push` — upload local `posts/*.md` (create or update by slug); never deletes remote posts.
+- `micropage posts pull` — write remote posts to local `posts/*.md` files.
+- `micropage posts list` — list remote posts.
+- `micropage posts rm <slug>` — delete a post remotely (local file is untouched).
+
+## The `.page` grammar (closed vocabulary)
+
+Micropage is a line-oriented markup with a small, fixed set of tags — one element per line, no nesting, no inventing names. The whole grammar is roughly:
+
+- File shape: a `[site]` block (title, description, logo, favicon, lang, colors, theme_color, og_image), optional `[nav]` and `[footer]`, then one or more page blocks like `[Home -> /]` / `[About -> /about]`.
+- Sections inside a page: `/// hero`, `/// section`, and (rarely) `/// html`. Both `/// hero` and `/// section` take optional `align:center` and `bg:primary|secondary|muted|success|info`.
+- Elements (~30 legal tags): `h1:`–`h5:`, `p:`, `small:`, `icon: bi bi-name`, `img: <- filename`, `button:`, `btn-secondary:`, `btn-outline:`, `link:`, `col:`, and form tags `form:`, `input:` (trailing `*` = required), `text:`, `textarea:`, `select: Label [A, B]`, `checkboxes:`, `radios:`, `submit:`.
+- Images use the `<- filename` convention (e.g. `img: <- product-dashboard`); the file must be uploaded to the project. Don't hardcode random remote URLs unless asked.
+- Colors and typography come from the `[site]` block, not from inline styles.
+
+This is a summary. The canonical, always-current grammar lives at `https://micropage.sh/llms.txt` — read it before generating or heavily editing `.page` content.
+
+<!-- PROJECT_TONE: (optional) one line describing this project's voice/tone for the agent. -->
 
 ## How to propose edits safely
 
-- Prefer editing existing `.page` files instead of introducing new formats.
-- Keep the Micropage DSL valid — follow the patterns used in the `examples/` folder.
+- Prefer editing existing `.page` files in place instead of introducing new formats or new files.
+- Keep the Micropage DSL valid — use only the tags above and follow the patterns in the `examples/` folder.
+- Do not invent element names or new components, and do not emit React, Tailwind class soup, or custom HTML. Avoid `/// html` unless explicitly asked for raw markup.
+- Do not wrap the file in markdown fences when writing it back — the `.page` file is not a Markdown document.
+- Keep structure stable across edits: change copy and reorder before adding or removing sections.
+- Read the current `[site]` block and reuse its declared colors; never introduce inline colors.
 - When creating alternative versions of a section, consider:
   - Copying the original block into `examples/` and annotating it there.
   - Proposing a diff-style change rather than rewriting entire files.
@@ -26,6 +74,7 @@ This project was created with the Micropage CLI and is designed to be friendly t
 
 For full documentation of the Micropage format and features, see:
 
-- `https://docs.micropage.sh`
+- `https://micropage.sh/llms.txt` — the canonical, machine-readable grammar (start here when editing `.page` files)
+- `https://docs.micropage.sh` — human-facing docs
 
-You can use the examples in this project as concrete references when generating or modifying `.page` content.*** End Patch***}"/>
+You can use the examples in this project as concrete references when generating or modifying `.page` content.