chore(refiner): stabilize docs, Playwright config, and test adjustments

Minor tweaks to enterprise-release-gates.md, operator-testing.md, README,
playwright.config.ts port/timeout settings, index.ts export alignment,
and test fixture updates for dashboard.spec.ts, index.test.ts, and
register-global.test.ts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Aitomates

docs/enterprise-release-gates.md

@@ -27,6 +27,12 @@ For exact operator commands, current evidence, and the gate-to-CI mapping, see [
 12. Secret scanning finds no committed credentials.
 13. Linux, Windows, and dashboard E2E CI jobs pass before merge.
 
+## Port Policy
+
+- The operator dashboard/runtime port is fixed at `3000` and should be referenced as `http://127.0.0.1:3000`.
+- The dashboard browser E2E gate uses fixed test port `3999` by default to avoid colliding with an already-running operator dashboard.
+- Package-runtime acceptance may print a random ephemeral health-check port. That port is a test isolation detail, not a configuration value.
+
 ## Current Coverage Baseline
 
 The first measured baseline on June 14, 2026 exposed substantial untested production behavior:

docs/operator-testing.md

@@ -17,6 +17,7 @@ This is the latest known-good baseline at the time this guide was updated:
 | Local test count | 51 test files, 382 tests |
 | Coverage | 100% statements, branches, functions, and lines |
 | Local runtime health | `/api/health` returned `runtime.status: online` |
+| Operator dashboard port | `3000` (`http://127.0.0.1:3000`) |
 | Local semantic provider | `http://localhost:11434`, models `gemma3:12b` and `gemma3` |
 
 Treat this table as evidence, not a permanent guarantee. When any product behavior changes, rerun the gate and update this baseline.
@@ -94,6 +95,12 @@ Expected result:
 - Package dry-run passes.
 - `acceptance:package-runtime` installs the packed tarball into a temporary global prefix and serves `/api/health`.
 
+Port policy:
+
+- Operator dashboard/runtime: fixed to `3000`.
+- Dashboard E2E: fixed to `3999` by default through `PROMPT_REFINER_E2E_PORT` so browser tests do not collide with an operator runtime.
+- Package runtime smoke: intentionally uses an ephemeral random port to avoid CI and local conflicts. The `<port>` printed by that test is not the operator dashboard port and should not be copied into setup instructions.
+
 If this command fails, do not bypass it. Fix the failing behavior or document an explicit, reviewed exception in this file and in `docs/enterprise-release-gates.md`.
 
 ## 3. Check Global MCP Registration
@@ -156,6 +163,7 @@ Get-CimInstance Win32_Process |
   ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
 
 $env:PROMPT_REFINER_BACKGROUND = 'true'
+$env:PROMPT_REFINER_DASHBOARD_PORT = '3000'
 Start-Process -WindowStyle Hidden -FilePath node -ArgumentList (Join-Path $repo 'dist\src\index.js') -WorkingDirectory $repo
 ```
 
@@ -199,7 +207,7 @@ Expected result:
 Package runtime smoke passed: installed universal-refiner-8.0.0 and served /api/health on <port>.
 ```
 
-This catches missing production dependencies that are hidden by the local workspace.
+This catches missing production dependencies that are hidden by the local workspace. The `<port>` value is intentionally ephemeral for test isolation; the operator dashboard remains fixed at `http://127.0.0.1:3000`.
 
 ## 8. Confirm GitHub CI
 

universal-refiner/README.md

@@ -9,12 +9,16 @@ model or MCP sampling fallback.
 ```powershell
 # From the universal-refiner directory
 npm run build
+$env:PROMPT_REFINER_BACKGROUND = 'true'
+$env:PROMPT_REFINER_DASHBOARD_PORT = '3000'
 node dist/src/index.js
 ```
 
 The server registers as an MCP stdio transport. Global registration is managed by
 `scripts/operations/register-global.ps1`.
 
+The operator dashboard is fixed at `http://127.0.0.1:3000`. Use `PROMPT_REFINER_DASHBOARD_PORT` only when intentionally testing an alternate local port; the generic `PORT` variable remains a compatibility fallback.
+
 ## Local Model Configuration
 
 `refine_prompt` routes semantic refinement through `LocalOpenAiProvider` first (tier-0),

universal-refiner/playwright.config.ts

@@ -1,5 +1,8 @@
 import { defineConfig, devices } from '@playwright/test';
 
+const e2ePort = process.env.PROMPT_REFINER_E2E_PORT || '3999';
+const e2eBaseUrl = `http://localhost:${e2ePort}`;
+
 export default defineConfig({
   testDir: './tests/e2e',
   fullyParallel: true,
@@ -8,7 +11,7 @@ export default defineConfig({
   workers: process.env.CI ? 1 : undefined,
   reporter: 'html',
   use: {
-    baseURL: 'http://localhost:3999',
+    baseURL: e2eBaseUrl,
     trace: 'on-first-retry',
   },
   projects: [
@@ -19,12 +22,12 @@ export default defineConfig({
   ],
   webServer: {
     command: 'npm run start',
-    url: 'http://localhost:3999',
+    url: e2eBaseUrl,
     reuseExistingServer: !process.env.CI,
     timeout: 10000,
     env: {
       PROMPT_REFINER_BACKGROUND: 'true',
-      PORT: '3999'
+      PROMPT_REFINER_DASHBOARD_PORT: e2ePort
     }
   },
 });

universal-refiner/src/index.ts

@@ -6,8 +6,9 @@ import { RuntimeLogger } from "./core/logger.js";
 import * as path from "path";
 import { AgenticBlackboard } from "./core/blackboard.js";
 import { EventStore } from "./history/event-store.js";
+import { resolveDashboardPort } from "./core/ports.js";
 
-const port = parseInt(process.env.PORT || "3000", 10);
+const port = resolveDashboardPort();
 const rootPath = path.resolve(process.cwd());
 const backgroundMode = process.env.PROMPT_REFINER_BACKGROUND === "true";
 if (backgroundMode) {

universal-refiner/tests/e2e/dashboard.spec.ts

@@ -14,7 +14,7 @@ test.describe('Intelligence Hub Dashboard UI', () => {
       }
     });
 
-    await page.goto('http://localhost:3999');
+    await page.goto('/');
   });
 
   test('should load the dashboard and display the sidebar and projects', async ({ page }) => {
@@ -68,7 +68,7 @@ test.describe('Intelligence Hub Dashboard UI', () => {
   test('should render newly ingested proxy prompts in the global stream', async ({ page, request }) => {
     // 1. Programmatically send a prompt via the proxy endpoint
     const uniquePrompt = `Automated Proxy Stream Test - ${Date.now()}`;
-    const proxyResponse = await request.post('http://localhost:3999/proxy/v1/chat/completions', {
+    const proxyResponse = await request.post('/proxy/v1/chat/completions', {
       data: {
         messages: [{ role: 'user', content: uniquePrompt }]
       }

universal-refiner/tests/index.test.ts

@@ -61,6 +61,7 @@ describe("runtime bootstrap", () => {
     mocks.dashboardStop.mockResolvedValue(undefined);
     mocks.flush.mockResolvedValue(undefined);
     delete process.env.PORT;
+    delete process.env.PROMPT_REFINER_DASHBOARD_PORT;
     delete process.env.PROMPT_REFINER_BACKGROUND;
   });
 
@@ -90,6 +91,7 @@ describe("runtime bootstrap", () => {
   });
 
   it("starts background ownership explicitly and exits on fatal server failure", async () => {
+    process.env.PROMPT_REFINER_DASHBOARD_PORT = "3000";
     process.env.PORT = "4321";
     process.env.PROMPT_REFINER_BACKGROUND = "true";
     const error = new Error("startup failed");
@@ -100,7 +102,7 @@ describe("runtime bootstrap", () => {
     await import("../src/index.js");
     await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1));
 
-    expect(mocks.dashboardStart).toHaveBeenCalledWith(4321, process.cwd());
+    expect(mocks.dashboardStart).toHaveBeenCalledWith(3000, process.cwd());
     expect(mocks.watcherStart).toHaveBeenCalledOnce();
     const changeHandler = mocks.watcherOn.mock.calls.find(call => call[0] === "change")?.[1];
     changeHandler({ event: "change", path: `${process.cwd()}\\src\\a.ts` });

universal-refiner/tests/register-global.test.ts

@@ -103,7 +103,7 @@ describeIfPowerShell("global registration doctor", () => {
     expect(result.stdout + result.stderr).toContain("$.apiKey");
     expect(result.stdout + result.stderr).not.toContain("do-not-print-this");
     expect(existsSync(join(root, ".claude.json"))).toBe(false);
-  });
+  }, 45_000);
 
   it("refuses to merge invalid JSON without overwriting it", () => {
     const root = makeRoot();