Codex Handoff — Capture-to-Sale Build Brief & the Positioning Wedge

Audience: Codex (and any coding agent). Author: Claude. Updated: 2026-06-17.

This is the build-ordered bridge under the now-canonical specs — and an argument for why this sequence. It is not the source of truth; these are:

• docs/product/capture-to-sale-tracking.md — the 8-stage process contract.
• docs/CC-Analysis/trovesnap-vision-scanning-spec.md — the AI/vision layer.
• docs/CC-Analysis/trovesnap-competitive-learning-and-trojan-horse-strategy.md — GTM.
• docs/product/pricing-and-tokens.md, docs/technical/data-model.md — pricing + the planned identity tables.

What changed since the first draft of this handoff: the QR identity layer, the capture-to-sale tracking spine, responsible disposal, and POS-interop are now canonical planned work (see those docs), not "off-limits below the line." Build them as canonical — while still honoring the invariants in §1.

0. The argument — why build it in this order (read first)

If you take one thing from this doc: do not lead with model-heavy AI cataloging, and do not try to be a POS. Both are traps.

1. AI cataloging is commoditizing into table stakes. Gavelist, EstateSail, Estimint, aListEngine all do photo→listing and charge per lot. Matching them on batch-listing quality is a race to a thin-margin feature, and per-lot inference is a cost trap. (Evidence: ai-cataloging-theirs-vs-ours.md.)
2. POS/checkout is entrenched. Square is the install base; EstateSail/PROSALE own clerking. Replacing checkout in v1 means rebuilding payments, refunds, tax, and disputes to win a battle that doesn't differentiate us.
3. So the moat is elsewhere: a durable item identity (QR), a buyer-demand graph + local marketplace liquidity, and recovery of unsold value — plus a proprietary sold-outcome corpus that compounds. (Evidence: trojan-horse memo.)
4. Therefore the winning shape is: a low-cost wedge (free/near-free) that crews adopt because it removes real friction, deterministic/local-first AI so the base is economically free to give away, a QR identity spine that captures floor truth and feeds demand/recovery, and interop with the tools sellers already run.
5. And the order matters. capture-to-sale-tracking.md is explicit: operational primitives (rooms, teams, bulk ops, labels, client reports, POS imports) come before heavy AI. Those are how crews keep a big house moving; they are the actual adoption blocker — not tagging quality. Lead with them.

Net: the catalog is the commodity input; identity + demand + recovery is the product. Build the spine and the operational floor first; layer staged vision and premium intelligence on top; run the positioning wedge to acquire the crews.

1. Invariants (confirm against the repo before editing)

• Ingestion contract: connectors / scans / imports write candidates + events only; promoteInventoryCandidate() stays the single canonical writer, post- review. New identity/scan tables feed this — they do not bypass it.
• No payments in v1. Square/PROSALE/EstateSail/Shopify/manual keep handling money; TroveSnap reconciles item identity and status, not cash.
• POS interop, not replacement (until clearly earned).
• Public QR = buyer-safe + opaque. Never expose internal pricing guidance, margin, consignor details, private notes, or seller PII. Staff/bind/checkout views are auth-gated.
• Language rules: "internal pricing guidance / suggested range / research recommended" — never "certified appraisal" or "guaranteed value." Nothing publishes without explicit seller approval; AI copy/tags always editable.
• Demo mode (NEXT_PUBLIC_TROVESNAP_DEMO=1): new surfaces render from fixtures, writes no-op.
• Vision output stays separate from inventory/POS/lifecycle state (vision spec §2).

If any instruction below conflicts with these, stop and surface it — the invariant wins.

2. Build order (six workstreams, sequenced)

Aligned to capture-to-sale-tracking.md. Each item: what · why · acceptance.

W1 — Operational foundation (before heavy AI)

The adoption floor crews need. Why: this, not tagging quality, is why pros stay.

• Rooms / zones / pickup areas attached to sale setup, capture, labels, checkout, pickup, and reports.
• Team roles (owner/admin, cataloger, pricer, label/runner, checkout, report viewer).
• Bulk operations (price/category/room edits, mass label gen, batch discount changes, duplicate-room setup, conflict preview before apply).
• Label batches as a first-class workflow (pick items → stock/format → preview → print/assign pack codes → bind; reprints, skips, unlabelled-high-value list).
• Client reports (sold/unsold/donated/removed, gross/fees/net, by room/consignor, audit-linked to status events).
• POS / CSV imports (Square quick-amount reconciliation; EstateSail/PROSALE itemized exports; Shopify/Whatnot when present) — the onboarding bridge.
• Acceptance: a crew can set up a multi-room sale, assign roles, bulk-price, mass-print labels, import a sold-report CSV, and produce a client report — in demo mode.

W2 — Identity spine (QR / bindings)

The inbound loop the pipeline was missing. Why: floor truth + demand + recovery all key off one durable id.

• Add the planned qr_codes / item_identity_bindings tables (data-model.md): code, item_id, estate_sale_id, state, bound_at, released_at, binding_history. States: unbound → bound → released → rebound. Idempotent, offline-safe.
• Public QR → opaque id → buyer-safe item/sale page (links back to seller profile, never to it). Watch-for-markdown + make-offer reuse discount_phases, buyer_offers, notifications.
• Scan events → anonymous interest signals (buyer_qr_scanned) feeding demand.
• Both label sources sync: pre-printed packs (bind on first scan) and print-your-own (minted from record). Reusable durable tags for high-value/auction/consignment/agency inventory (collect → release → rebind).
• Acceptance: bind ≤5s (two-scan), offline queue + sync; public page exposes no private data; scans increment demand metrics; a reusable tag rebinds next sale.

W3 — Deterministic / local-first capture & enrich

The free base. Why: near-zero marginal cost is what lets the base be free; voice beats photo-only.

• Voice + photo capture → local transcribe → condense → candidate fields (on-device/low-cost first; inventory_candidate, never canonical).
• Deterministic tagging/ranking for the bulk; confidence-tiered promotion policy over promoteInventoryCandidate() (auto-promote high-confidence/low-value, hold uncertain/high-value; log plugin_events).
• Acceptance: a sale can be cataloged end-to-end with zero paid AI; voice measurably improves tag specificity; promotion policy is pure + unit-tested.

W4 — Staged vision (token-metered, only when justified)

Implement trovesnap-vision-scanning-spec.md in its phase order.

• Phase 1: table_hunt + item_scan, strict schemas, normalized 0–1000 xyxy boxes, overlays, one hosted provider, deterministic candidate ranking.
• Phase 2: room_scan (multi-image, counts, dedup). Phase 3: mark_scan + condition_scan. Phase 4–5: appraisal_prepare / appraisal_value (token-metered; internal corpus + external comps). Phase 6: local VLM adapter.
• Honor the spec's cost controls (economy for discovery, strong only post- isolation), watchlists (versioned, IDs never invented), and provider normalization to one canonical result.
• Acceptance: per the spec's §26 acceptance criteria per scan type.

W5 — Demand + recovery

The compounding moat. Why: this is what nobody in the cataloger cluster has.

• Interest telemetry as a first-class subsystem (trojan-horse §9): impressions, views, saves, shares, QR scans, watches, offers, carts, purchases — each with item/sale/source/price/phase/geo/actor. Derive save rate, conversion, elasticity, nearby-demand. Lives in the app/marketplace layer, not in vision output.
• Wishlist/watch matching + What's Next disposition: notify matched buyers, offers, auction export, consignment, clearance, donation manifest (8283-aware), responsible disposal, archive — explainable from demand/value/category/scan/timing.
• Auction export adapters (auction-outbound-integration-spec.md): per-target profiles (LiveAuctioneers/Proxibid/Invaluable/Auction Flex·HiBid/Wavebid) + lot-numbered image bundles. File export first (no Auth); API + results pull-back later.
• Acceptance: unsold items route with explainable recommendations; auction export produces a valid per-platform package; sold-results reconcile to inventory_status_events.

W6 — Positioning wedge (acquisition layer)

The original freemium work — still valuable, now layered on top of the spine. Full copy/specs in freemium-ingestion-pain-analysis.md §5–§9.

• Ingestion-led /for-sellers landing; persona hero variants + deterministic routing; OG images + per-route metadata; funnel analytics (seller_signup, seller_activation = first sale w/ ≥1 item in 48h); A/B harness (sticky, pre-paint).
• Acceptance: renders in demo mode; variants pure + tested; events attributable; copy passes language rules.

3. Decisions worth defending (the argument, applied)

• Interop-first. Import PROSALE/Square/EstateSail outputs; keep source: aliases. Don't build deep two-way vendor APIs without demand. Reserve real integration effort for auction marketplaces (they have buyers).
• Don't compete on the scan or the catalog. Both are commoditizing/entrenched; the moat is identity + demand + recovery + the sold-outcome corpus.
• Deterministic/local-first. Free base is only viable if the bulk avoids paid inference; meter premium only when the seller chooses and the value is visible.
• Identity is the spine, not a reporting afterthought.

4. Open decisions for the human (don't guess)

• Vision provider(s) for MVP and the local VLM target (cost/quality tradeoff).
• Which scan types ship in v1 (spec recommends table_hunt, room_scan, item_scan).
• Pricing: pricing-and-tokens.md now sets the tiers (Free / Estate $12 / Pro $29, token packs) and marks physical QR/tag SKUs "under review" (internal) — confirm before surfacing any SKU pricing externally; keep numbers in one config source.
• Claims substantiation ("up to" vs measured) before any paid ads.
• A/B test mode (route-then-test-within-persona vs. 3-arm) — depends on traffic segmentation.

5. Out of scope / deferred

• Payments/refunds/tax/disputes (v1 stays interop).
• "Never double-sell" until cross-channel auto-delist (Auth + connectors) is real — say "one source of truth" meanwhile.
• Model-heavy, no-free-fallback ideas: photo decomposition / video-sweep, active-learning review, authenticity detector — defer until a corpus/quality bar exists.

6. Source documents

• Canonical: docs/product/capture-to-sale-tracking.md, trovesnap-vision-scanning-spec.md, trovesnap-competitive-learning-and-trojan-horse-strategy.md, docs/product/pricing-and-tokens.md, docs/technical/data-model.md.
• Supporting research / assets (this folder): ai-cataloging-theirs-vs-ours, freemium-ingestion-pain-analysis, qr-closed-loop-and-sticker-packs, auction-outbound-integration-spec, post-sale-inventory-disposition, pipeline-enhancement-ideas, pipeline-pressure-test, capture-to-sale-flow (+ decision-flow A/B), capture-to-sale-pipeline.json, pipeline-dashboard-mockup, trovesnap-estatesale-edition.
• Invariants: project CLAUDE.md, docs/product/style-guide.md, docs/technical/architecture.md, docs/technical/folder-structure.md.