docs(tool-executions): recording and retention are self-service [PLT-2978]

[josebarrueta]

Stacked onto #1129 so nothing on that branch is rewritten — merge this into it and the page is current.

Why

The Retention section describes the world before PLT-2978. It says:

To change the retention window, or to turn off execution logging and delete the history for your organization, contact Arcade support.

That capability is being shipped as self-service in a stack now in review (monorepo #3165 the API, #3243 the dashboard page). The stale instruction is the obvious problem, but three smaller ones matter more, because each would mislead a reader who acts on it.

It offered project-level overrides — "7 days unless your organization sets a different default or a project overrides it". Project-level settings are an explicit non-goal of the spec. Nothing customer-reachable sets a project's own window, and the API reports retention_changeable_at_project: false for exactly this reason. A reader would go looking for a control that does not exist.

It folded two different actions together — "turn off execution logging and delete the history". They are not the same operation and behave differently. Turning recording off stops new runs being written down and leaves what is stored to expire on the window; the retention sweep marks on the window alone and never reads whether recording is on. Shortening the window is the control that deletes, and it reaches records already held. Someone who turns recording off expecting an erasure gets neither the deletion nor a warning.

It gave no bounds, so nothing told a reader that 0 and 400 are refused with a 422 rather than clamped.

What changed

One file, app/en/operate/governance/tool-executions/page.mdx. The section is now Recording and retention and covers:

• the two settings, both organization-wide, and that an organization admin sets them
• how to change them — the dashboard page and PUT /v1/orgs/{org_id}/logging-config
• the bounds, and that out-of-range is a 422
• what each setting does to history you already have — the distinction above, stated plainly, including that shortening the window cannot be undone
• what a reader sees when the list is empty, since an empty history has several causes and the product now says which applies

The intro also picks up a pointer, since "Arcade records every tool run" is only true while recording is on.

Checked

bun run build passes. It caught a real mistake first: I used <Note>, which this site does not have — the convention is <Callout> (282 uses) and it needs an explicit import { Callout } from "nextra/components". Prerendering failed until both were right.

Every claim is checked against the implementation rather than the spec prose:

Claim	Source
Default 7 days, max 90	ORG_DEFAULT_LOG_RETENTION_DAYS, MAX_LOG_RETENTION_DAYS in core/conf.py
Out-of-range is 422	within_platform_maximum on the FastAPI-validated body
Recording off does not delete	runMarkPhase reads LogRetentionDays only, never LoggingEnabled
Shortening deletes retroactively	the mark phase re-evaluates all unmarked rows against the current window
Org-admin authority	logging_config_update, org-admin only, plus can_edit_logging on the org read

Sequencing

This documents behaviour that is not merged yet. #3165 and #3243 are green and awaiting review, not released. If #1129 is likely to ship first, hold this one until the stack lands — otherwise the page promises a dashboard page that isn't there. Happy to gate it however you prefer.

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only change with no runtime or API behavior modified in this PR.

Overview
Updates the Tool Executions governance doc so it matches org-wide, self-service execution logging instead of “contact support” and misleading retention behavior.

The intro now states that recording is on by default and points to the new Recording and retention section. That section replaces the old Retention block: it describes two org-admin settings (recording on/off and retention days), Cloud defaults (7-day window, 90-day max) vs self-hosted, and how to change them via the dashboard Execution Logging page or PUT /v1/orgs/{org_id}/logging-config. It documents validation (422 for out-of-range values, minimum 1 day, zero is not valid) and clarifies that turning recording off only stops new writes while existing rows expire on the window, whereas shortening the window retroactively deletes older history org-wide and cannot be undone. Project-level retention overrides are no longer implied.

^{Reviewed by Cursor Bugbot for commit df4f755. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 25, 2026 6:52pm

[josebarrueta]

All eight applied — pushed as 10d24ff3. Net +4 / −20, so the review took considerably more out than it put in, which was the right direction.

Your three wordings are in as written, bar one liberty: I added the article in "configured by an organization admin". Say the word if you meant it without.

The four cuts, and what each was doing:

• Org-admin authority line — your opening sentence already says it.
• "These come apart, and the difference matters" and "If you want existing history gone…" — both announced or restated the two bullets between them.
• The permits-not-compels callout — you're right that project-level settings don't exist, and the callout half-conceded it ("the two are indistinguishable"). A distinction with no observable effect is only something to trip over. Its import { Callout } went too, since that was the last use in the file.
• "When the history is empty" — narrating UI copy means two places to keep in step, and the UI wins that race.

One thing worth leaving on the record from that last cut: an empty list has several causes — nothing ran, recording is off, the window already expired — and telling them apart is the outcome this feature is measured on. That job now sits entirely with the dashboard, which is the better home for it, but it is a real requirement rather than a nicety.

bun run build passes.