@liminis/editor 0.1.0-rc.1

package/docs/decisions/adr-007.md

@@ -0,0 +1,27 @@
+# ADR-007: IPC via contextBridge API (2026-01-25)
+
+**Context:**
+- Electron security model requires isolating renderer from Node.js
+- Need to expose main process functionality to React UI
+- Want type-safe API for all IPC calls
+- Many different domains (fs, agent, chat, settings, etc.)
+
+**Decision:**
+- Use `contextBridge.exposeInMainWorld` to create `window.api`
+- Organize API by domain: `api.fs.*`, `api.agent.*`, `api.chat.*`, etc.
+- Use `ipcRenderer.invoke` for request/response
+- Use `ipcRenderer.on` for events (streaming, file changes)
+- Define TypeScript types in `window-api.d.ts`
+
+**Alternatives Considered:**
+- Enable nodeIntegration → Rejected: security risk, Electron anti-pattern
+- Single IPC channel with message types → Rejected: harder to type, less discoverable
+- GraphQL-like schema → Rejected: overkill for desktop app
+
+**Consequences:**
+- ✅ Secure by default (no Node.js in renderer)
+- ✅ Discoverable API through types
+- ✅ Clean domain separation
+- ✅ Support for both invoke (request/response) and events (streaming)
+- ❌ Verbose preload script
+- ❌ Must maintain types for both ends

package/docs/decisions/adr-010.md

@@ -0,0 +1,26 @@
+# ADR-010: Bidirectional Markdown Conversion (mdast ↔ Lexical) (2026-01-25)
+
+**Context:**
+- Source of truth is markdown files on disk
+- Editor operates on Lexical node tree
+- Need to preserve markdown formatting on round-trip
+- Support for extensions: wiki-links, frontmatter, math, GFM tables
+
+**Decision:**
+- Parse markdown to mdast (Markdown Abstract Syntax Tree) using unified/remark ecosystem
+- Convert mdast → Lexical nodes for editing (`mdastToLexical.ts`)
+- Convert Lexical nodes → mdast for saving (`lexicalToMdast.ts`)
+- Use micromark extensions for wiki-links, frontmatter, math, GFM
+
+**Alternatives Considered:**
+- Direct markdown ↔ Lexical → Rejected: mdast provides cleaner intermediate representation
+- Store Lexical JSON as source → Rejected: lose markdown portability
+- Markdown-only editing (no WYSIWYG) → Rejected: poor UX for notes app
+
+**Consequences:**
+- ✅ Markdown files remain portable
+- ✅ Clean separation of parsing/serialization from editing
+- ✅ Can add new markdown extensions via mdast plugins
+- ✅ Preserve formatting on round-trip
+- ❌ Two conversion layers add complexity
+- ❌ Some edge cases in bidirectional conversion

package/docs/decisions/adr-024.md

@@ -0,0 +1,124 @@
+# ADR-024: UI Consistency - Custom Dialogs Over Native Browser Functions (2026-01-29)
+
+**Context:**
+- PR #54 (right-click context menu for document rename/delete) required confirmation dialogs
+- Native browser functions (`window.confirm`, `window.alert`, `window.prompt`) available but have UX limitations:
+  - Non-customizable styling (doesn't match app design system)
+  - Blocks entire application (modal blocking at OS level)
+  - Can't be themed (always system default appearance)
+  - No loading states or async actions
+  - Inconsistent appearance across platforms
+- Gemini Code Assist review comment highlighted the UX inconsistency concern
+- Need architectural guidance for future development
+
+**Decision:**
+- **ALWAYS use shadcn/ui components** for all UI elements throughout the application
+- **NEVER use native browser functions** (`window.confirm`, `window.alert`, `window.prompt`)
+- **NEVER use unstyled HTML elements** directly (use shadcn/ui wrappers instead)
+- Use shadcn/ui components with consistent styling:
+  - `Dialog` + `DialogContent` for modal interactions
+  - `Button` for all clickable actions (with appropriate variants)
+  - `Input` and `Textarea` for form fields
+  - `Badge` for status indicators
+  - `ScrollArea` for custom scrollable regions
+  - `ContextMenu` for right-click interactions
+- Component patterns:
+  - `Dialog` + `DialogHeader` + `DialogTitle` + `DialogDescription` for context
+  - `DialogFooter` with `Button` components for actions
+  - Variant system: `variant="destructive"` for dangerous actions, `variant="outline"` for secondary
+  - Loading states: `disabled={isLoading}` with dynamic button text
+- Apply this pattern to ALL user interactions: dialogs, confirmations, forms, buttons, menus, etc.
+
+**Rationale:**
+- Visual consistency: All dialogs match application design system and theme
+- Better UX: Can show loading states, error messages, contextual information
+- Accessibility: Proper ARIA labels, keyboard navigation via Radix UI primitives
+- Flexibility: Can customize layout, add checkboxes ("Don't ask again"), show warnings
+- Professional appearance: Custom dialogs elevate perceived quality
+
+**Current State:**
+- ✅ PR #54 correctly implements custom Dialog for delete/rename confirmations
+- ❌ One violation: `RemarkablePanel.tsx` line 277 uses `window.confirm` for uninstall confirmation
+
+**Alternatives Considered:**
+- Allow native dialogs for "quick confirmations" → Rejected: Creates inconsistency, same effort to use Dialog component
+- Hybrid approach (custom for complex, native for simple) → Rejected: Hard to define boundary, leads to inconsistent UX
+- Only enforce for "important" actions → Rejected: All user interactions deserve consistent treatment
+
+**Consequences:**
+- ✅ Consistent, professional user experience across all interactions
+- ✅ Themeable dialogs (dark mode, custom branding)
+- ✅ Better accessibility via Radix UI primitives
+- ✅ Can show loading states and error handling inline
+- ✅ More control over layout and information hierarchy
+- ❌ Slightly more code than native `window.confirm()` (but minimal with shadcn components)
+- ❌ Need to manage dialog state (open/close, target data)
+
+**Implementation Pattern:**
+
+```tsx
+// State management
+const [confirmDialogOpen, setConfirmDialogOpen] = useState(false)
+const [confirmTarget, setConfirmTarget] = useState<DataType | null>(null)
+const [isProcessing, setIsProcessing] = useState(false)
+
+// Trigger confirmation
+const handleActionClick = (item: DataType) => {
+  setConfirmTarget(item)
+  setConfirmDialogOpen(true)
+}
+
+// Handle confirmed action
+const handleConfirm = async () => {
+  if (!confirmTarget) return
+  
+  setIsProcessing(true)
+  try {
+    await performAction(confirmTarget)
+    setConfirmDialogOpen(false)
+    // Success handling
+  } catch (error) {
+    // Error handling
+  } finally {
+    setIsProcessing(false)
+  }
+}
+
+// Dialog component
+<Dialog open={confirmDialogOpen} onOpenChange={setConfirmDialogOpen}>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Confirm Action</DialogTitle>
+      <DialogDescription>
+        Are you sure you want to perform this action?
+      </DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <Button 
+        variant="outline" 
+        onClick={() => setConfirmDialogOpen(false)}
+        disabled={isProcessing}
+      >
+        Cancel
+      </Button>
+      <Button 
+        variant="destructive" 
+        onClick={handleConfirm}
+        disabled={isProcessing}
+      >
+        {isProcessing ? 'Processing...' : 'Confirm'}
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+**Action Items:**
+- [ ] Fix `RemarkablePanel.tsx` uninstall confirmation to use Dialog component
+- [ ] Document this pattern in component library or contributing guide
+- [ ] Add ESLint rule to warn on `window.confirm`, `window.alert`, `window.prompt` usage
+
+**References:**
+- PR #54: Document rename/delete with custom dialogs (exemplar implementation)
+- Gemini Code Assist review comment on PR #54
+- shadcn/ui Dialog: https://ui.shadcn.com/docs/components/dialog

package/docs/decisions/adr-025.md

@@ -0,0 +1,103 @@
+# ADR-025: Zustand for Renderer-Side State Management (2026-01-30)
+
+**Context:**
+- PR #70 initially used `window` custom events for frontmatter UI communication between `EditorColumn` (toolbar) and `FrontmatterPlugin` (editor)
+- Pattern: `window.dispatchEvent(new CustomEvent('frontmatter:toggle'))` and `window.addEventListener('frontmatter:state', handler)`
+- This worked but had architectural issues:
+  - Global event listeners make data flow difficult to trace
+  - No type safety for event payloads
+  - Unclear relationships between components
+  - Hard to debug (events scattered across global scope)
+  - Not idiomatic React architecture
+- Code review feedback identified this as an anti-pattern to avoid
+- Both components are in the same React tree (SlashMDApp rendered as child component)
+
+**Decision:**
+- **ALWAYS use Zustand stores for renderer-side state management**
+- **NEVER use window events for React component communication**
+- Create focused stores for specific domains (e.g., `editorStore`, `navigationStore`)
+- Use Zustand's selector pattern for granular subscriptions
+- Store pattern:
+  ```typescript
+  interface EditorState {
+    // State properties
+    hasFrontmatter: boolean
+    isFrontmatterOpen: boolean
+    
+    // Actions (methods that update state)
+    setHasFrontmatter: (has: boolean) => void
+    toggleFrontmatter: () => void
+    reset: () => void
+  }
+  
+  export const useEditorStore = create<EditorState>((set, get) => ({
+    hasFrontmatter: false,
+    isFrontmatterOpen: false,
+    
+    setHasFrontmatter: (has: boolean) => set({ hasFrontmatter: has }),
+    toggleFrontmatter: () => set({ isFrontmatterOpen: !get().isFrontmatterOpen }),
+    reset: () => set({ hasFrontmatter: false, isFrontmatterOpen: false })
+  }))
+  ```
+- Component usage:
+  ```typescript
+  // Read specific state slice
+  const isOpen = useEditorStore((state) => state.isFrontmatterOpen)
+  
+  // Get action
+  const toggle = useEditorStore((state) => state.toggleFrontmatter)
+  
+  // Use in handler
+  <Button onClick={toggle}>Toggle</Button>
+  ```
+
+**When to Use Zustand:**
+- State shared between multiple React components in renderer process
+- UI state (navigation, editor modes, panel visibility)
+- Client-side derived state (selections, filters, temporary UI flags)
+- State that doesn't need to persist to disk or main process
+
+**When NOT to Use Zustand:**
+- Main process state (chat history, file system, agents) → Use IPC with reactive events (see ADR-024)
+- Form state for single component → Use `useState`
+- Transient animations/hover states → Use `useState`
+- State synchronized with main process → Use IPC invoke + IPC events
+
+**Window Events Are Still Valid For:**
+- Cross-context communication where Zustand can't reach (different window instances, web workers)
+- Integration with non-React code (legacy libraries, browser APIs)
+- NOT for React-to-React component communication
+
+**Alternatives Considered:**
+- Window custom events → Rejected: poor traceability, no type safety, not idiomatic React
+- Redux → Rejected: too much boilerplate for renderer-only state
+- React Context → Rejected: performance issues with frequent updates, prop drilling
+- Component callbacks → Rejected: tight coupling, doesn't scale
+
+**Consequences:**
+- ✅ Explicit, traceable data flow via React DevTools
+- ✅ TypeScript type safety for state and actions
+- ✅ Granular subscriptions (components only re-render when their slice changes)
+- ✅ Simple API (less boilerplate than Redux)
+- ✅ Works across component boundaries without prop drilling
+- ✅ Easy to test (store is independent of components)
+- ✅ Consistent with existing `navigationStore` pattern
+- ❌ Additional file per domain (acceptable trade-off for clarity)
+- ❌ Learning curve for Zustand patterns (minimal, simpler than Redux)
+
+**Implementation Example from PR #70:**
+- Created `editorStore.ts` for editor UI state
+- Refactored `EditorColumn.tsx` to use `useEditorStore` instead of window events
+- Refactored `FrontmatterPlugin.tsx` to update store directly instead of dispatching events
+- Removed all `window.addEventListener` and `dispatchEvent` calls
+
+**Store Organization:**
+- Location: `src/renderer/stores/`
+- Naming: `{domain}Store.ts` (e.g., `editorStore.ts`, `navigationStore.ts`)
+- One store per domain (don't create monolithic global store)
+- Keep stores focused and cohesive
+
+**References:**
+- Zustand docs: https://github.com/pmndrs/zustand
+- PR #70: Config/Agents/Skills navigation refactor
+- Existing pattern: `navigationStore.ts`

package/docs/decisions/adr-027.md

@@ -0,0 +1,66 @@
+# ADR-027: Test Framework Strategy - Vitest + Playwright (2026-02-02)
+
+**Context:**
+- Liminis has grown to ~39K LOC with zero test coverage (greenfield)
+- Complex Electron architecture: main process (IPC, file ops, Claude SDK) + renderer (React 19, Lexical editor)
+- Need comprehensive testing strategy covering unit, integration, component, and E2E tests
+- Build system uses Vite via electron-vite, package.json has `"type": "module"` (ESM)
+- React 19 requires compatible testing libraries
+- TypeScript 5.9 with strict mode throughout
+
+**Decision:**
+- Adopt **3-tier testing pyramid**: 60% unit, 25% integration, 15% E2E
+- **Vitest** for unit and integration tests:
+  - Native ESM support (matches project `"type": "module"`)
+  - Vite integration (already using Vite via electron-vite)
+  - Fast parallel execution
+  - Compatible with Testing Library ecosystem
+- **Playwright** for E2E tests:
+  - Official Electron testing recommendation
+  - Full app launch via `_electron.launch()`
+  - Video recording, multi-window support
+- **React Testing Library** for component tests:
+  - User-behavior focused testing
+  - React 19 compatible (@testing-library/react@16.x)
+  - Runs on Vitest
+- **Test structure**: Co-located tests in `__tests__/` directories, integration in `tests/`, E2E in `e2e/`
+- **Key patterns**:
+  - Extract business logic from IPC handlers for testability
+  - Mock Claude SDK to avoid real API calls
+  - Use temp directories for file system isolation
+  - Test markdown layer, not Lexical editor internals
+
+**Alternatives Considered:**
+- Jest → Rejected: Complex ESM configuration, slower than Vitest, less modern
+- Spectron → Rejected: Deprecated by Electron team in favor of Playwright
+- Cypress → Rejected: Electron support requires workarounds, Playwright is official recommendation
+- Keep no tests → Rejected: Codebase complexity demands automated testing
+
+**Consequences:**
+- ✅ Fast unit tests (<1s) for rapid iteration
+- ✅ Seamless Vite integration (no build config changes)
+- ✅ Modern testing stack (Vitest + Playwright actively maintained)
+- ✅ Type-safe tests with full TypeScript support
+- ✅ Coverage reporting via Vitest's built-in v8 provider
+- ✅ CI/CD ready (GitHub Actions examples in strategy doc)
+- ❌ Learning curve for team (but minimal - Vitest similar to Jest)
+- ❌ Need to write ~200-300 tests to reach 60% coverage target
+- ❌ Initial setup investment (1-2 weeks)
+
+**Implementation Plan:**
+- Phase 1: Infrastructure setup (Vitest/Playwright configs, CI)
+- Phase 2: Critical path tests (20-30 tests covering key workflows)
+- Phase 3: Expand coverage (component tests, all IPC handlers, E2E journeys)
+- Phase 4: CI/CD integration (GitHub Actions, coverage gates)
+
+**Coverage Targets:**
+- Unit: 70% of utilities, stores, business logic
+- Integration: 100% of critical IPC handlers
+- E2E: 5-10 critical user journeys
+- Overall: 60%+ code coverage
+
+**References:**
+- Detailed strategy: `docs/testing-strategy.md`
+- Electron testing docs: https://www.electronjs.org/docs/latest/tutorial/automated-testing
+- Playwright Electron API: https://playwright.dev/docs/api/class-electron
+- Vitest: https://vitest.dev/

package/docs/decisions/adr-057.md

@@ -0,0 +1,67 @@
+# ADR-057: Knowledge Corrections — File Format and Renderer→Filesystem→MCP Pipeline (2026-04-23)
+
+> Documents the `.liminis/knowledge-corrections.yaml` file format and the architecture of the inline correction flow introduced by the right-click Correction panel.
+
+**Context:**
+
+- Meeting transcripts frequently mis-transcribe names (e.g. "Tito" instead of "Tyto"). Before this feature, a user who spotted the error had to edit the document manually and had no way to push the correction into the knowledge graph.
+- The knowledge-writer MCP server already implements `knowledge_apply_corrections`, which reads a corrections file and merges entities. The file format was defined in the framework SKILL.md but no renderer code wrote to it.
+- A new UI path is needed: right-click selected text → open correction panel → confirm → write YAML → sync graph.
+
+**Decision:**
+
+Introduce `.liminis/knowledge-corrections.yaml` as a first-class workspace artifact written by the renderer and consumed by the knowledge-writer MCP server.
+
+**File format:**
+
+```yaml
+corrections:
+  - type: same_as
+    canonical: "Tyto"
+    aliases:
+      - "Tito"
+      - "Tyto Ornaments"
+  - type: same_as
+    canonical: "Ritesh"
+    aliases:
+      - "Ratesh"
+```
+
+- `type: same_as` — entity merging: the `aliases` are all treated as the same entity as `canonical`.
+- `type: retract` — fact invalidation (not written by the correction panel; reserved for future use).
+- `applied_at` — optional timestamp written by `knowledge_apply_corrections` after it processes an entry. Entries with `applied_at` are skipped on subsequent runs.
+
+**Renderer→filesystem→MCP pipeline:**
+
+1. User right-clicks selected text in the Lexical editor and chooses "Correction…".
+2. `SelectionContextMenuPlugin` calls `useCorrectionStore.getState().open()` — a Zustand action (ADR-025).
+3. `CorrectionPanelPlugin` (a Lexical plugin inside `LexicalComposer`) reads the Zustand store and renders a floating panel.
+4. Panel mounts immediately. In parallel it fires:
+   - `window.api.fs.readFile('.liminis/knowledge-corrections.yaml')` — parsed in the renderer using the `yaml` package
+   - `window.api.mcp.callTool('knowledge-reader', 'knowledge_find_entities', ...)` — async, loads progressively
+   - `window.api.mcp.callTool('knowledge-reader', 'knowledge_search_passages', ...)` — async, loads progressively
+5. On confirm, the renderer:
+   a. Optionally replaces all occurrences of the alias in the open document via `editor.update()` (Lexical history entry is created; undo reverts the document but not the YAML — this is intentional).
+   b. Calls `window.api.fs.mkdir('.liminis')` to ensure the directory exists.
+   c. Merges the new entry into the parsed YAML and writes atomically via `window.api.fs.writeFile(..., 'atomic')` (ADR-055).
+   d. Calls `window.api.mcp.callTool('knowledge-writer', 'knowledge_apply_corrections', {})`.
+   e. If the MCP call fails, shows an error toast; the YAML write is never blocked on MCP availability.
+
+**Why YAML parsing in the renderer (not a dedicated main-process handler):**
+
+The `yaml` package is pure JavaScript — Vite bundles it into the renderer without configuration. Using the existing `fs:readFile` / `fs:writeFile` IPC channels avoids adding a new IPC surface. The renderer merges entries in memory (a simple array operation) and writes the result atomically. A main-process handler would add indirection with no architectural benefit.
+
+**Why `CorrectionPanelPlugin` lives inside `LexicalComposer`:**
+
+Text replacement via `editor.update()` requires access to the Lexical editor instance, which is only available inside the `LexicalComposer` context via `useLexicalComposerContext()`. Placing the panel as a Lexical plugin (alongside `SearchPlugin`, `FrontmatterPlugin`) is consistent with existing practice and avoids passing a replacement callback from `EditorColumn`.
+
+**Graceful degradation:**
+
+- If the knowledge-writer MCP server is unavailable, the YAML write still succeeds. An error toast informs the user: "The correction was saved. It will be applied on the next ingestion pass." The `knowledge_apply_corrections` tool is idempotent and will process the pending entries the next time it is called (e.g., on the next document ingestion).
+- If `.liminis/knowledge-corrections.yaml` does not exist, it is created on first use. The `fs:mkdir` call is a no-op if the directory already exists.
+
+**Consequences:**
+
+- `.liminis/knowledge-corrections.yaml` is the single source of truth for name corrections. Do not introduce a second store.
+- Future features that write corrections (e.g., bulk import, retract entries) must append to this file using the same format.
+- The `applied_at` field is written by the Python MCP server, not by the renderer. The renderer must preserve existing entries (including `applied_at` values) when merging — the `mergeCorrection` helper does this.

package/docs/decisions/adr-070.md

@@ -0,0 +1,131 @@
+# ADR-070: Dedicated Lexical Node Types vs. Paragraph-Pattern Detection for Lossless Markdown Round-Tripping
+
+**Date:** 2026-07-12
+**Status:** Accepted
+**Issue:** #906
+
+## Context
+
+Liminis's editor round-trips markdown through `parse.ts` -> `mdastToLexical.ts` ->
+[Lexical editor state] -> `lexicalToMdast.ts` -> `stringify.ts`. Several markdown
+constructs have no native Lexical equivalent, so the import side must invent an
+in-editor representation and the export side must recognize it and reconstruct the
+original mdast node. This codebase has, by now, used both of the two available
+strategies for that gap, with materially different outcomes:
+
+1. **Dedicated custom Lexical node type(s)** — `CalloutNode` (GitHub-style
+   `> [!NOTE]` blockquotes) and `ToggleContainerNode`/`ToggleTitleNode`/
+   `ToggleContentNode` (`<details>`/`<summary>`) each introduce purpose-built
+   `ElementNode` subclasses, registered in `editorNodes` (`Editor.tsx` and the
+   round-trip test harness), with `importJSON`/`exportJSON`/`importDOM`/`exportDOM`.
+   Export-side detection is a type check (`$isCalloutNode`, `$isToggleContainerNode`)
+   — unambiguous by construction.
+
+2. **Marker/pattern detection on plain nodes** — `footnoteDefinition` support
+   (indent=1 paragraphs, the first prefixed with a `FootnoteNode` label) and the
+   #897 list-item fix (a pair of bare, adjacent `LineBreakNode`s marking a
+   paragraph boundary inside a list item) reuse existing node types and detect a
+   *shape* on export, with no new node class or registration needed.
+
+Issue #906 (definition lists flattened to a bold-term paragraph + plain paragraphs
+on round-trip) needed one of these two strategies chosen for a third construct.
+Research surfaced a specific asymmetry: the existing (lossy) `defList` import
+already marks a definition-list term by toggling **bold** — a generic Lexical
+format bit that ordinary user content can also carry. Pattern (2) is only safe
+when the detected shape cannot occur except as the output of the reciprocal
+import step. The `footnoteDefinition` marker (a dedicated `FootnoteNode`) satisfies
+that; a real user paragraph cannot accidentally contain one. But this codebase's
+own fixture corpus already documents a case where pattern (2) failed that test:
+`other-list-item-double-hard-break` (`fixtures/roundtrip/README.md`) — the #897
+fix's two-bare-`LineBreakNode` marker is also produced by ordinary content (a line
+ending in `\` immediately followed by a line that is only `\`), so on export the
+detector cannot distinguish "list-item paragraph boundary" from "one paragraph
+with two literal hard breaks," and silently reformats the latter.
+
+Reusing **bold formatting** as an implicit term marker for definition lists would
+repeat that exact failure mode, but with a much more common trigger: any ordinary
+bold paragraph followed by an indented paragraph — plausible real-world content —
+would misparse as a former definition list on export, corrupting unrelated
+documents (violating this project's no-regression bar for round-trip fidelity,
+tracked here via the fixture corpus's `FR-007`-style requirement).
+
+## Decision
+
+**Use dedicated custom Lexical node types for definition lists**:
+`DefinitionListNode` (container, `<dl>`), `DefinitionTermNode` (`<dt>`, holds
+phrasing content directly like `HeadingNode`), and `DefinitionDescriptionNode`
+(`<dd>`, holds block content like `ToggleContentNode`) — modeled directly on the
+`CalloutNode`/`ToggleContainerNode` precedent, registered in `editorNodes` in both
+`Editor.tsx` and `roundtrip-test-utils.ts`.
+
+**General rule for future constructs:** prefer a dedicated node type whenever the
+candidate marker for pattern-detection is (or reuses) a *generic* Lexical
+primitive — a format bit (bold/italic/etc.), an indent level, a bare structural
+node (`LineBreakNode`) — that ordinary user-authored content could also produce.
+Pattern detection remains an acceptable lighter-weight choice only when the marker
+is itself dedicated and unique (e.g., a `FootnoteNode` label that only the
+footnote import path ever creates), so the shape genuinely cannot arise except
+from the reciprocal import.
+
+The one-time cost of a dedicated node type — a new `ElementNode` subclass or
+three, `importJSON`/`exportJSON`/`importDOM`/`exportDOM`, and registration in two
+`editorNodes` arrays — is small, bounded, and non-recurring per construct. It
+eliminates the false-positive class of bug entirely, rather than trading it for a
+"probably rare enough" argument that this codebase's own fixture corpus has
+already shown to fail in practice.
+
+## Alternatives Considered
+
+**Reuse the existing bold-paragraph + indented-paragraph marker, detected on
+export.** Rejected: the marker (bold formatting) is a generic format bit that
+real, unrelated user paragraphs can carry, and the closely analogous
+`other-list-item-double-hard-break` gap already demonstrates this class of bug in
+this exact codebase. Continuing to add pattern-detection converters on top of a
+demonstrated false-positive mechanism would compound the risk rather than close it.
+
+**Give definition-list term paragraphs a new, more specific marker (e.g., a
+dedicated zero-width marker node prefixing the term, analogous to
+`FootnoteNode`).** Not pursued: this still requires a new node type (to make the
+marker unique), at which point representing the term/description structure with
+dedicated nodes directly — rather than a marker plus post-hoc paragraph
+regrouping — is simpler and mirrors the mdast shape (`defList` /
+`defListTerm` / `defListDescription`) one-to-one.
+
+## Consequences
+
+**Positive:**
+- Zero false-positive risk: `$isDefinitionListNode`/`$isDefinitionTermNode`/
+  `$isDefinitionDescriptionNode` are exact type checks, not shape heuristics.
+- The Lexical-side representation mirrors mdast's own `defList` shape (flat
+  `defListTerm`/`defListDescription` siblings under one container), so
+  `defListToMarkdown` — already wired into `stringify.ts` — needed no *node-type*
+  changes; only a handler-level spacing override (see Neutral, below) was needed.
+- Establishes an explicit, documented decision rule (above) for the next time this
+  fork comes up, instead of re-litigating the trade-off from scratch or silently
+  defaulting to whichever pattern the most recently touched file happens to use.
+
+**Negative / trade-offs:**
+- Three new node classes and two `editorNodes` registration sites (`Editor.tsx`,
+  `roundtrip-test-utils.ts`) to maintain going forward — boilerplate that a
+  pattern-detection approach would have avoided.
+- No live-editor WYSIWYG affordances (slash-menu entry, toolbar button,
+  Enter-key UX) were added for definition lists — out of scope for this fix — so
+  the new node types are currently reachable only via markdown import/paste, not
+  by typing a definition list from scratch in the editor.
+
+**Neutral:**
+- `mdast-util-definition-list`'s `defListToMarkdown` normalizes the description
+  marker to `:` followed by exactly three spaces (a four-column indent) on every
+  export, regardless of the original input's marker spacing — a pre-existing
+  property of that third-party serializer, independent of this ADR's node-type
+  choice. Since the issue's own reproduction and the spec's acceptance scenarios
+  use the single-space `: ` convention, `stringify.ts` overrides just the
+  `defListDescription` handler (alongside its existing `emphasis`/`strong`/
+  `wikiLink` handler overrides) to emit `: ` instead of `:   `, so byte-identical
+  round-tripping works for that convention without needing to special-case
+  fixture spacing.
+
+## Update log
+
+- **2026-07-12** (issue #906): initial adoption, for definition-list round-trip
+  fidelity.