@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/plan/references/plan-template.md

@@ -0,0 +1,153 @@
+# Plan artifact template
+
+Copy this skeleton into `02-DOCS/wiki/sdd/plans/<slug>.md` and fill every section. The `<slug>`
+must match the spec's slug exactly — one plan per spec, same name. Delete the parenthetical
+guidance once a section is written; never leave an empty section (an empty section is a `tasks`
+phase that can't find its input). Keep everything at the *structure* altitude: contracts, shapes,
+flows, levels — not framework syntax.
+
+---
+
+```markdown
+---
+type: plan
+title: Plan — <feature name>
+description: The structure-level implementation plan for <feature> — contracts, shapes, flows.
+tags: [sdd, plan]
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+topic: sdd
+slug: <slug>
+status: draft
+---
+
+# Plan — <feature name>
+
+> Spec: [../specs/<slug>.md](../specs/<slug>.md) · Constitution: [../constitution.md](../constitution.md) · Status: draft | approved
+> Last updated: YYYY-MM-DD
+
+## 0. Global Constraints
+
+(The project-wide rules that EVERY task implicitly includes — copied **verbatim** from the spec
+and constitution, with exact values, not paraphrased. A context-isolated implementer only sees its
+own task, so anything not stated here or in a task's Interfaces block is invisible to it. This is
+also the **reviewer's attention lens**: the per-task reviewer reads these first and treats a
+violation as a finding. Keep it to hard, checkable values — version floors, naming/copy rules,
+authorship, framework canon, security/compliance bars. If a value matters, write the value, not
+"per the spec".)
+
+- **<Category>:** <exact value> (e.g. "Node ≥ 20", "all amounts in cents (integer)", "no
+  Co-Authored-By footer", "error envelope `{ code, message }` everywhere").
+- …
+
+## 1. Context & constraints
+
+(One or two lines each. Cite, don't re-paste, the spec and constitution.)
+
+- Acceptance criteria that shape the design: spec §Acceptance #1, #3 …
+- Non-functional bars: latency / throughput / scale / data residency …
+- Constitution rules in play: stack canon, quality bar, naming/convention rules …
+- Out of scope (from the spec) that the design must NOT creep into:
+
+## 2. Architecture
+
+(Box-and-arrow diagram + one sentence of single-responsibility per component. Mark each
+component as INTERNAL or EXTERNAL. The arrows are the seams you'll test and parallelize.)
+
+```text
+[ component A ] --<protocol>--> [ component B ]
+       |
+       v
+[ store / external ]
+```
+
+- **<component>** (internal/external) — single responsibility.
+- …
+
+**Top architectural decision:** <the one choice that matters> — chosen because <reason tied to a
+constraint above>. (If two designs are viable, state both, the trade-off, and the recommendation.)
+
+## 3. Interfaces & contracts
+
+(One block per seam. Operation, inputs → outputs incl. error modes, invariants. Language-neutral.)
+
+```text
+<component>.<operation>(<input>: <Type>) -> <Success> | <Error1> | <Error2>
+  - invariant: idempotent on … / transactional / ordered / …
+  - precondition: …
+  - postcondition: …
+```
+
+## 4. Data model & flow
+
+(Entities at the model level — key fields and relationships, not DDL. Then trace one primary
+scenario end to end. Concrete schema/indexes/migrations → ../<stack>/SKILL.md.)
+
+**Entities**
+
+- **<Entity>** — key fields; relationship to <Entity>.
+
+**Primary flow** (`<scenario from spec>`)
+
+1. <entry> receives <input> →
+2. <component> does <X>, reads/writes <store> →
+3. … → returns <output>.
+
+- Consistency boundaries: <what's transactional together> / <what's eventually consistent>.
+- Migration impact: new table? new column? backfill? destructive?
+
+## 5. Testing strategy
+
+(Per acceptance criterion: the level that proves it, what it asserts, what it fakes. Levels:
+unit / contract / integration / e2e. Tooling is the stack skill's job — name the strategy here.)
+
+| Acceptance criterion | Level | Asserts | Fakes / mocks |
+| --- | --- | --- | --- |
+| spec §Acceptance #1 | unit | … | … |
+| spec §Acceptance #2 | integration | … | … |
+
+- Where the e2e line is, and why.
+- What MUST be a real dependency (not mocked) for the test to mean anything.
+
+## 6. Sequencing & dependencies
+
+(Ordered, independently-verifiable steps. Mark serial vs. parallelizable. This becomes the
+`tasks` list.)
+
+1. <step> — depends on: none — [serial | parallelizable]
+2. <step> — depends on: #1 — …
+
+- Parallel candidates (disjoint scope, no shared state): #…, #… (fan-out via the parallel phase)
+- Hard ordering constraints and why.
+
+## 7. Risks & open decisions
+
+**Risks** (ranked, most likely/impactful first)
+
+| Risk | Trigger | Impact | Mitigation / spike to retire it |
+| --- | --- | --- | --- |
+| … | … | … | … |
+
+**Open decisions** (still genuinely undecided)
+
+- <decision> — closes when <input/answer> arrives. (Significant decisions taken during planning
+  go to ../decisions.md as well.)
+```
+
+---
+
+## Notes on filling it
+
+- **Altitude check.** If a section contains real framework code, you've dropped too low — restate
+  it as a contract or a flow and let the stack skill render it at `implement`.
+- **Citations over copies.** Reference `spec §…` and `constitution §…`; the plan is a derivative
+  view, not a duplicate. Duplicated text drifts out of sync.
+- **One decision, defended.** The architecture section's job is to make the load-bearing call and
+  defend it, not to enumerate every option without choosing.
+- **Empty section = defect.** Every one of the seven must say something real before `tasks` runs.
+  If a section genuinely has no content (e.g. no migration), write "none — <why>", not silence.
+- **Index it.** After writing, add the plan to the root `CLAUDE.md` `## Knowledge map` so the
+  harness wiki and later phases can find it.
+- **Global Constraints carry the verbatim values.** §0 is not a summary of §1 — §1 explains *which*
+  constraints shape the design and *why*; §0 lists the exact values a blind implementer and the
+  reviewer must honor. A value that lives only in prose ("use the project's naming rule") is a value
+  the isolated worker can't see. Put it in §0, exact.

package/skills/shared/planetscale/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: planetscale
+description: "Use when operating PlanetScale (Vitess serverless MySQL) — branches and the `pscale` CLI, schema changes through deploy requests (Online DDL cutover, ~30-min revert window), tables without foreign keys, or the edge HTTP driver. NOT MySQL engine work like EXPLAIN or index choice (that is `mysql`), NOT generic migration theory (that is `db-migrations`)."
+tags: [planetscale, vitess, mysql, deploy-requests, serverless-db]
+recommends: [mysql, db-migrations, prisma-orm, drizzle-orm, github-actions, postgresdb]
+origin: ai-hub
+---
+
+# PlanetScale — Vitess serverless MySQL: branches, deploy requests, no FKs
+
+PlanetScale is serverless, MySQL-compatible database-as-a-service built on **Vitess** — the same
+horizontal-scaling layer that runs YouTube. You do not `ALTER TABLE` against production. Schema
+changes live on an isolated **branch** (a full copy of the schema), reach production through a
+**deploy request** (a pull request for your schema), and apply via **Online DDL**: Vitess builds a
+shadow table holding the new schema, replicates rows and in-flight writes old→new with VReplication,
+then **cuts over** with no table lock. Because Online DDL and sharding are the platform's center of
+gravity, you **design without foreign keys** (FKs are now an opt-in but unsharded-only feature). This
+skill owns that workflow — not MySQL the engine.
+
+Heuristic for the boundary: **would this answer be identical on RDS MySQL? Then it is not this skill.**
+
+| When the question is really about | Route to |
+| --- | --- |
+| A slow query, an `EXPLAIN` plan, an index decision, JSON columns, locking | `../mysql/SKILL.md` for MySQL-engine work; `../postgresdb/SKILL.md` when you want the transferable engine reasoning |
+| PostgreSQL engine/design — even PlanetScale's own managed Postgres SQL semantics | `../postgresdb/SKILL.md`. PlanetScale sells Postgres too; this skill is strictly the **Vitess/MySQL branch+deploy-request** flow |
+| Engine-agnostic migration *theory* (expand-contract, backfill ordering) | `../db-migrations/SKILL.md`. Here you get the concrete PlanetScale realization, not the theory |
+| Postgres copy-on-write branches | `../neon/SKILL.md`. Postgres BaaS → `../supabase/SKILL.md` |
+| ORM client ergonomics (Prisma `updateMany`, Drizzle query builder) | `../prisma-orm/SKILL.md` / `../drizzle-orm/SKILL.md`. This skill owns only the PlanetScale-specific knobs those ORMs expose (`relationMode`, serverless driver adapter) |
+
+## Mental model
+
+| PlanetScale concept | Git analogue | What it actually is |
+| --- | --- | --- |
+| Branch | branch | A full, isolated copy of the schema. `main` is your production branch. |
+| Deploy request | pull request | The gate that carries schema from a dev branch to production. |
+| Schema diff | the PR diff | The exact DDL the deploy will run, computed by PlanetScale. |
+| Online DDL | (no git analogue) | Shadow table + VReplication + non-blocking cutover. No `ALTER` lock. |
+| Schema revert | revert commit | A **~30-minute** window after deploy to undo while preserving post-deploy writes. |
+
+The revert window is the one thing people get wrong: it is **not** forever, and it has carve-outs
+(dropped tables/columns and FK-constraint changes are not cleanly revertible). After ~30 minutes the
+deploy is permanent. Plan rollbacks as new forward deploys, not as "I'll just revert later."
+
+## The deploy-request workflow
+
+Production branches should have **safe migrations** enabled — that is what forces every schema change
+through a deploy request instead of letting a raw `ALTER` hit `main`. Production branches are protected
+by default. The full lifecycle (numbered steps, real `pscale` commands):
+
+```bash
+# 0. Install + authenticate (once)
+brew install planetscale/tap/pscale   # or scoop / apt — see pscale docs
+pscale auth login
+
+# 1. Create the database (region close to your app)
+pscale database create my_app --region us-east
+
+# 2. Create a dev branch off production to hold the change
+pscale branch create my_app add-orders-table
+
+# 3. Apply your DDL on the BRANCH, never on main.
+#    Open a MySQL shell scoped to the branch and run your CREATE/ALTER:
+pscale shell my_app add-orders-table
+#    mysql> CREATE TABLE orders (id BIGINT PRIMARY KEY AUTO_INCREMENT, ...);
+#    mysql> ALTER TABLE users ADD COLUMN last_seen_at TIMESTAMP NULL;
+
+# 4. Open a deploy request from the branch back to production.
+#    --disable-auto-apply gates the cutover behind a manual apply (recommended for risky drops).
+pscale deploy-request create my_app add-orders-table --disable-auto-apply
+
+# 5. Inspect the exact schema diff the deploy will run. ALWAYS read this.
+pscale deploy-request diff my_app 42
+
+# 6. Review / approve (the schema-PR review step)
+pscale deploy-request review my_app 42 --approve
+
+# 7. Deploy. PlanetScale runs Online DDL: shadow table -> VReplication -> cutover.
+pscale deploy-request deploy my_app 42
+
+# 8. If you disabled auto-apply, the change waits gated until you apply the cutover:
+pscale deploy-request apply my_app 42
+
+# 9. Verify on production. If wrong, REVERT within the ~30-minute window:
+pscale deploy-request revert my_app 42
+```
+
+**Auto-apply is ON by default.** With it on, step 7 deploys *and* cuts over in one motion. For
+anything destructive — dropping a column/table, narrowing a type — pass `--disable-auto-apply` at
+step 4 so the cutover sits gated (step 8) until a human applies it. That gap is your last cheap exit
+before the revert window starts ticking.
+
+For queued/gated deploys that won't move, lint errors that block a deploy, declarative vs imperative
+schema, and the exact revert carve-outs, see [deploy-requests](references/deploy-requests.md).
+
+## Design without foreign keys
+
+Vitess's first-class features are Online DDL and horizontal sharding. Native foreign keys fight both:
+a cross-shard FK is meaningless once a table is sharded, and FK constraint checks degrade
+high-concurrency writes. PlanetScale **historically disallowed FKs entirely**; they are now an opt-in
+but **unsharded-only** feature. The scale-safe default is **app-level referential integrity** with
+emulated relations, not database-enforced FKs.
+
+```sql
+-- Bad on PlanetScale at scale: a DB-enforced FK with ON DELETE CASCADE.
+-- Blocks sharding, conflicts with Online DDL, and the cascade is a hidden write amplifier.
+CREATE TABLE orders (
+  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
+  user_id   BIGINT NOT NULL,
+  CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
+);
+
+-- Good: no DB FK. Index the relation column, enforce integrity in the app/ORM,
+-- and do cascades explicitly in a transaction or background job.
+CREATE TABLE orders (
+  id        BIGINT PRIMARY KEY AUTO_INCREMENT,
+  user_id   BIGINT NOT NULL,
+  KEY idx_orders_user_id (user_id)   -- the relation still needs its index
+);
+```
+
+With Prisma, declare `relationMode = "prisma"` so the client emulates relations and adds the implicit
+indexes instead of emitting DB-level FKs:
+
+```prisma
+datasource db {
+  provider     = "mysql"
+  url          = env("DATABASE_URL")
+  relationMode = "prisma"
+}
+```
+
+With Drizzle, model the relation in app code (`relations()`), index the join column, and skip the
+`references()`-backed FK constraint at the DB layer.
+
+| Will this table shard? | FK strategy | Notes |
+| --- | --- | --- |
+| Yes, or unsure | No DB FK — emulate in app/ORM | Default. Index the relation column; cascade in code. |
+| Never (small, bounded, unsharded) | Unsharded FK opt-in *is* acceptable | Accept Online DDL friction; document why it won't shard. |
+
+See [no-foreign-keys](references/no-foreign-keys.md) for emulated cascades, ORM specifics, and the opt-in caveats.
+
+## Connecting
+
+Two connection paths. Pick by **runtime**, not by preference.
+
+```ts
+// Direct MySQL string — for Node/long-lived servers that can open a TCP socket.
+// DATABASE_URL=mysql://user:pass@host/db?ssl-mode=require   (TLS required)
+
+// Serverless HTTP driver — for edge/serverless where raw TCP MySQL is blocked.
+import { connect } from "@planetscale/database";
+
+const conn = connect({ url: process.env.DATABASE_URL });
+const result = await conn.execute("SELECT id FROM users WHERE email = ?", [email]);
+```
+
+`@planetscale/database` is Fetch-API compatible: it speaks HTTP, so it works where you cannot open a
+MySQL socket — Cloudflare Workers, Vercel Edge, Lambda. The spelling is exactly `@planetscale/database`;
+there is no other official package name. Drizzle ships a matching adapter,
+`drizzle-orm/planetscale-serverless`, that wraps this driver — see `../drizzle-orm/SKILL.md` for the
+query-builder side.
+
+| Runtime | Connection path | Why |
+| --- | --- | --- |
+| Node server, long-lived process | Direct `mysql://…?ssl-mode=require` | TCP socket available; pool it. |
+| Vercel Edge / Cloudflare Workers | `@planetscale/database` (HTTP) | No raw TCP; the Fetch-based driver works. |
+| AWS Lambda / short-lived serverless | `@planetscale/database` (HTTP) | Avoids per-invocation connection churn. |
+| Drizzle on edge | `drizzle-orm/planetscale-serverless` | Wraps the HTTP driver; same constraints. |
+
+## CI/CD
+
+Wire the deploy-request flow into CI so schema changes are reviewed like code. A GitHub Actions job
+installs `pscale`, authenticates with a service token (`PLANETSCALE_SERVICE_TOKEN` /
+`PLANETSCALE_SERVICE_TOKEN_ID` as secrets), then drives the same verbs you run locally:
+
+```yaml
+# .github/workflows/schema.yml — open + diff a deploy request on PR
+- run: |
+    pscale deploy-request create "$DB" "${{ github.head_ref }}" --disable-auto-apply
+    pscale deploy-request diff   "$DB" "$DR_NUMBER"   # surface the schema diff in the PR
+```
+
+For a **branch-per-PR preview database**, create a PlanetScale branch named after the PR head, run the
+app's migrations against it, and tear the branch down when the PR closes. The orchestration (matrix,
+secrets, cleanup-on-close) is generic CI — defer the Actions plumbing to `../github-actions/SKILL.md`
+and keep the PlanetScale verbs here.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `ALTER TABLE` on the `main` production branch | Skips the gate; no diff, no review, no revert window | Branch → DDL → deploy request → diff → deploy |
+| Relying on DB-enforced foreign keys at scale | Blocks sharding, fights Online DDL, degrades high-concurrency writes | App/ORM-level integrity; `relationMode="prisma"`; index the relation column |
+| Leaving auto-apply ON for a destructive change | Deploy + cutover happen in one motion; no gated last-look before the drop | `--disable-auto-apply`, inspect, then `deploy-request apply` |
+| Opening a direct `mysql://` connection from Vercel Edge / Workers | Raw TCP MySQL is blocked on edge runtimes → connection timeouts | Use `@planetscale/database` HTTP driver |
+| Treating revert as available forever | The window is **~30 min** and excludes dropped tables/cols and FK changes | Plan rollbacks as new forward deploys |
+| Deploying without reading `deploy-request diff` | You ship DDL you never saw; surprise table rewrites | Always run the diff before `deploy` |
+| Inventing a driver name (`@planetscale/serverless`, `planetscale-js`) | There is no such package; install fails | The package is exactly `@planetscale/database` |

package/skills/shared/planetscale/evals/README.md

@@ -0,0 +1,11 @@
+# Evals — planetscale
+
+`cases.yaml` holds prompt-routing checks and capability rubrics for the repo's eval harness. The
+`should_trigger` / `should_not_trigger` entries assert routing: an LLM grader decides whether each
+prompt would invoke the planetscale skill, and the `should_not_trigger` cases name the real sibling it
+should go to instead (mysql, postgresdb, neon, db-migrations, prisma-orm). The `capability` entry is a
+scenario graded against its `must_include` rubric — the model's answer must hit each bullet (dev
+branch, branch-scoped DDL, `pscale deploy-request create`/`diff`, Online DDL shadow-copy/cutover,
+auto-apply vs manual apply, the ~30-minute revert window and its carve-outs, and a no-FK table design).
+No live PlanetScale account, `pscale` CLI, or database is needed — everything is graded from the model's
+text. Run it through the repo's standard eval runner against this directory.

package/skills/shared/planetscale/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: planetscale
+
+should_trigger:
+  - prompt: "How do I make a schema change on PlanetScale without taking the table offline?"
+    why: "Core Online DDL / deploy-request workflow — branch, deploy request, shadow-copy cutover — is the heart of this skill."
+  - prompt: "My deploy request on PlanetScale has been stuck in the queue for ages and won't cut over. What's going on?"
+    why: "Non-obvious stuck-deploy symptom; the skill distinguishes 'still copying via VReplication' from 'gated waiting on apply' and routes to the deploy-requests reference."
+  - prompt: "PlanetScale won't let me add a foreign key. What's the right way to model this relationship?"
+    why: "No-FK design is a named scope; the answer is emulated relations / relationMode, not a generic schema lecture."
+  - prompt: "I'm on Vercel Edge and my MySQL connection to PlanetScale keeps timing out. How do I connect?"
+    why: "Non-obvious: raw TCP MySQL is blocked on edge runtimes; the fix is the @planetscale/database HTTP driver, which is PlanetScale-specific."
+  - prompt: "Necesito cambiar el esquema sin downtime en PlanetScale, ¿cómo lo hago?"
+    why: "Spanish phrasing of the core branch + deploy-request zero-downtime workflow."
+  - prompt: "I deployed a PlanetScale deploy request about 40 minutes ago and need to undo it — can I still revert?"
+    why: "Non-obvious: the ~30-minute revert window has likely closed, and reverts exclude dropped tables/cols and FK changes — a load-bearing nuance of this skill."
+  - prompt: "Set relationMode = prisma for my PlanetScale database and explain why."
+    why: "PlanetScale-specific ORM knob for emulating relations without DB foreign keys; the skill owns this even though Prisma is an ORM."
+
+should_not_trigger:
+  - prompt: "This MySQL query does a full table scan even with an index. How do I make it use the index?"
+    route_to: mysql
+    why: "Engine-level query tuning / index usage — identical answer on RDS MySQL — is the mysql sibling, not the PlanetScale platform workflow."
+  - prompt: "Design my PostgreSQL schema with proper constraints and pick the right column types."
+    route_to: postgresdb
+    why: "Postgres engine design and SQL semantics route to postgresdb, even when PlanetScale also sells managed Postgres."
+  - prompt: "I want Postgres branches for spinning up preview environments per pull request."
+    route_to: neon
+    why: "Postgres copy-on-write branching is Neon's model; PlanetScale branches are Vitess MySQL gated by deploy requests, a different engine and flow."
+  - prompt: "Can you explain how expand-contract migrations work in general, regardless of database?"
+    route_to: db-migrations
+    why: "Engine-agnostic migration theory belongs to db-migrations; this skill is the concrete PlanetScale deploy-request realization."
+  - prompt: "My Prisma Client updateMany returns the wrong count — what is the ORM actually doing?"
+    route_to: prisma-orm
+    why: "ORM client API ergonomics are the prisma-orm sibling; this skill owns only the PlanetScale connector knobs like relationMode."
+
+capability:
+  - scenario: "Walk me through shipping an ADD COLUMN on users plus a new orders table to a production PlanetScale MySQL database with zero downtime and a rollback plan."
+    must_include:
+      - "Creates a dev branch (pscale branch create), not editing main/production directly"
+      - "Applies the DDL on the branch (pscale shell), never against the production branch"
+      - "Opens a deploy request with pscale deploy-request create"
+      - "Runs pscale deploy-request diff and reads it before deploying"
+      - "Explains Online DDL: shadow table + VReplication copy + non-blocking cutover"
+      - "Addresses auto-apply ON by default vs --disable-auto-apply + deploy-request apply for the gated cutover"
+      - "Notes the ~30-minute revert window and that it excludes dropped tables/columns and FK-constraint changes"
+      - "Designs the new orders table without a DB-level foreign key (indexed relation column + app/ORM integrity), or justifies the unsharded FK opt-in"

package/skills/shared/planetscale/references/deploy-requests.md

@@ -0,0 +1,75 @@
+# Deploy requests — lifecycle, gating, lint, reverts
+
+Offloaded depth from SKILL.md §"The deploy-request workflow". The body has the happy path; this file
+covers the states a deploy request moves through, why it stalls, and the revert carve-outs.
+
+## Lifecycle states
+
+A deploy request moves through roughly:
+
+1. **Open** — created from a dev branch against production; PlanetScale has computed a schema diff.
+2. **Approved** — a reviewer ran `pscale deploy-request review … --approve` (or approved in the UI).
+3. **Queued / deploying** — the deploy is submitted; Vitess starts Online DDL (shadow table build +
+   VReplication copy). Large tables spend most of their time here.
+4. **Pending cutover / gated** — if auto-apply was disabled (`--disable-auto-apply`), the copy is done
+   and the change waits for a manual `pscale deploy-request apply` before cutting over.
+5. **Deployed** — cutover complete. The **~30-minute revert window** opens here.
+6. **Reverted** or **permanent** — either reverted within the window, or finalized after it closes.
+
+## Online DDL mechanics
+
+A deploy does not run a blocking `ALTER`. Vitess:
+
+- builds a **shadow table** with the target schema,
+- uses **VReplication** to copy existing rows and continuously apply in-flight writes from old→new,
+- waits for the shadow to catch up (lag → ~0),
+- performs an atomic **cutover**, swapping the shadow in as the live table.
+
+That is why a deploy against a big table can sit in "deploying" for a long time: it is copying rows,
+not stuck. Watch the deploy's progress before assuming it hung.
+
+## Why a deploy is queued / won't cut over
+
+| Symptom | Likely cause | Action |
+| --- | --- | --- |
+| "Queued" for a long time on a large table | VReplication is still copying rows | Wait; check copy progress. It is working, not stuck. |
+| Deployed-but-not-cut-over | Auto-apply disabled; it is gated | Run `pscale deploy-request apply <db> <number>`. |
+| Another deploy already in flight | Deploys serialize per branch | Let the in-flight one finish or revert it first. |
+| Blocked at open with lint errors | The diff violates a schema lint rule | Fix the DDL on the branch, re-diff, re-open. |
+
+## Lint errors
+
+PlanetScale lints the schema diff before it will deploy. Common blockers: a table without a primary
+key (Vitess wants one for VReplication), or unsupported/foot-gun DDL. Resolve by editing the DDL on the
+**branch** (open a `pscale shell`, fix the schema), regenerate the diff, and re-open the deploy request.
+Never try to force a lint failure through.
+
+## Revert carve-outs
+
+The ~30-minute window lets you undo a deploy **while preserving writes that happened after the deploy**
+— for most additive changes. It does **not** cleanly cover:
+
+- **Dropped tables or columns** — the data is gone; a revert cannot resurrect it.
+- **Foreign-key constraint changes** — excluded from clean revert.
+
+After the window closes the deploy is permanent. Treat the window as a safety net for *additive*
+changes, and plan destructive rollbacks (re-adding a dropped column, restoring data) as **new forward
+deploys**, not as reverts.
+
+## Declarative vs imperative schema
+
+Two ways to express the change on a branch:
+
+- **Imperative** — you run the `ALTER`/`CREATE` statements yourself in `pscale shell`; the deploy
+  request diffs branch-vs-production and deploys that diff.
+- **Declarative** — you keep the desired schema in version control and let PlanetScale compute the DDL
+  needed to converge the branch to that target.
+
+Either way the deploy request is the gate and the diff is the contract. Read the diff before deploying.
+
+## Branch protection / safe migrations
+
+Production branches are protected by default. **Safe migrations** on a branch is the setting that
+*requires* the deploy-request flow — it stops raw schema edits from landing directly on the protected
+branch. Keep it on for any branch that fronts production. Dev branches are disposable; protect the one
+that matters.

package/skills/shared/planetscale/references/no-foreign-keys.md

@@ -0,0 +1,88 @@
+# Designing without foreign keys on PlanetScale
+
+Offloaded depth from SKILL.md §"Design without foreign keys". The body has the rule and one Bad→Good
+fence; this file covers emulated cascades, the ORM specifics, and the unsharded opt-in caveats.
+
+## Why FKs fight Vitess
+
+Two of Vitess's first-class features make native FKs a poor default:
+
+- **Horizontal sharding** — a foreign key between rows on different shards has no meaning; the
+  constraint cannot be enforced across the shard boundary.
+- **Online DDL** — FK constraints complicate the shadow-table copy + cutover dance.
+
+On top of that, FK constraint checks add per-write overhead that **degrades high-concurrency
+workloads**. PlanetScale historically disallowed FKs entirely; they are now an **opt-in but
+unsharded-only** feature. So the scale-safe default is app-level referential integrity.
+
+## Emulated relations
+
+You keep the relationship — you just stop asking the database to enforce it.
+
+- **Index the relation column.** A non-FK relation still needs its index for join/lookup performance.
+  `KEY idx_orders_user_id (user_id)`.
+- **Enforce existence in the app/ORM.** Validate that `user_id` points at a real user before insert.
+- **Cascade explicitly.** There is no `ON DELETE CASCADE`. Delete dependents yourself, in a
+  transaction or a background job:
+
+```sql
+-- App-side cascade, in one transaction (or a queued job for large fan-out):
+START TRANSACTION;
+DELETE FROM order_items WHERE order_id IN (SELECT id FROM orders WHERE user_id = ?);
+DELETE FROM orders      WHERE user_id = ?;
+DELETE FROM users       WHERE id = ?;
+COMMIT;
+```
+
+For large fan-out, prefer a batched background job over one giant transaction so you do not hold writes.
+
+## Prisma: relationMode = "prisma"
+
+Setting `relationMode = "prisma"` tells Prisma to emulate relations in the client instead of emitting
+DB-level foreign keys. Prisma then also creates the **implicit indexes** on relation scalar fields that
+a real FK would have given you for free.
+
+```prisma
+datasource db {
+  provider     = "mysql"
+  url          = env("DATABASE_URL")
+  relationMode = "prisma"
+}
+
+model Order {
+  id     BigInt @id @default(autoincrement())
+  userId BigInt
+  user   User   @relation(fields: [userId], references: [id])
+
+  @@index([userId]) // required under relationMode="prisma" — no implicit FK index from the DB
+}
+```
+
+ORM-client ergonomics beyond this knob belong to `../../prisma-orm/SKILL.md`, not here.
+
+## Drizzle: app-level relations
+
+Drizzle models relations in app code via `relations()` and queries them with the relational API. On
+PlanetScale you index the join column and skip the `references()`-backed DB constraint; the relation
+lives in code, not in the database. The query-builder side is `../../drizzle-orm/SKILL.md`.
+
+## The unsharded FK opt-in
+
+Native FKs are available again, but **only on unsharded keyspaces**. It is acceptable to use one when:
+
+- you are certain the table will **never** shard (small, bounded, low-write reference data), and
+- you accept the extra Online DDL friction the FK introduces, and
+- you remember that FK constraint changes are **excluded from clean schema reverts** (see
+  deploy-requests.md).
+
+If any of those is shaky, default back to emulated relations. Document *why* a given table is allowed
+an FK so the next person does not "fix" it.
+
+## Bad → Good patterns
+
+| Pattern | Bad on PlanetScale at scale | Good |
+| --- | --- | --- |
+| Relation | DB `FOREIGN KEY … REFERENCES` | Indexed column + app/ORM-emulated relation |
+| Delete dependents | `ON DELETE CASCADE` | Explicit transactional or batched delete in app code |
+| Index on relation column | Relying on the FK's implicit index | Declare the index yourself (`@@index`, `KEY`) |
+| Integrity guarantee | "the database will reject orphans" | Validate before write; reconcile orphans in a job |