aaj3f · Aug 17, 2026 · Aug 15, 2026 · Aug 15, 2026 · Aug 15, 2026 · Aug 15, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -5,9 +5,15 @@
     "email": "ajohnson@flur.ee"
   },
   "metadata": {
-    "description": "Internal Claude Code plugins for Fluree demos and tooling"
+    "description": "Claude Code plugins for working with Fluree AI — connecting to your stack, driving the fluree CLI, and generating demo datasets"
   },
   "plugins": [
+    {
+      "name": "fluree-companion",
+      "source": "./plugins/fluree-companion",
+      "description": "Connect Claude Code to your Fluree AI (Solo) stack and work against it — discovery, human-approved device login, Space MCP registration, and playbooks that read the stack's own version-pinned docs. Includes /fluree-companion:connect.",
+      "version": "1.0.0"
+    },
     {
       "name": "fluree-dataset-generator",
       "source": "./plugins/fluree-dataset-generator",
@@ -18,7 +24,7 @@
       "name": "fluree-cli",
       "source": "./plugins/fluree-cli",
       "description": "Companion for driving the fluree CLI well — probe-first doctrine, safety rails, and Fluree AI (Solo) remote workflows. Defers all command reference to the binary's own embedded docs.",
-      "version": "1.0.1"
+      "version": "1.0.2"
     }
   ]
 }
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -54,23 +54,48 @@ jobs:
       # `fluree manifest` command) and published as a release asset by
       # fluree/db — validating against it means validating against what
       # actually shipped, without building anything. The URL lives in the
-      # facts file (single source of truth).
+      # facts file (single source of truth). fluree/db v4.1.5 ships the
+      # asset, so a missing manifest is an infrastructure failure now, not
+      # a skip (issue #2).
       - name: Download latest fluree CLI manifest
-        id: manifest
         run: |
           set -euo pipefail
           url=$(node -p "JSON.parse(require('node:fs').readFileSync('plugins/fluree-cli/contract/cli-facts.json','utf-8')).manifest_source")
-          code=$(curl -sSL -w '%{http_code}' -o /tmp/fluree-cli-manifest.json "$url" || echo 000)
-          if [ "$code" = "200" ]; then
-            echo "found=true" >> "$GITHUB_OUTPUT"
-          elif [ "$code" = "404" ]; then
-            echo "found=false" >> "$GITHUB_OUTPUT"
-            echo "::warning::fluree-cli-manifest.json is not on the latest fluree/db release yet — contract check SKIPPED (tracked to be made required in issue #2). Remove this branch once fluree/db#1571 ships in a release."
+          curl -fsSL -o /tmp/fluree-cli-manifest.json "$url"
+
+      # Every plugin that names a `fluree …` command is on the hook for it
+      # existing, not just the CLI plugin — so check each cli-facts.json.
+      - name: Check cli-facts contracts
+        run: |
+          set -e
+          for f in plugins/*/contract/cli-facts.json; do
+            echo "── $f"
+            node scripts/check-cli-contract.mjs "$f" /tmp/fluree-cli-manifest.json
+          done
+
+  stack-contract:
+    name: fluree-companion contract vs solo endpoint manifest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The endpoint manifest is generated from the Solo router's own route
+      # table and committed to fluree/solo. It does not exist on solo's main
+      # yet (fluree/solo#1041), so a 404 warns and skips — the same lifecycle
+      # the cli-contract job went through, and it flips to a hard failure
+      # here the moment that PR merges.
+      - name: Download solo router endpoint manifest
+        id: manifest
+        run: |
+          set -uo pipefail
+          url=$(node -p "JSON.parse(require('node:fs').readFileSync('plugins/fluree-companion/contract/stack-facts.json','utf-8')).manifest_source")
+          if curl -fsSL -o /tmp/endpoint-manifest.json "$url"; then
+            echo "available=true" >> "$GITHUB_OUTPUT"
           else
-            echo "::error::manifest download failed with HTTP $code — an infrastructure failure, not a missing-asset skip."
-            exit 1
+            echo "available=false" >> "$GITHUB_OUTPUT"
+            echo "::warning::endpoint manifest not published yet ($url) — skipping the stack-facts check. Remove this skip when fluree/solo#1041 merges."
           fi
 
-      - name: Check cli-facts contract
-        if: steps.manifest.outputs.found == 'true'
-        run: node scripts/check-cli-contract.mjs plugins/fluree-cli/contract/cli-facts.json /tmp/fluree-cli-manifest.json
+      - name: Check stack-facts contract
+        if: steps.manifest.outputs.available == 'true'
+        run: node scripts/check-stack-facts.mjs plugins/fluree-companion/contract/stack-facts.json /tmp/endpoint-manifest.json
diff --git a/README.md b/README.md
@@ -1,23 +1,34 @@
 # Fluree Claude Plugins
 
-Internal [Claude Code](https://code.claude.com/docs) plugins for Fluree demos and tooling.
+[Claude Code](https://code.claude.com/docs) plugins for working with **Fluree AI** — connecting
+to your stack, driving the `fluree` CLI, and generating datasets to load into it.
 
 This repository is a **Claude Code plugin marketplace**. Add it once, then install any plugin
 inside it from Claude Code — either the **Claude Desktop** app (Code mode) or the **Claude
 Code CLI** in a terminal.
 
-> New here and just want to make demo data for Fluree? Jump to
-> [Installation](#installation), install **fluree-dataset-generator**, then follow its
-> [usage guide](plugins/fluree-dataset-generator/README.md).
+> Have a Fluree AI stack and want Claude Code working against it? Jump to
+> [Installation](#installation), install **fluree-companion**, then run
+> `/fluree-companion:connect`.
 
 ---
 
 ## What's inside
 
+Three plugins, and the mental model behind them: **your stack**, **the CLI that drives it**,
+and **data to put in it**. Install the ones that match what you're doing — they're independent,
+and `fluree-companion` + `fluree-cli` are designed to be used together.
+
 | Plugin                       | What it does                                                                                                                                                                                   | Docs                                                 |
 | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| **fluree-dataset-generator** | Interviews you about a domain and generates a complete, **validated** JSON-LD dataset (RDF model + realistic instance data) ready to upload into a Fluree knowledge graph such as Fluree Solo. | [README](plugins/fluree-dataset-generator/README.md) |
+| **fluree-companion**         | Connects Claude Code to **your Fluree AI (Solo) stack** and works against it — capability discovery, the human-approved device login, Space MCP registration, and playbooks that read your stack's own version-pinned docs instead of guessing. Includes `/fluree-companion:connect`. | [README](plugins/fluree-companion/README.md)         |
 | **fluree-cli**               | Teaches Claude Code to drive the **`fluree` CLI** safely and well — probe-first use of the binary's embedded docs, destructive-op and credential safety rails, and Fluree AI (Solo) remote workflows. Includes `/fluree-cli:setup`. | [README](plugins/fluree-cli/README.md)               |
+| **fluree-dataset-generator** | Interviews you about a domain and generates a complete, **validated** JSON-LD dataset (RDF model + realistic instance data) ready to load into a Fluree knowledge graph. | [README](plugins/fluree-dataset-generator/README.md) |
+
+Why a plugin rather than a hosted service: every Fluree AI stack is its own deployment running
+its own release. So the plugins carry *choreography* — how to connect, what order to do things
+in, what not to do — while the knowledge itself stays in your stack and in your `fluree` binary,
+where it always matches the version you're actually running.
 
 _Marketplace name: `fluree-plugins` (this is what you reference when installing — see below)._
 
@@ -59,8 +70,9 @@ You only add the marketplace once; afterward you can install/update plugins free
 
 ```text
 /plugin marketplace add fluree/claude-plugins
-/plugin install fluree-dataset-generator@fluree-plugins
+/plugin install fluree-companion@fluree-plugins
 /plugin install fluree-cli@fluree-plugins
+/plugin install fluree-dataset-generator@fluree-plugins
 ```
 
 Notes:
@@ -98,8 +110,8 @@ always the same:
    **`Personal`**.
 8. Click the **`+`** icon to add a plugin repository → **`Add marketplace from GitHub`**.
 9. Type **`fluree/claude-plugins`** and click **`Sync`**.
-10. A **`Fluree dataset generator`** card appears. Hover it and click **`Install`**. Once
-    installed, the button changes to **`Manage`**.
+10. A card appears for each plugin in this marketplace. Hover the one you want and click
+    **`Install`**. Once installed, the button changes to **`Manage`**.
 11. Back out to the main session with **`Code`** selected at the top — you're ready to use it.
 
 ### Option C — Team / non-interactive (settings.json)
@@ -115,7 +127,8 @@ To pre-register the marketplace and auto-enable plugins for a project or team, a
     }
   },
   "enabledPlugins": {
-    "fluree-dataset-generator@fluree-plugins": true
+    "fluree-companion@fluree-plugins": true,
+    "fluree-cli@fluree-plugins": true
   }
 }
 ```
@@ -129,20 +142,23 @@ commands. Project-scoped marketplaces prompt users to trust them before loading.
 
 Once installed, each plugin contributes a **Skill** that you can invoke three ways:
 
-- **Ask in plain English** — skills auto-trigger on intent, e.g. _"generate a demo insurance
-  dataset for Fluree"_ or _"connect the fluree CLI to my stack."_ You don't have to name the
-  plugin.
+- **Ask in plain English** — skills auto-trigger on intent, e.g. _"connect Claude Code to my
+  Fluree stack"_, _"generate a demo insurance dataset for Fluree"_, or _"query this ledger from
+  the CLI."_ You don't have to name the plugin.
 - **Desktop menu** — `+` → **Plugins → \<plugin\> → Skills** (inserts the skill's slash
   command, then press **Enter**).
-- **CLI slash command** — `/fluree-dataset-generator:fluree-dataset-generator`, or for the
-  CLI companion `/fluree-cli:setup` (its skill auto-triggers; `setup` is the explicit entry
-  point).
-
-Each plugin's own README has the full usage guide. For the dataset generator — including the
-interview questions, scale guidance, and how to **upload the output into Fluree Solo** — see
+- **CLI slash command** — `/fluree-companion:connect` to set up a stack connection,
+  `/fluree-cli:setup` to set up the binary, or
+  `/fluree-dataset-generator:fluree-dataset-generator` to generate data. (The skills
+  auto-trigger; these are the explicit entry points.)
+
+Each plugin's own README has the full usage guide — the stack companion's connection
+choreography and contract checks in
+**[plugins/fluree-companion/README.md](plugins/fluree-companion/README.md)**, what the CLI skill
+enforces and how it stays in sync with the binary in
+**[plugins/fluree-cli/README.md](plugins/fluree-cli/README.md)**, and the dataset generator's
+interview questions, scale guidance, and load instructions in
 **[plugins/fluree-dataset-generator/README.md](plugins/fluree-dataset-generator/README.md)**.
-For the CLI companion — what the skill enforces, the MCP docs server, and how it stays in
-sync with the CLI — see **[plugins/fluree-cli/README.md](plugins/fluree-cli/README.md)**.
 
 ---
 
@@ -152,7 +168,7 @@ sync with the CLI — see **[plugins/fluree-cli/README.md](plugins/fluree-cli/RE
 | ---------------------------- | ---------------------------------------------------------------- |
 | Open the plugin UI           | `/plugin`                                                        |
 | Update this marketplace      | `/plugin marketplace update fluree-plugins`                      |
-| Update an installed plugin   | re-run `/plugin install fluree-dataset-generator@fluree-plugins` |
+| Update an installed plugin   | re-run `/plugin install fluree-companion@fluree-plugins`         |
 | Enable / disable / uninstall | `/plugin` → **Installed** tab                                    |
 
 In Claude Desktop, the **`Manage`** button on a plugin card (or **Plugins → Manage Plugins**)
@@ -166,32 +182,55 @@ covers update/disable/uninstall.
 claude-plugins/
 ├── .claude-plugin/
 │   └── marketplace.json                 # marketplace manifest (name: "fluree-plugins")
-├── .github/workflows/ci.yml             # validate --strict, version sync, CLI contract check
+├── .github/workflows/ci.yml             # validate --strict, version sync, contract checks
 ├── scripts/
 │   ├── check-version-sync.mjs           # marketplace ↔ plugin.json version invariant
-│   └── check-cli-contract.mjs           # cli-facts vs the fluree CLI's release manifest
+│   ├── check-cli-contract.mjs           # cli-facts vs the fluree CLI's release manifest
+│   └── check-stack-facts.mjs            # stack-facts vs solo's router endpoint manifest
 └── plugins/
-    ├── fluree-dataset-generator/
+    ├── fluree-companion/
     │   ├── .claude-plugin/
-    │   │   └── plugin.json              # plugin manifest (name, version, author)
-    │   ├── README.md                    # plugin usage guide
+    │   │   └── plugin.json
+    │   ├── README.md
+    │   ├── commands/connect.md          # /fluree-companion:connect
+    │   ├── contract/
+    │   │   ├── stack-facts.json         # every stack path/slug/tool the plugin names
+    │   │   └── cli-facts.json           # the fluree commands its choreography names
     │   └── skills/
-    │       └── fluree-dataset-generator/
-    │           ├── SKILL.md             # the skill's instructions to Claude
-    │           └── scripts/             # Python validators run during generation
-    └── fluree-cli/
+    │       └── fluree-companion/
+    │           ├── SKILL.md             # stack-first operating doctrine
+    │           └── references/          # connect choreography, stack knowledge, playbooks
+    ├── fluree-cli/
+    │   ├── .claude-plugin/
+    │   │   └── plugin.json
+    │   ├── README.md
+    │   ├── .mcp.json                    # auto-connects `fluree mcp serve --toolsets docs`
+    │   ├── commands/setup.md            # /fluree-cli:setup
+    │   ├── contract/cli-facts.json      # every CLI fact the plugin hard-codes (CI-checked)
+    │   └── skills/
+    │       └── fluree-cli/
+    │           ├── SKILL.md             # probe-first operating doctrine
+    │           └── references/          # workflows, remote/Fluree AI, policy, troubleshooting
+    └── fluree-dataset-generator/
         ├── .claude-plugin/
-        │   └── plugin.json
-        ├── README.md
-        ├── .mcp.json                    # auto-connects `fluree mcp serve --toolsets docs`
-        ├── commands/setup.md            # /fluree-cli:setup
-        ├── contract/cli-facts.json      # every CLI fact the plugin hard-codes (CI-checked)
+        │   └── plugin.json              # plugin manifest (name, version, author)
+        ├── README.md                    # plugin usage guide
         └── skills/
-            └── fluree-cli/
-                ├── SKILL.md             # probe-first operating doctrine
-                └── references/          # workflows, remote/Fluree AI, policy, troubleshooting
+            └── fluree-dataset-generator/
+                ├── SKILL.md             # the skill's instructions to Claude
+                └── scripts/             # Python validators run during generation
 ```
 
+### How the plugins stay honest
+
+Both companions defer their reference material to a producer — the `fluree` binary's embedded
+docs, and your stack's own served docs — so they can't go stale when either one ships a new
+release. The few facts their prose *does* hard-code live in a `contract/` file per plugin and
+are validated in CI against an artifact the producer publishes: `cli-facts.json` against the
+`fluree-cli-manifest.json` release asset from fluree/db, and `stack-facts.json` against the
+generated router endpoint manifest from fluree/solo. If a release changes something a plugin
+says, CI fails here before a user hits it.
+
 ---
 
 ## For maintainers — adding a plugin

diff --git a/plugins/fluree-cli/.claude-plugin/plugin.json b/plugins/fluree-cli/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "fluree-cli",
   "description": "Companion for driving the fluree CLI well — probe-first doctrine, safety rails, and Fluree AI (Solo) remote workflows. Defers all command reference to the binary's own embedded docs.",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "author": {
     "name": "Fluree Dev Rel"
   },

diff --git a/plugins/fluree-cli/README.md b/plugins/fluree-cli/README.md
@@ -13,6 +13,10 @@ Teaches Claude Code to drive the [`fluree`](https://github.com/fluree/db) CLI sa
 
 Requires **fluree ≥ 4.1.4** (the floor set by `fluree auth token`; the `fluree model` governance family needs 4.1.3+).
 
+## Working against a deployed stack?
+
+Install **[fluree-companion](../fluree-companion/README.md)** alongside this one. It owns the stack-first half: discovery via `/.well-known/fluree.json`, the guided `/fluree-companion:connect`, registering a Space's MCP server, and reading a stack's own version-pinned docs rather than recalling platform knowledge. This plugin stays the authority on the binary; that one routes the data and admin work back here.
+
 ## Install
 
 ```text

diff --git a/plugins/fluree-cli/skills/fluree-cli/SKILL.md b/plugins/fluree-cli/skills/fluree-cli/SKILL.md
@@ -37,6 +37,8 @@ Prefer structured output when parsing: `query` and `multi-query` take `--format
 
 `--remote <name>` takes a configured **alias**, never a URL. The full connection choreography — `remote add`, the device-code login where the *human* approves in a browser, token scripting, and what differs between local and server-routed execution — is in `references/remote-fluree-ai.md`. The one thing to never forget: **`fluree auth login` blocks on the user approving a device code at the stack's `/activate` page** — run it, tell the user to approve, and verify with `fluree auth status` before continuing.
 
+When the work is really *about the stack* rather than about the CLI — connecting a fresh machine to one, asking what a particular stack can do, or answering a how-do-I question whose answer lives in the stack's own docs — that is the **`fluree-companion`** plugin's job (same marketplace; `/fluree-companion:connect` is its guided setup). It probes `/.well-known/fluree.json` for capabilities and the minimum CLI version, reads the stack's version-pinned docs instead of recalling platform knowledge, and hands data and admin operations back to this skill.
+
 ## Common flows
 
 Step-by-step recipes (create→insert→query, bulk import, branch/merge, Iceberg mapping, app-building against a Fluree AI stack): `references/workflows.md`. Debugging divergences (server-routed vs `--direct`, time-travel formatting rules, auto-routing): `references/troubleshooting.md`.
diff --git a/plugins/fluree-companion/.claude-plugin/plugin.json b/plugins/fluree-companion/.claude-plugin/plugin.json
@@ -0,0 +1,9 @@
+{
+  "name": "fluree-companion",
+  "description": "Stack-first companion for Fluree AI (Solo) — connection choreography and playbooks that defer to the stack's own version-pinned knowledge. Includes /fluree-companion:connect.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Fluree Dev Rel"
+  },
+  "homepage": "https://github.com/fluree/claude-plugins/tree/main/plugins/fluree-companion"
+}