From b7e11b2f2c5fd54deaa4890d9b47b40352ec124f Mon Sep 17 00:00:00 2001 From: ACoolNERD Date: Mon, 17 Aug 2026 03:30:49 -0400 Subject: [PATCH 1/7] Protect local secrets and generated artifacts --- .gitignore | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..4e68d9a7 --- /dev/null +++ b/.gitignore @@ -0,0 +1,18 @@ +# Secrets +.env +.env.* +!.env.example + +# OS / editor +.DS_Store +.vscode/ +.idea/ + +# Python +__pycache__/ +*.pyc +.venv/ + +# Generated exports +exports/ +*.log From 52332db3c55d28c1ff80df176ae51f3d4846dc6c Mon Sep 17 00:00:00 2001 From: ACoolNERD Date: Mon, 17 Aug 2026 03:30:55 -0400 Subject: [PATCH 2/7] Add safe SportsCardsPro environment template --- .env.example | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 00000000..3bde8a5f --- /dev/null +++ b/.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 From 79d23b0c206e9d1d735799fc4a327aef6ed2307b Mon Sep 17 00:00:00 2001 From: ACoolNERD Date: Mon, 17 Aug 2026 03:31:00 -0400 Subject: [PATCH 3/7] Remove committed local secrets file --- .env.local | 2 -- 1 file changed, 2 deletions(-) delete mode 100644 .env.local diff --git a/.env.local b/.env.local deleted file mode 100644 index c86f62b1..00000000 --- a/.env.local +++ /dev/null @@ -1,2 +0,0 @@ -SPORTSCARDSPRO_API_KEY=f42b5e4844ea5d15a60d1762686cabcfacb56814 -PRICECHARTING_BASE_URL=https://www.pricecharting.com From 04a0f5ea37a3be3597e6081edfa2981b7d492942 Mon Sep 17 00:00:00 2001 From: ACoolNERD Date: Mon, 17 Aug 2026 03:31:22 -0400 Subject: [PATCH 4/7] Add bounded SportsCardsPro inventory refresh tool --- scripts/sportscardspro_refresh.py | 115 ++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 scripts/sportscardspro_refresh.py diff --git a/scripts/sportscardspro_refresh.py b/scripts/sportscardspro_refresh.py new file mode 100644 index 00000000..1476c164 --- /dev/null +++ b/scripts/sportscardspro_refresh.py @@ -0,0 +1,115 @@ +#!/usr/bin/env python3 +"""Refresh SportsCardsPro guide fields for a bounded inventory slice. + +Safe defaults: +- reads token from environment only +- never writes back to SportsCardsPro +- caps the number of API requests unless the operator raises --max-items +- writes a new CSV instead of mutating the source file + +SportsCardsPro/PriceCharting price data is an internal guide input. Premium public +pricing still requires exact-version/condition proof and completed-sale evidence. +""" + +from __future__ import annotations + +import argparse +import csv +import json +import os +import time +import urllib.parse +import urllib.request +from datetime import datetime, timezone +from pathlib import Path + +DEFAULT_BASE_URL = "https://www.pricecharting.com" + + +def fetch_product(base_url: str, token: str, product_id: str, timeout: int = 20) -> dict: + params = urllib.parse.urlencode({"t": token, "id": product_id}) + url = f"{base_url.rstrip('/')}/api/product?{params}" + req = urllib.request.Request(url, headers={"User-Agent": "ACoolCOLLECTOR/1.0"}) + with urllib.request.urlopen(req, timeout=timeout) as resp: + return json.loads(resp.read().decode("utf-8")) + + +def pennies_to_usd(value: object) -> str: + try: + return f"{int(value) / 100:.2f}" + except (TypeError, ValueError): + return "" + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("input_csv", type=Path) + parser.add_argument("output_csv", type=Path) + parser.add_argument("--max-items", type=int, default=100, + help="Maximum rows to refresh in this run; default 100") + parser.add_argument("--delay", type=float, + default=float(os.getenv("SPORTSCARDSPRO_REQUEST_DELAY_SECONDS", "1.0")), + help="Operator-configured delay between requests; not an official rate-limit claim") + args = parser.parse_args() + + token = os.getenv("SPORTSCARDSPRO_API_KEY") or os.getenv("SPORTSCARDSPRO_TOKEN") + if not token: + raise SystemExit("Set SPORTSCARDSPRO_API_KEY in your local environment; do not commit it.") + + base_url = os.getenv("SPORTSCARDSPRO_BASE_URL", DEFAULT_BASE_URL) + refreshed_at = datetime.now(timezone.utc).isoformat() + + with args.input_csv.open(newline="", encoding="utf-8-sig") as f: + rows = list(csv.DictReader(f)) + original_fields = list(f.fieldnames or []) + + extra_fields = [ + "scp-refresh-status", "scp-refreshed-at", "scp-loose-price", "scp-loose-usd", + "scp-graded-price", "scp-psa10-price", "scp-bgs10-price", "scp-sales-volume", + "scp-review-reason" + ] + fields = original_fields + [x for x in extra_fields if x not in original_fields] + + refreshed = 0 + for row in rows: + product_id = (row.get("id") or "").strip() + if refreshed >= args.max_items: + row["scp-refresh-status"] = "NOT_REFRESHED_LIMIT" + continue + if not product_id: + row["scp-refresh-status"] = "REVIEW" + row["scp-review-reason"] = "Missing SportsCardsPro product id" + continue + try: + payload = fetch_product(base_url, token, product_id) + if payload.get("status") != "success": + row["scp-refresh-status"] = "REVIEW" + row["scp-review-reason"] = str(payload.get("error") or payload.get("status") or "API response not success") + else: + row["scp-refresh-status"] = "REFRESHED" + row["scp-refreshed-at"] = refreshed_at + row["scp-loose-price"] = payload.get("loose-price", "") + row["scp-loose-usd"] = pennies_to_usd(payload.get("loose-price")) + row["scp-graded-price"] = payload.get("graded-price", "") + row["scp-psa10-price"] = payload.get("manual-only-price", "") + row["scp-bgs10-price"] = payload.get("bgs-10-price", "") + row["scp-sales-volume"] = payload.get("sales-volume", "") + refreshed += 1 + except Exception as exc: # keep row and make the failure reviewable + row["scp-refresh-status"] = "ERROR" + row["scp-review-reason"] = f"{type(exc).__name__}: {exc}" + if args.delay > 0: + time.sleep(args.delay) + + args.output_csv.parent.mkdir(parents=True, exist_ok=True) + with args.output_csv.open("w", newline="", encoding="utf-8") as f: + writer = csv.DictWriter(f, fieldnames=fields, extrasaction="ignore") + writer.writeheader() + writer.writerows(rows) + + print(f"Refreshed {refreshed} items; wrote {args.output_csv}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) From 0d9e6f3bc6d3ad51b80f4c9f33a6fb95b56c7301 Mon Sep 17 00:00:00 2001 From: ACoolNERD Date: Mon, 17 Aug 2026 03:31:38 -0400 Subject: [PATCH 5/7] Add BreakVault 30-day operating system --- .../BreakVault_Operating_System_2026-08-17.md | 77 +++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 docs/operations/BreakVault_Operating_System_2026-08-17.md diff --git a/docs/operations/BreakVault_Operating_System_2026-08-17.md b/docs/operations/BreakVault_Operating_System_2026-08-17.md new file mode 100644 index 00000000..2cfe8c97 --- /dev/null +++ b/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. From fdf28536a1d98c9880048cc3856528193473c4d4 Mon Sep 17 00:00:00 2001 From: ACoolNERD Date: Mon, 17 Aug 2026 03:31:59 -0400 Subject: [PATCH 6/7] Refresh SportsCardsPro integration guidance --- docs/ACoolAPI_Integration.md | 89 ++++++++++++++++++++++++++---------- 1 file changed, 64 insertions(+), 25 deletions(-) diff --git a/docs/ACoolAPI_Integration.md b/docs/ACoolAPI_Integration.md index 41f71c0b..0c7f56a6 100644 --- a/docs/ACoolAPI_Integration.md +++ b/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 From 6131750ca89eeab519bd0d6ef4aefb19c16bfdc6 Mon Sep 17 00:00:00 2001 From: ACoolNERD Date: Mon, 17 Aug 2026 03:32:20 -0400 Subject: [PATCH 7/7] Add ACoolCOLLECTOR agent and skill specifications --- .../operations/ACoolAGENTS_and_SKILL_SPECS.md | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 docs/operations/ACoolAGENTS_and_SKILL_SPECS.md diff --git a/docs/operations/ACoolAGENTS_and_SKILL_SPECS.md b/docs/operations/ACoolAGENTS_and_SKILL_SPECS.md new file mode 100644 index 00000000..2e6d4dad --- /dev/null +++ b/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.