fluree-cli plugin: probe-first CLI companion with a manifest-checked contract

[aaj3f]

Why

Fluree AI already hands its users' AI assistants off to the fluree CLI (the Build-an-App prompt, the LLM-targeted served docs). This plugin is the Claude-Code-native half of that story: it packages the operating doctrine — how to drive the CLI safely — while deliberately refusing to carry command reference, which the binary itself serves version-exactly via its embedded docs. That division is what keeps the plugin from drifting: most CLI changes require zero plugin changes, and the few facts the plugin does hard-code are machine-validated in CI.

What

plugins/fluree-cli/:

• Skill (auto-triggers on Fluree/terminal work): probe-first rule (check fluree docs / --help / the MCP docs tools before composing commands; a missing command usually means a feature-gated build), safety rails (destructive-op confirmation for drop/branch drop, .fluree/ token hygiene, auth token vs config list --reveal, explicit import budgets on shared machines, policy-correlation verification), machine-output map, and the Fluree AI remote choreography — including that fluree auth login blocks on the human approving a device code at the stack's /activate page. Deep material in references/ (workflows, remote-fluree-ai, policy, troubleshooting).
• /fluree-cli:setup: binary check + install pointers, the ≥ 4.1.3 version gate, docs-access verification, duplicate-MCP-registration cleanup, .fluree/ gitignore hygiene.
• .mcp.json: auto-connects fluree mcp serve --toolsets docs (the binary's embedded, version-exact documentation as docs_search/docs_get/docs_examples/docs_tree). Missing binary degrades gracefully.
• contract/cli-facts.json + scripts/check-cli-contract.mjs: every command path and flag the plugin's text mentions, validated against the fluree-cli-manifest.json release asset that fluree/db now publishes (a JSON surface description generated from the CLI's own clap definitions, so it cannot drift from the binary).
• CI (.github/workflows/ci.yml): claude plugin validate --strict over every plugin in the marketplace, a marketplace↔plugin version-sync check (both verified passing locally), and the contract check — which skips with a notice until the first fluree/db release ships the manifest asset, then should be made required.

Cross-repo pairing

• CLI agent-surface truth + the manifest rail db#1571 (feat/cli-ai-surface): ships the hidden fluree manifest command + the fluree-cli-manifest.json release asset this repo's CI validates against, plus docs/ai/claude-code.md — the in-binary agent guide this skill defers to.
• fluree/solo#893 (feat/cli-ai-surface): the platform half (its cli-snippets module rides the same manifest rail; its Build-an-App prompt and this plugin divide labor — prompt = per-stack bootstrap, plugin = durable procedure).

This PR is safe to land before either: the contract check self-skips until the manifest asset exists.

Validation

claude plugin validate --strict: ✔ both plugins and the marketplace root. check-version-sync.mjs: ✔ 2 plugins. Contract checker run against a locally built manifest from fluree/db#1571's branch: 42 commands OK — and its very first run caught a real error in my own draft (fluree list has no --json; the skill text shipped corrected), which is the rail doing its job.

Notes for reviewers

• The skill's description is the auto-trigger surface — worth a critical read.
• Naming (fluree-cli, hence /fluree-cli:setup) follows the settled decision to leave room for future platform-side plugins.
• Follow-up once a fluree/db release ships the manifest: flip the CI contract step from skip-if-absent to required, and pin min_cli_version messaging if the release number differs from 4.1.3-era expectations.