# KEEL — User Journey, Use Cases & Benefits **Status:** current as of 22 Aug 2026 · verified against the shipped screens in `app/` **Companion documents:** [ARCHITECTURE.md](./ARCHITECTURE.md) (how it is built) · [GUIDE.md](./GUIDE.md) (why each algorithm exists) · [DEMO.md](./DEMO.md) (how to present it) --- ## 1. The job to be done A buyer at a mid-sized manufacturer looks after 200–400 part numbers. On any given Tuesday, one supplier email arrives that says nothing: > *"Due to transport issues, delivery may be delayed by 5-7 days. We are trying to resolve this and > will update soon."* To know whether that matters, someone has to open the ERP, check usable stock against daily usage, find which production orders draw on that part, check their deadlines and priorities, decide whether inbound can be trusted, pull the supplier catalogue, request quotes, check certifications, compare split options against expedite fees, work out whether a low-priority order could move instead, and — if the answer costs more than their authority allows — write a case for their manager and wait. That is a half-day of work, per email. **So it usually does not happen.** The email gets filed as "acknowledged", the delivery keeps counting as inbound stock, and the shortage becomes visible when the line stops. **KEEL does that half-day of work in a few minutes, on every email, and shows its working.** --- ## 2. Who uses it | | Role | What they want | Where they live in the product | |---|---|---|---| | 👤 | **The Buyer / Planner** *(primary)* | To know which of 340 parts actually threatens production today, and to have the recovery already worked out | Agent Console, Mail, ERP Records | | 🧾 | **The Approver** — plant manager, procurement head | To decide in 60 seconds, with cost, consequence and alternatives in front of them | Approval Inbox | | 🚚 | **The Supplier** — outside the company | To answer the buyer's question in their own words | Supplier Portal (a link, no login) | | 🔍 | **The Auditor / Exec** | To be able to ask "why did we spend ₹1.4 lakh on Thursday?" and get a straight answer | Audit & Score, What It Prevented | | 🛠 | **The Ops Engineer** | To point it at their own data and see whether the reasoning survives contact with reality | ERP Records → connect a workbook, Integrations, Engine Lab | --- ## 3. The primary journey — a buyer's morning ``` ┌────────────────────────────────────────────────────────────────────────────┐ │ BEFORE │ │ Overnight: one vague supplier email lands. Nobody reads it until 9:40 am. │ └────────────────────────────────────────────────────────────────────────────┘ ┌─ 1 ─────────────────────┐ Mission Control / │ Pick the disruption │ The plant's opening position, seven scenarios, │ and a seed │ a seed you can randomise in front of anyone. └───────────┬─────────────┘ ▶ Start ▼ ┌─ 2 ─────────────────────┐ Agent Console /run/[id] ★ the product │ Watch it work │ Header: sim clock · cycle · tool-call gauge · ₹ committed │ Step, or Run │ Left : agent activity — what it did, and why │ │ Middle : the risk register — what is at stake │ │ Right : plans and messages │ │ ⚡ Inject: break the world mid-run └───────────┬─────────────┘ │ ├──────────────▶ It reconciles stock "ERP says 800. Warehouse says 390. │ Implied by usage: 304. Using 304." │ ├──────────────▶ It refuses a vague reply "No date, no quantity, three hedges — │ PO-7712 excluded from coverage." │ ├──────────────▶ It challenges a claim "SUP-21 says dispatched. The carrier │ ★ the moment record shows a label and no pickup. │ Reliability 0.88 → 0.53. Alternate │ sourcing CONTINUES." │ ├──────────────▶ It rejects the cheapest "Bharat Precision is ₹9/unit cheaper │ and a day faster. No Automotive-Grade │ certification. Rejected." │ ├──────────────▶ It declines to expedite "Cost of speed ₹24,000. Cost of the │ delay it avoids ₹9,600. Split instead, │ and move PROD-902 two days." ▼ ┌─ 3 ─────────────────────┐ Approvals /run/[id]/approvals │ It stops and asks you │ Only when cost > ₹1,50,000. One screen: │ ★ human-in-the-loop │ recommended action · total cost · overage · impact if approved · │ │ impact if REJECTED · alternatives with reasons · residual risk └───────────┬─────────────┘ [ Approve ] [ Reject ] │ ├── Approve ──▶ it executes, raises the POs, commits the budget └── Reject ───▶ the risk REOPENS and it must find something under the threshold. A rejection is an instruction, not a dead end. ▼ ┌─ 4 ─────────────────────┐ ERP Records /run/[id]/erp │ Check it actually │ New POs created by the agent. Untrusted orders flagged. │ moved the world │ Rescheduled deadlines. Export the whole thing as .xlsx. └───────────┬─────────────┘ ▼ ┌─ 5 ─────────────────────┐ What it prevented /run/[id]/impact │ See the counterfactual │ The same Tuesday run two ways: what a competent buyer working from │ │ the ERP screen would have believed, when they would have found out, │ │ what the downtime and panic freight would have cost — against what │ │ the agent actually spent. └───────────┬─────────────┘ ▼ ┌─ 6 ─────────────────────┐ Audit & Score /run/[id]/audit │ Justify every rupee │ Every detection, consideration, tool call, decision, escalation, │ │ contradiction and replan — with the reasoning attached. │ │ Filter to decisions only. Export as JSON. └─────────────────────────┘ ``` ### The two side journeys **The supplier.** Open `/run/[id]/suppliers`, copy a supplier's private link, open it on a phone. You are now that supplier. Stall, over-promise, or claim a shipment left when it never did — in your own words, not from a menu. The moment a person answers, the simulated persona goes quiet, and the agent has no field that tells it which one it is talking to. **The ops engineer.** Open `/run/[id]/erp`, download the template, fill it with your own inventory and supplier list, and either upload it or **connect it live** — a file path or a URL. From then on the agent re-reads that workbook at the top of every cycle. Edit a cell while it is running and it notices: *"COMP-104 usable stock 390 → 120"*, its costed plans are thrown away, and it replans. --- ## 4. Use cases ### 4.1 The seven built-in scenarios Each is a real failure mode, not a difficulty setting. | | Scenario | The situation | What the agent has to get right | |---|---|---|---| | S1 | **Baseline delay** | The incumbent says "5–7 days, will update soon" | Recognise that this is not a commitment, and chase for specifics rather than replanning on it | | S2 | **Phantom inventory** | The ERP reports 800 units; 390 are usable | Reconcile every stock signal and plan on the most pessimistic — unprompted | | S3 | **Adversarial claim** | The supplier says the goods have shipped. Only a label exists | Check the claim against the carrier record, downgrade the supplier, and **keep sourcing** | | S4 | **Quality trap** | The cheapest alternate is faster and lacks the required certification | Apply the gate before price is considered, and say so explicitly | | S5 | **Approval wall** | Every feasible plan exceeds the autonomous limit | Stop gathering, escalate with a complete brief, and keep working other risks while it waits | | S6 | **Twelve-hour cliff** | A high-priority line stops within 12 hours; the reliable supplier is short on quantity and the fast one is unreliable | Split — and price continuity, not just cost | | **S7** | **Compound** | Phantom stock **and** a lying supplier **and** a priority flip mid-run | All of the above, while the world moves underneath it | ### 4.2 The six live injections Anything can be broken mid-run from the console, and the agent must adapt rather than finish the plan it already had: `supplier reneges after confirming` · `warehouse corrects stock downward` · `demand spike +40%` · `expedite becomes unavailable` · `production priority flips` · `a second component goes critical` Every injection unverifies the assumptions behind every risk and throws away the costed plans, so adaptation is forced rather than hoped for. ### 4.3 Beyond the demo — where this shape of agent fits | Situation | Why KEEL's shape fits | |---|---| | **Inbound delay triage** across hundreds of SKUs | Detection is cheap; *impact assessment* is what nobody has time for, and it is the part that is fully automatable | | **Supplier claim verification** | Any claim about the physical world can be checked against an independent record. The pattern generalises past shipping — quantities, certificates, capacity | | **Emergency-buy governance** | The threshold, the brief, and the audit trail are the control. Not the purchase itself | | **Expedite spend reduction** | Roughly half of expedite spend traces to a planning failure. Pricing speed against the delay it avoids, every time, is a policy that cannot be maintained by hand | | **Supplier scorecarding that reflects behaviour** | Reliability moves when a supplier hedges or is contradicted — not once a quarter from a spreadsheet | | **Spreadsheet-run plants** | A great many mid-market manufacturers do not have a planning system; they have a workbook. Connecting to it directly is not a compromise — for that buyer, it *is* the ERP | --- ## 5. Benefits ### 5.1 To the buyer | Without | With | |---|---| | One vague email takes half a day to assess, so it is not assessed | Assessed in minutes, on every email | | Coverage is `stock ÷ usage` from a screen that may be wrong | Reconciled across three signals; the most pessimistic wins, and the disagreement is reported | | An acknowledged delay silently keeps counting as inbound stock | A reply without a date **and** a quantity **and** no hedging excludes the order from coverage until specifics arrive | | Alternates are compared in a spreadsheet sorted by unit price | Certification and quality gate applied *before* cost; every rejection recorded with its reason | | "Split or expedite?" is a judgement call under time pressure | Both priced, with the arithmetic shown, including the option of moving a low-priority order for zero rupees | | A plan is made once and held past its expiry | Assumptions carry TTLs; an external change reopens every risk it touched | ### 5.2 To the approver | Without | With | |---|---| | "Urgent approval needed — ₹1.6 lakh" | Recommended action, total cost, overage against the threshold, **impact if approved, impact if rejected**, alternatives with reasons, residual risk, decide-by time | | Approval averages more than two business days | One screen, two buttons, a decide-by stamp | | A rejection stalls the recovery | A rejection **reopens** the risk with an explicit instruction: find something under the threshold, or state that the stoppage is unavoidable | | No way to know what was *not* chosen | Rejected options are first-class data, including the ones that were cheaper and faster | ### 5.3 To the business - **Downtime avoided** — the counterfactual is computed from the run's own t=0 snapshot: what a competent buyer would have believed, when they would have found out, and the downtime plus emergency-freight cost that follows. Set against what the agent actually committed. - **Emergency spend that is defensible** — every rupee traces to a plan with workings, a cost-of-delay comparison, and either an authority check or a human signature. - **An audit trail that answers "why"** — nine kinds of event, each carrying the reasoning that produced it. Exportable as JSON. - **Supplier truth on record** — contradictions and hedging attach to the supplier permanently and feed straight back into the allocation maths through `effectiveReliability`. - **No integration project to start** — a workbook is enough. Import it, or connect it live. ### 5.4 What it deliberately does not claim - It does not replace the buyer. It does the assessment; a human still owns anything above the threshold, and the threshold is a setting. - It does not learn between runs. Supplier memory lives inside a run. - It does not touch a real ERP, contact a real supplier, or move money. Email delivery is off unless explicitly enabled, and even then it goes only to an address the operator owns. - It is not a forecasting system. It reacts to disruption; it does not predict demand. --- ## 6. The screens, one line each | # | Screen | Route | Its job | |---|---|---|---| | 1 | Mission Control | `/` | Choose the disruption and the seed | | 2 | **Agent Console** | `/run/[id]` | **Watch it detect, investigate, decide, act — one step at a time** | | 3 | Approvals | `/run/[id]/approvals` | You are the human in human-in-the-loop | | 4 | Mail | `/run/[id]/mail` | The correspondence, threaded, with each reply tagged firm or not | | 5 | Suppliers | `/run/[id]/suppliers` | Private portal links — hand one to a real person | | 6 | ERP Records | `/run/[id]/erp` | Proof the world moved · import, export, or connect a live workbook | | 7 | What it prevented | `/run/[id]/impact` | The counterfactual, computed rather than asserted | | 8 | Audit & Score | `/run/[id]/audit` | Every decision, with reasoning · rubric score · JSON export | | 9 | Supplier Portal | `/supplier/[token]` | Outside the company. No navigation, no login | | — | Integrations | `/integrations` | What is actually connected: model, email, sheet, store | | — | Engine Lab | `/lab` | The solvers with no agent attached — turn the dials yourself | --- ## 7. First fifteen minutes ```bash npm install cp .env.example .env.local # add LLM_API_KEY (+ LLM_ENDPOINT for azure-ai) npm run dev ``` 1. Open `http://localhost:3000`. Pick **S7 — Compound**. Press **Start**. 2. Press **Step** four or five times. Read the left column: each card is one cycle, with the agent's own reason for the action above the action itself. 3. When it verifies a dispatch claim, open **Audit** and find the `caught a lie` entry. 4. Press **Run** and let it work until the approvals badge lights up in the sidebar. 5. Open **Approvals**. Read the brief. Press **Reject** — then watch it find a cheaper route. 6. Open **What it prevented**, then **Audit & Score**. 7. Now go back to Mission Control, change the seed, and run it again. Nothing repeats. To make it yours: **ERP Records → download the template**, fill in your own parts and suppliers, connect it, and edit a cell while the agent is running.