diff --git a/.github/workflows/skill-sync.yml b/.github/workflows/skill-sync.yml new file mode 100644 index 0000000..8b23f63 --- /dev/null +++ b/.github/workflows/skill-sync.yml @@ -0,0 +1,24 @@ +name: Skill copies in sync + +# skills/ardent-cli-skill.txt is canonical: installed skills self-update +# from https://docs.tryardent.com/skills/ardent-cli-skill.txt, so that +# file must keep serving raw. skills/ardent-cli/SKILL.md is the same +# content in the layout `npx skills` discovers. This check keeps the +# two identical. + +on: + push: + branches: [main] + pull_request: + +jobs: + diff: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: SKILL.md matches ardent-cli-skill.txt + run: | + if ! diff -u skills/ardent-cli-skill.txt skills/ardent-cli/SKILL.md; then + echo "::error::skills/ardent-cli/SKILL.md is out of sync with skills/ardent-cli-skill.txt (canonical). Run: cp skills/ardent-cli-skill.txt skills/ardent-cli/SKILL.md" + exit 1 + fi diff --git a/branches.mdx b/branches.mdx new file mode 100644 index 0000000..d933991 --- /dev/null +++ b/branches.mdx @@ -0,0 +1,49 @@ +--- +title: "Branch behavior" +description: "What a branch contains, how it behaves after creation, and its lifecycle" +--- + +A branch is a full, isolated Postgres database cloned from your connected source. This page covers what's in it, what happens to it over time, and what it costs to keep around. + +## Branches are frozen at creation + +**A branch does not receive replication after it's created.** Ardent keeps a read replica continuously in sync with your source database; a branch captures that replica's state at the moment you run `ardent branch create`, and from then on it's on its own: + +- Writes to your source database after that moment **do not appear** on the branch — no WAL, no DDL, nothing streams in. +- Writes to the branch **never flow back** to your source database or to other branches. + +This is by design: tests and migrations need a database that doesn't shift underneath them mid-run. + +**Want fresher data? Create a new branch.** Branches are created in seconds from the always-current replica, so the cheapest way to "refresh" is to delete the old branch and cut a new one. + +## What a branch contains + +Each branch is real Postgres — not a schema-only copy, not a subset: + +- Your schema and all your rows, as of creation time. +- Grants, row-level security, functions, triggers, and supported extensions. +- A few source features need an explicit choice during connector setup — [replica identity](/cli/connectors#replica-identity-decisions) for tables without a primary key, and a small set of provider-specific extensions. Ardent flags these before you can branch, so a branch never silently drops them. + +You can also configure per-connector defaults for new branches — the database name and any SQL to run on each new branch — in [connector settings](/cli/settings). + +## Lifecycle + +1. **Create.** `ardent branch create my-feature` clones from the replica in seconds, regardless of source size. The branch becomes your current branch and the CLI prints its connection URL. +2. **Use.** Connect with the printed URL from psql, your app, an ORM, or an agent. Compute auto-scales with load. +3. **Auto-suspend.** After 5 minutes of inactivity, the branch suspends on its own. +4. **Resume.** Connecting again wakes it instantly — no command needed. Your data and any changes you made are exactly as you left them. +5. **Delete.** `ardent branch delete my-feature` removes it. Cleanup isn't urgent on a laptop thanks to auto-suspend, but CI should always delete its branches. + +## Isolation and credentials + +Every branch gets its own connection string, routed through Ardent's proxy. It has no access to your source database — if a branch URL leaks (say, to an AI agent's logs), your production data and real credentials stay safe. Revoke access by deleting the branch. + +## Storage + +Branches share storage with the replica through copy-on-write. Creating a branch doesn't duplicate your data — you only pay storage for the rows you change on the branch. That's why "create one per task and move on" is the intended workflow, not something to ration. + +## Common questions + +- **Do branches stay in sync with production?** No — frozen at creation, see above. +- **Does branching load my production database?** No. Branches are always cloned from the replica, never from your source directly. +- **How many can I create?** As many as you need; see [Storage](#storage). diff --git a/connectors/planetscale.mdx b/connectors/planetscale.mdx index 85b5fc7..20e3ecb 100644 --- a/connectors/planetscale.mdx +++ b/connectors/planetscale.mdx @@ -5,15 +5,16 @@ description: "The PlanetScale-specific parts of connecting to Ardent" Ardent works with PlanetScale Postgres. This page covers only what's specific to PlanetScale — the full walkthrough is the [Quickstart](/quickstart). - -With the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) installed, a short ask is enough — the skill fetches this page and runs the checks: + +[Install the ardent-cli skill](/workflows/ai-agents#install-the-ardent-cli-skill) once, and a short ask is enough — the skill fetches this page and runs the checks: ``` Check if my PlanetScale Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` + -Without the skill, paste the full directions: +Without the skill, paste the full directions into your agent: ``` Check if my PlanetScale Postgres database is ready to connect to Ardent. @@ -32,18 +33,17 @@ Verify: After preflight passes, run: ardent connector create postgresql '' ``` - Two things matter here: - + In your PlanetScale dashboard, go to **Settings > Integrations** and enable **Logical Replication**. This is what lets Ardent replicate your data for branching. - + Go to **Connect > Connect with: Postgres** and copy the connection string. It looks like: diff --git a/connectors/rds.mdx b/connectors/rds.mdx index 6c1c2a8..a70e2c0 100644 --- a/connectors/rds.mdx +++ b/connectors/rds.mdx @@ -5,15 +5,16 @@ description: "The RDS-specific parts of connecting to Ardent" Ardent works with AWS RDS for PostgreSQL. This page covers only what's specific to RDS — the full walkthrough is the [Quickstart](/quickstart). - -With the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) installed, a short ask is enough — the skill fetches this page and runs the checks: + +[Install the ardent-cli skill](/workflows/ai-agents#install-the-ardent-cli-skill) once, and a short ask is enough — the skill fetches this page and runs the checks: ``` Check if my AWS RDS Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` + -Without the skill, paste the full directions: +Without the skill, paste the full directions into your agent: ``` Check if my AWS RDS Postgres database is ready to connect to Ardent. @@ -33,12 +34,11 @@ Verify: After preflight passes, run: ardent connector create postgresql '' ``` - RDS needs three things before preflight can pass: - + Create or modify a parameter group for your RDS Postgres major version and set: @@ -58,7 +58,7 @@ Apply the parameter group to your instance. - + In the RDS console, open **Databases > your instance > Connectivity & security** and confirm the endpoint and port. Allow Ardent's outbound IP to reach the instance on the Postgres port, usually `5432`. Ask your Ardent contact for the current outbound IP if you don't have it. @@ -68,7 +68,7 @@ In the RDS console, open **Databases > your instance > Connectivity & security** - + Connect as a role with `rds_superuser` privileges and grant RDS's replication role to the user Ardent will connect as: diff --git a/connectors/self-hosted.mdx b/connectors/self-hosted.mdx index f4fad7f..233c0a3 100644 --- a/connectors/self-hosted.mdx +++ b/connectors/self-hosted.mdx @@ -15,15 +15,16 @@ ardent connector preflight postgresql 'postgresql://user:[YOUR-PASSWORD]@host:54 Preflight is fast and non-destructive — it stores no credentials and creates nothing. It prints a pass/fail checklist and a **Grant script** with the exact SQL for your database and schemas. - -With the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) installed, a short ask is enough — the skill fetches this page and runs the checks: + +[Install the ardent-cli skill](/workflows/ai-agents#install-the-ardent-cli-skill) once, and a short ask is enough — the skill fetches this page and runs the checks: ``` Check whether my self-hosted Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` + -Without the skill, paste the full directions: +Without the skill, paste the full directions into your agent: ``` Check whether my self-hosted Postgres database is ready to connect to Ardent. @@ -44,11 +45,10 @@ Then verify these source requirements and tell me exactly what to fix: After preflight passes, run: ardent connector create postgresql '' ``` - - + Ardent connects from a static outbound IP for your environment. If your network restricts inbound traffic, allow that IP on the Postgres port, usually `5432`. Ask your Ardent contact for the current outbound IP if you don't have it. @@ -74,7 +74,7 @@ Hostnames must resolve to an IPv4 address. IPv6-only hosts are not supported tod - + Check the current values first: @@ -124,7 +124,7 @@ Prefer doing it by hand? Run the `SHOW` queries above and only change the settin - + Ardent reads changes through the `wal2json` logical-decoding plugin. Install the package matching your Postgres major version: @@ -152,7 +152,7 @@ No rows should come back. - + Today, vanilla self-hosted Postgres requires the Ardent role to create event triggers, which is restricted to `SUPERUSER`. That's a broad permission — a Postgres superuser can read and modify anything on the cluster. Use a dedicated role, restrict network access to Ardent's outbound IP, rotate the password deliberately, and prefer a dedicated source cluster or database if your security model requires stricter isolation. @@ -210,7 +210,7 @@ WHERE schemaname = ''; - + ```bash ardent connector preflight postgresql 'postgresql://ardent_replication:[YOUR-PASSWORD]@your-host:5432/mydb' --schemas public diff --git a/connectors/supabase.mdx b/connectors/supabase.mdx index 48e331c..9349382 100644 --- a/connectors/supabase.mdx +++ b/connectors/supabase.mdx @@ -5,15 +5,16 @@ description: "The Supabase-specific parts of connecting to Ardent" Ardent works with Supabase Postgres. This page covers only what's specific to Supabase — the full walkthrough is the [Quickstart](/quickstart). - -With the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) installed, a short ask is enough — the skill fetches this page and runs the checks: + +[Install the ardent-cli skill](/workflows/ai-agents#install-the-ardent-cli-skill) once, and a short ask is enough — the skill fetches this page and runs the checks: ``` Check if my Supabase database is ready to connect to Ardent. My connection string: [paste here] ``` + -Without the skill, paste the full directions: +Without the skill, paste the full directions into your agent: ``` Check if my Supabase database is ready to connect to Ardent. @@ -33,12 +34,11 @@ Verify: After preflight passes, run: ardent connector create postgresql '' ``` - Three things matter here: - + In your Supabase dashboard: @@ -53,7 +53,7 @@ In your Supabase dashboard: - + Scroll down in the Connect dialog to the **IPv4 compatible** indicator. @@ -62,7 +62,7 @@ Scroll down in the Connect dialog to the **IPv4 compatible** indicator. - + It looks like: diff --git a/docs.json b/docs.json index 3dafa18..0b546aa 100644 --- a/docs.json +++ b/docs.json @@ -66,6 +66,7 @@ "icon": "layers", "pages": [ "architecture", + "branches", "security" ] }, diff --git a/faq.mdx b/faq.mdx index edfa56b..3a75b87 100644 --- a/faq.mdx +++ b/faq.mdx @@ -28,7 +28,7 @@ description: "Common questions answered" - No. A branch is a point-in-time snapshot taken from a continuously synced replica. After creation it's isolated: your changes don't affect production, and production changes don't flow in. + No. A branch is a point-in-time snapshot taken from a continuously synced replica. After creation it's isolated: your changes don't affect production, and production changes don't flow in. See [Branch behavior](/branches) for the full picture. diff --git a/index.mdx b/index.mdx index b9df824..7402117 100644 --- a/index.mdx +++ b/index.mdx @@ -28,15 +28,58 @@ No more shared staging databases. No more hand-maintained fixtures. An instant d Branch your Postgres database in a few commands. - -With the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) installed, a short ask is enough — the skill fetches the current docs and works through setup: + + +Install the skill once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then a short ask is enough — the skill fetches the current docs and works through setup: + +``` +Set up Ardent for database branching on this project. +My connection string: [paste here] +``` + + + +Install into your project (or into `~/.claude/skills/` to use it everywhere) and Claude Code loads it automatically whenever a task involves Ardent: + +```bash +mkdir -p .claude/skills/ardent-cli +tmp_skill="$(mktemp)" +if curl -fsS https://docs.tryardent.com/skills/ardent-cli-skill.txt -o "$tmp_skill"; then + mv "$tmp_skill" .claude/skills/ardent-cli/SKILL.md +else + rm -f "$tmp_skill" + exit 1 +fi +``` + +To guarantee it's used, add this to your project's `CLAUDE.md`, which Claude Code reads every session: + +``` +Before touching the database in this repo — Postgres in any form, including +Supabase, RDS, PlanetScale, and self-hosted — for migrations, schema changes, +seeds, or queries against real data, use the ardent-cli skill and work on an +Ardent branch. Never use the main connection string unless the user +explicitly asks to change the real database. +``` + +Then a short ask is enough — the skill fetches the current docs and works through setup: ``` Set up Ardent for database branching on this project. My connection string: [paste here] ``` -Without the skill, paste the full directions: +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#install-the-ardent-cli-skill). + + + +Without the skill, paste the full directions into your agent: ``` Set up Ardent for database branching. Act like a teammate at my keyboard: @@ -72,7 +115,6 @@ Run these in order: If a command errors, fix it. Docs: https://docs.tryardent.com/quickstart ``` - ## How it works @@ -89,6 +131,8 @@ The workflow mirrors git: - **`ardent branch info`** — see the connection URL and status - **`ardent branch delete`** — clean up when you're done +A branch is frozen at creation: it does not receive replication from production afterwards, and nothing you do on a branch flows back to production or other branches. Want fresher data? Create a new branch — it comes from the always-current replica in seconds. Full details: [Branch behavior](/branches). + Branches suspend after 5 minutes of inactivity and wake instantly on reconnect. You pay storage only for the changes you make on a branch — so create as many as you need and throw them away freely. ## Next steps diff --git a/quickstart.mdx b/quickstart.mdx index a559ac7..f344f1c 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -10,7 +10,7 @@ description: "Branch your Postgres database in a few minutes" - + ```bash npm install -g ardent-cli @@ -18,7 +18,7 @@ npm install -g ardent-cli - + ```bash ardent login @@ -36,9 +36,62 @@ Create one with: ardent project create On a fresh account, create a project first: `ardent project create my-app`. If you already have exactly one project and connector, Ardent selects them for you. +Prefer to hand it off? Everything after login — preflight, connecting your database, creating branches — can be done by Claude Code or Cursor with the ardent-cli skill: + + + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then ask: + +``` +Set up Ardent for database branching on this project. +My connection string: [paste here] +``` + + + +Install into your project (or into `~/.claude/skills/` to use it everywhere) and Claude Code loads it automatically whenever a task involves Ardent: + +```bash +mkdir -p .claude/skills/ardent-cli +tmp_skill="$(mktemp)" +if curl -fsS https://docs.tryardent.com/skills/ardent-cli-skill.txt -o "$tmp_skill"; then + mv "$tmp_skill" .claude/skills/ardent-cli/SKILL.md +else + rm -f "$tmp_skill" + exit 1 +fi +``` + +To guarantee it's used, add this to your project's `CLAUDE.md`, which Claude Code reads every session: + +``` +Before touching the database in this repo — Postgres in any form, including +Supabase, RDS, PlanetScale, and self-hosted — for migrations, schema changes, +seeds, or queries against real data, use the ardent-cli skill and work on an +Ardent branch. Never use the main connection string unless the user +explicitly asks to change the real database. +``` + +Then ask: + +``` +Set up Ardent for database branching on this project. +My connection string: [paste here] +``` + +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#install-the-ardent-cli-skill). + + + - + + +This is the Postgres URL of the database you want to branch — your source database's **writable primary**, not a read replica or pooler endpoint. Save it in your shell so the next two commands can reuse it: @@ -52,22 +105,22 @@ Where to find it, and the one thing that usually blocks the next step: -In your Supabase dashboard, open **Connect** and copy the **direct connection** string — not the pooler one. The pooler can't do replication, and preflight will fail on it. Details: [Supabase setup](/connectors/supabase). +In your Supabase dashboard, open **Connect** and copy the [**direct connection** string — not the pooler one](/connectors/supabase#use-the-direct-connection-not-the-pooler). The pooler can't do replication, and preflight will fail on it. Details: [Supabase setup](/connectors/supabase). -Logical replication is usually off by default. Set `rds.logical_replication = 1` in your parameter group and reboot before running preflight. Details: [RDS setup](/connectors/rds). +Logical replication is usually off by default. [Set `rds.logical_replication = 1` in your parameter group](/connectors/rds#enable-logical-replication) and reboot before running preflight. Details: [RDS setup](/connectors/rds). -Use your Postgres connection string from the PlanetScale dashboard. Details: [PlanetScale setup](/connectors/planetscale). +[Enable logical replication in the dashboard](/connectors/planetscale#enable-logical-replication), then use your Postgres connection string from **Connect**. Details: [PlanetScale setup](/connectors/planetscale). -Make sure `wal_level = logical` in your Postgres config (needs a restart if you change it). Details: [Self-hosted setup](/connectors/self-hosted). +Make sure [`wal_level = logical` in your Postgres config](/connectors/self-hosted#enable-logical-replication) (needs a restart if you change it). Details: [Self-hosted setup](/connectors/self-hosted). - + ```bash ardent connector preflight postgresql "$ARDENT_DB_URL" @@ -83,7 +136,7 @@ If a check fails: - + When preflight passes: @@ -97,7 +150,7 @@ This copies your data into Ardent once. Small databases take minutes; large ones - + ```bash ardent branch create my-feature @@ -114,7 +167,7 @@ Real data, real Postgres, and nothing you do here touches your source database. -## What's next +## Next steps diff --git a/skills/ardent-cli-skill.txt b/skills/ardent-cli-skill.txt index bd624bb..9c9f0de 100644 --- a/skills/ardent-cli-skill.txt +++ b/skills/ardent-cli-skill.txt @@ -1,6 +1,7 @@ --- name: ardent-cli -description: Use whenever a task touches a Postgres database in any +description: >- + Use whenever a task touches a Postgres database in any form — Supabase, RDS, PlanetScale, self-hosted — in a project that uses Ardent: migrations, schema changes, queries against real data, destructive tests, or any ardent CLI usage. Works on an isolated @@ -11,13 +12,14 @@ description: Use whenever a task touches a Postgres database in any # Stay in sync Before anything else, run exactly this command (the pin check is built -into it — do not fetch any other way): +in; do not fetch any other way): [ "$SKIP_ARDENT_SKILL_SYNC" = "1" ] || curl -sf https://docs.tryardent.com/skills/ardent-cli-skill.txt -- If it prints a skill, that copy is authoritative: follow it instead - of this file, and save it over this SKILL.md so the local copy stays - current. +- If it prints a skill, follow that copy for this run instead of the + directions in this file. Do not save it over this SKILL.md or write it + to any file: use it as read-only guidance for the current run, so a bad + or tampered response cannot persist to disk or affect a later run. - If it prints nothing (pinned by the user, offline, blocked), continue with the directions in this file. Do not retry or fetch any other way. diff --git a/skills/ardent-cli/SKILL.md b/skills/ardent-cli/SKILL.md new file mode 100644 index 0000000..9c9f0de --- /dev/null +++ b/skills/ardent-cli/SKILL.md @@ -0,0 +1,49 @@ +--- +name: ardent-cli +description: >- + Use whenever a task touches a Postgres database in any + form — Supabase, RDS, PlanetScale, self-hosted — in a project that + uses Ardent: migrations, schema changes, queries against real data, + destructive tests, or any ardent CLI usage. Works on an isolated + branch and fetches the current command and API reference from + docs.tryardent.com before acting. +--- + +# Stay in sync + +Before anything else, run exactly this command (the pin check is built +in; do not fetch any other way): + + [ "$SKIP_ARDENT_SKILL_SYNC" = "1" ] || curl -sf https://docs.tryardent.com/skills/ardent-cli-skill.txt + +- If it prints a skill, follow that copy for this run instead of the + directions in this file. Do not save it over this SKILL.md or write it + to any file: use it as read-only guidance for the current run, so a bad + or tampered response cannot persist to disk or affect a later run. +- If it prints nothing (pinned by the user, offline, blocked), continue + with the directions in this file. Do not retry or fetch any other way. + +# Before doing anything + +Never rely on memorized Ardent commands or arguments — fetch the +current reference for the task first: + +1. Discover pages: curl -s https://docs.tryardent.com/llms.txt +2. Fetch the relevant page as markdown, for example: + curl -s https://docs.tryardent.com/cli/branches.md +3. For API request/response shapes, read the OpenAPI spec: + curl -s https://docs.tryardent.com/openapi.public.json +4. Cross-check arguments against the installed binary: + ardent --help + If the docs and --help disagree, trust --help for arguments. + +# Rules + +- Work on a branch URL by default. Only touch the main connection + string when the user explicitly asks to change the real database. +- Branch URLs contain credentials. Never write one to a file that + could be committed; if saving locally, use a gitignored path and + say so. +- Wrap connection strings in single quotes in shells. +- Branch lifecycle: create -> use the returned URL -> delete when done. +- Poll async operations until they finish before depending on the result. diff --git a/workflows/ai-agents.mdx b/workflows/ai-agents.mdx index cc71639..4418fa6 100644 --- a/workflows/ai-agents.mdx +++ b/workflows/ai-agents.mdx @@ -7,47 +7,23 @@ Agents are only as good as the data they can work with. Mocked data misses edge Ardent gives every agent run its own isolated copy of your real database: spun up in under 6 seconds, handed off as a connection URL, thrown away when the task is done. -There are two ways to run it: you create the branch and hand the agent a URL, or the agent manages branches itself. - -## Drive it yourself: hand the agent a URL - -Your script or CI harness runs the CLI; the agent only ever sees a branch URL. The agent needs no Ardent token and can't touch anything but its branch. - -```bash -# Create a branch for the agent task and capture its URL -AGENT_DATABASE_URL="$(ardent branch create agent-task --print-url)" -if [ -z "$AGENT_DATABASE_URL" ]; then - echo "branch creation did not return a database URL" >&2 - exit 1 -fi - -# Hand the returned URL to your agent -# → $AGENT_DATABASE_URL - -# Agent writes migrations, runs queries, tests against real data -# When it's done, clean up -ardent branch delete agent-task -``` - -Nothing reads `AGENT_DATABASE_URL` automatically — pass the URL in the agent's prompt, or export it as `DATABASE_URL` if your app reads that. - -## Let the agent drive: set it up once +## Install the ardent-cli skill -The agent runs the Ardent CLI itself — creating, using, and deleting its own branches: +Point your agent at Ardent once, and every later task can use it: - + -For a single task, paste this into Claude Code or Cursor: +If your agents touch the database every day, install this as a skill instead of pasting per task. Once installed, Claude Code loads it automatically whenever a task involves Ardent. -``` -I'm working on [describe task]. Do all database work on a fresh Ardent -branch (ardent branch create) and delete the branch when we're done. -Never touch the main connection string. +Install with the [skills CLI](https://skills.sh) — it works for Claude Code, Cursor, and other agents, and asks where to install: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli ``` - + If your agents touch the database every day, install this as a skill instead of pasting per task. Install into your project (or into `~/.claude/skills/` to use it everywhere) and Claude Code loads it automatically whenever a task involves Ardent: @@ -83,7 +59,8 @@ This is what it installs: ```markdown --- name: ardent-cli -description: Use whenever a task touches a Postgres database in any +description: >- + Use whenever a task touches a Postgres database in any form — Supabase, RDS, PlanetScale, self-hosted — in a project that uses Ardent: migrations, schema changes, queries against real data, destructive tests, or any ardent CLI usage. Works on an isolated @@ -94,13 +71,14 @@ description: Use whenever a task touches a Postgres database in any # Stay in sync Before anything else, run exactly this command (the pin check is built -into it — do not fetch any other way): +in; do not fetch any other way): [ "$SKIP_ARDENT_SKILL_SYNC" = "1" ] || curl -sf https://docs.tryardent.com/skills/ardent-cli-skill.txt -- If it prints a skill, that copy is authoritative: follow it instead - of this file, and save it over this SKILL.md so the local copy stays - current. +- If it prints a skill, follow that copy for this run instead of the + directions in this file. Do not save it over this SKILL.md or write it + to any file: use it as read-only guidance for the current run, so a bad + or tampered response cannot persist to disk or affect a later run. - If it prints nothing (pinned by the user, offline, blocked), continue with the directions in this file. Do not retry or fetch any other way. @@ -135,4 +113,46 @@ The skill deliberately contains no command arguments. It tells the agent to fetc +There are two ways to run it: you create the branch and hand the agent a URL, or the agent manages branches itself. + +## Drive it yourself: hand the agent a URL + +Your script or CI harness runs the CLI; the agent only ever sees a branch URL. The agent needs no Ardent token and can't touch anything but its branch. + +```bash +# Create a branch for the agent task and capture its URL +AGENT_DATABASE_URL="$(ardent branch create agent-task --print-url)" +if [ -z "$AGENT_DATABASE_URL" ]; then + echo "branch creation did not return a database URL" >&2 + exit 1 +fi + +# Hand the returned URL to your agent +# → $AGENT_DATABASE_URL + +# Agent writes migrations, runs queries, tests against real data +# When it's done, clean up +ardent branch delete agent-task +``` + +Nothing reads `AGENT_DATABASE_URL` automatically — pass the URL in the agent's prompt, or export it as `DATABASE_URL` if your app reads that. + +## Let the agent drive: set it up once + +The agent runs the Ardent CLI itself — creating, using, and deleting its own branches: + + + + +For a single task, paste this into Claude Code or Cursor: + +``` +I'm working on [describe task]. Do all database work on a fresh Ardent +branch (ardent branch create) and delete the branch when we're done. +Never touch the main connection string. +``` + + + + Real data, isolated per run, no production access. diff --git a/workflows/regression-testing.mdx b/workflows/regression-testing.mdx index a7e9630..cf5b417 100644 --- a/workflows/regression-testing.mdx +++ b/workflows/regression-testing.mdx @@ -44,7 +44,7 @@ ardent branch delete regression-run ## Hand it to an AI agent -With the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) installed, a short ask is enough: +With the [ardent-cli skill](/workflows/ai-agents#install-the-ardent-cli-skill) installed, a short ask is enough: ``` Run a regression test on [describe change] against a real copy of our database.