/maple-onboard

name: maple-onboard
description: "Onboard a project to Maple by installing OpenTelemetry traces, logs, and metrics across every app and service in the repo. Triggers on requests like 'install Maple', 'set up Maple', 'add Maple telemetry', 'onboard this repo to Maple', 'instrument with OpenTelemetry for Maple'."

Maple onboarding

Wire OpenTelemetry traces, logs, and metrics into the user's project so telemetry streams to Maple. Cover **every app and service in the repo**, not only the one the user is currently working in.

Prefer native OpenTelemetry APIs and the framework's documented bootstrap over custom helper layers. If a specific stack stumps you, search the OTel docs for that language; don't guess.

Before editing, read the applicable companion skills:

• `maple-onboarding-style` for the cross-language rules: the business-span pattern, resource attributes, signal quality, LLM calls, smoke checks.
• `maple-nextjs-style` for Next.js / Vercel apps.
• `maple-nodejs-style` for plain Node servers (Express, Fastify, Hono, Bun).
• `maple-python-style` for Python services (FastAPI, Django, Flask).
• `maple-effect-style` for Effect-based services (Maple's first-class SDK).
• `maple-go-style`, `maple-rust-style`, `maple-java-style`, `maple-csharp-style`, `maple-kotlin-style` for those stacks.

If they are not installed next to this skill, read them from https://github.com/MapleTechLabs/maple/tree/main/skills. If none match the stack (Ruby, Elixir, PHP, plain Deno, …), use `maple-onboarding-style` and the upstream OTel docs for that language.

Step 0: Region, endpoint, and key

Maple runs two separate regions. A key only works in the region that issued it; the other region answers `401`.

| Region | Ingest endpoint | Dashboard | MCP server | | --- | --- | --- | --- | | US (default) | `https://ingest.maple.dev` | `https://app.maple.dev` | `https://api.maple.dev/mcp` | | EU | `https://ingest.eu.maple.dev` | `https://app.eu.maple.dev` | `https://api.eu.maple.dev/mcp` |

Pick the region in this order: an ingest endpoint in the prompt (use it verbatim), an EU mention or an `eu.maple.dev` URL in the prompt, otherwise US. Use that region's hosts everywhere below: `<dashboard>` and `<mcp>` mean that region's dashboard and MCP server from this table. The endpoint is not a secret and **goes inline** in the bootstrap code.

The **ingest key** is **project-scoped and write-only**. It can only send telemetry to one organization; it can't read anything or change settings. Treat it like a Sentry DSN or a PostHog public key: **inline it directly in the OTel bootstrap source** alongside the endpoint. No `.env` files, no deploy-target wiring, no `process.env.OTEL_EXPORTER_OTLP_HEADERS`. The user deploys their code and events flow.

Each organization has two ingest keys with the same permissions:

• **Public key** (`maple_pk_…`). Safe in browser and mobile bundles. Use it everywhere, servers included, so one key covers the repo.
• **Private key** (`maple_sk_…`). Server-side code only. Never put it in a browser or mobile bundle.

Three paths, no questions asked:

• **Public key in the prompt:** inline it in every bootstrap file.
• **Private key in the prompt:** inline it in server-side bootstrap files only. Put `MAPLE_TEST` in browser and mobile code, and tell the user to swap in the public key there. Mention that the public key also works on servers, so one key can cover the repo.
• **No key:** inline the literal sentinel `MAPLE_TEST`. Both regions accept it and return 200 without storing anything, so the app can boot and exercise the OTel bootstrap path while the user gets a real key. Tell the user *briefly* at the top of your work: "I'm using `MAPLE_TEST` as a placeholder so the bootstrap can run. Copy your public ingest key from Settings → Ingestion (<dashboard>/settings?tab=ingestion) and search-replace `MAPLE_TEST` in the files I write." Then keep going. Don't block install on signup.

Step 1: Map every app/service in the repo

Before instrumenting anything, enumerate what's here. Check workspace manifests (`pnpm-workspace.yaml`, root `package.json` `workspaces`, `bun` workspaces, `go.work`, Cargo workspace, Python `pyproject.toml` workspace setups, `apps/*` and `services/*` conventions). Identify each service: web frontend, API, workers, background jobs, CLIs, sample/demo apps, mobile apps, Supabase and/or server functions. Mobile and serverless/edge functions are in scope; do not skip them merely because they are client-side or short-lived. Skip pure type/config packages with no runtime entry point. Do not skip any runnable services or leave them "out of scope": instrument absolutely everything in this run; there may be no follow-up.

Print the list before you start so the user can correct it, then continue without waiting for a reply.

Step 2: For each service, install native OTel and bootstrap

**Use the language's native OpenTelemetry SDK.** Don't reach for vendor wrappers or hand-rolled helpers when an official package exists. What "native" means per stack:

• Node servers: `@opentelemetry/sdk-node`.
• Next.js / Vercel, server side: `@vercel/otel` (sdk-node breaks Next's webpack and misses the framework bootstrap).
• Browser frontends (Vite, SPA, the client side of Next.js): `@maple-dev/browser`, Maple's browser SDK. It is OTel web tracing plus error capture and session replay that share one `session.id`; raw `@opentelemetry/sdk-trace-web` gives you spans only.
• Expo / React Native: `@opentelemetry/sdk-trace-web` with an OTLP HTTP exporter.
• Python: `opentelemetry-sdk` + `opentelemetry-instrumentation-*`. Go: `go.opentelemetry.io/otel`.

No broad wrapper APIs. Avoid reusable helpers like `sendMapleSpan`, `recordCounter`, `recordLog`, `startTelemetrySpan`, or `withTelemetry`. Acquire native tracers/meters/loggers at module scope and use the SDK's own APIs directly. In TypeScript/JavaScript that means `tracer.startActiveSpan` with `try` / `catch` / `finally` (see `maple-onboarding-