@ohtaman/washi 0.3.0 → 0.5.0

package/docs/examples/transportation.md

@@ -0,0 +1,90 @@
+# Transportation & Allocation Network (LP)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Linear Programming (LP) | HiGHS (default) | `m.continuous()`, `m.constraint()`, `expr`, `minimize`, `dot` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=transportation">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/09-transportation-problem.ts">Source Code</a></li></ul> |
+
+The transportation problem is one of the most fundamental network optimization models: determine how many units to ship from each supply origin (factory) to each destination (store) to minimize total shipping cost while respecting factory supply limits and meeting store demands.
+
+This example demonstrates how to construct a **2D matrix of decision variables** using `m.continuous(factories, stores)` and write aggregated constraints declaratively via `dot()` and `m.constraint(expr`...`)`.
+
+## Problem Inputs
+
+We have **3 factories** (`Tokyo`, `Nagoya`, `Osaka`) shipping to **4 regional stores** (`North`, `East`, `West`, `South`):
+
+| Factory \ Store | North ($/unit) | East ($/unit) | West ($/unit) | South ($/unit) | Supply Capacity |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| **Tokyo** | $4 | $2 | $7 | $8 | **120** units |
+| **Nagoya** | $6 | $4 | $3 | $5 | **100** units |
+| **Osaka** | $9 | $7 | $2 | $3 | **80** units |
+| **Store Demand** | **70** units | **90** units | **60** units | **60** units | Total: 280 / 300 |
+
+## Mathematical Formulation
+
+Let $x_{f, s} \ge 0$ be the quantity shipped from factory $f \in F$ to store $s \in S$, and $c_{f, s}$ be the unit shipping cost.
+
+$$\begin{aligned}
+\text{Minimize} \quad & \sum_{f \in F} \sum_{s \in S} c_{f,s} \, x_{f,s} \\
+\text{Subject to} \quad & \sum_{s \in S} x_{f,s} \le \text{Supply}_f \quad \forall f \in F \quad (\text{Factory capacity}) \\
+& \sum_{f \in F} x_{f,s} \ge \text{Demand}_s \quad \forall s \in S \quad (\text{Store demand}) \\
+& x_{f,s} \ge 0 \quad \forall f \in F, s \in S
+\end{aligned}$$
+
+## Implementation in WaSHI
+
+<CodeRunner preset="transportation">
+
+```typescript
+import { Model, sum, dot, minimize, expr } from "@ohtaman/washi";
+
+const factories = ["Tokyo", "Nagoya", "Osaka"] as const;
+const stores = ["North", "East", "West", "South"] as const;
+
+const shippingCost = {
+  Tokyo:  { North: 4, East: 2, West: 7, South: 8 },
+  Nagoya: { North: 6, East: 4, West: 3, South: 5 },
+  Osaka:  { North: 9, East: 7, West: 2, South: 3 },
+};
+
+const supplies = { Tokyo: 120, Nagoya: 100, Osaka: 80 };
+const demands = { North: 70, East: 90, West: 60, South: 60 };
+
+async function runTransportation() {
+  const m = new Model("TransportationNetwork");
+
+  // 1. Create 2D continuous variables: ship[factory][store] >= 0
+  const ship = m.continuous([...factories], [...stores], { lb: 0 });
+
+  // 2. Objective: Minimize total shipping cost across all routes via 2D dot product
+  m.objective(minimize(dot(shippingCost, ship)));
+
+  // 3. Supply constraints (row sums): outgoing from f <= supplies[f]
+  for (const f of factories) {
+    m.constraint(
+      expr`${sum(stores, (s) => ship[f][s])} <= ${supplies[f]}`,
+      `supply_${f}`
+    );
+  }
+
+  // 4. Demand constraints (column sums): incoming to s >= demands[s]
+  for (const s of stores) {
+    m.constraint(
+      expr`${sum(factories, (f) => ship[f][s])} >= ${demands[s]}`,
+      `demand_${s}`
+    );
+  }
+
+  const status = await m.solve();
+  console.log(`Status: ${status}, Total Shipping Cost: $${m.objectiveValue}`);
+  for (const f of factories) {
+    const routes = stores
+      .map((s) => `${s}:${Math.round(ship[f][s].value ?? 0)}`)
+      .join(", ");
+    console.log(`  ${f.padEnd(7)} -> ${routes}`);
+  }
+}
+
+runTransportation();
+```
+
+</CodeRunner>

package/docs/examples/unsat-core.md

@@ -0,0 +1,64 @@
+# Conflict Diagnosis (Unsat Core)
+
+| Problem Class | Solver | Key APIs | Links |
+| :--- | :--- | :--- | :--- |
+| Infeasibility Diagnosis / Unsat Core | Z3 (`@ohtaman/washi/solvers/z3`) | `m.integer()`, `m.continuous()`, `m.constraint()`, `expr`, `m.check()`, `m.conflicts` | <ul><li><a href="https://ohtaman.github.io/washi/demo/?preset=conflict_diagnosis_unsat">Open in Playground</a></li><li><a href="https://github.com/ohtaman/washi/blob/main/examples/node/05-unsat-core-diagnosis.ts">Source Code</a></li></ul> |
+
+When business rules, budgets, and operational policies grow complex, constraints inevitably conflict. Traditional solvers simply report "Infeasible", leaving engineers to guess which of hundreds of rules caused the contradiction.
+
+This example shows how to isolate the conflicting constraint subset using Z3 Unsat Core extraction.
+
+## The Conflicting Scenario
+
+A tech team is staffing a customer project:
+1. Each engineer costs $8,000 against the project budget (`budget_limit`).
+2. The customer requires rush delivery (`rush_required`).
+3. Rush delivery mandates at least 8 engineers (`rush_staffing_rule`).
+4. The board has imposed a strict budget cap of $50,000 (`strict_board_budget_cap`).
+5. Labor law requires at least 1 employee on staff (`minimum_one_employee`).
+
+Notice that:
+
+$$8 \text{ engineers} \times \$8,000 = \$64,000 > \$50,000 \text{ budget!}$$
+
+## Implementation in WaSHI
+
+<CodeRunner preset="conflict_diagnosis_unsat">
+
+```typescript
+import { Model, expr } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+async function diagnoseConflicts() {
+  const m = new Model({ name: "ConflictDiagnosis", solver: "z3" });
+
+  const engineers = m.integer("engineers", { lb: 0, ub: 20 });
+  const budget = m.continuous("budget", { lb: 0, ub: 100000 });
+  const rushDelivery = m.bool("rushDelivery");
+
+  // Rule 1: Each engineer costs $8,000
+  m.constraint(expr`8000 * ${engineers} <= ${budget}`, "budget_limit");
+
+  // Rule 2: Customer requires rush delivery
+  m.constraint(rushDelivery, "rush_required");
+
+  // Rule 3: Rush delivery requires at least 8 engineers
+  m.constraint(rushDelivery.implies(engineers.ge(8)), "rush_staffing_rule");
+
+  // Rule 4: Board budget cap of $50,000 (Conflict!)
+  m.constraint(expr`${budget} <= 50000`, "strict_board_budget_cap");
+
+  // Rule 5: Innocent bystander rule
+  m.constraint(expr`${engineers} >= 1`, "minimum_one_employee");
+
+  // Run diagnosis
+  const res = await m.check({ solver: "z3" });
+
+  console.log(`Status: ${res.status}`);
+  console.log("Conflicting Constraints (conflicts):", m.conflicts);
+}
+
+diagnoseConflicts();
+```
+
+</CodeRunner>

package/docs/getting-started/ai-agents.md

@@ -0,0 +1,267 @@
+# AI Coding Agent Quick-Reference Guide
+
+> **Scope Note**: This document is the **consumer modeling quick-reference** for AI coding agents and developers building optimization or satisfiability models with `@ohtaman/washi`.
+> - **Portable Agent Skill (`SKILL.md`)**: For an actionable end-to-end modeling, `toLpString()` inspection, `validateSolution()` verification, and Z3 `unsatCore` conflict-diagnosis workflow skill (compatible with Claude Code, Antigravity, Cursor, Codex, and other `SKILL.md`-aware agents), use [`skills/washi/SKILL.md`](https://github.com/ohtaman/washi/blob/main/skills/washi/SKILL.md) (also shipped in the npm package at `node_modules/@ohtaman/washi/skills/washi/SKILL.md`):
+>   ```bash
+>   # Link or copy the packaged skill into your project's agent skills directory
+>   mkdir -p .agents/skills/washi
+>   cp node_modules/@ohtaman/washi/skills/washi/SKILL.md .agents/skills/washi/SKILL.md
+>   ```
+> - **Repository Review Guidelines**: For repository contribution and pull-request review rules, see [`AGENTS.md`](https://github.com/ohtaman/washi/blob/main/AGENTS.md) in the repository root.
+
+---
+
+## 1. Package Imports & Deployment
+
+### Node.js / Bundlers (Vite, Webpack, Next.js, Bun)
+
+```ts
+import {
+  Model,
+  expr,
+  sum,
+  dot,
+  maximize,
+  minimize,
+  and,
+  or,
+  not,
+  implies,
+  xor,
+  setHighsWasmUrl,
+} from "@ohtaman/washi";
+
+// Optional solver plugins (require installing peer dependencies first):
+// npm install z3-solver
+import "@ohtaman/washi/solvers/z3";
+// npm install glpk.js
+import "@ohtaman/washi/solvers/glpk";
+```
+
+### Browser ESM & Classic Script Tags
+
+- **Browser ESM**:
+  - Core (HiGHS built-in): `import { Model, expr, maximize } from "./washi/washi.js";`
+  - GLPK plugin: `import "./washi/solvers/glpk.js";`
+  - Z3 plugin: `import "./washi/solvers/z3.js";`
+- **Classic `<script>` / CodePen (IIFE)**:
+  - Core: `<script src="./washi/washi.min.js"></script>` (exposes global `Washi`)
+  - GLPK plugin: `<script src="./washi/solvers/glpk.min.js"></script>` (registers `"glpk"`, exposes `WashiGLPK`)
+  - Z3 plugin: `<script src="./washi/solvers/z3.min.js"></script>` (registers `"z3"`, exposes `WashiZ3`)
+
+### WebAssembly Asset & Runtime Rules
+
+1. **Bundled WASM by default (no implicit CDN fallback)**:
+   - In Node.js and modern bundlers, WebAssembly assets resolve relative to the module automatically.
+   - In browser deployments, deploy the full `dist/browser/` directory (JS, Worker, and `.wasm` files) together. If a local WASM URL is missing or returns an HTML SPA fallback, initialization fails immediately and reports the attempted URL—it **never** silently switches to a public CDN.
+   - In browser runtimes, to load `highs.wasm` from a custom location, call `setHighsWasmUrl("https://.../highs.wasm")` or pass `await m.solve({ wasmUrl: "https://.../highs.wasm" })` (ignored in Node.js, which always loads the local Node `highs` package runtime).
+2. **Z3 requires a Secure Context, Cross-Origin Isolation, and CORS in browsers**:
+   - Z3 WebAssembly uses `SharedArrayBuffer` multithreading. Browser pages running Z3 must run in a secure context (`window.isSecureContext === true`, i.e., HTTPS or `localhost`) and be cross-origin isolated (`window.crossOriginIsolated === true`) by serving:
+     - `Cross-Origin-Opener-Policy: same-origin` (on the document)
+     - `Cross-Origin-Embedder-Policy: require-corp` (on the document)
+     - `Cross-Origin-Resource-Policy: cross-origin` and `Access-Control-Allow-Origin` (on cross-origin script/WASM asset responses)
+   - Importing `@ohtaman/washi` never auto-injects a Service Worker. When a secure context or cross-origin isolation is absent in a browser, Z3 rejects immediately with a descriptive error.
+3. **Web Workers & Cancellation (`AbortSignal`)**:
+   - Pre-solve cancellation (`signal.aborted` before execution starts) is supported across all solvers.
+   - In browsers where `Worker` is available, HiGHS runs in a dedicated Web Worker by default (`useWorker: true`). Passing `{ signal }` to `m.solve({ signal })` preemptively terminates an in-flight Worker solve (or cancels queued Worker requests).
+   - On main-thread HiGHS (`useWorker: false` or in Node.js), cooperative mid-solve cancellation is supported when `abort()` is triggered synchronously inside an `onProgress` callback at a solver interrupt checkpoint; arbitrary asynchronous aborts from outside cannot preempt a blocked synchronous WASM thread until a callback checkpoint or completion. Single-threaded WASM solvers without interrupt hooks (GLPK, Z3) check `signal` before execution starts.
+
+---
+
+## 2. Canonical Modeling Workflow
+
+Formulating and solving a model consists of four distinct steps:
+
+### Step 1: Create Model & Decision Variables
+
+```ts
+const m = new Model("ExampleModel");
+
+// Scalar variables
+const x = m.continuous("x", { lb: 0, ub: 100 });
+const n = m.integer("n", { lb: 0, ub: 10 });
+const b = m.binary("b");
+const flag = m.bool("flag"); // Propositional boolean (for Z3 / logical constraints)
+
+// Indexed variable containers:
+// - Numeric dimension -> Array
+// - Key-array dimension -> Record
+const vec = m.continuous(4, { lb: 0, prefix: "v" }); // Var[] (length 4)
+const grid = m.binary(2, 3, { prefix: "g" }); // Var[][] (2x3)
+const byItem = m.integer(["desk", "chair"] as const, { lb: 0 }); // Record<"desk" | "chair", Var>
+const mixed = m.binary(["A", "B"] as const, 3); // Record<"A" | "B", Var[]>
+```
+
+- **Optional Primal Initial Values (`initialValue?: number`)**:
+  - Numeric variable constructors (`m.continuous`, `m.integer`, `m.binary`, and `new Var`) and the mutable `v.initialValue` property accept an optional finite primal hint (validated with tolerance `1e-6` against bounds `[lb, ub]` and integer/binary domains), kept distinct from the solved `v.value`.
+  - A start may be complete or partial (e.g., transferred by stable variable names when rebuilding a MIP model). Supplying `initialValue` is a hint only—it does **not** fix the variable, add a hard constraint, or guarantee solver acceptance or a runtime speedup.
+  - Supported by **HiGHS** (`supportsWarmStart: true`); solvers without warm-start support (**GLPK**, **Z3**) throw an error if any variable has `initialValue !== undefined`.
+
+### Step 2: Build Expressions (`expr`, `sum`, `dot`)
+
+- **Unified `expr` template tag**:
+  - Linear expression (`LinExpr`): `` expr`30 * ${x} + 50 * ${n} - 10` ``
+  - Quadratic expression (`QuadExpr`): `` expr`${x}^2 + 2 * ${x} * ${n} + ${n}^2` `` (variable-by-variable products and squares are supported for convex QP objectives).
+  - Linear constraint (`Constraint`): `` expr`${x} + 2 * ${n} <= 40` `` (supports `<=`, `>=`, `==`, and `=`).
+- **Aggregations**:
+  - `sum(iterable, mapper?)` sums an `Iterable` of `Var` / `LinExpr` / `number` (e.g., `Var[]`, `grid.flat()`, or `Object.values(record)`).
+  - `dot(a, b)` computes the inner product of matching 1D arrays, 2D arrays (`number[][]` / `Var[][]`), plain records (`Record<string, ...>`), or mixed Array/Record containers in either operand order.
+- **Fluent methods**:
+  - Arithmetic (on `LinExpr` and `QuadExpr`; `Var` supports `.add()`, `.sub()`, `.mul()`, `.neg()`): `.add(other)`, `.sub(other)`, `.mul(other)`, `.div(scalar)`, `.neg()`
+  - Comparisons (on `Var` and `LinExpr`): `.le(rhs, name?)`, `.ge(rhs, name?)`, `.eq(rhs, name?)`
+  - Boolean logic (on `BoolVar`, `BoolExpr`, and `Constraint` for Z3): standalone `and(...)`, `or(...)`, `not(...)`, `implies(a, b)`, `xor(a, b)` and fluent `.and(...)`, `.or(...)`, `.not()`, `.implies(...)`, `.xor(...)`
+
+### Step 3: Register Objective & Constraints on the Model
+
+Constructing an `expr` or `.le()` object does **not** attach it to the model until you pass it to `m.constraint(...)` or `m.objective(...)`:
+
+```ts
+// Set objective using maximize() or minimize()
+m.objective(maximize(expr`30 * ${x} + 50 * ${n}`));
+
+// Register constraints on the model
+m.constraint(expr`${x} + 2 * ${n} <= 40`, "resource_limit");
+
+// Indicator constraint (MIP Big-M reformulation: b === 1 => x <= 50)
+m.indicator(b, expr`${x} <= 50`, { activeValue: 1, name: "cap_when_b" });
+```
+
+### Step 4: Execute (`solve` or `check`) & Verify (`validateSolution`)
+
+- **Optimization (`await m.solve(options?)`)**:
+  - Returns `SolverStatus` (`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`, `"Sat"`, or `"Unsat"`). Built-in optimization solvers return the optimization statuses (`"Optimal"`, `"Feasible"`, `"Infeasible"`, `"Unbounded"`, `"TimeLimit"`, `"IterationLimit"`, `"Error"`, `"Unknown"`, `"NotSolved"`), where a time-, iteration-, or solution-limited run (or an interrupted solve) that found a valid primal incumbent returns `"Feasible"`; `"Sat"` and `"Unsat"` are included in `SolverStatus` for satisfiability/custom solver adapters (such as `MockSolver`).
+  - Read values via `x.value`, `expr`...`.value`, `m.getValues(x)`, `m.getValues(container)`, `m.objectiveValue`, `constr.dual`, `constr.slack`, and `x.reducedCost`.
+  - Call `m.validateSolution()` after solving to independently verify variable finiteness, variable bounds (`lb`/`ub`), integer/binary/boolean domains, linear constraint residuals, and logical constraints (`SolutionValidationReport`: `{ valid, complete, maxViolation, violations, ... }`). Note that `validateSolution()` checks primal feasibility of variables and constraints; it does not recompute or compare `m.objectiveValue`.
+- **Satisfiability & Unsat Core (`await m.check(options?)`)**:
+  - Returns `CheckResult` (`{ status: "Sat" | "Unsat" | "Unknown", values: Record<string, number | boolean>, conflicts?: readonly string[], unsatCore?: readonly string[], runTime?: number }`), where `conflicts` and `unsatCore` are optional and populated only when an unsat-core-capable solver (such as Z3) returns `"Unsat"`.
+  - For models containing only linear arithmetic constraints, `m.check()` works with any solver (including the default HiGHS and GLPK) by falling back to a feasibility `solve()`. Logical constraints (`BoolVar`, `and`, `or`, `implies`, etc.) and unsatisfiable-core extraction (`result.conflicts` / `result.unsatCore`) require an SMT-capable solver (`{ solver: "z3" }`). Because Z3 asserts variable bounds (`lb`/`ub`) and binary `{0, 1}` domains directly while tracking registered constraints, `conflicts` / `unsatCore` reports a subset of registered constraint names that conflicts *together with the model's fixed variable bounds/domains* (and is not guaranteed minimal).
+- **No concurrent mutation during async solve/check**:
+  - Mutating variables, constraints, or the objective while `await m.solve()` or `await m.check()` is pending invalidates the in-flight execution and rejects the stale promise.
+
+---
+
+## 3. Executable Examples
+
+### Example A: Mixed-Integer Linear Programming (MIP) with Indexed Containers & Solution Validation
+
+```ts
+import { Model, expr, dot, sum, maximize } from "@ohtaman/washi";
+
+export async function runMipExample() {
+  const m = new Model("ProductionMIP");
+  const products = ["desk", "chair"] as const;
+  const profit = { desk: 30, chair: 50 };
+  const woodPerUnit = { desk: 1, chair: 2 };
+  const laborPerUnit = { desk: 2, chair: 1 };
+
+  const qty = m.integer(products, { lb: 0, ub: 100 });
+  const setup = m.binary("setup");
+
+  m.objective(maximize(expr`${dot(profit, qty)} - 20 * ${setup}`));
+  m.constraint(expr`${dot(woodPerUnit, qty)} <= 40`, "wood_cap");
+  m.constraint(expr`${dot(laborPerUnit, qty)} <= 50`, "labor_cap");
+  m.constraint(expr`${sum(Object.values(qty))} <= 30 * ${setup}`, "require_setup");
+
+  const status = await m.solve();
+  const report = m.validateSolution();
+  const values = m.getValues(qty);
+
+  return {
+    status,
+    objectiveValue: m.objectiveValue,
+    values,
+    setup: setup.value,
+    valid: report.valid,
+    maxViolation: report.maxViolation,
+  };
+}
+```
+
+### Example B: Convex Quadratic Programming (QP)
+
+Variable-by-variable products (`${x} * ${y}`) and squares (`${x}^2`) are supported in `expr` for quadratic objectives:
+
+```ts
+import { Model, expr, minimize } from "@ohtaman/washi";
+
+export async function runQpExample() {
+  const m = new Model("PortfolioQP");
+  const x = m.continuous("x", { lb: 0 });
+  const y = m.continuous("y", { lb: 0 });
+
+  // Minimize x^2 + y^2 subject to x + y >= 4
+  m.objective(minimize(expr`${x}^2 + ${y}^2`));
+  m.constraint(expr`${x} + ${y} >= 4`, "budget");
+
+  const status = await m.solve();
+  const report = m.validateSolution();
+
+  return {
+    status,
+    objectiveValue: m.objectiveValue,
+    x: x.value,
+    y: y.value,
+    valid: report.valid,
+  };
+}
+```
+
+### Example C: Z3 Feasibility Check & Unsat Core Diagnosis
+
+```ts
+import { Model, expr, implies } from "@ohtaman/washi";
+import "@ohtaman/washi/solvers/z3";
+
+export async function runZ3Example() {
+  const m = new Model("PolicyCheck", { solver: "z3" });
+  const vip = m.bool("vip");
+  const discount = m.integer("discount", { lb: 0, ub: 50 });
+
+  m.constraint(vip, "customer_is_vip");
+  m.constraint(implies(vip, expr`${discount} >= 20`), "vip_min_discount");
+  m.constraint(expr`${discount} <= 10`, "campaign_cap");
+
+  const unsatResult = await m.check();
+  return {
+    status: unsatResult.status,
+    conflicts: unsatResult.conflicts,
+  };
+}
+```
+
+---
+
+## 4. Negative Examples & Common Pitfalls
+
+Avoid these invalid patterns and retired aliases:
+
+```ts
+import { Model, expr, maximize } from "@ohtaman/washi";
+
+export function verifyNegativePatterns() {
+  const m = new Model("NegativeExamples");
+  const x = m.continuous("x", { lb: 0 });
+  const y = m.continuous("y", { lb: 0 });
+
+  // 1. DO NOT pass a Constraint to m.objective() or arithmetic methods:
+  // WRONG: m.objective(maximize(expr`${x} <= 10` as any)); -> throws Error
+  // WRONG: expr`${x} + 1`.add(expr`${y} <= 5` as any); -> throws Error
+
+  // 2. DO NOT pass an arithmetic expression without (<=, >=, ==) to m.constraint():
+  // WRONG: m.constraint(expr`${x} + ${y}` as any); -> throws Error
+
+  // 3. DO NOT use quadratic terms inside linear constraints:
+  // WRONG: expr`${x}^2 <= 10`; -> throws Error ("Quadratic constraints are not supported")
+
+  // 4. DO NOT use retired aliases (removed in #59 / #81):
+  // - Use `expr` instead of retired `c` template tag
+  // - Use `m.constraint(...)` instead of `m.constrain(...)` or `m.add(...)`
+  // - Use `m.objective(maximize(...))` / `m.objective(minimize(...))` instead of `m.maximize(...)` / `m.minimize(...)` / `m.setObjective(...)`
+  // - Use `await m.solve()` instead of `await m.optimize()`
+  // - Use `.le()`, `.ge()`, `.eq()` instead of `.lessThanOrEqual()`, `.greaterThanOrEqual()`, `.equalTo()`
+  // - Use `.value` or `m.getValues(...)` instead of `expr.getValue()`
+  // - Use `m.variables` / `m.constraints` instead of `m.vars` / `m.constrs`
+  return { m, x, y, maximize };
+}
+```
+

package/docs/getting-started/cross-origin.md

@@ -0,0 +1,87 @@
+# Cross-Origin Isolation (Z3 & Browsers)
+
+When running the **Z3** solver engine inside a web browser, special HTTP headers are required due to browser security models.
+
+---
+
+## Why is Cross-Origin Isolation Required?
+
+The Z3 WebAssembly engine utilizes multithreading backed by `SharedArrayBuffer` and Web Workers.
+
+In modern browsers (Chrome, Firefox, Safari, Edge), `SharedArrayBuffer` is disabled by default to mitigate Spectre-style timing side-channel attacks. To re-enable it, the hosting page must be **Cross-Origin Isolated**.
+
+---
+
+## Required HTTP Response Headers
+
+To establish cross-origin isolation, your web server must serve the top-level HTML document with the following HTTP headers:
+
+```http
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+In addition, any cross-origin assets (e.g. scripts or WASM files loaded from external domains) must send:
+
+```http
+Cross-Origin-Resource-Policy: cross-origin
+```
+
+---
+
+## Solutions by Hosting Environment
+
+### 1. Custom Node.js / Express Server
+
+```javascript
+app.use((req, res, next) => {
+  res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+  res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+  next();
+});
+```
+
+### 2. Next.js (`next.config.js`)
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  async headers() {
+    return [
+      {
+        source: "/(.*)",
+        headers: [
+          { key: "Cross-Origin-Opener-Policy", value: "same-origin" },
+          { key: "Cross-Origin-Embedder-Policy", value: "require-corp" },
+        ],
+      },
+    ];
+  },
+};
+
+module.exports = nextConfig;
+```
+
+### 3. Static Hosting without Header Control (e.g., GitHub Pages)
+
+Platforms like GitHub Pages or preview environments do not allow customizing response headers directly.
+
+For these environments, you can use **`coi-serviceworker`** (a lightweight Service Worker that injects isolation headers on the client side):
+
+1. Place `coi-serviceworker.js` in your website root.
+2. In your HTML `<head>`, include:
+
+```html
+<script src="/coi-serviceworker.js"></script>
+```
+
+When a user visits for the first time, the service worker registers and reloads the page once to establish `window.crossOriginIsolated === true`.
+
+---
+
+## Graceful Degradation in WaSHI
+
+WaSHI's Z3 solver adapter automatically inspects the environment at runtime. If Z3 is invoked in a browser lacking cross-origin isolation, it immediately rejects with a clear, informative error message explaining that COOP/COEP headers or a service worker are required, rather than hanging silently.
+
+> [!TIP]
+> The default **HiGHS** solver engine does not require cross-origin isolation or `SharedArrayBuffer`. It works out of the box in standard browser contexts.

package/docs/getting-started/index.md

@@ -0,0 +1,116 @@
+# Introduction & Installation
+
+Welcome to **WaSHI** (WebAssembly-backed, Solver-independent, High-level modeling Interface).
+
+WaSHI brings the algebraic modeling style of Python's **PuLP** and Julia's **JuMP** to the TypeScript and JavaScript ecosystem. You can formulate mathematical optimization problems using algebraic expressions and solve them locally using WebAssembly solvers (**HiGHS**, **Z3**, and **GLPK**)—without a separate Python service or native C/C++ build steps.
+
+### Why TypeScript & WebAssembly?
+
+- **Removing the deployment bottleneck**: In traditional optimization workflows (e.g., Python with PuLP or Pyomo), turning a model into an interactive application requires provisioning a backend service and managing native C/C++ solver binaries. As AI-assisted development accelerates UI and application prototyping, backend infrastructure often becomes the primary bottleneck to shipping. Running both the modeler and WebAssembly solvers on standard Web technologies allows an optimization tool to be deployed as static assets (e.g., on GitHub Pages or Cloudflare Pages, serving the generated JS, Worker, and WASM files; with COOP/COEP headers when using Z3)—and makes it straightforward to pair mathematical optimization with in-browser LLMs (e.g., WebGPU / WebLLM) entirely on the client.
+- **Algebraic syntax without operator overloading (`expr`)**: Because JavaScript lacks operator overloading, libraries usually trade off between verbose method chaining (`x.mul(30).add(y.mul(50))`) and untyped strings (`"30 * x + 50 * y"`). WaSHI uses tagged template literals (`` expr`30 * ${x} + 50 * ${y} <= 40` ``) similar to parameterized SQL queries—parsing infix operators while binding `${x}` directly as typed TypeScript object references for static type checking, IDE symbol renaming, and multi-dimensional indexing (`${flow[i][j]}`).
+
+---
+
+## 📦 Installation
+
+Install WaSHI using your preferred package manager:
+
+::: code-group
+
+```bash [npm]
+npm install @ohtaman/washi
+```
+
+```bash [pnpm]
+pnpm add @ohtaman/washi
+```
+
+```bash [yarn]
+yarn add @ohtaman/washi
+```
+
+```bash [bun]
+bun add @ohtaman/washi
+```
+
+:::
+
+### Optional Solver Dependencies
+
+WaSHI ships with **HiGHS** built-in with zero configuration. If you need SMT logic / Unsat Core diagnosis via **Z3**, or compatibility with **GLPK**, install their respective peer dependencies:
+
+```bash
+# For SMT logic and Unsat Core conflict diagnosis
+npm install z3-solver
+
+# For GLPK solver (GPL-3.0)
+npm install glpk.js
+```
+
+---
+
+## 🚀 Quickstart Walkthrough
+
+Here is a step-by-step example of solving a production allocation problem.
+
+### 1. Import the Core Classes
+
+```typescript
+import { Model, expr, maximize } from "@ohtaman/washi";
+```
+
+### 2. Instantiate a Model
+
+```typescript
+const model = new Model("WoodworkingProfit");
+```
+
+### 3. Add Decision Variables
+
+Variables represent the unknowns you want to determine. Factory methods (`m.continuous`, `m.integer`, `m.binary`) clearly define their domain:
+
+```typescript
+const x = model.integer("x", { lb: 0 });
+const y = model.integer("y", { lb: 0 });
+```
+
+### 4. Set the Objective Function
+
+Use the `expr` tagged template literal along with `maximize(...)` or `minimize(...)` to define the goal:
+
+```typescript
+// Maximize 30*x + 50*y
+model.objective(maximize(expr`30 * ${x} + 50 * ${y}`));
+```
+
+### 5. Add Constraints
+
+Use `model.constraint()` with the `expr` tagged template to formulate equality and inequality constraints:
+
+```typescript
+model.constraint(expr`${x} + 2 * ${y} <= 40`, "wood_capacity");
+model.constraint(expr`2 * ${x} + ${y} <= 50`, "labor_capacity");
+```
+
+### 6. Solve and Extract Results
+
+Solve the model asynchronously via WebAssembly (HiGHS by default):
+
+```typescript
+const status = await model.solve();
+
+console.log("Status:", status); // "Optimal"
+console.log("Optimal Objective Value:", model.objectiveValue); // 1100
+console.log(`Solution: x = ${x.value}, y = ${y.value}`); // x = 20, y = 10
+```
+
+---
+
+## 🧭 Next Steps
+
+- Give AI coding agents a concise API & deployment reference with the [AI Coding Agent Quick-Reference Guide](./ai-agents.md).
+- Learn how to run WaSHI across different environments in [Runtime Environments](./runtimes.md).
+- Understand how to formulate complex expressions in the [Modeling Guide](../guide/expressions.md).
+- Explore built-in and pluggable solvers in the [Solvers Matrix](../solvers/).
+- Browse 9 runnable optimization and SMT recipes in [Examples & API Finder](../examples/).
+