@uniweb/build 1.5.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -56,15 +56,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
-    "@uniweb/content-reader": "~1.5.2",
-    "@uniweb/projections": "~1.1.4",
-    "@uniweb/semantic-parser": "~1.12.0",
+    "@uniweb/semantic-parser": "~1.12.2",
+    "@uniweb/content-reader": "~1.5.4",
+    "@uniweb/theming": "~1.2.0",
     "@uniweb/content-writer": "~1.3.0",
-    "@uniweb/schemas": "~1.5.0",
-    "@uniweb/theming": "~1.2.0"
+    "@uniweb/projections": "~1.1.4",
+    "@uniweb/schemas": "~1.5.0"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "~1.1.8"
+    "@uniweb/runtime": "~1.1.11"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -73,8 +73,8 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/runtime": "~1.1.8",
-    "@uniweb/core": "~1.3.0"
+    "@uniweb/core": "~1.3.1",
+    "@uniweb/runtime": "~1.1.11"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/foundation/prose-styles.js

@@ -1,9 +1,9 @@
 /**
  * Prose without its stylesheet — the one foundation mistake that renders fine and looks wrong.
  *
- * kit's `<Prose>` (and `<Article>`, which is `<Prose>` in an `<article>`) draws content inside
- * Tailwind Typography's `prose` classes. Those classes style nothing unless the foundation's
- * stylesheet brings the plugin, which is one line:
+ * kit's `<Prose>` (and `<Article>`, which is `<Prose>` in an `<article>`) draws content inside a
+ * `prose` container. The class styles nothing unless the foundation's stylesheet imports kit's
+ * prose layer, which is one line:
  *
  *     @import "@uniweb/kit/prose-tokens.css";
  *
@@ -20,7 +20,7 @@
 /** kit's Prose module, wherever kit resolves from — the workspace or node_modules. */
 const PROSE_MODULE = /[\\/]kit[\\/]src[\\/]styled[\\/]Prose[\\/]index\.jsx$/
 
-/** A rule of the typography plugin's, which every one of its selectors starts with. */
+/** A rule of kit's prose layer, which every one of its selectors starts with. ⛔ Tailwind Typography's until 2026-10-19. */
 const PROSE_RULE = /\.prose\b/
 
 /**

package/src/hosts/github-pages.js

@@ -35,7 +35,7 @@
  *     the branch history stays intact and revertible.
  *
  * UNIWEB_BASE is decided at workflow scaffold time based on the deploy
- * target (per gotcha #15 for the base-path flow):
+ * target, and becomes the site's base path:
  *
  *   - With `domain`: bakes `UNIWEB_BASE: /` and emits a CNAME file under
  *     `<sitePath>/public/`. GitHub Pages serves the custom domain at

package/src/site/build-site-data.js

@@ -2,19 +2,24 @@
  * Site data builder — runs the data pipeline without vite.
  *
  * `siteContentPlugin` (`./plugin.js`) emits site data inside vite's
- * `generateBundle` hook because today's `uniweb build` always goes through
- * vite (to produce a static-host JS bundle). For `uniweb build --link`,
- * the JS bundle is wasted CPU — the deployed Uniweb-hosted site is rendered
- * by the worker using its own runtime + the foundation served from the
- * registry; nothing from the site's vite output reaches the browser.
+ * `generateBundle` hook, on the bundle lane, where vite builds a JS bundle for
+ * a static host. `uniweb build --link`, which `uniweb publish` runs, needs no
+ * bundle: what `publish` sends a backend carries no JS. The content goes over
+ * the sync wire, read from the site's source files (`../uwx/`), and the site
+ * names its foundation by registered version.
+ *
+ * ⛔ *Until 2026-10-19 this said a Uniweb-hosted site "is rendered by the worker
+ * using its own runtime" — a statement about a host, which framework cannot
+ * make (the note under `site-content.json` below).*
  *
  * This function is the shared data-emission core used by the link-mode
  * pipeline. The vite plugin keeps its own emission for the bundle-mode
  * path (where the static-host extras — sitemap, robots, search-index,
  * `_pages/*` for split content — are actually consumed). Both paths use
  * the same underlying building blocks (`collectSiteContent`,
- * `processQueries`, `processAssets`, etc.), so behavior stays
- * consistent without forcing one path through the other's lifecycle.
+ * `processQueries`, etc.), so behavior stays consistent without forcing
+ * one path through the other's lifecycle. Media processing — WebP copies,
+ * video posters, PDF thumbnails — is the bundle path's alone (below).
  */
 
 import { writeFile, readFile, mkdir, cp } from 'node:fs/promises'
@@ -25,8 +30,6 @@ import { resolveDefaultLocale, DATA_DIR } from '@uniweb/core'
 import { collectSiteContent } from './content-collector.js'
 import { processQueries, writeQueryFiles } from './query-processor.js'
 import { resolveRecordsDir } from './entity-pool.js'
-import { processAssets, rewriteSiteContentPaths } from './asset-processor.js'
-import { processAdvancedAssets } from './advanced-processors.js'
 import {
   renderSiteIndex,
   renderPageMarkdown,
@@ -39,11 +42,17 @@ import {
 } from '@uniweb/projections'
 
 /**
- * Build the site data outputs needed by `uniweb deploy` (link-mode).
+ * Build the site data for `uniweb build --link`, which `uniweb publish` runs.
+ * `publish` reads two things back from `distDir`: the files of the queries that
+ * have no data schema, which it uploads, and the languages to make live.
  *
  * Emits to `distDir`:
  *   - `site-content.json` — full content tree, sections always inlined.
- *     The deploy CLI reads this and ships it as `payload.locales[default]`.
+ *     `publish` reads the languages to make live from it and from the
+ *     `<locale>/site-content.json` files beside it (`languagesFromContent`);
+ *     the content itself goes over the sync wire, built from source.
+ *     ⛔ *Until 2026-10-19 this said the deploy CLI shipped this file as
+ *     `payload.locales[default]`.*
  *
  *     ⛔ Ship FULL sections; never strip them per the split-content rule.
  *     A stripped manifest is what prerender emits for static-host bundles,
@@ -54,27 +63,30 @@ import {
  *     does with the payload. Removed 2026-08-18: the description was
  *     accurate about one deployment and false about another, and both were
  *     live at once — so naming "the worker" was wrong even though the
- *     sentence was true somewhere. Framework has no host client and no host
- *     knowledge (root CLAUDE.md, THE LANE CHAIN); we cannot tell consumers
- *     apart and must not write as though we can.
+ *     sentence was true somewhere. The framework has no host client and no
+ *     knowledge of hosts; we cannot tell consumers apart and must not write
+ *     as though we can.
  *
  *     ⇒ The rule stands on its own: we do not know which consumers
  *     re-derive, so we always ship enough for the ones that do.
- *   - `data/<collection>.json` (+ each record's own file,
- *     `data/<collection>/<$name>.json`) — same shape `processQueries` produces today.
+ *   - `data/<query>.json` (+ each record's own file, `data/<query>/<$name>.json`) —
+ *     same shape `processQueries` produces today. `publish` uploads the files of
+ *     the queries that have no data schema (`collectSchemalessData`).
  *   - `records/<path under the records directory>` — the records' co-located assets, where
  *     the compiled records point.
- *   - `assets/<media>` — processed images / video posters / PDF
- *     thumbnails. Filtered by the deploy CLI to MEDIA only at upload time.
  *
  * Does NOT emit:
+ *   - `assets/<media>` — no media is processed here, and a media ref in
+ *     `site-content.json` stays the site's own path. `publish` uploads a
+ *     site's media from the site's own files (the CLI's `uploadSiteMedia`), so
+ *     processed copies would be built for nothing. ⛔ *Until 2026-10-19 this
+ *     lane made WebP copies, video posters and PDF thumbnails into
+ *     `dist/assets/` on every publish, and rewrote the refs to them.*
  *   - HTML, JS, CSS, source maps, `_importmap/*` — static-host bundle
  *     artifacts; a host on this lane renders pages itself.
  *   - `_pages/<route>.json` — only meaningful for static-host bundles,
  *     where they are served as files.
- *   - `sitemap.xml`, `robots.txt` — static-host bundle territory. Note these
- *     are simply absent from Uniweb-hosted sites today: nothing in platform
- *     generates them, at publish time or at request time.
+ *   - `sitemap.xml`, `robots.txt` — static-host bundle territory.
  *   - ANY search index — neither the single-file `search-index.json` nor the
  *     split `_search/{locale}/*.json`. This lane emitted both until
  *     2026-08-01 and emits neither now; see step 5 for why. A host that
@@ -91,14 +103,7 @@ import {
  * @param {string} params.distDir - Absolute path to the dist output directory.
  * @param {string} [params.foundationPath] - Absolute path to the foundation
  *   directory, when one exists locally. Used by `collectSiteContent` to
- *   resolve theme variable defaults from `foundation.js::theme.vars`.
- * @param {Object} [params.assets] - Asset processing options.
- * @param {boolean} [params.assets.process=true]
- * @param {boolean} [params.assets.convertToWebp=true]
- * @param {number} [params.assets.quality=80]
- * @param {string} [params.assets.outputDir='assets']
- * @param {boolean} [params.assets.videoPosters=true]
- * @param {boolean} [params.assets.pdfThumbnails=true]
+ *   resolve the defaults of the theme variables it declares (its `main.js` `vars`).
  * @param {string} [params.basePath='/'] - Base path prefix for collection URLs.
  * @returns {Promise<{ siteContent: Object, distDir: string }>}
  */
@@ -106,7 +111,6 @@ export async function buildSiteData({
   siteRoot,
   distDir,
   foundationPath,
-  assets = {},
   basePath = '/',
 }) {
   if (!siteRoot) throw new Error('buildSiteData: siteRoot is required')
@@ -114,21 +118,13 @@ export async function buildSiteData({
 
   const resolvedSiteRoot = resolve(siteRoot)
   const resolvedDistDir = resolve(distDir)
-  const assetsOpts = {
-    process: assets.process !== false,
-    convertToWebp: assets.convertToWebp !== false,
-    quality: assets.quality || 80,
-    outputDir: assets.outputDir || 'assets',
-    videoPosters: assets.videoPosters !== false,
-    pdfThumbnails: assets.pdfThumbnails !== false,
-  }
 
   await mkdir(resolvedDistDir, { recursive: true })
 
   // 1. Collect content (pages, sections, theme, config, assets manifest).
   //    No vite needed — collectSiteContent is a plain async function.
-  //    dropUnpublished: link mode is always a published deploy — prune hidden
-  //    pages + their subtree so drafts never reach the served site.
+  //    dropUnpublished: link mode is the build `publish` runs, so it reads
+  //    the site as published — hidden pages and their subtree pruned.
   let siteContent = await collectSiteContent(resolvedSiteRoot, { foundationPath, dropUnpublished: true, base: basePath, strict: true })
 
   // 2. Compile content collections (file-based markdown/yaml/json).
@@ -166,69 +162,27 @@ export async function buildSiteData({
     }
   }
 
-  // 3. Process media assets — images, optional video posters and PDF
-  //    thumbnails — and rewrite the in-memory content tree so its image/
-  //    video/document references point at the processed paths.
-  let finalContent = siteContent
-  if (assetsOpts.process && siteContent?.assets) {
-    const assetCount = Object.keys(siteContent.assets).length
-    if (assetCount > 0) {
-      const { pathMapping, files } = await processAssets(siteContent.assets, {
-        outputDir: resolvedDistDir,
-        assetsSubdir: assetsOpts.outputDir,
-        convertToWebp: assetsOpts.convertToWebp,
-        quality: assetsOpts.quality,
-        basePath,
-      })
-
-      const advancedEnabled = assetsOpts.videoPosters || assetsOpts.pdfThumbnails
-      if (advancedEnabled) {
-        const { posterMapping, thumbnailMapping } = await processAdvancedAssets(
-          siteContent.assets,
-          {
-            outputDir: resolvedDistDir,
-            assetsSubdir: assetsOpts.outputDir,
-            videoPosters: assetsOpts.videoPosters,
-            pdfThumbnails: assetsOpts.pdfThumbnails,
-            quality: assetsOpts.quality,
-            basePath,
-            hasExplicitPoster: siteContent.hasExplicitPoster || new Set(),
-            hasExplicitPreview: siteContent.hasExplicitPreview || new Set(),
-          }
-        )
-
-        finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
-        if (Object.keys(posterMapping).length > 0 || Object.keys(thumbnailMapping).length > 0) {
-          finalContent._assetMeta = {
-            posters: posterMapping,
-            thumbnails: thumbnailMapping,
-          }
-        }
-      } else {
-        finalContent = rewriteSiteContentPaths(siteContent, pathMapping, files)
-      }
-    }
-  } else {
-    // Drop the assets manifest from the output when processing is off
-    // (matches the vite plugin's behavior — manifest is internal).
-    finalContent = { ...siteContent }
-    delete finalContent.assets
-  }
+  // 3. No media processing (header, "Does NOT emit"). The collector's asset
+  //    manifest is internal, so it is dropped — as the vite plugin drops it
+  //    when processing is off.
+  let finalContent = { ...siteContent }
+  delete finalContent.assets
 
-  // Strip internal-only properties that don't serialize and have no
-  // place in the published payload (Sets don't JSON-roundtrip; the
-  // build's split-content emit consumed them already).
+  // Strip internal-only properties that don't serialize (Sets don't
+  // JSON-roundtrip): the collector records them for media processing.
   delete finalContent.hasExplicitPoster
   delete finalContent.hasExplicitPreview
 
   // ⛔ `config.icons` is a HOST-owned slot on this lane — drop it.
   //
-  // This payload only ever goes to a backend (link mode is what `uniweb deploy`
-  // runs), and `config` is site.yml spread whole, so an author's
-  // `icons.cdnUrl` would otherwise ride along and land in a slot the host is
-  // supposed to fill. The icon base is a property of the DEPLOYMENT, identical
-  // for every site a given backend serves — not something one site gets to
-  // choose [Diego, 2026-08-17].
+  // This is the build for a backend (link mode is what `uniweb publish` runs),
+  // and `config` is site.yml spread whole, so an author's `icons.cdnUrl` would
+  // otherwise sit in a slot the host is supposed to fill. The icon base is a
+  // property of the DEPLOYMENT, identical for every site a given backend
+  // serves — not something one site gets to choose [Diego, 2026-08-17].
+  // ⛔ *Until 2026-10-19 this said the payload "only ever goes to a backend":
+  // `publish` reads it for its languages, and sends the content over the sync
+  // wire, which never had this exposure (below).*
   //
   // The reason it cannot be a site's call is that the base and the NAMESPACE
   // are coupled: icon filenames are minted by whoever built the corpus, so

package/src/site/deploy-config.js

@@ -5,7 +5,7 @@
  * by name. Read-only — never writes. See deploy-config-writer.js for
  * the write path.
  *
- * On-disk shape (spec: kb/framework/reference/deploy-yml.md):
+ * On-disk shape:
  *   default: production
  *   targets:
  *     production: { host, backend?, ...host-specific config }

package/src/site/file-transport.js

@@ -5,8 +5,7 @@
  * (`@uniweb/runtime/ssr::loadPageData`) asks for what a page's render will read, by the rule the
  * render itself uses, and dispatches every request through one function the caller supplies. A host
  * gives it the network; this lane gives it `dist/` and `public/`. So the build asks the same
- * question as every other lane and only the answering differs — which is the whole point of
- * `kb/framework/plans/what-a-page-needs.md`.
+ * question as every other lane, and only the answering differs.
  *
  * ⛔ **A remote `url:` is still the browser's lane by default.** Nothing here decides that: the
  * author's `prerender:` does, and the step is run with `prerender: 'author'` so a deferred request

package/src/site/foundation-ref.js

@@ -70,9 +70,11 @@ export function parseCatalogRef(value) {
  *   - `'local'` — workspace-local source (sibling directory, file: dep, or
  *     `../../foundations/<name>/`). The build inlines or runtime-links it
  *     depending on the operating mode.
- *   - `'url'`  — loaded by URL at runtime. Two URL shapes:
- *       - `@org/name@ver`   → catalog ref (resolves against the registry CDN)
- *       - `https://...`    → arbitrary URL
+ *   - `'url'`  — loaded by URL at runtime: an `https://…` URL, or the object
+ *     form's `url`. A catalog ref (`@org/name@ver`) is refused, since where one
+ *     is served is the host's to say — except under `uniweb dev`, which is
+ *     handed the answer (`served`). ⛔ *Until 2026-10-19 this listed a catalog
+ *     ref as a URL shape, "resolved against the registry CDN".*
  *
  * Versionless registry refs (`@org/name`) are rejected with a specific error —
  * they were a silent fall-through before. Versionless names that don't match
@@ -181,9 +183,9 @@ export function detectFoundationType(foundation, siteRoot, { served = null } = {
   // resolve through the local checks below (file: dep,
   // workspace sibling) when the developer is iterating locally on a
   // foundation that will eventually be published as `@org/name@ver`.
-  // Tianyu's uniweb.io site uses this shape:
-  //   site.yml:     foundation: '@uniweb/io'
-  //   package.json: "@uniweb/io": "file:../../foundations/io"
+  // For example:
+  //   site.yml:     foundation: '@acme/marketing'
+  //   package.json: "@acme/marketing": "file:../../foundations/marketing"
   // The file: dep check below picks it up. If no local resolution exists
   // either, the function throws below with a "missing version" hint.
 

package/src/uwx/data-schema.js

@@ -78,7 +78,7 @@ export function openMapFromRows(rows) {
 /**
  * A `text` field marked as rich content (`format: markdown` or `html`): the
  * file-based body target. Round-trips as the raw source string — what the retired
- * `richtext` kind used to be. See framework/CLAUDE.md gotcha #21 and uwx-format.md.
+ * `richtext` kind used to be.
  */
 export function isMarkupTextField(field) {
   return field?.type === 'text' && CONTENT_TEXT_FORMATS.has(field?.format)
@@ -89,7 +89,7 @@ export function isMarkupTextField(field) {
  * authored as markdown on the file side, carried as a ProseMirror document on the
  * sync wire (the common language with the visual app). The single predicate the
  * sync producer/projector use to decide md⇄ProseMirror conversion + structural-map
- * localization. See framework/CLAUDE.md gotcha #21 and uwx-format.md.
+ * localization.
  */
 export function isProseMirrorField(field) {
   return field?.type === 'json' && field?.format === 'richtext'

package/src/uwx/entity-document.js

@@ -36,7 +36,6 @@ import {
  * then, and ⛔ nothing reads that spelling — no production backend existed to keep a
  * window for [Diego, 2026-09-24]. The value comes back as it is, so a caller can still
  * tell an id from a name and say which it met.
- * Record: `kb/framework/build/uwx-format.md` § *The data schema an entity names*.
  *
  * @param {object} doc - an entity `$`-document
  * @returns {string|null}

package/src/uwx/folder.js

@@ -75,7 +75,7 @@ export const FOLDER_ENTITY_KEY = '@folder'
 // registry of the backend we talk to. ⛔ Neither is an identity across backends: each
 // has its own registry [Diego, 2026-09-24]. (A TODO here asked
 // for the id until then; the agreement settled it the other way.) The key was `model`
-// until the same date. Record: `kb/framework/build/uwx-format.md` § 8.
+// until the same date.
 function refLeaf(entity) {
   const leaf = { kind: 'ref', name: entity.slug }
   if (entity.uuid) leaf.entry = { schema: entity.model, entity: entity.uuid }

package/src/uwx/index.js

@@ -106,7 +106,6 @@ export { emitSyncPackages } from './sync-package.js'
 export { restoreAssetRefs, servedFingerprint } from './asset-map.js'
 // `sync.json` — what each backend minted, keyed by origin. Absorbs `assets.json`
 // above, `site.yml`'s identity keys and three maps out of the sync cache.
-// Spec: kb/framework/reference/sync-json.md
 export {
   SYNC_STORE_FILE,
   readSyncStore,
@@ -122,7 +121,6 @@ export {
   normalizeOrigin as normalizeBackendOrigin,
 } from './sync-store.js'
 // A site's services request — `site.yml::services`, applied over the site's own rows.
-// Spec: kb/framework/reference/site-services-request.md
 export {
   RUNTIME_KEYS,
   readServicesRequest,

package/src/uwx/services-request.js

@@ -43,8 +43,6 @@
  * Pure functions, shared by the static build (`content-collector.js`), the producer
  * (`site.js`), pull (`site-project.js`) and the CLI's push, publish and doctor.
  *
- * Spec: kb/framework/reference/site-services-request.md
- *
  * @module
  */
 
@@ -456,8 +454,8 @@ export function servicesFromDocument({ rows, local } = {}) {
  * The `services` Section a push sends: every service `site.yml` lists, as it says it, and
  * OFF for every service this copy holds that the file does not list.
  *
- * ⭐ A PUSH STATES, AND THE BACKEND DECIDES PER SERVICE [Diego, 2026-10-07 —
- * kb/framework/plans/services-exchange.md]. Every service is on or off, off by default.
+ * ⭐ A PUSH STATES, AND THE BACKEND DECIDES PER SERVICE [Diego, 2026-10-07]. Every
+ * service is on or off, off by default.
  *
  *   - A service the file lists goes WHOLE — its switch, and the entry as its `config` — so
  *     a setting removed from the file is removed.

package/src/uwx/site.js

@@ -1104,13 +1104,13 @@ function queriesNested(declarations, uuids = null, scope = null, keyTyped = null
 // ── `services` + `secrets` — what a site asks of its host ─────────────────────────
 //
 // ⭐ THE `services` SECTION IS THE OWNER'S REQUEST, AUTHORED IN `site.yml::services` — a
-// map from service name to `true`, `false` or the service's settings (spec:
-// kb/framework/reference/site-services-request.md). A push STATES: every service the
+// map from service name to `true`, `false` or the service's settings. A push STATES:
+// every service the
 // file lists, as it says it, and OFF for every service this copy holds that the file no
 // longer lists (`statedServices`). The services it holds are named in that backend's
 // entry in `sync.json`, `{ name: $uuid }`, written by pull and by a push that succeeded;
 // one it never saw is not sent, and the site keeps it. The backend decides per service
-// from the versions the push sends [Diego, 2026-10-07 — kb/framework/plans/services-exchange.md].
+// from the versions the push sends [Diego, 2026-10-07].
 // ⛔ *Until then the Section went as a FULL LIST — the site's rows, read just before the
 // push, with the file's changed asks applied — because the backend replaced the Section
 // with what it was sent; and from 2026-09-20 to 2026-10-06 the rows lived only in
@@ -1734,5 +1734,5 @@ export function writeSiteEntityUuid(siteRoot, backend, uuid) {
 // ⛔ `writeSiteBackend` and `site.yml::$backend` are GONE (2026-09-20). The scope is
 // no longer a value recorded beside the uuid — it is the KEY the identity is stored
 // under (`sync.json::backends.<origin>`), so there is nothing to record and nothing
-// that can disagree with it. `kb/framework/reference/sync-json.md`.
+// that can disagree with it.
 

package/src/uwx/sync-package.js

@@ -53,7 +53,7 @@ const withBaseVersion = (baseVersions, itemBaseVersions, { every = false } = {})
   // present AND for items the files dropped. A push deletes only the items it holds a
   // version for, and only while the site left them unchanged — so a dropped item's
   // version is what makes leaving it out a deletion, and without it the item is kept
-  // [Diego, 2026-10-07; backend's gate, kb/framework/plans/services-exchange.md]. The
+  // [Diego, 2026-10-07; backend's gate]. The
   // caller holds a version only for an item it has seen (`heldTokens`, cli), so none is
   // ever sent for an item the backend holds and this copy does not.
   // ⛔ Until then this narrowed to the units the document carried: a dropped page was

package/src/uwx/sync-store.js

@@ -11,9 +11,6 @@
  * ⭐ **If it changed, something got synced.** Nothing else writes it — which is the
  * whole reason it is separate from `deploy.yml`, whose diff means "a target changed".
  *
- * Spec: `kb/framework/reference/sync-json.md`. Why it exists at all:
- * `kb/framework/plans/backend-scoped-project-state.md`.
- *
  * ## Why it is keyed by ORIGIN, all the way down
  *
  * A project may sync with any number of backends. Nothing can be shared between