build-in-public-docs — Implementation Plan

build-in-public-docs — Implementation Plan

Alias: bpd — invoke as /pipeline bpd <section> or /discovery bpd <section>. Section IDs in YAML + commits still use the canonical slug build-in-public-docs.

Context

/build-log is the channel's "show the work" surface — a public, SEO-indexed section of fabled10x.com that renders the agent-driven build process of the site itself as published content. Viewers who watch a Fabled10X episode about the TDD pipeline can land on /build-log/jobs/website-foundation and read the exact plan the agents are executing against, then visit /build-log/status to see what beat is currently running. The methodology and the artifact are the same thing. This job is #8 in docs/future-jobs.md and implements the "Full documentation of site build process as Fabled10X content" bullet from Phase 4 ("The Meta Play") of docs/fabled10x-website-implementation-plan.md.

The scope is two new loaders (one for the currentwork/ job tree, one for the pipeline/active/ YAML state) plus four routes (/build-log index, /build-log/jobs/[slug] job README, /build-log/jobs/[slug]/[phase] phase file, /build-log/status live status board), plus a runtime markdown rendering component to render the existing .md files as styled HTML, plus the usual SEO/sitemap/nav polish. The section is fully public, indexable, no email gate, in keeping with the brand doc's "show the work" principle. Source data is read from disk at build time — there is no database, no real-time updates, no editing-from-the-site.

This job depends entirely on website-foundation (alias wf) having shipped: the brand design tokens, the site shell, the <Container> primitive, the validators module, the dynamic sitemap, the header nav, the metadataBase configuration, the SEO + JSON-LD pattern, and the generateStaticParams

• dynamicParams = false pattern all come from that job.

Out of scope (explicit non-goals): editing currentwork/ or pipeline/ artifacts from the site, running pipeline operations from the site, real-time updates, git-log integration, pipeline/archive/ history view (the future-jobs entry calls this "optional" — defer to a follow-up job), search across the build-log (deferred to the dedicated search job), per-section drill-downs into pipeline/active/{section}/discovery.yaml (those YAMLs are too noisy and churn too fast to render as published content), parsing phase-file markdown bodies into structured trees (only the README's feature table gets parsed structurally — phase bodies pass through to the markdown renderer as opaque strings).

What Already Exists

Already in the repo today (2026-04-11)

• Next.js 16 App Router scaffold — React 19.2.4, Tailwind 4, strict TS, @/ → src/. (package.json, tsconfig.json, next.config.ts)
• Standalone output configured — next.config.ts sets output: "standalone" for self-hosted VPS deploy.
• Content schemas — src/content/schemas/{content-tier,content-pillar,episode,source-material,index}.ts. No Job/JobPhase/SessionStatus/KnowledgeFile types yet.
• currentwork/ tree — already populated with 7 planned jobs (website-foundation, community-showcase, testimonials-results, cohort-enrollment, email-funnel, free-tools, storefront-auth) plus TEMPLATE.md. Each job dir has a README.md + 3–4 phase-N-{slug}.md files. The loader walks this tree directly — no MDX, no frontmatter.
• pipeline/active/ YAML state — session.yaml (id, current_phase, current_section, current_agent, current_stage, context_window, completed_sections list, notes) and knowledge.yaml (project_context, conventions, patterns, open_questions). Both small (under 4KB), both updated by the TDD pipeline skills as work progresses.
• Job alias convention — aliases live at the top of each currentwork/{slug}/README.md as a **Alias:** {short} — ... line. They are NOT centralized in CLAUDE.md. The loader extracts them per-job from the README.
• Test infra — Vitest 2.1.8 + jsdom, @testing-library/jest-dom/vitest loaded via src/__tests__/setup.ts, MSW 2.7 installed, coverage thresholds 70/80/80/80 (vitest.config.ts).
• Source docs — docs/fabled10x-website-implementation-plan.md, docs/fabled10x-brand-identity.md, docs/future-jobs.md, AGENTS.md (Next.js 16 local-docs reminder).
• public/llms.txt — already populated (will be polished further by wf 4.4 first, then mention /build-log here in 3.1 — merged polish section).

Delivered by website-foundation (prerequisite — NOT YET SHIPPED when this plan is written)

This job reuses these wf outputs and cannot start its TDD cycles until they exist.

• Brand design tokens (src/app/globals.css from wf 1.3) — --color-{ink,parchment,ember,steel,mist,signal} + semantic aliases --color-{background,foreground,muted,accent,link}. Tailwind class surface: bg-accent, text-muted, border-mist, text-link, bg-parchment, font-display.
• Site shell (src/components/site/{Header,Footer}.tsx + src/app/layout.tsx from wf 1.4) — mounted root layout with metadataBase set to https://fabled10x.com.
• <Container> layout primitive (src/components/site/Container.tsx from wf 1.4) — mx-auto w-full max-w-5xl px-6 md:px-10, accepts className + as prop. Used as the page wrapper on every build-log route.
• Zod validators module (src/content/schemas/validators.ts from wf 1.2) — EpisodeSchema, SourceMaterialSchema, CaseSchema. JobSchema, SessionStatusSchema, KnowledgeFileSchema are added here following the same export style.
• Dynamic sitemap (src/app/sitemap.ts from wf 4.4) — Phase 3.1 of this job (merged polish) appends /build-log + /build-log/status + every job and phase URL.
• Header nav (src/components/site/Header.tsx from wf 1.4) — Phase 3.1 adds a "Build log" link with active-state highlighting on /build-log.
• Homepage (src/app/page.tsx from wf 3.1) — Phase 3.1 inserts a small "Inside the build" callout linking to /build-log.
• Pattern: getAllX() / getXBySlug() (src/lib/content/episodes.ts, src/lib/content/cases.ts from wf 2.2) — this job applies the same shape to getAllJobs() / getJobBySlug() despite reading a different filesystem location (currentwork/ instead of src/content/).
• Pattern: module-level cache + Object.freeze (wf 2.2) — both build-log loaders cache their parsed result and freeze the returned arrays to prevent caller mutation.
• Pattern: generateStaticParams + dynamicParams = false (wf 3.3, 3.5) — /build-log/jobs/[slug] and /build-log/jobs/[slug]/[phase] follow the same shape so unknown slugs and phases 404 at build time.
• Pattern: generateMetadata + JSON-LD via dangerouslySetInnerHTML (wf 4.3) — every build-log page gets per-route metadata; job and phase pages embed TechArticle JSON-LD.
• public/llms.txt — polished by wf 4.4; this job's 3.1 adds /build-log to the sitemap section.
• Permissive robots.ts (wf 4.4) — already allows the build-log section by default; no robots changes needed in this job.

Feature Overview (6 Features, 3 Phases — post-condense from 9)

Size guide: S = few hours, single file. M = half day, 2-3 files. L = full day, 4+ files. XL = multi-day, new content type + loader + UI.

Total rough job size: M/L — comparable to testimonials-results (M/L). Slightly heavier than the docs/future-jobs.md "M" estimate because the loaders parse non-trivial markdown structure (the README feature table) and ship a runtime markdown rendering pipeline that the rest of the site doesn't yet have.

Condense history: Originally planned as 9 sections; condensed to 6 on 2026-04-12 via three merges — 1.1+1.2 (inseparable pair: schemas + their consumer), 2.2+2.3 (same-entity views: jobs index + jobs detail), 3.1+3.2 (small finishing touches). No deliverables dropped.

Dependency Graph (post-condense)

Phase 1: Foundation (schemas + loaders)
│
│   1.1 → 1.2              ← strictly sequential
│                            (schemas + job-tree loader bundled in 1.1
│                            because the loader can't be tested without
│                            the schemas; 1.2 joins the job index against
│                            session.yaml.completed_sections)
│
v
Phase 2: Pages (markdown component + routes)
│
│   2.1 ─┬→ 2.2             ← <MarkdownDocument> blocks every page;
│        └→ 2.3                2.2 (index+jobs+phases) and 2.3 (status)
│                              are parallel after 2.1
│
v
Phase 3: Polish (SEO + sitemap + nav + a11y)
│
    3.1                      ← single consolidated polish section
                              (metadata + sitemap + nav + llms + homepage
                              + a11y sweep), depends on Phase 2 complete

Hard dependencies:

• 1.1 self-contained — schemas + job-tree loader consolidated into one feature because the loader (getAllJobs/getJobBySlug/getJobPhase) imports Job / JobSchema and can't be meaningfully tested without them.
• 1.1 → 1.2 — getSessionStatus imports SessionStatusSchema (from 1.1); getKnowledgeFile imports KnowledgeFileSchema (from 1.1); getJobsRollup joins getAllJobs (from 1.1) against the completed_sections list from session.yaml. Without 1.1 there's no schemas and no job list to join against.
• Phase 1 → Phase 2 — every page in Phase 2 calls one or more loader functions. Without the loaders, the pages have no data.
• 2.1 → 2.2, 2.3 — <MarkdownDocument> is mounted by every build-log page (the index renders job summary excerpts; jobs/phases render full markdown bodies; the status board renders the knowledge.yaml.notes block via the same component). Building pages before the renderer means duplicating the react-markdown wiring.
• 2.2 and 2.3 are parallel — 2.2 (index + job + phase pages) consumes getAllJobs/getJobBySlug/getJobPhase; 2.3 (status board) consumes getSessionStatus/getKnowledgeFile/getJobsRollup. Different route files, different loader entry points.
• Phase 2 → 3.1 — polish needs every route to exist first. Per-page metadata widens Phase 2's static metadata consts; sitemap append needs every route to be enumerable; nav link needs /build-log to exist so the active state has a target; homepage callout needs /build-log to link to. 3.1 is the single consolidated polish pass.

New Content Types Required

All types live in src/content/schemas/build-log.ts. JobFeature, JobPhase, and JobRollupEntry are exported but not re-exported as top-level types elsewhere — they only appear nested on Job / the rollup return shape. JobSchema, SessionStatusSchema, KnowledgeFileSchema are added to src/content/schemas/validators.ts alongside the existing EpisodeSchema / CaseSchema per the wf 1.2 convention.

Critical Files Reference

Verification Plan

Phase Documentation

• Phase 1: Foundation — schemas, job-tree loader, pipeline-state loader
• Phase 2: Pages — <MarkdownDocument> + four routes
• Phase 3: Polish — SEO + sitemap + nav + llms.txt + homepage callout + a11y sweep

Dependencies to Add

Installed in Phase 1.2 (post-condense; was 1.3) and Phase 2.1:

zod is already installed by wf 1.2. All packages above are pure-JS, MIT-licensed, well-maintained, with no native build steps. Total install footprint ≈ 600KB unminified.

Open Items (Resolve During Implementation)

• Code highlighting theme — rehype-highlight doesn't ship CSS itself. Phase 2.1 imports a highlight.js/styles/*.css theme that matches the brand tokens — probably github-dark.css against the dark surfaces or github.css against the light surfaces. Final call during /green 2.1 after the brand tokens land from wf 1.3.
• Markdown caching strategy — getAllJobs() IS cached at module-load (matches the wf content loader pattern). Individual phase bodies are NOT separately cached — they're loaded on demand inside the route's generateStaticParams iteration during npm run build, then served as static HTML. No runtime fetch.
• Status board refresh signal — there is none in v1. The page is statically rebuilt on every npm run build. If real-time freshness is desired later, an ISR + revalidate upgrade can be added without touching the loader contract.
• Empty currentwork/ guard — getAllJobs() returns [] (does NOT throw) if currentwork/ contains only TEMPLATE.md and no job dirs. The community-showcase 1.2 pattern of throwing on empty makes sense for content galleries but NOT for a build log — the absence of jobs IS information worth showing. The /build-log index page handles the empty array with an "Initializing..." empty state.
• Phase header parsing strictness — parsePhase parses the leading header block (# Phase N: ..., **Total Size:** ..., **Prerequisites:** ...) via regex. If a phase file omits the header block (e.g. a hand-edited in-progress file), the parser returns undefined for the missing fields and the page renders the body without the header strip rather than failing. Strict mode is rejected because the build log should be tolerant of in-progress artifacts.
• Feature Overview table parsing strictness — same logic. If a job README omits the table or formats it differently, parseReadme returns features: [] and the page renders the README body without a structured feature index. The job rollup row for that job shows unknown rather than zero-percent.
• session.yaml schema tolerance — SessionStatusSchema makes most fields optional except id and completed_sections. The pipeline skills update these fields independently and a freshly-initialized session may have many empty strings. Strict required fields would break the build during normal initialization windows.
• completed_sections shape — session.yaml.completed_sections is currently an empty list. The shape going forward (per the partymasters port) is one entry per finished /refactor cycle, with at least a section ID ({job-slug}-{phase}.{feature}) and optionally a timestamp. The schema accepts both string-only and object entries to remain forward-compatible.
• JSON-LD type for build-log pages — Phase 3.1 uses TechArticle for job and phase pages and CollectionPage for the index and status board. These are the closest schema.org types for "developer-facing technical writing".

Section IDs for TDD Workflow (post-condense — 6 sections)

Each feature maps to one section ID used by /discovery, /red, /green, /refactor. Section IDs use the canonical slug build-in-public-docs, not the alias bpd.

These IDs are consumed by pipeline/active/session.yaml and used as directory names under pipeline/active/.