Static build: fully static versiond-cli + docs

2026-10-18 14:03:59 +00:00
parent 8a507bfc11
commit f37e13af3d
79 changed files with 7309 additions and 0 deletions
@@ -0,0 +1,53 @@
+# 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.