@passioncode-ai/fabric-agent-adapter 0.4.3 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.5.1 - 2026-09-30
+
+Aligns the kits, the probe and the provider writer with the contract owner's rulings,
+Fabric Agent Contract DEC-0017. **Contract pin** moves from `a22dea3` to `9cd778e`.
+
+### Changed
+
+- **A job's result is the full result envelope** (OQ-0002): `result_envelope` /
+  `resultEnvelope` now build the contract's `result.schema.json` shape — `id`,
+  `contractVersion`, `outcome`, `artifacts`, `createdAt`, `producer` beside the four
+  collections, `output` and `usage` — and refuse `succeeded` with unverified claims
+  (FAC-SEM-001). `outcome` and `producer` are new required arguments.
+- **The envelope carries its trace** (OQ-0003): `trace: {traceparent}`, authoritative for
+  a stored result. `JobStore.complete` fills it from the job's span and refuses an envelope
+  that names another span; `fabric.job.get` answers with the envelope's traceparent in
+  `_meta`, so the two always agree (FAC-SEM-022).
+- **A job-backed tool serves `oneOf[result envelope, job handle]`** (OQ-0006):
+  `tool_for_capability` / `toolForCapability` wrap the output schema with
+  `job_tool_output_schema` / `jobToolOutputSchema` for a job capability, so
+  `structuredContent` always conforms; the manifest keeps the pure schema. The probe's
+  `interop.tools-match` expects the union for a job capability.
+- **Provider entries name their provider by URI** (OQ-0001): `fabric_provider.py` requires
+  `providerId` (`--provider-id`), refuses an entry whose manifest does not resolve or whose
+  `provider.id` differs, and `validate` checks that the file is named `<id>.json`.
+
+## 0.5.0 - 2026-09-30
+
+### Added
+
+- **`fabric-interop/0.1` in the kits** (Fabric Agent Contract DEC-0016).
+  `building-fabric-services/scripts/fabric_interop.py` and its Node twin
+  `fabric-interop.mjs`: W3C trace context (`child_traceparent`, `trace_ids`), a
+  capability served as the MCP tool of its name with annotations from its effect,
+  durable jobs (`JobStore`: ids survive a restart, terminal states never change,
+  `unknown-job` for an unknown id), the result envelope with `usage`, and elicitations
+  (a titled single-select in form mode, URL mode for secrets; form mode refuses a
+  secret field). Python also ships `McpToolServer`, a minimal `tools/list` /
+  `tools/call` dispatcher with `fabric.job.get` and `fabric.job.cancel` built in.
+- Events carry `traceId` and `spanId` as a pair (`make_event`, `makeEvent`).
+- The sample service serves MCP at `/mcp`: `sample.echo`, and `sample.draft`, a job
+  that stops for a title choice and completes with a traced result. `register` writes
+  its manifest and schemas and points the descriptor's `fabricManifest` at it.
+- The probe `check_service.py` gains seven `interop.*` rules: manifest link (G-07),
+  capability list, tools equal to the manifest (FAC-SEM-017), job tools, unknown job,
+  trace propagation and event trace pairs. It calls only `tools/list` and
+  `fabric.job.get` for a made-up id.
+- `adapting-projects-to-fabric/scripts/fabric_provider.py`: writes, validates and
+  removes `fabric-provider/0.1` entries for agents that are not services — argv only,
+  env values as `secret-ref:` references, never the id of an existing service.
+- `adapt_project.py scaffold --job` writes the capability's interop block; an `mcp`
+  capability now requires the tool of its own name instead of `tool:replace-me`, and
+  `check` refuses a malformed interop block.
+- Skills teach it: `building-fabric-services` gains `references/interop.md`,
+  `adapting-projects-to-fabric` gains `references/provider-entry.md` and step 4b, and
+  `creating-fabric-agents` starts new agents on it. Trigger and scenario evals added
+  first.
+
+### Changed
+
+- **Contract pin** moves from `a5a2709` to `a22dea3` (fabric-agent-contract `main`,
+  AR-1: interop, provider entries, runner catalogue, pipelines). The provider profiles
+  and every existing schema field are unchanged; the contract added schemas and
+  optional fields only (DEC-0016). **One pin**: `fabric-contract.lock.json`, and
+  `test/validate.py` fails any live file that names another contract revision (G-11).
+- The README has a newcomer path that starts the sample service and probes it.
+
 ## 0.4.3 - 2026-09-29
 
 ### Changed
@@ -7,8 +73,7 @@
 - **License.** The adapter is now source-available under
   `PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0`, with a
   commercial license on request (contact@passioncode.ai). Versions up to and including
-  v0.4.2, and npm releases up to and including 0.3.1, were released under MIT and remain
-  available under it. The manifests, the three skills' `license:` and the README say the
+  v0.4.2, on GitHub and on npm, were released under MIT and remain available under it. The manifests, the three skills' `license:` and the README say the
   same; contributions come in under `CLA.md`, which the new PR template asks for.
   `test/validate.py` fails a tree that slips back to MIT.
 - Author and marketplace owner are PassionCode.ai (`https://passioncode.ai/`).

package/LICENSE

@@ -15,9 +15,8 @@ this software or its code into a product or service you provide to others,
 needs a separate commercial license: contact@passioncode.ai.
 This summary is not part of either license; the texts below govern.
 
-Versions up to and including v0.4.2 of this repository (and npm releases up to and
-including 0.3.1) were released under the MIT License; those releases remain available
-under MIT.
+Versions up to and including v0.4.2 of this repository, and of its npm package, were
+released under the MIT License; those releases remain available under MIT.
 
 Required Notice: Copyright (c) 2026 Siarhei Sheleh (https://passioncode.ai)
 

package/README.md

@@ -17,7 +17,7 @@ without moving the Project onto one proprietary agent runtime.
 [![validate](https://github.com/passioncode-ai/fabric-agent-adapter/actions/workflows/validate.yml/badge.svg)](https://github.com/passioncode-ai/fabric-agent-adapter/actions/workflows/validate.yml)
 [![license](https://img.shields.io/badge/license-source--available-blue.svg)](LICENSE)
 
-Private, portable Agent Skills for the
+Portable Agent Skills that make any agent Fabric-compatible, for the
 [Fabric Agent Contract](https://github.com/passioncode-ai/fabric-agent-contract):
 `adapting-projects-to-fabric`, `creating-fabric-agents` and
 `building-fabric-services`.
@@ -32,6 +32,14 @@ complete `scripts/sample_service.py`, and `scripts/check_service.py`, a live pro
 python3 plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py example-agent
 ```
 
+Services and agents that other agents call follow `fabric-interop/0.1`: each capability
+is the MCP tool of its name, long work is a job with a stable id (`fabric.job.get`,
+`fabric.job.cancel`), a question for a person is an elicitation, and every call carries
+one W3C trace. The kits ship the helpers (`scripts/fabric_interop.py`,
+`scripts/fabric-interop.mjs`), the sample service serves a job end to end, and the probe
+checks the interop rules. An agent that is not a service is announced with a provider
+entry: `adapting-projects-to-fabric/scripts/fabric_provider.py`.
+
 For provider bundles the adapting skill helps an agent author:
 
 - inspect the project's stable integration surfaces without executing it;
@@ -46,7 +54,7 @@ yet ship the host registry/runtime needed to connect and authorize a live provid
 
 ## Install
 
-The repository is private; the npm package is public. The npm path needs no GitHub access — the GitHub paths do.
+The repository and the npm package are public; neither path needs an account.
 
 npm — no GitHub access required:
 
@@ -110,6 +118,23 @@ python3 "$SKILL_DIR/scripts/adapt_project.py" check /path/to/project \
 Scaffolding is non-destructive by default. It writes only the paths declared in the
 [delivery brief](docs/evidence/specs/2026-08-27-brief.md) and refuses collisions.
 
+## Verify one service (newcomer path)
+
+After installing (above), with Python 3.9+ and no other dependency:
+
+```bash
+KIT=plugins/fabric-agent-adapter/skills/building-fabric-services/scripts   # or ~/.agents/skills/building-fabric-services/scripts
+DATA=$(mktemp -d); SERVICES=$(mktemp -d)
+python3 "$KIT/sample_service.py" serve --port 47190 --data-dir "$DATA" &
+python3 "$KIT/sample_service.py" register --port 47190 --data-dir "$DATA" --services-dir "$SERVICES"
+python3 "$KIT/check_service.py" sample --services-dir "$SERVICES"   # exit 0: no FAIL
+kill %1
+```
+
+The probe prints one line per rule — `PASS`, `FAIL` or `NOT_RUN` with its evidence — and
+exits 1 on any `FAIL`. Run it against your own service by its id once its installer has
+written the descriptor.
+
 ## Validate this repository
 
 ```bash
@@ -125,17 +150,21 @@ checks copies installed elsewhere, such as `~/.agents/skills/*/SKILL.md`.
 
 ## Contract pin
 
+The one pin is [`fabric-contract.lock.json`](fabric-contract.lock.json):
+
 - version: `0.1.0`
-- commit: `a5a27092ba0dcc5facfbeae8b359146dfb403e9a`
+- commit: `9cd778eb6f14b977f9a5b4930826f62dc95c5619`
 
-The contract repository is normative. Updating the pin requires a new adapter release,
-fixture review, and a complete validation run.
+Every other mention of the contract revision — this section, the skills' metadata, the
+skill card, `adapt_project.py` — must equal it; `python3 test/validate.py` fails a tree
+where one does not. The contract repository is normative. Updating the pin requires a
+new adapter release, fixture review, and a complete validation run.
 
 ## License
 
 Source-available under PolyForm Noncommercial or Internal Use; commercial license on
 request (contact@passioncode.ai). SPDX:
 `PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0` — see
-[LICENSE](LICENSE). Versions up to and including v0.4.2 (npm up to 0.3.1) were released
-under the MIT License and remain available under it. Contributions are accepted under
+[LICENSE](LICENSE). Versions up to and including v0.4.2 (on GitHub and on npm) were
+released under the MIT License and remain available under it. Contributions are accepted under
 [CLA.md](CLA.md) ([CONTRIBUTING.md](CONTRIBUTING.md)).

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
-    "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test test/"
+    "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"
   },
   "bin": {
     "fabric-agent-adapter": "bin/fabric-agent-adapter.js"

package/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/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/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/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/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