@stratta/mcp 0.15.0 → 1.16.0

package/README.md

@@ -34,7 +34,7 @@ https://stratta.ch/mcp
 That is the shorter path, the one the dashboard walks you through for Claude,
 ChatGPT, Claude Code, Codex, Cursor, VS Code, Gemini CLI and Windsurf, and the
 only one that works in an agent running in the cloud (claude.ai, ChatGPT). It
-serves 54 of the 55 tools below, **ingestion included**: the pre-pass script is
+serves 58 of the 59 tools below, **ingestion included**: the pre-pass script is
 downloaded from https://stratta.ch/ingest-prepass.py when it is not on disk.
 See https://stratta.ch/docs/en/guides/connect-remote.
 
@@ -176,8 +176,8 @@ named `E2E dossier <timestamp>` and does not delete it.
 
 ## Tools exposed
 
-55 tools, generated from one catalogue shared with the remote connector (which
-serves the same 54, everything minus `add_attachment`).
+59 tools, generated from one catalogue shared with the remote connector (which
+serves the same 58, everything minus `add_attachment`).
 
 **Read** (10 tools — query the norms of your workspace):
 
@@ -211,33 +211,37 @@ serves the same 54, everything minus `add_attachment`).
 
 **Dossier** (25 tools — keep what was decided on a project, and everything the dossier page can do to a question):
 
-| Tool                   | Purpose                                                                                                |
-| ---------------------- | ------------------------------------------------------------------------------------------------------ |
-| `list_dossiers`        | Your organisation's dossiers, most recently touched first, with open-question counts and site id.      |
-| `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.                                |
-| `list_attachments`     | The project attachments of a dossier: site reports, borehole logs, minutes, data sheets.               |
-| `read_attachment`      | Read an attachment's text as Markdown, page by page.                                                   |
-| `search_in_dossier`    | Full-text search over a dossier's attachments, with the page of each hit.                              |
-| `add_attachment`       | Upload a file from the user's machine to a dossier (PDF, DOCX, XLSX, images, text). Local server only. |
-| `list_templates`       | The checklists the organisation wrote for its types of structure.                                      |
-| `apply_template`       | Open a template's questions in a dossier and file the clauses that resolve in the corpus.              |
-| `list_questions`       | The questions of a dossier, paginated, with status, assignee, due date, options and decision title.    |
-| `get_question`         | One question in full: options, decision, evidence with every citation field, comments with authors.    |
-| `get_dossier_activity` | The history of a dossier, most recent first, paginated: who did what, from the app or an agent.        |
-| `list_exports`         | The verification notes and journals exported from a dossier, with hash and trusted timestamp.          |
-| `update_question`      | Reword a question, assign it by e-mail address, set or clear its due date.                             |
-| `add_option`           | Add one way of settling a question. Idempotent on the name.                                            |
-| `update_option`        | Rename or describe an option, or mark it retained (the others are released).                           |
-| `delete_option`        | Remove an option; its evidence stays on the question. Asks the user first.                             |
-| `delete_question`      | Delete a question opened by mistake; its evidence stays, unfiled. Asks the user first.                 |
-| `add_comment`          | Leave a signed remark on a dossier, a question or an entry.                                            |
-| `update_entry`         | Correct an entry's wording, value, confidence or citation in place.                                    |
-| `attach_entry`         | File an entry under a question and optionally an option, or unfile it.                                 |
+| Tool                   | Purpose                                                                                                       |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `list_dossiers`        | Your organisation's dossiers, most recently touched first, with open-question counts and site id.             |
+| `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.                                       |
+| `list_attachments`     | The project attachments of a dossier: site reports, borehole logs, minutes, data sheets.                      |
+| `read_attachment`      | Read an attachment's text as Markdown, page by page.                                                          |
+| `search_in_dossier`    | Full-text search over a dossier's attachments, with the page of each hit.                                     |
+| `add_attachment`       | Upload a file from the user's machine to a dossier (PDF, DOCX, XLSX, images, text). Local server only.        |
+| `list_templates`       | The checklists the organisation wrote for its types of structure.                                             |
+| `apply_template`       | Open a template's questions in a dossier and file the clauses that resolve in the corpus.                     |
+| `draft_deliverable`    | Open the document a dossier produces (project basis, use agreement, report) and get its plan and sources.     |
+| `write_section`        | Write one section of a deliverable with what it rests on; a section without a source is refused.              |
+| `list_skills`          | The procedures the agent follows for a repeatable task: the ones Stratta ships and the ones the office wrote. |
+| `get_skill`            | Read one procedure in full; the office version wins over the Stratta one of the same name.                    |
+| `list_questions`       | The questions of a dossier, paginated, with status, assignee, due date, options and decision title.           |
+| `get_question`         | One question in full: options, decision, evidence with every citation field, comments with authors.           |
+| `get_dossier_activity` | The history of a dossier, most recent first, paginated: who did what, from the app or an agent.               |
+| `list_exports`         | The verification notes and journals exported from a dossier, with hash and trusted timestamp.                 |
+| `update_question`      | Reword a question, assign it by e-mail address, set or clear its due date.                                    |
+| `add_option`           | Add one way of settling a question. Idempotent on the name.                                                   |
+| `update_option`        | Rename or describe an option, or mark it retained (the others are released).                                  |
+| `delete_option`        | Remove an option; its evidence stays on the question. Asks the user first.                                    |
+| `delete_question`      | Delete a question opened by mistake; its evidence stays, unfiled. Asks the user first.                        |
+| `add_comment`          | Leave a signed remark on a dossier, a question or an entry.                                                   |
+| `update_entry`         | Correct an entry's wording, value, confidence or citation in place.                                           |
+| `attach_entry`         | File an entry under a question and optionally an option, or unfile it.                                        |
 
 A dossier is read, annotated, reviewed and exported from
 [stratta.ch/dossiers](https://stratta.ch/dossiers).

package/dist/confirm.js

@@ -1,4 +1,5 @@
 const decisionSummary = (args) => [
+    args.question ? `${String(args.question)}:` : null,
     args.title,
     args.value ? `= ${String(args.value)}` : null,
     args.retainedOption ? `(option ${String(args.retainedOption)})` : null,
@@ -32,7 +33,7 @@ export const CONFIRMED_TOOLS = {
         summary: () => 'remove this option; the evidence filed under it stays on the question',
         prompt: 'Remove it?',
     },
-    // The third deletion, gated since 0.15.0 on both transports: it is the one
+    // The third deletion, gated since 1.15.0 on both transports: it is the one
     // that empties a corpus rather than a dossier.
     ingest_delete: {
         what: 'Document',

package/dist/index.js

@@ -12,6 +12,7 @@ import { confirmWithUser } from './confirm.js';
 import { readTools } from './tools/read.js';
 import { ingestTools } from './tools/ingest.js';
 import { dossierTools } from './tools/dossier.js';
+import { libraryTools } from './tools/library.js';
 import { siteTools } from './tools/site.js';
 import { SESSION_ID, usageDigest } from './usage.js';
 import { SERVER_INSTRUCTIONS } from './tools/catalog.gen.js';
@@ -107,6 +108,7 @@ for (const def of [
     ...readTools,
     ...siteTools,
     ...dossierTools,
+    ...libraryTools,
     ...ingestTools,
 ]) {
     server.registerTool(def.name, {

package/dist/tools/catalog.gen.js

@@ -471,7 +471,7 @@ export const CATALOG = [
     {
         "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. Name the retained option when the question listed some; put the number in value and set confidence when the decision is a value. Only after the user confirmed the decision, never on your own reasoning. The question leaves the open items and keeps its evidence. Returns entryId.",
+        "description": "Record what the engineer retained: the decision in one line, why, and the clause it rests on. Pass questionId when the question already exists; otherwise pass dossierId and question (what is settled, in one line) and the question is opened on the spot, already decided. Name the retained option when the question listed some; put the number in value and set confidence when the decision is a value. Only after the user confirmed the decision, never on your own reasoning. Returns entryId.",
         "annotations": {
             "readOnlyHint": false,
             "destructiveHint": false,
@@ -483,7 +483,9 @@ export const CATALOG = [
             "remote"
         ],
         "params": {
-            "questionId": "Question id returned by open_question or load_dossier.",
+            "questionId": "Question id returned by open_question or load_dossier, when the question exists.",
+            "dossierId": "Without questionId: the dossier the decision belongs to (open_dossier, load_dossier).",
+            "question": "Without questionId: what is settled, in one line (\"Friction angle of the moraine\"). The same words find the question already opened.",
             "retainedOption": "The option that was retained, by the name it was given. An option not listed yet is created.",
             "title": "The decision in one line, as it would be written in a report.",
             "detail": "Why, in one or two sentences, and what it rests on.",
@@ -647,6 +649,82 @@ export const CATALOG = [
             "templateId": "The template, from list_templates."
         }
     },
+    {
+        "name": "draft_deliverable",
+        "title": "Open a deliverable",
+        "description": "Open the document a dossier produces (project basis, use agreement, geotechnical report, verification note) and get its plan: one section per chapter, each with a path, a title, a hint of what belongs there, its state (gap, current, stale: a source moved, the reason says which) and an excerpt of what is already written. The plan is the office template of that kind when the organization validated one, otherwise the plan Stratta proposes. Also returns the decisions of the dossier with their ids, so write_section can cite them, and the site id when there is one. Calling it again on the same dossier and kind returns the same document, never a second one. Then read the skill of that kind (get_skill) and fill the sections with write_section.",
+        "annotations": {
+            "readOnlyHint": false,
+            "destructiveHint": false,
+            "idempotentHint": true,
+            "openWorldHint": false
+        },
+        "transports": [
+            "stdio",
+            "remote"
+        ],
+        "params": {
+            "dossierId": "The dossier the document belongs to (open_dossier, load_dossier).",
+            "kind": "project_basis, use_agreement, geotechnical_report, verification_note or other.",
+            "title": "The document title, when the user named it. Default: the kind and the dossier name."
+        }
+    },
+    {
+        "name": "write_section",
+        "title": "Write a section",
+        "description": "Write one section of a deliverable: the text as it would be printed, and what it rests on. Every sentence of substance must come from a source the section lists: a decision or piece of evidence of the dossier (kind entry, ref the entry id), a fact of the site (kind fact, ref the fact key such as groundwater.level), a clause read in a norm (kind clause, ref the norm code and the section path as in \"SIA 267 s. 9.5.2\"), a page of an attachment (kind attachment, ref the id with #p12), or a reading recorded by the dossier (kind reading, ref the reading id). A section without a source is refused; when the dossier has nothing for it, pass gap true with a body that says what is missing, and the section is printed as something to establish. Replaces what the section held. Never invent a value: a section written from memory is worse than a gap.",
+        "annotations": {
+            "readOnlyHint": false,
+            "destructiveHint": false,
+            "idempotentHint": true,
+            "openWorldHint": false
+        },
+        "transports": [
+            "stdio",
+            "remote"
+        ],
+        "params": {
+            "deliverableId": "The deliverable id from draft_deliverable.",
+            "path": "The section path from the plan, e.g. \"2\" or \"3.1\".",
+            "body": "The text of the section, plain prose or Markdown, up to 12000 characters.",
+            "sources": "What the text rests on: a list of {kind, ref, label?}. At least one unless gap is true.",
+            "gap": "true when the dossier holds nothing for this section; the body then says what is missing."
+        }
+    },
+    {
+        "name": "list_skills",
+        "title": "Skills of this workspace",
+        "description": "List the procedures an agent follows for a repeatable task: drafting the project basis or the use agreement, writing the terrain chapter of a report, instructing a type of structure, preparing a review, the verification note. Two sources: the skills Stratta ships and the ones this organization wrote; an organization skill with the same name replaces the Stratta one. Call it before drafting a document or starting such a task, then get_skill on the one that fits.",
+        "annotations": {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": true,
+            "openWorldHint": false
+        },
+        "transports": [
+            "stdio",
+            "remote"
+        ],
+        "params": {}
+    },
+    {
+        "name": "get_skill",
+        "title": "Read a skill",
+        "description": "Read one skill in full: Markdown with its front matter (name, description) and its steps, rules and output shape. Follow it for the task at hand. The organization version wins over the Stratta version of the same name, because it carries the office plan and wording. Returns null when no skill has that name.",
+        "annotations": {
+            "readOnlyHint": true,
+            "destructiveHint": false,
+            "idempotentHint": true,
+            "openWorldHint": false
+        },
+        "transports": [
+            "stdio",
+            "remote"
+        ],
+        "params": {
+            "name": "The skill name from list_skills, e.g. \"project-basis\"."
+        }
+    },
     {
         "name": "list_questions",
         "title": "Questions of a dossier",

package/dist/tools/dossier.d.ts

@@ -47,7 +47,9 @@ export declare const recordDecision: import("./define.js").ToolDef<{
     sectionPath: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
     normEdition: z.ZodOptional<z.ZodString>;
-    questionId: z.ZodString;
+    questionId: z.ZodOptional<z.ZodString>;
+    dossierId: z.ZodOptional<z.ZodString>;
+    question: z.ZodOptional<z.ZodString>;
     retainedOption: z.ZodOptional<z.ZodString>;
 }>;
 export declare const loadDossier: import("./define.js").ToolDef<{
@@ -59,6 +61,34 @@ export declare const resolveQuestion: import("./define.js").ToolDef<{
     resolved: z.ZodOptional<z.ZodBoolean>;
     confirmed: z.ZodOptional<z.ZodBoolean>;
 }>;
+export declare const draftDeliverable: import("./define.js").ToolDef<{
+    dossierId: z.ZodString;
+    kind: z.ZodEnum<{
+        project_basis: "project_basis";
+        use_agreement: "use_agreement";
+        geotechnical_report: "geotechnical_report";
+        verification_note: "verification_note";
+        other: "other";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+}>;
+export declare const writeSection: import("./define.js").ToolDef<{
+    deliverableId: z.ZodString;
+    path: z.ZodString;
+    body: z.ZodString;
+    sources: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            entry: "entry";
+            fact: "fact";
+            clause: "clause";
+            attachment: "attachment";
+            reading: "reading";
+        }>;
+        ref: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    gap: z.ZodOptional<z.ZodBoolean>;
+}>;
 export declare const listAttachments: import("./define.js").ToolDef<{
     dossierId: z.ZodString;
 }>;
@@ -201,7 +231,9 @@ export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("
     sectionPath: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
     normEdition: z.ZodOptional<z.ZodString>;
-    questionId: z.ZodString;
+    questionId: z.ZodOptional<z.ZodString>;
+    dossierId: z.ZodOptional<z.ZodString>;
+    question: z.ZodOptional<z.ZodString>;
     retainedOption: z.ZodOptional<z.ZodString>;
 }> | import("./define.js").ToolDef<{
     dossierId: z.ZodOptional<z.ZodString>;
@@ -210,6 +242,32 @@ export declare const dossierTools: (import("./define.js").ToolDef<{}> | import("
     questionId: z.ZodString;
     resolved: z.ZodOptional<z.ZodBoolean>;
     confirmed: z.ZodOptional<z.ZodBoolean>;
+}> | import("./define.js").ToolDef<{
+    dossierId: z.ZodString;
+    kind: z.ZodEnum<{
+        project_basis: "project_basis";
+        use_agreement: "use_agreement";
+        geotechnical_report: "geotechnical_report";
+        verification_note: "verification_note";
+        other: "other";
+    }>;
+    title: z.ZodOptional<z.ZodString>;
+}> | import("./define.js").ToolDef<{
+    deliverableId: z.ZodString;
+    path: z.ZodString;
+    body: z.ZodString;
+    sources: z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            entry: "entry";
+            fact: "fact";
+            clause: "clause";
+            attachment: "attachment";
+            reading: "reading";
+        }>;
+        ref: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    gap: z.ZodOptional<z.ZodBoolean>;
 }> | import("./define.js").ToolDef<{
     dossierId: z.ZodString;
 }> | import("./define.js").ToolDef<{

package/dist/tools/dossier.js

@@ -127,7 +127,16 @@ export const saveFinding = defineTool({
 export const recordDecision = defineTool({
     ...headOf('record_decision'),
     inputSchema: {
-        questionId: questionId('record_decision'),
+        // Either the question, or the dossier and what is settled: since 1.16.0
+        // a decision no longer needs a question opened beforehand.
+        questionId: questionId('record_decision').optional(),
+        dossierId: dossierId('record_decision').optional(),
+        question: z
+            .string()
+            .min(3)
+            .max(200)
+            .optional()
+            .describe(param('record_decision', 'question')),
         retainedOption: z
             .string()
             .max(120)
@@ -188,6 +197,55 @@ export const resolveQuestion = defineTool({
         return { ok: true };
     },
 });
+/* ------------------------------------------------------------ deliverables */
+const deliverableKind = z.enum([
+    'project_basis',
+    'use_agreement',
+    'geotechnical_report',
+    'verification_note',
+    'other',
+]);
+const sourceSchema = z.object({
+    kind: z.enum(['entry', 'fact', 'clause', 'attachment', 'reading']),
+    ref: z.string().min(1).max(120),
+    label: z.string().max(120).optional(),
+});
+export const draftDeliverable = defineTool({
+    ...headOf('draft_deliverable'),
+    inputSchema: {
+        dossierId: dossierId('draft_deliverable'),
+        kind: deliverableKind.describe(param('draft_deliverable', 'kind')),
+        title: z
+            .string()
+            .max(160)
+            .optional()
+            .describe(param('draft_deliverable', 'title')),
+    },
+    run: (client, args) => client.action(api.dossiersApi.draftDeliverable, {
+        apiKey: requireApiKey(),
+        ...args,
+    }),
+});
+export const writeSection = defineTool({
+    ...headOf('write_section'),
+    inputSchema: {
+        deliverableId: z
+            .string()
+            .min(1)
+            .describe(param('write_section', 'deliverableId')),
+        path: z.string().min(1).max(20).describe(param('write_section', 'path')),
+        body: z.string().max(12_000).describe(param('write_section', 'body')),
+        sources: z
+            .array(sourceSchema)
+            .max(30)
+            .describe(param('write_section', 'sources')),
+        gap: z.boolean().optional().describe(param('write_section', 'gap')),
+    },
+    run: (client, args) => client.action(api.dossiersApi.writeSection, {
+        apiKey: requireApiKey(),
+        ...args,
+    }),
+});
 const MIME_BY_EXT = {
     '.pdf': 'application/pdf',
     '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
@@ -642,6 +700,8 @@ export const dossierTools = [
     addAttachment,
     listTemplates,
     applyTemplate,
+    draftDeliverable,
+    writeSection,
     listQuestions,
     getQuestion,
     getDossierActivity,

package/dist/tools/library.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export declare const listSkills: import("./define.js").ToolDef<{}>;
+export declare const getSkill: import("./define.js").ToolDef<{
+    name: z.ZodString;
+}>;
+export declare const libraryTools: (import("./define.js").ToolDef<{}> | import("./define.js").ToolDef<{
+    name: z.ZodString;
+}>)[];

package/dist/tools/library.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { api } from '../client.js';
+import { requireApiKey } from '../auth.js';
+import { catalogEntry, param } from './catalog.gen.js';
+import { defineTool } from './define.js';
+/**
+ * The library: the procedures the agent follows for a repeatable task, the
+ * ones Stratta ships and the ones the office wrote (ADR 48). Served as tools
+ * so that every client reads them, whether or not it supports resources or
+ * installed the skills folder of this package.
+ */
+const headOf = (name) => {
+    const entry = catalogEntry(name);
+    return {
+        name,
+        title: entry.title,
+        description: entry.description,
+        annotations: entry.annotations,
+    };
+};
+export const listSkills = defineTool({
+    ...headOf('list_skills'),
+    inputSchema: {},
+    run: async (client) => ({
+        skills: await client.action(api.libraryApi.listSkills, {
+            apiKey: requireApiKey(),
+        }),
+    }),
+});
+export const getSkill = defineTool({
+    ...headOf('get_skill'),
+    inputSchema: {
+        name: z.string().min(1).max(64).describe(param('get_skill', 'name')),
+    },
+    run: (client, args) => client.action(api.libraryApi.getSkill, {
+        apiKey: requireApiKey(),
+        name: args.name,
+    }),
+});
+export const libraryTools = [listSkills, getSkill];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stratta/mcp",
   "mcpName": "ch.stratta/mcp",
-  "version": "0.15.0",
+  "version": "1.16.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/skills/consult-stratta/SKILL.md

@@ -42,25 +42,23 @@ DEMO 001 is a fictional document shipped with Stratta so that navigation and cit
 
 ## Dossier
 
-A conversation disappears, a project lasts months. The dossier is what remains: what was retained, what it rests on, and what is still open. It is the trail an engineer hands to a reviewer or an insurer.
+A conversation disappears, a project lasts months. The dossier is what remains: what was read, what was retained, and what is still open. Keeping it costs the user nothing: every section you read is filed under the project by itself, and one call records a decision.
 
-**Open one** (`open_dossier`) when the user names a project, a structure, a site or a mandate, when a value is retained for a design rather than looked up, when a hypothesis is set, when a site observation is reported, or when a question is left open. Do not open a dossier for a one-off lookup with no project behind it.
+**Name the project once.** When the user names a project, a structure, a site or a mandate, call `list_dossiers` then `load_dossier` (or `open_dossier` for a new one) BEFORE answering. It reloads what was already decided so it is not decided twice, and from then on each `get_section` you make is journaled under that dossier without any further call. Do not open a dossier for a one-off lookup with no project behind it.
 
-**Reload it first** (`list_dossiers`, `load_dossier`) BEFORE answering, as soon as the user returns to a project already named ("pick up dossier X", "where were we on Y"): reloading is what stops a decision already taken from being taken again. Read its entries and its open questions before answering anything about that project. To work on one question, `get_question` reads it in full (options, evidence with every citation field, comments); `attach_entry` files what `load_dossier` lists as unclassified. A question is edited with `update_question`, never deleted unless the user says so.
+**Record what is retained** (`record_decision`) as soon as the user fixes a value or a choice for the design ("we take 30 degrees", "keep pile P38"): the decision in one line, why, the clause it rests on (`normCode`, `sectionPath`, `page`, `normEdition` from the header of the section read), the number in `value` with its unit and `confidence` (established, judgement or to_confirm; in geotechnics a retained value is a judgement). Pass `dossierId` and `question` (what is settled, in one line): the question is opened already decided. Pass `questionId` instead when the question exists. ONLY after the user confirmed it, never on your own reasoning.
+
+**Open a question** (`open_question`) only when something is left to settle later, or when the user weighs several options and wants them on the table. File what backs it with `save_finding` (one clause, one value or one fact per call, under its `questionId`): reference, hypothesis or observation. `get_question` reads one in full; `update_question` edits it; never delete one unless the user says so.
 
 **Read its attachments.** A dossier carries the project's own documents (site reports, borehole logs, meeting minutes): `list_attachments`, then `read_attachment` on what bears on the question, or `search_in_dossier` when the dossier holds many. A fact from a piece is evidence like a clause: cite it as [name, p. N] and file it with `attachmentId` and `attachmentPage`.
 
-**Start from a template when one fits.** The office may have written checklists for its types of structure (`list_templates`); on a new project that matches one, `apply_template` opens the questions with the clauses they rest on, and says which clauses the corpus lacks.
+**Start from a template when one fits** (`list_templates`, `apply_template`): the office's checklist for a type of structure opens the questions with the clauses they rest on, and says which clauses the corpus lacks.
 
-**Shape.** A dossier is a set of questions, each with its evidence, its options and eventually its decision. The question is the unit of work ("can pile P38 be kept?", "which friction angle do we retain?"). Open one with `open_question` BEFORE gathering evidence for it, one question per thing to settle, and name the options on the table when there are several.
+**What not to write:** your own prose, the intermediate steps, anything the user did not treat as a decision. The dossier documents the engineer's reasoning; it does not replace it: never conclude that a structure complies, never write a decision the user has not confirmed.
 
-**What to write** (`save_finding`, one clause, one value or one fact per call, in one or two sentences, filed under its question with `questionId`):
-- reference: what the norm says, with `normCode`, `sectionPath`, `page`, and `normEdition` taken from the header of the section read;
-- hypothesis: the retained value AND the reasoning; in geotechnics a retained value is a judgement, not the output of a calculation;
-- observation: what the site showed, with the date when known;
-- decision (`record_decision`): what was decided, why, the clause it rests on and the retained option, ONLY after the user confirmed it.
+## Skills
 
-**What not to write:** your own prose, the intermediate steps, anything the user did not treat as a decision. Set `confidence` whenever a value is at stake: established, judgement or to_confirm. The dossier documents the engineer's reasoning; it does not replace it: never conclude that a structure complies, never write a hypothesis the user has not confirmed.
+Before drafting a document (project basis, use agreement, terrain chapter, verification note) or starting a repeatable task (instructing a type of structure, preparing a review), call `list_skills` then `get_skill` on the one that fits, and follow it. The organization's own skill replaces Stratta's of the same name: it carries the office's plan and wording. When no skill fits, say so and proceed with the method above.
 
 ## Boundaries
 
@@ -70,4 +68,4 @@ A conversation disappears, a project lasts months. The dossier is what remains:
 - Do not expose internal identifiers unless the next Stratta tool call requires them.
 - Ingesting a new norm starts from a PDF on the user's own machine: it goes through the local `@stratta/mcp` server and its `ingest-norm` skill, never through the remote connector.
 
-methodology: v2
+methodology: v3

package/skills/handoff-to-word/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: handoff-to-word
+description: Hand a document drafted in the conversation to the office's Word template: clean Markdown with a stable heading plan, tables, citations and visible gaps, plus the two lines the person needs to paste it. Use only for a text that was not written with draft_deliverable, which the dossier page exports to Word itself. Trigger phrases: "mets-le en forme pour Word", "prepare pour le gabarit", "export pour Word", "paste into Word".
+---
+
+# Handoff to Word
+
+Use this skill when a document was drafted in the conversation (a terrain chapter, a
+note) and the office wants it in its own Word template. A document written with
+`draft_deliverable` and `write_section` does not need it: the dossier page exports it to
+Word under Livrables, headings and sources included; tell the user so.
+
+Do not use it to write the document: it formats one that exists.
+
+## What to produce
+
+1. The document as Markdown with a stable plan: `#` for the title, `##` for chapters
+   numbered as the office numbers them, `###` at most. No deeper level: Word templates
+   rarely style a fourth.
+2. Tables as Markdown tables with a header row; one table per subject, no merged cells.
+3. Provenance marks kept exactly as the source skill wrote them: `(#xxxxxx)` for dossier
+   entries, `[CODE section, p. N]` for clauses, `(fait: topic.key)` for site facts. They
+   are what the reviewer checks; a Word document without them is prose.
+4. Gaps kept as `[A etablir : ...]`, `[A confirmer : ...]` or `[A convenir : ...]`, on
+   their own line when they replace a paragraph, so they show up in a search.
+5. A final section **Sources** listing every clause cited with its edition and every
+   attachment cited with its page.
+
+## Then tell the user, in two lines
+
+- How to paste: in Word, paste as text, then apply the template's heading styles to the
+  `#` levels (or use the office's Markdown import when it has one).
+- That the dossier page produces the verification note as a PDF, hashed and
+  timestamped, and that the two documents should agree.
+
+## Rules
+
+- Change nothing in the content: no rewording, no reordering, no gap filled.
+- Keep the closing sentence of the source document ("Document prepare par un agent...").
+- The office may have its own `handoff-to-word` skill (`list_skills`), for instance
+  with its heading numbering or its table style: it replaces this one.

package/skills/instruct-structure/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: instruct-structure
+description: Instruct a type of structure in a Stratta dossier (a bored pile, a retaining wall, a slope, a raft) by opening the questions it raises from the office's template or from the norm's own chapters, then gathering the clauses each one rests on, stopping short of any decision. Trigger phrases: "instruis", "prepare les questions pour", "checklist pour", "instruct the pile", "what do we need to settle for".
+---
+
+# Instruct a type of structure
+
+Use this skill when the user starts on a type of structure and wants the questions it
+raises laid out with the clauses that govern them, before deciding anything: "instruis
+le pieu P38", "qu'est-ce qu'on doit trancher pour ce mur de soutenement".
+
+Do not use it to answer one technical question (that is the ordinary method) and do not
+record decisions with it: it prepares the work, the engineer decides.
+
+## Steps
+
+1. `list_dossiers` then `load_dossier` (or `open_dossier` when the project is new). If
+   questions already cover the structure, do not open them twice: list what exists first.
+2. `list_templates`. When a template matches the type of structure, `apply_template`: it
+   opens the questions with the clauses they rest on and says which clauses the corpus
+   lacks. Report both to the user and stop here unless the user asks for more.
+3. Without a template: `get_toc` on the norm that governs the structure (SIA 267 for
+   geotechnics, SIA 262 for concrete, and so on, only if `list_norms` holds it), then
+   `get_subtree` on the chapter of the structure. Propose the questions, one per thing to
+   settle, in the user's words ("Quel angle de frottement retenir pour la moraine ?",
+   "Le pieu peut-il etre conserve ?"), and open them with `open_question` after the user
+   agreed on the list. Name the options when the chapter offers several methods.
+4. For each question, read the clauses that govern it (`get_section`, follow resolvable
+   references) and file each as a `reference` with `save_finding`: the clause, its page,
+   its edition, one clause per call.
+5. Summarise: the questions opened, the clauses filed, what the corpus does not hold, and
+   which question the user wants to work on first.
+
+## Rules
+
+- Open questions only with the user's agreement on the list; ten precise questions beat
+  one that bundles them.
+- File clauses you read in this conversation, never from memory.
+- Do not write a hypothesis, an observation or a decision here. The office may have its
+  own `instruct-structure` skill (`list_skills`): it replaces this one.
+
+## Example
+
+User: "instruis le mur de soutenement de la villa Morges". Agent: loads the dossier, finds
+no template, reads the SIA 267 chapter on retaining structures, proposes six questions
+(earth pressure model, drainage, bearing capacity of the base, sliding, overturning,
+serviceability), opens them once the user agrees, files nine clauses, and reports that
+the corpus does not hold the SIA 261 clause on traffic loads behind the wall.

package/skills/project-basis/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: project-basis
+description: Draft the project basis (base du projet, Projektbasis) required by SIA 260 clause 2.5 from a Stratta dossier and its site sheet, chapter by chapter, every statement traced to a decision, a site fact or a clause, every gap written as a gap. Trigger phrases: "redige la base du projet", "base du projet", "Projektbasis", "project basis".
+---
+
+# Project basis (SIA 260 clause 2.5)
+
+Use this skill when the user asks for the project basis of a structure, in any of its
+names: base du projet, Projektbasis, project basis. The document states the conditions the
+design rests on: the site, the actions, the retained values and the norms. Stratta holds
+most of that matter already; the skill assembles it and shows what is missing.
+
+Do not use it for the use agreement (convention d'utilisation, clause 2.2): that is the
+`use-agreement` skill. Do not use it to decide anything: a gap stays a gap.
+
+## Before writing
+
+1. `list_skills`: if the office wrote its own `project-basis`, that version replaces this
+   one entirely. Read it with `get_skill` and follow it.
+2. `list_dossiers` then `load_dossier` on the project. Read its decisions and its open
+   questions; `get_question` on any decision whose clause you need in full.
+3. `get_site_context` on the dossier's site when it has one (`siteId` in `load_dossier`),
+   then `get_boreholes` when the terrain chapter needs them.
+4. `get_toc("SIA 260", maxDepth: 2)` and read the clause on the project basis with
+   `get_section` when the corpus holds SIA 260. If it does not, say so once at the top of
+   the document and keep the chapter plan below.
+
+## How to write it
+
+The document lives in Stratta, not in the conversation:
+
+1. `draft_deliverable` with the dossier id and `kind: "project_basis"`. It returns the
+   plan (the office template when one was validated, otherwise the plan below), the
+   decisions of the dossier with their entry ids, the open questions and the site id.
+   Calling it twice returns the same document.
+2. For each section of the plan, `write_section` with the text and its sources. Every
+   sentence of substance rests on one of:
+   - a decision or piece of evidence: `{kind: "entry", ref: "<entryId>"}`;
+   - a site fact: `{kind: "fact", ref: "groundwater.level"}`;
+   - a clause you read in this conversation: `{kind: "clause", ref: "SIA 261 s. 16.2.1"}`;
+   - a page of an attachment: `{kind: "attachment", ref: "<id>#p12"}`.
+     A section with no source is refused. When the dossier holds nothing for a section,
+     call `write_section` with `gap: true` and a body that says what is missing and who
+     can supply it.
+3. Tell the user the document is on the dossier page, under Livrables, where they read
+   it section by section, correct, and export it to Word. Do not paste the whole
+   document in the conversation; summarise what was written and list the gaps.
+
+## The plan
+
+Unless the office's own skill says otherwise:
+
+1. **Objet et situation**: the structure, the address, the parcel, the mandate.
+2. **Terrain de fondation**: one paragraph per site topic (geology, groundwater, hazards,
+   contamination, protection sectors, boreholes), built with the `site-chapter` skill's
+   rules: an `established` fact is a statement with its source and date; an `indicative`
+   fact is written as `[A confirmer : ...]`; an `uncovered` topic is `[A etablir : ...]`.
+3. **Actions**: seismic zone and ground class, snow, wind, from the site facts that carry
+   a SIA 261 clause; each value with its clause and page.
+4. **Hypotheses et valeurs retenues**: one line per decision of the dossier: the value,
+   its confidence (established, judgement, to confirm), the clause it rests on.
+5. **Bases normatives**: the norms and editions cited in the dossier, one line each.
+6. **Points ouverts**: the open questions, with their due date and assignee when set.
+
+The text of a section is plain prose: the sources go in the `sources` argument, not in
+the text. Stratta prints them under each section.
+
+## Rules
+
+- Write nothing the dossier, the site sheet or a clause you read does not carry. A
+  plausible sentence with no source is the one mistake this document cannot afford.
+- A value retained by judgement stays a judgement in the text; do not upgrade it.
+- A site fact is a register's answer, not a design value: it goes in chapter 2 or 3 with
+  its source, and the retained value goes in chapter 4 only if the dossier decided it.
+- Do not conclude that the structure complies, and do not write a decision the user has
+  not confirmed.
+- Stratta prints the closing sentence ("Document prepare par un agent...") and the
+  signature belongs to the engineer, on the dossier page. Do not sign anything.
+
+## After drafting
+
+List the gaps in one short table (chapter, what is missing, which tool or which person can
+fill it), and ask which one to settle first. A gap settled later is written with
+`write_section` on the same path; the document keeps its version history.
+
+When the user comes back and `draft_deliverable` returns sections in state `stale`, start
+with those: `staleReason` says which source moved (a decision retaken, a fact changed by a
+rescan, a clause changed by a new edition). Reread the source, rewrite the section or tell
+the user it still holds.

package/skills/review-open-questions/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: review-open-questions
+description: Prepare the review of a Stratta dossier for the senior engineer: what is decided and on what, what is still open with its due date, which values are marked to confirm, in one brief that proposes nothing new. Trigger phrases: "prepare la revue", "ou en est le dossier", "qu'est-ce qui reste a trancher", "brief pour le chef de projet", "review the dossier".
+---
+
+# Review of the open questions
+
+Use this skill when someone is about to review a dossier: the project lead before a
+meeting, the senior engineer before signing, the colleague who picks the project up.
+The brief tells them what was retained, on what it rests, and what is still open, in
+the order they need to read it.
+
+Do not use it to decide, to propose values or to reopen questions: a review reads first.
+
+## Steps
+
+1. `list_dossiers` then `load_dossier`; `list_questions` with `status: "open"` when the
+   dossier is large; `get_question` on each open question that has evidence, to read
+   its options and what backs them.
+2. `get_dossier_activity` for what changed since the last review, when the user names a
+   date or the dossier has been worked on by several people.
+3. Write the brief.
+
+## What to produce
+
+Markdown, in the user's language, four parts, short:
+
+1. **Etat**: the dossier name, its status, the counts (open, decided, closed), the site
+   when there is one.
+2. **A trancher**: one line per open question, ordered by due date then by how much
+   backs it: the question, its assignee, its due date, the options on the table, what is
+   filed (n references, n hypotheses, n observations), and what is missing to settle
+   it. A question with no evidence is marked as such.
+3. **Retenu**: one line per decision: what was decided, the value with its confidence,
+   the clause it rests on `[CODE section, p. N]`, who confirmed it and when. Values marked
+   `to_confirm` are listed apart, with what would confirm them.
+4. **Depuis la derniere revue**: the changes, when step 2 was run.
+
+Every line ends with `(#xxxxxx)` when it rests on an entry.
+
+## Rules
+
+- Read, do not judge: no opinion on a decision, no new option, no value proposed.
+- A gap is named as a gap; the reviewer's job is to see them, not to be spared them.
+- The office may have its own `review-open-questions` skill (`list_skills`): it replaces
+  this one.
+
+## After the brief
+
+Ask which open question to work on first, and only then switch to the ordinary method.

package/skills/site-chapter/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: site-chapter
+description: Write the terrain chapter of a report (situation, geology, groundwater, boreholes, hazards, constraints) from a Stratta site sheet, one sentence per fact with its source and date, register answers kept apart from design values. Trigger phrases: "chapitre terrain", "chapitre situation", "decris le site", "site chapter", "conditions du terrain".
+---
+
+# Terrain chapter
+
+Use this skill when the user needs the part of a report that describes the site: the
+geotechnical report's situation chapter, the terrain chapter of a project basis, the
+site paragraph of an offer. The site sheet already holds what the public registers say,
+with a source and a date on each fact; the chapter is that sheet, written in prose,
+without adding a single value.
+
+Do not use it to interpret the ground (a retained soil parameter is a decision of the
+dossier, not a fact of the sheet), and do not use it when the dossier has no site: say
+so and offer `scan_site`.
+
+## Before writing
+
+1. `list_skills`: an office version named `site-chapter` replaces this one.
+2. `load_dossier`, then `get_site_context` on its `siteId`. When the chapter needs the
+   boreholes, `get_boreholes` (nearest first; `withStrataOnly` when only logged strata
+   matter).
+
+## What to produce
+
+Markdown, in the user's language, ordered as the sheet is: situation (address, parcel,
+elevation), geology, boreholes and groundwater, natural hazards, contamination and water
+protection, other constraints (noise, radon, zoning, forest), actions (seismic zone and
+ground class, snow, wind).
+
+One sentence per fact, then its provenance in brackets: the register that answered, the
+date of the answer, and the clause when the fact carries one:
+
+- `established`: state it. "La parcelle repose sur des alluvions recentes (cadastre
+  geologique VD, 2026-09-14)."
+- `indicative`: state it with the reserve the register itself puts on it, and mark
+  `[A confirmer]`. "La classe de sol de fondation indiquee par la carte est C, carte non
+  precise a l'echelle de la parcelle (SIA 261 §16.2, p. 51) [A confirmer par sondage]."
+- `uncovered`: say the register did not answer, in one line, marked `[A etablir]`.
+
+For boreholes: their number in the radius, the nearest with its distance and depth, how
+many have logged strata, the measured water levels with their dates. No interpolation
+between boreholes: the sheet's cross-section is an interpretation and says so.
+
+## Rules
+
+- A fact of the sheet is a register's answer. It never becomes a design value in this
+  chapter; if the dossier retained one, cite the decision `(#xxxxxx)` in a separate
+  sentence.
+- Keep the date. A fact without its date reads as permanent, and a cadastre changes.
+- Do not complete a missing topic from general knowledge of the region.
+- Do not conclude on the feasibility of the structure.
+
+## After drafting
+
+Name the `[A etablir]` and `[A confirmer]` items in one list, with what would settle each
+(a borehole, a cantonal request, a site visit).

package/skills/use-agreement/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: use-agreement
+description: Draft the use agreement (convention d'utilisation, Nutzungsvereinbarung) required by SIA 260 clause 2.2 from a Stratta dossier, as a document the owner and the engineer sign together, every requirement traced to a decision and every open point left visible. Trigger phrases: "convention d'utilisation", "Nutzungsvereinbarung", "use agreement".
+---
+
+# Use agreement (SIA 260 clause 2.2)
+
+Use this skill when the user asks for the use agreement of a structure: the document in
+which the owner and the engineer agree on what the structure is for, how long, under
+which requirements and with which risks accepted. It is written in the owner's language,
+for the owner to read and sign; the engineer keeps the technical basis in the project
+basis (`project-basis` skill).
+
+Do not use it to draft the project basis, and do not fill a requirement the owner has
+not stated: an open point in this document is a question for the next meeting, not a
+default.
+
+## Before writing
+
+1. `list_skills`: an office version named `use-agreement` replaces this one; read it with
+   `get_skill` and follow it.
+2. `list_dossiers` then `load_dossier`. The decisions that concern use (service life,
+   categories of use, loads the owner asked for, tolerances, special risks) are the
+   matter; the open questions are the points to raise with the owner.
+3. `get_toc("SIA 260", maxDepth: 2)` and read the clause on the use agreement with
+   `get_section` when the corpus holds SIA 260; otherwise say so once and keep the plan.
+
+## How to write it
+
+The document lives in Stratta: `draft_deliverable` with the dossier id and
+`kind: "use_agreement"` returns the plan (the office template when one was validated)
+and the decisions with their ids; then one `write_section` per section, each with its
+sources (`{kind: "entry", ref: <entryId>}` for a decision, `{kind: "fact", ref: ...}`
+for a site fact). A requirement the owner has not stated is a `write_section` with
+`gap: true` and a body that names the point to agree. Tell the user the document is on
+the dossier page under Livrables; do not paste it in the conversation.
+
+## The plan
+
+In the user's language, unless the office's own skill says otherwise:
+
+1. **Objet**: the structure and the parties.
+2. **Objectifs d'utilisation**: what the structure is for, its service life category,
+   the uses foreseen.
+3. **Exigences d'utilisation**: the requirements the owner sets (loads, deformations,
+   vibrations, appearance, durability), each as one line.
+4. **Environnement et conditions**: what the site imposes, in plain words, from the site
+   sheet when there is one (`get_site_context`): hazards, groundwater, contamination.
+5. **Risques acceptes et mesures**: what the owner accepts and what is done about it.
+6. **Points a convenir**: everything above that the dossier does not settle, as a list
+   the two parties go through together.
+
+The text is plain prose; the sources go in the `sources` argument. A point to agree is
+a gap, printed as such.
+
+## Rules
+
+- Plain language: the owner is not an engineer. Keep clause references for the project
+  basis; here, name the norm once in a footnote.
+- No requirement invented to look complete. A short agreement with visible gaps is worth
+  more than a full one the owner did not agree to.
+- Do not conclude on compliance; do not write a decision the user has not confirmed.
+- The last section ends with the two signature lines (owner, engineer). Stratta prints
+  the closing sentence; the signature is the parties', on paper.
+
+## After drafting
+
+List the points to agree in one table and propose them as questions to open in the
+dossier (`open_question`), only if the user says so.