Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
docs: Obsidian distribution channel and agent-access model
FABIOTESS0c115ff3e15b
diff --git a/README.md b/README.mdindex 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.mdnew file mode 100644index 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.mdindex 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.