@floless/app 0.59.1 → 0.61.0

package/dist/floless-server.cjs

@@ -53022,7 +53022,7 @@ function appVersion() {
   return resolveVersion({
     isSea: isSea2(),
     sqVersionXml: readSqVersionXml(),
-    define: true ? "0.59.1" : void 0,
+    define: true ? "0.61.0" : void 0,
     pkgVersion: readPkgVersion()
   });
 }
@@ -53032,7 +53032,7 @@ function resolveChannel(s) {
   return "dev";
 }
 function appChannel() {
-  return resolveChannel({ isSea: isSea2(), define: true ? "0.59.1" : void 0 });
+  return resolveChannel({ isSea: isSea2(), define: true ? "0.61.0" : void 0 });
 }
 
 // workflow-update.ts
@@ -53783,30 +53783,45 @@ function walk(value, node, root, path, errors) {
     }
   }
 }
-var _cached = null;
-function loadSteelTakeoffSchema() {
-  if (_cached) return _cached;
+var _cache = /* @__PURE__ */ new Map();
+function loadContractSchema(file) {
+  const hit = _cache.get(file);
+  if (hit) return hit;
   const here2 = (0, import_node_path14.dirname)((0, import_node_url2.fileURLToPath)(__import_meta_url));
   const candidates = [
-    (0, import_node_path14.join)(here2, "..", "schemas", "steel.takeoff.v1.schema.json"),
+    (0, import_node_path14.join)(here2, "..", "schemas", file),
     // dev: server/ next to schemas/
-    (0, import_node_path14.join)(here2, "schemas", "steel.takeoff.v1.schema.json")
+    (0, import_node_path14.join)(here2, "schemas", file)
     // bundled: dist/ holds ./schemas
   ];
   for (const p of candidates) {
     try {
-      const text = (0, import_node_fs16.readFileSync)(p, "utf8");
-      _cached = JSON.parse(text);
-      return _cached;
+      const parsed = JSON.parse((0, import_node_fs16.readFileSync)(p, "utf8"));
+      _cache.set(file, parsed);
+      return parsed;
     } catch (err2) {
       if (err2.code !== "ENOENT") throw err2;
     }
   }
-  throw new Error("steel.takeoff/v1 schema file not found");
+  throw new Error(`contract schema file not found: ${file}`);
+}
+function loadSteelTakeoffSchema() {
+  return loadContractSchema("steel.takeoff.v1.schema.json");
+}
+function loadDrawingVectorSchema() {
+  return loadContractSchema("drawing.vector.v1.schema.json");
 }
 function validateSteelTakeoff(doc) {
   return validate(doc, loadSteelTakeoffSchema());
 }
+function validateDrawingVector(doc) {
+  return validate(doc, loadDrawingVectorSchema());
+}
+function validateContract(doc) {
+  const type = doc && typeof doc === "object" ? doc.type : void 0;
+  if (type === "drawing.vector/v1") return validateDrawingVector(doc);
+  return validateSteelTakeoff(doc);
+}
 
 // contract-store.ts
 var ContractError = class extends Error {
@@ -53832,7 +53847,7 @@ function readContract(appId) {
 }
 function writeContract(appId, doc) {
   const p = contractPath(appId);
-  const res = validateSteelTakeoff(doc);
+  const res = validateContract(doc);
   if (!res.valid) {
     const first = res.errors.slice(0, 5).map((e) => `${e.path}: ${e.message}`).join("; ");
     throw new ContractError(`contract failed schema validation \u2014 ${first}`);
@@ -53851,11 +53866,12 @@ function readContractForApp(appId, readAppFn = readApp) {
   } catch {
     return null;
   }
-  const node = app.nodes.find((n) => n.config["contract"] === "steel.takeoff/v1");
+  const isBaked = (v) => v != null && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length > 0;
+  const node = app.nodes.find(
+    (n) => typeof n.config["contract"] === "string" && n.config["contract"] !== "" && isBaked(n.config["takeoff"])
+  );
   const t = node?.config["takeoff"];
-  if (t == null || typeof t !== "object" || Array.isArray(t) || Object.keys(t).length === 0) {
-    return null;
-  }
+  if (!isBaked(t)) return null;
   return t;
 }
 
@@ -53886,29 +53902,124 @@ function bakeContractIntoApp(sourcePath, contract) {
       return p;
     });
   }
+  const stripPageRaster = (p) => {
+    if (p && typeof p === "object") {
+      const page = { ...p };
+      delete page.bg_b64;
+      return page;
+    }
+    return p;
+  };
   const filter = baked.filter;
   if (filter && typeof filter === "object") {
-    const stripPage = (p) => {
-      if (p && typeof p === "object") {
-        const page = { ...p };
-        delete page.bg_b64;
-        return page;
-      }
-      return p;
-    };
     const next = { ...filter };
-    if (filter.page) next.page = stripPage(filter.page);
+    if (filter.page) next.page = stripPageRaster(filter.page);
     if (Array.isArray(filter.sheets)) {
       next.sheets = filter.sheets.map(
-        (s) => s && typeof s === "object" ? { ...s, page: stripPage(s.page) } : s
+        (s) => s && typeof s === "object" ? { ...s, page: stripPageRaster(s.page) } : s
       );
     }
     baked.filter = next;
   }
+  if (Array.isArray(baked.sheets)) {
+    baked.sheets = baked.sheets.map(
+      (s) => s && typeof s === "object" ? { ...s, page: stripPageRaster(s.page) } : s
+    );
+  }
   doc.setIn(["nodes", idx, "config", "takeoff"], baked);
   (0, import_node_fs18.writeFileSync)(sourcePath, doc.toString());
 }
 
+// vectorize.ts
+function assignIds(items, prefix) {
+  const used = /* @__PURE__ */ new Set();
+  const keep = items.map((it) => {
+    if (it.id && !used.has(it.id)) {
+      used.add(it.id);
+      return true;
+    }
+    return false;
+  });
+  let counter = 0;
+  const nextId = () => {
+    let id;
+    do {
+      counter += 1;
+      id = `${prefix}${counter}`;
+    } while (used.has(id));
+    used.add(id);
+    return id;
+  };
+  return items.map((it, i) => keep[i] ? it : { ...it, id: nextId() });
+}
+function geomKey(el, index) {
+  const layer = el.layer ?? "";
+  if (el.kind === "text") {
+    const pos2 = el.origin ? el.origin.join(",") : (el.bbox ?? []).join(",");
+    return `text|${layer}|${el.text ?? ""}|${pos2}`;
+  }
+  if (el.d) return `${el.kind}|${layer}|${el.d}`;
+  if (el.pts) return `${el.kind}|${layer}|${el.pts.map((p) => p.join(",")).join(" ")}`;
+  return `nogeom|${index}`;
+}
+function dedupeElements(elements) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  elements.forEach((el, i) => {
+    const key = geomKey(el, i);
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(el);
+  });
+  return out;
+}
+function snapEndpoints(elements, tol = 1) {
+  const reps = [];
+  const tol2 = tol * tol;
+  const snap = (p) => {
+    for (const r of reps) {
+      const dx = p[0] - r[0];
+      const dy = p[1] - r[1];
+      if (dx * dx + dy * dy <= tol2) return r;
+    }
+    const rep = [p[0], p[1]];
+    reps.push(rep);
+    return rep;
+  };
+  return elements.map((el) => {
+    if (!el.pts || el.pts.length === 0) return el;
+    const pts = el.pts.map((p) => {
+      const s = snap(p);
+      return [s[0], s[1]];
+    });
+    return { ...el, pts };
+  });
+}
+function deriveLayers(elements, existing) {
+  const onByName = /* @__PURE__ */ new Map();
+  for (const l of existing ?? []) if (l && l.name && l.on != null) onByName.set(l.name, l.on);
+  const counts = /* @__PURE__ */ new Map();
+  for (const el of elements) {
+    if (!el.layer) continue;
+    counts.set(el.layer, (counts.get(el.layer) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([name, count]) => onByName.has(name) ? { name, count, on: onByName.get(name) } : { name, count }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+function postProcess(contract, opts = {}) {
+  const snapTol = opts.snapTol ?? 1;
+  const sheets = contract.sheets.map((sheet, i) => {
+    let elements = sheet.elements ?? [];
+    elements = snapEndpoints(elements, snapTol);
+    elements = dedupeElements(elements);
+    elements = assignIds(elements, "e");
+    const layers = deriveLayers(elements, sheet.layers);
+    const id = sheet.id ?? `s${i + 1}`;
+    const groups = sheet.groups ? assignIds(sheet.groups, "g") : void 0;
+    return { ...sheet, id, elements, layers, ...groups ? { groups } : {} };
+  });
+  return { ...contract, type: "drawing.vector/v1", sheets };
+}
+
 // steel-joints.ts
 var GROUPS = {
   "base-plate": { key: "base-plate", label: "Base plates", color: "#6b7a8d" },
@@ -61279,6 +61390,8 @@ var PRODUCT_SKILLS = [
   // handle a tweak-contract request from the Steel Model contract editor (Slice 2 AI round-trip)
   "floless-app-ui",
   //            compose Custom Panels (~/.floless/ui/extensions.json) for the Dashboard
+  "floless-app-vectorize",
+  //     read a vector PDF into an editable drawing.vector/v1 contract (the Vectorize reader)
   "floless-app-workflows",
   //     author/run .flo workflows
   "reading-structural-drawings",
@@ -63537,7 +63650,7 @@ async function startServer() {
       return reply.status(409).send({ ok: false, error: `"${id}"'s saved data is unreadable \u2014 open it in the editor and re-save before updating`, code: "contract-corrupt" });
     }
     if (contract != null) {
-      const v = validateSteelTakeoff(contract);
+      const v = validateContract(contract);
       if (!v.valid) return reply.status(409).send({ ok: false, error: `"${id}"'s saved data is invalid \u2014 re-save it in the editor before updating`, code: "contract-invalid" });
     }
     _wfUpdating.add(id);
@@ -63670,6 +63783,9 @@ async function startServer() {
   app.get("/api/contract/:appId", async (req, reply) => {
     const doc = readContractForApp(req.params.appId);
     if (doc == null) return reply.status(404).send({ ok: false, error: "no contract for this app yet" });
+    if (doc && typeof doc === "object" && doc.type === "drawing.vector/v1") {
+      return postProcess(doc);
+    }
     return doc;
   });
   app.put(
@@ -63690,7 +63806,7 @@ async function startServer() {
   app.post("/api/contract/:appId/approve", async (req, reply) => {
     const doc = readContract(req.params.appId);
     if (doc == null) return reply.status(404).send({ ok: false, error: "no contract to approve" });
-    const v = validateSteelTakeoff(doc);
+    const v = validateContract(doc);
     if (!v.valid) return reply.status(400).send({ ok: false, error: "stored contract is invalid \u2014 re-save it in the editor" });
     const sourcePath = readApp(req.params.appId).source.path;
     try {
@@ -64001,7 +64117,7 @@ async function startServer() {
       return reply.status(409).send({ ok: false, error: `"${id}"'s saved data is unreadable \u2014 open it in the editor and re-save before restoring`, code: "contract-corrupt" });
     }
     if (contract != null) {
-      const v = validateSteelTakeoff(contract);
+      const v = validateContract(contract);
       if (!v.valid) return reply.status(409).send({ ok: false, error: `"${id}"'s saved data is invalid \u2014 re-save it in the editor before restoring`, code: "contract-invalid" });
     }
     _wfUpdating.add(id);

package/dist/schemas/drawing.vector.v1.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://floless.app/schemas/drawing.vector/v1",
+  "title": "drawing.vector/v1",
+  "description": "Vocabulary-free vectorized-drawing contract: clean 2D linework + text extracted from any sketch / PDF / photo, the general 'draw CAD from anything' core. Mirrors the (steel-agnostic) steel.takeoff/v1 `filter` block but makes every element and group ID-BEARING (so a placed/edited detail can be targeted) and first-class. The contract is the single source of truth; the 2D vectorize editor is its view; server/vectorize.ts is the pure post-processor; exporters (SVG now; viewer-3d/ifc via a generalized scene later) consume it; Approve bakes the .lock. Coordinates are DISPLAY space (the drawing's own frame); `sheets[].transform` carries the reader-emitted display->world mapping a renderer cannot reconstruct. Confidential rasters ride inside as base64 and are NEVER committed (stripped at bake, like steel's page.bg_b64). Design: docs/superpowers/specs/2026-07-01-vectorize-draw-from-anything-design.md.",
+  "type": "object",
+  "required": ["type", "sheets"],
+  "additionalProperties": true,
+  "properties": {
+    "type": { "const": "drawing.vector/v1", "description": "Renderer-registry discriminator (web/renderers.js contractTypeOf)." },
+    "active": { "type": "integer", "description": "Index into `sheets` of the active sheet (mirrors steel's plans/active)." },
+    "units": { "type": "string", "description": "World units the `transform` maps into (default 'mm'). The scene/3D reuse is mm, Z-up." },
+    "source": {
+      "type": "object",
+      "description": "Provenance: where this drawing was read from.",
+      "properties": {
+        "name":    { "type": "string" },
+        "path":    { "type": "string" },
+        "kind":    { "enum": ["pdf", "image"], "description": "Input modality the extractor read." },
+        "sha256":  { "type": "string" },
+        "read_at": { "type": "string" },
+        "extractor": { "type": "string", "description": "How it was read (e.g. 'pymupdf@compose-time', later 'vectorize.extract@<ver>'). Determinism/audit trail." }
+      },
+      "additionalProperties": true
+    },
+    "sheets": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/sheet" },
+      "description": "One entry per page/view. Multi-page PDFs and image sets each become a sheet."
+    }
+  },
+  "$defs": {
+    "sheet": {
+      "type": "object",
+      "required": ["id", "elements"],
+      "additionalProperties": true,
+      "description": "One drawing page/view: its raster backdrop, the display->world transform, and the vectorized elements + optional detected groups. Lines render as SVG paths over a dimmed page raster; text spans stay pickable.",
+      "properties": {
+        "id": { "type": "string", "description": "Stable, document-unique sheet id (e.g. 's1'). Targets are keyed {sheet,id} (member ids can collide across sheets — task_d1db821f)." },
+        "label": { "type": "string", "description": "Human sheet name (page title / detail name)." },
+        "page": {
+          "type": "object",
+          "required": ["w", "h"],
+          "description": "Page geometry in DISPLAY space. w/h are required and positive.",
+          "properties": {
+            "w": { "type": "number", "minimum": 1 },
+            "h": { "type": "number", "minimum": 1 },
+            "bg_b64": { "type": "string", "description": "Base64 JPEG of the page for the dimmed backdrop. CONFIDENTIAL — machine-local, stripped from the baked .flo (contract-bake.ts), never committed." },
+            "rect": { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "[x0,y0,x1,y1] display-coords the raster was clipped to, so the viewer registers 1:1 with the linework." }
+          },
+          "additionalProperties": true
+        },
+        "transform": {
+          "type": "object",
+          "description": "READER-EMITTED display->world mapping a renderer cannot reconstruct: pixel/point -> `units`. AWARE-owned on graduation (§Graduation). Absent = display space treated as world 1:1.",
+          "properties": {
+            "scale":    { "type": "number", "description": "World units per display unit (e.g. mm per pt). Uniform." },
+            "origin":   { "$ref": "#/$defs/point2", "description": "Display-space point mapped to world [0,0]." },
+            "units":    { "type": "string", "description": "World units this maps into (overrides the top-level default for this sheet)." },
+            "rotation": { "type": "number", "description": "Degrees the display frame is rotated relative to world (page orientation)." }
+          },
+          "additionalProperties": true
+        },
+        "layers": {
+          "type": "array",
+          "description": "Distinct layers observed (name + count), for the editor's layer toggles. Vocabulary-free: no steel 'is this a beam' flags.",
+          "items": {
+            "type": "object",
+            "required": ["name"],
+            "additionalProperties": true,
+            "properties": {
+              "name":  { "type": "string" },
+              "count": { "type": "number" },
+              "on":    { "type": "boolean", "description": "Persisted visibility state." }
+            }
+          }
+        },
+        "elements": {
+          "type": "array",
+          "description": "Every vectorized element, each with a STABLE id. Geometry elements carry an SVG path `d`; text elements carry `text`+`bbox`.",
+          "items": { "$ref": "#/$defs/element" }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Optional detected entities (the AEC-on-top layer, or user groupings): a named set of element ids. Each group is ID-BEARING so it can be targeted for insert/modify.",
+          "items": { "$ref": "#/$defs/group" }
+        }
+      }
+    },
+    "element": {
+      "type": "object",
+      "required": ["id", "kind"],
+      "additionalProperties": true,
+      "description": "One drawing element. STABLE, sheet-unique `id`, REQUIRED on write (the store validates before the post-processor runs; the post-processor only repairs id collisions on read) — so every element can be selected, exported, and targeted for modification.",
+      "properties": {
+        "id":    { "type": "string", "description": "Stable, sheet-unique element id (e.g. 'e12')." },
+        "kind":  { "enum": ["line", "arc", "polyline", "spline", "text"], "description": "Geometry class (broader than steel's line/text)." },
+        "d":     { "type": "string", "description": "SVG path in DISPLAY coords (geometry elements). The SVG export is near-free — this IS the path." },
+        "pts":   { "type": "array", "items": { "$ref": "#/$defs/point2" }, "description": "Optional explicit vertices (display coords) for line/polyline; a convenience alongside/instead of `d` for snap/edit." },
+        "text":  { "type": "string", "description": "Label text (text elements)." },
+        "bbox":  { "type": "array", "items": { "type": "number" }, "minItems": 4, "maxItems": 4, "description": "[x0,y0,x1,y1] display coords (text + geometry bounds)." },
+        "size":  { "type": "number", "description": "Text font size in display units (text elements) — reader-emitted; the renderer needs it (a fixed size renders wrong)." },
+        "origin": { "$ref": "#/$defs/point2", "description": "Text BASELINE start [x,y] (text elements) — where the glyphs actually sit. The bbox top is NOT the baseline; reader-emitted." },
+        "angle": { "type": "number", "description": "Text rotation in degrees from the writing direction (text elements); 0 = horizontal. Reader-emitted." },
+        "font":  { "type": "string", "description": "Text font family (text elements)." },
+        "layer": { "type": "string" },
+        "color": { "type": "string", "description": "Stroke colour (#hex or name), reader-emitted." },
+        "w":     { "type": "number", "description": "Stroke width (display units)." },
+        "dashed": { "type": "boolean" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "READER-EMITTED trace confidence 0..1. The editor flags weak traces (.chip.weak) below a threshold; absent = trusted (1)." },
+        "group": { "type": "string", "description": "Optional back-reference to a `groups[].id` this element belongs to." }
+      }
+    },
+    "group": {
+      "type": "object",
+      "required": ["id"],
+      "additionalProperties": true,
+      "description": "A named, ID-BEARING set of elements (a detected entity or a user grouping) — the unit an insert/modify Request can target.",
+      "properties": {
+        "id":    { "type": "string", "description": "Stable, sheet-unique group id." },
+        "kind":  { "type": "string", "description": "Free-form entity kind (vocabulary-free; e.g. 'detail', 'wall', 'annotation'). The generic core does not enforce a taxonomy." },
+        "label": { "type": "string" },
+        "elementIds": { "type": "array", "items": { "type": "string" }, "description": "The `elements[].id`s in this group." },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1, "description": "Reader-emitted grouping confidence 0..1." }
+      }
+    },
+    "point2": {
+      "type": "array",
+      "items": { "type": "number" },
+      "minItems": 2,
+      "maxItems": 2,
+      "description": "[x, y] in display space."
+    }
+  }
+}

package/dist/skills/floless-app-vectorize/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: floless-app-vectorize
+description: Vectorize a drawing into an editable drawing.vector/v1 contract in floless.app — the "Vectorize" reader. Triggers on a pending floless `rebake` request for the `vectorize` app (queued from its "Re-read & re-bake ▸" button), or asks like "vectorize this PDF", "turn my sketch into clean CAD linework", "read this detail into vectors", "trace this photo". Teaches the host AI to read a drawing at COMPOSE time — a vector PDF via ONE deterministic PyMuPDF pass (no LLM), a scan/photo/hand sketch via AWARE's fenced vision.extract (schema-bound, cached) — emit the drawing.vector/v1 contract, PUT it to the contract store, and hand the 2D vector editor to the user.
+metadata:
+  version: 0.3.0
+---
+
+# Vectorize — read a drawing into a drawing.vector/v1 contract
+
+## What this is
+
+`vectorize` is a FloLess app that turns a drawing — a vector PDF, a scan, a photo, a hand
+sketch — into clean, editable **2D vector linework**: a `drawing.vector/v1` contract
+(vocabulary-free; every element has a stable id) rendered in the 2D vector editor, where the
+user pans/zooms, toggles Lines/Curves/Text and layers, reviews weak traces, and exports SVG.
+
+The drawing is read **at compose time**, by one of two paths:
+
+- **Vector PDF → deterministic.** One PyMuPDF pass; the geometry is exact, extracted, never
+  guessed. No model, no API key.
+- **Raster (scan/photo/sketch) → AWARE `vision.extract`.** The substrate's fenced extraction
+  carve-out: a FIXED schema + prompt + pinned model, content-hash cached (same input → same
+  JSON, no repeat model call). Coordinates come from the model, flagged with per-element
+  confidence the editor surfaces for review — never from you eyeballing pixels.
+
+There is **no model in the run path** either way. The app ships with a tiny hard-coded
+example; this skill is how the user's OWN drawing replaces it.
+
+**Later slices (mention as "next", do not attempt here):** multi-view 3D reconstruction,
+DXF export.
+
+> **Pasted a request?** If the user pastes a message beginning with a `[floless-request
+> type=rebake id=…]` marker, that's a request copied from the FloLess Dashboard — resolve it
+> via `GET /api/requests` (match the id), don't run the pasted line verbatim, and `DELETE` it
+> when done.
+
+## The loop
+
+### 1. Find the drawing(s)
+
+From a `rebake` request: `GET http://localhost:<port>/api/requests` → the entry with
+`type:"rebake"` and `appId:"vectorize"` carries `snapshots: ["<abs path>", …]` and optionally
+`sourceName` (use it for `source.name` provenance). **`snapshots` may hold multiple files —
+read every one**, each page becoming a sheet. If the user just attaches or names a file in
+prose, skip the lookup and proceed from that path. Resolve the port from the running
+floless.app (check `~/.floless/port` or the active server port), as the other floless-app
+skills do.
+
+### 2. Pick the path — vector or raster?
+
+Probe the file: a PDF whose pages return `page.get_drawings()` paths is a **vector PDF** →
+step 3a (deterministic, always preferred). An image file, or a PDF with no vector paths (a
+scan, a photo, a hand sketch) → step 3b (vision). **Never trace pixels by eye into made-up
+coordinates** — fabricated geometry is worse than no geometry; the raster path exists so the
+extraction is fenced, cached, and confidence-flagged instead.
+
+### 3a. Vector path — one deterministic PyMuPDF pass
+
+Run the bundled extractor (it lives beside this file):
+
+```
+python <skill dir>/scripts/extract_pdf.py <drawing.pdf> [more.pdf …] --out contract.json
+```
+
+Requires PyMuPDF (`pip install pymupdf`). The script forces UTF-8 on its own output; but any
+OTHER ad-hoc Python that prints extracted drawing text must set UTF-8 first — drawings carry
+glyphs (Ø, —) that crash a cp1250 Windows console (PowerShell
+`$env:PYTHONIOENCODING='utf-8'`; bash `PYTHONIOENCODING=utf-8 python …`). What it does, per
+page:
+
+- **Geometry** — each `page.get_drawings()` path becomes one element in DISPLAY coords:
+  a continuous straight-line chain emits `pts` (explicit vertices — the server snaps shared
+  corners through them); everything else emits an SVG `d` (`c` items become cubic béziers,
+  `re`/`qu` closed 4-corner polygons). Never both — renderers prefer `d`, which would shadow
+  snapped `pts`. Plus stroke `color` (falling back to fill), `w`, `dashed`, and the OCG
+  `layer` when the PDF carries one. Kind is `line` (single segment), `polyline`, or `spline`
+  (any bézier).
+- **Text** — each `page.get_text("dict")` span becomes `{kind:'text', text, origin (baseline),
+  size, angle, color, font, bbox}`. The baseline `origin` and real `size`/`angle` matter — a
+  fixed size or bbox-top placement renders wrong.
+- **Rotated pages** — every point is mapped through `page.rotation_matrix` into display space
+  (`page.rect` is already display). Never mix native/display coords.
+- **Ids** — the PUT schema **requires** per-element ids; the script assigns `e1…` per sheet
+  and `s1…` sheets in document order.
+
+If the script needs adapting (odd PDF, extra filtering), patch a local copy — the mapping
+above is the contract. Hard schema requirements the server enforces on PUT: `type`,
+`sheets[].id`, and `sheets[].elements[].{id,kind}` (a missing element id is rejected). Do NOT
+dedupe, snap, or derive layers yourself — the server post-processes every read of this
+contract type.
+
+### 3b. Raster path — AWARE `vision.extract` (the fenced exception)
+
+For each raster image (or rasterized PDF page exported to an image):
+
+1. Copy `references/vision-inputs.template.json` (beside this file) to a scratch file and set
+   **only** `"file"` to the image's absolute path. The `prompt`, `schema`, and pinned `model`
+   are FIXED — together with the file bytes they form the extraction's content-hash cache key
+   and its fence; do not tweak them per run.
+2. Invoke the substrate:
+
+   ```
+   aware agent invoke vision extract --inputs @<scratch>/vision-inputs.json --json > <scratch>/vision-out.json
+   ```
+
+   A cache miss shells out to the local authenticated `claude`/`codex` CLI (no API key) and can
+   take a minute; a repeat of the same input replays from cache instantly. If neither CLI nor a
+   `vision-model` credential is available, stop and tell the user what to set up.
+3. Convert to the contract (the model traces in a normalized 0..1000 frame; this maps it onto
+   the image's real pixel size and carries per-element confidence):
+
+   ```
+   python <skill dir>/scripts/vision_to_contract.py <scratch>/vision-out.json <image> --out contract.json
+   ```
+
+   For a multi-image set, run steps 1–3 per image and append with
+   `--merge-into contract.json` instead of `--out`.
+4. Sanity-check the result before PUT: element count > 0, and the traced text you can see in
+   the vision output matches what the drawing actually says. A wildly wrong trace usually means
+   the image is too low-contrast — say so rather than shipping garbage.
+
+### 4. Write to the contract store
+
+```
+PUT http://localhost:<port>/api/contract/vectorize
+Content-Type: application/json
+
+<contract JSON body>
+```
+
+The server schema-validates the body; on `400` read the error, fix the offending fields, and
+re-PUT. The stored draft **wins over the baked example immediately** — no compile needed for
+the editor to show it. Read back with `GET /api/contract/vectorize` (served through the pure
+post-processor, so ids/layers come back cleaned).
+
+### 5. Hand off to the user
+
+Tell the user:
+
+- **What was read** — e.g. "2 sheets, 214 lines, 12 curves, 96 text spans from `detail.pdf`".
+- **Open the editor**: double-click the `read` node on the Vectorize canvas. It renders their
+  drawing — pan/zoom + Fit, Lines/Curves/Text toggles, per-layer toggles, weak-trace isolation,
+  and **Export SVG**. Deterministic reads have no weak traces; after a **vision** read, point
+  the user at the **Confidence** panel — each trace the model was unsure about (confidence
+  < 0.5) is listed there with **Accept** (mark correct) and **Delete** (remove, with Undo), and
+  a "Reviewed N/M" counter tracks progress. Edits auto-save to the contract store.
+- **Approve & bake lock**: when satisfied, the user clicks Approve in the editor header — it
+  bakes the (edited) contract into the `read` node's `config.takeoff` and recompiles, arming
+  the Run gate. Never auto-approve on their behalf.
+
+### 6. Clear the request
+
+If the trigger came from a `rebake` request:
+
+```
+DELETE http://localhost:<port>/api/requests/<id>
+```
+
+## Guardrails
+
+- **Compose-time only.** The drawing is read HERE, by the terminal AI, then PUT to the store.
+  Never add a runtime node that reads the drawing — `aware app validate` rejects it, and it
+  breaks determinism.
+- **Deterministic first, fenced second, eyeballs never.** Vector geometry is extracted
+  exactly; raster interpretation goes ONLY through `vision.extract` (fixed schema/prompt/model,
+  cached, confidence-flagged). Never hand-write coordinates you read off pixels yourself, and
+  never swap the vision path for your own vision — the fence is what makes the extraction
+  reproducible.
+- **Thin-UI contract.** The browser recorded intent and the file path; the brain is the
+  terminal AI. The UI never reads the drawing and never writes the contract itself.
+- **Stay in scope.** Producing and handing off the contract is the whole job — do not wire
+  editor Save/edit, 3D, or DXF here.
+- **Confidentiality.** The contract carries `source.path` and the drawing's content; it is
+  machine-local (`~/.floless/contracts/vectorize.json`) and never committed. Don't echo client
+  or project identifiers into files or commits.

package/dist/skills/floless-app-vectorize/references/vision-inputs.template.json

@@ -0,0 +1,40 @@
+{
+  "file": "<FILL IN: absolute path to the raster image/PDF>",
+  "model": "claude-sonnet-5",
+  "prompt": "Trace every visible stroke and label in this drawing into vector geometry. Use a coordinate frame where x runs 0..1000 left to right and y runs 0..1000 top to bottom over the full image. Emit each straight stroke as kind 'line' (exactly two points) or a connected run of straight strokes as 'polyline' (a vertex chain); follow smooth curves with a 'polyline' of enough vertices to track the curve (at most 20). Emit every piece of text as kind 'text' with the text content and its bounding box [x0,y0,x1,y1]. Mark a stroke dashed:true only if it is visibly drawn dashed. Do NOT invent geometry that is not visibly drawn; skip shading, hatching texture, smudges and paper artifacts. For every element report confidence between 0 and 1 — report 0.5 or lower whenever you are unsure the stroke exists, its endpoints are ambiguous, or the text is hard to read.",
+  "schema": {
+    "type": "object",
+    "required": ["elements"],
+    "properties": {
+      "elements": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": ["kind", "confidence"],
+          "allOf": [
+            { "if": { "properties": { "kind": { "enum": ["line", "polyline"] } } }, "then": { "required": ["pts"] } },
+            { "if": { "properties": { "kind": { "const": "text" } } }, "then": { "required": ["text", "bbox"] } }
+          ],
+          "properties": {
+            "kind": { "enum": ["line", "polyline", "text"] },
+            "pts": {
+              "type": "array",
+              "items": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2 },
+              "description": "Vertices in the 0..1000 frame (line/polyline)"
+            },
+            "text": { "type": "string" },
+            "bbox": {
+              "type": "array",
+              "items": { "type": "number" },
+              "minItems": 4,
+              "maxItems": 4,
+              "description": "[x0,y0,x1,y1] in the 0..1000 frame (text)"
+            },
+            "dashed": { "type": "boolean" },
+            "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+          }
+        }
+      }
+    }
+  }
+}