Varlock

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 encrypted() entry to the functions reference (its relationship to _VARLOCK_ENV_KEY and encrypted deployments suggests it's real), or update the env-spec overview example to the documented varlock(local:...) form and rephrase the reserved-variables mention.

2. Published npm README says "8 secret manager plugins" while the docs' plugin table lists 17 (significant)

Location: https://registry.npmjs.org/varlock (README of varlock@1.9.0, published Jun 25, 2026) vs. https://varlock.dev/plugins/overview/

Problem: The npm package README — the surface behind 105.7K weekly downloads — states: "🔌 8 secret manager plugins (1Password, Infisical, AWS, Azure, GCP, Bitwarden, HashiCorp Vault, Pass)". The docs' official plugins table lists 17: 1Password, Akeyless, AWS, Azure Key Vault, Bitwarden, Dashlane, Doppler, Google Secrets Manager, HashiCorp Vault, Infisical, KeePass, Keeper, Kubernetes, macOS Keychain, Pass, Passbolt, and Proton Pass. The GitHub README uses a third framing ("plugins to pull data from various backends (1Password, Infisical, AWS, Azure, GCP, HCP Vault, more!)").

Consequence: A developer evaluating varlock on npm who needs Doppler, Kubernetes, Keeper, or Proton Pass concludes it isn't supported and moves on. Agents that ingest package READMEs (a common context source) will confidently report the wrong plugin list.

The fix: Drop the hardcoded count from the package README (mirror the GitHub README's open-ended phrasing) or regenerate the npm README from the docs' plugin table on release so it can't go stale.

3. Homepage marquee advertises Ruby, which appears nowhere in the documentation (minor)

Location: https://varlock.dev/ (integration marquee) vs. https://varlock.dev/integrations/overview/

Problem: The homepage marquee lists Ruby among supported languages ("Go JS/Node.js Other languages PHP Python Ruby Rust TypeScript"). But the integrations overview has dedicated pages for Python, Rust, Go, and PHP only, and the word "Ruby" does not occur anywhere in the site's full-text mirror (llms-full.txt) — no integration page, no mention in "Other languages," nothing. (Other marquee entries like Vercel, Netlify, Fly.io, GitLab CI, and GCP Cloud Run are documented, but only inside the Encrypted deployments and OIDC guides — the integrations overview never points to them, so a developer browsing "Official integrations" won't find them there.)

Consequence: A Ruby developer drawn in by the homepage finds zero documentation — not even a "use varlock run + a generated module like the other languages" pointer — and can't tell whether Ruby is supported, planned, or a marketing overreach. Platform users who start at the integrations overview instead of the guides can similarly miss the deployment docs that do exist.

The fix: Add Ruby to the other-languages page (or a dedicated page matching Python/Rust/Go/PHP) — or remove it from the marquee. Add pointers from the integrations overview to the Encrypted deployments and OIDC guide sections for the deploy platforms named on the homepage.

4. Homepage hero schema calls op() without the plugin declaration every other example says is required (minor)

Location: https://varlock.dev/ (hero .env.schema example)

Problem: The hero example sets XYZ_TOKEN=op("op://api-prod/xyz/auth-token") with no header. Every real usage of op() in the docs (secrets guide, GitHub README) first declares and initializes the plugin: # @plugin(@varlock/1password-plugin) / # @initOp(...) in the file header, and the plugins overview notes only @varlock-scoped plugins are supported.

Consequence: The homepage is the most-copied snippet on the site. Pasting it as-is yields a schema referencing a resolver whose plugin was never loaded, and the error is the developer's first experience with the tool.

The fix: Add the two-line plugin header to the hero example, or a visible caption noting op() requires the 1Password plugin (with a link).

What they do well

• First-class agent readability: llms.txt, llms-small.txt, and llms-full.txt all exist and mirror the complete docs, and there's a Docs MCP server plus an --agent flag on the CLI itself.
• The CLI reference is genuinely complete — every command documents options, examples, exit codes, and stdout/stderr behavior, which is rare.
• Deprecations are handled honestly in-place: @envFlag, varlock typegen, and the old remap() syntax are all documented with their replacements rather than silently removed.

Top 3 recommendations

1. Resolve the encrypted() mystery: it headlines the env-spec overview and is referenced by the _VARLOCK_ENV_KEY docs, but the functions reference never defines it — document it or replace it with varlock(local:...).
2. Generate the npm README's feature list from the same source as the docs' plugin table so the package page (105K weekly downloads) can't drift to less than half the real plugin count.
3. Make every homepage marquee entry land somewhere: give Ruby at least an other-languages mention, and link the deploy platforms (Vercel, Netlify, Fly.io, GitLab CI, GCP Cloud Run) from the integrations overview to the guides that already cover them.