sitelines 1.0.0

package/DESIGN.md

@@ -0,0 +1,129 @@
+# sitelines viewer - design
+
+The authority for `viewer/style.css`. Read this before changing anything visual.
+
+**Mode: Operate.** The visitor is a developer holding a question: *where does this button go, and what did I break?*
+Scanability, state legibility, and keyboard reach outrank expression. The brand lives in precision, not in
+personality. If a decision makes the map prettier and the answer slower, the decision is wrong.
+
+## World
+
+A **plan view**. The map is a technical drawing of a site: pages are cards laid out on a measured ground,
+depth columns are ruled like a drafting grid, links are drawn wires with a legible arrowhead. Nothing is
+themed, gamified, or narrated. The visual interest comes from real density and real hierarchy: forty live
+page previews arranged by how many clicks they sit from the front door.
+
+The tool runs beside an editor, all day, in whatever ambient light the developer already chose. So it ships
+**both themes**, follows `prefers-color-scheme` by default, and offers a manual override that persists.
+Neither theme is the "real" one.
+
+## Tokens
+
+Every value below is a CSS custom property in `:root`, re-declared under `[data-theme="dark"]` and
+`@media (prefers-color-scheme: dark)`. Nothing in the stylesheet may hardcode a color.
+
+| role | light | dark |
+| --- | --- | --- |
+| `--bg` canvas | `#f5f6f8` | `#0d0f12` |
+| `--surface` cards, panels, bar | `#ffffff` | `#16191e` |
+| `--surface-2` insets, fields | `#eef0f4` | `#1d2127` |
+| `--surface-3` pressed, hovered inset | `#e7eaef` | `#252a32` |
+| `--text` primary | `#10131a` | `#eceef2` |
+| `--text-2` secondary | `#3f4653` | `#b9bfc9` |
+| `--text-3` tertiary | `#5c6472` | `#949ba6` |
+| `--text-4` quietest legible | `#6f7784` | `#7f8794` |
+| `--line` hairline | `#e2e5ea` | `#262b33` |
+| `--line-2` defined edge | `#cdd2da` | `#363c46` |
+| `--wire` link stroke | `#99a1af` | `#4e5663` |
+
+Every text token clears 4.5:1 against the surface it is used on, in both themes. `--text-4` is the floor,
+not a decorative gray: there is no token below AA.
+
+**One accent, locked:** `--accent` `#2563eb` / `#5b9cff`. It means *selected, primary, interactive*. It is
+the only non-status hue on the surface.
+
+**Three status hues, each a meaning:**
+
+| token | meaning | light | dark |
+| --- | --- | --- | --- |
+| `--danger` | a link that goes nowhere | `#d92d20` | `#ff6b5e` |
+| `--warn` | queued, proposed, not yet in the code | `#b25e09` | `#f0b132` |
+| `--ok` | an entry point, a way in | `#067a5b` | `#35c99a` |
+
+Adding a color means adding a row to the legend. There is no decorative color.
+
+## Link kind is drawn, not colored
+
+A wire's **hue carries state** (normal, dead, queued, traced). A wire's **style carries kind**, so the four
+navigation mechanisms stay distinguishable without spending four more hues:
+
+| kind | stroke |
+| --- | --- |
+| anchor / button | solid |
+| script navigation | dotted `1 4` |
+| redirect | dashed `8 5` |
+| form submit | solid, with a bar terminal at the source |
+| queued (proposed) | dashed `7 5`, `--warn`, heavier |
+
+## Shape
+
+One radius system, no exceptions:
+
+- `--r-1` **6px** - every interactive control: buttons, tabs, inputs, chips, badges, list rows.
+- `--r-2` **10px** - every surface: page cards, panels, popovers, the modal, the preview frame.
+- `--r-3` **14px** - containers that hold surfaces: the section backdrop.
+
+A pill, a circle, or a square-cornered control is a bug. The one intentional circle is the I/O port dot,
+which is a dot because it is a point of connection.
+
+## Type
+
+- `--ui`: the platform's own UI stack. Chrome, headings, labels, prose. No webfont: the viewer is served
+  from `node:http` with zero dependencies and must paint correctly offline, on the first frame.
+- `--mono`: the platform's own mono stack. Reserved for **data**: routes, `file:line`, counts, link labels,
+  measurements. Mono here is not a costume for "technical" - every string set in it is an identifier or a
+  number the developer will compare against something else.
+
+Hierarchy comes from weight and color, not scale. The size range across the whole UI is 11px to 19px.
+Uppercase tracking appears in exactly two places: rail panel titles, and depth-column labels on the canvas.
+Both are axis labels for a graph, not section eyebrows.
+
+## Motion
+
+`prefers-reduced-motion` collapses all of it. The budget is deliberately small.
+
+- **One authored moment:** on first paint the map settles in, cards rising 6px and fading, staggered by
+  depth column so the site's shape reads left to right. It plays once per render, never on scroll.
+- Everything else is feedback: 120ms on hover and focus, 90ms on `:active`, a wire trace on hover.
+- Nothing loops. Nothing parallaxes. A skeleton shimmer marks a preview that is genuinely still loading.
+
+## Density and honesty
+
+The viewer is a cockpit, and it earns that density by never lying about it:
+
+- Below `0.26` scale, wire labels and page thumbnails leave the render tree. A map that cannot show detail
+  says so by not drawing it, rather than compositing an unreadable smear.
+- At most 12 preview iframes stay mounted, two loading at a time, page JS off by default. Offscreen cards
+  unmount.
+- Past 60 pages, previews start off and the viewer says why.
+
+## Icons
+
+12px geometric glyphs from a single inline `<symbol>` sprite in `index.html`, one stroke weight (1.6),
+`currentColor` throughout. An icon library is the right default and is deliberately not used here: the
+project ships zero dependencies and no build step, so a CDN or an npm icon set would break both. That
+constraint buys the sprite; it does not buy hand-drawn illustration. Every glyph is a rectangle, a line, a
+circle, or a chevron.
+
+No emoji anywhere in the UI.
+
+## Anti-reference
+
+Two worlds this replaced, both evidence of what the tool does rather than authority over how it looks:
+
+1. A dark stone-and-torch "dungeon" theme with rooms, corridors, and quests.
+2. A periwinkle "starchart" theme with sky gradients, star specks, and violet hero cards.
+
+Do not reintroduce a spatial metaphor, a decorative ground texture, pill controls, all-mono chrome, or a
+saturated gradient card. The nouns in this tool are **page**, **link**, **section**, **entry**, **exit**,
+**issue**, and **change**. They are the product's language, and they are the only language the UI speaks.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sitelines contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+<div align="center">
+
+# sitelines
+
+**See every page on your site, every link between them, and everything that is broken.**
+
+Zero dependencies · no build step · Node 18+ · MIT
+
+</div>
+
+![The sitelines viewer showing a 20-page site laid out by click depth, with dead links in red](https://raw.githubusercontent.com/Jkaos725/sitelines/main/docs/map.jpg)
+
+sitelines reads your source, finds every page and every link, button, redirect, and form that moves between
+them, then serves a map in your browser. Each card is a real page with a live preview. Each wire is a real
+control, labelled with its actual button text and traced back to `file:line`.
+
+It tells you what is wrong: links that go nowhere, pages nothing links to, pages with no way out, pages
+buried more than three clicks deep, and pages carrying too many exits.
+
+You can also change the navigation from the map. Rename a button, point it somewhere else, draw a new link
+between two pages, propose a new page. **Nothing is written to your site.** Changes queue to a JSON file,
+and a coding agent implements them in your code when you ask.
+
+> The screenshots on this page are the bundled example site, mapped by sitelines itself. Run
+> `npx sitelines demo` and you get exactly this.
+
+---
+
+## How to use it
+
+**1. Point it at your pages.**
+
+```bash
+cd your-project
+npx sitelines open
+```
+
+That scans, starts a local server, and opens `http://localhost:4370`. It looks for your pages in `public`,
+`site`, `www`, `static`, `src/pages`, `src/routes`, `src/app`, `app/pages`, `pages`, `app`, or `docs`.
+Point it somewhere else with `--root`:
+
+```bash
+npx sitelines open --root src/routes --port 5000
+```
+
+**2. Read the map.** Columns are click depth from your front door. Cards are pages. Wires are controls. The
+left sidebar counts what exists and lists what is broken, and every issue jumps you to the page it is on.
+
+**3. Change the navigation.** Edit an exit's text, change where it points, draw a new link, propose a page.
+Everything you do queues up instead of touching your files.
+
+**4. Hand the queue to an agent.** Press **Copy prompt**, or install the skill and say
+*"apply my sitelines changes"*.
+
+---
+
+## Install
+
+Three ways in, depending on what you want.
+
+### Option 1: the tool
+
+Everything above. The scanner, the server, and the map.
+
+```bash
+npx sitelines open          # npm
+pnpm dlx sitelines open     # pnpm
+bunx sitelines open         # bun
+```
+
+Or keep it around:
+
+```bash
+npm  install -g sitelines
+pnpm add -g sitelines
+bun  add -g sitelines
+```
+
+**Every `npx` in this README works the same as `pnpm dlx` and `bunx`.** sitelines has no dependencies and
+no build step, so there is nothing for a package manager to disagree about. It runs on Node 18+ and on Bun.
+
+Or from source, with nothing to build:
+
+```bash
+git clone https://github.com/Jkaos725/sitelines.git
+cd your-project
+node /path/to/sitelines/bin/sitelines.mjs open
+```
+
+### Option 2: the demo
+
+See what it does before pointing it at anything of yours. This copies a 20-page example site into
+`./sitelines-demo` and maps it. Nothing outside that folder is touched.
+
+```bash
+npx sitelines demo
+```
+
+The example has deliberate faults so every part of the map has something to show: two dead links (one of
+them only reachable by reading the JavaScript), three orphans, a dead end, and a page four clicks deep.
+
+### Option 3: the Claude Code skill
+
+The same tool, plus the instructions an agent needs to turn your queued changes into real code. This is the
+only option that can actually **write** the changes for you.
+
+**Claude Code** reads skill folders:
+
+```bash
+npx sitelines skill install            # ~/.claude/skills/sitelines    (every project)
+npx sitelines skill install --project  # ./.claude/skills/sitelines    (this repo only)
+```
+
+**Codex, opencode, Cursor, Zed, Gemini CLI** read `AGENTS.md` from your project root:
+
+```bash
+npx sitelines agents install            # writes the block into ./AGENTS.md
+npx sitelines agents uninstall          # takes it back out
+```
+
+That appends a fenced block rather than overwriting, so an existing `AGENTS.md` keeps everything it
+already had. Re-running replaces the block in place instead of duplicating it, and uninstalling leaves
+your own content untouched.
+
+<details>
+<summary>Install it by hand instead</summary>
+
+A Claude Code skill is just a folder containing a `SKILL.md`. Copy four things into it:
+
+```bash
+git clone https://github.com/Jkaos725/sitelines.git
+mkdir -p ~/.claude/skills/sitelines
+
+cp    sitelines/skill/SKILL.md   ~/.claude/skills/sitelines/
+cp -r sitelines/skill/references ~/.claude/skills/sitelines/
+cp -r sitelines/scripts          ~/.claude/skills/sitelines/
+cp -r sitelines/viewer           ~/.claude/skills/sitelines/
+```
+
+On Windows PowerShell:
+
+```powershell
+git clone https://github.com/Jkaos725/sitelines.git
+New-Item -ItemType Directory -Force "$HOME\.claude\skills\sitelines"
+
+Copy-Item sitelines\skill\SKILL.md   "$HOME\.claude\skills\sitelines\"
+Copy-Item sitelines\skill\references "$HOME\.claude\skills\sitelines\" -Recurse
+Copy-Item sitelines\scripts          "$HOME\.claude\skills\sitelines\" -Recurse
+Copy-Item sitelines\viewer           "$HOME\.claude\skills\sitelines\" -Recurse
+```
+
+</details>
+
+<details>
+<summary>Or ask Claude Code to install it</summary>
+
+Paste this in:
+
+> Install the sitelines skill from https://github.com/Jkaos725/sitelines into `~/.claude/skills/sitelines`.
+> Clone the repo to a temp directory, copy `skill/SKILL.md`, `skill/references/`, `scripts/`, and `viewer/`
+> into the skill folder, then confirm `~/.claude/skills/sitelines/SKILL.md` exists.
+
+</details>
+
+Restart Claude Code, then type `/sitelines` or just ask:
+
+- "show me the site flow"
+- "where does the Start free button go?"
+- "find the dead links"
+- "apply my sitelines changes"
+
+### All commands
+
+```
+sitelines scan  [--root DIR] [--out DIR]                       read the site, write .sitelines/flow.json
+sitelines serve [--root DIR] [--out DIR] [--port N] [--open]   open the map
+sitelines open  [--root DIR] [--port N]                        scan, serve, and open the browser
+sitelines demo  [--dir DIR] [--port N]                         copy the example site and map it
+sitelines skill install   [--global|--project] [--force]       install the Claude Code skill
+sitelines skill uninstall [--global|--project]                 remove it
+sitelines agents install   [--dir DIR]                         write the AGENTS.md block (every other agent)
+sitelines agents uninstall [--dir DIR]                         remove just that block
+sitelines version
+sitelines help
+```
+
+---
+
+## Features
+
+### It hides your header and footer, and says so
+
+A nav bar repeated on twenty pages emits twenty identical links, and those wires bury every link that is
+actually specific to a page. sitelines detects any link appearing on more than four pages, folds it away,
+and reports the count it folded: **27 of 174** in the screenshot above. Turn it back on under **Layers**.
+
+Folding is a drawing decision, never an analytical one. A page reachable only through your footer is still
+reachable, and sitelines will not call it an orphan just because the footer is hidden.
+
+### Every page is live, at any width
+
+![The inspector panel open on a docs page, showing a live desktop preview and all eight of its exits with file and line numbers](https://raw.githubusercontent.com/Jkaos725/sitelines/main/docs/inspector.jpg)
+
+Click a card to open it: a real preview at mobile, tablet, or desktop width, every exit with its editable
+label and destination, every entrance, and a notes field. Previews come straight off disk, so you do not
+need a dev server running.
+
+The dots down each side of a card are ports, and each wire terminates on the exact dot that represents it.
+Hover any dot or wire for the control's real text, both routes, how it navigates, and its `file:line`.
+
+### Changes queue instead of landing
+
+![The queued changes drawer listing five pending edits, with the map already previewing them](https://raw.githubusercontent.com/Jkaos725/sitelines/main/docs/changes.jpg)
+
+| Do this | Get this |
+| --- | --- |
+| Edit an exit's text field | A queued rename |
+| Change an exit's destination | A queued retarget |
+| Click the ✕ on an exit | A queued removal |
+| **+ Link**, then click a destination | A queued new control |
+| **+ Page** | A queued new page, optionally linked from the selected one |
+
+The map previews the result immediately: queued links draw in amber, and a proposed page appears as a
+dashed card. The queue lives in `.sitelines/edits.json` and is the only thing sitelines writes.
+
+### Both themes, because it sits next to your editor
+
+![The same map in dark mode](https://raw.githubusercontent.com/Jkaos725/sitelines/main/docs/dark.jpg)
+
+Follows `prefers-color-scheme` and remembers a manual override. Every text color clears WCAG AA in both.
+
+### Views are yours to define
+
+The base view, **everything**, always shows every page and never takes a rule. Filter from it and sitelines
+starts a new view rather than quietly turning your one complete picture into a partial one. Press **+** on
+the tab bar to name a view, or write one into `.sitelines/views.json` and it appears:
+
+```json
+{
+  "active": "all",
+  "views": [
+    { "id": "all",  "label": "everything", "base": true, "include": [], "exclude": [] },
+    { "id": "docs", "label": "docs only",  "include": ["/docs/**"], "exclude": [] },
+    { "id": "app",  "label": "no legal",   "include": [], "exclude": ["/legal/**"] }
+  ]
+}
+```
+
+Patterns: `/docs/**` (subtree), `/docs/` (exact), `/docs/*` (one level), `*report*` (substring).
+
+### Directories collapse
+
+Pages sharing a top-level directory sit on a labelled backdrop. Click the label to fold the whole directory
+into one card: internal links disappear, and the directory keeps one wire per neighbour labelled `N links`,
+with every underlying control in its tooltip.
+
+### Keyboard
+
+| | |
+| --- | --- |
+| Drag background / wheel | Pan / zoom |
+| `f` | Fit everything on screen |
+| `/` | Focus the filter |
+| `1` `2` `3` | Switch views |
+| `e` | New link from the selected page |
+| `Escape` | Cancel whatever is in progress |
+
+---
+
+## What the scanner reads
+
+| Source | How the label is found |
+| --- | --- |
+| `<a href>` | The link text |
+| `<button>` / `<div>` with `onclick="location.href=…"`, `data-href`, `data-nav`, `formaction` | The element text |
+| `<form action>` | `POST form` |
+| `<meta http-equiv=refresh>` | `meta refresh` |
+| `location.href` / `.assign` / `.replace`, `window.open`, `router.push` / `.replace`, `navigate()` | The nearest `getElementById` or `querySelector` above the call |
+
+Pages are `*.html` files. If a project has none, sitelines falls back to framework page files under
+`pages/`, `routes/`, or `app/`.
+
+It is static analysis, so it reads what is in the source. A destination assembled at runtime from a template
+string is not something a scanner can resolve, and sitelines skips it rather than guessing.
+
+## Previews
+
+Two defaults worth knowing:
+
+- **Page JavaScript is off.** Preview iframes get an empty `sandbox`. A page that polls or retries a dead
+  API will otherwise peg your browser forty iframes over. Markup and CSS still render. Turn it on under
+  **Layers → Run page JavaScript**.
+- **Service workers are blocked** inside previews, or your site's own worker caches the preview responses
+  and serves them back for every later preview.
+
+For pages that need real data or a login, run your own dev server and use the **Open** button on the card.
+
+## Performance
+
+Large sites stay usable because the viewer refuses to pretend:
+
+- At most 12 preview iframes stay mounted, two loading at a time. Offscreen cards unmount.
+- Past 60 pages previews start off, and the viewer says why.
+- Below 0.26 zoom, thumbnails and wire labels leave the render tree instead of compositing a smear.
+
+## State
+
+sitelines writes one directory next to where you run it:
+
+```
+.sitelines/
+├── flow.json     the scan: pages, links, issues, plus your card positions and notes
+├── views.json    your views and their rules
+└── edits.json    the change queue, including applied history
+```
+
+Add it to `.gitignore` if it is yours alone, or commit it to share the layout and notes with your team.
+Nothing outside this directory is ever written.
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome.
+
+- **No dependencies.** Everything is Node's standard library and platform web APIs. A PR adding a runtime
+  dependency needs a strong reason.
+- **No build step.** `viewer/` is HTML, CSS, and ES modules served as written.
+- **Read `DESIGN.md` before touching `viewer/style.css`.** It is the authority on tokens, shape, type,
+  motion, and what each color means.
+- Test against `examples/demo-site` and against something with more than 40 pages. Density is where this
+  tool succeeds or fails.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/sitelines.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+// sitelines CLI - scan a site's navigation, then browse and edit it in a map.
+import path from 'node:path';
+import fs from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.join(here, '..');
+const scripts = path.join(pkgRoot, 'scripts');
+const argv = process.argv.slice(2);
+const cmd = argv[0];
+const rest = argv.slice(1);
+
+const version = (() => {
+  try { return JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version; }
+  catch { return '0.0.0'; }
+})();
+
+const HELP = `sitelines ${version} - map, audit, and edit a site's navigation
+
+  sitelines scan [--root DIR] [--out DIR]
+      Read every page and every link between them. Writes .sitelines/flow.json.
+      --root defaults to the first of public, site, www, static, src/pages,
+      src/routes, src/app, app/pages, pages, app, docs that exists.
+
+  sitelines serve [--root DIR] [--out DIR] [--port N] [--open]
+      Open the map in a browser. Requires a scan first.
+
+  sitelines open [--root DIR] [--port N]
+      Scan, then serve, then open the browser. The usual entry point.
+
+  sitelines demo [--dir sitelines-demo] [--port N]
+      Copy the bundled 20-page example site into ./sitelines-demo, map it, and
+      open it. Nothing outside that directory is touched. Use this to see what
+      sitelines does before pointing it at your own project.
+
+  sitelines skill install [--global|--project] [--dir PATH] [--force]
+  sitelines skill uninstall [--global|--project] [--dir PATH]
+      Install sitelines as a Claude Code skill so /sitelines works and Claude can
+      apply the changes you queue in the map. --global is ~/.claude/skills,
+      --project is ./.claude/skills. Defaults to --global.
+
+  sitelines agents [install|uninstall] [--dir PATH]
+      Same instructions, as an AGENTS.md block in your project root. Codex,
+      opencode, Cursor, Zed and Gemini CLI read that file, so this is how those
+      agents learn to apply your queued changes. Appends to an existing
+      AGENTS.md rather than overwriting it.
+
+  sitelines version
+  sitelines help
+
+State lives in .sitelines/ next to where you run it. Add it to .gitignore, or
+commit it to share the map's layout and notes with your team.`;
+
+function run(file, args, opts = {}) {
+  const r = spawnSync(process.execPath, [path.join(scripts, file), ...args], { stdio: 'inherit', ...opts });
+  if (r.error) { console.error(`sitelines: ${r.error.message}`); process.exit(1); }
+  return r.status ?? 0;
+}
+
+function flagValue(args, name, fallback) {
+  const i = args.indexOf(`--${name}`);
+  return i > -1 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : fallback;
+}
+
+function openBrowser(url) {
+  const cmds = process.platform === 'win32'
+    ? ['cmd', ['/c', 'start', '', url]]
+    : process.platform === 'darwin'
+      ? ['open', [url]]
+      : ['xdg-open', [url]];
+  try { spawn(cmds[0], cmds[1], { stdio: 'ignore', detached: true }).unref(); }
+  catch { /* no browser here; the URL is already printed */ }
+}
+
+switch (cmd) {
+  case 'scan':
+    process.exit(run('scan.mjs', rest));
+    break;
+
+  case 'serve': {
+    const wantOpen = rest.includes('--open');
+    const args = rest.filter((a) => a !== '--open');
+    if (wantOpen) setTimeout(() => openBrowser(`http://localhost:${flagValue(args, 'port', '4370')}`), 700);
+    process.exit(run('serve.mjs', args));
+    break;
+  }
+
+  case 'open': {
+    const code = run('scan.mjs', rest);
+    if (code !== 0) process.exit(code);
+    setTimeout(() => openBrowser(`http://localhost:${flagValue(rest, 'port', '4370')}`), 700);
+    process.exit(run('serve.mjs', rest));
+    break;
+  }
+
+  case 'demo': {
+    const dest = path.resolve(process.cwd(), flagValue(rest, 'dir', 'sitelines-demo'));
+    const src = path.join(pkgRoot, 'examples', 'demo-site');
+    if (!fs.existsSync(src)) { console.error(`sitelines: the bundled example is missing at ${src}`); process.exit(1); }
+    if (fs.existsSync(dest) && fs.readdirSync(dest).length) {
+      console.log(`sitelines: reusing the existing ${path.basename(dest)}/`);
+    } else {
+      fs.mkdirSync(dest, { recursive: true });
+      fs.cpSync(src, dest, { recursive: true });
+      console.log(`sitelines: copied the example site to ${path.basename(dest)}/ (20 pages)`);
+    }
+    const port = flagValue(rest, 'port', '4370');
+    // keep the demo's state inside the demo, so it never mixes with the map of
+    // whatever real project the user runs this from
+    const args = ['--root', dest, '--out', path.join(dest, '.sitelines'), '--port', port];
+    const code = run('scan.mjs', args);
+    if (code !== 0) process.exit(code);
+    console.log('sitelines: this example has deliberate faults - 2 dead links, 3 orphans, a dead end, and a page 4 clicks deep');
+    setTimeout(() => openBrowser(`http://localhost:${port}`), 700);
+    process.exit(run('serve.mjs', args));
+    break;
+  }
+
+  case 'skill': {
+    const sub = rest[0];
+    const args = rest.slice(1);
+    if (sub === 'install') process.exit(run('install-skill.mjs', args));
+    if (sub === 'uninstall') process.exit(run('install-skill.mjs', ['--uninstall', ...args]));
+    console.error('sitelines: expected `sitelines skill install` or `sitelines skill uninstall`');
+    process.exit(1);
+    break;
+  }
+
+  case 'agents': {
+    const sub = rest[0] === 'uninstall' ? ['--uninstall'] : [];
+    const args = rest.filter((a) => a !== 'install' && a !== 'uninstall');
+    process.exit(run('install-skill.mjs', ['--agents', ...sub, ...args]));
+    break;
+  }
+
+  case 'version':
+  case '--version':
+  case '-v':
+    console.log(version);
+    break;
+
+  case undefined:
+  case 'help':
+  case '--help':
+  case '-h':
+    console.log(HELP);
+    break;
+
+  default:
+    console.error(`sitelines: unknown command "${cmd}"\n`);
+    console.log(HELP);
+    process.exit(1);
+}

package/examples/demo-site/about/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>About | Meridian</title>
+<link rel="stylesheet" href="../assets/site.css">
+</head>
+<body>
+  <header class="nav">
+    <a class="logo" href="/">Meridian</a>
+    <nav>
+      <a href="/product/">Product</a>
+      <a href="/docs/">Docs</a>
+      <a href="/pricing/">Pricing</a>
+    </nav>
+    <a class="cta" href="/signup/">Start free</a>
+  </header>
+  <main>
+    <h1>About</h1>
+    <p class="lead">Six people, one product, no roadmap theatre.</p>
+    <p><a href="/blog/">Read the blog</a> and <a href="/contact/">get in touch</a>.</p>
+  </main>
+  <footer class="foot">
+    <a href="/legal/privacy/">Privacy</a>
+    <a href="/legal/terms/">Terms</a>
+    <a href="https://github.com/">GitHub</a>
+  </footer>
+</body>
+</html>

package/examples/demo-site/assets/auth.js

@@ -0,0 +1,3 @@
+document.getElementById('submit').addEventListener('click', () => {
+  location.href = '/app/';
+});