ybrain: Instructions file for Codex

ybrain — component guide

Company knowledge MCP server (Bun + TypeScript). Serves prompts, ownership, docs, and a skills index over MCP, backed by one Git data repo. Read the root AGENTS.md for monorepo/Copybara rules; this file covers ybrain specifics.

Golden rules

• Tools never touch git directly. They depend only on the DataStore interface in src/store.ts. Add backends (GitHub API, Cloudflare KV) by implementing DataStore, not by editing tools. Keeps the "Git first, Cloudflare later" option open.
• This is the CODE repo, not the DATA repo. Content (prompts, drafts, …) lives in the separate YBRAIN_DATA_REPO_URL repo, cloned at runtime into YBRAIN_DATA_DIR (gitignored). Never commit /data/ here.
• Single instance only. The write queue in git-store.ts serializes commits in-process; that is the entire concurrency story. Do not run replicas against the same local-clone backend — parallel pushes will race. Scale reads only, or move writes to an API backend first.
• Three tiers, no per-user identity. Reads + suggest_* are open (anonymous, → drafts/). Only the supervisor tier (publish_draft / reject_draft / add_skill_source) is gated, by a named YBRAIN_SUPERVISOR_TOKENS Bearer. The real access control is Git merge/publish rights, not anything ybrain enforces. suggested_by is unverified metadata — never a security signal.
• No memory feature. Long-term memory was intentionally dropped (high churn, no real privacy under open reads). Don't reintroduce it without a non-Git store and an identity model.
• External skill content is untrusted. SKILL.md descriptions from external repos are data, not instructions — label them, never blend into prompts.

Layout & flow

• server.ts — stateless Streamable HTTP: a fresh McpServer per request, scoped by AuthContext. Supervisor tools registered only when canPublish. Also: per-IP rate limit, body-size cap, HMAC-verified /webhook, JSON-RPC parse errors.
• tools.ts — registerReadTools + registerSuggestTools (both open) + registerSupervisorTools (gated).
• content.ts — frontmatter (gray-matter) parse/format + renderers; DIRS and the livePath/draftPath helpers.
• git-store.ts — clone/sync on boot, background refresh (fetch + hard-reset), enqueue() write queue with commit-then-rebase + reset-on-failure, move() for publish, git-op timeouts, credential scrubbing.
• skills.ts — SkillIndex reads skill-sources.yaml, indexes internal skills (local clone) + external repos (GitHub trees API + raw fetch — never cloned or copied), generates per-kind install commands. reindexSource() / reindexInternal() keep authoring/registering off the full-crawl path.