Skip to content

00 — Context

Problem statement

Adventive's engineering plans, runbooks, and SOPs live as Markdown + WeasyPrint PDFs in ~/Documents/Claude/Projects/Adventive Engineering/ on Jeffrey's laptop. Colleagues cannot read this material without being sent the PDFs ad hoc, and the source Markdown — which is the actual canonical form — is invisible to them. There's no search, no cross-linking, no per-page commenting, and no way to point a contractor at "the runbook for X" without an email attachment.

Business motivation

  • Onboarding cost: new platform engineers can't self-serve answers. Every "how do we deploy a Worker" question round-trips through Jeffrey.
  • Source-of-truth drift: PDFs get emailed, edited locally, re-shared. The Markdown in this folder is the truth, and it should be what people read.
  • Plays well with the rest of the stack: the Admin Dashboard project is already standardizing on Cloudflare Pages + Cloudflare Access for operator UIs. A docs site on the same pattern is one more reason to keep that path well-paved.
  • No ongoing cost: Cloudflare Pages and Access (under existing Zero Trust seats) absorb this with effectively no marginal cost.

Scope

  • In scope:
  • Static site rendered from this folder's Markdown
  • Search across all projects and platform standards
  • Navigation that mirrors projects/ and platform/ structure
  • Cloudflare Access gate bound to JumpCloud (engineering-docs-readers group)
  • Auto-deploy on push to main

  • PDFs remain downloadable from the project page where they live

  • Out of scope:

  • Authoring in the browser (source remains local Markdown)
  • Per-page comments (defer; revisit if the team adopts the site)
  • Generating PDFs from the site (PDFs continue to be built locally with WeasyPrint per the house style)

  • Versioned doc history beyond what git provides

  • Deferred:

  • Multi-language support
  • Public (non-Access) sections — start fully gated; carve out exceptions if asked

Success criteria

  1. A signed-in Adventive engineer can open https://docs.adventive.dev, browse to any project's runbook, and download the PDF — all without involving Jeffrey.
  2. New documents added under projects/ or platform/ appear on the site within 5 minutes of merge to main.
  3. Search returns relevant results across all Markdown files.
  4. Access policy denies anyone outside the Adventive engineering group, verified by an unauthorized test.

Stakeholders

Role Name Interest
Owner Jeffrey Lambert Architecture, hosting, content curation
Approver Jeffrey + Patrick Sign off on Access policy and content classification
Consulted Engineering colleagues (TBD) Confirm navigation matches their mental model
Informed Anyone with Cloudflare Access to the Adventive tenant They become readers