uniweb 1.25.4 → 1.25.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,123 @@
1
+ # Theming: tokens, light and dark, `theme.yml`, fonts, `styles.css`
2
+
3
+ On-demand guide (`uniweb guide theme`); AGENTS.md is assumed read. Author's view: `reference/site-theming.md`.
4
+
5
+ ## Semantic tokens
6
+
7
+ | Token | Purpose |
8
+ |---|---|
9
+ | `heading`, `body`, `subtle` | text |
10
+ | `section`, `card`, `muted` | section background, panel background, hover/zebra |
11
+ | `border`, `ring` | lines, focus |
12
+ | `link` / `link-hover` | links |
13
+ | `primary` / `-foreground` / `-hover` / `-border`, `secondary` / … | actions |
14
+ | `success` / `warning` / `error` / `info`, `+ -subtle` | status, status backgrounds |
15
+
16
+ Palette shades: `text-primary-600`, `bg-neutral-100`, `border-accent-300` — 50–950 for primary, secondary, accent, neutral. Full mapping in `theme-tokens.css`.
17
+
18
+ **Debugging a token that "does nothing" — don't probe in the browser.** Tailwind v4 is JIT and emits only classes found in scanned source, so a class assigned from the console can never resolve. Ask the build: `grep -o '\.text-link{[^}]*}' dist/assets/*.css`. A rule prints → the utility exists and something overrides it at runtime. Nothing prints → `styles.css` doesn't import `theme-tokens.css` (or declares its own `@theme inline` omitting it), or `@source` doesn't cover the file.
19
+
20
+ **Per-section theme maps.** A section's `theme:` is `theme.yml` for that section — tokens beside `mode`, plus `colors`, `contexts`, `vars` scoped to it (`theme: { mode: light, section: neutral-100, card: neutral-50, primary: neutral-900, colors: { accent: '#e65100' }, contexts: { dark: { link: accent-300 } } }`). `background:` accepts CSS variables and hex too, so authors alternate surfaces with no component code. Map a source design's surface variations to backgrounds or token overrides in frontmatter — not to component code.
21
+
22
+ ## Section context vs site scheme
23
+
24
+ - **Section context** — `theme:` on one section. Per-section, author-controlled.
25
+ - **Site scheme** — the global preference under `appearance:` in `theme.yml`; the visitor's toggle.
26
+
27
+ A section with no `theme:` follows the scheme; one that pins `theme: dark` stays dark in either.
28
+
29
+ ```yaml
30
+ appearance:
31
+ default: light # light | dark | system
32
+ allowToggle: true # offer a switch (also generates dark tokens)
33
+ respectSystemPreference: true # first visit follows the OS; false pins `default`
34
+ schemes: [light, dark]
35
+ ```
36
+
37
+ Shorthands: `appearance: light` / `dark` (fixed), `appearance: system`. A site has dark mode when it offers a toggle, defaults to `dark`/`system`, or lists `dark`. Precedence: stored choice > a dark OS > `default:` — the OS can only choose dark, so `default: light` is a fallback, not a guarantee, unless `respectSystemPreference: false`, and `default: dark` stays dark on a light OS.
38
+
39
+ | Goal | `theme.yml` |
40
+ |---|---|
41
+ | Always light / dark, no switch | `appearance: light` / `dark` |
42
+ | Toggle, follow OS on first visit | `{ default: system, allowToggle: true }` |
43
+ | Toggle, always start light | `{ default: light, allowToggle: true, respectSystemPreference: false }` |
44
+
45
+ ```jsx
46
+ const { scheme, toggle, canToggle } = useAppearance()
47
+ if (!canToggle) return null
48
+ ```
49
+
50
+ The runtime applies `scheme-dark`/`scheme-light` to `<html>` before paint. For Tailwind `dark:` utilities: `@custom-variant dark (&:where(.scheme-dark, .scheme-dark *));` in `styles.css`; prefer tokens, which adapt per section.
51
+
52
+ ## theme.yml
53
+
54
+ ```yaml
55
+ colors:
56
+ primary: '#3b82f6' # your hex at shade 500
57
+ secondary: '#64748b'
58
+ accent: '#8b5cf6'
59
+ neutral: stone # named preset: stone, zinc, gray, slate, neutral
60
+ contexts:
61
+ light: { section: '#fafaf9' }
62
+ appearance: { default: light, allowToggle: true }
63
+ fonts: { heading: "'Inter', system-ui, sans-serif", body: "'Inter', system-ui, sans-serif" }
64
+ inline: { callout: { color: var(--accent), font-weight: '600' } }
65
+ vars: { radius: 0.75rem }
66
+ code: dracula # or { light: github-light, dark: github-dark }, or { theme: github-dark, background: '#0D0D0D' }
67
+ ```
68
+
69
+ Context override keys match token names (`section:` not `bg:`). In light/medium `--primary` uses shade 600, `--link` 600, `--ring` 500; in dark `--primary` 500, `--link` 400. Buttons use 600 for contrast with white text; for brand-exact buttons set `contexts.light.primary: primary-500` and `primary-hover: primary-600`, and test contrast — bright brands at 500 may fail WCAG 4.5:1. A code block paints its theme's background and foreground before the highlighter loads when both are known.
70
+
71
+ ## Fonts
72
+
73
+ | Role | Wired onto | Use |
74
+ |---|---|---|
75
+ | `body` | `body` | paragraphs, UI |
76
+ | `heading` | `h1, h2, h3` | titles |
77
+ | `code` | `code, pre, kbd, samp` | monospace |
78
+
79
+ The site wires families onto elements, so a foundation normally sets none — render semantic markup and the roles apply. Weight/size/style utilities are yours; a font-**family** utility (`font-sans`, `font-serif`) resolves to Tailwind's stacks unless the foundation declares it as a font var. For typefaces the three roles can't express, declare each as a **font var** in `main.js` — a `font-*` name is recognised as a typeface (a bare name takes `type: 'font'`):
80
+
81
+ ```js
82
+ export const vars = {
83
+ 'font-serif': { default: 'ui-serif, Georgia, serif', applyTo: ['blockquote', '.tagline'] }, // framework emits the rule
84
+ 'font-display': { default: 'ui-sans-serif, system-ui, sans-serif' }, // component wires it
85
+ }
86
+ ```
87
+
88
+ `fonts:` in `theme.yml` takes any role name; redeclaring a built-in role's var with a new `applyTo` retargets it. `serif` and `font-serif` are the same var (the site sets it by the bare role name).
89
+
90
+ ```yaml
91
+ fonts:
92
+ heading: "Poppins, sans-serif"
93
+ serif: '"Fraunces", Georgia, serif'
94
+ import: [{ url: "https://fonts.googleapis.com/css2?family=Poppins:wght@600;700" }]
95
+ faces: [{ family: "Fraunces", src: /fonts/fraunces.woff2, weight: "100 900" }]
96
+ ```
97
+
98
+ The build adds preconnect hints, emits `@font-face` + preload, drops unreferenced families; `uniweb push` uploads face files under `public/`. An imported font replaces the fallback when it arrives (`display=swap`, unless the URL says otherwise), which can re-wrap text on a first visit. `display=optional` in the URL keeps the font first drawn for that visit instead, and `faces:` serves the files from the site, preloaded. The `code` role owns `--font-code`; Tailwind's `font-mono` reads `--font-mono`, a separate var you declare yourself. A role's face on an element it isn't wired onto — a wordmark in the heading face, say — is `font-family: var(--font-heading)`, or a utility of your own: `@theme inline { --font-display: var(--font-heading); }` in `styles.css`, then `font-display`.
99
+
100
+ ## styles.css
101
+
102
+ ```css
103
+ @import "tailwindcss";
104
+ @import "@uniweb/kit/theme-tokens.css";
105
+ @import "@uniweb/kit/prose-tokens.css";
106
+ @source "./sections/**/*.{js,jsx}";
107
+ @source "./components/**/*.{js,jsx}";
108
+ @source "./layouts/**/*.{js,jsx}";
109
+ @theme { --breakpoint-xs: 30rem; }
110
+ ```
111
+
112
+ Two more imports are opt-in: `@uniweb/kit/math-tokens.css` lays out equations, and `@uniweb/kit/callout-tokens.css` draws concept blocks such as `md:warning`, which are otherwise plain prose.
113
+
114
+ **Name every folder that writes classes.** The foundation's own build finds them all, but a site build and `uniweb dev` read only what these lines name, so a class in a folder left out is in one CSS and missing from the other. `uniweb dev`, a site build and `uniweb doctor` (`unread-folder`) give the line to add. `theme-tokens.css` also tells Tailwind to read kit's source, so kit's own classes reach your CSS wherever your package manager put kit; a foundation that skips that import names kit itself, by where kit is (`./node_modules/@uniweb/kit/src/**` under pnpm, `../node_modules/@uniweb/kit/src/**` under npm).
115
+
116
+ Custom CSS is expected alongside Tailwind — shadow systems, border hierarchies, gradients, glass. Tokens are a floor; add vocabulary that references them so it adapts per context:
117
+
118
+ ```css
119
+ .border-subtle { border-color: color-mix(in oklch, var(--border), transparent 50%); }
120
+ .text-tertiary { color: color-mix(in oklch, var(--body), var(--subtle) 50%); }
121
+ ```
122
+
123
+ Priority: design quality > portability > configurability. Four things a ported design brings that break something: global `scroll-behavior: smooth` (the runtime's `scrollTo(x, y)` inherits it and route changes animate/interrupt — scope it to an element); `filter: blur()` glows (Safari repaints them on the main thread during view transitions — use a radial `mask-image` instead); `-webkit-font-smoothing: antialiased` on `html` (scope it to `.scheme-dark`); JS-started entrance animations (write them in CSS so they start at first paint on a prerendered page).
package/partials/start.md CHANGED
@@ -3,20 +3,21 @@
3
3
 
4
4
  You're in the Uniweb project at `{{root}}`.
5
5
 
6
- Its pages are markdown files, and how they look and behave comes from its foundation:
7
- React components that the pages pick by name. The `uniweb` CLI builds and runs the
8
- project, and brings it into the Uniweb app, where the person you're working with can keep
9
- editing it visually.
6
+ Its pages are made of sections: structured content written in markdown, and drawn by its
7
+ foundation, React components that each section picks by name. The `uniweb` CLI builds and
8
+ runs the project, and brings it into the Uniweb app, where the person you're working with
9
+ can keep editing it visually.
10
10
 
11
11
  `uniweb start` only prints this guide; `npx uniweb dev` runs the site. To start a new
12
12
  project instead, run `npx uniweb@latest start` in a folder outside this one.
13
13
  {{else}}
14
14
  # Build a website with Uniweb
15
15
 
16
- You're building a website for the person you're working with. In Uniweb, the pages are
17
- markdown files, and how they look and behave comes from a foundation: React components
18
- that the pages pick by name. One project holds both. The `uniweb` CLI builds and runs it,
19
- and brings it into the Uniweb app, where the person can keep editing it visually.
16
+ You're building a website for the person you're working with. In Uniweb, a page is made of
17
+ sections: structured content written in markdown, and drawn by a foundation, React
18
+ components that each section picks by name. One project holds both. The `uniweb` CLI builds
19
+ and runs it, and brings it into the Uniweb app, where the person can keep editing it
20
+ visually.
20
21
  {{/if}}
21
22
 
22
23
  ## Run everything yourself
@@ -131,12 +132,12 @@ pages, text and theme here, but not its section types.
131
132
 
132
133
  {{#if agents}}
133
134
  AGENTS.md, at the project's root, is the manual for this project and its version of
134
- Uniweb. It's long, so read its Part 0 before writing code, then the parts it names for
135
+ Uniweb. Read it before writing code, and follow its procedure, which runs the guide for
135
136
  your task.
136
137
  {{else}}
137
138
  This project has no AGENTS.md, the manual for a Uniweb project. Write one with
138
- `npx uniweb update --agents-only`, then read its Part 0 before writing code, and the parts
139
- it names for your task.
139
+ `npx uniweb update --agents-only`, then read it before writing code, and follow its
140
+ procedure.
140
141
  {{/if}}
141
142
 
142
143
  Uniweb's mistakes are quiet: an unknown section type or param builds fine and renders
@@ -1451,6 +1451,8 @@ export default function ${name}({ content, params }) {
1451
1451
  `${colors.dim}The dev server will pick it up automatically.${colors.reset}`
1452
1452
  )
1453
1453
  }
1454
+ log('')
1455
+ log(`Before editing it: ${colors.cyan}${getCliPrefix()} guide foundation${colors.reset}`)
1454
1456
 
1455
1457
  if (starterResult) {
1456
1458
  // Regenerate against the declaration just written, so what is printed is
@@ -11,9 +11,10 @@
11
11
  *
12
12
  * --bundle (internal; called by `uniweb deploy --host` / `uniweb export`)
13
13
  * Full vite + post-vite pipeline. Produces a static-host JS bundle
14
- * (`dist/index.html`, `dist/entry.js`, `_importmap/*`, `_pages/*` for
15
- * split mode, sitemap/robots, each language's search index, llms.txt and
16
- * page markdown, prerendered HTML when configured). The foundation is
14
+ * (`dist/index.html`, the JS and CSS in `dist/assets/`, `_importmap/*` when
15
+ * a foundation or an extension loads by URL, `_pages/*` for split mode,
16
+ * sitemap/robots, each language's search index, llms.txt and page
17
+ * markdown, prerendered HTML when configured). The foundation is
17
18
  * statically inlined when site.yml names a
18
19
  * workspace-local one (the self-contained case), and loaded by URL when
19
20
  * it names a URL, or under VITE_FOUNDATION_MODE=runtime. A catalog ref
@@ -691,12 +692,13 @@ async function buildSite(projectDir, options = {}) {
691
692
 
692
693
  reportLocalizedSite(built)
693
694
  } catch (err) {
694
- error(`i18n build failed: ${err.message}`)
695
+ // ⛔ Until 2026-11-02 this said "Continuing without localized content" and the build ended
696
+ // complete and exit 0, with every page of every other language missing.
697
+ error(`Couldn't build the site's other languages: ${err.message}`)
695
698
  if (process.env.UNIWEB_DEBUG) {
696
699
  console.error(err.stack)
697
700
  }
698
- // Don't fail the build, just warn
699
- log(`${colors.yellow}Continuing without localized content${colors.reset}`)
701
+ process.exit(1)
700
702
  }
701
703
  }
702
704
 
@@ -720,6 +722,11 @@ async function buildSite(projectDir, options = {}) {
720
722
  success(
721
723
  `Pre-rendered ${result.pages} page${result.pages !== 1 ? 's' : ''} to static HTML`
722
724
  )
725
+ if (result.skipped?.length > 0) {
726
+ log(
727
+ `${colors.yellow}${result.skipped.length} page${result.skipped.length !== 1 ? 's' : ''} left to render in the browser: ${result.skipped.join(', ')}${colors.reset}`
728
+ )
729
+ }
723
730
 
724
731
  // Summary
725
732
  log('')
@@ -6,9 +6,10 @@
6
6
  * CloudFront, etc.). Does NOT upload anywhere — `uniweb deploy --host`
7
7
  * uploads to a third-party host; `uniweb publish` ships to Uniweb hosting.
8
8
  *
9
- * The `dist/` output bundles the runtime + foundation + content into
10
- * concatenated packaging, with a vite-built `index.html` + `entry.js` +
11
- * `assets/`. The user copies it to whatever host they like.
9
+ * The `dist/` output concatenates the runtime and a local foundation into the
10
+ * site's JS (a foundation named by URL stays a URL), with the content beside
11
+ * that JS and never in it: a vite-built `index.html` + `entry.js` + `assets/`.
12
+ * The user copies it to whatever host they like.
12
13
  *
13
14
  * Internally this is `uniweb build --bundle` plus user guidance for the
14
15
  * upload step. The `--link` / `--bundle` flag pair is internal-only
@@ -0,0 +1,89 @@
1
+ /**
2
+ * `uniweb guide` — the part of a project's manual that isn't in its AGENTS.md.
3
+ *
4
+ * AGENTS.md holds what an agent would confidently get wrong, and each guide holds the rest of a
5
+ * subject, one command away. They ship in this package (`partials/guides/`), so what a project's
6
+ * CLI prints describes the code in that project's `node_modules`, and nothing is added to the
7
+ * project.
8
+ *
9
+ * ⭐ FOR AN AGENT, SO THE TEXT IS ALL THERE IS. The file goes to stdout as it is: no banner, no
10
+ * color, no pager. `--path` names the file, for a tool that cuts long output.
11
+ *
12
+ * ⛔ READ-ONLY, AND SAFE ANYWHERE. No network, no project files and no cache, so it also works in
13
+ * an empty folder (`npx uniweb@latest guide start`). `index.js` answers it before the update
14
+ * check, as it does `start`. Unlike `start` it is delegated to a project's own CLI, because the
15
+ * guide has to match the version the project pins.
16
+ */
17
+
18
+ import { readFileSync } from 'node:fs'
19
+ import { dirname, join } from 'node:path'
20
+ import { fileURLToPath } from 'node:url'
21
+ import { didYouMean } from '../utils/args.js'
22
+ import { checkFlags } from '../utils/flag-guard.js'
23
+
24
+ const GUIDES_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'partials', 'guides')
25
+
26
+ /**
27
+ * The guides, in the order `uniweb guide` lists them.
28
+ *
29
+ * @returns {Array<{ name: string, title: string, description: string }>}
30
+ */
31
+ export function listGuides() {
32
+ return JSON.parse(readFileSync(join(GUIDES_DIR, 'index.json'), 'utf8'))
33
+ }
34
+
35
+ /** Where a guide's file is. */
36
+ export function guidePath(name) {
37
+ return join(GUIDES_DIR, `${name}.md`)
38
+ }
39
+
40
+ /**
41
+ * What a guide's name was probably meant to be, and every name there is, for a name that isn't one.
42
+ *
43
+ * @param {string} name
44
+ * @param {string[]} names
45
+ * @returns {string}
46
+ */
47
+ function unknownGuide(name, names) {
48
+ const near = didYouMean(name, names)
49
+ return [
50
+ `No guide named \`${name}\`.${near ? ` Did you mean \`${near}\`?` : ''}`,
51
+ ` Guides: ${names.join(', ')}`,
52
+ ].join('\n')
53
+ }
54
+
55
+ /**
56
+ * @param {string[]} [args] - guide names, and `--path`
57
+ * @returns {Promise<{ exitCode: number }>}
58
+ */
59
+ export async function guide(args = []) {
60
+ const badFlag = checkFlags('guide', args)
61
+ if (badFlag) {
62
+ console.error(badFlag.message)
63
+ return { exitCode: 2 }
64
+ }
65
+
66
+ const guides = listGuides()
67
+ const asked = args.filter((arg) => !arg.startsWith('-'))
68
+
69
+ if (asked.length === 0) {
70
+ const width = Math.max(...guides.map((g) => g.name.length))
71
+ for (const g of guides) console.log(`${g.name.padEnd(width)} ${g.description}`)
72
+ return { exitCode: 0 }
73
+ }
74
+
75
+ const names = guides.map((g) => g.name)
76
+ const unknown = asked.find((name) => !names.includes(name))
77
+ if (unknown) {
78
+ console.error(unknownGuide(unknown, names))
79
+ return { exitCode: 1 }
80
+ }
81
+
82
+ if (args.includes('--path')) {
83
+ for (const name of asked) console.log(guidePath(name))
84
+ return { exitCode: 0 }
85
+ }
86
+
87
+ process.stdout.write(asked.map((name) => readFileSync(guidePath(name), 'utf8').trimEnd()).join('\n\n---\n\n') + '\n')
88
+ return { exitCode: 0 }
89
+ }
@@ -679,10 +679,10 @@ export async function publish(args = []) {
679
679
  reportSchemalessQueries(probe.schemaless, say)
680
680
  const localAssets = probe.localAssets || []
681
681
 
682
- // 3a. A clone with no `$uuid` is bound to no backend site, so every cached map
683
- // that describes one is stale — including after the documented "clear
684
- // `$uuid` to re-publish as a new site" recovery. Must run BEFORE the create,
685
- // which mints a uuid and would make the clone look bound.
682
+ // 3a. A copy with no site uuid for this backend (`sync.json`) is bound to no site
683
+ // there, so every cached map that describes one is stale. `uniweb forget` clears
684
+ // the maps with the uuid; this catches a uuid gone any other way. Must run BEFORE
685
+ // the create, which mints a uuid and would make the copy look bound.
686
686
  const droppedState = clearRemoteSyncStateIfUnbound(siteDir, client.origin)
687
687
  if (droppedState.length) {
688
688
  say.dim(
@@ -697,7 +697,8 @@ export async function publish(args = []) {
697
697
  // so a repeatedly-failing first publish would burn quota with no recovery
698
698
  // short of support. Creating the site first makes the artifact of a failed
699
699
  // publish an EMPTY SITE instead: it costs nothing to keep and the owner can
700
- // clear it. A no-op once `$uuid` is set, so only a first publish pays.
700
+ // clear it. A no-op once `sync.json` holds this backend's site uuid, so only
701
+ // a first publish pays.
701
702
  //
702
703
  // This ordering is load-bearing, not incidental — the asset plan requires an
703
704
  // owner. A test asserts the create precedes the upload.
@@ -348,11 +348,12 @@ export async function push(args = [], deps = {}) {
348
348
  // ⛔ DROP STALE REMOTE STATE FIRST — this must precede the hash read below, and it
349
349
  // did not until 2026-08-19.
350
350
  //
351
- // The guard itself is right and its docblock names this exact outcome: on a clone
352
- // whose `$uuid` was cleared to re-publish as a new site — WHICH IS OUR OWN
353
- // DOCUMENTED RECOVERY — send-only-changed would "skip every entity whose content
354
- // had not changed since the OLD site's last push, so the NEW site would come up
355
- // missing exactly the content that did not change." It was defeated twice over:
351
+ // The guard itself is right and its docblock names this exact outcome: on a copy
352
+ // whose site uuid went without the maps — which our own guidance to clear `$uuid`
353
+ // led to, until 2026-09-21; `uniweb forget` takes both now — send-only-changed would
354
+ // "skip every entity whose content had not changed since the OLD site's last push,
355
+ // so the NEW site would come up missing exactly the content that did not change."
356
+ // It was defeated twice over:
356
357
  //
357
358
  // · it ran AFTER `readSyncCache`, so the emit still diffed against the old
358
359
  // site's hashes even though the file on disk had just been emptied;
@@ -483,7 +484,8 @@ export async function push(args = [], deps = {}) {
483
484
  if (mediaRefs.length) {
484
485
  // The site has to exist before its bytes do — an upload with no owning
485
486
  // entity is charged and cannot be freed, because freeing means deleting the
486
- // owner. A no-op once `$uuid` is set, so only a never-synced site pays.
487
+ // owner. A no-op once `sync.json` holds this backend's site uuid, so only a
488
+ // never-synced site pays.
487
489
  // ⛔ The PINNED ref, not site.yml's. The create is a THIRD writer of this
488
490
  // value — the emit below stamps it via `injectInfo`, publish passes it here,
489
491
  // and push did neither until 2026-08-19: it sent the authored alias (`src`),
@@ -904,6 +904,17 @@ async function foundationCheck(siteDir, siteYml, client) {
904
904
  return { id: 'app.foundation', state: 'ok', summary: `The site pins the latest version of its foundation (${fndVersion}).` }
905
905
  }
906
906
 
907
+ /**
908
+ * What moves a project to a newer Uniweb. `--yes` because an agent has no terminal to answer the
909
+ * prompt, and the docs are why it can't wait: they describe the latest release.
910
+ */
911
+ const LATEST_UPDATE = {
912
+ step: 'update',
913
+ latest: true,
914
+ command: 'npx uniweb@latest update --yes',
915
+ why: 'bring the project and its AGENTS.md up to date, since the docs describe the latest release — then build, and look at the pages'
916
+ }
917
+
907
918
  /** `uniweb.version`: a newer Uniweb, named the same way for every release. */
908
919
  async function versionCheck(siteDir, { offline }) {
909
920
  const runs = projectUniweb(siteDir)
@@ -915,7 +926,7 @@ async function versionCheck(siteDir, { offline }) {
915
926
  }
916
927
  return {
917
928
  checks: [{ id: 'uniweb.version', state: 'attention', summary: `Uniweb ${latest} is out; this project runs ${runs}.`, detail: { runs, latest } }],
918
- proposals: [{ step: 'update', latest: true, command: 'npx uniweb@latest update', why: 'bring the project and its AGENTS.md up to date — then build, and look at the pages' }]
929
+ proposals: [LATEST_UPDATE]
919
930
  }
920
931
  }
921
932
 
@@ -944,7 +955,7 @@ async function doctorCheck(siteDir) {
944
955
  const newer = isBehind(projectUniweb(siteDir), getCliVersion())
945
956
  proposals.push(
946
957
  newer
947
- ? { step: 'update', latest: true, command: 'npx uniweb@latest update', why: 'bring the project and its AGENTS.md up to date — then build, and look at the pages' }
958
+ ? LATEST_UPDATE
948
959
  : { step: 'update', command: 'npx uniweb update', why: "align the dependencies and AGENTS.md with this project's Uniweb" }
949
960
  )
950
961
  }
@@ -1489,7 +1500,7 @@ const ICON = {
1489
1500
  skipped: `${c.dim}·${c.reset}`
1490
1501
  }
1491
1502
 
1492
- function render({ summary, backend, checks, next }) {
1503
+ function render({ summary, backend, checks, next, neverShipped }) {
1493
1504
  const out = ['']
1494
1505
  out.push(`${c.bold}${summary}${c.reset}`)
1495
1506
  for (const [prefix, title] of GROUPS) {
@@ -1520,6 +1531,10 @@ function render({ summary, backend, checks, next }) {
1520
1531
  }
1521
1532
  })
1522
1533
  }
1534
+ if (neverShipped) {
1535
+ out.push('')
1536
+ out.push(`First time shipping this project? ${c.cyan}npx uniweb guide ship${c.reset}`)
1537
+ }
1523
1538
  const unknown = checks.filter((k) => k.state === 'unknown').map((k) => k.id)
1524
1539
  if (unknown.length) {
1525
1540
  out.push('')
@@ -1708,7 +1723,9 @@ export async function status(args = []) {
1708
1723
  )
1709
1724
  return { exitCode: 0 }
1710
1725
  }
1711
- console.log(render({ summary, backend: app.backend, checks, next }))
1726
+ // Nowhere yet: no site on a backend and no deploy on a host.
1727
+ const neverShipped = !synced.length && !deploys.targets.some((t) => t.deployed)
1728
+ console.log(render({ summary, backend: app.backend, checks, next, neverShipped }))
1712
1729
  return { exitCode: 0 }
1713
1730
  }
1714
1731
 
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-02T06:00:38.485Z",
3
+ "generatedAt": "2026-11-02T19:27:56.253Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.9"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.14.1"
9
+ "version": "1.14.3"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.8"
@@ -24,19 +24,19 @@
24
24
  "version": "1.0.8"
25
25
  },
26
26
  "@uniweb/kit": {
27
- "version": "1.7.1"
27
+ "version": "1.7.3"
28
28
  },
29
29
  "@uniweb/loom": {
30
- "version": "1.1.2"
30
+ "version": "1.1.3"
31
31
  },
32
32
  "@uniweb/press": {
33
- "version": "1.2.1"
33
+ "version": "1.2.2"
34
34
  },
35
35
  "@uniweb/projections": {
36
36
  "version": "1.2.10"
37
37
  },
38
38
  "@uniweb/runtime": {
39
- "version": "1.3.11"
39
+ "version": "1.3.13"
40
40
  },
41
41
  "@uniweb/scene": {
42
42
  "version": "1.0.1"
@@ -54,7 +54,7 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.2.1"
57
+ "version": "1.2.3"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.2.1"
package/src/index.js CHANGED
@@ -721,6 +721,21 @@ async function main() {
721
721
  return
722
722
  }
723
723
 
724
+ // `guide` — the rest of a project's manual (commands/guide.js). Reached here from a project's
725
+ // own CLI, or with no project at all; like `start`, it asks nothing and makes no request. Its
726
+ // output is the file and nothing else, so the exit code is set rather than exited on, which
727
+ // would cut a long guide short on a pipe.
728
+ if (command === 'guide') {
729
+ if (args.slice(1).some((a) => a === '--help' || a === '-h')) {
730
+ printCommandHelp('guide')
731
+ return
732
+ }
733
+ const { guide } = await import('./commands/guide.js')
734
+ const { exitCode } = await guide(args.slice(1))
735
+ process.exitCode = exitCode
736
+ return
737
+ }
738
+
724
739
  // Update check for global installs.
725
740
  //
726
741
  // - `create` / `clone` STOP when a newer release exists, before anything is
@@ -1437,7 +1452,7 @@ async function main() {
1437
1452
  }
1438
1453
  log('')
1439
1454
  log(
1440
- ` ${colors.bright}AGENTS.md${colors.reset} is the project's manual, for you and for AI agents: its Part 0 says where to begin.`
1455
+ ` ${colors.bright}AGENTS.md${colors.reset} is the project's manual, for you and for AI agents: read it before you start.`
1441
1456
  )
1442
1457
  if (recPm !== 'pnpm') {
1443
1458
  log('')
@@ -1595,6 +1610,20 @@ pay when the site goes live; the guide has the agent run every command.
1595
1610
  Inside a Uniweb project it starts from that project instead of creating one.
1596
1611
  It asks nothing, writes nothing and makes no request, so it is safe to run
1597
1612
  anywhere. To run a site's dev server, use \`uniweb dev\`.
1613
+ `,
1614
+ guide: `
1615
+ ${colors.cyan}${colors.bright}uniweb guide${colors.reset} ${colors.dim}— The rest of a project's manual, one subject at a time${colors.reset}
1616
+
1617
+ ${colors.bright}Usage:${colors.reset}
1618
+ uniweb guide List the guides
1619
+ uniweb guide <name> Print a guide, in Markdown
1620
+ uniweb guide <name> <name> Print several
1621
+ uniweb guide <name> --path Print where its file is, to read instead
1622
+
1623
+ AGENTS.md holds what an agent would otherwise get wrong, and tells it which guide
1624
+ to run for a task. The guides ship with the CLI, so in a project they describe the
1625
+ version the project pins. They need no network and no project, so
1626
+ \`npx uniweb@latest guide start\` works in an empty folder.
1598
1627
  `,
1599
1628
  dev: `
1600
1629
  ${colors.cyan}${colors.bright}uniweb dev${colors.reset} ${colors.dim}— Start a dev server for a site${colors.reset}
@@ -2343,6 +2372,7 @@ ${colors.bright}Usage:${colors.reset}
2343
2372
 
2344
2373
  ${colors.bright}Commands:${colors.reset}
2345
2374
  start How an AI agent begins a site (a guide; changes nothing)
2375
+ guide [name] Print a guide to building with Uniweb: content, foundation, theme, …
2346
2376
  create [name] Create a new project
2347
2377
  clone <site-uuid> Clone a backend site into a local file project
2348
2378
  add <type> [name] Add a foundation, site, or extension to a project
@@ -31,13 +31,28 @@ export function readAgentsVersion(filePath) {
31
31
  }
32
32
 
33
33
  /**
34
- * Generate AGENTS.md content with version stamp
35
- * @returns {string} Full AGENTS.md content with stamp
34
+ * ⭐ THE LAST LINE OF EVERY AGENTS.md, after any project notes. A tool may cut an instruction file
35
+ * without saying so: Codex stops at `project_doc_max_bytes`, 32 KiB by default, counting every
36
+ * instruction file it has read, and a person can raise that. So the file doesn't promise to fit
37
+ * [Diego, 2026-11-02]. It says near its top, inside any cap, that this line ends it, and an agent
38
+ * that can't see the line reads the rest itself.
36
39
  */
37
- export function generateAgentsContent() {
40
+ export const AGENTS_END_LINE = 'End of AGENTS.md'
41
+
42
+ /** The partial, stamped, with nothing after it. */
43
+ function stampedPartial() {
38
44
  const partialsDir = join(__dirname, '..', '..', 'partials')
39
45
  const agentsContent = readFileSync(join(partialsDir, 'agents.md'), 'utf8')
40
- return `<!-- uniweb-agents v${getCliVersion()} -->\n${agentsContent}\n`
46
+ return `<!-- uniweb-agents v${getCliVersion()} -->\n${agentsContent.trimEnd()}`
47
+ }
48
+
49
+ /**
50
+ * Generate AGENTS.md content with version stamp: what `create` writes, and what `update` writes
51
+ * for a project with no notes.
52
+ * @returns {string} Full AGENTS.md content with stamp
53
+ */
54
+ export function generateAgentsContent() {
55
+ return `${stampedPartial()}\n\n${AGENTS_END_LINE}\n`
41
56
  }
42
57
 
43
58
  /**
@@ -91,20 +106,19 @@ export function readProjectNotes(text) {
91
106
  }
92
107
 
93
108
  /**
94
- * AGENTS.md as `update` writes it: this CLI's partial, stamped, and the project-notes blocks of the
95
- * file it replaces after it.
109
+ * AGENTS.md as `update` writes it: this CLI's partial, stamped, the project-notes blocks of the
110
+ * file it replaces after it, and the line that ends the file.
96
111
  *
97
112
  * @param {string|null} existing - the current AGENTS.md, or null when there is none
98
113
  * @returns {{ content: string, kept: number } | { error: string }}
99
114
  */
100
115
  export function refreshAgentsContent(existing) {
101
- const fresh = generateAgentsContent()
102
- if (existing == null) return { content: fresh, kept: 0 }
116
+ if (existing == null) return { content: generateAgentsContent(), kept: 0 }
103
117
  const notes = readProjectNotes(existing)
104
118
  if (notes.error) return notes
105
- if (!notes.blocks.length) return { content: fresh, kept: 0 }
119
+ if (!notes.blocks.length) return { content: generateAgentsContent(), kept: 0 }
106
120
  return {
107
- content: `${fresh.replace(/\s+$/, '')}\n\n${notes.blocks.join('\n\n')}\n`,
121
+ content: `${stampedPartial()}\n\n${notes.blocks.join('\n\n')}\n\n${AGENTS_END_LINE}\n`,
108
122
  kept: notes.blocks.length,
109
123
  }
110
124
  }
@@ -142,7 +142,9 @@ const VERBS = {
142
142
  * `flag-guard-coverage.test.js`'s walk does not see it). ⛔ Until 2026-10-25 `dev` checked
143
143
  * no flags, and read the value of `--port 5199` as the name of a site.
144
144
  */
145
- dev: ['--site', '--port', '--status', '--stop', '--org', '--personal']
145
+ dev: ['--site', '--port', '--status', '--stop', '--org', '--personal'],
146
+ // Prints a file: a flag it doesn't know is a typo, not a backend it might reach.
147
+ guide: ['--path']
146
148
  }
147
149
 
148
150
  /**