@usefillo/cli 0.8.0 → 0.10.0

package/dist/index.js

@@ -1294,6 +1294,10 @@ function _default(innerType, defaultValue) {
 }
 
 // ../core/dist/index.js
+var CONTENT_KINDS = ["heading", "paragraph", "divider"];
+function isField(block) {
+  return !CONTENT_KINDS.includes(block.kind);
+}
 var C = (iso2, name, dialCode, lengths = [], groups = [], example = "") => ({ iso2, name, dialCode, lengths, groups, example });
 var PHONE_COUNTRIES = [
   C("US", "United States", "1", [10], [3, 3, 4], "2015550123"),
@@ -1415,7 +1419,11 @@ var blockSchema = looseObject({
 var pageSchema = object({
   id: idSchema,
   title: optional(string2().check(_maxLength(500))),
-  blocks: array(blockSchema).check(_maxLength(500))
+  blocks: array(blockSchema).check(_maxLength(500)),
+  // Optional conditional page flow. Kept as unknown here (this schema is strict,
+  // so it would otherwise be dropped at parse) and normalized by hand below once
+  // the page-id set is known — a jump to a missing page is dropped, never kept.
+  next: optional(unknown())
 });
 var schemaShape = object({
   version: literal(1),
@@ -1426,7 +1434,7 @@ var schemaShape = object({
 });
 var MAX_SCHEMA_VERSION = 1;
 var FILLO_SCHEMA_VERSION = 1;
-var FILLO_SDK_VERSION = true ? "0.8.0" : "0.0.0-dev";
+var FILLO_SDK_VERSION = true ? "0.10.0" : "0.0.0-dev";
 function str(value, max, fallback = "") {
   return typeof value === "string" ? value.trim().slice(0, max) : fallback;
 }
@@ -1481,6 +1489,23 @@ function conditions(value) {
   });
   return normalized.length ? normalized : void 0;
 }
+function jumpRules(value, pageIds, sourceId, allowedFieldIds) {
+  if (!Array.isArray(value)) return void 0;
+  const rules = value.slice(0, 50).flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const rec = item;
+    const to = typeof rec.to === "string" ? rec.to : void 0;
+    if (!to || to !== "end" && !pageIds.has(to)) return [];
+    if (to === sourceId) return [];
+    const rawWhen = rec.when;
+    if (rawWhen !== void 0 && !Array.isArray(rawWhen)) return [];
+    const when2 = conditions(rawWhen);
+    if (Array.isArray(rawWhen) && rawWhen.length > 0 && when2 === void 0) return [];
+    if (when2 && when2.some((c) => !allowedFieldIds.has(c.fieldId))) return [];
+    return [{ when: when2 ?? [], to }];
+  });
+  return rules.length ? rules : void 0;
+}
 function baseBlock(rec) {
   return {
     id: str(rec.id, 128),
@@ -1524,6 +1549,17 @@ function normalizeResponseLimit(value) {
     onRepeat
   };
 }
+function normalizeTrust(value) {
+  if (!value || typeof value !== "object") return void 0;
+  const rec = value;
+  const unverified = rec.unverified === "allow" || rec.unverified === "quarantine" ? rec.unverified : void 0;
+  const challenge = rec.challenge === "turnstile" ? "turnstile" : void 0;
+  if (!unverified && !challenge) return void 0;
+  return {
+    ...unverified ? { unverified } : {},
+    ...challenge ? { challenge } : {}
+  };
+}
 function normalizeSettings(value) {
   const rec = value && typeof value === "object" ? value : {};
   const submitMode = rec.submitMode === "button" || rec.submitMode === "auto" ? rec.submitMode : void 0;
@@ -1535,6 +1571,7 @@ function normalizeSettings(value) {
     redirectUrl: normalizeUrl(rec.redirectUrl),
     showProgress: bool(rec.showProgress),
     responseLimit: normalizeResponseLimit(rec.responseLimit),
+    trust: normalizeTrust(rec.trust),
     notifyEmail: email2().check(_maxLength(254)).safeParse(rec.notifyEmail).success ? rec.notifyEmail : void 0,
     sendReceipt: bool(rec.sendReceipt),
     saveProgress: bool(rec.saveProgress),
@@ -1674,15 +1711,24 @@ function normalizeFormSchema(input) {
   if (parsed.data.version > MAX_SCHEMA_VERSION) {
     return { ok: false, error: `Unsupported schema version: ${parsed.data.version}` };
   }
-  const pages = parsed.data.pages.map((page) => {
+  const rebuilt = parsed.data.pages.map((page) => {
     const blocks = page.blocks.flatMap((raw) => {
       const block = normalizeBlock(raw);
       return block ? [block] : [];
     });
+    return { id: str(page.id, 128), title: optionalStr(page.title, 500), blocks, next: page.next };
+  });
+  const targetIds = new Set(rebuilt.map((p) => p.id));
+  const priorFieldIds = /* @__PURE__ */ new Set();
+  const pages = rebuilt.map((page) => {
+    for (const block of page.blocks) {
+      if (isField(block)) priorFieldIds.add(block.id);
+    }
     return cleanObject({
-      id: str(page.id, 128),
-      title: optionalStr(page.title, 500),
-      blocks
+      id: page.id,
+      title: page.title,
+      blocks: page.blocks,
+      next: jumpRules(page.next, targetIds, page.id, new Set(priorFieldIds))
     });
   });
   const pageIds = /* @__PURE__ */ new Set();
@@ -1881,6 +1927,7 @@ function openBrowser(url) {
   } catch {
     return;
   }
+  if (process.env.CI === "true") return;
   try {
     if (process.platform === "win32") {
       const child = spawn("cmd", ["/c", "start", "", safeUrl], { stdio: "ignore", detached: true });
@@ -1917,7 +1964,7 @@ async function readJson(res) {
     die(`Unexpected non-JSON response from ${API} (${res.status}).`);
   }
 }
-async function login(flags) {
+async function login(flags, options2 = {}) {
   const apiBase = flagString(flags, "api")?.replace(/\/$/, "") ?? API;
   const run = flagString(flags, "run");
   const progressToken = flagString(flags, "token");
@@ -1966,7 +2013,9 @@ Login failed (${r.status}).`);
       console.log("\n");
       await whoami(apiBase);
       console.log(
-        run ? `
+        options2.continueToAgentRun ? `
+  ${dim("Workspace approved. Connecting this setup...")}
+` : run ? `
   ${dim("Return to the Fillo setup prompt and run its next command.")}
 ` : `
   ${dim("Now run:")} fillo push form.json
@@ -1997,10 +2046,174 @@ async function list() {
   if (!forms.length) return console.log("  No forms yet.");
   for (const f of forms) {
     console.log(
-      `  ${f.status === "published" ? "\x1B[32m\u25CF\x1B[0m" : "\u25CB"} ${terminalText(f.name)}  ${dim(f.id)}`
+      `  ${f.status === "published" ? "\x1B[32m\u25CF\x1B[0m" : "\u25CB"} ${terminalText(f.name)}  ${dim(f.id)}  ${dim(f.url)}`
     );
   }
 }
+async function status(handle) {
+  if (!handle) die("Usage: fillo status <formId|handle>");
+  const res = await api(`/cli/forms/${encodeURIComponent(handle)}`, { token: requireToken() });
+  if (res.status === 401) die("Token invalid \u2014 run `fillo login` again.");
+  if (res.status === 404) {
+    try {
+      JSON.parse(await res.text());
+    } catch {
+      die(
+        "This Fillo server does not support `fillo status` yet. Update the deployment, or check the form in the dashboard."
+      );
+    }
+    die(`No form matches "${handle}" in this workspace. Run \`fillo list\` to see its forms.`);
+  }
+  const body = await readJson(res);
+  if (!res.ok || !body.form) die(body.error ?? `status failed (${res.status}).`);
+  const form = body.form;
+  console.log(
+    `  ${form.status === "published" ? "\x1B[32m\u25CF\x1B[0m" : "\u25CB"} ${terminalText(form.name)}  ${dim(form.id)}`
+  );
+  console.log(`  Status: ${bold(form.staged ? "staged" : form.status)}`);
+  if (form.status === "published") console.log(`  Live at ${terminalText(form.url)}`);
+  else console.log(`  ${dim(`Publishes to ${form.url}`)}`);
+  if (form.staged) {
+    console.log(`  ${dim("Staged changes are waiting for review in the Fillo dashboard.")}`);
+  }
+  if (form.warning) {
+    const pending = form.status !== "published" || form.staged === true;
+    console.log(`  ${dim(pending ? `Before publishing: ${form.warning}` : form.warning)}`);
+  }
+  if (form.warningUrl) console.log(`  Storage settings: ${terminalText(form.warningUrl)}`);
+}
+async function publish(handle, flags) {
+  if (!handle) die("Usage: fillo publish <formId|handle> [--allow-breaking]");
+  const res = await api(`/cli/forms/${encodeURIComponent(handle)}/publish`, {
+    method: "POST",
+    token: requireToken(),
+    body: JSON.stringify(
+      flags["allow-breaking"] === true ? { allowBreaking: true } : {}
+    )
+  });
+  if (res.status === 401) die("Token invalid \u2014 run `fillo login` again.");
+  if (res.status === 404) {
+    try {
+      JSON.parse(await res.text());
+    } catch {
+      die(
+        "This Fillo server does not support `fillo publish` yet. Update the deployment, or publish the form from the dashboard."
+      );
+    }
+    die(`No form matches "${handle}" in this workspace. Run \`fillo list\` to see its forms.`);
+  }
+  const body = await readJson(res);
+  if (res.status === 409 && body.code === "breaking_changes") {
+    const fields = Array.isArray(body.breakingFields) ? body.breakingFields.filter((f) => typeof f === "string") : [];
+    console.error(
+      "\x1B[31m\u2717\x1B[0m Not published \u2014 the staged changes remove or re-type fields that existing responses answered."
+    );
+    if (fields.length) console.error(`  Fields: ${terminalText(fields.join(", "))}`);
+    console.error(
+      `  ${dim("Recorded answers are kept, but the live form, grid, and exports stop showing these fields.")}`
+    );
+    console.error("  Re-run with --allow-breaking to publish anyway.");
+    process.exit(1);
+  }
+  if (res.status === 409 && typeof body.warningUrl === "string" && body.warningUrl) {
+    console.error(`\x1B[31m\u2717\x1B[0m ${terminalText(body.error ?? `publish failed (${res.status}).`)}`);
+    console.error(`  Storage settings: ${terminalText(body.warningUrl)}`);
+    process.exit(1);
+  }
+  if (!res.ok || !body.form) die(body.error ?? `publish failed (${res.status}).`);
+  const form = body.form;
+  if (body.changed === false) {
+    console.log(
+      `
+  \x1B[32m\u2713\x1B[0m ${bold(terminalText(form.name))} is already live \u2014 nothing staged to publish.`
+    );
+  } else {
+    console.log(`
+  \x1B[32m\u2713\x1B[0m Published ${bold(terminalText(form.name))}  ${dim(form.id)}`);
+  }
+  console.log(`  Live at ${terminalText(form.url)}
+`);
+}
+async function loadResponseData(file) {
+  let value;
+  if (file === "-") {
+    try {
+      const chunks = [];
+      let bytes = 0;
+      for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.byteLength;
+        if (bytes > MAX_STDIN_SCHEMA_BYTES) {
+          die("The response data on stdin is too large (maximum 1 MB).");
+        }
+        chunks.push(buffer);
+      }
+      const input = Buffer.concat(chunks).toString("utf8");
+      if (!input.trim()) {
+        die("stdin is empty - pipe one JSON answer object to `fillo test-response <form> -`.");
+      }
+      value = JSON.parse(input);
+    } catch (error) {
+      die(`Couldn't read response data from stdin: ${error.message}`);
+    }
+  } else {
+    const abs = isAbsolute(file) ? file : resolve(process.cwd(), file);
+    if (!abs.endsWith(".json")) {
+      die("Test response data must be a .json file (or - for JSON on stdin).");
+    }
+    try {
+      value = JSON.parse(readFileSync(abs, "utf8"));
+    } catch (error) {
+      die(`Couldn't read ${file}: ${error.message}`);
+    }
+  }
+  if (!isRecord(value)) {
+    die("Test response data must be one JSON object keyed by field id.");
+  }
+  return value;
+}
+async function testResponse(handle, file) {
+  if (!handle || !file) {
+    die("Usage: fillo test-response <formId|handle> <answers.json|->");
+  }
+  const token = requireToken();
+  const data = await loadResponseData(file);
+  const res = await api(`/cli/forms/${encodeURIComponent(handle)}/test-response`, {
+    method: "POST",
+    token,
+    body: JSON.stringify({ data })
+  });
+  if (res.status === 401) die("Token invalid \u2014 run `fillo login` again.");
+  if (res.status === 404) {
+    try {
+      JSON.parse(await res.text());
+    } catch {
+      die(
+        "This Fillo server does not support `fillo test-response` yet. Update the deployment, then retry."
+      );
+    }
+    die(`No form matches "${handle}" in this workspace. Run \`fillo list\` to see its forms.`);
+  }
+  const body = await readJson(res);
+  if (res.status === 422 && body.errors && typeof body.errors === "object") {
+    console.error("\x1B[31m\u2717\x1B[0m Test response failed server validation.");
+    for (const [field2, message] of Object.entries(body.errors)) {
+      console.error(`  ${terminalText(field2)}: ${terminalText(message)}`);
+    }
+    process.exit(1);
+  }
+  if (!res.ok || !body.id || body.preview !== true) {
+    die(body.error ?? `test response failed (${res.status}).`);
+  }
+  console.log(
+    `
+  \x1B[32m\u2713\x1B[0m Test response passed the ${bold(body.schema ?? "current")} schema  ${dim(body.id)}`
+  );
+  console.log(
+    `  ${dim("Preview only \u2014 excluded from responses, limits, delivery, and analytics; auto-deletes after 7 days.")}
+`
+  );
+}
 async function loadSchema(file, allowCode) {
   if (file === "-") {
     try {
@@ -2114,6 +2327,7 @@ function printSynced(body, requestedStage) {
     console.log(`  Live at ${terminalText(`${API}/f/${body.slug}`)}`);
   }
   if (body.warning) console.log(`  ${dim(`Before publishing: ${body.warning}`)}`);
+  if (body.warningUrl) console.log(`  Storage settings: ${terminalText(body.warningUrl)}`);
   console.log(`  Embed:  <FilloForm formId="${terminalText(formId)}" />
 `);
 }
@@ -2203,7 +2417,14 @@ async function push(file, flags) {
         })
       });
       const body = await readJson(res);
-      if (!res.ok || !body.formId) die(body.error ?? `push failed (${res.status}).`);
+      if (!res.ok || !body.formId) {
+        if (res.status === 409 && typeof body.warningUrl === "string" && body.warningUrl) {
+          console.error(`\x1B[31m\u2717\x1B[0m ${terminalText(body.error ?? `push failed (${res.status}).`)}`);
+          console.error(`  Storage settings: ${terminalText(body.warningUrl)}`);
+          process.exit(1);
+        }
+        die(body.error ?? `push failed (${res.status}).`);
+      }
       printPushed(body.formId, body.url, !!body.updated);
     }
     return;
@@ -2242,6 +2463,18 @@ async function init(flags) {
 `);
 }
 var AGENT_ACTIONS = ["claim_required", "storage_required", "publish_required"];
+var AGENT_EVENT_STATUSES = [
+  "created",
+  "connected",
+  "asking",
+  "planning",
+  "installing",
+  "editing",
+  "checking",
+  "needs_action",
+  "done",
+  "error"
+];
 var FORM_STATUSES = ["draft", "published"];
 function enumFlag(flags, key, allowed) {
   const value = flags[key];
@@ -2265,46 +2498,39 @@ async function agent(subcommand, flags) {
     return agentHelp();
   }
   if (!run || !token) {
-    die("Usage: fillo agent <connect|event> --run <id> --token <token> [--api <url>]");
+    die("Usage: fillo agent <bootstrap|connect|event> --run <id> --token <token> [--api <url>]");
   }
   if (flags.account !== void 0 && flags.account !== true) {
     die("--account does not take a value.");
   }
-  if (subcommand === "connect") {
-    const account = flags.account === true ? await attachAgentAccount(apiBase, run, token) : void 0;
-    await postAgentEvent(apiBase, run, token, {
-      status: "connected",
-      message: "Agent connected. Reading the app now."
-    });
-    console.log(`  \x1B[32m\u2713\x1B[0m Live progress connected.`);
-    if (account) {
-      console.log(`  \x1B[32m\u2713\x1B[0m ${bold(account.workspace)}`);
-      console.log(`  ${dim("Publishable key:")} ${account.publishableKey}`);
+  if (subcommand === "bootstrap") {
+    installSkill(flags);
+    if (flags.account === true) {
+      await login(flags, { continueToAgentRun: true });
     }
-    console.log(`  ${dim("Report next steps with:")}`);
-    console.log(
-      `  fillo agent event --api ${terminalText(apiBase)} --run ${terminalText(run)} --token <same-token> --status editing --message "Editing the form screen"`
-    );
-    return;
+    return connectAgentRun(apiBase, run, token, flags.account === true);
+  }
+  if (subcommand === "connect") {
+    return connectAgentRun(apiBase, run, token, flags.account === true);
   }
   if (flags.account === true) {
-    die("--account can only be used with `fillo agent connect`.");
+    die("--account can only be used with `fillo agent bootstrap` or `fillo agent connect`.");
   }
   if (subcommand === "event") {
-    const status = flagString(flags, "status");
+    const status2 = enumFlag(flags, "status", AGENT_EVENT_STATUSES);
     const message = flagString(flags, "message");
-    if (!status) die("Usage: fillo agent event --status <status> --message <short update>");
+    if (!status2) die('Usage: fillo agent event --status <status> --message "<what the human does next>"');
     const action = enumFlag(flags, "action", AGENT_ACTIONS);
     const formStatus = enumFlag(flags, "form-status", FORM_STATUSES);
     const formId = optionalStringFlag(flags, "form-id");
-    if ((status === "done" || status === "needs_action") && !formId) {
-      die(`--form-id is required when --status is ${status}.`);
+    if ((status2 === "done" || status2 === "needs_action") && !formId) {
+      die(`--form-id is required when --status is ${status2}.`);
     }
-    if (status === "needs_action" && !action) {
+    if (status2 === "needs_action" && !action) {
       die("--action is required when --status is needs_action.");
     }
     await postAgentEvent(apiBase, run, token, {
-      status,
+      status: status2,
       message,
       appUrl: flagString(flags, "app-url"),
       action,
@@ -2317,16 +2543,44 @@ async function agent(subcommand, flags) {
   }
   die(`Unknown agent command: ${subcommand}`);
 }
-var SKILL_AGENTS = [
-  "agents",
-  "codex",
-  "claude",
-  "cursor",
-  "copilot",
-  "gemini"
-];
+async function connectAgentRun(apiBase, run, token, attachAccount) {
+  const account = attachAccount ? await attachAgentAccount(apiBase, run, token) : void 0;
+  await postAgentEvent(apiBase, run, token, {
+    status: "connected",
+    message: "Agent connected. Reading the app now."
+  });
+  console.log(`  \x1B[32m\u2713\x1B[0m Live progress connected.`);
+  if (account) {
+    console.log(`  \x1B[32m\u2713\x1B[0m ${bold(account.workspace)}`);
+    console.log(`  ${dim("Publishable key:")} ${account.publishableKey}`);
+  }
+  console.log(`  ${dim("Report next steps with:")}`);
+  console.log(
+    `  fillo agent event --api ${terminalText(apiBase)} --run ${terminalText(run)} --token <same-token> --status editing --message "Editing the form screen"`
+  );
+  console.log(
+    `  ${dim("For needs_action or done, lead --message with what the human does next \u2014 max 180 chars, longer is cut off.")}`
+  );
+}
+var SKILL_AGENT_DIRECTORIES = {
+  shared: ".agents/skills",
+  universal: ".agents/skills",
+  agents: ".agents/skills",
+  codex: ".agents/skills",
+  cursor: ".agents/skills",
+  copilot: ".agents/skills",
+  "github-copilot": ".agents/skills",
+  gemini: ".agents/skills",
+  "gemini-cli": ".agents/skills",
+  amp: ".agents/skills",
+  cline: ".agents/skills",
+  opencode: ".agents/skills",
+  warp: ".agents/skills",
+  claude: ".claude/skills",
+  "claude-code": ".claude/skills"
+};
 function isSkillAgent(value) {
-  return SKILL_AGENTS.some((agent2) => agent2 === value);
+  return Object.prototype.hasOwnProperty.call(SKILL_AGENT_DIRECTORIES, value);
 }
 function findProjectRoot(start) {
   let current = resolve(start);
@@ -2337,19 +2591,25 @@ function findProjectRoot(start) {
     current = parent;
   }
 }
-function detectSkillAgent() {
-  if (process.env.CLAUDECODE === "1" || process.env.CLAUDE_CODE === "1") {
-    return "claude";
-  }
-  return "agents";
-}
-function parseSkillAgent(flags) {
-  if (flags.agent === true || flags.agent === "") {
-    die(`--agent requires one of: ${SKILL_AGENTS.join(", ")}`);
+function parseSkillDirectories(flags) {
+  const agent2 = flagString(flags, "agent");
+  const customDirectory = flagString(flags, "dir");
+  if (agent2 && customDirectory) die("Choose either --agent or --dir, not both.");
+  if (customDirectory) {
+    if (isAbsolute(customDirectory)) {
+      die("--dir must be relative to the project root, or to your home directory with --global.");
+    }
+    const parts = customDirectory.split(/[\\/]+/).filter((part) => part && part !== ".");
+    if (parts.length === 0 || parts.some((part) => part === "..")) {
+      die("--dir must name a skill directory inside the selected project or home scope.");
+    }
+    return [join(...parts)];
   }
-  const value = flagString(flags, "agent") ?? detectSkillAgent();
-  if (isSkillAgent(value)) return value;
-  die(`--agent must be one of: ${SKILL_AGENTS.join(", ")}`);
+  if (!agent2) return [SKILL_AGENT_DIRECTORIES.shared, SKILL_AGENT_DIRECTORIES.claude];
+  if (isSkillAgent(agent2)) return [SKILL_AGENT_DIRECTORIES[agent2]];
+  die(
+    `Unknown agent ${agent2}. Use --agent shared, --agent claude, or --dir <agent-skill-directory>.`
+  );
 }
 function skillFiles(root, relative2 = "") {
   const directory = join(root, relative2);
@@ -2436,52 +2696,69 @@ function installSkill(flags) {
   if (flags.global === true && flags.project === true) {
     die("Choose either --project or --global, not both.");
   }
-  const agent2 = parseSkillAgent(flags);
+  const skillDirectories = parseSkillDirectories(flags);
   const global = flags.global === true;
-  const agentDirectory = agent2 === "claude" ? ".claude" : ".agents";
   const scopeRoot = global ? homedir() : findProjectRoot(process.cwd());
-  const skillsRoot = join(scopeRoot, agentDirectory, "skills");
-  const target = join(skillsRoot, "build-with-fillo");
-  const destinationParts = [agentDirectory, "skills", "build-with-fillo"];
   if (!existsSync(BUNDLED_SKILL_DIR)) {
     die("This CLI package is missing its bundled Fillo skill. Reinstall @usefillo/cli@latest.");
   }
-  assertSafeSkillDestination(scopeRoot, destinationParts);
-  const targetExists = pathEntryExists(target);
-  const updatingManagedSkill = targetExists && isCliManagedFilloSkill(target);
-  if (targetExists) {
-    if (sameSkillBundle(BUNDLED_SKILL_DIR, target)) {
-      console.log(`
-  \x1B[32m\u2713\x1B[0m Fillo skill is already installed.`);
-      console.log(`  ${dim(target)}
-`);
-      return;
-    }
-    if (!updatingManagedSkill && flags.force !== true) {
+  const destinations = Array.from(
+    new Set(skillDirectories)
+  ).map((skillDirectory) => {
+    const skillsRoot = resolve(scopeRoot, skillDirectory);
+    const target = join(skillsRoot, "build-with-fillo");
+    const relativeSkillsRoot = relative(scopeRoot, skillsRoot);
+    if (relativeSkillsRoot === ".." || relativeSkillsRoot.startsWith(`..${sep}`) || isAbsolute(relativeSkillsRoot)) {
+      die("The skill destination must stay inside the selected project or home scope.");
+    }
+    const destinationParts = [
+      ...relativeSkillsRoot.split(sep).filter(Boolean),
+      "build-with-fillo"
+    ];
+    assertSafeSkillDestination(scopeRoot, destinationParts);
+    const targetExists = pathEntryExists(target);
+    const current = targetExists && sameSkillBundle(BUNDLED_SKILL_DIR, target);
+    const updatingManagedSkill = targetExists && isCliManagedFilloSkill(target);
+    if (targetExists && !current && !updatingManagedSkill && flags.force !== true) {
       die(`A different skill already exists at ${target}. Re-run with --force to replace it.`);
     }
-  }
-  mkdirSync(skillsRoot, { recursive: true });
-  assertSafeSkillDestination(scopeRoot, destinationParts.slice(0, 2));
-  const staging = join(skillsRoot, `.build-with-fillo.install-${randomUUID()}`);
-  try {
-    cpSync(BUNDLED_SKILL_DIR, staging, { recursive: true, errorOnExist: true });
-    assertSafeSkillDestination(scopeRoot, destinationParts);
-    if (!targetExists && pathEntryExists(target)) {
-      throw new Error(`Skill destination changed during install: ${target}`);
+    return {
+      skillsRoot,
+      target,
+      destinationParts,
+      targetExists,
+      current,
+      updatingManagedSkill
+    };
+  });
+  for (const destination of destinations) {
+    if (destination.current) continue;
+    mkdirSync(destination.skillsRoot, { recursive: true });
+    assertSafeSkillDestination(scopeRoot, destination.destinationParts.slice(0, 2));
+    const staging = join(
+      destination.skillsRoot,
+      `.build-with-fillo.install-${randomUUID()}`
+    );
+    try {
+      cpSync(BUNDLED_SKILL_DIR, staging, { recursive: true, errorOnExist: true });
+      assertSafeSkillDestination(scopeRoot, destination.destinationParts);
+      if (!destination.targetExists && pathEntryExists(destination.target)) {
+        throw new Error(`Skill destination changed during install: ${destination.target}`);
+      }
+      moveSkillIntoPlace(staging, destination.target);
+    } finally {
+      if (pathEntryExists(staging)) rmSync(staging, { recursive: true, force: true });
     }
-    moveSkillIntoPlace(staging, target);
-  } finally {
-    if (pathEntryExists(staging)) rmSync(staging, { recursive: true, force: true });
   }
+  const changed = destinations.filter((destination) => !destination.current);
+  const action = changed.length === 0 ? "Fillo skill is already installed" : changed.every((destination) => destination.updatingManagedSkill) ? `Updated ${bold("Build with Fillo")}` : `Installed ${bold("Build with Fillo")}`;
+  console.log(`
+  \x1B[32m\u2713\x1B[0m ${action}.`);
+  for (const destination of destinations) console.log(`  ${dim(destination.target)}`);
+  console.log(`
+  Ask your agent to use ${bold("build-with-fillo")}.`);
   console.log(
-    `
-  \x1B[32m\u2713\x1B[0m ${updatingManagedSkill ? "Updated" : "Installed"} ${bold("Build with Fillo")} for ${agent2}.`
-  );
-  console.log(`  ${dim(target)}`);
-  console.log(
-    `
-  Ask your agent to read ${terminalText(join(target, "SKILL.md"))} and add a Fillo form.
+    `  ${dim(`If it does not discover skills, point it to ${join(destinations[0].target, "SKILL.md")}.`)}
 `
   );
 }
@@ -2534,15 +2811,22 @@ function agentHelp() {
   ${bold("fillo agent")} \u2014 report live progress back to a Fillo prompt modal
 
   ${bold("Commands")}
+    agent bootstrap     Install the skill and connect this coding-agent run
+                       ${dim("--account   approve and attach an existing workspace in the browser")}
     agent connect       Connect a coding-agent run to the open browser modal
                        ${dim("--account   attach the workspace from `fillo login`")}
     agent event         Send a short progress update
-                       ${dim("--status <created|connected|asking|planning|installing|editing|checking|needs_action|done|error>")}
-                       ${dim('--message "Short update"')}
+                       ${dim(`--status <${AGENT_EVENT_STATUSES.join("|")}>`)}
+                       ${dim('--message "What the human does next" (max 180 chars)')}
                        ${dim("--form-id <id> --form-status <draft|published> --form-name <name>")}
                        ${dim("--action <claim_required|storage_required|publish_required>")}
                        ${dim("--app-url <localhost-url>")}
                        ${dim("--run <id> --token <token> --api <url>")}
+
+  ${dim("For --status needs_action or done, lead the message with what the human does")}
+  ${dim('next, in one or two sentences, plus the form URL or form id \u2014 e.g. "Connect')}
+  ${dim('storage in Fillo, publish the form, then submit one test response".')}
+  ${dim("Max 180 characters \u2014 longer is cut off. Never list changed files in the message.")}
 `);
 }
 function skillHelp() {
@@ -2551,11 +2835,12 @@ function skillHelp() {
 
   ${bold("Commands")}
     skill install       Install into this project (default)
-                       ${dim("--agent <agents|codex|claude|cursor|copilot|gemini>")}
+                       ${dim("--agent <shared|claude>   choose a standard destination")}
+                       ${dim("--dir <path>              install into any agent's skill directory")}
                        ${dim("--global   install for the current user")}
                        ${dim("--force    replace a different existing copy")}
 
-  ${dim("Codex, Cursor, Copilot, and Gemini use shared .agents/skills; Claude Code uses .claude/skills.")}
+  ${dim("Default: open Agent Skills path (.agents/skills) plus Claude Code (.claude/skills).")}
 `);
 }
 function printVersion() {
@@ -2582,8 +2867,14 @@ function help() {
                        ${dim("--stage          stage beside the live form for dashboard review")}
                        ${dim("--draft          alias with a handle; legacy one-off draft without")}
                        ${dim("--allow-code     allow a .mjs/.js schema (executes the file)")}
-    list               List the workspace's forms
-    agent <cmd>        Report live progress to a Fillo prompt modal
+    list               List the workspace's forms and their live URLs
+    status <form>      Show one form's status, live URL, and publish blockers
+                       ${dim("<form> is a form id or handle")}
+    publish <form>     Publish staged changes (or a draft form) \u2014 prints the live URL
+                       ${dim("--allow-breaking  confirm removing/re-typing fields responses answered")}
+    test-response <form> <file|->
+                       Validate answers against staged changes without real delivery
+    agent <cmd>        Prepare an agent run and report live progress
     skill install      Install the Build with Fillo Agent Skill
 
   ${dim(`API: ${API}  \xB7  set FILLO_API to override`)}
@@ -2592,6 +2883,7 @@ function help() {
 }
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "account",
+  "allow-breaking",
   "allow-code",
   "draft",
   "stage",
@@ -2612,6 +2904,9 @@ var FLAGS_BY_COMMAND = {
   push: ["handle", "stage", "draft", "allow-code"],
   list: [],
   ls: [],
+  status: [],
+  publish: ["allow-breaking"],
+  "test-response": [],
   agent: [
     "run",
     "token",
@@ -2625,7 +2920,7 @@ var FLAGS_BY_COMMAND = {
     "form-name",
     "form-status"
   ],
-  skill: ["agent", "global", "project", "force"],
+  skill: ["agent", "dir", "global", "project", "force"],
   help: [],
   version: []
 };
@@ -2711,6 +3006,12 @@ async function main() {
     case "list":
     case "ls":
       return list();
+    case "status":
+      return status(positional[0]);
+    case "publish":
+      return publish(positional[0], flags);
+    case "test-response":
+      return testResponse(positional[0], positional[1]);
     case "agent":
       return agent(positional[0], flags);
     case "skill":