Add BreakVault 30-day operating system and secure SportsCardsPro integration

.env.example

@@ -0,0 +1,6 @@
+# Copy to .env.local and fill locally. Never commit real secrets.
+SPORTSCARDSPRO_API_KEY=
+
+# Optional operational settings
+SPORTSCARDSPRO_BASE_URL=https://www.pricecharting.com
+SPORTSCARDSPRO_REQUEST_DELAY_SECONDS=1.0

.gitignore

@@ -0,0 +1,18 @@
+# Secrets
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+.vscode/
+.idea/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# Generated exports
+exports/
+*.log

docs/ACoolAPI_Integration.md

@@ -1,31 +1,70 @@
 # API Integration Documentation
 
-## SportsCardsPro API
-The primary data source for card valuations is the SportsCardsPro (PriceCharting) API.
+## SportsCardsPro / PriceCharting Prices API
+
+SportsCardsPro is a current price-guide and demand input for ACoolCOLLECTOR. It is not, by itself, the final completed-sale evidence source for premium transactions.
 
 ### Authentication
-- **Parameter:** `t`
-- **Key:** Obtained from `.env.local` (`SPORTSCARDSPRO_API_KEY`).
+
+- Premium API access requires a qualifying paid subscription.
+- Authentication uses the `t` request parameter.
+- Store the real token only in local/runtime secrets such as `SPORTSCARDSPRO_API_KEY`.
+- `.env.local` is ignored and must never be committed.
 
 ### Base URL
-- `https://www.pricecharting.com`
-
-### Endpoints
-1. **Product Lookup:** `GET /api/product?id=[ID]&t=[TOKEN]`
-   - Used for fetching the latest price for a specific card.
-   - Priority: `loose-price` (for Raw/Ungraded cards).
-2. **Search:** `GET /api/products?q=[QUERY]&t=[TOKEN]`
-   - Returns up to 20 products matching the query.
-   - Used for adding new cards to the inventory.
-
-### Rate Limits
-- 1 call per second.
-- CSV download: 1 per 10 minutes.
-
-## Data Mapping
-| CSV Column | API Field | Note |
-| :--- | :--- | :--- |
-| `id` | `id` | Matches SportsCardsPro Product ID |
-| `price-in-pennies` | `loose-price` | Current market value for Raw cards |
-| `product-name` | `product-name` | Full card title |
-| `console-name` | `console-name` | Set/Category info |
+
+`https://www.pricecharting.com`
+
+SportsCardsPro documentation and examples also reference the SportsCardsPro domain, but the documented base URL is PriceCharting.
+
+### Current-price endpoints
+
+1. `GET /api/product?t=[TOKEN]&id=[SPORTSCARDSPRO_ID]`
+   - Current data for one mapped product.
+   - `loose-price` = ungraded/raw guide value for cards.
+   - Other graded fields must be mapped to the exact grading service/grade.
+2. `GET /api/products?t=[TOKEN]&q=[QUERY]`
+   - Returns up to the first 20 matching products.
+   - Use for mapping only when a validated SportsCardsPro product ID is unavailable.
+
+### Bulk data
+
+SportsCardsPro provides downloadable price-list CSVs to eligible subscribers. Their documentation says these CSVs are generated once every 24 hours. Prefer bulk set downloads for large refreshes when available rather than issuing unnecessary one-product requests.
+
+### Important limitation
+
+The Prices API and downloadable price CSVs provide **current item values**, not historical sale records. Premium ACoolCOLLECTOR pricing should therefore pair exact-version/condition proof with completed-sale evidence from sources such as eBay, 130point, and TCGplayer where applicable.
+
+### Price / demand fields
+
+Common card fields include:
+
+- `id`
+- `product-name`
+- `console-name`
+- `loose-price` — ungraded
+- `graded-price` — graded 9 guide field
+- `manual-only-price` — PSA 10 guide field for cards
+- `bgs-10-price` — BGS 10 guide field
+- `sales-volume` — yearly units sold
+- retailer buy/sell guide fields where included
+
+Prices are integer pennies in the API response. Persist both the raw penny field and normalized USD.
+
+## ACoolCOLLECTOR mapping
+
+| Inventory field | SportsCardsPro field | Control |
+|---|---|---|
+| `id` | `id` | Require match verification if source is not a known SportsCardsPro export |
+| `product-name` | `product-name` | Exact parallel/version matters |
+| `console-name` | `console-name` | Used with product name for mapping review |
+| `price-in-pennies` | `loose-price` | Current guide input for raw cards, not completed-sale proof |
+| grading data | graded guide fields | Never infer service/grade when absent |
+
+## Rights / redistribution gate
+
+SportsCardsPro terms state that its price data may be used for internal business purposes under an active qualifying subscription, while third-party-accessible redistribution requires permission. ACoolCOLLECTOR therefore defaults SportsCardsPro price data to internal decision support unless external-display rights are separately cleared.
+
+Official documentation:
+- https://www.sportscardspro.com/api-documentation
+- https://www.sportscardspro.com/page/terms-of-service

docs/operations/ACoolAGENTS_and_SKILL_SPECS.md

@@ -0,0 +1,142 @@
+# ACoolCOLLECTOR Agent Mesh + Skill Specifications
+
+These are operating specifications for the repository and automation layer. They do not grant agents authority to buy, sell, move custody, expose PII, or publish premium-card prices without the human gates below.
+
+## Agent hierarchy
+
+### ACoolOMNI — Orchestrator
+
+**Inputs:** inventory state, calendar, market refresh state, content state, live state, fulfillment/reconciliation exceptions.
+
+**Outputs:** prioritized daily plan, routing to sub-agents, exception summary.
+
+**Human gate:** Collector Lead approves irreversible external actions.
+
+### ACoolCARD Intake — Inventory sub-agent
+
+- Normalizes imports.
+- Creates/maintains asset IDs and source lineage.
+- Flags duplicate IDs, missing folder/location, missing cost basis, missing grade/cert, and identification ambiguity.
+- Routes premium digital-twin enrichment to Ruth Review.
+
+### BETH Market — Market-intelligence sub-agent
+
+- Reads exact card identity and condition evidence.
+- Refreshes SportsCardsPro current-guide fields.
+- Collects completed-sale evidence from eBay, 130point, and TCGplayer where applicable.
+- Produces comp confidence, cash/trade/lot scenario, evidence timestamp, and review reason.
+- Does not finalize premium public pricing below the required evidence/confidence gate.
+
+### CONTENT-25 — Content sub-agent
+
+- Selects 25 sale assets/day from eligible inventory.
+- Produces hooks, card facts, CTA, channel adaptation, and live-event bridge.
+- Sends premium/high-variance assets to Ruth Review before publish.
+
+### ACoolBREAK Producer — Break-ops sub-agent
+
+- Builds disclosed break manifests from eligible inventory.
+- Creates spot schema, participant ledger template, run of show, evidence checklist, and fulfillment map.
+- Does not invent undisclosed mystery/raffle mechanics.
+
+### LIVE Director — Broadcast sub-agent
+
+- Validates cameras, microphones, lighting, network, scene framing, recording, and clip-marker plan.
+- Tracks live milestones and records exception timestamps.
+- Host retains go-live/end authority.
+
+### BreakVault Custody — Custody sub-agent
+
+- Links every break item and hit to its digital twin.
+- Records protection, assignment, packing handoff, and storage-location events.
+- Requires front/back/serial/cert evidence for premium assets.
+
+### HOWARD Community — Community sub-agent
+
+- Moderates questions and claims.
+- Routes FAQs, payment handoff, shipping questions, and post-live follow-up.
+- Cannot override price, payment state, ownership, or custody records.
+
+### Fulfillment Agent
+
+- Generates pack lists from paid assignments.
+- Controls label queue and tracking state.
+- Keeps customer addresses and other PII off public video and public artifacts.
+
+### Finance Recon
+
+- Reconciles paid orders, fees, refunds, shipping, adjustments, and inventory state daily.
+- Human approval is required before authoritative accounting writeback.
+
+### SportsCardsPro Sync
+
+- Reads the API token only from secrets.
+- Refreshes bounded inventory slices or bulk price files.
+- Preserves source ID, raw pennies, normalized USD, refresh timestamp, sales volume, mapping confidence, and exceptions.
+- Does not redistribute SportsCardsPro price data externally without rights clearance.
+
+### Ruth Review — QA / disclosure gate
+
+- Checks public facts, exact identity, condition claims, comp evidence, break proof, and correction language.
+- Can fail an asset/event back to the responsible agent.
+- Premium content does not bypass this gate.
+
+---
+
+# Reusable skill specifications
+
+## Skill: ACoolCOLLECTOR Inventory Intake
+
+**Trigger:** a new collection CSV/export/photo batch is supplied.
+
+**Steps:**
+1. Preserve the source snapshot unchanged.
+2. Normalize fields into the inventory ledger.
+3. Detect duplicate IDs/SKUs and quantity ambiguity.
+4. Classify category, set, player/character, year, variation, grade, cert, and storage state.
+5. Generate data-quality exceptions.
+6. Create digital-twin enrichment queue.
+7. Never overwrite a source snapshot.
+
+## Skill: BETH Comp Refresh
+
+**Trigger:** a card is about to be posted, priced, graded, financed, insured, traded, or placed into a premium break.
+
+**Steps:**
+1. Confirm exact card/version/serial/grade/condition.
+2. Refresh SportsCardsPro guide/demand fields.
+3. Gather completed-sale evidence from eBay/130point/TCGplayer where applicable.
+4. Exclude asking prices from the comp set.
+5. Calculate cash/trade/lot scenarios and confidence.
+6. Require at least 9.7/10 evidence quality for final premium recommendations; otherwise expose the evidence gap.
+
+## Skill: CONTENT-25 Daily Sell Queue
+
+**Trigger:** daily content-production cycle.
+
+**Steps:**
+1. Remove duplicate/reconciliation holds.
+2. Rank by sellability, marketability, value, star/character demand, scarcity/parallel features, and inventory strategy.
+3. Protect high-value/parallel-sensitive assets until BETH + Ruth Review pass.
+4. Route sub-$5 cards toward lots/breaks rather than labor-heavy one-off sale posts.
+5. Output five waves of five with TikTok, YouTube, and WhatsApp adaptations.
+6. Reconcile posted/sold/held/skipped state nightly.
+
+## Skill: ACoolBREAKS Live Event
+
+**Trigger:** a scheduled live break/showcase.
+
+**Steps:**
+1. Freeze the disclosed manifest and rules.
+2. Validate participant/payment ledger.
+3. Prove product or disclosed inventory board on camera.
+4. Perform and record randomization only if the published format uses it.
+5. Keep an uninterrupted opening/showcase record.
+6. Assign and protect hits immediately.
+7. Recap, reconcile, fulfill, and retain evidence.
+
+## Skill: Ruth Review
+
+**Trigger:** premium price/post, break launch, public correction, or material inventory exception.
+
+**Checks:** identity, version, condition, source freshness, sold-vs-asking evidence, unsupported claims, ownership/custody, PII exposure, participant fairness, fulfillment traceability, and correction requirement.

docs/operations/BreakVault_Operating_System_2026-08-17.md

@@ -0,0 +1,77 @@
+# ACoolCOLLECTOR BreakVault Operating System — 2026-08-17
+
+## Source of truth
+
+- Newest collection source: `collection_20260817 2.csv`
+- 4,003 inventory rows / 4,022 represented units.
+- Stored source guide-price total: approximately $10,391.04 before fresh completed-sale verification.
+- Duplicate product IDs are routed to reconciliation before posting or break assignment.
+- Drive Command Center: `ACoolCOLLECTOR_BreakVault_OS_2026-08-17/00_COMMAND_CENTER`.
+
+## Brand / platform architecture
+
+- **ACoolCOLLECTOR** — master collector platform.
+- **ACoolCARD** — inventory, collection, valuation, and digital-twin layer.
+- **BreakVault** — trust, custody, break evidence, and fulfillment chain.
+- **ACoolBREAKS** — live commerce/community operating layer.
+- **BETH** — market intelligence and comp confidence.
+- **HOWARD** — community routing and help.
+- **Ruth Review** — final quality and disclosure gate.
+
+Tagline: **Cards today. Legacy tomorrow.**
+Operating principle: **Collect. Verify. Protect. Grow.**
+
+## Daily content cadence
+
+Create 25 inventory-specific assets per day in five waves of five:
+
+1. 09:00 ET — hero cards.
+2. 11:30 ET — player/set cards.
+3. 14:00 ET — value/lot cards.
+4. 17:00 ET — pre-live cards.
+5. 22:15 ET — hits / last-call cards.
+
+The same 25 inventory assets can be adapted into TikTok vertical posts, YouTube Shorts, and the indexed WhatsApp Daily 25 drop. Premium claims remain pending until identity, condition, current evidence, and payment are confirmed.
+
+## Weekly live cadence
+
+| Day | Time ET | Program |
+|---|---:|---|
+| Monday | 20:00 | Market Monday Singles Showcase |
+| Tuesday | 20:30 | Basketball Break |
+| Wednesday | — | Production, clipping, fulfillment, prep |
+| Thursday | 20:30 | One Piece / Baseball rotation |
+| Friday | 21:00 | Football Prime |
+| Saturday | 14:00 + 20:00 | Multi-Sport Matinee + BreakVault Prime |
+| Sunday | 19:00 | Hits Recap + Ship With Me |
+
+## Broadcast roles
+
+- DSLR via compatible HDMI capture: YouTube horizontal master.
+- Logi camera: overhead/card close-up or backup.
+- Phone in ONN RGB ring-light holder: TikTok 9:16 vertical.
+- Bower dual wireless microphones: host + guest/backup after connector/audio testing.
+- WhatsApp: daily drop, alerts, claims handoff, follow-up, and results—not the primary video master.
+
+## Break evidence standard
+
+Every break must preserve:
+
+1. product or fully disclosed inventory-board proof,
+2. published format and rules,
+3. participant/payment ledger,
+4. recorded randomization when the disclosed format uses randomization,
+5. uninterrupted opening/showcase record,
+6. hit assignment,
+7. protection/custody event,
+8. packing and tracking,
+9. delivery/refund/dispute disposition,
+10. final inventory and financial reconciliation.
+
+## Premium-card gate
+
+Do not finalize price or break placement for high-value, vintage, autographed, serialized, short-print, parallel-sensitive, or condition-sensitive inventory until the exact version and condition are verified. SportsCardsPro is a current guide/demand input; completed-sale evidence should be added from eBay/130point/TCGplayer when applicable before a premium public ask.
+
+## Required next inventory enrichment
+
+For important assets, add front/back/angled images, exact variation, serial, grading data/cert, complete cost basis, beneficial owner, storage location, custody history, insurance value when applicable, movement authorization, and sell/hold/grade/break instruction.