Merge branch 'main' into vilius-kimchi-cli

Author: bentleyvk

.github/AGENTS.md

@@ -12,8 +12,9 @@ Before changing GitHub automation, read the current versions of:
 - `.github/workflows/report.atom.yml`
 - `.github/scripts/handoff.py`
 - `scripts/scopes.ts`
+- `specs/current/ci.md` when changing scope rules, confidence tiers, or guards
 - `e2e/tests/packaged-smoke-workflow.test.ts`
-- `scripts/approve-fork-pr-workflows.ts` and `scripts/approve-fork-pr-workflows.test.ts` when touching fork PR approval behavior
+- `scripts/approve-fork-pr-workflows.ts` and `e2e/tests/scripts/approve-fork-pr-workflows.test.ts` when touching fork PR approval behavior
 
 If the change affects cross-workflow behavior, update the topology tests instead of relying only on workflow YAML review.
 
@@ -44,7 +45,7 @@ Default rule: do not add a new domain-specific follow-on workflow such as `foo.c
 - `.github/workflows/` contains GitHub Actions workflow entrypoints.
 - `.github/actions/` contains reusable composite actions for workflow setup steps.
 - `.github/scripts/` contains workflow-owned scripts and contracts that are not general repo developer commands.
-- `.github/workflow/scripts/` currently contains older release workflow implementation scripts. Treat it as existing release infrastructure, not as the default location for new CI handoff helpers.
+- `.github/scripts/release/` contains release workflow implementation helpers. Keep release-only helpers there and CI handoff helpers at `.github/scripts/`.
 - Root `scripts/` remains for repo-level developer checks, product scripts, and guard/test logic. Do not move workflow-only handoff glue there just to make it look more general.
 
 New workflow-owned helpers should usually live under `.github/scripts/`. Prefer TypeScript for project-owned scripts in general, but Python is acceptable for small GitHub runner glue when stdlib portability and low setup cost matter. Keep such exceptions narrow and covered by `pnpm guard` policy.
@@ -163,4 +164,4 @@ GitHub artifact behavior is easy to drift: artifact names must be unique per upl
 
 ### Where should tests live?
 
-Cross-workflow topology tests belong in `e2e/tests/` when they observe repository-level behavior. Script-specific behavior can stay next to the script's existing tests. Do not add one-off `*.test.ts` files just because a workflow helper exists; prefer existing topology coverage and helper self-checks when that is enough.
+Cross-workflow topology tests belong in `e2e/tests/` when they observe repository-level behavior. Root `scripts/` is test-free (enforced by `pnpm guard`); script behavior-contract coverage lives in `e2e/tests/scripts/`. Do not add one-off `*.test.ts` files just because a workflow helper exists; prefer existing topology coverage and helper self-checks when that is enough.

.github/actions/setup-workspace/action.yml

@@ -14,6 +14,10 @@ inputs:
     description: JSON array of labels selected for this job's runs-on value
     required: false
     default: '[]'
+  save-pnpm-cache:
+    description: Save a missing pnpm cache after install; trusted main seed jobs only
+    required: false
+    default: 'false'
 
 runs:
   using: composite
@@ -62,13 +66,21 @@ runs:
       shell: bash
       run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
 
-    - name: Cache pnpm store
+    - name: Restore pnpm store
+      id: pnpm-cache-restore
       if: ${{ steps.persistent-pnpm-store.outputs.enabled != 'true' }}
-      uses: actions/cache@v5.0.5
+      uses: actions/cache/restore@v5
       with:
         path: ${{ steps.pnpm-store.outputs.path }}
         key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
 
     - name: Install dependencies
       shell: bash
       run: pnpm install --frozen-lockfile
+
+    - name: Save pnpm store
+      if: ${{ inputs.save-pnpm-cache == 'true' && steps.persistent-pnpm-store.outputs.enabled != 'true' && steps.pnpm-cache-restore.outputs.cache-hit != 'true' && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch' || github.event_name == 'schedule') }}
+      uses: actions/cache/save@v5
+      with:
+        path: ${{ steps.pnpm-store.outputs.path }}
+        key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}

.github/pull_request_template.md

@@ -31,7 +31,7 @@ Fixes #
 
 - [ ] **UI** — new page / dialog / panel / menu item / setting / empty state in `apps/web` or `apps/desktop` (including Electron menu bar)
 - [ ] **Keyboard shortcut** — new or changed
-- [ ] **CLI / env var** — new `od` subcommand or flag, new `tools-dev` / `tools-pack` / `tools-pr` flag, or new `OD_*` env var
+- [ ] **CLI / env var** — new `od` subcommand or flag, new `tools-dev` / `tools-pack` flag, or new `OD_*` env var
 - [ ] **API / contract** — new `/api/*` endpoint, new SSE event, or changed shape in `packages/contracts`
 - [ ] **Extension point** — new entry under `skills/`, `design-systems/`, `design-templates/`, or `craft/`, or change to the skills protocol
 - [ ] **i18n keys** — added new translation keys (see `TRANSLATIONS.md` for the locale workflow)

.github/screenshots/time-aware-home-greeting.png

@@ -0,0 +1,68 @@
+name: cache-maintenance
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - pnpm-lock.yaml
+      - .github/actions/setup-workspace/action.yml
+      - .github/workflows/cache-maintenance.yml
+  pull_request_target:
+    types: [closed]
+  workflow_dispatch:
+
+permissions:
+  actions: write
+  contents: read
+
+jobs:
+  seed-pnpm-windows:
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
+    runs-on: windows-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v6.0.2
+
+      - name: Seed Windows pnpm cache
+        uses: ./.github/actions/setup-workspace
+        with:
+          save-pnpm-cache: 'true'
+
+  clean-closed-pr-buildkit:
+    if: github.event_name == 'pull_request_target' && github.repository == 'nexu-io/open-design'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - name: Delete closed PR BuildKit caches
+        env:
+          CACHE_REF: refs/pull/${{ github.event.pull_request.number }}/merge
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+
+          cache_rows="$(
+            gh cache list \
+              --repo "$GITHUB_REPOSITORY" \
+              --ref "$CACHE_REF" \
+              --limit 10000 \
+              --json id,key,sizeInBytes \
+              --jq '.[] | select((.key | startswith("buildkit-blob-")) or (.key | startswith("index-buildkit-"))) | [.id, .key, .sizeInBytes] | @tsv'
+          )"
+
+          if [ -z "$cache_rows" ]; then
+            echo "No closed-PR BuildKit caches found for $CACHE_REF"
+            exit 0
+          fi
+
+          count=0
+          bytes=0
+          while IFS=$'\t' read -r cache_id cache_key cache_size; do
+            [ -n "$cache_id" ] || continue
+            echo "Deleting cache id=$cache_id key=$cache_key bytes=$cache_size ref=$CACHE_REF"
+            gh cache delete "$cache_id" --repo "$GITHUB_REPOSITORY"
+            count=$((count + 1))
+            bytes=$((bytes + cache_size))
+          done <<< "$cache_rows"
+
+          echo "Deleted $count closed-PR BuildKit caches ($bytes bytes) for $CACHE_REF"

.github/workflows/cache-maintenance.yml

@@ -63,6 +63,7 @@ jobs:
       run_playwright_critical: ${{ steps.detect.outputs.run_playwright_critical }}
       run_playwright_visual: ${{ steps.detect.outputs.run_playwright_visual }}
       run_preflight: ${{ steps.detect.outputs.run_preflight }}
+      run_preflight_typecheck: ${{ steps.detect.outputs.run_preflight_typecheck }}
       run_ui_p0: ${{ steps.detect.outputs.run_ui_p0 }}
       run_web_workspace_tests: ${{ steps.detect.outputs.run_web_workspace_tests }}
       run_windows_tools_pack_payload_tests: ${{ steps.detect.outputs.run_windows_tools_pack_payload_tests }}
@@ -136,21 +137,31 @@ jobs:
     timeout-minutes: 10
     env:
       ACTIONLINT_VERSION: 1.7.12
+      SHELLCHECK_VERSION: 0.11.0
 
     steps:
       - name: Checkout
         uses: actions/checkout@v6.0.2
 
-      - name: Install actionlint
+      - name: Install actionlint and ShellCheck
         run: |
           case "$(uname -m)" in
-            x86_64) actionlint_arch=amd64 ;;
-            aarch64|arm64) actionlint_arch=arm64 ;;
+            x86_64)
+              actionlint_arch=amd64
+              shellcheck_arch=x86_64
+              ;;
+            aarch64|arm64)
+              actionlint_arch=arm64
+              shellcheck_arch=aarch64
+              ;;
             *) echo "Unsupported actionlint architecture: $(uname -m)" >&2; exit 1 ;;
           esac
           curl -fsSL "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_${actionlint_arch}.tar.gz" \
             | tar -xz actionlint
+          curl -fsSL "https://github.com/koalaman/shellcheck/releases/download/v${SHELLCHECK_VERSION}/shellcheck-v${SHELLCHECK_VERSION}.linux.${shellcheck_arch}.tar.gz" \
+            | tar -xz --strip-components=1 "shellcheck-v${SHELLCHECK_VERSION}/shellcheck"
           sudo install -m 0755 actionlint /usr/local/bin/actionlint
+          sudo install -m 0755 shellcheck /usr/local/bin/shellcheck
 
       - name: Check workflow files
         run: actionlint -color
@@ -245,12 +256,14 @@ jobs:
       # If postinstall grows a targeted app type-generation phase covering these
       # three exports without broad app builds, this CI prebuild can be removed.
       - name: Prebuild workspace type declarations
+        if: ${{ needs.scopes.outputs.run_preflight_typecheck == 'true' }}
         run: |
           pnpm --filter @open-design/daemon build
           pnpm --filter @open-design/desktop build
           pnpm --filter @open-design/web build:sidecar
 
       - name: Typecheck workspaces
+        if: ${{ needs.scopes.outputs.run_preflight_typecheck == 'true' }}
         run: |
           pnpm -r --filter '!open-design' --filter '!@open-design/landing-page' --workspace-concurrency="${OPEN_DESIGN_WORKSPACE_CONCURRENCY:-1}" --if-present run typecheck
           pnpm exec tsc -p scripts/tsconfig.json --noEmit
@@ -291,7 +304,13 @@ jobs:
             pnpm --filter @open-design/tools-dev test
           fi
           if [ "${{ needs.scopes.outputs.tools_pack_tests_required }}" = "true" ]; then
+            pnpm --filter @open-design/desktop build
+            pnpm --filter @open-design/desktop test
+            pnpm --filter @open-design/packaged test
             pnpm --filter @open-design/tools-pack test
+            if [ "${{ needs.scopes.outputs.run_e2e_vitest }}" != "true" ]; then
+              pnpm --filter @open-design/e2e test tests/packaged-launcher-update-loop.test.ts
+            fi
           fi
 
       - name: Probe watcher environment
@@ -441,12 +460,16 @@ jobs:
           OD_PLAYWRIGHT_FULLY_PARALLEL: "1"
         run: pnpm -C e2e exec playwright test -c playwright.config.ts ${{ matrix.files }} --grep '@critical'
 
-  ui_p0_smoke:
-    name: UI P0 smoke
+  ui_p0:
+    name: UI P0 (${{ matrix.name }})
     needs: [scopes, runners]
     if: ${{ needs.scopes.outputs.run_ui_p0 == 'true' }}
     runs-on: ${{ fromJSON(needs.runners.outputs.runs_on).ui_hot }}
-    timeout-minutes: 30
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJSON(needs.scopes.outputs.ui_p0_matrix) }}
 
     steps:
       - name: Checkout
@@ -476,14 +499,14 @@ jobs:
       - name: Clean Playwright state
         run: pnpm -C e2e exec tsx scripts/playwright.ts clean
 
-      - name: Run UI shell smoke
-        run: pnpm -C e2e exec tsx scripts/playwright.ts run-ui-group smoke
+      - name: Run UI P0 domain
+        run: pnpm -C e2e exec tsx scripts/playwright.ts run-ui-group ${{ matrix.shard }}
 
-      - name: Upload Playwright debug artifact
-        if: ${{ always() }}
+      - name: Preserve project-runtime domain artifact
+        if: ${{ success() && matrix.shard == 'project-runtime' }}
         uses: actions/upload-artifact@v7
         with:
-          name: ui-p0-ci-${{ github.run_id }}-smoke
+          name: ui-p0-ci-${{ github.run_id }}-${{ matrix.name }}-domain
           path: |
             e2e/ui/reports/playwright-html-report
             e2e/ui/reports/test-results
@@ -492,47 +515,9 @@ jobs:
           if-no-files-found: ignore
           retention-days: 7
 
-  ui_p0:
-    name: UI P0 (${{ matrix.name }})
-    needs: [scopes, runners]
-    if: ${{ needs.scopes.outputs.run_ui_p0 == 'true' }}
-    runs-on: ${{ fromJSON(needs.runners.outputs.runs_on).ui_hot }}
-    timeout-minutes: 45
-    strategy:
-      fail-fast: false
-      matrix:
-        include: ${{ fromJSON(needs.scopes.outputs.ui_p0_matrix) }}
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6.0.2
-
-      - name: Configure CI parallelism
-        uses: ./.github/actions/configure-ci-parallelism
-
-      - name: Setup workspace
-        uses: ./.github/actions/setup-workspace
-        with:
-          runner-labels: ${{ toJSON(fromJSON(needs.runners.outputs.runs_on).ui_hot) }}
-
-      - name: Setup Playwright
-        uses: ./.github/actions/setup-playwright
-        with:
-          package-json-path: e2e/package.json
-          install-command: pnpm -C e2e exec playwright install --with-deps chromium
-          runner-labels: ${{ toJSON(fromJSON(needs.runners.outputs.runs_on).ui_hot) }}
-
-      - name: Prebuild workspace type declarations
-        run: |
-          pnpm --filter @open-design/daemon build
-          pnpm --filter @open-design/desktop build
-          pnpm --filter @open-design/web build:sidecar
-
-      - name: Clean Playwright state
-        run: pnpm -C e2e exec tsx scripts/playwright.ts clean
-
-      - name: Run UI P0 domain
-        run: pnpm -C e2e exec tsx scripts/playwright.ts run-ui-group ${{ matrix.shard }}
+      - name: Run UI critical extras
+        if: ${{ matrix.shard == 'project-runtime' }}
+        run: pnpm -C e2e exec tsx scripts/playwright.ts run-ui-group critical-extras
 
       - name: Upload Playwright debug artifact
         if: ${{ always() }}
@@ -648,7 +633,6 @@ jobs:
       - web_workspace_tests
       - e2e_vitest
       - playwright_critical
-      - ui_p0_smoke
       - ui_p0
       - playwright_visual
     if: ${{ always() }}
@@ -695,7 +679,7 @@ jobs:
               + when($out.run_web_workspace_tests == "true"; ["web_workspace_tests"])
               + when($out.run_e2e_vitest == "true"; ["e2e_vitest"])
               + when($out.run_playwright_critical == "true"; ["playwright_critical"])
-              + when($out.run_ui_p0 == "true"; ["ui_p0_smoke", "ui_p0"])
+              + when($out.run_ui_p0 == "true"; ["ui_p0"])
               + when($out.run_playwright_visual == "true"; ["playwright_visual"])
             )[]
             | select(($needs[.].result // "missing") != "success")
@@ -758,8 +742,11 @@ jobs:
               marker="<!-- merge-queue-needs-validation -->"
               {
                 printf '%s\n' "$marker"
+                # Markdown code spans are intentional literal text.
+                # shellcheck disable=SC2016
                 printf 'Ejected from the merge queue: this PR still carries the `needs-validation` label.\n\n'
                 printf 'The merge queue gate ([run %s](%s/%s/actions/runs/%s)) blocked the queued group because of the label. That failure runs on the queue'"'"'s transient ref, so it never appears in this PR'"'"'s own checks — they stay green, and this notice is the only visible trace on the PR.\n\n' "$RUN_ID" "$GITHUB_SERVER_URL" "$REPO" "$RUN_ID"
+                # shellcheck disable=SC2016
                 printf 'To land this PR: complete the QA pass the label is tracking, remove the `needs-validation` label, then add the PR back to the merge queue.\n'
               } > "$handoff_dir/body.md"
               jq -n \

.github/workflows/ci.yml

@@ -100,10 +100,12 @@ jobs:
           # (e.g. version=0.15.1 gates open-design-v0.15.0, not the latest 0.14.0).
           vmajor=${V%%.*}; vrest=${V#*.}; vminor=${vrest%%.*}
           MINOR_BASE="${vmajor}.${vminor}.0"
-          echo "version=$V"                          >> "$GITHUB_OUTPUT"
-          echo "branch=release/v$V"                  >> "$GITHUB_OUTPUT"
-          echo "minor_base=$MINOR_BASE"              >> "$GITHUB_OUTPUT"
-          echo "minor_tag=open-design-v$MINOR_BASE"  >> "$GITHUB_OUTPUT"
+          {
+            echo "version=$V"
+            echo "branch=release/v$V"
+            echo "minor_base=$MINOR_BASE"
+            echo "minor_tag=open-design-v$MINOR_BASE"
+          } >> "$GITHUB_OUTPUT"
           echo "Cutting patch v$V (branch release/v$V); gating on stable v$MINOR_BASE"
 
       # Guard: the minor this patch sits on (the Tuesday cut) must already be a

.github/workflows/cut-patch-release.yml

@@ -81,9 +81,9 @@ jobs:
       - name: Setup workspace
         uses: ./.github/actions/setup-workspace
 
-      - name: Cache generated previews
+      - name: Restore generated previews
         id: previews-cache
-        uses: actions/cache@v5.0.5
+        uses: actions/cache/restore@v5
         with:
           path: apps/landing-page/public/previews
           key: landing-page-previews-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'package.json', 'apps/landing-page/package.json', 'apps/landing-page/scripts/generate-previews.ts', 'apps/landing-page/scripts/fallback-preview-card.ts', 'skills/**', 'design-templates/**', 'templates/live-artifacts/**', 'plugins/_official/**') }}
@@ -125,6 +125,13 @@ jobs:
           OD_LANDING_NOINDEX: '1'
         run: pnpm --filter @open-design/landing-page build:static
 
+      - name: Save generated previews
+        if: ${{ steps.previews-cache.outputs.cache-hit != 'true' && github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch') }}
+        uses: actions/cache/save@v5
+        with:
+          path: apps/landing-page/public/previews
+          key: landing-page-previews-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml', 'package.json', 'apps/landing-page/package.json', 'apps/landing-page/scripts/generate-previews.ts', 'apps/landing-page/scripts/fallback-preview-card.ts', 'skills/**', 'design-templates/**', 'templates/live-artifacts/**', 'plugins/_official/**') }}
+
       - name: Lint changed blog SEO
         # The build above sets OD_LANDING_NOINDEX=1, so every rendered page in
         # `out/` carries `noindex`. Pass the same flag through so the SEO linter