@localizeaso/cli 0.1.0-preview.5 → 0.1.0-preview.6

package/README.md

@@ -11,10 +11,15 @@ npx @localizeaso/cli@preview --help
 For local desktop or BYO-agent use, sign in once and store a local CLI session:
 
 ```sh
+npx @localizeaso/cli@preview skills install
 localizeaso login --staging
 localizeaso whoami --json
 ```
 
+`skills install` copies the bundled `localizeaso-review-agent` skill into local
+Codex/agent skill folders. The same package also exposes the safe MCP bridge for
+Vercel AI SDK or other agent runtimes that call LocalizeASO through tools.
+
 For VPS, CI, and hosted automation, prefer an explicit bearer token:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@localizeaso/cli",
-  "version": "0.1.0-preview.5",
+  "version": "0.1.0-preview.6",
   "description": "LocalizeASO command-line tools for agent-assisted App Store review workflows.",
   "type": "module",
   "repository": {
@@ -14,6 +14,7 @@
   "files": [
     "README.md",
     "scripts",
+    "skills",
     "packages/asc-shared/dist"
   ],
   "scripts": {

package/scripts/localizeaso.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 import { spawnSync } from 'node:child_process';
-import { chmodSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { chmodSync, cpSync, existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -13,6 +13,8 @@ const reviewAgentScript = join(__dirname, 'review-agent.mjs');
 const reviewMcpScript = join(__dirname, 'review-mcp.mjs');
 const astroMcpExportScript = join(__dirname, 'export-astro-mcp-apps.mjs');
 const ensureSharedBuildScript = join(__dirname, 'ensure-shared-build.mjs');
+const packagedSkillsRoot = join(repoRoot, 'skills');
+const repoSkillsRoot = join(repoRoot, '.agents', 'skills');
 const DEFAULT_CLI_CONFIG_PATH = join(homedir(), '.localizeaso', 'config.json');
 const LOCAL_BACKEND_URL = 'http://localhost:8787';
 const LOCAL_DASHBOARD_URL = 'http://localhost:5174';
@@ -188,6 +190,11 @@ Usage:
     need LOCALIZEASO_TOKEN in every shell. LOCALIZEASO_TOKEN, LOCALIZEASO_BACKEND,
     and LOCALIZEASO_DASHBOARD still override the local config for CI/automation.
 
+  localizeaso skills install [localizeaso-review-agent] [--target codex|agents|both]
+    Install the bundled LocalizeASO review-agent skill locally for Codex and
+    agent runtimes that read ~/.agents/skills. This is local setup only; it does
+    not log in, approve, apply, submit, or touch App Store Connect.
+
   localizeaso workspace jobs --app-id APP_ID
   localizeaso workspace open-next --app-id APP_ID
   localizeaso workspace boundary
@@ -406,6 +413,10 @@ function normalizedArgs(argv) {
     return { kind: command, args };
   }
 
+  if (command === 'skill' || command === 'skills' || command === 'agent-skill' || command === 'agent-skills') {
+    return { kind: 'skills', args };
+  }
+
   if (command === 'dashboard' || command === 'dash') {
     const subcommand = args.shift();
     if (!subcommand || subcommand === 'doctor' || subcommand === 'diagnose' || subcommand === 'health') {
@@ -1475,6 +1486,99 @@ async function readJsonResponse(response) {
   }
 }
 
+function printSkillUsage() {
+  console.log(`Usage:
+  localizeaso skills install [localizeaso-review-agent] [--target codex|agents|both] [--json]
+
+Targets:
+  codex   ~/.codex/skills
+  agents  ~/.agents/skills
+  both    install to both targets (default)
+`);
+}
+
+function resolveSkillSource(skillName) {
+  const candidates = [
+    join(packagedSkillsRoot, skillName),
+    join(repoSkillsRoot, skillName),
+  ];
+  return candidates.find((candidate) => existsSync(join(candidate, 'SKILL.md'))) || '';
+}
+
+function skillInstallTargets(target) {
+  if (target === 'codex') return [{ id: 'codex', root: join(homedir(), '.codex', 'skills') }];
+  if (target === 'agents') return [{ id: 'agents', root: join(homedir(), '.agents', 'skills') }];
+  return [
+    { id: 'codex', root: join(homedir(), '.codex', 'skills') },
+    { id: 'agents', root: join(homedir(), '.agents', 'skills') },
+  ];
+}
+
+function skillsCommand(args = []) {
+  const subcommand = args[0];
+  if (!subcommand || subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+    printSkillUsage();
+    return 0;
+  }
+  if (subcommand !== 'install' && subcommand !== 'add') {
+    console.error(`Unknown skills command: ${subcommand}`);
+    printSkillUsage();
+    return 2;
+  }
+
+  const { flags, positional } = parseLocalFlagArgs(args.slice(1));
+  const skillName = positional[0] || 'localizeaso-review-agent';
+  const target = typeof flags.target === 'string' ? flags.target : 'both';
+  const json = flags.json === true;
+
+  if (!['codex', 'agents', 'both'].includes(target)) {
+    console.error('Invalid --target. Use codex, agents, or both.');
+    return 2;
+  }
+
+  const source = resolveSkillSource(skillName);
+  if (!source) {
+    console.error(`Bundled skill not found: ${skillName}`);
+    return 1;
+  }
+
+  const installed = skillInstallTargets(target).map(({ id, root }) => {
+    const destination = join(root, skillName);
+    mkdirSync(root, { recursive: true });
+    cpSync(source, destination, { recursive: true, force: true });
+    return { target: id, path: destination };
+  });
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          kind: 'localizeaso_skill_install',
+          ok: true,
+          skill: skillName,
+          source,
+          installed,
+          safety: {
+            localSetupOnly: true,
+            approves: false,
+            applies: false,
+            submits: false,
+            touchesAppStoreConnect: false,
+          },
+        },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log(`Installed ${skillName}:`);
+    for (const item of installed) {
+      console.log(`  ${item.target}: ${item.path}`);
+    }
+  }
+  return 0;
+}
+
 function shouldOpenBrowser(flags = {}, env = process.env) {
   if (flags.open === false || flags['no-open'] === true) return false;
   if (env.LOCALIZEASO_DISABLE_OPEN === '1' || env.LOCALIZEASO_DISABLE_BROWSER_OPEN === '1') return false;
@@ -2221,6 +2325,10 @@ async function main() {
     return whoamiCommand(mapped.args);
   }
 
+  if (mapped.kind === 'skills') {
+    return skillsCommand(mapped.args);
+  }
+
   if (mapped.kind === 'workspace-runbook') {
     const buildExit = ensureSharedBuild();
     if (buildExit !== 0) return buildExit;

package/skills/localizeaso-review-agent/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: localizeaso-review-agent
+description: Use when generating LocalizeASO screenshot or field-review proposals with a BYO coding/AI agent. Pulls an agent bundle, writes structured proposals, and never applies changes without human approval.
+version: 1.0.0
+license: MIT
+---
+
+# LocalizeASO Review Agent
+
+Use this skill when acting as a local/BYO agent for LocalizeASO screenshot or field-review jobs.
+
+## Contract
+
+- Fetch review context with the friendly surface command whenever possible: `pnpm localizeaso screenshots bundle <jobId> --out screenshot-bundle.json --handoff screenshot-handoff.json`, `pnpm localizeaso metadata bundle <jobId> --out field-bundle.json --handoff field-handoff.json`, `pnpm localizeaso keywords bundle <jobId> --out field-bundle.json --handoff field-handoff.json`, or `pnpm localizeaso pricing bundle <jobId> --out field-bundle.json --handoff field-handoff.json`.
+- For non-pricing metadata and keyword field reviews, export the provider-neutral ASO keyword detection map before proposal generation with `pnpm localizeaso metadata aso-map <jobId> --out aso-keyword-map.json`, `pnpm localizeaso keywords aso-map <jobId> --out aso-keyword-map.json`, or `pnpm localizeaso fields aso-map <jobId> --surface metadata --out aso-keyword-map.json`. The report is read-only, compatible with any coding agent, and includes `agentCompatibility.audience="any_coding_agent"`, per-locale/per-field keyword matches, positions, popularity, difficulty, source, preferred flags, unassigned keywords, warnings, and errors. Use it to fill `assignedKeywords`, `unassignedKeywords`, `warnings`, and rationale; it never grants approval, apply, publish, status, or App Store Connect submit permission.
+- To create a local/BYO screenshot-review run from an existing manifest, prefer `pnpm localizeaso screenshots auto --file screenshot-job.json --bundle-out screenshot-bundle.json --handoff screenshot-handoff.json` for safe automatic Astro CSV discovery (`optional-auto`), keyword-context attach, bundle export, and human review navigation. Use `pnpm localizeaso screenshots auto-import --file screenshot-job.json --bundle-out screenshot-bundle.json --handoff screenshot-handoff.json` only when discovered Astro CSV rows should also be persisted into the LocalizeASO ASO keyword inventory before the bundle is fetched. If the CSV path is already known, pass `--keywords-csv path/to/astro.csv`; use strict `--keywords-csv auto` only when a missing CSV should fail. These start flows write the agent bundle without applying Figma changes. Start outputs include `reviewConsent` with the human checklist, prohibited agent actions, and the next human open-review command/MCP tool; treat it as consent-screen navigation, not approval or apply permission.
+- Friendly local wrapper aliases are available for safe review setup and proposal work: `pnpm localizeaso screenshots start ...`, `pnpm localizeaso screenshots bundle <jobId> --out screenshot-bundle.json --handoff screenshot-handoff.json`, `pnpm localizeaso screenshots prompt <jobId> --out agent-prompt.md`, `pnpm localizeaso screenshots proposal-template <jobId> --out screenshot-proposal.json`, `pnpm localizeaso screenshots jobs --app-id APP_ID`, `pnpm localizeaso screenshots open-next --app-id APP_ID`, `pnpm localizeaso screenshots open <jobId>`, `pnpm localizeaso screenshots popup <jobId>`, `pnpm localizeaso screenshots readiness <jobId> --proposal-id PROPOSAL_ID`, `pnpm localizeaso screenshots handoff-summary <jobId> --out handoff-summary.json`, `pnpm localizeaso screenshots attach-keywords <jobId> --file keyword-context.json`, `pnpm localizeaso screenshots attach-keywords-csv <jobId> --file optional-auto --astro-dir .`, `pnpm localizeaso screenshots keyword-brief <jobId> --out keyword-brief.json`, `pnpm localizeaso screenshots keyword-prompt <jobId> --out keyword-agent-prompt.md`, `pnpm localizeaso screenshots keyword-automation <jobId> --out keyword-automation.json`, `pnpm localizeaso screenshots submit <jobId> --file screenshot-proposal.json`, `pnpm localizeaso screenshots refine <jobId> --context-snapshot-file copied-review-context.md --instructions "Reviewer feedback" --out screenshot-refine-result.json`, `pnpm localizeaso fields start ...`, `pnpm localizeaso fields bundle <jobId> --out field-bundle.json --handoff field-handoff.json`, `pnpm localizeaso fields prompt <jobId> --out agent-prompt.md`, `pnpm localizeaso fields proposal-template <jobId> --out field-proposal.json`, `pnpm localizeaso fields jobs --app-id APP_ID --surface metadata`, `pnpm localizeaso fields open-next --app-id APP_ID --surface metadata`, `pnpm localizeaso fields open <jobId>`, `pnpm localizeaso fields popup <jobId>`, `pnpm localizeaso fields readiness <jobId> --proposal-id PROPOSAL_ID`, `pnpm localizeaso fields handoff-summary <jobId> --out handoff-summary.json`, `pnpm localizeaso fields sync-keywords <jobId> --out synced-keyword-context.json`, `pnpm localizeaso fields attach-keywords <jobId> --file keyword-context.json`, `pnpm localizeaso fields attach-keywords-csv <jobId> --file optional-auto --astro-dir .`, `pnpm localizeaso fields keyword-brief <jobId> --out keyword-brief.json`, `pnpm localizeaso fields keyword-prompt <jobId> --out keyword-agent-prompt.md`, `pnpm localizeaso fields keyword-automation <jobId> --out keyword-automation.json`, `pnpm localizeaso fields pricing-brief <jobId> --out pricing-brief.json`, `pnpm localizeaso fields submit <jobId> --file field-proposal.json`, and `pnpm localizeaso fields refine <jobId> --context-snapshot-file copied-field-review-context.md --instructions "Reviewer feedback" --out field-refine-result.json`. Generic field keyword sync/context aliases are metadata/keyword-only; pricing jobs reject keyword inputs and use `pnpm localizeaso pricing brief <jobId>` instead. `pnpm localizeaso metadata popup <jobId>` and `pnpm localizeaso keywords popup <jobId>` are friendly aliases for opening the metadata/keyword human review consent screen. `pnpm localizeaso metadata ...` is a friendly alias for the same field-review surface when the job starts from the metadata UI. `pnpm localizeaso pricing bundle|pricing-brief|proposal-template|submit|refine|open|readiness|handoff-summary ...` are friendly aliases for existing pricing field-review jobs. The friendly `screenshots`/`fields`/`metadata`/`keywords`/`pricing` surface intentionally exposes only setup, bundle/prompt/template, metadata/keyword sync/context attach, keyword brief/prompt/automation, pricing brief, queue inspection, human review navigation, proposal submission, open-review/popup, readiness, refine, and handoff-summary aliases; approval, rejection, apply/export, status, publish, and submit remain lower-level human-only commands with explicit consent flags.
+- Friendly `submit` and `submit-proposal` aliases, plus the lower-level `pnpm review:agent submit-proposal` and `pnpm review:agent field-submit-proposal` commands, return the local human review/consent handoff after the proposal is stored without opening a browser by default; add `--open` only when the human is ready for browser navigation. This is navigation only and still does not approve, apply, export, schedule, publish, submit, or mark status.
+- For a combined human review queue across screenshots, metadata, keywords, and pricing, prefer `pnpm localizeaso workspace runbook --app-id APP_ID --astro-app APP_STORE_ID --json` when an agent needs one safe orchestration document for local doctor, Astro keyword export/import, review starts, proposal handoff, and human review navigation. Use `pnpm localizeaso workspace jobs --app-id APP_ID` and `pnpm localizeaso workspace open-next --app-id APP_ID`, or the lower-level `pnpm review:agent review-jobs --app-id APP_ID` and `pnpm review:agent review-open-next --app-id APP_ID`, for queue inspection/navigation. Use `pnpm localizeaso workspace boundary` or `pnpm review:agent monetization-boundary --kind workspace` to inspect the combined free/local, Agent Pass, hosted pass, BYO AI, and hosted-submit boundary. MCP exposes the same runbook through `localizeaso_workspace_runbook`, the same navigation-only workflow through `localizeaso_review_jobs` and `localizeaso_review_open_next`, and the same boundary through `localizeaso_monetization_boundary {"kind":"workspace"}`. These commands only build runbooks, inspect queues, open the next human review screen, or print boundary metadata; they never approve, reject, apply, export, schedule, publish, submit, or mark status.
+- Creating screenshot or field-review jobs requires the user's active LocalizeASO pass for that app/surface. After the job exists, BYO agents may fetch bundles, attach keyword context for screenshots/metadata/keywords, inspect pricing briefs for pricing, and submit proposals without hosted AI usage.
+- Agent Pass is the BYO/no-hosted-AI path. It can export local `asc` metadata/pricing handoffs after approval, but hosted LocalizeASO App Store Connect submit convenience requires Submit Pass or a hosted LocalizeASO pass; if a submit command is absent from the handoff, do not invent or run one.
+- If job creation fails with a CLI JSON error `{ "kind": "backend_error", "status": 402, "code": "ENTITLEMENT_REQUIRED" | "ENTITLEMENT_APP_LIMIT" | "ENTITLEMENT_LANGUAGE_LIMIT" | "ENTITLEMENT_CAPABILITY_REQUIRED" | "ENTITLEMENT_SURFACE_EXPIRED" }`, stop and send the human to choose/adjust a LocalizeASO pass. Do not retry proposal generation until the pass gate is resolved.
+- Generate only a structured proposal and submit it with `pnpm localizeaso screenshots submit <jobId> --file screenshot-proposal.json`, `pnpm localizeaso metadata submit <jobId> --file field-proposal.json`, `pnpm localizeaso keywords submit <jobId> --file field-proposal.json`, or `pnpm localizeaso pricing submit <jobId> --file field-proposal.json`. These commands return the human review handoff without opening a browser by default; add `--open` only when the human is ready for browser navigation. The command output includes `humanReview`, `nextHumanAction`, `reviewSignalContract`, `monetizationBoundary`, `handoffSafety.phase="post_proposal_human_review"`, `handoffSafety.proposalSubmissionOnly=true`, and explicit false apply/approval/submit/status permission flags; treat that as the handoff to the human reviewer, not as approval or apply permission.
+- `monetizationBoundary` is informational and machine-readable: local manifest, CSV keyword, prompt, and proposal-template steps are agent-safe setup; persistent review jobs, review history, approval handoffs, and Figma review/apply plans require an Agent Pass or hosted pass; hosted AI requires a hosted AI pass, while hosted App Store upload/submit convenience requires Submit Pass or a hosted LocalizeASO pass. Do not use it as permission to approve, apply, submit, or mark status.
+- To inspect the free/local vs paid boundary without a backend token, run `pnpm localizeaso boundary --kind screenshots`, `pnpm localizeaso boundary --kind field`, or `pnpm localizeaso workspace boundary`; MCP exposes the same read-only data through `localizeaso_monetization_boundary`. Treat it as product/package guidance only, not as workflow permission.
+- If keyword research was run separately, attach it first with `pnpm localizeaso screenshots attach-keywords <jobId> --file keyword-context.json`, `pnpm localizeaso metadata attach-keywords <jobId> --file keyword-context.json`, or `pnpm localizeaso keywords attach-keywords <jobId> --file keyword-context.json`.
+- Before running Astro, MCP, CSV, or another keyword agent for screenshot jobs, prefer `pnpm localizeaso screenshots keyword-brief <jobId> --out keyword-brief.json`. The brief lists target locales, existing keywords, missing keyword locales, seed screenshot text, the expected provider-neutral keyword-context shape, and attach commands.
+- For a compact ordered Astro/MCP/CSV handoff before screenshot proposal generation, use `pnpm localizeaso screenshots keyword-automation <jobId> --out keyword-automation.json`. It is read-only orchestration guidance and must not approve, reject, apply, mark status, or submit anything.
+- To hand keyword research to Astro MCP or any coding/keyword agent, export a ready-to-use prompt with `pnpm localizeaso screenshots keyword-prompt <jobId> --out keyword-agent-prompt.md`. The prompt is read-only and asks the keyword agent to return provider-neutral `keyword-context.json`.
+- Screenshot bundles include a `handoff` block with dashboard path, absolute `reviewUrl`, backend endpoints, ready-to-run CLI commands, and `handoff.runbook` environment/command/guardrail steps. Use `pnpm localizeaso screenshots bundle <jobId> --out screenshot-bundle.json --handoff screenshot-handoff.json` when an orchestrator should read commands separately, or add `--open` to open the human review screen immediately.
+- CLI bundle outputs also include root `monetizationBoundary` plus `handoffSafety.readOnly=true` and `handoffSafety.bundleContextOnly=true`. Treat bundle fetches as context-only: they can inform proposal generation and safe keyword/prompt/template commands, but they do not approve, reject, apply/export, schedule, submit, or mark status.
+- When a screenshot or non-pricing field bundle includes `handoff.keywordAutomation`, prefer its ordered `steps` before proposal generation. For metadata and keyword field reviews, this may include the ASO keyword detection map command and MCP map tool before keyword brief/prompt work. It is a pre-proposal keyword research path for Astro CSV, MCP keyword agents, provider-neutral `keyword-context.json`, and read-only ASO coverage checks; it must not approve, reject, apply, mark status, or submit anything.
+- `handoff.runbook.commands` are agent-safe proposal/revision/setup commands. If `handoff.postApprovalCommands` is present, treat those commands as human-only after approval; do not run them from an agent proposal pass.
+- Newer handoffs also expose `handoff.agentSafeCommands` and `handoff.humanOnlyCommands` as machine-readable command groups. Prefer `agentSafeCommands` for autonomous setup/proposal work and never run `humanOnlyCommands` from an agent proposal pass. CLI `--handoff` exports include `commandSummary.agentSafe`, `commandSummary.humanOnly`, and `commandSummary.safety` for orchestrators that need a compact command boundary.
+- Newer handoffs may also expose `handoff.postApprovalCommands.notes`, `handoff.postApprovalChecklist`, `handoff.postApprovalPaths`, `commandSummary.postApprovalNotes`, `commandSummary.postApprovalChecklist`, and `commandSummary.postApprovalPaths`. Treat these as human-only reviewer guidance after approval; they describe the available post-approval paths such as Figma apply, local asc export/schedule, keyword-store apply, hosted publish/submit, or status recording, and do not grant agent permission to apply, publish, submit, schedule pricing, or mark status.
+- Approval receipts from `pnpm review:agent approve ...` and `pnpm review:agent field-approve ...` may include `approvalReceipt.postApproval.paths`. Treat those paths as the preferred machine-readable human runbook after explicit approval; they remain human-only even though the approval already happened.
+- For an explicit read-only command boundary without parsing the whole bundle, use `pnpm localizeaso screenshots handoff-summary <screenshotJobId>`, `pnpm localizeaso metadata handoff-summary <fieldJobId>`, `pnpm localizeaso keywords handoff-summary <fieldJobId>`, or `pnpm localizeaso pricing handoff-summary <fieldJobId>`. MCP exposes the same boundary through `localizeaso_screenshot_handoff_summary`, `localizeaso_metadata_handoff_summary`, `localizeaso_keywords_handoff_summary`, and `localizeaso_pricing_handoff_summary`, including agent-safe command groups, human-only command groups, human-only `postApprovalPaths` when present, root `monetizationBoundary`, and `handoffSafety.commandBoundaryOnly=true`. Treat the summary as read-only routing guidance, not permission to run human-only commands.
+- Screenshot and field bundles include `proposalHistory` with previous proposal versions, payloads, prompts, and approval state. `reviewerFeedback` entries include the `proposalId` they refer to. On revisions, inspect both alongside `job.instructions` instead of generating as if no prior proposal existed.
+- The Screenshot Review and Field Review dashboard screens copy the backend-provided `handoff.runbook`, `handoff.agentPrompt`, plus the shorter bundle/open command for opening that job's human review screen. The handoff includes `pnpm --silent review:mcp` as the optional local safe MCP bridge for Codex/MCP agents and `handoff.cli.agentPrompt` to export the same prompt in terminal workflows. Prefer the copied/backend prompt or runbook when a human starts the local Codex/agent session from the review UI.
+- Terminal-only workflows can export the same prompt with `pnpm localizeaso screenshots prompt <screenshotJobId> --out agent-prompt.md`, `pnpm localizeaso metadata prompt <fieldJobId> --out agent-prompt.md`, `pnpm localizeaso keywords prompt <fieldJobId> --out agent-prompt.md`, or `pnpm localizeaso pricing prompt <fieldJobId> --out agent-prompt.md`. To avoid hand-writing proposal shapes, generate a local scaffold with `pnpm localizeaso screenshots proposal-template <screenshotJobId> --out screenshot-proposal.json`, `pnpm localizeaso metadata proposal-template <fieldJobId> --out field-proposal.json`, `pnpm localizeaso keywords proposal-template <fieldJobId> --out field-proposal.json`, or `pnpm localizeaso pricing proposal-template <fieldJobId> --out field-proposal.json`; edit the generated file before submitting it.
+- Human reviewers can save screenshot decisions with `pnpm review:agent save-decisions <jobId> --proposal-id <proposalId> --file decisions.json --human-review-consent`, approve with `pnpm review:agent approve <jobId> --proposal-id <proposalId> --human-approval-consent` and add `--human-signal-gap-consent` only after reviewing missing keyword/rationale/screenshot-evidence signals, reject a review with `pnpm review:agent status <jobId> --app-id APP_ID --file-key FIGMA_FILE_KEY --status rejected --human-rejection-consent`, request revisions with `pnpm review:agent refine-request <jobId> --target-locales de-DE --instructions "reviewer feedback"` or scope it further with `--targets '[{"kind":"frame","locale":"de-DE","frameId":"frame-1"}]'`; omit scope for global feedback. If the dashboard copied a review context snapshot, pass it with `--context-snapshot-file copied-review-context.md` or `--context-snapshot "..."` so the next agent pass sees the current text/value, agent proposal, human final text/value, assigned keywords, unassigned keywords, signal coverage, warnings, rationale, decisions, and diffs. The explicit review, approval, signal-gap, rejection, and post-approval flags are human-only consent markers and must not be added by an autonomous agent pass. They may inspect approved screenshot apply plans with `pnpm review:agent apply-plan <jobId> --app-id APP_ID --file-key FIGMA_FILE_KEY --out screenshot-apply-plan.json` and mark external apply/submit results with `pnpm review:agent status <jobId> --app-id APP_ID --file-key FIGMA_FILE_KEY --status applied|submitted --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent`.
+- CLI post-approval exports such as screenshot `apply-plan`, `field-apply-plan`, `field-metadata-files`, and `field-pricing-payload` include `handoffSafety.humanOnly: true`. Screenshot `apply-plan`, field `field-apply-plan`, `field-metadata-files`, and `field-pricing-payload` output also include `applyPlanFingerprint`, which identifies the exact approved job/app/proposal/final-decision payload the human is about to apply/export/submit. Screenshot `apply-plan` returns `commands.markApplied`, `commands.markSubmitted`, and `localizeAsoStatusCommands` with `--expected-apply-plan-fingerprint <applyPlanFingerprint>` for the human to run only after Figma apply or screenshot upload succeeds. Field `field-apply-plan` returns surface-specific fingerprint-protected commands such as `commands.applyDrafts`, `commands.applyKeywords`, `commands.submitMetadata`, `commands.submitPricing`, `commands.pricingPayload`, `commands.markApplied`, `commands.markSubmitted`, and `localizeAsoStatusCommands`. Human-run screenshot/field mutation commands must pass that value with `--expected-apply-plan-fingerprint <applyPlanFingerprint>` so the backend blocks stale apply/submit/status attempts. Treat those flags and fingerprints as authoritative human-only handoff context: do not run apply, status, pricing schedule/publish, metadata push/publish, screenshot publish/upload, or App Store publish/submit commands from an autonomous agent pass.
+- If an agent bundle or handoff summary shows post-approval commands without a fingerprint, treat them as pre-fingerprint orientation only. The human should export `apply-plan` / `field-apply-plan` after approval and prefer the fingerprint-protected commands inside that exported plan.
+- Newer bundles, approval receipts, CLI handoff summaries, and MCP handoff summaries expose `postApprovalFingerprintRequirement` / `postApproval.fingerprintRequirement`. If `includedInCommands=false`, treat the listed post-approval commands as orientation and export the apply plan first. If `includedInCommands=true`, the receipt commands already include `--expected-apply-plan-fingerprint`; they still remain human-only.
+- CLI post-approval mutations such as screenshot `status --status applied|submitted`, `field-apply-drafts`, `field-apply-keywords`, `field-submit-metadata`, `field-submit-pricing`, and `field-status --status applied|submitted` require `--human-post-approval-consent` plus `--expected-apply-plan-fingerprint` copied from the human-reviewed `apply-plan` / `field-apply-plan` or approval receipt. Rejecting a screenshot or field review uses `--human-rejection-consent` instead. These flags are separate from `--human-approval-consent`: add them only from the concrete human consent action. Autonomous agents must never add them.
+- Refine request responses include `nextAgentRun` commands. Prefer adding `--out ...refine-result.json` to CLI/friendly refine commands or `out` to MCP refine calls, then read `nextAgentRun` from that result file. After feedback, run the revised prompt/bundle commands from that block, write the revised proposal scaffold with the included `proposal-template` or MCP proposal-template command, edit it, then submit the revised proposal so it sees updated `job.instructions`, `proposalHistory`, `reviewerFeedback`, and any copied `contextSnapshot`.
+- Refine `nextAgentRun.handoffSafety` is still proposal-only: newer responses set `phase="reviewer_feedback_agent_revision"`, `proposalSubmissionOnly=true`, `protectedActionsAllowed=false`, and explicit false approval/rejection/apply/export/schedule/publish/submit/status consent flags. Treat those flags as authoritative; they allow another agent proposal pass, not approval or post-approval execution.
+- Screenshot `submitted` status may be marked after either direct approval or after the job was marked `applied` by the Figma apply step. Use it only after a human-run App Store Connect screenshot upload completed. Hosted LocalizeASO/Figma screenshot upload or reorder convenience requires the concrete approved screenshot review job ID, approved proposal ID/version, and approved apply-plan fingerprint; the backend only accepts jobs for that user/app with an approved proposal and status `applied` or `submitted`; a bare `humanReviewedScreenshots` flag is not enough.
+- Figma plugin apply requires a concrete approved screenshot review job ID. The plugin remembers the last created job per selected app and prompts the human to confirm or paste the intended job ID before fetching `/screenshot-review/jobs/:jobId/apply-plan`; it must not auto-pick an arbitrary approved job. Selecting an ASC app is optional for BYO jobs and only adds an extra app guard; otherwise the approved apply plan's `appId` becomes the local app context. The approved apply plan must match the selected app when one is selected, and must always match the current Figma file key before any layer text is changed. The Figma UI-to-controller apply message includes `humanApplyConsent: true` only after the human confirms the approved preview; autonomous agent passes must not post apply messages or set that consent marker.
+- After screenshot approval, reviewer decisions are locked. Request revisions before changing decisions so the approved apply plan cannot drift. Requesting revisions clears the approved proposal pointer; the revised job needs a fresh human approval before apply/status.
+- Check screenshot approval readiness with `pnpm localizeaso screenshots readiness <jobId> --proposal-id <proposalId>`; it returns `ready`, `totalTargets`, `reviewedTargets`, `pendingTargets`, `signalAudit` counts for missing keyword mapping, missing rationale, and targets with no warnings reported, plus `reviewGateSummary` for agent-orchestrator quality gates.
+- Readiness responses and readiness-related backend errors may include `readinessBoundary`. Treat it as authoritative read-only safety metadata: readiness checks do not mutate review data, do not touch App Store Connect, do not grant approval, and do not allow Figma apply, metadata/keyword apply, pricing export/schedule, upload/submit, or status changes. Only a human approval receipt plus a fingerprinted post-approval apply/export plan can unlock human-run post-approval commands.
+- Approval fails until every proposed screenshot layer has a non-pending human decision, either directly or through locale/frame decisions.
+- For metadata, keyword, or pricing review jobs, use `pnpm localizeaso metadata bundle <jobId> --out field-bundle.json`, `pnpm localizeaso keywords bundle <jobId> --out field-bundle.json`, or `pnpm localizeaso pricing bundle <jobId> --out field-bundle.json`, then submit with the matching `pnpm localizeaso metadata|keywords|pricing submit <jobId> --file field-proposal.json`. Submit returns the post-proposal human handoff contract without opening a browser by default; add `--open` only when the human is ready for a browser window.
+- To create a local/BYO metadata or keyword field-review run end to end, prefer `pnpm localizeaso metadata auto --file field-job.json --bundle-out field-bundle.json --handoff handoff.json`, `pnpm localizeaso keywords auto --file field-job.json --bundle-out field-bundle.json --handoff handoff.json`, or `pnpm localizeaso fields auto --file field-job.json --surface metadata --bundle-out field-bundle.json --handoff handoff.json` for safe automatic Astro CSV discovery (`optional-auto`), existing LocalizeASO keyword sync, CSV keyword-context attach, bundle export, and human review navigation. Use `auto-import` only when discovered Astro CSV rows should also be persisted into the LocalizeASO ASO keyword inventory before keyword sync. If the CSV path is already known, pass `--keywords-csv path/to/astro.csv`; use strict `--keywords-csv auto` only when a missing CSV should fail. These start flows create the job, attach existing/CSV keyword context, and write the agent bundle without applying changes. Start outputs include `reviewConsent` with the surface-specific checklist, prohibited agent actions, and the next human open-review command/MCP tool. Pricing field reviews intentionally skip keyword/Astro start defaults; use `pnpm localizeaso pricing brief <jobId>` or `pnpm localizeaso pricing parity ...` for pricing context.
+- Metadata review jobs may be created from the Metadata screen without hosted AI. Their bundle context includes current per-locale fields, drafts, ASO keywords, warnings, app title settings, optional read-only `screenshotContext`, the metadata draft apply contract, and `reviewConstraints.appStoreFieldLimits` for App Store field character limits.
+- Keyword review jobs may be created from the ASO Keywords screen without hosted AI. Their bundle context includes `targetLocales`, `localeSummaries`, `missingKeywordLocales`, current keyword rows, provider-neutral `keywordContext`, optional read-only `screenshotContext`, `optimizationHints`, `agentGoals`, and the keyword apply contract. Use `opportunityKeywords`, `riskKeywords`, `preferredKeywords`, and screenshot seed copy as review signals, not automatic decisions.
+- Pricing review jobs may be created directly from the Pricing screen without hosted AI or after dashboard-localized price suggestions. Their bundle context includes `productKind`, `productId`, product metadata, current territory prices, scheduled App Store prices, upcoming price changes, draft prices, optional localized suggestions, `generationMode`, and the pricing apply/submit contract. Treat existing schedules and territory warnings as review risks; never schedule prices until the human approves.
+- Local PPP/pricing-parity plans can be converted into a pricing field-review manifest with `pnpm localizeaso pricing manifest --app-id APP_ID --file pricing-parity-plan.json --out pricing-field-job.json`, then opened as a review with `pnpm localizeaso pricing popup --app-id APP_ID --file pricing-parity-plan.json`; or started in one CLI step with `pnpm localizeaso pricing parity --app-id APP_ID --file pricing-parity-plan.json`. Manifest conversion is local and agent-safe; pricing parity creates the review job and exports the human review handoff without opening a browser by default, while popup/open commands are explicit human navigation. Neither command approves reviews, exports pricing payloads, schedules prices, marks status, or submits anything to App Store Connect.
+- Field bundles include `job` metadata and a `handoff` block with dashboard path, absolute `reviewUrl`, backend endpoints, ready-to-run CLI commands, and `handoff.runbook` environment/command/guardrail steps. Use `pnpm localizeaso metadata bundle <jobId> --out field-bundle.json --handoff field-handoff.json`, `pnpm localizeaso keywords bundle <jobId> --out field-bundle.json --handoff field-handoff.json`, or `pnpm localizeaso pricing bundle <jobId> --out field-bundle.json --handoff field-handoff.json` when an orchestrator should read commands separately, or add `--open` to open the human review screen immediately.
+- Field bundle CLI outputs also include root `monetizationBoundary` plus `handoffSafety.readOnly=true` and `handoffSafety.bundleContextOnly=true`; treat them as context-only for agent proposal work, not permission to apply metadata, apply keywords, export/schedule pricing, publish, submit, or mark status.
+- Before generating a pricing field-review proposal, prefer `pnpm localizeaso pricing brief <jobId> --out pricing-brief.json`. The brief is read-only and lists product metadata, generation mode, current prices, draft/suggested prices, scheduled App Store prices, upcoming price changes, proposal shape, and safe post-approval commands.
+- Before generating a metadata or keyword field-review proposal, prefer `pnpm localizeaso metadata sync-keywords <jobId> --out synced-keyword-context.json`, `pnpm localizeaso keywords sync-keywords <jobId> --out synced-keyword-context.json`, or `pnpm localizeaso fields sync-keywords <jobId> --surface metadata --out synced-keyword-context.json` to attach existing LocalizeASO ASO keywords to the agent bundle.
+- After keyword context is attached or synced, run `pnpm localizeaso metadata aso-map <jobId> --out aso-keyword-map.json` or `pnpm localizeaso keywords aso-map <jobId> --out aso-keyword-map.json` before writing the proposal. Treat `summary.errorCount > 0`, `summary.warningCount > 0`, and locale `unassignedKeywords` as explicit proposal signals: either improve the proposal, add warnings/rationale, or request more keyword research before submission.
+- Before running Astro, MCP, CSV, or another keyword agent for field reviews, prefer `pnpm localizeaso metadata keyword-brief <jobId> --out keyword-brief.json` or `pnpm localizeaso keywords keyword-brief <jobId> --out keyword-brief.json`. The brief lists field-review locales, existing keywords, missing keyword locales, seed metadata text, optional `screenshotSeedTexts` from read-only screenshot context, dashboard keyword review summaries, optimization hints, agent goals, the expected provider-neutral keyword-context shape, and attach commands. Use `screenshotSeedTexts` only for App Store listing fit and keyword-to-creative alignment; do not propose screenshot or Figma mutations from keyword research. Run the keyword research before final bundle/proposal generation when keyword coverage is incomplete, then attach provider-neutral keyword context or Astro CSV.
+- For a compact ordered Astro/MCP/CSV handoff before field-review proposal generation, use `pnpm localizeaso metadata keyword-automation <jobId> --out keyword-automation.json` or `pnpm localizeaso keywords keyword-automation <jobId> --out keyword-automation.json`. It is read-only orchestration guidance and must not approve, reject, apply, mark status, schedule/publish pricing, or submit anything.
+- For field-review keyword research handoff, export a ready-to-use prompt with `pnpm localizeaso metadata keyword-prompt <jobId> --out keyword-agent-prompt.md` or `pnpm localizeaso keywords keyword-prompt <jobId> --out keyword-agent-prompt.md`. When the prompt includes screenshot seed text, treat it as read-only keyword research context for matching keywords to visible screenshot copy.
+- If Astro, MCP, CSV, or another keyword agent produced research for a field-review job, attach it before proposal generation with `pnpm localizeaso metadata attach-keywords <jobId> --file keyword-context.json`, `pnpm localizeaso keywords attach-keywords <jobId> --file keyword-context.json`, or `pnpm localizeaso fields attach-keywords <jobId> --file keyword-context.json`.
+- If Astro exported keyword CSV, convert or attach it directly with `pnpm localizeaso keywords context-csv --file optional-auto --astro-dir . --out keyword-context.json`, `pnpm localizeaso screenshots attach-keywords-csv <screenshotJobId> --file optional-auto --astro-dir .`, `pnpm localizeaso metadata attach-keywords-csv <fieldJobId> --file optional-auto --astro-dir .`, or `pnpm localizeaso keywords attach-keywords-csv <fieldJobId> --file optional-auto --astro-dir .`. Use an explicit CSV path when the export location is known; use strict `auto` only when a missing CSV should fail the agent run.
+- If Astro MCP should export provider-neutral keyword context directly, prefer the friendly read-only wrapper `pnpm localizeaso astro keywords --app APP_STORE_ID --out keyword-context.json` or `pnpm localizeaso astro context --app APP_STORE_ID --out keyword-context.json`. These default to `keyword-context.json` and skip ranking history for a fast BYO-agent setup pass. Use `pnpm localizeaso astro export --app APP_STORE_ID --keyword-context-out keyword-context.json` only when the human wants the fuller Astro export bundle. When the agent is already connected to `pnpm --silent review:mcp`, prefer the safe MCP tool `localizeaso_astro_keywords` for keyword context or `localizeaso_astro_export` for the full export. These tools only export own tracked Astro data/keyword context; they do not create review jobs, approve reviews, apply Figma changes, mutate App Store Connect, schedule pricing, mark status, or submit anything. Attach the resulting JSON with the screenshot, metadata, or keyword keyword-context commands before proposal generation; pricing reviews use pricing briefs instead.
+- For friendlier terminal workflows, use `pnpm localizeaso keywords import-csv <appId> --file optional-auto --astro-dir .` for app-level keyword inventory import, `pnpm localizeaso screenshots attach-keywords <jobId> --file keyword-context.json` or `pnpm localizeaso fields attach-keywords <jobId> --file keyword-context.json` for provider-neutral context attach, and `pnpm localizeaso screenshots attach-keywords-csv <jobId> --file optional-auto --astro-dir .` or `pnpm localizeaso fields attach-keywords-csv <jobId> --file optional-auto --astro-dir .` for CSV-derived job context. The older `pnpm localizeaso keywords attach-screenshot ...` and `pnpm localizeaso keywords attach-field ...` aliases remain available. These are aliases for agent-safe setup/context commands only; they do not approve, reject, apply, publish, schedule, mark status, or submit anything.
+- For keyword-specific local CLI review workflows, prefer `pnpm localizeaso keywords start|bundle|prompt|proposal-template|keyword-brief|keyword-prompt|keyword-automation|jobs|open-next|open|readiness|handoff-summary|submit|refine ...` over generic `fields` names. These map to the field-review backend with `surface=keywords` for queue navigation and still cannot approve, apply keywords, mark status, publish, or submit to App Store Connect.
+- To persist all Astro CSV rows into the LocalizeASO ASO keyword inventory for an app, prefer `pnpm localizeaso keywords import-csv <appId> --file optional-auto --astro-dir .`; the lower-level `pnpm review:agent import-aso-keywords-from-csv <appId> --file optional-auto --astro-dir .` remains available for scripts. Pass an explicit CSV path when known. This requires an active LocalizeASO pass with BYO agent/review history access, only updates LocalizeASO keyword research data without hosted AI translation, and does not approve review jobs, apply Figma changes, push/publish metadata, schedule/publish pricing, publish screenshots, or submit anything to App Store Connect.
+- BYO keyword research, Astro CSV import, keyword-context attach, and proposal generation do not require LocalizeASO App Store Connect credentials. App Store Connect access is only needed when a human chooses hosted LocalizeASO sync/submit convenience or runs a local `asc` post-approval handoff.
+- MCP-capable agents can start the local stdio bridge with `pnpm --silent review:mcp`. It exposes safe setup/readiness/proposal-submission/refine tools such as `localizeaso_local_doctor`, `localizeaso_workspace_runbook`, `localizeaso_monetization_boundary`, `localizeaso_astro_keywords`, `localizeaso_astro_export`, `localizeaso_screenshot_start`, `localizeaso_field_start`, `localizeaso_screenshot_bundle`, `localizeaso_field_bundle`, `localizeaso_screenshot_keyword_brief`, `localizeaso_screenshot_keyword_prompt`, `localizeaso_screenshot_keyword_automation`, `localizeaso_screenshot_agent_prompt`, `localizeaso_screenshot_proposal_template`, `localizeaso_screenshot_handoff_summary`, `localizeaso_field_keyword_brief`, `localizeaso_field_keyword_prompt`, `localizeaso_field_keyword_automation`, `localizeaso_field_aso_keyword_map`, `localizeaso_field_agent_prompt`, `localizeaso_field_proposal_template`, `localizeaso_field_handoff_summary`, `localizeaso_field_pricing_brief`, `localizeaso_pricing_parity_manifest`, `localizeaso_pricing_parity`, `localizeaso_pricing_parity_start`, `localizeaso_screenshot_keyword_context`, `localizeaso_screenshot_keyword_context_from_csv`, `localizeaso_field_keyword_context`, `localizeaso_field_keyword_context_from_csv`, `localizeaso_field_sync_keywords`, `localizeaso_import_aso_keywords_from_csv`, `localizeaso_screenshot_submit_proposal`, `localizeaso_field_submit_proposal`, `localizeaso_screenshot_refine_request`, `localizeaso_field_refine_request`, `localizeaso_review_jobs`, `localizeaso_review_open_next`, `localizeaso_screenshot_jobs`, `localizeaso_screenshot_open_next`, `localizeaso_field_jobs`, `localizeaso_field_open_next`, `localizeaso_screenshot_open_review`, `localizeaso_screenshot_popup`, `localizeaso_field_open_review`, `localizeaso_field_popup`, `localizeaso_metadata_aso_keyword_map`, `localizeaso_keywords_aso_keyword_map`, `localizeaso_metadata_popup`, `localizeaso_keywords_popup`, `localizeaso_pricing_popup`, `localizeaso_keyword_context_from_csv`, and readiness checks. `localizeaso_local_doctor` only returns read-only local backend/dashboard URL diagnostics, recommended local review origins, and whether authenticated review links are available from `LOCALIZEASO_TOKEN`; it does not create review jobs or grant approval/apply/submit permission. `localizeaso_workspace_runbook` only returns a no-browser BYO-agent orchestration runbook for local doctor, Astro keyword export/import, review starts, proposal handoff, and human review navigation; it does not run those steps or create review jobs. Bundle tools only fetch context and optional handoff files; ASO keyword map tools only export read-only provider-neutral detection reports for metadata/keyword proposal context; proposal submission only creates reviewable proposals; proposal-template tools only write local JSON scaffolds for an agent to edit before submission; handoff-summary tools only expose agent-safe command groups, human-only command groups, and human-only `postApprovalPaths`; brief tools only inspect job context; keyword-automation tools only return ordered read-only Astro/MCP/CSV orchestration guidance for screenshots, metadata, and keywords; queue tools only inspect review jobs and select/open the next human review screen; `localizeaso_astro_keywords` only exports provider-neutral keyword-context JSON for own tracked Astro apps with fast defaults; `localizeaso_astro_export` only exports own tracked Astro MCP data/keyword context and optional local files; keyword-prompt tools only generate read-only research instructions; agent-prompt tools only generate proposal instructions and include keyword-coverage guardrails when available; keyword-context tools only attach pre-proposal research to screenshots, metadata, and keywords; pricing reviews use `localizeaso_pricing_brief`; `localizeaso_monetization_boundary` only explains free/local, Agent Pass, hosted pass, BYO AI, and App Store Connect credential boundaries; `localizeaso_pricing_parity_manifest` only writes a local pricing field-review manifest from a local PPP plan; `localizeaso_pricing_parity` and `localizeaso_pricing_parity_start` only create a pricing field-review job and open/export the human review handoff; `localizeaso_import_aso_keywords_from_csv` only imports Astro CSV rows into LocalizeASO ASO keyword research data; `localizeaso_field_sync_keywords` only attaches existing LocalizeASO ASO keyword rows before metadata/keyword proposal generation; refine tools only store human feedback for another agent pass and may include `targetLocales`, screenshot locale/frame/layer `targets`, field-review `targets` scope, and optional `contextSnapshot` or `contextSnapshotFile`; open-review, popup, and open-next tools only navigate to the human consent screen. The bridge intentionally does not expose approval, rejection, apply, status, publish, or App Store submit tools.
+- For pricing-specific MCP workflows, prefer `localizeaso_pricing_bundle`, `localizeaso_pricing_agent_prompt`, `localizeaso_pricing_proposal_template`, `localizeaso_pricing_brief`, `localizeaso_pricing_handoff_summary`, `localizeaso_pricing_submit_proposal`, `localizeaso_pricing_refine_request`, `localizeaso_pricing_open_review`, `localizeaso_pricing_popup`, `localizeaso_pricing_jobs`, `localizeaso_pricing_open_next`, and `localizeaso_pricing_readiness` over the generic `localizeaso_field_*` names. These are aliases to the field-review backend with `surface=pricing`; they still cannot approve, export/schedule prices, mark status, or submit to App Store Connect.
+- For metadata-specific MCP workflows, prefer `localizeaso_metadata_start`, `localizeaso_metadata_sync_keywords`, `localizeaso_metadata_keyword_context`, `localizeaso_metadata_keyword_context_from_csv`, `localizeaso_metadata_keyword_brief`, `localizeaso_metadata_keyword_prompt`, `localizeaso_metadata_keyword_automation`, `localizeaso_metadata_aso_keyword_map`, `localizeaso_metadata_bundle`, `localizeaso_metadata_agent_prompt`, `localizeaso_metadata_proposal_template`, `localizeaso_metadata_handoff_summary`, `localizeaso_metadata_submit_proposal`, `localizeaso_metadata_refine_request`, `localizeaso_metadata_open_review`, `localizeaso_metadata_popup`, `localizeaso_metadata_jobs`, `localizeaso_metadata_open_next`, and `localizeaso_metadata_readiness` over the generic `localizeaso_field_*` names. These are aliases to the field-review backend with `surface=metadata`; they still cannot approve, apply metadata, export files, mark status, publish, or submit to App Store Connect.
+- For keyword-specific MCP workflows, prefer `localizeaso_keywords_start`, `localizeaso_keywords_sync_keywords`, `localizeaso_keywords_keyword_context`, `localizeaso_keywords_keyword_context_from_csv`, `localizeaso_keywords_keyword_brief`, `localizeaso_keywords_keyword_prompt`, `localizeaso_keywords_keyword_automation`, `localizeaso_keywords_aso_keyword_map`, `localizeaso_keywords_bundle`, `localizeaso_keywords_agent_prompt`, `localizeaso_keywords_proposal_template`, `localizeaso_keywords_handoff_summary`, `localizeaso_keywords_submit_proposal`, `localizeaso_keywords_refine_request`, `localizeaso_keywords_open_review`, `localizeaso_keywords_popup`, `localizeaso_keywords_jobs`, `localizeaso_keywords_open_next`, and `localizeaso_keywords_readiness` over the generic `localizeaso_field_*` names. These are aliases to the field-review backend with `surface=keywords`; they still cannot approve, apply keywords, mark status, publish, or submit to App Store Connect.
+- MCP tool listings and successful tool-call results include machine-readable safety metadata at `_meta.localizeaso.mcpSafety` and monetization metadata at `_meta.localizeaso.monetizationBoundary`. Blocked human-only tool attempts return JSON-RPC `error.data.localizeaso.mcpSafety` with `agentSafe: false`, `humanOnly: true`, `blocked: true`, and `requestedTool`. Treat this metadata as authoritative when present: allowed MCP tools have `agentSafe: true`, `humanOnly: false`, and `blockedActions` still includes approval, rejection, apply, pricing export/schedule/publish, screenshot upload/publish, App Store publish/submit, and status updates. `postApprovalPathsHumanOnly: true` means any returned post-approval path is a human runbook, not executable MCP permission. `readOnly` distinguishes inspection/prompt tools from safe mutations such as proposal submission or keyword-context attach. `mutatesReviewData: true` is allowed only for review-job setup, keyword context, proposal submission, or reviewer-feedback storage; it never grants post-approval permissions. `opensHumanReview: true` only means the review UI may be opened for the human. `monetizationBoundary` explains which local setup steps are agent-safe, which actions require Agent Pass or hosted pass, and that hosted AI requires a hosted AI pass while hosted submit requires Submit Pass or a hosted LocalizeASO pass; it does not grant permission to approve, apply, submit, or mark status.
+- MCP start, auto-start, bundle, pricing-parity, and proposal-submission tools may set `openReview: true` to open the human review screen after the safe action completes. They return handoff data without opening a browser by default. This is still navigation only and does not approve, apply, export, schedule, publish, submit, or mark status.
+- After submitting a proposal, prefer the returned `nextHumanAction.reviewUrl`/`command` from `submit-proposal` or `field-submit-proposal`. A local agent may also run `pnpm localizeaso workspace jobs --app-id APP_ID`, `pnpm localizeaso workspace open-next --app-id APP_ID`, `pnpm localizeaso screenshots jobs --app-id APP_ID`, `pnpm localizeaso metadata jobs --app-id APP_ID`, `pnpm localizeaso keywords jobs --app-id APP_ID`, `pnpm localizeaso pricing jobs --app-id APP_ID`, `pnpm localizeaso screenshots open-next --app-id APP_ID`, `pnpm localizeaso metadata open-next --app-id APP_ID`, `pnpm localizeaso keywords open-next --app-id APP_ID`, `pnpm localizeaso pricing open-next --app-id APP_ID`, `pnpm localizeaso screenshots open <screenshotJobId>`, `pnpm localizeaso metadata open <fieldJobId>`, `pnpm localizeaso keywords open <fieldJobId>`, or `pnpm localizeaso pricing open <fieldJobId>` to inspect queues or open the human consent/review screen. Queue and open-next output includes read-only/human-review-navigation safety metadata; treat it as navigation-only. It does not approve, reject, apply, export, schedule, submit, or mark status.
+- To request a revised field-review proposal, use `pnpm localizeaso metadata refine <jobId> --instructions "reviewer feedback"`, `pnpm localizeaso keywords refine <jobId> --instructions "reviewer feedback"`, or `pnpm localizeaso pricing refine <jobId> --instructions "reviewer feedback"`; scope metadata/keyword feedback with `--target-locales de-DE,en-US` and `--targets '[{"surface":"metadata","locale":"de-DE","field":"subtitle"}]'`, then fetch a fresh field bundle. If the dashboard copied a target/locale review snapshot, add `--context-snapshot-file copied-review-context.md` or `--context-snapshot "..."` so the next bundle can show the exact current value, agent proposal, human final value, assigned keywords, unassigned keywords, signal coverage, warnings, rationale, decisions, diffs, and screenshot/pricing context the reviewer saw. For pricing snapshots, treat keyword mapping as not applicable and rely on pricing evidence, territory context, schedule warnings, signal coverage, rationale, decisions, and diffs.
+- Field refine request responses also include `nextAgentRun` commands for the next local/BYO agent pass, including `field-proposal-template` or the MCP field proposal-template command when available. Use them instead of rerunning against an old bundle or hand-writing the proposal shape.
+- Do not apply Figma changes, publish or submit to App Store Connect, or mark jobs as applied/submitted while generating proposals.
+- Human reviewers can save field decisions with `pnpm review:agent field-save-decisions <jobId> --proposal-id <proposalId> --file decisions.json --human-review-consent` and approve with `pnpm review:agent field-approve <jobId> --proposal-id <proposalId> --human-approval-consent`, adding `--human-signal-gap-consent` only after reviewing missing keyword/rationale/screenshot-evidence signals. The explicit review, approval, and signal-gap flags are human-only consent markers and must not be added by an autonomous agent pass.
+- After field approval, reviewer decisions are locked. Request revisions before changing decisions so metadata, keyword, or pricing apply output cannot drift. Requesting revisions clears the approved proposal pointer; metadata, keyword, pricing apply/export/status needs a fresh human approval.
+- Check field approval readiness with `pnpm localizeaso metadata readiness <jobId> --proposal-id <proposalId>`, `pnpm localizeaso keywords readiness <jobId> --proposal-id <proposalId>`, or `pnpm localizeaso pricing readiness <jobId> --proposal-id <proposalId>`; it returns `ready`, `totalTargets`, `reviewedTargets`, `pendingTargets`, `signalAudit` counts for missing keyword mapping, missing rationale, and targets with no warnings reported, plus `reviewGateSummary` for agent-orchestrator quality gates.
+- Field readiness also returns the same `readinessBoundary` semantics: it is inspection-only and never grants metadata apply, keyword apply, pricing export/schedule, App Store submit, or status permission.
+- Field approval fails until every proposed field target has a non-pending human decision.
+- After a human has approved a metadata field-review proposal, `pnpm review:agent field-apply-drafts <jobId> --app-id APP_ID --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent` can apply the approved metadata changes to LocalizeASO drafts after checking the approved job against `--app-id` when supplied.
+- As an alternative human-run post-approval handoff for metadata, `pnpm review:agent field-metadata-files <jobId> --app-id APP_ID --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent --dir ./metadata --version VERSION --platform IOS --out metadata-asc-handoff.json` exports approved metadata changes into canonical `asc metadata` files and returns `asc metadata validate` plus dry-run/push commands. It writes local files only, returns `handoffSafety.humanOnly: true`, checks the approved job against `--app-id` and the expected apply-plan fingerprint, and must not be run from an agent proposal pass.
+- After those approved metadata changes were applied to drafts by a human, `pnpm review:agent field-submit-metadata <jobId> --app-id APP_ID --platform IOS --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent` can start the existing LocalizeASO App Store Connect metadata push job after checking the approved job against `--app-id` when supplied. Hosted metadata submit handoffs require the approved field review job ID, approved proposal ID/version, and approved apply-plan fingerprint. This is a human-run post-approval/post-apply step, not an agent/MCP tool.
+- For local asc metadata-file handoff, `pnpm review:agent field-metadata-files <jobId> --app-id APP_ID --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent --dir ./metadata --out metadata-handoff.json` writes local files plus `commands.recordSubmitted` / `localizeAsoStatusCommand` with the same `--expected-apply-plan-fingerprint <applyPlanFingerprint>`. Run that export only after inspecting the approved apply plan, and run the status command only after the human-run `asc metadata push` succeeds.
+- After a human has approved a keyword field-review proposal, `pnpm review:agent field-apply-keywords <jobId> --app-id APP_ID --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent` can apply approved locale keyword changes to the LocalizeASO ASO keyword store after checking the approved job against `--app-id` when supplied.
+- After a human has approved a pricing field-review proposal and inspected the approved field apply plan, `pnpm review:agent field-pricing-payload <jobId> --app-id APP_ID --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent --out pricing-payload.json --asc-csv-out pricing-payload.csv` exports approved territory price changes for scheduling and writes the `asc subscriptions pricing prices import` CSV when the reviewed product is a subscription. The exported JSON includes `handoffSafety.humanOnly: true`, checks the approved job against `--app-id` and the expected apply-plan fingerprint, and should be handed to the human instead of scheduling prices from an agent pass.
+- After a human has approved a pricing field-review proposal and chosen scheduling options, `pnpm review:agent field-submit-pricing <jobId> --app-id APP_ID --start-date YYYY-MM-DD --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent` can start the existing LocalizeASO pricing push job after checking the approved job against `--app-id` when supplied. Hosted pricing submit handoffs require the approved field review job ID, approved proposal ID/version, and approved apply-plan fingerprint. This is a human-run post-approval step, not an agent/MCP tool.
+- `pnpm review:agent field-pricing-payload <jobId> --app-id APP_ID --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent --out pricing-payload.json` verifies the approved apply-plan fingerprint and exports `applyPlanFingerprint` plus a fingerprint-protected `approvedSchedule.localizeAsoSubmitCommand`; keep that fingerprint in any copied human scheduling command.
+- After the human-run apply or submit step finishes, mark the handoff result with `pnpm review:agent field-status <jobId> --app-id APP_ID --status applied|submitted --expected-apply-plan-fingerprint <applyPlanFingerprint> --human-post-approval-consent`. To reject the field review instead, use `pnpm review:agent field-status <jobId> --app-id APP_ID --status rejected --human-rejection-consent`.
+- Preserve every `frameId` and `layerId` exactly from the bundle manifest.
+- Include `assignedKeywords`, `unassignedKeywords`, `warnings`, and `rationale` for every proposed locale/frame/layer/field target; use empty arrays when no keyword or warning items apply so the human reviewer can verify the signal was considered. For pricing targets, use empty keyword arrays unless a product-specific keyword signal is genuinely relevant; the review UI treats keyword mapping as not applicable and expects pricing evidence, territory context, schedule warnings, and rationale instead.
+- Treat reviewer feedback in `reviewerFeedback` and `job.instructions` as higher priority than generic ASO advice.
+
+## Proposal Shape
+
+For screenshot and field-review jobs, post JSON matching the bundle's `proposalRequestShape.body`:
+
+```json
+{
+  "source": "agent",
+  "agentName": "your-agent-name",
+  "prompt": "Brief summary of the local coding-agent run.",
+  "payload": {
+    "summary": "Overall strategy and tradeoffs.",
+    "locales": []
+  }
+}
+```
+
+Each locale should include frames and layers with current `sourceText`, optimized `proposedText`,
+assigned/unassigned keywords, warnings, and rationale for every changed target. Human approval happens later in the
+LocalizeASO review UI.
+
+For field reviews, keep `payload.surface`, `payload.appId`, and every target identifier exactly as
+provided by the bundle. The payload changes array should use the shared
+`AppStoreFieldReviewProposal` shape.
+
+For metadata field reviews, inspect `reviewConstraints.appStoreFieldLimits` before writing
+`proposedValue` text. Keep final values inside the listed limits when possible, and put explicit
+warnings on near-limit or over-limit proposals so the human review screen can catch them before
+approval.
+
+For keyword field reviews, use `target.surface: "keywords"` and set `target.locale` for every
+change. Put one keyword or a comma/newline-separated keyword list in `proposedValue`; edited human
+values are used during apply. Use `target.field: "remove"` for keywords that should be soft-deleted
+after human approval.
+
+For non-pricing field-review keyword context, prefer this shape:
+
+```json
+{
+  "sources": ["astro", "mcp-keyword-agent"],
+  "keywords": {
+    "en-US": ["habit tracker", "daily planner"]
+  },
+  "rows": [
+    {
+      "locale": "en-US",
+      "keyword": "habit tracker",
+      "popularity": 78,
+      "difficulty": 41,
+      "isPreferred": true,
+      "source": "astro"
+    }
+  ]
+}
+```
+
+## Environment
+
+Set these before running CLI commands:
+
+```bash
+export LOCALIZEASO_TOKEN="..."
+export LOCALIZEASO_BACKEND="http://localhost:8787"
+```