OpenKnowledge Documentation

Pages

1. OverviewMonorepo packages, runtime surfaces (desktop app, `ok` CLI web editor, MCP server), and the shortest path from install to first agent-driven edit.
2. InstallationInstall paths for the macOS desktop DMG and the `@inkeep/open-knowledge` npm CLI, including Node.js 24+, git, and Bun toolchain prerequisites for contributors.
3. QuickstartRun `ok init`, `ok start --open`, verify the editor loads, and confirm MCP tools respond from a connected agent.
4. Core conceptsThree-layer model (editor, knowledge engine, markdown files), filesystem-as-database persistence, link graph and backlinks, and git-backed attribution.
5. Project scaffold`.ok/` directory layout, three config scopes (project, user, project-local), `.okignore` exclusions, and `content.dir` content-root semantics.
6. Collaboration serverHocuspocus/Yjs CRDT server lifecycle, per-project `ok start` locks, server-free MCP reads (`exec`, `preview_url`) versus server-routed writes, and protocol version boundaries.
7. Initialize a projectRun `ok init` to scaffold `.ok/`, initialize git, install project and user skills, and register MCP entries for detected editors (Claude Code, Cursor, Codex).
8. Wire agent editorsConnect Claude Code, Cursor, and Codex via MCP registration, bundled skills, `ok repair-skills`, and verification prompts that exercise the `exec` tool.
9. Editor workflowsWYSIWYG and source-mode editing, ephemeral single-file sessions (`ok notes.md`), Open with AI handoffs, properties pane, timeline panel, and rich MDX embeds.
10. GitHub sync and conflictsClone with `ok clone`, enable auto-sync, push/pull via CLI, and resolve merge conflicts through MCP `conflicts` and `resolve_conflict` tools.
11. Team sharingPublish projects to GitHub, construct share URLs, and manage read-only doc sharing via `ok share` and `ok sharing` commands.
12. Semantic search setupEnable embeddings-based MCP search ranking with `ok embeddings set-key`, project-local `search.semantic.*` config, and content-egress constraints.
13. Folders and templatesFolder properties in `.ok/frontmatter.yml`, leaf-to-root template resolution, and MCP `write({ document: { template } })` instantiation semantics.
14. CLI referenceAll `ok` subcommands, global flags (`--cwd`, `--log-level`), server management (`start`, `stop`, `ps`, `status`, `clean`), and single-file dispatch behavior.
15. MCP tools referenceSeventeen MCP tools (`exec`, `search`, `links`, `write`, `edit`, `delete`, `move`, `history`, `checkpoint`, `workflow`, and others), input nesting conventions, preview envelopes, and conflict guards.
16. Configuration referenceYAML config keys in `.ok/config.yml`, `~/.ok/global.yml`, and `.ok/local/config.yml`; precedence order; published JSON Schema paths; and environment-only variables.
17. HTTP API referenceEditor and agent HTTP routes on the Hocuspocus server (`/api/agent-write-md`, `/api/search`, `/api/documents`, `/api/share/*`, `/api/local-op/*`) used by the web app and desktop shell.
18. Auth referenceGitHub OAuth device flow (`ok auth login`), PAT storage, `gh` CLI credential reuse, git credential helper, and token scopes for clone, sync, and share operations.
19. Karpathy LLM wiki workflowSource-grounded knowledge base pattern with `research/` and `articles/` folders, starter packs, and MCP `workflow` kinds `ingest`, `research`, and `consolidate`.
20. Entity vault workflowGBrain-compatible entity dossiers with compiled truth and append-only timelines, scaffolded via starter packs and maintained through MCP write and checkpoint tools.
21. TroubleshootingDiagnose server lock state, run `ok diagnose health` and `ok diagnose bundle`, file bug reports, repair stale skills/MCP configs, and recover from crash leftovers with `ok clean`.
22. ContributingPublic mirror PR flow, `bun install` and `bun run check` gate, package layout, changeset requirements, and local dev commands for app and docs site.