@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/scene-expander/scene-blueprint.schema.yaml

@@ -0,0 +1,114 @@
+# Scene Blueprint Schema (v1)
+#
+# Maps the 12 labeled blocks emitted by `scene-expander` to the
+# adapter-contract JSON consumed by every adapter under
+# `scripts/ai-video/adapters/`. Validation lives in
+# `scripts/ai-video/lib/parse-blueprint.sh`.
+#
+# Source format: plain-text, one labeled block per line OR per
+# heading. Labels are case-insensitive; whitespace around `:` is
+# tolerated. Block order is the canonical order below — out-of-order
+# blocks are accepted but logged as a warning.
+#
+# The blueprint is the provider-agnostic intermediate representation:
+# no block may carry one provider's prompt grammar. Per-provider
+# encoding lives in the motion-choreographer skill; the anti-leak
+# test in tests/test_ai_video_blueprint_schema.py scans this schema
+# and the scene-expander skill for provider tokens.
+
+version: 1
+
+blocks:
+  STYLE:
+    required: true
+    target: prompt.style
+    description: "Film stock + decade (live-action) or film title + year (animated)."
+
+  SUBJECT:
+    required: true
+    target: prompt.subject
+    description: "Character read. Verbatim from character.json when locked."
+
+  ENVIRONMENT:
+    required: true
+    target: prompt.environment
+    description: "Location, time-of-day, weather, era; world reaction."
+
+  ACTION:
+    required: true
+    target: prompt.action
+    description: "Anticipation / action / reaction with beat counts."
+
+  CAMERA:
+    required: true
+    target: prompt.camera
+    description: "Position, height, distance, move intent (provider-agnostic vocabulary)."
+
+  LENS:
+    required: true
+    target: prompt.lens
+    description: "Focal length in mm + aperture intent (live-action). Animated runs may emit 'n/a' but the block must be present."
+
+  LIGHTING:
+    required: true
+    target: prompt.lighting
+    description: "Key / fill / back / practical with direction."
+
+  MOOD:
+    required: true
+    target: prompt.mood
+    description: "Single emotional read."
+
+  DIALOGUE:
+    required: false
+    target: audio.dialogue
+    description: "Optional. Marks audio.native requirement when present."
+    null_when_absent: true
+
+  AMBIENT SOUND:
+    required: false
+    target: audio.ambient
+    description: "Optional ambient layer list."
+    null_when_absent: true
+
+  DURATION:
+    required: true
+    target: duration
+    type: number
+    description: "Seconds. Integer or one decimal."
+
+  NEGATIVE:
+    required: true
+    target: negative
+    description: "Clichés to reject, load-bearing top-first."
+
+# Adapter-contract JSON shape produced by parse-blueprint.sh
+output_shape: |
+  {
+    "prompt": {
+      "style": "...",
+      "subject": "...",
+      "environment": "...",
+      "action": "...",
+      "camera": "...",
+      "lens": "...",
+      "lighting": "...",
+      "mood": "..."
+    },
+    "audio": {
+      "dialogue": [...] | null,
+      "ambient": [...] | null,
+      "enable_native_audio": true | false
+    },
+    "duration": 5.0,
+    "negative": ["...", "..."],
+    "requires": {
+      "audio_native": true | false
+    }
+  }
+
+# `enable_native_audio` derives from: DIALOGUE present OR AMBIENT SOUND present.
+# Orchestrator uses `requires.audio_native` to pick an adapter with
+# `audio: native` capability (Phase 4 Step 1). When no native adapter
+# is available the orchestrator routes audio.* to ffmpeg mux at
+# stitch time (Phase 4 Step 7) and clears `enable_native_audio`.

package/dist/agent-src/skills/script-writing/SKILL.md

@@ -0,0 +1,231 @@
+---
+model_tier: medium
+name: script-writing
+description: "Use when adding or editing any script under `scripts/` — `--quiet` flag, `_lib/script_output` helpers, silent Taskfile wiring, Iron-Law carve-outs — even when you just say 'add a check script for X'."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+<!-- cloud_safe: degrade -->
+
+# script-writing
+
+## When to use
+
+* Creating a new Python script in `scripts/{name}.py` (linters, checks, generators, measure tools)
+* Editing an existing script that prints progress or success lines
+* Wiring a script into `Taskfile.yml` or `taskfiles/*.yml`
+* Reviewing a PR that adds scripts and asking "why does this still print on minimal?"
+
+Do NOT use this skill when:
+
+* The content is a one-off / archival under `scripts/ai_council/one_off_archive/` — those carry an `_one_off_` prefix and are exempt from the verbosity convention
+* The content is a shell entrypoint with secret prompts (install-keys, release confirms) → see § 3 Iron-Law carve-outs
+* The content is a `.mjs` / Node script under `scripts/cost/` — different runtime; convention covered in `agents/settings/contexts/cost-tracking.md`
+
+## Script vs other writers — critical test
+
+| Intent | Artifact |
+|---|---|
+| "Maintenance script the agent or CI runs" | **This skill** |
+| "User types `/foo` to invoke" | `command-writing` |
+| "Constraint the agent must always honor" | `rule-writing` |
+| "Reference knowledge agents cite" | `guideline-writing` |
+
+Scripts orchestrate file checks, generators, and validators. They are
+neither user-invoked nor agent-routed — `task` and CI call them.
+
+## Procedure
+
+### 0. Run the Drafting Protocol
+
+Creating or materially rewriting a script that joins the linter / check
+family **must** go through Understand → Research → Draft from the
+[`artifact-drafting-protocol`](../../rules/artifact-drafting-protocol.md) rule.
+
+* **Understand** — what failure does this script catch that no existing
+  check catches? Is it a one-off (then archive it) or evergreen?
+* **Research** — `ls scripts/check_*.py scripts/lint_*.py`, grep for
+  overlap, skim 1–2 peer scripts (e.g. `lint_handoffs.py`,
+  `check_md_language.py`).
+* **Draft** — propose name + one-line purpose first. Only fill the body
+  after the shape is confirmed.
+
+### 1. `--quiet` flag — argparse + sys.argv fallback
+
+Every `check_*.py` / `lint_*.py` script MUST accept `--quiet` so the
+silent Taskfile layer (§ 4) can suppress success-only output.
+
+**With argparse (preferred):**
+
+```python
+parser = argparse.ArgumentParser(...)
+parser.add_argument("--quiet", action="store_true",
+                    help="Only print on failure")
+args = parser.parse_args()
+...
+if not args.quiet:
+    print("✅ All clean")
+```
+
+**Plain script (no argparse) fallback:**
+
+```python
+import sys
+
+QUIET = "--quiet" in sys.argv
+...
+if not QUIET:
+    print("✅ All clean")
+```
+
+Failure output (`❌`, non-zero exit) is **never** gated — failures must
+always print regardless of `--quiet`.
+
+### 2. `_lib/script_output` helpers — preferred for new scripts
+
+For anything richer than a single `✅`/`❌`, import the verbosity-aware
+router instead of raw `print()`:
+
+```python
+from _lib.script_output import info, success, warn, error, flush_summary
+
+info("Loading manifest")          # drops on silent + minimal
+success("Wrote 3 files")          # collected at minimal, printed at verbose
+warn("Skipping stale entry")      # stderr unless silent
+error("Manifest missing")         # stderr always
+
+flush_summary("Done — 3 entries") # one-line summary at minimal
+```
+
+Resolution order (first wins, cached for the process):
+
+1. `AGENT_SCRIPT_VERBOSITY` env (`silent` / `minimal` / `verbose`)
+2. `SCRIPT_OUTPUT_VERBOSE=1` alias (== `verbose`)
+3. `.agent-settings.yml` → `verbosity.script_output`
+4. Default `minimal`
+
+The resolved level is exported back into `AGENT_SCRIPT_VERBOSITY` so
+child processes inherit it. Tests reset via `reset_level()` from the
+same module — see `tests/test_script_output.py`.
+
+### 3. Iron-Law carve-outs — never silenced
+
+The following surfaces **MUST** use plain `print()` and never the
+helpers, so verbosity settings cannot suppress them:
+
+* Release confirms — every task in `taskfiles/release.yml`
+* Secret prompts — `install-anthropic-key`, `install-openai-key`,
+  `setup-evals`, `install-hooks` interactive sections
+* `runtime-e2e` and `test-triggers-live`
+* CI orchestration sentinels — `_ci-start`, `_ci-end`, root `ci`
+* Any prompt that asks the user for confirmation per
+  [`non-destructive-by-default`](../../rules/non-destructive-by-default.md) — Hard Floor cannot be silenced
+
+If unsure, check `scripts/ai_council/one_off_archive/2026-05/_one_off_silent_taskfiles.py`
+`CARVE_OUTS` for the canonical list.
+
+### 4. Taskfile wiring — `silent: true` + `{{.QUIET_FLAG}}`
+
+Every Taskfile task that wraps a `--quiet`-aware script MUST set
+`silent: true` and pass `{{.QUIET_FLAG}}` to the script:
+
+```yaml
+# Per-task in taskfiles/*.yml:
+tasks:
+  lint-handoffs:
+    silent: true
+    cmd: python3 scripts/lint_handoffs.py {{.QUIET_FLAG}}
+```
+
+The `QUIET_FLAG` var is defined once at the root of `Taskfile.yml`
+and resolves to `""` only when `AGENT_SCRIPT_VERBOSITY=verbose`:
+
+```yaml
+# Root Taskfile.yml — already in place, do not duplicate:
+vars:
+  QUIET_FLAG:
+    sh: '[ "$AGENT_SCRIPT_VERBOSITY" = "verbose" ] && echo "" || echo "--quiet"'
+```
+
+Carve-out tasks (release, install secrets, CI orchestration — see § 3)
+do **not** add `silent: true` and do **not** use `{{.QUIET_FLAG}}`.
+
+### 5. Validate
+
+* Run `python3 scripts/skill_linter.py .agent-src.uncondensed/skills/script-writing/SKILL.md` → 0 FAIL
+* Run `python3 scripts/{your-script}.py --quiet` and the verbose path — exit code 0 on clean, non-zero on failure regardless of flag
+* If the script uses `_lib/script_output`, add a test under `tests/` patterned on `tests/test_script_output.py` — assert `silent` / `minimal` / `verbose` behave per § 2
+* Run the full CI pipeline locally (see `Taskfile.yml` in this repo for the script list) — must exit 0 except for tolerated warnings
+
+## Output format
+
+1. Script file at `scripts/{name}.py` with `--quiet` accepted
+2. Taskfile wiring with `silent: true` + `{{.QUIET_FLAG}}` (unless carve-out)
+3. Test under `tests/` if `_lib/script_output` is used
+4. Linter output showing 0 FAIL
+
+## Gotchas
+
+* Forgetting `--quiet` — the silent Taskfile layer wraps the script and the call fails with `unrecognized arguments: --quiet`
+* Gating `❌` failures behind `--quiet` — failures must always print
+* Using raw `print()` for progress lines — drops on `minimal`, no inheritance
+* Adding `silent: true` to a release / install-keys task — bypasses the Hard Floor confirmation
+* Editing `Taskfile.yml`'s `QUIET_FLAG` var — single source of truth, do not duplicate
+* Forgetting that `from _lib.script_output import …` requires the script's resolution to walk up to `scripts/` — copy the `Path(__file__).resolve().parent` pattern from a peer
+
+## Frugality Standards
+
+Apply the [Frugality Charter](../../contexts/contracts/frugality-charter.md)
+to every script you author. Phase 10 of the charter (settings hooks
+row — `verbosity.script_output` / `verbosity.taskfile_command_echo`)
+is what this skill exists to teach.
+
+**Examples in this artifact:**
+- Per the charter's default-terse rule, success lines are gated behind
+  `--quiet` so the only thing visible at `minimal` is the end-of-run
+  summary or a failure.
+- Per the post-action summary suppression, scripts with multi-step
+  output collect via `success()` and emit one `flush_summary()` line.
+- Per the cheap-question check, scripts never prompt unless they hit
+  a Hard Floor surface (§ 3 carve-outs).
+
+**Pre-save self-check:**
+1. Does every `print("✅ ...")` line sit behind `--quiet` / the helper?
+2. Does the script add `silent: true` + `{{.QUIET_FLAG}}` to its
+   Taskfile entry (unless a carve-out)?
+3. Are failure lines (`❌`, exit non-zero) **never** gated by quiet?
+4. Are Iron-Law surfaces using plain `print()` and not the helper?
+
+## Do NOT
+
+* Do NOT gate `❌` / failure output behind `--quiet`
+* Do NOT use `_lib/script_output` for release confirms or secret prompts
+* Do NOT add `silent: true` to carve-out tasks
+* Do NOT hardcode `print()` for progress in new scripts — use `info()`
+* Do NOT skip the Taskfile wiring — without it the verbosity gates leak
+* Do NOT edit `dist/agent-src/`, `.augment/`, or `.claude/` projections
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the package's `task`
+runner and `_lib/script_output` are not reachable. The skill still
+applies — with prose-only validation:
+
+* Emit the full script + Taskfile snippet as copyable Markdown blocks. Do not attempt to write to disk.
+* Self-check: `--quiet` accepted, failures never gated, success lines gated, helper imports look syntactically right.
+* Tell the user to save under `scripts/{name}.py`, wire the Taskfile entry, and run `task lint-skills && task ci` locally before committing.
+* Skip every reference to running the linter or `task` commands yourself — they only run on the user's machine.
+
+## Examples
+
+Good description (trigger-shaped, names domain + symptoms):
+
+> "Use when adding or editing any script under `scripts/` — `--quiet` flag, `_lib/script_output` helpers, silent Taskfile wiring, Iron-Law carve-outs — even when you just say 'add a check script for X'."
+
+Bad description (vague, no trigger):
+
+> "Script conventions"

package/dist/agent-src/skills/secrets-management/SKILL.md

@@ -0,0 +1,148 @@
+---
+model_tier: medium
+name: secrets-management
+description: "Use when picking a secrets store, designing rotation, or wiring scanning gates — multi-cloud (Vault, AWS, Azure, GCP), CI, and Kubernetes — decision framework, provider deep-dives externalized."
+domain: devops
+status: active
+refresh_trigger: "A cited provider deprecates an auth method, OR External Secrets Operator ships a major version with breaking CRD changes, OR ≥30% of cited scanner tools change their gate semantics."
+sunset_criterion: "When provider docs (Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) all converge on a single rotation + scanning standard AND consumer projects no longer cite this skill in PR reviews for two consecutive review cycles."
+recommended_for_user_types: [ops, developer]
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# secrets-management
+
+Decision framework for storing, rotating, and scanning secrets across cloud, CI, and Kubernetes. **Provider deep-dives live upstream** (links in § Provenance) — this skill is the predicate, not the per-vendor cookbook. Sunset-policy compliant.
+
+## When to use
+
+- Designing where a new secret lives (env var, Vault, AWS Secrets Manager, Azure KV, GCP SM, GitHub/GitLab CI, k8s).
+- Reviewing a diff that introduces a credential, API key, signing key, or DB password.
+- Setting up secret rotation for an existing application.
+- Wiring secret-scanning gates into pre-commit, CI, or org-policy.
+
+Do NOT use when:
+
+- The secret is project-AWS-only and `aws-infrastructure` already covers the placement — route there.
+- The work is a security audit of running code — route to [`security-audit`](../security-audit/SKILL.md) or [`threat-modeling`](../threat-modeling/SKILL.md).
+- The decision is which cipher to use for at-rest encryption — read the provider's KMS docs directly.
+
+## Decision framework
+
+### Step 1 — Pick the store
+
+```
+Ephemeral, dev-only, never leaves the laptop  → .env (gitignored). Stop.
+Single-cloud, single-app                       → that cloud's native store
+                                                  (AWS Secrets Manager / Azure Key Vault /
+                                                  GCP Secret Manager).
+Multi-cloud OR on-prem hybrid                  → HashiCorp Vault (or cloud-agnostic equivalent).
+CI-only (deploy keys, signing tokens)          → GitHub/GitLab repo+environment secrets;
+                                                  scope to environment (production/staging).
+Kubernetes workload secrets                    → External Secrets Operator pulling from
+                                                  the canonical store above; never hand-rolled
+                                                  k8s `Secret` objects committed to git.
+Cross-tenant / cross-org shared secret         → don't. Re-architect; shared secrets are an
+                                                  outage and a breach class on their own.
+```
+
+### Step 2 — Pick the access pattern
+
+```
+Application reads at boot                      → fetch once, hold in memory; re-fetch on rotation event.
+Application reads per-request                  → cache with TTL ≤ rotation period / 2.
+Short-lived workload (Lambda, Job)             → fetch per-invocation; rely on platform IAM.
+Long-lived workload                            → leased / dynamic credentials (Vault DB engine,
+                                                  AWS IAM role) — never static creds.
+Human access                                   → no shared logins; per-user identity + audit.
+```
+
+### Step 3 — Define the rotation contract
+
+Every secret MUST have:
+
+- **Owner** — team/person responsible for rotation; tracked in code or runbook.
+- **Period** — calendar trigger (e.g. 90 days for static creds, hours/minutes for dynamic).
+- **Mechanism** — automated (Lambda + Secrets Manager rotation, Vault dynamic secret, IAM role) or documented manual procedure.
+- **Verification** — post-rotation health check; alert if old credential still observed in use after rotation grace window.
+
+Static secrets without a rotation mechanism are a deferred incident — refuse to merge.
+
+### Step 4 — Wire the scanning gates
+
+Three layers, all required:
+
+```
+Pre-commit  → gitleaks / TruffleHog / detect-secrets pre-commit hook.
+CI          → server-side scan on every PR; block merge on high-confidence finding.
+Org policy  → push-protection at the SCM (GitHub Advanced Security secret scanning,
+              GitLab Secret Detection); rotate any leaked secret immediately.
+```
+
+A leaked secret is rotated, not deleted. Git history retention defeats deletion.
+
+### Step 5 — Egress controls
+
+```
+Logs                → mask before write; CI runners must mark secrets as masked.
+Stack traces        → never include secret values; sanitize at the boundary.
+Error responses     → never echo the secret back, even on failure.
+Telemetry / APM     → strip from request/response captures; allowlist headers.
+```
+
+## Procedure: Apply to a new secret
+
+1. **Inspect** the existing secret inventory and IaC for store conventions; run Step 1 and lock the store decision in code/IaC.
+2. Define the access pattern (Step 2); choose static-vs-dynamic explicitly.
+3. Write the rotation contract (Step 3) into the runbook **before** the secret ships.
+4. Verify the three scanning gates (Step 4) cover the repo.
+5. Audit egress paths (Step 5) for the new secret class.
+6. Hand the design to a reviewer; cite this skill.
+
+## Output format
+
+1. Secret-inventory entry: name · store · access-pattern · owner · rotation-period · mechanism.
+2. Scanner-gate matrix: layer · tool · scope · failure mode.
+3. Egress-control checklist with sign-off per category.
+
+## Gotcha
+
+- "We rotate in Secrets Manager" — but the application caches the value forever. Cache TTL must be ≤ rotation grace.
+- External Secrets Operator pulls into a k8s `Secret`; that Secret is base64, **not encrypted**. Threat-model node access accordingly.
+- GitHub environment secrets are NOT available on `pull_request` events from forks — designs that rely on them silently break for external contributors.
+- Vault dynamic creds expire faster than long-running connection pools assume; close + re-acquire on lease near-expiry, don't wait for the failure.
+- Pre-commit scanners fire only when developers install the hook — CI scanners are the load-bearing gate.
+
+## Do NOT
+
+- Do NOT commit a secret, even to a private repo. Rotate any leaked secret; deletion does not work.
+- Do NOT pass secrets via CLI args (`ps` exposes them) — use env or stdin.
+- Do NOT echo secrets in logs, stack traces, error responses, or APM captures.
+- Do NOT hand-roll Kubernetes `Secret` objects committed to git — use External Secrets Operator.
+- Do NOT inline the per-provider cookbooks into this skill — externalize per Sunset Policy.
+
+## Auto-trigger keywords
+
+- secrets management
+- secret rotation
+- vault / aws secrets manager / azure key vault / gcp secret manager
+- external secrets operator
+- secret scanning / gitleaks / trufflehog
+- credential leak
+
+## Provenance
+
+- Adopted from: an external reference (MIT, © 2025 an external reference) — **Sunset Policy applied**: 346-line provider cookbook reduced to a ~140-line decision framework; per-provider deep-dives externalized to upstream docs below.
+- Externalized provider docs:
+  - HashiCorp Vault: https://developer.hashicorp.com/vault/docs · https://developer.hashicorp.com/vault/docs/secrets/databases
+  - AWS Secrets Manager: https://docs.aws.amazon.com/secretsmanager/ · rotation: https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html
+  - Azure Key Vault: https://learn.microsoft.com/en-us/azure/key-vault/general/
+  - GCP Secret Manager: https://cloud.google.com/secret-manager/docs
+  - External Secrets Operator: https://external-secrets.io/
+  - GitHub secret scanning: https://docs.github.com/en/code-security/secret-scanning · gitleaks: https://github.com/gitleaks/gitleaks · TruffleHog: https://github.com/trufflesecurity/trufflehog
+- Cross-linked: [`aws-infrastructure`](../aws-infrastructure/SKILL.md), [`security-audit`](../security-audit/SKILL.md), [`threat-modeling`](../threat-modeling/SKILL.md), [`security`](../security/SKILL.md).
+- Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `secrets-management`).
+- Iron-Law floor: `verify-before-complete`, `skill-quality`, `non-destructive-by-default`.

package/dist/agent-src/skills/sentry-integration/SKILL.md

@@ -0,0 +1,175 @@
+---
+model_tier: medium
+name: sentry-integration
+description: "Use when the user shares a Sentry URL, says \"check Sentry\", or wants to investigate production errors. Uses Sentry MCP tools for deep analysis."
+domain: devops
+workspaces:
+  - engineering
+packs:
+  - engineering-base
+---
+
+# Sentry Skill
+
+## When to use
+
+Use this skill when:
+- Investigating a Sentry error or issue URL
+- Analyzing error patterns, frequency, or affected users
+- Working with Sentry MCP tools for issue details
+- Adding error reporting or breadcrumbs to code
+- Configuring Sentry alerts or release tracking
+
+## Available MCP tools
+
+### Issue investigation
+
+| Tool | Purpose |
+|---|---|
+| `get_issue_details` | Full issue details: stacktrace, tags, metadata |
+| `get_issue_tag_values` | Distribution by tag (browser, URL, environment, user) |
+| `search_issues` | Find issues by criteria (unresolved, critical, etc.) |
+| `search_events` | Count/aggregate events, find individual error logs |
+| `search_issue_events` | Filter events within a specific issue |
+| `analyze_issue_with_seer` | AI root cause analysis with code fix suggestions |
+
+### Context tools
+
+| Tool | Purpose |
+|---|---|
+| `get_trace_details` | Trace overview for performance issues |
+| `get_event_attachment` | Download screenshots, logs attached to events |
+| `find_organizations` | Find org slug (needed for most queries) |
+| `find_projects` | Find project slug |
+| `find_releases` | Check recent releases and deploy timing |
+
+## Procedure: Investigate a Sentry error
+
+### 1. Get issue details
+
+From a Sentry URL:
+```
+get_issue_details(issueUrl='https://sentry.io/issues/PROJECT-123/')
+```
+
+From an issue ID:
+```
+get_issue_details(organizationSlug='my-org', issueId='PROJECT-123')
+```
+
+### 2. Analyze the stacktrace
+
+- **Top frame** = where it crashed
+- **Bottom frame** = entry point (HTTP request, job, command)
+- Read each file in the call chain using `codebase-retrieval`
+- Identify where data becomes invalid or assumptions break
+
+### 3. Check distribution
+
+```
+get_issue_tag_values(issueId='PROJECT-123', tagKey='environment')
+get_issue_tag_values(issueId='PROJECT-123', tagKey='url')
+get_issue_tag_values(issueId='PROJECT-123', tagKey='browser')
+```
+
+Useful tags: `environment`, `url`, `browser`, `os`, `release`, `user`, `device`
+
+### 4. Check frequency and timing
+
+```
+search_events(organizationSlug='my-org', naturalLanguageQuery='count of errors for PROJECT-123 in last 7 days')
+```
+
+### 5. AI analysis (if needed)
+
+```
+analyze_issue_with_seer(issueUrl='https://sentry.io/issues/PROJECT-123/')
+```
+
+Only use when you cannot determine the root cause from the stacktrace alone.
+
+## Error reporting in code
+
+### MonitoringHelper (project convention)
+
+Always use the project's `MonitoringHelper` — never the Sentry SDK directly:
+
+```php
+// ✅ Correct
+MonitoringHelper::captureException($exception);
+
+// ❌ Wrong
+\Sentry\captureException($exception);
+```
+
+### Breadcrumbs
+
+Use project enums for structured breadcrumbs:
+
+```php
+use App\Enums\Sentry\BreadcrumbType;
+use App\Enums\Sentry\BreadcrumbLevel;
+```
+
+### Context
+
+Check the project for Sentry context enums and the tenant switching service that sets context automatically.
+
+## Common error patterns
+
+| Pattern | Root cause | Fix approach |
+|---|---|---|
+| `TypeError: null passed to non-nullable` | Missing null check on optional DB column | Add null guard or make parameter nullable |
+| `ModelNotFoundException` | Deleted or missing related record | Add `optional()` or existence check |
+| `ConnectionException` | Multi-tenant DB switch failed | Check tenant switching service flow |
+| `ValidationException` in jobs | Job data changed between dispatch and execution | Re-validate in `handle()` |
+| `Undefined array key` | External API/import data missing expected field | Add `array_key_exists()` or null coalescing |
+
+## Search patterns
+
+### Find issues by criteria
+
+```
+search_issues(organizationSlug='my-org', naturalLanguageQuery='unresolved errors in production last 24h')
+search_issues(organizationSlug='my-org', naturalLanguageQuery='errors affecting more than 100 users')
+search_issues(organizationSlug='my-org', naturalLanguageQuery='issues assigned to me')
+```
+
+### Count events
+
+```
+search_events(organizationSlug='my-org', naturalLanguageQuery='how many errors today')
+search_events(organizationSlug='my-org', naturalLanguageQuery='count of database failures this week')
+```
+
+## Related
+
+- **Skill:** `logging-monitoring` — full monitoring stack (Sentry + Grafana + Loki)
+- **Skill:** `bug-analyzer` — uses Sentry as input for bug investigation
+- **Command:** `/bug-investigate` — fetches Sentry details automatically
+- **Config:** `config/sentry.php` — Sentry DSN and configuration
+
+
+## Output format
+
+1. Sentry integration code with proper context and breadcrumbs
+2. Error grouping configuration if needed
+
+## Gotcha
+
+- Sentry groups errors by stacktrace — different root → may appear as the same issue. Check multiple events.
+- The model tends to analyze only the latest event — check the "Events" tab for patterns across time.
+- Don't use Sentry MCP tools for simple lookups — use the Sentry web UI link instead (saves tokens).
+
+## Do NOT
+
+- Do NOT use Sentry SDK directly — use MonitoringHelper.
+- Do NOT ignore Sentry errors without investigating root cause.
+- Do NOT expose sensitive data in Sentry error context.
+
+## Auto-trigger keywords
+
+- Sentry
+- error tracking
+- issue investigation
+- error reporting