A chapter-neutral organizing-site kit for a Progress Now chapter: one WordPress theme that owns content, SEO and editing, and three interchangeable frontends for the public site — the server-rendered PHP theme itself, a Nuxt 4 static rendition that takes over from a PHP shell, and a headless Next.js app on its own origin. An install picks one; the CMS, the REST API and the contracts are the same for all three. Everything that names or pictures a chapter is data in wp-admin; everything shipped in the repo is a generic placeholder.

Bilingual (EN at /, ES at /es/…), accessible (WCAG 2.2 AA target, built-in text-size / high-contrast / reduced-motion controls), no analytics, no third-party trackers.

⚠️ This codebase was written almost entirely by AI. Every line was produced with Claude Code using Claude Fable 5.1 and Claude Opus 5, prompted and reviewed by one person. It is a vibe-coded app. Assume hallucinations exist: APIs that don't quite exist, tests that assert the wrong thing, docs that describe code that was never written, security assumptions nobody checked. Read the Contributing section before you trust it, and open a PR when you find something. Human or AI-authored fixes are equally welcome.

This repository is a fresh start. The code was developed 2026-05 → 2026-09 as a single-chapter site, then renamed, made chapter-neutral and re-platformed onto Nuxt 4. The design and decision history lives in openspec/ (see History); the original git history is not carried over.

• What you get
• Frontends: pick one
• Architecture
• Repository layout
• Documentation
• Requirements
• Local development
• Configuration
• Deployment
• Content model
• REST API
• Design system
• Testing
• OpenSpec workflow
• History
• Roadmap
• Contributing
• License

Run one JS frontend per install. Both JS apps read GET /wp-json/progressnow/v1/*, share the theme's zod contracts, Tailwind tokens and category registry by drift test, and reproduce every route in both languages.

                    ┌─────────────────────────────────────────────┐
  visitor ───────►  │  WordPress + Timber (wp-content/themes/      │
  (every URL)       │  progressnow)                                │
                    │  • full SEO head (inc/seo.php)               │
                    │  • crawlable header/content/footer in #__nuxt│
                    │  • __SHELL_DATA__ route payload (payloads.php)│
                    │  • <script>/<link> tags from shell-manifest  │
                    └───────────────┬─────────────────────────────┘
                                    │ mounts into #__nuxt
                    ┌───────────────▼─────────────────────────────┐
                    │  Nuxt 4 client (nuxt-js/)                       │
                    │  1. landing route from __SHELL_DATA__        │
                    │  2. later navigations from prerendered       │
                    │     …/_payload.json                          │
                    │  3. REST fallback for search/filter/calendar │
                    │     and while a rebuild is in flight         │
                    └─────────────────────────────────────────────┘

  editor saves ─► content version bump ─► inc/rebuild.php (debounce 90 s)
     ─► GitHub repository_dispatch | signed webhook
     ─► `nuxt generate` from GET /wp-json/progressnow/v1/*
     ─► rsync | S3 (manifest uploaded last) ─► POST /build-status ─► cache purge

  ── headless alternative (next-js/) ──────────────────────────────────────────
  visitor ───────►  Next.js (own origin, SSR from cached progressnow/v1 envelopes)
  editor saves ─► content version bump ─► signed webhook ─► POST /api/rebuild
     ─► revalidate cache tags ─► (optional) POST /build-status ─► WordPress marks live

Key properties:

• PHP first, always. Crawlers, deep links and no-JS users get a complete page from WordPress. The app is an enhancement, never a dependency for content.
• Static by default, fresh by guard. A freshness guard compares the shell's contentVersion with the static build's; if the build is stale the session stays on REST until the next build lands.
• Nothing runs node on the WordPress host. Builds run in GitHub Actions (or any webhook receiver).
• One contract. schemas.ts (zod) defines every payload shape; PHP serializers and TS consumers are held to it by committed JSON fixtures asserted from both sides.
• Three frontends, one CMS. CHAPTER_FRONTEND selects islands (the PHP theme with its Vite-built Vue islands — the PHP-only frontend, kept permanently) or nuxt (the shell handoff above); the headless next-js/ app needs no flag — it runs elsewhere and WordPress only points its canonical origin and rebuild webhook at it. Switching back is a constant flip.

.
├── wp-content/themes/progressnow/   WordPress theme (Timber 2 / Twig, ACF Pro, Polylang Pro)
│   ├── inc/            one PHP file per domain (see Content model)
│   ├── views/          Twig templates + partials (Twig twins of the Vue components)
│   ├── blocks/         six progressnow/* ACF blocks (block.json + render.php)
│   ├── page-templates/ about, get-involved, calendar, styleguide
│   ├── src/            shared Vue/TS/Tailwind source (copied into nuxt-js/app — see Design system)
│   ├── static/         self-hosted fonts, brand placeholders, artwork
│   ├── bin/            seed.php, migrate-post-blocks.php, worktree-bootstrap.sh
│   ├── tests/          PHPUnit (WorDBless) + vitest, contract fixtures
│   ├── categories.json canonical category registry (slugs, labels, colors)
│   └── README.md       deep theme documentation
├── nuxt-js/             Nuxt 4 static rendition (see nuxt-js/README.md)
│   ├── app/            lib/chapter data layer, composables, plugins, routes, shared components
│   ├── modules/        routes-manifest, shell-manifest
│   ├── shared/         fixture-backed mock API
│   └── test/unit       contracts, resolver, shell/freshness/cache, drift tests
├── next-js/             headless Next.js frontend (see next-js/README.md)
│   ├── app/            App Router: catch-all route, api/rebuild, api/health, api/events
│   ├── components/     site components (React), shadcn/ui, a11y provider
│   ├── lib/            schemas (drift-guarded copy), api, data cache, routes, links, signing, security headers
│   ├── test/           unit + component (Vitest/RTL/jest-axe), mock API, Playwright e2e + axe-core
│   └── Dockerfile      standalone image (node:22-alpine, non-root, HEALTHCHECK)
├── docs/
│   ├── deployment.md            operator guide: constants, GitHub config, same-host vs CDN, headless Next.js (§10), cutover, rollback
│   ├── security-gates.md        CI security gates (PHPCS sniffs, gitleaks, artifact guard), the theme's headers + CSP rollout
│   └── accessibility-statement.md  EN/ES base text for the public Accessibility page
├── infra/terraform/     reference S3 + CloudFront + GitHub OIDC module (optional)
├── openspec/            specs (current behavior) + changes (proposals, designs, tasks)
├── LICENSE
└── wp-config-sample.php

WordPress core, wp-config.php, uploads, wp-content/plugins/, build output (nuxt-js/dist, nuxt-js/.output, theme dist/), node_modules/, vendor/ and the synced static-site/ are all git-ignored. Plugins are installed by the adopter, never vendored.

One document owns each topic. Every other document keeps at most a sentence and a link to the owner — never a copy of its paragraphs.

| AI session handoffs and agent configuration | untracked — .claude/ is gitignored, and nothing from a session is committed |

The docs CI job (.github/workflows/docs.yml, scripts/docs/) keeps this honest: the Roadmap and Capabilities sections below are rendered from openspec/ and fail when stale; every backticked repository path and every relative link in the README, docs/, the app READMEs and open change proposals must resolve; and a section duplicated across files fails.

WordPress host

• PHP 8.2+ (Timber 2.5's floor; CI runs 8.2 and 8.4), WordPress 6.x, pretty permalinks enabled
• Composer (for the theme's vendor/: Timber 2, kucrut/vite-for-wp)
• Plugins: ACF Pro and Polylang Pro (required, licensed). Wordfence and WP Super Cache are optional. Duplicator must not be installed in production.
• WP-CLI (seeding, wp chapter … commands)
• System cron hitting wp-cron.php every minute (DISABLE_WP_CRON on)

Build

• Node 22 and npm — the root .nvmrc pins the major and every app's .npmrc sets engine-strict, so npm ci under another major fails with an engine error (nvm use / fnm use read the file)
• A GitHub repository (default rebuild transport) or any HMAC-verified webhook receiver

# from a local WP install (e.g. MAMP at https://chapter.test:8890) with this repo as the docroot
cp wp-config-sample.php wp-config.php        # fill in DB + salts
cd wp-content/themes/progressnow
composer install
npm install

Activate the Progress Now theme, install/activate ACF Pro and Polylang Pro, configure Polylang (EN en_US default + ES es_MX; language in directory, default hidden), set Settings → General → Timezone to your city (event times, calendar links, and the ICS feed follow it — the theme has no built-in zone), then seed:

wp eval-file wp-content/themes/progressnow/bin/seed.php

The seed is idempotent: categories + colors, 14 placeholder events, lorem posts covering every block type, menus, Chapter Settings, interior documents, the Spanish page pairs and string translations. Spanish pages are written on create only. Islands mode (the default — CHAPTER_FRONTEND unset or islands) needs nothing more: npm run dev in the theme for the Vite dev server with HMR. Every theme command, the MAMP seeding invocation and the Polylang details: theme README.

cd nuxt-js
cp .env.example .env    # NUXT_DEV_WP_ORIGIN, NUXT_PUBLIC_WP_API_BASE (…/wp-json/progressnow/v1)
npm install
npm run dev             # nuxt dev, proxies /wp-json + /wp-content to the local WordPress

Every command (generate, generate:mock, verify:output, lint / typecheck / test), local TLS and the Vercel setup: nuxt-js/README.md. The full handoff locally — npm run generate, then CHAPTER_FRONTEND=nuxt and CHAPTER_STATIC_DIR in wp-config.php — is docs/deployment.md §9.

cd next-js
cp .env.example .env.local   # WP_API_BASE (…/wp-json/progressnow/v1), NEXT_PUBLIC_SITE_ORIGIN, CHAPTER_REBUILD_SECRET
npm install
npm run dev                  # against the local WordPress; `npm run dev:mock` needs no WordPress

Every command, the environment contract and the test layers: next-js/README.md. The WordPress-side constants for the full loop (CHAPTER_REBUILD_TRANSPORT=webhook, the webhook URL, the shared secret, CHAPTER_CANONICAL_ORIGIN): docs/deployment.md §10.8.

Working in a git worktree? bin/worktree-bootstrap.sh /path/to/full-checkout symlinks the untracked WordPress runtime into it (shares the database, snapshot first).

All operator settings are wp-config.php constants — or environment variables of the same name, which win (an empty value counts as unset), so a host with a secret manager never writes a secret into a PHP file. The Site build panel reports each setting's source, never its value. The reference for every CHAPTER_* constant, precedence and secret strength is docs/deployment.md §2 (§10.3 for the headless ones). The ones that pick a frontend: CHAPTER_FRONTEND (islands default, or nuxt), CHAPTER_REBUILD_TRANSPORT (webhook recommended; github only through a dispatch repository, docs/rebuild-dispatch-repo.md; none), CHAPTER_REBUILD_SECRET (≥ 32 characters; rotation in docs/secrets-rotation.md) and, for a headless frontend, CHAPTER_CANONICAL_ORIGIN. Set DISALLOW_UNFILTERED_HTML to true as well — the theme denies the capability for every role regardless (docs/authoring-trust-model.md).

Everything chapter-specific (name, short name, region label, headline, logos, hero photo, socials, newsletter URL, contact email, committees, footer tagline…) lives in Chapter Settings in wp-admin, with generic placeholder fallbacks. Social and newsletter URLs have no default; the UI that needs them renders only when they are set.

Three supported shapes, all documented step by step in docs/deployment.md:

1. Same-host (STATIC_DEPLOY_TARGET=rsync): the workflow syncs the build into CHAPTER_STATIC_DIR on the WordPress host. Apache/nginx rules serve the static paths directly; PHP passthrough is the fallback.
2. CDN (STATIC_DEPLOY_TARGET=s3): infra/terraform/ provisions a private versioned bucket, a CloudFront distribution (static paths → S3, everything else → WordPress honoring origin cache headers, optional 5xx failover to prerendered HTML) and a GitHub OIDC role.
3. Webhook: WordPress POSTs a signed { event: "rebuild", … } to any receiver (e.g. API Gateway → CodeBuild) that runs npm ci --ignore-scripts && npx nuxt prepare && npm run generate, syncs, and reports back with the same signed POST /build-status.
4. Headless Next.js (next-js/): deploy the standalone build (Vercel, the Dockerfile, or a VPS behind a reverse proxy) and point the same signed webhook at <next-origin>/api/rebuild; the receiver revalidates its cache and reports back with POST /build-status. Set CHAPTER_CANONICAL_ORIGIN to the Next origin. docs/deployment.md §10; node scripts/smoke.mjs <origin> after each deploy.

The rebuild workflow (.github/workflows/rebuild-site.yml) listens for repository_dispatch (rebuild-site), workflow_dispatch, and pushes to main touching nuxt-js/, with concurrency: rebuild-site so bursts of edits collapse into one build. Repository variables/secrets: WP_API_BASE, STATIC_DEPLOY_TARGET, WP_BUILD_STATUS_URL, CHAPTER_REBUILD_SECRET, plus rsync or S3 credentials. Content-driven rebuilds reach it through the signed webhook or a dispatch repository that checks this one out read-only: the token WordPress holds never has write access here (docs/rebuild-dispatch-repo.md; rotation of every pipeline credential in docs/secrets-rotation.md).

Cutover (§7): activate theme → seed → set constants with CHAPTER_FRONTEND=islands → trigger a build → verify shell-manifest.json → flip to nuxt → watch the Site build panel (scheduled → requested → building → live). Rollback (§8): flip CHAPTER_FRONTEND back, or restore a prior manifest from S3 versioning / re-run the workflow.

One PHP file per domain under wp-content/themes/progressnow/inc/:

Rules that hold everywhere:

• Every content area is editable in wp-admin, registered in PHP (never DB-only), and falls back to neutral copy so an empty install renders a complete generic site.
• Category slugs chapter | poled | mutual | labor | electoral | social are load-bearing (URLs, TS types). Rename labels and colors, never slugs.
• Editor HTML is wp_kses-sanitized at serialize time.
• Calendar, About and Get Involved are page templates, not magic slugs.

GET /wp-json/progressnow/v1/*, public, publish-only, GET-only. Handlers reuse the domain serializers, so REST and embedded payloads cannot drift. Routes: /posts (paged, category-filtered, searched), /posts/{slug}, /events (date-windowed), /categories, the /site / /routes / /front / /page/… payloads that nuxt generate reads, and the signed POST /build-status callback. Anonymous responses are HTTP-cached (max-age=300, stale-while-revalidate, ETag/304); logged-in ones are no-store. Additive changes stay on /v1; breaking ones go to /v2. Parameters, bounds and envelopes: theme README § REST API.

v4 "Progress Now" system, one token set in src/css/tailwind.css (Tailwind v4 @theme, role names only):

• Color: brand #1848D8, brand-deep #0F2E9C, accent #0E62E6, brand-light #A9C7FF, alt #F2F5FB, ink #1B1B22, yellow #FFC800, plus muted / line / control / border tokens. No color-named aliases remain (grep-gated).
• Type: Public Sans variable (body), Bowlby One (display, 400 only), Special Season Brush (CTA line). Self-hosted from static/fonts/, preloaded.
• Tones: every band carries data-tone="blue|white|alt|ink"; the high-contrast mode recolors by tone and flips focus rings on dark tones.
• Radius: 20px cards (18 tablet / 16 mobile), 14px rows, 10–12px pills/tiles, 999 for chips and breadcrumbs.
• Components: shadcn-vue (vendored into src/components/ui/), site components in src/components/site/, styleguide at /styleguide/.

Shared source rule. src/components/site/**, src/components/ui/**, useA11ySettings.ts, schemas.ts and tailwind.css in the theme are copied verbatim into nuxt-js/app/. Edit the theme copy and re-copy; nuxt-js/test/unit/shared-source-drift.test.ts fails on any drift. Twig partials and route components must keep the same class literals as their Vue twins.

Each app's README owns its commands; this is the map. Nothing needs a WordPress instance: the theme runs PHPUnit on WorDBless, nuxt-js generates against its nitro mock, next-js tests against its fixture-backed mock — all fed by the theme's committed contract fixtures (tests/fixtures/*.json, asserted byte-for-byte from PHP and parsed by zod from TS; regenerate them deliberately — theme README § Contract governance).

• Theme — composer test, composer lint, npm test, npm run build, node bin/twig-audit.mjs: theme README § Commands.
• nuxt-js — npm test, npm run typecheck, npm run lint, npm run generate:mock && npm run verify:output: nuxt-js/README.md § Commands.
• next-js — unit + component (Vitest, RTL, jest-axe), Playwright e2e / a11y / failure, the container smoke: next-js/README.md § Checks.
• Repository gates — PHPCS security sniffs, gitleaks and the artifact guard (required on main

  Read the rest on GitHub