versioningcpp/skills/versiond-admin/SKILL.md

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.