@xanots/sdk 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to [`@xanots/sdk`](https://www.npmjs.com/package/@xanots/sdk).
+
+This file is **generated** from the [GitHub releases](https://github.com/xanots/sdk/releases)
+by `npm run changelog` — edit the release, not this file. Each entry summarizes
+one release and links to its full notes.
+
+Versions before 0.0.1 belong to the retired `@xanots/core` line and are not
+listed here.
+
+---
+
+## 0.0.4 — The markdown your agents read
+
+_2026-08-26_ · [release notes](https://github.com/xanots/sdk/releases/tag/v0.0.4)
+
+Knowledge is now workspace source: the markdown your Xano agents read before they act is authored as real `.md` files, reviewed in a diff, and deployed with the code it describes. Two commands join the CLI — `xanots onboard` puts the scaffold's choices in a browser, and `xanots upgrade` answers the version question on purpose rather than nudging. Windows users should take this one regardless: every npm call in the package was failing before it reached npm.
+
+- `knowledge()` — author the markdown your Xano agents read
+- `xanots onboard` — pick the scaffold's look in a browser
+- `xanots upgrade` — the version question asked on purpose
+- Every npm call failed on a current Node for Windows
+- The guides ship in the tarball
+- `CHANGELOG.md` ships, generated from the releases
+
+---
+
+## 0.0.3 — The scaffold gets a look
+
+_2026-08-25_ · [release notes](https://github.com/xanots/sdk/releases/tag/v0.0.3)
+
+`xanots init` wrote one hard-coded stylesheet, so every scaffolded project looked
+identical. It now takes a theme, a corner radius, a dark-mode strategy, three
+typeface slots and an icon set — 126 themes composed from shadcn/ui's own tables,
+or any registry theme URL. The same command can install **and register**
+marketplace add-ons in one line, and the agent grounding now points assistants at
+a prebuilt module instead of hand-rolling one. Nothing changes for anyone not
+passing the new flags: no flags and no TTY scaffolds exactly what it did before.
+
+- `xanots init` takes a theme, typefaces and an icon set
+- `chart-*` and `sidebar-*` were missing from every scaffolded stylesheet
+- `components.json` hard-coded a base color the stylesheet no longer used
+- Dark mode shipped inert
+- `--marketplace` installs add-ons and registers them
+- Agents are grounded in marketplace discovery and the first-party modules
+- New `@xanots/sdk/scaffold` export carries the scaffold's palette as data
+
+---
+
+## 0.0.2 — What the engine actually requires
+
+_2026-08-25_ · [release notes](https://github.com/xanots/sdk/releases/tag/v0.0.2)
+
+This release is about the statement surface refusing what the engine cannot accept, while you are writing rather than after you deploy. An absent required argument does not error on Xano — it substitutes a type default and answers HTTP 200 with a confident wrong result, which nothing downstream can distinguish from a right one. So 50-odd arguments that were typed optional are now required, one field the engine never reads is gone, and the wrappers that used to pass a missing field along now name it. If your code omitted any of them it will stop type-checking; it was already producing the wrong answer.
+
+- ⚠️ 25 arguments across 15 statements are now required
+- ⚠️ The Elasticsearch and OpenSearch credentials and target are required
+- ⚠️ `webflow.request` no longer offers a `headers` field
+- ⚠️ Statements that passed a missing field along now refuse it
+- A zero-argument call names the field it needs
+- A pulled workspace decodes where it used to fall back to `raw()`
+- Every statement in the catalog has byte evidence behind it
+
+---
+
+## 0.0.1 — The new name, and a README to match
+
+_2026-08-24_ · [release notes](https://github.com/xanots/sdk/releases/tag/v0.0.1)
+
+The SDK is now published as **`@xanots/sdk`**, starting a fresh version line at 0.0.1. The name says what the package is — the authoring surface, the compiler, and the CLI — rather than implying one member of a family with a shared core. Alongside the rename: two new build-time warnings for shapes that used to ship clean and then misbehave at request time, and a README rebuilt as a landing page with its reference material split into browsable guides.
+
+- ⚠️ The package is now `@xanots/sdk`
+- `s.switch` fell through without `break: true`
+- A filtered operand in a `where` could 500 at request time
+- The README is a landing page again
+- Scaffolds build the frontend before deploying it
+- `@xanots/auth` is authentication, not authorization
+- `InferResponse`: the shapes that never derive, and the line that closes each

package/README.md

@@ -93,6 +93,10 @@ for you, and the target instance comes from your token rather than a flag.
 npx @xanots/sdk login
 ```
 
+> On a remote shell, container, or Codespace — anywhere your browser can't reach this
+> machine's `127.0.0.1` — add `--paste`. It prints the URL for you to open anywhere, and you
+> paste the redirect back. See [Signing in & deploying](https://github.com/xanots/sdk/blob/main/guides/deploying.md).
+
 **2. Scaffold.** `init` writes a complete project: a Vite frontend under `frontend/` (React
 19 + shadcn/ui by default, or SvelteKit with `--framework svelte`), a XanoTS backend under
 `xano/`, and the `xano:export` / `xano:deploy` scripts already wired.
@@ -115,6 +119,20 @@ The starter backend is empty but already compiles and deploys — grow it from t
 in `xano/EXAMPLE.md`. For the flags, the two presets, theming, and add-ons, see
 [The scaffolded project](https://github.com/xanots/sdk/blob/main/guides/scaffold.md).
 
+Prefer to see the theme before you commit to it? `xanots onboard` picks the framework, the
+palette, the typefaces and the add-ons in a browser, against a live preview, and hands the
+result back to `init` here in your terminal.
+
+```bash
+npx @xanots/sdk onboard my-app
+```
+
+It is a nicer way to arrive at the flags above, not a second scaffolder — it prints the
+equivalent `init` command when it is done, so the project stays reproducible from a script.
+The configurator is downloaded on demand, so `onboard` needs the registry before it can
+start; `init` reaches out only to install the new project's dependencies, which
+`--no-install` skips.
+
 **3. Build the frontend.**
 
 ```bash
@@ -214,7 +232,25 @@ the Xano engine, and the output is proven byte-for-byte against the engine's own
 fixtures.
 
 Give a table a `seed` array and those rows ship into the database on deploy, so a fresh
-environment comes up with its lookup tables and fixtures already in place. Tables, fields,
+environment comes up with its lookup tables and fixtures already in place.
+
+Your workspace's own AI agents are configured the same way. `knowledge()` is the markdown
+they read before they act — standing instructions, a skill, or reference docs — and the body
+is a real `.md` file in your repo rather than a string in a def:
+
+```ts
+knowledge({
+  name: "deploy-runbook",
+  description: "How this workspace ships: environments, gates, and rollback.",
+  body: knowledgeFile("./deploy-runbook.md", import.meta.url),
+  refs: knowledgeDir("./deploy-runbook", import.meta.url),
+});
+```
+
+So the instructions your agents follow are reviewed in a diff, versioned with the code they
+describe, and redeployed with it — instead of living in a console where nothing tracks them.
+
+Tables, fields,
 statements, values, inputs, and middleware are all in the
 [Authoring reference](https://github.com/xanots/sdk/blob/main/guides/authoring.md); every kind you can author is in
 [Object kinds](https://github.com/xanots/sdk/blob/main/guides/object-kinds.md).
@@ -386,6 +422,7 @@ Both are readable by people too.
 [npm](https://www.npmjs.com/package/@xanots/sdk) ·
 [GitHub](https://github.com/xanots/sdk) ·
 [Issues](https://github.com/xanots/sdk/issues) ·
+[Changelog](CHANGELOG.md) ·
 [`llms.txt`](llms.txt) — the agent-facing router, mapping the `llms/` topic files
 
 XanoTS is the official TypeScript SDK for [Xano](https://xano.com). MIT licensed.

package/dist/.build-fingerprint

@@ -1 +1 @@
-07182bd42383cb8fe65cb807a679f776ecf2395dce7ca0d984068e2be86e7150
+c0021219c47ba8aba005451538637f3d324faefad89c71468080cbe5bd443fa1

package/dist/agent-file-refresh-IJ7GN2FJ.js

@@ -0,0 +1,17 @@
+import {
+  CI_ENV_VARS,
+  codingAgentDetected,
+  isCI,
+  refreshAgentFiles
+} from "./chunk-D6OGU2AI.js";
+import "./chunk-7SISR3CS.js";
+import "./chunk-ZSYZTGJH.js";
+import "./chunk-6DHJVLYP.js";
+import "./chunk-EZG76F7R.js";
+export {
+  CI_ENV_VARS,
+  codingAgentDetected,
+  isCI,
+  refreshAgentFiles
+};
+//# sourceMappingURL=agent-file-refresh-IJ7GN2FJ.js.map

package/dist/bin.js

@@ -1,168 +1,27 @@
 #!/usr/bin/env node
+import {
+  maybeNotifyUpdate
+} from "./chunk-ZGA5MUNC.js";
 import {
   readVersion,
   run
-} from "./chunk-3NFUWXOC.js";
+} from "./chunk-MS3BRZAZ.js";
 import {
   exitCodeOf,
   reportFailure
-} from "./chunk-6USV65XA.js";
-import "./chunk-HJPTWBLH.js";
+} from "./chunk-IVP6TS26.js";
+import "./chunk-MFIHIS6B.js";
+import "./chunk-GNPVYOPB.js";
 import {
-  blank,
   clearProgress,
-  detail,
-  error,
-  style,
-  warn
+  error
 } from "./chunk-EZG76F7R.js";
-import {
-  atomicWrite
-} from "./chunk-GNPVYOPB.js";
-import "./chunk-55VHDNW5.js";
-import "./chunk-DYCLVQXW.js";
-import "./chunk-5L4X5LS6.js";
+import "./chunk-BPEEGJJA.js";
+import "./chunk-F5T45NAM.js";
+import "./chunk-YUPQOLFX.js";
 import "./chunk-WHOJWOSV.js";
 import "./chunk-5XZ744TS.js";
-import "./chunk-4HT3BNZ7.js";
-
-// src/emit/update-check.ts
-import { existsSync, readFileSync, mkdirSync } from "fs";
-import { homedir } from "os";
-import { dirname, join } from "path";
-import { createRequire } from "module";
-function registryUrl() {
-  return process.env.XANOTS_UPDATE_REGISTRY ?? "https://registry.npmjs.org/@xanots/sdk/latest";
-}
-function cachePath() {
-  return process.env.XANOTS_UPDATE_CACHE ?? join(homedir(), ".xanots", "update-check.json");
-}
-var CHECK_INTERVAL_MS = 60 * 60 * 1e3;
-var FETCH_TIMEOUT_MS = 2e3;
-function isNewer(candidate, current) {
-  const a = parseSemver(candidate);
-  const b = parseSemver(current);
-  if (!a || !b) return false;
-  for (let i = 0; i < 3; i++) {
-    if (a.nums[i] !== b.nums[i]) return a.nums[i] > b.nums[i];
-  }
-  if (a.pre.length === 0) return b.pre.length > 0;
-  if (b.pre.length === 0) return false;
-  return comparePre(a.pre, b.pre) > 0;
-}
-function parseSemver(v) {
-  const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(v.trim());
-  if (!m) return null;
-  return {
-    nums: [Number(m[1]), Number(m[2]), Number(m[3])],
-    pre: m[4] ? m[4].split(".") : []
-  };
-}
-function comparePre(a, b) {
-  const len = Math.max(a.length, b.length);
-  for (let i = 0; i < len; i++) {
-    if (i >= a.length) return -1;
-    if (i >= b.length) return 1;
-    const x = a[i];
-    const y = b[i];
-    const xn = /^\d+$/.test(x);
-    const yn = /^\d+$/.test(y);
-    if (xn && yn) {
-      if (Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1;
-    } else if (xn !== yn) {
-      return xn ? -1 : 1;
-    } else if (x !== y) {
-      return x < y ? -1 : 1;
-    }
-  }
-  return 0;
-}
-function readCache() {
-  const path = cachePath();
-  if (!existsSync(path)) return void 0;
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (typeof parsed.latest === "string" && typeof parsed.checkedAt === "number") {
-      return { latest: parsed.latest, checkedAt: parsed.checkedAt };
-    }
-  } catch {
-  }
-  return void 0;
-}
-function writeCache(cache) {
-  try {
-    const path = cachePath();
-    mkdirSync(dirname(path), { recursive: true });
-    atomicWrite(path, JSON.stringify(cache, null, 2) + "\n");
-  } catch {
-  }
-}
-async function fetchLatest() {
-  try {
-    const res = await fetch(registryUrl(), {
-      headers: { accept: "application/json" },
-      signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
-    });
-    if (!res.ok) return null;
-    const data = await res.json();
-    return typeof data.version === "string" ? data.version : null;
-  } catch {
-    return null;
-  }
-}
-function disabled() {
-  return Boolean(
-    process.env.XANOTS_NO_UPDATE_CHECK || process.env.NO_UPDATE_NOTIFIER || process.env.CI
-  );
-}
-async function resolveUpdateNotice(opts) {
-  if (!opts?.force && disabled()) return null;
-  const current = opts?.current ?? readVersion();
-  if (current === "unknown") return null;
-  const cache = readCache();
-  let latest = cache?.latest;
-  const now = Date.now();
-  if (!cache || now - cache.checkedAt > CHECK_INTERVAL_MS) {
-    const fetched = await fetchLatest();
-    if (fetched) {
-      latest = fetched;
-      writeCache({ latest: fetched, checkedAt: now });
-    }
-  }
-  return latest && isNewer(latest, current) ? { current, latest } : null;
-}
-function detectInstallMode() {
-  const override = process.env.XANOTS_INSTALL_MODE;
-  if (override === "global" || override === "local") return override;
-  try {
-    const requireFromCwd = createRequire(join(process.cwd(), "package.json"));
-    requireFromCwd.resolve("@xanots/sdk/package.json");
-    return "local";
-  } catch {
-    return "global";
-  }
-}
-function upgradeCommand(mode) {
-  return mode === "global" ? "npm i -g @xanots/sdk@latest" : "npm i -D @xanots/sdk@latest";
-}
-function printUpdateNotice(notice) {
-  blank();
-  warn(
-    `A new @xanots/sdk is available: ${style.dim(notice.current)} \u2192 ${style.green(notice.latest)}`
-  );
-  detail(`update: ${upgradeCommand(detectInstallMode())}`);
-}
-function runExitedClean(code = process.exitCode) {
-  return code === void 0 || code === 0;
-}
-async function maybeNotifyUpdate() {
-  try {
-    if (disabled() || process.stderr.isTTY !== true || !runExitedClean()) return;
-    const notice = await resolveUpdateNotice();
-    if (notice) printUpdateNotice(notice);
-  } catch {
-  }
-}
+import "./chunk-YUBJLB6G.js";
 
 // src/emit/interrupt.ts
 var EXIT_SIGINT = 130;

package/dist/{capture-HUV5BNTC.js → capture-7PO6SGB4.js}

@@ -1,6 +1,6 @@
 import {
   fixtureDirForKind
-} from "./chunk-76QBEIGO.js";
+} from "./chunk-T4XPCJRF.js";
 
 // src/validate/capture.ts
 import { mkdirSync, writeFileSync } from "fs";
@@ -29,4 +29,4 @@ function safeName(name) {
 export {
   captureFixtures
 };
-//# sourceMappingURL=capture-HUV5BNTC.js.map
+//# sourceMappingURL=capture-7PO6SGB4.js.map

package/dist/{chunk-CMZLPTGW.js → chunk-7SISR3CS.js}

@@ -1,6 +1,6 @@
 import {
   runNpm
-} from "./chunk-WUSKBXXD.js";
+} from "./chunk-ZSYZTGJH.js";
 import {
   defaultThemeChoice,
   reactPreset,
@@ -442,4 +442,4 @@ export {
   resolveAiPresets,
   scaffoldProject
 };
-//# sourceMappingURL=chunk-CMZLPTGW.js.map
+//# sourceMappingURL=chunk-7SISR3CS.js.map

package/dist/{chunk-XQ22GLYS.js → chunk-AAFBSOSD.js}

@@ -1,12 +1,12 @@
-import {
-  exportWorkspaceBundle
-} from "./chunk-QTNO2WD6.js";
 import {
   sandboxBaseUrl
-} from "./chunk-7DKX2SPN.js";
+} from "./chunk-OR43PDCW.js";
 import {
   getAccessToken
-} from "./chunk-C56BC2FY.js";
+} from "./chunk-SG4UBJ47.js";
+import {
+  exportWorkspaceBundle
+} from "./chunk-QTNO2WD6.js";
 import {
   step,
   success
@@ -115,4 +115,4 @@ export {
   fetchSandboxBundle,
   runSandboxExportCommand
 };
-//# sourceMappingURL=chunk-XQ22GLYS.js.map
+//# sourceMappingURL=chunk-AAFBSOSD.js.map

package/dist/{chunk-BT2CSEC5.js → chunk-APOR6TCV.js}

@@ -1,10 +1,10 @@
 import {
   getEnvironment,
   readEphemeralState
-} from "./chunk-DGSF2Q5H.js";
+} from "./chunk-WJYB7DSI.js";
 import {
   sandboxBaseUrl
-} from "./chunk-7DKX2SPN.js";
+} from "./chunk-OR43PDCW.js";
 import {
   fetchReadOrExplain,
   httpFailure
@@ -66,7 +66,7 @@ async function resolveMetaTarget(auth, opts, deps = {}) {
     case "sandbox":
       return resolveSandbox(auth);
     case "ephemeral": {
-      const resolveLive = deps.resolveLive ?? (await import("./ephemeral-command-JL4TPIRQ.js")).resolveLive;
+      const resolveLive = deps.resolveLive ?? (await import("./ephemeral-command-46SL27GJ.js")).resolveLive;
       return resolveEphemeral(auth, opts.name, { ...deps, resolveLive });
     }
   }
@@ -75,4 +75,4 @@ async function resolveMetaTarget(auth, opts, deps = {}) {
 export {
   resolveMetaTarget
 };
-//# sourceMappingURL=chunk-BT2CSEC5.js.map
+//# sourceMappingURL=chunk-APOR6TCV.js.map

package/dist/{chunk-55VHDNW5.js → chunk-BPEEGJJA.js}

@@ -12,7 +12,7 @@ import {
   middlewareEntryGuid,
   stackReferencesAuth,
   tableColumns
-} from "./chunk-5L4X5LS6.js";
+} from "./chunk-YUPQOLFX.js";
 import {
   CANONICAL_PAYLOAD_KEYS,
   REFERENCEABLE_KINDS,
@@ -23,7 +23,7 @@ import {
   mintCanonical,
   recordObserved,
   resolveRef
-} from "./chunk-4HT3BNZ7.js";
+} from "./chunk-YUBJLB6G.js";
 
 // src/workspace/seed-coerce.ts
 function coerceScalarValue(label, column, type, value, values) {
@@ -1108,6 +1108,60 @@ function checkRunFamilyHosts(sections, bag) {
     }
   }
 }
+var KNOWLEDGE_NAME_OK = /^[A-Za-z0-9/_\-{}. ]+$/;
+var KNOWLEDGE_NAME_MAX = 200;
+function checkKnowledge(sections, bag, opts) {
+  const items = sections.knowledge ?? [];
+  if (items.length === 0) return;
+  const agentsMd = items.filter((i) => i.knowledge_type === "agents.md");
+  if (agentsMd.length > 1) {
+    bag.error(
+      "knowledge.multiple-agents-md",
+      `A workspace can have at most one \`type: "agents.md"\` knowledge item, and this one declares ${agentsMd.length}: ${agentsMd.map((i) => `"${i.name}"`).join(", ")}. AGENTS.md is the workspace's standing instructions \u2014 merge them into one item, or make the others \`type: "skill"\`.`
+    );
+  }
+  for (const item of items) {
+    const name = String(item.name ?? "");
+    const label = `knowledge "${name}"`;
+    if (name.length > KNOWLEDGE_NAME_MAX) {
+      bag.error(
+        "knowledge.name-too-long",
+        `${label}: name is ${name.length} characters; the platform accepts at most ${KNOWLEDGE_NAME_MAX}.`
+      );
+    } else if (!KNOWLEDGE_NAME_OK.test(name)) {
+      const bad = [...name].filter((c) => !KNOWLEDGE_NAME_OK.test(c));
+      bag.error(
+        "knowledge.name-charset",
+        `${label}: name contains ${bad.map((c) => JSON.stringify(c)).join(", ")}. The platform accepts the deploy and then silently DROPS the item \u2014 the agent ends up with no such knowledge and nothing reports an error. Names may use letters, digits, and \`/ _ - { } . \` or a space.`
+      );
+    }
+    if (item.knowledge_type === "agents.md" && item.mode !== "auto") {
+      bag.warn(
+        "knowledge.agents-md-mode",
+        `${label}: \`mode: "${item.mode}"\` has no effect on an \`agents.md\` item \u2014 its body is injected in full on every turn regardless. Drop \`mode\`, or make this a \`skill\` if you wanted the item loaded on demand.`
+      );
+    }
+    for (const [field, value] of [
+      ["name", name],
+      ["description", String(item.description ?? "")]
+    ]) {
+      if (value.includes("\n")) {
+        bag.warn(
+          "knowledge.newline",
+          `${label}: \`${field}\` contains a newline. It deploys, but the platform writes these into a line-oriented markdown header when a workspace is synced to files, and a newline does not survive that round trip.`
+        );
+      }
+    }
+    if (opts.resolved) {
+      if (String(item.content ?? "").trim() === "") {
+        bag.warn(
+          "knowledge.empty-body",
+          `${label}: the markdown body is empty. An enabled item still occupies a slot in the agent's menu and contributes nothing when loaded.`
+        );
+      }
+    }
+  }
+}
 
 // src/workspace/xano.ts
 var XANO_BRAND = /* @__PURE__ */ Symbol.for("xanots.Xano");
@@ -1118,6 +1172,7 @@ var Xano = class {
   sections = /* @__PURE__ */ new Map();
   /** Table defs, encoded lazily at {@link export} so each can inherit the workspace `use_xdo`. */
   tableDefs = [];
+  knowledgeDefs = [];
   workspaceConfig = {};
   bundleType = "workspace";
   /** True for any `Xano` registry, even one created by a different module instance. */
@@ -1146,6 +1201,9 @@ var Xano = class {
       for (const def of defs) this.tableDefs.push(def);
       return this;
     }
+    if (kind.name === "knowledge") {
+      for (const def of defs) this.knowledgeDefs.push(def);
+    }
     const bucket = this.sections.get(kind.payloadKey) ?? [];
     for (const def of defs) bucket.push(this.encodeOne(kind, def));
     this.sections.set(kind.payloadKey, bucket);
@@ -1200,6 +1258,35 @@ var Xano = class {
     this.workspaceConfig = encodeObject("workspace", withName);
     return this;
   }
+  /**
+   * Fill each encoded knowledge item's `content` and emit its reference files as
+   * the sibling `knowledge_file` section.
+   *
+   * Reference rows name their parent by GUID rather than by row id: the id does
+   * not exist until the import inserts the parent, and the importer resolves the
+   * guid back to it. `references` stays empty — the platform derives that list
+   * from the stored files itself, so anything written here is overwritten.
+   */
+  fillKnowledge(sections, resolved) {
+    const byName = new Map(resolved.map((r) => [r.name, r]));
+    const items = sections.knowledge ?? [];
+    const files = [];
+    for (const item of items) {
+      const match = byName.get(item.name);
+      if (match === void 0) continue;
+      item.content = match.content;
+      for (const file of match.files) {
+        files.push({
+          knowledge: { id: item.guid },
+          path: file.path,
+          content: file.content,
+          size: file.size,
+          guid: deriveGuid("knowledge_file", `${item.name}/${file.path}`)
+        });
+      }
+    }
+    if (files.length > 0) sections.knowledge_file = files;
+  }
   /** Set the bundle `type` (defaults to "workspace"). */
   setBundleType(type) {
     this.bundleType = type;
@@ -1214,9 +1301,23 @@ var Xano = class {
   tables() {
     return [...this.tableDefs];
   }
+  /**
+   * The registered knowledge defs (with their authored `body`/`refs` path
+   * markers), for the Node compile path to read markdown off disk. Deliberately
+   * NOT reached from `export()` — a file read has no place in the browser-safe
+   * bundle, so the encoder emits an empty `content` and the compile path fills
+   * it. See {@link import("./knowledge.js")}.
+   */
+  knowledge() {
+    return [...this.knowledgeDefs];
+  }
   registerFunctions(defs) {
     return this.register("function", defs);
   }
+  /** Register knowledge items — the markdown a workspace's AI agents read. */
+  registerKnowledge(defs) {
+    return this.register("knowledge", defs);
+  }
   registerTriggers(defs) {
     return this.register("trigger", defs);
   }
@@ -1294,6 +1395,9 @@ var Xano = class {
         return { ...encoded, import: { mode: "standard" } };
       });
     }
+    if (options.knowledge !== void 0 && options.knowledge.length > 0) {
+      this.fillKnowledge(sections, options.knowledge);
+    }
     const bag = new DiagnosticBag(options.strict === true);
     this.validateQueryAuth(sections, bag);
     this.validateMiddlewareAuth(sections, bag);
@@ -1315,6 +1419,7 @@ var Xano = class {
     checkNullMatchArgs(sections, bag);
     checkSameNameSiblings(sections, bag);
     checkSeed(this.tableDefs, bag);
+    checkKnowledge(sections, bag, { resolved: options.knowledge !== void 0 });
     checkRealtimePublish(this.bundleType, sections, bag);
     bag.flush();
     if (lockCtx) this.applyLock(lockCtx, sections);
@@ -1547,4 +1652,4 @@ export {
   Xano,
   workspace
 };
-//# sourceMappingURL=chunk-55VHDNW5.js.map
+//# sourceMappingURL=chunk-BPEEGJJA.js.map

package/dist/{chunk-U3G2UW65.js → chunk-CYJ7R3AD.js}

@@ -35,7 +35,7 @@ import {
   registerKind,
   tableColumns,
   withFilters
-} from "./chunk-5L4X5LS6.js";
+} from "./chunk-YUPQOLFX.js";
 import {
   assertPathParamInputs,
   fillPathParams,
@@ -51,7 +51,7 @@ import {
   deriveGuid,
   realtimeChannelSeedName,
   resolveRef
-} from "./chunk-4HT3BNZ7.js";
+} from "./chunk-YUBJLB6G.js";
 
 // src/statements/set-var.ts
 var SET_VAR = "mvp:set_var";
@@ -3721,4 +3721,4 @@ export {
   workspaceKind,
   workspaceConfig
 };
-//# sourceMappingURL=chunk-U3G2UW65.js.map
+//# sourceMappingURL=chunk-CYJ7R3AD.js.map

package/dist/{agent-file-refresh-6M5M7T24.js → chunk-D6OGU2AI.js}

@@ -5,9 +5,7 @@ import {
   presetFilePath,
   renderPreset,
   upsertManagedBlock
-} from "./chunk-CMZLPTGW.js";
-import "./chunk-WUSKBXXD.js";
-import "./chunk-6DHJVLYP.js";
+} from "./chunk-7SISR3CS.js";
 import {
   warn
 } from "./chunk-EZG76F7R.js";
@@ -50,7 +48,7 @@ function appNameFor(projectDir) {
 }
 function refreshAgentFiles(opts) {
   const env = opts.env ?? process.env;
-  if (isCI(env) || !codingAgentDetected(env)) return [];
+  if (opts.explicit !== true && (isCI(env) || !codingAgentDetected(env))) return [];
   const mode = opts.mode ?? guidanceModeFor(opts.projectDir);
   const appName = opts.appName ?? appNameFor(opts.projectDir);
   const managed = [];
@@ -87,10 +85,11 @@ function refreshAgentFiles(opts) {
   }
   return refreshed;
 }
+
 export {
-  CI_ENV_VARS,
   codingAgentDetected,
+  CI_ENV_VARS,
   isCI,
   refreshAgentFiles
 };
-//# sourceMappingURL=agent-file-refresh-6M5M7T24.js.map
+//# sourceMappingURL=chunk-D6OGU2AI.js.map