@stratta/mcp 0.9.3 → 0.9.5

package/README.md

@@ -1,216 +1,230 @@
-<!--
-Ownership marker for the official MCP registry. It must match `mcpName` in
-package.json exactly, and it must be present in the *published* tarball —
-the registry reads the README from npm, not from this repository. Without it
-`mcp-publisher publish` rejects the server as unverified.
-
-mcp-name: ch.stratta/mcp
--->
-
-# @stratta/mcp
-
-MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients via Stratta TreeRAG.
-
-> Requires a free Stratta account. Sign up at https://stratta.ch and generate an API key at https://stratta.ch/api-keys.
-
-> [!IMPORTANT]
-> Your `STRATTA_API_KEY` is a **secret** — it grants read/write access to your
-> Stratta workspace. Never commit it to a repository, paste it into a shared/
-> project-scoped MCP config, or share it in logs. Prefer a user-scoped config or
-> a shell environment variable. If a key leaks, revoke it immediately at
-> https://stratta.ch/api-keys.
-
-## Install
-
-### Claude Code (recommended)
-
-Add the server — no key needed up front:
-
-```bash
-claude mcp add stratta --scope user -- npx -y @stratta/mcp
-```
-
-`--scope user` registers it for your user, so the tools are there in every
-project. Without it, `claude mcp add` writes to the current folder's config and
-the server exists nowhere else.
-
-Then sign in. This opens stratta.ch in your browser, where you confirm which
-machine and organisation to authorise; the key comes back to the terminal on
-its own and is saved to `~/.stratta/config.json` (owner-only, `0600`). You
-never see it, and you only do this once:
-
-```bash
-npx -y @stratta/mcp login
-```
-
-No browser on this machine — remote server, SSH, CI? `login --paste` asks for a
-key from https://stratta.ch/api-keys instead, without echoing it.
-
-If you skip the step entirely, Claude Code prompts you for a key on the first
-tool call.
-
-You can also pass the key explicitly as an environment variable (it then takes
-precedence over the saved key):
-
-```bash
-claude mcp add stratta --scope user --env STRATTA_API_KEY=sk_strt_xxx -- npx -y @stratta/mcp
-```
-
-### Claude Desktop
-
-Sign in once from a terminal — the desktop app cannot prompt you interactively:
-
-```bash
-npx -y @stratta/mcp login
-```
-
-Then add the server to `claude_desktop_config.json` (Settings → Developer →
-Edit Config) — no key needed in the file:
-
-```json
-{
-  "mcpServers": {
-    "stratta": {
-      "command": "npx",
-      "args": ["-y", "@stratta/mcp"]
-    }
-  }
-}
-```
-
-Restart Claude Desktop. The Stratta tools should appear in the MCP indicator.
-
-> Prefer to keep the key in the config instead of `~/.stratta/config.json`? Add
-> an `"env": { "STRATTA_API_KEY": "sk_strt_xxx" }` block to the server entry —
-> but that file then stores the key in plaintext, so keep it private and unsynced.
-
-### Global install (optional)
-
-```bash
-npm install -g @stratta/mcp
-```
-
-Then use `"command": "stratta-mcp"` instead of `npx`.
-
-## Configuration
-
-The API key is resolved in this order: the `STRATTA_API_KEY` env var, then
-`~/.stratta/config.json` (written by `login` or the first-run prompt). Other
-settings come from environment variables — see [`.env.example`](./.env.example).
-
-| Variable             | Required | Default              | Purpose                                                                                                                                                        |
-| -------------------- | -------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `STRATTA_API_KEY`    | no¹      | –                    | API key from https://stratta.ch. ¹If unset, the server falls back to `~/.stratta/config.json`, or prompts you on first use (clients that support elicitation). |
-| `STRATTA_CONVEX_URL` | no       | Stratta prod backend | Override only if you self-host.                                                                                                                                |
-
-## Tools exposed
-
-**Read** (8 tools — query norms in your workspace):
-
-| Tool              | Purpose                                                                                |
-| ----------------- | -------------------------------------------------------------------------------------- |
-| `get_methodology` | Behavioural contract: persona, workflow, meta-routing hints, answer rules. Call first. |
-| `list_norms`      | List all norms published in your workspace (code, year, title, language).              |
-| `get_toc`         | Hierarchical TOC for a norm (default `maxDepth=1` = chapters).                         |
-| `get_subtree`     | Drill into a chapter/section subtree (`path` + `maxDepth`).                            |
-| `get_section`     | Full enriched content of a section (formulas, tables, figures, cross-refs).            |
-| `search_in_norm`  | Keyword search inside a norm.                                                          |
-| `get_figure`      | Retrieve a figure inline (base64 ImageContent) + public URL.                           |
-| `get_cross_refs`  | Outgoing cross-refs from a section to other norms.                                     |
-
-**Dossier** (5 tools — keep what was decided on a project):
-
-| Tool               | Purpose                                                                                           |
-| ------------------ | ------------------------------------------------------------------------------------------------- |
-| `list_dossiers`    | Your organisation's dossiers, most recently touched first, with open counts.                      |
-| `open_dossier`     | Open a project's dossier, creating it if needed. Idempotent on the name.                          |
-| `save_finding`     | Record one decision: a cited article, a retained value and why, an observation, an open question. |
-| `load_dossier`     | Reload everything, unresolved questions first. Accepts the id or the name.                        |
-| `resolve_question` | Mark a question settled. The entry stays; it stops surfacing at the top.                          |
-
-A dossier is read, annotated, reviewed and exported from
-[stratta.ch/dossiers](https://stratta.ch/dossiers).
-
-**Ingest** (10 tools — add YOUR licensed norms; driven by the bundled `ingest-norm` skill):
-
-| Tool                          | Purpose                                                      |
-| ----------------------------- | ------------------------------------------------------------ |
-| `ingest_status`               | Check if a norm already exists in your workspace.            |
-| `ingest_create_document`      | Create a draft norm document.                                |
-| `ingest_create_sections`      | Bulk-insert sections (returns `nodeId → sectionId` map).     |
-| `ingest_attach_formula`       | Attach a LaTeX formula to a section.                         |
-| `ingest_attach_table`         | Attach a structured table `{headers, rows}` to a section.    |
-| `ingest_attach_cross_ref`     | Attach an explicit cross-ref to another norm.                |
-| `ingest_upload_figure`        | Upload a figure (base64 PNG/JPEG/WebP, ≤ 8 MB) to a section. |
-| `ingest_normalize_cross_refs` | Auto-detect and rebuild cross-refs from section content.     |
-| `ingest_publish`              | Flip a draft to published — visible via the read tools.      |
-| `ingest_delete`               | Delete a document and all its children.                      |
-
-## How agents should use it
-
-For querying:
-
-1. Call `get_methodology` first — load the behavioural contract.
-2. Call `list_norms` to see what's available in your workspace.
-3. Call `get_toc(norm)` to navigate the structure; `get_subtree` to drill in.
-4. Call `get_section(norm, path)` to read specific content.
-5. Use `search_in_norm` when the section path is unknown.
-6. Follow `crossRefs` for compound questions (e.g. SIA 261 → SIA 263 → EC).
-7. Call `get_figure` when the section references a figure relevant to the answer.
-
-For ingesting your own licensed norms, see the bundled **`ingest-norm` skill** —
-a 2-phase hybrid pipeline (since 0.4.0): a Python pre-pass
-(`scripts/ingest-prepass.py`, PyMuPDF) extracts the hierarchical tree and
-rasterizes figures deterministically, then the agent enriches sections with
-summaries, LaTeX formulas, tables and cross-refs via targeted visual reading.
-Requires Python ≥ 3.10 with PyMuPDF (`python -m pip install --user pymupdf`).
-
-## Troubleshooting
-
-### `Authentication failed` / `Invalid API key`
-
-- Verify the key starts with `sk_strt_` and is not revoked at https://stratta.ch/api-keys.
-- Check the env var is reaching the process: `echo $STRATTA_API_KEY` (or `$env:STRATTA_API_KEY` on Windows PowerShell).
-- If you copied from the UI, make sure no leading/trailing whitespace was added.
-
-### `ECONNREFUSED` / network errors
-
-- Confirm outbound HTTPS to `*.convex.cloud` is allowed by your firewall/VPN.
-- Try `curl -I https://stratta.ch` to verify general internet reachability.
-
-### Tools don't appear in Claude
-
-- Restart your Claude client after editing the config.
-- Check the MCP server logs (Claude Code: `claude mcp logs stratta`; Claude Desktop: `~/Library/Logs/Claude/mcp-server-stratta.log` on macOS).
-- Make sure your Node.js version is `>=20` (`node --version`).
-
-### Rate-limited
-
-- Each user can create up to 50 active keys and 20 new keys per 24h. Revoke unused keys in the dashboard.
-
-### `QUOTA_EXCEEDED`
-
-Your organization reached one of its limits. The error names the dimension, your
-current count and the plan limit. Retrying will fail identically.
-
-| Limit           | Free | Pro    | Max     |
-| --------------- | ---- | ------ | ------- |
-| Norms           | 1    | 15     | 60      |
-| Sections        | 500  | 5,000  | 21,000  |
-| Figures         | 60   | 750    | 3,000   |
-| Queries / month | 500  | 15,000 | 100,000 |
-| Members         | 1    | 1      | 5       |
-
-Beyond Max, an Enterprise plan scales to 100 members, 300 norms and a million
-monthly queries; the calculator is at https://stratta.ch/tarifs
-
-Stock limits free up when you delete a norm (`ingest_delete`). The monthly query
-counter resets on its own. Gauges live on the Workspace page of your dashboard,
-and an org admin can also set caps below the plan. Full details:
-https://stratta.ch/docs/en/account/plans
-
-## License
-
-Proprietary — © Stratta, Lausanne. All rights reserved. This package is the
-official Stratta MCP client; redistribution, modification, or reuse of the source
-is not permitted without prior written consent.
+<!--
+Ownership marker for the official MCP registry. It must match `mcpName` in
+package.json exactly, and it must be present in the *published* tarball —
+the registry reads the README from npm, not from this repository. Without it
+`mcp-publisher publish` rejects the server as unverified.
+
+mcp-name: ch.stratta/mcp
+-->
+
+# @stratta/mcp
+
+MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients via Stratta TreeRAG.
+
+> Requires a free Stratta account. Sign up at https://stratta.ch and generate an API key at https://stratta.ch/api-keys.
+
+> [!IMPORTANT]
+> Your `STRATTA_API_KEY` is a **secret** — it grants read/write access to your
+> Stratta workspace. Never commit it to a repository, paste it into a shared/
+> project-scoped MCP config, or share it in logs. Prefer a user-scoped config or
+> a shell environment variable. If a key leaks, revoke it immediately at
+> https://stratta.ch/api-keys.
+
+## Install
+
+### Claude Code (recommended)
+
+Add the server — no key needed up front:
+
+```bash
+claude mcp add stratta --scope user -- npx -y @stratta/mcp
+```
+
+`--scope user` registers it for your user, so the tools are there in every
+project. Without it, `claude mcp add` writes to the current folder's config and
+the server exists nowhere else.
+
+Then sign in. This opens stratta.ch in your browser, where you confirm which
+machine and organisation to authorise; the key comes back to the terminal on
+its own and is saved to `~/.stratta/config.json` (owner-only, `0600`). You
+never see it, and you only do this once:
+
+```bash
+npx -y @stratta/mcp login
+```
+
+No browser on this machine — remote server, SSH, CI? `login --paste` asks for a
+key from https://stratta.ch/api-keys instead, without echoing it.
+
+If you skip the step entirely, Claude Code prompts you for a key on the first
+tool call.
+
+You can also pass the key explicitly as an environment variable (it then takes
+precedence over the saved key):
+
+```bash
+claude mcp add stratta --scope user --env STRATTA_API_KEY=sk_strt_xxx -- npx -y @stratta/mcp
+```
+
+## Staying up to date
+
+`npx -y @stratta/mcp` fetches the published package, but npx caches what it
+resolved, so a server can keep launching a version npm replaced weeks ago with
+nothing to tell you.
+
+```bash
+npx -y @stratta/mcp update
+```
+
+Prints the version you are running and the one npm serves, and fetches the new
+one if they differ. Restart your agent afterwards. The server also mentions it
+on stderr at startup when it notices it is behind.
+
+### Claude Desktop
+
+Sign in once from a terminal — the desktop app cannot prompt you interactively:
+
+```bash
+npx -y @stratta/mcp login
+```
+
+Then add the server to `claude_desktop_config.json` (Settings → Developer →
+Edit Config) — no key needed in the file:
+
+```json
+{
+  "mcpServers": {
+    "stratta": {
+      "command": "npx",
+      "args": ["-y", "@stratta/mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The Stratta tools should appear in the MCP indicator.
+
+> Prefer to keep the key in the config instead of `~/.stratta/config.json`? Add
+> an `"env": { "STRATTA_API_KEY": "sk_strt_xxx" }` block to the server entry —
+> but that file then stores the key in plaintext, so keep it private and unsynced.
+
+### Global install (optional)
+
+```bash
+npm install -g @stratta/mcp
+```
+
+Then use `"command": "stratta-mcp"` instead of `npx`.
+
+## Configuration
+
+The API key is resolved in this order: the `STRATTA_API_KEY` env var, then
+`~/.stratta/config.json` (written by `login` or the first-run prompt). Other
+settings come from environment variables — see [`.env.example`](./.env.example).
+
+| Variable             | Required | Default              | Purpose                                                                                                                                                        |
+| -------------------- | -------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STRATTA_API_KEY`    | no¹      | –                    | API key from https://stratta.ch. ¹If unset, the server falls back to `~/.stratta/config.json`, or prompts you on first use (clients that support elicitation). |
+| `STRATTA_CONVEX_URL` | no       | Stratta prod backend | Override only if you self-host.                                                                                                                                |
+
+## Tools exposed
+
+**Read** (8 tools — query norms in your workspace):
+
+| Tool              | Purpose                                                                                |
+| ----------------- | -------------------------------------------------------------------------------------- |
+| `get_methodology` | Behavioural contract: persona, workflow, meta-routing hints, answer rules. Call first. |
+| `list_norms`      | List all norms published in your workspace (code, year, title, language).              |
+| `get_toc`         | Hierarchical TOC for a norm (default `maxDepth=1` = chapters).                         |
+| `get_subtree`     | Drill into a chapter/section subtree (`path` + `maxDepth`).                            |
+| `get_section`     | Full enriched content of a section (formulas, tables, figures, cross-refs).            |
+| `search_in_norm`  | Keyword search inside a norm.                                                          |
+| `get_figure`      | Retrieve a figure inline (base64 ImageContent) + public URL.                           |
+| `get_cross_refs`  | Outgoing cross-refs from a section to other norms.                                     |
+
+**Dossier** (5 tools — keep what was decided on a project):
+
+| Tool               | Purpose                                                                                           |
+| ------------------ | ------------------------------------------------------------------------------------------------- |
+| `list_dossiers`    | Your organisation's dossiers, most recently touched first, with open counts.                      |
+| `open_dossier`     | Open a project's dossier, creating it if needed. Idempotent on the name.                          |
+| `save_finding`     | Record one decision: a cited article, a retained value and why, an observation, an open question. |
+| `load_dossier`     | Reload everything, unresolved questions first. Accepts the id or the name.                        |
+| `resolve_question` | Mark a question settled. The entry stays; it stops surfacing at the top.                          |
+
+A dossier is read, annotated, reviewed and exported from
+[stratta.ch/dossiers](https://stratta.ch/dossiers).
+
+**Ingest** (10 tools — add YOUR licensed norms; driven by the bundled `ingest-norm` skill):
+
+| Tool                          | Purpose                                                      |
+| ----------------------------- | ------------------------------------------------------------ |
+| `ingest_status`               | Check if a norm already exists in your workspace.            |
+| `ingest_create_document`      | Create a draft norm document.                                |
+| `ingest_create_sections`      | Bulk-insert sections (returns `nodeId → sectionId` map).     |
+| `ingest_attach_formula`       | Attach a LaTeX formula to a section.                         |
+| `ingest_attach_table`         | Attach a structured table `{headers, rows}` to a section.    |
+| `ingest_attach_cross_ref`     | Attach an explicit cross-ref to another norm.                |
+| `ingest_upload_figure`        | Upload a figure (base64 PNG/JPEG/WebP, ≤ 8 MB) to a section. |
+| `ingest_normalize_cross_refs` | Auto-detect and rebuild cross-refs from section content.     |
+| `ingest_publish`              | Flip a draft to published — visible via the read tools.      |
+| `ingest_delete`               | Delete a document and all its children.                      |
+
+## How agents should use it
+
+For querying:
+
+1. Call `get_methodology` first — load the behavioural contract.
+2. Call `list_norms` to see what's available in your workspace.
+3. Call `get_toc(norm)` to navigate the structure; `get_subtree` to drill in.
+4. Call `get_section(norm, path)` to read specific content.
+5. Use `search_in_norm` when the section path is unknown.
+6. Follow `crossRefs` for compound questions (e.g. SIA 261 → SIA 263 → EC).
+7. Call `get_figure` when the section references a figure relevant to the answer.
+
+For ingesting your own licensed norms, see the bundled **`ingest-norm` skill** —
+a 2-phase hybrid pipeline (since 0.4.0): a Python pre-pass
+(`scripts/ingest-prepass.py`, PyMuPDF) extracts the hierarchical tree and
+rasterizes figures deterministically, then the agent enriches sections with
+summaries, LaTeX formulas, tables and cross-refs via targeted visual reading.
+Requires Python ≥ 3.10 with PyMuPDF (`python -m pip install --user pymupdf`).
+
+## Troubleshooting
+
+### `Authentication failed` / `Invalid API key`
+
+- Verify the key starts with `sk_strt_` and is not revoked at https://stratta.ch/api-keys.
+- Check the env var is reaching the process: `echo $STRATTA_API_KEY` (or `$env:STRATTA_API_KEY` on Windows PowerShell).
+- If you copied from the UI, make sure no leading/trailing whitespace was added.
+
+### `ECONNREFUSED` / network errors
+
+- Confirm outbound HTTPS to `*.convex.cloud` is allowed by your firewall/VPN.
+- Try `curl -I https://stratta.ch` to verify general internet reachability.
+
+### Tools don't appear in Claude
+
+- Restart your Claude client after editing the config.
+- Check the MCP server logs (Claude Code: `claude mcp logs stratta`; Claude Desktop: `~/Library/Logs/Claude/mcp-server-stratta.log` on macOS).
+- Make sure your Node.js version is `>=20` (`node --version`).
+
+### Rate-limited
+
+- Each user can create up to 50 active keys and 20 new keys per 24h. Revoke unused keys in the dashboard.
+
+### `QUOTA_EXCEEDED`
+
+Your organization reached one of its limits. The error names the dimension, your
+current count and the plan limit. Retrying will fail identically.
+
+| Limit           | Free | Pro    | Max     |
+| --------------- | ---- | ------ | ------- |
+| Norms           | 1    | 15     | 60      |
+| Sections        | 500  | 5,000  | 21,000  |
+| Figures         | 60   | 750    | 3,000   |
+| Queries / month | 500  | 15,000 | 100,000 |
+| Members         | 1    | 1      | 5       |
+
+Beyond Max, an Enterprise plan scales to 100 members, 300 norms and a million
+monthly queries; the calculator is at https://stratta.ch/tarifs
+
+Stock limits free up when you delete a norm (`ingest_delete`). The monthly query
+counter resets on its own. Gauges live on the Workspace page of your dashboard,
+and an org admin can also set caps below the plan. Full details:
+https://stratta.ch/docs/en/account/plans
+
+## License
+
+Proprietary — © Stratta, Lausanne. All rights reserved. This package is the
+official Stratta MCP client; redistribution, modification, or reuse of the source
+is not permitted without prior written consent.

package/dist/index.js

@@ -93,14 +93,31 @@ for (const def of [...readTools, ...dossierTools, ...ingestTools]) {
     (args) => call(def, args));
 }
 async function main() {
-    if (process.argv[2] === 'login') {
+    const command = process.argv[2];
+    if (command === 'login') {
         const { runLogin } = await import('./login.js');
         await runLogin(process.argv.slice(3));
         return;
     }
+    if (command === 'update') {
+        const { runUpdate } = await import('./update.js');
+        await runUpdate(packageVersion());
+        return;
+    }
+    // `--version` because that is what everyone types first, and because
+    // `update` needs a cheap way to make npx materialise a given version.
+    if (command === '--version' || command === '-v' || command === 'version') {
+        console.log(packageVersion());
+        return;
+    }
     await server.connect(new StdioServerTransport());
     // Stderr only; stdout carries the MCP protocol.
     console.error(`[stratta-mcp] v${packageVersion()} listening on stdio`);
+    // After connect, never before: the check reaches the network, and a server
+    // that starts slowly because of a version lookup is a worse problem than an
+    // out-of-date one.
+    const { noticeIfOutdated } = await import('./update.js');
+    noticeIfOutdated(packageVersion());
 }
 main().catch((err) => {
     console.error('[stratta-mcp] fatal:', err);

package/dist/login.js

@@ -68,15 +68,15 @@ function openBrowser(url) {
     }
 }
 function page(title, body) {
-    return `<!doctype html><html lang="fr"><meta charset="utf-8">
-<title>${title}</title>
-<style>
-  body{font:16px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;
-       background:#12110f;color:#f5f1e8;display:grid;place-items:center;
-       min-height:100vh;margin:0;padding:2rem;text-align:center}
-  .c{max-width:26rem} h1{font-size:1.25rem;margin:0 0 .5rem}
-  p{margin:0;color:#a8a196}
-</style>
+    return `<!doctype html><html lang="fr"><meta charset="utf-8">
+<title>${title}</title>
+<style>
+  body{font:16px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif;
+       background:#12110f;color:#f5f1e8;display:grid;place-items:center;
+       min-height:100vh;margin:0;padding:2rem;text-align:center}
+  .c{max-width:26rem} h1{font-size:1.25rem;margin:0 0 .5rem}
+  p{margin:0;color:#a8a196}
+</style>
 <div class="c"><h1>${title}</h1><p>${body}</p></div>`;
 }
 /**

package/dist/update.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What version npm would serve right now, or null if we could not ask.
+ *
+ * Deliberately quiet about failures: this runs on a path where being offline,
+ * behind a proxy, or on a flaky connection is ordinary, and none of that is
+ * worth an error. A missed check is not a problem; a server that refuses to
+ * start because a version check failed would be.
+ */
+export declare function latestPublished(timeoutMs?: number): Promise<string | null>;
+/** Numeric compare, so 0.9.10 sorts above 0.9.9. */
+export declare function isNewer(candidate: string, current: string): boolean;
+/**
+ * Tell the user, on stderr, when they are running something old.
+ *
+ * Fire-and-forget from `main`: the server is already listening by the time
+ * this resolves, so a slow registry delays nothing. stdout carries the MCP
+ * protocol and must stay clean.
+ */
+export declare function noticeIfOutdated(current: string): void;
+/**
+ * `npx @stratta/mcp update`.
+ *
+ * npx caches a resolved package and reuses it, so `npx -y @stratta/mcp` can
+ * keep launching a version that npm replaced weeks ago — the user has no way
+ * to tell, and nothing tells them. This says which version is running, which
+ * one is published, and clears the cache entry so the next launch fetches the
+ * new one.
+ */
+export declare function runUpdate(current: string): Promise<void>;

package/dist/update.js

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process';
+const REGISTRY = 'https://registry.npmjs.org/@stratta/mcp/latest';
+/**
+ * What version npm would serve right now, or null if we could not ask.
+ *
+ * Deliberately quiet about failures: this runs on a path where being offline,
+ * behind a proxy, or on a flaky connection is ordinary, and none of that is
+ * worth an error. A missed check is not a problem; a server that refuses to
+ * start because a version check failed would be.
+ */
+export async function latestPublished(timeoutMs = 3000) {
+    try {
+        const res = await fetch(REGISTRY, {
+            signal: AbortSignal.timeout(timeoutMs),
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return body.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Numeric compare, so 0.9.10 sorts above 0.9.9. */
+export function isNewer(candidate, current) {
+    const a = candidate.split('.').map(Number);
+    const b = current.split('.').map(Number);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}
+/**
+ * Tell the user, on stderr, when they are running something old.
+ *
+ * Fire-and-forget from `main`: the server is already listening by the time
+ * this resolves, so a slow registry delays nothing. stdout carries the MCP
+ * protocol and must stay clean.
+ */
+export function noticeIfOutdated(current) {
+    void latestPublished().then((latest) => {
+        if (!latest || !isNewer(latest, current))
+            return;
+        console.error(`[stratta-mcp] version ${latest} disponible (vous avez ${current}) — ` +
+            `lancez : npx -y @stratta/mcp update`);
+    });
+}
+/**
+ * `npx @stratta/mcp update`.
+ *
+ * npx caches a resolved package and reuses it, so `npx -y @stratta/mcp` can
+ * keep launching a version that npm replaced weeks ago — the user has no way
+ * to tell, and nothing tells them. This says which version is running, which
+ * one is published, and clears the cache entry so the next launch fetches the
+ * new one.
+ */
+export async function runUpdate(current) {
+    console.log(`Version installée : ${current}`);
+    const latest = await latestPublished(8000);
+    if (!latest) {
+        console.log('Impossible de joindre npm. Vérifiez votre connexion et réessayez.');
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Dernière publiée  : ${latest}`);
+    if (!isNewer(latest, current)) {
+        console.log('\nVous êtes à jour.');
+        return;
+    }
+    console.log('\nRécupération de la nouvelle version…');
+    // `npx -y pkg@version` bypasses whatever npx had cached for the bare name,
+    // and populates the cache with the new one in the same step.
+    const r = spawnSync(process.platform === 'win32' ? 'npx.cmd' : 'npx', ['-y', `@stratta/mcp@${latest}`, '--version'], { stdio: 'inherit' });
+    if (r.status === 0) {
+        console.log(`\n@stratta/mcp ${latest} est prêt.\n` +
+            'Redémarrez votre agent pour que le serveur reparte sur cette version.');
+    }
+    else {
+        console.log(`\nLa récupération a échoué. À lancer à la main :\n` +
+            `  npx -y @stratta/mcp@${latest}`);
+        process.exitCode = 1;
+    }
+}

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "@stratta/mcp",
-  "mcpName": "ch.stratta/mcp",
-  "version": "0.9.3",
-  "description": "MCP server exposing the engineering norms your firm is licensed for (SIA / Eurocodes) to any MCP client, via Stratta TreeRAG.",
-  "license": "UNLICENSED",
-  "author": "SmartFlow <hello@stratta.ch>",
-  "homepage": "https://stratta.ch",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/hugogebel-boop/stratta-v2.git",
-    "directory": "packages/mcp"
-  },
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "claude",
-    "rag",
-    "sia",
-    "eurocodes",
-    "civil-engineering",
-    "stratta"
-  ],
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "stratta-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "skills",
-    "scripts",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
-    "dev": "tsc --watch",
-    "start": "node dist/index.js",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "convex": "^1.42.3",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^26.1.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@stratta/mcp",
+  "mcpName": "ch.stratta/mcp",
+  "version": "0.9.5",
+  "description": "MCP server exposing the engineering norms your firm is licensed for (SIA / Eurocodes) to any MCP client, via Stratta TreeRAG.",
+  "license": "UNLICENSED",
+  "author": "SmartFlow <hello@stratta.ch>",
+  "homepage": "https://stratta.ch",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hugogebel-boop/stratta-v2.git",
+    "directory": "packages/mcp"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "rag",
+    "sia",
+    "eurocodes",
+    "civil-engineering",
+    "stratta"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "stratta-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "convex": "^1.42.3",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/publish-release.ps1

@@ -1,99 +1,99 @@
-<#
-.SYNOPSIS
-  Publish @stratta/mcp to npm, then register it with the official MCP registry.
-
-.DESCRIPTION
-  The two publications are ordered, not independent: the registry reads
-  `mcpName` from the tarball npm serves, so a version that is not on npm yet
-  cannot be registered. Doing it by hand in the wrong order fails with
-
-      NPM package '@stratta/mcp' exists, but version 'x.y.z' was not found
-
-  which reads like a transient error and is not one.
-
-  Run this from an interactive terminal. `npm publish` triggers a 2FA prompt
-  that opens a browser, and `npm login` needs one too if the session has
-  lapsed. Neither works from a non-interactive shell -- by design, so that
-  access to a machine is not access to the package.
-
-  ASCII only, on purpose: Windows PowerShell 5.1 reads a UTF-8 file without a
-  BOM as ANSI, and a single arrow or em dash in a comment breaks the parser
-  with an error that points at the wrong line.
-
-.PARAMETER PrivateKey
-  The Ed25519 key proving control of stratta.ch, 64 hex characters. Lives in
-  Doppler under MCP_REGISTRY_PRIVATE_KEY. Its public half is served from
-  /.well-known/mcp-registry-auth -- deleting that file breaks publishing.
-
-.PARAMETER PublisherPath
-  Path to mcp-publisher. Download it from the registry releases if absent:
-  https://github.com/modelcontextprotocol/registry/releases
-
-.EXAMPLE
-  .\publish-release.ps1 -PrivateKey (doppler secrets get MCP_REGISTRY_PRIVATE_KEY --plain)
-#>
-param(
-  [Parameter(Mandatory = $true)][string]$PrivateKey,
-  [string]$PublisherPath = "mcp-publisher"
-)
-
-$ErrorActionPreference = "Stop"
-Push-Location (Join-Path $PSScriptRoot "..")
-
-try {
-  $pkg = Get-Content package.json -Raw | ConvertFrom-Json
-  $srv = Get-Content server.json -Raw | ConvertFrom-Json
-
-  Write-Host "-> @stratta/mcp $($pkg.version) as $($pkg.mcpName)" -ForegroundColor Cyan
-
-  # Fail before publishing, not after. The three names and the three versions
-  # have to agree, or the registry rejects the server as unverified once npm
-  # has already gone out, and a version number is burnt.
-  if ($pkg.mcpName -ne $srv.name) {
-    throw "package.json mcpName ($($pkg.mcpName)) does not match server.json name ($($srv.name))"
-  }
-  if ($pkg.version -ne $srv.version -or $pkg.version -ne $srv.packages[0].version) {
-    throw "version mismatch: package.json $($pkg.version), server.json $($srv.version), packages[0] $($srv.packages[0].version)"
-  }
-  if (-not (Select-String -Path README.md -Pattern ("mcp-name: " + [regex]::Escape($pkg.mcpName)) -Quiet)) {
-    throw "README.md is missing the marker 'mcp-name: $($pkg.mcpName)'"
-  }
-  Write-Host "   manifest is coherent" -ForegroundColor DarkGray
-
-  Write-Host "-> npm whoami" -ForegroundColor Cyan
-  npm whoami
-  if ($LASTEXITCODE -ne 0) { throw "Not logged in to npm. Run 'npm login' and retry." }
-
-  Write-Host "-> npm publish (a 2FA prompt may open a browser)" -ForegroundColor Cyan
-  npm publish
-  if ($LASTEXITCODE -ne 0) { throw "npm publish failed" }
-
-  # npm's CDN needs a moment before the registry can see the new version.
-  Write-Host "-> waiting for npm to serve $($pkg.version)" -ForegroundColor Cyan
-  $seen = $false
-  foreach ($i in 1..20) {
-    Start-Sleep -Seconds 3
-    try {
-      $served = Invoke-RestMethod "https://registry.npmjs.org/@stratta/mcp/$($pkg.version)"
-      if ($served.version -eq $pkg.version) { $seen = $true; break }
-    } catch { }
-  }
-  if (-not $seen) { throw "npm has not served $($pkg.version) after 60s; rerun the registry steps by hand" }
-  Write-Host "   npm serves $($pkg.version)" -ForegroundColor DarkGray
-
-  # Domain proof rather than the GitHub device flow: nothing waits on a human
-  # typing a code. The JWT it returns expires in under an hour, which is why
-  # login and publish run back to back with nothing in between.
-  Write-Host "-> mcp-publisher login (domain proof)" -ForegroundColor Cyan
-  & $PublisherPath login http --domain stratta.ch --private-key $PrivateKey
-  if ($LASTEXITCODE -ne 0) { throw "registry login failed. Check that https://stratta.ch/.well-known/mcp-registry-auth is still served." }
-
-  Write-Host "-> mcp-publisher publish" -ForegroundColor Cyan
-  & $PublisherPath publish
-  if ($LASTEXITCODE -ne 0) { throw "registry publish failed" }
-
-  Write-Host "OK  $($pkg.version) published to npm and to registry.modelcontextprotocol.io" -ForegroundColor Green
-}
-finally {
-  Pop-Location
-}
+<#
+.SYNOPSIS
+  Publish @stratta/mcp to npm, then register it with the official MCP registry.
+
+.DESCRIPTION
+  The two publications are ordered, not independent: the registry reads
+  `mcpName` from the tarball npm serves, so a version that is not on npm yet
+  cannot be registered. Doing it by hand in the wrong order fails with
+
+      NPM package '@stratta/mcp' exists, but version 'x.y.z' was not found
+
+  which reads like a transient error and is not one.
+
+  Run this from an interactive terminal. `npm publish` triggers a 2FA prompt
+  that opens a browser, and `npm login` needs one too if the session has
+  lapsed. Neither works from a non-interactive shell -- by design, so that
+  access to a machine is not access to the package.
+
+  ASCII only, on purpose: Windows PowerShell 5.1 reads a UTF-8 file without a
+  BOM as ANSI, and a single arrow or em dash in a comment breaks the parser
+  with an error that points at the wrong line.
+
+.PARAMETER PrivateKey
+  The Ed25519 key proving control of stratta.ch, 64 hex characters. Lives in
+  Doppler under MCP_REGISTRY_PRIVATE_KEY. Its public half is served from
+  /.well-known/mcp-registry-auth -- deleting that file breaks publishing.
+
+.PARAMETER PublisherPath
+  Path to mcp-publisher. Download it from the registry releases if absent:
+  https://github.com/modelcontextprotocol/registry/releases
+
+.EXAMPLE
+  .\publish-release.ps1 -PrivateKey (doppler secrets get MCP_REGISTRY_PRIVATE_KEY --plain)
+#>
+param(
+  [Parameter(Mandatory = $true)][string]$PrivateKey,
+  [string]$PublisherPath = "mcp-publisher"
+)
+
+$ErrorActionPreference = "Stop"
+Push-Location (Join-Path $PSScriptRoot "..")
+
+try {
+  $pkg = Get-Content package.json -Raw | ConvertFrom-Json
+  $srv = Get-Content server.json -Raw | ConvertFrom-Json
+
+  Write-Host "-> @stratta/mcp $($pkg.version) as $($pkg.mcpName)" -ForegroundColor Cyan
+
+  # Fail before publishing, not after. The three names and the three versions
+  # have to agree, or the registry rejects the server as unverified once npm
+  # has already gone out, and a version number is burnt.
+  if ($pkg.mcpName -ne $srv.name) {
+    throw "package.json mcpName ($($pkg.mcpName)) does not match server.json name ($($srv.name))"
+  }
+  if ($pkg.version -ne $srv.version -or $pkg.version -ne $srv.packages[0].version) {
+    throw "version mismatch: package.json $($pkg.version), server.json $($srv.version), packages[0] $($srv.packages[0].version)"
+  }
+  if (-not (Select-String -Path README.md -Pattern ("mcp-name: " + [regex]::Escape($pkg.mcpName)) -Quiet)) {
+    throw "README.md is missing the marker 'mcp-name: $($pkg.mcpName)'"
+  }
+  Write-Host "   manifest is coherent" -ForegroundColor DarkGray
+
+  Write-Host "-> npm whoami" -ForegroundColor Cyan
+  npm whoami
+  if ($LASTEXITCODE -ne 0) { throw "Not logged in to npm. Run 'npm login' and retry." }
+
+  Write-Host "-> npm publish (a 2FA prompt may open a browser)" -ForegroundColor Cyan
+  npm publish
+  if ($LASTEXITCODE -ne 0) { throw "npm publish failed" }
+
+  # npm's CDN needs a moment before the registry can see the new version.
+  Write-Host "-> waiting for npm to serve $($pkg.version)" -ForegroundColor Cyan
+  $seen = $false
+  foreach ($i in 1..20) {
+    Start-Sleep -Seconds 3
+    try {
+      $served = Invoke-RestMethod "https://registry.npmjs.org/@stratta/mcp/$($pkg.version)"
+      if ($served.version -eq $pkg.version) { $seen = $true; break }
+    } catch { }
+  }
+  if (-not $seen) { throw "npm has not served $($pkg.version) after 60s; rerun the registry steps by hand" }
+  Write-Host "   npm serves $($pkg.version)" -ForegroundColor DarkGray
+
+  # Domain proof rather than the GitHub device flow: nothing waits on a human
+  # typing a code. The JWT it returns expires in under an hour, which is why
+  # login and publish run back to back with nothing in between.
+  Write-Host "-> mcp-publisher login (domain proof)" -ForegroundColor Cyan
+  & $PublisherPath login http --domain stratta.ch --private-key $PrivateKey
+  if ($LASTEXITCODE -ne 0) { throw "registry login failed. Check that https://stratta.ch/.well-known/mcp-registry-auth is still served." }
+
+  Write-Host "-> mcp-publisher publish" -ForegroundColor Cyan
+  & $PublisherPath publish
+  if ($LASTEXITCODE -ne 0) { throw "registry publish failed" }
+
+  Write-Host "OK  $($pkg.version) published to npm and to registry.modelcontextprotocol.io" -ForegroundColor Green
+}
+finally {
+  Pop-Location
+}

package/skills/ingest-norm/SKILL.md

@@ -1,162 +1,162 @@
----
-name: ingest-norm
-description: Use when the user wants to add an engineering norm (SIA, Eurocode, etc.) they are licensed for into THEIR Stratta workspace. A Python pre-pass (PyMuPDF) extracts the hierarchical tree and rasterizes figures; an agentic pass enriches sections (LaTeX formulas, tables, cross-references, summaries) and writes everything via the MCP `ingest_*` tools — scoped to the user's own organization. Trigger phrases: "ingère cette norme", "/ingest-norm", "ingest SIA", "ajoute la norme X à Stratta".
----
-
-# Ingest a norm into your Stratta workspace
-
-This skill turns a norm PDF **you are licensed to use** into a queryable
-TreeRAG inside **your own** Stratta workspace. A Python pre-pass (PyMuPDF)
-does the deterministic heavy lifting — TOC tree, per-section raw text, figure
-captions and full-page renders. Then an agentic pass enriches sections with
-summaries, LaTeX formulas, structured tables, and cross-references. Final
-writes go through the Stratta MCP `ingest_*` tools, scoped to your org.
-
-> ⚠️ **Licence**: only ingest norms your organization holds a valid licence
-> for. You are responsible for your usage rights (see Stratta's Terms).
-
-## Prerequisites
-
-- The Stratta MCP server is installed and your `STRATTA_API_KEY` resolves
-  (via env, `~/.stratta/config.json`, or first-call elicitation).
-- **Python ≥ 3.10 with PyMuPDF**. Install once:
-  `python -m pip install --user pymupdf` (or `uv pip install pymupdf`).
-- The norm PDF is available locally.
-
-## Tools used (all scoped to your workspace)
-
-`ingest_status` · `ingest_create_document` · `ingest_create_sections` ·
-`ingest_attach_formula` · `ingest_attach_table` · `ingest_attach_cross_ref` ·
-`ingest_upload_figure` · `ingest_normalize_cross_refs` · `ingest_publish` ·
-`ingest_delete`.
-
-## Quotas — read before you start
-
-The workspace has server-enforced limits on norms, sections and figures. A
-`QUOTA_EXCEEDED` error names the dimension, the current count and the limit.
-
-**Do not retry it.** The limit will not move on its own. Stop the ingestion,
-report the numbers to the user, and offer the two ways out: delete a norm that is
-no longer needed (`ingest_delete`), or raise the plan.
-
-Check the budget up front on a large norm: the pre-pass output tells you how many
-sections and figures you are about to write. Failing at step 8 of 10 leaves a
-half-ingested document behind, which the user then has to delete by hand.
-
-## Workflow
-
-### 1. Locate the pre-pass script
-
-It ships inside this package at `scripts/ingest-prepass.py`. Resolve its path:
-
-```bash
-node -e "console.log(require.resolve('@stratta/mcp/package.json'))"
-# → <root>/package.json  →  <root>/scripts/ingest-prepass.py
-```
-
-If the user is working in the Stratta monorepo, the script also lives at
-`packages/mcp/scripts/ingest-prepass.py`.
-
-### 2. Check for an existing copy
-
-`ingest_status { code }` (e.g. `"SIA 261"`). To re-ingest, call
-`ingest_delete { documentId }` first.
-
-### 3. Run the pre-pass
-
-```bash
-python <pkg-root>/scripts/ingest-prepass.py \
-  --pdf <path-to-pdf> \
-  --output .stratta-ingest/<code-slug>
-```
-
-Output under `.stratta-ingest/<code-slug>/`:
-
-- `prepass.json` — full manifest (see below).
-- `figures/page-NNN.png` — one PNG per page that contains a `Figure N` caption.
-
-`prepass.json` structure:
-
-- `doc` — `pageCount`, detected `language`, `tocSource`, raw `metadata`.
-- `stats` — `sectionCount`, `byDepth`, `figureCount`.
-- `sections[]` — full hierarchical tree (depth **0 = chapter**, 1+ = sub-sections),
-  each with `nodeId`, `parentNodeId`, `path` (`"4.2.1"` or `"Annexe B"`),
-  `title`, `depth`, `pageStart`, `pageEnd`, `orderIndex`, `rawText` (concat
-  of the pages the node spans).
-- `figures[]` — one entry per `Figure N` caption: `figureNumber`, `caption`,
-  `page`, `fileName`, `mimeType`.
-
-The pre-pass is **exhaustive** (e.g. ~550 nodes on SIA 261). You decide what
-to keep in the next step.
-
-### 4. Create the document
-
-Read `prepass.json`, then:
-`ingest_create_document { code, year, title, language: <doc.language>, totalPages: <doc.pageCount> }`
-→ returns `documentId`. Keep it for every subsequent call.
-
-### 5. Decide section granularity + generate summaries
-
-Iterate `sections[]` and decide what to keep. Two viable strategies:
-
-- **Keep all** — most faithful, ~500 sections on a typical SIA norm. Great
-  for fine-grained navigation but verbose.
-- **Aggregate trivial leaves** — fold paragraph-level nodes (`6.1.1`...`6.1.11`)
-  into their parent (`6.1`), concatenating their `rawText`. Typical result:
-  100-150 sections. Recommended unless the user asks for max granularity.
-
-For each kept section, prepare:
-
-- `summary` — 1-3 sentences derived from `rawText` (mention formulas/values).
-- `content` — enriched text with LaTeX inline where the source has math
-  (e.g. `$\sigma_d = f_{yd} \cdot \gamma$`). Open the PDF visually for pages
-  that contain formulas or multi-column tables — PyMuPDF mangles those.
-- `rawContent` — use the pre-pass `rawText` as-is.
-
-Keep the `nodeId` / `parentNodeId` / `path` / `pageStart` / `pageEnd` /
-`orderIndex` / `depth` from the pre-pass — those are deterministic.
-
-### 6. Insert sections (batched)
-
-`ingest_create_sections { documentId, sections: [...] }` in batches of 30-50.
-Parent links resolve via `parentNodeId` within the batch and across prior
-batches. The call returns a `nodeId → sectionId` map — **use those `sectionId`s**
-for every enrichment call below.
-
-### 7. Enrich
-
-- `ingest_attach_formula { sectionId, latex, description, formulaNumber }`
-- `ingest_attach_table { sectionId, data: { headers, rows }, caption, tableNumber }`
-- `ingest_attach_cross_ref { sourceSectionId, targetDocumentCode, targetSectionPath?, refText, refType }`
-
-### 8. Upload figures
-
-For each figure in `prepass.json#figures`:
-
-- Read `.stratta-ingest/<code>/<fileName>` and base64-encode the bytes.
-- Find the owning section: the kept section whose `pageStart..pageEnd`
-  range includes the figure's `page`.
-- `ingest_upload_figure { sectionId, base64, mimeType: "image/png", caption, figureNumber }`
-  (≤ 8 MB per image).
-
-### 9. Auto cross-references (optional but recommended)
-
-`ingest_normalize_cross_refs { documentId }` scans every section's text for
-references to other norms (SIA / SN EN / EN / ISO / DIN …) and rebuilds the
-cross-ref index. Idempotent.
-
-### 10. Publish
-
-`ingest_publish { documentId }`. The norm is now queryable in your workspace
-via `list_norms`, `get_toc`, `get_section`, `search_in_norm`, `get_figure`, etc.
-
-## Quality bar
-
-- Trust the pre-pass for `path` + `pageStart`/`pageEnd` — it's deterministic
-  and verified against the PDF bookmarks.
-- Summaries drive navigation — be specific (mention key formulas/values).
-- Keep `content` faithful to the source; don't invent values.
-- If PyMuPDF mangled a formula (Greek letters, fractions, exponents broken),
-  re-read the relevant PDF page visually and write proper LaTeX.
-- Never skip annexes — they hold key numeric values (zones, coefficients,
-  characteristic loads).
+---
+name: ingest-norm
+description: Use when the user wants to add an engineering norm (SIA, Eurocode, etc.) they are licensed for into THEIR Stratta workspace. A Python pre-pass (PyMuPDF) extracts the hierarchical tree and rasterizes figures; an agentic pass enriches sections (LaTeX formulas, tables, cross-references, summaries) and writes everything via the MCP `ingest_*` tools — scoped to the user's own organization. Trigger phrases: "ingère cette norme", "/ingest-norm", "ingest SIA", "ajoute la norme X à Stratta".
+---
+
+# Ingest a norm into your Stratta workspace
+
+This skill turns a norm PDF **you are licensed to use** into a queryable
+TreeRAG inside **your own** Stratta workspace. A Python pre-pass (PyMuPDF)
+does the deterministic heavy lifting — TOC tree, per-section raw text, figure
+captions and full-page renders. Then an agentic pass enriches sections with
+summaries, LaTeX formulas, structured tables, and cross-references. Final
+writes go through the Stratta MCP `ingest_*` tools, scoped to your org.
+
+> ⚠️ **Licence**: only ingest norms your organization holds a valid licence
+> for. You are responsible for your usage rights (see Stratta's Terms).
+
+## Prerequisites
+
+- The Stratta MCP server is installed and your `STRATTA_API_KEY` resolves
+  (via env, `~/.stratta/config.json`, or first-call elicitation).
+- **Python ≥ 3.10 with PyMuPDF**. Install once:
+  `python -m pip install --user pymupdf` (or `uv pip install pymupdf`).
+- The norm PDF is available locally.
+
+## Tools used (all scoped to your workspace)
+
+`ingest_status` · `ingest_create_document` · `ingest_create_sections` ·
+`ingest_attach_formula` · `ingest_attach_table` · `ingest_attach_cross_ref` ·
+`ingest_upload_figure` · `ingest_normalize_cross_refs` · `ingest_publish` ·
+`ingest_delete`.
+
+## Quotas — read before you start
+
+The workspace has server-enforced limits on norms, sections and figures. A
+`QUOTA_EXCEEDED` error names the dimension, the current count and the limit.
+
+**Do not retry it.** The limit will not move on its own. Stop the ingestion,
+report the numbers to the user, and offer the two ways out: delete a norm that is
+no longer needed (`ingest_delete`), or raise the plan.
+
+Check the budget up front on a large norm: the pre-pass output tells you how many
+sections and figures you are about to write. Failing at step 8 of 10 leaves a
+half-ingested document behind, which the user then has to delete by hand.
+
+## Workflow
+
+### 1. Locate the pre-pass script
+
+It ships inside this package at `scripts/ingest-prepass.py`. Resolve its path:
+
+```bash
+node -e "console.log(require.resolve('@stratta/mcp/package.json'))"
+# → <root>/package.json  →  <root>/scripts/ingest-prepass.py
+```
+
+If the user is working in the Stratta monorepo, the script also lives at
+`packages/mcp/scripts/ingest-prepass.py`.
+
+### 2. Check for an existing copy
+
+`ingest_status { code }` (e.g. `"SIA 261"`). To re-ingest, call
+`ingest_delete { documentId }` first.
+
+### 3. Run the pre-pass
+
+```bash
+python <pkg-root>/scripts/ingest-prepass.py \
+  --pdf <path-to-pdf> \
+  --output .stratta-ingest/<code-slug>
+```
+
+Output under `.stratta-ingest/<code-slug>/`:
+
+- `prepass.json` — full manifest (see below).
+- `figures/page-NNN.png` — one PNG per page that contains a `Figure N` caption.
+
+`prepass.json` structure:
+
+- `doc` — `pageCount`, detected `language`, `tocSource`, raw `metadata`.
+- `stats` — `sectionCount`, `byDepth`, `figureCount`.
+- `sections[]` — full hierarchical tree (depth **0 = chapter**, 1+ = sub-sections),
+  each with `nodeId`, `parentNodeId`, `path` (`"4.2.1"` or `"Annexe B"`),
+  `title`, `depth`, `pageStart`, `pageEnd`, `orderIndex`, `rawText` (concat
+  of the pages the node spans).
+- `figures[]` — one entry per `Figure N` caption: `figureNumber`, `caption`,
+  `page`, `fileName`, `mimeType`.
+
+The pre-pass is **exhaustive** (e.g. ~550 nodes on SIA 261). You decide what
+to keep in the next step.
+
+### 4. Create the document
+
+Read `prepass.json`, then:
+`ingest_create_document { code, year, title, language: <doc.language>, totalPages: <doc.pageCount> }`
+→ returns `documentId`. Keep it for every subsequent call.
+
+### 5. Decide section granularity + generate summaries
+
+Iterate `sections[]` and decide what to keep. Two viable strategies:
+
+- **Keep all** — most faithful, ~500 sections on a typical SIA norm. Great
+  for fine-grained navigation but verbose.
+- **Aggregate trivial leaves** — fold paragraph-level nodes (`6.1.1`...`6.1.11`)
+  into their parent (`6.1`), concatenating their `rawText`. Typical result:
+  100-150 sections. Recommended unless the user asks for max granularity.
+
+For each kept section, prepare:
+
+- `summary` — 1-3 sentences derived from `rawText` (mention formulas/values).
+- `content` — enriched text with LaTeX inline where the source has math
+  (e.g. `$\sigma_d = f_{yd} \cdot \gamma$`). Open the PDF visually for pages
+  that contain formulas or multi-column tables — PyMuPDF mangles those.
+- `rawContent` — use the pre-pass `rawText` as-is.
+
+Keep the `nodeId` / `parentNodeId` / `path` / `pageStart` / `pageEnd` /
+`orderIndex` / `depth` from the pre-pass — those are deterministic.
+
+### 6. Insert sections (batched)
+
+`ingest_create_sections { documentId, sections: [...] }` in batches of 30-50.
+Parent links resolve via `parentNodeId` within the batch and across prior
+batches. The call returns a `nodeId → sectionId` map — **use those `sectionId`s**
+for every enrichment call below.
+
+### 7. Enrich
+
+- `ingest_attach_formula { sectionId, latex, description, formulaNumber }`
+- `ingest_attach_table { sectionId, data: { headers, rows }, caption, tableNumber }`
+- `ingest_attach_cross_ref { sourceSectionId, targetDocumentCode, targetSectionPath?, refText, refType }`
+
+### 8. Upload figures
+
+For each figure in `prepass.json#figures`:
+
+- Read `.stratta-ingest/<code>/<fileName>` and base64-encode the bytes.
+- Find the owning section: the kept section whose `pageStart..pageEnd`
+  range includes the figure's `page`.
+- `ingest_upload_figure { sectionId, base64, mimeType: "image/png", caption, figureNumber }`
+  (≤ 8 MB per image).
+
+### 9. Auto cross-references (optional but recommended)
+
+`ingest_normalize_cross_refs { documentId }` scans every section's text for
+references to other norms (SIA / SN EN / EN / ISO / DIN …) and rebuilds the
+cross-ref index. Idempotent.
+
+### 10. Publish
+
+`ingest_publish { documentId }`. The norm is now queryable in your workspace
+via `list_norms`, `get_toc`, `get_section`, `search_in_norm`, `get_figure`, etc.
+
+## Quality bar
+
+- Trust the pre-pass for `path` + `pageStart`/`pageEnd` — it's deterministic
+  and verified against the PDF bookmarks.
+- Summaries drive navigation — be specific (mention key formulas/values).
+- Keep `content` faithful to the source; don't invent values.
+- If PyMuPDF mangled a formula (Greek letters, fractions, exponents broken),
+  re-read the relevant PDF page visually and write proper LaTeX.
+- Never skip annexes — they hold key numeric values (zones, coefficients,
+  characteristic loads).