Skip to content
Ark

RFC 0001 — Docsite infrastructure

  • Status: Accepted (2026-05-26)
  • Date: 2026-05-26
  • Author: j + Claude
  • Tracking: PLAN.md §9 (versioning→changelog flow), §10 (docsite + gate), §14 Phases 3–4

Decisions confirmed (2026-05-26): D1 → split layout (docs/ authored + apps/docs/ Starlight app). D2 → Cut 1 is local build + moon/CI only; Cloudflare Pages + Access gate deferred to Cut 2. D3 → scaffold docs/rfcs/, docs/adr/, docs/CONTEXT.md now.

Summary

Section titled “Summary”

Stand up the Ark docsite: an Astro Starlight static site that aggregates the repo’s authored docs (PLAN, extraction map, releasing reference, per-app architecture) and per-package CHANGELOG.mds into one searchable portfolio, deployed to Cloudflare Pages behind a Zero-Trust Access gate (email ends with @7hoenix.com).

This RFC also establishes the home for the RFC/ADR habit and CONTEXT.md — the process we just adopted (“write + review an RFC before significant work”). The docsite is the first dogfood of that process.

Motivation

Section titled “Motivation”
  • jg is now stood up end-to-end (CI, tests, TestFlight, versioning). The docs that describe it (PLAN.md, apps/jg/docs/**, releasing.md, CHANGELOG.md) are scattered and read-only-in-git. A single rendered, searchable site makes the monorepo navigable for both of us and for agents.
  • The versioning flow (Knope → per-package CHANGELOG.md) was built to feed a docsite (PLAN.md §9.4). Nothing renders those changelogs yet.
  • The new RFC/ADR habit needs an obvious, low-friction home so it actually gets used.

Decisions (the forks worth reviewing)

Section titled “Decisions (the forks worth reviewing)”

D1 — Where the site lives → apps/docs workspace, authored docs stay in docs/

Section titled “D1 — Where the site lives → apps/docs workspace, authored docs stay in docs/”

PLAN.md §4 literally says “docs/ = Astro Starlight.” I propose a small refinement that keeps the spirit but separates authored source from the rendering app:

  • docs/ (root) = human/agent-authored markdown, the source of truth: docs/rfcs/, docs/adr/, docs/CONTEXT.md, docs/extraction-map.md, plus shared architecture/reference prose. This is where you write. Plain markdown, no build step.
  • apps/docs/ = the Starlight site (a normal bun/moon app workspace). It ingests docs/** and every CHANGELOG.md via Starlight content loaders and renders + deploys them.

Why split rather than make docs/ itself the Astro project:

  • apps/docs drops cleanly into the existing apps/* moon + bun-workspace globs and gets normal build/dev tasks + affected-graph + cache — identical shape to jg/trained.
  • The RFC habit’s home (docs/rfcs/) stays a dead-simple markdown dir, not buried under apps/docs/src/content/docs/rfcs/. Authored docs don’t carry Astro project cruft.
  • The site becomes a pure build artifact (nothing authored lives only inside it).

Trade-off: Starlight content then loads from outside its own src/ (via a glob() content loader pointed at ../../docs and the package changelogs). Supported, but slightly more config than the default src/content/docs/ layout.

(Alternative kept on record: docs/ IS the Astro project, authored docs live under docs/src/content/docs/. Simpler to scaffold, matches PLAN.md verbatim, but couples authoring with the build and makes apps/*/moon integration less uniform.)

D2 — First-cut scope → build + ingest + moon/CI locally; defer Cloudflare to a second cut

Section titled “D2 — First-cut scope → build + ingest + moon/CI locally; defer Cloudflare to a second cut”
  • Cut 1 (this RFC): scaffold apps/docs, wire content ingestion (docs/** + CHANGELOGs), define nav, moon build/dev tasks, build runs in CI (catches broken site + dead internal links). No deploy yet — verify locally with bun run dev/build.
  • Cut 2 (follow-up, PLAN Phase 4): Cloudflare Pages deploy (wrangler pages deploy, consistent with the existing worker-deploy pattern; reuses CLOUDFLARE_API_TOKEN) + Zero-Trust Access policy @7hoenix.com. Outward-facing → confirmed separately before firing.

Rationale: get the rendering + ingestion right and reviewable first; the gate is an independent, mostly-dashboard step that shouldn’t block content work. “Take it slow.”

D3 — RFC/ADR/CONTEXT scaffolding → create the empty scaffolding now, as part of this cut

Section titled “D3 — RFC/ADR/CONTEXT scaffolding → create the empty scaffolding now, as part of this cut”

The docsite needs sections to render and the habit needs a home, so Cut 1 also lands:

  • docs/rfcs/ (this file is 0001) + a short docs/rfcs/0000-template.md.
  • docs/adr/0000-template.md (Nygard-style) — the improve-codebase-architecture skill reads docs/adr/.
  • docs/CONTEXT.md seeded with the domain language we already have (Ark, jg/trained, golden path, packages, the two tag schemes, scopes convention). Filling it out richly stays a follow-up, but the file + skeleton land now.

Proposed structure & nav

Section titled “Proposed structure & nav”
docs/                         # authored source (markdown)
├── CONTEXT.md                # domain language (seeded)
├── extraction-map.md         # (exists)
├── rfcs/0000-template.md, 0001-docsite.md
└── adr/0000-template.md
apps/docs/                    # Starlight site (build artifact)
├── package.json              # astro + @astrojs/starlight
├── astro.config.mjs          # content loaders → ../../docs + **/CHANGELOG.md
├── moon.yml                  # build (CI) / dev (runInCI:false)
└── src/ (config, styles)

Initial sidebar:

  • Overview — PLAN.md, CONTEXT.md
  • Architecture — apps/jg/docs/architecture/**, extraction-map
  • Reference — releasing.md, system-overview
  • Changelog — per-package CHANGELOG.md (jg today; grows automatically)
  • RFCs — docs/rfcs/**
  • ADRs — docs/adr/**

Integration details

Section titled “Integration details”
  • bun: apps/docs is already covered by the apps/* workspace glob; bun install at root picks up astro/starlight.
  • moon: apps/docs/moon.yml, layer: application, toolchain: system. Tasks: build (bun run build → outputs dist/, runs in CI), dev (runInCI: false).
  • CI: moon ci already runs build-class tasks; the docs build joins the affected graph.
  • knope/versioning: no change. The site reads changelogs; it isn’t a versioned package (no [packages.docs]). Doc-only commits use a non-package scope (e.g. docs(...)/chore(docs):).

Out of scope (this RFC)

Section titled “Out of scope (this RFC)”
  • Cloudflare Pages deploy + Access gate (Cut 2 / PLAN Phase 4).
  • Pulling each app’s elm-book into the site (PLAN §10 mentions it; later — needs the book build wired first).
  • Rich CONTEXT.md authoring and a real first ADR (follow-up).

Open questions for review

Section titled “Open questions for review”
  1. D1 — apps/docs workspace + authored docs/ (recommended), or docs/ as the Astro project per PLAN.md verbatim?
  2. D2 — defer Cloudflare Pages + Access to Cut 2 (recommended), or include the deploy now?
  3. D3 — scaffold RFC/ADR/CONTEXT now (recommended), or split into its own RFC?
  4. Astro Starlight version/theme defaults fine, or any look/structure preferences?