Skip to content

ADR — The Adventive Engineering folder is the docs repo

  • Date: 2026-04-27
  • Status: Accepted (Amended 2026-04-27)
  • Project: engineering-docs-site

Decision

The existing ~/Documents/Claude/Projects/Adventive Engineering/ folder will be converted into the adventive/adventive-engineering-docs GitHub repository. There is no separate "source" and "site" repo; the folder we author plans in IS the docs repo. mkdocs.yml lives at the root of this folder.

All authored content (READMEs, project plans, runbooks, ADRs, PDFs, the _archive/_shared/_templates scaffolding) lives under a single docs/ subdirectory inside the repo. Build/config files (mkdocs.yml, requirements.txt, .gitignore, .github/, overrides/) live at the repo root.

Context

Two strategies were on the table:

  1. Convert this folder into the docs repo (single source of truth, zero drift).
  2. Keep this folder under Cowork and create a sibling repo at ~/Repositories/GitHub/Adventive/adventive-engineering-docs/, then sync (symlink, rsync, or manual copy).

The sibling-repo approach has a guaranteed drift problem: every time content is authored here, a sync step has to run before changes are visible on the site. Symlinks don't survive Cloudflare Pages' git checkout. Rsync is a manual step that will be skipped. Manual copy is worst of all.

Consequences

Positive:

  • One source of truth. The thing you read in your editor is the thing the site renders.
  • Git history captures the same edits that produce the PDFs and the published pages.
  • PR previews on Cloudflare Pages just work — no sync infrastructure to maintain.
  • The "convert when needed" path is a one-time git init + remote add; no repo migration later.

Negative / accepted trade-offs:

  • The folder grows a .git/ directory, .github/ workflows, mkdocs.yml, requirements.txt, etc. These are tolerable additions and are excluded from the published site by mkdocs.yml.
  • Cowork and Claude Code now share the same git repo — we keep the convention that Cowork edits Markdown and PDFs, Claude Code edits code (in separate repos), and the engineering-docs-site is the one place where Cowork edits committed-to-git Markdown directly.

Implementation

Performed (or to be performed) by Jeffrey:

cd ~/Documents/Claude/Projects/Adventive\ Engineering/
git init
git add -A
git commit -m "Initial commit — restructured 2026-04-27"
gh repo create adventive/adventive-engineering-docs --private --source=. --push

Cloudflare Pages then connects to the repo as documented in 02-code-updates.md.

Amendment — 2026-04-27 (post-verification)

Running mkdocs build --strict revealed that MkDocs 1.6 forbids docs_dir: . (the validator rejects "the parent directory of the config file" being used as docs_dir). The original wording of this ADR — "no separate docs/ directory, no symlinks, no rsync" — closed off the three escape hatches MkDocs leaves open.

Resolution adopted: content lives under a single docs/ subdirectory inside the repo. Build/config files (mkdocs.yml, requirements.txt, .gitignore, .github/, overrides/) stay at the repo root.

The original ADR's intent — single source of truth, no copy/sync between two parallel structures — is preserved. There is still exactly one place content lives, and Git history is on the same files MkDocs renders. The amendment only adds one folder level. Other rejected options (sibling repo, symlinks, rsync staging, switching generator) all carried larger costs than this layout adjustment.

mkdocs.yml now sets docs_dir: docs. The repo layout becomes:

adventive-engineering-docs/
├─ mkdocs.yml
├─ requirements.txt
├─ .gitignore
├─ .github/workflows/build.yml
├─ overrides/                # Material theme partials (custom_dir target)
└─ docs/                     # ← docs_dir
   ├─ README.md              # site landing page
   ├─ assets/extra.css       # site CSS (must live inside docs_dir)
   ├─ projects/
   ├─ platform/
   ├─ _archive/              # excluded from rendered site
   ├─ _shared/               # excluded from rendered site
   └─ _templates/            # excluded from rendered site

A thin top-level README.md (separate from the site landing page) describes the repo and its build steps for GitHub repo browser visitors.