Repository navigation
Conversation
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.
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.
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.
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.
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.
This reverts commit e7e4539.
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.
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.
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.
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.
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.
…er-specific 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.
Greptile SummaryThis PR improves setup documentation and adds a distributable Ardent CLI skill.
Confidence Score: 4/5This should be fixed before merging.
skills/ardent-cli/SKILL.md, skills/ardent-cli-skill.txt
|
| Filename | Overview |
|---|---|
| skills/ardent-cli/SKILL.md | Adds the npx-discoverable skill and stops remote content from overwriting the local file, but keeps remote content active for the current run. |
| skills/ardent-cli-skill.txt | Updates the canonical skill with valid YAML and the same current-run remote instruction behavior. |
| .github/workflows/skill-sync.yml | Adds a CI check that keeps the canonical skill and discovered skill copy identical. |
| quickstart.mdx | Adds explicit step links, writable-primary guidance, and agent handoff instructions. |
| branches.mdx | Adds branch lifecycle, isolation, and frozen-at-creation documentation. |
Reviews (2): Last reviewed commit: "docs: skill self-sync follows fetched co..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
/codesmith fix it |
|
On it, I'm reviewing the PR feedback and fixes now. |
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 <codesmith-bot@users.noreply.github.com>
Fixed and pushed to this PR ( What I changed: the skill's self-sync used to tell installed agents to Why not Greptile's SHA-256 sidecar: the suggested Residual risk: following any remote content over HTTPS from our own domain is inherent to the fetch-first model (the skill also fetches |
| - 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. |
There was a problem hiding this comment.
There was a problem hiding this comment.
Same mutable-remote-authority concern already adjudicated in this thread (comment 3598295904), where the suggestion was withdrawn and the mutable-fetch behavior agreed acceptable for this PR. The fetch-first self-update is the skill's deliberate, documented design (HTTPS, with a SKIP_ARDENT_SKILL_SYNC=1 pin opt-out); a signed/pinned integrity mechanism needs backend infrastructure and owner approval and is tracked as separate work, out of scope for this docs PR.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 310b151. Configure here.
| - 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. |
There was a problem hiding this comment.
Remote follow defeats save guard
Medium Severity
The new sync rules tell the agent to treat the curled remote skill as authoritative instead of this file, while also claiming a tampered response cannot persist because nothing is written to disk. Those conflict: if the remote copy says to overwrite SKILL.md, following it overrides the local do-not-save rule, so a bad fetch can still persist. The same full replacement also re-enters # Stay in sync and can loop the curl.
Additional Locations (2)
Reviewed by Cursor Bugbot for commit 310b151. Configure here.
There was a problem hiding this comment.
False positive against current HEAD: the bug's premise (text claims "nothing is written to disk" while also saving over SKILL.md) doesn't exist at commit 1487504, where all three synced copies plainly instruct saving the fetched copy over SKILL.md; cursor reviewed the stale commit 310b151. The residual persistence point duplicates the mutable-remote-authority concern already adjudicated and withdrawn earlier in this thread, with the signed/pinned integrity story tracked as separate backend work out of scope for this docs PR.
This branch has not been deployed
2 participants
Addresses the customer docs feedback batch (Hanover), plus follow-up restructures.
Feedback items
<Step>on the Quickstart and connector pages now carries an explicitid, so setup steps are deep-linkable (Mintlify rendersid=\"\"without one). The Quickstart's provider tabs now use them: each blocker sentence links straight to the connector step that fixes it. Renamed "What's next" → "Next steps" so the anchor survives smart typography as plain ASCII.ArdentAILabs/ardent-branch-actionrepo for testing and is deliberately not referenced in the docs yet./branchesConcepts page leading with the frozen-at-creation answer (no WAL/DDL after creation; fresh data = new branch), plus contents, lifecycle, isolation, and copy-on-write storage. One-sentence version added to the landing page's How-it-works; FAQ links to the page.skills/ardent-cli/SKILL.mdsonpx skills add ArdentAILabs/docs --skill ardent-cliworks after this merges. The served.txtstays canonical; a CI check (skill-sync.yml) keeps the two byte-identical. Also fixes the skill frontmatter: the description contained an unquoted:(invalid YAML) that strict parsers — including the skills CLI — rejected; folded scalar yields the same string.Restructures
#install-the-ardent-cli-skill; inbound links repointed.Testing
mint dev(200s, anchors present in rendered HTML, all four quickstart deep-link targets resolve).npx skills add <local repo> --skill ardent-clitested end-to-end: discovery, install, installed file byte-identical to canonical; frontmatter also validated with PyYAML./quickstart,/connectors/self-hosted) unaffected;docs.tryardent.com/cli/branches.mdraw-markdown contract re-verified live.Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.Note
Low Risk
Documentation and skill packaging only; no runtime product code. Skill sync change is a security-minded doc update for agents.
Overview
This PR expands Ardent docs for customer feedback: linkable setup steps, a dedicated branch behavior concept page, and
npx skillsinstall for the ardent-cli skill.Branch behavior — New
/branchespage explains branches are frozen at creation (no ongoing replication from production; changes don’t flow back). It covers contents, lifecycle, isolation, and copy-on-write storage. The landing page and FAQ now point there instead of repeating the full story.Quickstart & connectors — Every
<Step>gets an explicitidfor deep links. Quickstart clarifies the connection string must be the source writable primary; provider tabs link to the matching connector fix steps. Section title What's next → Next steps for stable anchors.AI agents / skill —
skills/ardent-cli/SKILL.mdmirrors canonicalardent-cli-skill.txtfornpx skills add ArdentAILabs/docs --skill ardent-cli. CI (skill-sync.yml) fails if they diverge. Skill frontmatter uses valid YAML (description: >-); self-sync instructions no longer persist fetched skill to disk (read-only per run). Install docs move to the top of the AI agents page; index and quickstart add npx + manual install accordions.Connector pages — Slimmer skill accordions (link to install) plus unchanged full “without the skill” prompts; inbound links use
#install-the-ardent-cli-skill.Reviewed by Cursor Bugbot for commit 310b151. Bugbot is set up for automated code reviews on this repo. Configure here.