@bicon/mcp-composer 0.1.7 → 0.3.2

package/README.md

@@ -24,10 +24,54 @@ via API keys is a separate, security-reviewed phase.
 | Name | What it does |
 |---|---|
 | resource `initiative://schema` / tool `get_initiative_schema` | The field catalog: required fields, enum values, the four dimensions with their named sub-dimensions (EN/DE labels + help text, plus the wording the app uses in digital / innovation portfolios), the exact shape of every optional section, the EU-AI-Act vocabularies, and the handoff steps. **Read this first.** |
-| `assemble_initiative` | Compact spec (metadata + named sub-ratings 0–100 + confidence per dimension + optional sections) → fully-formed initiative validated against the API contract (`CreateInitiativeBody` from `@workspace/api-zod`). Mints id/timestamps, **derives** the four dimension scores (the app's own scoring function), returns `{ok, initiative, derivedScores, warnings, errors}`. |
+| `assemble_initiative` | Compact spec (metadata + named sub-ratings 0–100 + confidence per dimension + optional sections, optionally the organisation's `context`) → fully-formed initiative validated against the API contract (`CreateInitiativeBody` from `@workspace/api-zod`). Mints the initiative id and every nested row id (decision-log entries, status reports, incidents — a client never invents ids), **derives** the four dimension scores (the app's own scoring function), accepts dates as dd/mm/yyyy, dd.mm.yyyy or yyyy-mm-dd, returns `{ok, initiative, derivedScores, warnings, errors, contextId}`. Pass `id` (an existing initiative's) only to **update** that initiative. |
 | `export_initiative_file` | Takes the **same compact spec**, assembles it and wraps the result in the app's single-initiative JSON envelope; returns `{ok, filename, json, importInstructions, derivedScores, warnings}`. There is one pipeline — a hand-edited initiative object is not an input, so client-supplied scores or unknown keys can never bypass assembly. |
+| `read_portfolio_context` | Takes the organisation's **portfolio-context file** (see below) and returns the interview plan for that organisation — its own labels, help texts and rating notes per sub-dimension, which sub-dimensions are switched off, its business units, categories, tags, skills (id + name) and non-archived initiatives (id + name), currency, discount rate, whether the EU-AI-Act module is on — plus a short **contextId** that stands in for the file in the two other tools. |
 | `composer_version` | Returns `{composerVersion, capabilities}`. Every *successful* tool result also carries `composerVersion`. |
 
+### The portfolio context — how the Composer learns an organisation's settings
+
+The Composer holds no credentials and calls no API, so on its own it cannot
+know how an organisation configured its portfolio. The app therefore exports
+a small **portfolio-context** JSON (Import/Export → the AI-assistant card →
+*Download portfolio context*): the active portfolio mode, which evaluation
+sliders are switched off, the organisation's own slider wording and rating
+notes, business units, categories, tags, the skill roster and the live
+initiatives (id + name), currency, discount rate and the AI-Act module switch.
+The user hands that file to the assistant at the start; the assistant calls
+`read_portfolio_context` once and then passes the returned **contextId**
+(`ctx_<16 hex>`, a content hash — or the whole file again) as `context` to
+`assemble_initiative` / `export_initiative_file`, so a 5–40 KB document is
+not re-emitted three times per initiative. The id resolves against a
+per-process content cache; an unknown id (server restarted) is a clear error
+naming the fix, never a wrong answer. Effects:
+
+- the interview uses the organisation's wording (org label › mode overlay ›
+  base) and skips switched-off sub-dimensions;
+- switched-off sub-dimensions are optional in the spec, stored as 0 (the app's
+  blank default — a value sent anyway is zeroed with a warning) and
+  **excluded from the dimension score** — the app's own derivation, so the
+  score does not change on the first save in Evaluate; a dimension with every
+  sub-dimension off needs only `{ confidence }`;
+- `businessUnit` and `aiCategory` **must be on the organisation's lists** (no
+  inventing — matched case-insensitively and normalised to the organisation's
+  spelling; new ones are created in the app's Settings); `dependsOn`,
+  `requiredSkills[].skillId` and an update `id` must be ids that exist (any
+  id format; Retired initiatives count, archived ones do not);
+- ratings must be on the organisation's **slider step** (Settings › Slider
+  granularity: 5, 10, 20 or 25) — the plan states it, a value off the grid is
+  rejected with the step in the message (files exported before 2026-08-21
+  carry no step and are not checked);
+- every EU-AI-Act field the app strips is warned about while the
+  organisation's AI-Act module is off; the export file defaults to the
+  context's mode and language; a file newer than the Composer knows is flagged.
+
+Without the file everything falls back to the built-in catalog: business unit
+and category are free text, dependency / update ids must at least be UUID-shaped
+(zod's rule, the same the API uses), and scores are derived over all 30
+sub-dimensions. Export the file again after changing settings — the plan
+reports its export date.
+
 ### How validation works (and why it lives at the wire)
 
 The MCP SDK validates every call with the registered schema **and hands the
@@ -35,9 +79,9 @@ handler the parsed value** — whatever the schema strips, the server never sees
 So the spec schema is registered as a full **strict** object, with every
 optional section a **deep-strict copy of the API contract**: an unknown key
 anywhere is rejected by the SDK with its exact path
-(`Unrecognized key(s) in object: 'literacy' at aiAct`), enum values, date
-formats (`YYYY-MM-DD`, real calendar dates), blank names and non-UUID ids are
-caught with field paths, and the advertised JSON Schema
+(`Unrecognized key(s) in object: 'literacy' at aiAct`), enum values, dates
+(dd/mm/yyyy, dd.mm.yyyy or yyyy-mm-dd — real calendar dates, normalised to
+yyyy-mm-dd) and blank names are caught with field paths, and the advertised JSON Schema
 (`additionalProperties: false`, no `$ref` pointers) means what it says. A
 section may also be sent as a **JSON string** (clients working from a stale
 tool descriptor did that); it is parsed and validated identically. What a JSON
@@ -45,7 +89,11 @@ Schema cannot express — the 30 named ratings, the AI-Act controlled
 vocabularies (`aiActVocabularies` in the descriptor; the app drops unknown
 obligation keys and never shows unknown artifact keys), the score derivation —
 is checked in the assembler, which reports **all** problems of a call at once
-with the allowed values in the message.
+with the allowed values in the message (id shapes included). Row ids of
+decision-log entries, status reports and incidents are minted by the
+Composer — a client-supplied UUID is kept, anything else replaced — because
+the app keys those rows per initiative and a re-used id from another
+initiative is exactly what collided on import once.
 
 Errors the SDK raises before a handler runs (`Input validation error: …`) carry
 no `composerVersion` — that is normal. A *successful* result without it means an
@@ -73,9 +121,9 @@ The Composer imports the app's own domain leaf, `@workspace/initiative-model`
 (types and value lists incl. the AI-Act vocabularies, the score derivation, the
 portfolio-mode wording overlays, the backup-format version) — the same package
 the web app renders and validates with — and derives its enum lists from the
-generated API contract. The only hand-listed part is the 30 sub-dimension keys
-with the app's base wording; `catalog-drift.test.ts` pins them to the
-contract in both directions. `server.test.ts` drives the real server through
+generated API contract. The 30 sub-dimension keys are the shared leaf's too;
+the only hand-listed part is their base wording, and `catalog-drift.test.ts`
+pins the keys to the contract in both directions. `server.test.ts` drives the real server through
 the real SDK client over an in-memory transport, so what is asserted is what a
 client sees.
 
@@ -144,7 +192,7 @@ For Claude Desktop, build and install the extension instead.
 from `package.json` — the checked-in `mcpb/manifest.json` carries
 placeholders), adds the single self-contained bundle, and — before zipping —
 boots the staged server and drives it through the protocol: `initialize`
-(version), `tools/list` (four tools, no `$ref`), `composer_version`,
+(version), `tools/list` (five tools, no `$ref`), `composer_version`,
 `resources/list`, and an `assemble_initiative` call with an unknown AI-Act key
 that must be rejected by name. It then copies the `.mcpb` to
 `artifacts/bicon-portfolio/public/downloads/` and writes
@@ -153,22 +201,29 @@ card imports. Requires `python3` for the zip container.
 
 ## Using it (the interview → import flow)
 
-1. Ask Claude: *"Help me set up a new initiative in BICon."* It reads
-   `initiative://schema` and interviews you — metadata first, then the 30
-   sub-dimensions with the app's own help text (ask which portfolio mode you
-   work in; digital and innovation portfolios use different wording for some
-   of them), then a confidence per dimension.
-2. Claude calls `assemble_initiative` and shows you the **derived scores** and
+1. (Recommended) In the app, Import/Export → *Download portfolio context*,
+   and give that file to Claude first — it then interviews with your
+   organisation's own wording, skips switched-off sliders and only accepts
+   your business units, categories, skills and initiatives.
+2. Ask Claude: *"Help me set up a new initiative in BICon."* It reads
+   `initiative://schema` (and your context) and interviews you — metadata
+   first, then the sub-dimensions with the app's help text, then a confidence
+   per dimension. Dates are dd/mm/yyyy in conversation.
+3. Claude calls `assemble_initiative` and shows you the **derived scores** and
    any warnings as a sanity check (fix and re-run if anything looks off).
-3. Claude calls `export_initiative_file` with the same spec → save the returned
-   JSON under the suggested filename (`initiative-<name>-<date>.json`).
-4. In the app (signed in to the target organisation): if the initiative carries
-   EU-AI-Act data, make sure the portfolio is in **AI mode** (the app strips
-   AI-Act fields on import when it is not — the file's `sourceMode` is
-   informational and cannot override that). Then **Import/Export → Single
-   initiative** card → drop the file → the preview should show **0 warnings**
-   → **Add as new** → **Confirm**.
-5. The initiative appears in the Inventory with exactly the scores Claude
+4. Claude calls `export_initiative_file` with the same spec → save the returned
+   JSON under the suggested filename (`initiative-<name>-<date>.json`). To
+   **update** an existing initiative, name it — Claude passes its id from the
+   context and the app offers "Update"; a re-export without the id is
+   recognised by name and offered as an update too.
+5. In the app (signed in to the target organisation): if the initiative carries
+   EU-AI-Act data, make sure the organisation's **EU-AI-Act module is switched
+   on** (Settings › AI Act — the app strips AI-Act fields on import while it is
+   off; the file's `sourceMode` is informational and cannot override that).
+   Then **Import/Export → Single initiative** card → drop the file → the
+   preview should show **0 warnings** → **Add as new** (or **Update**, which
+   keeps the existing initiative's id, creation date and links) → **Confirm**.
+6. The initiative appears in the Inventory with exactly the scores Claude
    reported.
 
 ## Publishing (maintainers)

package/dist/index.mjs

@@ -12,7 +12,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/version.ts
-var COMPOSER_VERSION = true ? "0.1.7" : readPackageVersion();
+var COMPOSER_VERSION = true ? "0.3.2" : readPackageVersion();
 
 // ../../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
 var external_exports = {};
@@ -4205,6 +4205,8 @@ var ListSnapshotsResponseItem = objectType({
     "solutionType": enumType(["Internal", "External", "Hybrid"]),
     "aiCategory": stringType(),
     "tags": arrayType(stringType()),
+    "docsUrl": stringType().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+    "pmUrl": stringType().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
     "archived": booleanType(),
     "evaluation": objectType({
       "valueScale": objectType({
@@ -4455,6 +4457,8 @@ var CreateSnapshotBody = objectType({
     "solutionType": enumType(["Internal", "External", "Hybrid"]),
     "aiCategory": stringType(),
     "tags": arrayType(stringType()),
+    "docsUrl": stringType().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+    "pmUrl": stringType().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
     "archived": booleanType(),
     "evaluation": objectType({
       "valueScale": objectType({
@@ -4710,6 +4714,8 @@ var RenameSnapshotResponse = objectType({
     "solutionType": enumType(["Internal", "External", "Hybrid"]),
     "aiCategory": stringType(),
     "tags": arrayType(stringType()),
+    "docsUrl": stringType().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+    "pmUrl": stringType().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
     "archived": booleanType(),
     "evaluation": objectType({
       "valueScale": objectType({
@@ -4956,6 +4962,8 @@ var ListInitiativesResponseItem = objectType({
   "solutionType": enumType(["Internal", "External", "Hybrid"]),
   "aiCategory": stringType(),
   "tags": arrayType(stringType()),
+  "docsUrl": stringType().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+  "pmUrl": stringType().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
   "archived": booleanType(),
   "evaluation": objectType({
     "valueScale": objectType({
@@ -5198,6 +5206,8 @@ var CreateInitiativeBody = objectType({
   "solutionType": enumType(["Internal", "External", "Hybrid"]),
   "aiCategory": stringType(),
   "tags": arrayType(stringType()),
+  "docsUrl": stringType().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+  "pmUrl": stringType().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
   "archived": booleanType(),
   "evaluation": objectType({
     "valueScale": objectType({
@@ -5448,6 +5458,8 @@ var GetInitiativeResponse = objectType({
   "solutionType": enumType(["Internal", "External", "Hybrid"]),
   "aiCategory": stringType(),
   "tags": arrayType(stringType()),
+  "docsUrl": stringType().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+  "pmUrl": stringType().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
   "archived": booleanType(),
   "evaluation": objectType({
     "valueScale": objectType({
@@ -5692,6 +5704,8 @@ var UpdateInitiativeBody = objectType({
   "solutionType": enumType(["Internal", "External", "Hybrid"]),
   "aiCategory": stringType(),
   "tags": arrayType(stringType()),
+  "docsUrl": stringType().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+  "pmUrl": stringType().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
   "archived": booleanType(),
   "evaluation": objectType({
     "valueScale": objectType({
@@ -5939,6 +5953,8 @@ var UpdateInitiativeResponse = objectType({
   "solutionType": enumType(["Internal", "External", "Hybrid"]),
   "aiCategory": stringType(),
   "tags": arrayType(stringType()),
+  "docsUrl": stringType().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+  "pmUrl": stringType().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
   "archived": booleanType(),
   "evaluation": objectType({
     "valueScale": objectType({
@@ -8178,6 +8194,15 @@ var MODES = {
     defaultCompanyName: "Halcyon Biosciences AG"
   }
 };
+function getModeOverride(mode, language, key) {
+  const md = MODES[mode];
+  if (!md) return void 0;
+  const dict = md.overrides[language];
+  if (dict && key in dict) return dict[key];
+  const enDict = md.overrides.en;
+  if (enDict && key in enDict) return enDict[key];
+  return void 0;
+}
 var AI_GATE_ITEMS = [
   { id: "businessCase", label: { en: "Business case validated", de: "Business Case validiert" } },
   { id: "dpia", label: { en: "DPIA / risk assessment signed", de: "DSFA / Risikobewertung unterzeichnet" } },
@@ -8211,6 +8236,59 @@ var DEFAULT_GATE_CHECKLISTS_BY_MODE = {
   innovation: buildDefaultsForMode(INNOVATION_GATE_ITEMS)
 };
 
+// ../../initiative-model/src/dimensions.ts
+var DIMENSION_KEYS = ["valueScale", "feasibility", "governance", "strategic"];
+var VALUE_SUBS = [
+  "frequencyOfProcess",
+  "labourIntensity",
+  "operationalLeverage",
+  "scalability",
+  "volumeSensitivity",
+  "costReduction",
+  "revenueImpact"
+];
+var FEASIBILITY_SUBS = [
+  "dataAvailability",
+  "dataQuality",
+  "modelRobustness",
+  "reproducibility",
+  "explainability",
+  "technologyMaturity",
+  "integrationFeasibility"
+];
+var GOVERNANCE_SUBS = [
+  "regulatoryExposure",
+  "humanOversight",
+  "decisionCriticality",
+  "reputationalRisk",
+  "operationalDependency",
+  "auditability",
+  "monitoringComplexity",
+  "cybersecurityExposure"
+];
+var STRATEGIC_SUBS = [
+  "strategicDifferentiation",
+  "qualityImprovement",
+  "operatingModelAlignment",
+  "transformationPotential",
+  "competitiveAdvantage",
+  "clientImpact",
+  "organisationalLeverage",
+  "innovationCapability"
+];
+var DIMENSION_SUBS = {
+  valueScale: VALUE_SUBS,
+  feasibility: FEASIBILITY_SUBS,
+  governance: GOVERNANCE_SUBS,
+  strategic: STRATEGIC_SUBS
+};
+var ALL_SLIDER_IDS = [...VALUE_SUBS, ...FEASIBILITY_SUBS, ...GOVERNANCE_SUBS, ...STRATEGIC_SUBS];
+var SLIDER_QUADRANT = (() => {
+  const out = {};
+  for (const dim of DIMENSION_KEYS) for (const k of DIMENSION_SUBS[dim]) out[k] = dim;
+  return out;
+})();
+
 // src/catalog.ts
 var enumValues = (e) => Object.values(e);
 var STATUS_VALUES = enumValues(InitiativeStatus);
@@ -8233,7 +8311,6 @@ var AI_ACT_VOCABULARIES = {
   artifactKeys: ACT_ARTIFACT_KEYS,
   obligationKeys: OPERATIONAL_OBLIGATION_KEYS
 };
-var DIMENSION_KEYS = ["valueScale", "feasibility", "governance", "strategic"];
 var sd = (key, en, de, helpEn, helpDe) => ({
   key,
   label: { en, de },
@@ -8475,10 +8552,10 @@ var DIMENSIONS = [
     ]
   }
 ];
-var DIMENSION_SUBS = Object.fromEntries(
-  DIMENSIONS.map((d) => [d.key, d.subs.map((s) => s.key)])
-);
 function modeOverlays() {
+  return MODE_OVERLAYS;
+}
+function computeModeOverlays() {
   const out = {};
   for (const mode of PORTFOLIO_MODES2) {
     if (mode === "ai") continue;
@@ -8509,14 +8586,15 @@ function modeOverlays() {
   }
   return out;
 }
+var MODE_OVERLAYS = computeModeOverlays();
 var REQUIRED_FIELDS = [
   { key: "name", type: "string", hint: { en: "Short initiative name", de: "Kurzer Name der Initiative" } },
   { key: "businessUnit", type: "string", hint: { en: "Owning business unit (use the org's own BU names)", de: "Zust\xE4ndiger Gesch\xE4ftsbereich (Namen der Organisation verwenden)" } },
   { key: "owner", type: "string", hint: { en: "Accountable person", de: "Verantwortliche Person" } },
   { key: "description", type: "string", hint: { en: "One or two sentences on what it does and for whom", de: "Ein bis zwei S\xE4tze: was sie tut und f\xFCr wen" } },
   { key: "status", type: "enum", values: STATUS_VALUES, hint: { en: "Lifecycle stage", de: "Lebenszyklus-Phase" } },
-  { key: "timelineStart", type: "date", hint: { en: "YYYY-MM-DD", de: "JJJJ-MM-TT" } },
-  { key: "timelineEnd", type: "date", hint: { en: "YYYY-MM-DD", de: "JJJJ-MM-TT" } },
+  { key: "timelineStart", type: "date", hint: { en: "dd/mm/yyyy (stored as yyyy-mm-dd)", de: "TT/MM/JJJJ (gespeichert als JJJJ-MM-TT)" } },
+  { key: "timelineEnd", type: "date", hint: { en: "dd/mm/yyyy (stored as yyyy-mm-dd)", de: "TT/MM/JJJJ (gespeichert als JJJJ-MM-TT)" } },
   { key: "budget", type: "number", hint: { en: "Total budget in the org's currency", de: "Gesamtbudget in der Organisationsw\xE4hrung" } },
   { key: "vendorDependency", type: "enum", values: VENDOR_DEPS, hint: { en: "How dependent on external vendors", de: "Abh\xE4ngigkeit von externen Anbietern" } },
   { key: "solutionType", type: "enum", values: SOLUTION_TYPES, hint: { en: "Built internally, bought, or hybrid", de: "Eigenbau, Zukauf oder hybrid" } },
@@ -8524,11 +8602,18 @@ var REQUIRED_FIELDS = [
 ];
 var OPTIONAL_SECTIONS = [
   { key: "tags", hint: { en: "Free-text tags", de: "Freie Schlagworte" } },
+  {
+    key: "docsUrl / pmUrl",
+    hint: {
+      en: "Links to the project documentation (Confluence, SharePoint, \u2026) and the project-management tool (Jira, MS Project, \u2026)",
+      de: "Links zur Projektdokumentation (Confluence, SharePoint, \u2026) und zum Projektmanagement-Werkzeug (Jira, MS Project, \u2026)"
+    }
+  },
   {
     key: "dependsOn",
     hint: {
-      en: "UUIDs of initiatives this one depends on. The Composer cannot look ids up \u2014 leave empty and link dependencies in the app unless the user gives you the ids.",
-      de: "UUIDs vorgelagerter Initiativen. Der Composer kann keine IDs nachschlagen \u2014 leer lassen und in der App verkn\xFCpfen, sofern der Nutzer keine IDs nennt."
+      en: "Ids of initiatives this one depends on. With the portfolio-context file, pick them from read_portfolio_context \u2192 lists.initiatives (id + name); without it, leave empty and link dependencies in the app.",
+      de: "IDs vorgelagerter Initiativen. Mit der Portfolio-Kontext-Datei aus read_portfolio_context \u2192 lists.initiatives (ID + Name) w\xE4hlen; ohne sie leer lassen und in der App verkn\xFCpfen."
     }
   },
   { key: "aiRiskTier / hitlPosture / dpiaStatus / modelCardStatus", hint: { en: "EU AI Act governance flags", de: "EU-AI-Act-Governance-Flags" } },
@@ -8545,8 +8630,8 @@ var OPTIONAL_SECTIONS = [
   {
     key: "requiredSkills",
     hint: {
-      en: "[{skillId, fte}] \u2014 skillId is the UUID of a skill that exists in the org; the Composer cannot look ids up \u2014 leave empty and link skills in the app unless the user gives you the ids.",
-      de: "[{skillId, fte}] \u2014 skillId ist die UUID eines vorhandenen Skills; leer lassen und in der App verkn\xFCpfen, sofern der Nutzer keine IDs nennt."
+      en: "[{skillId, fte}] \u2014 skillId is the id of a skill that exists in the organisation. With the portfolio-context file, pick from read_portfolio_context \u2192 lists.skills (id + name); without it, leave empty and link skills in the app.",
+      de: "[{skillId, fte}] \u2014 skillId ist die ID eines vorhandenen Skills. Mit der Portfolio-Kontext-Datei aus read_portfolio_context \u2192 lists.skills (ID + Name) w\xE4hlen; ohne sie leer lassen und in der App verkn\xFCpfen."
     }
   }
 ];
@@ -8594,7 +8679,7 @@ function describeZodShape(schema, depth = 0) {
 }
 function buildSchemaDescriptor(sectionShapes) {
   return {
-    about: "BICon initiative composer. Collect the required fields, then rate every sub-dimension 0\u2013100 (higher = more of the named quality) and a confidence per dimension. Dimension scores are DERIVED (mean of subs) \u2014 never ask the user for them. Values are used verbatim; enum values must match exactly; unknown keys are rejected.",
+    about: "BICon initiative composer. Collect the required fields, then rate every sub-dimension 0\u2013100 (higher = more of the named quality) and a confidence per dimension. Dimension scores are DERIVED (mean of subs) \u2014 never ask the user for them. Values are used verbatim; enum values must match exactly; unknown keys are rejected. Dates: talk dd/mm/yyyy with the user (dd/mm/yyyy, dd.mm.yyyy and yyyy-mm-dd are all accepted; stored as yyyy-mm-dd). Row ids of decision-log entries, status reports and incidents are minted by the Composer \u2014 never invent ids. To UPDATE an existing initiative pass its id as `id`; omit it for a new one.",
     requiredFields: REQUIRED_FIELDS,
     enums: {
       status: STATUS_VALUES,
@@ -8621,7 +8706,7 @@ function buildSchemaDescriptor(sectionShapes) {
     // keys, same 0–100 scale) — ask the user which mode their portfolio is in
     // and interview with that mode's wording. Missing entries = unchanged.
     portfolioModes: {
-      note: "Ask which portfolio mode the user works in (ai | digital | innovation). Keys and scale never change; only the wording below does. The app keeps EU-AI-Act fields only while it is in AI mode.",
+      note: "Ask which portfolio mode the user works in (ai | digital | innovation) \u2014 or read it from the portfolio-context file. Keys and scale never change; only the wording below does. Whether EU-AI-Act fields are kept depends on the organisation's AI-Act module switch (on by default in AI portfolios, configurable in every mode), not on the mode itself.",
       overlays: modeOverlays()
     },
     optionalSections: OPTIONAL_SECTIONS,
@@ -8636,7 +8721,8 @@ function buildSchemaDescriptor(sectionShapes) {
       ...AI_ACT_VOCABULARIES,
       note: "prohibitedPractices/art50Flags: arrays of these ids. artifacts/obligations: maps keyed by these ids. annexIIICategory: one of these, or omit when no Annex III area applies (record the reasoning in classificationRationale; annexExceptionRationale is only for an Art. 6(3) exception claim). Empty is honest; invented values are rejected."
     },
-    handoff: "Call assemble_initiative with the compact spec, review derivedScores (and any warnings) with the user, then call export_initiative_file with the SAME spec \u2192 save the JSON \u2192 in the app: Import/Export \u2192 Single initiative \u2192 drop the file \u2192 'Add as new' \u2192 Confirm. If the initiative carries EU-AI-Act data, the app must be in AI mode when importing."
+    portfolioContext: "Ask the user for the organisation's portfolio-context file first (in the app: Import/Export \u2192 'Download portfolio context'). Call read_portfolio_context on it: it returns the interview plan in the organisation's own wording, the sub-dimensions that are switched off, the slider step the ratings must follow, and the organisation's business units, categories, tags, skills and initiatives \u2014 with the file, business unit and category MUST be from those lists (no inventing) and skill / dependency ids are validated. Pass the same context to assemble_initiative and export_initiative_file. Without the file, interview with the wording below and treat business unit / category as free text.",
+    handoff: "Call assemble_initiative with the compact spec (+ context), review derivedScores (and any warnings) with the user, then call export_initiative_file with the SAME spec (+ context) \u2192 save the JSON \u2192 in the app: Import/Export \u2192 Single initiative \u2192 drop the file \u2192 'Add as new' \u2192 Confirm. If the initiative carries EU-AI-Act data, the organisation's EU-AI-Act module must be switched on (Settings \u203A AI Act) when importing."
   };
 }
 
@@ -8653,24 +8739,48 @@ function contractSection(key) {
   return s instanceof external_exports.ZodOptional ? s.unwrap() : s;
 }
 var keepDescription = (from, to) => from.description ? to.describe(from.description) : to;
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+var DMY = /^(\d{1,2})[./](\d{1,2})[./](\d{4})$/;
+function normaliseDateInput(v) {
+  if (typeof v !== "string") return v;
+  const m = DMY.exec(v.trim());
+  if (!m) return v;
+  const [, d, mo, y] = m;
+  return `${y}-${mo.padStart(2, "0")}-${d.padStart(2, "0")}`;
+}
+function isCalendarDate(s) {
+  if (!ISO_DATE.test(s)) return false;
+  const [y, m, d] = s.split("-").map(Number);
+  const dt = new Date(Date.UTC(y, m - 1, d));
+  return dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d;
+}
+var dateField = (what) => external_exports.preprocess(normaliseDateInput, external_exports.string().refine(isCalendarDate, { message: `${what} must be a real calendar date \u2014 dd/mm/yyyy or yyyy-mm-dd` })).describe("dd/mm/yyyy (or yyyy-mm-dd)");
+var DATE_LIKE_KEY = /^date$|Date$|At$/;
+var MINTED_KEYS = /* @__PURE__ */ new Set(["id", "createdAt", "updatedAt"]);
+var holdsString = (s) => s instanceof external_exports.ZodString || s instanceof external_exports.ZodOptional && s.unwrap() instanceof external_exports.ZodString || s instanceof external_exports.ZodNullable && s.unwrap() instanceof external_exports.ZodString;
 function deepStrict(schema) {
-  const walk = (s) => {
+  const walk = (s, inArrayItem = false) => {
     if (s instanceof external_exports.ZodObject) {
       const next = {};
-      for (const [k, v] of Object.entries(s.shape)) next[k] = walk(v);
+      for (const [k, v] of Object.entries(s.shape)) {
+        let field = walk(v, false);
+        if (inArrayItem && MINTED_KEYS.has(k) && !(field instanceof external_exports.ZodOptional)) field = field.optional();
+        if (DATE_LIKE_KEY.test(k) && holdsString(field)) field = keepDescription(field, external_exports.preprocess(normaliseDateInput, field));
+        next[k] = field;
+      }
       return keepDescription(s, external_exports.object(next).strict());
     }
-    if (s instanceof external_exports.ZodOptional) return keepDescription(s, walk(s.unwrap()).optional());
-    if (s instanceof external_exports.ZodNullable) return keepDescription(s, walk(s.unwrap()).nullable());
-    if (s instanceof external_exports.ZodDefault) return keepDescription(s, walk(s.removeDefault()).default(s._def.defaultValue()));
-    if (s instanceof external_exports.ZodEffects) return new external_exports.ZodEffects({ ...s._def, schema: walk(s._def.schema) });
-    if (s instanceof external_exports.ZodArray) return new external_exports.ZodArray({ ...s._def, type: walk(s.element) });
-    if (s instanceof external_exports.ZodRecord) return new external_exports.ZodRecord({ ...s._def, valueType: walk(s.valueSchema) });
-    if (s instanceof external_exports.ZodUnion) return new external_exports.ZodUnion({ ...s._def, options: s.options.map(walk) });
+    if (s instanceof external_exports.ZodOptional) return keepDescription(s, walk(s.unwrap(), inArrayItem).optional());
+    if (s instanceof external_exports.ZodNullable) return keepDescription(s, walk(s.unwrap(), inArrayItem).nullable());
+    if (s instanceof external_exports.ZodDefault) return keepDescription(s, walk(s.removeDefault(), inArrayItem).default(s._def.defaultValue()));
+    if (s instanceof external_exports.ZodEffects) return new external_exports.ZodEffects({ ...s._def, schema: walk(s._def.schema, inArrayItem) });
+    if (s instanceof external_exports.ZodArray) return new external_exports.ZodArray({ ...s._def, type: walk(s.element, true) });
+    if (s instanceof external_exports.ZodRecord) return new external_exports.ZodRecord({ ...s._def, valueType: walk(s.valueSchema, inArrayItem) });
+    if (s instanceof external_exports.ZodUnion) return new external_exports.ZodUnion({ ...s._def, options: s.options.map((o) => walk(o, inArrayItem)) });
     if (s instanceof external_exports.ZodIntersection) {
       const { left, right } = s._def;
-      if (left instanceof external_exports.ZodObject && right instanceof external_exports.ZodObject) return keepDescription(s, walk(left.merge(right)));
-      return new external_exports.ZodIntersection({ ...s._def, left: walk(left), right: walk(right) });
+      if (left instanceof external_exports.ZodObject && right instanceof external_exports.ZodObject) return keepDescription(s, walk(left.merge(right), inArrayItem));
+      return new external_exports.ZodIntersection({ ...s._def, left: walk(left, inArrayItem), right: walk(right, inArrayItem) });
     }
     return s;
   };
@@ -8694,41 +8804,41 @@ var SECTION_SCHEMAS = Object.fromEntries(
   SECTION_KEYS.map((k) => [k, contractSection(k)])
 );
 var SECTION_DESCRIPTIONS = {
-  aiAct: "EU AI Act block \u2014 see get_initiative_schema \u2192 sectionShapes.aiAct for the exact keys (role, gpai, prohibitedPractices, art50Flags, annexIIICategory, artifacts, obligations, registration, aiLiteracy, incidents\u2026) and aiActVocabularies for the allowed ids. Unknown keys are rejected.",
+  aiAct: "EU AI Act block \u2014 see get_initiative_schema \u2192 sectionShapes.aiAct for the exact keys (role, gpai, prohibitedPractices, art50Flags, annexIIICategory, artifacts, obligations, registration, aiLiteracy, incidents\u2026) and aiActVocabularies for the allowed ids. Unknown keys are rejected. Incident ids/stamps are minted by the Composer \u2014 leave them out.",
   economics: "Economics block (P10/P50/P90 benefit & cost, ramp, confidence, discount rate) \u2014 see sectionShapes.economics.",
   actuals: "Actuals block (In Production only) \u2014 see sectionShapes.actuals.",
-  decisionLog: "Decision log entries \u2014 see sectionShapes.decisionLog.",
-  statusReports: "Status reports \u2014 see sectionShapes.statusReports.",
-  requiredSkills: "Required skills [{skillId, fte}] \u2014 skillId must be an existing skill's UUID in the target organisation (the Composer cannot look ids up; leave the list empty and link skills in the app when unsure)."
+  decisionLog: "Decision log entries \u2014 see sectionShapes.decisionLog. Entry ids are minted by the Composer \u2014 leave them out. Dates dd/mm/yyyy or yyyy-mm-dd.",
+  statusReports: "Status reports \u2014 see sectionShapes.statusReports. Report ids are minted by the Composer \u2014 leave them out. Dates dd/mm/yyyy or yyyy-mm-dd.",
+  requiredSkills: "Required skills [{skillId, fte}] \u2014 skillId must be the id of a skill that exists in the organisation. With the portfolio context the Composer validates it (read_portfolio_context \u2192 lists.skills gives id + name); without it, leave the list empty and link skills in the app."
 };
-var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
-function isCalendarDate(s) {
-  if (!ISO_DATE.test(s)) return false;
-  const [y, m, d] = s.split("-").map(Number);
-  const dt = new Date(Date.UTC(y, m - 1, d));
-  return dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d;
-}
-var isoDate = (what) => external_exports.string().refine(isCalendarDate, { message: `${what} must be a real calendar date in YYYY-MM-DD` }).describe("YYYY-MM-DD");
+var contextWire = () => external_exports.preprocess(parseIfString, external_exports.union([external_exports.string().regex(/^ctx_[0-9a-f]{16}$/, "a contextId looks like ctx_<16 hex>"), external_exports.object({}).passthrough()]));
 var requiredText = () => external_exports.string().trim().min(1, "must not be empty");
-var UUID_HINT = "must be the UUID of an initiative that exists in the target organisation \u2014 the Composer cannot look ids up; leave the list empty and link dependencies in the app when unsure";
+var DEPENDS_ON_HINT = "the id of an initiative that exists in the organisation. With the portfolio context the Composer validates it (read_portfolio_context \u2192 lists.initiatives gives id + name); without it, only UUID-shaped ids are accepted \u2014 leave the list empty and link dependencies in the app when unsure";
 var dimensionInput = () => external_exports.object({
-  subs: external_exports.record(external_exports.string(), external_exports.number()).describe("Named sub-dimension ratings 0\u2013100 \u2014 every key of the dimension is required, no others"),
+  subs: external_exports.record(external_exports.string(), external_exports.number()).optional().describe(
+    "Named sub-dimension ratings 0\u2013100 \u2014 every ENABLED key of the dimension is required and no other key is accepted; switched-off ones (portfolio context) are left out"
+  ),
   confidence: external_exports.enum(CONFIDENCES)
 }).strict();
 var compactSpecSchema = external_exports.object({
+  id: external_exports.string().trim().min(1).optional().describe(
+    "ONLY to UPDATE an existing initiative: its id (from read_portfolio_context \u2192 lists.initiatives, or the app). The exported file then updates that initiative in place. Omit for a new initiative \u2014 never invent an id."
+  ),
   name: requiredText(),
-  businessUnit: requiredText(),
+  businessUnit: requiredText().describe("With a portfolio context: one of the organisation's business units (read_portfolio_context \u2192 lists.businessUnits)"),
   owner: requiredText(),
   description: requiredText(),
   status: external_exports.enum(STATUS_VALUES),
-  timelineStart: isoDate("timelineStart"),
-  timelineEnd: isoDate("timelineEnd"),
+  timelineStart: dateField("timelineStart"),
+  timelineEnd: dateField("timelineEnd"),
   budget: external_exports.number().finite(),
   vendorDependency: external_exports.enum(VENDOR_DEPS),
   solutionType: external_exports.enum(SOLUTION_TYPES),
-  aiCategory: requiredText(),
+  aiCategory: requiredText().describe("With a portfolio context: one of the organisation's categories (read_portfolio_context \u2192 lists.categories)"),
   tags: external_exports.array(external_exports.string().trim().min(1)).optional(),
-  dependsOn: external_exports.array(external_exports.string().uuid(`each entry ${UUID_HINT}`)).optional().describe(`Ids of initiatives this one depends on \u2014 each ${UUID_HINT}`),
+  docsUrl: external_exports.string().optional().describe("Link to the project documentation (Confluence, SharePoint, \u2026)"),
+  pmUrl: external_exports.string().optional().describe("Link to the project-management tool (Jira, MS Project, \u2026)"),
+  dependsOn: external_exports.array(external_exports.string().trim().min(1)).optional().describe(`Ids of initiatives this one depends on \u2014 each entry ${DEPENDS_ON_HINT}`),
   evaluation: external_exports.object({
     valueScale: dimensionInput(),
     feasibility: dimensionInput(),
@@ -8748,15 +8858,22 @@ var compactSpecSchema = external_exports.object({
   modelCardStatus: external_exports.enum(MODEL_CARD_STATUSES).optional(),
   modelCardUrl: external_exports.string().optional(),
   prohibitedOverride: external_exports.string().optional(),
-  aiAct: wireSection(SECTION_SCHEMAS.aiAct, SECTION_DESCRIPTIONS.aiAct).optional()
+  aiAct: wireSection(SECTION_SCHEMAS.aiAct, SECTION_DESCRIPTIONS.aiAct).optional(),
+  context: contextWire().optional().describe(
+    `OPTIONAL but strongly recommended: the organisation's portfolio context \u2014 the contextId returned by read_portfolio_context ("ctx_\u2026") or the file's JSON itself. With it, switched-off sub-dimensions are skipped in the score, business unit / category must be the organisation's own, and skill / dependency / update ids are validated.`
+  )
 }).strict();
 var exportInputSchema = external_exports.object({
   spec: external_exports.preprocess(parseIfString, external_exports.object({}).passthrough()).describe("The compact spec exactly as accepted by assemble_initiative (same object \u2014 see that tool's schema)"),
   sourceMode: external_exports.enum(PORTFOLIO_MODES2).optional().describe(
-    "Portfolio mode the user works in (default ai) \u2014 recorded in the file. The app keeps AI-Act fields only while it is itself in AI mode; this field does not change that."
+    "Portfolio mode recorded in the file (default: the context's mode, else ai). Informational \u2014 whether the app keeps EU-AI-Act fields depends on the organisation's AI-Act module switch, not on this."
   ),
-  language: external_exports.enum(LANGUAGES2).optional().describe("Language recorded in the file (default en)"),
-  filename: external_exports.string().trim().min(1).optional().describe("Override the suggested filename")
+  language: external_exports.enum(LANGUAGES2).optional().describe("Language recorded in the file (default: the context's language, else en)"),
+  filename: external_exports.string().trim().min(1).optional().describe("Override the suggested filename"),
+  context: contextWire().optional().describe("The organisation's portfolio context (contextId or file), same as for assemble_initiative \u2014 also sets the file's default sourceMode and language.")
+}).strict();
+var readContextInputSchema = external_exports.object({
+  context: contextWire().describe("The portfolio-context file's JSON (object or string), exactly as downloaded from the app \u2014 or a contextId from an earlier call")
 }).strict();
 function formatIssues(err) {
   return err.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`);
@@ -8783,21 +8900,240 @@ function dimensionScore(subcomponents, disabled) {
   return normaliseScore(sum / values.length);
 }
 
+// src/context.ts
+import { createHash } from "node:crypto";
+
+// ../../initiative-model/src/portfolio-context.ts
+var PORTFOLIO_CONTEXT_KIND = "portfolio-context";
+var PORTFOLIO_CONTEXT_VERSION = 1;
+
+// ../../initiative-model/src/ai-act-fields.ts
+var AI_ACT_FIELDS = [
+  "aiAct",
+  "aiRiskTier",
+  "hitlPosture",
+  "dpiaStatus",
+  "dpiaUrl",
+  "modelCardStatus",
+  "modelCardUrl",
+  "prohibitedOverride"
+];
+
+// src/context.ts
+var sliderSchema = external_exports.object({
+  key: external_exports.string().min(1),
+  dimension: external_exports.enum(DIMENSION_KEYS),
+  enabled: external_exports.boolean(),
+  label: external_exports.string().optional(),
+  help: external_exports.string().optional(),
+  note: external_exports.string().optional()
+}).passthrough();
+var portfolioContextSchema = external_exports.object({
+  kind: external_exports.literal(PORTFOLIO_CONTEXT_KIND),
+  version: external_exports.number().int().min(1),
+  exportedAt: external_exports.string(),
+  companyName: external_exports.string().optional(),
+  portfolioMode: external_exports.enum(PORTFOLIO_MODES2),
+  language: external_exports.enum(LANGUAGES2),
+  currency: external_exports.string(),
+  aiActEnabled: external_exports.boolean(),
+  discountRatePct: external_exports.number(),
+  /** Slider step (5/10/20/25). Files from before 2026-08-21 lack it → no grid check. */
+  sliderGranularity: external_exports.number().int().positive().max(100).optional(),
+  businessUnits: external_exports.array(external_exports.string()),
+  categories: external_exports.array(external_exports.string()),
+  suggestedTags: external_exports.array(external_exports.string()),
+  skills: external_exports.array(external_exports.object({ id: external_exports.string().min(1), name: external_exports.string() }).passthrough()),
+  initiatives: external_exports.array(external_exports.object({ id: external_exports.string().min(1), name: external_exports.string(), status: external_exports.enum(STATUS_VALUES) }).passthrough()),
+  sliders: external_exports.array(sliderSchema)
+}).passthrough();
+var CONTEXT_SUPPORTED_VERSION = PORTFOLIO_CONTEXT_VERSION;
+function versionNotice(ctx) {
+  return ctx.version > CONTEXT_SUPPORTED_VERSION ? `The portfolio-context file is version ${ctx.version}; this Composer understands version ${CONTEXT_SUPPORTED_VERSION}. Newer fields are ignored \u2014 update the Composer (Import/Export \u2192 download the extension again) to be safe.` : void 0;
+}
+var CONTEXT_ID_PREFIX = "ctx_";
+var CACHE_MAX = 32;
+var cache = /* @__PURE__ */ new Map();
+function contextIdOf(ctx) {
+  return CONTEXT_ID_PREFIX + createHash("sha256").update(JSON.stringify(ctx)).digest("hex").slice(0, 16);
+}
+function remember(ctx) {
+  const id = contextIdOf(ctx);
+  cache.delete(id);
+  cache.set(id, ctx);
+  while (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value);
+  return id;
+}
+function resolveContext(raw) {
+  if (typeof raw === "string") {
+    if (raw.startsWith(CONTEXT_ID_PREFIX)) {
+      const hit = cache.get(raw);
+      if (hit) {
+        remember(hit);
+        return { ok: true, context: hit, contextId: raw };
+      }
+      return {
+        ok: false,
+        errors: [
+          `context: unknown contextId "${raw}" \u2014 the Composer has restarted since it was issued, or it belongs to a different file. Call read_portfolio_context again with the file's JSON and use the new contextId (or pass the file itself).`
+        ]
+      };
+    }
+    return { ok: false, errors: ["context: expected the portfolio-context file's JSON (object or JSON string) or a contextId from read_portfolio_context."] };
+  }
+  const parsed = portfolioContextSchema.safeParse(raw);
+  if (!parsed.success) return { ok: false, errors: formatIssues(parsed.error).map((e) => `context.${e}`) };
+  const context = parsed.data;
+  return { ok: true, context, contextId: remember(context) };
+}
+function disabledSliders(ctx) {
+  return new Set(ctx.sliders.filter((s) => !s.enabled).map((s) => s.key));
+}
+function allowedList(values, max = 12) {
+  if (values.length <= max) return values.join(" | ");
+  return `${values.slice(0, max).join(" | ")} \u2026 (${values.length - max} more \u2014 see read_portfolio_context)`;
+}
+var norm = (s) => s.trim().toLowerCase();
+function canonical(value, list) {
+  const key = norm(value);
+  return list.find((v) => norm(v) === key);
+}
+function checkAgainstContext(spec, ctx) {
+  const errors = [];
+  const warnings = [];
+  const v = versionNotice(ctx);
+  if (v) warnings.push(v);
+  const bus = ctx.businessUnits;
+  let businessUnit = spec.businessUnit;
+  const buMatch = canonical(spec.businessUnit, bus);
+  if (!buMatch) {
+    errors.push(
+      bus.length ? `businessUnit: "${spec.businessUnit}" is not a business unit of this organisation \u2014 use one of: ${allowedList(bus)}. New business units are created in the app's Settings, not here.` : `businessUnit: this organisation has no business units configured \u2014 add them in the app's Settings, download the portfolio context again, then continue.`
+    );
+  } else {
+    if (buMatch !== spec.businessUnit) warnings.push(`businessUnit: "${spec.businessUnit}" normalised to the organisation's spelling "${buMatch}".`);
+    businessUnit = buMatch;
+  }
+  const cats = ctx.categories;
+  let aiCategory = spec.aiCategory;
+  const catMatch = canonical(spec.aiCategory, cats);
+  if (!catMatch) {
+    errors.push(
+      cats.length ? `aiCategory: "${spec.aiCategory}" is not a category of this organisation \u2014 use one of: ${allowedList(cats)}. New categories are created in the app's Settings, not here.` : `aiCategory: this organisation has no categories configured \u2014 add them in the app's Settings, download the portfolio context again, then continue.`
+    );
+  } else {
+    if (catMatch !== spec.aiCategory) warnings.push(`aiCategory: "${spec.aiCategory}" normalised to the organisation's spelling "${catMatch}".`);
+    aiCategory = catMatch;
+  }
+  const initiativeIds = new Set(ctx.initiatives.map((i) => i.id));
+  if (spec.id !== void 0 && !initiativeIds.has(spec.id)) {
+    errors.push(`id: "${spec.id}" is not an initiative of this organisation \u2014 an id is only for UPDATING an existing initiative (read_portfolio_context \u2192 lists.initiatives); omit it to create a new one.`);
+  }
+  for (const [i, id] of (spec.dependsOn ?? []).entries()) {
+    if (!initiativeIds.has(id)) errors.push(`dependsOn.${i}: "${id}" is not the id of an initiative in this organisation \u2014 pick from read_portfolio_context \u2192 lists.initiatives (id + name), or leave dependsOn empty.`);
+  }
+  if (spec.id !== void 0 && (spec.dependsOn ?? []).includes(spec.id)) errors.push("dependsOn: an initiative cannot depend on itself.");
+  const skillIds = new Set(ctx.skills.map((s) => s.id));
+  for (const [i, s] of (spec.requiredSkills ?? []).entries()) {
+    if (!skillIds.has(s.skillId)) errors.push(`requiredSkills.${i}.skillId: "${s.skillId}" is not a skill of this organisation \u2014 pick from read_portfolio_context \u2192 lists.skills (id + name), or leave requiredSkills empty.`);
+  }
+  const aiFieldsSet = AI_ACT_FIELDS.filter((f) => spec[f] !== void 0);
+  if (aiFieldsSet.length && !ctx.aiActEnabled) {
+    warnings.push(
+      `EU-AI-Act fields are set (${aiFieldsSet.join(", ")}), but this organisation's AI-Act module is switched OFF \u2014 the app removes ${AI_ACT_FIELDS.join(" / ")} on import unless the module is switched on first (Settings \u203A AI Act).`
+    );
+  }
+  return { errors, warnings, businessUnit, aiCategory };
+}
+function resolveSub(base, ctxSlider, mode, lang) {
+  const out = {
+    key: base.key,
+    label: ctxSlider?.label?.trim() || getModeOverride(mode, lang, `sub.${base.key}`) || base.label[lang],
+    help: ctxSlider?.help?.trim() || getModeOverride(mode, lang, `subHelp.${base.key}`) || base.help[lang]
+  };
+  const note = ctxSlider?.note?.trim();
+  if (note) out.note = note;
+  return out;
+}
+function gridExample(step) {
+  const pts = [0, step, 2 * step].filter((v) => v < 100);
+  return `${pts.join(", ")} \u2026 100`;
+}
+function buildInterviewPlan(ctx, contextId) {
+  const mode = ctx.portfolioMode;
+  const lang = ctx.language;
+  const ctxByKey = new Map(ctx.sliders.map((s) => [s.key, s]));
+  const disabled = disabledSliders(ctx);
+  const dimensions = DIMENSIONS.map((d) => {
+    const subs = d.subs.filter((s) => !disabled.has(s.key)).map((s) => resolveSub(s, ctxByKey.get(s.key), mode, lang));
+    return { key: d.key, title: getModeOverride(mode, lang, `dim.${d.key}.title`) || d.title[lang], subs, allSwitchedOff: subs.length === 0 };
+  });
+  const skipped = DIMENSION_KEYS.flatMap((dim) => DIMENSION_SUBS[dim].filter((k) => disabled.has(k)).map((key) => ({ key, dimension: dim })));
+  const allOff = dimensions.filter((d) => d.allSwitchedOff).map((d) => d.key);
+  const warnings = [];
+  const v = versionNotice(ctx);
+  if (v) warnings.push(v);
+  const rules = [
+    "Interview with these labels, help texts and notes \u2014 they are the organisation's own wording for its portfolio mode.",
+    skipped.length ? `Do NOT ask about the ${skipped.length} switched-off sub-dimension(s) listed under interview.skipped and do not send them; the app excludes them from the dimension score, and so does the Composer when the same context is passed to assemble_initiative / export_initiative_file. Every OTHER sub-dimension of a dimension is still required.` : "No sub-dimension is switched off in this mode: all 30 are asked and scored.",
+    ...allOff.length ? [`Dimension(s) with EVERY sub-dimension switched off (${allOff.join(", ")}) still need an entry in evaluation: { subs: {}, confidence } \u2014 the score is 0 there; ask only for the confidence.`] : [],
+    ctx.businessUnits.length && ctx.categories.length ? "businessUnit MUST be one of lists.businessUnits and aiCategory one of lists.categories (matched case-insensitively, normalised to the organisation's spelling) \u2014 the Composer rejects anything else; new ones are created in the app's Settings, not in the interview." : "This organisation has no business units and/or categories configured yet \u2014 they must be added in the app's Settings and the context downloaded again before an initiative can be assembled.",
+    "dependsOn entries must be ids from lists.initiatives; requiredSkills[].skillId must be ids from lists.skills. Never invent an id; leave the list empty when unsure.",
+    "To UPDATE an existing initiative instead of creating a new one, pass its id (from lists.initiatives) as `id` in the spec \u2014 the exported file then updates it in the app (Import/Export \u2192 Single initiative \u2192 'Update'). Omit id for a new initiative.",
+    ...ctx.sliderGranularity ? [`Ratings are in steps of ${ctx.sliderGranularity} (the organisation's slider step \u2014 Settings \u203A Slider granularity): ask for and send only multiples of ${ctx.sliderGranularity} between 0 and 100 (${gridExample(ctx.sliderGranularity)}); any other value is rejected.`] : [],
+    "Dates: talk to the user in dd/mm/yyyy; you may send dates as dd/mm/yyyy, dd.mm.yyyy or yyyy-mm-dd \u2014 the Composer stores yyyy-mm-dd.",
+    ctx.aiActEnabled ? "The organisation's EU-AI-Act module is ON: collect the AI-Act block and governance flags." : "The organisation's EU-AI-Act module is OFF: skip the AI-Act block and governance flags (the app would remove them on import).",
+    `Pass \`context: "${contextId}"\` (this contextId \u2014 or the whole file again) to assemble_initiative and export_initiative_file so scores are derived over the enabled sub-dimensions and ids are validated. Amounts are in ${ctx.currency}; the default discount rate is ${ctx.discountRatePct}%.`,
+    `The file is from ${ctx.exportedAt}; if the user changed settings since, ask them to export it again (Import/Export \u2192 Download portfolio context).`
+  ];
+  return {
+    contextId,
+    organisation: {
+      ...ctx.companyName ? { companyName: ctx.companyName } : {},
+      portfolioMode: mode,
+      language: lang,
+      currency: ctx.currency,
+      aiActEnabled: ctx.aiActEnabled,
+      discountRatePct: ctx.discountRatePct,
+      ...ctx.sliderGranularity ? { sliderGranularity: ctx.sliderGranularity } : {},
+      contextExportedAt: ctx.exportedAt
+    },
+    lists: {
+      businessUnits: ctx.businessUnits,
+      categories: ctx.categories,
+      suggestedTags: ctx.suggestedTags,
+      skills: ctx.skills.map((s) => ({ id: s.id, name: s.name })),
+      initiatives: ctx.initiatives.map((i) => ({ id: i.id, name: i.name, status: i.status }))
+    },
+    interview: {
+      dimensions,
+      skipped,
+      scoreDerivation: "mean of the ENABLED sub-dimension values (switched-off ones excluded), rounded, clamped 0\u2013100 \u2014 the app's own function"
+    },
+    rules,
+    warnings
+  };
+}
+
 // src/assembler.ts
-function checkSubs(dim, subs, errors) {
+var uuidSchema = external_exports.string().uuid();
+var isUuid = (v) => typeof v === "string" && uuidSchema.safeParse(v).success;
+function checkSubs(dim, subs, errors, disabled, step) {
   const expected = DIMENSION_SUBS[dim];
+  const enabled = expected.filter((k) => !disabled.has(k));
   if (!subs || typeof subs !== "object") {
-    errors.push(`evaluation.${dim}.subs is missing (expected keys: ${expected.join(", ")})`);
+    if (enabled.length) errors.push(`evaluation.${dim}.subs is missing (expected keys: ${enabled.join(", ")})`);
     return;
   }
-  for (const key of expected) {
+  for (const key of enabled) {
     const v = subs[key];
     if (v === void 0) errors.push(`evaluation.${dim}.subs.${key} is missing`);
     else if (typeof v !== "number" || !Number.isFinite(v)) errors.push(`evaluation.${dim}.subs.${key} must be a number`);
     else if (v < 0 || v > 100) errors.push(`evaluation.${dim}.subs.${key} must be within 0\u2013100 (got ${v})`);
+    else if (step && v % step !== 0) errors.push(`evaluation.${dim}.subs.${key} must be a multiple of ${step} \u2014 the organisation's slider step (got ${v})`);
   }
   for (const key of Object.keys(subs)) {
-    if (!expected.includes(key)) errors.push(`evaluation.${dim}.subs.${key} is not a known sub-dimension (expected: ${expected.join(", ")})`);
+    if (!expected.includes(key)) errors.push(`evaluation.${dim}.subs.${key} is not a known sub-dimension (expected: ${enabled.join(", ")})`);
   }
 }
 function checkAiActVocabularies(block, errors) {
@@ -8826,44 +9162,89 @@ function checkAiActVocabularies(block, errors) {
     errors.push(`aiAct.annexIIICategory: "${cat}" is not an Annex III category \u2014 allowed: ${ANNEX_III_CATEGORIES.join(" | ")}; omit it when no Annex III area applies.`);
   }
 }
-function assembleInitiative(spec, now = /* @__PURE__ */ new Date()) {
+function mintNestedIds(rows, stamp, withStamps = false) {
+  if (!rows) return void 0;
+  return rows.map((r) => {
+    const next = { ...r, id: isUuid(r.id) ? r.id : randomUUID() };
+    if (withStamps) {
+      if (!next.createdAt) next.createdAt = stamp;
+      if (!next.updatedAt) next.updatedAt = stamp;
+    }
+    return next;
+  });
+}
+function assembleInitiative(input, now = /* @__PURE__ */ new Date()) {
   const errors = [];
   const warnings = [];
+  const { context: rawContext, ...spec } = input;
+  let context;
+  let contextId;
+  if (rawContext !== void 0) {
+    const resolved = resolveContext(rawContext);
+    if (!resolved.ok) return { ok: false, errors: resolved.errors, warnings };
+    context = resolved.context;
+    contextId = resolved.contextId;
+  }
+  const disabled = context ? disabledSliders(context) : /* @__PURE__ */ new Set();
   for (const dim of DIMENSION_KEYS) {
     const d = spec.evaluation?.[dim];
     if (!d) {
       errors.push(`evaluation.${dim} is missing`);
       continue;
     }
-    checkSubs(dim, d.subs, errors);
+    checkSubs(dim, d.subs, errors, disabled, context?.sliderGranularity);
     if (!d.confidence) errors.push(`evaluation.${dim}.confidence is missing (Low | Medium | High)`);
+    for (const key of Object.keys(d.subs ?? {})) {
+      if (disabled.has(key)) warnings.push(`evaluation.${dim}.subs.${key}: this sub-dimension is switched off in the organisation \u2014 value ignored (stored as 0, not scored).`);
+    }
   }
   if (spec.aiAct && typeof spec.aiAct === "object") checkAiActVocabularies(spec.aiAct, errors);
+  let businessUnit = spec.businessUnit;
+  let aiCategory = spec.aiCategory;
+  if (context) {
+    const c = checkAgainstContext(spec, context);
+    errors.push(...c.errors);
+    warnings.push(...c.warnings);
+    businessUnit = c.businessUnit;
+    aiCategory = c.aiCategory;
+  } else {
+    if (spec.id !== void 0 && !isUuid(spec.id)) errors.push(`id: "${spec.id}" is not a UUID \u2014 an id is only for UPDATING an existing initiative; omit it to create a new one, or provide the organisation's portfolio context so the id can be verified.`);
+    for (const [i, id] of (spec.dependsOn ?? []).entries()) {
+      if (!isUuid(id)) errors.push(`dependsOn.${i}: "${id}" is not a UUID \u2014 without the organisation's portfolio context the Composer cannot verify ids; leave dependsOn empty and link dependencies in the app, or provide the context.`);
+    }
+  }
   if (spec.timelineStart && spec.timelineEnd && spec.timelineEnd < spec.timelineStart) {
     warnings.push("timelineEnd is before timelineStart");
   }
-  if (errors.length) return { ok: false, errors, warnings };
+  if (errors.length) return { ok: false, errors, warnings, ...contextId ? { contextId } : {} };
   const evaluation = Object.fromEntries(
     DIMENSION_KEYS.map((dim) => {
       const d = spec.evaluation[dim];
-      return [dim, { score: dimensionScore(d.subs), confidence: d.confidence, subs: d.subs }];
+      const subs = Object.fromEntries(DIMENSION_SUBS[dim].map((k) => [k, disabled.has(k) ? 0 : d.subs?.[k] ?? 0]));
+      return [dim, { score: dimensionScore(subs, disabled), confidence: d.confidence, subs }];
     })
   );
   const stamp = now.toISOString();
+  const aiAct = spec.aiAct;
   const candidate = {
     ...spec,
-    id: randomUUID(),
+    id: spec.id ?? randomUUID(),
+    businessUnit,
+    aiCategory,
     tags: spec.tags ?? [],
     archived: false,
     dependsOn: spec.dependsOn ?? [],
     evaluation,
+    decisionLog: mintNestedIds(spec.decisionLog, stamp),
+    statusReports: mintNestedIds(spec.statusReports, stamp),
+    aiAct: aiAct ? { ...aiAct, ...aiAct.incidents ? { incidents: mintNestedIds(aiAct.incidents, stamp, true) } : {} } : void 0,
     createdAt: stamp,
     updatedAt: stamp
   };
   const parsed = CreateInitiativeBody.safeParse(candidate);
-  if (!parsed.success) return { ok: false, errors: formatIssues(parsed.error), warnings };
+  if (!parsed.success) return { ok: false, errors: formatIssues(parsed.error), warnings, ...contextId ? { contextId } : {} };
   const derivedScores = Object.fromEntries(DIMENSION_KEYS.map((dim) => [dim, evaluation[dim].score]));
-  return { ok: true, initiative: parsed.data, derivedScores, warnings, errors };
+  return { ok: true, initiative: parsed.data, derivedScores, warnings, errors, ...contextId ? { contextId } : {} };
 }
 
 // ../../initiative-model/src/backup-version.ts
@@ -8891,9 +9272,9 @@ function suggestFilename(name, now = /* @__PURE__ */ new Date()) {
 var IMPORT_INSTRUCTIONS = [
   "1. Save the JSON below as the suggested filename.",
   "2. In the BICon app (signed in to the target organisation), open Import/Export.",
-  "3. If the initiative carries EU-AI-Act data, make sure the portfolio is in AI mode first \u2014 the app strips AI-Act fields when it is not.",
+  "3. If the initiative carries EU-AI-Act data, make sure the organisation's EU-AI-Act module is switched on (Settings \u203A AI Act) \u2014 the app strips AI-Act fields while it is off.",
   "4. In the 'Single initiative' card, drop the file (or Browse).",
-  "5. Review the preview \u2014 it should show 0 warnings \u2014 then choose 'Add as new' and Confirm.",
+  "5. Review the preview \u2014 it should show 0 warnings \u2014 then choose 'Add as new' (or 'Update' when the file carries an existing initiative's id or the same name \u2014 the app then keeps that initiative's id and history) and Confirm.",
   "6. The initiative appears in the Inventory with the derived dimension scores."
 ].join("\n");
 
@@ -8925,10 +9306,12 @@ function createServer() {
     async () => text({
       capabilities: [
         "strict typed schemas: unknown keys anywhere in the spec are rejected with their exact path (never silently dropped)",
-        "sections (aiAct/economics/actuals/decisionLog/statusReports/requiredSkills) accept a JSON object/array or the same JSON as a string",
+        "sections (aiAct/economics/actuals/decisionLog/statusReports/requiredSkills) accept a JSON object/array or the same JSON as a string; row ids are minted by the Composer",
+        "dates accepted as dd/mm/yyyy, dd.mm.yyyy or yyyy-mm-dd (stored as yyyy-mm-dd)",
         "get_initiative_schema: sectionShapes, aiActVocabularies, portfolio-mode wording overlays",
         "AI-Act vocabulary and id-format enforcement with the allowed values in the error",
-        "one pipeline: export_initiative_file takes the same spec as assemble_initiative \u2014 scores are always derived"
+        "one pipeline: export_initiative_file takes the same spec as assemble_initiative \u2014 scores are always derived; pass `id` to update an existing initiative",
+        "portfolio context: read_portfolio_context turns the app's exported context file into an organisation-specific interview plan and a short contextId; with it, switched-off sub-dimensions are skipped in the score, business unit / category must be the organisation's own, and skill / dependency / update ids are validated"
       ]
     })
   );
@@ -8940,11 +9323,24 @@ function createServer() {
     },
     async () => ({ content: [{ type: "text", text: DESCRIPTOR_TEXT }] })
   );
+  server.registerTool(
+    "read_portfolio_context",
+    {
+      title: "Read portfolio context",
+      description: "Turns the organisation's portfolio-context file (downloaded in the BICon app: Import/Export \u2192 'Download portfolio context') into the interview plan for THIS organisation: its own labels, help texts and rating notes for the sub-dimensions, which sub-dimensions are switched off (do not ask, not scored), its business units, categories, tags, skills (id + name) and initiatives (id + name), currency, discount rate and whether the EU-AI-Act module is on \u2014 plus a short contextId. Call it right after get_initiative_schema when the user provides the file, then pass `context: \"<contextId>\"` to assemble_initiative and export_initiative_file.",
+      inputSchema: readContextInputSchema
+    },
+    async ({ context }) => {
+      const resolved = resolveContext(context);
+      if (!resolved.ok) return text({ ok: false, errors: resolved.errors });
+      return text({ ok: true, ...buildInterviewPlan(resolved.context, resolved.contextId) });
+    }
+  );
   server.registerTool(
     "assemble_initiative",
     {
       title: "Assemble initiative",
-      description: "Turns a compact spec (metadata + named sub-dimension ratings + confidence per dimension + optional sections) into a fully-formed, contract-valid initiative. Mints the id and timestamps, DERIVES the four dimension scores (mean of subs) and validates against the API contract. Returns {ok, initiative, derivedScores, warnings, errors}. On errors, fix the listed fields and call again. Show derivedScores (and warnings) to the user before exporting.",
+      description: "Turns a compact spec (metadata + named sub-dimension ratings + confidence per dimension + optional sections, plus the organisation's `context` \u2014 contextId or file \u2014 when the user provided it) into a fully-formed, contract-valid initiative. Mints the id and timestamps (pass `id` only to UPDATE an existing initiative), DERIVES the four dimension scores (mean of the enabled subs) and validates against the API contract and \u2014 with context \u2014 the organisation's own lists and ids. Returns {ok, initiative, derivedScores, warnings, errors, contextId}. On errors, fix the listed fields and call again. Show derivedScores (and warnings) to the user before exporting.",
       inputSchema: compactSpecSchema
     },
     async (spec) => text(assembleInitiative(spec))
@@ -8953,22 +9349,30 @@ function createServer() {
     "export_initiative_file",
     {
       title: "Export initiative file",
-      description: "Assembles the SAME compact spec you passed to assemble_initiative and wraps the result in the app's single-initiative JSON envelope. Returns {ok, filename, json, importInstructions, derivedScores, warnings}. Save `json` under `filename`; the user imports it via Import/Export \u2192 Single initiative \u2192 'Add as new' \u2192 Confirm. sourceMode/language are recorded in the file; the app keeps AI-Act fields only while it is itself in AI mode.",
+      description: "Assembles the SAME compact spec (and context) you passed to assemble_initiative and wraps the result in the app's single-initiative JSON envelope. Returns {ok, filename, json, importInstructions, derivedScores, warnings}. Save `json` under `filename`; the user imports it via Import/Export \u2192 Single initiative \u2192 'Add as new' (or 'Update' when the spec carried an existing id or the name matches) \u2192 Confirm. sourceMode/language are recorded in the file (defaulting to the context's); whether the app keeps EU-AI-Act fields depends on the organisation's AI-Act module switch.",
       inputSchema: exportInputSchema
     },
     async (input) => {
       const parsed = compactSpecSchema.safeParse(input.spec);
       if (!parsed.success) return text({ ok: false, errors: formatIssues(parsed.error), warnings: [] });
-      const result = assembleInitiative(parsed.data);
-      if (!result.ok || !result.initiative) return text({ ok: false, errors: result.errors, warnings: result.warnings });
-      const envelope = buildEnvelope(result.initiative, { sourceMode: input.sourceMode, language: input.language });
+      const rawContext = input.context ?? parsed.data.context;
+      const result = assembleInitiative({ ...parsed.data, context: rawContext });
+      if (!result.ok || !result.initiative) return text({ ok: false, errors: result.errors, warnings: result.warnings, ...result.contextId ? { contextId: result.contextId } : {} });
+      const ctx = rawContext !== void 0 ? resolveContext(rawContext) : void 0;
+      const ctxData = ctx && ctx.ok ? ctx.context : void 0;
+      const envelope = buildEnvelope(result.initiative, {
+        sourceMode: input.sourceMode ?? ctxData?.portfolioMode,
+        language: input.language ?? ctxData?.language
+      });
       return text({
         ok: true,
         filename: input.filename ?? suggestFilename(result.initiative.name),
         json: JSON.stringify(envelope, null, 2),
         importInstructions: IMPORT_INSTRUCTIONS,
         derivedScores: result.derivedScores,
-        warnings: result.warnings
+        warnings: result.warnings,
+        ...result.contextId ? { contextId: result.contextId } : {},
+        update: parsed.data.id !== void 0
       });
     }
   );

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@bicon/mcp-composer",
-  "version": "0.1.7",
+  "version": "0.3.2",
   "description": "MCP server that helps an AI client compose a valid BICon portfolio initiative and hand it back as an import file (draft-first, no auth, no API calls).",
   "license": "UNLICENSED",
   "author": "BICon Establishment",
   "homepage": "https://www.bicon.digital",
-  "keywords": ["mcp", "model-context-protocol", "bicon", "portfolio", "eu-ai-act"],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "bicon",
+    "portfolio",
+    "eu-ai-act"
+  ],
   "type": "module",
   "bin": {
     "bicon-mcp-composer": "dist/index.mjs"