@passioncode-ai/fabric-agent-adapter 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.17.0 - 2026-10-12
+
+The organisation's lifecycle rules LC-19 and LC-21 apply to what the adapter ships and checks (FAA-22, FAA-23):
+no plugin starts a stdio MCP server in every session, and no credential travels in argv or a URL query.
+
+### Added
+
+- **`adapt_project.py check`** refuses:
+  - **LC-19:** a Claude Code plugin in the project that declares a stdio MCP server, whether in its `.mcp.json` or in
+    `plugin.json` `mcpServers`, because it starts in every session that enables the plugin. An HTTP entry to a
+    resident service passes.
+  - **LC-21:** a launch argument or a URL that carries a credential, in the manifest's connections and in the plugin
+    servers' argv, URL and env.
+
+  `scaffold` refuses a runtime argument that carries a credential.
+- **`fabric_provider.py`** refuses a credential in `run.mcp.stdio.command` (LC-21, FAC-SEM-057). The key goes in
+  `env` as a secret reference.
+- **`test/validate.py` gate:** the adapter's own plugin declares no MCP server and no hook command carries a
+  credential.
+- The detector is the contract's (`fabric_secrets`, 0.16.0). The adapting skill carries an identical copy, so it
+  works installed alone, and a test keeps the two copies byte-identical.
+- Docs: the adapting skill's check step, `provider-entry.md`, and `surfaces-and-auth.md` (an HTTP registration
+  starts nothing per session). The scenario eval `plugin-and-argv-hygiene` came first. Five planted defects were
+  each caught.
+
+## 0.16.0 - 2026-10-12
+
+Runner and model profiles in both kits (contract DEC-0046, Fabric ADR-0147; FAA-19). The contract's credential
+detector (DEC-0044) is ported too. The contract pin is unchanged (`0cacd08`).
+
+### Added
+
+- **`scripts/fabric_profiles.py` and `scripts/fabric-profiles.mjs`**:
+  - `resolve_model_profile` / `resolveModelProfile` (FAC-SEM-060). The order is request, agent, binding or project,
+    then estate default. The project's `modelClasses` narrow the result, and when nothing is left the launch is
+    refused as `model-classes-empty`, with the policy named.
+  - `profile_problems` / `profileProblems`, the FAC-SEM-058…060 checks of catalogues, profile sets, runner profiles
+    and recorded resolutions.
+  - `runner_check` / `runnerCheck`, for the doctor (runners.md C2). It runs only the catalogued bare binary on `PATH`
+    with its catalogued version and `auth` argv, never through a shell, for at most 5 s.
+  - `model_usable`.
+  - `configuration`, the well-known `configuration`, and `configuration_summary`, which gives the Runner and Model
+    tiles for the dashboard.
+- **`scripts/fabric_secrets.py` and `scripts/fabric-secrets.mjs`**: the contract's one credential detector
+  (`secret-shape.ts`), with `credential_name`, `secret_value`, `secret_argument` and `secret_url`. It is the base for
+  FAA-23 (LC-21).
+- **`build_well_known(configuration=)` / `buildWellKnown({ configuration })`** validates the configuration and carries
+  it. `configuration_problems` / `configurationProblems` are added.
+- **`make_usage_receipt(route=)` / `makeUsageReceipt({ route })`**: a receipt records `subscription` or `key`, and
+  the report keeps the rows of one model on two routes apart.
+- **Probe rule `configuration.declared`.**
+- **Vectors**: `test/fixtures/contract/profile-vectors.json` holds 17 rule cases, 35 resolutions and 128
+  credential-detector cases. Every expected answer comes from the contract's own `profile-rules.ts` and
+  `secret-shape.ts` (`make_profile_vectors.mjs`). Credential-shaped samples are made up and stored hex-encoded.
+- Tests: 11 planted defects across both kits were each caught.
+- **Docs**: `references/profiles.md`, a pointer in SKILL.md, and an updated `protocol.md`. The scenario eval
+  `runner-and-model-profiles` came first.
+
 ## 0.15.0 - 2026-10-12
 
 Fabric's button in the dashboard kit (contract DEC-0040, FB-7). With it, FAA-20 is complete. The contract pin is

package/README.md

@@ -230,8 +230,8 @@ FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/curren
 ```
 
 Without both environment variables, those tests explicitly skip as `NOT_RUN`.
-This source checkout is 0.15.0. 0.14.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
-were never released); 0.15.0 is published by its `v0.15.0` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.17.0. 0.16.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
+were never released); 0.17.0 is published by its `v0.17.0` tag. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "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.mjs'"

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.15.0",
+  "version": "0.17.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.15.0"
+  version: "0.17.0"
   contract-version: "0.1.0"
   contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
 ---
@@ -173,6 +173,12 @@ python3 <skill-dir>/scripts/adapt_project.py check <project-root> \
   --contract /path/to/fabric-agent-contract --json
 ```
 
+The local check also refuses two lifecycle faults (LC-19, LC-21): a Claude Code plugin in
+the project that declares a stdio MCP server — it starts in every session that enables the
+plugin; serve it over HTTP from one resident process or register it at project scope — and a
+credential in a launch argument or a URL query, where every process and every log can read it.
+Fix both at their cause; never weaken the check.
+
 Load [verification](references/verification.md) before interpreting or publishing the
 result. Fix every local error. Fix every placeholder warning or record why the bundle is
 still a draft. Do not convert `NOT_RUN` or `NOT_VERIFIED` to `PASS` without the named

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

@@ -35,7 +35,8 @@ 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. An entry may carry
 `run.mcp.stdio.scope` (DEC-0044): `project` (started for the sessions of a project that binds it) or `on-demand`;
 `session` — a server in every coding session — is refused (FAC-SEM-056, LC-19). The validator accepts the field; the
-writer does not set it until Fabric reads it.
+writer does not set it until Fabric reads it. An argument that carries a credential is refused
+(LC-21, FAC-SEM-057): a key goes in `env` as a `secret-ref:<name>`, never in argv.
 
 It refuses, with one sentence that never quotes a value:
 

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

@@ -15,6 +15,9 @@ import sys
 from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
 from urllib.parse import urlparse
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_secrets as _secrets  # noqa: E402 - the contract's credential detector (DEC-0044, LC-21), beside this file
+
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
@@ -230,6 +233,8 @@ def _generated_files(args: argparse.Namespace) -> Dict[str, str]:
         lowered = runtime_arg.lower().replace("_", "").replace("-", "")
         if any(term in lowered for term in ("password", "apikey", "accesstoken", "clientsecret")):
             raise AdaptationError("runtime arguments must not contain secret-like values or names")
+        if _secrets.secret_argument(runtime_arg):
+            raise AdaptationError("a runtime argument carries a credential; argv is visible to every process (LC-21): read it from a secret reference instead")
 
     created_at = dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
     manifest = {
@@ -465,6 +470,58 @@ import {SCHEMA_PREFIX} from './src/contract.ts';
     return "PASS", ["manifest validated by selected contract schema at %s" % selected_commit]
 
 
+def _credential_problems(manifest: Dict[str, Any]) -> List[str]:
+    """LC-21 (FAA-23): no credential in a launch argument or in a URL the manifest names."""
+    problems: List[str] = []
+    for index, capability in enumerate(manifest.get("capabilities") or []):
+        connection = ((capability or {}).get("profile") or {}).get("connection") if isinstance(capability, dict) else None
+        if not isinstance(connection, dict):
+            continue
+        for arg in connection.get("args") or []:
+            if isinstance(arg, str) and _secrets.secret_argument(arg):
+                problems.append("LC-21: capability[%d] passes a credential in a launch argument; argv is visible to every process" % index)
+        for field in ("url", "agentCardUrl"):
+            if isinstance(connection.get(field), str) and _secrets.secret_url(connection[field]):
+                problems.append("LC-21: capability[%d].%s carries a credential in the URL; a query lands in every log" % (index, field))
+    return problems
+
+
+_PLUGIN_SKIP = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", ".worktrees"}
+
+
+def _plugin_problems(root: Path) -> List[str]:
+    """LC-19 (FAA-22) and LC-21 for the Claude Code plugins in the project: a plugin's stdio MCP server starts in
+    every session that enables the plugin; serve it over HTTP from one resident process, or register it at project
+    scope instead. No server entry carries a credential in its argv, URL or env."""
+    problems: List[str] = []
+    for top, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in _PLUGIN_SKIP]
+        here = Path(top)
+        if here.name != ".claude-plugin" or "plugin.json" not in files:
+            continue
+        plugin = here.parent
+        name = plugin.relative_to(root).as_posix() or "."
+        servers: Dict[str, Any] = {}
+        for source in (here / "plugin.json", plugin / ".mcp.json"):
+            try:
+                doc = json.loads(source.read_text(encoding="utf-8")) if source.is_file() else {}
+            except (OSError, ValueError):
+                continue
+            block = doc.get("mcpServers") if isinstance(doc, dict) else None
+            if isinstance(block, dict):
+                servers.update({k: v for k, v in block.items() if isinstance(v, dict)})
+        for server, entry in sorted(servers.items()):
+            if "command" in entry:
+                problems.append("LC-19: plugin %s declares the stdio MCP server %s, which starts in every session that enables the plugin; serve it over HTTP from one resident process or register it at project scope" % (name, server))
+            argv = [entry.get("command")] + list(entry.get("args") or [])
+            if any(isinstance(a, str) and _secrets.secret_argument(a) for a in argv) or (isinstance(entry.get("url"), str) and _secrets.secret_url(entry["url"])):
+                problems.append("LC-21: plugin %s's MCP server %s carries a credential in its argv or URL" % (name, server))
+            env = entry.get("env") if isinstance(entry.get("env"), dict) else {}
+            if any(isinstance(v, str) and _secrets.secret_value(v) for v in env.values()):
+                problems.append("LC-21: plugin %s's MCP server %s writes a credential value in env; reference it instead" % (name, server))
+    return problems
+
+
 def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
     errors: List[str] = []
     warnings: List[str] = []
@@ -534,6 +591,7 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
                 errors.append("secret-like field is forbidden in manifest: %s" % key)
             if isinstance(value, str) and ("replace-me" in value or ".invalid" in value):
                 warnings.append("placeholder:%s" % key)
+        errors.extend(_credential_problems(manifest))
         provider = manifest.get("provider")
         if isinstance(provider, dict) and provider.get("contentHash") == "sha256:" + ("0" * 64):
             warnings.append("placeholder:provider.contentHash")
@@ -545,6 +603,7 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
     elif contract is not None and manifest_path.is_file():
         shape_status, shape_receipts = _contract_shape(manifest_path, contract, lock["commit"])
 
+    errors.extend(_plugin_problems(root))
     local_status = "PASS" if not errors else "FAIL"
     ready = local_status == "PASS" and shape_status == "PASS" and not warnings
     return {

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

@@ -29,6 +29,9 @@ import sys
 import tempfile
 from typing import Any, Dict, List, Optional
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_secrets as _secrets  # noqa: E402 - the contract's credential detector (DEC-0044, LC-21), beside this file
+
 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_]*$")
@@ -124,6 +127,8 @@ def _run_problems(run: Any) -> List[str]:
     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")
+    elif any(_secrets.secret_argument(a) for a in command):
+        problems.append("run.mcp.stdio.command carries a credential in an argument; argv is visible to every process (LC-21, FAC-SEM-057): pass it as a secret reference in env")
     env = stdio.get("env", {})
     if not isinstance(env, dict):
         return problems + ["run.mcp.stdio.env is an object"]

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

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""The contract's one credential detector (Fabric Agent Contract DEC-0044, `src/secret-shape.ts` at the pin): a name
+that can only carry a credential, a value shaped like one, a launch argument that carries one, and a URL that does
+(LC-21). A port held to the contract's own answers by test/fixtures/contract/profile-vectors.json. Standard library
+only. The dashboard kit's fabric-button.js carries its own copy of the name and value checks (FL-4)."""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List
+import urllib.parse
+
+CREDENTIAL_WORDS = (
+    "token", "secret", "password", "passwd", "pass", "passphrase", "credential", "credentials", "cookie", "authorization",
+    "bearer", "jwt", "otp", "apikey", "signature", "sig",
+    "accesstoken", "idtoken", "authtoken", "refreshtoken", "sessionid", "sessiontoken", "logincode", "authcode", "privatekey",
+    "clientsecret", "secretkey", "accesskey",
+)
+CREDENTIAL_PAIRS: Dict[str, tuple] = {
+    "key": ("private", "api", "access", "secret", "session", "auth", "signing", "encryption", "master", "client", "login", "refresh"),
+    "auth": ("token", "code", "header"),
+    "session": ("token", "id"),
+    "code": ("login", "auth", "access", "session"),
+}
+JWT_SHAPE = re.compile(r"eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*")
+SECRET_VALUE = re.compile(r"(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})",
+                          re.IGNORECASE | re.DOTALL)
+_LONG_RUN = re.compile(r"[A-Za-z0-9+/=_-]{40,}")
+_BEARER_INSIDE = re.compile(r"\bbearer\s+(?=[A-Za-z0-9._~+/-]*\d)[A-Za-z0-9._~+/-]{12,}=*", re.IGNORECASE)
+_PATH_LIKE = re.compile(r"^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*://)", re.IGNORECASE)
+_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
+
+def name_words(name: str) -> List[str]:
+    """A name's words: split at `.`, `_`, `-` and camelCase humps, lowercased (`APIKey` is `api key`)."""
+    spaced = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", name)
+    spaced = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1 \2", spaced)
+    return [w.lower() for w in re.split(r"[\s._-]+", spaced) if w]
+
+
+def _with_singulars(words: List[str]) -> List[str]:
+    return words + [w[:-1] for w in words if len(w) > 2 and w.endswith("s")]
+
+
+def credential_name(name: str) -> bool:
+    """Whether a name — a parameter, a header, an environment variable, a config key — can only carry a credential."""
+    split = name_words(name)
+    words = _with_singulars(split)
+    if any(w in CREDENTIAL_WORDS for w in words):
+        return True
+    if len(split) == 1 and any(w in CREDENTIAL_PAIRS for w in words):
+        return True
+    return any(word in words and any(p in words for p in partners) for word, partners in CREDENTIAL_PAIRS.items())
+
+
+def _long_secret(value: str) -> bool:
+    return any(re.search(r"[a-z]", run) and re.search(r"[A-Z]", run) and re.search(r"[0-9]", run) for run in _LONG_RUN.findall(value))
+
+
+def secret_value(value: str) -> bool:
+    """A JWT anywhere, a provider key or `Bearer …`, or a long base64 run mixing upper case, lower case and digits."""
+    return bool(JWT_SHAPE.search(value) or SECRET_VALUE.search(value) or _long_secret(value))
+
+
+def _path_like(piece: str) -> bool:
+    return bool(_PATH_LIKE.match(piece)) or (
+        bool(re.search(r"[\\/]", piece))
+        and (bool(re.search(r"\.[A-Za-z0-9]{1,8}$", piece)) or any(re.fullmatch(r"[a-z][a-z0-9_-]{2,}", s) for s in re.split(r"[\\/]", piece))))
+
+
+def secret_argument(value: str) -> bool:
+    """The same for a launch argument or a server's command and URL: a long run is looked for between path separators,
+    so a folder path holding a session id is not taken for a key."""
+    if JWT_SHAPE.search(value) or SECRET_VALUE.search(value) or _BEARER_INSIDE.search(value):
+        return True
+    for piece in re.split(r"[\s=]", value):
+        if _path_like(piece):
+            if any(_long_secret(part) for part in re.split(r"[\\/]", piece)):
+                return True
+        elif _long_secret(piece):
+            return True
+    return False
+
+
+def _decode_keeping_plus(raw: str) -> str:
+    """decodeURIComponent: a malformed escape or bytes that are not UTF-8 leave the raw text."""
+    if re.search(r"%(?![0-9A-Fa-f]{2})", raw):
+        return raw
+    try:
+        return urllib.parse.unquote_to_bytes(raw).decode("utf-8")
+    except UnicodeDecodeError:
+        return raw
+
+
+def _form_name(text: str) -> str:
+    pairs = urllib.parse.parse_qsl(text, keep_blank_values=True)
+    return pairs[0][0] if pairs else ""
+
+
+def raw_values(query: str) -> Dict[str, List[str]]:
+    """Each query or fragment piece's raw value by its decoded name, with `+` kept."""
+    values: Dict[str, List[str]] = {}
+    for piece in query.split("&"):
+        if piece == "":
+            continue
+        at = piece.find("=")
+        name = _form_name(piece if at < 0 else piece[:at])
+        values.setdefault(name, []).append("" if at < 0 else _decode_keeping_plus(piece[at + 1:]))
+    return values
+
+
+def secret_url(value: str) -> bool:
+    """Whether a URL an MCP entry or a launch names carries a credential (LC-21): anything secret_argument finds, a
+    password in its user information, or a query or fragment parameter whose name can only carry a credential and has
+    a value, or whose value is shaped like one. A string that is not an absolute URL is checked as an argument only."""
+    if secret_argument(value):
+        return True
+    if not _SCHEME.match(value.strip()):
+        return False  # not an absolute URL (WHATWG URL parsing refuses it)
+    try:
+        parts = urllib.parse.urlsplit(value.strip())
+    except ValueError:
+        return False
+    if not parts.scheme:
+        return False
+    if parts.password:
+        return True
+    for part in (parts.query, parts.fragment):
+        for name, raws in raw_values(part).items():
+            if any((raw != "" and credential_name(name)) or secret_value(raw) for raw in raws):
+                return True
+    return False

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -16,7 +16,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only (Linux services use lifecycle manager none until a systemd adapter exists). Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.15.0"
+  version: "0.17.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
@@ -83,7 +83,8 @@ are in [`scripts/fabric_interop.py`](scripts/fabric_interop.py) and
 [`scripts/fabric-interop.mjs`](scripts/fabric-interop.mjs). When the callers are agents of the estate, the
 service checks each call's delegation token (DEC-0039): read [the delegation reference](references/delegation.md);
 the verifier is [`scripts/fabric_delegation.py`](scripts/fabric_delegation.py) /
-[`scripts/fabric-delegation.mjs`](scripts/fabric-delegation.mjs).
+[`scripts/fabric-delegation.mjs`](scripts/fabric-delegation.mjs). When Fabric chooses the service's runner and models
+(DEC-0046), read [the profiles reference](references/profiles.md).
 
 ## Step 2 — the non-negotiables
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/profiles.md

@@ -0,0 +1,64 @@
+# Runner and model profiles (DEC-0046)
+
+Which coding agent runs a job (the **runner**) and which models it may use (the **model profile**) are chosen in
+Fabric, not in the service. The service resolves them in the contract's order, keeps to the project's model classes,
+says what applies in its well-known document, and checks in its doctor that the runner and the model are usable.
+Contract: `docs/specification/runners.md` §"Runner and model profiles" and `src/profile-rules.ts` at the pin.
+Python: [`scripts/fabric_profiles.py`](../scripts/fabric_profiles.py); Node:
+[`scripts/fabric-profiles.mjs`](../scripts/fabric-profiles.mjs). Both answer the contract's own vectors.
+
+## Contents
+
+- Resolving the model profile
+- Checking the documents
+- Declaring and showing what applies
+- The doctor
+- Usage by route
+
+## Resolving the model profile
+
+```python
+import fabric_profiles as fp
+resolution = fp.resolve_model_profile(catalogue=catalogue, profiles=estate_and_agent_profiles,
+                                      choices={"request": asked, "agent": own_default, "binding": bound, "estate": estate_default},
+                                      policy=project_spend_policy)
+```
+
+The first level that names a profile wins: **request, agent, binding or project, estate default**. The project's
+`modelClasses` narrow the profile's models — a model stays only if every class the catalogue gives it is allowed — and
+never choose one. An empty result is `{"refused": "model-classes-empty", "policy": {id, revision}}`: refuse the launch
+and name the policy; never fall back to a model outside it. No level at all is `no-profile`; an id nobody offers is
+`unknown-profile`.
+
+## Checking the documents
+
+`profile_problems(kind, doc)` / `profileProblems(kind, doc)` returns the contract's findings for a `model-catalogue`
+(a model catalogued once; a provider never both ordered and ignored, a base slug covering its variants), a
+`model-profiles` set (an id once), a `runner-profile` (a subscription only in its vendor's runner — Claude in Claude
+Code, Kimi in Kimi Code, ChatGPT in Codex; a key route's allow-list is its own model profile; a key named by reference,
+never by value) and a recorded `profile-resolution` (it equals the order's answer).
+
+## Declaring and showing what applies
+
+```python
+conf = fp.configuration(["runner", "model"], resolution, runner_profile)
+well_known = fs.build_well_known(..., configuration=conf, summary=fp.configuration_summary(conf) + other_tiles)
+```
+
+`configuration` is read-only: a change is made in Fabric and reaches the service through its binding, never through
+the well-known document. `configuration_summary` gives the **Runner** and **Model** tiles ("claude-code ·
+subscription", "default · deepseek/deepseek-v4-pro") that the dashboard shows beside the others. The probe checks the
+declaration (`configuration.declared`).
+
+## The doctor
+
+`runner_check(entry)` / `runnerCheck(entry)` takes one entry of Fabric's runner catalogue (`registry/runners.json`)
+and answers whether the runner is installed, which version answers and whether it is signed in. It runs only a bare
+catalogued binary found on `PATH`, only with the catalogued version argv (and `auth` argv), without a shell, within
+the entry's timeout (at most 5 s); an entry outside these rules is refused and nothing runs. `model_usable(model,
+catalogue, policy)` names why a model cannot be used here: not catalogued, or a class the project does not allow.
+
+## Usage by route
+
+`make_usage_receipt(..., route="subscription"|"key")` records how the call was paid — the operator's own login in its
+vendor's runner, or an issued key. The usage report keeps the rows of one model on two routes apart.

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/protocol.md

@@ -63,7 +63,7 @@ No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
   entries through unchanged.
 - `configuration` (DEC-0046) MAY say which runner and model profile the service resolved and from where
   (`request`, `agent`, `binding`, `estate`); a usage receipt MAY carry the `route` (`subscription` or `key`). The kits
-  do not emit either yet (FAA-19).
+  build both: `fabric_profiles.configuration` and `make_usage_receipt(route=)` ([profiles](profiles.md)).
 - `build` needs `commit` or `digest` (`sha256:<64 hex>`).
 - `summary`: at most six tiles; `attention: true` counts toward the host's badge.
 - `surfaces.events` is required; `dashboard` and `mcp` when the service has them; `usage`

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/surfaces-and-auth.md

@@ -21,7 +21,9 @@
   (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
   atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
   goes in `headers`, never in the URL — every log that records a URL prints its query
-  string.
+  string. An HTTP registration starts nothing per session: every client session talks to the
+  one resident service (LC-19). A stdio server, by contrast, is a process per session — keep
+  one only at project scope.
 - Ship server `instructions` that tell a caller where to start and that every answer
   carries `degraded`.
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py

@@ -245,6 +245,7 @@ class Probe:
         if "events" not in (wk.get("surfaces") or {}):
             problems.append("surfaces.events missing")
         self.add("well-known.shape", "FAIL" if problems else "PASS", "; ".join(problems) or "protocol, build, status, degraded, surfaces")
+        self.configuration_rule()
         svc = wk.get("service") or {}
         answered = "%s.%s" % (svc.get("id"), svc.get("instance"))
         expected = "%s.%s" % (self.d.get("id"), self.d.get("instance", "default"))
@@ -524,6 +525,16 @@ class Probe:
                 self.trace_rule(listing, sent)
         self.events_trace_rule(self.events)
 
+    def configuration_rule(self) -> None:
+        """DEC-0046: a well-known `configuration` is {slots, resolved} as the schema types it; absent is NOT_RUN."""
+        if not isinstance(self.wk, dict) or "configuration" not in self.wk:
+            self.add("configuration.declared", "NOT_RUN", "the service declares no runner or model configuration")
+            return
+        problems = fs.configuration_problems(self.wk["configuration"])
+        self.add("configuration.declared", "FAIL" if problems else "PASS", "; ".join(problems) or
+                 "slots %s; resolved from %s" % (", ".join(self.wk["configuration"].get("slots") or []) or "none",
+                                                 (self.wk["configuration"].get("resolved") or {}).get("from", "not stated")))
+
     def delegation_declared_rule(self, mcp_surface: Optional[Dict[str, Any]]) -> None:
         """DL-16 (DEC-0039): a service that accepts delegation tokens names the issuer it trusts and its JWKS
         in auth.delegation; with surfaces.mcp.auth delegation that declaration is required."""