Localizeaso Review Agent

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, proposa

…(truncated)