@passioncode-ai/fabric-agent-adapter 0.78.0 → 0.80.2

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

@@ -133,12 +133,20 @@ def check(data):
     return {'ok': True, 'kind': kind}
 
 
+def read_input(limit=65536):
+    # The handoff's bytes, decoded as UTF-8 with a byte order mark dropped: Windows before Python 3.15 decodes a text
+    # stdin with its code page, which misreads a Cyrillic handoff (FAA-210). A stream without bytes is read as text.
+    stream = getattr(sys.stdin, 'buffer', None)
+    raw = stream.read(limit + 1) if stream is not None else sys.stdin.read(limit + 1)
+    require(len(raw) <= limit, 'input_too_large')
+    return raw.decode('utf-8-sig') if isinstance(raw, bytes) else raw.lstrip('\ufeff')
+
+
 def main():
     try:
-        raw = sys.stdin.read(65537)
-        require(len(raw) <= 65536, 'input_too_large')
-        result = check(json.loads(raw))
-    except (ValueError, TypeError, KeyError, AttributeError):
+        result = check(json.loads(read_input()))
+    # RecursionError: Python 3.9 to 3.13 raise it on a deeply nested document under the cap
+    except (ValueError, TypeError, KeyError, AttributeError, RecursionError):
         # Fixed reasons only: never echo a submitted URL, token or JSON blob.
         result = {'ok': False, 'reason': 'dashboard_handoff_refused'}
     print(json.dumps(result))

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

@@ -17,6 +17,7 @@ itself takes an option of the same name. --env is for a stdio server only and is
 
 Normative source: fabric-agent-contract docs/specification/provider.md (DEC-0016, rulings DEC-0017).
 """
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 # #region provider-writer — docs: plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/provider-entry.md#the-writer
 
@@ -61,8 +62,12 @@ _URL = re.compile(URL_PATTERN)
 _MANIFEST = re.compile(MANIFEST_PATTERN[:-1] + r"\Z")
 # The manifest's name after a backslash: valid since DEC-0145, but no writer emits it until every reader accepts it.
 _MANIFEST_AFTER_BACKSLASH = re.compile(r"\\fabric-agent\.json\Z")
-# format: uri (RFC 3986 absolute URI): a scheme, a colon, then no whitespace or control character.
-_URI = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:[^\s\x00-\x1f\x7f]+\Z")
+# format: uri (RFC 3986 absolute URI) as ajv-formats reads it: RFC 3986 characters only (unreserved, reserved and %HH),
+# the class the service kit's descriptor check uses (fabric_descriptor `_SOURCE_URI`, 0.49.3); a byte-order mark, a
+# zero-width space, a non-ASCII path or an IDN host is refused (FAA-127).
+_URI = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:(?:[A-Za-z0-9._~:/?#@!$&'()*+,;=-]|%[0-9A-Fa-f]{2})+\Z")
+# Brackets belong to an IP-literal host only (RFC 3986 3.2.2); the literal is set aside before the character check.
+_IP_LITERAL = re.compile(r"^([A-Za-z][A-Za-z0-9+.-]*://(?:[^/?#@\[\]]*@)?)\[[0-9A-Fa-f:.vV]+\]")
 # format: date-time (RFC 3339).
 _TIMESTAMP = re.compile(r"^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt][0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})\Z")
 FIELDS = {"protocol", "id", "providerId", "name", "summary", "manifest", "run", "source", "installedAt", "installedBy", "extensions"}
@@ -145,11 +150,14 @@ def validate_provider_entry(entry: Any) -> List[str]:
         source = entry["source"]
         if not isinstance(source, dict) or not set(source) <= {"repository"}:
             problems.append("source is {repository?}")
+        elif "repository" in source and isinstance(source["repository"], str) and (
+                _URI_PASSWORD.match(source["repository"]) or _secrets.repository_credential(source["repository"])):
+            # FAA-120, as the service kit: a repository is named, never reached with a credential in its URI. Said
+            # before the character check, so a password beside a character the URI class refuses (a backslash, as
+            # git reads one) is still named a credential (FAA-127).
+            problems.append("source.repository carries no password or credential: it names the repository")
         elif "repository" in source and not _is_uri(source["repository"]):
             problems.append("source.repository is an absolute URI")
-        elif "repository" in source and (_URI_PASSWORD.match(source["repository"]) or _secrets.repository_credential(source["repository"])):
-            # FAA-120, as the service kit: a repository is named, never reached with a credential in its URI.
-            problems.append("source.repository carries no password or credential: it names the repository")
     if not isinstance(entry["installedAt"], str) or not _TIMESTAMP.fullmatch(entry["installedAt"]):
         problems.append("installedAt is an RFC 3339 date-time")
     if not isinstance(entry["installedBy"], str) or not 1 <= len(entry["installedBy"]) <= 200:
@@ -161,7 +169,7 @@ def validate_provider_entry(entry: Any) -> List[str]:
 
 
 def _is_uri(value: Any) -> bool:
-    return isinstance(value, str) and bool(_URI.fullmatch(value))
+    return isinstance(value, str) and bool(_URI.fullmatch(_IP_LITERAL.sub(r"\1h", value, count=1)))
 
 
 def _run_problems(run: Any) -> List[str]:
@@ -255,7 +263,7 @@ def write_provider_entry(entry: Dict[str, Any], directory: Optional[Path] = None
         # re-pins (CT-192), so the writer does not emit it yet.
         raise ProviderError("The manifest's name follows a backslash, which a reader that has not re-pinned to DEC-0145 refuses (CT-192). "
                             "Write the path with / before the name: ~/.../fabric-agent.json, which every Fabric release reads, or "
-                            "C:/.../fabric-agent.json, which Fabric reads only after v0.3.15 (its repin, CO-479).")
+                            "C:/.../fabric-agent.json, which Fabric reads only from v0.3.16 (its repin, CO-479).")
     problems = manifest_problems(entry)
     if problems:
         raise ProviderError("Provider entry is invalid: %s." % "; ".join(problems))
@@ -285,6 +293,13 @@ def _now() -> str:
     return dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 
 
+
+def entry_stem(path: str) -> str:
+    """CT-193 (FAC-SEM-014): the stem registry-rules.ts reads, `file.replace(/^.*[\\/]/, "").replace(/\\.json$/, "")`,
+    with ECMAScript's `.` (no line break: \\n, \\r, U+2028, U+2029) and `$` (the string's end) (FAA-189)."""
+    return re.sub(r"\.json\Z", "", re.sub(r"\A[^\n\r\u2028\u2029]*[\\/]", "", path, count=1))
+
+
 def main(argv: Optional[List[str]] = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -320,7 +335,7 @@ def main(argv: Optional[List[str]] = None) -> int:
             entry = json.loads(args.path.read_text(encoding="utf-8"))
             problems = validate_provider_entry(entry)
             # CT-193 (FAC-SEM-014): the stem is what follows the last / or \ and loses .json, on every platform.
-            stem = re.sub(r"\.json\Z", "", re.sub(r"^.*[\\/]", "", str(args.path), flags=re.S))
+            stem = entry_stem(str(args.path))
             if isinstance(entry, dict) and entry.get("id") != stem:
                 problems.append("the file name %s is not <id>.json for %s (FAC-SEM-014)" % (args.path.name, entry.get("id")))
             if not problems:

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

@@ -6,6 +6,7 @@ only. The dashboard kit's fabric-button.js carries its own copy of the name and
 
 It reads as the contract's ECMAScript does (FAA-136): ECMAScript's whitespace (Python's `\\s` also takes U+0085 and
 U+001C to U+001F, and not U+FEFF), `.` stopping at every line terminator, ASCII case folding, an ASCII word boundary."""
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 from __future__ import annotations
 
@@ -142,7 +143,7 @@ def _percent_encode(text: str, also: str) -> str:
     return "".join(out)
 
 
-def _url_parts(value: str) -> Tuple[str, str, str]:
+def url_parts(value: str) -> Tuple[str, str, str]:
     """The password, query and fragment of an absolute URL as WHATWG URL parsing splits them, read by hand: urlsplit
     refuses a `[` or `]` outside an IPv6 host (`<https>://u:p[w@h/`), where `new URL` reads the password (0.56.0 unit
     r7). The fragment starts at the first `#`, the query at the first `?` before it. A special scheme's authority starts
@@ -166,6 +167,9 @@ def _url_parts(value: str) -> Tuple[str, str, str]:
             _percent_encode(fragment, "`"))
 
 
+_url_parts = url_parts  # the name before FAA-250, kept for code that reached it
+
+
 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
@@ -177,7 +181,7 @@ def secret_url(value: str) -> bool:
     value = re.sub(r"[\t\n\r]", "", value.strip(_C0_OR_SPACE))
     if not _SCHEME.match(value):
         return False  # not an absolute URL (WHATWG URL parsing refuses it)
-    password, query, fragment = _url_parts(value)
+    password, query, fragment = url_parts(value)
     if password:
         return True
     for part in (query, fragment):

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

@@ -45,6 +45,7 @@ is refused: it would travel with the source. The summary says whether Git chose
 Under a locale whose file-system encoding is not UTF-8 the check restarts itself in Python's UTF-8 mode, so a name,
 an argument and a file are read in one encoding. Standard library only.
 """
+# Example URLs write their scheme in angle brackets: read `<https>` as `https` (FAA-212).
 
 # #region source-check — docs: plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/source-and-instance.md#the-check
 
@@ -200,7 +201,7 @@ def _url_secret(url: str, depth: int = 0) -> bool:
     url = url.rstrip(".,;)]}")
     if not _secrets._SCHEME.match(url):
         return False
-    password, query, fragment = _secrets._url_parts(url)
+    password, query, fragment = _secrets.url_parts(url)
     # what says it is synthetic is the value, never the host or the path (`examples.blob.core.windows.net`)
     if len(password) >= 8 and re.search(r"[0-9]", password) and re.search(r"[A-Za-z]", password) and _real(unquote(password)):
         return True

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

@@ -9,7 +9,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits (Node.js 22+ for a Linux service's instance lock); the probe needs Python 3.9+. launchd steps are macOS-only; Linux services install a systemd user unit and Windows ones a per-user Scheduled Task with the kits' writers. 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.78.0"
+  version: "0.80.2"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "18f8d48762edc5bfb1433657cbfe1c16196df1a6"
@@ -168,7 +168,9 @@ Calling out: [the connectors reference](references/connectors.md) (`fabric_http`
 deadline, safe retries and a size cap; `fabric_openrouter` with the agent's own key, a
 spend ceiling before every attempt, receipts and a fallback). The draft-and-check step of a
 support agent on the kit: [`recipes/support-agent/`](recipes/support-agent/README.md); the whole agent:
-creating-fabric-agents' `references/agents-that-answer-people.md`.
+creating-fabric-agents' `references/agents-that-answer-people.md`. A service that is only a dashboard:
+[`recipes/dashboard-only/`](recipes/dashboard-only/README.md); a door that hands a key on sealed:
+[`recipes/key-delivery-door/`](recipes/key-delivery-door/README.md).
 
 Startup order is the part that goes wrong; keep it exactly:
 

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-button.js

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.5 · Fabric's button (Fabric Agent Contract DEC-0040, FB-1…FB-8, FL-1…FL-6)
+/* fabric-dashboard-kit@1.1.6 · Fabric's button (Fabric Agent Contract DEC-0040, FB-1…FB-8, FL-1…FL-6)
    Load it same-origin, after fabric-dashboard.css, with the service it opens Fabric on:
      <script src="fabric-button.js" defer data-service="example-agent.default" data-service-name="Example Agent"
              data-project="project-a" data-project-name="Project A"></script>
@@ -11,7 +11,7 @@
 (function (root) {
   'use strict';
 
-  var VERSION = '1.1.5';
+  var VERSION = '1.1.6';
   var COOKIE = 'fabric_button';
   var GET_FABRIC = 'https://passioncode.ai/fabric';
   var ABSENT_AFTER_MS = 1500;
@@ -69,7 +69,10 @@
       if (piece === '') return;
       var at = piece.indexOf('=');
       var name = firstKey(at < 0 ? piece : piece.slice(0, at));
-      values.set(name, (values.get(name) || []).concat(at < 0 ? '' : decodeKeepingPlus(piece.slice(at + 1))));
+      var value = at < 0 ? '' : decodeKeepingPlus(piece.slice(at + 1));
+      var list = values.get(name);
+      if (list) list.push(value); // appended in place, as the contract's secret-shape.ts does (FAA-245)
+      else values.set(name, [value]);
     });
     return values;
   }

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-dashboard.css

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.5 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
+/* fabric-dashboard-kit@1.1.6 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
    A Fabric service dashboard shown inside a host pane: usable from 360 CSS px up, navigation always
    reachable, wide content in its own scroll box, one vertical scroller, appearance from the host.
    Copy this file next to fabric-dashboard.js; do not edit it in place. Put the page's own rules in

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/fabric-dashboard.js

@@ -1,4 +1,4 @@
-/* fabric-dashboard-kit@1.1.5 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
+/* fabric-dashboard-kit@1.1.6 · fabric-dashboard/0.1 (Fabric Agent Contract DEC-0036)
    Load it same-origin with <script src="fabric-dashboard.js" defer></script>: no inline script, no
    eval, nothing from a CDN. It applies the host's appearance (ED-6, ED-8), folds navigation that
    does not fit into a More menu (ED-3), makes wide boxes keyboard-reachable (ED-4) and keeps
@@ -8,7 +8,7 @@
   'use strict';
 
   var KIT = 'fabric-dashboard-kit';
-  var VERSION = '1.1.5';
+  var VERSION = '1.1.6';
   /* fabric-dashboard-kit:theme-ids:begin */
   var THEMES = ['graphite', 'fabric', 'paper', 'forest', 'ocean', 'ember', 'contrast'];
 /* fabric-dashboard-kit:theme-ids:end */
@@ -148,6 +148,20 @@
     root.addEventListener('focus', applyAppearance);
   }
 
+  /* ---- resize observers write in the next frame (since 1.1.6) ----
+     A ResizeObserver callback that changes the size of what it watches, or of an ancestor, makes WebKit raise
+     "ResizeObserver loop completed with undelivered notifications". So a callback only schedules the work for the next
+     animation frame, cancelling one already scheduled, and the work itself skips a size it has already laid out. */
+  function nextFrame(work) {
+    var pending = null;
+    var raf = root.requestAnimationFrame;
+    return function () {
+      if (typeof raf !== 'function') { work(); return; }
+      if (pending !== null) root.cancelAnimationFrame(pending);
+      pending = raf.call(root, function () { pending = null; work(); });
+    };
+  }
+
   /* ---- navigation: fold what does not fit into More (ED-3) ---- */
   function foldNav(nav) {
     if (typeof nav.fdRefresh === 'function') { nav.fdRefresh(); return; } // folded already: refit, no second observers
@@ -212,8 +226,16 @@
       }
     }
     layout();
-    if (typeof root.ResizeObserver === 'function') new root.ResizeObserver(function () { layout(); }).observe(nav);
-    else root.addEventListener('resize', layout);
+    // The fit depends on the nav's width only: a callback for a height the fold itself changed lays nothing out.
+    var laidOutWidth = null;
+    var refit = nextFrame(function () {
+      var width = nav.clientWidth;
+      if (width === laidOutWidth) return;
+      laidOutWidth = width;
+      layout();
+    });
+    if (typeof root.ResizeObserver === 'function') new root.ResizeObserver(refit).observe(nav);
+    else root.addEventListener('resize', refit);
     // A page that moves aria-current (its route changed) gets a fresh summary and fit, without telling the kit.
     if (typeof root.MutationObserver === 'function') {
       new root.MutationObserver(layout).observe(nav, { subtree: true, attributes: true, attributeFilter: ['aria-current'] });
@@ -255,12 +277,16 @@
       var header = chrome.querySelector('.fd-header');
       var lift = 0;
       if (height > limit && header) lift = Math.min(Math.ceil(header.getBoundingClientRect().height), height);
-      html.style.setProperty('--fd-chrome-top', lift ? -lift + 'px' : '0px');
-      html.style.setProperty('--fd-chrome-h', Math.max(0, height - lift) + 'px');
+      var top = lift ? -lift + 'px' : '0px';
+      var pinned = Math.max(0, height - lift) + 'px';
+      // An unchanged value is not written again: a write restyles the page and can wake the observer once more.
+      if (html.style.getPropertyValue('--fd-chrome-top') !== top) html.style.setProperty('--fd-chrome-top', top);
+      if (html.style.getPropertyValue('--fd-chrome-h') !== pinned) html.style.setProperty('--fd-chrome-h', pinned);
     }
     set();
-    if (typeof root.ResizeObserver === 'function') new root.ResizeObserver(set).observe(chrome);
-    root.addEventListener('resize', set);
+    var reset = nextFrame(set);
+    if (typeof root.ResizeObserver === 'function') new root.ResizeObserver(reset).observe(chrome);
+    root.addEventListener('resize', reset);
   }
 
   function init() {

package/plugins/fabric-agent-adapter/skills/building-fabric-services/assets/dashboard-kit/kit.json

@@ -1,6 +1,6 @@
 {
   "name": "fabric-dashboard-kit",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "profile": "fabric-dashboard/0.1",
   "decision": "DEC-0036",
   "declarationKey": "https://fabric.passioncode.ai/agent-contract/extensions/dashboard/0.1",
@@ -15,9 +15,9 @@
     "contrast"
   ],
   "files": {
-    "fabric-dashboard.css": "cc7a96fa2c5eeb03d113e7a543ed88d43ce78c2808c411de199ea0fc6d55b957",
-    "fabric-dashboard.js": "5df01193c590a1d8aa82a521954902fecf2d7f655df482165f90d7291b00087f",
-    "fabric-button.js": "e945b3252f9a246826d06dbe7bd4be66e82d539a33728c3d3043fd61d4cbd681",
+    "fabric-dashboard.css": "7a90bbe1f1a2170df5dac0f596a3f302167bef9a7243457bb21dd0eb34f4d359",
+    "fabric-dashboard.js": "146ec9a0fd50af2df3245c02ec7dfba75b7d4e8cb5476fedb5ef727869fef1cc",
+    "fabric-button.js": "60c2b6d44571213e0237c29a94a4cf220f9de3efcfa697ac6a33777d1ad25fd6",
     "themes.json": "511839f1a1a83eb37fadfd132791474497d5c28c5091700b9aa31ad076e359b5"
   },
   "history": {
@@ -54,6 +54,11 @@
       "fabric-dashboard.css": "cc7a96fa2c5eeb03d113e7a543ed88d43ce78c2808c411de199ea0fc6d55b957",
       "fabric-dashboard.js": "5df01193c590a1d8aa82a521954902fecf2d7f655df482165f90d7291b00087f",
       "fabric-button.js": "e945b3252f9a246826d06dbe7bd4be66e82d539a33728c3d3043fd61d4cbd681"
+    },
+    "1.1.6": {
+      "fabric-dashboard.css": "7a90bbe1f1a2170df5dac0f596a3f302167bef9a7243457bb21dd0eb34f4d359",
+      "fabric-dashboard.js": "146ec9a0fd50af2df3245c02ec7dfba75b7d4e8cb5476fedb5ef727869fef1cc",
+      "fabric-button.js": "60c2b6d44571213e0237c29a94a4cf220f9de3efcfa697ac6a33777d1ad25fd6"
     }
   }
 }

package/plugins/fabric-agent-adapter/skills/building-fabric-services/recipes/dashboard-only/README.md

@@ -0,0 +1,67 @@
+# Recipe: a service that is only a dashboard
+
+A `fabric-service/0.1` service with a dashboard and nothing else: no capabilities, no `mcp` surface, no `usage`
+surface, no provider key and no token of anybody else. Fabric Dashboards asked for it (FD-171, board thread
+`38c35e11`) for a page that shows what the agents of this computer are doing; this recipe is the shape agreed there
+(FAA-268). Built only on the service kit (`fabric_service.py`, `fabric-service.mjs`). Tests:
+`test/test_recipe_dashboard_only.py` and `test/recipe-dashboard-only.test.mjs`.
+
+## Install
+
+```bash
+python3 recipes/dashboard-only/install.py --id example-dashboard --folder ~/.local/share/example-dashboard
+node recipes/dashboard-only/install.mjs --id example-dashboard --folder ~/.local/share/example-dashboard
+```
+
+Both twins take the same flags and write the same descriptor bytes (but `installedAt`). Optional flags: `--instance`
+(default `default`), `--name`, `--repository` (the repository its code is built from; by default the folder's own
+`https://` origin, and a new install without one is refused by the kit, FAA-198), `--port` (this port and no other),
+`--label` with `--plist` (a launchd job, below), `--services-dir` (default `FABRIC_SERVICES_DIR`, else the OS's),
+`--json`.
+
+| Output | Rule |
+|---|---|
+| last stdout line | `{"descriptor": "<path>", "key": "<id>.<instance>", "port": <n>}`; `--json` prints only it |
+| a repeat with the same `--id` | changes nothing and answers the same line; a descriptor of that key another installer wrote, or one with another `--folder`, is refused and left as it is |
+| exit codes | 0 installed or already installed, 1 refused (the reason on stderr, never a value), 2 usage |
+
+The folder gets the token file (`service.token`, 0600, never printed) and later the event log, the login state and
+`snapshot.json`. A refused install writes nothing.
+
+## The port
+
+The installer takes the first port of 47300 to 47999 that no other descriptor of this account declares and that
+`127.0.0.1` binds now, and writes the descriptor through the kit's `write_descriptor` / `writeDescriptor`, whose port
+claim check refuses a port another descriptor declares; a port taken between the two is retried on the next one, up to
+eight. That is the kit's port check as it stands, the older sense of a port claim
+([lifecycle.md](../../references/lifecycle.md), *Install, upgrade, uninstall*): a port another OS account listens on
+or claims still passes (FAA-225). The contract's HA-1 claim file per OS account is not written, because its schema
+waits on the contract's CT-228; the recipe writes it the day the kit does, with no change to its flags or its output.
+
+## Running it
+
+```bash
+python3 recipes/dashboard-only/dashboard_service.py serve --descriptor <path the installer printed>
+```
+
+It serves `/.well-known/fabric-service` (surfaces `dashboard` and `events` only), the events feed and the login code
+for the service token, the one-time login and the signed-in page. Under launchd, pass `--label` and `--plist` on the
+first install and install the job with the kit's `launchd_plist` and `launchd_install`
+([lifecycle.md](../../references/lifecycle.md)), whose `ProgramArguments` run the line above from a release
+directory. `check_service.py <id>` passes every rule it can run on it (the test runs it).
+
+## Where its data comes from
+
+The page shows `<folder>/snapshot.json`, which the person's agent writes from what it reads through the Fabric
+Dashboards MCP (`list_services`, `spend`, `connections`) and Project Observatory's tools. The service itself calls
+nobody, so it holds no token but its own:
+
+```json
+{"takenAt": "2026-11-12T08:00:00Z",
+ "sections": [{"title": "Services", "source": "fabric-dashboards list_services",
+               "columns": ["Service", "State"], "rows": [["example-agent.default", "ready"]]}]}
+```
+
+A snapshot that is missing, cannot be read, does not have this shape, is over 1 MB or is older than a day is
+reported in `degraded` (source `snapshot`) and never shown as data. The well-known document declares the snapshot as
+its one connection (`kind: store`), so a host draws where the page's numbers come from.