gooseworks 0.4.2 → 0.4.4

package/dist/utils/browser-preflight.js

@@ -0,0 +1,338 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkBrowserPreflight = checkBrowserPreflight;
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+const MARKER = 'GOOSE_BROWSER_PREFLIGHT=';
+// A separate Node process preserves native module resolution (including NODE_PATH)
+// and keeps a broken Playwright installation from hanging or crashing the CLI.
+// Nothing imports or runs the renderer, downloads a browser, or navigates a page.
+const PROBE = String.raw `
+const fs = require('fs');
+const path = require('path');
+const { createRequire } = require('module');
+// Register each native child synchronously at creation. A probe can crash/exit
+// before the supervisor's inventory poll; Chromium must remain owned then too.
+const childProcess = require('child_process');
+const nativeSpawn = childProcess.spawn;
+if (process.platform !== 'win32') {
+  childProcess.spawn = function(...args) {
+    const child = Reflect.apply(nativeSpawn, this, args);
+    if (child.pid) {
+      const inventory = childProcess.spawnSync('/bin/ps', ['-p', String(child.pid), '-o', 'pid=', '-o', 'ppid=', '-o', 'pgid=', '-o', 'stat=', '-o', 'lstart='], {
+        encoding: 'utf8', timeout: 250, maxBuffer: 4096, stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      const row = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(inventory.stdout || '');
+      fs.writeSync(1, 'GOOSE_BROWSER_CHILD=' + JSON.stringify({
+        pid: child.pid, parent: process.pid,
+        born: row && Number(row[2]) === process.pid ? row[5] : null,
+      }) + '\n');
+    }
+    return child; // Preserve arguments, launch flags and the native ChildProcess.
+  };
+  require('module').syncBuiltinESMExports();
+}
+let [anchor, selected, launchMs, closeMs] = process.argv.slice(1);
+const meta = {};
+let browser;
+let completed = false;
+function finish(code, detail) {
+  if (completed) return;
+  completed = true;
+  process.stdout.write('GOOSE_BROWSER_PREFLIGHT=' + JSON.stringify({
+    ok: code === 'ready', code, detail, ...meta,
+  }) + '\n');
+  // Keep the tree rooted here until the supervisor acknowledges the result.
+  // In particular, Windows taskkill /T needs the parent PID still alive.
+  setInterval(() => {}, 1000);
+}
+function message(error) { return String(error?.message || error).slice(0, 4000); }
+async function closeBrowser() {
+  if (!browser) return;
+  await Promise.race([
+    browser.close(),
+    new Promise((_, reject) => setTimeout(() => reject(new Error('browser close timed out')), Number(closeMs))),
+  ]);
+}
+(async () => {
+  if (selected === 'true') {
+    try {
+      if (!fs.statSync(anchor).isFile()) throw new Error('not a file');
+      // Node resolves its main script's symlink unless explicitly told otherwise.
+      if (!/--preserve-symlinks-main\b/.test(process.env.NODE_OPTIONS || '')) anchor = fs.realpathSync(anchor);
+      meta.resolvedScript = anchor;
+    }
+    catch { return finish('invalid_script', 'Renderer script is not an existing file: ' + anchor); }
+  }
+  const fromRenderer = createRequire(anchor);
+  let playwright;
+  try {
+    meta.modulePath = fromRenderer.resolve('playwright');
+    playwright = fromRenderer('playwright');
+    meta.version = fromRenderer('playwright/package.json').version;
+    meta.cliPath = path.join(path.dirname(fromRenderer.resolve('playwright/package.json')), 'cli.js');
+    meta.executablePath = playwright.chromium.executablePath();
+    process.stdout.write('GOOSE_BROWSER_PREFLIGHT_META=' + JSON.stringify(meta) + '\n');
+  } catch (error) {
+    return finish(meta.modulePath ? 'probe_failed' : 'missing_module', message(error));
+  }
+  try {
+    // Preserve chromium.launch() defaults: no alternate executable, channel,
+    // headless mode or sandbox flags. The only override bounds the wait.
+    browser = await playwright.chromium.launch({ timeout: Number(launchMs) });
+  } catch (error) {
+    const detail = message(error);
+    const code = /executable.*doesn't exist|executable.*not found|ENOENT/i.test(detail)
+      ? 'missing_browser' : /timeout|timed out/i.test(detail) ? 'timeout' : 'launch_failed';
+    return finish(code, detail);
+  }
+  try { await closeBrowser(); }
+  catch (error) { return finish('close_failed', message(error)); }
+  finish('ready', 'Chromium launched and closed with the default renderer settings');
+})().catch(error => finish('probe_failed', message(error)));
+`;
+function quote(value) {
+    return process.platform === 'win32' ? `"${value}"` : `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function repair(code, folder, cliPath) {
+    const cd = `${process.platform === 'win32' ? 'cd /d' : 'cd'} ${quote(folder)}`;
+    const cli = cliPath ? `${quote(process.execPath)} ${quote(cliPath)}` : 'npx --no-install playwright';
+    if (code === 'invalid_script')
+        return 'Pass --renderer-script with the actual fetched renderer script path';
+    if (code === 'missing_module')
+        return `${cd} && npm install playwright && npx --no-install playwright install chromium`;
+    if (code === 'missing_browser')
+        return `${cd} && ${cli} install chromium`;
+    if (code === 'ready')
+        return '';
+    return `${cd} && ${cli} install --with-deps chromium`;
+}
+// spawnSync has no detached/process-group option. This supervisor uses spawn()
+// to own the probe. Chromium creates another detached Unix group, so cleanup
+// tracks descendants by parentage, freezes them, and kills owned PIDs before
+// the probe. The existing synchronous doctor/install API stays compatible.
+const SUPERVISOR = String.raw `
+const { spawn, spawnSync } = require('child_process');
+const [probe, ...args] = process.argv.slice(1);
+let output = '';
+let meta = {};
+let finished = false;
+const owned = new Map();
+let rootBorn;
+let ownershipUncertain = false;
+const registrations = new Set();
+function processTable() {
+  const result = spawnSync('/bin/ps', ['-A', '-o', 'pid=', '-o', 'ppid=', '-o', 'pgid=', '-o', 'stat=', '-o', 'lstart='], {
+    encoding: 'utf8', timeout: 250, maxBuffer: 256 * 1024, stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  if (result.status !== 0) return null;
+  const rows = new Map();
+  for (const line of result.stdout.split('\n')) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(.+?)\s*$/.exec(line);
+    if (match) rows.set(Number(match[1]), { pid: Number(match[1]), parent: Number(match[2]), group: Number(match[3]), state: match[4], born: match[5] });
+  }
+  return rows.size ? rows : null;
+}
+// Without a process inventory we cannot safely clean up a detached browser.
+// Fail before launching it; never use a broad browser-name or user-wide kill.
+if (process.platform !== 'win32' && !processTable()) {
+  process.stdout.write('GOOSE_BROWSER_PREFLIGHT=' + JSON.stringify({ ok: false, code: 'probe_failed', detail: 'Cannot inspect owned browser processes with /bin/ps; browser was not launched' }) + '\n');
+  process.exit(1);
+}
+const child = spawn(process.execPath, ['-e', probe, ...args], {
+  detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'ignore'], env: process.env,
+});
+function discover(rows) {
+  // Retain observed children after reparenting, but reject reused PID identities.
+  for (const [pid, row] of owned) if (rows.get(pid)?.born !== row.born) owned.delete(pid);
+  const root = rows.get(child.pid);
+  if (root && (!rootBorn || root.born === rootBorn)) {
+    rootBorn = root.born;
+    owned.set(child.pid, root);
+  }
+  let changed;
+  do {
+    changed = false;
+    for (const row of rows.values()) {
+      if (!owned.has(row.pid) && owned.has(row.parent)) {
+        owned.set(row.pid, row);
+        changed = true;
+      }
+    }
+  } while (changed);
+  return [...owned.keys()].map(pid => rows.get(pid)).filter(row => row && !row.state.startsWith('Z'));
+}
+function signal(row, name) {
+  try { process.kill(row.pid, name); } catch {} // Already gone, or reported by verification below.
+}
+const monitor = process.platform === 'win32' ? null : setInterval(() => {
+  const rows = processTable();
+  if (rows) discover(rows);
+}, 100);
+function cleanup() {
+  if (monitor) clearInterval(monitor);
+  if (!child.pid) return { ok: true, remainingPids: [] };
+  if (process.platform === 'win32') {
+    const result = spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { timeout: 2000, stdio: 'ignore' });
+    return { ok: result.status === 0, remainingPids: result.status === 0 ? [] : [child.pid] };
+  }
+  const until = Date.now() + 1500;
+  const frozen = new Set();
+  let active = [];
+  let stable = false;
+  // Freeze parent processes first, then rescan for children created just before
+  // SIGSTOP. This stops further forks without changing browser launch options.
+  for (let round = 0; round < 8 && Date.now() < until; round++) {
+    const rows = processTable();
+    if (!rows) continue; // Retry a transient inventory timeout within the same budget.
+    active = discover(rows);
+    const fresh = active.filter(row => !frozen.has(row.pid));
+    for (const row of fresh) { signal(row, 'SIGSTOP'); frozen.add(row.pid); }
+    if (!fresh.length) { stable = true; break; }
+  }
+  // Use individual owned PIDs, not a whole group that could contain unrelated
+  // processes. Detached Chromium groups and their renderers are still covered.
+  for (const row of active.filter(row => row.pid !== child.pid).reverse()) signal(row, 'SIGKILL');
+  const root = active.find(row => row.pid === child.pid);
+  if (root) signal(root, 'SIGKILL');
+  else if (child.exitCode === null && child.signalCode === null) child.kill('SIGKILL');
+  while (Date.now() < until) {
+    const rows = processTable();
+    if (!rows) continue;
+    active = discover(rows);
+    if (!active.length) return { ok: stable && !ownershipUncertain, remainingPids: [] };
+    for (const row of active) signal(row, 'SIGKILL');
+  }
+  return { ok: false, remainingPids: active.map(row => row.pid) };
+}
+function finish(code, override) {
+  if (finished) return;
+  finished = true;
+  clearTimeout(deadline);
+  const stopped = cleanup();
+  let result = { ...meta, ...override, cleanup: stopped };
+  if (!stopped.ok) {
+    result = { ...result, ok: false, code: 'probe_failed', detail: (result.detail || 'Browser probe ended') + '; could not confirm cleanup of owned browser processes' };
+    code = 1;
+  } else if (result.code === 'timeout') result.detail += '; its owned processes were stopped';
+  const text = 'GOOSE_BROWSER_PREFLIGHT=' + JSON.stringify(result) + '\n';
+  process.stdout.write(text, () => process.exit(code));
+}
+const deadline = setTimeout(() => finish(1, {
+  ok: false, code: 'timeout', detail: 'Browser launch/close probe timed out',
+}), Number(args[2]) + Number(args[3]) + 500);
+child.stdout.on('data', chunk => {
+  output += chunk;
+  if (Buffer.byteLength(output) > 60000) finish(1, { ok: false, code: 'probe_failed', detail: 'Browser probe exceeded its diagnostic output limit' });
+  // Consume creation records before processing a terminal result. writeSync in
+  // the probe and the close (not exit) handler preserve records on abrupt exit.
+  for (const line of output.split(/\r?\n/)) {
+    if (!line.startsWith('GOOSE_BROWSER_CHILD=') || !output.includes(line + '\n') || registrations.has(line)) continue;
+    registrations.add(line);
+    try {
+      const registration = JSON.parse(line.slice('GOOSE_BROWSER_CHILD='.length));
+      if (!registration.born || registration.parent !== child.pid) { ownershipUncertain = true; continue; }
+      // The creation record has the native parent's verified start identity.
+      // Seed discovery even if that parent has already exited and reparented it.
+      owned.set(registration.pid, registration);
+    } catch { ownershipUncertain = true; }
+  }
+  const metadata = output.split(/\r?\n/).find(line => line.startsWith('GOOSE_BROWSER_PREFLIGHT_META=') && output.includes(line + '\n'));
+  if (metadata) {
+    try { meta = JSON.parse(metadata.slice('GOOSE_BROWSER_PREFLIGHT_META='.length)); } catch {}
+  }
+  const line = output.split(/\r?\n/).find(line => line.startsWith('GOOSE_BROWSER_PREFLIGHT=') && output.includes(line + '\n'));
+  if (line) {
+    try { const result = JSON.parse(line.slice('GOOSE_BROWSER_PREFLIGHT='.length)); finish(result.ok ? 0 : 1, result); }
+    catch { finish(1, { ok: false, code: 'probe_failed', detail: 'Invalid browser probe result' }); }
+  }
+});
+child.on('error', error => finish(1, { ok: false, code: 'probe_failed', detail: error.message }));
+child.on('close', () => finish(1, { ok: false, code: 'probe_failed', detail: 'Browser probe closed without a result' }));
+`;
+/**
+ * Probe the package the script would require, using the caller's cwd and env.
+ * Without a script, this is only a general check rooted in the current folder.
+ * Browser startup creates normal temporary runtime files; no project output.
+ */
+function checkBrowserPreflight(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const selected = opts.rendererScript !== undefined;
+    const anchor = path.resolve(cwd, opts.rendererScript ?? '__gooseworks_browser_probe__.js');
+    const folder = path.dirname(anchor);
+    const launchMs = opts.launchTimeoutMs ?? 15000;
+    const closeMs = opts.closeTimeoutMs ?? 3000;
+    let result;
+    try {
+        const probe = (0, child_process_1.spawnSync)(process.execPath, ['-e', SUPERVISOR, PROBE, anchor, String(selected), String(launchMs), String(closeMs)], {
+            cwd,
+            env: process.env,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: launchMs + closeMs + 3500,
+            killSignal: 'SIGKILL',
+            maxBuffer: 64 * 1024,
+        });
+        const error = probe.error;
+        const line = (probe.stdout ?? '').split(/\r?\n/).find((s) => s.startsWith(MARKER));
+        if (line && !probe.error) {
+            result = JSON.parse(line.slice(MARKER.length));
+            if ((result.code === 'ready' && probe.status !== 0) || !result.code)
+                throw new Error('invalid browser probe result');
+        }
+        else {
+            result = {
+                ok: false,
+                code: error?.code === 'ETIMEDOUT' ? 'timeout' : 'probe_failed',
+                detail: error?.code === 'ETIMEDOUT'
+                    ? 'Browser probe supervisor timed out before returning a result'
+                    : `Browser probe could not complete (${probe.error?.message ?? `exit ${probe.status}`})`,
+            };
+        }
+    }
+    catch (error) {
+        result = { ok: false, code: 'probe_failed', detail: `Browser probe failed: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const location = result.modulePath ? `; Playwright ${result.version ?? 'unknown version'} at ${result.modulePath}` : '';
+    const executable = result.executablePath ? `; Chromium executable: ${result.executablePath}` : '';
+    return {
+        ...result,
+        ...(selected ? { rendererScript: anchor } : {}),
+        detail: `${selected ? `Renderer ${anchor}` : `General browser setup in ${cwd}`}: ${result.detail}${location}${executable}`,
+        fix: repair(result.code, result.resolvedScript ? path.dirname(result.resolvedScript) : folder, result.cliPath),
+    };
+}
+//# sourceMappingURL=browser-preflight.js.map

package/dist/utils/browser-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-preflight.js","sourceRoot":"","sources":["../../src/utils/browser-preflight.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gooseworks",
-  "version": "0.4.2",
-  "description": "GooseWorks CLI — give your coding agent real data tools",
+  "version": "0.4.4",
+  "description": "GooseWorks CLI \u2014 give your coding agent real data tools",
   "bin": {
     "gooseworks": "./dist/index.js"
   },

package/skills/goose-ads/SKILL.md

@@ -30,6 +30,58 @@ The GooseWorks ads skill. Two jobs:
 2. **Analyze ad performance** — fetch ad-analytics recipes from goose-skills on demand
    (these are unrelated to generation; see "Analyze / intelligence" below).
 
+## How to talk to the customer (applies to every message you send them)
+
+The customer is a marketer or founder, not an engineer. Everything in this skill about tools,
+fields, files, polling, models and pipeline steps is for YOU. Never pass it on to them.
+
+- **Say what they get and what they need to decide, never how it's made.**
+  Bad: "Checking the media-proxy helpers for voiceover timestamps and lipsync." / "Generated with
+  gpt-image-2 at high quality, mouth closed, passes QC."
+  Good: "Recording the voices now." / "Here are your two hosts."
+- **Never mention** tool, file or field names, ids, JSON, commands, scripts, installed software,
+  uploads, model or vendor names, timings in seconds or frames, retries, polling, internal statuses
+  or your own quality checks. Fix what you can quietly. If they ask how something works, explain it
+  simply.
+- **Update them only at milestones they care about**: choices confirmed, script and voices done,
+  visuals done, ready to review, finished. One short line each, then stay quiet until the next
+  milestone. No update for setup, downloads, uploads or saving.
+- **Money is in credits, with a number**: "the full video uses about N credits". Never "the cheap
+  pieces" or "the expensive render".
+- **Problems:** say what it means for them and what they can do, in one or two sentences. No error
+  codes or stack traces. Only raise a problem that changes something for them.
+- **Use their words**: script, voice, hook, scene, host, ending, logo, the product shot.
+- **No filler**: no "Great question!", "Certainly!", "I hope this helps!", no restating what they
+  just said at length.
+
+Example. Instead of a dozen lines about render tools, scripts, uploads and portraits, send:
+"Got it: warm tone, home podcast studio, Brielle as the skeptic and Mark as the believer." then
+"Script and voices are done (about 34 seconds)." then "Ready for you to review: the script, voices,
+both hosts and the ending. You can also review your recipe ingredients in the app: <link>. Say go
+here and I'll make the full video (about N credits)."
+
+## Use current instructions for new work
+
+Before a new task in a terminal host, run `gooseworks skills status` once. It compares the
+installed entry files, running CLI and published npm release. An older CLI needs a package
+upgrade before `gooseworks update`; update alone only uses that CLI's bundled instructions.
+Preserve local edits or unknown install provenance. Review/back up before explicitly replacing
+modified files; never quietly reinstall over them. If the release check is unavailable, report
+that freshness is unknown rather than claiming the local copy is latest.
+
+For a new recipe run, fetch its package from the connected catalog. Retain the returned
+`version` / `contentHash` and every dependency's hash with the saved package. When reusing a
+saved fetch JSON, `gooseworks fetch <slug> --saved-package <file>` returns the current package
+and a hash comparison without changing that file. With MCP, if the advertised `catalog_fetch`
+schema accepts them, send `saved_content_hash` and `saved_dependency_hashes`; otherwise fetch
+normally and compare the returned hashes yourself. Missing hashes mean unknown, not current.
+The server cannot inspect a client's saved files; hash metadata does not certify later edits.
+Fetch current packages into a new run directory and report stale saved instructions. Preserve
+an existing approved run's recorded package; changing that harness requires a reviewed change
+and approval before spending. Hosted installed snapshots use the existing Skills Update action.
+Skill content and a host's cached MCP tool schemas are separate: refreshing one does not refresh
+the other. Check the actual advertised tools before using new fields.
+
 ## Prerequisite — the GooseWorks MCP server is REQUIRED
 
 Everything goes through the `mcp__gooseworks__*` tools. If they are not available, **stop and
@@ -39,7 +91,7 @@ no HTTP/file fallback — the REST ad endpoints are session-cookie-only and reje
 ## Start from the brand context — don't re-ask what it already answers
 
 If the `gooseworks` router handed you brand context, USE IT. If you were invoked directly, call
-`brand_get_context` first (falling back to `get_brand_kit` for the selected brand). It already
+`brand_read { brand_id, sections: ["summary","kit","products","learnings"] }` first. It already
 answers most of what the flows below would otherwise ask the user:
 
 - **Which product to feature** → `products[]`. Offer the real catalog entries; never guess a
@@ -147,7 +199,7 @@ immediately.
   competitor ad or an image found online.
 - `get_ad_project` / `append_project_message` — inspect a creative / leave a note on its thread.
 
-## Keep the brand kit in sync — reconcile, then update (ASK first)
+## Keep the brand kit in sync — reconcile, then save or propose
 
 The brand kit is the source of truth every generation reads. During ANY task, when the user
 **tells you something about the brand or asks to change something brand-level** — a different
@@ -155,24 +207,79 @@ tagline, audience, voice, a product's name/price/description, "our logo is X", "
 anymore", a new product photo — treat it as a possible kit update, don't just use it for this one
 ad and forget it:
 
-1. **Check it against the kit.** Call `get_brand_kit` for the active brand and see whether what the user said
+1. **Check it against the kit.** Call `brand_read` with `kit` and `learnings` for the active brand and see whether what the user said
    matches, is missing from, or contradicts the kit.
 2. **If it's already in the kit and matches** — nothing to do; proceed.
-3. **If it's new or different — ASK before writing.** Confirm in one line: *"Want me to update
-   the brand kit so this sticks for future ads?"* Only persist on a yes (or when the user clearly
-   asked you to change the brand). Don't silently mutate the kit, and don't nag on trivia.
-4. **Persist with the write tools** (partial — only the fields you pass are touched; each edit is
-   recorded as a user override that later re-research won't clobber):
-   - `update_brand_kit` — structured brand fields.
-   - `upsert_brand_product` / `delete_brand_product` — products.
-   - `add_brand_product_image` / `remove_brand_reference_image` — product and reference photos.
+3. **If it's new or different**, persist an explicit request to correct or remember the brand
+   through the policy below; that request is already authorization. For an ambiguous one-ad
+   direction, ask once whether it should stick. Agent-derived suggestions become proposals.
+4. **Persist with the canonical write tools** (send only changed fields):
+   - `brand_update` with explicit user-correction intent — structured brand fields or products;
+     an inferred structured field uses agent-proposal intent instead. Follow the live schema.
+   - `media_upload` / `media_update` — the user's own product and reference photos.
    Inspect each live schema and send only the fields needed for the confirmed change.
-5. **Confirm what changed** and continue the task. (Logo, colors, and fonts are owned by the
-   backend research pass — prefer `update_ad_brand` / the research flow for those, not free text.)
+5. **Read back what changed** before saying saved, then continue the task. (Use the research
+   workflow for researched logo/colors/fonts; explicit user edits use only fields supported by
+   the canonical tool schema and the correction policy below.)
 
 This is the parity gap the app closes in-product: a brand fact the user gives mid-task should be
 able to flow back into the kit — with their ok — instead of being lost.
 
+## Save durable brand answers, then verify them
+
+Read the selected brand with `brand_read { brand_id, sections: ["summary", "kit", "products", "learnings", "onboarding"] }`
+(fallback: `brand_get_context` with the same sections). Keep founder answers, user corrections,
+research and your own hypotheses distinct. Reuse matching saved answers; ask only about gaps.
+
+When the user asks to remember a rule, answers a brand interview, or explicitly corrects a
+standing fact, save that answer in the same turn. The capture request authorizes those answers;
+do not ask for approval again. A direction for this one video stays in its brief. If the scope
+is genuinely ambiguous, ask whether it applies to future videos before saving a standing rule.
+
+Use the **live registered schema**. Where supported, call `brand_update` with
+`knowledge_intent: "user_correction"` and `user_statement` containing the user's exact,
+verbatim answer, not your paraphrase or researched text.
+For an inference or suggested improvement, use `knowledge_intent: "agent_proposal"`. Show the
+before/after change from your prior read and proposed value; retain the returned proposal IDs
+and say the user must accept it in the app. Link only a review surface actually returned by a
+tool; the compact `knowledge_updates` response does not itself contain a diff or URL.
+A pending proposal is not a saved fact. Never call an unavailable
+tool or silently relabel research or your inference as something the user said.
+
+The safe structured shape is `patch: { knowledge: { positioning?, audience?, voice?,
+instructions?, brandType?, tagline?, valueProps? } }`, using only fields present in the live
+schema. Inferred rules/taste go in an `instructions` proposal with a rationale, never in
+`patch.facts`. Prefix every video-only preference in that proposed text with "Video preference:"
+so it remains production direction after acceptance. Preserve unrelated instructions when
+proposing a merged replacement.
+
+| User answer | Canonical write |
+| --- | --- |
+| Primary audience, positioning or voice correction | `patch.knowledge: { audience/positioning/voice: <answer> }` (one actual key). During onboarding, `brand_onboarding { action: "review_research", review: { action: "correct", field, value } }` writes these existing corrections with provenance. |
+| Founder story, customer pains, objections, buying trigger or useful audience detail without a structured field | `patch.facts: [{ kind: "insight", text }]`; retain attribution such as "Founder reports: …" rather than turn a belief into a verified result. |
+| Required wording or pronunciation | `patch.facts: [{ kind: "must", text }]`; pronunciation is exactly `Pronounce "<term>" as "<say_as>"`. |
+| Forbidden claim, word or visual | `patch.facts: [{ kind: "dont", text }]`. |
+| Durable visual, voice or pacing preference | `patch.facts: [{ kind: "do", text }]` for a preference; `dont` for an avoidance; `template_hint` for a preferred format. Prefix video-only preferences with "Video preference:". |
+
+Facts are existing `ad_brand_learning` rows with user provenance; they are not a second profile.
+Update a matching rule by its returned `id` instead of adding duplicates. Preserve unrelated
+rules and the user's exact meaning. Only use the legacy facts shape for explicitly user-authored
+answers when the live schema lacks intent fields; agent suggestions still need a proposal path.
+
+**Claims and plans have separate gates.** A founder assertion or proof point is not an approved,
+evidence-backed claim or consent to quote a customer. Use the existing evidence/claims and
+operating-plan tools only if registered, following their proposal, evidence and confirmation
+requirements. Never encode a spend cap, approver or emergency stop as a learning. If that write
+path is missing, report the specific unsaved item and keep it pending for the supported review
+surface; do not claim it was saved or create a parallel local profile.
+
+After every write, **read back before saying saved**: use `brand_read` with `kit`, `learnings`
+or `onboarding` as appropriate, or `brand_onboarding { action: "status", brand_id }` after an
+onboarding answer. Verify the intended field/rule, its source and the absence of a conflicting
+duplicate. A generic success response, pending proposal, ignored key or truncated result is not
+proof. Report partial saves honestly. Carry the verified rules into the current task and the
+routed skill; claims still pass their own safety gate.
+
 ## Picking source ads — use approved sources, not the retired catalog
 
 When the user wants to make ads but has NOT named a specific template (id/slug/Community
@@ -332,9 +439,10 @@ run through the `gooseworks` CLI (`gooseworks fetch` / `gooseworks call`), like
 - **Treat competitor ads as inspiration** — never attest rights, imply ownership, or promise to
   copy a competitor's distinctive expression.
 - **Reconcile brand facts into the kit** — when the user states or changes something brand-level
-  mid-task, check it against `get_brand_kit` and, with their ok, persist it via `update_brand_kit`
-  / `upsert_brand_product` / `add_brand_product_image` so it sticks for future ads. Ask first;
-  never silently mutate the kit.
+  mid-task, compare it with `brand_read`. Save explicitly authorized corrections through
+  `brand_update` with correction intent and the user's exact statement, or the user's own
+  images through `media_upload`; read back before saying saved. Proposed improvements stay
+  pending. Ask only when it is unclear whether a one-ad direction should apply to future ads.
 - **Record feedback** — when the user reacts to a generated image, inspect and call
   `set_creative_feedback` so the quality loop learns.
 - **Plan mode is opt-in** — only use the live approval option, then `list_ad_approvals` and

package/skills/goose-product-photos/SKILL.md

@@ -26,6 +26,58 @@ Photos studio uses, so the skill and the app can never drift. The point is to **
 usable product imagery** — approved photos join the brand kit and can then feed the ad workflow
 (`goose-ads`).
 
+## How to talk to the customer (applies to every message you send them)
+
+The customer is a marketer or founder, not an engineer. Everything in this skill about tools,
+fields, files, polling, models and pipeline steps is for YOU. Never pass it on to them.
+
+- **Say what they get and what they need to decide, never how it's made.**
+  Bad: "Checking the media-proxy helpers for voiceover timestamps and lipsync." / "Generated with
+  gpt-image-2 at high quality, mouth closed, passes QC."
+  Good: "Recording the voices now." / "Here are your two hosts."
+- **Never mention** tool, file or field names, ids, JSON, commands, scripts, installed software,
+  uploads, model or vendor names, timings in seconds or frames, retries, polling, internal statuses
+  or your own quality checks. Fix what you can quietly. If they ask how something works, explain it
+  simply.
+- **Update them only at milestones they care about**: choices confirmed, script and voices done,
+  visuals done, ready to review, finished. One short line each, then stay quiet until the next
+  milestone. No update for setup, downloads, uploads or saving.
+- **Money is in credits, with a number**: "the full video uses about N credits". Never "the cheap
+  pieces" or "the expensive render".
+- **Problems:** say what it means for them and what they can do, in one or two sentences. No error
+  codes or stack traces. Only raise a problem that changes something for them.
+- **Use their words**: script, voice, hook, scene, host, ending, logo, the product shot.
+- **No filler**: no "Great question!", "Certainly!", "I hope this helps!", no restating what they
+  just said at length.
+
+Example. Instead of a dozen lines about render tools, scripts, uploads and portraits, send:
+"Got it: warm tone, home podcast studio, Brielle as the skeptic and Mark as the believer." then
+"Script and voices are done (about 34 seconds)." then "Ready for you to review: the script, voices,
+both hosts and the ending. You can also review your recipe ingredients in the app: <link>. Say go
+here and I'll make the full video (about N credits)."
+
+## Use current instructions for new work
+
+Before a new task in a terminal host, run `gooseworks skills status` once. It compares the
+installed entry files, running CLI and published npm release. An older CLI needs a package
+upgrade before `gooseworks update`; update alone only uses that CLI's bundled instructions.
+Preserve local edits or unknown install provenance. Review/back up before explicitly replacing
+modified files; never quietly reinstall over them. If the release check is unavailable, report
+that freshness is unknown rather than claiming the local copy is latest.
+
+For a new recipe run, fetch its package from the connected catalog. Retain the returned
+`version` / `contentHash` and every dependency's hash with the saved package. When reusing a
+saved fetch JSON, `gooseworks fetch <slug> --saved-package <file>` returns the current package
+and a hash comparison without changing that file. With MCP, if the advertised `catalog_fetch`
+schema accepts them, send `saved_content_hash` and `saved_dependency_hashes`; otherwise fetch
+normally and compare the returned hashes yourself. Missing hashes mean unknown, not current.
+The server cannot inspect a client's saved files; hash metadata does not certify later edits.
+Fetch current packages into a new run directory and report stale saved instructions. Preserve
+an existing approved run's recorded package; changing that harness requires a reviewed change
+and approval before spending. Hosted installed snapshots use the existing Skills Update action.
+Skill content and a host's cached MCP tool schemas are separate: refreshing one does not refresh
+the other. Check the actual advertised tools before using new fields.
+
 ## Prerequisite — the GooseWorks MCP server is REQUIRED
 
 Everything goes through the `mcp__gooseworks__*` tools. If they are not available, **stop and
@@ -35,7 +87,7 @@ HTTP/file fallback.
 ## Start from the brand context — don't re-ask what it already answers
 
 If the `gooseworks` router handed you brand context, USE IT. If you were invoked directly, call
-`brand_get_context` yourself first. It answers most of the setup questions below, so **do not ask
+`brand_read` yourself first. It answers most of the setup questions below, so **do not ask
 the user for them**:
 
 - **Which product?** — the context's `products[]` are the real catalog entries. Offer them; never
@@ -99,7 +151,7 @@ whether a human model is wanted (which needs explicit consent — see the rules)
 
 ## Workflow — shoot a product
 
-1. **Load the brand context** (`brand_get_context`, or reuse what the router passed you) and
+1. **Load the brand context** (`brand_read`, or reuse what the router passed you) and
    **resolve the brand + product.** `list_ad_brands` → `brand_id`. `list_brand_products` → pick a
    `product_id` from the catalog you already know about. If the product genuinely isn't there,
    `import_product` (poll `get_product_import`).
@@ -117,7 +169,7 @@ whether a human model is wanted (which needs explicit consent — see the rules)
 - **Never invent product facts.** The backend grounds the shot on the product's real images; don't
   describe a product you can't see.
 - **Use the brand context instead of interviewing the user.** Product, audience, voice, positioning,
-  logo/colors/fonts all come from `brand_get_context` / the brand kit. Ask only for the shot
+  logo/colors/fonts all come from `brand_read` / the brand kit. Ask only for the shot
   category, count, quality, and model consent.
 - **Ask before spending.** Quote the estimate and confirm `count` / `quality` before
   `generate_product_photos` — it reserves credits.