Restructure Documentation for a Configuration Library

Problem/Feature Description

A small open-source library called confz provides a configuration loading and validation utility for Node.js. It was originally documented in a single README.md that was written incrementally over two years. The result is a sprawling document that mixes examples with API tables, step-by-step walkthroughs with conceptual background, and quick start code with deep-dive explanations — all on one page.

The library now has enough users that the maintainers want proper structured documentation. They have assembled rough notes covering four main areas they want documented: getting started for new users, solving common configuration problems, a full reference of the configuration options, and background on how the layered resolution system works under the hood. The maintainers want these areas separated into well-organized pages that serve different user needs.

Your job is to take the raw notes below and produce a set of properly structured documentation pages. Each page should serve a single purpose and be easy for its intended reader to navigate. A first-time user should be able to get something working from the getting-started page without needing to read anything else. An experienced user who already knows confz should be able to solve a specific problem without reading conceptual background. Someone looking up an option should be able to find it in under 30 seconds.

Output Specification

Produce the following documentation files:

• docs/tutorial.md — for users learning confz for the first time
• docs/how-to.md — for experienced users solving a specific problem
• docs/reference.md — for users looking up options or API details
• docs/explanation.md — for users who want to understand how confz works

Each file should be written in Markdown.

Input Files

The following are the raw notes from the maintainers. Extract them before beginning.

=============== FILE: raw-notes/getting-started.txt =============== confz is a library for loading config. You call loadConfig() with a schema. Users are often new to validation libraries. They need to see a working example quickly. They should install it with npm install confz. Then they create a schema with z.object from zod. Then they call loadConfig({ schema }) and it reads from process.env. A good example is building a server config: PORT, DATABASE_URL, NODE_ENV. They should be able to run node server.ts at the end and see "Server running on port 3000". Each step should have something they can run or verify. Assume no prior knowledge.

=============== FILE: raw-notes/common-tasks.txt =============== A common ask: how to add a .env file as a source alongside process.env. Another common ask: how to set a default value for an optional field. Another common ask: how to validate that a string matches a specific format (e.g. a URL). Users asking these questions already know how to use confz basics. Just show the solution — no need to explain what confz is. Note alternatives: for defaults, you can use .default() in zod or the defaults option in loadConfig.

=============== FILE: raw-notes/options-reference.txt =============== loadConfig(options) accepts:

• schema: ZodObject — required — the Zod schema to validate against — example: z.object({ PORT: z.string() })
• sources: Source[] — default: [processEnv()] — list of config sources to merge — example: [dotenv('.env'), processEnv()]
• defaults: Record<string, string> — default: {} — key-value pairs merged before validation — example: { PORT: '3000' }
• strict: boolean — default: false — throw on unknown keys not in schema — example: true
• prefix: string — default: '' — strip this prefix from env var names before matching — example: 'APP_'

processEnv() — no options — reads from process.env dotenv(path) — path: string — reads from a .env file at the given path memory(values) — values: Record<string,string> — in-memory source for testing

=============== FILE: raw-notes/internals.txt =============== confz uses a layered resolution approach. Sources are merged left-to-right — later sources override earlier ones. This is similar to how webpack config merging works. The reason for left-to-right merging is that it makes defaults easy: put your defaults source first, env vars last. After merging, the combined object is passed to the Zod schema for validation. Unknown keys are stripped by default (strict: false). With strict: true they throw. The design decision to use Zod was made because Zod is widely used and provides good error messages. An alternative would have been to use a custom validator, but that would require users to learn another API.