okhp3-vite-github-pages

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

Use this focused runbook to keep the Abrahamic Reference Engine compatible with its client-only Vite build and GitHub Pages Actions deployment. Verify the repository before relying on any remembered version or workflow detail.

Scope

| In scope | Out of scope | | --- | --- | | vite.config.ts, .github/workflows/deploy-pages.yml, production base paths, BrowserRouter, build artifacts, Pages permissions/artifacts, environment wiring, and deployment diagnosis | Servers, databases, backend proxies, gh-pages branches, the legacy npm run deploy, secret creation, commits, pushes, and unrelated application changes |

Project contract

Treat these current facts as constraints, then re-read the files if the task may have changed them:

• vite.config.ts sets base to /abrahamic-reference-engine/ when command === 'build' and / otherwise. The dev server listens on 0.0.0.0:5000.
• src/App.tsx uses BrowserRouter with basename={import.meta.env.BASE_URL.replace(/\/$/, '')}.
• .github/workflows/deploy-pages.yml runs on pushes to main or manual dispatch, uses Pages permissions and concurrency, installs with npm ci, builds with npm run build, copies dist/index.html to dist/404.html, uploads dist, and deploys with the Pages actions.
• No environment variables are passed to the Vite build at this time.

Workflow

1. Plan

Read AGENTS.md, vite.config.ts, .github/workflows/deploy-pages.yml, package.json, src/App.tsx, and the relevant recent diff. Check git status --short. Classify the request as configuration, workflow, artifact, or diagnosis before editing. Do not change deployment settings merely because a validation command succeeds.

2. Validate the source of truth

Confirm the intended repository name, Pages base, router, build script, artifact path, trigger branch, environment variables, permissions, and fallback behavior from the files. If the requested result conflicts with the client-only boundary or the checked-in workflow, stop and report the conflict.

3. Execute safely

Make the smallest compatible edit. Keep the production base exactly /abrahamic-reference-engine/, local development at /, BrowserRouter with basename, npm, and Actions-based Pages deployment. Never place OAuth/API secrets in source, workflow text, or skill output; reference GitHub secrets by name only. Do not create a gh-pages branch or add a server workaround for an SPA that already handles routing via the 404.html fallback.

4. Validate

Run npm run build for build-affecting changes. Inspect the generated dist/index.html for /abrahamic-reference-engine/ asset URLs and confirm the workflow creates dist/404.html after the build. For workflow-only edits, inspect YAML structure and still run the narrowest available checks.

5. Report

Summarize changed files, verified local results, expected Actions behavior, required repository/environment configuration, and unresolved risks. Distinguish a successful local build from a verified live Pages deployment; the latter requires an actual environment smoke test.

Gotchas

• A wrong production base causes asset 404s under the repository subpath; do not “fix” this by changing the router to BrowserRouter.
• A successful Vite build does not prove Pages permissions, secrets, CORS, or deployed behavior are healthy.
• If environment variables are ever added to the Vite build, pass them via GitHub Actions secrets and never print or hard-code their values.
• Preserve npm ci and the checked-in lockfile. Do not switch to pnpm or npm install as a workaround.
• Do not claim dist/404.html exists from a local build unless the copy step was actually run; it is created by the workflow.

Output contract

Return:

1. deployment diagnosis or implementation summary;
2. exact files and invariants preserved;
3. validation commands/results and any blocked checks;
4. required GitHub/Pages environment configuration without secret values;
5. live-verification status and remaining risks.

About

Built by Jamie Hill · OverKill Hill P³ Published at github.com/OKHP3 Part of the OKHP3/skillz Agent Skill library. MIT License -- free to use, fork, and adapt. A nod to the source is appreciated.