@aifabrix/builder 2.53.1 → 2.55.0

package/templates/agent-kit/skills/aifabrix-connected-system/references/contract-checklist.md

@@ -0,0 +1,40 @@
+# Connected System contract checklist
+
+Use after BID apply / repair and before READY or BUILT.
+
+## Exposed
+
+`exposed` must include `filterable`, `readonly`, `required`, `profiles` (`default` plus capability keys), and `schema`.
+Every `filterable` field needs `metadataSchema.properties.<field>.filter: true` (usually `index: true`).
+Schema-only stubs are not BUILT. `labelKey` prefers login identity before display name.
+
+## Foreign keys
+
+Challenge every storage and view DS. Empty `foreignKeys` on business facts/children is a defect.
+FK lives on the child only: `fields` = carrier on this DS, `targetDatasource` = parent storage, `targetFields: ["externalId"]`.
+Do not add reverse FKs on the parent. Same-DS `parentId` is a field, not a self-FK.
+Allowed omit (changelog): config, logs, documented in-system root, self-tree.
+Revalidate after BID apply: `relationships` must land on the `from` EDS.
+
+## Viewpoints
+
+Partitioned aggregates and current-state person composition (person + current manager + current location/org when those storage DS exist) need FK + `dimensions` (`type: fk`) + usually `abac.applicability: required`.
+SQL must alias the grant column to the catalog dimension key before `GROUP BY`.
+Protection SSOT stays on the storage DS; views inherit. Never bulk-sync a view as storage.
+Do not flatten person+employment+org into one storage DS to avoid a current-state view.
+
+## RBAC / ABAC
+
+`roles[].value` = active COM catalog key from `aifabrix role list`. Map groups with `identity role set-groups`.
+Local ABAC filters the physical column named after the dimension key.
+Do not invent dimensions on `entityType: none` orchestration datasources.
+
+## CIP mappings
+
+Prefer `fieldMappings`, FK, and composite `primaryKey` for reshape. Minimal prep only for broken export JSON.
+CIP executes certified capability surfaces; it does not decide continuation. COM does not own continuation.
+Capabilities execute; they do not decide.
+
+## Format and changelog
+
+`aifabrix convert` is for `integration/` and `builder/` only. Manual EDS edits need `INTEGRATION_CHANGELOG.md`. File generic CLI gaps in `BUILDER_IMPROVEMENT_FINDINGS.md`.

package/templates/agent-kit/skills/aifabrix-connected-system/references/delivery-gates.md

@@ -0,0 +1,54 @@
+# Delivery gates
+
+Public docs: https://docs.aifabrix.ai/docs/build-ai-ready-systems-validate-test-cli-workflow
+
+## Create
+
+BID preferred:
+
+```bash
+aifabrix integration-definition validate ./integration/<systemKey>/bid.json
+aifabrix integration-definition apply ./integration/<systemKey>/bid.json --dry-run
+aifabrix integration-definition apply ./integration/<systemKey>/bid.json
+```
+
+Live OpenAPI: `aifabrix wizard --config integration/wizard-configs/<system>.yaml`
+
+Then `aifabrix repair <systemKey> --rbac --expose` (add `--auth` when credentials exist).
+Match workspace format with `aifabrix convert` on `integration/` only.
+
+If `integration/<systemKey>/deploy.js` exists, you may run it as the publish ladder.
+
+## Validate vs publish
+
+| Command | Meaning |
+| --- | --- |
+| `aifabrix validate <systemKey>` | Local package |
+| `aifabrix upload <systemKey>` | Draft application. CLI “Published” is not CS publish |
+| `aifabrix deploy <systemKey>` | Controller deploy = publish. Always run after upload |
+| `aifabrix show <systemKey> --online` | Dataplane **published** is truth |
+
+## Tests (separate results)
+
+| Layer | Command |
+| --- | --- |
+| Structure | `aifabrix datasource test <datasourceKey>` |
+| Pipeline | `aifabrix datasource test-integration <datasourceKey>` |
+| Live | `aifabrix datasource test-e2e <datasourceKey> --app <systemKey>` |
+| Static seed | `aifabrix datasource load <datasourceKey> --app <systemKey>` |
+
+Never mark live E2E pass when it did not run.
+
+## Identity and protection order
+
+1. `aifabrix auth status`
+2. Catalog roles + fixtures + `identity apply` / `identity sync` / `role set-groups`
+3. Load partitioned fixtures
+4. `aifabrix protection upload <sourceStorageDs> --sync` (storage DS, not the view)
+5. `aifabrix verify-governance --pack ./scenarios/….yaml` with `defaults.limit` ≤ 1000
+
+`builder/dataplane/rbac.yaml` is dataplane **app** RBAC, not customer CS roles.
+
+## Missing vendor `kv://`
+
+Do not AskQuestion for secrets. Resolve, empty generated Key Vault placeholders, **upload**, print `{dataplaneUrl}/connected-systems/{systemKey}?tab=authentication`, stop.

package/templates/agent-kit/skills/aifabrix-connected-system/references/production-safety.md

@@ -0,0 +1,35 @@
+# Production safety
+
+Many organizations have only a production vendor system. Assume that by default for live OpenAPI.
+
+System-specific limits (subject, partition, credential status, PII) live only in `integration/<systemKey>/README.md`.
+
+## Credential-deferred certify
+
+When the vendor secret is not yet in `kv://`:
+
+| Layer | Required |
+| --- | --- |
+| Package validate | Yes |
+| Structure test | Yes |
+| Integration / pipeline test | Yes when entityType supports it |
+| AI / Trust / ops | Yes where runnable without vendor secret |
+| Governance packs | Yes when subjects + fixtures exist offline; else skip-with-reason |
+| Live E2E / vendor-auth probe | Skip with reason |
+
+Publish may be **PASS_WITH_SKIPS** only for those allowed live/static skips. Never fake an E2E pass.
+Secret present and storage sync fails → FAIL / NEEDS_FIXES, never skipped.
+
+## Mutation blast radius
+
+1. README names exactly one approved test subject (stable identity keys).
+2. Create / update / delete may target only that subject.
+3. Never mutate “first list row” or a broader population.
+4. Prefer read-only E2E until writes and the subject are confirmed.
+5. Mutating E2E without a designated subject → BLOCKED before the call.
+
+## Agent
+
+Read the integration README before live or mutating tests.
+Do not invent a second safe subject without customer approval recorded in that README.
+Missing `kv://`: upload draft first, print the Authentication tab URL, stop.

package/templates/agent-kit/skills/aifabrix-connected-system/scripts/reserved-system-key.js

@@ -0,0 +1,19 @@
+/**
+ * Reserved Connected System key prefixes.
+ * @fileoverview Deterministic reserved-key check for customer delivery skills
+ */
+
+'use strict';
+
+/**
+ * @param {string} key Connected System key
+ * @returns {boolean} True when the key uses a reserved ra- or ek- prefix
+ */
+function isReservedSystemKey(key) {
+  const value = String(key || '')
+    .trim()
+    .toLowerCase();
+  return value.startsWith('ra-') || value.startsWith('ek-');
+}
+
+module.exports = { isReservedSystemKey };

package/templates/agent-kit/skills/aifabrix-plan/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: aifabrix-plan
+description: >
+  Turn a customer business specification into a delivery plan with a fixed
+  section order. Challenges missing facts; does not invent entities, roles,
+  or authority. Use before Connected System validate/build. Do not use for
+  Builder product source changes or COM architecture explanations.
+---
+
+# aifabrix-plan
+
+Input: business specification and optional `systemKey`.
+Output: one delivery plan from [plan-template.md](references/plan-template.md).
+
+Score completeness with [challenge-checklist.md](references/challenge-checklist.md).
+Next-step interaction: [interaction.md](references/interaction.md).
+Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
+
+## Sequence
+
+```text
+specification → aifabrix-plan → PLAN_READY | NEEDS_DECISIONS | BLOCKED
+```
+
+Do not start Connected System validate until **PLAN_READY** and the user picks `next-yes`.
+
+## Workflow
+
+1. Collect the spec the user named. Do not mine platform repos as the spec.
+2. Inventory without adding: purpose, sources, entities, relationships, role labels, operations, Viewpoints, Evidence, identity join. Missing sections → `TBD` plus an Open question.
+3. Challenge required rows. AskQuestion every MISSING required row. Authority and identity cannot be guessed.
+4. Write or update `.cursor/plans/{major}.0-{slug}.plan.md` using the template H2 order. Same capability updates in place.
+5. Report status and path. On PLAN_READY, offer validate — do not run it without `next-yes`.
+
+## Hard stops
+
+- Empty spec, reserved `ra-` / `ek-` key, or contradictory identity → **BLOCKED** (no challenge prompts).
+- Unmapped catalog roles → NEEDS_DECISIONS; never invent `*-reader`.
+- “Already connected” is FACT only if `integration/<key>/` exists in this workspace.
+- No implementation before the project plan gate.
+
+```bash
+aifabrix auth status
+aifabrix role list --page-size 1000
+```
+
+If still unauthenticated after refresh, draft the plan; catalog-role rows stay MISSING until the user runs `aifabrix login`.
+
+## Trigger examples
+
+- Turn this customer specification into an implementation plan

package/templates/agent-kit/skills/aifabrix-plan/references/challenge-checklist.md

@@ -0,0 +1,108 @@
+# Challenge checklist (business spec → plan)
+
+Mark every row **FACT** | **ASSUMPTION** | **MISSING**.  
+Do **not** invent FACT. ASSUMPTION is allowed only when the spec implies it and you name the risk.
+
+`PLAN_READY` requires every **Required** row FACT or a **locked decision** in the plan (not a silent guess).
+
+## AskQuestion (mandatory when a row is MISSING)
+
+Do **not** only list gaps in chat. For every **Required** row marked MISSING, and every **Challenge if missing** row that says Ask (C1, C2, D-edit, C4), call the **AskQuestion** tool in the same turn as the `/cust-0-plan` report. Batch into **one** AskQuestion (multiple `questions[]`). Do not invent FACT from a skipped prompt.
+
+Shared option ids: `challenge-fact` (user will supply via Other), `challenge-assumption` (lock ASSUMPTION + who must confirm), `challenge-open` (leave NEEDS_DECISIONS).
+
+```json
+{
+  "title": "Plan challenges",
+  "questions": [{
+    "id": "challenge-B4",
+    "prompt": "B4 Process owner is MISSING.\n\nPLAN_READY needs a named owner or a locked ASSUMPTION with who must confirm.",
+    "options": [
+      { "id": "challenge-fact", "label": "I will provide the FACT (use Other)" },
+      { "id": "challenge-assumption", "label": "Lock as ASSUMPTION (name who must confirm in Other)" },
+      { "id": "challenge-open", "label": "Leave open — NEEDS_DECISIONS" }
+    ]
+  }]
+}
+```
+
+Substitute `challenge-{rowId}` and the row’s **PLAN_READY when** / **If missing** text. For **C1**, options are 2–3 impact models (prefer hours saved) plus `challenge-open` — do not invent a FACT measure. For **C2** / **D-edit**, ask once with the same three shared ids (D-edit default if they pick assumption: enabled while Open).
+
+Do **not** AskQuestion challenges on **BLOCKED** (empty spec / reserved key / contradictory identity). Skip rows already FACT or locked.
+
+## Business case (Required)
+
+| # | Item | PLAN_READY when |
+| --- | --- | --- |
+| B1 | Purpose | One paragraph: what improves and for whom |
+| B2 | Expected outcome | What “done” looks like (experience + proof), not only “system exists” |
+| B3 | In / out of scope | Explicit out-of-scope (do not grow the spec) |
+| B4 | Process owner | Named owner **or** ASSUMPTION with “who must confirm” |
+| B5 | Business roles | ≥1 role with **can** and **cannot** (authority, not prompts) |
+| B6 | Prove story | How we will show authority change and refusals (demo / VAL / ATTACK) |
+
+## Delivery (Required)
+
+| # | Item | PLAN_READY when |
+| --- | --- | --- |
+| D1 | Connected System key(s) | kebab-case; not `ra-` / `ek-`; existing package vs **new** stated |
+| D2 | Authoritative source(s) | Each source: already connected in **this** workspace, to-be-connected, or internal-only |
+| D3 | Entities + identity | Every entity has a stable id; **no name-string PK**; identity join named if “current user → entity” |
+| D4 | Foreign keys | Every business fact/child has joins **on the child (`from`) only**; do **not** add reverse FKs on the parent; self-`parentId` is a field, not a same-DS FK; config/logs/root/self-tree omit only with rationale (skill `aifabrix-foreign-keys-challenge`) |
+| D5 | Catalog roles | Spec role **labels** mapped to COM keys from `aifabrix role list` — never invent `*-reader` |
+| D6 | Operations | List/submit/view/admin from the spec only; no extra authority |
+| D7 | Viewpoints vs raw | Aggregates/results use named Viewpoints; raw rows not exposed through result assistants. Person+employment+org packages include a **current-state person view** (person + current manager + current location/org) unless explicitly out of scope (`viewpoint-fk-dimensions.mdc`) |
+| D8 | Validations | Happy path **and** refusal/attack cases (VAL-* / ATTACK-* or equivalent) |
+| D9 | Evidence | What Evidence must prove (actor, role, rule, success/refusal) |
+| D10 | Historical vs current | Current eligibility from source of record; historical Evidence is **not** cascade-deleted |
+
+## Challenge if missing (may stay ASSUMPTION)
+
+| # | Item | If missing |
+| --- | --- | --- |
+| C1 | Success measures | Offer 2–3 models (prefer hours saved / participation); do not invent FACT |
+| C2 | Audience / personas | Ask once |
+| C3 | Language handling | Original = Evidence; derived translation/normalization = Knowledge; never overwrite original |
+| D-edit | Optional update-while-open | Ask; default **ASSUMPTION: enabled while Open** if spec says “if editing is enabled” |
+| C4 | Admin operators | Who Open / Close / Validate / Release — named role, not “the AI” |
+| C5 | Catalog `resourceType` | Confirm at BID apply; do not guess silently |
+| C6 | Designated test subject | Required before mutating live E2E (`production-system-safety.mdc`) — README later |
+| C7 | Credential posture | Secret present vs deferred — README later; do not block plan draft |
+| C8 | Role Assistant packages | `ra-<catalogRole>` only after D5; one RA per catalog role that performs work |
+| C9 | Supported languages | Spec may say “any supported”; list known ones as ASSUMPTION |
+| C10 | Taxonomy predefined vs discovered | Spec default: discovered unless owners lock a list |
+| C11 | Identity uniqueness | Email (or equivalent login identity) is **unique in business fact** — `index` + `filter` + identity join. EDS schema has no `unique` flag; prove uniqueness after **sync** (duplicates = data-quality fail). Do not invent a schema property. |
+| C12 | Live pull / sync | Live OpenAPI with secret stored: E2E **sync** (or `datasource load` for static) must pass. Sync fail with secret present is **FAIL**, not PASS_WITH_SKIPS. |
+| C13 | Governance packs | People/HR CS or any DS with dimensions: `scenarios/` + fixtures **before** claiming push ready. Missing packs = **FAIL** unless README says governance N/A. |
+
+## Must not invent
+
+- Extra Business Roles, operations, or “admin backdoors”
+- Extra entities or fields not in the spec
+- Vendor/source fields beyond the **approved** source scope
+- COM catalog role keys that are not on `aifabrix role list`
+- Treating display names as foreign keys
+- Adding FKs on **both** sides of a relationship (parent and child)
+- Enforcing BR-* only in UI or prompt text
+- Publishing results automatically when a process **closes** if the spec requires explicit release
+- Cascade-delete of historical Evidence when source records become inactive
+- Putting tenant ids, secrets, or designated subjects into `.cursor/rules` / skills / commands
+
+## Classification hints
+
+| Spec language | Classify as |
+| --- | --- |
+| “already connected” | FACT only if the package exists under `integration/` **in this workspace**; else MISSING (to-be-connected) |
+| Role names like “Employee”, “HR Manager” | Labels — **must** map to catalog keys (D5) |
+| “AI-derived” / themes | Knowledge, versioned, not authoritative fact |
+| Original free text | Evidence — immutable |
+| Aggregate leaderboards / maps | Viewpoints — not storage dumps |
+| Self-nomination / unique / window | Governed business rules (BR-*) |
+
+## Status
+
+| Status | Meaning |
+| --- | --- |
+| **PLAN_READY** | Required rows FACT or locked; remaining opens have owner; safe to `/cust-1-validate` |
+| **NEEDS_DECISIONS** | Required MISSING; **still write** the draft plan; do **not** start `/cust-1-validate` |
+| **BLOCKED** | Empty spec, reserved `system-key`, contradictory identity (name as PK with no join), or “invent authority” requested |

package/templates/agent-kit/skills/aifabrix-plan/references/interaction.md

@@ -0,0 +1,34 @@
+# Phase and result interaction
+
+Use structured questions. Do not start the next phase from chat prose alone.
+
+## After success
+
+Offer the next eligible phase. Proceed only on `next-yes`.
+
+Shared option ids: `next-yes` · `next-no` · `next-stop`.
+
+| Completed | Next offer |
+| --- | --- |
+| aifabrix-plan PLAN_READY | connected-system validate |
+| connected-system READY | connected-system build |
+| connected-system BUILT | connected-system publish |
+| connected-system PASS or PASS_WITH_SKIPS | archive (separate) and/or prove validate |
+| prove READY / BUILT / UPDATED | prove next phase |
+| prove PASS or PASS_WITH_SKIPS | iterate validate/build |
+
+Archive is a distinct user decision (`archive-yes` / `archive-no`). Never archive as a side effect of PASS.
+
+## On gaps
+
+- NEEDS_DECISIONS: AskQuestion challenge rows. No `cust-next`.
+- BLOCKED / FAIL / NEEDS_FIXES / ABORTED: do not offer the next phase as if success.
+
+## Phase detection (connected-system and prove)
+
+1. Explicit phase from the user
+2. Active plan and package state
+3. Safe next eligible phase
+4. Ask once if ambiguous
+
+Never silently run the following phase after success.

package/templates/agent-kit/skills/aifabrix-plan/references/plan-template.md

@@ -0,0 +1,182 @@
+# Cursor plan template (mandatory section order)
+
+Every `/cust-0-plan` output uses **this order**. Do not rename, skip, or reorder H2 sections. Empty sections get `TBD` plus an Open-question id — never omit the heading.
+
+File: `.cursor/plans/{major}.0-{slug}.plan.md`  
+`{major}` = next integer after existing plans (including `done/`). `{slug}` = kebab from capability name / proposed `system-key`.
+
+## Frontmatter (exact keys)
+
+```yaml
+---
+name: {major}.0-{slug}
+overview: |
+  {2–4 lines: purpose + systems + proof. No secrets.}
+todos:
+  - id: lock-open-questions
+    content: Close Open questions (or defer with owner) until PLAN_READY
+    status: pending
+  - id: map-catalog-roles
+    content: Map spec role labels to COM catalog keys (aifabrix role list)
+    status: pending
+  - id: author-bid
+    content: Author BID (or wizard config) for each new Connected System key
+    status: pending
+  - id: cust-1-validate
+    content: /cust-1-validate <system-key> → READY
+    status: pending
+  - id: cust-2-build
+    content: /cust-2-build <system-key> → BUILT
+    status: pending
+  - id: cust-3-push
+    content: /cust-3-push <system-key> → PASS or PASS_WITH_SKIPS
+    status: pending
+  - id: viewpoints-fk-dims
+    content: Viewpoints have FK + dimensions + ABAC (not raw storage dumps)
+    status: pending
+  - id: identity-fixtures
+    content: Catalog roles + fixtures/groups (skill aifabrix-identity-rbac) — push-scoped
+    status: pending
+  - id: ra-packages
+    content: Role Assistant packages ra-<catalogRole> after CS published
+    status: pending
+  - id: cust-biz-1-validate
+    content: /cust-biz-1-validate — prove-ready scope + learning.md
+    status: pending
+  - id: cust-biz-2-build
+    content: /cust-biz-2-build — demo / Knowledge / candidate Evidence / tests
+    status: pending
+  - id: cust-biz-3-prove
+    content: /cust-biz-3-prove — happy + refusal; Evidence summary
+    status: pending
+status: draft   # draft until PLAN_READY, then active
+isProject: false
+---
+```
+
+Duplicate `author-bid` / `cust-1-validate` / `cust-2-build` / `cust-3-push` **per additional** `system-key` (`author-bid-personio`, …). Do not add extra todo ids unless the spec requires a named workstream.
+
+When `/cust-0-plan` status is **NEEDS_DECISIONS**, keep `lock-open-questions` pending and `status: draft`. When **PLAN_READY**, set `status: active` and mark `lock-open-questions` completed if none remain.
+
+## Body (copy all H2s)
+
+```markdown
+# {major}.0 — {Capability title}
+
+**Plan status:** PLAN_READY | NEEDS_DECISIONS | BLOCKED  
+**Proposed system-key(s):** …  
+**Authoritative source(s):** … (in this workspace / to-be-connected / internal)  
+**Role Assistant(s):** `ra-<catalogRole>` (after D5) or TBD  
+**Operational SSOT (after build):** `integration/<system-key>/README.md`  
+**Public docs:** [Build AI-ready systems](https://docs.aifabrix.ai/docs/build-ai-ready-systems)
+
+## Goal
+
+{Business purpose — verbatim spirit of the spec. Why this capability exists.}
+
+## Non-goals
+
+- {From spec out-of-scope}
+- Extra authority, entities, or source fields not in the spec
+- Prompt-only enforcement of business rules
+
+## Authoritative sources
+
+| Source | Role | In this workspace? | Approved fields only |
+| --- | --- | --- | --- |
+| … | identity / facts / … | yes path / **no — to-be-connected** | list |
+
+Least privilege: the capability may retrieve **only** fields the spec approves.
+
+## Business entities
+
+For each entity: key fields, identity, source. `heroId`-style keys **resolve** to the source identity — they do not create a second master.
+
+## Relationship model
+
+ASCII diagram from the spec. Then the FK list. Call out dual relationships to the same entity (e.g. voter + nominee).
+
+## Foreign-key integrity
+
+- Current eligibility = source of record
+- Historical Evidence keeps stable FKs
+- **Do not** cascade-delete history when a source row becomes inactive
+
+## Business roles
+
+| Spec label | COM catalog key | Can | Cannot |
+| --- | --- | --- | --- |
+| … | from `aifabrix role list` or **TBD** | … | … |
+
+If the label is not a catalog key → Open question (do not invent).
+
+## Language handling
+
+| Artifact | Kind | Rule |
+| --- | --- | --- |
+| Original human text | Evidence | Never overwrite |
+| Normalized / translated text | Derived Knowledge | Separate field |
+
+## Core business rules
+
+Table `BR-ID` | Rule | Enforced as (governed rule, not prompt).
+
+## Governed operations
+
+Grouped by role. Inputs / outputs / window. No extra ops.
+
+## Result Viewpoints
+
+Each viewpoint: returns, **does not return** (no voter identities, no raw text, …). Viewpoints are governed aggregates — not dumps of join tables.
+
+## Validation cases
+
+Keep spec IDs (`VAL-001`, …). These become acceptance tests.
+
+## Security / attack validations
+
+Keep spec IDs (`ATTACK-001`, …). Expected: denied / rejected by BR-*.
+
+## Evidence to capture
+
+Actor, Business Role, operation, authority result, rule version, success/refusal, source, Viewpoint, taxonomy version. Include the spec’s **Evidence summary** shape if given.
+
+## Identity join (most important relationship)
+
+Authenticated person → catalog role → business entity → source record. Nominations (or equivalent) reference **ids**, never display names.
+
+## Locked decisions
+
+| # | Question | Decision | Date |
+| --- | --- | --- | --- |
+| 1 | … | … | … |
+
+## Open questions
+
+| ID | Question | Blocks | Owner |
+| --- | --- | --- | --- |
+| Q1 | … | PLAN_READY / build / push / prove | … |
+
+## Delivery mapping
+
+| Track | Command | When |
+| --- | --- | --- |
+| CS | `/cust-1-validate` → `/cust-2-build` → `/cust-3-push` | After PLAN_READY; one ladder per new `system-key` |
+| PoC | `/cust-biz-1-validate` ↔ `/cust-biz-2-build` ↔ `/cust-biz-3-prove` | After CS published (or explicit waiver) |
+
+Existing connected sources: reuse package; do not duplicate the employee/master.
+
+## Success criteria
+
+Numbered, testable. Include authority-change demo if the spec has one (same person, new role, same interface).
+
+## Next
+
+- **PLAN_READY** → AskQuestion `cust-next` → `/cust-1-validate <system-key>` on **`next-yes`**
+- **NEEDS_DECISIONS** → AskQuestion challenge rows ([challenge-checklist.md](challenge-checklist.md)); lock answers into this file; do not start `/cust-1-validate`
+- **BLOCKED** → stop; do not author BID
+```
+
+## Rewrite rule
+
+Re-running `/cust-0-plan` for the same capability **updates** this file (same `{major}.0-{slug}`). Do not mint a new major for Q&A.

package/templates/agent-kit/skills/aifabrix-prove/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: aifabrix-prove
+description: >
+  Prove a business case on a published Connected System and Role Assistant.
+  Updates learning, keeps candidate Evidence separate from certified Evidence,
+  and iterates validate, build, and prove. Do not use for Builder product
+  source changes or to skip Connected System publish.
+---
+
+# aifabrix-prove
+
+Phases: `validate` | `build` | `prove`.
+Loop: validate ↔ build ↔ prove ↔ learn.
+
+`READY` means prove-ready, not permission to stop authoring. Build may run without READY.
+
+Every phase **must** update [learning-template.md](references/learning-template.md).
+Evidence rules: [evidence-lifecycle.md](references/evidence-lifecycle.md).
+Demo shape: [demo-template.md](references/demo-template.md).
+Next-step: [interaction.md](../aifabrix-plan/references/interaction.md).
+Host runtimes (local vs SSH): [hosts.md](../shared/hosts.md).
+
+## Keys
+
+Connected System: same resolution as `aifabrix-connected-system`.
+Role: existing COM catalog key; on disk `role-assistant/ra-<roleKey>/`.
+
+CS must be published (`deploy` + `show --online`) before live prove. Upload-only draft is BLOCKED for prove.
+
+## Validate
+
+Clarify scope and unknowns. Classify MISSING rows. Drafting may continue offline.
+
+## Build
+
+Repeatable: demo, Knowledge, candidate Evidence, tests. Do not refuse because validate is not READY.
+
+## Prove
+
+Run assistant tests. Record observations and gap owner (`none` | `product-gap` | `missing-customer-fact` | `scope-decision`).
+Happy + safe-stop coverage for authority scenarios.
+Never report candidates as certified.
+
+## Narrative
+
+Prefer public product language from https://docs.aifabrix.ai and, when present, sibling website masters. Do not invent slogans. AI has no authority of its own.
+
+## Trigger examples
+
+- Prove this business case and update learning

package/templates/agent-kit/skills/aifabrix-prove/references/demo-template.md

@@ -0,0 +1,65 @@
+# demo.md template (Finnish, customer-facing)
+
+**Path:** `role-assistant/ra-<roleKey>/demo/demo.md`
+
+Feeds PowerPoint / ChatGPT / Gamma. Business language only — no MCP/API how-to.
+
+**Narrative SSOT:** `aifabrix-docs/anchor-docs/web-site/` — especially `evaluate.md`, `homepage.md`, `solutions.md`, `platform.md`, `use-cases.md`. Do not invent slogans; use pillar language from those masters (Enterprise Knowledge, Operational Trust, Role Assistants, Evidence Fabrix). AI has no authority of its own.
+
+## Outline
+
+```md
+# PoC-demo — <prosessi / rooli>
+
+## 1. Ongelma (nykytila)
+- Mitä työtä tehdään tänään (raportit, Excel, ad-hoc kyselyt)?
+- Kuka odottaa vastausta? Kuinka kauan?
+- Missä luottamus pettää (väärä data, väärä näkyvyys)?
+
+## 2. Mitä todistamme
+- Yksi prosessi, yksi rooli, mitattava lopputulos
+- Omistaja:
+- Onnistumisen mittarit (FACT vs oletus merkitty):
+
+## 3. Miksi AI Fabrix
+- Neljä pilaria (solutions/platform): Enterprise Knowledge → Operational Trust → Role Assistants → Evidence Fabrix
+- Luotettu liiketoimintakonteksti (ei raakadata-dumppi); AI:lla ei omaa toimivaltaa
+- Oikeat ihmiset näkevät / päättävät vain oman organisaatiovaltuutuksensa rajoissa
+- Role Assistant + Evidence — tarkastettavissa (evaluate.md / architecture-evidence-observability.md)
+- Lähde: `aifabrix-docs/anchor-docs/web-site/` (ei vapaa markkinointimuisti)
+
+## 4. Demo-skenaariot
+### <DOMAIN>-010 — <lyhyt nimi>
+- Kysymys (liiketoimintakieli):
+- Odotettu lopputulos:
+- Mitä ei saa tapahtua (safe stop / refusal):
+- Liittyvä rooli / oikeusraja:
+
+### <DOMAIN>-020 — …
+…
+
+## 5. Mitattava hyöty
+- Säästetyt tunnit / kierros / virheet — FACT vs oletus
+- Miten mitataan PoCissa
+
+## 6. Mitä ei tehdä tässä PoCissa
+- …
+
+## 7. Päätös (Day 10 -kehys)
+- Proceed / Refine / Stop — kriteerit
+```
+
+## English scenario map (for agents; keep out of customer slide deck)
+
+For each Finnish scenario, maintain in `learning.md` scenario map:
+
+| Field | English |
+| --- | --- |
+| scenarioId | e.g. FIN-010 |
+| intent | One sentence business intent |
+| happyExpected | What success looks like |
+| safeStopExpected | Refusal / authority / insufficient info |
+| capabilitiesInScope | Approved capability keys if known |
+| evidenceCandidate | Path under `evidence/candidates/` or — |
+| testHappy | YAML path |
+| testSafeStop | YAML path |