docs(v3): document App Actions V3 version history

[veljko7]

@

Summary

Documents the version-history feature added to V3 App Actions in fliplet-api (DEV-1259 / PR #8070): config snapshots on create/update/restore, the 100-version retention cap, and the three REST endpoints to list, fetch, and restore versions.

Changes

• New Version history section covering snapshot-on-write behaviour (create/update/pre-restore reasons), retention/pruning, cascade delete, and what a snapshot captures
• Documented GET /versions (paginated summary), GET /versions/:id (full snapshot), and POST /versions/:id/restore (undo-able restore, refuses production) with Fliplet.API.request() examples and response shapes
• Added concept point on versioning to Data models and key concepts
• Error tables: VERSION_NOT_FOUND, CANNOT_RESTORE_PRODUCTION, RESTORE_FAILED (plus the 409 name-collision case on restore)
• Rate limits: version reads under CRUD bucket, restore under publish
• Frontmatter capabilities: version history, restore version, rollback

🤖 Generated with Claude Code
@

[cloudflare-workers-and-pages]

Deploying fliplet-cli with    Cloudflare Pages

Latest commit:	25dca0e
Status:	✅  Deploy successful!
Preview URL:	https://c4b65dac.fliplet-cli.pages.dev
Branch Preview URL:	https://release-dev-1314.fliplet-cli.pages.dev

View logs

[Arpanexe]

LGTM

[Komsomol]

Approve. Docs-only PR. I verified every material claim against the fliplet-api implementation (DEV-1259 / routes/v3/app-actions.js, models/task.js) — the documented contract faithfully matches the shipped API: the 3 routes + middleware, all status strings, the { limit, offset, total, hasMore } pagination, the 100-version cap with oldest-pruned best-effort snapshotting, pre-restore undo, RESTORABLE_FIELDS excluding masterTaskId/productionTaskId, the 403/409 cases, and the appAction.v3.restore audit linkage. Unusually well-aligned docs.

Three non-blocking notes:

1. (please fix) assets is missing from "What a snapshot contains". The prose enumerates 14 fields but TASK_VERSION_FIELDS (models/task.js) has 15 — it includes assets, which is shown in the "Get a single version" example response, so the omission is internally inconsistent. Suggest: …code, actionVersion, dependencies, assets, plus the internal functions…

2. (optional) "heavy fields … are omitted" undersells the summary. formatVersionSummary returns only id, createdAt, userId, user, action, name, description, active, environment, frequency — it also drops timezone, triggers, functions, widgetInstanceIds, masterTaskId, productionTaskId, actionVersion, not just code/dependencies/assets. Wording isn't wrong, just reads narrower than reality.

3. (quick confirm) cascade delete. "Deleting an action cascades to its version history" is plausible (versions key on taskId) but is the one claim I couldn't directly evidence — worth confirming the FK is ON DELETE CASCADE or there's an explicit destroy.

Cosmetic: stray leading/trailing @ around the Summary in the PR body.

[Komsomol]

Approved. Verified every technical claim against fliplet-api@master (DEV-1259 / PR #8070): 100-version cap, snapshot field list (TASK_VERSION_FIELDS), restore field exclusions (masterTaskId/productionTaskId), pre-restore undo snapshot, cron re-apply, 409 name-collision, 403 CANNOT_RESTORE_PRODUCTION, appAction.v3.restore audit log, cascade delete (migration 182 FK onDelete: CASCADE), and rate-limit buckets (reads=CRUD 60/60s, restore=publish 10/60s) all match the implementation.

Nit (non-blocking): strip the stray @ characters at the start/end of the PR description before merge.