@passioncode-ai/fabric-agent-adapter 0.79.1 → 0.81.0

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/new-agent.md

@@ -0,0 +1,42 @@
+# One command for a new agent project
+
+`new` creates an agent project with the contract built in, from the kit's template (FAA-270, North Star G21). It runs
+after the intake grill (step 0) has named the agent's id, its profile and whether it runs as a service; the grill's
+other answers still go into the project by hand.
+
+```bash
+npx @passioncode-ai/fabric-agent-adapter new <folder> --id <agent-id> [--profile mcp|a2a|local-runner] [--service]
+python3 <plugin-dir>/skills/adapting-projects-to-fabric/scripts/new_agent.py <folder> --id <agent-id> [...]
+```
+
+Both run the same script (the npm command runs it under the first Python 3.9 or later on PATH). Optional flags:
+`--capability <domain.action>` (default `<id>.run`), `--effect <class>` (default `none`: declare money, deletion or
+publication now), `--force`, `--json`.
+
+## What it writes
+
+| Path | What |
+|---|---|
+| `fabric-agent.json`, `fabric-contract.lock.json`, `fabric/` | the provider bundle `adapt_project.py scaffold` writes, pinned to the contract; every value it invents is a sentinel `adapt_project.py check` names |
+| `fabric.source.json` | the source manifest (DEC-0149): `include` names the project's source, default deny; the slots are the publisher's URI behind `provider.createdBy` (`PUBLISHER_URI`), the placement record (`PLACEMENT_RECORD`) and, for a service, its supervisor label and port (`SUPERVISOR_LABEL`, `SERVICE_PORT`), never a value ([the source and the instance](source-and-instance.md)) |
+| `src/placement.py`, `tests/test_placement.py` | the placement guard ([where agents run](where-agents-run.md), *Its own machine*): placed on another machine, it refuses to start; no record, it starts; a record it cannot read, it starts degraded; the three cases are its tests |
+| `config/placement.example.json` | Project Observatory's placement record (`observatory-placement/1`) on neutral values: the shape the guard reads |
+| `README.md`, `LICENSE`, `.gitignore` | the layout and the slots by name; all rights reserved until the owner names the terms; the instance kept out of Git |
+| `service/` (with `--service`) | the service kit's sample (`service.py`, a `fabric-service/0.1` service) and the kit modules it imports, copied by `fabric_kit.py install` so `fabric_kit.py status` checks them later |
+| `fabric/new-agent.json` | the arguments it was made with, so a repeat is recognised |
+
+## Rules
+
+- **Idempotent.** A repeat with the same arguments in a folder this command made changes nothing and answers the same
+  line with `"repeated": true`.
+- **Never over someone's files.** A folder holding anything else is refused (exit 1) unless `--force`, which writes the
+  planned files over it and leaves every other file as it is.
+- **The last stdout line is JSON:** `{"folder", "id", "profile", "service", "created", "repeated"}`; `--json` prints
+  only it. Exit 0 made or already made, 1 refused (the reason on stderr), 2 usage.
+- **Done means checked.** The new project passes `fabric_source_check.py check <folder>` under its own manifest and its
+  own tests; a service passes `check_service.py` against its sample once it is served and registered
+  (`python3 service/service.py serve --id <agent-id> --port <port> --data-dir <data>`, then `register` with
+  `--repository`). Then the sentinels are replaced, the grill's answers written in, and the agent built.
+
+What it does not do yet: infer the agent from a sentence (`new "<sentence>"`) and run its evals (`test`). Both stay with
+FAA-26, blocked on Fabric's `fabric.agent.create`.

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/resilience-and-autonomy.md

@@ -216,6 +216,12 @@ leaves a held task still. The working-with-fabric skill's Step 5 carries it; Fab
    transaction, and log a transaction held long with the step that held it. Every blocking network
    wait is interruptible from outside, with its deadline on the socket, not between frames.
 
+13. **A routine fails its run when writing its result fails.** A scheduled or background routine (a digest, a
+   snapshot, a measurement, a sync) whose result file, row, report or board message cannot be written (a full disk,
+   a refused write, a lost connection, a schema the store refuses) exits non-zero and records the failure by its
+   code; it never logs success over a result nobody can read, and the next run sees the gap instead of yesterday's
+   value standing as today's. Its tests: a test makes the write fail and sees the run fail (FAA-294).
+
 ## Secrets and confinement
 
 1. **A secret never enters an environment, argv, URL or log a child can read.** The agent's own
@@ -268,7 +274,7 @@ Before the first release, answer each with a file and a test: where a limit paus
 `accept` each model call has; which vendors its fallback and checker use; where the attempt ledger
 and idempotency keys live; what happens to an unknown outcome; which waits are durable; who owns the
 run lock; what the next start sweeps; how a cancel reaches paid inner work; which outputs are
-capped; how a secret reaches a child; which test was seen failing for each fix; and, for an agent
+capped; which routine fails its run when its result cannot be written; how a secret reaches a child; which test was seen failing for each fix; and, for an agent
 that writes text for people, where its prompt says no em dash and which test fails on U+2014 in its
 output; and where each piece of work's retro is written (its lessons through `observatory_lesson`, or the agent's own retrospective
 file without Project Observatory; its insight/1 lines in `insights/`, practices.md *Reliability*) and which test shows it.

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/source-and-instance.md

@@ -7,13 +7,15 @@ first commit, so that its owner can hand the source over later without rewriting
 by itself: handing over, a new remote, a push or a change of visibility stays the owner's act, each time (a personal
 agent stays private until its owner says so about that act).
 
-The format of a source manifest, export and import is the contract's to decide (CT-194). What follows does not depend
-on it.
+The format of a source manifest, export and import is the contract's: DEC-0149 (`fabric-source/1`, its `source.md`) at
+the pin. The kit lays down `fabric.source.json` ([the source manifest](#the-source-manifest)), and the check reads the
+source under it.
 
 ## Contents
 
 - [The layout](#the-layout)
 - [The data home and its kind](#the-data-home-and-its-kind)
+- [The source manifest](#the-source-manifest)
 - [The check](#the-check)
 
 ## The layout
@@ -42,11 +44,11 @@ on it.
 - **Fixtures on neutral ids.** A test that needs a home folder, an owner or an account uses `example`, `example-agent`,
   `owner@example.com` or a one-letter home, and a credential-shaped test value says it is synthetic
   (`sk-test-not-a-key`) or is assembled at run time.
-- **Two names stay in the source until the contract decides (CT-194).** A service's supervisor label is the agent's
-  own name, reverse-DNS on the publisher's domain (`com.example.example-agent`), and `AGENTS.md` names it (LC-09):
-  never the owner's account or name. A provider's `createdBy` names the publisher; until one is chosen it
-  keeps the scaffold's sentinel, and a person's name or account is never written there. The adapter moves both when the
-  contract decides how an instance renames them (FAA-188 part 2).
+- **Two names are slots, never values (DEC-0149, FAA-188 part 2).** A service's supervisor label is the agent's own
+  name, reverse-DNS on the publisher's domain (`com.example.example-agent`), and `AGENTS.md` names it (LC-09): never the
+  owner's account or name; the label an installation runs under is its `SUPERVISOR_LABEL` slot, with its port in
+  `SERVICE_PORT`. A provider's `createdBy` names the publisher; the source keeps the scaffold's sentinel, and the
+  publisher's URI is the installation's `PUBLISHER_URI` slot, so a person's name or account is never written there.
 
 ## The data home and its kind
 
@@ -69,6 +71,41 @@ on it.
   configuration and dependency folders `--every-file` reads too), each exit 0, with the owner's list or its absence recorded, until the contract's export (CT-194)
   replaces it.
 
+## The source manifest
+
+`fabric.source.json` at the source's root says what is source and which slots an installation fills, never a value
+(DEC-0149, `fabric-source/1`):
+
+| Member | What |
+|---|---|
+| `include` | the source, default deny: a file outside every entry is not source; an entry ending in `/` is a folder, no globs |
+| `exclude` | holes in `include`, read in any letter case and Unicode form (a file an entry names only in another spelling is left out, and the check says `excluded-by-fold`) |
+| `binaries` | the binary files that are source (an icon, a font); another binary blocks |
+| `unchecked` | source paths that travel unread, each with its reason (synthetic test vectors, a licence naming a holder on the owner's list) |
+| `publicAddresses` | the e-mail addresses the source may carry (a support address); another one warns |
+| `slots` | what an installation fills, by name: `secret` (a key), `config` (a setting: a repository URL, a folder, the supervisor label, the publisher's identity), `store` (a data store, with its path in the data folder), `endpoint` (the operator's infrastructure by role) |
+
+- **Laying it down.** A new agent gets it from `new_agent.py` (creating-fabric-agents' `references/new-agent.md`); an
+  existing project from `adapt_project.py source <project-root>` (adapting-projects-to-fabric's scripts), which proposes `include` from the
+  project's top-level entries (what Git would commit, instance data by its name left out) and names the kit's slots
+  (`PUBLISHER_URI` where a provider manifest is there, `PLACEMENT_RECORD`, and with `--service` `SUPERVISOR_LABEL` and
+  `SERVICE_PORT`); `--secret NAME:PURPOSE` and `--store NAME:PATH:PURPOSE` add the agent's own. `--dry-run` prints the
+  proposal and writes nothing; an existing manifest is the owner's and is replaced only with `--force`. The author then
+  narrows `include` to what is source.
+- **The check under it.** When the folder it checks holds `fabric.source.json`, `fabric_source_check.py check` reads
+  the source the manifest names and reports the contract's kinds (`fabric_source_tree.py`, held to the contract's
+  vectors): blocking `home-path`, `credential`, `binary`, `nested-repository`, `instance-string`, `missing`,
+  `no-include` and the manifest's own findings (FAC-SEM-156, FAC-SEM-157); warnings `email`, `link-outside`,
+  `no-license`, `unused-exclude`, `excluded-by-fold`, each by path, line and column (UTF-16 units), never by the text
+  found. Exit 1 on a blocking finding, 0 when only warnings remain and every source file was read, 2 when one was not.
+  `.fabric-source-ignore` and `--exclude` are not read there: `exclude` and `unchecked` say it. A declared home
+  (`home: <name>`) is still found in every source file.
+- **Packing it.** `pack` (building-fabric-services' `references/package.md`) writes the package's `secrets[]` from the secret slots and `state[]` from the store slots' paths, and refuses a
+  package whose members differ (FAC-SEM-160); an empty `state[]` is a copy packed without state, and stays so. A
+  hand-written `secrets[]` naming a secret the manifest has no slot for is refused by name, never dropped.
+- **Handing it over** stays the owner's act, each time, on their word for that act (the contract's `source.md`,
+  Handing over).
+
 ## The check
 
 `fabric_source_check.py check` reads the files the source would carry (what Git would commit: tracked files and

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/where-agents-run.md

@@ -17,6 +17,7 @@ The normative rules are the Fabric Agent Contract's, at the commit this plugin p
 - [Sharing an agent into an organization](#sharing-an-agent-into-an-organization)
 - [Running while the laptop is closed](#running-while-the-laptop-is-closed)
 - [Uptime: A or B](#uptime-a-or-b)
+- [Its own machine: placement, keys and port](#its-own-machine-placement-keys-and-port)
 - [Selling an agent](#selling-an-agent)
 - [The checklist](#the-checklist)
 
@@ -115,6 +116,31 @@ Every new agent is given an uptime category on its first day, and the README nam
 A B agent that gains a capability that must answer around the clock becomes A for that capability; record the change
 and move only that capability to the cloud.
 
+## Its own machine: placement, keys and port
+
+An agent that may run on more than one machine of the estate (a laptop and a personal cloud, an old and a new
+computer during a move) runs on exactly one at a time, and each copy reads only its own machine's keys.
+
+- **Placement.** At start, before it polls, schedules or listens, the agent reads Project Observatory's placement
+  record, `${XDG_DATA_HOME:-~/.local/share}/project-observatory/placement.json` (schema `observatory-placement/1`;
+  Observatory's `observatory/engine/machine_identity.py`). An entry of its `elsewhere` list whose `serviceId` is the
+  agent's `id.instance`, or whose `label` is its launchd label or systemd unit, and whose `placedOn` is not the file's
+  `machine`, says the agent runs on another machine: it refuses to start, writes one log line and reports
+  `degraded` with the reason `placed-elsewhere` and the machine id where it can, and starts nothing that acts. With
+  no file (Observatory absent, nothing ever moved) it starts. A file it cannot read, or one of another schema, does
+  not stop it: it starts and reports `degraded` with `placement-unreadable`, since a guard that cannot read refuses
+  nothing the estate recorded. `full machine-move leave LABEL --to MACHINE` writes the entry and stops the job here;
+  `full machine-move cutover LABEL` removes it on the machine the job moves to. A supervisor that restarts on exit
+  (`KeepAlive`, `Restart=always`) restarts a refused copy under its throttle: stopping the job here is `leave`'s, and
+  the refusal guards a copy started anyway (a restore, a start by hand). Its tests start one copy placed elsewhere and see it refuse, and one with no file and one with a
+  malformed file and see them start.
+- **Keys.** Each copy reads its credentials only from its own vault, the vault of the OS account and machine it
+  runs on (`use_secret.py run` there), never copied from another machine's or account's vault, a backup or a file a
+  move carried. A key the new machine needs is issued anew there through the provider's door, or asked of the
+  person once, and the old machine's key is revoked when the copy there stops.
+- **Port.** Until the contract's port-claim decision (DEC-0160) lands, the kit refuses a port another OS account
+  already listens on (FAA-225); the port recorded per account and its claim file follow DEC-0160.
+
 ## Selling an agent
 
 - **A paid agent** runs in PassionCode's cloud inside its developer's organization (`org:<developer>`); each customer
@@ -133,6 +159,8 @@ and move only that capability to the cloud.
 - Which capabilities need the person's machine, and what do they answer when it is off?
 - On a computer with more than one counted OS account, or under a member's virtual machine: a port recorded per
   account, the listener's owner checked before a token is sent, no token-free loopback door (DEC-0154).
+- On a machine of its own: it starts only on the machine `placement.json` names (or with no entry for it), and reads
+  keys from that machine's own vault.
 - Which uptime category is it, A (a cloud host from the first release) or B (local only)? The README names it.
 - Who pays for each call (which grant, which key)? The person's personal key never pays for an organization.
 - If it joins machines or applies the estate record: tokens from stdin or a 0600 file only, revisions verified with

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/working-rules.md

@@ -0,0 +1,54 @@
+# Working rules a new agent carries from its first commit
+
+Three rules the operator set for every agent (board message `bfc0e14e`, 2026-11-12: FAA-299, FAA-300, FAA-301). A
+new agent's template (its `AGENTS.md`, its system prompt, its session start) states each one, and a test pins each
+one's key sentence, so a copy of the agent cannot lose them. The working-with-fabric skill states the same rules for a
+coding session; this page is what the agent you build says about itself.
+
+## Contents
+
+- [The context of a task](#the-context-of-a-task)
+- [A wait is not a stop](#a-wait-is-not-a-stop)
+- [Clean up after yourself](#clean-up-after-yourself)
+- [The checklist](#the-checklist)
+
+## The context of a task
+
+Follows the contract's CT-292 draft (rules TC-1 to TC-6, `docs/evidence/plans/2026-11-12-ct292-task-context.md` at
+`753c5093`) until its DEC lands (the contract's slice of 2026-11-21).
+
+An agent that can reach resources of more than one context (`personal`, `org:<orgId>`, contract DEC-0082) **settles
+the task's context at session start, before its first act on them**, from: the operator's words; the board request's
+Project; the folder's Project by folder attribution (DEC-0089) and its organization; the grant's context (DEC-0082);
+the place. The context is settled when every source that names one names the same one.
+
+When none names it, or they disagree, **the agent asks the operator once, naming the candidates and what each would
+do; it never guesses, never picks a "safest" one and never splits the task across contexts.** With no person in the
+session the question goes through `fabric_question_ask` (the candidates as `options`). This is the one exception to
+the template's "do not ask, do it" rule for the operator's word (FAA-207, CT-220). The answer is recorded in the
+handoff as `{context, by: "operator", at, source}`, so the next agent does not ask again. The question and the answer
+never go into either organization's board thread.
+
+The template's session start reads the five sources before any tool that acts across contexts; an agent that reaches
+only one context asks nothing and says which one in its report.
+
+## A wait is not a stop
+
+The agent finishes a unit of work and takes the next in the same turn (the board's next open task, a request addressed
+to it, the handoff's next task). **Every wait has its condition, owner, next action and watcher, or an honest "no
+watcher".** `fabric_heartbeat` carries `waitingOn` (`question`, `grant` or `continuation`, with its id) or a one-line
+`note` while it waits. **A turn ends with one line per open wait, never with "shall I continue?"**
+
+## Clean up after yourself
+
+After a merge the agent **removes its own worktrees and branches locally and on origin, then runs `git fetch
+--prune`**. A branch with commits found nowhere else is archived under `refs/archive/<date>/` before it is deleted. It
+removes build output and dependency folders in its abandoned or merged copies and stops its own processes. **It never
+touches another session's worktree, a `locked` one, or a Git-tracked file: `git ls-files -- <dir>` must print nothing
+before a folder is removed.**
+
+## The checklist
+
+- [ ] The template states the context rule, its one question and where the answer is recorded; a test pins it.
+- [ ] The template states "a wait is not a stop" with the four parts of a wait and the turn's last lines; a test pins it.
+- [ ] The template states the cleanup rule with its `git ls-files` check; a test pins it.

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/schemas/template/access.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/passioncode-ai/fabric-agent-adapter/schemas/template/access.schema.json",
+  "title": "access.json of an agent template: per access level, what it does without asking, what needs approval, what escalates",
+  "type": "object",
+  "required": ["levels", "never"],
+  "additionalProperties": false,
+  "patternProperties": {"^x-[a-z0-9-]+$": {}},
+  "properties": {
+    "levels": {
+      "type": "object",
+      "required": ["owner", "administrator", "project_architect", "member"],
+      "additionalProperties": false,
+      "properties": {
+        "owner": {"$ref": "#/$defs/owner"},
+        "administrator": {"$ref": "#/$defs/level"},
+        "project_architect": {"$ref": "#/$defs/level"},
+        "member": {"$ref": "#/$defs/level"}
+      }
+    },
+    "never": {"type": "array", "items": {"type": "string", "minLength": 1}, "description": "what the agent never does at any level"},
+    "rule": {"type": "string", "minLength": 1},
+    "notes": {"type": "string"}
+  },
+  "$defs": {
+    "acts": {"type": "array", "items": {"type": "string", "minLength": 1}},
+    "level": {
+      "type": "object",
+      "required": ["without_asking", "with_approval", "escalates"],
+      "additionalProperties": false,
+      "properties": {
+        "without_asking": {"$ref": "#/$defs/acts"},
+        "with_approval": {"$ref": "#/$defs/acts"},
+        "escalates": {"$ref": "#/$defs/acts"},
+        "notes": {"type": "string"}
+      }
+    },
+    "owner": {
+      "type": "object",
+      "required": ["without_asking", "with_approval", "escalates"],
+      "additionalProperties": false,
+      "properties": {
+        "without_asking": {"$ref": "#/$defs/acts"},
+        "with_approval": {"$ref": "#/$defs/acts"},
+        "escalates": {"type": "array", "maxItems": 0, "description": "nobody stands above the owner"},
+        "notes": {"type": "string"}
+      }
+    }
+  }
+}

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/schemas/template/connections.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/passioncode-ai/fabric-agent-adapter/schemas/template/connections.schema.json",
+  "title": "connections.json of an agent template: the source classes it reads and writes, each with its connector and grant",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["source_class", "connector", "grant", "required", "direction"],
+    "additionalProperties": false,
+    "properties": {
+      "source_class": {"type": "string", "minLength": 1, "description": "a class of source (a tracker, a chat, a store), never one installation"},
+      "connector": {"type": "string", "minLength": 1},
+      "grant": {"type": "string", "minLength": 1, "description": "the grant or scope it needs, by name; never a value"},
+      "required": {"type": "boolean"},
+      "when": {"type": "string", "minLength": 1, "description": "the condition under which an optional connection is needed, or under which a required one applies"},
+      "direction": {"enum": ["read", "write", "read-write", "call"]},
+      "scope": {"type": "string", "minLength": 1, "description": "what the direction covers, in words (\"draft pull requests only\")"},
+      "spends": {"type": "boolean", "description": "true when a call through it costs money (rule A6)"},
+      "variants": {"type": "array", "items": {"type": "string"}, "minItems": 1, "uniqueItems": true},
+      "notes": {"type": "string"}
+    }
+  }
+}

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/schemas/template/data-rooms.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/passioncode-ai/fabric-agent-adapter/schemas/template/data-rooms.schema.json",
+  "title": "data-rooms.json of an agent template: the rooms and blocks it reads or writes ([] when none)",
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": [
+      "room",
+      "blocks",
+      "access"
+    ],
+    "additionalProperties": false,
+    "properties": {
+      "room": {
+        "type": "string",
+        "minLength": 1
+      },
+      "blocks": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        },
+        "minItems": 1,
+        "uniqueItems": true
+      },
+      "access": {
+        "enum": [
+          "read",
+          "write",
+          "read-write"
+        ]
+      },
+      "scope": {
+        "type": "string",
+        "minLength": 1,
+        "description": "what the access covers, in words (\"its own block\", \"aggregate cells only\")"
+      },
+      "classes": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "minLength": 1
+        },
+        "minItems": 1,
+        "uniqueItems": true,
+        "description": "the data classes it may touch in the block"
+      },
+      "level": {
+        "type": "string",
+        "minLength": 1,
+        "description": "whose level bounds the read (\"the asker's level\")"
+      },
+      "required": {
+        "type": "boolean"
+      },
+      "variants": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "uniqueItems": true
+      },
+      "use": {
+        "type": "string"
+      },
+      "notes": {
+        "type": "string"
+      }
+    }
+  }
+}

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/schemas/template/manifest.schema.json

@@ -0,0 +1,170 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/passioncode-ai/fabric-agent-adapter/schemas/template/manifest.schema.json",
+  "title": "manifest.json of an agent template: placement, contract, doors, dashboard, base model per task, budget",
+  "description": "placement, doors, models, dashboard and budget sit at the top level, or in every entry of `variants` when the variants differ. Their inner shape is the template's own in schema 1.",
+  "type": "object",
+  "required": [
+    "template",
+    "version",
+    "contract"
+  ],
+  "additionalProperties": false,
+  "patternProperties": {
+    "^x-[a-z0-9-]+$": {}
+  },
+  "properties": {
+    "template": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,63}$",
+      "description": "equals TEMPLATE.md's template.id"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$",
+      "description": "equals TEMPLATE.md's template.version"
+    },
+    "contract": {
+      "description": "one protocol the template was checked against, or a map of them by role",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/protocol"
+        },
+        {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "$ref": "#/$defs/protocol"
+          }
+        }
+      ]
+    },
+    "placement": {
+      "type": [
+        "object",
+        "string"
+      ]
+    },
+    "doors": {
+      "type": [
+        "object",
+        "array"
+      ]
+    },
+    "models": {
+      "type": [
+        "object",
+        "array"
+      ]
+    },
+    "dashboard": {
+      "type": [
+        "object",
+        "string"
+      ]
+    },
+    "budget": {
+      "type": [
+        "object",
+        "string"
+      ]
+    },
+    "schedules": {
+      "type": [
+        "array",
+        "object",
+        "string"
+      ]
+    },
+    "limits": {
+      "type": "object"
+    },
+    "events": {
+      "type": "array"
+    },
+    "variants": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "placement": {
+            "type": [
+              "object",
+              "string"
+            ]
+          },
+          "doors": {
+            "type": [
+              "object",
+              "array"
+            ]
+          },
+          "models": {
+            "type": [
+              "object",
+              "array"
+            ]
+          },
+          "dashboard": {
+            "type": [
+              "object",
+              "string"
+            ]
+          },
+          "budget": {
+            "type": [
+              "object",
+              "string"
+            ]
+          }
+        }
+      }
+    },
+    "notes": {
+      "type": "string"
+    }
+  },
+  "$defs": {
+    "protocol": {
+      "type": "object",
+      "required": [
+        "name",
+        "home",
+        "checked_against"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "home": {
+          "type": "string",
+          "minLength": 1
+        },
+        "checked_against": {
+          "type": "string",
+          "minLength": 1,
+          "description": "the version or date checked against: \"checked against\", never \"requires\""
+        },
+        "extensions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "description": "the protocol's extensions the template uses, by name"
+        },
+        "applies_to": {
+          "type": "string",
+          "minLength": 1
+        },
+        "notes": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/schemas/template/template-header.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/passioncode-ai/fabric-agent-adapter/schemas/template/template-header.schema.json",
+  "title": "The `template:` header of an agent template's TEMPLATE.md (fabric-workspace S2, decision W0-Q8)",
+  "type": "object",
+  "required": ["template"],
+  "additionalProperties": false,
+  "properties": {
+    "template": {
+      "type": "object",
+      "required": ["id", "name", "version", "family", "checked", "readiness", "variants"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$", "description": "equals the folder's name"},
+        "name": {"type": "string", "minLength": 1, "maxLength": 120},
+        "version": {"type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$"},
+        "family": {"type": "string", "pattern": "^[a-z]+(-[a-z]+)*$"},
+        "checked": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"},
+        "readiness": {"enum": ["draft", "validated", "proven"]},
+        "sources": {"type": "integer", "minimum": 0},
+        "variants": {"type": "array", "items": {"type": "string", "pattern": "^[a-z][a-z0-9-]{0,63}$"}, "uniqueItems": true}
+      }
+    }
+  }
+}