From a8a51fad4a4278d9045fc24616f847a7e645ad6a Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 10:37:19 -0400 Subject: [PATCH 01/13] docs: make Step sections deep-linkable with explicit anchor ids Mintlify only anchors a Step when an explicit id prop is set (live site rendered id=""), so Quickstart and connector setup steps were not linkable. Also rename "What's next" to "Next steps" so the heading anchor stays plain ASCII under smart typography. --- connectors/planetscale.mdx | 4 ++-- connectors/rds.mdx | 6 +++--- connectors/self-hosted.mdx | 10 +++++----- connectors/supabase.mdx | 6 +++--- quickstart.mdx | 14 +++++++------- 5 files changed, 20 insertions(+), 20 deletions(-) diff --git a/connectors/planetscale.mdx b/connectors/planetscale.mdx index 85b5fc7..acaf459 100644 --- a/connectors/planetscale.mdx +++ b/connectors/planetscale.mdx @@ -37,13 +37,13 @@ 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..00869dd 100644 --- a/connectors/rds.mdx +++ b/connectors/rds.mdx @@ -38,7 +38,7 @@ 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..1c01c1e 100644 --- a/connectors/self-hosted.mdx +++ b/connectors/self-hosted.mdx @@ -48,7 +48,7 @@ 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..ab75da6 100644 --- a/connectors/supabase.mdx +++ b/connectors/supabase.mdx @@ -38,7 +38,7 @@ 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/quickstart.mdx b/quickstart.mdx index a559ac7..7e53934 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 @@ -38,7 +38,7 @@ On a fresh account, create a project first: `ardent project create my-app`. If y - + Save it in your shell so the next two commands can reuse it: @@ -67,7 +67,7 @@ Make sure `wal_level = logical` in your Postgres config (needs a restart if you - + ```bash ardent connector preflight postgresql "$ARDENT_DB_URL" @@ -83,7 +83,7 @@ If a check fails: - + When preflight passes: @@ -97,7 +97,7 @@ This copies your data into Ardent once. Small databases take minutes; large ones - + ```bash ardent branch create my-feature @@ -114,7 +114,7 @@ Real data, real Postgres, and nothing you do here touches your source database. -## What's next +## Next steps From dfcdd0bcb4d716ccf675c49f4225e65262807510 Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 10:42:26 -0400 Subject: [PATCH 02/13] docs: say what the quickstart connection string is MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Get your connection string" step jumped straight to "Save it in your shell" without saying what "it" is. State up front that it's the Postgres URL of the source database's writable primary — not a read replica or pooler endpoint — since preflight rejects both and the connector pages already warn about them. --- quickstart.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/quickstart.mdx b/quickstart.mdx index 7e53934..e7216f1 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -40,6 +40,8 @@ On a fresh account, create a project first: `ardent project create my-app`. If y +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: ```bash From d11bf41afea83085989dccb35916973af875ad4b Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 11:04:21 -0400 Subject: [PATCH 03/13] docs: add Branch behavior concepts page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Customer feedback: nothing in the docs said whether branches keep receiving replication after creation — the answer (they don't; a branch is frozen at creation time) was living in DMs and one FAQ accordion. New Concepts page states it up front, plus contents, lifecycle, isolation, and copy-on-write storage, all sourced from existing FAQ/architecture/CLI claims (no new billing or behavior claims). FAQ sync answer now links to it. --- branches.mdx | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ docs.json | 1 + faq.mdx | 2 +- 3 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 branches.mdx 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/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. From 3b5cbce29111315254229c7593038ac77dd89019 Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 11:08:05 -0400 Subject: [PATCH 04/13] docs: make the ardent-cli skill installable via npx skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds skills/ardent-cli/SKILL.md — the layout the skills.sh CLI discovers — so 'npx skills add ArdentAILabs/docs --skill ardent-cli' works once this merges to the public repo. The served .txt stays canonical (installed skills self-update from that URL); a CI check diffs the two copies so they can't drift. Also fixes the skill frontmatter: the description contained 'uses Ardent: migrations', a ': ' inside an unquoted YAML scalar. Claude Code tolerates it but strict parsers (including npx skills) reject the whole skill. Folded block scalar (>-) yields the same string and parses everywhere. Verified by installing from the local repo with npx skills: discovery, install, and byte-identical content. The AI agents page now leads with the npx install and keeps curl as the no-npm fallback. --- .github/workflows/skill-sync.yml | 24 ++++++++++++++++ skills/ardent-cli-skill.txt | 3 +- skills/ardent-cli/SKILL.md | 48 ++++++++++++++++++++++++++++++++ workflows/ai-agents.mdx | 13 +++++++-- 4 files changed, 85 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/skill-sync.yml create mode 100644 skills/ardent-cli/SKILL.md 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/skills/ardent-cli-skill.txt b/skills/ardent-cli-skill.txt index bd624bb..4c7652c 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 diff --git a/skills/ardent-cli/SKILL.md b/skills/ardent-cli/SKILL.md new file mode 100644 index 0000000..4c7652c --- /dev/null +++ b/skills/ardent-cli/SKILL.md @@ -0,0 +1,48 @@ +--- +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 +into it — 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 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..407aee2 100644 --- a/workflows/ai-agents.mdx +++ b/workflows/ai-agents.mdx @@ -49,7 +49,15 @@ Never touch the main connection string. -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: +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. + +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 +``` + +Or without npm, curl it into your project (or into `~/.claude/skills/` to use it everywhere): ```bash mkdir -p .claude/skills/ardent-cli @@ -83,7 +91,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 From e7e45396ba6e15c43f6699e5a256182c820047fc Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 11:27:11 -0400 Subject: [PATCH 05/13] docs: split agent accordion into skill and manual collapsibles The single 'Using Claude Code or Cursor? It can do the checks for you' accordion mixed two different paths in one box. Each page now has an AccordionGroup with two collapsibles: one installing the ardent-cli skill via npx skills plus the short ask, and one with the original full paste-in directions, unchanged. Applied to index and all four connector pages; verified both accordions render on the local preview. --- connectors/planetscale.mdx | 16 +++++++++++++--- connectors/rds.mdx | 16 +++++++++++++--- connectors/self-hosted.mdx | 16 +++++++++++++--- connectors/supabase.mdx | 16 +++++++++++++--- index.mdx | 16 +++++++++++++--- 5 files changed, 65 insertions(+), 15 deletions(-) diff --git a/connectors/planetscale.mdx b/connectors/planetscale.mdx index acaf459..617c874 100644 --- a/connectors/planetscale.mdx +++ b/connectors/planetscale.mdx @@ -5,15 +5,24 @@ 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#let-the-agent-drive-set-it-up-once) once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then 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: + +Paste the full directions into your agent: ``` Check if my PlanetScale Postgres database is ready to connect to Ardent. @@ -33,6 +42,7 @@ After preflight passes, run: ardent connector create postgresql '' ``` + Two things matter here: diff --git a/connectors/rds.mdx b/connectors/rds.mdx index 00869dd..12c7c88 100644 --- a/connectors/rds.mdx +++ b/connectors/rds.mdx @@ -5,15 +5,24 @@ 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#let-the-agent-drive-set-it-up-once) once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then 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: + +Paste the full directions into your agent: ``` Check if my AWS RDS Postgres database is ready to connect to Ardent. @@ -34,6 +43,7 @@ After preflight passes, run: ardent connector create postgresql '' ``` + RDS needs three things before preflight can pass: diff --git a/connectors/self-hosted.mdx b/connectors/self-hosted.mdx index 1c01c1e..d59746a 100644 --- a/connectors/self-hosted.mdx +++ b/connectors/self-hosted.mdx @@ -15,15 +15,24 @@ 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#let-the-agent-drive-set-it-up-once) once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then 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: + +Paste the full directions into your agent: ``` Check whether my self-hosted Postgres database is ready to connect to Ardent. @@ -45,6 +54,7 @@ After preflight passes, run: ardent connector create postgresql '' ``` + diff --git a/connectors/supabase.mdx b/connectors/supabase.mdx index ab75da6..6700274 100644 --- a/connectors/supabase.mdx +++ b/connectors/supabase.mdx @@ -5,15 +5,24 @@ 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#let-the-agent-drive-set-it-up-once) once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then 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: + +Paste the full directions into your agent: ``` Check if my Supabase database is ready to connect to Ardent. @@ -34,6 +43,7 @@ After preflight passes, run: ardent connector create postgresql '' ``` + Three things matter here: diff --git a/index.mdx b/index.mdx index b9df824..f5804f7 100644 --- a/index.mdx +++ b/index.mdx @@ -28,15 +28,24 @@ 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 [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) 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] ``` + -Without the skill, paste the full directions: + +Paste the full directions into your agent: ``` Set up Ardent for database branching. Act like a teammate at my keyboard: @@ -73,6 +82,7 @@ Run these in order: If a command errors, fix it. Docs: https://docs.tryardent.com/quickstart ``` + ## How it works From ab68290ef6d9dda2e8683db0c1dec236c59e39a1 Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 11:33:44 -0400 Subject: [PATCH 06/13] Revert "docs: split agent accordion into skill and manual collapsibles" This reverts commit e7e45396ba6e15c43f6699e5a256182c820047fc. --- connectors/planetscale.mdx | 16 +++------------- connectors/rds.mdx | 16 +++------------- connectors/self-hosted.mdx | 16 +++------------- connectors/supabase.mdx | 16 +++------------- index.mdx | 16 +++------------- 5 files changed, 15 insertions(+), 65 deletions(-) diff --git a/connectors/planetscale.mdx b/connectors/planetscale.mdx index 617c874..acaf459 100644 --- a/connectors/planetscale.mdx +++ b/connectors/planetscale.mdx @@ -5,24 +5,15 @@ 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). - - -Install the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) once: - -```bash -npx skills add ArdentAILabs/docs --skill ardent-cli -``` - -Then a short ask is enough — the skill fetches this page and runs the checks: + +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: ``` Check if my PlanetScale Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` - - -Paste the full directions into your agent: +Without the skill, paste the full directions: ``` Check if my PlanetScale Postgres database is ready to connect to Ardent. @@ -42,7 +33,6 @@ After preflight passes, run: ardent connector create postgresql '' ``` - Two things matter here: diff --git a/connectors/rds.mdx b/connectors/rds.mdx index 12c7c88..00869dd 100644 --- a/connectors/rds.mdx +++ b/connectors/rds.mdx @@ -5,24 +5,15 @@ 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). - - -Install the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) once: - -```bash -npx skills add ArdentAILabs/docs --skill ardent-cli -``` - -Then a short ask is enough — the skill fetches this page and runs the checks: + +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: ``` Check if my AWS RDS Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` - - -Paste the full directions into your agent: +Without the skill, paste the full directions: ``` Check if my AWS RDS Postgres database is ready to connect to Ardent. @@ -43,7 +34,6 @@ After preflight passes, run: ardent connector create postgresql '' ``` - RDS needs three things before preflight can pass: diff --git a/connectors/self-hosted.mdx b/connectors/self-hosted.mdx index d59746a..1c01c1e 100644 --- a/connectors/self-hosted.mdx +++ b/connectors/self-hosted.mdx @@ -15,24 +15,15 @@ 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. - - -Install the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) once: - -```bash -npx skills add ArdentAILabs/docs --skill ardent-cli -``` - -Then a short ask is enough — the skill fetches this page and runs the checks: + +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: ``` Check whether my self-hosted Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` - - -Paste the full directions into your agent: +Without the skill, paste the full directions: ``` Check whether my self-hosted Postgres database is ready to connect to Ardent. @@ -54,7 +45,6 @@ After preflight passes, run: ardent connector create postgresql '' ``` - diff --git a/connectors/supabase.mdx b/connectors/supabase.mdx index 6700274..ab75da6 100644 --- a/connectors/supabase.mdx +++ b/connectors/supabase.mdx @@ -5,24 +5,15 @@ 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). - - -Install the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) once: - -```bash -npx skills add ArdentAILabs/docs --skill ardent-cli -``` - -Then a short ask is enough — the skill fetches this page and runs the checks: + +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: ``` Check if my Supabase database is ready to connect to Ardent. My connection string: [paste here] ``` - - -Paste the full directions into your agent: +Without the skill, paste the full directions: ``` Check if my Supabase database is ready to connect to Ardent. @@ -43,7 +34,6 @@ After preflight passes, run: ardent connector create postgresql '' ``` - Three things matter here: diff --git a/index.mdx b/index.mdx index f5804f7..b9df824 100644 --- a/index.mdx +++ b/index.mdx @@ -28,24 +28,15 @@ No more shared staging databases. No more hand-maintained fixtures. An instant d Branch your Postgres database in a few commands. - - -Install the [ardent-cli skill](/workflows/ai-agents#let-the-agent-drive-set-it-up-once) 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: + +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: ``` Set up Ardent for database branching on this project. My connection string: [paste here] ``` - - -Paste the full directions into your agent: +Without the skill, paste the full directions: ``` Set up Ardent for database branching. Act like a teammate at my keyboard: @@ -82,7 +73,6 @@ Run these in order: If a command errors, fix it. Docs: https://docs.tryardent.com/quickstart ``` - ## How it works From 64246259725f4fef5e1f45bead3ca22ae307f185 Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 11:34:37 -0400 Subject: [PATCH 07/13] docs: split permanent-skill accordion into npx and manual collapsibles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'Permanent AI skill: SKILL.md' accordion mixed the npx skills install with the manual path. Now two collapsibles: 'install with npx' (skills CLI one-liner) and 'manual SKILL.md and CLAUDE.md', which restores the original text — curl install into .claude/skills/, the self-update/pinning notes, the CLAUDE.md snippet, and the full skill listing. --- workflows/ai-agents.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/workflows/ai-agents.mdx b/workflows/ai-agents.mdx index 407aee2..6e26f13 100644 --- a/workflows/ai-agents.mdx +++ b/workflows/ai-agents.mdx @@ -47,7 +47,7 @@ Never touch the main connection string. ``` - + 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. @@ -57,7 +57,10 @@ Install with the [skills CLI](https://skills.sh) — it works for Claude Code, C npx skills add ArdentAILabs/docs --skill ardent-cli ``` -Or without npm, curl it into your project (or into `~/.claude/skills/` to use it everywhere): + + + +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: ```bash mkdir -p .claude/skills/ardent-cli From 9d7894a6585804c78935a054a95b8a9d1c32c491 Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 11:46:07 -0400 Subject: [PATCH 08/13] docs: skill dropdowns hold install paths; full directions moved outside MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit On index and the four connector pages, the skill area is now two collapsibles: 'Set up the ardent-cli skill with npx' and 'Set up the ardent-cli skill manually: SKILL.md and CLAUDE.md' — the latter is the original install text (curl into .claude/skills/ plus the CLAUDE.md snippet), with a pointer to the AI agents page for self-update and pinning details. The 'without the skill, paste the full directions' prompt is its own section outside the skill dropdowns, text unchanged. --- connectors/planetscale.mdx | 50 +++++++++++++++++++++++++++++++++++--- connectors/rds.mdx | 50 +++++++++++++++++++++++++++++++++++--- connectors/self-hosted.mdx | 50 +++++++++++++++++++++++++++++++++++--- connectors/supabase.mdx | 50 +++++++++++++++++++++++++++++++++++--- index.mdx | 50 +++++++++++++++++++++++++++++++++++--- 5 files changed, 230 insertions(+), 20 deletions(-) diff --git a/connectors/planetscale.mdx b/connectors/planetscale.mdx index acaf459..9a47351 100644 --- a/connectors/planetscale.mdx +++ b/connectors/planetscale.mdx @@ -5,15 +5,58 @@ 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 skill once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then 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] ``` + + + +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. +``` -Without the skill, paste the full directions: +Then 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] +``` + +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). + + + +Without the skill, paste the full directions into your agent: ``` Check if my PlanetScale Postgres database is ready to connect to Ardent. @@ -32,7 +75,6 @@ Verify: After preflight passes, run: ardent connector create postgresql '' ``` - Two things matter here: diff --git a/connectors/rds.mdx b/connectors/rds.mdx index 00869dd..80311dc 100644 --- a/connectors/rds.mdx +++ b/connectors/rds.mdx @@ -5,15 +5,58 @@ 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 skill once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then 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] ``` + + + +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. +``` -Without the skill, paste the full directions: +Then 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] +``` + +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). + + + +Without the skill, paste the full directions into your agent: ``` Check if my AWS RDS Postgres database is ready to connect to Ardent. @@ -33,7 +76,6 @@ Verify: After preflight passes, run: ardent connector create postgresql '' ``` - RDS needs three things before preflight can pass: diff --git a/connectors/self-hosted.mdx b/connectors/self-hosted.mdx index 1c01c1e..1c75e2f 100644 --- a/connectors/self-hosted.mdx +++ b/connectors/self-hosted.mdx @@ -15,15 +15,58 @@ 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 skill once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then 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] +``` + + + +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 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: +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). + + + +Without the skill, paste the full directions into your agent: ``` Check whether my self-hosted Postgres database is ready to connect to Ardent. @@ -44,7 +87,6 @@ Then verify these source requirements and tell me exactly what to fix: After preflight passes, run: ardent connector create postgresql '' ``` - diff --git a/connectors/supabase.mdx b/connectors/supabase.mdx index ab75da6..9d83160 100644 --- a/connectors/supabase.mdx +++ b/connectors/supabase.mdx @@ -5,15 +5,58 @@ 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 skill once: + +```bash +npx skills add ArdentAILabs/docs --skill ardent-cli +``` + +Then 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] ``` + + + +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. +``` -Without the skill, paste the full directions: +Then 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] +``` + +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). + + + +Without the skill, paste the full directions into your agent: ``` Check if my Supabase database is ready to connect to Ardent. @@ -33,7 +76,6 @@ Verify: After preflight passes, run: ardent connector create postgresql '' ``` - Three things matter here: diff --git a/index.mdx b/index.mdx index b9df824..b57e306 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. +``` -Without the skill, paste the full directions: +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] +``` + +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). + + + +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 From 4878c26223def6dad13f8e0cdecc4702fcb17d59 Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 11:51:17 -0400 Subject: [PATCH 09/13] docs: move skill install to top of AI agents page The npx and manual (SKILL.md + CLAUDE.md) install collapsibles now lead the page under an 'Install the ardent-cli skill' heading instead of sitting at the bottom of 'Let the agent drive'. Inbound links from index, the connector pages, and regression-testing now point at the new #install-the-ardent-cli-skill anchor. --- connectors/planetscale.mdx | 2 +- connectors/rds.mdx | 2 +- connectors/self-hosted.mdx | 2 +- connectors/supabase.mdx | 2 +- index.mdx | 2 +- workflows/ai-agents.mdx | 85 +++++++++++++++++--------------- workflows/regression-testing.mdx | 2 +- 7 files changed, 52 insertions(+), 45 deletions(-) diff --git a/connectors/planetscale.mdx b/connectors/planetscale.mdx index 9a47351..9d15d99 100644 --- a/connectors/planetscale.mdx +++ b/connectors/planetscale.mdx @@ -52,7 +52,7 @@ Check if my PlanetScale Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` -Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#install-the-ardent-cli-skill). diff --git a/connectors/rds.mdx b/connectors/rds.mdx index 80311dc..984221a 100644 --- a/connectors/rds.mdx +++ b/connectors/rds.mdx @@ -52,7 +52,7 @@ Check if my AWS RDS Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` -Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#install-the-ardent-cli-skill). diff --git a/connectors/self-hosted.mdx b/connectors/self-hosted.mdx index 1c75e2f..c54490b 100644 --- a/connectors/self-hosted.mdx +++ b/connectors/self-hosted.mdx @@ -62,7 +62,7 @@ Check whether my self-hosted Postgres database is ready to connect to Ardent. My connection string: [paste here] ``` -Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#install-the-ardent-cli-skill). diff --git a/connectors/supabase.mdx b/connectors/supabase.mdx index 9d83160..3554a41 100644 --- a/connectors/supabase.mdx +++ b/connectors/supabase.mdx @@ -52,7 +52,7 @@ Check if my Supabase database is ready to connect to Ardent. My connection string: [paste here] ``` -Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#let-the-agent-drive-set-it-up-once). +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#install-the-ardent-cli-skill). diff --git a/index.mdx b/index.mdx index b57e306..2580229 100644 --- a/index.mdx +++ b/index.mdx @@ -75,7 +75,7 @@ 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#let-the-agent-drive-set-it-up-once). +Self-update behavior, pinning, and the full skill contents: [AI agents](/workflows/ai-agents#install-the-ardent-cli-skill). diff --git a/workflows/ai-agents.mdx b/workflows/ai-agents.mdx index 6e26f13..e73505f 100644 --- a/workflows/ai-agents.mdx +++ b/workflows/ai-agents.mdx @@ -7,47 +7,12 @@ 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: - -``` -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. -``` - - - + 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. @@ -58,7 +23,7 @@ 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: @@ -147,4 +112,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. From e1e08cb12f178a7d08ce1ea54e289be13c5353a0 Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 12:12:07 -0400 Subject: [PATCH 10/13] docs: state branch freeze behavior on the landing page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit How-it-works now says up front that a branch is frozen at creation — no replication in, no writes flowing back — and that fresh data means cutting a new branch, linking to the Branch behavior page. Feedback showed readers reached the end of the intro still assuming branches keep receiving WAL. --- index.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/index.mdx b/index.mdx index 2580229..7402117 100644 --- a/index.mdx +++ b/index.mdx @@ -131,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 From 901702dd753be524332fcdaacda0ac84345ec1f8 Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 12:15:10 -0400 Subject: [PATCH 11/13] docs: deep-link quickstart provider tabs to the fixing step MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each provider tab names the thing that usually blocks preflight; the sentence now links straight to the connector-page step that fixes it (direct-connection step for Supabase, enable-logical-replication for RDS/PlanetScale/self-hosted) — first internal use of the step anchors. The PlanetScale tab previously never mentioned its blocker at all. --- quickstart.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/quickstart.mdx b/quickstart.mdx index e7216f1..d6c5350 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -54,16 +54,16 @@ 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). From 14875040a0dcb5905a0b107ffb905a108b1a757e Mon Sep 17 00:00:00 2001 From: xmcp123 Date: Thu, 16 Jul 2026 12:18:30 -0400 Subject: [PATCH 12/13] docs: AI install lives in the quickstart; connector pages stay provider-specific MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The connector pages promise 'only what's specific to X' but carried the generic skill-install collapsibles, while the quickstart — the actual flow — never mentioned the AI option even though everything after ardent login can be delegated. Now: the Log in step ends with 'Prefer to hand it off?' and the npx/manual install collapsibles; the connector pages keep one provider-specific accordion (short ask, with the install linked) and the separate full-directions block, unchanged. --- connectors/planetscale.mdx | 46 ++-------------------------------- connectors/rds.mdx | 46 ++-------------------------------- connectors/self-hosted.mdx | 46 ++-------------------------------- connectors/supabase.mdx | 46 ++-------------------------------- quickstart.mdx | 51 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 59 insertions(+), 176 deletions(-) diff --git a/connectors/planetscale.mdx b/connectors/planetscale.mdx index 9d15d99..20e3ecb 100644 --- a/connectors/planetscale.mdx +++ b/connectors/planetscale.mdx @@ -5,15 +5,8 @@ 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). - - -Install the skill once: - -```bash -npx skills add ArdentAILabs/docs --skill ardent-cli -``` - -Then 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. @@ -21,41 +14,6 @@ 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 this page and runs the checks: - -``` -Check if my PlanetScale Postgres database is ready to connect to Ardent. -My connection string: [paste here] -``` - -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: ``` diff --git a/connectors/rds.mdx b/connectors/rds.mdx index 984221a..a70e2c0 100644 --- a/connectors/rds.mdx +++ b/connectors/rds.mdx @@ -5,15 +5,8 @@ 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). - - -Install the skill once: - -```bash -npx skills add ArdentAILabs/docs --skill ardent-cli -``` - -Then 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. @@ -21,41 +14,6 @@ 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 this page and runs the checks: - -``` -Check if my AWS RDS Postgres database is ready to connect to Ardent. -My connection string: [paste here] -``` - -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: ``` diff --git a/connectors/self-hosted.mdx b/connectors/self-hosted.mdx index c54490b..233c0a3 100644 --- a/connectors/self-hosted.mdx +++ b/connectors/self-hosted.mdx @@ -15,56 +15,14 @@ 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. - - -Install the skill once: - -```bash -npx skills add ArdentAILabs/docs --skill ardent-cli -``` - -Then 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] -``` - - - -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 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] ``` - -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: diff --git a/connectors/supabase.mdx b/connectors/supabase.mdx index 3554a41..9349382 100644 --- a/connectors/supabase.mdx +++ b/connectors/supabase.mdx @@ -5,15 +5,8 @@ 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). - - -Install the skill once: - -```bash -npx skills add ArdentAILabs/docs --skill ardent-cli -``` - -Then 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. @@ -21,41 +14,6 @@ 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 this page and runs the checks: - -``` -Check if my Supabase database is ready to connect to Ardent. -My connection string: [paste here] -``` - -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: ``` diff --git a/quickstart.mdx b/quickstart.mdx index d6c5350..f344f1c 100644 --- a/quickstart.mdx +++ b/quickstart.mdx @@ -36,6 +36,57 @@ 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). + + + From 310b1516f49931763868574797aef4fa626f88ab Mon Sep 17 00:00:00 2001 From: evanvolgas Date: Thu, 16 Jul 2026 19:21:46 +0000 Subject: [PATCH 13/13] docs: skill self-sync follows fetched copy without writing it to disk The skill told installed agents to save the fetched remote copy over their local SKILL.md, so a bad or tampered response from the docs endpoint could persist into a customer repo and taint every later run (flagged by Greptile, P2 security). Keep the fetch-first self-sync but follow the fetched copy as read-only guidance for the current run only; never overwrite the on-disk skill. Co-authored-by: Codesmith --- skills/ardent-cli-skill.txt | 9 +++++---- skills/ardent-cli/SKILL.md | 9 +++++---- workflows/ai-agents.mdx | 9 +++++---- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/skills/ardent-cli-skill.txt b/skills/ardent-cli-skill.txt index 4c7652c..9c9f0de 100644 --- a/skills/ardent-cli-skill.txt +++ b/skills/ardent-cli-skill.txt @@ -12,13 +12,14 @@ description: >- # 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 index 4c7652c..9c9f0de 100644 --- a/skills/ardent-cli/SKILL.md +++ b/skills/ardent-cli/SKILL.md @@ -12,13 +12,14 @@ description: >- # 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/workflows/ai-agents.mdx b/workflows/ai-agents.mdx index e73505f..4418fa6 100644 --- a/workflows/ai-agents.mdx +++ b/workflows/ai-agents.mdx @@ -71,13 +71,14 @@ description: >- # 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.