@construct-space/cli 1.7.7 → 1.8.0

package/dist/index.js

@@ -8527,16 +8527,16 @@ import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
 import { join as join9 } from "path";
 import { createHash as createHash2 } from "crypto";
 
-// node_modules/chokidar/index.js
+// node_modules/chokidar/esm/index.js
+import { stat as statcb } from "fs";
+import { stat as stat3, readdir as readdir2 } from "fs/promises";
 import { EventEmitter } from "events";
-import { stat as statcb, Stats } from "fs";
-import { readdir as readdir2, stat as stat3 } from "fs/promises";
-import * as sp2 from "path";
+import * as sysPath2 from "path";
 
-// node_modules/readdirp/index.js
-import { lstat, readdir, realpath, stat } from "fs/promises";
-import { join as pjoin, relative as prelative, resolve as presolve, sep as psep } from "path";
+// node_modules/readdirp/esm/index.js
+import { stat, lstat, readdir, realpath } from "fs/promises";
 import { Readable } from "stream";
+import { resolve as presolve, relative as prelative, join as pjoin, sep as psep } from "path";
 var EntryTypes = {
   FILE_TYPE: "files",
   DIR_TYPE: "directories",
@@ -8592,20 +8592,6 @@ var normalizeFilter = (filter) => {
 };
 
 class ReaddirpStream extends Readable {
-  parents;
-  reading;
-  parent;
-  _stat;
-  _maxDepth;
-  _wantsDir;
-  _wantsFile;
-  _wantsEverything;
-  _root;
-  _isDirent;
-  _statsProp;
-  _rdOptions;
-  _fileFilter;
-  _directoryFilter;
   constructor(options = {}) {
     super({
       objectMode: true,
@@ -8622,7 +8608,7 @@ class ReaddirpStream extends Readable {
     } else {
       this._stat = statMethod;
     }
-    this._maxDepth = opts.depth != null && Number.isSafeInteger(opts.depth) ? opts.depth : defaultOptions.depth;
+    this._maxDepth = opts.depth ?? defaultOptions.depth;
     this._wantsDir = type ? DIR_TYPES.has(type) : false;
     this._wantsFile = type ? FILE_TYPES.has(type) : false;
     this._wantsEverything = type === EntryTypes.EVERYTHING_TYPE;
@@ -8767,11 +8753,11 @@ function readdirp(root, options = {}) {
   return new ReaddirpStream(options);
 }
 
-// node_modules/chokidar/handler.js
-import { watch as fs_watch, unwatchFile, watchFile } from "fs";
-import { realpath as fsrealpath, lstat as lstat2, open, stat as stat2 } from "fs/promises";
+// node_modules/chokidar/esm/handler.js
+import { watchFile, unwatchFile, watch as fs_watch } from "fs";
+import { open, stat as stat2, lstat as lstat2, realpath as fsrealpath } from "fs/promises";
+import * as sysPath from "path";
 import { type as osType } from "os";
-import * as sp from "path";
 var STR_DATA = "data";
 var STR_END = "end";
 var STR_CLOSE = "close";
@@ -9063,7 +9049,7 @@ var binaryExtensions = new Set([
   "zip",
   "zipx"
 ]);
-var isBinaryPath = (filePath) => binaryExtensions.has(sp.extname(filePath).slice(1).toLowerCase());
+var isBinaryPath = (filePath) => binaryExtensions.has(sysPath.extname(filePath).slice(1).toLowerCase());
 var foreach = (val, fn) => {
   if (val instanceof Set) {
     val.forEach(fn);
@@ -9101,7 +9087,7 @@ function createFsWatchInstance(path, options, listener, errHandler, emitRaw) {
     listener(path);
     emitRaw(rawEvent, evPath, { watchedPath: path });
     if (evPath && path !== evPath) {
-      fsWatchBroadcast(sp.resolve(path, evPath), KEY_LISTENERS, sp.join(path, evPath));
+      fsWatchBroadcast(sysPath.resolve(path, evPath), KEY_LISTENERS, sysPath.join(path, evPath));
     }
   };
   try {
@@ -9216,19 +9202,17 @@ var setFsWatchFileListener = (path, fullPath, options, handlers) => {
 };
 
 class NodeFsHandler {
-  fsw;
-  _boundHandleError;
   constructor(fsW) {
     this.fsw = fsW;
     this._boundHandleError = (error2) => fsW._handleError(error2);
   }
   _watchWithNodeFs(path, listener) {
     const opts = this.fsw.options;
-    const directory = sp.dirname(path);
-    const basename4 = sp.basename(path);
+    const directory = sysPath.dirname(path);
+    const basename4 = sysPath.basename(path);
     const parent = this.fsw._getWatchedDir(directory);
     parent.add(basename4);
-    const absolutePath = sp.resolve(path);
+    const absolutePath = sysPath.resolve(path);
     const options = {
       persistent: opts.persistent
     };
@@ -9255,8 +9239,8 @@ class NodeFsHandler {
     if (this.fsw.closed) {
       return;
     }
-    const dirname3 = sp.dirname(file);
-    const basename4 = sp.basename(file);
+    const dirname3 = sysPath.dirname(file);
+    const basename4 = sysPath.basename(file);
     const parent = this.fsw._getWatchedDir(dirname3);
     let prevStats = stats;
     if (parent.has(basename4))
@@ -9339,9 +9323,8 @@ class NodeFsHandler {
     this.fsw._symlinkPaths.set(full, true);
   }
   _handleRead(directory, initialAdd, wh, target, dir, depth, throttler) {
-    directory = sp.join(directory, "");
-    const throttleKey = target ? `${directory}:${target}` : directory;
-    throttler = this.fsw._throttle("readdir", throttleKey, 1000);
+    directory = sysPath.join(directory, "");
+    throttler = this.fsw._throttle("readdir", directory, 1000);
     if (!throttler)
       return;
     const previous = this.fsw._getWatchedDir(wh.path);
@@ -9358,7 +9341,7 @@ class NodeFsHandler {
         return;
       }
       const item = entry.path;
-      let path = sp.join(directory, item);
+      let path = sysPath.join(directory, item);
       current.add(item);
       if (entry.stats.isSymbolicLink() && await this._handleSymlink(entry, directory, path, item)) {
         return;
@@ -9369,7 +9352,7 @@ class NodeFsHandler {
       }
       if (item === target || !target && !previous.has(item)) {
         this.fsw._incrReadyCount();
-        path = sp.join(dir, sp.relative(dir, path));
+        path = sysPath.join(dir, sysPath.relative(dir, path));
         this._addToNodeFs(path, initialAdd, wh, depth + 1);
       }
     }).on(EV.ERROR, this._boundHandleError);
@@ -9395,12 +9378,12 @@ class NodeFsHandler {
     });
   }
   async _handleDir(dir, stats, initialAdd, depth, target, wh, realpath2) {
-    const parentDir = this.fsw._getWatchedDir(sp.dirname(dir));
-    const tracked = parentDir.has(sp.basename(dir));
+    const parentDir = this.fsw._getWatchedDir(sysPath.dirname(dir));
+    const tracked = parentDir.has(sysPath.basename(dir));
     if (!(initialAdd && this.fsw.options.ignoreInitial) && !target && !tracked) {
       this.fsw._emit(EV.ADD_DIR, dir, stats);
     }
-    parentDir.add(sp.basename(dir));
+    parentDir.add(sysPath.basename(dir));
     this.fsw._getWatchedDir(dir);
     let throttler;
     let closer;
@@ -9441,7 +9424,7 @@ class NodeFsHandler {
       const follow = this.fsw.options.followSymlinks;
       let closer;
       if (stats.isDirectory()) {
-        const absPath = sp.resolve(path);
+        const absPath = sysPath.resolve(path);
         const targetPath = follow ? await fsrealpath(path) : path;
         if (this.fsw.closed)
           return;
@@ -9455,14 +9438,14 @@ class NodeFsHandler {
         const targetPath = follow ? await fsrealpath(path) : path;
         if (this.fsw.closed)
           return;
-        const parent = sp.dirname(wh.watchPath);
+        const parent = sysPath.dirname(wh.watchPath);
         this.fsw._getWatchedDir(parent).add(wh.watchPath);
         this.fsw._emit(EV.ADD, wh.watchPath, stats);
         closer = await this._handleDir(parent, stats, initialAdd, depth, path, wh, targetPath);
         if (this.fsw.closed)
           return;
         if (targetPath !== undefined) {
-          this.fsw._symlinkPaths.set(sp.resolve(path), targetPath);
+          this.fsw._symlinkPaths.set(sysPath.resolve(path), targetPath);
         }
       } else {
         closer = this._handleFile(wh.watchPath, stats, initialAdd);
@@ -9480,7 +9463,7 @@ class NodeFsHandler {
   }
 }
 
-// node_modules/chokidar/index.js
+// node_modules/chokidar/esm/index.js
 /*! chokidar - MIT License (c) 2012 Paul Miller (paulmillr.com) */
 var SLASH = "/";
 var SLASH_SLASH = "//";
@@ -9488,7 +9471,7 @@ var ONE_DOT = ".";
 var TWO_DOTS = "..";
 var STRING_TYPE = "string";
 var BACK_SLASH_RE = /\\/g;
-var DOUBLE_SLASH_RE = /\/\//g;
+var DOUBLE_SLASH_RE = /\/\//;
 var DOT_RE = /\..*\.(sw[px])$|~$|\.subl.*\.tmp/;
 var REPLACER_RE = /^\.[/\\]/;
 function arrify(item) {
@@ -9507,11 +9490,11 @@ function createPattern(matcher) {
       if (matcher.path === string)
         return true;
       if (matcher.recursive) {
-        const relative4 = sp2.relative(matcher.path, string);
+        const relative4 = sysPath2.relative(matcher.path, string);
         if (!relative4) {
           return false;
         }
-        return !relative4.startsWith("..") && !sp2.isAbsolute(relative4);
+        return !relative4.startsWith("..") && !sysPath2.isAbsolute(relative4);
       }
       return false;
     };
@@ -9521,12 +9504,14 @@ function createPattern(matcher) {
 function normalizePath(path) {
   if (typeof path !== "string")
     throw new Error("string expected");
-  path = sp2.normalize(path);
+  path = sysPath2.normalize(path);
   path = path.replace(/\\/g, "/");
   let prepend = false;
   if (path.startsWith("//"))
     prepend = true;
-  path = path.replace(DOUBLE_SLASH_RE, "/");
+  const DOUBLE_SLASH_RE2 = /\/\//;
+  while (path.match(DOUBLE_SLASH_RE2))
+    path = path.replace(DOUBLE_SLASH_RE2, "/");
   if (prepend)
     path = "/" + path;
   return path;
@@ -9567,32 +9552,31 @@ var toUnix = (string) => {
   if (str.startsWith(SLASH_SLASH)) {
     prepend = true;
   }
-  str = str.replace(DOUBLE_SLASH_RE, SLASH);
+  while (str.match(DOUBLE_SLASH_RE)) {
+    str = str.replace(DOUBLE_SLASH_RE, SLASH);
+  }
   if (prepend) {
     str = SLASH + str;
   }
   return str;
 };
-var normalizePathToUnix = (path) => toUnix(sp2.normalize(toUnix(path)));
+var normalizePathToUnix = (path) => toUnix(sysPath2.normalize(toUnix(path)));
 var normalizeIgnored = (cwd = "") => (path) => {
   if (typeof path === "string") {
-    return normalizePathToUnix(sp2.isAbsolute(path) ? path : sp2.join(cwd, path));
+    return normalizePathToUnix(sysPath2.isAbsolute(path) ? path : sysPath2.join(cwd, path));
   } else {
     return path;
   }
 };
 var getAbsolutePath = (path, cwd) => {
-  if (sp2.isAbsolute(path)) {
+  if (sysPath2.isAbsolute(path)) {
     return path;
   }
-  return sp2.join(cwd, path);
+  return sysPath2.join(cwd, path);
 };
 var EMPTY_SET = Object.freeze(new Set);
 
 class DirEntry {
-  path;
-  _removeWatcher;
-  items;
   constructor(dir, removeWatcher) {
     this.path = dir;
     this._removeWatcher = removeWatcher;
@@ -9617,7 +9601,7 @@ class DirEntry {
       await readdir2(dir);
     } catch (err) {
       if (this._removeWatcher) {
-        this._removeWatcher(sp2.dirname(dir), sp2.basename(dir));
+        this._removeWatcher(sysPath2.dirname(dir), sysPath2.basename(dir));
       }
     }
   }
@@ -9645,19 +9629,12 @@ var STAT_METHOD_F = "stat";
 var STAT_METHOD_L = "lstat";
 
 class WatchHelper {
-  fsw;
-  path;
-  watchPath;
-  fullWatchPath;
-  dirParts;
-  followSymlinks;
-  statMethod;
   constructor(path, follow, fsw) {
     this.fsw = fsw;
     const watchPath = path;
     this.path = path = path.replace(REPLACER_RE, "");
     this.watchPath = watchPath;
-    this.fullWatchPath = sp2.resolve(watchPath);
+    this.fullWatchPath = sysPath2.resolve(watchPath);
     this.dirParts = [];
     this.dirParts.forEach((parts) => {
       if (parts.length > 1)
@@ -9667,7 +9644,7 @@ class WatchHelper {
     this.statMethod = follow ? STAT_METHOD_F : STAT_METHOD_L;
   }
   entryPath(entry) {
-    return sp2.join(this.watchPath, sp2.relative(this.watchPath, entry.fullPath));
+    return sysPath2.join(this.watchPath, sysPath2.relative(this.watchPath, entry.fullPath));
   }
   filterPath(entry) {
     const { stats } = entry;
@@ -9682,24 +9659,6 @@ class WatchHelper {
 }
 
 class FSWatcher extends EventEmitter {
-  closed;
-  options;
-  _closers;
-  _ignoredPaths;
-  _throttled;
-  _streams;
-  _symlinkPaths;
-  _watched;
-  _pendingWrites;
-  _pendingUnlinks;
-  _readyCount;
-  _emitReady;
-  _closePromise;
-  _userIgnored;
-  _readyEmitted;
-  _emitRaw;
-  _boundRemove;
-  _nodeFsHandler;
   constructor(_opts = {}) {
     super();
     this.closed = false;
@@ -9808,7 +9767,7 @@ class FSWatcher extends EventEmitter {
         return;
       results.forEach((item) => {
         if (item)
-          this.add(sp2.dirname(item), sp2.basename(_origAdd || item));
+          this.add(sysPath2.dirname(item), sysPath2.basename(_origAdd || item));
       });
     });
     return this;
@@ -9819,10 +9778,10 @@ class FSWatcher extends EventEmitter {
     const paths = unifyPaths(paths_);
     const { cwd } = this.options;
     paths.forEach((path) => {
-      if (!sp2.isAbsolute(path) && !this._closers.has(path)) {
+      if (!sysPath2.isAbsolute(path) && !this._closers.has(path)) {
         if (cwd)
-          path = sp2.join(cwd, path);
-        path = sp2.resolve(path);
+          path = sysPath2.join(cwd, path);
+        path = sysPath2.resolve(path);
       }
       this._closePath(path);
       this._addIgnoredPath(path);
@@ -9866,7 +9825,7 @@ class FSWatcher extends EventEmitter {
   getWatched() {
     const watchList = {};
     this._watched.forEach((entry, dir) => {
-      const key = this.options.cwd ? sp2.relative(this.options.cwd, dir) : dir;
+      const key = this.options.cwd ? sysPath2.relative(this.options.cwd, dir) : dir;
       const index = key || ONE_DOT;
       watchList[index] = entry.getChildren().sort();
     });
@@ -9882,9 +9841,9 @@ class FSWatcher extends EventEmitter {
       return;
     const opts = this.options;
     if (isWindows)
-      path = sp2.normalize(path);
+      path = sysPath2.normalize(path);
     if (opts.cwd)
-      path = sp2.relative(opts.cwd, path);
+      path = sysPath2.relative(opts.cwd, path);
     const args = [path];
     if (stats != null)
       args.push(stats);
@@ -9935,7 +9894,7 @@ class FSWatcher extends EventEmitter {
         return this;
     }
     if (opts.alwaysStat && stats === undefined && (event === EVENTS.ADD || event === EVENTS.ADD_DIR || event === EVENTS.CHANGE)) {
-      const fullPath = opts.cwd ? sp2.join(opts.cwd, path) : path;
+      const fullPath = opts.cwd ? sysPath2.join(opts.cwd, path) : path;
       let stats2;
       try {
         stats2 = await stat3(fullPath);
@@ -9991,8 +9950,8 @@ class FSWatcher extends EventEmitter {
     const pollInterval = awf.pollInterval;
     let timeoutHandler;
     let fullPath = path;
-    if (this.options.cwd && !sp2.isAbsolute(path)) {
-      fullPath = sp2.join(this.options.cwd, path);
+    if (this.options.cwd && !sysPath2.isAbsolute(path)) {
+      fullPath = sysPath2.join(this.options.cwd, path);
     }
     const now = new Date;
     const writes = this._pendingWrites;
@@ -10049,7 +10008,7 @@ class FSWatcher extends EventEmitter {
     return new WatchHelper(path, this.options.followSymlinks, this);
   }
   _getWatchedDir(directory) {
-    const dir = sp2.resolve(directory);
+    const dir = sysPath2.resolve(directory);
     if (!this._watched.has(dir))
       this._watched.set(dir, new DirEntry(dir, this._boundRemove));
     return this._watched.get(dir);
@@ -10060,8 +10019,8 @@ class FSWatcher extends EventEmitter {
     return Boolean(Number(stats.mode) & 256);
   }
   _remove(directory, item, isDirectory) {
-    const path = sp2.join(directory, item);
-    const fullPath = sp2.resolve(path);
+    const path = sysPath2.join(directory, item);
+    const fullPath = sysPath2.resolve(path);
     isDirectory = isDirectory != null ? isDirectory : this._watched.has(path) || this._watched.has(fullPath);
     if (!this._throttle("remove", path, 100))
       return;
@@ -10079,7 +10038,7 @@ class FSWatcher extends EventEmitter {
     }
     let relPath = path;
     if (this.options.cwd)
-      relPath = sp2.relative(this.options.cwd, path);
+      relPath = sysPath2.relative(this.options.cwd, path);
     if (this.options.awaitWriteFinish && this._pendingWrites.has(relPath)) {
       const event = this._pendingWrites.get(relPath).cancelWait();
       if (event === EVENTS.ADD)
@@ -10094,8 +10053,8 @@ class FSWatcher extends EventEmitter {
   }
   _closePath(path) {
     this._closeFile(path);
-    const dir = sp2.dirname(path);
-    this._getWatchedDir(dir).remove(sp2.basename(path));
+    const dir = sysPath2.dirname(path);
+    this._getWatchedDir(dir).remove(sysPath2.basename(path));
   }
   _closeFile(path) {
     const closers = this._closers.get(path);
@@ -10389,7 +10348,10 @@ async function uploadSource(portalURL, identityToken, publisherKey, tarballPath,
     }
     msg += `
   Fork to a new space_id to publish your own version.`;
-    throw new Error(msg);
+    const err = new Error(msg);
+    err.ownerKind = result.owner_kind;
+    err.ownerOrgId = result.owner_org_id;
+    throw err;
   }
   if (resp.status >= 400) {
     const msg = result.error || result.errors?.join("; ") || `server returned ${resp.status}`;
@@ -10397,6 +10359,20 @@ async function uploadSource(portalURL, identityToken, publisherKey, tarballPath,
   }
   return result;
 }
+async function fetchOrgPublisherKey(portalURL, identityToken) {
+  const root = portalURL.replace(/\/api\/developer\/?$/, "").replace(/\/+$/, "");
+  try {
+    const resp = await fetch(`${root}/api/publisher/org`, {
+      headers: { Authorization: `Bearer ${identityToken}` }
+    });
+    if (!resp.ok)
+      return null;
+    const body = await resp.json();
+    return body.publisher?.api_key || null;
+  } catch {
+    return null;
+  }
+}
 function setVersionInFiles(root, oldVer, newVer) {
   const oldStr = `"version": "${oldVer}"`;
   const newStr = `"version": "${newVer}"`;
@@ -10553,7 +10529,23 @@ async function publish(options) {
   }
   const uploadSpinner = ora("Uploading & building...").start();
   try {
-    const result = await uploadSource(creds.portal, creds.token, creds.publisherKey, tarballPath, m, { private: wantPrivate, public: wantPublic });
+    const explicitKey = options?.apiKey || process.env.CONSTRUCT_PUBLISHER_KEY;
+    const initialKey = explicitKey || creds.publisherKey;
+    let result;
+    try {
+      result = await uploadSource(creds.portal, creds.token, initialKey, tarballPath, m, { private: wantPrivate, public: wantPublic });
+    } catch (e) {
+      if (e?.ownerKind === "org" && !creds.publisherKey) {
+        uploadSpinner.text = "Fetching org publisher key\u2026";
+        const orgKey = await fetchOrgPublisherKey(creds.portal, creds.token);
+        if (!orgKey)
+          throw e;
+        uploadSpinner.text = "Uploading & building (as org)\u2026";
+        result = await uploadSource(creds.portal, creds.token, orgKey, tarballPath, m, { private: wantPrivate, public: wantPublic });
+      } else {
+        throw e;
+      }
+    }
     unlinkSync2(tarballPath);
     gitSafe(root, "tag", `v${m.version}`);
     gitSafe(root, "push", "origin", `v${m.version}`);
@@ -11509,7 +11501,7 @@ function graphFork(newSpaceID) {
 // package.json
 var package_default = {
   name: "@construct-space/cli",
-  version: "1.7.7",
+  version: "1.8.0",
   description: "Construct CLI \u2014 scaffold, build, develop, and publish spaces",
   type: "module",
   bin: {
@@ -11561,7 +11553,7 @@ program2.command("scaffold [name]").alias("new").alias("create").description("Cr
 program2.command("build").description("Build the space (generate entry + run Vite)").option("--entry-only", "Only generate src/entry.ts").action(async (opts) => build(opts));
 program2.command("dev").description("Start dev mode with file watching and live reload").action(async () => dev());
 program2.command("install").alias("run").description("Install built space to Construct spaces directory").action(() => install());
-program2.command("publish").description("Publish a space to the Construct registry").option("-y, --yes", "Skip all confirmation prompts").option("--bump <type>", "Auto-bump version (patch, minor, major)").option("--private", "Publish as org-private (catalog-listed only inside the owning org). Requires an org publisher key.").option("--public", "Flip a previously-private space back to the public catalog on this publish. Without --private or --public, visibility is preserved on update (and defaults to public on first publish).").action(async (opts) => publish(opts));
+program2.command("publish").description("Publish a space to the Construct registry").option("-y, --yes", "Skip all confirmation prompts").option("--bump <type>", "Auto-bump version (patch, minor, major)").option("--private", "Publish as org-private (catalog-listed only inside the owning org). Requires an org publisher key.").option("--public", "Flip a previously-private space back to the public catalog on this publish. Without --private or --public, visibility is preserved on update (and defaults to public on first publish).").option("--api-key <key>", "Publisher API key (csk_live_\u2026). Overrides any key stored in the active profile. Also reads CONSTRUCT_PUBLISHER_KEY.").action(async (opts) => publish(opts));
 program2.command("validate").description("Validate space.manifest.json").action(() => validate3());
 program2.command("check").description("Run type-check (vue-tsc) and linter (eslint)").action(() => check());
 program2.command("clean").description("Remove build artifacts").option("--all", "Also remove node_modules and lockfiles").action((opts) => clean(opts));
@@ -11592,7 +11584,7 @@ space.command("scaffold [name]").alias("new").alias("create").option("--with-tes
 space.command("build").option("--entry-only").action(async (opts) => build(opts));
 space.command("dev").action(async () => dev());
 space.command("install").alias("run").action(() => install());
-space.command("publish").option("-y, --yes").option("--bump <type>").option("--private").option("--public").action(async (opts) => publish(opts));
+space.command("publish").option("-y, --yes").option("--bump <type>").option("--private").option("--public").option("--api-key <key>").action(async (opts) => publish(opts));
 space.command("validate").action(() => validate3());
 space.command("check").action(() => check());
 space.command("clean").option("--all").action((opts) => clean(opts));

package/dist/templates/space/actions.ts.tmpl

@@ -1,26 +1,58 @@
 /**
  * Space Actions — exposed to the AI agent via space_run_action.
  *
- * Each action: { description, params, run }.
- *  - `params` describe agent-callable inputs (type, description, required).
- *  - `run` receives the payload and returns any JSON-serialisable value.
+ * Each action: { description, params, run, tier? }.
+ *  - `params`      JSON-schema-ish input shape; each: { type, description?, required? }.
+ *  - `run`         receives the validated payload, returns any JSON-serialisable value.
+ *  - `tier`        (optional) default model bucket for useBrain() calls inside `run`:
+ *                    'small'   fast/cheap   — summarisation, classification, short Q&A
+ *                    'medium'  balanced     — general help, edits, structured output
+ *                    'large'   reasoning    — long-form writing, deep code, planning
+ *                  The host resolves tier → provider+model via the user's tier config
+ *                  (Settings → LLM Providers). Per-call `brain.complete({ tier })`
+ *                  wins over the action default.
+ *
+ * Permission for useBrain():
+ *  - Declare `{{.ID}}:brain` in `permissions.catalog` (space.manifest.json).
+ *  - Add the action to `permissions.actions` mapping to that id, e.g.
+ *      "permissions": {
+ *        "actions": { "summarize": "{{.ID}}:brain" },
+ *        "catalog": [{ "id": "{{.ID}}:brain", "label": "Use AI summaries" }]
+ *      }
  *
  * Pair with @construct-space/graph for typed multi-tenant data:
  *   import { useGraph } from '@construct-space/graph'
  *   import { Item } from './models'
  *   const items = useGraph(Item)
- *
- *   listItems: {
- *     description: 'List items',
- *     params: { limit: { type: 'number', required: false } },
- *     run: async (p: any) => ({ items: await items.find({ limit: p.limit ?? 50 }) }),
- *   }
  */
 
-export const actions = {
+import { useBrain } from '@construct-space/sdk'
+import type { SpaceActions } from '@construct-space/sdk'
+
+export const actions: SpaceActions = {
   ping: {
     description: 'Health check — returns pong with the space id.',
     params: {},
     run: () => ({ pong: true, space: '{{.ID}}' }),
   },
+
+  // Example: a tier-routed action. Delete or adapt for your space.
+  // Requires '{{.ID}}:brain' in permissions.catalog and a row in
+  // permissions.actions mapping 'summarize' to that id.
+  //
+  // summarize: {
+  //   description: 'Summarise the given text in 1-2 sentences.',
+  //   tier: 'small',
+  //   params: {
+  //     text: { type: 'string', required: true, description: 'Text to summarise.' },
+  //   },
+  //   async run({ text }: { text: string }) {
+  //     const brain = useBrain()
+  //     if (!brain) return { error: 'brain unavailable' }
+  //     const { text: summary } = await brain.complete({
+  //       prompt: `Summarise in 1-2 sentences:\n\n${text}`,
+  //     })
+  //     return { summary }
+  //   },
+  // },
 }

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

@@ -4,7 +4,12 @@ name: {{.DisplayName}}
 category: space
 description: AI agent for the {{.DisplayName}} space
 maxIterations: 15
-tools: []
+# Whitelist of tools the agent can call. Each action in src/actions.ts is
+# exposed as `<space-id>.<actionName>`. Add yours here as you build them;
+# space_list_actions + space_run_action remain available as the fallback
+# discovery bridge, but explicit listing gives the model proper tool schemas.
+tools:
+  - {{.ID}}.ping
 canInvokeAgents: []
 ---
 
@@ -12,12 +17,14 @@ You are Construct's {{.DisplayName}} agent. You help users work within the {{.Di
 
 ## Context
 
-Use space_list_actions to discover available actions for this space.
-Use space_run_action to execute actions.
+Use the listed tools above first. If you need an action that isn't whitelisted,
+call space_list_actions to discover what else this space exposes, then
+space_run_action to invoke it.
+
 Do NOT call get_project_context — you work with space content, not project files.
 
 ## Behavior
 
-- Start by listing available actions to understand what you can do
+- Start by understanding what the user wants in this space
 - Be concise and action-oriented
 - Focus on tasks relevant to this space

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

@@ -162,7 +162,7 @@ export const Task = defineModel('task', {
   labels:      field.json(),
   assignee_id: field.string().index(),
 }, {
-  scope: 'org',                          // partitions schema per organization
+  scopes: ['org'],                       // partitions schema per organization
   access: {
     read:   access.authenticated(),
     create: access.authenticated(),
@@ -188,10 +188,12 @@ await tasks.remove(id)
 
 **Access helpers**: `authenticated()`, `owner()`, `admin()`, `member()`. `member()` requires org context — use `authenticated()` for org-scoped models that allow any logged-in member.
 
-**Scopes**:
-- `app` — single shared schema (rare)
-- `org` — partitioned by organization (most product spaces)
-- `project` — partitioned by project (dev-tooling spaces)
+**Scopes** (must match `scopes` in space.manifest.json):
+- `'app'` — per-user bucket (personal install)
+- `'org'` — shared across the active organization (org install)
+- both: `scopes: ['app', 'org']` — host picks bucket at install time
+
+`'project'` was removed in SDK 1.0. Older docs that show it are stale.
 
 **Push models to backend after editing**: `construct graph push`.
 
@@ -219,7 +221,9 @@ await tasks.remove(id)
 `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 = {
+import type { SpaceActions } from '@construct-space/sdk'
+
+export const actions: SpaceActions = {
   createTask: {
     description: 'Create a task',
     params: {
@@ -231,6 +235,75 @@ export const actions = {
 }
 ```
 
+### Tier-routed brain calls (LLM from inside an action)
+
+Actions can call the model mid-execution via `useBrain()`. The action picks
+the **cost bucket** (small / medium / large), the **user** picks the slot
+in Settings → LLM Providers. The host maps tier → provider + model.
+
+```ts
+import { useBrain } from '@construct-space/sdk'
+import type { SpaceActions } from '@construct-space/sdk'
+
+export const actions: SpaceActions = {
+  summarizeThread: {
+    description: 'Summarise one email thread in 1-2 sentences.',
+    tier: 'small',                       // default for brain calls in `run`
+    params: { threadId: { type: 'string', required: true } },
+    async run({ threadId }) {
+      const brain = useBrain()
+      if (!brain) return { error: 'brain unavailable' }
+      const thread = await loadThread(threadId as string)
+      const { text } = await brain.complete({ prompt: `Summarise:\n${thread.body}` })
+      return { summary: text }
+    },
+  },
+
+  composeReply: {
+    description: 'Draft a polished reply to the given message.',
+    tier: 'large',                       // long-form writing → opus-class
+    params: {
+      original: { type: 'string', required: true },
+      style:    { type: 'string', required: false, description: 'e.g. "warm", "formal"' },
+    },
+    async run({ original, style }) {
+      const brain = useBrain()
+      if (!brain) return { error: 'brain unavailable' }
+      const { text } = await brain.chat({
+        system: 'You write replies that feel like a thoughtful human wrote them.',
+        messages: [{ role: 'user', content: `${style ? `Tone: ${style}.\n\n` : ''}Reply to:\n${original}` }],
+      })
+      return { draft: text }
+    },
+  },
+}
+```
+
+Per-call overrides win: `brain.complete({ prompt, tier: 'large' })` upgrades
+even a small-tier action when the user asked for "detailed".
+
+**Permission required.** A space whose actions call brain must declare
+`{{.ID}}:brain` in `permissions.catalog` and map each brain-using action
+to it under `permissions.actions`. The user grants this at install time.
+
+```jsonc
+// space.manifest.json
+{
+  "permissions": {
+    "actions": {
+      "summarizeThread": "{{.ID}}:brain",
+      "composeReply":    "{{.ID}}:brain"
+    },
+    "catalog": [
+      { "id": "{{.ID}}:brain", "label": "Use AI for summaries & drafts" }
+    ]
+  }
+}
+```
+
+Without the grant, `useBrain()` throws `BrainPermissionDenied` synchronously
+on the first method call so the action can fall back gracefully.
+
 ### 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".

package/dist/templates/space/vite.config.ts.tmpl

@@ -20,8 +20,9 @@ const hostExternals = [
   'dexie',
   'zod',
   '@construct-space/ui',
-  '@construct/sdk',
   '@construct-space/sdk',
+  '@construct-space/graph',
+  '@construct/sdk',           // legacy alias — keep during cutover
 ]
 
 function makeGlobals(externals: string[]): Record<string, string> {

package/package.json

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

package/templates/space/actions.ts.tmpl

@@ -1,26 +1,58 @@
 /**
  * Space Actions — exposed to the AI agent via space_run_action.
  *
- * Each action: { description, params, run }.
- *  - `params` describe agent-callable inputs (type, description, required).
- *  - `run` receives the payload and returns any JSON-serialisable value.
+ * Each action: { description, params, run, tier? }.
+ *  - `params`      JSON-schema-ish input shape; each: { type, description?, required? }.
+ *  - `run`         receives the validated payload, returns any JSON-serialisable value.
+ *  - `tier`        (optional) default model bucket for useBrain() calls inside `run`:
+ *                    'small'   fast/cheap   — summarisation, classification, short Q&A
+ *                    'medium'  balanced     — general help, edits, structured output
+ *                    'large'   reasoning    — long-form writing, deep code, planning
+ *                  The host resolves tier → provider+model via the user's tier config
+ *                  (Settings → LLM Providers). Per-call `brain.complete({ tier })`
+ *                  wins over the action default.
+ *
+ * Permission for useBrain():
+ *  - Declare `{{.ID}}:brain` in `permissions.catalog` (space.manifest.json).
+ *  - Add the action to `permissions.actions` mapping to that id, e.g.
+ *      "permissions": {
+ *        "actions": { "summarize": "{{.ID}}:brain" },
+ *        "catalog": [{ "id": "{{.ID}}:brain", "label": "Use AI summaries" }]
+ *      }
  *
  * Pair with @construct-space/graph for typed multi-tenant data:
  *   import { useGraph } from '@construct-space/graph'
  *   import { Item } from './models'
  *   const items = useGraph(Item)
- *
- *   listItems: {
- *     description: 'List items',
- *     params: { limit: { type: 'number', required: false } },
- *     run: async (p: any) => ({ items: await items.find({ limit: p.limit ?? 50 }) }),
- *   }
  */
 
-export const actions = {
+import { useBrain } from '@construct-space/sdk'
+import type { SpaceActions } from '@construct-space/sdk'
+
+export const actions: SpaceActions = {
   ping: {
     description: 'Health check — returns pong with the space id.',
     params: {},
     run: () => ({ pong: true, space: '{{.ID}}' }),
   },
+
+  // Example: a tier-routed action. Delete or adapt for your space.
+  // Requires '{{.ID}}:brain' in permissions.catalog and a row in
+  // permissions.actions mapping 'summarize' to that id.
+  //
+  // summarize: {
+  //   description: 'Summarise the given text in 1-2 sentences.',
+  //   tier: 'small',
+  //   params: {
+  //     text: { type: 'string', required: true, description: 'Text to summarise.' },
+  //   },
+  //   async run({ text }: { text: string }) {
+  //     const brain = useBrain()
+  //     if (!brain) return { error: 'brain unavailable' }
+  //     const { text: summary } = await brain.complete({
+  //       prompt: `Summarise in 1-2 sentences:\n\n${text}`,
+  //     })
+  //     return { summary }
+  //   },
+  // },
 }

package/templates/space/config.md.tmpl

@@ -4,7 +4,12 @@ name: {{.DisplayName}}
 category: space
 description: AI agent for the {{.DisplayName}} space
 maxIterations: 15
-tools: []
+# Whitelist of tools the agent can call. Each action in src/actions.ts is
+# exposed as `<space-id>.<actionName>`. Add yours here as you build them;
+# space_list_actions + space_run_action remain available as the fallback
+# discovery bridge, but explicit listing gives the model proper tool schemas.
+tools:
+  - {{.ID}}.ping
 canInvokeAgents: []
 ---
 
@@ -12,12 +17,14 @@ You are Construct's {{.DisplayName}} agent. You help users work within the {{.Di
 
 ## Context
 
-Use space_list_actions to discover available actions for this space.
-Use space_run_action to execute actions.
+Use the listed tools above first. If you need an action that isn't whitelisted,
+call space_list_actions to discover what else this space exposes, then
+space_run_action to invoke it.
+
 Do NOT call get_project_context — you work with space content, not project files.
 
 ## Behavior
 
-- Start by listing available actions to understand what you can do
+- Start by understanding what the user wants in this space
 - Be concise and action-oriented
 - Focus on tasks relevant to this space

package/templates/space/construct.md.tmpl

@@ -162,7 +162,7 @@ export const Task = defineModel('task', {
   labels:      field.json(),
   assignee_id: field.string().index(),
 }, {
-  scope: 'org',                          // partitions schema per organization
+  scopes: ['org'],                       // partitions schema per organization
   access: {
     read:   access.authenticated(),
     create: access.authenticated(),
@@ -188,10 +188,12 @@ await tasks.remove(id)
 
 **Access helpers**: `authenticated()`, `owner()`, `admin()`, `member()`. `member()` requires org context — use `authenticated()` for org-scoped models that allow any logged-in member.
 
-**Scopes**:
-- `app` — single shared schema (rare)
-- `org` — partitioned by organization (most product spaces)
-- `project` — partitioned by project (dev-tooling spaces)
+**Scopes** (must match `scopes` in space.manifest.json):
+- `'app'` — per-user bucket (personal install)
+- `'org'` — shared across the active organization (org install)
+- both: `scopes: ['app', 'org']` — host picks bucket at install time
+
+`'project'` was removed in SDK 1.0. Older docs that show it are stale.
 
 **Push models to backend after editing**: `construct graph push`.
 
@@ -219,7 +221,9 @@ await tasks.remove(id)
 `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 = {
+import type { SpaceActions } from '@construct-space/sdk'
+
+export const actions: SpaceActions = {
   createTask: {
     description: 'Create a task',
     params: {
@@ -231,6 +235,75 @@ export const actions = {
 }
 ```
 
+### Tier-routed brain calls (LLM from inside an action)
+
+Actions can call the model mid-execution via `useBrain()`. The action picks
+the **cost bucket** (small / medium / large), the **user** picks the slot
+in Settings → LLM Providers. The host maps tier → provider + model.
+
+```ts
+import { useBrain } from '@construct-space/sdk'
+import type { SpaceActions } from '@construct-space/sdk'
+
+export const actions: SpaceActions = {
+  summarizeThread: {
+    description: 'Summarise one email thread in 1-2 sentences.',
+    tier: 'small',                       // default for brain calls in `run`
+    params: { threadId: { type: 'string', required: true } },
+    async run({ threadId }) {
+      const brain = useBrain()
+      if (!brain) return { error: 'brain unavailable' }
+      const thread = await loadThread(threadId as string)
+      const { text } = await brain.complete({ prompt: `Summarise:\n${thread.body}` })
+      return { summary: text }
+    },
+  },
+
+  composeReply: {
+    description: 'Draft a polished reply to the given message.',
+    tier: 'large',                       // long-form writing → opus-class
+    params: {
+      original: { type: 'string', required: true },
+      style:    { type: 'string', required: false, description: 'e.g. "warm", "formal"' },
+    },
+    async run({ original, style }) {
+      const brain = useBrain()
+      if (!brain) return { error: 'brain unavailable' }
+      const { text } = await brain.chat({
+        system: 'You write replies that feel like a thoughtful human wrote them.',
+        messages: [{ role: 'user', content: `${style ? `Tone: ${style}.\n\n` : ''}Reply to:\n${original}` }],
+      })
+      return { draft: text }
+    },
+  },
+}
+```
+
+Per-call overrides win: `brain.complete({ prompt, tier: 'large' })` upgrades
+even a small-tier action when the user asked for "detailed".
+
+**Permission required.** A space whose actions call brain must declare
+`{{.ID}}:brain` in `permissions.catalog` and map each brain-using action
+to it under `permissions.actions`. The user grants this at install time.
+
+```jsonc
+// space.manifest.json
+{
+  "permissions": {
+    "actions": {
+      "summarizeThread": "{{.ID}}:brain",
+      "composeReply":    "{{.ID}}:brain"
+    },
+    "catalog": [
+      { "id": "{{.ID}}:brain", "label": "Use AI for summaries & drafts" }
+    ]
+  }
+}
+```
+
+Without the grant, `useBrain()` throws `BrainPermissionDenied` synchronously
+on the first method call so the action can fall back gracefully.
+
 ### 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".

package/templates/space/vite.config.ts.tmpl

@@ -20,8 +20,9 @@ const hostExternals = [
   'dexie',
   'zod',
   '@construct-space/ui',
-  '@construct/sdk',
   '@construct-space/sdk',
+  '@construct-space/graph',
+  '@construct/sdk',           // legacy alias — keep during cutover
 ]
 
 function makeGlobals(externals: string[]): Record<string, string> {