# Wishdeal Factory buyer-path - iteration 84 ship log

**Date:** 2026-05-14 (push mode, 45 min cadence, BIG ship iter: full API documentation)

## What shipped (3 substantive ships + audit-discovery)

This iter delivered on the queue's #1 long-standing item: the /factory/api-docs/ page. The discovery during research changed the page substantially - we found that the Factory already has a far richer live API surface than was documented (factory-api.service running 12 application endpoints, including a live Stripe webhook).

## Ship 1: /factory/api-docs/ - new transparency surface (BIG SHIP)

Live at https://wishdeal.com/factory/api-docs/. ~24.7 KB. Dark-theme docs page matching cron-status / quality-report aesthetic. 17 endpoints documented across two surfaces:

**Static read endpoints (Caddy-served files):**
- GET /factory/state.json - mission-control snapshot, 5 min cadence
- GET /factory/adoptability.json - all 244 scored products, 15 min cadence
- GET /factory/admin/health.json - 74-endpoint live health JSON
- GET /factory/healthz - 1-line text probe with last_tick_age
- GET /factory/dossiers/<slug>/teaser.md - 244 public teasers

**Application endpoints (factory-api Node service, port 3060):**
- GET /factory/api/dossier/<slug>?t=<token>&format=md|html - HMAC-gated full dossier
- POST /factory/api/mint-token - admin-only token mint
- POST /factory/api/stripe-webhook - LIVE, signature-validating when STRIPE_WEBHOOK_SECRET set, placeholder mode otherwise
- POST /factory/api/intent - buyer intent capture
- POST/GET /factory/api/rate - product tier ratings (drives wes_picks)
- POST /factory/api/feedback - generic feedback
- POST /factory/api/event - analytics event
- POST/GET /factory/api/validation - per-product validation tracker
- POST /factory/api/afterhours/{demo,signup} - product-internal routes

Each endpoint has: method tag, URL, auth model, format, cadence/limits, sample curl, response body, contextual note.

Plus three "honest framing" sections: what we will not break, what might change without notice, what we will not promise (no SLA, no rate limits, no v1/v2 deprecation cycle).

**Why the URL is /api-docs/ not /api/:** /factory/api/* is already a reverse-proxy route to the live Node service. The docs page goes at a sibling path so it does not shadow real endpoints.

**Audit-discovery during research:** The iter 75 ship log noted "stripe-webhook.py skeleton ready for Wes." That is true for the Python skeleton at director/stripe-webhook.py. But during research for this docs page, we found that the Node factory-api service at /home/ubuntu/factory/api/server.js has been hosting a fully live Stripe webhook at /factory/api/stripe-webhook for some time. It validates signatures when STRIPE_WEBHOOK_SECRET is set. The docs page documents the real production endpoint, not the skeleton.

## Ship 2: Cross-link wiring for /api-docs/ across transparency surfaces

The new page is now linked from 4 surfaces:

- **/factory/quality-report/** - nav row + footer + new operator-essay callout in intro (also adds reading-adoptability cross-link as a bonus)
- **/factory/cron-status/** - nav row + footer (also adds quality-report to its nav, which was missing)
- **/factory/honest/** - skeptic-Q&A transparency callout updated to include /api-docs/
- **/factory/start-here/** - "verify any of this" callout now mentions all 3 transparency surfaces

All source-fixed in their respective regen scripts (regen-quality-report.py, regen-cron-status.py, regen-honest-page.py, regen-start-here.py). Durable across the cron regeneration cycle.

**Bonus iter 82 fix:** The iter 82 ship log claimed /start-here/ got the transparency callout, but the regen-start-here.py cron overwrote it. The iter 82 edit was made on the live HTML but not the source. Iter 84 source-fixed it for real - it will now stay across regens.

## Ship 3: Cross-link reading-adoptability essay from /quality-report/

Done as part of Ship 2's quality-report wiring. The intro section now ends with:

> The score you see on every product card. The Adoptability score (one of the invariants the catalog enforces) is the primary navigation signal. The full operator-honest reader's manual is at /factory/playbooks/reading-adoptability/. Ten-minute read. Four reading modes. Three axes most operators misread.

The quality-report page is the catalog's content-quality dashboard. The new cross-link bridges it to the operator-honest essay about how to USE the primary score.

## Standard wirings

- **OG generator**: page-api-docs.png generated (63 KB), 19 total OG cards
- **Sitemap**: /factory/api-docs/ added at priority 0.6 weekly. 2317 URLs.
- **Health-check**: 74/74 passing (was 73). Added /factory/api-docs/ endpoint.

## Health hygiene (Op rule 5)

- **Em-dash sweep**: 3 files, 16 dashes stripped (mostly self-inflicted by the new pages being styled with rich content)
- **audit-fakeproof**: 0 hard / 9 soft findings (zero violations)
- **Health-check**: 74/74 passing, avg 12ms
- **Changelog**: regenerated, 83 iters listed (84 after this log lands)

## Status snapshot

- 244 products, 0 broken pages, 0 fake-proof violations
- 10 essays (~18,300 words) + **19 OG images**
- 8 high-trust pages + **4 transparency surfaces** (added /api-docs/)
- 26 hand-polished products
- 10 content invariants defended at surface+source AND surfaced on /quality-report/
- audit-fakeproof.py: 0 hard / 9 soft, daily cron at 4:30am verified
- **stripe-webhook is actually LIVE in Node** - not just a Python skeleton (corrected understanding)
- **74/74 health endpoints**, 2317 sitemap URLs
- 45 min cadence active

## Iter 84 throughput note

3 substantive ships + a meaningful audit-discovery (stripe-webhook was live, not just a skeleton). Sizeable enough to keep 45 min cadence rather than stepping to 60.

The /factory/api-docs/ page closes out the "biggest unbuilt surface" item that has been on every running queue since iter 76. It is also the catalog's strongest credibility surface for technical buyers - it documents the actual API contract, including the honest framing that there is no v1 contract.

## The catalog's transparency surfaces at iter 84

| # | URL | Cadence | Purpose |
|---|---|---|---|
| 1 | /factory/cron-status/ | 15 min | 126 cron jobs, live timestamps |
| 2 | /factory/quality-report/ | 30 min | 10 invariants, audit results, health |
| 3 | /factory/api-docs/ | weekly | 17-endpoint API reference |
| 4 | /factory/healthz | 1 min | One-line ops probe |

Four transparency surfaces, all cross-linked, all source-durable.

## Running queue (top 5 for iter 85)

1. **/factory/log/ INDEX page** - 84 ship logs without a navigable index is a missed surface for operators auditing the studio's pace.
2. **11th playbook essay** - candidate topics: "What we learned from 84 iterations" (meta-honest) OR "What ChatGPT 5.5 does for the catalog generation pipeline" (technical operator interest).
3. **Periodic verification of older polished products** (sample 5 randomly, check quality holds)
4. **Step cadence to 60 min** if iter 85 produces only 1-2 ships - iter 84 was a big-ship iter due to /api-docs/ unlocking; iter 85 may revert to small.
5. **Optional: deeper /api-docs/ work** - add interactive examples (auto-curl-able), or document the 9 soft fake-proof findings on /quality-report/ so they are not invisible.

## Cumulative iter 1-84

- **Catalog**: 244 products, 0 broken, 0 fabrications (hard), 26 hand-polished
- **Content library**: 10 essays + **19 OG cards**
- **High-trust pages**: 8 foundational + **4 transparency surfaces**, fully cross-linked
- **Source durability**: 15+ generators source-fixed + audit-fakeproof.py daily cron + stripe-webhook.py skeleton + factory-api.service live with 12 endpoints
- **Content invariants**: 10 defended + surfaced live on /quality-report/

The Factory now has a documented API contract for the first time. Combined with /quality-report/ + /cron-status/ + /healthz/, a technical buyer can verify every claim in the marketing copy from data they fetch themselves.