Ourobor OS: Project Wiki

This is the internal documentation for the Ourobor OS project. It also serves as a reference example for users of the skill — this is what a populated ouro/wiki/ looks like in practice.

The distributable skill package lives in ouro/. This wiki/ directory documents the Ourobor OS project itself and mirrors the structure users receive when they run bootstrap.py. See ADR-002.

Core Documentation

• schema.md — Doxygen tag reference (@entity, @brief, @snippet, etc.) and maintenance protocols (capture → synthesize → pop → index).

Entities

• capture.py — Stages files/text into the capture queue; --crawl --git stages only git-changed files (recommended for ongoing sessions); --crawl walks a directory (initial setup); --pop removes the first entry for LLM synthesis.
• bootstrap.py — One-time init: detects LLM environment (Claude, Cursor, Aider, Continue), creates ouro/wiki/ tree, appends maintenance protocol to instruction files. Idempotent.
• builder.py — Converts wiki/*.md → ouro-webui/dist/*.html; processes Doxygen tags via regex, renders Markdown with mistune, generates grouped sidebar. Not part of the distributed skill.
• package.py — Validates ouro/ structure then zips it to dist/ouro-skill.zip. Aborts if required files/dirs are missing. Root-level only, not in the distributed skill.

Architecture Decisions

• ADR-001 — ouro/wiki/ subdirs stay empty (.gitkeep only); project docs must not ship to users at install time.
• ADR-002 — Root wiki/ doubles as internal docs and a populated reference example; one directory, two jobs.
• ADR-003 — Inline Doxygen-style tags in plain Markdown (not real Doxygen); readable in any viewer, provides a rendering hook for builder.py.
• ADR-004 — Web UI excluded from the skill package; core skill stays pure stdlib + Markdown, web UI evolves independently.
• ADR-005 — --crawl is secure-by-default: skips ~50 credential dirs, exact sensitive filenames, and dangerous extensions. Edit constants in capture.py to tune.
• ADR-006 — Sidebar sections with >20 links use <details>/<summary>; active section auto-opens via inline script.
• ADR-007 — --crawl --git limits staging to git-changed files; full --crawl reserved for initial wiki population.

Patterns

• Capture-Synthesize Loop — The core workflow: raw code/notes → capture queue → LLM synthesizes into entities/patterns/decisions → --pop clears entry → index.md updated.

Maps

• System Architecture — Full directory tree, data flow diagram, and separation-of-concerns table (what ships vs. what doesn't).
• Project Roadmap — Phase 1 (core) and Phase 2 (web UI) both complete; verification criteria met.

Capture Queue

• capture-queue.md