creek 0.4.15 → 0.4.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "creek",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "description": "The Creek deployment platform — CLI and runtime",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
     "react.d.ts",
     "hono.js",
     "hono.d.ts",
+    "skills",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
@@ -50,7 +51,8 @@
     "directory": "packages/creek"
   },
   "dependencies": {
-    "@solcreek/cli": "^0.4.15",
+    "@solcreek/cli": "^0.4.17",
     "@solcreek/runtime": "^0.4.0"
-  }
+  },
+  "scripts": {}
 }

package/skills/README.md

@@ -0,0 +1,74 @@
+# Agent Skills for Creek
+
+[Agent Skills](https://agentskills.io/) for [Creek](https://creek.dev) —
+the deployment platform that ships full-stack apps to the edge with a
+single command and a single semantic resource model.
+
+## Install
+
+```bash
+npx skills add solcreek/creek/skills
+```
+
+The `skills` CLI supports subpath installation, so the skill ships
+directly from the monorepo. No separate distribution repo to sync.
+
+## Available skills
+
+| Skill | Description |
+|-------|-------------|
+| [creek](creek/SKILL.md) | Deploy + diagnose + manage Creek projects — CLI, resources, logs, MCP. |
+
+## Layout
+
+The `creek` skill follows Anthropic's [progressive-disclosure
+guidance](https://code.claude.com/docs/en/skills) — `SKILL.md` stays
+lean (~120 lines with mental model, anti-patterns, quick triage, cheat
+sheet), and topic-focused detail lives in `references/` files that
+Claude loads on demand.
+
+```
+skills/creek/
+├── SKILL.md                     entry + index of references
+└── references/
+    ├── commands.md              full command table + JSON output spec
+    ├── deployment-modes.md      authenticated / sandbox / CI / --from-github
+    ├── workflows.md             first-deploy / rollback / domain, frameworks
+    ├── creek-toml.md            creek.toml reference + cron + queue
+    ├── diagnosis.md             failure workflow + CK-code map + troubleshooting
+    ├── observability.md         creek logs + build logs + MCP get_build_log
+    ├── resources.md             creek db + team-owned databases + portable pattern
+    └── github-setup.md          GitHub App install + connection
+```
+
+## Same content, two surfaces
+
+The `.md` files here are the single source of truth for agent-facing
+guidance. They drive:
+
+1. **Filesystem skill** — installed via `npx skills add`, loaded by
+   Claude Code / Cursor / Codex / OpenCode.
+2. **MCP resources** — `mcp.creek.dev` exposes each reference file
+   as `creek://skill/<name>` via `resources/list` + `resources/read`.
+   Bundled into the MCP worker at deploy time. Serves claude.ai users
+   + API agents that can't load filesystem skills.
+
+Edit the `.md` file once — both surfaces update on next deploy.
+
+## Legacy install URL (deprecated)
+
+The old URL `npx skills add solcreek/skills` is **deprecated**. The
+standalone [`solcreek/skills`](https://github.com/solcreek/skills)
+repo is frozen at its last pre-consolidation snapshot and will be
+archived. Update any install scripts, docs, or READMEs to the
+`solcreek/creek/skills` form above — the content lives here
+alongside the code it describes, so it stays in sync by construction.
+
+## Requires
+
+- [Creek CLI](https://www.npmjs.com/package/creek) (`npm install -g creek`)
+- An authenticated account for production deploys (`creek login`)
+
+## License
+
+Apache-2.0

package/skills/creek/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: creek
+description: |
+  Deploy and manage full-stack apps to the edge with Creek — one
+  command from local code to a live URL. Ship, diagnose failed deploys,
+  read runtime + build logs, manage team-owned databases (creek db),
+  handle custom domains, cron, queues, GitHub push deploys, and local
+  dev. Skill covers Creek's conventions (semantic resource keys,
+  shared schema + split boot pattern, unified sandbox/production code
+  path) plus CK-error code fix hints.
+when_to_use: |
+  Use when the user mentions creek, creek.dev, creek.toml, creek deploy,
+  creek db, creek logs, creek doctor, `npx creek`, or "deploy to the
+  edge". Also use when a user says "my deploy failed" / "deploy to creek
+  didn't work" / "add a database to my creek project" / "why isn't my
+  push deploying" / "can I share a database across projects" / "is my
+  cron running". Pre-emptively load when editing creek.toml or code
+  that imports from @solcreek/*.
+license: Apache-2.0
+compatibility: Requires Creek CLI (npm install -g creek)
+paths:
+  - "**/creek.toml"
+  - "**/examples/vite-react-drizzle/**"
+  - "**/server/{local,worker,routes,schema}.ts"
+metadata:
+  author: solcreek
+  required-binaries: creek
+  required-env: CREEK_TOKEN
+---
+
+# Creek CLI — Agent Skill
+
+Creek deploys full-stack web apps to the edge with a single command.
+Auto-detects framework, determines render mode (SPA/SSR/Worker),
+provisions infrastructure.
+
+## Mental Model
+
+Creek manages the deploy target, bindings, and runtime for you. You
+work with semantic concepts — `database`, `cache`, `storage`, `ai` —
+not infrastructure primitives. The CLI and `@solcreek/runtime` cover
+the concerns you'd normally write glue code for.
+
+Rule of thumb: if you're about to write platform-level glue (editing
+generated config, manually provisioning infra, swapping drivers across
+local/production), check whether `creek` or `@solcreek/runtime` already
+handles it. It almost always does.
+
+## Conventions that matter on first pass
+
+Creek deviates from common deployment heuristics in a few specific
+ways. Getting these right up front avoids dead-end rewrites.
+
+- **Semantic resource keys.** In `creek.toml [resources]`, use
+  `database`, `cache`, `storage`, `ai`. These map to infrastructure
+  automatically. Other names are silently dropped — `creek doctor`
+  flags this with `CK-RESOURCES-KEYS`.
+
+- **Provision via `creek db create <name>`, not platform-specific
+  tooling.** Creates a team-owned resource with a stable UUID that
+  can be renamed, shared across projects, and detached without
+  dropping data. Provisioning outside Creek creates orphaned
+  infrastructure the platform can't track.
+
+- **One code path for sandbox and production.** Env var behavior is
+  identical. Sandbox just runs without user-set secrets. Gate on
+  `env.MY_KEY` being present; don't fork code paths.
+
+- **Shared schema + split boot files for portable DB code.** The
+  recommended shape: one `schema.ts` + one `routes.ts` (driver-agnostic)
+  + thin boot files (`server/local.ts` for local dev, `server/worker.ts`
+  for production) that differ only in driver setup. Never duplicate
+  the schema across local and production files — `creek doctor` flags
+  this with `CK-DB-DUAL-DRIVER-SPLIT`. See `references/resources.md`
+  and `examples/vite-react-drizzle`.
+
+- **`creek.toml` is the source of truth for config.** Creek generates
+  its deploy-target config at build time. Hand-edits to generated
+  files get reverted on next deploy. If an existing project has a
+  legacy config file from another tool, `creek doctor` flags it with
+  `CK-CONFIG-OVERLAP` and guides the reconciliation.
+
+## Quick Triage
+
+Map user phrasing to the right workflow before doing anything else.
+
+| User says / implies | First command |
+|---------------------|--------------|
+| "deploy this" (no context) | `creek deploy --dry-run --json` first, then `creek deploy --json` |
+| "deploy failed" / "something broke" | See `references/diagnosis.md` |
+| "can't see logs" | Is it missing because edge-cached? See `references/observability.md` |
+| "add a database" / "need a DB" (no account) | Sandbox auto-provisions: add `[resources] database = true` to creek.toml. See "Sandbox with DB" below. |
+| "add a database" / "need a DB" (signed in) | `creek db create <name>` + `creek db attach` (see `references/resources.md`) |
+| "how do I run this locally" | `creek dev` |
+| "rollback the last deploy" | `creek rollback --json` |
+| "add a domain" | `creek domains add <host>` + DNS CNAME → `creek domains activate` |
+| "why isn't my push deploying" | See `references/github-setup.md` |
+| "what env vars does it see" | `creek env ls --json` (add `--show` for values) |
+| "is my cron running" | `creek status --json` shows cron schedules |
+
+If the phrasing doesn't match any row, default to `creek doctor --json`
+— it surfaces the most likely misconfiguration.
+
+## Sandbox with DB (no account, 60 min preview)
+
+Sandbox mode auto-provisions a database when `creek.toml` declares
+`[resources] database = true` — no `creek login`, no `creek db create`
+required. The binding name is `DB`. This makes it safe to build a
+DB-backed CRUD demo (e.g. TODO list) and ship a live URL in one step.
+
+```toml
+# creek.toml
+[project]
+name = "todo-app"
+
+[build]
+worker = "worker.ts"      # required for API routes
+output = "public"         # static assets dir (at minimum: index.html)
+
+[resources]
+database = true           # NOT d1 = true — doctor flags that as error
+```
+
+```ts
+// worker.ts
+import { define } from "d1-schema";
+
+export interface Env { DB: D1Database }
+
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    await define(env.DB, {
+      todos: { id: "text primary key", text: "text not null", completed: "integer default 0" },
+    });
+    // ...env.DB.prepare("SELECT * FROM todos").all()
+  },
+};
+```
+
+Constraints to know before starting:
+
+- **`public/index.html` is required.** Sandbox rejects worker-only
+  bundles with `No assets in bundle`. Serve your UI as static + use
+  the worker for `/api/*`.
+- **`creek deploy --dry-run --json` first.** It runs the full
+  doctor check and surfaces `[resources]` typos (e.g. the `d1/kv/r2`
+  vs `database/cache/storage` split) before you burn a deploy.
+- **`creek logs` and `creek doctor --last` need auth**, so runtime
+  errors in sandbox are hard to diagnose. Return JSON errors with a
+  meaningful `message` from your handlers so failures surface via the
+  HTTP response instead.
+
+## Agent Rules
+
+1. **Always use `--json`** for structured output. Auto-enabled in non-TTY / CI.
+2. **Follow `breadcrumbs`** in JSON responses — they suggest the next command.
+3. **Use `--yes`** to skip confirmation prompts (auto-enabled in non-TTY).
+4. **Check `ok` field** — `true` = success, `false` = error with `error` and `message` fields.
+
+## Cheat Sheet
+
+Top commands. Full table in `references/commands.md`.
+
+| Task | Command |
+|------|---------|
+| Authenticate | `creek login` |
+| Deploy | `creek deploy --json` |
+| Dry-run plan (safe, no side effects) | `creek deploy --dry-run --json` |
+| Check status | `creek status --json` |
+| List deployments | `creek deployments --json` |
+| Read a deployment's build log | `creek deployments logs <ID> --json` |
+| Rollback | `creek rollback --json` |
+| Runtime logs | `creek logs --follow --json` |
+| Pre-deploy diagnostic | `creek doctor --json` |
+| Create team database | `creek db create <NAME> --json` |
+
+## Additional Resources
+
+Load on demand. These files live in `references/` and are meant to be
+read via `bash cat` when the task needs the detail.
+
+- `references/commands.md` — complete command table + JSON output spec
+- `references/deployment-modes.md` — authenticated / sandbox / CI / remote-GitHub
+- `references/workflows.md` — first-deploy / update-rollback / custom-domain, framework matrix, config detection order
+- `references/creek-toml.md` — full `creek.toml` reference, cron + queue details
+- `references/diagnosis.md` — failure diagnosis workflow + CK-code fix table + error-string troubleshooting
+- `references/observability.md` — `creek logs` + `creek deployments logs` + MCP `get_build_log` + edge-cache caveats
+- `references/resources.md` — `creek db` + team-owned resource model + portable pattern
+- `references/github-setup.md` — GitHub App install + repo connection

package/skills/creek/references/commands.md

@@ -0,0 +1,79 @@
+# Creek CLI — Command Reference
+
+Complete command table. Pair with `references/workflows.md` for
+common multi-command flows.
+
+| Task | Command |
+|------|---------|
+| Authenticate | `creek login` |
+| Authenticate (CI) | `creek login --token <KEY>` |
+| Check auth | `creek whoami --json` |
+| Init project | `creek init --json` |
+| Deploy | `creek deploy --json` |
+| Deploy directory | `creek deploy ./dist --json` |
+| Deploy from GitHub URL | `creek deploy https://github.com/user/repo --json` |
+| Deploy monorepo subdir | `creek deploy https://github.com/user/repo --path packages/app --json` |
+| Deploy latest commit via GitHub connection | `creek deploy --from-github --json` |
+| Deploy latest (target specific project) | `creek deploy --from-github --project <SLUG> --json` |
+| Deploy demo | `creek deploy --demo --json` |
+| Deploy template | `creek deploy --template vite-react` |
+| Skip build | `creek deploy --skip-build --json` |
+| Check status | `creek status --json` |
+| Check sandbox | `creek status <SANDBOX_ID> --json` |
+| Claim sandbox | `creek claim <SANDBOX_ID> --json` |
+| List projects | `creek projects --json` |
+| List deployments | `creek deployments --json` |
+| List deployments (other) | `creek deployments --project <SLUG> --json` |
+| Rollback | `creek rollback --json` |
+| Rollback to specific | `creek rollback <DEPLOYMENT_ID> --json` |
+| Set env var | `creek env set <KEY> <VALUE> --json` |
+| List env vars | `creek env ls --json` |
+| Show env values | `creek env ls --show --json` |
+| Remove env var | `creek env rm <KEY> --json` |
+| Add domain | `creek domains add <HOSTNAME> --json` |
+| List domains | `creek domains ls --json` |
+| Activate domain | `creek domains activate <HOSTNAME> --json` |
+| Remove domain | `creek domains rm <HOSTNAME> --json` |
+| Send a message to the project queue | `creek queue send '<JSON-BODY>' --json` |
+| Dev server (local) | `creek dev` |
+| Dev server + trigger a cron firing | `creek dev --trigger-cron "*/5 * * * *"` |
+| List team databases | `creek db ls --json` |
+| Create a team database | `creek db create <NAME> --json` |
+| Attach database to project | `creek db attach <NAME> --to <PROJECT> --as DB --json` |
+| Detach database from project | `creek db detach <NAME> --from <PROJECT> --json` |
+| Rename a database | `creek db rename <NAME> --to <NEW-NAME> --json` |
+| Delete a database | `creek db delete <NAME> --json` |
+| Tail runtime logs | `creek logs --json` |
+| Tail runtime logs (live) | `creek logs --follow --json` |
+| Filter runtime logs | `creek logs --outcome exception --since 1h --json` |
+| Read a deployment's build log | `creek deployments logs <DEPLOYMENT_ID> --json` |
+| Read raw build log ndjson | `creek deployments logs <DEPLOYMENT_ID> --raw` |
+| Pre-deploy diagnostic | `creek doctor --json` |
+
+## JSON Output Format
+
+Every command returns structured JSON with breadcrumbs:
+
+```json
+{
+  "ok": true,
+  "url": "https://my-app-team.bycreek.com",
+  "project": "my-app",
+  "breadcrumbs": [
+    { "command": "creek status", "description": "Check deployment status" },
+    { "command": "creek deployments --project my-app", "description": "View deployment history" }
+  ]
+}
+```
+
+On error:
+```json
+{
+  "ok": false,
+  "error": "not_authenticated",
+  "message": "Not authenticated. Run `creek login` first.",
+  "breadcrumbs": [
+    { "command": "creek login", "description": "Authenticate interactively" }
+  ]
+}
+```

package/skills/creek/references/creek-toml.md

@@ -0,0 +1,82 @@
+# `creek.toml` Reference
+
+```toml
+[project]
+name = "my-app"              # Required. Lowercase alphanumeric + hyphens.
+framework = "nextjs"         # Optional. Auto-detected from package.json.
+
+[build]
+command = "npm run build"    # Build command (default: npm run build)
+output = "dist"              # Build output directory
+worker = "worker/index.ts"   # Optional: custom Worker entry point
+
+[resources]
+database = true              # D1 database   → env.DB    + `import { db } from 'creek'`
+storage  = true              # R2 bucket     → env.BUCKET + `import { storage } from 'creek'`
+cache    = true              # KV namespace  → env.KV    + `import { cache } from 'creek'`
+ai       = true              # Workers AI    → env.AI    + `import { ai } from 'creek'`
+
+[triggers]
+cron  = ["0 */6 * * *"]      # One or more cron expressions. Standard 5-field format.
+queue = true                 # Creates a per-project queue + consumer binding.
+                             # Producer: `import { queue } from 'creek'` inside the Worker.
+                             # Consumer: export a `queue(batch, env, ctx)` handler.
+```
+
+**Semantic names** (`database` / `storage` / `cache`) are the stable
+Creek names and what you should write in new projects. The legacy
+Cloudflare names (`d1` / `r2` / `kv`) are still accepted for
+backward compatibility but deprecated.
+
+**`[resources]` booleans vs `creek db`** — the `[resources]` shorthand
+auto-provisions one resource per project, legacy-compatible with v1.
+For any project needing a renameable database, a database shared
+across projects, or explicit ENV var control, use `creek db create` +
+`creek db attach` (see `references/resources.md`). The two paths can
+coexist during migration.
+
+## Cron triggers
+
+Creek reads the `cron` array and registers each expression with
+Cloudflare's scheduled event system. The Worker must export a
+`scheduled(event, env, ctx)` handler. Creek generates this handler
+automatically when using a framework; for hand-written Workers, see
+the SSR/Worker examples in the docs.
+
+Verify cron is active:
+```bash
+creek status --json          # Shows registered cron schedules
+```
+
+Simulate a firing locally during dev:
+```bash
+creek dev --trigger-cron "0 */6 * * *"
+```
+
+## Queue triggers
+
+Setting `queue = true` auto-provisions a Cloudflare Queue and binds
+it to the project. Inside the Worker:
+
+```ts
+// Producer — in any request handler
+import { queue } from 'creek';
+await queue.send({ userId: 'abc', action: 'welcome-email' });
+```
+
+```ts
+// Consumer — export from the Worker entry
+export default {
+  async queue(batch, env, ctx) {
+    for (const msg of batch.messages) {
+      console.log(msg.body);
+      msg.ack();
+    }
+  },
+};
+```
+
+Send a message from the CLI (useful for testing):
+```bash
+creek queue send '{"userId":"abc"}' --json
+```

package/skills/creek/references/deployment-modes.md

@@ -0,0 +1,66 @@
+# Creek CLI — Deployment Modes
+
+Four ways to invoke `creek deploy`. Pick based on where the build runs
+and whether the result persists.
+
+## Authenticated (permanent)
+
+Requires `creek login`. Deploys persist under the user's account.
+Builds locally, uploads the bundle, deploys to Workers for Platforms.
+
+```bash
+creek deploy --json
+```
+
+## Sandbox (60-min preview)
+
+No auth required. Temporary preview with claimable URL.
+
+```bash
+creek deploy --json          # auto-sandbox when not logged in
+creek claim <SANDBOX_ID>     # convert to permanent project
+```
+
+Sandbox env vars are restricted — user-set secrets are not injected.
+Code that depends on an LLM API key or similar should gate on the
+env var being present and fall back gracefully, then deploy to
+production for full env access.
+
+## CI/CD
+
+```bash
+CREEK_TOKEN=ck_... creek deploy --yes --json
+```
+
+`--yes` is auto-enabled in non-TTY environments (no confirmation
+prompts). `--json` output is also auto-enabled in non-TTY.
+
+## Remote build via GitHub connection
+
+When the project has a GitHub connection (set up via the dashboard's
+`/new` import flow or `/projects/:id/settings`), Creek can deploy the
+latest commit on the project's production branch **without** running
+the build locally. The control-plane fetches the commit, invokes the
+same remote-builder container used by `git push` webhooks, and runs
+the full deploy pipeline server-side.
+
+Use this when:
+- You want to redeploy from a machine that doesn't have the source
+  checked out (fresh CI runner, different laptop, an agent with a
+  narrow workspace).
+- You want to trigger a deploy without pushing a commit.
+- You want CI capability parity with the dashboard "Deploy latest"
+  button.
+
+```bash
+# Infer the project from creek.toml in cwd
+creek deploy --from-github --json
+
+# Or target an explicit project by slug (or UUID)
+creek deploy --from-github --project my-app --json
+```
+
+The command polls the deployments list until the new row settles on
+`active`, `failed`, or `cancelled`, and prints each status transition.
+Fails fast if the project has no github_connection or the connection's
+production branch has no accessible commit.

package/skills/creek/references/diagnosis.md

@@ -0,0 +1,81 @@
+# Creek CLI — Failure Diagnosis
+
+When a user says "my deploy failed" or "creek deploy didn't work",
+follow this sequence. Don't guess — each step returns structured data
+you can act on.
+
+## 1. Pre-deploy check (if they haven't run it yet)
+
+```bash
+creek doctor --json
+```
+
+Returns findings with `CK-*` codes, severities, and concrete fixes.
+Run before any deploy-not-even-attempted scenario. Common fires:
+`CK-NO-CONFIG`, `CK-NOTHING-TO-DEPLOY`, `CK-DB-DUAL-DRIVER-SPLIT`,
+`CK-SYNC-SQLITE`, `CK-PRISMA-SQLITE`.
+
+## 2. Find the failed deployment
+
+```bash
+creek deployments --json                    # list, newest first
+```
+
+Scan for `status: "failed"` rows; note the `id`.
+
+## 3. Read the build log
+
+```bash
+creek deployments logs <id-prefix> --json
+```
+
+Look at `metadata.errorCode` and `metadata.errorStep`. The `entries`
+array is phase-grouped — lines with `level: "error"` or from the
+failing step are the signal.
+
+## 4. Apply the fix
+
+Match `errorCode` against the CK-* mapping:
+
+| Code | Fix |
+|------|-----|
+| `CK-NO-CONFIG` | Run `creek init` or cd to a project root |
+| `CK-NOTHING-TO-DEPLOY` | Run the build, or set `[build].command` in creek.toml |
+| `CK-DB-DUAL-DRIVER-SPLIT` | Consolidate to shared `schema.ts` + `routes.ts` + thin boot split (see `references/resources.md`) |
+| `CK-SYNC-SQLITE` | Move to async ORM (Drizzle/Kysely) with D1 adapter |
+| `CK-PRISMA-SQLITE` | Prisma+SQLite not supported on Workers; switch to Drizzle/Kysely |
+| `CK-RUNTIME-LOCKIN` | Drop the `@solcreek/*` runtime imports for a portable build |
+| `CK-CONFIG-OVERLAP` | Keep either creek.toml or wrangler.*, not both |
+
+For an unmapped error code or a generic `build_failed`, the
+`errorStep` tells you the phase (install / build / bundle) and the
+log entries carry the actual stderr.
+
+## 5. Redeploy
+
+```bash
+creek deploy --json
+```
+
+If the fix was config-side, `creek doctor --json` should now be clean.
+
+## Troubleshooting (error-string table)
+
+Quick lookup when the user reports a specific error string verbatim.
+
+| Error | Fix |
+|-------|-----|
+| "Not authenticated" | `creek login` or set `CREEK_TOKEN` |
+| "Invalid API key" | `creek login` to re-authenticate |
+| "No creek.toml found" | `creek init` or cd to project root |
+| "No project found" | Deploy from a dir with package.json or index.html |
+| "No supported project found in repo" | Use `--path` for monorepos |
+| "Project has no GitHub connection" (on `--from-github`) | Connect the repo first via the dashboard Settings → GitHub Connection |
+| "Could not determine target project" (on `--from-github`) | Pass `--project <slug>` or run the command from a directory with a `creek.toml` |
+| Sandbox expired | Redeploy — sandboxes last 60 minutes |
+| Domain stuck "pending" | Set CNAME to `cname.creek.dev`, then `creek domains activate` |
+| Build fails | Check `[build] command` in creek.toml |
+| Webhook not firing on push | Verify the repo is connected under project Settings; GitHub App must be installed on the repo's account |
+| `CK-DB-DUAL-DRIVER-SPLIT` from `creek doctor` | Consolidate db.local.ts + db.prod.ts to the shared-routes pattern. See `references/resources.md`. |
+| "Resource has bindings" on `creek db delete` | Detach from every project (`creek db detach <name> --from <project>`) before deletion |
+| "A resource named 'X' already exists" | Team-unique names; pick a different one or `creek db rename` the existing one |

package/skills/creek/references/github-setup.md

@@ -0,0 +1,19 @@
+# GitHub Auto-Deploy Setup
+
+For push-to-deploy + PR previews, the user installs the **Creek
+Deploy** GitHub App and connects a repository to a Creek project:
+
+1. Visit `https://github.com/apps/creek-deploy` and install on the
+   account or organization that owns the repo.
+2. GitHub redirects to `https://app.creek.dev/github/setup?installation_id=...`
+   which claims the installation for the current team and lists the
+   installation's repositories.
+3. Either import a new project from the dashboard's New Project →
+   Import Git Repository flow, or connect an existing project from
+   its Settings → GitHub Connection section.
+4. Pushes to the project's production branch trigger a full build +
+   deploy; pull requests trigger a preview deployment and post a
+   commit status with the preview URL.
+5. `creek deploy --from-github [--project <slug>]` can trigger the
+   same flow for the latest commit on demand (no push required). See
+   `references/deployment-modes.md` for when to reach for this.

package/skills/creek/references/observability.md

@@ -0,0 +1,56 @@
+# Creek CLI — Observability
+
+Two distinct log streams, answering different questions:
+
+| Question | Tool |
+|----------|------|
+| "What happened during my last deploy?" | `creek deployments logs <ID>` |
+| "What's my worker doing in production?" | `creek logs` |
+| "Why did my deploy fail, and can an agent fix it?" | MCP `get_build_log` |
+
+## Runtime logs — `creek logs`
+
+Per-project tail of `console.log` / `console.error` / uncaught
+exceptions for every request your Worker served. Tenant-isolated —
+the prefix is derived from the session, not URL params.
+
+```bash
+creek logs --json                      # last hour, all outcomes
+creek logs --follow                    # live tail via WebSocket
+creek logs --outcome exception         # errors only
+creek logs --since 24h --search "order"  # free text within a window
+creek logs --deployment <id>           # specific deploy
+```
+
+Note: **edge-cached HTML requests don't appear** — they never invoke
+the worker, so no log event fires. See the Analytics tab in the
+dashboard for total HTTP traffic (including cache hits).
+
+## Build logs — `creek deployments logs <id>`
+
+Structured transcript of the deploy pipeline: clone / detect / install
+/ build / bundle / upload / provision / activate. Surfaces the
+failing step with a `CK-*` diagnostic code and the subprocess stderr.
+
+```bash
+creek deployments logs <deployment-id> --json    # agent-safe
+creek deployments logs <deployment-id> --raw     # ndjson for piping
+creek deployments logs <short-id>                # 8-char prefix works
+```
+
+Available for `creek deploy` (CLI), GitHub push deploys, and via the
+dashboard's Deployments tab (expandable panel, auto-open on failure).
+Web deploys from `creek.dev/new` render the same transcript inline
+on failure.
+
+## MCP tool — `get_build_log`
+
+`mcp.creek.dev` exposes `get_build_log` for agents that want to
+diagnose a deploy without going through the CLI. Input: Creek API key
++ project slug + deployment id (short or full). Output: summary +
+important lines (errors + failing-step lines) + full log.
+
+Pattern: user says "my deploy to Creek failed, can you fix it?" → agent
+calls `get_build_log` → reads the `errorCode` + `errorStep` → applies
+the corresponding fix. See `references/diagnosis.md` for the CK-*
+code-to-fix mapping.

package/skills/creek/references/resources.md

@@ -0,0 +1,47 @@
+# Resources v2 — Team-Owned Databases
+
+Databases (and other resources) are **team-owned**, not project-owned.
+A resource has a stable UUID and a mutable name; it can be attached
+to one or more projects under different ENV var names. This replaces
+the "one D1 per project, name derived from project id" model.
+
+## Workflow
+
+```bash
+# 1. Create a team-level database (unattached, not yet provisioned in CF)
+creek db create users --json
+
+# 2. Attach it to one project as env.DB
+creek db attach users --to my-api --as DB --json
+
+# 3. Optionally share the same database with another project
+creek db attach users --to dashboard --as DB --json
+
+# 4. Inspect what's attached
+creek db ls --json
+```
+
+The database name is mutable — `creek db rename users --to prod-users`
+works without recreating the CF resource or breaking bindings.
+
+Deletion is blocked while any binding exists — detach from every
+project first, then `creek db delete`.
+
+## Portable pattern (required mental model)
+
+Share **schema + queries**; split **only the boot**. The
+`examples/vite-react-drizzle` reference:
+
+```
+server/
+├── schema.ts    shared Drizzle schema (one source of truth)
+├── routes.ts    shared Hono routes that accept a `() => db` thunk
+├── local.ts     Node + better-sqlite3 boot (dev)
+└── worker.ts    CF Worker + D1 boot (prod)
+```
+
+The async Drizzle API is the same across both drivers, so
+`routes.ts` runs unchanged in either environment. Migrations run
+against whichever driver the boot file sets up. Don't duplicate
+schema or queries across `db.local.ts` + `db.prod.ts` — `creek doctor`
+flags that with `CK-DB-DUAL-DRIVER-SPLIT`.

package/skills/creek/references/workflows.md

@@ -0,0 +1,44 @@
+# Creek CLI — Common Workflows
+
+## First deploy
+
+```bash
+creek login --json                # 1. Authenticate
+creek init --json                 # 2. Create creek.toml (optional)
+creek deploy --json               # 3. Deploy
+```
+
+## Update & rollback
+
+```bash
+creek deploy --json               # Deploy new version
+creek deployments --json          # View history
+creek rollback --json             # Rollback to previous
+creek rollback <ID> --json        # Rollback to specific deployment
+```
+
+## Custom domain
+
+```bash
+creek domains add app.example.com --json     # Add domain
+# User sets DNS: CNAME app.example.com → cname.creek.dev
+creek domains activate app.example.com --json # Activate after DNS
+creek domains ls --json                       # Verify status
+```
+
+## Supported Frameworks
+
+**SPA**: vite-react, vite-vue, vite-svelte, vite-solid, static HTML, astro
+**SSR**: nextjs, react-router, sveltekit, nuxt, solidstart, tanstack-start
+
+Not every SSR framework has equal support yet — check
+[creek.dev/docs/getting-started](https://creek.dev/docs/getting-started)
+for the current compatibility matrix. Next.js in particular requires
+`@solcreek/adapter-creek` or Creek's OpenNextJS workaround.
+
+## Config Detection Order
+
+1. `creek.toml` — explicit Creek config
+2. `wrangler.jsonc` / `wrangler.json` / `wrangler.toml` — existing CF config
+3. `package.json` — framework auto-detection
+4. `index.html` — static site