agentful 0.4.14 → 0.4.16

package/README.md

@@ -26,7 +26,7 @@ agentful open               # open the preview
 | `login` / `logout` / `whoami` | Browser-based sign-in; the token is kept in the macOS Keychain (on Linux: a `0600` file under `~/.config/agentful/`) |
 | `init [--link <id>] [--title <t>]` | Create a cloud project or link an existing one (`.agentful/project.json`) |
 | `push [--prebuilt [--dir <path>]]` | Upload the source and build in the cloud; `--prebuilt` uploads a local build |
-| `push --dry-run [--json]` | Analyse what a push would upload and what would block it — uploads nothing |
+| `push --dry-run [--json [--summary]]` | Analyse what a push would upload and what would block it — uploads nothing |
 | `open` | Open the live preview |
 | `share [--private]` | Make the preview public, or private again |
 | `publish <subdomain>` | Publish at `https://<subdomain>.agentful.page` |
@@ -39,6 +39,9 @@ agentful open               # open the preview
 
 Inside the interface, `/` lists the Agentful commands (`/setup`, `/push`,
 `/preview`, `/publish`, `/share`, `/status`) alongside the built-in ones.
+`/push` checks before it uploads: the agent reads the same analysis as
+`push --dry-run`, explains what would block the upload or go missing on the
+site, and asks you before it changes a file or pushes.
 
 `push` respects your `.gitignore` and always excludes `.git`, `node_modules`,
 build output and every `.env` file. A push carries at most about 4.4 MiB
@@ -48,10 +51,14 @@ in or creates a project.
 
 `agentful push --dry-run` shows that check on its own: what would be uploaded
 and what is left out, the largest files, identical copies, media embedded in
-HTML, and every reason the upload would be rejected. It uploads nothing,
-creates no project and changes no file; it exits with 1 when the push would be
-blocked. `--dry-run --json` prints the same analysis as one JSON document
-(`"schema": "agentful.push-analysis"`) for scripts and agents.
+HTML, and every reason the upload would be rejected. A file that is larger
+than a whole push on its own is named as such: it cannot be uploaded at all,
+whatever else is left out. It uploads nothing, creates no project and changes
+no file; it exits with 1 when the push would be blocked. `--dry-run --json`
+prints the same analysis as one JSON document
+(`"schema": "agentful.push-analysis"`) for scripts and agents; with `--summary`
+it leaves out the list of every file, keeps totals, limits and findings, and
+prints every size as text next to its byte count.
 
 ## What you can deploy
 

package/dist/index.cjs

@@ -3044,7 +3044,7 @@ var VERSION, brand, useColor, wrap, paint, tuiDesign, sym, ui;
 var init_branding = __esm({
   "src/branding.ts"() {
     "use strict";
-    VERSION = "0.4.14" ? "0.4.14" : null.version;
+    VERSION = "0.4.16" ? "0.4.16" : null.version;
     brand = {
       name: "agentful",
       // the command users type
@@ -6561,7 +6561,7 @@ function formatBytes(bytes2, rounding = "nearest") {
   }
   if (unit === 0 || Number.isInteger(value)) return `${value} ${units[unit]}`;
   const tenths = value * 10;
-  const rounded = (rounding === "down" ? Math.floor(tenths) : Math.round(tenths)) / 10;
+  const rounded = (rounding === "down" ? Math.floor(tenths) : rounding === "up" ? Math.ceil(tenths) : Math.round(tenths)) / 10;
   return `${rounded.toFixed(1)} ${units[unit]}`;
 }
 function sizeOverLimit(bytes2, limit) {
@@ -6606,6 +6606,7 @@ function failedAnalysis(mode, projectDir, blocker) {
     schema: ANALYSIS_SCHEMA,
     schema_version: ANALYSIS_SCHEMA_VERSION,
     cli_version: VERSION,
+    view: "full",
     mode,
     root: null,
     ok: false,
@@ -6727,6 +6728,10 @@ function analyzePush(options) {
   }
   duplicates.sort((a, b) => b.redundant_zip_bytes - a.redundant_zip_bytes || (a.paths[0] < b.paths[0] ? -1 : 1));
   const redundantZipBytes = duplicates.reduce((total, group) => total + group.redundant_zip_bytes, 0);
+  const maxZipBytes = maxZipBytesForUpload(mode, mode === "source" ? readBackendDeclaration(rootDir) : null);
+  const oversized = measured.filter((file) => file.zipLower > maxZipBytes).sort((a, b) => b.zipLower - a.zipLower || byPath(a, b));
+  const oversizedPaths = new Set(oversized.map((file) => file.path));
+  const restZipLower = zipLower - oversized.reduce((total, file) => total + file.zipLower, 0);
   const preflight = mode === "source" ? runPreflight(rootDir) : null;
   const framework = preflight?.framework ?? null;
   const hasManifest = storedNames.has("package.json");
@@ -6738,12 +6743,14 @@ function analyzePush(options) {
     return {
       path: file.path,
       bytes: file.bytes,
+      zip_bytes: file.zip_bytes,
       title: file.title,
       sha256: file.sha256,
-      same_content_as: first && first !== file.path ? first : null
+      same_content_as: first && first !== file.path ? first : null,
+      ...file.zipLower > maxZipBytes ? { larger_than_a_push: true } : {}
     };
   });
-  const maxZipBytes = maxZipBytesForUpload(mode, mode === "source" ? readBackendDeclaration(rootDir) : null);
+  const fittingCandidates = candidates.filter((candidate) => !candidate.larger_than_a_push);
   const zipLimit = formatBytes(maxZipBytes, "down");
   const blockers = [];
   const warnings = [];
@@ -6781,10 +6788,18 @@ function analyzePush(options) {
   }
   if (zipLower > maxZipBytes) {
     const [size, allowed] = sizeOverLimit(zipExact ? zipBytes : zipLower, maxZipBytes);
+    let message = `The upload is ${zipExact ? "" : "at least "}${size} compressed \u2014 a push carries at most ${allowed} compressed.`;
+    if (oversized.length > 0) {
+      const one = oversized.length === 1;
+      const named = samplePaths(oversized.map((file) => `${file.path} (${sizeOverLimit(file.zipLower, maxZipBytes)[0]})`));
+      message += one ? ` ${named} is larger than that on its own, so no push can carry it.` : ` ${plural(oversized.length, "file")} are each larger than that on their own, so no push can carry them: ${named}.`;
+      message += ` Without ${one ? "it" : "them"} the upload is ${restZipLower > maxZipBytes ? `still ${sizeOverLimit(restZipLower, maxZipBytes)[0]} compressed` : `${formatBytes(restZipLower)} compressed, which is within that limit`}.`;
+    }
     blockers.push({
       code: "zip_too_large",
       overridable: false,
-      message: `The upload is ${zipExact ? "" : "at least "}${size} compressed \u2014 a push carries at most ${allowed} compressed.`
+      message,
+      ...oversized.length > 0 ? { paths: oversized.map((file) => file.path).slice(0, FINDING_PATHS) } : {}
     });
   } else if (!zipExact && zipBytes > maxZipBytes) {
     warnings.push({
@@ -6793,10 +6808,12 @@ function analyzePush(options) {
     });
   }
   if (entryMissing) {
+    const tooBig = candidates.filter((candidate) => candidate.larger_than_a_push);
+    const cannotBecomeIt = tooBig.length === 0 ? "" : fittingCandidates.length === 0 ? candidates.length === 1 ? " The one HTML file here cannot become it as it is: it is larger than a whole push." : ` None of the ${candidates.length} HTML files here can become it as they are: each is larger than a whole push.` : ` ${tooBig.length} of the ${candidates.length} HTML files here cannot become it as ${tooBig.length === 1 ? "it is" : "they are"}, larger than a whole push: ${samplePaths(tooBig.map((candidate) => candidate.path))}.`;
     blockers.push({
       code: "entry_missing",
       overridable: false,
-      message: mode === "dist" ? `No index.html at the top level of ${dirLabel === "." ? "the uploaded folder" : `${dirLabel}/`}. A prebuilt upload is served as it is, and index.html is its start page.` : "No index.html at the top level. Without a package.json this is a static site, and the platform serves index.html as its start page."
+      message: (mode === "dist" ? `No index.html at the top level of ${dirLabel === "." ? "the uploaded folder" : `${dirLabel}/`}. A prebuilt upload is served as it is, and index.html is its start page.` : "No index.html at the top level. Without a package.json this is a static site, and the platform serves index.html as its start page.") + cannotBecomeIt
     });
   }
   const backend = mode === "source" ? checkBackendDeclaration(rootDir) : null;
@@ -6837,11 +6854,11 @@ function analyzePush(options) {
   }
   const tooLarge = blockers.some((b) => b.code === "zip_too_large" || b.code === "unpacked_too_large");
   if (entryMissing) {
-    if (candidates.length > 0) {
+    if (fittingCandidates.length > 0) {
       suggestions.push({
         code: "name_start_page",
         message: "Rename or copy the page that should open first to index.html at the top level, check that its relative links still resolve, then push again.",
-        paths: candidates.map((candidate) => candidate.path).slice(0, FINDING_PATHS)
+        paths: fittingCandidates.map((candidate) => candidate.path).slice(0, FINDING_PATHS)
       });
     }
     const siteDirs = /* @__PURE__ */ new Set();
@@ -6863,29 +6880,31 @@ function analyzePush(options) {
     }
   }
   if (tooLarge) {
-    const oversized = measured.filter((file) => file.zipLower > maxZipBytes).sort((a, b) => b.bytes - a.bytes || byPath(a, b));
-    if (oversized.length > 0) {
-      suggestions.push({
-        code: "oversized_files",
-        message: `${samplePaths(oversized.map((file) => `${file.path} (${formatBytes(file.zipLower)} compressed)`))} ${oversized.length === 1 ? "is" : "are each"} larger than a whole push can carry. The upload cannot fit while ${oversized.length === 1 ? "it is" : "they are"} part of it.`,
-        paths: oversized.map((file) => file.path).slice(0, FINDING_PATHS)
-      });
-    }
-    if (duplicates.length > 0 && redundantZipBytes >= zipBytes / 20) {
-      const copies = duplicates.reduce((total, group) => total + group.paths.length - 1, 0);
-      const remaining = zipBytes - redundantZipBytes;
+    const overZip = zipLower - maxZipBytes;
+    const overFiles = storedBytes - MAX_UNPACKED_BYTES;
+    const mustStayOut = [
+      overZip > 0 ? `${formatBytes(overZip, "up")} of the ${formatBytes(zipLower)} compressed` : "",
+      overFiles > 0 ? `${formatBytes(overFiles, "up")} of the ${formatBytes(storedBytes)} of files` : ""
+    ].filter(Boolean);
+    const toFit = ` To fit, at least ${mustStayOut.join(" and ")} ${mustStayOut.length > 1 ? "have" : "has"} to stay out.`;
+    const spareCopies = duplicates.filter((group) => !oversizedPaths.has(group.paths[0]));
+    const spareZipBytes = spareCopies.reduce((total, group) => total + group.redundant_zip_bytes, 0);
+    const base = oversized.length > 0 ? restZipLower : zipBytes;
+    if (spareCopies.length > 0 && spareZipBytes >= base / 20) {
+      const copies = spareCopies.reduce((total, group) => total + group.paths.length - 1, 0);
+      const remaining = base - spareZipBytes;
       suggestions.push({
         code: "remove_identical_copies",
-        message: `${plural(copies, "file is an identical copy", "files are identical copies")} of another file and ${copies === 1 ? "adds" : "add"} ${formatBytes(redundantZipBytes)} to the compressed upload. If nothing links to the extra names, one copy each brings it to ${formatBytes(remaining)}${remaining > maxZipBytes ? ` \u2014 still above the ${zipLimit} limit` : ""}.`,
-        paths: duplicates.flatMap((group) => group.paths.slice(1)).slice(0, FINDING_PATHS)
+        message: `${plural(copies, "file is an identical copy", "files are identical copies")} of another file and ${copies === 1 ? "adds" : "add"} ${formatBytes(spareZipBytes)} to the compressed upload. If nothing links to the extra names, one copy each brings ${oversized.length > 0 ? "what is left without the files no push can carry" : "it"} to ${formatBytes(remaining)}${remaining > maxZipBytes ? ` \u2014 still above the ${zipLimit} limit` : ""}.`,
+        paths: spareCopies.flatMap((group) => group.paths.slice(1)).slice(0, FINDING_PATHS)
       });
     }
     suggestions.push(mode === "source" ? {
       code: "exclude_with_gitignore",
-      message: "Files and folders listed in .gitignore are not uploaded. Leave out what the site does not serve \u2014 originals, working files, exports."
+      message: `Files and folders listed in .gitignore are not uploaded. Leave out what the site does not serve \u2014 originals, working files, exports.${toFit}`
     } : {
       code: "narrow_prebuilt_directory",
-      message: "A prebuilt upload takes every file in the folder. Put the finished site into a folder of its own and pass it with --dir."
+      message: `A prebuilt upload takes every file in the folder. Put the finished site into a folder of its own and pass it with --dir.${toFit}`
     });
     suggestions.push({
       code: "upload_limit",
@@ -6911,6 +6930,7 @@ function analyzePush(options) {
     schema: ANALYSIS_SCHEMA,
     schema_version: ANALYSIS_SCHEMA_VERSION,
     cli_version: VERSION,
+    view: "full",
     mode,
     root: rootDir,
     ok: blockers.length === 0,
@@ -6947,6 +6967,93 @@ function analyzePush(options) {
     fingerprint: `sha256:${fingerprint}`
   };
 }
+var SUMMARY_LISTS = {
+  largest_files: 8,
+  by_top_level: 8,
+  duplicates: 8,
+  duplicate_paths: 8,
+  embedded_media: 8,
+  entry_candidates: 20,
+  excluded_entries: 30,
+  dropped_by_platform: 20,
+  finding_paths: 8
+};
+var SUMMARY_MAX_BYTES = 24 * 1024;
+var sizeLabelKey = (key) => key === "base64_chars" ? "base64_size" : /(^|_)bytes(_|$)/.test(key) ? key.replace("bytes", "size") : null;
+function withSizeLabels(value) {
+  if (Array.isArray(value)) return value.map(withSizeLabels);
+  if (!value || typeof value !== "object") return value;
+  const labelled = {};
+  for (const [key, inner] of Object.entries(value)) {
+    labelled[key] = withSizeLabels(inner);
+    const label = typeof inner === "number" ? sizeLabelKey(key) : null;
+    if (label) labelled[label] = formatBytes(inner, key.startsWith("max_") ? "down" : "nearest");
+  }
+  return labelled;
+}
+var printAnalysis = (analysis) => `${JSON.stringify(analysis.view === "summary" ? withSizeLabels(analysis) : analysis, null, 2)}
+`;
+function summarize(analysis, divisor) {
+  const shortened = {};
+  const cut = (name, list, cap, alreadyOmitted = 0) => {
+    const keep = Math.max(1, Math.floor(cap / divisor));
+    const omitted = Math.max(0, list.length - keep) + alreadyOmitted;
+    if (omitted > 0) shortened[name] = (shortened[name] ?? 0) + omitted;
+    return list.slice(0, keep);
+  };
+  const finding = (kind) => (item) => item.paths ? { ...item, paths: cut(`${kind}.paths`, item.paths, SUMMARY_LISTS.finding_paths) } : item;
+  if (analysis.totals.files > 0) shortened.files = analysis.totals.files;
+  const excludedEntries = cut(
+    "excluded.entries",
+    analysis.excluded.entries,
+    SUMMARY_LISTS.excluded_entries,
+    analysis.excluded.omitted
+  );
+  return {
+    schema: analysis.schema,
+    schema_version: analysis.schema_version,
+    cli_version: analysis.cli_version,
+    view: "summary",
+    shortened,
+    mode: analysis.mode,
+    root: analysis.root,
+    ok: analysis.ok,
+    framework: analysis.framework,
+    project: analysis.project,
+    limits: analysis.limits,
+    totals: analysis.totals,
+    blockers: analysis.blockers.map(finding("blockers")),
+    // The note about the cap of the full file list describes a list that is not here.
+    warnings: analysis.warnings.filter((warning) => warning.code !== "file_list_truncated").map(finding("warnings")),
+    suggestions: analysis.suggestions.map(finding("suggestions")),
+    entry: {
+      ...analysis.entry,
+      candidates: cut("entry.candidates", analysis.entry.candidates, SUMMARY_LISTS.entry_candidates)
+    },
+    flattened_prefix: analysis.flattened_prefix,
+    largest_files: cut("largest_files", analysis.largest_files, SUMMARY_LISTS.largest_files),
+    by_class: analysis.by_class,
+    by_top_level: cut("by_top_level", analysis.by_top_level, SUMMARY_LISTS.by_top_level),
+    duplicates: cut("duplicates", analysis.duplicates, SUMMARY_LISTS.duplicates).map((group) => ({ ...group, paths: cut("duplicates.paths", group.paths, SUMMARY_LISTS.duplicate_paths) })),
+    embedded_media: cut("embedded_media", analysis.embedded_media, SUMMARY_LISTS.embedded_media),
+    excluded: {
+      ...analysis.excluded,
+      entries: excludedEntries,
+      omitted: analysis.excluded.omitted + analysis.excluded.entries.length - excludedEntries.length
+    },
+    dropped_by_platform: cut("dropped_by_platform", analysis.dropped_by_platform, SUMMARY_LISTS.dropped_by_platform),
+    files: [],
+    files_omitted: analysis.totals.files,
+    fingerprint: analysis.fingerprint
+  };
+}
+function summarizeAnalysis(analysis) {
+  let summary = summarize(analysis, 1);
+  for (let divisor = 2; divisor <= 32 && Buffer.byteLength(printAnalysis(summary), "utf8") > SUMMARY_MAX_BYTES; divisor *= 2) {
+    summary = summarize(analysis, divisor);
+  }
+  return summary;
+}
 function wouldUpload(analysis, force = false) {
   return analysis.blockers.every((blocker) => blocker.overridable && force);
 }
@@ -7011,7 +7118,7 @@ function renderAnalysis(analysis, options = {}) {
         lines.push("  HTML files found:");
         for (const candidate of analysis.entry.candidates.slice(0, SHOWN_FILES)) {
           lines.push(
-            `  ${sizeColumn(candidate.bytes)}  ${candidate.path}` + (candidate.title ? paint.dim(`  "${candidate.title}"`) : "") + (candidate.same_content_as ? paint.dim(`  (same content as ${candidate.same_content_as})`) : "")
+            `  ${sizeColumn(candidate.bytes)}  ${candidate.path}` + (candidate.title ? paint.dim(`  "${candidate.title}"`) : "") + (candidate.same_content_as ? paint.dim(`  (same content as ${candidate.same_content_as})`) : "") + (candidate.larger_than_a_push ? paint.dim("  (larger than a whole push)") : "")
           );
         }
         lines.push(...more(analysis.entry.candidates.length, SHOWN_FILES, "HTML file"));
@@ -7425,6 +7532,13 @@ async function pushCommand(opts) {
       "--json belongs to --dry-run: `agentful push --dry-run --json` prints the upload analysis and uploads nothing."
     );
   }
+  if (opts.summary && !opts.json) {
+    throw new ApiError(
+      0,
+      "invalid_options",
+      "--summary belongs to --dry-run --json: it prints the analysis without the list of every file."
+    );
+  }
   if (!opts.json) console.log(banner());
   const mode = opts.prebuilt ? "dist" : "source";
   const cwd = process.cwd();
@@ -7438,8 +7552,7 @@ async function pushCommand(opts) {
     analysis = failedAnalysis(mode, cwd, { code: err2.code, message: err2.message });
   }
   if (opts.dryRun) {
-    if (opts.json) process.stdout.write(`${JSON.stringify(analysis, null, 2)}
-`);
+    if (opts.json) process.stdout.write(printAnalysis(opts.summary ? summarizeAnalysis(analysis) : analysis));
     else for (const line of renderAnalysis(analysis, { force: opts.force, dryRun: true })) console.log(line);
     if (!wouldUpload(analysis, opts.force)) process.exitCode = 1;
     return;
@@ -7968,75 +8081,6 @@ var agentful_theme_default = {
 
 // src/branding/commands.ts
 init_branding();
-var NEEDS_A_PUSH = 'If the command reports "No Agentful project here", nothing has been deployed from this directory yet \u2014 run `agentful push` first (it creates the project and a preview), then retry.';
-var SLASH_COMMANDS = {
-  setup: {
-    description: `${brand.displayName}: create or link the cloud project for this directory`,
-    template: 'Check whether .agentful/project.json exists. If it does, report the linked project title and id and stop. Otherwise run `agentful init --title "<name>"` using the bash tool, where <name> is $ARGUMENTS if I gave one, otherwise the current directory name. Report what it created and mention the title I can change it to. Do not modify any other project files.'
-  },
-  push: {
-    description: `${brand.displayName}: deploy this project and get a preview URL`,
-    template: "Run `agentful push` from the project root using the bash tool. It creates the project automatically if this directory is not linked yet. Stream what it prints, and when it finishes report the preview URL on its own line. If it fails: quote the printed error verbatim, and if the failure happened in the cloud (not in the pre-upload preflight), also run `agentful build-status` and quote its phase/error/details as the cause. Diagnose ONLY from those records \u2014 never invent causes, env vars, or settings they do not show. Do not modify project files unless I ask."
-  },
-  "build-status": {
-    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
-  },
-  publish: {
-    description: `${brand.displayName}: publish on a public subdomain`,
-    template: "Ask me for the subdomain if I did not provide one in $ARGUMENTS, then run `agentful publish <subdomain>` from the project root using the bash tool and report the public URL. " + NEEDS_A_PUSH
-  },
-  share: {
-    description: `${brand.displayName}: make the live preview public (or private again)`,
-    template: "Run `agentful share` from the project root using the bash tool (add `--private` if $ARGUMENTS says private) and report the resulting visibility and URL. " + NEEDS_A_PUSH
-  },
-  status: {
-    description: `${brand.displayName}: show the linked project and account`,
-    template: "Run `agentful whoami` using the bash tool. Then read .agentful/project.json and report the linked project title and id, plus the preview URL https://preview-<projectId>.agentful.page/. If the file does not exist, say that this directory is not linked yet and that `/setup` creates the link."
-  }
-};
-function commandMarkdown(name) {
-  const cmd = SLASH_COMMANDS[name];
-  const description = JSON.stringify(cmd.description);
-  return `---
-description: ${description}
-agent: ${cmd.agent ?? "agentful-build"}
----
-
-${cmd.template}
-`;
-}
-
-// src/lib/tools.ts
-var import_node_fs13 = require("fs");
-var import_node_path15 = require("path");
-function assetsDir() {
-  const here = (0, import_node_path15.dirname)(process.argv[1] || "");
-  for (const candidate of [(0, import_node_path15.join)(here, "..", "assets"), (0, import_node_path15.join)(here, "assets")]) {
-    if ((0, import_node_fs13.existsSync)((0, import_node_path15.join)(candidate, "tools", "imagegen.ts"))) return candidate;
-  }
-  return null;
-}
-function installEngineTools(configDir2) {
-  const assets = assetsDir();
-  if (!assets) return false;
-  const target = (0, import_node_path15.join)(configDir2, "tools");
-  (0, import_node_fs13.mkdirSync)(target, { recursive: true });
-  try {
-    (0, import_node_fs13.cpSync)((0, import_node_path15.join)(assets, "tools"), target, { recursive: true });
-    return true;
-  } catch {
-    return false;
-  }
-}
 
 // src/lib/cloudTarget.ts
 var CLOUD_INSTRUCTIONS_FILENAME = "AGENTFUL_CLOUD.md";
@@ -8146,6 +8190,104 @@ function serverSideSection() {
     )
   ].join("\n\n");
 }
+var PUSH_ANALYSIS_COMMAND = "agentful push --dry-run --json --summary";
+function pushSection() {
+  const excludedDirs = [...ALWAYS_EXCLUDE_DIRS].filter((name) => /^[a-z]/.test(name)).map((name) => `\`${name}\``).join(", ");
+  return `## Pushing to the platform (\`agentful push\`)
+
+Two ways to upload. Every push replaces the previous upload completely, so a
+site can never be uploaded in several parts.
+
+- **Source push**, \`agentful push\`: uploads this directory, then builds it in
+  the cloud. Never uploaded: paths listed in \`.gitignore\`, \`.env*\` files,
+  symlinks, tool folders such as \`.git\` or \`.next\`, and any folder named
+  ${excludedDirs}, at any depth.
+  The cloud build runs \`npm ci\` (with a \`package-lock.json\`, otherwise
+  \`npm install\`) and then the build command from the table above. Nothing
+  else runs: no other package manager, no separate data or prepare script, no
+  CI workflow step.
+- **Prebuilt push**, \`agentful push --prebuilt --dir <folder>\`: uploads a
+  finished output folder and serves it as it is. No cloud build, \`.gitignore\`
+  is not applied, and \`index.html\` must sit at the top of that folder. It
+  carries the website only: the project source in the cloud stays as it was (a
+  later build in the cloud workspace replaces the site with a build of that
+  source), and Managed Server Actions and \`.agentful/backend.json\` are NOT
+  deployed by it.
+
+Limits of one push, either way: about ${formatBytes(maxZipBytesForUpload(), "down")} compressed, ${formatBytes(MAX_UNPACKED_BYTES)} of files, ${MAX_UPLOAD_FILES.toLocaleString("en-US")} files.
+\`--force\` lifts none of them: it only lets the cloud build try despite a
+compatibility finding.
+
+**The analysis decides, not an estimate.** \`${PUSH_ANALYSIS_COMMAND}\`
+(with \`--prebuilt --dir <folder>\` for a prebuilt push) reads the files and
+reports what a push would upload: no sign-in, no project, no upload, nothing
+written. Sizes, limits, what is left out and what blocks the upload come from
+that report and from nowhere else: quote its figures, never estimate or
+recompute them. Next to every byte count the report prints the size as text
+(\`size\` for \`bytes\`, \`zip_size\` for \`zip_bytes\`): use that text, do not
+convert bytes yourself. \`limits.max_zip_bytes\` is the exact limit for this
+push. Run it before the first push of a session, after a push was stopped,
+and after you changed what gets uploaded. In between, \`agentful push\` applies the same
+check itself and stops before sign-in when something blocks. A blocker with
+\`"overridable": false\` is final, the platform rejects that upload: do not
+retry, do not add \`--force\`, do not look for another route.
+
+Every change to the user's files for a push (including \`.gitignore\`) and every
+project script you run for it needs the user's OK first: name the concrete
+change, ask, wait for the answer. One question per reply: one decision, not
+several joined together. Never ask what the report or the project files
+answer, such as whether a \`.gitignore\` is in effect
+(\`excluded.gitignore_applied\`), which files are large or which are copies.
+
+- **No start page** (\`entry_missing\`): the platform serves \`index.html\` from
+  the top level. With \`entry.candidates\`: show them (path and title;
+  \`same_content_as\` marks copies, \`larger_than_a_push\` marks pages no push
+  can carry: they cannot be the start page as they are, say so) and ask which
+  of the others opens first. A candidate at the top level can be renamed to
+  \`index.html\`, or copied, which keeps the old address and adds the file's
+  size to the upload: ask which. A candidate in a subfolder must not be copied
+  up, its relative links would break. If that folder is the whole site, push
+  the folder (\`suggestions\` carries the command); otherwise adjust the links
+  and show the diff. Without candidates, ask which folder holds the site.
+- **Too large or too many files** (\`zip_too_large\`, \`unpacked_too_large\`,
+  \`too_many_files\`): settle first whether the site can fit at all. The
+  \`zip_too_large\` blocker names the files that are each larger than a whole
+  push on their own (all of them in its \`paths\`), and its message says what
+  is left without them. Such a file can only stay out. If
+  the site needs one of them (the page the user wants as the start page, or a
+  file a page loads: search the sources for references), the site cannot be
+  pushed yet: say that plainly, with the file and its size. Do not offer
+  \`.gitignore\` or a prebuilt push as a way around it, neither lifts a limit,
+  and larger uploads are not available.
+  Where no such file is needed: explain where the size is, from
+  \`largest_files\`, \`by_top_level\`, \`duplicates\` and \`embedded_media\` (media
+  stored inside text files as \`data:\` URLs), and propose which files the site
+  does not load to leave out with \`.gitignore\`. The \`exclude_with_gitignore\`
+  suggestion says how much has to stay out; if the site needs more than fits,
+  say plainly that it cannot be pushed yet. Before proposing to leave a file
+  out, search the sources for references to it and say what you checked:
+  identical content does not make a copy unused. A prebuilt push is smaller
+  than a source push only where a build produces the output folder; a site
+  without a build step is the same upload either way. Never shrink,
+  re-encode, move or delete the user's files on your own.
+- **Compatibility findings** (\`"overridable": true\`): fix the cause in the
+  code. \`--force\` only when the user asks to try the cloud build anyway.
+- **Files that would be missing on the site:** the warnings
+  \`dropped_by_platform\` and \`excluded_static_directory\`, and entries of
+  \`excluded.entries\` with reason \`gitignore\` that the site loads at runtime
+  (generated data under \`public/\`, for example). The build can succeed and the
+  site still be broken: tell the user before pushing and ask.
+- **Steps the cloud build does not run:** before the first push of a project
+  you did not create in this session, read the \`package.json\` scripts, the
+  README and the CI workflows for data generation, code generation or another
+  package manager. If the site needs such a step, a source push is the wrong
+  way: build locally with the project's own commands and its real data, keep
+  its checks, and push the output folder prebuilt. Never put sample data in
+  place of real data to get a push through.
+
+A finished build or upload does not prove that the site works: say what you
+verified and what you did not.`;
+}
 function renderCloudInstructions(framework, backend) {
   return `# Agentful Cloud target (platform contract)
 
@@ -8300,6 +8442,8 @@ user's conscious step \u2014 in that tab, or by answering the question
 \`agentful push\` asks once (it names both consequences; a non-interactive
 push never enables anything).
 
+${pushSection()}
+
 ## Diagnosing failed pushes and cloud builds (hard rule)
 
 Diagnose **only from evidence**: the preflight output of \`agentful push\`, and
@@ -8318,6 +8462,93 @@ ${backendSessionLines(backend)}
 `;
 }
 
+// src/branding/commands.ts
+var PUSH_TOOL_TIMEOUT_MS = 9e5;
+var NEEDS_A_PUSH = 'If the command reports "No Agentful project here", nothing has been deployed from this directory yet \u2014 run `agentful push` first (it creates the project and a preview), then retry.';
+var SLASH_COMMANDS = {
+  setup: {
+    description: `${brand.displayName}: create or link the cloud project for this directory`,
+    template: 'Check whether .agentful/project.json exists. If it does, report the linked project title and id and stop. Otherwise run `agentful init --title "<name>"` using the bash tool, where <name> is $ARGUMENTS if I gave one, otherwise the current directory name. Report what it created and mention the title I can change it to. Do not modify any other project files.'
+  },
+  // The analysis comes first (upload plan AP7): the report, not the model,
+  // says what would be uploaded, how large it is and what blocks it, and the
+  // rules for acting on it are in AGENTFUL_CLOUD.md. Two things the agent's
+  // shell tool forces on this template: `--summary`, because the tool cuts
+  // output after 2,000 lines or 50 KB and the full report lists every file;
+  // and an explicit timeout, because the tool ends a command after two
+  // minutes by default and a cloud build takes longer (engine 1.18.32).
+  push: {
+    description: `${brand.displayName}: check, deploy and get a preview URL`,
+    template: `Deploy this project, following "Pushing to the platform" in AGENTFUL_CLOUD.md. Run every command from the project root using the bash tool. What I typed after the command (may be empty): "$ARGUMENTS". If it names \`--prebuilt\`, a folder for \`--dir\`, or \`--force\`, pass that on to both commands below.
+
+1. Run \`${PUSH_ANALYSIS_COMMAND}\`. It only reads files: no sign-in, no upload. Its JSON report is the only source for sizes, limits and what blocks the upload: quote its figures as printed (the \`size\` texts next to the byte counts), never estimate or convert them.
+2. If the report or the project calls for a decision (a blocker, a file the site needs that would not be uploaded, a build step the cloud does not run), explain the finding in plain words with the figures of the report. If the report shows that what I want to publish cannot fit (a page or file it needs is larger than a whole push, or it stays above the limits without the files it does not load), say that plainly and do not offer ways out that do not get it under the limits. Otherwise ask me how to proceed: exactly one question per reply, and never one the report or the project files answer. Then wait for my answer. Until then do not change any file, do not run project scripts and do not push.
+3. After a change I approved, run the analysis again.
+4. When nothing blocks, run \`agentful push\` with the bash tool's \`timeout\` set to ${PUSH_TOOL_TIMEOUT_MS} (milliseconds): the cloud build takes minutes and the default timeout would cut the push off halfway. The command never waits for input. It creates the project automatically if this directory is not linked yet.
+5. Report the preview URL on its own line and what the push printed about the backend. If it fails: quote the printed error verbatim, and if the failure happened in the cloud (not before the upload), also run \`agentful build-status\` and quote its phase/error/details as the cause. Diagnose ONLY from those records \u2014 never invent causes, env vars, or settings they do not show.
+
+Apart from a change I approved in step 2, do not modify project files.`
+  },
+  "build-status": {
+    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
+  },
+  publish: {
+    description: `${brand.displayName}: publish on a public subdomain`,
+    template: "Ask me for the subdomain if I did not provide one in $ARGUMENTS, then run `agentful publish <subdomain>` from the project root using the bash tool and report the public URL. " + NEEDS_A_PUSH
+  },
+  share: {
+    description: `${brand.displayName}: make the live preview public (or private again)`,
+    template: "Run `agentful share` from the project root using the bash tool (add `--private` if $ARGUMENTS says private) and report the resulting visibility and URL. " + NEEDS_A_PUSH
+  },
+  status: {
+    description: `${brand.displayName}: show the linked project and account`,
+    template: "Run `agentful whoami` using the bash tool. Then read .agentful/project.json and report the linked project title and id, plus the preview URL https://preview-<projectId>.agentful.page/. If the file does not exist, say that this directory is not linked yet and that `/setup` creates the link."
+  }
+};
+function commandMarkdown(name) {
+  const cmd = SLASH_COMMANDS[name];
+  const description = JSON.stringify(cmd.description);
+  return `---
+description: ${description}
+agent: ${cmd.agent ?? "agentful-build"}
+---
+
+${cmd.template}
+`;
+}
+
+// src/lib/tools.ts
+var import_node_fs13 = require("fs");
+var import_node_path15 = require("path");
+function assetsDir() {
+  const here = (0, import_node_path15.dirname)(process.argv[1] || "");
+  for (const candidate of [(0, import_node_path15.join)(here, "..", "assets"), (0, import_node_path15.join)(here, "assets")]) {
+    if ((0, import_node_fs13.existsSync)((0, import_node_path15.join)(candidate, "tools", "imagegen.ts"))) return candidate;
+  }
+  return null;
+}
+function installEngineTools(configDir2) {
+  const assets = assetsDir();
+  if (!assets) return false;
+  const target = (0, import_node_path15.join)(configDir2, "tools");
+  (0, import_node_fs13.mkdirSync)(target, { recursive: true });
+  try {
+    (0, import_node_fs13.cpSync)((0, import_node_path15.join)(assets, "tools"), target, { recursive: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/lib/engineConfig.ts
 var PROVIDER_ID = "agentful";
 var DISABLED_ENGINE_PLUGINS = {
@@ -8555,18 +8786,20 @@ var SCAFFOLD_BY_FRAMEWORK = {
   // cra/nuxt get no scaffold skill: the react/vue skills are Vite-specific
   // and would teach the wrong shape — the template contract still applies.
 };
-function hasVueDependency(rootDir) {
+function dependencies(rootDir) {
   try {
     const pkg = JSON.parse((0, import_node_fs15.readFileSync)((0, import_node_path17.join)(rootDir, "package.json"), "utf8"));
-    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }["vue"]);
+    return { ...pkg.dependencies, ...pkg.devDependencies };
   } catch {
-    return false;
+    return {};
   }
 }
 function selectSkills(framework, rootDir) {
   const names = [CONTRACT_SKILL];
   if (framework === "vite") {
-    names.push(hasVueDependency(rootDir) ? "vue-scaffold" : "react-scaffold");
+    const deps = dependencies(rootDir);
+    if (deps.vue) names.push("vue-scaffold");
+    else if (deps.react) names.push("react-scaffold");
   } else {
     const scaffold = SCAFFOLD_BY_FRAMEWORK[framework];
     if (scaffold) names.push(scaffold);
@@ -9895,7 +10128,7 @@ program2.command("login").description("Sign in to your Agentful account (device
 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").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").option("-y, --yes", "enable the declared managed database without asking (CI); a non-interactive push never enables it").option("--dry-run", "analyse only: what would be uploaded, how large, and what would block it \u2014 no sign-in, no project, no upload").option("--json", "with --dry-run: print the analysis as JSON (for scripts and agents)").action(run((opts) => pushCommand(opts)));
+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").option("-y, --yes", "enable the declared managed database without asking (CI); a non-interactive push never enables it").option("--dry-run", "analyse only: what would be uploaded, how large, and what would block it \u2014 no sign-in, no project, no upload").option("--json", "with --dry-run: print the analysis as JSON (for scripts and agents)").option("--summary", "with --dry-run --json: totals and findings without the list of every file").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));

package/package.json

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