Add wallet v1 product spec and launch conformance gates

README.md

@@ -10,6 +10,10 @@ Free control-plane application for EDUT onboarding and entitlement-aware install
 4. Signed package download and verification orchestrator.
 5. Member app-channel inbox.
 
+Primary v1 wallet behavior and acceptance criteria are specified in:
+
+- `docs/wallet-v1-product-spec.md`
+
 ## Out of Scope
 
 1. Governance runtime internals.

docs/conformance-vectors.md

@@ -7,3 +7,6 @@
 5. `L-005` Expired install token blocks install.
 6. `L-006` Distinct payer wallet without ownership proof blocks quote request.
 7. `L-007` Event inbox polling works when push unavailable.
+8. `L-008` Wallet onboarding creates local wallet without forcing seed phrase display.
+9. `L-009` Outgoing sends require biometric/PIN confirmation.
+10. `L-010` Primary wallet screens render USD-first balances and plain-language history.

docs/release-gate.md

@@ -6,9 +6,11 @@
 2. Package verification pass/fail tests pass.
 3. Governance install path fails closed on invalid evidence.
 4. Marketplace and status APIs are called with app-session auth.
+5. Wallet v1 acceptance criteria pass (`docs/wallet-v1-product-spec.md`).
 
 ## Blockers
 
 1. Any path that installs unsigned package.
 2. Any path that leaks private key material.
 3. Any path that bypasses entitlement checks for governance activation.
+4. Any launch flow that exposes seed phrase by default.

docs/wallet-bootstrap-flow.md

@@ -1,5 +1,9 @@
 # Wallet Bootstrap Flow (Launcher)
 
+This document is a narrow bootstrap subset. Full wallet behavior is defined in:
+
+- `docs/wallet-v1-product-spec.md`
+
 ## Objective
 
 Create or import an ownership wallet locally before paid actions.

docs/wallet-v1-product-spec.md

@@ -0,0 +1,164 @@
+# EDUT Wallet v1 Product Spec
+
+## Product Contract
+
+The launcher wallet is a real, user-owned wallet from day one. It is not a hidden license container.
+
+At launch, the wallet is the primary interface for:
+
+1. Identity and ownership
+2. Funding
+3. EDUT purchases
+4. Person-to-person sends
+5. Plain-language transaction visibility
+
+## Launch Scope
+
+### In scope
+
+1. Automatic wallet creation during onboarding
+2. USD-first balance display
+3. Add money via embedded on-ramp (card / Apple Pay / Google Pay when provider supports it)
+4. Receive from another wallet (QR + copy address)
+5. Buy EDUT products from wallet balance
+6. Auto-open on-ramp for checkout shortfall
+7. Send funds to any address (QR scan or paste)
+8. Biometric/PIN confirmation for all spend/send actions
+9. Plain-language transaction history
+10. Recovery path available but not forced
+
+### Out of scope (post-launch)
+
+1. Off-ramp to fiat
+2. Multi-token portfolio management beyond USDC + ETH
+3. DeFi integrations
+
+## UX Language Contract
+
+Never show crypto jargon by default.
+
+1. Show: `Add money`, `Receive`, `Pay someone`, `Balance`
+2. Hide by default: gas, wei, long hex fields, tx hashes, block explorers
+3. Reveal technical details only behind explicit `View details`
+
+## Core Flows
+
+## 1) First Launch Onboarding
+
+1. User installs and opens launcher.
+2. Wallet is created automatically on device.
+3. User sees: `Your wallet is ready`.
+4. User is not shown seed phrase unless they explicitly open recovery settings.
+5. Balance card is visible immediately in USD (`$0.00` initial state).
+
+### Rules
+
+1. Private key material never leaves device.
+2. Key storage uses secure OS keystore where available.
+3. If secure keystore is unavailable, launcher requires local passcode and stores encrypted key locally.
+
+## 2) Add Money
+
+1. User taps `Add money`.
+2. Embedded on-ramp opens.
+3. User selects amount and payment method.
+4. On-ramp delivers funds to EDUT wallet address.
+5. Balance updates in USD when chain confirms.
+
+### Rules
+
+1. On-ramp session is initiated from launcher context.
+2. On-ramp failures return user to wallet with actionable error state.
+3. No fiat custody by EDUT backend.
+
+## 3) Receive From Another Wallet
+
+1. User taps `Receive`.
+2. Launcher shows QR code and copy-address action.
+3. Label shown to user: `Receive from another wallet`.
+4. Incoming transfer appears in history and updates USD balance.
+
+## 4) Buy EDUT Product
+
+1. User selects product in store.
+2. Checkout shows USD amount and available wallet balance.
+3. If balance is sufficient, complete purchase from wallet.
+4. If insufficient, launcher opens on-ramp for difference.
+5. After funding, checkout resumes and completes.
+
+### Rules
+
+1. No hidden split charges.
+2. User always sees final USD amount before confirmation.
+3. Membership and entitlement purchases write deterministic receipts.
+
+## 5) Pay Someone
+
+1. User taps `Pay someone`.
+2. User scans QR or pastes address.
+3. User enters USD amount.
+4. Confirmation screen shows:
+   1. USD amount
+   2. Destination summary (`0x...abcd` short form)
+   3. Clear `Confirm payment` action
+5. Biometric/PIN confirmation required before send.
+
+## 6) Transaction History
+
+History is plain-language first.
+
+Examples:
+
+1. `Added $100`
+2. `Bought Human Membership`
+3. `Sent $50 to 0x12ab...90ef`
+4. `Received $200 from 0x98cd...11aa`
+
+Technical details are available only in expanded view:
+
+1. Full wallet addresses
+2. Tx hash
+3. Raw asset amounts
+
+## Security Requirements
+
+1. Biometric or PIN required for every outgoing transaction.
+2. Device-local key ownership is mandatory.
+3. Recovery path must exist but remain opt-in in onboarding.
+4. Sensitive operations fail closed on secure storage errors.
+5. Wallet export (seed/private key) requires explicit authenticated flow.
+
+## Asset/Display Model
+
+Launch-supported assets:
+
+1. USDC (primary purchasing balance)
+2. ETH (network fee balance)
+
+Display rules:
+
+1. Primary balance shown in USD.
+2. Token-level balances available in details view.
+3. Checkout amounts shown in USD first, then token equivalent if expanded.
+
+## Integration Requirements (Execution)
+
+Launcher implementation must support:
+
+1. Embedded on-ramp provider integration
+2. Wallet funding address retrieval for receive flow
+3. Store checkout integration with backend quote/confirm APIs
+4. Deterministic local transaction journal rendering
+5. Price conversion for USD display (USDC fixed, ETH converted via trusted feed)
+
+## Acceptance Criteria
+
+1. Fresh install reaches usable wallet state without manual key setup.
+2. User can add funds and see updated USD balance.
+3. User can copy/QR receive address and receive funds.
+4. User can buy EDUT product from wallet balance.
+5. Insufficient-balance checkout opens on-ramp and resumes.
+6. User can send funds with biometric/PIN confirmation.
+7. History entries are human-readable and accurate.
+8. No crypto jargon appears in primary flow screens.
+9. Off-ramp and non-USDC/ETH asset management are absent from v1 UI.