openknowledge view

Start the local web viewer. Specify a path or registry key to open one knowledge base. Omit the target to open all connected knowledge bases in one registry workspace.

Usage

Start the local viewer without opening a browser. Use --no-browser to print its URL.

okn view [key-or-path]
okn view --no-browser Wiki
okn view --host 127.0.0.1 --port 8080 Wiki
okn view --allow-network --host 0.0.0.0 Wiki

Head injection also reads OPENKNOWLEDGE_HEAD_FILE, OPENKNOWLEDGE_HEAD_HTML, and OPENKNOWLEDGE_SCRIPT_SRC.

Viewer features

• Browser WebMCP exposes page list, search, read, and navigation tools to compatible browser agents. Local editor tools share the visible draft and can save changes to writable Markdown files.
• The viewer renders Markdown and follows local links. It renders fenced mermaid blocks as diagrams. It also shows note panels, source graphs, validation context, highlighted assets, and media or PDF previews.
• Markdown images resolve relative to the source Markdown file. Local images use the safe raw asset route. HTTP(S) images keep their external URL. Images include alt text, optional titles, lazy loading, and bounded sizes. Images in tables use a smaller cell boundary.
• Source and text files open as standard note cards. They use the same breadcrumbs, panel controls, syntax highlighting, and open-beside behavior. Other assets keep their raw or dedicated media previews.
• Click a rendered Mermaid diagram to open a viewport-filling dialog. You can also focus the diagram and press Enter or Space. Use the toolbar, wheel, or pinch gesture to zoom. Drag the diagram, or use the arrow keys, to pan. Select Fit to fit the complete diagram in the viewport. Select 100% to center the diagram at its original scale. Press Escape to close the dialog.
• The sidebar has top-level Documents, Graph, and Knowledge bases items. Documents opens files from any file tree in one document stack. Graph shows the combined graph. Each knowledge base contains its own file tree. A knowledge base with typed claim occurrences also contains a Claims item. The Claims item shows claims only from its knowledge base. Use the collapse icon to close all expanded trees. Use the plus icon to connect another local folder. Settings opens the viewer preferences from the sidebar footer. Select the shortcut badge in the viewer header to open or close the file explorer.
• Links replace the current panel by default. The link behavior control can select open-beside mode. The browser stores this selection. Hold Shift during activation to use the other mode one time. Each panel keeps its own focus and close controls. The file explorer opens by default on desktop. It remains visible during link navigation and uses the first grid column at 25vw. You can resize it within its minimum and maximum limits. The viewer header, note workspace, and horizontal scroll rail remain in the second grid column. With multiple panels open, drag the bottom horizontal scroll thumb to move the document stack directly. A document stack can contain files from different connected knowledge bases. Stack URLs and browser history retain the source knowledge base for each panel.
• On viewports up to 680 px, sidebar open and close actions have no motion. Note stack navigation has no View Transition or fallback panel entrance effect. A sidebar link closes the sidebar and shows its destination immediately.
• AST-based search uses the same section ranking as okn search. It also uses the same one-level link expansion. Results group section matches by document. They can link to and highlight the matching text. Search excerpts strip common Markdown markup. The search control is on the right side of the viewer header. Registry mode searches all connected knowledge bases. Each result shows its source knowledge base. The viewer adds folder context to Index titles. The search panel shows progress, result counts, no-result messages, and errors. Select Retry after an error. Use the arrow keys to select a result. Press Enter to open it. Press Shift+Enter to use the other panel mode. Press Escape to close search.
• Each note uses a compact header. The Details disclosure in the header starts collapsed. Select Details to inspect the typed YAML table. Each note with typed claims also has a collapsed Claims panel. The panel shows typed statements, status, scope, evidence totals, and occurrence relations. It uses ontology labels and keeps technical IDs in claim details. For a scoped metric, the panel uses the metric scope value as the compact identity. The compact statement shows only the subject, metric, and formatted quantity. Evidence and metadata retains scope, lifecycle, time, IDs, quantity kind, and evidence. The Claims workspace keeps technical fields under a collapsed Technical details disclosure. A section_ref links a claim to its Markdown section. The matching heading shows the claim count. Select the marker to open the first bound claim. The panel is read-only and does not change canonical YAML. When the registry workspace contains multiple knowledge bases, the header prefixes the path breadcrumb with the source knowledge-base name. The prefix uses the same breadcrumb style and slash separator. The viewer also provides tag filters, sortable tables, and directory breadcrumbs. The Documents view expands the active file branch. Directory rows can collapse, and the explorer has a Collapse all action.
• Markdown note headers include a Listen control when the browser provides speech synthesis. Open Knowledge does not require an OpenAI API key, consume Codex credits, or make its own speech API request. The browser selects the voice; depending on the browser, operating system, and installed voice, its speech service may be local or network-backed. Select the control again to pause or resume, and select Stop to end narration. Starting another note stops the current note first. Narration reads the rendered reader-facing article. It skips frontmatter, agent-only annotations, code blocks, Mermaid diagrams, and hidden controls. Browsers without speech synthesis hide the control.
• For OKF 0.2 concepts, the expanded frontmatter area groups derived trust, status, freshness, provenance, structured sources, and Attested Computation data. Each derived signal uses the same two-column field-and-value rows as the frontmatter table. The viewer marks inferred unverified trust and stable status values as Default. Source footnotes open the matching structured source entry. The viewer never executes declared resources automatically.
• The knowledge graph uses a theme-aware canvas. The left detail panel shows only the connection count for the selected or hovered node. The canvas aria-label keeps the node name and Enter hint. The graph preserves typed claim occurrence nodes. It shows declaration, reference, supersession, contradiction, and derivation relations. The top-bar Graph icon toggles between the graph and the open documents. On viewports wider than 680 px, the graph workspace fills the viewport below the header. The canvas is 380 px high on smaller viewports. On viewports up to 720 px, the Graph settings disclosure starts collapsed and contains graph filters, display and force controls, and reset and animation actions. Drag the canvas to pan. Use the wheel or trackpad to zoom. Icon-only zoom, fit, and settings controls sit in the canvas's lower-left corner. Graph settings are hidden by default. The settings control toggles a vertically centered card on the canvas's left. Drag a node to move it. Use the fit control to show the complete graph. Filter notes by title or path. The Color nodes by folder control applies theme-aware colors. Hovered and selected nodes keep their folder colors. Registry mode combines the graphs from all connected knowledge bases. Each knowledge base keeps its own index. The viewer does not add cross-base links. The canvas uses the complete workspace. Content filters select documents, claims, or entities. Knowledge-space filters select source knowledge bases. File-name labels use the source knowledge-base color. The file nodes keep their current graph colors. Display controls adjust arrows, labels, node size, and link thickness. Force controls adjust center, repel, and link forces. Select Pause to stop graph motion. Select Resume to start motion. Select Reset graph to restore the graph defaults. Arrow keys move the selection. Enter opens the selected note. The file tree stays in the file explorer.
• Use Settings to change browser-local themes, typography, line length, contrast, motion, and link settings. Reset to defaults restores the viewer defaults. The first visit uses the light blue default theme. A saved theme preference overrides this default. These preferences do not change source Markdown. The Horizontal stack switch is disabled by default in the Document section. Enable it to open linked documents beside the current document.
• The browser assigns a color to each connected knowledge base. Use the color control beside its name to change the color. The browser saves this choice locally and reuses it in search results and graph labels.
• Direct paths and writable local connections provide local editor links. Static exports use configured repository source links.
• The local viewer serves the same Vite-built JavaScript and CSS bundle as static exports. Local routes supply live API data. Static pages load one shared generated data file.
• The local viewer watches visible Markdown and asset files. It refreshes the open page after an add, update, rename, move, or deletion. One save burst causes one refresh after a short delay. The viewer reuses parsed AST and claim data between document requests. Navigation requests build only the selected document panel. Registry document pages request the combined graph only after you open it. Each Claims item requests data only from its knowledge base. A failed claims index does not affect claims in another knowledge base. A claim profile pass reads and indexes each pinned evidence artifact one time, even when many selectors use that artifact. Graphs with more than 250 nodes use a stable grid and start with force motion paused. The watcher reuses content digests for files whose metadata did not change. Existing open paths, the active path, the graph view, and scroll positions survive when their targets still exist. The viewer removes deleted open paths before refresh. Static HTML exports do not include this live reload client.

Use a page and report problems

Open Use this page in a note header. Copy context and source copies selected text, or the article text when no text is selected, with its source. For an open editor, it copies current draft text and identifies unsaved changes. Copy page link copies the document URL. Copy code copies a code block. If clipboard access fails, the viewer shows selectable text.

Open Report a problem to describe missing or outdated information. Copy report includes the source. Local Save to insights requires a writable project integration for this knowledge base. A saved report enters the insight inbox and does not change the document. Static viewers provide report copying only. A no-result search can open a report with the search question.

In the local viewer, open Knowledge health in the sidebar footer. The panel shows the current knowledge status, attention items, and pending insights. All checks and coverage shows each check layer, including unconfigured checks. Review and repair provides CLI commands. Refresh checks reloads the results. Static viewers do not provide live knowledge health.

Tables with four rows or fewer stay compact without filtering controls. Larger tables support sorting and filtering.

Edit Markdown

Open an existing Markdown page in a writable local knowledge base to edit its body directly. The WYSIWYG editor appears automatically in the document panel. Read-only registry connections and static exports do not permit edits. The editor does not create, rename, or delete documents.

Type ### followed by a space at a paragraph start to create a level-three heading. Type / at a paragraph start to open the block menu, or select +. The menu provides headings, lists, tasks, quotes, code, dividers, and tables. Use the formatting toolbar for text style, bold, italic, strikethrough, and links. Hold Ctrl or Command while you click an editor link to open its destination. Images resolve against the source document, including in additional panels. Select Preview saved page to inspect rendered diagrams and source references. This preview shows saved content. It does not include unsaved draft changes.

Visual body edits preserve YAML frontmatter without displaying it in the editor. Unchanged source blocks retain their original Markdown formatting. The editor serializes changed blocks as Markdown. Unsupported Markdown appears as an opaque block with a source preview. Its internal text is not visually editable and remains unchanged during other body edits.

Human input and WebMCP editor tools change the same visible draft. Undo and Redo share one change history. Changes expands the difference from the saved source below the editor. Hide changes closes that comparison. The editor remains visible. Unsaved drafts remain available when you navigate away and return to a page. Select Save, or press Cmd+S / Ctrl+S, to write the draft.

Each save checks the source revision and validates the document before the file replacement. Validation errors block the save. The editor shows warnings after a successful save. Bundle-wide claim and rule checks remain separate. The editor limits UTF-8 documents to 1 MiB.

When the saved file changes, an editor without unsaved changes loads the new source. If the draft has unsaved changes, the editor preserves them and blocks its save. Compare saved file shows the current source against the draft. Load saved version replaces the draft with that source. Undo restores the previous draft, which can then be reconciled before another save.

Live reload refreshes clean viewers, including their file catalog and metadata. If unsaved drafts exist, live reload preserves them and checks open documents for source conflicts. The browser keeps recovery text in tab session storage when available. If recovery storage fails, keep the tab open until the draft is saved.

Claims workspace

When a knowledge base contains typed claim occurrences, select Claims to browse them. The viewer hides Claims when no claim occurrence is present. Registry mode does not combine claims from different knowledge bases. A direct single-base viewer keeps an available Claims item in the main navigation.

The compact toolbar keeps the claim count, search, status, entity, predicate, and additional filters together. Filter claims by status, entity, predicate, owner, evidence stance, document, or validation state. Select a claim to inspect its typed value, evidence, provenance, and time. Evidence and metadata shows source information, owners, and evidence first. Expand Technical details for IDs and typed fields. This workspace is read-only.

When the selected claim has authored incoming or outgoing relations, a collapsed Relationships section appears below its details. Claims without authored relations do not show this section.

For a scoped metric, compact claim surfaces use the metric scope value as the identity and show only the subject, metric, and formatted quantity. The selected claim details retain scope, lifecycle, and source metadata.

The viewer selects the displayed brand from root metadata in this order: okf_bundle_title, okf_bundle_name, title, then the first H1. The viewer truncates long brand names with an ellipsis when header space is limited.

Network and file safety

Loopback mode does not require a token. A non-loopback or wildcard bind requires --allow-network. All routes then use token authentication.

The initial URL exchanges the token for an HttpOnly, SameSite cookie. It then redirects to a clean URL. A remote client can also send Authorization: Bearer <token>.

The live reload event stream uses the same authentication. Events contain a content revision and optional knowledge-base aliases. They do not contain file contents or filesystem paths.

Raw routes serve only regular non-Markdown bundle assets. They exclude dotfiles, .git, .openknowledge.toml, legacy openknowledge.toml, and symlinks. Markdown and asset resolution cannot leave the bundle root. Raw SVG responses keep their image media type and use the raw route sandbox policy.

The viewer inserts trusted head fragments in their original form. Use only content that you control.

In registry mode, the viewer rebuilds routes after the validated registry snapshot changes. It refreshes content-hashed search indexes after source edits. A registry or fingerprint failure returns an error. The viewer does not serve stale or partly trusted state.

The registry workspace can connect an existing local knowledge base. The connection is read-only unless you enable editor links. If the selected folder is not a knowledge base, the viewer shows the okn setup command that creates one. Direct-path and static-export views do not provide the registry connection control.

Theme and source-link configuration comes from .openknowledge.toml. For deployment, use the HTML exporter.

Use the Markdown viewer showcase to inspect the supported Markdown rendering contract.

Markdown agent-context annotations remain visible in the document flow. A subdued text color distinguishes their content from reader content. Their content remains in canonical source and the AST, but does not enter ordinary reader search. The viewer also accepts the legacy agent-maintenance footer marker.