@stratta/mcp 0.1.0

package/skills/ingest-norm/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ingest-norm
+description: Use when the user wants to add an engineering norm (SIA, Eurocode, etc.) they are licensed for into THEIR Stratta workspace. Reads the PDF, builds a hierarchical tree, enriches sections (LaTeX formulas, tables, figures, cross-references), and writes everything to Stratta via the MCP `ingest_*` tools — scoped to the user's own organization. Trigger phrases: "ingère cette norme", "ingest SIA", "ajoute la norme X à Stratta".
+---
+
+# Ingest a norm into your Stratta workspace
+
+This skill turns a norm PDF **you are licensed to use** into a queryable TreeRAG
+inside **your own** Stratta workspace. Everything runs on your machine through
+the Stratta MCP server (authenticated by your `STRATTA_API_KEY`); the norm is
+stored privately and scoped to your organization — no one else can see it.
+
+> ⚠️ **Licence**: only ingest norms your organization holds a valid licence for.
+> You are responsible for your usage rights (see Stratta's Terms).
+
+## Prerequisites
+- The Stratta MCP server is installed and `STRATTA_API_KEY` is set.
+- The norm PDF is available locally.
+- (Optional, for figures) `poppler` tools (`pdftoppm`, `pdfimages`) to rasterize
+  pages/extract images.
+
+## Tools used (all scoped to your workspace)
+`ingest_status` · `ingest_create_document` · `ingest_create_sections` ·
+`ingest_attach_formula` · `ingest_attach_table` · `ingest_attach_cross_ref` ·
+`ingest_upload_figure` · `ingest_normalize_cross_refs` · `ingest_publish` ·
+`ingest_delete`.
+
+## Workflow
+
+### 1. Check for an existing copy
+Call `ingest_status { code }` (e.g. `"SIA 261"`). If it already exists and you
+want to re-ingest, call `ingest_delete { documentId }` first.
+
+### 2. Read the PDF and plan the tree
+Read the PDF natively. Build a PageIndex-style hierarchy: chapters (depth 0),
+sections (depth 1), sub-sections (depth 2+), plus annexes. For each node decide
+a stable `nodeId`, a human `path` (e.g. `"4.2.1"`, `"Annexe B.1"`), `title`,
+a 1-3 sentence `summary` (used for navigation), `pageStart`/`pageEnd`, and an
+`orderIndex`. **Never skip annexes** — they hold key numeric values.
+
+### 3. Create the document
+`ingest_create_document { code, year, title, language, totalPages }` →
+returns `documentId`. Keep it for all subsequent calls.
+
+### 4. Insert sections (in batches)
+`ingest_create_sections { documentId, sections: [...] }`. Each section carries
+`nodeId`, optional `parentNodeId` (must already exist in this or a prior batch),
+`path`, `title`, `summary`, `depth`, `content` (full enriched text, LaTeX inline
+OK), `rawContent`, `pageStart`, `pageEnd`, `orderIndex`. The call returns a
+`nodeId → sectionId` map — **use those sectionIds** to attach formulas, tables,
+figures and cross-refs. Batch large docs (e.g. 30-50 sections per call).
+
+### 5. Enrich sections
+- `ingest_attach_formula { sectionId, latex, description, formulaNumber }`
+- `ingest_attach_table { sectionId, data: { headers, rows }, caption, tableNumber }`
+- `ingest_attach_cross_ref { sourceSectionId, targetDocumentCode, targetSectionPath?, refText, refType }`
+
+### 6. Figures
+For each relevant figure: rasterize/extract the image, read its bytes, base64-encode,
+then `ingest_upload_figure { sectionId, base64, mimeType, caption, figureNumber }`
+(png/jpeg/webp, ≤ 8 MB). The tool stores the image and links it in one call.
+
+### 7. Auto cross-references (optional)
+`ingest_normalize_cross_refs { documentId }` scans every section's text for
+references to other norms (SIA / SN EN / EN / ISO / DIN …) and rebuilds the
+cross-ref index. Idempotent.
+
+### 8. Publish
+`ingest_publish { documentId }`. The norm is now queryable in your workspace via
+`list_norms`, `get_toc`, `get_section`, `search_in_norm`, `get_figure`, etc.
+
+## Quality bar
+- Citations depend on accurate `path` + `pageStart/pageEnd` — get them right.
+- Summaries drive navigation — make them specific (mention formulas/values when present).
+- Keep `content` faithful to the source; don't invent values.