takomi 2.1.37 → 2.1.39

package/plugins/takomi-flow/references/flow-provider-contract.md

@@ -0,0 +1,326 @@
+# TakomiFlow Provider Contract
+
+## Purpose
+
+TakomiFlow gives agents a stable interface for asking Google Flow to create assets through a browser profile the user controls.
+
+## Surfaces
+
+- Skill: route Codex behavior and safety rules.
+- CLI: run browser workflows, request preparation, validation, and asset inspection.
+- MCP: expose safe no-spend commands as callable agent tools.
+
+MCP server:
+
+```bash
+node scripts/mcp-server.mjs
+```
+
+Smoke test:
+
+```bash
+node scripts/mcp-smoke.mjs
+```
+
+MCP tools mirror stable JSON operations: capabilities, doctor, audit, examples, template, prepare, workflow, validate, observe, generate, selftest, inspect, latest, runs, assets, review, collect, and report.
+
+Browser-capable MCP tools require explicit `allowBrowser=true`. Generation also requires the normal spend guard.
+
+MCP resources:
+
+- `takomi-flow://contract`
+- `takomi-flow://capabilities`
+- `takomi-flow://examples`
+- `takomi-flow://schemas/request`
+- `takomi-flow://schemas/result`
+- `takomi-flow://schemas/collection`
+- `takomi-flow://templates/video`
+- `takomi-flow://templates/image`
+
+MCP prompts:
+
+- `takomi_flow_video_workflow`
+- `takomi_flow_image_workflow`
+- `takomi_flow_review_workflow`
+- `takomi_flow_collect_workflow`
+
+## Agent Preflight
+
+Run this before browser work when reliability matters:
+
+```bash
+node scripts/takomi-flow.mjs doctor
+node scripts/takomi-flow.mjs audit
+```
+
+`audit` is the preferred agent preflight. It reports readiness, safe no-spend actions, gated browser/spend actions, recent runs, and recommended next steps.
+
+First-run agents should also check for an existing trusted Chrome DevTools endpoint before launching a new browser:
+
+```bash
+curl http://127.0.0.1:9222/json/version
+```
+
+If the endpoint exists, reuse it with `--cdp-url http://127.0.0.1:9222`. If it does not exist, run `trusted-chrome` and ask the user to sign into Google Flow manually. MCP is optional; every MCP operation has a CLI equivalent through `node scripts/takomi-flow.mjs`.
+
+Run this after install or edits:
+
+```bash
+node scripts/takomi-flow.mjs selftest
+```
+
+Discover supported agent options:
+
+```bash
+node scripts/takomi-flow.mjs capabilities
+node scripts/takomi-flow.mjs examples
+```
+
+Observe the current Flow UI without spending credits:
+
+```bash
+node scripts/takomi-flow.mjs observe
+node scripts/takomi-flow.mjs observe --browser-channel chrome
+```
+
+If Google login shows "This browser or app may not be secure", rerun browser commands with
+`trusted-chrome`. Playwright-launched Chrome can still expose automation flags such as
+`--no-sandbox`; `trusted-chrome` starts Chrome directly with a remote debugging port and a dedicated
+TakomiFlow profile. After manual login, pass `--cdp-url http://127.0.0.1:9222` so TakomiFlow attaches
+to the trusted browser session instead of automating credential entry.
+
+Verified signed-in observation currently sees a Flow dashboard with project cards, `PRO` account
+state, and a `New project` button. Treat this as the preferred selector discovery starting point.
+The project editor currently exposes a prompt textbox with text `What do you want to create?`, plus
+`Agent`, `Agent Instructions`, `Settings`, file input, and `Create` buttons. Prompt filling has been
+verified without pressing Create.
+Live video durations are `4`, `6`, `8`, and `10` seconds. If the agent asks for an unsupported
+duration, Flow may ask a follow-up. A verified generation also asked for explicit approval before
+spending 7 credits for one video. After output creation, opening the generated media reveals a
+toolbar `download` button that saves the MP4.
+
+Use templates when starting a request from scratch:
+
+```bash
+node scripts/takomi-flow.mjs template --kind video
+node scripts/takomi-flow.mjs template --kind image
+```
+
+Validate before generation:
+
+```bash
+node scripts/takomi-flow.mjs validate --request <request.json>
+```
+
+One-call agent workflow:
+
+```bash
+node scripts/takomi-flow.mjs workflow --kind video --prompt "cinematic AI lab scene" --variations 2
+```
+
+`workflow` prepares and validates a request in one call. Add `--submit --allow-browser --allow-spend` only after explicit user approval; the normal spend guard still applies.
+
+## Request JSON
+
+Agents can read `takomi-flow://schemas/request` for the JSON Schema version of this shape.
+
+```json
+{
+  "schemaVersion": 1,
+  "kind": "video",
+  "prompt": "cinematic AI lab scene with practical lighting",
+  "variations": 2,
+  "aspectRatio": "16:9",
+  "durationSeconds": 8,
+  "mode": "text-to-video",
+  "modelHint": "best-available",
+  "outputDir": "C:/Users/johno/.takomi-flow/runs",
+  "allowSpend": false,
+  "extractFrames": 4,
+  "notes": "Optional agent notes for traceability."
+}
+```
+
+## Fields
+
+Agents can discover the same fields from `capabilities.requestFields`.
+
+- `kind`: `video` or `image`.
+- `prompt`: Required non-empty generation prompt.
+- `variations`: Positive integer. Defaults to `1`.
+- `aspectRatio`: Optional UI hint such as `16:9`, `9:16`, or `1:1`.
+- `durationSeconds`: Optional video duration hint.
+- `mode`: Optional Flow mode hint such as `text-to-video`, `image-to-video`, or `text-to-image`.
+- `modelHint`: Optional human-readable model or quality hint.
+- `outputDir`: Optional base output directory.
+- `allowSpend`: Must be `true` for generation submission.
+- `extractFrames`: Optional number of review frames to extract from downloaded videos.
+- `sourceAssets`: Optional array of local file paths for future image/video-to-video flows.
+
+## Validation JSON
+
+`validate` normalizes request values, checks them against `capabilities`, verifies source asset paths, and reports spend-guard state:
+
+```json
+{
+  "schemaVersion": 1,
+  "status": "ok",
+  "normalized": {},
+  "errors": [],
+  "warnings": []
+}
+```
+
+## Result JSON
+
+Agents can read `takomi-flow://schemas/result` for the JSON Schema version of run metadata.
+
+```json
+{
+  "schemaVersion": 1,
+  "status": "manual_action_required",
+  "runId": "20260701-120000-flow",
+  "kind": "video",
+  "prompt": "cinematic AI lab scene with practical lighting",
+  "projectUrl": "https://labs.google/fx/tools/flow/project/example",
+  "settingsPlan": {
+    "requested": {
+      "mode": "text-to-video",
+      "variations": 2,
+      "aspectRatio": "16:9",
+      "durationSeconds": 8
+    },
+    "automatic": ["prompt", "download folder", "metadata", "asset catalog"],
+    "selectorDependent": [
+      { "field": "aspectRatio", "value": "16:9" }
+    ]
+  },
+  "assets": [],
+  "assetCatalogPath": "C:/Users/johno/.takomi-flow/runs/20260701-120000-flow/assets.json",
+  "screenshots": [],
+  "errors": [],
+  "manualActions": [
+    "Complete Google login or Flow consent in the opened browser."
+  ],
+  "metadataPath": "C:/Users/johno/.takomi-flow/runs/20260701-120000-flow/run.json"
+}
+```
+
+`projectUrl` records the exact Flow project/editor URL used for the run so agents do not lose track of generated projects. `settingsPlan` preserves the user's requested Flow options in run metadata. Prompt entry, downloads, metadata, asset cataloging, and frame extraction are automated. Mode, aspect ratio, duration, model controls, source assets, and multi-variation UI selection are selector-dependent until `observe` captures the live Flow controls.
+
+## Status Values
+
+- `prepared`: Request file created; no browser action happened.
+- `ok`: Command completed and artifacts were written.
+- `downloaded`: One or more assets were downloaded.
+- `manual_action_required`: User action is required in the browser.
+- `blocked`: Flow showed quota, safety, captcha, account, or unsupported UI state.
+- `failed`: Script error or unrecoverable automation failure.
+
+## Safety Invariants
+
+- Never store Google credentials.
+- Never submit generation unless request `allowSpend` is true or `TAKOMI_FLOW_ALLOW_SPEND=true`.
+- Never bypass Google account, captcha, safety, or quota controls.
+- Always write a result file, even on failure.
+- Always save downloads into the run directory unless the request explicitly overrides it.
+
+## Asset Catalog
+
+Run:
+
+```bash
+node scripts/takomi-flow.mjs assets --run <run.json|run-dir> --frames 4
+```
+
+The command writes `assets.json` next to `run.json`. Video assets are probed with `ffprobe` when available, and review frames are extracted with `ffmpeg` when `--frames` is greater than zero.
+
+## Run Review
+
+Run:
+
+```bash
+node scripts/takomi-flow.mjs review --run <run.json|run-dir> --frames 4
+```
+
+`review` is the preferred post-generation agent command. It inspects the run, catalogs downloaded assets, extracts review frames, writes a Markdown report, and returns next actions.
+
+## Collection
+
+Run:
+
+```bash
+node scripts/takomi-flow.mjs collect --run <run.json|run-dir> --target-dir <path> --frames 4 --include-frames
+```
+
+`collect` reviews a run, copies assets/report/optional frames into a downstream target folder, and writes `takomi-flow-collection.json` as a manifest.
+
+Agents can read `takomi-flow://schemas/collection` for the JSON Schema version of the collection manifest.
+
+## Markdown Reports
+
+Run:
+
+```bash
+node scripts/takomi-flow.mjs report --run <run.json|run-dir>
+node scripts/takomi-flow.mjs report --output-dir <runs-dir> --limit 10
+```
+
+The command writes `report.md` next to a single run, or `takomi-flow-report.md` in a runs directory. Reports include status, metadata paths, screenshots, assets, errors, manual actions, and catalog details when `assets.json` exists.
+
+## Diagnostics JSON
+
+`doctor` returns:
+
+```json
+{
+  "schemaVersion": 1,
+  "status": "ok",
+  "flowUrl": "https://labs.google/fx/tools/flow",
+  "profileDir": "C:/Users/johno/.takomi-flow/browser-profile",
+  "outputDir": "C:/Users/johno/.takomi-flow/runs",
+  "checks": [],
+  "recommendations": []
+}
+```
+
+## Capabilities JSON
+
+`capabilities` returns supported kinds, modes, variation limits, aspect ratios, output artifact names, safety invariants, and available commands. Agents should prefer this over hard-coded assumptions.
+
+## Observation JSON
+
+`observe` writes a normal `run.json` and includes a `controls` object:
+
+```json
+{
+  "controls": {
+    "buttons": [],
+    "inputs": [],
+    "links": []
+  }
+}
+```
+
+Use it to tune Flow selectors after Google changes the UI.
+
+## Self-Test JSON
+
+`selftest` runs a deterministic no-spend verification pass:
+
+- doctor diagnostics
+- readiness audit
+- capability loading
+- example loading
+- video/image template loading
+- request preparation
+- one-call workflow preparation/validation
+- settings-plan metadata for requested Flow options
+- request validation
+- spend-guard expectation
+- synthetic MP4 cataloging and frame extraction
+- Markdown report generation
+- one-call run review
+- downstream asset collection
+
+It writes artifacts under `<outputDir>/selftest`.

package/plugins/takomi-flow/scripts/lib/agent-plan.mjs

@@ -0,0 +1,130 @@
+import { loadCapabilities } from './capabilities.mjs';
+import { normalizeRequest } from './request.mjs';
+
+export function createAgentPlan(args = {}) {
+  const request = normalizeRequest(args);
+  const capabilities = loadCapabilities();
+  const submit = Boolean(args.submit);
+  const collectTarget = args.targetDir || args['target-dir'];
+  return {
+    schemaVersion: 1,
+    status: 'ready',
+    provider: capabilities.provider,
+    summary: `${request.kind} ${request.mode} Flow job with ${request.variations} variation(s).`,
+    request,
+    gates: gates(request, submit),
+    mcpSequence: mcpSequence(request, { submit, collectTarget }),
+    cliSequence: cliSequence(request, { submit, collectTarget }),
+    expectedOutputs: expectedOutputs(request, collectTarget),
+    nextActions: nextActions(submit, collectTarget),
+  };
+}
+
+function gates(request, submit) {
+  const items = [
+    {
+      name: 'spend',
+      required: submit,
+      satisfied: request.allowSpend,
+      note: 'Generation submission may spend Flow credits and requires allowSpend=true.',
+    },
+    {
+      name: 'browser',
+      required: submit,
+      satisfied: false,
+      note: 'Browser-opening MCP tools require allowBrowser=true at call time.',
+    },
+  ];
+  return submit ? items : items.map(item => ({ ...item, required: false }));
+}
+
+function mcpSequence(request, options) {
+  const workflowArgs = {
+    kind: request.kind,
+    prompt: request.prompt,
+    variations: request.variations,
+    aspectRatio: request.aspectRatio,
+    durationSeconds: request.durationSeconds,
+    mode: request.mode,
+    modelHint: request.modelHint,
+    outputDir: request.outputDir,
+    allowSpend: request.allowSpend,
+    extractFrames: request.extractFrames,
+    sourceAssets: request.sourceAssets,
+    submit: options.submit,
+    allowBrowser: options.submit,
+  };
+  const steps = [
+    { tool: 'takomi_flow_audit', arguments: { outputDir: request.outputDir } },
+    { tool: 'takomi_flow_workflow', arguments: compact(workflowArgs) },
+    { tool: 'takomi_flow_review', arguments: { run: '<run.json|run-dir>', frames: request.extractFrames || 0 } },
+  ];
+  if (options.collectTarget) {
+    steps.push({
+      tool: 'takomi_flow_collect',
+      arguments: {
+        run: '<run.json|run-dir>',
+        targetDir: options.collectTarget,
+        frames: request.extractFrames || 0,
+        includeFrames: true,
+      },
+    });
+  }
+  return steps;
+}
+
+function cliSequence(request, options) {
+  const base = [
+    'node scripts/takomi-flow.mjs audit',
+    `node scripts/takomi-flow.mjs workflow --kind ${request.kind} --prompt "${escapeArg(request.prompt)}"${optionArgs(request, options.submit)}`,
+    `node scripts/takomi-flow.mjs review --run <run.json|run-dir> --frames ${request.extractFrames || 0}`,
+  ];
+  if (options.collectTarget) {
+    base.push(`node scripts/takomi-flow.mjs collect --run <run.json|run-dir> --target-dir "${escapeArg(options.collectTarget)}" --frames ${request.extractFrames || 0} --include-frames`);
+  }
+  return base;
+}
+
+function optionArgs(request, submit) {
+  const args = [];
+  if (request.variations) args.push(`--variations ${request.variations}`);
+  if (request.aspectRatio) args.push(`--aspect-ratio ${request.aspectRatio}`);
+  if (request.durationSeconds) args.push(`--duration ${request.durationSeconds}`);
+  if (request.mode) args.push(`--mode ${request.mode}`);
+  if (request.modelHint) args.push(`--model "${escapeArg(request.modelHint)}"`);
+  if (request.outputDir) args.push(`--output-dir "${escapeArg(request.outputDir)}"`);
+  if (request.extractFrames) args.push(`--extract-frames ${request.extractFrames}`);
+  if (request.sourceAssets.length) args.push(`--assets "${escapeArg(request.sourceAssets.join(','))}"`);
+  if (submit) args.push('--submit --allow-browser --allow-spend');
+  return args.length ? ` ${args.join(' ')}` : '';
+}
+
+function expectedOutputs(request, collectTarget) {
+  const outputs = [
+    `${request.outputDir}/requests/<timestamp>-request.json`,
+    `${request.outputDir}/<runId>/run.json`,
+    `${request.outputDir}/<runId>/downloads/`,
+    `${request.outputDir}/<runId>/assets.json`,
+    `${request.outputDir}/<runId>/report.md`,
+  ];
+  if (request.extractFrames) outputs.push(`${request.outputDir}/<runId>/frames/`);
+  if (collectTarget) outputs.push(`${collectTarget}/takomi-flow-collection.json`);
+  return outputs;
+}
+
+function nextActions(submit, collectTarget) {
+  const actions = ['Run the audit step first and treat missing profile as a bootstrap/login gate.'];
+  if (!submit) actions.push('Use the workflow step without submit to prepare and validate the request without spending credits.');
+  if (submit) actions.push('Confirm the user explicitly approved spending Flow credits before running the submit step.');
+  actions.push('After generation, review run metadata, errors, screenshots, and downloaded assets.');
+  if (collectTarget) actions.push('Collect reviewed outputs into the downstream target folder for pipeline reuse.');
+  return actions;
+}
+
+function compact(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+
+function escapeArg(value) {
+  return String(value).replaceAll('"', '\\"');
+}

package/plugins/takomi-flow/scripts/lib/api.mjs

@@ -0,0 +1,113 @@
+import { createPreparedRequest } from './request.mjs';
+import fs from 'node:fs';
+import path from 'node:path';
+import { validateRequestFile } from './request-validator.mjs';
+import { runDoctor } from './doctor.mjs';
+import { loadCapabilities } from './capabilities.mjs';
+import { listTemplates, loadTemplate, writeTemplate } from './templates.mjs';
+import { runSelfTest } from './selftest.mjs';
+import { inspectRun, latestRun, listRuns, resolveRun } from './inspect.mjs';
+import { catalogAssets } from './media.mjs';
+import { observeFlow } from './observe.mjs';
+import { generateFromRequest } from './generation.mjs';
+import { createReport } from './report.mjs';
+import { runWorkflow } from './workflow.mjs';
+import { reviewRun } from './review.mjs';
+import { runAudit } from './audit.mjs';
+import { collectRun } from './collect.mjs';
+import { loadExamples } from './examples.mjs';
+import { createAgentPlan } from './agent-plan.mjs';
+
+export async function doctor(args = {}) {
+  return runDoctor({ profileDir: args.profileDir, outputDir: args.outputDir });
+}
+
+export function capabilities() {
+  return loadCapabilities();
+}
+
+export async function observe(args = {}) {
+  return observeFlow({
+    profileDir: args.profileDir,
+    outputDir: args.outputDir,
+    browserChannel: args.browserChannel,
+    cdpUrl: args.cdpUrl,
+    headless: Boolean(args.headless),
+  });
+}
+
+export function template(args = {}) {
+  if (!args.kind) return { templates: listTemplates() };
+  if (args.outputDir) return writeTemplate(args.kind, args.outputDir);
+  return loadTemplate(args.kind);
+}
+
+export function prepare(args = {}) {
+  const { request, requestPath } = createPreparedRequest(args);
+  return { status: 'prepared', requestPath, request };
+}
+
+export function validate(args = {}) {
+  return validateRequestFile(args.request);
+}
+
+export async function selftest(args = {}) {
+  return runSelfTest({ outputDir: args.outputDir });
+}
+
+export function inspect(args = {}) {
+  return inspectRun(args.run);
+}
+
+export function latest(args = {}) {
+  return latestRun(args.outputDir);
+}
+
+export function runs(args = {}) {
+  return listRuns(args.outputDir, args.limit);
+}
+
+export async function assets(args = {}) {
+  const run = resolveRun(args.run);
+  return catalogAssets(run, assetPathsForRun(run), { frames: args.frames || 0 });
+}
+
+export async function generate(args = {}) {
+  return generateFromRequest(args);
+}
+
+export function report(args = {}) {
+  return createReport(args);
+}
+
+export async function workflow(args = {}) {
+  return runWorkflow(args);
+}
+
+export async function review(args = {}) {
+  return reviewRun(args);
+}
+
+export async function audit(args = {}) {
+  return runAudit(args);
+}
+
+export async function collect(args = {}) {
+  return collectRun(args);
+}
+
+export function examples(args = {}) {
+  return loadExamples(args.name);
+}
+
+export function plan(args = {}) {
+  return createAgentPlan(args);
+}
+
+function assetPathsForRun(run) {
+  if (run.data.assets?.length) return run.data.assets;
+  if (!fs.existsSync(run.downloadsDir)) return [];
+  return fs.readdirSync(run.downloadsDir)
+    .map(name => path.join(run.downloadsDir, name))
+    .filter(filePath => fs.statSync(filePath).isFile());
+}

package/plugins/takomi-flow/scripts/lib/args.mjs

@@ -0,0 +1,57 @@
+export function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      args._.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      args[key] = true;
+      continue;
+    }
+    args[key] = next;
+    i += 1;
+  }
+  return args;
+}
+
+export function printUsage() {
+  console.log(`
+TakomiFlow
+
+Usage:
+  node scripts/takomi-flow.mjs bootstrap [--profile-dir <path>] [--browser-channel chrome] [--cdp-url <url>] [--headless]
+  node scripts/takomi-flow.mjs doctor [--profile-dir <path>] [--output-dir <path>]
+  node scripts/takomi-flow.mjs audit [--profile-dir <path>] [--output-dir <path>]
+  node scripts/takomi-flow.mjs capabilities
+  node scripts/takomi-flow.mjs examples [--name <example-name>]
+  node scripts/takomi-flow.mjs trusted-chrome [--port 9222] [--profile-dir <path>] [--chrome-path <path>]
+  node scripts/takomi-flow.mjs plan --kind <video|image> --prompt <text> [--submit --target-dir <path>]
+  node scripts/takomi-flow.mjs observe [--profile-dir <path>] [--output-dir <path>] [--browser-channel chrome] [--cdp-url <url>] [--headless]
+  node scripts/takomi-flow.mjs smoke [--profile-dir <path>] [--output-dir <path>] [--browser-channel chrome] [--cdp-url <url>]
+  node scripts/takomi-flow.mjs prepare --kind <video|image> --prompt <text> [--variations 1]
+  node scripts/takomi-flow.mjs workflow --kind <video|image> --prompt <text> [--submit --allow-browser --allow-spend]
+  node scripts/takomi-flow.mjs template --kind <video|image> [--output-dir <path>]
+  node scripts/takomi-flow.mjs validate --request <path>
+  node scripts/takomi-flow.mjs generate --request <path>
+  node scripts/takomi-flow.mjs selftest [--output-dir <path>]
+  node scripts/takomi-flow.mjs inspect --run <run.json|run-dir>
+  node scripts/takomi-flow.mjs latest [--output-dir <path>]
+  node scripts/takomi-flow.mjs runs [--output-dir <path>] [--limit 20]
+  node scripts/takomi-flow.mjs assets --run <run.json|run-dir> [--frames 4]
+  node scripts/takomi-flow.mjs review --run <run.json|run-dir> [--frames 4]
+  node scripts/takomi-flow.mjs collect --run <run.json|run-dir> --target-dir <path> [--frames 4 --include-frames]
+  node scripts/takomi-flow.mjs report [--run <run.json|run-dir>] [--output-dir <path>]
+
+Spend guard:
+  generation submits only when request allowSpend=true or TAKOMI_FLOW_ALLOW_SPEND=true.
+
+Google login note:
+  If Google says the browser may not be secure, use trusted Chrome attach mode:
+  node scripts/takomi-flow.mjs trusted-chrome
+  Then log in manually and attach with --cdp-url http://127.0.0.1:9222.
+`);
+}

package/plugins/takomi-flow/scripts/lib/audit.mjs

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import { runDoctor } from './doctor.mjs';
+import { loadCapabilities } from './capabilities.mjs';
+import { listRuns } from './inspect.mjs';
+
+export async function runAudit(args = {}) {
+  const doctor = await runDoctor({
+    profileDir: args.profileDir,
+    outputDir: args.outputDir,
+  });
+  const capabilities = loadCapabilities();
+  const history = listRuns(doctor.outputDir, args.limit || 5);
+  const profileReady = fs.existsSync(doctor.profileDir);
+  const browserReady = doctor.checks.every(check => (
+    check.name === 'profileDir' || check.status !== 'failed'
+  ));
+  return {
+    schemaVersion: 1,
+    status: doctor.status === 'failed' ? 'failed' : 'ok',
+    readiness: {
+      browserAutomation: browserReady,
+      flowProfile: profileReady,
+      mediaReview: hasCheck(doctor, 'ffmpeg') && hasCheck(doctor, 'ffprobe'),
+      mcpTools: capabilities.mcpTools.length,
+      mcpResources: capabilities.mcpResources.length,
+    },
+    safeActions: [
+      'capabilities',
+      'examples',
+      'plan',
+      'template',
+      'workflow without submit',
+      'validate',
+      'runs',
+      'inspect',
+      'assets',
+      'review',
+      'collect',
+      'report',
+      'selftest',
+    ],
+    gatedActions: [
+      'bootstrap requires a headed browser and manual Google login',
+      'observe requires allowBrowser=true',
+      'generate requires allowBrowser=true and allowSpend=true',
+      'workflow submit requires allowBrowser=true and allowSpend=true',
+    ],
+    doctor,
+    recentRuns: history.runs,
+    nextActions: nextActions(doctor, profileReady, history.runs),
+  };
+}
+
+function hasCheck(doctor, name) {
+  return doctor.checks.some(check => check.name === name && check.status === 'ok');
+}
+
+function nextActions(doctor, profileReady, runs) {
+  const actions = [...doctor.recommendations];
+  if (!profileReady) actions.push('Run bootstrap in headed mode and log into Google Flow manually.');
+  if (!runs.length) actions.push('Run workflow to prepare the first request, or smoke after login.');
+  if (runs.some(run => run.status === 'downloaded')) actions.push('Run review on downloaded runs before reusing assets.');
+  if (!actions.length) actions.push('TakomiFlow is ready for safe no-spend workflow preparation.');
+  return [...new Set(actions)];
+}