@danieljvdm/dev-kit 1.0.1 → 2.0.0

package/skills/sentry/references/concepts/profiling.md

@@ -0,0 +1,38 @@
+# Profiling — What & Why
+
+Code-level sampling of production execution.
+Tracing tells you _which operation_ is slow; profiling tells you _which function and
+line_ inside it is burning the time.
+The output is a **flame graph**, also available as **differential** ("what got slower
+between releases") views.
+
+## What a flame graph represents
+
+A flame graph aggregates many stack samples, and its two shapes have **different
+x-axes**. In a single-profile graph X is time and **width = time spent**, so the
+bottleneck is the deepest wide frame with high **self-time** (time in the function
+itself, excluding children) — a wide frame with little self-time just means the cost is
+in a child. In an **aggregated** graph X is not time; **width = how often a frame
+appears** across samples.
+Frames are colored **application vs.
+system**: you can only act on your own code, so a wide _application_ frame is the
+target, not a wide system frame.
+A profile covers one thread at a time.
+
+## Setup essentials
+
+- **Modes:** **Continuous profiling** (backend; Python/Node today) and **UI profiling**
+  (frontend/mobile) are the current products; legacy transaction-based profiling is
+  being replaced.
+- **The dependency to get right:** in the default **`manual` lifecycle** mode, profiling
+  runs _independently_ of tracing — you start/stop it explicitly
+  (`start_profiler`/`stop_profiler`), and nothing is collected until you do.
+  Only the optional **`trace` lifecycle** mode (and legacy transaction-based profiling)
+  require tracing on and sample relative to sampled transactions.
+- **Sample, don’t profile everything** — ~1–5% CPU overhead; sampling is session-scoped.
+  Mind minimum SDK versions (support varies by platform).
+
+## Related
+
+- [`tracing.md`](tracing.md) — profiling localizes a bottleneck tracing pointed at.
+- [`reduce-volume.md`](reduce-volume.md) — sampling/overhead tradeoffs.

package/skills/sentry/references/concepts/reduce-volume.md

@@ -0,0 +1,49 @@
+# Volume & Cost — Strategy
+
+Sentry bills by the volume of each signal (errors, spans, replays, profiles), and logs
+and metrics are billed by _size_ — so attribute count and message length matter, not
+just event count. Reducing volume is keeping the data that earns its place and dropping
+the rest — for quota _and_ for signal-to-noise.
+
+## The core tradeoff, per signal
+
+- **Errors:** sample _lightly_ or not at all — usually what you can’t afford to miss.
+  The cheapest win is **filtering known noise** (browser-extension errors, bots, a
+  specific bogus exception), not blanket down-sampling.
+- **Spans / traces:** sample _aggressively_ — the highest-volume signal and biggest
+  lever. A `tracesSampler` that keeps important paths and drops health-check noise beats
+  a flat low rate. (Note `tracesSampleRate: 0` doesn’t disable tracing — see
+  [`tracing.md`](tracing.md).)
+- **Replays / profiles:** keep the asymmetric/sampled defaults (high on error, low on
+  normal).
+- **Logs / metrics:** billed by size — trim attribute count and message length, not just
+  event count, on top of emitting fewer, higher-signal events.
+
+## Where to sample — head vs. server-side
+
+- **Client / head sampling (SDK)** — decide before sending; cheapest, and the decision
+  propagates across a trace so you keep whole traces.
+  The first lever.
+- **Server-side (Sentry)** — a backstop, and for what the SDK can’t cleanly decide:
+  - **Inbound data filters** — browser-extension errors, known crawlers, legacy
+    browsers, `localhost`, specific error messages or releases, by IP. (Some are
+    Business-plan.)
+  - **Per-DSN rate limits** — cap a noisy key.
+    **Spike protection** — an automatic guard against a sudden flood.
+    **Delete & Discard** — stop ingesting a specific high-volume issue entirely.
+
+## A practical workflow
+
+1. **Find the top offenders first** (MCP / Explore across errors, spans, and logs) —
+   don’t cut blind.
+2. **Filter known noise** — high precision, no fidelity loss on real data.
+3. **Tune span sampling** with a `tracesSampler` — the biggest lever.
+4. **Set rate limits / spike protection** as a safety net.
+5. **Re-measure** to confirm you cut noise, not signal.
+
+## Related
+
+- [`tracing.md`](tracing.md) — span sampling, the main lever.
+- [`logging.md`](logging.md)
+- [`session-replay.md`](session-replay.md)
+- [`profiling.md`](profiling.md)

package/skills/sentry/references/concepts/releases.md

@@ -0,0 +1,43 @@
+# Releases — What & Why
+
+A **release** is a version of your code deployed to an environment.
+Tying every event to its exact version unlocks:
+
+- **Regression detection** — when an issue first appeared and whether it came back in a
+  later release.
+- **Crash-free rates / release health** — error-free sessions and users per release
+  (session tracking is on by default in most modern SDKs).
+- **Suspect commits** — the specific commit(s) likely responsible for an issue, surfaced
+  on the issue with a suggested assignee.
+- **Resolve-in-next-release** and **`Fixes SENTRY-XXX`** — resolve an issue and let
+  Sentry track whether it stays fixed in the version that ships the fix.
+
+## While debugging
+
+Releases let you pin the exact code that was running when an issue was produced — diff
+against that revision rather than assuming `main` matches — and **suspect commits** on
+the issue are the fastest “what changed.”
+Suspect commits need the source-control integration below; without it you still get
+release-scoped regression and health, just not the culprit commit.
+
+## Setup essentials — two ingredients
+
+1. **The `release` (and `environment`) tag on events** — set in the SDK `init` (or
+   `SENTRY_RELEASE`). Without it every event is “unknown release” and regression/health
+   features can’t work.
+2. **The release object + commits + deploy, created in CI** — via `sentry-cli` or the
+   GitHub Action. **Associating commits is what powers suspect commits**, and that
+   association needs a **source-control integration** (GitHub/GitLab) connected in
+   Sentry’s UI (an OAuth step the agent can’t do).
+   The **release name must match** between the SDK tag and the CI-created release, or
+   events won’t attribute.
+
+Use a meaningful, unique version (a commit SHA or semver), set `environment` so staging
+noise doesn’t pollute prod health, and finalize the release + record the deploy at
+deploy time.
+
+## Related
+
+- [`monitors.md`](monitors.md) — release-health / crash-rate monitors build on this.
+- [`search-query-language.md`](../search-query-language.md) — `release`, `firstRelease`,
+  `release.stage`.

package/skills/sentry/references/concepts/session-replay.md

@@ -0,0 +1,35 @@
+# Session Replay — What & Why
+
+A reconstruction of a user session around an error or UX problem.
+On **web** it’s rebuilt from DOM snapshots and events (rrweb — _not_ a screen
+recording), so it’s lightweight; on **mobile** it’s a view-hierarchy reconstruction plus
+periodic screenshots, with more aggressive default redaction.
+Replays link to the errors, traces, and rage/dead clicks in the same session.
+It’s a **frontend/mobile** signal — there’s nothing to replay on a backend.
+
+## What a replay adds over a stack trace
+
+A replay is the _user’s path_, timestamp-synced to everything else in the session — the
+clicks, navigations, network calls, and console output that led to the error, not just
+the frame where it threw.
+Two UX signals live here that never surface as exceptions: a **dead click** (a click
+that produces no response within ~7s) and a **rage click** (the repeated-click subset) —
+and these are promoted to their own **issues**, so a real UX problem can exist with no
+exception behind it.
+
+## Setup essentials
+
+- **Two sample rates, asymmetric:** keep `replaysOnErrorSampleRate` **high** (often
+  `1.0` — you want a replay for any session that errored) and `replaysSessionSampleRate`
+  **low** (a few percent — capturing every healthy session is expensive).
+- **Privacy.** Defaults **mask all text and block media** — start there; use mask/block
+  selectors to redact sensitive fields before unmasking anything globally, and treat
+  network request/response **body capture as opt-in**. Mobile redacts more aggressively
+  by default; still review sensitive screens.
+
+## Related
+
+- [`data-scrubbing.md`](data-scrubbing.md)
+- [`reduce-volume.md`](reduce-volume.md)
+- [`search-query-language.md`](../search-query-language.md) — replay properties
+  (`count_rage_clicks`, `click.*`, `count_errors`, …).

package/skills/sentry/references/concepts/tracing.md

@@ -0,0 +1,54 @@
+# Tracing & Performance — What & Why
+
+## What it is
+
+Distributed tracing reconstructs one request as it flows across frontend, backend, and
+downstream services.
+A trace is a tree of **spans** — each a timed operation (an HTTP request, a DB query, a
+function call) with a name, duration, parent, and attributes.
+The root span is the **transaction**. Tracing answers _why_ something is slow, and it’s
+the substrate Sentry uses to **automatically detect performance issues** — N+1 queries,
+slow DB calls, render-blocking assets, consecutive HTTP calls (detection requires
+tracing on).
+
+## What a trace shows
+
+A trace is a waterfall of spans nested by ancestry, and the shape _is_ the diagnosis:
+the widest span — or a gap between spans — is where the time went (a slow query, a
+blocking upstream call), which the stack trace alone can’t tell you.
+A trace is also a cross-issue view: an error inside it links to its issue, and the real
+root cause can be a _different_ issue in the same request — a frontend exception, say,
+driven by a failing span in the backend service upstream.
+Two shapes to read correctly — a dashed/orphan span means a transaction is **missing**
+(unsent, sampled out, rate-limited), usually from a low sample rate rather than a real
+gap; multiple roots usually means a custom-instrumentation trace-ID bug.
+A span also carries its profile, the bridge down to the function level.
+
+## Setup essentials
+
+- **Sampling is the main cost/signal lever** (trace volume dwarfs errors).
+  `tracesSampleRate` is a flat fraction (start 5–20% in prod); `tracesSampler` is a
+  function returning a per-transaction rate — use it to sample _down_ noise (health
+  checks) and _up_ the paths you care about.
+  **`tracesSampleRate: 0` does not disable tracing** — it keeps tracing enabled but
+  samples nothing; omit the sampling config entirely to truly disable.
+  The head-of-trace sampling decision propagates downstream, so you capture whole
+  traces, not fragments.
+- **Cross-service:** add your API domains to `tracePropagationTargets` so the SDK
+  attaches trace headers (`sentry-trace`, `baggage`, and the newer `traceparent`) on
+  outbound requests, and allow those headers via CORS — or propagation silently fails
+  and you get two disconnected traces.
+- **Instrument boundaries first** (incoming/outbound HTTP, DB / cache / queue — mostly
+  auto-instrumented), add custom spans for meaningful business operations, and keep span
+  names **low-cardinality and templated** (`GET /users/:id`, not `/users/12345`) with
+  searchable attributes rather than baking values into the name.
+  Follow Sentry’s semantic conventions for span and attribute names.
+  The instrument skill lists the domain references under Semantic conventions; open only
+  the one you need (for example `references/semantics/http.md`).
+
+## Related
+
+- [`profiling.md`](profiling.md)
+- [`reduce-volume.md`](reduce-volume.md) — sampling is the main lever.
+- [`search-query-language.md`](../search-query-language.md) — span properties for
+  querying traces.

package/skills/sentry/references/concepts/user-feedback.md

@@ -0,0 +1,36 @@
+# User Feedback — What & Why
+
+Qualitative reports from real users, linked to Sentry context — the surrounding error,
+replay, trace, release, and user.
+The one signal that captures _what the human thinks went wrong_, which the machine
+signals can’t tell you.
+
+## What a feedback entry is worth
+
+Its value is the **linked context**, not the prose.
+A feedback entry carries a pivot to the moment it’s about: a widget submission attaches
+the user’s replay (roughly the minute before they hit submit) and the page URL; a
+crash-report submission links straight to the **issue**. So feedback is a way _into_ the
+machine signals from the human side — and it surfaces as its own issue category
+(`Feedback`) rather than living in a separate silo.
+
+## Setup essentials — three mechanisms
+
+- **Feedback widget** (browser only) — an embeddable, auto-injectable button/form with
+  an optional screenshot.
+  The default for web.
+- **`captureFeedback` API** — programmatic; the cross-platform path
+  (mobile/desktop/backend) and when you want control over your own UI.
+- **Crash-report modal** — prompts for detail right after an error fires; the practical
+  option where there’s no persistent UI to host a widget.
+
+Decide required fields and screenshots up front (more fields = fewer but richer
+submissions), **route feedback somewhere actionable** (Slack / Jira / an alert) so it
+isn’t a black hole, and apply replay-grade masking to screenshots — they capture
+whatever is on screen.
+
+## Related
+
+- [`session-replay.md`](session-replay.md)
+- [`data-scrubbing.md`](data-scrubbing.md)
+- [`search-query-language.md`](../search-query-language.md) — user-feedback properties.

package/skills/sentry/references/debug-artifacts/android.md

@@ -0,0 +1,68 @@
+# Debug files — Android (ProGuard/R8, NDK)
+
+Two independent artifact families, and a release build usually needs both:
+
+- **ProGuard/R8 mapping** — undoes name obfuscation in Kotlin/Java frames (`a.b.c()` →
+  real names).
+- **Native symbols (`.so`)** — symbolicates NDK/C++ frames.
+  Only relevant if the app ships native code.
+
+## Path A — the Sentry Gradle plugin (preferred)
+
+The plugin uploads on release builds, so it can’t be forgotten at release time.
+The plugin id and the dependency wiring live in `sdks/android/index.md`; the
+upload-related options in the `sentry {}` block are:
+
+```groovy
+sentry {
+    org = "YOUR_ORG_SLUG"
+    projectName = "YOUR_PROJECT_SLUG"
+    authToken = System.getenv("SENTRY_AUTH_TOKEN")
+
+    // Kotlin/Java deobfuscation
+    autoUploadProguardMapping = true
+
+    // Code context next to frames
+    includeSourceContext = true
+}
+```
+
+For an app with native code, also enable native symbol upload (`uploadNativeSymbols`,
+plus the matching include-sources option for native).
+Check the plugin’s own documentation for the current option names before adding them —
+the native options have changed across plugin majors, and a wrong name is silently
+ignored rather than failing the build.
+
+`authToken` from `System.getenv` keeps the secret out of the build file.
+A gitignored `sentry.properties` also works.
+
+## Path B — the wizard
+
+```
+npx @sentry/wizard@latest -i android
+```
+
+Interactive, so the **user** runs it.
+It handles login, org/project selection, the Gradle plugin, the DSN, and ProGuard/R8
+mapping upload.
+
+## Path C — manual `sentry-cli`
+
+For builds the plugin can’t be added to.
+The mapping file is produced by R8 at `app/build/outputs/mapping/<variant>/mapping.txt`,
+and it must be uploaded with the **UUID that the app reports**, so the plugin path is
+strongly preferred — doing this by hand means managing that UUID in
+`AndroidManifest.xml` yourself and keeping it in sync with each upload.
+Reach for it only when Gradle-plugin adoption is genuinely blocked, and read the current
+sentry-cli docs for the exact `debug-files upload` invocation for mappings.
+
+## Traps
+
+| Symptom                                       | Cause                                                                                               | Fix                                                            |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Frames still obfuscated after a release build | `autoUploadProguardMapping` not enabled, or minification runs in a variant the plugin doesn’t cover | Enable it; confirm the release variant is the one shipped      |
+| Debug builds look fine, release doesn’t       | Expected — obfuscation only runs for release                                                        | Always test symbolication on a release build                   |
+| Kotlin frames readable, native frames not     | Only the mapping was uploaded                                                                       | Enable native symbol upload                                    |
+| Nothing uploads, build green                  | Token unset — see `../auth-token.md`                                                                | Add `SENTRY_AUTH_TOKEN` to the build environment               |
+| Worked, then stopped after a version bump     | Plugin option renamed across a major, now silently ignored                                          | Re-check option names against the plugin docs for your version |
+| Frames readable, no code context              | `includeSourceContext` off                                                                          | Enable it and re-check a new event                             |

package/skills/sentry/references/debug-artifacts/apple.md

@@ -0,0 +1,96 @@
+# Debug files — Apple (iOS, macOS, tvOS, watchOS, visionOS)
+
+Native crashes arrive as addresses.
+Symbolication needs the **dSYM** bundle produced by the build that shipped — a different
+dSYM won’t do, because the UUID must match.
+
+## Prerequisite: the build must produce dSYMs
+
+Xcode only emits them when the build setting is right:
+
+- **`DEBUG_INFORMATION_FORMAT`** = `DWARF with dSYM File`. This is the default for
+  **Release** only — a Debug-configuration build produces no dSYM, so a crash from it
+  can’t be symbolicated this way.
+- **`ENABLE_USER_SCRIPT_SANDBOXING`** = `NO`, or an upload build phase can’t read the
+  dSYM directory.
+
+## Path A — the wizard (preferred)
+
+```
+brew install getsentry/tools/sentry-wizard && sentry-wizard -i ios
+```
+
+Interactive (browser login), so the **user** runs it.
+It sets up the auth token, the SDK, and the dSYM upload build phase — which is the part
+that’s easy to get wrong by hand.
+
+## Path B — an Xcode Run Script build phase
+
+Add a Run Script phase after the compile/archive steps:
+
+```bash
+sentry-cli debug-files upload --include-sources "$DWARF_DSYM_FOLDER_PATH"
+```
+
+- `$DWARF_DSYM_FOLDER_PATH` is provided by Xcode and points at the dSYMs for this build.
+- `--include-sources` bundles source snippets so Sentry can show code context next to
+  native frames. Omit it if your source can’t leave the build machine.
+- Supply `SENTRY_ORG`, `SENTRY_PROJECT`, and `SENTRY_AUTH_TOKEN` to the phase’s
+  environment (or a gitignored `sentry.properties`).
+- Add `--force-foreground` while debugging the phase — the upload otherwise backgrounds
+  itself and its output can be lost from the build log.
+
+For the phase’s input file list, the per-executable dSYM path is:
+
+```
+${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${EXECUTABLE_NAME}
+```
+
+## Path C — Fastlane
+
+If the project already uses Fastlane, upload there instead of in Xcode:
+
+```ruby
+sentry_debug_files_upload(
+  auth_token: ENV["SENTRY_AUTH_TOKEN"],
+  org_slug: "your-org",
+  project_slug: "your-project",
+  include_sources: true
+)
+```
+
+Self-hosted Sentry: export `SENTRY_URL`, or pass `url:` to the Fastlane action.
+
+## Path D — after the fact, from App Store Connect
+
+When Apple processes the build (or the shipped dSYMs were never uploaded), fetch them
+and upload separately.
+Fastlane’s `download_dsyms` handles the fetch; then run the same
+`sentry-cli debug-files upload` against the downloaded path.
+
+Uploading alone does not change the crash you’re already looking at — symbolication runs
+at ingest, so the stored event keeps the frames it was processed with.
+Unlike source maps, though, native events can be **reprocessed**: trigger it from the
+issue and Sentry re-runs symbolication against the debug files it now has.
+Three things to know before you do — wait at least an hour after the upload (the
+internal caches must expire first), reprocessed events count against quota a second
+time, and issue alerts don’t fire for them.
+See [Reprocessing](https://docs.sentry.io/product/issues/reprocessing/).
+
+## Verifying the artifact side
+
+`sentry-cli debug-files` can confirm what Sentry has before you re-run the app.
+Sentry’s issue view also lists the debug images an event needed and whether each was
+found — that list, not the build log, is the authority on whether the right UUID
+arrived.
+
+## Traps
+
+| Symptom                                              | Cause                                                                | Fix                                                         |
+| ---------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
+| No dSYM anywhere in the build output                 | Debug configuration, or `DEBUG_INFORMATION_FORMAT` set to DWARF-only | Set `DWARF with dSYM File`; symbolicate release builds      |
+| Build phase fails reading the dSYM dir               | User script sandboxing on                                            | `ENABLE_USER_SCRIPT_SANDBOXING = NO`                        |
+| Uploads succeed, crash still unsymbolicated          | UUID mismatch — a rebuild produced a new binary after the upload     | Upload from the archive that shipped; don’t rebuild between |
+| Frames symbolicated, no source lines                 | `--include-sources` not used                                         | Add it, re-upload, check a new event                        |
+| Works locally, not on CI/Xcode Cloud                 | Token or org/project env missing in the CI build environment         | Add them as CI secrets                                      |
+| Only your code is unsymbolicated; system frames fine | Sentry symbolicates OS frames itself; yours need your dSYM           | Nothing about system symbols to fix — chase your own upload |

package/skills/sentry/references/debug-artifacts/dotnet.md

@@ -0,0 +1,70 @@
+# Debug files — .NET (Portable PDB)
+
+.NET fails differently from JavaScript and native, and the difference matters for
+triage: method names survive.
+What goes missing is the **file name and line number**. A frame that reads
+`MyApp.Services.Checkout.Charge()` with no `Checkout.cs:118` after it is this problem —
+the trace isn’t unreadable, it’s unlocatable.
+Don’t go looking for a minification story that doesn’t exist.
+
+The artifact is the **PDB** the build already produces — Portable PDB on modern .NET,
+supported by Sentry since 22.11.0 (sentry-cli 2.8.0).
+
+## Path A — MSBuild (preferred)
+
+The Sentry NuGet package bundles sentry-cli and can upload during the build.
+Both upload properties default to **`false`**, so a project that installed the SDK and
+did nothing else uploads nothing — this is the normal starting state, not a broken
+config.
+
+```xml
+<PropertyGroup Condition="'$(Configuration)' == 'Release'">
+  <SentryOrg>YOUR_ORG_SLUG</SentryOrg>
+  <SentryProject>YOUR_PROJECT_SLUG</SentryProject>
+  <SentryUploadSymbols>true</SentryUploadSymbols>
+  <SentryUploadSources>true</SentryUploadSources>
+</PropertyGroup>
+```
+
+- `SentryUploadSources` is the source-context switch — file/line without it, surrounding
+  code with it. Omit it if your source can’t leave the build machine.
+- Condition on `Release`. An unconditional block uploads on every local Debug build.
+- `UseSentryCLI` (default `true`) disables the bundled CLI outright; if something in the
+  build sets it to `false`, nothing uploads regardless of the properties above.
+
+The wider property block — release creation and commit association — lives in
+`sdks/dotnet/index.md` as ordinary SDK config.
+This file covers the upload itself.
+
+## Path B — sentry-cli directly
+
+For a publish pipeline that doesn’t run the Sentry MSBuild targets:
+
+```bash
+sentry-cli debug-files upload --include-sources <path-to-build-output>
+```
+
+Same command as every other native platform — to sentry-cli a PDB is just another
+debug-file format.
+
+## Auth
+
+Don’t inline the token in the project file.
+`SentryAuthToken` exists as an MSBuild property but is discouraged for exactly that
+reason.
+
+- **Workstation:** `sentry-cli login` stores credentials in `~/.sentryclirc`.
+- **CI:** set `SENTRY_AUTH_TOKEN` from the platform’s secret store.
+- **Docker:** BuildKit’s `--secret`, so the token never persists into an image layer.
+
+Details in [`../auth-token.md`](../auth-token.md).
+
+## Traps
+
+| Symptom                                 | Cause                                                               | Fix                                                                          |
+| --------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Method names present, no file/line      | Symbols never uploaded — both properties default to `false`         | Set `SentryUploadSymbols`; this is the default state, not a misconfiguration |
+| File/line present, no surrounding code  | `SentryUploadSources` off                                           | Turn it on, then check a **new** event                                       |
+| Build log shows no upload and no error  | `SentryOrg`/`SentryProject` unset, or `UseSentryCLI=false`          | Supply both slugs — the upload is silent when it has nowhere to send         |
+| No `.pdb` in the build output to upload | `DebugType` is `none`, or `embedded` (which emits no separate file) | Confirm what the build actually produces before debugging the upload         |
+| Works locally, not on CI                | `SENTRY_AUTH_TOKEN` missing from the CI environment                 | Add it as a CI secret                                                        |

package/skills/sentry/references/debug-artifacts/flutter.md

@@ -0,0 +1,65 @@
+# Debug files — Flutter / Dart
+
+Unreadable Dart frames come from **obfuscation**, and the fix is to keep the artifacts
+that undo it — the split debug info and the obfuscation map — then upload them with
+`sentry_dart_plugin`. A Flutter app that also ships native code needs the platform debug
+files too.
+
+## Step 1 — Build so the artifacts exist
+
+Obfuscation and debug info are opt-in build flags, and the plugin can only upload what
+the build wrote:
+
+```bash
+# Android
+flutter build apk \
+  --release \
+  --obfuscate \
+  --split-debug-info=build/debug-info \
+  --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json
+dart run sentry_dart_plugin
+
+# iOS
+flutter build ipa \
+  --release \
+  --obfuscate \
+  --split-debug-info=build/debug-info \
+  --extra-gen-snapshot-options=--save-obfuscation-map=build/app/obfuscation.map.json
+dart run sentry_dart_plugin
+
+# Web
+flutter build web --release --source-maps
+dart run sentry_dart_plugin
+```
+
+If you are **not** obfuscating, Dart frames are generally readable already and this
+whole path is unnecessary — confirm that before adding flags.
+
+## Step 2 — Configure and run `sentry_dart_plugin`
+
+The plugin is configured from `pubspec.yaml` (a `sentry:` section carrying org, project,
+and the upload toggles) and reads `SENTRY_AUTH_TOKEN` from the environment.
+Consult the plugin’s own docs for the current key names before writing that block — they
+differ across plugin majors, and a misspelled key is ignored rather than reported.
+
+Run it **after** each build, as shown above.
+That ordering is the whole contract: the build writes `build/debug-info` and the
+obfuscation map, the plugin uploads them.
+
+## Native layers
+
+Flutter apps with native code inherit the platform pipelines: `apple.md` for dSYM,
+`android.md` for ProGuard/R8 and NDK symbols.
+The Dart obfuscation map does not symbolicate a native crash, and native debug files do
+not de-obfuscate Dart frames.
+
+## Traps
+
+| Symptom                                             | Cause                                                                       | Fix                                                |
+| --------------------------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------- |
+| Dart frames unreadable on release, fine in debug    | Release build obfuscates                                                    | Build with the flags above and run the plugin      |
+| Plugin runs, uploads nothing                        | Build didn’t emit debug info — missing `--split-debug-info` / `--obfuscate` | Add the flags; re-run the plugin after the build   |
+| Uploads happen, frames unchanged                    | Plugin ran against a different build than the one shipped                   | Build and upload in the same CI job, in that order |
+| Dart frames fixed, native crash still raw addresses | Native debug files not uploaded                                             | Follow `apple.md` / `android.md`                   |
+| Web frames minified                                 | Built without `--source-maps`                                               | Rebuild with it, re-run the plugin                 |
+| Config edits have no effect                         | Key name wrong for the installed plugin version                             | Check the plugin docs for your version             |

package/skills/sentry/references/debug-artifacts/index.md

@@ -0,0 +1,75 @@
+# Debug artifacts — making stack traces readable
+
+Frames that read `chunk-4f2a.js:1:28471` or `0x00000001045a2f10` cost you the thing
+Sentry is for.
+Fixing them means uploading the artifact that maps compiled output back to
+source. Two families:
+
+- **Source maps** — JavaScript/TypeScript, minified or bundled by a build step.
+- **Debug files** — native and mobile: dSYM (Apple), ProGuard/R8 mappings (Android),
+  `.so` symbols (NDK), Dart obfuscation maps (Flutter).
+
+This group is read from three directions: while setting Sentry up for the first time (so
+real-user traces are readable, not just the local test error), while adding
+instrumentation, and when someone arrives with an unreadable trace already in hand.
+Start here, route to the platform file.
+
+## First: which failure is it?
+
+Three different problems look identical in a stack trace and have different fixes.
+If an event already exists, read it before touching build config.
+
+| What you see                                                                                   | What it means                                                | Go to                                   |
+| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------- |
+| Minified/obfuscated frames, hex addresses, nothing uploaded for this build                     | No artifacts exist                                           | the platform file below                 |
+| Sentry found artifacts but frames stay unreadable; missing Debug ID or mismatched release/dist | Artifacts don’t match the event                              | [`matching.md`](matching.md)            |
+| Some frames readable, others not — often native frames inside an otherwise fine trace          | A second artifact family is missing                          | the platform file for _that_ family     |
+| Readable file/line but no surrounding code shown                                               | Source context wasn’t uploaded (separate from symbolication) | the platform file’s source-context note |
+| Method names read fine, but no file names or line numbers                                      | .NET without PDBs — a different failure from minification    | [`dotnet.md`](dotnet.md)                |
+
+Two facts that change the answer, worth establishing early:
+
+- **Was the event from a release build?** Dev builds are usually readable already —
+  don’t send someone after source maps for a local `next dev` trace.
+- **Did the upload happen before the event?** Artifacts uploaded afterward do not
+  retroactively fix a stored event on their own — confirm any fix on a **new** event.
+  The one exception is native/Apple events, which can be
+  [reprocessed](https://docs.sentry.io/product/issues/reprocessing/) to apply debug
+  files after the fact.
+  Source maps have no equivalent.
+
+## Platform routing
+
+| Platform                                                                              | Family                                                   | Read                                 |
+| ------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------ |
+| Browser, Node, Next.js, React, Svelte, Nest, Cloudflare, TanStack Start, React Router | Source maps                                              | [`javascript.md`](javascript.md)     |
+| Apple — iOS, macOS, tvOS, watchOS, visionOS                                           | dSYM                                                     | [`apple.md`](apple.md)               |
+| Android — Kotlin/Java, NDK                                                            | ProGuard/R8 mapping, `.so` symbols                       | [`android.md`](android.md)           |
+| React Native / Expo                                                                   | **Both** — JS source maps _and_ native debug files       | [`react-native.md`](react-native.md) |
+| Flutter / Dart                                                                        | Obfuscation map + native debug files (+ web source maps) | [`flutter.md`](flutter.md)           |
+| .NET — ASP.NET Core, MAUI, WPF, WinForms, Azure Functions                             | Portable PDB                                             | [`dotnet.md`](dotnet.md)             |
+| Python, Ruby, PHP, Go, Elixir                                                         | Usually none — frames come from readable source          | see below                            |
+
+Every path needs an auth token: [`../auth-token.md`](../auth-token.md).
+It is the single most common reason a correct-looking setup uploads nothing.
+
+For the last row, unreadable frames are rarely an artifact problem.
+Check that the deployed code matches what you’re reading, that the app isn’t running
+from a stripped or packed build (PyInstaller, Go built with `-ldflags "-s -w"`), and
+that source context is enabled.
+Don’t invent a source-map step for a language that doesn’t have one.
+
+## Where the build-tool config lives
+
+The bundler-plugin options, the Gradle `sentry {}` block, and the wizard invocations are
+documented per platform in that platform’s `sdks/<slug>/index.md`, as ordinary SDK
+configuration. Use it for the config; use this group for what it doesn’t cover — the
+token, artifact matching, native upload mechanics, and CI placement.
+
+## Confirming a fix
+
+Symbolication is proven only by a **new** event from a build that had upload wired in:
+build and deploy, trigger a fresh error, then check the frames.
+Re-reading the old event will show it still minified, which is correct and not a failure
+of the fix — reprocessing, where it’s available, is a separate step you have to ask for.
+The loop is in [`setup-verification.md`](../setup-verification.md).