predicate-skill 2.0.3 → 2.0.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "predicate",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "description": "Local reasoning knowledge graph (RDF/OWL) for AI agents — 9 kg_* MCP tools + cross-platform Stop-hook turn extraction (Claude Code + Gemini CLI + OpenCode) + reasoning bridge for action data.",
   "author": {
     "name": "Nordic Agents Research",
@@ -8,7 +8,7 @@
   },
   "homepage": "https://github.com/NordicAgents/predicate#readme",
   "repository": "https://github.com/NordicAgents/predicate",
-  "license": "Apache-2.0",
+  "license": "Elastic-2.0",
   "keywords": ["mcp", "knowledge-graph", "rdf", "owl", "sparql", "reasoning"],
   "mcpServers": {
     "predicate": {

package/LICENSE

@@ -1,202 +1,93 @@
+Elastic License 2.0 (ELv2)
 
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor's trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,97 +1,375 @@
-# predicate-skill
+# Predicate
 
-Distributable Predicate package: bundled MCP server + `predicate` CLI +
-Claude Code plugin (SKILL.md + hooks + slash commands) + per-platform
-hook adapters for Cursor, Gemini CLI, VS Code Copilot, OpenCode, and
-Codex CLI. This is the install target for both the Claude Code
-marketplace and the npm path.
+**Reasoning memory for AI agents — a knowledge graph that compounds with use.**
 
-Current version: **2.0.0** (`v2.0.0-domain-agnostic-bootstrap`).
+[![npm](https://img.shields.io/npm/v/predicate-skill?label=npm&color=blue)](https://www.npmjs.com/package/predicate-skill)
+[![marketplace](https://img.shields.io/badge/Claude%20Code-Marketplace-blue)](https://github.com/NordicAgents/predicate)
+[![License: ELv2](https://img.shields.io/badge/License-ELv2-blue.svg)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/NordicAgents/predicate?style=flat&color=yellow)](https://github.com/NordicAgents/predicate/stargazers)
+[![Last commit](https://img.shields.io/github/last-commit/NordicAgents/predicate?color=green)](https://github.com/NordicAgents/predicate/commits)
+
+## The Problem
+
+An AI coding or research agent loses most of its value to two failures: it
+forgets across sessions, and it can only answer single-hop lookups. Ask
+*"why did login break?"* and a RAG system returns documents containing the
+word *login*. It cannot traverse
+`auth.ts → validateToken → jwt.verify → JWT_SECRET → .env.production`,
+cannot tell you the blast radius of a rename, and cannot say which of two
+documents contradicts the other. The "agent memory" category mostly stores
+text or vectors with light graph structure on top — it does not separate
+schema from data, does not run a reasoner, does not track provenance per
+fact, and grows without bound until the operator cleans up by hand.
+
+### How Predicate solves it
+
+Predicate is an MCP skill that gives the agent a real reasoning graph,
+not a search index.
+
+1. **RDF/OWL, not retrieval.** Facts are stored as triples in Apache Jena
+   Fuseki. A curated OWL 2 RL ruleset materializes entailments through
+   SPARQL `CONSTRUCT` rules; SHACL covers closed-world validation. The
+   model formulates SPARQL against a freshly read schema — pre-baked
+   queries are forbidden — and reads logically entailed answers, never
+   hand-derived ones.
+2. **Provenance per triple.** Every fact carries source, time, confidence,
+   and extraction method via RDF-star. Low-confidence triples stay visible
+   to queries but are excluded from the inference closure so they cannot
+   poison entailment. `kg_explain` returns the backward-chained derivation
+   for any claim with citations.
+3. **Schema as code, with a use-gated promotion loop.** The TBox lives in
+   git as Turtle. The agent never edits it directly — it proposes deltas
+   to `kg:tbox-staging`. The reasoner validates each proposal; only after
+   N successful queries inside a TTL is a delta promoted into `kg:tbox`.
+   Unused proposals expire quietly. The graph cannot thrash because the
+   gate, not the goal source, is the safety mechanism.
+4. **Goal-conditioned growth.** Concepts enter because a goal needed
+   them, not because a document mentioned them. `kg_research_goal`
+   decomposes a goal, detects schema or data gaps, and runs research only
+   where the existing graph cannot answer. Periodic generalization and a
+   reaper sweep keep size bounded.
+5. **Cross-session continuity.** A Stop hook on each platform extracts
+   typed triples from the turn — files modified, commands that succeeded
+   or failed, decisions reached — and asserts them into `kg:abox`. The
+   reasoner derives `Hotspot`, `FlakyCommand`, and `ActiveFile` from
+   action data so `kg_ask` can answer "what is unstable here?" without
+   re-reading the repo next session.
 
 ## Install
 
 Prerequisites everywhere: **Docker** (for Fuseki) and **Node 20+**.
 
-### Claude Code marketplace
+<details open>
+<summary><strong>Claude Code</strong> — plugin marketplace, fully automatic</summary>
 
-```
+**Install:**
+
+```bash
 /plugin marketplace add NordicAgents/predicate
 /plugin install predicate@predicate
 ```
 
-### npm (any MCP-capable host)
+Restart Claude Code (or `/reload-plugins`). Then start the graph:
 
 ```bash
-npm install -g predicate-skill
 predicate up
+```
+
+**Verify:**
+
+```bash
 predicate doctor
 ```
 
-Or one-shot without a global install:
+All checks should show OK. The doctor validates Docker, Fuseki, the named
+graphs, the reasoner, and plugin registration.
+
+**Slash commands:**
+
+| Command | What it does |
+|---|---|
+| `/predicate:up` | Start Fuseki and bootstrap the 9 named graphs. |
+| `/predicate:down` | Stop Fuseki, keep the volume. |
+| `/predicate:doctor` | Health check across Docker, Fuseki, TBox, tools. |
+| `/predicate:stats` | Triples, ABox, inferred, TBox counts; inferred ratio; unused-concept ratio. |
+| `/predicate:ask <question>` | Free-form question routed through `kg_ask`. |
+
+**Routing:** Automatic. The SessionStart hook injects a one-line KG
+status banner. PreToolUse, PostToolUse, and Stop hooks capture tool
+calls and extract typed session triples — no file is written to your
+project.
+
+<details>
+<summary>Alternative — MCP-only install (no hooks or slash commands)</summary>
 
 ```bash
 claude mcp add predicate -- npx -y predicate-skill
 ```
 
-### Other platforms
+This gives you all `kg_*` tools without lifecycle hooks. Good for a quick
+trial before installing the full plugin.
 
-See the platform-specific config templates and READMEs under `hooks/`:
+</details>
 
-| Platform | Subdirectory | Hook events wired |
-|---|---|---|
-| Claude Code | `hooks/` (root) | SessionStart, PreToolUse, PostToolUse, Stop |
-| Gemini CLI | `hooks/gemini-cli/` | sessionStart, preCompress, stop |
-| Cursor | `hooks/cursor/` | manual / cron only (no native events) |
-| VS Code Copilot | `hooks/vscode-copilot/` | manual / VS Code tasks |
-| OpenCode | `hooks/opencode/` | session.started, session.compacted, session.stopped |
-| Codex CLI | `hooks/codex-cli/` | manual / shell alias / cron |
+</details>
 
-## CLI
+<details>
+<summary><strong>Any MCP-capable client</strong> — npm install</summary>
 
+```bash
+npm install -g predicate-skill
+predicate up
+predicate doctor
 ```
-predicate up             # docker compose up + bootstrap graphs (then init on first run)
-predicate init           # initialize kg:tbox (community ontology / upload / empty)
-predicate down           # stop fuseki, keep the volume
-predicate doctor         # health checks (docker, fuseki, tbox)
-predicate stats          # current kg_stats output
-predicate sessionstart   # one-line KG status banner (used by hook scripts)
-predicate maintain       # reaper + generalizer + promotion sweeper
-predicate capture        # record a tool invocation in kg:usage (opt-in: PREDICATE_RAW_CAPTURE=1)
-predicate extract        # read a Stop-hook payload and assert typed triples to kg:abox
-predicate --version
-predicate --help
+
+The bundled MCP server lives at the package's `bin` entry. Point any
+MCP-over-stdio client at `predicate-skill` (or
+`node /path/to/predicate-skill/server.bundle.mjs`) with env
+`FUSEKI_URL=http://localhost:3030` and `PREDICATE_DATASET=predicate`.
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong> — MCP + maintenance scripts</summary>
+
+**Install:**
+
+1. Install context-mode globally and start Fuseki:
+
+   ```bash
+   npm install -g predicate-skill
+   predicate up
+   ```
+
+2. Copy the MCP config template to `~/.cursor/mcp.json` and replace
+   `__PLUGIN_DIR__` with the absolute path to the installed
+   `predicate-skill` directory:
+
+   ```bash
+   cp $(npm root -g)/predicate-skill/hooks/cursor/mcp.json.template ~/.cursor/mcp.json
+   ```
+
+3. Reload MCP servers (Cmd-Shift-P → "Reload MCP servers").
+
+**Verify:** Open Cursor Settings → MCP and confirm "predicate" is
+connected. In agent chat, type `predicate stats`.
+
+**Routing:** Cursor has no native SessionStart / Stop events. The
+SessionStart, PreCompact, and Stop maintenance scripts under
+`hooks/cursor/` can be wired via cron or a shell alias — see
+`hooks/cursor/README.md`.
+
+</details>
+
+<details>
+<summary><strong>Gemini CLI</strong> — MCP + sessionStart + preCompress + stop hooks</summary>
+
+**Install:**
+
+1. Install and start Fuseki:
+
+   ```bash
+   npm install -g predicate-skill
+   predicate up
+   ```
+
+2. Merge the template into `~/.gemini/settings.json`, replacing
+   `__PLUGIN_DIR__` with the absolute path to the installed
+   `predicate-skill` directory:
+
+   ```bash
+   cat $(npm root -g)/predicate-skill/hooks/gemini-cli/settings.json.template
+   ```
+
+3. Restart Gemini CLI.
+
+**Verify:** `/mcp list` should show `predicate: ... Connected`.
+
+**Routing:** Automatic via the three hook events. The Stop hook pipes
+the transcript through `predicate extract --from-stdin --platform gemini`
+so session triples land in `kg:abox` after every turn.
+
+</details>
+
+<details>
+<summary><strong>VS Code Copilot</strong> — MCP via settings.json</summary>
+
+**Install:**
+
+1. Install and start Fuseki:
+
+   ```bash
+   npm install -g predicate-skill
+   predicate up
+   ```
+
+2. Merge `hooks/vscode-copilot/settings.json.template` into your VS Code
+   `settings.json`, replacing `__PLUGIN_DIR__`. Restart VS Code.
+
+**Verify:** Open Copilot Chat and type `predicate stats`.
+
+**Routing:** VS Code Copilot does not yet expose SessionStart / PreCompact
+/ Stop events. See `hooks/vscode-copilot/README.md` for manual and
+VS Code-task wiring of the maintenance scripts.
+
+</details>
+
+<details>
+<summary><strong>OpenCode</strong> — MCP + session.started + session.compacted + session.stopped hooks</summary>
+
+**Install:**
+
+1. Install and start Fuseki:
+
+   ```bash
+   npm install -g predicate-skill
+   predicate up
+   ```
+
+2. Merge `hooks/opencode/opencode.json.template` into
+   `~/.config/opencode/opencode.json`, replacing `__PLUGIN_DIR__`.
+
+3. Restart OpenCode.
+
+**Verify:** In the OpenCode session, type `predicate stats`.
+
+**Routing:** Automatic via the three lifecycle events. The
+session.stopped hook pipes the transcript through
+`predicate extract --from-stdin --platform opencode`.
+
+</details>
+
+<details>
+<summary><strong>Codex CLI</strong> — MCP via config.toml</summary>
+
+**Install:**
+
+1. Install and start Fuseki:
+
+   ```bash
+   npm install -g predicate-skill
+   predicate up
+   ```
+
+2. Merge `hooks/codex-cli/config.toml.template` into
+   `~/.codex/config.toml`, replacing `__PLUGIN_DIR__`.
+
+**Verify:** Launch `codex` and type `predicate stats`.
+
+**Routing:** Codex CLI has no lifecycle events yet. See
+`hooks/codex-cli/README.md` for shell-alias wiring of the maintenance
+scripts.
+
+</details>
+
+<details>
+<summary><strong>Continue.dev</strong> — MCP via config.yaml</summary>
+
+In `~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: predicate
+    command: predicate-skill
+    env:
+      FUSEKI_URL: http://localhost:3030
+      PREDICATE_DATASET: predicate
 ```
 
+Then `predicate up` and restart Continue.
+
+</details>
+
+## Bootstrap modes
+
+On first `predicate up`, choose how to seed the schema:
+
+- **Community ontology** — install a bundled vocabulary (`top`,
+  `codebase`, `foaf`, `schema-org-lite`, `fhir-core`) from the catalog
+  in `packages/predicate-ontology/catalog/`.
+- **Bring your own** — upload a Turtle file as the initial TBox.
+- **Empty** — start with no schema; let the agent grow vocabulary through
+  the propose → validate → 3-uses-in-7-days promotion gate.
+
+Schema-learning is toggleable at runtime via `kg_config_set` /
+`kg_config_get`.
+
 ## MCP tools
 
-The bundled server exposes 11 tools over stdio: `kg_explore_schema`,
-`kg_ask`, `kg_assert`, `kg_explain`, `kg_propose_schema`,
-`kg_research_goal`, `kg_stats`, `kg_maintain`, `kg_capture`,
-`kg_config_get`, `kg_config_set`.
+The bundled server exposes 11 tools over stdio:
 
-Env vars consumed at runtime:
+| Tool | What it does |
+|---|---|
+| `kg_explore_schema` | Returns the TBox slice for a concept so the model uses real predicates. |
+| `kg_ask` | Executes a caller-drafted SPARQL query against asserted + inferred graphs. Logs to `kg:usage`, truncates results, supports `includeRemote: true` for peer-federated queries. |
+| `kg_assert` | Writes a triple to `kg:abox` with RDF-star provenance. Rejects undeclared predicates. |
+| `kg_explain` | Returns the backward-chained derivation for a claim, with cited provenance. |
+| `kg_propose_schema` | Stages a `SchemaDelta` proposal in `kg:tbox-staging`. |
+| `kg_research_goal` | Decompose a goal → gap-detect → optionally execute research → return a plan. |
+| `kg_stats` | Triples, ABox, inferred, TBox counts; inferred ratio; unused-concept ratio. |
+| `kg_maintain` | Runs reaper, generalizer, and promotion sweeper, then re-materializes inferred. |
+| `kg_capture` | Records a tool invocation (toolName, input, output, sessionId, phase) into `kg:usage`. Used by PreToolUse / PostToolUse hooks. |
+| `kg_config_get` / `kg_config_set` | Read or update runtime config (e.g. schema-learning toggle). |
 
-- `FUSEKI_URL` (default `http://localhost:3030`)
-- `PREDICATE_DATASET` (default `predicate`)
-- `PREDICATE_CAPTURE_SKIP` (comma list of tool names to suppress in `kg_capture`, default empty)
-- `PREDICATE_CAPTURE_TRUNCATE` (max chars per captured input/output field, default `500`)
+## CLI
+
+```
+predicate up                # docker compose up + bootstrap the 9 named graphs
+predicate init              # initialize kg:tbox (community / upload / empty)
+predicate down              # stop Fuseki, keep the volume
+predicate doctor            # health checks (docker, fuseki, tbox, tools)
+predicate stats             # current kg_stats output
+predicate sessionstart      # one-line KG status banner (used by hook scripts)
+predicate maintain          # reaper + generalizer + promotion sweeper
+predicate capture           # record a tool call in kg:usage (opt-in: PREDICATE_RAW_CAPTURE=1)
+predicate extract           # read a Stop-hook payload and assert typed triples to kg:abox
+predicate sessions          # list recent extracted sessions (modifiedFiles / ok / fail)
+predicate captures          # list raw kg:usage ToolCall captures
+predicate recall <query>    # substring search over session history (files + commands)
+predicate dashboard         # serve a localhost web view of session history + reasoning output
+
+predicate peer add <name> <sparql-endpoint>   # register a teammate's Fuseki
+predicate peer list | peer remove
+predicate export-sessions [--since DATE] [--user NAME]
+predicate import-sessions <file.trig>
+
+predicate ld init           # register DBpedia + Wikidata as external LD peers
+predicate ld list
+predicate ld ask <query>    # one-shot SPARQL across all registered LD endpoints
+
+predicate --version
+predicate --help
+```
+
+## Environment
+
+| Var | Default | What it controls |
+|---|---|---|
+| `FUSEKI_URL` | `http://localhost:3030` | Where the MCP server reaches Fuseki. |
+| `PREDICATE_DATASET` | `predicate` | Fuseki dataset name. |
+| `PREDICATE_CAPTURE_SKIP` | *(empty)* | Comma-separated tool names suppressed by `kg_capture`. |
+| `PREDICATE_CAPTURE_TRUNCATE` | `500` | Max chars per captured input/output field. |
+| `PREDICATE_RAW_CAPTURE` | unset | When `1`, raw PreToolUse/PostToolUse captures are persisted to `kg:usage`. |
+| `ANTHROPIC_API_KEY` | unset | Enables the LLM-augmented decomposer fallback in `kg_research_goal`. |
 
 ## What's in this directory
 
-- `.claude-plugin/plugin.json` — MCP server + skills + hooks registration for the Claude Code marketplace path.
-- `server.bundle.mjs` — bundled MCP server (no `node_modules` required at runtime).
-- `cli.bundle.mjs` — bundled `predicate` CLI, surfaced via this package's `bin` entry.
-- `skills/predicate/SKILL.md` — host-agent contract: triggers, workflow, HARD-GATE anti-patterns, worked examples.
-- `skills/predicate-doctor/SKILL.md`, `skills/predicate-stats/SKILL.md` — operator skills.
-- `commands/{up,down,doctor,stats,ask}.md` — slash-command definitions for `/predicate:*`.
-- `hooks/hooks.json` — Claude Code hook registration (SessionStart, PreToolUse, PostToolUse).
-- `hooks/session-start.sh`, `hooks/pre-tool-use.sh`, `hooks/post-tool-use.sh` — Claude Code lifecycle hooks; each delegates to a `predicate` CLI subcommand.
-- `hooks/{cursor,gemini-cli,vscode-copilot,opencode,codex-cli}/` — per-platform hook scripts + config templates + per-platform README.
-- `compose/docker-compose.yml`, `compose/fuseki/config.ttl` — Fuseki + TDB2 config that `predicate up` launches.
+| Path | Purpose |
+|---|---|
+| `.claude-plugin/plugin.json` | MCP + skills + hooks registration for the Claude Code marketplace. |
+| `server.bundle.mjs` | Bundled MCP server — runs without `node_modules` at runtime. |
+| `cli.bundle.mjs` | Bundled `predicate` CLI, surfaced via this package's `bin` entry. |
+| `skills/predicate/SKILL.md` | Host-agent contract: triggers, workflow, HARD-GATE anti-patterns, worked examples. |
+| `skills/predicate-doctor/`, `skills/predicate-stats/` | Operator skills. |
+| `commands/{up,down,doctor,stats,ask}.md` | Slash-command definitions for `/predicate:*`. |
+| `hooks/hooks.json` | Claude Code hook registration (SessionStart, PreToolUse, PostToolUse, Stop). |
+| `hooks/{session-start,pre-tool-use,post-tool-use,stop}.sh` | Claude Code lifecycle hooks — each delegates to a `predicate` CLI subcommand. |
+| `hooks/{cursor,gemini-cli,vscode-copilot,opencode,codex-cli}/` | Per-platform hook scripts + config templates + per-platform README. |
+| `compose/docker-compose.yml`, `compose/fuseki/config.ttl` | Fuseki + TDB2 config launched by `predicate up`. |
 
 ## Rebuilding the bundles
 
-Bundles are committed so the marketplace install path works without
+The bundles are committed so the marketplace install path works without
 `pnpm install`. To rebuild after a source change:
 
 ```bash
@@ -110,9 +388,9 @@ The full workspace test suite runs against a live Fuseki:
 
 ```bash
 predicate up
-pnpm test           # 160 tests across 5 packages
+pnpm test
 ```
 
 ## License
 
-Apache-2.0. See `LICENSE`.
+Elastic License 2.0 (ELv2) — source-available. See [`LICENSE`](LICENSE).

package/catalog/catalog.json

@@ -10,7 +10,7 @@
     {
       "name": "codebase",
       "description": "Software code structure (files, symbols, calls, modifications)",
-      "license": "Apache-2.0",
+      "license": "Elastic-2.0",
       "files": ["codebase.ttl"],
       "shapes": "codebase.shacl.ttl"
     },

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "predicate-skill",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Local reasoning knowledge graph (RDF/OWL) for AI agents — Claude Code plugin + MCP server + predicate CLI.",
   "author": {
     "name": "Nordic Agents Research",
     "email": "midhunxavier@outlook.com"
   },
-  "license": "Apache-2.0",
+  "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/NordicAgents/predicate#readme",
   "repository": {
     "type": "git",

package/server.bundle.mjs

@@ -46295,8 +46295,37 @@ Anthropic.Beta = Beta;
 var { HUMAN_PROMPT, AI_PROMPT } = Anthropic;
 var sdk_default = Anthropic;
 
+// ../predicate-agent/src/completion-provider.ts
+var ANTHROPIC_MODEL = "claude-haiku-4-5-20251001";
+var AnthropicSdkProvider = class {
+  kind = "anthropic-sdk";
+  isAvailable() {
+    return Boolean(process.env["ANTHROPIC_API_KEY"]);
+  }
+  async complete(req) {
+    const client = new sdk_default();
+    const response = await client.messages.create({
+      model: ANTHROPIC_MODEL,
+      max_tokens: req.maxTokens,
+      system: [
+        { type: "text", text: req.systemPrompt },
+        {
+          type: "text",
+          text: `<tbox-slice>
+${req.tboxSlice}
+</tbox-slice>`,
+          cache_control: { type: "ephemeral" }
+        }
+      ],
+      messages: [{ role: "user", content: `Question: ${req.question}
+
+Return the JSON.` }]
+    });
+    return response.content.filter((b2) => b2.type === "text").map((b2) => b2.text).join("\n");
+  }
+};
+
 // ../predicate-agent/src/semantic-decomposer.ts
-var MODEL = "claude-haiku-4-5-20251001";
 var VALID_INTENTS = [
   "why-broken",
   "find-callers",
@@ -46335,33 +46364,31 @@ Output strict JSON, no prose:
 }`;
 var SemanticDecomposer = class {
   deterministic = new Decomposer();
-  options;
+  providers;
+  fallbackOnEmpty;
+  /** Set to the provider actually used on the last decompose() call (for telemetry). */
+  lastProviderUsed = null;
   constructor(options = {}) {
-    this.options = { fallbackOnEmpty: options.fallbackOnEmpty ?? true };
+    this.providers = options.providers ?? [new AnthropicSdkProvider()];
+    this.fallbackOnEmpty = options.fallbackOnEmpty ?? true;
   }
   async decompose(question, tboxSlice = "") {
+    this.lastProviderUsed = null;
     const deterministicResult = this.deterministic.decompose(question);
     const allUnknown = deterministicResult.every((sq) => sq.intent.kind === "unknown");
     if (!allUnknown) return deterministicResult;
-    if (!process.env["ANTHROPIC_API_KEY"]) {
-      return this.options.fallbackOnEmpty ? deterministicResult : [];
+    const provider = this.providers.find((p2) => p2.isAvailable());
+    if (!provider) {
+      return this.fallbackOnEmpty ? deterministicResult : [];
     }
     try {
-      const client = new sdk_default();
-      const response = await client.messages.create({
-        model: MODEL,
-        max_tokens: 1024,
-        system: [
-          { type: "text", text: SYSTEM_PROMPT },
-          { type: "text", text: `<tbox-slice>
-${tboxSlice}
-</tbox-slice>`, cache_control: { type: "ephemeral" } }
-        ],
-        messages: [{ role: "user", content: `Question: ${question}
-
-Return the JSON.` }]
+      const text = await provider.complete({
+        systemPrompt: SYSTEM_PROMPT,
+        tboxSlice,
+        question,
+        maxTokens: 1024
       });
-      const text = response.content.filter((b2) => b2.type === "text").map((b2) => b2.text).join("\n");
+      this.lastProviderUsed = provider.kind;
       const stripped = text.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
       const parsed = JSON.parse(stripped);
       if (!Array.isArray(parsed.subQuestions)) return deterministicResult;
@@ -46373,10 +46400,10 @@ Return the JSON.` }]
           payload: sq.intent.payload ?? {}
         }
       }));
-      if (validated.length === 0) return this.options.fallbackOnEmpty ? deterministicResult : [];
+      if (validated.length === 0) return this.fallbackOnEmpty ? deterministicResult : [];
       return validated;
     } catch {
-      return this.options.fallbackOnEmpty ? deterministicResult : [];
+      return this.fallbackOnEmpty ? deterministicResult : [];
     }
   }
 };
@@ -47214,18 +47241,22 @@ async function buildTBoxSlice(client) {
   );
   return r2.results.bindings.map((b2) => `${b2["p"].value} a ${b2["kind"].value} .`).join("\n");
 }
-async function kgResearchGoal(client, input) {
+async function kgResearchGoal(client, input, deps = {}) {
   const baseInput = {
     goal: input.goal,
     source: input.source ?? "user",
     parentGoal: input.parentGoal
   };
-  const useSemantic = Boolean(input.useLlmDecomposer) && Boolean(process.env["ANTHROPIC_API_KEY"]);
-  const decomposerKind = useSemantic ? "semantic" : "deterministic";
+  const providers = [
+    ...deps.extraCompletionProviders ?? [],
+    new AnthropicSdkProvider()
+  ];
+  const hasAvailableLlmProvider = providers.some((p2) => p2.isAvailable());
+  const useSemantic = Boolean(input.useLlmDecomposer) && hasAvailableLlmProvider;
   if (useSemantic) {
     const store = new GoalStore(client);
     const detector = new GapDetector(client);
-    const semantic = new SemanticDecomposer();
+    const semantic = new SemanticDecomposer({ providers });
     const goal = await store.create({
       statement: baseInput.goal,
       source: baseInput.source,
@@ -47235,8 +47266,9 @@ async function kgResearchGoal(client, input) {
     const subQuestions = await semantic.decompose(baseInput.goal, tboxSlice);
     const gaps = await Promise.all(subQuestions.map((sq) => detector.detect(sq)));
     const plan2 = { goalId: goal.id, subQuestions, gaps };
+    const decomposerProvider = semantic.lastProviderUsed ?? void 0;
     if (!input.executeResearch) {
-      return { ...plan2, decomposerKind };
+      return { ...plan2, decomposerKind: "semantic", ...decomposerProvider && { decomposerProvider } };
     }
     if (!input.corpusRoot) {
       throw new Error(
@@ -47260,7 +47292,7 @@ async function kgResearchGoal(client, input) {
   }
   if (!input.executeResearch) {
     const plan2 = await researchGoal(client, baseInput);
-    return { ...plan2, decomposerKind };
+    return { ...plan2, decomposerKind: "deterministic" };
   }
   if (!input.corpusRoot) {
     throw new Error(
@@ -47280,7 +47312,7 @@ async function kgResearchGoal(client, input) {
       new EnvVarExtractor()
     ]
   });
-  return { ...plan, decomposerKind };
+  return { ...plan, decomposerKind: "deterministic" };
 }
 
 // ../predicate-mcp/src/tools/kg-propose-schema.ts
@@ -47522,7 +47554,8 @@ var schemaDeltaSchema = external_exports.discriminatedUnion("kind", [
     shapes: external_exports.array(deltaQuadSchema).optional()
   })
 ]);
-function buildTools(client) {
+function buildTools(client, options = {}) {
+  const extraCompletionProviders = options.extraCompletionProviders ?? [];
   return [
     {
       name: "kg_explore_schema",
@@ -47606,7 +47639,7 @@ function buildTools(client) {
     },
     {
       name: "kg_research_goal",
-      description: "Decompose a goal and report which predicates the live TBox can/cannot answer. When executeResearch=true and corpusRoot is provided, also fetch artifacts from that directory, extract candidate triples, and assert them via kg_assert. Set useLlmDecomposer=true to enable Claude-Haiku-backed decomposition for questions that do not match a built-in pattern (requires ANTHROPIC_API_KEY; falls back to deterministic otherwise).",
+      description: "Decompose a goal and report which predicates the live TBox can/cannot answer. When executeResearch=true and corpusRoot is provided, also fetch artifacts from that directory, extract candidate triples, and assert them via kg_assert. Set useLlmDecomposer=true to enable LLM-augmented decomposition for questions that do not match a built-in pattern; the decomposer prefers MCP sampling (no API key needed) and falls back to ANTHROPIC_API_KEY, then to deterministic.",
       inputSchema: external_exports.object({
         goal: external_exports.string().min(1),
         source: external_exports.enum(["user", "inferred"]).optional(),
@@ -47624,7 +47657,7 @@ function buildTools(client) {
           corpusRoot: external_exports.string().optional(),
           useLlmDecomposer: external_exports.boolean().optional()
         }).parse(raw);
-        return kgResearchGoal(client, args);
+        return kgResearchGoal(client, args, { extraCompletionProviders });
       }
     },
     {
@@ -47708,15 +47741,62 @@ function stubs() {
   return [];
 }
 
+// ../predicate-mcp/src/sampling-provider.ts
+var SAMPLING_MODEL_HINT = "claude-haiku";
+var SamplingProvider = class {
+  constructor(server) {
+    this.server = server;
+  }
+  server;
+  kind = "mcp-sampling";
+  isAvailable() {
+    const caps = this.server.getClientCapabilities();
+    return Boolean(caps?.sampling);
+  }
+  async complete(req) {
+    const result = await this.server.createMessage({
+      systemPrompt: `${req.systemPrompt}
+
+<tbox-slice>
+${req.tboxSlice}
+</tbox-slice>`,
+      maxTokens: req.maxTokens,
+      modelPreferences: {
+        hints: [{ name: SAMPLING_MODEL_HINT }],
+        intelligencePriority: 0.3,
+        speedPriority: 0.7
+      },
+      messages: [
+        {
+          role: "user",
+          content: { type: "text", text: `Question: ${req.question}
+
+Return the JSON.` }
+        }
+      ]
+    });
+    const content = result.content;
+    if (Array.isArray(content)) {
+      return content.filter((b2) => b2.type === "text").map((b2) => b2.text).join("\n");
+    }
+    if (content && typeof content === "object" && "type" in content && content.type === "text") {
+      return content.text;
+    }
+    return "";
+  }
+};
+
 // ../predicate-mcp/src/index.ts
 async function main() {
   const config2 = loadConfig();
   const client = new SparqlClient(config2);
-  const tools = buildTools(client);
   const server = new Server(
     { name: "predicate-mcp", version: "0.1.0" },
     { capabilities: { tools: {} } }
   );
+  const tools = buildTools(client, {
+    extraCompletionProviders: [new SamplingProvider(server)]
+  });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: tools.map((t2) => ({
       name: t2.name,