Apply the oss-init conventions and keep Pages permissions off PR builds

.claude/rules/architecture.md

@@ -7,7 +7,7 @@ paths: "app/**/*.{ts,tsx}, scripts/**/*.ts, vite.config.ts"
 ## Directory Structure
 
 ```
-documents/
+probitas-test.github.io/
 ├── app/                         # Application source
 │   ├── server.ts                # HonoX entry point
 │   ├── client.ts                # Client-side JavaScript (bundled by Vite)
@@ -53,6 +53,8 @@ documents/
 ├── scripts/                     # Build and generation scripts
 │   ├── post-build.js            # Pagefind indexing & llms.txt.html→llms.txt rename
 │   └── generate-api-docs.ts     # Generate API docs from the npm packages
+├── flake.nix                    # Nix development shell
+├── justfile                     # Task recipes (`just ci` is the quality gate)
 ├── package.json                 # npm dependencies
 ├── vite.config.ts               # Vite + HonoX SSG configuration
 └── tsconfig.json                # TypeScript configuration

.envrc.sample

@@ -1 +1,2 @@
+# Copy to .envrc and run `direnv allow` to enter the Nix dev shell automatically.
 use flake

.gitattributes

@@ -0,0 +1,3 @@
+# Check text out with LF on every OS, so a Windows checkout builds and tests
+# the same bytes as the others.
+* text=auto eol=lf

.github/workflows/deploy.yml

@@ -7,49 +7,63 @@ on:
   pull_request:
   workflow_dispatch:
 
-# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
-  pages: write
-  id-token: write
-
-# Allow only one concurrent deployment
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
 
 jobs:
-  build:
+  ci:
     runs-on: ubuntu-latest
+    # A pull request only needs its latest commit checked. A run on main waits
+    # for the one before it instead of cancelling it, so each one finishes.
+    concurrency:
+      group: ci-${{ github.ref }}
+      cancel-in-progress: ${{ github.event_name == 'pull_request' }}
     steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v7
         with:
-          node-version: lts/*
-          cache: npm
-
-      - run: npm ci
-
-      - run: npm run build
-
-      - run: npm test
-
-      # Upload artifact for GitHub Pages
+          persist-credentials: false
+      - uses: cachix/install-nix-action@v31
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+      # The store the development shell comes from. Only an exact match is
+      # restored, and only main saves, so pull requests cannot evict the
+      # caches each other start from.
+      - uses: nix-community/cache-nix-action@v7
+        with:
+          primary-key: nix-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('flake.nix', 'flake.lock') }}
+          save: ${{ github.ref == 'refs/heads/main' }}
+      # Load the development shell (flake.nix) into the job.
+      - uses: nicknovitski/nix-develop@v1
+      # The same gate as local development (justfile).
+      - run: just ci
+        env:
+          CI: "1"
       - name: Upload artifact
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: ./dist
+          # Keep dist/.vite in the artifact as earlier versions of this action
+          # did; v4 started dropping dotfiles by default.
+          include-hidden-files: true
 
   deploy:
     if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-    needs: build
+    needs: ci
     runs-on: ubuntu-latest
+    # Deployments queue up and never cancel each other.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.gitignore

@@ -4,3 +4,7 @@
 .playwright-mcp
 dist/
 node_modules/
+/.envrc
+.direnv/
+result
+/.claude/worktrees/

AGENTS.md

@@ -0,0 +1,90 @@
+# probitas-test.github.io
+
+Documentation site for [Probitas](https://github.com/probitas-test/probitas) - a
+scenario-based testing framework shipped as a single binary.
+
+- **Runtime**: Node.js + HonoX + Vite SSG
+- **API reference**: TypeDoc JSON generated from the npm packages
+- **Deploy**: GitHub Pages, from `main`
+
+## How it is built
+
+- **Test first.** Red → green → refactor. Write the failing test before the
+  code that makes it pass.
+- **Each layer holds one thing.** Put a fact in the one layer that owns it,
+  and nowhere else.
+
+  | Layer | Holds |
+  | --- | --- |
+  | Tests | the details that pin the behaviour down: rules, boundaries, tables |
+  | Code | how it is done |
+  | Commits | why a change was made |
+  | Comments | why it is not done another way |
+
+- **Dependencies are current.** Before adding or bumping one, look up its
+  latest release in the registry. Do not copy a version from memory or from
+  another repository.
+
+Site structure, routes and the build pipeline are described in
+[`.claude/rules/architecture.md`](.claude/rules/architecture.md); writing
+guidelines for the pages under `docs/` in
+[`.claude/rules/content.md`](.claude/rules/content.md).
+
+## Commands
+
+Run `nix develop` (or use direnv with `.envrc.sample`) first so every tool is
+on PATH, then:
+
+```bash
+just install       # npm ci
+just dev           # Dev server with HMR
+just build         # Build static site (client + SSG + Pagefind)
+just preview       # Preview production build
+just test          # Check internal links in the built site
+just generate-api  # Regenerate data/api/ from the npm packages
+```
+
+## Quality gate
+
+Run `just ci` before reporting a change as done. CI runs the same recipe.
+
+## Reference Probitas packages
+
+When referencing the Probitas API:
+
+- Scenarios import from `@probitas-test/probitas` (npm); the JSR mirror is
+  `@probitas/probitas`
+- `data/api/{package}.json` holds the generated TypeDoc JSON of each package
+- Check `../probitas/` for the user-facing package and CLI source
+- Check `../probitas-packages/` for framework and client package source
+
+## Layout
+
+| Path | What lives there |
+| --- | --- |
+| `app/` | HonoX routes, templates, components and libraries |
+| `data/` | page configuration, home page examples, generated API JSON |
+| `docs/` | Markdown source of the documentation pages (site content) |
+| `public/` | static assets copied into the site |
+| `scripts/` | post-build step and the API reference generator |
+| `tests/` | link check of the built site |
+| `probitas/` | Probitas scenarios checking a served site (`DOCS_BASE_URL`) |
+| `.github/` | CI and the GitHub Pages deployment |
+
+## Language
+
+- README, docs and commit messages: English
+- Code comments, log and error messages: English
+
+## Commits
+
+[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), as
+described in [`.gitmessage`](.gitmessage) (install it with
+`git config commit.template .gitmessage`):
+
+```
+<type>[optional scope]: <description>
+```
+
+- Types: `feat`, `fix`, `deps`, `refactor`, `test`, `docs`, `style`, `chore`.
+- Scopes name the area touched, such as `api`, `ci`, `scripts`, `search`.

README.md

@@ -20,11 +20,14 @@ scenario-based testing framework shipped as a single binary.
 git clone https://github.com/probitas-test/probitas-test.github.io.git
 cd probitas-test.github.io
 
+# Enter the development shell (Node.js, Pagefind, just)
+nix develop
+
 # Install dependencies
-npm ci
+just install
 
 # Start development server
-npm run dev
+just dev
 ```
 
 ## Commands
@@ -36,6 +39,7 @@ npm run dev
 | `npm run preview`      | Preview built site                                   |
 | `npm test`             | Check internal links in the built site               |
 | `npm run generate-api` | Regenerate API documentation JSON                    |
+| `just ci`              | Everything CI checks (Nix format, build, link check) |
 
 ## Project Structure
 
@@ -71,7 +75,8 @@ npm run dev
 
 ### Prerequisites
 
-- [Node.js](https://nodejs.org/) (LTS)
+- [Nix](https://nixos.org/) with flakes enabled; `nix develop` provides Node.js,
+  Pagefind and [just](https://just.systems/). Without Nix, install Node.js 24.
 
 ### Regenerating API Documentation
 
@@ -105,7 +110,7 @@ The `npm run build` command performs the following steps:
 This site is deployed to **GitHub Pages** via GitHub Actions.
 
 1. Push to `main` branch
-2. GitHub Actions runs `npm run build`
+2. GitHub Actions runs `just ci`, which builds the site and checks its links
 3. Static files in `dist/` are deployed to GitHub Pages
 
 Live site: https://probitas-test.github.io/