# CASEAN T-TOS interactive prototype (Work items #78 A2-002, #79 A2-003, #80 A2-004)

Clickable, static HTML/CSS/JS. No build step, no npm, no server. Extends the low-fi frames from A2-001 (`../wireframes/`) and follows `../information-architecture.md` (including section 8, product decisions D1–D12) and `../user-role-matrix.md`.

## Open it

Double-click `index.html` (or open `docs/ia/prototype/index.html` in any current browser). Everything runs from `file://`.

| File | Purpose |
|---|---|
| `index.html` | Entry: pick Buyer / Supplier / Concierge and jump into a flow |
| `app.html` | The app shell (hash-routed: `app.html#/buyer/deals`, `#/supplier/deal/DL-0412/terms`, ...) |
| `prototype.css` | Shared styles. Neutral grays, one green accent, amber only for Proxy Mode and `[PENDING]` |
| `prototype.js` | Vanilla JS: seed data, rules, actions, views, router |

Demo state is saved in `localStorage` (key `casean-proto-a2004-v1`; older keys are ignored, so the demo starts from the seed). **Demo controls** (top bar) resets the data, changes verification tiers, and toggles the `authorized_signatory` flag for TRADER. The role dropdown in the top bar switches ORG_ADMIN / TRADER / OPERATIONS / VIEWER (or, in the concierge shell, CASEAN_SUPPORT / CASEAN_ADMIN / CASEAN_COMPLIANCE_OFFICER). Disabled controls always carry a tooltip or a note giving the reason.

## Sample data

Saigon Agri Imports Co. (buyer, Vietnam), Penang Grain & Spice (buyer, Malaysia, `NEW_COUNTERPARTY`), Prairie Gold Pulse Co-op (supplier, Saskatchewan; the supplier shell), Fraser Valley Oilseeds, Northern Lentil Exporters (`UNVERIFIED`). Seed deals cover each stage:

| Deal | State | Use it to demo |
|---|---|---|
| DL-0412 Red lentils | NEGOTIATING, payment terms open, vessel/containers/agent `[PENDING]` | Progressive terms, accept, whole closing path |
| DL-0431 Yellow peas | TERMS_AGREED, draft frozen, supplier already signed | Buyer sign, lock gate |
| DL-0398 Canola | DOCUMENTS_DEPOSITED (Fraser Valley is the supplier; invisible to the Prairie Gold shell) | Settlement confirmation, tenancy |
| DL-0377 Green lentils | SETTLED | Closed-deal view |

## Demo script (about 8 minutes)

1. **Create RFQ (buyer).** `index.html` > Buyer > *Create an RFQ*. Only the starred fields are required; open *Add optional details* to see the progressive disclosure. Publish: you land on *My RFQs* with the new RFQ highlighted.
2. **Respond (supplier).** Switch shell (top right) > Supplier > *Inquiries*. Open the new RFQ > *Respond*. Pick a lot, leave price blank, submit: the deal opens at `INQUIRY` with unagreed terms `[PENDING]`. Go back and respond with a price instead to see it open at `NEGOTIATING`.
3. **Progressive terms (buyer).** Buyer > *Deals* > DL-0412 > *Terms*. Note `[PENDING]` on payment terms (core) and vessel/containers/agent (secondary). Click *Edit terms*: tick *Mark as [PENDING]* on a secondary field, set payment terms, save. The Activity tab records the diff.
4. **Accept to TERMS_AGREED.** Buyer: *Accept terms*. Switch to Supplier > DL-0412 > Terms > *Accept terms*. The stepper moves to `TERMS_AGREED`. (Accepting while a core field is still `[PENDING]` is allowed with a warning; signing and locking are not.)
5. **Trade Sheet (concept).** Trade Sheet tab: the live preview shows `[PENDING]` markers; *Freeze draft*; sign as Supplier; switch to Buyer and sign. *Lock Trade Sheet* is enabled only when every line in **Lock gate** is met.
6. **Prove the gate.** Before locking, open *Demo controls* and set Prairie Gold to `UNVERIFIED`: Lock disables and names the unmet check. Restore Tier 1, lock. A SHA-256 appears and the PDF row shows in Documents as archived. (Switch the role to TRADER to see Sign disabled; tick the signatory flag to enable it.)
7. **Revision rule.** On DL-0431 (TERMS_AGREED, supplier signed) edit any term as buyer: sign-offs are revoked and the sheet becomes Rev 2.
8. **Documents and settlement.** Supplier > DL-0412 > Documents: *Upload* the three required documents, *Mark documents deposited*, record settlement evidence, then Buyer confirms: `SETTLED`.
9. **Concierge proxy.** Concierge workspace > Queue > *Act on behalf of Penang Grain & Spice* (or Organizations > any org). Give a reason. The amber banner and amber chrome appear. Create an RFQ, or open a deal where the represented org is a party and edit terms or upload a document. Activity shows `CASEAN_CONCIERGE_PROXY`, the operator, the represented org and the reason, visible to both sides. *Accept terms*, *Sign* and *Lock* are disabled with a reason; *Remind signatories* works. *Exit proxy* returns to read-only. Switch the role to CASEAN_COMPLIANCE_OFFICER: every proxy button disables (IA D1).

## Guided path and Assist (IA D11/D12, concept)

Concept notes: `guide/CONCEPT.md`; principle: `../guided-and-assist.md`. Full Milestone 1 facilitator path is in `docs/milestone-1/walkthrough-script.md` (about 5–7 minutes). Short click path (no tab tour):

1. Buyer > *Home*: the **Next step** card names the one thing to do; rows under *Needs your action* carry a *Do this* button.
2. Open DL-0412 > *Overview*: the **Guide** card shows the stage checklist and one primary button. Landed Cost and Trade Sheet are described as optional until terms are agreed. Click *I don't know: ask CASEAN*, send: Activity logs the request.
3. Top bar > **Assist** > *What should I do next?* answers from the same rules. Then paste: `Hi, 600 MT at USD 780/MT CIF, L/C at sight. Freight TBD.` > *Propose terms*. A `PROPOSED / AI draft` diff appears (freight is ignored on purpose). *Dismiss* changes nothing; *Accept & save* asks you to confirm, then Activity shows "AI draft accepted". A price/Incoterm on an INQUIRY deal moves it to NEGOTIATING.
4. Concierge > DL-0412 > *Overview*: the Guide suggests Proxy Mode rather than acting (COMPLIANCE is told it has no proxy). Switch role to VIEWER: Guide shows why you cannot act, with *Open* instead of *Do this now*.

Scripted, no LLM: AI proposes, you confirm (ADR-0006).

## Vault demo script (A2-003, about 5 minutes)

Concept notes: `vault/CONCEPT.md`. The demo date is fixed at 31 Oct 2026 so expiry statuses are stable.

1. **Library (supplier).** `index.html` > Supplier > *Vault library*. Tabs: *Documents* (filter by the six spec categories), *Checklists* (one card per open deal with a completeness meter), *Expiring* (expired, within 60 days, later). Prairie Gold has an expired Organic certificate and a HACCP certificate expiring in 35 days; neither blocks anything.
2. **Deal checklist statuses.** Supplier > Deals > DL-0431 > Documents: SGS `IN VAULT` (open *Version history (2)*), Phytosanitary `EXPIRED`, B/L `NOT YET DUE`. DL-0412 > Documents shows SGS `MISSING`. The legend lists all five statuses.
3. **Replace creates a new version.** DL-0431 > Documents > Phytosanitary > *Replace: new version*. Enter a later issue and expiry date, add a reason, *Register in Vault as v2*. You return to the deal tab with a receipt (pre-signed link, direct upload, SHA-256). The status turns `IN VAULT`; v1 is still in the history.
4. **Upload with progressive disclosure.** Vault > *Upload document*. Required: file, category, issuer, issue date. Pick *Corporate certifications* to make the expiry date required. Open *Add optional details* for lot/batch and reference. Optionally link a deal and checklist item; picking an item that already has a file turns the upload into the next version.
5. **Checklist upload.** DL-0412 > Documents > SGS > *Upload*: category, type, issuer and issue date are prefilled; register in one click. Repeat for the other two, then follow demo step 8 above.
6. **Document detail.** Open any document: metadata, version history with SHA-256 per version, *Download* (issues a simulated 15-minute pre-signed link and logs it on the deal).
7. **Roles.** Switch the role to VIEWER: every upload control disables with a reason; checklists, expiry and downloads still work. Buyer shell > Vault shows documents from the buyer's own deals; a supplier's organisation-level certificates are not visible to the buyer.
8. **Concierge proxy.** Concierge > Organizations > *Act on behalf of* Prairie Gold > Vault > Upload. Versions carry the `PROXY` stamp and reason; deal-linked uploads appear on Activity as `CASEAN_CONCIERGE_PROXY`.

## Dossier demo script (A2-004, about 6 minutes)

Concept notes: `dossier/CONCEPT.md`. Specs: `specs/trade-intelligence-dossier.md` (AC-001..008), ADR-0005, ADR-0007, IA D1. Start with *Demo controls > Reset demo data*.

1. **Public card and directory (buyer).** `index.html` > Buyer > *Supplier directory*. Three suppliers with tier badge, public certification logos, completed-deal count or `NEW_COUNTERPARTY` (Northern Lentil), and completeness as a plain percentage. Use the *Show* filter. There is no sort by trust, score or rank. Open *Prairie Gold Pulse Co-op*: the card, *What the tiers mean*, your deals with them, and a note on what is never shown (registration and tax numbers, tax documents, reviewer notes, sanctions, disputes). Prairie Gold has no certification logo yet; step 5 adds one.
2. **Same badge everywhere.** Buyer > *Deals*, a deal Overview, *Trade Sheet* parties, and Supplier > *Inquiries* all show the same tier badge and `NEW_COUNTERPARTY` (Penang). Org names link to the public card. Supplier shell > *Buyers* is the mirror directory.
3. **Own dossier (buyer).** Buyer > *Organization*. *Profile & Dossier*: completeness meter (60%), what is still missing, the five day-one fields (registration number, address, operating-since, licence numbers, commodities). Type a licence number and save: the meter moves to 70% and the history logs the edit. *Verification*: link a Vault document to *Export / import licence* (pick the Import licence), *Link*, then *Submit for review*. The status goes to `PENDING_REVIEW`; the row locks. Nothing in the app was blocked at 60%. *Public card preview* shows exactly what counterparties see.
4. **Review queue (COMPLIANCE).** Concierge workspace, role *CASEAN_COMPLIANCE_OFFICER* > *Verification*. Three orgs wait: Saigon, Prairie Gold, Northern Lentil. Open *Northern Lentil*: evidence viewer (file, issuer, dates, SHA-256), confidential panel (registration number, sanctions, disputes), tier card. Approve the Certificate of Incorporation. On the tax certificate pick *Request revision*, choose a reason code and write an internal note; without both, it refuses. The *Tier* list has Tier 1 disabled and names what is missing.
5. **Approve and assign tier.** Open *Prairie Gold*: approve both items. The HACCP logo now appears on their public card (buyer > Suppliers). Tier 2 stays disabled until a processing facility proof exists (no Vault document yet), so it cannot be assigned.
6. **What the org sees.** Supplier shell > Organization > Verification (Prairie Gold) shows decisions and reason codes, "CASEAN Compliance" instead of a reviewer name, and never the internal notes (AC-006). Northern Lentil's revision request is shown the same way.
7. **Proxy submission (SUPPORT).** Concierge, role *CASEAN_SUPPORT* > Organizations > *Act on behalf of Northern Lentil* (reason `CS-4510`) > *Organization* > *Verification*. Link the Tax certificate again and submit. History shows `CASEAN_CONCIERGE_PROXY`, the operator and the reason. In the same session every review action is disabled (whoever prepared a submission does not review it). As SUPPORT without proxy, *Verification* shows status only: documents, notes and the confidential panel are masked. As COMPLIANCE, every *Act on behalf of* is disabled (IA D1).
8. **Tier change reaches the deals.** As COMPLIANCE, approve Northern Lentil's tax certificate, then assign `TIER_1_VERIFIED` with a justification. Change Prairie Gold to `UNVERIFIED` with a justification instead: its badge changes in every table, DL-0431 Activity gets a `SYSTEM` line (tier only, never the justification), and the DL-0431 Trade Sheet *Lock gate* names the unmet check. *Verification > Decisions* lists every decision with reviewer ID. The audit trail on the review page holds reviewer ID, time, method and justification (AC-007).
9. **Roles.** In a supplier or buyer shell, TRADER sees the dossier read-only with a reason; OPERATIONS can link evidence but not edit or submit; VIEWER has no Organization nav (IA section 3) but still sees tier and completeness on Home.

## Landed Cost and Trade Sheet demo (A2-005, about 5 minutes)

Concept notes: `landed-cost/CONCEPT.md`, `trade-sheet/CONCEPT.md`. Theme: the screens show only what is known. No new required inputs anywhere.

1. **RFQ to blank-price response.** Buyer > RFQs, open an RFQ, then as supplier respond without a price (see the RFQ demo above). The deal opens at `INQUIRY`; price, Incoterm and payment are `[PENDING]`.
2. **Optional: concierge adds terms.** Concierge > act on behalf of the supplier > the deal > *Terms*: set an Incoterm (e.g. CFR) and a port. Skip if the deal already has them (DL-0412 is CIF).
3. **Landed Cost split.** *Landed Cost (concept)*. With no Incoterm: one empty-state line. With one: "Who pays what under CIF Cat Lai, Ho Chi Minh City", marked illustrative, not advice. Two buckets: *In the seller's price* (labels only, no amounts) and *Your costs (not in price)*, each `ESTIMATE_PENDING` / Excluded from Total, quotes from your broker or forwarder. The unit price is shown as a terms value; "Landed cost total: Not calculated". No platform-fee line, no inputs.
4. **Trade Sheet preview.** *Trade Sheet*: reference, revision, "Draft, not executed", Incoterm with named place, `[PENDING]` markers, a read-only *Documents to be presented* list from the Vault checklist, and vessel/containers/agent/inspection collapsed to "To be advised pre-shipment".
5. **Print.** *Print / save PDF*: the in-sheet banner "CONCEPT — NOT SIGNED — NOT FOR BANK SUBMISSION" is printed with the sheet. Signature lines read "Illustrative signature"; lock records a simulated PDF record. DL-0431 shows the sign and lock walkthrough.

## Product assumptions made

- **Phase labels (IA D7).** Landed Cost has no primary nav; the deal tab is a labelled Phase 1C concept (all cost lines `ESTIMATE_PENDING`, disclaimer, no calculator). Trade Sheet draft, sign and lock are a labelled walkthrough concept; in real 1B they would be read-only with signing disabled.
- **Accepting with pending core fields** is allowed (warn at `TERMS_AGREED`); the hard block is on signing and locking (IA field ladder; TSP AC-003). The spec gates "sign-off", the lock button additionally checks both Tier 1 (Dossier AC-008).
- **Signing** requires ORG_ADMIN, or TRADER with the audited signatory flag (D3). OPERATIONS and VIEWER never. OPERATIONS may edit secondary terms only.
- **Concierge** (CASEAN_SUPPORT / CASEAN_ADMIN) never accepts, signs, locks or confirms `SETTLED` (D2). It may record settlement evidence, draft the sheet, upload documents, and remind signatories. One operator persona stands in for both roles.
- **Core fields** are commodity, spec, quantity, price, currency, incoterm, payment terms (plus buyer and seller, always set). **Secondary** (may print "To Be Agreed Pre-Shipment"): tolerance, ports, shipment window, vessel, containers, shipping agent, inspection agency.
- A deal opens at `INQUIRY` when a supplier responds without terms, and at `NEGOTIATING` once price or Incoterm is proposed. Acceptances clear on any term edit.
- **Vault statuses (A2-003)** are `IN VAULT`, `EXPIRES IN n D` (within 60 days), `EXPIRED`, `MISSING` (due by the deal's milestone, not uploaded) and `NOT YET DUE`. Due-from: SGS at NEGOTIATING, Phytosanitary at TERMS_AGREED, B/L at TRADE_SHEET_LOCKED. They are reminders. *Mark documents deposited* still needs all three on file (the #78 milestone rule) but is not blocked by an expired one; the counterparty sees the status.
- Expiry date is required only for Corporate certifications; elsewhere it is optional.
- Verification tier never blocks navigation, RFQs or negotiation; it gates only the lock.
- Counterparties see each other's tier badge and `NEW_COUNTERPARTY` (no completed deals), never a score.
- **Dossier (A2-004).** Five day-one profile fields plus five evidence slots (Certificate of Incorporation and Tax certificate for Tier 1; licence, facility proof and food-safety certificate for Tier 2). Completeness = items filled or linked (not rejected or in revision) out of ten. It is informational only. Approvals unlock a tier; a reviewer still assigns it explicitly with a justification. Tier 2 needs all five items approved.
- Public card shows certification logos only after a reviewer approves the food-safety evidence. Registration and licence numbers, tax documents, reviewer notes, sanctions and dispute flags are confidential (AC-006): the owning org sees its own numbers and tax document; COMPLIANCE and ADMIN see everything; SUPPORT sees status only.
- **Roles on the dossier.** ORG_ADMIN edits and submits. OPERATIONS may link Vault evidence (proposed in the role matrix) but not submit. TRADER and VIEWER are read-only. SUPPORT and ADMIN prepare and submit only in Proxy Mode, stamped. COMPLIANCE and ADMIN review; SUPPORT cannot; nobody reviews while in Proxy Mode (segregation of duties, added here).
- Reviewer notes are internal. The org sees decision, reason code and a generic "CASEAN Compliance"; it never sees the note, reviewer name or ID.
- Corporate identity papers (Certificate of Incorporation, Tax certificate) are filed in the Vault under *Corporate certifications* without an expiry date, and the tax certificate is flagged `CONFIDENTIAL`. The six Vault categories have no corporate-identity category; product should decide.
- A completed deal (both parties confirm `SETTLED`) increments each org's completed-deal count in the demo.

## Known limits

- Single-browser, single-user demo: "two parties" means switching shells. No real auth, no multi-user sync.
- Uploads are simulated (a named sample file, or the name of a file you pick, is attached); no file is stored, and the per-version SHA-256 covers the file name and metadata, not file bytes. Pre-signed upload and download links are UX copy only. The Trade Sheet hash is a real SHA-256 of the deal terms, signatures and revision, computed in the browser. "Print / save PDF" uses the browser print dialog.
- Not built: Hybrid trader Buyer/Supplier context switch (D4), saved suppliers and buyers, Organization Team and Audit log tabs, commercial-reference evidence, `SUSPENDED` and `REJECTED` organisation states (ADR-0005), cross-org Vault (all), Reference Data, Audit & Governance (shown greyed in the nav), internal-only concierge deal notes (D10), RFQ editing or closing, multi-supplier responses to one RFQ, amending a locked Trade Sheet.
- Out of scope by design: tracking, dispatch, payments, escrow, wallets, rankings, risk scores, counterparty risk index (Phase 3), inspection-agency and logistics shells.
- Desktop-first; usable at phone width (nav becomes a scrolling bar, tables scroll horizontally).
- Verified by scripted run in headless Chrome (RFQ to settlement, gates, proxy stamps; A2-004 dossier flows: directory, submit, approve, revision, tier assignment, masking by role, proxy segregation). Not yet reviewed by a separate agent, and not tested in Safari or Firefox.