Update, uninstall, and project state

This page covers deploying Kiyo to the projects and machines where you use a coding agent. Kiyo-based work produces ordinary code in your repository, so there is no separate “Kiyo application” to deploy.

What each lifecycle action touches

Action	Changes	Never changes
Install / load	The host’s plugin store or session	Your repository, .kiyo/, instruction files
Select a Skill	Nothing by itself	Anything; selection grants no write authority
Init (initialize)	Only authorized .kiyo/ files and an optional managed block	Source, tests, dependencies, global settings
Update the plugin	Generated, immutable package content	.kiyo/policy.md, Memory, reports, the managed block
Uninstall	The host’s installed entry and cache	.kiyo/policy.md, Memory, reports, the managed block

Project state is user-owned. There is no Kiyo cleanup hook, and updating or uninstalling the plugin is never authority to remove your policy or Memory.

Updating

From the framework’s maintainer guide:

1. Identify the actual installed source, version or digest, and scope. The product version is currently UNSET, and a host-reported version such as Codex’s 1.0.0 is a fallback, not a release.
2. Review the upstream changes (metadata, references, policy effects) before adopting them. The Security Skill’s skills submode can assess an update (AST07 Update Drift).
3. Use the host’s documented update mechanism. Catalog refresh, installed-payload update, and new-session activation are three different steps.
4. Keep project Memory, policy, and human instructions as they are.
5. If a managed block needs to change, update it only in an authorized scope, after rereading the current text. Avoid duplicate blocks, and never copy the Core into instructions.

Cross-host update behavior is NOT_TESTED; a real update test needs two reviewed candidates.

Host	Update route
Claude Code	claude plugin update kiyo-axiom-framework@<catalog> (catalog refresh is separate)
Codex CLI	No generic plugin update flag is inferred; codex plugin marketplace upgrade <catalog> refreshes only the catalog snapshot
Copilot CLI	copilot plugin update <installed-name>; copilot plugin marketplace update <registered-name> for the catalog
Copilot VS Code	Extensions: Check for Extension Updates

Uninstalling

1. Remove the exact plugin through its real install route (see Host commands). For Claude, pass --scope explicitly, because the documented default is user scope.
2. A session-only Claude load (--plugin-dir) ends when you stop passing the flag.
3. Do not delete guessed cache directories, whole instruction files, or .kiyo/ content.

The only fully observed uninstall is Codex CLI 0.158.0 (disposable catalog). Three synthetic project files stayed byte-identical.

Removing the managed block (optional)

If you also want the project to stop pointing at Kiyo, make a separate, explicit request. Select Implement or Init, and name the file:

Remove only the Kiyo managed block (KIYO:BEGIN/END project-context) from CLAUDE.md; keep every other line and keep the file.

The agent rereads the file and reconciles any human edits inside the block. It removes only that marked range and keeps the containing file, even if the file ends up empty. .kiyo/ Memory and policy stay unless you separately ask to delete them.

Migration

Migration is an explicit, scoped proposal, made only when a real format, path, or version change requires it. The existing canonical Memory location and decision history are preserved. Kiyo never initializes a second store or regenerates all records. Missing or outdated Core is reported before any dependent Kiyo action.

Rolling out to a team

• Pick one install route per host and document it for your team, noting that the catalog route is NOT_TESTED today.
• Commit .kiyo/ so Memory and policy are reviewed like code.
• Decide whether to add the managed block, and review its diff.
• Record which governance preset, if any, the project adopts, with acceptance evidence.