@passioncode-ai/fabric-agent-adapter 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.37.0 - 2026-10-19
+
+### Added
+
+- **`creating-fabric-agents` carries what the estate learned about building agents** (FAA-58, the operator's request
+  of 2026-10-19): four new references every new agent starts from.
+  - `where-agents-run.md`: this machine, a personal cloud, an organization, Enterprise; contexts (`personal`,
+    `org:<id>`) with one instance per context and no secret, spend or journal crossing; connecting a machine (nearby
+    code, headless enroll token); sharing an agent into an organization; running while the laptop is closed; selling
+    an agent (a paid agent in its developer's organization, a partner's setup).
+  - `models-and-providers.md`: lanes with a fallback of another vendor and an open-vendor model where users' content is
+    read; a dated starting choice from the OpenRouter catalog; several kinds of input and output; budgets that survive
+    reasoning; one OpenRouter key per agent and context with its ceiling, read from the environment; measuring a choice.
+  - `orchestration-and-learning.md`: workflow first; the work graph of durable jobs with intent keys, effects observed,
+    limits as pauses (DEC-0087); calling other agents within a narrower grant and budget; stops for a person; learning
+    loops (decisions with reasons, one trace per turn, failures as planted fixtures first, history replayed, learnings
+    proposed and never self-approved); the loop guard.
+  - `practices.md`: the rules production agents taught us, each with its check: judges and evals, numbers, money,
+    people in the loop, reliability, shipping.
+- The intake grill asks **Where does it run, for whom?**, **Which models?**, **Who pays?** and **How does it learn?**;
+  the knowledge intake links the four references. `test/validate.py` holds the rows, the links and each reference's
+  checklist (`KnowledgePackTests`); eval scenario `agent-for-a-personal-and-an-organization-cloud`; three trigger
+  queries.
+
 ## 0.36.0 - 2026-10-19
 
 Repinned to Fabric Agent Contract `07042181bfae2a481aa0da1a5651f24c76669c48` (DEC-0084 to DEC-0088); `d8146cf` stays

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

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

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles; and teach a coding agent to work in a project through Fabric (fabric-mcp, fabric_whoami, claim and release), with Claude Code session hooks.",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

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

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.36.0"
+  version: "0.37.0"
   contract-version: "0.1.0"
   contract-commit: "07042181bfae2a481aa0da1a5651f24c76669c48"
 ---

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

@@ -18,7 +18,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; 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.36.0"
+  version: "0.37.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "07042181bfae2a481aa0da1a5651f24c76669c48"

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

@@ -1,11 +1,11 @@
 ---
 name: creating-fabric-agents
-description: Use when designing and building a NEW agent or provider that must be Fabric-compatible from its first commit — «создай агента, совместимого с фабрикой Passion Code», «новый агент под Fabric», "create a fabric-compatible agent", "build a new Fabric provider", "fabric-ready agent from scratch". Runs the intake grill (capability, named consumer, workflow-or-agent, MCP/A2A/local-runner profile, effect declarations), distils source projects into a knowledge pack whose recorded failures become planted eval fixtures, scaffolds the pinned contract bundle, and sets the two-clock eval expectation with the conformance report. NOT for adapting an existing project (use adapting-projects-to-fabric), building the Fabric host or orchestrator, or generic agent design where Fabric compatibility is not part of the request.
+description: Use when designing and building a NEW agent or provider that must be Fabric-compatible from its first commit, «создай агента, совместимого с фабрикой Passion Code», «новый агент под Fabric», "create a fabric-compatible agent", "build a new Fabric provider", "fabric-ready agent from scratch", «агент в облаке организации», "which models and OpenRouter key for a new Fabric agent". Runs the intake grill (capability, named consumer, workflow-or-agent, MCP/A2A/local-runner profile, effect declarations, where it runs, models, who pays, how it learns), distils source projects into a knowledge pack whose recorded failures become planted eval fixtures, scaffolds the pinned contract bundle, and sets the two-clock eval expectation with the conformance report. NOT for adapting an existing project (use adapting-projects-to-fabric), building the Fabric host or orchestrator, or generic agent design where Fabric compatibility is not part of the request.
 license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.36.0"
+  version: "0.37.0"
   contract-version: "0.1.0"
   contract-commit: "07042181bfae2a481aa0da1a5651f24c76669c48"
 ---
@@ -52,7 +52,10 @@ No file is created until every row has an answer. An answer of "later" fails the
 | **Workflow or agent?** | if every step can be named now, build a deterministic workflow behind the capability and skip the autonomy — an agent buys flexibility with latency, cost, and a new failure class, and that price needs a reason |
 | **Which profile?** | `mcp` when Fabric owns planning and retries and the capability has a schema; `a2a` when the provider owns its task lifecycle end to end; `local-runner` when it is a terminal agent Fabric drives. When unsure, the sibling skill's profile-selection reference is the decision record |
 | **What effects?** | declare anything money-, deletion-, or publication-adjacent now — the host's floor and grants are designed against these declarations, and one discovered late invalidates the admission |
-| **Which tenancy?** | record whether the agent assumes one operator; the assumption is cheap to write down and expensive to excavate |
+| **Where does it run, for whom?** | this machine, the person's cloud or an organization's, and in which contexts (`personal`, `org:<id>`): one instance per context, its secrets, spend and journal never crossing into another. Record which capabilities need the person's machine and what they answer when it is off (references/where-agents-run.md) |
+| **Which models?** | per lane (planning, replies, volume work, media): a primary, a fallback of another vendor, an open-vendor model where it reads what users send, the input kinds each reads, declared as classes in the profile (references/models-and-providers.md) |
+| **Who pays?** | one key per agent and context with its own ceiling, from the estate's key manager, read from the environment; checked before every call; a personal key never pays for an organization |
+| **How does it learn?** | decisions recorded with reasons, one trace per turn, every failure a planted fixture first, history replayed, learnings proposed and never self-approved (references/orchestration-and-learning.md) |
 | **Text for people?** | if it writes anything a person reads (a reply, a message, a post, a report, a UI string), its prompt forbids the em dash (U+2014) and any substitute for it, and a test fails on U+2014 in new output, from the first commit (the resilience reference, *Text for people*) |
 
 ## Step 1 — the knowledge intake
@@ -73,6 +76,20 @@ Skipping this step because there is no prior art is legal; skipping it because r
 is slower than generating is how the same collector truncates at the same row limit
 twice.
 
+Every new agent also starts from what the estate already learned, whether or not it has
+prior art of its own:
+
+- [practices.md](references/practices.md): the rules production agents taught us, each with
+  the check that catches it (judges and evals, numbers, money, people in the loop,
+  reliability, shipping). Organization members also read the knowledge base's
+  `knowledge/agent-practices.md` and add to it what this agent learns.
+- [where-agents-run.md](references/where-agents-run.md): this machine, a personal cloud, an
+  organization; contexts; connecting a machine; sharing into an organization; selling.
+- [models-and-providers.md](references/models-and-providers.md): lanes, a starting model
+  choice, several kinds of input and output, budgets, OpenRouter keys.
+- [orchestration-and-learning.md](references/orchestration-and-learning.md): the work graph,
+  calling other agents, stops for a person, learning loops, the loop guard.
+
 ## Step 2 — the project skeleton
 
 Create the minimal project: repository, `README.md` naming the capability and its

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/models-and-providers.md

@@ -0,0 +1,105 @@
+# Models and providers: which model for which lane, and how it is paid
+
+An agent has lanes: the part that plans and calls tools, the part that writes to a person, the part that classifies a
+thousand items a day, the part that reads an image. Each lane gets its model on purpose, a fallback from another vendor,
+and a budget that survives a verbose model. Most agents reach models through OpenRouter, one key per agent.
+
+Normative rules: the Fabric Agent Contract's `runners.md` (*Runner and model profiles*, DEC-0046: model classes, the
+resolution order request > agent > binding > policy), DEC-0083 (a lane that reads user content runs on an open-vendor
+model, FAC-SEM-112) and `openrouter-attribution.md` (FAC-SEM-098). The kit that resolves profiles is
+`building-fabric-services/scripts/fabric_profiles.py` (references/profiles.md there).
+
+## Contents
+
+- [Lanes, not one model](#lanes-not-one-model)
+- [A starting choice](#a-starting-choice)
+- [Several kinds of input and output](#several-kinds-of-input-and-output)
+- [Ids, budgets and deadlines](#ids-budgets-and-deadlines)
+- [OpenRouter: one key per agent](#openrouter-one-key-per-agent)
+- [Measuring a choice](#measuring-a-choice)
+- [The checklist](#the-checklist)
+
+## Lanes, not one model
+
+- **Big model where it pays, light model where volume is.** The strongest model for low-volume reasoning: an agent
+  that plans and calls tools, research, a judge. A light, cheap model for high-volume work: classification,
+  extraction to JSON, reranking, summaries, periodic jobs, routine chat.
+- **Every lane has a fallback from another vendor** (the prefix before `/` differs), and the config loader refuses a
+  profile without one. One vendor's outage or policy change must not take the whole agent down.
+- **A lane that reads what users send runs on an open-vendor model** as its primary, or as its fallback when the
+  primary is closed (DEC-0083: declare `reads: ["user-content"]` on the profile; FAC-SEM-112 refuses a route without
+  one). Closed vendors refuse or hedge on whole topics; the lane must still handle the worst message it receives.
+- **A judge is another vendor than the writer.** A model grading its own family rates its own habits.
+- **Declare classes, not names, in the agent's profile** (`modelClasses`): the policy and the binding narrow them, and
+  the host resolves the model. A hard-coded model name in code is a release to change it.
+
+## A starting choice
+
+As of 2026-10, all on OpenRouter, ordered from strongest to lightest. Prices and modalities change: read the catalog
+(`GET https://openrouter.ai/api/v1/models`, `architecture.input_modalities`, `pricing`) before you rely on them.
+
+| Model | Input | Good for |
+|---|---|---|
+| `xiaomi/mimo-v2.6-pro` | text, image, video, audio | an agent that plans and calls tools; replies to people; video and audio input |
+| `anthropic/claude-haiku-5.5` | text, image, file | code generated inside a product, internal tasks; test it on your users' topics before a reply lane |
+| `google/gemini-3.8-flash` | text, image, video, file, audio | audio and video input; costs more per token |
+| `qwen/qwen3.8-flash` | text, image, video | a fallback of another vendor for short answers |
+| `deepseek/deepseek-v4.1-flash` | text, image | classification, extraction, triage, periodic jobs, reading screenshots; always the newest `-flash`, never `-pro` |
+
+Embeddings, speech to text and text to speech are separate choices: keep the one measured on your data, and never
+change an embedding model without re-indexing every stored vector (search silently turns into noise).
+
+## Several kinds of input and output
+
+- **Input.** A model's name does not tell you what it reads: check `input_modalities` in the catalog. Send the medium
+  itself (an image, an audio clip) to a model that reads it, rather than a description another model wrote.
+- **A checker that cannot see a medium must not judge it.** A text-only judge refuses an audio or image candidate
+  instead of scoring its file name.
+- **Generated media** (images, video, voice, music, 3D) go through one media service that picks the provider, records
+  the cost and keeps the original, not through provider SDKs scattered across the agent. Check the input against the
+  provider's limits (media type, length, size) before a paid stage.
+- **Long documents** translated or rewritten in one call come back cut off without an error: send them in sections and
+  check that each section's end arrived.
+
+## Ids, budgets and deadlines
+
+- **Model ids are configuration**, read at start from one place; a changed default applies to new installs, and an
+  installed agent keeps its own until it is told.
+- **Set the default per job explicitly.** Never let the order of a catalog choose it.
+- **Reasoning spends the output budget.** With reasoning on and a tight `max_tokens`, a light model returns empty
+  content (`finish_reason: length`). Leave the budget generous, or turn reasoning off for short outputs where the
+  model allows it; some models refuse to turn it off.
+- **An empty answer is neither a refusal nor a success.** Retry with a larger budget or the fallback; never ship it.
+- **A fixed output budget must survive a verbose model**, and a deadline sized for one model times out another: count
+  partial and timed-out attempts per model before choosing either.
+- **A probe with `max_tokens: 1` proves routing and permission, not quality.**
+
+## OpenRouter: one key per agent
+
+- **Each agent spends its own key, with its own ceiling.** The key is minted for that agent (and that project) by the
+  estate's key manager, with a monthly limit; it is never pasted by a person into a file, a prompt or a command line.
+  Read it from the environment the service manager or the session gives the agent (Fabric Switchboard hands an agent
+  the key of the project it starts in).
+- **An organization's instance spends the organization's key** under its grant; a personal key never pays for an
+  organization's work.
+- **Check every attempt against the ceiling before it is sent,** retries included, estimating at the full output
+  budget; record the actual cost each call returns (`usage: {include: true}`).
+- **Show spend.** An agent's interface shows spend per day, per provider and per model for 30 days; spend nobody sees
+  is spend nobody controls.
+- **Unknown cost is `null`, never 0** (DEC-0087, `fabric-interop/0.2`).
+- **Attribution is off by default.** A product may send OpenRouter's attribution headers only with its operator's
+  setting and only for requests it originates (FAC-SEM-098); an agent a user built keeps the user's own.
+
+## Measuring a choice
+
+Choose a model on the agent's own real inputs, under its own key: a set of real cases (including the worst ones it
+will see), a score the code computes where it can, a judge of another vendor where it cannot, the date and the key
+scope recorded next to the default. Re-run it when you change the model, the prompt or the provider.
+
+## The checklist
+
+- Each lane: primary, fallback of another vendor, open-vendor where it reads user content, a declared class.
+- Each lane's input modalities checked in the catalog; media generation through one media service.
+- Budgets that survive reasoning; empty answers retried, never shipped.
+- One key per agent and context, read from the environment, with a ceiling checked before every call.
+- The choice measured on real inputs, recorded with its date.

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/references/orchestration-and-learning.md

@@ -0,0 +1,100 @@
+# Orchestration and learning: how the agent works, and how it gets better
+
+An agent is a loop: it takes work, plans, calls tools or other agents, stops for a person where it must, finishes or
+fails honestly, and learns from what happened. This page is the design of that loop. The agent's internal loop (tool
+calls, routing, memory, sub-agents) is designed in depth with `agent-orchestrator`, and its evals with `agent-evals`
+(agent-stack); this page is what a Fabric agent must get right whichever way it is built.
+
+Normative rules: the Fabric Agent Contract's `interop.md` (jobs, *Limits and uncertain effects*, DEC-0087),
+`pipeline.md` (`pipeline/0.1`), `memory-and-learning.md` (proposals, retrospectives, the loop guard) and
+`delegation.md` (grants and spend when one agent calls another).
+
+## Contents
+
+- [Workflow first, autonomy where it pays](#workflow-first-autonomy-where-it-pays)
+- [The work graph](#the-work-graph)
+- [Calling other agents](#calling-other-agents)
+- [Stops for a person](#stops-for-a-person)
+- [Learning loops](#learning-loops)
+- [The loop guard](#the-loop-guard)
+- [The checklist](#the-checklist)
+
+## Workflow first, autonomy where it pays
+
+If every step can be named, build a deterministic workflow behind the capability; let a model decide only where the
+input really varies (the intake grill's *Workflow or agent?*). An orchestrator is the part that owns the plan: it cuts
+work into steps, routes each to the cheapest lane that can do it (models-and-providers.md), runs independent steps in
+parallel, and is the only part that decides to retry, wait, ask a person or give up.
+
+## The work graph
+
+- **Every step is a durable job** with a stable id that survives a restart (`fabric-interop/0.1` jobs; the kit's
+  `JobStore`). A step's state lives on disk, not in a process's memory.
+- **Every step has an idempotency key derived from its intent**, never a clock or a random value
+  (`intent_idempotency_key({agentId, capability, input})`): a resend after a restart is the same request.
+- **Effects run once.** A step that pays, sends or publishes records its intent before the call and its observed
+  result after; when the answer was lost it ends `outcome-unknown` and is reconciled by observing, never re-run under
+  a new key.
+- **Limits are pauses, not failures.** A provider quota that will reset keeps the job `working` with
+  `quota-exhausted until <instant>`; one that needs a person ends `quota-exhausted` with `retryable: false`
+  (`jobs.pause`, `jobs.quota_exhausted`).
+- **The caller acts on each answer as `job_caller_action` says**: poll, wait until, answer a question, resend under the
+  same key, ask a person, reconcile. It never "submits anew".
+- **Count what is unknown.** A step whose cost, tokens or outcome nobody measured reports `null` and names it.
+
+## Calling other agents
+
+- Call another agent's capability through Fabric, never its keys or its database. Its spend is metered under the grant
+  you hold; a child call can only narrow scope, effects, data, deadline and depth, never widen them.
+- Hold a finite budget for the whole parent operation and allocate children within it; a child whose financial outcome
+  is unknown keeps its share reserved.
+- A child that is unavailable answers with an explicit denial; never fall back to a privileged account to get it done.
+- Record parent and child ids, so one operation can be followed end to end; refuse cycles.
+
+## Stops for a person
+
+- **Show who decides each stop.** The person's queue holds only the person's stops; an agent's own decisions are
+  recorded, not queued for approval.
+- **An approval holds the work, it does not refuse it.** Work above an approval line waits with its estimate and an
+  approval request, and resumes the moment it is granted.
+- **An agent never approves its own spend**, its own proposal, or its own acceptance checker.
+- **A promise of a person is a handoff.** If a reply says "a person will get back to you", the agent opens the handoff
+  that makes it true.
+- **Tell the person once per change.** A message to an operator goes out for a failure that lasts, for money, or for a
+  decision only they can make; one case once, the same case never repeated.
+
+## Learning loops
+
+An agent gets better only through loops that are recorded and checked, never by rewriting itself in place:
+
+1. **Record every decision with its reason**: the option chosen, the ones passed over, and why. This is what a review,
+   a retrospective and the next model read.
+2. **Keep one trace id per turn** with its model calls, tools, cost and outcome, stored where it outlives the
+   platform's own logs.
+3. **Turn every failure into a check before it is fixed**: a planted fixture with the exact defect, watched failing,
+   then the fix. A known defect not yet fixed is an expected-failure test that names its backlog row.
+4. **Replay the real history** through the current agent before calling a change right; evals hold the questions you
+   thought of, the history holds the ones users asked.
+5. **Propose, never self-approve.** A learning (goal, failed attempt, verified correction, cause, evidence, scope,
+   proposed change) is a proposal to the project's memory; a person or an independent check promotes it. It never
+   changes the running revision or its own checker (`memory-and-learning.md`).
+6. **Share what generalises.** A practice that held in two projects becomes a lesson other agents find (practices.md);
+   a practice in one project stays in its own knowledge pack.
+
+Memory is cited, bounded and scoped: a retrieval names the revisions it used, absence of a result is not proof of
+absence, and project memory never crosses into another context.
+
+## The loop guard
+
+Count entries per stage and hypothesis. A third entry into the same stage with the same hypothesis stops the step as
+`loop-guarded`; it resumes only with a changed hypothesis, dependency, plan or a person's decision. Switching the
+model, the runtime or the account does not reset a logic loop.
+
+## The checklist
+
+- Each step: a durable job, a key derived from its intent, its effect recorded before and observed after.
+- Limits paused or stopped with `quota-exhausted`; lost answers `outcome-unknown`; callers act as `job_caller_action`.
+- Child calls through Fabric, within the parent's budget and narrower grant.
+- The person's queue holds only their stops; no self-approval.
+- Decisions with reasons, one trace per turn, failures turned into fixtures, history replayed, learnings proposed.
+- A loop guard on every stage.

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

@@ -0,0 +1,103 @@
+# Practices that agents in production taught us
+
+Each rule below was learned from a measured failure of a real agent, and each names the check that now catches it.
+Read it before you design an agent's judge, model choice, spend or stops, and again before you call the agent
+finished. Organization members have the full page with every receipt: the PassionCode knowledge base,
+`knowledge/agent-practices.md` in fabric-workspace (add yours there, under its lease, by pull request).
+
+## Contents
+
+- [Judges and evals](#judges-and-evals)
+- [Numbers and data](#numbers-and-data)
+- [Money](#money)
+- [People in the loop](#people-in-the-loop)
+- [Reliability](#reliability)
+- [Shipping](#shipping)
+
+## Judges and evals
+
+- **A judge passes nothing until it has failed planted bad output.** Write fixtures with known defects (an invented
+  fact, a missing citation, a wrong number) and watch the judge fail each one. Check: a fixture suite that must fail.
+- **Code-proven defects veto the model's score.** What a program can prove (a citation id missing from the sources, a
+  quote not found in its source) fails the output whatever the model judge said.
+- **The judge is another vendor than the writer.**
+- **In-sample fixtures prove the checks, not the calibration.** Calibrate a judge on cases it was not written with.
+- **A checker reads what the drafter read**, with the time of each input; a checker that sees newer data than the
+  drafter marks correct answers wrong.
+- **A close score is not a verdict.** Scores drift run to run even at temperature 0; set the pass line with a margin
+  measured on repeated runs.
+- **A judge that cannot answer is an error, not a pass**, and a verdict missing a required field is no verdict; never
+  fill it with a default.
+- **A judge that cannot see a medium refuses it.**
+- **A judge without the agent's material must not judge facts**: it calls real features invented.
+- **Read a sample of a new judge's failures before reporting its rates.**
+- **A model judge not yet calibrated speaks as advice beside the verdict**, and its misses raise no alert until a person
+  has calibrated that check.
+- **A green full suite is not certification.** Before a release, independent readers take the diff (the unit, what
+  reaches it, what the docs and users see).
+- **Watch a new negative assertion fail before you trust it**: remove the fix, run the test, keep the failing run.
+- **Replay the real history before calling it right.**
+
+## Numbers and data
+
+- **What was not measured is "not measured", never 0.** Payloads name their unmeasured fields; a missing number is
+  `null`.
+- **The answering model states numbers from the facts; it never works them out.** Totals, savings and percentages are
+  computed by code and handed to the model.
+- **The producer's schema is the consumer's test fixture, pinned to a commit.**
+- **Over an open vocabulary, list what may stand, never what may not.** A deny-list over free text misses the next
+  variant.
+- **Re-pin a golden output only with the measured diff.**
+- **Budget a checker's context from what the runner really sends**, and a context budget that drops content says what
+  it dropped.
+- **Deleting a source item removes it from every stored derived artifact** (reports, summaries, caches).
+
+## Money
+
+- **Check every attempt against the cap before it is sent, retries included.**
+- **Each agent spends its own key, with its own ceiling**; never another agent's key, never a person's personal key for
+  an organization's work.
+- **Spend that is not shown is spend nobody controls.**
+- **A recorded status is not proof of payment**: act on money only after the payment provider or the chain confirms it.
+- **The paid call sends exactly the spec its recorded intent names.**
+- **A test run never holds a route to a paid key** unless the test hands it one.
+- **An agent cannot approve its own spend.**
+
+## People in the loop
+
+- **Count what a channel to a person actually sends** before trusting its rules; a notifier that sends a hundred
+  messages a day is ignored.
+- **Show who decides each stop**, and keep the person's queue to the person's stops.
+- **An approval holds the work; it does not refuse it.**
+- **Record every agent decision with its reason.**
+- **A fallback sent instead of a rejected reply must stand alone**, and never append a fixed text in one language to a
+  reply in another.
+- **An answer that promises a person is a handoff, or nobody comes.**
+- **A watcher gives the agent its own latency before it calls a person.**
+- **A pause a person makes survives the agent's own sync.**
+- **Response-time targets are per channel**: a private chat in seconds, mail in hours, store reviews in a day.
+- **Text for people carries no em dash (U+2014)**, held by the prompt and a test (resilience-and-autonomy.md).
+
+## Reliability
+
+- **One empty answer is evidence of absence, not a broken run**; an empty answer from a free provider hands the request
+  to the next provider.
+- **Check inputs against the provider's contract before a paid stage.**
+- **A step sent back for a fix continues its own session.**
+- **Health names output that should have reached a person and has not.**
+- **Every start sweeps the liveness markers of processes that are gone.**
+- **A shared run gate holds its lock for the whole command**, never check-then-release.
+- **Never source a service's env file in a shell.**
+- **A log sink never fails a call.**
+- **Parallelism is tested by counting overlapping work, not by the clock.**
+- **A reply agent never sends the same reply twice in a row.**
+- **Do not trust a hosted CI schedule to start; wake the workflow by a push**, and check that it ran.
+
+## Shipping
+
+- **A release smoke goes through the code the change touched**, not a version flag.
+- **A deploy is accepted on the bytes it serves**, hashed against the build, not on the deploy command's exit.
+- **Measure a size budget on a build from the commit you ship.**
+- **A changed default model is not a changed installed agent.**
+- **Start a long verification suite only above a disk floor.**
+- **Agents that number rows in one register need a gate that fails on a duplicate id.**

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

@@ -0,0 +1,112 @@
+# Where an agent runs: this machine, a personal cloud, an organization
+
+An agent built with this skill can run on the person's own machine, in their personal cloud, or in an organization's
+cloud, and the same agent can serve the person and several organizations at once. Decide where it runs at the intake
+grill (*Where does it run?*), because it decides where its secrets live, who pays for its calls, whose journal records
+it, and what happens when the person's laptop is closed.
+
+The normative rules are the Fabric Agent Contract's, at the commit this plugin pins: `docs/specification/contexts.md`
+(contexts), `estate-record.md` (machines and placements), `share-registration.md` (sharing into an organization),
+`entitlement.md` (what an order entitles), `ceremonies.md` (adding a machine). This page says how to design for them.
+
+## Contents
+
+- [The places](#the-places)
+- [Contexts: one agent, the person and each organization](#contexts-one-agent-the-person-and-each-organization)
+- [Connecting a machine or a cloud to the estate](#connecting-a-machine-or-a-cloud-to-the-estate)
+- [Sharing an agent into an organization](#sharing-an-agent-into-an-organization)
+- [Running while the laptop is closed](#running-while-the-laptop-is-closed)
+- [Selling an agent](#selling-an-agent)
+- [The checklist](#the-checklist)
+
+## The places
+
+| Where | What it is | Typical agent |
+|---|---|---|
+| **This machine** | the person's computer, Fabric and its services local; free and open source | a coding helper, a personal assistant that may stop when the laptop sleeps |
+| **Personal cloud** | the person's own always-on machine in PassionCode's cloud (or the same stack self-hosted), one more machine of their estate | an agent that answers mail at night, a scheduled digest, a bot |
+| **Organization** | the organization's cloud, its members' machines enrolled into it, its own server holding members, grants and usage | a support agent, an internal analyst, an agent the organization bought |
+| **Enterprise** | an organization's dedicated cloud with personal onboarding | the same agents under the enterprise's own boundary |
+
+Every step up is paid as cloud only: the person or the organization pays for the cloud its agents run in, and the
+order says which hosting it holds (`personal-cloud`, `org-cloud`, `enterprise-cloud` in `entitlement/1`). An agent never
+checks a price; it may read whether its context's entitlement is current and degrade honestly when it is not.
+
+## Contexts: one agent, the person and each organization
+
+A context is `personal` or `org:<orgId>`, compared exactly as written. Design every agent as if it will run in more
+than one:
+
+- **One instance per context.** On a machine an agent runs once per (agent, context). The personal instance and an
+  organization's instance are two instances with two state folders, two journals and two sets of secrets; never one
+  process that switches. In the estate record a placement names its `context`, and an organization's placement names
+  the share grant it runs under (FAC-SEM-074, FAC-SEM-111).
+- **Secrets stay in their context.** An organization's instance fills its secret slots from the organization's own
+  machine and vault; a personal secret never reaches it, and the person's personal keys never pay for organization
+  work.
+- **Spend and usage stay in their context.** Every call is metered under the grant it runs under; the organization
+  sees its instance's usage (`grant.usage`) and nothing of the person's personal work.
+- **Contexts are never linked.** Nothing the agent sends to one organization names the person's personal context or
+  another organization: no shared ids, no shared logs, no "also used by" field.
+- **Access is the grant, not a label.** What an organization's instance may do is its grant's capabilities, effect
+  ceiling, data classes, spend windows and expiry. A named level ("read only") is a preset that fills those fields.
+
+## Connecting a machine or a cloud to the estate
+
+A person's machines form their estate; an estate record signed with the person's passkey lists every machine, its
+keys, and what runs where. A new machine joins only when a passkey-signed revision lists it:
+
+- **Nearby** (a laptop, a phone): the two machines show the same six-digit comparison code; the person confirms it.
+- **Headless** (a cloud machine, a server): Fabric issues an `enroll-token/1`, valid for at most 15 minutes and one use.
+  The machine reads it from stdin or a file only its user can read, never from a command-line argument, a URL or a
+  log, proves its key with it, and waits until the revision that lists it is signed. The token gives no trust by
+  itself. The kit's `fabric_ceremonies.py` checks a token (building-fabric-services, *The estate ceremonies*).
+- **An organization's machine** enrolls into the organization's server: a device certificate names the organization
+  (`org.id`), and the machine's collector routes each context's events only to the server of that context.
+
+Removing a machine or replacing its key is a revision that revokes what it drops in the same revision (FAC-SEM-114).
+An agent service that applies the estate record verifies each revision with its parent before trusting it.
+
+## Sharing an agent into an organization
+
+The person's own agent can work for an organization without being copied into it:
+
+1. Fabric writes a **share grant** into the organization: `context: org:<orgId>`, id `urn:fabric:share:` and 32 random
+   hex digits, one agent (`agentRef`) for its whole life, a window, the capabilities and spend the organization may
+   use. Moving the share to another agent revokes the grant and mints a new id.
+2. The person's node sends the organization a **share registration**, so its server knows which agent the grant runs.
+3. The instance placed in that context runs under the grant; its daily `grant.usage` goes to the organization's
+   server, carrying the grant's own context.
+
+The kit checks the grant and the usage event (`fabric_share.py`). Revoking the grant stops calls at once where they are
+checked, and removes the instance from the next revision.
+
+## Running while the laptop is closed
+
+A cloud agent keeps working with the laptop closed only if everything it needs is in the cloud: its worker, its
+secrets, its data, and a hub that can admit calls. The local Fabric hub is not a cloud hub. Design for it:
+
+- Declare what each capability needs and where it is; a capability that needs the person's machine reports
+  `pending` or `unavailable` instead of pretending, and queues within a deadline or declines.
+- Never charge for work it cannot deliver on the promised terms.
+- A test that passed on fixtures says nothing about uptime; measure the installed agent in its cloud.
+
+## Selling an agent
+
+- **A paid agent** runs in PassionCode's cloud inside its developer's organization (`org:<developer>`); each customer
+  organization reaches it through its own credential, which is the credential of an external grant, metered per
+  customer. The developer sets the price; the platform earns the cloud.
+- **A partner** builds agents for a company and delivers them as a setup: each agent its own signed package, and one
+  organization skill set that requires them, all signed with the partner's key (building-fabric-services, *package*,
+  *A partner's setup for a company*). The company pays for the cloud; the partner's own work is between them.
+- Whatever is sold: one signed `fabric-package/1` per version, no secret in it, every effect declared, and the agent's
+  spend under the customer's grant, never under the developer's personal key.
+
+## The checklist
+
+- Where does each instance run, and in which context? Write it in the knowledge pack.
+- Does any state, secret, log line or cache key cross contexts? It must not.
+- Which capabilities need the person's machine, and what do they answer when it is off?
+- 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
+  their parent.

package/plugins/fabric-agent-adapter/skills/working-with-fabric/SKILL.md

@@ -19,7 +19,7 @@ compatibility: >-
   this plugin; Codex/Kimi use command hooks; Hermes/OpenCode/OpenClaw/Pi use native context plugins after opt-in.
 metadata:
   author: PassionCode.ai
-  version: "0.36.0"
+  version: "0.37.0"
 ---
 
 # Working with Fabric

package/plugins/fabric-agent-adapter/skills/working-with-fabric/scripts/fabric_session.py

@@ -66,7 +66,7 @@ WATCH_MAX_BACKOFF_S = 900
 SESSION_ID = re.compile(r"[A-Za-z0-9._:-]{1,128}")
 LOOPBACK_ORIGIN = re.compile(r"http://127\.0\.0\.1:(\d{1,5})")
 LOCAL_ORIGIN = re.compile(r'"origin": "http://(?:127\.0\.0\.1|localhost)')
-VERSION = "0.36.0"
+VERSION = "0.37.0"
 HOSTS = {"claude": "Claude Code", "codex": "Codex", "kimi": "Kimi Code",
          "hermes": "Hermes", "opencode": "OpenCode", "openclaw": "OpenClaw", "pi": "Pi"}
 NATIVE_PLUGIN_HOSTS = frozenset(("hermes", "opencode", "openclaw", "pi"))