wip

.agents/skills/prisma-postgres/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: prisma-postgres
+description: Prisma Postgres setup and operations guidance across Console, create-db CLI, Management API, and Management API SDK. Use when creating Prisma Postgres databases, working in Prisma Console, provisioning with create-db/create-pg/create-postgres, or integrating programmatic provisioning with service tokens or OAuth.
+license: MIT
+metadata:
+  author: prisma
+  version: "7.9.1"
+---
+
+# Prisma Postgres
+
+Guidance for creating, managing, and integrating Prisma Postgres across interactive and programmatic workflows.
+
+## When to Apply
+
+Reference this skill when:
+- Setting up Prisma Postgres from Prisma Console
+- Provisioning instant temporary databases with `create-db`
+- Linking an existing local project with `prisma postgres link`
+- Managing Prisma Postgres resources via Management API
+- Using `@prisma/management-api-sdk` in TypeScript/JavaScript
+- Handling claim URLs, connection strings, regions, and auth flows
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | CLI Provisioning | CRITICAL | `create-db-cli` |
+| 2 | Management API | CRITICAL | `management-api` |
+| 3 | Management API SDK | HIGH | `management-api-sdk` |
+| 4 | Console and Connections | HIGH | `console-and-connections` |
+
+## Quick Reference
+
+- `create-db-cli` - instant databases and current CLI flags (`--ttl`, `--copy`, `--quiet`, `--open`)
+- `management-api` - service token and OAuth API workflows
+- `management-api-sdk` - typed SDK usage with token storage
+- `console-and-connections` - Console operations, `prisma postgres link`, direct TCP connections, and serverless-driver choices
+
+## Core Workflows
+
+### 1. Console-first workflow
+
+Use Prisma Console for manual setup and operations:
+
+- Open `https://console.prisma.io`
+- Create/select workspace and project
+- Use Studio in the project sidebar to view/edit data
+- Retrieve direct connection details from the project UI
+
+### 2. Quick provisioning with create-db
+
+Use `create-db` when you need a database immediately:
+
+```bash
+npx create-db@latest
+```
+
+Aliases:
+
+```bash
+npx create-pg@latest
+npx create-postgres@latest
+```
+
+For app integrations, you can also use the programmatic API (`create()` / `regions()`) from the `create-db` npm package.
+
+Temporary databases auto-delete after ~24 hours unless claimed.
+
+### 2b. Persistent databases with the Platform CLI
+
+For databases that belong to a Project (not throwaway `create-db` databases), use `@prisma/cli`:
+
+```bash
+npx -y @prisma/cli@latest database create --help
+npx -y @prisma/cli@latest database list --json
+npx -y @prisma/cli@latest database connection create db_123
+npx -y @prisma/cli@latest database usage db_123
+npx -y @prisma/cli@latest database backup list db_123
+```
+
+`database create` and `database connection create` print a one-time connection URL; store it immediately. Destructive commands (`remove`, `restore`) require exact `--confirm <id>`.
+
+For automation, prefer `--json --no-interactive`, resolve ids before mutations, and verify the installed command's help because this CLI is beta.
+
+### 3. Link an existing local project
+
+Use `prisma postgres link` when the database already exists and you want to wire a local project to it:
+
+```bash
+prisma postgres link
+```
+
+For CI or other non-interactive environments:
+
+```bash
+prisma postgres link --api-key "<your-api-key>" --database "db_..."
+```
+
+This flow updates your local `.env` with `DATABASE_URL`, then you can run `prisma generate` and `prisma migrate dev`.
+
+### 4. Programmatic provisioning with Management API
+
+Use API endpoints on:
+
+```text
+https://api.prisma.io/v1
+```
+
+Explore the schema and endpoints using:
+
+- OpenAPI docs: `https://api.prisma.io/v1/doc`
+- Swagger Editor: `https://api.prisma.io/v1/swagger-editor`
+
+Auth options:
+
+- Service token (workspace server-to-server)
+- OAuth 2.0 (act on behalf of users)
+
+### 5. Type-safe integration with Management API SDK
+
+Install and use:
+
+```bash
+npm install @prisma/management-api-sdk
+```
+
+Use `createManagementApiClient` for existing tokens, or `createManagementApiSdk` for OAuth + token refresh.
+
+The SDK exposes typed workspace service-token list, create, and revoke routes. A newly created token value is returned exactly once. Let the installed SDK types or OpenAPI document settle exact beta endpoint shapes.
+
+## Rule Files
+
+Detailed guidance lives in:
+
+```
+references/console-and-connections.md
+references/create-db-cli.md
+references/management-api.md
+references/management-api-sdk.md
+```
+
+## How to Use
+
+Start with `references/create-db-cli.md` for fast setup, then switch to `references/management-api.md` or `references/management-api-sdk.md` when you need programmatic provisioning.

.agents/skills/prisma-postgres/references/console-and-connections.md

@@ -0,0 +1,69 @@
+# console-and-connections
+
+Use Prisma Console workflows for project visibility, data inspection, and connection setup.
+
+## Priority
+
+HIGH
+
+## Why It Matters
+
+Many Prisma Postgres tasks are quickest in the Console: viewing Studio data, checking metrics, and retrieving connection details. This avoids unnecessary API or CLI work for simple operational tasks.
+
+## Console workflow
+
+1. Open `https://console.prisma.io`.
+2. Select workspace and project.
+3. Use dashboard metrics for usage and billing visibility.
+4. Open the **Studio** tab in the sidebar to inspect and edit data.
+
+## Local Studio
+
+You can also inspect data locally:
+
+```bash
+npx prisma studio
+```
+
+## Linking an existing project
+
+If the Prisma Postgres database already exists, link the local project instead of provisioning a new one:
+
+```bash
+prisma postgres link
+```
+
+For CI or non-interactive usage:
+
+```bash
+prisma postgres link --api-key "<your-api-key>" --database "db_..."
+```
+
+This command updates or creates `.env` with `DATABASE_URL`. If the project is already linked, use `--force` to re-link. After linking, run `prisma generate`, then `prisma migrate dev` if you need to apply the schema.
+
+## Connection setup
+
+For direct PostgreSQL tools and drivers:
+
+- Generate/copy direct connection credentials from the project connection UI.
+- Use the resulting PostgreSQL URL as `DATABASE_URL` for `pg` and `@prisma/adapter-pg`.
+- For Prisma Postgres direct TCP, include `sslmode=require`.
+
+Typical direct TCP format:
+
+```env
+DATABASE_URL="postgres://identifier:key@db.prisma.io:5432/postgres?sslmode=require"
+```
+
+Management API connection responses expose both `endpoints.direct` (`db.prisma.io:5432`) and `endpoints.pooled` (`pooled.db.prisma.io:5432`); prefer those fields over the deprecated flat `connectionString`. Connection secrets are shown once at creation (one-time view); store them immediately.
+
+## Adapter choices
+
+- Standard Node.js apps: prefer `@prisma/adapter-pg` with the direct TCP URL above.
+- Edge/serverless runtimes: use `@prisma/adapter-ppg` with `@prisma/ppg` only when you specifically need the Prisma Postgres serverless driver.
+
+## References
+
+- [Prisma Postgres overview](https://www.prisma.io/docs/postgres/introduction/overview)
+- [Viewing data](https://www.prisma.io/docs/postgres/integrations/viewing-data)
+- [Direct connections](https://www.prisma.io/docs/postgres/database/direct-connections)

.agents/skills/prisma-postgres/references/create-db-cli.md

@@ -0,0 +1,136 @@
+# create-db-cli
+
+Use `create-db` for instant Prisma Postgres provisioning from the terminal.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+`create-db` is the fastest way to get a working Prisma Postgres instance for development, demos, and CI previews. It can also emit machine-readable output and write env variables directly.
+
+## Commands
+
+```bash
+npx create-db@latest
+npx create-db@latest create [options]
+npx create-db@latest regions
+```
+
+Aliases:
+
+```bash
+npx create-pg@latest
+npx create-postgres@latest
+```
+
+## Command discovery (`--help`)
+
+Always use `--help` first when integrating CLI commands:
+
+```bash
+npx create-db@latest --help
+npx create-db@latest create --help
+npx create-db@latest regions --help
+```
+
+Top-level commands currently exposed:
+
+- `create` (default) to provision a database
+- `regions` to list available regions
+
+## `create` options
+
+| Flag | Shorthand | Description |
+|---|---|---|
+| `--region [string]` | `-r` | Region choice: `ap-southeast-1`, `ap-northeast-1`, `eu-central-1`, `eu-west-3`, `us-east-1`, `us-west-1` |
+| `--interactive [boolean]` | `-i` | Open region selector |
+| `--json [boolean]` | `-j` | Output machine-readable JSON |
+| `--env [string]` | `-e` | Write `DATABASE_URL` and `CLAIM_URL` into a target `.env` |
+| `--ttl [string]` | `-t` | Auto-delete after a TTL like `30m` or `1h-24h` |
+| `--copy [boolean]` | `-c` | Copy the connection string to the clipboard |
+| `--quiet [boolean]` | `-q` | Only print the connection string |
+| `--open [boolean]` | `-o` | Open the claim URL in your browser |
+
+## Lifecycle and claim flow
+
+- Databases are temporary by default.
+- Unclaimed databases are auto-deleted after ~24 hours.
+- Claim the database using the URL shown in command output to keep it permanently.
+
+## Programmatic usage (library API)
+
+You can also use `create-db` programmatically in Node.js/Bun instead of shelling out to the CLI.
+
+Install:
+
+```bash
+npm install create-db
+# or
+bun add create-db
+```
+
+Create a database:
+
+```ts
+import { create, isDatabaseSuccess, isDatabaseError } from "create-db";
+
+const result = await create({
+  region: "us-east-1",
+  userAgent: "my-app/1.0.0",
+});
+
+if (isDatabaseSuccess(result)) {
+  console.log(result.connectionString);
+  console.log(result.claimUrl);
+  console.log(result.deletionDate);
+}
+
+if (isDatabaseError(result)) {
+  console.error(result.error, result.message);
+}
+```
+
+List regions programmatically:
+
+```ts
+import { regions } from "create-db";
+
+const available = await regions();
+console.log(available);
+```
+
+Programmatic `create()` defaults to `us-east-1` if no region is passed.
+
+## Common patterns
+
+```bash
+# quick database
+npx create-db@latest
+
+# region-specific database
+npx create-db@latest --region eu-central-1
+
+# interactive region selection
+npx create-db@latest --interactive
+
+# write env vars for app bootstrap
+npx create-db@latest --env .env
+
+# auto-delete sooner
+npx create-db@latest --ttl 2h
+
+# copy connection string to clipboard
+npx create-db@latest --copy
+
+# print only the connection string
+npx create-db@latest --quiet
+
+# CI-friendly output
+npx create-db@latest --json
+```
+
+## References
+
+- [npx create-db docs](https://www.prisma.io/docs/postgres/introduction/npx-create-db)

.agents/skills/prisma-postgres/references/management-api-sdk.md

@@ -0,0 +1,70 @@
+# management-api-sdk
+
+Use `@prisma/management-api-sdk` for typed API integration with optional OAuth and token refresh.
+
+The Platform API evolves independently from Prisma ORM. Inspect the installed package's generated `api.d.ts` for exact paths and request/response shapes.
+
+## Priority
+
+HIGH
+
+## Why It Matters
+
+The SDK provides typed endpoint methods and removes boilerplate around auth and refresh handling, which reduces errors in production provisioning flows.
+
+## Install
+
+```bash
+npm install @prisma/management-api-sdk
+```
+
+## Simple client (existing token)
+
+```typescript
+import { createManagementApiClient } from '@prisma/management-api-sdk'
+
+const client = createManagementApiClient({ token: process.env.PRISMA_SERVICE_TOKEN! })
+const { data: workspaces } = await client.GET('/v1/workspaces')
+```
+
+Check the generated client result before using `data`; typed clients surface HTTP failures separately. Never log a full response from connection/key creation because it may contain one-time credentials.
+
+## Workspace service tokens
+
+The typed client exposes routes to list, create, and revoke workspace service tokens:
+
+- `GET /v1/workspaces/{workspaceId}/service-tokens`
+- `POST /v1/workspaces/{workspaceId}/service-tokens`
+- `DELETE /v1/workspaces/{workspaceId}/service-tokens/{serviceTokenId}`
+
+Creation accepts a display `name`. The response's `data.value` is the complete token and is returned exactly once; transfer it directly to the intended secret store without logging the response. Later list calls return metadata and `valueHint`, not the token value. Treat revocation as destructive and resolve both ids explicitly.
+
+## Full SDK (OAuth + refresh)
+
+```typescript
+import { createManagementApiSdk, type TokenStorage } from '@prisma/management-api-sdk'
+
+const tokenStorage: TokenStorage = {
+  async getTokens() { return null },
+  async setTokens(tokens) {},
+  async clearTokens() {},
+}
+
+const api = createManagementApiSdk({
+  clientId: process.env.PRISMA_CLIENT_ID!,
+  redirectUri: 'https://your-app.com/auth/callback',
+  tokenStorage,
+})
+```
+
+## OAuth SDK flow
+
+1. Call `getLoginUrl()` and persist `state` + `verifier`.
+2. Redirect user to login URL.
+3. Handle callback with `handleCallback()`.
+4. Use `api.client` for typed endpoint calls.
+5. Call `logout()` when needed.
+
+## References
+
+- [Management API SDK docs](https://www.prisma.io/docs/postgres/introduction/management-api-sdk)

.agents/skills/prisma-postgres/references/management-api.md

@@ -0,0 +1,79 @@
+# management-api
+
+Use Prisma Management API for programmatic provisioning and workspace/project/database management.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+When you need backend automation, multi-tenant onboarding flows, or controlled resource provisioning, the Management API is the source of truth and is more reliable than interactive workflows.
+
+## Base URL
+
+```text
+https://api.prisma.io/v1
+```
+
+## API exploration
+
+- OpenAPI docs: `https://api.prisma.io/v1/doc`
+- Swagger Editor: `https://api.prisma.io/v1/swagger-editor`
+
+## Authentication methods
+
+- Service token: best for server-to-server operations in your own workspace
+- OAuth 2.0: best for acting on behalf of users across workspaces
+
+## Service token flow
+
+1. Create token in Prisma Console workspace settings.
+2. Send token as Bearer auth:
+
+```text
+Authorization: Bearer $TOKEN
+```
+
+## OAuth flow summary
+
+1. Redirect user to `https://auth.prisma.io/authorize` with `client_id`, `redirect_uri`, `response_type=code`, and scopes.
+2. Receive `code` on callback.
+3. Exchange code at `https://auth.prisma.io/token`.
+4. Use returned access token in Management API requests.
+
+## Resource model
+
+Workspace -> Project -> Branch -> Database. Branches are a first-class resource: databases attach to a Branch, and branch-scoped env/databases are how preview isolation works.
+
+## Current resource inventory
+
+The 1.55 OpenAPI surface includes:
+
+- workspaces, subscriptions, workspace integrations, workspace service tokens, and current-user metadata
+- projects, transfers, project databases, and project/branch environment variables
+- branches under a project plus branch get/update/delete operations
+- databases, usage, backups, restore, connections, and connection rotation
+- apps, deployments, promotion/rollback, runtime logs, domains, and build logs
+- buckets and bucket keys
+- source repositories, SCM installations/install intents, and repositories
+- integrations and regions
+
+App/deployment, branch mutation, SCM, and bucket routes include experimental surfaces. Read the installed SDK types or live OpenAPI before building durable automation around them.
+
+Connection create/rotate responses reveal credentials once. Later reads redact or omit the secret, so store the URL immediately. Use the structured direct/pooled endpoint returned by the concrete operation; do not assume a historical flat response shape.
+
+Workspace service-token creation also returns the complete token value exactly once. List calls expose only metadata and a `valueHint`; delete revokes the token. Keep workspace and token ids opaque, and never log a create response.
+
+Database create supports explicit project, region, branch, and source context. A source may be empty, a backup, or another database. Backup records are incremental; rely on current fields and documented units rather than old full-backup examples.
+
+## Notes
+
+- Management API mutation responses may include direct connection credentials; treat the entire response as secret until redacted.
+- Prefer an API-provided connection string over manually assembling one from fields.
+
+## References
+
+- [Management API docs](https://www.prisma.io/docs/postgres/introduction/management-api)
+- [OpenAPI docs](https://api.prisma.io/v1/doc)
+- [Swagger Editor](https://api.prisma.io/v1/swagger-editor)