akm-cli/docs/architecture/internals/fresh-host-rebuild-runbook.md

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

# Fresh-Host Rebuild Runbook

Rebuild a working akm install on a new machine. Assumes your bundle lives in a
git remote and that a versioned `config.json` copy is committed to the bundle
git (the 08-F1 recovery pattern — see step 3).

1. **Install the CLI.** Prebuilt binary (no runtime needed):
   `curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash`
   — or npm package (Node.js >= 22 required): `npm install -g akm-cli`.
   If a working Bun >= 1.0 is also on `PATH`, the package prefers it after Node
   bootstrap; old, unusable, or absent Bun installations fall back to Node.js.
   The standalone binary is runtime-free.
   (Windows: `irm https://github.com/itlackey/akm/releases/latest/download/install.ps1 | iex`.)
2. **Confirm the binary resolves:** `akm --version`.
3. **Restore `config.json`.** akm reads a single user config at
   `~/.config/akm/config.json` (`%APPDATA%\akm\config.json` on Windows;
   override with `AKM_CONFIG_DIR`). This file is gitignored on the host, so the
   recovery source is the ONE versioned copy committed to the bundle git
   (08-F1 pattern). Copy that file into place; it carries named `engines`,
   `defaults.engine` / `defaults.llmEngine`, and cron-load-bearing improve
   strategies that are otherwise unrecoverable.
4. **Provide secrets/env.** `config.json` references API keys via `${VAR}`
   placeholders; export those environment variables (or restore your env/secret
   assets) so named engines and the embedding connection resolve. Never commit
   the resolved values.
5. **Restore the working bundle.** Clone your bundle git remote to the path
   named by your working bundle's entry under `bundles` in the restored
   config (`defaultBundle` selects which one; default path `~/akm`). There is
   no top-level `stashDir` config key in 0.9 — it is retired and rejected at
   load. If starting clean instead, run `akm setup --yes` to scaffold it.
6. **Re-add non-git sources.** For each managed source not carried in the bundle
   git (websites, npm packages, GitHub repos), run `akm bundle add <ref>`. Verify the
   full set with `akm bundle list`.
7. **Rebuild the index:** `akm index --full` (forces a complete reindex rather
   than an incremental update).
8. **Verify health:** `akm health` (checks runtime, artifacts, and improve
   metrics — exits non-zero if `state.db` is missing) and `akm info` for index
   stats and effective config.
9. **Smoke-test discovery:** `akm search <term>` returns results, confirming the
   index and bundle are wired correctly.