Companion docs: DECK.md and REFERENCES.md

Two files sit next to your slides. They are not slides. They are not optional.

slides/
  index.ts
  title-slide.tsx
  ...
DECK.md
REFERENCES.md

DECK.md is the rules. REFERENCES.md is the receipts. Together they make the deck legible, auditable, and editable by an AI agent.

DECK.md — rules and plan

This is the file Claude Code reads before it edits a slide. It contains:

The narrative arc — what each slide is supposed to do, in order. Headline, goal, key point.
The slide-count rule — 10 to 15 for a YC-style pitch. Resistance to drift past 12.
The 30pt font rule — Kawasaki's heuristic. In Tailwind that's body text-lg minimum, headings text-4xl+. Never text-xs/text-sm for slide body. Footnotes only.
The positioning rule — never claim "we're the best." Show the empty quadrant.
The headline-as-resolution rule — every slide's headline names the artifact from the previous slide and adds the resolution.
The visual-as-headline rule — if the visual carries the message, kill the body copy.
The TAM rule — Market slide leads with customers × price = revenue the investor can recompute, not a Gartner chart.
The funnel rule — Traction slide shows progression, not point-in-time MRR.
The AI editing rule — when a slide changes, its SlideContext updates with it.

This isn't a style guide. It's an opinionated rulebook for one specific deck. The rulebook lives in the repo because Claude Code edits the deck through it.

# DECK.md
 
## Slide plan
1. Title — name + tagline + one image of the substrate
2. Problem — three truths, blunt, no metaphor
3. Solution — substrate diagram, headline names the problem artifact
...
 
## Rules
- 30pt font: text-lg body minimum, text-4xl+ headings
- Slide count: 10–15. Cut before adding past 12.
- Visual-as-headline: kill body copy when the visual lands
...

REFERENCES.md — the receipts

Every external claim in the deck has a row in REFERENCES.md.

# REFERENCES.md
 
## Problem slide
- "Workers spend 41% of their time on low-value repetitive tasks"
  Source: Asana Anatomy of Work Index 2023
  URL: https://asana.com/resources/anatomy-of-work
  Quote: "Workers spend 41% of time on work about work..."
  Verified: 2026-04-12
 
- "BetterCloud — average enterprise has 130+ SaaS apps"
  Source: BetterCloud State of SaaSOps 2024
  URL: https://www.bettercloud.com/state-of-saasops
  Quote: "Companies use an average of 130 SaaS applications"
  Verified: 2026-04-12
 
## Why-Now slide
- ...

Each row: claim, source, URL, extracted quote, verification date. When the deck goes to a top-tier VC's analyst for due diligence, you don't scramble. You hand them the file.

This is also what you check before each institutional pitch. The deck has been alive for months. The 41% number might be 38% now. You don't want to find out from the analyst.

Why these files specifically

The pattern is "documentation that the agent uses, not just documentation that the human reads." Two distinctions matter:

DECK.md is editable input — it shapes how slides are written. When you add a new rule ("never use stock photos"), the agent picks it up the next time it touches a slide.
REFERENCES.md is a checklist — it's the source of truth for every claim. When the agent edits a claim, it updates the row.

These are not READMEs. A README describes a project. These describe rules and facts about a specific deck.

What you don't put here

Slide content — that's in the slide components.
Design tokens — those are in tailwind.config or the design system.
Slide rationale — that's in each slide's SlideContext.nailsThis and SlideContext.storyThread. (Every slide carries its rationale.)

DECK.md is for rules that apply across slides. REFERENCES.md is for facts that come from outside the deck. Neither one duplicates information that lives elsewhere.

What changes when you commit to this

A few things shift quietly.

You stop saying "I'll fact-check this before the pitch." You fact-check at the moment you make the claim, because the row needs to exist or the claim doesn't get to be in the deck.

You stop arguing about font sizes inside the deck. The rule is in DECK.md. The agent enforces it. New slides comply by default.

You stop "fixing" slides in ways that violate principles you've already decided. The principles are written down. The agent reads them.

You can hand a new contributor — human or AI — your repo, and they can ship a slide that fits the deck without asking you anything.

For a YC pitch deck, DECK.md is two pages and REFERENCES.md is half a page. For an information memorandum with thirty slides and dozens of claims, DECK.md adds risk-section rules and financial-table conventions, and REFERENCES.md becomes the appendix that the IM literally references.

The format is the same. The content grows.

What it costs

Twenty minutes to write the first version. Five minutes per claim added. Pays back the first time someone asks "where did that number come from."

In nopoint, the deck scaffolds with empty DECK.md and REFERENCES.md files. You fill them as you write the deck. By the time the deck is done, the receipts are done.