@passioncode-ai/fabric-agent-adapter 0.3.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.4.2 - 2026-09-29
+
+- Kit: `LoopbackHTTPServer`, a `ThreadingHTTPServer` whose bind asks no resolver.
+  `http.server` calls `socket.getfqdn()` between `bind()` and `listen()`; on a macOS
+  CI runner that held a service's port bound but silent for over 20 seconds. The
+  sample service and the skill's startup order use it, and the skill names the trap.
+- Kit: a garbled pid file (for example a superscript digit) now reads as "no pid"
+  instead of raising `ValueError` while naming the holder of a lock.
+
+## 0.4.1 - 2026-09-29
+
+### Fixed
+
+- `building-fabric-services` could not be loaded by a strict YAML reader: its
+  front-matter `description` was an unquoted plain scalar holding `: `
+  ("fabric-service/0.1 extension: which surface", line 3, column 493), which YAML
+  rejects with "mapping values are not allowed here". Claude Code read it
+  leniently, so the plugin worked, but an agent reading the skill from
+  `~/.agents/skills` could drop it. The description is now a folded block
+  scalar (`>-`) with the exact same text (927 characters).
+- The validator could not see that class of defect: `test/validate.py` now
+  parses every SKILL.md front matter strictly (standard library only) and
+  rejects what a YAML reader rejects in an unquoted value — `: ` or a trailing
+  `:`, ` #` (a comment that silently truncates the value), a leading indicator
+  character, a duplicate key, an unclosed quote, an undeclared multi-line
+  value — with the line and column. `test/test_validate.py` plants each case.
+  `validate.py --frontmatter <SKILL.md ...>` checks installed copies anywhere.
+- The release smoke test looked for `~/.claude/skills`, where the installer has
+  not written since 0.4.0, so it would fail on the first release that ran it.
+  It now checks all three skills in `~/.agents/skills`, that `~/.claude/skills`
+  stays untouched, and that the installed front matter parses strictly.
+- `SKILL-CARD.md` versions and the release smoke paths joined the validator's
+  sync checks.
+
+## 0.4.0 - 2026-09-28
+
+- Add the `building-fabric-services` skill for the `fabric-service/0.1` local
+  service extension (Fabric Agent Contract DEC-0015): surface choice (MCP
+  streamable HTTP, CLI, A2A), token and one-time login, state and cache
+  directories, one copy per machine, launchd, descriptor, well-known document,
+  events feed and notifications.
+- Ship reference kits in Python (`fabric_service.py`) and Node
+  (`fabric-service.mjs`) whose instance locks exclude each other, a complete
+  `sample_service.py`, and `check_service.py`, a live conformance probe that
+  reports PASS, FAIL or NOT_RUN per rule.
+- `creating-fabric-agents` now routes an agent that runs as a service through
+  the new skill.
+- Fix the installer shadowing its own plugin: `npx @passioncode-ai/fabric-agent-adapter`
+  and `install.sh` now install into the agents hub `~/.agents/skills`; a plain
+  copy into `~/.claude/skills` is refused while the plugin is installed, and
+  `--prune-shadow` moves existing shadowing copies aside.
+
 ## 0.3.1 - 2026-08-27
 
 - Fix the executable bit on `bin/fabric-agent-adapter.js` and `install.sh`: the

package/README.md

@@ -1,13 +1,38 @@
+<p align="center">
+  <a href="https://passioncode.ai/">
+    <img src="assets/passioncode-icon-256.png" width="104" height="104" alt="PassionCode.ai passion fruit mark">
+  </a>
+</p>
+
 # Fabric Agent Adapter
 
+> **PassionCode.ai — The agent-agnostic operating system for AI-native teams.**
+
+**From vibe coding to passion coding.** PassionCode.ai moves the control point from
+managing agents one by one to operating Projects. Fabric Agent Adapter is the portable
+on-ramp: it helps an existing repository become a compatible, replaceable Provider
+without moving the Project onto one proprietary agent runtime.
+
 [![npm](https://img.shields.io/npm/v/%40passioncode-ai%2Ffabric-agent-adapter)](https://www.npmjs.com/package/@passioncode-ai/fabric-agent-adapter)
 [![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-MIT-green.svg)](LICENSE)
 
-Private, portable Agent Skill for adapting an existing agent project to the
-[Fabric Agent Contract](https://github.com/passioncode-ai/fabric-agent-contract).
+Private, portable Agent Skills for the
+[Fabric Agent Contract](https://github.com/passioncode-ai/fabric-agent-contract):
+`adapting-projects-to-fabric`, `creating-fabric-agents` and
+`building-fabric-services`.
+
+`building-fabric-services` makes an agent a long-lived local service with a dashboard
+that is always alive, runs as one copy, keeps its state through a reinstall and appears
+in Fabric Dashboards by itself — the `fabric-service/0.1` extension. It ships Python and
+Node reference kits (`scripts/fabric_service.py`, `scripts/fabric-service.mjs`), a
+complete `scripts/sample_service.py`, and `scripts/check_service.py`, a live probe:
+
+```bash
+python3 plugins/fabric-agent-adapter/skills/building-fabric-services/scripts/check_service.py example-agent
+```
 
-It helps an agent author:
+For provider bundles the adapting skill helps an agent author:
 
 - inspect the project's stable integration surfaces without executing it;
 - choose A2A `1.0`, MCP `2026-07-28`, or `fabric-local-runner/0.1` per capability;
@@ -26,7 +51,8 @@ The repository is private; the npm package is public. The npm path needs no GitH
 npm — no GitHub access required:
 
 ```bash
-npx @passioncode-ai/fabric-agent-adapter        # installs both skills into ~/.claude/skills
+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
 ```
 
 Generic Agent Skills clients:
@@ -34,6 +60,7 @@ Generic Agent Skills clients:
 ```bash
 npx skills add passioncode-ai/fabric-agent-adapter --skill adapting-projects-to-fabric
 npx skills add passioncode-ai/fabric-agent-adapter --skill creating-fabric-agents
+npx skills add passioncode-ai/fabric-agent-adapter --skill building-fabric-services
 ```
 
 Claude Code plugin marketplace:
@@ -52,6 +79,12 @@ Adapt this project for Fabric compatibility. Inspect it, choose the profile per
 capability, scaffold the provider bundle, and report every conformance gate.
 ```
 
+Or, for an agent that must keep running with a dashboard:
+
+```text
+Make this agent a local service with an always-on dashboard, following fabric-service/0.1.
+```
+
 Or, for an agent that does not exist yet:
 
 ```text
@@ -86,6 +119,10 @@ claude plugin validate ./plugins/fabric-agent-adapter --strict
 claude plugin validate . --strict
 ```
 
+`test/validate.py` reads every SKILL.md front matter as strictly as a YAML parser does; an
+unquoted value holding `: ` fails it. `python3 test/validate.py --frontmatter <SKILL.md ...>`
+checks copies installed elsewhere, such as `~/.agents/skills/*/SKILL.md`.
+
 ## Contract pin
 
 - version: `0.1.0`
@@ -93,4 +130,3 @@ claude plugin validate . --strict
 
 The contract repository is normative. Updating the pin requires a new adapter release,
 fixture review, and a complete validation run.
-

package/SECURITY.md

@@ -8,3 +8,17 @@ The adapter must not write secret values to manifests, fixtures, probes, logs, o
 arguments. Generated and external provider outputs are untrusted. Live probes must be
 bounded and non-publishing until explicit scoped grants exist in a project binding.
 
+
+## 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
+  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.
+- 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.

package/bin/fabric-agent-adapter.js

@@ -2,13 +2,12 @@
 /*
  * fabric-agent-adapter installer CLI.
  *
- * Installs every skill this plugin ships into ~/.claude/skills/<name>
- * (same layout as install.sh). Idempotent: an existing install is skipped unless
- * --force. Zero dependencies.
- *
- * For other agents (Cursor, Codex, 70+) use:
- *   npx skills add passioncode-ai/fabric-agent-adapter   (needs GitHub access —
- *   the repository is private; the npm package needs none)
+ * Installs every skill this plugin ships into the shared agents hub
+ * ~/.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.
  */
 'use strict';
 
@@ -18,20 +17,25 @@ const os = require('os');
 
 const ROOT = path.resolve(__dirname, '..');
 const REPO = 'passioncode-ai/fabric-agent-adapter';
+const PLUGIN_ID = 'fabric-agent-adapter@fabric-agent-adapter';
 
 function usage() {
   console.log(`fabric-agent-adapter installer
 
 Usage:
   npx @passioncode-ai/fabric-agent-adapter [--force]
-      install every skill this plugin ships into ~/.claude
-      (skip existing unless --force)
+      install every skill into the agents hub ~/.agents/skills
+  npx @passioncode-ai/fabric-agent-adapter --target claude [--force]
+      plain copy into ~/.claude/skills — refused while the plugin is installed
+  npx @passioncode-ai/fabric-agent-adapter --prune-shadow
+      remove plain ~/.claude/skills copies that shadow the installed plugin
   npx @passioncode-ai/fabric-agent-adapter --help
 
-Other install paths:
-  Claude Code plugin:  /plugin marketplace add ${REPO}
-                       /plugin install fabric-agent-adapter@fabric-agent-adapter
-  Any agent (70+):     npx skills add ${REPO}   (private repo — GitHub auth required)`);
+Claude Code (recommended):
+  claude plugin marketplace add ${REPO}
+  claude plugin install ${PLUGIN_ID}
+Every PassionCode.ai skill for every agent at once:
+  npx passioncode@latest update`);
 }
 
 function copyDir(src, dest) {
@@ -44,15 +48,38 @@ function copyDir(src, dest) {
   }
 }
 
-function installOne(label, src, dest, force) {
-  if (fs.existsSync(dest) && !force) {
-    console.log(`skip: ${label} already installed at ${dest} (rerun with --force to overwrite)`);
-    return;
+function pluginInstalled(home) {
+  try {
+    const data = JSON.parse(fs.readFileSync(path.join(home, '.claude/plugins/installed_plugins.json'), 'utf8'));
+    const records = (data.plugins || {})[PLUGIN_ID] || [];
+    return records.some((r) => r.installPath && fs.existsSync(path.join(r.installPath, 'skills')));
+  } catch {
+    return false;
+  }
+}
+
+function skillNames() {
+  const skillRoot = path.join(ROOT, 'plugins/fabric-agent-adapter/skills');
+  if (!fs.existsSync(skillRoot)) return { skillRoot, names: [] };
+  // Iterate rather than name one skill: a skill added to the plugin must not
+  // require an installer change to reach anybody.
+  const names = fs.readdirSync(skillRoot, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  return { skillRoot, names };
+}
+
+function pruneShadows(home, names) {
+  let removed = 0;
+  for (const name of names) {
+    const shadow = path.join(home, '.claude', 'skills', name);
+    let info;
+    try { info = fs.lstatSync(shadow); } catch { continue; }
+    const backup = path.join(home, '.claude', 'skills-shadow-backup', `${name}-${Date.now()}`);
+    fs.mkdirSync(path.dirname(backup), { recursive: true });
+    fs.renameSync(shadow, backup);
+    console.log(`Removed shadowing ${info.isSymbolicLink() ? 'link' : 'copy'} ${shadow} (kept at ${backup})`);
+    removed += 1;
   }
-  fs.rmSync(dest, { recursive: true, force: true });
-  fs.mkdirSync(path.dirname(dest), { recursive: true });
-  copyDir(src, dest);
-  console.log(`Installed ${label} -> ${dest}`);
+  if (!removed) console.log('No shadowing copies found.');
 }
 
 function main(argv) {
@@ -62,39 +89,56 @@ function main(argv) {
     return 0;
   }
   const force = args.includes('--force');
-  const unknown = args.filter((a) => a !== '--force');
-  if (unknown.length) {
-    console.error(`unknown argument(s): ${unknown.join(' ')}`);
+  const prune = args.includes('--prune-shadow');
+  let target = 'agents';
+  const known = new Set(['--force', '--prune-shadow']);
+  const unknown = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--target') {
+      target = args[i + 1];
+      i += 1;
+    } else if (!known.has(args[i])) unknown.push(args[i]);
+  }
+  if (unknown.length || !['agents', 'claude'].includes(target)) {
+    console.error(`unknown argument(s): ${unknown.concat(['agents', 'claude'].includes(target) ? [] : [`--target ${target}`]).join(' ')}`);
     usage();
     return 2;
   }
 
-  const skillRoot = path.join(ROOT, 'plugins/fabric-agent-adapter/skills');
-  if (!fs.existsSync(skillRoot)) {
-    console.error(`error: skill sources missing at ${skillRoot} — corrupted package?`);
+  const { skillRoot, names } = skillNames();
+  if (!names.length) {
+    console.error(`error: no skills found under ${skillRoot} — corrupted package?`);
     return 1;
   }
+  const home = os.homedir();
+  const hasPlugin = pluginInstalled(home);
 
-  // Iterate rather than name one skill: a skill added to the plugin must not
-  // require an installer change to reach anybody.
-  const names = fs
-    .readdirSync(skillRoot, { withFileTypes: true })
-    .filter((e) => e.isDirectory())
-    .map((e) => e.name)
-    .sort();
-  if (!names.length) {
-    console.error(`error: no skills found under ${skillRoot} — corrupted package?`);
+  if (prune) {
+    if (!hasPlugin) {
+      console.error(`error: the ${PLUGIN_ID} plugin is not installed, so a copy in ~/.claude/skills is not a shadow — nothing removed.`);
+      return 1;
+    }
+    pruneShadows(home, names);
+    return 0;
+  }
+  if (target === 'claude' && hasPlugin) {
+    console.error(`error: the ${PLUGIN_ID} plugin is installed; a plain copy in ~/.claude/skills would shadow it. Update the plugin instead:\n  claude plugin marketplace update fabric-agent-adapter && claude plugin update ${PLUGIN_ID}`);
     return 1;
   }
 
-  const home = os.homedir();
+  const destRoot = target === 'claude' ? path.join(home, '.claude', 'skills') : path.join(home, '.agents', 'skills');
   for (const name of names) {
-    installOne(
-      `${name} skill`,
-      path.join(skillRoot, name),
-      path.join(home, '.claude', 'skills', name),
-      force
-    );
+    const dest = path.join(destRoot, name);
+    if (fs.existsSync(dest) && !force) {
+      console.log(`skip: ${name} already installed at ${dest} (rerun with --force to overwrite)`);
+      continue;
+    }
+    fs.rmSync(dest, { recursive: true, force: true });
+    copyDir(path.join(skillRoot, name), dest);
+    console.log(`Installed ${name} -> ${dest}`);
+  }
+  if (target === 'agents' && !hasPlugin) {
+    console.log(`Claude Code reads plugins, not the hub:\n  claude plugin marketplace add ${REPO} && claude plugin install ${PLUGIN_ID}`);
   }
   console.log('Restart your agent — skills load at session start.');
   return 0;

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.3.1",
-  "description": "Create new Fabric-compatible agents and adapt existing projects to the Fabric Agent Contract — evidence-backed MCP, A2A, or local-runner provider bundles. This package is the installer CLI.",
+  "version": "0.4.2",
+  "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"
+    "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test test/"
   },
   "bin": {
     "fabric-agent-adapter": "bin/fabric-agent-adapter.js"
@@ -17,7 +17,9 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
-    "SECURITY.md"
+    "SECURITY.md",
+    "!**/__pycache__/**",
+    "!**/*.pyc"
   ],
   "repository": "github:passioncode-ai/fabric-agent-adapter",
   "homepage": "https://github.com/passioncode-ai/fabric-agent-adapter",
@@ -39,6 +41,9 @@
     "provider",
     "conformance",
     "claude-code",
-    "skill"
+    "skill",
+    "local-service",
+    "dashboard",
+    "launchd"
   ]
 }

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

@@ -2,8 +2,8 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
-  "description": "Create new Fabric-compatible agents and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.3.1",
+  "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
+  "version": "0.4.2",
   "author": {
     "name": "passioncode-ai",
     "url": "https://github.com/passioncode-ai"
@@ -22,4 +22,3 @@
     "conformance"
   ]
 }
-

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

@@ -5,7 +5,7 @@ license: MIT
 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.3.1"
+  version: "0.4.2"
   contract-version: "0.1.0"
   contract-commit: "20a818e648a4c09a60df0126d11626922e8b9094"
 ---

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

@@ -0,0 +1,240 @@
+---
+name: building-fabric-services
+description: >-
+  Use when building or running an agent as a long-lived local service with a dashboard on the
+  operator's Mac — «сделай агенту дашборд», «локальный сервис агента», «дашборд должен всегда
+  работать и не плодить копии», «где агенту хранить настройки», «подключи агента к Fabric
+  Dashboards», "make this agent a local service", "always-on dashboard", "fabric-service
+  protocol", "add the well-known endpoint", "migrate a service to fabric-service". Covers the
+  fabric-service/0.1 extension: which surface to expose (MCP streamable HTTP, CLI, A2A), the token
+  and one-time login, where state, config, logs and cache live, one copy per machine, launchd, the
+  descriptor, the well-known document, the events feed and notifications; ships Python and Node
+  reference kits and a live conformance probe. NOT for a one-off script or cron job, a hosted
+  SaaS, the provider manifest itself (adapting-projects-to-fabric), or building Fabric Dashboards.
+license: MIT
+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). No network or package install; the contract checkout is optional.
+metadata:
+  author: passioncode-ai
+  version: "0.4.2"
+  contract-version: "0.1.0"
+  extension: "fabric-service/0.1"
+  extension-commit: "a5a27092ba0dcc5facfbeae8b359146dfb403e9a"
+---
+
+# Building Fabric services
+
+A **service** is an agent that keeps running on the operator's computer: it holds
+state, answers other agents, and shows a dashboard. This skill makes one that is
+always alive, comes back after a restart, never runs twice, keeps its state through a
+reinstall, and appears in Fabric Dashboards by itself — the `fabric-service/0.1`
+extension of the Fabric Agent Contract (DEC-0015).
+
+Every rule below exists because a real service on this estate broke it. Treat them as
+non-negotiable; the kit implements them so you call a function instead of
+re-deriving a rule.
+
+## Boundary
+
+Use it to create a service, to bring an existing local server under the protocol, or
+to review one. Do not use it for:
+
+- a script, a cron job or a one-shot CLI — nothing stays running, so there is nothing
+  to supervise; a launchd `StartInterval` job needs no descriptor;
+- a hosted SaaS — the protocol is loopback-only by design;
+- the provider manifest and admission bundle — that is `adapting-projects-to-fabric`
+  (a service that is also a provider does both);
+- the Fabric Dashboards app itself.
+
+## Step 0 — is it a service?
+
+It is a service when at least one is true: other agents call it while the operator is
+away; it runs jobs longer than one request; it owns a store other tools read; the
+operator watches it on a page. Otherwise build a CLI and stop here.
+
+Answer before writing code, and record the answers in the project README:
+
+| Question | Answer shape |
+|---|---|
+| `id` | `^[a-z][a-z0-9-]{1,62}$`, stable forever (it names the data directory) |
+| Port | one number; run the claim check below before choosing it |
+| Who calls it | the named agents or people, and through which surface (Step 1) |
+| What it stores | the store, where it lives (Step 2, rule 5), and what survives uninstall |
+| What it tells the operator | the events worth a notification (Step 5) |
+
+## Step 1 — choose the surfaces
+
+| Caller | Surface | Why |
+|---|---|---|
+| Another agent on this machine | MCP `2026-07-28`, `streamable-http`, at `/mcp` on the service origin, token in a header | one process serves every session; stdio-per-session once left twenty stray servers on this machine |
+| The operator or a script | a CLI: `<tool> service status\|start\|stop\|restart`, `<tool> dashboard`, `<tool> doctor --json` | every verb delegates to launchd and the well-known document, never to its own process table |
+| A remote agent | A2A `1.0` over HTTPS, or MCP behind an authenticated gateway | loopback reachability is not authorization |
+| The dashboard page | same-origin REST under `/api`, session cookie plus a custom request header | the CSRF defence all four existing dashboards use |
+
+Read [the surfaces and auth reference](references/surfaces-and-auth.md) when wiring
+MCP registration into a client config, the login flow or the CSRF header.
+
+## Step 2 — the non-negotiables
+
+1. **Loopback only.** Bind `127.0.0.1`. Refuse any `Host` other than
+   `127.0.0.1:<port>`, `localhost:<port>`, `[::1]:<port>`; refuse a foreign `Origin` and
+   `Sec-Fetch-Site: cross-site` — on every path, the well-known one included.
+   *(A throwaway `python -m http.server` bound to every interface served a source tree to the local network.)*
+2. **One copy, locked before any side effect.** Take the exclusive lock on
+   `<data>/service.lock` first — before resuming jobs, starting a scheduler, migrating
+   a store or even creating a token. Held → print one sentence naming the holder's pid
+   and exit **75**. Binding the port is not a lock. *(A second copy re-queued the first
+   copy's running jobs in its startup hook, before its bind failed.)*
+3. **launchd is the only supervisor.** `RunAtLoad` true, `KeepAlive` true,
+   `ThrottleInterval` 10, `ExitTimeOut` above your drain time. Never start yourself
+   from a CLI with `nohup` or `&`; never let a host spawn you. *(`KeepAlive
+   {SuccessfulExit:false}` left a cleanly exited service down; hand-started copies
+   raced launchd's.)*
+4. **Build identity.** The well-known document carries the git commit or a package
+   digest and the process start time. *(A service ran on stale code after an edit and
+   burned budget; nothing showed which build was answering.)*
+5. **State outside code.** Data and config in `~/Library/Application Support/<id>/`,
+   logs in `~/Library/Logs/<id>/`, cache in `~/Library/Caches/<id>/`; secrets in a 0600
+   file. Never inside the service's own code checkout or a release directory; a
+   repository that versions the data itself is a store and is fine — declare
+   `source.repository` so the probe can tell them apart. *(Deleting a checkout left a
+   plist launchd retried every 10 s, and the data went with it.)*
+6. **Tokens stay in files and headers.** Mode 0600, owner-checked, never a symlink;
+   never in a query string, an argument vector or a plist. The dashboard gets a
+   one-time login code, never the token.
+7. **`degraded` is always present.** An empty list asserts full health; `ready` with a
+   non-empty list is a lie the kit corrects to `degraded`.
+8. **Atomic writes.** Temporary file, fsync, rename — for the store's side files, the
+   descriptor and the token.
+
+## Step 3 — build it with the kit
+
+Copy the kit into the service (each is one self-contained file): Python
+[`scripts/fabric_service.py`](scripts/fabric_service.py), Node
+[`scripts/fabric-service.mjs`](scripts/fabric-service.mjs). Both share file formats, and
+their locks exclude each other. The complete worked example is
+[`scripts/sample_service.py`](scripts/sample_service.py) — read it before writing a
+handler.
+
+Startup order is the part that goes wrong; keep it exactly:
+
+```python
+import fabric_service as fs
+
+dirs = fs.service_dirs("example-agent")
+lock = fs.hold_single_instance(dirs["data"])        # 1. lock — exits 75 if held
+token = fs.ensure_token(dirs["data"] / "service.token")  # 2. only now touch state
+log = fs.JsonlEventLog(dirs["data"] / "events.jsonl")    #    (or a view over your own log)
+codes = fs.LoginCodes(dirs["data"] / "auth")
+resume_jobs()                                        # 3. side effects after the lock
+fs.LoopbackHTTPServer(("127.0.0.1", port), Handler)  # 4. bind loopback, no resolver
+```
+
+Node: `const lock = await holdSingleInstance(dirs.data)` first, then the same order.
+
+On every request call `check_request(port, host, origin, sec_fetch_site)` and answer
+403 with its sentence when it returns one. Serve the four protocol routes:
+
+| Route | Auth | Kit |
+|---|---|---|
+| `GET /.well-known/fabric-service` | none, guard still applies | `build_well_known(...)` — from memory, under 100 ms |
+| `GET /fabric/v1/events?after=&limit=` | service token | `events_page(fetch, after, parse_limit(limit))` |
+| `POST /fabric/v1/login-code` | service token | `LoginCodes.issue()` |
+| `GET /fabric/v1/login?code=` | the code | `LoginCodes.redeem(code)` → `Set-Cookie: session_cookie_header(...)`, 302 to the dashboard |
+
+`SIGTERM` drains in-flight work within `ExitTimeOut`, then exits; interrupted work
+resumes on the next start.
+
+## Step 4 — install it
+
+The installer, not the service, owns the plist and the descriptor. Sequence:
+
+1. `write_descriptor(descriptor)` — refuses a port or `id.instance` another descriptor
+   claims. A preview or branch copy is a second **instance**, never a second id.
+2. `launchd_plist(...)` then `launchd_install(...)` — writes and lints the plist,
+   `bootout` and waits for the unload, `bootstrap` with retries on the transient I/O
+   error, then polls the well-known document until it answers with **this** identity.
+3. Uninstall: `launchd_uninstall`, `remove_descriptor`; keep data unless the operator
+   asks to purge.
+
+Code runs from an immutable release directory; an upgrade writes a new release,
+rewrites the plist and restarts. Read [the lifecycle reference](references/lifecycle.md)
+for the plist fields, the release layout, log rotation and the Linux case.
+
+## Step 5 — the dashboard and the events
+
+The dashboard is a same-origin page: no inline script, strict CSP, polling that pauses
+while the operator types or a dialog is open, one panel's failure never blanks the
+others, and every error is a sentence with the next action. Read
+[the dashboard reference](references/dashboard.md) before building the page.
+
+The events feed is a **view over the log you already keep** — a jobs table, a JSONL
+journal — not a second store. Each event is one sentence a person reads; set
+`notify: true` only for what the operator must act on or would want to hear about
+unprompted, with a `link` to the page that resolves it. Read
+[the events reference](references/events-and-notifications.md) for mapping an existing
+log, retention and notification policy.
+
+## Step 6 — verify
+
+Run the probe against the live service — it reads the descriptor, then checks every
+rule it can reach and says which it could not:
+
+```bash
+python3 <skill-dir>/scripts/check_service.py <id>[.<instance>]
+```
+
+It reports `PASS`, `FAIL` or `NOT_RUN` per rule (descriptor, port claim, well-known
+shape, identity, latency, Host/Origin/cross-site guards, loopback bind, token file,
+events auth and shape, single-use login, state outside code, instance lock, plist,
+launchd pid equals answering pid) and exits 1 on any `FAIL`. A `NOT_RUN` is not a pass —
+name it in the report.
+
+Then prove the lock: start a second copy by hand against the same data directory; it
+must exit 75 while the first keeps serving. Prove recovery: `kill -9` the launchd pid;
+the well-known document must answer again with a new pid within about 15 seconds.
+
+## Migrating an existing service
+
+Read [the migration reference](references/migrating-a-service.md) — the order of
+changes that keeps the service answering throughout, and what each existing service on
+this estate needs.
+
+## When something is missing
+
+- **Not macOS / no launchd:** declare `lifecycle.manager: "none"`; hosts show the
+  service read-only. Keep every other rule.
+- **No Python:** use the Node kit; run the probe from any machine that has Python and
+  can reach the port, or mark the probe `NOT_RUN` with the reason.
+- **Neither kit fits the framework:** implement the four routes and the lock by hand
+  against [the protocol reference](references/protocol.md); the probe is the judge.
+- **No contract checkout:** the protocol reference is pinned to the extension commit
+  in this skill's metadata; do not reconstruct fields from memory.
+- **Fabric Dashboards not installed:** nothing changes — the service is complete
+  without a host; the descriptor waits for one.
+
+## Gotchas
+
+- `lsof` shows `*:<port>` or `0.0.0.0` → the bind is wrong even if the Host check works.
+- A health probe that only checks HTTP 200 accepts any program on the port. Compare
+  `service.id` and `service.instance` — two services here once defaulted to ports
+  another service already held.
+- `launchctl bootstrap` right after `bootout` fails with I/O error 5 until the unload
+  finishes; wait, then retry.
+- Under launchd `PATH` is bare. Pin the interpreter by absolute path; set `PATH`
+  explicitly in the plist; never copy the whole shell environment into it.
+- A plist pointing at a worktree or a checkout breaks the day it moves. Point it at a
+  release.
+- `http.server.HTTPServer` asks the resolver for its FQDN between `bind()` and
+  `listen()`. With a slow resolver (a macOS CI runner, a Mac offline) the port is bound
+  but silent: connects time out instead of being refused. Use `fs.LoopbackHTTPServer`.
+- `logging.basicConfig` called twice: the second call is a no-op, so a server's own
+  log file stays empty. Configure logging once, in the entry point.
+- Hand-made `.plist.bak` files in `~/Library/LaunchAgents` are never cleaned up; keep
+  backups elsewhere.
+
+## Completion format
+
+Report: the `id`, port and surfaces with the Step 0 answers; files created or changed;
+the probe table verbatim with every `NOT_RUN` explained; the lock and kill-9 results
+with pids; and the one next command. Never call a service conformant while the probe
+reports a `FAIL`.