# versiond admin skill (C++ port)

Operate the local `versiond-cli` file-versioning service. Binary: `build/versiond-cli`. See README.md, INSTALL.md, CLI.md, PLAN.md, REGISTRY.md, AGENTS.md.

## Health first (see CLI.md)

- `./build/versiond-cli stats` (alias `status`) shows `versions=X blobs=Y`.
- `./build/versiond-cli roots` lists watch roots.
- HTTP if `serve` runs: `GET /api/health`. See README.md.

## Deploy (see INSTALL.md)

- Build: `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j`
- Test: `ctest --test-dir build -V`
- Serve: `./build/versiond-cli serve` (127.0.0.1:9922, never non-loopback).
- Env `VERSIOND_HOME` (default `/tmp/versiond`), config `config/config.toml`, index `data/index.sqlite`.

## Capture (see CLI.md, PLAN.md)

- `add <dir>`: add root and ingest now.
- `ingest <path>`: version one file, reason manual.
- `snapshot <path>`: version one file, reason snapshot.
- Cap `max_file_bytes` (default 10 MiB).
- Never: node_modules, venv, target, hidden dirs, *.pyc, *.o, *.so, *.min.js, *.map, temps (*.tmp, ~$*, #*#, *~, 4913).

## Retention (see CLI.md, REGISTRY.md)

- `purge`: cleanup old versions per `keep_days` (default 5), outputs purge=N.
- `gc`: remove unreferenced blobs, outputs gc=N.
- `sync`: push to remote SFTP via [remote] config, outputs sync=N.

## Recovery (see CLI.md, README.md)

1. Reinstall per INSTALL.md, restore config dir.
2. `history <path>` picks digest.
3. `show <digest>` verifies content.
4. `diff <digestA> <digestB>` verifies delta.
5. `restore <digest> <dst>` restores, parents created.

## Destructive (see AGENTS.md)

- `remove <dir>` only untracks root, data stays.
- `purge` and `gc` delete: run `history` and `stats` first.
- Verify with `show` and `diff` before `restore`.
- Targets must stay inside allowed roots, symlinks refused.

## Troubleshooting (see README.md, INSTALL.md)

- 0 versions: run `roots`, re-`add`.
- ingest skip: over max_file_bytes or ignored pattern.
- sync fail: check [remote] config and quota.
- serve refuse: non-loopback bind attempted.
- Full ref: CLI.md. Build: INSTALL.md. Map: PLAN.md. Provenance: REGISTRY.md. Rules: AGENTS.md.