# vibe/ — Arcodange Knowledge Base

You-are-here: the **root** of the `vibe/` knowledge tree — the front door for every doc agents write and read.
Up: [factory](../README.md) / [AGENTS.md](../AGENTS.md)

> **Status:** Active
> **Last Updated:** 2026-06-23

## What is `vibe/`?

`vibe/` is the knowledge base dedicated to **LLM agents** working on the Arcodange lab. It collects the *why* (ADRs), the *what/when* (PRDs), the *what-we-found* (investigations), the *how-it-fits-together* (guidebooks), the *how-to-do-it* (runbooks), and the *what-we-told-humans* (shareouts). Everything here is written in **English** — the single exception is **shareouts handouts, which are FRENCH**. Operating rules (no-tombstone, mermaid prefs, tree-docs, ADR/PRD/investigation conventions, PR crosslinking, language policy) are defined authoritatively in [AGENTS.md](../AGENTS.md); this page summarizes them and points there.

## Folder map

| Folder | When to use it | Status |
|---|---|---|
| [ADR](ADR/README.md) | Recording an architecture **decision** (MADR-lite; body immutable once Accepted). Canonical home going forward. | ⬜ |
| [PRD](PRD/README.md) | Specifying a **product/project**: Problem → … → QA strategy → `STATUS.md` (mandatory, kept current). | ⬜ |
| [investigations](investigations/README.md) | Capturing a **finding/analysis** — single `INV-NNN-slug.md`, or stub + notebooks when data-heavy. | ⬜ |
| [guidebooks](guidebooks/README.md) | Mapping a **component or the ecosystem** as navigable tree-docs (the lab cartography). | ⬜ |
| [runbooks](runbooks/README.md) | Documenting an **operational procedure** step-by-step with `[AGENT]` / `[HUMAN]` markers. | ⬜ |
| [shareouts](shareouts/README.md) | Producing **handouts/presentations** for humans (FRENCH). | ⬜ |

Status legend: ✅ done · 🟡 beta · 🔴 critical · ⚠️ known issue · ❌ disabled · ⬜ not started.

## Conventions at a glance

- **No-tombstone rule (foremost)** — write each file as currently true; never leave "previously X, now Y", changelogs, or "updated to …" notes. Git history is the audit trail. Only exception: a forward-looking `> [!CAUTION]` about a live risk.
- **Breadcrumb spine** — every non-root file starts with a breadcrumb: ancestors as relative links, current page bold-unlinked, separator ` > `. This root has no breadcrumb (it uses the you-are-here + up-link above instead).
- **README hub per folder** — each folder's `README.md` is an index table of its children (link + one-line summary + status), sorted by importance/sequence.
- **Bidirectional links** — if A references B as related, B references A. Use descriptive link text (never "here"/"this").
- **Mermaid prefs** — `theme base`/`forest` init directive; legible `classDef` palette (dark fills + light text); `<br>` not `\n`; leading space before slash-labels; validate with the Mermaid MCP; **a numbered ordered list restating the flow after every diagram**.
- **GitHub alert legend** — `[!NOTE]` info/forward-looking · `[!TIP]` aside · `[!IMPORTANT]` inherent constraint · `[!WARNING]` degraded-but-working · `[!CAUTION]` data-loss/breaking.
- **Status emoji legend** — ✅ done · 🟡 beta · 🔴 critical · ⚠️ known issue · ❌ disabled · ⬜ not started.
- **Language policy** — English throughout `vibe/`; FRENCH only for shareouts handouts.

Authority for all of the above: [AGENTS.md](../AGENTS.md).

## Maintenance policy

- **Adding a page** → also add its row to the parent folder's `README.md` index table.
- **Keep links bidirectional** → when you link A→B, add B→A.
- **Stamp `Last Updated:`** at each tree root (this file and every guidebook/big-PRD root) after any structural change.
- **Never tombstone** → edit content in place; let git carry the history.
- **Guidebook coupling** → changing a documented component means updating its guidebook page in the same change.
- **PR crosslinks** → every PR references the ADR/PRD it advances; that ADR's References and the PRD's `STATUS.md` link back.

## Cohort + workflow (recap)

Docs here are produced by a cohort of persona subagents — Lab Cartographer, ADR Scribe, PRD Architect, Runbook Engineer, Investigator, Diagram Smith, Continuity Warden — spawned via the Agent tool or a Workflow. The recommended pipeline for substantial contributions is **Scaffold → Author → Validate → Review → Assemble**. Full descriptions and responsibilities live in [AGENTS.md](../AGENTS.md).