Documentation accuracy sweep: undocumented behavior and stale claims #74

New Issue

clawbot · 2026-08-09T03:44:09+02:00

clawbot commented

2026-08-09 03:44:09 +02:00

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

Items 2, 3, 4, 6, 7, 8, 9 fixed by correcting the documentation.
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.
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.
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.
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

clawbot referenced this issue

2026-08-09 10:13:00 +02:00

Decide whether feature/daemon-mode is 1.0 scope #94

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sneak/vaultik#74