@micropage-sh/cli 2.0.8 → 2.6.1

package/src/commands/submissions.js

@@ -13,6 +13,11 @@ function formatCliFieldValue(value) {
   return String(value);
 }
 
+/** Spam is `flagged_at IS NOT NULL`; the inbox is everything else. */
+function applySpamFilter(query, spam) {
+  return spam ? query.not('flagged_at', 'is', 'null') : query.is('flagged_at', 'null');
+}
+
 async function list(options = {}) {
   const cwd = process.cwd();
   const config = getProjectConfig(cwd);
@@ -21,12 +26,17 @@ async function list(options = {}) {
     process.exit(1);
   }
 
+  const spam = Boolean(options.spam);
+  const columns = spam
+    ? 'id,form_id,form_name,page_url,created_at,form_index,spam_reason,flagged_at,flagged_by'
+    : 'id,form_id,form_name,page_url,created_at,form_index';
+
   let submissions;
   try {
-    submissions = await db
-      .from('form_submissions')
-      .select('id,form_id,form_name,page_url,created_at,form_index')
-      .eq('project_id', config.projectId)
+    submissions = await applySpamFilter(
+      db.from('form_submissions').select(columns).eq('project_id', config.projectId),
+      spam,
+    )
       .order('created_at', 'desc')
       .get();
   } catch (err) {
@@ -36,7 +46,7 @@ async function list(options = {}) {
   }
 
   if (!Array.isArray(submissions) || submissions.length === 0) {
-    console.log('No form submissions.');
+    console.log(spam ? 'No spam submissions.' : 'No form submissions.');
     return;
   }
 
@@ -45,14 +55,20 @@ async function list(options = {}) {
     return;
   }
 
-  const rows = submissions.map((s) => [
-    s.id.slice(0, 8) + '…',
-    s.form_id ? s.form_id.slice(0, 8) + '…' : '-',
-    s.form_name || '-',
-    s.page_url || '-',
-    formatDate(s.created_at),
-  ]);
-  formatTable(rows, ['ID (short)', 'Form ID', 'Form', 'Page URL', 'Submitted']);
+  const rows = submissions.map((s) => {
+    const row = [
+      s.id.slice(0, 8) + '…',
+      s.form_id ? s.form_id.slice(0, 8) + '…' : '-',
+      s.form_name || '-',
+      s.page_url || '-',
+      formatDate(s.created_at),
+    ];
+    if (spam) row.push(s.spam_reason || '-');
+    return row;
+  });
+  const headers = ['ID (short)', 'Form ID', 'Form', 'Page URL', 'Submitted'];
+  if (spam) headers.push('Spam reason');
+  formatTable(rows, headers);
 }
 
 async function show(id, options = {}) {
@@ -85,6 +101,9 @@ async function show(id, options = {}) {
   }
 
   console.log('ID:         ', submission.id);
+  if (submission.flagged_at) {
+    console.log('Spam:       ', submission.spam_reason || 'yes');
+  }
   console.log('Form ID:    ', submission.form_id || '-');
   console.log('Form:       ', submission.form_name || '-');
   console.log('Page URL:   ', submission.page_url || '-');
@@ -112,12 +131,14 @@ async function exportSubmissions(options = {}) {
     process.exit(1);
   }
 
+  const spam = Boolean(options.spam);
+
   let submissions;
   try {
-    submissions = await db
-      .from('form_submissions')
-      .select('*')
-      .eq('project_id', config.projectId)
+    submissions = await applySpamFilter(
+      db.from('form_submissions').select('*').eq('project_id', config.projectId),
+      spam,
+    )
       .order('created_at', 'desc')
       .get();
   } catch (err) {
@@ -127,7 +148,7 @@ async function exportSubmissions(options = {}) {
   }
 
   if (!Array.isArray(submissions) || submissions.length === 0) {
-    console.log('No form submissions to export.');
+    console.log(spam ? 'No spam submissions to export.' : 'No form submissions to export.');
     return;
   }
 
@@ -137,7 +158,7 @@ async function exportSubmissions(options = {}) {
     process.exit(1);
   }
 
-  const defaultName = `submissions.${format}`;
+  const defaultName = spam ? `submissions-spam.${format}` : `submissions.${format}`;
   const outFile = options.output
     ? path.isAbsolute(options.output)
       ? options.output
@@ -158,6 +179,7 @@ async function exportSubmissions(options = {}) {
         'build_id',
         'payload_json',
       ];
+      if (spam) header.push('spam_reason');
       const escapeCell = (value) => {
         if (value === null || value === undefined) return '';
         const str = String(value);
@@ -168,8 +190,8 @@ async function exportSubmissions(options = {}) {
       };
       const lines = [
         header.join(','),
-        ...submissions.map((s) =>
-          [
+        ...submissions.map((s) => {
+          const cells = [
             s.id,
             s.created_at,
             s.page_url || '',
@@ -178,8 +200,10 @@ async function exportSubmissions(options = {}) {
             s.form_index ?? '',
             s.build_id || '',
             JSON.stringify(s.payload || {}),
-          ].map(escapeCell).join(','),
-        ),
+          ];
+          if (spam) cells.push(s.spam_reason || '');
+          return cells.map(escapeCell).join(',');
+        }),
       ];
       fs.writeFileSync(outFile, lines.join('\n'), 'utf8');
     }
@@ -188,7 +212,8 @@ async function exportSubmissions(options = {}) {
     process.exit(1);
   }
 
-  console.log(`Exported ${submissions.length} submission(s) → ${outFile}`);
+  const noun = spam ? 'spam submission(s)' : 'submission(s)';
+  console.log(`Exported ${submissions.length} ${noun} → ${outFile}`);
 }
 
-module.exports = { list, show, exportSubmissions };
+module.exports = { list, show, exportSubmissions, applySpamFilter };

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();
 
@@ -218,8 +219,9 @@ const subCmd = program.command('submissions').description('View form submissions
 
 subCmd
   .command('list')
-  .description('List form submissions for the current project')
+  .description('List form submissions for the current project (spam excluded)')
   .option('--json', 'Output as JSON')
+  .option('--spam', 'List only submissions flagged as spam')
   .action((opts) => submissions.list(opts));
 
 subCmd
@@ -230,15 +232,55 @@ subCmd
 
 subCmd
   .command('export')
-  .description('Export form submissions for the current project to a file')
+  .description('Export form submissions for the current project to a file (spam excluded)')
+  .option('--spam', 'Export only submissions flagged as spam')
   .option(
     '-f, --format <format>',
     'Output format: csv or json (default: csv)',
   )
   .option(
     '-o, --output <file>',
-    'Output file path (default: submissions.<format>)',
+    'Output file path (default: submissions.<format>, or submissions-spam.<format> with --spam)',
   )
   .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

@@ -207,6 +207,8 @@ function buildQuery(table) {
     select(cols) { _select = cols; return q; },
     eq(col, val) { filters.push(`${col}=eq.${val}`); return q; },
     in(col, vals) { filters.push(`${col}=in.(${vals.join(',')})`); return q; },
+    is(col, val) { filters.push(`${col}=is.${val}`); return q; },
+    not(col, op, val) { filters.push(`${col}=not.${op}.${val}`); return q; },
     order(col, dir = 'asc') { _order = `${col}.${dir}`; return q; },
     limit(n) { _limit = n; return q; },
 
@@ -299,6 +301,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 +338,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}`;
 }
 
@@ -353,6 +365,20 @@ async function getMaxDeployEventIdForBuild(buildId, accessToken = null) {
   return Number.isFinite(n) ? n : 0;
 }
 
+/**
+ * Highest build_deploy_events.id across the project, 0 when none. A cursor
+ * taken before a post change, when the build the server will rebuild is not
+ * known yet: event ids are global and the stream filters by build.
+ */
+async function getMaxDeployEventIdForProject(projectId) {
+  const url = `${SUPABASE_URL}/rest/v1/build_deploy_events?select=id&project_id=eq.${encodeURIComponent(String(projectId))}&order=id.desc&limit=1`;
+  const data = await request('GET', url, null);
+  const row = Array.isArray(data) ? data[0] : null;
+  if (!row || row.id == null) return 0;
+  const n = Number(row.id);
+  return Number.isFinite(n) ? n : 0;
+}
+
 /**
  * Stream build/deploy/archive events until a terminal event or the connection closes.
  * @param {string} bearerToken
@@ -418,7 +444,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;
             }
@@ -689,6 +721,7 @@ module.exports = {
   handleAuthError,
   getValidAccessToken,
   getMaxDeployEventIdForBuild,
+  getMaxDeployEventIdForProject,
   streamDeployEventsUntilDone,
   exchangeDeployTokenForAccessToken,
   pushWithToken,

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.