@construct-space/cli 1.6.0 → 1.6.3

package/dist/index.js

@@ -5354,7 +5354,7 @@ async function scaffold(nameArg, options) {
 // src/commands/build.ts
 init_source();
 import { existsSync as existsSync6, readFileSync as readFileSync4, readdirSync as readdirSync3, renameSync, statSync as statSync3 } from "fs";
-import { join as join6 } from "path";
+import { extname as extname3, join as join6 } from "path";
 import { createHash } from "crypto";
 
 // node_modules/ora/index.js
@@ -8026,6 +8026,11 @@ function readRaw(dir) {
   const data = readFileSync2(path, "utf-8");
   return JSON.parse(data);
 }
+function write(dir, m) {
+  const path = join3(dir, MANIFEST_FILE);
+  writeFileSync2(path, JSON.stringify(m, null, 2) + `
+`);
+}
 function writeWithBuild(dir, raw, build) {
   raw.build = build;
   writeFileSync2(join3(dir, "manifest.json"), JSON.stringify(raw, null, 2) + `
@@ -8109,7 +8114,7 @@ function resolvePages(m, root, prefix) {
     if (existsSync4(legacyFullPath)) {
       let varName = "IndexPage";
       if (p.path) {
-        varName = capitalize(p.path.replace(/[\/:]/g, "-").replace(/-+/g, "-")) + "Page";
+        varName = capitalize(p.path.replace(/\[([^\]]+)\]/g, "$1").replace(/[\/:]/g, "-").replace(/-+/g, "-")) + "Page";
       }
       return { varName, importPath: prefix + legacyComponent, path: p.path };
     }
@@ -8243,41 +8248,245 @@ function bundleAgentDir(srcDir, distDir) {
 }
 
 // src/commands/build.ts
+function stripComments(source) {
+  let out = "";
+  let i = 0;
+  let quote = null;
+  let escaped = false;
+  while (i < source.length) {
+    const ch = source[i];
+    const next = source[i + 1];
+    if (quote) {
+      out += ch;
+      if (escaped) {
+        escaped = false;
+      } else if (ch === "\\") {
+        escaped = true;
+      } else if (ch === quote) {
+        quote = null;
+      }
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      out += ch;
+      i++;
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      while (i < source.length && source[i] !== `
+`) {
+        out += " ";
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      out += "  ";
+      i += 2;
+      while (i < source.length && !(source[i] === "*" && source[i + 1] === "/")) {
+        out += source[i] === `
+` ? `
+` : " ";
+        i++;
+      }
+      if (i < source.length) {
+        out += "  ";
+        i += 2;
+      }
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out;
+}
+function findMatchingBrace(source, openIndex) {
+  let depth = 0;
+  let quote = null;
+  let escaped = false;
+  for (let i = openIndex;i < source.length; i++) {
+    const ch = source[i];
+    if (quote) {
+      if (escaped)
+        escaped = false;
+      else if (ch === "\\")
+        escaped = true;
+      else if (ch === quote)
+        quote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "{")
+      depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0)
+        return i;
+    }
+  }
+  return -1;
+}
+function objectLiteralAfter(source, start) {
+  const open = source.indexOf("{", start);
+  if (open < 0)
+    return null;
+  const close = findMatchingBrace(source, open);
+  if (close < 0)
+    return null;
+  return source.slice(open + 1, close);
+}
+function actionsObject(source) {
+  const stripped = stripComments(source);
+  const match = /export\s+const\s+actions\s*=/.exec(stripped);
+  if (!match)
+    return null;
+  return objectLiteralAfter(stripped, match.index + match[0].length);
+}
+function objectEntries(body) {
+  const entries = [];
+  let i = 0;
+  while (i < body.length) {
+    const match = /\s*,?\s*([A-Za-z_$][\w$]*)\s*:/.exec(body.slice(i));
+    if (!match)
+      break;
+    const name = match[1];
+    const valueStart = i + match.index + match[0].length;
+    const open = body.indexOf("{", valueStart);
+    if (open < 0)
+      break;
+    if (body.slice(valueStart, open).trim()) {
+      i = valueStart;
+      continue;
+    }
+    const close = findMatchingBrace(body, open);
+    if (close < 0)
+      break;
+    entries.push({ name, body: body.slice(open + 1, close) });
+    i = close + 1;
+  }
+  return entries;
+}
+function stringProperty(body, name) {
+  const match = new RegExp(`${name}\\s*:\\s*['"\`]([^'"\`]*)['"\`]`).exec(body);
+  return match?.[1];
+}
+function booleanProperty(body, name) {
+  const match = new RegExp(`${name}\\s*:\\s*(true|false)`).exec(body);
+  if (!match)
+    return;
+  return match[1] === "true";
+}
+function propertyObject(body, name) {
+  const match = new RegExp(`${name}\\s*:`).exec(body);
+  if (!match)
+    return null;
+  return objectLiteralAfter(body, match.index + match[0].length);
+}
 function extractActionMetadata(actionsPath) {
   try {
-    const source = readFileSync4(actionsPath, "utf-8");
+    const actionsBody = actionsObject(readFileSync4(actionsPath, "utf-8"));
+    if (!actionsBody)
+      return null;
     const result = {};
-    const actionPattern = /(\w+)\s*:\s*\{[^}]*description\s*:\s*['"`]([^'"`]+)['"`]/g;
-    let match;
-    while ((match = actionPattern.exec(source)) !== null) {
-      const actionId = match[1];
-      const description = match[2];
-      result[actionId] = { description };
-    }
-    for (const actionId of Object.keys(result)) {
-      const paramBlockPattern = new RegExp(`${actionId}\\s*:\\s*\\{[\\s\\S]*?params\\s*:\\s*\\{([\\s\\S]*?)\\}\\s*,?\\s*(?:run|\\})`);
-      const paramMatch = source.match(paramBlockPattern);
-      if (paramMatch?.[1]) {
+    for (const action of objectEntries(actionsBody)) {
+      const description = stringProperty(action.body, "description");
+      if (!description)
+        continue;
+      const metadata = { description };
+      const paramsBody = propertyObject(action.body, "params");
+      if (paramsBody) {
         const params = {};
-        const paramEntryPattern = /(\w+)\s*:\s*\{\s*type\s*:\s*['"`](\w+)['"`](?:\s*,\s*description\s*:\s*['"`]([^'"`]*)['"`])?(?:\s*,\s*required\s*:\s*(true|false))?\s*\}/g;
-        let pm;
-        while ((pm = paramEntryPattern.exec(paramMatch[1])) !== null) {
-          params[pm[1]] = {
-            type: pm[2],
-            ...pm[3] ? { description: pm[3] } : {},
-            ...pm[4] === "true" ? { required: true } : {}
+        for (const param of objectEntries(paramsBody)) {
+          const type = stringProperty(param.body, "type");
+          if (!type)
+            continue;
+          const required = booleanProperty(param.body, "required");
+          params[param.name] = {
+            type,
+            ...stringProperty(param.body, "description") ? { description: stringProperty(param.body, "description") } : {},
+            ...required === true ? { required: true } : {}
           };
         }
-        if (Object.keys(params).length > 0) {
-          result[actionId].params = params;
-        }
+        if (Object.keys(params).length > 0)
+          metadata.params = params;
       }
+      result[action.name] = metadata;
     }
     return Object.keys(result).length > 0 ? result : null;
   } catch {
     return null;
   }
 }
+var ICON_MIME = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".ico": "image/x-icon"
+};
+function isInlineableIcon(value) {
+  if (typeof value !== "string" || !value)
+    return false;
+  if (value.startsWith("i-") || value.startsWith("lucide:"))
+    return false;
+  if (value.startsWith("data:"))
+    return false;
+  if (/^https?:\/\//.test(value))
+    return false;
+  return extname3(value).toLowerCase() in ICON_MIME;
+}
+function resolveIconPath(root, ref) {
+  const rel = ref.replace(/^\.?\//, "");
+  for (const candidate of [join6(root, rel), join6(root, "src", rel)]) {
+    if (existsSync6(candidate))
+      return candidate;
+  }
+  return null;
+}
+function inlineIcon(root, ref) {
+  const abs = resolveIconPath(root, ref);
+  if (!abs)
+    return null;
+  const mime = ICON_MIME[extname3(abs).toLowerCase()] || "application/octet-stream";
+  const b64 = readFileSync4(abs).toString("base64");
+  return `data:${mime};base64,${b64}`;
+}
+function inlineManifestIcons(root, raw) {
+  if (isInlineableIcon(raw.icon)) {
+    const data = inlineIcon(root, raw.icon);
+    if (data)
+      raw.icon = data;
+    else
+      console.warn(source_default.yellow(`  Icon not found: ${raw.icon}`));
+  }
+  const nav = raw.navigation;
+  if (nav && isInlineableIcon(nav.icon)) {
+    const data = inlineIcon(root, nav.icon);
+    if (data)
+      nav.icon = data;
+    else
+      console.warn(source_default.yellow(`  navigation.icon not found: ${nav.icon}`));
+  }
+  const pages = raw.pages;
+  if (Array.isArray(pages)) {
+    for (const p of pages) {
+      if (isInlineableIcon(p.icon)) {
+        const data = inlineIcon(root, p.icon);
+        if (data)
+          p.icon = data;
+        else
+          console.warn(source_default.yellow(`  page icon not found: ${p.icon}`));
+      }
+    }
+  }
+}
 async function build(options) {
   const root = process.cwd();
   if (!exists(root)) {
@@ -8326,6 +8535,7 @@ async function build(options) {
   const bundleData = readFileSync4(bundlePath);
   const checksum = createHash("sha256").update(bundleData).digest("hex");
   const raw = readRaw(root);
+  inlineManifestIcons(root, raw);
   const actionsPath = join6(root, "src", "actions.ts");
   if (existsSync6(actionsPath)) {
     const actionMeta = extractActionMetadata(actionsPath);
@@ -10319,6 +10529,22 @@ async function publish(options) {
 init_source();
 import { existsSync as existsSync12, readFileSync as readFileSync9 } from "fs";
 import { join as join15 } from "path";
+
+// src/lib/pagePaths.ts
+function pageComponentFromPath(path) {
+  const clean = path.replace(/^\/+|\/+$/g, "");
+  if (!clean)
+    return "pages/index.vue";
+  const segments = clean.split("/").map((segment) => {
+    if (segment.startsWith(":") && segment.length > 1) {
+      return `[${segment.slice(1)}]`;
+    }
+    return segment;
+  });
+  return `pages/${segments.join("/")}.vue`;
+}
+
+// src/commands/validate.ts
 function validate3() {
   const root = process.cwd();
   if (!exists(root)) {
@@ -10335,7 +10561,7 @@ function validate3() {
   }
   let warnings = 0;
   for (const page of m.pages) {
-    const component = page.component || (page.path === "" ? "pages/index.vue" : `pages/${page.path}.vue`);
+    const component = page.component || pageComponentFromPath(page.path);
     const fullPath = join15(root, "src", component);
     if (!existsSync12(fullPath)) {
       console.log(source_default.yellow(`  \u26A0 Page component not found: src/${component}`));
@@ -10386,7 +10612,7 @@ function check() {
   }
   let warnings = 0;
   for (const page of m.pages) {
-    const component = page.component || (page.path === "" ? "pages/index.vue" : `pages/${page.path}.vue`);
+    const component = page.component || pageComponentFromPath(page.path);
     if (!existsSync13(join16(root, "src", component))) {
       console.log(source_default.yellow(`  \u26A0 Page not found: src/${component}`));
       warnings++;
@@ -10949,6 +11175,33 @@ async function graphPush() {
     process.exit(1);
   }
 }
+function parseDefaultValue(raw) {
+  const value = raw.trim();
+  try {
+    return JSON.parse(value);
+  } catch {}
+  const quote = value[0];
+  if ((quote === "'" || quote === '"') && value.endsWith(quote)) {
+    return value.slice(1, -1).replace(/\\(['"\\bfnrt])/g, (_, ch) => {
+      switch (ch) {
+        case "b":
+          return "\b";
+        case "f":
+          return "\f";
+        case "n":
+          return `
+`;
+        case "r":
+          return "\r";
+        case "t":
+          return "\t";
+        default:
+          return ch;
+      }
+    });
+  }
+  return value;
+}
 function parseModelFile(content, fileName) {
   const modelMatch = content.match(/defineModel\s*\(\s*['"](\w+)['"]/);
   if (!modelMatch)
@@ -10976,11 +11229,7 @@ function parseModelFile(content, fileName) {
         field.validation = "url";
       const defaultMatch = modifiers.match(/\.default\((.+?)\)/);
       if (defaultMatch) {
-        try {
-          field.default = JSON.parse(defaultMatch[1]);
-        } catch {
-          field.default = defaultMatch[1];
-        }
+        field.default = parseDefaultValue(defaultMatch[1]);
       }
     }
     fields.push(field);
@@ -11162,10 +11411,41 @@ function parseModelFields(content, fileName) {
   }
   return { name: modelMatch[1], fields };
 }
+
+// src/commands/graph/fork.ts
+init_source();
+var spaceIDRegex = /^[a-z][a-z0-9-]*$/;
+function forkManifest(root, newSpaceID) {
+  const id = newSpaceID.trim();
+  if (!spaceIDRegex.test(id)) {
+    throw new Error("space id must be lowercase alphanumeric with hyphens, starting with a letter");
+  }
+  if (!exists(root)) {
+    throw new Error("No space.manifest.json found in current directory");
+  }
+  const m = read(root);
+  if (m.id === id) {
+    throw new Error(`space.manifest.json already uses id "${id}"`);
+  }
+  const oldSpaceID = m.id;
+  m.id = id;
+  write(root, m);
+  return { oldSpaceID, newSpaceID: id };
+}
+function graphFork(newSpaceID) {
+  try {
+    const result = forkManifest(process.cwd(), newSpaceID);
+    console.log(source_default.green(`Forked graph space id: ${result.oldSpaceID} -> ${result.newSpaceID}`));
+    console.log(source_default.dim("Run `construct graph push` to register the forked schema."));
+  } catch (err) {
+    console.error(source_default.red(err.message));
+    process.exit(1);
+  }
+}
 // package.json
 var package_default = {
   name: "@construct-space/cli",
-  version: "1.6.0",
+  version: "1.6.3",
   description: "Construct CLI \u2014 scaffold, build, develop, and publish spaces",
   type: "module",
   bin: {
@@ -11229,6 +11509,7 @@ var graph = program2.command("graph").description("Construct Graph \u2014 data m
 graph.command("init").description("Initialize Graph in a space project").action(() => graphInit());
 graph.command("generate <model> [fields...]").alias("g").description("Generate a data model").option("--access <rules>", "Access rules (e.g. read:member,create:member,update:owner,delete:admin)").action((model, fields, opts) => generate2(model, fields, opts));
 graph.command("push").description("Register models with the Graph service").action(async () => graphPush());
+graph.command("fork <new-space-id>").description("Rewrite this space manifest to a new graph space id").action((newSpaceID) => graphFork(newSpaceID));
 graph.command("migrate").description("Compare local models with server schema and apply changes").option("--apply", "Apply destructive changes (drop columns, alter constraints)").action(async (opts) => graphMigrate(opts));
 graph.command("spaces").alias("list").alias("ls").description("List spaces published by your org").option("--org <id>", "Override org id").option("--bundle <id>", "Filter to a single bundle").option("--json", "Output JSON").action(async (opts) => (await Promise.resolve().then(() => (init_spaces(), exports_spaces))).spacesList(opts));
 var bundles = graph.command("bundles").description("Manage space bundles (publisher grouping)");

package/dist/templates/space/construct.md.tmpl

@@ -100,6 +100,17 @@ All exported from the package root:
 
 **Composables**: `useNotification`, `notify`, `useAuth`, `useTheme`, `useClipboard`, `useMediaQuery`, `useFormValidation`, `useKeyboard`/`useHotkey`, `useClickOutside`, `useEscapeKey`, `useLocalStorage`, `useAsync`, `useDebounce`/`useThrottle`, `useToggle`, `useSearch`, `useIntersectionObserver`
 
+### Component gotchas
+
+- **`Avatar` sizes**: only `sm | md | lg` (no `xs`).
+- **`Select`** doesn't accept `multiple` — render a chip-toggle list yourself for multi-select.
+- **`Table`** column `align` literals must be `as const` to typecheck (`align: 'right' as const`).
+- **`Table` rowKey** is a string field name on the row object, not a function.
+- **`Modal`** uses `v-model:open` (not `v-model`); slots: `header | body | footer | accessory`.
+- **`Card`** slots: `header | accessory | default | footer | footer-end`. Use `title`/`description` props for the header to get standard styling; put right-side actions in `accessory`.
+- **`ConfirmationModal`** emits `@confirm` and `@cancel` — wire both, otherwise dismissal does nothing.
+- **Settings pages**: never raw `<select>`/`<input>`/`<textarea>` — use `Select`, `Switch`, `Input`, `Textarea` with `FormField` labels. Persist with `localStorage` (key prefix per space).
+
 ```vue
 <script setup lang="ts">
 import { Card, Button, Modal, Badge } from '@construct-space/ui'
@@ -185,15 +196,26 @@ await tasks.remove(id)
 
 ### Pitfalls
 
-- **`field.json()` columns** must receive a JSON-stringified value on write: `labels: JSON.stringify(arr)`. On read, parse back if it returns a string. Sending a JS array directly triggers `column is of type jsonb but expression is of type record`.
+- **`field.json()` columns** must receive a JSON-stringified value on write: `labels: JSON.stringify(arr)`. On read, parse back if it returns a string. Sending a JS array directly triggers `column is of type jsonb but expression is of type record`. Pattern:
+  ```ts
+  function parseLabels(raw: unknown): string[] {
+    if (Array.isArray(raw)) return raw as string[]
+    if (typeof raw === 'string' && raw.trim()) {
+      try { const v = JSON.parse(raw); return Array.isArray(v) ? v : [] } catch { return [] }
+    }
+    return []
+  }
+  ```
 - **Topological sort on push**: avoid `relation.belongsTo()` if push fails — use a `field.string()` foreign-key column instead and join manually in composables.
 - **Lazy provisioning**: first query for a new tenant auto-creates the schema; expect a one-time slower request.
+- **Schema ownership is sticky**: the first profile to `construct graph push` becomes the schema owner. Subsequent pushes from a different profile fail with "Ownership check failed". Bump the space `id` to fork, or push from the original owner profile.
+- **`access.member()` requires org context** — use `access.authenticated()` for org-scoped models that any logged-in member should be able to read/write. `member()` is for stricter membership checks.
 
 ---
 
 ## Actions (agent surface)
 
-`src/actions.ts` exports an `actions` object — each entry becomes an agent-callable tool via `space_run_action`.
+`src/actions.ts` exports an `actions` object — each entry is exposed to the space's agent as a first-class tool.
 
 ```ts
 export const actions = {
@@ -208,7 +230,24 @@ export const actions = {
 }
 ```
 
-The agent (configured in `agent/config.md`) calls `space_list_actions` then `space_run_action`. Keep descriptions tight and specific — they're the only docstring the agent sees.
+### Wiring (REQUIRED — easy to miss)
+
+Each action becomes a tool named **`{spaceID}.{actionName}`** (dot, not underscore). The operator only pre-registers actions that are **explicitly whitelisted** in the agent config. An empty `tools: []` means the agent sees zero action tools and will report "unknown tool".
+
+```yaml
+# agent/config.md frontmatter
+---
+id: {{.ID}}
+tools:
+  - {{.ID}}.createTask
+  - {{.ID}}.listTasks
+  - {{.ID}}.updateTask
+---
+```
+
+Fallback: agents can also discover/invoke actions via the generic `space_list_actions` + `space_run_action` bridge tools. Prefer the whitelist — it gives the model proper tool definitions instead of stringly-typed action names.
+
+Keep action descriptions tight and specific — they're the only docstring the agent sees.
 
 ---
 

package/dist/templates/space/package.json.tmpl

@@ -25,12 +25,12 @@
     "eslint-plugin-vue": "^10.0.0",
     "lucide-vue-next": "^1.0.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^9.0.0",
+    "typescript-eslint": "^8.0.0",
     "vite": "^6.3.5",
     "vue-tsc": "^3.2.5"
   },
   "dependencies": {
-    "@construct-space/graph": "^0.5.0",
-    "@construct-space/ui": "^0.5.2"
+    "@construct-space/graph": "^0.6.2",
+    "@construct-space/ui": "^0.6.1"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@construct-space/cli",
-  "version": "1.6.0",
+  "version": "1.6.3",
   "description": "Construct CLI — scaffold, build, develop, and publish spaces",
   "type": "module",
   "bin": {

package/templates/space/construct.md.tmpl

@@ -100,6 +100,17 @@ All exported from the package root:
 
 **Composables**: `useNotification`, `notify`, `useAuth`, `useTheme`, `useClipboard`, `useMediaQuery`, `useFormValidation`, `useKeyboard`/`useHotkey`, `useClickOutside`, `useEscapeKey`, `useLocalStorage`, `useAsync`, `useDebounce`/`useThrottle`, `useToggle`, `useSearch`, `useIntersectionObserver`
 
+### Component gotchas
+
+- **`Avatar` sizes**: only `sm | md | lg` (no `xs`).
+- **`Select`** doesn't accept `multiple` — render a chip-toggle list yourself for multi-select.
+- **`Table`** column `align` literals must be `as const` to typecheck (`align: 'right' as const`).
+- **`Table` rowKey** is a string field name on the row object, not a function.
+- **`Modal`** uses `v-model:open` (not `v-model`); slots: `header | body | footer | accessory`.
+- **`Card`** slots: `header | accessory | default | footer | footer-end`. Use `title`/`description` props for the header to get standard styling; put right-side actions in `accessory`.
+- **`ConfirmationModal`** emits `@confirm` and `@cancel` — wire both, otherwise dismissal does nothing.
+- **Settings pages**: never raw `<select>`/`<input>`/`<textarea>` — use `Select`, `Switch`, `Input`, `Textarea` with `FormField` labels. Persist with `localStorage` (key prefix per space).
+
 ```vue
 <script setup lang="ts">
 import { Card, Button, Modal, Badge } from '@construct-space/ui'
@@ -185,15 +196,26 @@ await tasks.remove(id)
 
 ### Pitfalls
 
-- **`field.json()` columns** must receive a JSON-stringified value on write: `labels: JSON.stringify(arr)`. On read, parse back if it returns a string. Sending a JS array directly triggers `column is of type jsonb but expression is of type record`.
+- **`field.json()` columns** must receive a JSON-stringified value on write: `labels: JSON.stringify(arr)`. On read, parse back if it returns a string. Sending a JS array directly triggers `column is of type jsonb but expression is of type record`. Pattern:
+  ```ts
+  function parseLabels(raw: unknown): string[] {
+    if (Array.isArray(raw)) return raw as string[]
+    if (typeof raw === 'string' && raw.trim()) {
+      try { const v = JSON.parse(raw); return Array.isArray(v) ? v : [] } catch { return [] }
+    }
+    return []
+  }
+  ```
 - **Topological sort on push**: avoid `relation.belongsTo()` if push fails — use a `field.string()` foreign-key column instead and join manually in composables.
 - **Lazy provisioning**: first query for a new tenant auto-creates the schema; expect a one-time slower request.
+- **Schema ownership is sticky**: the first profile to `construct graph push` becomes the schema owner. Subsequent pushes from a different profile fail with "Ownership check failed". Bump the space `id` to fork, or push from the original owner profile.
+- **`access.member()` requires org context** — use `access.authenticated()` for org-scoped models that any logged-in member should be able to read/write. `member()` is for stricter membership checks.
 
 ---
 
 ## Actions (agent surface)
 
-`src/actions.ts` exports an `actions` object — each entry becomes an agent-callable tool via `space_run_action`.
+`src/actions.ts` exports an `actions` object — each entry is exposed to the space's agent as a first-class tool.
 
 ```ts
 export const actions = {
@@ -208,7 +230,24 @@ export const actions = {
 }
 ```
 
-The agent (configured in `agent/config.md`) calls `space_list_actions` then `space_run_action`. Keep descriptions tight and specific — they're the only docstring the agent sees.
+### Wiring (REQUIRED — easy to miss)
+
+Each action becomes a tool named **`{spaceID}.{actionName}`** (dot, not underscore). The operator only pre-registers actions that are **explicitly whitelisted** in the agent config. An empty `tools: []` means the agent sees zero action tools and will report "unknown tool".
+
+```yaml
+# agent/config.md frontmatter
+---
+id: {{.ID}}
+tools:
+  - {{.ID}}.createTask
+  - {{.ID}}.listTasks
+  - {{.ID}}.updateTask
+---
+```
+
+Fallback: agents can also discover/invoke actions via the generic `space_list_actions` + `space_run_action` bridge tools. Prefer the whitelist — it gives the model proper tool definitions instead of stringly-typed action names.
+
+Keep action descriptions tight and specific — they're the only docstring the agent sees.
 
 ---
 

package/templates/space/package.json.tmpl

@@ -25,12 +25,12 @@
     "eslint-plugin-vue": "^10.0.0",
     "lucide-vue-next": "^1.0.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^9.0.0",
+    "typescript-eslint": "^8.0.0",
     "vite": "^6.3.5",
     "vue-tsc": "^3.2.5"
   },
   "dependencies": {
-    "@construct-space/graph": "^0.5.0",
-    "@construct-space/ui": "^0.5.2"
+    "@construct-space/graph": "^0.6.2",
+    "@construct-space/ui": "^0.6.1"
   }
 }