How this was made
These docs are a derived artifact. They aren’t written from memory — they’re generated from PulseAd’s live source repositories and pinned to the exact commit each page was produced from. That’s what makes them re-syncable: when the code moves, you re-run the sync and only the affected pages change. (To do that, see Refreshing the docs.)
The idea
Section titled “The idea”- The source repos are the truth for what exists. Endpoints, agents, models, tables, CLI commands — all read from code, not recalled.
- This repo is the truth for the mental model and point of view. It explains how the pieces fit, what to predict, and where the gotchas are.
- Every page records its provenance.
sync/manifest.jsonmaps each page to the source paths it’s derived from and pins the commit it was last generated from. A freshness check (npm run freshness) fails the build if a page has no provenance or a link breaks. - Unverifiable claims don’t get published. Anything the code can’t confirm goes
to
_internal/needs-johnny.mdinstead of being guessed.
The full contract lives in AGENTS.md
at the repo root; this page is the human-readable summary.
What it’s built with
Section titled “What it’s built with”- Astro Starlight — the docs site framework.
- Bilingual — English at
/, Korean mirror under/ko/. - Cloudflare Pages — static hosting.
- The interactive bits (the AI models map) are Astro components; provider logos come from lobe-icons.
The GitHub projects these docs are pulled from
Section titled “The GitHub projects these docs are pulled from”Every page is derived from one or more PulseAd/* repositories. Here’s what each
contributes:
That table is generated from sync/manifest.json
at build time — the repo list, the branches, and the “read by” column are all derived,
so they can’t drift out of date. The manifest also pins the exact commit per repo and
the source paths each page reads.
“Read by” is worth reading carefully. A repo can be tracked here and still be invisible to a given page: coverage is a property of each page↔path pair, not of the repo. That column is how you check.
How to keep it current
Section titled “How to keep it current”Source repos keep moving. When they do, refresh the docs — that page walks through re-running the sync so only the pages whose source changed get rewritten.