@ericrisco/rsc 0.1.44 → 0.1.46

package/skills/automation-flows/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: automation-flows
-description: "Use when building or fixing a no-code automation on n8n, Make, or Zapier — wiring a trigger to multi-app steps with branching, data mapping, retries, and an error path, or choosing the platform by its billing model. Triggers: 'wire up a Zap / Make scenario / n8n workflow that does X when Y happens', 'new Stripe payment → Notion row → Slack message in n8n', 'my Zap keeps failing silently, add error handling and retries', 'should I use Make or Zapier for 50k runs a month', 'my automation bill exploded', 'give me the JSON to import into n8n', 'automatiza esto en Make sin código', 'munta un workflow a n8n amb gestió d'errors', 'por qué se me dispara el Zap dos veces'. NOT writing a typed API client in code with auth/pagination/backoff (that is api-connector-builder), NOT building the inbound endpoint that receives and verifies webhook events in your own app (that is webhooks), NOT scripting one vendor's SDK directly (that is stripe / notion-connector / google-workspace / whatsapp-telegram)."
+description: "Use when building or fixing a no-code automation on n8n, Make, or Zapier — trigger to multi-app steps with data mapping, dedup, retries and an error path — or picking the platform by billing unit (task vs credit vs execution). NOT a typed API client in code (that is api-connector-builder), NOT a webhook receiver in your own app (that is webhooks)."
 tags: [automation, n8n, make, zapier, no-code, workflows, error-handling, integrations]
 recommends: [automation-strategy, n8n, make, zapier, power-automate, webhooks, api-connector-builder, error-handling, stripe, notion-connector, google-workspace, whatsapp-telegram]
 profiles: []
@@ -9,16 +9,12 @@ origin: risco
 
 # Automation flows — glue many SaaS apps on a visual platform, with an error path that actually fires
 
-You are building a working automation on a hosted visual platform: a trigger, a chain of app actions with branching and explicit data mapping, and — non-negotiably — an error-handling and retry strategy. A flow that has no error path is not done. It is a silent failure waiting for the day the API hiccups and nobody notices the orders stopped syncing.
+You are building a working automation on a hosted visual platform: a trigger, a chain of app actions with branching and explicit data mapping, and an error-handling and retry strategy without which the flow is not done.
 
 Your job is two things at once: **platform judgement** (pick n8n vs Make vs Zapier by the constraints) and a **buildable artifact** (an importable n8n workflow JSON, or a precise numbered build sheet for Make/Zapier, which have no portable export).
 
 This skill stops the moment the right answer is real code. Writing a typed API client → `../api-connector-builder/SKILL.md`. Building the endpoint that *receives* a webhook in your own app → `../webhooks/SKILL.md`. Scripting one vendor directly → `../stripe/SKILL.md`, `../notion-connector/SKILL.md`, `../google-workspace/SKILL.md`, `../whatsapp-telegram/SKILL.md`.
 
-## The iron rule
-
-Every flow ships with an error path. Before you call a flow done, you must be able to point at: where a failed run goes, how many times it retries, and who gets told. No exceptions.
-
 ## 1. Pick the platform
 
 The single most expensive mistake is choosing on familiarity instead of cost model. The three platforms bill on fundamentally different units, and at volume that gap is 10×.
@@ -60,7 +56,7 @@ Good: Trigger = Airtable "new record" webhook              → fires the instant
 
 ## 3. Error handling — the spine
 
-This is what separates a toy from production. Full per-platform recipes (including the manual exponential-backoff loop) live in `references/error-handling.md`; here is the working core.
+Every flow ships with an error path, because a flow without one is a silent failure waiting for the day the API hiccups and nobody notices the orders stopped syncing. Before you call a flow done you must be able to point at three things: where a failed run goes, how many times it retries, and who gets told. Full per-platform recipes (including the manual exponential-backoff loop) live in `references/error-handling.md`, and the retry/backoff theory under them in `../error-handling/SKILL.md`; here is the working core.
 
 **n8n.** Build a dedicated **Error Workflow** that begins with the **Error Trigger** node — it runs only when a monitored workflow fails. Wire it to Slack/email/a log row, then set it as the main flow's `settings.errorWorkflow`. On risky nodes (anything hitting an external API) toggle **Retry On Fail** (Max Tries 3–5, set a Wait between tries) and, where a single failed item shouldn't kill the run, **Continue On Fail** (the node emits an error object instead of halting). n8n's built-in retry is **linear** — for true exponential backoff you build a wait/loop yourself (recipe in references).
 
@@ -108,7 +104,9 @@ Good: webhook → lookup event_id in store →
 
 **If n8n is chosen, produce an importable workflow JSON** the user can paste into *Import from File/Clipboard*. It must have a non-empty `nodes` array (including a trigger node), a `connections` object, and `settings.errorWorkflow` pointing at the Error Workflow. Reference credentials by the n8n **credential store**, never paste secrets inline. Full schema and a minimal trigger→action→error example: `references/n8n-workflow-json.md`.
 
-**If Make or Zapier is chosen, produce a numbered build sheet** — neither has a portable export you can hand over. One row per step: `# | app | action | field mapping (source → target) | error directive`. End with the trigger type and the dedup key. The capability eval covers these prose sheets; `verify.sh` covers the JSON.
+**If Make or Zapier is chosen, produce a numbered build sheet** — neither has a portable export you can hand over. One row per step: `# | app | action | field mapping (source → target) | error directive`. End with the trigger type and the dedup key.
+
+Run `scripts/verify.sh` on any JSON you emit: read-only, no network, no credentials — it parses the file and checks a non-empty `nodes` array, a `connections` object, and ≥1 trigger node (exits 0 on an empty target).
 
 ## Anti-patterns
 
@@ -122,11 +120,3 @@ Good: webhook → lookup event_id in store →
 | Secrets pasted inline in a node | Leaked in exports, unrotatable, shared everywhere | Use the platform credential store, reference by name |
 | One mega-flow doing everything | Unreadable, untestable, one failure nukes all | Split: trigger → sub-flow per concern |
 | Choosing platform by familiarity | Bill 10× higher than the right unit; "my automation bill exploded" | Pick by billing unit (task vs op vs execution) up front |
-
-## References & verification
-
-- `references/error-handling.md` — per-platform error deep dive, the manual exponential-backoff loop for n8n, and the three dedup patterns.
-- `references/n8n-workflow-json.md` — importable n8n JSON schema, minimal example, import steps, what `verify.sh` checks.
-- `scripts/verify.sh` — read-only; validates any `*.json` workflow you emit (parses, non-empty `nodes`, `connections` object, ≥1 trigger node). No network, no credentials. Exits 0 on an empty target.
-
-Cross-skills: webhook receiver → `../webhooks/SKILL.md`; typed API client in code → `../api-connector-builder/SKILL.md`; deeper retry/backoff theory → `../error-handling/SKILL.md`.

package/skills/automation-strategy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: automation-strategy
-description: "Use when deciding whether a process is worth automating, choosing an automation platform, sizing ROI / build-vs-buy, designing an automation strategy, or diagnosing why a fleet of automations keeps breaking — the discipline layer that runs BEFORE anyone builds. Triggers: 'should we automate this?', 'is this worth automating', 'n8n vs Make vs Zapier vs Power Automate — which do we pick', 'custom script or no-code platform', \"what's the ROI on automating X\", 'design our automation strategy', 'our automations keep breaking', 'automating this cost more than it saved', '¿merece la pena automatizar esto?', 'qué plataforma de automatización elegimos'. NOT building the flow on a platform (design + importable artifact is automation-flows; driving a live platform API/MCP is the n8n / make / zapier / power-automate skills), NOT a typed API client with auth/pagination/backoff (api-connector-builder), NOT the inbound endpoint that receives webhook events in your app (webhooks)."
+description: "Use when deciding whether a process is worth automating, sizing ROI and build-vs-buy, choosing an automation platform, or diagnosing why a fleet of automations keeps breaking — the decision layer before anyone builds. NOT building the flow (that is `automation-flows`, or `n8n` / `make` / `zapier` / `power-automate` to drive a live platform)."
 tags: [automation, strategy, roi, build-vs-buy, platform-selection, orchestration, idempotency, n8n, make, zapier, power-automate]
 recommends: [automation-flows, n8n, make, zapier, power-automate]
 profiles: [core, full]
@@ -111,14 +111,6 @@ These are the guarantees every automation must meet regardless of platform. This
 | **No owner** | Orphaned automations rot; nobody notices the break or knows how it works | Name an owner + a one-page runbook per automation |
 | **Choosing platform by familiarity** | Bill 10× higher than the right billing unit; "our automation bill exploded" | Pick by billing unit for your run shape (§3) |
 
-## Related skills
-
-- `../automation-flows/SKILL.md` — **build layer**: designs the flow and emits the importable artifact once this skill has decided *whether* and *where*. Strategy decides; automation-flows designs.
-- `../n8n/SKILL.md`, `../make/SKILL.md`, `../zapier/SKILL.md`, `../power-automate/SKILL.md` — **operate layer**: drive that platform's live API/MCP to CRUD, activate, and run. Route here after §3.
-- `../api-connector-builder/SKILL.md` — when the answer is custom code, not a platform: typed client with auth/pagination/backoff.
-- `../webhooks/SKILL.md` — when you need to *receive* events in your own app (this skill treats webhooks as triggers, it doesn't build the receiver).
-- `../secure-coding/SKILL.md` — secrets/rotation engineering behind the orchestration policy in §4.
-
 ## Checklist
 
 - [ ] Ran the §1 gate: frequency × time-saved × error-rate × **stability** — and confirmed the process is standardized, not chaos being paved.

package/skills/aws-essentials/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: aws-essentials
-description: "Use when standing up the core AWS surface a small product needs — create a private S3 bucket for uploads, provision an encrypted RDS Postgres, choose ECS Fargate vs EC2 for a container, put CloudFront in front of S3, write or tighten an IAM policy, or harden a fresh account (root MFA, no long-lived keys). Triggers: 'set up an S3 bucket for user uploads', 'this role has AdministratorAccess, scope it down', 'spin up Multi-AZ Postgres on RDS', 'my bucket is public and I don't know why', 'this role can do everything', 'I can't encrypt RDS now', 'Fargate or EC2 for a low-traffic app', 'monta un bucket S3 privado', 'permisos mínims a IAM', 'posa CloudFront davant del bucket'. NOT the CI pipeline that ships your container (that is deployment), NOT app-code access-control review (that is secure-coding)."
+description: "Use when standing up the core AWS surface a small product needs: hardening a fresh account, a private S3 bucket, encrypted RDS Postgres, ECS Fargate vs EC2, CloudFront + OAC, or scoping an IAM policy to least privilege. NOT the CI pipeline that ships the container (that is `deployment`), NOT app-code access-control review (that is `secure-coding`)."
 tags: [aws, cloud, iam, s3, infrastructure]
 recommends: [deployment, secure-coding, dynamodb, postgresdb]
 origin: risco
@@ -17,19 +17,6 @@ god-mode app roles, long-lived keys, unencrypted databases). Pick the right tier
 account hardening → IAM (roles + scoped policies) → S3 (private) / RDS (encrypted) / ECS Fargate → CloudFront (OAC) → infra exists, wired, least-privilege
 ```
 
-## Operating posture — three rules
-
-- **Secure by default: keep the defaults AWS already hardened.** New S3 buckets are private
-  since April 2023 (Block Public Access on, ACLs disabled, SSE-S3 encryption). Do not undo them.
-- **Least privilege: scope every policy, never `"*"` on `"*"`.** A role that can do everything
-  is a breach waiting for one leaked credential. Start from a managed policy, then tighten.
-- **Roles, not keys.** Temporary credentials from a role beat a long-lived `AKIA…` access key
-  that lives forever in a `.env` and ends up on GitHub. Apps get task roles; CI gets OIDC.
-
-Boundary in one sentence: **this skill provisions and secures the AWS account and its core
-services; `../deployment/SKILL.md` puts your container on it; `../secure-coding/SKILL.md` audits
-the code inside it.**
-
 ## Service decision table
 
 | Need | Use | Use instead if |
@@ -61,7 +48,9 @@ Do this once, before anything else. Each line has a reason; skip none.
 
 Two principal types. **IAM users** = long-lived humans/keys; avoid them for workloads. **Roles**
 = an identity something *assumes* to get temporary credentials — this is what ECS tasks, Lambda,
-CI, and federated humans use. Default to roles.
+CI, and federated humans use. Default to roles: a temporary credential beats a long-lived `AKIA…`
+key that lives forever in a `.env`. (IAM governs who may call AWS APIs; access control *inside*
+your app code is `../secure-coding/SKILL.md`.)
 
 A policy is a JSON document. The four parts that matter:
 
@@ -181,7 +170,8 @@ Two more non-negotiables: the DB security group **references the app's security
 `0.0.0.0/0` (a DB open to the internet is a breach, not a convenience); credentials live in
 **Secrets Manager** with managed rotation (`--manage-master-user-password` above), never in task
 env vars. Use `--multi-az` for production HA. Full recipe (SG wiring, Secrets Manager rotation,
-connecting from ECS) → `references/rds-cloudfront-recipes.md`.
+connecting from ECS) → `references/rds-cloudfront-recipes.md`. Schema, indexes and query tuning
+once the instance exists → `../postgresdb/SKILL.md`.
 
 ## CloudFront + OAC — public web content, private bucket
 
@@ -214,10 +204,3 @@ Full CLI: create OAC → distribution → S3 bucket policy JSON → invalidation
 | Root user for daily ops | Highest blast radius, no per-action attribution | Root only for root-only tasks; admin via Identity Center |
 | No MFA on root | One phished password = total account loss | Passkey/security-key MFA on root and every human |
 | Confusing task role and execution role | App gets 403 at runtime, or ECS can't pull the image | Execution = pull image/logs; task = app's runtime perms |
-
-## Cross-links
-
-- `../deployment/SKILL.md` — Dockerfile, CI/CD, OIDC to ECR, the actual ship-the-container step.
-- `../secure-coding/SKILL.md` — app-code access control / OWASP (vs cloud IAM here).
-- `../postgresdb/SKILL.md` — schema, indexes, query tuning once the RDS instance exists.
-- For key-value / single-table serverless data instead of RDS, reach for the `dynamodb` skill.

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.