cdm227 · cdm227 · Jun 13, 2026 · Jun 13, 2026 · Jun 13, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,28 @@
+# GitHub Copilot instructions — AgriValue Tracker
+
+## Project
+
+Sicilian agricultural value-chain terminal with **Fabric IQ**, **Foundry IQ**, **Work IQ**, and a custom **MCP server** (`agrivalue-iq`).
+
+Read [AGENTS.md](../AGENTS.md) and [docs/architecture.md](../docs/architecture.md) before large changes.
+
+## MCP
+
+- Server: `mcp-server.js` — registered in `.vscode/mcp.json`
+- Invoke in Copilot Chat: `@agrivalue-iq get_market_intelligence crop="Olive Oil"`
+- Tools: `get_market_intelligence`, `generate_supply_contract`, `evaluate_crop_quality`
+
+## Code patterns
+
+- Business logic lives in `lib/fabric-iq.js` and `lib/iq-data.js`; expose via `server.js` and MCP.
+- Crop enum: `CROP_NAMES` in `lib/fabric-iq.js` — keep MCP JSON schema in sync.
+- Frontend uses Tailwind CDN + `public/css/app.css`; demo teleprompter styles are inline in `demo.html`.
+
+## Security
+
+- Never suggest committing `.env` or real credentials.
+- Use `.env.example` for documentation only.
+
+## Tests
+
+Run `npm test` after changing optimization, contracts, or IQ data. Tests live in `tests/`.
diff --git a/.github/workflows/azure-deploy.yml b/.github/workflows/azure-deploy.yml
@@ -1,38 +1,38 @@
-name: Deploy backend to Azure App Service
-
-on:
-  push:
-    branches: [PROD]
-    paths:
-      - 'server.js'
-      - 'lib/**'
-      - 'mcp-server.js'
-      - 'package.json'
-      - 'public/**'
-      - '.github/workflows/azure-deploy.yml'
-  workflow_dispatch:
-
-permissions:
-  contents: read
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    environment: azure-production
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: npm
-
-      - run: npm ci
-      - run: npm run build:static
-
-      - name: Deploy to Azure Web App
-        uses: azure/webapps-deploy@v3
-        with:
-          app-name: ${{ secrets.AZURE_WEBAPP_NAME }}
-          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
-          package: .
+name: Deploy backend to Azure App Service
+
+on:
+  push:
+    branches: [PROD]
+    paths:
+      - "server.js"
+      - "lib/**"
+      - "mcp-server.js"
+      - "package.json"
+      - "public/**"
+      - ".github/workflows/azure-deploy.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment: azure-production
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - run: npm ci
+      - run: npm run build:static
+
+      - name: Deploy to Azure Web App
+        uses: azure/webapps-deploy@v3
+        with:
+          app-name: ${{ secrets.AZURE_WEBAPP_NAME }}
+          publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
+          package: .
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: ["PROD"]
+  pull_request:
+    branches: ["PROD"]
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run format:check
+      - run: npm test
+      - run: npm run build:static
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1,2 @@
+npm run lint
+npm test
diff --git a/.prettierignore b/.prettierignore
@@ -0,0 +1,7 @@
+node_modules
+public/js/fabric-iq-client.js
+public/config.js
+public/demo.html
+public/index.html
+public/css/app.css
+.agents/skills/higgsfield-generate
diff --git a/.prettierrc b/.prettierrc
@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "trailingComma": "es5",
+  "printWidth": 100
+}
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,67 @@
+# AgriValue Tracker — Agent Context
+
+Sicilian value-chain optimizer for **Agents League Battle #1** (Creative Apps + GitHub Copilot MCP).
+
+## Stack
+
+| Layer        | Path                                                        | Role                                                        |
+| ------------ | ----------------------------------------------------------- | ----------------------------------------------------------- |
+| API          | `server.js`                                                 | Express routes, Foundry agent, IQ orchestration             |
+| IQ data      | `lib/iq-data.js`                                            | Unified Fabric / portfolio / optimize / advisor             |
+| Fabric graph | `lib/fabric-iq.js`, `lib/fabric-lakehouse.js`               | Semantic market graph (+ SQL fallback)                      |
+| Work IQ      | `lib/work-iq.js`                                            | Microsoft Graph / Teams webhooks                            |
+| MCP          | `mcp-server.js`, `.vscode/mcp.json`                         | Copilot tools in VS Code                                    |
+| UI           | `public/index.html`, `public/demo.html`, `public/js/app.js` | Terminal + judge teleprompter                               |
+| Static sync  | `scripts/sync-static-data.js`                               | Copies `lib/fabric-iq.js` → `public/js/fabric-iq-client.js` |
+
+**Default branch:** `PROD`. **Live demo:** https://cdm227.github.io/AgriValue-Tracker/demo.html
+
+## Commands
+
+```bash
+npm install
+npm start                    # http://localhost:3000
+npm run mcp                  # MCP server (stdio)
+npm test                     # node:test suite
+npm run lint                 # ESLint
+npm run agent:action -- help # deterministic demo actions
+npm run build:static         # Pages build (sync + config inject)
+```
+
+## Architecture & docs
+
+- [docs/architecture.md](docs/architecture.md) — system overview
+- [docs/MICROSOFT_IQ.md](docs/MICROSOFT_IQ.md) — Fabric / Foundry / Work IQ
+- [docs/COPILOT.md](docs/COPILOT.md) — Copilot + MCP usage
+- [docs/AZURE_DEPLOY.md](docs/AZURE_DEPLOY.md) — Azure App Service + Pages
+- [.agents/skills/agrivalue-iq-operator/SKILL.md](.agents/skills/agrivalue-iq-operator/SKILL.md) — operator skill
+
+## Conventions
+
+- **ES modules** (`"type": "module"`) throughout; no CommonJS.
+- **Secrets:** `.env` only (gitignored). Never commit keys. Use `.env.example` placeholders.
+- **CORS:** restrict to GitHub Pages origin + localhost (see `server.js`).
+- **IQ fallback:** app runs with in-memory Fabric graph when Azure/Fabric env vars are unset.
+- **UI language:** English for all user-facing strings.
+- **Minimal diffs:** match existing naming; extend `lib/iq-data.js` / `fabric-iq.js` rather than duplicating logic.
+- **Generated files:** do not hand-edit `public/js/fabric-iq-client.js` or `public/config.js` — use scripts.
+
+## MCP tools (`@agrivalue-iq`)
+
+| Tool                       | Purpose                             |
+| -------------------------- | ----------------------------------- |
+| `get_market_intelligence`  | Crop pricing, processor, compliance |
+| `generate_supply_contract` | Fair-Trade contract draft           |
+| `evaluate_crop_quality`    | Vision grade + profit multiplier    |
+
+## Do not
+
+- Commit `.env`, publish profiles, or API keys.
+- Add unrelated dependencies or large refactors during demo fixes.
+- Break GitHub Pages static fallback (`public/mock-api.js`, `api-client.js` demo mode).
+
+## Validation before PR
+
+```bash
+npm run lint && npm test && npm run build:static
+```
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,5 @@
+# Claude / Cursor context
+
+Read **[AGENTS.md](AGENTS.md)** first — it is the canonical agent context for this repo.
+
+Quick links: [architecture](docs/architecture.md) · [Copilot MCP](docs/COPILOT.md) · [operator skill](.agents/skills/agrivalue-iq-operator/SKILL.md)
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgriValue Tracker contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -20,17 +20,15 @@ If your Markdown viewer does not render video, open:
 
 ## Live Demo (for judges — start here)
 
-**Do not rely on the default Git clone branch.** Use these URLs directly:
+| Mode                                                 | URL                                                                              |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------- |
+| GitHub Pages UI                                      | [cdm227.github.io/AgriValue-Tracker](https://cdm227.github.io/AgriValue-Tracker) |
+| **2-min judge demo** (teleprompter + auto-narration) | […/demo.html](https://cdm227.github.io/AgriValue-Tracker/demo.html)              |
+| Full API (Azure)                                     | Set `AZURE_API_URL` secret → see [docs/AZURE_DEPLOY.md](docs/AZURE_DEPLOY.md)    |
 
-| Mode | URL |
-|------|-----|
-| GitHub Pages UI | [cdm227.github.io/AgriValue-Tracker](https://cdm227.github.io/AgriValue-Tracker) |
-| **2-min judge demo** (teleprompter + auto-narration) | […/demo.html](https://cdm227.github.io/AgriValue-Tracker/demo.html) |
-| Full API (Azure) | Set `AZURE_API_URL` secret → see [docs/AZURE_DEPLOY.md](docs/AZURE_DEPLOY.md) |
+**Source branch:** **`PROD`** (default branch — clones and Pages stay in sync).
 
-**Source branch:** production code lives on **`PROD`**. Set GitHub **Settings → General → Default branch → PROD** so clones match Pages.
-
-**CI:** Pushes to `PROD` auto-deploy GitHub Pages (`.github/workflows/static.yml`) and Azure backend (`.github/workflows/azure-deploy.yml`).
+**CI:** Pushes to `PROD` auto-deploy GitHub Pages (`.github/workflows/static.yml`) and Azure backend (`.github/workflows/azure-deploy.yml` when Azure secrets are configured).
 
 ## Quick Start
 
@@ -39,8 +37,12 @@ npm install
 cp .env.example .env   # optional: Azure, Fabric, Graph credentials
 npm start              # http://localhost:3000
 npm run mcp            # Copilot MCP server for VS Code
+npm test               # node:test suite (Fabric IQ + agent memory)
+npm run lint           # ESLint
 ```
 
+**AI / agent context:** [AGENTS.md](AGENTS.md) · [docs/architecture.md](docs/architecture.md) · [.github/copilot-instructions.md](.github/copilot-instructions.md)
+
 ### Test Locally Or In Codespaces
 
 The app works with demo data out of the box. Users only need their own Microsoft resources if they want live integrations.
@@ -90,20 +92,20 @@ npm run agent:action -- contract --crop "Olive Oil" --qty 15 --buyer "Cooperativ
 
 ## Triple IQ Stack
 
-| Layer | Technology | Purpose |
-|-------|------------|---------|
-| **Fabric IQ** | Fabric Lakehouse SQL + semantic graph | Market prices, processor network |
-| **Foundry IQ** | Azure AI Foundry agent | Grounded compliance & bonuses |
-| **Work IQ** | Microsoft Graph / Teams | Cooperative notifications |
+| Layer          | Technology                            | Purpose                          |
+| -------------- | ------------------------------------- | -------------------------------- |
+| **Fabric IQ**  | Fabric Lakehouse SQL + semantic graph | Market prices, processor network |
+| **Foundry IQ** | Azure AI Foundry agent                | Grounded compliance & bonuses    |
+| **Work IQ**    | Microsoft Graph / Teams               | Cooperative notifications        |
 
 ## Challenge Requirements
 
-| Requirement | Status | Documentation |
-|-------------|--------|---------------|
-| GitHub Copilot + MCP | Done | [docs/COPILOT.md](docs/COPILOT.md) |
-| Microsoft IQ (×3) | Demo + docs | [docs/MICROSOFT_IQ.md](docs/MICROSOFT_IQ.md) |
-| Azure deployment | Workflow ready | [docs/AZURE_DEPLOY.md](docs/AZURE_DEPLOY.md) |
-| Submission demo video | [YouTube](https://youtu.be/o8KqG8foLfM) | [docs/DEMO_SCRIPT.md](docs/DEMO_SCRIPT.md) |
+| Requirement           | Status                                  | Documentation                                |
+| --------------------- | --------------------------------------- | -------------------------------------------- |
+| GitHub Copilot + MCP  | Done                                    | [docs/COPILOT.md](docs/COPILOT.md)           |
+| Microsoft IQ (×3)     | Demo + docs                             | [docs/MICROSOFT_IQ.md](docs/MICROSOFT_IQ.md) |
+| Azure deployment      | Workflow ready                          | [docs/AZURE_DEPLOY.md](docs/AZURE_DEPLOY.md) |
+| Submission demo video | [YouTube](https://youtu.be/o8KqG8foLfM) | [docs/DEMO_SCRIPT.md](docs/DEMO_SCRIPT.md)   |
 
 ## UI Features (v3)
 
@@ -122,34 +124,35 @@ lib/
   fabric-lakehouse.js   # Microsoft Fabric SQL connector
   work-iq.js            # Microsoft Graph Teams
   iq-data.js            # Unified data layer
+tests/                  # node:test — optimize, contracts, memory
 server.js               # Express API + IQ orchestration
 mcp-server.js           # Copilot MCP tools
 public/                 # Terminal UI + demo recorder
 infra/                  # Bicep + Fabric SQL schema
-.github/workflows/      # Azure + GitHub Pages deploy
+.github/workflows/      # CI, Azure + GitHub Pages deploy
+AGENTS.md               # Canonical context for AI agents
+docs/architecture.md    # System overview + ADRs
 ```
 
 ## Agents League Submission
 
-| Item | Link |
-|------|------|
-| **Demo video** | https://youtu.be/o8KqG8foLfM |
-| **Live app** | https://cdm227.github.io/AgriValue-Tracker/demo.html |
-| **Register** (required for badge/prizes) | https://aka.ms/agentsleague/register |
-| **Submit issue** (official) | [microsoft/agentsleague — Project Submission](https://github.com/microsoft/agentsleague/issues/new?template=project.yml) |
+| Item                                     | Link                                                                                                                     |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **Demo video**                           | https://youtu.be/o8KqG8foLfM                                                                                             |
+| **Live app**                             | https://cdm227.github.io/AgriValue-Tracker/demo.html                                                                     |
+| **Register** (required for badge/prizes) | https://aka.ms/agentsleague/register                                                                                     |
+| **Submit issue** (official)              | [microsoft/agentsleague — Project Submission](https://github.com/microsoft/agentsleague/issues/new?template=project.yml) |
 
 Recording notes: [docs/DEMO_SCRIPT.md](docs/DEMO_SCRIPT.md)
 
-### Fix default branch & auto-deploy (one-time)
-
-| Step | Where | Action |
-|------|--------|--------|
-| Default branch | GitHub → **Settings → General → Default branch** | Switch from `testingv1` to **`PROD`** |
-| Pages deploy | Push to `PROD` | Workflow `static.yml` builds & deploys `public/` |
-| Azure API | Push to `PROD` | Workflow `azure-deploy.yml` (if Azure secrets configured) |
-| Manual deploy | **Actions** → *Deploy static content to Pages* → **Run workflow** | Use if you need a deploy before the next push |
-
+### Deploy & CI
 
+| Trigger                        | Workflow                                                          | Result                                      |
+| ------------------------------ | ----------------------------------------------------------------- | ------------------------------------------- |
+| PR / push to `PROD`            | `ci.yml`                                                          | Lint, format check, tests, static build     |
+| Push to `PROD`                 | `static.yml`                                                      | GitHub Pages deploy from `public/`          |
+| Push to `PROD` (backend paths) | `azure-deploy.yml`                                                | Azure App Service deploy (requires secrets) |
+| Manual                         | **Actions** → _Deploy static content to Pages_ → **Run workflow** | Redeploy Pages without a new commit         |
 
 ## Security