Release

.github/copilot-instructions.md

@@ -0,0 +1,7 @@
+# Project guidelines
+
+## General writing style
+
+- Prefer British English spelling in prose (for example: "synchronise",
+  "synchronisation").
+- Keep language simple, direct, and concise.

.github/instructions/architecture.instructions.md

@@ -0,0 +1,29 @@
+---
+description:
+  "Use when editing app or lib source files. Covers the main workspace structure
+  and package responsibilities."
+applyTo: "apps/**, libs/**, scripts/**"
+---
+
+# Architecture guidelines
+
+## Workspace structure
+
+- `apps/*` contains deployable applications.
+- `libs/*` contains shared workspace packages used by the apps.
+- `scripts/` contains workspace-level tooling.
+
+## Package responsibilities
+
+- Keep app-specific entry points, routes, and composition inside `apps/*`.
+- Keep reusable domain logic, UI primitives, and shared utilities inside
+  `libs/*`.
+- `libs/prisma` owns Prisma-related code and generated client integration for
+  the workspace.
+
+## Build model
+
+- Shared libs are generally consumed from their built output.
+- Changes to shared libs may require synchronisation into injected workspace
+  packages.
+- See: docs/decisions/002-workspace-package-injection.md

.github/instructions/code-comments.instructions.md

@@ -0,0 +1,14 @@
+---
+description:
+  "Use when creating or editing source code files. Covers the required style for
+  See reference lines in code comments."
+applyTo: "**/*.{js,ts,tsx}, **/Dockerfile, **/*.yml"
+---
+
+# Code comment guidelines
+
+## See reference lines
+
+- For "See" reference lines in code comments, use this style:
+  - `See: path/to/file`
+- In "See" reference lines, do not wrap the path in backticks.

.github/instructions/dependency-upgrades.instructions.md

@@ -0,0 +1,34 @@
+---
+description:
+  "Use when editing dependencies, pnpm-workspace.yaml, package.json dependency
+  fields. Covers workspace package injection and safe step-by-step dependency
+  changes."
+applyTo: "pnpm-workspace.yaml, **/package.json"
+---
+
+# Dependency upgrade guidelines
+
+## Workspace dependency model
+
+- Workspace packages are injected, not symlinked.
+- Keep `injectWorkspacePackages: true`.
+- Keep `dedupeInjectedDeps: false`.
+- Keep `syncInjectedDepsAfterScripts` pointing to `sync-workspace`.
+- See: docs/decisions/002-workspace-package-injection.md
+
+## Package manifest rules
+
+- Use `workspace:*` for internal dependencies.
+- Use `catalog:` for third-party dependencies managed at workspace level.
+- For libs that are consumed from `build/`, keep the `files` field aligned with
+  the published build output.
+- For injected libs, keep the `sync-workspace` hook and the scripts that trigger
+  it.
+
+## Upgrade strategy
+
+- Prefer step-by-step dependency changes over broad workspace-wide upgrades,
+  unless the upgrade is a patch release or a clearly simple minor release.
+- Keep peer dependency changes scoped and explicit.
+- When changing shared lib dependencies, consider the consuming apps before
+  aligning versions.

.github/instructions/docs-writing.instructions.md

@@ -0,0 +1,30 @@
+---
+description:
+  "Use when creating or editing documentation and markdown files. Covers heading
+  case, prose style, shorthand policy, and markdown formatting conventions."
+applyTo: "**/*.md"
+---
+
+# Documentation writing guidelines
+
+## Writing style
+
+- Use sentence case for document and section headings.
+
+## Naming and shorthand
+
+- Avoid shortened words in prose when a clear full word is available.
+- Allowed shorthand in prose: "apps" and "libs".
+
+## Markdown formatting
+
+- Wrap file paths and script names in backticks in prose and markdown text.
+- Prefer reference-style markdown links, with link references defined at the
+  bottom of the file.
+- Sort link references alphabetically by reference name.
+
+## Documentation changes
+
+- When updating ADRs or docs, preserve existing meaning and improve clarity.
+- Prefer fluid paragraphs over fragmented bullet points unless a list improves
+  readability.

.github/instructions/package-scripts.instructions.md

@@ -0,0 +1,43 @@
+---
+description:
+  "Use when creating or editing package.json scripts. Covers the script naming
+  conventions shared by apps, libs, and workspace packages."
+applyTo: "**/package.json"
+---
+
+# Package script guidelines
+
+## Script naming
+
+- Keep the existing script prefixes and meanings.
+- Use `build` for the production build entry point.
+- Use `build:*` for build subtasks.
+- Use `prebuild` for cleanup or generation that must happen before `build`.
+- Use `dev` for the long-running local workflow.
+- Use `dev:*` for long-running subtasks started by `dev`.
+- Use `generate` for one-off asset or code generation.
+- Use `generate:*` for generation subtasks.
+- Use `clean` to remove generated outputs.
+- Use `lint` for read-only validation checks.
+- Use `lint-fix` for safe automatic fixes.
+- Use `start` for the production runtime entry point.
+- Use `docker-build` and `docker-start` for local container workflows when
+  needed.
+
+## Script composition
+
+- Prefer `run-s` for sequential orchestration and `run-p` for parallel
+  orchestration.
+- When a script runs multiple subtasks, keep `--print-label` so output stays
+  readable.
+- For long-running parallel `dev` or `generate` workflows, keep
+  `--continue-on-error` unless a task must fail fast.
+
+## Workspace injection hooks
+
+- For libs that publish only `build/`, keep `postbuild` calling
+  `pnpm sync-workspace`.
+- For watch mode, use `dev:sync-workspace` to watch `build/` and trigger
+  `sync-workspace`.
+- Keep `sync-workspace` as the dedicated hook script used by
+  `pnpm-workspace.yaml`.

.github/instructions/source-editing.instructions.md

@@ -0,0 +1,39 @@
+---
+description:
+  "Use when creating or editing source code files. Covers common-sense editing
+  constraints, safe defaults, and refactor expectations for this workspace."
+applyTo: "**/*.{js,ts,tsx}, **/Dockerfile, **/*.yml"
+---
+
+# Source editing guidelines
+
+## General approach
+
+- Prefer small, focused changes that solve the root cause.
+- Preserve existing behaviour unless the task explicitly asks for a behaviour
+  change.
+- Preserve public APIs and script names unless the task requires changing them.
+
+## Opportunistic cleanups
+
+- Opportunistic cleanups are allowed.
+- Keep them small, local, and low risk.
+- Limit them to the code you are already touching or to directly related dead
+  code.
+- Do not mix broad refactors with functional changes unless the task asks for
+  both.
+
+## Generated outputs
+
+- Do not edit generated outputs by hand.
+- Treat `build/`, `public/build/`, and `src/generated/` as generated unless the
+  task is specifically about generation.
+- Prefer changing the source, generator, or script that produces generated
+  files.
+
+## Shared code
+
+- When a change affects multiple apps, prefer fixing the shared lib instead of
+  duplicating changes in each app.
+- Keep app-specific composition inside `apps/*` and reusable logic inside
+  `libs/*`.

.github/workflows/admin.checks.yml

@@ -22,9 +22,12 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build:
-    name: 📦 Build
+  prepare:
+    name: 🔧 Prepare
     runs-on: ubuntu-latest
+    outputs:
+      app_name: ${{ steps.app_name.outputs.value }}
+      image_tag: ${{ steps.image_tag.outputs.value }}
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
@@ -36,6 +39,25 @@ jobs:
           file: ./apps/admin/fly.toml
           field: app
 
+      # In workflows triggered by pull requests, `github.ref_name` is
+      # `<pr-number>/merge`. We use `github.head_ref` instead to get the
+      # source branch name.
+      - name: 🏷️ Build image tag
+        id: image_tag
+        run:
+          echo "value=registry.fly.io/${{ steps.app_name.outputs.value }}:$(echo
+          '${{ github.head_ref }}' | tr '/' '-')-${{ github.sha }}" >>
+          $GITHUB_OUTPUT
+
+  build:
+    name: 📦 Build
+    runs-on: ubuntu-latest
+    needs:
+      - prepare
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+
       - name: 🐳 Set up Docker Buildx
         uses: docker/setup-buildx-action@v2
         with:
@@ -54,9 +76,7 @@ jobs:
         with:
           context: .
           file: ./apps/admin/Dockerfile
-          tags:
-            registry.fly.io/${{ steps.app_name.outputs.value }}:${{
-            github.head_ref }}-${{ github.sha }}
+          tags: ${{ needs.prepare.outputs.image_tag }}
           cache-from: type=local,src=/tmp/.buildx-cache
           cache-to: type=local,mode=max,dest=/tmp/.buildx-cache-new
 

.github/workflows/admin.deploy.yml

@@ -24,6 +24,30 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  prepare:
+    name: 🔧 Prepare
+    runs-on: ubuntu-latest
+    outputs:
+      app_name: ${{ steps.app_name.outputs.value }}
+      image_tag: ${{ steps.image_tag.outputs.value }}
+    steps:
+      - name: ⬇️ Checkout repo
+        uses: actions/checkout@v4
+
+      - name: 👀 Read app name
+        uses: SebRollen/toml-action@v1.0.2
+        id: app_name
+        with:
+          file: ./apps/admin/fly.toml
+          field: app
+
+      - name: 🏷️ Build image tag
+        id: image_tag
+        run:
+          echo "value=registry.fly.io/${{ steps.app_name.outputs.value }}:$(echo
+          '${{ github.ref_name }}' | tr '/' '-')-${{ github.sha }}" >>
+          $GITHUB_OUTPUT
+
   lint:
     name: 🔬 Lint
     runs-on: ubuntu-latest
@@ -57,17 +81,12 @@ jobs:
   build:
     name: 📦 Build
     runs-on: ubuntu-latest
+    needs:
+      - prepare
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
 
-      - name: 👀 Read app name
-        uses: SebRollen/toml-action@v1.0.2
-        id: app_name
-        with:
-          file: ./apps/admin/fly.toml
-          field: app
-
       - name: 🐳 Set up Docker Buildx
         uses: docker/setup-buildx-action@v2
         with:
@@ -94,9 +113,7 @@ jobs:
           context: .
           file: ./apps/admin/Dockerfile
           push: true
-          tags:
-            registry.fly.io/${{ steps.app_name.outputs.value }}:${{
-            github.ref_name }}-${{ github.sha }}
+          tags: ${{ needs.prepare.outputs.image_tag }}
           cache-from: type=local,src=/tmp/.buildx-cache
           cache-to: type=local,mode=max,dest=/tmp/.buildx-cache-new
 
@@ -114,27 +131,20 @@ jobs:
     name: 🚀 Deploy
     runs-on: ubuntu-latest
     needs:
+      - prepare
       - lint
       - build
     steps:
       - name: ⬇️ Checkout repo
         uses: actions/checkout@v4
 
-      - name: 👀 Read app name
-        uses: SebRollen/toml-action@v1.0.2
-        id: app_name
-        with:
-          file: ./apps/admin/fly.toml
-          field: app
-
       - name: 🚀 Deploy Production
         if: ${{ github.ref == 'refs/heads/main' }}
         uses: superfly/flyctl-actions@1.4
         with:
           args:
-            deploy --config ./apps/admin/fly.toml --image registry.fly.io/${{
-            steps.app_name.outputs.value }}:${{ github.ref_name }}-${{
-            github.sha }}
+            deploy --config ./apps/admin/fly.toml --image ${{
+            needs.prepare.outputs.image_tag }}
         env:
           FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
 
@@ -144,8 +154,7 @@ jobs:
         with:
           args:
             deploy --config ./apps/admin/fly.toml --app ${{
-            steps.app_name.outputs.value }}-staging --image registry.fly.io/${{
-            steps.app_name.outputs.value }}:${{ github.ref_name }}-${{
-            github.sha }}
+            needs.prepare.outputs.app_name }}-staging --image ${{
+            needs.prepare.outputs.image_tag }}
         env:
           FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}