sneak/vaultik
1
0
Fork 0
Code Issues 17 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Documentation accuracy sweep: undocumented behavior and stale claims #74

New Issue
Open
opened 2026-08-09 03:44:09 +02:00 by clawbot · 0 comments
clawbot commented 2026-08-09 03:44:09 +02:00
Collaborator
Copy Link
Copy Source

A collection of smaller doc/code divergences found while surveying for
1.0. Individually minor, collectively the difference between docs a user
can trust and docs they learn to ignore. Grouped here because they are all
"make the docs match the code" with no design decisions.

Excluded because they have their own issues: the remote-layout and privacy
claims (#67), the migration story (#68), and snapshot list (#64).

Items

# Doc Reality
1 README:474-475 — "All user-facing output goes through helpers in internal/ui" False. Direct fmt.Fprintf(os.Stdout, …) bypassing ui in: internal/cli/version.go:20-37 (all of version); internal/cli/config.go:276-277,336,346,401 (all of config init/get/set); internal/cli/database.go:69,76,78,84,105 (all of database delete, including its interactive prompt); internal/vaultik/info.go:18-36 via v.stdoutf (vaultik.go:161-163); internal/vaultik/snapshot.go:610-684 (the snapshot list table). All unstyled, uncolored, and ignoring w.Quiet().
2 ARCHITECTURE.md:66, :197 — "typically 16KB-256KB for 64KB average", "avgChunkSize: From config (typically 64KB)" Default is 10MB (internal/config/config.go:27, defaultChunkSize). README:365 is correct; ARCHITECTURE.md is stale by two orders of magnitude.
3 README:348 — "zstd compression at configurable level (1-19)" internal/blobgen/writer.go uses zstd.EncoderLevelFromZstd, which collapses 1-19 into klauspost's 4 discrete levels. Validation accepts 1-19 (config.go:324-327) but only ~4 behaviors exist.
4 README:121-125 — three environment variables VAULTIK_CPUPROFILE and VAULTIK_MEMPROFILE are undocumented (cmd/vaultik/main.go:14,30).
5 README:113-119 — global flags The PID lock is undocumented. RunWithApp unconditionally takes a process-wide lock in $XDG_DATA_HOME/vaultik (internal/cli/app.go:264-275) for every fx-backed command, so vaultik snapshot list fails while a backup runs. Either document it or scope the lock to mutating commands — note that scoping is a behavior change and should be its own issue if chosen.
6 README:99, :102 Aliases ls (internal/cli/snapshot.go:155) and rm (:292) are undocumented.
7 README:363 configuration reference age_secret_key is a real config key (internal/config/config.go:132) but appears neither in the README reference nor in defaultConfigTemplate. Given the threat model, a key that places the private key on the backed-up host must be documented explicitly, with its consequences — or removed. See #73.
8 ARCHITECTURE.md:122-133 Sample fx.New block says fx.Supply(config.ConfigPath(...)); the real type is config.Path (internal/cli/app.go:85).
9 README Does not link ARCHITECTURE.md, docs/DATAMODEL.md, docs/REPOSTRUCTURE.md, or config.example.yml. Only AGENTS.md is linked (README:557). config.example.yml is named in a user-facing error string (internal/config/config.go:41) but is undiscoverable from the README.

Definition of done

  1. Items 2, 3, 4, 6, 7, 8, 9 fixed by correcting the documentation.
  2. Item 1: narrow the README claim to what is true rather than
    routing five call sites through ui — that refactor is a behavior
    change affecting --quiet and belongs in its own issue. File that
    issue and link it. Do not do both here.
  3. Item 5: document the PID lock's existence, scope, and user-visible
    effect. If scoping it to mutating commands is the right answer, file
    that separately as a behavior change.
  4. No code changes in this issue beyond doc comments. Every item is
    either fixed in docs or explicitly deferred to a linked issue — none
    silently dropped.
  5. make fmt over all changed markdown; make check green.
A collection of smaller doc/code divergences found while surveying for 1.0. Individually minor, collectively the difference between docs a user can trust and docs they learn to ignore. Grouped here because they are all "make the docs match the code" with no design decisions. Excluded because they have their own issues: the remote-layout and privacy claims (#67), the migration story (#68), and `snapshot list` (#64). ## Items | # | Doc | Reality | | --- | --- | --- | | 1 | README:474-475 — "All user-facing output goes through helpers in `internal/ui`" | **False.** Direct `fmt.Fprintf(os.Stdout, …)` bypassing `ui` in: `internal/cli/version.go:20-37` (all of `version`); `internal/cli/config.go:276-277,336,346,401` (all of `config init/get/set`); `internal/cli/database.go:69,76,78,84,105` (all of `database delete`, including its interactive prompt); `internal/vaultik/info.go:18-36` via `v.stdoutf` (`vaultik.go:161-163`); `internal/vaultik/snapshot.go:610-684` (the `snapshot list` table). All unstyled, uncolored, and ignoring `w.Quiet()`. | | 2 | ARCHITECTURE.md:66, :197 — "typically 16KB-256KB for 64KB average", "`avgChunkSize`: From config (typically 64KB)" | Default is **10MB** (`internal/config/config.go:27`, `defaultChunkSize`). README:365 is correct; ARCHITECTURE.md is stale by two orders of magnitude. | | 3 | README:348 — "zstd compression at configurable level (1-19)" | `internal/blobgen/writer.go` uses `zstd.EncoderLevelFromZstd`, which collapses 1-19 into klauspost's **4 discrete levels**. Validation accepts 1-19 (`config.go:324-327`) but only ~4 behaviors exist. | | 4 | README:121-125 — three environment variables | `VAULTIK_CPUPROFILE` and `VAULTIK_MEMPROFILE` are undocumented (`cmd/vaultik/main.go:14,30`). | | 5 | README:113-119 — global flags | **The PID lock is undocumented.** `RunWithApp` unconditionally takes a process-wide lock in `$XDG_DATA_HOME/vaultik` (`internal/cli/app.go:264-275`) for every fx-backed command, so `vaultik snapshot list` fails while a backup runs. Either document it or scope the lock to mutating commands — note that scoping is a behavior change and should be its own issue if chosen. | | 6 | README:99, :102 | Aliases `ls` (`internal/cli/snapshot.go:155`) and `rm` (`:292`) are undocumented. | | 7 | README:363 configuration reference | `age_secret_key` is a real config key (`internal/config/config.go:132`) but appears neither in the README reference nor in `defaultConfigTemplate`. Given the threat model, a key that places the private key on the backed-up host must be documented explicitly, with its consequences — or removed. See #73. | | 8 | ARCHITECTURE.md:122-133 | Sample `fx.New` block says `fx.Supply(config.ConfigPath(...))`; the real type is `config.Path` (`internal/cli/app.go:85`). | | 9 | README | Does not link `ARCHITECTURE.md`, `docs/DATAMODEL.md`, `docs/REPOSTRUCTURE.md`, or `config.example.yml`. Only `AGENTS.md` is linked (README:557). `config.example.yml` is named in a user-facing error string (`internal/config/config.go:41`) but is undiscoverable from the README. | ## Definition of done 1. Items 2, 3, 4, 6, 7, 8, 9 fixed by correcting the documentation. 2. Item 1: **narrow the README claim to what is true** rather than routing five call sites through `ui` — that refactor is a behavior change affecting `--quiet` and belongs in its own issue. File that issue and link it. Do not do both here. 3. Item 5: document the PID lock's existence, scope, and user-visible effect. If scoping it to mutating commands is the right answer, file that separately as a behavior change. 4. No code changes in this issue beyond doc comments. Every item is either fixed in docs or explicitly deferred to a linked issue — none silently dropped. 5. `make fmt` over all changed markdown; `make check` green.
clawbot added this to the 1.0.0 milestone 2026-08-09 03:44:09 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
merge-ready
All checks pass, reviewed, rebased, ready for merge
 needs-checks
make check does not pass cleanly
 needs-rebase
PR has merge conflicts or is behind main
 needs-review
Code review not yet done
 needs-rework
Code review found issues to fix
No labels
Milestone
No items
No Milestone 1.0.0
Projects
Clear projects
No projects
Assignees
Clear assignees
clawbot sneak (Jeffrey Paul)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: sneak/vaultik#74