Varlock Documentation Audit
Varlock's docs are unusually strong for a young project — full llms.txt/llms-full.txt mirrors, exhaustive CLI reference with exit codes, and honest deprecation notes — but the surfaces developers see first (the spec overview's flagship example, the npm README, the homepage marquee) have drifted from the reference docs in ways that will mislead both developers and AI agents.
1. The @env-spec overview's flagship example uses an encrypted() resolver that the functions reference never defines (significant)
Location: https://varlock.dev/env-spec/overview/ (vs. https://varlock.dev/reference/functions/ and https://varlock.dev/reference/reserved-variables/)
Problem: The first and only code example on the spec overview page is:
# @required @sensitive @type=string(startsWith="sk_")
STRIPE_SECRET_KEY=encrypted("asdfqwerqwe2374298374lksdjflksdjf981273948okjdfksdl")
This is also literally the first code block in the site's llms-full.txt mirror — the first thing an agent ingesting the docs sees. Yet the functions reference — "A reference of all available function resolvers in varlock" — documents ref(), concat(), exec(), fallback(), remap(), cache(), and "encryption functions for device-local secrets," with no encrypted() entry. encrypted() is not a one-off marketing leftover either: the reserved-variables page says _VARLOCK_ENV_KEY is the "Encryption key used to decrypt the injected env blob and any encrypted() values at runtime." So two pages reference encrypted() as a real value form, and the reference that is supposed to enumerate all resolvers never defines it. Meanwhile every device-local encryption example uses a different resolver: varlock(local:abc123...) (secrets guide, homepage) / varlock("local:<encrypted>") (CLI reference).
Consequence: A developer who copies the spec overview's example into their schema, or an agent that generates it from the top of llms-full.txt, produces a value form they cannot look up: it isn't in the functions reference, and searching the docs only turns up a second undefined mention on the reserved-variables page. There's no way to tell whether encrypted() is deprecated, a spec-level placeholder, or a real runtime feature that's simply missing its docs.
The fix: Either add an entry to the functions reference (its relationship to and encrypted deployments suggests it's real), or update the env-spec overview example to the documented form and rephrase the reserved-variables mention.