Deploy to GitHub Pages (client-only)#

GitHub Pages serves static files only, so this build has no server: the site, the web app and the chat app run entirely in the browser (VITE_CLIENT_ONLY=1). In client-only mode the apps use in-browser speech-to-text and LLMs on local files, or the user's own provider keys (stored in the browser's IndexedDB, never sent anywhere but the provider). Optionally the apps can point at a vid2context API you run elsewhere.

GitHub Actions is unavailable on this account, so publishing is a local script that commits to the gh-pages branch from a temporary git worktree.

Publish#

npm run deploy:pages -- --dry-run                       # build and commit in a throwaway clone; touches nothing
npm run deploy:pages                                    # build and commit to the local gh-pages branch, no push
npm run deploy:pages -- --push                          # ... and push gh-pages to origin
npm run deploy:pages -- --cname pages.vid2context.com --push   # custom domain
npm run deploy:pages -- --api-base https://vid2context.com/api/v1 --push   # apps call a real API

Then, once, in the repository settings: Pages, Build and deployment, Source "Deploy from a branch", branch gh-pages, folder / (root).

Option	Default	Meaning
`--api-base <url>`	empty	`VITE_API_BASE` for the apps; empty means pure client-only
`--cname <domain>`	none	writes `CNAME` and serves from the domain root
`--base-path <path>`	`/` with `--cname`, else `/vid2context/`	URL prefix of the whole tree
`--branch`, `--remote`	`gh-pages`, `origin`	where to commit and push
`--dry-run`	off	do everything in a temporary clone of the repo; never pushes
`--push`	off	push after committing; nothing is pushed without it
`--no-build`	off	reuse existing app `dist/` folders
`--strict`	off	fail when an app is present but does not build

Paths#

Without a custom domain the site lives at https://nirholas.github.io/vid2context/. The script builds the apps with Vite --base /vid2context/app/ (and /chat/) and rewrites the site's root-absolute links (href="/llms.txt") to the prefix. With --cname everything is served from /.

GitHub Pages has no rewrites, so app deep links rely on the apps' query-string URLs (/app/?url=..., /chat/?input=..., as the web contract defines); path-style deep links would hit the site's 404 page.

What the script does#

Builds dist/pages/ with deploy/serverless/lib/assets.mjs (client-only, base path applied), adds .nojekyll (so _-prefixed files are served) and CNAME when asked.
Checks the git identity is nirholas with a noreply address, as AGENTS.md requires.
Adds a temporary worktree for gh-pages (creating an orphan branch the first time, or tracking origin/gh-pages if it exists), replaces its contents with the build, and commits only if something changed.
Pushes only with --push, then removes the worktree. Git commands in the real repo run under the shared lock .vid2context/locks/git.

Limits#

GitHub Pages sites are public, limited to 1 GB, and have a soft bandwidth limit of 100 GB per month. The live API demo on the landing page needs a server, so it does not work on a pure client-only Pages build.