@passioncode-ai/fabric-agent-adapter 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # Changelog
 
+## 0.41.0 (2026-10-22)
+
+The 2026-10-22 audit, closed (FAA-68 to FAA-81; [report](docs/reports/2026-10-22-adapter-audit/README.md),
+[brief](docs/evidence/specs/2026-10-22-audit-fixes-brief.md)). Its 53 findings fell into six classes; each class got
+its fixes and a guard that fails the next instance. Each fix has a test; the builders' reports and the commit
+messages name the ones seen failing before the fix. Three blind readings (unit, seam, product) certified the result
+and their findings are fixed here too.
+
+### Fixed
+
+- **Session hooks and the delivery worker** (FAA-68). One JSON-RPC error or unreadable spool entry no longer blocks
+  a session's spool for good: the entry is logged by its code and dropped, and the end, the claim release and the end
+  observation still go out. `fabric-mcp` runs in its own process group and the whole group is ended at the deadline,
+  so a wrapper (`npx`, a shell script, `fabric-mcp.cmd`) cannot hold the worker for a minute. A process walk that
+  cannot read the processes spools nothing and releases nothing; a launched session is remembered. Turn facts are
+  measured when the turn ends (counts only). watch-mail keeps its delay between 10 s and 15 min after the jitter and
+  honours the once-a-minute rejoin mark. Stale spool folders are pruned even while the hooks are inert; a stale
+  worker lock is taken by an atomic rename, and its identity includes the write time and size (Linux reuses a freed
+  inode number at once). An end whose release got no answer stays for the next worker. On Windows a bare `fabric-mcp`
+  resolves to `fabric-mcp.cmd`.
+- **Host installers and the dashboard notice** (FAA-69). The SessionStart notice asks whether the repository owns a
+  service before it reads the tree, all within one 3.5 s budget. The Kimi installer repairs or removes a stale script
+  path; Kimi and Codex require the script to exist; Hermes `--remove` works without the source folder; the OpenCode
+  and OpenClaw bridges run the helper once per workspace, not per request, and never keep a failed run.
+- **The service kit's Python twin** (FAA-70). `launchd_plist` refuses what the Node twin refuses: a secret-shaped
+  argument or environment value, a bad label, an empty argv, an `ExitTimeOut` under the drain. `JobStore` and the
+  event log hold a lock per store path (one idempotency key made two jobs; a cancelled job became completed; 41 of
+  160 events were kept). `pause` checks for a terminal job first (both twins). The JWKS fetch has one 5 s deadline,
+  runs outside the cache lock and turns a garbage answer into `issuer-unavailable`. Whole-value patterns end in
+  `\Z`, so a trailing newline no longer validates. An origin written with its default port is accepted as Node
+  accepts it. A socket timeout is a timeout on Python 3.9. Non-object MCP params answer -32602. systemd
+  `Environment=` no longer doubles `$`. The sample service answers 400 to a bad `Content-Length` or body.
+- **The board responder** (FAA-77). A lost reply answer no longer leaves a request `accepted` for good: a transfer
+  re-derives the per-attempt keys after re-sending the old reply under its old key, and `idempotency_conflict` is its
+  own `board.blocked` event. One fenced call per entry at a time, and a `revision_conflict` on renew re-reads the
+  revision. An effect lost while the session holds the slot is observed and completed, or its slot is replaced so the
+  board records `outcome_unknown`. One lost answer keeps the session while the lease holds. Every transferred request
+  resumes, and a transfer survives a second lost answer (the request completes with one reply). The session's link
+  (MCP session, checkpoint, request) is its own module, `fabric_board_link` / `fabric-board-link.mjs`.
+- **Interop job keys** (FAA-70, FAA-77). A key admits only the intent it was first used for: another capability or
+  input is `idempotency-conflict` in `create` and `conflict` in `repeat`, which now takes the intent. A key file
+  written before 0.41.0 is answered with its job, and runs again only for the intent its job stored.
+- **Package, delegation and estate twins** (FAA-78). Both kits refuse a package path holding a control character,
+  U+2028 or U+2029, whatever the schema's pattern lets through (the contract owner was told). An unreadable folder
+  entry is refused instead of skipped (Python) or crashing (Node). Files are opened without following links. Node
+  reads JSON as strict UTF-8 and keeps a top-level `__proto__`; both cap nesting at 256 levels; dates take ASCII
+  digits. An explicit `null` estate, applied mark or revocation list fails closed in both kits. JWKS `x` must be
+  canonical base64url in both. Python Ed25519 signing is a Montgomery ladder that does not branch on the key. The
+  hub's loopback origin takes ASCII digits only. On Windows, `fabric.package.json` is written with `\n` like the Node
+  kit's, and the command line answers in UTF-8 whatever the console's code page.
+- **The adapting skill's scripts** (FAA-71). `fabric_provider.py write` refuses what the pinned provider schema
+  refuses (ports under 100, a non-URI repository, an argument over 1024 characters), refuses `--env` with `--url`
+  and a writer option after `--stdio`. `check` names every template value still present and keeps
+  `readyForAdmission` false; `check --contract` calls the checkout's own `tsx`, never `pnpm exec`; a client
+  `.mcp.json` is not an MCP surface; a non-UTF-8 manifest is a typed receipt. `scaffold --dry-run` prints the writes
+  and a diff of each collision.
+- **Dashboard probes and the link gate** (FAA-79). The layout probe never prints a login code (it starts the browser
+  before asking for one); ED-3 checks vertical clipping; ED-4 says NOT_RUN past its element cap. The handoff-link
+  gate normalises the path and refuses `code`, `api_key` and the other credential names. The "Get Fabric" menu link is
+  reachable by keyboard; the dashboard kit is 1.1.2.
+- **Installers** (FAA-80). `install.sh` leaves an existing copy alone without `--force` and never copies
+  `__pycache__`; both installers build a new copy beside the old and rename it, report each failure and exit 1.
+- **The support-agent recipe** (FAA-81). A reply carrying a link (bare host names included), address, phone number,
+  amount or number its cited entries do not contain goes to a person; links and addresses are compared by equality,
+  never as substrings; the customer's message reaches the model as fenced data. A promise written in words is not
+  caught, and the README says so. Decisions are an
+  append-only log; `prune --keep-days N` deletes old rows; the README says the outbox keeps customer text.
+
+### Changed
+
+- **CI follows the organization's rule** (FAA-72). `validate.yml` runs nightly on `main` and on dispatch, with job
+  timeouts and a concurrency group; a `contract` job installs the contract at the pin and at the legacy revision and
+  runs the tests that used to skip (one of them had rotted); a `floors` job runs Python 3.9 and Node 18; a `macos` job
+  runs both suites; Windows runs the session tests and the whole Node suite (16 tests that assumed POSIX now check
+  the Windows ACL or say why they skip). `engines.node` is `>=18` (the npm CLI); the Node service kit needs 20, and on
+  Linux its instance lock needs 22: Node 18 and early 20 collapse every abstract socket name into one, and later 20
+  pads it so no Python copy or probe sees it, so the kit refuses to start there with a sentence naming Node 22.
+- **The release path** (FAA-73). The tarball smoke test runs before the GitHub release is created; every action is
+  pinned to a commit SHA; npm and the Claude Code CLI are pinned; release titles carry no em dash; the dead
+  private-repository branch is gone. Moving npm publishing to trusted publishing (and removing `NPM_TOKEN`) waits on
+  the operator's npmjs.com sign-in.
+- **Skills and documents** (FAA-74, FAA-75). SECURITY.md and SKILL-CARD say what the probe and the kit really reach
+  and write; the `vault.py moved` command is correct; the secret tools have a path and a fallback; each skill's
+  NOT-for list names its siblings; shared blocks live in one reference; the building skill's description is 799
+  characters. `test/evals/run_evals.py` runs the trigger evals against a real client when asked; its first run scored
+  25/25 on `adapting-projects-to-fabric`.
+
+### Guards (each fails on a planted defect)
+
+- `validate.py` refuses a `$`-anchored whole-value pattern in every skill's scripts (R1; it found a real one in
+  `adapt_project`'s cost preset id), an em dash under
+  `.github/` (R6), and a workflow that floats an action, uses `@latest`, lacks a timeout, drops the nightly or gated
+  jobs, gains a push or PR trigger, or creates the release before the smoke test (R5).
+- Shared hostile-input fixtures run by both twins: `kit-hostile-inputs-core.json`, `kit-hostile-inputs-package.json`,
+  `kit-hostile-inputs-estate.json` (R1).
+- Fault-injection tests for the spool, the worker, the responder and the package walk (R2); concurrency tests for every
+  store a threaded server reaches (R3).
+- `test_a_released_version_keeps_its_digests`: a release's `kit.json` history entry stays what the release shipped (a
+  build before the version moved on had rewritten 0.40.0's, which would have read genuine 0.40.0 copies as modified).
+  It runs in a clone that has the release tags (a full local clone); the shallow hosted checkout skips it (FAA-82).
+- Two timing tests no longer fail on a loaded host: the runner probe's positive cases take the most a probe may take,
+  and the interop probe test lets the machine-timing verdict be the one that fails.
+
+### Upgrading
+
+- **A service built on the copied kit:** `fabric_kit.py status <dir>` names the modules to update; `fabric_kit.py install
+  <dir>` brings the closure, `fabric_board_link` included. Passing `estate=None` (or `estate_applied=None`,
+  `estate_revocations=None`) on purpose now refuses every token as `estate-unreadable`: leave the option out instead.
+- **A Linux service on the Node kit:** run it on Node 22 or later; on 18 or 20 it stops at start with a sentence saying so.
+- **A scaffolded bundle:** new scaffolds write a `urn:fabric:adapter:template` block into `fabric-agent.json` and take
+  `--data-class`, `--created-by`, `--identity-method` and `--probe-assertion`. Rerun `check`: an older bundle that still
+  holds the template's author, schemas or assertions now reads `readyForAdmission: false` until they are replaced.
+- **A dashboard on kit 1.1.1:** the SessionStart notice now points at 1.1.2; `dashboard_kit.py install` updates it.
+- **The support recipe:** its state moves to `decisions.jsonl` (an old `decisions.json` is still read); handoff rows gain
+  `question` and `at`, and new reasons `unsupported:url|email|phone|amount|number`. Run `prune --keep-days N` once, then
+  delete `decisions.json`.
+- **Links you hand out:** the gate now refuses a query or fragment name such as `code`, `key`, `auth` or `api_key`, and
+  a path with a dot segment or an encoded separator.
+- **Installing:** a copy already in the hub is kept unless `--force` (both installers); the npm installer reports each
+  skill `up to date`, `differs` or installed, and never copies Python bytecode.
+- **Open human step:** moving npm publishing to trusted publishing and deleting `NPM_TOKEN` needs the operator's
+  npmjs.com sign-in.
+
+
 ## 0.40.0 - 2026-10-21
 
 The kits as production modules (FAA-65). Every name a kit module made public at 0.39.1 is still there; a service that

package/README.md

@@ -38,8 +38,8 @@ resume) puts that preamble into the session when the MCP server `fabric` is regi
 is down it adds one line (skip `fabric_whoami`, start Fabric through the broker if the task needs it), and only in a
 project that uses Fabric; Stop records each turn's facts (HEAD, files changed, lines added and removed, never content)
 and the board's unread count; UserPromptSubmit adds one line only when that count rose; SessionEnd releases what the
-session left claimed. Stop, UserPromptSubmit and SessionEnd act only when the running Fabric advertises
-`session-hooks/1`. All are silent in a session Fabric launched, never block the session, read no token and always
+session left claimed. Stop, UserPromptSubmit and SessionEnd spool and call Fabric only when the running Fabric
+advertises `session-hooks/1`; Stop and SessionEnd always prune their own stale spool folders. All are silent in a session Fabric launched, never block the session, read no token and always
 exit 0. `fabric_session.py watch-mail` waits for board mail under a background watcher, and `install-host-hooks
 --host codex|kimi|hermes|opencode|openclaw|pi` installs each host's native context bridge (dry run unless `--apply`).
 Codex receives structured SessionStart JSON; Hermes, OpenCode, OpenClaw and Pi use native plugin APIs.
@@ -129,8 +129,13 @@ then restart your agents. Alone, without any account:
 ```bash
 npx @passioncode-ai/fabric-agent-adapter        # installs every skill into the agents hub ~/.agents/skills
 npx @passioncode-ai/fabric-agent-adapter --prune-shadow   # remove ~/.claude/skills copies that shadow the plugin
+npx @passioncode-ai/fabric-agent-adapter --force          # update a copy already in the hub (a launcher link is never replaced)
 ```
 
+A copy already in the hub is left alone unless `--force` is given; with it, the new copy is built beside the old one
+and renamed into place, so a failed run leaves the old copy or nothing. `install.sh --force` from a checkout does the
+same.
+
 Claude Code plugin marketplace:
 
 ```text
@@ -189,7 +194,8 @@ own service by its id once its installer has written the descriptor.
 
 ### Develop
 
-There is no build step and no dependency beyond Python 3.9+ and Node.js:
+There is no build step and no dependency beyond Python 3.9+ and Node.js. The npm CLI (installer, `pack`, `sign`,
+`verify`) needs Node.js 18+, the Node service kit 20+, and a Linux service's instance lock 22+:
 
 ```bash
 npm test                     # validate.py, the Python unit tests, the Node kit tests

package/SECURITY.md

@@ -11,13 +11,34 @@ bounded and non-publishing until explicit scoped grants exist in a project bindi
 ## What the installers and scripts touch
 
 - `npx @passioncode-ai/fabric-agent-adapter` and `install.sh` write only
-  `~/.agents/skills/<skill>`; `--target claude` writes `~/.claude/skills/<skill>` and is
+  `~/.agents/skills/<skill>` (and, while replacing a copy with `--force`, the sibling folders
+  `.<skill>.installing-*` and `.<skill>.replaced-*`, removed when the run ends; a killed run can
+  leave one behind); `--target claude` writes `~/.claude/skills/<skill>` and is
   refused while the plugin is installed; `--prune-shadow` moves shadowing copies into
   `~/.claude/skills-shadow-backup/`.
 - `building-fabric-services/scripts/check_service.py` reads a descriptor and the token
-  file it names, talks only to `127.0.0.1:<port>`, and redeems one login code it asked
-  for itself (creating one dashboard session). It never prints the token.
+  file it names, and redeems one login code it asked for itself (creating one dashboard
+  session). It never prints the token. For a local service it talks only to
+  `127.0.0.1:<port>`; for a remote placement it talks to the service's own `https` origin
+  named in the descriptor (`--ca-file` and `--connect` only change which CA it trusts and
+  which address it dials, for tests).
 - The service kits create the service token (0600) and the instance lock in the
-  service's own data directory, and write a launchd plist and a descriptor only when an
-  installer calls them. The token is readable by any process of the same user; the
-  protocol defends against web pages and mistakes, not against hostile local code.
+  service's own data directory, and write supervisor files only when an installer calls
+  them: a launchd plist in `~/Library/LaunchAgents` (macOS), a systemd user unit (Linux) or
+  a per-user Scheduled Task (Windows), plus one descriptor in the services directory. The
+  token is readable by any process of the same user; the protocol defends against web pages
+  and mistakes, not against hostile local code.
+- The kits' connectors (`fabric_http`, `fabric_openrouter` and their Node twins) reach the
+  external APIs the service's author configures, such as OpenRouter, with keys the service
+  reads by name at run time; the kit itself calls no outside host on its own. A board
+  responder talks only to Fabric's hub on loopback.
+- The working-with-fabric session hooks run as the person: Stop and SessionEnd run `git`
+  in the session's folder (counts only, at most 1.5 s), read the process table to tell a
+  session Fabric launched, write their spool and log under the user's cache folder (0600),
+  and the delivery worker starts `fabric-mcp` in its own process group and ends that group
+  (`killpg`, or `taskkill /T /F` on Windows) at its 10 s deadline. They read no token.
+- `adapting-projects-to-fabric/scripts/adapt_project.py` reads the target project without
+  executing it and writes only the seven documented bundle paths (`scaffold --dry-run`
+  writes nothing); `check --contract` runs the contract checkout's own
+  `node_modules/.bin/tsx` and installs nothing. `fabric_provider.py write` writes one
+  entry (0600) in the providers directory.

package/bin/fabric-agent-adapter.js

@@ -6,8 +6,9 @@
  * ~/.agents/skills/<name> (read by Codex, Cursor, Gemini, OpenCode and others).
  * Claude Code gets the skills through the plugin, never through a plain copy:
  * a copy in ~/.claude/skills shadows the plugin and serves its frozen version
- * forever. Idempotent; an existing install is skipped unless --force.
- * Zero dependencies.
+ * forever. Idempotent; an existing install is skipped unless --force. Each skill is
+ * copied into a sibling temporary folder and renamed into place, so a failure
+ * leaves the old copy or nothing, never half of each. Zero dependencies.
  */
 'use strict';
 
@@ -46,9 +47,13 @@ Every PassionCode.ai skill for every agent at once:
   npx @passioncode-ai/passioncode@latest update`);
 }
 
+// Bytecode a checkout's own runs left behind is not part of a skill.
+function bytecode(name) { return name === '__pycache__' || name.endsWith('.pyc'); }
+
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (bytecode(entry.name)) continue;
     const s = path.join(src, entry.name);
     const d = path.join(dest, entry.name);
     if (entry.isDirectory()) copyDir(s, d);
@@ -56,6 +61,54 @@ function copyDir(src, dest) {
   }
 }
 
+// The same files with the same bytes: what "already installed" means.
+function sameTree(src, dest) {
+  let a;
+  let b;
+  try {
+    a = fs.readdirSync(src, { withFileTypes: true }).filter((e) => !bytecode(e.name));
+    // The same filter on both sides: an installed skill whose Python ran has its own __pycache__.
+    b = fs.readdirSync(dest, { withFileTypes: true }).filter((e) => !bytecode(e.name));
+  } catch {
+    return false;
+  }
+  if (a.length !== b.length) return false;
+  const there = new Map(b.map((e) => [e.name, e]));
+  return a.every((e) => {
+    const d = there.get(e.name);
+    if (!d || e.isDirectory() !== d.isDirectory() || d.isSymbolicLink()) return false;
+    const s = path.join(src, e.name);
+    const t = path.join(dest, e.name);
+    if (e.isDirectory()) return sameTree(s, t);
+    try { return fs.readFileSync(s).equals(fs.readFileSync(t)); } catch { return false; }
+  });
+}
+
+// Copy beside, then rename over: the old copy stays until the new one is whole.
+function installSkill(src, dest) {
+  const stamp = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+  const temp = path.join(path.dirname(dest), `.${path.basename(dest)}.installing-${stamp}`);
+  const old = path.join(path.dirname(dest), `.${path.basename(dest)}.replaced-${stamp}`);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  try {
+    copyDir(src, temp);
+    if (fs.existsSync(dest)) {
+      fs.renameSync(dest, old);
+      try {
+        fs.renameSync(temp, dest);
+      } catch (err) {
+        fs.renameSync(old, dest);
+        throw err;
+      }
+      fs.rmSync(old, { recursive: true, force: true });
+    } else {
+      fs.renameSync(temp, dest);
+    }
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+  }
+}
+
 // A link in the hub belongs to whoever made it: 'launcher' for the PassionCode launcher's
 // ~/.passioncode/... links, 'other' for any other link, null for a directory or nothing.
 function linkOwner(dest) {
@@ -144,6 +197,7 @@ function main(argv) {
   }
 
   const destRoot = target === 'claude' ? path.join(home, '.claude', 'skills') : path.join(home, '.agents', 'skills');
+  const failed = [];
   for (const name of names) {
     const dest = path.join(destRoot, name);
     const owner = linkOwner(dest);
@@ -155,13 +209,24 @@ function main(argv) {
         : `skip: ${name} at ${dest} is a link managed elsewhere; remove the link first to install a copy here`);
       continue;
     }
+    const src = path.join(skillRoot, name);
     if (fs.existsSync(dest) && !force) {
-      console.log(`skip: ${name} already installed at ${dest} (rerun with --force to overwrite)`);
+      console.log(sameTree(src, dest)
+        ? `up to date: ${name} at ${dest}`
+        : `skip: ${name} at ${dest} differs from this version (rerun with --force to replace it)`);
       continue;
     }
-    fs.rmSync(dest, { recursive: true, force: true });
-    copyDir(path.join(skillRoot, name), dest);
-    console.log(`Installed ${name} -> ${dest}`);
+    try {
+      installSkill(src, dest);
+      console.log(`Installed ${name} -> ${dest}`);
+    } catch (err) {
+      failed.push(name);
+      console.error(`error: ${name} was not installed (${err.code || 'error'}: ${err.message}); ${fs.existsSync(dest) ? 'the copy that was there is unchanged' : 'nothing was left at ' + dest}`);
+    }
+  }
+  if (failed.length) {
+    console.error(`error: ${failed.length} of ${names.length} skill(s) failed: ${failed.join(', ')}`);
+    return 1;
   }
   if (target === 'agents' && !hasPlugin) {
     console.log(`Claude Code reads plugins, not the hub:\n  claude plugin marketplace add ${REPO} && claude plugin install ${PLUGIN_ID}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.40.0",
+  "version": "0.41.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'"
@@ -31,7 +31,7 @@
     "url": "https://passioncode.ai/"
   },
   "engines": {
-    "node": ">=16"
+    "node": ">=18"
   },
   "keywords": [
     "fabric",

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; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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

@@ -1,11 +1,11 @@
 ---
 name: adapting-projects-to-fabric
-description: Use when adapting an existing agent, MCP server, A2A peer, HTTP service, or terminal CLI to the Fabric Agent Contract (choosing MCP/A2A/local-runner, scaffolding a provider bundle, or checking Fabric compatibility); also for «подключить проект к Fabric» or «сделать агента совместимым с Fabric». NOT for building the Fabric host/orchestrator, configuring an MCP client, or a brand-new agent (that is creating-fabric-agents).
+description: Use when adapting an existing agent, MCP server, A2A peer, HTTP service, or terminal CLI to the Fabric Agent Contract (choosing MCP/A2A/local-runner, scaffolding a provider bundle, or checking Fabric compatibility); also for «подключить проект к Fabric» or «сделать агента совместимым с Fabric». NOT for building the Fabric host/orchestrator, configuring an MCP client, a brand-new agent (creating-fabric-agents), running an agent as a local or online Fabric service with a dashboard (building-fabric-services), or a coding session working through Fabric, its board or claims, «подключись к Fabric» (working-with-fabric).
 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.40.0"
+  version: "0.41.0"
   contract-version: "0.1.0"
   contract-commit: "c55f2d5a11c9a0197e958e87212fca7ae1154769"
 ---
@@ -25,7 +25,11 @@ Use this skill to adapt or assess a provider project. Do not use it to:
 - answer wire-level MCP or A2A questions (transports, sessions, auth handshakes, task
   states on the wire): that is `agent-interop` (agent-stack); the pinned contract stays
   normative for what Fabric requires;
-- design a new agent from scratch: that is the sibling skill creating-fabric-agents;
+- design a new agent from scratch: that is the sibling skill `creating-fabric-agents`;
+- run the agent as a resident service with a dashboard, a descriptor and launchd: that is
+  `building-fabric-services`;
+- work in a project through Fabric from a coding session (registering `fabric-mcp`, the board,
+  claims): that is `working-with-fabric`;
 - claim admission merely because generated files or a valid manifest exist.
 
 If the project has only a browser interface and no stable API, MCP/A2A surface, or CLI,
@@ -57,7 +61,9 @@ python3 <skill-dir>/scripts/adapt_project.py inspect <project-root> --json
 ```
 
 The inspector samples repository files but does not execute the project. Verify its
-evidence manually. Existing runtime documentation and code outrank filename heuristics.
+evidence manually. Existing runtime documentation and code outrank filename heuristics. A
+client configuration (`.mcp.json`, an `mcpServers` block) lists servers the project calls, not one
+it serves: inspect reports it as `mcp-client-config` and asks instead of choosing `mcp`.
 
 If the inspector returns `undetermined`, answer its lifecycle question before creating
 files. A repository can expose multiple surfaces; choose a profile per capability, not
@@ -110,12 +116,18 @@ target paths. It refuses any collision.
 `charge`, `delete`, `merge`, `deploy`, `change-policy`), read from what the code does or asked of the author. Choose
 `--idempotency required|supported|none` for an external effect on purpose. When a run's cost varies, give the
 launcher fixed options (DEC-0037): `--cost-preset ID MAX_USD LABEL` per option and `--default-cost-preset ID`; the
-amounts come from the author or measured runs, never invented. Do not use `--force` unless the user explicitly
-authorizes replacement after the exact conflicting files and diff are shown.
+amounts come from the author or measured runs, never invented. Pass what the author knows so it is not written as a
+scaffold default: `--data-class` (repeat), `--created-by URI`, `--identity-method`, `--probe-assertion` (repeat).
 
-The generated zero hash, `.invalid` endpoints, `replace-me` values, generic schemas, and
-assertions are deliberate blockers. Replace them with implementation-backed facts. A
-template that still contains one is not ready for admission.
+On a collision run `scaffold --dry-run` first: it writes nothing and prints the planned writes and a unified diff of
+each existing file. Use `--force` only when the user authorizes replacing exactly those files.
+
+Every value the scaffold invents is a sentinel that `check` names: the zero hash, `.invalid` endpoints,
+`replace-me` values, `urn:fabric:adapter:author`, the generic schemas (marked `fabric-adapter-template`), the
+generic fixture and assertions, and each value listed under the manifest's `urn:fabric:adapter:template`
+extension (the defaulted `dataClasses`, a defaulted `tls` identity method). Replace each with an
+implementation-backed fact, then remove it from that list and the block when it is empty. While one remains,
+`readyForAdmission` is false.
 
 ### 4. Implement the adapter seam
 
@@ -138,11 +150,14 @@ Treat all provider output as untrusted until schemas and semantic assertions pas
 
 ### 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`).
+An agent Fabric reaches as a stdio MCP server, or as an MCP server on a loopback URL that is not
+a service, 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).
+A provider entry only describes an MCP server: a CLI that does not speak MCP gets no entry; it is
+announced by its `local-runner` manifest (step 3). An agent that runs as a service uses a
+descriptor instead (`building-fabric-services`).
 
 ### 5. Make probes safe and meaningful
 
@@ -195,58 +210,25 @@ Update `fabric/FABRIC-CONFORMANCE.md` with dated receipts for:
 
 Include commands and exit codes, immutable endpoint or artifact identities, and explicit
 unverified surfaces. If live Fabric admission/runtime does not yet exist, the last gates
-remain `NOT VERIFIED`; the completed deliverable is an adaptation-ready provider bundle,
+remain `NOT_VERIFIED`; the completed deliverable is an adaptation-ready provider bundle,
 not a connected provider.
 
 ### 8. Propose the operator channel
 
 If the agent has a human stop (a choice, an approval, a confirmation) or emits `notify: true`
-events, propose its **operator channel** to the operator once, now. The channel is the agent's
-own messenger channel, first Telegram, that sends those events and answers its stops with
-buttons: `fabric-operator-channel/0.1` (contract DEC-0034,
-`docs/specification/operator-channel.md`), whose rule OC-11 this step follows. Give the
-operator's four steps:
-
-1. create a bot with @BotFather;
-2. put its token into the operator's secret store under the name the agent reads (for example
-   `EXAMPLE_AGENT_TELEGRAM_BOT_TOKEN`), never into a chat, a file or the bundle;
-3. run the agent's link command;
-4. type the code it shows in the chat with the bot.
-
-In a group shared with other bots the channel follows OC-14…OC-17 (DEC-0035): it stays silent
-unless addressed (`/command@ThisBot`, a reply to its own message or a press of its own button; a
-bare `/command` in a group is not addressed), and a channel nobody receives on is `degraded`
-(`receiver-missing`). Say so in the proposal when the operator means to bind a shared group.
-
-Record the answer (`accepted`, `declined` or `later`) in the agent's state and the
-conformance report, and do not ask again; an agent that serves `surfaces.operatorChannel` also
-shows it as `proposal` in its status document. Creating the bot, storing the token and enabling the
-channel are the operator's action: never create the bot, ask for or store the token's value, or
-enable the channel yourself. The default pin carries DEC-0034 and DEC-0035: a served status document is checked
-against the pinned `schemas/operator-channel-status.schema.json`; the channel's runtime rules have
-no probe rule here yet, so report them `NOT_RUN`. An agent with neither stops nor notify
-events skips this step.
+events, propose its operator channel (`fabric-operator-channel/0.1`, OC-11) to the operator once,
+now, as [the operator channel and the repository standard](references/operator-channel-and-repository.md)
+describes: the operator's four steps, the answer recorded and never asked again, and the bot, the
+token and enabling the channel left to the operator. An agent with neither stops nor notify events
+skips this step.
 
 ## The repository around the provider
 
 **For a PassionCode.ai repository**, the adapted project's repository follows the organization's
-[repository standard](https://github.com/passioncode-ai/fabric-workspace/blob/main/knowledge/repository-standard.md) (`knowledge/repository-standard.md`
-in the organization's knowledge base; a clone has it at `fabric-workspace/knowledge/`) from its
-first commit:
-
-- `LICENSE`, `COMMERCIAL-LICENSE.md` and `CLA.md` copied byte for byte from the knowledge base's
-  `templates/`, and `AGPL-3.0-only OR LicenseRef-PassionCode-Commercial` in every manifest and
-  every SKILL.md `license:`; `SECURITY.md` when the repository is public;
-- a README whose first heading is the full name, with `## Quick start for a new teammate`
-  (Install; Configure, key names only; MCP, the registration command and one proving tool call,
-  verified with a real client in a temporary config; Develop) and `## License`;
-- an `AGENTS.md` that opens with the template's *Read first* block and closes with *After work*,
-  and a `CLAUDE.md` whose first line is `@AGENTS.md`.
-
-org-index `scripts/check_format.py` reports 0 findings for it before it is called done. **An agent
-someone builds for themselves is not a PassionCode.ai repository:** its licence is its owner's
-choice, nothing about it is published or listed by the organization, and none of these files is
-required of it, though the verified MCP quick start is still how anyone learns to drive it.
+repository standard (`knowledge/repository-standard.md`) from its first commit: the licence files,
+the README quick start verified with a real client, `AGENTS.md` and `CLAUDE.md`, listed in the
+shared reference above. An agent someone builds for themselves is not a PassionCode.ai repository:
+its licence is its owner's choice and none of those files is required of it.
 
 ## Completion format
 
@@ -265,12 +247,6 @@ passed against a real provider and the project binding is valid.
 
 ## Dashboard handoff: also for consumers
 
-When handing a registered service dashboard to a person, or writing the generated
-agent's completion/notification instructions, read and apply
-[dashboard links](references/dashboard-links.md): use the host's `open_link`,
-check the target device and host, and run the bundled output gate before delivery.
-An installed host failure never means browser fallback. This applies in Claude
-Code, Codex and other providers; it needs no host-specific hook. MCP unavailable:
-report the unresolved capability or use an approved project resolver; no automatic
-client configuration. Python unavailable: perform the reference's manual checks
-and report the executable gate NOT_RUN. Headless agents need no dashboard.
+When handing a registered service dashboard to a person, or writing the generated agent's
+completion or notification instructions, read and apply [dashboard links](references/dashboard-links.md)
+and run its output gate before delivery, in any host. Headless agents need no dashboard.

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/dashboard-links.md

@@ -83,8 +83,10 @@ or instructions alone do not prove all final answers from every agent are filter
   path is required. Skills must be activated/loaded; install does not intercept every answer.
 - MCP absent: report unresolved host capability once, use the project's approved
   resolver/CLI if available. Do not write machine or agent MCP config automatically.
-- Python absent: perform the comparisons above manually; mark the executable gate
-  NOT_RUN. Do not label the output mechanically validated.
+- Python absent: perform the comparisons above manually, including the gate's own rules (a
+  path with a `.` or `..` segment, an encoded or backslash separator, or a query or fragment
+  name or value that reads as a credential, such as `code`, `key`, `auth` or `api_key`, is
+  refused); mark the executable gate NOT_RUN. Do not label the output mechanically validated.
 
 Syntax is owned by Fabric Dashboards and `@passioncode-ai/fabric-service-host`:
 [ADR-0005](https://github.com/passioncode-ai/fabric-dashboards/blob/51a7a80acf42781d7bec304cc87c655d48cc309b/docs/adr/0005-service-links.md).

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/operator-channel-and-repository.md

@@ -0,0 +1,55 @@
+# The operator channel and the repository standard
+
+Shared by `adapting-projects-to-fabric` and `creating-fabric-agents`; the two copies are byte-identical
+(`test/test_shared_references.py`). "The agent" is the provider being adapted or created.
+
+## The operator channel
+
+If the agent has a human stop (a choice, an approval, a confirmation) or emits `notify: true`
+events, propose its **operator channel** to the operator once, at the step that links here. The
+channel is the agent's own messenger channel, first Telegram, that sends those events and answers
+its stops with buttons: `fabric-operator-channel/0.1` (contract DEC-0034,
+`docs/specification/operator-channel.md`), whose rule OC-11 this follows. Give the operator's four
+steps:
+
+1. create a bot with @BotFather;
+2. put its token into the operator's secret store (Project Observatory where it is installed) under
+   the name the agent reads (for example `EXAMPLE_AGENT_TELEGRAM_BOT_TOKEN`), never into a chat, a
+   file or the bundle;
+3. run the agent's link command;
+4. type the code it shows in the chat with the bot.
+
+In a group shared with other bots the channel follows OC-14 to OC-17 (DEC-0035): it stays silent
+unless addressed (`/command@ThisBot`, a reply to its own message or a press of its own button; a
+bare `/command` in a group is not addressed), and a channel nobody receives on is `degraded`
+(`receiver-missing`). Say so in the proposal when the operator means to bind a shared group.
+
+Record the answer (`accepted`, `declined` or `later`) in the agent's state and in its conformance
+report, and do not ask again; an agent that serves `surfaces.operatorChannel` also shows it as
+`proposal` in its status document. Creating the bot, storing the token and enabling the channel
+are the operator's action: never create the bot, ask for or store the token's value, or enable the
+channel yourself. The default pin carries DEC-0034 and DEC-0035: a served status document is
+checked against the pinned `schemas/operator-channel-status.schema.json`; the channel's runtime
+rules have no probe rule here yet, so report them `NOT_RUN`. An agent with neither stops nor notify
+events skips this.
+
+## The repository standard
+
+For a PassionCode.ai repository, the agent's repository follows the organization's
+[repository standard](https://github.com/passioncode-ai/fabric-workspace/blob/main/knowledge/repository-standard.md)
+(`knowledge/repository-standard.md` in the organization's knowledge base; a clone has it at
+`fabric-workspace/knowledge/`) from its first commit:
+
+- `LICENSE`, `COMMERCIAL-LICENSE.md` and `CLA.md` copied byte for byte from the knowledge base's
+  `templates/`, and `AGPL-3.0-only OR LicenseRef-PassionCode-Commercial` in every manifest and
+  every SKILL.md `license:`; `SECURITY.md` when the repository is public;
+- a README whose first heading is the full name, with `## Quick start for a new teammate`
+  (Install; Configure, key names only; MCP, the registration command and one proving tool call,
+  verified with a real client in a temporary config; Develop) and `## License`;
+- an `AGENTS.md` that opens with the template's *Read first* block and closes with *After work*,
+  and a `CLAUDE.md` whose first line is `@AGENTS.md`.
+
+org-index `scripts/check_format.py` reports 0 findings for it before it is called done. An agent
+someone builds for themselves is not a PassionCode.ai repository: its licence is its owner's
+choice, nothing about it is published or listed by the organization, and none of these files is
+required of it, though the verified MCP quick start is still how anyone learns to drive it.

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

@@ -32,7 +32,9 @@ python3 scripts/fabric_provider.py validate ~/Library/Application\ Support/ai.pa
 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
+`--stdio` comes last and takes the rest of the line as the argument array; there is no shell string. A writer
+option after it (`--env`, `--name`, ...) is refused rather than swallowed into argv; write `--stdio -- EXECUTABLE ...`
+when the server itself takes an option of that name. `--env` belongs to a stdio server and is refused with `--url`. 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. An argument that carries a credential is refused
@@ -46,8 +48,12 @@ It refuses, with one sentence that never quotes a value:
 - 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.
+- what the pinned `provider.schema.json` refuses: a URL other than `http://127.0.0.1:<port>/mcp` with a port from 100
+  to 65535, a manifest path that is not an absolute or `~/` path to `fabric-agent.json` (or is a network share, or over
+  1024 characters), a shell-string command, more than 32 arguments or one over 1024 characters, more than 64 env
+  names, a `source.repository` that is not an absolute URI, an `installedAt` that is not an RFC 3339 date-time,
+  unknown fields. The patterns are the schema's, copied (`test_provider.SchemaParityTests` compares them with a
+  contract checkout at the pin when `FABRIC_CONTRACT_NEW` names one).
 
 `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)`,