docs: state the mkfifo mechanism, and close the grant and AI-wrap gaps - #62
Merged
Conversation
Readers kept asking how a file read reaches the vault and could not find the answer: the docs said "local encrypted store" in many places and never named the mechanism. The README, how-it-works and mounts now state it plainly - a POSIX FIFO at mode 0600, open(2) blocking until the service connects O_WRONLY, bytes going from memory into the kernel pipe buffer, and the re-open loop that lets it be read more than once. No kernel extension, no filesystem driver. Verified against internal/mount before writing. jit grant shipped in v0.86.0 and reached none of the onboarding pages: it lived only in service/grants.md, the README and the generated reference, so a reader walking quickstart -> run -> tools never met it. It is now a quickstart step, a run-guide section and a tools row. Same story for the five AI wrappers added in v0.84.0 (cursor-agent, copilot, cline, opencode, kiro-cli), which had their own pages but appeared in neither tool list. The install section put the tarball beside brew as an equal alternative with the signing rationale ten lines below, which read as recommending the weaker path. The caveat now sits with the command, and the tarball carries its own shasum and codesign verification lines. Corrections found while checking claims rather than trusting them: - security/brief claimed "no network calls, no auto-update", untrue since jit upgrade landed in v0.41.0. It now describes the one outbound request and what it verifies before installing. - quickstart still called scan "audit", stale since the v0.33.0 rename. - PR #57's stale mount registrations and group-aware vault rm, and PR #58's doctor hygiene routing, reached the generated reference but no prose. - a broken anchor in environment-variables.md (two hyphens, needs three). Also answers the questions the docs were repeatedly asked but never addressed: full-disk encryption solving a different problem, memory being explicitly out of scope, what the crypto actually is (stdlib AES-256-GCM, with Argon2id from x/crypto for export passphrases only), and an honest comparison against age, SOPS, dotenvx, 1Password and systemd-creds. Prose em dashes removed from the entry and security pages per the voice guide. Sample output blocks keep theirs, because the CLI really prints one (internal/audit/triage.go); changing that is a terminal-output change and wants a preview first. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HU9CJPZU9B5JydjLqr4js4
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs-only. Two drivers: a staleness audit against the shipped CLI, and the questions the HN thread kept asking that the docs did not answer.
The mechanism people could not find
Readers asked how a file read reaches the vault and could not find it: the docs said "local encrypted store" in many places and never named the mechanism. README,
how-it-works.mdandrun/mounts.mdnow state it plainly, a POSIX FIFO at mode 0600,open(2)blocking until the service connectsO_WRONLY, bytes moving from memory into the kernel pipe buffer, and the re-open loop that lets it be read more than once. No kernel extension, no filesystem driver. Checked againstinternal/mountbefore writing.Coverage gaps
jit grantshipped in v0.80.0-era and reached none of the onboarding pages. It lived only inservice/grants.md, the README and the generated reference, so a reader walking quickstart to run to tools never met it. Now a quickstart step, a run-guide section and a tools row.cursor-agent,copilot,cline,opencode,kiro-cli) had their own pages but appeared in neither tool list.vault rm, and PR doctor: route the vault hygiene sweeps in as advisory findings #58's doctor hygiene routing, reached the generated reference but no prose page.Corrections found by checking claims
security/brief.mdclaimed "no network calls, no auto-update", untrue sincejit upgradelanded. It now describes the one outbound request and what it verifies before installing.scan"audit", stale since the rename.environment-variables.md(two hyphens, needs three).Install ordering
The tarball sat beside brew as an equal alternative with the signing rationale ten lines below, which read as recommending the weaker path. The caveat now sits with the command, and the tarball carries its own
shasumandcodesignverification lines.New answers
Full-disk encryption solving a different problem, memory being explicitly out of scope, what the crypto actually is (stdlib AES-256-GCM, with Argon2id from
x/cryptofor export passphrases only), and an honest comparison against age, SOPS, dotenvx, 1Password and systemd-creds.Verification
docs/resolvego build ./...clean, no code touchedNot included
The em dash in
jit scanoutput (internal/audit/triage.go) breaks the voice guide's hard rule, but changing it is a terminal-output change and wants a preview script first. Prose em dashes on the entry and security pages are fixed here; sample output blocks keep theirs because they accurately reproduce what the CLI prints.🤖 Generated with Claude Code
https://claude.ai/code/session_01HU9CJPZU9B5JydjLqr4js4