new plan

.pi-lens/cache/todo-baseline.json

@@ -0,0 +1,3 @@
+{
+  "items": []
+}

.pi-lens/cache/todo-baseline.meta.json

@@ -0,0 +1,3 @@
+{
+  "timestamp": "2026-04-07T09:58:01.691Z"
+}

.pi/agents/supervisor.md

@@ -0,0 +1,33 @@
+---
+name: supervisor
+# tools: read,write,edit,bash,grep,find,ls
+# model:
+# standalone: true
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  Project-Specific Supervisor Guidance
+
+  This file is COMPOSED with the base supervisor prompt shipped in the
+  taskplane package. Your content here is appended after the base prompt.
+
+  The base prompt (maintained by taskplane) handles:
+  - Supervisor identity and standing orders
+  - Recovery action classification and autonomy levels
+  - Audit trail format and rules
+  - Batch monitoring, failure handling, operator communication
+  - Orchestrator tool reference (orch_status, orch_pause, etc.)
+  - Startup checklist and operational knowledge
+
+  Add project-specific supervisor rules below. Common examples:
+  - Run linter before integration ("always run `npm run lint` after merge")
+  - CI dashboard URL for failure triage
+  - PR template or label conventions
+  - Project-specific recovery procedures
+  - Team notification preferences (Slack, etc.)
+  - Custom health check commands
+
+  To override frontmatter values (tools, model), uncomment and edit above.
+  To use this file as a FULLY STANDALONE prompt (ignoring the base),
+  uncomment `standalone: true` above and write the complete prompt below.
+═══════════════════════════════════════════════════════════════════ -->

.pi/npm/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

.pi/settings.json

@@ -0,0 +1,5 @@
+{
+  "packages": [
+    "npm:@lnittman/pi-interview"
+  ]
+}

.pi/taskplane.json

@@ -0,0 +1,9 @@
+{
+  "migrations": {
+    "applied": {
+      "add-supervisor-local-template-v1": {
+        "appliedAt": "2026-04-07T09:54:49.502Z"
+      }
+    }
+  }
+}

README.md

@@ -9,6 +9,7 @@ Documentation-first workspace for a Brazil-first B2B2C fintech concept focused o
 - `docs/market-memo.md` - market gap, competitor map, differentiation, and business model framing
 - `docs/positioning-and-landing-copy.md` - messaging directions, landing-page copy, and narrative structure
 - `docs/year-one-roadmap.md` - phased plan for the first year of product and partner execution
+- `docs/prototype-plan.md` - proposed scope, flows, architecture, and build sequence for a first product prototype
 - `docs/ideas-for-review.md` - ideas from external conversations that are not yet part of the core docs
 
 ## Suggested reading order
@@ -18,6 +19,7 @@ Documentation-first workspace for a Brazil-first B2B2C fintech concept focused o
 - `docs/market-memo.md`
 - `docs/positioning-and-landing-copy.md`
 - `docs/year-one-roadmap.md`
+- `docs/prototype-plan.md`
 
 ## Notes
 

docs/prototype-plan.md

@@ -0,0 +1,462 @@
+# Prototype Plan
+
+## Purpose
+
+Build the smallest functional prototype that proves the core wedge for this company:
+
+`a verified customer payment can become an auditable commission balance, and a safe portion of that balance can be accessed instantly via Pix`
+
+This prototype should validate three things at once:
+
+- employers trust the platform to calculate and track commissions
+- employees understand and value faster access to earned commissions
+- the operating model works with partner-led custody and conservative availability rules
+
+## Prototype philosophy
+
+This should be an ops-backed product prototype, not a full production fintech stack.
+
+The prototype should be good enough to demo to design partners and, if needed, support a tightly controlled pilot with manual operations behind the scenes.
+
+That means:
+
+- real product flows where they matter
+- mocked or manual partner workflows where regulation or integration would slow learning
+- a real commission ledger and audit trail from day one
+- conservative rules for reversals, reserves, and payout eligibility
+
+## Core hypothesis
+
+If a Brazil-based employer with a commission-heavy team can see commissions generated from payment events in near real time, and if employees can access the available portion of those commissions through `Pix`, then the company will have a strong design-partner wedge.
+
+## Primary prototype users
+
+### Employer admin
+
+Usually finance, operations, founder, or sales management.
+
+Needs to:
+
+- define a commission rule
+- see payment-linked commissions
+- understand current commission liability
+- review payouts and adjustments
+- trust the audit trail
+
+### Employee
+
+Usually a salesperson or commission-earning worker.
+
+Needs to:
+
+- see what has been `earned`
+- see what is `available`
+- understand what is still pending or held in reserve
+- request a `Pix` cash-out
+- trust that the numbers are correct
+
+### Internal ops admin
+
+Used by the startup team during the prototype.
+
+Needs to:
+
+- onboard employers manually
+- ingest payment events
+- review KYC or employer setup issues
+- approve or simulate payouts
+- process reversals and adjustments
+
+## Prototype scope
+
+### In scope
+
+#### 1. Employer setup
+
+- create employer account manually through an internal admin tool
+- create teams or stores
+- invite or upload employees through CSV
+- configure one simple commission plan per team
+- register employer settlement preferences
+
+#### 2. Payment ingestion
+
+Support two prototype ingestion modes:
+
+- webhook simulator for demos
+- CSV upload for early design partners
+
+Each payment event should include at minimum:
+
+- employer
+- customer payment reference
+- employee or seller attribution
+- gross amount
+- payment status
+- timestamp
+
+#### 3. Commission calculation
+
+Keep rules narrow for the first prototype.
+
+Support:
+
+- flat percentage commission
+- optional per-employee override
+- optional reserve or holdback percentage for availability
+
+Do not try to support every real-world compensation edge case yet.
+
+#### 4. Commission ledger
+
+This is the most important part of the prototype.
+
+Track balances in three states:
+
+- `earned`
+- `available`
+- `settled`
+
+Also track:
+
+- payout requests
+- reserves or holdbacks
+- reversals
+- manual adjustments
+- fees, if needed for reporting
+
+Every payment-triggered commission event should create an immutable audit trail.
+
+#### 5. Employee balance view
+
+Mobile-first web experience that shows:
+
+- current `earned`, `available`, and `settled` balances
+- transaction history
+- payout history
+- current `Pix` key on file
+- payout request button
+
+#### 6. `Pix` payout flow
+
+For the prototype, use partner-led abstractions and manual controls.
+
+Support:
+
+- employee submits payout request
+- system checks available balance and payout limits
+- ops admin approves or auto-approves based on simple rules
+- payout is marked as sent and completed through a mocked or manually triggered partner adapter
+
+#### 7. Employer dashboard
+
+Minimal dashboard showing:
+
+- recent payment events
+- commissions created today and this week
+- current commission liability
+- total already paid out
+- pending adjustments or reversals
+- employee-level history
+
+#### 8. Reversal and adjustment flow
+
+At least one negative event flow must exist in the prototype.
+
+Support:
+
+- payment reversal or refund event
+- system creates a negative commission adjustment
+- impact is shown in employer and employee histories
+- if necessary, the adjustment reduces future availability rather than trying to claw back immediately
+
+### Out of scope
+
+Keep these out of the first prototype:
+
+- stored balance as a major product surface
+- card issuance
+- employer-backed advance
+- any standalone credit product
+- full payroll integration
+- broad ERP, CRM, or POS integrations
+- multi-entity support
+- sophisticated forecasting or BI
+- automated labor and tax logic
+- consumer-grade banking features
+
+## Prototype scenario to optimize for
+
+Use one clear happy-path demo story.
+
+### Example
+
+- employer: aesthetic clinic group in Brazil
+- employee: seller named Ana
+- rule: 20 percent commission on completed payments
+- availability rule: 70 percent of commission becomes immediately `available`; 30 percent stays held until settlement
+- customer payment: `R$1,000`
+
+System behavior:
+
+- payment received: `R$1,000`
+- commission calculated: `R$200 earned`
+- immediate availability: `R$140 available`
+- held amount: `R$60 pending settlement`
+- Ana requests `R$100` `Pix` cash-out
+- employer dashboard updates liability and payout history
+
+This single scenario should work end to end before adding more complexity.
+
+## Recommended product flows
+
+### Flow 1: Employer onboarding
+
+1. ops creates employer
+2. employer admin logs in
+3. employer uploads employees or assigns seller IDs
+4. employer selects a simple commission rule
+5. employer confirms reserve and availability settings
+
+### Flow 2: Payment to commission
+
+1. payment event enters through webhook simulator or CSV
+2. system validates employer and seller mapping
+3. commission engine calculates commission result
+4. ledger records `earned`
+5. availability policy releases eligible amount to `available`
+6. employer and employee dashboards update
+
+### Flow 3: Employee payout
+
+1. employee opens mobile web app
+2. employee sees `available` balance
+3. employee requests payout to registered `Pix` key
+4. payout request is validated
+5. payout is sent through mocked or manual partner adapter
+6. ledger records the payout and reduces `available`
+
+### Flow 4: Refund or reversal
+
+1. refund event is posted
+2. system creates negative adjustment against commission
+3. held reserve absorbs the loss first
+4. if reserve is insufficient, future availability is reduced
+5. employer and employee both see the adjustment trail
+
+## Product decisions for the prototype
+
+### Source of truth
+
+Use the customer payment event as the default trigger for commission creation whenever possible.
+
+### Availability policy
+
+Do not make all earned commissions instantly withdrawable.
+
+For the prototype, choose one conservative rule such as:
+
+- 50 to 70 percent of a commission becomes `available` immediately
+- remaining amount stays held until a defined settlement event or time window
+
+### Money movement model
+
+Do not represent the startup as directly holding funds.
+
+The prototype should frame all custody and regulated movement as partner-led, even if the integration is mocked.
+
+### Rule complexity
+
+Support only the smallest useful rule set first.
+
+Good first version:
+
+- one flat commission percentage per team
+- employee-specific overrides
+- reserve percentage
+
+Avoid tiers, quotas, split commissions, and retroactive accelerators in v0.
+
+## Technical shape of the prototype
+
+A simple but durable architecture is enough.
+
+### Suggested stack
+
+- frontend: `Next.js` + TypeScript + Tailwind
+- backend: TypeScript API routes or a small Node service
+- database: `PostgreSQL`
+- auth: magic link or OTP-based login
+- hosting: Vercel, Render, or Fly.io
+- file upload: CSV upload for payment events and employee imports
+
+### Core modules
+
+- employer management
+- employee management
+- payment ingestion
+- commission engine
+- commission ledger
+- payout orchestration
+- admin ops console
+- audit log
+
+### Integration adapters
+
+Define adapters even if they are mocked.
+
+- `PaymentProviderAdapter`
+- `PixPayoutAdapter`
+- `KycProviderAdapter`
+
+This keeps the prototype aligned with the long-term partner-led model and avoids hard-coding demo logic everywhere.
+
+## Minimal data model
+
+The first version likely needs these core entities:
+
+- `employers`
+- `employees`
+- `commission_plans`
+- `payment_events`
+- `commission_results`
+- `ledger_accounts`
+- `ledger_entries`
+- `payout_requests`
+- `adjustments`
+- `audit_events`
+
+### Balance logic
+
+At minimum, model separate balances for:
+
+- employee `earned`
+- employee `available`
+- employee `settled`
+- employer liability
+- reserve or holdback balance
+
+## Prototype screens
+
+### Employer-facing
+
+- login
+- employer overview dashboard
+- employee list
+- commission rule setup
+- payment event feed
+- commission history by employee
+- payout history
+- adjustments view
+
+### Employee-facing
+
+- login
+- balance home
+- transaction history
+- payout request screen
+- payout receipt or status screen
+
+### Internal ops
+
+- employer creation
+- employee import support
+- payment event simulator
+- payout approval queue
+- adjustment and reversal tool
+
+## Success criteria
+
+The prototype is successful if it can demonstrate all of the following in one controlled flow:
+
+- an employer can be configured in under 30 minutes
+- a payment event generates a commission and updates balances automatically
+- an employee understands `earned` versus `available`
+- an employee can request a `Pix` payout from the `available` balance
+- a refund or reversal creates a visible adjustment without breaking the ledger story
+- an employer can view liability, payouts, and audit history without relying on spreadsheets
+
+## What should be faked or manual at first
+
+To move faster, these can be manual in the first prototype:
+
+- KYB and KYC review
+- employer contract setup
+- payment provider onboarding
+- actual `Pix` movement through a partner
+- exception handling and customer support
+- settlement reconciliation edge cases
+
+Manual operations are acceptable as long as the product surface still teaches the right workflow.
+
+## Build sequence
+
+### Week 1: definition and UX
+
+- lock target design-partner vertical
+- write product requirements for the prototype
+- define the event model
+- sketch employer and employee screens
+- finalize one default commission and reserve policy
+
+### Week 2: domain and ledger
+
+- implement payment event ingestion
+- implement commission calculation
+- implement balance state transitions
+- implement audit trail
+- seed one demo employer with sample data
+
+### Week 3: employer product surface
+
+- employer login
+- employee upload
+- commission rule setup
+- payment and commission dashboards
+
+### Week 4: employee product surface
+
+- employee login
+- balance screen
+- payout request flow
+- payout history
+
+### Week 5: ops and failure paths
+
+- payout approval queue
+- reversal and adjustment flow
+- webhook simulator
+- CSV imports
+
+### Week 6: polish and design-partner readiness
+
+- improve copy and onboarding
+- add demo data scripts
+- record a product walkthrough
+- prepare pilot runbook and support checklist
+
+## Open questions before building
+
+- which vertical should the first demo represent: clinics, education, franchise retail, or another segment?
+- will the first prototype use only simulated payments, or one real payment source?
+- what immediate availability percentage is safe enough for the first demo?
+- should commission be recognized on payment authorization or only on confirmed settlement?
+- how will seller attribution be supplied in the first design-partner workflow?
+- what is the first refund and chargeback policy the employer can accept?
+
+## Recommended next deliverables
+
+After this plan, the next useful documents would be:
+
+- a short product requirements doc for the prototype
+- wireframes for employer and employee flows
+- an event model spec for payments, commissions, payouts, and adjustments
+- a partner-interface spec for mocked `Pix`, KYC, and payment ingestion
+
+## Bottom line
+
+The right prototype is not a broad fintech app.
+
+It is a narrow commission infrastructure demo that proves one loop extremely well:
+
+`payment event -> commission calculation -> earned and available balance -> Pix payout -> employer visibility and audit trail`