OpenHaven — Open Protocol Navigator

A live, data-driven convergence navigator for the P2P / decentralized-web ecosystem. Users navigate Use Cases → Affordances → Tools to find the protocols and platforms for a given need, with governance model and capture risk surfaced alongside technical capability. Astro 5

• React 19 + Tailwind 4, deployed at https://openhaven.net.

This repository is both the website and the BMAD planning workspace that produces it:

Path	What
src/, public/, astro.config.mjs, Dockerfile, nginx.conf	The website (built to dist/, served by nginx)
_bmad/	BMAD method install (stock modules gitignored; only customizations tracked)
_bmad-output/	PRD, architecture, epics, stories, tech specs — the source of truth for work
scripts/, research/	The protocol-data pipeline and its source spreadsheet
collaboration/	Team conventions + skills (the Linear ↔ BMAD workflow)
docs/	Project + methodology docs

Quick start (website)

bun install        # install deps
bun run dev        # dev server
bun run build      # static build → dist/
bun run preview    # preview the build

Setup / onboarding (new contributors)

You need access to this Forgejo repo (log in via Authentik) and your own Linear connection.

# 1. Clone
git clone https://git.myceli.al/openhaven/openhaven.net.git
cd openhaven.net

# 2. Website deps (only if you'll run/build the site)
bun install                 # or: npm install

# 3. Regenerate the stock BMAD modules (gitignored — only customizations are tracked).
#    Install the same modules as the workspace, and recompile agents when prompted
#    so the tracked customizations apply.
npx bmad-method install     # BMAD v6.0.3 · modules: core, bmm, cis, bmb

# 4. Load the shared collaboration skills into your agent
mkdir -p .claude/skills && cp -R collaboration/skills/* .claude/skills/

# 5. Connect your OWN Linear MCP (workspace OpenHaven · team key OPE).
#    See collaboration/README.md → Setup §1.

Then point your AI agent at CLAUDE.md first — it carries the session protocol (AWAKEN), the BMAD ↔ Linear source-of-truth rules, and the Design Audit checklist.

How we work: BMAD (_bmad-output/) is the source of truth for user stories; Linear (team OPE) is the live status board. An item created in Linear isn't dev-ready until its BMAD story exists. Full conventions: collaboration/ (README.md + the linear-bmad / linear-bmad-merge skills).

Data pipeline

The protocol matrix is authored in a single-writer source spreadsheet and compiled to JSON. Full technical reference: docs/data-pipeline.md. Process/review rules: docs/governance.md.

• Source: research/protocols/OpenHaven for P2P Convergence - Master.xlsx (binary; data authority @Enli10ment — see CODEOWNERS). On conflict, the data authority reconciles it in a spreadsheet app, then re-runs the pipeline.
• Routine changes: scripts/pipeline-op.py — the primary interface for adding, removing, or editing entities/attributes. 5 of its 7 modes default to a dry run (--apply to write); sync-check is always read-only, and full-regen is gated by a typed confirmation phrase instead. Every write mode runs a sync-check preflight first, which can block the write outright on structural source-file problems (--force overrides, not recommended). Every use requires its own BMAD story and Linear issue, per docs/governance.md.
• Full re-generation: scripts/convert-xlsx.py (xlsx → JSON) is the rare, loudly-gated exception, not the default — it re-extracts everything from the spreadsheet and requires typing a confirmation phrase. scripts/enrichment_data.py supplies its fallback/enrichment data, and scripts/audit_xlsx_vs_json.py — wrapped by pipeline-op.py sync-check — is the read-only drift check described above. On macOS, use the Xcode Command Line Tools python3 (not Homebrew) for openpyxl compatibility.
• Output: src/data/*.json (protocols, affordances, domains, entity-types, attributes, narrative …), validated against src/lib/schemas.ts and consumed by the Astro site.

Edit narrative copy directly in src/data/narrative.json; edit matrix data via pipeline-op.py/the spreadsheet + pipeline, not the generated JSON.

Deployment

The site is a static Astro build served by nginx — the Dockerfile builds the Astro output and serves /dist via nginx.conf — deployed to self-hosted infrastructure. Only src/ is built; the BMAD folders are never bundled or served.

⚠️ The legacy .github/workflows/deploy.yml targets GitHub Pages and is inert on Forgejo — it's a leftover from the GitHub era and does not deploy here. Replace it with a Forgejo Actions workflow (or remove it) when convenient.

Project structure

openhaven.net/                 # one repo: website + BMAD workspace
├── src/                       # Astro site (pages, components, data, lib, styles)
├── public/                    # static assets
├── astro.config.mjs
├── Dockerfile, nginx.conf     # build + serve
├── _bmad/                     # BMAD method (stock gitignored; customizations tracked)
├── _bmad-output/              # PRD, architecture, epics, stories, specs  ← work source of truth
├── scripts/                   # xlsx → JSON data pipeline
├── research/                  # protocol source spreadsheet + governance research
├── collaboration/             # team conventions + Linear↔BMAD skills
├── docs/                      # project + methodology docs
└── CLAUDE.md                  # session protocol + working rules