read-only

Decouple the agentic board from DOCS_ENABLED — ship /board publicly in production while the /knowledge reading surface stays gated dark

0035-board-public-knowledge-gated

decision read as Explain confidence asserted status active 2026-06-16 owner product-owner
Reversibility
two-way door

DEC-0035 — Ship the board publicly while the KB reading surface stays gated

Reversibility: two-way door — re-coupling the board to DOCS_ENABLED is one guard restored; trivially reversible by flipping DOCS_ENABLED on in production, which lights both surfaces. The durable intent — the board is a self-contained, public-ready proof of the loop, the not-yet-ready KB reading surface stays dark — is what holds.

Context

Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own put the marketing landing public while holding the OKF knowledge-base reading surface back behind a reversible DOCS_ENABLED env flag: default ON for local dev/build, false in production via packages/site/vercel.json build.env, so a production build emits only index.astro (+ the capture endpoint) and the Starlight /knowledge/* routes are not built. The KB reading surface "isn't a public artifact yet" was the explicit reason for the gate.

When the read-only agentic board surface (Agentic "sprint board" architecture — a git-resident OKF task board worked by bounded, hook-governed Agent SDK loops / Agentic board v1 — build the git-resident OKF task board (deterministic offline core, SDK reserved), resolving DEC-0024's four open questions and dogfooding Dossier's own repo first, redesigned as "The Ledger of Work" in The read-only /board redesigned as "The Ledger of Work" — reframe the surface from task-management to loop-health legibility, with motion that animates only real git state) was built, it was coupled to that same DOCS_ENABLED flag — in landing-only production the board rendered a "this is part of the docs surface" teaser instead of the real board. So the single flag darkened both the Starlight KB reading surface and the board, even though the two are very different in readiness: the board is a self-contained, compelling, read-only proof of Dossier's agentic learning loop, while the full KB reading surface is not yet ready for public exposure.

This decision decouples the board from DOCS_ENABLED so the board ships publicly now while the KB reading surface stays gated dark. It was made and the code change completed this session (2026-06-16); see Verification for the honest build status.

Provenance note — a DEC-number mislabel inherited here, not propagated. The triggering instruction and the in-file comments in packages/site/src/pages/board.astro (lines ~57-64) attribute the landing-only DOCS_ENABLED gate to "DEC-0021". The landing-only gate is actually DEC-0022 (Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own); DEC-0021 is Web ingestion — a keyless HttpConnector by default, Firecrawl wired as the premium path, and a first-class CLI web-ingest mode (the keyless web connector), an unrelated record. This decision is therefore linked to the correct record (DEC-0022) and does not carry the wrong edge forward. The stale "DEC-0021" references in the board.astro source comments were corrected to DEC-0022 (and a DEC-0035 reference added) the same session — see Consequences; the mislabel was never a rationale.

Options considered

1. Keep the board coupled to DOCS_ENABLED (status quo) vs. decouple it.

  • (a) Keep them coupled — one flag gates both the KB reading surface and the board; the board shows the "part of the docs surface" teaser in landing-only prod. Rejected: it withholds a surface that is ready to show publicly (the board) solely because a different surface (the KB reading pages) is not ready. The two surfaces have independent readiness; one flag should not conflate them.
  • (b) Decouple the board from DOCS_ENABLED; load task atoms unconditionally; narrow the flag to gate only links into the reading surface (chosen). The board renders publicly in production; the Starlight /knowledge/* reading routes stay dark behind DOCS_ENABLED=false. The flag's residual job shrinks to gating the links into the reading surface (the Docs nav link, the "Browse the knowledge base" CTA), not the board's own data.

2. How the board gets its data in a landing-only build — does removing the guard actually work?

  • The load now runs unconditionally because the docs content collection reads straight from the knowledge repo via Astro's glob loader, which is independent of the Starlight integration. DOCS_ENABLED=false skips the Starlight integration (so /knowledge/* routes aren't built), but the content collection — and therefore the board's getCollection('docs', type==='task') — still resolves against the KB on disk. So the board has its data even when the reading routes don't exist. (This is reasoned from how Astro content collections relate to integrations; it was not confirmed by a production-style build this session — see Verification.)

3. The board's deep links into individual atoms in landing-only prod — fix now vs. accept the 404.

  • (a) Make the deep links resolve (e.g. build a minimal atom route, or hide the links) before shipping. Not done.
  • (b) Accept the 404 as a known, explicitly-accepted trade-off (chosen, accepted by the user). A card's href, dependency links, and the modal's "Open the atom ↗" point at /knowledge/… routes that are not built in landing-only prod, so they 404. Accepted because the exposure is narrow: with JS on (the common path) a card click opens the read-only quick-look modal and never navigates, so the 404 only affects (i) the modal's "Open the atom" button and (ii) the no-JS click-through.

Decision

Decouple the read-only agentic board from DOCS_ENABLED: ship /board publicly in production while the OKF knowledge READING surface (/knowledge/*) stays gated dark. vercel.json is unchanged — DOCS_ENABLED stays false; the board is simply no longer coupled to it. Three edits to packages/site/src/pages/board.astro:

  1. Load task atoms unconditionally. The if (docsEnabled) guard around getCollection('docs', type === 'task') is removed. This works in a landing-only prod build because the docs content collection reads the knowledge repo via Astro's glob loader, independent of the Starlight integration — so the board has its data even though the integration (and the /knowledge/* routes) isn't built. A missing/empty KB still degrades to the honest empty state (the try/catch → tasks = [] path).
  2. Remove the !docsEnabled teaser branch. The "board is part of the docs surface" teaser is gone; the page now falls through to the real board (or the honest empty state if a KB has no tasks).
  3. Narrow docsEnabled's remaining role to gate links INTO the reading surface only — the "Docs" nav link and the "Browse the knowledge base" CTA. It no longer governs whether the board renders.

The accepted trade-off is recorded as part of the decision: deep links from the board into an individual atom (card href, dependency links, the modal's "Open the atom ↗") point at /knowledge/… routes that 404 in landing-only prod. Mitigated by the JS-on modal path that never navigates.

This refines Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own — it splits that decision's single "hold the docs/KB surface back" gate into two independently-gated surfaces (board: public; KB reading: dark). It does not supersede DEC-0022: the KB reading surface stays gated exactly as DEC-0022 set it, vercel.json is untouched, and flipping DOCS_ENABLED on in production remains the reversible re-entry for the reading surface.

Rationale

Consequences

Review

Promote toward verified once a production-style DOCS_ENABLED=false build has been run and confirmed: /board builds and renders its task atoms with DOCS_ENABLED=false, and /knowledge/* is absent — empirically closing the "asserted, not build-verified" gap. Re-examine the accepted 404 trade-off when the KB reading surface is readied for public exposure (flipping DOCS_ENABLED on — the Ship the landing publicly behind a docs-gate flag, capture demand through two honest doors, into a list we own re-entry — makes the deep links resolve and retires the trade-off). The source-comment cleanup (correct "DEC-0021" → DEC-0022 and add DEC-0035 in board.astro) is done (2026-06-16).