@ericrisco/rsc 0.1.43 → 0.1.45

package/skills/backups/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: backups
-description: "Use when designing or auditing a backup-and-restore program that must survive a real disaster — picking defensible RPO/RTO targets, building a 3-2-1-1-0 layout, wiring point-in-time recovery, adding offsite+immutable copies, or proving restores actually work. Triggers: 'we have no real backups, design something', 'what RPO/RTO should we target', 'set up PITR for Postgres', 'are our backups any good', the non-obvious 'our backups live on the same server as the database', and Catalan 'com provo que les còpies de seguretat funcionen de debò'. NOT tuning Postgres internals or writing the archive_command (that is postgresdb)."
+description: "Use when designing or auditing a backup-and-restore program that must survive a real disaster: setting defensible RPO/RTO targets, laying out 3-2-1-1-0 copies that are offsite and immutable, wiring point-in-time recovery, and proving restores work on a schedule. NOT tuning Postgres internals or writing the archive_command (that is `postgresdb`)."
 tags: [backups, disaster-recovery, pitr, rpo-rto, restore]
 recommends: [postgresdb, secure-coding, monitoring]
 origin: risco
@@ -128,10 +128,4 @@ The fill-in-the-blank restore runbook, the scheduled-test checklist, and the act
 | Trusting managed snapshots without knowing the ceiling | RDS caps at 35 days; longer needs an exported copy | Know the retention ceiling, export beyond it (§3) |
 | Counting "job succeeded" as success | The job wrote a corrupt/empty archive | `check`/`verify` + a real test restore (§6–7) |
 
-## References
-
-- `references/engine-recipes.md` — copy-paste config and commands per engine: pgBackRest stanza + full/diff + PITR `--type=time`, WAL-G, RDS `restore-db-instance-to-point-in-time`, XtraBackup + binlog, Redis RDB/AOF, restic/Borg against an Object-Lock bucket.
-- `references/restore-runbook.md` — fill-in restore runbook template, the scheduled-restore-test checklist, and the actual-RTO log table.
-- Engine internals (archive_command, VACUUM, migrations): `../postgresdb/SKILL.md`. Encryption-key management as a security control: `../secure-coding/SKILL.md`.
-
 `scripts/verify.sh <path-to-policy-or-runbook>` lints a produced backup-policy/runbook artifact for the five pillars (RPO, RTO, offsite, immutability, scheduled-restore + verification). It is a completeness lint, not a backup executor.

package/skills/bash-scripting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bash-scripting
-description: "Use when writing or hardening a shell script that has to survive another machine — a CI step, install script, build glue, cron job, git hook, or devcontainer entrypoint — and it 'works on my machine' but fails in CI/Docker/macOS, mangles filenames with spaces, leaks temp files when interrupted, or trips ShellCheck. Triggers: 'works locally but breaks in CI', 'filenames with spaces break my loop', 'set -e didn't catch the error', 'unquoted variable ate my path', 'trap fires twice', 'fix these SC2086 warnings', 'make this run on macOS and Linux', 'should this be #!/bin/bash or #!/bin/sh', 'script que peta en CI però funciona al portàtil', 'fes el script portable / hazlo robusto'. NOT CI workflow structure, runners, caching, matrix (that is github-actions)."
+description: "Use when writing or hardening a shell script that must survive another machine — a CI step, install script, cron job, git hook, devcontainer entrypoint: strict-mode leaks, quoting/word-splitting, arrays, trap cleanup, bash-vs-POSIX portability, ShellCheck findings. NOT CI workflow structure, runners, caching or matrix (that is `github-actions`)."
 tags: [bash, shell, shellcheck, posix, scripting]
 recommends: [github-actions, error-handling, docker, secure-coding]
 origin: risco
@@ -47,7 +47,10 @@ is `#!/bin/sh` you may not get bash — on Debian/Alpine `sh` is `dash`/busybox.
 Two traps to internalize: macOS `/bin/bash` is **3.2** (no `declare -A`,
 no `${var,,}`, no `mapfile`); and bash **5.3** added `${ cmd; }` /
 `GLOBSORT` / `read -E` that will not run on either of the above. Pick a floor
-and stay above it. Deep matrix and workarounds: `references/portability.md`.
+and stay above it — the full bash-vs-POSIX feature matrix, `bash 3.2`
+workarounds, dash/busybox gotchas, the 5.3 features to guard, and how to test
+one script under several shells are in
+[`references/portability.md`](references/portability.md).
 
 ## Strict mode, honestly
 
@@ -222,10 +225,3 @@ belongs to `../github-actions/SKILL.md`, the shell inside the step belongs here.
 | `[ a == b ]` under `#!/bin/sh` | `==` is a bashism; dash errors | POSIX uses `[ a = b ]` |
 | Fixed temp path `/tmp/build` | race + collision + no cleanup | `tmp=$(mktemp -d); trap 'rm -rf "$tmp"' EXIT` |
 | `pipefail` in a `#!/bin/sh` script | not POSIX; dash ignores or errors | use bash, or check pipeline status another way |
-
-## References
-
-- `references/portability.md` — the full bash-vs-POSIX feature matrix, macOS
-  `bash 3.2` workarounds (no `declare -A` / `${var,,}` / `mapfile` — portable
-  equivalents), dash/busybox gotchas, the bash 5.3 feature list to guard or
-  avoid, and how to test the same script under multiple shells.

package/skills/bookkeeping/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bookkeeping
-description: "Use when a small business needs clean, audit-ready books — standing up a chart of accounts, recording a transaction and unsure which account or which side (debit vs credit), a bank feed full of uncategorized lines, a month-end ledger that won't reconcile to the bank, or choosing cash vs accrual. Triggers: 'set up a chart of accounts', 'where does this transaction post', 'which side is a debit when I pay rent', 'my books don't tie out to the bank', '300 transactions sitting uncategorized', 'cash or accrual accounting', 'how long do I keep receipts', 'categoriza los movimientos del banco', 'mi contabilidad está hecha un desastre', 'cuadra el libro con el extracto', 'comptabilitat feta un desastre'. The loop is record → classify → reconcile so the numbers are trustworthy. NOT analyzing runway/burn/P&L or the monthly finance cadence (that is finance-ops), NOT issuing a customer invoice (that is invoicing), NOT setting a price (that is pricing), NOT future projections (that is financial-model)."
+description: "Use when a small business needs audit-ready books — a chart of accounts, posting a transaction to the right account and side, clearing an uncategorized bank feed, cash vs accrual, or a ledger that won't tie to the bank. NOT interpreting the numbers — runway, burn, P&L cadence (that is `finance-ops`), NOT issuing invoices (that is `invoicing`)."
 tags: [bookkeeping, double-entry, chart-of-accounts, reconciliation, ledger, accounting, categorization]
 recommends: [finance-ops, invoicing, pricing, financial-model, cost-tracking, stripe, spreadsheet-ops]
 origin: risco
@@ -14,7 +14,7 @@ The whole job is one loop: **Record → Classify → Reconcile.** Record the raw
 
 ## Route out before you start
 
-This skill answers "where does this transaction go and does the ledger balance." When the ask is something else, stop and route:
+"Where does this post and does it balance" is bookkeeping; "what do these numbers mean for the business" is not. Route out when the ask is:
 
 - Interpreting the numbers — runway, burn, P&L review, monthly finance cadence → `../finance-ops/SKILL.md`.
 - Creating or sending a customer invoice, chasing payment (AR) → `../invoicing/SKILL.md`.
@@ -24,8 +24,6 @@ This skill answers "where does this transaction go and does the ledger balance."
 - Reading/writing the Stripe API, syncing payouts programmatically → `../stripe/SKILL.md`.
 - Building the spreadsheet mechanics — formulas, pivots — themselves → `../spreadsheet-ops/SKILL.md`.
 
-Rule of thumb: "where does this post and does it balance" is bookkeeping; "what do these numbers mean for the business" is finance-ops.
-
 ## Rule 1 — every entry balances: debits = credits
 
 Double-entry means each transaction touches at least two accounts, and **total debits equal total credits** — always. The check behind it is the accounting equation, which must hold after every posting:
@@ -176,9 +174,3 @@ Spain (autónomo, estimación directa simplificada): the obligation is **libros
 | Mixing personal and business in one account | Untraceable books, tax and liability exposure | Separate business account; owner draws/capital for transfers |
 | Trusting bank-feed auto-match blindly | Miscategorizes transfers, refunds, draws | Review every match against type/date/amount |
 | Over-splitting the COA into 200 accounts | Every classification becomes a coin flip | Start at ~20–30; merge when you hesitate |
-
-## References
-
-- `references/chart-of-accounts.md` — full numbered example COA across the five categories, contra accounts (accumulated depreciation, allowance for doubtful accounts), add-vs-merge rules, the over-splitting failure mode.
-- `references/reconciliation-playbook.md` — step-by-step month-end reconciliation, the full won't-tie-out diagnostic ladder, and the jurisdiction detail (IRS retention table + Spain libros registro de IVA fields).
-- `references/tricky-transactions.md` — the classification cases that bare judgment gets wrong: transfers, refunds, partial/overpayments, loan & finance splits, payroll decomposition, prepaids & deferrals, accruals, sales tax/VAT collected, merchant-fee netting (Stripe/PayPal gross-vs-net), bad debt, foreign currency, personal/mixed-use — each with the right journal entry and the wrong one it replaces.

package/skills/brand-identity/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brand-identity
-description: "Use when defining a project's visual identity foundation from scratch or consolidating ad-hoc brand assets into one system: a logo brief, a color system, a type system, usage rules, and an exported design-tokens.json that downstream skills consume. Use when there is no visual foundation yet, or a rebrand must unify scattered colors/fonts. Triggers: 'build our brand identity', 'create a brand book / brand guidelines', 'logo brief', 'pick our color palette', 'define our type system', 'consolidate our random fonts and hex codes scattered across files into one system', 'necesito una identidad de marca', 'crea la guia de marca amb les normes d'us del logo'. NOT the applied UI/pixels (that is design), NOT the words/tone (that is brand-voice), NOT a journalist asset pack (that is press-kit)."
+description: "Use when a project needs its visual foundation built or consolidated into one system: logo brief, color system in HEX/RGB/CMYK/OKLCH with proven AA contrast, type system, usage rules, and an exported W3C design-tokens.json that later skills consume. NOT the applied UI pixels (that is design), NOT the words or tone (that is brand-voice)."
 tags: [brand, identity, logo, color, typography]
 recommends: [design, brand-voice, press-kit, presentations]
 origin: risco
@@ -10,46 +10,19 @@ origin: risco
 
 *This skill emits the brand book — logo brief, color system, type system, usage rules — and a machine-readable `design-tokens.json` that `design` consumes. You write the rules every later pixel must obey; you do not paint the live UI.*
 
-A brand identity with nothing checkable behind it is a mood board. The bar here is a **brand book that compiles**: roles named, every color carrying four channels, contrast pairs proven against WCAG, and a tokens file that `scripts/verify.sh` can validate. Hit that bar or it is not done.
+A brand identity with nothing checkable behind it is a mood board. The bar here is a **brand book that compiles**: roles named, every color carrying four channels, contrast pairs proven against WCAG, and a tokens file that `scripts/verify.sh` can validate.
 
-## When to use / When NOT to use
+All four parts ship together — logo brief, color system, type system, usage guidelines with the tokens export. A part missing its bar is incomplete, not "lite".
 
-Use when:
-
-- A new product/company has no visual foundation and needs one defined.
-- A rebrand must consolidate ad-hoc colors, fonts, and one-off logos into a single system.
-- `design` is about to build the site and STOPS because no brand study exists — you produce that study's visual half.
-- The user asks for a logo brief, a palette with documented values, or a type system.
-
-Do NOT use — route instead:
-
-| Request | Route to | Why |
-| --- | --- | --- |
-| "Write our tone of voice, tagline, naming, messaging pillars" | `../brand-voice/SKILL.md` | Verbal identity — the words, not the pixels. |
-| "Make this landing page look premium / pick layout + motion / ship the Tailwind" | `../design/SKILL.md` | The applied UI layer — it consumes this foundation, it is not it. |
-| "Write the hero headline, value prop, CTA copy" | `../marketing/SKILL.md` | Page words, not the visual system. |
-| "Assemble a press kit — boilerplate, logos-for-press, fact sheet" | `../press-kit/SKILL.md` | Media packaging of finished assets, not system definition. |
-| "Build the investor pitch deck visuals" | `../presentations/SKILL.md` | Deck composition, not the brand foundation. |
-
-**The one-line test:** "define what our brand looks like everywhere" → here. "make *this surface* look premium" → `design`.
-
-## The deliverable contract (four parts)
-
-Every brand-identity engagement ships all four. Each has a MUST-contain bar; a part missing its bar is incomplete, not "lite".
-
-1. **Logo brief** — MUST define the variation set (primary / stacked / mark-only / mono), the clear-space rule, minimum sizes, and the file + favicon export matrix. *Why:* a logo that only works in one context is not a system; it breaks the first time someone needs a favicon or a one-color print.
-2. **Color system** — MUST give every color a role (primary / secondary / neutral / accent) and four channels (HEX + RGB + CMYK + OKLCH), document AA contrast pairs, and define light/dark roles. *Why:* HEX alone fails print (no CMYK) and wide-gamut screens (no OKLCH); undocumented contrast ships inaccessible.
-3. **Type system** — MUST name 2–3 typefaces max with a scale, weights, and a one-line pairing rationale. *Why:* more than three families reads as chaos; an undocumented scale gets re-guessed on every screen.
-4. **Usage guidelines** — MUST give do/don't rules, a misuse table, and an exported W3C-format `design-tokens.json`. *Why:* the tokens file is the hand-off contract; without it `design` re-derives your palette by eye and drifts.
+The one-line boundary test: "define what our brand looks like everywhere" → here. "make *this surface* look premium" → `design`.
 
 ## Logo brief
 
 Specify a system, not a single picture. The mark must survive from favicon to billboard, in color and in one ink.
 
-- **Variation set** — primary (horizontal lockup), stacked (vertical, for square/tight slots), mark-only (the symbol alone, for avatars/favicons), monochrome (single-ink: black, white-knockout). A logo that has no mono version fails the moment it lands on a colored background or a fax.
+- **Variation set** — primary (horizontal lockup), stacked (vertical, for square/tight slots), mark-only (the symbol alone, for avatars/favicons), monochrome (single-ink: black, white-knockout). A logo with no mono version fails the moment it lands on a colored background or a fax. Test the mono version first; if it dies in one color, the design is too fragile.
 - **Clear space** — define it relative to the mark, not in fixed px, so it scales: clear space = the cap-height (or x-height of the mark) on all four sides. Nothing intrudes inside it.
 - **Minimum size** — below this, detail collapses. Defaults: 24px wide digital, 10mm wide print for the full lockup; the mark-only may go smaller (favicon).
-- **Color + mono requirement** — every variation must be reproducible in full color AND in a single ink. Test the mono version first; if it dies in one color, the design is too fragile.
 - **File + favicon matrix** — ship the formats below. SVG is the digital primary (scales, tiny); PNG carries transparency; JPEG is print-safe; 72 DPI digital / 300 DPI print.
 
 | Asset | Format | Notes |
@@ -71,8 +44,8 @@ Full variation grid, clear-space/min-size formulas, and the favicon HTML markup
 Assign roles first, values second. A color with no role is decoration waiting to be misused.
 
 - **Role taxonomy** — 2–3 primary (the brand's signature), 2–3 secondary (support), a neutral ramp (text, surfaces, borders), and exactly **one accent** reserved for CTAs/highlights. One accent keeps "click here" unambiguous.
-- **Four channels, every color** — HEX (web), RGB (screen math), CMYK (print), OKLCH (perceptual + wide-gamut). The W3C Design Tokens Color Module (2025.10) supports CSS Color 4 spaces including OKLCH and Display P3, so wide-gamut color lives in the token file natively — author in OKLCH and let HEX be the fallback.
-- **AA contrast pairing rule** — every text-on-background pair you document must clear WCAG 2 AA: **4.5:1 for normal text, 3:1 for large text** (≥18.66px bold or ≥24px). AAA is 7:1 / 4.5:1 — reach for it on body text where you can. Pair colors explicitly ("`fg` on `bg`: 12.4:1 ✓"); do not leave it to chance.
+- **Four channels, every color, no exceptions** — HEX (web), RGB (screen math), CMYK (print), OKLCH (perceptual + wide-gamut). This one is absolute because a HEX-only palette silently breaks the two places nobody tests: print (no CMYK) and wide-gamut screens (no OKLCH). The W3C Design Tokens Color Module (2025.10) supports CSS Color 4 spaces including OKLCH and Display P3, so wide-gamut color lives in the token file natively — author in OKLCH and let HEX be the fallback.
+- **AA contrast pairing** — every text-on-background pair you document clears WCAG 2 AA: **4.5:1 normal text, 3:1 large text** (≥18.66px bold or ≥24px). Not negotiable — it is a conformance threshold, not a taste call, and shipping under it ships an inaccessible product. AAA is 7:1 / 4.5:1 — reach for it on body text where you can. Pair colors explicitly ("`fg` on `bg`: 12.4:1 ✓").
 - **Logo-text exemption caveat** — WCAG 1.4.3 exempts logos and brand-name text from the contrast minimums. But a *typed* sub-brand or tagline that is plain text (not a graphical logo) IS subject to text-contrast rules. Mark logo-only tokens exempt; hold everything else to 4.5:1.
 - **Light/dark roles** — define the role in both schemes from day one (`bg`/`fg` invert, brand stays anchored). Retrofitting dark mode onto a light-only palette produces muddy, low-contrast surfaces.
 
@@ -89,7 +62,7 @@ Two to three typefaces, no more. Most brands need exactly two: one display (head
 
 ## Emit the tokens (the hand-off contract)
 
-The `design-tokens.json` is what makes this skill's output machine-readable and the reason `design` does not re-derive your palette by eye. Use the **W3C Design Tokens format**, which reached its first stable version (2025.10) on 2025-10-28 — a vendor-neutral JSON for sharing design decisions, with light/dark and multi-brand themes via group inheritance / `$extends`.
+Ship `design-tokens.json` even when the client only asked for a PDF — it is the one artifact `design` can read, and without it the palette gets re-derived by eye and drifts. Use the **W3C Design Tokens format**, which reached its first stable version (2025.10) on 2025-10-28 — a vendor-neutral JSON for sharing design decisions, with light/dark and multi-brand themes via group inheritance / `$extends`.
 
 ```json
 {
@@ -126,9 +99,9 @@ Full tokens file with light/dark via `$extends`, the Tailwind v4 `@theme` mappin
 
 ## Usage guidelines + anti-patterns
 
-State the misuse rules explicitly — the gap a brand book exists to close is the well-meaning teammate who stretches the logo to fit. Bad → Good:
+State the misuse rules explicitly — the gap a brand book exists to close is the well-meaning teammate who stretches the logo to fit.
 
-| Rationalization | Reality / Fix |
+| Misuse in the wild | Why it breaks / Fix |
 | --- | --- |
 | "Stretch the logo to fill the space" | Non-uniform scaling distorts the mark. Lock aspect ratio; pick the variation that fits (stacked vs primary). |
 | "This blue is close enough" | Off-palette colors fracture recognition. Use the token; if a need is unmet, add a role, don't eyeball one. |
@@ -151,11 +124,12 @@ The skill emits a checkable artifact, so verify it before claiming done. Run aga
 
 It checks: the file parses as JSON; required color roles are present (primary, neutral, accent at minimum); every color token carries a HEX value; and, for each documented text/background pair (declared via `$extensions["com.risco.contrast"]` pairs), it computes the WCAG relative-luminance contrast ratio and **fails any normal-text pair below 4.5:1**. Logo-only tokens are exempt. On an empty or clean target it exits 0 — no false failures.
 
-## Hand-off
+## Boundary + hand-off
 
-Once the brand book and tokens exist, point the next skill at them:
-
-- `../design/SKILL.md` — **applies** this foundation: reads `design-tokens.json`, builds the accessible, fast UI. This skill produces the brand study's visual half that `design` STOPS without.
-- `../brand-voice/SKILL.md` — owns the **words/tone**; pair it with this so copy and visuals agree.
-- `../press-kit/SKILL.md` — **packages** the finished logos/colors for journalists and media.
-- `../presentations/SKILL.md` — consumes the tokens for on-brand decks.
+| Request | Route to | Why |
+| --- | --- | --- |
+| Tone of voice, tagline, naming, messaging pillars | `../brand-voice/SKILL.md` | Verbal identity — the words, not the pixels. Pair it with this so copy and visuals agree. |
+| Make this page premium, pick layout + motion, ship the Tailwind | `../design/SKILL.md` | The applied UI layer: it reads `design-tokens.json` and builds the accessible, fast UI. This skill produces the brand study's visual half that `design` STOPS without. |
+| Hero headline, value prop, CTA copy | `../marketing/SKILL.md` | Page words, not the visual system. |
+| Press kit — boilerplate, logos-for-press, fact sheet | `../press-kit/SKILL.md` | Media packaging of finished assets, not system definition. |
+| Investor pitch deck visuals | `../presentations/SKILL.md` | Deck composition consuming the tokens, not the brand foundation. |

package/skills/brand-voice/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: brand-voice
-description: "Use when defining or documenting how a brand SOUNDS — turning fuzzy adjectives ('professional but approachable') into voice rules a writer or LLM can actually apply, building a use/avoid word bank, plotting tone on the four dimensions, or producing an AI voice-DNA block so generated copy stays on-brand. Also when content drifts: blog, emails, and support replies read like five different people wrote them. Triggers: 'define our tone of voice', 'we have no brand voice guide', 'turn these adjectives into rules', 'word bank / banned words', 'make ChatGPT write like us', 'our content sounds like AI', 'everything sounds off-brand', 'define el tono de voz de la marca', 'la nostra veu de marca'. NOT writing the actual landing copy (that is landing-copy), the launch email (that is marketing), or the logo/colors (that is brand-identity)."
+description: "Use when defining how a brand SOUNDS as a reusable system: adjectives turned into linguistic rules, four tone dimensions as ratios, a use/avoid word bank, an AI voice-DNA block — so content stops sounding like five different writers. NOT the finished copy written against it (that is `landing-copy` / `marketing`), NOT the brand's look (`brand-identity`)."
 tags: [brand-voice, tone-of-voice, messaging, brand, voice-guide]
 recommends: [landing-copy, brand-identity, marketing, content-engine, customer-support]
 origin: risco
@@ -8,32 +8,9 @@ origin: risco
 
 # Brand Voice — How the Brand Sounds
 
-*The durable definition of how a brand sounds. You write it once; everything downstream writes against it. This skill produces the guide, never the finished piece of copy.*
+You own the **reusable voice-and-tone system**: 3–5 personality traits → concrete linguistic rules → a position on the four tone dimensions → a use/avoid word bank → a tone-by-context matrix → a paste-into-the-prompt voice-DNA block. The output is a persisted document, never a finished piece of copy.
 
-You own the **reusable voice-and-tone system**: 3–5 personality traits → concrete linguistic rules → a position on the four tone dimensions → a use/avoid word bank → a tone-by-context matrix → a paste-into-the-prompt voice-DNA block. The output is a persisted document, not a landing page, email, or article. Those are downstream consumers that *read* this guide.
-
-## When to use / When NOT
-
-Use when:
-
-- A brand has no voice guide, or has one that is just a list of adjectives nobody can apply.
-- Fuzzy adjectives ("bold, warm, expert") must become rules a writer or LLM can follow.
-- Building the word bank: power words to lean on, words/phrases to ban.
-- Specifying how tone shifts by context (error vs. celebration vs. legal) while voice stays constant.
-- Producing the AI voice-DNA block to paste into a system prompt so generated copy stays on-brand.
-- Auditing existing copy for off-brand drift against a defined voice.
-- The drift symptom: "our blog, emails, and support replies all sound like different people."
-
-Do NOT use when (route to the sibling that owns it):
-
-- Writing the hero / value prop / CTA / section copy of a page → `landing-copy`.
-- Writing launch emails, channel posts, or finished marketing pieces → [`../marketing/SKILL.md`](../marketing/SKILL.md), and for blog/article systems → `content-engine`, `article-writing`, `newsletter`, `social-publisher`.
-- Logo, color, type, visual identity, design tokens → `brand-identity`.
-- Visual/UX layout, motion, component look → [`../design/SKILL.md`](../design/SKILL.md).
-- An investor narrative or sales deck → [`../pitch-deck/SKILL.md`](../pitch-deck/SKILL.md).
-- Replying to a live customer ticket in-tone → `customer-support` (it consumes this guide; it does not author it).
-
-The line: **brand-voice owns the reusable definition of how the brand sounds.** The moment you write one finished piece against it, that is a copywriting skill. The way the brand *looks* is `brand-identity`.
+The line: **brand-voice owns the reusable definition of how the brand sounds.** The moment you write one finished piece against it, that is a copywriting skill — page hero/value prop/CTA is `landing-copy`; launch emails and channel posts are [`../marketing/SKILL.md`](../marketing/SKILL.md); blog and article systems are `content-engine`, `article-writing`, `newsletter`, `social-publisher`; an investor narrative is [`../pitch-deck/SKILL.md`](../pitch-deck/SKILL.md); a live customer ticket is `customer-support` (it consumes this guide, it does not author it). The way the brand *looks* — logo, color, type, design tokens — is `brand-identity`, and layout/motion is [`../design/SKILL.md`](../design/SKILL.md).
 
 ## Voice vs. tone (the load-bearing distinction)
 
@@ -150,7 +127,7 @@ Tone by context: onboarding=warm; error=plain+reassuring, no humor;
   success=light warmth, no hype; billing=precise+calm; legal=formal+exact.
 ```
 
-**Persist it.** Write the compiled guide under `02-DOCS/wiki/brand/voice-guide.md` and the voice-DNA block beside it, per the `harness` Karpathy-wiki convention (compiled brand articles under `02-DOCS/wiki/brand/`, raw user inputs under `02-DOCS/raw/brand/`). The persisted file is an OKF v0.1 wiki article: open it with YAML frontmatter carrying a non-empty `type:` (use `type: brand-voice`) — see the frontmatter block in [`references/voice-guide-template.md`](references/voice-guide-template.md). This is the exact study `marketing`, `landing-copy`, and `content-engine` read to ground their copy. A guide in a slide deck is invisible to them.
+**Persist it.** Write the compiled guide under `02-DOCS/wiki/brand/voice-guide.md` and the voice-DNA block beside it, per the `harness` Karpathy-wiki convention (compiled brand articles under `02-DOCS/wiki/brand/`, raw user inputs under `02-DOCS/raw/brand/`). The persisted file is an OKF v0.1 wiki article: open it with YAML frontmatter carrying a non-empty `type:` (use `type: brand-voice`) — see the frontmatter block in [`references/voice-guide-template.md`](references/voice-guide-template.md), which is also the fill-in-the-blanks skeleton for the whole guide (traits → rules → 4-D ratios → word bank → context matrix → voice-DNA block) with one fully worked mini-example brand. This is the exact study `marketing`, `landing-copy`, and `content-engine` read to ground their copy. A guide in a slide deck is invisible to them.
 
 ## Auditing for drift
 
@@ -174,10 +151,6 @@ Off-brand reads like everyone else: abstract nouns, hedged claims, AI tells, ene
 | Guide lives in a deck or someone's head | Downstream skills and LLMs can't read it | Persist machine-readable under `02-DOCS/wiki/brand/` |
 | Writing the actual landing/email/article | That is a finished piece, not the definition | Stop; hand to `landing-copy` / `marketing` / `content-engine` |
 
-## Templates
-
-A fill-in-the-blanks guide (traits → rules → 4-D ratios → word bank → context matrix → voice-DNA block) with one fully worked mini-example brand lives in [`references/voice-guide-template.md`](references/voice-guide-template.md). The universal ban list and power-word derivation method are in [`references/word-bank.md`](references/word-bank.md).
-
 ## Verify
 
 `scripts/verify.sh <guide.md>` is a read-only structural linter for a produced voice guide: it checks the required sections are present (traits, rules with Bad→Good, four-dimension ratios, a non-empty ban list, context matrix, voice-DNA block), flags a trait count outside 3–5, warns on brand-neutral filler used as a trait, and greps the guide's own prose for words it lists in its own ban list (self-consistency). Empty or clean input exits 0 — no false failure.

package/skills/building-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-agents
-description: "Use when designing or building an LLM agent, tool-using system, RAG pipeline, eval harness, or MCP server in this repo — across any provider (OpenAI, Anthropic, Google Gemini, or OSS via OpenAI-compatible endpoints / litellm). Triggers: 'build an agent', 'add tool calling / function calling', 'structured JSON output', 'RAG / retrieval / embeddings / rerank', 'agent loop / ReAct / orchestrator-worker / multi-agent', 'LLM eval / golden set / LLM-as-judge / regression gate', 'prompt caching / model routing / token budget / cost control', 'trace / observability for LLM calls', 'build an MCP server', or 'make our LLM code provider-agnostic / swap models'. FastAPI/Python, Next.js, Go, Flutter, Postgres stacks."
+description: "Use when building or restructuring an LLM agent — provider adapter, tool calling, structured output, RAG, agent loop, eval gate, cost routing, tracing, MCP server — model-agnostic across OpenAI/Anthropic/Gemini/OSS so a model swap is a config change. NOT vector-store SQL alone (that is `postgresdb`) or service deployment (that is `deployment`)."
 tags: [agents, llm, mcp, rag, evals, ai]
 recommends: [secure-coding, deployment]
 origin: risco
@@ -8,65 +8,26 @@ origin: risco
 
 # Building production LLM agents (model-agnostic)
 
-Build production LLM agents that are model-agnostic by construction — a thin provider adapter, a disciplined agent loop, schema-validated tools, provider-neutral RAG, eval gates, OTel tracing, and optionally an MCP server — so swapping OpenAI ↔ Anthropic ↔ Gemini ↔ OSS is a config change, not a rewrite.
+A thin provider adapter, a disciplined agent loop, schema-validated tools, provider-neutral RAG, eval gates, OTel tracing, and optionally an MCP server — so swapping OpenAI ↔ Anthropic ↔ Gemini ↔ OSS is a config change, not a rewrite.
 
 ## The one rule
 
-> Program against a **capability interface**, never a vendor SDK. Vendor specifics (model id, tool-schema shape, JSON mode, caching, token limits) live behind one adapter resolved from config. If a model name or price appears in business logic, it's a bug.
+> Program against a **capability interface**, never a vendor SDK. Vendor specifics (model id, tool-schema shape, JSON mode, caching, token limits) live behind one adapter resolved from config. Model names and prices rot — if one appears in business logic it's a bug, and re-verify the dated tables before quoting a number.
 
-> Model names and prices rot. Never hardcode them in app logic — resolve from config/registry, and re-verify the dated tables before quoting a number.
-
-## When to use / When NOT to use
-
-> **⚠️ SDD new-feature gate — read this first.** If this skill fired on a **new, non-trivial feature or behaviour change** and there is **no approved spec + plan** under `02-DOCS/wiki/sdd/`, STOP — do **not** write feature code yet. Hand off to `../specify/SKILL.md` first: it runs brainstorm → spec → plan → tasks before any code, then routes back here once the plan is approved. Build here directly only for a genuinely one-line / low-risk change. Method: `../sdd/SKILL.md`.
-
-**Use when:** starting any production-bound LLM feature; code is hardwired to one SDK and you want to swap/route/fallback models; adding tools/function calling, structured output, or streaming; standing up RAG over Postgres/`pgvector` or an external store; building an eval harness / CI quality gate; adding tracing, cost tracking, caching, or routing/cascades; building or hardening an MCP server.
-
-**Do NOT use when:**
-
-- One-shot throwaway prompt, no tools, no eval, no production path → just call the SDK directly.
-- Pure prompt-wording improvement with no architecture → that's prompt engineering, not this.
-- Anthropic-SDK-specific tuning (caching internals, thinking, batch) in a file that *only* imports `anthropic` → defer to a dedicated Anthropic-SDK skill if your environment provides one (e.g. `claude-api`); this skill stays multi-provider.
-- Workspace scaffolding (`01-TOOLS`/`02-DOCS` layout) → **`harness`**.
-- Picking *which* coding agent (Claude Code vs Aider) → agent-eval territory, not this.
-- No retrieval, no tools, no loop, no evals at all → you don't need an agent; say so.
+**Hand off instead when:** a new non-trivial feature has no approved spec + plan under `02-DOCS/wiki/sdd/` → stop and run [`specify`](../specify/SKILL.md) first (method: [`sdd`](../sdd/SKILL.md)), which routes back here once the plan is approved; one-line/low-risk changes go straight through. Anthropic-SDK internals (caching, thinking, batch) in a file that *only* imports `anthropic` → `claude-api` if your environment has it, since this skill stays multi-provider. Workspace scaffolding → [`harness`](../harness/SKILL.md). Choosing *which* coding agent to use → agent-eval territory. Pure prompt-wording tuning with no architecture change → prompt engineering, not this. A one-shot throwaway prompt, or no retrieval/tools/loop/evals at all → you don't need an agent; call the SDK directly and say so.
 
 ## Decision rules (read before writing code)
 
 1. **Adapter first** — define the `LLMProvider` Protocol before any provider call.
-2. **Smallest loop that works** — single-agent before multi-agent; ReAct only when the path is uncertain; plan-execute when steps are knowable.
+2. **Smallest loop that works** — single-agent before multi-agent; ReAct only when the path is uncertain; plan-execute when steps are knowable. Multi-agent means orchestrator-worker with a semaphore-bounded parallel fan-out, never a free-for-all.
 3. **Tools are typed contracts** — schema + validation + idempotency key on every side-effecting tool; no catch-all tools.
 4. **Retrieve, don't stuff** — RAG when ground truth lives in data; cite or refuse.
 5. **Eval before ship** — a golden set + regression gate in CI, or it's not production.
 6. **Cheapest model that passes the eval** — route/cascade up, never default to flagship.
 
-## Architecture at a glance
-
-```text
-            ┌───────────────────────────────────────────────────────────┐
-  Caller ──▶│  Agent loop  (perceive → decide → act → observe, bounded) │
-            └───────────────────────────────────────────────────────────┘
-               │              │                │              │
-               ▼              ▼                ▼              ▼
-        ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
-        │  Provider  │  │   Tool     │  │ Retriever  │  │  Tracer    │
-        │  adapter   │  │  registry  │  │ (pgvector) │  │  (OTel)    │
-        │ ↔ OpenAI / │  │ → sandboxed│  │ → cite/    │  │ gen_ai.*   │
-        │ Anthropic /│  │   tools    │  │   refuse   │  │            │
-        │ Gemini /OSS│  └────────────┘  └────────────┘  └────────────┘
-        └────────────┘
-               ▲                                          │
-               └──────────── Eval gate (CI) ◀─────────────┘
-   provider-abstraction.md  agent-loops…/tools-and-rag.md  evals-and-observability.md
-```
-
 ## The provider adapter (the heart of the skill)
 
-The one payload to internalize. Python 3.12+, Pydantic v2, **async** so it composes
-directly with the agent loop in `references/agent-loops-and-harness.md`. Streaming,
-the Gemini and OSS/litellm adapters, tool-result plumbing, and a `route()` registry live
-in `references/provider-abstraction.md` — this excerpt is the load-bearing core, not the
-whole interface.
+The one payload to internalize. Python 3.12+, Pydantic v2, **async** so it composes directly with the bounded loop (and orchestrator-worker fan-out) in [`references/agent-loops-and-harness.md`](references/agent-loops-and-harness.md). Structured output is the quirk that differs most per vendor: strict JSON Schema (OpenAI), tool-forcing (Anthropic), `response_json_schema` (Gemini). Streaming, the Gemini and OSS/litellm adapters, tool-result plumbing, and a `route()` registry live in [`references/provider-abstraction.md`](references/provider-abstraction.md) — this excerpt is the load-bearing core, not the whole interface.
 
 ```python
 from __future__ import annotations
@@ -176,21 +137,7 @@ def get_provider(spec: str | None = None) -> LLMProvider:
 
 ## Good vs Bad
 
-```python
-# BAD — vendor SDK + model id hardwired into a handler; swapping = rewrite every call-site.
-client = OpenAI()
-def summarize(text: str) -> str:
-    r = client.chat.completions.create(model="gpt-5.5", messages=[{"role": "user", "content": text}])
-    return r.choices[0].message.content
-```
-
-```python
-# GOOD — one adapter resolved from config; logic never names a model.
-provider = get_provider(settings.llm)  # e.g. "anthropic:claude-sonnet-4-6"
-async def summarize(text: str) -> str:
-    req = CompletionRequest(model=settings.model_id, messages=[Message(role="user", content=text)])
-    return (await provider.complete(req)).text
-```
+Call-sites use the adapter and never name a model: `provider = get_provider(settings.llm)` (e.g. `"anthropic:claude-sonnet-4-6"`), then `await provider.complete(req)`. The two failures that survive that discipline:
 
 ```python
 # BAD — parse-and-pray; wrong shape fails silently at 3am.
@@ -276,9 +223,10 @@ def dispatch(name: str, raw_args: dict) -> ToolResult:
         return ToolResult(status="error", summary="invalid args", data={"errors": e.errors()},
                           next_actions=["fix the arguments and retry"])
     return handler(args)
-# schema design, sandboxing, idempotency, DI-scoped DB sessions -> references/tools-and-rag.md
 ```
 
+Schema design, sandboxing, idempotency, DI-scoped DB sessions, plus the RAG internals below — chunking, hybrid RRF, rerank, the citation grader, memory — are in [`references/tools-and-rag.md`](references/tools-and-rag.md).
+
 ## RAG in 30 lines (provider-agnostic embeddings)
 
 ```sql
@@ -320,7 +268,6 @@ async def answer(query: str) -> str:
                   Message(role="user", content=f"{context}\n\nQ: {query}")],
     )
     return (await provider.complete(req)).text
-# chunking, hybrid RRF, rerank, citation grader, memory -> references/tools-and-rag.md
 ```
 
 ## Evals & cost gates (the production line)
@@ -355,8 +302,8 @@ async def run_eval(golden_path: str, graders: list, thresholds: dict[str, float]
 ```
 
 Routing cascade in one line: `route(task) → cheapest model whose eval passes; escalate only on a failed self-check`.
-
-Pointer: full runner, judge, CI gate, caching, batching, budgets → `references/evals-and-observability.md`.
+Full runner, judge, CI gate, caching, batching and budgets →
+[`references/evals-and-observability.md`](references/evals-and-observability.md).
 
 ## Observability (OTel GenAI, vendor-neutral)
 
@@ -381,10 +328,10 @@ async def traced_complete(provider: LLMProvider, req: CompletionRequest) -> Comp
 
 ## MCP: when and the smallest server
 
-**Native tools** when the agent and tools share a process/repo. **MCP** when tools must be reused across clients/teams or run out-of-process — accept the MCP cost (schema tokens, transport, ops) in exchange for reuse.
+**Native tools** when the agent and tools share a process/repo. **MCP** when tools must be reused across clients/teams or run out-of-process — accept the MCP cost (schema tokens, transport, ops) in exchange for reuse. TypeScript server, transports, HTTP+auth and testing are in [`references/mcp-servers.md`](references/mcp-servers.md).
 
 ```python
-from fastmcp import FastMCP  # standalone fastmcp 2.x; see references/mcp-servers.md
+from fastmcp import FastMCP  # standalone fastmcp 2.x
 
 mcp = FastMCP("invoices")
 
@@ -406,12 +353,11 @@ def read_invoice(invoice_id: str) -> str:
 if __name__ == "__main__":
     mcp.run()  # stdio transport
 # (MCP spec 2025-11-25; stateless-core RC 2026-07-28; verify before quoting)
-# TypeScript server, transports, HTTP+auth, testing -> references/mcp-servers.md
 ```
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality |
+| Anti-pattern | Reality |
 |---|---|
 | "I'll just call the OpenAI SDK directly, we'll never switch" | The adapter is ~40 lines; retrofitting it across 30 call-sites later is a rewrite. Adapter first. |
 | "JSON output is usually valid, I'll parse it" | "Usually" = pages at 3am. Use strict structured output + schema validation. |
@@ -426,44 +372,15 @@ if __name__ == "__main__":
 | "Tool results just return the raw API blob" | Give the model `status/summary/next_actions`; raw blobs waste context and stall recovery. |
 | "Prompt caching is Anthropic-only so skip caching" | Each provider has its own caching/dedup; abstract it behind the adapter, don't skip it. |
 
-## Quick reference
-
-| Task | Do this | Reference |
-|---|---|---|
-| Define a provider | `LLMProvider` Protocol + normalized request/response | `references/provider-abstraction.md` |
-| Add a tool | Pydantic args model + `ToolResult` + validating dispatcher | `references/tools-and-rag.md` |
-| Structured output | Strict JSON Schema (OpenAI) / tool-forcing (Anthropic) / `response_json_schema` (Gemini) | `references/provider-abstraction.md` |
-| Build the loop | Bounded perceive → decide → act → observe with budgets | `references/agent-loops-and-harness.md` |
-| Multi-agent | Orchestrator-worker + parallel fan-out with a semaphore | `references/agent-loops-and-harness.md` |
-| RAG | `pgvector` ANN + hybrid RRF + rerank + cite | `references/tools-and-rag.md` |
-| Eval gate | Golden set + graders + CI threshold exit code | `references/evals-and-observability.md` |
-| Trace | OTel GenAI `gen_ai.*` spans, swappable exporter | `references/evals-and-observability.md` |
-| Cut cost | Cache + route/cascade + batch + budgets | `references/evals-and-observability.md` |
-| MCP server | FastMCP stdio / Streamable HTTP server | `references/mcp-servers.md` |
-
 ## verify.sh
 
 `scripts/verify.sh` lints example agent code and dry-runs the eval smoke test in **the user's project** — not in this skill repo. It detects each tool (`ruff`, `mypy`, `tsc`/`node`, `go`, the eval entrypoint, `markdownlint`) and skips any that are missing with a yellow WARN; a missing tool never fails the run. Invoke it with `bash scripts/verify.sh` from the project root. Exit 0 means clean (or only skips); a non-zero exit means a real lint/typecheck/vet/eval failure.
 
-## Project grounding (02-DOCS + CLAUDE.md)
-
-When this skill runs in a project with a `02-DOCS/` layer (the
-[`harness`](../harness/SKILL.md) Karpathy wiki), record this
-project's agent decisions there and index them in `02-DOCS/wiki/index.md`, so the next
-agent inherits the conventions instead of re-deriving them.
-
-1. **Find the article** `02-DOCS/wiki/stack/agents.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map index; root `CLAUDE.md` points to it).
-2. **If missing or stale**, create/update it with the project's real choices — the provider(s) and model routing, where the provider adapter lives, tool/RAG conventions, the eval gates, and the observability backend —
-   then index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it). Write it as an OKF v0.1 wiki article per the harness [`wiki-article-template.md`](../harness/references/wiki-article-template.md): open with YAML frontmatter carrying a non-empty `type:` (use `type: stack`), and use standard markdown links — never wikilinks.
-3. **Read it first on every use** and stay consistent; when a convention changes, update the
-   article (bump its `timestamp`) in the same change.
+## Project grounding
 
-No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Unlike the
-brand study, technical conventions are *recorded, not gated* — never block the task on this.
+In a project with a `02-DOCS/` layer ([`harness`](../harness/SKILL.md)), read `02-DOCS/wiki/stack/agents.md` first on every use and stay consistent with it. If it is missing or stale, write this project's real choices there — provider(s) and model routing, where the adapter lives, tool/RAG conventions, eval gates, observability backend — as a `type: stack` article per the harness [`wiki-article-template.md`](../harness/references/wiki-article-template.md), index it in `02-DOCS/wiki/index.md`, and bump its `timestamp` in the same change as any convention change. No `02-DOCS/`? Skip silently — technical conventions here are *recorded, not gated*; never block the task on this.
 
-## See Also
+## See also
 
-- `../harness/SKILL.md` — workspace `01-TOOLS`/`02-DOCS` scaffolding.
-- Stack siblings the examples target: `../fastapi/SKILL.md`, `../nextjs/SKILL.md`, `../go/SKILL.md`, `../postgresdb/SKILL.md`, `../flutter/SKILL.md`; plus `../secure-coding/SKILL.md` and `../deployment/SKILL.md` for hardening and shipping the agent service.
-- External skills (no sibling in this repo; use if your environment provides them): `claude-api` — Anthropic-SDK-specific tuning (caching internals, thinking, batch) when a file only imports `anthropic`; `deep-research` — the research-harness fan-out / verify pattern.
-- ECC analogues (external, no links): `agent-harness-construction`, `eval-harness`, `cost-aware-llm-pipeline`, `mcp-server-patterns`, `context-budget`.
+- Stacks the examples target: [`fastapi`](../fastapi/SKILL.md), [`nextjs`](../nextjs/SKILL.md), [`go`](../go/SKILL.md), [`postgresdb`](../postgresdb/SKILL.md), [`flutter`](../flutter/SKILL.md). Harden with [`secure-coding`](../secure-coding/SKILL.md), ship with [`deployment`](../deployment/SKILL.md).
+- External (no sibling here; use if your environment provides them): `claude-api` for Anthropic-SDK-only tuning, `deep-research` for the research-harness fan-out / verify pattern.

package/skills/business-intelligence/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: business-intelligence
-description: "Use when someone wants to ask business questions over the org's data in plain language and get consistent, trustworthy numbers, when a metric (revenue, MRR, active users, gross margin) must be defined once so every dashboard/report/agent computes it identically, when wiring an LLM or agent to query data without hallucinating SQL, or when two teams report different numbers for the same thing. Triggers: 'semantic layer', 'metrics layer', 'define MRR once', 'self-serve analytics in plain English', 'text-to-SQL but trustworthy', 'sales and finance disagree on revenue', 'the agent keeps hallucinating SQL', 'dbt Semantic Layer', 'MetricFlow', 'Cube', 'capa semántica', 'consultar dades en llenguatge natural'. NOT designing chart layout or panels (that is dashboard), NOT choosing which KPIs to track (that is kpi-framework), NOT writing the raw query by hand (that is sql)."
+description: "Use when a metric (revenue, MRR, margin) needs defining once in a governed semantic layer so every dashboard, report and agent returns the same number, or when an LLM must answer data questions in plain language without hallucinating SQL. NOT chart layout (that is `dashboard`), NOT which KPIs to track (that is `kpi-framework`), NOT a hand-written query (that is `sql`)."
 tags: [business-intelligence, semantic-layer, metrics-layer, text-to-sql, natural-language-query, dbt, cube]
 recommends: [sql, dashboard, kpi-framework, reporting, analytics, forecasting, clickhouse-analytics, duckdb]
 origin: risco
@@ -119,15 +119,6 @@ Question: "MRR by plan, monthly, last 2 quarters, EU customers only"
   filter      -> region = 'EU'
 ```
 
-```text
-Pregunta (ES/CA): "ingresos por región, mensual, últimos 2 trimestres, solo UE"
-  metric      -> gross_revenue
-  group by    -> region
-  time grain  -> month
-  date filter -> last 2 quarters
-  filter      -> region = 'EU'
-```
-
 You hand the layer that spec; it generates the governed SQL. You then explain the answer back in business terms ("EU MRR grew 8% QoQ, driven by the Pro plan"), not as a table dump.
 
 ## Wire the agent
@@ -155,22 +146,17 @@ Author toward the **Open Semantic Interchange** standard so definitions survive
 
 ## Anti-patterns
 
-| Rationalization | Reality | STOP |
+| Anti-pattern | Why it bites | Instead |
 |---|---|---|
-| "Just free-hand the SQL this once, it's faster" | "Once" becomes the fourth conflicting revenue figure; it's unauditable | Add/query a metric |
-| "Each dashboard can define revenue itself" | That is exactly how you get three numbers and a fire drill | One metric, all consumers query it |
-| "The time dimension grain is obvious, skip declaring it" | Undeclared grain → silent daily-vs-monthly mismatches | Declare `time_granularity`/`grain` |
-| "Give the agent warehouse creds, it'll figure out the joins" | Raw text-to-SQL is 84-90% (33% in 2023); unauditable | Expose metrics via MCP/API |
-| "Stand up a semantic layer for this 200-row CSV" | Pure overhead for one analyst | `../sql/SKILL.md` / `../duckdb/SKILL.md` |
-| "The LLM is smart enough to write correct SQL" | The dbt 2026 benchmark says the layer is +8-14pts more accurate | Ground it in the layer |
-| "Hard-code the EU filter into the metric" | Now you need a second metric for every region | Pass filters at query time |
+| Free-handing the SQL "just this once" because it's faster | "Once" becomes the fourth conflicting revenue figure; it's unauditable | Add/query a metric |
+| Letting each dashboard define revenue itself | That is exactly how you get three numbers and a fire drill | One metric, all consumers query it |
+| Skipping the time dimension's grain because it's "obvious" | Undeclared grain → silent daily-vs-monthly mismatches | Declare `time_granularity`/`grain` |
+| Handing the agent warehouse creds to figure out the joins | Raw text-to-SQL is 84-90% (33% in 2023) and unauditable; the dbt 2026 benchmark puts the layer +8-14pts ahead | Expose metrics via MCP/API |
+| Standing up a semantic layer for a 200-row CSV | Pure overhead for one analyst | `../sql/SKILL.md` / `../duckdb/SKILL.md` |
+| Hard-coding the EU filter into the metric | Now you need a second metric for every region | Pass filters at query time |
 
 ## Verify
 
 Run `scripts/verify.sh [path]` on your semantic-model directory. It is read-only, never touches a warehouse, and discovers candidate YAML, then warns (advisory) on: a metric with no underlying measure, a measure with no declared `agg`, a time dimension with no grain, duplicate metric names, and a `.sql` beside the model hand-rolling an aggregate the layer should own. It exits non-zero only on unparseable YAML; an empty or clean target passes clean.
 
-## See also
-
-- `references/authoring-semantic-models.md` — multi-entity models, metric types, semi-additive measures, time spines, fan-out traps.
-- `references/wiring-agents-and-apis.md` — MCP metrics-tool pattern, dbt SL / Cube query shapes, agent guardrails.
-- Siblings: `../sql/SKILL.md` · `../dashboard/SKILL.md` · `../kpi-framework/SKILL.md` · `../reporting/SKILL.md` · `../analytics/SKILL.md` · `../forecasting/SKILL.md`
+Siblings: `../sql/SKILL.md` · `../dashboard/SKILL.md` · `../kpi-framework/SKILL.md` · `../reporting/SKILL.md` · `../analytics/SKILL.md` · `../forecasting/SKILL.md`