# Typed change specifications, v0.3 Typed business tools support explicitly configured owned projects. Original import tools target the configured default catalog. `solutionlink_list_contexts` is authoritative for the configured IDs, and native identity/owner/repository checks run again before changes. Adding a context to local configuration is a maintained configuration change requiring actual task authorization, not permission granted by an input file. Call `solutionlink_prepare_change` with `contextId`, `kind` and an absolute `specificationFile` path. The file is JSON data with no service names, executable expressions or arbitrary URLs to execute. Preparation performs reads and creates a local plan under `change-evidence//plan.json`. Inspect its preview, then apply with `solutionlink_apply_change` using that plan path. The user's existing authorization can cover the application; the tool does not impose a separate approval ritual. Preparation rejects unknown keys, ambiguous existing names, foreign IDs, invalid dates, nonfinite/negative financial inputs and invalid type relations. Existing records require explicit native IDs. Unlisted items and relations are preserved. No deletion, publication, native scenario-link write, currency conversion, automatic-to-manual timing conversion, or arbitrary HTTP call is exposed. A plan is not portable to another context or evidence root. The baseline is checked again before application. Every write has a before/after journal entry. A partial failure leaves `needs-inspection`; no blind replay or automatic rollback occurs. Re-applying a complete plan independently checks current native state and returns `alreadyApplied`, without creating another object. A later native change yields a conflict rather than silently accepting the old proof. ## TIPS ```json { "items": [ {"key":"driver","type":"trend","name":"Authoritative baseline (Draft)","description":"Proposed business objective, validate with the program.","categoryId":1,"relevant":true}, {"key":"pain","type":"challenge","name":"Manual reconciliation (Draft)","description":"OEM hypothesis, not an established customer finding.","categoryId":6,"relevant":true}, {"key":"initiative","type":"possibility","name":"Controlled engineering handoff (Draft)","description":"Proposed outcome, owner role and measurable acceptance gate.","categoryId":9,"relevant":true} ], "relations":[ {"from":"driver","to":"pain"}, {"from":"pain","to":"initiative"}, {"from":"initiative","to":""} ] } ``` Replace the placeholder with a measured ID before calling the tool. Each item can include `id` to explicitly update an existing custom editable item. Relations connect adjacent types only: Trend -> Challenge -> Possibility -> Solution. The tool merges edges and verifies `isRelation:true` on direct native reads. It does not infer native scenario associations from description text. ## Deployment ```json { "verificationRoiId":"", "phases":[{ "key":"pilot", "name":"Pilot and acceptance (Draft)", "description":"Owner role, scoped capabilities, dependencies and exit criteria.", "startDate":"2027-01-01", "endDate":"2027-03-31", "goLiveDate":"2027-04-01", "rollout":{ "name":"Pilot adoption (Draft)", "description":"Adoption and measurement after the phase gate.", "startDate":"2027-04-01", "endDate":"2027-12-31", "deployDays":90, "adoptionDays":30 } }], "assignments":[{"solutionId":"","phaseKey":"pilot"}] } ``` Existing phase and rollout edits require their explicit `id` fields. A new phase can use its single native auto-created rollout; the tool refuses an ambiguous default. Dates use YYYY-MM-DD and are converted for the native API. A rollout must begin after the phase gate and contain its adoption duration. An available native color is selected for new phases. Assignments require a measured existing `verificationRoiId`: the exercised per-solution phase read is `getSolutionsWithPhasesAndRollouts`. The tool checks the assignment's actual phase ID. It does not claim to synchronize all ROI deployment snapshots; the observed automatic synchronization endpoint failed with500. Read each affected ROI deployment plan separately when that propagation is part of the request. ## ROI ```json { "name":"Illustrative capacity case (Draft)", "description":"Explicit cohort, rate, disjoint benefit pools, recoverability, adoption, costs and exclusions. Capacity is not committed cash savings.", "currencyId":"", "projectConfiguration":{"discountRate":0.006,"endSimulationDate":"2029-12-31"}, "benefits":[{ "key":"data2027","name":"Data preparation capacity,2027 (Illustrative)", "description":"Formula and assumptions; no customer actuals asserted.", "amount":10000,"recurring":true,"unit":"month", "categoryId":"", "startDate":"2027-04-01","endDate":"2027-12-31" }], "costs":[{ "key":"implementation","name":"Implementation budget (Illustrative)", "description":"Planning allowance, not a vendor quote.", "amount":500000,"recurring":false,"unit":"day","expenseType":"OPEX", "categoryId":"", "startDate":"2027-01-01","endDate":"2027-01-01" }], "metrics":[{ "key":"potential","name":"Annual gross capacity potential (Illustrative)", "description":"Before recoverability and adoption; do not add again to timed benefits.", "amount":200000,"valueId":"", "categoryId":"" }] } ``` `id` on the ROI and each line/metric explicitly targets an existing object. Names alone are never adopted. Units: day/week/month/quarter/year. One-time lines use one date and unit `day`. The tool supports manual timing and constant annual currency potential metrics. It preserves existing formula metrics and checks an existing constant metric's native value relation before editing it. Currency conversion is not supported. Native default zero-cost templates are retained. The November 8 cost-update correction uses duration1 for an existing one-time cost so its native end date stays on the requested day. New one-time cost creation retains the previously exercised duration0 convention. A prior-day native end date fails readback and leaves the plan inspect-only. Prepare a fresh plan only after measuring partial effects; do not replay a failed journal. `projectConfiguration` affects **all simulations in the project** and is shown in the preview. In the exercised monthly ROI cashflows, discountRate is a rate per month, not an annual rate. The example0.006 means0.6%monthly, or7.4424%effectiveannual. Native storage rounded a submitted0.006434030110003455 (the8%annual equivalent) to0.006. The adapter now rejects a configuration normalization instead of claiming the requested rate was stored. Read back the actual value and label it explicitly. Omit this configuration when no shared change is intended. Annual potential metrics can contribute on top of manual timed benefits through allocation; reconcile total cashflow to prevent duplication. Build multiple cases with explicit inputs, or plan explicit updates to inspected cases; cloning is not a public v0.3 tool. Read current native currency/category options from the prepared plan's baseline, or the native application. An invalid category/currency is rejected before application. Do not invent UUIDs from labels. ## Financial checks `solutionlink_evaluate_roi` accepts explicit chronological cashflows and an annual discount rate. It returns totals, `(benefit-cost)/cost`, dated NPV using actual days/365.25 and payback at the observed period boundary. It returns no assumed population, savings or customer facts. `solutionlink_read_business_case` with `includeForecasts:true` independently calculates native equal-month,end-of-period NPV from the monthly stored rate, with the first cashflow at period1. It reports the effective annual equivalent, a separate actual-date datedNPV reference, native comparison and cashflow-total reconciliation. An annual rate accidentally entered as a monthly rate can cause negative NPV. Native storage may round the monthly equivalent; compare the actual stored rate with the intended rate and disclose the difference. Never alter cashflows or hide the stored rate just to force agreement. ## Authentication and connection The dedicated approved Edge profile is used internally. No credentials, tokens or browser cookies are tool arguments. Renew interactively only if effect-based status fails. This remains an observed native web-client integration, not a supported headless Siemens OAuth contract. The configured server is launched from source on a fresh stdio connection. If the current Codex chat advertises only the original six tools, reconnect the MCP or use `node scripts/call.mjs ` from the registered server root. `node scripts/call.mjs list` lists the freshly launched tool surface. Do not terminate the desktop app to refresh tools.