Projects, artifacts, and checkpoints

AgentKit works inside real projects, where generated content and your existing work can live side by side. Its safety model depends on distinguishing recorded installation files from files it does not own.

Projects are locations, not ownership claims

The AgentKit project registry tracks directories bootstrapped with ak new or ak init; you can also add or remove registry entries explicitly. The registry helps the CLI find projects. Registering a directory does not transfer ownership of its contents to AgentKit.

Project-scoped Kit installation is a separate idea. It writes supported runtime content for the current workspace and records lifecycle metadata for that installation. User-scoped installation writes to the selected runtime's user locations instead. See Runtime adapters for the scope and delivery combinations.

Configure where docs and plans live

When adopting an existing project, ak init --docs-dir <path> --plans-dir <path> persists either or both values to .agentkit/config.yaml as paths.docs and paths.plans. This lets AgentKit avoid a project's pre-existing docs/ or plans/ layout without making those directories installation-owned.

A relative value must stay inside the project and cannot target the AgentKit-owned .agentkit tree. A safe relative paths.plans value is shared by Engineer Skills, ak plan, journals, reindex and migration operations, and the Desktop/dashboard plan readers. Missing, malformed, outside-project, or linked plan locations degrade to the default plans/ for those Go-native surfaces.

Absolute values are allowed for consolidated artifact storage. Engineer's session-start Hook exports an absolute paths.docs or paths.plans value verbatim in CK_DOCS_PATH or CK_PLANS_PATH; a relative value resolves under the session's project base. The config and Skills honor absolute values, but ak plan, journals, and Desktop/dashboard deliberately fall back to project plans/ instead of reading an absolute plan directory.

What AgentKit records

For an installed Kit, AgentKit records the paths and content fingerprints of the files it emitted. Later lifecycle operations use that record to classify files:

This boundary also applies to shared runtime settings. AgentKit removes or updates registrations it can identify as its own and preserves foreign settings. If the CLI cannot prove ownership, preservation is the expected result.

Artifacts belong to the workflow and project

A workflow may produce code, plans, reports, images, or other files. These are artifacts, not automatically AgentKit-managed installation files. Review them with the tools appropriate to the project—often your editor, tests, and version-control diff.

Treat model output as a proposal until you have checked it. In particular, review before you:

• Commit or merge code;
• Publish content or contact another person;
• Send sensitive data to an external service;
• Approve a destructive action or one that can incur cost.

AgentKit installation metadata cannot decide whether an artifact is correct, safe, or ready to publish.

Checkpoints and recovery snapshots

A checkpoint is a moment to inspect state before continuing. For project work, that can mean an approved plan, passing focused tests, or a reviewed diff. For AgentKit lifecycle operations, the CLI also creates rollback snapshots before supported mutations such as forced overwrite, install-mode transition, or uninstall.

Snapshots are stored in AgentKit's backup area and carry a manifest of captured paths. They are scoped recovery records, not full backups of your repository or runtime home. Skipping them with --no-backup removes that recovery path and is intended only for users who accept the risk.

Before restoring, inspect the snapshot and preview the restore plan:

ak backups list
ak backups show <id>
ak backups verify <id>
ak backups restore <id> --dry-run

A restore is replace-only: it can overwrite captured paths and may remove paths explicitly listed in its confirmed plan, while unrelated files created later normally remain. A multi-file restore is not transactional; a host failure can leave an intermediate state. Review the plan before applying it and take a new snapshot first when practical.

Restoring a project bundle requires one exact --allow-root value for every persisted root shown by ak backups show <id>. Some project-local snapshots instead require the manual recovery instructions printed by the operation; keep the reported backup ID and path.

A safe review loop

The mutation path keeps ownership classification and scoped recovery evidence between preview and write. Recovery remains limited to the affected paths; it is not a checkpoint object or a full-machine rollback.

flowchart LR
  accTitle: Ownership-aware mutation and recovery
  accDescr: Preview the plan, classify file ownership, record a scoped snapshot or journal, apply the confirmed mutation, then audit or recover only the affected files.
  preview["Preview the plan"] --> ownership["Classify ownership"]
  ownership --> record["Snapshot or journal"]
  record --> mutate["Apply confirmed mutation"]
  mutate --> audit["Audit or scoped recovery"]

1. Read the operation preview and adapter warnings.
2. Preserve unrelated work with version control or your own backup.
3. Let AgentKit create its snapshot; do not use --force as routine recovery.
4. Run the workflow and inspect the artifacts it creates.
5. Test the changed behavior and review the diff.
6. Only then commit, publish, or approve external actions.

Never recover by deleting an entire runtime home or project configuration directory. Start with the operation report, ownership status, and snapshot manifest so recovery stays limited to the affected files.

For exact backup and lifecycle commands, use the CLI reference.