Refreshing the docs

As PulseAd’s source repos get new commits, these docs go stale. Refreshing them re-reads the source and rewrites only the pages whose source actually changed — everything else is left untouched.

The one-command way

In Claude Code, from the repo root:

/sync-docs

That command runs the whole procedure below, shows you a diff summary first, and opens a pull request. If nothing changed under any page’s source, it tells you and stops. You almost never need the manual steps — they’re here so you know what /sync-docs is doing.

What it does, step by step

1. Pull the latest source

Clone or fetch every source repo into .sources/ (gitignored — never committed):

mkdir -p .sources
for r in ai-api pulsy-frontend pulsead-agents \
         snowflake-semantic-agent data_semanticview off-amazon-upload \
         aop-hermes banana-bunch ads-variation video-generator; do
  if [ -d ".sources/$r" ]; then git -C ".sources/$r" fetch --quiet origin;
  else gh repo clone "PulseAd/$r" ".sources/$r"; fi
done

(The authoritative repo + branch list is sync/manifest.json → sources.)

2. Read the pinned commits

Each source has a syncedCommit in sync/manifest.json — the commit the docs were last generated from.

3. Diff each repo from its pin to live HEAD

For every source, list what changed since the pin, and note the new HEAD SHA:

git -C .sources/ai-api diff --name-only <syncedCommit>..origin/develop

4. Map changed files → affected pages

Each page in the manifest lists derivedFrom entries like "<source>:<path-prefix>". A changed file affects a page when its path starts with that prefix. If nothing changed under a page’s derivedFrom, that page is left alone.

5. Regenerate only the affected pages — both locales

Rewrite each affected page following the writing rules in AGENTS.md (lead with the model; verify against code, not stale internal docs; only code-verifiable gotchas; placeholders only, never real brands). Update both the English page and its Korean mirror under /ko/. Anything the code can’t answer goes to _internal/needs-johnny.md instead of being guessed.

6. Bump the pins

Set each touched source’s syncedCommit to its live HEAD SHA, update lastSyncedAt, and set each regenerated page’s status to synced.

7. Verify

npm run build       # the site builds
npm run freshness   # every page has provenance; no broken links

8. Open a PR

Commit on a branch and open a pull request. Do not push to main.

When to run it

• After a meaningful release or merge in any source repo.
• Before sharing the docs with a new audience (partners, investors).
• On a regular cadence (e.g. weekly) to catch drift.

To see how stale things are right now, check lastSyncedAt and each sources.<name>.syncedCommit in sync/manifest.json against the repos’ live HEADs.

Automation (optional)

Today the refresh is run on demand (a person triggers /sync-docs). It can be scheduled — e.g. a job that runs the diff in step 3 and opens a PR only when a page’s source changed — so refreshes happen automatically as commits land. That isn’t set up yet; ask if you’d like it wired up.