Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ agent-browser skills get slack # Slack workspace automation
agent-browser skills get dogfood # Exploratory testing / QA / bug hunts
agent-browser skills get derive-client # Record a HAR, derive a standalone API client for a site
agent-browser skills get vercel-sandbox # agent-browser inside Vercel Sandbox microVMs
agent-browser skills get protected-vercel-deployments # Access protected Vercel deployments
agent-browser skills get agentcore # AWS Bedrock AgentCore cloud browsers
```

Expand Down
1 change: 1 addition & 0 deletions plugins/agent-browser/agent/skills/agent-browser/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ agent-browser skills get slack # Slack workspace automation
agent-browser skills get dogfood # Exploratory testing / QA / bug hunts
agent-browser skills get derive-client # Record a HAR, derive a standalone API client for a site
agent-browser skills get vercel-sandbox # agent-browser inside Vercel Sandbox microVMs
agent-browser skills get protected-vercel-deployments # Access protected Vercel deployments
agent-browser skills get agentcore # AWS Bedrock AgentCore cloud browsers
```

Expand Down
2 changes: 1 addition & 1 deletion plugins/agent-browser/skills-lock.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"source": "vercel-labs/agent-browser",
"sourceType": "github",
"skillPath": "skills/agent-browser/SKILL.md",
"computedHash": "a674b7d81066e3cc471a7512ddb4ae724418cbfefa75cbb050b0dc430e4d57a0"
"computedHash": "80161e6836b3b40f4e83730a290deb40ac14d877d38c97ad5f6d71be37ce74c3"
},
"dogfood": {
"source": "vercel-labs/agent-browser",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,17 @@ description: Configure Better Auth server and client, set up database adapters,

# Better Auth Integration Guide

**Always consult [better-auth.com/docs](https://better-auth.com/docs) for code examples and latest API.**
## Documentation Version

Use documentation that matches the Better Auth version installed in the project. APIs and plugin names can differ across maintained release lines.

1. Prefer a version explicitly named by the user.
2. Otherwise, inspect the resolved `better-auth` version in the lockfile, falling back to the package manifest when no lockfile is available.
3. When the Better Auth MCP is available, call `get_doc` with `/llms.txt` to resolve that package version to a documentation identifier. Pass the identifier to every `search_docs` call and pass result paths to `get_doc` unchanged.
4. Without MCP, start at [better-auth.com/llms.txt](https://better-auth.com/llms.txt) and follow the matching version index.
5. Use the latest documentation only when the project version cannot be determined or the user explicitly asks about the latest release or an upgrade.

When planning an upgrade, separate guidance for the currently installed version from guidance for the target version.

---

Expand All @@ -16,9 +26,9 @@ description: Configure Better Auth server and client, set up database adapters,
3. Create `auth.ts` with database + config
4. Create route handler for your framework
5. Run migrations:
- **Built-in adapter:** `npx @better-auth/cli@latest migrate`
- **Drizzle:** `npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` (dev) or `npx drizzle-kit generate && npx drizzle-kit migrate` (prod)
- **Prisma:** `npx @better-auth/cli@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
- **Built-in adapter:** `npx auth@latest migrate`
- **Drizzle:** `npx auth@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` (dev) or `npx drizzle-kit generate && npx drizzle-kit migrate` (prod)
- **Prisma:** `npx auth@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
6. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`

---
Expand All @@ -35,9 +45,9 @@ Only define `baseURL`/`secret` in config if env vars are NOT set.
CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--config` for custom path.

### CLI Commands
- `npx @better-auth/cli@latest migrate` - Apply schema (built-in adapter)
- `npx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle
- `npx @better-auth/cli mcp --cursor` - Add MCP to AI tools
- `npx auth@latest migrate` - Apply schema (built-in adapter)
- `npx auth@latest generate` - Generate schema for Prisma/Drizzle
- `npx auth@latest mcp --cursor` - Add MCP to AI tools

**Re-run after adding/changing plugins.**

Expand Down Expand Up @@ -179,4 +189,4 @@ For separate client/server projects: `createAuthClient<typeof auth>()`.
- [Options Reference](https://better-auth.com/docs/reference/options)
- [LLMs.txt](https://better-auth.com/llms.txt)
- [GitHub](https://github.com/better-auth/better-auth)
- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)
- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ description: Configure email verification, implement password reset flows, set p
1. Enable email/password: `emailAndPassword: { enabled: true }`
2. Configure `emailVerification.sendVerificationEmail`
3. Add `sendResetPassword` for password reset flows
4. Run `npx @better-auth/cli@latest migrate`
4. Run `npx auth@latest migrate`
5. Verify: attempt sign-up and confirm verification email triggers

---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Configure multi-tenant organizations, manage members and invitation

1. Add `organization()` plugin to server config
2. Add `organizationClient()` plugin to client config
3. Run `npx @better-auth/cli@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
3. Run `npx auth@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
4. Verify: check that organization, member, invitation tables exist in your database

```ts
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Configure TOTP authenticator apps, send OTP codes via email/SMS, ma

1. Add `twoFactor()` plugin to server config with `issuer`
2. Add `twoFactorClient()` plugin to client config
3. Run `npx @better-auth/cli@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
3. Run `npx auth@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
4. Verify: check that `twoFactorSecret` column exists on user table

```ts
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,17 @@ description: "Configure Better Auth server and client, set up database adapters,
---
# Better Auth Integration Guide

**Always consult [better-auth.com/docs](https://better-auth.com/docs) for code examples and latest API.**
## Documentation Version

Use documentation that matches the Better Auth version installed in the project. APIs and plugin names can differ across maintained release lines.

1. Prefer a version explicitly named by the user.
2. Otherwise, inspect the resolved `better-auth` version in the lockfile, falling back to the package manifest when no lockfile is available.
3. When the Better Auth MCP is available, call `get_doc` with `/llms.txt` to resolve that package version to a documentation identifier. Pass the identifier to every `search_docs` call and pass result paths to `get_doc` unchanged.
4. Without MCP, start at [better-auth.com/llms.txt](https://better-auth.com/llms.txt) and follow the matching version index.
5. Use the latest documentation only when the project version cannot be determined or the user explicitly asks about the latest release or an upgrade.

When planning an upgrade, separate guidance for the currently installed version from guidance for the target version.

---

Expand All @@ -14,9 +24,9 @@ description: "Configure Better Auth server and client, set up database adapters,
3. Create `auth.ts` with database + config
4. Create route handler for your framework
5. Run migrations:
- **Built-in adapter:** `npx @better-auth/cli@latest migrate`
- **Drizzle:** `npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` (dev) or `npx drizzle-kit generate && npx drizzle-kit migrate` (prod)
- **Prisma:** `npx @better-auth/cli@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
- **Built-in adapter:** `npx auth@latest migrate`
- **Drizzle:** `npx auth@latest generate --output src/db/auth-schema.ts` then `npx drizzle-kit push` (dev) or `npx drizzle-kit generate && npx drizzle-kit migrate` (prod)
- **Prisma:** `npx auth@latest generate --output prisma/schema.prisma` then `npx prisma migrate dev`
6. Verify: call `GET /api/auth/ok` — should return `{ status: "ok" }`

---
Expand All @@ -33,9 +43,9 @@ Only define `baseURL`/`secret` in config if env vars are NOT set.
CLI looks for `auth.ts` in: `./`, `./lib`, `./utils`, or under `./src`. Use `--config` for custom path.

### CLI Commands
- `npx @better-auth/cli@latest migrate` - Apply schema (built-in adapter)
- `npx @better-auth/cli@latest generate` - Generate schema for Prisma/Drizzle
- `npx @better-auth/cli mcp --cursor` - Add MCP to AI tools
- `npx auth@latest migrate` - Apply schema (built-in adapter)
- `npx auth@latest generate` - Generate schema for Prisma/Drizzle
- `npx auth@latest mcp --cursor` - Add MCP to AI tools

**Re-run after adding/changing plugins.**

Expand Down Expand Up @@ -177,4 +187,4 @@ For separate client/server projects: `createAuthClient<typeof auth>()`.
- [Options Reference](https://better-auth.com/docs/reference/options)
- [LLMs.txt](https://better-auth.com/llms.txt)
- [GitHub](https://github.com/better-auth/better-auth)
- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)
- [Init Options Source](https://github.com/better-auth/better-auth/blob/main/packages/core/src/types/init-options.ts)
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: "Configure email verification, implement password reset flows, set
1. Enable email/password: `emailAndPassword: { enabled: true }`
2. Configure `emailVerification.sendVerificationEmail`
3. Add `sendResetPassword` for password reset flows
4. Run `npx @better-auth/cli@latest migrate`
4. Run `npx auth@latest migrate`
5. Verify: attempt sign-up and confirm verification email triggers

---
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: "Configure multi-tenant organizations, manage members and invitatio

1. Add `organization()` plugin to server config
2. Add `organizationClient()` plugin to client config
3. Run `npx @better-auth/cli@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
3. Run `npx auth@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
4. Verify: check that organization, member, invitation tables exist in your database

```ts
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: "Configure TOTP authenticator apps, send OTP codes via email/SMS, m

1. Add `twoFactor()` plugin to server config with `issuer`
2. Add `twoFactorClient()` plugin to client config
3. Run `npx @better-auth/cli@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
3. Run `npx auth@latest migrate` (built-in adapter) or generate + push for Drizzle/Prisma
4. Verify: check that `twoFactorSecret` column exists on user table

```ts
Expand Down
8 changes: 4 additions & 4 deletions plugins/better-auth/skills-lock.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"source": "better-auth/skills",
"sourceType": "github",
"skillPath": "better-auth/best-practices/SKILL.md",
"computedHash": "61ba0ef64ed2e7c424401cc848ca33dd6d790a720c44727717dc0c5cba5fc122"
"computedHash": "0c30be0e118c2b7a0c4c57bd9e63bf110c7e420a79ec6ce7997153f3b1e066ee"
},
"create-auth-skill": {
"source": "better-auth/skills",
Expand All @@ -17,19 +17,19 @@
"source": "better-auth/skills",
"sourceType": "github",
"skillPath": "better-auth/emailAndPassword/SKILL.md",
"computedHash": "747d7f73bd9e2ec5317b8ef88dc70f97df716d00e3d02de4051feebaa48b062d"
"computedHash": "863886759f729081e265941f4f72c503835d55a1f34f6d63cebe6571159fff4a"
},
"organization-best-practices": {
"source": "better-auth/skills",
"sourceType": "github",
"skillPath": "better-auth/organization/SKILL.md",
"computedHash": "27627eb3a13bd44eff3a5d890f96e7db052b623db90e01684f759abe3e7fe56b"
"computedHash": "8c85e683dabef4532f1e8b67bbed5c453d39e0e3d5aeedd69d16b568f6e6d44f"
},
"two-factor-authentication-best-practices": {
"source": "better-auth/skills",
"sourceType": "github",
"skillPath": "better-auth/twoFactor/SKILL.md",
"computedHash": "a6f720042e5a090909e0d519a6a50a7eb8179553cd5315f0bbad852a6d20dac8"
"computedHash": "5bc3051aef5060db013f0b3cbe812c40dbae5c22d6ba3ddde4b941158362a197"
}
}
}
32 changes: 23 additions & 9 deletions plugins/dev3000/.agents/skills/d3k/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,45 +19,59 @@ When this skill triggers, operate d3k. Do not merely tell the user how to run it

Run from the project root.

1. Check for an existing project runtime:
1. Check canonical Portless readiness before starting any app process:

```bash
d3k portless status --json
```

If `"setupRequired": true`, run:

```bash
d3k portless setup
```

On macOS this opens the system administrator authorization dialog. Wait for the user to approve it, then rerun `d3k portless status --json`. Do not start d3k until `"canonical": true`, `"serviceInstalled": true`, and `"setupRequired": false`. If authorization is declined or unavailable, stop and explain the blocker. Never silently substitute direct localhost.

2. Check for an existing project runtime:

```bash
d3k status --json
```

If it reports `"running": true`, reuse it. Do not start a second dev server or browser.
Reuse it only if it reports `"running": true`, `"ready": true`, `"routing": "portless"`, `"browserConnected": true`, and a genuinely port-free `https://...localhost` `appUrl`. If an active session reports `"routing": "direct"`, stop that retained d3k session and restart after Portless is ready. Do not start a second dev server or browser.

2. If d3k is not installed, install it:
3. If d3k is not installed, install it:

```bash
bun install -g dev3000
```

Use `npm install -g dev3000` only when Bun is unavailable.

3. Start d3k with the agent's shell/process tool as a retained background or yielded session:
4. Start d3k with the agent's shell/process tool as a retained background or yielded session (non-TUI by default):

```bash
d3k --no-agent --no-tui -t
d3k -t
```

Do not wait for this long-running command to exit. Keep its process/session handle so you can monitor or stop it later. Prefer the execution tool's background/session support over shelling with `&`.

If the target URL is already known, pass it so the managed browser opens there:

```bash
d3k --no-agent --no-tui -t --app-url "<url>"
d3k -t --app-url "<url>"
```

Let d3k auto-detect the package manager, dev command, and port. Add `--command`, `--script`, or `--port` only when detection is wrong or the user specified them.

4. Poll until the runtime is ready:
5. Poll until the runtime is ready:

```bash
d3k status --json
```

A successful status response is the readiness boundary. Prefer the reported Portless `appUrl`; the underlying app port may change between runs. If startup fails, inspect the retained process output and `d3k logs --type server`; do not launch a separate dev server.
A successful status response is the readiness boundary only when it reports `"ready": true`, `"routing": "portless"`, `"browserConnected": true`, and a port-free `https://...localhost` `appUrl`. The underlying app port may change between runs. If startup fails, inspect the retained process output and `d3k logs --type server`; do not launch a separate dev server.

## User-Driven Testing

Expand Down Expand Up @@ -125,4 +139,4 @@ Use `--headless` only for CI or when explicitly requested. Use `--servers-only`
- Keep d3k alive across edits and retests.
- Preserve the project-stable Chrome profile unless the user explicitly asks for a fresh profile.
- Leave the runtime running when handing a headed browser to the user; stop it only when asked or when the task requires a clean restart.
- Portless routing is the default. Use `--no-portless` or `PORTLESS=0` only when direct localhost routing is explicitly required.
- Canonical Portless HTTPS routing is required by default. Never add `--no-portless` or set `PORTLESS=0` unless the user explicitly requests direct localhost routing.
32 changes: 23 additions & 9 deletions plugins/dev3000/agent/skills/d3k/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,45 +17,59 @@ When this skill triggers, operate d3k. Do not merely tell the user how to run it

Run from the project root.

1. Check for an existing project runtime:
1. Check canonical Portless readiness before starting any app process:

```bash
d3k portless status --json
```

If `"setupRequired": true`, run:

```bash
d3k portless setup
```

On macOS this opens the system administrator authorization dialog. Wait for the user to approve it, then rerun `d3k portless status --json`. Do not start d3k until `"canonical": true`, `"serviceInstalled": true`, and `"setupRequired": false`. If authorization is declined or unavailable, stop and explain the blocker. Never silently substitute direct localhost.

2. Check for an existing project runtime:

```bash
d3k status --json
```

If it reports `"running": true`, reuse it. Do not start a second dev server or browser.
Reuse it only if it reports `"running": true`, `"ready": true`, `"routing": "portless"`, `"browserConnected": true`, and a genuinely port-free `https://...localhost` `appUrl`. If an active session reports `"routing": "direct"`, stop that retained d3k session and restart after Portless is ready. Do not start a second dev server or browser.

2. If d3k is not installed, install it:
3. If d3k is not installed, install it:

```bash
bun install -g dev3000
```

Use `npm install -g dev3000` only when Bun is unavailable.

3. Start d3k with the agent's shell/process tool as a retained background or yielded session:
4. Start d3k with the agent's shell/process tool as a retained background or yielded session (non-TUI by default):

```bash
d3k --no-agent --no-tui -t
d3k -t
```

Do not wait for this long-running command to exit. Keep its process/session handle so you can monitor or stop it later. Prefer the execution tool's background/session support over shelling with `&`.

If the target URL is already known, pass it so the managed browser opens there:

```bash
d3k --no-agent --no-tui -t --app-url "<url>"
d3k -t --app-url "<url>"
```

Let d3k auto-detect the package manager, dev command, and port. Add `--command`, `--script`, or `--port` only when detection is wrong or the user specified them.

4. Poll until the runtime is ready:
5. Poll until the runtime is ready:

```bash
d3k status --json
```

A successful status response is the readiness boundary. Prefer the reported Portless `appUrl`; the underlying app port may change between runs. If startup fails, inspect the retained process output and `d3k logs --type server`; do not launch a separate dev server.
A successful status response is the readiness boundary only when it reports `"ready": true`, `"routing": "portless"`, `"browserConnected": true`, and a port-free `https://...localhost` `appUrl`. The underlying app port may change between runs. If startup fails, inspect the retained process output and `d3k logs --type server`; do not launch a separate dev server.

## User-Driven Testing

Expand Down Expand Up @@ -123,4 +137,4 @@ Use `--headless` only for CI or when explicitly requested. Use `--servers-only`
- Keep d3k alive across edits and retests.
- Preserve the project-stable Chrome profile unless the user explicitly asks for a fresh profile.
- Leave the runtime running when handing a headed browser to the user; stop it only when asked or when the task requires a clean restart.
- Portless routing is the default. Use `--no-portless` or `PORTLESS=0` only when direct localhost routing is explicitly required.
- Canonical Portless HTTPS routing is required by default. Never add `--no-portless` or set `PORTLESS=0` unless the user explicitly requests direct localhost routing.
2 changes: 1 addition & 1 deletion plugins/dev3000/skills-lock.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"source": "vercel-labs/dev3000",
"sourceType": "github",
"skillPath": "skills/d3k/SKILL.md",
"computedHash": "6462ff3b28aaec3ba02f8419e4a6faace3ccb69165bf0da8f55a7da93393e2d3"
"computedHash": "b8604d8dcb3136f9d04a3a0ec02962380d0260c7b7ffc321ca90e8d5569e2b8d"
}
}
}
Loading
Loading