uniweb 1.26.9 → 1.27.0

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "uniweb",
3
- "version": "1.26.9",
3
+ "version": "1.27.0",
4
4
  "description": "Create structured Vite + React sites with content/code separation",
5
5
  "type": "module",
6
6
  "bin": {
@@ -47,7 +47,7 @@
47
47
  "@uniweb/schemas": "~1.6.8"
48
48
  },
49
49
  "peerDependencies": {
50
- "@uniweb/build": "~1.15.6",
50
+ "@uniweb/build": "~1.16.0",
51
51
  "@uniweb/content-reader": "~1.5.9",
52
52
  "@uniweb/semantic-parser": "~1.13.2"
53
53
  },
@@ -249,7 +249,7 @@ content = { title, pretitle, subtitle, paragraphs, links, images, icons, videos,
249
249
 
250
250
  **Backgrounds and theme are frontmatter.** `background:` takes an image, video, gradient, quoted color or palette token, or an object (`image`, `video`, `overlay`); `theme: light | medium | dark`, or a map with token overrides (`section: neutral-100`).
251
251
 
252
- **Pages.** `pages/<name>/` → `/<name>`; a name or `slug:` holding `?`, `#` or `%` stops the build. `page.yml`: `title`, `description`, `id`, `order`, `sections: [a, b, ...]`, `pages: [...]`, `nest`, `redirect`, `slug: { fr: … }`, `hidden` (draft; takes the pages below it), `hideIn` (nav only), `knowledge` (agent-only, never rendered — not a security control), `query` / `fetch`, `seo`, `layout`. `folder.yml` for a folder *of pages*. Numeric prefixes order sections; `2.5-x.md` slots between. Config cascades `page.yml → folder.yml → site.yml → foundation`. `layout/header.md`, `footer.md` render on every page — a markdown list is the nav, a standalone link the CTA, `yaml:nav` for richer menus. Child sections: `@child.md` + `nest: { parent: [child] }`.
252
+ **Pages.** `pages/<name>/` → `/<name>`; a name or `slug:` holding `?`, `#` or `%` stops the build. `page.yml`: `title`, `description`, `id`, `order`, `sections: [a, b, ...]`, `pages: [...]`, `nest`, `redirect`, `slug: { fr: … }`, `hidden` (draft; takes the pages below it), `hideIn` (nav only), `knowledge` (agent-only, never rendered — not a security control), `query` / `fetch`, `seo`, `layout`. `folder.yml` for a folder *of pages*. Numeric prefixes (a number then a dash) order sections, pages and page folders and never reach a URL: `2-about/` is `/about`, and `pages:`/`index:` name it `about`; `2.5-x.md` slots between; `3d-printing` has no number. Config cascades `page.yml → folder.yml → site.yml → foundation`. `layout/header.md`, `footer.md` render on every page — a markdown list is the nav, a standalone link the CTA, `yaml:nav` for richer menus. Child sections: `@child.md` + `nest: { parent: [child] }`.
253
253
 
254
254
  **`site.yml`.** `index`, `pages`, `foundation`, `extensions`, `paths`, `placeholders`, `languages`, `services`, `agents`, `seo` (`origin`: scheme + host, `image`: 1200×630), `favicon`, `touchIcon`. Everything in `site.yml` and `queries.yml` ships to the browser — **never a secret**.
255
255
 
@@ -209,7 +209,7 @@ site/pages/home/
209
209
  └── 2-features.md
210
210
  ```
211
211
 
212
- Decimals insert between (`2.5-x.md`). Ignored: `README.md`, `_*.md`, `_*/`.
212
+ Decimals insert between (`2.5-x.md`). A page folder's number works the same way: `pages/2-about/` orders second and is `/about`, named `about` in `pages:` and `index:`. A number counts only with a dash after it, or as the whole name (`404`): `3d-printing.md` keeps its name. Ignored: `README.md`, `_*.md`, `_*/`.
213
213
 
214
214
  ```yaml
215
215
  # page.yml
@@ -237,9 +237,11 @@ extensions: ['@acme/fx@0.3.1']
237
237
 
238
238
  **Cascade:** `page.yml → folder.yml → site.yml → foundation defaults`. Put `layout: marketing` in a `folder.yml` and every page inherits it; one page can still override.
239
239
 
240
+ **A folder of pages holds pages of one section.** Under a `folder.yml`, each page is one `.md` file of one section, and each subfolder is a folder of pages too. The build stops on a subfolder with a `page.yml` of its own, a parametric `[slug]/` included. A page of several sections goes outside the folder. In the app, such a page takes no second section, and a pull holds one made there.
241
+
240
242
  **Routes:** folders map 1:1 to routes; `pages:` controls order only. The site root is the exception: the first of `pages:` sets `/`, else `index:`, declared in `site.yml` or in the pages directory's own `folder.yml`/`page.yml`, with `site.yml` winning. A folder with `page.yml` but no markdown is a structural group (`hasContent: false`); visiting it redirects to the first descendant with content.
241
243
 
242
- **Mounted folders:** a local folder for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subfolder in the local folder isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested folder, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere. A mount that is its own repository (a submodule, or a clone beside the site) takes its edits as commits there, and `uniweb refresh` takes its latest; a push or publish stops on one that is behind its remote or holds uncommitted changes, and `--mounts-as-is` sends it as it is. A pull leaves a mounted folder as it is and names each page an author changed in the app, which the next push undoes; `pages/docs: { path: ../docs, writable: true }` has a pull write those edits into the folder instead, where the site's own repository holds it or a submodule of it does (a commit there, to push before the site's repository), and stop on a writable mount anywhere else.
244
+ **Mounted folders:** a local folder for a mounted route says how *this site* presents it. Keep `layout:`, `title:` and SEO in a `folder.yml` there; the mounted repo's own `folder.yml` supplies ordering and title where the stub is silent. A `page.yml` with markdown of its own makes a real page above the mounted pages — a landing page for the branch. A mount is one level under `pages/`, and a subfolder in the local folder isn't read, since the branch's pages come from the mount; the build says so. What a site can't do from outside a repo it mounts: leave a file out, title or order a nested folder, or use a `README.md` as a page — those are the mounted repo's to do. A relative link to a markdown file (`./deploying.md#setup`), which is how docs in a repo link to each other, leads to the page that file became; the build names one that leads nowhere. A mount that is its own repository (a submodule, or a clone beside the site) takes its edits as commits there, and `uniweb refresh` takes its latest; a push or publish stops on one that is behind its remote or holds uncommitted changes, and `--mounts-as-is` sends it as it is. A pull writes an author's app edits into a mounted folder where the site's own repository holds it, or a submodule of it does (a commit there, to push before the site's repository). A folder it cannot merge into — a clone beside the site — keeps its text and the app keeps the author's: the pull and `status` name each such page as held, and a push leaves it alone while its file is unchanged. A mount is its folder, `pages/docs: ../docs`; the object form is refused.
243
245
 
244
246
  **Visibility flags:** `hidden: true` is a draft (not published; `uniweb dev` previews it; on a page it takes the pages below with it; on a section it's also kept from the component's params and takes its children with it); `hideIn: ['*']` or `[header]` controls nav placement only; `knowledge: true` is a different audience (below). An authored `pages/404/` needs no flag — `hidden: true` there makes it a draft and the site falls back to the generic 404.
245
247
 
@@ -47,6 +47,7 @@ import {
47
47
  computeUnitHashes,
48
48
  collectSiteUnits,
49
49
  collectUnitUuids,
50
+ heldUnitsOf,
50
51
  collectFolderItemUuids,
51
52
  collectFolderRecordTypes,
52
53
  collectQueryUuids,
@@ -976,6 +977,69 @@ export function writeItemBaseVersions(siteDir, backend, versions) {
976
977
  if (!versions || typeof versions !== 'object') return
977
978
  updateSyncCache(siteDir, backend, { itemBaseVersions: { ...versions } })
978
979
  }
980
+ /**
981
+ * ⭐ WHAT A PULL HELD — `{ <unit path>: <hash> }`: each page or section the app changed in a way its
982
+ * files cannot say, where the files keep it, with what they said there at the pull
983
+ * (`@uniweb/build`'s `held-units.js`). A push leaves out each whose files still say it, so the backend
984
+ * keeps the app's version — it deletes only an item a push holds a version for, and a pull banks none
985
+ * for these (`agreedVersions`) — and stops on one whose files changed since. REPLACED by every pull that
986
+ * takes the site's content, and empty when it held nothing. Per copy, like every map here: a copy
987
+ * without it has no base either, and a push refuses it until a pull records both (`untakenBase`).
988
+ */
989
+ export function readHeldUnits(siteDir, backend) {
990
+ return readMap(siteDir, backend, 'heldUnits')
991
+ }
992
+ export function writeHeldUnits(siteDir, backend, held) {
993
+ updateSyncCache(siteDir, backend, { heldUnits: { ...(held || {}) } })
994
+ }
995
+
996
+ /**
997
+ * What a pull held, as the files it wrote into keep it (`heldUnitsOf`): each held item's unit, and
998
+ * every unit below a held page, by path, with the hash the files give it — the files' document before
999
+ * any media is rewritten, as a push compares it. Found by the identity this copy held BEFORE the pull
1000
+ * (`itemUuids`), so a page the app moved is found where the files still keep it. Offline.
1001
+ *
1002
+ * @param {string} siteDir - the files the pull wrote into: the stand-in, in a repository
1003
+ * @param {string} backend
1004
+ * @param {{ held: Iterable<string>, itemUuids?: object, declarations?: Map, fields?: object }} opts
1005
+ * @returns {Promise<Object<string,string>>}
1006
+ */
1007
+ export async function heldUnitBaseline(siteDir, backend, { held = [], itemUuids = {}, declarations = null, fields = null } = {}) {
1008
+ const uuids = [...held]
1009
+ if (!uuids.length) return {}
1010
+ const pkg = await comparisonEmit(siteDir, { backend, sendAll: true, declarations, fields, heldUnits: {}, extra: { unitHashes: true, itemUuids } })
1011
+ return heldUnitsOf({ hashes: pkg.unitHashes || {}, uuids: pkg.unitUuids || {}, held: uuids })
1012
+ }
1013
+
1014
+ // A held unit's page, by its route: `pages/guide/install/page.yml` and `pages/guide/install/install.md`
1015
+ // are both `/guide/install`.
1016
+ function heldRoute(path) {
1017
+ const dir = /\/(page|folder)\.yml$/.test(path) ? path.replace(/\/(page|folder)\.yml$/, '') : path.slice(0, path.lastIndexOf('/'))
1018
+ return `/${dir.replace(/^pages\/?/, '')}`
1019
+ }
1020
+
1021
+ /**
1022
+ * ⭐ A PAGE A PULL HELD WHOSE FILES CHANGED SINCE STOPS A PUSH: the app's version and the file's would
1023
+ * both claim it, and the push cannot keep the one without dropping the other (`heldChanged`,
1024
+ * `@uniweb/build`'s `held-units.js`). Shared by push and publish. Returns whether it stopped.
1025
+ */
1026
+ export function refuseChangedHeld(pkg, { error, note }) {
1027
+ const routes = [...new Set((pkg?.heldChanged || []).map(heldRoute))]
1028
+ if (!routes.length) return false
1029
+ error(`${routes.length} page(s) changed in the app in a way their files cannot say, and changed in their files since the pull:`)
1030
+ for (const route of routes) note(` ${route}`)
1031
+ note('Undo one of the two: the app\'s change, then pull, or the file\'s. `--force` sends the files\' version over the app\'s.')
1032
+ return true
1033
+ }
1034
+
1035
+ /** The pages a push left out because a pull held them, said — they stay as the app has them. */
1036
+ export function noteHeldLeftOut(pkg, { note }) {
1037
+ const routes = [...new Set((pkg?.heldLeftOut || []).map(heldRoute))]
1038
+ if (!routes.length) return
1039
+ note(`Left out: ${routes.length} page(s) a pull held, which stay as the app has them — their files cannot say its change (\`uniweb pull\` names why):`)
1040
+ for (const route of routes) note(` ${route}`)
1041
+ }
1042
+
979
1043
  export function mergeItemBaseVersions(siteDir, backend, versions) {
980
1044
  if (!versions || !Object.keys(versions).length) return
981
1045
  // ⛔ The read names the backend. Without it the read keyed nothing, came back `{}`,
@@ -2114,7 +2178,7 @@ export async function probeUnpushed(siteDir, { backend = null, sendAll = false }
2114
2178
  */
2115
2179
  async function comparisonEmit(
2116
2180
  siteDir,
2117
- { backend = null, priorHashes = {}, sendAll = false, declarations = null, fields = null } = {}
2181
+ { backend = null, priorHashes = {}, sendAll = false, declarations = null, fields = null, heldUnits = undefined, extra = {} } = {}
2118
2182
  ) {
2119
2183
  const applied = readAppliedInjections(siteDir, backend)
2120
2184
  // ⛔ Per backend: an asset id is minted by one and means nothing to another, so a
@@ -2138,7 +2202,11 @@ async function comparisonEmit(
2138
2202
  // the last push banked.
2139
2203
  ...(fields || {}),
2140
2204
  ...(Object.keys(queryUuids).length ? { queryUuids } : {}),
2141
- ...(Object.keys(assetIds).length ? { assetIds } : {})
2205
+ ...(Object.keys(assetIds).length ? { assetIds } : {}),
2206
+ // What a pull held stays out of the comparison as it stays out of a push (`readHeldUnits`), so a
2207
+ // hash banked over it compares with the push's.
2208
+ heldUnits: heldUnits === undefined ? readHeldUnits(siteDir, backend) : heldUnits,
2209
+ ...extra
2142
2210
  // ⛔ No `org`: a site's `@/x` refs resolve into its FOUNDATION's scope, which the
2143
2211
  // emit reads itself — the same read a push makes, so the hashes compare alike.
2144
2212
  })
@@ -98,6 +98,9 @@ import {
98
98
  readSyncCache,
99
99
  readBaseVersions,
100
100
  readItemBaseVersions,
101
+ readHeldUnits,
102
+ refuseChangedHeld,
103
+ noteHeldLeftOut,
101
104
  ensureItemUuids,
102
105
  readFolderItemUuids,
103
106
  readRecordItemUuids,
@@ -665,7 +668,9 @@ export async function publish(args = []) {
665
668
  // Placement identity for the folder — see writeFolderItemUuids.
666
669
  folderItemUuids: readFolderItemUuids(siteDir, client.origin),
667
670
  ...(foundationDir ? { foundationDir } : {}),
668
- resolveModel
671
+ resolveModel,
672
+ // What a pull held, for a page that changed since to stop the publish before anything goes up.
673
+ ...(args.includes('--force') ? {} : { heldUnits: readHeldUnits(siteDir, client.origin) })
669
674
  })
670
675
  } catch (err) {
671
676
  say.err(`Could not build the sync package: ${err.message}`)
@@ -676,6 +681,8 @@ export async function publish(args = []) {
676
681
  if (refuseUnsendableRecords(probe.refusals, { error: say.err, note: say.dim })) {
677
682
  return { exitCode: 1 }
678
683
  }
684
+ // …and so does a page a pull held whose files changed since (`refuseChangedHeld`).
685
+ if (refuseChangedHeld(probe, { error: say.err, note: say.dim })) return { exitCode: 1 }
679
686
  const schemalessNames = (probe.schemaless || []).map((col) => col.name)
680
687
  // A product decision the author is usually making unknowingly — say it at warn
681
688
  // level, not dim among everything else. See the helper for what the old
@@ -969,7 +976,9 @@ export async function publish(args = []) {
969
976
  ? {}
970
977
  : {
971
978
  baseVersions: readBaseVersions(siteDir, client.origin),
972
- itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
979
+ itemBaseVersions: readItemBaseVersions(siteDir, client.origin),
980
+ // What a pull held is left out while its files still say it — see `uniweb push`.
981
+ heldUnits: readHeldUnits(siteDir, client.origin)
973
982
  }),
974
983
  ...(Object.keys(injectInfo).length ? { injectInfo } : {}),
975
984
  ...(Object.keys(ext.pins).length ? { injectExtensions: ext.pins } : {}),
@@ -996,6 +1005,8 @@ export async function publish(args = []) {
996
1005
  if (refuseUnsendableRecords(pkg.refusals, { error: say.err, note: say.dim })) {
997
1006
  return { exitCode: 1 }
998
1007
  }
1008
+ if (refuseChangedHeld(pkg, { error: say.err, note: say.dim })) return { exitCode: 1 }
1009
+ noteHeldLeftOut(pkg, { note: (m) => say.dim(m) })
999
1010
  // ⭐ `records` is what delivers the records the pages show on the published site — said
1000
1011
  // here, at publish, and never at push: syncing records does not depend on it.
1001
1012
  const notAsked = recordsNotAsked({ siteYml, shown: pkg.recordsShown })
@@ -104,6 +104,9 @@ import {
104
104
  mergeBaseVersions,
105
105
  writeItemBaseVersions,
106
106
  pulledItemVersions,
107
+ readItemUuids,
108
+ writeHeldUnits,
109
+ heldUnitBaseline,
107
110
  writeUnitBases,
108
111
  commitWriteBacks,
109
112
  reportWriteBacks,
@@ -113,7 +116,7 @@ import {
113
116
  readItemBaseVersions
114
117
  } from '../backend/site-sync.js'
115
118
  import { resolveWorkspace } from '../backend/workspace.js'
116
- import { siteRoots, sentRoots, laneRoots, writableMounts, refusedMountLines } from '../utils/site-roots.js'
119
+ import { siteRoots, sentRoots, laneRoots, writableMounts, refusedMountLines, heldMountLines } from '../utils/site-roots.js'
117
120
  import {
118
121
  repoOf,
119
122
  mergeInProgress,
@@ -508,17 +511,30 @@ function filesUnder(siteDir, roots) {
508
511
  return out
509
512
  }
510
513
 
511
- // ⭐ A VERSION IS BANKED FOR WHAT THE FILES TOOK, OR CHOSE NOT TO TAKE. A page held because its file
512
- // cannot say the app's change keeps the version this copy last agreed on, so the per-item gate keeps the
513
- // backend's copy while the file is unchanged and refuses a push that changed it. One this copy never agreed
514
- // on keeps the backend's: there is no agreement to hold. A mount's page takes the backend's, so the next
515
- // push puts the folder's back.
516
- export function agreedVersions(pulled, heldPages, prior) {
514
+ // ⭐ A VERSION IS BANKED FOR WHAT THE FILES TOOK, OR CHOSE NOT TO TAKE.
515
+ // - A page held because its files cannot say the app's change (`leftOut`) gets NO version: a push leaves
516
+ // it out while its files still say what they said (`heldUnitBaseline`), and the backend keeps an item a
517
+ // push holds no version for. ⛔ Until 2026-11-04 it kept the version this copy last agreed on, so a copy
518
+ // that never agreed on one — a fresh clone, CI — banked the backend's, and its next push sent the file
519
+ // over the app's edit; and a section the app added there was banked, so that push deleted it.
520
+ // - A page of a mount the pull cannot merge into, or of a route the files give two pages for
521
+ // (`heldPages`), keeps the version this copy last agreed on, so the per-item gate keeps the backend's
522
+ // copy while the file is unchanged and refuses a push that changed it. One this copy never agreed on
523
+ // keeps the backend's: there is no agreement to hold.
524
+ export function agreedVersions(pulled, heldPages, prior, leftOut = []) {
517
525
  const out = { ...pulled }
518
526
  for (const { uuids } of heldPages || []) for (const u of uuids || []) if (prior?.[u]) out[u] = prior[u]
527
+ for (const { uuids } of leftOut || []) for (const u of uuids || []) delete out[u]
519
528
  return out
520
529
  }
521
530
 
531
+ // The pages a push leaves out while their files say what they said at the pull: every page the pull held
532
+ // for what its files cannot say. Not a route the files give two pages for, which no push can leave out
533
+ // of the two the files send.
534
+ export function leftOutOfPush(heldPages) {
535
+ return (heldPages || []).filter(({ what }) => !(what || []).includes('two pages on one route'))
536
+ }
537
+
522
538
  // The mounted pages the backend holds at another version than this copy last agreed on, by route.
523
539
  export function mountedPagesMoved(mountedPages, pulled, prior) {
524
540
  return (mountedPages || [])
@@ -781,13 +797,13 @@ export async function pull(args = [], deps = {}) {
781
797
  const blocked = await checkWorkingTree(siteDir, args)
782
798
  if (blocked) return blocked
783
799
  }
784
- // ⭐ A MOUNT IS WRITTEN WHERE THE SITE SAYS `writable: true` AND THIS COPY CAN MERGE IT
785
- // (`writableMounts`). One it cannot stops the pull before anything is asked or taken: left read-only,
786
- // the app's edits to it would be undone by the next push, which is what the declaration asks to avoid.
800
+ // ⭐ A MOUNT IS WRITTEN WHEREVER THIS COPY CAN MERGE IT, and its app edits held where it cannot
801
+ // (`writableMounts`) — never undone. One written in the retired object form stops the pull before
802
+ // anything is asked or taken, as it stops the build.
787
803
  const mounts = writableMounts(siteDir)
788
804
  if (mounts.refused.length) {
789
805
  if (probe) return { exitCode: 1, probe: null }
790
- error(`${mounts.refused.length === 1 ? 'A mount' : `${mounts.refused.length} mounts`} marked writable cannot be written by a pull:`)
806
+ error(`${mounts.refused.length === 1 ? 'A mount is' : `${mounts.refused.length} mounts are`} written in a form a pull no longer reads:`)
791
807
  for (const m of mounts.refused) for (const line of refusedMountLines(m)) note(line)
792
808
  return { exitCode: 1 }
793
809
  }
@@ -974,6 +990,8 @@ export async function pull(args = [], deps = {}) {
974
990
  // and a mount's, which the folder wins.
975
991
  let heldPages = []
976
992
  let mountedPages = []
993
+ // A mount's own route the app renamed or removed, which `site.yml`'s `paths:` now says.
994
+ let mountRoutes = []
977
995
  let mountedMoved = []
978
996
  // Set when the folder lane carried records this pull did not place — see the ⛔
979
997
  // where it is set.
@@ -988,8 +1006,11 @@ export async function pull(args = [], deps = {}) {
988
1006
  // only while the sync point it was banked with is.
989
1007
  const cache = readPullCache(siteDir)
990
1008
  const held = repo ? readSyncPoint(siteDir, client.origin) : null
991
- // The versions this copy agreed on before this pull — what a held page keeps (`agreedVersions`).
1009
+ // The versions this copy agreed on before this pull — what a mount's held page keeps (`agreedVersions`).
992
1010
  const priorVersions = readItemBaseVersions(siteDir, client.origin)
1011
+ // …and the identity it held, by the paths its files keep each item at: where a held page is found in
1012
+ // them though the app moved it (`heldUnitBaseline`). Read before the pull replaces it.
1013
+ const priorItems = readItemUuids(siteDir, client.origin)
993
1014
  const cacheHolds = etagsHold(siteDir, client.origin, repo)
994
1015
  let etagContent = cache.content
995
1016
  let etagFolder = cache.folder
@@ -1267,8 +1288,27 @@ export async function pull(args = [], deps = {}) {
1267
1288
  leftAlone += report.leftAlone?.length || 0
1268
1289
  heldPages = report.held || []
1269
1290
  mountedPages = report.mountedPages || []
1291
+ mountRoutes = report.mountRoutes || []
1270
1292
  mountedMoved = mountedPagesMoved(mountedPages, pulledVersions, priorVersions)
1271
1293
  outsideLanguages = report.outsideLanguages || []
1294
+ // ⭐ WHAT IT HELD, AS THE FILES KEEP IT — where each held page is in the files it wrote into, the
1295
+ // stand-in in a repository, and what they say there — for a push to leave out while they still
1296
+ // say it (`readHeldUnits`). Replaced by each pull that takes the site's content. In the stand-in's
1297
+ // cache, which comes back to the site with the others.
1298
+ try {
1299
+ writeHeldUnits(projDir, client.origin, await heldUnitBaseline(projDir, client.origin, {
1300
+ held: leftOutOfPush(heldPages).flatMap((h) => h.uuids || []),
1301
+ // Where this copy kept each item before the pull, over where the backend keeps it — the same
1302
+ // place for a page the app did not move, and the one a `sync.json` without items still has.
1303
+ itemUuids: { ...collectUnitUuids(siteDoc), ...priorItems },
1304
+ ...(declarations.size ? { declarations } : {}),
1305
+ fields
1306
+ }))
1307
+ } catch (err) {
1308
+ // The files did not emit: neither will a push from them, which this pull leaves to say why.
1309
+ writeHeldUnits(projDir, client.origin, {})
1310
+ note(`! could not record the pages this pull held: ${err.message}`)
1311
+ }
1272
1312
  }
1273
1313
 
1274
1314
  if (folderTaken) {
@@ -1600,7 +1640,12 @@ export async function pull(args = [], deps = {}) {
1600
1640
  // again, asking the backend to delete it. The folder lane's are not kept — that lane
1601
1641
  // is gated by its entity version. (Both were merged into one map until 2026-10-07.)
1602
1642
  if (pulledVersions && content && !content.notModified && !content.refused) {
1603
- writeItemBaseVersions(siteDir, client.origin, agreedVersions(pulledVersions, heldPages, priorVersions))
1643
+ // ⭐ Held where the files cannot take the app's change: a page they cannot say, and each page of a
1644
+ // mount the pull could not write. ⛔ Until 2026-11-04 a mount's took the backend's version, and the
1645
+ // next push put the folder's back over the app's edit.
1646
+ const leftOut = leftOutOfPush(heldPages)
1647
+ const keptAt = [...heldPages.filter((h) => !leftOut.includes(h)), ...mountedPages]
1648
+ writeItemBaseVersions(siteDir, client.origin, agreedVersions(pulledVersions, keptAt, priorVersions, leftOut))
1604
1649
  }
1605
1650
  // Persist the ETags so the next pull is conditional (304 when unchanged). The
1606
1651
  // folder's is DROPPED when records were not placed, so the next pull fetches
@@ -1619,22 +1664,30 @@ export async function pull(args = [], deps = {}) {
1619
1664
  (deleted ? `, ${deleted} deleted` : '')
1620
1665
  if (notTaken || recordsNotPlaced) info(summary)
1621
1666
  else success(summary)
1667
+ // ⭐ Said, since it edits `site.yml`: the route is the mount's key there, and its local folder.
1668
+ if (!notTaken) {
1669
+ for (const { from, to } of mountRoutes) {
1670
+ note(
1671
+ to
1672
+ ? `The app renamed /${from}, a mounted route, to /${to}: \`paths:\` in site.yml says pages/${to} now, and its local folder moved with it. The mounted folder is as it was.`
1673
+ : `The app removed /${from}, a mounted route: it is gone from \`paths:\` in site.yml, with its local folder. The mounted folder is as it was.`
1674
+ )
1675
+ }
1676
+ }
1622
1677
  if (leftAlone) {
1623
1678
  note(
1624
- `Left as written: ${leftAlone} page(s) a pull does not write — a mounted folder's, a \`.md\` page given what its file cannot say, or two pages on one route. ` +
1625
- 'An edit made to one in the app does not come back here, and the next push sends the file.'
1679
+ `Left as written: ${leftAlone} page(s) a pull cannot write — in a mounted folder it cannot merge into, what a folder of single-section pages cannot hold, or two pages on one route. ` +
1680
+ "An edit made to one in the app is held: kept on the backend, not undone by a push while the page's file is unchanged, and a push that changed it stops."
1626
1681
  )
1627
1682
  if (mountedMoved.length) {
1628
- note(
1629
- `The backend holds a newer version of ${mountedMoved.length} mounted page(s), changed in the app: the next push puts the folder's back. ` +
1630
- 'To keep a change, make it in the mounted folder, or mark its mount `writable: true` in site.yml.'
1631
- )
1683
+ note(`Held: ${mountedMoved.length} mounted page(s) changed in the app, which their folder cannot take:`)
1632
1684
  for (const route of mountedMoved) note(` /${route}`)
1685
+ for (const m of mounts.held) for (const line of heldMountLines(m)) note(line)
1633
1686
  }
1634
1687
  if (heldPages.length) {
1635
1688
  note(
1636
1689
  `Held: ${heldPages.length} page(s) whose files cannot say what the app made of them. The site keeps the app's version and the files keep theirs; ` +
1637
- 'a push leaves it, and one that changes such a page is refused. Undo it in the app, or give the page a folder of its own with a page.yml, and pull again.'
1690
+ 'a push leaves it, and one that changes such a page is refused. Undo it in the app, and pull again.'
1638
1691
  )
1639
1692
  for (const { route, what } of heldPages) note(` /${route}: ${what.join(', ')}`)
1640
1693
  }
@@ -88,6 +88,9 @@ import {
88
88
  readSyncCache,
89
89
  readBaseVersions,
90
90
  readItemBaseVersions,
91
+ readHeldUnits,
92
+ refuseChangedHeld,
93
+ noteHeldLeftOut,
91
94
  readItemUuids,
92
95
  readFolderItemUuids,
93
96
  readQueryUuids,
@@ -470,6 +473,7 @@ export async function push(args = [], deps = {}) {
470
473
  if (!output && !dryRun) {
471
474
  let mediaRefs = []
472
475
  let refusals = []
476
+ let held = null
473
477
  try {
474
478
  const probe = await emitSyncPackages(siteDir, {
475
479
  backend: client.origin,
@@ -477,11 +481,14 @@ export async function push(args = [], deps = {}) {
477
481
  // Placement identity for the folder — see writeFolderItemUuids.
478
482
  folderItemUuids: readFolderItemUuids(siteDir, client.origin),
479
483
  ...(foundationDir ? { foundationDir } : {}),
480
- resolveModel: makeModelResolver({ client, offline: false, siteDir })
484
+ resolveModel: makeModelResolver({ client, offline: false, siteDir }),
485
+ // What a pull held, for a page that changed since to stop the push before anything goes up.
486
+ ...(force ? {} : { heldUnits: readHeldUnits(siteDir, client.origin) })
481
487
  })
482
488
  // Site-root media, and each file record's file (`@uniweb/file` — `{ ref, path, contentType }`).
483
489
  mediaRefs = [...(probe.localAssets || []), ...(probe.localFiles || [])]
484
490
  refusals = probe.refusals || []
491
+ held = probe
485
492
  } catch (err) {
486
493
  error(`Could not scan the site for local media: ${err.message}`)
487
494
  return { exitCode: 2 }
@@ -489,6 +496,8 @@ export async function push(args = [], deps = {}) {
489
496
  // A record the backend would refuse stops the push HERE — before the site is
490
497
  // created or a byte uploaded, not merely before the send (`refuseUnsendableRecords`).
491
498
  if (refuseUnsendableRecords(refusals, { error, note })) return { exitCode: 1 }
499
+ // …and so does a page a pull held whose files changed since (`refuseChangedHeld`).
500
+ if (refuseChangedHeld(held, { error, note })) return { exitCode: 1 }
492
501
  if (mediaRefs.length) {
493
502
  // The site has to exist before its bytes do — an upload with no owning
494
503
  // entity is charged and cannot be freed, because freeing means deleting the
@@ -620,7 +629,10 @@ export async function push(args = [], deps = {}) {
620
629
  ? {}
621
630
  : {
622
631
  baseVersions: readBaseVersions(siteDir, client.origin),
623
- itemBaseVersions: readItemBaseVersions(siteDir, client.origin)
632
+ itemBaseVersions: readItemBaseVersions(siteDir, client.origin),
633
+ // ⭐ What a pull held is left out while its files still say what they said, so the backend
634
+ // keeps the app's version (`readHeldUnits`). `--force` sends it with everything else.
635
+ heldUnits: readHeldUnits(siteDir, client.origin)
624
636
  }),
625
637
  ...(assetRewrite ? { assetRewrite } : {}),
626
638
  ...(assetIds ? { assetIds } : {})
@@ -652,6 +664,8 @@ export async function push(args = [], deps = {}) {
652
664
  // The same stop for the paths the probe above does not run on — `-o` and
653
665
  // `--dry-run` say what a push would do, and a push would stop here.
654
666
  if (refuseUnsendableRecords(pkg.refusals, { error, note })) return { exitCode: 1 }
667
+ if (refuseChangedHeld(pkg, { error, note })) return { exitCode: 1 }
668
+ noteHeldLeftOut(pkg, { note })
655
669
  // Warn level, not dim: this is the author choosing entities vs static files.
656
670
  reportSchemalessQueries(pkg.schemaless, { warn, dim: note })
657
671
 
@@ -80,7 +80,7 @@ import {
80
80
  siteTreeIn,
81
81
  unmergedPaths
82
82
  } from '../utils/sync-point.js'
83
- import { submoduleMountRoots, writableMounts, refusedMountLines } from '../utils/site-roots.js'
83
+ import { submoduleMountRoots, writableMounts, refusedMountLines, heldMountLines } from '../utils/site-roots.js'
84
84
  import { aheadBehind, remoteMoved, upstreamOf } from '../utils/git.js'
85
85
  import { mountedRepositories, askRemote, standing, mountName, short } from '../utils/mounted-repositories.js'
86
86
  import { getLatestVersion, isBehind } from '../utils/update-check.js'
@@ -1281,46 +1281,34 @@ async function projectChecks(siteDir, siteYml) {
1281
1281
  }
1282
1282
  })
1283
1283
 
1284
- // ⭐ Pages from outside the site's folder (`paths:` mounts, by the build's own rule): a pull writes
1285
- // one the site marks `writable: true` where this copy can merge it (`writableMounts`), and no other
1286
- // (`uwx/page-files.js`); one in its own repository is edited there.
1284
+ // ⭐ Pages from outside the site's folder (`paths:` mounts, by the build's own rule): a pull writes the
1285
+ // app's edits into each one this copy can merge, and holds them for any other (`writableMounts`,
1286
+ // `uwx/page-files.js`); one in its own repository is edited there.
1287
1287
  const { mountEntriesOf } = await import('@uniweb/build/site')
1288
1288
  const siteRepo = repoOf(siteDir)?.top ?? null
1289
- const { writable, refused } = writableMounts(siteDir)
1289
+ const { writable, held, refused } = writableMounts(siteDir)
1290
1290
  const mounts = mountEntriesOf(siteYml?.paths).map(([segment, dir]) => {
1291
1291
  const abs = resolve(siteDir, String(dir))
1292
1292
  const exists = existsSync(abs)
1293
1293
  const top = exists ? repoOf(abs)?.top ?? null : null
1294
1294
  const repository = !exists ? null : !top ? 'none' : top === siteRepo ? 'same' : 'other'
1295
- return { segment, dir: String(dir), exists, repository, writable: writable.includes(segment) }
1295
+ return { segment, dir: String(dir), exists, repository, writable: writable.includes(segment), held: held.some((h) => h.segment === segment) }
1296
1296
  })
1297
1297
  const mountLine = (m) =>
1298
1298
  !m.exists
1299
1299
  ? `pages/${m.segment} names ${m.dir}, which does not exist.`
1300
- : m.repository === 'other'
1301
- ? m.writable
1300
+ : m.held
1301
+ ? `pages/${m.segment} comes from ${m.dir}, which a pull cannot merge into — it holds the app's edits to those pages.`
1302
+ : m.repository === 'other'
1302
1303
  ? `pages/${m.segment} comes from ${m.dir}, its own git repository — a pull writes the app's edits there as commits, which you push there before this repository.`
1303
- : `pages/${m.segment} comes from ${m.dir}, its own git repository — edits there are commits in it.`
1304
- : m.writable
1305
- ? `pages/${m.segment} comes from ${m.dir}, outside the site's folder — a pull writes the app's edits into it.`
1306
- : `pages/${m.segment} comes from ${m.dir}, outside the site's folder.`
1307
- // The pages an app edit to does not come back to: each mount but a writable one, and one a pull refuses.
1308
- const readOnly = mounts.filter((m) => !m.writable && !refused.some((r) => r.segment === m.segment))
1304
+ : `pages/${m.segment} comes from ${m.dir}, outside pages/ — a pull writes the app's edits into it.`
1309
1305
  checks.push(
1310
1306
  mounts.length
1311
1307
  ? {
1312
1308
  id: 'project.mounts',
1313
1309
  state: mounts.some((m) => !m.exists) || refused.length ? 'attention' : 'ok',
1314
- summary: mounts.length === 1 ? mountLine(mounts[0]) : `${count(mounts.length, 'page folder')} come from outside the site's folder.`,
1315
- lines: [
1316
- ...(mounts.length === 1 ? [] : mounts.map(mountLine)),
1317
- ...refused.flatMap(refusedMountLines),
1318
- ...(readOnly.length
1319
- ? [
1320
- `An edit made in the app to ${readOnly.length === mounts.length ? 'those pages' : `the pages of ${readOnly.map((m) => `pages/${m.segment}`).join(', ')}`} does not come back on a pull, and the next push replaces it with the files.`
1321
- ]
1322
- : [])
1323
- ],
1310
+ summary: mounts.length === 1 ? mountLine(mounts[0]) : `${count(mounts.length, 'page folder')} come from outside pages/.`,
1311
+ lines: [...(mounts.length === 1 ? [] : mounts.map(mountLine)), ...refused.flatMap(refusedMountLines), ...held.flatMap(heldMountLines)],
1324
1312
  detail: { mounts }
1325
1313
  }
1326
1314
  : { id: 'project.mounts', state: 'skipped', summary: "All the site's pages are in its own folder.", quiet: true, detail: { mounts: [] } }
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "generatedAt": "2026-11-04T20:40:44.545Z",
3
+ "generatedAt": "2026-11-05T01:35:06.410Z",
4
4
  "packages": {
5
5
  "@uniweb/api": {
6
6
  "version": "1.6.9"
7
7
  },
8
8
  "@uniweb/build": {
9
- "version": "1.15.6"
9
+ "version": "1.16.0"
10
10
  },
11
11
  "@uniweb/content-reader": {
12
12
  "version": "1.5.9"
@@ -54,13 +54,13 @@
54
54
  "version": "1.1.2"
55
55
  },
56
56
  "@uniweb/templates": {
57
- "version": "1.2.5"
57
+ "version": "1.2.6"
58
58
  },
59
59
  "@uniweb/theming": {
60
60
  "version": "1.2.1"
61
61
  },
62
62
  "@uniweb/unipress": {
63
- "version": "1.1.32"
63
+ "version": "1.1.33"
64
64
  }
65
65
  },
66
66
  "templates": {
@@ -50,6 +50,11 @@ function remoteCall(cwd, args, timeoutMs) {
50
50
  }
51
51
 
52
52
  /** true, false, or null when git cannot say (a commit it does not hold). */
53
+ // Does a remote branch hold this commit? Then it came from someone's line of work, not this checkout's.
54
+ function onARemoteBranch(cwd, sha) {
55
+ return Boolean(text(cwd, ['branch', '-r', '--contains', sha]))
56
+ }
57
+
53
58
  function ancestor(cwd, a, b) {
54
59
  try {
55
60
  run(cwd, ['merge-base', '--is-ancestor', a, b])
@@ -326,10 +331,12 @@ function siteName(siteDir) {
326
331
  * uncommitted changes in it, never backwards, and never from a commit the branch does not
327
332
  * contain, which is a pin put somewhere else on purpose.
328
333
  *
329
- * ⭐ `merge`: a mount a pull writes into (`writable: true`) takes its latest as the site takes its own,
330
- * by merging, since the pull's commits there are its own work: a checkout that has them and a branch
331
- * that moved on have each moved, and the merge of the two is its latest. Never a rebase, which would
332
- * replay a pull's commit onto another one while the site's sync point still names it.
334
+ * ⭐ `merge`: a mount a pull writes into (a submodule's, `writableMounts`) takes its latest as the site takes its own,
335
+ * by merging, where its checkout holds work of its own — commits no remote branch has, a pull's among
336
+ * them: that checkout and a branch that moved on have each moved, and the merge of the two is its
337
+ * latest. Never a rebase, which would replay a pull's commit onto another one while the site's sync
338
+ * point still names it. A checkout another remote branch holds is a pin put there on purpose, and is
339
+ * left where it is, merge or not.
333
340
  *
334
341
  * @param {string} siteDir
335
342
  * @param {object} m - from `mountedRepositories`
@@ -376,7 +383,9 @@ export async function takeLatest(siteDir, m, { merge = false } = {}) {
376
383
  }
377
384
  contained = ancestor(cur.top, cur.head, answer.tip)
378
385
  }
379
- if (contained !== true && !merge) return { ...r, left: `${short(cur.head)} is not on ${answer.branch ?? 'its branch'}`, kind: 'off-branch' }
386
+ if (contained !== true && (!merge || onARemoteBranch(cur.top, cur.head))) {
387
+ return { ...r, left: `${short(cur.head)} is not on ${answer.branch ?? 'its branch'}`, kind: 'off-branch' }
388
+ }
380
389
  try {
381
390
  if (contained !== true) {
382
391
  // Each has moved: the checkout's commits — a pull's among them — merged with the branch's.
@@ -19,7 +19,7 @@ import { readFileSync, realpathSync } from 'node:fs'
19
19
  import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path'
20
20
  import yaml from 'js-yaml'
21
21
  import { siteContentRoots } from '@uniweb/build/uwx'
22
- import { mountDeclarationsOf } from '@uniweb/build/site'
22
+ import { mountEntriesOf } from '@uniweb/build/site'
23
23
  import { mountHolding } from './mounted-repositories.js'
24
24
  import { repoOf } from './sync-point.js'
25
25
 
@@ -84,51 +84,58 @@ export function submoduleMountRoots(siteDir) {
84
84
  }
85
85
 
86
86
  /**
87
- * ⭐ THE MOUNTS A PULL MAY WRITE INTO: each one the site declares
88
- * `writable: true` that this copy can merge —
89
- * - a folder the site's own repository holds, whose files are among the site's roots;
90
- * - a folder in a submodule of the site's repository (`submodules`), merged in the submodule's own
91
- * history: git's own pairing of the two, since every commit of the site names the submodule's;
92
- * - for a site in no repository, a folder inside the site's own, which a pull writes as it writes the
93
- * site's files.
94
- * Every other one is refused, with why:
95
- * - `own`: a repository of its own that the site's does not record — a clone beside the site;
96
- * - `none`: no repository holds it, or one ignores it, or it is outside the folder of a site in none;
97
- * - `unchecked`: a submodule that is not checked out.
98
- * The first two have no history that pairs them with the site's, so no copy of the site — a
99
- * teammate's, CI's — could find what it last merged from.
87
+ * ⭐ WHETHER A PULL WRITES THE APP'S EDITS INTO EACH MOUNT — no setting, but where its folder is
88
+ * [Diego, 2026-11-04: "I don't think it should default to false and I don't even know if it should
89
+ * exist. Ignoring incoming changes and then submitting the unmodified version may be wrong"]:
90
+ * - `writable`: a folder the site's own repository holds, whose files are among the site's roots; or a
91
+ * folder in a submodule of it (`submodules`), merged in the submodule's own history, git's own pairing
92
+ * of the two; or, for a site in no repository, a folder inside the site's own. Written like the
93
+ * site's own pages.
94
+ * - `held`: one a pull cannot merge into, with why — `own`, a repository the site's does not record, a
95
+ * clone beside it; `none`, a folder no repository holds, or one ignores, or outside the folder of a
96
+ * site in none; `unchecked`, a submodule not checked out. Its app edits are neither written nor
97
+ * undone: the copy holds the version it last agreed on (`agreedVersions`, `commands/pull.js`).
98
+ * - `refused`: a mount written as an object, the form `writable` was set in, which the build refuses
99
+ * too. The pull stops on it.
100
+ * ⛔ Until 2026-11-04 a mount was written only where the site marked it `writable: true`, and the next
101
+ * push undid every app edit to any other.
100
102
  *
101
103
  * @param {string} siteDir
102
- * @returns {{ writable: string[], refused: Array<{ segment: string, path: string, why: 'own'|'none'|'unchecked' }>,
104
+ * @returns {{ writable: string[], held: Array<{ segment: string, path: string, why: 'own'|'none'|'unchecked' }>,
105
+ * refused: Array<{ segment: string, path: string|null }>,
103
106
  * submodules: Array<{ segment: string, at: string, root: string, repo: object }> }} `submodules`: each
104
- * writable mount in one, with the submodule's path from the site repository's top, the mounted
105
- * folder's path in it, and its `repoOf`
107
+ * mount in one, with the submodule's path from the site repository's top, the mounted folder's path
108
+ * in it, and its `repoOf`
106
109
  */
107
110
  export function writableMounts(siteDir) {
108
111
  const repo = repoOf(siteDir)
109
112
  const writable = []
113
+ const held = []
110
114
  const refused = []
111
115
  const submodules = []
112
- for (const { segment, path, writable: declared } of mountDeclarationsOf(readSiteYml(siteDir).paths)) {
113
- if (!declared || typeof path !== 'string' || !path) continue
114
- const abs = resolve(siteDir, path)
116
+ for (const [segment, folder] of mountEntriesOf(readSiteYml(siteDir).paths)) {
117
+ if (typeof folder !== 'string' || !folder) {
118
+ refused.push({ segment, path: typeof folder?.path === 'string' ? folder.path : null })
119
+ continue
120
+ }
121
+ const abs = resolve(siteDir, folder)
115
122
  let why = null
116
123
  if (repo) {
117
- const held = mountHolding(siteDir, abs)
118
- if (held.kind === 'submodule') {
119
- const top = join(repo.top, held.submodule.path)
124
+ const holding = mountHolding(siteDir, abs)
125
+ if (holding.kind === 'submodule') {
126
+ const top = join(repo.top, holding.submodule.path)
120
127
  const sub = repoOf(top)
121
128
  if (!sub?.head) why = 'unchecked'
122
- else submodules.push({ segment, at: held.submodule.path, root: relative(realOf(top), realOf(abs)).split(sep).join('/') || '.', repo: sub })
123
- } else if (held.kind !== 'site') why = held.kind
129
+ else submodules.push({ segment, at: holding.submodule.path, root: relative(realOf(top), realOf(abs)).split(sep).join('/') || '.', repo: sub })
130
+ } else if (holding.kind !== 'site') why = holding.kind
124
131
  } else {
125
132
  const rel = relative(siteDir, abs)
126
133
  if (!rel || isAbsolute(rel) || rel === '..' || rel.startsWith(`..${posix.sep}`) || rel.startsWith('..\\')) why = 'none'
127
134
  }
128
- if (why) refused.push({ segment, path, why })
135
+ if (why) held.push({ segment, path: folder, why })
129
136
  else writable.push(segment)
130
137
  }
131
- return { writable, refused, submodules }
138
+ return { writable, held, refused, submodules }
132
139
  }
133
140
 
134
141
  const realOf = (p) => {
@@ -139,19 +146,30 @@ const realOf = (p) => {
139
146
  }
140
147
  }
141
148
 
142
- /** What to tell a person about a mount a pull may not write, and what settles it. */
143
- export function refusedMountLines({ segment, path, why }) {
144
- if (why === 'unchecked') {
145
- return [
146
- `pages/${segment} is mounted from ${path} with \`writable: true\`, but its submodule is not checked out, so a pull has nothing to merge into.`,
147
- ' Check it out (`git submodule update --init`), or run `npx uniweb refresh`, then pull.'
148
- ]
149
- }
150
- const what = why === 'own' ? `a repository of its own, which the site's repository does not record` : `a folder no history of the site's holds`
149
+ /** What stops a pull on a mount written as an object, and what replaced it. */
150
+ export function refusedMountLines({ segment, path }) {
151
+ return [
152
+ `pages/${segment} in site.yml's paths: is an object. A mount is its folder: \`pages/${segment}: ${path ?? '../docs'}\`.`,
153
+ " `writable` is retired: a pull writes the app's edits into a mounted folder wherever it can merge them, a folder of the site's repository or of a submodule, and holds them where it cannot."
154
+ ]
155
+ }
156
+
157
+ /** What to tell a person about a mount whose app edits a pull holds, and what lets a pull write them. */
158
+ export function heldMountLines({ segment, path, why }) {
159
+ const what =
160
+ why === 'unchecked'
161
+ ? 'a submodule that is not checked out'
162
+ : why === 'own'
163
+ ? "a repository of its own, which the site's repository does not record"
164
+ : "a folder no history of the site's holds"
165
+ const settle =
166
+ why === 'unchecked'
167
+ ? 'Check it out (`git submodule update --init`), then pull to take them.'
168
+ : why === 'own'
169
+ ? "To have a pull write them, make it a submodule of the site's repository."
170
+ : "To have a pull write them, make it part of the site's repository, or a submodule of it."
151
171
  return [
152
- `pages/${segment} is mounted from ${path} with \`writable: true\`, but it is ${what}, so a pull cannot merge into it.`,
153
- why === 'own'
154
- ? " Make it a submodule of the site's repository, or remove `writable: true` to keep it read-only."
155
- : " Make it part of the site's repository (or a folder of the site, outside one), or remove `writable: true` to keep it read-only."
172
+ `pages/${segment} comes from ${path}, ${what}, so a pull cannot merge into it: the app's edits to its pages are held — kept on the backend, not written here, and not undone by a push while their files are unchanged.`,
173
+ ` ${settle}`
156
174
  ]
157
175
  }