git:20260825.169b526 to git:20260904.482f8e6

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repo is

Kasetto is a declarative AI agent environment manager: a Rust CLI that syncs four asset kinds -

**skills**, **slash-commands**, **MCP servers**, and **instructions** (`CLAUDE.md` / `AGENTS.md` /

`.cursor/rules` / ...) - from git repos or local dirs into 23 agent environments, driven by a

`kasetto.yaml` config and pinned by a `kasetto.lock`. Modeled on cargo/uv ergonomics.

Two things live here:

- **`/` (Rust crate `kasetto`)** - the CLI. Two binaries from one lib: `kasetto` (default-run) and

`kst` (`src/bin/kst.rs`); both call `kasetto::run`.

- **`site/`** - Next.js 15 App Router app serving both the marketing landing and the Fumadocs docs

## Commands

```bash

just check # format + lint + test + build, both targets - the pre-PR gate

just lint-rs # cargo clippy --all-targets -- -D warnings

just test-rs # cargo test (skipped if a .no-tests sentinel file exists)

just build-rs # cargo build --release

just lint-next # cd site && pnpm lint (biome, --write)

just build-next # cd site && pnpm build

just dev-next # local Next.js dev server

just audit # cargo-audit + pnpm audit (installs cargo-audit if missing)

just sync-config # regenerate README/docs/hero from kasetto.example.yaml

cargo test <name> # single test by substring

cargo test --lib model::agent::tests # one module's tests

cargo run -- sync --dry-run # exercise the CLI locally

```

`just test-next` is a deliberate no-op (`echo "no Next.js tests"`); the site has no test suite.

**`kasetto.example.yaml` is the single source of truth for the example config.** It is copied into

`README.md` (between `<!-- kasetto-config:start/end -->`), the docs, and the homepage hero by

## Rust architecture

`src/lib.rs` owns default-config resolution and re-exports `run` + `Result`. `src/app.rs` parses

clap args and dispatches; with no subcommand it prints the banner + `--help` and exits 0 (cargo/uv

style). Errors are a boxed `Box<dyn Error + Send + Sync>` (`error.rs`), no error enum.

### Module map

| Module | Responsibility |

| --- | --- |

| `cli.rs` | clap `Cli`/`Commands` plus the flattened `OutputArgs` / `ScopeArgs` / `SyncArgs` groups |

| `commands/` | one module per subcommand; `sync/` splits into `skills` / `mcps` / `commands` / `instructions` |

| `model/` | `Agent` enum + install-path registry (`agent.rs`), config schema (`config.rs`), lock/report types (`types.rs`), `extends` merge (`extend.rs`) |

| `source/` | URL parsing (`parse.rs`), archive download + sparse extraction (`remote.rs`), env-token auth (`auth.rs`), git-host rewriting (`hosts.rs`) |

| `fsops/` | config load incl. HTTP + `extends` (`config.rs`), comment-preserving YAML edits (`config_edit.rs`), extracted-tree cache (`cache.rs`), XDG dirs, SHA256, copy, settings I/O |

| `secrets/` | `${kst...}` placeholder scanning (`template.rs`) and resolution backends (`source.rs`) |

| `mcps/` | format-aware merge into agent settings (`merge.rs`), Codex TOML (`codex.rs`) |

| `prompts/` / `instructions/` | per-agent transforms for commands and instruction files; both parse via the shared `frontmatter.rs` |

| `lock.rs` / `state.rs` | committed `kasetto.lock` vs machine-local runtime state |

| `ui.rs` / `colors.rs` / `banner.rs` | all terminal rendering |

### Core concepts

- **Scope** (`model::resolve_scope`): `Project` or `Global`, resolved CLI flag -> config field ->

default `Global`. It picks install paths *and* the lock location: `<project root>/kasetto.lock`

- **Agent as exhaustive enum** (`model/agent.rs`, 23 variants + `AGENT_PRESETS`): each variant maps

to skill dirs, command dirs, instruction destinations, and MCP settings targets where supported,

- **Aggregate vs per-file instructions**: `AggregateMarkdown` merges many instructions into one

shared file (`CLAUDE.md`, `AGENTS.md`, ...) using managed `<!-- kasetto:instruction:ID -->`

comment blocks so hand edits and other instructions survive; the other two formats write one file

per instruction into a rules directory. The lock's `destination` token encodes which

(`agg:<rel>` = strip the block on teardown, `file:<rel>` = delete the file).

- **The lock is authoritative.** A plain `sync` installs exactly what `kasetto.lock` pins and does

zero network I/O when on-disk hashes already match (`needs_fetch` in `commands/sync/skills.rs`

re-hashes destinations *before* deciding to download). `--update`/`-u` is the only path that

re-resolves moving refs and rewrites hashes; `--locked`/`--frozen` never fetches and errors if

- **`state.rs` holds everything machine-local** (last run, latest report JSON, per-skill install

- **Source cache** (`fsops/cache.rs`): only immutable `ref:` sources are cached, under

- **Secrets are in-memory only.** `${kst_<name>}` (chain form: env var as written, then uppercased,

then `credentials.yaml`) or `${kst:<tag>:<ref>}` (tagged: `env`, `crd`, `op`, `vault`,

`kp`/`keepass`, `aws`, `gcp`, `az`, `pass`, `keychain`). Only the lowercase `kst` sentinel is

claimed - `${VAR}` and `${KST_...}` pass through untouched. Injection happens on the MCP merge

path after parsing, so the lock hashes the *placeholder* file and resolved values never reach

- **Comment-preserving config edits**: `add`/`remove` rewrite `kasetto.yaml` line-surgically via

`fsops/config_edit.rs`, never a serde round-trip, so user comments and key order survive

byte-for-byte. Then they delegate to `sync`.

### Output conventions

`colors.rs` defines 8 semantic 24-bit roles - `ACCENT` (bold, no color), `ATTENTION` (amber),

`SUCCESS` (green), `ERROR` (red), `INFO` (cyan), `BRAND` (violet), `SECONDARY` (grey), `INFRA`

(dim) - and hex values live *only* there. There is deliberately no foreground constant; body text

inherits the terminal. Commands must render through `ui.rs` helpers (`action_glyph`,

`print_section_header`, `print_source_header`, `print_status_leaf`, `print_tree_leaf`,

`print_sync_chips`, `with_spinner`, `eprint_fail`/`eprint_warn`) rather than emitting inline ANSI.

The banner is only shown on bare `kst` and `kst init`.

Sync/clean tree rows are `├─ {glyph} {label} {name} {detail}` (`print_status_leaf`) - icon, then

the status word in a fixed `STATUS_LABEL_W` column, then the name, then dim version metadata.

Every column left of the name is constant width, so names always start at the same offset. `list`

Most commands accept `--json`, `--color <auto|always|never>`, `-q`/`--quiet` (repeatable), and

`--project`/`--global`; only `sync` has `-v`/`--verbose`. `--plain` is a hidden deprecated alias

**One exit path.** `app::run` returns `ExitCode` and is the only place the process decides its

status; no command calls `process::exit`. Commands that can complete *and* report a problem return

`commands::Outcome` (`sync` when anything is broken or failed, `doctor` when a check fails,

`lock --check` on drift, `add`/`remove` by propagating their follow-up sync's verdict); the rest

return `Result<()>` and are wrapped by `app::ok`. An `Err` is rendered once by `eprint_error` -

never let one reach `main`, or Rust's `Debug` formatter prints `Error: Custom { .. }`.

### Env vars the CLI reads

`KASETTO_CONFIG`, `KASETTO_CACHE_DIR`, `KASETTO_NO_CACHE`, `PI_CODING_AGENT_DIR`, `NO_COLOR`,

`KST_KEEPASS_PASSWORD`, and source auth tokens (`GITHUB_TOKEN`/`GH_TOKEN`, `GITLAB_TOKEN`,

`CI_JOB_TOKEN`, `BITBUCKET_*`, `CODEBERG_TOKEN`/`GITEA_TOKEN`/`FORGEJO_TOKEN`).

## Site (`site/`)

Next.js 15 + React 19, Tailwind 3 with the Fumadocs preset, Biome (not ESLint/Prettier) for both

lint and format, pnpm 11 / Node >= 22.

- `app/page.tsx` is the marketing landing; `app/docs/[[...slug]]/page.tsx` renders MDX from

`content/docs/*.mdx` (sidebar order comes from `content/docs/meta.json`).

- Raw-Markdown and LLM routes: `app/docs-md/[[...slug]]/route.ts` (reached via the

`/docs/:path*.md` rewrite in `next.config.mjs`), `app/llms.txt`, `app/llms-full.txt`.

- `next.config.mjs` also holds security headers and host-gated 308 redirects from

`docs.kasetto.dev/<slug>` to `kasetto.dev/docs/<slug>` (add new slugs to `DOC_SLUGS`).

- ` ```mermaid ` fences become live `<Mermaid>` JSX via the `remarkMermaid` plugin in

`source.config.ts`, bypassing Shiki.

- Vercel auto-deploy on `main` is disabled (`site/vercel.json`); the site ships via the manual

`site.yaml` workflow.

## Conventions

- **Module docs**: every `.rs` file opens with a `//!` comment. `lib.rs` and each `mod.rs` start

`Package that contains ...`; every other file starts `Module that contains ...`. One summary

sentence, extra detail on following `//!` lines.

- `unsafe_code` is forbidden; `clippy::all` is denied, `perf` warns, and `dbg!`/`todo!` warn

(`[lints]` in `Cargo.toml`).

- Rust indents 4, everything else 2 (`.editorconfig`); max line length 120.

- **Conventional Commits** (`<type>(<scope>): <subject>`, imperative, lowercase, no trailing

- Feature or messaging changes must land in `README.md`, `site/content/docs/`, and the code

together.

## CI and release (`.github/workflows/`)

- **`ci.yaml`** - push to `main` + every PR. Two parallel jobs on `ubuntu-24.04-arm`: `ci-rs`

(install -> lint -> audit -> test -> build) and `ci-next` (same shape). Every step is a `just`

recipe, so reproducing CI locally is `just check` plus `just audit`.

- **`site.yaml`** - manual only, `npx vercel deploy --prod --yes`. Decoupled from the CLI release.