docs(5db2766d-3107-4a9d-a6a4-9d9950cd4fbe): add comprehensive version history documentation - #775
Conversation
…entation page Creates build/agents/build-your-agent/version-history.mdx covering all three asset types (Agents, Tools, Workforces) with sections on version creation, the draft/active model, restoring from UI or Inventor, naming, the (restored) suffix, and retention policy. Adds version history links to create-an-agent, create-a-tool, create-a-workforce, and expands the Inventor restore tab. Updates docs.json navigation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
🎯 Vibe checkReviewed: 6 files (2 with issues, 4 clean) — 5 Scores
Score key: 🟢 9–10, 🟡 6–8, 🔴 1–5. ✨ Overall vibe: This is a tidy, well-executed PR. The new 🔧 Issues (1)
🧩 Component suggestions (1)
✅ Clean files (4)
🔋 Credit usage
Files read: |
|
Agent, Tool, and Workforce all need amended capitalisation |
|
Instead of just having a "Restore via Inventor" section, please make it feel more integrated into this documentation, as Invent is going to be an extremely common way of working moving forward. |
|
Do you really need a big heading for "The “(restored)” suffix"? |
|
"Things to know" should really just be notes / disclaimers / callouts in plain-text. If you mean to insert a Frequently asked questions (FAQs) section then make sure that is exactly the title |
jordanc-relevanceai
added
the
drafter:go
… on version history page - Capitalize Agent, Tool, Workforce consistently as product names throughout version-history.mdx - Rework Invent integration: promote Inventor to a first-class restore path alongside the UI, weave it into the main narrative rather than an isolated subsection - Fold the (restored) suffix note into the Version naming and descriptions section instead of a standalone heading - Rename Things to know → Frequently asked questions (FAQs) per content standards - Fix invent.mdx line 24: capitalize Agents, Tools, Workforces in card description - Add href anchors to create-a-tool.mdx CardGroup cards (matching create-an-agent.mdx pattern) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Addressed all reviewer feedback from @jordanc-relevanceai: Capitalization — Invent as first-class restore path — Removed the isolated "Restore via Inventor" subsection. The "Restoring a version" section now opens with a sentence establishing both the UI and Inventor as equal paths, then presents "From the UI" and "With Inventor" as parallel
"Things to know" → "Frequently asked questions (FAQs)" — Section renamed exactly as specified. The three accordion items are genuinely FAQ-shaped (limitation questions with explanations), so the FAQ title is the right fit.
|
claude
Bot
removed
the
drafter:go
🎯 Vibe checkReviewed: 6 files (1 with issues, 5 clean) Scores
Score key: 🟢 9–10, 🟡 6–8, 🔴 1–5. ✨ Overall vibe: A clean, well-scoped PR — the new version-history page is solid, and the cross-links added to the three create pages are exactly the right way to surface it. The only real issue is a consistent capitalization pattern in 🔧 Issues (7)
✅ Clean files (5)
🔋 Credit usage
Files read: |
|
Make sure the FAQ section actually has questions in the accordion titles |
|
I think for me there are too many big headings. Can we please break this down into less categories? Look at other docs and how they employ this kind of thing |
jordanc-relevanceai
added
the
drafter:go
… on version history page - Convert FAQ accordion titles from statements to questions - Consolidate 7 ## sections down to 4: "How version history works", "Accessing and restoring versions", "Version retention", and "Frequently asked questions" - Move draft/active model and version naming content under the top-level "How version history works" section - Merge restoring-from-UI instructions into the accessing section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Addressed the reviewer feedback: FAQ accordion titles converted to questions:
Heading structure consolidated from 7
|
claude
Bot
removed
the
drafter:go
🎯 Vibe checkReviewed: 6 files (2 with issues, 4 clean) — 5 MDX + 1 Scores
Score key: 🟢 9–10, 🟡 6–8, 🔴 1–5 ✨ Overall vibe: The version history feature is well-documented and cleanly cross-linked from all three create-X pages — that part is solid work. The main drag is 🔧 Issues (11)
🧩 Component suggestions (1)
🏗️ Page structure (1)
|
| Item | Count |
|---|---|
| Files reviewed | 6 |
| Context pages read | 2 |
| Total lines processed | ~650 |
Files read: version-history.mdx (93 lines), create-an-agent.mdx (92 lines), invent.mdx (243 lines), create-a-tool.mdx (103 lines), create-a-workforce.mdx (46 lines), docs.json (excerpt), enterprise/data-retention.mdx (~40 lines), build/agents/build-your-agent/evals.mdx (~30 lines)
Resolve invent.mdx conflict by taking main's restructured page (Inventor renamed to Invent, cards and tabs reorganized) and re-applying the version-history link inside the "Restore a version" accordion. Align terminology in version-history.mdx to match. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…eck failures - Rename FAQ heading to the required exact form "Frequently asked questions (FAQs)" in version-history.mdx - Replace aspectRatio with paddingTop: '56.25%' on the Supademo wrapper in invent.mdx so it matches the standard embed snippet Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…d naming claims Verified against relevance-api-node at latest main. - Renaming a saved version IS supported in the builder UI for all three asset types, via the three-dot menu on a version row. Rewrite the FAQ that claimed it was impossible. - Versions carry a name and a description; the page previously only described descriptions. Unnamed versions display as a timestamp. - The (restored) suffix is appended to the version name, not the description; the description carries over unchanged. - Drop the claim that Invent requires a version description. It is not required on publish, and restore takes only a version_id. - Replace approximate UI navigation with the actual entry points, and note that the Tool builder embedded in the Agent builder omits the version history entry point. - Note the permission asymmetry on renaming Agent versions. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ess steps The access path is identical for Agents, Tools, and Workforces — all three render PdDropdownMenu variant="icon" (lucide:ellipsis) containing a "Versions" action, so the per-asset tabs described a distinction that doesn't exist. Replace them with one set of steps. Add the real shared caveat: the Versions entry only appears on the build view, and the Tool builder embedded in the Agent builder omits it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… steps The numbered "From the UI" steps restated the three-dot pattern already established by the access steps directly above. Fold the one detail worth keeping — the "Restore this version" menu item — into the surrounding prose, and trim the duplicated draft explanation from the Invent section. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… screenshot Add images/version-history-panel.png to the access section, kept generic rather than described as workforce-specific. Correct the accompanying sentence to match what a row actually renders: ListItem.vue shows name-or-timestamp (not both), the author, a Live marker on the active version, and an Invent/MCP pill for versions created by those surfaces. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…er the intro Place the screenshot directly after the opening paragraph as a visual anchor, matching the pattern on invent.mdx. The sentence describing the row fields stays in the access section, where it explains the panel the reader has just opened. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… behavior
Version pruning is opt-in, not automatic. The page framed deletion as
default behavior with active/draft as the only two exceptions, but the
sweep is gated three times over:
- deletion_command_lister.ts only sweeps orgs that have a data retention
config at all
- listers/commands.ts checks a per-asset-type setting and skips when unset
(delete_agent_versions / delete_tool_versions /
delete_workforce_versions), and the three are independent
- migration 20251019232514 creates all three columns as
DEFAULT false NOT NULL, confirmed by the column comments added in
20260512000014 ("Defaults to false")
So versions are kept indefinitely unless an admin configures retention and
enables pruning for that asset type. Also note eligibility is measured
from created_at, so relabelling an old version does not reset its age.
The active/draft protection itself was accurate and is retained.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… per-type claim Two corrections after checking the actual settings UI: - Drop "pruning". No user-facing surface uses that word; it came from a DB column comment. The customer UI and enterprise/data-retention.mdx both say "deleted". Use "retention window" to match the input label. - Drop the claim that Agent, Tool, and Workforce version deletion are switched on independently. DataRetentionConfig.vue exposes a single toggle that maps every settings key to the same value, so a customer cannot set them apart. The per-type booleans exist in the API and DB only, and the control-panel view of them is read-only. Also state that retention is an Enterprise feature that must be enabled, and that no version-specific setting exists. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…yes/no Both "Why..." questions presupposed the answer instead of asking it. Reframe as questions a reader would actually type, and lead each answer with a direct No so the verdict is readable before the explanation. - "Why is there no version history for assets I haven't edited recently?" becomes "Does every Agent, Tool, and Workforce have version history?" - "Why doesn't restoring a version publish it automatically?" becomes "Does restoring a version publish it automatically?" Matches the existing "Can I rename a version after it's been saved?" / "Yes." pattern, so all three now read consistently. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…availability FAQ It told readers that an asset with no saved changes has no saved versions, which they can work out themselves. The underlying point — history only exists from when the feature shipped, and the migrations that created the version tables do not backfill existing assets — is technically true but of shrinking relevance: those tables landed 2025-05-31 (tools) and 2025-06-09 (agents). Not worth an FAQ slot. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…tention section Drop the enablement mechanics — Enterprise gating, who flips the switch, and the fact that one toggle covers logs and versions together. Those describe internal configuration a reader cannot see or act on, and the retention path also depends on a per-org fga_enabled config value that is invisible to customers, so any promise about what enabling retention does is unsafe to document here. Keep the two facts a builder needs: nothing is deleted by default, and the active and draft versions are protected at any age. Configuration details stay on the canonical Data retention page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…wkward phrasing - Retention bullet no longer uses "neither ... nor". A sentence about not losing work should not need parsing twice. - "on the build view" becomes "in the builder", and the Note is split into two sentences so the three exceptions are readable. Jargon and the active/live/published overlap left as they are. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
🎯 Vibe checkReviewed: 5 MDX files + docs.json navigation update + 1 image asset (3 files with issues, 2 clean) Scores
Score key: 🟢 9–10, 🟡 6–8, 🔴 1–5. ✨ Overall vibe: The version-history.mdx page is the standout — tight, well-organized, and complete without over-explaining. The "Inventor" misnaming and the lowercase product-term drift in the tool-editing section are the main things to fix; everything else is polish. The docs.json and image changes look clean and are correctly scoped. 🔧 Issues (7)
|
| Item | Count |
|---|---|
| Files reviewed | 5 MDX + docs.json |
| Context pages read | 2 (triggers.mdx, enterprise/data-retention.mdx) |
| Total lines processed | ~560 |
Files read: build/agents/build-your-agent/version-history.mdx (89 lines), build/agents/create-an-agent.mdx (92 lines), build/invent/invent.mdx (360 lines), build/tools/create-a-tool.mdx (103 lines), build/workforces/create-a-workforce.mdx (46 lines), build/agents/build-your-agent/triggers.mdx (50 lines, context), enterprise/data-retention.mdx (160 lines, context)
2 participants
Summary
build/agents/build-your-agent/version-history.mdx— a new page covering version history for Agents, Tools, and Workforces with sections on when versions are created, the draft/active model, accessing the UI per asset type, restoring via UI and Inventor, the(restored)suffix, and the retention policycreate-an-agent.mdx,create-a-tool.mdx, andcreate-a-workforce.mdxinvent.mdxwith a link to the full guidedocs.jsonto add the new page under Build an Agent in the navigationFixes: https://linear.app/relevance/issue/5db2766d-3107-4a9d-a6a4-9d9950cd4fbe/
Test plan
/build/agents/build-your-agent/version-history