feat(mcp): Add keyword discovery and targeting audits

.agents/skills/openaso-aso/SKILL.md

@@ -21,21 +21,29 @@ Use OpenASO as the evidence layer for ASO recommendations. Do not copy generic A
 4. Keep refreshes bounded. Prefer narrow storefronts, small limits, and partial results over broad crawls.
 5. Separate verified evidence from hypotheses. Label unsupported or missing inputs instead of inventing them.
 
+## Keyword Discovery
+
+For keyword research, expansion, or high-impact opportunities, follow [references/keyword-discovery.md](references/keyword-discovery.md). Use fresh popularity to choose branches, explore distinct feature seeds and additional pages, then verify a relevant shortlist. Report coverage and the remaining frontier so a bounded search is not mistaken for exhaustive market coverage.
+
+## Metadata Targeting
+
+For title, subtitle, private keyword-field audits, drafts, or release comparisons, follow [references/metadata-targeting.md](references/metadata-targeting.md). Read owned metadata with saved App Store Connect access, compare a relevant discovery shortlist, and validate alternatives before any publishing step.
+
 ## Unsupported Or User-Provided Data
 
 OpenASO public/local evidence does not prove:
 
 - Downloads, revenue, LTV, retention, or paid campaign performance.
 - Exact App Store Connect impressions, product page views, conversion rate, or test results.
-- The current hidden App Store keyword field unless the user provides it.
+- The current hidden App Store keyword field unless authenticated metadata tools return it or the user provides it.
 - Exact competitor conversion rates or revenue.
 
 Ask for these inputs when required, or mark them as missing.
 
 ## ASO Rubrics To Apply
 
 - Title and subtitle are 30 characters each.
-- Hidden iOS keyword field is 100 characters when user-provided.
+- Hidden iOS keyword field is 100 characters when available from authenticated reads or user input.
 - Promotional text is 170 characters; description and release notes are 4000 characters.
 - Avoid repeating keyword words across title, subtitle, and keyword field.
 - Prefer comma-separated keyword-field terms without spaces.

.agents/skills/openaso-aso/references/keyword-discovery.md

@@ -0,0 +1,28 @@
+# Popularity-guided keyword discovery
+
+Find relevant, incremental keywords with measured demand. A high popularity index supports a demand hypothesis; relevance, ranking evidence and competition determine whether it is an opportunity for this app.
+
+## Establish scope
+
+Use the app overview and existing tracks to identify its actual features, target audience, tracked terms and evidence freshness. If a broad workspace read times out, continue with narrow tool calls and disclose the missing context. Keep a ledger keyed by normalized keyword/storefront/platform, plus seeds and page offsets already requested.
+
+Research one storefront at a time. Start with an app-based `suggest_keywords` call (omit `seed_keyword`) and two or three distinct feature/use-case seeds. Use `limit: 50` and `ranking_limit: 0` during expansion so the response budget goes to discovery. A default budget of eight suggestion requests per app is a useful starting point; increase it when the user requests broader coverage and new useful terms continue to appear.
+
+## Expand with evidence
+
+- `suggest_keywords` looks up fresh market popularity automatically when available. Retain `popularity.popularityScore`, its source and observation time separately from contextual `suggestionScore`. The latter can change with the seed and should be compared only within that request context.
+- Use `get_keyword_popularity` to check untracked terms, synonyms, or evidence that is missing or stale, in batches of at most 50 terms. The service uses saved official credentials and the saved web-session fallback automatically. If access fails, retain candidates and report the reason instead of repeatedly retrying authentication.
+- Prefer feature-relevant terms with market popularity above 5 as branch seeds. Keep scores of 0...5 and unknown scores in separate exploratory groups; missing data is not evidence of zero demand. Retain a low-score term when its feature coverage makes it worth testing.
+- Exclude unrelated intent, unsupported features, wrong-language phrases and competitor brands from the organic opportunity shortlist before choosing branches. A popular competitor can supply research context without becoming a metadata recommendation.
+- Re-query promising untried terms as `seed_keyword` values. Also follow `suggestionPages.nextOffset` with the same seed and limit to inspect another page. Deduplicate terms across pages and seeds while retaining every request context; flag already tracked terms using `isTracked`.
+- Count the new, relevant above-floor terms returned by each expansion. Stop after two successive expansion calls add none, when the frontier is exhausted, or at the request budget. Return untried seeds/pages when the budget stops a productive search. Treat a partial page as provider pagination evidence, not proof that every possible keyword has been found.
+
+## Verify and select
+
+Use `get_ranked_apps_for_keyword` on the strongest shortlist to inspect target rank, competing apps, search intent and ranking provenance. Native App Store results and an iTunes fallback have different evidential strength; identify the fallback when used. Popularity alone does not establish downloads, exact search volume, conversion, or an achievable rank.
+
+Prioritize by feature relevance, fresh market popularity, current rank and competitive evidence. Return a coverage summary with seeds/pages tried, unique candidates, above-floor relevant terms, new versus tracked counts, provider failures, and the remaining frontier. For each recommendation include its rationale, popularity source/time, seed context and ranking gaps. Keep low/unknown-demand hypotheses separate from the primary shortlist.
+
+When keyword additions are authorized, use `add_keywords` for the selected new terms and preserve source context with `update_keyword_notes`. Keep contextual suggestion scores out of stored market-popularity fields. Use `refresh_keyword_metrics` with its `keywords` filter to persist fresh market popularity for the chosen terms in batches of at most 50. Refresh rankings in bounded batches when needed; distinguish adding a track from refreshing it.
+
+Retire tracked keywords only when removal is authorized. Use `remove_keywords` with the exact app, platform and storefronts; review removed/skipped results. Shared query observations and market popularity survive, while track-specific history and statuses are removed. Do not prune automatically based only on floor or missing popularity.

.agents/skills/openaso-aso/references/metadata-targeting.md

@@ -0,0 +1,37 @@
+# Keyword targeting and metadata proposals
+
+Connect keyword discovery to owned metadata and measured performance. Popularity is demand evidence; feature relevance, search intent, competition, existing visibility and evidence freshness determine whether a term is worth targeting.
+
+## Read the actual baseline
+
+Use `get_app_store_metadata` with the app ID, exact App Store locale, search platform and `scope: live` or `editable`. App Store Connect credentials are separate from Apple Ads access. The tool reads title/subtitle and version-specific private keywords using saved credentials, returns version/state and a content hash, and fails instead of silently substituting another language or mixing a draft with live metadata. If authenticated access is unavailable, request the missing fields or mark the audit partial.
+
+Keep locale and storefront explicit: locale selects metadata language, storefront selects demand and rankings. Repeat research for each intended market instead of translating US keyword choices.
+
+## Audit opportunities and current targeting
+
+Run the keyword-discovery workflow first, then pass a curated shortlist to `audit_keyword_targeting`. Include promising new terms and valuable existing terms that a draft must protect. The tool defaults to at most 50 tracked terms ordered by stored popularity; this default is a bounded sample, not the complete keyword market.
+
+The audit combines fresh market popularity, app-specific metadata overlap, lexical coverage and up to eight bounded ranking samples. Its relevance score is a heuristic; review actual feature fit, search-result intent, brands, language and unsupported claims. A popular phrase with no app relevance is a review candidate rather than an automatic opportunity.
+
+For sampled keywords, inspect `competition`: its score is an OpenASO native-result heuristic with confidence, source/time and bounded competitor evidence. A missing score or fallback/insufficient-data reason means unknown competition. Compare demand and relevance with observed competitor authority and metadata saturation; do not treat a lower score as guaranteed rankability or an Apple metric. Audits calculate this evidence without persisting it.
+
+Distinguish literal phrase presence, word combinations across fields, English plural variants, and missing components. Apple advises avoiding filler such as "to" and "the" in the private keyword field. Token presence and variant combinations do not prove indexing. A well-covered term with weak rankings needs a different diagnosis from a term with missing metadata components.
+
+Use native App Store ranking evidence when available. Preserve source, observation time and sample size; iTunes fallback or an absent target in a bounded sample leaves native rank unknown. Do not turn a missing rank into a numeric position.
+
+## Produce reviewable alternatives
+
+Draft a conservative option and a broader positioning option. Preserve the app's brand, readable product promise and useful existing targets. Use `compare_metadata_draft` with proposed fields, the same keyword shortlist, and the baseline `expected_hash`.
+
+Inspect 30/30/100 character validation, duplicate/plural/filler warnings and gained/lost lexical coverage. Explain which terms each field targets and which existing terms lose prominence. Review exact phrases as well as inferred combinations; avoid unsupported claims about title/subtitle ranking weights or predicted rank lift. Return character counts, source/time, before/after fields, tradeoffs and remaining evidence gaps.
+
+These tools do not publish App Store changes. Any later apply step needs the user's authorized publishing scope and a fresh baseline check.
+
+## Record and measure a release
+
+Use `record_metadata_baseline` before a metadata release to save the live version, private fields, fixed keyword set and ranking/popularity evidence locally. Keep its ID and a release-oriented label. `list_metadata_baselines` finds prior records for an app.
+
+Use `compare_metadata_baseline` after the release to compare the same app, locale, storefront, platform and queries. It repeats only previously sampled rank queries and computes deltas only from native positions present in both observations. Note version changes, coverage gains/losses, demand changes and source failures.
+
+Optional App Store Search impression/download counts require explicit reporting periods and are labeled caller-provided. Match market and comparable periods, account for paid Apple Ads and seasonality, and keep aggregate acquisition separate from keyword attribution. The comparison is observational, not a randomized title/subtitle/keyword experiment. Schedule later measurement only when the user requests it.