Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

docs: Obsidian distribution channel and agent-access model

FABIOTESS0c115ff3e15b
diff --git a/README.md b/README.md
index a51abf5a..0a391bdf 100644
--- a/README.md
+++ b/README.md
@@ -192,6 +192,15 @@ Add to `.cursor/mcp.json` or equivalent:
</details>
+<details>
+<summary><strong>Obsidian</strong></summary>
+
+The [Open Ontologies plugin for Obsidian](https://github.com/fabio-rovai/obsidian-open-ontologies) runs this engine as a managed sidecar inside Obsidian: ontology tree, SPARQL console, validation panel, validate-on-save for Turtle files, and a vault-to-RDF mapper so your notes become a graph the reasoners can work on. It also exposes the engine over MCP on a stable authenticated loopback port, so Claude Code or Claude Desktop can query the reasoned vault graph. Desktop only; the plugin auto-downloads the pinned engine release, or point it at an existing binary.
+
+See [docs/obsidian.md](docs/obsidian.md) for the settings reference and the agent-access model.
+
+</details>
+
<details>
<summary><strong>HTTP transport (<code>serve-http</code>)</strong></summary>
diff --git a/docs/obsidian.md b/docs/obsidian.md
new file mode 100644
index 00000000..c4d976c6
--- /dev/null
+++ b/docs/obsidian.md
@@ -0,0 +1,51 @@
+# Obsidian
+
+Open Ontologies ships as an Obsidian plugin alongside the Rust binary, the Docker image and the PyPI package. The plugin runs **this engine** as a managed sidecar, so every tool is available inside Obsidian, reasoners included.
+
+Repository: [fabio-rovai/obsidian-open-ontologies](https://github.com/fabio-rovai/obsidian-open-ontologies)
+
+## What it does
+
+Two planes of data, both first-class:
+
+1. **Ontology files in the vault.** `.ttl`, `.owl`, `.rdf` and `.jsonld` files get validate-on-save with inline diagnostics, plus reason, classify, diff and lint commands. An ontology tree pane and a SPARQL console give you a workbench without leaving Obsidian.
+2. **The vault itself as RDF.** Notes become individuals, `type:` frontmatter becomes `rdf:type`, Dataview-style `property:: [[Target]]` inline fields become object properties, plain wikilinks become a configurable predicate, and tags become SKOS concepts. Once compiled, the vault is reasoned over and SHACL-validated against shapes stored in the vault.
+
+## Agent access over MCP
+
+The sidecar is `open-ontologies serve-http`, so it is already an MCP server. The plugin binds it to a stable loopback port (default 27125) with a generated bearer token and offers a one-click config copy, which means Claude Code or Claude Desktop can query the reasoned vault graph directly.
+
+This is deliberately not a file-access integration. `mcp-obsidian` with the Local REST API plugin already gives an agent read, write and search over vault files; the two compose. What this channel adds is reasoning: entailment, SHACL conformance, and SPARQL over a typed graph.
+
+```json
+{
+ "mcpServers": {
+ "open-ontologies": {
+ "type": "http",
+ "url": "http://127.0.0.1:27125/mcp",
+ "headers": { "Authorization": "Bearer YOUR_TOKEN" }
+ }
+ }
+}
+```
+
+Authentication is mandatory and not configurable off. The HTTP router applies permissive CORS, so an unauthenticated listener on a fixed, documented port would be reachable cross-origin from any page in the user's browser. The bearer layer wraps `/api` and `/mcp` (only `/health` sits outside it), so the token closes that hole.
+
+## Starter vocabulary
+
+Entailment over an untyped vault is vacuous: without types and typed relations, the graph is a bag of "links to" triples and OWL-RL derives nothing worth querying. The plugin therefore ships a starter ontology, installed by command, defining `Note`, `Person`, `Project`, `Task`, `Source`, `Idea` and `Topic`, with `partOf` declared `owl:TransitiveProperty` and `relatesTo` declared `owl:SymmetricProperty`, plus SHACL shapes. Those two property characteristics are what give the reasoner something to derive.
+
+## Settings reference
+
+| Setting | Meaning |
+| --- | --- |
+| Engine binary path | Empty auto-downloads the pinned release (checksum-verified). Set a path to reuse an existing install. |
+| Vault mapping rules (YAML) | Overrides for `iriBase` (default `vault:`), `typeKey` (`type`), `iriKey` (`iri`), `defaultLinkPredicate` (`vault:linksTo`), `tagPredicate` (`vault:hasTag`), `skipKeys` (`aliases`, `cssclasses`, `tags`). |
+| Auto-sync vault to graph | Recompiles the vault ten seconds after the last note change so an MCP client always queries current data. |
+| MCP port | Stable loopback port for external MCP clients. Falls back to an ephemeral port if occupied. |
+| Copy MCP client config | Copies a ready-to-paste JSON block with the URL and token. |
+| Regenerate access token | Issues a new token and restarts the engine, invalidating previously copied configs. |
+
+## Compatibility
+
+The plugin pins a compatible engine range (`^1.1`) and blocks with an update prompt rather than running against a skewed version.
diff --git a/docs/superpowers/plans/2026-08-14-obsidian-plugin.md b/docs/superpowers/plans/2026-08-14-obsidian-plugin.md
index 11d63a2d..ff8d03d2 100644
--- a/docs/superpowers/plans/2026-08-14-obsidian-plugin.md
+++ b/docs/superpowers/plans/2026-08-14-obsidian-plugin.md
@@ -2464,5 +2464,9 @@ Open the PR following their template (checklist: release assets present, `isDesk
## Self-review notes
- Spec coverage: sidecar lifecycle (T7), full-tool access via `call()` (T5), both data planes (T4 files via T9/T10 commands), three panes (T10-T12), validate-on-save (T10), settings + log (T9), error handling (T7 backoff/version gate, T9 notices), testing (per-task + T13 e2e + CI), distribution (T14/T16), engine README (T15). Loopback-only: engine defaults to 127.0.0.1 and we pass `--host 127.0.0.1` explicitly (T7), satisfying the spec's security decision with no engine change.
-- Known reality-check points are concentrated in T13 (e2e): `onto_load` argument names and `onto_query` output shape. Both have explicit correction instructions. The `onto_diff` (`old_path`/`new_path`, verified in engine `src/server.rs`) names are confirmed; `onto_pack`/`onto_unpack` argument names should be confirmed against `OntoPackInput`/`OntoUnpackInput` in engine `src/server.rs` during Task 9 and corrected in place if they differ from `{path}`.
+- Known reality-check points were concentrated in T13 (e2e). **All three were wrong in the plan and have been corrected in the implementation** (verified against engine v1.1.1 at `target/release/open-ontologies`):
+ 1. **SSE priming frame.** The engine opens every stream with `data: \nid: 0\nretry: 3000\n\n` — an empty `data:` payload. A parser that `JSON.parse`s every `data:` line throws `Unexpected end of JSON input` on the first call. `EngineClient.post` now skips empty payloads, tolerates `\r`, and ignores unparseable frames. The mock server in `tests/client.test.ts` emits the priming frame so this stays covered.
+ 2. **`onto_load` arguments.** Takes `turtle` (inline) or `path`, plus optional `name` / `auto_refresh` / `force_recompile` — **not** `input`/`inline`. Confirmed in engine `src/inputs.rs:25`. Other tools were as planned: `onto_validate`/`onto_lint` take `input`+`inline`, `onto_shacl` takes `shapes`, `onto_reason` takes `profile`, `onto_diff` takes `old_path`/`new_path`, `onto_query` takes `query`.
+ 3. **`onto_query` output.** Returns `{"variables": [...], "results": [{var: term}, ...]}` — a third shape, and the terms are raw RDF serializations (`<vault:X>`, `"lit"@en`, `"1815"^^<...>`). Left unnormalized, angle brackets propagate into the tree view's `iriBase` prefix check and the inferred-connections labels. `parseBindings` now handles the engine shape and normalizes every term centrally via `normalizeTerm`.
+- The e2e also verifies two claims the design rests on: an unauthenticated MCP call is rejected, and the starter ontology's transitive `partOf` actually entails `T1 partOf Prog` from `T1 partOf P1 partOf Prog`. The `onto_diff` (`old_path`/`new_path`, verified in engine `src/server.rs`) names are confirmed; `onto_pack`/`onto_unpack` argument names should be confirmed against `OntoPackInput`/`OntoUnpackInput` in engine `src/server.rs` during Task 9 and corrected in place if they differ from `{path}`.
- Deferred consciously: registering a text editor view for `.ttl` (Obsidian cannot edit non-md files without a custom view; validate-on-save still works when files are edited externally or via other plugins, and the workbench commands accept the active file when opened with other viewers). If in-Obsidian ttl editing is wanted, add a `TextFileView` in v0.2.