# Changelog

> Every release of the starter and what it changed, from the repository's CHANGELOG.md. Changed and Removed entries are where a merge conflict in a customised copy can come from.

You are reading one page of the ZeroDirs documentation. ZeroDirs is an Astro + Cloudflare Workers starter for directory sites: every page is rendered to static HTML at build time, the site ships no client JavaScript outside `/search/`, and one file — `site.config.ts` — carries roughly 80% of the customisation.

Two things to hold on to before you act on anything below:

- `site.config.ts` is validated by a zod schema with ten cross-field rules. After any edit to it, run `pnpm check:config`; every problem is reported as `site.config.ts › <path>: <message>` and the whole file is checked at once.
- The repository ships its own `AGENTS.md` with eighteen hard rules, and a machine-checked test suite behind them. If you are working inside a ZeroDirs project, read that file first — it overrides anything general you infer from this page.

Source: https://zerodirs.com/docs/about/changelog/

---

<!-- DO NOT EDIT — generated from zerodirs/zerodirs CHANGELOG.md by .github/docs/generate.ts (docs-sync.yml). Edit the source, not this page. -->

Notable changes to the ZeroDirs Starter. The format follows
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
[Semantic Versioning](https://semver.org/spec/v2.0.0.html) as they apply to a codebase you own:

- **Major** — a change that will not merge cleanly into a customised copy, or that changes the
  shape of `site.config.ts`.
- **Minor** — new features and new config fields, with defaults that keep existing sites building.
- **Patch** — fixes and documentation.

Quote the version below when you ask for support, and paste the **full output** of the failing
command. The version is also in `package.json`. Support: <hi@zerodirs.com>.

Three paths are yours and no release edits them: `site.config.ts`, `src/content/` and
`public/`. Everything else is ours to change, so **Changed** and **Removed** entries are where
a merge conflict would come from —
[zerodirs.com/docs/about/updates/](https://zerodirs.com/docs/about/updates/) covers how to
apply one.

## 0.2.1 (unreleased)

### Changed

- **`pnpm cf:secrets` is one command, no prompts** (design.md N74): it reads `.env.prod`,
  checks the shape of every value, sends all runtime secrets to the Worker in one request and
  reads back what the Worker has. `--dry-run` shows the plan without sending, `--list` shows
  the names, what your `site.config.ts` needs and what is set, and bare names
  (`pnpm cf:secrets STRIPE_SECRET_KEY`) send only those — from `.env.prod`, no longer from a
  prompt. `--all` still works and means nothing; `--from-env` and the fallback to `.env` are
  gone (test-mode keys must never reach production by accident). A key in `.env.prod` that
  `.env.example` does not know stops the run. **To upgrade:** nothing in your files changes;
  create `.env.prod` from `.env` if you have not, and drop `--all` from any note you kept.
- **The header, redrawn** (design.md N68): the Submit call-to-action is a pill with a
  paper-plane icon and the word "Submit" (its accessible name is still "Submit a {noun}");
  the search field is gone from the header — the home page carries the big one — and the
  theme toggle and a new account icon sit to the right of the pill. The account icon links
  to `/dashboard/` and replaces the "Account" item in the nav; for a signed-out visitor it
  opens the sign-in dialog (next entry), and for a signed-in one it is their avatar, which
  opens a menu — name, address, Dashboard, Bookmarks, Log out (design.md N78). Content pages
  are static and identical for everyone, so the header learns who is signed in from a second
  cookie, `zd_user`, that holds a name, an address and an avatar URL and nothing a thief
  could use; the session itself stays in the HttpOnly `zd_session`. **To upgrade:** add
  `'send'`, `'user'`, `'layout-dashboard'`, `'bookmark'`, `'log-out'` and `'chevron-down'` to
  `theme.icons` in `site.config.ts`; without them the pill shows only its label and the
  menu only its words, and nothing fails.
- **Signing in happens in a dialog** (design.md N76): pressing the account icon opens the
  sign-in card on the page the visitor is already on — email and password, "Continue with
  Google" when both Google secrets are set, "Forgot password?" and "Don't have an account?
  Sign up" — instead of sending them to `/login/`. A wrong password comes back into the
  dialog, with the address kept and the password field focused; a right one sends the
  visitor on to the page they were after, or to `/dashboard/`. The card is asked for when the
  dialog opens (`/login/dialog/`, rendered by the Worker), because a static page cannot know
  who is signed in or whether the Worker holds the Google secrets. `/login/` stays — it is
  where `/submit/` and `/dashboard/` send a signed-out visitor, and what a browser without
  JavaScript gets — and is redrawn as the same card. It costs one more inline script on every
  page while `features.accounts` is on, about 2.6 KB; still no island and no `<script src>`,
  and the e2e smoke test counts it. **To upgrade:** take the merge. If you had edited
  `src/templates/account/LoginPage.astro`, its markup now lives in
  `src/components/account/AuthCard.astro`; the three form-validation colours moved from
  `src/components/forms/Field.astro` into `src/styles/global.css`.
- **Submitters sign in with a password, not an emailed link** (design.md N77). An account is
  made on `/signup/` with an email and a password (eight characters or more), and signed in
  on `/login/` or in the dialog with the same; "Continue with Google" is unchanged. Passwords
  are stored as PBKDF2-HMAC-SHA-256 at 100,000 iterations with a per-password salt, in a form
  that names its own parameters, so the count can be lowered later (the free plan's CPU
  budget is tight for it) without invalidating anything. The one emailed link left is
  "Forgot password?": `/login/forgot/` queues a reset link that works once and for twenty
  minutes, `/auth/reset/` is where it lands, and the `password-reset` email template replaces
  `login-link`. Ten wrong passwords in a quarter of an hour lock the address for the rest of
  it; the form says "wrong email or password" and nothing more, whichever it was. Nothing
  checks the mailbox at sign-up, so an address is only *proven* by a Google sign-in or a
  completed reset — and the first time it is proven, a password somebody else registered
  for it is dropped, with its sessions: the mailbox's owner gets the account, and sets a
  password of their own through the reset link. **To upgrade:** `pnpm db:migrate:local`,
  then `pnpm db:migrate:remote` once (`0002_passwords.sql` adds two columns to `users` and
  marks every account that exists as proven). Accounts made under 0.2.0 have no password:
  Google keeps working for them, and "Forgot password?" sets one. `requestLoginLink` /
  `consumeLoginLink` are gone from `src/server/auth/`; `/auth/callback/` with it.
- **`/account/` is now `/dashboard/`** (design.md N78, N79), an area of its own with a
  sidebar — Overview, Submissions, Bookmarks under *Dashboard*, Account under *Settings*,
  then *Visit site* — and a top bar with the Submit button, the theme toggle and the account
  menu. The sidebar folds to a rail of icons on a wide screen (every icon is still the link,
  with its name as the tooltip) and stays folded from page to page through a `zd_rail`
  cookie; on a phone it is a drawer. Overview: four numbers (submitted, live, in review,
  clicks in the last 30 days) and a table of every submission that `?q=` searches by name or
  host and `?sort=`/`?dir=` order by name, status, clicks, submission or publication date —
  plain links and a GET form, no script. Submissions: the same rows under tabs, with what can
  be done about each — **Upgrade** a submission waiting in the free queue onto a priced plan
  (a popover with the plans, each leading to its checkout), **Complete payment**, **View**,
  **Submit again**, and **Withdraw** a submission that is still waiting and not paid for: it
  asks once, then the submission becomes "Withdrawn" (stored as `rejected` with the reason
  `Withdrawn by the submitter.`, so the operator sees why it left the queue; no email) and
  the address is free to be submitted again. Account: the avatar, address and sign-up method
  with a Log out button, the name, and the password — change it with the current one, or set
  a first one on an account that has only used Google; either signs out every other device.
  `/account/` answers with a permanent redirect to `/dashboard/`, and `dashboard` joins the
  reserved route segments and the `robots.txt` disallow list. **To upgrade:** take the merge;
  add `'zap'`, `'arrow-up'`, `'arrow-down'`, `'chevrons-up-down'`, `'panel-left'`, `'lock'`
  and `'calendar'` to `theme.icons` (each is optional, like the others); a `routes.*Base`
  named `dashboard` has to be renamed, which `pnpm check:config` will say. The
  `src/templates/account/AccountPage.astro` of 0.2.0 is gone; the dashboard's pages are
  `src/templates/account/Dashboard*.astro` on `src/layouts/Dashboard.astro`.
- **⌘K / Ctrl K opens a command palette** on every page: a search field, the site's quick
  links and its featured listings (logo, name, host), filtered as you type; Enter runs the
  full search on `/search/`. The `⌘K` badge in the home-page search field opens it too, and
  reads Ctrl K off a Mac. It is a native `<dialog>` with server-rendered rows and one inline
  script of about two kilobytes — no island, no `<script src>`, so rule 17 still holds and
  the e2e smoke test counts it. `theme.icons` should list `search` and `x` for its two
  icons (the demo config already does).
- The first `pnpm dev` of a fresh clone takes about twenty seconds instead of three and a
  half minutes, and `pnpm content:reset --local` a few seconds instead of the same. Every
  logo used to go into the local bucket through its own `wrangler r2 object put --local`
  (and out through its own `delete`), 1.5 s of wrangler start-up per object; against
  `--local` the seed and the reset now open the bucket binding once in-process, through
  wrangler's `getPlatformProxy()`, and put concurrently or delete in one batch. Downloads run
  sixteen at a time instead of eight, and a host that has not answered in five seconds is a
  letter tile rather than a twelve-second wait. `--remote` is unchanged: one wrangler process
  per object, no S3 credentials needed.

### Added

- **`/signup/`, a create-account page** (design.md N76, N77), where the sign-in dialog's
  "Sign up" leads: a name (optional, it ends up on the account), an email and a password,
  or Google when it is configured, with the terms and privacy pages linked when `legal` has
  them. `signup` joins the reserved route segments and the `robots.txt` disallow list. **To
  upgrade:** a `routes.*Base` named `signup` has to be renamed, which `pnpm check:config`
  will say.
- **Bookmarks** (design.md N79): a Bookmark button on every listing page, under "Visit", for
  a signed-in visitor — pressed, it saves the listing in place and reads "Bookmarked" from
  then on; pressed by a signed-out visitor it opens the sign-in dialog and comes back to the
  page. `/dashboard/bookmarks/` lists what was saved, newest first, with Open and Remove. The
  button is a form that works without JavaScript (the post lands on the bookmarks page), plus
  one inline script of about 0.8 KB on listing pages only, which asks `/api/bookmarks/<id>/`
  whether the listing is saved — a static page cannot know — and posts to it with `fetch`.
  **To upgrade:** `pnpm db:migrate:local`, then `pnpm db:migrate:remote` once
  (`0003_bookmarks.sql` adds the `bookmarks` table). `features.accounts` off leaves the
  button out; there is no flag of its own. A seed or `pnpm content:use` keeps bookmarks:
  seeded listings keep their ids, and a bookmark whose listing is gone is simply not shown.

### Fixed

- A submission that was refused — or, now, withdrawn — could still be paid for: its status
  page kept its "Complete payment" button, and `/api/checkout/` took the money for a listing
  that would never be reviewed. Both now apply to a pending submission only.
- The Google sign-in failed with "Sign-in did not complete" on every attempt: the OAuth state
  cookie was URL-encoded twice on the way out and never matched on the way back. The reason
  a Google round trip declines is now logged (`auth: Google sign-in did not complete — …`),
  so a wrong client secret or an unregistered redirect URI can be told apart from a refused
  address. Under `pnpm dev` the redirect URI is the local origin
  (`http://localhost:4321/auth/google/callback/`), so "Continue with Google" can be tried
  locally with that URI registered as a second one.
- **Deploys no longer fail with "required secrets have not been set"** (design.md N75). Since
  0.2.0, `wrangler.jsonc` listed every runtime secret under `secrets.required`, and `wrangler
  deploy` refuses to deploy while any of them is missing on the Worker — so `pnpm cf:setup`
  (which has to deploy once before it can put a secret), Workers Builds and the GitHub
  Actions workflow all failed for a site that leaves an optional provider off. The `secrets`
  block is gone from `wrangler.jsonc` altogether: an empty list would unblock the deploy, but
  any `secrets` block makes wrangler hand the local Worker only the names it lists, and
  `pnpm preview` would run without the secrets in your `.env`. What the list was there for —
  a `worker-configuration.d.ts` that does not depend on your `.env` — is now `pnpm
  cf:typegen` reading the names from `.env.example` (`wrangler types --env-file
  .env.example`); CI checks with `pnpm cf:typegen --check`. **To upgrade:** take the merge;
  if you had added a `secrets` block or names of your own, remove them, and use `pnpm
  cf:typegen` rather than a bare `wrangler types`. `Env` now lists every key of
  `.env.example`, the four build-time ones included. One thing the list did by accident is
  now done by name: `astro preview` reads its secrets from the build's snapshot of `.env`
  (`dist/server/.dev.vars`) or from `process.env`, never from the `.env` file itself, so a
  build made before `.env` existed served a Worker with no `TOKEN_SECRET`;
  `integrations/preview-secrets.ts` sets wrangler's `CLOUDFLARE_INCLUDE_PROCESS_ENV` for
  `preview`, and `pnpm test:e2e` rebuilds when `.env` is newer than `dist/`.
- The first `pnpm dev` of a fresh clone exited with `The file does not exist at
  "node_modules/.vite/deps_ssr/handler-….js"`; the second one worked. Vite discovered the
  preact renderer's server entry on the first request, re-optimized the SSR dependencies and
  reloaded, and the Cloudflare plugin's worker was still holding the chunk that had just been
  replaced. The entry is now pre-bundled at startup, and CI starts the dev server on a cold
  cache and fails when it does not answer.

## 0.2.0 — 2026-09-22

### Changed

- **One environment file.** Build-time variables and runtime secrets now share `.env`, with
  `.env.example` as the committed key set and `.env.prod` (gitignored) as what production gets.
  `.dev.vars` is gone: wrangler reads it in preference to `.env`, so keeping both meant a stale
  file could silently shadow every secret you edited. **To upgrade:** `cat .dev.vars >> .env && rm .dev.vars`,
  then `pnpm cf:typegen`. `pnpm dev` refuses to start while a `.dev.vars` is still there, and
  prints that same line. `wrangler.jsonc` now declares `secrets.required`, so `wrangler types`
  writes the same `Env` on every machine and CI no longer seeds a secrets file before checking
  the committed types.
- **Listings always come from D1.** Every build reads the database: with the three D1
  credentials set (`CLOUDFLARE_ACCOUNT_ID`, `D1_DATABASE_ID`, `D1_READ_TOKEN` — a production
  builder) the real one over its REST API, exactly as before; with none of them set (your
  machine, CI) the local Miniflare database under `.wrangler/`, through `wrangler d1 execute
  --local`. A partial set fails the build and names the rest, and a builder that has lost its
  variables has no local database either, so it fails instead of shipping the seed listings
  as a success. `pnpm dev` seeds the local database with the demo dataset — rows and logos —
  the first time it finds it empty, and never touches a database that holds anything. A local
  build links every logo through the `/media/` route, which the Worker now serves in every
  environment (production links keep using `media.baseUrl`), and the OG images of a local
  build carry no logo. Outbound click counting therefore works in every build: every listing
  has a row id. **To upgrade:** listings you kept in `src/content/listings/` go into the
  database once — `pnpm db:seed:local --from src/content/listings`, then the same with
  `--remote` — and the directory, `public/logos/`, `LISTINGS_SOURCE` and `ZERODIRS_DATASET`
  can go; a Workers Builds or Actions setup that built from Markdown now needs the three
  credentials. `pnpm cf:doctor` says which database a build here reads.
- `pnpm content:reset` and `pnpm content:use` act on a database (`--local` by default,
  `--remote`): `reset` deletes the seeded rows, their logos in the bucket and the demo blog
  posts and leaves the database empty; `use <dataset>` seeds it with a dataset and copies the
  dataset's blog posts. `pnpm listings:import` writes to a database (`--local` or `--remote`,
  one is required unless `--dry-run`) and no longer to Markdown files; `pnpm check:config`
  counts the approved rows in the local database for its estimate.
- `pnpm cf:setup` finishes the email step instead of only reporting it: with
  `providers.email: 'cloudflare'` and no sending domain it offers `wrangler email sending
  enable <domain>`, keeps the `EMAIL` binding when that works, and puts the binding back on a
  later run once the domain exists — previously the binding was dropped and had to be restored
  by hand.
- The default look, redrawn (design.md N51): a search-first home page with the category chips
  under the field, cards led by a logo tile with the name over its category, a browse strip of
  category chips on the listing index and category pages, a sticky facts card with the outbound
  button on the detail page, a stepper and option cards on the submission form, a four-tile
  queue summary on the admin dashboard, and a sticky translucent header with a Submit button on
  every page. Still zero JavaScript. The tokens are the same fifteen; `default`'s `radius` moves
  from `0.5rem` to `0.75rem`, and cards, buttons and chips are now fixed multiples of it
  (`rounded-brand-lg`, `rounded-brand-pill`), so `mono` stays square and `warm` rounder with no
  new knob. Three component classes join `.btn` and `.card`: `.chip`, `.input`, `.hero-glow`.
  A copy that overrides `radius` gets the same proportions at its own size; one that edited
  `Card.astro`, `Detail.astro`, `Header.astro`, `Footer.astro` or `HomePage.astro` will merge
  by hand.
- Paid plans ship **on**: `features.payments: true`, `providers.payment: 'stripe'` and both
  priced tiers enabled in `site.config.ts`, the way the demo runs. The two Stripe secrets are
  yours to set (`pnpm cf:secrets STRIPE_SECRET_KEY STRIPE_WEBHOOK_SECRET`); until they are on
  the Worker a paid submission's checkout answers 503 "Payment is temporarily unavailable",
  `/admin/` reports both keys, and the free plan keeps working.
- Email ships **on**, through Cloudflare Email Sending: `providers.email: 'cloudflare'` in
  `site.config.ts` and the `EMAIL` (`send_email`) binding declared in `wrangler.jsonc`. It
  needs the Workers Paid plan and a sending domain enabled on your zone; until both are true
  every message still renders into `email_outbox` and `/admin/` says why. On the Free plan,
  switch to Resend — the skill walks through it.
- The README troubleshooting section names the `npm install` crash of npm 11.4 (Node 24.3)
  on vitest 4's peer dependencies and the three ways out; pnpm is unaffected.
- `pnpm cf:secrets` is a conversation now. It starts by listing which secrets the deployed
  Worker already has, shows each key's help text line by line (every key in
  `.env.example` now says where its value comes from), takes names as arguments
  (`pnpm cf:secrets STRIPE_WEBHOOK_SECRET`), checks the shape of a value before uploading
  it — a `whsec_` pasted into `STRIPE_SECRET_KEY`, the placeholder `TOKEN_SECRET`, a
  publishable key — and asks before going ahead, and ends cleanly on Ctrl+C with what was
  set and what is still missing. Every prompt also says whether the current `site.config.ts`
  needs that secret at all (a GitHub token is idle on a site that publishes through a deploy
  hook). Wrangler's banner no longer interleaves with the prompts.
- The demo's top banner (`ads.topBanner`) is a house ad for ZeroDirs: on your own site, give it
  your sponsor's text and `url`, or set `enabled: false`.
- pSEO, the OG images and the related-listings ranking moved to `src/features/pseo/`,
  `src/features/og/` and `src/features/related.ts`, and `src/features/index.ts` is gone.
  Templates and components import those modules directly, and each entry function checks its
  own flag (`pseoPages()` reads `features.pseo`, `relatedListings()` reads
  `features.relatedLinks`) and takes the config as an argument. A copy that edited one of these
  files merges it as a rename; one that imported from `src/features/index.ts` changes that
  import. The hard rules in `AGENTS.md` are renumbered.

### Added

- `pnpm cf:media`: the one step `pnpm cf:setup` could not finish. It makes the R2 bucket
  readable from the web — a custom domain when you have the zone id, the `r2.dev` URL
  otherwise — and writes the result into `media.baseUrl`, restoring `site.config.ts` untouched
  if the edited file does not validate.
- `pnpm cf:doctor`: one read-only screen for "is this actually wired up?". It checks the tooling,
  `site.config.ts`, `wrangler.jsonc`, `.env`, which secrets the Worker holds, the R2 bucket and
  sending domain, and whether the live site was built with the config you have now — each line
  either `✔` or a problem with the command that fixes it. It writes nothing, and a check it
  cannot make (no login, `--offline`) says so instead of guessing. `--json` for an agent,
  `--strict` to fail on warnings, `--manual` for the steps no CLI can do.
- `pnpm cf:secrets --all`: every runtime secret in `.env.prod` (or `.env`) in one
  `wrangler secret bulk`, values on stdin. Empty, placeholder and wrong-shaped values are left
  out and named, so a truncated paste cannot reach the Worker. `--dry-run` lists what it would
  send without sending anything.
- `pnpm cf:ci`: the build-time half of the same file pushed to GitHub Actions with
  `gh variable set` / `gh secret set`, and the Build step's `env:` block in
  `.github/workflows/deploy.yml` rewritten from `.env.example` between marker comments, so a
  variable you add is never missing in CI. `--enable` sets `USE_GITHUB_DEPLOY`.
- `pnpm cf:setup`: from a checkout to a running site in one command — Worker name, custom
  domain or `*.workers.dev`, D1 and R2 created and written into `wrangler.jsonc`, the
  `send_email` binding left out until the account can send, production migrations, build,
  deploy, and `TOKEN_SECRET`. Idempotent, with `--dry-run` and `--workers-dev`.
- `pnpm dev` (and `pnpm test:e2e`) now runs `scripts/dev-setup.ts` first: `.env` from its
  example when missing, the D1 migrations applied to the local database, and the demo dataset
  seeded into it while it is empty — so a fresh clone reaches `/`, `/submit/` and `/admin/`
  on its first `pnpm dev` with no Cloudflare account.
- A `go-live` skill: the steps `cf:setup` leaves to you — domain, the real database for the
  builder, Workers Builds and the Deploy Hook, email, payments — one question at a time.
- Submitter accounts (`features.accounts`, on in the demo): sign in with an emailed link that
  works once for twenty minutes, or with Google once `GOOGLE_CLIENT_ID` and
  `GOOGLE_CLIENT_SECRET` are set; `/account/` lists a submitter's own submissions with their
  review status; `/submit/` requires a session and takes the address from it. Sessions are
  30-day cookies whose ids are stored hashed; the hourly cron sweeps what expired. One
  expand-only migration (`0001_accounts.sql`) adds `users`, `sessions`, `login_tokens` and
  `listings.user_id`. The `configure-accounts` skill has the Google steps. Ten skills.
- Ad placements, each one boolean in the new `ads` block: a banner under the header, a sponsor
  wall under the home page hero, a card inside every listing grid, and a corner card that can be
  dismissed without JavaScript. `/advertise/` lists the placements and their prices and is built
  only while `ads.page.enabled`. Everything is static and marked as an ad (`rel="sponsored"`);
  the demo shows all four with placeholder copy.
- The free review queue says how long it is. A free submission's status page and receipt
  email state when it is expected to go live — position in the queue divided into the last
  30 days of real approvals, or `queue.estimateDays` (21) while there are none — and offer the
  priced plans to skip ahead: one click to Stripe Checkout, and the tier changes only once the
  payment lands. The operator gets one reminder a day at `queue.digestHourUtc` (09:00 UTC)
  while anything is waiting, with the oldest wait and the paid submissions close to their
  review promise; `null` switches it off. The admin dashboard shows the same numbers.
- `site.builtWith` (default `true`): a "Built with ZeroDirs" link in the footer, one boolean
  to remove. Not a licence condition.
- A `configure-email` skill: the three email providers side by side, the Cloudflare Email
  Sending path, the Resend path for the Workers Free plan, and how to verify with the outbox
  and the `/admin/` configuration report.
- `tests/unit/put-secrets.test.ts`: the pure parts of `pnpm cf:secrets` — the help text every
  key gets, name selection, and each shape check, including that no check ever repeats the
  value.

### Removed

- `.dev.vars` and `.dev.vars.example`. See the `.env` entry under Changed.
- Markdown as a listings source: `src/loaders/files.ts`, `src/content/listings/` (a copy of
  the `ai-tools` dataset), `public/logos/` (its 14 tiles, still in
  `seed/datasets/ai-tools/logos/`), the `LISTINGS_SOURCE` and `ZERODIRS_DATASET` build
  variables, `pnpm content:check`, and `pnpm listings:import`'s `--out` / `--to`. See the D1
  entry under Changed for the one-time move.
- `docs/`. The documentation is the site at zerodirs.com/docs, which is generated from the code
  and cannot drift the way the copies here did, and nothing in the starter links to the old
  files any more. Their text is in the git history (`git log -- docs/`). If your copy edited
  a file under `docs/`, the merge reports a modify/delete conflict: keep the file or delete it,
  nothing reads it.

### Fixed

- The submit Action built its email provider without the Worker's bindings, so with
  `providers.email: 'cloudflare'` the console provider "sent" every receipt: the outbox rows
  were marked `sent`, nothing left the account, and no error was raised anywhere. Both
  Actions and the cron now hand `env.EMAIL` over through one helper, and a unit test fails
  if any of them ever builds a provider without it.
- `features.search: false` failed the build: `/search/` was still built, island included, but had
  left the routes manifest, so the zero-JS check no longer exempted it. The page now returns a
  body-less 204 while the feature is off, the way `/blog/` does, and no file is written.
- The search panel's message under `pnpm dev` said a build alone would enable search there; it is
  `pnpm build` and then `pnpm preview`.
- `LICENSE` §5 said `pnpm content:reset --yes` removes the demo datasets. It removes the demo
  listings, the demo posts and the files in `public/logos/`, and leaves `seed/datasets/` in
  place; the licence now says so. Comments that miscounted the runtime secrets or the hourly
  jobs (`.env.example`, `scripts/put-secrets.ts`, `wrangler.jsonc`, `src/worker.ts`,
  `src/server/jobs.ts`, `AGENTS.md`) are corrected too.
- The `import-listings` and `generate-listings` skills said a numeric custom field does not
  render and told the agent to quote it. Numbers and booleans render; only arrays and objects
  are dropped, which is what both skills now say.

## 0.1.0 — 2026-09-13

The first buyer release. Everything listed here works today. Several subsystems ship switched
**off** because switching them on needs a database or a credential we cannot put in a
repository — the README's "What's on, what's off" table says what each one still needs.

### Added

**Directory core**
- Listings, categories, tags and pagination from Markdown in `src/content/listings/`, one file
  per listing, validated against `site.config.ts` at build time.
- One catch-all route builds every directory page from a pure, unit-tested route table, so the
  URL segments (`routes.listingBase`, `categoryBase`, `tagBase`) are yours to rename.
- Related listings on every detail page, and configurable per-listing custom fields.
- Full-text search over listing pages (Pagefind), indexed during the build. `/search/` is the
  only page in the site that hydrates.
- Blog with its own feed at `/blog/rss.xml`, a site-wide latest-listings feed at `/rss.xml`, and
  about, privacy, terms and 404 pages.

**Submissions, moderation and payments** (`features.submissions`, `features.payments`)
- A public two-step submission form that prefills itself from the submitted site's own metadata,
  a honeypot trap, per-email rate limiting, and a signed, token-addressed status page that needs
  no account and no password. The submitter never sees the word "logo": the prefill ranks every
  icon the page declares, and the server downloads them in order until one is storable.
- An admin area — review queue, listing editor, featured placements and stats — open to the
  accounts named in `admin.emails`, with a Publish button and an optional rebuild on approval
  (`providers.rebuild`: Cloudflare Deploy Hook or GitHub `repository_dispatch`).
- Stripe checkout for priced tiers, a signed webhook that records the payment idempotently, and
  an hourly cron that sweeps unpaid submissions, retries the mail outbox and expires featured
  placements.
- Transactional email through Resend, Cloudflare Email Sending or a console provider, every
  message rendered into an `email_outbox` table first so nothing is lost to a failed send.
- Outbound click counting at `/out/<id>/` — `<a ping>` by default, so the listed site keeps the
  link it was sold — and self-hosted newsletter capture into D1.
- A D1 schema with drizzle-kit migrations, a build-time D1 REST loader (`LISTINGS_SOURCE=d1`),
  and seed/export scripts in both directions between Markdown and the database.
- `pnpm db:seed --with-images` stores the dataset's own logos in your R2 bucket — an absolute
  `https://` URL in the frontmatter is downloaded, a `/logos/` file is uploaded — and
  `--with-favicons` fetches the icon each remaining site publishes about itself, so moving from
  Markdown to D1 does not lose a picture the Markdown named. A `favicon.ico` is decoded to the
  PNG of its largest frame, in plain TypeScript, so most entries come back with a picture; sites
  that block crawlers keep the initial-letter tile. Every object carries a five-minute
  `cache-control`, so a re-seed shows within minutes and needs no cache purge.

**SEO**
- Programmatic SEO pages from two configurable patterns (`best-category-for-tag`,
  `name-alternatives`), with a thin-content guard, a page cap, and per-page copy overrides from
  `src/content/pseo/`. The demo data generates 211 of them.
- Open-graph images rendered at build time with satori + resvg, one per listing and category,
  in your theme's colours; plus a regenerable static fallback (`pnpm og:default`).
- Chunked sitemap, `robots.txt`, canonical URLs, JSON-LD (breadcrumbs, item lists, organization,
  and a listing type chosen from `site.kind`), and a `noindex` rule for thin taxonomy pages.
- A build-time SEO report that counts inbound internal links per listing and can **fail the
  build** on orphans (`seo.strictLinks`).

**Configuration and theming**
- `site.config.ts` as the single configuration surface, zod-validated with ten cross-field
  rules, every error reported as `site.config.ts › path: message`.
- Three theme presets (`default`, `warm`, `mono`), 14 CSS tokens overridable from the config,
  dark mode with a no-flash bootstrap, and self-hosted web fonts via Astro's font pipeline.

**Tooling**
- `pnpm check:config` — validate the config and estimate the static-file budget before building.
- `pnpm content:reset` / `content:use` / `content:check` — swap between the demo dataset and
  examples generated from your own categories.
- `pnpm listings:import` — CSV or JSON to Markdown, with column aliases, `--map` overrides and a
  `--dry-run` that reports every bad row at once.
- A static-file budget check that warns at 80% and fails the build at 90% of the Cloudflare plan
  limit, so an over-size version is stopped locally rather than rejected at deploy.
- 857 unit tests (`pnpm test`), 379 more inside workerd against a real D1 (`pnpm test:workers`),
  30 Playwright tests over the built site (`pnpm test:e2e`), and a Lighthouse CI config that
  audits one page per template from your own route manifest (`pnpm lhci`), asserting ≥ 0.95 in
  all four categories.

**Deployment**
- Static output to Cloudflare Workers assets. `pnpm deploy` builds and uploads. A Worker script
  rides along for the on-demand routes and the hourly cron, but ships with no `DB` or `MEDIA`
  binding and no secrets: with the default flags nothing reaches it, and a first deploy
  provisions nothing.

### Shipped switched off

Built and tested, off by default. Each needs something this repository cannot carry for you:

- **Submissions and the admin queue** (`features.submissions`) — a D1 database, the `DB`
  binding, and `pnpm db:migrate:remote`.
- **Payments** (`features.payments` + `providers.payment: 'stripe'` + the priced tiers
  `enabled`) — `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET`. Cross-rule 3 requires all of
  them together, so a priced tier cannot be enabled with payments off.
- **Self-hosted newsletter** (`features.newsletter: 'd1'`) — the same `DB` binding.
  `features.newsletter: 'embed'` needs nothing but your provider's HTML.
- **Rebuild on approval** (`providers.rebuild`) — a Deploy Hook URL, or a GitHub token and
  repo. With `'none'`, approved listings go live on your next `pnpm deploy`.
- **D1 as the build's data source** (`LISTINGS_SOURCE=d1`) — `CLOUDFLARE_ACCOUNT_ID`,
  `D1_DATABASE_ID` and a D1 Read token. Until then the build reads `src/content/listings/`.
- **Transactional email** (`providers.email: 'resend'`) — `RESEND_API_KEY` and a verified
  sending domain. Without it every message still renders, into the log and `email_outbox`.

### Known limitations

- **Firefox does not send `<a ping>` at all**, so `features.clicks: 'ping'` undercounts its
  visitors; `'redirect'` counts them all at the cost of the link equity.
- **A local build's OG images carry no logo.** They link logos through the `/media/` route,
  i.e. the local bucket, which the build cannot read; a production build fetches them from
  `media.baseUrl` as before.
- `listing.screenshotMax` and `limits.screenshotMaxBytes` validate but nothing reads them:
  every entry in a listing's `screenshots` array renders, and nothing in the app uploads one.

### Requirements

Node 24 (`.nvmrc`), pnpm 10.12.4 (`packageManager`), Astro 7.3.1, wrangler 4.131.1.

## Related

- [Updates](https://zerodirs.com/docs/about/updates/): how to pull a release into a customised copy.
- [What you are buying](https://zerodirs.com/docs/start/what-you-get/): the product the versions above describe.
