Add Gitea Actions CI + switch to PR-based workflow

- Add .gitea/workflows/ci.yml: typecheck -> lint -> unit -> build -> deterministic
  Playwright e2e against the dev webServer (LLM_STUB=1). No dind/docker/static IP.
- package-lock.json is committed (reproducible `npm ci`); verified npm install is a no-op.
- Add CHANGELOG.md, set version 0.1.0, add .env (gitignored) + .env.example placeholder.
- Document the mandatory feature-branch -> PR -> CI -> auto-merge workflow in
  AGENTS.md + README.md (e2e now runs in CI on every PR).
- Add Playwright html/json reporters (playwright-report/, test-results/e2e.json)
  for the CI E2E-results summary step and the failure artifact upload.

.env.example

@@ -0,0 +1,5 @@
+# Copy to `.env` and fill in real values. `.env` is gitignored; never commit secrets.
+
+# Gitea API token (used for PR / branch-protection automation via the Gitea REST API).
+# Get one from: https://git.kkhost.pl/user/settings/applications
+GITEA_TOKEN=gitea-api-token

.gitea/workflows/ci.yml

@@ -0,0 +1,140 @@
+# CI for the History simulator. Mirrors the local verification list in AGENTS.md
+# (typecheck → lint → unit → build) and then runs the deterministic Playwright e2e
+# suite (LLM_STUB=1) against the app's OWN dev webServer (npm run dev) on the runner.
+# No dind / docker-compose / static IP / NO_PROXY needed: history's e2e targets the dev
+# webServer, not a Docker image (unlike flight/orb's image-based e2e). CI never deploys:
+# production is updated manually on the host after a tag.
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  ci:
+    name: build + unit + e2e
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      # Job-level dep cache via the runner's built-in cache server. continue-on-error:
+      # an unreachable/broken cache server must never break the run (sibling convention).
+      # Caches node_modules and npm's tarball store ($HOME/.npm); npm ci wipes
+      # node_modules, so the $HOME/.npm store is what actually makes a cache hit fast.
+      - name: Restore deps cache
+        uses: actions/cache@v4
+        continue-on-error: true
+        with:
+          path: |
+            node_modules
+            $HOME/.npm
+          key: ${{ runner.os }}-deps-npm-${{ hashFiles('package-lock.json') }}
+
+      # Retried: the runner's outbound network/DNS is flaky (transient EAI_AGAIN seen in CI).
+      # npm ci is fully reproducible from the committed package-lock.json.
+      - name: Install dependencies
+        run: |
+          set -u
+          ok=0
+          for i in 1 2 3; do
+            if npm ci; then ok=1; break; fi
+            echo "::warning::dependency install attempt $i/3 failed (likely transient network) — retrying in 5s" >&2
+            sleep 5
+          done
+          [ "$ok" = "1" ] || { echo "::error::dependency install failed after 3 attempts" >&2; exit 1; }
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Lint
+        run: npm run lint
+
+      # Deterministic: the LLM client uses the stub transport (LLM_STUB=1), so no model
+      # or network is needed. vitest auto-appends its summary to $GITHUB_STEP_SUMMARY.
+      - name: Unit tests
+        run: npm test
+
+      # Vite client build → dist/ + tsup server bundle → server/dist/. Verifies the
+      # production build path (docker build does the same thing inside the image).
+      - name: Build
+        run: npm run build
+
+      # Browsers run locally in CI (no remote browser server, no dind). Binaries
+      # (~187 MiB) are cached across runs — the runner's uplink is flaky and
+      # cdn.playwright.dev downloads time out mid-transfer; once seeded, installs skip.
+      - name: Restore browser cache
+        uses: actions/cache@v4
+        continue-on-error: true
+        with:
+          path: $HOME/.cache/ms-playwright
+          key: ${{ runner.os }}-pw-browsers-${{ hashFiles('package.json') }}
+
+      # Retried: cdn.playwright.dev is flaky from this runner — Playwright's internal
+      # retry window is often not enough, but runs get through with a longer one.
+      # Progress accumulates across attempts: playwright skips already-installed browsers.
+      - name: Install browsers (local)
+        run: |
+          set -u
+          ok=0
+          for i in 1 2 3 4 5 6; do
+            if npx playwright install --with-deps chromium; then ok=1; break; fi
+            echo "::warning::browser install attempt $i/6 failed (flaky cdn.playwright.dev) — retrying in 5s" >&2
+            sleep 5
+          done
+          [ "$ok" = "1" ] || { echo "::error::browser install failed after 6 attempts" >&2; exit 1; }
+
+      # E2E: fully deterministic. The Playwright config boots its own dev webServer
+      # (npm run dev) with LLM_STUB=1 and DATA_DIR=data/e2e. VITE_PORT / HISTORY_API_PORT
+      # are set to free ports so that webServer won't collide with anything else on the
+      # runner (history's normal dev ports are 5173/4321). The config emits an HTML report
+      # (playwright-report/) and a JSON report (test-results/e2e.json) used below.
+      - name: E2E
+        env:
+          VITE_PORT: "5199"
+          HISTORY_API_PORT: "4399"
+        run: npm run e2e
+
+      # Short machine-readable summary appended to the PR/job. Runs even on failure
+      # (always()) and never breaks the job (|| true). Parses Playwright's JSON report:
+      # stats.expected = passed, stats.unexpected = failed, stats.skipped = skipped.
+      - name: E2E results summary
+        if: always()
+        run: |
+          {
+            echo "## E2E results"
+            echo
+            if [ -f test-results/e2e.json ]; then
+              node -e '
+                const fs = require("fs");
+                const r = JSON.parse(fs.readFileSync("test-results/e2e.json", "utf8"));
+                const s = r.stats || {};
+                console.log(`- **Passed:** ${s.expected ?? 0}`);
+                console.log(`- **Failed:** ${s.unexpected ?? 0}` + (s.flaky ? ` (flaky: ${s.flaky})` : ""));
+                console.log(`- **Skipped:** ${s.skipped ?? 0}`);
+                console.log(`- **Duration:** ${((s.duration ?? 0) / 1000).toFixed(1)}s`);
+              ' || echo "- could not parse test-results/e2e.json"
+            else
+              echo "- no test-results/e2e.json produced (e2e did not run)"
+            fi
+          } >> "$GITHUB_STEP_SUMMARY" || true
+
+      # On failure, keep the HTML report + raw results for debugging.
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        continue-on-error: true
+        with:
+          name: playwright-report
+          path: |
+            playwright-report/
+            test-results/
+          retention-days: 7

.gitignore

@@ -4,6 +4,7 @@ server/dist/
 *.log
 .env
 .env.*
+!.env.example
 data/
 *.sqlite
 *.sqlite3

AGENTS.md

@@ -11,6 +11,15 @@ which returns a structured `TurnResult` (events + stat/relation/territory deltas
 validates, clamps, and applies to the world state. A MapLibre choropleth renders territorial
 ownership; the whole thing persists to SQLite and streams over SSE on a single port.
 
+## Change process (mandatory)
+
+1. **Small, incremental, well-tested changes** — work is done one change at a time, in smaller parts; each part is tested before moving on. Connected tasks that touch the same area of code MAY be done together on one branch/PR with a single version bump (e.g. two tweaks to the same panel).
+2. **Feature branch + PR** — every change lands on a feature branch off `master` (no direct pushes to `master`). Open a pull request against `master` on Gitea (`https://git.kkhost.pl`, repo `OpenCode/History`).
+3. **Changelog entry** — every change is listed in `CHANGELOG.md` with a version, date and time (format: `## v<version> — YYYY-MM-DD HH:MM`, then bullet points of what changed).
+4. **Version bump** — the version is updated in `package.json`.
+5. **CI must pass** — branch protection on `master` requires the CI status check to be green before merge. Merge via auto-merge (`POST /repos/OpenCode/History/pulls/{n}/merge` with body `{"do":"merge","merge_style":"merge","merge_when_checks_succeed":true}`) so the PR merges by itself once CI is green. **CI never deploys to production.**
+6. **Tag + manual deploy after merge** — once merged, tag the version on `master` (e.g. `v0.1.0`). Production (`https://history.dev.kkhost.pl`) is updated manually afterwards on the host: `docker compose up -d --build`, then verify the site.
+
 ## Stack
 
 - TypeScript everywhere, `strict: true`
@@ -80,9 +89,11 @@ history/
 | `npm test` | vitest unit tests in `server/` (19 tests) |
 | `npm run typecheck` | `tsc --noEmit` (strict) across src/server/shared/e2e/configs |
 | `npm run lint` | ESLint flat config |
-| `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`); overrides dev ports via `VITE_PORT`/`HISTORY_API_PORT` if set |
+| `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`); **runs in CI on every PR** (see below) |
 | `docker compose up -d --build` | prod image on :4321, routed via Traefik at `history.dev.kkhost.pl` |
 
+**Local verification (before every PR):** `npm run typecheck` + `npm run lint` + `npm test` (unit) + `npm run build`. The full **e2e** suite (`npm run e2e`) is verified by **CI on every PR** (the Playwright config boots its own dev webServer with `LLM_STUB=1`) — locally you only need the four checks above; e2e is the CI source of truth.
+
 ## Conventions
 
 - **The server is authoritative.** All world state lives in SQLite (`server/db.ts`). The client

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to **History** are listed here, newest first.
+
+## v0.1.0 — 2026-10-11 08:02
+
+- Added a Gitea Actions CI pipeline (`.gitea/workflows/ci.yml`: `typecheck → lint → unit → build → deterministic Playwright e2e`). E2e runs against the app's own dev webServer (`LLM_STUB=1`) — no dind/docker.
+- Committed `package-lock.json` so CI uses a reproducible `npm ci`.
+- Switched to the mandatory PR-based workflow: feature branch → PR to `master` → CI green → auto-merge → tag + manual deploy (documented in `AGENTS.md`).
+- Versioned the repo at `0.1.0` (`package.json`) and added `CHANGELOG.md`, `.env` (gitignored) and `.env.example`.
+- This change is the first one landed through the new PR process (dogfooding it).

README.md

@@ -79,7 +79,14 @@ docker compose up -d --build --force-recreate  # after uncommenting LLM_STUB=1 i
 | `npm test` | vitest unit tests in `server/` (19) |
 | `npm run typecheck` | `tsc --noEmit` (strict) across the whole tree |
 | `npm run lint` | ESLint (flat config) |
-| `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`) |
+| `npm run e2e` | Playwright, fully deterministic (`LLM_STUB=1`); runs in CI on every PR |
+
+## Change process
+
+Changes follow a mandatory PR-based workflow (full rules in [AGENTS.md](./AGENTS.md#change-process-mandatory)):
+work on a feature branch off `master` (no direct pushes), add a `CHANGELOG.md` entry and bump the
+`package.json` version, open a PR to `master`, and let **CI pass** (typecheck → lint → unit → build → e2e)
+before auto-merging. After merge, tag the version and deploy manually (`docker compose up -d --build`).
 
 ## Design notes
 

playwright.config.ts

@@ -18,6 +18,13 @@ export default defineConfig({
     baseURL: devUrl,
     headless: true,
   },
+  // Reporters: list → console; html → playwright-report/ (uploaded by CI on failure);
+  // json → test-results/e2e.json (parsed by CI's "E2E results summary" step).
+  reporter: [
+    ['list'],
+    ['html'],
+    ['json', { outputFile: 'test-results/e2e.json' }],
+  ],
   webServer: {
     command: 'npm run dev',
     url: devUrl,