Ardent Documentation Audit

The CLI surface and Postgres connector setup are covered competently, but a developer who needs anything beyond the happy path — HTTP API, BYOC provisioning, version history, error reference, troubleshooting — falls off a cliff. The biggest single problem is a direct contradiction between the FAQ's security promise and the recommended onboarding flow.

1. BYOC deployment exposes four AWS flags with zero setup documentation (critical)

Location: /cli/connectors.md, /architecture.md, /security.md (vs. missing /byoc page — 404)

Problem: The connector CLI offers a complete "customer-cloud" deployment path:

ardent connector create postgresql '<url>' \
  --deployment-model customer-cloud \
  --aws-role-arn <arn> \
  --aws-external-id <id> \
  --aws-region us-east-1 \
  --aws-cluster-name <cluster>

Nothing in the docs explains where <arn>, <id>, or <cluster> come from, what IAM policy the role needs, how the external-id is generated, or what AWS resources Ardent expects to find under <cluster>. The architecture page describes "Managed, your cloud" at concept level only ("the data plane deploys into your own cloud account"); the security page mentions AWS SSM Parameter Store for secrets but again with no setup steps. /byoc and /byoc.md both 404. The marketing pricing page advertises "Template BYOC" (Scale) vs "Custom BYOC" (Enterprise) as differentiated SKUs — neither term appears anywhere in the docs.

Consequence: A team paying for the Scale tier ($250/mo) cannot self-serve the BYOC feature they're paying for. They cannot tell their cloud team what IAM trust policy to attach, which AWS account ID to whitelist, or what regions are supported. The CLI offers no way to discover the values; if they paste in wrong ARNs the command will fail with a runtime error against a feature with no troubleshooting page.

The fix: Publish /byoc with: (a) the CloudFormation/Terraform module or step-by-step IAM role setup, (b) exactly which trust policy and external-id pattern Ardent expects, (c) regional availability, (d) what --aws-cluster-name refers to (EKS cluster? RDS cluster? new ECS cluster?), (e) the difference between "Template BYOC" and "Custom BYOC" from the pricing page. Link it from /cli/connectors, /architecture, and /security.

2. FAQ promises LLMs never see real credentials; every connector page asks the user to paste them into one (critical)

Location: /faq.md vs. /connectors/rds.md, /connectors/self-hosted.md, /connectors/planetscale.md, /connectors/supabase.md

Problem: The FAQ entry "Can I use branches with AI agents?" reassures: "Ardent generates a unique connection string for each branch — your real database credentials are never exposed. … An LLM will never see or have access to your real credentials." That promise is framed around branch URLs. But every connector page leads with a "Want Claude to handle this? Paste this into Claude Code or Cursor:" block that tells the user to paste their production connection string (with real username and password) into the agent for the pre-flight check, e.g. on /connectors/self-hosted.md: "My connection string: [paste here] … Verify: 1. The host is reachable and credentials work …". The same pattern is on the RDS, Supabase, and PlanetScale pages.

Consequence: The headline security claim is wrong as soon as a user follows the recommended onboarding. Production credentials get pasted into a third-party LLM, often into a context that persists in chat history, telemetry, or training pipelines. A security-conscious reader who reads the FAQ first and then follows the connector page has been actively misled.

The fix: Either (a) reword the FAQ to scope the promise to post-connector branch URLs and explicitly call out that the initial connector setup may expose credentials to an LLM if the user opts into the Claude prompt, or (b) rewrite the connector pre-flight prompts so they don't include the connection string — have Claude tell the user what to check, not check it itself. Add a one-line note above each "Paste this into Claude Code" block: "This shares your production connection string with the LLM. Skip this section if that's not acceptable."

3. No HTTP API reference exists, despite the CLI being a thin client over one (critical)

Location: /api-reference (404), /api (404), llms.txt index

Problem: Every URL under /api* returns 404. The llms.txt full index does not list any API page. Yet the architecture page describes a control plane that "still orchestrates everything via API", the CI/CD workflow tells users to "create an API token at https://app.tryardent.com/app/settings/api-keys", and ardent login --token exists — so a REST/RPC API plainly exists.

Consequence: Anyone who wants to integrate Ardent without shelling out to ardent-cli (custom CI runners that can't install Node, internal platform tooling, agents that can't run subprocesses, dashboards) has no documented surface at all. They have to reverse-engineer requests from the CLI binary. Token scoping, rotation, expiry, rate limits, and error codes are also undocumented.

The fix: Publish at minimum a token-auth page covering (a) how to create/rotate/revoke a token, (b) what scopes it has, (c) expiry semantics. Then publish the underlying HTTP endpoints used by the CLI as an OpenAPI spec — even an auto-generated one is better than nothing for agents indexing the docs.

4. No changelog or release notes anywhere (significant)

Location: /changelog (404), llms.txt, sitemap

Problem: /changelog 404s. No release notes, version history, or "what's new" page exists in the sitemap or llms.txt. The CLI is installed via npm install -g ardent-cli with no pinned version anywhere in the docs, and ardent --version is mentioned only as a global flag with no example output. Nothing tells a reader what version is current or what changed between versions.

Consequence: When a user files a bug or asks an agent for help, neither party can say "as of which version". CI pipelines that npm install -g ardent-cli will silently float to whatever the latest is — and there's no way to learn that a flag like --deployment-model was added in a specific release. Breaking changes can ship invisibly.

The fix: Publish /changelog keyed off the npm version of ardent-cli. Even a thin one ("v0.X.Y — added X flag, fixed Y") is enough. Pin a minimum version in the quickstart, and add a real example of ardent --version output to /cli/overview.

5. No error reference, troubleshooting page, or status page (significant)

Location: /troubleshooting (404), /errors (404), /contact.md

Problem: Both /troubleshooting and /errors 404. The contact page is a single card pointing at one individual's personal email (vikram@tryardent.com). No status page, no community channel, no Slack invite — yet the marketing pricing page promises "Slack support" as a Scale-tier perk. The self-hosted connector page also contradicts itself: a <Tip> says "Ardent checks all prerequisites during setup and tells you what's missing", but the same page lists four manual steps plus a Claude verification prompt, and the docs never enumerate what error messages those checks emit.

Consequence: When a connector setup fails — replication slot exhausted, wal_level wrong, RDS reboot pending, security group misconfigured — the developer has no documented mapping from error message to fix. The only escalation path is one person's inbox. Scale-tier customers expecting Slack support have nowhere in the docs that explains how to get into the Slack.

The fix: Add /troubleshooting keyed by the actual error messages the replicator and connector setup emit. Replace the single contact card with an org support address (support@tryardent.com) and a documented path to the Slack for Scale-tier customers. Link a status page if one exists.

6. RDS prerequisite checklist is split between the Claude prompt and the manual steps (significant)

Location: /connectors/rds.md

Problem: The Claude verification prompt at the top of the RDS page lists four checks, including #4: "The security group allows inbound connections on port 5432". The manual <Steps> block below covers parameter group, rds_replication grant, hostname, and the connector create command — but never mentions security groups. The two checklists are not the same set.

Consequence: A user who skips the Claude prompt (e.g., because their tooling can't take a connection string, or because they read finding #2 above and don't want to paste prod credentials into an LLM) follows the manual steps, runs ardent connector create, and then sees a connection-refused error that the docs never warned them about. The most common AWS misconfiguration for new RDS users is not in the manual list.

The fix: Add a "Verify network reachability" step to the manual <Steps> block that covers the security-group inbound rule on 5432 and which CIDR ranges to allow (Ardent's egress IPs for managed mode, or VPC-internal for BYOC). Keep the two checklists in lockstep.

7. CI/CD workflow's URL extraction is brittle and undocumented (significant)

Location: /workflows/ci-cd.md, /cli/branches.md

Problem: The recommended CI snippet extracts the branch URL with:

echo "DATABASE_URL=$(ardent branch info | awk '/URL:/{print $2}')" >> "$GITHUB_ENV"

This depends on (a) ardent branch info always emitting a literal URL: label, (b) the value being whitespace-separated as the second field, (c) no ANSI color codes contaminating the line. The /cli/branches.md reference for ardent branch list narrates in prose that "the current branch is green: the *, health dot, name, and connection URL. Other branches use default color for the name and dim for the URL" — so the CLI definitely emits ANSI for list output and may emit it for info too. There is no documented --json, -o json, or --no-color flag anywhere in the CLI reference.

Consequence: If the CLI ever changes the branch info output format (renames the field, adds a column, emits color codes when stdout is detected as a TTY in some runner), every CI pipeline built from this template silently sets DATABASE_URL to garbage or empty, and tests run against whatever fallback the app has — possibly production.

The fix: Add a --json or --output json flag to the CLI and document it on /cli/branches. Rewrite the CI snippet to use ardent branch info --json | jq -r .url. Until then, at minimum document a --no-color/NO_COLOR=1 guarantee and pin the field-extraction contract in /cli/branches.

8. Branch URLs embed working credentials; CI template writes them to GITHUB_ENV unmasked (significant)

Location: /cli/branches.md, /workflows/local-dev.md, /workflows/regression-testing.md, /workflows/ci-cd.md, /faq.md

Problem: Every example output shows branch URLs as postgresql://user:pass@my-feature-postgres.routing.tryardent.com:5432/db — credentials inline in the URL. The FAQ says these are scoped credentials that can't reach production, which is reassuring, but no page warns that the URL is still a bearer credential for that branch. Worse, the FAQ explicitly says it's "safe to hand branch URLs to AI agents." The CI/CD workflow assigns the full URL to DATABASE_URL in GITHUB_ENV via plain echo — GitHub Actions does not auto-mask values that haven't been registered as secrets, so the URL is loggable in plaintext across the rest of the job.

Consequence: Users paste full branch URLs into Slack, bug reports, agent chat windows, and CI logs without realizing they're handing over working credentials for the duration of that branch's life. CI logs in particular are often retained or piped to third-party log aggregators. The FAQ's reassurance is read as "safe to paste anywhere", which it is not.

The fix: Add a one-line note to /cli/branches, the FAQ, and the CI/CD workflow: "Branch URLs contain a scoped password — treat them like any other secret." Update the CI snippet to call ::add-mask:: on the URL before writing to GITHUB_ENV. Soften the FAQ phrasing from "safe to hand branch URLs to AI agents" to "safe to hand to a sandboxed agent — still treat the URL as a credential."

9. AI-agents workflow never tells the agent how to consume the connection URL (significant)

Location: /workflows/ai-agents.md vs. /workflows/regression-testing.md

Problem: The ai-agents.md Claude prompt says "use the returned connection URL for all database work" but never specifies a mechanism — no env var name, no config file, no export DATABASE_URL=…. By contrast /workflows/regression-testing.md explicitly discusses the DATABASE_URL convention, ORM expectations, and how to wire it in. The two workflow pages disagree on how concrete the integration should be.

Consequence: A coding agent reading ai-agents.md will guess. Sometimes it will hardcode the URL into a script; sometimes it will try to set DATABASE_URL; sometimes it will fall back to whatever connection string is already in the project's .env — which is exactly the production string the workflow is trying to avoid. The whole pitch of Ardent for agents (a real database, safely isolated) depends on the agent actually using the branch URL.

The fix: Rewrite the ai-agents.md Claude prompt to be explicit: "Export the returned URL as DATABASE_URL (or whatever env var the project uses — check .env.example) and run all DB commands with that environment in scope. Do not modify .env itself." Mirror the same paragraph from regression-testing.md so the two pages agree.

10. ANSI color policy is split across command groups with no rationale (minor)

Location: /cli/org.md, /cli/branches.md, /cli/connectors.md, /cli/projects.md

Problem: ardent invite list and ardent org members explicitly state "No ANSI colors." ardent branch list, ardent connector list, and ardent project list are documented as emitting green for the current/selected item and dim for secondary text. No page explains why org/team output is plain while resource lists are colored.

Consequence: A reader writing a script that parses CLI output has to remember per-command which group emits ANSI and which doesn't. Combined with finding #7, anyone building automation around ardent branch info or ardent branch list has to guess what stripping the CLI needs and won't catch a regression where one group's behavior drifts toward the other.

The fix: Either unify the behavior (all list commands respect NO_COLOR / --no-color and emit the same shape) or document the policy explicitly on /cli/overview: "Resource lists colorize the current/selected row; team/org commands do not." Better still, provide a global --output json or --plain flag and pin its contract.

11. regression-testing.md contains an editing artifact referencing content not on the page (minor)

Location: /workflows/regression-testing.md

Problem: The page says: "One-line alternative: DATABASE_URL='…' npm test sets the variable only for that one process, which is why it looked as if the URL and npm test had to share a line." Nothing earlier on the page would make a reader think those two had to share a line — the preceding example uses export DATABASE_URL=… on one line and npm test on the next. This is a stranded sentence from a previous revision.

Consequence: Readers (and agents) re-read the page trying to figure out what "looked as if" refers to, conclude they missed something, and lose trust in the doc. It's a small artifact but it's exactly the kind of thing that makes a careful reader question the rest.

The fix: Delete the trailing clause. The sentence reads cleanly as "DATABASE_URL='…' npm test sets the variable only for that one process. That is valid shell, but export and a separate command are easier to read."

12. ardent status description and example output disagree (minor)

Location: /cli/auth.md

Problem: The page says ardent status checks "your current authentication, project, and connector." The example output shown directly beneath is:

✓ Logged in as vikram@tryardent.com
  Organization: Ardent

No project, no connector, no organization-vs-project explanation. The reader can't tell whether the description is aspirational, whether the example was trimmed, or whether Organization is what the docs mean by "project".

Consequence: Agents and developers writing scripts that parse ardent status output will key off the wrong fields. Users debugging "which connector am I on?" will run status, see neither, and not know whether it's a bug or expected.

The fix: Either expand the example to show all four fields the description promises, or rewrite the description to match what's actually shown. If Organization is distinct from project, clarify the relationship between orgs, projects, and connectors on /cli/overview or /architecture.

13. Role enum is documented only on set-role, but invite accepts it positionally (minor)

Location: /cli/org.md

Problem: ardent invite alice@company.com admin is shown as a valid command form, with no enumeration of which roles are valid in the invite context. The valid roles — owner, admin, member, viewer — only appear several sections later under ardent org set-role. A reader scanning top-to-bottom sees the invite example first and has no way to know admin is one of four choices, or whether you can invite someone directly as owner.

Consequence: Users guess role names that don't exist (e.g., developer, read-only) and get a CLI error. Agents writing invite scripts will hardcode whatever role appears in the example and not realize alternatives exist.

The fix: Enumerate the valid roles next to the first ardent invite example, or factor the role list into a shared "Roles" subsection that both invite and set-role reference.

14. PlanetScale Postgres provenance is unexplained (minor)

Location: /connectors/planetscale.md

Problem: The page is titled "PlanetScale" and instructs the user to "Go to Connect > Connect with: Postgres in your PlanetScale dashboard." PlanetScale was a MySQL-only product for its entire public history; Postgres support is recent and not available on all PlanetScale plans or accounts. The page never disambiguates which PlanetScale offering it supports, never states a minimum version, and never links out to PlanetScale's own Postgres documentation.

Consequence: A user on legacy PlanetScale MySQL clicks this page expecting it to work, follows the dashboard path "Settings > Integrations > Logical Replication" that doesn't exist for them, and has no way to tell whether the problem is on Ardent's side, on their side, or that they're on the wrong PlanetScale tier entirely.

The fix: Open the page with one sentence: "Ardent supports PlanetScale's Postgres offering (in public beta as of [date]). MySQL clusters are not supported." Link to PlanetScale's own Postgres docs so users can confirm their account has it enabled.

15. Branch-anonymization is documented twice in compatible-but-not-identical wording (minor)

Location: /security.md ("Branch anonymization") and /cli/settings.md ("Branch configuration and anonymization")

Problem: Both pages introduce branch_sql, describe the same @./scripts/anonymize-branch.sql pattern, and cross-link to each other. Neither is the canonical reference. The phrasings differ subtly — Settings says "Anonymization or redaction so branches get realistic shape without real PII"; Security frames it as "When you need realistic schema and relationships but not real PII." Not a contradiction, but two near-duplicates.

Consequence: Behavior changes (timeouts, error handling on partial failure, what counts as idempotency) have two places to update; agents indexing the docs may surface either page depending on the query.

The fix: Pick /cli/settings as the canonical reference for mechanism and reduce the Security section to a 2–3 sentence summary plus a link. (Or vice versa — but commit to one canonical page.)

What they do well

• The "Have Claude set this up" prompts on connector and workflow pages are a thoughtful, agent-native pattern — they anticipate that an LLM is the primary reader and hand it a concrete checklist. (Whether they should include the connection string is a separate matter — see finding #2.)
• The architecture page is unusually concrete for a young company: it names the components (Replicator, Kafka, read replica, copy-on-write branches), explains DDL replay via event triggers, and draws a clean control-plane / data-plane boundary.
• Connector pages are appropriately specific per provider (RDS parameter groups, PlanetScale dashboard path, self-hosted wal_level) rather than one generic Postgres page.

Top 3 recommendations

1. Resolve the FAQ-vs-onboarding credential contradiction. Either stop asking users to paste production connection strings into Claude on the connector pages, or rewrite the FAQ so its security promise scopes only to post-connector branch URLs. This is the single most damaging consistency problem in the docs.
2. Publish /byoc, an API reference + token-auth page, and a changelog. These three pages together close the largest documentation gaps for paying customers, integrators, and anyone debugging a version-specific issue.
3. Add a troubleshooting/error reference and a real support address. Replace the single personal-email contact card with an org address and a documented Slack invite path for Scale-tier customers; key the troubleshooting page off the actual error messages the replicator and connector setup emit.