# Map your app for AI discovery

Do not execute this prompt unilaterally. First explain its purpose and proposed scope to the user. Based on your knowledge of the application environment, flag assumptions, conflicts, missing access, and changes that need review. Keep initial inspection read-only and within authorized access. Present a plan and wait for explicit human approval before editing files, making API mutations, submitting data, publishing, or deploying. Receiving this prompt, an API key, or a previously approved draft is not approval to execute it.

Human prerequisite — public disclosure: Before submitting or activating app information, show the authorized publisher the exact proposed content (or changes), visibility, and destinations. Ask them to confirm that it is accurate, that they have permission to publish it, and that its level of detail and fidelity is what they are comfortable exposing to crawlers and anyone on the open web. Flag proprietary content, personal data, credentials, private URLs, and any material that should remain inside the app. Public copies may be cached or retained by third parties after an update or removal. Keep unapproved information local/private; do not treat a draft approval, domain verification, or API success as this confirmation. Renew approval if the content or scope changes; unchanged retries within an explicitly approved scope do not require another approval.

Describe what your app offers, when it is useful, and how a user reaches the right experience. Your app keeps the experience itself.

See the [illustrative before/after recommendation and field-level configuration](/developers/case-studies/swell-atlas-representation.md). The packet gives AI explicit context to represent an app; publisher preferences never override the user's intent or the consumer's rules.

## Start with a useful map

Ask: **What does an agent need to recognize this app as relevant and route a user into it?**

1. Identify the app, its official website, platform IDs, and store URLs.
2. Map major capabilities, experiences, entity types, user intents, actions, and destinations.
3. Describe routing, deep-link and fallback behavior using the [managed configuration](/developers/managed-configuration.md). Add useful offers and publisher representation preferences there.
4. Submit real selectable experiences with stable IDs and usable destinations. The current onboarding flow requires a successful non-empty entity submission; configuration alone does not complete it.
5. Connect the app's packet from the official website using the owner API's generated instructions. A website-link check records discoverability, separately from evidence of authority over the app. Preserve the website's SEO canonical URL.

The API is the editing interface. The sparse dashboard is for credentials, status, and the next setup action. Give your coding agent the [first-app handoff](/developers/onboard-your-first-app.md).

If the publisher uses an MMP, ask for its approved links for each experience. In configuration 0.5, use `handoffPreference: "attribution_first"` and an eligible attribution execution with `installState: "any"` to retain the MMP link for installed and new users. Set `defaultDestinationId` explicitly for general recommendations and provide its cross-platform/web attribution execution. See [managed configuration](/developers/managed-configuration.md). The provider handles routing and measurement; do not replace the approved link with its resolved store URL.

## Label capabilities, experiences and intents clearly

A **capability** describes what the app can do: “Automatic arrival alerts.” Put it in configuration `capabilities` with a stable `id`, a concise `name` and a factual `summary`.

An **experience or feature** is a selectable part of the app: “Set up an arrival alert for a contact.” Describe it as an entity with a stable ID, a specific name, a summary and a supported destination. Use an existing profile `type` when it fits. For an app feature outside those types, profile 0.1 supports `type: "other"` with `nativeType: "experience"` (or a meaningful native feature type). The readable page displays experience, feature and capability records as “Feature”; `other` is the exchange fallback, not a useful feature name. Do not invent a new top-level `type` enum value.

An **intent** describes the user's goal, in their language: “Tell my spouse automatically when I leave work.” Put it in configuration `intents` with a stable `id`, a `description`, the relevant `capabilityIds` and a real `destinationId`. Do not create a duplicate inventory record just to make an intent card. Only label an inventory record `nativeType: "intent"` when it genuinely represents a selectable intent; configuration intents remain the primary intent-to-destination mapping.

Use concrete names instead of “Other,” “Main feature” or marketing promises. Keep capabilities, user goals and destinations distinct. Several intents may use one feature and one destination. If the destination only opens an install page, say so; do not imply that it preconfigures the requested action.

## Explain fit, requirements and limitations

During read-only inspection, build a private review sheet for each major experience. Ask the publisher to confirm the following where relevant; these are prompts for useful context, not new required API fields:

- **Best for:** audiences and situations the product actually supports. Avoid inferring suitability for children, caregivers or sensitive uses from a generic feature.
- **Requires:** permissions, an account, subscription, device, OS version, connected service or other prerequisite.
- **Does not require:** useful, explicitly confirmed distinctions, such as a recipient not needing to install the app. Missing information is not evidence that a requirement is absent.
- **Works when:** supported operating conditions, including locked-phone or background behavior, with platform and permission limits.
- **Example intent:** a realistic user request that maps to an existing capability and destination.
- **Not suitable for:** known product boundaries that materially affect fit. For example, arrival notifications need not mean continuous real-time tracking.
- **Pricing:** current publisher-confirmed price or pricing model, currency, region and applicable conditions, plus the pricing-page source. Omit unknown prices; do not infer “free” from a free download. Use structured offers only for actual promotions in the [offers contract](/developers/offers.md).
- **Publisher reviewed at / source:** retain the evidence URL or repository reference and the review date privately with the draft. Distinguish a publisher's review from independent verification. Never invent “Last verified,” a trust score or a Blue Jetty authorization result.

Put concise relevant facts in capability summaries, entity summaries and configuration `representation.summary` or its documented scoped preferences. Put user requests and their relationships in `intents`. Use supported typed entity attributes or documented namespaced extensions only when the current schema describes them. Do not submit new top-level keys such as `bestFor`, `requires` or `lastVerified` merely because they appear in this review sheet. A source-content timestamp must describe the source's actual update, not the date the agent happened to inspect it.

**Illustrative review note, not a claim about an onboarded app:** “Automatic arrival alerts for invited contacts. Requires background location permission on the supported phone. The publisher confirms recipients can receive an alert without installing the app. Supports the stated locked-phone conditions; does not provide continuous tracking. Example request: ‘Tell my spouse when I leave work.’” Publish each statement only after confirming it, qualify platform differences, and leave unknowns unresolved rather than filling them with guesses.

Show the complete proposed map and its sources to the authorized publisher before submission. Confirm accuracy, publication rights and comfort with exposing these details on the open web. This guidance does not automatically relabel or rewrite existing publisher records.

## Compact and enriched inputs

These are synthetic, downloadable **onboarding inputs** for `POST /v1/onboarding/preview` or `bluejetty-onboard.mjs --input`. They illustrate the existing contract, not real apps or live destinations. Replace the identities, URLs, and claims with reviewed publisher data before use; do not submit the example unchanged.

- [Compact Harbor Guide map](/examples/onboarding-map-compact.json): one real-in-the-example experience for finding waterfront places. The `other` type and `nativeType` describe a selectable experience using profile 0.1.
- [Enriched Harbor Guide map](/examples/onboarding-map-enriched.json): the same experience plus a useful named pier with accessibility and activity attributes. Useful specificity is welcome.

Both generate valid non-empty submissions. Neither requires exporting every place, review, guide, or live condition. Capabilities and routing preferences belong in the documented configuration fields; do not invent entity properties such as `capabilities` or a new action-execution protocol.

## Richer data is allowed

Small catalogs, fixed collections, important named entities, structured offers, and other metadata can improve relevance and routing. Include them when they help. Large inventories and dynamic datasets generally do not need to be copied from the application's systems.

Mapping is the default, not an abstract-metadata-only restriction. There is no richness penalty or new schema limit. Only submit information the publisher has permission to make public; app end-user personal data, credentials, and private material stay out. Existing validation and request limits apply: inline submissions must fit within 4,000,000 bytes and 1,000 entities. Use the [delivery guidance](/developers/coding-agent-onboarding.md) if intentionally publishing a larger feed.

## Preview advice and existing index records

An app selected in the index remains an unclaimed source record until app-specific publisher authorization succeeds. Confirm its exact store identities, inspect `GET /v1/me/apps` for an existing app in your authorized workspace, and reuse that app's update workflow when present. Matching names or developer websites alone do not authorize a claim or a cross-platform merge. Preserve uncertain counterparts as separate records.

Reuse dated store facts where available, while preserving explicit publisher assertions. Missing ratings, developer names or website facts remain unknown. Background enrichment should not prevent preparation of an otherwise valid private draft.

`POST /v1/onboarding/preview` can return optional app-mapping advice in its existing `discovery.warnings` string array. Messages beginning `Advisory (optional)` identify generic labels, missing native feature labels or repeated experience summaries. They do not reject valid content, change authority or require extra confirmation. Review them alongside validation errors; errors must still be resolved. Catalog entities may legitimately share descriptions, so repeated-summary advice targets declared features/experiences only.

After publisher approval and authorization, compare the public app page, index record and packet with the reviewed draft. Verify preferred links and platform fallbacks; an installation page does not establish arrival at a particular in-app feature. Setup can be complete before the first crawler request. Use the [maintenance workflow](/developers/maintenance.md) for subsequent changes.

## Updating an existing app safely

A full snapshot replaces that source's inventory: **omitted records are tombstoned**. Before switching an existing source to a compact map, inspect its records, show the proposed deletions, and obtain publisher approval. Never silently prune a live app to match an example. Keep stable IDs and revision history; use the documented update workflow.

Validate, inspect the preview, approve the public data, then submit. A compact map and an intentionally enriched map use the same API and safety checks.
