# OpenKnowledge Documentation

> Reference for the local-first markdown editor, `ok` CLI, Hocuspocus collaboration server, and MCP tool surface that agents use to read and write knowledge bases stored as git-versioned files.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e)
- [GitHub repository](https://github.com/sashimikun/open-knowledge)

## Repository

- Repository: sashimikun/open-knowledge

- Generated: 2026-06-25T22:59:07.884Z
- Updated: 2026-06-25T23:00:14.631Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 22

## Pages

- [Overview](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/01-overview.md): Monorepo packages, runtime surfaces (desktop app, `ok` CLI web editor, MCP server), and the shortest path from install to first agent-driven edit.
- [Installation](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/02-installation.md): Install paths for the macOS desktop DMG and the `@inkeep/open-knowledge` npm CLI, including Node.js 24+, git, and Bun toolchain prerequisites for contributors.
- [Quickstart](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/03-quickstart.md): Run `ok init`, `ok start --open`, verify the editor loads, and confirm MCP tools respond from a connected agent.
- [Core concepts](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/04-core-concepts.md): Three-layer model (editor, knowledge engine, markdown files), filesystem-as-database persistence, link graph and backlinks, and git-backed attribution.
- [Project scaffold](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/05-project-scaffold.md): `.ok/` directory layout, three config scopes (project, user, project-local), `.okignore` exclusions, and `content.dir` content-root semantics.
- [Collaboration server](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/06-collaboration-server.md): Hocuspocus/Yjs CRDT server lifecycle, per-project `ok start` locks, server-free MCP reads (`exec`, `preview_url`) versus server-routed writes, and protocol version boundaries.
- [Initialize a project](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/07-initialize-a-project.md): Run `ok init` to scaffold `.ok/`, initialize git, install project and user skills, and register MCP entries for detected editors (Claude Code, Cursor, Codex).
- [Wire agent editors](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/08-wire-agent-editors.md): Connect Claude Code, Cursor, and Codex via MCP registration, bundled skills, `ok repair-skills`, and verification prompts that exercise the `exec` tool.
- [Editor workflows](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/09-editor-workflows.md): WYSIWYG and source-mode editing, ephemeral single-file sessions (`ok notes.md`), Open with AI handoffs, properties pane, timeline panel, and rich MDX embeds.
- [GitHub sync and conflicts](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/10-github-sync-and-conflicts.md): Clone with `ok clone`, enable auto-sync, push/pull via CLI, and resolve merge conflicts through MCP `conflicts` and `resolve_conflict` tools.
- [Team sharing](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/11-team-sharing.md): Publish projects to GitHub, construct share URLs, and manage read-only doc sharing via `ok share` and `ok sharing` commands.
- [Semantic search setup](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/12-semantic-search-setup.md): Enable embeddings-based MCP search ranking with `ok embeddings set-key`, project-local `search.semantic.*` config, and content-egress constraints.
- [Folders and templates](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/13-folders-and-templates.md): Folder properties in `.ok/frontmatter.yml`, leaf-to-root template resolution, and MCP `write({ document: { template } })` instantiation semantics.
- [CLI reference](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/14-cli-reference.md): All `ok` subcommands, global flags (`--cwd`, `--log-level`), server management (`start`, `stop`, `ps`, `status`, `clean`), and single-file dispatch behavior.
- [MCP tools reference](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/15-mcp-tools-reference.md): Seventeen MCP tools (`exec`, `search`, `links`, `write`, `edit`, `delete`, `move`, `history`, `checkpoint`, `workflow`, and others), input nesting conventions, preview envelopes, and conflict guards.
- [Configuration reference](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/16-configuration-reference.md): YAML config keys in `.ok/config.yml`, `~/.ok/global.yml`, and `.ok/local/config.yml`; precedence order; published JSON Schema paths; and environment-only variables.
- [HTTP API reference](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/17-http-api-reference.md): Editor 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.
- [Auth reference](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/18-auth-reference.md): GitHub OAuth device flow (`ok auth login`), PAT storage, `gh` CLI credential reuse, git credential helper, and token scopes for clone, sync, and share operations.
- [Karpathy LLM wiki workflow](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/19-karpathy-llm-wiki-workflow.md): Source-grounded knowledge base pattern with `research/` and `articles/` folders, starter packs, and MCP `workflow` kinds `ingest`, `research`, and `consolidate`.
- [Entity vault workflow](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/20-entity-vault-workflow.md): GBrain-compatible entity dossiers with compiled truth and append-only timelines, scaffolded via starter packs and maintained through MCP write and checkpoint tools.
- [Troubleshooting](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/21-troubleshooting.md): Diagnose 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`.
- [Contributing](https://grok-wiki.com/public/docs/sashimikun-open-knowledge-5c45105c876e/pages/22-contributing.md): Public mirror PR flow, `bun install` and `bun run check` gate, package layout, changeset requirements, and local dev commands for app and docs site.

## Source Files

- `.bun-version`
- `.changeset/config.json`
- `.env.example`
- `.github/workflows/monorepo-pr-bridge.yml`
- `.node-version`
- `AGENTS.md`
- `CONTRIBUTING.md`
- `docs/content/advanced/folders-and-templates.mdx`
- `docs/content/features/agent-activity.mdx`
- `docs/content/features/assets-and-embeds.mdx`
- `docs/content/features/editor.mdx`
- `docs/content/features/github-sync.mdx`
- `docs/content/features/ignore-patterns.mdx`
- `docs/content/features/share.mdx`
- `docs/content/features/timeline-and-recovery.mdx`
- `docs/content/get-started/overview.mdx`
- `docs/content/get-started/quickstart.mdx`
- `docs/content/integrations/claude-code.mdx`
- `docs/content/integrations/codex.mdx`
- `docs/content/integrations/cursor.mdx`
- `docs/content/reference/cli.mdx`
- `docs/content/reference/configuration.mdx`
- `docs/content/reference/core-concepts.md`
- `docs/content/reference/mcp.mdx`
- `docs/content/workflows/entity-vault.mdx`
- `docs/content/workflows/karpathy-llm-wiki.mdx`
- `docs/package.json`
- `package.json`
- `packages/app/package.json`
- `packages/cli/package.json`
- `packages/cli/scripts/build-config-schema.mjs`
- `packages/cli/scripts/postinstall.mjs`
- `packages/cli/src/cli.ts`
- `packages/cli/src/commands/auth/git-credential.ts`
- `packages/cli/src/commands/auth/index.ts`
- `packages/cli/src/commands/auth/login.ts`
- `packages/cli/src/commands/auth/pat.ts`
- `packages/cli/src/commands/auth/status.ts`
- `packages/cli/src/commands/bug-report.ts`
- `packages/cli/src/commands/clean.ts`
- `packages/cli/src/commands/clone.ts`
- `packages/cli/src/commands/config.ts`
- `packages/cli/src/commands/diagnose-health.ts`
- `packages/cli/src/commands/diagnose.ts`
- `packages/cli/src/commands/editors.ts`
- `packages/cli/src/commands/embeddings/index.ts`
- `packages/cli/src/commands/init.ts`
- `packages/cli/src/commands/install-skill.ts`
- `packages/cli/src/commands/lock-state.ts`
- `packages/cli/src/commands/mcp.ts`
- `packages/cli/src/commands/open.ts`
- `packages/cli/src/commands/ps.ts`
- `packages/cli/src/commands/pull.ts`
- `packages/cli/src/commands/push.ts`
- `packages/cli/src/commands/repair-mcp-configs.ts`
- `packages/cli/src/commands/repair-skills.ts`
- `packages/cli/src/commands/seed.ts`
- `packages/cli/src/commands/share/publish.ts`
- `packages/cli/src/commands/sharing/share.ts`
- `packages/cli/src/commands/single-file-dispatch.ts`
- `packages/cli/src/commands/single-file-open.ts`
- `packages/cli/src/commands/start.ts`
- `packages/cli/src/commands/status.ts`
- `packages/cli/src/commands/stop.ts`
- `packages/cli/src/commands/sync.ts`
- `packages/cli/src/constants.ts`
- `packages/cli/src/integrations/write-project-skill.ts`
- `packages/cli/src/sharing/git-exclude.ts`
- `packages/core/package.json`
- `packages/core/src/config/bind-okignore-doc.ts`
- `packages/core/src/config/field-registry.ts`
- `packages/core/src/config/merge-layered.ts`
- `packages/core/src/config/schema-version.ts`
- `packages/core/src/config/schema.ts`
- `packages/core/src/config/validate-patch-scopes.ts`
- `packages/core/src/frontmatter/tags.ts`
- `packages/core/src/markdown/entity-ref-guard.ts`
- `packages/core/src/protocol-version.ts`
- `packages/core/src/templates/template-format.ts`
- `packages/desktop/package.json`
- `packages/server/package.json`
- `packages/server/src/api-agent-write-summary.test.ts`
- `packages/server/src/api-config.test.ts`
- `packages/server/src/api-extension.ok-init.test.ts`
- `packages/server/src/api-extension.ts`
- `packages/server/src/api-search-semantic.test.ts`
- `packages/server/src/api-search.test.ts`
- `packages/server/src/github-permissions.ts`
- `packages/server/src/handoff-api.ts`
- `packages/server/src/index.ts`
- `packages/server/src/init-project.ts`
- `packages/server/src/mcp/agent-identity.ts`
- `packages/server/src/mcp/tools/checkpoint.ts`
- `packages/server/src/mcp/tools/conflicts.ts`
- `packages/server/src/mcp/tools/consolidate-body.ts`
- `packages/server/src/mcp/tools/discover-body.ts`
- `packages/server/src/mcp/tools/edit.ts`
- `packages/server/src/mcp/tools/exec.ts`
- `packages/server/src/mcp/tools/history.ts`
- `packages/server/src/mcp/tools/index.ts`
- `packages/server/src/mcp/tools/ingest-body.ts`
- `packages/server/src/mcp/tools/links.ts`
- `packages/server/src/mcp/tools/palette.ts`
- `packages/server/src/mcp/tools/research-body.ts`
- `packages/server/src/mcp/tools/resolve-conflict.ts`
- `packages/server/src/mcp/tools/search.ts`
- `packages/server/src/mcp/tools/share-link.ts`
- `packages/server/src/mcp/tools/shared.ts`
- `packages/server/src/mcp/tools/verb-schemas.ts`
- `packages/server/src/mcp/tools/workflow.ts`
- `packages/server/src/mcp/tools/write.ts`
- `packages/server/src/share/construct-url.ts`
- `packages/server/src/share/publish.ts`
- `README.md`