docs: portfolio audit — Node 22 alignment, verify bar, docs-link-check

.github/workflows/docs-link-check.yml

@@ -0,0 +1,30 @@
+name: docs-link-check
+on:
+  pull_request:
+    paths:
+      - '**.md'
+      - 'docs/**'
+  push:
+    branches: [main, master]
+    paths:
+      - '**.md'
+      - 'docs/**'
+
+permissions:
+  contents: read
+
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Markdown link check
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --no-progress
+            --exclude-loopback
+            --exclude '^https://www\.gartner\.com/'
+            --exclude '^https://www\.wolterskluwer\.com/'
+            '**/*.md'
+          fail: true

.nvmrc

@@ -0,0 +1 @@
+22

AGENTS.md

@@ -2,15 +2,11 @@
 
 ## Merge / handoff verification bar
 
-Run in order (fix failures before merge or handoff):
-
 ```bash
 ./scripts/verify.sh
-npm run verify
 ```
 
-`./scripts/verify.sh` is the harness Definition of Done wrapper; it delegates to `npm run verify`.
-Defined as: **`eslint` → `tsc --noEmit` → `vitest run`**. Same as CI `verify` job (without Playwright).
+Harness Definition of Done — delegates to `npm run verify` (`eslint` → `tsc --noEmit` → `vitest run`). Same as CI `verify` job (without Playwright).
 
 **Enterprise / technical diligence:** keep [docs/architecture-map.md](docs/architecture-map.md), [docs/workflow-depth.md](docs/workflow-depth.md), [docs/procurement-readiness.md](docs/procurement-readiness.md), and [docs/approval-workflow.md](docs/approval-workflow.md) aligned with real behavior when you change workflows, RBAC, retention, approvals, or integrations. Documentation index: [docs/README.md](docs/README.md); source tree: [docs/codebase-layout.md](docs/codebase-layout.md). For **staging / business UAT**, use [docs/qa/staging-uat-desk-to-field.md](docs/qa/staging-uat-desk-to-field.md); for **transactional `writeAuditLog` completeness**, maintain [docs/qa/mutation-auditability-matrix.md](docs/qa/mutation-auditability-matrix.md) when adding regulated mutations. After large router or delegation refactors, run **`npm run audit:matrix-greps`** (`scripts/audit-matrix-greps.sh`; **ripgrep** preferred, `find`+`grep` fallback) and refresh the matrix prose if counts shift. **Cursor MCP vs ship path:** contributors using IDE tool connections should follow [docs/cursor-tool-connections-deployment.md](docs/cursor-tool-connections-deployment.md) so staging/prod stay GitHub-/Vercel-/EKS-authoritative—not MCP-authoritative.
 

CHANGELOG.md

@@ -24,7 +24,7 @@
 
 ### Bug Fixes
 
-* **security:** per-org inbound secrets and SSRF-safe operational webhooks ([#39](https://github.com/SafetyMP/Autonomous-EHS-Management/issues/39)) ([f02e882](https://github.com/SafetyMP/Autonomous-EHS-Management/commit/f02e88233603c7ed4b76a051885ce66229e638e7)), closes [hi#severity](https://github.com/hi/issues/severity)
+* **security:** per-org inbound secrets and SSRF-safe operational webhooks ([#39](https://github.com/SafetyMP/Autonomous-EHS-Management/issues/39)) ([f02e882](https://github.com/SafetyMP/Autonomous-EHS-Management/commit/f02e88233603c7ed4b76a051885ce66229e638e7))
 
 ## [1.4.2](https://github.com/SafetyMP/Autonomous-EHS-Management/compare/v1.4.1...v1.4.2) (2026-07-06)
 

Dockerfile

@@ -32,7 +32,7 @@
 #   env at runtime   → ConfigMap + Secret (never commit raw Secret YAML with data)
 # =============================================================================
 
-FROM node:26-bookworm-slim AS base
+FROM node:22-bookworm-slim AS base
 WORKDIR /app
 # Disable Next telemetry in CI/images unless org policy wants it.
 ENV NEXT_TELEMETRY_DISABLED=1

README.md

@@ -48,13 +48,15 @@
 
 ## Quick start
 
+**Prerequisites:** Node.js **22.x** (see `.nvmrc`), npm, Docker (for demo Postgres). Matches CI and the production `Dockerfile`.
+
 1. **Clone and install:** `git clone <repo-url> && cd <repo-dir> && npm ci`  
    **Path tip:** Avoid a **working directory name with a trailing space** (some macOS / archive flows introduce `"…System "`). That can break scripts, tooling, and shell `cd` unless you always **quote paths**—prefer renaming the folder to remove stray spaces.
 2. **Configure:** pick a row in **Environment snapshots** below and copy the listed template to `.env.local` (fill secrets).
 3. **Run:**
    - **Docker demo:** `npm run demo:up` then `npm run dev` → [http://localhost:3000/sign-in](http://localhost:3000/sign-in) (details in [Turnkey local demo](#turnkey-local-demo-docker-postgres)).
    - **Your own Postgres:** `npm run db:migrate` then `SEED_ADMIN_EMAIL=you@company.com npm run db:seed` then `npm run dev`.
-4. **Before a PR:** `npm run verify` — same bar as CI ([AGENTS.md](AGENTS.md)).
+4. **Before a PR:** `./scripts/verify.sh` — harness DoD wrapper (same bar as `npm run verify` in CI). See [AGENTS.md](AGENTS.md).
 
 ## Environment snapshots
 

docs/cursor-tool-connections-deployment.md

@@ -73,4 +73,4 @@ Branch/preview URLs must avoid pointing at production `DATABASE_URL`. Treat prev
 ## Related documentation
 
 - [procurement-readiness.md — customer vs internal Cursor tooling](./procurement-readiness.md#customer-facing-integrations-vs-internal-cursor-tooling)
-- [REPO_SETUP.md § 10 Cursor IDE](./REPO_SETUP.md#10-cursor-ide-tool-connections-optional)
+- [REPO_SETUP.md § 11 Cursor IDE](../REPO_SETUP.md#11-cursor-ide-tool-connections-optional)

docs/procurement-readiness.md

@@ -1,6 +1,6 @@
 # Procurement readiness (strategy Pack)
 
-This document implements the **business and GTM** recommendations from the critique Pack at repo root: [`Autonomous Ehs Management Recommendations.pdf`](../Autonomous%20Ehs%20Management%20Recommendations.pdf).
+This document implements the **business and GTM** recommendations from the internal critique Pack (strategy PDF; not shipped in the public repo).
 
 It covers: ROI framing, pilot structure, economic moat narrative, implementation methodology, and repository presentation—**without** overstating shipped product scope.
 
@@ -158,7 +158,7 @@ Use this in **enterprise questionnaires** so buyers do not assume filing-ready a
 |-----------------|---------------|-------------------------|
 | **OSHA agency-formatted electronic filing** | **`compliance.regulatoryOsha.agencyExportPlaceholder` only** — not submission-ready ([`ROADMAP.md`](../ROADMAP.md) barriers, [`oshaAgencyExportScaffold.ts`](../src/lib/regulatory/oshaAgencyExportScaffold.ts)). | Program data and internal injury/illness exports may be available; **direct agency submission formats** require counsel review and additional product work. |
 | **Full DSAR automation** | Intake / policy surfaces exist; end-to-end export/erasure needs **counsel process** ([`ROADMAP.md`](../ROADMAP.md)). | Privacy tooling is **governance-aligned**, not a one-click “erase everything” guarantee. |
-| **Turnkey HRIS / Workday connector** | **iPaaS playbooks ship** ([`docs/runbooks/`](../runbooks/)); named vendor OAuth modules remain roadmap. Plan Workato/Boomi middleware + SCIM for PortCo pilots. Budget worksheet: [procurement-portco-integration-budget.md](./procurement-portco-integration-budget.md). |
+| **Turnkey HRIS / Workday connector** | **iPaaS playbooks ship** ([`docs/runbooks/`](./runbooks/)); named vendor OAuth modules remain roadmap. Plan Workato/Boomi middleware + SCIM for PortCo pilots. Budget worksheet: [procurement-portco-integration-budget.md](./procurement-portco-integration-budget.md). |
 | **Customer MCP server** | **Context Sync REST** ships; native MCP server **does not** ([adr/0001-mcp-context-sync-strategy.md](./adr/0001-mcp-context-sync-strategy.md)). | Agent read access is **governed REST**, not MCP-branded; Cursor MCP is **internal dev tooling only**. |
 | **Occupational health clinic depth** | Not targeted at Cority-class medical surveillance in v1. | Occupational health programs may need a **specialist module** or partner system. |
 | **Environmental regulatory permits vs PTW** | **Permits to work** (`/dashboard/permits`) are **field authorization** (PTW). **Environmental permits** (`/dashboard/environmental-permits`) are a **regulatory register** (metadata, renewals, conditions)—**not** agency filing-ready by default (see [COMPLIANCE.md](../COMPLIANCE.md)). | Buyers should map **Cority/Enablon-style** permit tracking to the environmental permit module + obligations/monitoring; **do not** conflate with PTW. |

docs/user-manual-ehs-console.md

@@ -242,7 +242,7 @@ Desk supervisors still see program **Needs attention** chips and KPI tiles; desk
 3. Optional: tap **Download command center CSV** (when the snapshot has loaded) to save the command-center figures your account may export—useful for leadership packs or audits.
 4. When data loads, note **Snapshot as of** *date/time* under the header (if shown)—figures reflect that moment.
 5. If **Needs attention:** appears, read the amber pill links for program-level alerts (personal approvals are deduplicated when shown in **Your work**).
-6. Integration backlog and scheduled job health moved to **[Integrations](/dashboard/integrations)** for administrators. Supervisors may also see a **PortCo pilot proof** panel summarizing integration health when your organization runs a portfolio pilot—details live on **Integrations**, not on the desk home.
+6. Integration backlog and scheduled job health moved to **Integrations** (`/dashboard/integrations`) for administrators. Supervisors may also see a **PortCo pilot proof** panel summarizing integration health when your organization runs a portfolio pilot—details live on **Integrations**, not on the desk home.
 7. Under **Key indicators**, scan tiles (supervisors see the full grid; contributors may see them collapsed). Integration and cron panels no longer appear on the desk home.
 8. Open **Recent activity** for a timestamped feed; links open record detail.
 9. Expand **ISO setup checklist** in the sidebar panel when aligning the management system.
@@ -1110,8 +1110,8 @@ Identity administrators, integration engineers, anyone granted **integration:rea
 ### SOP — Check status
 
 1. Open **Integrations**. Heading **Integrations**. Intro text explains events are readable with **`integration:read`** and points to NDJSON warehouse export—the following paragraphs list inbound URLs, bearer secrets, and doc paths for administrators.
-2. **PortCo identity (SCIM & OIDC JIT)** — when your role includes org admin controls, configure **SCIM 2.0** bearer tokens and **group→role mappings**, or **OIDC JIT claim rules** for multi-entity portfolios. Rotate tokens when counsel or IdP policy requires it. Engineering detail: [OIDC_JIT_PROVISIONING.md](../OIDC_JIT_PROVISIONING.md), [hris-portco-integration-playbook.md](../roadmap/hris-portco-integration-playbook.md).
-3. **HRIS platform & roster drift** — copy the **inbound URL** and **bearer secret** for iPaaS connectors; pick connector presets (Workday, ADP, BambooHR) when shown. Review **Roster drift** rows after nightly reconciliation; use **Reconcile now** when your runbook calls for manual follow-up. Connector runbooks: [docs/runbooks/](../runbooks/).
+2. **PortCo identity (SCIM & OIDC JIT)** — when your role includes org admin controls, configure **SCIM 2.0** bearer tokens and **group→role mappings**, or **OIDC JIT claim rules** for multi-entity portfolios. Rotate tokens when counsel or IdP policy requires it. Engineering detail: [OIDC_JIT_PROVISIONING.md](./OIDC_JIT_PROVISIONING.md), [hris-portco-integration-playbook.md](./roadmap/hris-portco-integration-playbook.md).
+3. **HRIS platform & roster drift** — copy the **inbound URL** and **bearer secret** for iPaaS connectors; pick connector presets (Workday, ADP, BambooHR) when shown. Review **Roster drift** rows after nightly reconciliation; use **Reconcile now** when your runbook calls for manual follow-up. Connector runbooks: [docs/runbooks/](./runbooks/).
 4. **Download NDJSON (500 newest)** gathers a downloadable slice once data returns (shows **Preparing export…** while running).
 5. **Connector field mapping (operator notes)** stores JSON mapping drafts per connector; pick **Connector** from the drop-down list, edit the textarea JSON, tap **Save mapping** (**Saving…** while storing).
 6. **Operational webhooks (org admin)** appears when permitted—under **Subscribe to** tick the operational event codes your stack needs, submit **Add webhook** (**Creating…** while busy), then manage listed endpoints with **Disable**, **Enable**, or **Delete**.
@@ -1122,7 +1122,7 @@ Command center may spotlight **Integration backlog (*N* failed)** with shortcuts
 
 ### Context Sync (org administrators)
 
-Separate from **Organization context (ISO 4)** above. When your role includes org admin controls, the **Context Sync (org admin)** panel on this page enables **governed REST read access** for IDE and agent tooling (`/api/contextsync/*`)—tenant opt-in, rate limits, and audit expectations apply. This is **not** a customer MCP server and **not** ISO scope editing. Engineering details: [procurement-integrations-appendix.md](../procurement-integrations-appendix.md).
+Separate from **Organization context (ISO 4)** above. When your role includes org admin controls, the **Context Sync (org admin)** panel on this page enables **governed REST read access** for IDE and agent tooling (`/api/contextsync/*`)—tenant opt-in, rate limits, and audit expectations apply. This is **not** a customer MCP server and **not** ISO scope editing. Engineering details: [procurement-integrations-appendix.md](./procurement-integrations-appendix.md).
 
 ### What if things go wrong?