Changelog - 2026-04-26 (#1)

Context Vigilance: Spec Authoring + Decision Capture for the Long-Form Reader

Overview

This is a documentation-heavy entry, not a code-heavy one. The argument for investing this much time in writing: a thorough spec with captured rationale is the cheapest way to make a future session — mine, a contributor's, or a fresh AI assistant's — productive without 30 minutes of context re-discovery.

What we wrote today will outlast what we built today.

The actual implementation work for this session lives in the sites/fullstack-vc submodule (commits 6b88c29 and 1a4449e); see that submodule's changelog/2026-04-26_01.md for the per-component breakdown. This entry covers the parent monorepo's context-v/ artifacts and the practice of context vigilance itself.

Changes by Area

1. New spec: context-v/specs/An-Internet-Friendly-Responsive-UI-for-Longform-Writing.md

A v0.0.1.0 spec (~700 lines) for the long-form reader UI that will publish the Venture Handbook (formerly the in-joke "Voodoo Handbook") and any future books on the FullStack VC site. Status: Proposed.

Major sections:

• Context — overview, inspiration (Stripe Press, Tufte, The Pudding, mdBook, Lossless Reader prior art), preferred stack, audience + scale, the "wrapper stays out of the way" thesis (load-bearing decision: all content-level features live in @lossless-group/lfm, the reader UI handles only sequencing + reading affordances + theme cohesion).

• Responsive design — four modes (Mobile / Tablet / Half-Screen / Desktop), triggered by container width AND aspect ratio (not viewport-px alone), implemented via container queries. The Half-Screen mode exists specifically because split-screen on a high-DPI laptop is wide-but-portrait — width-only thresholds miss it.

• Section-Specific & Quote Sharing — the highest-leverage feature in the spec. Mobile DM has displaced email as the high-trust distribution channel; people share the part of a piece that hit them, not the whole chapter. Section + quote shares with OG metadata override, the URL-fragment-doesn't-work problem explained (#anchor is never sent to the server, so unfurlers see chapter-level meta), recommended /share/[book]/[chapter]?h=…&q=… SSR endpoint approach to preserve CDN caching, W3C Text Fragments interop.

• Centralized path management — src/config/routes.ts as single source of truth for URL builders AND disk-organization → URL mapping. Disk can nest deeply (src/content/library/books/venture-handbook/); URLs stay short (/read/venture-handbook/strategy-development/).

• Component inventory — 10 components (4 new, several copy-pattern from packages/lfm-astro/), homed in src/components/library/.

• Schema additions — concrete defineCollection() block for src/content.config.ts.

• Acceptance criteria sequenced as v0.1 → v0.2 → v0.3: single chapter render → multi-chapter sequencing + section share → mobile polish + quote share + save-my-place.

• Yak shaving — LFM features the reader depends on, in build order: remark-heading-slugs first, then remark-image-directive, then remark-toc-extract, then (stretch) remark-wikilinks.

• 10 open questions, 9 future-plan items.

Notable design calls captured with rationale so they survive future re-reads:

1. Wing it with LFM (rejected Starlight, mdBook, Quartz) — same brand chrome as the rest of the site, forcing function for LFM wishlist features that other sibling sites also need.

2. Container queries over viewport media queries — driven by user observation that split-screen on his MacBook Pro reports 1732×2158 (wide-but-portrait). Viewport-px alone calls it "Desktop" and ships the full triptych, which then crowds the layout.

3. /read/[book]/[chapter]/ (rejected /library/, /dojo/library/, /books/) — short, verb-clear, SEO-friendly. Disk org stays free to nest deeply.

4. Section/quote shares > whole-chapter shares — mobile message sharing has displaced email; URLs need to land on the section, not the chapter top. URL fragments alone don't work for OG (servers never see #anchor); we use ?h= and ?q= query params combined with #:~:text= for native browser highlighting.

5. /share/... SSR endpoint over SSR-everywhere — preserves CDN caching for the bare chapter URL (the 99% of traffic that's just reading), accepts a small two-route maintenance burden in exchange.

2. Discussion appended in-place: context-v/prompts/Discuss-how-to-Publish-Long-Form-like-eBook.md

Mike's original setup content preserved at the top. Beneath it: a web-search-augmented evaluation of all four options (plus Quartz 4 as a bonus), against the actual shape of the source artifact (10 chapters, ~5–10K words each, ~50 footnotes, ~25 images, parallel sub-section grammar).

Recommendation: wing it with LFM + push three concrete features into @lossless-group/lfm as forcing functions (image directive, heading slugs + per-chapter TOC, wikilinks).

This file became the seed of the spec above. Pattern worth noting: discussion-in-the-prompt-file → leads-to-decision → decision becomes spec → spec becomes implementation. Each artifact is the source of record for the next phase, with rationale carried forward.

3. New orchestration prompt: context-v/prompts/Sequential-Steps-or-Tasks-to-Workthrough.md

The prompt that drove this entire session — three sequential tasks pointed at sub-prompt files (the dojo index, the Areas of Venture section, the long-form discussion). Reusable pattern for delegating multi-step work to an AI assistant: "digest as PM, then execute as lead dev, here are the three pointers."

4. New layout/section prompts: context-v/sitemap/

• sitemap/dojo_index.md — drove the new /dojo landing page in fullstack-vc. Specified the 2/3 hero · 1/3 alternate-CTA layout, the Hero composition fields, and the system-tokens-only constraint.

• sitemap/layouts/sections/Section__Areas-of-Venture.md — drove the Areas-of-Venture grid section by pointing at the Voodoo Handbook source for headings/subheadings.

Together these demonstrate the "describe the component you want, AI assembles it" pattern at two levels: page (dojo_index) and section (Areas-of-Venture).

5. Source artifact bundle: context-v/extra/background-content/

The actual Venture Handbook (née Voodoo Handbook) source: raw Google Doc download (markdown + zip). Included as the source-of-record for the chapters being scaffolded in sites/fullstack-vc/src/content/long-form/venture-workflows/. The original "Voodoo" filename is preserved as historical provenance.

Submodule pointer: sites/fullstack-vc → 1a4449e

Two commits landed in the submodule this session:

• 6b88c29 — dojo page (src/pages/dojo/index.astro), four new reusable components (HeroContentCoreMessage, AlternateCta, AreasOfVentureGrid, TextLinkSpan — all in fresh subdirectories under src/components/), 10 chapter frontmatter scaffolds at src/content/long-form/venture-workflows/, dev port pinned to 4324, header link repointed / → /dojo, two SVG approximations of the Kauffman Fellows mark, theme.css minor additions (--color__pampas, light-mode headline gradient).

• 1a4449e — Voodoo → Venture rename across forward-looking, user-facing references (changelog body + tag, AreasOfVentureGrid header comment, dojo page provenance comment, design-system catalog description). The source_publication frontmatter field on each chapter and the original Google Doc filename are deliberately not renamed (kept as historical provenance — open call to flip if we want full consistency).

See sites/fullstack-vc/changelog/2026-04-26_01.md (post-rename) for the full per-component breakdown.

On "context vigilance" as a practice

The principle behind this entry: every architectural decision worth making is worth writing down with why, not just what. The spec we shipped today contains:

• ~10 close-call design decisions, each with rationale

• ~10 open questions surfaced explicitly (so they're not surprises six months from now)

• ~9 future-plan items (so the v0.1 implementer doesn't accidentally over-build)

• Concrete code samples for the load-bearing primitives (routes.ts, schema additions, share-URL builder)

• Clear acceptance criteria per version (v0.1 / v0.2 / v0.3)

Cost: roughly two hours of focused writing. Payoff: a fresh session reading the spec + CLAUDE.md can implement v0.1 without re-litigating any of the design decisions. That payoff compounds every time the spec is re-read — by a future session, by a new collaborator, by an AI assistant who's never seen the codebase, by Mike six months later.

We don't always need this much documentation. We do for surface-area-large work that touches data shape, URL scheme, shared components, or features other sites will want to copy. The Long-Form Reader hits all four.

What's NOT in this commit (intentional scope)

The parent monorepo also has unstaged work on:

• context-v/specs/Codifying-a-Comprehensive-Extended-Markdown-Flavor-and-Shared-Package.md (Mike's separate edits to the LFM spec)

• context-v/specs/Dynamic-Webpage-to-Display-Portfolio-w-Authentication.md (Mike's separate edits)

• context-v/specs/Maintain-an-Interactive-Stack-Display.md (Mike's separate edits)

• context-v/explorations/Choosing-the-Right-DataStores.md (Mike's separate exploration)

• context-v/reminders/Quirks-of-Obsidian-Flavored-Markdown.md (Mike's separate reminder)

Those are independent threads — committed separately when they're ready, by Mike.

Next session

The natural opening prompt for the next session: "Implement v0.1 of the long-form reader per context-v/specs/An-Internet-Friendly-Responsive-UI-for-Longform-Writing.md. Start with src/config/routes.ts, then content collection registration in src/content.config.ts, then BookReaderLayout.astro, then a single test chapter."

Probable yak-shave that lands first: remark-heading-slugs in @lossless-group/lfm (~30 LOC). The reader's mobile ToC, anchor-link-on-hover, AND section-share URLs all depend on stable heading IDs.