diff --git a/.env.example b/.env.example index c19707406..00bb73487 100644 --- a/.env.example +++ b/.env.example @@ -1,4 +1,4 @@ -# Open Knowledge environment variables. +# OpenKnowledge environment variables. # # All variables are OPTIONAL. A fresh clone runs end-to-end with no .env file: # diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dfd170db0..b930fe844 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to Open Knowledge +# Contributing to OpenKnowledge -Open Knowledge is developed in Inkeep's internal monorepo and mirrored to this public repository with Copybara. Public contributions should still start here: open a pull request against `inkeep/open-knowledge`. +OpenKnowledge is developed in Inkeep's internal monorepo and mirrored to this public repository with Copybara. Public contributions should still start here: open a pull request against `inkeep/open-knowledge`. ## How Public PRs Flow @@ -42,7 +42,7 @@ bun run dev ### Environment Variables -Open Knowledge requires no environment variables for development — `bun install && bun run check` works in a fresh clone. To start the dev server, see the commands above. See `.env.example` for optional dev/observability env vars (OpenTelemetry, custom dev server port). +OpenKnowledge requires no environment variables for development — `bun install && bun run check` works in a fresh clone. To start the dev server, see the commands above. See `.env.example` for optional dev/observability env vars (OpenTelemetry, custom dev server port). ### Toolchain @@ -91,4 +91,4 @@ Only source code, public docs, and build or development scripts are exported her ## License -Open Knowledge is licensed under the [GNU General Public License v3.0 or later](./LICENSE) (`GPL-3.0-or-later`). By submitting a contribution, you agree that it is licensed under the same terms. +OpenKnowledge is licensed under the [GNU General Public License v3.0 or later](./LICENSE) (`GPL-3.0-or-later`). By submitting a contribution, you agree that it is licensed under the same terms. diff --git a/README.md b/README.md index 3a4d51e8c..4fd18224a 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ -# Open Knowledge +# OpenKnowledge -Open Knowledge is a local-first knowledge base for teams that want docs, help-center content, SOPs, and agent-facing knowledge to live in one structured editing system. +OpenKnowledge is a beautiful, local-first markdown editor and LLM wiki with integrations for Claude, Codex, and Cursor. -The project includes a desktop app, web app, server, CLI, shared core packages, and docs site. It uses Bun workspaces and Turbo for builds. +The editor has full WYSWIG so that editing markdown feels like editing a Google Doc or Notion page. + +Sharing and auto-sync are available for team-based collaboration are powered by git. ## Install @@ -17,17 +19,13 @@ ok init # scaffold the project + wire up Claude Code, Cursor, and Codex ok start --open # serve the editor and open it in your browser ``` -Full documentation: . - -The sections below are for **contributing to** Open Knowledge. - -## Repository Model +Docs for general usage: . -This public repository is mirrored from Inkeep's internal monorepo with Copybara. The internal source path is `public/open-knowledge/` in `inkeep/agents-private`. +## Contributions -Public pull requests are welcome. When a public PR opens here, automation mirrors it into the internal monorepo for review and merge. After the internal PR lands, Copybara syncs the accepted change back to this repository. +Public pull requests are welcome. When a public PR opens here, automation mirrors it into the internal monorepo for review and merge. -See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full contribution flow and [AGENTS.md](./AGENTS.md) for agent-facing development guidance. +See [CONTRIBUTING.md](./CONTRIBUTING.md) for details. ## Prerequisites @@ -79,4 +77,4 @@ bun run build ## License -Open Knowledge is licensed under the [GNU General Public License v3.0 or later](./LICENSE) (`GPL-3.0-or-later`). +OpenKnowledge is licensed under the [GNU General Public License v3.0 or later](./LICENSE) (`GPL-3.0-or-later`). diff --git a/docs/content/advanced/folders-and-templates.mdx b/docs/content/advanced/folders-and-templates.mdx index e76721239..cf7c5cd54 100644 --- a/docs/content/advanced/folders-and-templates.mdx +++ b/docs/content/advanced/folders-and-templates.mdx @@ -3,13 +3,13 @@ title: Folders and templates description: Describe a folder with its own properties, and offer reusable templates that give new documents their starting content and properties. --- -Folders organize a project the same way they do on your computer: a place to group related docs. Open Knowledge adds two things on top: a folder can **describe itself** (its own properties, exactly like a document's), and it can offer a set of **templates** for new documents. +Folders organize a project the same way they do on your computer: a place to group related docs. OpenKnowledge adds two things on top: a folder can **describe itself** (its own properties, exactly like a document's), and it can offer a set of **templates** for new documents. Click any folder in the sidebar to open its **overview**: a page listing what's inside, plus two cards: **Folder properties** and **Templates available**. ## Properties, in one minute -Every doc can carry a bit of structured information at the top: a `status`, an `owner`, a `tags` list, a date. Open Knowledge calls these its **properties**. In the raw markdown file they live in a `---`-fenced block at the very top, which markdown tools call *frontmatter*; the **Properties** panel in the editor edits them as ordinary form fields, so you never touch that block by hand. See [Editor → Properties](/docs/features/editor#properties) for the basics. +Every doc can carry a bit of structured information at the top: a `status`, an `owner`, a `tags` list, a date. OpenKnowledge calls these its **properties**. In the raw markdown file they live in a `---`-fenced block at the very top, which markdown tools call *frontmatter*; the **Properties** panel in the editor edits them as ordinary form fields, so you never touch that block by hand. See [Editor → Properties](/docs/features/editor#properties) for the basics. A doc's properties are its own: exactly what's written in that file, nothing injected from elsewhere. The tedious part is setting the same starting properties on every new doc in a folder, which is what **templates** solve (below). @@ -71,7 +71,7 @@ Recorded by {{user}} ## Blockers ``` -These two are the only placeholders Open Knowledge fills in. Any other `{{...}}` is rejected when the template is saved, so a template never quietly grows its own mini-language. +These two are the only placeholders OpenKnowledge fills in. Any other `{{...}}` is rejected when the template is saved, so a template never quietly grows its own mini-language. ### Give new documents their own properties @@ -96,9 +96,9 @@ tags: [daily] (...) ``` -The `template:` block is the template's own info (the name and description shown in the picker); Open Knowledge strips it when a document is created. Every other key — `type`, `description`, `title`, `status`, `tags` above — becomes the new document's own properties, written as real bytes into the file. `description` gives each new document a starting one-line summary; edit it per document. Because these are the new doc's *own* properties, the doc owns them outright: editing one doc never touches another. +The `template:` block is the template's own info (the name and description shown in the picker); OpenKnowledge strips it when a document is created. Every other key — `type`, `description`, `title`, `status`, `tags` above — becomes the new document's own properties, written as real bytes into the file. `description` gives each new document a starting one-line summary; edit it per document. Because these are the new doc's *own* properties, the doc owns them outright: editing one doc never touches another. -(Older templates that used two stacked frontmatter blocks still work — Open Knowledge reads them and rewrites them to the single-block form the next time they're saved.) +(Older templates that used two stacked frontmatter blocks still work — OpenKnowledge reads them and rewrites them to the single-block form the next time they're saved.) ### Edit and delete @@ -108,7 +108,7 @@ Deleting a template removes the `.ok/templates/.md` file. Folders and agen ## How templates reach subfolders -Templates flow **downhill**: a template on `posts/` applies to `posts/`, `posts/2026/`, `posts/2026/drafts/`, and every folder beneath it. When you create a document, Open Knowledge starts at the document's own folder and walks up to the top of the project, gathering the templates each folder along the way offers: +Templates flow **downhill**: a template on `posts/` applies to `posts/`, `posts/2026/`, `posts/2026/drafts/`, and every folder beneath it. When you create a document, OpenKnowledge starts at the document's own folder and walks up to the top of the project, gathering the templates each folder along the way offers: - Templates from the document's **own folder** are marked **local**. - Templates from a **folder above it** are marked **inherited**. @@ -125,7 +125,7 @@ Agents create documents from templates the same way you do. Through MCP, an agen write({ document: { path: "posts/launch", template: "blog-post" } }) ``` -Open Knowledge finds the `blog-post` template the same way the New File dialog does: the agent gets the one that applies to `posts/`. The template's **starter content** becomes the new document; the template's own name and description stay behind as template info and are not copied into the document. +OpenKnowledge finds the `blog-post` template the same way the New File dialog does: the agent gets the one that applies to `posts/`. The template's **starter content** becomes the new document; the template's own name and description stay behind as template info and are not copied into the document. This is why a template's **Name** matters: it is the label an agent reads when choosing which template fits the document it is about to create. diff --git a/docs/content/features/assets-and-embeds.mdx b/docs/content/features/assets-and-embeds.mdx index 9d33d3360..48f455726 100644 --- a/docs/content/features/assets-and-embeds.mdx +++ b/docs/content/features/assets-and-embeds.mdx @@ -3,11 +3,11 @@ title: Assets and embeds description: Drop files into the editor and reference them with wiki-style embeds. --- -Open Knowledge treats assets (images, PDFs, video, audio) as first-class content alongside markdown. This page covers how asset references behave when shared outside the editor. +OpenKnowledge treats assets (images, PDFs, video, audio) as first-class content alongside markdown. This page covers how asset references behave when shared outside the editor. ## Sharing across apps -Local-path images (`![chart](./Q3-sales.png)`), wiki-embeds (`![[diagram.png]]`), and any other reference whose URL only resolves on your machine cannot render in apps that don't have access to your filesystem. When you copy a section containing one of these and paste into Gmail, Outlook, Notion, Slack, Discord, or Google Docs, Open Knowledge degrades visibly instead of silently: +Local-path images (`![chart](./Q3-sales.png)`), wiki-embeds (`![[diagram.png]]`), and any other reference whose URL only resolves on your machine cannot render in apps that don't have access to your filesystem. When you copy a section containing one of these and paste into Gmail, Outlook, Notion, Slack, Discord, or Google Docs, OpenKnowledge degrades visibly instead of silently: - **Non-portable URLs surface as a styled code block.** Recipients see the literal markdown source (e.g. `![chart](./Q3-sales.png)`) in monospace, not a broken-image icon. They can read what the section was meant to include and ask for the file or accept the textual reference. - **Inline images in paragraphs surface as inline source.** A paragraph with a local-path image keeps its prose flow; only the `` collapses to inline source markup, and the surrounding sentence is unaffected. @@ -16,7 +16,7 @@ Local-path images (`![chart](./Q3-sales.png)`), wiki-embeds (`![[diagram.png]]`) Two affordances are preserved across the cross-app boundary, not degradations themselves: - **Markdown-aware destinations get the source.** Linear, Outline, Obsidian, and similar apps that read `text/plain` first receive clean canonical markdown; the cross-app degradation only affects the `text/html` payload that destinations like Gmail render. -- **Open Knowledge → Open Knowledge paste round-trips faithfully.** Copying out of one Open Knowledge doc and pasting into another preserves the original markdown image / wiki-link / wiki-embed shape, because the cross-app degradation only fires when the receiving app reads `text/html` instead of `text/plain`. +- **OpenKnowledge → OpenKnowledge paste round-trips faithfully.** Copying out of one OpenKnowledge doc and pasting into another preserves the original markdown image / wiki-link / wiki-embed shape, because the cross-app degradation only fires when the receiving app reads `text/html` instead of `text/plain`. Source-mode copy (the CodeMirror toggle) works the same way: the clipboard's `text/html` payload is always a styled code block of the raw markdown bytes, never the rendered output. Pasting a `# Heading` from source-mode into Gmail produces a code block, not a rendered heading. This is consistent with VS Code, Obsidian source mode, GitHub textareas, and CodeMirror itself. diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdx index 7b4105a62..e13a75550 100644 --- a/docs/content/features/editor.mdx +++ b/docs/content/features/editor.mdx @@ -1,6 +1,6 @@ --- title: Editor -description: The Open Knowledge editor. WYSIWYG markdown, source toggle, content blocks, inline frontmatter, and the file sidebar. +description: The OpenKnowledge editor. WYSIWYG markdown, source toggle, content blocks, inline frontmatter, and the file sidebar. --- The editor is where you read, write, and collaborate on your docs, and where AI agents land when they edit. WYSIWYG by default with a source-mode toggle, a frontmatter properties pane, real-time CRDT collaboration, and a file sidebar that organizes the project. @@ -13,7 +13,7 @@ ok notes.md # open a single file in the editor ok ./specs/foo/SPEC.md # a file inside a project opens that project, focused on the doc ``` -When the file is inside an existing Open Knowledge project, this opens that project focused on the doc. When it's a loose file, it opens an **ephemeral single-file session**: a throwaway editor scoped to just that one file, with no project scaffolding, no agents, and no git. Your edits save straight back to the original file, and **nothing is written into the file's directory** — all session state lives in a temporary directory that's removed when you close the window. Opening a file you don't edit leaves it byte-for-byte unchanged. +When the file is inside an existing OpenKnowledge project, this opens that project focused on the doc. When it's a loose file, it opens an **ephemeral single-file session**: a throwaway editor scoped to just that one file, with no project scaffolding, no agents, and no git. Your edits save straight back to the original file, and **nothing is written into the file's directory** — all session state lives in a temporary directory that's removed when you close the window. Opening a file you don't edit leaves it byte-for-byte unchanged. It opens in the desktop app when it's installed, and falls back to your browser otherwise (press Ctrl-C in the terminal to end a browser session). Single-file sessions show just the file and the editor — no sidebar, tabs, or project switcher. Discover it any time with `ok --help`. @@ -53,7 +53,7 @@ Select text in the WYSIWYG editor and the selection bubble menu shows an **Ask A ## Properties -Every doc can carry a bit of structured information at the top: a `status`, an `owner`, a `tags` list, a date. Open Knowledge calls these its **properties**. +Every doc can carry a bit of structured information at the top: a `status`, an `owner`, a `tags` list, a date. OpenKnowledge calls these its **properties**. In the raw markdown file, these properties live in a fenced block at the very top of the file, between two `---` lines. Markdown tools call that block *frontmatter*: it's just a small chunk of YAML, the doc's "labels." You never have to write it by hand: the **Properties** panel on the right of the editor shows each field as an ordinary form input (text, number, checkbox, date, or list) and saves your changes back into the file. Edit the panel or the raw block in source mode; changes propagate live either way. @@ -112,7 +112,7 @@ On very large trees the disk walk is capped per level, and the sidebar shows a n ### Open with AI -**Open with AI ▸** dispatches the project, the folder, or the file to one of your installed agent apps (Claude, Codex, or Cursor). The agent receives a short text prompt asking it to open the target in the Open Knowledge web preview, then grounds the rest of the conversation via the [Open Knowledge MCP](/docs/reference/mcp). Three scopes, three prompt shapes: +**Open with AI ▸** dispatches the project, the folder, or the file to one of your installed agent apps (Claude, Codex, or Cursor). The agent receives a short text prompt asking it to open the target in the OpenKnowledge web preview, then grounds the rest of the conversation via the [OpenKnowledge MCP](/docs/reference/mcp). Three scopes, three prompt shapes: | Scope | Triggered from | Prompt template | | --- | --- | --- | @@ -130,13 +130,13 @@ The Claude **claude.ai** web fallback row appears on file-scope dispatches only; See the [per-integration pages](/docs/integrations/claude-code) for what each agent receives once dispatched. -The menu is organized into two sections. **Desktop** lists the installed agent apps (Claude, Codex, Cursor); selecting one launches it via its deep link. **Terminal** (desktop app only) adds a row for each CLI — **Claude**, **Codex**, and **Cursor** — that runs the corresponding CLI (`claude`, `codex`, `cursor`) in Open Knowledge's docked terminal with the same scoped prompt. Because both sections can list the same name, a Desktop **Claude** (the app) and a Terminal **Claude** (the CLI) can appear together; screen readers tell them apart by the Terminal row's "Claude CLI" accessible name (and likewise "Codex CLI" / "Cursor CLI"). Each section renders only when it has something to launch, so on the web build — which has no docked terminal — the Terminal section is absent and a CLI pick falls back to the first installed Desktop app target. +The menu is organized into two sections. **Desktop** lists the installed agent apps (Claude, Codex, Cursor); selecting one launches it via its deep link. **Terminal** (desktop app only) adds a row for each CLI — **Claude**, **Codex**, and **Cursor** — that runs the corresponding CLI (`claude`, `codex`, `cursor`) in OpenKnowledge's docked terminal with the same scoped prompt. Because both sections can list the same name, a Desktop **Claude** (the app) and a Terminal **Claude** (the CLI) can appear together; screen readers tell them apart by the Terminal row's "Claude CLI" accessible name (and likewise "Codex CLI" / "Cursor CLI"). Each section renders only when it has something to launch, so on the web build — which has no docked terminal — the Terminal section is absent and a CLI pick falls back to the first installed Desktop app target. The empty-state create composer on a fresh project carries the same Desktop / Terminal split: its Desktop rows pick the default agent the **Create** button uses, while its Terminal **Claude** row (desktop only, disabled until the workspace resolves) launches the `claude` CLI with the brief you typed. ### Open in Terminal -Spawns `open -a Terminal.app ` at the right path: the folder for a folder row, the file's parent for a file row, the project root for the empty-space menu, the parent dir for an asset row. Terminal.app is hardcoded for v1; user-configurable terminal preference is on the roadmap. This is distinct from the **Terminal** section inside **Open with AI**, which runs a CLI (`claude`, `codex`, or `cursor`) in Open Knowledge's docked terminal rather than opening Terminal.app. +Spawns `open -a Terminal.app ` at the right path: the folder for a folder row, the file's parent for a file row, the project root for the empty-space menu, the parent dir for an asset row. Terminal.app is hardcoded for v1; user-configurable terminal preference is on the roadmap. This is distinct from the **Terminal** section inside **Open with AI**, which runs a CLI (`claude`, `codex`, or `cursor`) in OpenKnowledge's docked terminal rather than opening Terminal.app. ## Sidebars and window width @@ -144,9 +144,9 @@ The editor has two sidebars: the file sidebar on the left and the document panel - At comfortable widths (about 1024px and up) both sidebars open by default. - Below that, both default to collapsed so the editor canvas isn't squeezed off-screen. -- When Open Knowledge is opened inside an AI editor's webview (Cursor, Codex, Claude Desktop), both sidebars start collapsed regardless of width; the embedded view is for reading the content you were sent, not for file management. +- When OpenKnowledge is opened inside an AI editor's webview (Cursor, Codex, Claude Desktop), both sidebars start collapsed regardless of width; the embedded view is for reading the content you were sent, not for file management. -The defaults only apply until you toggle. Open Knowledge remembers your most recent Show / Hide for each sidebar in your browser and survives reloads. When you come back to the same layout context (narrow window, comfortable window, or embedded view) you used last, your toggle is what you'll see. Toggling in a different context replaces that memory; only your most recent choice sticks, so a stale preference from a wide-monitor session can't quietly override what you just chose on a narrow screen. +The defaults only apply until you toggle. OpenKnowledge remembers your most recent Show / Hide for each sidebar in your browser and survives reloads. When you come back to the same layout context (narrow window, comfortable window, or embedded view) you used last, your toggle is what you'll see. Toggling in a different context replaces that memory; only your most recent choice sticks, so a stale preference from a wide-monitor session can't quietly override what you just chose on a narrow screen. Keyboard shortcuts (use `Ctrl` on Windows / Linux in place of `Cmd`): @@ -157,11 +157,11 @@ Keyboard shortcuts (use `Ctrl` on Windows / Linux in place of `Cmd`): In the desktop app the same actions live in the **View** menu (see below) and each menu label flips between **Show …** and **Hide …** based on current state, matching Finder. -Inside an AI editor's embedded view, the **Open with AI** menus, the bottom Ask AI composer, and the empty-state agent grid are hidden; you're already inside an agent, so the handoff would loop back into the same surface. Open Knowledge's MCP tools and the document itself stay fully available; only the launchers are gone. +Inside an AI editor's embedded view, the **Open with AI** menus, the bottom Ask AI composer, and the empty-state agent grid are hidden; you're already inside an agent, so the handoff would loop back into the same surface. OpenKnowledge's MCP tools and the document itself stay fully available; only the launchers are gone. ## macOS application menus -The Open Knowledge desktop app keeps its menu bar in sync with the active editor target: File menu items enable / disable based on whether a doc, folder, or nothing is currently selected. +The OpenKnowledge desktop app keeps its menu bar in sync with the active editor target: File menu items enable / disable based on whether a doc, folder, or nothing is currently selected. ### File menu diff --git a/docs/content/features/github-sync.mdx b/docs/content/features/github-sync.mdx index f09a55585..fe0f54927 100644 --- a/docs/content/features/github-sync.mdx +++ b/docs/content/features/github-sync.mdx @@ -2,15 +2,15 @@ title: GitHub sync description: Clone repos from GitHub, auto-sync changes with your team, and resolve conflicts. --- -Open Knowledge can connect a project to a GitHub remote repository and keep it synced over time. When GitHub sync is enabled, Open Knowledge actively pulls commits from the remote and pushes commits back. +OpenKnowledge can connect a project to a GitHub remote repository and keep it synced over time. When GitHub sync is enabled, OpenKnowledge actively pulls commits from the remote and pushes commits back. - Only enable GitHub sync for repositories where you are comfortable with Open Knowledge writing commits to the remote history. If you are worried about automated commits corrupting or cluttering your Git history, do not enable sync for that repository. + Only enable GitHub sync for repositories where you are comfortable with OpenKnowledge writing commits to the remote history. If you are worried about automated commits corrupting or cluttering your Git history, do not enable sync for that repository. ## What GitHub sync is for -Use GitHub sync when you want to collaborate with your team on an Open Knowledge project. +Use GitHub sync when you want to collaborate with your team on an OpenKnowledge project. It helps you: @@ -30,7 +30,7 @@ It helps you: ### Sign into GitHub - If you are already signed in with the GitHub CLI, Open Knowledge will use those credentials by default. If not, click **Sign into GitHub** and complete the device authentication flow. + If you are already signed in with the GitHub CLI, OpenKnowledge will use those credentials by default. If not, click **Sign into GitHub** and complete the device authentication flow. @@ -48,7 +48,7 @@ It helps you: ## Publish a local project -You can publish your local project to GitHub directly from the Open Knowledge app by opening a folder or file and clicking the **Share** button in the top right of the editor. +You can publish your local project to GitHub directly from the OpenKnowledge app by opening a folder or file and clicking the **Share** button in the top right of the editor. This will open a dialog where you can choose an owner and repository name. You can also choose to make the repository public or private. @@ -56,7 +56,7 @@ This will open a dialog where you can choose an owner and repository name. You c When you open a freshly cloned project, you will be prompted to enable sync. You can also toggle it from the project settings page at any time. -While sync is active, Open Knowledge: +While sync is active, OpenKnowledge: - Fetches commits from the remote - Commits your edits locally using the configured Git identity @@ -68,9 +68,9 @@ If you want to set a default auto-sync setting for future collaborators, go to t ## Authentication -If you are logged in with the GitHub CLI, Open Knowledge will use those credentials for GitHub operations. If not, you can complete device authentication to generate an OAuth token. Open Knowledge stores this token in the keychain and reuses it for syncing, cloning, and publishing. +If you are logged in with the GitHub CLI, OpenKnowledge will use those credentials for GitHub operations. If not, you can complete device authentication to generate an OAuth token. OpenKnowledge stores this token in the keychain and reuses it for syncing, cloning, and publishing. -Manage the connection from **Settings → Account**. **Connect GitHub** authorizes Open Knowledge to browse and sync your repositories; **Disconnect** clears Open Knowledge's GitHub token only. +Manage the connection from **Settings → Account**. **Connect GitHub** authorizes OpenKnowledge to browse and sync your repositories; **Disconnect** clears OpenKnowledge's GitHub token only. The sync status indicator surfaces an auth-error state when stored credentials stop working, and sync pauses until you reconnect. @@ -80,7 +80,7 @@ The sync status indicator in the editor shows the current state of the connectio ## Resolving a conflict -When a remote update conflicts with your local edits, Open Knowledge surfaces the conflict in three places at once: the conflicted file gains a `⚠` badge on its tab, a pinned **Conflicts** section appears at the top of the file tree listing every conflicted file, and the editor area swaps from the normal editor to a unified diff view. +When a remote update conflicts with your local edits, OpenKnowledge surfaces the conflict in three places at once: the conflicted file gains a `⚠` badge on its tab, a pinned **Conflicts** section appears at the top of the file tree listing every conflicted file, and the editor area swaps from the normal editor to a unified diff view. Click the badged tab or any row in the Conflicts section to focus the conflict. @@ -94,21 +94,21 @@ A few situations stop sync from completing successfully. In each case the sync s - **Unresolved conflicts.** If even one file has a conflict between your edits and your team's, sync waits. You can keep working on every other doc; only the conflicted files are frozen until you choose a side from the diff view. See [Resolving a conflict](#resolving-a-conflict) above. - **Local changes would be overwritten by an incoming update.** A teammate's update is ready to pull, but you have uncommitted local edits to the same file. Sync pauses rather than clobber your work. Commit or discard the in-progress edit from the editor's git surface and sync resumes. -- **Edits made outside the app aren't ready yet.** If you (or another tool) edited a file directly on disk while sync wanted to merge, Open Knowledge waits until those external edits settle before merging. Usually this clears in a second or two on its own. +- **Edits made outside the app aren't ready yet.** If you (or another tool) edited a file directly on disk while sync wanted to merge, OpenKnowledge waits until those external edits settle before merging. Usually this clears in a second or two on its own. ### Project isn't on a normal branch - **The project is parked on a specific commit, not a branch.** This usually means someone checked out an older commit from the terminal to look around. There's no branch to push to, so sync pauses. Switch back to your normal branch (`main`, your working branch, whichever) and sync resumes. -- **Diverged history.** When the remote has been rewritten (force-push, rebase, branch reset) in a way Open Knowledge can't reconcile automatically, sync stops and shows the error. This one usually needs a fix from the command line. Ask whoever rewrote the history, or restore from the [Timeline](/docs/features/timeline-and-recovery). +- **Diverged history.** When the remote has been rewritten (force-push, rebase, branch reset) in a way OpenKnowledge can't reconcile automatically, sync stops and shows the error. This one usually needs a fix from the command line. Ask whoever rewrote the history, or restore from the [Timeline](/docs/features/timeline-and-recovery). ### GitHub-side blockers - **Authentication errors.** Your stored credentials expired, were revoked, or don't have access to this repository anymore. Reconnect from the sync indicator (or from **Settings → Account**) to clear the error. -- **You don't have permission to push to this repo.** Someone shared a project backed by a GitHub repo where your account isn't a collaborator (or has read-only access on a private repo). Open Knowledge checks this up front: instead of prompting you to enable sync that would just fail, the toggle is disabled with an inline "You don't have permission to push to this repo" message in both the sync indicator popover and **Settings → Sync**. If you had sync enabled on a different repo and switch to one you can't push to, Open Knowledge pauses sync in-memory rather than mutating your preference; your `Auto-sync: on` setting is preserved for the next repo you have full access to. Ask the project owner for write access, then click sync to re-check. -- **Protected branches and rejected pushes.** If the target branch requires reviews, signed commits, or status checks, GitHub rejects the push. Open Knowledge turns sync off automatically so it stops retrying. Switch to a branch you can push to, or use a pull request for the protected branch instead. +- **You don't have permission to push to this repo.** Someone shared a project backed by a GitHub repo where your account isn't a collaborator (or has read-only access on a private repo). OpenKnowledge checks this up front: instead of prompting you to enable sync that would just fail, the toggle is disabled with an inline "You don't have permission to push to this repo" message in both the sync indicator popover and **Settings → Sync**. If you had sync enabled on a different repo and switch to one you can't push to, OpenKnowledge pauses sync in-memory rather than mutating your preference; your `Auto-sync: on` setting is preserved for the next repo you have full access to. Ask the project owner for write access, then click sync to re-check. +- **Protected branches and rejected pushes.** If the target branch requires reviews, signed commits, or status checks, GitHub rejects the push. OpenKnowledge turns sync off automatically so it stops retrying. Switch to a branch you can push to, or use a pull request for the protected branch instead. - **Missing Git identity.** Commits need a name and email attached. The status indicator prompts you to set one the first time sync needs to commit. ### Temporary problems -- **Network or service hiccups.** Flaky Wi-Fi, a VPN drop, or a brief GitHub outage. Open Knowledge keeps retrying in the background; no action needed unless the issue lasts long enough that you want to manually trigger a sync from the indicator. +- **Network or service hiccups.** Flaky Wi-Fi, a VPN drop, or a brief GitHub outage. OpenKnowledge keeps retrying in the background; no action needed unless the issue lasts long enough that you want to manually trigger a sync from the indicator. diff --git a/docs/content/features/ignore-patterns.mdx b/docs/content/features/ignore-patterns.mdx index e9dabe351..03e4bba7b 100644 --- a/docs/content/features/ignore-patterns.mdx +++ b/docs/content/features/ignore-patterns.mdx @@ -3,7 +3,7 @@ title: Ignore patterns description: Hide files and folders from the editor, search, and your AI agents. --- -Open Knowledge indexes the markdown in your project so it can power the file tree, search, and the tools your AI agents call. When you don't want a file in that picture (drafts, scratch notes, vendor-pasted material), hide it with an ignore pattern. Hidden items don't appear in the file tree, don't show up in search, and don't reach AI agents through MCP. Nothing on disk is deleted. +OpenKnowledge indexes the markdown in your project so it can power the file tree, search, and the tools your AI agents call. When you don't want a file in that picture (drafts, scratch notes, vendor-pasted material), hide it with an ignore pattern. Hidden items don't appear in the file tree, don't show up in search, and don't reach AI agents through MCP. Nothing on disk is deleted. ## Hide a file from the file tree @@ -57,15 +57,15 @@ drafts/ ## Where the patterns live -Patterns are stored in a `.okignore` file at your project root, alongside `.gitignore`. It's checked into version control and shared with anyone who clones the repo. Hand-edit it directly in any editor; Open Knowledge picks up changes the same way it picks up Settings edits. +Patterns are stored in a `.okignore` file at your project root, alongside `.gitignore`. It's checked into version control and shared with anyone who clones the repo. Hand-edit it directly in any editor; OpenKnowledge picks up changes the same way it picks up Settings edits. -Open Knowledge scaffolds a starter `.okignore` with a commented header the first time it sets up a project, so the file is there from day one. +OpenKnowledge scaffolds a starter `.okignore` with a commented header the first time it sets up a project, so the file is there from day one. ## Nested files Drop additional `.okignore` files at any folder depth. Each file scopes to its directory, the same way nested `.gitignore` files do. Nested files are honored at runtime but aren't currently editable from Settings; open them in your IDE. -If Open Knowledge can't reload your ignore files (rare; usually a filesystem error), it surfaces a toast with the path that triggered the reload. The workspace keeps using the previous patterns until the next change. +If OpenKnowledge can't reload your ignore files (rare; usually a filesystem error), it surfaces a toast with the path that triggered the reload. The workspace keeps using the previous patterns until the next change. ## Working with `.gitignore` @@ -75,9 +75,9 @@ If Open Knowledge can't reload your ignore files (rare; usually a filesystem err !secret.md ``` -`.gitignore` itself is git's contract; Open Knowledge never edits it. If you want a file out of git but visible in Open Knowledge, that's where the negation goes. +`.gitignore` itself is git's contract; OpenKnowledge never edits it. If you want a file out of git but visible in OpenKnowledge, that's where the negation goes. -The negation is an Open Knowledge behavior; `git` itself only reads `.gitignore`, so an `!` line in `.okignore` does not change what git tracks. +The negation is an OpenKnowledge behavior; `git` itself only reads `.gitignore`, so an `!` line in `.okignore` does not change what git tracks. ## Temporarily surfacing hidden files diff --git a/docs/content/features/share.mdx b/docs/content/features/share.mdx index e6af1982f..07b493e67 100644 --- a/docs/content/features/share.mdx +++ b/docs/content/features/share.mdx @@ -1,9 +1,9 @@ --- title: Share links -description: Copy a link to any doc or folder and send it to a teammate. Open Knowledge handles the GitHub round-trip, the deep link, and the branch on the other end. +description: Copy a link to any doc or folder and send it to a teammate. OpenKnowledge handles the GitHub round-trip, the deep link, and the branch on the other end. --- -Open Knowledge has a Share button in the editor toolbar. Click it and the app copies a `https://openknowledge.ai/d/…` URL to your clipboard. Anyone you send it to lands on a splash page that knows the project and target, and a single click opens it in their copy of Open Knowledge. +OpenKnowledge has a Share button in the editor toolbar. Click it and the app copies a `https://openknowledge.ai/d/…` URL to your clipboard. Anyone you send it to lands on a splash page that knows the project and target, and a single click opens it in their copy of OpenKnowledge. ## Sending a share link @@ -26,7 +26,7 @@ The recipient clicks the URL and lands on a splash page showing the target (file The splash offers two ways to receive: -- **Desktop app (macOS).** Click **Open in Open Knowledge** to fire the deep link into the Open Knowledge desktop app — on the shared doc, folder overview, or project root depending on what was shared. **Download for macOS** ships the arm64 DMG for recipients who don't yet have the app. +- **Desktop app (macOS).** Click **Open in OpenKnowledge** to fire the deep link into the OpenKnowledge desktop app — on the shared doc, folder overview, or project root depending on what was shared. **Download for macOS** ships the arm64 DMG for recipients who don't yet have the app. - **CLI (macOS and Linux).** Copy the pre-filled `npm install -g @inkeep/open-knowledge` then `ok clone -b ` from the splash to clone the repo locally and open the editor. The clone command is always branch-pinned, but if the feature branch has been deleted, it will fall back to the default branch. See the [CLI reference](/docs/reference/cli#clone-from-github) for `ok clone` and related commands. ## What the desktop app does when it receives the link @@ -46,6 +46,6 @@ If you have the repo open locally but on a different branch, the app falls throu ### Receiving without push permission -If the shared repo is one your GitHub account can't push to (you're not a collaborator on a public repo, or you have read-only access on a private one), Open Knowledge skips the usual "Enable auto-sync?" prompt. Sync is also disabled for the same reason in **Settings → Sync**. If the project owner grants you write access later, click the sync indicator to re-check; Open Knowledge will pick up the change without an app restart. See [GitHub sync: GitHub-side blockers](/docs/features/github-sync#github-side-blockers) for the full set of permission shapes the sync UI handles. +If the shared repo is one your GitHub account can't push to (you're not a collaborator on a public repo, or you have read-only access on a private one), OpenKnowledge skips the usual "Enable auto-sync?" prompt. Sync is also disabled for the same reason in **Settings → Sync**. If the project owner grants you write access later, click the sync indicator to re-check; OpenKnowledge will pick up the change without an app restart. See [GitHub sync: GitHub-side blockers](/docs/features/github-sync#github-side-blockers) for the full set of permission shapes the sync UI handles. See [GitHub sync](/docs/features/github-sync) for how to automatically sync changes to GitHub, and [Timeline and recovery](/docs/features/timeline-and-recovery) for per-doc history once the doc is open. diff --git a/docs/content/features/timeline-and-recovery.mdx b/docs/content/features/timeline-and-recovery.mdx index b1dc242ed..6707f6e1b 100644 --- a/docs/content/features/timeline-and-recovery.mdx +++ b/docs/content/features/timeline-and-recovery.mdx @@ -15,11 +15,11 @@ Timeline entries include: - **Agent and human edits** with contributor attribution and change summaries - **Upstream sync** entries from Git -- **File system** changes made outside of Open Knowledge +- **File system** changes made outside of OpenKnowledge ## Review changes -Click a timeline entry to expand it. Open Knowledge shows an inline diff so you can compare that version with the current document. If that version is the same as the current document, you will see `no changes`. +Click a timeline entry to expand it. OpenKnowledge shows an inline diff so you can compare that version with the current document. If that version is the same as the current document, you will see `no changes`. You can switch between unified and split diff layouts from the editor controls. @@ -27,4 +27,4 @@ You can switch between unified and split diff layouts from the editor controls. ## Restore a previous version -Use the restore button on a timeline entry to restore the document to the selected version. Restoring is append-only: Open Knowledge creates a new change with the old content instead of deleting history. +Use the restore button on a timeline entry to restore the document to the selected version. Restoring is append-only: OpenKnowledge creates a new change with the old content instead of deleting history. diff --git a/docs/content/get-started/overview.mdx b/docs/content/get-started/overview.mdx index 5d129e6e1..0eb071681 100644 --- a/docs/content/get-started/overview.mdx +++ b/docs/content/get-started/overview.mdx @@ -4,21 +4,21 @@ description: A markdown knowledge base your AI coding agents can read and edit, footer: false --- -Open Knowledge is a native macOS app for creating and maintaining a portable markdown knowledge base alongside the agents you already use. On Linux or an Intel Mac, the same editor runs as a local [web app](/docs/reference/cli) you launch from the terminal. It works with any MCP-capable agent. +OpenKnowledge is a native macOS app for creating and maintaining a portable markdown knowledge base alongside the agents you already use. On Linux or an Intel Mac, the same editor runs as a local [web app](/docs/reference/cli) you launch from the terminal. It works with any MCP-capable agent. ## Three layers -Open Knowledge is three layers working together: a surface you edit, an engine that keeps it consistent, and the files underneath. +OpenKnowledge is three layers working together: a surface you edit, an engine that keeps it consistent, and the files underneath. ## What you get - **Rich MDX editing.** Beyond plain markdown, the editor renders Mermaid diagrams, LaTeX math, YouTube, Vimeo, and Loom embeds, an in-browser PDF viewer, interactive HTML and JS previews for charts and custom widgets, callouts, collapsible sections, and live block transclusion. Toggle between WYSIWYG and source modes anytime. -- **First-class AI support, agent-agnostic.** Write collaboratively with the agent of your choice. Open Knowledge ships the toolset; you bring the agent and the model of your choice. -- **A knowledge base that gets stronger over time.** Reads and writes flow through the Open Knowledge toolset, so links, backlinks, frontmatter, and asset embeds stay consistent as your knowledge base grows. +- **First-class AI support, agent-agnostic.** Write collaboratively with the agent of your choice. OpenKnowledge ships the toolset; you bring the agent and the model of your choice. +- **A knowledge base that gets stronger over time.** Reads and writes flow through the OpenKnowledge toolset, so links, backlinks, frontmatter, and asset embeds stay consistent as your knowledge base grows. - **Track changes with edit level attribution.** Every edit, human or agent, is recorded on top of git, with per-document version history, point-in-time recovery, and automatic syncing for remote collaboration. ## Where to start diff --git a/docs/content/get-started/quickstart.mdx b/docs/content/get-started/quickstart.mdx index a1dea549b..d410e0a2b 100644 --- a/docs/content/get-started/quickstart.mdx +++ b/docs/content/get-started/quickstart.mdx @@ -8,7 +8,7 @@ description: Set up your agent-maintained knowledge base in less than five minut - **macOS on Apple Silicon** (M1 or later). - - **`git`.** Open Knowledge initializes a git repo for your project (used for the timeline and recovery features). Install from [git-scm.com](https://git-scm.com/install/mac). + - **`git`.** OpenKnowledge initializes a git repo for your project (used for the timeline and recovery features). Install from [git-scm.com](https://git-scm.com/install/mac). @@ -17,7 +17,7 @@ description: Set up your agent-maintained knowledge base in less than five minut ### Install the desktop app -Download the latest version of the Open Knowledge desktop app for macOS. +Download the latest version of the OpenKnowledge desktop app for macOS. @@ -27,7 +27,7 @@ Download the latest version of the Open Knowledge desktop app for macOS. ### Create a new project -- Open the Open Knowledge app and click **Create new project**. +- Open the OpenKnowledge app and click **Create new project**. - Type a name for your project (for example, *Team Wiki*). - Optionally click **Browse** to change where the project is saved, then click **Create**. @@ -54,7 +54,7 @@ Not sure what to write? Paste this into the composer (or use a topic of your cho Create a knowledge base about Large Language Models. Include an overview page and separate pages for three key concepts. - To avoid having to approve all Open Knowledge tool calls, set your agent to auto-mode, full-access, or an equivalent setting. + To avoid having to approve all OpenKnowledge tool calls, set your agent to auto-mode, full-access, or an equivalent setting. @@ -67,7 +67,7 @@ Not sure what to write? Paste this into the composer (or use a topic of your cho ### Watch your agent work -If you are working with Cursor, Codex or Claude Desktop, your agent will open the Open Knowledge editor in an embedded window. Otherwise, your agent will open the Open Knowledge editor in your system browser. +If you are working with Cursor, Codex or Claude Desktop, your agent will open the OpenKnowledge editor in an embedded window. Otherwise, your agent will open the OpenKnowledge editor in your system browser. You will see your agent's icon in the top right of the editor window. Click on the icon to see the agent's [activity](/docs/features/agent-activity) across files in the knowledge base. @@ -101,8 +101,8 @@ Right-click anywhere in the sidebar (empty space, a folder, or a file) to create - - **Node.js 24+.** Open Knowledge requires Node.js 24 or higher. Download from [nodejs.org](https://nodejs.org/en/download/). - - **`git`.** Open Knowledge initializes a git repo for your project (used for the timeline and recovery features). Install it from [git-scm.com](https://git-scm.com) or your package manager. + - **Node.js 24+.** OpenKnowledge requires Node.js 24 or higher. Download from [nodejs.org](https://nodejs.org/en/download/). + - **`git`.** OpenKnowledge initializes a git repo for your project (used for the timeline and recovery features). Install it from [git-scm.com](https://git-scm.com) or your package manager. @@ -132,14 +132,14 @@ ok start --open ### Open the knowledge base in your AI agent -`ok init` already registered Open Knowledge with the AI editors it detected, so your agent can use the Open Knowledge tools right away. Open your project in your agent — or, from the editor, right-click the project in the sidebar, choose **Open with AI ▸**, and pick one. (The bottom **Ask AI** field is available in the desktop app only.) +`ok init` already registered OpenKnowledge with the AI editors it detected, so your agent can use the OpenKnowledge tools right away. Open your project in your agent — or, from the editor, right-click the project in the sidebar, choose **Open with AI ▸**, and pick one. (The bottom **Ask AI** field is available in the desktop app only.) In the agent's chat window, add the following to get started or use a topic of your choice: Create a knowledge base about Large Language Models. Include an overview page and separate pages for three key concepts. - To avoid having to approve all Open Knowledge tool calls, set your agent to auto-mode, full-access, or an equivalent setting. + To avoid having to approve all OpenKnowledge tool calls, set your agent to auto-mode, full-access, or an equivalent setting. @@ -187,4 +187,4 @@ Right-click anywhere in the sidebar (empty space, a folder, or a file) to create - Syncing your knowledge base to GitHub: [Syncing](/docs/features/github-sync) - Define folders and templates: [Folders and templates](/docs/advanced/folders-and-templates) -- Configure Open Knowledge: [Configuration](/docs/reference/configuration) +- Configure OpenKnowledge: [Configuration](/docs/reference/configuration) diff --git a/docs/content/integrations/claude-code.mdx b/docs/content/integrations/claude-code.mdx index 30ddf4985..605cffa96 100644 --- a/docs/content/integrations/claude-code.mdx +++ b/docs/content/integrations/claude-code.mdx @@ -1,9 +1,9 @@ --- title: Claude -description: Use Open Knowledge with Claude Code, in the CLI or the Claude Desktop app. +description: Use OpenKnowledge with Claude Code, in the CLI or the Claude Desktop app. --- -Open Knowledge works with Claude Code through MCP plus an installed skill that teaches the agent how to use the tools. Both surfaces are supported: +OpenKnowledge works with Claude Code through MCP plus an installed skill that teaches the agent how to use the tools. Both surfaces are supported: - **Claude Code CLI** — the `claude` command in your terminal. - **Claude Desktop app** — Claude Code in the **Code** tab. @@ -12,13 +12,13 @@ Open Knowledge works with Claude Code through MCP plus an installed skill that t -If you installed the Open Knowledge desktop app from the macOS DMG, a consent dialog runs on first launch and offers to wire up the MCP-capable agents it detects, Claude Code included — click **Add**. To re-trigger it, delete `~/.ok/mcp-status.json` and relaunch. +If you installed the OpenKnowledge desktop app from the macOS DMG, a consent dialog runs on first launch and offers to wire up the MCP-capable agents it detects, Claude Code included — click **Add**. To re-trigger it, delete `~/.ok/mcp-status.json` and relaunch. ## Open with AI From the editor, **Open with AI ▸ Claude** dispatches the current file, folder, or project to Claude Code in one click. Two entry points: the sidebar's right-click menu (file / folder / empty space) and the macOS **File → Open with AI** menu. You can also hand the current doc to Claude from the bottom **Ask AI** composer. -Claude Code receives a short prompt asking it to open the target in Open Knowledge's web preview, then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX. +Claude Code receives a short prompt asking it to open the target in OpenKnowledge's web preview, then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX. ## Verify @@ -26,8 +26,8 @@ Open the project in Claude Code and ask: -If Claude Code doesn't use the Open Knowledge `exec` tool, restart it so it picks up the new MCP entry. +If Claude Code doesn't use the OpenKnowledge `exec` tool, restart it so it picks up the new MCP entry. ## Live editing -When Claude Code writes to a doc, you'll see the change land live in Open Knowledge. Just ask Claude Code to open it for you. +When Claude Code writes to a doc, you'll see the change land live in OpenKnowledge. Just ask Claude Code to open it for you. diff --git a/docs/content/integrations/codex.mdx b/docs/content/integrations/codex.mdx index b53376a97..6f4e6fb70 100644 --- a/docs/content/integrations/codex.mdx +++ b/docs/content/integrations/codex.mdx @@ -1,9 +1,9 @@ --- title: Codex -description: Use Open Knowledge with OpenAI Codex. +description: Use OpenKnowledge with OpenAI Codex. --- -Open Knowledge plugs into Codex through MCP. +OpenKnowledge plugs into Codex through MCP. ## Install @@ -13,7 +13,7 @@ Open Knowledge plugs into Codex through MCP. From the editor, **Open with AI ▸ Codex** dispatches the current file, folder, or project to Codex in one click. Two entry points: the sidebar's right-click menu (file / folder / empty space) and the macOS **File → Open with AI** menu. You can also hand the current doc to Codex from the bottom **Ask AI** composer. -Codex receives a short prompt asking it to open the target in Open Knowledge's web preview. The agent then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX. +Codex receives a short prompt asking it to open the target in OpenKnowledge's web preview. The agent then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX. ## Verify diff --git a/docs/content/integrations/cursor.mdx b/docs/content/integrations/cursor.mdx index beba804a2..c1111e0b4 100644 --- a/docs/content/integrations/cursor.mdx +++ b/docs/content/integrations/cursor.mdx @@ -1,9 +1,9 @@ --- title: Cursor -description: Use Open Knowledge with Cursor. +description: Use OpenKnowledge with Cursor. --- -Open Knowledge plugs into Cursor through MCP plus an installed skill that teaches the agent how to use the tools. +OpenKnowledge plugs into Cursor through MCP plus an installed skill that teaches the agent how to use the tools. ## Install @@ -17,7 +17,7 @@ Cursor prompts you to approve a new MCP server when you next open the project. A From the editor, **Open with AI ▸ Cursor** dispatches the current file, folder, or project to Cursor. Two entry points: the sidebar's right-click menu (file / folder / empty space) and the macOS **File → Open with AI** menu. You can also hand the current doc to Cursor from the bottom **Ask AI** composer. -Cursor uses a two-step handoff: Open Knowledge spawns `cursor ` to open the workspace first, then fires the `cursor://` URL with a short prompt asking Cursor to open the target in Open Knowledge's web preview. The agent then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX. +Cursor uses a two-step handoff: OpenKnowledge spawns `cursor ` to open the workspace first, then fires the `cursor://` URL with a short prompt asking Cursor to open the target in OpenKnowledge's web preview. The agent then grounds the rest of the conversation through MCP. See [Editor → Open with AI](/docs/features/editor#open-with-ai) for the full UX. In the web app, Cursor's spawn step runs through a local `POST /api/spawn-cursor` fallback, so the **Open with AI ▸ Cursor** row works there too — not just in the desktop app. diff --git a/docs/content/meta.json b/docs/content/meta.json index 017152b2f..dc80e05c1 100644 --- a/docs/content/meta.json +++ b/docs/content/meta.json @@ -1,5 +1,5 @@ { - "title": "Open Knowledge", + "title": "OpenKnowledge", "icon": "LuBookOpen", "pages": [ "---GET STARTED---", diff --git a/docs/content/reference/cli.mdx b/docs/content/reference/cli.mdx index 00dd10010..ad429d510 100644 --- a/docs/content/reference/cli.mdx +++ b/docs/content/reference/cli.mdx @@ -1,18 +1,18 @@ --- title: CLI & web app -description: Install the ok CLI and run the Open Knowledge web app in your browser — on Linux or an Intel Mac. +description: Install the ok CLI and run the OpenKnowledge web app in your browser — on Linux or an Intel Mac. --- On macOS, use the [desktop app](/docs/get-started/quickstart) for the smoothest experience. On **Linux** or an **Intel Mac**, install the `ok` CLI from npm and run the **same editor as a local web app** in your browser. - - **Node.js 24+.** Open Knowledge requires [Node.js](https://nodejs.org) 24 or higher. - - **`git`.** Open Knowledge initializes a git repo for your project (used for the timeline and recovery features). On macOS it comes with the Xcode Command Line Tools (`xcode-select --install`); on Linux, install it from [git-scm.com](https://git-scm.com) or your package manager. + - **Node.js 24+.** OpenKnowledge requires [Node.js](https://nodejs.org) 24 or higher. + - **`git`.** OpenKnowledge initializes a git repo for your project (used for the timeline and recovery features). On macOS it comes with the Xcode Command Line Tools (`xcode-select --install`); on Linux, install it from [git-scm.com](https://git-scm.com) or your package manager. ## Install -Install the Open Knowledge CLI globally to put `ok` on your `PATH`: +Install the OpenKnowledge CLI globally to put `ok` on your `PATH`: ```bash npm install -g @inkeep/open-knowledge @@ -20,7 +20,7 @@ npm install -g @inkeep/open-knowledge ## Set up a project -Run `ok init` in any folder to turn it into an Open Knowledge project. It scaffolds a `.ok/` directory and registers the Open Knowledge MCP server with the AI editors it detects on your machine (Claude Code, Cursor, Codex). +Run `ok init` in any folder to turn it into an OpenKnowledge project. It scaffolds a `.ok/` directory and registers the OpenKnowledge MCP server with the AI editors it detects on your machine (Claude Code, Cursor, Codex). ```bash cd my-project @@ -45,13 +45,13 @@ This opens your file directly in the WYSIWYG/source editor without any of the ve ## Clone from GitHub -You can pull repositories directly from GitHub and open them with Open Knowledge: +You can pull repositories directly from GitHub and open them with OpenKnowledge: ```bash ok clone ``` -`ok clone` accepts a full `https://github.com/...` URL or the `owner/repo` shorthand. It clones the repository, initializes Open Knowledge if it isn't already, and opens the editor. +`ok clone` accepts a full `https://github.com/...` URL or the `owner/repo` shorthand. It clones the repository, initializes OpenKnowledge if it isn't already, and opens the editor. Pin a branch with `-b `: @@ -76,7 +76,7 @@ Each project runs its own local server. These commands let you see and stop them | Command | What it does | | --- | --- | | `ok status` | Show whether a server and UI are running for the current project | -| `ok ps` | List every running Open Knowledge server on your machine | +| `ok ps` | List every running OpenKnowledge server on your machine | | `ok stop` | Stop the server for the current directory (or pass a port, a path, pid or `all` to stop all servers). | | `ok clean` | Remove stale lock files left behind by a crash (never touches live servers) | diff --git a/docs/content/reference/configuration.mdx b/docs/content/reference/configuration.mdx index f6fdeaaa2..ae82a52c1 100644 --- a/docs/content/reference/configuration.mdx +++ b/docs/content/reference/configuration.mdx @@ -3,7 +3,7 @@ title: Configuration description: The .ok/config.yml schema and environment variables. --- -Open Knowledge reads YAML config from three places: +OpenKnowledge reads YAML config from three places: - **Project**: `./.ok/config.yml` (this project, committed to git) - **User**: `~/.ok/global.yml` (every project on your machine) @@ -30,7 +30,7 @@ The **Scope** column says which file a setting belongs in: **project** → `.ok/ | `appearance.sidebar.showHiddenFiles` | boolean | `false` | project-local | Show files whose path segments start with `.`. The sidebar otherwise lists every file on disk under the content directory; tooling internals (`.git/`, `.ok/`, `node_modules/`) stay hidden regardless. Toggled from the sidebar's right-click menu or the macOS **View → Show Hidden Files** item. | | `autoSync.enabled` | `boolean \| null` | `null` | project-local | Per-machine git auto-sync toggle. `null` means "unanswered"; the editor's onboarding modal triggers on first remote-detected open. | | `editor.wordWrap` | boolean | `true` | user | Soft-wrap long lines in the source-mode CodeMirror editor. A personal preference, not project-shared. Toggle from the Settings pane. | -| `appearance.preview.autoOpen` | boolean | `true` | user | Whether the agent should open or refresh the Open Knowledge preview when it edits a doc through the MCP. Default `true` lets the agent route the preview by host capability: the host's in-app browser (Cursor preview pane, Codex's built-in browser, Claude Code Desktop) when one exists, the system browser otherwise. Set `false` to keep the agent's hands off your preview window. This is useful when you're already viewing the doc in OK Desktop, a browser tab on a second display, a non-default browser, or any flow where your extensions / accessibility tooling only work in your own browser. The agent then surfaces the URL on request but does not navigate. The change takes effect on the next preview-related tool call. Toggle from **Settings → Preferences → "Open preview when agent edits"**. | +| `appearance.preview.autoOpen` | boolean | `true` | user | Whether the agent should open or refresh the OpenKnowledge preview when it edits a doc through the MCP. Default `true` lets the agent route the preview by host capability: the host's in-app browser (Cursor preview pane, Codex's built-in browser, Claude Code Desktop) when one exists, the system browser otherwise. Set `false` to keep the agent's hands off your preview window. This is useful when you're already viewing the doc in OK Desktop, a browser tab on a second display, a non-default browser, or any flow where your extensions / accessibility tooling only work in your own browser. The agent then surfaces the URL on request but does not navigate. The change takes effect on the next preview-related tool call. Toggle from **Settings → Preferences → "Open preview when agent edits"**. | | `telemetry.localSink.enabled` | boolean | `true` | project | Write local diagnostic spans + logs under `.ok/local/` for `ok diagnose bundle` to collect. Local-only: nothing leaves the machine until you run `bundle`. Set `false` for sensitive workspaces. | | `telemetry.localSink.spans.maxBytes` | number | `52428800` (~50 MB) | project | Max size of the local diagnostic spans file before it rotates. | | `telemetry.localSink.logs.maxBytes` | number | `26214400` (~25 MB) | project | Max size of the local diagnostic logs file before it rotates. | diff --git a/docs/content/reference/core-concepts.md b/docs/content/reference/core-concepts.md index 461764c4b..312b68bf5 100644 --- a/docs/content/reference/core-concepts.md +++ b/docs/content/reference/core-concepts.md @@ -1,13 +1,13 @@ --- title: Core Concepts -description: "How Open Knowledge works: the three-layer model, the file system as the database, links and backlinks, the well-connected knowledge base, and attribution." +description: "How OpenKnowledge works: the three-layer model, the file system as the database, links and backlinks, the well-connected knowledge base, and attribution." --- This page is the precise reference for the ideas the rest of the docs build on. If you want the persuasive tour instead, start with the [Overview](../get-started/overview.mdx); if you want to start using it, see the [Quickstart](../get-started/quickstart.mdx). ## Three layers -Open Knowledge is three layers working together: a surface you edit, an engine that keeps it consistent, and the files underneath. +OpenKnowledge is three layers working together: a surface you edit, an engine that keeps it consistent, and the files underneath. @@ -27,7 +27,7 @@ Because the knowledge engine is exposed over [MCP](https://modelcontextprotocol. ## The file system is the database -The third layer is the content itself. Open Knowledge has **no database dependency**. Your knowledge base is plain markdown files in your own project directory, and the only persistence layer is the file system, version-controlled by git. +The third layer is the content itself. OpenKnowledge has **no database dependency**. Your knowledge base is plain markdown files in your own project directory, and the only persistence layer is the file system, version-controlled by git. This means: @@ -39,7 +39,7 @@ The set of files the engine treats as your knowledge base is the configured cont ## Links and backlinks -Internal cross-references are written with **standard markdown links**: `[text](./relative/path.md)` or `[text](/absolute/from/content-root.md)`. Whenever document A links to document B, Open Knowledge automatically records the inverse on B: a **backlink** from B back to A. +Internal cross-references are written with **standard markdown links**: `[text](./relative/path.md)` or `[text](/absolute/from/content-root.md)`. Whenever document A links to document B, OpenKnowledge automatically records the inverse on B: a **backlink** from B back to A. You never write backlinks by hand. They are computed from the links you already write, and together they form the **link graph**: the network of relationships across your knowledge base. @@ -75,12 +75,12 @@ Agents use these to repair and densify the graph as they work, instead of lettin Every factual claim should trace back to a source **inside** the knowledge base. External material is pulled in and cited locally rather than linked off to the open web, so the knowledge base stays self-contained and auditable. This is the backbone of the source-grounded workflows: see [Karpathy's LLM wiki workflow](../workflows/karpathy-llm-wiki.mdx) and the [Entity vault (GBrain-compatible) workflow](../workflows/entity-vault.mdx). - Open Knowledge is unopinionated about which workflow you adopt; these are supported patterns, not requirements. Grounding, backlinks, and the graph tools work the same regardless of how you choose to organize. + OpenKnowledge is unopinionated about which workflow you adopt; these are supported patterns, not requirements. Grounding, backlinks, and the graph tools work the same regardless of how you choose to organize. ## Attribution and collaboration -Every change made through Open Knowledge is tracked, with **attribution** to whoever made it: a human author or a specific AI agent. The change history is persisted in the file system with no dependency beyond git. +Every change made through OpenKnowledge is tracked, with **attribution** to whoever made it: a human author or a specific AI agent. The change history is persisted in the file system with no dependency beyond git. That gives you: diff --git a/docs/content/reference/mcp.mdx b/docs/content/reference/mcp.mdx index d0ef6be2f..ec9dc554b 100644 --- a/docs/content/reference/mcp.mdx +++ b/docs/content/reference/mcp.mdx @@ -1,9 +1,9 @@ --- title: MCP -description: Tools the Open Knowledge MCP server exposes to AI agents. +description: Tools the OpenKnowledge MCP server exposes to AI agents. --- -The MCP server gives AI agents structured access to your knowledge base. Two reads are server-free: `exec` (shell-style reads, fs-direct against the disk) and `preview_url` (reads `ui.lock` directly) both work even when the editor is down. Every other read tool (`search`, `links`, `history`, etc.) and all write tools route through the Hocuspocus server, which Open Knowledge starts for you on the first write. +The MCP server gives AI agents structured access to your knowledge base. Two reads are server-free: `exec` (shell-style reads, fs-direct against the disk) and `preview_url` (reads `ui.lock` directly) both work even when the editor is down. Every other read tool (`search`, `links`, `history`, etc.) and all write tools route through the Hocuspocus server, which OpenKnowledge starts for you on the first write. The surface is **17 tools**. Three of the four write verbs — `write`, `edit`, `delete` — are native CRUD operations polymorphic over a target (`document`, `folder`, `template`, `asset`): per-target fields nest inside the address key (`write({ document: { path, content } })`), and you pass exactly one target per call. `move` is the fourth write verb but takes flat `from`/`to` paths and auto-detects whether the path is a document, folder, or asset (no `template` target). diff --git a/docs/content/workflows/entity-vault.mdx b/docs/content/workflows/entity-vault.mdx index a877491c3..3d0f6c57b 100644 --- a/docs/content/workflows/entity-vault.mdx +++ b/docs/content/workflows/entity-vault.mdx @@ -1,6 +1,6 @@ --- title: Entity vault (GBrain-compatible) workflow -description: A GBrain-compatible Markdown workflow for people, companies, meetings, and concepts. Open Knowledge is the cockpit/editor/review layer; Garry Tan's gbrain can import or sync the same vault for indexing and automation. +description: A GBrain-compatible Markdown workflow for people, companies, meetings, and concepts. OpenKnowledge is the cockpit/editor/review layer; Garry Tan's gbrain can import or sync the same vault for indexing and automation. --- An **Entity vault (GBrain-compatible Markdown)** is a Markdown brain organized around typed dossiers: people, companies, meetings, concepts, originals, and media. Each durable dossier has two zones: @@ -8,7 +8,7 @@ An **Entity vault (GBrain-compatible Markdown)** is a Markdown brain organized a 1. **Compiled truth** — the current synthesis, rewritten as evidence changes. 2. **Timeline** — append-only evidence bullets, dated and attributable. -Open Knowledge scaffolds and edits that Markdown. Garry Tan's [`gbrain`](https://github.com/garrytan/gbrain), if you install it, can import/sync the same vault and add its DB-backed retrieval, graph extraction, embedding, and automation. OK does **not** replace `gbrain`; it gives GBrain-style Markdown brains a human cockpit for review, correction, attribution, and Git-visible edits. +OpenKnowledge scaffolds and edits that Markdown. Garry Tan's [`gbrain`](https://github.com/garrytan/gbrain), if you install it, can import/sync the same vault and add its DB-backed retrieval, graph extraction, embedding, and automation. OK does **not** replace `gbrain`; it gives GBrain-style Markdown brains a human cockpit for review, correction, attribution, and Git-visible edits. ## Who this is for @@ -19,7 +19,7 @@ Open Knowledge scaffolds and edits that Markdown. Garry Tan's [`gbrain`](https:/ ## The division of labor -| Layer | Open Knowledge | Garry Tan's `gbrain` | +| Layer | OpenKnowledge | Garry Tan's `gbrain` | | --- | --- | --- | | Markdown files | Creates, edits, reviews, templates, folder guidance | Imports/syncs as source material | | Human correction | WYSIWYG/source editor, activity attribution, version checkpoints | Sees corrections after import/sync | diff --git a/docs/content/workflows/karpathy-llm-wiki.mdx b/docs/content/workflows/karpathy-llm-wiki.mdx index 1a72fbb6f..fdacd6a95 100644 --- a/docs/content/workflows/karpathy-llm-wiki.mdx +++ b/docs/content/workflows/karpathy-llm-wiki.mdx @@ -3,14 +3,14 @@ title: Karpathy's LLM wiki workflow description: Build a source-grounded knowledge base where an LLM agent curates the wiki from the raw material you feed it. Every claim traces back to a preserved source. Maps directly to the Knowledge base starter pack. --- -A persistent, compounding knowledge base where you bring the raw material and the LLM does the summarization, cross-referencing, and maintenance. The pattern is Andrej Karpathy's, from [his April 2026 gist on LLM-curated wikis](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). Open Knowledge ships the **Knowledge base** starter pack as a direct implementation, with one extension Karpathy doesn't formalize: **the wiki layer is split** into `research/` (status: provisional) and `articles/` (status: canonical), with the `consolidate` workflow as the explicit promotion step, so premature canonicalization becomes a thing you opt into rather than something that drifts in. +A persistent, compounding knowledge base where you bring the raw material and the LLM does the summarization, cross-referencing, and maintenance. The pattern is Andrej Karpathy's, from [his April 2026 gist on LLM-curated wikis](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). OpenKnowledge ships the **Knowledge base** starter pack as a direct implementation, with one extension Karpathy doesn't formalize: **the wiki layer is split** into `research/` (status: provisional) and `articles/` (status: canonical), with the `consolidate` workflow as the explicit promotion step, so premature canonicalization becomes a thing you opt into rather than something that drifts in. -The point of this guide is to show how **Open Knowledge's features compose** to make the pattern feel native: the starter-pack picker scaffolds the layout in one click; per-folder templates + agent-readable folder frontmatter teach the LLM the conventions (Karpathy's centralized `CLAUDE.md` / `AGENTS.md` schema, distributed per-folder); the `workflow` tool's three pipeline kinds (`ingest`, `research`, `consolidate`) cover the sources → provisional → canonical pipeline; the WYSIWYG editor + CRDT keep editing frictionless; the activity panel attributes every write; the `links` tool keeps the source graph clean. Every step uses three or four of these together. That's the product. +The point of this guide is to show how **OpenKnowledge's features compose** to make the pattern feel native: the starter-pack picker scaffolds the layout in one click; per-folder templates + agent-readable folder frontmatter teach the LLM the conventions (Karpathy's centralized `CLAUDE.md` / `AGENTS.md` schema, distributed per-folder); the `workflow` tool's three pipeline kinds (`ingest`, `research`, `consolidate`) cover the sources → provisional → canonical pipeline; the WYSIWYG editor + CRDT keep editing frictionless; the activity panel attributes every write; the `links` tool keeps the source graph clean. Every step uses three or four of these together. That's the product. ## Who this is for - **You're new to LLM-curated PKM.** You've felt the pull of "the LLM should remember my context for me" but you don't want a vault that turns into a junk drawer of unprocessed clips. Start here. -- **You already practice Karpathy's pattern in another tool** (Obsidian, plain folders, Claude projects). You want to know what Open Knowledge does differently, and what you keep. +- **You already practice Karpathy's pattern in another tool** (Obsidian, plain folders, Claude projects). You want to know what OpenKnowledge does differently, and what you keep. Either way, by the end of this guide you'll have a working source-grounded knowledge base, a routine for adding sources, and a daily-driver agent setup that interrogates the vault on your behalf. @@ -18,7 +18,7 @@ Either way, by the end of this guide you'll have a working source-grounded knowl You need: -- **The Open Knowledge desktop app.** The native macOS app is the canonical surface: WYSIWYG editor, file sidebar, agent activity panel, version timeline, and the starter-pack picker all live there. Install it from the [Quickstart](../get-started/quickstart.mdx). +- **The OpenKnowledge desktop app.** The native macOS app is the canonical surface: WYSIWYG editor, file sidebar, agent activity panel, version timeline, and the starter-pack picker all live there. Install it from the [Quickstart](../get-started/quickstart.mdx). - **An MCP-capable agent assistant.** [Claude Code](../integrations/claude-code.mdx), [Cursor](../integrations/cursor.mdx), or [Codex](../integrations/codex.mdx). The OK desktop app's first-launch flow detects them and wires them up. - **A read of the source pattern.** Andrej Karpathy's [LLM wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) is the canonical description of what we're implementing here. It's a 10-minute read and worth doing first; this guide builds on it directly. @@ -36,7 +36,7 @@ You're evaluating a new agent framework for an upcoming architecture decision. Y By the end of the afternoon you can ask your agent "what does the framework do when two sub-agents race on the same write?" and get an answer that cites the specific paragraph in the architecture doc, contextualized with the maintainer's clarification on Twitter, without re-reading any of the five sources yourself. -That's the payoff. Below is how you get there in Open Knowledge. +That's the payoff. Below is how you get there in OpenKnowledge. ## What's in your vault after one afternoon @@ -82,11 +82,11 @@ Karpathy's framing of why this matters: > the wiki is a persistent, compounding artifact. The cross-references are already there. -## How Open Knowledge implements (and extends) this +## How OpenKnowledge implements (and extends) this The **Knowledge base** pack scaffolds Karpathy's pattern with one significant addition: **the wiki layer is split** into `research/` (provisional) and `articles/` (canonical), with `consolidate` as the explicit promotion ritual. -| Karpathy | Open Knowledge | +| Karpathy | OpenKnowledge | |---|---| | `raw/` (verbatim sources, immutable) | `external-sources/` (OK's name; same role) + `clip` template + `ingest` workflow | | `wiki/` (single LLM-owned layer) | **Split**: `research/` (provisional, status:`provisional`, sources cited) + `articles/` (canonical, status:`canonical`, supersedes chain); `consolidate` promotes | @@ -101,7 +101,7 @@ When your agent lists `external-sources/`, it reads the folder description telli ### 1. Open the desktop app and pick a project folder -Launch **Open Knowledge** (the macOS app). Either drag-and-drop a folder, open one from **Pick Existing Project**, or click **Start Fresh** to create a new vault. The first-launch consent dialog scaffolds `.ok/` and offers to wire up any MCP-capable editors it detects (Claude Code, Cursor, Codex). +Launch **OpenKnowledge** (the macOS app). Either drag-and-drop a folder, open one from **Pick Existing Project**, or click **Start Fresh** to create a new vault. The first-launch consent dialog scaffolds `.ok/` and offers to wire up any MCP-capable editors it detects (Claude Code, Cursor, Codex). Don't have the desktop app yet? See the [Quickstart](../get-started/quickstart.mdx). @@ -203,7 +203,7 @@ The compounding move: end each ingest session with one synthesis query. The answ ## Looking for entity tracking instead? -This guide is the **source-grounded** posture: bring sources, the LLM curates the wiki. If what you actually want is to track *people, companies, and meetings* (who's in your network, what was said, what changes over time), the [Entity vault (GBrain-compatible) workflow guide](./entity-vault.mdx) is the better starting point. Different pattern, same Open Knowledge editor. +This guide is the **source-grounded** posture: bring sources, the LLM curates the wiki. If what you actually want is to track *people, companies, and meetings* (who's in your network, what was said, what changes over time), the [Entity vault (GBrain-compatible) workflow guide](./entity-vault.mdx) is the better starting point. Different pattern, same OpenKnowledge editor. ## Further reading @@ -211,7 +211,7 @@ This guide is the **source-grounded** posture: bring sources, the LLM curates th - **[Karpathy's LLM wiki gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f).** The original three-layer pattern, in his words. Read this before or alongside this guide. -### Open Knowledge internals that support this workflow +### OpenKnowledge internals that support this workflow - **[Agent activity](../features/agent-activity.mdx).** How every agent edit lands in the shadow repo with attribution. - **[Claude Code](../integrations/claude-code.mdx)**, **[Cursor](../integrations/cursor.mdx)**, **[Codex](../integrations/codex.mdx).** Agent-assistant integrations. @@ -219,4 +219,4 @@ This guide is the **source-grounded** posture: bring sources, the LLM curates th ### Adjacent OK workflow -- **[Entity vault (GBrain-compatible) workflow in Open Knowledge](./entity-vault.mdx).** Entity-vault counterpart, if the source-grounded posture isn't your fit. +- **[Entity vault (GBrain-compatible) workflow in OpenKnowledge](./entity-vault.mdx).** Entity-vault counterpart, if the source-grounded posture isn't your fit. diff --git a/docs/src/app/(home)/sections/hero-preview.tsx b/docs/src/app/(home)/sections/hero-preview.tsx index 3d1d4b541..0f87310bb 100644 --- a/docs/src/app/(home)/sections/hero-preview.tsx +++ b/docs/src/app/(home)/sections/hero-preview.tsx @@ -25,7 +25,7 @@ export type HeroPreviewAgentId = keyof typeof AGENT_META; const PAUSED = false; const USER_MESSAGE = 'Help me write up our launch week'; -const AGENT_STATUS = 'Drafting your launch recap in Open Knowledge.'; +const AGENT_STATUS = 'Drafting your launch recap in OpenKnowledge.'; const DOC_PATH = 'retros/launch-week'; const TOOL_NAME = 'open-knowledge · write'; const TOOL_SUMMARY = 'Create recap + add daily activity chart'; @@ -523,7 +523,7 @@ function EditorPanel({
diff --git a/docs/src/app/(home)/site-nav.tsx b/docs/src/app/(home)/site-nav.tsx index 11f6ce175..6237d26dc 100644 --- a/docs/src/app/(home)/site-nav.tsx +++ b/docs/src/app/(home)/site-nav.tsx @@ -32,6 +32,7 @@ const navLinks: NavLink[] = [ label: 'Discord', external: true, icon: DiscordIcon, + iconOnly: true, }, { href: 'https://x.com/OpenKnowledgeAI', @@ -91,8 +92,8 @@ export function SiteNav() { return (
- - + +