Doramagic Project Pack · Human Manual
open-knowledge
OpenKnowledge
Overview & Monorepo Architecture
Related topics: Editor, Frontend Components & Integrated Terminal, Server, Persistence, Shadow Repo & Sync, CLI, Desktop Shell & Agent Handoff (Claude / Codex / Cursor)
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Editor, Frontend Components & Integrated Terminal, Server, Persistence, Shadow Repo & Sync, CLI, Desktop Shell & Agent Handoff (Claude / Codex / Cursor)
Overview & Monorepo Architecture
Project Purpose & Scope
OpenKnowledge is a local-first markdown editor and LLM-powered wiki with first-class integrations for Claude Code, Codex, and Cursor. It provides a WYSIWYG editing experience that "feels like editing a Google Doc or Notion page," while keeping the underlying storage as plain markdown in a git repository so that team-based sharing and auto-sync are powered by git itself. Source: README.md:3-9.
The editor is distributed as:
- A macOS desktop app packaged as a DMG, and
- A local web app for Linux and Intel Macs, served by a Node.js 24+ CLI named
ok.
Source: README.md:11-23.
The project emphasizes being local-first: edits round-trip through a Y.js document shared via Hocuspocus, with markdown round-tripped through the core package for serialization and parsing. Source: packages/app/src/server/agent-flow.test.ts:7-37.
Monorepo Layout
The repository is a Bun workspace monorepo. The root package.json declares two workspace globs and pins Bun 1.3.13 plus Node 24 as the package manager and engine, respectively. Source: package.json:1-16.
| Path | Package name | Role | Key dependency / entry |
|---|---|---|---|
packages/core | @inkeep/open-knowledge-core | Markdown ⇄ ProseMirror serialization, Y.js integration, shadow-repo layout, schema, helper bundle | Tiptap 3.22.3, unified/remark/rehype, yjs, Orama (search). Source: packages/core/package.json:1-58 |
packages/server | @inkeep/open-knowledge-server | Hocuspocus collaboration server + MCP SDK for agents | @hocuspocus/server 4.0.0-rc.1, @modelcontextprotocol/sdk. Source: packages/server/package.json:1-26 |
packages/app | @inkeep/open-knowledge-app | Electron + Vite frontend (Tiptap editor, presence, terminal) | Tiptap, Vite 8, Biome, Lingui. Source: packages/app/package.json:1-50 |
packages/cli | @inkeep/open-knowledge | Published CLI ok / open-knowledge (init + start) | Bundles app + server + core; engines.node: ">=24". Source: packages/cli/package.json:1-42 |
docs | (workspace) | Markdown/MDX documentation site | Declared as a workspace in root. Source: package.json:8-10 |
packages/core exposes several entry points (./, ./shadow-repo-layout, ./server, ./keepalive, ./helper-bundle) so that the server, the CLI, and the Electron preload can each import only what they need, while sharing one TypeScript source tree. Source: packages/core/package.json:9-32.
Build & Test Orchestration
Task orchestration is handled by Turbo. The turbo.json defines per-task inputs so that Turbo can cache results based on which source files changed. Examples:
test:integrationdeclares inputs acrosssrc/,tests/,../server/src/,../core/src/, the workspacebiome.jsonc, and../../biome-plugins/**— meaning a change to any lint plugin invalidates every app integration test cache entry. Source: turbo.json:1-60.test:conversionscopes tosrc/editor/**, conversion/integration tests, and thecore+serverpackages.test:dom,test:e2e,test:visual, andtest:a11yare deliberatelycache: false, because their results depend on a real browser/Electron runtime.
The CLI ships as an aggregated artifact. packages/cli copies packages/app/dist into dist/public and bundles the server's skill assets so a single npm install -g @inkeep/open-knowledge delivers a runnable editor. Source: packages/cli/package.json:33-42.
Cross-Package Data Flow
At runtime, the data path for a single user keystroke is: Editor (Tiptap/ProseMirror) → Y.Doc (Hocuspocus) → MarkdownManager (core) → files on disk. Agents reverse the flow via MCP: they receive a Y.Doc view, mutate the default XmlFragment or the source Y.Text, and the changes propagate back through the editor. Source: packages/app/src/server/agent-flow.test.ts:17-55.
flowchart LR UI[Tiptap Editor<br/>packages/app] -- "Y.js deltas" --> HOCUS[Hocuspocus<br/>packages/server] HOCUS -- "Y.Doc events" --> CORE[MarkdownManager<br/>packages/core] CORE -- "round-trip markdown" --> FS[(Project files on disk<br/>git-backed)] AGENT[Claude / Codex / Cursor<br/>via MCP] -- "Y.Doc writes" --> HOCUS CLI[ok CLI<br/>packages/cli] -- "serves app + server" --> UI
The integration test packages/app/src/server/agent-flow.test.ts codifies the contract: after an agent writes through a Hocuspocus.openDirectConnection, the resulting XmlFragment must contain the expected paragraphs and serialize through MarkdownManager to markdown that contains the agent's text. Source: packages/app/src/server/agent-flow.test.ts:19-37. A second case verifies the markdown source-mode path: the agent appends raw markdown to a Y.Text('source') channel, and the editor preserves both the original paragraph and the injected content. Source: packages/app/src/server/agent-flow.test.ts:39-75.
Tooling & Conventions
The monorepo pins runtime versions (.bun-version and .node-version) and uses Biome for linting/formatting plus a set of custom GritQL plugins under biome-plugins/. These plugins encode project-specific conventions — for example microcopy-ellipsis reserves … for native macOS menus and truncation indicators, while no-unportaled-editor-content enforces that <EditorContent /> is always rendered through a React portal. Source: biome-plugins/README.md:30-80. Tests for these plugins live in packages/app/tests/integration/, and the test:integration Turbo inputs explicitly include ../../biome-plugins/** so plugin changes re-run the plugin tests. Source: turbo.json:13-22.
The v0.18.1-beta.3 release notes (community context) describe a small UX change to the integrated terminal — its default height now computes as about one third of the window height on first use rather than a hard-coded 240 px. This sits squarely in the packages/app Electron shell and illustrates the kind of user-facing polish the monorepo enables: a single package change shipped through the same ok CLI distribution pipeline. Source: package.json:18-30, packages/cli/package.json:21-31.
See Also
- Editor & Yjs Collaboration
- Agent / MCP Integration
- CLI Distribution & Build Pipeline
- Biome Plugins & Lint Conventions
Source: https://github.com/inkeep/open-knowledge / Human Manual
Editor, Frontend Components & Integrated Terminal
Related topics: Overview & Monorepo Architecture, Server, Persistence, Shadow Repo & Sync, CLI, Desktop Shell & Agent Handoff (Claude / Codex / Cursor)
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview & Monorepo Architecture, Server, Persistence, Shadow Repo & Sync, CLI, Desktop Shell & Agent Handoff (Claude / Codex / Cursor)
Editor, Frontend Components & Integrated Terminal
OpenKnowledge is a local-first markdown editor and LLM wiki that pairs a WYSIWYG Tiptap-based editing surface with an integrated terminal for running project tooling alongside the document. This page covers the frontend component architecture, the editor's collaborative write model, and the integrated terminal's behavior and recent changes. Source: README.md:1-3
Project Layout and Package Roles
The repository is a Bun/Turborepo monorepo with four primary workspace packages that together compose the editor experience:
| Package | Role | Public Binaries |
|---|---|---|
@inkeep/open-knowledge-app | Vite-built frontend (Tiptap editor, UI components, terminal panel) | — |
@inkeep/open-knowledge-core | Markdown ↔ ProseMirror serialization, Yjs binding, Orama search, schema definitions | — |
@inkeep/open-knowledge-server | Hocuspocus collaboration server, MCP SDK, OpenTelemetry traces/metrics | — |
@inkeep/open-knowledge (CLI) | ok init / ok start --open for Linux/Intel-Mac local-web workflow | open-knowledge, ok |
The CLI's build:app script copies packages/app/dist into dist/public, so the npm-published CLI ships the prebuilt editor assets inside the binary. Source: packages/cli/package.json:32-42
Tiptap Editor and the Yjs Collaborative Surface
The editor is built on Tiptap v3 (@tiptap/core, @tiptap/pm, @tiptap/starter-kit) and renders into a Yjs XmlFragment named default. The MarkdownManager from @inkeep/open-knowledge-core serializes the Yjs fragment to markdown and back, while @tiptap/y-tiptap (yXmlFragmentToProseMirrorRootNode) converts the fragment into a ProseMirror root node for rendering. Source: packages/app/src/server/agent-flow.test.ts:7-19, packages/core/package.json:39-48
A second Yjs primitive — a Y.Text named source — holds the raw markdown projection. Agent writes can target either surface:
- Rich write (default fragment): the agent pushes a
Y.XmlElement('paragraph')containing aY.XmlTextwith the inserted delta; Tiptap re-renders and the markdown manager re-serializes the document. - Markdown write (source text): the agent appends to
doc.getText('source'), which the source-mode viewer reflects without re-parsing through ProseMirror.
The agent-sim harness exercises both paths against an Hocuspocus.openDirectConnection so the same code path used by remote agents is testable in-process. Source: packages/app/src/server/agent-flow.test.ts:21-46, packages/app/src/server/agent-flow.test.ts:60-90
flowchart LR Agent[Agent / CLI] -->|Y.Doc transact| Fragment[XmlFragment 'default'] Agent -.->|append markdown| Source[Y.Text 'source'] Fragment --> Tiptap[Tiptap Editor UI] Source --> SourceView[Source-mode viewer] Fragment --> MM[MarkdownManager] Source --> MM MM --> Disk[(Project files via git sync)]
Frontend Component Conventions
UI components live under packages/app/src/components and packages/app/src/editor. A few load-bearing conventions are enforced by custom Biome plugins so the lint budget is the source of truth:
- No unportaled
EditorContent.createPortal(<EditorContent …/>, portalTarget)is the sanctioned shape, preventing H6 cross-doc DOM bleed. Source: biome-plugins/README.md:no-unportaled-editor-content.grit section - Ellipsis discipline.
…is reserved for native macOS menu items (built viaMenu.buildFromTemplate) and for literal truncation indicators (graph labels, breadcrumb collapse, search snippets). It is forbidden in JSX text children and inplaceholder|aria-label|title|description|tooltipattributes. Source: biome-plugins/README.md:microcopy-ellipsis.grit section - Playwright
toPassbudget.toPass({ timeout: N })below15_000is flagged because macOSopen(1)plus window/IPC startup empirically takes 2–8s on a healthy CI runner. Source: biome-plugins/README.md:playwright-topass-budget.grit section
Components that need to silence these rules use the suppression form // biome-ignore lint/plugin/<rule-name>: <reason> — a per-rule suppression that survives grep and ratchets down with the backlog. Source: biome-plugins/README.md:Suppression syntax
Integrated Terminal
The integrated terminal lives alongside the editor and reuses the same project working directory, so commands like git, bun, and project CLIs run in the same shell context the user is editing. On Linux and Intel Macs, ok start boots the same editor as a local web app, and the terminal panel is mounted in the desktop shell. Source: README.md:9-19
Height policy change (v0.18.1-beta.3)
Prior to v0.18.1-beta.3, the terminal opened at a fixed 240px on first use, which was frequently too short to read a command's output before the user had to drag the splitter. The new behavior computes the default height as roughly one third of the window height on first open. The exact computation and the persisted-overrides flow live in the TerminalPanel / TerminalDock components, and the test tier (test:integration, test:e2e) gates regressions in the splitter contract. Source: turbo.json:test:integration inputs, community release notes for v0.18.1-beta.3
Terminal gating and CLI detection
TerminalGate decides whether the terminal mounts at all, and TerminalCliMissingBanner surfaces a recoverable error when the user's PATH is missing the shell or the ok binary the terminal expects to invoke. Both are tree-shakeable so a user who never opens the terminal does not pay the bundle cost. Source: README.md:9-19, packages/app/package.json:30-80
Common failure modes
| Symptom | Likely cause | Where to look |
|---|---|---|
| Terminal mounts but commands are no-ops | ok binary not in PATH (CLI not installed globally) | TerminalCliMissingBanner |
| First-open height reverts to old value | Cached prefersTerminalHeight in local storage from a prior beta | Browser devtools → application storage |
| Agent markdown appends vanish in WYSIWYG | Write targeted Y.Text 'source' while editor was in source mode (expected) | agent-flow.test.ts:source mode injection test |
| Splitter drag is janky on HiDPI | Missing devicePixelRatio listener on the panel resize observer | TerminalDock.tsx resize effect |
See Also
- README.md — install,
ok init/ok startworkflow - packages/core/src/markdown —
MarkdownManagerround-trip semantics - packages/server/src — Hocuspocus + MCP wiring
- biome-plugins/README.md — GritQL plugin authoring guide
- v0.18.1-beta.3 release notes — terminal default-height change
Source: https://github.com/inkeep/open-knowledge / Human Manual
Server, Persistence, Shadow Repo & Sync
Related topics: Overview & Monorepo Architecture, Editor, Frontend Components & Integrated Terminal, CLI, Desktop Shell & Agent Handoff (Claude / Codex / Cursor)
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview & Monorepo Architecture, Editor, Frontend Components & Integrated Terminal, CLI, Desktop Shell & Agent Handoff (Claude / Codex / Cursor)
Server, Persistence, Shadow Repo & Sync
The open-knowledge editor is a local-first, git-backed markdown workspace. To deliver real-time collaboration, agent integration, and durable on-disk storage without sacrificing the local-first feel, the project ships a dedicated server package (@inkeep/open-knowledge-server) that owns the realtime sync plane, the disk persistence plane, and the git/shadow-repo plane. This page documents how those planes fit together.
1. Role and Scope of the Server Package
The server package is the runtime that mediates between Yjs documents in the browser/Electron renderer, the local filesystem, and the user’s git repository. It is published as the workspace package @inkeep/open-knowledge-server and is consumed by the desktop app, the ok CLI web mode, and integration tests. Source: packages/server/package.json.
Key responsibilities visible from the dependency and test surface:
| Concern | Implementation |
|---|---|
| Realtime collaboration | @hocuspocus/server 4.0.0-rc.1 (Hocuspocus class) — Source: packages/app/src/server/agent-flow.test.ts |
| CRDT document model | yjs, @tiptap/y-tiptap, ProseMirror schema — Source: packages/server/package.json |
| Agent ↔ editor bridge | MCP SDK (@modelcontextprotocol/sdk) and direct Yjs transactions — Source: packages/app/src/server/agent-flow.test.ts |
| Observability | OpenTelemetry trace + metric exporters (OTLP HTTP) — Source: packages/server/package.json |
| Persistence & sync | server-factory, persistence, sync-engine, conflict-storage, file-watcher, shadow-repo modules |
The README frames the product as “a beautiful, local-first markdown editor and LLM wiki … Sharing and auto-sync are available for team-based collaboration [and] are powered by git.” Source: README.md.
2. Document Model and Sync Engine
The editor stores two parallel representations of the same file inside a single Yjs document:
- An
XmlFragment('default')that mirrors the ProseMirror / Tiptap rich-text tree. This is what the WYSIWYG surface binds to. - A
Y.Text('source')that holds the canonical markdown serialization. This is what the source-mode surface binds to and what the git layer diffs against.
Both shapes are written inside doc.transact(...) so origin tracking and undo stay consistent. The agent-flow.test.ts suite exercises three write paths: a direct Y.XmlElement push into the fragment, a markdown append into Y.Text('source'), and a source-mode “agent write updates serialized markdown” scenario that asserts the fragment re-serializes to the expected markdown. Source: packages/app/src/server/agent-flow.test.ts.
The sync-engine module owns the reconciliation rules between these two representations and feeds the resulting state to the persistence layer. Because the markdown in Y.Text('source') is what eventually lands on disk, the engine keeps the two sides consistent — e.g. when an agent writes markdown, the next observation round re-derives the fragment snapshot. The same module is what the desktop app and CLI rely on for opening documents in Hocuspocus.openDirectConnection(...) for headless writes.
3. Persistence Layer and Conflict Storage
persistence.ts is responsible for durable storage of Yjs updates between sessions, while conflict-storage.ts captures the cases where the on-disk markdown (e.g. a concurrent git pull, an external editor save) diverges from what the live document expects. When divergence is detected, the conflict-storage path keeps both the CRDT side and the disk side instead of silently overwriting — users can later resolve the conflict inside the editor.
The file-watcher.ts module bridges the filesystem and the sync engine: it observes the working tree and feeds external changes back into the sync engine so that, for example, switching branches or pulling in a teammate’s commit surfaces in the editor without losing local CRDT state.
Because the build pipeline caches by source inputs (turbo.json declares inputs per test:integration task that includes ../server/src/**/*.ts and ../core/src/**/*.ts), any change to these modules forces a full integration rebuild, signaling that the persistence ↔ sync boundary is treated as load-bearing. Source: turbo.json.
4. Shadow Repo and Git-Backed Sync
OpenKnowledge persists every change as git commits inside a hidden mirror of the user’s project — a “shadow repo.” The layout of that mirror is shared between the core package and the server so both agree on where each document lives on disk. Source: packages/core/src/shadow-repo-layout.ts.
The shadow-repo.ts module is the server-side owner of this layout. It:
- Creates and maintains the shadow repo on first launch (or detects an existing one).
- Writes Yjs snapshots as ordinary markdown files at the layout paths.
- Commits those files so that every edit produces a reviewable git history — the same history that powers team sharing, as described in the README. Source: README.md.
- Coordinates with
conflict-storageso that three-way merges (CRDT vs. shadow vs. upstream remote) can be surfaced rather than dropped.
flowchart LR
Editor[Tiptap / Yjs in renderer] -- Yjs sync --> SyncEngine[sync-engine.ts]
Agent[LLM agent via MCP] -- Yjs transactions --> SyncEngine
SyncEngine -- XmlFragment + Y.Text --> Persistence[persistence.ts]
Persistence -- markdown snapshots --> ShadowRepo[shadow-repo.ts]
ShadowRepo -- git commits --> Git[(Local shadow git repo)]
Git -- push / pull --> Remote[(Team remote)]
FileWatcher[file-watcher.ts] -- external diffs --> SyncEngine
ConflictStorage[conflict-storage.ts] -- unresolved diffs --> Editor5. Operational Notes and Common Failure Modes
- Dual-write consistency. Both the rich-text fragment and the markdown
Y.Textmust be written in the samedoc.transactcall; otherwise the editor and the shadow repo can drift. Theagent-flow.test.tssuite pins this contract. - First-use terminal sizing (community context). v0.18.1-beta.3 changed the integrated terminal default to one third of window height — a UX-only patch, but it shows the project’s pattern of pairing editor-facing defaults with reactive sizing computed from runtime dimensions, similar in spirit to how the sync engine reacts to runtime Yjs events.
- Build caching.
turbo.jsondeclarescache: truefortest:integrationandtest:conversion, with explicitinputscoveringpackages/server/src/**/*.tsandpackages/core/src/**/*.ts— change any persistence or sync file and the gate re-runs. Source: turbo.json. - External edits. The file-watcher is the only path that pulls filesystem changes back into the CRDT; disabling or misconfiguring it leaves the editor blind to
git pull, IDE refactors, or CLI-driven rewrites.
See Also
- Editor extensions and WYSIWYG surface — see the project’s editor package and
sharedextensions referenced byagent-flow.test.ts. - CLI install and
ok initflow — README.md. - Core markdown ↔ ProseMirror serialization —
@inkeep/open-knowledge-core(see packages/core/package.json).
Source: https://github.com/inkeep/open-knowledge / Human Manual
CLI, Desktop Shell & Agent Handoff (Claude / Codex / Cursor)
Related topics: Overview & Monorepo Architecture, Editor, Frontend Components & Integrated Terminal, Server, Persistence, Shadow Repo & Sync
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Overview & Monorepo Architecture, Editor, Frontend Components & Integrated Terminal, Server, Persistence, Shadow Repo & Sync
CLI, Desktop Shell & Agent Handoff (Claude / Codex / Cursor)
OpenKnowledge ships in two delivery shapes that share one editor core: a macOS desktop bundle and a Node-based local web app driven by an ok CLI. Both shapes converge on a Hocuspocus-backed Y.Doc so that external agents (Claude Code, Codex, Cursor) can write markdown into a document while the editor reflects the change in real time. Source: README.md.
Distribution Shapes
Desktop app (macOS)
The README describes a signed DMG that drops Open Knowledge.app into /Applications. Source: README.md. The desktop bundle re-uses the same editor and server packages — packages/app and packages/server — so feature parity between the DMG and the CLI is intentional. The @inkeep/open-knowledge-app package is private: true, indicating it is built only inside this monorepo, while the CLI package (@inkeep/open-knowledge, version 0.18.0) is published for general consumption. Source: packages/app/package.json, Source: packages/cli/package.json.
CLI / local web app
On Linux, Intel Macs, or any environment where the DMG is not viable, the editor runs as a browser-served web app. The CLI registers two bin entries — open-knowledge and ok — pointing at dist/cli.mjs. Source: packages/cli/package.json. Bootstrapping requires Node.js 24+ (.node-version) and Bun 1.3.13+ (.bun-version). Source: README.md.
CLI Surface
Two commands are documented in the README:
| Command | Purpose |
|---|---|
ok init | Scaffold the current directory as an OpenKnowledge project and wire up Claude Code, Cursor, and Codex integrations. |
ok start --open | Serve the editor locally and open it in the user's default browser. |
Source: README.md.
The CLI package depends on @inkeep/open-knowledge-app, @inkeep/open-knowledge-core, and @inkeep/open-knowledge-server (all workspace:*), so the same editor bundle that ships in the DMG is statically embedded by the CLI build. The build:app script copies packages/app/dist into dist/public, and build:skill-asset bundles server-side skill assets into the CLI distribution. Source: packages/cli/package.json. This means ok start serves the production editor bundle; it does not hot-reload packages/app/src/** unless invoked from the monorepo via bun run dev.
Desktop Shell
The desktop shell wraps the same Vite-built editor and Hocuspocus server in an Electron-style host. The lint plugin rule no-loosely-typed-webcontents-ipc is suppressed in 12 sites of packages/desktop/src/main/preload/index.ts, 1 site of packages/desktop/src/main/shared/ipc-send.ts, and 2 e2e smoke sites — a strong signal that the desktop shell uses typed contextBridge channels to expose a narrow API surface to the renderer. Source: biome-plugins/README.md.
A notable UX change in the latest beta: the integrated terminal now opens at approximately one third of the window height on first use, rather than the prior fixed 240px default. Source: v0.18.1-beta.3 release notes (community context). This matches a common complaint pattern in markdown editors where a fixed pixel default is too short for command output without manual dragging.
Agent Handoff (Claude / Codex / Cursor)
Wiring during `ok init`
ok init configures three agent surfaces side by side so that an LLM agent can read or write into the same Y.Doc the editor uses:
- Claude Code — wired as a project skill via
@modelcontextprotocol/sdk. - Cursor — wired through the editor's helper bundle.
- Codex — wired through the CLI's skill bundle (
build-skill-asset).
Sources: README.md, packages/server/package.json, packages/cli/package.json.
Write path
Agents write through a Hocuspocus DirectConnection against the same document name the editor has open. The test suite demonstrates the contract: a server-side Hocuspocus instance opens openDirectConnection('test-agent-flow'), mutates the default Y.XmlFragment inside a transaction, then re-serializes the fragment through yXmlFragmentToProseMirrorRootNode plus MarkdownManager.serialize to confirm the markdown string contains the agent's text. Source: packages/app/src/server/agent-flow.test.ts.
A second variant, "source mode injection," proves that an agent can write by appending to a Y.Text named source while the user is in raw markdown view. The test seeds the fragment, hydrates doc.getText('source') with the serialized markdown, then inserts ${separator}${agentMarkdown}\n at the end inside a transaction tagged 'agent-write'. The serialized markdown after the operation must contain both the original and the agent text. Source: packages/app/src/server/agent-flow.test.ts.
flowchart LR
A[Claude / Codex / Cursor agent] -->|MCP skill or helper bundle| B[ok init config]
B --> C[Hocuspocus server]
C -->|DirectConnection.transact| D[Y.Doc default fragment + source text]
D -->|yXmlFragmentToProseMirrorRootNode| E[TipTap ProseMirror schema]
E -->|MarkdownManager.serialize| F[Markdown string]
F -->|reflected to| G[Editor WYSIWYG / Source mode]The same MarkdownManager and sharedExtensions from @inkeep/open-knowledge-core are used by both the editor (via @tiptap/core's schema) and the agent write path, guaranteeing round-trip fidelity. Source: packages/app/src/server/agent-flow.test.ts, Source: packages/core/package.json.
Agent simulator
packages/app/src/server/agent-sim.ts is a developer-facing simulator that drives the same write paths against a running dev server. It exposes two modes — agentWriteMarkdown (raw Y.Text append) and agentWriteRaw (fragment mutation) — and a "patch mode" that walks a PATCH_SEQUENCE of find/replace pairs over a starter document, logging awareness transitions (editing→idle) and activity-map updates after each successful write. Source: packages/app/src/server/agent-sim.ts. If a write fails the simulator prints Is the dev server running? (bun run dev) to remind the operator to start the editor first. Source: packages/app/src/server/agent-sim.ts.
Common Failure Modes
- CLI invoked without
ok init:ok start --openwill serve the editor, but no agent will be wired into the project. Re-runok initfrom the project root. - Agent writes invisible in editor: usually means the agent opened a
DirectConnectionagainst a different document name than the editor's active tab. Verify the doc identifier matches. - Source-mode divergence: the agent wrote into the
Y.XmlFragment, but the editor is in source mode and shows theY.Text('source')projection. Both views must observe each other; the test inagent-flow.test.tsenforces that invariant. - Stale skill bundle: after changing skill source, run
bun run build:skill-assetin the CLI package sodist/assets/skills/is regenerated before publishing. - Terminal too short: fixed-pixel terminal defaults are replaced by a proportional one-third-of-window default in v0.18.1-beta.3 — older betas need a manual drag if the divider feels cramped. Source: v0.18.1-beta.3 release notes (community context).
See Also
- README.md — installation and quickstart
- packages/cli/package.json — CLI package manifest and build scripts
- packages/app/src/server/agent-flow.test.ts — canonical agent-write test contract
- packages/app/src/server/agent-sim.ts — developer agent simulator
- biome-plugins/README.md — desktop IPC typing conventions
Sources: README.md, packages/server/package.json, packages/cli/package.json.
Doramagic Pitfall Log
Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
May increase setup, validation, or first-run risk for the user.
Doramagic Pitfall Log
Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.
1. Configuration risk: Configuration risk requires verification
- Severity: medium
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.host_targets | https://news.ycombinator.com/item?id=48675435
2. Capability evidence risk: Capability evidence risk requires verification
- Severity: medium
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: capability.assumptions | https://news.ycombinator.com/item?id=48675435
3. Maintenance risk: Maintenance risk requires verification
- Severity: medium
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48675435
4. Security or permission risk: Security or permission risk requires verification
- Severity: medium
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: downstream_validation.risk_items | https://news.ycombinator.com/item?id=48675435
5. Security or permission risk: Security or permission risk requires verification
- Severity: medium
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=48675435
6. Maintenance risk: Maintenance risk requires verification
- Severity: low
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48675435
7. Maintenance risk: Maintenance risk requires verification
- Severity: low
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Recommended check: Reproduce the official install and quickstart path in an isolated environment.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48675435
Source: Doramagic discovery, validation, and Project Pack records
Community Discussion Evidence
These external discussion links are review inputs, not standalone proof that the project is production-ready.
Count of project-level external discussion links exposed on this manual page.
Open the linked issues or discussions before treating the pack as ready for your environment.
Community Discussion Evidence
Doramagic exposes project-level community discussion separately from official documentation. Review these links before using open-knowledge with real data or production workflows.
- v0.18.1-beta.3 - github / github_release
- v0.18.1-beta.2 - github / github_release
- v0.18.1-beta.1 - github / github_release
- v0.18.1-beta.0 - github / github_release
- v0.18.0 - github / github_release
- v0.18.0-beta.0 - github / github_release
- v0.17.1-beta.1 - github / github_release
- v0.17.1-beta.0 - github / github_release
- v0.17.0 - github / github_release
- v0.17.0-beta.0 - github / github_release
- Configuration risk requires verification - GitHub / issue
Source: Project Pack community evidence and pitfall evidence