uniweb 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uniweb",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Create structured Vite + React sites with content/code separation",
   "type": "module",
   "bin": {
@@ -42,13 +42,13 @@
     "prompts": "^2.4.2",
     "tar": "^7.0.0",
     "@uniweb/core": "^0.8.5",
-    "@uniweb/runtime": "^0.11.7",
-    "@uniweb/kit": "^0.11.3"
+    "@uniweb/kit": "^0.12.0",
+    "@uniweb/runtime": "^0.11.7"
   },
   "peerDependencies": {
-    "@uniweb/build": "^0.21.0",
-    "@uniweb/semantic-parser": "^1.2.2",
-    "@uniweb/content-reader": "^1.2.2"
+    "@uniweb/content-reader": "^1.2.2",
+    "@uniweb/build": "^0.22.0",
+    "@uniweb/semantic-parser": "^1.2.2"
   },
   "peerDependenciesMeta": {
     "@uniweb/build": {

package/partials/agents.md

@@ -649,6 +649,50 @@ seo:
 
 **Localized URLs:** on a multilingual site (`languages:` in site.yml), `slug: { <lang>: <segment> }` gives a page a native URL segment per language; the folder name stays the canonical route. Nested folders compose automatically, and localized URLs flow through navigation, the language switcher, and the sitemap. See Part 5 for the translation workflow.
 
+**Knowledge pages — content for an AI agent, not for a visitor.** `knowledge: true` in a `page.yml` or `folder.yml` marks a page as agent-only: it is **never rendered** — no route, no HTML — and it cascades to the whole subtree by route prefix, so one marker on `pages/kb/` covers everything under it and `/kb` never claims `/kbase`. Write plain markdown; a section `type:` there never selects a component, because nothing renders these pages.
+
+⚠️ **A knowledge page is not published to anyone — it powers a service your site offers.** Everything your site *does* publish is published on equal terms: an AI visiting your site sees exactly what a person sees. `llms.txt` and the per-page `.md` files are a convenience for that reader, not a privileged tier — no visitor, human or machine, gets more than another.
+
+A knowledge page is different in kind, not in audience. It is never a page anyone reads; it is source material for an assistant the site offers **to its visitors** — they ask, they get an answer, and the material behind it stays unpublished. That is why it is kept out of `llms.txt`, the `.md` projections and the search index: not because some readers are trusted less, but because a knowledge page was never a page.
+
+⇒ If what you want is "make this readable by any AI that visits", write an ordinary page. It is already published to them, on the same terms as to everyone else.
+
+⛔ **`knowledge:` is not a security control — don't put secrets there.** "Not published" is about who the prose is *written for*, not about confidentiality. The assistant's job is to answer visitors using this material and it can quote it back to whoever asks, so a visitor who prompts it can surface what a knowledge page says — **by design, not by leak.** The test for what belongs here is "is this written for the assistant to reason with?", not "do I want to keep this from people?" Anything that genuinely must not reach a visitor doesn't belong in your site's content at all.
+
+```yaml
+# pages/kb/page.yml
+title: Product Knowledge
+knowledge: true
+```
+
+What can actually *read* it depends on where you deploy, because reading it needs a server:
+
+- **`uniweb deploy`** (backend-hosted) — the content travels with the site, so an assistant running over it can grep and read your knowledge material alongside the public content when answering a visitor's question.
+- **`uniweb export` / `uniweb deploy --host <adapter>`** (static host) — **the build drops these pages and says so**: `Dropped 2 knowledge page(s) from this build: /kb, /kb/pricing`. Files are served as files here; there is no assistant, so nothing would read them. The warning means the flag was honoured.
+
+The artifacts **your build emits** to describe the public site never name them — `llms.txt`, the per-page `.md` projections, and the search index all describe pages a visitor reads, and a knowledge page's prose was written for the assistant instead. Two settings **outrank** `knowledge:`, so a contradiction resolves toward the narrower reach: `agents.exclude` in `site.yml`, and any `_`-prefixed route segment. *(A host that derives these artifacts itself, rather than serving the ones your build produced, applies its own rules — ask your host what it does with `knowledge:` before relying on it there.)*
+
+Don't confuse it with the visibility flags: `hidden: true` is a **draft** (not published at all), `hideIn` only controls **nav placement** (still reachable by URL), and `knowledge: true` is a **different audience** (never rendered for anyone).
+
+**A site can be nothing but knowledge — that is a real and useful shape.** A site is a set of routes; it does not have to have HTML pages. Mark the root `knowledge: true` and every page inherits it, so the site renders nothing at all and exists to *be* an agent: a `/_agent/chat` URL that a web app, a mobile app, or someone else's backend sends requests to.
+
+```
+site/pages/
+├── page.yml          # knowledge: true — cascades to everything
+├── house-style.md
+├── pricing.md
+└── support.md
+```
+
+Measured on exactly that shape: **the agent corpus holds every page; the public projections hold nothing** — `llms.txt` lists no pages, the search index has 0 entries, and no `.md` files are emitted. Nothing leaks, by construction rather than by configuration, because there is no public surface to leak onto.
+
+⛔ **This shape needs a host that actually runs an agent, and deploying is not the same as having one.** Two ways to end up with nothing:
+
+- **A static host** (`uniweb export`, `deploy --host`) drops every page — they have no reader there — and you get an empty SPA shell. The build still says *"complete"*, because 0 pages is not an error: it reports `Collected 0 pages` and pre-renders none.
+- **A backend-hosted deployment that does not offer the service.** Whether an agent endpoint exists is the host's to decide, per site — it is not implied by deploying successfully.
+
+⇒ **The way to know is to ask, at render:** `resolveService(website, 'assistant')` returns a `url` only where the host declared one. On a site that is *only* knowledge there is no component to ask — so confirm with your host that the agent is enabled for that site before you build an integration against it. If you meant to build an agent endpoint and got silence, this is where to look.
+
 ### Your site is readable by agents, automatically
 
 Every build emits two things an AI agent can use directly, alongside the HTML. **Free, on by default, nothing to install.**
@@ -674,6 +718,38 @@ agents:
 agents: false            # or turn the whole thing off in one word
 ```
 
+#### Expecting agent traffic from somewhere specific
+
+If your site runs an agent (see *Knowledge pages* above), you can declare where its requests are expected to come from. Useful when the site exists to serve someone else's app rather than its own visitors — a chat endpoint your web app calls.
+
+```yaml
+# site.yml
+agents:
+  expectedOrigins:
+    - https://app.example.com
+    - https://partner.example.org
+```
+
+**It is a declaration, not a gate — the name is the contract.** You are telling the host where you expect callers from; a host that offers an agent may then decline requests whose browser-sent `Origin` is not one of them, before it spends anything answering. Behaviour where it is honoured:
+
+| | |
+|---|---|
+| not declared | no check at all — nothing happens unless you ask for it |
+| your own site's origin | always fine, without listing it — declaring a partner must not take down your own chat box |
+| a request with **no** `Origin` | **allowed** — see below, this is deliberate |
+| matching | exact, per entry; no wildcards |
+
+⛔ **It is not a spend limit, and it cannot be.** `Origin` is set by the browser and enforced by the browser: anything that is not a browser sends whatever it likes, or nothing at all. So this stops **casual misuse and third-party embedding** — someone dropping your endpoint into their own page — and it does **not** stop anyone determined to run up your bill. Do not size your budget on it.
+
+⭐ **And that is why a request with no `Origin` is allowed rather than refused.** There are two shapes of caller and this check only sees one:
+
+- your app's **JavaScript**, in a browser — sends `Origin`, covered here;
+- your app's **server**, calling from its own backend — never sends one, and refusing it would break the integration this feature partly exists for.
+
+Server-to-server callers are authenticated by other means, arranged with your host — not by anything in `site.yml`. **Never put a shared secret in `site.yml`:** everything in it is delivered to every visitor as part of the site payload.
+
+⚠️ Spelling matters and nothing downstream will catch it — the block is forwarded to your host as opaque data, so a typo is carried and simply never acted on. `uniweb doctor` flags unknown keys in `agents:` for exactly this reason; run it before you rely on one.
+
 **Set `seo.baseUrl` if you want absolute links** in the index — without it the links are root-relative, which still works for an agent that arrived via the index. `uniweb doctor` warns when it's unset.
 
 **What's excluded, and it's deliberate:** `seo.noindex` pages, `hidden` pages, `_`-prefixed drafts, and dynamic route templates. An index *describes* pages rather than merely listing them, so an unlinked page would become both discoverable and summarized — which is why these exclusions are load-bearing rather than tidy-up. `noindex` or `hidden` on a **folder** takes the whole branch with it.
@@ -1781,6 +1857,21 @@ resolution for anything, so a foundation can define a service the framework has
 never heard of and a host can fill it. Same escalation `fetcher.transports`
 offers for data.
 
+**Building an "Ask AI" component?** The service name is `assistant`, and a host that runs an agent for a site typically serves it at the conventional path `/_agent`. **You should never need to write that path** — ask the runtime instead:
+
+```jsx
+const { url } = resolveService(website, 'assistant')
+if (!url) return null          // this site has no agent — render nothing, or a static fallback
+```
+
+**This is a synchronous read, not a request.** Which services a site has was settled when the site was last published and travels in its metadata, so the runtime already holds the answer — there is no handshake, no probe, no await. Your component asks the runtime; the runtime does not ask anyone.
+
+⛔ **Absent is the answer, not a lookup that failed.** No `url` means the site has no agent — never enabled, or this host runs none. Render for that case; don't retry it. And don't hardcode `/_agent/chat` when nothing was declared: on a static host that turns "no agent here" into a 404 your component can't tell from a broken endpoint. The path is named above so you recognize the shape, not so you can construct it.
+
+⛔ **And don't tell the visitor.** `resolveService` also returns a `reason`, and it is **not visitor copy** — a visitor has no stake in which services the operator provisioned, and "this site has no assistant configured" reports someone's billing state to the public while reading like a breakage. It is neither. **Absence is a rendering decision, not a message**: a generic component is expected to be smart about it. No assistant → no Ask-AI affordance. No submit endpoint → no form, or degrade to a `mailto:` the site already carries in its content. The `reason` string is there for *you*, while you wire a site up.
+
+*(A live agent that errors mid-conversation is a different problem — that's ordinary request failure, handled where you make the request.)*
+
 ```yaml
 # site.yml — only when YOU are providing the endpoint. Publishing to Uniweb
 # Cloud needs nothing here; `uniweb export` and most `deploy --host` targets do.
@@ -1791,14 +1882,16 @@ submit: https://forms.example.com/intake    # or another origin
 ```jsx
 import { useFormSubmit } from '@uniweb/kit'
 
-const { submit, status, error, canSubmit, unavailableReason } = useFormSubmit({
+const { submit, status, error, canSubmit } = useFormSubmit({
   block,                                    // supplies section + page context
   context: { formId: 'contact' },
   summary: (v) => ({ title: v.name, subtitle: v.email }),
 })
 
-<button type="submit" disabled={!canSubmit || status === 'submitting'}>Send</button>
-{!canSubmit && <p role="status">{unavailableReason}</p>}
+if (!canSubmit) return null    // nowhere to send — render no form, or fall back
+                               // to contact details from the site's own content
+
+<button type="submit" disabled={status === 'submitting'}>Send</button>
 ```
 
 > **The framework never invents an endpoint — but a host may supply one.** Don't
@@ -1807,11 +1900,18 @@ const { submit, status, error, canSubmit, unavailableReason } = useFormSubmit({
 > one hosting.
 >
 > `canSubmit` is false only when neither a declaration nor a host supplies a
-> destination. **Check it when you render, not only on the button press**, so the
-> control is visibly disabled before anyone fills the form in, and show
-> `unavailableReason` — it explains which case you are in. A read that 404s
+> destination. **Check it when you render, not only on the button press** — a
+> form nobody can send should not be on the page at all. A read that 404s
 > degrades to `[]` and the page still renders; a write that 404s loses what a
 > person typed, so it gets no silent fallback.
+>
+> ⛔ **Don't tell the visitor why.** There is deliberately no explanatory string:
+> which services an operator bought is none of a visitor's business, "not enabled
+> for this site" reads like a breakage when nothing is broken, and any such
+> sentence would be one language on a site that is often multilingual and rarely
+> English. Text a visitor reads is **site content** — authored, and localized with
+> everything else. Degrade to something useful instead: a `mailto:`, a phone
+> number, an address the site already carries.
 
 `status` runs `idle → submitting → success | error`; a non-2xx becomes a thrown
 `Error` carrying the endpoint's own `error` message when it sends one. For file

package/src/commands/doctor.js

@@ -17,7 +17,7 @@ import {
   classifyPackage,
   isExtensionPackage as buildIsExtensionPackage
 } from '@uniweb/build'
-import { loadDeployYml } from '@uniweb/build/site'
+import { loadDeployYml, AGENTS_KEYS } from '@uniweb/build/site'
 import { listAdapters } from '@uniweb/build/hosts'
 import { getCliVersion } from '../versions.js'
 import { readAgentsVersion } from '../utils/agents-stamp.js'
@@ -255,6 +255,108 @@ export function findFormContent(sitePath, siteYml) {
   return found
 }
 
+/**
+ * A misspelled key in `agents:` is silent everywhere else, forever.
+ *
+ * The block reaches a backend as **opaque JSON** — measured 2026-08-13, and it
+ * is the right design: the vocabulary is the framework's, and a backend that
+ * validated it would be inventing our language. The cost is that nothing
+ * downstream can object. A host receives `expectedOrgins`, stores it, forwards
+ * it, and enforces nothing; the author sees a configured site and gets no
+ * check. **This is the only lane that can catch it.**
+ *
+ * ⛔ Severity is deliberate. It is a `warning` for an unknown key generally,
+ * but the failure it prevents is worst for the keys that RESTRICT something —
+ * an author who writes `expectedOrgins` believes they asked for a check they
+ * did not get. A key that silently does nothing is the recurring wart of this
+ * block: `exclude`'s glob spelling excludes nothing, and a carried key nobody
+ * reads enforces nothing.
+ *
+ * `agents: false` turns the capability off in one word and is not an object —
+ * flagging its absence of keys would be nonsense.
+ */
+export function checkAgentsBlock({ siteName, siteYml, issues }) {
+  const agents = siteYml?.agents
+  if (agents === undefined || agents === false) return
+  if (!agents || typeof agents !== 'object' || Array.isArray(agents)) {
+    const id = 'agents-not-an-object'
+    issues.push({
+      id,
+      type: 'warning',
+      site: siteName,
+      message: `site.yml: \`agents:\` should be a map of options, or \`false\` to turn it off`
+    })
+    warn(`[${id}] ${siteName}: \`agents:\` is neither a map of options nor \`false\`.`)
+    return
+  }
+
+  const known = new Set(AGENTS_KEYS)
+  const unknown = Object.keys(agents).filter((k) => !known.has(k))
+  if (unknown.length === 0) return
+
+  const id = 'agents-unknown-key'
+  issues.push({
+    id,
+    type: 'warning',
+    site: siteName,
+    message: `site.yml: \`agents:\` has ${unknown.length === 1 ? 'an unknown key' : 'unknown keys'}: ${unknown.join(', ')}`
+  })
+  warn(
+    `[${id}] ${siteName}: \`agents:\` ${unknown.length === 1 ? 'key' : 'keys'} ${unknown
+      .map((k) => `'${k}'`)
+      .join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not recognized.`
+  )
+  for (const key of unknown) {
+    const near = nearestAgentsKey(key, known)
+    if (near) log(`    ${colors.dim}'${key}' — did you mean ${colors.reset}${colors.green}${near}${colors.reset}${colors.dim}?${colors.reset}`)
+  }
+  log(
+    `    ${colors.dim}Nothing downstream will reject it: the block is forwarded to the host as opaque data,${colors.reset}`
+  )
+  log(
+    `    ${colors.dim}so an unrecognized key is carried and never acted on. Known: ${AGENTS_KEYS.join(', ')}.${colors.reset}`
+  )
+}
+
+/**
+ * The closest known key within a small edit distance, or null.
+ *
+ * Suggestions are capped at distance 3 rather than "closest wins": on a
+ * six-word vocabulary an uncapped nearest-match confidently proposes `index`
+ * for `origins`, and a wrong suggestion is worse than none — it sends the
+ * author to change a line that was not their mistake.
+ */
+function nearestAgentsKey(input, known) {
+  let best = null
+  let bestScore = Infinity
+  for (const candidate of known) {
+    const score = editDistance(input.toLowerCase(), candidate.toLowerCase())
+    if (score < bestScore) {
+      bestScore = score
+      best = candidate
+    }
+  }
+  return bestScore <= 3 ? best : null
+}
+
+/** Levenshtein distance, iterative two-row form. */
+function editDistance(a, b) {
+  if (a === b) return 0
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i]
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(
+        prev[j] + 1,
+        row[j - 1] + 1,
+        prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      )
+    }
+    prev = row
+  }
+  return prev[b.length]
+}
+
 /**
  * A site whose content declares a form needs somewhere to send it.
  *
@@ -657,6 +759,7 @@ export async function doctor(args = []) {
     // anyone who knows the URL, listed by nothing.
     // Forms need a destination, and having none is only visible on the page.
     await checkFormSubmitTarget({ sitePath, siteName, siteYml, issues })
+    checkAgentsBlock({ siteName, siteYml, issues })
 
     checkGeneratedDataDir({
       sitePath,

package/src/framework-index.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-08-13T15:51:25.141Z",
+  "generatedAt": "2026-08-13T20:52:45.396Z",
   "packages": {
     "@uniweb/build": {
-      "version": "0.21.0",
+      "version": "0.22.0",
       "path": "framework/build",
       "deps": [
         "@uniweb/content-reader",
@@ -46,7 +46,7 @@
       "deps": []
     },
     "@uniweb/kit": {
-      "version": "0.11.3",
+      "version": "0.12.0",
       "path": "framework/kit",
       "deps": [
         "@uniweb/core",
@@ -65,7 +65,7 @@
       "deps": []
     },
     "@uniweb/projections": {
-      "version": "0.3.0",
+      "version": "0.3.1",
       "path": "framework/projections",
       "deps": [
         "@uniweb/content-writer",
@@ -111,7 +111,7 @@
       "deps": []
     },
     "@uniweb/unipress": {
-      "version": "0.8.6",
+      "version": "0.8.7",
       "path": "framework/unipress",
       "deps": [
         "@uniweb/build",