diff --git a/docs/README.md b/docs/README.md
index be08a7d..4a27457 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,6 +9,7 @@ built, operated, and evolved.
 |-----------------|---------------------------------------------------------------------|
 | `architecture/` | Architecture, boundaries, invariants, and ADRs                      |
 | `development/`  | Local development and implementation guidance                       |
+| `discovery/`    | Phase reports: Phase 0 assessment, Phase 1 review                   |
 | `engineering/`  | Engineering process and standards — testing, quality, workflow      |
 | `operations/`   | Deployment, infrastructure, monitoring, and incident procedures     |
 | `product/`      | Product requirements, scope, personas, goals, and product decisions |
@@ -18,10 +19,14 @@ built, operated, and evolved.
 - New contributor? The repository [`../README.md`](../README.md) covers setup.
 - Building a change? [`engineering/definition-of-done.md`](engineering/definition-of-done.md)
   and [`engineering/git-workflow.md`](engineering/git-workflow.md).
-- Understanding the system? [`product/vision.md`](product/vision.md),
+- Understanding the product? [`product/product-requirements.md`](product/product-requirements.md)
+  and [`product/user-journeys.md`](product/user-journeys.md).
+- Understanding the system? [`architecture/system-overview.md`](architecture/system-overview.md),
+  [`architecture/domain-context-map.md`](architecture/domain-context-map.md),
   [`architecture/INVARIANTS.md`](architecture/INVARIANTS.md), and the ADRs in
   [`architecture/adr/`](architecture/adr/).
-- Where the marketplace is headed? [`architecture/marketplace-migration.md`](architecture/marketplace-migration.md).
+- How Nexo 2.0 got here? [`discovery/`](discovery/): the Phase 0 assessment and the
+  Phase 1 review.
 
 ## Documentation Principle
 
diff --git a/docs/architecture/INVARIANTS.md b/docs/architecture/INVARIANTS.md
index c61d896..469222b 100644
--- a/docs/architecture/INVARIANTS.md
+++ b/docs/architecture/INVARIANTS.md
@@ -1,85 +1,172 @@
 # System Invariants
 
-These are properties that must remain true regardless of implementation details.
+- **Status:** Revised 2026-11-01 (Phase 1 draft for owner review). This replaces the 2026-08-30 list. Every earlier invariant is kept, reworded or strengthened; the changes are listed at the end.
 
-They represent architectural constraints rather than feature requirements.
+These properties must hold regardless of implementation. Each one names its **enforcement**, meaning the mechanism that makes a violation impossible or detectable, and its **proof**, meaning the test or check that demonstrates it. An invariant without both is a wish, not an invariant.
+
+Requirement documents cite these as **[INV-n]**.
 
 ---
 
-## Vendor Isolation
+## Access and identity
 
-Vendor-context queries must only expose records belonging to the
-authenticated vendor.
+**INV-1 · Vendor isolation.** A vendor context can read or change only records owned by its vendor. Storefront catalogue queries are intentionally not vendor-scoped.
 
-Storefront catalog queries are intentionally not vendor-scoped.
+- **Enforcement:** the `vendor.context` middleware fails closed; there is no global scope; route bindings are scoped; vendor queries require an explicit `vendorId`.
+- **Proof:** the isolation suite (merge gate), plus an arch test that every vendor controller is covered (ADR-0011).
 
----
+**INV-2 · Identity.**
 
-## Marketplace Identity
+- A customer identity is marketplace-wide.
+- A user is a member of at most one vendor.
+- Platform staff belong to no vendor and place no orders.
+- **Enforcement:** unique `vendor_members.user_id`, and application guards.
+- **Proof:** domain tests.
 
-A shopper has one marketplace-wide identity.
+## Orders
 
-A vendor-team user belongs to exactly one vendor.
+**INV-3 · Order structure.**
 
-A platform operator does not belong to a vendor.
+- An OrderGroup is one customer checkout.
+- A VendorOrder is exactly one vendor's portion, and all of its lines belong to that vendor.
+- The group total equals the sum of its VendorOrder totals at creation.
+- **Enforcement:** the checkout use case, plus a DB foreign key from line → variant → vendor that is checked at creation.
+- **Proof:** property test over random carts.
 
----
+**INV-4 · Refund isolation.** A refund, cancellation or dispute outcome on one VendorOrder never changes the state or ledger entries of a sibling VendorOrder.
 
-## Order Structure
+- **Proof:** sibling-unchanged assertions in every refund and cancellation test.
 
-An `OrderGroup` represents one shopper checkout.
+**INV-5 · Refund cap.** For each VendorOrder, the sum of refunds in `requested | approved | submitted | succeeded` never exceeds the captured amount allocated to it. Per line, refunds never exceed the line's net amount.
 
-An `Order` represents exactly one vendor's portion of that checkout.
+- **Enforcement:** guarded counter updates on `vendor_orders.refund_committed_minor` and `vendor_order_lines.refund_committed_qty` (ADR-0015 §9).
+- **Proof:** concurrent refund test on MySQL.
 
-An order must never contain products belonging to multiple vendors.
+**INV-6 · Snapshots and frozen rates.** Line prices, names and options, allocated discounts and points, shipping amounts, and the commission rate are fixed when a VendorOrder is created. Later catalogue, price or commission-configuration changes never alter existing orders.
 
----
+- **Proof:** mutation-after-order tests.
 
-## Payment Ownership
+**INV-14 · Guarded transitions.** OrderGroup, VendorOrder, ReturnRequest, Refund, PaymentAttempt, Reservation and Vendor statuses change only through their state machine. Each change uses a conditional update on the current status, so concurrent transitions cannot both succeed.
 
-An `OrderGroup` has exactly one PaymentIntent for its total.
+- **Proof:** an arch test (no status assignment outside state machines), plus concurrent transition tests.
 
----
+## Inventory
 
-## Refund Isolation
+**INV-7 · Stock.** For every variant:
 
-A refund against one vendor's `Order` must never alter the financial state
-of another vendor's `Order`.
+- `0 ≤ reserved ≤ on_hand`;
+- `reserved = Σ qty of active reservations`;
+- `on_hand = Σ delta_on_hand of movements`.
 
----
+Stock is never oversold.
 
-## Commission
+- **Enforcement:** DB CHECK constraint, conditional updates, and the unique movement key.
+- **Proof:** parallel-process tests and the nightly reconciliation check (ADR-0014).
 
-The commission rate applied to an order is frozen at order creation.
+## Money
 
-Changing the platform commission configuration must not alter historical orders.
+**INV-8 · Exact allocation.** Every split (discounts, points value, commission, dispute amounts) sums exactly to its source amount, in integer minor units.
 
----
+- **Proof:** property tests (ADR-0013).
 
-## Inventory
+**INV-9 · Idempotency.**
 
-Inventory must never be oversold.
+- One OrderGroup per (customer, checkout key).
+- One effect per provider event id.
+- At most one active payment attempt per group.
+- At most one succeeded attempt per group.
+- At most one ledger transaction per (type, reference).
+- At most one consumption per inbox (consumer, message).
+- **Enforcement:** unique keys.
+- **Proof:** concurrent duplicate tests.
 
-Stock reservation and release operations must be concurrency-safe.
+**INV-10 · Ledger.**
 
----
+- Every ledger transaction balances (Σ debits = Σ credits, single currency).
+- Entries are append-only.
+- Balances are derived from entries.
+- **Proof:** the posting-service assertion, the nightly check, and property tests (ADR-0016).
 
-## Vendor Visibility
+**INV-11 · Paid means captured.** An OrderGroup is `paid` if and only if exactly one PaymentAttempt has `succeeded`, with amount and currency equal to the group total. A provider event with a mismatched amount never marks a group paid.
 
-A vendor's products are sellable only when the vendor satisfies the required
-marketplace approval and payment-onboarding conditions.
+- **Proof:** webhook processing tests plus nightly reconciliation.
 
----
+**INV-16 · Payout safety.**
 
-## Auditability
+- A payout never exceeds the vendor's available balance net of receivable.
+- Held funds are never paid out.
+- Each payout run pays each vendor at most once.
+- **Proof:** concurrent payout-run test.
 
-Money-moving operations and material vendor-state changes must produce an
-auditable record.
+**INV-17 · Points.**
 
----
+- A customer's spendable points balance equals the sum of their points-ledger entries and is never negative.
+- Redemptions are held, then confirmed or released, exactly once.
+
+**INV-18 · Promotion limits.** Confirmed plus pending redemptions never exceed a promotion's total or per-customer limit.
+
+- **Enforcement:** a conditional update on the usage counter.
+- **Proof:** parallel test on the last allowed use.
+
+## Catalogue and vendors
 
-## Documentation
+**INV-12 · Sellability.** A product is visible in the storefront and purchasable only if all of these hold:
 
-Boundary-shaping architectural decisions must have an ADR.
+- product `active`;
+- not blocked;
+- vendor `approved`;
+- at least one active variant.
+
+One implementation is used by the storefront, search indexing and checkout.
+
+- **Proof:** a sellability matrix test across all three paths.
+
+**INV-13 · Vendor lifecycle.**
+
+- Vendor status is always one of `pending | approved | suspended`, and changes only through defined transitions.
+- Vendors are never physically deleted.
+- **Enforcement:** DB CHECK constraint, the state machine, and `RESTRICT` foreign keys.
+
+## Platform
+
+**INV-15 · Events if and only if commit.** An integration event is published if and only if the transaction that produced it commits. Consumers tolerate duplicates and reordering.
+
+- **Enforcement:** the outbox and inbox (ADR-0017).
+- **Proof:** rollback and duplicate tests.
+
+**INV-19 · Auditability.** These actions write an audit record (actor, impersonator if any, action, subject, before/after, IP, timestamp) in the same transaction as the change:
+
+- money-moving actions;
+- vendor lifecycle changes;
+- moderation;
+- commission changes;
+- staff changes;
+- reconciliation resolutions;
+- impersonation.
+
+**INV-20 · Environment isolation.**
+
+- No Nexo 2.0 environment holds legacy production credentials.
+- No environment accepts live payment keys.
+- Tests run only against databases whose names end in `_testing`.
+- **Enforcement:** boot checks and the test bootstrap guard (ADR-0009, ADR-0021).
+
+**INV-21 · Documentation.** Boundary-shaping decisions have an ADR. Scope changes update the product documents in the same change.
+
+---
 
-Changes to product scope must update the corresponding product documentation.
\ No newline at end of file
+## Changes from the 2026-08-30 version
+
+| Earlier invariant | Now |
+|---|---|
+| Vendor Isolation | INV-1, with enforcement made explicit |
+| Marketplace Identity | INV-2, adding "staff place no orders" |
+| Order Structure | INV-3 |
+| Payment Ownership ("exactly one PaymentIntent for its total") | INV-9 / INV-11: retries can create several attempts over time; at most one active and at most one succeeded |
+| Refund Isolation | INV-4, plus the new refund cap INV-5 |
+| Commission (frozen at creation) | INV-6, extended to every snapshot |
+| Inventory | INV-7, made quantitative |
+| Vendor Visibility ("approval and payment-onboarding conditions") | INV-12; payment onboarding removed (no Stripe Connect, D-6) |
+| Auditability | INV-19, with an explicit list |
+| Documentation | INV-21 |
+| — | New: INV-8, 10, 13–18, 20 |
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index 5b1c60b..a9d20f6 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -1,30 +1,50 @@
 # Architecture Documentation
 
-This directory records the architectural boundaries, invariants, and decisions
-that shape Nexo.
+This directory records Nexo's architectural boundaries, invariants and decisions.
 
 ## Contents
 
-| Path                        | Purpose                                                              |
-|-----------------------------|--------------------------------------------------------------------|
-| `INVARIANTS.md`             | Properties that must hold regardless of implementation             |
-| `marketplace-migration.md`  | The plan for pivoting from multi-tenant SaaS to a single marketplace |
-| `adr/`                      | Architecture Decision Records                                       |
+| Path | Purpose |
+|---|---|
+| [`system-overview.md`](system-overview.md) | Runtime components, code organisation, key flows |
+| [`domain-context-map.md`](domain-context-map.md) | Modules (bounded contexts), owned data, relationships, glossary |
+| [`dependency-rules.md`](dependency-rules.md) | Allowed and forbidden dependencies, enforced by arch tests |
+| [`database-design.md`](database-design.md) | Initial database model, constraints and table ownership |
+| [`INVARIANTS.md`](INVARIANTS.md) | Business invariants [INV-n], each with enforcement and proof |
+| [`security-model.md`](security-model.md) | Roles, permission matrix, isolation and enforcement points |
+| [`integration-contracts.md`](integration-contracts.md) | Browser ↔ Laravel, module ↔ module, and Nexo ↔ Stripe contracts |
+| [`financial-model.md`](financial-model.md) | Ledger, commission, refunds, disputes, payouts, reconciliation, worked examples |
+| [`lifecycles/`](lifecycles/) | Checkout and payment, inventory, orders/fulfilment/returns: state machines and failure-scenario matrices |
+| [`vendor-domain-design.md`](vendor-domain-design.md) | Vendor entity design (2026-09), still current |
+| [`marketplace-migration.md`](marketplace-migration.md) | *Superseded:* SaaS-to-marketplace migration plan |
+| [`adr/`](adr/) | Architecture Decision Records |
 
 ## Architecture Decision Records
 
-An ADR captures **one** boundary-shaping decision: why it was made, what was
-rejected, and what must now be lived with. See
-[`adr/0001-adr-template-and-process.md`](adr/0001-adr-template-and-process.md)
-for when to write one and the template to use.
+The template is [`adr/ADR-TEMPLATE.md`](adr/ADR-TEMPLATE.md) (ADR-0006). Proposed ADRs are not implemented until the owner accepts them.
 
-| ADR | Decision |
-|-----|----------|
-| [0001](adr/0001-adr-template-and-process.md) | ADR template and process |
-| [0002](adr/0002-vendor-is-a-tenant-record.md) | A "vendor" is the existing tenant record, reframed |
-| [0003](adr/0003-context-dependent-vendor-scoping.md) | Context-dependent vendor scoping (retire the blanket global scope) |
-| [0004](adr/0004-order-group-and-per-vendor-orders.md) | One basket, one payment, one Order per vendor |
+| ADR | Decision | Status |
+|---|---|---|
+| [0001](adr/0001-adr-template-and-process.md) | ADR template and process | Accepted; template superseded by 0006 |
+| [0002](adr/0002-vendor-is-a-tenant-record.md) | A vendor is the existing tenant record | Accepted. **Proposed to be marked Superseded by 0005** (fresh database) |
+| [0003](adr/0003-context-dependent-vendor-scoping.md) | Context-dependent vendor scoping | Accepted; refined by 0011 |
+| [0004](adr/0004-order-group-and-per-vendor-orders.md) | One basket, one payment, one order per vendor | Accepted. **Superseded by 0012 on acceptance** |
+| [0005](adr/ADR-0005-vendor-naming.md) | Use Vendor as the seller entity | Proposed. **Recommended: accept** (file to be renamed `0005-vendor-naming.md`) |
+| [0006](adr/0006-adr-process-v2.md) | Nexo 2.0 ADR template and statuses | Accepted (brief) |
+| [0007](adr/0007-product-positioning-currency-and-locales.md) | Portfolio marketplace; MYR; EN primary with AR/MS | Accepted (D-4, D-5) |
+| [0008](adr/0008-repository-and-frontend-stack.md) | This repository; Vue 3 + Inertia + TS | Accepted (D-1, D-2) |
+| [0009](adr/0009-runtime-and-persistence-baseline.md) | Laravel 13 / PHP 8.5; MySQL 8.4 everywhere, including tests | Proposed (D-3) |
+| [0010](adr/0010-modular-monolith-and-dependency-rules.md) | Modular monolith with enforced contracts | Proposed |
+| [0011](adr/0011-identity-roles-and-vendor-isolation.md) | Identity, roles and fail-closed vendor isolation | Proposed |
+| [0012](adr/0012-order-group-and-vendor-orders.md) | OrderGroup + VendorOrder state machines | Proposed |
+| [0013](adr/0013-money-representation-and-allocation.md) | Money: integer minor units, deterministic allocation | Proposed |
+| [0014](adr/0014-inventory-reservations.md) | Inventory: on-hand/reserved, TTL reservations, movement journal | Proposed |
+| [0015](adr/0015-checkout-and-payment-orchestration.md) | Checkout saga, idempotency, webhook-driven payment | Proposed |
+| [0016](adr/0016-financial-ledger-and-simulated-payouts.md) | Double-entry ledger; simulated payouts | Proposed (core approved as D-6; D-9/10/11 pending) |
+| [0017](adr/0017-domain-events-and-transactional-outbox.md) | Transactional outbox and idempotent consumers | Proposed |
+| [0018](adr/0018-backend-frontend-contracts.md) | PHP data objects → generated TS types | Proposed |
+| [0019](adr/0019-search-behind-a-port.md) | Search port, MySQL first | Proposed (D-8) |
+| [0020](adr/0020-platform-administration-in-filament.md) | Filament for staff; Vue for vendors and customers | Proposed |
+| [0021](adr/0021-environments-demo-data-and-production-isolation.md) | Isolated environments; reproducible demo | Proposed |
 
-Engineering standards that do **not** shape a domain, data-isolation, money,
-runtime-dependency, or deployment boundary live in
-[`../engineering/`](../engineering/), not in an ADR.
+Engineering standards that do **not** shape a domain, data-isolation, money, runtime-dependency or deployment boundary live in [`../engineering/`](../engineering/), not in an ADR.
diff --git a/docs/architecture/adr/0006-adr-process-v2.md b/docs/architecture/adr/0006-adr-process-v2.md
new file mode 100644
index 0000000..0eb6abe
--- /dev/null
+++ b/docs/architecture/adr/0006-adr-process-v2.md
@@ -0,0 +1,77 @@
+# ADR-0006: Adopt the Nexo 2.0 ADR template and status model
+
+- **Number:** 0006
+- **Status:** Accepted (settled by the Nexo 2.0 brief §4.3 and §18)
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+- **Supersedes:** the template section of ADR-0001 (its "when to write one" rules stay in force)
+
+---
+
+## Context
+
+ADR-0001 introduced ADRs with a four-section template: Context, Decision, Alternatives, Consequences. The Nexo 2.0 brief requires more fields:
+
+- problem;
+- decision drivers;
+- considered alternatives;
+- positive and negative consequences;
+- risks;
+- testing implications;
+- migration implications.
+
+It also requires the statuses Proposed, Accepted, Rejected, Deprecated and Superseded.
+
+Two template files currently exist: the one inside ADR-0001 and `ADR-TEMPLATE.md`. Filenames are inconsistent; `ADR-0005-vendor-naming.md` breaks the `NNNN-kebab-title.md` rule.
+
+## Problem
+
+Which template, statuses and location do Nexo 2.0 ADRs use?
+
+## Decision drivers
+
+- Compliance with the brief.
+- One template, not two.
+- Keep the existing repository convention, so no churn for its own sake.
+
+## Considered alternatives
+
+### A. Move ADRs to `docs/decisions/ADR-NNNN-*.md` (the brief's example layout)
+
+Rejected. The brief says to adapt to existing repository conventions. `docs/architecture/adr/` already holds ADR-0001 to ADR-0005, and moving them breaks links for no gain.
+
+### B. Keep the location; adopt the brief's fields in `ADR-TEMPLATE.md` (chosen)
+
+## Decision
+
+1. ADRs stay in `docs/architecture/adr/`, named `NNNN-short-kebab-title.md` and numbered sequentially.
+2. `ADR-TEMPLATE.md` is the single template. It contains every field the brief requires.
+3. Statuses are: Proposed, Accepted, Rejected, Deprecated, and Superseded by ADR-XXXX.
+4. **Proposed ADRs are not implemented.** An ADR moves to Accepted only on owner approval, and the approval date is recorded in the status line.
+5. After acceptance, only the status line changes. A changed decision needs a new ADR.
+6. The ADR index in `docs/architecture/README.md` is updated in the same change as any ADR.
+
+## Positive consequences
+
+- Every significant decision records its testing and migration implications, which feed the Phase 3–5 test plans directly.
+
+## Negative consequences
+
+- Longer ADRs. This is mitigated by keeping one decision per ADR.
+
+## Risks
+
+- ADRs drift from the code. Mitigation: the definition of done requires ADR references in pull requests that touch a decided boundary.
+
+## Testing implications
+
+None directly.
+
+## Migration implications
+
+- ADR-0001 to ADR-0005 keep their original format; they are not rewritten.
+- `ADR-0005-vendor-naming.md` should be renamed to `0005-vendor-naming.md` when ADR-0005 is accepted (owner action listed in the Phase 1 review).
+
+## Related
+
+- ADR-0001; the brief §4.3 and §18.
diff --git a/docs/architecture/adr/0007-product-positioning-currency-and-locales.md b/docs/architecture/adr/0007-product-positioning-currency-and-locales.md
new file mode 100644
index 0000000..1dafc12
--- /dev/null
+++ b/docs/architecture/adr/0007-product-positioning-currency-and-locales.md
@@ -0,0 +1,103 @@
+# ADR-0007: Position Nexo as a portfolio-grade general marketplace in MYR, English-primary
+
+- **Number:** 0007
+- **Status:** Accepted, by owner decisions D-4 and D-5 (2026-11-01)
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+- **Supersedes:** the product framing in `docs/product/vision.md`, `scope.md`, `goals.md` and `personas.md` (ratified 2026-08-30), and `docs/architecture/marketplace-migration.md`
+
+---
+
+## Context
+
+The existing product documents describe **aljebal-albeedos**:
+
+- a Sudan-market, Arabic-first marketplace;
+- settlement in SDG;
+- Stripe Connect transfers paying each vendor;
+- a migration plan for an existing live SaaS database.
+
+The Nexo 2.0 brief describes something different:
+
+- **Nexo**, a premium multi-vendor general-merchandise marketplace;
+- built as a portfolio showcase that must feel like a credible commercial product;
+- on a fresh database, with no connection to the old production data.
+
+Phase 0 found (R2) that the Sudan + Stripe pairing was not viable as a real payment design. Stripe does not operate in Sudan, which is an assumption based on Stripe's published country list as of mid-2026.
+
+## Problem
+
+What product, market, currency and locale set do the Phase 1 specifications assume?
+
+## Decision drivers
+
+- Brief §2: the purpose is portfolio credibility for recruiters and engineers.
+- A payment provider that genuinely supports the currency in test mode.
+- A real RTL locale, to demonstrate internationalisation (brief §16).
+- One currency, to keep the financial model provable.
+
+## Considered alternatives
+
+### A. Keep aljebal-albeedos, SDG, Arabic-primary
+
+Rejected (D-4). This contradicts the brief's purpose, and SDG has no Stripe support.
+
+### B. USD, English-primary
+
+This was a viable option. Owner chose MYR instead.
+
+### C. MYR, English-primary, with Arabic (RTL) and Malay as full peers (chosen)
+
+- Stripe supports MYR, including card payments in test mode.
+- Malay is a natural second locale.
+- Arabic demonstrates genuine RTL.
+
+### D. Multi-currency display
+
+Rejected. It needs an FX ADR and complicates the ledger and refunds, with no showcase benefit proportional to the cost.
+
+## Decision
+
+1. **Product:** Nexo, a single unified multi-vendor general-merchandise marketplace. It has three surfaces: customer storefront, vendor dashboard and platform administration.
+2. **Settlement and display currency: MYR only.**
+   - Amounts are stored as integer sen (see ADR-0013).
+   - Every money column carries an explicit `currency` value, so a second currency later is an additive change.
+3. **Locales:**
+   - `en` is primary and the fallback.
+   - `ar` (full RTL) and `ms` are full peers. Every UI string ships in all three before a feature is done.
+4. **Prices are tax-inclusive.** Nexo v2 does not calculate, itemise or remit tax.
+   - This is a stated product limitation, not an oversight.
+   - A tax engine needs its own ADR.
+5. **Market framing for demo content: Malaysia.**
+   - Fictional vendors and customers.
+   - Malaysian addresses and shipping zones: Peninsular, Sabah/Sarawak/Labuan.
+6. The previous product documents stay in the repository marked **Superseded** for history.
+
+## Positive consequences
+
+- The payment design can be exercised end to end in Stripe test mode.
+- One currency keeps allocation, rounding and reconciliation exact and testable.
+
+## Negative consequences
+
+- Arabic users see prices in MYR. This is acceptable for a showcase.
+- No tax handling. This is visible to a knowledgeable reviewer, so it is stated in the README limitations.
+
+## Risks
+
+- Malaysian regulations (PDPA, SST registration) are out of scope. All demo data is fictional. The README must say Nexo is not a production service.
+
+## Testing implications
+
+- Locale coverage tests: every translation key exists in `en`, `ar` and `ms`.
+- RTL visual checks in Phase 9.
+- Money formatting tests per locale.
+
+## Migration implications
+
+- Product documents are superseded. New `product-requirements.md` and `functional-requirements.md` replace them.
+- The REQ-VENDOR-* identifiers are carried into the new functional specification.
+
+## Related
+
+- ADR-0013 (money); `docs/product/product-requirements.md`; Phase 0 report §A.8.
diff --git a/docs/architecture/adr/0008-repository-and-frontend-stack.md b/docs/architecture/adr/0008-repository-and-frontend-stack.md
new file mode 100644
index 0000000..0f0aa0c
--- /dev/null
+++ b/docs/architecture/adr/0008-repository-and-frontend-stack.md
@@ -0,0 +1,98 @@
+# ADR-0008: Build Nexo 2.0 in this repository with Vue 3, Inertia and TypeScript
+
+- **Number:** 0008
+- **Status:** Accepted, by owner decisions D-1 and D-2 (2026-11-01)
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+Phase 0 found two candidate foundations.
+
+**The old repository `AdilAzhari/nexo-ecommerce`:**
+
+- Laravel 12, Vue 3, Inertia 2, Filament.
+- Extensive, but with critical defects in payments, inventory and vendor authorisation.
+- Its CI/CD is connected to a production database.
+
+**This repository `Sentients-AI/Nexo`:**
+
+- A clean Laravel 13 / PHP 8.5 shell: Pest 5, Larastan, Pint, arch tests and an engineering handbook.
+- Branch `feat/vendor-frontend` (61 commits) holds a tested React 19 vendor workspace.
+- `main` contains no frontend framework.
+
+The brief's technology baseline names Vue and Inertia.
+
+## Problem
+
+Which repository is the foundation, and which frontend framework does v2 use?
+
+## Decision drivers
+
+- A clean history and no inherited production coupling.
+- Alignment with the brief's baseline.
+- Reuse of the highest-quality existing work, where it does not compromise the above.
+
+## Considered alternatives
+
+### A. Continue in the old repository on an orphan branch
+
+Rejected (D-2). It inherits deploy pipelines wired to production and a confusing history.
+
+### B. Use this repository with React, reusing `feat/vendor-frontend`
+
+Rejected (D-1). The owner prefers the brief's Vue baseline.
+
+### C. Use this repository with Vue 3 + Inertia + TypeScript, keeping the React work as reference (chosen)
+
+## Decision
+
+1. `Sentients-AI/Nexo` is the Nexo 2.0 repository. The old repository is a read-only historical reference.
+2. v2 starts from `main`, the Laravel 13 shell. `feat/vendor-frontend` is not merged.
+3. The frontend is **Vue 3 (Composition API, `<script setup>`) + `@inertiajs/vue3` + TypeScript in strict mode**, built by Vite and styled with Tailwind 4.
+   - The exact Inertia major version is chosen in Phase 3. It must match `inertiajs/inertia-laravel`.
+   - Frontend unit and component tests use Vitest + Vue Test Utils.
+4. **Reference material from the React workspace** may be ported, but not copied as code:
+   - design tokens;
+   - framework-neutral TypeScript in `lib/` (money, format, status, countdown);
+   - EN/AR locale strings;
+   - the component inventory;
+   - `docs/frontend/vendor-frontend-spec.md`;
+   - the design handoff.
+5. Nothing from the old repository's application code is copied wholesale. Individual pieces may be ported only when a Phase 3+ task cites them and re-tests them.
+
+## Positive consequences
+
+- A clean, single-purpose history for the portfolio.
+- No inherited production coupling.
+- The brief's stack is honoured.
+
+## Negative consequences
+
+- About 12k lines of tested React UI are not reused directly, so the component kit is rebuilt in Vue in Phase 2/7.
+
+## Risks
+
+- The 61 React commits exist only locally. They are preserved by bundle in `C:\laragon\backups\nexo-2026-11-01\`. The owner should also push them to a reference branch (open item).
+- The history has mixed author emails (D-15). This must be settled before the repository is shown publicly.
+
+## Testing implications
+
+CI gains these steps:
+
+- `npm ci`
+- `vue-tsc --noEmit`
+- ESLint
+- Vitest
+- `vite build`
+
+## Migration implications
+
+- The React-specific files on `feat/vendor-frontend` are never merged to `main`.
+- The Phase 0 report is copied to `docs/discovery/`.
+
+## Related
+
+- ADR-0018 (contracts); Phase 0 report §A.4; ADR-0020 (admin).
diff --git a/docs/architecture/adr/0009-runtime-and-persistence-baseline.md b/docs/architecture/adr/0009-runtime-and-persistence-baseline.md
new file mode 100644
index 0000000..b1b2139
--- /dev/null
+++ b/docs/architecture/adr/0009-runtime-and-persistence-baseline.md
@@ -0,0 +1,92 @@
+# ADR-0009: Run Laravel 13 on PHP 8.5 with MySQL 8.4 in every environment, including tests
+
+- **Number:** 0009
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner (open decision D-3)
+
+---
+
+## Context
+
+- `main` already requires `php ^8.5` and `laravel/framework ^13.17`. Local PHP is 8.5.8.
+- `.env.example` uses MySQL with database and cache-backed queue and cache. `phpunit.xml` and `docs/engineering/testing.md` pin tests to in-memory SQLite. CI installs only `pdo_sqlite`.
+- Phase 0 showed the cost of SQLite tests. The old repository's "concurrency" and "torture" tests passed on SQLite with real double-subtraction and race bugs present, because:
+  - `SELECT … FOR UPDATE` is a no-op on SQLite;
+  - SQLite serialises all writers;
+  - `CHECK` and type semantics differ from MySQL.
+- The brief (§10, §11) requires tests for concurrent purchase, duplicate webhooks, simultaneous transitions and rollback behaviour.
+
+## Problem
+
+Which runtime versions and which database engine do code and tests run on?
+
+## Decision drivers
+
+- Tests must exercise the real locking, isolation and constraint semantics.
+- Reproducibility for reviewers: one command, no surprises.
+- CI time stays reasonable.
+
+## Considered alternatives
+
+### A. Keep SQLite for feature tests; add a separate MySQL suite for concurrency only
+
+- Faster local feedback.
+- But it keeps two behaviours. Constraint and `CHECK`, JSON, collation and locking differences leak into the "fast" suite and give false confidence, as happened in the old repository.
+
+### B. MySQL 8.4 LTS for every test that touches the database (chosen)
+
+- Unit tests stay database-free.
+- Feature, integration and concurrency tests use a dedicated `nexo_testing` schema.
+
+### C. PostgreSQL
+
+- Excellent constraints, and partial indexes would help several designs.
+- Rejected: the brief's baseline is MySQL, and the target host and demo hosting are MySQL-oriented.
+
+## Decision
+
+1. **PHP 8.5, Laravel 13.** Upgrade within minor versions freely. A major upgrade needs an ADR.
+2. **MySQL 8.4 LTS** is the only supported database.
+   - The engine is InnoDB.
+   - The default isolation level is `REPEATABLE READ`. Code that relies on locks uses explicit `SELECT … FOR UPDATE` or conditional `UPDATE … WHERE` statements, never read-then-write without a lock.
+   - The connection uses strict mode and `utf8mb4`/`utf8mb4_0900_ai_ci`.
+3. **Tests:**
+   - Unit tests use no database.
+   - Feature tests use MySQL `nexo_testing`, with transactions rolled back per test via `RefreshDatabase`.
+   - Concurrency tests run real parallel workers: separate PHP processes, each with its own connection, synchronised by a start barrier. They run against committed data with explicit cleanup, because a rollback-per-test transaction would hide concurrency.
+   - `phpunit.xml` guards against any database whose name does not end in `_testing`. A bootstrap check aborts the run otherwise.
+4. **CI** runs a MySQL 8.4 service container.
+5. **Redis** is used for queue, cache and locks in deployed environments (demo). Local development may use the `database` queue and cache drivers.
+6. **Local configuration caching is forbidden in development.**
+   - `bootstrap/cache/config.php` must not exist in a working copy.
+   - The test bootstrap refuses to run if it does.
+   - This prevents the Phase 0 incident where a cached config pointed tests at the MySQL database `nile`.
+
+## Positive consequences
+
+- Tests prove behaviour on the production engine.
+- Concurrency claims become evidence-based.
+
+## Negative consequences
+
+- Slower feature tests than in-memory SQLite. Mitigated by parallel testing (`--parallel` with per-process schemas) and by keeping logic in unit tests.
+- Contributors need MySQL locally. Laragon already provides MySQL 8.0, so 8.4 is recommended but 8.0 is tolerated locally; CI pins 8.4.
+
+## Risks
+
+- Tests could be accidentally pointed at a real database. This is mitigated by the `_testing` name guard and by refusing to run with a cached config.
+
+## Testing implications
+
+- `docs/engineering/testing.md` and `database.md` change from SQLite to MySQL in Phase 3. They are left untouched until this ADR is accepted.
+- The concurrency harness is built in Phase 3 and used in Phases 4–5.
+
+## Migration implications
+
+- `phpunit.xml`, the CI workflow and `.env.example` change in Phase 3.
+- No data migration is needed (fresh database).
+
+## Related
+
+- ADR-0014 (inventory), ADR-0015 (checkout), ADR-0021 (environments); Phase 0 §9, R4.
diff --git a/docs/architecture/adr/0010-modular-monolith-and-dependency-rules.md b/docs/architecture/adr/0010-modular-monolith-and-dependency-rules.md
new file mode 100644
index 0000000..f24830e
--- /dev/null
+++ b/docs/architecture/adr/0010-modular-monolith-and-dependency-rules.md
@@ -0,0 +1,116 @@
+# ADR-0010: Structure the application as a modular monolith with enforced module contracts
+
+- **Number:** 0010
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+The brief (§5, §9) prefers a modular monolith with explicit boundaries, controlled cross-domain communication and automated dependency checks.
+
+Phase 0 found that the old repository had 29 `app/Domain` folders with free cross-imports:
+
+- a domain-event store nobody consumed;
+- controllers that bypassed state machines.
+
+`docs/engineering/architecture-guidelines.md` already forbids generic services, repositories that merely wrap Eloquent, and interfaces without a second implementation or test seam.
+
+## Problem
+
+How is code organised into modules, what may a module depend on, and how is that enforced?
+
+## Decision drivers
+
+- Boundaries a reviewer can see in the directory tree and verify in CI.
+- Pragmatism: Eloquent stays the persistence model, with no purist repository layer.
+- Cross-module calls are explicit and few.
+
+## Considered alternatives
+
+### A. Laravel default layout (`app/Models`, `app/Http`, …)
+
+Rejected. There are no visible boundaries, and the old repository's failure mode would come back.
+
+### B. Purist hexagonal design per module (domain entities separate from Eloquent, repositories everywhere)
+
+Rejected. It doubles the model code and contradicts the existing guidelines. That cost is not justified at this scale.
+
+### C. Pragmatic modules with a public `Contracts` surface, enforced by Pest `arch()` (chosen)
+
+### D. As C, plus deptrac
+
+Deferred. Pest `arch()` (already installed) can express every rule below. Deptrac is added only if a rule cannot be expressed.
+
+## Decision
+
+1. **Layout.** One folder per module under `app/Modules/<Module>/`, with these sub-namespaces:
+
+   | Sub-namespace | Contents |
+   |---|---|
+   | `Domain/` | Eloquent models owned by the module, value objects, enums, state machines, domain exceptions and domain events. No HTTP, session, Inertia, Filament or provider SDK. |
+   | `Application/` | Use-case classes (`PlaceCheckout`, `ReserveStock`), one public `handle()` each, and the module's transaction boundaries. Query objects for reads. |
+   | `Infrastructure/` | Provider adapters (Stripe), queue jobs, listeners, outbox consumers, console commands. |
+   | `Http/` | Controllers, form requests, Inertia page props (DTOs) and route files. Vendor, storefront and API controllers live in separate sub-folders. |
+   | `Contracts/` | **The only namespace other modules may import:** interfaces (`InventoryReservations`), immutable DTOs, integration events and enums that cross the boundary. |
+   | `Filament/` | Admin resources for this module (ADR-0020). |
+
+2. **Shared kernel** `app/Shared/`. This is the only code every module may use:
+   - `Money`;
+   - `Clock`;
+   - public ID generation;
+   - `Outbox` writer;
+   - `Idempotency`;
+   - `Audit` recorder;
+   - the base exception types.
+
+   Nothing business-specific belongs here.
+
+3. **Module list and allowed dependencies** are defined in `docs/architecture/domain-context-map.md` and `dependency-rules.md`. Those documents are normative.
+
+4. **Cross-module communication:**
+   - **Synchronous:** call a `Contracts` interface, implemented inside the owning module and bound in its service provider. Used when the caller needs an answer inside its own use case (checkout asks Inventory to reserve).
+   - **Asynchronous:** integration events published through the transactional outbox (ADR-0017). Used for reactions (search re-index, notifications, ledger postings that follow a state change).
+
+5. **Data ownership.** Each table has exactly one owning module (`database-design.md`). Only the owner writes it.
+   - Other modules never query it with Eloquent relationships or joins.
+   - The single exception is read-only reporting queries in `Application/Queries` of the **Finance** and **Platform admin** read models. These are listed explicitly in `dependency-rules.md`.
+
+6. **Foreign keys across modules are allowed** for referential integrity, with `ON DELETE RESTRICT`. Eloquent relationships across modules are not.
+
+7. **Enforcement** in `tests/Arch/`:
+   - module A may not import `App\Modules\B\{Domain,Application,Infrastructure,Http}`;
+   - `Domain` may not import `Illuminate\Http`, `Inertia`, `Filament` or `Stripe`;
+   - controllers may not call `DB::` or Eloquent writes directly;
+   - no `env()` outside `config/` (existing rule).
+
+   Arch tests are a CI gate.
+
+## Positive consequences
+
+- Boundaries are visible, testable and reviewable.
+- Each module can be read in isolation.
+
+## Negative consequences
+
+- More files and DTO mapping at the boundaries.
+- Some reads need a contract method instead of a join.
+
+## Risks
+
+- Over-modularisation of small concerns. Mitigation: the module list is deliberately short (13 modules), and new modules need an ADR amendment.
+
+## Testing implications
+
+- Arch tests for every rule.
+- Each `Contracts` interface has a contract test, run against the real implementation and, where a fake exists, against the fake.
+
+## Migration implications
+
+None. The application is greenfield on `main`.
+
+## Related
+
+- `docs/architecture/domain-context-map.md`, `dependency-rules.md`, ADR-0017.
diff --git a/docs/architecture/adr/0011-identity-roles-and-vendor-isolation.md b/docs/architecture/adr/0011-identity-roles-and-vendor-isolation.md
new file mode 100644
index 0000000..e83f511
--- /dev/null
+++ b/docs/architecture/adr/0011-identity-roles-and-vendor-isolation.md
@@ -0,0 +1,112 @@
+# ADR-0011: Model identity as one user table with vendor memberships and platform staff roles; enforce vendor isolation by context, policy and test
+
+- **Number:** 0011
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+- **Refines:** ADR-0003, which is still accepted: no global scope; explicit vendor scoping
+- **Depends on:** ADR-0005 (Vendor naming; this ADR assumes it is accepted)
+
+---
+
+## Context
+
+**Phase 0 finding S1 (critical).** In the old application, any registered shopper could reach `/vendor/*`. There were two causes:
+
+- the vendor routes checked only `auth`;
+- the tenant global scope failed open when no tenant was resolved.
+
+ADR-0003 already chose explicit, context-dependent scoping over a global scope. `INVARIANTS.md` says:
+
+- a vendor-team user belongs to exactly one vendor;
+- an operator belongs to no vendor.
+
+The brief (§15) requires authorisation to be tested at the application boundary.
+
+## Problem
+
+How are users, vendor teams and platform staff modelled? How is "this request acts for vendor X" established and enforced so that it cannot fail open?
+
+## Decision drivers
+
+- Default deny.
+- A missing context must be an error, never "everything".
+- Simple, explicit and auditable.
+- No dependency unless it removes real work.
+
+## Considered alternatives
+
+### A. `spatie/laravel-permission` with database-stored roles and permissions
+
+- Flexible, and familiar to reviewers.
+- Rejected for v2: roles here are a fixed, small, code-reviewed set. Database-editable permissions add a privilege-escalation surface and test burden with no product need.
+
+### B. Separate guards and user tables for customers, vendors and staff
+
+Rejected. A vendor owner is also a person who may shop, and duplicate accounts confuse the model.
+
+### C. One `users` table; `vendor_members` for vendor roles; `users.platform_role` for staff; permissions as PHP enums mapped from roles; Laravel policies (chosen)
+
+## Decision
+
+1. **One `users` table**, holding authentication and profile data. Every user can be a customer.
+2. **Vendor membership** is `vendor_members(vendor_id, user_id UNIQUE, role, status)`.
+   - In v2 a user belongs to **at most one vendor** (unique `user_id`).
+   - Roles: `owner`, `manager`, `fulfilment`, `finance`, `support`.
+   - Exactly one `owner` per vendor. This is enforced in the application, plus a unique key on `(vendor_id, owner_marker)` where `owner_marker` is 1 or NULL.
+3. **Platform staff** are users with `platform_role ∈ {admin, operations, finance, support}`.
+   - A staff user **may not** hold a vendor membership, and staff accounts cannot place orders. Both are enforced in the application and asserted by tests.
+   - Staff accounts are created by an admin, never by registration. Two-factor authentication is mandatory for staff (Phase 3).
+4. **Permissions** are an enum `Permission` (for example `vendor.orders.fulfil` or `platform.refunds.override`).
+   - A static map in code assigns each role its permissions. The matrix is in `security-model.md`.
+   - Policies check two things: (a) ownership, `resource.vendor_id === VendorContext.vendorId`, and (b) the role permission.
+5. **VendorContext:**
+   - The middleware `vendor.context` on every `/vendor/*` route resolves the active membership of the authenticated user.
+   - It responds **403** if there is none, if the membership is not active, or if the vendor is not in an operating state for the action. Vendor state rules come from Vendors (`vendor-domain-design.md` §8).
+   - The resolved context is an immutable value object injected into controllers and use cases.
+   - There is **no** global Eloquent scope and **no** null-means-all fallback.
+   - A vendor-scoped query without a context is a programming error. It throws `MissingVendorContext`.
+6. **Vendor-owned queries:**
+   - They use explicit `->whereBelongsToVendor($context)` query scopes, or receive `vendorId` as a required argument to an Application query.
+   - Route-model binding for vendor routes is scoped. A vendor route binding `{order}` resolves only within the context's vendor; otherwise it returns 404, which avoids leaking existence.
+7. **Platform admin** is Filament, behind a separate `/admin` panel. Access requires `platform_role`, and every Filament resource and action is checked by a policy.
+8. **Impersonation:**
+   - Only `admin` may impersonate, and never another staff member.
+   - Each impersonation is audit-logged with start and stop.
+   - Money-moving actions are blocked while impersonating.
+9. **Isolation test suite** (`tests/Feature/Isolation/`). For every vendor-facing route and action, it asserts that:
+   - vendor A's member cannot read or mutate vendor B's records (404 or 403);
+   - a customer without membership gets 403;
+   - a suspended membership gets 403.
+
+   An arch test fails if a vendor controller is not covered by the dataset. The suite is a merge gate.
+
+## Positive consequences
+
+- Fails closed by construction.
+- Authorisation is reviewable in one matrix and one place per resource.
+
+## Negative consequences
+
+- Multi-vendor membership (one person running two stores) is not supported in v2. A later ADR would add a context switcher.
+- Role changes require a code change. That is intended.
+
+## Risks
+
+- A developer forgets the vendor scope in a new query. Mitigation: scoped route binding, required `vendorId` arguments, the isolation dataset arch check, and code review.
+
+## Testing implications
+
+- Isolation suite (merge gate).
+- Policy unit tests per role × permission.
+- Staff-cannot-order and staff-cannot-join-vendor tests.
+- Impersonation audit tests.
+
+## Migration implications
+
+- `users` (from `main`) gains `platform_role`.
+- New `vendor_members` table.
+
+## Related
+
+- ADR-0003, ADR-0005; `security-model.md`; Phase 0 S1.
diff --git a/docs/architecture/adr/0012-order-group-and-vendor-orders.md b/docs/architecture/adr/0012-order-group-and-vendor-orders.md
new file mode 100644
index 0000000..4c4f1f3
--- /dev/null
+++ b/docs/architecture/adr/0012-order-group-and-vendor-orders.md
@@ -0,0 +1,126 @@
+# ADR-0012: Represent a checkout as an OrderGroup of VendorOrders with explicit state machines
+
+- **Number:** 0012
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+- **Supersedes (on acceptance):** ADR-0004. Its structure is kept. Its Stripe Connect transfer rules and its "one PaymentIntent" invariant are replaced.
+
+---
+
+## Context
+
+ADR-0004 chose one parent (`OrderGroup`) with one `Order` per vendor. That structure satisfies the brief (§8). Two of its rules conflict with later decisions:
+
+- **Transfers:** a Stripe Connect `Transfer` per child on payment, and a transfer reversal per refund. D-6 replaces this with an internal ledger and simulated payouts (ADR-0016).
+- **PaymentIntent:** "exactly one PaymentIntent per OrderGroup". With checkout retries after a decline or provider outage, a group can have several *attempts* over time. What matters is *at most one active attempt* and *at most one successful capture*.
+
+Phase 0 (C4) also found the old state machine bypassed: `updateStatus` accepted any status.
+
+## Problem
+
+What is the order aggregate shape? Which statuses and transitions exist, and who may perform each?
+
+## Decision drivers
+
+- Vendor fulfilment and refunds are independent.
+- The customer sees one purchase.
+- Transitions are guarded, concurrency-safe and auditable.
+
+## Considered alternatives
+
+### A. A single Order with vendor-tagged lines
+
+Rejected for the reasons in ADR-0004.
+
+### B. Keep ADR-0004 verbatim
+
+Rejected because of the two conflicts above.
+
+### C. OrderGroup + VendorOrder, with the payment and ledger concerns moved out (chosen)
+
+## Decision
+
+1. **Names:**
+   - `OrderGroup` is the customer's purchase. It is called the "order" in customer UI, with reference `NX-YYMMDD-XXXXXX`.
+   - `VendorOrder` is one vendor's portion, with reference `<group ref>-<n>`, plus its `VendorOrderLine`s.
+   - `ADR-0004`'s `Order` becomes `VendorOrder`, to avoid ambiguity.
+2. **OrderGroup.status** (stored):
+
+   ```
+   pending_payment → paid
+   pending_payment → expired     (reservation TTL elapsed; system)
+   pending_payment → cancelled   (customer abandons before paying)
+   ```
+
+   Refund and fulfilment summaries are **derived** from the VendorOrders, never stored on the group.
+
+3. **VendorOrder.status** (stored):
+
+   ```
+   pending_payment ─► awaiting_fulfilment ─► processing ─► shipped ─► delivered ─► completed
+          │                   │                  │
+          ▼                   ▼                  ▼
+        voided           cancelled           cancelled
+   ```
+
+   | Transition | Who | Guard |
+   |---|---|---|
+   | `pending_payment → awaiting_fulfilment` | System (payment captured) | Group paid |
+   | `pending_payment → voided` | System (group expired or cancelled) | — |
+   | `awaiting_fulfilment → processing` | Vendor (`fulfilment`, `manager`, `owner`) | — |
+   | `processing → shipped` | Vendor | Carrier + tracking number required |
+   | `shipped → delivered` | Vendor, customer confirmation, or system after N days (no carrier integration) | — |
+   | `delivered → completed` | System | Return window (default 7 days) elapsed and no open return or dispute |
+   | `awaiting_fulfilment / processing → cancelled` | Vendor (`manager`, `owner`) with reason; customer (only from `awaiting_fulfilment`); platform `operations` | Triggers a full refund of that VendorOrder and release of stock |
+
+4. **Returns** are a separate `ReturnRequest` per VendorOrder:
+
+   ```
+   requested → approved → received → closed
+   requested → rejected
+   ```
+
+   - Platform `operations` may override a vendor rejection.
+   - Refunds are separate Payments objects (ADR-0015, ADR-0016). A VendorOrder's refund state (`none | partial | full`) is derived.
+
+5. **Every transition** is a use case that:
+   - executes `UPDATE vendor_orders SET status = :to, … WHERE id = :id AND status = :from`, and treats 0 affected rows as a conflict (HTTP 409, or a no-op for idempotent system retries);
+   - writes `vendor_order_status_history` (from, to, actor, reason, timestamp);
+   - writes an outbox event in the same transaction.
+
+   Controllers never set `status` directly. An arch test forbids status assignment outside the state-machine class.
+
+6. **Snapshots.** Lines snapshot product name, variant options, SKU, unit price, quantity, and the allocated discount and points. The VendorOrder snapshots the commission rate in basis points, the shipping amount and the shipping address. Later catalogue or price changes never alter an order.
+
+7. **Vendors see** only their VendorOrder, its lines, the shipping address and the customer's display name and contact needed for fulfilment. They never see the group total or sibling orders.
+
+## Positive consequences
+
+- Refund and fulfilment isolation between vendors is structural.
+- Transitions are race-safe and auditable.
+
+## Negative consequences
+
+- Derived group status needs a query or projection for customer order lists.
+- Two references per purchase.
+
+## Risks
+
+- `delivered` without carrier integration is a trust assumption. Mitigation: auto-deliver N days after shipping (configurable). Customers can open a "not received" return.
+
+## Testing implications
+
+- State-machine unit tests over every from/to pair: allowed and rejected.
+- Concurrency test: two simultaneous transitions; exactly one succeeds.
+- Snapshot-immutability tests.
+- Vendor visibility tests (no sibling data).
+
+## Migration implications
+
+- ADR-0004 → Superseded by ADR-0012.
+- `INVARIANTS.md` "Payment Ownership" is reworded.
+
+## Related
+
+- ADR-0004, ADR-0015, ADR-0016; `lifecycles/orders-fulfilment-and-returns.md`.
diff --git a/docs/architecture/adr/0013-money-representation-and-allocation.md b/docs/architecture/adr/0013-money-representation-and-allocation.md
new file mode 100644
index 0000000..d8ac6ce
--- /dev/null
+++ b/docs/architecture/adr/0013-money-representation-and-allocation.md
@@ -0,0 +1,102 @@
+# ADR-0013: Represent money as integer minor units with an explicit currency and deterministic allocation
+
+- **Number:** 0013
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+`docs/engineering/database.md` already says:
+
+- money is integer minor units plus currency;
+- never floats;
+- decimals only for rates.
+
+ADR-0007 fixes one currency (MYR). Several calculations split one amount across many parts:
+
+- discounts across lines and vendors;
+- loyalty points across lines;
+- commission per line;
+- dispute amounts across VendorOrders.
+
+Each split must sum *exactly*, or the ledger cannot balance.
+
+## Problem
+
+What is the money type, how are rates represented, and how are rounding and allocation done?
+
+## Decision drivers
+
+- Exactness: the ledger always balances.
+- Determinism: the same input always gives the same allocation.
+- No floating point anywhere in money paths, including JavaScript.
+
+## Considered alternatives
+
+### A. `brick/money`
+
+- Mature, with allocation support.
+- Adds a dependency, and its `BigDecimal` contexts are more than a single-currency integer domain needs.
+- A reasonable fallback if the first-party type proves insufficient.
+
+### B. `moneyphp/money`
+
+Similar trade-off to A.
+
+### C. A small first-party immutable `Money` value object in `app/Shared/Money` (chosen)
+
+About 150 lines with exhaustive unit tests.
+
+## Decision
+
+1. **`Money`** is `(int $minor, Currency $currency)`, immutable.
+   - Operations: `add`, `subtract`, `multiplyByInt`, `isNegative`, `equals`, `allocate(array $weights)`, `percentage(BasisPoints)`.
+   - Operations on mismatched currencies throw.
+   - Overflow is checked; `PHP_INT_MAX` sen is far beyond any order.
+2. **Rates** are integer **basis points** (`commission_rate_bps = 1000` means 10.00 %). No decimal columns are needed.
+3. **Rounding:** `percentage()` uses **half-even** (banker's) rounding on the minor unit.
+4. **Allocation** uses the **largest-remainder method**:
+   - Compute floor shares proportional to the weights.
+   - Distribute the leftover minor units one by one to the largest fractional remainders.
+   - Ties go to the lowest line position.
+
+   The result always sums to the input. Allocations are stored on the rows they apply to (line `discount_allocated_minor`, `points_value_allocated_minor`), so reversals use stored values and never recompute.
+5. **Commission** is computed per line: `line_commission = percentage(line_goods_minor, rate_bps)`. The VendorOrder commission is the sum of its lines, so a partial refund of one line reverses exactly that line's commission.
+6. **Columns:**
+   - `*_minor BIGINT` (signed only where a negative value is meaningful, e.g. ledger entries are always positive with a direction column);
+   - plus `currency CHAR(3)` on every table holding money.
+7. **Serialisation to the frontend** is `{ amount: <int minor>, currency: "MYR" }`. Formatting happens client-side with `Intl.NumberFormat` (ADR-0018). The browser never does arithmetic that is persisted or trusted. Display totals come from the server.
+
+## Positive consequences
+
+- Exact sums everywhere.
+- Reversals are trivially exact.
+- One small, fully tested type.
+
+## Negative consequences
+
+- Owning a money type. Mitigated by its narrow scope and property tests.
+
+## Risks
+
+- Developers bypass `Money` with raw ints. Mitigation: arch test that `*_minor` attributes are cast to `Money` via an Eloquent cast, plus PHPStan.
+
+## Testing implications
+
+Property-based tests (random amounts and weights):
+
+- the allocation sum is preserved;
+- no share is negative;
+- results are deterministic;
+- `percentage` matches a reference implementation.
+
+## Migration implications
+
+None (greenfield).
+
+## Related
+
+- ADR-0016, `financial-model.md`.
diff --git a/docs/architecture/adr/0014-inventory-reservations.md b/docs/architecture/adr/0014-inventory-reservations.md
new file mode 100644
index 0000000..a6cec2b
--- /dev/null
+++ b/docs/architecture/adr/0014-inventory-reservations.md
@@ -0,0 +1,130 @@
+# ADR-0014: Track inventory as on-hand and reserved quantities per variant, with TTL reservations and an idempotent movement journal
+
+- **Number:** 0014
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+Phase 0 finding C3 (critical). The old inventory code:
+
+- double-subtracted stock on reservation (`quantity` decremented **and** `reserved` incremented, while availability was computed as `quantity − reserved`);
+- ignored the variant on release;
+- never expired reservations.
+
+Its "concurrency" tests ran on SQLite and passed anyway.
+
+The brief requires correct behaviour (§10, §11) for:
+
+- the last unit;
+- concurrent reservation;
+- reservation expiry;
+- payment failing after reservation;
+- reservation release failing;
+- conflicting adjustments;
+- vendor cancellation;
+- duplicated stock movements.
+
+## Problem
+
+What is the inventory data model, and which concurrency mechanism makes overselling impossible?
+
+## Decision drivers
+
+- No overselling under concurrency, provable on MySQL.
+- Every quantity change is explained by a journal entry.
+- Recovery from crashes without manual repair.
+
+## Considered alternatives
+
+### A. Decrement stock at add-to-cart
+
+Rejected. Abandoned carts lock up inventory.
+
+### B. Decrement stock only when payment succeeds (no reservation)
+
+Rejected. Two customers can both pay for the last unit, and one must then be refunded. That is poor UX and makes the "last unit" scenario a refund scenario.
+
+### C. Pessimistic `SELECT … FOR UPDATE` on `stock_levels`, then write
+
+Correct, but every check needs a lock round-trip. Deadlock risk if locks are taken in inconsistent order.
+
+### D. Atomic conditional `UPDATE … WHERE available >= qty`, with rows touched in ascending `variant_id` order (chosen)
+
+One statement per line, correct under concurrency in InnoDB, with deadlocks minimised by ordering. Used inside the checkout transaction.
+
+### E. Optimistic version column for all writes
+
+Kept only for *absolute* vendor stock sets (D handles deltas better).
+
+## Decision
+
+1. **`stock_levels`** has columns `variant_id` (PK), `vendor_id`, `on_hand INT UNSIGNED`, `reserved INT UNSIGNED`, `version INT UNSIGNED`.
+   - DB `CHECK (reserved <= on_hand)` is enforced on MySQL 8.0.16+.
+   - `available = on_hand − reserved` is never stored.
+2. **Reserve** (inside the checkout transaction, lines sorted by `variant_id`):
+
+   ```sql
+   UPDATE stock_levels SET reserved = reserved + :qty, version = version + 1
+    WHERE variant_id = :v AND on_hand - reserved >= :qty
+   ```
+
+   - 0 rows means insufficient stock. The whole checkout transaction rolls back and the customer sees which lines are short.
+   - A `stock_reservations` row is created with `(order_group_id, variant_id, qty, status = active, expires_at = now + TTL)`.
+   - **TTL default: 15 minutes.**
+3. **Consume** (payment captured): a reservation goes `active → consumed`, guarded by `WHERE status = 'active'`. In the same statement set, `on_hand -= qty` and `reserved -= qty`.
+4. **Release** (payment failed terminally, group expired or cancelled, or a cancellation before shipping): a reservation goes `active → released | expired`, and `reserved -= qty`.
+5. **Stock that is already consumed** (cancellation after payment, before shipping) is returned with `on_hand += qty` and a `cancellation_restock` movement.
+6. **Returns:** `on_hand += qty` only when the vendor marks a returned item `received` *and* `resellable`.
+7. **Every quantity change** writes a `stock_movements` row: `(variant_id, type, delta_on_hand, delta_reserved, reference_type, reference_id, actor)`.
+   - Unique key `(type, reference_type, reference_id, variant_id)`.
+   - A duplicated release or consume attempt hits the unique key and is a no-op. This covers the "stock movement is duplicated" scenario.
+   - The guarded reservation status update is the primary protection; the unique key is defence in depth.
+8. **Vendor adjustments:**
+   - *Delta* ("received 20 units"): `on_hand = on_hand + :d WHERE on_hand + :d >= reserved`.
+   - *Absolute set* (stock count): compare-and-swap on `version`. On mismatch, return 409 "stock changed since you loaded it", showing the current value.
+   - Setting on-hand below `reserved` is rejected, with a message naming the reserved quantity.
+9. **Sweeper.** It is owned by **Ordering** as `ExpireUnpaidGroups`, scheduled every minute, because Inventory must not depend on Payments (`dependency-rules.md`). It handles OrderGroups in `pending_payment` whose reservations are past `expires_at`. For each group it first asks Payments for the attempt state (ADR-0015):
+   - if the payment is `processing` or `requires_action`, it extends the reservation once, by up to 15 minutes;
+   - otherwise it expires the group, releasing the reservations and cancelling the provider intent.
+
+   The sweeper is idempotent and safe to run concurrently (`FOR UPDATE SKIP LOCKED` on candidate groups).
+10. **Reconciliation invariant** (nightly and in tests): for each variant, `reserved = Σ active reservations.qty`, and `on_hand = Σ movements.delta_on_hand`. A mismatch raises an operational alert, not a silent fix.
+
+## Positive consequences
+
+- Overselling is impossible by construction, and this is provable with parallel-process tests.
+- Full audit trail.
+- Crash-safe through guarded updates and the sweeper.
+
+## Negative consequences
+
+- Reserved stock is unavailable for up to the TTL, plus at most one extension.
+- The sweeper is an operational dependency (the scheduler must run).
+
+## Risks
+
+- **Late payment after expiry.** The customer paid but the reservation expired and the stock was sold elsewhere. Handled in ADR-0015: re-reserve, or automatically refund the affected VendorOrder.
+- **Scheduler outage.** Reservations persist longer, so nothing is oversold, and a health check alerts.
+
+## Testing implications
+
+On MySQL with parallel processes (ADR-0009):
+
+- N buyers for 1 unit → exactly 1 succeeds;
+- concurrent reservations across overlapping variants complete without deadlock failures (or retry on deadlock);
+- duplicate consume/release is a no-op;
+- an absolute set races a reservation;
+- the sweeper races a webhook;
+- the reconciliation invariant holds after random operation sequences.
+
+## Migration implications
+
+None (greenfield).
+
+## Related
+
+- ADR-0015; `lifecycles/inventory.md`; Phase 0 C3.
diff --git a/docs/architecture/adr/0015-checkout-and-payment-orchestration.md b/docs/architecture/adr/0015-checkout-and-payment-orchestration.md
new file mode 100644
index 0000000..5095e6e
--- /dev/null
+++ b/docs/architecture/adr/0015-checkout-and-payment-orchestration.md
@@ -0,0 +1,159 @@
+# ADR-0015: Orchestrate checkout as a short saga with provider calls outside database transactions, idempotency keys at every boundary, and webhook-driven payment state
+
+- **Number:** 0015
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+Phase 0 findings:
+
+- **C1 (critical):** successful payments never marked orders paid. The webhook handler re-confirmed an already-succeeded intent, and the `PaymentSucceeded` event was never dispatched.
+- **C6 (high):** the Stripe call ran inside the database transaction.
+- **C5 (high):** refunds raced and had no provider idempotency keys.
+- A guest could check out another session's cart.
+
+The brief's payment scenarios (§11) are:
+
+- success, decline and pending;
+- late, duplicated and forged webhooks;
+- browser closed;
+- checkout retry;
+- partial refund success;
+- provider outage;
+- crash mid-processing.
+
+## Problem
+
+What are the transaction boundaries, sources of truth and idempotency mechanisms for checkout, payment and refund?
+
+## Decision drivers
+
+- Never hold database locks across a network call.
+- The provider's signed event is the source of truth for money movement. The browser never is.
+- Every retry, by user, queue or webhook, is safe.
+
+## Considered alternatives
+
+### A. A single transaction including the provider call (old design)
+
+Rejected. It holds locks during network I/O, and a rollback can leave an orphaned provider intent.
+
+### B. Redirect-based confirmation (trust the return URL)
+
+Rejected. A closed browser loses the order, and the return URL is client-controlled.
+
+### C. Saga: local transaction → provider call after commit → webhook-driven completion, with sweepers (chosen)
+
+## Decision
+
+1. **Checkout requires an authenticated customer.** Guest checkout is out of scope for v2 (PRD §6); the cart is merged on login. This removes the guest-cart ownership class of bug.
+
+2. **Step 1, place.** `POST /checkout` carries an `Idempotency-Key`: a UUID generated when the checkout page renders, unique per customer.
+   1. Re-price the cart server-side: current prices, promotions, points, shipping quotes. If the total differs from the total the customer confirmed, return **409** with the new summary. Never charge an amount the customer did not see.
+   2. In **one DB transaction**, create the following, then commit:
+      - `OrderGroup(pending_payment)`, its `VendorOrder`s and lines (snapshots);
+      - the reservations (ADR-0014);
+      - the promotion redemption and points hold, both in `pending` state;
+      - an outbox `CheckoutPlaced` event.
+   3. `UNIQUE(customer_id, idempotency_key)` on `order_groups`. A duplicate submission returns the existing group, including its existing payment attempt.
+
+3. **Step 2, attempt.** After commit, Payments creates a `PaymentAttempt(created)`, then calls the provider with these parameters:
+   - amount equal to the group total;
+   - currency MYR;
+   - metadata `{order_group_id, attempt_id}`;
+   - **provider idempotency key `attempt:{id}`**.
+
+   It stores `provider_payment_id` (UNIQUE), sets `requires_payment_method`, and returns the client secret.
+
+   Rules for attempts:
+   - **At most one active attempt per group.** This is enforced with `order_groups.active_attempt_id` updated under a row lock. Creating a new attempt first cancels the previous provider intent.
+   - **Provider unavailable** (timeout or 5xx): the attempt becomes `creation_failed`. The group stays `pending_payment` with its reservations, and the customer sees "Payment service unavailable, try again". Retry creates a new attempt. The provider idempotency key prevents duplicates where the first call actually succeeded.
+
+4. **Step 3, confirm.** The browser confirms with Stripe.js (3-D Secure as needed). The UI shows "Confirming your payment…" and polls the group status. **The browser result is never trusted to mark anything paid.**
+
+5. **Step 4, webhook ingestion.** `POST /webhooks/stripe`:
+   1. Verify the signature. If invalid: **400**, nothing persisted, a security-log entry and a metric.
+   2. `INSERT provider_events(provider, event_id UNIQUE, type, payload, received_at)`. On a duplicate key, return **200** and do nothing.
+   3. Dispatch `ProcessProviderEvent` after commit. Return **200** quickly.
+
+6. **Step 5, processing** (queued job, idempotent):
+   1. Lock the attempt and the group (`FOR UPDATE`, always group first, then attempt).
+   2. **Re-fetch the provider object** for authoritative current state. This handles out-of-order events.
+   3. Check that amount and currency match the attempt. A mismatch becomes a `reconciliation_exception`, not paid.
+   4. On `succeeded`:
+      - attempt → `succeeded`;
+      - group → `paid`;
+      - VendorOrders → `awaiting_fulfilment`;
+      - reservations consumed;
+      - redemption and points confirmed;
+      - ledger *capture* transaction posted (ADR-0016);
+      - outbox `OrderGroupPaid` and per-vendor `VendorOrderPaid`;
+      - all in **one transaction**.
+   5. Already succeeded → no-op.
+   6. On `payment_failed`: attempt → `failed` with the decline code. The group stays `pending_payment` until TTL so the customer can retry with another card.
+   7. On `processing` or `requires_action`: record it. The sweeper honours it (ADR-0014).
+   8. Mark the event `processed_at`. On exception, the job retries with backoff. A scheduled job re-dispatches events received but unprocessed for more than 5 minutes. This covers a crash mid-processing.
+
+7. **Late success.** If a success arrives for an `expired` or `cancelled` group (the cancel lost a race):
+   - Try to re-reserve every line.
+   - On success, proceed as paid.
+   - On partial failure, mark the group paid and immediately cancel the affected VendorOrders with reason `stock_unavailable_after_payment`. This triggers full refunds for those VendorOrders and notifies the customer.
+   - Never silently keep money for goods that cannot ship.
+
+8. **Expiry.** The sweeper (ADR-0014) cancels the provider intent before expiring a group. If the cancel fails because the intent already succeeded, the sweeper processes success instead.
+
+9. **Refunds** (also ADR-0016):
+   - `Refund` rows are per VendorOrder, with lines and amounts.
+   - **Eligibility is owned by Ordering**, because Payments must not lock Ordering's tables. `vendor_orders` carries `refundable_cap_minor` (captured allocation, set at payment) and `refund_committed_minor`. A refund is committed by a guarded update:
+
+     ```sql
+     UPDATE vendor_orders SET refund_committed_minor = refund_committed_minor + :amt
+      WHERE id = :id AND refund_committed_minor + :amt <= refundable_cap_minor
+     ```
+
+     Per-line counters (`vendor_order_lines.refund_committed_qty`) are guarded the same way, inside the same transaction.
+   - In that transaction, Ordering calls `Payments\Contracts\Refunds::request(...)`, which creates the `Refund` row.
+   - On a terminal `RefundFailed` event, Ordering decrements the committed amount, so the refund can be retried or re-requested.
+   - The provider call happens after commit with idempotency key `refund:{id}`.
+   - **Timeout leaves the refund `submitted`, never `failed`.** Resolution comes from `charge.refunded`/`refund.updated` webhooks or reconciliation. "Partially succeeds" becomes per-refund status, visible per VendorOrder. Failed refunds go to an operations queue.
+   - Refunds are blocked while a dispute is open on the charge.
+
+10. **Application idempotency store** `idempotency_keys(scope, key, request_hash, response, created_at)`, used for `POST /checkout`, refund requests and payout runs:
+    - reusing a key with a **different** request hash returns **422** "idempotency key reused with different parameters";
+    - the same request replays the stored response;
+    - keys expire after 24 hours.
+
+11. **Provider port.** `PaymentProvider` (in `Payments/Contracts`) has a Stripe adapter and a **deterministic fake** used in tests. The fake can be scripted to decline, time out, deliver duplicates, deliver out of order or deliver late.
+
+## Positive consequences
+
+- No locks across I/O.
+- The provider's signed event drives money state.
+- Every scenario in brief §11 has a defined outcome (`lifecycles/checkout-and-payment.md`).
+
+## Negative consequences
+
+- More moving parts: attempts, events, sweepers, idempotency store.
+- The customer sees a short "confirming" state.
+
+## Risks
+
+- **Webhook endpoint misconfigured in the demo environment.** Mitigation: the reconciliation sweep re-fetches attempts stuck in `requires_payment_method` or `processing` past 30 minutes, and a health check shows the last webhook received.
+
+## Testing implications
+
+- With the fake provider, every §11 scenario is a named test.
+- A Stripe test-mode smoke suite runs manually or nightly (not on every PR) using the Stripe CLI to forward webhooks.
+- MySQL concurrency tests: duplicate checkout submit; duplicate webhook delivered concurrently; sweeper racing a webhook; two refunds on one VendorOrder.
+
+## Migration implications
+
+None (greenfield). The old code is not ported.
+
+## Related
+
+- ADR-0012, ADR-0014, ADR-0016, ADR-0017; `lifecycles/checkout-and-payment.md`; Phase 0 C1, C5, C6.
diff --git a/docs/architecture/adr/0016-financial-ledger-and-simulated-payouts.md b/docs/architecture/adr/0016-financial-ledger-and-simulated-payouts.md
new file mode 100644
index 0000000..a8fc49e
--- /dev/null
+++ b/docs/architecture/adr/0016-financial-ledger-and-simulated-payouts.md
@@ -0,0 +1,141 @@
+# ADR-0016: Account for money with an internal double-entry ledger; simulate vendor payouts
+
+- **Number:** 0016
+- **Status:** Proposed. The core direction (ledger + simulated payouts, no Stripe Connect in v2) was approved by the owner as D-6 on 2026-11-01. Rules 6–8 (D-9, D-10, D-11) await approval.
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+The brief (§8) requires the design to distinguish:
+
+- customer collection;
+- commission;
+- vendor payables;
+- transfers;
+- refund liabilities;
+- disputes;
+- reconciliation.
+
+It also forbids real payouts until the model is defined.
+
+The old documents assumed Stripe Connect transfers with Stripe as the only financial record. The owner chose an internal ledger with simulated payouts (D-6). The full model, with worked examples, is in `docs/architecture/financial-model.md`. This ADR records the binding rules.
+
+## Problem
+
+Where is the financial truth recorded, and what are the rules for commission, payables, refunds, chargebacks and payouts?
+
+## Decision drivers
+
+- Every money movement is explainable and balances.
+- Reconcilable against the provider.
+- No real vendor transfers.
+
+## Considered alternatives
+
+### A. Stripe Connect as the financial record (old documents)
+
+- Rejected (D-6).
+- Needs Connect onboarding.
+- Reconciliation and vendor statements depend on provider reports.
+
+### B. Mutable balance columns on vendors
+
+- Rejected.
+- Not auditable.
+- Races on concurrent updates.
+- No explanation of a balance.
+
+### C. Append-only double-entry ledger; balances derived (chosen)
+
+## Decision
+
+1. **Finance** module owns three tables:
+   - `ledger_accounts`;
+   - `ledger_transactions`, with columns `(id, type, reference_type, reference_id, occurred_at)` and **UNIQUE `(type, reference_type, reference_id)`**, so each business event posts at most once;
+   - `ledger_entries`, with columns `(transaction_id, account_id, direction debit|credit, amount_minor > 0, currency)`.
+2. **Every transaction balances** (Σ debits = Σ credits). This is checked in the posting service, and also by a nightly job. Entries are never updated or deleted. Corrections are new reversing transactions.
+3. **Chart of accounts:**
+
+   | Account | Kind |
+   |---|---|
+   | `platform:psp_clearing` | asset |
+   | `platform:commission_revenue` | revenue |
+   | `platform:psp_fees` | expense |
+   | `platform:promo_expense` | expense |
+   | `platform:loyalty_expense` | expense |
+   | `platform:dispute_holding` | asset |
+   | `platform:dispute_losses` | expense |
+   | `vendor:{id}:payable_pending` | liability |
+   | `vendor:{id}:payable_available` | liability |
+   | `vendor:{id}:payable_held` | liability |
+   | `vendor:{id}:receivable` | asset |
+
+4. **Postings are triggered** by Payments and Ordering events through the outbox (ADR-0017), consumed idempotently. Each posting type is defined in `financial-model.md`:
+   - capture;
+   - fee;
+   - refund;
+   - maturity;
+   - payout;
+   - dispute opened, won and lost;
+   - receivable netting.
+5. **Commission:**
+   - Rate resolution order: vendor override → top-level category rate → platform default (10 %).
+   - The rate is frozen on the VendorOrder in basis points.
+   - Computed per line on the goods amount *before* platform-funded discounts (ADR-0013).
+6. **Fees (D-9, proposed):** the platform bears payment-processing fees. They are posted from the provider balance transaction to `psp_fees`. Vendors are not charged fees.
+7. **Commission on refunds and shipping (D-10, proposed):**
+   - A refund reverses the commission of the refunded lines exactly, using the stored per-line commission.
+   - **Shipping is excluded** from commission. Shipping charged to the customer is credited 100 % to the vendor, who ships.
+8. **Disputes (D-11, proposed):**
+   - The disputed amount is allocated to VendorOrders and moved to `payable_held`.
+   - If the dispute is lost, the vendor bears the goods amount (debit held; any shortfall becomes `receivable`).
+   - The platform bears the dispute fee.
+   - No refunds or payouts are allowed against held amounts.
+9. **Promotions and loyalty** are platform-funded in v2:
+   - vendor payable is calculated on pre-discount goods;
+   - the discount is posted to `promo_expense` or `loyalty_expense`.
+10. **Maturity:** when a VendorOrder becomes `completed` (return window elapsed), its pending payable moves to available. This is idempotent per VendorOrder.
+11. **Simulated payouts:**
+    - A weekly payout run is a scheduled job, also triggerable by Finance staff with an idempotency key.
+    - For every vendor with available balance ≥ the minimum (RM 50.00, configurable), with any receivable netted first, it creates a `Payout(status=simulated_paid)` and posts Dr `payable_available` / Cr `psp_clearing`.
+    - Nothing leaves the platform. The UI labels payouts "Simulated (demo)".
+12. **Balances are derived** from entries. A cached projection (`ledger_account_balances`) may be added for speed only if it is verified nightly against entries.
+13. **Reconciliation**, in three levels:
+    - internal invariants;
+    - provider reconciliation, which matches balance transactions daily;
+    - operational sweeps.
+
+    Exceptions go to `reconciliation_exceptions`, which Finance staff resolve in Filament. Every resolution is audit-logged.
+
+## Positive consequences
+
+- Every figure on vendor and finance screens is explainable line by line.
+- The full model is testable without Stripe Connect.
+
+## Negative consequences
+
+- Owning accounting logic.
+- Simulated payouts are visibly not real. That is acceptable and honestly labelled.
+
+## Risks
+
+- Posting rules wrong in edge cases (refund after payout, dispute after refund). Mitigation: property tests and the worked examples in `financial-model.md` as executable tests.
+
+## Testing implications
+
+- Property tests: random baskets, discounts, partial refunds and disputes; the ledger always balances; Σ refunds ≤ captured per VendorOrder.
+- Concurrency tests: refund vs maturity; payout run executed twice concurrently; duplicate posting events.
+- Each worked example in `financial-model.md` is an executable test.
+
+## Migration implications
+
+- Connect onboarding fields are removed from the vendor design.
+- `INVARIANTS.md` gains the ledger invariants.
+- ADR-0004's transfer rules are superseded via ADR-0012.
+
+## Related
+
+- `financial-model.md`, ADR-0013, ADR-0015, ADR-0017; Phase 0 §A.7.
diff --git a/docs/architecture/adr/0017-domain-events-and-transactional-outbox.md b/docs/architecture/adr/0017-domain-events-and-transactional-outbox.md
new file mode 100644
index 0000000..07d602e
--- /dev/null
+++ b/docs/architecture/adr/0017-domain-events-and-transactional-outbox.md
@@ -0,0 +1,93 @@
+# ADR-0017: Publish integration events through a transactional outbox with idempotent consumers
+
+- **Number:** 0017
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+Phase 0 finding C2: the old `DomainEventRecorder` wrote a `domain_events` table that nothing ever read. Meanwhile, plain Laravel events were dispatched before transactions committed in places. Either way, reactions could be lost or could happen for rolled-back work.
+
+Nexo needs reliable reactions to state changes:
+
+- ledger postings;
+- notifications;
+- search indexing;
+- loyalty awards;
+- payable maturity.
+
+## Problem
+
+How do modules react to each other's state changes reliably, without distributed transactions?
+
+## Decision drivers
+
+- An event is published **if and only if** the state change commits.
+- At-least-once delivery, with consumers safe under duplicates.
+- Observable: backlog, failures and dead letters are visible.
+
+## Considered alternatives
+
+### A. Laravel events with `ShouldDispatchAfterCommit` / `afterCommit` queued listeners
+
+- Simple.
+- Rejected as the *only* mechanism: if the process crashes between commit and dispatch, the reaction is lost, and there is no durable backlog to inspect or replay.
+
+### B. External broker (Kafka/RabbitMQ)
+
+Rejected. Unjustified operational weight for a modular monolith.
+
+### C. Outbox table written in the same transaction, relayed to the queue; consumer inbox for de-duplication (chosen)
+
+## Decision
+
+1. **Outbox table:** `outbox_messages(id ULID, type, aggregate_type, aggregate_id, payload JSON, occurred_at, dispatched_at NULL, attempts, last_error)`.
+   - It is written by `Shared\Outbox::record()` **inside** the use case's transaction.
+   - Payloads are versioned DTOs from the publishing module's `Contracts/Events`.
+2. **Relay:** a scheduled command (every 5 seconds, `withoutOverlapping`) selects undispatched rows `FOR UPDATE SKIP LOCKED` in batches.
+   - It pushes one queue job per subscriber and sets `dispatched_at`.
+   - Failures increment `attempts` with backoff.
+   - After 10 attempts the row is marked dead and an operations alert is raised.
+3. **Subscribers** are registered explicitly per event type in each consuming module's service provider. There is no auto-discovery.
+4. **Inbox:** `processed_messages(consumer, message_id, processed_at)`, with a UNIQUE pair.
+   - The consumer inserts its inbox row in the same transaction as its own effects.
+   - A duplicate becomes a no-op.
+   - Consumers that are naturally idempotent, such as ledger postings with unique `(type, reference)`, still use the inbox for uniformity.
+5. **Ordering:** no global ordering guarantee. Consumers must tolerate reordering, by checking the state they act on, or by re-reading through the owner's contract.
+6. **Intra-module** reactions that must be atomic stay inside the use case (same transaction). The outbox is for cross-module, eventually consistent reactions.
+7. **Observability:** Filament shows outbox backlog, dead letters (with retry action) and consumer failures. The health endpoint reports the age of the oldest undispatched message.
+8. **Retention:** dispatched rows are pruned after 14 days. Inbox rows are pruned after 30 days.
+
+## Positive consequences
+
+- No lost or phantom reactions.
+- Replayable.
+- Testable with a synchronous relay in tests.
+
+## Negative consequences
+
+- Up to about 5 seconds of extra latency on reactions.
+- Two more tables and a scheduler dependency.
+
+## Risks
+
+- Scheduler not running in an environment. Mitigation: health check and alert on outbox age.
+
+## Testing implications
+
+- Rollback test: a rolled-back transaction publishes nothing.
+- Crash simulation: a message is not dispatched until the relay runs.
+- Duplicate delivery to every consumer is a no-op.
+- The `SKIP LOCKED` relay runs in parallel without double dispatch (MySQL test).
+
+## Migration implications
+
+- `jobs`/`failed_jobs` from `main` stay (queue).
+- New outbox and inbox tables.
+
+## Related
+
+- ADR-0010, ADR-0015, ADR-0016; Phase 0 C2.
diff --git a/docs/architecture/adr/0018-backend-frontend-contracts.md b/docs/architecture/adr/0018-backend-frontend-contracts.md
new file mode 100644
index 0000000..666886d
--- /dev/null
+++ b/docs/architecture/adr/0018-backend-frontend-contracts.md
@@ -0,0 +1,105 @@
+# ADR-0018: Define Inertia page contracts as PHP data objects and generate TypeScript types from them
+
+- **Number:** 0018
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+Phase 0 found 22 `vue-tsc` errors in the old repository, and that its prop types were hand-written and had drifted from the controllers.
+
+The brief (§12) asks for explicit contracts covering:
+
+- requests;
+- responses;
+- TypeScript types and shared props;
+- pagination;
+- errors;
+- money, date and enum serialisation.
+
+It also asks for no duplicated business rules between PHP and TypeScript.
+
+## Problem
+
+How are the shapes exchanged between Laravel and Vue defined once and kept in sync?
+
+## Decision drivers
+
+- One source of truth for every prop shape.
+- Drift fails CI.
+- No business logic in the browser.
+
+## Considered alternatives
+
+### A. Hand-written TypeScript interfaces
+
+Rejected. They drift, as in the old repository.
+
+### B. A REST API with OpenAPI and a generated client
+
+Rejected for v2 surfaces. Inertia is the transport, and a public API is out of scope (PRD §6).
+
+### C. `spatie/laravel-data` DTOs as page props, plus `spatie/laravel-typescript-transformer` to generate `.d.ts` (chosen)
+
+- These are two new dependencies, justified because they remove a whole class of drift.
+- Exact versions are verified for Laravel 13 compatibility in Phase 3. If they are incompatible, the fallback is a small first-party transformer over PHP attributes.
+
+## Decision
+
+1. **Every Inertia page** receives props built from `*PageData` / `*Data` classes in the module's `Http/` namespace. Arrays built ad hoc in controllers are forbidden by an arch test.
+2. **Generated types** are written to `resources/js/types/generated.d.ts` by `php artisan typescript:transform`.
+   - The file is committed.
+   - CI regenerates it and fails on any diff.
+3. **Serialisation rules:**
+   - **Money:** `{ amount: number /* integer minor units */, currency: 'MYR' }`. The frontend formats it with `Intl.NumberFormat(locale, { style: 'currency', currency })`. For Arabic it uses the `-u-nu-latn` extension, so prices use Latin digits; this is a design-system decision to confirm in Phase 2.
+   - **Dates:** ISO 8601 strings in UTC with an offset. They are displayed in `Asia/Kuala_Lumpur` by default.
+   - **Enums:** PHP backed enums become TypeScript string-literal unions. Labels come from translation keys `enums.<Enum>.<case>`, never hard-coded in Vue.
+   - **IDs:** public ULIDs or references only. Internal auto-increment IDs are never exposed.
+   - **Nullable** stays `T | null`, never optional-undefined, so every key is always present.
+4. **Pagination:**
+   - The generic `Paginated<T>` is `{ data: T[], meta: { currentPage, perPage, total, lastPage }, links: { prev: string|null, next: string|null } }`.
+   - Cursor pagination is used for large vendor and admin lists, as `CursorPaginated<T>`.
+5. **Shared props** (`HandleInertiaRequests`), each typed by a `SharedData` class:
+   - `auth.user`;
+   - `auth.vendor`, present only in vendor context;
+   - `locale` and `direction`;
+   - `flash`;
+   - `cart.count`.
+6. **Errors:**
+   - Validation errors use the Inertia errors bag (422), keyed by field.
+   - Domain errors (insufficient stock, price changed, invalid transition) are thrown as typed `DomainException`s with a stable `code`, and rendered as a flash `{ code, message }` or a page-level error component.
+   - The JSON endpoints that exist (webhooks, the polling endpoint for payment status) return `application/problem+json` (RFC 9457) with a `code` extension.
+7. **Requests:**
+   - Form requests validate. The generated TypeScript types for request payloads come from the same `*Data` classes when practical.
+   - **The server re-derives every price, total and permission.** The client only displays.
+8. **Business rules are not duplicated in TypeScript.** For example, refundable amounts, allowed transitions and stock availability are sent as computed fields (`canCancel`, `refundableAmount`, `allowedTransitions[]`).
+
+## Positive consequences
+
+- Drift becomes a CI failure.
+- The UI cannot drift into making business decisions.
+
+## Negative consequences
+
+- Two dependencies, and a generation step in the workflow.
+
+## Risks
+
+- Package incompatibility with Laravel 13. Mitigation: verify in Phase 3, with the first-party fallback above.
+
+## Testing implications
+
+- `assertInertia` tests per page checking the component and the prop keys and types.
+- The CI type-generation diff check.
+- `vue-tsc --noEmit` as a gate.
+
+## Migration implications
+
+None.
+
+## Related
+
+- `integration-contracts.md`, ADR-0008, ADR-0013.
diff --git a/docs/architecture/adr/0019-search-behind-a-port.md b/docs/architecture/adr/0019-search-behind-a-port.md
new file mode 100644
index 0000000..870c070
--- /dev/null
+++ b/docs/architecture/adr/0019-search-behind-a-port.md
@@ -0,0 +1,85 @@
+# ADR-0019: Put catalogue search behind a port, implemented with MySQL first
+
+- **Number:** 0019
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner (open decision D-8)
+
+---
+
+## Context
+
+- The old repository ran Typesense through Laravel Scout.
+- The brief lists Typesense in the existing stack, but says not every technology must remain.
+- The demo catalogue is small: a few hundred to low thousands of curated products.
+- Every extra service makes the demo harder for reviewers to run.
+
+## Problem
+
+What powers storefront search and filtering in v2?
+
+## Decision drivers
+
+- Relevance that is good enough for a curated catalogue.
+- Facets: category, price range, vendor, rating, in-stock.
+- Minimal infrastructure.
+- A clean seam for a later engine.
+
+## Considered alternatives
+
+### A. Typesense from day one
+
+- Better relevance and typo tolerance.
+- Rejected for now: it adds a service and an index-consistency problem before it adds value.
+
+### B. Laravel Scout's `database` engine
+
+Thin. It hides the query shape needed for facets.
+
+### C. A `CatalogueSearch` port with a MySQL implementation (chosen)
+
+- `FULLTEXT` index on searchable product text, plus indexed facet columns on a denormalised `search_documents` table.
+- The table is maintained by the Search module from Catalogue and Inventory outbox events.
+
+## Decision
+
+1. Search owns `search_documents`. There is one row per sellable product, built from Catalogue, Vendors, Inventory and Engagement events:
+   - title;
+   - brand;
+   - category path;
+   - vendor;
+   - minimum and maximum price;
+   - in-stock flag;
+   - rating;
+   - per-locale searchable text.
+
+   It is never a source of truth, and it can be rebuilt with `php artisan search:rebuild`.
+2. Search queries use `MATCH … AGAINST` in natural-language mode, with a LIKE fallback for queries shorter than the minimum token size. Facet counts come from grouped queries on indexed columns.
+3. The `CatalogueSearch` interface is stable. A Typesense adapter can be added in Phase 8 if search quality measurably needs it, with a new ADR.
+4. **Visibility rules** are applied when building documents (only sellable products), and re-checked when the product page loads.
+
+## Positive consequences
+
+- No extra service.
+- Consistency is handled by the outbox.
+
+## Negative consequences
+
+- Weaker relevance and typo tolerance.
+- Arabic stemming is limited in MySQL FULLTEXT.
+
+## Risks
+
+- Arabic search quality. Mitigation: normalise Arabic text (alef forms, diacritics) into the searchable text, and test it.
+
+## Testing implications
+
+- Search tests on MySQL: relevance ordering for fixtures, facet counts, hidden products never returned, and Arabic normalisation.
+
+## Migration implications
+
+- The Scout/Typesense dependency is not carried over.
+
+## Related
+
+- ADR-0017; Phase 0 §13.4.
diff --git a/docs/architecture/adr/0020-platform-administration-in-filament.md b/docs/architecture/adr/0020-platform-administration-in-filament.md
new file mode 100644
index 0000000..1171b90
--- /dev/null
+++ b/docs/architecture/adr/0020-platform-administration-in-filament.md
@@ -0,0 +1,72 @@
+# ADR-0020: Build platform administration with Filament; build the vendor dashboard in Vue
+
+- **Number:** 0020
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+- The brief (§6.3) asks to *evaluate and improve* Filament rather than assume replacement.
+- The old repository used Filament (v5.7) for an admin panel and Vue for the vendor area.
+- Platform staff need dense back-office CRUD, queues and audit views. Vendors need a product-grade, branded, localised experience (Phase 2 design system).
+
+## Problem
+
+Which technology serves the platform-administration and vendor surfaces?
+
+## Decision drivers
+
+- Speed of delivery for back-office tooling.
+- Product-grade UX for vendors.
+- Consistent authorisation.
+
+## Considered alternatives
+
+### A. Filament for both admin and vendor
+
+- Fast to build.
+- Rejected: the vendor experience would look like a generic admin, and Filament's tenancy model invites the global-scope pattern Phase 0 found unsafe.
+
+### B. Vue for both
+
+- One frontend stack.
+- Rejected: it rebuilds tables, filters, forms and actions that Filament provides, for a surface only staff see.
+
+### C. Filament for platform staff at `/admin`; Vue + Inertia for vendors at `/vendor` and customers at `/` (chosen)
+
+## Decision
+
+1. Filament serves only users with `platform_role`. The panel is gated by `canAccessPanel()`. Every resource and action is gated by policies using the permission enum (ADR-0011).
+2. Filament resources live in each module's `Filament/` namespace. They call Application use cases for every state change: approve vendor, override return, retry refund, resolve reconciliation exception. **Filament never writes status or money columns directly.**
+3. Admin dashboards (GMV, orders, refunds, payables, outbox and reconciliation health) read from Finance and Platform read models.
+4. Filament is themed with the Phase 2 design tokens (colours, typography) so it looks like part of the same product.
+5. **Compatibility check:** Filament's support for Laravel 13 / PHP 8.5 is to be verified in Phase 3 before installation. If it is unsupported, this ADR is revisited. The fallback is Vue admin pages built from the same component kit.
+
+## Positive consequences
+
+- Rich operator tooling at low cost.
+- Vendor UX is uncompromised.
+
+## Negative consequences
+
+- Two UI technologies (Livewire for admin, Vue for the rest).
+- The admin is localised in `en` only for v2 (stated limitation).
+
+## Risks
+
+- Direct Eloquent edits through generic Filament forms bypass use cases. Mitigation: status and money fields are read-only in forms, and an arch test forbids `Filament` namespaces from importing Domain models' state-machine setters.
+
+## Testing implications
+
+- Livewire/Filament tests per resource: access denied for non-staff and wrong role; actions invoke use cases; audit entries written.
+
+## Migration implications
+
+None.
+
+## Related
+
+- ADR-0011, `security-model.md`.
diff --git a/docs/architecture/adr/0021-environments-demo-data-and-production-isolation.md b/docs/architecture/adr/0021-environments-demo-data-and-production-isolation.md
new file mode 100644
index 0000000..69b1b19
--- /dev/null
+++ b/docs/architecture/adr/0021-environments-demo-data-and-production-isolation.md
@@ -0,0 +1,88 @@
+# ADR-0021: Isolate every Nexo 2.0 environment from the legacy production system; reproduce the demo from a clean database
+
+- **Number:** 0021
+- **Status:** Proposed
+- **Date:** 2026-11-01
+- **Decision owner:** Project owner
+
+---
+
+## Context
+
+Phase 0 found that:
+
+- the old staging deployed the `redesign` branch against the **production** database, with shared queue and cache tables;
+- the production deploy ran `migrate --force` by default.
+
+The brief (§3, §14) requires a fresh database, no connection to production, and a reproducible, isolated demo with believable data.
+
+The old deploy pipelines are still active, because disabling them needs repository admin rights (D-12 follow-up).
+
+## Problem
+
+Which environments exist, how are they isolated, and how is the demo built?
+
+## Decision drivers
+
+- Zero shared credentials or data with the legacy system.
+- Anyone can reproduce the demo.
+- No accidental migrations against anything that matters.
+
+## Considered alternatives
+
+### A. Reuse the legacy server and database with a new schema
+
+Rejected. It shares credentials and blast radius.
+
+### B. Separate environments with a seeded demo (chosen)
+
+## Decision
+
+1. **Environments:**
+
+   | Environment | Database | Payments | Purpose |
+   |---|---|---|---|
+   | local | `nexo` / `nexo_testing` on the developer's MySQL | Stripe test keys (optional) or the fake provider | Development |
+   | CI | MySQL 8.4 service container | Fake provider only | Gates |
+   | demo | Its own MySQL database and user on a host with **no** legacy credentials | Stripe **test mode** only | Public showcase |
+
+   There is **no** production environment handling real customers or money in scope.
+
+2. **Credentials:**
+   - The demo `.env` is created fresh. No value is copied from the legacy `.env`.
+   - Stripe live keys are rejected at boot: `sk_live_` and `pk_live_` prefixes throw in a service-provider check unless `NEXO_ALLOW_LIVE_PAYMENTS=true`, which no environment sets in v2.
+3. **Migrations in deployed environments** run as an explicit, separate, manually approved workflow step. They never run as a side effect of a push.
+4. **Demo data** comes from `php artisan nexo:demo:seed`, which is deterministic (fixed seed) and idempotent on an empty database. It creates:
+   - 8–12 vendors with distinct, coherent product lines;
+   - curated products with variants and licensed or royalty-free imagery (source and licence recorded in `docs/engineering/demo-environment.md`, Phase 3);
+   - customers, orders in every status, multi-vendor checkouts, refunds, a dispute, promotions, reviews and notifications.
+
+   Ledger postings are created **through the real use cases**, never by inserting balances. This means the demo data itself proves the ledger balances.
+5. **Demo credentials** are published in the README for demo roles only (customer, vendor owner, vendor fulfilment, platform operations, platform finance). The demo can be reset nightly by a scheduled `migrate:fresh` + seed, guarded so it runs only when `APP_ENV=demo`.
+6. **Legacy system:** the old repository's deploy workflows should be disabled by its admin (D-12). Nexo 2.0 workflows never reference legacy secrets.
+
+## Positive consequences
+
+- The brief's isolation rule is enforced by construction.
+- The demo is reproducible from a clean database.
+
+## Negative consequences
+
+- Hosting for the demo must be provisioned (Phase 10).
+
+## Risks
+
+- **Copied secrets.** Mitigation: the live-key boot check, plus secret scanning in CI (Phase 3).
+
+## Testing implications
+
+- The seeder runs in CI on an empty database. Ledger invariants and the reconciliation checks pass on the seeded data.
+- A boot test rejects live keys.
+
+## Migration implications
+
+None for v2. The legacy system is out of scope apart from containment (D-12).
+
+## Related
+
+- ADR-0009; Phase 0 §A.5, Addendum B.
diff --git a/docs/architecture/adr/ADR-TEMPLATE.md b/docs/architecture/adr/ADR-TEMPLATE.md
index dd47137..92060be 100644
--- a/docs/architecture/adr/ADR-TEMPLATE.md
+++ b/docs/architecture/adr/ADR-TEMPLATE.md
@@ -1,54 +1,59 @@
 # ADR-NNNN: <short imperative title>
 
-**Status:** Proposed | Accepted | Superseded by ADR-XXXX
-**Date:** YYYY-MM-DD
+- **Number:** NNNN
+- **Status:** Proposed | Accepted | Rejected | Deprecated | Superseded by ADR-XXXX
+- **Date:** YYYY-MM-DD
+- **Decision owner:** Project owner
+- **Supersedes / relates to:** ADR-XXXX (optional)
 
 ---
 
 ## Context
 
-What is forcing a decision now?
+What exists today, and the constraints. Separate verified facts from assumptions.
 
-Describe:
+## Problem
 
-- the problem;
-- constraints;
-- relevant existing architecture;
-- what is known;
-- what remains uncertain.
+The specific question this ADR answers, in one or two sentences.
 
-## Decision
+## Decision drivers
+
+- The forces that matter for this decision (correctness, cost, operability, showcase value, …).
+
+## Considered alternatives
 
-State the decision plainly.
+### A. <option>
 
-Avoid describing multiple possible futures.
+Description, then why it was chosen or rejected.
 
-## Alternatives Considered
+### B. <option>
+
+Description, then why it was chosen or rejected.
+
+## Decision
 
-### Option A
+The choice, stated plainly. One future, not several.
 
-Why it was considered and why it was rejected.
+## Positive consequences
 
-### Option B
+- What becomes easier or safer.
 
-Why it was considered and why it was rejected.
+## Negative consequences
 
-## Consequences
+- What becomes harder, and what we now have to maintain.
 
-### Positive
+## Risks
 
-What becomes easier or safer?
+- What could go wrong, and how we would notice.
 
-### Negative
+## Testing implications
 
-What becomes harder?
+- The tests that prove the decision holds, and where they run.
 
-### Follow-up
+## Migration implications
 
-What work does this decision create?
+- Effect on existing code, data and documents. "None" is a valid answer for greenfield work.
 
 ## Related
 
-- Related ADRs
-- Relevant product documentation
-- Relevant issues
+- ADRs, product requirements, lifecycle documents.
diff --git a/docs/architecture/database-design.md b/docs/architecture/database-design.md
new file mode 100644
index 0000000..8143505
--- /dev/null
+++ b/docs/architecture/database-design.md
@@ -0,0 +1,192 @@
+# Initial Database Model
+
+- **Status:** Draft for owner review (Phase 1). This is a logical model; migrations are written in Phases 3–6, one module at a time.
+- **Date:** 2026-11-01
+- **Engine:** MySQL 8.4, InnoDB, `utf8mb4_0900_ai_ci`, strict mode (ADR-0009)
+
+## 1. Conventions
+
+| Topic | Rule |
+|---|---|
+| Primary keys | `id BIGINT UNSIGNED AUTO_INCREMENT`. Internal only; never exposed to the browser. |
+| Public identifiers | `public_id CHAR(26)` ULID, UNIQUE, on every entity addressed by URL (vendors use `slug`). Order references are human-readable and separately unique. |
+| Money | `*_minor BIGINT` + `currency CHAR(3)` (ADR-0013). Rates are `*_bps INT UNSIGNED`. |
+| Status | `VARCHAR(32)` + `CHECK (status IN (...))` matching the PHP enum, so a value outside the enum fails at the database |
+| Time | `TIMESTAMP(6)` in UTC; `created_at`, `updated_at` on every mutable table. Append-only tables have only `created_at` / `occurred_at`. |
+| Foreign keys | Always declared. `ON DELETE RESTRICT` by default; `CASCADE` only for pure child rows of the same aggregate (e.g. `cart_lines` of `carts`). Cross-module foreign keys are `RESTRICT` (ADR-0010). |
+| Soft deletes | **Not used.** Lifecycle status (vendors, products), anonymisation (users) and archival (closed carts) replace them. Financial and order tables are never deleted. |
+| Translations | Platform-owned names (categories, attributes, shipping zones) are stored as `JSON` `{en, ar, ms}`. Vendor-entered content is single-language `VARCHAR/TEXT`. |
+| Ownership | Exactly one owning module per table (`domain-context-map.md` §2); the owner is noted below as **[Module]** |
+
+## 2. Entity overview
+
+```
+users ─1:0..1─ vendor_members ─*:1─ vendors ─1:1─ vendor_profiles
+  │                                   │ 1:*
+  │ 1:*                               ├── products ─1:*─ variants ─1:1─ stock_levels ─1:*─ stock_reservations
+addresses                             │      │                │                   └─1:*─ stock_movements
+                                      │      └─1:*─ product_images      └─*:*─ attribute_values (via variant_attribute_values)
+                                      └── vendor_shipping_rates ─*:1─ shipping_zones
+categories (tree) ─1:*─ products
+
+users ─1:*─ order_groups ─1:*─ vendor_orders ─1:*─ vendor_order_lines ─*:1─ variants
+                 │                 │  ├─1:*─ shipments
+                 │                 │  ├─1:*─ return_requests ─1:*─ return_request_lines
+                 │                 │  └─1:*─ vendor_order_status_history
+                 └─1:*─ payment_attempts ─1:*─ refunds(per vendor_order) ; disputes(per attempt)
+provider_events (independent, unique event id)
+ledger_transactions ─1:*─ ledger_entries ─*:1─ ledger_accounts ; payouts ─*:1─ payout_runs
+```
+
+## 3. Tables by module
+
+Only key columns are listed. Every table also has `created_at`/`updated_at` unless it is marked append-only.
+
+### Identity
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `users` | id, public_id, name, email, email_verified_at, password, locale (`en/ar/ms`), platform_role NULL (`admin/operations/finance/support`), two_factor_secret NULL, two_factor_confirmed_at NULL, anonymised_at NULL | UNIQUE email; CHECK locale; CHECK platform_role |
+| `addresses` | id, user_id, recipient_name, phone, line1, line2, city, postcode (5 digits), state, zone_code, is_default | FK user CASCADE; INDEX (user_id); at most one default via `default_marker` (1/NULL) UNIQUE (user_id, default_marker) |
+| `sessions`, `password_reset_tokens` | Laravel defaults | — |
+| `staff_invitations` | id, email, platform_role, token_hash, expires_at, accepted_at | UNIQUE token_hash |
+
+### Vendors
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `vendor_applications` | id, public_id, user_id, store_name, description, contact_phone, category_focus, status (`submitted/approved/rejected`), decided_by, decided_at, decision_reason | FK user; one open application per user: UNIQUE (user_id, open_marker) |
+| `vendors` | id, public_id, slug, name, status (`pending/approved/suspended`), approved_at, suspended_at, suspension_reason | UNIQUE slug; CHECK status; INDEX status |
+| `vendor_members` | id, vendor_id, user_id, role (`owner/manager/fulfilment/finance/support`), status (`active/deactivated`), owner_marker (1/NULL) | UNIQUE user_id (INV-2); UNIQUE (vendor_id, owner_marker) (one owner); FK vendor, user RESTRICT |
+| `vendor_invitations` | id, vendor_id, email, role, token_hash, invited_by, expires_at, accepted_at, revoked_at | UNIQUE token_hash; INDEX (vendor_id, email) |
+| `vendor_profiles` | vendor_id PK, tagline, description, logo_path, banner_path, return_policy, support_email | FK vendor CASCADE |
+
+> **Note:** commission overrides are owned by Finance (`commission_rates`). `vendors` does **not** store them, which keeps `vendor-domain-design.md` §3 intact.
+
+### Catalogue
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `categories` | id, public_id, parent_id NULL, slug, name JSON, depth (1–3), path (materialised, e.g. `/3/17/`), is_active, position | UNIQUE slug; CHECK depth BETWEEN 1 AND 3; INDEX path; FK parent RESTRICT |
+| `attributes` | id, code, name JSON | UNIQUE code |
+| `attribute_values` | id, attribute_id, code, label JSON, position | UNIQUE (attribute_id, code) |
+| `products` | id, public_id, vendor_id, category_id, slug, title, description, brand NULL, status (`draft/active/inactive`), blocked_at NULL, blocked_reason NULL, published_at | UNIQUE (vendor_id, slug); INDEX (vendor_id, status); INDEX (category_id, status); FK vendor, category RESTRICT |
+| `product_images` | id, product_id, path, alt, position, width, height | FK product CASCADE; UNIQUE (product_id, position) |
+| `variants` | id, public_id, product_id, vendor_id (denormalised for scoping), sku, price_minor, compare_at_minor NULL, currency, weight_grams, is_active, option_signature (sorted value ids, e.g. `3-17`) | UNIQUE (vendor_id, sku); UNIQUE (product_id, option_signature); CHECK price_minor > 0; CHECK compare_at_minor IS NULL OR compare_at_minor > price_minor |
+| `variant_attribute_values` | variant_id, attribute_value_id | PK pair; FK CASCADE |
+| `product_moderation_events` (append-only) | id, product_id, action (`blocked/unblocked`), reason, actor_id, created_at | INDEX product_id |
+
+### Inventory (ADR-0014)
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `stock_levels` | variant_id PK, vendor_id, on_hand INT UNSIGNED, reserved INT UNSIGNED, low_stock_threshold, version | CHECK reserved <= on_hand; INDEX vendor_id |
+| `stock_reservations` | id, order_group_id, vendor_order_line_id, variant_id, qty, status (`active/consumed/released/expired`), expires_at, extended_at NULL | INDEX (status, expires_at); INDEX order_group_id; UNIQUE vendor_order_line_id |
+| `stock_movements` (append-only) | id, variant_id, vendor_id, type (`receipt/adjustment/count/reservation/release/sale/cancellation_restock/return_restock`), delta_on_hand INT, delta_reserved INT, reference_type, reference_id, actor_id NULL, reason NULL, created_at | **UNIQUE (type, reference_type, reference_id, variant_id)**; INDEX (variant_id, created_at) |
+
+### Shipping
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `shipping_zones` | id, code (`WM`, `EM`), name JSON, states JSON | UNIQUE code |
+| `vendor_shipping_rates` | id, vendor_id, zone_id, rate_minor, free_over_minor NULL, currency | UNIQUE (vendor_id, zone_id) |
+
+### Ordering
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `carts` | id, user_id NULL, session_token_hash NULL, status (`active/merged/converted/abandoned`) | UNIQUE (user_id, active_marker); UNIQUE session_token_hash |
+| `cart_lines` | id, cart_id, variant_id, qty | UNIQUE (cart_id, variant_id); CHECK qty BETWEEN 1 AND 20; FK cart CASCADE |
+| `order_groups` | id, public_id, reference (`NX-YYMMDD-XXXXXX`), customer_id, idempotency_key, status (`pending_payment/paid/expired/cancelled`), goods_minor, shipping_minor, discount_minor, points_value_minor, total_minor, currency, shipping_address JSON (snapshot), active_attempt_id NULL, promotion_id NULL, points_redeemed, expires_at, paid_at | **UNIQUE (customer_id, idempotency_key)**; UNIQUE reference; INDEX (status, expires_at); CHECK total_minor = goods_minor + shipping_minor − discount_minor − points_value_minor |
+| `vendor_orders` | id, public_id, reference (`<group>-<n>`), order_group_id, vendor_id, status (ADR-0012), goods_minor, shipping_minor, discount_minor, points_value_minor, total_minor, commission_rate_bps, commission_minor, refundable_cap_minor, refund_committed_minor, currency, shipped_at, delivered_at, completed_at, return_window_ends_at, cancelled_reason | UNIQUE reference; UNIQUE (order_group_id, vendor_id); INDEX (vendor_id, status, created_at); CHECK refund_committed_minor <= refundable_cap_minor |
+| `vendor_order_lines` | id, vendor_order_id, variant_id, product_title, variant_label, sku, unit_price_minor, qty, goods_minor, discount_allocated_minor, points_value_allocated_minor, commission_minor, refund_committed_qty, refund_committed_minor | CHECK refund_committed_qty <= qty; INDEX vendor_order_id |
+| `vendor_order_status_history` (append-only) | id, vendor_order_id, from_status, to_status, actor_type (`system/customer/vendor_member/staff`), actor_id, reason, created_at | INDEX vendor_order_id |
+| `shipments` | id, vendor_order_id, carrier, tracking_number, shipped_at | UNIQUE vendor_order_id (one shipment per VendorOrder in v2) |
+| `return_requests` | id, public_id, vendor_order_id, customer_id, status (`requested/approved/rejected/received/closed/escalated`), reason_code, note, decided_by, decided_at, escalated_at | INDEX (vendor_order_id); INDEX (status, created_at) |
+| `return_request_lines` | id, return_request_id, vendor_order_line_id, qty, received_qty, resellable_qty | CHECK received_qty <= qty |
+
+### Payments
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `payment_attempts` | id, public_id, order_group_id, provider (`stripe/fake`), provider_payment_id NULL, amount_minor, currency, status (`created/creation_failed/requires_payment_method/requires_action/processing/succeeded/failed/cancelled`), failure_code, client_secret_encrypted | **UNIQUE provider_payment_id**; INDEX (order_group_id); INDEX (status, updated_at) |
+| `provider_events` | id, provider, event_id, type, payload JSON, received_at, processed_at NULL, attempts, last_error | **UNIQUE (provider, event_id)**; INDEX (processed_at, received_at) |
+| `refunds` | id, public_id, vendor_order_id, payment_attempt_id, amount_minor, currency, reason, initiator_type, initiator_id, status (`requested/approved/submitted/succeeded/failed`), provider_refund_id NULL, failure_code | UNIQUE provider_refund_id; INDEX (vendor_order_id); INDEX (status, updated_at) |
+| `refund_lines` | refund_id, vendor_order_line_id, qty, amount_minor, commission_reversed_minor, discount_reversed_minor, points_value_reversed_minor | PK pair |
+| `disputes` | id, payment_attempt_id, provider_dispute_id, amount_minor, reason, status (`open/won/lost`), evidence_due_at | UNIQUE provider_dispute_id |
+
+### Finance (ADR-0016)
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `commission_rates` | id, scope (`default/category/vendor`), scope_id NULL, rate_bps, effective_from, created_by | UNIQUE (scope, scope_id, effective_from); CHECK rate_bps BETWEEN 0 AND 5000 |
+| `ledger_accounts` | id, code (e.g. `vendor:42:payable_pending`), kind (`asset/liability/revenue/expense`), vendor_id NULL | UNIQUE code |
+| `ledger_transactions` (append-only) | id, type, reference_type, reference_id, description, occurred_at, metadata JSON | **UNIQUE (type, reference_type, reference_id)** |
+| `ledger_entries` (append-only) | id, transaction_id, account_id, direction (`debit/credit`), amount_minor, currency | CHECK amount_minor > 0; INDEX (account_id, id) |
+| `payout_runs` | id, idempotency_key, period_end, status (`running/completed`), started_at, completed_at | UNIQUE idempotency_key; UNIQUE period_end |
+| `payouts` | id, public_id, payout_run_id, vendor_id, amount_minor, currency, status (`simulated_paid`) | **UNIQUE (payout_run_id, vendor_id)** |
+| `dispute_allocations` | id, dispute_id, vendor_order_id, amount_minor | UNIQUE (dispute_id, vendor_order_id) |
+| `reconciliation_runs` | id, kind (`internal/provider`), window_start, window_end, status, summary JSON | — |
+| `reconciliation_exceptions` | id, run_id, category, subject_type, subject_id, details JSON, status (`open/resolved`), resolved_by, resolution_note | INDEX (status) |
+
+### Promotions
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `promotions` | id, public_id, name, code NULL, kind (`coupon/automatic`), discount_type (`percent/fixed`), value (bps or minor), min_spend_minor, max_discount_minor NULL, starts_at, ends_at, usage_limit NULL, per_customer_limit NULL, used_count, pending_count, is_active | UNIQUE code; CHECK used_count + pending_count <= COALESCE(usage_limit, ~0) is enforced by guarded update (CHECK with NULL logic documented in the migration) |
+| `promotion_targets` | promotion_id, target_type (`category/vendor`), target_id | PK triple |
+| `promotion_redemptions` | id, promotion_id, customer_id, order_group_id, status (`pending/confirmed/released`), discount_minor | UNIQUE (promotion_id, order_group_id) |
+
+### Loyalty
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `points_entries` (append-only) | id, customer_id, type (`earn/redeem/release/clawback/referral_award/adjustment`), points (signed), reference_type, reference_id, created_at | UNIQUE (type, reference_type, reference_id); INDEX (customer_id, id) |
+| `points_holds` | id, customer_id, order_group_id, points, status (`held/confirmed/released`) | UNIQUE order_group_id |
+| `referral_codes` | id, customer_id, code | UNIQUE code; UNIQUE customer_id |
+| `referrals` | id, referrer_id, referee_id, first_order_group_id NULL, status (`pending/qualified/awarded/void`) | UNIQUE referee_id |
+
+### Engagement
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `reviews` | id, public_id, product_id, vendor_id, vendor_order_line_id, customer_id, rating, body, status (`published/hidden`), hidden_reason | **UNIQUE vendor_order_line_id**; CHECK rating BETWEEN 1 AND 5; INDEX (product_id, status) |
+| `review_images` | id, review_id, path, position | — |
+| `review_replies` | id, review_id, vendor_member_id, body | UNIQUE review_id |
+| `wishlist_items` | customer_id, product_id | PK pair |
+| `store_follows` | customer_id, vendor_id | PK pair |
+
+### Search, Notifications, Shared
+
+| Table | Key columns | Constraints and indexes |
+|---|---|---|
+| `search_documents` | product_id PK, vendor_id, category_path, title, brand, text_en, text_ar, text_ms, min_price_minor, max_price_minor, in_stock, rating_avg, rating_count, published_at | FULLTEXT (title, brand, text_en, text_ar, text_ms); INDEX (category_path), (min_price_minor), (vendor_id), (in_stock) |
+| `notifications` | Laravel database notifications | — |
+| `notification_preferences` | user_id, channel, category, enabled | PK triple |
+| `outbox_messages` | id ULID, type, aggregate_type, aggregate_id, payload JSON, occurred_at, dispatched_at NULL, attempts, dead_at NULL, last_error | INDEX (dispatched_at, occurred_at) |
+| `processed_messages` | consumer, message_id, processed_at | PK (consumer, message_id) |
+| `idempotency_keys` | scope, key, user_id NULL, request_hash, response JSON, status_code, created_at, expires_at | PK (scope, key) |
+| `audit_log` (append-only) | id, actor_id, impersonator_id NULL, action, subject_type, subject_id, before JSON, after JSON, ip, user_agent, created_at | INDEX (subject_type, subject_id); INDEX (actor_id, created_at) |
+| `settings` | key, value JSON, updated_by | PK key |
+| `jobs`, `failed_jobs`, `cache`, `cache_locks` | Laravel defaults (local/dev only; Redis in demo) | — |
+
+## 4. Concurrency-relevant constraints (summary)
+
+| Scenario (brief §10) | Primary protection | Secondary |
+|---|---|---|
+| Last unit / concurrent reservation | Conditional `UPDATE stock_levels … WHERE on_hand - reserved >= qty` | CHECK reserved <= on_hand |
+| Duplicate checkout submission | UNIQUE (customer_id, idempotency_key) | Idempotency store replay |
+| Simultaneous order transitions | `UPDATE … WHERE status = :from` | Status-history audit |
+| Duplicate webhook | UNIQUE (provider, event_id) | Inbox; ledger UNIQUE (type, reference) |
+| Repeated refund requests | Guarded `refund_committed_*` counters | Idempotency key; provider idempotency key |
+| Concurrent vendor stock updates | Delta guarded update; absolute set with `version` CAS | Movement journal |
+| Idempotency-key reuse with different payload | `idempotency_keys.request_hash` comparison → 422 | — |
+| Failed transaction / rollback | Use-case transactions; outbox in same TX | Rollback tests |
+| Concurrent payout runs | UNIQUE period_end / idempotency_key; UNIQUE (run, vendor) | Ledger UNIQUE |
+| Promotion last use | Guarded counter update | Redemption UNIQUE |
+
+## 5. Open points for Phase 3
+
+- MySQL `CHECK` constraints that reference other columns work on 8.0.16+. Constraints that need cross-row logic stay in guarded updates.
+- The `*_marker` (1/NULL) technique emulates partial unique indexes. It is documented in the migration comments.
+- Whether `search_documents` keeps three per-locale text columns or one combined column is decided by search tests on Arabic fixtures.
diff --git a/docs/architecture/dependency-rules.md b/docs/architecture/dependency-rules.md
new file mode 100644
index 0000000..36e29bd
--- /dev/null
+++ b/docs/architecture/dependency-rules.md
@@ -0,0 +1,102 @@
+# Dependency Rules
+
+- **Status:** Draft for owner review (Phase 1). This document is normative once ADR-0010 is accepted. Every rule below becomes a Pest `arch()` test in Phase 3.
+- **Date:** 2026-11-01
+
+## 1. Layer rules (inside every module)
+
+```
+Http ──► Application ──► Domain
+Infrastructure ──► Application, Domain
+Filament ──► Application (writes), Application/Queries (reads)
+Domain ──► Shared only
+```
+
+| # | Rule | Arch test sketch |
+|---|---|---|
+| L1 | `Domain` does not import `Illuminate\Http`, `Illuminate\Support\Facades\Request`, `Inertia\`, `Filament\`, `Livewire\`, `Stripe\` | `arch()->expect('App\Modules\*\Domain')->not->toUse([...])` |
+| L2 | `Application` does not import `Http`, `Filament`, `Inertia` | similar |
+| L3 | Controllers do not use `DB::`, `Model::create/update/save/delete` or status setters; they call one Application use case | `expect('App\Modules\*\Http\Controllers')->not->toUse('Illuminate\Support\Facades\DB')` plus a custom expectation |
+| L4 | Only state-machine classes assign `status` attributes | custom expectation over `->status =` / `update(['status'` patterns (PHPStan rule if arch is insufficient) |
+| L5 | Provider SDKs (`Stripe\`) are used only in `Payments\Infrastructure` | arch |
+| L6 | `env()` is used only in `config/` | existing rule |
+| L7 | No debug helpers (`dd`, `dump`, `ray`, `var_dump`) | existing preset |
+
+## 2. Module rules
+
+| # | Rule |
+|---|---|
+| M1 | A module may import another module **only** from `App\Modules\<Other>\Contracts\*`. |
+| M2 | Every module may import `App\Shared\*`. `Shared` imports no module. |
+| M3 | No Eloquent relationship, join, or raw query from module A touches a table owned by module B. The exceptions are listed in §4. |
+| M4 | Allowed synchronous dependencies are only those in the matrix below (✓). Anything else is either an event subscription or a design error. |
+| M5 | No cycles in synchronous dependencies. The matrix is acyclic; the arch test computes the graph. |
+| M6 | Events are published only by their owning module (`<Module>\Contracts\Events`), and are consumed through explicit subscriptions. |
+
+### Synchronous dependency matrix (row → may call contracts of column)
+
+| ↓ caller / callee → | Identity | Vendors | Catalogue | Inventory | Shipping | Ordering | Payments | Finance | Promotions | Loyalty | Engagement | Search | Notif. |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| **Identity** | | | | | | | | | | | | | |
+| **Vendors** | ✓ | | | | | | | | | | | | |
+| **Catalogue** | | ✓ | | | | | | | | | | | |
+| **Inventory** | | ✓ | ✓ | | | | | | | | | | |
+| **Shipping** | | ✓ | | | | | | | | | | | |
+| **Ordering** | ✓ | ✓ | ✓ | ✓ | ✓ | | ✓ | ✓¹ | ✓ | ✓ | | | |
+| **Payments** | | | | | | ✓² | | | | | | | |
+| **Finance** | | ✓ | | | | ³ | ³ | | | | | | |
+| **Promotions** | | | ✓ | | | | | | | | | | |
+| **Loyalty** | ✓ | | | | | | | | | | | | |
+| **Engagement** | ✓ | ✓ | ✓ | | | ✓⁴ | | | | | | | |
+| **Search** | | ✓ | ✓ | ✓ | | | | | | | ✓ | | |
+| **Notifications** | ✓ | ✓ | | | | ✓ | | | | | | | |
+
+Footnotes:
+
+1. Ordering asks Finance for the commission rate to freeze (`CommissionRates::resolve(vendorId, categoryId)`), and that is all.
+2. Payments calls `Ordering\Contracts\OrderPayments` inside the payment-success transaction (context map §3). **Cycle check:** Ordering → Payments (create attempt, request refund) and Payments → Ordering (markPaid) would form a cycle. It is broken as follows:
+   - `OrderPayments` is an interface declared in **Payments\Contracts** and *implemented* by Ordering. This is dependency inversion: Payments owns the port, and Ordering provides the adapter.
+   - Payments therefore never imports Ordering, and the graph stays acyclic.
+3. **Deliberately empty.** Finance must not call Ordering or Payments synchronously; Ordering → Finance (footnote 1) would otherwise create a cycle.
+   - Statements are built from Finance's own ledger. Every ledger transaction carries its `reference_type` and `reference_id`, plus the order and refund references it needs for display, copied from the event payload.
+   - Reconciliation and dashboards use the named read-model queries in §4.
+4. Engagement asks Ordering "did this customer receive this line?" for verified reviews.
+
+## 3. Event subscriptions (asynchronous; no restriction on direction)
+
+| Event (publisher) | Subscribers |
+|---|---|
+| `VendorApproved`, `VendorSuspended`, `VendorReinstated` (Vendors) | Catalogue (sellability cache), Search, Notifications |
+| `ProductChanged`, `ProductBlocked/Unblocked` (Catalogue) | Search, Engagement (wishlist availability), Notifications (followers, S) |
+| `StockLevelChanged` (Inventory) | Search |
+| `CheckoutPlaced` (Ordering) | Notifications (none in v2: placeholder for an abandoned-payment reminder) |
+| `OrderGroupPaid`, `VendorOrderPaid` (Ordering) | Notifications, Finance (capture posting, from `PaymentCaptured`, see below) |
+| `PaymentCaptured`, `ProviderFeeRecorded`, `RefundSucceeded`, `RefundFailed`, `DisputeOpened/Won/Lost` (Payments) | Finance, Ordering (refund status), Loyalty and Promotions (reversals), Notifications |
+| `VendorOrderCancelled`, `ReturnReceived` (Ordering) | Payments (request refund), Notifications |
+| `VendorOrderCompleted` (Ordering) | Finance (maturity), Loyalty (award), Engagement (review prompt) |
+| `PayoutMade` (Finance) | Notifications |
+| `ReviewPublished/Hidden` (Engagement) | Search (rating), Notifications |
+
+## 4. Allowed read-model exceptions to M3
+
+These read across tables owned by other modules. Each is a read-only query class in its own module's `Application/Queries`, named and listed here, and arch-tested to use only `DB::table()->select` (no writes).
+
+| Query | Module | Reads | Why |
+|---|---|---|---|
+| `FinanceDashboardQuery` | Finance | `vendor_orders`, `refunds` | Period aggregates; contract calls would be N+1 |
+| `ReconciliationQuery` | Finance | `payment_attempts`, `provider_events`, `refunds` | Matching against the ledger |
+| `AdminOrderLookupQuery` | Ordering | `payment_attempts.provider_payment_id`, `users.email` | Support lookup |
+| `SearchDocumentBuilder` | Search | `products`, `variants`, `stock_levels`, `vendors`, `reviews` | Rebuild command (the event path uses contracts) |
+
+Adding to this list needs a PR that updates this table.
+
+## 5. Frontend rules
+
+| # | Rule |
+|---|---|
+| F1 | `resources/js/storefront` and `resources/js/vendor` may import `resources/js/shared`, but not each other |
+| F2 | Pages import types only from `types/generated.d.ts` for server data (no local re-declaration) |
+| F3 | No money arithmetic in components beyond display; totals come from the server (ADR-0013, ADR-0018) |
+| F4 | No physical direction utilities (`ml-`, `pr-`, `left-`, `text-left`) in components; use logical equivalents (`ms-`, `pe-`, `start-`, `text-start`) |
+
+Rules F1–F4 are enforced with ESLint (`import/no-restricted-paths`, plus a custom Tailwind class lint) in Phase 3.
diff --git a/docs/architecture/domain-context-map.md b/docs/architecture/domain-context-map.md
new file mode 100644
index 0000000..ff1dc34
--- /dev/null
+++ b/docs/architecture/domain-context-map.md
@@ -0,0 +1,111 @@
+# Domain Context Map
+
+- **Status:** Draft for owner review (Phase 1). This document is normative once ADR-0010 is accepted.
+- **Date:** 2026-11-01
+
+## 1. How boundaries were chosen
+
+The brief (§8) says boundaries should follow these criteria:
+
+- business ownership;
+- consistency requirements;
+- independent lifecycle;
+- language.
+
+The table records which criterion separates each module. Capabilities that share a consistency boundary and a lifecycle were merged rather than split. The brief lists about 20 capabilities; they map to **13 modules plus a shared kernel**.
+
+| Brief capability | Module | Why here |
+|---|---|---|
+| Identity and access management | **Identity** | Accounts, authentication, staff roles; one owner of `users` |
+| Vendor management | **Vendors** | Vendor lifecycle, applications, team membership, store profile; operator-owned lifecycle |
+| Catalogue, categories and attributes, product variants, pricing | **Catalogue** | One consistency boundary: a variant's price, options and sellability change together. Pricing has no independent lifecycle in v2. |
+| Inventory | **Inventory** | Different consistency needs (high-contention counters, reservations); single writer of stock |
+| Shipping (rates) | **Shipping** | Vendor-configured rate tables and quoting. Shipments are part of Ordering (below). |
+| Cart, checkout, orders, shipping and fulfilment (shipments), returns | **Ordering** | Cart → checkout → OrderGroup/VendorOrder → shipments → returns share the order lifecycle and language |
+| Payments, refunds (provider side) | **Payments** | Provider interaction, attempts, provider events, refunds and disputes as provider objects; its own failure modes |
+| Financial reporting, commissions, payouts | **Finance** | Ledger, commission policy, balances, payouts, reconciliation; accounting language and audit needs |
+| Promotions | **Promotions** | Campaign lifecycle independent of orders; redemption limits need their own consistency |
+| Loyalty (justified: owner D-7) | **Loyalty** | Points ledger and referrals; their own balance invariant |
+| Reviews, wishlist, store follow | **Engagement** | Customer-generated content around products and stores; low consistency coupling |
+| Search | **Search** | A read model only, rebuilt from events |
+| Notifications | **Notifications** | Delivery channels and preferences; event subscriber only |
+| Platform operations | **Shared** kernel (audit, settings) + Filament surfaces in each module | Not a business domain. Cross-cutting tooling must not become a "god module". |
+
+## 2. Module responsibilities and owned data
+
+| Module | Responsibilities | Owns (tables) |
+|---|---|---|
+| Identity | Registration, login, verification, 2FA (staff), profile, addresses, locale preference, platform staff roles | `users`, `addresses`, `password_reset_tokens`, `sessions`, `staff_invitations` |
+| Vendors | Applications, vendor lifecycle, memberships and invitations, store profile, operating eligibility | `vendor_applications`, `vendors`, `vendor_members`, `vendor_invitations`, `vendor_profiles` |
+| Catalogue | Category tree, attributes, products, variants, media, sellability, moderation | `categories`, `attributes`, `attribute_values`, `products`, `product_images`, `variants`, `variant_attribute_values`, `product_moderation_events` |
+| Inventory | Stock levels, reservations, movements, adjustments, sweeper | `stock_levels`, `stock_reservations`, `stock_movements` |
+| Shipping | Zones, vendor rate tables, quotes | `shipping_zones`, `vendor_shipping_rates` |
+| Ordering | Carts, checkout placement, OrderGroups, VendorOrders, lines, status history, shipments, returns | `carts`, `cart_lines`, `order_groups`, `vendor_orders`, `vendor_order_lines`, `vendor_order_status_history`, `shipments`, `return_requests`, `return_request_lines` |
+| Payments | Payment attempts, provider events, refunds, disputes (provider side), provider adapter | `payment_attempts`, `provider_events`, `refunds`, `refund_lines`, `disputes` |
+| Finance | Commission policy, ledger, balances, payouts, reconciliation | `commission_rates`, `ledger_accounts`, `ledger_transactions`, `ledger_entries`, `payouts`, `payout_runs`, `dispute_allocations`, `reconciliation_runs`, `reconciliation_exceptions` |
+| Promotions | Promotions, codes, eligibility, allocation, redemptions | `promotions`, `promotion_targets`, `promotion_redemptions` |
+| Loyalty | Points ledger, holds, referral codes, referrals | `points_entries`, `points_holds`, `referral_codes`, `referrals` |
+| Engagement | Reviews, replies, moderation, wishlist, store follows | `reviews`, `review_images`, `review_replies`, `wishlist_items`, `store_follows` |
+| Search | Search documents, rebuild | `search_documents` |
+| Notifications | Notification records, preferences, delivery | `notifications`, `notification_preferences` |
+| Shared | Outbox, inbox, idempotency keys, audit log, settings | `outbox_messages`, `processed_messages`, `idempotency_keys`, `audit_log`, `settings` |
+
+## 3. Relationships
+
+**U** = upstream (supplier of the model). **D** = downstream (consumer). "Contract" means a synchronous `Contracts` interface. "Events" means asynchronous delivery through the outbox.
+
+```
+                         ┌───────────┐
+                         │ Identity  │ U (customer/user ids, staff roles)
+                         └─────┬─────┘
+                               │ contract
+          ┌────────────────────┼─────────────────────────────┐
+          ▼                    ▼                             ▼
+     ┌─────────┐ events   ┌───────────┐ contract (sellability, ┌──────────┐
+     │ Vendors │────────► │ Catalogue │  variant snapshot)     │ Shipping │
+     └────┬────┘          └─────┬─────┘──────────┐             └────┬─────┘
+          │ contract (eligibility)│ events         ▼ contract         │ contract (quote)
+          │                     │            ┌──────────┐           │
+          │                     ▼            │ Ordering │◄──────────┘
+          │               ┌───────────┐ contract (reserve/consume/release)
+          │               │ Inventory │◄─────┤          │── contract (hold/confirm) ─► Promotions
+          │               └───────────┘      │          │── contract (hold/confirm) ─► Loyalty
+          │                                  │          │── contract (create attempt, request refund) ─► Payments
+          │                                  └────┬─────┘
+          │                                       │ events (VendorOrderPaid, Cancelled, Completed, ReturnReceived…)
+          ▼                                       ▼
+     ┌─────────┐   events (captured, refunded,  ┌─────────┐
+     │ Finance │◄─ disputed, fees) ─────────────│Payments │──► contract: Ordering.markGroupPaid (inside the
+     └─────────┘                                └─────────┘    payment-success transaction, see note)
+     Search, Notifications, Engagement(rating aggregates) ◄── events from all of the above
+```
+
+**Note on the payment-success transaction.** Payments, Ordering, Inventory, Promotions and Loyalty commit **together** when a payment succeeds, because "paid without stock consumed" is not an acceptable intermediate state. This is the only cross-module synchronous transaction.
+
+It is orchestrated by `Payments\Application\HandlePaymentSucceeded`, which calls these contracts within one database transaction:
+
+- `Ordering\Contracts\OrderPayments::markPaid(groupId, attemptRef)`;
+- that, in turn, calls Inventory, Promotions and Loyalty contracts.
+
+Finance is **not** in this transaction. It posts from the outbox event, because a ledger lag of seconds is acceptable, whereas a lost posting is not, and the outbox guarantees the posting is never lost.
+
+## 4. Ubiquitous language (glossary)
+
+| Term | Meaning | Not to be confused with |
+|---|---|---|
+| Vendor | An independent seller entity with its own lifecycle | A user, a store page |
+| Vendor member | A user's membership of one vendor, with a role | Platform staff |
+| Customer | Any signed-in user acting as a buyer | Visitor (not signed in) |
+| Product / Variant | A listing / a purchasable option combination with SKU, price and stock | — |
+| Sellable | Product active ∧ not blocked ∧ vendor approved ∧ ≥ 1 active variant (INV-12) | "Active" alone |
+| OrderGroup | One customer checkout and payment | VendorOrder |
+| VendorOrder | One vendor's portion of an OrderGroup; the unit of fulfilment, refund and payable | — |
+| Reservation | Stock held for an unpaid OrderGroup, with a TTL | Allocation |
+| Payment attempt | One provider payment try for a group; several may exist over time, at most one active | Payment (the group's captured money) |
+| Refund | A provider refund for part or all of one VendorOrder | Return (the goods workflow) |
+| Return request | A customer's request to send goods back | Refund |
+| Dispute | A chargeback raised through the provider on a group's charge | Return |
+| Payable | Ledger liability owed to a vendor (pending, available, held) | Payout |
+| Payout | A (simulated) settlement of available payable to a vendor | Refund |
+| Commission | Platform revenue per line, at the frozen rate | Fee (provider's charge to the platform) |
+| Allocation | The deterministic split of an amount across lines or orders | Reservation |
diff --git a/docs/architecture/financial-model.md b/docs/architecture/financial-model.md
new file mode 100644
index 0000000..3541fa0
--- /dev/null
+++ b/docs/architecture/financial-model.md
@@ -0,0 +1,194 @@
+# Financial Model
+
+- **Status:** Draft for owner review (Phase 1). It implements ADR-0016 and ADR-0013. It develops Phase 0 §A.7.
+- **Date:** 2026-11-01
+- **Assumptions pending approval:** D-9 (the platform bears payment fees), D-10 (commission reversed exactly; shipping excluded from commission), D-11 (the vendor bears lost-dispute goods value; the platform bears the dispute fee)
+
+All amounts are MYR. They are shown in RM for readability and stored in sen.
+
+## 1. Principles
+
+1. **Customer money is collected once per OrderGroup**, in Stripe test mode on the platform account.
+2. **The internal ledger is the financial record.** Stripe is reconciled against it, not the other way round.
+3. **Vendor payable** for a line is the *pre-discount* goods value minus commission, plus the VendorOrder's shipping. Promotions and points are platform-funded in v2.
+4. **Commission** is the frozen basis-point rate × the line's pre-discount goods value, rounded half-even per line. It excludes shipping (D-10).
+5. **Every posting is a balanced transaction**, unique per (type, reference). Corrections are new transactions.
+6. **Loyalty points are not a ledger liability** in v2. Their money value is recognised as `loyalty_expense` when redeemed. This simplification is documented and acceptable for a showcase: unredeemed points have no cash value.
+
+## 2. Accounts
+
+| Account | Kind | Increases with | Meaning |
+|---|---|---|---|
+| `platform:psp_clearing` | Asset | Debit | Money held for the platform at Stripe |
+| `platform:commission_revenue` | Revenue | Credit | Commission earned |
+| `platform:psp_fees` | Expense | Debit | Stripe processing fees (D-9) |
+| `platform:promo_expense` | Expense | Debit | Platform-funded discounts |
+| `platform:loyalty_expense` | Expense | Debit | Points redeemed at checkout |
+| `platform:dispute_holding` | Asset | Debit | Funds withdrawn by Stripe pending a dispute |
+| `platform:dispute_losses` | Expense | Debit | Dispute fees and platform-borne losses |
+| `vendor:{id}:payable_pending` | Liability | Credit | Owed, not yet withdrawable (before completion) |
+| `vendor:{id}:payable_available` | Liability | Credit | Withdrawable at the next payout |
+| `vendor:{id}:payable_held` | Liability | Credit | Frozen by an open dispute |
+| `vendor:{id}:receivable` | Asset | Debit | Vendor owes the platform (refund or dispute after payout) |
+
+## 3. Posting catalogue
+
+| Type | Trigger (event) | Reference | Entries |
+|---|---|---|---|
+| `capture` | `PaymentCaptured` | payment attempt | Dr `psp_clearing` total; Dr `promo_expense` Σ discount; Dr `loyalty_expense` Σ points value; Cr each vendor `payable_pending` (goods − commission + shipping); Cr `commission_revenue` Σ commission |
+| `psp_fee` | `ProviderFeeRecorded` | balance transaction | Dr `psp_fees` / Cr `psp_clearing` |
+| `refund` | `RefundSucceeded` | refund | Cr `psp_clearing` refund amount; Dr `commission_revenue` commission reversed; Cr `promo_expense` discount reversed; Cr `loyalty_expense` points value reversed; Dr vendor payable (pending → available → receivable, in that order) for the balancing amount |
+| `maturity` | `VendorOrderCompleted` | vendor order | Dr `payable_pending` / Cr `payable_available` for that VendorOrder's net remaining payable |
+| `payout` | Payout created | payout | Dr `payable_available` / Cr `psp_clearing` |
+| `receivable_netting` | Payout run (before payout) | payout | Dr `payable_available` / Cr `receivable` (up to the available amount) |
+| `dispute_opened` | `DisputeOpened` | dispute | Dr `dispute_holding` / Cr `psp_clearing` (disputed amount); Dr `dispute_losses` / Cr `psp_clearing` (fee); per allocation, move vendor payable → `payable_held` |
+| `dispute_won` | `DisputeWon` | dispute | Dr `psp_clearing` / Cr `dispute_holding`; per allocation `payable_held` → origin bucket (`pending` if the VendorOrder is not completed, else `available`) |
+| `dispute_lost` | `DisputeLost` | dispute | Per allocation: Dr `payable_held` / Cr `dispute_holding` (D-11; any shortfall moves to Dr `receivable`) |
+
+**Refund balancing amount:** vendor debit = refund amount − commission reversed + discount reversed + points value reversed. It is computed from stored per-line allocations, so it is exact.
+
+## 4. Worked example (an executable test in Phase 5)
+
+**Setup**
+
+- Commission is 10 % for both vendors.
+- Coupon RM 10.00, platform-funded.
+- No points.
+
+| Line | Vendor | Goods | Allocated discount (largest remainder, pro-rata to goods) | Commission |
+|---|---|---|---|---|
+| A1 | A | 40.00 | 4.00 | 4.00 |
+| A2 | A | 20.00 | 2.00 | 2.00 |
+| B1 | B | 40.00 | 4.00 | 4.00 |
+
+Shipping: A RM 8.00, B RM 5.00.
+
+**Charged:** 100.00 + 13.00 − 10.00 = **RM 103.00**
+
+**4.1 Capture**
+
+| Account | Dr | Cr |
+|---|---|---|
+| psp_clearing | 103.00 | |
+| promo_expense | 10.00 | |
+| A:payable_pending (60 − 6 + 8) | | 62.00 |
+| B:payable_pending (40 − 4 + 5) | | 41.00 |
+| commission_revenue | | 10.00 |
+| **Total** | **113.00** | **113.00** |
+
+**4.2 Fee.** Assume a Stripe fee of RM 4.09: Dr psp_fees 4.09 / Cr psp_clearing 4.09. The platform bears it (D-9). Vendor payables are unchanged.
+
+**4.3 Partial refund: A2 returned.** The customer paid 20.00 − 2.00 = **18.00** for A2. Shipping is not refunded because other A lines remain.
+
+| Account | Dr | Cr |
+|---|---|---|
+| psp_clearing | | 18.00 |
+| commission_revenue (A2's commission) | 2.00 | |
+| promo_expense (A2's discount) | | 2.00 |
+| A:payable_pending (18 − 2 + 2 = 18) | 18.00 | |
+| **Total** | **20.00** | **20.00** |
+
+A's pending payable is now 44.00 = (40 − 4) + 8. B is untouched (INV-4).
+
+**4.4 Vendor B cancels before shipping.** The full VendorOrder is refunded, including shipping: 40 − 4 + 5 = **41.00**.
+
+| Account | Dr | Cr |
+|---|---|---|
+| psp_clearing | | 41.00 |
+| commission_revenue | 4.00 | |
+| promo_expense | | 4.00 |
+| B:payable_pending (41 − 4 + 4) | 41.00 | |
+| **Total** | **45.00** | **45.00** |
+
+B's payable is 0.00. Platform result on B is 0: commission and promo expense are both reversed.
+
+**4.5 Maturity.** A's VendorOrder completes: Dr A:payable_pending 44.00 / Cr A:payable_available 44.00.
+
+**4.6 Payout run.** Available 44.00 ≥ minimum 50.00? **No.** A is skipped this week (P-7 minimum), and the balance carries forward. This is a deliberate test of the threshold rule.
+
+**4.7 Goodwill refund after a payout** (separate scenario).
+
+- Vendor A has available 0.00 and has already been paid out.
+- Vendor Finance grants RM 10.00 goodwill on A1. A1's paid amount was 36.00, with commission 4.00 and discount 4.00.
+- Pro-rata reversal, half-even: commission 4.00 × 10/36 = 1.11; discount 1.11.
+- Vendor debit = 10.00 − 1.11 + 1.11 = 10.00. No payable remains, so the debit goes to **receivable**:
+
+| Account | Dr | Cr |
+|---|---|---|
+| psp_clearing | | 10.00 |
+| commission_revenue | 1.11 | |
+| promo_expense | | 1.11 |
+| A:receivable | 10.00 | |
+| **Total** | **11.11** | **11.11** |
+
+At the next payout run, `receivable_netting` recovers it from A's available balance before any payout.
+
+**Refund cap check (INV-5).** A1 refundable = 36.00. After this refund, 26.00 remains.
+
+## 5. Disputes (D-11)
+
+- A dispute is raised on the Stripe charge, so it is per OrderGroup.
+- **Allocation:**
+  - if the dispute reason and evidence identify specific VendorOrders (Finance staff selects them), the amount is allocated to those;
+  - otherwise it is allocated pro-rata to the VendorOrders' remaining captured amounts, by largest remainder.
+- **Opened:**
+  - funds move to `dispute_holding`;
+  - the dispute fee (assume RM 15.00 test value) goes to `dispute_losses`;
+  - each allocation moves from the vendor's pending or available payable to `payable_held`. If the vendor's payable is insufficient (already paid out), the shortfall is recorded but not held, and on loss it becomes receivable.
+- **Won:** the funds return; holds are released to their origin bucket.
+- **Lost:** the held amount is consumed against `dispute_holding`, so the vendor bears the goods value. The fee stays a platform loss.
+- **Guards:**
+  - refunds on a disputed group are blocked;
+  - payouts exclude held balances;
+  - maturity of a VendorOrder with an open dispute allocation waits until the dispute closes.
+
+## 6. Balances and statements
+
+- **Vendor balance by bucket** is Σ credits − Σ debits on that bucket's account. Receivable is Σ debits − Σ credits.
+- The **vendor statement** lists every ledger entry on the vendor's accounts with:
+  - date;
+  - type;
+  - reference (VendorOrder, refund, dispute or payout reference, from transaction metadata);
+  - amount;
+  - running balance per bucket.
+
+  It is exportable to CSV. The statement totals equal the balances (FR-FIN-03).
+- **Platform finance dashboard:**
+  - GMV = Σ captured;
+  - net revenue = commission − promo − loyalty − fees − dispute losses;
+  - refunds;
+  - outstanding payables;
+  - receivables.
+
+## 7. Payout run
+
+1. Scheduled Monday 09:00 MYT, or triggered by Finance staff. Idempotency key `payout-run:{period_end}`, with UNIQUE `period_end`.
+2. For each vendor, under a per-vendor lock:
+   1. net the receivable against available;
+   2. if available ≥ RM 50.00, create `Payout(simulated_paid)` and post `payout`.
+3. Notify vendors.
+4. Concurrency: running the payout twice concurrently gives one run. The second gets a unique violation and returns the existing run.
+
+## 8. Reconciliation
+
+| Level | Frequency | Checks | On failure |
+|---|---|---|---|
+| Internal | Nightly + in tests | Every transaction balances; per group, captured = Σ vendor payable credits + commission − promo − loyalty (at capture); per VendorOrder, Σ refunds ≤ refundable cap; paid groups ⇔ one succeeded attempt; balance projections = entry sums | `reconciliation_exceptions` (category `internal`) and an alert |
+| Provider | Daily, for the previous day (MYT) | Match Stripe balance transactions (charges, refunds, fees, disputes) to attempts, refunds, disputes and fee postings by provider id; compare amount and currency | Exceptions: `missing_locally` (replay from provider), `missing_at_provider`, `amount_mismatch` |
+| Operational | Every 5 min | Attempts in `processing`/`requires_payment_method` > 30 min → re-fetch; refunds `submitted` > 30 min → re-fetch; provider events unprocessed > 5 min → re-dispatch | Escalate after 3 tries |
+
+Finance staff resolve exceptions in Filament with a note. Resolution may trigger a corrective posting through a use case. Every resolution is audit-logged.
+
+## 9. Tests this document requires
+
+- §4 worked example as one end-to-end test with exact amounts.
+- Property tests: random carts (1–5 vendors, 1–6 lines each), random discounts and points, then random sequences of partial refunds, cancellations, disputes and payouts. After every step, check:
+  - all transactions balance;
+  - INV-5 holds;
+  - vendor payable + commission − promo − loyalty reconciles to captured minus refunded;
+  - no balance bucket is negative except via receivable.
+- Concurrency (MySQL):
+  - refund vs maturity on the same VendorOrder;
+  - two payout runs;
+  - duplicated `RefundSucceeded`;
+  - dispute opened while a refund is being requested.
diff --git a/docs/architecture/integration-contracts.md b/docs/architecture/integration-contracts.md
new file mode 100644
index 0000000..b259141
--- /dev/null
+++ b/docs/architecture/integration-contracts.md
@@ -0,0 +1,153 @@
+# Integration Contracts and the API / Frontend Contract Strategy
+
+- **Status:** Draft for owner review (Phase 1). It implements ADR-0018, ADR-0015 and ADR-0010.
+- **Date:** 2026-11-01
+
+Three kinds of contract exist:
+
+1. **Browser ↔ Laravel**: Inertia pages, plus the few JSON endpoints.
+2. **Module ↔ module**: `Contracts` interfaces and integration events.
+3. **Nexo ↔ Stripe**: the payment provider port.
+
+---
+
+## 1. Browser ↔ Laravel
+
+### 1.1 Transport
+
+| Kind | Used for | Format |
+|---|---|---|
+| Inertia page visit | Every page in storefront, account and vendor | Props from `*PageData` objects (ADR-0018) |
+| Inertia form submit | Every mutation from Vue | Form request validation → redirect with flash, or 422 errors bag |
+| Inertia partial reload | Facet changes, cart drawer, dashboard widgets | `only: [...]` prop keys |
+| JSON | `GET /checkout/{reference}/status` (payment polling), `POST /webhooks/stripe` | `application/json`; errors as `application/problem+json` |
+
+**Not provided:** a public REST API, versioned `/api/v1` and a mobile API. If one is introduced, a new ADR defines OpenAPI-first contracts.
+
+### 1.2 Shape rules (normative)
+
+| Data | Wire format | Example |
+|---|---|---|
+| Money | `{ amount: int, currency: "MYR" }` (minor units) | `{ "amount": 12990, "currency": "MYR" }` = RM 129.90 |
+| Rate | `{ bps: int }` | `{ "bps": 1000 }` |
+| Date-time | ISO 8601 UTC with `Z` | `"2026-11-01T03:15:00Z"` |
+| Date | `YYYY-MM-DD` | — |
+| Enum | String literal; label via i18n key `enums.<Enum>.<value>` | `"awaiting_fulfilment"` |
+| Identifier | `publicId` (ULID) or `reference`; never `id` | `"01JC…"` |
+| Optional values | Key always present; `null` when absent | — |
+| Collections | `Paginated<T>` or `CursorPaginated<T>` | ADR-0018 §4 |
+| Permissions | `can: { cancel: boolean, refund: boolean, … }` computed server-side | — |
+| Allowed actions | `allowedTransitions: VendorOrderStatus[]` | — |
+
+### 1.3 Error contract
+
+| Situation | HTTP | Inertia behaviour | Code examples |
+|---|---|---|---|
+| Validation | 422 | `errors` bag per field | — |
+| Domain rule violation | 409 or 422 | Redirect back with flash `{ type: "error", code, message }` | `stock.insufficient`, `checkout.price_changed`, `order.transition_conflict`, `refund.exceeds_refundable`, `promotion.limit_reached`, `idempotency.key_reused` |
+| Not found or not owned | 404 | Error page | — |
+| Forbidden | 403 | Error page (no detail) | — |
+| Rate limited | 429 | Flash with retry hint | — |
+| Server error | 500 | Generic error page, correlation id shown | — |
+
+Domain error codes live in a PHP enum `ErrorCode`. They are exported to TypeScript and have i18n messages. The message text is never built from exception messages.
+
+### 1.4 Checkout-specific contract
+
+1. The checkout page props include `checkoutKey` (UUID), `summary` (per-vendor groups, totals) and `summaryHash`. The hash is a server HMAC of the priced summary.
+2. `POST /checkout` sends `{ checkoutKey, addressId, shippingSelections, promotionCode?, pointsToRedeem, summaryHash }`. It receives either:
+   - a redirect to `/checkout/{reference}/pay`, with props `{ clientSecret, publishableKey, expiresAt, total }`; or
+   - a 409 `checkout.price_changed`, with a fresh summary.
+3. `GET /checkout/{reference}/status` returns `{ status: "pending_payment" | "paid" | "expired" | "cancelled", attempt: { status, failureCode } }`. The client polls every 2 seconds for up to 60 seconds, then shows "We're still confirming; you'll get an email".
+
+### 1.5 Contract verification
+
+- Generated `types/generated.d.ts` with a CI diff check.
+- `vue-tsc --noEmit`.
+- `assertInertia` tests for component name and prop structure on every page, using one dataset per page.
+- Error codes: an enum ↔ i18n key coverage test.
+
+---
+
+## 2. Module ↔ module
+
+### 2.1 Synchronous contracts (initial list; signatures are indicative)
+
+| Interface (owner) | Methods | Used by |
+|---|---|---|
+| `Identity\Contracts\Customers` | `get(customerId): CustomerSummary`, `addressSnapshot(addressId, customerId): AddressSnapshot` | Ordering, Notifications, Loyalty |
+| `Vendors\Contracts\VendorDirectory` | `get(vendorId): VendorSummary`, `canSell(vendorId): bool`, `memberContext(userId): ?VendorContext` | Catalogue, Ordering, Search, Inventory, Shipping |
+| `Catalogue\Contracts\Sellables` | `snapshot(variantIds): VariantSnapshot[]` (price, title, options, vendorId, categoryId, sellable) | Ordering, Promotions, Inventory |
+| `Inventory\Contracts\StockReservations` | `reserve(groupId, lines[], ttl)`, `consume(groupId)`, `release(groupId, reason)`, `restockCancelled(lineId, qty)`, `available(variantIds)` | Ordering |
+| `Shipping\Contracts\ShippingQuotes` | `quote(vendorId, zoneCode, goods): Money\|Unavailable` | Ordering |
+| `Promotions\Contracts\PromotionEngine` | `evaluate(cartSnapshot, code?): Allocation`, `hold(groupId, …)`, `confirm(groupId)`, `release(groupId)` | Ordering |
+| `Loyalty\Contracts\Points` | `balance(customerId)`, `hold(groupId, points)`, `confirm(groupId)`, `release(groupId)` | Ordering |
+| `Finance\Contracts\CommissionRates` | `resolve(vendorId, categoryId, at): BasisPoints` | Ordering |
+| `Payments\Contracts\PaymentAttempts` | `create(groupRef, amount, idempotencyKey): AttemptResult`, `status(groupId): AttemptStatus`, `cancelActive(groupId)` | Ordering |
+| `Payments\Contracts\Refunds` | `request(vendorOrderRef, lines[], amount, initiator, idempotencyKey): RefundRef` | Ordering |
+| `Payments\Contracts\OrderPayments` *(port owned by Payments, implemented by Ordering)* | `markPaid(groupId, attemptRef): void` | Payments |
+| `Ordering\Contracts\PurchaseVerification` | `receivedLine(customerId, lineRef): ?PurchasedLine` | Engagement |
+
+Each interface has a contract test suite in `tests/Contracts/` that runs against the real implementation, and against the in-memory fake where one exists.
+
+### 2.2 Integration events
+
+- The event list and subscribers are in `dependency-rules.md` §3.
+- Every event payload is a `final readonly` DTO with `eventId` (ULID), `occurredAt` and `version`.
+- A breaking payload change creates a new event version. Consumers handle both versions until all outbox rows of the old version are drained.
+
+---
+
+## 3. Nexo ↔ Stripe (payment provider port)
+
+### 3.1 Port (`Payments\Contracts\PaymentProvider`, implemented in `Payments\Infrastructure`)
+
+| Operation | Stripe call | Idempotency key |
+|---|---|---|
+| `createPayment(amount, currency, metadata)` | `paymentIntents.create` (automatic payment methods restricted to `card`) | `attempt:{attempt_id}` |
+| `retrievePayment(providerId)` | `paymentIntents.retrieve` | — |
+| `cancelPayment(providerId)` | `paymentIntents.cancel` | `attempt-cancel:{attempt_id}` |
+| `refund(providerPaymentId, amount, metadata)` | `refunds.create` | `refund:{refund_id}` |
+| `retrieveRefund(providerRefundId)` | `refunds.retrieve` | — |
+| `balanceTransactions(window)` | `balanceTransactions.list` | — |
+| `verifyWebhook(payload, signature)` | `Webhook::constructEvent` (tolerance 300 s) | — |
+
+### 3.2 Webhook events consumed
+
+| Event | Effect |
+|---|---|
+| `payment_intent.succeeded` | Payment success path (ADR-0015 §6) |
+| `payment_intent.payment_failed` | Attempt failed (retry allowed) |
+| `payment_intent.processing`, `payment_intent.requires_action` | Record the state (affects the sweeper) |
+| `payment_intent.canceled` | Attempt cancelled |
+| `charge.refunded`, `refund.updated`, `refund.failed` | Refund resolution |
+| `charge.dispute.created`, `charge.dispute.closed` | Dispute lifecycle |
+| `balance.available` *(informational)* | Ignored in v2 |
+
+Unknown event types are stored and marked processed with no effect. They are counted in health metrics.
+
+### 3.3 Fake provider (tests and CI)
+
+`FakePaymentProvider` is deterministic and scriptable:
+
+- `willDecline(code)`;
+- `willTimeoutOnce()`;
+- `willSucceedAfter(ms)`;
+- `deliverEventTwice()`;
+- `deliverOutOfOrder()`;
+- `failRefund(code)`;
+- `openDispute(amount)`.
+
+It emits signed events through the same webhook controller, so the ingestion path is tested end to end.
+
+### 3.4 Verification against real Stripe (D-14)
+
+A manual or nightly suite runs against Stripe test mode, using the Stripe CLI to forward webhooks. It covers:
+
+- card success;
+- decline;
+- 3-D Secure;
+- refund;
+- a dispute test card.
+
+It is not a PR gate, because it needs network access and secrets.
diff --git a/docs/architecture/lifecycles/checkout-and-payment.md b/docs/architecture/lifecycles/checkout-and-payment.md
new file mode 100644
index 0000000..3934b81
--- /dev/null
+++ b/docs/architecture/lifecycles/checkout-and-payment.md
@@ -0,0 +1,97 @@
+# Checkout and Payment Lifecycle
+
+- **Status:** Draft for owner review (Phase 1). It implements ADR-0015, ADR-0012 and ADR-0014.
+- **Date:** 2026-11-01
+
+## 1. State machines
+
+### OrderGroup
+
+```
+             place (TX1)
+   (cart) ───────────────► pending_payment ──── payment captured ────► paid
+                               │   │
+          customer abandons ◄──┘   └── TTL elapsed, no live payment ──► expired
+          (explicit cancel)                     (sweeper)
+                 ▼
+             cancelled
+```
+
+### PaymentAttempt
+
+```
+ created ──► requires_payment_method ──► requires_action (3DS) ──► processing ──► succeeded
+    │                 │   │                      │                       │
+    ▼                 │   └──────────────────────┴──────► failed ◄───────┘
+ creation_failed      └──────────────────────────────────► cancelled (superseded or group expired)
+```
+
+- At most one attempt per group is in a non-terminal state.
+- Terminal states are `succeeded`, `failed`, `cancelled` and `creation_failed`.
+
+## 2. Sequence: happy path
+
+```
+Browser            Ordering                  Inventory/Promo/Loyalty   Payments                 Stripe
+  │ POST /checkout   │                              │                     │                        │
+  │ (checkoutKey,    │ re-price; compare hash        │                     │                        │
+  │  summaryHash) ──►│ BEGIN                         │                     │                        │
+  │                  │  insert group+vendor orders   │                     │                        │
+  │                  │  reserve (sorted) ───────────►│ conditional UPDATEs │                        │
+  │                  │  hold promo / points ────────►│                     │                        │
+  │                  │  outbox CheckoutPlaced        │                     │                        │
+  │                  │ COMMIT                        │                     │                        │
+  │                  │ create attempt ──────────────────────────────────►│ insert attempt         │
+  │                  │                               │                     │ create PI (idem key) ─►│
+  │◄─ redirect /pay (clientSecret, expiresAt) ───────────────────────────────────────────────────┤
+  │ confirmPayment (Stripe.js, 3DS) ─────────────────────────────────────────────────────────────►│
+  │ poll /status every 2 s                                                                        │
+  │                                                                     │◄── webhook succeeded ──┤
+  │                                                                     │ verify sig; insert event (unique); 200
+  │                                                                     │ job: lock group→attempt; retrieve PI
+  │                  │◄─ OrderPayments::markPaid (same TX) ─────────────│ BEGIN … COMMIT         │
+  │                  │  group paid; VOs awaiting_fulfilment; consume; confirm promo/points; outbox
+  │◄─ status: paid ──┤                                                                            │
+```
+
+## 3. Scenario matrix (brief §10 and §11)
+
+Each row becomes a named Pest test in Phase 5. **F** means it runs with the fake provider in CI. **S** means it is a Stripe test-mode smoke test. **C** means a MySQL parallel concurrency test.
+
+| # | Scenario | Expected outcome | Recovery mechanism | Test |
+|---|---|---|---|---|
+| P1 | Payment succeeds | Group `paid`; one VendorOrder per vendor `awaiting_fulfilment`; stock consumed; promo and points confirmed; capture posted; one email to the customer, one notification per vendor | — | F, S |
+| P2 | Payment declined | Attempt `failed` with decline code; group stays `pending_payment`; reservation kept; the customer may retry until `expires_at` | Retry creates a new attempt (the previous one is already terminal) | F, S |
+| P3 | Payment remains pending (`processing`/`requires_action`) | Group `pending_payment`; the sweeper extends the reservation once (≤ 15 min); then the attempt is cancelled at the provider and the group expires | Stuck-attempt sweep re-fetches after 30 min | F |
+| P4 | Webhook arrives late (after `expires_at`) | Late-success path: re-reserve; if all lines are available → paid; otherwise paid + affected VendorOrders cancelled with `stock_unavailable_after_payment` and refunded | Reconciliation catches a success with no webhook at all | F |
+| P5 | Webhook delivered multiple times (sequentially or concurrently) | Exactly one effect: second insert hits UNIQUE (provider, event_id) → 200 no-op; a different event id for the same success finds the attempt already `succeeded` → no-op | Unique keys | F, C |
+| P6 | Webhook signature invalid | 400; nothing stored; security log + metric | — | F |
+| P7 | Customer closes the browser during payment | No effect on outcome; the webhook completes the order; the confirmation email is sent | — | F |
+| P8 | Checkout retried (double click, refresh, back button) | Same `checkoutKey` → the same OrderGroup and active attempt are returned (idempotency store replay) | UNIQUE (customer_id, idempotency_key) | F, C |
+| P9 | Idempotency key reused with different parameters | 422 `idempotency.key_reused`; nothing created | Request-hash comparison | F |
+| P10 | Price changed between review and placement | 409 `checkout.price_changed` with the fresh summary; nothing reserved or charged | — | F |
+| P11 | Insufficient stock at placement | TX1 rolls back entirely; short lines are reported; nothing charged | — | F, C |
+| P12 | Payment provider unavailable at attempt creation | Attempt `creation_failed`; the group remains `pending_payment` with reservations; the customer sees a retryable error | Retry; the provider idempotency key guards against a hidden success | F |
+| P13 | Provider unavailable during webhook processing (re-fetch fails) | Job fails and retries with backoff; the event stays unprocessed | Unprocessed-event sweep after 5 min | F |
+| P14 | Application crashes after TX1 commit, before attempt creation | Group `pending_payment` without an attempt; the pay page creates the attempt on load (idempotent); if the customer never returns, the group expires and stock is released | Sweeper | F |
+| P15 | Application crashes mid-success-processing | The transaction rolls back entirely; the event is still unprocessed; the retry succeeds once | Queue retry and the unprocessed-event sweep | F |
+| P16 | Amount or currency mismatch between provider and attempt | Not marked paid; `reconciliation_exception` (amount_mismatch); Finance alerted | Manual resolution | F |
+| P17 | Customer starts a new attempt while one is `requires_action` | The previous attempt is cancelled at the provider first; if the cancel fails because it already succeeded → process success and return "already paid" | Group row lock serialises attempt changes | F, C |
+| P18 | Success webhook races the expiry sweeper | Both lock the group row; whichever is first: if the sweeper wins it cancels the PI (the cancel fails if it already succeeded → it switches to the success path); if the webhook wins the group is `paid` and the sweeper skips it | Row locks and status guards | C |
+| P19 | Refund partially succeeds (a cancellation affecting several VendorOrders, one refund fails) | Each refund is independent: succeeded ones are posted; the failed one is `failed` with code, `refund_committed` is decremented, and it appears in the Finance queue | Retry with the same refund idempotency key | F |
+| P20 | Repeated refund requests (double click, two staff) | One refund committed; the second fails the guarded counter with 422 `refund.exceeds_refundable`, or replays the idempotent response | Guarded counters | F, C |
+| P21 | Refund call times out | Refund stays `submitted`; resolved by `refund.updated` or the refund sweep; never re-sent with a new key | Provider idempotency key | F |
+
+## 4. Customer-visible states
+
+| Internal state | Customer sees |
+|---|---|
+| group `pending_payment`, attempt `requires_payment_method` | "Complete your payment" + reservation countdown |
+| attempt `requires_action`/`processing` | "Confirming your payment…" |
+| attempt `failed` | "Your card was declined (reason). Try another card." + countdown |
+| attempt `creation_failed` | "Payment service is temporarily unavailable. Try again." |
+| group `paid` | Confirmation page |
+| group `expired` | "Your reservation expired and you were not charged. Your cart is still saved." |
+| paid + VendorOrder cancelled `stock_unavailable_after_payment` | Confirmation + notice "One item couldn't be fulfilled; you've been refunded RM x" |
+
+"Pending" never looks like "failed" (design principle carried over from the 2026-08-30 vision).
diff --git a/docs/architecture/lifecycles/inventory.md b/docs/architecture/lifecycles/inventory.md
new file mode 100644
index 0000000..08a29a5
--- /dev/null
+++ b/docs/architecture/lifecycles/inventory.md
@@ -0,0 +1,65 @@
+# Inventory Lifecycle
+
+- **Status:** Draft for owner review (Phase 1). It implements ADR-0014.
+- **Date:** 2026-11-01
+
+## 1. Quantities
+
+```
+on_hand   = units physically held by the vendor (Σ movements.delta_on_hand)
+reserved  = units held for unpaid OrderGroups (Σ active reservation qty)
+available = on_hand − reserved            (never stored, never negative)
+```
+
+## 2. Reservation state machine
+
+```
+           reserve (checkout TX)
+               │
+               ▼
+            active ──── payment captured ───────► consumed      (on_hand −q, reserved −q, movement: sale)
+               │  └──── group expired (sweeper) ─► expired      (reserved −q, movement: release)
+               └─────── group cancelled/failed ──► released     (reserved −q, movement: release)
+   extension: active.expires_at += ≤ 15 min, once, if payment processing (extended_at set)
+```
+
+**Guard.** Every transition is `UPDATE stock_reservations SET status = :to WHERE id = :id AND status = 'active'`. Only when that update affects 1 row are the `stock_levels` change and the movement applied, in the same transaction.
+
+## 3. Movement types
+
+| Type | Δ on_hand | Δ reserved | Reference |
+|---|---|---|---|
+| `receipt` | +q | 0 | adjustment id |
+| `adjustment` (damage, correction, with reason) | ±q | 0 | adjustment id |
+| `count` (absolute set) | target − current | 0 | adjustment id |
+| `reservation` | 0 | +q | reservation id |
+| `release` | 0 | −q | reservation id |
+| `sale` | −q | −q | reservation id |
+| `cancellation_restock` | +q | 0 | vendor order line id |
+| `return_restock` | +q (resellable qty) | 0 | return request line id |
+
+UNIQUE (type, reference_type, reference_id, variant_id) makes each logical change apply at most once.
+
+## 4. Scenario matrix (brief §10 and §11, inventory)
+
+| # | Scenario | Expected outcome | Mechanism | Test |
+|---|---|---|---|---|
+| I1 | Insufficient stock | Checkout fails as a whole; short lines named; nothing reserved | Conditional update affects 0 rows → rollback | F |
+| I2 | Two customers buy the last unit concurrently | Exactly one OrderGroup created; the other gets I1 | Conditional update (row lock in InnoDB) | C (N=20 parallel processes) |
+| I3 | Concurrent reservations over overlapping variants | All complete or fail cleanly; no deadlock surfaces to the user | Ascending `variant_id` lock order; one automatic retry on deadlock (1213) | C |
+| I4 | Reservation expires | Released by the sweeper; stock available again; group `expired`; promo and points released | Ordering `ExpireUnpaidGroups` | F (frozen clock) |
+| I5 | Payment fails after reservation | Reservation stays active until TTL so the customer can retry; then I4 | — | F |
+| I6 | Reservation release fails (crash mid-release) | The transaction rolls back; the reservation is still `active`; the next sweeper run releases it | Idempotent sweeper | F |
+| I7 | Inventory adjustment conflicts (two members count stock simultaneously) | The first succeeds; the second gets 409 with the current value | `version` compare-and-swap | C |
+| I8 | Vendor reduces on-hand below reserved | Rejected with "N units are reserved by unpaid checkouts" | Guarded update `on_hand + d >= reserved` | F |
+| I9 | Vendor cancels an order | Before payment: N/A (vendors never see unpaid orders). After payment, before shipping: `cancellation_restock` +q; refund triggered | VendorOrder cancel use case | F |
+| I10 | Stock movement duplicated (event replay, double job) | The second insert violates the unique key → no-op; quantities unchanged | Unique movement key + reservation status guard | F, C |
+| I11 | Payment succeeds after the reservation expired and stock was resold | Late-success path (checkout P4): re-reserve fails → affected VendorOrder cancelled and refunded | ADR-0015 §7 | F |
+| I12 | Return received | `return_restock` only for resellable qty | Vendor action | F |
+| I13 | Reconciliation | Nightly: `reserved = Σ active`, `on_hand = Σ movements`; a mismatch raises an exception (never auto-fixed) | Reconciliation job | F |
+
+## 5. What vendors see
+
+- **Per variant:** on-hand, reserved ("held in unpaid checkouts"), available, low-stock badge.
+- **Movement history**, filterable by type, with links to orders and returns.
+- **Conflict messages** name the current values. They never show a bare "error".
diff --git a/docs/architecture/lifecycles/orders-fulfilment-and-returns.md b/docs/architecture/lifecycles/orders-fulfilment-and-returns.md
new file mode 100644
index 0000000..961cea2
--- /dev/null
+++ b/docs/architecture/lifecycles/orders-fulfilment-and-returns.md
@@ -0,0 +1,89 @@
+# Orders, Fulfilment, Returns and Refunds Lifecycle
+
+- **Status:** Draft for owner review (Phase 1). It implements ADR-0012, ADR-0015 §9 and ADR-0016.
+- **Date:** 2026-11-01
+
+## 1. VendorOrder
+
+```
+pending_payment ──(group paid)──► awaiting_fulfilment ──► processing ──► shipped ──► delivered ──► completed
+      │                                │                    │                          │
+      └─(group expired/cancelled)─► voided                  │                          └─ return window (7 d) elapsed,
+                                       └────► cancelled ◄───┘                             no open return/dispute
+```
+
+| Transition | Actor | Preconditions | Side effects (same TX unless noted) |
+|---|---|---|---|
+| → `awaiting_fulfilment` | System | Group paid | Stock consumed; `refundable_cap_minor` set; outbox `VendorOrderPaid` |
+| → `voided` | System | Group expired or cancelled | Reservations released |
+| → `processing` | Vendor (`orders.fulfil`) | — | History |
+| → `shipped` | Vendor (`orders.fulfil`) | Carrier + tracking | Shipment row; outbox (customer notified); `delivered` auto-deadline = +10 d |
+| → `delivered` | Vendor, customer, or system at the deadline | — | `return_window_ends_at` = +7 d |
+| → `completed` | System (hourly) | Window ended; no open return; no open dispute allocation | Outbox `VendorOrderCompleted` → Finance maturity, Loyalty award, review prompt |
+| → `cancelled` | Customer (from `awaiting_fulfilment` only), vendor (`orders.cancel`, before `shipped`), platform Operations | Reason required | `cancellation_restock` for consumed stock; full refund of the VendorOrder (goods + shipping, net of allocations) via Payments; outbox |
+
+**Concurrency rule.** Each transition is `UPDATE … WHERE id = ? AND status = :from`. The loser gets 409 `order.transition_conflict` with the current status and the actor who changed it.
+
+## 2. OrderGroup (customer view, derived)
+
+| Derived label | Rule |
+|---|---|
+| Processing | Any VendorOrder in `awaiting_fulfilment`/`processing` |
+| Partially shipped | Some shipped or delivered, some not |
+| Delivered | All non-cancelled VendorOrders delivered or completed |
+| Partially refunded / Refunded | Σ succeeded refunds > 0 / = Σ captured |
+| Cancelled | All VendorOrders cancelled |
+
+## 3. ReturnRequest
+
+```
+requested ──(vendor approves)──► approved ──(vendor marks received)──► received ──(refund succeeded)──► closed
+    │   └──(vendor rejects)──► rejected ──(customer escalates ≤ 3 d)──► escalated
+    └──(no vendor response 3 d)──────────────────────────────────────► escalated
+escalated ──(Operations upholds rejection)──► rejected (final)
+escalated ──(Operations overrides)──► approved
+```
+
+| Rule | Detail |
+|---|---|
+| Eligibility | VendorOrder `delivered`; now ≤ `return_window_ends_at`; qty ≤ purchased − already returned |
+| Effect on completion | An open return blocks `completed` (and so blocks payable maturity) |
+| Receipt | `received_qty`, `resellable_qty` per line → `return_restock` for resellable units; refund created for received units |
+| Not-received claim (S) | Shipped past deadline + 5 d: the customer opens a claim; Operations decides; refund without restock |
+
+## 4. Refund
+
+```
+requested ──► approved ──► submitted ──► succeeded
+                               └───────► failed  (refund_committed decremented; Finance queue)
+```
+
+| Initiator | Starts at | Approval |
+|---|---|---|
+| System (cancellation, return received, stock unavailable after payment) | `approved` | Implicit |
+| Vendor Owner/Finance goodwill | `approved` | Vendor's own decision; capped at the refundable remainder |
+| Platform Finance override | `approved` | Staff decision; audit |
+| (Customer) | — | Customers never create refunds directly; they create returns or cancellations |
+
+`requested` exists for future approval workflows. In v2 all initiators are pre-authorised, so refunds start at `approved`.
+
+**Amount computation** (per line, from stored allocations):
+
+- **Full line:** goods − allocated discount − allocated points value. Shipping is added only when the refund makes the VendorOrder fully refunded.
+- **Partial quantity:** that share of each stored allocation, using largest remainder across the units.
+- **Goodwill amount:** pro-rata reversal of commission, discount and points against the line's paid amount (financial-model §4.7).
+
+## 5. Scenario matrix (orders and refunds)
+
+| # | Scenario | Expected outcome | Test |
+|---|---|---|---|
+| O1 | Two members transition the same VendorOrder at once | One succeeds; the other gets 409 | C |
+| O2 | Customer cancels while the vendor moves it to processing | Exactly one wins; if processing wins, the customer sees "being prepared; use returns" | C |
+| O3 | Vendor cancels one of three VendorOrders | Refund for that VendorOrder only; siblings' state and ledger unchanged (INV-4) | F |
+| O4 | Return of 1 of 2 units | Refund = one unit's share of stored allocations; commission reversed exactly | F |
+| O5 | Two refund requests race on the last refundable amount | One commits; the other fails `refund.exceeds_refundable` (INV-5) | C |
+| O6 | Refund after the VendorOrder completed and was paid out | Vendor debit to receivable; netted at the next payout (financial-model §4.7) | F |
+| O7 | Refund requested while a dispute is open | Rejected `refund.dispute_open` | F |
+| O8 | Return open when the window ends | `completed` waits until the return closes | F |
+| O9 | Auto-deliver and auto-complete jobs run twice | Idempotent: guarded transitions | F |
+| O10 | Vendor suspended with open orders | Can still fulfil, cancel and refund existing orders; receives no new ones | F |
diff --git a/docs/architecture/marketplace-migration.md b/docs/architecture/marketplace-migration.md
index 52caac6..2a30b07 100644
--- a/docs/architecture/marketplace-migration.md
+++ b/docs/architecture/marketplace-migration.md
@@ -1,5 +1,7 @@
 # Marketplace Migration Plan
 
+> **Superseded 2026-11-01** by [ADR-0007](../architecture/adr/0007-product-positioning-currency-and-locales.md) (owner decision D-4) and the Nexo 2.0 product documents: [product-requirements.md](../product/product-requirements.md), [functional-requirements.md](../product/functional-requirements.md). Kept for history only; do not implement from this file.
+
 **Status:** Draft 2026-08-30
 **Tracks:** the pivot from multi-tenant SaaS (isolated stores on subdomains) to a single
 multi-vendor marketplace. See [../product/vision.md](../product/vision.md).
diff --git a/docs/architecture/security-model.md b/docs/architecture/security-model.md
new file mode 100644
index 0000000..ec0377f
--- /dev/null
+++ b/docs/architecture/security-model.md
@@ -0,0 +1,120 @@
+# Security Model: Roles, Permissions and Isolation
+
+- **Status:** Draft for owner review (Phase 1). It implements ADR-0011.
+- **Date:** 2026-11-01
+
+## 1. Principals
+
+| Principal | How established | Surface |
+|---|---|---|
+| Visitor | No session user | Storefront (read), guest cart |
+| Customer | Authenticated user without `platform_role` | Storefront, account |
+| Vendor member | Customer with an active `vendor_members` row; `VendorContext` resolved per request | `/vendor` |
+| Platform staff | User with `platform_role` and confirmed 2FA | `/admin` (Filament) |
+| System | Scheduler, queue jobs, webhook processor; recorded as `actor_type = system` | — |
+
+## 2. Permission matrix: vendor roles
+
+✓ means allowed. Ownership (`resource.vendor_id = context.vendor_id`) is always required in addition to the permission.
+
+| Permission | Owner | Manager | Fulfilment | Finance | Support |
+|---|---|---|---|---|---|
+| `vendor.dashboard.view` | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `vendor.products.view` | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `vendor.products.manage` (create, edit, activate, import) | ✓ | ✓ | | | |
+| `vendor.inventory.adjust` | ✓ | ✓ | ✓ | | |
+| `vendor.orders.view` | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `vendor.orders.fulfil` (processing, shipped, delivered) | ✓ | ✓ | ✓ | | |
+| `vendor.orders.cancel` | ✓ | ✓ | | | |
+| `vendor.returns.decide` | ✓ | ✓ | | | ✓ |
+| `vendor.returns.receive` | ✓ | ✓ | ✓ | | |
+| `vendor.refunds.goodwill` (capped at the refundable remainder) | ✓ | | | ✓ | |
+| `vendor.finance.view` (balances, statement, payouts) | ✓ | | | ✓ | |
+| `vendor.reviews.reply` | ✓ | ✓ | | | ✓ |
+| `vendor.store.manage` (profile, shipping rates) | ✓ | ✓ | | | |
+| `vendor.team.manage` | ✓ | | | | |
+
+**Suspended vendor overlay** (`vendor-domain-design.md` §8). For a suspended vendor:
+
+- `products.manage` is denied;
+- new orders cannot arrive, because the vendor's products are not sellable;
+- `orders.fulfil`, `orders.view`, `finance.view` and `returns.*` stay allowed.
+
+A `pending` vendor can manage its profile, shipping and draft products, but cannot activate them.
+
+## 3. Permission matrix: platform roles
+
+| Permission | Admin | Operations | Finance | Support |
+|---|---|---|---|---|
+| `platform.staff.manage` | ✓ | | | |
+| `platform.impersonate` (customers and vendor members only) | ✓ | | | |
+| `platform.vendors.review` (applications, approve, suspend, reinstate) | ✓ | ✓ | | |
+| `platform.catalogue.manage` (categories, attributes) | ✓ | ✓ | | |
+| `platform.catalogue.moderate` (block or unblock products, hide reviews) | ✓ | ✓ | | |
+| `platform.orders.view` | ✓ | ✓ | ✓ | ✓ |
+| `platform.orders.intervene` (cancel a VendorOrder, override returns) | ✓ | ✓ | | |
+| `platform.refunds.override` (create or retry refunds) | ✓ | | ✓ | |
+| `platform.disputes.manage` | ✓ | | ✓ | |
+| `platform.finance.view` (ledger, balances, dashboards) | ✓ | | ✓ | |
+| `platform.finance.commission` | ✓ | | ✓ | |
+| `platform.finance.payouts` (trigger run) | ✓ | | ✓ | |
+| `platform.finance.reconcile` (resolve exceptions) | ✓ | | ✓ | |
+| `platform.promotions.manage` | ✓ | ✓ | | |
+| `platform.loyalty.manage` (rates, manual adjustment) | ✓ | | ✓ | |
+| `platform.customers.view` | ✓ | ✓ | ✓ | ✓ |
+| `platform.audit.view` | ✓ | | ✓ | |
+| `platform.health.view` (outbox, jobs, webhooks; retry dead letters) | ✓ | ✓ | | |
+
+**Separation of duties.** Finance cannot change catalogue, and Operations cannot move money. Only Admin holds both, and every Admin action is audit-logged.
+
+## 4. Customer rules
+
+- A customer can access only their own carts, orders, returns, reviews, wishlist, follows, points and addresses.
+- Order, return and refund URLs use `public_id` or the reference, and are always looked up **scoped to the authenticated customer**. Another customer's reference returns 404.
+- A customer can review only lines they bought and received (INV, FR-REV-01).
+
+## 5. Enforcement points
+
+| Layer | Mechanism |
+|---|---|
+| Routing | Route groups: `storefront` (web), `account` (auth + verified), `vendor` (auth + verified + `vendor.context`), `admin` (Filament panel + 2FA), `webhooks` (signature middleware, CSRF-exempt) |
+| Binding | Vendor routes use scoped bindings: `{vendorOrder}` resolves `where vendor_id = context`. Customer routes resolve `where customer_id = auth id`. |
+| Policies | One policy per aggregate; `before()` never grants a blanket allow, not even for Admin (Admin is granted explicitly per permission) |
+| Use cases | Accept `Actor` (user, role, vendor context, impersonator) and re-check the permission. Use cases may be called from Filament, jobs or controllers, so the check lives in the use case as well as in the controller. |
+| Database | Ownership columns are NOT NULL; foreign keys use RESTRICT |
+| Frontend | Hides unavailable actions using server-computed `can.*` props. This is never relied on for security. |
+
+## 6. Threat-driven controls (summary)
+
+| Threat | Control |
+|---|---|
+| Cross-vendor access (Phase 0 S1) | Fail-closed VendorContext, scoped bindings, isolation suite |
+| IDOR on customer resources | Scoped lookup by public id, plus tests |
+| Price or quantity tampering | Server re-pricing; client totals only compared, never trusted |
+| Forged webhooks | Signature verification with a tolerance window; 400 on failure |
+| Replayed requests | Idempotency keys; unique provider ids |
+| Account takeover | Rate limits; email verification; staff 2FA; session regeneration on login; password rules (min 12, breached-password check via `Password::uncompromised()`) |
+| Privilege escalation through role edits | Roles in code; membership changes only by the Owner via a use case; staff roles only by Admin |
+| Malicious uploads | MIME sniffing, re-encode, size limits, private storage until processed |
+| Information leakage | Generic production errors (`APP_DEBUG=false`); vendors see minimal customer PII (NFR-PRIV-02) |
+| Impersonation abuse | Admin-only, audited, banner, money actions blocked |
+| Secrets exposure | Live-key boot refusal; secret scanning in CI |
+
+## 7. Audit events (INV-19)
+
+These actions are recorded:
+
+- vendor application decisions;
+- vendor lifecycle changes;
+- membership changes;
+- product block and unblock;
+- review hide and unhide;
+- commission changes;
+- refund create, retry and override;
+- dispute outcomes;
+- payout runs;
+- reconciliation resolutions;
+- return overrides;
+- staff create, change and deactivate;
+- impersonation start and stop;
+- loyalty manual adjustments.
diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md
new file mode 100644
index 0000000..f53d79d
--- /dev/null
+++ b/docs/architecture/system-overview.md
@@ -0,0 +1,74 @@
+# System Overview
+
+- **Status:** Draft for owner review (Phase 1)
+- **Date:** 2026-11-01
+
+## 1. Context
+
+```
+                 ┌──────────────┐     card details (Payment Element; never touch Nexo)
+  Customer ─────►│              │◄──────────────────────────────── Stripe.js
+  (browser)      │              │
+  Vendor team ──►│  Nexo        │── PaymentIntents / Refunds (test mode) ──► Stripe
+  (browser)      │  Laravel 13  │◄── signed webhooks ─────────────────────── Stripe
+  Platform ─────►│  monolith    │
+  staff (/admin) │              │── transactional email ────────────────────► SMTP provider
+                 └──────┬───────┘
+                        │
+              MySQL 8.4 · Redis (queue/cache/locks) · object storage for images
+```
+
+## 2. Runtime components
+
+| Component | Role |
+|---|---|
+| Web (PHP-FPM) | Inertia pages for storefront (`/`) and vendor (`/vendor`); Filament (`/admin`); webhook endpoint (`/webhooks/stripe`); payment-status polling (`/checkout/{ref}/status`) |
+| Queue workers | Outbox subscribers, provider-event processing, notifications, search indexing, image processing |
+| Scheduler | Outbox relay (5 s), reservation sweeper (1 min), stuck-attempt/refund sweeps (5 min), delivery auto-confirm and completion (hourly), payout run (weekly), reconciliation (nightly), pruning |
+| MySQL 8.4 | Single schema; source of truth for everything including the ledger |
+| Redis | Queue, cache, rate limiting, scheduler mutexes (demo env) |
+| Object storage | Product, review and store images (local disk in dev, S3-compatible in demo) |
+
+## 3. Code organisation (ADR-0010)
+
+```
+app/
+  Shared/                Money, Clock, PublicId, Outbox, Idempotency, Audit, exceptions
+  Modules/
+    Identity/  Vendors/  Catalogue/  Inventory/  Shipping/  Ordering/
+    Payments/  Finance/  Promotions/  Loyalty/  Engagement/  Search/  Notifications/
+      ├─ Domain/  Application/  Infrastructure/  Http/  Contracts/  Filament/
+resources/js/
+  storefront/  vendor/  shared/ (design-system components, lib/, i18n)
+  types/generated.d.ts   (ADR-0018)
+tests/
+  Unit/  Feature/  Isolation/  Concurrency/  Arch/
+```
+
+## 4. Key flows (detail in `lifecycles/`)
+
+| Flow | Path |
+|---|---|
+| Checkout | Ordering.PlaceCheckout → (TX: OrderGroup + VendorOrders + Inventory.reserve + Promotions.hold + Loyalty.hold + outbox) → Payments.CreateAttempt → provider |
+| Payment | webhook → Payments.provider_events → job → TX: attempt succeeded + Ordering.markGroupPaid (+ Inventory.consume, Promotions.confirm, Loyalty.confirm) + outbox → Finance posts capture; Notifications; Search |
+| Fulfilment | Vendor UI → Ordering transitions → outbox → Notifications; completion → Finance maturity, Loyalty award |
+| Refund | Ordering (cancel/return) or Finance staff → Payments.RequestRefund → provider → webhook → Finance posts refund; Loyalty/Promotions adjust |
+| Payout | Scheduler → Finance.RunPayouts (idempotent) → ledger postings → Notifications |
+
+## 5. Cross-cutting concerns
+
+| Concern | Approach |
+|---|---|
+| AuthN | Laravel session auth (Fortify-style flows built in-app or via starter kit — chosen in Phase 3); staff 2FA |
+| AuthZ | Policies + permission enum + VendorContext (ADR-0011) |
+| Transactions | Use cases own boundaries; no provider calls inside DB transactions (ADR-0015) |
+| Async | Outbox + inbox (ADR-0017) |
+| Idempotency | Unique keys + idempotency store (ADR-0015) |
+| Time | Injected `Clock`; UTC storage; MYT display |
+| Observability | JSON logs with correlation id, health endpoint, admin health page |
+| i18n | Laravel lang JSON as single source; exported to the frontend at build; RTL via logical CSS |
+| Security headers | Middleware; CSP with Vite nonce |
+
+## 6. What is deliberately absent
+
+Microservices, message brokers, CQRS/event sourcing beyond the outbox and ledger, a public REST API, WebSockets, Typesense, Stripe Connect — each with its reason in the relevant ADR or PRD §6.2.
diff --git a/docs/development/README.md b/docs/development/README.md
index 58a4f53..2f4c14c 100644
--- a/docs/development/README.md
+++ b/docs/development/README.md
@@ -20,6 +20,7 @@ is in the repository [`README.md`](../../README.md). Start there.
 
 ## Domain naming note
 
-Per [ADR-0002](../architecture/adr/0002-vendor-is-a-tenant-record.md), the code
-says `tenant` / `Tenant` / `tenant_id` where the product language says
-**vendor**. They are the same concept. A future ADR decides whether to rename.
+Nexo 2.0 uses **Vendor** in code, schema and UI (`vendors`, `vendor_id`), per
+[ADR-0005](../architecture/adr/ADR-0005-vendor-naming.md) (recommended for acceptance in the
+Phase 1 review). ADR-0002's `tenant` naming applied to the legacy SaaS database and is proposed
+to be marked superseded.
diff --git a/docs/discovery/PHASE-0-TECHNICAL-ASSESSMENT.md b/docs/discovery/PHASE-0-TECHNICAL-ASSESSMENT.md
new file mode 100644
index 0000000..afa04a0
--- /dev/null
+++ b/docs/discovery/PHASE-0-TECHNICAL-ASSESSMENT.md
@@ -0,0 +1,1285 @@
+# Nexo 2.0 — Phase 0: Discovery and Technical Assessment
+
+| | |
+|---|---|
+| **Status** | Draft for owner review |
+| **Date** | 2026-11-01 |
+| **Scope** | Read-only assessment of the existing codebase. No application code, configuration, migrations or dependencies were changed. |
+| **Repository assessed** | `AdilAzhari/nexo-ecommerce` → local `C:\laragon\www\modular-ecommerce-system` (its `origin` remote is `Sentients-AI/nexo-ecommerce`) |
+| **Working tree assessed** | Branch `redesign` @ `774d131`, **plus 44 uncommitted files** (33 modified, 11 untracked). `redesign` is 4 commits ahead of / 2 behind `main`. |
+| **Also inspected** | `C:\laragon\www\Nexo` (`Sentients-AI/Nexo`): a separate, earlier restart on Laravel 13 + React 19 (see §16, Q2) |
+
+### How to read this report
+
+Every finding is tagged with:
+
+- **Severity:** Critical / High / Medium / Low / Info.
+- **Kind:**
+  - **Defect:** behaviour is wrong today.
+  - **Risk:** an architectural concern that will cause defects.
+  - **Opportunity:** an improvement, not a fix.
+- **Evidence level:**
+  - **Verified:** executed or observed (tests, type-check, command output).
+  - **Code-confirmed:** traced through source, not executed.
+  - **Documented:** claimed by docs and not verified.
+  - **Assumption:** an inference that still needs confirming.
+
+All paths are relative to the repository root unless stated otherwise.
+
+---
+
+## 1. Executive summary
+
+**What exists.** The repository is a large Laravel 12 + Filament 5 + Vue 3/Inertia 2 application:
+
+- 621 PHP files in `app/` across 29 `app/Domain/*` folders.
+- 109 migrations.
+- 81 Vue single-file components.
+- ~1,314 Pest test cases in 135 files.
+
+It was built as a **multi-tenant SaaS** (one isolated store per subdomain). On 2026-08-30 it was partly re-documented as a **single multi-vendor marketplace** for the Sudan market (`docs/product/*`, ADR-0002..0004). The code still implements the SaaS model. The marketplace pivot exists on paper plus a small WIP on `redesign`, and that WIP takes a direction (a session-scoped "shopping tenant") that contradicts its own ADR-0004.
+
+**The headline.** The codebase *looks* far more sophisticated than it *behaves*. It has DDD folder structure, specifications, guards, value-object IDs, a domain-event table, projections, metrics and an `INVARIANTS.md`. But several load-bearing paths are broken or never wired:
+
+1. **Payments never mark an order as paid** (Critical, code-confirmed).
+   - No production code dispatches `PaymentSucceeded`, so the `MarkOrderPaid` listener never runs.
+   - The webhook success path also calls Stripe's *confirm* API on a PaymentIntent the browser has already confirmed. Stripe rejects that call, and the job then fails and rolls back.
+2. **The domain-event "outbox" is write-only** (Critical, code-confirmed). `DomainEventRecorder::record()` writes to `domain_events`. Nothing ever schedules or dispatches the job that reads it (`DispatchDomainEventsJob`). As a result:
+   - `RefundSucceeded` never reaches `UpdateOrderRefundState` or `ReleaseStockOnRefund`.
+   - `PaymentFailed` never reaches its listeners.
+3. **Inventory arithmetic is internally inconsistent** (Critical, code-confirmed).
+   - Reserving stock subtracts it twice: it decrements `quantity_available` *and* `isAvailable()` subtracts `quantity_reserved` again.
+   - Release and cancel paths ignore `variant_id`, and use three different, contradictory semantics.
+4. **Vendor dashboard has no role authorization** (Critical, code-confirmed).
+   - Any logged-in user whose `tenant_id` matches the store can use `/vendor/*`. Storefront customers get the store's `tenant_id` automatically on registration.
+   - Such a user can set any order to any status (bypassing the state machine), edit products and prices, and adjust stock.
+5. **Staging deploys the `redesign` branch against the production database** (High, documented in the workflow itself). This conflicts directly with the brief's rule never to connect experiments to production.
+6. **The "concurrency/torture" tests do not test concurrency.** They run sequentially on SQLite, where `lockForUpdate()` is a no-op, and their assertions are loose enough to pass with the double-subtraction bug present.
+
+**Assessment.** The *ideas* are mostly sound and worth keeping: integer-cents money, idempotency keys, snapshotted order lines, a state-machine enum, an `OrderGroup` + per-vendor `Order` split (ADR-0004) and context-dependent vendor scoping (ADR-0003). The *implementation* is not a safe base to evolve. The money, inventory and authorization paths need re-implementation against a fresh schema, not patching. This supports the brief's hybrid-rebuild strategy:
+
+- Reuse concepts, enums, value objects, specifications and selected UI pieces as references.
+- Re-implement the transactional core with real tests (MySQL, real concurrency).
+
+**The single most important owner decision (Q1)** is the product context. The ratified docs target the **Sudan market with Stripe + Stripe Connect**. The new brief targets a **portfolio-grade, Lazada/Shopee-style general marketplace (EN/AR/MS)**. Stripe does not support Sudan-based businesses or Connect accounts *(assumption, to verify against Stripe's current country list)*, so the documented V1 money flow cannot work for the documented market. This decision shapes ADR-0005 (payments), currency, demo data and copy.
+
+---
+
+## 2. Repository inventory
+
+### 2.1 Stack (verified from `composer.json`, `package.json`, `composer.lock`)
+
+| Layer | Declared | Notes |
+|---|---|---|
+| PHP | `^8.2` (README says 8.4; CI uses 8.4; local CLI is 8.5.8) | Constraint is looser than reality |
+| Laravel | `^12.0` | |
+| Admin | `filament/filament ^5.3` | Single panel `control-plane` (`app/Providers/Filament/AdminPanelProvider.php`) |
+| Frontend | Vue 3.5, `@inertiajs/vue3 ^2.3`, TypeScript 5.9, Tailwind 4, Vite 7 | `vue-tsc` installed but **not run in CI** |
+| Payments | `laravel/cashier ^16.1` **and** `stripe/stripe-php: "*"` (unpinned) | Cashier used only for the (dormant) subscription feature |
+| Realtime | `laravel/reverb: "*"` (unpinned), laravel-echo, pusher-js | |
+| Search | `laravel/scout ^11.1`, `typesense/typesense-php ^6.0` | |
+| Auth | Sanctum 4, Socialite (Google) | |
+| Misc | `nativephp/electron: "*"`, `amphp/parallel`, `barryvdh/laravel-dompdf`, `fakerphp/faker` (in **require**, not dev) | `nativephp/electron` has no visible use in a web marketplace; unpinned `*` constraints are a supply-chain/reproducibility risk |
+| Quality | Pint, Rector, `carthage-software/mago 1.1.0`, Pest 4, `laravel/boost` | **No PHPStan/Larastan.** Mago is installed but not wired into CI |
+| Composer audit | `config.audit.ignore: GHSA-vvj3-c3rp-c85p` | Ignored advisory must be justified (Q9) |
+
+### 2.2 Top-level layout
+
+```
+app/Application/   UseCases (Checkout, ProcessPayment, RequestRefund) + Request/Response DTOs
+app/Domain/        29 folders (see §4)
+app/Infrastructure/Payment/Stripe/PaymentGatewayService.php   (only infrastructure adapter)
+app/Filament/      ~23 resources, 8 pages, 17 widgets
+app/Http/          36 web controllers, 17 API v1 controllers, 9 middleware, 10 policies
+app/Shared/        Alerting, Metrics, Performance, Specifications, ValueObjects, Domain events, AuditLog
+app/Jobs/          HandleStripeEventJob, ConfirmPaymentIntentJob, DispatchDomainEventsJob
+resources/js/      Pages (49), Components (29), Composables (13), Layouts (3), types (4)
+lang/{en,ar,ms}/ui.php   117 lines each
+tests/             Feature (Api, Domains, Journeys, MultiTenancy, Torture, Web, Filament…), Unit, Browser (3)
+.github/workflows/ ci.yml, pr-checks.yml, format.yml, codeql.yml, deploy.yml, deploy-staging.yml
+```
+
+### 2.3 Documentation inventory and its reliability
+
+| Document | Describes | Reliability |
+|---|---|---|
+| `README.md` | Feature list (≈40 features), SaaS multi-tenancy | **Overstates.** It lists e.g. "Order Processing — full lifecycle (pending → paid → …)", which the payment defect breaks (§7.1). The 2026-08-30 banner admits it is mid-pivot. |
+| `docs/product/{vision,goals,personas,problem-statement,scope}.md` | Sudan-market marketplace, Stripe Connect, V1 success criteria | Coherent, but is *intent*. Contradicted by the new brief on market and audience. Untracked (uncommitted). |
+| `docs/architecture/adr/0002..0004` | Vendor = tenant record; explicit vendor scoping; OrderGroup + per-vendor Order | Status "Accepted" but **not implemented**. ADR-0005 (payments) referenced, never written. Untracked. |
+| `docs/architecture/marketplace-migration.md` | Phases A–G of SaaS → marketplace pivot | Plan only |
+| `INVARIANTS.md` | Invariants, state machines, guards | Partly aspirational. Its own "Known Gaps" section admits incomplete guards and a webhook bug. Claims "Order Pending → Paid via `PaymentSucceeded` event via webhook", which is not wired (§7.1). |
+| `PRODUCTION_READINESS_REVIEW.md`, `DATABASE_SCHEMA.md`, `API.md`, `docs/COMPREHENSIVE_CODEBASE_GUIDE.md`, `docs/DECISIONS.md`, `docs/ARCHITECTURE_DECISIONS.md` | SaaS-era deep dives | Out of date relative to the pivot. Treat as historical. |
+| `docs/REDESIGN_BRIEF.md`, `redesign.md`, `Check.md` | Earlier visual-redesign briefs ("Nile Market" palette) | Superseded by the Nexo 2.0 brief |
+| `CLAUDE.md` (git-ignored) | Agent instructions | Not part of the shared repo |
+
+---
+
+## 3. Current architecture
+
+### 3.1 Runtime shape
+
+```
+Browser (Vue/Inertia SPA)            Filament /control-plane (Livewire)
+   │  Inertia pages  /{locale}/…        │
+   │  JSON  /api/v1/* (session+Sanctum) │
+   ▼                                    ▼
+routes/web.php ─ middleware: locale, tenant.subdomain | tenant.user, auth
+routes/api/v1.php ─ api group + EnsureFrontendRequestsAreStateful + ResolveTenantFromUser
+   │
+Controllers ──(some)──► Application/UseCases ──► Domain/*/Actions ──► Eloquent models
+   │ (48 of ~60 controllers query Eloquent directly)
+   ▼
+MySQL/MariaDB ◄── Context('tenant_id') global TenantScope on 46 models
+Queue: HandleStripeEventJob; Scout→Typesense; Reverb broadcasts; Schedule: 3 commands
+```
+
+### 3.2 Layering in practice
+
+- **Application layer is thin and partial.** Only three use cases exist: `CheckoutUseCase`, `ProcessPaymentUseCase` and `RequestRefundUseCase`. Most behaviour lives in controllers or Filament pages calling models or actions directly.
+- **Domain is not independent of infrastructure.** Domain models are Eloquent models, and actions call `DB::transaction`, `Context`, `config()` and `MetricsRecorder` directly. 11 domain files import `App\Events\*` (broadcast events defined outside the domain). This is normal for Laravel, but it is not the "domain independent of infrastructure" the brief asks for.
+- **Two parallel event mechanisms:**
+  1. Laravel events (`X::dispatch`, auto-discovered listeners in `app/Domain/*/Listeners`, see `bootstrap/app.php`).
+  2. `DomainEventRecorder` → `domain_events` table, which has no consumer (§7.2).
+
+  Which mechanism is used varies per action, and that is the root cause of several defects.
+- **Duplicated actions:**
+  - `Inventory/Actions/ReserveStock` and `ReserveStockAction` are near-identical, but only one filters by variant.
+  - `Order/Actions/CheckoutAction` is used only by tests.
+  - `Payment/Webhooks/HandlePaymentWebhookAction.php` is empty.
+
+### 3.3 Domain dependency graph (code-confirmed, from `use App\Domain\…` imports)
+
+```
+Order    -> Bundle Cart Currency GiftCard Inventory Payment Product Promotion Refund Shipping Tax Tenant User   (14)
+Product  -> Category Inventory Order Question Review Tenant User
+Refund   -> Inventory Order Payment Tenant User
+Payment  -> Order Tenant
+Inventory-> Order Product Tenant User
+Promotion-> Cart Category Order Product Tenant User
+Tenant   -> Product Review Role User
+User     -> Order Role Tenant
+```
+
+**Cycles:**
+
+- Order↔Payment
+- Order↔Inventory
+- Order↔Refund
+- Order↔Product
+- Order↔Promotion
+- Product↔Inventory
+- Tenant↔User
+
+No tooling enforces boundaries: no architecture tests, no deptrac, no PHPStan rules.
+
+---
+
+## 4. Current domain map
+
+| Folder | Files | Scope tag in `docs/product/scope.md` | Observed state |
+|---|---|---|---|
+| Refund | 32 | Core | Rich model, broken event delivery (§7.2), race conditions (§7.5) |
+| Order | 29 | Core | State-machine enum good; bypassed in several places (§7.4) |
+| Inventory | 23 | Core | Arithmetic inconsistent (§7.3) |
+| Product | 22 | Core | Variants, price history, downloads |
+| Payment | 22 | Core | Success path broken (§7.1) |
+| Promotion | 18 | Extended | BOGO/tiered/bundle/flash/code + experiments |
+| User | 15 | Core | Is tenant-scoped (`BelongsToTenant`) |
+| Review, Referral, Loyalty | 13/13/12 | Extended | |
+| Cart | 12 | Core | One cart = one tenant |
+| Chat, Question, GiftCard, Subscription, Bundle, Content, FeatureFlag, Config | 2–9 each | Experimental/Extended | Candidates for retirement |
+| Projections | 7 | — | Refund/order-financial projections + replay; depends on the unconsumed event table |
+| Tenant | 5 | Core ("Vendor") | Subdomain resolution + global scope |
+| Tax, Shipping, Currency, Idempotency, Role, Notification, Category, Shared | 1–7 each | Core/Extended | |
+
+**Key observation.** "Domain" here means *folder*, not *bounded context*. Ownership of state transitions is spread across controllers, Filament pages, listeners and actions. For example, `Order.status` is written from:
+
+- `VendorOrderController::updateStatus`
+- `CancelOrder`
+- `CompensateStockOnCancelAction`
+- `HandleStripeEventJob::handleFailure`
+- `MarkOrderPaid`
+- `RetryOrderFinalizationAction`
+- Filament `ViewOrder`
+
+---
+
+## 5. Current database design
+
+### 5.1 Overview (code-confirmed from `database/migrations/*`)
+
+- 109 migrations. 41 of them alter existing tables, and many are "add_x_to_y" patches. This is a normal history, but it is a strong signal for the brief's fresh-schema decision.
+- Money is stored as **integer cents** (`bigInteger …_cents`). This is good and should be kept. `decimal` is used only for `exchange_rate (10,6)`, tax `rate (5,4)` and metrics.
+- `tenant_id` was retro-fitted to ~45 tables by one migration, `2026_02_07_000002_add_tenant_id_to_tables.php`. It is nullable, with `cascadeOnDelete`.
+
+### 5.2 Integrity findings
+
+| # | Finding | Evidence | Sev / Kind |
+|---|---|---|---|
+| D1 | Deleting a **tenant cascades** to orders, payment intents, refunds, stock movements and every other tenant-owned table. A vendor deletion would destroy financial history. | `add_tenant_id_to_tables.php` (`->cascadeOnDelete()`) | High / Risk |
+| D2 | Deleting a **user cascades** to their orders; deleting a **product cascades** to historical `order_items`. | `create_orders_table.php:18`, `create_order_items_table.php:19` | High / Risk |
+| D3 | `stocks`: unique only on `variant_id`. Product-level stock rows (`variant_id NULL`) have no uniqueness, so duplicates are possible. Lookups use `->first()`, so which row is used is non-deterministic. | `relax_product_id_unique_constraint_on_stocks_table.php` | High / Defect-enabling |
+| D4 | No DB-level guarantee that `quantity_reserved ≤ quantity_available`, or that either is ≥ 0. `unsigned()` exists on MySQL only; tests run on SQLite. | `create_stocks_table.php` | Medium / Risk |
+| D5 | `payment_intents.provider_reference` is neither unique nor indexed, yet it is the webhook lookup key. | `create_payment_intents_table.php` | Medium / Risk |
+| D6 | `stock_movements` has no idempotency key (e.g. unique `(stock_id, type, reference_type, reference_id)`), so duplicated movements are possible. | `create_stock_movements_table.php` | Medium / Risk |
+| D7 | `refunds` has no idempotency key and no unique `external_refund_id`. `payment_intent_id` is a free string (Stripe id), not an FK. | `create_refunds_table.php`, `make_payment_intent_id_nullable_on_refunds.php` | Medium / Risk |
+| D8 | `idempotency_keys.key` is **globally unique** *and* `(key, action)` is unique. Two users choosing the same key collide. | `create_idempotency_keys_table.php` | Low / Defect |
+| D9 | Product `slug` is unique per `(tenant_id, slug)`, but the storefront route `/{locale}/products/{product:slug}` is marketplace-wide. Two vendors with the same slug make the route ambiguous. | `add_tenant_id_to_tables.php:54-55`, `routes/web.php` | Medium / Defect (marketplace) |
+| D10 | Categories are tenant-owned (`(tenant_id, slug)`). A marketplace needs a platform-owned taxonomy. | same | Medium / Model mismatch |
+| D11 | `orders` has no `order_group_id`, `commission_*` or transfer fields. ADR-0004 is unimplemented. | `create_orders_table.php` + later alters | — / Gap |
+
+### 5.3 Implications of a fresh database (brief §3)
+
+**Benefits:**
+
+- Removes ~109 migrations of accreted patches.
+- Allows vendor ownership (`vendor_id`), platform-owned taxonomy, `order_groups`, a ledger, `RESTRICT` FKs on financial tables and CHECK constraints from day one.
+
+**Costs:**
+
+- No continuity with `store.aljebal-albeedos.com`. Its users, vendors, orders and Stripe objects are not migrated.
+- If that site stays live on the old code, it is a separate product. It must keep its own database, and the new app must never point at it (see R5).
+- Any future data migration would be an explicit, separate project with its own ADR.
+
+---
+
+## 6. Frontend assessment
+
+| Area | Finding | Evidence | Sev |
+|---|---|---|---|
+| Structure | Reasonable Inertia layout: `Pages/`, `Components/{UI,Layout,Products,…}`, `Composables/`, `Layouts/{Guest,Authenticated,Vendor}`. Every SFC uses `lang="ts"`. | `resources/js/**` | Info |
+| Type safety | **`vue-tsc --noEmit` reports 22 errors** (TS2339 ×14, TS18046 ×4, TS2322 ×3, TS2353 ×1), mostly in `Pages/Products/Show.vue` (10), `Vendor/Dashboard.vue` (4) and `Orders/Show.vue` (3). CI never runs it. | Verified, run locally 2026-11-01 | Medium |
+| Contracts | Types in `resources/js/types/{models,api}.ts` are hand-written. Controllers build ad-hoc arrays (e.g. `CheckoutController::summary`) with no generated or validated contract, and money is passed as raw ints with inconsistent naming (`price`, `subtotal`, `total_cents`). | `app/Http/Controllers/Web/CheckoutController.php` | Medium |
+| Design system | Component kit is minimal (Alert, Badge, Modal, Toast, DataTable, EmptyState, Spinner…). No tokens doc. `resources/css/app.css` is 253 lines. The largest pages are monoliths: `Products/Show.vue` 1,370 lines, `Checkout/Summary.vue` 603. | | Medium |
+| i18n | `vue-i18n` is created with **empty messages**. Translations come via the Inertia shared prop `translations` from `lang/*/ui.php` (117 lines/locale). 174 `t()` call sites, but many hard-coded English strings remain (e.g. `Pages/Refunds/Status.vue:84`). | `resources/js/i18n/index.ts`, `HandleInertiaRequests.php:64` | Medium |
+| RTL | `<html dir>` is set correctly for `ar`. But layout uses **201 physical direction utilities** (`ml-/mr-/pl-/pr-/left-/right-`) vs **1 logical** (`ms-/me-/ps-/pe-/start-/end-`), so Arabic layout will mirror incorrectly. | `resources/views/app.blade.php:2`; grep | High (for an Arabic-first product) |
+| Payments UI | Uses Stripe Payment Element + client-side `confirmPayment` (`Composables/usePayments.ts:91`), which is correct. But it then calls the server `/api/v1/checkout/confirm-payment`, which re-confirms server-side (§7.1). | | Linked to C1 |
+| Vendor UI | 19 vendor pages exist (dashboard, orders, products CRUD/import, inventory, returns, Q&A, reviews, promotions, storefront, settings, bundles, earnings, analytics, customers) | `Pages/Vendor/*` | Info: good feature inventory to re-spec |
+
+**Verdict.** Treat the frontend as a **feature and requirements reference**, not a base. A new design system (Phase 2) plus logical-property RTL plus a typed props contract will touch nearly every file anyway.
+
+---
+
+## 7. Critical business-flow findings (payments, inventory, orders, refunds)
+
+### 7.1 C1 — Successful payments never transition orders to Paid · **Critical · Defect · Code-confirmed**
+
+**Trace:**
+
+1. The browser confirms the PaymentIntent with Stripe.js (`resources/js/Composables/usePayments.ts:91`).
+2. Stripe sends `payment_intent.succeeded` → `StripeWebhookController` → `HandleStripeEventJob::handleSuccess()`.
+3. `handleSuccess` calls `ConfirmPaymentIntentAction::execute()`. That calls `Infrastructure/Payment/Stripe/PaymentGatewayService::confirmIntent()`, which calls `$stripe->paymentIntents->confirm()` **on an intent that already succeeded**. Stripe rejects confirming a succeeded intent *(assumption, Stripe API behaviour; verify with a test-mode call)*.
+4. The action catches the error, sets `status = Failed` and rethrows *inside* `DB::transaction`. The write rolls back and the job fails.
+5. Even if step 3 succeeded, the action only sets `PaymentIntent.status = Succeeded`. **Nothing in `app/` dispatches `PaymentSucceeded`** (grep shows only the class definition, a listener type-hint and tests). So `Order/Listeners/MarkOrderPaid` never runs.
+
+**Further problems:**
+
+- `/api/v1/checkout/confirm-payment` (auth-only) has the same re-confirm problem. Guests have no equivalent.
+- `payments:reconcile-orphaned` (`ReconcileOrphanedPaymentsCommand`) would repair orders, but it is **not scheduled** (`routes/console.php` schedules only loyalty expiry, abandoned carts and FX rates). It also only matches intents already marked `Succeeded`, which step 4 prevents.
+- **Test gap:** no test exercises the webhook path (`grep HandleStripeEventJob|webhooks/stripe tests/` returns nothing).
+
+**Impact:**
+
+- Customers are charged while orders stay `pending`.
+- Vendors filter by status and do not see the order as paid.
+- Stock stays reserved.
+
+*Note:* recent commits on `main` ("return the actual client_secret…", "uncaught ModelNotFoundException on checkout…") suggest the live checkout was being debugged in this area.
+
+### 7.2 C2 — Domain-event outbox has no consumer · **Critical · Defect · Code-confirmed**
+
+- `App\Shared\Domain\DomainEventRecorder::record()` inserts into `domain_events`.
+- `App\Jobs\DispatchDomainEventsJob` would replay unprocessed rows as Laravel events, but **nothing dispatches or schedules it**.
+- Events recorded only this way (`ProcessRefundAction`, `RequestRefundAction`, `RetryRefundExecutionAction`, `HandleStripeEventJob::handleFailure`):
+  - `RefundSucceeded` → listeners `UpdateOrderRefundState` and `ReleaseStockOnRefund` **never run**.
+  - `RefundFailed` and `RefundRequested` likewise never reach listeners.
+  - `PaymentFailed` → `Payment/Listeners/PaymentFailed` **never runs**.
+- Even if scheduled, the job is unsafe:
+  - No row locking or claim (`SELECT … FOR UPDATE SKIP LOCKED`), so concurrent workers double-dispatch.
+  - It marks a row processed after `event()`, so a listener exception leaves the row to be re-dispatched forever, with no attempts counter or dead-letter.
+  - `new $eventClass(...$record->payload)` depends on `get_object_vars` ordering and includes base-class properties.
+
+### 7.3 C3 — Inventory arithmetic is inconsistent · **Critical · Defect · Code-confirmed**
+
+| Operation | `quantity_available` | `quantity_reserved` | Implied meaning of `available` |
+|---|---|---|---|
+| `Stock::isAvailable()` (`Inventory/Models/Stock.php`) | uses `available − reserved` | | on-hand (gross) |
+| `ReserveStock` / `ReserveStockAction` | **−qty** | +qty | net of reservations |
+| `CompensateStockOnCancelAction` | +qty | −qty | net |
+| `ReleaseStockAction` (used by `CancelOrder` and `ReleaseStockOnRefund`) | unchanged | −qty | gross |
+| Payment success / fulfilment | *(nothing consumes reservations)* | | — |
+
+**Consequences:**
+
+- **Phantom stockouts.** With 10 units, reserving 3 leaves `available=7, reserved=3`, so sellable is 4. A second reservation of 3 leaves 4/6, so sellable is −2. Only 6 of 10 units can ever be sold.
+- **Stock never returns.** `CancelOrder` decrements `reserved` but never restores `available`.
+- **Variant blindness.**
+  - `ReleaseStockAction` and `CompensateStockOnCancelAction` look up `Stock` by `product_id` only.
+  - `CreateOrderFromCart::lockAndValidateStock()` and `ReserveStock` add the variant filter only when `variant_id !== null`. A product-level cart line can therefore lock or modify *any* variant's row.
+  - `ReserveStockAction` (used by `CheckoutAction`) never filters by variant at all.
+- **No reservation expiry.** Unpaid or abandoned checkouts hold stock forever. No scheduled release exists.
+- **No deadlock discipline.** Rows are locked in cart-item order, not sorted by id. Concurrent multi-item checkouts can deadlock.
+- **The "torture" tests miss all of this.** `tests/Feature/Torture/ConcurrentStockReservationTest.php` runs a sequential `for` loop on SQLite, where `lockForUpdate()` is a no-op. Its assertions (`reserved ≤ initial`, `available ≥ 0`) pass even with double subtraction.
+
+### 7.4 C4 — Order state machine is bypassed · **High · Defect · Code-confirmed**
+
+- `OrderStatus::canTransitionTo()` and `Order/Support/OrderStateGuard` exist and are reasonable.
+- `VendorOrderController::updateStatus()` does `$order->update(['status' => $validated['status']])` for **any** enum value: `paid`, `refunded`, back to `pending`, and so on.
+- `CancelOrder` only refuses `cancelled`/`completed`. It cancels paid or shipped orders without a refund and without a guard.
+- `HandleStripeEventJob::handleFailure()` sets `Order → Failed` on the first `payment_intent.payment_failed`. In Stripe that event is **not terminal**: the customer can retry with another card on the same intent. Because `PaymentStatus::Failed` is terminal locally, a later `succeeded` webhook is ignored. The result is a charged customer with a failed order, and **no stock release** on failure.
+- `OrderStatus::PartiallyRefunded → PartiallyRefunded` is disallowed, so a second partial refund cannot be represented.
+- No row lock or optimistic version on status writes, so concurrent transitions are last-write-wins.
+
+### 7.5 C5 — Refund races and unsafe provider calls · **High · Defect/Risk · Code-confirmed**
+
+- `RequestRefundAction` checks `getRemainingRefundableAmount()` **outside** the transaction and without locking the order. Concurrent requests can over-refund.
+- `ProcessRefundAction`:
+  - Checks status, then updates, without `lockForUpdate`, so concurrent approvals can issue two Stripe refunds.
+  - Calls `gateway->refund()` **without a Stripe idempotency key** (`PaymentGatewayService::refund`).
+  - On any exception, including a timeout after Stripe succeeded, marks the refund `Failed`. A retry (`RetryStuckRefundsCommand`, `RetryRefundExecutionAction`) can then refund twice.
+- There is no reconciliation against Stripe refund objects (`charge.refunded` / `refund.updated` webhooks are not handled).
+
+### 7.6 C6 — Checkout transaction design · **High · Risk · Code-confirmed** (`Application/UseCases/Order/CheckoutUseCase.php`, `Domain/Order/Actions/CreateOrderFromCart.php`)
+
+- **External call inside the DB transaction.** The Stripe `paymentIntents->create` call (`CreatePaymentIntentAction`) runs inside the outer `DB::transaction`, while holding stock row locks.
+  - If the commit fails afterwards, an orphan Stripe intent exists.
+  - Stripe latency extends lock hold time.
+  - The Stripe request carries **no idempotency key** (the local `idempotency_key` is not passed to Stripe).
+- **Cart not locked.** Two concurrent submissions both pass `CartIsNotCompleted`. HTTP idempotency (`EnsureIdempotentAction`) only applies to **authenticated** users who send an `Idempotency-Key` header. It is check-then-act with no claim row: `lockForUpdate` on a missing row locks nothing, and it is not inside a transaction.
+- **Prices taken from the cart snapshot** (`cart_items.price_cents_snapshot`) at add-to-cart time, without re-pricing or re-validation at checkout.
+- **Currency conversion done per component** (subtotal, tax, shipping, each discount converted separately), so the converted parts may not sum to the converted total. The base currency comes from the ambient `Context::get('tenant')`.
+- **Promotion usage recorded only when `$user !== null`.** Guests can reuse a limited code without bound.
+- **Tax by region never applies.** `CreateOrderData::shippingAddress` is never populated by `CheckoutUseCase`.
+- **Events dispatched before commit.** `OrderCreated` and `OrderStatusUpdated` (broadcast) fire inside the transaction with no `ShouldDispatchAfterCommit`, so listeners and broadcasts can observe rolled-back orders.
+
+---
+
+## 8. Security assessment
+
+| # | Finding | Evidence | Sev / Kind / Evidence level |
+|---|---|---|---|
+| S1 *(revised in Addendum A.6: on production code this is **cross-vendor**)* | **Vendor dashboard has no role/permission check.** Routes use only `['auth','tenant.user']`. `ResolveTenantFromUser` just sets context from `users.tenant_id`. Storefront registration (`Web/AuthController::register` → `User::create`) gives customers the current store's `tenant_id` via `BelongsToTenant`'s `creating` hook. A **customer can open `/vendor/*`** and change order statuses, edit products and prices, adjust stock, export customer lists, answer reviews and toggle promotions. None of the 26 vendor controllers call `authorize`/Gate. Tests cover only "vendor" and "guest", never "customer". | `routes/web.php` vendor group; `app/Http/Controllers/Web/Vendor*.php`; `tests/Feature/Web/VendorDashboardTest.php` | **Critical / Defect / Code-confirmed** |
+| S2 | **Tenant scope fails open.** `TenantScope::apply` adds no filter when `Context('tenant_id')` is null. Any route or job where context is not resolved is unscoped: users with `tenant_id NULL` on `/vendor/*`, guest API calls, queued jobs and console commands. Also, `/vendor/*` route-model binding (`{order}`, `{product}`, `{stock}`) may resolve **before** `tenant.user` sets context, depending on middleware priority. *Needs a runtime test to confirm cross-tenant IDOR.* | `app/Domain/Tenant/Scopes/TenantScope.php`; `bootstrap/app.php` | High / Risk / Code-confirmed (IDOR: assumption) |
+| S3 | **Guest checkout of another user's cart.** `Api/V1/CheckoutController::checkout` checks ownership only when *both* the requester and the cart have a user. An anonymous request with any (sequential) `cart_id` checks out, completes and archives a logged-in user's cart, and reserves its stock. | `CheckoutController.php` (`if ($user !== null && $cart->user_id !== null …)`) | High / Defect / Code-confirmed |
+| S4 | **Filament panel shared by platform and tenant staff**, with resources lacking policies. Filament grants access when no policy exists. No policy covers `SubscriptionPlan` (global, not tenant-scoped), `PaymentIntent`, `GiftCard`, `ShippingMethod`, `TaxZone`, `Bundle`, `ContentPage`, `Review`, `VariantAttributeType`, `PromotionExperiment`. `canAccessPanel` admits any tenant `admin`/`support`/`finance` user. | `app/Policies/` (10 policies), `User::canAccessPanel`, `app/Filament/Resources/*` | High / Risk / Code-confirmed (per-resource reachability: to verify) |
+| S5 | **Exception messages exposed to clients.** The global Inertia error renderer passes `$e->getMessage()` for 500s. It also references an un-imported `HttpException` (resolves to global `\HttpException`, so `instanceof` is always false), and JSON clients receive an Inertia HTML page. | `bootstrap/app.php` `withExceptions` | Medium / Defect |
+| S6 | **Webhook hardening.** An invalid signature throws an unhandled `SignatureVerificationException` and returns 500 (should be 400). There is no event-id de-duplication table. The whole Stripe event object is serialised into the queue payload. Amount and currency in the event are not checked against the local intent. | `Webhooks/StripeWebhookController.php`, `Jobs/HandleStripeEventJob.php` | Medium / Risk |
+| S7 | Arbitrary status writes by vendors (S1 + §7.4) allow marking unpaid orders paid or delivered. That would trigger downloads (`GenerateDownloadsOnOrderPaid`) and loyalty or earnings if listeners key off status. | `VendorOrderController::updateStatus` | High / Defect |
+| S8 | Rate limits exist on API groups (`throttle:20–60,1`). Login/register web routes have no explicit throttle *(assumption: no custom limiter found)*. | `routes/web.php`, `routes/api/v1.php` | Low / Risk |
+| S9 | Staging shares the production DB and auto-deploys on CI success on `redesign`, with optional `migrate --force`. Staging code (including unreviewed WIP) can mutate production data. | `.github/workflows/deploy-staging.yml` header + "Finalize deploy" step | High / Risk / Verified (workflow text) |
+| S10 | Demo credentials: all seeded users share `password`. Acceptable for demo only. The README documents it, and these seeders must never run against production. | `README.md`, `database/seeders/DatabaseSeeder.php` | Info |
+
+**Not found (positive):** mass-assignment uses `$fillable`; Sanctum stateful API; CSRF-exempt only `webhooks/stripe` and `_boost/*`; download links are token-gated; `dompurify` is used for rich content.
+
+---
+
+## 9. Testing and quality assessment
+
+| Item | Finding | Evidence |
+|---|---|---|
+| Volume | ~1,314 test cases / 135 files. Broad surface coverage. | `grep -c` |
+| Execution | See §9.1 for this assessment's run. | Verified |
+| DB engine | **SQLite in-memory** (`phpunit.xml`). Production is MySQL/MariaDB. Row locks, `unsigned`, JSON functions, collation and FK behaviour differ, and no locking or concurrency claim is testable. | `phpunit.xml:26-27` |
+| Concurrency | `tests/Feature/Torture/*` are sequential loops (§7.3). No multi-process or multi-connection tests. | |
+| Payments | Gateway mocked with Mockery in API tests (fine). **No webhook tests**, and no tests for duplicate or late webhooks, decline-then-succeed, or provider timeouts. | `tests/Feature/Api/V1/CheckoutApiTest.php` |
+| Authorization | No "customer cannot use vendor dashboard" or "vendor A cannot mutate vendor B by id" tests on web vendor routes (`MultiTenancy/TenantIsolationTest.php` covers model scoping). | |
+| Architecture | No `arch()` tests, no deptrac, no PHPStan/Larastan. | |
+| Static analysis in CI | Pint (`--test`), Rector `--dry-run`, `composer audit`, `npm audit`, CodeQL (JS/TS only). **Missing:** PHPStan, `vue-tsc`, ESLint, Mago. | `.github/workflows/ci.yml`, `codeql.yml` |
+| Frontend tests | None (no Vitest, no Playwright beyond 3 Pest "Browser" files). | `tests/Feature/Browser` |
+| Test isolation | No global `tests/Pest.php`. Each file calls `uses(TestCase::class, RefreshDatabase::class)` itself. Inconsistent and easy to forget. | |
+
+### 9.1 Test run performed for this assessment
+
+See **Addendum A.1** for complete results. Summary: 1,311 tests: **1,293 passed, 17 failed, 1 skipped** (4,403 assertions), 2,121 s locally. All 17 failures are caused by the uncommitted WIP change to `routes/web.php`. CI on the committed `redesign` head (`774d131`) reports 1,291 passed, 1 skipped.
+
+---
+
+## 10. Performance risks
+
+| # | Risk | Evidence | Sev |
+|---|---|---|---|
+| P1 | Stripe HTTP call made while holding stock row locks inside the checkout transaction | §7.6 | High |
+| P2 | Unsorted row locking makes concurrent multi-item checkouts deadlock-prone | `CreateOrderFromCart::lockAndValidateStock` | Medium |
+| P3 | 48 controllers build queries inline. Repeated status-count queries (`VendorOrderController::index` runs a separate `GROUP BY` on every request). No caching of catalogue facets. | | Low–Medium |
+| P4 | Translations cached "forever until cleared" per locale and shipped on **every** Inertia response as a shared prop | `HandleInertiaRequests.php:64-97` | Low |
+| P5 | `payment_intents.provider_reference` unindexed (webhook lookup) | D5 | Low (pilot scale) |
+| P6 | Large monolithic pages (`Products/Show.vue` 1,370 lines) and no route-level code-splitting review | | Low |
+| P7 | Typesense index requires manual `scout:import-all` after deploys, and failure is silent (README admits this) | `README.md` | Medium (operational) |
+
+The pilot scale in `docs/product/goals.md` (<100 orders/day) means correctness, not throughput, is the binding constraint.
+
+---
+
+## 11. Technical debt summary
+
+1. **Two product models in one codebase.** SaaS tenancy (subdomains, global scope, per-tenant categories, per-tenant currency) coexists with half-started marketplace semantics. On `redesign`, the session `shopping_tenant_id` (`ResolveTenantFromSubdomain::resolveShoppingTenant`, `Web/Concerns/RequiresShoppingTenant`) forces a cart to be single-store, contradicting ADR-0004.
+2. **Two event mechanisms**, one of them dead (§7.2).
+3. **Duplicate or dead code:**
+   - `ReserveStock` / `ReserveStockAction`.
+   - `CheckoutAction` (test-only).
+   - Empty `HandlePaymentWebhookAction.php`.
+   - `ConfirmPaymentIntentJob` (never dispatched in production; *to verify*).
+4. **Feature sprawl.** About 10 "Experimental" features (subscriptions, gift cards, A/B promotion experiments, chat, Q&A, waitlist, abandoned cart, fraud dashboard, downloads, AI recs) each add schema, Filament resources and test load.
+5. **Unpinned dependencies** (`stripe/stripe-php`, `laravel/reverb`, `nativephp/electron` set to `*`), and `faker` in production `require`.
+6. **Stale documentation** that over-claims (README, INVARIANTS, PRODUCTION_READINESS_REVIEW).
+7. **Uncommitted WIP** (44 files) on a branch that auto-deploys to a production-connected staging site.
+
+---
+
+## 12. Reusable vs replaceable matrix
+
+| Component | Disposition | Rationale |
+|---|---|---|
+| Integer-cents money convention; `currency` + `exchange_rate` snapshot on orders | **Reuse (concept)** | Correct; formalise as a `Money` value object |
+| `OrderStatus` / `PaymentStatus` / `RefundStatus` enums + `canTransitionTo` | **Reuse as reference** | Good starting state machines; fix gaps (§7.4) and enforce in one place |
+| Specification pattern (`app/Shared/Specifications`) | **Reuse selectively** | Useful for composable eligibility rules (promotions, refundability). Avoid using it for every guard. |
+| Typed IDs (`AbstractId`, `OrderId`…) | **Optional** | Adds ceremony. Decide in the ADR on conventions. |
+| Order-line snapshotting (`price_cents_snapshot`, `tax_cents_snapshot`) | **Reuse (concept)** | Correct for financial history |
+| Idempotency-key model | **Re-implement** | Concept right, implementation racy (§7.6) |
+| `CheckoutUseCase` / `CreateOrderFromCart` | **Replace** | Must become OrderGroup + per-vendor orders, with an external call outside the transaction and sorted locks |
+| Inventory actions | **Replace** | Semantics inconsistent (§7.3). Redesign as on-hand + reservations ledger. |
+| Stripe gateway adapter & webhook job | **Replace** | Wrong confirm flow, no event de-dup, no idempotency keys |
+| Refund actions | **Replace** | Races, unsafe retries (§7.5) |
+| `DomainEventRecorder` / `DispatchDomainEventsJob` | **Replace** with a real transactional outbox (if ADR approves) | §7.2 |
+| `BelongsToTenant` global scope | **Retire** | Per ADR-0003: explicit vendor scoping + policies + tests |
+| Subdomain tenancy, onboarding `/start` trial, `tenant-switcher` | **Retire** | Contradicts the single-storefront model |
+| Filament control plane | **Keep the technology; rebuild resources** | Filament 5 suits an operator back office. Rebuild with policies, separate it from vendor UI, and remove tenant-staff access. |
+| Vendor dashboard (Vue pages) | **Reference only** | Good feature inventory. Rebuild on the new design system with authorization. |
+| Storefront Vue pages | **Reference only** | Rebuild with logical-property RTL and typed contracts |
+| `lang/*/ui.php` strings | **Reuse as seed** | Restructure per namespace |
+| Metrics / alerting / correlation-id / audit log (`app/Shared`) | **Evaluate in Phase 8** | Possibly useful. Not on the critical path. |
+| Experimental features (§11.4) | **Retire from v2 scope** unless the owner promotes them | Reduces surface area |
+| CI workflows | **Rewrite** | Add PHPStan, vue-tsc, ESLint, MySQL service, arch tests. Remove the prod-DB staging. |
+| Seeders/factories | **Rewrite** | New schema; curated demo dataset (brief §14) |
+
+---
+
+## 13. Target architecture proposal (initial — for ADRs in Phase 1)
+
+### 13.1 Shape: a modular monolith, one Laravel app
+
+```
+app/
+  Modules/ (or src/)            one folder per bounded context, each with:
+    <Context>/
+      Domain/        entities/aggregates, value objects, domain events, policies (pure PHP where practical)
+      Application/   commands/queries (use cases), DTOs, ports (interfaces)
+      Infrastructure/Eloquent models, repositories/queries, gateways (Stripe), listeners
+      Http/          controllers, form requests, resources (Inertia props), routes
+      Contracts/     the ONLY namespace other modules may import (interfaces + DTOs + events)
+  Platform/          cross-cutting: Money, Clock, Ids, Outbox, Idempotency, Audit
+```
+
+Whether Eloquent models live in `Domain` (pragmatic) or behind repositories (purist) is itself an ADR. **Recommendation: pragmatic.**
+
+- Eloquent models live inside the module.
+- Business rules go in aggregate methods and domain services.
+- Other modules access them only through `Contracts`.
+- Enforcement uses Pest `arch()` tests plus deptrac.
+
+### 13.2 Proposed bounded contexts (fewer than the 29 folders today)
+
+| Context | Owns | Notes |
+|---|---|---|
+| **Identity & Access** | users, roles/permissions, vendor memberships, sessions | Shopper is marketplace-wide. Vendor staff hold a membership row (`vendor_id`, role). Operators are platform roles. No `tenant_id` on users. |
+| **Vendors** | vendor profile, application/approval lifecycle, payout account reference, commission overrides | Rename `tenant` → `vendor` (fresh DB makes this free) |
+| **Catalogue** | platform taxonomy (categories, attributes), products, variants, media, moderation state, pricing (list/sale price per variant) | Pricing stays inside Catalogue until promotions need more |
+| **Inventory** | stock per variant (on-hand), reservations (with TTL), movements ledger | Single-writer of stock; invariant `reserved ≤ on_hand` enforced in DB and code |
+| **Ordering (Cart + Checkout + Orders)** | cart, checkout session, **OrderGroup**, **VendorOrder**, lines, fulfilment state machine | Checkout orchestrates Inventory + Payments + Promotions via contracts |
+| **Payments & Finance** | payment attempts, provider events (de-duplicated), refunds, **ledger** (customer charge, commission, vendor payable, refund liability), payouts (later) | Its own context because money has its own lifecycle and audit needs |
+| **Promotions** | campaigns, codes, eligibility, allocation | Platform-run first |
+| **Engagement** | reviews, wishlist, (loyalty if promoted) | |
+| **Search** | read model / Typesense projection | Fed by events; never a source of truth |
+| **Notifications** | channels, templates, preferences | Event subscriber only |
+| **Platform Ops** | audit log, configuration, feature flags, health | |
+
+**Dependency direction (proposed):**
+
+```
+Http → Application → Domain;  Infrastructure → Domain
+Ordering → {Catalogue, Inventory, Payments, Promotions}.Contracts
+Payments → Ordering.Contracts (events only)
+Search, Notifications → *.Contracts events only
+Forbidden: any module importing another module's Domain/Infrastructure;
+           Domain importing Illuminate\Http, Filament, Inertia;
+           cross-module Eloquent relationships / joins outside read-model queries.
+```
+
+### 13.3 Key transactional design (to be decided by ADRs, not implemented yet)
+
+- **Checkout runs as a short saga:**
+  1. Validate and re-price.
+  2. One DB transaction creates the `OrderGroup`, `VendorOrders` and reservations (TTL), with locks taken in sorted order. It also writes outbox rows.
+  3. After commit, create the provider payment (idempotency key = checkout id).
+  4. Webhook drives `paid`, which consumes the reservations.
+  5. A scheduled sweeper releases expired reservations and cancels unpaid groups.
+- **Webhooks:**
+  - Verify the signature, return 400 on failure.
+  - Insert into `provider_events(provider, event_id UNIQUE)` and return 200.
+  - Process asynchronously with row locks.
+  - Re-fetch the provider object for authoritative state.
+- **Money:** a double-entry ledger for commission, vendor payable and refund liability, even before real payouts exist. It makes reconciliation testable without Stripe Connect.
+- **Outbox:** written in the same transaction and drained by a scheduled worker using `SKIP LOCKED`, with attempts, backoff and dead-letter.
+- **Concurrency tests:** run on MySQL in CI using real parallel processes or connections (e.g. `pcntl_fork` or `amphp/parallel`, already a dependency).
+
+### 13.4 Stack recommendation (each item an ADR)
+
+| Decision | Recommendation | Why |
+|---|---|---|
+| Laravel version | **Laravel 13 / PHP 8.4+** for the fresh start | Fresh app, no upgrade cost. Local PHP is 8.5. Pick the newest stable LTS-equivalent the host supports. |
+| Frontend | **Vue 3 + Inertia (v2 or v3) + TypeScript (strict)**, per the brief | The brief says Vue, but the separate `Nexo` repo chose React. Owner must confirm (Q2). |
+| Admin | **Keep Filament** for the operator panel only. Vendor dashboard in Vue/Inertia. | Filament excels at operator back-office CRUD, and vendors deserve a product-grade UI |
+| DB | **MySQL 8** (dev via Docker/Laragon; CI service container). Stop testing on SQLite for anything transactional. | Locking semantics |
+| Queue/cache | Redis | Already present |
+| Search | Start with **MySQL full-text + good indexes**. Add Typesense behind a `Search` port when demo data warrants it. | Reduces moving parts. Keeps search an ADR, not a default. |
+| Realtime | Defer Reverb until a feature needs it (order status push) | Fewer services for reviewers to run |
+| Payments | Stripe in **test mode** behind a `PaymentProvider` port. Connect/payout decision deferred to the finance ADR. | See Q1/Q3 |
+| Static analysis | PHPStan/Larastan (level 8 target), Pint, Rector, `vue-tsc`, ESLint, Pest `arch()`, deptrac | Brief §13 |
+| Contracts | Typed Inertia props generated from PHP DTOs (e.g. `spatie/laravel-data` + `typescript-transformer`) | Avoids duplicated rules and hand-written types. Needs an ADR. |
+
+---
+
+## 14. ADR backlog (proposed, none written yet)
+
+| # | Title | Depends on |
+|---|---|---|
+| 0001 | ADR process, template (brief §18 fields), statuses | — |
+| 0002 | Product context & market (portfolio showcase vs Sudan pilot), currencies, locales | Q1 |
+| 0003 | Fresh repository vs fresh branch; Laravel/PHP versions; Vue vs React | Q2 |
+| 0004 | Modular-monolith structure, module contracts and enforced dependency rules (arch tests + deptrac) | 0003 |
+| 0005 | Identity model: shopper / vendor membership / operator; RBAC library choice | 0004 |
+| 0006 | Vendor ownership & data isolation (explicit scoping, policies, isolation test suite as merge gate) — supersedes old ADR-0003 | 0005 |
+| 0007 | Catalogue: platform taxonomy, attributes, variants, media, moderation | |
+| 0008 | Inventory model: on-hand + reservations with TTL + movement ledger; DB constraints; lock ordering | |
+| 0009 | Order aggregate: OrderGroup + VendorOrder; state machines; who may transition what | |
+| 0010 | Checkout saga, transaction boundaries, idempotency (HTTP + provider) | 0008, 0009 |
+| 0011 | Payment provider integration: intent lifecycle, webhook ingestion & de-dup, reconciliation | 0010 |
+| 0012 | Financial model: ledger, commission freezing, vendor payables, refunds/chargebacks, payouts deferral | 0011 |
+| 0013 | Domain events & transactional outbox | 0004 |
+| 0014 | Backend↔frontend contract strategy (DTO → TS generation, money/date/enum serialisation, error shape) | |
+| 0015 | Search strategy (DB first vs Typesense) | |
+| 0016 | i18n & RTL strategy (logical properties, locale routing, currency/number/date formatting) | 0002 |
+| 0017 | Testing strategy: MySQL in CI, concurrency harness, failure-simulation fakes | |
+| 0018 | Environments & data isolation: demo env, seeding, **no shared prod DB** | |
+| 0019 | Admin surface: Filament scope and separation from vendor UI | |
+| 0020 | Feature retirement list (experimental features out of v2 scope) | Q5 |
+
+---
+
+## 15. Risk register (prioritised)
+
+| ID | Risk | Likelihood | Impact | Severity | Mitigation / phase |
+|---|---|---|---|---|---|
+| R1 | Carrying the broken payment, inventory and refund cores into v2 by "reusing" them | High if reused | Critical | **Critical** | Re-implement behind ADR-0008..0012, test-first on MySQL (P3–P5) |
+| R2 | Market/payment-provider mismatch (Sudan + Stripe) invalidates the money design | High | Critical | **Critical** | Owner decision Q1 before Phase 1 money ADRs |
+| R3 | Vendor isolation regressions after removing the global scope | Medium | Critical | **Critical** | Policies + isolation suite as merge gate + arch test (ADR-0006) |
+| R4 | Concurrency bugs undetected because tests run on SQLite | High | High | **High** | MySQL in CI + parallel-process harness (ADR-0017) |
+| R5 | New work touching the production DB (shared-DB staging, copied `.env`) | Medium | Critical | **High** | Separate repo/env; never reuse prod credentials; disable staging-on-prod workflow for v2 (ADR-0018) |
+| R6 | Scope creep from ~40 legacy features | High | Medium | **High** | Explicit v2 scope (Q5, ADR-0020) |
+| R7 | Uncommitted `redesign` WIP lost or auto-deployed | Medium | Medium | **Medium** | Owner decides: commit to a branch, stash, or discard (Q8) |
+| R8 | Financial model under-specified (commission, refunds, chargebacks) | Medium | High | **High** | ADR-0012 before Phase 5 |
+| R9 | RTL treated as mirroring | Medium | Medium | **Medium** | Logical properties from the design system up (ADR-0016) |
+| R10 | Portfolio credibility: README claims outrun behaviour | High (today) | High | **High** | Evidence-based docs; CI badges; reproducible demo (P10) |
+| R11 | Unpinned dependencies / ignored audit advisory | Medium | Medium | **Medium** | Pin; review GHSA-vvj3-c3rp-c85p (Q9) |
+| R12 | Solo-engineer bandwidth vs a 10-phase plan | High | Medium | **Medium** | Keep v2 scope tight; prefer depth (money/inventory) over breadth |
+
+---
+
+## 16. Recommended phase sequence
+
+The brief's sequence is sound. Recommended adjustments:
+
+1. **Before Phase 1:** owner answers Q1–Q5 (they change the PRD and money ADRs).
+2. **Phase 1:** write ADR-0001..0006 and 0008..0012 *before* any design work. Financial and inventory invariants drive schema, which drives UI states (pending, partially refunded, etc.).
+3. **Phase 2 (design system)** can run in parallel with late Phase 1, since it does not depend on the money ADRs.
+4. **Phase 3:** stand up a **new repository or orphan branch** (Q2) with MySQL-in-CI, arch tests and the test harness *first*, so every later phase lands against real gates.
+5. **Phases 4–5:** implement Inventory and Checkout/Payments **test-first**, including the §10/§11 failure scenarios from the brief, before building any storefront UI on them.
+6. **Phase 7 (frontend):** port features from the old Vue pages using the new design system and typed props.
+7. Throughout: no environment of v2 ever receives production credentials (R5).
+
+---
+
+## 17. Questions requiring owner decisions
+
+| # | Question | Why it matters | My recommendation |
+|---|---|---|---|
+| **Q1** | **What is v2's product context?** (a) Portfolio showcase of a generic marketplace (brief), (b) the real Sudan-market aljebal-albeedos pilot (ratified docs), or (c) both. | Determines payment provider, currency (SDG/MYR/USD), locales' priority, demo data, and whether Stripe Connect is viable. | (a) for v2, with a provider-agnostic payment port so (b) remains possible later |
+| **Q2** | **Where does v2 live, and in what frontend?** (a) New repo, (b) orphan branch in `nexo-ecommerce`, or (c) continue `C:\laragon\www\Nexo` (Laravel 13 + **React**, 67 commits). And Vue (brief) vs React (Nexo repo)? | Repo history and recruiters' first impression; Vue/React choice is fundamental | New repo (or `Nexo` repo reset) on Laravel 13 + **Vue 3/Inertia + TS**, as your brief states. Keep `nexo-ecommerce` read-only as the reference. |
+| **Q3** | Payments: test-mode Stripe with an **internal ledger** and simulated payouts (no Connect), or real Stripe Connect (separate charges & transfers)? | Connect adds onboarding/KYC flows and country constraints | Internal ledger + test-mode Stripe; Connect later via ADR |
+| **Q4** | Is the old live site (`store.aljebal-albeedos.com`) staying up on the old code? If yes, who maintains it, and should the C1/C3/S1 defects be hot-fixed there? | Real customers may be charged without orders being marked paid; customers can access vendor tools | If it takes real payments, hot-fix or take payments offline; that is outside the v2 phases and needs your explicit go-ahead |
+| **Q5** | v2 scope: which "Extended/Experimental" features survive? (loyalty, referrals, bundles, gift cards, subscriptions, chat, Q&A, waitlist, flash sales, digital downloads) | Scope and schema | Keep: promotions (platform-run), reviews, wishlist. Defer the rest. |
+| Q6 | Single currency for v2 (and which), or multi-currency display with single settlement currency? | Money model | Single settlement currency (e.g. MYR or USD); display conversion later |
+| Q7 | Primary locale and RTL priority: is Arabic primary, or English with Arabic/Malay as full peers? | Design system defaults | English primary for portfolio; AR/MS full peers with real RTL |
+| Q8 | What to do with the 44 uncommitted files on `redesign` (and the auto-deploy-to-prod-DB staging workflow)? | Risk of loss or accidental prod mutation | Commit to a WIP branch you don't push, or stash; disable `deploy-staging.yml` for that branch |
+| Q9 | Why is `GHSA-vvj3-c3rp-c85p` in `composer.json` audit ignore? | Supply-chain hygiene | Re-evaluate in the new repo |
+| Q10 | Hosting target for the demo (VPS as today, or a PaaS)? | Phase 3 environment and Phase 10 deployment docs | Decide by Phase 3 |
+
+---
+
+## 18. Phase 0 acceptance checklist (for the owner)
+
+- [ ] Major business workflows understood (browse → cart → checkout → pay → fulfil → refund) — §3, §7
+- [ ] Existing architecture documented — §3, §4
+- [ ] Critical invariants and their violations identified — §7
+- [ ] Weaknesses evidenced with file/class references — §5, §7, §8
+- [ ] Target architecture proposed with justification — §13
+- [ ] ADR backlog and risk register — §14, §15
+- [ ] Open questions listed — §17
+
+**Method note:** all inspection was read-only. Commands executed:
+
+- `git` log, status and diff.
+- `grep`/`find`.
+- `vue-tsc --noEmit`.
+- The Pest suite, with every external credential (Stripe, Google, Typesense, Mailtrap, FX API) overridden by dummy values in the process environment.
+
+The only file written to the repository is this report.
+
+---
+
+# Addendum A — Owner review clarifications (2026-11-01, still Phase 0)
+
+This addendum answers the owner's eight review points. Everything was gathered read-only:
+
+- File reads, `git` read commands, `git ls-remote`, and `gh run list/view` (GitHub Actions metadata and logs).
+- Local test runs, with every external credential replaced by a dummy value.
+
+No deployment, migration, stash, reset, clean, checkout or commit was executed in either repository.
+
+**Repository side effects, disclosed in full:**
+
+1. This report file (new, untracked).
+2. My first test attempt set `DB_DATABASE=__discovery_never_used` in the process environment, intending to guard the real DB. Because environment variables override `phpunit.xml`'s `<env>` values, that run used a SQLite **file** of that name in the repo root instead of `:memory:`. I stopped that run, deleted the file, and deleted a 0-byte remnant left by the stopped process. No MySQL database was touched. The `.env` points at MySQL, which was never reached.
+
+## A.1 Complete test-suite results (review point 1)
+
+### Old repository (`modular-ecommerce-system`, working tree = `redesign@774d131` + 44 uncommitted files)
+
+| Item | Value |
+|---|---|
+| Command | `php vendor/bin/pest --compact` (Pest 4 / PHPUnit 12, PHP 8.5.8 NTS, Windows 11) |
+| Environment overrides | `DB_CONNECTION=sqlite DB_DATABASE=:memory:`. Dummy `STRIPE_SECRET/KEY/WEBHOOK_SECRET`, `GOOGLE_CLIENT_SECRET`, `TYPESENSE_*`, `MAILTRAP_API_TOKEN`, `REVERB_APP_SECRET`. `MAIL_MAILER=array`. `CURRENCY_API_URL=http://127.0.0.1:9` (unreachable on purpose). `phpunit.xml` additionally forces `QUEUE_CONNECTION=sync`, `CACHE_STORE=array`, `SCOUT_DRIVER=collection`, `BROADCAST_CONNECTION=null`. |
+| **Total** | **1,311 tests, 4,403 assertions** |
+| **Passed** | **1,293** |
+| **Failed** | **17** |
+| **Skipped** | **1**: `tests/Feature/Domains/Order/CreateOrderConcurrencyTest.php:85`, reason "Requires amphp/parallel package for concurrent testing". Notably, this is the only test that would have exercised real concurrency, and it never runs. |
+| Risky / incomplete / todo | None reported |
+| Warnings / deprecations | None printed by the runner (compact mode prints PHP deprecations if any are triggered; none appeared) |
+| **Wall-clock duration** | **2,121.27 s (≈35 min)**. Each test re-runs 109 migrations on a fresh in-memory DB under Windows. CI on Linux takes 46.8 s for the same suite. |
+| Raw log | `C:\Users\MCR\AppData\Local\Temp\claude\C--laragon-www\ef9ce4e1-abb5-4e83-856a-1347f2ba36a5\scratchpad\pest-clean.txt` |
+
+**The 17 failures:**
+
+| Test file | Failing tests | Error |
+|---|---|---|
+| `tests/Feature/Browser/AuthTest.php` | 15: Login (7), Registration (7), Logout (1) | `Expected response status code [>=200, <300] but received 404` (and the 3xx variants) |
+| `tests/Feature/AdminImpersonationTest.php` | 2: "shares impersonation state as inactive…", "shares active impersonation state…" | `Not a valid Inertia response.` (the response was a 404, not an Inertia page) |
+
+**Root cause (verified):**
+
+- The uncommitted change to `routes/web.php` adds `tenant.subdomain` (`ResolveTenantFromSubdomain`) to the whole `/{locale}` storefront group (diff: `->middleware('locale')` → `->middleware(['locale', 'tenant.subdomain'])`).
+- These two test files make requests without creating a tenant whose domain matches the test host, so the middleware throws `NotFoundHttpException('Tenant not found.')`.
+- **Confirmation run:** re-running only these two files with `APP_URL=http://localhost` (CI's value) reproduced the same failures, which rules out my local `APP_URL=http://127.0.0.1:8000` as the cause.
+- The tests that pass after the WIP change rely on the WIP's modified `tests/Traits/WithTenant.php`, which now sets the tenant's `domain` to the test host. These two files do not use that trait.
+
+**Baseline for comparison (read-only from GitHub Actions):** CI run `32982452177` on committed `redesign@774d131` (2026-08-26, Ubuntu, PHP 8.4): **1,291 passed, 1 skipped, 0 failed, 4,354 assertions, 46.77 s.** The 20-test difference comes from tests added or changed in the WIP.
+
+**What these numbers do and do not show:**
+
+- The suite passing on committed code does **not** contradict §7–§8.
+- No test covers the webhook path, a customer reaching `/vendor/*`, guest cart takeover, or real concurrency.
+- The torture tests' assertions tolerate the inventory double-subtraction.
+
+### Frontend type check (old repository)
+
+`npx vue-tsc --noEmit -p tsconfig.json` reports **22 errors**: TS2339 ×14, TS18046 ×4, TS2322 ×3, TS2353 ×1. By file: `Products/Show.vue` 10, `Vendor/Dashboard.vue` 4, `Orders/Show.vue` 3, `Vendor/Orders.vue` 2, `Refunds/Status.vue` 1, `Error.vue` 1, `UI/DataTable.vue` 1. The process exit status was reported as 0 through the shell pipeline, but the error count above is what the log contains. CI does not run this check.
+
+### Separate `Nexo` repository
+
+| Suite | Command | Result | Duration |
+|---|---|---|---|
+| Pest (backend) | `php vendor/bin/pest`, with `APP_CONFIG_CACHE=<nonexistent scratch path> DB_CONNECTION=sqlite DB_DATABASE=:memory:` | **109 tests: 109 passed, 0 failed, 0 skipped**, 1,038 assertions (Laravel Pao JSON summary) | 52.1 s (56 s wall) |
+| Vitest (frontend) | `npx vitest run` | **33 files / 78 tests: 78 passed, 0 failed** | 88.6 s |
+
+**Finding (environment hazard, Medium):**
+
+- `C:\laragon\www\Nexo\bootstrap\cache\config.php` (git-ignored, dated 2026-09-10) is a cached config. When it exists, Laravel ignores `phpunit.xml`'s `DB_CONNECTION=sqlite`, so the tests ran against the `.env` MySQL database **`nile`**.
+- My first two attempts therefore tried `127.0.0.1:3306/nile`. MySQL was not running: each test waited ~16 s for a refused connection, and the run hit my 900 s timeout with no output (Pao prints only at the end).
+- **Had MySQL been running, `RefreshDatabase` would have dropped and re-migrated that local `nile` database.**
+- To avoid modifying the repository I did not run `config:clear`. I bypassed the cache with the `APP_CONFIG_CACHE` environment variable.
+- Fix for v2: tests should refuse to run against a non-test database, for example a guard in `TestCase` that asserts the connection is the test connection.
+
+## A.2 Stripe payment failure: confirmed by source vs needs test-mode verification (review point 2)
+
+### A.2.1 Confirmed by source inspection
+
+| # | Fact | Evidence |
+|---|---|---|
+| F1 | No production code instantiates or dispatches `App\Domain\Payment\Events\PaymentSucceeded`. Only the class, the `MarkOrderPaid` handler type-hint and two tests reference it. | `grep -rn PaymentSucceeded app tests` |
+| F2 | `MarkOrderPaid` is the only listener that sets `Paid` after payment. The other writer, `RetryOrderFinalizationAction`, is reachable only from the manual command `payments:reconcile-orphaned`, which `routes/console.php` does **not** schedule. | `Domain/Order/Listeners/MarkOrderPaid.php`, `Console/Commands/ReconcileOrphanedPaymentsCommand.php` |
+| F3 | The browser confirms the intent client-side with `stripe.confirmPayment(...)`. | `resources/js/Composables/usePayments.ts:91` |
+| F4 | On `payment_intent.succeeded`, `HandleStripeEventJob::handleSuccess()` → `ConfirmPaymentIntentAction::execute()` → `PaymentGatewayService::confirmIntent()` → `$stripe->paymentIntents->confirm($provider_reference)`. | `app/Jobs/HandleStripeEventJob.php`, `app/Infrastructure/Payment/Stripe/PaymentGatewayService.php` |
+| F5 | That Stripe call runs inside `DB::transaction`. On any `Throwable` the action writes `status=Failed` and **rethrows**, so the write is rolled back and the job fails. | `Domain/Payment/Actions/ConfirmPaymentIntentAction.php` |
+| F6 | On its success branch the action only updates `payment_intents.status`. It dispatches no event and never touches the order. | same |
+| F7 | `handleFailure()` sets intent and order to `Failed`. `PaymentStatus::Failed` is terminal, so a later `payment_intent.succeeded` for the same intent hits the `isTerminal()` early-return and is ignored. | `HandleStripeEventJob.php`, `Domain/Payment/Enums/PaymentStatus.php` |
+| F8 | `POST /api/v1/checkout/confirm-payment` (auth only) performs the same server-side confirm. Guests have no equivalent. | `Api/V1/CheckoutController::confirmPayment` |
+| F9 | `SignatureVerificationException`/`UnexpectedValueException` are not caught, so an invalid signature returns HTTP 500 instead of 400. | `Webhooks/StripeWebhookController.php` |
+| F10 | No test covers `HandleStripeEventJob` or `POST /webhooks/stripe`. | `grep` over `tests/` |
+
+**Conclusion that needs no Stripe call:** because of F1, F2 and F6, the webhook never moves an order to `Paid`, **whatever Stripe answers**. Stripe's behaviour only decides *how* it fails: an exception and failed job, or an intent silently marked `Succeeded` while the order stays `Pending`.
+
+### A.2.2 Requires Stripe test-mode verification (not executed; needs your authorisation)
+
+| # | Hypothesis | Why it matters | Test-mode procedure |
+|---|---|---|---|
+| V1 | Confirming an already-`succeeded` intent returns an error (Stripe documents `payment_intent_unexpected_state`) | Exception path (job fails, intent stays `Processing`) vs silent path (intent `Succeeded`, order `Pending`) | Fresh local DB, test keys, `stripe listen --forward-to http://localhost:8000/webhooks/stripe`, pay with `4242 4242 4242 4242`, inspect `payment_intents`, `orders`, `failed_jobs` |
+| V2 | Decline then retry on the same intent ends with a charged customer and a `Failed` order (F7) | Real-money impact if live keys are in use | Card `4000 0000 0000 0002`, then `4242…` in the same Payment Element |
+| V3 | Server `QUEUE_CONNECTION`: `sync` makes the webhook itself return 500 so Stripe retries for 3 days; `database`/`redis` records failures in `failed_jobs` | Where the evidence is, and whether Stripe has disabled the endpoint | Owner reads server config (read-only) |
+| V4 | Intent creation without `automatic_payment_methods`/`payment_method_types` works under the API version pinned by `stripe/stripe-php v17.6.0` | Whether the Payment Element even renders | Same harness as V1 |
+| V5 | The production webhook endpoint exists, subscribes to the right events, and the secret matches | If missing, orders stay `pending` for a different reason | Stripe Dashboard → Developers → Webhooks |
+
+Recommendation: run V1, V2 and V4 only in local test mode against a throw-away database. Do it now only if you need the answer for the live-site decision (A.6); otherwise it belongs in Phase 5's failure-simulation suite.
+
+## A.3 Preservation plan for uncommitted work (review point 3): proposal only, nothing executed
+
+### A.3.1 Inventory (verified)
+
+**`modular-ecommerce-system`, branch `redesign` @ `774d131`** (local and `origin/redesign` identical, 0/0 ahead/behind):
+
+- **33 modified tracked files** (+801/−73 lines):
+  - `README.md`
+  - `app/Domain/Tenant/Models/Tenant.php`
+  - 3 Filament `VariantAttributeTypes` files
+  - `Web/{Auth,Cart,Checkout,Home,Store}Controller.php`
+  - `Middleware/ResolveTenantFromSubdomain.php`, `config/tenancy.php`
+  - `database/factories/TenantFactory.php`, `database/seeders/DatabaseSeeder.php`
+  - `lang/{ar,en,ms}/ui.php`
+  - `Components/Layout/{BottomNav,MobileNav}.vue`, `Layouts/{Authenticated,Guest}Layout.vue`, `Pages/{Home,Stores/Show}.vue`
+  - `routes/web.php`
+  - 9 files under `tests/Feature/**` and `tests/Traits/WithTenant.php`
+- **11 untracked paths:**
+  - `app/Domain/Tenant/Models/StoreFollow.php`
+  - `app/Http/Controllers/Web/Concerns/RequiresShoppingTenant.php`
+  - Migrations `2026_08_27_142036_add_marketplace_fields_to_tenants_table.php` and `2026_08_27_142044_create_store_follows_table.php`
+  - `database/seeders/VariantAttributeTypeSeeder.php`
+  - `docs/REDESIGN_BRIEF.md`
+  - `docs/architecture/` (ADR-0001..0004, `marketplace-migration.md`)
+  - `docs/product/` (5 docs)
+  - `resources/js/Components/Stores/StoreCard.vue`, `resources/js/Pages/Stores/Index.vue`
+  - `tests/Feature/Filament/VariantAttributeTypeResourceTest.php`
+  - Plus this report under `docs/discovery/`.
+- **Git-ignored but not reproducible from Git:** `.env` (secrets), `CLAUDE.md`, `Check.md`, `boost.json`, `.mcp.json`, `.idea/`.
+- **Stashes:**
+  - `stash@{0}` "WIP on main: d0ba78c bulk product import".
+  - `stash@{1}` "WIP on chore/ci-cd-wiki: 489e35e".
+- **Agent worktree** `.claude/worktrees/agent-a8ba81d6`, branch `worktree-agent-a8ba81d6` @ `5975250` (2026-03-22). It has its own uncommitted changes: ≥10 modified files in the review-submission area.
+
+**`C:\laragon\www\Nexo`:**
+
+- **Branch `feat/vendor-frontend` holds 61 commits with no upstream.** `git ls-remote` lists only `refs/heads/main` on `Sentients-AI/Nexo`. These commits exist on this disk only. **This is the largest loss risk found.**
+- 3 modified files (`app/Http/Middleware/SetLocale.php`, `app/Providers/AppServiceProvider.php`, `resources/css/app.css`) and `stash@{0}`.
+- Untracked: `Form dependencies for artboards/` (3.1 MB design handoff `design_handoff_nile_lagoon`, cited as the design source of truth), `.github/hooks/`, `.github/workflows/hello.yaml`, and a vim swap file.
+
+### A.3.2 Plan (each step needs your approval; steps 1–3 do not modify either repository)
+
+1. **Out-of-repo snapshot** to e.g. `C:\laragon\backups\nexo-2026-11-01\`:
+   - `git diff --binary` → `redesign-tracked.patch`.
+   - Path-preserving copies of all untracked and ignored files above. `.env` is kept local only and **never committed or uploaded**.
+   - `git stash show -p --include-untracked stash@{N}` → one patch per stash.
+   - `git -C .claude/worktrees/agent-a8ba81d6 diff --binary` → `agent-worktree.patch`.
+   - `git bundle create … --all` for both repositories. This captures every branch, including the 61 unpushed commits and the worktree branch.
+   - The same diff and untracked copy for the `Nexo` repo.
+2. **Verify** without touching the repositories:
+   - `git bundle verify`.
+   - Clone each bundle into a scratch folder.
+   - Check out `774d131` there and run `git apply --check` on the patch.
+   - Record SHA-256 checksums of every artefact.
+3. **Off-machine copy:** you copy the folder somewhere you control. I will not upload it.
+4. *(Optional, separate approval, mutating)*
+   - Commit the old-repo WIP to a **new local branch** `wip/marketplace-pivot-2026-08`.
+   - Push `feat/vendor-frontend` to `Sentients-AI/Nexo`.
+   - **Never push to `redesign`.** A green CI on `redesign` auto-deploys to the production-DB staging site (A.5). Any other branch name only runs CI.
+5. *(Later)* Disposition:
+   - Keep `docs/product/*` and ADR-0002..0004 as v2 inputs.
+   - Treat the code WIP (session "shopping tenant", StoreFollow, `tenant.subdomain` on the storefront) as reference only. It contradicts ADR-0004 and breaks 17 tests.
+
+## A.4 The `C:\laragon\www\Nexo` repository (review point 4)
+
+| Dimension | `Nexo` (`Sentients-AI/Nexo`) | Old repo (`AdilAzhari/nexo-ecommerce`) |
+|---|---|---|
+| History | 67 commits, 2026-08-31 → 09-15. `main` (6 commits; `origin/main` 2 ahead with merged PR #4 "vendor domain documentation"). `chore/phase-0-foundation` (pushed). `feat/vendor-frontend`: 61 commits, **local only**. Plan-driven conventional commits (D1–D7, B1–B2). | 208 commits on `redesign`; SaaS history plus many deploy fixes |
+| Author identity | 60 × `adelazhary1997@…`, 3 × `adelazhry1997@…`, 4 × `adilazhariosman@…`: **mixed** | — |
+| Backend stack (verified, `composer.json`) | PHP `^8.5`, **Laravel `^13.17`**, `inertiajs/inertia-laravel ^3.3`, Ziggy. Dev: **Larastan 3 / PHPStan 2**, Pint, **Pest 5**, Pao, Pail | PHP ^8.2, Laravel 12.68, Inertia 2.0.19, Filament 5.7.6, Cashier 16.1, stripe-php 17.6, Reverb, Scout/Typesense, Pest 4, Rector, Mago |
+| Frontend stack (verified, `package.json`) | **React 19.2, `@inertiajs/react` 3.7, TypeScript 6, Vite 8, Tailwind 4, Vitest 5 + Testing Library, ESLint 9, Prettier** | Vue 3.5, `@inertiajs/vue3` 2.3, TS 5.9, Vite 7, Tailwind 4; no frontend tests, no linter |
+| Backend maturity | **Skeleton.** 42 PHP files: one model (`User`), 3 framework migrations (users/cache/jobs), 14 vendor + 11 auth controllers that render **static fixture arrays** (`app/Support/Fixtures/*`). No domain, persistence, auth, payments or inventory. | Extensive but defective (§7–§8) |
+| Frontend maturity | **High for the vendor workspace:**<br>• 134 files, ~12.2k lines TS/TSX.<br>• UI kit of ~40 components (`components/ui`: DataTable, Sheet, MoneyInput, Stepper, Timeline, StatusBadge, TypedConfirm, charts, …) with co-located tests.<br>• `lib/` money, format, i18n, theme, status and countdown utilities, each with tests.<br>• "Lagoon" design tokens, Bidi/Money primitives, EN+AR locale files.<br>• Every vendor screen D1–D7 and auth B1–B2.<br>• Spec `docs/frontend/vendor-frontend-spec.md` (440 lines, "Shipped 2026-09-14"). | Functional but monolithic pages; 22 type errors; physical-direction CSS |
+| Tests | 43 PHP test files: page renders, fixture shapes, locale routing, `arch()` presets (no debug helpers, php and security presets, `env()` only in config). ~20 Vitest files. Results below. | 1,311 Pest tests (A.1) |
+| CI (`ci.yml`) | composer validate + audit, Pint, **PHPStan**, `php artisan test`. **Does not** run `npm ci`, `tsc`, ESLint or Vitest. | Pint, Rector dry-run, Pest/SQLite, audits, CodeQL-JS |
+| Docs | Product docs (incl. `requirements/{shopper,vendor,platform}`), ADR-0001..0004 (same decisions as the old repo's untracked ADRs), engineering handbook, 4 implementation plans | SaaS-era docs, partly over-claiming |
+
+**Nexo test results** (A.1):
+
+- Pest 109/109 passed in 52 s. Vitest 78/78 passed in 89 s.
+- Those tests cover page rendering, fixture shapes, locale routing, arch presets and UI components only. They say nothing about business logic, because there is none yet.
+
+**Suitability as the Nexo 2.0 foundation:**
+
+- **Backend:** equivalent to a fresh Laravel 13 app with better tooling and a good engineering handbook. There is no domain code to inherit, which is fine given a fresh-database rebuild.
+- **Frontend and design:** the most valuable artefact in either repository. It provides a tested component kit, money and bidi utilities, real RTL handling and a written vendor UX spec. **It is React, while the brief's stack baseline is Vue + Inertia** (brief §5 requires an ADR to replace an existing technology).
+- **The frontend choice belongs to you (decision D-1):**
+  - (a) **Vue, per the brief.** Port the React kit's *design*: tokens, component inventory, screen specs, copy. Roughly the kit has to be rebuilt.
+  - (b) **React, via an ADR that supersedes the brief's stack line.** Reuse ~12k lines of tested UI directly.
+- **My engineering recommendation is (b).** It reuses the most recent, highest-quality work and matches the latest owner decisions recorded in that repo. But it overrides the brief's text, so I will not assume it.
+- **Prerequisites either way:**
+  - Push or bundle the 61 local commits (A.3).
+  - Track the design-handoff folder.
+  - Decide author identity before the repo becomes the public portfolio (D-15).
+  - Add `npm` type-check, lint and Vitest to its CI.
+
+## A.5 Deployment workflows and the production database (review point 5)
+
+### A.5.1 Facts (verified from workflow files and read-only `gh` queries)
+
+**`deploy.yml` (production):**
+
+- **Triggers:** `workflow_run` when **CI** completes successfully on `main`, or `workflow_dispatch` (input `environment`: `production`/`staging`).
+- **Server sequence:** `git fetch origin main` → auto-`git stash push -u` of any server drift → `git merge --ff-only origin/main` → `composer install --no-dev` → caches → **`php artisan migrate --force` by default** (`run_migrations` defaults to `true`; automatic runs use `|| 'true'`).
+- **Last run:** `32973123836`, 2026-08-26 13:15 UTC, `headSha 2a43b9d` = current `origin/main`.
+
+**`deploy-staging.yml` (staging):**
+
+- Its header says staging "**shares the production database (same tenants, orders, users)**".
+- **Triggers:**
+  1. `workflow_run` after CI completes. For this event type GitHub runs the workflow file from the default branch, and `origin/main` contains it. The job runs only if `conclusion == success && head_branch == 'redesign'`.
+  2. `workflow_dispatch`.
+- **Checkout:** `ref: redesign`. Server: `git fetch origin redesign` → auto-stash drift → `git checkout redesign` → `merge --ff-only`.
+- **Assets:** rsynced to `STAGING_DEPLOY_PATH/public/build`. The web root's `index.php`/`.htaccess` are regenerated to point at the staging app.
+- **Migrations:** `RUN_MIGRATIONS = inputs.run_migrations || 'false'`, so **off for automatic runs** and opt-in on dispatch.
+- **Typesense:** `RUN_SCOUT_IMPORT` (opt-in) runs `scout:flush` + `scout:import` for Product, Category and Order.
+
+**`ci.yml`:** runs on **every push to every branch**.
+
+**Staging run history (all 7 runs, 2026-08-26):**
+
+- `32982669102`, `32978174614`, `32972588491` (`workflow_run`) and `32974726689`, `32971048644` (dispatch) logged `RUN_MIGRATIONS: false`, with no executed migration output.
+- `32970786677` and `32967584631` (dispatch) predate the migration step.
+- **No staging run has executed migrations.** Staging code has been serving requests since 2026-08-26 against the production database *(per the workflow's own statement; the server `.env` was not inspected)*.
+
+### A.5.2 How `redesign` can interact with production data
+
+| Path | Trigger | Effect | Exposure |
+|---|---|---|---|
+| P1 Runtime writes | Any request to the staging site | Registrations, carts, checkouts, stock reservations, vendor-dashboard and Filament edits, queued jobs: all written to production tables by **unreviewed `redesign` code**, with every defect in §7–§8 | **Ongoing while staging is up** |
+| P2 Schema change | Dispatch Deploy Staging with `run_migrations=true` | Runs `redesign` migrations on production. The two **uncommitted** migrations would run if they were committed and pushed. Production code (`main`) would then face an unknown schema. | Manual |
+| P3 Auto-deploy | `git push origin redesign` → green CI | New code live against production data, **no human gate** (migrations off) | Any push to `redesign` |
+| P4 Search wipe | Dispatch with `run_scout_import=true` | Flushes the Product/Category/Order indexes. If Typesense is shared *(unverified)*, production search is empty until re-import, which then comes from staging's code. | Manual |
+| P5 Duplicate schedulers/queues | A cron/queue worker for the staging path *(unverified)* | Loyalty expiry, abandoned-cart e-mails and FX fetch run twice against the same data | Unknown |
+| P6 Storage divergence | Uploads via staging | Production rows reference files that exist only in staging's storage | If used |
+| P7 Merge to `main` | Merge `redesign` → `main` | Production deploy runs `migrate --force` **by default**, applying `redesign`'s migrations automatically | On merge |
+
+**Not verifiable without server access:**
+
+- The staging `.env` DB target.
+- Whether staging cron or queue workers run.
+- Whether Typesense, Stripe keys and webhooks are shared with production.
+
+**Containment options (your decision; not executed):**
+
+- Remove the `workflow_run` trigger from `deploy-staging.yml` (on `main`, since that copy governs `workflow_run`).
+- Take staging offline, or give it its own database copy.
+
+For v2: no workflow may reach this server's database (ADR-0018).
+
+## A.6 Status of the old live storefront's risks (review point 6)
+
+### A.6.1 Confirmed from code (not from the live server)
+
+- The last production deploy shipped `origin/main @ 2a43b9d`.
+- `git diff --stat origin/main redesign` is **empty** for every implicated path:
+  - `app/Jobs`, `app/Domain/{Payment,Inventory,Order}`, `app/Infrastructure`, `app/Shared`.
+  - `Web/Vendor*`, `Middleware/ResolveTenantFromUser.php`, `Api/V1/CheckoutController.php`.
+  - `routes/web.php`, `routes/console.php`.
+- The uncommitted WIP does not touch those paths either, except `routes/web.php`.
+- **So production and staging run the same C1 (payment finalisation), C2 (dead outbox), C3 (inventory) and S3 (guest cart) code.**
+
+### A.6.2 Correction to S1 for production
+
+Evidence:
+
+- On `origin/main`, the `tenant.subdomain` middleware is registered (`bootstrap/app.php`) but **applied to no route**. `git grep` finds no use in `routes/`. The storefront group uses only `locale`.
+- Nothing else sets tenant context for web requests. `git grep "Context::add('tenant"` on `origin/main` finds only:
+  - `ResolveTenantFromSubdomain` (unused).
+  - `ResolveTenantFromUser` (vendor routes and API).
+  - `FilamentTenantMiddleware`.
+  - Two listeners/actions.
+- So a shopper registering through `/{locale}/register` gets **`tenant_id = NULL`**: `BelongsToTenant`'s `creating` hook copies `Context::get('tenant_id')`, which is null.
+
+Consequence: on `/vendor/*` (`auth` + `tenant.user`), `ResolveTenantFromUser` treats a NULL-tenant user like a super-admin and adds no context. `TenantScope` then applies **no filter**. **Any self-registered shopper can therefore read and modify every vendor's data:**
+
+- Orders: any status, bypassing the state machine.
+- Products and prices, and stock.
+- Returns, reviews and Q&A.
+- The customer list, which includes other users' names and e-mails.
+
+This is **worse than the single-store exposure §8 first described**. Code-confirmed; not runtime-verified against the live site. (With the WIP applied, a shopper registered on a store's domain gets that store's `tenant_id`, which narrows exposure to that one store.)
+
+### A.6.3 Not confirmed (needs your access; I used none)
+
+- That the server's checked-out code equals `2a43b9d`. Deploys auto-stash server drift, so manual hot-fixes may have been stashed away.
+- Live vs test Stripe keys, and whether real payments occurred.
+- Webhook registration and queue worker (A.2 V3/V5).
+- Whether real (non-seed) shoppers or vendors exist.
+
+### A.6.4 Risk by scenario
+
+| Risk | Live keys + real users | Test keys / demo only |
+|---|---|---|
+| C1 payment finalisation | Customers charged; orders stay `pending`; vendors see no paid orders; stock stays reserved; decline-then-success leaves charged customer with `failed` order | Functional bug |
+| S1 vendor dashboard | Anyone who registers can operate **all** vendors' dashboards and read customer PII | Same exposure on demo data; still a public privacy/defacement risk |
+| S3 guest cart takeover | Anonymous request can complete another user's cart and reserve stock | Low impact |
+
+### A.6.5 Owner-side read-only checks (I will not run these without approval)
+
+1. Stripe Dashboard: mode, payments, webhook delivery failures.
+2. Read-only SQL:
+   - `SELECT o.status, pi.status, COUNT(*) FROM orders o LEFT JOIN payment_intents pi ON pi.order_id = o.id GROUP BY o.status, pi.status;`
+   - `SELECT COUNT(*) FROM users WHERE tenant_id IS NULL AND role_id IS NULL;` (self-registered shoppers able to reach `/vendor/*`)
+3. Web-server access logs: `/vendor/` requests by non-staff sessions.
+
+**Containment options (your decision; outside v2 scope):**
+
+- Maintenance mode, or disable registration and checkout.
+- Take staging offline.
+- A minimal reviewed hot-fix for S1 (role check on the vendor route group) and C1.
+
+## A.7 Target financial model, expanded (review point 7)
+
+**Scope note.** This is a proposal for ADR-0012, not a decision. It assumes:
+
+- One settlement currency, with amounts as integer minor units.
+- The platform collects payment (Stripe test mode, "separate charges and transfers" semantics).
+- Vendor payouts are **simulated** in the ledger until Stripe Connect is approved separately (brief §8: no real payouts before the model is defined).
+
+### A.7.1 Entities
+
+```
+OrderGroup (one customer checkout) 1──* VendorOrder 1──* VendorOrderLine
+   │ grand_total, currency                 │ commission_rate_bps (frozen at creation)
+   │                                       │ per-line: net price, allocated_discount, tax, shipping share
+   1──* PaymentAttempt (≤1 active)         1──* Fulfilment / Return
+            │ provider_payment_id UNIQUE
+            ▼
+ProviderEvent (provider, event_id UNIQUE) ─► LedgerTransaction 1──* LedgerEntry(account, debit|credit, amount)
+Refund (per VendorOrder, per line)        ─► idempotency_key UNIQUE, provider_refund_id UNIQUE
+Dispute (per charge) ─► DisputeAllocation (per VendorOrder)
+Payout (simulated, per vendor)            ─► from payable_available
+```
+
+### A.7.2 Chart of accounts (double-entry; every LedgerTransaction sums to zero)
+
+| Account | Type | Meaning |
+|---|---|---|
+| `platform:psp_clearing` | Asset | Funds held for the platform at the provider |
+| `platform:commission_revenue` | Revenue | Commission earned |
+| `platform:psp_fees` | Expense | Processing fees |
+| `platform:promo_expense` | Expense | Platform-funded discounts |
+| `platform:dispute_holding` | Asset | Funds withdrawn by the provider pending a dispute |
+| `platform:dispute_losses` | Expense | Disputes lost and absorbed by the platform |
+| `vendor:{id}:payable_pending` | Liability | Owed to vendor, not yet withdrawable |
+| `vendor:{id}:payable_available` | Liability | Withdrawable |
+| `vendor:{id}:payable_held` | Liability | Frozen (open dispute or investigation) |
+| `vendor:{id}:receivable` | Asset | Vendor owes the platform (refund or chargeback after payout) |
+| `platform:tax_payable` *(only if the marketplace collects tax)* | Liability | Tax collected on behalf |
+
+### A.7.3 Worked lifecycle (two vendors, 10 % commission)
+
+Vendor A goods 60.00, Vendor B goods 40.00, charge 100.00, provider fee 3.20.
+
+1. **Capture** (on `payment_intent.succeeded`, de-duplicated by `event_id`, amount and currency checked against the attempt):
+   - Dr `psp_clearing` 100.00
+   - Cr `vendor:A:payable_pending` 54.00 · Cr `commission_revenue` 6.00
+   - Cr `vendor:B:payable_pending` 36.00 · Cr `commission_revenue` 4.00
+2. **Fee** (from the provider's balance transaction): Dr `psp_fees` 3.20 / Cr `psp_clearing` 3.20. Who bears it is decision D-9.
+3. **Maturity.** A's order is delivered and its return window (e.g. 7 days) has elapsed: Dr `A:payable_pending` 54.00 / Cr `A:payable_available` 54.00. The job is idempotent per VendorOrder.
+4. **Simulated payout:** Dr `A:payable_available` 54.00 / Cr `psp_clearing` 54.00, plus a `Payout` row. Later, real transfers via Connect `transfers.create` with `source_transaction` and idempotency key = payout id.
+
+### A.7.4 Partial vendor-order refund
+
+Customer returns one Vendor A line worth 20.00.
+
+- **Eligibility under a lock:**
+  - Inside a transaction holding `SELECT … FOR UPDATE` on the VendorOrder:
+    `refundable_remaining = captured_allocated(A) − Σ refunds(A) in {requested, approved, submitted, succeeded}`.
+  - Per-line cap = line net after allocated discount, plus tax and shipping share per policy.
+  - This serialises concurrent requests (fixes §7.5).
+- **Lifecycle:** `requested → approved → submitted → succeeded | failed | requires_action`.
+  - The provider call carries idempotency key = `refund.id`.
+  - **A timeout leaves `submitted`, never `failed`.** Resolution comes from `refund.updated`/`charge.refunded` or reconciliation, so a retry cannot double-refund.
+- **Ledger, posted only when the provider confirms success:**
+  - Dr `A:payable_pending` (or `payable_available`) 18.00
+  - Dr `commission_revenue` 2.00 (commission reversed pro-rata; decision D-10)
+  - Cr `psp_clearing` 20.00
+  - The original fee is normally not returned by the provider and stays expensed.
+- **Already paid out:** the debit drives A's payable negative. The shortfall moves to `vendor:A:receivable` and is recovered by netting future payables (or by a transfer reversal once Connect exists).
+- **Siblings untouched.** Vendor B's entries and order state never change. OrderGroup status is *derived* (`partially_refunded` when any child has refunds).
+- **Inventory:**
+  - Restock only on `ReturnReceived` (inspected).
+  - A refund for a never-shipped item releases or consumes the reservation instead.
+  - Shipping and tax refund portions follow the line's stored allocation.
+
+### A.7.5 Discounts and promotions
+
+- Group-level discounts are allocated to lines pro-rata to net amount, with largest-remainder rounding so they sum exactly.
+- The allocation is stored on the line, so refunds reverse exactly what was allocated.
+- **Funding source:**
+  - Platform-funded: the vendor payable is computed on the pre-discount amount, and the platform posts Dr `promo_expense`.
+  - Vendor-funded: the vendor payable is computed on the discounted amount.
+
+### A.7.6 Commission
+
+- `commission_rate_bps` is resolved at VendorOrder creation (vendor override → category → platform default) and **frozen**.
+- It applies to line net after vendor-funded discounts, excluding tax. Shipping is included or excluded per D-10.
+- Per-line rounding is half-even, with a documented residual-cent rule.
+- Changing rates never alters existing orders; a test asserts this.
+
+### A.7.7 Vendor payable balances
+
+- Balances are **derived from ledger entries**, never stored as mutable columns. A cached projection is allowed, with a nightly consistency check.
+- Vendor dashboard shows pending, available, held, receivable and paid, plus a statement export of ledger lines.
+- Payout eligibility requires `available > 0` with no open dispute holds on the same orders. A minimum payout amount is a config value.
+
+### A.7.8 Chargebacks and disputes
+
+- **`charge.dispute.created`** (dispute is per charge, i.e. per OrderGroup):
+  - The provider withdraws amount plus fee: Dr `dispute_holding` / Cr `psp_clearing`.
+  - **Allocate** the disputed amount to VendorOrders: by the disputed items if identifiable, else pro-rata.
+  - Move each allocation from `payable_*` to `payable_held`.
+  - Notify the vendors and collect evidence through the vendor UI.
+- **Won:** funds return (Dr `psp_clearing` / Cr `dispute_holding`), and holds are released to `available`.
+- **Lost, per D-11:**
+  - Vendor bears the goods amount: Dr `payable_held` / Cr `dispute_holding`, with any shortfall moving to `receivable`.
+  - Or the platform bears it: Dr `dispute_losses`.
+  - The dispute fee is normally platform-borne.
+- **Guards:**
+  - No refund while a dispute is open (prevents double recovery).
+  - No payout of held funds.
+
+### A.7.9 Reconciliation
+
+1. **Internal invariants** (tests and a nightly job):
+   - Every transaction balances.
+   - Per OrderGroup: `captured = Σ vendor payables + Σ commission − promo_expense adjustments`.
+   - `Σ refunds ≤ captured` per VendorOrder.
+   - `paid` VendorOrders ⇔ a succeeded PaymentAttempt.
+   - Reservations ⇔ unpaid open orders.
+2. **Provider reconciliation** (daily):
+   - Pull provider balance transactions for the window and match by payment, refund, dispute and transfer id.
+   - Classify each as matched, missing-locally (replay from the provider object), missing-at-provider, or amount/currency mismatch.
+   - Exceptions go to a `reconciliation_exceptions` queue with Filament resolve actions (audit-logged).
+3. **Operational sweeps:**
+   - Attempts stuck in `processing` beyond a threshold are re-fetched from the provider.
+   - Expired reservations are released and their unpaid groups cancelled.
+   - Refunds stuck in `submitted` are re-fetched.
+4. **Reporting:** a daily settlement report (captures, refunds, fees, commission, payable movements, disputes) that ties out to the provider payout report.
+
+### A.7.10 Testing implications
+
+- **Property tests:** random baskets, discounts and partial refunds; the ledger always balances and allocations sum exactly.
+- **MySQL concurrency tests:**
+  - Two refunds on one VendorOrder.
+  - Duplicate `event_id` delivery.
+  - Refund racing payout maturity.
+  - Dispute racing refund.
+- **Failure tests with a fake provider adapter** (out-of-order, duplicated and delayed events; timeouts):
+  - No double refund.
+  - No payout of held funds.
+  - Reconciliation detects an injected mismatch.
+
+## A.8 What the brief already settles vs what needs your decision (review point 8)
+
+### A.8.1 Settled by the brief (treated as given)
+
+| Topic | Settled position | Brief § |
+|---|---|---|
+| Purpose & audience | Premium portfolio showcase for recruiters and engineers; must feel like a credible commercial product | header, §2 |
+| Product model | Unified multi-vendor general-merchandise marketplace; three surfaces | §2, §6 |
+| Process | One phase at a time; owner approval; ADRs for significant decisions; evidence-based reporting | §4, §19 |
+| Strategy | Hybrid rebuild; **fresh database**; old app is a reference; never connect to the production DB | §3 |
+| Architecture style | Modular monolith with explicit boundaries; no microservices | §5 |
+| Order shape | Checkout/OrderGroup → per-vendor orders, designed explicitly | §8 |
+| Payouts | No real vendor payouts until the financial model is defined | §8 |
+| Admin | Evaluate and improve Filament rather than assume replacement | §6.3 |
+| Technology changes | Any replacement of an existing technology needs an ADR | §5 |
+| Visual identity | New from scratch; design system reviewed before frontend build | §7, Phase 2 |
+| Quality | Concurrency, failure and authorization tests; CI gates must pass honestly | §10–§13 |
+| Locales | Evaluate EN, AR (real RTL), MS | §16 |
+| Docs layout & ADR template | As specified | §18 |
+
+**Correction to §1 and §17.** I called "product context" (Q1) the single most important open question. The brief already settles it: the purpose is a portfolio showcase. What actually remains for you is D-4 (formally supersede the Sudan-market docs) and D-5 (currency and locale priority).
+
+### A.8.2 Genuinely requires your decision
+
+| ID | Decision | Options | Recommendation | Needed by |
+|---|---|---|---|---|
+| D-1 | Frontend framework | Vue 3 (brief) · React 19 (Nexo repo, via ADR) | React on reuse grounds, *or* Vue to follow the brief literally (A.4) | Phase 1 ADR |
+| D-2 | v2 repository | New repo · continue `Sentients-AI/Nexo` · orphan branch in `nexo-ecommerce` | Continue `Sentients-AI/Nexo` after preservation, or a new repo if clean authorship matters | Phase 1 ADR |
+| D-3 | Laravel/PHP version | Laravel 13 / PHP 8.5 · Laravel 12 / 8.4 | Laravel 13; PHP per your demo host | Phase 1 ADR |
+| D-4 | Sudan-market product docs | Supersede · keep as a future context | Supersede for v2; archive | Phase 1 PRD |
+| D-5 | Settlement currency & primary locale | MYR · USD · other; EN- or AR-primary | Single currency (MYR suits Malay locale and the existing demo vendor); EN primary with AR/MS as full peers | Phase 1 |
+| D-6 | Payment depth | Test-mode Stripe + internal ledger + simulated payouts · Stripe Connect | The former; Connect as a later ADR | ADR-0011/12 |
+| D-7 | v2 feature scope | Loyalty, referrals, bundles, gift cards, subscriptions, chat, Q&A, waitlist, flash sales, downloads | Keep promotions, reviews, wishlist; defer others | Phase 1 PRD |
+| D-8 | Search | Typesense from day one · DB search behind a port first | DB first; Typesense in Phase 8 if justified | ADR-0015 |
+| D-9 | Provider fees bearer | Platform · pro-rata to vendors | Platform | ADR-0012 |
+| D-10 | Commission on refunds / on shipping | Reverse pro-rata or keep · include or exclude shipping | Reverse pro-rata; exclude shipping | ADR-0012 |
+| D-11 | Chargeback liability | Vendor bears goods · platform bears | Vendor bears goods, platform bears fee | ADR-0012 |
+| D-12 | Old live site & staging containment | Leave · maintenance · hot-fix S1/C1 · staging offline | **Urgent:** at minimum take staging offline and close `/vendor/*` to non-staff (A.6) | Now |
+| D-13 | Preservation of uncommitted work | Plan A.3 steps 1–3 · plus step 4 | Steps 1–3 now | Now |
+| D-14 | Stripe test-mode verification (A.2.2) | Now · Phase 5 | Phase 5, unless needed for D-12 | — |
+| D-15 | Commit author identity for the public repo | Keep history · rewrite to one identity before publishing | Decide together with D-2 | Before Phase 3 |
+
+---
+
+**End of Phase 0 addendum A.**
+
+---
+
+# Addendum B — Owner decisions and their execution (2026-11-01, still Phase 0)
+
+## B.1 Decisions recorded
+
+| ID | Owner decision | Status |
+|---|---|---|
+| D-12 | Close public access to `/vendor/*` and take staging offline until its production-database connection is removed | **Approved. Not executed:** needs server access (B.3) |
+| D-13 | Preservation steps 1–3, strictly read-only against both repositories | **Steps 1–2 executed and verified (B.2). Step 3 is yours** |
+| D-1 | **Vue 3 + Inertia.js + TypeScript.** The existing React implementation is a reference, not the foundation | Approved; becomes ADR in Phase 1 |
+| D-2 | **The clean `Nexo` repository is the Nexo 2.0 foundation.** The old repository is retained as a historical reference | Approved; becomes ADR in Phase 1 |
+
+**Consequences of D-1 + D-2 together (for Phase 1 to plan, not acted on):**
+
+- `Nexo` keeps its backend shell and tooling: Laravel 13, Larastan/PHPStan, Pint, Pest 5 with `arch()` presets, the engineering handbook, product and requirements docs, ADR-0001..0004 and CI.
+- Its frontend layer gets replaced by Vue:
+  - `@inertiajs/react` and React 19 give way to `@inertiajs/vue3`.
+  - The Testing Library flavour changes, and `tsconfig`/ESLint configuration follows.
+- The React vendor workspace (`feat/vendor-frontend`, 61 commits) becomes reference material. Its reusable assets are framework-neutral:
+  - design tokens;
+  - `lib/` money, format, status and countdown logic, portable to TS modules almost unchanged;
+  - EN/AR locale files;
+  - the component inventory and `vendor-frontend-spec.md`;
+  - the design handoff folder.
+- The old repo's Vue pages are reference only: they have 22 type errors and physical-direction CSS (§6).
+- Phase 1 decides which `Nexo` branch v2 starts from. `main` holds the Phase 0 foundation, while `feat/vendor-frontend` adds the React UI that D-1 sets aside.
+- D-15 (commit author identity) now applies to `Sentients-AI/Nexo`. It must be settled before that repository is presented publicly.
+- This report lives, untracked, in the old repository. Moving it into `Nexo/docs/discovery/` is a Phase 1 housekeeping step.
+
+## B.2 D-13 execution record (steps 1–2)
+
+**Location:** `C:\laragon\backups\nexo-2026-11-01\` (9.8 MB, 144 files, outside both repositories).
+
+**Method:** every git command ran with `GIT_OPTIONAL_LOCKS=0`, so not even the index was refreshed. Only read commands were used: `diff`, `ls-files`, `stash show`, `bundle create` (writes only the output file), `rev-parse` and `status`. The script is kept beside the scratch verification output; nothing was written inside either repository.
+
+| Artefact | Contents |
+|---|---|
+| `old/redesign-tracked.patch` (69 KB) | `git diff --binary HEAD` of the 33 modified tracked files on `redesign@774d131` |
+| `old/untracked/` (20 files) | All untracked files, paths preserved (includes this report) |
+| `old/ignored/` | `.env`, `CLAUDE.md`, `Check.md`, `boost.json`, `.mcp.json`, `.claude/settings.local.json`, `.idea/`, `public/redesign/` |
+| `old/stashes/stash-{0,1}.patch` | Both stashes, `--include-untracked`, binary |
+| `old/agent-worktree/` | `agent-worktree.patch` (33 KB, 14 modified files) and `untracked/` (30 files) of `worktree-agent-a8ba81d6@5975250` |
+| `old/nexo-ecommerce-all.bundle` | `git bundle --all`: every local and remote-tracking branch, including the worktree branch |
+| `nexo/feat-vendor-frontend-tracked.patch` (7 KB) | The 3 modified tracked files on `feat/vendor-frontend@cc4e8bc` |
+| `nexo/untracked/` (39 files) | Design handoff (`Form dependencies for artboards/…`), `.github/hooks/`, `hello.yaml`, swap file |
+| `nexo/ignored/` | `.env`, `.idea/`, `.impeccable/` |
+| `nexo/stashes/stash-0.patch` | The one stash |
+| `nexo/nexo-all.bundle` | `git bundle --all`, including the **61 local-only commits** |
+| `SHA256SUMS` | Checksums of every artefact |
+| `SECRETS-WARNING.txt` | Both `.env` files are secrets: keep local, never upload or commit |
+
+**Excluded on purpose** because they are regenerable: `vendor/`, `node_modules/`, `storage/`, `bootstrap/cache/`, `public/hot`, and `Nexo/build/` (a 69 MB PHPStan cache).
+
+**Verification (step 2), all in a scratch folder:**
+
+- `git bundle verify` reports "okay" for both bundles.
+- Clone of the old bundle:
+  - Check out `774d131`, then `git apply --check redesign-tracked.patch`: **applies**.
+  - Check out `5975250`, then `git apply --check agent-worktree.patch`: **applies**.
+- Clone of the Nexo bundle:
+  - Check out `cc4e8bc`, then `git apply --check`: **applies**.
+  - `origin/main..origin/feat/vendor-frontend` = **61 commits**, so the local-only work is captured.
+- Untracked file counts match the live inventory: 20, 30 and 39.
+- **Both repositories confirmed unchanged afterwards:**
+  - old repo: `774d131 redesign`, 45 status entries, 2 stashes;
+  - Nexo: `cc4e8bc feat/vendor-frontend`, 7 status entries, 1 stash.
+
+**Step 3 (yours):** copy `C:\laragon\backups\nexo-2026-11-01\` to storage you control. Check it there with `sha256sum -c SHA256SUMS`. Prefer an encrypted location, since the folder holds the two `.env` files. Until this is done, the 61 commits still exist on one physical disk only.
+
+## B.3 D-12: why it is not executed yet, and the runbook
+
+**What I can and cannot reach:**
+
+- Staging and production run on one server, which is reached over SSH. The connection details are GitHub secrets (`DEPLOY_HOST`, `DEPLOY_KEY`, `STAGING_DEPLOY_PATH`, …), visible in `deploy-staging.yml` lines 73–185. I have no server access and will not ask for keys.
+- From here I can only:
+  - disable GitHub workflows (B.3.3), which needs your go-ahead because it is an outward-facing change to the repo settings;
+  - afterwards, check the public URLs with read-only `curl -I` requests.
+
+**New finding while preparing the runbook (High, risk; depends on the server's `.env`):**
+
+- `.env.example` sets `QUEUE_CONNECTION=database` and `CACHE_STORE=database`. If staging inherits these against the production database:
+  - **Queue:** staging and production share one `jobs` table. A staging worker (running `redesign` code) can pick up and execute production jobs, including the Stripe webhook job, and the reverse is also true.
+  - **Cache:** they share the `cache` table, including rate-limit counters, locks and cached config-derived values.
+  - **Scheduler:** if staging has a `schedule:run` cron, scheduled tasks run twice against production data.
+- This adds to A.5.2. It is one more reason the database connection, not just the website, must be cut.
+
+### B.3.1 Staging offline (on the server, by you)
+
+1. **Check the maintenance driver first:** `grep APP_MAINTENANCE_ "$STAGING_DEPLOY_PATH/.env"`.
+   - It must be `file` (the default).
+   - If it is `cache` with the `database` store, `artisan down` on staging **would also take production down**, because the flag would live in the shared cache table. In that case, skip step 2 and disable the staging subdomain in the hosting panel instead.
+2. `cd "$STAGING_DEPLOY_PATH" && php artisan down`. In maintenance mode, queue workers stop pulling jobs and scheduled tasks are skipped.
+3. Stop anything staging runs in the background:
+   - staging queue workers (supervisor or panel);
+   - any `schedule:run` cron line pointing at the staging path (`crontab -l`).
+4. **Cut the database connection.** In the staging `.env`, blank `DB_HOST`, `DB_DATABASE`, `DB_USERNAME` and `DB_PASSWORD`, or point them at a separate, empty staging database. Then run `php artisan config:clear`, because the deploy caches config.
+5. If staging uses **the same MySQL user** as production, removing it from the staging `.env` is not enough. Give production its own user (or rotate the password and update **only** the production `.env`), so the old credentials can no longer reach the data.
+6. Staging stays down until it has its own database. Under D-2 it will not be redeployed from the old repo at all.
+
+### B.3.2 Close `/vendor/*` on production (on the server, by you, with no deploy)
+
+**Why not a code hot-fix?** It would mean committing to `main`. A push to `main` triggers `deploy.yml`, which runs `migrate --force` by default (`run_migrations: default true`) and re-runs the Scout imports. That is a production deployment with migrations, which this phase must avoid.
+
+**Use a web-server rule instead.** The site runs Apache (the deploy copies `public/.htaccess` into the web root), and nothing under `public/` is named `vendor`, so blocking the route prefix affects no assets. In the **web root** `.htaccess`, directly after `RewriteEngine On`, add:
+
+```apache
+# NEXO D-12 containment 2026-11-01: vendor workspace closed pending v2
+# Optional staff allow-list: uncomment and set your IP
+# RewriteCond %{REMOTE_ADDR} !^203\.0\.113\.10$
+RewriteRule ^vendor(/.*)?$ - [F,L]
+```
+
+- This returns 403 for every `/vendor/*` request, including Inertia XHR requests. Filament admin (`/admin`), the storefront and checkout are untouched.
+- The rule is undone by deleting those lines.
+- **Every production deploy overwrites this `.htaccess`** (`cp public/.htaccess $DEPLOY_WEBROOT/.htaccess`). That is why B.3.3 matters.
+- **Limitation:** this closes the hole for every vendor, legitimate ones included. Use the IP allow-list for yourself. Real vendor authorization belongs to v2.
+
+### B.3.3 Freeze the old repository's deploy pipelines (I can do this, with your go-ahead)
+
+```bash
+gh workflow disable "Deploy Staging" -R AdilAzhari/nexo-ecommerce
+gh workflow disable "Deploy"         -R AdilAzhari/nexo-ecommerce
+```
+
+- This stops a green CI on `redesign` from redeploying staging (which would undo B.3.1 and run `config:cache` against whatever `.env` is there).
+- It stops a push to `main` from deploying, migrating and overwriting the B.3.2 `.htaccess`.
+- It changes no code and no server, and `gh workflow enable` reverses it.
+- CI, Auto Format and PR Checks remain active.
+
+### B.3.4 Verification after B.3.1–B.3.3
+
+I can run these read-only checks once you have done the server steps:
+
+- `curl -sI https://store.aljebal-albeedos.com/vendor/dashboard` → expect `403`.
+- `curl -sI https://store.aljebal-albeedos.com/` → expect `200` (storefront unaffected).
+- Staging URL → expect `503` (maintenance) or unreachable. I need the staging hostname from you; it is a secret.
+- `gh workflow list -R AdilAzhari/nexo-ecommerce` → both deploy workflows `disabled_manually`.
+
+---
+
+**End of Phase 0 addendum B. Phase 1 has not been started. Stopping for owner review.**
diff --git a/docs/discovery/PHASE-1-REVIEW.md b/docs/discovery/PHASE-1-REVIEW.md
new file mode 100644
index 0000000..6dddac7
--- /dev/null
+++ b/docs/discovery/PHASE-1-REVIEW.md
@@ -0,0 +1,158 @@
+# Phase 1 Review: Product Specification and Architectural Foundation
+
+- **Date:** 2026-11-01
+- **Branch:** `docs/phase-1-specification` (worktree `C:\laragon\www\nexo-v2`, from `origin/main@1cc7b4e`). Committed as four commits (one per document group) and opened as a PR to `main` on 2026-11-03.
+- **Scope:** documentation only. No application code, migrations, dependencies or configuration were changed.
+
+---
+
+## 1. Completed work
+
+| Brief Phase 1 deliverable | Where |
+|---|---|
+| Product Requirements Document | `docs/product/product-requirements.md` |
+| Functional Requirements Specification | `docs/product/functional-requirements.md` (FR-* with acceptance criteria; legacy REQ-VENDOR-* mapped) |
+| Non-functional Requirements | `docs/product/non-functional-requirements.md` |
+| User roles and permissions | `docs/architecture/security-model.md` (permission matrices) + ADR-0011 |
+| Customer and vendor workflows | `docs/product/user-journeys.md` (plus platform-staff journeys) |
+| Bounded contexts / Domain Context Map | `docs/architecture/domain-context-map.md` (13 modules + shared kernel, glossary) |
+| Dependency rules | `docs/architecture/dependency-rules.md` (layer rules, module matrix, events, read-model exceptions, frontend rules) |
+| Database ownership + initial database model | `docs/architecture/database-design.md` |
+| Business invariants | `docs/architecture/INVARIANTS.md` (INV-1…21, each with enforcement and proof) |
+| Integration contracts / API and frontend contract strategy | `docs/architecture/integration-contracts.md` + ADR-0018 |
+| Checkout and payment lifecycle | `docs/architecture/lifecycles/checkout-and-payment.md` (21-row scenario matrix) |
+| Inventory lifecycle | `docs/architecture/lifecycles/inventory.md` (13-row scenario matrix) |
+| Orders, fulfilment, returns, refunds | `docs/architecture/lifecycles/orders-fulfilment-and-returns.md` |
+| Financial model | `docs/architecture/financial-model.md` (balanced worked examples, disputes, payouts, reconciliation) |
+| System overview | `docs/architecture/system-overview.md` |
+| ADR conventions and ADRs | ADR-0006 (process) + ADR-0007…0021; index in `docs/architecture/README.md` |
+| Phase 0 report carried into this repository | `docs/discovery/PHASE-0-TECHNICAL-ASSESSMENT.md` (copy) |
+
+**Owner decisions applied this phase:**
+
+| Decision | Applied as |
+|---|---|
+| D-1 Vue 3 + Inertia + TS; D-2 this repository | ADR-0008 (Accepted) |
+| D-4 supersede the Sudan/aljebal-albeedos product docs | ADR-0007 (Accepted); banners on old docs |
+| D-5 MYR, EN-primary, AR/MS peers | ADR-0007 (Accepted) |
+| D-6 ledger + simulated payouts | ADR-0016 (core approved) |
+| D-7 promotions, reviews, wishlist and follows, loyalty and referrals in scope | PRD §6.1, FR-PRO/LOY/REV/ENG |
+
+## 2. Changed files
+
+**New (32):**
+
+- `docs/architecture/adr/0006…0021` (16 ADRs);
+- the 4 product documents above;
+- 7 architecture documents;
+- `docs/architecture/lifecycles/` (3 files);
+- `docs/discovery/PHASE-0-TECHNICAL-ASSESSMENT.md`;
+- this file.
+
+**Modified (12):**
+
+| File | Change |
+|---|---|
+| `docs/README.md` | Start-here links, `discovery/` row |
+| `docs/architecture/README.md` | Full index and ADR status table |
+| `docs/architecture/INVARIANTS.md` | Rewritten as INV-1…21, with a change table versus the 2026-08-30 version |
+| `docs/architecture/adr/ADR-TEMPLATE.md` | Brief §18 fields |
+| `docs/product/README.md` | Current vs superseded index (also closes an unclosed code fence) |
+| `docs/development/README.md` | Naming note → Vendor |
+| `docs/product/{vision,scope,goals,personas,problem-statement}.md`, `docs/architecture/marketplace-migration.md` | One "Superseded" banner line each; content untouched |
+
+**Untouched on purpose:**
+
+- Existing ADR-0001…0005: status changes are yours.
+- `docs/engineering/testing.md` and `database.md`: they still say SQLite and change only if ADR-0009 is accepted.
+- `docs/vendor-domain-design.md`: a duplicate of `architecture/vendor-domain-design.md`.
+- The empty `requirements/*` stubs.
+
+**Other repositories:**
+
+- Old repository `modular-ecommerce-system`: no change in this phase.
+- `C:\laragon\www\Nexo` (`feat/vendor-frontend` checkout): untouched. The worktree adds only `.git/worktrees/nexo-v2` metadata and the new local branch.
+
+## 3. Architectural decisions (explained)
+
+These are the significant ones, each with its reason. The trade-offs and alternatives are in each ADR.
+
+1. **Modular monolith with `Contracts`-only cross-module imports, enforced by Pest arch tests (ADR-0010).** Boundaries become visible and CI-checked without purist repository layers. While writing the dependency matrix I found and removed **two cycles**:
+   - Ordering↔Finance: Finance now reads its own ledger instead of calling Ordering.
+   - Ordering↔Payments: the `OrderPayments` port is owned by Payments and implemented by Ordering.
+
+   I also moved the reservation sweeper from Inventory to Ordering, so Inventory never depends on Payments.
+2. **Fail-closed vendor context (ADR-0011).** This directly answers Phase 0 S1: no global scope, no null-means-all fallback, scoped bindings, and an isolation suite as a merge gate.
+3. **MySQL for every database test (ADR-0009).** The old repository's concurrency tests passed on SQLite with real bugs present. Correctness claims must run on the real engine.
+4. **Checkout saga (ADR-0015):**
+   - local transaction;
+   - provider call after commit;
+   - signed webhook as the only source of payment truth;
+   - idempotency keys at the HTTP, provider and event levels.
+
+   Every brief §11 scenario has a defined outcome (P1–P21).
+5. **Inventory as on-hand/reserved with conditional updates (ADR-0014).** Overselling is impossible by construction, and duplicate movements are blocked by a unique key.
+6. **Refund cap owned by Ordering via guarded counters (ADR-0015 §9).** I first wrote a design where Payments locked Ordering's table. That breaks the module rules, so it was corrected.
+7. **Internal double-entry ledger (ADR-0016).** The worked examples in `financial-model.md` were checked by hand to balance: 113.00 / 20.00 / 45.00 / 11.11. They become executable tests in Phase 5.
+8. **Outbox + inbox (ADR-0017).** This replaces the old write-only event table (Phase 0 C2).
+9. **Generated TypeScript types from PHP data objects (ADR-0018).** This addresses the 22 type errors and the prop drift found in the old repository.
+
+## 4. Tests and verification
+
+- **No application tests were run or needed.** This phase changed only Markdown, and the worktree has no `vendor/` installed.
+- **Verification performed:**
+  - A script resolved every relative Markdown link under `docs/`. **1 broken:** `marketplace-migration.md` → `../REDESIGN_BRIEF.md`. It pre-exists inside a superseded document and I left it.
+  - Line endings were normalised to LF.
+  - The financial worked examples balance (checked manually).
+  - FR → INV cross-references were checked by hand.
+  - The dependency matrix was checked by hand for cycles.
+- **Not verified, so these are assumptions:**
+  - Filament, `spatie/laravel-data` and `spatie/laravel-typescript-transformer` compatibility with Laravel 13 / PHP 8.5 (ADR-0018, ADR-0020, checked in Phase 3).
+  - MYR card + 3-D Secure support in Stripe test mode (D-14, Phase 5).
+  - The fee figure in the worked example (RM 4.09) is illustrative.
+
+## 5. Known limitations
+
+- These are specifications. Nothing is implemented, and none of the guarantees exist yet.
+- Several product parameters are **proposals** (P-1…P-8 in the PRD) and need your confirmation.
+- Tax is out of scope, and prices are tax-inclusive (ADR-0007). A reviewer may notice this, so the README must state it.
+- One vendor per user; staff cannot shop; guest checkout is excluded (P-1).
+- The admin panel is English-only in v2 (ADR-0020).
+- Loyalty points are not a ledger liability (financial-model §1). This is a deliberate simplification.
+- MySQL FULLTEXT search with limited Arabic stemming (ADR-0019).
+
+## 6. Unresolved questions (need your decision)
+
+| ID | Question | My recommendation |
+|---|---|---|
+| ADR status | Accept ADR-0009…0021? | Accept all, or name the ones to revise |
+| ADR-0005 | Accept the Vendor naming, mark ADR-0002 superseded, rename the file to `0005-vendor-naming.md` | Yes |
+| D-3 | Laravel 13 / PHP 8.5 / MySQL 8.4 (ADR-0009) | Yes |
+| D-8 | Search: MySQL first (ADR-0019) | Yes |
+| D-9 | Platform bears Stripe fees | Yes |
+| D-10 | Commission reversed exactly on refunds; shipping excluded from commission | Yes |
+| D-11 | Vendor bears lost-dispute goods value; platform bears the fee | Yes |
+| P-1…P-8 | Product parameters in PRD §6.3 | As proposed |
+| D-12 follow-up | **Your GitHub account `AdilAzhariOmsan` has read-only access to `AdilAzhari/nexo-ecommerce`.** I could not disable "Deploy Staging" or "Deploy". Run the two `gh workflow disable` commands as the repository owner, or disable them in GitHub → Actions. The server steps in Phase 0 Addendum B.3.1–B.3.2 are still pending on your side. | Do both before Phase 3 |
+| D-13 step 3 | Copy `C:\laragon\backups\nexo-2026-11-01\` off-machine | Pending on your side |
+| D-15 | Commit author identity. **The repository's local git config is `adelazhary1997@gmail.com`.** Commits made for you will use `adilazhariosman@gmail.com` explicitly. Do you want the history rewritten before going public? | Decide before Phase 3 |
+| Commit | May I commit this phase to `docs/phase-1-specification` and open a PR to `main`? | Yes, as one commit per document group |
+| Tooling | The repository's `CLAUDE.md` asks for Laravel Boost (`composer require laravel/boost --dev`). It is a dependency, so it was not installed in this docs-only phase. | Install at the start of Phase 3 if you want it |
+| 61 React commits | Push `feat/vendor-frontend` to a reference branch on GitHub (they are only bundled locally) | Yes |
+
+## 7. Review checklist
+
+- [ ] PRD objectives, audience and scope (in and out) match your intent; P-1…P-8 confirmed or changed.
+- [ ] Functional requirements: priorities (M/S/C) acceptable; nothing missing from your expectations for the three surfaces.
+- [ ] NFR targets are acceptable (performance numbers are assumptions until Phase 9 measures them).
+- [ ] Roles and permission matrices (`security-model.md`) reflect how you want vendors and staff to work.
+- [ ] 13 modules and their ownership (`domain-context-map.md`) make sense; the dependency matrix is acceptable.
+- [ ] Database model: naming and constraints acceptable; no table you expected is missing.
+- [ ] Invariants INV-1…21 are the right guarantees.
+- [ ] Lifecycle scenario matrices cover the failure cases you care about.
+- [ ] Financial model: posting rules and worked examples are acceptable; D-9/10/11 decided.
+- [ ] ADR-0005 and 0009…0021: accept, revise or reject each.
+- [ ] Containment actions (D-12) and the off-machine backup (D-13 step 3) done on your side.
+- [ ] Authorise (or not) committing this branch; decide D-15.
+
+**Phase 1 stops here. Phase 2 (Brand Identity and Design System) has not been started.**
diff --git a/docs/product/README.md b/docs/product/README.md
index 47c6555..74ead24 100644
--- a/docs/product/README.md
+++ b/docs/product/README.md
@@ -21,3 +21,20 @@ Stories
 Tasks
       ↓
 Implementation
+```
+
+## Nexo 2.0 product documents (current)
+
+| Document | Purpose |
+|---|---|
+| [`product-requirements.md`](product-requirements.md) | PRD: objectives, audience, roles, surfaces, scope, release gate |
+| [`functional-requirements.md`](functional-requirements.md) | FR-* requirements with acceptance criteria |
+| [`non-functional-requirements.md`](non-functional-requirements.md) | NFR-*: correctness, security, performance, a11y, i18n, quality gates |
+| [`user-journeys.md`](user-journeys.md) | Customer, vendor and platform-staff workflows with failure branches |
+
+## Superseded (history only)
+
+`vision.md`, `scope.md`, `goals.md` and `personas.md` (aljebal-albeedos framing) were superseded on
+2026-11-01 by ADR-0007. `problem-statement.md` and the empty stubs under `requirements/` are
+also superseded: `requirements/vendor/onboarding.md` and
+`requirements/platform/vendor-management.md` are carried into FR-VEN.
diff --git a/docs/product/functional-requirements.md b/docs/product/functional-requirements.md
new file mode 100644
index 0000000..7479161
--- /dev/null
+++ b/docs/product/functional-requirements.md
@@ -0,0 +1,220 @@
+# Functional Requirements Specification
+
+- **Status:** Draft for owner review (Phase 1)
+- **Date:** 2026-11-01
+- **Source:** [product-requirements.md](product-requirements.md)
+
+**Priority** uses MoSCoW: M = must, S = should, C = could. Every M requirement is in the v2 release gate.
+
+**Acceptance criteria** are written so that each can become one or more Pest tests. **[INV-n]** refers to [`../architecture/INVARIANTS.md`](../architecture/INVARIANTS.md).
+
+**Legacy IDs.** `REQ-VENDOR-*` and `REQ-VENDOR-MGMT-*` from `requirements/vendor/onboarding.md` and `requirements/platform/vendor-management.md` are carried into FR-VEN. Their mapping is listed in each row.
+
+---
+
+## FR-ID: Identity and accounts
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-ID-01 | M | Visitors can register with name, email and password, and must verify their email before checkout | Unverified users are redirected to verification when they reach checkout; the verification link is signed and expires in 60 minutes |
+| FR-ID-02 | M | Login, logout, password reset, with rate limiting | Login is throttled to 5 attempts per minute per email+IP; reset tokens are single-use and expire |
+| FR-ID-03 | M | Customers manage profile and address book (Malaysian address format, zone derived from state) | Address state determines the shipping zone; at most one default address |
+| FR-ID-04 | M | Platform staff accounts are created by an Admin, require 2FA, and cannot register publicly | A staff login without 2FA confirmation cannot reach `/admin` |
+| FR-ID-05 | M | Staff accounts cannot place orders or hold vendor membership [INV-2] | Attempting either fails with a domain error; covered by tests |
+| FR-ID-06 | S | Customers can delete their account; personal data is anonymised and order records are retained | After deletion the name and email are anonymised; orders and ledger remain intact |
+| FR-ID-07 | M | The UI language is selectable (en/ar/ms) and persisted per user; Arabic renders RTL | `<html lang dir>` reflects the choice; the preference survives logout and login |
+
+## FR-VEN: Vendor onboarding and management
+
+| ID | P | Requirement | Acceptance criteria | Legacy |
+|---|---|---|---|---|
+| FR-VEN-01 | M | A signed-in customer can submit a vendor application (store name, description, contact, category focus) | Submission does not create a Vendor; one open application per user | REQ-VENDOR-001 |
+| FR-VEN-02 | M | Platform Operations approves or rejects applications with a reason | Approve creates a Vendor in `pending`, plus an Owner membership for the applicant, in one transaction. Reject creates no Vendor and notifies the applicant. | REQ-VENDOR-001, 001A |
+| FR-VEN-03 | M | A Vendor has a stable id and a unique slug that never changes | The slug has a unique constraint; renaming the vendor keeps the slug | REQ-VENDOR-002 |
+| FR-VEN-04 | M | Vendor lifecycle is `pending → approved ⇄ suspended`; other transitions are rejected and leave the status unchanged | Every invalid pair is tested; transitions are audit-logged | REQ-VENDOR-003…007, MGMT-002…005, 009 |
+| FR-VEN-05 | M | Operating eligibility: only `approved` vendors' products are sellable. A `suspended` vendor can view history and fulfil existing orders, but cannot edit or create products or receive new orders. | Suspension hides products from the storefront (search documents updated); existing VendorOrders stay fulfillable | REQ-VENDOR-008, MGMT-010 |
+| FR-VEN-06 | M | Vendor identity and history are preserved through suspension; vendors are never hard-deleted | No delete action exists; foreign keys use RESTRICT | REQ-VENDOR-009, MGMT-006 |
+| FR-VEN-07 | M | The Vendor Owner invites team members by email with a role (manager, fulfilment, finance, support); invitations expire in 7 days | The invitee must not already belong to a vendor or be staff; exactly one owner per vendor | REQ-VENDOR-010 |
+| FR-VEN-08 | M | The Owner changes roles and deactivates members; the Owner role is transferred explicitly | A deactivated member gets 403 on `/vendor` immediately (next request) | |
+| FR-VEN-09 | M | Vendors manage their store profile: logo, banner, description, return-policy text | Shown on the public store page | |
+| FR-VEN-10 | M | Vendor data is isolated: no vendor context can read or modify another vendor's records [INV-1] | Isolation test suite (merge gate) | MGMT-007 |
+
+## FR-CAT: Catalogue
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-CAT-01 | M | Platform Operations manages a category tree (max depth 3) with names in en/ar/ms and an optional commission override | A category with products cannot be deleted, only deactivated |
+| FR-CAT-02 | M | Platform defines option attributes (for example Colour, Size) with values, usable for variants | Variant option combinations are unique per product |
+| FR-CAT-03 | M | Vendors create products: title, description, brand, category (leaf), images (≤ 8, ordered), status `draft/active/inactive` | Only an `approved` vendor can set `active`; image MIME type and size are validated; images are stored privately until processed |
+| FR-CAT-04 | M | Products have ≥ 1 variant; each variant has a SKU (unique per vendor), price, optional compare-at price (> price), weight and option values | Price > 0; compare-at > price or null |
+| FR-CAT-05 | M | A product is **sellable** iff: product `active` ∧ not blocked ∧ vendor `approved` ∧ ≥ 1 variant active | The storefront and checkout use the same sellability rule (single implementation) |
+| FR-CAT-06 | M | Platform Operations can block or unblock a product with a reason (reactive moderation, P-2) | A blocked product disappears from the storefront; the vendor sees the reason |
+| FR-CAT-07 | M | Price changes never affect existing orders [INV-6] | Snapshot test |
+| FR-CAT-08 | S | Vendors import products by CSV with a validation report (dry-run first) | Invalid rows are reported with line numbers; no partial import unless confirmed |
+
+## FR-INV: Inventory
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-INV-01 | M | Each variant has on-hand and reserved quantities; available = on-hand − reserved, never negative [INV-7] | DB CHECK constraint present; tests attempt violations |
+| FR-INV-02 | M | Checkout reserves stock atomically; insufficient stock fails the whole checkout and names the short lines | Parallel test: N buyers for the last unit, exactly one succeeds |
+| FR-INV-03 | M | Reservations expire after 15 minutes (P-4), with one extension while payment is processing | Sweeper test with a frozen clock |
+| FR-INV-04 | M | Payment success consumes reservations; failure, expiry or cancellation releases them; each happens at most once | Duplicate events give a single movement |
+| FR-INV-05 | M | Vendors adjust stock by delta (receive, damage, correction with reason) or by absolute count with conflict detection | A stale count returns 409 with the current value; on-hand below reserved is rejected |
+| FR-INV-06 | M | Every change records a stock movement with type, deltas, reference and actor; the vendor can view the history per variant | Movement sums equal on-hand (reconciliation test) |
+| FR-INV-07 | S | Low-stock threshold per variant, shown in the vendor dashboard | |
+| FR-INV-08 | M | A returned item is restocked only when the vendor marks it received and resellable | |
+
+## FR-SHP: Shipping
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-SHP-01 | M | Each vendor sets a flat rate per zone (Peninsular, East Malaysia) and an optional free-shipping threshold | Checkout quotes per VendorOrder, using the vendor's goods subtotal before discounts |
+| FR-SHP-02 | M | A vendor that has no rate for the customer's zone cannot be checked out to that address | Checkout shows which vendor cannot ship there |
+| FR-SHP-03 | M | Vendors enter carrier and tracking number when marking shipped | Required fields; the customer sees them on the order timeline |
+
+## FR-CART: Cart
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-CART-01 | M | Visitors and customers add variants from any number of vendors to one cart, grouped by vendor in the UI | |
+| FR-CART-02 | M | A guest cart merges into the customer cart at login (quantities summed, capped at available) | Merge is idempotent |
+| FR-CART-03 | M | The cart revalidates on view: price changes, unavailable items and quantity above available are flagged, and checkout is blocked until acknowledged | |
+| FR-CART-04 | M | Quantity per line is limited to 1–20 (configurable) and to available stock | |
+| FR-CART-05 | M | A cart is owned by exactly one session or customer; no endpoint accepts a cart id from the client | Test: another user's cart cannot be read or checked out |
+
+## FR-CHK: Checkout
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-CHK-01 | M | Checkout requires a verified customer account (P-1) | |
+| FR-CHK-02 | M | The customer selects a shipping address; the system quotes shipping per vendor and shows a breakdown per vendor and in total | |
+| FR-CHK-03 | M | The customer may apply one coupon and redeem points; the system shows the allocation as a total discount | Invalid coupons give a reason code |
+| FR-CHK-04 | M | Placing the order re-prices server-side; if the total differs from the confirmed total, nothing is charged and the customer reviews again | 409 test |
+| FR-CHK-05 | M | Placing is idempotent per checkout key; double-submit creates one OrderGroup [INV-9] | Parallel test |
+| FR-CHK-06 | M | One payment for the group total by card (Stripe test mode, 3-D Secure supported) | |
+| FR-CHK-07 | M | The payment outcome is determined only by verified provider events; the customer sees "confirming" until then | Closing the browser does not change the outcome (test) |
+| FR-CHK-08 | M | After a declined payment the customer can retry with another card until the reservation expires | One active attempt at a time |
+| FR-CHK-09 | M | If the provider is unavailable the customer sees a retryable error; no order is paid and stock stays reserved until TTL | Fake-provider outage test |
+| FR-CHK-10 | M | Successful payment creates one VendorOrder per vendor in `awaiting_fulfilment`, notifies each vendor and emails the customer one confirmation | |
+
+## FR-ORD: Orders and fulfilment
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-ORD-01 | M | Customers see their orders as groups expanding into vendor shipments, each with its own status timeline | |
+| FR-ORD-02 | M | Vendors see only their VendorOrders, filterable by status and date, with the shipping address and items | No sibling or group totals are exposed [INV-1] |
+| FR-ORD-03 | M | Vendor transitions follow the state machine in ADR-0012; invalid transitions are rejected | Every pair is tested; concurrent transition test |
+| FR-ORD-04 | M | A vendor cancels with a reason before shipping, which triggers a full refund of that VendorOrder and releases stock | Siblings unaffected [INV-4] |
+| FR-ORD-05 | M | A customer cancels a VendorOrder while `awaiting_fulfilment` (P-8) | |
+| FR-ORD-06 | M | Delivered is confirmed by the vendor or the customer, or automatically after 10 days shipped (P-3) | |
+| FR-ORD-07 | M | Completed is set automatically when the return window has ended with no open return or dispute; this triggers payable maturity and points award | |
+| FR-ORD-08 | M | Every transition is recorded in the status history with actor and reason | |
+| FR-ORD-09 | S | Vendors export orders as CSV for a date range | Only their own orders |
+
+## FR-RET: Returns
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-RET-01 | M | A customer requests a return for delivered lines within the return window (quantity per line, reason, optional photos) | No more than the purchased minus already-returned quantity |
+| FR-RET-02 | M | The vendor approves or rejects (with reason) within 3 days; after 3 days with no response the request escalates to Platform Operations | |
+| FR-RET-03 | M | On approval and receipt, the vendor marks items received (resellable or not), which triggers the refund of those lines | |
+| FR-RET-04 | M | Platform Operations can override a vendor rejection | Audit-logged |
+| FR-RET-05 | S | "Not received" claim on a shipped order past its expected window, handled as a return without item receipt | |
+
+## FR-REF: Refunds
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-REF-01 | M | Refunds are per VendorOrder and per line (goods + proportional shipping when all lines are refunded); the amount never exceeds the refundable remainder [INV-5] | Concurrent refund test |
+| FR-REF-02 | M | Initiators: system (cancellation, return receipt, stock unavailable after payment), Vendor Owner/Finance (goodwill, capped), Platform Finance (override) | |
+| FR-REF-03 | M | Refund lifecycle `requested → approved → submitted → succeeded / failed`; a provider timeout leaves it `submitted` until confirmed | |
+| FR-REF-04 | M | Refunds reverse the refunded lines' commission, discount allocation and points exactly | Ledger tests |
+| FR-REF-05 | M | No refund while a dispute is open on the payment | |
+| FR-REF-06 | M | Customer, vendor and finance see refund status per VendorOrder | |
+
+## FR-PAY / FR-FIN: Payments and finance
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-PAY-01 | M | Webhooks are signature-verified; invalid signatures get 400 and nothing is stored | |
+| FR-PAY-02 | M | Each provider event is processed at most once in effect [INV-9] | Concurrent duplicate-delivery test |
+| FR-PAY-03 | M | An amount or currency mismatch between provider and attempt never marks paid; it raises a reconciliation exception | |
+| FR-FIN-01 | M | Every money movement posts a balanced ledger transaction exactly once [INV-10] | |
+| FR-FIN-02 | M | The commission rate (vendor → category → default) is frozen per VendorOrder [INV-6] | Changing rates affects new orders only |
+| FR-FIN-03 | M | Vendors see balances (pending, available, held, receivable, paid out) and a statement of ledger lines, exportable as CSV | Balance = Σ statement |
+| FR-FIN-04 | M | A weekly simulated payout run pays each vendor's available balance ≥ the minimum, net of receivables; it is idempotent | Running it twice concurrently produces one payout per vendor |
+| FR-FIN-05 | M | Disputes hold the allocated vendor funds and resolve per ADR-0016 | |
+| FR-FIN-06 | M | Reconciliation: nightly invariant checks and provider matching; exceptions are listed for Finance to resolve | Injected mismatch is detected |
+| FR-FIN-07 | M | Platform Finance edits the default and override commission rates; changes are audit-logged | |
+| FR-FIN-08 | S | Platform finance dashboard: GMV, commission, refunds, payables, payouts by period | |
+
+## FR-PRO: Promotions
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-PRO-01 | M | Platform Operations creates promotions: coupon code or automatic; percentage or fixed; minimum spend; target all, categories or vendors; total and per-customer usage limits; date window | |
+| FR-PRO-02 | M | One coupon per checkout; the best automatic promotion is applied when no coupon is used (no stacking in v2) | |
+| FR-PRO-03 | M | Discounts are allocated to eligible lines by largest remainder and stored per line [INV-8] | Property test: sum exact |
+| FR-PRO-04 | M | Usage limits hold under concurrency (redemption reserved at checkout, released on expiry) | Parallel test on the last allowed use |
+| FR-PRO-05 | M | Promotions are platform-funded; vendor payable is unaffected | Ledger test |
+
+## FR-LOY: Loyalty and referrals
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-LOY-01 | M | Points are earned on completed VendorOrders at the configured rate (P-5), recorded in a points ledger | Award is idempotent per VendorOrder |
+| FR-LOY-02 | M | Points are redeemed at checkout up to the cap; held at placement, confirmed on payment, released on expiry | |
+| FR-LOY-03 | M | A refund of redeemed-point lines returns the points; a refund after award claws back the earned points (balance may not go below zero; the shortfall is recorded) | |
+| FR-LOY-04 | M | Each customer has a referral code; the referee benefit and referrer award follow P-6; self-referral and repeat referral are blocked | |
+| FR-LOY-05 | S | Points balance and history page | |
+
+## FR-REV: Reviews
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-REV-01 | M | Customers review a purchased product after delivery: one review per purchased VendorOrder line, rating 1–5, text, optional photos | Unique (line) |
+| FR-REV-02 | M | Vendors reply once per review (editable) | |
+| FR-REV-03 | M | Platform Operations hides or unhides reviews with a reason; product rating aggregates only visible reviews | |
+| FR-REV-04 | S | Customers report reviews | |
+
+## FR-ENG: Wishlist and follows
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-ENG-01 | M | Customers add and remove products to a wishlist; unavailable items are shown as such | |
+| FR-ENG-02 | M | Customers follow or unfollow vendor stores; the account page shows new products from followed stores | |
+
+## FR-SRCH: Search and discovery
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-SRCH-01 | M | Keyword search across sellable products with facets: category, price range, vendor, rating ≥ n, in stock; sorting by relevance, price, newest, rating | Hidden products never returned |
+| FR-SRCH-02 | M | Category pages list with the same facets | |
+| FR-SRCH-03 | M | Search documents update within about 1 minute of product, stock, vendor or review changes | Outbox-driven |
+| FR-SRCH-04 | S | Arabic queries normalise letter forms and diacritics | |
+
+## FR-NOT: Notifications
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-NOT-01 | M | In-app notifications and email for: order placed or paid, vendor order received, shipped, delivered, cancelled, return updates, refund succeeded, payout made, application decision, team invite | Sent once per event (inbox de-duplication) |
+| FR-NOT-02 | M | Emails are localised in the recipient's language | |
+| FR-NOT-03 | S | Users manage email preferences for non-transactional notifications | |
+
+## FR-ADM: Platform administration
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-ADM-01 | M | Staff roles and permissions per `security-model.md`; every action is policy-checked | Denied-access tests per resource |
+| FR-ADM-02 | M | Audit log for: vendor lifecycle, moderation, refunds, commission changes, payouts, reconciliation resolutions, impersonation, staff changes | Each action writes an audit row (actor, before/after, IP) |
+| FR-ADM-03 | M | Admin impersonates vendor members or customers for support; impersonation is banner-marked and audited, and money-moving actions are blocked | |
+| FR-ADM-04 | M | Operational health: outbox backlog and dead letters, failed jobs, last webhook received, reconciliation exceptions, sweeper last run | |
+| FR-ADM-05 | M | Order lookup across vendors by reference, customer email or provider payment id | |
+
+## FR-DEMO: Demo environment
+
+| ID | P | Requirement | Acceptance criteria |
+|---|---|---|---|
+| FR-DEMO-01 | M | One command builds the demo from an empty database (ADR-0021), deterministically | CI runs it; invariants pass |
+| FR-DEMO-02 | M | Documented demo logins per role; demo-only banner; Stripe test cards documented | |
diff --git a/docs/product/goals.md b/docs/product/goals.md
index 3d7f215..381f172 100644
--- a/docs/product/goals.md
+++ b/docs/product/goals.md
@@ -1,5 +1,7 @@
 # Goals & Non-Goals
 
+> **Superseded 2026-11-01** by [ADR-0007](../architecture/adr/0007-product-positioning-currency-and-locales.md) (owner decision D-4) and the Nexo 2.0 product documents: [product-requirements.md](../product/product-requirements.md), [functional-requirements.md](../product/functional-requirements.md). Kept for history only; do not implement from this file.
+
 **Status:** Ratified 2026-08-30
 
 ---
diff --git a/docs/product/non-functional-requirements.md b/docs/product/non-functional-requirements.md
new file mode 100644
index 0000000..0ee48de
--- /dev/null
+++ b/docs/product/non-functional-requirements.md
@@ -0,0 +1,91 @@
+# Non-functional Requirements
+
+- **Status:** Draft for owner review (Phase 1)
+- **Date:** 2026-11-01
+
+These requirements are measurable. Where a target is an assumption rather than a measurement, it says so. Targets apply to the **demo environment** at demo scale. Demo scale is about 12 vendors, ≤ 1,000 products and ≤ 5,000 orders (PRD §8).
+
+## NFR-COR: Correctness (highest priority)
+
+| ID | Requirement | Verification |
+|---|---|---|
+| NFR-COR-01 | No overselling under concurrent checkout | Parallel-process MySQL tests (ADR-0014) |
+| NFR-COR-02 | Every ledger transaction balances; every business event posts at most once | Property tests + nightly invariant job |
+| NFR-COR-03 | Every brief §10 and §11 scenario has a defined outcome and an automated test | Scenario matrix in `lifecycles/*.md`, each row linked to a test name in Phase 4–5 |
+| NFR-COR-04 | Retries (user, queue, webhook, scheduler) are idempotent | Duplicate-execution tests per use case |
+
+## NFR-SEC: Security
+
+| ID | Requirement | Verification |
+|---|---|---|
+| NFR-SEC-01 | OWASP ASVS 4.0 Level 1 controls for authentication, session, access control, validation, and error handling and logging | Phase 9 checklist |
+| NFR-SEC-02 | Default-deny authorisation; vendor isolation suite is a merge gate | ADR-0011 |
+| NFR-SEC-03 | Staff 2FA mandatory; staff sessions expire after 2 hours idle | Tests |
+| NFR-SEC-04 | Webhook signature verification; CSRF on all state-changing web routes; rate limits on auth, checkout, coupon validation and review creation | Tests |
+| NFR-SEC-05 | Uploads: images only (JPEG, PNG, WebP), ≤ 5 MB, re-encoded server-side, randomised names, EXIF stripped | Tests |
+| NFR-SEC-06 | No secrets in the repository; live payment keys refused at boot (ADR-0021); `composer audit` and `npm audit --omit=dev` gate CI | CI |
+| NFR-SEC-07 | Production error pages never expose exception messages or stack traces (Phase 0 S-finding) | Test with `APP_DEBUG=false` |
+| NFR-SEC-08 | Security headers: CSP (nonce-based for Vite), HSTS on demo, `X-Content-Type-Options`, `Referrer-Policy`, `frame-ancestors 'none'` | Header tests |
+
+## NFR-PERF: Performance (assumption-based targets; measured in Phase 9)
+
+| ID | Requirement |
+|---|---|
+| NFR-PERF-01 | Server time p95 ≤ 300 ms for storefront pages (home, category, product, search) at demo scale |
+| NFR-PERF-02 | `POST /checkout` server time p95 ≤ 800 ms, excluding the provider call |
+| NFR-PERF-03 | No N+1 queries on list pages; enforced with `Model::preventLazyLoading()` outside production, plus query-count assertions on key pages |
+| NFR-PERF-04 | Largest Contentful Paint ≤ 2.5 s on a mid-range mobile profile (Lighthouse) for home and product pages; responsive images in WebP with explicit dimensions |
+| NFR-PERF-05 | Initial JS for the storefront entry ≤ 200 KB gzip; vendor and admin code split from storefront |
+
+## NFR-REL: Reliability and operability
+
+| ID | Requirement |
+|---|---|
+| NFR-REL-01 | Outbox, sweeper and reconciliation jobs are idempotent and safe to run concurrently |
+| NFR-REL-02 | Health endpoint reports DB, queue, outbox age, scheduler heartbeat and last webhook time |
+| NFR-REL-03 | Structured JSON logs with a correlation id propagated from request → jobs → outbox consumers |
+| NFR-REL-04 | Failed jobs and dead-lettered messages are visible and retryable from the admin panel |
+| NFR-REL-05 | Demo database backed up daily and restorable via the documented procedure (or rebuilt from the seed) |
+
+## NFR-A11Y: Accessibility
+
+| ID | Requirement |
+|---|---|
+| NFR-A11Y-01 | WCAG 2.2 AA for storefront and vendor dashboard key journeys (browse, cart, checkout, order tracking, vendor fulfilment) |
+| NFR-A11Y-02 | Full keyboard operation, visible focus, semantic landmarks, labelled form controls, error messages linked with `aria-describedby` |
+| NFR-A11Y-03 | Colour contrast ≥ 4.5:1 for text (verified against Phase 2 tokens) |
+| NFR-A11Y-04 | Automated axe checks in browser tests; manual screen-reader pass (NVDA) on checkout in Phase 9 |
+
+## NFR-I18N: Internationalisation
+
+| ID | Requirement |
+|---|---|
+| NFR-I18N-01 | en, ar and ms have 100 % key coverage for the UI; CI fails on missing keys |
+| NFR-I18N-02 | RTL uses CSS logical properties and direction-aware components (icons, carousels, steppers, progress); no physical `left/right` utilities in components (lint rule) |
+| NFR-I18N-03 | Currency, number and date formatting is locale-aware through `Intl`; dates display in MYT |
+| NFR-I18N-04 | Locale in the storefront URL (`/ms/...`, `/ar/...`; `en` unprefixed) for shareable links; `hreflang` alternates |
+
+## NFR-MNT: Maintainability and quality gates
+
+| ID | Requirement |
+|---|---|
+| NFR-MNT-01 | CI gates (all blocking): Pint, PHPStan/Larastan level 8 (raised from the current 6 during Phase 3), Pest (unit + feature + arch on MySQL), concurrency suite, `vue-tsc`, ESLint, Vitest, Vite build, generated-types diff, translation-key check, `composer audit`, `npm audit` |
+| NFR-MNT-02 | Module dependency rules enforced by arch tests (ADR-0010) |
+| NFR-MNT-03 | Every boundary decision has an ADR; PRs reference the ADRs they implement |
+| NFR-MNT-04 | No test is skipped in CI without a linked issue; skipped tests are reported in CI output |
+
+## NFR-COMP: Compatibility
+
+| ID | Requirement |
+|---|---|
+| NFR-COMP-01 | Latest two versions of Chrome, Edge, Firefox and Safari; iOS Safari 17+; Android Chrome |
+| NFR-COMP-02 | Responsive from 360 px wide; storefront is mobile-first; vendor dashboard is fully usable at ≥ 768 px and functional on mobile for order fulfilment |
+
+## NFR-PRIV: Privacy and data
+
+| ID | Requirement |
+|---|---|
+| NFR-PRIV-01 | All demo personal data is fictional; no real customer data is ever imported |
+| NFR-PRIV-02 | Vendors see only the customer data needed to fulfil (name, shipping address, phone); never email or other orders |
+| NFR-PRIV-03 | Card data never touches Nexo servers (Stripe Elements / Payment Element) |
+| NFR-PRIV-04 | Logs never contain passwords, tokens, full addresses or provider secrets |
diff --git a/docs/product/personas.md b/docs/product/personas.md
index e4594fa..980904b 100644
--- a/docs/product/personas.md
+++ b/docs/product/personas.md
@@ -1,5 +1,7 @@
 # Personas
 
+> **Superseded 2026-11-01** by [ADR-0007](../architecture/adr/0007-product-positioning-currency-and-locales.md) (owner decision D-4) and the Nexo 2.0 product documents: [product-requirements.md](../product/product-requirements.md), [functional-requirements.md](../product/functional-requirements.md). Kept for history only; do not implement from this file.
+
 **Status:** Ratified 2026-08-30
 
 Four primary personas. The vendor-team sub-roles already exist in code
diff --git a/docs/product/problem-statement.md b/docs/product/problem-statement.md
index a48999b..9d87bcb 100644
--- a/docs/product/problem-statement.md
+++ b/docs/product/problem-statement.md
@@ -1,5 +1,7 @@
 # Problem Statement
 
+> **Superseded 2026-11-01** by [ADR-0007](../architecture/adr/0007-product-positioning-currency-and-locales.md) (owner decision D-4) and [product-requirements.md](product-requirements.md). Kept for history only.
+
 **Status:** Ratified 2026-08-30
 
 ---
diff --git a/docs/product/product-requirements.md b/docs/product/product-requirements.md
new file mode 100644
index 0000000..4e1e2d8
--- /dev/null
+++ b/docs/product/product-requirements.md
@@ -0,0 +1,175 @@
+# Nexo — Product Requirements Document
+
+- **Status:** Draft for owner review (Phase 1)
+- **Date:** 2026-11-01
+- **Supersedes:** `vision.md`, `scope.md`, `goals.md`, `personas.md` (aljebal-albeedos framing), per ADR-0007
+- **Related:** [functional-requirements.md](functional-requirements.md) · [non-functional-requirements.md](non-functional-requirements.md) · [user-journeys.md](user-journeys.md)
+
+---
+
+## 1. Product summary
+
+Nexo is a multi-vendor general-merchandise marketplace:
+
+- Independent vendors sell through one shared storefront.
+- Customers discover products across vendors, buy from several vendors in one checkout and pay once.
+- Each vendor fulfils its own part of the order.
+- The platform collects payment, keeps a commission, and accounts for what it owes each vendor.
+
+Nexo is built as a **portfolio showcase**. It must look, behave and hold up under scrutiny like a credible commercial product. It is not operated as a real business:
+
+- all vendors, customers and orders are fictional;
+- payments run in Stripe test mode;
+- vendor payouts are simulated.
+
+## 2. Objectives
+
+| # | Objective | Evidence of success |
+|---|---|---|
+| O1 | Demonstrate correct marketplace commerce | Multi-vendor checkout, split vendor orders, independent fulfilment and refunds, all passing the failure scenarios in `docs/architecture/lifecycles/` |
+| O2 | Demonstrate trustworthy money handling | Ledger balances under property and concurrency tests; vendor statements reconcile to orders and refunds |
+| O3 | Demonstrate engineering quality | All CI gates green (tests on MySQL, static analysis, types, lint, arch rules); ADRs for every boundary decision |
+| O4 | Feel premium | New visual identity (Phase 2); polished storefront, vendor dashboard and admin; real RTL Arabic |
+| O5 | Be reproducible | Demo rebuilt from a clean database with one command; documented credentials for each role |
+
+## 3. Audience
+
+| Audience | What they evaluate |
+|---|---|
+| Recruiters and hiring managers | First impression, polish, a clear README, a live demo with role logins |
+| Engineers and reviewers | Architecture, ADRs, tests, concurrency and payment correctness, code quality |
+| Project owner | A maintainable codebase that can grow |
+
+## 4. Users and roles
+
+The full permission matrix is in `docs/architecture/security-model.md`.
+
+| Role | Description |
+|---|---|
+| Visitor | Not signed in. Browses, searches, keeps a guest cart. |
+| Customer | Signed-in shopper. Checks out, tracks orders, returns, reviews, wishlist, follows stores, loyalty and referrals. |
+| Vendor Owner | Created when the platform approves a vendor application. Full control of their own vendor, including team management. |
+| Vendor Manager | Catalogue, inventory, orders, returns, shipping settings, review replies. |
+| Vendor Fulfilment | Order fulfilment and stock adjustments. |
+| Vendor Finance | Earnings, statements, payouts, refund approval. |
+| Vendor Support | Order lookup, return handling, review replies. Read-only on catalogue. |
+| Platform Admin | Everything, including staff management and impersonation. |
+| Platform Operations | Vendor applications and lifecycle, catalogue moderation, order and return arbitration, promotions. |
+| Platform Finance | Commission settings, refunds override, disputes, reconciliation, payout runs. |
+| Platform Support | Read access to orders, customers and vendors for support. No money-moving actions. |
+
+## 5. Product surfaces
+
+1. **Customer storefront** (`/`, Vue). Covers:
+   - home and merchandising;
+   - category browsing;
+   - search with facets;
+   - product pages with variants;
+   - vendor store pages;
+   - multi-vendor cart and checkout;
+   - account pages: orders, returns, addresses, wishlist, followed stores, points, referrals, reviews, notifications.
+2. **Vendor dashboard** (`/vendor`, Vue). Covers:
+   - overview;
+   - products and variants;
+   - inventory;
+   - orders and fulfilment;
+   - returns;
+   - earnings, statement and payouts;
+   - reviews;
+   - store profile;
+   - shipping rates;
+   - team;
+   - notifications.
+3. **Platform administration** (`/admin`, Filament). Covers:
+   - vendor applications and vendors;
+   - catalogue taxonomy and moderation;
+   - orders and returns arbitration;
+   - refunds and disputes;
+   - finance (ledger, payouts, reconciliation);
+   - promotions;
+   - loyalty settings;
+   - customers;
+   - staff;
+   - audit log;
+   - system health (outbox, queues, webhooks).
+
+## 6. Scope
+
+### 6.1 In scope for v2
+
+| Area | Notes |
+|---|---|
+| Identity | Registration, login, email verification, password reset, profile, address book; staff 2FA |
+| Vendor onboarding | Application → platform review → vendor created (pending) → approved; suspension and reactivation |
+| Vendor team | Invite members with roles; one vendor per user |
+| Catalogue | Platform-owned category tree and attribute definitions; vendor products with variants (option combinations), images, descriptions; product status (draft, active, inactive); platform moderation (block or unblock) |
+| Pricing | Price per variant, optional compare-at price; tax-inclusive (no tax engine) |
+| Inventory | On-hand and reserved per variant; reservations with TTL; adjustments; movement history; low-stock indicator |
+| Shipping | Per-vendor flat rates by zone (Peninsular Malaysia, East Malaysia); per-vendor free-shipping threshold; manual carrier and tracking entry |
+| Cart | Guest and customer cart, multi-vendor, grouped by vendor; merged on login; stock and price revalidation |
+| Checkout | Account required; address; per-vendor shipping; coupon; points redemption; single card payment (Stripe test mode, 3-D Secure) |
+| Orders | OrderGroup + VendorOrders; customer timeline per vendor; vendor fulfilment states; cancellation rules |
+| Returns and refunds | Customer return requests per VendorOrder line; vendor decision; platform arbitration; partial and full refunds; refunds tracked per VendorOrder |
+| Disputes | Ingest provider disputes (test mode), hold vendor funds, record evidence, record the outcome |
+| Finance | Double-entry ledger, frozen commission, vendor balances (pending, available, held, receivable), statement, weekly simulated payouts, reconciliation |
+| Promotions | Platform-run coupon codes and automatic discounts (percentage or fixed, minimum spend, category or vendor targeting, usage limits, date window) |
+| Loyalty and referrals | Marketplace-wide points earned on completed vendor orders and redeemed at checkout; referral codes (referee discount, referrer points) |
+| Reviews | Verified-purchase product reviews (rating + text), one per purchased line, vendor reply, platform moderation |
+| Wishlist and store follow | Customer wishlist; follow vendor stores; followed-store feed on the account page |
+| Notifications | Database (in-app) and email for order, return, refund, payout and application events |
+| Search | Full-text search with facets: category, price, vendor, rating, in stock. MySQL-backed (ADR-0019) |
+| i18n | `en` (primary), `ar` (RTL), `ms` for all UI. Platform taxonomy translated. Vendor-entered content is single-language. |
+| Demo | Reproducible seeded environment with role logins |
+
+### 6.2 Out of scope for v2 (with reason)
+
+| Excluded | Reason |
+|---|---|
+| Guest checkout | Account-required checkout removes a class of ownership bugs; the cart still works for guests (decision P-1, below) |
+| Real vendor payouts / Stripe Connect | D-6; simulated payouts only |
+| Tax calculation and invoices | ADR-0007; prices are tax-inclusive |
+| Multi-currency | ADR-0007 |
+| Carrier integrations and shipping labels | Manual tracking entry |
+| Vendor-funded promotions | Platform-funded only, which keeps the finance model tight |
+| Subscriptions, gift cards, digital downloads, bundles, flash-sale engine, A/B experiments, chat, Q&A, waitlist, abandoned-cart email, AI recommendations | Legacy experimental features; not needed for the showcase objectives |
+| Public REST API and mobile apps | Inertia is the only client (ADR-0018) |
+| Realtime push (WebSockets) | Polling where needed. Reverb is deferred. |
+| Multiple vendors per user | ADR-0011 |
+| Translation of vendor-entered content | Single-language listing content |
+
+### 6.3 Product decisions proposed in this PRD (need owner confirmation)
+
+| ID | Proposal | Rationale |
+|---|---|---|
+| P-1 | Checkout requires an account (inline sign-up on the checkout page); guest browsing and cart allowed | Removes guest-ownership bugs; simpler order access |
+| P-2 | Vendor products publish immediately once the vendor is approved; platform moderation is reactive (block or unblock) | Pre-moderation slows demos; reactive moderation still demonstrates control |
+| P-3 | Return window of 7 days after delivery; auto-deliver 10 days after shipping when not confirmed | No carrier integration exists |
+| P-4 | Reservation TTL of 15 minutes, with one extension while payment is processing | Brief §11 |
+| P-5 | Points: earn 1 point per RM 1 of goods on **completed** vendor orders; 100 points = RM 1; redeem up to 20 % of goods subtotal | Award after the return window avoids most clawbacks |
+| P-6 | Referral: referee gets RM 10 off a first order over RM 50; referrer gets 500 points when that order completes | Simple and demonstrable |
+| P-7 | Default commission 10 %, with category and vendor overrides; minimum payout RM 50; weekly payout run (Monday 09:00 MYT) | Plausible marketplace parameters |
+| P-8 | Customer may cancel a VendorOrder only while `awaiting_fulfilment`; afterwards they use a return | Standard practice |
+
+## 7. Success criteria for v2 (release gate)
+
+1. A customer buys products from **three vendors** in one checkout. They see one order with three vendor shipments, tracked independently.
+2. Each vendor fulfils independently. One vendor cancels; the customer is refunded for that vendor only, and the other two are unaffected.
+3. A customer returns one line from one vendor. The partial refund reverses exactly that line's goods, commission and points, and the vendor statement shows it.
+4. A disputed payment holds the affected vendors' funds and resolves according to the dispute rules.
+5. A weekly payout run produces simulated payouts that equal each vendor's available balance, and the ledger reconciles.
+6. Every scenario in `lifecycles/` passes on MySQL in CI, including the parallel concurrency tests.
+7. Every page works in `en`, `ar` (RTL) and `ms`; WCAG 2.2 AA checks pass on the key journeys.
+8. The demo rebuilds from an empty database with one command, and the seeded data passes the ledger invariants.
+
+## 8. Assumptions and constraints
+
+- Single developer; phase-gated delivery per the brief.
+- Demo scale: about 12 vendors, up to 1,000 products, up to 5,000 seeded orders. Architecture is not designed beyond 10× that without a new ADR.
+- Stripe test mode is available for MYR card payments, including 3-D Secure test cards. This is an assumption to verify in Phase 5 (D-14).
+- All content (names, addresses, images) is fictional or licensed.
+
+## 9. Open questions
+
+- P-1 to P-8 above.
+- D-9, D-10, D-11 in ADR-0016.
+- D-15: commit author identity before the repository is public.
diff --git a/docs/product/scope.md b/docs/product/scope.md
index fa58eff..b2f4f70 100644
--- a/docs/product/scope.md
+++ b/docs/product/scope.md
@@ -1,5 +1,7 @@
 # Scope
 
+> **Superseded 2026-11-01** by [ADR-0007](../architecture/adr/0007-product-positioning-currency-and-locales.md) (owner decision D-4) and the Nexo 2.0 product documents: [product-requirements.md](../product/product-requirements.md), [functional-requirements.md](../product/functional-requirements.md). Kept for history only; do not implement from this file.
+
 **Status:** Ratified 2026-08-30
 
 Every feature area is tagged so a new developer knows what is load-bearing.
diff --git a/docs/product/user-journeys.md b/docs/product/user-journeys.md
new file mode 100644
index 0000000..86cc2f9
--- /dev/null
+++ b/docs/product/user-journeys.md
@@ -0,0 +1,153 @@
+# User Journeys and Workflows
+
+- **Status:** Draft for owner review (Phase 1)
+- **Date:** 2026-11-01
+
+Each journey lists its steps, the requirements it exercises, and the failure branches the design must handle. The journeys drive the Phase 2 screen inventory and the Phase 9 end-to-end tests.
+
+---
+
+## Customer journeys
+
+### CJ-1 Discover and buy from several vendors (happy path)
+
+1. Visitor lands on home (featured categories, curated collections, stores to follow) → category page → applies facets.
+2. Opens a product page and selects variant options:
+   - price and stock update per variant;
+   - the vendor card links to the store page.
+3. Adds three items from three vendors. The cart groups lines by vendor and shows per-vendor subtotals and shipping estimates.
+4. Proceeds to checkout and is asked to sign in or create an account. The guest cart is merged (FR-CART-02).
+5. Selects an address. Shipping is quoted per vendor, then the customer applies a coupon and redeems points. The summary shows goods, shipping per vendor, discount, points and total.
+6. Places the order:
+   - the stock is reserved;
+   - the payment form shows a timer for the reservation;
+   - the customer pays with a test card and completes 3-D Secure.
+7. Sees "Confirming your payment…", then the confirmation page: group reference and three vendor shipments.
+8. Receives one confirmation email. Each vendor gets a new-order notification.
+
+**Requirements:** FR-SRCH-01, FR-CAT-05, FR-CART-01…04, FR-CHK-01…10.
+
+**Failure branches:**
+
+| Branch | Expected behaviour |
+|---|---|
+| Price changed between cart and placement | 409; review the new total |
+| Line out of stock at placement | Order not placed; short lines named |
+| Card declined | Retry with another card within TTL |
+| Provider unavailable | Retryable error; nothing charged |
+| Browser closed after paying | Order still marked paid by webhook; email sent |
+| Reservation expired before paying | Group expired; the customer can return to the cart, which is kept |
+| Double-click on "Place order" | One order |
+
+### CJ-2 Track and receive
+
+1. Account → Orders. Each group expands into vendor shipments, each with a timeline: paid → processing → shipped (carrier + tracking) → delivered.
+2. The customer confirms delivery, or it auto-confirms after 10 days.
+
+### CJ-3 Cancel before shipping
+
+1. On a vendor shipment in `awaiting_fulfilment`, the customer chooses Cancel and gives a reason.
+2. That VendorOrder is cancelled:
+   - a full refund for that vendor's portion (goods + shipping, minus nothing);
+   - points and discount allocation for those lines are returned.
+3. The other shipments are unchanged.
+
+**Failure branch:** the vendor moved it to `processing` at the same moment. The customer sees "This shipment is already being prepared; request a return after delivery." (409).
+
+### CJ-4 Return and partial refund
+
+1. Within 7 days of delivery, the customer requests a return of 1 of 2 units on one line, with a reason and photos.
+2. The vendor approves and the customer ships the item back (out of band).
+3. The vendor marks it received and resellable. The refund is created for exactly that unit's goods value, net of its allocated discount.
+4. The customer sees the refund go `submitted` → `succeeded`. Points for that unit are adjusted.
+
+**Branches:**
+
+| Branch | Expected behaviour |
+|---|---|
+| Vendor rejects | Customer can escalate; Platform Operations arbitrates |
+| Vendor silent for 3 days | Auto-escalation |
+| Provider refund timeout | Status stays "Processing refund", resolved by webhook or reconciliation |
+
+### CJ-5 Review
+
+After delivery, the customer reviews a purchased line (rating, text, photos). The vendor replies. Platform Operations may hide the review.
+
+### CJ-6 Engage
+
+- Wishlist add and remove.
+- Follow a store; see new products from followed stores.
+- Share a referral code; the friend gets a discount; the customer earns points when the friend's order completes.
+
+---
+
+## Vendor journeys
+
+### VJ-1 Apply and get approved
+
+1. A signed-in user selects "Sell on Nexo" and submits an application.
+2. Platform Operations reviews it and approves:
+   - a Vendor is created as `pending` with the applicant as Owner;
+   - an operator then approves the vendor (`approved`).
+3. The Owner is notified, opens `/vendor` and completes the store profile and shipping rates. A checklist shows readiness: profile, shipping rates for at least one zone, at least one active product.
+
+**Branch:** rejected application, with reason; the applicant may apply again after 30 days.
+
+### VJ-2 Build the catalogue
+
+1. Create a product: category, details and images.
+2. Define options (Colour × Size), which generates the variant matrix. Set SKU, price and stock per variant.
+3. Activate the product. It appears in search within about 1 minute.
+4. Optionally run a CSV import: dry-run report, then confirm.
+
+### VJ-3 Fulfil an order
+
+1. The vendor receives a notification. The orders list shows filters by status.
+2. Opens the VendorOrder: items, shipping address, customer name and phone.
+3. Moves it to `processing` (packing), then `shipped` with carrier and tracking.
+4. Later the order becomes `delivered`, then `completed`. The earnings change from pending to available.
+
+**Branches:**
+
+| Branch | Expected behaviour |
+|---|---|
+| Item cannot be supplied | Vendor cancels with reason; automatic full refund for this VendorOrder; stock returned |
+| Concurrent edit by two team members | One transition wins; the other sees "Status changed by <name>" (409) |
+
+### VJ-4 Manage stock
+
+- Receive stock (delta) or do a stock count (absolute).
+- A conflicting count gets 409 with the current figure.
+- Reserved quantity is visible, with the explanation "held in unpaid checkouts".
+
+### VJ-5 Handle a return
+
+Approve or reject a return, then mark the items received (resellable or damaged). The refund is triggered automatically. The vendor statement shows the reversal line, with commission reversed.
+
+### VJ-6 Earnings and payouts
+
+1. The Finance role opens Earnings and sees balances: pending, available, held, receivable, paid out.
+2. The statement lists every ledger line, linked to orders, refunds and disputes. It can be exported as CSV.
+3. The Monday payout run creates a simulated payout, labelled "Simulated (demo)".
+
+### VJ-7 Manage the team
+
+The Owner invites a fulfilment member. The member accepts and sees only the permitted menus. The Owner deactivates the member, whose access ends on their next request.
+
+---
+
+## Platform staff journeys (Filament)
+
+| ID | Journey | Steps |
+|---|---|---|
+| PJ-1 | Vendor applications | Queue → review → approve or reject → approve vendor → (later) suspend with reason → reactivate |
+| PJ-2 | Catalogue moderation | Report or queue → block product with reason → vendor notified → unblock |
+| PJ-3 | Return arbitration | Escalated returns queue → view evidence → uphold or override → refund triggered |
+| PJ-4 | Dispute | Dispute appears (provider event) → funds held for affected vendors → upload evidence (simulated) → record outcome (won or lost) → ledger postings |
+| PJ-5 | Refund failure | Failed refund queue → inspect provider error → retry (same idempotency key) or mark resolved with note |
+| PJ-6 | Reconciliation | Nightly report → exceptions list → investigate (links to attempt, event, ledger) → resolve with note (audit) |
+| PJ-7 | Payout run | View the upcoming run → trigger manually (idempotency key) or wait for the schedule → payouts list |
+| PJ-8 | Commission | Change default, category or vendor rate → effective for new orders only → audit entry |
+| PJ-9 | Promotions | Create coupon → limits and targeting → monitor redemptions |
+| PJ-10 | Support | Look up an order by reference, email or payment id → impersonate the customer or vendor member (audited, no money actions) |
+| PJ-11 | Health | Outbox backlog, dead letters (retry), failed jobs, last webhook, sweeper heartbeat |
diff --git a/docs/product/vision.md b/docs/product/vision.md
index 64a66e9..150fb29 100644
--- a/docs/product/vision.md
+++ b/docs/product/vision.md
@@ -1,5 +1,7 @@
 # Product Vision
 
+> **Superseded 2026-11-01** by [ADR-0007](../architecture/adr/0007-product-positioning-currency-and-locales.md) (owner decision D-4) and the Nexo 2.0 product documents: [product-requirements.md](../product/product-requirements.md), [functional-requirements.md](../product/functional-requirements.md). Kept for history only; do not implement from this file.
+
 **Status:** Ratified 2026-08-30 · Owner: Platform Operator
 **Supersedes:** the "generic multi-tenant e-commerce SaaS" framing used in `README.md`
 and `docs/COMPREHENSIVE_CODEBASE_GUIDE.md` prior to 2026-08-30.