Apply /review findings for the toolkit

- propose.apply(): preserve pre-frontmatter content byte-for-byte; handle
  empty frontmatter; Proposal carries target_iri resolved at propose time
  (single IRI derivation, idempotent re-runs); link regex handles title
  attributes and angle-bracket targets; cues added for wasAttributedTo and
  joinsWith with a coverage test; dead 'see also' alternative dropped
- cli: --json composes with --apply (rows gain "applied"); single-member
  subcommand registry inlined
- schema: resolution is now ancestors-first (checkout edits always win)
  with the packaged copy as fallback; zip-safe packaged lookup;
  Vocabulary.subclasses_of(); drift-guard + resolution-order tests
- model: O(1) Bundle.get via cached IRI index; graph() parses once via a
  single @graph document; build.py assemble/to_rdf ported onto the Bundle
  API (bundle.json verified byte-identical; .nt graphs isomorphic) and the
  packaged-data refresh guarded to the lokf repo itself
- export: reified relations flagged (reified=true) and page copy states
  the flattening honestly; scalar relations entries skipped; JSON-LD
  resolves relative refs and uses the passed vocabulary; hook caches the
  bundle once per build and emits meta.source_base for the page's source
  links (no hardcoded GitHub URL in JS)
- graph page: init driven via document$ with an on-demand cytoscape
  loader — renders on direct load, instant-nav arrival, and repeated
  visits (browser-verified)
- toolkit docs: resolution-order and reified-RDF claims corrected; pip
  lockfile caveat; tutorial validate block embeds the README snippet

Author: nicholsn

docs/graph.md

@@ -4,9 +4,9 @@ Every edge below is an **RDF predicate** drawn from a concept's typed
 frontmatter relations — labels like `prov:wasDerivedFrom`, `dcterms:requires`,
 or `lokf:measures` (compacted through the LOKF
 [vocabulary](guide/relationships.md)). Plain markdown links in a concept's
-*body* are **not** edges: only the typed relations that project to RDF triples
-appear here, so this graph is exactly the concept-to-concept subset of the
-[bundle's RDF projection](examples.md).
+*body* are **not** edges. Named typed relations appear exactly as in the
+[bundle's RDF projection](examples.md); reified `relations:` entries are
+flattened to labeled edges for display (in RDF they are reified statements).
 
 The data is the [Acme knowledge bundle](examples.md) — six concepts, eight
 typed relations. Search dims non-matching nodes; the filters toggle node types
@@ -100,27 +100,74 @@ and predicates; click a node for its details.
 }
 </style>
 
-<script src="../assets/js/cytoscape.min.js"></script>
 <script>
 (function () {
-  var mount = document.getElementById("lokf-cy");
-  if (!mount || typeof cytoscape === "undefined") { return; }
+  // Material's navigation.instant swaps page content and re-executes these
+  // scripts without waiting for external <script src> tags, so the vendored
+  // cytoscape build is loaded on demand behind a shared promise, and init is
+  // driven off document$ (re-emitted on every SPA navigation) when available.
+  var CY_SRC = "../assets/js/cytoscape.min.js";
+  var DATA_SRC = "../assets/graph.json";
   // Small type -> color palette; nodes without a known type fall through.
   var PALETTE = [
     "#5b8def", "#e8833a", "#2ea77d", "#c1558b",
     "#9b6dd6", "#d2b13a", "#4bacc6", "#d05b5b"
   ];
-  var SRC_BASE =
-    "https://github.com/nicholsn/lokf/tree/main/examples/acme-knowledge/";
 
-  fetch("../assets/graph.json")
-    .then(function (r) { return r.json(); })
-    .then(function (graph) { render(graph); })
-    .catch(function (e) {
-      mount.textContent = "Could not load graph data: " + e;
+  function ensureCytoscape() {
+    if (window.cytoscape) { return Promise.resolve(); }
+    if (!window.__lokfCyLoad) {
+      window.__lokfCyLoad = new Promise(function (resolve, reject) {
+        var s = document.createElement("script");
+        s.src = CY_SRC;
+        s.onload = function () { resolve(); };
+        s.onerror = function () {
+          window.__lokfCyLoad = null;
+          reject(new Error("could not load " + CY_SRC));
+        };
+        document.head.appendChild(s);
+      });
+    }
+    return window.__lokfCyLoad;
+  }
+
+  function boot() {
+    var mount = document.getElementById("lokf-cy");
+    if (!mount || mount.dataset.lokfInit) { return; }
+    mount.dataset.lokfInit = "1";
+    Promise.all([
+      ensureCytoscape(),
+      fetch(DATA_SRC).then(function (r) {
+        if (!r.ok) { throw new Error(r.status + " " + r.statusText); }
+        return r.json();
+      })
+    ]).then(function (results) {
+      if (!mount.isConnected) { return; }  // page swapped away while loading
+      if (window.__lokfCy) {
+        try { window.__lokfCy.destroy(); } catch (e) { /* already gone */ }
+        window.__lokfCy = null;
+      }
+      window.__lokfCy = render(mount, results[1]);
+    }).catch(function (e) {
+      mount.textContent = "Could not load graph: " + (e.message || e);
     });
+  }
 
-  function render(graph) {
+  // Subscribe to document$ exactly once (this script re-runs per instant-nav
+  // visit); on themes without it, fall back to plain page-load events. All
+  // other listeners live on elements inside the swapped content (or on the
+  // cy instance we destroy), so they die with the old page.
+  if (window.document$ && typeof window.document$.subscribe === "function") {
+    if (!window.__lokfGraphSub) {
+      window.__lokfGraphSub = window.document$.subscribe(boot);
+    }
+  } else if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", boot, { once: true });
+  } else {
+    boot();
+  }
+
+  function render(mount, graph) {
     var types = [];
     graph.nodes.forEach(function (n) {
       if (types.indexOf(n.data.type) === -1) { types.push(n.data.type); }
@@ -155,7 +202,7 @@ and predicates; click a node for its details.
 
     var cy = cytoscape({
       container: mount,
-      elements: graph,
+      elements: { nodes: graph.nodes, edges: graph.edges },
       layout: { name: "cose", padding: 30, animate: false,
                 nodeRepulsion: 9000, idealEdgeLength: 130 },
       style: [
@@ -193,7 +240,8 @@ and predicates; click a node for its details.
     buildTypeFilter(cy, types, colorOf);
     buildPredicateFilter(cy, predicates);
     wireSearch(cy);
-    wireDetail(cy);
+    wireDetail(cy, graph.meta);
+    return cy;
   }
 
   function buildTypeFilter(cy, types, colorOf) {
@@ -262,7 +310,8 @@ and predicates; click a node for its details.
     });
   }
 
-  function wireDetail(cy) {
+  function wireDetail(cy, meta) {
+    var srcBase = meta && meta.source_base;
     var panel = document.getElementById("lokf-detail");
     var close = document.getElementById("lokf-detail-close");
     cy.on("tap", "node", function (evt) {
@@ -272,7 +321,12 @@ and predicates; click a node for its details.
       document.getElementById("lokf-detail-iri").textContent = d.id;
       document.getElementById("lokf-detail-cid").textContent = d.concept_id;
       var src = document.getElementById("lokf-detail-src");
-      src.href = SRC_BASE + d.concept_id + ".md";
+      if (srcBase) {
+        src.href = srcBase + d.concept_id + ".md";
+        src.hidden = false;
+      } else {
+        src.hidden = true;  // no repo_url configured: nothing to link to
+      }
       panel.hidden = false;
     });
     cy.on("tap", function (evt) {

docs/hooks/lokf_hooks.py

@@ -3,6 +3,10 @@
 Runs in CI where ``lokf`` is not installed and ``rdflib`` is absent, so the
 repo's ``src`` directory is put on ``sys.path`` and all logic lives in
 ``lokf.export`` (which derives everything from frontmatter + Vocabulary).
+
+The bundle and its projections are computed at most once per build: the cache
+is reset in ``on_config`` and filled lazily, so ``on_post_page`` (which fires
+per JSON-LD page) and ``on_post_build`` share one bundle load.
 """
 from __future__ import annotations
 
@@ -19,25 +23,59 @@
 _BUNDLE = _REPO / "examples" / "acme-knowledge"
 _JSONLD_PAGES = ("examples.md", "graph.md")
 
+_cache: dict = {}
+
+
+def on_config(config, **kwargs):
+    """Reset the per-build cache; remember ``repo_url`` for graph metadata."""
+    _cache.clear()
+    _cache["repo_url"] = (config.get("repo_url") or "").rstrip("/")
+    return config
+
+
+def _bundle():
+    if "bundle" not in _cache:
+        _cache["bundle"] = load_bundle(_BUNDLE)
+    return _cache["bundle"]
 
-def on_post_build(config, **kwargs):
-    """Write ``site/assets/graph.json`` from the example bundle's graph."""
-    out = pathlib.Path(config["site_dir"]) / "assets" / "graph.json"
-    out.parent.mkdir(parents=True, exist_ok=True)
-    graph = to_cytoscape(load_bundle(_BUNDLE))
-    out.write_text(json.dumps(graph, indent=2), encoding="utf-8")
+
+def _graph_json() -> str:
+    """The cytoscape graph + ``meta.source_base`` as a JSON string."""
+    if "graph_json" not in _cache:
+        graph = to_cytoscape(_bundle())
+        meta = {}
+        repo_url = _cache.get("repo_url", "")
+        if repo_url:
+            rel = _BUNDLE.relative_to(_REPO).as_posix()
+            meta["source_base"] = f"{repo_url}/tree/main/{rel}/"
+        graph["meta"] = meta
+        _cache["graph_json"] = json.dumps(graph, indent=2)
+    return _cache["graph_json"]
+
+
+def _jsonld_blocks() -> str:
+    if "jsonld_blocks" not in _cache:
+        _cache["jsonld_blocks"] = "\n".join(
+            '<script type="application/ld+json">' + json.dumps(doc) + "</script>"
+            for doc in dataset_search_jsonld(_bundle())
+        )
+    return _cache["jsonld_blocks"]
 
 
 def on_post_page(output, page, config, **kwargs):
     """Inject schema.org Dataset JSON-LD into the dataset-bearing pages."""
     if page.file.src_uri not in _JSONLD_PAGES:
         return output
-    blocks = "\n".join(
-        '<script type="application/ld+json">' + json.dumps(doc) + "</script>"
-        for doc in dataset_search_jsonld(load_bundle(_BUNDLE))
-    )
+    blocks = _jsonld_blocks()
     if not blocks:
         return output
     if "</article>" in output:
         return output.replace("</article>", blocks + "\n</article>", 1)
     return output + blocks
+
+
+def on_post_build(config, **kwargs):
+    """Write ``site/assets/graph.json`` from the example bundle's graph."""
+    out = pathlib.Path(config["site_dir"]) / "assets" / "graph.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(_graph_json(), encoding="utf-8")

docs/toolkit/index.md

@@ -35,6 +35,9 @@ never hardcodes a type or predicate it can read from the schema.
     pip install git+https://github.com/nicholsn/lokf
     ```
 
+    Note that pip bypasses `uv.lock` (the locked toolchain) — fine for
+    consumers of the package; contributors should use `uv sync`.
+
 Working inside a clone of this repository? `uv sync` already installs the
 package in editable mode — see [Getting started](../getting-started.md).
 
@@ -80,9 +83,11 @@ vocab.expand("prov:wasDerivedFrom")         # -> 'http://www.w3.org/ns/prov#wasD
 !!! tip "The schema travels with the package"
 
     `vocabulary()` and `load_context()` resolve `lokf.yaml` and
-    `lokf.context.jsonld` from the copies packaged inside the wheel, so an
-    installed `lokf` works outside a repo checkout. An explicit path or a
-    checkout in an ancestor directory takes precedence.
+    `lokf.context.jsonld` in this order: an explicit path argument first,
+    then a checkout found by walking up from the current directory — so
+    local schema edits always win — and only then the copies packaged
+    inside the wheel, the fallback that lets an installed `lokf` work
+    outside a repo checkout.
 
 ## Where next
 

docs/toolkit/proposer.md

@@ -12,6 +12,7 @@ uv run lokf propose mykb/                    # dry-run: table of proposals
 uv run lokf propose mykb/ --json             # same list, machine-readable
 uv run lokf propose mykb/ --min-confidence 0.5   # drop the weak ones
 uv run lokf propose mykb/ --apply --min-confidence 0.5   # write frontmatter
+uv run lokf propose mykb/ --json --apply     # apply + JSON report of what was written
 ```
 
 Or from Python:
@@ -53,8 +54,10 @@ matched against a priority-ordered table of cue patterns: wording like
 *derived / computed / built from* points at `derivedFrom`
 (`prov:wasDerivedFrom`), *depends / requires / needs* at `dependsOn`
 (`dcterms:requires`), *measures / counts* at `measures`, *part of / within*
-at `isPartOf`, *same as / alias* at `sameAs`, and so on across the
-[relation vocabulary](../guide/relationships.md). The first row that matches
+at `isPartOf`, *same as / alias* at `sameAs`, *attributed to / authored by*
+at `wasAttributedTo`, *joins with / joined on* at `joinsWith`, and so on
+across the [relation vocabulary](../guide/relationships.md). The first row
+that matches
 (and whose relation the source's type may carry) wins. A link whose sentence
 matches no cue at all falls back to a low-confidence `relatedTo` — the
 weakest, most honest claim available.
@@ -119,8 +122,19 @@ untouched. Where a proposal lands depends on the relation:
       target: https://acme.example/knowledge/tables/customers
   ```
 
-Both forms project to identical RDF, so nothing downstream cares which one a
-proposal used.
+The two forms do **not** project to identical RDF. A named slot becomes a
+direct triple with its bound predicate
+(`<metric> prov:wasDerivedFrom <dataset>`); a `relations:` entry projects as
+a [reified statement](../guide/relationships.md#custom-predicates-relations)
+— an `rdf:Statement` node reached via `lokf:relations` that carries the
+predicate and target — not a direct triple. The
+[knowledge-graph page](../graph.md) flattens reified entries back into
+labeled edges for display, so both forms look the same in the picture, but
+SPARQL over `bundle.graph()` sees the difference.
+
+`--json` composes with `--apply`: the proposals are still written, and the
+JSON output reports the outcome — every proposal that was written gains
+`"applied": true`.
 
 ## Honest limits
 

docs/toolkit/tutorial.md

@@ -115,8 +115,10 @@ session window.
 ## 3. Validate
 
 The JSON Schema validates *documents*, so there is one assembly step: fold
-the concepts (plus their resolved `id`s) into a single `KnowledgeBundle`
-JSON, exactly as `lokf-build` does for the reference bundle.
+the concepts into a single `KnowledgeBundle` JSON, injecting each concept's
+`id` where it is missing (a `setdefault`, resolved from `base_iri` + Concept
+ID — explicit `id`s are kept), exactly as `lokf-build` does for the
+reference bundle.
 
 === "Whole bundle"
 

src/lokf/build.py

@@ -18,15 +18,14 @@
     examples/weekly-active-users.nt       RDF triples for one concept
 """
 from __future__ import annotations
-import glob
 import json
 import os
 import pathlib
 import shutil
 import subprocess
 import sys
 
-from lokf.parse import isoify, parse_concept
+from lokf.model import load_bundle
 
 
 def _find_root() -> pathlib.Path:
@@ -83,26 +82,28 @@ def generate(root: pathlib.Path) -> None:
         pass
 
     # Refresh the copies packaged with the lokf toolkit so an installed wheel
-    # is self-sufficient (see lokf.schema's resolution order).
-    data = root / "src" / "lokf" / "data"
-    data.mkdir(parents=True, exist_ok=True)
-    shutil.copy(root / "lokf.yaml", data / "lokf.yaml")
-    shutil.copy(root / "lokf.context.jsonld", data / "lokf.context.jsonld")
-    print("  -> lokf.context.jsonld, lokf.schema.json, lokf.shacl.ttl, lokf.owl.ttl "
-          "(+ src/lokf/data copies)")
+    # is self-sufficient (see lokf.schema's resolution order). Only when run
+    # inside the lokf repo itself: a downstream knowledge repo that satisfies
+    # _find_root must not have a src/lokf/ tree planted in it.
+    outputs = "  -> lokf.context.jsonld, lokf.schema.json, lokf.shacl.ttl, lokf.owl.ttl"
+    if (root / "src" / "lokf" / "__init__.py").exists():
+        data = root / "src" / "lokf" / "data"
+        data.mkdir(parents=True, exist_ok=True)
+        shutil.copy(root / "lokf.yaml", data / "lokf.yaml")
+        shutil.copy(root / "lokf.context.jsonld", data / "lokf.context.jsonld")
+        outputs += " (+ src/lokf/data copies)"
+    print(outputs)
 
 
 def assemble(root: pathlib.Path) -> dict:
     """Assemble all concept files (+ root index.md metadata) into one bundle."""
-    import yaml
-    bundle_dir = root / "examples" / "acme-knowledge"
-    idx = open(bundle_dir / "index.md", encoding="utf-8").read().split("---", 2)
-    bundle = isoify(yaml.safe_load(idx[1]))
-    concepts = [
-        parse_concept(p)
-        for p in sorted(glob.glob(str(bundle_dir / "**" / "*.md"), recursive=True))
-        if os.path.basename(p) not in ("index.md", "log.md")
-    ]
+    b = load_bundle(root / "examples" / "acme-knowledge")
+    bundle = dict(b.meta)
+    concepts = []
+    for c in b.concepts:
+        doc = dict(c.data)
+        doc.setdefault("id", b.iri(c))  # no-op where frontmatter has explicit id
+        concepts.append(doc)
     bundle["concepts"] = concepts
     json.dump(bundle, open(root / "examples" / "acme-knowledge.bundle.json", "w"), indent=2)
     print(f"== assembled bundle: {len(concepts)} concepts "
@@ -123,11 +124,14 @@ def to_rdf(root: pathlib.Path, bundle: dict) -> None:
     ex = root / "examples"
     ctx = json.load(open(root / "lokf.context.jsonld"))["@context"]
 
+    # Same single-parse projection as lokf.model.Bundle.graph(): the
+    # assembled concepts already carry injected ids, so one @graph document
+    # (context compiled once) covers the whole bundle.
     whole = Graph()
-    for c in bundle["concepts"]:
-        doc = dict(c)
-        doc["@context"] = ctx
-        whole.parse(data=json.dumps(doc), format="json-ld")
+    whole.parse(
+        data=json.dumps({"@context": ctx, "@graph": bundle["concepts"]}),
+        format="json-ld",
+    )
     whole.serialize(destination=str(ex / "acme-knowledge.nt"), format="nt")
 
     metric = next(c for c in bundle["concepts"] if c["type"] == "Metric")