uniweb 1.18.3 → 1.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "1.18.3",
+  "version": "1.19.1",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -41,15 +41,15 @@
     "js-yaml": "^4.1.0",
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
-    "@uniweb/core": "~1.4.4",
-    "@uniweb/semantic-parser": "~1.13.0",
     "@uniweb/content-writer": "~1.3.0",
+    "@uniweb/core": "~1.4.6",
+    "@uniweb/semantic-parser": "~1.13.0",
     "@uniweb/schemas": "~1.6.5"
   },
   "peerDependencies": {
-    "@uniweb/build": "~1.8.5",
-    "@uniweb/semantic-parser": "~1.13.0",
-    "@uniweb/content-reader": "~1.5.6"
+    "@uniweb/build": "~1.9.0",
+    "@uniweb/content-reader": "~1.5.6",
+    "@uniweb/semantic-parser": "~1.13.0"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -179,6 +179,8 @@ pnpm preview          # preview the production build
 
 Markdown, `theme.yml`, and component edits hot-reload. New section types are picked up without a restart.
 
+**The dev server says where it is — read it, never assume a port.** `uniweb dev` takes a free port and, once the server listens, prints `Serving <site> at <url>`. The usual port may be another project's server, and reviewing that page reports success on the wrong site. Run `uniweb dev` in the background when you need your shell back: `uniweb dev --status` prints the address later, a second `uniweb dev` points at the running server instead of starting another, and `uniweb dev --stop` stops it when you are done. They know the server `uniweb dev` started, not one you start with `vite` or `npm run dev` inside the site. Pass `--port <n>` only when a port is required: you get that one or an error, never another.
+
 ---
 
 ## Part 2 — Working in an existing project
@@ -286,6 +288,8 @@ The architecture exists to keep content and code separate. Your task sits in one
 
 ```bash
 uniweb dev                         # from the workspace root; it picks the site
+uniweb dev --status                # the address it is serving at — read it, never assume a port
+uniweb dev --stop                  # stop it when you are done
 ```
 
 **When you're unsure what shape your markdown produces, don't reason about it — run it.** From the *site* directory (paths resolve against your shell's working directory):
@@ -590,7 +594,7 @@ submitLabel: Send
 ```
 ````
 
-→ `content.data?.form` = `{ fields: [...], submitLabel: "Send" }`, when the component declares `data: { form: … }`. A block under a key the component does not declare stays out of `content.data` (the dev console says so) and is still in `content.sequence`.
+→ `content.data?.form` = `{ fields: [...], submitLabel: "Send" }`, when the component declares `data: { form: … }`. A block under a key the component does not declare stays out of `content.data` (the dev console says so) and is still in `content.sequence`. A block inside an item is that item's (`content.items[n].data`) and needs no declaration.
 
 **Code snippets** — display content with a language for syntax highlighting, collected in `content.snippets` as `[{ language, code }]`. Filter with `content.snippets.filter(s => s.language === 'css')`.
 
@@ -656,6 +660,9 @@ background: primary-900                                  # Palette token (bare n
 background:                                              # Object form for more control
   image: { src: /img.jpg, position: center top }
   overlay: { enabled: true, type: dark, opacity: 0.5 }
+
+background:
+  video: { src: /videos/hero.mp4, poster: /images/hero.jpg }   # the poster shows until the video plays
 ```
 
 Components that render their own background declare `background: 'self'` in `meta.js`, and the runtime then draws none; to draw the author's background themselves they render kit's `<SectionBackground block={block} />`.
@@ -717,21 +724,24 @@ end the list with `...`.**
 
 **A local folder for a mounted route should use `folder.yml`, not `page.yml`.** The filename is how you say what the folder holds — `page.yml` for a page built from sections, `folder.yml` for a folder of pages — and for a mount that answer also decides how the mounted tree is read. A `page.yml` stub over a mounted folder of pages says "sections", and top-level markdown in the mounted repo collapses into one page instead of becoming pages of its own. Keep `layout:`, `title:` and SEO in that stub; the mounted repo's own `folder.yml` supplies its ordering and title where the stub is silent.
 
-**SEO & social cards:** set site-wide defaults in `site.yml`; any page overrides per-field in `page.yml` (page wins, site fills gaps). These render into every page's static `<head>` — Open Graph, Twitter Card, canonical, robots — so shares and crawlers see them without running JS. The social `image` is the field most worth setting once at site level.
+**SEO & social cards:** set site-wide defaults in `site.yml`; any page overrides per-field in `page.yml` (page wins, site fills gaps). Each page's static `<head>` carries its own tags — Open Graph, Twitter Card, canonical, robots, and hreflang on a multilingual site — so shares and crawlers see them without running JS. The social `image` is the field most worth setting once at site level; the site's `description` is the home page's alone. These tags are the framework's: a `head.html` tag of the same name is replaced.
 
 ```yaml
 # site.yml
 keywords: [components, react, cms]
 seo:
+  origin: https://acme.com          # where the site is served from — only where no host states it
   image: /og-default.png
   noindex: false                    # true keeps the WHOLE site out of search
 
 # page.yml
 seo:
   image: /og-about.png
-  canonical: https://acme.com/about
+  canonical: https://acme.com/team  # only to name ANOTHER URL — a page is its own canonical by default
 ```
 
+**Where the site lives — every absolute URL is made on it:** a page's canonical and `og:url`, its social image, its sitemap entry, the links in `llms.txt`. It is the site's origin plus its base path, and whoever serves the site states it: the GitHub Pages workflow `uniweb add ci --host=github-pages` writes asks GitHub; Netlify and Vercel state their production URL during the build; on any other static host, set `seo.origin` — a scheme and a host, `https://acme.com`, never with a path (a path is the site's `base:`; `seo.origin: https://user.github.io/repo` is refused). `seo.baseUrl` is retired, and refused. With no address, pages state no canonical, no `sitemap.xml` is written, and `llms.txt` links are root-relative — `uniweb doctor` says when that is so, and how to fix it for your host.
+
 **Localized URLs:** on a multilingual site (`languages:` in site.yml), `slug: { <lang>: <segment> }` gives a page a native URL segment per language; the folder name stays the canonical route. Nested folders compose automatically, and localized URLs flow through navigation, the language switcher, and the sitemap. See Part 5 for the translation workflow.
 
 **Knowledge pages — content for an AI agent, not for a visitor.** `knowledge: true` in a `page.yml` or `folder.yml` marks a page as agent-only: it is **never rendered** — no route, no HTML — and it cascades to the whole subtree by route prefix, so one marker on `pages/kb/` covers everything under it and `/kb` never claims `/kbase`. Write plain markdown; a section `type:` there never selects a component, because nothing renders these pages.
@@ -835,7 +845,7 @@ Server-to-server callers are authenticated by other means, arranged with your ho
 
 ⚠️ Spelling matters and nothing downstream will catch it — the block is forwarded to your host as opaque data, so a typo is carried and simply never acted on. `uniweb doctor` flags unknown keys in `agents:` for exactly this reason; run it before you rely on one.
 
-**Set `seo.baseUrl` if you want absolute links** in the index — without it the links are root-relative, which still works for an agent that arrived via the index. `uniweb doctor` warns when it's unset.
+**The index links absolutely on the site's address** (see *Where the site lives*) — without one the links are root-relative, which still works for an agent that arrived via the index. Each record of a parametric page is listed as a page, with a `.md` of its own.
 
 **What's excluded, and it's deliberate:** `seo.noindex` pages, `hidden` pages, `_`-prefixed drafts, and a parametric page's URL pattern (`/blog/:slug`). An index *describes* pages rather than merely listing them, so an unlinked page would become both discoverable and summarized — which is why these exclusions are load-bearing rather than tidy-up. `noindex` or `hidden` on a **folder** takes the whole branch with it.
 
@@ -1174,7 +1184,7 @@ Header.className = 'p-0'
 Header.as = 'header'
 ```
 
-**A header that stays in view is a setting, not a class.** `sticky top-0` on your component's markup does nothing: a sticky element moves only within its parent, and the section's wrapper and the area's are as tall as your header. Declare `sticky: true` in the type's `meta.js` — an author turns it off with `sticky: false` — and the runtime makes sticky the box that can stay in view. A section in the body sticks the same way and stays below the stuck header by itself: the runtime measures how far the header reaches and publishes it as `--uw-sticky-top` (a type's `top` overrides it). A link to a section lands below the stuck header too. A child section in kit's `<ChildGrid>` stays in view beside the column it sits next to, and on a phone, at one column, scrolls with the page. A sticky section inside a box with `overflow: hidden` cannot stick — clip with `overflow: clip`. A layout of your own that wraps an area in an element makes that element sticky when `page.isSticky('header')`. `uniweb dev` names a sticky element that cannot move in the console.
+**A header that stays in view is a setting, not a class.** `sticky top-0` on your component's outermost element does nothing: a sticky element moves only within its parent, and the section's wrapper and the area's are as tall as your header. (An element inside your component is different: a form beside a long list sticks within the row the two share, a box you draw.) Declare `sticky: true` in the type's `meta.js` — an author turns it off with `sticky: false` — and the runtime makes sticky the box that can stay in view. A section in the body sticks the same way and stays below the stuck header by itself: the runtime measures how far the header reaches and publishes it as `--uw-sticky-top` (a type's `top` overrides it). A link to a section lands below the stuck header too. A child section in kit's `<ChildGrid>` stays in view beside the column it sits next to, and on a phone, at one column, scrolls with the page. A sticky section inside a box with `overflow: hidden` cannot stick — clip with `overflow: clip`. A layout of your own that wraps an area in an element makes that element sticky when `page.isSticky('header')`. `uniweb dev` names a sticky element that cannot move in the console, once the page's data is in, and says which box holds it.
 
 ### meta.js
 
@@ -1867,7 +1877,7 @@ const page = website.activePage
 | `block.themeName` | `"light"`, `"medium"`, `"dark"` |
 | `block.stableId` / `block.key` | Stable ID from filename or `id:` / unique key across pages — use as React key |
 | `block.path` | Page route this block belongs to |
-| `block.dataLoading` | True while declared data is still resolving |
+| `block.dataLoading` | True while declared data is still resolving — also on a pre-rendered page, for data the browser fetches, so the loading state is what that page first shows |
 | `block.dataError` | `{ <key>: message }` when the fetch filling a declared key FAILED, else `null`. A failed key is `null` in `content.data` — never `[]`, which means "no records" |
 
 ```jsx
@@ -2793,7 +2803,8 @@ them, and any other in full; it matches a name exactly. State is in memory; rest
 ## Part 5 — Commands, shipping, and migration
 
 ```bash
-uniweb dev                        # Start dev server (picks the site for you)
+uniweb dev                        # Start dev server (picks the site for you; prints its address)
+uniweb dev --status / --stop      # The running dev server's address / stop it
 pnpm build / pnpm preview         # Build for production / preview the build (SSG + SPA)
 
 uniweb deploy                     # Wizard: pick a destination, then deploy (or set up CI)
@@ -3099,7 +3110,7 @@ Most Uniweb failures are **silent** — the build succeeds and the page is wrong
 
 **A var in frontmatter does nothing** — component vars only apply when declared in that section type's `meta.js` `vars:`. Unknown names are ignored silently.
 
-**A sticky header scrolls away** — it is `sticky top-0` on the component's own markup, which has no room to move. Make the section sticky instead: `sticky: true` in its type's `meta.js`. A sticky section that still scrolls away sits in a box with `overflow: hidden` — clip with `overflow: clip`. `uniweb dev` names the element in the console.
+**A sticky header scrolls away** — it is `sticky top-0` on the component's outermost element, which has no room to move. Make the section sticky instead: `sticky: true` in its type's `meta.js`. A sticky section that still scrolls away sits in a box with `overflow: hidden` — clip with `overflow: clip`. `uniweb dev` names the element in the console.
 
 Loud failures:
 

package/src/commands/dev.js

@@ -12,6 +12,17 @@
  *   uniweb dev                  Start dev server for the (single) site
  *   uniweb dev <site>           Start dev server for a specific site
  *   uniweb dev --site <name>    Same, with explicit flag form
+ *   uniweb dev --port <n>       On that port, or not at all
+ *   uniweb dev --status         Print the running dev server's address
+ *   uniweb dev --stop           Stop the running dev server
+ *
+ * ⭐ THE DEV SERVER SAYS WHERE IT IS; NOTHING GUESSES. It takes a free port (Vite moves past a
+ * busy one), and once it listens, the server `dev` starts — only that one — records the address
+ * it was given (`@uniweb/build/site`'s `dev-server.js`). `dev` reads that record: it prints the
+ * address the moment the server states it, `--status` prints it later, a second `dev` for the
+ * site points at the running server rather than starting another on another port, and `--stop`
+ * asks it to stop, which it does with exit 0. ⛔ Until 2026-10-25 a caller had to pick a port to
+ * know the address, and `--port` was read as the site's name.
  *
  * Resolution order for which site to launch:
  *   1. --site <name> (if passed)
@@ -48,6 +59,7 @@ import { readWorkspaceConfig } from '../utils/config.js'
 import { discoverSites } from '../utils/discover.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
 import { readFlagValue } from '../utils/args.js'
+import { checkFlags } from '../utils/flag-guard.js'
 import {
   checkSiteInstall,
   readDeclaredFoundation
@@ -55,12 +67,62 @@ import {
 import { discoverFoundations } from '../utils/discover.js'
 
 const RED = '\x1b[31m'
+const GREEN = '\x1b[32m'
 const YELLOW = '\x1b[33m'
 const DIM = '\x1b[2m'
 const CYAN = '\x1b[36m'
 const RESET = '\x1b[0m'
 
+/** The flags `dev` reads a value after — none of which is ever the site's name. */
+const VALUE_FLAGS = ['--site', '--port', '--org']
+
+/**
+ * What `uniweb dev` was asked: the site, by `--site` or a bare name; the port, if one; and
+ * whether to report on the running server or stop it rather than start one.
+ *
+ * @param {string[]} args
+ * @returns {{ site: string|null, port: number|null, status: boolean, stop: boolean, error?: string }}
+ */
+export function readDevArgs(args) {
+  let positional = null
+  for (let i = 0; i < args.length && positional === null; i++) {
+    if (args[i] === '--') break
+    if (VALUE_FLAGS.includes(args[i])) i++
+    else if (!args[i].startsWith('-')) positional = args[i]
+  }
+  const siteFlag = readFlagValue(args, '--site')
+  const wanted = {
+    site: typeof siteFlag === 'string' ? siteFlag : positional,
+    port: null,
+    status: args.includes('--status'),
+    stop: args.includes('--stop')
+  }
+  const port = readFlagValue(args, '--port')
+  if (port !== undefined) {
+    const n = Number(port)
+    if (port === null || !Number.isInteger(n) || n < 1 || n > 65535) {
+      return { ...wanted, error: '`--port` takes a port number, 1–65535: uniweb dev --port 5199' }
+    }
+    wanted.port = n
+  }
+  if (wanted.status && wanted.stop) {
+    return { ...wanted, error: '`--status` and `--stop` ask for different things; pass one.' }
+  }
+  return wanted
+}
+
 export async function dev(args = []) {
+  const badFlag = checkFlags('dev', args)
+  if (badFlag) {
+    console.error(`${RED}✗${RESET} ${badFlag.message}`)
+    process.exit(2)
+  }
+  const wanted = readDevArgs(args)
+  if (wanted.error) {
+    console.error(`${RED}✗${RESET} ${wanted.error}`)
+    process.exit(2)
+  }
+
   const cwd = process.cwd()
   const rootDir = findWorkspaceRoot(cwd) || cwd
 
@@ -90,10 +152,7 @@ export async function dev(args = []) {
   }
 
   // Pick the site
-  const siteFlag = readFlagValue(args, '--site')
-  const positional = args.find((a) => !a.startsWith('-'))
-  const requested =
-    (typeof siteFlag === 'string' ? siteFlag : null) || positional || null
+  const requested = wanted.site
 
   let site
   if (requested) {
@@ -116,6 +175,42 @@ export async function dev(args = []) {
     console.error(`  Available: ${sites.map((s) => s.name).join(', ')}`)
     console.error('')
   }
+  const sitePath = join(rootDir, site.path)
+
+  const { runningDevServer, stopDevServer, DEV_PORT_ENV, DEV_RECORD_ENV } = await import('@uniweb/build/site')
+  if (wanted.status) {
+    const running = await runningDevServer(sitePath)
+    if (!running) {
+      console.error(`No dev server started by \`uniweb dev\` is running for ${site.name}.`)
+      process.exit(1)
+    }
+    console.log(running.url)
+    return
+  }
+  if (wanted.stop) {
+    const result = await stopDevServer(sitePath)
+    if (result.none) console.error(`No dev server started by \`uniweb dev\` is running for ${site.name}.`)
+    else if (result.stuck) {
+      console.error(`${RED}✗${RESET} The dev server for ${site.name} (pid ${result.stuck.pid}) did not stop.`)
+      console.error(`  Stop it with: kill -9 ${result.stuck.pid}`)
+      process.exit(1)
+    } else console.error(`${GREEN}✓${RESET} Stopped the dev server for ${site.name} (${result.stopped.url}).`)
+    return
+  }
+
+  // One dev server per site: a second `dev` points at the running one rather than start another
+  // on the next free port.
+  const running = await runningDevServer(sitePath)
+  if (running) {
+    if (wanted.port !== null && wanted.port !== running.port) {
+      console.error(`${RED}✗${RESET} ${site.name} is already being served at ${running.url}, not on port ${wanted.port}.`)
+      console.error('  Stop it first: uniweb dev --stop')
+      process.exit(1)
+    }
+    console.error(`${GREEN}✓${RESET} ${site.name} is already being served at ${CYAN}${running.url}${RESET} (pid ${running.pid}).`)
+    console.error('  Stop it with: uniweb dev --stop')
+    return
+  }
 
   // A `file:` foundation dependency can be satisfied by a link or by a copy,
   // and a copy is a snapshot: the dev server serves it while builds read the
@@ -127,7 +222,6 @@ export async function dev(args = []) {
   const pm = detectPackageManager()
   const command = filterCmd(pm, site.name, 'dev')
   const [bin, ...rest] = command.split(' ')
-  const sitePath = join(rootDir, site.path)
 
   // ⭐ A SITE WHOSE FOUNDATION IS A CATALOG REF — a clone — is previewed with what the backend
   // it is on says: where that version is served. Asked here, for this dev server alone, and
@@ -140,14 +234,18 @@ export async function dev(args = []) {
     for (const line of asked.refused.slice(1)) console.error(`  ${line}`)
     process.exit(1)
   }
-  let env = process.env
+  // The server this starts keeps the record the next `dev`, `--status` and `--stop` read; one
+  // started any other way keeps none (`dev-server.js`).
+  let env = { ...process.env, [DEV_RECORD_ENV]: '1' }
   if (asked?.preview) {
     const { PREVIEW_ENV, encodePreview } = await import('@uniweb/build/site')
-    env = { ...process.env, [PREVIEW_ENV]: encodePreview(asked.preview) }
+    env = { ...env, [PREVIEW_ENV]: encodePreview(asked.preview) }
     console.error(
       `${DIM}→ Previewing with ${asked.preview.foundation.ref}, served by ${asked.preview.backend}${RESET}`
     )
   }
+  // That port or none: the dev server refuses to move past it (`dev-server.js`).
+  if (wanted.port !== null) env = { ...env, [DEV_PORT_ENV]: String(wanted.port) }
 
   await ensureSiteExtensionsBuilt(sitePath)
 
@@ -156,12 +254,33 @@ export async function dev(args = []) {
   )
   console.error('')
 
+  const startedAt = Date.now()
   const child = spawn(bin, rest, { cwd: rootDir, stdio: 'inherit', env })
   child.on('close', (code) => process.exit(code ?? 0))
   child.on('error', (err) => {
     console.error(`${RED}✗${RESET} Failed to start dev server: ${err.message}`)
     process.exit(1)
   })
+  // A line of help, never a reason for the server to stop.
+  announceWhenListening({ site, sitePath, startedAt, child, runningDevServer }).catch(() => {})
+}
+
+/**
+ * Say where the dev server is once it states it: one line, the same every time, for whoever
+ * started it to read. Waits on the server's own record, written when it listens, so the
+ * address is the one it was given, not one this derived from a port.
+ */
+async function announceWhenListening({ site, sitePath, startedAt, child, runningDevServer }) {
+  let exited = false
+  child.once('close', () => { exited = true })
+  for (const until = Date.now() + 120_000; !exited && Date.now() < until; ) {
+    const running = await runningDevServer(sitePath, { timeout: 1000 })
+    if (running && Date.parse(running.startedAt) >= startedAt) {
+      console.error(`${GREEN}✓${RESET} Serving ${site.name} at ${CYAN}${running.url}${RESET}`)
+      return
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
 }
 
 /**

package/src/commands/doctor.js

@@ -19,7 +19,7 @@ import {
   extensionNameOf,
   findSiteExtension
 } from '@uniweb/build'
-import { loadDeployYml, AGENTS_KEYS, originOf } from '@uniweb/build/site'
+import { loadDeployYml, AGENTS_KEYS, originOf, refuseUnreadableAddress } from '@uniweb/build/site'
 import { listAdapters } from '@uniweb/build/hosts'
 import { RUNTIME_KEYS } from '@uniweb/build/uwx'
 import { getCliVersion } from '../versions.js'
@@ -30,6 +30,7 @@ import { discoverFoundations, discoverSites } from '../utils/discover.js'
 import { checkSiteInstall } from '../utils/install-integrity.js'
 import { editWorkspaceFilePackages } from '../utils/workspace-packages.js'
 import { findWorkspaceRoot } from '../utils/workspace.js'
+import { ignoredByRepo } from '../utils/git.js'
 import { DATA_DIR } from '@uniweb/core/data-paths'
 import { FAMILIES, resolveFamily } from '@uniweb/schemas/families'
 import { suggestFamily } from '@uniweb/schemas/family-aliases'
@@ -1008,6 +1009,79 @@ export async function checkFormSubmitTarget({ sitePath, siteName, siteYml, issue
   )
 }
 
+/** The host a site's default deploy target names (`deploy.yml`), or null. */
+function defaultDeployHost(deployYml) {
+  const targets = deployYml?.targets || {}
+  const names = Object.keys(targets)
+  const name = deployYml?.default || (names.length === 1 ? names[0] : null)
+  return name ? targets[name]?.host || name : null
+}
+
+/** Hosts that state, at build, where they serve a site — so it needs no `seo.origin` of its own. */
+const ADDRESS_STATING_HOSTS = new Set(['uniweb', 'netlify', 'vercel'])
+
+/**
+ * Where the site lives — what every absolute URL it states is made on: a page's canonical and
+ * `og:url`, its `sitemap.xml`, its agent index's links (`@uniweb/build`'s `site/site-address.js`).
+ * A host may state it: Netlify and Vercel at build, a Uniweb host when it serves the site, GitHub
+ * Pages through the workflow `uniweb add ci` writes. Otherwise `seo.origin` does. ⛔ Until
+ * 2026-10-25 this asked for `seo.baseUrl` — which, once set, gave every page the home page's
+ * canonical — and named only the agent index.
+ */
+export async function checkSiteAddress({ sitePath, siteName, siteYml, workspaceDir, issues }) {
+  try {
+    refuseUnreadableAddress(siteYml, 'site.yml')
+  } catch (err) {
+    const id = 'site-address-config'
+    const message = err.message.replace(/^\[uniweb\] /, '')
+    issues.push({ id, type: 'error', site: siteName, message })
+    error(`[${id}] ${message}`)
+    return
+  }
+  if (siteYml?.seo?.origin) return
+
+  let deployYml = null
+  try {
+    deployYml = await loadDeployYml(sitePath)
+  } catch {
+    // malformed deploy.yml is reported by its own check; treat as absent here
+  }
+  const host = defaultDeployHost(deployYml)
+  if (ADDRESS_STATING_HOSTS.has(host)) return
+
+  const without = 'Without one, no page states a canonical URL, no sitemap.xml is written, and llms.txt links root-relative.'
+  if (host === 'github-pages') {
+    const workflowPath = join(workspaceDir, '.github', 'workflows', 'deploy-github-pages.yml')
+    const workflow = existsSync(workflowPath) ? readFileSync(workflowPath, 'utf8') : null
+    if (workflow?.includes('UNIWEB_ORIGIN')) return
+    if (workflow) {
+      const id = 'site-address-from-github'
+      issues.push({
+        id,
+        type: 'warning',
+        site: siteName,
+        message: "The GitHub Pages workflow does not hand the build the address GitHub serves the site at"
+      })
+      warn(`[${id}] GitHub Pages states where it serves this site, but the workflow predates reading it`)
+      log(`    Regenerate it: ${colors.green}uniweb add ci --host=github-pages --force${colors.reset} — or set ${colors.green}seo.origin${colors.reset} in site.yml`)
+      log(`    ${colors.dim}${without}${colors.reset}`)
+      return
+    }
+  }
+
+  const id = 'site-address-unknown'
+  issues.push({
+    id,
+    type: 'warning',
+    site: siteName,
+    message: 'The site states no address: no canonical URLs, no sitemap.xml, root-relative llms.txt'
+  })
+  warn(`[${id}] Nothing states where this site is served`)
+  log(`    Set ${colors.green}seo.origin${colors.reset} in site.yml — the origin it is served from, e.g. https://example.com`)
+  log(`    ${colors.dim}A host that states it needs none: the GitHub Pages workflow \`uniweb add ci\` writes, Netlify, Vercel.${colors.reset}`)
+  log(`    ${colors.dim}${without}${colors.reset}`)
+}
+
 /** The bare map in `queries.yml`, or `{}` when there is none. */
 function readQueriesYml(sitePath) {
   try {
@@ -1018,7 +1092,7 @@ function readQueriesYml(sitePath) {
   }
 }
 
-function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix, fixed }) {
+export function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix, fixed }) {
   const dataDir = join(sitePath, 'public', DATA_DIR)
   // ⚠️ THE QUERIES, not the pool. `public/<DATA_DIR>/x.json` is a query's
   // MATERIALIZATION — one file per named query — so the bijection is with the
@@ -1074,15 +1148,24 @@ function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix,
 
   // The ignore rule. Checked whether or not the directory exists yet — the
   // point is to have it in place *before* the first build writes there.
+  //
+  // ⭐ ASKED OF GIT when a repository holds the site (`ignoredByRepo`): git reads every
+  // rule, a workspace's root `.gitignore` naming `site/public/data/` among them, and only
+  // it can say whether the build's files would be committed. Outside a repository nothing
+  // is committed yet, and the site's own `.gitignore` is read for the rule `--fix` writes.
+  // ⛔ Until 2026-10-25 that file was read in a repository too, so a rule in the root
+  // `.gitignore` was reported as missing.
   const gitignorePath = join(sitePath, '.gitignore')
   const rule = `public/${DATA_DIR}/`
   const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : null
   const covered =
-    existing !== null &&
-    existing
-      .split('\n')
-      .map((line) => line.trim().replace(/\/$/, ''))
-      .includes(rule.replace(/\/$/, ''))
+    // Any file the build writes there: `x.json` is a query's list.
+    ignoredByRepo(sitePath, `${rule}x.json`) ??
+    (existing !== null &&
+      existing
+        .split('\n')
+        .map((line) => line.trim().replace(/\/$/, ''))
+        .includes(rule.replace(/\/$/, '')))
 
   if (!covered) {
     const id = 'generated-data-not-ignored'
@@ -1092,7 +1175,7 @@ function checkGeneratedDataDir({ sitePath, siteName, siteYml, issues, shouldFix,
       site: siteName,
       message: `public/${DATA_DIR}/ is generated but not gitignored`
     })
-    warn(`[${id}] public/${DATA_DIR}/ is build output but not in .gitignore`)
+    warn(`[${id}] public/${DATA_DIR}/ is build output but not gitignored`)
     log(`    Committing it means a diff on every build, and it invites editing what the build overwrites.`)
     if (shouldFix(id)) {
       const body = existing === null ? '' : existing.replace(/\n*$/, '\n')
@@ -1503,30 +1586,7 @@ export async function doctor(args = []) {
       continue
     }
 
-    // The agent index ships by default, but it can only carry absolute links
-    // when the site declares where it lives. Root-relative links still work
-    // for an agent that arrived via the index, so this warns rather than
-    // suppressing the artifact the way sitemap.xml does — a silently absent
-    // index is the exact failure the projections exist to prevent.
-    const agentsConfig = siteYml.agents
-    const indexEnabled = agentsConfig !== false && agentsConfig?.index !== false
-    if (indexEnabled && !siteYml.seo?.baseUrl) {
-      const issue = {
-        id: 'agents-index-relative-links',
-        type: 'warning',
-        site: siteName,
-        message:
-          'llms.txt will use root-relative links because seo.baseUrl is unset'
-      }
-      issues.push(issue)
-      warn(`[agents-index-relative-links] llms.txt links will be root-relative`)
-      log(
-        `    Set ${colors.green}seo.baseUrl${colors.reset} in site.yml so agents get absolute URLs`
-      )
-      log(
-        `    (this also turns on sitemap.xml and robots.txt, which are skipped without it)`
-      )
-    }
+    await checkSiteAddress({ sitePath, siteName, siteYml, workspaceDir, issues })
 
     // `public/<DATA_DIR>/` is the build's output directory and nothing else —
     // `records/` is the only supported way to provide structured data. That makes the mapping a bijection: every entry there should be backed

package/src/framework-index.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-10-24T22:25:23.486Z",
+  "generatedAt": "2026-10-25T16:50:54.453Z",
   "packages": {
     "@uniweb/api": {
       "version": "1.6.4"
     },
     "@uniweb/build": {
-      "version": "1.8.5"
+      "version": "1.9.0"
     },
     "@uniweb/content-reader": {
       "version": "1.5.6"
@@ -15,7 +15,7 @@
       "version": "1.3.0"
     },
     "@uniweb/core": {
-      "version": "1.4.4"
+      "version": "1.4.6"
     },
     "@uniweb/frame-bridge": {
       "version": "1.0.2"
@@ -24,7 +24,7 @@
       "version": "1.0.6"
     },
     "@uniweb/kit": {
-      "version": "1.6.3"
+      "version": "1.6.4"
     },
     "@uniweb/loom": {
       "version": "1.1.2"
@@ -33,10 +33,10 @@
       "version": "1.1.4"
     },
     "@uniweb/projections": {
-      "version": "1.1.7"
+      "version": "1.2.0"
     },
     "@uniweb/runtime": {
-      "version": "1.1.20"
+      "version": "1.2.1"
     },
     "@uniweb/scene": {
       "version": "1.0.1"
@@ -60,7 +60,7 @@
       "version": "1.2.1"
     },
     "@uniweb/unipress": {
-      "version": "1.1.14"
+      "version": "1.1.15"
     }
   },
   "templates": {

package/src/index.js

@@ -1537,6 +1537,15 @@ ${colors.bright}Usage:${colors.reset}
   uniweb dev                  Start dev server for the (single) site
   uniweb dev <site>           Start dev server for a specific site
   uniweb dev --site <name>    Same, with explicit flag form
+  uniweb dev --port <n>       On that port, or not at all
+  uniweb dev --status         Print the running dev server's address
+  uniweb dev --stop           Stop the running dev server
+
+The dev server takes a free port and says where it is: once it listens,
+\`dev\` prints \`Serving <site> at <url>\`. Don't assume a port: another
+project's server may be on the one you would guess. While one is running,
+\`uniweb dev\` points at it rather than starting another. \`--status\` and
+\`--stop\` know the server \`uniweb dev\` started, not one started with \`vite\`.
 
 Thin wrapper around the package manager's workspace-filtered \`dev\`
 script (\`pnpm --filter <site> dev\` or \`npm -w <site> run dev\`). Picks

package/src/utils/flag-guard.js

@@ -130,7 +130,16 @@ const VERBS = {
   refresh: [
     '--no-backend', '--no-git',
     '--org', '--personal', '--dry-run', '--no-validate', '--yes', ...VIA_DEPLOY
-  ]
+  ],
+  /**
+   * `dev` = start a site's dev server, or report on (`--status`) or stop (`--stop`) the
+   * running one, on that port or none (`--port`). It reaches a backend only for a site whose
+   * foundation is a catalog ref, to ask where that version is served, and that asks in the
+   * workspace `--org` / `--personal` name (`backend/site-preview.js` — imported lazily, so
+   * `flag-guard-coverage.test.js`'s walk does not see it). ⛔ Until 2026-10-25 `dev` checked
+   * no flags, and read the value of `--port 5199` as the name of a site.
+   */
+  dev: ['--site', '--port', '--status', '--stop', '--org', '--personal']
 }
 
 /**

package/src/utils/git.js

@@ -102,6 +102,26 @@ export function isGitRepo(dir) {
   return Boolean(repoOf(dir))
 }
 
+/**
+ * Would the repository that holds `dir` ignore `path` (relative to `dir`)? True or false —
+ * or null when no repository holds `dir` (`repoOf`) or git cannot say.
+ *
+ * Asked of git, never read from a `.gitignore`: the rule may sit in a parent's file (a
+ * workspace root naming `site/public/data/`), be spelled with or without its slashes, or
+ * come from `.git/info/exclude`, and git reads them all. `--no-index` asks about the rules
+ * alone, so a file committed despite them does not read as unignored, and `path` need not
+ * exist.
+ */
+export function ignoredByRepo(dir, path) {
+  if (!repoOf(dir)) return null
+  try {
+    git(['check-ignore', '-q', '--no-index', path], dir)
+    return true
+  } catch (err) {
+    return err?.status === 1 ? false : null
+  }
+}
+
 /** Does this repo have a remote configured to pull from? */
 export function hasRemote(dir) {
   try {