@stratta/mcp 0.9.7 → 0.10.0

package/README.md

@@ -20,6 +20,25 @@ MCP server exposing Swiss engineering norms (SIA / Eurocodes) to Claude clients
 > a shell environment variable. If a key leaks, revoke it immediately at
 > https://stratta.ch/api-keys.
 
+## Do you need this package?
+
+Often not. Stratta also runs as a **remote connector** — one address, a browser
+sign-in, no key and no Node:
+
+```
+https://stratta.ch/mcp
+```
+
+That is the shorter path, and the only one that works in an agent running in the
+cloud (claude.ai). See https://stratta.ch/docs/en/guides/connect-remote.
+
+This package is what you want when:
+
+- you are **ingesting a norm** — it reads a PDF from your disk and runs a Python
+  pre-pass, neither of which a remote connector can reach;
+- your agent **cannot open a browser** — CI, a scheduled task, a server;
+- you would simply rather run the server yourself.
+
 ## Install
 
 ### Claude Code (recommended)
@@ -148,15 +167,17 @@ settings come from environment variables — see [`.env.example`](./.env.example
 | `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.                          |
+**Dossier** (7 tools — keep what was decided on a project):
+
+| Tool               | Purpose                                                                                  |
+| ------------------ | ---------------------------------------------------------------------------------------- |
+| `list_dossiers`    | Your organisation's dossiers, most recently touched first, with open-question counts.    |
+| `open_dossier`     | Open a project's dossier, creating it if needed. Idempotent on the name.                 |
+| `open_question`    | Open one question to settle, with optional named options. Idempotent on the title.       |
+| `save_finding`     | Record one piece of evidence: a cited article, a retained value and why, an observation. |
+| `record_decision`  | Settle a question with a decision the engineer has confirmed, and the retained option.   |
+| `load_dossier`     | Reload everything: questions with their evidence and decisions, open ones first.         |
+| `resolve_question` | Close a question without a decision, or reopen one. The evidence stays.                  |
 
 A dossier is read, annotated, reviewed and exported from
 [stratta.ch/dossiers](https://stratta.ch/dossiers).

package/dist/tools/dossier.d.ts

@@ -4,14 +4,34 @@ export declare const openDossier: import("./define.js").ToolDef<{
     name: z.ZodString;
     reference: z.ZodOptional<z.ZodString>;
 }>;
+export declare const openQuestion: import("./define.js").ToolDef<{
+    dossierId: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}>;
 export declare const saveFinding: import("./define.js").ToolDef<{
+    title: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        established: "established";
+        judgement: "judgement";
+        to_confirm: "to_confirm";
+    }>>;
+    normCode: z.ZodOptional<z.ZodString>;
+    sectionPath: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    normEdition: z.ZodOptional<z.ZodString>;
     dossierId: z.ZodString;
+    questionId: z.ZodOptional<z.ZodString>;
     kind: z.ZodEnum<{
         reference: "reference";
         hypothesis: "hypothesis";
         observation: "observation";
-        question: "question";
     }>;
+}>;
+export declare const recordDecision: import("./define.js").ToolDef<{
     title: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     value: z.ZodOptional<z.ZodString>;
@@ -23,13 +43,16 @@ export declare const saveFinding: import("./define.js").ToolDef<{
     normCode: z.ZodOptional<z.ZodString>;
     sectionPath: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
+    normEdition: z.ZodOptional<z.ZodString>;
+    questionId: z.ZodString;
+    retainedOption: z.ZodOptional<z.ZodString>;
 }>;
 export declare const loadDossier: import("./define.js").ToolDef<{
     dossierId: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
 }>;
 export declare const resolveQuestion: import("./define.js").ToolDef<{
-    entryId: z.ZodString;
+    questionId: z.ZodString;
     resolved: z.ZodOptional<z.ZodBoolean>;
 }>;
 export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("./define.js").ToolDef<{
@@ -37,12 +60,30 @@ export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("
     reference: z.ZodOptional<z.ZodString>;
 }> | import("./define.js").ToolDef<{
     dossierId: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}> | import("./define.js").ToolDef<{
+    title: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodOptional<z.ZodEnum<{
+        established: "established";
+        judgement: "judgement";
+        to_confirm: "to_confirm";
+    }>>;
+    normCode: z.ZodOptional<z.ZodString>;
+    sectionPath: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodNumber>;
+    normEdition: z.ZodOptional<z.ZodString>;
+    dossierId: z.ZodString;
+    questionId: z.ZodOptional<z.ZodString>;
     kind: z.ZodEnum<{
         reference: "reference";
         hypothesis: "hypothesis";
         observation: "observation";
-        question: "question";
     }>;
+}> | import("./define.js").ToolDef<{
     title: z.ZodString;
     detail: z.ZodOptional<z.ZodString>;
     value: z.ZodOptional<z.ZodString>;
@@ -54,10 +95,13 @@ export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("
     normCode: z.ZodOptional<z.ZodString>;
     sectionPath: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
+    normEdition: z.ZodOptional<z.ZodString>;
+    questionId: z.ZodString;
+    retainedOption: z.ZodOptional<z.ZodString>;
 }> | import("./define.js").ToolDef<{
     dossierId: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
 }> | import("./define.js").ToolDef<{
-    entryId: z.ZodString;
+    questionId: z.ZodString;
     resolved: z.ZodOptional<z.ZodBoolean>;
 }>)[];

package/dist/tools/dossier.js

@@ -3,17 +3,24 @@ import { api } from '../client.js';
 import { requireApiKey } from '../auth.js';
 import { defineTool } from './define.js';
 /**
- * The five dossier tools: how the work survives the conversation.
+ * The seven dossier tools: how the work survives the conversation.
  *
  * Everything else here reads a norm. These write down what was decided with
  * it, so the next conversation starts where the last one stopped and a human
  * can review it in the app.
  *
+ * A dossier is a set of QUESTIONS. Each question holds the evidence gathered
+ * for it, the options on the table and, once the engineer has confirmed it, a
+ * decision. The question is the unit of work: it is what gets assigned,
+ * reviewed and closed. The first model was a flat journal, and the one real
+ * dossier it produced held a single "question" with eight sub-questions in its
+ * body — unassignable, unanswerable one at a time, unreadable.
+ *
  * The descriptions carry more instruction than the read tools do, on purpose.
  * An agent left to guess will either record nothing — and the feature is dead
  * — or record every sentence it produces, which buries the three decisions
  * that mattered. `get_methodology` tells it when to open a dossier; these tell
- * it what is worth putting in one.
+ * it what is worth putting in one, and in what shape.
  */
 const write = { readOnlyHint: false, openWorldHint: false };
 const readOnly = { readOnlyHint: true, openWorldHint: false };
@@ -21,10 +28,57 @@ const dossierId = z
     .string()
     .min(1)
     .describe('Dossier id returned by open_dossier or list_dossiers.');
+const questionId = z
+    .string()
+    .min(1)
+    .describe('Question id returned by open_question or load_dossier.');
+/** The fields a piece of evidence or a decision carries. */
+const entryFields = {
+    title: z
+        .string()
+        .min(1)
+        .max(200)
+        .describe('The fact in one line, as an engineer would write it in a report. One clause, one value or one observation; not a theme.'),
+    detail: z
+        .string()
+        .max(4000)
+        .optional()
+        .describe('The reasoning, in one or two sentences: why this value, what it rests on, what disagreed. Required in practice for a hypothesis.'),
+    value: z
+        .string()
+        .max(120)
+        .optional()
+        .describe('The retained value WITH its unit, e.g. "30°", "1,25 kN/m²".'),
+    confidence: z
+        .enum(['established', 'judgement', 'to_confirm'])
+        .optional()
+        .describe('How firm the value is. See the tool description.'),
+    normCode: z
+        .string()
+        .max(40)
+        .optional()
+        .describe('Norm this comes from, e.g. "SIA 267".'),
+    sectionPath: z
+        .string()
+        .max(60)
+        .optional()
+        .describe('Exact section path, e.g. "9.5.2.1".'),
+    page: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Page in the norm, so a human can verify it in their PDF.'),
+    normEdition: z
+        .string()
+        .max(40)
+        .optional()
+        .describe('The edition cited, e.g. "2013" or "2020 + rect. 2022", when list_norms gives it.'),
+};
 export const listDossiers = defineTool({
     name: 'list_dossiers',
     title: 'List dossiers',
-    description: 'List the dossiers of YOUR organisation, most recently touched first. A dossier is a project record: what was decided, what it rests on, and what is still open. Call this when the user mentions a project by name, or asks what they were working on. Each row carries the count of entries and of UNRESOLVED questions — a dossier with open questions is the one to resume.',
+    description: 'List the dossiers of YOUR organisation, most recently touched first. A dossier is a project record: the questions to settle, what was decided, what it rests on. Call this when the user mentions a project by name, or asks what they were working on. Each row carries the count of entries and of OPEN questions — a dossier with open questions is the one to resume.',
     inputSchema: {},
     annotations: readOnly,
     run: async (client) => ({
@@ -36,7 +90,7 @@ export const listDossiers = defineTool({
 export const openDossier = defineTool({
     name: 'open_dossier',
     title: 'Open a dossier',
-    description: "Open the dossier for a project, creating it if it does not exist yet. IDEMPOTENT on the name: calling it twice with the same name returns the same dossier rather than splitting a project's history in two. Call this when the user starts working on a named project and there is something worth keeping — a retained value, an assumption, a site observation, an unanswered question. Do not open one for a passing lookup. Returns { dossierId, created }.",
+    description: "Open the dossier for a project, creating it if it does not exist yet. IDEMPOTENT on the name: calling it twice with the same name returns the same dossier rather than splitting a project's history in two. Call this when the user starts working on a named project and there is something worth keeping — a question to settle, a retained value, an assumption, a site observation. Do not open one for a passing lookup. Returns { dossierId, created }.",
     inputSchema: {
         name: z
             .string()
@@ -56,63 +110,89 @@ export const openDossier = defineTool({
         reference: args.reference,
     }),
 });
+export const openQuestion = defineTool({
+    name: 'open_question',
+    title: 'Open a question',
+    description: `Open ONE question to settle in a dossier, BEFORE gathering evidence for it. A question is the unit of work: "Can pile P38 be kept?", "Which φ'k do we retain for the fill?", "Is kinematic interaction to be checked?". Evidence saved with save_finding and the eventual record_decision hang off it.
+
+ONE QUESTION PER THING TO SETTLE. Never put a list of sub-questions in the body: a question that bundles eight cannot be assigned, answered or closed one at a time. Open eight questions.
+
+IDEMPOTENT on the title: reopening the same wording returns the question already open, with its evidence. Name the options on the table in \`options\` when the user or the norm puts several forward ("abandon the pile", "recover it by re-concreting plus integrity tests", "redistribute onto P37/P39"). Returns { questionId, created }.`,
+    inputSchema: {
+        dossierId,
+        title: z
+            .string()
+            .min(1)
+            .max(200)
+            .describe('The question in one line, phrased as a question.'),
+        body: z
+            .string()
+            .max(4000)
+            .optional()
+            .describe('What is at stake and why it is not settled, in two or three sentences. Not a list of sub-questions.'),
+        options: z
+            .array(z.string().min(1).max(120))
+            .max(10)
+            .optional()
+            .describe('The ways this could be settled, one short name each.'),
+    },
+    annotations: { ...write, idempotentHint: true },
+    run: (client, args) => client.action(api.dossiersApi.openQuestion, {
+        apiKey: requireApiKey(),
+        dossierId: args.dossierId,
+        title: args.title,
+        body: args.body,
+        options: args.options,
+    }),
+});
 export const saveFinding = defineTool({
     name: 'save_finding',
-    title: 'Save a finding to a dossier',
-    description: `Record ONE decision in a dossier. Call it as you work, not in a batch at the end — a finding saved when it is made carries the reasoning that produced it.
+    title: 'Record evidence in a dossier',
+    description: `Record ONE piece of evidence in a dossier. Call it as you work, not in a batch at the end — a finding saved when it is made carries the reasoning that produced it.
 
 WHAT TO RECORD, by kind:
 - reference: what a norm says, that the project relies on. ALWAYS fill normCode + sectionPath (+ page). If you cannot cite it, it is not a reference.
 - hypothesis: a value the engineer RETAINS, and why. This is the one that matters most in geotechnics, where a retained value is a judgement between disagreeing measurements rather than the output of a formula. Put the number in \`value\` and the reasoning in \`detail\`.
 - observation: what the site, a borehole, or a survey showed. Include the date in \`detail\` when known.
-- question: something not settled. These surface FIRST when the dossier is reloaded, so record them even when you cannot answer — especially then.
 
-WHAT NOT TO RECORD: your own prose, intermediate steps, anything the user did not treat as a decision. A dossier of forty entries where three mattered is worse than a dossier of three.
+KEEP IT SHORT: one clause, one value or one fact per call, in one or two sentences. Three short entries beat one paragraph that mixes the citation, the reasoning and the consequence. A question is NOT recorded here: call open_question. A decision is NOT recorded here: call record_decision.
+
+FILE IT: pass \`questionId\` so the entry lands under the question it serves. If you do not yet know which question it serves, save it anyway without one — the engineer files it later.
 
 Set \`confidence\` whenever the entry is a value: established (computed or read directly), judgement (the engineer chose it), to_confirm (provisional, needs a test or a check). Confusing those three is the professional fault this field exists to prevent.`,
     inputSchema: {
         dossierId,
+        questionId: questionId
+            .optional()
+            .describe('The question this evidence serves, from open_question or load_dossier. Omit only when you do not know yet.'),
         kind: z
-            .enum(['reference', 'hypothesis', 'observation', 'question'])
+            .enum(['reference', 'hypothesis', 'observation'])
             .describe('See the tool description: pick by what the entry IS.'),
-        title: z
-            .string()
-            .min(1)
-            .max(200)
-            .describe('The decision in one line, as an engineer would write it in a report.'),
-        detail: z
-            .string()
-            .max(4000)
-            .optional()
-            .describe('The reasoning: why this value, what it rests on, what disagreed. Required in practice for a hypothesis — without it the entry cannot be reviewed.'),
-        value: z
+        ...entryFields,
+    },
+    annotations: write,
+    run: (client, args) => client.action(api.dossiersApi.saveFinding, {
+        apiKey: requireApiKey(),
+        ...args,
+    }),
+});
+export const recordDecision = defineTool({
+    name: 'record_decision',
+    title: 'Record a decision',
+    description: `Settle a question with a decision the engineer has CONFIRMED: what was decided, why, and the clause it rests on. The question leaves the open items and keeps its evidence; the decision becomes the entry a reviewer reads first.
+
+Only call this once the user has confirmed the decision, never on your own reasoning. Name the retained option in \`retainedOption\` when the question listed some (the name as it was given; an option not listed yet is created). Put the number in \`value\` when the decision is a value, and set \`confidence\`. Returns { entryId }.`,
+    inputSchema: {
+        questionId,
+        retainedOption: z
             .string()
             .max(120)
             .optional()
-            .describe('The retained value WITH its unit, e.g. "30°", "1,25 kN/m²".'),
-        confidence: z
-            .enum(['established', 'judgement', 'to_confirm'])
-            .optional()
-            .describe('How firm the value is. See the tool description.'),
-        normCode: z
-            .string()
-            .max(40)
-            .optional()
-            .describe('Norm this comes from, e.g. "SIA 261".'),
-        sectionPath: z
-            .string()
-            .max(60)
-            .optional()
-            .describe('Exact section path, e.g. "14.2".'),
-        page: z
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe('Page in the norm, so a human can verify it in their PDF.'),
+            .describe('The option that was retained, by name.'),
+        ...entryFields,
     },
     annotations: write,
-    run: (client, args) => client.action(api.dossiersApi.saveFinding, {
+    run: (client, args) => client.action(api.dossiersApi.recordDecision, {
         apiKey: requireApiKey(),
         ...args,
     }),
@@ -120,7 +200,7 @@ Set \`confidence\` whenever the entry is a value: established (computed or read
 export const loadDossier = defineTool({
     name: 'load_dossier',
     title: 'Load a dossier',
-    description: 'Reload everything a dossier holds: retained values, what they rest on, site observations, open questions and the comments a colleague left. UNRESOLVED QUESTIONS COME FIRST — read them before anything else and tell the user what is still open. Call this whenever the user returns to a project ("reprends le dossier X", "on en était où sur Y") BEFORE answering anything about it, so you build on what was decided instead of deciding it again. Accepts either the id or the name the user uses.',
+    description: 'Reload everything a dossier holds: its questions with their evidence, options and decisions, then the evidence not yet filed under a question, then the comments a colleague left. OPEN QUESTIONS COME FIRST — read them before anything else and tell the user what is still open. Call this whenever the user returns to a project ("reprends le dossier X", "on en était où sur Y") BEFORE answering anything about it, so you build on what was decided instead of deciding it again. Accepts either the id or the name the user uses.',
     inputSchema: {
         dossierId: z
             .string()
@@ -143,23 +223,20 @@ export const loadDossier = defineTool({
 });
 export const resolveQuestion = defineTool({
     name: 'resolve_question',
-    title: 'Close an open question',
-    description: 'Mark a question entry as settled, once it actually is. The entry stays in the dossier — the trail of what was once uncertain is part of the record — but it stops surfacing at the top on reload. Only call this when the user has confirmed the answer, never on your own reasoning.',
+    title: 'Close a question',
+    description: 'Close a question that stopped mattering WITHOUT a decision: the variant was abandoned, the client withdrew the request, the point became moot. The question stays in the dossier, marked closed, with its evidence. To settle a question with an answer, call record_decision instead. Pass resolved: false to reopen a question. Only call this when the user says so, never on your own reasoning.',
     inputSchema: {
-        entryId: z
-            .string()
-            .min(1)
-            .describe('Entry id of the question, from load_dossier.'),
+        questionId,
         resolved: z
             .boolean()
             .optional()
-            .describe('Defaults to true. Pass false to reopen a question.'),
+            .describe('Defaults to true (close). Pass false to reopen.'),
     },
     annotations: { ...write, idempotentHint: true },
     run: async (client, args) => {
         await client.action(api.dossiersApi.resolveQuestion, {
             apiKey: requireApiKey(),
-            entryId: args.entryId,
+            questionId: args.questionId,
             resolved: args.resolved,
         });
         return { ok: true };
@@ -168,7 +245,9 @@ export const resolveQuestion = defineTool({
 export const dossierTools = [
     listDossiers,
     openDossier,
+    openQuestion,
     saveFinding,
+    recordDecision,
     loadDossier,
     resolveQuestion,
 ];

package/dist/tools/read.js

@@ -44,7 +44,7 @@ export const listNorms = defineTool({
 export const getToc = defineTool({
     name: 'get_toc',
     title: 'Get table of contents',
-    description: "Get the high-level table of contents for a norm. By default returns only top-level chapters (depth=1) to stay light. Call get_subtree on a specific chapter's path to drill into sections + subsections. Increase maxDepth if you need a wider overview (cost: response size grows fast). Each node has nodeId, path, title, summary, pageStart, pageEnd, depth, and children (empty at the maxDepth boundary).",
+    description: "Get the high-level table of contents for a norm. By default returns only top-level chapters (depth=1) to stay light. Call get_subtree on a specific chapter's path to drill into sections + subsections. Increase maxDepth if you need a wider overview (cost: response size grows fast). Each node has path, title, summary, pageStart, pageEnd, depth, and children (empty at the maxDepth boundary).",
     inputSchema: {
         norm,
         maxDepth: z
@@ -76,7 +76,7 @@ export const getToc = defineTool({
 export const getSubtree = defineTool({
     name: 'get_subtree',
     title: 'Get subtree',
-    description: 'Drill down into a specific chapter or section. Returns the subtree rooted at `path` with optional depth limit (relative to the root). Use this after get_toc to explore one chapter in detail without fetching the entire TOC. Each node has nodeId, path, title, summary, depth, pageStart, pageEnd, and recursive children.',
+    description: 'Drill down into a specific chapter or section. Returns the subtree rooted at `path` with optional depth limit (relative to the root). Use this after get_toc to explore one chapter in detail without fetching the entire TOC. Each node has path, title, summary, depth, pageStart, pageEnd, and recursive children.',
     inputSchema: {
         norm,
         path: sectionPath.describe('Section path to root the subtree at, e.g. "14" or "14.2".'),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "ch.stratta/mcp",
-  "version": "0.9.7",
+  "version": "0.10.0",
   "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>",

package/scripts/ingest-prepass.py

@@ -77,10 +77,163 @@ def detect_running_text(doc: "fitz.Document") -> set[str]:
 CHAP_UPPER_RE = re.compile(
     r"^(\d+)\s+([A-ZÉÈÀÂÔÎÛÇ][^a-z\n]{3,120})\s*$", re.MULTILINE
 )
+# Norms adopted from CEN (SIA 262.6xx, SIA 267.1xx) set their headings in
+# sentence case, which CHAP_UPPER_RE rejects by design. Used only as a second
+# pass, when the uppercase form found almost nothing — on a native SIA norm it
+# would promote body sentences to chapters.
+CHAP_MIXED_RE = re.compile(
+    r"^(\d{1,2})\s+([A-ZÀ-Þ][A-Za-zÀ-ÿ][^\n]{2,90})\s*$", re.MULTILINE
+)
 ANNEX_BODY_RE = re.compile(
     r"^(?:ANNEXE|Annexe)\s+([A-Z])(?:\s*\(([^)]+)\))?\s*(.*?)$", re.MULTILINE
 )
 
+# A heading split across two lines: the number alone, the title underneath.
+# Comes from the numbering column of CEN-style layouts, where PyMuPDF reads the
+# column before the text. Left as-is, every regex below misses the heading.
+SPLIT_NUM_RE = re.compile(r"^\s*(\d{1,2}(?:\.\d{1,2}){0,3})\s*$")
+SPLIT_TITLE_RE = re.compile(r"^\s*([A-ZÀ-Þ][A-Za-zÀ-ÿ'’\-][^\n]{2,90})\s*$")
+# Words that open a continuing sentence, never a heading.
+SPLIT_STOP_RE = re.compile(
+    r"^(Le |La |Les |Il |Elle |Dans |Pour |Selon |Cette |Ce |Ces |Si |En |Au |Aux |De |Des |Du |Un |Une )",
+)
+
+
+def join_split_headings(text: str) -> str:
+    """Rewrite `12\\nTitre` as `12 Titre` so the heading regexes can see it.
+
+    Conservative on purpose: the title line must look like a title (starts
+    uppercase, no sentence-ending punctuation, not a sentence opener). A false
+    join invents a chapter, which is worse than missing one.
+    """
+    lines = text.splitlines()
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        m = SPLIT_NUM_RE.match(lines[i])
+        if m and i + 1 < len(lines):
+            nxt = lines[i + 1]
+            t = SPLIT_TITLE_RE.match(nxt)
+            if t and not nxt.rstrip().endswith((".", ",", ";", ":")) and not SPLIT_STOP_RE.match(t.group(1)):
+                out.append(f"{m.group(1)} {t.group(1).strip()}")
+                i += 2
+                continue
+        out.append(lines[i])
+        i += 1
+    return "\n".join(out)
+
+
+def heading_text(doc: "fitz.Document", pageno: int) -> str:
+    """Page text prepared for heading detection (never for section content)."""
+    return join_split_headings(doc[pageno].get_text("text"))
+
+
+NOT_A_TITLE_RE = re.compile(
+    r"^(?:EN|SN|ISO|DIN|SIA|NOTE|Tableau|Figure|Table|Bild)\b|^\W|\.$", re.IGNORECASE
+)
+# A heading cut mid-phrase by the column break: "Résistance à la flexion au".
+TRUNCATED_RE = re.compile(
+    r"\b(?:ou|et|au|aux|de|des|du|le|la|les|un|une|dans|pour|par|sur|avec|sans|selon|entre)$",
+    re.IGNORECASE,
+)
+
+
+def plausible_title(title: str) -> bool:
+    """Reject what a numbered line can be other than a heading.
+
+    A stray table cell ("I ~ ~"), a normative reference ("EN 12063:2024 (F)") or
+    a wrapped sentence all match the heading shape. Promoting one invents a
+    chapter, and an invented chapter swallows the page range of a real one.
+    """
+    t = title.strip()
+    if not 3 <= len(t) <= 90:
+        return False
+    # A normative heading is capitalised. A lowercase one is a table row that
+    # happens to sit behind a number ("2.3 retrait des obstacles").
+    if not (t[0].isupper() or t[0].isdigit()):
+        return False
+    if NOT_A_TITLE_RE.search(t):
+        return False
+    if SPLIT_STOP_RE.match(t) or TRUNCATED_RE.search(t):
+        return False
+    letters = sum(1 for c in t if c.isalpha() or c.isspace())
+    return letters / len(t) >= 0.7
+
+
+def dense_heading_pages(doc: "fitz.Document", toc_pages: set[int]) -> set[int]:
+    """Pages listing many numbered headings: a contents page, whatever its
+    typography. Detecting it by leader dots alone misses the ones set without
+    them, and every heading read there points at the contents page instead of
+    the section it names."""
+    dense: set[int] = set()
+    for i in range(doc.page_count):
+        if i in toc_pages:
+            continue
+        found = {m.group(1) for m in SUB_RE.finditer(heading_text(doc, i))}
+        # A page of the body drills into one chapter; a contents page walks
+        # across several. Counting headings alone would drop a dense page of
+        # definitions (3.1 … 3.8), which is real content.
+        if len(found) >= 5 and len({n.split(".", 1)[0] for n in found}) >= 3:
+            dense.add(i)
+    return dense
+
+
+def prune_chapters(chapters: dict[str, dict]) -> dict[str, dict]:
+    """Keep the run of chapter numbers that reads like a table of contents.
+
+    Real chapters are consecutive and move forward through the document. A lone
+    "25" between chapters 1 and 2, or a chapter that starts thirty pages before
+    the one preceding it, is a detection artefact.
+    """
+    numbered = sorted(((int(k), k) for k in chapters if k.isdigit()))
+    if not numbered:
+        return chapters
+
+    # A norm with N detected chapters does not have a chapter 40. Missing a few
+    # headings is normal; a number far past the count is a table cell.
+    ceiling = 2 * len(numbered) + 3
+    numbered = [(n, k) for n, k in numbered if n <= ceiling]
+    if not numbered:
+        return chapters
+
+    # Longest run whose pages move forward, so one bad page does not discard
+    # every chapter after it.
+    best = [1] * len(numbered)
+    prev = [-1] * len(numbered)
+    for i in range(len(numbered)):
+        page_i = chapters[numbered[i][1]]["pageStart"]
+        for j in range(i):
+            if chapters[numbered[j][1]]["pageStart"] <= page_i and best[j] + 1 > best[i]:
+                best[i], prev[i] = best[j] + 1, j
+    idx = best.index(max(best))
+    chain = []
+    while idx != -1:
+        chain.append(numbered[idx][1])
+        idx = prev[idx]
+
+    # Missing a heading or two leaves a small gap; doubling (10 → 20 → 30) means
+    # the numbers stopped being chapters and started being table rows.
+    kept: dict[str, dict] = {}
+    previous = None
+    for key in reversed(chain):
+        n = int(key)
+        if previous is not None and n - previous > 3 and n >= 2 * previous:
+            break
+        kept[key] = chapters[key]
+        previous = n
+
+    # Annexes close a norm, in order. One that lands before the last chapter was
+    # read off the contents page, and its page range would swallow the document.
+    last_page = max((m["pageStart"] for m in kept.values()), default=0)
+    for key, meta in sorted(
+        ((k, m) for k, m in chapters.items() if not k.isdigit()), key=lambda kv: kv[0]
+    ):
+        if meta["pageStart"] < last_page:
+            continue
+        kept[key] = meta
+        last_page = meta["pageStart"]
+    return kept
+
 
 def extract_chapters(
     doc: "fitz.Document", toc_pages: set[int] | None = None
@@ -105,32 +258,64 @@ def extract_chapters(
     if chapters:
         return chapters
 
-    # Fallback: no bookmarks → scan body for uppercase chapter headings.
-    skip = toc_pages or set()
-    for pageno in range(doc.page_count):
-        if pageno in skip:
-            continue
-        text = doc[pageno].get_text("text")
-        for m in CHAP_UPPER_RE.finditer(text):
-            num = m.group(1)
-            title = clean(m.group(2))
-            if int(num) > 50:
-                continue
-            if num in chapters:
-                continue
-            chapters[num] = {"title": title, "pageStart": pageno + 1}
-        for m in ANNEX_BODY_RE.finditer(text):
-            letter = m.group(1)
-            kind = m.group(2) or ""
-            rest = clean(m.group(3) or "")
-            path = f"Annexe {letter}"
-            if path in chapters:
+    # Fallback: no bookmarks → scan body for chapter headings.
+    skip = set(toc_pages or set())
+
+    def scan(pattern: "re.Pattern[str]", skip_pages: set[int]) -> dict[str, dict]:
+        found: dict[str, dict] = {}
+        for pageno in range(doc.page_count):
+            if pageno in skip_pages:
                 continue
-            t = path + (f" ({kind})" if kind else "")
-            if rest and rest.lower() != path.lower():
-                t += f" — {rest}"
-            chapters[path] = {"title": t, "pageStart": pageno + 1}
-    return chapters
+            text = heading_text(doc, pageno)
+            for m in pattern.finditer(text):
+                num, title = m.group(1), clean(m.group(2))
+                if int(num) > 50 or num in found or not plausible_title(title):
+                    continue
+                found[num] = {"title": title, "pageStart": pageno + 1}
+            for m in ANNEX_BODY_RE.finditer(text):
+                letter, kind = m.group(1), m.group(2) or ""
+                rest = clean(m.group(3) or "")
+                path = f"Annexe {letter}"
+                if path in found:
+                    continue
+                t = path + (f" ({kind})" if kind else "")
+                if rest and rest.lower() != path.lower():
+                    t += f" — {rest}"
+                found[path] = {"title": t, "pageStart": pageno + 1}
+        return found
+
+    def toc_like_pages(found: dict[str, dict]) -> set[int]:
+        """Pages holding three or more chapter headings are the table of
+        contents, whatever the typography. Without this every chapter of such a
+        norm starts on the contents page, and every section body is wrong."""
+        per_page: dict[int, int] = defaultdict(int)
+        for meta in found.values():
+            per_page[meta["pageStart"]] += 1
+        return {p - 1 for p, n in per_page.items() if n >= 3}
+
+    for pattern in (CHAP_UPPER_RE, CHAP_MIXED_RE):
+        chapters = scan(pattern, skip)
+        extra = toc_like_pages(chapters)
+        if extra:
+            chapters = scan(pattern, skip | extra)
+        if len([k for k in chapters if k.isdigit()]) >= 3:
+            break
+
+    return prune_chapters(chapters)
+
+
+def chapter_page_spans(chapters: dict[str, dict], n_pages: int) -> dict[str, tuple[int, int]]:
+    """First and last page of each numbered chapter, from where the next starts."""
+    ordered = sorted(
+        ((k, v["pageStart"]) for k, v in chapters.items()),
+        key=lambda kv: kv[1],
+    )
+    spans: dict[str, tuple[int, int]] = {}
+    for idx, (key, start) in enumerate(ordered):
+        end = ordered[idx + 1][1] - 1 if idx + 1 < len(ordered) else n_pages
+        if key.isdigit():
+            spans[key] = (start, max(start, end))
+    return spans
 
 
 def extract_subsections(
@@ -138,13 +323,15 @@ def extract_subsections(
     chap_prefixes: set[str],
     toc_pages: set[int],
     running: set[str],
+    chapter_spans: dict[str, tuple[int, int]] | None = None,
 ) -> dict[str, tuple[str, int]]:
     """Numeric sub-sections (depths 2-4) detected in body pages."""
     out: dict[str, tuple[str, int]] = {}
+    skip = set(toc_pages) | dense_heading_pages(doc, toc_pages)
     for i in range(doc.page_count):
-        if i in toc_pages:
+        if i in skip:
             continue
-        text = doc[i].get_text("text")
+        text = heading_text(doc, i)
         for m in SUB_RE.finditer(text):
             num = m.group(1)
             title = clean(m.group(2))
@@ -153,7 +340,13 @@ def extract_subsections(
             top = num.split(".", 1)[0]
             if top not in chap_prefixes:
                 continue
-            if len(title) < 3 or re.fullmatch(r"[^A-Za-zÀ-ÿ]+", title):
+            # A sub-section sits inside its chapter. "1.1" found sixty pages
+            # after chapter 1 ended is a numbered line in an annexe, and keeping
+            # it hangs an unrelated page under the wrong parent.
+            span = chapter_spans.get(top) if chapter_spans else None
+            if span and not span[0] <= i + 1 <= span[1]:
+                continue
+            if not plausible_title(title):
                 continue
             if num in out:
                 continue
@@ -218,6 +411,44 @@ def extract_section_text(doc: "fitz.Document", nodes: list[dict]) -> None:
         chunks = page_texts[ps - 1 : pe]
         node["rawText"] = "\n".join(chunks).strip()
 
+    trim_shared_pages(nodes, page_texts)
+
+
+def trim_shared_pages(nodes: list[dict], page_texts: list[str]) -> None:
+    """Cut the opening page where several sections start on it.
+
+    Page granularity is the unit everywhere else, but two sections beginning on
+    the same page would otherwise carry byte-identical text — so a summary reads
+    like its neighbour's, and the table of contents misleads before anything is
+    even opened.
+    """
+    by_page: dict[int, list[dict]] = defaultdict(list)
+    for node in nodes:
+        by_page[node["pageStart"]].append(node)
+
+    for page, group in by_page.items():
+        if len(group) < 2:
+            continue
+        text = page_texts[page - 1]
+        # Where each section's heading sits on that page, in reading order.
+        marks: list[tuple[int, dict]] = []
+        for node in group:
+            title = node["title"].split(" — ")[-1].strip()
+            at = text.find(title) if len(title) >= 4 else -1
+            if at == -1:
+                at = text.find(f"{node['path']} ")
+            marks.append((at, node))
+        if any(at == -1 for at, _ in marks):
+            continue  # a heading we cannot locate: leave the whole page in place
+        marks.sort(key=lambda m: m[0])
+        for i, (at, node) in enumerate(marks):
+            end = marks[i + 1][0] if i + 1 < len(marks) else len(text)
+            head = text[at:end].strip()
+            if not head:
+                continue
+            rest = "\n".join(page_texts[node["pageStart"] : node["pageEnd"]]).strip()
+            node["rawText"] = f"{head}\n{rest}".strip() if rest else head
+
 
 def extract_figures(
     doc: "fitz.Document",
@@ -295,7 +526,8 @@ def main() -> None:
     running = detect_running_text(doc)
     chapters = extract_chapters(doc, toc_pages)
     chap_prefixes = {k for k in chapters if k.isdigit()}
-    subsections = extract_subsections(doc, chap_prefixes, toc_pages, running)
+    spans = chapter_page_spans(chapters, doc.page_count)
+    subsections = extract_subsections(doc, chap_prefixes, toc_pages, running, spans)
     nodes = build_tree(chapters, subsections, doc.page_count)
     extract_section_text(doc, nodes)
     figures = extract_figures(doc, toc_pages, out_dir, dpi=args.dpi)