sitelines 1.0.0

package/scripts/serve.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// sitelines server - serves the viewer, the site (for live previews), and the change queue.
+// Usage: node serve.mjs [--root public] [--out .sitelines] [--port 4370]
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const viewerDir = path.join(here, '..', 'viewer');
+const args = parseArgs(process.argv.slice(2));
+const cwd = process.cwd();
+const outDir = path.resolve(cwd, args.out || '.sitelines');
+const flowPath = path.join(outDir, 'flow.json');
+const editsPath = path.join(outDir, 'edits.json');
+const viewsPath = path.join(outDir, 'views.json');
+const port = Number(args.port || 4370);
+
+if (!fs.existsSync(flowPath)) {
+  console.error(`sitelines: no scan at ${flowPath}`);
+  console.error('sitelines: run `sitelines scan` first (or `node scripts/scan.mjs`)');
+  process.exit(1);
+}
+const flow0 = JSON.parse(fs.readFileSync(flowPath, 'utf8'));
+const siteRoot = path.resolve(cwd, args.root || flow0.root || 'public');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8', '.json': 'application/json; charset=utf-8', '.svg': 'image/svg+xml',
+  '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.avif': 'image/avif',
+  '.gif': 'image/gif', '.ico': 'image/x-icon',
+  '.woff': 'font/woff', '.woff2': 'font/woff2', '.txt': 'text/plain; charset=utf-8', '.xml': 'application/xml',
+  '.webmanifest': 'application/manifest+json', '.map': 'application/json',
+};
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, `http://localhost:${port}`);
+  const p = decodeURIComponent(url.pathname);
+  try {
+    if (p === '/api/flow' && req.method === 'GET') return json(res, read(flowPath));
+    if (p === '/api/edits' && req.method === 'GET') return json(res, readEdits());
+    if (p === '/api/views' && req.method === 'GET') return json(res, readViews());
+    if (p === '/api/views' && req.method === 'POST') {
+      const body = await readBody(req);
+      const next = withBase(body);
+      write(viewsPath, next);
+      return json(res, next);
+    }
+    if (p === '/api/edits' && req.method === 'POST') {
+      const body = await readBody(req);
+      const edits = readEdits();
+      const edit = { id: `e${Date.now().toString(36)}${Math.floor(performance.now() * 1000 % 999)}`, at: new Date().toISOString(), status: 'pending', ...body };
+      edits.push(edit);
+      write(editsPath, edits);
+      log(`queued ${edit.op}: ${edit.summary || ''}`);
+      return json(res, edit);
+    }
+    if (p === '/api/edits' && req.method === 'DELETE') {
+      const id = url.searchParams.get('id');
+      const edits = readEdits().filter((e) => (id ? e.id !== id : false));
+      write(editsPath, edits);
+      return json(res, { ok: true, remaining: edits.length });
+    }
+    if (p === '/api/layout' && req.method === 'POST') {
+      const body = await readBody(req);
+      const flow = read(flowPath);
+      flow.layout = { ...flow.layout, ...(body.layout || {}) };
+      if (body.notes) flow.notes = { ...flow.notes, ...body.notes };
+      write(flowPath, flow);
+      return json(res, { ok: true });
+    }
+    if (p === '/api/rescan' && req.method === 'POST') {
+      const { spawnSync } = await import('node:child_process');
+      const r = spawnSync(process.execPath, [path.join(here, 'scan.mjs'), '--root', siteRoot, '--out', outDir], { cwd, encoding: 'utf8' });
+      return json(res, { ok: r.status === 0, out: (r.stdout || '') + (r.stderr || '') });
+    }
+    if (p.startsWith('/site/') || p === '/site') {
+      const sub = p.replace(/^\/site/, '') || '/';
+      // a previewed page must never install a service worker: it would cache the
+      // preview responses and then serve them back for every later preview.
+      if (/\/(sw|service-worker)\.js$/i.test(sub)) {
+        res.writeHead(200, { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-store' });
+        return res.end("self.addEventListener('install',()=>self.skipWaiting());try{self.registration.unregister()}catch(e){}\n");
+      }
+      return serveStatic(res, siteRoot, sub, true, req);
+    }
+    return serveStatic(res, viewerDir, p === '/' ? '/index.html' : p, false, req);
+  } catch (e) {
+    res.writeHead(500, { 'content-type': 'text/plain' });
+    res.end(String(e && e.stack || e));
+  }
+});
+
+server.on('error', (e) => {
+  if (e.code === 'EADDRINUSE') {
+    console.error(`sitelines: port ${port} is already in use - try \`sitelines serve --port ${port + 1}\``);
+    process.exit(1);
+  }
+  throw e;
+});
+
+// Loopback only. This server hands out every file under the scan root and has
+// endpoints that write to disk and spawn a rescan, so it must not be reachable
+// from the network just because you are on shared wifi. --host is opt-in.
+const host = args.host === true ? '0.0.0.0' : (args.host || '127.0.0.1');
+
+server.listen(port, host, () => {
+  console.log(`sitelines  http://localhost:${port}`);
+  console.log(`  previews from ${posix(path.relative(cwd, siteRoot)) || '.'}  |  changes -> ${posix(path.relative(cwd, editsPath))}`);
+  if (host !== '127.0.0.1') console.log(`  WARNING: listening on ${host}, so anyone on this network can read your source`);
+});
+
+const SW_GUARD = `<script>(function(){try{var n=navigator;if(!n.serviceWorker)return;
+n.serviceWorker.getRegistrations&&n.serviceWorker.getRegistrations().then(function(rs){rs.forEach(function(r){r.unregister()})}).catch(function(){});
+Object.defineProperty(n,'serviceWorker',{configurable:true,get:function(){return{register:function(){return Promise.resolve({unregister:function(){return Promise.resolve(true)},addEventListener:function(){}})},getRegistration:function(){return Promise.resolve(undefined)},getRegistrations:function(){return Promise.resolve([])},ready:new Promise(function(){}),controller:null,addEventListener:function(){}}}});}catch(e){}})();</script>`;
+
+// shown inside a preview frame when the route has no file on disk
+const MISSING_PAGE = `<!doctype html><meta charset="utf-8"><title>Not on disk</title>
+<style>
+  :root{color-scheme:light dark}
+  body{margin:0;height:100vh;display:grid;place-content:center;gap:.4rem;text-align:center;
+    font:13px/1.6 ui-sans-serif,-apple-system,"Segoe UI",Roboto,sans-serif;
+    background:#f6f7f9;color:#454c59}
+  b{color:#10131a;font-size:14px}
+  code{font-family:ui-monospace,"Cascadia Mono",Menlo,Consolas,monospace}
+  @media (prefers-color-scheme:dark){
+    body{background:#101317;color:#9aa1ad} b{color:#eceef2}
+  }
+</style>
+<b>No file on disk</b>
+<span>This route is a dynamic route or a dead link.</span>`;
+
+// `resolved.startsWith(base)` is not a containment check: with base /srv/public a
+// request resolving to /srv/public-private/secret passes it. Compare the relative
+// path instead, which is empty or a plain descendant only when truly inside.
+function inside(base, file) {
+  const rel = path.relative(path.resolve(base), path.resolve(file));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function serveStatic(res, base, p, isSite, req) {
+  let file = path.join(base, p);
+  if (!inside(base, file)) { res.writeHead(403); return res.end('forbidden'); }
+  if (fs.existsSync(file) && fs.statSync(file).isDirectory()) file = path.join(file, 'index.html');
+  if (!fs.existsSync(file)) {
+    const alt = file.replace(/\/$/, '') + '.html';
+    if (fs.existsSync(alt)) file = alt;
+    else { res.writeHead(404, { 'content-type': 'text/html; charset=utf-8' }); return res.end(MISSING_PAGE); }
+  }
+  // preview assets are hit once per page card and again every time the map reloads,
+  // so let the browser keep them: revalidate cheaply against mtime+size
+  const st = fs.statSync(file);
+  const etag = `W/"${st.size.toString(36)}-${st.mtimeMs.toString(36)}${isSite ? '-s' : ''}"`;
+  if (req && req.headers['if-none-match'] === etag) {
+    res.writeHead(304, { etag, 'cache-control': 'public, max-age=30, must-revalidate' });
+    return res.end();
+  }
+  let body = fs.readFileSync(file);
+  const type = MIME[path.extname(file).toLowerCase()] || 'application/octet-stream';
+  if (isSite && type.startsWith('text/html')) {
+    const html = body.toString('utf8');
+    body = Buffer.from(/<head[^>]*>/i.test(html) ? html.replace(/<head[^>]*>/i, (m) => m + SW_GUARD) : SW_GUARD + html, 'utf8');
+  }
+  res.writeHead(200, { 'content-type': type, etag, 'cache-control': 'public, max-age=30, must-revalidate' });
+  res.end(body);
+}
+
+function readEdits() { return fs.existsSync(editsPath) ? JSON.parse(fs.readFileSync(editsPath, 'utf8')) : []; }
+
+// Views are user-editable include/exclude sets. Exactly one is seeded: the base
+// view, which always shows every page and never carries rules. Users add their
+// own from the viewer, and agents add them by appending to this file.
+function readViews() {
+  if (fs.existsSync(viewsPath)) return withBase(read(viewsPath));
+  const v = withBase({ active: 'all', views: [] });
+  write(viewsPath, v);
+  return v;
+}
+
+// the base view is a guarantee, not a default: restore it if a hand-edit drops it
+function withBase(cfg) {
+  const views = Array.isArray(cfg.views) ? cfg.views.filter((v) => v && v.id) : [];
+  const i = views.findIndex((v) => v.base || v.id === 'all');
+  const base = { ...(i > -1 ? views[i] : {}), id: 'all', label: 'everything', base: true, include: [], exclude: [] };
+  if (i > -1) views.splice(i, 1);
+  const out = { active: cfg.active || 'all', views: [base, ...views] };
+  if (!out.views.some((v) => v.id === out.active)) out.active = 'all';
+  return out;
+}
+function read(f) { return JSON.parse(fs.readFileSync(f, 'utf8')); }
+function write(f, v) { fs.mkdirSync(path.dirname(f), { recursive: true }); fs.writeFileSync(f, JSON.stringify(v, null, 2)); }
+function json(res, v) { res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(v)); }
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    let b = '';
+    req.on('data', (c) => { b += c; if (b.length > 1e6) req.destroy(); });
+    req.on('end', () => { try { resolve(b ? JSON.parse(b) : {}); } catch (e) { reject(e); } });
+    req.on('error', reject);
+  });
+}
+function log(m) { console.log(`sitelines: ${m}`); }
+function posix(p) { return p.split(path.sep).join('/'); }
+function parseArgs(a) {
+  const o = {};
+  for (let i = 0; i < a.length; i++) if (a[i].startsWith('--')) { const k = a[i].slice(2); o[k] = a[i + 1] && !a[i + 1].startsWith('--') ? a[++i] : true; }
+  return o;
+}

package/skill/AGENTS.md

@@ -0,0 +1,61 @@
+<!-- sitelines:begin -->
+## sitelines: the site navigation map
+
+This project uses [sitelines](https://github.com/Jkaos725/sitelines) to map its navigation. Every page and
+every link, button, redirect, and form between them is scanned into `.sitelines/flow.json`, and changes the
+user makes in the browser map are queued into `.sitelines/edits.json` for you to implement.
+
+### Show the map
+
+```bash
+npx sitelines scan --root public     # -> .sitelines/flow.json
+npx sitelines serve --root public    # -> http://localhost:4370
+```
+
+Run `serve` in the background and give the user the URL. Never block on it. `--root` is the directory
+holding the pages; it is auto-detected if omitted. The viewer never writes to the site.
+
+### Answer questions from flow.json, not from grep
+
+`.sitelines/flow.json` already holds every navigation edge with its trigger text, `file`, and `line`. Read
+it to answer "where does this button go", "what links to this page", or "what is unreachable" instead of
+searching the codebase by hand.
+
+`flow.json.issues` carries, in priority order: `deadLinks` (a control that goes nowhere, always a real
+bug), `orphans` and `unreachable` (no inbound link, or not reachable from the entry by clicking), `deep`
+(more than 3 clicks from the entry), `deadEnds` (no exits), and `hubs` (more than 12 exits). Report these
+with `file:line` and let the user choose before changing anything.
+
+### Apply the user's queued changes
+
+When the user says "apply my sitelines changes" or similar, read `.sitelines/edits.json` and implement
+every entry whose `status` is `pending`:
+
+| op | what to do in code |
+| --- | --- |
+| `add-link` | add the anchor or button on `from` (in the region named by `where`, matching sibling markup and the project's conventions) navigating to `to`, text = `label`; `via: redirect` means a JS `location.href`, `via: form` means a form `action` |
+| `remove-link` | delete the control at `file:line`, and any handler left dangling |
+| `relabel` | change the visible text `oldLabel` to `label` at `file:line`; keep `aria-label` and `title` in sync |
+| `retarget` | change the destination `to` to `newTo` at `file:line` |
+| `add-page` | create the page at `route` following the repo's existing page scaffold (copy the closest sibling page: same head, nav, footer, asset versioning) |
+| `delete-page` | delete the page file and every link pointing at it (query the flow for edges whose `to` equals the route) |
+
+Line numbers are from the last scan, so **match on the label text first** and treat the number as a hint.
+
+After applying: re-run `sitelines scan`, confirm the intended links exist and no new dead link appeared,
+then set `"status": "applied"` on each entry you implemented. Keep them as history; do not delete them.
+Report what changed as `file:line`.
+
+Obey this repo's own conventions when writing: read `CLAUDE.md`, `AGENTS.md`, or any project docs for
+cache-busting query strings, nav partials, route registration, and tests that must run.
+
+### State
+
+```
+.sitelines/flow.json     the scan, plus the user's card positions and notes
+.sitelines/views.json    saved views; "everything" is the base view and always shows every page
+.sitelines/edits.json    the change queue, including applied history
+```
+
+`layout` and `notes` in `flow.json` are user data. The scanner preserves them; never hand-edit them away.
+<!-- sitelines:end -->

package/skill/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: sitelines
+description: Map, audit, and edit a website's navigation. Scans the repo for pages and every link, button, redirect, and form that moves between them, then serves an interactive map where each card is a page with a live preview and each wire is a navigation. Flags dead links, orphans, dead ends, and pages buried too deep. Changes made in the browser are queued and implemented in the code by the agent. Use when the user says "show the site flow", "map the app", "user flow", "site map", "where does this button go", "add a page to the flow", "find dead links", "optimize navigation", or invokes /sitelines.
+---
+
+# sitelines - a site's navigation as a map you can edit
+
+Three verbs: **show** (scan and serve the map), **change** (queue navigation edits in the browser),
+**improve** (act on the flagged issues). The map is the source of truth for what the code does; the change
+queue is the source of truth for what the user wants different.
+
+## Show the map
+
+```bash
+node <skill-dir>/scripts/scan.mjs --root public      # -> .sitelines/flow.json
+node <skill-dir>/scripts/serve.mjs --root public     # -> http://localhost:4370
+```
+
+Run `serve.mjs` with `run_in_background: true`, then give the user the URL. Never block on it.
+
+- `--root` = the directory holding the site's pages. Auto-detected if omitted (`public`, `site`, `www`,
+  `static`, `src/pages`, `src/routes`, `src/app`, `app/pages`, `pages`, `app`, `docs`).
+- `--out` = state directory, default `.sitelines/` in the repo. Suggest adding it to `.gitignore` unless
+  the user wants to share the map's layout and notes with their team.
+- `--port` = default 4370.
+- Node 18+, zero dependencies, no build step.
+
+If the user installed the npm package instead, `sitelines scan` and `sitelines serve` do the same thing.
+
+If they only want to see what the tool does, `sitelines demo` copies the bundled 20-page example site into
+`./sitelines-demo` and maps that. The example carries deliberate faults (two dead links, three orphans, a
+dead end, a page four clicks deep), so every part of the map has something to show.
+
+Previews are served from disk by `serve.mjs` at `/site<route>`, so no dev server is needed. Two deliberate
+defaults:
+
+- **Page JavaScript is off** in previews (iframes get an empty `sandbox`). Real pages that poll, retry a
+  dead API, or animate will otherwise peg the renderer forty iframes over. Markup and CSS still render. The
+  **Run page JavaScript** toggle under Layers turns it back on.
+- **Service workers are neutralised** for anything under `/site/`, because the site's own worker would
+  otherwise cache the preview responses and serve them back for every later preview.
+
+Thumbnails mount two at a time and switch off past 60 pages. For pages that need real data (auth, an API),
+run the user's own dev server and use the page's **Open** button against it instead.
+
+## What the scanner extracts
+
+Cards are pages (`*.html`, or framework page files if there is no HTML). Wires are navigations, each
+carrying the **trigger text** (the actual button or link label), the file, and the line:
+
+| source | how it is found |
+| --- | --- |
+| `<a href>` | label = link text |
+| `<button>`/`<div>` with `onclick="location.href=…"`, `data-href`, `data-nav`, `formaction` | label = element text |
+| `<form action>` | label = `POST form` |
+| `<meta http-equiv=refresh>` | label = `meta refresh` |
+| JS: `location.href/assign/replace`, `window.open`, `router.push/replace`, `navigate(…)`, `href="…"` in templates | trigger inferred from the nearest `getElementById`/`querySelector` above the call |
+
+Targets that resolve to no file become **dead-link** cards. `/api/*` and `http(s)://` become side cards,
+hidden by default behind the API and external toggles.
+
+**Site-wide links fold away by default.** A link appearing from more than 4 pages is tagged `repeated` by
+the scanner (a header, a footer, a nav partial), as is any link wired by a script more than 4 pages include
+(`js-shared`). Both hide behind **Layers → Site-wide nav and footer links**, and the sidebar reports the
+count it folded, for example `Links drawn 27 of 174`. This is a drawing decision only: depth, orphans,
+dead ends, and every other judgement are computed from the complete link set, so a page reachable only
+through the footer is never reported as an orphan.
+
+Re-running the scan preserves card positions and notes.
+
+## Improve
+
+`flow.json.issues` and the **Issues** list carry, in priority order:
+
+1. **Dead links** - a control goes nowhere. Always a real bug: fix the href or create the page.
+2. **Orphan / unreachable** - no inbound link, or not reachable from the entry by clicking. Link it or delete it.
+3. **Deep** - more than 3 clicks from the entry. Propose a shortcut from a hub.
+4. **Dead ends** - no exits. Add a next step or a way back.
+5. **Hubs** - more than 12 exits on one page. Propose grouping.
+
+Report these as findings with `file:line`, and only change code once the user picks.
+
+## Apply the user's changes
+
+The browser queues changes to `.sitelines/edits.json`; the viewer never writes to the site. When the user
+says "apply my sitelines changes" (or similar), read that file and implement each `pending` entry in the
+real code:
+
+```bash
+cat .sitelines/edits.json
+```
+
+| op | what to do in code |
+| --- | --- |
+| `add-link` | add the anchor or button on `from` (in the region named by `where`, matching sibling markup and the project's design system) navigating to `to`, text = `label`; `via: redirect` means a JS `location.href` in that page's script, `via: form` means a form `action` |
+| `remove-link` | delete the control at `file:line`, and any handler left dangling |
+| `relabel` | change the visible text `oldLabel` to `label` at `file:line`; keep `aria-label` and `title` in sync |
+| `retarget` | change the destination `to` to `newTo` at `file:line` |
+| `add-page` | create the page at `route` following the repo's existing page scaffold (copy the closest sibling page: same head, nav, footer, asset versioning) |
+| `delete-page` | delete the page file and every link pointing at it (search the flow for inbound edges first) |
+
+`references/edit-protocol.md` has the exact JSON shape of every op.
+
+After applying: re-run `scan.mjs`, confirm the intended links now exist and no new dead links appeared, then
+mark each applied entry by setting `"status": "applied"` in `.sitelines/edits.json`. Keep them as history;
+do not silently drop them. Report what changed as `file:line`.
+
+Obey the repo's own conventions when writing. Read `CLAUDE.md`, `AGENTS.md`, or any project skill for
+cache-busting query strings, nav partials, route registration, or tests that must run.
+
+## Views, sections, and state
+
+**One view is seeded**: `everything`, the base view. It always shows every page and never carries a rule.
+Filtering while it is active creates a new view instead of narrowing the one complete picture of the site.
+
+To add a view, append to `.sitelines/views.json` and its tab appears. Do this rather than touching the
+viewer code when the user asks for a different split:
+
+```json
+{
+  "active": "all",
+  "views": [
+    { "id": "all",  "label": "everything", "base": true, "include": [], "exclude": [] },
+    { "id": "docs", "label": "docs only",  "include": ["/docs/**"], "exclude": [] }
+  ]
+}
+```
+
+Each view is `{id, label, include[], exclude[], collapsed[], entry?}`. Patterns: `/admin/**` (subtree),
+`/admin/` (exact), `/admin/*` (one level), `*report*` (substring). A non-empty `include` means *only* those.
+The base view is a guarantee: the server restores it if a hand-edit drops it, and strips any rule added to
+it. Users also add views from the **+** on the tab bar, the rule box in the sidebar, and **Hide from this
+view** in the inspector.
+
+- Hiding a page removes it **and every wire touching it** from that view; the sidebar lists what is hidden.
+- **Sections**: pages sharing a top-level directory get a labelled backdrop. Click the backdrop label (or
+  the card's **Expand**) to collapse the whole section into one card. Internal links fold away and the
+  collapsed section keeps **one wire per neighbour**, labelled `N links`, with every underlying control in
+  its hover tooltip.
+- **Ports**: dots down each card's left (entrances) and right (exits) edge. Hover one, or any wire, for the
+  button text, both routes, the trigger kind, and `file:line`; the wire lights up. Click a port to jump to
+  the page at the other end.
+- The sidebar's **Entry points** lists where a visit can start; **Leaves the site** lists where the site
+  sends people (API, external, dead).
+
+## Viewer controls (tell the user these)
+
+- Drag the background to pan, wheel to zoom, `f` to fit, `/` to search, `Escape` to cancel, drag a card to
+  move it (the position is saved).
+- **Layers**: site-wide nav and footer links, API endpoints, external links, live previews, run page JavaScript.
+- Keys `1` `2` `3` switch view tabs; **+** on the tab bar makes a new view.
+- Click a card to inspect it: full-size live preview at mobile, tablet, or desktop width, its exits, its
+  entrances, and notes.
+- **+ Link** (or `e`), then click a destination, proposes a new control.
+- Edit an exit's text, or change its destination in the dropdown, to queue a rename or retarget. The ✕
+  queues a removal.
+- **+ Page** proposes a new page, optionally linked from the selected one.
+- **Changes** is the queue; **Copy prompt** gives the user the exact sentence to paste back.
+- The theme follows the OS and can be overridden with the sun/moon button.
+
+## Files
+
+```
+DESIGN.md                     the viewer's visual system - read before touching viewer/style.css
+scripts/scan.mjs              static analysis -> .sitelines/flow.json
+scripts/serve.mjs             viewer + site preview server + change queue API (node:http, no deps)
+scripts/install-skill.mjs     copies this skill into a Claude Code skills directory
+viewer/                       the map UI (index.html, app.js, style.css)
+references/edit-protocol.md   exact JSON shape of every queued change
+```

package/skill/references/edit-protocol.md

@@ -0,0 +1,57 @@
+# sitelines change protocol
+
+`.sitelines/edits.json` is a JSON array, append-only from the viewer. Every entry:
+
+```json
+{ "id": "e1m2k3", "at": "2026-07-28T18:03:11.000Z", "status": "pending", "op": "...", "summary": "human sentence" }
+```
+
+`status`: `pending`, then the agent implements it and sets `applied`, keeping the record. Use `rejected`
+with a `reason` if the user decides against it after discussion.
+
+## Ops
+
+### add-link
+```json
+{ "op":"add-link", "from":"/home/", "to":"/pricing/", "label":"See pricing", "via":"link|button|redirect|form", "where":"hero CTA row" }
+```
+Add a real control on the `from` page. `where` is a free-text hint from the user. If it is empty, place the
+control next to the closest existing sibling control and say where you put it.
+
+### remove-link
+```json
+{ "op":"remove-link", "from":"/home/", "to":"/beta/", "label":"Try beta", "file":"home/index.html", "line":142 }
+```
+`file` is relative to the scan root. The line comes from the last scan, so verify by matching the label
+rather than trusting the number.
+
+### relabel
+```json
+{ "op":"relabel", "from":"/home/", "to":"/join/", "oldLabel":"Sign up", "label":"Get started", "file":"home/index.html", "line":88 }
+```
+
+### retarget
+```json
+{ "op":"retarget", "from":"/home/", "to":"/login/", "newTo":"/join/", "label":"Get started", "file":"home/index.html", "line":88 }
+```
+
+### add-page
+```json
+{ "op":"add-page", "route":"/pricing/", "label":"Pricing" }
+```
+Scaffold from the closest sibling page in the same section, so head tags, nav, footer, asset versioning,
+and auth guards match. Usually paired with an `add-link` entry.
+
+### delete-page
+```json
+{ "op":"delete-page", "route":"/beta/", "file":"beta/index.html" }
+```
+Also remove every inbound link (query the flow for edges whose `to` equals the route).
+
+## Rules
+
+1. The viewer never writes to the site. Every source change comes from the agent, after the user asks.
+2. Re-run `scan.mjs` after applying. A fix that creates a new dead link is not done.
+3. `flow.json` fields `layout` (card positions) and `notes` (per-route text) are user data. The scanner
+   preserves them; never hand-edit them away.
+4. Line numbers and `file` paths refer to the state at scan time. Match on the label text first.