---
name: build-with-mappls
description: Plan, implement, review, debug, or migrate source-grounded Mappls/MapmyIndia integrations across REST, Web, Android, iOS, React Native, Flutter, Cordova, Xamarin, Linux, Automotive, widgets, deep links, MCP, and A2A. Use for location, maps, places, routing, navigation, telematics, field operations, geospatial, vision, AI-agent, SDK selection, API code, architecture, stateful journeys, starter apps, authentication, errors, release qualification, or any request to build with Mappls/MMI.
---

# Build with Mappls

Use the canonical catalog before choosing a product, platform, credential generation, SDK, API operation, or durable journey. Preserve the difference between repository evidence, deterministic fixtures, observed live behavior, account entitlement, and production approval.

## Start with exact discovery

1. Run `node scripts/mappls-context.mjs summary` to confirm the bundled catalog revision and authority boundary.
2. Run `node scripts/mappls-context.mjs search "<user outcome and platform>" --limit 12` before proposing an integration.
3. Read only the references needed for the task:
   - Read [references/workflows.md](references/workflows.md) to choose the correct public, CLI, MCP, A2A, or downloadable path.
   - Read [references/authority.md](references/authority.md) whenever credentials, live calls, compatibility, entitlement, support, production, or source conflicts matter.
   - Read [references/stateful.md](references/stateful.md) for navigation, trips, assets, devices, geofences, tasks, contribution, inspection, offline releases, datasets, or any lifecycle-bearing workflow.
   - Read [references/ai-native.md](references/ai-native.md) for agents, copilots, RAG, MCP, A2A, tool calling, or model-visible location data.
4. If the use case, platform, and operating depth are known, run:

   `node scripts/mappls-context.mjs manifest --use-case <slug> --platform <platform> --mode <request-response|composed-experience|durable-operation>`

   Treat the returned `mappls.integration-manifest.v1` as the implementation handoff. Do not silently broaden its products, sources, operations, or authority.

## Follow the build workflow

### 1. Resolve intent

Record the user outcome, industry, runtime, current stack, geography, data class, online/offline needs, latency, scale, accessibility, and state depth. Ask only for a choice that materially changes architecture and cannot be derived from the repository.

### 2. Select evidence

Prefer, in order:

1. Exact current contract or declared SDK source.
2. Exact retained generation plus its migration record.
3. Source-declared successor.
4. Adjacent reference or sample, clearly labelled as non-authoritative.
5. A visible selection-required stop.

Use canonical links in the plan and final handoff. Never turn repository recency, sample code, a nearby SDK, or a passing fixture into a product-support claim.

### 3. Choose the narrowest integration

- Use deep links for a zero-SDK handoff.
- Use a documented widget for a prebuilt user experience.
- Use a native/web SDK for interactive maps, device integration, navigation, or platform UI.
- Use REST behind a trusted server for cross-platform business logic and protected credentials.
- Use MCP for typed agent discovery and read-only provider access.
- Use A2A when another agent must discover, delegate, poll, or retrieve a durable task.

Keep current and legacy authentication generations separate. Never ask the user to paste credentials into chat, source, generated code, query logs, or model-visible configuration. Use placeholders and describe the approved secret boundary.

### 4. Implement fixture first

Start from the exact quickstart, source launchpad, starter kit, tutorial, recipe, or maintained sample found by catalog search. Add validation, typed errors, timeouts, bounded retry, request identity, observability, data minimization, and accessible empty/failure states before live access.

For REST and live-read AI work, keep provider credentials in the trusted runtime. For browser/mobile SDKs, apply the exact domain, package/signing, bundle/team, or entitlement restrictions documented by the selected authentication path.

### 5. Model durable journeys

If any provider or application resource survives one request, use the full stateful workflow in [references/stateful.md](references/stateful.md). Persist business identity, provider identity, event time, version, idempotency, decision, and reconciliation outside the model and UI session.

### 6. Verify and qualify

Run repository tests, type checks, builds, sample journeys, hostile fixtures, and secret scans. Then separate:

- offline fixture success;
- issued non-production account conformance;
- exact entitlement/region/quota observation;
- independent security/product/operations approval;
- deployment, observation, and rollback evidence.

Do not claim the later stages from evidence of an earlier stage.

## Use AI-native surfaces deliberately

Prefer the offline MCP profile for planning. Enable live-read tools only in a separately governed trusted deployment with exact scope, purpose, identity, data controls, budget, audit, kill switch, and human boundary. The Mappls MCP and A2A surfaces expose no provider writes.

For retrieval or offline indexing, verify `/ai-context.jsonl` against `/ai-context.jsonl.sha256`; retain each record's canonical URL. Use `/llms-full.txt` when Markdown context is more appropriate.

## Produce a complete handoff

End implementation work with:

- selected use case, platform, products, state model, and operating depth;
- exact source, contract, SDK, authentication, tutorial, journey, and sample identities;
- files changed and how to run them;
- fixture and hostile-path evidence;
- unresolved selection, entitlement, compatibility, region, quota, privacy, or operational gates;
- explicit statement that repository work does not grant production approval.

Never invent an endpoint, credential placement, provider payload, lifecycle event, compatibility claim, or live result to make the handoff appear complete.

