uniweb 1.25.3 → 1.25.5

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.
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('')
@@ -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
+ }
@@ -168,6 +168,16 @@ function readSiteYml(path) {
168
168
  }
169
169
  }
170
170
 
171
+ // The backend's own sentences about a publish, for the person: what it changed (`applied`, a
172
+ // confirmed change or a reduction), then what it did not change and they should know (`notes`),
173
+ // such as something asked for that this deployment does not serve. The publish went through, so
174
+ // nothing else would say so.
175
+ export function publishSentences(result) {
176
+ return [result?.applied, result?.notes]
177
+ .flatMap((list) => (Array.isArray(list) ? list : []))
178
+ .filter((line) => typeof line === 'string' && line)
179
+ }
180
+
171
181
  // Languages from the BUILT site — the authority after a build: `config.languages` where
172
182
  // the site declares them (three accepted shapes: 'en', { value, label }, { code, label }),
173
183
  // else its default and each language the build produced (`dist/<locale>/site-content.json`).
@@ -1141,11 +1151,7 @@ export async function publish(args = []) {
1141
1151
  say.ok(
1142
1152
  `Published ${c.bold}${siteUuid}${c.reset}${result.status ? ` (${result.status})` : ''}`
1143
1153
  )
1144
- // What the request changed, in the backend's own sentences — a confirmed change, or a reduction
1145
- // (`applied`, its §4A). Absent when nothing changed.
1146
- for (const line of Array.isArray(result.applied) ? result.applied : []) {
1147
- if (typeof line === 'string' && line) say.info(line)
1148
- }
1154
+ for (const line of publishSentences(result)) say.info(line)
1149
1155
 
1150
1156
  // ⛔ SAY IT WHEN A LANGUAGE ASKED FOR DID NOT GO OUT.
1151
1157
  //
@@ -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
  }
@@ -1384,6 +1395,14 @@ function workflowsCheck(siteDir) {
1384
1395
 
1385
1396
  const list = (names) => names.map((n) => `\`${n}\``).join(', ')
1386
1397
 
1398
+ /**
1399
+ * Asked for, and never among what a publish reports delivering (`last_published_services`):
1400
+ * a host loads Google's tag, so nothing answers at an address and nothing is sold. By that
1401
+ * comparison it would read "not live yet" for ever, and send an agent back to publish. A row
1402
+ * changed since the last publish still says so, as `draft_dirty`.
1403
+ */
1404
+ const NOT_REPORTED_AS_LIVE = new Set(['google'])
1405
+
1387
1406
  /**
1388
1407
  * `app.services`: what `site.yml` asks for, beside what the backend holds — the request it
1389
1408
  * stored, and what the last publish delivered (`last_published_services`). Comparing the
@@ -1421,7 +1440,7 @@ async function servicesCheck({ siteDir, siteYml, site }) {
1421
1440
  }
1422
1441
  const live = on(site.last_published_services)
1423
1442
  const requested = on(site.services)
1424
- const waiting = requested.filter((n) => !live.includes(n))
1443
+ const waiting = requested.filter((n) => !live.includes(n) && !NOT_REPORTED_AS_LIVE.has(n))
1425
1444
  if (waiting.length && site.published) {
1426
1445
  lines.push(`Requested, not live yet: ${list(waiting)} — publishing makes ${waiting.length === 1 ? 'it' : 'them'} live, and may ask for payment.`)
1427
1446
  proposals.push({ step: 'publish', command: 'npx uniweb publish', why: 'make those changes live — the person decides', ask: true })
@@ -1481,7 +1500,7 @@ const ICON = {
1481
1500
  skipped: `${c.dim}·${c.reset}`
1482
1501
  }
1483
1502
 
1484
- function render({ summary, backend, checks, next }) {
1503
+ function render({ summary, backend, checks, next, neverShipped }) {
1485
1504
  const out = ['']
1486
1505
  out.push(`${c.bold}${summary}${c.reset}`)
1487
1506
  for (const [prefix, title] of GROUPS) {
@@ -1512,6 +1531,10 @@ function render({ summary, backend, checks, next }) {
1512
1531
  }
1513
1532
  })
1514
1533
  }
1534
+ if (neverShipped) {
1535
+ out.push('')
1536
+ out.push(`First time shipping this project? ${c.cyan}npx uniweb guide ship${c.reset}`)
1537
+ }
1515
1538
  const unknown = checks.filter((k) => k.state === 'unknown').map((k) => k.id)
1516
1539
  if (unknown.length) {
1517
1540
  out.push('')
@@ -1700,7 +1723,9 @@ export async function status(args = []) {
1700
1723
  )
1701
1724
  return { exitCode: 0 }
1702
1725
  }
1703
- 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 }))
1704
1729
  return { exitCode: 0 }
1705
1730
  }
1706
1731
 
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-02T04:09:19.127Z",
3
+ "generatedAt": "2026-11-02T16:57:17.019Z",
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.2"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.8"
@@ -24,10 +24,10 @@
24
24
  "version": "1.0.8"
25
25
  },
26
26
  "@uniweb/kit": {
27
- "version": "1.7.1"
27
+ "version": "1.7.2"
28
28
  },
29
29
  "@uniweb/loom": {
30
- "version": "1.1.2"
30
+ "version": "1.1.3"
31
31
  },
32
32
  "@uniweb/press": {
33
33
  "version": "1.2.1"
@@ -36,7 +36,7 @@
36
36
  "version": "1.2.10"
37
37
  },
38
38
  "@uniweb/runtime": {
39
- "version": "1.3.10"
39
+ "version": "1.3.12"
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.2"
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
  /**
@@ -18,6 +18,7 @@ import {
18
18
  } from '../templates/processor.js'
19
19
  import { getVersionsForTemplates, getCliVersion } from '../versions.js'
20
20
  import { writeJsonPreservingStyleAsync } from './json-file.js'
21
+ import { generateAgentsContent } from './agents-stamp.js'
21
22
 
22
23
  const __dirname = dirname(fileURLToPath(import.meta.url))
23
24
  const TEMPLATES_DIR = join(__dirname, '..', '..', 'templates')
@@ -46,8 +47,8 @@ export async function scaffoldWorkspace(targetDir, context, options = {}) {
46
47
  // because an empty packages: [] makes pnpm search parent directories.
47
48
  const skip = context.workspaceGlobs?.length ? [] : ['pnpm-workspace.yaml']
48
49
 
49
- // Inject CLI version for AGENTS.md stamp
50
- context = { ...context, cliVersion: getCliVersion() }
50
+ // AGENTS.md comes from the one writer `update` uses too, so `create` and `update` can't differ.
51
+ context = { ...context, cliVersion: getCliVersion(), agentsContent: generateAgentsContent() }
51
52
 
52
53
  const templatePath = join(TEMPLATES_DIR, 'workspace')
53
54
  await copyTemplateDirectory(templatePath, targetDir, context, {
@@ -1,2 +1 @@
1
- <!-- uniweb-agents v{{cliVersion}} -->
2
- {{> agents}}
1
+ {{{agentsContent}}}
@@ -133,7 +133,8 @@ conventions, instead of a blank canvas. What an agent builds here, authors can u
133
133
  after the next sync.
134
134
 
135
135
  [AGENTS.md](./AGENTS.md) is written for developers and AI agents alike. Many coding agents read it
136
- on their own when they start in this folder; point any other agent at it first.
136
+ on their own when they start in this folder; point any other agent at it first. `npx uniweb guide`
137
+ prints the rest of the manual, one subject at a time.
137
138
  `npx uniweb@latest update` moves the project to the latest release of Uniweb, and AGENTS.md with
138
139
  it.
139
140