Merge Context Engine and documentation updates

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: raiseCatError

.github/actions/linux-shells/action.yml

@@ -0,0 +1,30 @@
+name: Linux shell prerequisites
+description: Install missing shell/build tools and secure system completion paths
+runs:
+  using: composite
+  steps:
+    - shell: bash
+      run: |
+        # Ubuntu images supply native build tools; probe rather than reinstall.
+        packages=()
+        command -v zsh >/dev/null || packages+=(zsh)
+        command -v fish >/dev/null || packages+=(fish)
+        command -v g++ >/dev/null || packages+=(g++)
+        command -v make >/dev/null || packages+=(make)
+        command -v python3 >/dev/null || packages+=(python3)
+        if (( ${#packages[@]} )); then
+          sudo apt-get update
+          sudo apt-get install -y "${packages[@]}"
+        fi
+        insecure="$(zsh -fc 'autoload -Uz compaudit; compaudit' 2>/dev/null || true)"
+        while IFS= read -r path; do
+          [ -z "$path" ] && continue
+          case "$path" in
+            /usr/share/zsh|/usr/share/zsh/*|/usr/local/share/zsh|/usr/local/share/zsh/*)
+              sudo chown root:root "$path"
+              sudo chmod go-w "$path"
+              ;;
+            *) echo "::error::Unexpected insecure completion path: $path"; exit 1 ;;
+          esac
+        done <<< "$insecure"
+        zsh -fc 'autoload -Uz compaudit; compaudit'

.github/workflows/ci.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches: [master, dev]
   pull_request:
-    branches: [master, dev]
   workflow_dispatch:
 
 permissions:
@@ -15,43 +14,184 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  verify:
-    name: Verify
-    runs-on: macos-latest
+  changes:
+    name: Detect code changes
+    runs-on: ubuntu-24.04
+    outputs:
+      code: ${{ steps.changes.outputs.code }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - id: changes
+        env:
+          EVENT: ${{ github.event_name }}
+          BASE: ${{ github.event.pull_request.base.sha }}
+          HEAD: ${{ github.event.pull_request.head.sha }}
+        shell: bash
+        run: |
+          # Never path-skip the workflow: the final CI check must always exist.
+          # Push/manual runs always collect comprehensive evidence.
+          if [[ "$EVENT" != pull_request ]]; then
+            echo 'code=true' >> "$GITHUB_OUTPUT"
+          else
+            git diff --check "$BASE" "$HEAD"
+            git diff --no-renames --name-only -z "$BASE" "$HEAD" > /tmp/changed-files
+            python3 - <<'PYTHON' >> "$GITHUB_OUTPUT"
+          from pathlib import Path
+          files = Path('/tmp/changed-files').read_bytes().split(b'\0')
+          docs_only = all(f.startswith(b'docs/') or f.endswith(b'.md') for f in files if f)
+          print('code=' + str(not docs_only).lower())
+          PYTHON
+          fi
+
+  quality:
+    name: Quality (Node 26)
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 26.x
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run typecheck:bench
+      - run: npm run test:fast
+      - run: git diff --check
+
+  tests:
+    name: Tests (${{ matrix.os }}, ${{ matrix.shard }}/2)
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ${{ matrix.os }}
     timeout-minutes: 10
     strategy:
+      fail-fast: false
       matrix:
-        node-version: [22.x, 26.x]
-
+        os: [macos-latest, ubuntu-24.04]
+        shard: [1, 2]
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Build
-        run: npm run build
-
-      - name: Typecheck
-        run: npm run typecheck
+          node-version: 26.x
+          cache: npm
+      - uses: ./.github/actions/linux-shells
+        if: runner.os == 'Linux'
+      - run: npm ci
+      # Built-launcher tests must execute rather than silently skip on fresh runners.
+      - run: npm run build
+      - run: npm test -- --shard=${{ matrix.shard }}/2 --test-timeout=120000
+      - name: Process leak check
+        if: always()
+        run: bash scripts/check-process-leaks.sh
 
-      - name: Run tests
-        run: npm test
+  node22:
+    name: Node 22 compatibility
+    needs: changes
+    if: needs.changes.outputs.code == 'true'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: npm
+      - uses: ./.github/actions/linux-shells
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test:node22 -- --test-timeout=120000
+      - name: Process leak check
+        if: always()
+        run: bash scripts/check-process-leaks.sh
 
-      - name: Verify working tree clean
-        run: git diff --check
+  timings:
+    name: Timing smoke (${{ matrix.os }}, Node 26)
+    if: github.event_name != 'pull_request'
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 5
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, ubuntu-24.04]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 26.x
+          cache: npm
+      - uses: ./.github/actions/linux-shells
+        if: runner.os == 'Linux'
+      - run: npm ci
+      - run: npm run bench:smoke
+      - name: Process leak check
+        if: always()
+        run: bash scripts/check-process-leaks.sh
 
+  fedora:
+    name: Linux portability subset (Fedora)
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    container: fedora:42
+    steps:
+      - name: Install system prerequisites
+        run: dnf install -y git zsh fish gcc-c++ make python3 which lsof procps-ng
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test:fedora -- --test-timeout=120000
       - name: Process leak check
+        if: always()
+        run: bash scripts/check-process-leaks.sh
+
+  status:
+    name: CI
+    if: always()
+    needs: [changes, quality, tests, node22, timings, fedora]
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Require all applicable gates
+        env:
+          RESULTS: ${{ toJSON(needs) }}
         run: |
-          if ps -axo pid,ppid,pgid,command | grep -E '[z]sh.*nmsh-semantic|[n]msh-semantic|viewportSyntax' | grep -v grep; then
-            echo "::error::NMSh helper or test processes leaked!"
-            exit 1
-          fi
-          echo "No processes leaked."
+          python3 - <<'PYTHON'
+          import json, os
+          jobs = json.loads(os.environ['RESULTS'])
+          code = jobs['changes']['outputs'].get('code')
+          required = ['changes']
+          if code == 'true':
+              required += ['quality', 'tests', 'node22']
+          elif code != 'false':
+              raise SystemExit('Missing change classification')
+          if '${{ github.event_name }}' != 'pull_request':
+              required += ['timings', 'fedora']
+          failed = [name for name in required if jobs[name]['result'] != 'success']
+          if failed:
+              raise SystemExit('Failed or skipped required gates: ' + ', '.join(failed))
+          print('All applicable CI gates passed')
+          PYTHON
+
+  # Preserve the exact check names required by the existing master ruleset.
+  required-checks:
+    name: Verify (${{ matrix.node-version }})
+    needs: status
+    if: always()
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        node-version: [22.x, 26.x]
+    steps:
+      - name: Require aggregate CI success
+        env:
+          RESULT: ${{ needs.status.result }}
+        run: test "$RESULT" = success

.github/workflows/homebrew-tap.yml

@@ -0,0 +1,68 @@
+name: Homebrew tap
+
+# After a stable GitHub release is published, propose the matching formula
+# update to raiseCatError/homebrew-tap as a pull request (reviewable; the
+# tap's own CI installs and tests it). Never runs for prereleases, dev pushes
+# or pull requests.
+#
+# Needs one secret, HOMEBREW_TAP_TOKEN: a fine-grained token limited to the
+# raiseCatError/homebrew-tap repository with Contents and Pull requests write.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  formula:
+    # Distribution is not configured yet. Enable only in the separate Homebrew setup pass.
+    if: ${{ false }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Release facts
+        id: release
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          # Strict stable semver only: the value later reaches a URL and a sed expression.
+          printf '%s' "$TAG" | grep -Eqx 'v[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4}' || { echo "Not a stable version tag."; exit 1; }
+          version="${TAG#v}"
+          url="https://github.com/${GITHUB_REPOSITORY}/archive/refs/tags/${TAG}.tar.gz"
+          curl -fsSL --retry 3 -o release.tar.gz "$url"
+          sha256="$(sha256sum release.tar.gz | cut -d' ' -f1)"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          echo "url=$url" >> "$GITHUB_OUTPUT"
+          echo "sha256=$sha256" >> "$GITHUB_OUTPUT"
+
+      - name: Check out the tap
+        uses: actions/checkout@v4
+        with:
+          repository: raiseCatError/homebrew-tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          path: tap
+
+      - name: Propose the formula update
+        working-directory: tap
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          VERSION: ${{ steps.release.outputs.version }}
+          URL: ${{ steps.release.outputs.url }}
+          SHA256: ${{ steps.release.outputs.sha256 }}
+        run: |
+          formula=Formula/nmsh.rb
+          if grep -q "^  url \"$URL\"$" "$formula"; then
+            # A published archive is immutable: never re-point the same version at different bytes.
+            grep -q "^  sha256 \"$SHA256\"$" "$formula" || { echo "The formula already names $URL with a different sha256. Publish a new patch release instead."; exit 1; }
+            echo "Formula already at $VERSION."; exit 0
+          fi
+          sed -i -E "s|^  url \".*\"$|  url \"$URL\"|; s|^  sha256 \".*\"$|  sha256 \"$SHA256\"|" "$formula"
+          git diff --stat
+          branch="nmsh-$VERSION"
+          git switch -c "$branch"
+          git -c user.name=J -c user.email=315733358+raiseCatError@users.noreply.github.com commit -am "nmsh $VERSION"
+          git push origin "$branch"
+          gh pr create --title "nmsh $VERSION" --body "Release: https://github.com/raiseCatError/notMyShell/releases/tag/v$VERSION
+          Archive: $URL
+          sha256: $SHA256"

.gitignore

@@ -1,3 +1,4 @@
 dist/
 node_modules/
 .DS_Store
+*.swp

.serena/.gitignore

@@ -0,0 +1,2 @@
+/cache
+/project.local.yml