Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Architectural Precedents
Titles index for the architectural precedents that Open Knowledge code cites as precedent #N. Numbers are a stability contract: a slot is never renumbered and never reused, so a citation resolves to the same rule for as long as the code carries it. A rule that was withdrawn keeps its slot and is marked below.
61 numbered slots, 58 active, 3 retracted.
Convention & discipline (precedents 1–8)
- Typed transaction origins.
- Generic primitives over specific ones.
- Structured event schemas.
- Shared computation, per-surface rendering.
- Contract-first MCP tools.
- Mode state as enums.
- Remove broken capabilities rather than shipping them.
- Separate long-lived identity from short-lived session concerns.
CRDT bridge & schema (precedents 9–14, 28, 38)
- Schema is add-only forever.
- Opaque-but-content-bearing nodes for Y.Item identity.
- Minimize CRDT mutation in sync bridges.
- [RETRACTED — superseded by precedent #38 (Y.Text-is-truth contract).]
- Bridge invariants are auto-enforced and property-verified.
- Cross-CRDT sync is single-writer, server-side.
- Direct PM dispatch for nested editors.
- Y.Text-is-truth contract: Y.Text holds user-intended source-form bytes; XmlFragment derives via
parse(ytext).
Markdown pipeline (precedents 15–17)
- Idempotent micromark-extension attachers.
- Phase-ordered visitor dispatchers when passes consume each other's output.
- Byte-for-byte equivalence validators gate high-risk refactors.
UI / React patterns (precedents 18, 19, 21, 29, 30)
- Hybrid Activity + Suspense +
use(promise)for subscription-source async primitives. - Clipboard pipeline is mdast-canonical with per-view hook mechanisms.
- Ancestor-priority for auto-revealing tree-state derivations.
- Compound components use DOM data-attributes to bridge across NodeView portal boundaries. RETRACTED.
- All user content visible and editable (no hidden content).
Testing, tooling, infra (precedents 20, 22, 23)
- E2E test infrastructure conventions.
- Shell-script conventions for repo tooling.
- Async socket errors on closing sockets are caught at the boundary, not pre-filtered in userspace.
Actor identity & attribution (precedents 24, 25)
- Per-session actor identity at the CRDT origin layer.
- Classified writer IDs + subject-prefix action encoding in the shadow repo.
Perf + V2 editor architecture (precedents 26–27)
- Perf instrumentation as first-class.
- V2 editor cache + InteractionLayer + Option E split walker (2026-04-20) + cv-auto block-chunked render (2026-04-30).
Selection & chrome architecture (precedents 31–37)
- Selection state as typed PM PluginState.
data-*attributes over className toggling for composable states in React-rendered NodeViews.- CSS custom-property tokens scoped via
[data-component-type]for per-block-type theming. - Innermost-wins visible chrome, ancestor propagation via state (not
:has()). - Floating UI is the canonical positioning primitive for selection-anchored overlays.
- A11y codified in the selection plugin, not retrofitted per-block.
- Asset-click dispatch is a single shared surface.
API surface discipline (precedent 39)
- HTTP
/apiroutes emit RFC 9457 problem details on errors and a flat success body keyed by HTTP status.
Cross-process state mirroring (precedent 40)
- Renderer-state↔main-state propagation: typed-IPC push + show-gate dual-signal + build-time token resolution for cross-process value sharing.
Connection-admission stacking (precedent 41)
- Connection-admission policies stack via
hocuspocus.configuration.extensions.push()after identity threading; admission decisions that depend on a recently-removed cache consult the cache FIRST and use the on-disk file as a disambiguator only when the cache has an entry.
Custom lint enforcement (precedent 42)
- Custom lint enforcement is oxlint JS-plugin rules.
Tier-3 React-runtime test substrate (precedent 43)
- Tier-3 React-runtime tests (RTL mount under jsdom 29) run in a dedicated Vitest project (
packages/app/vitest.dom.config.ts) with per-projectsetupFiles— never a global preload.
Editor DOM-tree exclusivity + delete-then-recreate coordination (precedent 44)
- TipTap
view.domDOM-tree exclusivity is a load-bearing OK invariant —<EditorContent>MUST render viaReact.createPortalto a per-Activity exclusively-owned DOM target; parked-state cache entries MUST own per-entry parking nodes; clientcloseAndClearPersistenceand concurrentpool.openMUST coordinate viapendingClears; server-sideshouldUnloadDocumentMUST honorforceUnloadunconditionally.
JSX selection UX corrections (precedents 45–48)
--selection-halo-insetis uniform across substrates; per-substrate inset overrides are precluded.- Customer-facing JSX descriptors with required string props key off key-absence, not empty-string, to surface the missing-decision state.
- Test-file substrate vocabulary is structurally checked against the registry via a meta-test.
- Block-level keyboard contract is structural, not mode-based;
KeyboardNavis the canonical home.
Electron host chrome safe area (precedent 49)
- In-window full-viewport overlays must reserve the macOS traffic-light footprint via
--ok-titlebar-reserve-left.
Project locality for LLM-functional resources (precedents 50, 51)
- Project locality for LLM-functional + reproducibility-sensitive resources.
- Every overlay primitive carries a one-line
motion-reduce:opt-in inline on its Content (and SubContent where present) — the only OK divergence from shadcnradix-novaupstream motion across the original 7 Radix overlay primitives (Dialog, Sheet, Popover, Select, Dropdown-menu, Context-menu, Tooltip).
Two-tier overlay-motion system — documented forks of the radix-nova preset (precedent 52 — RETRACTED)
- The 7 overlay primitives in the design system are organized into a two-tier motion system: a snappy tier (100ms transition-based enter / 0ms exit) for the 5 high-frequency primitives (Popover, Select, Dropdown-menu, Context-menu, Tooltip) — implemented as documented forks of the radix-nova shadcn preset's animation utilities — and a standard tier (200ms enter / 150ms exit) for the 2 low-frequency primitives (Dialog, Sheet), with Dialog additionally exposing a typed two-tier
transition?: 'standard' | 'snappy'prop on DialogOverlay + DialogContent so the palette can opt into the snappy tier without forking the modal class set. RETRACTED.
Category-aware overlay placement — generic dialogs center, command/search palettes top-anchor (precedent 53)
Overlay placement is category-aware, expressed via an inline className on the palette-category primitive (CommandDialog) — mirroring shadcn radix-nova upstream's own pattern.
Structural lifecycle gates on mutating write spines (precedent 54)
- Lifecycle-state refusal on mutating write spines is structural, expressed via a single typed-throw class + a single HTTP-response helper + a meta-test that scans every mutating route.
Content scope predicate symmetry (precedent 55)
ContentFilteris the single source of truth for whether a path is in OK content scope; walkers may not augment it with local admission rules.
Canonical link contract (precedent 56)
- OK has two valid internal-link forms — relative (
./sibling.md,../folder/doc.md) and root-absolute (/folder/doc.md, leading slash = content root) — and the substrate VALIDATES every outbound link at write time so a broken hybrid never ships silently.
Per-write-path fidelity bar (precedent 57)
- Every write surface declares its fidelity bar at the intake layer — byte-sacred or construct-canonical — never inside the serializer.
One-transaction menu insertions (precedent 58)
- A menu that deletes its trigger range and then inserts content MUST land both in one transaction; the menu item contributes steps, never a dispatch of its own.
Project scoping for renderer storage names (precedent 59)
- Every client-side persistent storage name whose collision domain is the ORIGIN must be scoped to the project through
scopedStorageKey(packages/app/src/lib/storage-scope.ts), or explicitly justify itself as app-global.
Native-handoff transport carries path and prompt only (precedent 60)
- A native-handoff deep link carries a folder or workspace path plus a short directive prompt — never a
file=attach param and never whole-doc bytes; the receiving agent grounds by reading the doc through the OpenKnowledge MCP server.
JSX prop renames (precedent 61)
- Rename a JSX prop by listing its old spelling in the new prop's
legacyNames; old spellings stay readable.