Operator Platform — Pay Model + Job Costing (spec, 2026-07-02; queue AFTER Session 7b)

Goal: retire the Charles-pay spreadsheets. Square-paid jobs flow into a Pay view; Ryan enters ACTUAL per-job expenses (replacing per-service estimates); the system computes true gross profit, profit %, and Charles's recommended pay using the existing threshold model. Owner-only.

Model (ported from Charles_Pay_Model XLS — the proven logic)

Per job: gross_profit = billed − variable_cost where variable_cost = actual costs if entered, else the per-service estimate (flagged "est."). Per month (chronological within month): recommended_pay = max(0, min(sharePct × job_GP, max(minFloor, sharePct × (max(0, cumGP − monthlyFixed) − max(0, (cumGP − job_GP) − monthlyFixed))))) — i.e., share of profit ABOVE the month's fixed-cost break-even, capped at share×job's own GP, optional floor. Actual pay = owner override ?? recommended. to_be_paid_via_payroll = actual_pay − debited_cash; payroll_hours = to_be_paid / hourlyRate.

Storage (no new tables — 7b's tenant_settings + existing jobs.pay)

• tenant_settings.pay_model jsonb: {sharePct:0.40, minFloorPerJob:0, monthlyFixedCosts:1100, payrollHourlyRate:40, taxReservePct:0.27, defaultVarCosts:{"Driveway Only":50,"House Wash":60,"House+Drive Combo":77,"Big Combo (Roof+House+Drive)":115,"Other":0}} (seed from current Pay Settings tab).
• jobs.pay jsonb (column exists): {costs:[{label:"Chems",amount:22.50},...], pay_override:null, debited_cash:0, pay_notes:""}.

UI (owner role ONLY — field role must never see pay/margins per existing auth rule; Charles is field)

1. Job detail / deal drawer (Completed+Paid stages): "Job costs" quick-add — chips Chems / Fuel / Materials / Other + amount; shows total actual vs the service estimate.
2. Pay screen (nav, owner): month picker; table of PAID non-imported jobs: date, customer, service, billed, var cost (actual | est. badge), GP, profit %, cum GP, recommended, You-Assign override, actual, debited cash, payroll $, payroll hrs. Month footer: jobs, billed, var, GP, fixed, Charles pay, pre-tax, tax reserve, take-home. Profit % per job and month = the headline number.
3. Settings: pay-model editor (share %, fixed, rate, floor, tax %, default var costs per service type).

Flow

Square webhook → job paid (already live) → job appears in Pay view for its month → Ryan adds actual costs (anytime; recalc is live) → month closes itself; payroll-hours number feeds the W-2 payroll entry (existing checklist in 05-Tax and Accounting).

Backfill

June 2026: 13 rows from the Google Sheet "Charles Pay" tab — port billed/service/debited/overrides (incl. Nana manual $20 cost, "You Assign" rows) so June closes in the platform. Sheet + XLS become read-only archives after parity check (June totals platform == fixed sheet).

Expense sources (Ryan, 7/2)

Real spend lives in Square Checking (ongoing business variable/overhead spend) plus some June items on a personal Amex (owner-paid, needs reimbursement/recording). So the model gets its numbers two ways:

• v1 (this build): manual — per-job costs entered on the job; a per-month "actual overhead" field on the Pay screen that overrides the monthlyFixedCosts estimate when Ryan enters the real number from Square Checking (est. badge until then). Every stored cost carries a source tag: square_checking | amex_personal | cash | other. amex_personal items flag for owner reimbursement (accountable-plan paper trail).
• v2 (fast follow): statement import — drop Square Checking / Amex CSV exports into an Expense Inbox; each line gets tagged Job / Overhead / Personal-exclude; job-tagged lines land in jobs.pay.costs, overhead lines sum into the month's actual overhead. (Square Checking API access TBD — CSV is the reliable v1 path.)

Advances (added 7/2 — DESIGN RULE from June)

Cash advances to the crew count AGAINST the profit share — never additive. Ryan's habit: customer pays cash → he hands Charles some/all of it as an advance. Build:

• jobs.pay.advances: [{date, amount, note}] (job-linked — the normal case). Keep debited_cash as the derived sum for back-compat with June backfill.
• "Record advance" action on job detail + deal drawer; ALSO prompt it inside the existing "record manual payment (cash/check)" pipeline action: "Advance any of this cash to Charles? [$__]" — that's the exact moment it happens in real life.
• Pay screen month view: advances column per job + month total; payroll due = model comp − Σ advances (floor at 0; if advances exceed comp, show the overage and let owner choose let-ride vs carry-forward — June precedent: let-ride, no carry).
• Advances visible to owner only, like everything else here.

Month-close screen (added 7/2 after doing June manually — this replaces the reconciliation workbook)

One page per month: revenue vs collected (Square truth, pending checks flagged — Anita pattern), actual expenses (imported + tagged), Charles comp table (recommended/override/cash-received/payroll-due/hours), owner-reimbursement tracker (owed → paid-back checkmark), P&L footer (pre-tax, 27% reserve, take-home, margin %). "Close month" button snapshots it immutably. The June close found $1,222 of billing drift between the manual sheet and Square — THE selling point: this screen can't drift because it reads the same rows Square writes.

THE LINE (Ryan 7/2): job economics, not accounting

In scope — everything that touches a job or an operating decision: pricing config, per-job actual costs, expense import+tagging (Square Checking/card CSVs), crew pay model + dials (share %, floor, monthly threshold, hourly rate — Settings UI), month close, margin %, owner-reimbursement flags, payroll HOURS number (handed to the payroll provider). Out of scope — QuickBooks/accountant territory, permanently: double-entry general ledger, bank reconciliation beyond Square, AP/bills, depreciation/assets, tax prep or filing, payroll tax filing, financial statements. The platform EXPORTS clean data (CSV now, QBO connector someday) — it never becomes the books. This is also where every competitor draws it (Jobber/Housecall/QuoteIQ sell "job costing," none do accounting; all integrate with QBO). Differentiator vs them: the configurable PROFIT-SHARE pay model — none of them can answer "pay my guy 40% of profit above break-even" — plus Square-verified month close.