@passioncode-ai/passioncode 0.1.4

package/payload/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`.

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

@@ -0,0 +1,32 @@
+# Dashboard principles
+
+The dashboard is where the operator decides; it must stay truthful when parts of the
+service are not.
+
+1. **Same origin, static assets.** HTML shell plus hashed `app.js`/`app.css` from a
+   whitelist; no inline script; a strict CSP. Nothing from a CDN — the page must work
+   offline on a plane.
+2. **State first, then detail.** The top of every page answers "is it working, and
+   does it need me?" — the same `status`, `degraded` and attention tiles the
+   well-known document publishes, so the page and Fabric Dashboards never disagree.
+3. **Calm refresh.** Poll the page's own API every 5 s while visible, back off when
+   hidden, and pause while a field is focused, a form has unsaved input or a dialog is
+   open. Replace a region only when its data changed; keep focus, scroll and open
+   sections.
+4. **Partial failure stays partial.** Load panels independently (`Promise.allSettled`);
+   a failed panel shows its own one-sentence error and a retry, and the rest render.
+5. **Every error is a sentence and an action.** "Store listing push failed: App Store
+   Connect rejected the key. Settings → Keys" — never a status code, a stack trace or a
+   blank area. Show when data was last fresh.
+6. **Server down is a state, not a crash.** When the API stops answering, keep the
+   last data greyed with "Service not answering since 17:02", and recover by itself
+   when it returns.
+7. **Approvals show the diff and its hash.** Any write the operator approves shows
+   before → after and the hash the service will verify at apply time.
+8. **Theme.** Follow the operator's product design system (PassionCode.ai tokens for
+   Fabric-family services); respect `prefers-color-scheme` unless the product fixes a
+   theme; never encode meaning by colour alone.
+9. **Links into the page are stable.** Event `link`s point at hash routes that survive
+   a reload (`/dashboard#/approvals/77`) so a notification opens the exact item.
+10. **No second browser tab required.** With Fabric Dashboards installed, the page is
+    shown inside it; do not open windows or tabs on your own — use in-page dialogs.

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/events-and-notifications.md

@@ -0,0 +1,44 @@
+# Events and notifications
+
+## Map the log you already keep
+
+| Existing log | View |
+|---|---|
+| a SQL `events`/`jobs` table with an autoincrement id | `SELECT … WHERE id > ? ORDER BY id LIMIT ?`; `id` as string |
+| per-job JSONL files | keep one append-only `activity.jsonl` index written beside them, or merge by `(ts, job, seq)` into a composite id `"<ts>-<job>-<seq>"` that still sorts |
+| a journal with no id | add a monotonic counter when appending; backfill ids once on migration |
+| nothing | `JsonlEventLog` from the kit |
+
+The feed is a view: never copy rows into a second store that can drift from the first.
+
+## Writing an event
+
+- `kind`: dotted, stable, past tense or state (`job.failed`, `job.awaiting_choice`,
+  `service.started`, `collector.stale`). Hosts filter on it.
+- `level`: `info` (routine), `notice` (the operator may want to look), `warning`
+  (something is degrading), `error` (something failed and needs action).
+- `text`: one sentence, in the operator's language, with the object named and the
+  number stated — "The Q3 report draft is ready for your approval (12 sections, 3
+  languages)." Never a machine id, never a stack trace.
+- `subject`: what it is about (`{type: "report", id: "q3", label: "Q3 report"}`), so a host
+  can group.
+- `link`: the page that resolves it.
+
+## When to set `notify: true`
+
+Notify when the operator must act (an approval is waiting, a key expired, a job failed
+after retries) or asked to be told (a long job finished). Do not notify for routine
+progress, retries that will succeed, or anything that fires more than a few times an
+hour. The host decides whether to show it — quiet hours, per-service settings — and
+debounces; the service decides only what is notification-worthy.
+
+## Lifecycle events every service emits
+
+`service.started` (with the build), `service.stopping`, `service.degraded` and
+`service.recovered` when a degraded source appears or clears, `update.available` when
+the service learns of a newer release.
+
+## Retention
+
+At least seven days or 1000 events, whichever is more; trim oldest first; a cursor
+older than retention returns the oldest retained page, not an error.

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

@@ -0,0 +1,63 @@
+# Lifecycle — supervisor, install, release layout, state
+
+## launchd plist (generate it with `launchd_plist`)
+
+| Key | Value | Why |
+|---|---|---|
+| `Label` | reverse-DNS, stable (`com.example.example-agent`) | the host controls the job by label |
+| `ProgramArguments` | absolute interpreter + module/script inside a **release** directory | a worktree or checkout path breaks the day it moves |
+| `RunAtLoad` | `true` | back at every login |
+| `KeepAlive` | `true` | `{SuccessfulExit:false}` leaves a cleanly exited service down |
+| `ThrottleInterval` | `10` | bounds a crash loop |
+| `ExitTimeOut` | drain time + margin (40 s default) | SIGKILL arrives after it |
+| `ProcessType` | `Background` | scheduler hint |
+| `EnvironmentVariables` | `PATH` set explicitly; `*_FILE` paths to secrets | never a secret value — the plist is world-readable in backups |
+| `StandardOutPath`/`StandardErrorPath` | `~/Library/Logs/<id>/service.log` | one place the host tails |
+
+## Install, upgrade, uninstall
+
+1. Build or unpack the release into `~/.local/share/<id>/releases/<version>-<sha12>/`
+   (a venv or `node_modules` inside it). Never edit a release after it is written.
+2. `write_descriptor` (port and id claims are checked here).
+3. `launchd_install`: write + `plutil -lint`, `enable`, `bootout` and wait until
+   `launchctl print gui/<uid>/<label>` fails, `bootstrap` with up to five retries,
+   then poll the well-known document until it answers with this `id.instance`.
+4. Upgrade = new release, rewrite the plist with the new path, `launchd_install`
+   again. Keep the previous release for rollback; prune older ones by count.
+5. Uninstall = `launchd_uninstall` + `remove_descriptor`. Data stays.
+
+A host stops a service with `bootout` **and** `disable` (off survives a login) and
+starts it with `enable` + `bootstrap`; restart is `kickstart -k`. The service never
+implements these verbs itself — its CLI calls launchctl the same way.
+
+## Directories
+
+| What | macOS | Linux |
+|---|---|---|
+| data + config | `~/Library/Application Support/<id>/` | `${XDG_DATA_HOME:-~/.local/share}/<id>/` |
+| logs | `~/Library/Logs/<id>/` | `${XDG_STATE_HOME:-~/.local/state}/<id>/logs/` |
+| cache (deletable any time) | `~/Library/Caches/<id>/` | `${XDG_CACHE_HOME:-~/.cache}/<id>/` |
+| code | `~/.local/share/<id>/releases/…` | same |
+
+A repository that versions the data itself (a registry, a plan) may hold the data; the
+service's own code checkout and its releases may not. Directories 0700, secret files 0600. A store carries a schema version and the service
+refuses to open a store newer than its code. The cache holds only what can be rebuilt;
+anything the operator would miss belongs in data.
+
+## Logs
+
+One structured log (JSON lines) rotated by size (5 × 5 MB is a sane default) plus the
+launchd stdout file, truncated at start. Configure logging once, in the entry point.
+Never log a token, a cookie, a login code or a request body that may carry one.
+
+## Shutdown
+
+On `SIGTERM`: stop accepting new work, append a `service.stopping` event, drain
+in-flight work until `ExitTimeOut` minus a margin, persist what was interrupted so the
+next start resumes it, release the lock, exit 0.
+
+## Linux
+
+Until a systemd adapter exists, declare `lifecycle.manager: "none"`. A `systemd --user`
+unit with `Restart=always` gives the same guarantees; the host will control it once the
+adapter ships. Everything else in this skill applies unchanged.

package/payload/plugins/fabric-agent-adapter/skills/building-fabric-services/references/migrating-a-service.md

@@ -0,0 +1,32 @@
+# Migrating an existing service
+
+Order matters: each step leaves the service answering.
+
+1. **Measure first.** Run `check_service.py --descriptor <draft>` against a descriptor
+   written by hand into a temporary `--services-dir`; keep the `FAIL` list as the
+   migration's checklist.
+2. **Add the well-known route and the build identity.** Read-only, no risk.
+3. **Add the events view** over the existing log, then the login-code routes. Keep the
+   service's old login path until the operator has switched.
+4. **Move the lock to the top of startup** — before the startup hook that resumes jobs.
+   Test: a second copy exits 75 and the first copy's running jobs are untouched.
+5. **Move state out of the code tree** if it lives there: copy to the OS data
+   directory, switch the paths, keep the old tree read-only for one release, then
+   delete it with the operator's consent.
+6. **Regenerate the plist** from `launchd_plist`, pointing at a release; delete stray
+   `.plist.bak` files from `~/Library/LaunchAgents` after moving them elsewhere.
+7. **Write the descriptor** from the installer; resolve any port claim it refuses by
+   moving the newcomer, never the established service.
+8. **Re-run the probe** until nothing `FAIL`s; record the table in the service's
+   verification document.
+
+## Gaps that existing services usually have
+
+| Gap | What fixes it |
+|---|---|
+| A health route that answers `{"ok": true}` with no identity | the well-known document with `service.id`, `instance`, build and pid |
+| The port bind treated as the single-instance guarantee, with a startup hook that runs first | the lock at the top of startup; a second copy exits 75 |
+| Data, logs or caches inside the repository | the OS data, log and cache directories; the old tree read-only for one release |
+| `KeepAlive {SuccessfulExit:false}`, a plist pointing at a checkout or a worktree | a plist generated by `launchd_plist`, pointing at a release |
+| A port another service already uses by default | the port claim at install; move the newcomer |
+| An event log in a private shape | the events view over it, with one sentence per event |

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

@@ -0,0 +1,83 @@
+# fabric-service/0.1 — wire reference
+
+Pinned to `fabric-agent-contract` commit `a5a27092ba0dcc5facfbeae8b359146dfb403e9a`
+(`docs/specification/service.md`, DEC-0015). The contract's schemas are normative;
+this page is the working summary. Extension key:
+`https://fabric.passioncode.ai/agent-contract/extensions/service/0.1`.
+
+## Descriptor — written by the installer
+
+Directory: macOS `~/Library/Application Support/ai.passioncode.fabric/services/`,
+Linux `${XDG_DATA_HOME:-~/.local/share}/passioncode-fabric/services/`, or
+`FABRIC_SERVICES_DIR`. File `<id>.<instance>.json`, mode 0600, atomic.
+
+| Field | Rule |
+|---|---|
+| `protocol` | `"fabric-service/0.1"` |
+| `id`, `instance` | `^[a-z][a-z0-9-]{1,62}$`, `^[a-z][a-z0-9-]{0,31}$` (default `default`); the pair is unique per machine |
+| `name`, `summary` | ≤ 80 and ≤ 200 characters |
+| `origin` | `http://127.0.0.1:<port>`; the port is a machine-wide claim |
+| `auth` | `tokenFile` (0600); `header` default `Authorization` with `scheme` `Bearer`; any other header carries the raw token with `scheme: "none"` |
+| `lifecycle` | `manager` `launchd` (then `label` and `plist`) or `none` |
+| `paths` | `data` (required), `logs[]`, optional `config`, `cache` |
+| `commands` | only `doctor` and `update`, argument arrays whose first item is an absolute or `~/` path |
+| `source.repository`, `fabricManifest` | optional |
+| `installedAt`, `installedBy` | when and by which installer version |
+
+## Well-known document — `GET /.well-known/fabric-service`
+
+No auth; the Host/Origin guard applies; answered from memory in under 100 ms.
+
+```json
+{
+  "protocol": "fabric-service/0.1",
+  "service": { "id": "example-agent", "instance": "default", "name": "Example Agent",
+               "version": "0.2.0", "build": { "commit": "8b80be9", "dirty": false, "builtAt": "2026-09-28T17:40:00Z" } },
+  "process": { "pid": 58090, "startedAt": "2026-09-28T17:41:02Z" },
+  "status": "degraded",
+  "degraded": [{ "source": "llm", "reason": "No model key: drafting is paused." }],
+  "summary": [{ "label": "Jobs running", "value": 2 }, { "label": "Awaiting you", "value": 1, "attention": true }],
+  "surfaces": { "dashboard": { "path": "/dashboard", "login": true },
+                "mcp": { "path": "/mcp", "transport": "streamable-http" },
+                "events": { "path": "/fabric/v1/events" } },
+  "update": { "available": null }
+}
+```
+
+- `status`: `starting | ready | degraded | stopping`. No answer means `down`.
+- `build` needs `commit` or `digest` (`sha256:<64 hex>`).
+- `summary`: at most six tiles; `attention: true` counts toward the host's badge.
+- `surfaces.events` is required; `dashboard` and `mcp` when the service has them.
+
+## Events page — `GET /fabric/v1/events?after=<cursor>&limit=<n>`
+
+Token required. `limit` default 50, maximum 200. Without `after`: the newest `limit`,
+ascending. `cursor` is the last id returned, or the `after` you sent when the page is
+empty, or `null` for an empty log. Retain at least seven days or 1000 events.
+
+```json
+{ "events": [ { "id": "4213", "at": "2026-09-28T17:55:10Z", "kind": "job.awaiting_choice",
+                "level": "notice", "text": "The Q3 report draft is ready for your approval.",
+                "subject": { "type": "report", "id": "q3", "label": "Q3 report" },
+                "link": "/dashboard#/approvals/77", "notify": true } ],
+  "cursor": "4213" }
+```
+
+`kind` is dotted lowercase; `level` is `info | notice | warning | error`; `link` is a
+path on the service origin, never an absolute URL. Optional SSE stream at
+`surfaces.events.stream` carrying the same objects.
+
+## Login code — `POST /fabric/v1/login-code`
+
+Token required → `{ "url": "/fabric/v1/login?code=<16–256 url-safe chars>", "expiresAt": "…" }`,
+single use, at most 120 s, recorded as used before it is honoured. `GET` that URL →
+`Set-Cookie` `HttpOnly; SameSite=Strict`, `302` to `surfaces.dashboard.path`.
+
+## Semantic rules a host applies
+
+| Code | Rule |
+|---|---|
+| `FAC-SEM-009` | well-known `service.id.instance` equals the descriptor's, else the port holder is `foreign` |
+| `FAC-SEM-010` | no two descriptors claim one port or one `id.instance` |
+| `FAC-SEM-011` | `ready` carries no degraded source |
+| `FAC-SEM-012` | commands start with an absolute or `~/` executable |

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

@@ -0,0 +1,58 @@
+# Surfaces and auth
+
+## MCP for agents
+
+- One server inside the service process, `streamable-http`, at `/mcp` on the service
+  origin, stateless JSON responses unless the tools stream.
+- Authenticate with the service token in the declared header. OAuth is for remote
+  multi-user servers, not for a loopback service.
+- Register it into a client config with the service's own command
+  (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
+  atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
+  goes in `headers`, never in the URL — every log that records a URL prints its query
+  string.
+- Ship server `instructions` that tell a caller where to start and that every answer
+  carries `degraded`.
+
+## CLI for people and scripts
+
+`<tool> service status|start|stop|restart` (launchctl on the label, then the
+well-known document), `<tool> dashboard` (asks for a login code and opens it; with
+Fabric Dashboards installed it opens the service there instead), `<tool> doctor --json`
+(the same checks the probe runs, plus provider keys), `--json` on every command. Print
+a sign-in link only when stdout is a terminal.
+
+## A2A for remote agents
+
+Remote reach goes through A2A `1.0` over HTTPS or an authenticated gateway in front of
+MCP — never by binding a LAN address. A tunnel (Tailscale Serve and the like) is an
+outward surface with its own token lifetime; watch it like a service, because nothing
+else will notice it expire.
+
+## Token
+
+- Created once with `ensure_token` at first start, after the instance lock.
+- Stored at the descriptor's `auth.tokenFile`, 0600, owner-checked, never a symlink.
+- Compared in constant time (`token_matches`).
+- Rotation is an operator act: write a new file, restart, re-run `mcp-register`.
+- Same-user processes can read it. The protocol defends against web pages and
+  mistakes, not against hostile code running as the operator — say so in SECURITY.md.
+
+## Dashboard session
+
+- `POST /fabric/v1/login-code` (token) → single-use code, at most 120 s, persisted as
+  used before it is honoured, burned even when expired.
+- `GET /fabric/v1/login?code=` → `HttpOnly; SameSite=Strict` cookie, 302 to the
+  dashboard. Sessions are HMAC-signed; `revoke_all` rotates the key and ends every
+  session at once.
+- Browser writes need the cookie **and** a custom header such as `X-<Tool>-Request: 1`,
+  which forces a preflight the service never answers.
+- A dashboard that is deliberately read-open to local pages declares
+  `"login": false`; its writes still need the header.
+
+## Headers every response carries
+
+`Cache-Control: no-store`, `X-Content-Type-Options: nosniff`, a CSP with no inline
+script, and `frame-ancestors 'self'` unless the page must never be embedded. Fabric
+Dashboards shows pages in a native view, not a frame, so `X-Frame-Options: DENY` does
+not stop it.