okf-wiki-kit 0.2.0__py3-none-any.whl

okf_wiki_kit-0.2.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: okf-wiki-kit
+Version: 0.2.0
+Summary: Build Open-Knowledge-Format (OKF) / Obsidian LLM wikis from any source material.
+Author: okf-wiki-kit contributors
+License: MIT
+Project-URL: Homepage, https://github.com/olivermorgan2/okf-wiki-kit
+Project-URL: Issues, https://github.com/olivermorgan2/okf-wiki-kit/issues
+Project-URL: Repository, https://github.com/olivermorgan2/okf-wiki-kit
+Keywords: okf,obsidian,knowledge-graph,llm,rag,wiki,markdown
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == "openai"
+Provides-Extra: rag
+Requires-Dist: numpy>=1.24; extra == "rag"
+Provides-Extra: voyage
+Requires-Dist: voyageai>=0.3; extra == "voyage"
+Provides-Extra: local-embeddings
+Requires-Dist: numpy>=1.24; extra == "local-embeddings"
+Requires-Dist: model2vec>=0.3; extra == "local-embeddings"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == "mcp"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# okf-wiki-kit
+
+Build a cross-linked **[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
+(OKF)** knowledge wiki — browsable in **Obsidian** and consumable by **LLMs/agents** — from *any*
+source material.
+
+OKF represents knowledge as a directory of markdown files: each file is a typed node with YAML
+frontmatter (only `type` is required) and `[[wikilinks]]` that form a knowledge graph richer than
+the folder hierarchy. `okf-wiki-kit` gives you a small, dependency-light engine that turns your
+content into such a bundle, with optional LLM enrichment.
+
+## How it works
+
+```
+your source ──► SourceAdapter.load() ──► [Node, Node, …] ──► engine ──► OKF/Obsidian vault
+                (you write ~40 lines,        (normalized)      (generic: frontmatter, wikilinks,
+                 or use a built-in one)                          indexes, link-inference, validate)
+```
+
+You implement **one method** — `load() -> Iterable[Node]` — that turns your source into a list of
+`Node`s. The engine does everything else: unique filenames, frontmatter, wikilinks, per-type and
+root `index.md` files, optional mention-based link inference, validation, and optional LLM
+enrichment.
+
+## Quickstart (zero code)
+
+Point the built-in *markdown-folder* adapter at any folder of `.md` files:
+
+```bash
+pip install -e .                     # or: pip install okf-wiki-kit
+cp okf.config.example.yaml okf.config.yaml
+# edit okf.config.yaml -> adapter_options.path: ./my-notes
+okf build                            # writes ./vault
+okf validate                         # every node typed, every wikilink resolves
+```
+
+Open the `./vault` folder in Obsidian and look at the Graph View.
+
+## Optional: LLM enrichment
+
+```bash
+pip install -e ".[openai]"           # or ".[anthropic]"
+export OPENROUTER_API_KEY=...        # or ANTHROPIC_API_KEY
+okf enrich                           # writes enrichment.json (canonical concepts + descriptions)
+okf build                            # rebuild, applying the enrichment
+```
+
+Enrichment is **provider-flexible**: Anthropic (`claude-sonnet-4-6`) or any OpenAI-compatible
+endpoint such as **OpenRouter** (`qwen/qwen3.7-plus`). Provider is auto-detected from your env keys.
+
+## Writing your own adapter
+
+For structured sources (JSON, a database, a CMS), write a small adapter:
+
+```python
+from okfkit.model import Node, Link
+from okfkit.adapters.base import SourceAdapter
+
+class MyAdapter(SourceAdapter):
+    def load(self):
+        for row in my_source():
+            yield Node(
+                id=row["slug"], type="Article", title=row["title"],
+                body=row["markdown"],
+                frontmatter={"author": row["author"]},
+                links=[Link(target=t, rel="related", section="See also")
+                       for t in row["related_slugs"]],
+                tags=row["tags"],
+            )
+```
+
+Point `okf.config.yaml` at it: `adapter: path/to/my_adapter.py:MyAdapter`. See
+[`docs/writing-an-adapter.md`](docs/writing-an-adapter.md) and the worked example in
+[`examples/textbook/`](examples/textbook/).
+
+## The `Node` model
+
+| field | meaning |
+|-------|---------|
+| `id` | stable unique id → becomes the filename / wikilink target |
+| `type` | OKF `type:` value (required) — `"Chapter"`, `"Concept"`, or anything you invent |
+| `title` | human-readable name (wikilink display) |
+| `body` | markdown body (no frontmatter) |
+| `frontmatter` | any extra YAML fields (may contain `[[wikilinks]]`) |
+| `links` | edges to other nodes; each `Link(target, rel, section)` renders under a `## section` heading |
+| `tags`, `aliases` | Obsidian-native tags and aliases |
+
+## Use with Claude Code / Claude Desktop
+
+Serve a built vault as a read-only MCP server so agents can query it as tools:
+
+```bash
+pip install -e ".[mcp]"
+claude mcp add okf-wiki -- okf serve -c /abs/path/okf.config.yaml
+```
+
+The server exposes five read-only tools: `okf_vault_info` (orientation — call first),
+`okf_search` (semantic; needs a prior `okf index`), `okf_list_notes` (browse/paginate by type or
+tag), `okf_get_note` (full note with links and backlinks), and `okf_neighbors` (walk the link
+graph). The graph tools need no API keys. Use `okf serve --vault /abs/path/vault` to serve any
+OKF vault without a config, and `--no-rag` for graph tools only.
+
+## Roadmap
+
+- **Build** — engine, markdown-folder adapter, custom adapters, link inference, LLM enrichment, CLI.
+- **Semantic RAG (Phase 7) ✓** — `okf index` / `okf search` / `okf ask`: embeddings index + retrieval-augmented Q&A.
+- **MCP server (Phase 8) ✓** — `okf serve`: expose the vault as read-only tools for Claude Code / Desktop / any MCP client.
+
+See [`docs/roadmap.md`](docs/roadmap.md) for details.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

okf_wiki_kit-0.2.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+okf_wiki_kit-0.2.0.dist-info/licenses/LICENSE,sha256=p34ts6qpfM42vGnl33KtSvTJkDJIHmbANW70Iv6hrV8,1082
+okfkit/__init__.py,sha256=equkfQ-3hNkNatZGLs-yc-EhboAxhDVPby8Z9Zv0R1g,165
+okfkit/cli.py,sha256=gTbO_la9h1Wcm5fD-qK_EJ-63gUfcUB3gQQsp0loIY8,10604
+okfkit/config.py,sha256=uNdMNDkK4IZTSgoUtnORyOBs8N0zPbjQ8JhOkAfoqy8,1878
+okfkit/engine.py,sha256=pRVr7_IRgrufuqsJSVHv4VQHWVW0GIBUkt7leVge3ow,13500
+okfkit/enrich.py,sha256=23jcefvOKP0Con6S_tdqP8Q8H86tKLIudXiV7r5l9fQ,12431
+okfkit/model.py,sha256=DyZdelyPEDTihbOVicYBexEF1_rcRjzkiHkxY6VWWZ8,1995
+okfkit/render.py,sha256=yUEHI4O_eXdrCcUv9TXvjgXE3MDQO4qHjfBKUy61SPU,3651
+okfkit/adapters/__init__.py,sha256=Xrn0GsKkfPvt-28n_X8G_NbsYgYS0v1iCSNu7WlsnaA,304
+okfkit/adapters/base.py,sha256=-FiMJ7mvLAV0NyHLCv4gLrif3xfdUD8q5oTZymXG-P8,2243
+okfkit/adapters/markdown_folder.py,sha256=PMTZNyTGI7iXQPf22AAYrLBflQnB7jQNXuMc1r1CYLc,1838
+okfkit/serve/__init__.py,sha256=CiOmNuIOslhcHaJ38q9_BIZ9a0bht5boYt8l_A2q5YY,1504
+okfkit/serve/embeddings.py,sha256=QJ0GTPXPxBwl94PqkxepONt_fb9xKIQX-zoiaeb892I,4591
+okfkit/serve/mcp.py,sha256=N-nsh_oWrfoowlDqpk1D5bLdIO3BElfsRKY3xy9jdKc,15845
+okfkit/serve/rag.py,sha256=hwLLXP03xxOiIrEyIkPbOMmnNv200IME3qyFA45MALA,13837
+okfkit/serve/vault.py,sha256=9ATzPI56PpZZQQq4FZaI4cWGjxQg3DYPqUDS-l-dSks,4421
+okf_wiki_kit-0.2.0.dist-info/METADATA,sha256=8qrF7IxVB1x5ojR_jHF3Zc-_vco7h1Sw1noOWqqjIeA,6285
+okf_wiki_kit-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+okf_wiki_kit-0.2.0.dist-info/entry_points.txt,sha256=nDpPHk-9s0enmCcp2qWXCBEmqkUZQuRLXcjXjew3xRM,40
+okf_wiki_kit-0.2.0.dist-info/top_level.txt,sha256=ztDdsEtk2Q5K-r4FSr9XO8pCqIvduT0JrGg_vMUvJsw,7
+okf_wiki_kit-0.2.0.dist-info/RECORD,,

okf_wiki_kit-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

okf_wiki_kit-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+okf = okfkit.cli:main

okf_wiki_kit-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 okf-wiki-kit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

okf_wiki_kit-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+okfkit

okfkit/__init__.py

@@ -0,0 +1,6 @@
+"""okf-wiki-kit — build OKF/Obsidian LLM wikis from any source material."""
+
+from okfkit.model import Node, Link
+
+__version__ = "0.2.0"
+__all__ = ["Node", "Link"]

okfkit/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Source adapters — turn a specific source into `Node`s.
+
+Built-in adapters are resolved by short name (e.g. "markdown_folder"). Custom
+adapters are resolved by "path/to/file.py:ClassName".
+"""
+
+from okfkit.adapters.base import SourceAdapter, load_adapter
+
+__all__ = ["SourceAdapter", "load_adapter"]

okfkit/adapters/base.py

@@ -0,0 +1,66 @@
+"""The SourceAdapter contract and the resolver that loads one by name/path."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import os
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+
+from okfkit.model import Node
+
+# short name -> "module:Class" for built-in adapters
+BUILTINS = {
+    "markdown_folder": "okfkit.adapters.markdown_folder:MarkdownFolderAdapter",
+}
+
+
+class SourceAdapter(ABC):
+    """Subclass this and implement `load()`. That is the entire contract.
+
+    Options from `okf.config.yaml`'s `adapter_options:` are passed as keyword
+    arguments and stored on `self.options`.
+    """
+
+    def __init__(self, **options):
+        self.options = options
+
+    @abstractmethod
+    def load(self) -> Iterable[Node]:
+        """Yield (or return a list of) `Node`s built from the source."""
+        raise NotImplementedError
+
+
+def load_adapter(spec: str, options: dict | None = None) -> SourceAdapter:
+    """Instantiate an adapter from a built-in name or a "path.py:Class" / "module:Class" spec."""
+    options = options or {}
+    if spec in BUILTINS:
+        spec = BUILTINS[spec]
+    if ":" not in spec:
+        raise ValueError(
+            f"Adapter spec {spec!r} must be a built-in name ({', '.join(BUILTINS)}) "
+            f"or 'module_or_path:ClassName'."
+        )
+    target, class_name = spec.rsplit(":", 1)
+
+    if target.endswith(".py") or os.path.sep in target or os.path.exists(target):
+        module = _import_from_path(target)
+    else:
+        module = importlib.import_module(target)
+
+    cls = getattr(module, class_name, None)
+    if cls is None or not (isinstance(cls, type) and issubclass(cls, SourceAdapter)):
+        raise ValueError(f"{class_name!r} in {target!r} is not a SourceAdapter subclass.")
+    return cls(**options)
+
+
+def _import_from_path(path: str):
+    path = os.path.abspath(os.path.expanduser(path))
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"Adapter file not found: {path}")
+    name = "okfkit_adapter_" + os.path.splitext(os.path.basename(path))[0]
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module

okfkit/adapters/markdown_folder.py

@@ -0,0 +1,48 @@
+"""Built-in zero-code adapter: turn a folder of markdown files into OKF nodes.
+
+Each `.md` file becomes one node. `type`, `title`, `tags`, and `aliases` are read
+from YAML frontmatter if present (falling back to sensible defaults). The file's
+existing inline `[[wikilinks]]` are left in the body untouched — filenames are
+preserved as node ids so those links keep resolving.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from okfkit import render
+from okfkit.adapters.base import SourceAdapter
+from okfkit.model import Node
+
+
+class MarkdownFolderAdapter(SourceAdapter):
+    def load(self):
+        root = Path(self.options.get("path", ".")).expanduser()
+        if not root.is_dir():
+            raise NotADirectoryError(f"markdown_folder: path is not a directory: {root}")
+        default_type = self.options.get("default_type", "Note")
+
+        for f in sorted(root.glob("**/*.md")):
+            if f.name.lower() == "readme.md":
+                continue
+            fm, body = render.split_frontmatter(f.read_text(encoding="utf-8"))
+            node_id = str(fm.get("id") or f.stem)      # preserve filename → inline links resolve
+            yield Node(
+                id=node_id,
+                type=str(fm.get("type") or default_type),
+                title=str(fm.get("title") or f.stem),
+                body=body.strip(),
+                frontmatter={k: v for k, v in fm.items()
+                             if k not in ("id", "title", "type", "tags", "aliases")},
+                links=[],   # inline [[wikilinks]] already live in the body
+                tags=_as_list(fm.get("tags")),
+                aliases=_as_list(fm.get("aliases")),
+            )
+
+
+def _as_list(v):
+    if v is None:
+        return []
+    if isinstance(v, (list, tuple)):
+        return [str(x) for x in v]
+    return [str(v)]

okfkit/cli.py

@@ -0,0 +1,298 @@
+"""The `okf` command: build | enrich | validate | init | index | search | ask | serve."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from okfkit import __version__
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="okf", description="Build OKF/Obsidian wikis from any source.")
+    ap.add_argument("--version", action="version", version=f"okf-wiki-kit {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    helps = {
+        "build": "build the wiki",
+        "enrich": "enrich the wiki",
+        "validate": "validate the wiki",
+        "index": "build/refresh the semantic embeddings index over the built vault",
+        "search": "semantic search over the indexed vault (offline)",
+        "ask": "answer a question from the vault (retrieve + LLM)",
+        "serve": "run a read-only MCP server over the built vault (stdio)",
+    }
+    for name in ("build", "enrich", "validate", "index", "search", "ask", "serve"):
+        p = sub.add_parser(name, help=helps[name])
+        p.add_argument("-c", "--config", default="okf.config.yaml", help="path to okf.config.yaml")
+    # enrich-only overrides
+    ep = sub._name_parser_map["enrich"]
+    ep.add_argument("--provider", choices=["anthropic", "openai"], default=None)
+    ep.add_argument("--model", default=None)
+    ep.add_argument("--base-url", default=None)
+    # index-only flags
+    xp = sub._name_parser_map["index"]
+    xp.add_argument("--force", action="store_true", help="re-embed everything (ignore cached rows)")
+    # search/ask shared flags
+    for name in ("search", "ask"):
+        qp = sub._name_parser_map[name]
+        qp.add_argument("query", help="natural-language query")
+        qp.add_argument("-k", type=int, default=None, help="number of notes to retrieve (default: config top_k, else 8)")
+        qp.add_argument("--type", action="append", default=None, metavar="TYPE",
+                        help="restrict to this note type (repeatable)")
+    # ask-only chat-backend overrides (mirrors `okf enrich`)
+    kp = sub._name_parser_map["ask"]
+    kp.add_argument("--provider", choices=["anthropic", "openai"], default=None)
+    kp.add_argument("--model", default=None)
+    kp.add_argument("--base-url", default=None)
+    # serve-only flags
+    sp = sub._name_parser_map["serve"]
+    sp.add_argument("--vault", default=None, metavar="PATH",
+                    help="serve this OKF vault directly (bypasses the config)")
+    sp.add_argument("--no-rag", action="store_true",
+                    help="disable okf_search (graph tools only; no index needed)")
+
+    ip = sub.add_parser("init", help="scaffold okf.config.yaml (and an adapter stub)")
+    ip.add_argument("--adapter-stub", action="store_true", help="also write adapter.py template")
+
+    args = ap.parse_args(argv)
+    return {"build": _build, "enrich": _enrich, "validate": _validate, "init": _init,
+            "index": _index, "search": _search, "ask": _ask, "serve": _serve}[args.cmd](args)
+
+
+def _load(args):
+    from okfkit import config
+    from okfkit.adapters.base import load_adapter
+    cfg = config.load(args.config)
+    adapter = load_adapter(cfg.adapter, cfg.adapter_options)
+    nodes = list(adapter.load())
+    if not nodes:
+        raise SystemExit(f"Adapter {cfg.adapter!r} produced no nodes — check your source path.")
+    return cfg, nodes
+
+
+def _enrichment_path(cfg):
+    return os.path.join(cfg.base_dir, "enrichment.json")
+
+
+def _build(args):
+    from okfkit import engine
+    cfg, nodes = _load(args)
+    enrichment = None
+    ep = _enrichment_path(cfg)
+    if os.path.exists(ep):
+        with open(ep, encoding="utf-8") as fh:
+            enrichment = json.load(fh)
+        print(f"(using {os.path.relpath(ep)})")
+    result = engine.build(nodes, cfg.resolve(cfg.output),
+                          link_style=cfg.link_style,
+                          link_inference=cfg.link_inference,
+                          enrichment=enrichment)
+    print(result.summary())
+    print(f"\nVault written to {cfg.resolve(cfg.output)}")
+    return 0 if result.ok else 2
+
+
+def _enrich(args):
+    from okfkit import enrich
+    cfg, nodes = _load(args)
+    e = cfg.enrich or {}
+    enrich.run(
+        nodes, _enrichment_path(cfg),
+        canonicalize_type=e.get("canonicalize_type", ""),
+        describe_types=e.get("describe_types", []),
+        provider=args.provider or e.get("provider"),
+        model=args.model or e.get("model"),
+        base_url=args.base_url or e.get("base_url"),
+    )
+    print("Now run:  okf build")
+    return 0
+
+
+def _validate(args):
+    from okfkit import config, engine
+    cfg = config.load(args.config)
+    output = cfg.resolve(cfg.output)
+    if not os.path.isdir(output):
+        raise SystemExit(f"No vault at {output}. Run `okf build` first.")
+    unresolved, total, counts = engine.validate_vault(output)
+    print(f"Vault: {output}")
+    for t in sorted(counts):
+        print(f"  {t:16s}: {counts[t]}")
+    print(f"  {'TOTAL files':16s}: {total}")
+    if unresolved:
+        print(f"\n!! {len(unresolved)} unresolved wikilink target(s):")
+        for tgt, srcs in list(sorted(unresolved.items()))[:25]:
+            print(f"   [[{tgt}]]  <- {srcs[0]}")
+        return 2
+    print("\n  All wikilinks resolve. ✓")
+    return 0
+
+
+def _rag_settings(cfg):
+    """The `serve.rag` block of the config (all keys optional)."""
+    return (cfg.serve or {}).get("rag") or {}
+
+
+def _load_index(cfg, backend=None):
+    from okfkit.serve import Index
+    try:
+        return Index.load(cfg.base_dir, backend=backend)
+    except FileNotFoundError as exc:
+        raise SystemExit(str(exc))
+
+
+def _index(args):
+    from okfkit import config
+    from okfkit.serve import Index, chunk_notes, load_vault, make_embedder
+    cfg = config.load(args.config)
+    vault = cfg.resolve(cfg.output)
+    rag = _rag_settings(cfg)
+    emb = rag.get("embedding") or {}
+    backend = make_embedder(provider=emb.get("provider"), model=emb.get("model"),
+                            base_url=emb.get("base_url"))
+    notes = load_vault(vault)
+    chunks = chunk_notes(
+        notes,
+        max_chars=rag.get("chunk_max_chars") or 4000,
+        exclude_types=tuple(rag.get("exclude_types") or ("Index", "Home")),
+    )
+    try:
+        idx = (Index(backend, vault_path=vault) if args.force
+               else Index.load(cfg.base_dir, backend=backend))
+    except FileNotFoundError:
+        idx = Index(backend, vault_path=vault)
+    idx.vault_path = vault
+    print(f"Vault: {vault}  ({len(notes)} notes -> {len(chunks)} chunks)")
+    stats = idx.build(chunks, force=args.force)
+    npz_path, chunks_path = idx.save(cfg.base_dir)
+    print(f"  embedded {stats['embedded']}, reused {stats['reused']}, total {stats['total']}")
+    print(f"Index written to {os.path.dirname(npz_path)}")
+    return 0
+
+
+def _search(args):
+    from okfkit import config
+    cfg = config.load(args.config)
+    k = args.k or _rag_settings(cfg).get("top_k") or 8
+    idx = _load_index(cfg)
+    hits = idx.search(args.query, k=k, types=args.type)
+    if not hits:
+        print("No matches.")
+        return 2
+    for h in hits:
+        head = f"  · {h.heading}" if h.heading else ""
+        print(f"  {h.score:6.3f}  [{h.type or '-'}] {h.node_id} — {h.title}{head}")
+    return 0
+
+
+def _ask(args):
+    from okfkit import config, enrich
+    from okfkit.serve import ask
+    cfg = config.load(args.config)
+    rag = _rag_settings(cfg)
+    k = args.k or rag.get("top_k") or 8
+    idx = _load_index(cfg)
+    e = cfg.enrich or {}
+    backend = enrich.make_backend(
+        provider=args.provider or e.get("provider"),
+        model=args.model or e.get("model"),
+        base_url=args.base_url or e.get("base_url"),
+    )
+    answer, hits = ask(args.query, idx, backend, k=k, types=args.type)
+    print(answer)
+    if not hits:
+        return 2
+    print("\nSources:")
+    for h in hits:
+        print(f"  {h.score:6.3f}  [[{h.node_id}]] {h.title}")
+    return 0
+
+
+def _serve(args):
+    """Run the read-only MCP server (stdio). stdout belongs to the MCP
+    transport once `run()` starts — all diagnostics go to stderr."""
+    from okfkit.serve import mcp as mcpmod
+    if args.vault:
+        target = os.path.abspath(os.path.expanduser(args.vault))
+        if not os.path.isdir(target):
+            raise SystemExit(f"No vault at {target}.")
+        register = f"claude mcp add okf-wiki -- okf serve --vault {target}"
+    else:
+        from okfkit import config
+        target = config.load(args.config)
+        register = f"claude mcp add okf-wiki -- okf serve -c {os.path.abspath(args.config)}"
+    if args.no_rag:
+        register += " --no-rag"
+    print("okf MCP server starting (stdio). Register it with e.g.:", file=sys.stderr)
+    print(f"  {register}", file=sys.stderr)
+    return mcpmod.run(target, use_rag=not args.no_rag)
+
+
+def _init(args):
+    dst = "okf.config.yaml"
+    if os.path.exists(dst):
+        print(f"{dst} already exists — leaving it untouched.")
+    else:
+        with open(dst, "w", encoding="utf-8") as fh:
+            fh.write(_CONFIG_TEMPLATE)
+        print(f"Wrote {dst}")
+    if args.adapter_stub:
+        if os.path.exists("adapter.py"):
+            print("adapter.py already exists — leaving it untouched.")
+        else:
+            with open("adapter.py", "w", encoding="utf-8") as fh:
+                fh.write(_ADAPTER_TEMPLATE)
+            print("Wrote adapter.py")
+    print("\nNext: edit okf.config.yaml, then run `okf build`.")
+    return 0
+
+
+_CONFIG_TEMPLATE = """\
+adapter: markdown_folder
+adapter_options:
+  path: ./notes
+  default_type: Note
+output: ./vault
+link_style: wikilink
+link_inference:
+  concept_type: ""
+  scan_types: []
+  min_surface_len: 5
+  exclude_titles: ["References"]
+enrich:
+  provider: null
+  model: null
+  base_url: null
+  describe_types: []
+  canonicalize_type: ""
+"""
+
+_ADAPTER_TEMPLATE = '''\
+"""Custom source adapter. Point okf.config.yaml at it: adapter: adapter.py:MyAdapter"""
+
+from okfkit.model import Node, Link
+from okfkit.adapters.base import SourceAdapter
+
+
+class MyAdapter(SourceAdapter):
+    def load(self):
+        # self.options holds adapter_options from okf.config.yaml
+        # Yield one Node per knowledge item:
+        yield Node(
+            id="example-1",
+            type="Article",
+            title="Example",
+            body="# Example\\n\\nBody markdown here.",
+            frontmatter={},
+            links=[],           # e.g. [Link(target="example-2", rel="related", section="See also")]
+            tags=[],
+            aliases=[],
+        )
+'''
+
+
+if __name__ == "__main__":
+    sys.exit(main())