@resolveio/server-lib 22.2.33 → 22.2.34

package/.github/workflows/ai-assistant-nightly-eval.yml

@@ -0,0 +1,224 @@
+name: AI Assistant Nightly Eval
+
+on:
+  schedule:
+    - cron: '20 6 * * *'
+  workflow_dispatch:
+    inputs:
+      server_dir:
+        description: 'Absolute path to server dir that has settings + data access'
+        required: false
+        default: ''
+        type: string
+      settings_file:
+        description: 'Settings filename relative to server_dir (example: settings.local.json)'
+        required: false
+        default: 'settings.local.json'
+        type: string
+      app_id:
+        description: 'App ID override (defaults to parent folder name of server_dir)'
+        required: false
+        default: ''
+        type: string
+      corpus_max_prompts:
+        description: 'Max prompts to include in corpus build'
+        required: false
+        default: '80'
+        type: string
+      corpus_lookback_days:
+        description: 'Lookback days for corpus harvesting'
+        required: false
+        default: '45'
+        type: string
+      corpus_run_limit:
+        description: 'Max corpus replay cases to execute'
+        required: false
+        default: '40'
+        type: string
+      codex_model:
+        description: 'Model override (example: gpt-5.3-codex)'
+        required: false
+        default: ''
+        type: string
+      fail_on_eval_errors:
+        description: 'Fail workflow when parity/replay/triage reports errors'
+        required: false
+        default: true
+        type: boolean
+
+concurrency:
+  group: ai-assistant-nightly-eval-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  assistant-nightly-eval:
+    runs-on: self-hosted
+    timeout-minutes: 360
+    env:
+      AI_ASSISTANT_EVAL_SERVER_DIR: ${{ vars.AI_ASSISTANT_EVAL_SERVER_DIR }}
+      AI_ASSISTANT_EVAL_SETTINGS: ${{ vars.AI_ASSISTANT_EVAL_SETTINGS }}
+      AI_ASSISTANT_EVAL_APP_ID: ${{ vars.AI_ASSISTANT_EVAL_APP_ID }}
+      AI_ASSISTANT_EVAL_USER_ID: ${{ vars.AI_ASSISTANT_EVAL_USER_ID }}
+      AI_ASSISTANT_CODEX_MODEL_DEFAULT: ${{ vars.AI_ASSISTANT_CODEX_MODEL }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Resolve Eval Environment
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [[ -z "${OPENAI_API_KEY:-}" ]]; then
+            echo "::error::OPENAI_API_KEY secret is required for AI assistant eval runs."
+            exit 1
+          fi
+
+          SERVER_DIR="${{ github.event.inputs.server_dir || '' }}"
+          if [[ -z "$SERVER_DIR" ]]; then
+            SERVER_DIR="${AI_ASSISTANT_EVAL_SERVER_DIR:-}"
+          fi
+          if [[ -z "$SERVER_DIR" ]]; then
+            FALLBACK="$GITHUB_WORKSPACE/../resolveio-all/geochem/server"
+            if [[ -d "$FALLBACK" ]]; then
+              SERVER_DIR="$FALLBACK"
+            fi
+          fi
+          if [[ -z "$SERVER_DIR" || ! -d "$SERVER_DIR" ]]; then
+            echo "::error::Could not resolve a valid server directory. Provide workflow input 'server_dir' or repo var 'AI_ASSISTANT_EVAL_SERVER_DIR'."
+            exit 1
+          fi
+
+          SETTINGS_FILE="${{ github.event.inputs.settings_file || '' }}"
+          if [[ -z "$SETTINGS_FILE" ]]; then
+            SETTINGS_FILE="${AI_ASSISTANT_EVAL_SETTINGS:-settings.local.json}"
+          fi
+
+          APP_ID="${{ github.event.inputs.app_id || '' }}"
+          if [[ -z "$APP_ID" ]]; then
+            APP_ID="${AI_ASSISTANT_EVAL_APP_ID:-$(basename "$(dirname "$SERVER_DIR")")}"
+          fi
+
+          CODEX_MODEL="${{ github.event.inputs.codex_model || '' }}"
+          if [[ -z "$CODEX_MODEL" ]]; then
+            CODEX_MODEL="${AI_ASSISTANT_CODEX_MODEL_DEFAULT:-}"
+          fi
+
+          echo "AI_ASSISTANT_CORPUS_SERVER_DIR=$SERVER_DIR" >> "$GITHUB_ENV"
+          echo "AI_ASSISTANT_PARITY_SERVER_DIR=$SERVER_DIR" >> "$GITHUB_ENV"
+          echo "AI_ASSISTANT_CORPUS_SETTINGS=$SETTINGS_FILE" >> "$GITHUB_ENV"
+          echo "AI_ASSISTANT_PARITY_SETTINGS=$SETTINGS_FILE" >> "$GITHUB_ENV"
+          echo "AI_ASSISTANT_CORPUS_APP_ID=$APP_ID" >> "$GITHUB_ENV"
+          echo "AI_ASSISTANT_PARITY_APP_ID=$APP_ID" >> "$GITHUB_ENV"
+          echo "AI_ASSISTANT_CORPUS_MAX_PROMPTS=${{ github.event.inputs.corpus_max_prompts || '80' }}" >> "$GITHUB_ENV"
+          echo "AI_ASSISTANT_CORPUS_LOOKBACK_DAYS=${{ github.event.inputs.corpus_lookback_days || '45' }}" >> "$GITHUB_ENV"
+          echo "AI_ASSISTANT_CORPUS_RUN_LIMIT=${{ github.event.inputs.corpus_run_limit || '40' }}" >> "$GITHUB_ENV"
+          if [[ -n "${AI_ASSISTANT_EVAL_USER_ID:-}" ]]; then
+            echo "AI_ASSISTANT_CORPUS_USER_ID=${AI_ASSISTANT_EVAL_USER_ID}" >> "$GITHUB_ENV"
+          fi
+          if [[ -n "$CODEX_MODEL" ]]; then
+            echo "AI_ASSISTANT_CODEX_MODEL=$CODEX_MODEL" >> "$GITHUB_ENV"
+          fi
+
+          echo "Resolved server_dir=$SERVER_DIR"
+          echo "Resolved settings_file=$SETTINGS_FILE"
+          echo "Resolved app_id=$APP_ID"
+
+      - name: Build Query Corpus
+        id: corpus_build
+        shell: bash
+        run: npm run ai-assistant-corpus-build
+
+      - name: Run Data Parity E2E
+        id: data_parity
+        continue-on-error: true
+        shell: bash
+        run: npm run ai-assistant-data-parity-e2e
+
+      - name: Run Corpus Replay E2E
+        id: corpus_replay
+        continue-on-error: true
+        shell: bash
+        run: npm run ai-assistant-corpus-replay-e2e
+
+      - name: Build Failure Triage + Clusters
+        id: eval_triage
+        if: always()
+        continue-on-error: true
+        shell: bash
+        run: npm run ai-assistant-eval-triage
+
+      - name: Upload Eval Artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: ai-assistant-eval-${{ github.run_id }}
+          retention-days: 21
+          if-no-files-found: warn
+          path: |
+            tmp/ai-assistant-query-corpus.json
+            tmp/ai-assistant-data-parity-e2e-output.json
+            tmp/ai-assistant-corpus-replay-e2e-output.json
+            tmp/ai-assistant-eval-triage.json
+            tmp/ai-assistant-eval-triage.md
+
+      - name: Publish Summary
+        if: always()
+        shell: bash
+        run: |
+          set -euo pipefail
+          if [[ -f tmp/ai-assistant-eval-triage.md ]]; then
+            cat tmp/ai-assistant-eval-triage.md >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "No triage markdown generated." >> "$GITHUB_STEP_SUMMARY"
+          fi
+          if [[ -f tmp/ai-assistant-eval-triage.json ]]; then
+            node <<'NODE' >> "$GITHUB_STEP_SUMMARY"
+          const fs = require('fs');
+          const triagePath = 'tmp/ai-assistant-eval-triage.json';
+          const triage = JSON.parse(fs.readFileSync(triagePath, 'utf8'));
+          const top = (triage?.allFailures?.priorityClusters || []).slice(0, 5);
+          console.log('');
+          console.log('### Top Priority Clusters');
+          if (!top.length) {
+          	console.log('- None');
+          	process.exit(0);
+          }
+          top.forEach((cluster, index) => {
+          	console.log(`${index + 1}. ${cluster.name} (score=${cluster.score}, cases=${cluster.count})`);
+          });
+NODE
+          fi
+
+      - name: Enforce Eval Status
+        if: always()
+        shell: bash
+        run: |
+          set -euo pipefail
+          FAIL_ON_ERRORS="${{ github.event_name != 'workflow_dispatch' || github.event.inputs.fail_on_eval_errors == 'true' }}"
+          if [[ "$FAIL_ON_ERRORS" != "true" ]]; then
+            echo "Eval status enforcement disabled by workflow input."
+            exit 0
+          fi
+
+          PARITY_OUTCOME="${{ steps.data_parity.outcome }}"
+          REPLAY_OUTCOME="${{ steps.corpus_replay.outcome }}"
+          TRIAGE_OUTCOME="${{ steps.eval_triage.outcome }}"
+          if [[ "$PARITY_OUTCOME" != "success" || "$REPLAY_OUTCOME" != "success" || "$TRIAGE_OUTCOME" != "success" ]]; then
+            echo "::error::AI assistant eval reported failures. Check uploaded artifacts and triage summary."
+            exit 1
+          fi

package/.github/workflows/ai-assistant-pr-guardrails.yml

@@ -0,0 +1,60 @@
+name: AI Assistant PR Guardrails
+
+on:
+  pull_request:
+    branches:
+      - '**'
+    paths:
+      - '.github/workflows/ai-assistant-pr-guardrails.yml'
+      - 'src/methods/ai-terminal.ts'
+      - 'src/services/codex-client.ts'
+      - 'tests/ai-assistant-utils.test.ts'
+      - 'tests/ai-assistant-routing-eval.test.ts'
+      - 'tests/ai-assistant-eval-triage.ts'
+      - 'tests/ai-assistant-corpus-build.ts'
+      - 'tests/ai-assistant-data-parity-e2e.ts'
+      - 'tests/ai-assistant-corpus-replay-e2e.ts'
+      - 'package.json'
+      - 'package-lock.json'
+  workflow_dispatch:
+
+concurrency:
+  group: ai-assistant-pr-guardrails-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  ai-assistant-guardrails:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Run AI Assistant Utils Tests
+        run: npm run ai-assistant-utils-test
+
+      - name: Run AI Assistant Routing Eval Tests
+        run: npm run ai-assistant-routing-eval-test
+
+      - name: Publish Summary
+        if: always()
+        shell: bash
+        run: |
+          set -euo pipefail
+          echo "## AI Assistant PR Guardrails" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "- \`ai-assistant-utils-test\`: completed" >> "$GITHUB_STEP_SUMMARY"
+          echo "- \`ai-assistant-routing-eval-test\`: completed" >> "$GITHUB_STEP_SUMMARY"

package/.nodemon.json

@@ -0,0 +1,5 @@
+{
+    "events": {
+        "exit": "npm run stop-server"
+   }
+}

package/.vscode/settings.json

@@ -0,0 +1,21 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+    "editor.minimap.enabled": false,
+	"javascript.preferences.importModuleSpecifier": "relative",
+	"typescript.preferences.importModuleSpecifier": "relative",
+	"javascript.preferences.quoteStyle": "single",
+	"git.ignoreLimitWarning": true,
+	"editor.codeActionsOnSave": {
+	  "source.organizeImports": "explicit",
+	  "source.fixAll.eslint": "always"
+	},
+	"eslint.validate": [
+	  "typescript",
+	  "javascript",
+	  "typescriptreact",
+	  "javascriptreact",
+	  "html"
+	],
+	"eslint.run": "onType",
+	"eslint.enable": true
+}

package/AGENTS.md

@@ -0,0 +1,179 @@
+# AGENTS.md
+
+## Overview
+resolveio-server-lib provides the backend infrastructure for the ResolveIO platform. It exposes server methods, publications, queues, and worker coordination so heavy work runs off the main thread.
+
+> Written for contributors and for GitHub Copilot / OpenAI Codex to learn the library.
+
+---
+
+## Architecture
+resolveio-server-lib is a Node 22 / TypeScript library built on Mongo 8 (never use Mongoose). The core server connects through a custom Mongo wrapper and dispatches work to workers when clustered.
+
+### Directory Map
+```txt
+src/
+├─ collections/Mongo collection helpers
+├─ models/TypeScript interfaces & SimpleSchema
+├─ methods/loadXMethods() modules registering method handlers
+├─ publications/loadXPublications() modules registering subscriptions
+├─ managers/infrastructure managers (MethodManager, WebSocketManager, etc.)
+├─ cron/scheduled jobs
+├─ http/Express route helpers
+├─ util/shared utilities
+resolveio-server-app.tsbootstraps the server and connects to Mongo
+server-app.tsHTTP/WebSocket server for main & worker processes
+client-server-app.tsclient-facing entry for hybrid deployments
+```
+
+### Core Managers
+- MethodManager: registers method handlers via `methodManager.methods({ ... })`
+- SubscriptionManager: registers publications via `subscriptionManager.publications({ ... })`
+- WebSocketManager: tracks socket connections and emits messages
+- WorkerDispatcherManager & WorkerServerManager: queue and execute heavy jobs
+- CronManager: defines recurring jobs in `src/cron`
+- MongoManager & LocalLogManager: database and log helpers
+
+### Methods
+- Stateless functions invoked by clients.
+- Defined in `src/methods/*` using `loadXMethods` patterns.
+- Each method provides a `check` (SimpleSchema) and an async `function`.
+```ts
+export function loadFooMethods(methodManager: MethodManager) {
+	methodManager.methods({
+		doSomething: {
+			check: new SimpleSchema({ name: { type: String } }),
+			function: async function (name: string) {
+				// logic
+				return result;
+			},
+		},
+	});
+}
+```
+
+### Publications
+- Stream Mongo documents or computed data to subscribers.
+- Defined in `src/publications/*` using `loadXPublications`.
+- Publication objects declare `function`, optional `check`, and affected `collections`.
+```ts
+export function loadFlagsPublications(subscriptionManager: SubscriptionManager) {
+	subscriptionManager.publications({
+		flagWithType: {
+			function: (flagType: string) => Flags.findOne({ type: flagType }),
+			check: new SimpleSchema({ flagType: { type: String } }),
+			collections: ['flags'],
+		},
+	});
+}
+```
+
+### Worker & Queue Agents
+- Heavy or blocking work should be dispatched to worker servers.
+- Use `WorkerDispatcherManager.enqueue(task)` for background processing.
+- Cron jobs live in `src/cron` and register through `CronManager`.
+
+---
+
+## Coding Conventions
+- Tabs for indentation, newline `else if`, opening brace on same line.
+- No `find` in loops; batch fetch then `bulkWrite`.
+- Separate validation, data retrieval, and processing blocks.
+- Use `async/await` with `try/catch`.
+- Never use `Math.round`; always use `round` from the ResolveIO client/server libraries.
+- Use `async/await` with `try/catch` instead of `.then()`/`.catch()`/`.finally()`.
+- Never leave unused variables, parameters, or imports; remove or refactor instead of suppressing lint.
+- Never construct Promises or use `.then()`/`.catch()`/`.finally()`; use `async/await` + `try/catch`.
+- Never leave promises floating; `await` or `return` every async call (including `Promise.all`).
+- Do not `await` inside `forEach`; use `for...of` or `Promise.all` with `map`.
+- Every async method must `await` at least one call (Mongo transactions).
+- Follow the `eslint.ts` rules.
+- Models and collections must mirror each other at all times.
+
+```ts
+if (x > 3) {
+	console.log(1);
+}
+else if (x === 2) {
+	console.log(2);
+}
+else {
+	console.log(3);
+}
+```
+
+---
+
+## Formatting & Linting
+- `.editorconfig`, `.prettierrc.json`, and `.vscode/settings.json` enforce tabs and 120-column width.
+- Always open `eslint.config.js` in this project before coding and follow its rules; do not assume defaults from other repos.
+- Run lint before committing:
+```bash
+npx eslint .
+```
+
+---
+
+## Quick Start
+```bash
+npm install
+npm run build
+npm start
+```
+
+---
+
+## PR Checklist
+- Tabs only; `else`/`else if` start on new lines.
+- Avoid `find` in loops; use `bulkWrite`.
+- Use transactions when multiple writes must succeed atomically.
+- Offload heavy work to workers.
+- Run `npx eslint .` before committing.
+
+---
+
+## Response Requirements
+
+- Include a customer-facing summary of the request and the estimated the number of human hours an advanced ResolveIO engineer would take to fully complete the task including testing.
+- Include a work ticket summary (what was done) and the estimated the number of human hours an advanced ResolveIO engineer would take to fully complete the task including testing.
+
+---
+
+## Anti-Patterns
+- Converting tabs to spaces.
+- `updateOne` or `find` in loops.
+- Blocking work on the main server.
+- Deep nesting without early returns.
+
+## STRING _id POLICY
+- `_id` values are always strings in this codebase.
+- Generate `_id` values with `objectIdHexString()`.
+- Never use MongoDB `ObjectId` values or assumptions for `_id`.
+- For bulk writes (`insertMany`, `bulkWrite`, batch upserts), always set `_id` explicitly as a string before writing.
+- Never let MongoDB auto-generate `_id`, because that can create `ObjectId`-style ids.
+
+## RESOLVEIO LIBRARY SOURCE-OF-TRUTH POLICY
+- Never use `patch-package` for any `@resolveio/*` library changes.
+- Never patch `node_modules/@resolveio/*` as the primary fix path.
+- Always implement fixes in the actual source library repo (for example `resolveio-server-lib` or `resolveio-client-lib`).
+- After applying a library-source fix, explicitly report:
+  - Why the fix had to be made in the library source (root cause and ownership).
+  - What downstream impact to expect (version bump/publish, consumer upgrades, rollout risk, and compatibility considerations).
+
+## AI Terminal Boundary Policy
+
+- Keep `resolveio-server-lib/src/methods/ai-terminal.ts` strictly platform-generic (`server-lib` / core ResolveIO only).
+- Do not add app-specific names, app-only aliases, app-specific field fallbacks, or app-specific branching logic in `server-lib` AI terminal code.
+- Put app-specific AI behavior in the app repo layer (for example `server/src/ai/assistant-heuristics.json` and app-level method/config wiring), not in `resolveio-server-lib`.
+
+## Distinct Filter Guidance
+
+- For list/filter dropdowns, use distinct-backed options from the underlying collection data wherever practical instead of hardcoded option lists.
+- Prefer list-template distinct filter support (`optionsDistinctKey`, `distinctQuery`, `distinctSort`, `distinctCollection`) when using `resolveio-list-template`.
+- Keep an explicit "All" option for optional filters and ensure labels/values map to the true stored field values.
+- Use hardcoded options only when values are truly fixed business enums that should not vary by dataset.
+
+## Rio Select Form-Control Rule
+
+- Never apply Bootstrap `form-control` to `rio-select` (including `class="form-control"`). Use component-specific classes for `rio-select` styling.
+- Never apply Bootstrap `form-control` to `rio-date-picker` (including `class="form-control"`). Use component-specific classes for `rio-date-picker` styling.

package/README.md

@@ -0,0 +1,22 @@
+## Copyright
+
+Copyright © 2017-2019 ResolveIO, LLC. All Rights Reserved. This work is to be used/viewed by ResolveIO, LLC Employees ONLY.
+
+## ResolveIO Command Line
+
+- `$ npm run server` - Run the server application.
+- `$ npm run build-prod` - Build production (dist folder).
+- `$ npm run package` - Build tarball for npm publish (version inside package json, must rebuild if changed)
+- `$ npm publish ./resolveio-server-lib-x.x.x.tgz` - Publish tarball to npm
+
+## Contents
+
+This package contains:
+
+- ResolveIO Server Library
+
+### Server
+
+The `server` folder contain single TypeScript (`.ts`) file which is the main file (`/server/src/index.ts`), and creates both connections to client-database and resolveio-support database, then creates the main server instance, and then starts it.
+
+All other server files should be located under `/server/src/*`.

package/build_package.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+source ~/.nvm/nvm.sh   # Ensure this path is correct for your nvm installation
+nvm use 22
+npm run build-prod
+npm pack ./dist

package/compileDTS.pl

@@ -0,0 +1,64 @@
+use strict;
+use warnings;
+use JSON;
+
+my @allIds;
+
+my $dir = './dist';
+
+my $extraFiles = '';
+
+search_dir($dir);
+
+sub search_dir {
+
+    my ($locdir) = @_;
+    # print "Entered search_dir sub, working with directory => $locdir \n";
+    my $dh; # handle
+
+    if ( !opendir ($dh, $locdir)) {
+        warn "Unable to open $locdir: $!\n";
+        return;
+    }
+    
+    my @FILES = grep { $_ ne '.' && $_ ne '..' } readdir($dh);
+        
+    foreach my $file (@FILES) {
+        my $path = "$locdir/$file";    
+        if ( -d $path ) {
+            # print "Directory $path found\n";
+            search_dir ($path); 
+        }
+        else {
+            if ($file =~ m/.d.ts/ and $file !~ m/index.d.ts/) {
+                # print "Open file $path\n";
+                open (FILE, "<", "$path");
+                my @lines = <FILE>;
+                close FILE;
+                chomp @lines;
+
+                for (my $k = 0; $k < scalar(@lines); $k++) {
+					if ($lines[$k] =~ m/^export / and $lines[$k] !~ m/export {};/) {
+						$extraFiles .= $lines[$k] . "\n";
+
+						if ($lines[$k] =~ m/\{\s*$/) {
+							while($lines[++$k] !~ m/^\};?\s*$/) {
+								$extraFiles .= $lines[$k] . "\n";
+							}
+
+							$extraFiles .= $lines[$k] . "\n";
+						}
+					}
+				}
+            }
+        }
+    }
+
+    closedir ($dh);
+}
+
+print "Extras\n\n$extraFiles";
+
+open (FILE, ">>", "./dist/index.d.ts");
+print FILE "\n$extraFiles";
+close FILE;

package/docs/ai-assistant-nightly-eval.md

@@ -0,0 +1,65 @@
+# AI Assistant Nightly Eval
+
+This repo now includes a scheduled workflow at:
+
+- `.github/workflows/ai-assistant-nightly-eval.yml`
+- `.github/workflows/ai-assistant-pr-guardrails.yml`
+
+It runs:
+
+1. `npm run ai-assistant-corpus-build`
+2. `npm run ai-assistant-data-parity-e2e`
+3. `npm run ai-assistant-corpus-replay-e2e`
+4. `npm run ai-assistant-eval-triage`
+
+Artifacts are uploaded from `tmp/` and the workflow summary includes top prioritized failure clusters.
+
+PR guardrails run on pull requests and execute:
+
+1. `npm run ai-assistant-utils-test`
+2. `npm run ai-assistant-routing-eval-test`
+
+## Required GitHub Setup
+
+Set the secret:
+
+- `OPENAI_API_KEY`
+
+Set repository variables (recommended):
+
+- `AI_ASSISTANT_EVAL_SERVER_DIR`: absolute path to server folder with settings and data access
+- `AI_ASSISTANT_EVAL_SETTINGS`: settings filename (default `settings.local.json`)
+- `AI_ASSISTANT_EVAL_APP_ID`: app id override (optional)
+- `AI_ASSISTANT_EVAL_USER_ID`: user id override for corpus replay/build (optional)
+- `AI_ASSISTANT_CODEX_MODEL`: model override (optional)
+
+## Running Manually
+
+Use **Actions -> AI Assistant Nightly Eval -> Run workflow**.
+
+Optional dispatch inputs:
+
+- `server_dir`
+- `settings_file`
+- `app_id`
+- `corpus_max_prompts`
+- `corpus_lookback_days`
+- `corpus_run_limit`
+- `codex_model`
+- `fail_on_eval_errors`
+
+## Output Files
+
+Main outputs:
+
+- `tmp/ai-assistant-query-corpus.json`
+- `tmp/ai-assistant-data-parity-e2e-output.json`
+- `tmp/ai-assistant-corpus-replay-e2e-output.json`
+- `tmp/ai-assistant-eval-triage.json`
+- `tmp/ai-assistant-eval-triage.md`
+
+The triage JSON now includes:
+
+- `allFailures.intentBuckets`
+- `allFailures.collectionBuckets`
+- `allFailures.priorityClusters`

package/docs/ai-assistant-preflight-checklist.md

@@ -0,0 +1,23 @@
+# AI Assistant Preflight Checklist
+
+Run this checklist before broader assistant evals.
+
+1. Lock deterministic runtime knobs in `settings.development.json`:
+- `AI_ASSISTANT_CODEX_PLANNER_ENABLED`
+- `AI_ASSISTANT_FAST_MODE_ENABLED`
+- `AI_ASSISTANT_ALWAYS_ALLOW_PROBE`
+- `AI_ASSISTANT_RUN_BUDGET_MS`
+- `AI_ASSISTANT_MONGO_MAX_TIME_MS`
+- `AI_ASSISTANT_CODEX_TIMEOUT_MS`
+
+2. Run focused assistant tests:
+- `npm run ai-assistant-utils-test`
+- `npm run ai-assistant-routing-eval-test`
+
+3. Validate the preflight prompt matrix:
+- `npm run ai-assistant-preflight-matrix`
+- Optional JSON output: `npm run ai-assistant-preflight-matrix -- --json`
+
+4. Use safe config copies when sharing logs/results:
+- Share `settings.development.redacted.json` (not `settings.development.json`)
+- Do not post raw secrets/tokens in issue comments or eval reports.