diff --git a/skills/sentry-instrument/SKILL.md b/skills/sentry-instrument/SKILL.md
index 0e3d3c9..ad96ebc 100644
--- a/skills/sentry-instrument/SKILL.md
+++ b/skills/sentry-instrument/SKILL.md
@@ -95,6 +95,70 @@ Signals this skill wires up: error monitoring, tracing/performance, profiling (r
 tracing), logging, metrics, cron check-in code, session replay, user feedback, and
 AI/LLM monitoring.
 
+### Semantic conventions
+
+When naming custom span or log attributes, open **only** the matching domain reference
+below. Prefer these stable keys over invented names. Deprecated attributes are omitted.
+
+- [`angular`](references/semantics/angular.md)
+- [`app`](references/semantics/app.md)
+- [`art`](references/semantics/art.md)
+- [`aws`](references/semantics/aws.md)
+- [`browser`](references/semantics/browser.md)
+- [`cache`](references/semantics/cache.md)
+- [`client`](references/semantics/client.md)
+- [`cloud`](references/semantics/cloud.md)
+- [`cloudflare`](references/semantics/cloudflare.md)
+- [`code`](references/semantics/code.md)
+- [`culture`](references/semantics/culture.md)
+- [`db`](references/semantics/db.md)
+- [`device`](references/semantics/device.md)
+- [`error`](references/semantics/error.md)
+- [`event`](references/semantics/event.md)
+- [`exception`](references/semantics/exception.md)
+- [`faas`](references/semantics/faas.md)
+- [`file`](references/semantics/file.md)
+- [`flag`](references/semantics/flag.md)
+- [`gcp`](references/semantics/gcp.md)
+- [`gen_ai`](references/semantics/gen_ai.md)
+- [`general`](references/semantics/general.md)
+- [`graphql`](references/semantics/graphql.md)
+- [`grpc`](references/semantics/grpc.md)
+- [`http`](references/semantics/http.md)
+- [`jsonrpc`](references/semantics/jsonrpc.md)
+- [`jvm`](references/semantics/jvm.md)
+- [`koa`](references/semantics/koa.md)
+- [`logger`](references/semantics/logger.md)
+- [`mcp`](references/semantics/mcp.md)
+- [`mdc`](references/semantics/mdc.md)
+- [`messaging`](references/semantics/messaging.md)
+- [`middleware`](references/semantics/middleware.md)
+- [`navigation`](references/semantics/navigation.md)
+- [`nel`](references/semantics/nel.md)
+- [`network`](references/semantics/network.md)
+- [`os`](references/semantics/os.md)
+- [`otel`](references/semantics/otel.md)
+- [`params`](references/semantics/params.md)
+- [`process`](references/semantics/process.md)
+- [`react`](references/semantics/react.md)
+- [`remix`](references/semantics/remix.md)
+- [`resource`](references/semantics/resource.md)
+- [`rpc`](references/semantics/rpc.md)
+- [`score`](references/semantics/score.md)
+- [`sentry`](references/semantics/sentry.md)
+- [`server`](references/semantics/server.md)
+- [`service`](references/semantics/service.md)
+- [`session`](references/semantics/session.md)
+- [`state`](references/semantics/state.md)
+- [`thread`](references/semantics/thread.md)
+- [`timber`](references/semantics/timber.md)
+- [`trpc`](references/semantics/trpc.md)
+- [`ui`](references/semantics/ui.md)
+- [`url`](references/semantics/url.md)
+- [`user`](references/semantics/user.md)
+- [`user_agent`](references/semantics/user_agent.md)
+- [`vercel`](references/semantics/vercel.md)
+
 ## Step 4 — Verify it landed
 
 For a fresh install the spine already verified the first error.
diff --git a/skills/sentry-instrument/references/concepts/ai-monitoring.md b/skills/sentry-instrument/references/concepts/ai-monitoring.md
index 4eaddb8..4d4e2c2 100644
--- a/skills/sentry-instrument/references/concepts/ai-monitoring.md
+++ b/skills/sentry-instrument/references/concepts/ai-monitoring.md
@@ -35,9 +35,9 @@ The span `op` is `gen_ai.{operation}` — `chat`, `embeddings`, `generate_conten
 **name** repeats the operation with its subject: `chat gpt-4o`,
 `invoke_agent Weather Agent`, `execute_tool get_weather`,
 `handoff from triage to billing`. Attributes accept primitives only; arrays/objects are
-JSON-stringified. The canonical attribute set is the
-[Sentry gen_ai conventions](https://getsentry.github.io/sentry-conventions/attributes/gen_ai/)
-— the SDK docs can lag, and attributes marked deprecated there should not be set.
+JSON-stringified. The canonical attribute set is
+[`semantics/gen_ai.md`](../semantics/gen_ai.md) — the SDK docs can lag, and
+deprecated attributes are omitted from that reference on purpose.
 
 ## Conversations
 
diff --git a/skills/sentry-instrument/references/concepts/tracing.md b/skills/sentry-instrument/references/concepts/tracing.md
index 7c58da5..9cbea3b 100644
--- a/skills/sentry-instrument/references/concepts/tracing.md
+++ b/skills/sentry-instrument/references/concepts/tracing.md
@@ -42,8 +42,9 @@ A span also carries its profile, the bridge down to the function level.
   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 (aligned with OpenTelemetry) for span and
-  attribute names so they match what the product expects.
+  Follow Sentry’s semantic conventions for span and attribute names. The core
+  [`SKILL.md`](../../SKILL.md#semantic-conventions) lists the domain references; open
+  only the one you need.
 
 ## Related
 
diff --git a/skills/sentry-instrument/references/semantics/angular.md b/skills/sentry-instrument/references/semantics/angular.md
new file mode 100644
index 0000000..d7cc8fc
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/angular.md
@@ -0,0 +1,8 @@
+# angular attributes
+
+Stable Sentry semantic convention attributes for `angular`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `angular.version` | `string` | The version of the Angular framework |
diff --git a/skills/sentry-instrument/references/semantics/app.md b/skills/sentry-instrument/references/semantics/app.md
new file mode 100644
index 0000000..ca3b8da
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/app.md
@@ -0,0 +1,29 @@
+# app attributes
+
+Stable Sentry semantic convention attributes for `app`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `app.build` | `string` | Internal build identifier, as it appears on the platform. |
+| `app.identifier` | `string` | Version-independent application identifier, often a dotted bundle ID. |
+| `app.in_foreground` | `boolean` | Whether the application is currently in the foreground. |
+| `app.name` | `string` | Human readable application name, as it appears on the platform. |
+| `app.start_time` | `string` | Formatted UTC timestamp when the user started the application. |
+| `app.version` | `string` | Human readable application version, as it appears on the platform. |
+| `app.vitals.frames.delay.value` | `integer` | The sum of all delayed frame durations in seconds during the lifetime of the span. For more information see [frames delay](https://develop.sentry.dev/sdk/performance/frames-delay/). |
+| `app.vitals.frames.frozen.count` | `integer` | The number of frozen frames rendered during the lifetime of the span. |
+| `app.vitals.frames.frozen.rate` | `double` | The fraction of rendered frames that were frozen, calculated as `app.vitals.frames.frozen.count` divided by `app.vitals.frames.total.count`. This is computed by Relay. |
+| `app.vitals.frames.slow.count` | `integer` | The number of slow frames rendered during the lifetime of the span. |
+| `app.vitals.frames.slow.rate` | `double` | The fraction of rendered frames that were slow, calculated as `app.vitals.frames.slow.count` divided by `app.vitals.frames.total.count`. This is computed by Relay. |
+| `app.vitals.frames.total.count` | `integer` | The number of total frames rendered during the lifetime of the span. |
+| `app.vitals.stall.duration` | `double` | The combined duration of all stalls in milliseconds. Only applies to React Native. This is computed by Relay. |
+| `app.vitals.stall.percentage` | `double` | The fraction of transaction duration during which the app was stalled, between 0.0 and 1.0. For example, 0.8 represents 80%. Only applies to React Native. This is computed by Relay. |
+| `app.vitals.start.cold.value` | `double` | The duration of a cold app start in milliseconds |
+| `app.vitals.start.prewarmed` | `boolean` | Whether the app start was prewarmed. |
+| `app.vitals.start.reason` | `string` | The reason that triggered the app start. |
+| `app.vitals.start.screen` | `string` | The screen that is rendered when the app start is complete. This is the screen the user first sees and can interact with after launch. The absence of this attribute on the app start span indicates a background app start where no UI was rendered. |
+| `app.vitals.start.type` | `string` | The type of app start, for example `cold` or `warm` |
+| `app.vitals.start.warm.value` | `double` | The duration of a warm app start in milliseconds |
+| `app.vitals.ttfd.value` | `double` | The duration of time to full display in milliseconds |
+| `app.vitals.ttid.value` | `double` | The duration of time to initial display in milliseconds |
diff --git a/skills/sentry-instrument/references/semantics/art.md b/skills/sentry-instrument/references/semantics/art.md
new file mode 100644
index 0000000..14f46a1
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/art.md
@@ -0,0 +1,18 @@
+# art attributes
+
+Stable Sentry semantic convention attributes for `art`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `art.gc.blocking_count` | `integer` | Total number of blocking (stop-the-world) garbage collections performed by the Android Runtime |
+| `art.gc.blocking_time` | `double` | Total time spent in blocking (stop-the-world) garbage collections by the Android Runtime, in milliseconds |
+| `art.gc.pre_oome_count` | `integer` | Total number of garbage collections triggered as a last resort before an OutOfMemoryError by the Android Runtime |
+| `art.gc.total_count` | `integer` | Total number of garbage collections performed by the Android Runtime |
+| `art.gc.total_time` | `double` | Total time spent in garbage collection by the Android Runtime, in milliseconds |
+| `art.gc.waiting_time` | `double` | Total time threads spent waiting for garbage collection to complete in the Android Runtime, in milliseconds |
+| `art.memory.free` | `integer` | Free memory available to the process as reported by the Android Runtime, in bytes |
+| `art.memory.free_until_gc` | `integer` | Free memory available before a garbage collection would be triggered by the Android Runtime, in bytes |
+| `art.memory.free_until_oome` | `integer` | Free memory available before an OutOfMemoryError would be thrown by the Android Runtime, in bytes |
+| `art.memory.max` | `integer` | Maximum memory the process is allowed to use as reported by the Android Runtime, in bytes |
+| `art.memory.total` | `integer` | Total memory currently allocated to the process by the Android Runtime, in bytes |
diff --git a/skills/sentry-instrument/references/semantics/aws.md b/skills/sentry-instrument/references/semantics/aws.md
new file mode 100644
index 0000000..b758388
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/aws.md
@@ -0,0 +1,44 @@
+# aws attributes
+
+Stable Sentry semantic convention attributes for `aws`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `aws.cloudwatch.logs.log_group` | `string` | The name of the CloudWatch Logs log group |
+| `aws.cloudwatch.logs.log_stream` | `string` | The name of the CloudWatch Logs log stream |
+| `aws.cloudwatch.logs.url` | `string` | The URL to the CloudWatch Logs log group |
+| `aws.dynamodb.attribute_definitions` | `string[]` | The JSON-serialized value of each item in the `AttributeDefinitions` request field. |
+| `aws.dynamodb.consistent_read` | `boolean` | The value of the `ConsistentRead` request parameter. |
+| `aws.dynamodb.consumed_capacity` | `string[]` | The JSON-serialized value of each item in the `ConsumedCapacity` response field. |
+| `aws.dynamodb.count` | `integer` | The value of the `Count` response parameter. |
+| `aws.dynamodb.exclusive_start_table` | `string` | The value of the `ExclusiveStartTableName` request parameter. |
+| `aws.dynamodb.global_secondary_index_updates` | `string[]` | The JSON-serialized value of each item in the `GlobalSecondaryIndexUpdates` request field. |
+| `aws.dynamodb.global_secondary_indexes` | `string[]` | The JSON-serialized value of each item of the `GlobalSecondaryIndexes` request field. |
+| `aws.dynamodb.index_name` | `string` | The value of the `IndexName` request parameter. |
+| `aws.dynamodb.item_collection_metrics` | `string` | The JSON-serialized value of the `ItemCollectionMetrics` response field. |
+| `aws.dynamodb.limit` | `integer` | The value of the `Limit` request parameter. |
+| `aws.dynamodb.local_secondary_indexes` | `string[]` | The JSON-serialized value of each item of the `LocalSecondaryIndexes` request field. |
+| `aws.dynamodb.projection` | `string` | The value of the `ProjectionExpression` request parameter. |
+| `aws.dynamodb.provisioned_read_capacity` | `double` | The value of the `ProvisionedThroughput.ReadCapacityUnits` request parameter. |
+| `aws.dynamodb.provisioned_write_capacity` | `double` | The value of the `ProvisionedThroughput.WriteCapacityUnits` request parameter. |
+| `aws.dynamodb.scan_forward` | `boolean` | The value of the `ScanIndexForward` request parameter. |
+| `aws.dynamodb.scanned_count` | `integer` | The value of the `ScannedCount` response parameter. |
+| `aws.dynamodb.segment` | `integer` | The value of the `Segment` request parameter. |
+| `aws.dynamodb.select` | `string` | The value of the `Select` request parameter. |
+| `aws.dynamodb.table_count` | `integer` | The number of items in the `TableNames` response parameter. |
+| `aws.dynamodb.table_names` | `string[]` | The keys in the `RequestItems` object field. |
+| `aws.dynamodb.total_segments` | `integer` | The value of the `TotalSegments` request parameter. |
+| `aws.extended_request_id` | `string` | The AWS extended request ID as returned in the response headers. |
+| `aws.kinesis.stream_name` | `string` | The name of the AWS Kinesis stream the request refers to. |
+| `aws.lambda.execution_duration_in_millis` | `double` | The execution duration of the Lambda function invocation in milliseconds |
+| `aws.lambda.invoked_arn` | `string` | The full ARN of the Lambda function that was invoked |
+| `aws.lambda.remaining_time_in_millis` | `double` | The remaining time in milliseconds before the Lambda function times out |
+| `aws.log.group.names` | `string[]` | The name(s) of the AWS log group(s) an application is writing to. |
+| `aws.log.stream.names` | `string[]` | The name(s) of the AWS log stream(s) an application is writing to. |
+| `aws.request_id` | `string` | The AWS request ID as returned in the response headers. |
+| `aws.s3.bucket` | `string` | The S3 bucket name the request refers to. |
+| `aws.secretsmanager.secret.arn` | `string` | The ARN of the Secret stored in Secrets Manager. |
+| `aws.sns.topic.arn` | `string` | The ARN of the AWS SNS Topic. An Amazon SNS topic is a logical access point that acts as a communication channel. |
+| `aws.step_functions.activity.arn` | `string` | The ARN of the AWS Step Functions Activity. |
+| `aws.step_functions.state_machine.arn` | `string` | The ARN of the AWS Step Functions State Machine. |
diff --git a/skills/sentry-instrument/references/semantics/browser.md b/skills/sentry-instrument/references/semantics/browser.md
new file mode 100644
index 0000000..4a5f262
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/browser.md
@@ -0,0 +1,35 @@
+# browser attributes
+
+Stable Sentry semantic convention attributes for `browser`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `browser.bfcache.frame` | `string` | Which frame in the page's frame tree a back/forward cache not-restored reason originated from: the top document or a child frame. |
+| `browser.bfcache.not_restored_reason_count` | `integer` | The number of reported reasons a page was not restored from the back/forward cache on a back/forward navigation. 0 when the browser reported no reasons (e.g. non-Chromium browsers). |
+| `browser.bfcache.outcome` | `string` | Whether a back/forward navigation was restored from the browser's back/forward cache (bfcache). 'hit' means the page was restored; 'miss' means it was reloaded. |
+| `browser.bfcache.reason` | `string` | A browser-reported reason a page was not restored from the back/forward cache on a back/forward navigation, taken from the notRestoredReasons API. Reported per reason (a single miss can have several). Currently Chromium-only. |
+| `browser.name` | `string` | The name of the browser. |
+| `browser.performance.navigation.activation_start` | `double` | The time between initiating a navigation to a page and the browser activating the page |
+| `browser.performance.time_origin` | `double` | The browser's performance.timeOrigin timestamp representing the time when the pageload was initiated |
+| `browser.report.type` | `string` | A browser report sent via reporting API.. |
+| `browser.script.invoker` | `string` | How a script was called in the browser. |
+| `browser.script.invoker_type` | `string` | Browser script entry point type. |
+| `browser.script.source_char_position` | `integer` | A number representing the script character position of the script. |
+| `browser.version` | `string` | The version of the browser. |
+| `browser.web_vital.cls.report_event` | `string` | The event that caused the SDK to report CLS (pagehide or navigation) |
+| `browser.web_vital.cls.source.<key>` | `string` | The HTML elements or components responsible for the layout shift. <key> is a numeric index from 1 to N |
+| `browser.web_vital.cls.value` | `double` | The value of the recorded Cumulative Layout Shift (CLS) web vital |
+| `browser.web_vital.fcp.value` | `double` | The time it takes for the browser to render the first piece of meaningful content on the screen |
+| `browser.web_vital.fp.value` | `double` | The time in milliseconds it takes for the browser to render the first pixel on the screen |
+| `browser.web_vital.inp.value` | `double` | The value of the recorded Interaction to Next Paint (INP) web vital |
+| `browser.web_vital.lcp.element` | `string` | The HTML element selector or component name for which LCP was reported |
+| `browser.web_vital.lcp.id` | `string` | The id of the dom element responsible for the largest contentful paint |
+| `browser.web_vital.lcp.load_time` | `integer` | The time it took for the LCP element to be loaded |
+| `browser.web_vital.lcp.render_time` | `integer` | The time it took for the LCP element to be rendered |
+| `browser.web_vital.lcp.report_event` | `string` | The event that caused the SDK to report LCP (pagehide or navigation) |
+| `browser.web_vital.lcp.size` | `integer` | The size of the largest contentful paint element |
+| `browser.web_vital.lcp.url` | `string` | The url of the dom element responsible for the largest contentful paint |
+| `browser.web_vital.lcp.value` | `double` | The value of the recorded Largest Contentful Paint (LCP) web vital |
+| `browser.web_vital.ttfb.request_time` | `double` | The time it takes for the server to process the initial request and send the first byte of a response to the user's browser |
+| `browser.web_vital.ttfb.value` | `double` | The value of the recorded Time To First Byte (TTFB) web vital in Milliseconds |
diff --git a/skills/sentry-instrument/references/semantics/cache.md b/skills/sentry-instrument/references/semantics/cache.md
new file mode 100644
index 0000000..bdc3134
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/cache.md
@@ -0,0 +1,13 @@
+# cache attributes
+
+Stable Sentry semantic convention attributes for `cache`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `cache.hit` | `boolean` | If the cache was hit during this span. |
+| `cache.item_size` | `integer` | The size of the requested item in the cache. In bytes. |
+| `cache.key` | `string[]` | The key of the cache accessed. |
+| `cache.operation` | `string` | The operation being performed on the cache. |
+| `cache.ttl` | `integer` | The ttl of the cache in seconds |
+| `cache.write` | `boolean` | If the cache operation resulted in a write to the cache. |
diff --git a/skills/sentry-instrument/references/semantics/client.md b/skills/sentry-instrument/references/semantics/client.md
new file mode 100644
index 0000000..f995cbd
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/client.md
@@ -0,0 +1,9 @@
+# client attributes
+
+Stable Sentry semantic convention attributes for `client`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `client.address` | `string` | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. |
+| `client.port` | `integer` | Client port number. |
diff --git a/skills/sentry-instrument/references/semantics/cloud.md b/skills/sentry-instrument/references/semantics/cloud.md
new file mode 100644
index 0000000..de5f66d
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/cloud.md
@@ -0,0 +1,13 @@
+# cloud attributes
+
+Stable Sentry semantic convention attributes for `cloud`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `cloud.account.id` | `string` | The cloud account ID the resource is assigned to |
+| `cloud.availability_zone` | `string` | Cloud regions often have multiple, isolated locations known as zones to increase availability |
+| `cloud.platform` | `string` | The cloud platform in use |
+| `cloud.provider` | `string` | Name of the cloud provider |
+| `cloud.region` | `string` | The geographical region the resource is running |
+| `cloud.resource_id` | `string` | Cloud provider-specific native identifier of the monitored cloud resource |
diff --git a/skills/sentry-instrument/references/semantics/cloudflare.md b/skills/sentry-instrument/references/semantics/cloudflare.md
new file mode 100644
index 0000000..b3315a8
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/cloudflare.md
@@ -0,0 +1,24 @@
+# cloudflare attributes
+
+Stable Sentry semantic convention attributes for `cloudflare`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `cloudflare.d1.duration` | `integer` | The duration of a Cloudflare D1 operation. |
+| `cloudflare.d1.rows_read` | `integer` | The number of rows read in a Cloudflare D1 operation. |
+| `cloudflare.d1.rows_written` | `integer` | The number of rows written in a Cloudflare D1 operation. |
+| `cloudflare.durable_object.query.bindings` | `integer` | The number of bound parameters passed to the SQL exec call. |
+| `cloudflare.durable_object.response.rows_read` | `integer` | The number of rows read by a Cloudflare Durable Object SQL operation. |
+| `cloudflare.durable_object.response.rows_written` | `integer` | The number of rows written by a Cloudflare Durable Object SQL operation. |
+| `cloudflare.r2.bucket` | `string` | The name of the Cloudflare R2 bucket binding |
+| `cloudflare.r2.operation` | `string` | The R2 API operation being performed |
+| `cloudflare.r2.request.delimiter` | `string` | The delimiter used to group objects in an R2 list operation |
+| `cloudflare.r2.request.key` | `string` | The object key used in the R2 operation |
+| `cloudflare.r2.request.part_number` | `integer` | The part number in a multipart upload operation |
+| `cloudflare.r2.request.prefix` | `string` | The prefix used to filter objects in an R2 list operation |
+| `cloudflare.workflow.attempt` | `integer` | The current attempt number for a Cloudflare Workflow step |
+| `cloudflare.workflow.retries.backoff` | `string` | The backoff strategy for Cloudflare Workflow step retries |
+| `cloudflare.workflow.retries.delay` | `string` | The delay between Cloudflare Workflow step retries |
+| `cloudflare.workflow.retries.limit` | `integer` | The maximum number of retries for a Cloudflare Workflow step |
+| `cloudflare.workflow.timeout` | `string` | The timeout duration for a Cloudflare Workflow step |
diff --git a/skills/sentry-instrument/references/semantics/code.md b/skills/sentry-instrument/references/semantics/code.md
new file mode 100644
index 0000000..0c9b69f
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/code.md
@@ -0,0 +1,12 @@
+# code attributes
+
+Stable Sentry semantic convention attributes for `code`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `code.file.path` | `string` | The source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path). |
+| `code.function` | `string` | The method or function name, or equivalent (usually rightmost part of the code unit's name). |
+| `code.function.name` | `string` | The method or function fully-qualified name without arguments. |
+| `code.line.number` | `integer` | The line number in code.filepath best representing the operation. It SHOULD point within the code unit named in code.function |
+| `code.namespace` | `string` | The 'namespace' within which code.function is defined. Usually the qualified class or module name, such that code.namespace + some separator + code.function form a unique identifier for the code unit. |
diff --git a/skills/sentry-instrument/references/semantics/culture.md b/skills/sentry-instrument/references/semantics/culture.md
new file mode 100644
index 0000000..172921c
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/culture.md
@@ -0,0 +1,12 @@
+# culture attributes
+
+Stable Sentry semantic convention attributes for `culture`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `culture.calendar` | `string` | The calendar system used by the culture. |
+| `culture.display_name` | `string` | Human readable name of the culture. |
+| `culture.is_24_hour_format` | `boolean` | Whether the culture uses 24-hour time format. |
+| `culture.locale` | `string` | The locale identifier following RFC 4646. |
+| `culture.timezone` | `string` | The timezone of the culture, as a geographic timezone identifier. |
diff --git a/skills/sentry-instrument/references/semantics/db.md b/skills/sentry-instrument/references/semantics/db.md
new file mode 100644
index 0000000..0450542
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/db.md
@@ -0,0 +1,22 @@
+# db attributes
+
+Stable Sentry semantic convention attributes for `db`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `db.collection.name` | `string` | The name of a collection (table, container) within the database. |
+| `db.driver.name` | `string` | The name of the driver used for the database connection. |
+| `db.namespace` | `string` | The name of the database being accessed. |
+| `db.operation.batch.size` | `integer` | The number of queries included in a batch operation. Operations are only considered batches when they contain two or more operations, and so db.operation.batch.size SHOULD never be 1. |
+| `db.operation.name` | `string` | The name of the operation being executed. |
+| `db.query.parameter.<key>` | `string` | A query parameter used in db.query.text, with <key> being the parameter name, and the attribute value being a string representation of the parameter value. |
+| `db.query.summary` | `string` | A shortened representation of operation(s) in the full query. This attribute must be low-cardinality and should only contain the operation table names. |
+| `db.query.text` | `string` | The database parameterized query being executed. Any parameter values (filters, insertion values, etc) should be replaced with parameter placeholders. If applicable, use `db.query.parameter.<key>` to add the parameter value. |
+| `db.redis.connection` | `string` | The redis connection name. |
+| `db.redis.key` | `string` | The key the Redis command is operating on. |
+| `db.redis.parameters` | `string[]` | The array of command parameters given to a redis command. |
+| `db.response.status_code` | `string` | Database response status code. The status code returned by the database. Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. |
+| `db.stored_procedure.name` | `string` | The name of a stored procedure being called. |
+| `db.system.name` | `string` | An identifier for the database management system (DBMS) product being used. See [OpenTelemetry docs](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystem) for a list of well-known identifiers. |
+| `db.user` | `string` | The database user. |
diff --git a/skills/sentry-instrument/references/semantics/device.md b/skills/sentry-instrument/references/semantics/device.md
new file mode 100644
index 0000000..5d19416
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/device.md
@@ -0,0 +1,44 @@
+# device attributes
+
+Stable Sentry semantic convention attributes for `device`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `device.archs` | `string[]` | The CPU architectures of the device. |
+| `device.battery_level` | `double` | The battery level of the device as a percentage (0-100). |
+| `device.battery_temperature` | `double` | The battery temperature of the device in Celsius. |
+| `device.boot_time` | `string` | A formatted UTC timestamp when the system was booted. |
+| `device.brand` | `string` | The brand of the device. |
+| `device.charging` | `boolean` | Whether the device was charging or not. |
+| `device.chipset` | `string` | The chipset of the device. |
+| `device.class` | `string` | The classification of the device. For example, `low`, `medium`, or `high`. Typically inferred by Relay - SDKs generally do not need to set this directly. |
+| `device.cpu_description` | `string` | A description of the CPU of the device. |
+| `device.external_free_storage` | `integer` | External storage free size in bytes. |
+| `device.external_storage_size` | `integer` | External storage total size in bytes. |
+| `device.family` | `string` | The family of the device. |
+| `device.free_memory` | `integer` | Free system memory in bytes. |
+| `device.free_storage` | `integer` | Free device storage in bytes. |
+| `device.id` | `string` | Unique device identifier. |
+| `device.locale` | `string` | The locale of the device. |
+| `device.low_memory` | `boolean` | Whether the device was low on memory. |
+| `device.low_power_mode` | `boolean` | Whether the device is in Low Power Mode. |
+| `device.manufacturer` | `string` | The manufacturer of the device. |
+| `device.memory.estimated_capacity` | `integer` | The estimated total memory capacity of the device, only a rough estimation in gigabytes. Browsers report estimations in buckets of powers of 2, mostly capped at 8 GB |
+| `device.memory_size` | `integer` | Total system memory available in bytes. |
+| `device.model` | `string` | The model of the device. |
+| `device.model_id` | `string` | An internal hardware revision to identify the device exactly. |
+| `device.name` | `string` | The name of the device. On mobile, this is the user-assigned device name. On servers and desktops, this is typically the hostname. |
+| `device.online` | `boolean` | Whether the device was online or not. |
+| `device.orientation` | `string` | The orientation of the device, either "portrait" or "landscape". |
+| `device.processor_count` | `integer` | Number of "logical processors". |
+| `device.processor_frequency` | `double` | Processor frequency in MHz. |
+| `device.screen_density` | `double` | The screen density of the device. |
+| `device.screen_dpi` | `integer` | The screen density in dots-per-inch (DPI) of the device. |
+| `device.screen_height_pixels` | `integer` | The height of the device screen in pixels. |
+| `device.screen_width_pixels` | `integer` | The width of the device screen in pixels. |
+| `device.simulator` | `boolean` | Whether the device is a simulator or an actual device. |
+| `device.storage_size` | `integer` | Total device storage in bytes. |
+| `device.thermal_state` | `string` | The thermal state of the device. Based on Apple's `ProcessInfo.ThermalState` enum: `nominal`, `fair`, `serious`, or `critical`. |
+| `device.timezone` | `string` | The timezone of the device. |
+| `device.usable_memory` | `integer` | Memory usable for the app in bytes. |
diff --git a/skills/sentry-instrument/references/semantics/error.md b/skills/sentry-instrument/references/semantics/error.md
new file mode 100644
index 0000000..5bb127c
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/error.md
@@ -0,0 +1,8 @@
+# error attributes
+
+Stable Sentry semantic convention attributes for `error`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `error.type` | `string` | Describes a class of error the operation ended with. |
diff --git a/skills/sentry-instrument/references/semantics/event.md b/skills/sentry-instrument/references/semantics/event.md
new file mode 100644
index 0000000..651e0d0
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/event.md
@@ -0,0 +1,9 @@
+# event attributes
+
+Stable Sentry semantic convention attributes for `event`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `event.id` | `integer` | The unique identifier for this event (log record) |
+| `event.name` | `string` | The name that uniquely identifies this event (log record) |
diff --git a/skills/sentry-instrument/references/semantics/exception.md b/skills/sentry-instrument/references/semantics/exception.md
new file mode 100644
index 0000000..ddd1ba0
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/exception.md
@@ -0,0 +1,11 @@
+# exception attributes
+
+Stable Sentry semantic convention attributes for `exception`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `exception.escaped` | `boolean` | SHOULD be set to true if the exception event is recorded at a point where it is known that the exception is escaping the scope of the span. |
+| `exception.message` | `string` | The error message. |
+| `exception.stacktrace` | `string` | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. |
+| `exception.type` | `string` | The type of the exception (its fully-qualified class name, if applicable). The dynamic type of the exception should be preferred over the static type in languages that support it. |
diff --git a/skills/sentry-instrument/references/semantics/faas.md b/skills/sentry-instrument/references/semantics/faas.md
new file mode 100644
index 0000000..5b484f2
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/faas.md
@@ -0,0 +1,20 @@
+# faas attributes
+
+Stable Sentry semantic convention attributes for `faas`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `faas.coldstart` | `boolean` | A boolean that is true if the serverless function is executed for the first time (aka cold-start). |
+| `faas.cron` | `string` | A string containing the schedule period as Cron Expression. |
+| `faas.duration_in_ms` | `integer` | The duration a function took to run, in milliseconds. |
+| `faas.entry_point` | `string` | The code that's run when the cloud provider invokes your function. |
+| `faas.identity` | `string` | The Service Account (GCP), IAM Execution Role (AWS), or Managed Identity (Azure) used by the serverless function when interacting with other cloud services |
+| `faas.invocation_id` | `string` | The invocation ID of the current function invocation. |
+| `faas.invoked_name` | `string` | The name of the invoked function. |
+| `faas.invoked_provider` | `string` | The cloud provider of the invoked function. |
+| `faas.invoked_region` | `string` | The cloud region of the invoked function. |
+| `faas.name` | `string` | The name of the serverless function |
+| `faas.time` | `string` | A string containing the function invocation time in the ISO 8601 format expressed in UTC. |
+| `faas.trigger` | `string` | Type of the trigger which caused this function invocation. |
+| `faas.version` | `string` | The version of the function that was invoked |
diff --git a/skills/sentry-instrument/references/semantics/file.md b/skills/sentry-instrument/references/semantics/file.md
new file mode 100644
index 0000000..7727b13
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/file.md
@@ -0,0 +1,9 @@
+# file attributes
+
+Stable Sentry semantic convention attributes for `file`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `file.path` | `string` | Path to the file. |
+| `file.size` | `integer` | File size in bytes. |
diff --git a/skills/sentry-instrument/references/semantics/flag.md b/skills/sentry-instrument/references/semantics/flag.md
new file mode 100644
index 0000000..d7242ba
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/flag.md
@@ -0,0 +1,8 @@
+# flag attributes
+
+Stable Sentry semantic convention attributes for `flag`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `flag.evaluation.<key>` | `boolean` | An instance of a feature flag evaluation. The value of this attribute is the boolean representing the evaluation result. The <key> suffix is the name of the feature flag. |
diff --git a/skills/sentry-instrument/references/semantics/gcp.md b/skills/sentry-instrument/references/semantics/gcp.md
new file mode 100644
index 0000000..d1c2602
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/gcp.md
@@ -0,0 +1,17 @@
+# gcp attributes
+
+Stable Sentry semantic convention attributes for `gcp`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `gcp.function.context.event_id` | `string` | The event ID from the legacy GCP Cloud Function context (1st gen) |
+| `gcp.function.context.event_type` | `string` | The type of the GCP Cloud Function event |
+| `gcp.function.context.id` | `string` | The unique event ID from the GCP CloudEvents context (2nd gen Cloud Functions) |
+| `gcp.function.context.resource` | `string` | The resource that triggered the GCP Cloud Function event |
+| `gcp.function.context.source` | `string` | The source of the GCP Cloud Function event |
+| `gcp.function.context.specversion` | `string` | The CloudEvents specification version of the GCP Cloud Function event |
+| `gcp.function.context.time` | `string` | The timestamp of the GCP Cloud Function event |
+| `gcp.function.context.timestamp` | `string` | The legacy timestamp of the GCP Cloud Function event |
+| `gcp.function.context.type` | `string` | The type of the GCP Cloud Function event context |
+| `gcp.project.id` | `string` | The ID of the project in GCP that this resource is associated with |
diff --git a/skills/sentry-instrument/references/semantics/gen_ai.md b/skills/sentry-instrument/references/semantics/gen_ai.md
new file mode 100644
index 0000000..9a7c888
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/gen_ai.md
@@ -0,0 +1,54 @@
+# gen_ai attributes
+
+Stable Sentry semantic convention attributes for `gen_ai`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `gen_ai.agent.name` | `string` | The name of the agent being used. |
+| `gen_ai.context.utilization` | `double` | The fraction of the model context window utilized by this generation. |
+| `gen_ai.context.window_size` | `integer` | The maximum context window size supported by the model for this generation. |
+| `gen_ai.conversation.id` | `string` | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. |
+| `gen_ai.cost.cache_creation.input_tokens` | `double` | The cost of input tokens written to cache in USD. |
+| `gen_ai.cost.cache_read.input_tokens` | `double` | The cost of cached input tokens in USD. |
+| `gen_ai.cost.input_tokens` | `double` | The total cost of all input tokens in USD (includes cached and cache creation tokens). |
+| `gen_ai.cost.output_tokens` | `double` | The total cost of all output tokens in USD (includes reasoning tokens). |
+| `gen_ai.cost.reasoning.output_tokens` | `double` | The cost of reasoning output tokens in USD. |
+| `gen_ai.cost.total_tokens` | `double` | The total cost for the tokens used. |
+| `gen_ai.embeddings.input` | `string` | The input to the embeddings model. |
+| `gen_ai.function_id` | `string` | Framework-specific tracing label for the execution of a function or other unit of execution in a generative AI system. |
+| `gen_ai.input.messages` | `string` | The messages passed to the model. It has to be a stringified version of an array of objects. The `role` attribute of each object must be `"user"`, `"assistant"`, `"tool"`, or `"system"`. For messages of the role `"tool"`, the `content` can be a string or an arbitrary object with information about the tool call. For other messages the `content` can be either a string or a list of objects in the format `{type: "text", text:"..."}`. |
+| `gen_ai.operation.name` | `string` | The name of the operation being performed. It has the following list of well-known values: 'chat', 'create_agent', 'embeddings', 'execute_tool', 'generate_content', 'invoke_agent', 'text_completion'. If one of them applies, then that value MUST be used. Otherwise a custom value MAY be used. |
+| `gen_ai.operation.type` | `string` | The type of AI operation. Must be one of 'agent' (invoke_agent and create_agent spans), 'ai_client' (any LLM call), 'tool' (execute_tool spans), 'handoff' (handoff spans), 'other' (input and output processors, skill loading, guardrails etc.) . Added during ingestion based on span.op and gen_ai.operation.type. Used to filter and aggregate data in the UI |
+| `gen_ai.output.messages` | `string` | The model's response messages. It has to be a stringified version of an array of message objects, which can include text responses and tool calls. |
+| `gen_ai.pipeline.name` | `string` | Name of the AI pipeline or chain being executed. |
+| `gen_ai.prompt.name` | `string` | The name of the prompt that uniquely identifies it. |
+| `gen_ai.provider.name` | `string` | The Generative AI provider as identified by the client or server instrumentation. |
+| `gen_ai.request.frequency_penalty` | `double` | Used to reduce repetitiveness of generated tokens. The higher the value, the stronger a penalty is applied to previously present tokens, proportional to how many times they have already appeared in the prompt or prior generation. |
+| `gen_ai.request.max_tokens` | `integer` | The maximum number of tokens to generate in the response. |
+| `gen_ai.request.model` | `string` | The model identifier being used for the request. |
+| `gen_ai.request.presence_penalty` | `double` | Used to reduce repetitiveness of generated tokens. Similar to frequency_penalty, except that this penalty is applied equally to all tokens that have already appeared, regardless of their exact frequencies. |
+| `gen_ai.request.reasoning.level` | `string` | The reasoning or thinking effort level requested for a GenAI model. |
+| `gen_ai.request.seed` | `string` | The seed, ideally models given the same seed and same other parameters will produce the exact same output. |
+| `gen_ai.request.stop_sequences` | `string[]` | List of sequences that the model will use to stop generating further tokens. |
+| `gen_ai.request.temperature` | `double` | For an AI model call, the temperature parameter. Temperature essentially means how random the output will be. |
+| `gen_ai.request.top_k` | `integer` | Limits the model to only consider the K most likely next tokens, where K is an integer (e.g., top_k=20 means only the 20 highest probability tokens are considered). |
+| `gen_ai.request.top_p` | `double` | Limits the model to only consider tokens whose cumulative probability mass adds up to p, where p is a float between 0 and 1 (e.g., top_p=0.7 means only tokens that sum up to 70% of the probability mass are considered). |
+| `gen_ai.response.finish_reasons` | `string` | The reason why the model stopped generating. |
+| `gen_ai.response.id` | `string` | Unique identifier for the completion. |
+| `gen_ai.response.model` | `string` | The vendor-specific ID of the model used. |
+| `gen_ai.response.streaming` | `boolean` | Whether or not the AI model call's response was streamed back asynchronously |
+| `gen_ai.response.time_to_first_chunk` | `double` | Time in seconds when the first response content chunk arrived in streaming responses. |
+| `gen_ai.response.tokens_per_second` | `double` | The total output tokens per seconds throughput |
+| `gen_ai.system_instructions` | `string` | The system instructions passed to the model. |
+| `gen_ai.tool.call.arguments` | `string` | The arguments of the tool call. It has to be a stringified version of the arguments to the tool. |
+| `gen_ai.tool.call.result` | `string` | The result of the tool call. It has to be a stringified version of the result of the tool. |
+| `gen_ai.tool.definitions` | `string` | The list of source system tool definitions available to the GenAI agent or model. |
+| `gen_ai.tool.description` | `string` | The description of the tool being used. |
+| `gen_ai.tool.name` | `string` | Name of the tool utilized by the agent. |
+| `gen_ai.usage.cache_creation.input_tokens` | `integer` | The number of tokens written to the cache when processing the AI input (prompt). |
+| `gen_ai.usage.cache_read.input_tokens` | `integer` | The number of cached tokens used to process the AI input (prompt). |
+| `gen_ai.usage.input_tokens` | `integer` | The number of tokens used to process the AI input (prompt) including cached input tokens. |
+| `gen_ai.usage.output_tokens` | `integer` | The number of tokens used for creating the AI output (including reasoning tokens). |
+| `gen_ai.usage.reasoning.output_tokens` | `integer` | The number of tokens used for reasoning to create the AI output. |
+| `gen_ai.usage.total_tokens` | `integer` | The total number of tokens used to process the prompt. (input tokens plus output todkens) |
diff --git a/skills/sentry-instrument/references/semantics/general.md b/skills/sentry-instrument/references/semantics/general.md
new file mode 100644
index 0000000..eeffaef
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/general.md
@@ -0,0 +1,12 @@
+# general attributes
+
+Stable Sentry semantic convention attributes for `general`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `blocked_main_thread` | `boolean` | Whether the main thread was blocked by the span. |
+| `channel` | `string` | The channel name that is being used. |
+| `id` | `string` | A unique identifier for the span. |
+| `previous_route` | `string` | Also used by mobile SDKs to indicate the previous route in the application. |
+| `type` | `string` | More granular type of the operation happening. |
diff --git a/skills/sentry-instrument/references/semantics/graphql.md b/skills/sentry-instrument/references/semantics/graphql.md
new file mode 100644
index 0000000..109a908
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/graphql.md
@@ -0,0 +1,10 @@
+# graphql attributes
+
+Stable Sentry semantic convention attributes for `graphql`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `graphql.document` | `string` | The GraphQL document being executed. |
+| `graphql.operation.name` | `string` | The name of the operation being executed. |
+| `graphql.operation.type` | `string` | The type of the operation being executed. |
diff --git a/skills/sentry-instrument/references/semantics/grpc.md b/skills/sentry-instrument/references/semantics/grpc.md
new file mode 100644
index 0000000..6c3cbae
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/grpc.md
@@ -0,0 +1,20 @@
+# grpc attributes
+
+Stable Sentry semantic convention attributes for `grpc`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `grpc.error.bad_request.field_violations` | `string[]` | The individual field violations from a google.rpc.BadRequest error detail. Each entry is a JSON-encoded object with field, description, reason, and (optional) localized_message keys, mirroring google.rpc.BadRequest.FieldViolation. |
+| `grpc.error.debug_info.detail` | `string` | Additional debugging information, such as a server-side stack trace, from a google.rpc.DebugInfo error detail. SDKs should only send this attribute when sendDefaultPii is enabled or dataCollection is configured accordingly. |
+| `grpc.error.debug_info.stack_entries` | `string[]` | The server-side stack trace entries from a google.rpc.DebugInfo error detail. SDKs should only send this attribute when sendDefaultPii is enabled or dataCollection is configured accordingly. |
+| `grpc.error.error_info.domain` | `string` | The logical grouping to which the gRPC error reason belongs, from the google.rpc.ErrorInfo error detail. |
+| `grpc.error.error_info.metadata.<key>` | `string` | Additional structured metadata attached to a google.rpc.ErrorInfo error detail, with <key> being the metadata key name. SDKs should only send this attribute when sendDefaultPii is enabled or dataCollection is configured accordingly. |
+| `grpc.error.error_info.reason` | `string` | The reason for the gRPC error, as defined by the service that generated it, from the google.rpc.ErrorInfo error detail. |
+| `grpc.error.precondition_failure.violations` | `string[]` | The individual precondition violations from a google.rpc.PreconditionFailure error detail. Each entry is a JSON-encoded object with type, subject, and description keys. SDKs should only send this attribute when sendDefaultPii is enabled or dataCollection is configured accordingly, since violation subjects may identify specific resources or users. |
+| `grpc.error.quota_failure.violations` | `string[]` | The individual quota violations from a google.rpc.QuotaFailure error detail. Each entry is a JSON-encoded object with subject, description, api_service, quota_metric, quota_id, quota_dimensions, quota_value, and (optional) future_quota_value keys, mirroring google.rpc.QuotaFailure.Violation. SDKs should only send this attribute when sendDefaultPii is enabled or dataCollection is configured accordingly, since violation subjects may identify specific resources or users. |
+| `grpc.error.resource_info.description` | `string` | A description of the error that occurred while accessing the resource, from a google.rpc.ResourceInfo error detail. |
+| `grpc.error.resource_info.owner` | `string` | The owner of the resource being accessed (e.g. project or account owning it), from a google.rpc.ResourceInfo error detail. SDKs should only send this attribute when sendDefaultPii is enabled or dataCollection is configured accordingly. |
+| `grpc.error.resource_info.resource_name` | `string` | The name of the resource being accessed, from a google.rpc.ResourceInfo error detail. SDKs should only send this attribute when sendDefaultPii is enabled or dataCollection is configured accordingly. |
+| `grpc.error.resource_info.resource_type` | `string` | The type of resource being accessed, from a google.rpc.ResourceInfo error detail. |
+| `grpc.error.retry_info.retry_delay_ms` | `integer` | How long the client should wait before retrying the gRPC call, in milliseconds, from the google.rpc.RetryInfo error detail. |
diff --git a/skills/sentry-instrument/references/semantics/http.md b/skills/sentry-instrument/references/semantics/http.md
new file mode 100644
index 0000000..2dcd4b0
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/http.md
@@ -0,0 +1,35 @@
+# http attributes
+
+Stable Sentry semantic convention attributes for `http`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `http.decoded_response_content_length` | `integer` | The decoded body size of the response (in bytes). |
+| `http.fragment` | `string` | The fragments present in the URI. Note that this contains the leading # character, while the `url.fragment` attribute does not. |
+| `http.query` | `string` | The query string present in the URL. Note that this contains the leading ? character, while the `url.query` attribute does not. |
+| `http.request.body.data` | `string` | HTTP request body data. Can be given as string or structural data of any format. |
+| `http.request.connect_start` | `double` | The UNIX timestamp representing the time immediately before the user agent starts establishing the connection to the server to retrieve the resource. |
+| `http.request.connection_end` | `double` | The UNIX timestamp representing the time immediately after the browser finishes establishing the connection to the server to retrieve the resource. The timestamp value includes the time interval to establish the transport connection, as well as other time intervals such as TLS handshake and SOCKS authentication. |
+| `http.request.domain_lookup_end` | `double` | The UNIX timestamp representing the time immediately after the browser finishes the domain-name lookup for the resource. |
+| `http.request.domain_lookup_start` | `double` | The UNIX timestamp representing the time immediately before the browser starts the domain name lookup for the resource. |
+| `http.request.fetch_start` | `double` | The UNIX timestamp representing the time immediately before the browser starts to fetch the resource. |
+| `http.request.header.<key>` | `string[]` | HTTP request headers, <key> being the normalized HTTP Header name (lowercase), the value being the header values. |
+| `http.request.method` | `string` | The HTTP method used. |
+| `http.request.redirect_end` | `double` | The UNIX timestamp representing the timestamp immediately after receiving the last byte of the response of the last redirect |
+| `http.request.redirect_start` | `double` | The UNIX timestamp representing the start time of the fetch which that initiates the redirect. |
+| `http.request.request_start` | `double` | The UNIX timestamp representing the time immediately before the browser starts requesting the resource from the server, cache, or local resource. If the transport connection fails and the browser retires the request, the value returned will be the start of the retry request. |
+| `http.request.resend_count` | `integer` | The ordinal number of request resending attempt (for any reason, including redirects). |
+| `http.request.response_end` | `double` | The UNIX timestamp representing the time immediately after the browser receives the last byte of the resource or immediately before the transport connection is closed, whichever comes first. |
+| `http.request.response_start` | `double` | The UNIX timestamp representing the time immediately before the browser starts requesting the resource from the server, cache, or local resource. If the transport connection fails and the browser retires the request, the value returned will be the start of the retry request. |
+| `http.request.same_origin` | `boolean` | Indicates that a URL has the same origin as the current page's origin in the browser. |
+| `http.request.secure_connection_start` | `double` | The UNIX timestamp representing the time immediately before the browser starts the handshake process to secure the current connection. If a secure connection is not used, the property returns zero. |
+| `http.request.time_to_first_byte` | `double` | The time in seconds from the browser's timeorigin to when the first byte of the request's response was received. See https://web.dev/articles/ttfb#measure-resource-requests |
+| `http.request.worker_start` | `double` | The UNIX timestamp representing the timestamp immediately before dispatching the FetchEvent if a Service Worker thread is already running, or immediately before starting the Service Worker thread if it is not already running. |
+| `http.response.body.size` | `integer` | The encoded body size of the response (in bytes). |
+| `http.response.header.<key>` | `string[]` | HTTP response headers, <key> being the normalized HTTP Header name (lowercase), the value being the header values. |
+| `http.response.header.content-length` | `string` | The size of the message body sent to the recipient (in bytes) |
+| `http.response.size` | `integer` | The transfer size of the response (in bytes). |
+| `http.response.status_code` | `integer` | The status code of the HTTP response. |
+| `http.route` | `string` | The matched route, that is, the path template in the format used by the respective server framework. |
+| `http.server.request.time_in_queue` | `double` | The time in milliseconds the request spent in the server queue before processing began. Measured from the X-Request-Start header set by reverse proxies (e.g., Nginx, HAProxy, Heroku) to when the application started handling the request. |
diff --git a/skills/sentry-instrument/references/semantics/jsonrpc.md b/skills/sentry-instrument/references/semantics/jsonrpc.md
new file mode 100644
index 0000000..e06ecbb
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/jsonrpc.md
@@ -0,0 +1,9 @@
+# jsonrpc attributes
+
+Stable Sentry semantic convention attributes for `jsonrpc`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `jsonrpc.protocol.version` | `string` | The version of the JSON-RPC protocol used. |
+| `jsonrpc.request.id` | `string` | The JSON-RPC request identifier. Unique within the session. |
diff --git a/skills/sentry-instrument/references/semantics/jvm.md b/skills/sentry-instrument/references/semantics/jvm.md
new file mode 100644
index 0000000..6f41d12
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/jvm.md
@@ -0,0 +1,13 @@
+# jvm attributes
+
+Stable Sentry semantic convention attributes for `jvm`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `jvm.gc.action` | `string` | Name of the garbage collector action. |
+| `jvm.gc.name` | `string` | Name of the garbage collector. |
+| `jvm.memory.pool.name` | `string` | Name of the memory pool. |
+| `jvm.memory.type` | `string` | Name of the memory pool. |
+| `jvm.thread.daemon` | `boolean` | Whether the thread is daemon or not. |
+| `jvm.thread.state` | `string` | State of the thread. |
diff --git a/skills/sentry-instrument/references/semantics/koa.md b/skills/sentry-instrument/references/semantics/koa.md
new file mode 100644
index 0000000..a4e645e
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/koa.md
@@ -0,0 +1,8 @@
+# koa attributes
+
+Stable Sentry semantic convention attributes for `koa`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `koa.type` | `string` | The type of the Koa layer that handled the request. |
diff --git a/skills/sentry-instrument/references/semantics/logger.md b/skills/sentry-instrument/references/semantics/logger.md
new file mode 100644
index 0000000..6ed5fc0
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/logger.md
@@ -0,0 +1,8 @@
+# logger attributes
+
+Stable Sentry semantic convention attributes for `logger`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `logger.name` | `string` | The name of the logger that generated this event. |
diff --git a/skills/sentry-instrument/references/semantics/mcp.md b/skills/sentry-instrument/references/semantics/mcp.md
new file mode 100644
index 0000000..9e29da3
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/mcp.md
@@ -0,0 +1,38 @@
+# mcp attributes
+
+Stable Sentry semantic convention attributes for `mcp`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `mcp.cancelled.reason` | `string` | Reason for the cancellation of an MCP operation. |
+| `mcp.cancelled.request_id` | `string` | Request ID of the cancelled MCP operation. |
+| `mcp.client.name` | `string` | Name of the MCP client application. |
+| `mcp.client.title` | `string` | Display title of the MCP client application. |
+| `mcp.client.version` | `string` | Version of the MCP client application. |
+| `mcp.lifecycle.phase` | `string` | Lifecycle phase indicator for MCP operations. |
+| `mcp.logging.data_type` | `string` | Data type of the logged message content. |
+| `mcp.logging.level` | `string` | Log level for MCP logging operations. |
+| `mcp.logging.logger` | `string` | Logger name for MCP logging operations. |
+| `mcp.logging.message` | `string` | Log message content from MCP logging operations. |
+| `mcp.method.name` | `string` | The name of the MCP request or notification method being called. |
+| `mcp.progress.current` | `integer` | Current progress value of an MCP operation. |
+| `mcp.progress.message` | `string` | Progress message describing the current state of an MCP operation. |
+| `mcp.progress.percentage` | `double` | Calculated progress percentage of an MCP operation. Computed from current/total * 100. |
+| `mcp.progress.token` | `string` | Token for tracking progress of an MCP operation. |
+| `mcp.progress.total` | `integer` | Total progress target value of an MCP operation. |
+| `mcp.prompt.result.description` | `string` | Description of the prompt result. |
+| `mcp.prompt.result.message_content` | `string` | Content of the message in the prompt result. Used for single message results only. |
+| `mcp.prompt.result.message_count` | `integer` | Number of messages in the prompt result. |
+| `mcp.prompt.result.message_role` | `string` | Role of the message in the prompt result. Used for single message results only. |
+| `mcp.protocol.ready` | `integer` | Protocol readiness indicator for MCP session. Non-zero value indicates the protocol is ready. |
+| `mcp.protocol.version` | `string` | MCP protocol version used in the session. |
+| `mcp.request.argument.<key>` | `string` | MCP request argument with dynamic key suffix. The <key> is replaced with the actual argument name. The value is a JSON-stringified representation of the argument value. |
+| `mcp.request.argument.name` | `string` | Name argument from prompts/get MCP request. |
+| `mcp.request.argument.uri` | `string` | URI argument from resources/read MCP request. |
+| `mcp.resource.uri` | `string` | The resource URI being accessed in an MCP operation. |
+| `mcp.server.name` | `string` | Name of the MCP server application. |
+| `mcp.server.title` | `string` | Display title of the MCP server application. |
+| `mcp.server.version` | `string` | Version of the MCP server application. |
+| `mcp.session.id` | `string` | Identifier for the MCP session. |
+| `mcp.tool.result.content_count` | `integer` | Number of content items in the tool result. |
diff --git a/skills/sentry-instrument/references/semantics/mdc.md b/skills/sentry-instrument/references/semantics/mdc.md
new file mode 100644
index 0000000..022a145
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/mdc.md
@@ -0,0 +1,8 @@
+# mdc attributes
+
+Stable Sentry semantic convention attributes for `mdc`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `mdc.<key>` | `string` | Attributes from the Mapped Diagnostic Context (MDC) present at the moment the log record was created. The MDC is supported by all the most popular logging solutions in the Java ecosystem, and it's usually implemented as a thread-local map that stores context for e.g. a specific request. |
diff --git a/skills/sentry-instrument/references/semantics/messaging.md b/skills/sentry-instrument/references/semantics/messaging.md
new file mode 100644
index 0000000..c268201
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/messaging.md
@@ -0,0 +1,24 @@
+# messaging attributes
+
+Stable Sentry semantic convention attributes for `messaging`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `messaging.batch.message_count` | `integer` | The number of messages sent, received, or processed in the scope of the batching operation. |
+| `messaging.destination.connection` | `string` | The message destination connection. |
+| `messaging.destination.name` | `string` | The message destination name. |
+| `messaging.destination.partition.id` | `string` | The identifier of the partition messages are sent to or received from, unique within the messaging.destination.name. |
+| `messaging.kafka.message.key` | `string` | Message keys in Kafka are used for grouping alike messages to ensure they're processed on the same partition. They differ from messaging.message.id in that they're not unique. If the key is null, the attribute MUST NOT be set. |
+| `messaging.kafka.message.tombstone` | `boolean` | A boolean that is true if the message is a tombstone. |
+| `messaging.kafka.offset` | `integer` | The offset of a record in the corresponding Kafka partition. |
+| `messaging.message.body.size` | `integer` | The size of the message body in bytes. |
+| `messaging.message.conversation_id` | `string` | The conversation ID identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". |
+| `messaging.message.envelope.size` | `integer` | The size of the message body and metadata in bytes. |
+| `messaging.message.id` | `string` | A value used by the messaging system as an identifier for the message, represented as a string. |
+| `messaging.message.receive.latency` | `integer` | The latency between when the message was published and received. |
+| `messaging.message.retry.count` | `integer` | The amount of attempts to send the message. |
+| `messaging.operation.name` | `string` | The name of the messaging operation being performed |
+| `messaging.operation.type` | `string` | A string identifying the type of the messaging operation |
+| `messaging.rabbitmq.destination.routing_key` | `string` | RabbitMQ message routing key. |
+| `messaging.system` | `string` | The messaging system as identified by the client instrumentation. |
diff --git a/skills/sentry-instrument/references/semantics/middleware.md b/skills/sentry-instrument/references/semantics/middleware.md
new file mode 100644
index 0000000..db6b37c
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/middleware.md
@@ -0,0 +1,8 @@
+# middleware attributes
+
+Stable Sentry semantic convention attributes for `middleware`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `middleware.name` | `string` | The name of the middleware. |
diff --git a/skills/sentry-instrument/references/semantics/navigation.md b/skills/sentry-instrument/references/semantics/navigation.md
new file mode 100644
index 0000000..a539879
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/navigation.md
@@ -0,0 +1,10 @@
+# navigation attributes
+
+Stable Sentry semantic convention attributes for `navigation`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `navigation.origin` | `string` | The origin of the navigation (usually client side router navigations). Should preferrably parameterized template (like url.template) or a URL path otherwise. |
+| `navigation.route.id` | `string` | The identifier of the matched client-side route, as assigned by the routing framework (e.g., vue-router name, react-router id). |
+| `navigation.type` | `string` | The type of navigation done by a client-side router. |
diff --git a/skills/sentry-instrument/references/semantics/nel.md b/skills/sentry-instrument/references/semantics/nel.md
new file mode 100644
index 0000000..66be602
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/nel.md
@@ -0,0 +1,12 @@
+# nel attributes
+
+Stable Sentry semantic convention attributes for `nel`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `nel.elapsed_time` | `integer` | The elapsed number of milliseconds between the start of the resource fetch and when it was completed or aborted by the user agent. |
+| `nel.phase` | `string` | If request failed, the phase of its network error. If request succeeded, "application". |
+| `nel.referrer` | `string` | request's referrer, as determined by the referrer policy associated with its client. |
+| `nel.sampling_function` | `double` | The sampling function used to determine if the request should be sampled. |
+| `nel.type` | `string` | If request failed, the type of its network error. If request succeeded, "ok". |
diff --git a/skills/sentry-instrument/references/semantics/network.md b/skills/sentry-instrument/references/semantics/network.md
new file mode 100644
index 0000000..73eab85
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/network.md
@@ -0,0 +1,18 @@
+# network attributes
+
+Stable Sentry semantic convention attributes for `network`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `network.connection.effective_type` | `string` | Specifies the effective type of the current connection (e.g. slow-2g, 2g, 3g, 4g). |
+| `network.connection.rtt` | `integer` | Specifies the estimated effective round-trip time of the current connection, in milliseconds. |
+| `network.connection.type` | `string` | Specifies the type of the current connection (e.g. wifi, ethernet, cellular , etc). |
+| `network.local.address` | `string` | Local address of the network connection - IP address or Unix domain socket name. |
+| `network.local.port` | `integer` | Local port number of the network connection. |
+| `network.peer.address` | `string` | Peer address of the network connection - IP address or Unix domain socket name. |
+| `network.peer.port` | `integer` | Peer port number of the network connection. |
+| `network.protocol.name` | `string` | OSI application layer or non-OSI equivalent. |
+| `network.protocol.version` | `string` | The actual version of the protocol used for network communication. |
+| `network.transport` | `string` | OSI transport layer or inter-process communication method. |
+| `network.type` | `string` | OSI network layer or non-OSI equivalent. |
diff --git a/skills/sentry-instrument/references/semantics/os.md b/skills/sentry-instrument/references/semantics/os.md
new file mode 100644
index 0000000..07bd611
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/os.md
@@ -0,0 +1,16 @@
+# os attributes
+
+Stable Sentry semantic convention attributes for `os`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `os.build_id` | `string` | The build ID of the operating system. |
+| `os.description` | `string` | Human readable (not intended to be parsed) OS version information, like e.g. reported by ver or lsb_release -a commands. |
+| `os.kernel_version` | `string` | An independent kernel version string. Typically the entire output of the `uname` syscall. |
+| `os.name` | `string` | Human readable operating system name. |
+| `os.raw_description` | `string` | An unprocessed description string obtained by the operating system. For some well-known runtimes, Sentry will attempt to parse `name` and `version` from this string, if they are not explicitly given. |
+| `os.rooted` | `boolean` | Whether the operating system has been jailbroken or rooted. |
+| `os.theme` | `string` | Whether the OS runs in dark mode or light mode. |
+| `os.type` | `string` | The operating system type. |
+| `os.version` | `string` | The version of the operating system. |
diff --git a/skills/sentry-instrument/references/semantics/otel.md b/skills/sentry-instrument/references/semantics/otel.md
new file mode 100644
index 0000000..a240cc3
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/otel.md
@@ -0,0 +1,11 @@
+# otel attributes
+
+Stable Sentry semantic convention attributes for `otel`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `otel.scope.name` | `string` | The name of the instrumentation scope - (InstrumentationScope.Name in OTLP). |
+| `otel.scope.version` | `string` | The version of the instrumentation scope - (InstrumentationScope.Version in OTLP). |
+| `otel.status_code` | `string` | Name of the code, either “OK” or “ERROR”. MUST NOT be set if the status code is UNSET. |
+| `otel.status_description` | `string` | Description of the Status if it has a value, otherwise not set. |
diff --git a/skills/sentry-instrument/references/semantics/params.md b/skills/sentry-instrument/references/semantics/params.md
new file mode 100644
index 0000000..8d8154a
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/params.md
@@ -0,0 +1,8 @@
+# params attributes
+
+Stable Sentry semantic convention attributes for `params`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `params.<key>` | `string` | Decoded parameters extracted from a URL path. Usually added by client-side routing frameworks like vue-router. |
diff --git a/skills/sentry-instrument/references/semantics/process.md b/skills/sentry-instrument/references/semantics/process.md
new file mode 100644
index 0000000..ae31a80
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/process.md
@@ -0,0 +1,15 @@
+# process attributes
+
+Stable Sentry semantic convention attributes for `process`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `process.command_args` | `string[]` | All the command arguments (including the command/executable itself) as received by the process. |
+| `process.executable.name` | `string` | The name of the executable that started the process. |
+| `process.pid` | `integer` | The process ID of the running process. |
+| `process.runtime.description` | `string` | An additional description about the runtime of the process, for example a specific vendor customization of the runtime environment. Equivalent to `raw_description` in the Sentry runtime context. |
+| `process.runtime.engine.name` | `string` | The name of the runtime engine. |
+| `process.runtime.engine.version` | `string` | The version of the runtime engine. |
+| `process.runtime.name` | `string` | The name of the runtime. Equivalent to `name` in the Sentry runtime context. |
+| `process.runtime.version` | `string` | The version of the runtime of this process, as returned by the runtime without modification. Equivalent to `version` in the Sentry runtime context. |
diff --git a/skills/sentry-instrument/references/semantics/react.md b/skills/sentry-instrument/references/semantics/react.md
new file mode 100644
index 0000000..314ec07
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/react.md
@@ -0,0 +1,8 @@
+# react attributes
+
+Stable Sentry semantic convention attributes for `react`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `react.version` | `string` | The version of the React framework |
diff --git a/skills/sentry-instrument/references/semantics/remix.md b/skills/sentry-instrument/references/semantics/remix.md
new file mode 100644
index 0000000..31d8080
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/remix.md
@@ -0,0 +1,8 @@
+# remix attributes
+
+Stable Sentry semantic convention attributes for `remix`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `remix.action_form_data.<key>` | `string` | Remix form data, <key> being the form data key, the value being the form data value. |
diff --git a/skills/sentry-instrument/references/semantics/resource.md b/skills/sentry-instrument/references/semantics/resource.md
new file mode 100644
index 0000000..d3e1deb
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/resource.md
@@ -0,0 +1,8 @@
+# resource attributes
+
+Stable Sentry semantic convention attributes for `resource`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `resource.render_blocking_status` | `string` | The render blocking status of the resource. |
diff --git a/skills/sentry-instrument/references/semantics/rpc.md b/skills/sentry-instrument/references/semantics/rpc.md
new file mode 100644
index 0000000..275bc59
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/rpc.md
@@ -0,0 +1,11 @@
+# rpc attributes
+
+Stable Sentry semantic convention attributes for `rpc`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `rpc.method` | `string` | The fully-qualified logical name of the method from the RPC interface perspective. |
+| `rpc.response.status_code` | `string` | Status code of the RPC returned by the RPC server or generated by the client. |
+| `rpc.service` | `string` | The full (logical) name of the service being called, including its package name, if applicable. |
+| `rpc.system.name` | `string` | A string identifying the remoting system. |
diff --git a/skills/sentry-instrument/references/semantics/score.md b/skills/sentry-instrument/references/semantics/score.md
new file mode 100644
index 0000000..3d26441
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/score.md
@@ -0,0 +1,11 @@
+# score attributes
+
+Stable Sentry semantic convention attributes for `score`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `score.<key>` | `double` | The weighted performance score for a web vital. This is defined as `score.weight.<key>` * `score.ratio.<key>`. |
+| `score.ratio.<key>` | `double` | The score for a web vital, normalized to a number between 0 and 1. |
+| `score.total` | `double` | The total performance score of a span. This is the sum of individual weighted web vital scores (see `score.<key>`). |
+| `score.weight.<key>` | `double` | The relative weight of a web vital in a span's performance score. |
diff --git a/skills/sentry-instrument/references/semantics/sentry.md b/skills/sentry-instrument/references/semantics/sentry.md
new file mode 100644
index 0000000..6112e80
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/sentry.md
@@ -0,0 +1,70 @@
+# sentry attributes
+
+Stable Sentry semantic convention attributes for `sentry`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `sentry.action` | `string` | Used as a generic attribute representing the action depending on the type of span. For instance, this is the database query operation for DB spans, and the request method for HTTP spans. |
+| `sentry.cancellation_reason` | `string` | The reason why a span ended early. |
+| `sentry.category` | `string` | The high-level category of a span, derived from the span operation or span attributes. This categorizes spans by their general purpose (e.g., database, HTTP, UI). Known values include: 'ai', 'ai.pipeline', 'app', 'browser', 'cache', 'console', 'db', 'event', 'file', 'function.aws', 'function.azure', 'function.gcp', 'function.nextjs', 'function.remix', 'graphql', 'grpc', 'http', 'measure', 'middleware', 'navigation', 'pageload', 'queue', 'resource', 'rpc', 'serialize', 'subprocess', 'template', 'topic', 'ui', 'ui.angular', 'ui.ember', 'ui.react', 'ui.svelte', 'ui.vue', 'view', 'websocket'. |
+| `sentry.client_sample_rate` | `double` | Rate at which a span was sampled in the SDK. |
+| `sentry.description` | `string` | The human-readable description of a span. |
+| `sentry.dist` | `string` | The sentry dist. |
+| `sentry.domain` | `string` | Used as a generic attribute representing the domain depending on the type of span. For instance, this is the collection/table name for database spans, and the server address for HTTP spans. |
+| `sentry.dsc.environment` | `string` | The environment from the dynamic sampling context. |
+| `sentry.dsc.project_id` | `string` | The ID of the project where the trace originated (i.e. the project of the SDK that started the trace). Propagated through the dynamic sampling context and set by Relay during ingestion. |
+| `sentry.dsc.public_key` | `string` | The public key from the dynamic sampling context. |
+| `sentry.dsc.release` | `string` | The release identifier from the dynamic sampling context. |
+| `sentry.dsc.sample_rate` | `string` | The sample rate from the dynamic sampling context. |
+| `sentry.dsc.sampled` | `boolean` | Whether the event was sampled according to the dynamic sampling context. |
+| `sentry.dsc.trace_id` | `string` | The trace ID from the dynamic sampling context. |
+| `sentry.dsc.transaction` | `string` | The transaction name from the dynamic sampling context. |
+| `sentry.environment` | `string` | The sentry environment. |
+| `sentry.event.serialized_breadcrumbs` | `string` | JSON-serialized `breadcrumbs` property from a Sentry event. |
+| `sentry.event.serialized_contexts` | `string` | JSON-serialized `contexts` property from a Sentry event. |
+| `sentry.event.serialized_extra` | `string` | JSON-serialized `extra` property from a Sentry event. |
+| `sentry.event.serialized_meta` | `string` | JSON-serialized `_meta` for the `sentry.event.serialized_*` properties from a Sentry event. |
+| `sentry.exclusive_time` | `double` | The exclusive time duration of the span in milliseconds. |
+| `sentry.graphql.operation` | `string` | Indicates the type of graphql operation, emitted by the Javascript SDK. |
+| `sentry.group` | `string` | Stores the hash of `sentry.normalized_description`. This is primarily used for grouping spans in the product end. |
+| `sentry.http.prefetch` | `boolean` | If an http request was a prefetch request. |
+| `sentry.idle_span_finish_reason` | `string` | The reason why an idle span ended early. |
+| `sentry.is_remote` | `boolean` | Indicates whether a span's parent is remote. |
+| `sentry.kind` | `string` | Used to clarify the relationship between parents and children, or to distinguish between spans, e.g. a `server` and `client` span with the same name. |
+| `sentry.main_thread` | `boolean` | Whether the span or event occurred on the main thread. Computed by Relay and should not be set by SDKs. |
+| `sentry.message.parameter.<key>` | `string` | A parameter used in the message template. <key> can either be the number that represent the parameter's position in the template string (sentry.message.parameter.0, sentry.message.parameter.1, etc) or the parameter's name (sentry.message.parameter.item_id, sentry.message.parameter.user_id, etc) |
+| `sentry.message.template` | `string` | The parameterized template string. |
+| `sentry.metric.source` | `string` | The provenance of a metric.  For example, this can be set to indicate if a metric was generated by Relay from a span. |
+| `sentry.mobile` | `boolean` | Whether the application is using a mobile SDK. Computed by Relay and should not be set by SDKs. |
+| `sentry.module.<key>` | `string` | A module that was loaded in the process. The key is the name of the module. |
+| `sentry.nextjs.ssr.function.route` | `string` | A parameterized route for a function in Next.js that contributes to Server-Side Rendering. Should be present on spans that track such functions when the file location of the function is known. |
+| `sentry.nextjs.ssr.function.type` | `string` | A descriptor for a for a function in Next.js that contributes to Server-Side Rendering. Should be present on spans that track such functions. |
+| `sentry.normalized_db_query` | `string` | The normalized version of `db.query.text`. |
+| `sentry.normalized_db_query.hash` | `string` | The hash of `sentry.normalized_db_query`. |
+| `sentry.normalized_description` | `string` | Used as a generic attribute representing the normalized `sentry.description`. This refers to the legacy use case of `sentry.description` where it holds relevant data depending on the type of span (e.g. database query, resource url, http request description, etc). |
+| `sentry.observed_timestamp_nanos` | `string` | The timestamp at which an envelope was received by Relay, in nanoseconds. |
+| `sentry.op` | `string` | The operation of a span. |
+| `sentry.origin` | `string` | The origin of the instrumentation (e.g. span, log, etc.) |
+| `sentry.pageload.span_id` | `string` | The id of the pageload span, set by web vital spans and metrics |
+| `sentry.platform` | `string` | The sdk platform that generated the event. |
+| `sentry.profile_id` | `string` | The ID of the Sentry profile the span is associated with. This is only meaningful for transaction-based profiling. |
+| `sentry.profiler_id` | `string` | The id of the currently running profiler (continuous profiling) |
+| `sentry.relay.ingress` | `string` | How an item (span, log, &c.) entered Relay. |
+| `sentry.relay.pipeline` | `string` | An internal descriptor of which processing pipeline an item went through in Relay. |
+| `sentry.release` | `string` | The sentry release. |
+| `sentry.replay_id` | `string` | The id of the sentry replay. |
+| `sentry.replay_is_buffering` | `boolean` | A sentinel attribute on log events indicating whether the current Session Replay is being buffered (onErrorSampleRate). |
+| `sentry.sdk.integrations` | `string[]` | A list of names identifying enabled integrations. The list shouldhave all enabled integrations, including default integrations. Defaultintegrations are included because different SDK releases may contain differentdefault integrations. |
+| `sentry.sdk.name` | `string` | The sentry sdk name. |
+| `sentry.sdk.version` | `string` | The sentry sdk version. |
+| `sentry.segment.id` | `string` | The segment ID of a span |
+| `sentry.segment.name` | `string` | The segment name of a span |
+| `sentry.segment.name.source` | `string` | The source of the segment span name. Should only be set on segment spans. Known values are:  `'custom'`, `'url'`, `'route'`, `'component'`, `'view'`, `'task'`. |
+| `sentry.server_sample_rate` | `double` | Rate at which a span was sampled in Relay. |
+| `sentry.status` | `string` | The span's status (either "ok" or "error"). Older SDKs may set this to a more specific error, but this behaviour is deprecated. |
+| `sentry.status.message` | `string` | The from OTLP extracted status message. |
+| `sentry.status_code` | `integer` | The HTTP status code used in Sentry Insights. Typically set by Sentry during ingestion, rather than by clients. |
+| `sentry.timestamp.sequence` | `integer` | A sequencing counter for deterministic ordering of logs or metrics when timestamps share the same integer millisecond. Starts at 0 on SDK initialization, increments by 1 for each captured item, and resets to 0 when the integer millisecond of the current item differs from the previous one. |
+| `sentry.trace.status` | `string` | The segment's status (either "ok" or "error"). Older SDKs may set this to a more specific error, but this behaviour is deprecated. |
+| `sentry.trace_lifecycle` | `string` | Indicates the chosen trace lifecycle mode of the SDK (stream or static) |
diff --git a/skills/sentry-instrument/references/semantics/server.md b/skills/sentry-instrument/references/semantics/server.md
new file mode 100644
index 0000000..d40bdeb
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/server.md
@@ -0,0 +1,9 @@
+# server attributes
+
+Stable Sentry semantic convention attributes for `server`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `server.address` | `string` | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. |
+| `server.port` | `integer` | Server port number. |
diff --git a/skills/sentry-instrument/references/semantics/service.md b/skills/sentry-instrument/references/semantics/service.md
new file mode 100644
index 0000000..95211bf
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/service.md
@@ -0,0 +1,9 @@
+# service attributes
+
+Stable Sentry semantic convention attributes for `service`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `service.name` | `string` | Logical name of the service. |
+| `service.version` | `string` | The version string of the service API or implementation. The format is not defined by these conventions. |
diff --git a/skills/sentry-instrument/references/semantics/session.md b/skills/sentry-instrument/references/semantics/session.md
new file mode 100644
index 0000000..309a54b
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/session.md
@@ -0,0 +1,8 @@
+# session attributes
+
+Stable Sentry semantic convention attributes for `session`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `session.id` | `string` | A unique id identifying the active session at the time of setting this attribute |
diff --git a/skills/sentry-instrument/references/semantics/state.md b/skills/sentry-instrument/references/semantics/state.md
new file mode 100644
index 0000000..1022796
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/state.md
@@ -0,0 +1,8 @@
+# state attributes
+
+Stable Sentry semantic convention attributes for `state`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `state.type` | `string` | The type of state management library |
diff --git a/skills/sentry-instrument/references/semantics/thread.md b/skills/sentry-instrument/references/semantics/thread.md
new file mode 100644
index 0000000..19797de
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/thread.md
@@ -0,0 +1,9 @@
+# thread attributes
+
+Stable Sentry semantic convention attributes for `thread`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `thread.id` | `integer` | Current “managed” thread ID. |
+| `thread.name` | `string` | Current thread name. |
diff --git a/skills/sentry-instrument/references/semantics/timber.md b/skills/sentry-instrument/references/semantics/timber.md
new file mode 100644
index 0000000..3fa377f
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/timber.md
@@ -0,0 +1,8 @@
+# timber attributes
+
+Stable Sentry semantic convention attributes for `timber`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `timber.tag` | `string` | The log tag provided by the timber logging framework. |
diff --git a/skills/sentry-instrument/references/semantics/trpc.md b/skills/sentry-instrument/references/semantics/trpc.md
new file mode 100644
index 0000000..adb5fa2
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/trpc.md
@@ -0,0 +1,9 @@
+# trpc attributes
+
+Stable Sentry semantic convention attributes for `trpc`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `trpc.procedure_path` | `string` | The path of the tRPC procedure being called |
+| `trpc.procedure_type` | `string` | The type of the tRPC procedure |
diff --git a/skills/sentry-instrument/references/semantics/ui.md b/skills/sentry-instrument/references/semantics/ui.md
new file mode 100644
index 0000000..da9f583
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/ui.md
@@ -0,0 +1,19 @@
+# ui attributes
+
+Stable Sentry semantic convention attributes for `ui`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `ui.component_name` | `string` | The name of the associated component. |
+| `ui.contributes_to_ttfd` | `boolean` | Whether the span execution contributed to the TTFD (time to fully drawn) metric. |
+| `ui.contributes_to_ttid` | `boolean` | Whether the span execution contributed to the TTID (time to initial display) metric. |
+| `ui.element.height` | `integer` | The height of the UI element (for Html in pixels) |
+| `ui.element.id` | `string` | The id of the UI element |
+| `ui.element.identifier` | `string` | The identifier used to measure the UI element timing |
+| `ui.element.load_time` | `double` | The loading time of a UI element (from time origin to finished loading) |
+| `ui.element.paint_type` | `string` | The type of element paint. Can either be 'image-paint' or 'text-paint' |
+| `ui.element.render_time` | `double` | The rendering time of the UI element (from time origin to finished rendering) |
+| `ui.element.type` | `string` | type of the UI element |
+| `ui.element.url` | `string` | The URL of the UI element (e.g. an img src) |
+| `ui.element.width` | `integer` | The width of the UI element (for HTML in pixels) |
diff --git a/skills/sentry-instrument/references/semantics/url.md b/skills/sentry-instrument/references/semantics/url.md
new file mode 100644
index 0000000..18f5dde
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/url.md
@@ -0,0 +1,16 @@
+# url attributes
+
+Stable Sentry semantic convention attributes for `url`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `url.domain` | `string` | Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. |
+| `url.fragment` | `string` | The fragments present in the URI. Note that this does not contain the leading # character, while the `http.fragment` attribute does. |
+| `url.full` | `string` | The URL of the resource that was fetched. |
+| `url.path` | `string` | The URI path component. |
+| `url.path.parameter.<key>` | `string` | Decoded parameters extracted from a URL path. Usually added by client-side routing frameworks like vue-router. |
+| `url.port` | `integer` | Server port number. |
+| `url.query` | `string` | The query string present in the URL. Note that this does not contain the leading ? character, while the `http.query` attribute does. |
+| `url.scheme` | `string` | The URI scheme component identifying the used protocol. |
+| `url.template` | `string` | The low-cardinality template of an absolute URL path reference. |
diff --git a/skills/sentry-instrument/references/semantics/user.md b/skills/sentry-instrument/references/semantics/user.md
new file mode 100644
index 0000000..eaad015
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/user.md
@@ -0,0 +1,18 @@
+# user attributes
+
+Stable Sentry semantic convention attributes for `user`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `user.email` | `string` | User email address. |
+| `user.full_name` | `string` | User's full name. |
+| `user.geo.city` | `string` | Human readable city name. |
+| `user.geo.country_code` | `string` | Two-letter country code (ISO 3166-1 alpha-2). |
+| `user.geo.region` | `string` | Human readable region name or code. |
+| `user.geo.subdivision` | `string` | Human readable subdivision name. |
+| `user.hash` | `string` | Unique user hash to correlate information for a user in anonymized form. |
+| `user.id` | `string` | Unique identifier of the user. |
+| `user.ip_address` | `string` | The IP address of the user. |
+| `user.name` | `string` | Short name or login/username of the user. |
+| `user.roles` | `string[]` | Array of user roles at the time of the event. |
diff --git a/skills/sentry-instrument/references/semantics/user_agent.md b/skills/sentry-instrument/references/semantics/user_agent.md
new file mode 100644
index 0000000..17229c1
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/user_agent.md
@@ -0,0 +1,8 @@
+# user_agent attributes
+
+Stable Sentry semantic convention attributes for `user_agent`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `user_agent.original` | `string` | Value of the HTTP User-Agent header sent by the client. |
diff --git a/skills/sentry-instrument/references/semantics/vercel.md b/skills/sentry-instrument/references/semantics/vercel.md
new file mode 100644
index 0000000..bca7f92
--- /dev/null
+++ b/skills/sentry-instrument/references/semantics/vercel.md
@@ -0,0 +1,43 @@
+# vercel attributes
+
+Stable Sentry semantic convention attributes for `vercel`.
+Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.
+
+| Key | Type | Brief |
+| --- | --- | --- |
+| `vercel.branch` | `string` | Git branch name for Vercel project |
+| `vercel.build_id` | `string` | Identifier for the Vercel build (only present on build logs) |
+| `vercel.deployment_id` | `string` | Identifier for the Vercel deployment |
+| `vercel.destination` | `string` | Origin of the external content in Vercel (only on external logs) |
+| `vercel.edge_type` | `string` | Type of edge runtime in Vercel |
+| `vercel.entrypoint` | `string` | Entrypoint for the request in Vercel |
+| `vercel.execution_region` | `string` | Region where the request is executed |
+| `vercel.id` | `string` | Unique identifier for the log entry in Vercel |
+| `vercel.ja3_digest` | `string` | JA3 fingerprint digest of Vercel request |
+| `vercel.ja4_digest` | `string` | JA4 fingerprint digest |
+| `vercel.log_type` | `string` | Vercel log output type |
+| `vercel.path` | `string` | Function or dynamic path of the request in Vercel. |
+| `vercel.project_id` | `string` | Identifier for the Vercel project |
+| `vercel.project_name` | `string` | Name of the Vercel project |
+| `vercel.proxy.cache_id` | `string` | Original request ID when request is served from cache |
+| `vercel.proxy.client_ip` | `string` | Client IP address |
+| `vercel.proxy.host` | `string` | Hostname of the request |
+| `vercel.proxy.lambda_region` | `string` | Region where lambda function executed |
+| `vercel.proxy.method` | `string` | HTTP method of the request |
+| `vercel.proxy.path` | `string` | Request path with query parameters |
+| `vercel.proxy.path_type` | `string` | How the request was served based on its path and project configuration |
+| `vercel.proxy.path_type_variant` | `string` | Variant of the path type |
+| `vercel.proxy.referer` | `string` | Referer of the request |
+| `vercel.proxy.region` | `string` | Region where the request is processed |
+| `vercel.proxy.response_byte_size` | `integer` | Size of the response in bytes |
+| `vercel.proxy.scheme` | `string` | Protocol of the request |
+| `vercel.proxy.status_code` | `integer` | HTTP status code of the proxy request |
+| `vercel.proxy.timestamp` | `integer` | Unix timestamp when the proxy request was made |
+| `vercel.proxy.user_agent` | `string[]` | User agent strings of the request |
+| `vercel.proxy.vercel_cache` | `string` | Cache status sent to the browser |
+| `vercel.proxy.vercel_id` | `string` | Vercel-specific identifier |
+| `vercel.proxy.waf_action` | `string` | Action taken by firewall rules |
+| `vercel.proxy.waf_rule_id` | `string` | ID of the firewall rule that matched |
+| `vercel.request_id` | `string` | Identifier of the Vercel request |
+| `vercel.source` | `string` | Origin of the Vercel log (build, edge, lambda, static, external, or firewall) |
+| `vercel.status_code` | `integer` | HTTP status code of the request (-1 means no response returned and the lambda crashed) |
diff --git a/skills/sentry-instrument/scripts/gen-semantics.py b/skills/sentry-instrument/scripts/gen-semantics.py
new file mode 100644
index 0000000..dfb3c1e
--- /dev/null
+++ b/skills/sentry-instrument/scripts/gen-semantics.py
@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Generate sentry-instrument semantics lookup files from published conventions.
+
+Source: https://getsentry.github.io/sentry-conventions/api/attributes.json
+Re-run when conventions bump. Commits the markdown artifacts on purpose (v0).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from collections import defaultdict
+from pathlib import Path
+
+SOURCE_URL = "https://getsentry.github.io/sentry-conventions/api/attributes.json"
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+REFERENCES = SKILL_ROOT / "references"
+OUT_DIR = REFERENCES / "semantics"
+
+
+
+def fetch_attributes() -> list[dict]:
+    with urllib.request.urlopen(SOURCE_URL, timeout=60) as resp:
+        return json.load(resp)
+
+
+def main() -> None:
+    attrs = fetch_attributes()
+    stable = [a for a in attrs if not a.get("deprecated")]
+    by_cat: dict[str, list[dict]] = defaultdict(list)
+    for a in stable:
+        cat = a.get("category") or "general"
+        by_cat[cat].append(a)
+
+    for cat in by_cat:
+        by_cat[cat].sort(key=lambda a: a["key"])
+
+    OUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    # wipe previous domain files so renames/removals don't leave orphans
+    for old in OUT_DIR.glob("*.md"):
+        old.unlink()
+
+    # domain files
+    for cat, items in sorted(by_cat.items()):
+        lines = [
+            f"# {cat} attributes",
+            "",
+            f"Stable Sentry semantic convention attributes for `{cat}`.",
+            "Generated — do not edit by hand. Re-run `scripts/gen-semantics.py`.",
+            "",
+            "| Key | Type | Brief |",
+            "| --- | --- | --- |",
+        ]
+        for a in items:
+            key = a["key"].replace("|", "\\|")
+            typ = str(a.get("type", "")).replace("|", "\\|")
+            brief = str(a.get("brief", "")).replace("|", "\\|").replace("\n", " ")
+            lines.append(f"| `{key}` | `{typ}` | {brief} |")
+        lines.append("")
+        (OUT_DIR / f"{cat}.md").write_text("\n".join(lines), encoding="utf-8")
+
+    print(f"wrote {len(by_cat)} domain files ({len(stable)} stable attrs)")
+
+
+if __name__ == "__main__":
+    main()