fenix-claude-plugin 0.1.3 → 0.2.0

package/commands/fenix-install.md

@@ -1,17 +1,25 @@
 ---
-description: Refresh the Fenix patent skills from the server (per-firm customized, latest version)
+description: Refresh Fenix skills and install the current Fenix Workspace
 ---
 
-The Fenix plugin ships a **static snapshot** of the patent skills so they work the moment you install it. Run this command to pull the **latest, firm-customized** versions from the connected Fenix server (the snapshot is a generic default; your server account may customize the prompt content).
+The plugin ships a static snapshot of the current Fenix skills and workspace.
+Use the Fenix MCP's two-tool interface; do not call the retired
+`install_fenix_skills` tool.
 
-For each skill — `fenix-application`, `fenix-office-action`, `fenix-project`:
+1. Confirm the connector is live with `read({ resource: "schema" })`.
+2. To refresh a firm-customized skill, call:
+   `read({ resource: "skills", options: { skill: "fenix-application" } })`
+   Repeat for `fenix-office-action` and `fenix-project`. If a local `VERSION`
+   exists, include it as `fromVersion` in `options`. Do not overwrite an existing
+   `CUSTOMIZE.md`.
+3. To install the Fenix Workspace, call:
+   `read({ resource: "artifacts", name: "fenix-workspace" })`.
+   Save the returned HTML verbatim as `fenix-workspace.html` and open it as a
+   live artifact in a desktop-side session. Do not edit or substitute anything
+   in the returned HTML; its embedded permissions grant access to Fenix `read`
+   and `write`.
 
-1. Call the `install_fenix_skills` MCP tool with that `skill` name. If the skill is already installed locally, read its `VERSION` file and pass `fromVersion` so the server returns only changed files (incremental update).
-2. Follow the `nextStep` in the response to save it.
-3. **Never overwrite an existing `CUSTOMIZE.md`.** If a local `CUSTOMIZE.md` already exists for the skill, keep that existing file and discard the downloaded copy — it holds the user's own customizations.
+If the Fenix `read` tool is absent or reports that it is still connecting, run
+`/reload-plugins` or restart Claude Code. A 401 means the personal access code
+has not been configured; run `/fenix-setup` and reload.
 
-The connector is configured by this plugin and **infers your firm (client + database) from your single API key**, so never pass a `clientDb` or client argument to any tool — let it default.
-
-If the `install_fenix_skills` tool is **not available** (you can't find it, or the `fenix` server shows "still connecting" in `/mcp`), the plugin's MCP server hasn't started in this session. Run **`/reload-plugins`** (or fully restart Claude Code), then retry — do not give up after one lookup.
-
-If `install_fenix_skills` returns **401/unauthorized**, the API key isn't set or is wrong — run `/fenix-setup`, then `/reload-plugins`.

package/commands/fenix-setup.md

@@ -1,19 +1,24 @@
 ---
-description: Configure the Fenix plugin's API key (one key; client and database are inferred)
+description: Configure the Fenix plugin's personal MCP access code
 ---
 
-Help the user connect the Fenix plugin. **Only one value is needed: a single API key.**
+Help the user connect the Fenix plugin. Only one value is needed: a personal
+Fenix MCP access code.
 
-1. Confirm the user has a **Fenix API key** (issued by Fenix for their firm). The server maps this key to their account and **infers the client and database from it** — they never provide a client name, database, or any second value.
-2. The connector reads the key from the **`FENIX_API_KEY`** environment variable and sends it as a bearer token to `https://claude.fenix.ai/api/plugin`.
-3. Guide them to set `FENIX_API_KEY` (do not type the key into chat; have them set it themselves):
-   - **macOS / Linux:** add `export FENIX_API_KEY="<their key>"` to `~/.zshrc` or `~/.bashrc`.
-   - **Windows (PowerShell):** run `setx FENIX_API_KEY "<their key>"`.
-4. **Reload so the connector picks up the key — this step is required.** The Fenix MCP server only connects at session startup, so after setting the key the user must **run `/reload-plugins`** (or fully quit and reopen Claude Code, and reopen the terminal so the new env var is in scope). Without this, the `fenix` server stays unconnected even with a valid key.
-5. Verify with `/mcp` — the `fenix` server should show **connected** with tools. Then call a read-only tool such as `get_project` (or run `/fenix-install`).
+1. Confirm that the user has a personal access code from Fenix: **Settings > MCP Access**.
+   The code identifies both the user and the firm; never ask for a client name or database.
+2. The connector reads the code from `FENIX_MCP_TOKEN` and sends it as a bearer
+   token to `https://claude.fenix.ai/chau/mcp`.
+3. Have the user set `FENIX_MCP_TOKEN` themselves. Never request or repeat the code in chat.
+   - macOS/Linux: add `export FENIX_MCP_TOKEN="<their code>"` to `~/.zshrc` or `~/.bashrc`.
+   - Windows PowerShell: run `setx FENIX_MCP_TOKEN "<their code>"`.
+4. Run `/reload-plugins`, or fully restart Claude Code after reopening the terminal.
+5. Verify in `/mcp` that `fenix` is connected and exposes `read` and `write`.
+   Verify service access with `read({ resource: "schema" })`.
 
-## Troubleshooting
-- **`fenix` server shows "still connecting" / no Fenix tools (install_fenix_skills, get_project) appear:** the server hasn't started in this session. Run **`/reload-plugins`**, or fully restart Claude Code. ("Still connecting" is NOT an auth error — a bad key shows as "Failed to connect.")
-- **"Failed to connect" / 401:** the key is missing or wrong. Confirm `FENIX_API_KEY` is set **in the environment Claude Code was launched from** (set it, reopen the terminal, then `/reload-plugins`).
+Troubleshooting:
+
+- **Still connecting / no `read` or `write`:** reload the plugins or restart Claude Code.
+- **401 / Failed to connect:** the code is missing, expired, or invalid. Set
+  `FENIX_MCP_TOKEN` in the environment Claude Code was launched from, then reload.
 
-Never print, log, or store the key anywhere other than the environment variable.

package/package.json

@@ -1,16 +1,16 @@
-{
-  "name": "fenix-claude-plugin",
-  "version": "0.1.3",
-  "description": "Fenix patent automation plugin for Claude Code — MCP connector plus patent drafting, office-action, and project skills.",
-  "license": "UNLICENSED",
-  "homepage": "https://claude.fenix.ai",
-  "keywords": ["claude", "claude-code", "claude-plugin", "patent", "fenix", "mcp"],
-  "files": [
-    ".claude-plugin/",
-    ".mcp.json",
-    "commands/",
-    "skills/",
-    "artifacts/",
-    "README.md"
-  ]
-}
+{
+  "name": "fenix-claude-plugin",
+  "version": "0.2.0",
+  "description": "Fenix patent automation plugin for Claude Code — tenant-aware MCP connector, Fenix Workspace, and current patent skills.",
+  "license": "UNLICENSED",
+  "homepage": "https://claude.fenix.ai",
+  "keywords": ["claude", "claude-code", "claude-plugin", "patent", "fenix", "mcp"],
+  "files": [
+    ".claude-plugin/",
+    ".mcp.json",
+    "commands/",
+    "skills/",
+    "artifacts/",
+    "README.md"
+  ]
+}

package/skills/fenix-application/SKILL.md

@@ -6,7 +6,7 @@ description: >-
 
 # Fenix Application
 
-**Skill version: 21** (authoritative version is in the top-level `VERSION` file; this line is for reference only).
+**Skill version: 48** (authoritative version is in the top-level `VERSION` file; this line is for reference only).
 
 ## Triggers
 
@@ -29,11 +29,12 @@ description: >-
 
 ## Customization
 
-Before applying any workflow in this skill, read the `CUSTOMIZE.md` file in this skill directory. If it contains anything other than the placeholder text "place custom instructions here", treat its contents as user overrides that take precedence over the default instructions in this SKILL.md and its reference files.
+User overrides for this skill live in a `CUSTOMIZE.md` file in this skill directory. This file is **not shipped with the skill** -- it belongs to the user. **If `CUSTOMIZE.md` does not already exist in this skill directory, create it now** containing exactly the single line `place custom instructions here`. **If it already exists, never overwrite it** -- it holds the user's own instructions.
+
+Before applying any workflow in this skill, read `CUSTOMIZE.md`. If it contains anything other than the placeholder text "place custom instructions here", treat its contents as user overrides that take precedence over the default instructions in this SKILL.md and its reference files.
 
 Apply the custom overrides **only as long as the result still satisfies every structured-output contract** this skill depends on, including:
 - the JSON shapes passed to `save_project` (claims, figures, sections)
-- the `[EDITOR SUBMIT - <type>]` clipboard prefixes produced by the HTML editors
 - the figure ElementSchema (`type`, `label`, `number`, `text`) and component numbering rules
 - the spec section names and ordering required by the save/print tools
 
@@ -45,10 +46,11 @@ Custom instructions may freely change tone, phrasing, default counts, section pr
 - `references/claim1-method-drafting.md`  --  house style for an independent method claim 1 (skeleton, wherein rules, verb/lexicon, budgets, procedure)
 - `references/figures.md`  --  Phase 1+2 figure workflow
 - `references/spec.md`  --  spec section workflow
-- `references/editors.md`  --  exact INITIAL_CONTENT shapes + submit handling for the 3 HTML editors (read this instead of the editor HTML)
+- `references/figure-strategy.md`  --  interactive figure-strategy worksheet (3-column editable HTML built from the source documents; how to read the user's edits back)
+- `references/editors.md`  --  how to open and drive the installed live editors (and the one rule: never edit artifact HTML)
 - `references/patent-safe.md`  --  language guidelines
 - `references/figure-description.md`  --  figure description protocol
-- `references/disclosure.md`  --  disclosure interview
+- `references/disclosure.md`  --  the disclosure: item SCHEMA, where an item goes, the save contract, and the interview
 - `references/figures-guidance.md`  --  figure planning prompts
 - `references/spec-guidance.md`  --  spec section prompts
 - `references/patent-review.md`  --  pre-filing review workflow (6-section checklist)
@@ -56,15 +58,13 @@ Custom instructions may freely change tone, phrasing, default counts, section pr
 - `references/patent-review-claim-formats.md`  --  Method/CRM/System/Training templates
 - `references/patent-review-advantages.md`  --  advantages paragraph template
 - `references/patent-review-profanity.md`  --  patent profanity term list
-- `assets/claims_editor.html`  --  accordion editor for ALL claims (open any claim to edit; keeps claims parsed; outputs a JSON claim array in the Fenix schema)
-- `assets/figures_editor.html`  --  accordion editor for ALL figures (open any figure to edit its steps/components table; outputs figures JSON array)
-- `assets/spec_editor.html`  --  accordion editor for ALL spec sections, each figure description its own section (outputs sections JSON object)
 - `scripts/parse_claims.py`  --  local claims parser
 - `scripts/calculate_figure_layout.py`  --  local layout calculator
+- `scripts/figure_strategy_server.py`  --  serves the figure-strategy worksheet and persists the user's edits to figure-strategy.json (a file:// page cannot save itself)
 
 ## Staying current
 
-This is **fenix-application** version 21. Every `get_project` response includes a `_fenix.skillVersions` map of the server's authoritative skill versions. When you load a project, compare `_fenix.skillVersions["fenix-application"]` to 21: if the server value is higher, a newer version of this skill is available -- tell the user and offer to run `/fenix-install` (or update the Fenix plugin) before continuing. Do not silently keep working on a stale skill.
+This is **fenix-application** version 48. Every `get_project` response includes a `_fenix.skillVersions` map of the server's authoritative skill versions. When you load a project, compare `_fenix.skillVersions["fenix-application"]` to 48: if the server value is higher, a newer version of this skill is available -- tell the user and offer to run `/fenix-install` (or update the Fenix plugin) before continuing. Do not silently keep working on a stale skill.
 
 ## How to use
 
@@ -75,7 +75,7 @@ Read the relevant section below for the task at hand, then follow it to the spec
 Trigger when the user wants to describe a new invention or answer disclosure questions:
 - "run the disclosure interview" / "gather the disclosure" / "new invention"
 
-Read `references/disclosure.md` for the structured interview protocol. Captures technical field, problem, inventive concept, method steps, components, variations, examples, and prior art.
+Read `references/disclosure.md`. It carries the ITEM SCHEMA (the four item types and their fields), what `insertedInSection` may hold -- a spec section, a figure, a GROUP, or `""` for excluded -- the destructive-replace save contract, and the interview protocol for the case where there is no document.
 
 ## Review a patent application
 
@@ -93,8 +93,31 @@ Trigger when the user asks to review, audit, red-line, or check a patent applica
 
 ## Draft a patent application
 
+**Before anything else, make sure the matter has a Fenix project.** Every claim, figure, and section saves INTO a project, so drafting without one has nowhere to go. Search first: `read {resource:"project", options:{identifier}}` (exact matter/application number) or `read {resource:"project", options:{query}}` (keyword). If a project already exists, use it. If none does, do NOT start drafting and do NOT invent one silently -- gather the five intake fields (matter/application number, notification date, project type, due date, assignee initials) and create it with `write {resource:"project", action:"create"}`, then confirm the returned project id before saving anything. The `fenix-project` skill covers that intake flow. Only then continue to the phases below.
+
 Read `references/patent.md` for the 3-phase workflow overview. Phase-specific references:
 - **Claims**: `references/claims.md`, `references/claim1-method-drafting.md` (method claim 1 house style), `references/patent-safe.md`
-- **Figures**: `references/figures.md`, `references/figures-guidance.md`
+- **Figures**: `references/figures.md`, `references/figures-guidance.md`, `references/figure-strategy.md` (plan the figure set with the user in an editable worksheet first)
 - **Spec**: `references/spec.md`, `references/spec-guidance.md`, `references/figure-description.md`
-- **Disclosure interview**: `references/disclosure.md`
+- **Disclosure**: `references/disclosure.md`
+
+## Saving to Fenix -- hand a big save to a background agent
+
+A finished disclosure set, a full claim set, or a whole specification is a large payload, and in the main conversation it costs you **twice**: once in the call you write out, and again in the result echoed back. It also blocks -- you sit through the round trip instead of working with the user.
+
+So when a payload is large and the content is already settled, **delegate the save**:
+
+1. **Write the payload to a file** -- e.g. `disclosure.json`, holding the complete array. This is the step that actually saves anything: the agent reads the file, so the JSON never passes through the conversation a second time. Pasting the payload into the agent's prompt instead saves nothing at all.
+2. **Spawn a background agent** whose prompt (a) names the file, (b) states the exact call to make, and (c) says what to report back.
+3. **Keep working** with the user while it runs -- then **check its result before you rely on the save**. A save you never confirmed is not a save.
+
+A prompt of the right shape:
+
+> Read `<path>/disclosure.json`. Make exactly one call: `write {resource:"project", action:"save", options:{projectId:"<id>", type:"disclosure", baseRev:<rev>, disclosure:<the file's contents>}}`. Do not edit, re-word, re-order or add to the content -- it is approved work product. Reply with `itemCount`, `includedCount` and `disclosureRev` from the response, or the full error if it failed.
+
+**Rules**
+- The agent **saves; it does not draft**. Drafting is settled with the user in the main conversation, and an agent asked to "finish" or "improve" anything will write work product nobody approved.
+- **Only for saves that are large and settled.** One section, or a two-item change, costs more to delegate than to call.
+- **Pass `baseRev`** (the rev you loaded). A background save is exactly the case where someone else -- the user, in the editor -- may have changed the same data meanwhile; with `baseRev` a stale save is rejected (409) instead of silently overwriting them.
+- **One save per agent, and never two agents on the same group.** A `type:"disclosure"` (or `type:"claims"`) save REPLACES the whole set, so two of them race and the loser's work is gone.
+- **The agent needs the same Fenix connection you have.** If your host cannot run a background agent, or the agent cannot reach the Fenix tools, just make the call yourself -- that is always the fallback, and a delegated save that never happened is worse than a slow one.

package/skills/fenix-application/VERSION

@@ -1 +1 @@
-21
+48

package/skills/fenix-application/references/claim1-method-drafting.md

@@ -1,6 +1,6 @@
 # Method Claim 1 Drafting Guide
 
-**Version: 21**
+**Version: 48**
 
 House style for drafting an **independent method claim 1**, especially for AI/ML
 inventions. Use this whenever you draft a method independent claim. (Apparatus/CRM/

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

@@ -1,6 +1,6 @@
 # Claims Workflow
 
-**Version: 21**
+**Version: 48**
 
 ## Before drafting
 Read `references/patent-safe.md` for language guidelines.
@@ -21,12 +21,11 @@ Claims flow through the system **parsed**, as an array of claim objects -- not r
 Parse claims into this schema yourself with `scripts/parse_claims.py` (pipe the text in, or `--file claims.txt --pretty`). Keep the claims in this parsed form from drafting through save -- do not flatten back to raw text. Holding the schema also lets you make structural edits directly (renumber, relink a dependent, etc.).
 
 ## Editor (accordion)
-**Always ask the user whether they want to open the claims editor to review/edit the full set** before (or instead of) the one-at-a-time pass -- e.g. "Want me to open the claims editor so you can review them all at once?" Only open it if they say yes. **In Cowork, prefer the live claims editor:** `get_live_artifacts({ name: "claims-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 claims and **saves them itself**; when the user pastes a `[CLAIMS SAVED - claimsRev N]` block, apply that delta to your working set and do **not** call `save_project` again (see `references/editors.md`). **Otherwise (non-Cowork), open `assets/claims_editor.html`** and pre-fill `INITIAL_CONTENT` with the **parsed schema array** -- e.g. `INITIAL_CONTENT = [{"claimNumber":"1","claimStatus":"original","claimType":"independent","claimText":["A system comprising:","a processor; and","a memory."],"parent":"","independentParent":""}, ...]`. The editor shows every claim as a collapsible accordion item (open any claim to edit its number/text, add or remove claims) and **keeps the claims parsed**: on Copy it emits `[EDITOR SUBMIT - claims]` followed by a JSON array of schema objects. Strip the prefix and pass that array straight to save.
-
+**Always ask the user whether they want to open the claims editor to review/edit the full set** before (or instead of) the one-at-a-time pass -- e.g. "Want me to open the claims editor so you can review them all at once?" 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** (Claims view) from their artifacts sidebar. **Never write, edit, or substitute anything into the artifact** -- it discovers its own connector prefix and asks the server which matter to open; see `references/editors.md`. When the user pastes a `[CLAIMS SAVED - claimsRev N]` block, apply that delta to your working set and do **not** call `write {resource:"project", action:"save"}` again.
 ## Save (parsed array -- preferred)
-Call `save_project({ type: "claims", claims: [...] })` with the parsed schema array (from your parse or from the editor). The server persists the array and derives the claim tree the spec generator needs, then returns `parsedClaims` (the normalized array, with `claimType`/`parent`/`independentParent` re-derived server-side) and `treeBuilt: true`. You do not need to re-verify a structured save.
+Call `write {resource:"project", action:"save", options:{type: "claims", claims: [...]}}` with the parsed schema array (from your parse or from the editor). The server persists the array and derives the claim tree the spec generator needs, then returns `parsedClaims` (the normalized array, with `claimType`/`parent`/`independentParent` re-derived server-side) and `treeBuilt: true`. You do not need to re-verify a structured save.
 
 ## Save (raw text -- fallback)
-If you only have raw claim text, call `save_project({ type: "claims", rawClaims })`. The server parses it and returns `parsedClaims` plus a `parseVerification` object. Always check `parseVerification.ok`:
+If you only have raw claim text, call `write {resource:"project", action:"save", options:{type: "claims", rawClaims}}`. The server parses it and returns `parsedClaims` plus a `parseVerification` object. Always check `parseVerification.ok`:
 - `ok` true: clean parse. Done.
 - `ok` false: inspect `gaps` (missing numbers), `suspectedMerges` (a claim body starting with "N." -- a missed boundary), and `countMatches`. Re-parse the claims yourself into the schema array and re-submit via the parsed-array path above (NOT raw text). Common cause: a claim number not followed by a period (e.g. "4 A system" instead of "4. A system") merges two claims -- split them.

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

@@ -1,16 +1,122 @@
-# Disclosure Interview
+# Disclosure
 
-**Version: 2**
+**Version: 48**
 
-## Default approach
+## Default approach: adapt the documents, then let the user edit
 
-When the user wants to capture an invention disclosure, **start by asking for the disclosure document rather than conducting an interview**:
+When the user wants to capture an invention disclosure, **start by asking for the disclosure documents rather than conducting an interview**:
 
-1. Ask the user to upload their disclosure document (Word doc, PDF, or text).
-2. If working in a Cowork session with a project folder connected, check the folder for an existing disclosure document.
-3. Parse the uploaded/found document to extract: technical field, problem, inventive concept, method steps, system components, variations, examples, and prior art.
-4. Summarize what was extracted and ask the user to confirm or correct it.
-5. Save to the project: `save_project({ name, disclosure: structuredObject })`
+1. Ask the user to upload their disclosure document(s) (Word, PDF, or text). There may be **several** -- a disclosure, related applications, an earlier spec. Take all of them.
+2. In a Cowork session with a project folder connected, check the folder for existing disclosure documents.
+3. **Split each document into paragraphs** and, for every paragraph, write a patent-adapted rewrite and decide where it belongs -- a spec section, a figure group, or nowhere.
+4. Save the whole set to the PATENT record:
+
+   ```
+   write {resource:"project", action:"save", options:{ projectId, type:"disclosure", disclosure: [
+     { _localId: "d1", type: "text",
+       text: "<the paragraph, adapted to patent language>",
+       insertedInSection: "Background",
+       originalText: "<verbatim paragraph from the source document>",
+       source: "Disclosure.docx" }
+   ]}}
+   ```
+
+5. **Open the Fenix Patent Editor** (installed live artifact, Disclosure view) so the user can review it: each item's adapted text plus where it flows. They edit in place and the editor saves itself. Do NOT write or modify any HTML -- see `references/editors.md`.
+6. When they paste a `[DISCLOSURE SAVED - disclosureRev N]` block, it is already saved -- apply the delta, do **not** save again.
+
+## The schema
+
+The disclosure is a **flat array of items** on the patent record, and **the array order is the document order**: items flow into a section in the order they appear here.
+
+### Every item, whatever its type
+
+| Field | Type | Required | What it does |
+|---|---|---|---|
+| `_localId` | string | **yes** | This item's stable id, unique within the array. Keep it stable across saves -- a new id is a new item. |
+| `type` | `"text"` \| `"image"` \| `"stencil"` \| `"template_figure"` | **yes** | Which shape this item is. **Only `text` items reach the specification.** |
+| `insertedInSection` | string | **yes** | Where the item goes -- see below. `""` means kept on the record but excluded from the patent. |
+| `figureId` | string | only when assigned to a figure | The figure's stable key. See "A figure paragraph binds to the FIGURE". |
+| `group`, `responseIds` | -- | no | Editor bookkeeping (content library, AI response chains). Pass through untouched; never author them. |
+
+Unknown fields are **stored verbatim and returned unchanged**, so an item survives a round trip through Fenix intact. `originalText` and `source` above are this skill's own provenance convention on that basis -- they are preserved and are useful on a later pass, but no view renders them, so never rely on the user seeing them.
+
+### `type: "text"` -- the only kind that reaches the specification
+
+| Field | Type | Required | What it does |
+|---|---|---|---|
+| `text` | string | **yes** | The patent-adapted wording. Plain text or an HTML fragment; a paragraph that is not already `<p>...</p>` is wrapped when it flows into a section. |
+| `plainText` | string | no | A tag-free copy, when you have one. Nothing requires it. |
+
+### `type: "image"`
+
+| Field | Type | Required | What it does |
+|---|---|---|---|
+| `imageUrl` | string | **yes** | Where the image lives. |
+| `key` | string | **yes** | Its storage key. |
+| `filename`, `mimeType`, `extension` | string | no | As uploaded. |
+| `altText`, `caption` | string | no | Shown with the image. |
+| `width`, `height` | number | no | With `unit`: `"px"` or `"in"`. |
+
+### `type: "stencil"`
+
+| Field | Type | Required | What it does |
+|---|---|---|---|
+| `elements` | array | **yes** | Figure elements, in the figure `ElementSchema` shape (`type`, `label`, `number`, `text`, ...). |
+
+### `type: "template_figure"`
+
+| Field | Type | Required | What it does |
+|---|---|---|---|
+| `text` | string | **yes** | The paragraph text. |
+| `figure` | object | no | The figure this stands in for. |
+| `breif_description` | string | no | Spelled that way in the schema -- match it exactly. |
+| `introductory`, `detailed_description` | string | no | Prose around the figure. |
+
+**You author `text` items.** Image, stencil and template_figure items come from documents the user uploaded and from the editor. You will see them when you load a disclosure, and your job is to pass them back **unchanged** -- see the destructive-replace rule below.
+
+## Where an item goes: `insertedInSection`
+
+One field decides everything about an item's destination, and it takes four kinds of value.
+
+**1. A spec section** -- the text flows straight into that section, in array order:
+
+`Background` · `Introduction` · `Summary` · `Glossary` · `Examples` · `Additional Description` · `Field Of The Invention` · `Abstract` · `Clauses`
+
+**2. A figure section** -- `"Figure 3"`, plus `figureId`. The text is pulled into that figure's description.
+
+**3. A group** -- any other non-empty name. A group is a named bucket of related material that a **figure picks up later**, on the Figures tab, where `_DISCLOSURE` pulls the group's text in.
+
+Groups exist because of an ordering problem: the disclosure is adapted long **before** the figures exist, so "which figure does this paragraph describe?" is a question with no answer yet. A group answers the question that *can* be answered -- what is this paragraph *about*.
+
+So **give groups meaningful names** -- `"Training"`, `"Diffusion model"`, `"Data ingest"`. The drafter later chooses a group from a picker that shows only its name, and a good name tells them what is in it without opening it. `"Disclosure Group 1"`, `"Disclosure Group 2"` are the fallback for material with no obvious category yet, not the default.
+
+**4. `""`** -- excluded from the patent. The item stays on the record (and in the editor, where the user can include it later); it reaches no section. **This is the include flag** -- there is no separate boolean.
+
+### A figure paragraph binds to the FIGURE, not to its number
+
+`"Figure 3"` is positional. Insert a figure at the front and every one of those labels names a different drawing -- the paragraph about the diffusion model silently ends up under the U-Net, nothing errors, and the specification is simply wrong.
+
+So when you assign an item to a figure, also set **`figureId`** to that figure's stable key (its `figureId`, else `_id`, else `localId` -- whichever it already has). The label is then reconciled from the key whenever the figures move. If you do not have the figures yet, use a **group** instead; that is what groups are for.
+
+## Two different disclosures -- only one reaches the patent
+
+`write {resource:"project", action:"save", options:{type:"disclosure", disclosure:[...]}}` writes the item ARRAY to the **patent** record. That is the disclosure the Disclosure view shows, and the one whose text flows into the spec.
+
+A save with **no** `type` and a bare `disclosure` field writes free-form content to the **project** record instead. The Disclosure view never reads it and it never reaches the specification -- the call succeeds and nothing the user can see changes. **Do not capture a disclosure that way.**
+
+## A disclosure save REPLACES the whole array
+
+There is no partial disclosure save. Send **every item you want to keep**, including the image, stencil and template_figure items you are not touching, or you will delete them.
+
+1. Load first: `read {resource:"project", options:{projectId, include:["disclosure"]}}`. The response also carries `revs`.
+2. Apply your changes to that array.
+3. Save it back **whole**, and pass `baseRev: <the disclosure rev you loaded>`. With `baseRev` the save is **rejected** (409, `conflict:true`) if the disclosure changed in Fenix since you loaded -- the user editing in the Disclosure view is exactly that case. Without it, you overwrite their work silently.
+
+On success the response gives you `itemCount`, `includedCount` (how many carry a destination), `sections` (the destinations in use) and the new `disclosureRev`.
+
+## Saving a large set
+
+A finished disclosure set is a large payload. When it is settled, hand the save to a background agent rather than making the call yourself -- see **Saving to Fenix** in `SKILL.md`. Write the complete array to a file and let the agent read it: that is what keeps the JSON out of the conversation.
 
 ## Disclosure interview (only if explicitly requested)
 
@@ -30,4 +136,4 @@ In that case, ask questions in this order (one at a time, wait for each answer):
 7. Do you have examples or experimental results?
 8. What prior art are you aware of?
 
-After all answers: summarize, confirm with user, then `save_project({ name, disclosure: structuredObject })`.
+After all answers: summarize, confirm with the user, then write the answers up as disclosure paragraphs and save them the same way (step 4 above).