agentful 0.2.0 → 0.2.2

package/dist/index.cjs

@@ -3044,7 +3044,7 @@ var VERSION, brand, useColor, wrap, paint, sym, ui;
 var init_branding = __esm({
   "src/branding.ts"() {
     "use strict";
-    VERSION = "0.2.0" ? "0.2.0" : null.version;
+    VERSION = "0.2.2" ? "0.2.2" : null.version;
     brand = {
       name: "agentful",
       // the command users type
@@ -4395,7 +4395,8 @@ function materializeStarter(name, targetDir, projectName) {
     throw new ApiError(
       0,
       "directory_not_empty",
-      `This directory is not empty (found ${blockers.slice(0, 3).join(", ")}${blockers.length > 3 ? ", \u2026" : ""}). \`init --template\` scaffolds into an empty directory only \u2014 it never overwrites your files.`
+      `This directory is not empty (found ${blockers.slice(0, 3).join(", ")}${blockers.length > 3 ? ", \u2026" : ""}). \`init --template\` scaffolds into an empty directory only \u2014 it never overwrites your files.
+Pass a new folder name instead: \`agentful init --template ${name} my-app\` (creates it for you).`
     );
   }
   let written = 0;
@@ -4419,16 +4420,15 @@ function materializeStarter(name, targetDir, projectName) {
 function slugify(value) {
   return value.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
 }
+function prepareScaffoldDirectory(baseDir, directory) {
+  const target = (0, import_node_path4.resolve)(baseDir, directory);
+  (0, import_node_fs3.mkdirSync)(target, { recursive: true });
+  return target;
+}
 
 // src/commands/init.ts
-async function initCommand(opts) {
+async function initCommand(opts, directory) {
   console.log(banner());
-  const existing = readProjectConfig();
-  if (existing) {
-    ui.info(`Already initialized (project ${existing.projectId} \u2014 "${existing.title}").`);
-    ui.info("Delete .agentful/project.json to re-initialize.");
-    return;
-  }
   if (opts.template && opts.link) {
     throw new ApiError(
       0,
@@ -4436,6 +4436,22 @@ async function initCommand(opts) {
       "--template scaffolds a new project and cannot be combined with --link."
     );
   }
+  if (directory && !opts.template) {
+    throw new ApiError(
+      0,
+      "invalid_options",
+      "A target directory only makes sense with --template \u2014 plain `init` links the directory you are in."
+    );
+  }
+  if (opts.template && directory) {
+    process.chdir(prepareScaffoldDirectory(process.cwd(), directory));
+  }
+  const existing = readProjectConfig();
+  if (existing) {
+    ui.info(`Already initialized (project ${existing.projectId} \u2014 "${existing.title}").`);
+    ui.info("Delete .agentful/project.json to re-initialize.");
+    return;
+  }
   if (opts.template) {
     const title2 = opts.title?.trim() || (0, import_node_path5.basename)(process.cwd());
     ui.step(`Scaffolding from the ${opts.template} starter\u2026`);
@@ -4465,6 +4481,7 @@ async function initCommand(opts) {
   const config = await createProject(auth, title);
   ui.ok(`Project created (${config.projectId}). Next: \`agentful push\``);
   if (opts.template) {
+    if (directory) ui.info(`Next: \`cd ${directory}\` \u2014 the project lives there now.`);
     ui.info("Run `npm install` before local dev; `agentful push` builds in the cloud either way.");
     ui.info(`Or start the coding agent right away: \`agentful\` (templates: ${STARTER_NAMES.join(", ")}).`);
   }
@@ -5404,9 +5421,9 @@ var contract_default = {
       details: "raw build output excerpt"
     },
     adopted_by: {
-      build_engine: ["status", "timestamp", "error", "details", "framework"],
-      executor: ["status", "timestamp", "phase", "error"],
-      $comment: "Current state, not the target: the engine writes no phase codes and neither builder writes build_id/started_at/status:running yet. Full adoption is AP4 (engine) + AP5 (executor); until then the CLI must not poll against build identity \u2014 it uses the timestamp freshness guard instead."
+      build_engine: ["schema_version", "build_id", "started_at", "status", "timestamp", "phase", "error", "details", "framework"],
+      executor: ["schema_version", "build_id", "started_at", "status", "timestamp", "phase", "error"],
+      $comment: "Both builders write the attempt identity since AP4/AP5 (2026-08-18); failures carry phase codes and \u2014 for contract violations \u2014 code/reason/hints. The engine additionally writes a running record at start; the executor has no separate build-start moment (started_at is the turn start) and writes no running record. The CLI may graduate from timestamp freshness to identity-based polling for the ENGINE path."
     }
   }
 };
@@ -5590,6 +5607,38 @@ function runPreflight(rootDir) {
   return { framework, issues, warnings };
 }
 
+// src/lib/backendDecl.ts
+var import_node_fs6 = require("fs");
+var import_node_path8 = require("path");
+function readBackendDeclaration(dir = process.cwd()) {
+  const path = (0, import_node_path8.join)(dir, ".agentful", "backend.json");
+  if (!(0, import_node_fs6.existsSync)(path)) return null;
+  try {
+    const parsed = JSON.parse((0, import_node_fs6.readFileSync)(path, "utf8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    const decl = {
+      schema_version: Number(parsed.schema_version) || 1,
+      managed_db: Boolean(parsed.managed_db),
+      actions: Array.isArray(parsed.actions) ? parsed.actions.filter((a) => typeof a === "string") : [],
+      contract_doc: typeof parsed.contract_doc === "string" ? parsed.contract_doc : void 0
+    };
+    if (!decl.managed_db && decl.actions.length === 0) return null;
+    return decl;
+  } catch {
+    return null;
+  }
+}
+function describeBackendDeclaration(decl) {
+  const parts = [];
+  if (decl.managed_db) parts.push("managed DB");
+  if (decl.actions && decl.actions.length > 0) parts.push(`${decl.actions.length} server action(s)`);
+  const base = parts.join(" + ") || "managed backend";
+  return decl.contract_doc ? `${base} (contract: ${decl.contract_doc})` : base;
+}
+function backendTabUrl(userId, projectId) {
+  return `${APP_URL}/workspace/${userId}/${projectId}?view=backend`;
+}
+
 // src/lib/buildStatus.ts
 init_branding();
 var DIAGNOSIS_MAX_AGE_MS = 15 * 60 * 1e3;
@@ -5715,6 +5764,10 @@ async function pushCommand(opts) {
   console.log("");
   ui.ok(`Live preview: ${ui.url(url)}`);
   ui.info(`Manage in the browser: ${ui.url(`https://app.agentful.dev/workspace/${userId}/${projectId}`)}`);
+  const backend = readBackendDeclaration();
+  if (backend) {
+    ui.info(`Declared managed backend: ${describeBackendDeclaration(backend)} \u2014 enable/manage it in the Backend tab: \`agentful backend\` takes you there.`);
+  }
 }
 async function pollBuild(token, userId, projectId, startedAtMs) {
   const deadline = Date.now() + 10 * 60 * 1e3;
@@ -5800,6 +5853,24 @@ async function buildStatusCommand() {
   }
 }
 
+// src/commands/backend.ts
+init_branding();
+async function backendCommand() {
+  console.log(banner());
+  const project = requireProject();
+  const decl = readBackendDeclaration();
+  if (decl) {
+    ui.info(`This project declares: ${describeBackendDeclaration(decl)}.`);
+    ui.info("Declared in code is not enabled on the platform \u2014 that happens in the Backend tab.");
+  }
+  const url = backendTabUrl(project.userId, project.projectId);
+  ui.step(`Opening the Backend tab: ${ui.url(url)}`);
+  if (!openInBrowser(url)) {
+    ui.info("Could not launch a browser \u2014 open this URL manually:");
+    ui.info(ui.url(url));
+  }
+}
+
 // src/commands/open.ts
 init_branding();
 async function openCommand() {
@@ -5816,15 +5887,15 @@ async function openCommand() {
 
 // src/commands/tui.ts
 var import_node_child_process5 = require("child_process");
-var import_node_path16 = require("path");
+var import_node_path17 = require("path");
 
 // src/lib/binWrapper.ts
-var import_node_fs6 = require("fs");
-var import_node_path8 = require("path");
+var import_node_fs7 = require("fs");
+var import_node_path9 = require("path");
 var import_node_os3 = require("os");
 function ensureCliOnPath() {
-  const binDir = (0, import_node_path8.join)((0, import_node_os3.homedir)(), ".local", "share", "agentful", "bin");
-  (0, import_node_fs6.mkdirSync)(binDir, { recursive: true });
+  const binDir = (0, import_node_path9.join)((0, import_node_os3.homedir)(), ".local", "share", "agentful", "bin");
+  (0, import_node_fs7.mkdirSync)(binDir, { recursive: true });
   const entry = process.argv[1];
   if (!entry) return binDir;
   const restore = (name) => {
@@ -5833,8 +5904,8 @@ function ensureCliOnPath() {
 ` : `export ${name}=${JSON.stringify(original)}
 `;
   };
-  const wrapper = (0, import_node_path8.join)(binDir, "agentful");
-  (0, import_node_fs6.writeFileSync)(
+  const wrapper = (0, import_node_path9.join)(binDir, "agentful");
+  (0, import_node_fs7.writeFileSync)(
     wrapper,
     `#!/bin/sh
 # Generated by the Agentful CLI so the coding agent can run \`agentful \u2026\`.
@@ -5844,7 +5915,7 @@ function ensureCliOnPath() {
     "utf8"
   );
   try {
-    (0, import_node_fs6.chmodSync)(wrapper, 493);
+    (0, import_node_fs7.chmodSync)(wrapper, 493);
   } catch {
   }
   return binDir;
@@ -5854,9 +5925,9 @@ function ensureCliOnPath() {
 init_branding();
 
 // src/lib/engine.ts
-var import_node_fs7 = require("fs");
+var import_node_fs8 = require("fs");
 var import_node_crypto = require("crypto");
-var import_node_path9 = require("path");
+var import_node_path10 = require("path");
 var import_node_os4 = require("os");
 var import_node_child_process3 = require("child_process");
 var import_node_stream = require("stream");
@@ -5897,8 +5968,8 @@ function platformKey() {
   );
 }
 function cacheDir(version) {
-  const base = process.env.XDG_CACHE_HOME || (0, import_node_path9.join)((0, import_node_os4.homedir)(), ".cache");
-  return (0, import_node_path9.join)(base, "agentful", "engine", version);
+  const base = process.env.XDG_CACHE_HOME || (0, import_node_path10.join)((0, import_node_os4.homedir)(), ".cache");
+  return (0, import_node_path10.join)(base, "agentful", "engine", version);
 }
 async function fetchManifest() {
   try {
@@ -5909,7 +5980,7 @@ async function fetchManifest() {
 }
 async function sha256File(path) {
   const hash = (0, import_node_crypto.createHash)("sha256");
-  await (0, import_promises2.pipeline)((0, import_node_fs7.createReadStream)(path), hash);
+  await (0, import_promises2.pipeline)((0, import_node_fs8.createReadStream)(path), hash);
   return hash.digest("hex");
 }
 async function ensureEngine() {
@@ -5918,12 +5989,12 @@ async function ensureEngine() {
   noticeIfOutdated(manifest);
   const version = manifest?.engine_version || FALLBACK_ENGINE_VERSION;
   const dir = cacheDir(version);
-  const binPath = (0, import_node_path9.join)(dir, ENGINE_BINARY);
-  if ((0, import_node_fs7.existsSync)(binPath)) return binPath;
+  const binPath = (0, import_node_path10.join)(dir, ENGINE_BINARY);
+  if ((0, import_node_fs8.existsSync)(binPath)) return binPath;
   const artifact = manifest?.artifacts?.[key];
   const url = artifact?.url || `${APP_URL}/cli/engine/${version}/${key}${key.startsWith("darwin") ? ".zip" : ".tar.gz"}`;
-  (0, import_node_fs7.mkdirSync)(dir, { recursive: true });
-  const archivePath = (0, import_node_path9.join)(dir, key.startsWith("darwin") ? "engine.zip" : "engine.tar.gz");
+  (0, import_node_fs8.mkdirSync)(dir, { recursive: true });
+  const archivePath = (0, import_node_path10.join)(dir, key.startsWith("darwin") ? "engine.zip" : "engine.tar.gz");
   ui.step(`Preparing the ${brand.displayName} engine (first run only)\u2026`);
   const resp = await fetch(url, {
     redirect: "follow",
@@ -5937,11 +6008,11 @@ async function ensureEngine() {
       `Could not download the engine (HTTP ${resp.status}). Check your connection and try again.`
     );
   }
-  await (0, import_promises2.pipeline)(import_node_stream.Readable.fromWeb(resp.body), (0, import_node_fs7.createWriteStream)(archivePath));
+  await (0, import_promises2.pipeline)(import_node_stream.Readable.fromWeb(resp.body), (0, import_node_fs8.createWriteStream)(archivePath));
   if (artifact?.sha256) {
     const actual = await sha256File(archivePath);
     if (actual !== artifact.sha256) {
-      (0, import_node_fs7.rmSync)(archivePath, { force: true });
+      (0, import_node_fs8.rmSync)(archivePath, { force: true });
       throw new ApiError(
         0,
         "engine_checksum_mismatch",
@@ -5950,7 +6021,7 @@ async function ensureEngine() {
     }
   }
   const extract = archivePath.endsWith(".zip") ? (0, import_node_child_process3.spawnSync)("unzip", ["-oq", archivePath], { cwd: dir, stdio: "ignore" }) : (0, import_node_child_process3.spawnSync)("tar", ["-xzf", archivePath], { cwd: dir, stdio: "ignore" });
-  (0, import_node_fs7.rmSync)(archivePath, { force: true });
+  (0, import_node_fs8.rmSync)(archivePath, { force: true });
   if (extract.status !== 0) {
     throw new ApiError(
       0,
@@ -5958,24 +6029,24 @@ async function ensureEngine() {
       `Could not unpack the engine (needs ${archivePath.endsWith(".zip") ? "unzip" : "tar"} on PATH).`
     );
   }
-  const extracted = (0, import_node_path9.join)(dir, "opencode");
-  if ((0, import_node_fs7.existsSync)(extracted) && !(0, import_node_fs7.existsSync)(binPath)) (0, import_node_fs7.renameSync)(extracted, binPath);
-  if (!(0, import_node_fs7.existsSync)(binPath)) {
+  const extracted = (0, import_node_path10.join)(dir, "opencode");
+  if ((0, import_node_fs8.existsSync)(extracted) && !(0, import_node_fs8.existsSync)(binPath)) (0, import_node_fs8.renameSync)(extracted, binPath);
+  if (!(0, import_node_fs8.existsSync)(binPath)) {
     throw new ApiError(0, "engine_extract_failed", "Engine archive did not contain the expected binary.");
   }
-  (0, import_node_fs7.chmodSync)(binPath, 493);
+  (0, import_node_fs8.chmodSync)(binPath, 493);
   ui.ok(`Engine ready.`);
   console.log(paint.dim("  powered by opencode (MIT) \xB7 run `agentful licenses` for details"));
   return binPath;
 }
 
 // src/lib/gatewayToken.ts
-var import_node_fs8 = require("fs");
-var import_node_path10 = require("path");
-var cachePath = () => (0, import_node_path10.join)(configDir(), "gateway.json");
+var import_node_fs9 = require("fs");
+var import_node_path11 = require("path");
+var cachePath = () => (0, import_node_path11.join)(configDir(), "gateway.json");
 async function ensureGatewaySession(auth, projectId) {
   try {
-    const cached = JSON.parse((0, import_node_fs8.readFileSync)(cachePath(), "utf8"));
+    const cached = JSON.parse((0, import_node_fs9.readFileSync)(cachePath(), "utf8"));
     if (cached?.token && cached.expires_at - Date.now() / 1e3 > 3600) {
       return cached;
     }
@@ -5986,18 +6057,18 @@ async function ensureGatewaySession(auth, projectId) {
     body: projectId ? { project_id: projectId } : {},
     timeoutMs: 3e4
   });
-  (0, import_node_fs8.mkdirSync)(configDir(), { recursive: true });
-  (0, import_node_fs8.writeFileSync)(cachePath(), JSON.stringify(res, null, 2) + "\n", "utf8");
+  (0, import_node_fs9.mkdirSync)(configDir(), { recursive: true });
+  (0, import_node_fs9.writeFileSync)(cachePath(), JSON.stringify(res, null, 2) + "\n", "utf8");
   try {
-    (0, import_node_fs8.chmodSync)(cachePath(), 384);
+    (0, import_node_fs9.chmodSync)(cachePath(), 384);
   } catch {
   }
   return res;
 }
 
 // src/lib/engineConfig.ts
-var import_node_fs10 = require("fs");
-var import_node_path12 = require("path");
+var import_node_fs11 = require("fs");
+var import_node_path13 = require("path");
 var import_node_os5 = require("os");
 
 // src/branding/agentful-theme.json
@@ -6106,6 +6177,10 @@ var SLASH_COMMANDS = {
     description: `${brand.displayName}: show the last cloud build result`,
     template: "Run `agentful build-status` from the project root using the bash tool and report what it prints: status, phase, framework, when it was recorded, and the error/details verbatim if it failed. That record is the only source of truth about the cloud build \u2014 do not speculate beyond it. " + NEEDS_A_PUSH
   },
+  backend: {
+    description: `${brand.displayName}: open the Backend tab (managed DB + server actions)`,
+    template: "Run `agentful backend` from the project root using the bash tool and report the URL it opened. If it prints a declared backend (managed DB / server actions), summarize that and remind me that declared-in-code serves nothing until enabled in that tab. " + NEEDS_A_PUSH
+  },
   preview: {
     description: `${brand.displayName}: open the live preview in the browser`,
     template: "Run `agentful open` from the project root using the bash tool and report the URL it opened. Note that `open` neither builds nor uploads. " + NEEDS_A_PUSH
@@ -6136,22 +6211,22 @@ ${cmd.template}
 }
 
 // src/lib/tools.ts
-var import_node_fs9 = require("fs");
-var import_node_path11 = require("path");
+var import_node_fs10 = require("fs");
+var import_node_path12 = require("path");
 function assetsDir() {
-  const here = (0, import_node_path11.dirname)(process.argv[1] || "");
-  for (const candidate of [(0, import_node_path11.join)(here, "..", "assets"), (0, import_node_path11.join)(here, "assets")]) {
-    if ((0, import_node_fs9.existsSync)((0, import_node_path11.join)(candidate, "tools", "imagegen.ts"))) return candidate;
+  const here = (0, import_node_path12.dirname)(process.argv[1] || "");
+  for (const candidate of [(0, import_node_path12.join)(here, "..", "assets"), (0, import_node_path12.join)(here, "assets")]) {
+    if ((0, import_node_fs10.existsSync)((0, import_node_path12.join)(candidate, "tools", "imagegen.ts"))) return candidate;
   }
   return null;
 }
 function installEngineTools(configDir2) {
   const assets = assetsDir();
   if (!assets) return false;
-  const target = (0, import_node_path11.join)(configDir2, "tools");
-  (0, import_node_fs9.mkdirSync)(target, { recursive: true });
+  const target = (0, import_node_path12.join)(configDir2, "tools");
+  (0, import_node_fs10.mkdirSync)(target, { recursive: true });
   try {
-    (0, import_node_fs9.cpSync)((0, import_node_path11.join)(assets, "tools"), target, { recursive: true });
+    (0, import_node_fs10.cpSync)((0, import_node_path12.join)(assets, "tools"), target, { recursive: true });
     return true;
   } catch {
     return false;
@@ -6229,6 +6304,19 @@ statically evaluable; prefer client-side fetch or Managed Server Actions.
 (b) an external backend called from the client. Never a bundled server
 process, and never a script the user must run locally to produce the result.
 
+When you design a managed backend (DB schema, server actions), also write the
+machine-readable declaration \`.agentful/backend.json\`:
+\`{"schema_version": 1, "managed_db": true, "actions": ["<action-name>", \u2026], "contract_doc": "docs/backend-contract.md"}\`
+\u2014 \`agentful push\` and \`agentful backend\` use it to tell the user honestly
+what is declared in code but not yet enabled on the platform.
+
+When you point the user at the Backend tab, NEVER say "the Backend tab"
+without an address. Read \`.agentful/project.json\` and give the full URL
+\`https://app.agentful.dev/workspace/<userId>/<projectId>?view=backend\` \u2014 or
+simply the command \`agentful backend\`, which opens exactly that page.
+Declaring a backend never enables it; enabling is the user's conscious step
+in that tab.
+
 ## Diagnosing failed pushes and cloud builds (hard rule)
 
 Diagnose **only from evidence**: the preflight output of \`agentful push\`, and
@@ -6296,11 +6384,11 @@ function buildEngineConfig(opts) {
   };
 }
 function engineXdg() {
-  const root = (0, import_node_path12.join)((0, import_node_os5.homedir)(), ".local", "share", "agentful");
+  const root = (0, import_node_path13.join)((0, import_node_os5.homedir)(), ".local", "share", "agentful");
   return {
-    configHome: (0, import_node_path12.join)(root, "engine-config"),
-    dataHome: (0, import_node_path12.join)(root, "engine-data"),
-    stateHome: (0, import_node_path12.join)(root, "engine-state")
+    configHome: (0, import_node_path13.join)(root, "engine-config"),
+    dataHome: (0, import_node_path13.join)(root, "engine-data"),
+    stateHome: (0, import_node_path13.join)(root, "engine-state")
   };
 }
 async function resolveTheme() {
@@ -6319,24 +6407,24 @@ async function resolveTheme() {
 }
 async function writeEngineSession(session, catalog, localProviders = {}, framework = "unknown", skillsInstruction = null) {
   const xdg = engineXdg();
-  const configDir2 = (0, import_node_path12.join)(xdg.configHome, "opencode");
-  const dataDir = (0, import_node_path12.join)(xdg.dataHome, "opencode");
-  const themesDir = (0, import_node_path12.join)(configDir2, "themes");
-  const pluginsDir = (0, import_node_path12.join)(configDir2, "plugins");
-  const commandsDir = (0, import_node_path12.join)(configDir2, "commands");
-  for (const dir of [themesDir, pluginsDir, commandsDir, dataDir, (0, import_node_path12.join)(xdg.stateHome, "opencode")]) {
-    (0, import_node_fs10.mkdirSync)(dir, { recursive: true });
+  const configDir2 = (0, import_node_path13.join)(xdg.configHome, "opencode");
+  const dataDir = (0, import_node_path13.join)(xdg.dataHome, "opencode");
+  const themesDir = (0, import_node_path13.join)(configDir2, "themes");
+  const pluginsDir = (0, import_node_path13.join)(configDir2, "plugins");
+  const commandsDir = (0, import_node_path13.join)(configDir2, "commands");
+  for (const dir of [themesDir, pluginsDir, commandsDir, dataDir, (0, import_node_path13.join)(xdg.stateHome, "opencode")]) {
+    (0, import_node_fs11.mkdirSync)(dir, { recursive: true });
   }
   const imagegenAvailable = installEngineTools(configDir2) && session.img_on !== false;
-  const cloudInstructionsPath = (0, import_node_path12.join)(configDir2, CLOUD_INSTRUCTIONS_FILENAME);
-  (0, import_node_fs10.writeFileSync)(cloudInstructionsPath, renderCloudInstructions(framework));
-  const skillsPath = (0, import_node_path12.join)(configDir2, "AGENTFUL_SKILLS.md");
+  const cloudInstructionsPath = (0, import_node_path13.join)(configDir2, CLOUD_INSTRUCTIONS_FILENAME);
+  (0, import_node_fs11.writeFileSync)(cloudInstructionsPath, renderCloudInstructions(framework));
+  const skillsPath = (0, import_node_path13.join)(configDir2, "AGENTFUL_SKILLS.md");
   const instructionPaths = [cloudInstructionsPath];
   if (skillsInstruction) {
-    (0, import_node_fs10.writeFileSync)(skillsPath, skillsInstruction);
+    (0, import_node_fs11.writeFileSync)(skillsPath, skillsInstruction);
     instructionPaths.push(skillsPath);
   } else {
-    (0, import_node_fs10.rmSync)(skillsPath, { force: true });
+    (0, import_node_fs11.rmSync)(skillsPath, { force: true });
   }
   const config = buildEngineConfig({
     session,
@@ -6345,24 +6433,24 @@ async function writeEngineSession(session, catalog, localProviders = {}, framewo
     imagegenAvailable,
     instructionPaths
   });
-  (0, import_node_fs10.writeFileSync)((0, import_node_path12.join)(configDir2, "config.json"), JSON.stringify(config, null, 2));
-  (0, import_node_fs10.writeFileSync)((0, import_node_path12.join)(dataDir, "auth.json"), JSON.stringify({
+  (0, import_node_fs11.writeFileSync)((0, import_node_path13.join)(configDir2, "config.json"), JSON.stringify(config, null, 2));
+  (0, import_node_fs11.writeFileSync)((0, import_node_path13.join)(dataDir, "auth.json"), JSON.stringify({
     [PROVIDER_ID]: { apiKey: session.token }
   }, null, 2));
   const { brandingPluginSource: brandingPluginSource2 } = await Promise.resolve().then(() => (init_plugin(), plugin_exports));
-  const pluginPath = (0, import_node_path12.join)(pluginsDir, "agentful-branding.tsx");
-  (0, import_node_fs10.writeFileSync)(pluginPath, brandingPluginSource2());
-  (0, import_node_fs10.writeFileSync)((0, import_node_path12.join)(configDir2, "tui.json"), JSON.stringify({
+  const pluginPath = (0, import_node_path13.join)(pluginsDir, "agentful-branding.tsx");
+  (0, import_node_fs11.writeFileSync)(pluginPath, brandingPluginSource2());
+  (0, import_node_fs11.writeFileSync)((0, import_node_path13.join)(configDir2, "tui.json"), JSON.stringify({
     theme: "agentful",
     plugin: [`file://${pluginPath}`]
   }, null, 2));
-  (0, import_node_fs10.writeFileSync)((0, import_node_path12.join)(themesDir, "agentful.json"), JSON.stringify(await resolveTheme(), null, 2));
+  (0, import_node_fs11.writeFileSync)((0, import_node_path13.join)(themesDir, "agentful.json"), JSON.stringify(await resolveTheme(), null, 2));
   for (const name of Object.keys(SLASH_COMMANDS)) {
-    (0, import_node_fs10.writeFileSync)((0, import_node_path12.join)(commandsDir, `${name}.md`), commandMarkdown(name));
+    (0, import_node_fs11.writeFileSync)((0, import_node_path13.join)(commandsDir, `${name}.md`), commandMarkdown(name));
   }
   for (const legacy of ["xdg-config", "xdg-data", "xdg-state"]) {
     try {
-      (0, import_node_fs10.rmSync)((0, import_node_path12.join)((0, import_node_os5.homedir)(), ".local", "share", "agentful", legacy), { recursive: true, force: true });
+      (0, import_node_fs11.rmSync)((0, import_node_path13.join)((0, import_node_os5.homedir)(), ".local", "share", "agentful", legacy), { recursive: true, force: true });
     } catch {
     }
   }
@@ -6370,8 +6458,8 @@ async function writeEngineSession(session, catalog, localProviders = {}, framewo
 }
 
 // src/lib/skills.ts
-var import_node_fs11 = require("fs");
-var import_node_path13 = require("path");
+var import_node_fs12 = require("fs");
+var import_node_path14 = require("path");
 
 // src/generated/skills.json
 var skills_default = {
@@ -6398,7 +6486,7 @@ var SCAFFOLD_BY_FRAMEWORK = {
 };
 function hasVueDependency(rootDir) {
   try {
-    const pkg = JSON.parse((0, import_node_fs11.readFileSync)((0, import_node_path13.join)(rootDir, "package.json"), "utf8"));
+    const pkg = JSON.parse((0, import_node_fs12.readFileSync)((0, import_node_path14.join)(rootDir, "package.json"), "utf8"));
     return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }["vue"]);
   } catch {
     return false;
@@ -6426,7 +6514,7 @@ function renderSkillsInstruction(names) {
   return "# Platform deployment skills (mandatory)\n\nThese are the same skills the cloud build agent loads for this stack.\nFollow them when scaffolding or editing \u2014 they are not optional hints.\n\n" + sections.join("\n\n---\n\n") + "\n";
 }
 function skillsInstructionFor(framework, rootDir) {
-  if (!(0, import_node_fs11.existsSync)(rootDir)) return null;
+  if (!(0, import_node_fs12.existsSync)(rootDir)) return null;
   return renderSkillsInstruction(selectSkills(framework, rootDir));
 }
 
@@ -6541,15 +6629,15 @@ function decideLocalProviders(policy) {
 }
 
 // src/lib/localProviders.ts
-var import_node_fs12 = require("fs");
-var import_node_path14 = require("path");
+var import_node_fs13 = require("fs");
+var import_node_path15 = require("path");
 var LOCAL_PROVIDERS_FILE = "local-providers.json";
 function localProvidersPath() {
-  return (0, import_node_path14.join)(configDir(), LOCAL_PROVIDERS_FILE);
+  return (0, import_node_path15.join)(configDir(), LOCAL_PROVIDERS_FILE);
 }
 function readLocalProviders() {
   try {
-    const raw = JSON.parse((0, import_node_fs12.readFileSync)(localProvidersPath(), "utf8"));
+    const raw = JSON.parse((0, import_node_fs13.readFileSync)(localProvidersPath(), "utf8"));
     if (raw && typeof raw === "object" && !Array.isArray(raw)) {
       const map = raw.providers && typeof raw.providers === "object" ? raw.providers : raw;
       const usable = {};
@@ -6584,8 +6672,8 @@ function resolveLocalProviders(policy) {
 }
 function writeLocalProvidersExample() {
   const path = localProvidersPath();
-  if ((0, import_node_fs12.existsSync)(path)) return path;
-  (0, import_node_fs12.mkdirSync)(configDir(), { recursive: true });
+  if ((0, import_node_fs13.existsSync)(path)) return path;
+  (0, import_node_fs13.mkdirSync)(configDir(), { recursive: true });
   const example = {
     _comment: 'Providers with your own API key, running locally. Requests go directly to the provider \u2014 no Agentful credits, no platform region guarantee. Remove the leading underscore from "_anthropic" and fill in your key to enable it.',
     _anthropic: {
@@ -6595,21 +6683,21 @@ function writeLocalProvidersExample() {
       models: { "claude-sonnet-4-5": { name: "Claude Sonnet 4.5 (my key)" } }
     }
   };
-  (0, import_node_fs12.writeFileSync)(path, JSON.stringify(example, null, 2) + "\n", "utf8");
+  (0, import_node_fs13.writeFileSync)(path, JSON.stringify(example, null, 2) + "\n", "utf8");
   try {
-    (0, import_node_fs12.chmodSync)(path, 384);
+    (0, import_node_fs13.chmodSync)(path, 384);
   } catch {
   }
   return path;
 }
 
 // src/lib/sessions.ts
-var import_node_fs13 = require("fs");
-var import_node_path15 = require("path");
+var import_node_fs14 = require("fs");
+var import_node_path16 = require("path");
 var import_node_child_process4 = require("child_process");
 function lastSessionForDirectory(cwd = process.cwd()) {
-  const dbPath = (0, import_node_path15.join)(engineXdg().dataHome, "opencode", "opencode.db");
-  if (!(0, import_node_fs13.existsSync)(dbPath)) return null;
+  const dbPath = (0, import_node_path16.join)(engineXdg().dataHome, "opencode", "opencode.db");
+  if (!(0, import_node_fs14.existsSync)(dbPath)) return null;
   const escaped = cwd.replace(/'/g, "''");
   const res = (0, import_node_child_process4.spawnSync)(
     "sqlite3",
@@ -6688,7 +6776,7 @@ async function tuiCommand(opts = {}) {
   }
   console.log("");
   if (process.stdout.isTTY) process.stdout.write(`\x1B]0;${brand.displayName}\x07`);
-  const code = await new Promise((resolve) => {
+  const code = await new Promise((resolve2) => {
     const engineArgs = opts.session ? ["--session", opts.session] : [];
     const child = (0, import_node_child_process5.spawn)(binPath, engineArgs, {
       stdio: "inherit",
@@ -6697,7 +6785,7 @@ async function tuiCommand(opts = {}) {
         ...process.env,
         // Slash commands run `agentful …` through the agent's bash tool, which
         // has no access to the user's shell aliases.
-        PATH: `${binDir}${import_node_path16.delimiter}${process.env.PATH || ""}`,
+        PATH: `${binDir}${import_node_path17.delimiter}${process.env.PATH || ""}`,
         XDG_CONFIG_HOME: xdg.configHome,
         XDG_DATA_HOME: xdg.dataHome,
         XDG_STATE_HOME: xdg.stateHome,
@@ -6715,10 +6803,10 @@ async function tuiCommand(opts = {}) {
         ...session.image_model ? { IMAGE_MODEL: session.image_model } : {}
       }
     });
-    child.on("exit", (c) => resolve(c ?? 0));
+    child.on("exit", (c) => resolve2(c ?? 0));
     child.on("error", (err2) => {
       ui.fail(`Could not start the engine: ${err2.message}`);
-      resolve(1);
+      resolve2(1);
     });
   });
   try {
@@ -6802,28 +6890,28 @@ async function shareCommand(opts) {
 }
 
 // src/commands/pull.ts
-var import_node_fs14 = require("fs");
-var import_node_path17 = require("path");
+var import_node_fs15 = require("fs");
+var import_node_path18 = require("path");
 init_branding();
 init_branding();
 function isProbablyBase64Binary(path) {
   return /\.(png|jpe?g|gif|webp|ico|woff2?|ttf|otf|eot|pdf|zip|mp[34]|webm|avif)$/i.test(path);
 }
 function writeEntry(root, rel, value) {
-  const target = (0, import_node_path17.join)(root, rel);
-  (0, import_node_fs14.mkdirSync)((0, import_node_path17.dirname)(target), { recursive: true });
+  const target = (0, import_node_path18.join)(root, rel);
+  (0, import_node_fs15.mkdirSync)((0, import_node_path18.dirname)(target), { recursive: true });
   const content = typeof value === "object" && value !== null && "content" in value ? String(value.content) : String(value ?? "");
   if (isProbablyBase64Binary(rel)) {
-    (0, import_node_fs14.writeFileSync)(target, Buffer.from(content, "base64"));
+    (0, import_node_fs15.writeFileSync)(target, Buffer.from(content, "base64"));
   } else {
-    (0, import_node_fs14.writeFileSync)(target, content, "utf8");
+    (0, import_node_fs15.writeFileSync)(target, content, "utf8");
   }
 }
 async function pullCommand(opts) {
   console.log(banner());
   const auth = await ensureAuth();
   const project = requireProject();
-  const nonHidden = (0, import_node_fs14.readdirSync)(process.cwd()).filter((n) => n !== ".agentful" && !n.startsWith("."));
+  const nonHidden = (0, import_node_fs15.readdirSync)(process.cwd()).filter((n) => n !== ".agentful" && !n.startsWith("."));
   if (nonHidden.length > 0 && !opts.force) {
     throw new ApiError(
       0,
@@ -6847,9 +6935,9 @@ async function pullCommand(opts) {
         ui.warn(`Skipped ${rel} (HTTP ${resp.status})`);
         continue;
       }
-      const target = (0, import_node_path17.join)(process.cwd(), rel);
-      (0, import_node_fs14.mkdirSync)((0, import_node_path17.dirname)(target), { recursive: true });
-      (0, import_node_fs14.writeFileSync)(target, Buffer.from(await resp.arrayBuffer()));
+      const target = (0, import_node_path18.join)(process.cwd(), rel);
+      (0, import_node_fs15.mkdirSync)((0, import_node_path18.dirname)(target), { recursive: true });
+      (0, import_node_fs15.writeFileSync)(target, Buffer.from(await resp.arrayBuffer()));
       written++;
     }
   } else if (data.files) {
@@ -6992,9 +7080,10 @@ program2.name("agentful").description("Agentful in your terminal \u2014 local de
 program2.command("login").description("Sign in to your Agentful account (device flow)").option("--no-browser", "do not open the browser automatically").action(run((opts) => loginCommand({ browser: opts.browser !== false })));
 program2.command("logout").description("Remove the stored credentials").action(run(logoutCommand));
 program2.command("whoami").description("Show the signed-in account").action(run(whoamiCommand));
-program2.command("init").description("Create (or link) the Agentful cloud project for this directory").option("--link <projectId>", "link an existing project instead of creating one").option("--title <title>", "project title (skips the prompt)").option("--template <framework>", "scaffold this empty directory from a platform starter (nextjs, react, vue, vanilla)").action(run((opts) => initCommand(opts)));
+program2.command("init").description("Create (or link) the Agentful cloud project for this directory").argument("[directory]", "with --template: new folder to scaffold into (created for you)").option("--link <projectId>", "link an existing project instead of creating one").option("--title <title>", "project title (skips the prompt)").option("--template <framework>", "scaffold from a platform starter (nextjs, react, vue, vanilla)").action(run((directory, opts) => initCommand(opts, directory)));
 program2.command("push").description("Upload this project and get a live preview URL").option("--prebuilt", "upload a locally built output instead of building in the cloud").option("--dir <path>", "built-output directory for --prebuilt (default: auto-detect)").option("--force", "push even when the pre-upload compatibility check finds blocking issues").action(run((opts) => pushCommand(opts)));
 program2.command("build-status").description("Show the cloud's record of the last build (the real error on failures)").action(run(buildStatusCommand));
+program2.command("backend").description("Open this project's Backend tab (managed DB + server actions) in the browser").action(run(backendCommand));
 program2.command("open").description("Open the live preview in the browser").action(run(openCommand));
 program2.command("tui").description("Start the Agentful coding TUI with your Agentful account").option("-s, --session <id>", "resume a previous session").action(run((opts) => tuiCommand(opts)));
 program2.command("publish <subdomain>").description("Publish the built project at https://<subdomain>.agentful.dev").action(run(publishCommand));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentful",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Agentful in your terminal — local development with push-to-cloud previews",
   "license": "Apache-2.0",
   "homepage": "https://agentful.dev",