fenix-claude-plugin 0.1.3 → 0.2.0

package/skills/fenix-application/references/editors.md

@@ -1,71 +1,242 @@
 # Editors — how to drive them
 
-**Version: 21**
+**Version: 48**
 
-There are two ways to run the claims / figures / sections editors. **Prefer the live editors in Cowork**; use the clipboard editors elsewhere. **You never need to open or read any editor HTML** — everything you need is below.
+The Fenix editors are **pages served by the MCP into one installed wrapper artifact**. They load and
+save Fenix data themselves, so a full claim/figure/section/disclosure set never passes back through
+chat — far faster and far cheaper in tokens.
 
-## Live editors (preferred in Cowork)
+There is **one** installed artifact, the Fenix workspace shell. It knows nothing about patents; it
+fetches a page by address and runs it. New pages and new features never require a reinstall, because
+the shell's grant is `{read, write}` and does not change.
 
-In a Cowork host, use the **self-saving live editor artifacts** instead of the clipboard editors. They load and save themselves, so the full claim/figure/section set never has to pass back through chat — far faster and far cheaper in tokens.
+## The one rule
 
-To open one:
-1. Call `get_live_artifacts({ name: "claims-editor" })` (or `"figures-editor"`, `"sections-editor"`).
-2. Take the returned `html` and substitute its two placeholders before writing it: `__PROJECT_ID__` → the target Fenix project id, and `__SERVER_PREFIX__` → your MCP connector's tool prefix (the part before the tool name in a fully-qualified tool id — e.g. if your tools appear as `mcp__abc123__get_project`, the prefix is `mcp__abc123__`; bare tool names do not resolve when the host namespaces MCP tools). Then write it to the returned `fileName` and open it as a live HTML artifact for the user.
-3. That's it — the artifact loads the project's current claims/figures/sections itself (via `get_project`) and, on **Save**, writes them back itself (via `save_project`). **Do NOT pre-fill it, and do NOT call `save_project` for it yourself.**
+**You never write, edit, or substitute anything into an artifact's HTML. Ever.**
 
-**When the user pastes a `[CLAIMS SAVED - claimsRev N]` block** (or `[FIGURES SAVED - figuresRev N]` / `[SECTIONS SAVED - sectionsRev N]`), the editor has **already saved to Fenix**:
-- **Do NOT call `save_project` again** — it is already persisted.
-- Update your working copy from the block: it gives the **full text of every changed/added** item, the **numbers of removed** items, and the **numbers left unchanged**. Apply that delta to the set you already had.
-- Note the rev (`claimsRev`/`figuresRev`/`sectionsRev`). `get_project` returns the current rev for each; if yours is behind, reload to re-sync.
+Not a connector prefix, not a project id, not a docket number. This is not a style preference — it is
+a correctness rule with three independent reasons:
 
-If the host is **not** Cowork (no live artifacts, or the user can't run them), fall back to the clipboard editors below.
+1. **A remote push destroys grants.** Updating an installed MCP artifact from a chat session wipes
+   its connector grants *irreversibly*; recovering means a fresh desktop-side install. An edit you
+   make to "help" costs the user their working editor.
+2. **A baked-in prefix is wrong everywhere else.** Tool namespacing differs per host
+   (`mcp__Fenix__…` in a cloud session, `mcp__<connector-id>__…` on the desktop). A value correct in
+   your session resolves to nothing in theirs.
+3. **The shell already knows.** It discovers the prefix itself and asks the server which page to
+   open. Anything you inline is a stale duplicate of something it can look up.
 
-## Clipboard editors (fallback — non-Cowork hosts)
+The single exception is the **courier** (below), whose entire purpose is to be rewritten.
 
-This skill also ships three accordion HTML editors in `assets/`. Open one with pre-filled data:
-1. Take the editor file (`assets/<editor>.html`) as-is — do not parse it.
-2. Replace the line `var INITIAL_CONTENT="";` with `var INITIAL_CONTENT=<JSON>;`, where `<JSON>` is the data for that editor in the shape below (a JSON string the editor will `JSON.parse`, or an inlined array/object — both work).
-3. Save the working copy and open it for the user.
+## The two tools
 
-The header has an **Expand all / Collapse all** toggle; each row has **Remove**; there is an **+ Add** button. The user clicks **Copy for Save**, which copies a clipboard payload prefixed with `[EDITOR SUBMIT - <type>]`. The user pastes it back into chat; you strip the prefix line and call `save_project`.
+This server has exactly two tools, `read` and `write`. Everything is a resource on one of them.
 
-## claims_editor.html
-INITIAL_CONTENT = array of claim objects in the Fenix schema:
 ```
-[
-  { "claimNumber": "1", "claimStatus": "original", "claimType": "independent",
-    "claimText": ["A system comprising:", "a processor; and", "a memory."],
-    "parent": "", "independentParent": "" },
-  { "claimNumber": "2", "claimStatus": "original", "claimType": "dependent",
-    "claimText": ["The system of claim 1, wherein the processor is multi-core."],
-    "parent": "1", "independentParent": "1" }
-]
+read  { resource, name?, options?, haveVersions?, haveRev?, noContextUpdate?, ops? }
+write { resource, action?, options?, noContextUpdate?, ops? }
 ```
-- `claimText` is an array of lines (one entry per line of the claim body).
-Output: `[EDITOR SUBMIT - claims]` then a JSON array of the same schema. Strip the prefix; call `save_project({ type: "claims", claims: [...] })`.
 
-## figures_editor.html
-INITIAL_CONTENT = array of figure objects:
+**Batching.** Both take `ops: [...]` — an array of the same shape they take singly — and do the lot
+in one call. Omit it for a single action. Reads in a batch run in parallel; writes run in order, and
+one failing op does not stop the rest or discard the others' results. Every call pays the same fixed
+cost (the host hop, authentication, a database connection) whatever it asks for, so two questions in
+one call is close to half the cost of two calls. Batch by default when you know what you need:
+
+```
+read { ops: [ {resource:"context"}, {resource:"project", options:{projectId, include:["claims"]}} ] }
+```
+
+Call `read {resource:"schema"}` for the full directory of resources, actions and their parameters —
+prefer that over guessing. `read {resource:"schema", name:"project"}` documents one.
+
+The mappings you will use most:
+
+| The tool that used to exist | Call instead |
+|---|---|
+| get&#95;context | `read {resource:"context"}` |
+| set&#95;context | `write {resource:"context", options:{ids:{projectId}, label}}` |
+| get&#95;project | `read {resource:"project", options:{projectId, include}}` |
+| save&#95;project | `write {resource:"project", action:"save", options:{…}}` |
+| get&#95;claim&#95;limitations | `read {resource:"claim-limitations", options:{projectId}}` |
+| update&#95;claim&#95;limitation | `write {resource:"claim-limitation", options:{…}}` |
+| list&#95;active&#95;projects | `read {resource:"projects"}` |
+| get&#95;docket | `read {resource:"docket"}` |
+
+Any tool not listed: `read {resource:"schema"}` names them all.
+
+## The working context — and what moves it
+
+The working context is the record of what this person is working on. **The open Fenix workspace
+follows it.** It polls every few seconds and, unless the user has switched `follow` off on its status
+line, it *navigates* when the context moves. So moving the context is not bookkeeping — it changes
+what is on the user's screen, within seconds, while they are looking at it.
+
+Know which of your calls do that:
+
+| Call | Moves the context? |
+|---|---|
+| `write {…}` — any resource, any action | **Yes.** Every write folds its object ids in. |
+| `read {…}` — any resource | **No.** Reads never move it. |
+| `read {resource:"page", name:"…/<id>"}` | **Yes** — arriving at an address *is* navigating. |
+| `write {resource:"context", options:{ids:{projectId}}}` | **Yes** — that is its whole job. |
+| anything with `noContextUpdate: true` | **No.** |
+
+Reads used to move it too. They no longer do, so context tracks what is being **worked on** rather
+than what was last **looked at** — reading fifty matters to answer a question no longer drags the
+user's workspace across all fifty.
+
+**Turning it off.** `noContextUpdate: true` suppresses the move. Put it on a single call, or on the
+envelope of a batch where it applies to every op unless an op says otherwise:
+
+```
+write { noContextUpdate: true, ops: [ … ] }        // a sweep: change data, leave the user alone
+```
+
+Use it whenever the work is not the user's attention: automations, migrations, background
+housekeeping, or any loop over many matters. A 3am feed sweep is not navigation.
+
+Conversely, when you **do** want the user taken somewhere, say so deliberately with
+`write {resource:"context", options:{ids:{projectId}, label:"<matter number>"}}` rather than relying
+on a side effect of some other write.
+
+**Reading it cheaply.** `read {resource:"context"}` returns `{session, sessions, rev, url}`. Pass
+`haveRev` with the `rev` you last saw and an unchanged context answers `{notModified:true, rev}` with
+no payload — that is how the workspace polls every few seconds without cost. `url` is the website
+address the context points at.
+
+## Opening an editor
+
+1. **Bind the matter first:** `write {resource:"context", options:{ids:{projectId}, label:"<matter
+   number>"}}`. The shell reads context on load and opens on whatever you bound. This replaces the
+   old `__DOCKET__` substitution.
+2. **Tell the user to open the installed Fenix workspace** from the artifacts sidebar. If they don't
+   have it, they install it once from a **desktop-side** session — remote `create_artifact` /
+   `update_artifact` never populate the tool allowlist, so a chat-installed MCP artifact cannot call
+   tools no matter how it is built.
+
+**If the workspace is already open, step 2 happens by itself.** It follows the context, so binding
+the matter moves it there within a few seconds — no reload, and nothing to ask them to click. Say
+what you have opened rather than telling them to go and open it. (Only if they have switched `follow`
+off does it wait, showing an "open →" offer instead.)
+
+To switch matters, write the context again — the open workspace follows. Do not push a new copy.
+
+**Writing the file, when you do install one.** The html is large, so the fetch that returns it is
+usually persisted to a **file** rather than shown in the conversation. Read the bytes from that file
+and write them out programmatically. Never hand-transcribe an artifact, and never reconstruct one
+from what you can see of it — it must be byte-exact. A copy that is subtly wrong fails at runtime in
+ways that look like a Fenix bug: a truncated script, a mangled escape, a meta block that no longer
+parses and therefore grants nothing. If it comes back inline instead, write it through verbatim; if
+it looks truncated, fetch it again rather than filling the gap.
+
+**There is no grant prompt.** Nothing appears on first open and nothing is waiting to be approved. If
+you tell a user to expect one, they will sit waiting for a dialog that does not exist instead of
+reporting the code that says what is actually wrong. A copy with no permissions is FX02 — a
+desktop-side reinstall — not a prompt someone missed.
+
+## Addressing a page
+
+Pages are addressed the way the website addresses them, and **the id is always last**:
+
 ```
-[
-  { "number": "1", "type": "Flowchart", "briefDescription": "...",
-    "steps": [ { "number": "100", "label": "receive", "text": "receiving a request" } ], "components": [] },
-  { "number": "2", "type": "Device", "briefDescription": "...",
-    "steps": [], "components": [ { "number": "200", "label": "processor", "text": "a processor" } ] }
-]
+tools/patent/claims/<projectId>
+tools/oa/arguments/<projectId>
+collections/projects            (the list)
+collections/projects/<id>       (one matter)
+collections/deadlines
+dashboards/home
 ```
-- `type` is "Flowchart" | "Device" | "Placeholder".
-- Flowchart figures use `steps`; Device figures use `components`. Each row is `{ number, label, text }`.
-- There is no per-figure introductory-sentence field. The figure's introductory/opening sentence is generated from its `briefDescription` during spec drafting — do not collect or pass it.
-Output: `[EDITOR SUBMIT - figures]` then a JSON array of figure objects. Strip the prefix; call `save_project({ type: "figures", figures: [...] })`.
 
-## spec_editor.html
-INITIAL_CONTENT = a sections object: key = section name, value = `{ "paragraphs": string[] }`. Each figure description is its own section (e.g. "FIG. 1").
+Opening an address that carries an id also **moves the working context to it** — arriving somewhere
+is the same event as navigating there. So handing the user a full address is an alternative to
+writing context first, not a step after it.
+
+## The patent editor
+
+One page family, four views — **Disclosure, Claims, Figures, Specification** — matching the website's
+tabs, reached as `tools/patent/<view>/<projectId>`. It saves per group with revision checks, so it
+will not silently overwrite work done elsewhere, and it polls for changes: if the user is mid-edit it
+tells them rather than replacing what they typed.
+
+It is deliberately simpler than the website. It does **not** do feature/limitation linking, component
+association, claim-type conversion, or DOCX import. Those stay on the web tool, and where the user
+needs them, that is what you tell them to open. What the editor does not model, **you** do through
+the tools: `read {resource:"claim-limitations"}` and `write {resource:"claim-limitation"}` address
+limitations by `N.i` and handle links, `modifies`, and match confirmation.
+
+### Disclosure view
+
+You build the document first, then open the editor on it. Read every disclosure document the user
+gave you, split them into paragraphs, and for each write the patent-adapted wording and choose the
+section it belongs in. Save with `write {resource:"project", action:"save", options:{type:
+"disclosure", disclosure}}`, then have them open the editor to revise. Item shape (one per
+paragraph):
+
+```json
+{ "_localId": "d1", "type": "text",
+  "originalText": "verbatim paragraph from the source document",
+  "text": "the same content, adapted to patent language",
+  "insertedInSection": "Background",
+  "source": "Disclosure.docx" }
 ```
-{
-  "Field of the Invention": { "paragraphs": ["<p>The present disclosure relates to ...</p>"] },
-  "FIG. 1": { "paragraphs": ["<p>FIG. 1 illustrates ...</p>", "<p>In block 100, ...</p>"] }
-}
+
+⚠️ **There are two different "disclosures", and only one of them reaches the patent.**
+A project save with `type: "disclosure"` writes the item array to the **patent** record — this is the
+one the Disclosure view reads and the one whose text flows into the spec sections. The bare
+project-level `disclosure` field (a save with **no** `type`) writes to the **project** record, which
+the Disclosure view never reads. Passing the disclosure that way looks like it worked and changes
+nothing the user can see. Always pass `type: "disclosure"`.
+
+- **`insertedInSection` IS the include flag.** A section name means the paragraph flows into that
+  spec section; `""` means the item is kept on the record but excluded from the patent.
+- **A save REPLACES the whole array.** The editor carries non-text items (images, stencils) through
+  untouched — if you save the disclosure yourself, do the same, or you will delete them.
+- Load it back with `read {resource:"project", options:{projectId, include:["disclosure"]}}`.
+- When the user pastes a `[DISCLOSURE SAVED - disclosureRev N]` block, it is **already saved** — do
+  not call the save again; just apply the delta to your working copy.
+
+## The courier — the one artifact you may rewrite
+
+A ~1KB, grant-free artifact (`mcpTools: []`) whose only job is to carry a value into the device's
+shared artifact storage. Because it holds no grants, re-pushing it costs nothing — which is exactly
+why it, and never an editor, is the thing that gets rewritten.
+
+Its source contains a single `PAYLOAD` block. Rewrite that, push it, and have the user **open it** —
+delivery happens on page load, not on push. Its on-screen "payload #N written" line is the check.
+
+```js
+const PAYLOAD = {
+  seq: 2,             // MUST change every push — receivers dedup on it
+  prefix: null,       // connector prefix; null = leave alone
+  banner: null,
+  matterNum: null,
+  projectId: null
+};
 ```
-- In the editor, a blank line separates paragraphs; on submit each paragraph is wrapped in `<p>...</p>`.
-Output: `[EDITOR SUBMIT - sections]` then a JSON sections object. Strip the prefix; call `save_project({ type: "sections", sections: {...} })`.
+
+Rules: change `seq` every time; a field left `null` is not written, so a payload never clobbers what
+it doesn't name; keep payloads small (the storage quota is shared by every artifact); put no secrets
+in it (every installed artifact can read the same origin).
+
+In normal operation the courier is **not needed** — the shell discovers the connector prefix itself
+and caches it for the whole fleet. It earns its keep in one situation: the connector was re-added, so
+every cached and hinted prefix is stale. See FX04 below.
+
+## When the user says it isn't working
+
+The shell self-diagnoses and shows a code. Ask for the code — it is five characters and the user can
+read it off the screen. There is also a **Copy details** button that puts the full diagnostic on
+their clipboard; ask for that when the code alone isn't enough.
+
+| Code | Meaning | What to do |
+|---|---|---|
+| **FX01** | Not a live artifact — a file preview or chat chip | Have them open the artifact from the sidebar |
+| **FX02** | Never fully installed (no tool allowlist) | Needs a one-time **desktop-side** install |
+| **FX03** | Self-healed after a connector change | Nothing — informational |
+| **FX04** | Connector lost or re-added; no valid prefix anywhere | Send a courier carrying the new `prefix`, or have them paste it into the courier's manual field |
+| **FX05** | Fenix server or data error | Read the message in the strip; a back-end problem, not a wiring one |
+
+Never respond to any of these by editing the artifact's HTML. Never retry name variants either —
+if the allowlist is empty, no spelling of a tool name will resolve. FX02 and FX04 are
+install/connector problems; the others are not wiring problems at all.

package/skills/fenix-application/references/figure-description.md

@@ -1,6 +1,6 @@
 # Figure Description Protocol
 
-**Version: 21**
+**Version: 48**
 
 You are a patent drafting assistant. Your task is to write a detailed textual description of a figure (e.g., FIG. 1) for inclusion in the Detailed Description section of a patent application.
 

package/skills/fenix-application/references/figure-strategy.md

@@ -0,0 +1,166 @@
+# Figure Strategy — the interactive strategy document
+
+**Version: 48**
+
+A **figure strategy** is a one-page, editable worksheet you build BEFORE drafting figures. The user
+sees every proposed figure at a glance — a picture of what it will look like, what it shows, and its
+components — and edits it directly. You then read their edits back and turn the result into the
+figure set.
+
+Use it when the user wants to plan the figures collaboratively, when there are **source documents**
+(a disclosure, related applications, prior specs) to draw from, or when they ask for a "figure
+strategy". It replaces guessing the figure list and reading it out in chat.
+
+This is a **planning** artifact. It is not a Fenix entity: it is not saved by `write {resource:"project", action:"save"}` and has
+no rev. It ends by producing the figures array that Phase 1 of `references/figures.md` saves.
+
+---
+
+## ⚠️ Read-back: a browser CANNOT write to the HTML file it loaded
+
+**The trap:** you write `figure-strategy.html` to the sandbox, the user opens it, types into it — and
+you re-read the file and see **your original markup**. Their edits are in the browser's memory, not
+on disk. A page loaded from `file://` has no way to write back to itself. If you assume otherwise you
+will silently draft from the wrong plan and the user will not know why.
+
+So the page **must be given a way to hand its state back**. Pick the first option that fits the host:
+
+### A. Cowork — the artifact talks to Fenix itself (preferred there)
+In Cowork, `window.cowork` is available and live artifacts call MCP tools directly. Follow
+`references/editors.md`. The figure strategy has no Fenix entity of its own, so once the user is
+happy, have the page emit the finished figures and let the normal figures flow save them — or just
+have the user paste the summary block the page prints.
+
+### B. Local sandbox — serve it and POST the state back (use this for a local HTML file)
+This is the pattern that makes "the assistant can read anything the user entered" actually true.
+
+1. Write `figure-strategy.html` and `figure-strategy.json` (the initial state) into the sandbox.
+2. Run the bundled server: `python3 scripts/figure_strategy_server.py --dir <that dir> [--port 8765]`
+3. Give the user the URL it prints (`http://127.0.0.1:8765/`). **Do not tell them to open the
+   `.html` file directly** — opened as `file://` the save round-trip cannot work.
+4. The page **autosaves on every edit** (debounced): it `POST`s its whole state to `/save`, and the
+   server writes it to `figure-strategy.json`.
+5. You then **read `figure-strategy.json`** whenever you want the user's current plan. That file —
+   never the HTML — is the source of truth.
+
+Re-read the JSON right before you act on it. The user may have kept editing while you were talking.
+
+### C. No server available — export or paste (fallback)
+Give the page a **Copy JSON** button (writes the state to the clipboard) and an **Export JSON**
+button (`Blob` + `<a download>`, which works even on `file://`). The user pastes the JSON into chat,
+or tells you where the download landed (usually `~/Downloads/figure-strategy.json`) and you read it.
+Higher friction and it costs tokens, so prefer B.
+
+**Do not rely on the File System Access API** (`showSaveFilePicker`). It is Chromium-only and needs a
+secure context — it does not work from a `file://` page. It *does* work when the page is served over
+localhost, but then option B is already available and is simpler and browser-agnostic.
+
+---
+
+## Layout — three columns, near-full width
+
+One row per proposed figure. Size the table to a standard screen: `width: 100%` with a
+`max-width: 1600px`, and let column 3 take the slack. Keep rows aligned to a grid so the eye can scan
+down a column.
+
+| # | Column | Width | Contents |
+|---|--------|-------|----------|
+| 1 | **Icon / image** | ~240–320px, fixed | The visual: a snapshot cropped from a source document, or a generated SVG preview. Fixed width so every row's art lines up. |
+| 2 | **Description** | ~28–32% | An **editable text field** (`<textarea>`) — a short description of what this figure shows about the invention. 1–3 sentences. This becomes the figure's `briefDescription`. |
+| 3 | **Components** | remaining (widest) | An **editable list** of the figure's components/steps. Add / remove / reorder rows. Each row is a label plus optional text. Numbers are NOT edited here — they are derived (see Numbering). |
+
+Also per row: the figure **type** (`Flowchart` / `Device` / `Placeholder`) and a control to
+**add, remove and reorder** whole figures. Reordering is the whole point of the exercise — make it
+easy.
+
+Every editable control writes into the state object and triggers the debounced autosave. If an edit
+cannot reach `figure-strategy.json`, the document is decorative and you have lost the user's work.
+
+---
+
+## Source documents and previews
+
+The user may bring **several** sources — the disclosure, related applications, an earlier spec. Ask
+for all of them up front, and record which source each proposed figure came from (show it as a
+caption under the icon, and keep it in the state as `source`). It tells the user *why* a figure is
+being proposed, and tells you where to go back for detail.
+
+### Start from the figures the sources ALREADY have
+
+**Before you propose a single new figure, scan every source document for figures that already
+exist** — block diagrams, architecture diagrams, schematics, flowcharts, plots, graphs. The
+inventor has usually already drawn the invention; proposing a fresh figure set while ignoring their
+drawings is how a strategy worksheet ends up describing a different invention from the disclosure.
+
+Every existing figure becomes a worksheet row, before any new ones:
+
+- **Preview** — a snapshot crop of the actual drawing, embedded as a `data:` URI.
+- **Provenance** — say exactly where it came from, e.g. "Figure 1 of the disclosure", "FIG. 3 of
+  US 11,123,456". Put it in the caption and in the state's `source`.
+- **Type** — a diagram-type source (block diagram, architecture, schematic) becomes a **Device** or
+  **Flowchart** row whose components/steps **mirror the blocks in the source figure**: take the
+  labels off the drawing rather than inventing your own. A data graph or plot (a results chart, a
+  loss curve) becomes a **Placeholder** row flagged as **custom art** — it cannot be generated by
+  the Visio renderer and needs a draftsperson.
+
+Only once every source figure is on the worksheet do you add the new ones — claim flowcharts, the
+apparatus/system diagram, and any figure the claims need but the disclosure lacks.
+
+Column 1's visual comes from one of two places:
+
+- **Snapshot** — a crop of an actual drawing from a source document (a figure from a related
+  application, a whiteboard photo in the disclosure). Embed it as a `data:` URI so the HTML stays
+  self-contained and survives being moved.
+- **Dynamic SVG** — for a figure that does not exist yet, generate a preview in the Fenix drawing
+  style. Follow `references/diagram-svg-guide.md` in the **fenix-diagram** skill (square-cornered
+  steps, rounded input/output boxes, filled arrows, S-curve lead lines, reference numerals). Inline
+  the SVG so it scales cleanly and can be regenerated when the components change.
+
+A preview is a sketch, not the final drawing. Say so on the page. The real drawing comes from
+`read {resource:"patent-document", options:{type:"drawings"}}` after the figures are saved.
+
+---
+
+## State shape (what the page reads and writes)
+
+Keep it flat and close to the Fenix figure shape so the handoff is mechanical:
+
+```json
+{
+  "matter": "8828-700",
+  "sources": [{ "id": "disc", "name": "Disclosure.docx" }],
+  "figures": [
+    {
+      "id": "f1",
+      "type": "Device",
+      "source": "disc",
+      "preview": { "kind": "svg", "content": "<svg .../>" },
+      "description": "The overall media generation system and its major components.",
+      "components": [{ "label": "processor", "text": "execute the instructions" }]
+    }
+  ]
+}
+```
+
+`preview.kind` is `"svg"` or `"image"` (a `data:` URI). Do not put figure or element **numbers** in
+this file — they are derived on the way out, and holding stale numbers here invites the renumbering
+bugs the figures workflow exists to prevent.
+
+---
+
+## Handing off to the figures workflow
+
+When the user is done:
+
+1. **Re-read `figure-strategy.json`** — do not use the copy you had in context.
+2. Confirm the final list with them — **END TURN** — do not skip this.
+3. Convert each entry to a figure object: `description` → `briefDescription`; `components` →
+   `components` (type `Device`) or `steps` (type `Flowchart`). Content MUST go under `steps` or
+   `components`, never a generic `elements` list, or the figure prints as a blank page (see
+   `references/figures.md`, "Figure object shape").
+4. **Number everything now**, in final order: figures sequential and gap-free; each element derived
+   from its figure's number (flowchart `N00, N05, ...`; device `N05, N10, ...`). This is the
+   Renumbering invariant — the strategy document deliberately carries no numbers, so apply them here.
+5. `write {resource:"project", action:"save", options:{type: "figures", figures: allFigures}}` — include **every** figure, existing and
+   new.
+6. Continue at Phase 2 of `references/figures.md` to fill in each figure's content.

package/skills/fenix-application/references/figures-guidance.md

@@ -1,6 +1,6 @@
 # Figures Guidance
 
-**Version: 21**
+**Version: 48**
 
 ## Figure List
 

package/skills/fenix-application/references/figures.md

@@ -1,44 +1,81 @@
 # Figures Workflow
 
-**Version: 21**
+**Version: 48**
 
 ## ⚠️ Renumbering invariant (applies at EVERY point in the process)
-Figures are numbered **sequentially with no gaps** (FIG. 1, 2, 3, ...), and **every element number is derived from its figure's number** -- flowchart steps `N00, N05, N10, ...` and device components `N05, N10, ...`, where `N` is the figure number (see `## Numbering` and `references/figures-guidance.md`).
+Figures are numbered **sequentially with no gaps** (FIG. 1, 2, 3, ...), and **every element number is derived from its figure's number** -- flowchart steps and device components alike run `N05, N10, N15, ...`, where `N` is the figure number. `N00` is NOT an element: it is the figure's own numeral ("the system 100"), so nothing starts at `N00` (see `## Numbering`).
 
 **So ANY time the figure set changes -- a figure is ADDED, REMOVED, reordered, or template figures are IMPORTED (at intake, in Phase 1, in Phase 2, or via the editor) -- you MUST renumber BEFORE saving:**
 1. Renumber the **figures** so they remain sequential and gap-free.
-2. Renumber **every affected figure's steps/components** to match its new figure number -- e.g. if FIG. 2 becomes FIG. 3, its `205, 210, ...` components become `305, 310, ...`.
+2. Renumber **every affected figure's steps/components** to match its new figure number -- e.g. if FIG. 2 becomes FIG. 3, its `205, 210, ...` components become `305, 310, ...`. Change ONLY the figure-number prefix; **keep each element's two-digit suffix exactly as it was** (`220` -> `320`, never `315`). The suffix is what the drawing draws, so re-sequencing it to close a gap breaks the match with the artwork.
 
 Never leave a figure or an element number out of sync with its figure's position. **Importing template figures is the most common trap** -- the template's figure and element numbers will not line up with your set, so renumber them in. This is not optional and not only an end-of-phase step: renumber the moment the set changes, every time.
 
 ## Phase 1  --  List
-0. **Ask up front how the user wants to start the figure list** -- e.g. "Want to start the figures from a template, from a figure-strategy document you have, or draft them from scratch?" Three options:
-   - **From a template:** `list_patent_templates` -> let the user pick -> import with `save_project({ templateId })` so the template's figures become the starting set, **then renumber the imported figures and all their steps/components into your set** (see the Renumbering invariant -- template numbers will not match). (Skip this option if a template/source was already imported during intake.)
-   - **From a figure strategy document:** if the user has a document describing the intended figures (which figures, what each illustrates, key steps/components), ask them to provide or upload it, then read it and use it to build the figure list (interpret it against `references/figures-guidance.md`).
+0. **Ask up front how the user wants to start the figure list** -- e.g. "Want to start the figures from a template, plan them together in a figure-strategy worksheet, from a figure-strategy document you already have, or draft them from scratch?" Four options:
+   - **From a template:** `read {resource:"patent-templates"}` -> let the user pick -> import with `write {resource:"project", action:"save", options:{templateId}}` so the template's figures become the starting set, **then renumber the imported figures and all their steps/components into your set** (see the Renumbering invariant -- template numbers will not match). (Skip this option if a template/source was already imported during intake.)
+   - **Build a figure-strategy worksheet (recommended when there are source documents):** an editable
+     3-column HTML worksheet -- a preview image/SVG of each proposed figure, a short description, and
+     an editable component list -- built from the user's disclosure and any related applications. The
+     user edits it directly and you read their edits back. Read `references/figure-strategy.md` and
+     follow it; it hands you the figure list, then continue from step 1.
+     **A `file://` page cannot save itself** -- serve it with `scripts/figure_strategy_server.py` and
+     read `figure-strategy.json`, or the user's edits are invisible to you.
+   - **From a figure strategy document:** if the user already has a document describing the intended figures (which figures, what each illustrates, key steps/components), ask them to provide or upload it, then read it and use it to build the figure list (interpret it against `references/figures-guidance.md`).
    - **From scratch:** plan the figure list from the disclosure.
    Then continue from step 1.
-1. `get_project({ projectId, include: ["figures"] })`  --  note ALL figures including Placeholders
+1. `read {resource:"project", options:{projectId, include: ["figures"]}}`  --  note ALL figures including Placeholders
 2. Use `references/figures-guidance.md` for figure list planning
 3. Number new figures from max(existing)+1
 4. Show ALL figures  --  **END TURN**  --  confirm
-5. `save_project({ type: "figures", figures: allFigures })`  --  never omit existing figures
+5. `write {resource:"project", action:"save", options:{type: "figures", figures: allFigures}}`  --  never omit existing figures
 
 ## Phase 2  --  Content (one figure at a time)
 Skip Placeholders (type="Placeholder" or empty steps/components).
 For each: read `references/figures-guidance.md` -> generate -> show  --  **END TURN** -> confirm, then move to the next figure.
-**Do NOT save after each figure** -- it is slow. Accumulate the confirmed figures and **save the whole set once** at the end of the pass with `save_project({ type: "figures", figures: allFigures })` (include every figure, existing + new).
+**Do NOT save after each figure** -- it is slow. Accumulate the confirmed figures and **save the whole set once** at the end of the pass with `write {resource:"project", action:"save", options:{type: "figures", figures: allFigures}}` (include every figure, existing + new).
+
+## Figure object shape (get this right or the figure renders BLANK)
+The Visio renderer reads a figure's content from the **`steps`** array (flowcharts) or the **`components`** array (device diagrams) — **not** a generic `elements` list. Content put under any other key renders as a blank page.
+- **Flowchart** → `type: "Flowchart"`, content in `steps`.
+- **Device / component diagram** → `type: "Device"`, content in `components`.
+- Element shape (both): `{ "number", "label", "text", "type": "step" | "component" }`.
+- Valid figure `type` values: `Flowchart`, `Device`, `Placeholder`. **There is no `"Diagram"` type** — it renders nothing.
+
+```json
+{ "number": "13", "type": "Flowchart", "briefDescription": "...",
+  "steps": [ { "number": "1305", "label": "receive", "text": "receiving the message", "type": "step" } ], "components": [] }
+{ "number": "15", "type": "Device", "briefDescription": "...",
+  "steps": [], "components": [ { "number": "1505", "label": "receiver", "text": "a receiver", "type": "component" } ] }
+```
+
+**Verify before printing:** run `calculate_figure_layout.py` — every flowchart must show a non-empty `steps` list and every device `componentCount > 0`. An empty `steps: []` / `components: []` in the layout output means the content is under the wrong key and the figure will print blank.
 
 ## Numbering
-- Flowchart steps: 100, 105, 110...
-- Device components: figureNum05, figureNum10... (never figureNum00)
+
+A reference numeral is `<figure number><two-digit suffix>`. The suffix is the element's identity;
+the figure number is just a prefix.
+
+- Flowchart steps: `N05, N10, N15, ...`
+- Device components: `N05, N10, N15, ...`
+- **`N00` is never an element.** It is the FIGURE's own numeral -- the thing the figure as a whole is
+  called ("the system 100", "the method 400"). Numbering a step `100` collides with it: the spec
+  then uses one numeral for two different things, and the drawing labels the wrong shape. Both step
+  and component numbering start at `N05`.
 - Every element needs `type`: "step" or "component"
 
+**The suffix is permanent.** When a figure moves -- FIG. 2 becomes FIG. 3 -- only the PREFIX
+changes: `205, 210, 220` becomes `305, 310, 320`. Do not renumber the suffixes into a tidy
+sequence. They are what the drawing draws (each shape in the Visio stencil carries its own fixed
+suffix), so closing a gap in the spec silently breaks the correspondence with the artwork. Gaps are
+normal and are often deliberate.
+
 ## ElementSchema
 `{ type, label, number, text, name, action, angle, flipX, flipY }`
 
 ## Editor (accordion)
-**Always ask the user whether they want to open the figures editor to review/edit all figures at once** -- e.g. "Want me to open the figures editor so you can review them all together?" Only open it if they say yes. **In Cowork, prefer the live figures editor:** `get_live_artifacts({ name: "figures-editor" })`, substitute `__PROJECT_ID__` (project id) and `__SERVER_PREFIX__` (your MCP tool prefix, e.g. `mcp__<id>__` — see `references/editors.md`) in the returned HTML, and open it — it loads the current figures and **saves them itself**; when the user pastes a `[FIGURES SAVED - figuresRev N]` block, apply that delta and do **not** call `save_project` again (see `references/editors.md`). **Otherwise (non-Cowork), open `assets/figures_editor.html`** with `INITIAL_CONTENT` set to the full figures JSON array. Each figure is a collapsible accordion item; opening one reveals its number, type, brief description, and a steps/components table with add/remove rows. There is no introductory-sentence field -- the figure's introductory/opening sentence is generated from its brief description during spec drafting. The user can also add/remove whole figures -- **after any add/remove, renumber the figures and their steps/components** (see the Renumbering invariant) before saving. On `[EDITOR SUBMIT - figures]`, strip the prefix and call `save_project({ type: "figures", figures: [...] })` with the returned array.
+**Always ask the user whether they want to open the figures editor to review/edit all figures at once** -- e.g. "Want me to open the figures editor so you can review them all together?" Only open it if they say yes. To open it: call `write {resource:"context", options:{ids: { projectId }, label: "<matter number>"}}` to bind the matter, then tell the user to open the **installed Fenix Patent Editor** (Figures view) from their artifacts sidebar. **Never write, edit, or substitute anything into the artifact**; see `references/editors.md`. When the user pastes a `[FIGURES SAVED - figuresRev N]` block, apply that delta and do **not** call `write {resource:"project", action:"save"}` again. The editor has no introductory-sentence field -- the figure's introductory/opening sentence is generated from its brief description during spec drafting. **After any add/remove of whole figures, renumber the figures and their steps/components** (see the Renumbering invariant) before they are saved.
 
 ## After all figures
-Run `scripts/calculate_figure_layout.py` with the figures JSON -> check `warnings` array and `readyToPrint` flag. **Do NOT print automatically.** Only call `print_patent(type=drawings)` if the user explicitly asks for the drawings file. After figures are saved and the layout is clean, simply tell the user the figures are ready and ask whether they want the drawings file generated.
-**When you do run `print_patent(type=drawings)`, always show the user the returned download URL/link in your reply** -- do not run the print silently. Surface the link (e.g. "Drawings ready: <url>") so they can open it.
+Run `scripts/calculate_figure_layout.py` with the figures JSON -> check `warnings` array and `readyToPrint` flag. **Do NOT print automatically.** Only call `read {resource:"patent-document", options:{type:"drawings"}}` if the user explicitly asks for the drawings file. After figures are saved and the layout is clean, simply tell the user the figures are ready and ask whether they want the drawings file generated.
+**When you do run `read {resource:"patent-document", options:{type:"drawings"}}`, always show the user the returned download URL/link in your reply** -- do not run the print silently. Surface the link (e.g. "Drawings ready: <url>") so they can open it.

package/skills/fenix-application/references/patent-review-checklist.md

@@ -1,4 +1,4 @@
-# Pre-Filing Checklist (16 items)
+# Pre-Filing Checklist (18 items)
 
 | # | Check | Notes |
 | --- | --- | --- |
@@ -18,6 +18,8 @@
 | 14 | Reference numerals consistent | Same numeral = same element. No orphans. |
 | 15 | Cross-reference to provisional/foreign priority | For rewrites. |
 | 16 | Equations correct and formatted | Check against disclosure documents. |
+| 17 | Fonts standard and embeddable | Flag any non-standard / web font (e.g. Google Sans, Roboto). The USPTO requires legible standard fonts (Times New Roman, Arial, Courier) fully embedded in the PDF  --  MPEP 608.01 / 37 CFR 1.52(b). Non-standard or non-embedded fonts are rejected at Patent Center upload or draw a Notice to File Corrected Application Papers. |
+| 18 | Figure components set to generate | Every component of a **non-boilerplate** figure has `generateElement: true` (else it gets no Visio box and no description text  --  it is treated as background/boilerplate). Boilerplate figures leave it off. Include `figures` in `read {resource:"project"}` to inspect components. |
 
 ## General Issues