Ship log · iter #84
Iteration 84 ship log
2026-05-14 · push mode, 45 min cadence, BIG ship iter: full API documentation
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)
- /factory/log/ INDEX page - 84 ship logs without a navigable index is a missed surface for operators auditing the studio's pace.
- 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).
- Periodic verification of older polished products (sample 5 randomly, check quality holds)
- 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.
- 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.