@passioncode-ai/passioncode 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.1.10 - 2026-09-30
+
+### Changed
+
+- Fabric Agent Adapter 0.5.1 in the set (`family.json` pins `v0.5.1`, was `v0.5.0`): the kits follow the
+  contract rulings of DEC-0017 — full result envelope with its trace for jobs, a job tool's
+  `outputSchema` as the union of envelope and handle, `providers/` entries carrying `providerId`.
+
+## 0.1.9 - 2026-09-30
+
+### Changed
+
+- Fabric Agent Adapter 0.5.0 in the set (`family.json` pins `v0.5.0`, was `v0.4.3`); Observatory
+  Log stays at Observatory `v0.8.2`, still its latest tag.
+
+### Fixed
+
+- The CLI help, `README.md` and `SECURITY.md` told people to run `npx passioncode <command>`.
+  No unscoped `passioncode` package exists on npm (`npm view passioncode` → E404), so those
+  commands failed on any machine without a local install, and a squatted name would have run
+  someone else's code. They now name `npx @passioncode-ai/passioncode@latest <command>`.
+- `README.md` gains a quick start for a new teammate: install, configure, MCP, develop.
+
 ## 0.1.8 - 2026-09-29
 
 ### Added

package/README.md

@@ -18,6 +18,23 @@ npx @passioncode-ai/passioncode@latest update
 Only PassionCode.ai products are members. Agents that people build for themselves stay
 out of it, even when they implement Fabric protocols.
 
+## Quick start for a new teammate
+
+1. **Install** (Node 18 or newer; the Claude Code CLI on `PATH` for the plugins):
+   `npx @passioncode-ai/passioncode@latest update`, then restart your agents. Check it with
+   `npx @passioncode-ai/passioncode@latest status` (every member `claude: plugin · hub: n/n`) and
+   `claude plugin list` (three plugins `@passioncode`). Always call the scoped package: there is
+   no unscoped `passioncode` package on npm.
+2. **Configure:** nothing to set, no account and no key. Background updates are on by default;
+   `npx @passioncode-ai/passioncode@latest config set update.auto off` turns them off.
+3. **MCP:** none. The launcher installs skills and session hooks; it neither serves nor calls an
+   MCP server. The tools that do (Fabric Switchboard, Fabric Inbox) document their own.
+4. **Develop:** clone, then `npm test` — there are no dependencies and no lockfile, so there is
+   nothing to install (`npm ci` refuses to run here). `npm run vendor` builds `payload/` from the
+   members pinned in `family.json`; `claude plugin validate ./payload --strict` checks it. Start
+   in `lib/launcher.js` (update, restore, status, uninstall) and `bin/passioncode.js` (the CLI);
+   [AGENTS.md](AGENTS.md) maps the rest and [CONTRIBUTING.md](CONTRIBUTING.md) the rules.
+
 ## How it installs
 
 - **Claude Code** gets plugins from a local marketplace named `passioncode` at
@@ -31,7 +48,7 @@ out of it, even when they implement Fabric protocols.
   the machine.
 - Nothing is written to `~/.claude/skills`: a plain copy there shadows the plugin. Such
   copies, and hub entries that pointed at a repository's working tree, are moved into
-  `~/.passioncode/quarantine/` — `npx passioncode restore` puts them back.
+  `~/.passioncode/quarantine/` — `npx @passioncode-ai/passioncode@latest restore` puts them back.
 - Each version is an immutable release under `~/.passioncode/releases/<version>`.
 
 ## Staying current
@@ -41,12 +58,12 @@ day and, when a newer set is out **and every npm account that publishes it is in
 plugin's `trust.json`**, updates to that exact version in the background — it takes
 effect in the next session. A version published by anyone else is named and not
 installed ([SECURITY.md](SECURITY.md#the-self-update-and-who-it-trusts)).
-`npx passioncode config set update.auto off` makes it only say so.
+`npx @passioncode-ai/passioncode@latest config set update.auto off` makes it only say so.
 
 ```bash
-npx passioncode status      # the installed release: its members, their channels, shadows
-npx passioncode update --dry-run
-npx passioncode uninstall
+npx @passioncode-ai/passioncode@latest status   # the installed release: its members, their channels, shadows
+npx @passioncode-ai/passioncode@latest update --dry-run
+npx @passioncode-ai/passioncode@latest uninstall
 ```
 
 ## Release (maintainers)

package/SECURITY.md

@@ -40,7 +40,7 @@ published (npm E404) is silent; a failed check is shown once.
 `trust.json` ships **empty**, so auto-update stays inert until the maintainers name the
 npm account(s) that publish PassionCode. Adding an account there is a release decision:
 it is reviewed like code and ships in the package. A person who wants no background
-updates at all runs `npx passioncode config set update.auto off`.
+updates at all runs `npx @passioncode-ai/passioncode@latest config set update.auto off`.
 
 The published package carries skill text only; the vendor step refuses to build when it
 finds a credential-shaped string, or when the self plugin has no valid `trust.json`.

package/bin/passioncode.js

@@ -4,11 +4,11 @@ const L = require('../lib/launcher');
 
 const HELP = `passioncode — every PassionCode.ai skill, for every agent on this machine
 
-  npx @passioncode-ai/passioncode@latest update [--dry-run] [--json]   install or update the whole set
-  npx passioncode status [--json]                       what is installed where
-  npx passioncode restore                               put back what the last update moved aside
-  npx passioncode config set update.auto on|off         background updates at session start
-  npx passioncode uninstall                             remove the set (quarantined items stay restorable)
+  npx @passioncode-ai/passioncode@latest update [--dry-run] [--json]     install or update the whole set
+  npx @passioncode-ai/passioncode@latest status [--json]                 what is installed where
+  npx @passioncode-ai/passioncode@latest restore                         put back what the last update moved aside
+  npx @passioncode-ai/passioncode@latest config set update.auto on|off   background updates at session start
+  npx @passioncode-ai/passioncode@latest uninstall                       remove the set (quarantined items stay restorable)
 
 Claude Code gets plugins from the local "passioncode" marketplace; other agents get
 the same skills through ~/.agents/skills. Restart your agent after an update.`;

package/family.json

@@ -8,7 +8,7 @@
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "repo": "passioncode-ai/fabric-agent-adapter",
-      "ref": "v0.4.3",
+      "ref": "v0.5.1",
       "kind": "plugin",
       "path": "plugins/fabric-agent-adapter",
       "legacyPluginIds": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/passioncode",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Every PassionCode.ai agent skill — Fabric Agent Adapter, Observatory Log and the organisation's working rules — for Claude Code and every other agent on the machine, updated as one set.",
   "bin": {
     "passioncode": "bin/passioncode.js"

package/payload/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "source": "./plugins/fabric-agent-adapter",
-      "version": "0.4.3",
+      "version": "0.5.1",
       "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
       "author": {
         "name": "PassionCode.ai",
@@ -35,7 +35,7 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "source": "./plugins/passioncode",
-      "version": "0.1.8",
+      "version": "0.1.10",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/manifest.json

@@ -1,15 +1,15 @@
 {
   "family": "passioncode",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "release": true,
   "members": [
     {
       "name": "fabric-agent-adapter",
       "displayName": "Fabric Agent Adapter",
       "repo": "passioncode-ai/fabric-agent-adapter",
-      "ref": "v0.4.3",
-      "commit": "c1a57abd7889c3aed1b0e97b00d4e089cc53036e",
-      "version": "0.4.3",
+      "ref": "v0.5.1",
+      "commit": "761be46e5047879f65630cbb05a82344220f0175",
+      "version": "0.5.1",
       "via": "clone of https://***@github.com/passioncode-ai/fabric-agent-adapter.git",
       "skills": [
         "adapting-projects-to-fabric",
@@ -22,7 +22,7 @@
       "legacyMarketplaces": [
         "fabric-agent-adapter"
       ],
-      "contentHash": "sha256:7074066a0046ac055a6545f44bf2729d316047710e39846ce666b254620aff34",
+      "contentHash": "sha256:b3dd5a474a99f51fefa353134f47f23730251ccec7b9052327be0e338ceffef2",
       "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
       "author": {
         "name": "PassionCode.ai",
@@ -61,16 +61,16 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "repo": "passioncode-ai/passioncode",
-      "ref": "v0.1.8",
+      "ref": "v0.1.10",
       "commit": null,
-      "version": "0.1.8",
+      "version": "0.1.10",
       "via": "this repository",
       "skills": [
         "working-in-passioncode"
       ],
       "legacyPluginIds": [],
       "legacyMarketplaces": [],
-      "contentHash": "sha256:e233f0c95abb4f060aa8428c4a1509e4ef1a3777b5597a6771d7abd2a3a439ef",
+      "contentHash": "sha256:57360b29ce3e8dcd3e846ed94c1798385400bc68c43e40c398869e459dd3f9cc",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,9 +5,9 @@ license: PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned private fabric-agent-contract checkout. Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.4.3"
+  version: "0.5.1"
   contract-version: "0.1.0"
-  contract-commit: "a5a27092ba0dcc5facfbeae8b359146dfb403e9a"
+  contract-commit: "9cd778eb6f14b977f9a5b4930826f62dc95c5619"
 ---
 
 # Adapting projects to Fabric
@@ -70,7 +70,7 @@ Use exactly:
 
 - contract version `0.1.0`;
 - repository `https://github.com/passioncode-ai/fabric-agent-contract`;
-- commit `a5a27092ba0dcc5facfbeae8b359146dfb403e9a`.
+- commit `9cd778eb6f14b977f9a5b4930826f62dc95c5619`.
 
 Read the pinned contract's guide
 `docs/guides/connecting-compatible-agents.md`, the selected profile specification, and
@@ -93,7 +93,10 @@ python3 <skill-dir>/scripts/adapt_project.py scaffold <project-root> \
   --schema-base https://agents.example/fabric
 ```
 
-Valid profiles are `mcp`, `a2a`, and `local-runner`. The helper creates only the locked
+Valid profiles are `mcp`, `a2a`, and `local-runner`. For `mcp` the capability is served
+as the MCP tool of its own name (`requiredFeatures: ["tool:<capability>"]`, contract
+`fabric-interop/0.1`); add `--job` when its work may outlive one request, which writes
+`"job": true` in the capability's interop block. The helper creates only the locked
 target paths. It refuses any collision. Do not use `--force` unless the user explicitly
 authorizes replacement after the exact conflicting files and diff are shown.
 
@@ -108,6 +111,11 @@ Preserve the chosen ownership boundary:
 - A2A maps the provider's remote task, progress, artifact, cancellation, and terminal
   states; Fabric does not take over its internal loop.
 - MCP exposes bounded tools/resources/prompts while Fabric owns planning and retries.
+  The served tool's name, input and output schemas equal the manifest's (FAC-SEM-017);
+  long work returns a job handle and serves `fabric.job.get` / `fabric.job.cancel`; a
+  question for a person is a form-mode choice, a secret goes through URL mode; every call
+  runs as a child span of `_meta.traceparent`. The kit for all of it is
+  `building-fabric-services`'s `scripts/fabric_interop.py`.
 - Local runner maps typed input, executable identity, result location, cancellation,
   heartbeat, and partial results without relying on ambient accounts.
 
@@ -115,6 +123,14 @@ Keep model selection and provider-internal reasoning outside the Fabric contract
 typed outcomes, evidence, artifacts, and protocol-visible state—not chain-of-thought.
 Treat all provider output as untrusted until schemas and semantic assertions pass.
 
+### 4b. Announce an agent that is not a service
+
+An agent Fabric reaches as a CLI or a stdio MCP server gets a provider entry, written by
+its installer with [`scripts/fabric_provider.py`](scripts/fabric_provider.py) and removed
+by its uninstaller — argv arrays only, env values as `secret-ref:` references, never the
+id of an existing service, and a `providerId` equal to the manifest's `provider.id`. Load [provider entries](references/provider-entry.md). An
+agent that runs as a service uses a descriptor instead (`building-fabric-services`).
+
 ### 5. Make probes safe and meaningful
 
 For each capability, create at least one bounded fixture that:

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/provider-entry.md

@@ -0,0 +1,57 @@
+# Provider entries: agents that are not services
+
+Normative source: the Fabric Agent Contract's `docs/specification/provider.md`
+(`fabric-provider/0.1`, DEC-0016, rulings DEC-0017) at the commit this plugin pins.
+
+An agent Fabric reaches as a CLI or a stdio MCP server — not a long-running service —
+is announced by one entry, `providers/<id>.json`, in the same root as the services
+directory:
+
+| Platform | Directory |
+|---|---|
+| macOS | `~/Library/Application Support/ai.passioncode.fabric/providers/` |
+| Linux | `${XDG_DATA_HOME:-~/.local/share}/passioncode-fabric/providers/` |
+| any | `FABRIC_PROVIDERS_DIR` when set |
+
+A service uses a descriptor instead (the `building-fabric-services` skill). One id is a
+service or a provider, never both.
+
+## The writer
+
+`scripts/fabric_provider.py` is the installer's tool; it writes atomically, mode 0600,
+and refuses what the contract refuses.
+
+```bash
+python3 scripts/fabric_provider.py write --id example-agent --provider-id https://agents.example/providers/example-agent \
+  --name "Example Agent" \
+  --manifest ~/.local/share/example-agent/fabric-agent.json --installed-by "example-agent 1.0.0" \
+  --env EXAMPLE_API_KEY=secret-ref:example-agent/EXAMPLE_API_KEY \
+  --stdio ~/.local/bin/example-agent mcp
+python3 scripts/fabric_provider.py write ... --url http://127.0.0.1:47201/mcp
+python3 scripts/fabric_provider.py validate ~/Library/Application\ Support/ai.passioncode.fabric/providers/example-agent.json
+python3 scripts/fabric_provider.py remove example-agent      # the uninstaller
+```
+
+`--stdio` takes the rest of the line as the argument array; there is no shell string.
+
+It refuses, with one sentence that never quotes a value:
+
+- a manifest that does not resolve, or whose `provider.id` is not the entry's
+  `providerId` — the two URIs are compared as URIs (FAC-SEM-014);
+- an id that is already a service in `services/` (FAC-SEM-013);
+- an env value that is not `secret-ref:<name>`, or a reference that has the shape of a
+  credential itself — a token prefix, a private key, a JWT (FAC-SEM-015: a value is
+  checked by its form; name patterns apply to names);
+- a URL other than `http://127.0.0.1:<port>/mcp`, a manifest path that is not an
+  absolute or `~/` path to `fabric-agent.json`, a shell-string command, unknown fields.
+
+`validate` also checks that the file is named `<id>.json` (FAC-SEM-014, slug half).
+From Python: `write_provider_entry(entry)`, `remove_provider_entry(id)`,
+`validate_provider_entry(entry)`, `manifest_problems(entry)`, `providers_dir()`.
+
+## What the entry does not do
+
+It grants nothing: Fabric lists the agent, and admission (probes) and a project binding
+still decide what it may do. The manifest it points at is the authority for the
+agent's capabilities. Equality is between like things (DEC-0017): the slug `id` with the
+file name, the URI `providerId` with the manifest's URI `provider.id`.

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/adapt_project.py

@@ -16,7 +16,8 @@ from urllib.parse import urlparse
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
-CONTRACT_COMMIT = "a5a27092ba0dcc5facfbeae8b359146dfb403e9a"
+CONTRACT_COMMIT = "9cd778eb6f14b977f9a5b4930826f62dc95c5619"
+INTEROP_KEY = "https://fabric.passioncode.ai/agent-contract/extensions/interop/0.1"
 MCP_REVISION = "2026-07-28"
 A2A_VERSION = "1.0"
 LOCAL_VERSION = "fabric-local-runner/0.1"
@@ -167,7 +168,8 @@ def _profile(args: argparse.Namespace, schema_base: str) -> Dict[str, Any]:
             "kind": "mcp",
             "protocolRevision": MCP_REVISION,
             "connection": connection,
-            "requiredFeatures": ["tool:replace-me"],
+            # fabric-interop/0.1 C3.1: the capability is served as the MCP tool of its own name.
+            "requiredFeatures": ["tool:%s" % args.capability_name],
             "probes": [probe],
         }
     if profile == "a2a":
@@ -215,6 +217,8 @@ def _generated_files(args: argparse.Namespace) -> Dict[str, str]:
     _require_absolute_uri(args.agent_card_url, "Agent Card URL")
     if urlparse(args.agent_card_url).scheme != "https":
         raise AdaptationError("Agent Card URL must use HTTPS")
+    if getattr(args, "job", False) and args.profile != "mcp":
+        raise AdaptationError("--job marks an MCP capability as a job (fabric-interop/0.1); %s has no job handle" % args.profile)
     for runtime_arg in args.runtime_arg:
         lowered = runtime_arg.lower().replace("_", "").replace("-", "")
         if any(term in lowered for term in ("password", "apikey", "accesstoken", "clientsecret")):
@@ -249,6 +253,8 @@ def _generated_files(args: argparse.Namespace) -> Dict[str, str]:
             }
         ],
     }
+    if getattr(args, "job", False):
+        manifest["capabilities"][0]["extensions"] = {INTEROP_KEY: {"job": True}}
     lock = {
         "contract": "fabric-agent-contract",
         "version": CONTRACT_VERSION,
@@ -431,6 +437,12 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
                     errors.append("capability[%d] must pin %s=%s" % (index, expected[0], expected[1]))
                 if not profile.get("probes"):
                     errors.append("capability[%d] must declare probes" % index)
+                block = (capability.get("extensions") or {}).get(INTEROP_KEY)
+                if block is not None:
+                    if not isinstance(block, dict) or set(block) - {"job"} or not isinstance(block.get("job", False), bool):
+                        errors.append("capability[%d] interop block must be {\"job\": true|false}" % index)
+                    elif kind != "mcp":
+                        errors.append("capability[%d] interop block is for an mcp capability, not %s" % (index, kind))
                 for field in ("inputSchema", "outputSchema"):
                     value = capability.get(field)
                     try:
@@ -503,6 +515,7 @@ def build_parser() -> argparse.ArgumentParser:
     scaffold.add_argument("--runner-kind", default="replace-me")
     scaffold.add_argument("--executable-ref", default="urn:executable:replace-me")
     scaffold.add_argument("--runtime-arg", action="append", default=[])
+    scaffold.add_argument("--job", action="store_true", help="the capability's work may outlive one request (fabric-interop/0.1 job)")
     scaffold.add_argument("--force", action="store_true")
     scaffold.add_argument("--json", action="store_true")
 

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/fabric_provider.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""Write and remove fabric-provider/0.1 entries: agents that are not services.
+
+An agent reached as a CLI or a stdio MCP server announces itself with one entry in
+the providers directory, beside the services directory. Only its installer writes the
+entry and only its uninstaller removes it; the entry grants no Project access.
+Standard library only; it does not import the service kit, so this skill stands alone.
+
+  fabric_provider.py write --id ID --provider-id URI --name NAME --manifest PATH --installed-by TEXT
+                           (--url http://127.0.0.1:PORT/mcp | --stdio EXECUTABLE [ARG ...])
+                           [--env NAME=secret-ref:REF ...] [--summary TEXT] [--repository URL]
+  fabric_provider.py remove ID
+  fabric_provider.py validate PATH
+
+Normative source: fabric-agent-contract docs/specification/provider.md (DEC-0016, rulings DEC-0017).
+"""
+
+# #region provider-writer — docs: plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/provider-entry.md#the-writer
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+from typing import Any, Dict, List, Optional
+
+PROTOCOL = "fabric-provider/0.1"
+_ID = re.compile(r"^[a-z][a-z0-9-]{1,62}$")
+_ENV_NAME = re.compile(r"^[A-Z_][A-Z0-9_]*$")
+_SECRET_REF = re.compile(r"^secret-ref:([A-Za-z0-9][A-Za-z0-9._/:@-]{0,255})$")
+_LOCAL_PATH = re.compile(r"^(~/|/)[^\x00]*$")
+_URL = re.compile(r"^http://127\.0\.0\.1:([0-9]{1,5})/mcp$")
+_URI = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:[^\s]+$")
+FIELDS = {"protocol", "id", "providerId", "name", "summary", "manifest", "run", "source", "installedAt", "installedBy", "extensions"}
+# FAC-SEM-015 reads a credential by its SHAPE: a reference named after a key is fine.
+CREDENTIAL_SHAPES = [re.compile(p) for p in (
+    r"^(sk|pk|rk)[-_](live|test|proj|or|ant)?[-_]?[A-Za-z0-9_-]{16,}",
+    r"^(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}",
+    r"^github_pat_[A-Za-z0-9_]{20,}",
+    r"^xox[abprs]-[A-Za-z0-9-]{10,}",
+    r"^(AKIA|ASIA)[A-Z0-9]{16}$",
+    r"^lin_api_[A-Za-z0-9]{20,}",
+    r"^AIza[0-9A-Za-z_-]{30,}",
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
+    r"^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$",
+    r"^(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])[A-Za-z0-9+=_-]{32,}$",
+)]
+
+
+class ProviderError(Exception):
+    """An entry was refused; the message is one readable sentence and never quotes a value."""
+
+
+def services_dir() -> Path:
+    override = os.environ.get("FABRIC_SERVICES_DIR")
+    if override:
+        return Path(override).expanduser()
+    home = Path.home()
+    if sys.platform == "darwin":
+        return home / "Library/Application Support/ai.passioncode.fabric/services"
+    return Path(os.environ.get("XDG_DATA_HOME") or str(home / ".local/share")) / "passioncode-fabric/services"
+
+
+def providers_dir() -> Path:
+    """FABRIC_PROVIDERS_DIR, else `providers/` in the same root as `services/`."""
+    override = os.environ.get("FABRIC_PROVIDERS_DIR")
+    if override:
+        return Path(override).expanduser()
+    return services_dir().parent / "providers"
+
+
+def looks_like_credential(value: str) -> bool:
+    return any(shape.search(value) for shape in CREDENTIAL_SHAPES)
+
+
+def validate_provider_entry(entry: Any) -> List[str]:
+    """Mirrors provider.schema.json and FAC-SEM-015 (the schema stays normative)."""
+    if not isinstance(entry, dict):
+        return ["an entry is a JSON object"]
+    problems: List[str] = []
+    for key in ("protocol", "id", "providerId", "name", "manifest", "run", "installedAt", "installedBy"):
+        if key not in entry:
+            problems.append("missing %s" % key)
+    for key in sorted(set(entry) - FIELDS):
+        problems.append("unknown field %s" % key)
+    if problems:
+        return problems
+    if entry["protocol"] != PROTOCOL:
+        problems.append("protocol must be %s" % PROTOCOL)
+    if not _ID.match(str(entry["id"])):
+        problems.append("id must match %s" % _ID.pattern)
+    if not _URI.match(str(entry["providerId"])):
+        problems.append("providerId is the absolute URI of the manifest's provider.id")
+    if not isinstance(entry["name"], str) or not 1 <= len(entry["name"]) <= 80:
+        problems.append("name is 1 to 80 characters")
+    if "summary" in entry and (not isinstance(entry["summary"], str) or len(entry["summary"]) > 200):
+        problems.append("summary is at most 200 characters")
+    manifest = str(entry["manifest"])
+    if not _LOCAL_PATH.match(manifest) or not re.search(r"(^|/)fabric-agent\.json$", manifest):
+        problems.append("manifest is an absolute or ~/ path to fabric-agent.json")
+    problems.extend(_run_problems(entry["run"]))
+    return problems
+
+
+def _run_problems(run: Any) -> List[str]:
+    mcp = run.get("mcp") if isinstance(run, dict) and set(run) == {"mcp"} else None
+    if not isinstance(mcp, dict) or len(mcp) != 1 or not set(mcp) <= {"stdio", "url"}:
+        return ["run is {mcp: {stdio: ...}} or {mcp: {url: ...}}, exactly one"]
+    if "url" in mcp:
+        match = _URL.match(str(mcp["url"]))
+        return [] if match and 1 <= int(match.group(1)) <= 65535 else ["run.mcp.url is http://127.0.0.1:<port>/mcp"]
+    stdio = mcp["stdio"]
+    problems: List[str] = []
+    if not isinstance(stdio, dict) or not set(stdio) <= {"command", "env"} or "command" not in stdio:
+        return ["run.mcp.stdio is {command, env?}"]
+    command = stdio["command"]
+    if not isinstance(command, list) or not 1 <= len(command) <= 32 or not all(isinstance(a, str) and a for a in command):
+        problems.append("run.mcp.stdio.command is an argument array, never a shell string")
+    env = stdio.get("env", {})
+    if not isinstance(env, dict):
+        return problems + ["run.mcp.stdio.env is an object"]
+    for name, value in env.items():
+        if not _ENV_NAME.match(name):
+            problems.append("env name %s is not an environment variable name" % name)
+        reference = _SECRET_REF.match(value) if isinstance(value, str) else None
+        if not reference or looks_like_credential(reference.group(1)):
+            problems.append("env %s must be a secret reference (secret-ref:<name>), never a secret value (FAC-SEM-015)" % name)
+    return problems
+
+
+def manifest_problems(entry: Dict[str, Any]) -> List[str]:
+    """FAC-SEM-014 (DEC-0017), URI half: the manifest resolves and its provider.id equals providerId."""
+    try:
+        manifest = json.loads(Path(os.path.expanduser(str(entry["manifest"]))).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return ["the manifest %s does not resolve (FAC-SEM-014)" % entry["manifest"]]
+    provider = manifest.get("provider") if isinstance(manifest, dict) else None
+    if not isinstance(provider, dict) or not isinstance(manifest.get("capabilities"), list):
+        return ["%s is not a provider manifest (FAC-SEM-014)" % entry["manifest"]]
+    if provider.get("id") != entry["providerId"]:
+        return ["providerId %s is not the manifest's provider.id %s (FAC-SEM-014)" % (entry["providerId"], provider.get("id"))]
+    return []
+
+
+def _atomic_write(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    os.chmod(path.parent, 0o700)
+    fd, tmp = tempfile.mkstemp(prefix="." + path.name + ".", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        try:
+            os.unlink(tmp)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _service_ids(directory: Path) -> Dict[str, str]:
+    ids: Dict[str, str] = {}
+    if directory.is_dir():
+        for path in sorted(directory.glob("*.json")):
+            try:
+                ids.setdefault(str(json.loads(path.read_text(encoding="utf-8")).get("id")), path.name)
+            except (OSError, ValueError, AttributeError):
+                continue
+    return ids
+
+
+def write_provider_entry(entry: Dict[str, Any], directory: Optional[Path] = None, services: Optional[Path] = None) -> Path:
+    """Installer-only. Refuses an invalid entry and an id that is already a service (FAC-SEM-013)."""
+    problems = validate_provider_entry(entry)
+    if not problems:
+        problems = manifest_problems(entry)
+    if problems:
+        raise ProviderError("Provider entry is invalid: %s." % "; ".join(problems))
+    clash = _service_ids(services or services_dir()).get(entry["id"])
+    if clash:
+        raise ProviderError("%s is already a service (%s); an id is a service or a provider, never both (FAC-SEM-013)." % (entry["id"], clash))
+    target = (directory or providers_dir()) / ("%s.json" % entry["id"])
+    _atomic_write(target, (json.dumps(entry, indent=2, ensure_ascii=False) + "\n").encode())
+    return target
+
+
+def remove_provider_entry(provider_id: str, directory: Optional[Path] = None) -> bool:
+    """Uninstaller-only. Returns whether there was an entry to remove."""
+    if not _ID.match(provider_id):
+        raise ProviderError("Provider id %s does not match %s." % (provider_id, _ID.pattern))
+    try:
+        ((directory or providers_dir()) / ("%s.json" % provider_id)).unlink()
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def _now() -> str:
+    return dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    write = sub.add_parser("write")
+    write.add_argument("--id", required=True)
+    write.add_argument("--provider-id", required=True, help="the manifest's provider.id (a URI)")
+    write.add_argument("--name", required=True)
+    write.add_argument("--summary")
+    write.add_argument("--manifest", required=True)
+    write.add_argument("--installed-by", required=True)
+    write.add_argument("--repository")
+    write.add_argument("--env", action="append", default=[], help="NAME=secret-ref:REF (a reference, never a value)")
+    transport = write.add_mutually_exclusive_group(required=True)
+    transport.add_argument("--url")
+    transport.add_argument("--stdio", nargs=argparse.REMAINDER, help="the executable and its arguments, last on the line")
+    remove = sub.add_parser("remove")
+    remove.add_argument("id")
+    check = sub.add_parser("validate")
+    check.add_argument("path", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "remove":
+            print("removed" if remove_provider_entry(args.id) else "no entry for %s" % args.id)
+            return 0
+        if args.command == "validate":
+            entry = json.loads(args.path.read_text(encoding="utf-8"))
+            problems = validate_provider_entry(entry)
+            if isinstance(entry, dict) and entry.get("id") != args.path.stem:
+                problems.append("the file name %s is not <id>.json for %s (FAC-SEM-014)" % (args.path.name, entry.get("id")))
+            if not problems:
+                problems = manifest_problems(entry)
+            print("; ".join(problems) if problems else "valid")
+            return 1 if problems else 0
+        env: Dict[str, str] = {}
+        for pair in args.env:
+            name, sep, value = pair.partition("=")
+            if not sep:
+                raise ProviderError("--env takes NAME=secret-ref:REF.")
+            env[name] = value
+        run: Dict[str, Any] = {"mcp": {"url": args.url}} if args.url else {"mcp": {"stdio": {"command": args.stdio}}}
+        if env and args.stdio:
+            run["mcp"]["stdio"]["env"] = env
+        entry: Dict[str, Any] = {"protocol": PROTOCOL, "id": args.id, "providerId": args.provider_id, "name": args.name, "manifest": args.manifest,
+                                 "run": run, "installedAt": _now(), "installedBy": args.installed_by}
+        if args.summary:
+            entry["summary"] = args.summary
+        if args.repository:
+            entry["source"] = {"repository": args.repository}
+        print(write_provider_entry(entry))
+        return 0
+    except (ProviderError, OSError, ValueError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+# #endregion provider-writer