Phase 5 / Slice 11 (v2): Build Log article series + about page

[tkowalczyk]

Parent PRD: #1 · Status: unblocked (#10 closed 2026-06)

Problem Statement

The LP ships v1 as a "statements site" — methodology + weekly/monthly financial statements. That is enough to publish a track record. It is not enough to signal that the project is actively maintained, that real R&D is ongoing, or that the methodology has a history worth auditing.

Two specific gaps remain after v1:

1. No narrative. The methodology page cites the source papers and the disclosure policy, but nothing on the site explains how the methodology actually evolved — which decisions were made, what was tried and abandoned, what was learned. Acquirers cannot triage the project's depth without that.
2. No author surface. There is no /about page. A serious institutional reader who wants to know who built this — credentials, public links, partnership contact — has to leave the site to find out.

The blocking constraint from the original issue body has resolved: #10 closed, v1 cadence is sustainable, and we know how much time per week the statements take. Budget exists for articles + an about page.

Solution

Add an article content collection to the LP and ship two surfaces:

1. A chronological Build Log series of 8–10 articles narrating how poly-track was built — sign-randomization replication, anchor methodology evolution, category exclusions, cluster detection, the paper-replication structural finding, infrastructure decisions, etc. Each article covers a build phase and embeds the relevant code/diff excerpts inline; commit ranges are kept in frontmatter as internal metadata since upstream is private. Articles are ~800–1200 words, narrative-led, full methodology detail. Generation is hybrid — an LLM drafts from a commit-range bundle produced by a small extraction script, and the author curates for voice.
2. An /about page identifying the named single author with bio, photo, credentials, partnership-inquiry contact, and public links (GitHub / X / LinkedIn).

The article collection resolves at /articles/<slug> (HTML) and /articles/<slug>.md (markdown) — picked up automatically by the existing Dual-Format Serving and Feed Generator deep modules from Phase 1. The series-vs-essay distinction is encoded by a series field on the frontmatter (no new collection). Post-launch cadence is tied to upstream poly-track milestones — articles ship when a substantive change lands upstream, not on a calendar.

Full methodology detail is the explicit disclosure stance for articles. The site's disclosure policy still binds: never publish full wallet addresses, never publish live alerts, never publish anything that could front-run a still-open position. Build Log articles narrate methodology and decision history; they do not include wallet IDs or alert payloads, both of which remain in statements with their existing anonymization.

User Stories

Institutional reader (acquirer / VC / data buyer)

1. As an institutional reader, I want to land on /about and see who built this with real name, photo, and credentials, so that I can decide whether to take an inquiry seriously.
2. As an institutional reader, I want a partnership-inquiry contact on the about page, so that I can act when ready without scraping the footer.
3. As an institutional reader, I want public links (GitHub / X / LinkedIn) on the about page, so that I can verify identity and prior work independently.
4. As an institutional reader, I want a Build Log article series, so that I can audit not just the current methodology but the decisions that produced it.
5. As an institutional reader, I want each Build Log article to be ~5–8 minutes to read, so that I can triage the project's depth on a coffee break.
6. As an institutional reader, I want the Build Log to read chronologically (episode-numbered), so that the narrative compounds rather than jumping between unrelated topics.
7. As an institutional reader, I want articles to embed real code/diff excerpts inline, so that the methodology claims are inspectable without leaving the page.
8. As an institutional reader, I want articles to ship with the same /<slug>.md companion as statements, so that I can paste an LLM prompt with the markdown URL and get a substantive answer.

Technical peer (quant engineer / data scientist / prediction-market builder)

9. As a technical peer, I want articles that explain why methodology decisions were made (peak-fill vs calendar anchor, sports exclusion, cluster detection), so that I can reuse the reasoning in my own work.
10. As a technical peer, I want articles to acknowledge what didn't work (failed paper-replication, structural divergence), so that I can trust the author's honesty signal.
11. As a technical peer, I want the source papers cited inline where the methodology refers to them, so that I can chase the academic context.

LLM agent (and the human who runs it)

12. As an LLM agent, I want every article available at /articles/<slug>.md with Content-Type: text/markdown, so that I can ingest article content without HTML parsing.
13. As an LLM agent, I want llms.txt to list every article URL with a one-line description, so that I discover articles alongside statements.
14. As an LLM agent, I want articles in the RSS feed alongside statements, so that one subscription covers the whole site.
15. As a human running an LLM, I want pasting ogsfrompoly.com/llms.txt into Claude or ChatGPT and asking "summarize ogsfrompoly's methodology evolution" to produce a substantive answer derived from articles alone.

Author / maintainer

16. As the author, I want the article collection schema to enforce required frontmatter (title, slug, date, series, episode_number, summary, tags, author, reading_time, commit_range), so that CI rejects malformed entries before merge.
17. As the author, I want an extraction script that turns a commit range from the upstream poly-track repo into a markdown context bundle I can paste into Claude, so that drafting an article is a 30-minute task not a 2-hour task.
18. As the author, I want articles to opt-in to a hero image (typographic-only on launch), so that I don't need to source artwork for each piece.
19. As the author, I want the series field to discriminate between build-log (numbered episodes) and essay (ad-hoc), so that future standalone pieces live alongside without polluting the chronological series.
20. As the author, I want the commit_range field captured in frontmatter as internal metadata, so that I retain an audit trail back to the upstream poly-track repo even though the repo is private.
21. As the author, I want post-launch cadence to be tied to upstream milestones (not calendar), so that I am never publishing articles for the sake of publishing.

Operator (post-launch)

22. As the operator, I want Cloudflare Web Analytics to register /about and /articles/... page views the same way it registers statements, so that I can see which articles draw which referrers.

Implementation Decisions

Audience and voice

• Primary audience: institutional acquirer / VC / data buyer (consistent with parent PRD PRD: ogsfrompoly.com landing page v1 — open-book prediction-market intelligence #1).
• Secondary: technical peers. Tertiary: LLM agents.
• Voice: narrative-led, opinionated, ~800–1200 words per article. Light code, no fixed chart commitment.
• Disclosure stance for articles: full methodology detail. Articles narrate mechanics in citable form. Wallet IDs, alert payloads, and anything that could front-run an open position remain out of scope.

Content surface

• Single article content collection. The series field discriminates build-log (numbered episodes) from essay (ad-hoc).
• URL structure: /articles/<slug> (HTML) and /articles/<slug>.md (markdown). Flat namespace; the existing Dual-Format Serving deep module picks the new collection up with zero new per-route code.
• /articles/ listing page sorted by episode_number ascending. Episodes read chronologically (the build narrative); essays appear inline by date.
• /about page at /about, containing: origin story (1–2 paragraphs), author bio with real photo and credentials, partnership-inquiry contact (same address as homepage footer), public links (GitHub, X, LinkedIn).

Schema

• New article Zod schema with fields: title, slug, date, series (enum: build-log | essay), episode_number (integer, required when series === "build-log"), summary, tags, author, reading_time (minutes), commit_range (array of SHAs or refs, internal metadata only), hero (optional URL).
• Independent SCHEMA_VERSION_ARTICLE marker. Articles are an LP-only contract with no upstream producer; versioning is independent of statement to allow each to evolve separately.
• Article schema is colocated with the existing statement schema in the content collection config — extends the Content Schema deep module without widening its surface beyond a new collection registration.

Launch slate

• 8–10 chronological Build Log articles on launch, covering distinct phases of poly-track's evolution.
• Slate selection is deferred to the /carve step — extraction script must exist first so slate selection is informed by real commit-range exploration.

Generation workflow

• Hybrid: the LLM drafts from a commit-range context bundle; the author curates for voice and opinion.
• Small extraction script in this repo (sketch: scripts/extract-commits.ts) — takes a commit range from the sibling auditmos/ogsfrompoly checkout and emits a structured markdown bundle (commits with messages, file-level diffs, scope-relevant excerpts) ready to paste into Claude.
• No clickable commit links in articles — upstream repo is private. Articles stand alone via embedded snippets.
• Self-review is the disclosure gate. The author reviews each article against the disclosure policy before merge. No paired-review requirement.

Phasing within the slice

1. Schema + dual-format wiring + feed inclusion, smoke-tested with one stub article. Verifies the existing deep modules from Phase 1 / Slice 2: Dual-format serving — every content entry resolves at HTML + .md URLs #3 and Phase 1 / Slice 3: Feed generators — rss.xml, llms.txt, sitemap.xml derived from content collections #4 pick up the new collection.
2. /about page shipped as static composition.
3. Articles in batches, after the extraction script is ready. Slate selection happens here.

Feeds

• rss.xml, llms.txt, sitemap.xml remain combined feeds — statements + articles in one stream. No per-collection feed surface introduced.

Visual

• Optional hero field in schema; launch articles ship without imagery. Strong typographic hero (oversized title, monospace meta block) carries each article.

Components (deep modules vs shallow)

#	Component	Shape
1	article collection + Zod schema	Extends the Content Schema deep module — no new module, stable interface widened
2	/about page	Shallow composition — static Astro page
3	/articles/<slug> HTML + .md	Zero new code — existing Dual-Format Serving deep module
4	/articles/ listing page	Composition — sorts by episode_number, filters by series
5	RSS / llms.txt / sitemap inclusion	Zero new code — existing Feed Generators deep module
6	Commit-range extraction script	NEW deep module — small CLI interface, hidden git invocation
7	Article UI primitives	Shallow composition — episode header, embedded snippet block, hero rendering
8	About-page primitives	Shallow composition — bio, photo, contact, link list

Out-of-band setup

• No new Cloudflare resources required.
• Public photo of the author must be sourced before /about ships.

Validation Strategy

Automated acceptance criteria

Component	Acceptance criterion
Article schema rejection	Fixture markdown files with malformed article frontmatter (missing required field, wrong series enum value, missing episode_number when series === "build-log", malformed commit_range) must fail CI before merge. Error message points at the bad field.
Dual-format coverage for articles	The existing dual-format integration test must iterate over the article collection and assert: (a) /articles/<slug> returns text/html and renders the content; (b) /articles/<slug>.md returns text/markdown with a body whose payload matches the source markdown. No content type may be exempt.
Feed regeneration	Feed snapshot tests include the article collection. Adding, removing, or modifying an article fixture produces a deterministic, reviewable diff in rss.xml, llms.txt, sitemap.xml.

Manual acceptance criteria

Component	Acceptance criterion
LLM install-snippet recheck	After 8–10 articles are live, paste the homepage install snippet into Claude and ChatGPT, ask "summarize ogsfrompoly's methodology evolution." Both must produce a substantively correct answer derived from article content alone (no homepage scraping).
Disclosure-policy self-review	Each article passes a pre-merge author review against docs/disclosure-policy.md: no wallet IDs, no live alerts, no content that could front-run an open position.
/about walkthrough	Manual walkthrough on staging: bio, photo, contact, links all render; partnership-inquiry contact is the same address as the homepage footer; all public links resolve.

Definition of "Slice 11 launched"

1. article collection ships with Zod schema; CI rejects malformed entries.
2. /articles/<slug> and /articles/<slug>.md resolve for every entry.
3. rss.xml, llms.txt, sitemap.xml include articles alongside statements.
4. At least 8 Build Log articles are live, covering distinct phases of poly-track's evolution.
5. /about is live with bio, photo, contact, and public links.
6. The LLM install-snippet manual recheck passes against the expanded content surface.

Out of Scope

• Cross-repo article automation. This slice ships manual workflow only. Future automation (poly-track CI emits draft articles on merged PRs) is a v3+ concern.
• Topic slate selection. Deferred to the /carve step — slate selection must be informed by real commit-range exploration via the extraction script.
• Extraction-script boundary tests. The script is treated as a helper; correctness is verified by manual inspection of its output, not by snapshot tests.
• Per-article hero imagery. Launch is typographic-only. Image-based heroes are a future polish task.
• Per-collection feeds. No articles.rss.xml introduced; one combined feed.
• /about page evolution to a "team" framing. v1 is named-single-author. Multi-author or collaborator credits is a future concern.
• Image hosting / Cloudflare Images integration. Only relevant once hero imagery ships.

Further Notes

• Disclosure-policy interaction. Full methodology detail in articles is consistent with the existing disclosure policy because articles narrate mechanics, not positions. Wallet IDs and alert payloads remain in statements only, with existing anonymization. The structural-divergence finding from the paper-replication work (per the cross-project lessons doc) is a candidate Build Log topic — publishing the honest-partial result rather than chasing a green checkbox.
• Schema-versioning rationale. Independent SCHEMA_VERSION_ARTICLE and SCHEMA_VERSION_STATEMENT decouple LP-only contracts from cross-repo contracts. Statements are the v2 cross-repo target; articles remain LP-only for the foreseeable future.
• Post-launch cadence rationale. Tying article cadence to upstream milestones avoids the content-treadmill failure mode. The 8–10 launch articles are the "active maintenance" signal; future articles are bonus.
• Episode-numbering policy. If a retroactive article belongs between episode 3 and 4, it can be inserted as episode_number: 3.5 (decimal) without rewriting the existing ones. Re-numbering existing entries is forbidden — would break /articles/<slug> permalinks and feed history.