@tinycloud/cli 0.7.0-beta.1 → 0.7.0-beta.10

package/dist/index.js

@@ -322,7 +322,8 @@ function wrapError(error) {
 }
 function handleError(error) {
   const cliError = wrapError(error);
-  const hint = buildAuthHint(cliError) ?? (cliError.code === "NETWORK_ERROR" ? buildNetworkHint() : void 0);
+  const prebuilt = typeof cliError.metadata?.hint === "string" ? cliError.metadata.hint : void 0;
+  const hint = prebuilt ?? buildAuthHint(cliError) ?? (cliError.code === "NETWORK_ERROR" ? buildNetworkHint() : void 0);
   outputError(cliError.code, cliError.message, hint);
   process.exit(cliError.exitCode);
 }
@@ -815,12 +816,19 @@ function buildAuthUrl(did, options = {}) {
   if (options.host) {
     params.set("host", options.host);
   }
+  const reason = typeof options.reason === "string" ? options.reason.trim() : "";
   if (options.permissions?.length) {
     params.set(
       "permissions",
-      Buffer.from(JSON.stringify({ permissions: options.permissions })).toString("base64url")
+      Buffer.from(JSON.stringify({
+        permissions: options.permissions,
+        ...reason ? { reason } : {}
+      })).toString("base64url")
     );
   }
+  if (reason) {
+    params.set("reason", reason);
+  }
   if (options.expiry !== void 0) {
     params.set("expiry", String(options.expiry));
   }
@@ -911,8 +919,8 @@ async function callbackFlow(did, options = {}) {
       }
       if (openBrowser) {
         try {
-          const open = (await import("open")).default;
-          await open(authUrl);
+          const open2 = (await import("open")).default;
+          await open2(authUrl);
         } catch {
           server.close();
           throw new Error("Failed to open browser");
@@ -973,11 +981,19 @@ Open this URL in a browser to authenticate:
 
 // src/commands/init.ts
 function registerInitCommand(program2) {
-  program2.command("init").description("Initialize a new TinyCloud profile").option("--name <profile>", "Profile name", "default").option("--key-only", "Only generate key, skip authentication").option("--host <url>", "TinyCloud node URL").option("--paste", "Use manual paste mode for authentication").option("--no-popup", "Print the OpenKey URL without opening a browser").action(async (options, cmd) => {
+  program2.command("init").description("Initialize a new TinyCloud profile").option("--name <profile>", "Profile name", "default").option("--key-only", "Only generate key, skip authentication").option("--host <url>", "TinyCloud node URL").option("--paste", "Use manual paste mode for authentication").option("--no-popup", "Print the OpenKey URL without opening a browser").option("--default-space <name>", "Default space used when --space is omitted (e.g. applications)").action(async (options, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const profileName = options.name;
       const host = options.host ?? globalOpts.host ?? DEFAULT_HOST;
+      const defaultSpace = options.defaultSpace;
+      if (defaultSpace !== void 0 && !/^[A-Za-z0-9_-]+$/.test(defaultSpace)) {
+        throw new CLIError(
+          "INVALID_SPACE",
+          `Invalid --default-space "${defaultSpace}". Use a short name ([A-Za-z0-9_-]).`,
+          ExitCode.USAGE_ERROR
+        );
+      }
       if (await ProfileManager.profileExists(profileName)) {
         throw new CLIError(
           "PROFILE_EXISTS",
@@ -996,7 +1012,8 @@ function registerInitCommand(program2) {
         chainId: DEFAULT_CHAIN_ID,
         spaceName: "default",
         did,
-        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        ...defaultSpace ? { defaultSpace } : {}
       };
       await ProfileManager.setProfile(profileName, profileConfig);
       const config = await ProfileManager.getConfig();
@@ -1044,7 +1061,7 @@ import { spawn } from "child_process";
 import { mkdir as mkdir2, readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
 import { dirname as dirname2 } from "path";
 import { createInterface as createInterface2 } from "readline";
-import { principalDidEquals } from "@tinycloud/node-sdk";
+import { grantAuthRequest, principalDidEquals } from "@tinycloud/node-sdk";
 
 // src/config/types.ts
 var CLI_PROFILE_POSTURES = [
@@ -5731,6 +5748,31 @@ var KVService = class extends BaseService {
     }
     return void 0;
   }
+  /**
+   * Classify a KV 404 by reading the response body once.
+   *
+   * The server returns 404 both for a genuinely missing key AND for an
+   * un-hosted space (body "Space not found"). Previously get/head/delete
+   * collapsed every 404 to KV_NOT_FOUND before reading the body, so an
+   * un-hosted-space read was indistinguishable from a missing key. We now
+   * preserve status + the "Space not found" body for the un-hosted case (so the
+   * CLI/SDK can normalize it to SPACE_NOT_HOSTED, matching put/list/sql), and
+   * fall through to KV_NOT_FOUND for a real missing key.
+   */
+  async classifyNotFound(response, key) {
+    const errorText = await response.text();
+    if (/space not found/i.test(errorText)) {
+      return err(
+        serviceError(
+          ErrorCodes.KV_NOT_FOUND,
+          `KV ${response.status} - ${errorText}`,
+          "kv",
+          { meta: { status: response.status, statusText: response.statusText } }
+        )
+      );
+    }
+    return err(serviceError(ErrorCodes.KV_NOT_FOUND, `Key not found: ${key}`, "kv"));
+  }
   /**
    * Get the full path with optional prefix.
    *
@@ -5781,6 +5823,38 @@ var KVService = class extends BaseService {
       signal: this.combineSignals(signal)
     });
   }
+  /**
+   * Serialize a single put value into a fetch body.
+   *
+   * Binary values (Blob/ArrayBuffer/typed-array, incl. Node Buffer) are sent as
+   * raw bytes (as a Blob) so they round-trip byte-identically — without this a
+   * Buffer would be JSON.stringify'd into `{"type":"Buffer","data":[...]}`.
+   * Strings are returned unchanged (preserving prior behavior); other values are
+   * JSON-encoded. `contentType` overrides the inferred type for binary values.
+   */
+  serializePutValue(value, contentType) {
+    if (value instanceof Blob) {
+      if (!contentType || value.type === contentType) {
+        return value;
+      }
+      return new Blob([value], { type: contentType });
+    }
+    if (value instanceof ArrayBuffer) {
+      return new Blob([value], {
+        type: contentType ?? "application/octet-stream"
+      });
+    }
+    if (ArrayBuffer.isView(value)) {
+      const view = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+      return new Blob([view], {
+        type: contentType ?? "application/octet-stream"
+      });
+    }
+    if (typeof value === "string") {
+      return contentType ? new Blob([value], { type: contentType }) : value;
+    }
+    return JSON.stringify(value);
+  }
   serializeBatchPutValue(item) {
     const contentType = item.contentType;
     if (item.value instanceof Blob) {
@@ -5850,10 +5924,13 @@ var KVService = class extends BaseService {
    * @param raw - Whether to return raw text
    * @returns Parsed data
    */
-  async parseResponse(response, raw = false) {
+  async parseResponse(response, raw = false, binary = false) {
     if (!response.ok) {
       return void 0;
     }
+    if (binary) {
+      return new Uint8Array(await response.arrayBuffer());
+    }
     if (raw) {
       return await response.text();
     }
@@ -5942,13 +6019,7 @@ var KVService = class extends BaseService {
             }));
           }
           if (response.status === 404) {
-            return err(
-              serviceError(
-                ErrorCodes.KV_NOT_FOUND,
-                `Key not found: ${key}`,
-                "kv"
-              )
-            );
+            return this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
           return err(
@@ -5960,7 +6031,11 @@ var KVService = class extends BaseService {
             )
           );
         }
-        const data = await this.parseResponse(response, options?.raw);
+        const data = await this.parseResponse(
+          response,
+          options?.raw,
+          options?.binary
+        );
         return ok({
           data,
           headers: this.createResponseHeaders(response.headers)
@@ -5979,12 +6054,7 @@ var KVService = class extends BaseService {
         return err(authRequiredError("kv"));
       }
       const path = this.getFullPath(key, options?.prefix);
-      let body;
-      if (typeof value === "string") {
-        body = value;
-      } else {
-        body = JSON.stringify(value);
-      }
+      const body = this.serializePutValue(value, options?.contentType);
       try {
         const response = await this.invokeOperation(
           path,
@@ -6210,13 +6280,7 @@ var KVService = class extends BaseService {
             }));
           }
           if (response.status === 404) {
-            return err(
-              serviceError(
-                ErrorCodes.KV_NOT_FOUND,
-                `Key not found: ${key}`,
-                "kv"
-              )
-            );
+            return this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
           return err(
@@ -6261,13 +6325,7 @@ var KVService = class extends BaseService {
             }));
           }
           if (response.status === 404) {
-            return err(
-              serviceError(
-                ErrorCodes.KV_NOT_FOUND,
-                `Key not found: ${key}`,
-                "kv"
-              )
-            );
+            return this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
           return err(
@@ -6414,6 +6472,7 @@ var DatabaseHandle = class {
 var SQLAction = {
   READ: "tinycloud.sql/read",
   WRITE: "tinycloud.sql/write",
+  DDL: "tinycloud.sql/ddl",
   ADMIN: "tinycloud.sql/admin",
   SELECT: "tinycloud.sql/select",
   INSERT: "tinycloud.sql/insert",
@@ -6423,6 +6482,7 @@ var SQLAction = {
   EXPORT: "tinycloud.sql/export",
   ALL: "tinycloud.sql/*"
 };
+var DDL_TOKENS = /* @__PURE__ */ new Set(["alter", "create", "drop"]);
 var SQLService = class extends BaseService {
   constructor(config = {}) {
     super();
@@ -6498,9 +6558,15 @@ var SQLService = class extends BaseService {
         if (options?.schema) {
           body.schema = options.schema;
         }
+        const actions = [
+          this.actionForSql(sql, SQLAction.WRITE),
+          ...(options?.schema ?? []).map(
+            (statement) => this.actionForSql(statement, SQLAction.DDL)
+          )
+        ];
         const response = await this.invokeSQL(
           dbName,
-          this.actionForSql(sql, SQLAction.WRITE),
+          this.dedupeActions(actions),
           body,
           options?.signal
         );
@@ -6522,7 +6588,7 @@ var SQLService = class extends BaseService {
       try {
         const response = await this.invokeSQL(
           dbName,
-          this.actionForSqlBatch(statements),
+          this.actionsForSqlBatch(statements),
           { action: "batch", statements },
           options?.signal
         );
@@ -6586,9 +6652,10 @@ var SQLService = class extends BaseService {
     });
   }
   // === Private helpers ===
-  async invokeSQL(dbName, action, body, signal) {
+  async invokeSQL(dbName, actions, body, signal) {
     const session = this.context.session;
-    const headers = this.context.invoke(session, "sql", dbName, action);
+    const actionList = Array.isArray(actions) ? actions : [actions];
+    const headers = actionList.length === 1 ? this.context.invoke(session, "sql", dbName, actionList[0]) : this.invokeSQLAny(session, dbName, actionList);
     return this.context.fetch(`${this.host}/invoke`, {
       method: "POST",
       headers: {
@@ -6600,12 +6667,34 @@ var SQLService = class extends BaseService {
     });
   }
   actionForSql(sql, fallback) {
-    return firstSqlToken(sql) === "pragma" ? SQLAction.ADMIN : fallback;
+    const token = firstSqlToken(sql);
+    if (token === "pragma") return SQLAction.ADMIN;
+    if (token !== void 0 && DDL_TOKENS.has(token)) return SQLAction.DDL;
+    return fallback;
+  }
+  actionsForSqlBatch(statements) {
+    return this.dedupeActions(
+      statements.map((statement) => this.actionForSql(statement.sql, SQLAction.WRITE))
+    );
   }
-  actionForSqlBatch(statements) {
-    return statements.some(
-      (statement) => this.actionForSql(statement.sql, SQLAction.WRITE) === SQLAction.ADMIN
-    ) ? SQLAction.ADMIN : SQLAction.WRITE;
+  dedupeActions(actions) {
+    return [...new Set(actions)];
+  }
+  invokeSQLAny(session, dbName, actions) {
+    if (!this.context.invokeAny) {
+      throw new Error(
+        `SQL operation requires multiple permissions (${actions.join(", ")}) but this SDK runtime does not support multi-resource invocations`
+      );
+    }
+    return this.context.invokeAny(
+      session,
+      actions.map((action) => ({
+        spaceId: session.spaceId,
+        service: "sql",
+        path: dbName,
+        action
+      }))
+    );
   }
   async handleErrorResponse(response, operation) {
     const errorText = await response.text();
@@ -10733,30 +10822,31 @@ function resolveChainId(profile, session) {
   return profile.chainId;
 }
 async function resolveSpaceUri(input, profileName) {
-  if (!input) return void 0;
-  if (input.startsWith("tinycloud:")) {
-    const parsed = parseSpaceUri(input);
+  const profile = await ProfileManager.getProfile(profileName);
+  const effective = input || profile.defaultSpace;
+  if (!effective) return void 0;
+  if (effective.startsWith("tinycloud:")) {
+    const parsed = parseSpaceUri(effective);
     if (!parsed) {
       throw new CLIError(
         "INVALID_SPACE",
-        `Invalid --space "${input}". Use a short name ([A-Za-z0-9_-]) or a full tinycloud:... URI.`,
+        `Invalid space "${effective}". Use a short name ([A-Za-z0-9_-]) or a full tinycloud:... URI.`,
         ExitCode.USAGE_ERROR
       );
     }
     return buildSpaceUri(parsed.owner, parsed.name);
   }
-  if (!/^[A-Za-z0-9_-]+$/.test(input)) {
+  if (!/^[A-Za-z0-9_-]+$/.test(effective)) {
     throw new CLIError(
       "INVALID_SPACE",
-      `Invalid --space "${input}". Use a short name ([A-Za-z0-9_-]) or a full tinycloud:... URI.`,
+      `Invalid space "${effective}". Use a short name ([A-Za-z0-9_-]) or a full tinycloud:... URI.`,
       ExitCode.USAGE_ERROR
     );
   }
-  const profile = await ProfileManager.getProfile(profileName);
   const session = await ProfileManager.getSession(profileName);
   const address = resolveAddress(profile, session);
   const chainId = resolveChainId(profile, session);
-  return makePkhSpaceId(address, chainId, input);
+  return makePkhSpaceId(address, chainId, effective);
 }
 
 // src/lib/permissions.ts
@@ -10938,6 +11028,7 @@ async function loadManifestPermissions(source, profile) {
         )
       };
     });
+    permissions.push(...await secretPermissionsFromAppManifest(manifest, profile));
     return resolvePermissionSpaces(permissions, profile);
   }
   throw new CLIError(
@@ -10946,6 +11037,46 @@ async function loadManifestPermissions(source, profile) {
     ExitCode.USAGE_ERROR
   );
 }
+async function secretPermissionsFromAppManifest(manifest, profile) {
+  if (manifest.secrets === void 0) {
+    return [];
+  }
+  const resolved = resolveManifest({
+    app_id: String(manifest.app_id),
+    name: typeof manifest.name === "string" ? manifest.name : String(manifest.app_id),
+    defaults: false,
+    prefix: "",
+    secrets: manifest.secrets
+  });
+  const permissions = resolved.resources.filter(
+    (resource) => resource.service === "tinycloud.kv" && resource.space === "secrets" && resource.path.startsWith("vault/secrets/")
+  );
+  const needsDecrypt = permissions.some(
+    (permission) => permission.actions.includes("tinycloud.kv/get")
+  );
+  if (needsDecrypt) {
+    permissions.push({
+      service: ENCRYPTION_PERMISSION_SERVICE,
+      space: ENCRYPTION_MANIFEST_SPACE,
+      path: await defaultSecretsNetworkId(profile),
+      actions: ["tinycloud.encryption/decrypt"],
+      skipPrefix: true
+    });
+  }
+  return permissions;
+}
+async function defaultSecretsNetworkId(profileName) {
+  const profile = await ProfileManager.getProfile(profileName);
+  const ownerDid = (profile.ownerDid ?? profile.did)?.split("#")[0];
+  if (!ownerDid) {
+    throw new CLIError(
+      "OWNER_DID_UNKNOWN",
+      `Cannot determine owner DID for profile "${profileName}". Run \`tc auth login\` first.`,
+      ExitCode.AUTH_REQUIRED
+    );
+  }
+  return `urn:tinycloud:encryption:${ownerDid}:default`;
+}
 function permissionsFromDelegation(delegation) {
   if (delegation.resources?.length) {
     return delegation.resources.map((resource) => ({
@@ -11298,6 +11429,10 @@ function registerAuthCommand(program2) {
             jwk: key,
             host: ctx.host,
             permissions: group,
+            reason: permissionGrantReason(
+              "Grant requested TinyCloud permissions from `tc auth request --grant`.",
+              group
+            ),
             openkeyHost,
             expiry: expiryOption,
             noPopup: options.popup === false
@@ -11442,23 +11577,11 @@ function registerAuthCommand(program2) {
         node,
         requested: parsed.requested,
         expiryOption: parsed.requestedExpiry,
+        reason: "Grant permissions requested by a TinyCloud auth request artifact.",
         yes: options.yes === true
       });
-      const result = await node.delegateTo(
-        parsed.sessionDid,
-        parsed.requested,
-        parsed.requestedExpiry !== void 0 ? { expiry: parsed.requestedExpiry } : void 0
-      );
-      outputJson({
-        kind: "tinycloud.auth.delegation",
-        version: 1,
-        requestId: parsed.requestId,
-        delegationCid: result.delegation.cid,
-        delegation: result.delegation,
-        permissions: parsed.requested,
-        expiry: result.delegation.expiry.toISOString(),
-        prompted: result.prompted
-      });
+      const grant = await grantAuthRequest(node, parsed);
+      outputJson(grant);
     } catch (error) {
       handleError(error);
     }
@@ -11738,6 +11861,7 @@ async function ensureDelegationAuthority(params) {
         jwk: key,
         host: params.ctx.host,
         permissions: group,
+        reason: permissionGrantReason(params.reason, group),
         openkeyHost,
         expiry: params.expiryOption
       });
@@ -11785,6 +11909,12 @@ async function ensureDelegationAuthority(params) {
     });
   }
 }
+function permissionGrantReason(context, permissions) {
+  const first = permissions[0];
+  const summary = first ? compactPermission(first) : "no permissions";
+  const more = permissions.length > 1 ? ` and ${permissions.length - 1} more permission${permissions.length === 2 ? "" : "s"}` : "";
+  return `${context} Requested: ${summary}${more}.`;
+}
 function execCapturedCommand(command) {
   return new Promise((resolve3, reject) => {
     const child = spawn(process.execPath, [process.argv[1], ...command.argv], {
@@ -11874,9 +12004,10 @@ function groupPermissionsBySpace(permissions) {
       rawEntries.push(permission);
       continue;
     }
-    const group = groups.get(permission.space) ?? [];
+    const key = normalizeSpaceForCompare(permission.space);
+    const group = groups.get(key) ?? [];
     group.push(permission);
-    groups.set(permission.space, group);
+    groups.set(key, group);
   }
   const grouped = Array.from(groups.values());
   if (grouped.length === 0) {
@@ -11888,8 +12019,16 @@ function groupPermissionsBySpace(permissions) {
 function isRawPermission(permission) {
   return permission.service === "tinycloud.encryption" && permission.path.startsWith("urn:tinycloud:encryption:");
 }
+function normalizeSpaceForCompare(space) {
+  return space.replace(
+    /(eip155:\d+:)(0x[0-9a-fA-F]{40})/,
+    (_match, prefix, addr) => prefix + addr.toLowerCase()
+  );
+}
 function returnedSpaceMatchesExpected(returnedSpace, expectedSpace) {
-  if (returnedSpace === expectedSpace) return true;
+  if (normalizeSpaceForCompare(returnedSpace) === normalizeSpaceForCompare(expectedSpace)) {
+    return true;
+  }
   if (!returnedSpace.startsWith("tinycloud:")) return false;
   const returnedName = returnedSpace.slice(returnedSpace.lastIndexOf(":") + 1);
   return returnedName === expectedSpace;
@@ -11898,7 +12037,7 @@ function portableFromOpenKeyDelegation(data, permissions, host) {
   const primary = permissions.find((permission) => !isRawPermission(permission)) ?? permissions[0];
   const returnedSpace = String(data.spaceId ?? primary.space ?? "encryption");
   const expectedSpaces = new Set(
-    permissions.filter((permission) => !isRawPermission(permission)).map((permission) => permission.space)
+    permissions.filter((permission) => !isRawPermission(permission)).map((permission) => normalizeSpaceForCompare(permission.space))
   );
   const matchesExpectedSpace = expectedSpaces.size === 1 && returnedSpaceMatchesExpected(returnedSpace, Array.from(expectedSpaces)[0]);
   if (expectedSpaces.size > 0 && !matchesExpectedSpace) {
@@ -12125,6 +12264,79 @@ async function refreshOpenKeySession(profileName, host, options = {}) {
 // src/commands/kv.ts
 import { readFile as readFile4 } from "fs/promises";
 import { writeFile as writeFile3 } from "fs/promises";
+
+// src/lib/host.ts
+function canonicalizeAddress2(address) {
+  const trimmed = address.trim();
+  return trimmed.startsWith("0x") ? `0x${trimmed.slice(2).toLowerCase()}` : trimmed.toLowerCase();
+}
+async function resolveLocalAddress(profile, profileName) {
+  const session = await ProfileManager.getSession(profileName);
+  const sessAddr = session?.address;
+  if (typeof sessAddr === "string" && sessAddr.length > 0) {
+    return canonicalizeAddress2(sessAddr);
+  }
+  if (profile.address) return canonicalizeAddress2(profile.address);
+  if (profile.ownerDid) {
+    const match = profile.ownerDid.match(/^did:pkh:eip155:\d+:(0x[a-fA-F0-9]{40})$/);
+    if (match) return canonicalizeAddress2(match[1]);
+  }
+  return null;
+}
+function ownerAddressFromSpaceUri(spaceUri) {
+  const match = spaceUri.match(/^tinycloud:pkh:eip155:\d+:(0x[a-fA-F0-9]{40}):/);
+  return match ? canonicalizeAddress2(match[1]) : null;
+}
+function ownerDidFromSpaceUri(spaceUri) {
+  const match = spaceUri.match(/^tinycloud:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40}):/);
+  if (!match) return null;
+  return `did:pkh:eip155:${match[1]}:${canonicalizeAddress2(match[2])}`;
+}
+async function isRootAuthority(spaceUri, profileName) {
+  const profile = await ProfileManager.getProfile(profileName);
+  if (resolveProfilePosture(profile) === "delegate-session") return false;
+  const ownerAddr = ownerAddressFromSpaceUri(spaceUri);
+  if (!ownerAddr) return false;
+  const selfAddr = await resolveLocalAddress(profile, profileName);
+  return selfAddr !== null && selfAddr === ownerAddr;
+}
+function spaceNameFromUri(spaceUri) {
+  return spaceUri.slice(spaceUri.lastIndexOf(":") + 1);
+}
+async function unhostedSpaceError(error, spaceUri, profileName) {
+  if (!spaceUri) return null;
+  const status = error.meta?.status;
+  const isUnhosted = status === 404 && /space not found/i.test(error.message);
+  if (!isUnhosted) return null;
+  const spaceName = spaceNameFromUri(spaceUri);
+  const owner = await isRootAuthority(spaceUri, profileName);
+  const hint = owner ? [
+    "You are the owner. Host it once:",
+    `  tc space host ${spaceName}`,
+    "Then retry."
+  ].join("\n") : [
+    "You are a delegate and CANNOT host this space \u2014 only its owner can.",
+    "Emit a host request:",
+    `  tc space host-request ${spaceName} --emit ./host-request.json`,
+    "Send it to the owner; they run `tc space host` and confirm. Then retry."
+  ].join("\n");
+  const message = owner ? `Space '${spaceName}' (${spaceUri}) is not hosted.` : `Space '${spaceName}' (owner ${ownerDidFromSpaceUri(spaceUri) ?? spaceUri}) is not hosted.`;
+  return new CLIError("SPACE_NOT_HOSTED", message, ExitCode.ERROR, { hint });
+}
+async function resolveHostSpace(name, profileName) {
+  const resolved = await resolveSpaceUri(name, profileName);
+  if (!resolved) {
+    throw new Error(`Could not resolve a space for "${name}".`);
+  }
+  return resolved;
+}
+
+// src/commands/kv.ts
+async function throwKvError(error, spaceUri, profileName) {
+  const hosted = await unhostedSpaceError(error, spaceUri, profileName);
+  if (hosted) throw hosted;
+  throw new CLIError(error.code, error.message, ExitCode.ERROR);
+}
 async function readStdin2() {
   const chunks = [];
   for await (const chunk of process.stdin) {
@@ -12134,7 +12346,8 @@ async function readStdin2() {
 }
 async function kvHandle(node, spaceInput, profileName) {
   const spaceUri = await resolveSpaceUri(spaceInput, profileName);
-  return spaceUri ? node.kvForSpace(spaceUri) : node.kv;
+  const kv = spaceUri ? node.kvForSpace(spaceUri) : node.kv;
+  return { kv, spaceUri };
 }
 function registerKvCommand(program2) {
   const kv = program2.command("kv").description("Key-value store operations");
@@ -12143,25 +12356,29 @@ function registerKvCommand(program2) {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const kv2 = await kvHandle(node, options.space, ctx.profile);
-      const result = await withSpinner(`Getting ${key}...`, () => kv2.get(key));
+      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
+      const wantBytes = !!options.output || !!options.raw;
+      const result = await withSpinner(
+        `Getting ${key}...`,
+        () => kv2.get(key, wantBytes ? { binary: true } : void 0)
+      );
       if (!result.ok) {
+        const hosted = await unhostedSpaceError(result.error, spaceUri, ctx.profile);
+        if (hosted) throw hosted;
         if (result.error.code === "KV_NOT_FOUND" || result.error.code === "NOT_FOUND") {
           throw new CLIError("NOT_FOUND", `Key "${key}" not found`, ExitCode.NOT_FOUND);
         }
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR);
+        await throwKvError(result.error, spaceUri, ctx.profile);
       }
       const data = result.data.data;
       const metadata = result.data.headers ?? {};
       if (options.output) {
-        const content = typeof data === "string" ? data : JSON.stringify(data);
-        await writeFile3(options.output, content);
+        await writeFile3(options.output, data);
         outputJson({ key, written: options.output });
         return;
       }
       if (options.raw) {
-        const content = typeof data === "string" ? data : JSON.stringify(data);
-        process.stdout.write(content);
+        process.stdout.write(data);
         return;
       }
       if (shouldOutputJson()) {
@@ -12178,7 +12395,7 @@ function registerKvCommand(program2) {
       handleError(error);
     }
   });
-  kv.command("put <key> [value]").description("Set a value").option("--file <path>", "Read value from file").option("--stdin", "Read value from stdin").action(async (key, value, options, cmd) => {
+  kv.command("put <key> [value]").description("Set a value").option("--file <path>", "Read value from file").option("--stdin", "Read value from stdin").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, value, options, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
@@ -12202,23 +12419,25 @@ function registerKvCommand(program2) {
           putValue = value;
         }
       }
-      const result = await withSpinner(`Writing ${key}...`, () => node.kv.put(key, putValue));
+      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
+      const result = await withSpinner(`Writing ${key}...`, () => kv2.put(key, putValue));
       if (!result.ok) {
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR);
+        await throwKvError(result.error, spaceUri, ctx.profile);
       }
       outputJson({ key, written: true });
     } catch (error) {
       handleError(error);
     }
   });
-  kv.command("delete <key>").description("Delete a key").action(async (key, _options, cmd) => {
+  kv.command("delete <key>").description("Delete a key").option("--space <name|uri>", "Target a non-primary space (short name or full URI)").action(async (key, options, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const result = await withSpinner(`Deleting ${key}...`, () => node.kv.delete(key));
+      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
+      const result = await withSpinner(`Deleting ${key}...`, () => kv2.delete(key));
       if (!result.ok) {
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR);
+        await throwKvError(result.error, spaceUri, ctx.profile);
       }
       outputJson({ key, deleted: true });
     } catch (error) {
@@ -12230,11 +12449,11 @@ function registerKvCommand(program2) {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const kv2 = await kvHandle(node, options.space, ctx.profile);
+      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
       const listOptions = options.prefix ? { prefix: options.prefix } : void 0;
       const result = await withSpinner("Listing keys...", () => kv2.list(listOptions));
       if (!result.ok) {
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR);
+        await throwKvError(result.error, spaceUri, ctx.profile);
       }
       const rawData = result.data.data ?? result.data;
       const keyList = Array.isArray(rawData) ? rawData : rawData?.keys ?? [];
@@ -12265,14 +12484,16 @@ function registerKvCommand(program2) {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const kv2 = await kvHandle(node, options.space, ctx.profile);
+      const { kv: kv2, spaceUri } = await kvHandle(node, options.space, ctx.profile);
       const result = await withSpinner(`Checking ${key}...`, () => kv2.head(key));
       if (!result.ok) {
+        const hosted = await unhostedSpaceError(result.error, spaceUri, ctx.profile);
+        if (hosted) throw hosted;
         if (result.error.code === "KV_NOT_FOUND" || result.error.code === "NOT_FOUND") {
           outputJson({ key, exists: false, metadata: {} });
           return;
         }
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR);
+        await throwKvError(result.error, spaceUri, ctx.profile);
       }
       outputJson({
         key,
@@ -12286,6 +12507,13 @@ function registerKvCommand(program2) {
 }
 
 // src/commands/space.ts
+import { randomBytes as randomBytes3 } from "crypto";
+import { mkdir as mkdir3, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname3 } from "path";
+function didWithoutFragment2(did) {
+  const fragment = did.indexOf("#");
+  return fragment === -1 ? did : did.slice(0, fragment);
+}
 function registerSpaceCommand(program2) {
   const space = program2.command("space").description("Space management");
   space.command("list").description("List spaces").action(async (_options, cmd) => {
@@ -12315,16 +12543,60 @@ function registerSpaceCommand(program2) {
       handleError(error);
     }
   });
-  space.command("create <name>").description("Create a new space").action(async (name, _options, cmd) => {
+  space.command("create <name>").alias("host").description("Create (host) one of your owned spaces by name").action(async (name, _options, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const result = await node.spaces.create(name);
-      if (!result.ok) {
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR);
+      const spaceId = await node.hostOwnedSpace(name);
+      outputJson({ spaceId, name, hosted: true });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  space.command("host-request <name>").description("Emit a request asking the space owner to host it (delegate-only)").option("--emit [file]", "Write the request artifact to file (or stdout when no path)").addHelpText("after", `
+
+A delegate cannot host a space \u2014 only its owner (root authority) can. This
+emits a tinycloud.host.request artifact naming the space and its owner so you
+can hand it to the owner; they run \`tc space host <name>\` and confirm.
+
+If you ARE the owner of the resolved space, this refuses and tells you to host
+it directly with \`tc space host <name>\` (no request needed).
+`).action(async (name, options, cmd) => {
+    try {
+      const globalOpts = cmd.optsWithGlobals();
+      const ctx = await ProfileManager.resolveContext(globalOpts);
+      const profile = await ProfileManager.getProfile(ctx.profile);
+      const spaceId = await resolveHostSpace(name, ctx.profile);
+      const spaceName = spaceNameFromUri(spaceId);
+      if (await isRootAuthority(spaceId, ctx.profile)) {
+        throw new CLIError(
+          "ALREADY_ROOT_AUTHORITY",
+          `You are the owner of ${spaceId}. Host it directly: tc space host ${spaceName}`,
+          ExitCode.USAGE_ERROR
+        );
+      }
+      const requesterDid = didWithoutFragment2(profile.sessionDid ?? profile.did);
+      const ownerDid = ownerDidFromSpaceUri(spaceId);
+      if (!ownerDid) {
+        throw new CLIError(
+          "UNRESOLVABLE_OWNER",
+          `Cannot determine the owner of ${spaceId}; host-request needs a pkh space URI.`,
+          ExitCode.USAGE_ERROR
+        );
       }
-      outputJson({ spaceId: result.data.id, name });
+      const artifact = {
+        kind: "tinycloud.host.request",
+        version: 1,
+        requestId: `hostreq_${Date.now().toString(36)}_${randomBytes3(4).toString("hex")}`,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+        spaceName,
+        spaceId,
+        ownerDid,
+        requesterDid,
+        host: ctx.host
+      };
+      await emitHostRequestArtifact(artifact, options.emit);
     } catch (error) {
       handleError(error);
     }
@@ -12361,6 +12633,22 @@ function registerSpaceCommand(program2) {
     }
   });
 }
+async function emitHostRequestArtifact(artifact, emitOption) {
+  if (typeof emitOption === "string" && emitOption.length > 0) {
+    await mkdir3(dirname3(emitOption), { recursive: true });
+    await writeFile4(emitOption, JSON.stringify(artifact, null, 2) + "\n", "utf8");
+    outputJson({
+      emitted: true,
+      path: emitOption,
+      requestId: artifact.requestId,
+      spaceName: artifact.spaceName,
+      spaceId: artifact.spaceId,
+      ownerDid: artifact.ownerDid
+    });
+    return;
+  }
+  outputJson(artifact);
+}
 
 // src/lib/duration.ts
 function parseDuration(input) {
@@ -12776,6 +13064,7 @@ function registerProfileCommand(program2) {
         process.stdout.write(formatField("Posture", posture) + "\n");
         process.stdout.write(formatField("Operator", operatorType) + "\n");
         process.stdout.write(formatField("Space", p.spaceId || null) + "\n");
+        process.stdout.write(formatField("Default Space", p.defaultSpace || null) + "\n");
         process.stdout.write(formatField("Key", hasKey) + "\n");
         process.stdout.write(formatField("Session", hasSession) + "\n");
         process.stdout.write(formatField("Created", p.createdAt) + "\n");
@@ -12796,6 +13085,46 @@ function registerProfileCommand(program2) {
       handleError(error);
     }
   });
+  profile.command("set-default-space [name]").description("Set (or clear) the default space used when --space is omitted").option("--profile <name>", "Profile to modify (defaults to the active profile)").option("--unset", "Clear the default space so commands fall back to the primary space").addHelpText("after", `
+
+The default space is a short space NAME (e.g. "applications"), resolved per
+profile at command time. Precedence for every kv/sql command:
+  explicit --space flag  >  profile defaultSpace  >  primary space.
+
+Examples:
+  $ tc profile set-default-space applications
+  $ tc profile set-default-space applications --profile cli-test
+  $ tc profile set-default-space --unset
+`).action(async (name, options, cmd) => {
+    try {
+      const globalOpts = cmd.optsWithGlobals();
+      const ctx = await ProfileManager.resolveContext({
+        ...globalOpts,
+        profile: options.profile ?? globalOpts.profile
+      });
+      const profileName = ctx.profile;
+      if (!options.unset && (name === void 0 || name === "")) {
+        throw new CLIError(
+          "USAGE_ERROR",
+          "Provide a space name (e.g. `tc profile set-default-space applications`) or pass --unset.",
+          ExitCode.USAGE_ERROR
+        );
+      }
+      if (!options.unset && !/^[A-Za-z0-9_-]+$/.test(name)) {
+        throw new CLIError(
+          "INVALID_SPACE",
+          `Invalid space name "${name}". Use a short name ([A-Za-z0-9_-]).`,
+          ExitCode.USAGE_ERROR
+        );
+      }
+      const p = await ProfileManager.getProfile(profileName);
+      const defaultSpace = options.unset ? void 0 : name;
+      await ProfileManager.setProfile(profileName, { ...p, defaultSpace });
+      outputJson({ profile: profileName, defaultSpace: defaultSpace ?? null, updated: true });
+    } catch (error) {
+      handleError(error);
+    }
+  });
   profile.command("delete <name>").description("Delete a profile").action(async (name, _options, cmd) => {
     try {
       if (isInteractive()) {
@@ -12967,7 +13296,7 @@ complete -c tc -l quiet -s q -d "Suppress non-essential output"
 
 // src/commands/vault.ts
 import { readFile as readFile5 } from "fs/promises";
-import { writeFile as writeFile4 } from "fs/promises";
+import { writeFile as writeFile5 } from "fs/promises";
 import { PrivateKeySigner as PrivateKeySigner2 } from "@tinycloud/node-sdk";
 async function readStdin3() {
   const chunks = [];
@@ -13056,7 +13385,7 @@ function registerVaultCommand(program2) {
       const data = result.data.data ?? result.data;
       if (options.output) {
         const content = data instanceof Uint8Array ? Buffer.from(data) : typeof data === "string" ? data : JSON.stringify(data);
-        await writeFile4(options.output, content);
+        await writeFile5(options.output, content);
         outputJson({ key, written: options.output });
         return;
       }
@@ -13140,7 +13469,7 @@ function registerVaultCommand(program2) {
 
 // src/commands/secrets.ts
 import { readFile as readFile6 } from "fs/promises";
-import { writeFile as writeFile5 } from "fs/promises";
+import { writeFile as writeFile6 } from "fs/promises";
 import { join as join5 } from "path";
 import { homedir as homedir2 } from "os";
 var SECRETS_SPACE2 = "secrets";
@@ -13262,12 +13591,17 @@ async function runSecretOperation(params) {
       node: params.node,
       requested,
       expiryOption: void 0,
+      reason: secretPermissionReason(params.action, params.name),
       yes: true,
       force: true
     })
   );
   return runSecretOperationAttempt(params.label, params.operation);
 }
+function secretPermissionReason(action, name) {
+  const target = name ? ` secret "${name}"` : " secrets";
+  return `Allow \`tc secrets ${action}${name ? ` ${name}` : ""}\` to access${target} with the required TinyCloud permissions.`;
+}
 async function runSecretOperationAttempt(label, operation) {
   try {
     return await withSpinner(label, operation);
@@ -13639,6 +13973,30 @@ function secretPermissionEntries(params) {
   }
   return permissions;
 }
+function formatSecretScopeFlag(options) {
+  return options?.scope ? ` --scope ${JSON.stringify(options.scope)}` : "";
+}
+function outputSecretDoctor(result) {
+  if (shouldOutputJson()) {
+    outputJson(result);
+    return;
+  }
+  process.stderr.write(formatSection("Secrets") + "\n");
+  for (const check of result.checks) {
+    process.stdout.write(formatCheck(check.ok, check.name, check.detail) + "\n");
+    if (check.hint) {
+      process.stdout.write(`  ${theme.hint(check.hint)}
+`);
+    }
+  }
+  process.stdout.write("\n");
+  if (result.healthy) {
+    process.stdout.write(theme.success("Secrets checks passed.") + "\n");
+  } else {
+    const failed = result.checks.filter((check) => check.ok === false).length;
+    process.stdout.write(theme.warn(`${failed} secrets check${failed > 1 ? "s" : ""} need attention.`) + "\n");
+  }
+}
 function registerSecretsCommand(program2) {
   const secrets = program2.command("secrets").description("Encrypted secrets management");
   const network = secrets.command("network").description("Manage the default secrets encryption network");
@@ -13680,6 +14038,93 @@ function registerSecretsCommand(program2) {
       handleError(error);
     }
   });
+  secrets.command("doctor [name]").description("Check secrets setup and optional secret access").option("--scope <scope>", "Logical secret scope").option("--space <scope>", "Deprecated alias for --scope").option("--network <name>", "Encryption network name", "default").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (name, options, cmd) => {
+    try {
+      const globalOpts = cmd.optsWithGlobals();
+      const ctx = await ProfileManager.resolveContext(globalOpts);
+      const node = await ensureSecretsNode(ctx, options);
+      const networkName = options.network ?? "default";
+      const networkId = networkName.startsWith("urn:tinycloud:encryption:") ? networkName : node.getDefaultEncryptionNetworkId(networkName);
+      const descriptor = await withSpinner(
+        "Checking secrets encryption network...",
+        () => node.getEncryptionNetwork(networkName)
+      );
+      const checks = [
+        descriptor ? {
+          name: "Encryption network",
+          ok: descriptor.state === "active" ? true : "warn",
+          detail: `${networkName} (${descriptor.state})`
+        } : {
+          name: "Encryption network",
+          ok: false,
+          detail: `${networkName} not found`,
+          hint: `tc secrets network init ${networkName}`
+        }
+      ];
+      let secret;
+      if (name) {
+        const scopeOptions = resolveSecretScope(options);
+        const resolved = resolveSecretPath2(name, scopeOptions);
+        const result = await runSecretOperation({
+          ctx,
+          node,
+          action: "get",
+          name,
+          scopeOptions,
+          label: `Checking secret ${name}...`,
+          operation: () => node.secrets.get(name, scopeOptions)
+        });
+        if (result.ok) {
+          secret = {
+            name: resolved.name,
+            path: resolved.permissionPaths.vault,
+            ...resolved.scope ? { scope: resolved.scope } : {},
+            exists: true,
+            readable: true
+          };
+          checks.push({
+            name: "Secret access",
+            ok: true,
+            detail: `${resolved.permissionPaths.vault} readable`
+          });
+        } else {
+          const notFound = result.error.code === "NOT_FOUND" || result.error.code === "KEY_NOT_FOUND";
+          secret = {
+            name: resolved.name,
+            path: resolved.permissionPaths.vault,
+            ...resolved.scope ? { scope: resolved.scope } : {},
+            exists: !notFound,
+            readable: false
+          };
+          checks.push({
+            name: "Secret access",
+            ok: false,
+            detail: notFound ? `${resolved.permissionPaths.vault} not found` : result.error.message,
+            hint: notFound ? `tc secrets put ${resolved.name}${formatSecretScopeFlag(scopeOptions)} <value>` : "Ask the owner profile to grant tinycloud.kv/get and tinycloud.encryption/decrypt."
+          });
+        }
+      } else {
+        checks.push({
+          name: "Secret access",
+          ok: "warn",
+          detail: "skipped; pass a secret name to verify read access"
+        });
+      }
+      outputSecretDoctor({
+        healthy: checks.every((check) => check.ok !== false),
+        network: {
+          name: networkName,
+          networkId,
+          exists: descriptor !== null,
+          ...descriptor?.state ? { state: descriptor.state } : {}
+        },
+        ...secret ? { secret } : {},
+        checks
+      });
+    } catch (error) {
+      handleError(error);
+    }
+  });
   secrets.command("list").description("List secrets").option("--scope <scope>", "Logical secret scope").option("--space <scope>", "Deprecated alias for --scope").option("--private-key <hex>", "Ethereum private key (or set TC_PRIVATE_KEY)").action(async (options, cmd) => {
     try {
       const globalOpts = cmd.optsWithGlobals();
@@ -13731,7 +14176,7 @@ function registerSecretsCommand(program2) {
           })
         );
         if (options.output) {
-          await writeFile5(options.output, value2);
+          await writeFile6(options.output, value2);
           outputJson({ name, written: options.output });
           return;
         }
@@ -13760,7 +14205,7 @@ function registerSecretsCommand(program2) {
       }
       const value = String(result.data);
       if (options.output) {
-        await writeFile5(options.output, value);
+        await writeFile6(options.output, value);
         outputJson({ name, written: options.output });
         return;
       }
@@ -13867,8 +14312,8 @@ function registerSecretsCommand(program2) {
   });
   secrets.command("manage").description("Open the TinyCloud Secrets Manager in your browser").action(async () => {
     try {
-      const open = (await import("open")).default;
-      await open("https://secrets.tinycloud.xyz");
+      const open2 = (await import("open")).default;
+      await open2("https://secrets.tinycloud.xyz");
       outputJson({ opened: "https://secrets.tinycloud.xyz" });
     } catch (error) {
       handleError(error);
@@ -13878,7 +14323,7 @@ function registerSecretsCommand(program2) {
 
 // src/commands/vars.ts
 import { readFile as readFile7 } from "fs/promises";
-import { writeFile as writeFile6 } from "fs/promises";
+import { writeFile as writeFile7 } from "fs/promises";
 var VARIABLES_PREFIX = "variables/";
 async function readStdin5() {
   const chunks = [];
@@ -13950,7 +14395,7 @@ function registerVarsCommand(program2) {
         value = typeof data === "string" ? data : JSON.stringify(data);
       }
       if (options.output) {
-        await writeFile6(options.output, value);
+        await writeFile7(options.output, value);
         outputJson({ name, written: options.output });
         return;
       }
@@ -14124,12 +14569,18 @@ function registerDoctorCommand(program2) {
 }
 
 // src/commands/sql.ts
-import { writeFile as writeFile7 } from "fs/promises";
+import { writeFile as writeFile8 } from "fs/promises";
 import { resolve } from "path";
 async function dbHandle(node, dbName, spaceInput, profileName) {
   const spaceUri = await resolveSpaceUri(spaceInput, profileName);
   const sql = spaceUri ? node.sqlForSpace(spaceUri) : node.sql;
-  return sql.db(dbName);
+  return { handle: sql.db(dbName), spaceUri };
+}
+async function throwSqlError(error, spaceUri, profileName, prefix) {
+  const hosted = await unhostedSpaceError(error, spaceUri, profileName);
+  if (hosted) throw hosted;
+  const message = prefix ? `${prefix}${error.message}` : error.message;
+  throw new CLIError(error.code, message, ExitCode.ERROR, error.meta);
 }
 function registerSqlCommand(program2) {
   const sql = program2.command("sql").description("SQLite database operations for your TinyCloud space").addHelpText("after", `
@@ -14175,13 +14626,13 @@ Output:
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
       const params = options.params ? JSON.parse(options.params) : void 0;
-      const handle = await dbHandle(node, options.db, options.space, ctx.profile);
+      const { handle, spaceUri } = await dbHandle(node, options.db, options.space, ctx.profile);
       const result = await withSpinner(
         "Running query...",
         () => handle.query(sqlStr, params)
       );
       if (!result.ok) {
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR, result.error.meta);
+        await throwSqlError(result.error, spaceUri, ctx.profile);
       }
       const { columns, rows, rowCount } = result.data;
       if (shouldOutputJson()) {
@@ -14219,13 +14670,13 @@ Output:
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
       const params = options.params ? JSON.parse(options.params) : void 0;
-      const handle = await dbHandle(node, options.db, options.space, ctx.profile);
+      const { handle, spaceUri } = await dbHandle(node, options.db, options.space, ctx.profile);
       const result = await withSpinner(
         "Executing statement...",
         () => handle.execute(sqlStr, params)
       );
       if (!result.ok) {
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR, result.error.meta);
+        await throwSqlError(result.error, spaceUri, ctx.profile);
       }
       outputJson({
         changes: result.data.changes,
@@ -14249,18 +14700,18 @@ Output:
       const globalOpts = cmd.optsWithGlobals();
       const ctx = await ProfileManager.resolveContext(globalOpts);
       const node = await ensureAuthenticated(ctx);
-      const handle = await dbHandle(node, options.db, options.space, ctx.profile);
+      const { handle, spaceUri } = await dbHandle(node, options.db, options.space, ctx.profile);
       const result = await withSpinner(
         "Exporting database...",
         () => handle.export()
       );
       if (!result.ok) {
-        throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR, result.error.meta);
+        await throwSqlError(result.error, spaceUri, ctx.profile);
       }
       const blob = result.data;
       const buffer = Buffer.from(await blob.arrayBuffer());
       const outputPath = resolve(options.output);
-      await writeFile7(outputPath, buffer);
+      await writeFile8(outputPath, buffer);
       outputJson({
         file: outputPath,
         size: blob.size,
@@ -14304,8 +14755,8 @@ Notes:
           ExitCode.USAGE_ERROR
         );
       }
-      const fromHandle = await dbHandle(node, options.fromDb, fromSpaceInput, ctx.profile);
-      const toHandle = await dbHandle(node, options.toDb, toSpaceInput, ctx.profile);
+      const { handle: fromHandle, spaceUri: fromSpaceUriResolved } = await dbHandle(node, options.fromDb, fromSpaceInput, ctx.profile);
+      const { handle: toHandle, spaceUri: toSpaceUriResolved } = await dbHandle(node, options.toDb, toSpaceInput, ctx.profile);
       let tables;
       if (options.table && options.table.length > 0) {
         tables = options.table.flatMap((t) => t.split(",").map((s) => s.trim()).filter(Boolean));
@@ -14314,7 +14765,7 @@ Notes:
           "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
         );
         if (!listing.ok) {
-          throw new CLIError(listing.error.code, `Cannot list source tables: ${listing.error.message}`, ExitCode.ERROR, listing.error.meta);
+          await throwSqlError(listing.error, fromSpaceUriResolved, ctx.profile, "Cannot list source tables: ");
         }
         tables = listing.data.rows.map((r) => String(r[0]));
       }
@@ -14330,12 +14781,7 @@ Notes:
         const safe = quoteIdent(table);
         const countResult = await fromHandle.query(`SELECT count(*) AS n FROM ${safe}`);
         if (!countResult.ok) {
-          throw new CLIError(
-            countResult.error.code,
-            `Cannot count rows in source table "${table}": ${countResult.error.message}`,
-            ExitCode.ERROR,
-            countResult.error.meta
-          );
+          await throwSqlError(countResult.error, fromSpaceUriResolved, ctx.profile, `Cannot count rows in source table "${table}": `);
         }
         const rows = Number(countResult.data.rows[0]?.[0] ?? 0);
         plan.push({ table, rows, copied: 0, skipped: 0 });
@@ -14353,7 +14799,7 @@ Notes:
         const safe = quoteIdent(entry.table);
         const fetched = await fromHandle.query(`SELECT * FROM ${safe}`);
         if (!fetched.ok) {
-          throw new CLIError(fetched.error.code, `Failed to read "${entry.table}": ${fetched.error.message}`, ExitCode.ERROR, fetched.error.meta);
+          await throwSqlError(fetched.error, fromSpaceUriResolved, ctx.profile, `Failed to read "${entry.table}": `);
         }
         const columns = fetched.data.columns;
         const rows = fetched.data.rows;
@@ -14364,12 +14810,7 @@ Notes:
         for (const row of rows) {
           const writeResult = await toHandle.execute(insertSql, row);
           if (!writeResult.ok) {
-            throw new CLIError(
-              writeResult.error.code,
-              `Insert into "${entry.table}" failed after ${entry.copied} row(s): ${writeResult.error.message}`,
-              ExitCode.ERROR,
-              writeResult.error.meta
-            );
+            await throwSqlError(writeResult.error, toSpaceUriResolved, ctx.profile, `Insert into "${entry.table}" failed after ${entry.copied} row(s): `);
           }
           entry.copied += writeResult.data.changes ?? 1;
         }
@@ -14389,7 +14830,7 @@ function quoteIdent(name) {
 }
 
 // src/commands/duckdb.ts
-import { readFile as readFile8, writeFile as writeFile8 } from "fs/promises";
+import { readFile as readFile8, writeFile as writeFile9 } from "fs/promises";
 import { resolve as resolve2 } from "path";
 function registerDuckdbCommand(program2) {
   const duckdb = program2.command("duckdb").description("DuckDB database operations");
@@ -14503,7 +14944,7 @@ ${rowCount} row${rowCount === 1 ? "" : "s"} returned`) + "\n");
       const blob = result.data;
       const buffer = Buffer.from(await blob.arrayBuffer());
       const outputPath = resolve2(options.output);
-      await writeFile8(outputPath, buffer);
+      await writeFile9(outputPath, buffer);
       outputJson({
         file: outputPath,
         size: blob.size,
@@ -15088,6 +15529,310 @@ function plural(count, label) {
   return `${count} ${label}${count === 1 ? "" : "s"}`;
 }
 
+// src/commands/account.ts
+import open from "open";
+import { readFile as readFile10 } from "fs/promises";
+var ACCOUNT_BILLING_URL = "https://account.tinycloud.xyz/billing";
+function registerAccountCommand(program2) {
+  const account = program2.command("account").description("Account applications, spaces, delegations, and billing");
+  account.command("status").description("Show account status").action(async (_options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const status = await node.account.status();
+      assertOk(status);
+      outputJson(status.data);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  const apps = account.command("apps").description("Manage account application registry");
+  apps.command("list").description("List applications registered under account/applications").option("--live", "Read canonical account KV records instead of the SQLite index").action(async (_options, cmd) => {
+    try {
+      const options = _options;
+      const node = await authenticatedNode(cmd);
+      const result = options.live ? await node.account.applications.list() : await node.account.index.applications.list();
+      assertOk(result);
+      const payload = { applications: result.data, count: result.data.length };
+      if (shouldOutputJson()) {
+        outputJson(payload);
+        return;
+      }
+      if (result.data.length === 0) {
+        process.stdout.write(theme.muted("No account applications registered.") + "\n");
+        return;
+      }
+      process.stdout.write(
+        formatTable(
+          ["App ID", "Name", "Manifests", "Updated"],
+          result.data.map((app) => [
+            app.appId,
+            app.name ?? "\u2014",
+            String(app.manifests.length),
+            app.updatedAt ?? "\u2014"
+          ])
+        ) + "\n"
+      );
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  const spaces = account.command("spaces").description("Manage account space registry");
+  spaces.command("list").description("List spaces registered under account/spaces").option("--live", "Read canonical account KV records instead of the SQLite index").action(async (options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = options.live ? await node.account.spaces.list() : await node.account.index.spaces.list();
+      assertOk(result);
+      const payload = { spaces: result.data.map(formatSpace), count: result.data.length };
+      if (shouldOutputJson()) {
+        outputJson(payload);
+        return;
+      }
+      if (result.data.length === 0) {
+        process.stdout.write(theme.muted("No account spaces registered.") + "\n");
+        return;
+      }
+      process.stdout.write(
+        formatTable(
+          ["Space", "Type", "Owner", "Status", "Updated"],
+          result.data.map((space) => [
+            space.name,
+            space.type,
+            space.ownerDid,
+            space.status,
+            space.updatedAt ?? "\u2014"
+          ])
+        ) + "\n"
+      );
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  spaces.command("info <space-id>").description("Show a registered account space").action(async (spaceId, _options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.spaces.get(spaceId);
+      assertOk(result);
+      outputJson(formatSpace(result.data));
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  spaces.command("register <space-id>").description("Register a space in account/spaces").requiredOption("--name <name>", "Display name for the space").requiredOption("--owner <did>", "Owner DID for the space").option("--type <type>", "Space type: owned, delegated, or discovered", "discovered").option("--permission <permission...>", "Permission strings for the space").action(async (spaceId, options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.spaces.register({
+        spaceId,
+        name: options.name,
+        ownerDid: options.owner,
+        type: options.type,
+        permissions: options.permission ?? [],
+        status: "active"
+      });
+      assertOk(result);
+      outputJson({ space: formatSpace(result.data), registered: true });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  spaces.command("sync").description("Register currently accessible spaces into account/spaces").action(async (_options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.spaces.syncAccessible();
+      assertOk(result);
+      outputJson({ spaces: result.data.map(formatSpace), count: result.data.length, synced: true });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  spaces.command("remove <space-id>").alias("delete").description("Remove a space registry entry").action(async (spaceId, _options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.spaces.remove(spaceId);
+      assertOk(result);
+      outputJson({ spaceId, removed: true });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  apps.command("info <app-id>").description("Show a registered account application").action(async (appId, _options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.applications.get(appId);
+      assertOk(result);
+      outputJson(result.data);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  apps.command("register <manifest>").description("Register an app manifest in account/applications").action(async (manifestSource, _options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const manifest = await loadManifestSource2(manifestSource);
+      const result = await node.account.applications.register(manifest);
+      assertOk(result);
+      outputJson({ application: result.data, registered: true });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  apps.command("remove <app-id>").alias("delete").description("Remove an application registry entry").action(async (appId, _options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.applications.remove(appId);
+      assertOk(result);
+      outputJson({ appId, removed: true });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  const delegations = account.command("delegations").description("View and revoke account delegations");
+  delegations.command("list").description("List delegations granted by or to this account").option("--granted", "Show only delegations granted by this account").option("--received", "Show only delegations granted to this account").option("--space <space>", "Filter by space name or ID").option("--live", "Read live delegation services instead of the SQLite index").action(async (options, cmd) => {
+    try {
+      if (options.granted && options.received) {
+        throw new CLIError("USAGE_ERROR", "Use only one of --granted or --received.", ExitCode.USAGE_ERROR);
+      }
+      const node = await authenticatedNode(cmd);
+      const direction = options.granted ? "granted" : options.received ? "received" : "all";
+      const result = options.live ? await node.account.delegations.list({ direction, space: options.space }) : await node.account.index.delegations.list({ direction, space: options.space });
+      assertOk(result);
+      const payload = { delegations: result.data.map(formatDelegation2), count: result.data.length };
+      if (shouldOutputJson()) {
+        outputJson(payload);
+        return;
+      }
+      if (result.data.length === 0) {
+        process.stdout.write(theme.muted("No delegations found.") + "\n");
+        return;
+      }
+      process.stdout.write(
+        formatTable(
+          ["CID", "Direction", "Space", "Counterparty", "Status", "Expiry"],
+          result.data.map((delegation) => [
+            delegation.cid,
+            delegation.direction,
+            delegation.spaceName ?? delegation.spaceId,
+            delegation.counterpartyDid,
+            delegation.status,
+            delegation.expiry.toISOString()
+          ])
+        ) + "\n"
+      );
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  delegations.command("revoke <cid>").description("Revoke an active delegation granted by this account").requiredOption("--space <space>", "Space name or ID containing the delegation").action(async (cid, options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.delegations.revoke({ cid, space: options.space });
+      assertOk(result);
+      outputJson({ cid, space: options.space, revoked: true });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  const index = account.command("index").description("Manage the materialized account SQLite index");
+  index.command("status").description("Show account SQLite index sync status").action(async (_options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.index.status();
+      assertOk(result);
+      outputJson(result.data);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  index.command("rebuild").description("Rebuild account SQLite index from canonical account data").action(async (_options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const result = await node.account.index.rebuild();
+      assertOk(result);
+      outputJson(result.data);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  index.command("query <sql>").description("Query the materialized account SQLite index").option("--params <json>", "Bind parameters as a JSON array for ? placeholders").action(async (sql, options, cmd) => {
+    try {
+      const node = await authenticatedNode(cmd);
+      const params = parseParams(options.params);
+      const result = await node.account.index.query(sql, params);
+      assertOk(result);
+      outputJson(result.data);
+    } catch (error) {
+      handleError(error);
+    }
+  });
+  const billing = account.command("billing").description("Open account billing");
+  for (const name of ["status", "checkout", "portal"]) {
+    billing.command(name).description(`${name === "status" ? "Show" : "Open"} account billing page`).option("--open", "Open account.tinycloud.xyz in your browser").action(async (options) => {
+      try {
+        if (options.open) {
+          await open(ACCOUNT_BILLING_URL);
+        }
+        outputJson({ url: ACCOUNT_BILLING_URL, opened: Boolean(options.open) });
+      } catch (error) {
+        handleError(error);
+      }
+    });
+  }
+}
+async function authenticatedNode(cmd) {
+  const globalOpts = cmd.optsWithGlobals();
+  const ctx = await ProfileManager.resolveContext(globalOpts);
+  return ensureAuthenticated(ctx);
+}
+function assertOk(result) {
+  if (!result.ok) {
+    throw new CLIError(result.error.code, result.error.message, ExitCode.ERROR);
+  }
+}
+async function loadManifestSource2(source) {
+  const raw = /^https?:\/\//i.test(source) ? await fetchManifest(source) : await readFile10(source, "utf8");
+  return JSON.parse(raw);
+}
+async function fetchManifest(source) {
+  const response = await fetch(source);
+  if (!response.ok) {
+    throw new CLIError(
+      "MANIFEST_FETCH_FAILED",
+      `Failed to fetch manifest from ${source}: ${response.status} ${response.statusText}`,
+      ExitCode.NETWORK_ERROR
+    );
+  }
+  return response.text();
+}
+function parseParams(input) {
+  if (!input) return void 0;
+  const parsed = JSON.parse(input);
+  if (!Array.isArray(parsed)) {
+    throw new CLIError("INVALID_PARAMS", "--params must be a JSON array.", ExitCode.USAGE_ERROR);
+  }
+  return parsed;
+}
+function formatDelegation2(delegation) {
+  return {
+    cid: delegation.cid,
+    direction: delegation.direction,
+    spaceId: delegation.spaceId,
+    spaceName: delegation.spaceName,
+    counterpartyDid: delegation.counterpartyDid,
+    delegateDid: delegation.delegateDid,
+    delegatorDid: delegation.delegatorDid,
+    path: delegation.path,
+    actions: delegation.actions,
+    expiry: delegation.expiry.toISOString(),
+    status: delegation.status,
+    createdAt: delegation.createdAt?.toISOString()
+  };
+}
+function formatSpace(space) {
+  return {
+    ...space,
+    expiresAt: space.expiresAt?.toISOString()
+  };
+}
+
 // src/index.ts
 var { version } = JSON.parse(
   readFileSync3(new URL("../package.json", import.meta.url), "utf-8")
@@ -15138,6 +15883,7 @@ registerDuckdbCommand(program);
 registerManifestCommand(program);
 registerUpgradeCommand(program);
 registerStatusCommand(program);
+registerAccountCommand(program);
 program.addHelpText("before", () => `${theme.label("Version:")} ${theme.value(version)}
 `);
 program.addHelpText("afterAll", () => {
@@ -15149,6 +15895,7 @@ ${theme.heading("Examples:")}
   ${theme.command('tc kv put greeting "Hello"')}           ${theme.muted("Store a value")}
   ${theme.command("tc kv list")}                           ${theme.muted("List all keys")}
   ${theme.command("tc secrets network init")}              ${theme.muted("Create the default secrets network")}
+  ${theme.command("tc account apps list")}                 ${theme.muted("List registered account apps")}
   ${theme.command("tc delegation create --to did:pkh:...")}  ${theme.muted("Grant access to another user")}
   ${theme.command("tc space list")}                        ${theme.muted("Show your spaces")}