@ericrisco/rsc 0.1.44 → 0.1.45

package/skills/analyze/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: analyze
-description: "Use when the spec, plan and task list are written and you want a last consistency check BEFORE any code is touched — the pre-implementation GATE of the rsc-sdd chain. It cross-reads constitution vs spec vs plan vs tasks and reports gaps, contradictions, duplication, ambiguity and scope drift, mapping every artifact to the requirements it claims to satisfy. Report-only: it never edits artifacts and never writes code; the user decides each resolution. Triggers: 'analyze', 'analiza la spec antes de implementar', 'cross-check constitution spec plan tasks', 'consistency gate', 'are spec and plan aligned', 'did we miss any requirement', 'scope drift check', 'gap analysis before coding', 'is the plan complete', 'sanity-check before implement', 'coverage of requirements'. NOT clarifying a single spec (that is `clarify`), NOT writing the plan or tasks, NOT running tests/lint (that is `verify`), NOT root-causing a bug (that is `debug`)."
+description: "Use when constitution, spec, plan and tasks all exist and you want them cross-read against each other before any code is written — the rsc-sdd pre-implementation gate. Reports coverage gaps, contradictions, duplication, ambiguity and scope drift; edits nothing. NOT the task breakdown (that is `tasks`), NOT the coding (that is `implement`), NOT the post-code test gate (that is `verify`), NOT resolving ambiguity (that is `clarify`)."
 tags: [sdd, analyze, consistency]
 recommends: [implement]
 profiles: [core, full]
@@ -9,51 +9,26 @@ origin: risco
 
 # Analyze — the pre-implementation consistency gate
 
-You have a **constitution**, a **spec**, a **plan** and a **task list**. Four artifacts written at four different moments, by a mind that drifted a little each time. `analyze` is the last checkpoint before the first line of code: it reads all four *against each other* and surfaces where they disagree. It is the cheapest place in the whole chain to catch a problem — a contradiction found here costs a sentence; the same contradiction found mid-implement costs a rewrite.
+You have a **constitution**, a **spec**, a **plan** and a **task list**. Four artifacts written at four different moments, by a mind that drifted a little each time. `analyze` reads all four *against each other* and surfaces where they disagree. It is the cheapest place in the whole chain to catch a problem — a contradiction found here costs a sentence; the same contradiction found mid-implement costs a rewrite.
 
-This is the **sixth phase** of the rsc-sdd chain (`constitution → specify → clarify → plan → tasks → analyze → implement`). It is a **gate, not a worker**: it produces a report and stops. It does not patch the spec, does not reorder tasks, does not touch code. The user reads the findings and decides what to fix, and which phase to send each fix back to.
+Sixth phase of the rsc-sdd chain (`constitution → specify → clarify → plan → tasks → analyze → implement`); the method itself lives in `../sdd/SKILL.md`. It is a **gate, not a worker**: it produces a report and stops. The user reads the findings and decides what to fix, and which phase to send each fix back to.
 
-## The one rule that defines this skill
+**Report only. Resolve nothing.** Never edit the constitution, spec, plan or tasks; never open a code file to "just fix it"; never silently reconcile a contradiction by picking a side. This one is absolute because a gate that quietly fixes things stops being a gate: the user never learns the spec was wrong, the plan built on the old assumption stays stale, and the "consistency check" has manufactured a new inconsistency. Name the conflict, show both sides with locations, propose where it should be resolved, hand the decision back.
 
-**Report only. Resolve nothing.** `analyze` never edits the constitution, spec, plan or tasks, never opens a code file to "just fix it", never silently reconciles a contradiction by picking a side. It names the conflict, shows both artifacts with their locations, proposes where it should be resolved, and hands the decision back. The moment you feel the urge to edit an artifact, you have left this skill — stop and route the fix to the phase that owns it.
+**Model tier: `heavy`** (adversarial cross-reading). Resolve and apply it per `../sdd/references/model-routing.md`; routing is off unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`.
 
-Why so strict? Because a gate that quietly fixes things stops being a gate. If `analyze` patches the spec on its own, the user never learns the spec was wrong, the plan built on the old assumption stays stale, and the "consistency check" has manufactured a new inconsistency. The value is the *honest report*, not the patch.
+**Accompaniment dial.** Read `02-DOCS/wiki/harness/user-profile.md` before reporting — default to **L2** and say the harness has not gauged the user yet if there is no profile. The dial flexes how the report reads, never what gets checked; the six analyses always run in full.
 
-## When to use / when NOT to use
-
-Use when:
-
-- The plan and tasks exist and you are about to start implementing — run this first, every time.
-- A spec or plan changed after the others were written and you want to re-check alignment.
-- Implementation stalled because the artifacts seem to contradict each other.
-- You want a requirements-coverage map: which task satisfies which spec requirement, and what is orphaned.
-
-Do NOT use when (route elsewhere):
-
-- A single spec is fuzzy and you need to ask the user questions and bake answers in → `clarify` (analyze reports the ambiguity; clarify resolves it).
-- The plan or tasks don't exist yet → write them first (`plan`, then `tasks`).
-- You want to run lint/types/tests/acceptance after coding → `verify` (post-implementation gate; analyze is pre-implementation).
-- A test is failing or behavior is wrong → `debug`.
-- You intend to fix what you find right now → that is `implement`/`clarify`/`plan`/`tasks` work, not analyze. Analyze only reports.
-
-## Model tier — `heavy` (opt-in routing)
-
-This phase's default model tier is **`heavy`** — it is the adversarial consistency gate across constitution ↔ spec ↔ plan ↔ tasks. Routing is **off** unless `models.enabled: true` in `02-DOCS/wiki/sdd/config.yaml`. When on: resolve this phase's tier (`models.overrides` wins over `models.phases`), map it to a model via `models.tiers`, and apply per `../sdd/references/model-routing.md` — announce the switch per the accompaniment dial when it differs from the session model, and dispatch any `Task`/`parallel` subagents on that model. Routing off or no profile → honor the session model silently. Never fake a switch a tool can't make; skip routing on a one-line change.
-
-## Read the accompaniment dial first
-
-Before reporting, read `02-DOCS/wiki/harness/user-profile.md` for the technical + accompaniment level (the harness dial, L0..L3). It shapes how the report reads — not what gets checked. The six analyses always run in full; verbosity flexes:
-
-- **L0** — the finding table only: severity, the two artifacts, the conflict in one line. No prose.
-- **L1** — the table plus a one-line *why it matters* per CRITICAL/HIGH finding.
-- **L2** — the table plus, per finding, the recommended resolution phase and the trade-off of leaving it.
-- **L3** — full walk-through: for each finding, quote both sides, explain the consequence at implement time in plain language, and lay out the options so a non-technical user can choose.
-
-If no profile exists, default to L2 and note that the harness has not gauged the user yet.
+| Dial | The report renders as |
+| --- | --- |
+| L0 | Finding table only: severity, the two artifacts, the conflict in one line. No prose. |
+| L1 | + a one-line *why it matters* per CRITICAL/HIGH finding. |
+| L2 | + per finding, the recommended resolution phase and the trade-off of leaving it. |
+| L3 | + full walk-through: quote both sides, explain the consequence at implement time in plain language, lay out the options so a non-technical user can choose. |
 
 ## Inputs — locate the four artifacts
 
-Read all four before analyzing. The rsc-sdd artifacts live under `02-DOCS/wiki/sdd/` (the harness Karpathy-wiki convention), indexed from `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it):
+Read all four before analyzing. The rsc-sdd artifacts live under `02-DOCS/wiki/sdd/`, indexed from `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer to it):
 
 | Artifact | Canonical location | Role in the check |
 | --- | --- | --- |
@@ -110,32 +85,22 @@ Produce a single consistency report:
 1. **Verdict line** — `GATE: PASS` (zero CRITICAL/HIGH) or `GATE: BLOCKED` (one or more CRITICAL/HIGH), with the counts.
 2. **Coverage map** — the table above.
 3. **Findings table** — `# | Severity | Type | Artifact A (loc) | Artifact B (loc) | Conflict | Resolve in (phase)`.
-4. **Recommended routing** — group fixes by the phase that owns them (`clarify` for spec ambiguity, `plan` for missing architecture, `tasks` for a missing done-check, `constitution` if a principle itself is wrong).
+4. **Recommended routing** — group fixes by the phase that owns them (`clarify` for spec ambiguity, `plan` for missing architecture, `tasks` for a missing done-check, `constitution` if a principle itself is wrong). If findings pour in across all six checks, the artifacts diverged badly — recommend re-running `clarify`/`plan` before a line-by-line analyze is even useful.
 
-Write the report to `02-DOCS/wiki/sdd/analysis/<slug>.md` (create the dir if absent) and index it in `02-DOCS/wiki/index.md` (the Knowledge map; root `CLAUDE.md` keeps only a short pointer) under the `sdd/` topic, so the next phase and the harness can find it. It is an OKF v0.1 wiki article: open it with YAML frontmatter carrying a non-empty `type:` (use `type: analysis`), a `timestamp` in ISO 8601, and standard markdown links — never wikilinks. The report is the artifact analyze owns — it is the *only* thing analyze writes. Per-run point-in-time; overwrite on re-run, the wiki keeps history.
+Write the report to `02-DOCS/wiki/sdd/analysis/<slug>.md` (create the dir if absent) and index it in `02-DOCS/wiki/index.md` under the `sdd/` topic, so the next phase and the harness can find it. It is an OKF v0.1 wiki article: open it with YAML frontmatter carrying a non-empty `type:` (use `type: analysis`), a `timestamp` in ISO 8601, and standard markdown links — never wikilinks. The report is the artifact analyze owns — it is the *only* thing analyze writes. Per-run point-in-time; overwrite on re-run, the wiki keeps history.
 
-Adapt the rendered verbosity to the dial (L0 = table only; L3 = full walk-through). Do not log a decision to `decisions.md` — analyze decides nothing; the phase that resolves the finding logs its own decision.
+Render it at the dial's verbosity. Do not log a decision to `decisions.md` — analyze decides nothing; the phase that resolves the finding logs its own decision.
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization | Reality / Fix |
+| Anti-pattern | Why it breaks the gate / do instead |
 | --- | --- |
-| "This contradiction is trivial, I'll just fix the spec myself" | Then you are `clarify`/`plan`, not `analyze`. Report it; the user resolves. A gate that edits stops being a gate. |
-| "No CRITICAL findings, so I'll start coding from here" | Analyze never transitions to code. Pass the verdict to `implement`; that phase starts the work. |
-| "The plan adds caching the spec didn't mention — obviously a good idea, I'll allow it" | That is DRIFT. Flag it. Good ideas still need the spec amended (user's call), or they are silent scope creep. |
-| "I'll only check coverage; contradictions are rare" | Run all six analyses every time. The one you skip is the one that bites at implement time. |
-| "The spec is vague but I can guess what they meant" | Guessing defeats the gate. Mark AMBIGUOUS and route to `clarify`; do not encode your guess. |
-| "I'll fold the findings straight into the task list to save a step" | No. Editing tasks is the `tasks` phase. Report, route, hand back. |
-| "Constitution says Postgres but plan picked Mongo for good reasons — I'll side with the plan" | The constitution wins by definition. Flag CRITICAL. If the principle is wrong, that is a `constitution` change the user makes, not a quiet override here. |
-| "I read the spec and tasks; the constitution is boilerplate, skip it" | The constitution is analysis #1 and the highest severity. Never skip it. |
-
-## Red flags — stop and report instead of analyzing
-
-- An artifact is missing (no plan, no tasks) → say which, name the phase, do not fabricate it.
-- Multiple specs match the slug → ask which feature; don't analyze the wrong one.
-- You catch yourself opening a source file → you have left the gate; close it.
-- Findings are pouring in across all six checks → the artifacts diverged badly; recommend the user re-runs `clarify`/`plan` before a line-by-line analyze is even useful.
+| Fixing a "trivial" contradiction in the spec yourself | Then you are `clarify`/`plan`/`tasks`, not `analyze`. Report it; the user resolves. |
+| Starting to code because nothing CRITICAL turned up | Analyze never transitions to code. Hand the verdict to `implement`; that phase starts the work. |
+| Waving through plan work the spec never asked for because it's obviously a good idea | That is DRIFT. Flag it. Good ideas still need the spec amended (user's call), or they are silent scope creep. |
+| Siding with the plan when it contradicts the constitution | The constitution wins by definition — flag CRITICAL. If the principle itself is wrong, that is a `constitution` change the user makes, not a quiet override here. |
+| Guessing what a vague requirement meant | Guessing defeats the gate. Mark AMBIGUOUS and route to `clarify`; do not encode your guess. |
 
 ## Next in the chain
 
-When the verdict is `GATE: PASS` (or the user has consciously accepted the remaining MEDIUM/LOW findings), proceed to **`implement`** — execute the tasks with TDD discipline, delegating concrete test tooling to the relevant stack skill (`fastapi`, `nextjs`, `go`, `flutter`, `postgresdb`). If the verdict is `GATE: BLOCKED`, route each CRITICAL/HIGH finding to its owning phase (`clarify`, `plan`, `tasks`, or `constitution`), let the user resolve, then re-run `analyze`. The gate only opens once.
+On `GATE: PASS` (or once the user consciously accepts the remaining MEDIUM/LOW findings), proceed to **`implement`** — execute the tasks with TDD discipline, delegating concrete test tooling to the relevant stack skill (`fastapi`, `nextjs`, `go`, `flutter`, `postgresdb`). On `GATE: BLOCKED`, route each CRITICAL/HIGH finding to its owning phase (`clarify`, `plan`, `tasks`, or `constitution`), let the user resolve, then re-run `analyze`. The gate only opens once.

package/skills/angular/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: angular
-description: "Use when building, refactoring, reviewing, or debugging an Angular app (Angular 20/21+: standalone components, signals, zoneless change detection, the @if/@for/@defer built-in control flow, inject() DI, resource()/httpResource(), RxJS interop, NgRx SignalStore, the ng CLI). Triggers: 'why isn't my view updating', migrating NgModules to standalone, replacing *ngFor with @for, decorator inputs vs input() signals, 'monta una app Angular', 'componente standalone con signals', 'com passo a zoneless', going zoneless / removing Zone.js, app.config.ts providers, toSignal/toObservable interop, ng generate/ng update. NOT React (that is react), NOT Next.js (that is nextjs), NOT a plain TypeScript language question (that is typescript)."
+description: "Use when building, refactoring, or debugging Angular (v20/21+): standalone components, signals, zoneless change detection, @if/@for/@defer control flow, inject() DI, resource()/httpResource(), RxJS interop, NgRx SignalStore, ng CLI. NOT React (that is react), NOT Next.js (that is nextjs), NOT a TypeScript language question (that is typescript)."
 tags: [angular, frontend, web, signals, typescript, spa]
 recommends: [typescript, testing-web, secure-coding]
 origin: risco
@@ -10,31 +10,23 @@ origin: risco
 
 > Build Angular the way it ships in 2026: standalone components, signals as the reactivity model, zoneless change detection, built-in control flow, and `inject()` DI. Treat NgModules, `*ngFor`, and `@Input()` decorators as legacy you only touch to migrate.
 
-## When to use
+## Not this skill
 
-- Creating or editing Angular components, directives, services, guards, resolvers, interceptors, or routes.
-- Anything touching `angular.json`, the `ng` CLI, `main.ts` bootstrap, `app.config.ts`, or `provide*()` providers.
-- Deciding signals vs RxJS, or migrating decorators/NgModules to standalone + signals.
-- Wiring data fetching with `httpResource()`/`resource()` or `HttpClient` + RxJS.
-- Debugging zoneless change detection, `OnPush`, or "view not updating" bugs.
-- State with NgRx SignalStore or plain signal services; reactive/typed forms; route-bound signal inputs.
-
-## When NOT to use
-
-- **AngularJS (1.x)** — out of scope entirely. This skill is Angular 2+ only; the APIs do not map.
-- **React** → that is the `react` skill. NOT React (that is react).
-- **Next.js App Router** → `../nextjs/SKILL.md`.
-- **Vue/Nuxt, Svelte, SolidJS, Astro** → `vue-nuxt`, `svelte`, `solid-js`, `../astro/SKILL.md`.
-- **Pure TypeScript language question** (generics, narrowing, tsconfig) with no Angular dimension → `../typescript/SKILL.md`.
-- **A standalone NestJS API** → `../nestjs/SKILL.md`. A generic Node service → `nodejs`. Angular Universal SSR itself stays here.
-- **Cross-framework Playwright e2e strategy** → `testing-web` / `e2e-testing`. Angular's own `ng test` (Vitest) setup stays here.
+**AngularJS (1.x)** is out of scope entirely — this skill is Angular 2+ only and the APIs do not map.
+Route elsewhere for **React** → `../react/SKILL.md`; **Next.js App Router** → `../nextjs/SKILL.md`;
+**Vue/Nuxt, Svelte, SolidJS, Astro** → `../vue-nuxt/SKILL.md`, `../svelte/SKILL.md`,
+`../solid-js/SKILL.md`, `../astro/SKILL.md`; a **pure TypeScript language question** (generics,
+narrowing, tsconfig) with no Angular dimension → `../typescript/SKILL.md`; a **standalone NestJS
+API** → `../nestjs/SKILL.md`; a generic Node service → `../nodejs/SKILL.md`; **cross-framework
+Playwright e2e strategy** → `../testing-web/SKILL.md` / `../e2e-testing/SKILL.md`. Angular Universal
+SSR and Angular's own `ng test` (Vitest) setup stay here.
 
 ## Decide first
 
 | Situation | Do this | Why |
 |-----------|---------|-----|
 | Greenfield app / new feature | Zoneless + signals + standalone by default. `ng new` (Angular 21) already excludes Zone.js. | The defaults shipped stable in v20-v21; fight them and you write more code that the framework now does for you. |
-| Brownfield NgModule + decorator app | Migrate incrementally with schematics; do not rewrite. Keep Zone.js until you flip it on purpose. | A working app that uses `*ngIf` is not a bug. Churn introduces risk for no user value. |
+| Brownfield NgModule + decorator app | Migrate incrementally with the schematics in `references/migration.md` (NgModule→standalone, control flow, decorator→signal inputs, Zone.js→zoneless, Karma→Vitest); do not rewrite. Keep Zone.js until you flip it on purpose. | A working app that uses `*ngIf` is not a bug. Churn introduces risk for no user value. |
 | "View not updating" complaint | Jump to the change-detection section: signal not read in template, `OnPush` without a signal, or stale Zone.js assumption. | Zoneless means a mutation that no signal observes will never repaint — the fix is structural, not a `detectChanges()` call. |
 
 ## The modern baseline
@@ -178,7 +170,7 @@ profile = resource({
 ```
 
 - Rule: `httpResource()`/`resource()` give you `value()`, `isLoading()`, `error()`, `reload()` for free — prefer them over a manual `subscribe` that you have to clean up. Why: less boilerplate, no leak, refetches automatically when its source signals change.
-- Rule: when you genuinely need a stream (websocket, debounced search, retry/switchMap), keep `HttpClient` + RxJS and bridge to a signal with `toSignal()`. Why: signals are not streams; do not fake backpressure with effects. See `references/signals-rxjs.md`.
+- Rule: when you genuinely need a stream (websocket, debounced search, retry/switchMap), keep `HttpClient` + RxJS and bridge to a signal with `toSignal()`. Why: signals are not streams; do not fake backpressure with effects. `references/signals-rxjs.md` has the signals-vs-RxJS decision matrix, `toSignal`/`toObservable` interop recipes, `effect` pitfalls (infinite loops, untracked reads), and `takeUntilDestroyed`.
 
 ## DI & services
 
@@ -280,9 +272,4 @@ it('renders the user name', async () => {
 | Nested `subscribe()` inside `subscribe()` | Callback pyramid, lost cancellation | `switchMap`/`concatMap`, one subscription |
 | Constructor DI only (`constructor(private x: X)`) | Legacy ergonomic; can't compose into functions | `private x = inject(X)` |
 
-## References
-
-- `references/signals-rxjs.md` — signals-vs-RxJS decision matrix, `toSignal`/`toObservable` interop recipes, `effect` pitfalls (infinite loops, untracked reads), `linkedSignal`/`resource()` patterns, `takeUntilDestroyed`.
-- `references/migration.md` — incremental migration checklist + schematics: NgModule→standalone, control-flow migration, decorator-input→signal-input, Zone.js→zoneless go-live, Karma/Jasmine→Vitest.
-
 `scripts/verify.sh` is a heuristic copy-banlist lint — it greps your Angular sources for the banned patterns above. It is a hint, not a compiler.

package/skills/api-connector-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-connector-builder
-description: "Use when writing a client against a third-party REST or GraphQL API and the boring-but-critical parts keep biting — token refresh mid-run, only-the-first-page results, random 429s, banned keys. Covers auth flow selection (API key, Bearer, OAuth2 client-credentials, auth-code+PKCE, device), pagination to exhaustion (offset, cursor/keyset, Link header, Relay connections), retry-with-jitter on transient failures only, and rate-limit-aware throttling. Triggers: 'write a connector for the Linear/Shopify API', 'this API keeps 429-ing us', 'paginate through all results', 'token expires mid-run add refresh', 'wrap this REST API as a typed SDK', 'conector para una API que nos limita', 'recórreme totes les pàgines'. NOT receiving inbound callbacks (that is webhooks), NOT chaining many services into a flow (that is automation-flows), NOT designing your own API surface (that is api-design)."
+description: "Use when writing a client for someone else's REST or GraphQL API: auth flow choice and token refresh, pagination to exhaustion, retry-with-jitter on transient failures only, rate-limit-aware throttling. NOT inbound callbacks (that is `webhooks`), NOT chaining services (that is `automation-flows`), NOT designing your own API (that is `api-design`)."
 tags: [api, rest, graphql, oauth, pagination, retries, rate-limiting, http-client, connector]
 recommends: [webhooks, automation-flows, api-design, data-scraper, secure-coding, error-handling, structured-extraction]
 origin: risco
@@ -12,31 +12,18 @@ You are writing a client for **someone else's** HTTP API. You do not own the
 contract; you obey it. The deliverable is one typed connector module per vendor
 that authenticates, walks the whole result set, retries only transient failures
 with backoff, and stays under the rate limit without getting the key banned.
+One connector = one vendor: mixed clients tangle two auth schemes and two
+rate-limit budgets into something no one can reason about.
 
 Four pillars, every time: **auth, pagination, retries, rate limits.** If your
 connector skips any one of them it works in the demo and breaks in production —
 on page 2, on token expiry, on the first 429, or on a flaky network.
 
-This skill goes **outbound** (you call them). Receiving their callbacks is the
-inverse and lives in `webhooks`.
-
-## Operating posture
-
-- **Read the vendor docs before writing a line.** Invented endpoints and guessed
-  field names 404 in prod. Find the real base URL, version, and error envelope.
-- **Secrets come from env or a secret store, never source.** Hardcoded keys leak
-  through git history and screenshots and you cannot rotate them cleanly.
-- **One connector = one vendor.** Mixed clients tangle two auth schemes and two
-  rate-limit budgets into one tangle no one can reason about.
-- **Every request gets a timeout.** A hung socket with no timeout stalls the
-  whole run forever; the default in most clients is "wait indefinitely".
-- **Log request id + status + attempt, never the token.** Logs get shipped to
-  third parties; a logged bearer token is a leaked credential.
-
 ## Step 0 — read the contract
 
-Before any code, extract these from the vendor's docs. Each one changes what you
-write, so missing one means a rewrite.
+Read the vendor docs before writing a line — invented endpoints and guessed
+field names 404 in prod. Extract these first; each one changes what you write,
+so missing one means a rewrite.
 
 | Find in their docs        | Why it changes your code                                  |
 | ------------------------- | --------------------------------------------------------- |
@@ -202,8 +189,9 @@ def iter_records(client):
             return
 ```
 
-Full code for every style — offset, keyset, `Link`-header parsing, and GraphQL
-Relay connection walking, in Python and TS — is in `references/pagination.md`.
+Full code for every style — offset, keyset, `Link`-header parsing, GraphQL Relay
+connection walking, in Python and TS, plus dedup-on-overlap notes — is in
+`references/pagination.md`.
 
 ## Putting it together
 
@@ -272,12 +260,7 @@ export async function request(path: string, init: RequestInit = {}, attempt = 0)
 | Token in query string                 | Token ends up in logs / referrers        | Bearer in the `Authorization` header         |
 | Implicit / password OAuth grant       | Removed in OAuth 2.1; insecure           | Auth-Code + PKCE, or Client Credentials      |
 
-## References & verify
-
-- `references/auth-flows.md` — per-flow walkthroughs, token storage + rotation,
-  OAuth 2.1 deltas, RFC 9700 refresh rotation, DPoP note. Python + TS.
-- `references/pagination.md` — full code for offset, cursor/keyset, Link-header,
-  and GraphQL Relay walking. Exhaustion-loop and dedup-on-overlap notes.
+## Verify
 
 Run `scripts/verify.sh` over the connector you write: it greps for hardcoded
 secrets, asserts a retry mechanism and a pagination loop and a request timeout

package/skills/api-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-design
-description: "Use when designing the contract of a network API before/independent of implementation — modeling resources and URLs, choosing REST vs GraphQL, picking a versioning strategy, defining one consistent error envelope, and settling pagination/filtering/idempotency conventions. Triggers: 'design the REST API for X', 'what should the endpoints be', 'how do I version this without breaking clients', 'should this be REST or GraphQL', 'cursor vs offset pagination', 'standard error format for my API', 'RFC 9457 problem details', 'idempotency key on POST', '200 with error body', 'diseña la API REST de esto', 'cómo verziono la API sin romper clientes'. NOT implementing endpoints in a framework (that is fastapi/nestjs/go/nodejs), NOT security/auth hardening (that is secure-coding), NOT receiving inbound webhooks (that is webhooks), NOT building an outbound client to a third-party API (that is api-connector-builder)."
+description: "Use when settling the contract of an API you expose, before implementation: resources/URLs, REST vs GraphQL, versioning, one RFC 9457 error envelope, pagination, idempotency — emitted as OpenAPI 3.1. NOT implementing the endpoints (that is `fastapi`/`nestjs`/`go`/`nodejs`), NOT auth hardening (that is `secure-coding`), NOT consuming a third-party API (that is `api-connector-builder`)."
 tags: [api-design, rest, graphql, openapi, versioning, pagination, http, rfc9457, contract-design]
 recommends: [fastapi, nestjs, go, nodejs, secure-coding, webhooks, api-connector-builder, code-review]
 origin: risco
@@ -24,7 +24,7 @@ Pick on traffic shape, not fashion. Decide once, write it down.
 | Many client shapes, deep nested graphs, mobile over-fetch is real | **GraphQL** | one round-trip, client picks fields; no N endpoints per screen |
 | Stable resource API + one rich read surface for a client app | **Hybrid** | REST for the system of record, a GraphQL read layer on top |
 
-Operational gotcha that decides monitoring: **GraphQL returns HTTP 200 even when a field errored** — failures live in an `errors[]` array next to partial `data`. Your dashboards cannot alert on 5xx; you must alert on the `errors[]` payload. REST signals failure with the HTTP status itself. If your ops team lives on status-code SLOs, that is a point for REST. Details in `references/graphql-design.md`.
+Operational gotcha that decides monitoring: **GraphQL returns HTTP 200 even when a field errored** — failures live in an `errors[]` array next to partial `data`. Your dashboards cannot alert on 5xx; you must alert on the `errors[]` payload. REST signals failure with the HTTP status itself. If your ops team lives on status-code SLOs, that is a point for REST. Schema/nullability design, mutation and error-union conventions, and this error model in full: [`references/graphql-design.md`](references/graphql-design.md).
 
 ## Resource & URL modeling
 
@@ -44,7 +44,7 @@ Rules, each with its reason:
 | `GET /projects/active` | `GET /projects?status=active` | filter is a query param |
 | `POST /projects/{id}/delete` | `DELETE /projects/{id}` | method, not path segment |
 
-Full query grammar (filter operators, sparse fieldsets, sort syntax) is in `references/rest-conventions.md`.
+Full query grammar (filter operators, sparse fieldsets, sort syntax), content negotiation, rate-limit headers and a HATEOAS note: [`references/rest-conventions.md`](references/rest-conventions.md).
 
 ## Status codes that matter
 
@@ -67,7 +67,7 @@ You need a small map, used consistently. Don't overload 200.
 
 Two distinctions agents get wrong:
 - **401 vs 403** — 401 means *unauthenticated* (no/invalid credentials); 403 means *authenticated but unauthorized*. Returning 401 on a permission failure leaks that re-auth might help when it won't.
-- **409 vs 422** — 409 is a *state* conflict (the request fights the current server state: dup key, stale version). 422 is a *content* problem (the body parses but fails business rules). Full table with when-each in `references/rest-conventions.md`.
+- **409 vs 422** — 409 is a *state* conflict (the request fights the current server state: dup key, stale version). 422 is a *content* problem (the body parses but fails business rules). Full status-code table with when-each in [`references/rest-conventions.md`](references/rest-conventions.md).
 
 ## Error envelope: RFC 9457
 
@@ -116,7 +116,7 @@ REST cursor envelope — same keys on every list endpoint:
 
 The next page is `GET /projects?cursor=eyJpZCI6MTI4N30&limit=50`. The cursor is opaque — clients must not parse or construct it.
 
-GraphQL has its own de-facto standard: **Relay Connections** — `edges { node, cursor }`, `pageInfo { hasNextPage, endCursor }`, args `first` / `after`. Use it; don't invent a bespoke GraphQL pagination shape. See `references/graphql-design.md`.
+GraphQL has its own de-facto standard: **Relay Connections** — `edges { node, cursor }`, `pageInfo { hasNextPage, endCursor }`, args `first` / `after`. Use it; don't invent a bespoke GraphQL pagination shape. See [`references/graphql-design.md`](references/graphql-design.md).
 
 ## Versioning & evolution
 
@@ -135,7 +135,7 @@ Sunset: Sat, 31 Oct 2026 23:59:59 GMT
 Link: <https://api.acme.com/v2/projects>; rel="successor-version"
 ```
 
-Full breaking-vs-non-breaking matrix and the deprecation workflow live in `references/versioning-and-evolution.md`.
+Full breaking-vs-non-breaking matrix, the three versioning mechanisms and the deprecation/sunset workflow: [`references/versioning-and-evolution.md`](references/versioning-and-evolution.md).
 
 ## Idempotency & concurrency
 
@@ -167,7 +167,7 @@ Idempotency-Key: 9b1f7c2e-...
 
 ## Handoff
 
-The contract is the artifact. Emit it as an **OpenAPI 3.1** document (see `references/openapi-contract.md`) — that is the checkable deliverable a framework skill generates code from.
+The contract is the artifact. Emit it as an **OpenAPI 3.1** document — the checkable deliverable a framework skill generates code from. How to shape it, and what `scripts/verify.sh` checks: [`references/openapi-contract.md`](references/openapi-contract.md).
 
 Hand off to the builder:
 - Python/async → [`../fastapi/SKILL.md`](../fastapi/SKILL.md)
@@ -180,10 +180,3 @@ Adjacent concerns you do **not** own:
 - Receiving inbound webhooks (HMAC verify, replay, dedupe) → [`../webhooks/SKILL.md`](../webhooks/SKILL.md)
 - Building an outbound client to a third-party API → [`../api-connector-builder/SKILL.md`](../api-connector-builder/SKILL.md)
 - Reviewing handler code (not the design) → [`../code-review/SKILL.md`](../code-review/SKILL.md)
-
-## References
-
-- `references/rest-conventions.md` — full status-code table, filter/sort/sparse-fieldset grammar, content negotiation, rate-limit headers, HATEOAS note.
-- `references/versioning-and-evolution.md` — breaking-vs-non-breaking matrix, three versioning mechanisms, deprecation/sunset workflow.
-- `references/graphql-design.md` — schema/nullability design, Relay Connections, mutation + error-union conventions, the HTTP-200 error model and its monitoring impact.
-- `references/openapi-contract.md` — capture the contract as OpenAPI 3.1 so frameworks generate from it; what `scripts/verify.sh` checks.

package/skills/article-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: article-writing
-description: "Use when drafting a long-form blog post or article from a topic or target query and you need publishable prose plus the on-page surface that ships with it — an answer-first lede, a question-shaped H2/H3 hierarchy, title tag, meta description, slug, FAQ block, and Article/FAQPage JSON-LD. Use when an intro buries the answer, a draft rambles or reads padded with AI tells, or a piece needs depth matched to search intent for AI Overviews and featured snippets. Triggers: 'write a blog post about X', 'draft a 1500-word article', 'rewrite this intro so the answer comes first', 'add FAQ schema to this post', 'cut the fluff out of this draft', 'escriu un article de blog sobre teletreball optimitzat per SEO', 'redacta un artículo optimizado para SEO'. NOT keyword research or which topics to target (that is seo-geo), and NOT the editorial calendar or content pipeline (that is content-engine)."
+description: "Use when writing one long-form article end to end — answer-first lede, question-shaped headings, plus its on-page surface (title, meta, slug, FAQ, Article/FAQPage JSON-LD) — or fixing a draft that buries the answer or reads AI-padded. NOT keyword research or topic selection (that is `seo-geo`), NOT the editorial calendar (that is `content-engine`)."
 tags: [article, blog, long-form, seo-writing, geo, on-page, eeat, copywriting]
 recommends: [seo-geo, content-engine, brand-voice, landing-copy, technical-writing, case-studies]
 origin: risco
@@ -12,15 +12,6 @@ Draft one long-form article end to end: the prose **and** the on-page surface th
 
 You own a single finished article. You do not pick the topic, build the calendar, or define the house voice — those are siblings below.
 
-## When to use
-
-- Drafting a blog post or long-form article from a topic or a target query.
-- Turning a brief or outline into finished, publishable prose at the right depth.
-- Writing the answer-first lede — the first ~200 words that fully answer the primary query.
-- Restructuring a rambling draft into a question-shaped H2/H3 hierarchy.
-- Writing the on-page surface: title tag, meta description, H1, slug, FAQ section, and Article/FAQPage JSON-LD.
-- Cutting an AI-tell, fluff-padded draft down to the depth the query actually needs.
-
 ## When NOT to use
 
 | You want… | Go to |
@@ -109,14 +100,6 @@ Every article ships with these. Keep them in the file's front-matter or a clearl
 - **Slug**: short, lowercase, hyphenated, keyword-bearing, no stop-word noise — `/compost-in-apartment` not `/how-to-start-composting-in-your-apartment-today`.
 - **FAQ block**: 3–6 real questions from "People also ask", each answered in 2–4 sentences.
 
-Quick checklist:
-
-- [ ] Title 50–60 chars, keyword in first ~35
-- [ ] Meta 140–160 chars, value-first
-- [ ] Exactly one H1
-- [ ] Slug short + keyword-bearing
-- [ ] FAQ questions match visible page content
-
 Full pixel/char tables, slug rules, and copy-ready `Article`/`BlogPosting` + `FAQPage` JSON-LD (JSON-LD only — never microdata) live in [`references/on-page-seo.md`](references/on-page-seo.md). The JSON-LD must describe what is actually on the page; schema that does not match visible content is a quality flag, not a win.
 
 ## Internal links and topical authority

package/skills/astro/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: astro
-description: "Use when building a content-driven or marketing site with Astro 6 — static-first pages, islands, content collections, partial hydration, server islands, per-route on-demand rendering, and deploy adapters. Triggers: 'Astro blog with content collections', 'make this widget interactive only when it scrolls into view', 'server island to personalize a static page', 'migrate Astro 5 to 6', the non-obvious 'ship zero JS but keep one form interactive', and Catalan/Spanish 'web de marketing rápida con Astro' / 'una web de contingut amb Astro'. NOT app-router React or server actions (that is nextjs)."
+description: "Use when building a content-driven or marketing site with Astro 6: static-first pages, islands and partial hydration, content collections, server islands, per-route on-demand rendering, deploy adapters, and Astro 5→6 migration. NOT app-router React with server actions and heavy client interactivity (that is `nextjs`)."
 tags: [astro, ssg, islands, content-collections, partial-hydration, marketing-site, frameworks]
 recommends: [landing-copy, seo-geo, vercel, cloudflare, netlify]
 origin: risco
@@ -8,41 +8,31 @@ origin: risco
 
 # Astro 6 — static-first sites, islands, content collections
 
-> Build fast content and marketing sites with Astro 6: ship zero client JS by default, hydrate the
-> smallest possible surface, model content with type-safe collections, deploy static or hybrid.
-
 ## The prime directive
 
 **Ship zero client JavaScript by default. Hydrate the smallest possible surface, as late as you can
-get away with.** Every island is a JS bundle the visitor downloads, parses, and executes — marketing
-and content sites win on TTFB/LCP and Lighthouse, not on React-everywhere. An `.astro` component
-renders to HTML at build time and ships *no* runtime. Only reach for an interactive island when a
-piece of UI genuinely needs client state, effects, or event handlers.
-
-If you find yourself adding `client:load` to make a page "work," stop — the page already works; you
-are adding interactivity, and interactivity is the expensive exception, not the default.
+get away with.** An `.astro` component renders to HTML at build time and ships *no* runtime; every
+island is a bundle the visitor downloads, parses, and executes. Content and marketing sites win on
+TTFB/LCP and Lighthouse, not on React-everywhere. If you find yourself adding `client:load` to make
+a page "work," stop — the page already works; you are adding interactivity, and interactivity is the
+expensive exception, not the default.
 
 ## First: detect the project version
 
-Astro 6.0 is stable (released 2026-03-10); the Astro 5 line is still production-ready. Do not mix
-advice across majors. Every v6-only claim below is sourced to the official release post or the
-upgrade guide — cited inline so you can re-check before acting.
-
-1. Read `package.json` → the `astro` version.
-2. Astro 6 **requires Node `22.12.0` or higher** (Node 18 and 20 are dropped) — verbatim floor from
-   the [upgrade-to-v6 guide](https://docs.astro.build/en/guides/upgrade-to/v6/). Check the runtime.
-3. v6 content config lives at `src/content.config.ts`. The legacy `src/content/config.ts` path is
-   **removed**, not merely discouraged: the v6 upgrade guide instructs you to "Rename and move this
-   file to `src/content.config.ts`," and the old auto-detection (with the `legacy.collections` flag)
-   is gone. A temporary `legacy.collectionsBackwardsCompat` escape hatch exists but is a migration
-   crutch, not a supported layout.
-4. v6 ships **Vite 7** (Vite v7.0), **Zod 4** for content schemas (imported from `astro/zod`, **not**
-   `astro:content` — see Content collections below), and makes **Live Content Collections**, the
-   **Fonts API**, and the **CSP API** stable. Sources: [Astro 6.0 release post,
-   2026-03-10](https://astro.build/blog/astro-6/) and the
-   [upgrade-to-v6 guide](https://docs.astro.build/en/guides/upgrade-to/v6/). (v6 also ships an
-   *experimental* Rust compiler succeeding the Go one — experimental, so do not rely on or configure
-   it in production advice.)
+Astro 6.0 is stable ([released 2026-03-10](https://astro.build/blog/astro-6/)); the Astro 5 line is
+still production-ready. Do not mix advice across majors — read `package.json` → the `astro` version
+before advising. What v6 changes, per the
+[upgrade-to-v6 guide](https://docs.astro.build/en/guides/upgrade-to/v6/):
+
+- **Node `22.12.0` or higher is required** (18 and 20 are dropped) — check the actual runtime.
+- Content config lives at `src/content.config.ts`. The legacy `src/content/config.ts` path is
+  **removed**, not merely discouraged, and the old auto-detection (`legacy.collections`) is gone.
+  The `legacy.collectionsBackwardsCompat` escape hatch is a migration crutch, not a supported layout.
+- **Vite 7** and **Zod 4** for content schemas — `z` is imported from `astro/zod`, **not**
+  `astro:content` (see Content collections below).
+- **Live Content Collections**, the **Fonts API** and the **CSP API** are stable.
+- The Rust compiler succeeding the Go one is *experimental* — do not rely on or configure it in
+  production advice.
 
 ## Decision table — what kind of thing is this?
 
@@ -160,8 +150,8 @@ const { Content } = await render(post);
 ```
 
 Built-in loaders are `glob()` (many files) and `file()` (one JSON/YAML array). Custom and CMS
-loaders, collection references, Live Content Collections (real-time data with no rebuild, stable in
-v6), and MDX details → `references/content-layer.md`.
+loaders, Zod 4 schema patterns, collection references, Live Content Collections (real-time data with
+no rebuild, stable in v6), querying and MDX details → `references/content-layer.md`.
 
 ## Server islands
 
@@ -202,14 +192,13 @@ npx astro add react mdx sitemap
 
 - **Tailwind 4** wires through the official **Vite plugin** (`@tailwindcss/vite`), not the legacy
   `@astrojs/tailwind` integration (that path was for Tailwind 3).
-- **Fonts API** (stable in v6 per the [Astro 6.0 release post,
-  2026-03-10](https://astro.build/blog/astro-6/)) self-hosts and optimizes fonts from
-  `astro.config.mjs` — no manual `@font-face`.
-- **CSP API** (stable in v6, same release) emits a Content-Security-Policy with hashes for your
-  inline scripts/styles.
+- **Fonts API** (stable in v6) self-hosts and optimizes fonts from `astro.config.mjs` — no manual
+  `@font-face`.
+- **CSP API** (stable in v6) emits a Content-Security-Policy with hashes for your inline
+  scripts/styles.
 
-Adapter recipes, env handling, and SSR endpoints (`src/pages/api/*.ts`) →
-`references/deploy-and-integrations.md`.
+Adapter recipes per platform, hybrid rendering, env handling, SSR endpoints (`src/pages/api/*.ts`)
+and the Fonts/CSP config → `references/deploy-and-integrations.md`.
 
 ## Performance rules
 
@@ -235,9 +224,9 @@ npx @astrojs/upgrade
       legacy path is removed, not just deprecated).
 - [ ] Full guide (dated 2026): `docs.astro.build/en/guides/upgrade-to/v6`.
 
-## Anti-patterns → STOP
+## Anti-patterns
 
-| Rationalization                                          | Reality / STOP                                                              |
+| Anti-pattern                                             | Reality                                                                     |
 | -------------------------------------------------------- | --------------------------------------------------------------------------- |
 | "Add `client:load` so the page works"                    | An `.astro` page already works statically; you're shipping JS for nothing   |
 | "`client:load` everywhere, simplest"                     | Pick `client:visible`/`idle`/`media`; first-paint JS is the LCP killer       |
@@ -251,19 +240,12 @@ npx @astrojs/upgrade
 
 ## Verify
 
-Run `bash scripts/verify.sh` from the Astro project root. It is grep-based and needs no install: it
-**FAILS** if a v6 project still has `src/content/config.ts` instead of `src/content.config.ts`,
-**WARNS** on over-hydration smells (many `client:load`, or `client:only` with no framework string),
-**CHECKS** that content schemas import from `astro:content`, and — only if the `astro` binary
-resolves — optionally runs `npx astro check`. On an empty or clean tree it prints OK and exits 0;
-warnings are advisory and never fail the run.
-
-## References
-
-- `references/content-layer.md` — loaders (`glob`/`file`/custom/CMS), Zod 4 schema patterns,
-  collection references, Live Content Collections, querying & rendering, MDX.
-- `references/deploy-and-integrations.md` — adapter table per platform, hybrid rendering, SSR
-  endpoints, env handling, `astro add` recipes, Fonts API & CSP API config.
+`bash scripts/verify.sh` from the Astro project root — grep-based, needs no install. It **FAILS** if
+a v6 project still has `src/content/config.ts` instead of `src/content.config.ts`, **WARNS** on
+over-hydration smells (many `client:load`, or `client:only` with no framework string), **CHECKS**
+that content schemas import from `astro:content`, and — only if the `astro` binary resolves —
+optionally runs `npx astro check`. On an empty or clean tree it prints OK and exits 0; warnings are
+advisory and never fail the run.
 
 ## See Also