kandev/docs/plans/managed-runtime-recovery/task-06-document-runtime-version-recovery.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
06-document-runtime-version-recovery	Document runtime version recovery	done	5	04-add-responsive-version-recovery-ui	plan.md	../../specs/agents/requirements/runtime-updates.md

Task 06: Document runtime version recovery

Acceptance

• Public agent/profile guidance explains selecting update, rollback, and repair targets and that activation follows a successful ACP validation.
• The guide states that the active exact version survives Kandev restarts, affects only later host-local probes/utility calls/sessions, and does not change active or remote/container sessions.
• Troubleshooting covers incomplete latest releases, failed candidates, authentication-required validation, and retrying another stable version.
• The guide does not recommend global npm cache cleanup or imply Kandev owns an offline artifact inventory.

Implementation

1. Replace the current latest-only update steps in the existing how-to section.
2. Add a concise troubleshooting entry for selecting the previous stable version when latest cannot initialize.
3. Check all labels and guarantees against the implemented API/UI and spec.
4. Run documentation link and formatting checks available in the repository.

Files likely touched

• docs/public/agents-and-profiles.md

Verification

rtk rg -n "Update a managed agent runtime|Roll back runtime|Repair runtime|npm cache" docs/public/agents-and-profiles.md
rtk rg -n "docs/public|markdown" Makefile apps/package.json package.json

Run the repository documentation check discovered by the second command and record the exact command/result.

Risks

• Describe host scope and persistence precisely; do not promise remote updates or cached offline reinstall.
• Keep this as an operator how-to, not an implementation narrative.

Output contract

Record changed sections, checks, and risks in Results. Update this task and plan.md status.

Results

Updated docs/public/agents-and-profiles.md with exact-version selection, update/rollback/repair behavior, ACP validation, restart and host-local scope, active-session and remote/container boundaries, failed-candidate preservation, and retry guidance. GREEN verification:

• rtk node --test scripts/validate-public-docs.test.mjs — 60 tests passed.
• rtk node scripts/validate-public-docs.mjs — 41 published docs pages validated.

The guide does not promise global npm cache cleanup or an offline artifact inventory.