A no-op at runtime by design -- nothing passed here is retained anywhere,
and this can never throw, no matter how malformed schema/docs are.
Calling it is entirely optional: createEnv works identically whether or
not a matching documentEnv call exists. The real "is everything
documented?" check, and every artifact this data drives (the docs
artifact's ownership matrix, dependency graph, lifecycle report, and
security review; .env.example's comments), runs entirely inside
build.generateEnvManifest's static analysis -- this function's only job at
runtime is to exist as a safe, harmless marker the AST parser can find,
and to give you type-checked argument shapes while writing it.
S is inferred from schema, never written out by hand -- pass the
schema object literal (or a const-inferred reference to it) directly for
the strongest inference; an explicitly-widened schema: EnvSchema
annotation loses the per-key literal type and falls back to accepting any
string key in docs.variables, same as before this generic existed.
Documents a schema for the generator: explains values, assigns ownership, and describes lifecycle, feeding the generated docs artifact and
.env.example. Pass it the same schema object given to createEnv, so the generator can statically link the two and verify every variable is documented -- and so TypeScript can checkdocs.variables' keys againstschema's own keys, the same object identity doing double duty for both the generator's static link and the type checker's.