# User Guide — Forge PM Work Order Simulation

> **FICTIONAL / SYNTHETIC DEPLOYMENT MODEL.** No real customer data is used.

## Prerequisites

- Node.js >= 20.
- The sibling package `../work-order-agents` with its dependencies installed
  (`@electric-sql/pglite`, `@grpc/grpc-js`, `@grpc/proto-loader`). This simulation
  imports the ecosystem from there and reuses its `node_modules` at runtime.

## Run the full simulation

```bash
node verify.mjs
```

This will:
1. Generate 100,000 deterministic synthetic work orders (seed `20260625`) and write
   the full corpus to `data/enterprise-work-orders.jsonl` (git-ignored, ~60 MB) plus
   a 1,000-row sample to `datasets/sample-1000.jsonl`.
2. Boot the real ecosystem (PGlite Postgres + gRPC dispatch).
3. Process every order through classify → route → validate → action.
4. Write `verification-report.json`, `verification-report.md`, and
   `evidence/{simulation-results.json, roi.json, audit-trace-sample.json}`.
5. Print a 25-check MUST_PASS summary and exit non-zero if any check fails.

A full run takes roughly 15–20 minutes (the ecosystem performs real SQL and a real
gRPC round trip per order). For a fast iteration loop, scale it down:

```bash
WO_SIM_N=2500 node verify.mjs
```

The synthetic mix is proportional, so small runs approximate the full-scale numbers.

## Build the reports

```bash
node build-deliverables.mjs    # regenerates report/impact-study.md + certification-report.md
```

These read `verification-report.json` so the narrative always matches the latest run.

## Publish the case-study page

```bash
node publish.mjs
```

Generates `../../published/forge-pm-work-order-sim/` (landing page, rendered docs,
downloadable package, and copied Proof Layer decision).

## Where the numbers come from

| You want | Look at |
| --- | --- |
| Operational metrics | `verification-report.md` / `.json` (`simulation`) |
| ROI math | `evidence/roi.json` and `report/impact-study.md` |
| The dataset schema | `datasets/dataset-card.md` + `datasets/dataset-manifest.json` |
| What is simulated vs. live | `proof/LIMITATIONS.md` |
| How to reproduce every number | `proof/REPRODUCE.md` |

## Interpreting the certification

The Proof Layer assigns the authoritative state. For this outcome it is not
`PRODUCTION_VALIDATED` by design (fictional customer + synthetic data). The
simulation-tier label `FICTIONAL_DEPLOYMENT_MODEL_CERTIFIED` means the simulation is
reproducible and internally validated — it is not a claim about a real deployment.
