@ztothez/design-engineering 2.0.0

package/knowledge-base/design-intelligence/interaction-recovery-verification.md

@@ -0,0 +1,72 @@
+# Interaction And Recovery Verification
+
+Use this protocol when a browser product contract needs executable evidence for task progress,
+failure recovery, keyboard operation, exports, or offline behavior. It extends rendered runtime
+verification; it does not establish usability, comprehension, backend availability, or a human
+review outcome.
+
+## Compatibility Boundary
+
+Existing journey suites remain version `1.0`. A version `1.1` suite requires an `interaction`
+declaration for every journey. Product contracts that rely on those declarations use version `1.2`.
+Do not upgrade an older benchmark merely to make it appear interaction-qualified. Add a new versioned
+contract only when the product owner supplies the applicable task, state, and recovery evidence.
+
+## Journey Declaration
+
+Each version `1.1` journey declares an `interaction` object:
+
+```json
+{
+  "task": "record-decision",
+  "phases": ["primary", "recovery"],
+  "applicableStates": ["disconnected", "error"],
+  "keyboard": true,
+  "export": true,
+  "offline": true
+}
+```
+
+`phases: ["primary"]` requires `start` and `success` checkpoints. `phases: ["recovery"]`
+requires `failure` and `preserved-state` checkpoints. Each declared applicable state requires a
+checkpoint of the same name. Keyboard, export, and offline declarations additionally require
+their matching checkpoint.
+
+A checkpoint immediately follows the assertion that establishes it:
+
+```json
+{ "action": "expectValue", "selector": "#draft", "value": "priority-record-01" },
+{ "action": "checkpoint", "checkpoint": "preserved-state" }
+```
+
+The verifier retains the checkpoint number, the preceding assertion number, and the observation in
+the runtime report. Checkpoints are not free-form prose and cannot be used to declare evidence that
+the preceding browser assertion did not observe.
+
+## Executable Actions
+
+Use `press` before a `keyboard` checkpoint. Use `expectDownload` before an `export` checkpoint.
+Use `setNetwork` with `state: "offline"` before an `offline` checkpoint, then assert the visible
+disconnected recovery state. A disconnected state that is only declared by a product scenario does
+not prove the browser was offline; keep those facts separate.
+
+Verify only states that the current product contract and data model make applicable: `loading`,
+`empty`, `partial`, `stale`, `disconnected`, `unauthorized`, and `error`. Do not add synthetic
+states to satisfy coverage. If the browser cannot automate a declared behavior, retain it as a
+verifier limitation and keep the product result `unverified`; it is neither a pass nor a product
+failure.
+
+## Contract Binding
+
+A version `1.2` product contract requires a version `1.1` journey suite. Every browser task
+journey must declare the same task identifier. Primary tasks require a primary phase; tasks whose
+recovery is required also require a recovery phase. The contract validator rejects missing or
+mismatched coverage before a quality gate can treat browser output as task evidence.
+
+## Evidence Boundary
+
+Runtime evidence proves that a declared browser sequence completed in the configured environment.
+It does not prove representative users can recover, that all real network conditions behave the
+same way, that an export is semantically correct beyond the retained artifact, or that an identity
+or authorization system is secure. Never generate a human or representative-user attestation from
+these results.

package/knowledge-base/design-intelligence/interface-trust.md

@@ -0,0 +1,103 @@
+# Interface Trust And Data Provenance
+
+Use this module for interfaces that display operational state, external data, generated analysis, cached or imported results, health claims, environment labels, or exports. Create an `interface-trust.yaml` from `interface-trust.template.yaml` before implementing consequential actions or operational status UI.
+
+## Trust Boundary
+
+Treat four facts as separate state dimensions:
+
+```text
+dataMode: demo | live | hybrid | imported | cached
+connection: unknown | checking | connected | degraded | disconnected
+resultOrigin: live | simulated | imported | cached
+freshness: status plus offset timestamp plus IANA timezone
+```
+
+A working interface does not prove a working backend. A successful local simulation does not prove external connectivity. A connected health endpoint does not prove that the displayed result came from that endpoint. Bind each claim to the source that establishes that exact fact.
+
+## Step 1: Inventory Sources
+
+Give every source a stable identifier, kind, authority, description, and evidence location when available.
+
+- Use `runtime-probe`, `authenticated-api`, or `runtime-processing` only for facts observed at runtime. Record `checkedAt` with an offset.
+- Use `demo-fixture` or `local-simulation` for demonstration content. Never relabel it as live output.
+- Use `import-record` for imported data and `cache-record` for cached data. Preserve their original timestamps and scope.
+- Use `configuration` for deployment or environment declarations. Configuration may identify an intended environment but cannot prove service availability.
+- Use `user-input` only for values explicitly supplied by the user. Do not convert user intent into a verified external fact.
+
+Do not place credentials, realistic secret placeholders, tokens, passwords, or API keys in the contract, UI, examples, source, or screenshots. Declare only an approved credential source such as environment configuration, a secret manager, OAuth, or runtime user entry.
+
+## Step 2: Define Product States
+
+Model at least one concrete state for each required scenario:
+
+1. `demo`: demo data with simulated result origin.
+2. `live`: runtime-derived live mode, connected state, and live result origin.
+3. `fallback`: a failed or degraded primary path producing an explicitly non-live result with limitations.
+4. `stale`: cached or imported content whose age is explicit.
+5. `disconnected`: runtime-derived disconnection with preserved context and a recovery action.
+
+For each state, declare data mode, connection, result availability and origin, freshness, environment, scope, limitations, sources, and recovery action where applicable. Use `unknown` rather than guessing. Use `checking` while evidence is pending. Keep partial and stale content usable, but never visually merge it with current live output.
+
+## Step 3: Bind Every Claim
+
+Record each visible operational claim with its state, kind, text, classification, sources, locations, and visibility.
+
+- `verified` means the cited source establishes the claim.
+- `demonstration` means the cited fixture or local simulation establishes only demonstration behavior.
+- `unknown` means the interface explicitly declines to assert a value. Unknown claims do not require a source.
+
+Labels such as `operational`, `online`, `connected`, `production`, and `live` require verified evidence. A green dot, shield, pulse, or success color does not establish status. Pair state color with explicit text and evidence-derived semantics.
+
+Keep data mode in the application shell. Before a consequential action, show data mode and processing boundary next to the action. Do not hide trust information in help text, a settings page, an obstructive watermark, or an export-only disclaimer.
+
+## Step 4: Preserve Disclosure Through Processing
+
+For live work, distinguish connection checking, request acceptance, processing, result delivery, and result provenance. Do not collapse them into one `online` state.
+
+For fallback work, preserve data mode, result origin, and limitations in all of these locations:
+
+```text
+shell -> loading -> result -> history -> export
+```
+
+For stale content, preserve the observed timestamp, timezone, scope, and stale label in the result, history, and export. For disconnection, preserve the last usable context, prohibit unsupported current-state claims, and provide a concrete retry, reconnect, import, or offline action.
+
+## Step 5: Preserve History And Export Provenance
+
+History and exports must retain the same provenance visible in the interface:
+
+- Data mode.
+- Connection state at capture time.
+- Result origin.
+- Freshness timestamp and timezone.
+- Environment.
+- Scope.
+- Limitations, including an explicitly empty limitation set when none are known.
+
+An export is incomplete when it strips demo, fallback, cached, imported, stale, or disconnected context. A history row is misleading when it shows success without the processing path and result origin.
+
+## Step 6: Validate And Verify
+
+Validate the declaration:
+
+```bash
+npm run validate-trust -- --contract PATH
+```
+
+Or use the MCP tool `validate_interface_trust`.
+
+Resolve every error before implementation is treated as trust-complete. Then verify the rendered interface and runtime behavior separately. The contract validator cannot prove that the UI displays a claim, that a source is reachable, that timestamps update, or that users understand the disclosure. Item 6 browser checks and Item 8 attributable review close those evidence gaps.
+
+## Rejection Patterns
+
+Reject or remediate these patterns:
+
+- `System operational` derived from the frontend mounting successfully.
+- `Connected` derived from a configured URL without a runtime request.
+- `Production` shown because an environment variable has a production-like name.
+- A simulated result displayed after a network failure without persistent fallback disclosure.
+- A cached metric shown without its observed time, timezone, and scope.
+- A history row or export that removes demo, fallback, imported, cached, stale, or disconnected provenance.
+- A realistic credential string or placeholder committed for visual completeness.
+- A watermark that obstructs the task while the shell and result omit readable trust labels.

package/knowledge-base/design-intelligence/interface-trust.schema.yaml

@@ -0,0 +1,263 @@
+$schema: https://json-schema.org/draft/2020-12/schema
+$id: https://local.ztothez-design-engineering/schemas/interface-trust-1.0.schema.json
+title: ZtotheZ Interface Trust Contract
+description: Version 1.0 contract for interface state truth, operational claims, source traceability, and provenance-preserving records.
+type: object
+additionalProperties: false
+required: [version, id, product, preparedAt, preparedBy, sources, states, claims, actions, records, security]
+properties:
+  version:
+    const: "1.0"
+  id:
+    $ref: "#/$defs/id"
+  product:
+    $ref: "#/$defs/shortText"
+  preparedAt:
+    type: string
+    format: date-time
+  preparedBy:
+    type: object
+    additionalProperties: false
+    required: [type, name]
+    properties:
+      type:
+        enum: [agent, human, mixed]
+      name:
+        $ref: "#/$defs/shortText"
+  sources:
+    type: array
+    minItems: 1
+    maxItems: 500
+    items:
+      $ref: "#/$defs/source"
+  states:
+    type: array
+    minItems: 5
+    maxItems: 500
+    items:
+      $ref: "#/$defs/state"
+  claims:
+    type: array
+    minItems: 1
+    maxItems: 5000
+    items:
+      $ref: "#/$defs/claim"
+  actions:
+    type: array
+    maxItems: 500
+    items:
+      $ref: "#/$defs/action"
+  records:
+    type: object
+    additionalProperties: false
+    required: [history, export]
+    properties:
+      history:
+        $ref: "#/$defs/record"
+      export:
+        $ref: "#/$defs/record"
+  security:
+    type: object
+    additionalProperties: false
+    required: [allowsEmbeddedCredentials, credentialSources]
+    properties:
+      allowsEmbeddedCredentials:
+        const: false
+      credentialSources:
+        type: array
+        minItems: 1
+        maxItems: 5
+        uniqueItems: true
+        items:
+          enum: [environment, secret-manager, oauth, user-runtime, none]
+$defs:
+  id:
+    type: string
+    pattern: "^[a-z0-9][a-z0-9-]{0,63}$"
+  shortText:
+    type: string
+    minLength: 1
+    maxLength: 256
+  text:
+    type: string
+    minLength: 1
+    maxLength: 1024
+  idList:
+    type: array
+    maxItems: 500
+    items:
+      $ref: "#/$defs/id"
+  source:
+    type: object
+    additionalProperties: false
+    required: [id, kind, authority, description]
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      kind:
+        enum: [runtime-probe, authenticated-api, runtime-processing, user-input, import-record, cache-record, demo-fixture, local-simulation, configuration]
+      authority:
+        enum: [runtime, user, fixture, cache, configuration]
+      description:
+        type: string
+        minLength: 1
+        maxLength: 512
+      evidence:
+        type: string
+        minLength: 1
+        maxLength: 1024
+      checkedAt:
+        type: string
+        format: date-time
+  freshness:
+    type: object
+    additionalProperties: false
+    required: [status]
+    properties:
+      status:
+        enum: [current, stale, unknown, not-applicable]
+      observedAt:
+        type: string
+        format: date-time
+      timezone:
+        type: string
+        minLength: 1
+        maxLength: 128
+    allOf:
+      - if:
+          properties:
+            status:
+              enum: [current, stale]
+        then:
+          required: [observedAt, timezone]
+  state:
+    type: object
+    additionalProperties: false
+    required: [id, scenario, dataMode, connection, result, freshness, environment, scope, limitations, sourceRefs]
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      scenario:
+        enum: [demo, live, fallback, stale, disconnected]
+      dataMode:
+        enum: [demo, live, hybrid, imported, cached]
+      connection:
+        enum: [unknown, checking, connected, degraded, disconnected]
+      result:
+        type: object
+        additionalProperties: false
+        required: [availability]
+        properties:
+          availability:
+            enum: [none, pending, available, partial, failed]
+          origin:
+            enum: [live, simulated, imported, cached]
+        allOf:
+          - if:
+              properties:
+                availability:
+                  enum: [available, partial]
+            then:
+              required: [origin]
+            else:
+              not:
+                required: [origin]
+      freshness:
+        $ref: "#/$defs/freshness"
+      environment:
+        $ref: "#/$defs/shortText"
+      scope:
+        type: string
+        minLength: 1
+        maxLength: 512
+      limitations:
+        type: array
+        maxItems: 30
+        items:
+          type: string
+          minLength: 1
+          maxLength: 512
+      sourceRefs:
+        type: array
+        minItems: 1
+        maxItems: 50
+        items:
+          $ref: "#/$defs/id"
+      recoveryAction:
+        type: string
+        minLength: 1
+        maxLength: 512
+  claim:
+    type: object
+    additionalProperties: false
+    required: [id, state, kind, text, classification, sourceRefs, locations, visibility]
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      state:
+        $ref: "#/$defs/id"
+      kind:
+        enum: [data-mode, connection-status, result-origin, freshness, environment, scope, processing-boundary, limitation, interface-availability, backend-availability]
+      text:
+        $ref: "#/$defs/text"
+      classification:
+        enum: [verified, demonstration, unknown]
+      sourceRefs:
+        type: array
+        maxItems: 50
+        items:
+          $ref: "#/$defs/id"
+      locations:
+        type: array
+        minItems: 1
+        maxItems: 7
+        uniqueItems: true
+        items:
+          enum: [shell, before-action, loading, result, error, history, export]
+      visibility:
+        enum: [persistent, contextual]
+  action:
+    type: object
+    additionalProperties: false
+    required: [id, label, outcome, consequential, stateRefs, disclosureClaimRefs]
+    properties:
+      id:
+        $ref: "#/$defs/id"
+      label:
+        type: string
+        minLength: 1
+        maxLength: 160
+      outcome:
+        type: string
+        minLength: 1
+        maxLength: 512
+      consequential:
+        type: boolean
+      stateRefs:
+        type: array
+        minItems: 1
+        maxItems: 50
+        items:
+          $ref: "#/$defs/id"
+      disclosureClaimRefs:
+        type: array
+        maxItems: 200
+        items:
+          $ref: "#/$defs/id"
+  record:
+    type: object
+    additionalProperties: false
+    required: [enabled, fields, stateRefs, disclosureClaimRefs]
+    properties:
+      enabled:
+        type: boolean
+      fields:
+        type: array
+        maxItems: 7
+        uniqueItems: true
+        items:
+          enum: [data-mode, connection, result-origin, freshness, environment, scope, limitations]
+      stateRefs:
+        $ref: "#/$defs/idList"
+      disclosureClaimRefs:
+        $ref: "#/$defs/idList"

package/knowledge-base/design-intelligence/interface-trust.template.yaml

@@ -0,0 +1,173 @@
+version: "1.0"
+id: operational-interface-trust-v1
+product: Example Operations Workspace
+preparedAt: 2026-08-26T16:00:00+03:00
+preparedBy:
+  type: agent
+  name: ZtotheZ Design Engineering
+
+sources:
+  - id: demo-dataset
+    kind: demo-fixture
+    authority: fixture
+    description: Versioned demonstration dataset bundled for local evaluation.
+    evidence: fixtures/demo-dataset.json
+  - id: service-api
+    kind: authenticated-api
+    authority: runtime
+    description: Authenticated application API providing the current scoped dataset.
+    evidence: evidence/service-api-contract.json
+    checkedAt: 2026-08-26T12:00:00Z
+  - id: health-probe
+    kind: runtime-probe
+    authority: runtime
+    description: Runtime connection probe for the application service.
+    evidence: evidence/health-probe.json
+    checkedAt: 2026-08-26T12:00:00Z
+  - id: analysis-engine
+    kind: runtime-processing
+    authority: runtime
+    description: Runtime analysis execution and result metadata.
+    evidence: evidence/analysis-run.json
+    checkedAt: 2026-08-26T12:00:00Z
+  - id: fallback-engine
+    kind: local-simulation
+    authority: fixture
+    description: Explicit local fallback used only after the primary path fails.
+    evidence: fixtures/fallback-result.json
+  - id: last-known-cache
+    kind: cache-record
+    authority: cache
+    description: Last successful result retained with original scope and observation time.
+    evidence: evidence/cache-record.json
+    checkedAt: 2026-08-25T09:30:00Z
+  - id: deployment-context
+    kind: configuration
+    authority: configuration
+    description: Declared tenant and deployment context; does not establish service availability.
+    evidence: evidence/deployment-context.json
+
+states:
+  - id: demo-ready
+    scenario: demo
+    dataMode: demo
+    connection: unknown
+    result: { availability: available, origin: simulated }
+    freshness: { status: current, observedAt: 2026-08-26T12:00:00Z, timezone: UTC }
+    environment: Demonstration workspace
+    scope: Bundled example estate with 142 synthetic resources
+    limitations: [Values do not represent an external account or current service state.]
+    sourceRefs: [demo-dataset, deployment-context]
+  - id: service-ready
+    scenario: live
+    dataMode: live
+    connection: connected
+    result: { availability: available, origin: live }
+    freshness: { status: current, observedAt: 2026-08-26T12:00:00Z, timezone: UTC }
+    environment: Primary tenant prod-eu-west-1
+    scope: Authenticated tenant resources returned by the current request
+    limitations: [Results cover only resources authorized for the current tenant and request.]
+    sourceRefs: [service-api, health-probe, analysis-engine, deployment-context]
+  - id: local-fallback
+    scenario: fallback
+    dataMode: hybrid
+    connection: degraded
+    result: { availability: available, origin: simulated }
+    freshness: { status: current, observedAt: 2026-08-26T12:00:00Z, timezone: UTC }
+    environment: Primary tenant with local fallback
+    scope: Current request inputs evaluated by the local fallback fixture
+    limitations: [Primary processing failed; the displayed result is simulated and cannot establish external state.]
+    sourceRefs: [service-api, health-probe, fallback-engine, deployment-context]
+    recoveryAction: Retry primary analysis or continue with the labeled local result.
+  - id: cached-stale
+    scenario: stale
+    dataMode: cached
+    connection: unknown
+    result: { availability: available, origin: cached }
+    freshness: { status: stale, observedAt: 2026-08-25T09:30:00Z, timezone: UTC }
+    environment: Primary tenant last-known snapshot
+    scope: Resources included in the last successful scoped request
+    limitations: [Changes after the recorded observation time are not included.]
+    sourceRefs: [last-known-cache, deployment-context]
+    recoveryAction: Refresh the snapshot when a service connection is available.
+  - id: service-disconnected
+    scenario: disconnected
+    dataMode: cached
+    connection: disconnected
+    result: { availability: partial, origin: cached }
+    freshness: { status: stale, observedAt: 2026-08-25T09:30:00Z, timezone: UTC }
+    environment: Primary tenant offline view
+    scope: Last-known resources from the previous successful request
+    limitations: [Current external state is unavailable; only the last-known cached result is shown.]
+    sourceRefs: [last-known-cache, health-probe, deployment-context]
+    recoveryAction: Retry the connection while preserving the current cached context.
+
+claims:
+  - { id: demo-mode, state: demo-ready, kind: data-mode, text: "Demo dataset", classification: demonstration, sourceRefs: [demo-dataset], locations: [shell, before-action, result, history, export], visibility: persistent }
+  - { id: demo-connection, state: demo-ready, kind: connection-status, text: "Connection has not been checked", classification: unknown, sourceRefs: [], locations: [shell, before-action, result, history, export], visibility: persistent }
+  - { id: demo-origin, state: demo-ready, kind: result-origin, text: "Simulated result from the bundled fixture", classification: demonstration, sourceRefs: [demo-dataset], locations: [result, history, export], visibility: contextual }
+  - { id: demo-freshness, state: demo-ready, kind: freshness, text: "Fixture observed 2026-08-26 12:00 UTC", classification: demonstration, sourceRefs: [demo-dataset], locations: [result, history, export], visibility: contextual }
+  - { id: demo-environment, state: demo-ready, kind: environment, text: "Demonstration workspace", classification: verified, sourceRefs: [deployment-context], locations: [shell, result, history, export], visibility: persistent }
+  - { id: demo-scope, state: demo-ready, kind: scope, text: "142 synthetic resources", classification: demonstration, sourceRefs: [demo-dataset], locations: [before-action, result, history, export], visibility: contextual }
+  - { id: demo-limitation, state: demo-ready, kind: limitation, text: "Values do not represent an external account", classification: demonstration, sourceRefs: [demo-dataset], locations: [result, history, export], visibility: contextual }
+  - { id: demo-processing, state: demo-ready, kind: processing-boundary, text: "Analysis uses the bundled fixture on this device", classification: demonstration, sourceRefs: [demo-dataset], locations: [before-action, loading, result], visibility: contextual }
+
+  - { id: live-mode, state: service-ready, kind: data-mode, text: "Live tenant data", classification: verified, sourceRefs: [service-api], locations: [shell, before-action, result, history, export], visibility: persistent }
+  - { id: live-connection, state: service-ready, kind: connection-status, text: "Connected to the application service", classification: verified, sourceRefs: [health-probe], locations: [shell, before-action, loading, result, history, export], visibility: persistent }
+  - { id: live-origin, state: service-ready, kind: result-origin, text: "Live result from the runtime analysis", classification: verified, sourceRefs: [analysis-engine], locations: [result, history, export], visibility: contextual }
+  - { id: live-freshness, state: service-ready, kind: freshness, text: "Observed 2026-08-26 12:00 UTC", classification: verified, sourceRefs: [service-api], locations: [result, history, export], visibility: contextual }
+  - { id: live-environment, state: service-ready, kind: environment, text: "Primary tenant prod-eu-west-1", classification: verified, sourceRefs: [deployment-context], locations: [shell, result, history, export], visibility: persistent }
+  - { id: live-scope, state: service-ready, kind: scope, text: "Resources authorized for the current tenant request", classification: verified, sourceRefs: [service-api], locations: [before-action, result, history, export], visibility: contextual }
+  - { id: live-limitation, state: service-ready, kind: limitation, text: "Results exclude resources outside current tenant authorization", classification: verified, sourceRefs: [deployment-context], locations: [result, history, export], visibility: contextual }
+  - { id: live-processing, state: service-ready, kind: processing-boundary, text: "The application service processes this request", classification: verified, sourceRefs: [analysis-engine], locations: [before-action, loading, result], visibility: contextual }
+
+  - { id: fallback-mode, state: local-fallback, kind: data-mode, text: "Hybrid mode using local fallback", classification: verified, sourceRefs: [service-api, fallback-engine], locations: [shell, before-action, loading, result, history, export], visibility: persistent }
+  - { id: fallback-connection, state: local-fallback, kind: connection-status, text: "Service degraded", classification: verified, sourceRefs: [health-probe], locations: [shell, before-action, loading, result, history, export], visibility: persistent }
+  - { id: fallback-origin, state: local-fallback, kind: result-origin, text: "Simulated result from the local fallback", classification: demonstration, sourceRefs: [fallback-engine], locations: [loading, result, history, export], visibility: persistent }
+  - { id: fallback-freshness, state: local-fallback, kind: freshness, text: "Fallback generated 2026-08-26 12:00 UTC", classification: demonstration, sourceRefs: [fallback-engine], locations: [result, history, export], visibility: contextual }
+  - { id: fallback-environment, state: local-fallback, kind: environment, text: "Primary tenant with local fallback", classification: verified, sourceRefs: [deployment-context], locations: [shell, result, history, export], visibility: persistent }
+  - { id: fallback-scope, state: local-fallback, kind: scope, text: "Current inputs evaluated by the local fixture", classification: demonstration, sourceRefs: [fallback-engine], locations: [before-action, result, history, export], visibility: contextual }
+  - { id: fallback-limitation, state: local-fallback, kind: limitation, text: "Primary processing failed; this result cannot establish external state", classification: demonstration, sourceRefs: [fallback-engine], locations: [loading, result, history, export], visibility: persistent }
+  - { id: fallback-processing, state: local-fallback, kind: processing-boundary, text: "The local fallback processes this request", classification: demonstration, sourceRefs: [fallback-engine], locations: [before-action, loading, result], visibility: contextual }
+
+  - { id: stale-mode, state: cached-stale, kind: data-mode, text: "Cached snapshot", classification: verified, sourceRefs: [last-known-cache], locations: [shell, before-action, result, history, export], visibility: persistent }
+  - { id: stale-connection, state: cached-stale, kind: connection-status, text: "Current connection state is unknown", classification: unknown, sourceRefs: [], locations: [shell, before-action, result, history, export], visibility: persistent }
+  - { id: stale-origin, state: cached-stale, kind: result-origin, text: "Cached result from the last successful request", classification: verified, sourceRefs: [last-known-cache], locations: [result, history, export], visibility: contextual }
+  - { id: stale-freshness, state: cached-stale, kind: freshness, text: "Stale since 2026-08-25 09:30 UTC", classification: verified, sourceRefs: [last-known-cache], locations: [shell, result, history, export], visibility: persistent }
+  - { id: stale-environment, state: cached-stale, kind: environment, text: "Primary tenant last-known snapshot", classification: verified, sourceRefs: [deployment-context], locations: [shell, result, history, export], visibility: persistent }
+  - { id: stale-scope, state: cached-stale, kind: scope, text: "Resources in the last successful request", classification: verified, sourceRefs: [last-known-cache], locations: [before-action, result, history, export], visibility: contextual }
+  - { id: stale-limitation, state: cached-stale, kind: limitation, text: "Changes after the observation time are not included", classification: verified, sourceRefs: [last-known-cache], locations: [result, history, export], visibility: persistent }
+  - { id: stale-processing, state: cached-stale, kind: processing-boundary, text: "No new external processing occurs while viewing this snapshot", classification: verified, sourceRefs: [last-known-cache], locations: [before-action, loading, result], visibility: contextual }
+
+  - { id: disconnected-mode, state: service-disconnected, kind: data-mode, text: "Cached offline view", classification: verified, sourceRefs: [last-known-cache], locations: [shell, before-action, result, history, export], visibility: persistent }
+  - { id: disconnected-connection, state: service-disconnected, kind: connection-status, text: "Disconnected from the application service", classification: verified, sourceRefs: [health-probe], locations: [shell, before-action, error, result, history, export], visibility: persistent }
+  - { id: disconnected-origin, state: service-disconnected, kind: result-origin, text: "Cached result from the previous request", classification: verified, sourceRefs: [last-known-cache], locations: [result, history, export], visibility: contextual }
+  - { id: disconnected-freshness, state: service-disconnected, kind: freshness, text: "Stale since 2026-08-25 09:30 UTC", classification: verified, sourceRefs: [last-known-cache], locations: [shell, result, history, export], visibility: persistent }
+  - { id: disconnected-environment, state: service-disconnected, kind: environment, text: "Primary tenant offline view", classification: verified, sourceRefs: [deployment-context], locations: [shell, result, history, export], visibility: persistent }
+  - { id: disconnected-scope, state: service-disconnected, kind: scope, text: "Last-known resources from the previous request", classification: verified, sourceRefs: [last-known-cache], locations: [before-action, result, history, export], visibility: contextual }
+  - { id: disconnected-limitation, state: service-disconnected, kind: limitation, text: "Current external state is unavailable", classification: verified, sourceRefs: [health-probe], locations: [error, result, history, export], visibility: persistent }
+  - { id: disconnected-processing, state: service-disconnected, kind: processing-boundary, text: "Retry requires restoring the service connection", classification: verified, sourceRefs: [health-probe], locations: [before-action, error, result], visibility: contextual }
+
+actions:
+  - id: run-analysis
+    label: Run analysis
+    outcome: Produce a scoped result whose processing path and provenance remain visible.
+    consequential: true
+    stateRefs: [demo-ready, service-ready, local-fallback, cached-stale, service-disconnected]
+    disclosureClaimRefs: [demo-mode, demo-processing, live-mode, live-processing, fallback-mode, fallback-processing, stale-mode, stale-processing, disconnected-mode, disconnected-processing]
+
+records:
+  history:
+    enabled: true
+    fields: [data-mode, connection, result-origin, freshness, environment, scope, limitations]
+    stateRefs: [demo-ready, service-ready, local-fallback, cached-stale, service-disconnected]
+    disclosureClaimRefs: [demo-mode, demo-connection, demo-origin, demo-freshness, demo-environment, demo-scope, demo-limitation, live-mode, live-connection, live-origin, live-freshness, live-environment, live-scope, live-limitation, fallback-mode, fallback-connection, fallback-origin, fallback-freshness, fallback-environment, fallback-scope, fallback-limitation, stale-mode, stale-connection, stale-origin, stale-freshness, stale-environment, stale-scope, stale-limitation, disconnected-mode, disconnected-connection, disconnected-origin, disconnected-freshness, disconnected-environment, disconnected-scope, disconnected-limitation]
+  export:
+    enabled: true
+    fields: [data-mode, connection, result-origin, freshness, environment, scope, limitations]
+    stateRefs: [demo-ready, service-ready, local-fallback, cached-stale, service-disconnected]
+    disclosureClaimRefs: [demo-mode, demo-connection, demo-origin, demo-freshness, demo-environment, demo-scope, demo-limitation, live-mode, live-connection, live-origin, live-freshness, live-environment, live-scope, live-limitation, fallback-mode, fallback-connection, fallback-origin, fallback-freshness, fallback-environment, fallback-scope, fallback-limitation, stale-mode, stale-connection, stale-origin, stale-freshness, stale-environment, stale-scope, stale-limitation, disconnected-mode, disconnected-connection, disconnected-origin, disconnected-freshness, disconnected-environment, disconnected-scope, disconnected-limitation]
+
+security:
+  allowsEmbeddedCredentials: false
+  credentialSources: [environment, secret-manager, oauth]