@uniweb/build 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,16 +59,16 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/projections": "^0.3.2",
+    "@uniweb/content-writer": "^0.3.3",
     "@uniweb/schemas": "^0.2.10",
-    "@uniweb/projections": "^0.3.0",
-    "@uniweb/theming": "^0.1.15",
-    "@uniweb/content-writer": "^0.3.3"
+    "@uniweb/theming": "^0.1.15"
   },
   "optionalDependencies": {
-    "@uniweb/schemas": "^0.2.10",
     "@uniweb/content-reader": "^1.2.2",
-    "@uniweb/semantic-parser": "^1.2.2",
-    "@uniweb/runtime": "^0.11.7"
+    "@uniweb/runtime": "^0.11.8",
+    "@uniweb/schemas": "^0.2.10",
+    "@uniweb/semantic-parser": "^1.2.2"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -77,7 +77,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.8.5"
+    "@uniweb/core": "^0.9.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/site/index.js

@@ -9,6 +9,10 @@
 export { siteContentPlugin } from './plugin.js'
 export { defineSiteConfig, readSiteConfig, default } from './config.js'
 export { collectSiteContent } from './content-collector.js'
+// The `agents:` vocabulary lives in @uniweb/projections (which owns the block);
+// re-exported so the CLI can validate an author's spelling without taking a
+// direct dependency on it. Same shape as the search re-exports.
+export { AGENTS_KEYS } from '@uniweb/projections'
 export { buildSiteData } from './build-site-data.js'
 export { shouldSplitContent } from './split-content.js'
 export {

package/src/site/plugin.js

@@ -513,13 +513,20 @@ export function siteContentPlugin(options = {}) {
   /**
    * Collect the site, then drop `knowledge:` pages.
    *
-   * ⛔ **This is the bundle lane, and the bundle lane has no agent endpoint.**
+   * ⛔ **This is the bundle lane, and the bundle lane has no agent.**
    * `uniweb export` and `uniweb deploy --host <adapter>` both run this pipeline
    * (`cli/src/commands/export.js`, `deploy.js`), and their destinations are
-   * static hosts — no worker, no backend, nothing that can gate a request. A
-   * `knowledge:` page is content the author marked for an agent and not for a
-   * visitor; here there is no agent to serve it to and no gate to withhold it
-   * with, so shipping it is disclosure with **no consumer on the other side**.
+   * static hosts — files served as files, with no service running over the
+   * content. A `knowledge:` page is source material for such a service: prose
+   * written for it to reason with, addressed to it rather than to a person.
+   * Here there is no service to give it to, so publishing it would turn prose
+   * written for a machine reader into pages for visitors — the only readers
+   * this host has.
+   *
+   * ⚠️ **Not a confidentiality argument.** [Diego, 2026-08-13] *"It is not the
+   * case that it's private in the sense of sensitive."* The service quotes this
+   * material back to whoever prompts it, by design. The reason to drop it here
+   * is that it has no reader on this lane, not that it must be kept from one.
    *
    * Measured 2026-08-13, before this existed: a knowledge page became
    * `dist/kb/index.html` — a public route — and its body rode in the
@@ -543,8 +550,8 @@ export function siteContentPlugin(options = {}) {
       const routes = knowledgePages.map(page => page.route).join(', ')
       console.warn(
         `[site-content] Dropped ${knowledgePages.length} knowledge page(s) from this build: ${routes}\n` +
-          `  This build targets a host that serves files only, so there is no agent endpoint to read them ` +
-          `and no gate to keep them from visitors. Use \`uniweb deploy\` to make them agent-readable.`
+          `  This build targets a host that serves files only, so nothing here reads them — their prose is ` +
+          `written for a site assistant, not for visitors. Use \`uniweb deploy\` to make them agent-readable.`
       )
     }
 

package/src/uwx/site-project.js

@@ -110,12 +110,27 @@ const INFO_TO_SITE_YML = {
   // through `config.services` and resolved at render time, so it never enters
   // `info` and a pull cannot launder it into authored config.
   //
-  // ⚠️ One asymmetry worth knowing: push STRIPS credential-shaped keys, so a
-  // block that carried an `apiKey` comes back without it and the pull rewrites
-  // the author's file minus that line. That is intended — the key must not be
-  // there and the push already warned — but it is the one case where a pull
-  // removes something the author typed.
+  // ⚠️ Credential-shaped keys are STRIPPED ON PUSH (`stripCredentials`), so the
+  // backend never stores one and it cannot come back. What that does to the
+  // author's file depends on which direction they are pulling into, and the two
+  // differ — ⛔ this comment asserted the wrong one until it was run:
+  //
+  //   - `pull` over an EXISTING site.yml — the local `apiKey` SURVIVES.
+  //     `mergeYamlConfig` spreads one level (`{...existing[key], ...value}`), so
+  //     the projected `{endpoint, …}` merges over the local block and nothing
+  //     removes a key the document does not carry.
+  //   - `clone` into a fresh directory — no local block exists, so the file is
+  //     written from the document alone and has no `apiKey`.
+  //
+  // Both are correct: a pull does not silently delete something the author
+  // typed, and the push already warned them. The security property is upheld at
+  // the push, not by the pull. Measured end-to-end against a live uniwebd —
+  // every unit test passed before and after, so only a real push touched it.
   assistant: 'assistant',
+  // Authored-only, like `submit` and `assistant`: a host's tracking endpoint is
+  // offered through `config.services.tracking` and resolved at render, so it
+  // never enters `info` and a pull cannot launder it into authored config.
+  tracking: 'tracking',
   paths: 'paths',
   data: 'data',
   template: 'template',
@@ -358,7 +373,7 @@ export function pageSectionsToFiles({ pageDir, pageSections, ctx, pageContext })
 // and preserved. Keep in sync with pageRecordToYml below.
 const PAGE_YML_MANAGED_KEYS = new Set([
   'id', 'title', 'description', 'label', 'keywords', 'index', 'hidden',
-  'hideIn', 'redirect', 'rewrite', 'layout', 'seo',
+  'hideIn', 'knowledge', 'redirect', 'rewrite', 'layout', 'seo',
   'fetch', 'sections',
 ])
 
@@ -380,6 +395,7 @@ function pageRecordToYml(record, sectionsArray, sourceLocale) {
   if (record.is_index) y.index = true
   if (record.hidden !== undefined) y.hidden = record.hidden
   if (record.hide_in !== undefined) y.hideIn = record.hide_in
+  if (record.knowledge !== undefined) y.knowledge = record.knowledge
   if (record.redirect !== undefined) y.redirect = record.redirect
   if (record.rewrite !== undefined) y.rewrite = record.rewrite
   if (record.layout !== undefined) y.layout = record.layout

package/src/uwx/site.js

@@ -201,6 +201,11 @@ function buildPageData(config, ctx) {
   setIf(data, 'hidden', config.hidden)
   const hideIn = normalizeHideIn(config)
   if (hideIn.length) data.hide_in = hideIn
+  // Agent-only content. Sent as authored — only the marked page carries it, and
+  // the cascade to descendants is the CONSUMER's to compute (by route prefix, or
+  // equivalently by walking the page tree). A reader that tests this field alone
+  // honours the branch root and silently misses every child.
+  setIf(data, 'knowledge', config.knowledge)
   setIf(data, 'redirect', config.redirect)
   setIf(data, 'rewrite', config.rewrite)
   setIf(data, 'layout', config.layout)
@@ -756,6 +761,20 @@ export async function siteProjectToDocument(siteRoot, opts = {}) {
   //
   // ⛔ Credentials are stripped, not trusted — see `stripCredentials`.
   setIf(info, 'assistant', stripCredentials(siteYml.assistant, 'assistant'))
+  // `tracking` — where this site's usage events go (`endpoint`, read by the
+  // runtime through `resolveService`, plus `consent:`). Same family as
+  // `search`/`submit`/`assistant` and here for the same reason: the bundle lane
+  // spreads all of site.yml while this one is an allowlist, so without this line
+  // an authored `tracking:` works on a static host and vanishes silently on the
+  // synced lane.
+  //
+  // ⛔ Credentials stripped like `assistant`. A collector that wants a write key
+  // is a real shape, and this block is published world-readable — but note the
+  // strip only reaches a KEYED FIELD: a key embedded in the endpoint URL itself
+  // (`https://collector/e?key=…`) is invisible here and is disclosed. The host's
+  // secret store is the only right home either way.
+  // (kb/framework/plans/tracking.md)
+  setIf(info, 'tracking', stripCredentials(siteYml.tracking, 'tracking'))
   setIf(info, 'paths', siteYml.paths)
   setIf(info, 'data', siteYml.data ?? siteYml.fetch)
   // `app` — the deployment's `@uniweb/app-spec` reference (a bare uuid string),