# 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.

**Sprint translation:** D6 in `docs/tracking/decision-log.md` and
`docs/tracking/deliberations/closed-codex-2026-06-18-build-order.md` define the
accepted implementation order: POC-first, five sprints plus parallel positioning.
Use W1-W6 below as the strategy/dependency map, not as one-to-one sprint chunks.

### 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`.