Simplify docs and add CI workflow for build validation

.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: Build
+
+# Validates the build on every push, any branch. Deploying to Pages (main
+# only) is pages.yml's job, not this one.
+on:
+  push:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  packages: read # lets GITHUB_TOKEN read @astrelitehq/localgrid below
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: '24'
+
+      - name: Install dependencies
+        run: npm install
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build
+        run: npm run build

.github/workflows/pages.yml

@@ -1,20 +1,14 @@
 name: Deploy to GitHub Pages
 
 on:
-  # Fired by localgrid.dev's release-please.yml (notify-proxy job) once a
-  # new @astrelitehq/localgrid version is published, via repository_dispatch
-  # over the GitHub API (a plain push/release trigger can't reach across
-  # repos). client_payload.tag_name is informational only, it's not pinned
-  # into the install below: `npm install` always pulls whatever version
-  # satisfies package.json's range, which is what "the latest release" means
-  # here.
+  # Fired by localgrid.dev's release-please.yml after a new package version
+  # is published (repository_dispatch, since a cross-repo trigger can't
+  # work any other way).
   repository_dispatch:
     types: [localgrid-release]
   # Rebuild on this repo's own commits, not just localgrid releases.
   push:
     branches: [main]
-  # Manual re-run, e.g. after bumping the @astrelitehq/localgrid version
-  # range in package.json or editing this workflow.
   workflow_dispatch: {}
 
 permissions:
@@ -35,23 +29,16 @@ jobs:
 
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: '20'
-          # No npm cache here: there's no committed package-lock.json yet
-          # (see .gitignore), so there's nothing for setup-node to key the
-          # cache on. Switch this back on once a lockfile is committed.
+          node-version: '24' # matches @types/node's ^24.x range below
+          # No npm cache: no committed package-lock.json yet (see .gitignore).
 
       - name: Install dependencies
-        # npm ci needs a committed lockfile, which this repo doesn't have
-        # yet (see .gitignore). Switch back to `npm ci` once one exists.
-        run: npm install
+        run: npm install # switch to `npm ci` once a lockfile is committed
         env:
           NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} # granted via the package's Actions access settings
 
       - name: Build
-        # Builds @astrelitehq/localgrid's own source (installed into
-        # node_modules) with its base path set to this repo's github.io
-        # subpath, then copies the result to ./dist. See the "build" script
-        # in package.json.
+        # Builds @astrelitehq/localgrid's source with this repo's base path.
         run: npm run build
 
       - name: Upload build artifact

AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+localgrid.proxy mirrors [localgrid.dev](https://github.com/AstreliteHQ/localgrid.dev) to GitHub Pages at a different base path. No app source here: it installs the published `@astrelitehq/localgrid` npm package and builds that.
+
+## Important instructions
+
+- No em dash (—) or en dash (–) as punctuation. Use a comma, period, or parentheses instead.
+- Avoid these words and phrases: delve, leverage, seamless, seamlessly, boilerplate, furthermore, moreover, "in today's world", "it's not just X, it's Y".
+- No emoji unless the user explicitly asks for them.
+
+## Commands
+
+- `npm run dev` start the dev server
+- `npm run build` build with this repo's base path, output in `dist/`
+
+## Commit and pull request
+
+- Use conventional commit message pattern
+- Do not commit or open pull requests without explicit instruction

README.md

@@ -1,63 +1,40 @@
 # localgrid.proxy
 
-A GitHub Pages (`github.io`) mirror of [localgrid.dev](https://github.com/AstreliteHQ/localgrid.dev).
-
-localgrid.dev deploys behind its own custom domain. This repo exists so the
-app is also reachable at `astrelitehq.github.io/localgrid.proxy/`, without
-touching that custom-domain deployment. It doesn't contain any app source of
-its own: it installs the [`@astrelitehq/localgrid`](https://github.com/AstreliteHQ/localgrid.dev/pkgs/npm/localgrid)
-npm package (published to GitHub Packages on every localgrid.dev release) and
-builds *that* package's own source, with the Vite base path overridden to
-`/localgrid.proxy/` instead of localgrid.dev's default `/`. The base path is
-baked into the built assets at build time, so this is the only difference
-between the two deployments.
-
-## How it stays up to date
-
-localgrid.dev's release workflow sends a `repository_dispatch` event to this
-repo after it publishes a new `@astrelitehq/localgrid` version, which
-triggers [`pages.yml`](.github/workflows/pages.yml) here to reinstall
-(picking up the new version) and redeploy. It can also be run manually from
-the Actions tab (`workflow_dispatch`).
-
-## One-time manual setup
-
-A few things can't be done from code and need to happen once in each repo's
-settings:
-
-- **GitHub Pages source**: in this repo's Settings → Pages, set the source
-  to "GitHub Actions".
-- **`PACKAGES_READ_TOKEN` secret** (in this repo): a personal access token
-  with `read:packages` scope (classic) or Packages: Read (fine-grained) on
-  the AstreliteHQ org, so `npm install` can pull `@astrelitehq/localgrid`
-  from GitHub Packages. Add it under Settings → Secrets and variables →
-  Actions.
-- **`PROXY_DISPATCH_TOKEN` secret** (in localgrid.dev, not here): a PAT with
-  `repo` scope (classic) or Contents: Read + Actions: Write (fine-grained)
-  on this repo, so localgrid.dev's release workflow can dispatch the deploy
-  above. See the `notify-proxy` job in localgrid.dev's
-  `.github/workflows/release-please.yml`.
-
-A single fine-grained PAT scoped to both repos (Packages: Read on
-localgrid.dev, Contents: Read + Actions: Write on localgrid.proxy) can back
-both secrets if you'd rather manage one token than two.
+Mirrors [localgrid.dev](https://github.com/AstreliteHQ/localgrid.dev) to
+`astrelitehq.github.io/localgrid.proxy/`, alongside its custom-domain
+deployment. No app source lives here: it installs the
+[`@astrelitehq/localgrid`](https://github.com/AstreliteHQ/localgrid.dev/pkgs/npm/localgrid)
+npm package and builds *that* package's source with a different Vite base
+path baked in.
+
+## Staying up to date
+
+localgrid.dev's release workflow dispatches a rebuild here on every new
+package version. Also rebuilds on push to `main`, or manually via
+`workflow_dispatch`. `ci.yml` builds (not deploys) on every push, any
+branch, to catch a broken build before it reaches `main`.
+
+## Extra devDependencies
+
+`vitest`, Testing Library, and `@types/spark-md5` are devDependencies here
+even though this repo has no tests. `@astrelitehq/localgrid`'s own build
+(`tsc -b`) type-checks its whole source tree, tests included, but the
+published package doesn't ship its devDependencies. Listing the same ones
+here lets npm's hoisted `node_modules` satisfy that type-check. Keep their
+versions in sync with localgrid.dev's own `package.json`.
 
 ## Lockfile
 
-`package-lock.json` isn't committed yet (see `.gitignore`): generating one
-requires resolving `@astrelitehq/localgrid` from GitHub Packages, which
-needs the same `read:packages`-scoped credentials as above. Once you have
-those locally (`export NODE_AUTH_TOKEN=...` with a PAT that has
-`read:packages`), run `npm install`, commit the generated
-`package-lock.json`, remove it from `.gitignore`, and switch
-[`pages.yml`](.github/workflows/pages.yml) from `npm install` back to
-`npm ci` for reproducible installs.
+Not committed yet (see `.gitignore`); generating one needs
+`read:packages` credentials to resolve `@astrelitehq/localgrid`. Once you
+have one, run `npm install`, commit `package-lock.json`, and switch
+`pages.yml` to `npm ci`.
 
 ## Local development
 
 ```bash
 export NODE_AUTH_TOKEN=<a PAT with read:packages on AstreliteHQ>
 npm install
-npm run dev      # dev server, base path defaults to /
-npm run build    # production build at /localgrid.proxy/, output in ./dist
+npm run dev      # base path defaults to /
+npm run build    # production build at /localgrid.proxy/
 ```

package.json

@@ -13,13 +13,18 @@
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/jest-dom": "^7.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.3",
     "@types/node": "^24.13.3",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
+    "@types/spark-md5": "^3.0.5",
     "@vitejs/plugin-react": "^6.0.4",
     "tailwindcss": "^4.3.3",
     "typescript": "~6.0.2",
     "vite": "^8.2.0",
-    "vite-plugin-pwa": "^1.3.0"
+    "vite-plugin-pwa": "^1.3.0",
+    "vitest": "^4.1.10"
   }
 }