@rubytech/create-realagent-code 0.1.257 → 0.1.259

package/dist/__tests__/installer-settings-permissions.test.js

@@ -1,8 +1,12 @@
-// Task 583 — Installer must seed permissions.defaultMode=bypassPermissions
-// and permissions.allow=["*"] into the brand-scoped settings.json so
-// claude.ai/code sessions never fall through to the Anthropic remote
-// auto-classifier. Existing top-level keys must be preserved; an
-// already-correct file must be a true no-op (mtime unchanged).
+// Task 583 / Task 664 — Installer must seed permissions.defaultMode=
+// bypassPermissions and permissions.allow=[] into the brand-scoped
+// settings.json so claude.ai/code sessions never fall through to the
+// Anthropic remote auto-classifier. bypassPermissions alone carries the
+// Stage-1 short-circuit; the old wildcard allow=["*"] was redundant and is
+// rejected by Claude Code >= 2.1.167 (blocking Settings Warning that halts
+// the rc-spawn bind — Task 664). Existing top-level keys must be preserved;
+// an already-correct file must be a true no-op (mtime unchanged); a
+// "*"-bearing file must be rewritten on upgrade.
 import test from "node:test";
 import assert from "node:assert/strict";
 import { mkdtempSync, readFileSync, writeFileSync, statSync, rmSync } from "node:fs";
@@ -19,7 +23,7 @@ test("empty target: creates settings.json with the permissions block", () => {
         assert.equal(result.action, "seeded");
         assert.equal(result.path, join(dir, "settings.json"));
         const parsed = JSON.parse(readFileSync(result.path, "utf-8"));
-        assert.deepEqual(parsed, { permissions: { defaultMode: "bypassPermissions", allow: ["*"], deny: [] } });
+        assert.deepEqual(parsed, { permissions: { defaultMode: "bypassPermissions", allow: [], deny: [] } });
         assert.equal(assertBypassPermissionsSeed(dir).status, "ok");
     }
     finally {
@@ -46,7 +50,7 @@ test("existing keys preserved verbatim; permissions added", () => {
         assert.equal(parsed.inputNeededNotifEnabled, false);
         assert.equal(parsed.agentPushNotifEnabled, false);
         assert.equal(parsed.model, "opus");
-        assert.deepEqual(parsed.permissions, { defaultMode: "bypassPermissions", allow: ["*"], deny: [] });
+        assert.deepEqual(parsed.permissions, { defaultMode: "bypassPermissions", allow: [], deny: [] });
         assert.equal(assertBypassPermissionsSeed(dir).status, "ok");
     }
     finally {
@@ -57,7 +61,7 @@ test("idempotent: already-correct block triggers no write", () => {
     const dir = freshDir();
     try {
         const settingsPath = join(dir, "settings.json");
-        writeFileSync(settingsPath, JSON.stringify({ model: "opus", permissions: { defaultMode: "bypassPermissions", allow: ["*"], deny: [] } }, null, 2));
+        writeFileSync(settingsPath, JSON.stringify({ model: "opus", permissions: { defaultMode: "bypassPermissions", allow: [], deny: [] } }, null, 2));
         const before = statSync(settingsPath).mtimeMs;
         // Small busy-wait so a same-millisecond write would be detectable on
         // filesystems with millisecond mtime granularity.
@@ -106,7 +110,33 @@ test("assert: partial block (no wildcard) reports missing", () => {
 });
 test("BYPASS_PERMISSIONS_BLOCK frozen literal matches expected shape", () => {
     assert.equal(BYPASS_PERMISSIONS_BLOCK.defaultMode, "bypassPermissions");
-    assert.deepEqual([...BYPASS_PERMISSIONS_BLOCK.allow], ["*"]);
+    assert.deepEqual([...BYPASS_PERMISSIONS_BLOCK.allow], []);
     assert.deepEqual([...BYPASS_PERMISSIONS_BLOCK.deny], []);
     assert.ok(Object.isFrozen(BYPASS_PERMISSIONS_BLOCK));
 });
+test("assert: wildcard allow reports missing (forces rewrite on upgrade)", () => {
+    const dir = freshDir();
+    try {
+        writeFileSync(join(dir, "settings.json"), JSON.stringify({ permissions: { defaultMode: "bypassPermissions", allow: ["*"], deny: [] } }));
+        assert.equal(assertBypassPermissionsSeed(dir).status, "missing");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test("seeding over a wildcard-bearing file rewrites allow to [] preserving other keys", () => {
+    const dir = freshDir();
+    try {
+        const p = join(dir, "settings.json");
+        writeFileSync(p, JSON.stringify({ model: "opus", permissions: { defaultMode: "bypassPermissions", allow: ["*"], deny: [] } }));
+        const result = seedBypassPermissionsSettings(dir);
+        assert.equal(result.action, "seeded");
+        const parsed = JSON.parse(readFileSync(p, "utf-8"));
+        assert.equal(parsed.model, "opus");
+        assert.deepEqual(parsed.permissions, { defaultMode: "bypassPermissions", allow: [], deny: [] });
+        assert.equal(assertBypassPermissionsSeed(dir).status, "ok");
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

package/dist/permissions-seed.js

@@ -1,9 +1,17 @@
-// Task 583 — Seed Claude Code's two-stage permission classifier with a
-// wildcard allow so claude.ai/code sessions never fall through to the
-// Anthropic remote auto-classifier. The classifier routes `Agent`/`Task`
-// to `ask`, which surfaces as a permission prompt that an unattended
-// operator never clicks — observed as 4-minute dead-air hangs on
-// realagent-code.
+// Task 583 / Task 664 — Seed Claude Code's permission block so claude.ai/code
+// sessions never fall through to the Anthropic remote auto-classifier. The
+// classifier routes `Agent`/`Task` to `ask`, which surfaces as a permission
+// prompt that an unattended operator never clicks — observed as 4-minute
+// dead-air hangs on realagent-code.
+//
+// `defaultMode: "bypassPermissions"` is the load-bearing key: it resolves to
+// skip_all_permission_checks before any allow/deny matching, short-circuiting
+// Stage 1 for every tool. The Task 583 belt-and-suspenders `allow: ["*"]` was
+// redundant and is now actively rejected by Claude Code >= 2.1.167: `"*"` is
+// not a legal allow token, so the CLI renders a blocking "Settings Warning"
+// screen that, under `--remote-control` in a PTY, no operator dismisses — the
+// stdout bind banner never prints and every rc-spawn times out (Task 664).
+// The allow array is therefore empty and MUST stay "*"-free.
 //
 // This module is the single writer for the brand-scoped settings.json
 // permissions block. Account-scoped settings.json is written by
@@ -12,7 +20,7 @@ import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from "
 import { join, dirname } from "node:path";
 export const BYPASS_PERMISSIONS_BLOCK = Object.freeze({
     defaultMode: "bypassPermissions",
-    allow: ["*"],
+    allow: [],
     deny: [],
 });
 function isAlreadyCorrect(permissions) {
@@ -21,7 +29,9 @@ function isAlreadyCorrect(permissions) {
     const p = permissions;
     if (p.defaultMode !== "bypassPermissions")
         return false;
-    if (!Array.isArray(p.allow) || !p.allow.includes("*"))
+    // Require an empty allow array. A "*"-bearing file (the pre-664 seed) is no
+    // longer correct, so this returns false and forces a rewrite on upgrade.
+    if (!Array.isArray(p.allow) || p.allow.length !== 0)
         return false;
     if (!Array.isArray(p.deny) || p.deny.length !== 0)
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-realagent-code",
-  "version": "0.1.257",
+  "version": "0.1.259",
   "description": "Install Real Agent — Built for agents. By agents.",
   "bin": {
     "create-realagent-code": "./dist/index.js"

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Real Agent ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:0c253f3a1c9946f4256daea47978fa363b3a6eef6875b4a417792393c4fc00e9
+content-hash: sha256:d73292d40056e98b2483ca095571c47e72f896e24c979cb40c60b6d99d3335ef
 brand: realagent-code
 product-name: Real Agent
 ---
@@ -302,7 +302,7 @@ If you suspect background processes are piling up, run `grep '\[reaper\]' ~/.{br
 
 ## Tool Permissions
 
-Every install seeds a wildcard `permissions.allow:["*"]` plus `defaultMode:"bypassPermissions"` into both the brand-scoped settings file (`~/.{brand}/.claude/settings.json`) and every account-scoped one (`<install>/data/accounts/<id>/.claude/settings.json`). This stops Claude Code from sending tool calls to its remote auto-classifier, which would otherwise surface a permission prompt in the chat that an unattended session never answers. What each subagent is allowed to use is still controlled by the `tools:` line in its agent file, not by a top-level allowlist. To verify after an install: `cat ~/.{brand}/.claude/settings.json | jq '.permissions'`.
+Every install seeds `permissions.allow:[]` plus `defaultMode:"bypassPermissions"` into both the brand-scoped settings file (`~/.{brand}/.claude/settings.json`) and every account-scoped one (`<install>/data/accounts/<id>/.claude/settings.json`). `bypassPermissions` alone stops Claude Code from sending tool calls to its remote auto-classifier (it skips all permission checks), which would otherwise surface a permission prompt in the chat that an unattended session never answers. The `allow` array stays empty and **must never contain `"*"`**: Claude Code ≥ 2.1.167 rejects `"*"` as an allow token and renders a blocking Settings Warning that, under `--remote-control`, stops every `/rc-spawn` from binding (Task 664). What each subagent is allowed to use is still controlled by the `tools:` line in its agent file, not by a top-level allowlist. To verify after an install: `cat ~/.{brand}/.claude/settings.json | jq '.permissions'` (expect `allow: []`). To repair an install seeded before Task 664: `bash <install>/platform/scripts/backfill-bypass-permissions.sh ~/.{brand}`.
 
 ---
 # Plugins Guide

package/payload/platform/plugins/business-assistant/PLUGIN.md

@@ -54,7 +54,10 @@ Load the relevant reference when the task requires it:
 
 - **Triage & escalation** → `references/escalation.md` — urgency classification (RED/AMBER/GREEN), customer handoff protocol, voice IVR handling
 - **Scheduling & briefings** → `references/scheduling.md` — booking protocol, geographic clustering, travel time estimation, morning briefings, holiday mode, GPS integration
-- **Quotes** → `references/quoting.md` — photo-to-quote, formatting, follow-up timings
+- **Quotes (lightweight)** → `references/quoting.md` — photo-to-quote, formatting, follow-up timings
+- **Pricing method** → invoke the `pricing-method` skill (via the Skill tool) to build, edit, re-learn, or verify an operator's own pricing method — the items, quantity rules, pricing rules, and roll-up the quote flow consumes
+- **Priced quote compute** → `references/quote-engine.md` — generate & run the owner's bespoke pricing engine (measured/counted work → priced result), domain-agnostic compute contract
+- **Quote generation (engine-driven outputs)** → `references/quote-generation.md` — the output contract for a priced job: internal margin-bearing view + client breakdown + client quote, each reconciling to one engine total and rendered to PDF
 - **Invoices & payment** → `references/invoicing.md` — HTML invoice creation, PDF generation via `browser-navigate` + `browser-pdf-save`, sending, payment chase protocol
 - **Customer records** → `references/crm.md` — contact record management, `contact_lookup`/`contact_update` usage, pipeline tracking, when to create/update records
 - **Document filing** → `references/document-management.md` — dual-scope filing system, naming conventions, folder structure for customer-facing vs internal documents

package/payload/platform/plugins/business-assistant/references/quote-engine.md

@@ -0,0 +1,122 @@
+# Priced-quote compute engine
+
+This reference is the **compute core** for a structured, priced quote: it turns a job (the items the
+owner selected, with their measurements or counts) into priced figures — line prices, group
+subtotals, and a final total — computed by **this owner's own pricing method**.
+
+It carries no items, no units, no rates, no margins, no overheads, no taxes, and no roll-up sequence.
+Every such value and rule is the owner's, captured as data. A trade pricing by the square metre, a
+caterer pricing by the head, and a printer pricing by per-unit break are all priced by the same
+approach — only their captured method differs.
+
+The compute engine itself is **not shipped**. You generate a small bespoke engine for this owner the
+first time they need a priced quote, and regenerate it whenever their business changes. The captured
+method is data the engine reads. Both persist in the owner's workspace and are re-run on demand.
+
+## When this path applies
+
+Use this for a **priced quote computed from the owner's method** — measured or counted work that has
+to be priced the way this owner prices it, then totalled. This is distinct from the simple
+photo-to-quote / chat-to-quote flow in `references/quoting.md`, which formats a quote the owner has
+already priced. If the owner has already worked out the numbers, stay in `quoting.md`. Come here when
+the numbers have to be **computed**.
+
+**Precondition:** a captured method for this owner must exist. Its *content* (the owner's items,
+rules, dials, roll-up, and past-job fixtures) is produced and maintained by the method-capture flow —
+Task 659 — which populates the method/job shape **this reference defines** below. If no captured method
+exists, capture it first; do not invent rates or rules here.
+
+## Where the engine and method live
+
+The agent runs in the owner's workspace (the spawn cwd, `$ACCOUNT_DIR`). Keep the engine and the
+captured method together under a `quoting/` subdirectory there, addressed by relative path:
+
+- the **method** — the owner's items, dials, and roll-up, as data;
+- the **engine** — the bespoke script that reads a method and a job and prices it;
+- the owner's **past jobs**, each with the figures they actually issued, used to verify the engine.
+
+These persist across sessions, are edited when the business changes, and are the engine's only inputs.
+Nothing about the owner's business lives in this reference or in the plugin.
+
+## The method shape (owner data)
+
+This section is the authoritative definition of the method/job shape; the method-capture flow (Task
+659) fills it with one owner's content. The method describes how this owner prices. For each
+**priceable item** it records:
+
+- what the item is (an identifier, a human label, a unit);
+- **how a quantity arises** — the item's own rule for turning a measurement into a quantity (for
+  example, an area from supplied dimensions, a length, a volume), or that the item carries **no
+  measurement rule** because it is counted or taken as a single unit. This is the item's *default*
+  quantity rule; a quantity entered on the job line always overrides it (see the job shape);
+- **how a line price is computed** — the owner's own rule for that item, in whatever form their
+  history shows it takes;
+- which **group** the line rolls into (the owner's own section headings);
+- whether the item is **standing-rule priced** (a rule fixes its price) or **judgement priced** (the
+  owner sets the price per job) — so the quote flow knows when it must ask the owner for a figure
+  rather than computing one.
+
+Alongside the items the method holds:
+
+- named **dials** — the owner's own scalars that their rules reference (a labour day-rate, a margin
+  multiplier, a percentage — whatever their method uses, named by them);
+- the **roll-up** — an ordered list of steps applied above the line items to reach the final total.
+  Each step names its rule, the prior figures it reads, and the label of the figure it produces. This
+  is whatever sequence the owner actually applies. It is **not** a fixed margin-then-overhead-then-tax
+  chain: an owner may apply an overhead, a contingency, a discount, a tax, or nothing, in their own
+  order. The engine implements exactly the step kinds this owner's roll-up uses, and no others.
+
+## The job shape (per quote)
+
+A job is the work selected for one quote: a list of lines, each naming an item and supplying **either**
+measurements **or** a directly-entered quantity, plus — for a judgement-priced item — the price the
+owner set for this line. The quantity source is decided per line by precedence: a quantity entered on
+the line is used as-is; otherwise the engine derives the quantity from the line's measurements via the
+item's measurement rule. An item with no measurement rule therefore requires an entered quantity (or
+its single-unit default). The job also carries the header the issued quote needs (who it is for, the
+address, the reference).
+
+## What the generated engine must do
+
+The engine reads one method and one job and produces the priced result. It must:
+
+1. **Resolve each line's quantity** — an entered quantity takes precedence; otherwise derive it from
+   the line's measurements via the item's measurement rule — and record which source was used.
+2. **Resolve each line's price** — by the item's own rule, or by the per-line figure the owner gave for
+   a judgement item — and record which was used.
+3. **Group** the priced lines under the owner's own headings.
+4. **Run the roll-up** steps in their defined order to reach the final total.
+5. **Emit observability** so a wrong figure is diagnosable from the log, not just the document: per
+   line, the resolved quantity and its source (measurement-derived vs entered) and the price rule
+   applied and its source (item rule vs per-line override); and each roll-up step with its result.
+6. **Reconcile** the sum of the group subtotals against the running line-item total and report it as an
+   explicit pass/fail — not a silent assumption.
+7. **Verify** on demand: given one of the owner's own past jobs, compare every computed figure
+   (line, group, final) against the figures the owner actually issued and report each as a match or
+   a mismatch.
+
+## Expressiveness — bounded by the owner's history
+
+Build the engine to support **exactly** the quantity, pricing, and roll-up forms the owner's own
+history exercises — discovered when their method was captured. Do not add quantity bases, price-rule
+forms, or roll-up step kinds the owner does not use. Unused generality is a liability: it is untested
+against their figures and invites a wrong quote later. If a new job needs a form the method has never
+expressed, that is a change to the captured method (and a re-verification), not a guess made here.
+
+## Acceptance — reproduction of the owner's own figures
+
+The engine is correct only when it **reproduces the owner's own past jobs** — line prices, group
+subtotals, and final totals — to the owner's own precision. The fixtures are that owner's
+history, supplied with their method; there are no built-in figures to test against. Reproducing their
+history, not parsing cleanly, is the signal that the engine prices the way they do. Verify on every
+generate and every method change; a reproduction failure blocks issuing a computed quote.
+
+## Boundaries
+
+- **Capturing and maintaining** the content of the method (items, rules, dials, roll-up, past-job
+  fixtures) is the method-capture flow — Task 659; it populates the shape this reference defines. This
+  reference consumes that method; it does not build it.
+- **Rendering** the priced result into the documents the owner issues (internal view, client
+  breakdown, branded quote) is Task 658. Those documents are printed to PDF through the existing
+  `browser-pdf-save` path (see `references/invoicing.md`); this compute reference produces only the
+  figures, not the documents.

package/payload/platform/plugins/business-assistant/references/quote-generation.md

@@ -0,0 +1,94 @@
+# Quote generation — output contract
+
+This is the **output half** of the engine-driven quote path. The engine (the operator's captured
+pricing method applied to a job) produces the figures; this contract turns those figures into the
+documents the operator issues, each rendered to PDF.
+
+It holds **no** business content. There are no fixed section names, no fixed wording, no fixed brand,
+and no fixed page layout here. What each document contains and how it looks is the operator's, held
+as their own data (their headings, their narrative, their charts, their logo, colours, contact and
+terms, their page size). The same contract serves any trade or service business by reading that
+operator's own document definitions.
+
+This is distinct from the lightweight WhatsApp quote in `references/quoting.md`. Use that one for a
+quick text quote. Use this one when the operator prices a job from a captured method and issues a set
+of reconciling documents.
+
+## What the engine hands you
+
+You render from the engine result. Read it as:
+
+- an ordered set of priced **groups** (the operator's own stages or categories);
+- each group an ordered set of **lines**; each line carries its quantity and the quantity's source
+  (measurement-derived or entered), its unit, its rate, its cost, and its sell;
+- each group's **subtotal**;
+- the operator's named **roll-up** steps — whatever sequence of adjustments and taxes they apply
+  above the line items, in order;
+- the **totals**: the client-visible subtotal and the final total.
+
+The engine guarantees the reconciliation invariant: the group subtotals carried through the roll-up
+equal the final total. You never recompute these figures — you display them.
+
+The engine itself, and how a line's quantity, rate, cost and sell are derived, are out of scope here
+(that is the compute core). This contract only reads the result.
+
+## The three documents
+
+The operator defines the content and styling of each; the **roles** are fixed, the **contents** are
+not. A document is **engine-driven**: a section or line appears **only where the job priced it**.
+
+| Role | Shows | Withholds | Filing scope |
+|---|---|---|---|
+| **Internal margin-bearing view** | every line's quantity and its source, unit, rate, cost and sell; each group subtotal; the full roll-up; the totals | nothing — this is the operator's own check on profitability before issuing | **admin-only** |
+| **Client breakdown** | how the price is composed, at the granularity the operator chooses: the client-facing amount per group or line, the roll-up steps the client sees, and the headline figure | any cost, margin, or internal rate figure (the operator's own unit rate, not a client-facing per-unit price) | client-facing (shared) |
+| **Client quote document** | the issued document in the operator's brand: their cover, their narrative or schedule, the client breakdown, the headline price, the acceptance block, and their standing terms | any cost, margin, or internal rate figure (the operator's own unit rate, not a client-facing per-unit price) | client-facing (shared) |
+
+The internal view exists so the operator can confirm the job is profitable before it goes out; it may
+expose cost and margin freely. The two client documents **never** surface a cost, margin, or
+internal-rate figure. A column or line that shows the price to the client is fine; a figure that
+reveals what the work cost the operator, or the markup applied, is a leak.
+
+### The margin boundary is the filing scope
+
+The leak boundary is structural, not a matter of remembering to omit a column. File each document by
+its scope, exactly as `references/document-management.md` defines:
+
+- the **internal margin-bearing view** goes to the **admin-only** customer folder
+  (`memory/admin/customers/{phone}/`), which the customer never receives;
+- the **client breakdown** and the **client quote** go to the customer-facing documents folder
+  (`memory/users/{phone}/documents/`).
+
+A document that carries cost or margin must never be written to the shared scope.
+
+## Print fidelity
+
+Each document becomes a PDF through the device's Chromium print pipeline, so the HTML must survive
+that pipeline. Start from the A4 print conventions already in `references/invoicing.md` and
+`references/document-management.md` — an `@page` size directive, `@media print` styles, and
+`page-break-inside: avoid` on blocks that must not split — and keep the operator's own page size on
+`@page` (their stationery may not be A4).
+
+A multi-page issued quote needs two things beyond what those siblings show; state them explicitly in
+the document:
+
+- page-level chrome — a running header or footer and page numbers — via `@page` margin boxes, never
+  absolutely-positioned elements that drift across pages;
+- `print-color-adjust: exact` on coloured fills, so the operator's brand fills survive print. The
+  renderer prints backgrounds, but make the intent explicit rather than relying on the default.
+
+## Producing the PDF
+
+Render the document as self-contained HTML (styles inline, images by absolute local path), then use
+the same path as every other business-assistant document:
+
+1. write the HTML to the document's filing-scope path;
+2. `browser-navigate` to it via a `file://` absolute URL;
+3. `browser-pdf-save` to an absolute `.pdf` path alongside the HTML;
+4. confirm a non-zero byte count from the `Saved PDF to <path> (<bytes>)` line before treating the PDF
+   as done.
+
+## Before you hand anything to the PDF tool
+
+Log, for the run: which document roles were produced, each one's page count, and the reconciliation —
+each document's displayed total against the engine total. If a document's total does not reconcile to
+the engine total, fail loudly and stop. Never ship a document whose figures disagree with the engine.

package/payload/platform/plugins/business-assistant/references/quoting.md

@@ -1,5 +1,20 @@
 # Quoting
 
+This reference is the **lightweight** quote path: read a handwritten or spoken quote, format it
+cleanly, and send it as a WhatsApp message (or a one-off PDF on request).
+
+When the operator prices a job from a captured pricing method and issues a set of documents that must
+reconcile to one engine total — an internal margin-bearing view, a client breakdown that withholds
+cost and margin, and a branded client quote — use `references/quote-generation.md` instead.
+
+## Where the operator's pricing comes from
+
+The operator's priceable items, quantity rules, pricing rules, and roll-up are not held here. They are
+captured and maintained by the `pricing-method` skill (invoke it via the Skill tool — see PLUGIN.md).
+That skill is the single source of the operator's own method; the quote flow consumes it. Because the
+method records which items are priced by a standing rule and which by per-job judgement, the quote flow
+applies the standing-rule items itself and asks the operator only about the judgement-priced lines.
+
 ## Photo-to-Quote (Handwritten)
 
 1. Business owner sends a photo of their handwritten quote
@@ -22,6 +37,20 @@
 2. Format as above
 3. Confirm and send
 
+## Priced Quote (Computed from the Operator's Method)
+
+The two flows above format a quote the owner has **already priced** — they read the figures off a photo
+or out of a conversation. When the numbers instead have to be **computed** from the owner's own pricing
+method — measured or counted work priced item by item and rolled up to a total the way this owner
+prices — use `references/quote-engine.md`.
+
+That reference is the compute core: it generates a bespoke pricing engine from the owner's captured
+method and runs it on the job to produce line prices, group subtotals, and the final total,
+with an observability log and a check against the owner's own past quotes. It carries none of the
+owner's items, rates, or rules — those are the owner's captured data. Reach for it whenever the owner
+hands over measurements or quantities rather than a finished price. If there is no captured method yet,
+capture it first rather than inventing rates here.
+
 ## Quote Formatting Template
 
 Quotes sent to customers should be clean, readable, and professional — but delivered as a WhatsApp message (not a PDF, unless the business owner requests one).

package/payload/platform/plugins/business-assistant/skills/pricing-method/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: pricing-method
+description: Use when an operator's own way of pricing jobs needs to become something the assistant can apply — onboarding a new business's pricing, building or editing their priceable items and rules by hand, re-learning their method from past quotes, or checking that the captured method reproduces their past quotes. Triggers include "set up my pricing", "learn how I quote", "add an item / change a rate", "my method's quotes don't match my past jobs", and any work that produces or maintains the method that the quote-generation flow consumes. Not for pricing or troubleshooting a single live quote — that is the quote-generation flow.
+---
+
+# Pricing method
+
+This skill ends with a correct, machine-usable representation of **one operator's own** pricing
+method: the things they price (what each is, how it is quantified, how it is priced), the rules that
+roll line prices up to a total, and the documents they issue. The quote-generation flow consumes that
+method; this skill is the only place it is built and maintained.
+
+## Principle: the skill carries no business content
+
+This skill ships no item catalogue, no units, no rates, no margin, overhead, contingency or tax
+values, no roll-up formula, no document templates — **and no predetermined schema or data shape.** It
+is a procedure for eliciting and encoding an operator's *own* method. The same skill must onboard a
+trade that prices by the square metre, a caterer who prices per head in tiers, and a printer with
+per-unit price breaks — businesses with nothing in common. Everything that varies between businesses
+is captured as that operator's data, never written into this skill.
+
+The operator's structure is **discovered, not imposed.** Capture it faithfully wherever it diverges
+from any shape you might assume — an operator whose margin differs by category, who applies
+adjustments in an unusual order, who quantifies one item from a measurement and another by eye. If you
+find yourself forcing their method into a fixed template, the template is the defect. There is no
+canonical set of fields; there is only what *their* method actually contains.
+
+## Building, verifying, and maintaining the method
+
+Two paths build the method:
+
+- **Learn from history** — derive the method from the operator's own past pricing artifacts. See
+  [references/learning-from-history.md](references/learning-from-history.md).
+- **Define manually** — build or edit the method by hand for an operator with no usable history, or
+  making an adjustment. See [references/manual-definition.md](references/manual-definition.md).
+
+Two activities keep it correct:
+
+- **Verify against the operator's own outputs** — the method is accepted only when it reproduces that
+  operator's own past quotes to their own precision. See
+  [references/verification.md](references/verification.md).
+- **Maintain** — re-learning or editing preserves prior manual adjustments and re-verifies green. See
+  [references/maintenance.md](references/maintenance.md).
+
+**Onboarding** a new operator is a build path (learn from history, or define by hand) followed
+*always* by verification: the method is not onboarded until it reproduces their past jobs. A learned
+method and a hand-built method are the same kind of thing in the same captured form; nothing downstream
+should be able to tell which path produced an entry.
+
+## Standing rule vs per-job judgement
+
+For every priceable thing, the method records whether the operator prices it by a **standing rule**
+(the same rule applies every time — a rate, a tier, a formula they always use) or by **per-job
+judgement** (they decide the price afresh each job). This distinction is load-bearing: it is what lets
+the quote flow stay quiet about standing-rule items and ask the operator only about judgement-priced
+ones. Derive the classification from the operator's history — an item whose price moves
+unpredictably across past jobs is judgement-priced; one that follows a consistent rule is not — or
+take it from the operator directly when defining by hand.
+
+## Observability
+
+Under-capture that hides until it produces a wrong quote is the failure this skill exists to prevent.
+Two things are always visible:
+
+- **A capture log.** Every item, rule, and dial derived is logged with where it came from. Just as
+  important, every part of a source artifact that could **not** be confidently encoded — skipped,
+  ambiguous, or guessed — is logged as such, so gaps are seen at onboarding, not discovered later in a
+  wrong quote.
+- **A reconciliation report.** The standing check is reproduction against the operator's own history:
+  per past job, the **delta** between the reproduced figures and the operator's own, at line, group,
+  and final level — a delta, never a boolean. The verification pillar owns why and how
+  ([references/verification.md](references/verification.md)).
+
+## Scope
+
+This skill produces and maintains the method only. The compute that applies the method to a job, and
+the documents that present the result, are the quote-generation flow — separate work. This skill owns
+*what the operator's method is*; it does not own pricing a live job or rendering a quote.

package/payload/platform/plugins/business-assistant/skills/pricing-method/references/learning-from-history.md

@@ -0,0 +1,51 @@
+# Learning the method from history
+
+The operator has been pricing jobs for years. That method already exists — it lives in their past
+quotes, estimates, invoices, and spreadsheets. This pillar derives it from those artifacts so the
+assistant can apply the same method going forward. The source is whatever the operator actually used:
+a workbook, a folder of PDFs, photographed handwritten estimates, a price list. Work from what they
+have.
+
+## What a complete derivation captures
+
+From the operator's own artifacts, recover four things, and nothing the artifacts do not show:
+
+- **The priceable things.** Each distinct thing the operator charges for. Two lines that are the same
+  priced thing under different wording are one method entry, not two — collapse repeated instances of
+  the same thing across jobs into a single entry, and let the variation across those instances tell you
+  how the thing is quantified and priced.
+- **How each is quantified.** For each thing, how a job turns into a quantity. Some quantities are
+  derived from a measurement the operator takes (a length, an area, a volume, a weight); some are
+  counted directly (how many doors, heads, units); some are simply one of a thing. Read which it is
+  from how the past jobs got their numbers — do not assume a unit.
+- **How each is priced.** The rule that turns a quantity into a line price. It may be a rate per unit,
+  a tiered or banded price, a price that steps at break quantities, a fixed amount, or something else
+  entirely. Capture the form the operator's history actually shows; do not flatten everything into
+  "rate × quantity" if their numbers say otherwise.
+- **How lines roll up.** The sequence the operator applies above the line items to reach the total —
+  any markups, overheads, contingencies, discounts, and taxes, **in the order their arithmetic
+  reveals.** Do not assume a markup-then-overhead-then-tax chain; discover the operator's actual
+  sequence, including adjustments that apply to only part of the work.
+
+## Standing rule vs per-job judgement
+
+Classify each priceable thing as you derive it (the rule and why it matters are in
+[../SKILL.md](../SKILL.md)). On this path the signal is **variance across the operator's own jobs**: a
+price that follows a consistent rule from job to job is a standing rule; one that moves unpredictably
+is priced by judgement.
+
+## Faithfulness over tidiness
+
+The aim is the operator's method as it really is, including its irregularities. If their margin
+differs by category, capture that. If one adjustment applies before tax and another after, capture
+that. A clean, regular method that does **not** reproduce their past quotes is wrong; an irregular one
+that does is right. Reproduction is the test (see [verification.md](verification.md)).
+
+## Provenance and under-capture are recorded
+
+Every derived element carries where it came from — which artifact, which job. And every part of a
+source that could not be confidently encoded is logged as skipped, ambiguous, or guessed, rather than
+silently dropped or invented. A derivation that quietly omits a section the operator charges for will
+surface later as a quote that is wrong by exactly that section; logging the gap at onboarding is what
+prevents that. Under-capture you can see is a question to ask the operator; under-capture you cannot
+see is a future wrong quote.

package/payload/platform/plugins/business-assistant/skills/pricing-method/references/maintenance.md

@@ -0,0 +1,32 @@
+# Maintaining the method
+
+A pricing method is not set once. Rates change, items come and go, the operator refines how they
+charge, and a better history may arrive later that is worth re-learning from. Maintenance keeps the
+method correct across those changes without losing what was already established.
+
+## Re-learning preserves prior manual adjustments
+
+When the method is re-learned from history — because new artifacts arrived, or the first derivation
+was incomplete — the operator's prior manual adjustments are preserved, not overwritten. An operator
+who corrected a derived rate by hand, or added an item the artifacts missed, must not have that
+correction silently reverted by the next derivation. A re-learn that would drop a prior manual
+adjustment is a failure: surface the conflict to the operator and let them decide, rather than quietly
+choosing the freshly-derived value.
+
+This is why provenance matters (see [learning-from-history.md](learning-from-history.md)): an element
+the operator set by hand is distinguishable from one derived from an artifact, so a re-learn knows
+which it must not clobber.
+
+## Every change re-verifies
+
+Any maintenance pass — a re-learn, an added or retired item, a changed rate or roll-up step — is
+followed by re-running verification against the operator's own history (see
+[verification.md](verification.md)). The reconciliation must still be green to the operator's
+precision. A change that is recorded but breaks reproduction of a past job is not done; either the
+change is wrong, or a past fixture is no longer representative and the operator confirms which.
+
+## The outcome, not a storage scheme
+
+Maintenance is defined by two outcomes — prior manual adjustments survive, and reproduction stays
+green — not by any particular way of versioning or storing the method. How the method is held is the
+operator's data; what maintenance guarantees is preservation and re-verification.

package/payload/platform/plugins/business-assistant/skills/pricing-method/references/manual-definition.md

@@ -0,0 +1,42 @@
+# Defining and editing the method by hand
+
+Not every operator hands over a usable history, and every operator eventually changes how they price.
+This pillar builds or edits the method directly with the operator, by conversation, producing the same
+captured method that learning from history produces. A method built this way and a method learned from
+artifacts are indistinguishable to anything downstream — same kind of thing, same captured form.
+
+## What the operator must be able to express
+
+Building by hand means letting the operator state, in their own terms, the same four things a
+derivation recovers:
+
+- **A priceable thing** — something they charge for, named the way they name it.
+- **How it is quantified** — whether its quantity comes from a measurement they take, a count they
+  enter, or is simply one of a thing.
+- **How it is priced** — the rule that turns its quantity into a line price, in whatever form their
+  pricing takes (a rate, a tier, a price break, a fixed amount, or otherwise).
+- **How lines roll up** — the adjustments and taxes they apply above the lines, in the order they
+  apply them, and the dials those adjustments use (a markup percentage, a day rate, a tax rate).
+
+There is no fixed set of fields to fill and no form to complete. Capture what the operator's method
+contains; if their pricing for one thing needs something another thing's does not, the method holds
+both. Forcing every entry into the same template is the same defect here as it is when learning from
+history.
+
+## Standing rule vs per-job judgement
+
+Classify each thing here too (the rule and why it matters are in [../SKILL.md](../SKILL.md)). On this
+path the signal is simplest: **ask the operator directly** whether each thing is priced the same way
+every time or decided per job.
+
+## A hand-defined item is immediately quotable; a hand-edited rule takes effect
+
+The point of building by hand is that it works at once. A priceable thing the operator just defined is
+available to a quote with no further step, and a rule the operator just changed governs the next quote
+that uses it. An edit that is recorded but does not change what the next quote does is not an edit.
+
+## Editing is a first-class path, not a fallback
+
+Editing an existing method — adding a thing, retiring one, changing a rate or a roll-up step — runs
+through this pillar, and through [maintenance.md](maintenance.md) for preserving prior adjustments and
+re-verifying. A manual edit must survive a later re-learn from history; see maintenance.