docs-bundle
okf-loom Documentation
okf-loom is a GitHub-cloneable, vendor-neutral, harness-agnostic skill repository with a documentation bundle, focused resources, and checkout-local scripts. It validates, searches, discovers gaps in, updates, and renders a navigable wiki + graph viewer for any Open Knowledge Format bundle. See the current okf-loom specification; upstream OKF SPEC v0.1 remains the base wire-format reference.
See it in action: the Rendering & Feature Showcase packs every renderer (Mermaid, KaTeX, syntax highlighting, tables) and live feature onto one page.
This bundle IS okf-loom's own documentation, organised in the Diátaxis framework: each concept belongs to one of four content types, and the type tells you how to read it.
Demo
- Rendering & Feature Showcase — every renderer (Mermaid, KaTeX, syntax highlighting, tables) and every governed key on one page. Open it first when evaluating the viewer.
Four kinds of documentation
Learning
Walk-throughs written for someone new to okf-loom. Read top to bottom; reproduce every step.
- Use okf-loom from a clone — clone, load
SKILL.mdand resources, verify, firstscripts/okf-loom validate. - Author your first bundle — scaffold, write, validate.
- Use the live studio — serve, navigate, comment.
- Direct the agent loop — wait → claim → write → resolve.
See tutorials/ for the full list.
How-to
Recipe-style guides for a specific goal. Skim the list, find your task, follow the steps.
- Validate a bundle in CI
- Find and fix bundle gaps
- Author concepts via CLI verbs
- Build a static site
- Archive and resolve comment threads
- Embed the viewer in an agent harness
- Migrate across spec versions
See how-to/ for the full list.
Reference
Technical descriptions of the machinery. Read topically; not sequential.
- CLI command reference
- Current okf-loom specification
- Frontmatter contract
- Link forms
- Capability registry
- Search modes
- HTTP server routes
- Comment lifecycle and archive rules
- okf-loom.config.yaml reference
Deep design docs (imported)
These are the long-form authoritative sources for design rationale and binding specs. They live in the bundle so search/graph/indexes reach them.
- okf-loom architecture — module-by-module developer reference.
- Embedding guide — harness-specific wiring recipes (opencode, Claude Code, Codex, LangGraph, MCP, custom).
See reference/ for the full list.
Understanding
Discussion-oriented pieces that clarify the why behind the design.
- What OKF is for
- okf-loom architecture (concise)
- Why the live studio exists
- Dependency-light philosophy
- Why this bundle uses Diátaxis
- Original requirements brief — the user-stated goals + traceability matrix.
- Best-of-breed research — comparative analysis of Obsidian, Quartz, MkDocs, etc.
See explanation/ for the full list.
Outside the bundle
These stay in okf-loom/docs/ because they are retained proof artifacts rather than user-facing docs:
- docs/screenshots/ — viewer capture proof PNGs.
Demo 1
- Rendering & Feature Showcase demo/showcase One page that exercises everything the okf-loom viewer can render — diagrams, math, code, tables, governed keys, live features — so you can …
Explanation 7
- Best-of-Breed Research explanation/research Historical research input — comparative analysis of Obsidian, Logseq, Notion, MkDocs Material, Hugo, Jekyll, Docusaurus, Quartz v4, Foam, De…
- Dependency-light philosophy explanation/zero_dependencies Why okf-loom runs from a checkout with no primary install step, how the PyYAML-preferred fallback works, and where optional browser proof fi…
- okf-loom architecture explanation/architecture Why okf-loom is shaped around one canonical ContentIndex feeding three render targets (serve, build, render), and why each module has the sh…
- Original Requirements explanation/requirements The original user requirements brief that shaped okf-loom, with a traceability matrix mapping each requirement to the docs and code that imp…
- What OKF is for explanation/what_is_okf Why the Open Knowledge Format exists — knowledge as plain, diffable, agent-parseable markdown files linked into a graph — and what it delibe…
- Why the live studio exists explanation/live_studio_design The rationale behind the live studio — comment-driven directing, no review gate by default, all-on defaults, SSE plus polling fallback, the …
- Why this bundle uses Diátaxis explanation/diataxis Why this docs bundle is organised by the Diátaxis framework — the four content types, the four reader postures they serve, why mixing them c…
How-to 7
- Archive and resolve comment threads how-to/archive_threads Archive and unarchive comment threads in the live studio using the current archive track, where archived is a separate boolean, archiving is…
- Author concepts via CLI verbs how-to/author_with_verbs Edit OKF concepts from the command line with write-concept, set-frontmatter, link-add, and entity-add, grouping writes for one-click undo an…
- Build a static site how-to/build_static_site Render an OKF bundle to a portable static site with the build command, choosing the SPA, static, or single-file target, and optionally embed…
- Embed the viewer in an agent harness how-to/embed_in_harness Embed okf-loom inside an agent harness (opencode, Claude Code, Codex, LangGraph, or custom) using the CLI shell-out shape, the Python librar…
- Find and fix bundle gaps how-to/discover_and_fix_gaps Run discovery to find missing links, indexes, descriptions, relations, and orphans, then apply fixes directly via mutators or a reviewable u…
- Migrate across spec versions how-to/migrate_spec_version Migrate an OKF bundle across OKF spec versions by declaring okf_version in the root index, previewing with upgrade checks, and applying idem…
- Validate a bundle in CI how-to/validate_in_ci Enforce OKF conformance in CI by picking a validation profile and wiring the strict validate command into GitHub Actions or GitLab CI.
Reference 11
- Capability registry reference/capabilities The OKF capability registry — tier model (core / recommended / optional), the full catalogue, opt-in mechanisms, and the capabilities comman…
- CLI command reference reference/cli Every `scripts/okf-loom` subcommand — purpose, key flags, exit codes, and output formats — for the okf-loom v1.0 baseline.
- Comment lifecycle and archive rules reference/comment_lifecycle The full current comment state model — states, the separate archive track, the request_summary/summary pair, ts vs updated_at, threading, an…
- Embedding Guide reference/embedding_guide How to wire okf-loom into any agent / meta-harness — CLI shell-out, Python library, and long-running server shapes, with harness-specific re…
- Frontmatter contract reference/frontmatter The OKF frontmatter contract (SPEC §4.1) — required and recommended keys, round-trip preservation, and YAML gotchas.
- HTTP server routes reference/http_routes Every route the live studio exposes — method, purpose, body shape, response shape, and status codes.
- Link forms reference/links The two OKF link forms (SPEC §5) — absolute bundle-relative and relative — plus anchors, external links, wikilinks, and broken-link toleranc…
- okf-loom Architecture reference/architecture Developer-facing reference for okf-loom — module map, design rationale, extension points, and forward-compat mechanisms.
- okf-loom Current Specification reference/spec The current canonical specification for okf-loom v1.0, covering the upstream OKF SPEC v0.1 wire-format baseline, source-checkout and agent-s…
- okf-loom.config.yaml reference reference/config_yaml Every `okf-loom.config.yaml` key — `bundle.*`, `viewer.*`, `search.*`, `validate.*`, `studio.*` — with type, default, and behaviour. Path-be…
- Search modes reference/search_modes The six search modes behind one `--mode` flag, their backends, and the `SearchBackend` Protocol for plugging in custom backends.
Tutorial 4
- Author your first bundle tutorials/first_bundle Scaffold a new OKF bundle with scripts/okf-loom init, hand-write a few concepts, validate, discover gaps, and fix one.
- Direct the agent loop tutorials/author_with_agent Drive the canonical OKF agent loop — wait for a comment, claim it, author via mutators, resolve it, and loop.
- Use okf-loom from a clone tutorials/install Clone the okf-loom skill repository, load SKILL.md and focused resources, verify source-checkout invocation, and run your first validation a…
- Use the live studio tutorials/live_studio_basics Bring up scripts/okf-loom serve, navigate the viewer (rendered, source, split, graph, search), post a comment, and watch it land in directiv…