kaloko 0.14.0 → 0.16.0

package/README.md

@@ -51,7 +51,7 @@ For example:
 
 > Draft a Kaloko scenario for https://example.com (home, pricing, contact)
 > with the seo, a11y and perf packs, run it on production read-only and
-> summarise what fails.
+> summarise its health.
 
 ## Run a scenario by hand (or in CI)
 
@@ -229,7 +229,11 @@ show (overlap, cut-off text, a raw translation key, an endless spinner);
 reviewers turn the right findings into comments with one click, and findings
 never change a verdict. Triage counts against the hosted-evaluation allowance,
 so it needs the Team plan or higher.
-The `a11y` pack walks the page with Tab (order, visible focus, traps, skip
+Check packs (`seo`, `a11y`, `perf`, `usability`, `console`) report the app's
+health apart from acceptance: they never fail a step that meets its brief,
+`kaloko health` lists what is new since the previous run, and
+`kaloko health adopt` makes one check an acceptance criterion when the team
+wants it to decide. The `a11y` pack walks the page with Tab (order, visible focus, traps, skip
 link) and reads names from the accessibility tree. Pixel diffs skip the
 regions a step ignores; `kaloko walk --stability 3` and `kaloko stability`
 find the clocks, ads and carousels worth ignoring, and `kaloko stability --pull`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Your AI agents build; Kaloko walks every screen, puts it on one canvas and records who approved what.",
   "keywords": [
     "qa",

package/schemas/config.v1.json

@@ -8,7 +8,9 @@
   "properties": {
     "schema": { "const": "qawalk.config.v1" },
     "org": { "type": "string", "description": "Organization slug on kaloko.app." },
-    "project": { "type": "string" },
+    "project": { "type": "string", "description": "Slug of the Kaloko project runs of this repository belong to (a scenario's project: wins)." },
+    "project_name": { "type": "string", "maxLength": 80, "description": "The name people see for that project on Kaloko (ECO Podcasty). A share creates a missing project with it; kaloko projects sync renames an existing one." },
+    "product": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]{0,79}$", "description": "Slug of a product on Kaloko the project is part of; kaloko projects sync adds the project to it." },
     "products": {
       "type": "object",
       "description": "Optional: what is released and versioned as a whole and has its own visual changelog (docs/DOCS-CHANGELOG.md). Without it the project is the product. Keys are product slugs.",

package/schemas/evidence.v1.json

@@ -0,0 +1,257 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qawalk.com/schemas/evidence.v1.json",
+  "title": "Kaloko evidence (qawalk.evidence.v1)",
+  "description": "What a downstream generator reads from Kaloko to write its own documentation: the evidence of a run (kind run), of a release (kind release), the trace matrix on its own (kind trace) and the MANIFEST.json of an evidence package (kind package). The contract is additive: new fields may appear in v1, existing fields keep their meaning and type; a breaking change makes qawalk.evidence.v2. Kaloko never formats output for a particular QMS. Produced by GET /api/v1/orgs/<org>/runs/<id>/evidence, …/evidence.zip, …/trace.json, GET /api/v1/orgs/<org>/evidence?product=&version=, MCP get_evidence and kaloko evidence.",
+  "type": "object",
+  "required": ["schema", "kind"],
+  "properties": {
+    "schema": { "const": "qawalk.evidence.v1" },
+    "kind": { "enum": ["run", "release", "trace", "package"] }
+  },
+  "allOf": [
+    { "if": { "properties": { "kind": { "const": "run" } } }, "then": { "$ref": "#/$defs/run" } },
+    { "if": { "properties": { "kind": { "const": "release" } } }, "then": { "$ref": "#/$defs/release" } },
+    { "if": { "properties": { "kind": { "const": "trace" } } }, "then": { "$ref": "#/$defs/trace" } },
+    { "if": { "properties": { "kind": { "const": "package" } } }, "then": { "$ref": "#/$defs/package" } }
+  ],
+  "$defs": {
+    "time": { "type": ["string", "null"], "description": "ISO 8601 time in UTC (…Z), from the service's clock." },
+    "sha256": { "type": ["string", "null"], "pattern": "^[0-9a-f]{64}$", "description": "SHA-256, lowercase hex." },
+    "refs": { "type": "array", "items": { "type": "string" }, "description": "Requirement references as written in the scenario (refs:), free text, never interpreted." },
+    "run": {
+      "type": "object",
+      "required": ["generated_at", "acceptance", "signing", "record", "run", "scenario", "steps", "signatures", "trace"],
+      "properties": {
+        "generated_at": { "$ref": "#/$defs/time", "description": "When this document was made. It is not signed itself; record.sha256 names the signed record it was made from." },
+        "issuer": {
+          "type": "object",
+          "properties": {
+            "service": { "type": ["string", "null"], "description": "The Kaloko service that holds the run, e.g. https://kaloko.app." },
+            "commit": { "type": ["string", "null"], "description": "The service's deployed version (git commit), when known." },
+            "public_keys": { "type": ["string", "null"], "description": "URL of the public keys the record and the package manifest verify against (/.well-known/kaloko-signoff.json)." }
+          }
+        },
+        "org": { "type": ["object", "null"], "properties": { "slug": { "type": "string" }, "name": { "type": ["string", "null"] } } },
+        "acceptance": { "enum": ["none", "accepted", "returned"], "description": "The run's acceptance in Kaloko: accepted, returned, or none (nobody decided the run, or the decision was reset). A generator writes from this, never from the presence of other fields." },
+        "signing": { "enum": ["in_kaloko", "none"], "description": "in_kaloko: at least one electronic signature made in Kaloko stands (see signatures). none: no signature in Kaloko; if the approval is signed, it is signed in another system (the client's eQMS) and that system holds it." },
+        "record": {
+          "type": "object",
+          "description": "The signed record this evidence was derived from (record/kaloko-signoff.json in the package).",
+          "properties": {
+            "schema": { "type": ["string", "null"], "description": "kaloko.signoff.v1." },
+            "kind": { "enum": ["acceptance", "execution"], "description": "acceptance: the stored record of an accepted run (byte-identical on every download while its verdict and signatures stay). execution: a run that is not accepted; signed when made, not stored." },
+            "sha256": { "$ref": "#/$defs/sha256", "description": "SHA-256 of the record's canonical JSON without its signature: what kaloko signoff --verify prints as the record hash." },
+            "signed": { "type": "boolean", "description": "The record carries the service's Ed25519 signature." },
+            "kid": { "type": ["string", "null"], "description": "Id of the signing key." },
+            "issued_at": { "$ref": "#/$defs/time" },
+            "exported_by": { "type": ["string", "null"], "description": "Who downloaded the record first (e-mail)." }
+          }
+        },
+        "run": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "url": { "type": ["string", "null"], "description": "The run on the canvas." },
+            "project": { "type": ["string", "null"] },
+            "started_at": { "$ref": "#/$defs/time", "description": "When the walk started (the walking machine's clock)." },
+            "finished_at": { "$ref": "#/$defs/time", "description": "When the manifest was built (the walking machine's clock)." },
+            "version": { "type": ["string", "null"], "description": "Design version, for runs of design environments." },
+            "app_version": { "type": ["string", "null"], "description": "Version of the application under test, when the run names one." }
+          }
+        },
+        "scenario": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "title": { "type": ["string", "null"] },
+            "version": { "type": ["integer", "string", "null"], "description": "The scenario's own version: field, when set." },
+            "file": { "type": ["string", "null"], "description": "Path of the scenario file in the repository." },
+            "sha256": { "$ref": "#/$defs/sha256", "description": "SHA-256 of the scenario file as walked (CLI 0.15+; null before)." },
+            "refs": { "$ref": "#/$defs/refs" }
+          }
+        },
+        "environment": { "type": ["object", "null"], "description": "{ name, url }: the environment and its base URL." },
+        "git": { "type": ["object", "null"], "description": "{ commit, branch, repo } of the code the run walked, when known." },
+        "tools": {
+          "type": ["object", "null"],
+          "description": "What walked and evaluated the run.",
+          "properties": {
+            "cli": { "type": ["object", "null"], "description": "{ name, version } of the Kaloko CLI (null version: walked before 0.15)." },
+            "node": { "type": ["string", "null"] },
+            "os": { "type": ["string", "null"] },
+            "browsers": { "type": "array", "items": { "type": "string" }, "description": "Browser engines and versions seen in the captures, e.g. \"chromium 131.0.6778.33\"." },
+            "executor": { "type": ["object", "null"], "description": "{ kind: cli | agent, name }." },
+            "service": { "type": ["object", "null"], "description": "{ url, commit } of the service that signed the record." }
+          }
+        },
+        "manifest": { "type": ["object", "null"], "description": "{ path: run.json, sha256, bytes }: the run manifest as stored. Every signature is bound to this hash." },
+        "verdict": { "type": ["object", "null"], "description": "{ verdict: pending | accepted | returned, by, via: session | token | agent, at, note, country, counts_as_person }. via session is a person in the app; token and agent are never a person's decision." },
+        "approvals": { "type": ["object", "null"], "description": "{ required: [e-mail], people: [{ email, at }], tokens_and_agents: [{ email, at, via, counts_as_person: false }] }." },
+        "summary": { "type": ["object", "null"] },
+        "ai": { "type": ["object", "null"], "description": "{ advisory: true, models: [model id], statement }: AI verdicts are advisory; the decisions that count are a person's." },
+        "advisory": { "type": ["object", "null"], "description": "Results the run carries besides its acceptance criteria (e.g. a health section), copied as they are. They never change acceptance." },
+        "steps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "kind": { "type": "string" },
+              "title": { "type": ["string", "null"] },
+              "refs": { "$ref": "#/$defs/refs" },
+              "status": { "enum": ["pass", "partial", "fail", "skip"] },
+              "decision": { "type": ["object", "null"], "description": "The step's current decision: { id, state: approved | returned, by, at, via, agent?, counts_as_person, note?, attachments?: [{ id, name, type, bytes, sha256, by, at, path: decisions/<step>/<file> in the evidence package }], pin?, shape? }." },
+              "decisions": { "type": "array", "description": "Every decision on the step, oldest first, shaped like decision; superseded ones too (resolved_at, deleted: true without content)." },
+              "carried": { "type": ["object", "null"], "description": "An approval carried over from an earlier accepted run: { from_run, compared_run, kind, approved_by, approved_at, approved_via }." },
+              "criteria": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "id": { "type": "string" },
+                    "text": { "type": ["string", "null"], "description": "The criterion as walked (from the scenario at the time of the run)." },
+                    "type": { "type": ["string", "null"], "description": "deterministic, semantic or manual." },
+                    "pack": { "type": "string", "description": "The pack the criterion came from, when it did." },
+                    "refs": { "$ref": "#/$defs/refs" },
+                    "verdict": { "type": "string", "description": "pass, fail, needs_review, not_evaluated or not_reached; the worst over locales and viewports after people's verdicts." },
+                    "assessed_by": { "enum": ["person", "ai", "deterministic", "none"] },
+                    "models": { "type": "array", "items": { "type": "string" }, "description": "AI models that assessed it." },
+                    "advisory": { "type": "boolean", "description": "true: the result is an AI's and no person decided this criterion." },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "locale": { "type": "string" },
+                          "viewport": { "type": "string" },
+                          "verdict": { "type": "string" },
+                          "score": { "type": "number", "description": "The AI's probability that the criterion holds (0–1)." },
+                          "assessed_by": { "enum": ["person", "ai", "deterministic", "none"] },
+                          "assessor": { "type": ["string", "null"], "description": "The person's e-mail, or the AI model id." },
+                          "advisory": { "type": "boolean" }
+                        }
+                      }
+                    },
+                    "reviewer": { "type": "array", "description": "Criterion verdicts set by people: { email, verdict, note, locale, at }." }
+                  }
+                }
+              },
+              "captures": {
+                "type": "array",
+                "items": { "type": "object", "properties": { "locale": { "type": "string" }, "viewport": { "type": "string" }, "path": { "type": ["string", "null"], "description": "Path in the run; the package stores it under captures/<path>." }, "sha256": { "$ref": "#/$defs/sha256" } } }
+              }
+            }
+          }
+        },
+        "signatures": {
+          "type": "array",
+          "description": "Electronic signatures made in Kaloko, oldest first, withdrawn ones included. Empty unless the organization signs in Kaloko.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "string" },
+              "scope": { "enum": ["run", "step"] },
+              "step": { "type": ["string", "null"] },
+              "review": { "type": ["string", "null"], "description": "The step approval it signs (comment id)." },
+              "decision": { "type": "string", "description": "accepted (run) or approved (step)." },
+              "meaning": { "type": "string", "description": "The meaning the signer chose from the organization's list, as the label they saw." },
+              "meaning_id": { "type": ["string", "null"], "description": "subject_v 2: the meaning's id (reviewed, approved, verified, or the organization's own)." },
+              "lang": { "type": ["string", "null"], "description": "subject_v 2: the language the meaning's label was shown in (en, cs)." },
+              "subject_v": { "type": "integer", "description": "2 for signatures made since 7 Oct 2026; absent (1) before." },
+              "decision_sha256": { "type": ["string", "null"], "description": "subject_v 2: SHA-256 of the canonical decision { note, attachments [{ name, bytes, sha256 }], pin, shape } (a run: its note)." },
+              "name": { "type": "string", "description": "Printed name of the signer." },
+              "email": { "type": "string" },
+              "signed_at": { "$ref": "#/$defs/time" },
+              "time_zone": { "type": "string", "description": "The signer's IANA time zone." },
+              "local_time": { "type": "string", "description": "The signing time in the signer's zone with its UTC offset." },
+              "auth": { "type": "object", "description": "{ session: how the session signed in, second_step_at: when the second step was confirmed, second_step_by: kaloko | idp }." },
+              "verdict_at": { "$ref": "#/$defs/time" },
+              "manifest_sha256": { "$ref": "#/$defs/sha256" },
+              "subject_sha256": { "$ref": "#/$defs/sha256", "description": "SHA-256 of the canonical JSON { v: 1, run, step, decision, meaning, email, name, signed_at, manifest_sha256 } (subject_v 2 adds meaning_id, lang and decision_sha256): what was signed. kaloko signoff --verify recomputes it." },
+              "withdrawn": { "type": ["object", "null"], "description": "{ at, by, reason } once the decision changed; the signature is never rewritten otherwise." }
+            }
+          }
+        },
+        "decision_changes": { "type": "array", "description": "Withdrawn signatures: { at, by, reason, signature, scope, step, signed_by, meaning }." },
+        "audit": {
+          "type": "array",
+          "description": "The audit trail of the run, oldest first: rows of the audit log about the run (source audit_log) and its decisions from comments and criterion verdicts (source decisions).",
+          "items": { "type": "object", "properties": { "at": { "$ref": "#/$defs/time" }, "actor": { "type": ["string", "null"] }, "action": { "type": ["string", "null"] }, "target": { "type": ["string", "null"] }, "via": { "type": ["string", "null"] }, "agent": { "type": ["string", "null"] }, "country": { "type": ["string", "null"] }, "source": { "enum": ["audit_log", "decisions"] }, "detail": {} } }
+        },
+        "trace": { "type": "array", "items": { "$ref": "#/$defs/traceRow" } }
+      }
+    },
+    "traceRow": {
+      "type": "object",
+      "description": "One row of the trace matrix: a requirement, a criterion, a step in one locale and viewport, its screenshot, the result and the decisions. A criterion's requirements are its own refs, its step's and its scenario's (requirement_level); a criterion without any gets one row with requirement null. The CSV has these columns in this order.",
+      "properties": {
+        "requirement": { "type": ["string", "null"] },
+        "requirement_level": { "enum": ["criterion", "step", "scenario", null] },
+        "run_id": { "type": ["string", "null"] },
+        "scenario_id": { "type": ["string", "null"] },
+        "scenario_version": { "type": ["integer", "string", "null"] },
+        "step_id": { "type": "string" },
+        "step_title": { "type": ["string", "null"] },
+        "criterion_id": { "type": "string" },
+        "criterion_text": { "type": ["string", "null"] },
+        "criterion_type": { "type": ["string", "null"] },
+        "locale": { "type": ["string", "null"] },
+        "viewport": { "type": ["string", "null"] },
+        "evidence_file": { "type": ["string", "null"] },
+        "evidence_sha256": { "$ref": "#/$defs/sha256" },
+        "result": { "type": ["string", "null"] },
+        "assessed_by": { "type": ["string", "null"] },
+        "assessor": { "type": ["string", "null"] },
+        "advisory": { "type": "boolean" },
+        "step_decision": { "type": ["string", "null"] },
+        "step_decided_by": { "type": ["string", "null"] },
+        "step_decided_at": { "$ref": "#/$defs/time" },
+        "step_decided_via": { "type": ["string", "null"] },
+        "step_signature_meaning": { "type": ["string", "null"] },
+        "step_signer_name": { "type": ["string", "null"] },
+        "step_signed_at": { "$ref": "#/$defs/time" },
+        "step_signer_time_zone": { "type": ["string", "null"] },
+        "step_comment": { "type": ["string", "null"] },
+        "run_verdict": { "type": ["string", "null"] },
+        "run_decided_by": { "type": ["string", "null"] },
+        "run_decided_at": { "$ref": "#/$defs/time" },
+        "run_decided_via": { "type": ["string", "null"] },
+        "run_signature_meaning": { "type": ["string", "null"] },
+        "run_signer_name": { "type": ["string", "null"] },
+        "run_signed_at": { "$ref": "#/$defs/time" },
+        "run_signer_time_zone": { "type": ["string", "null"] }
+      }
+    },
+    "release": {
+      "type": "object",
+      "required": ["release", "runs", "trace"],
+      "properties": {
+        "generated_at": { "$ref": "#/$defs/time" },
+        "release": { "type": "object", "description": "{ product, version, released_on, tag, commit, runs: [run id] }." },
+        "runs": { "type": "array", "items": { "$ref": "#/$defs/run" }, "description": "The evidence of each run of the release the caller can read." },
+        "missing": { "type": "array", "items": { "type": "object", "properties": { "run": { "type": "string" }, "reason": { "type": "string" } } }, "description": "Runs of the release without evidence here, with the reason." },
+        "trace": { "type": "array", "items": { "$ref": "#/$defs/traceRow" } }
+      }
+    },
+    "trace": {
+      "type": "object",
+      "required": ["rows"],
+      "properties": { "run": { "type": "string" }, "record_sha256": { "$ref": "#/$defs/sha256" }, "rows": { "type": "array", "items": { "$ref": "#/$defs/traceRow" } } }
+    },
+    "package": {
+      "type": "object",
+      "required": ["files", "signature"],
+      "description": "MANIFEST.json of an evidence package, signed like a record (Ed25519 over its canonical JSON without signature).",
+      "properties": {
+        "created_at": { "$ref": "#/$defs/time" },
+        "issuer": { "type": "object", "description": "{ service, kid, public_keys }." },
+        "run": { "type": "string" },
+        "record_sha256": { "$ref": "#/$defs/sha256" },
+        "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "sha256": { "$ref": "#/$defs/sha256" }, "bytes": { "type": "integer" } } } },
+        "missing": { "type": "array", "items": { "type": "string" }, "description": "Screenshots the record names that could not be read when the package was made." },
+        "signature": { "type": "object", "description": "{ alg: Ed25519, kid, value, canonical: kaloko-c14n-v1 }." }
+      }
+    }
+  }
+}

package/schemas/run.v1.json

@@ -50,6 +50,15 @@
         "file": {
           "type": "string"
         },
+        "sha256": {
+          "type": "string",
+          "description": "SHA-256 of the scenario file as it was walked (kaloko 0.15+)."
+        },
+        "refs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Requirement references of the scenario (scenario refs:)."
+        },
         "source": {
           "type": [
             "string",
@@ -132,6 +141,16 @@
         "null"
       ]
     },
+    "tools": {
+      "type": "object",
+      "description": "What walked the run (kaloko 0.15+): cli {name, version}, node (the Node.js version), os (platform and architecture), browsers (engine versions seen in the captures).",
+      "properties": {
+        "cli": { "type": "object" },
+        "node": { "type": ["string", "null"] },
+        "os": { "type": ["string", "null"] },
+        "browsers": { "type": "array", "items": { "type": "string" } }
+      }
+    },
     "started_at": {
       "type": "string"
     },
@@ -227,6 +246,17 @@
         },
         "criteria": {
           "type": "object"
+        },
+        "health": {
+          "type": "object",
+          "description": "Health counts (advisory, CS Kondice): checks evaluated and findings by severity (error, warning; info = the evaluator was unsure), also per pack. Never part of pass, partial or fail.",
+          "properties": {
+            "checks": { "type": "integer" },
+            "error": { "type": "integer" },
+            "warning": { "type": "integer" },
+            "info": { "type": "integer" },
+            "packs": { "type": "object" }
+          }
         }
       }
     },
@@ -251,6 +281,10 @@
         "slug": {
           "type": "string"
         },
+        "name": {
+          "type": "string",
+          "description": "The project's name from project_name: in kaloko.config.yml; a project that a share creates gets it."
+        },
         "repo": {
           "type": [
             "string",
@@ -417,6 +451,11 @@
         "purpose": {
           "type": "string"
         },
+        "refs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Requirement references of the step (refs: in the scenario)."
+        },
         "col": {
           "type": "integer"
         },
@@ -535,6 +574,11 @@
               "verdict": {
                 "$ref": "#/$defs/verdict"
               },
+              "refs": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Requirement references of the criterion (refs: in the scenario)."
+              },
               "by_locale": {
                 "type": "object"
               },
@@ -559,7 +603,33 @@
               },
               "check": {
                 "type": "object"
-              }
+              },
+              "pack": {
+                "type": ["string", "null"],
+                "description": "The check pack the criterion comes from. In criteria a pack criterion counts for acceptance only with acceptance: true; runs stored before health was split off have pack criteria here without it (readers show them as health; their stored verdicts stay)."
+              },
+              "acceptance": { "type": "boolean" },
+              "from": { "type": "string", "description": "The health check an adopted criterion came from (e.g. HC302)." }
+            }
+          }
+        },
+        "health": {
+          "type": "array",
+          "description": "Health checks (CS Kondice): criteria of check packs outside acceptance, shaped like criteria plus level (error or warning when the check fails). Advisory: they never decide the step status or the run verdict. Absent when the step has none.",
+          "items": {
+            "type": "object",
+            "required": ["id", "text", "verdict"],
+            "properties": {
+              "id": { "type": "string", "description": "Health check id, HC<n> (HC302). Runs written before 7 Oct 2026 store AC<n>; readers map it to HC<n>." },
+              "text": { "type": "string" },
+              "pack": { "type": ["string", "null"] },
+              "level": { "enum": ["error", "warning"] },
+              "verdict": { "$ref": "#/$defs/verdict" },
+              "by_locale": { "type": "object" },
+              "counts": { "type": "object", "description": "Stack steps: pages per verdict." },
+              "evidence": { "type": ["string", "null"] },
+              "check": { "type": "object" },
+              "help": { "type": "object" }
             }
           }
         },

package/schemas/scenario.v1.json

@@ -89,12 +89,23 @@
       "enum": ["landing", "work", "list", "settings", "form", "doc"],
       "description": "Default page type of every step (a step may set its own). landing: a public or marketing page; work: an app screen where people work (overview, canvas, inbox); list: a list or table of items; settings: settings or billing; form: a form to fill in; doc: documentation or long text. The usability pack picks its questions by type. Not set: landing for steps with the seo pack or scenarios allowed on production, work otherwise."
     },
+    "health": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Health (CS Kondice): the checks of packs are advisory, shown apart from acceptance and never part of a verdict. acceptance lists the packs whose checks still count for acceptance in this scenario, as they did before health was split off (the design pack always does). To make one check count, adopt it: kaloko health adopt <step>:<check> (e.g. home:HC103) adds the criterion AC103 with from: HC103.",
+      "properties": {
+        "acceptance": { "type": "array", "uniqueItems": true, "items": { "enum": ["seo", "usability", "a11y", "perf", "console", "errors", "app", "design"] } }
+      }
+    },
     "tags": {
       "type": "array",
       "items": {
         "type": "string"
       }
     },
+    "refs": {
+      "$ref": "#/$defs/refs"
+    },
     "nodes": {
       "type": "array",
       "minItems": 1,
@@ -193,6 +204,13 @@
     }
   },
   "$defs": {
+    "refs": {
+      "description": "Requirement references this part verifies, as your QMS or tracker writes them (URS-12, FS-3.4, JIRA-1234). Free text; Kaloko carries them into the run, the acceptance record and the trace matrix (qawalk.evidence.v1) and never interprets them.",
+      "type": "array",
+      "maxItems": 50,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^\\S(.*\\S)?$" }
+    },
     "record": {
       "description": "Recordings of walked steps (opt-in): true or step records each step from the previous screen to its capture; flow records the whole walk per locale with a chapter per step; failed keeps only steps that fail; false or off turns it off. Uploaded on Business and Enterprise.",
       "oneOf": [
@@ -277,6 +295,9 @@
         "purpose": {
           "type": "string"
         },
+        "refs": {
+          "$ref": "#/$defs/refs"
+        },
         "lane": {
           "type": "integer",
           "minimum": 0
@@ -341,7 +362,7 @@
               "design"
             ]
           },
-          "description": "Check packs whose criteria are added to this node (ids AC1xx seo, AC2xx usability, AC3xx a11y, AC4xx perf, AC5xx console, AC6xx errors, AC7xx app, AC8xx design: checks against the design reference)."
+          "description": "Check packs whose checks are added to this node. Health checks (advisory): HC1xx seo, HC2xx usability, HC3xx a11y, HC4xx perf, HC5xx console, HC6xx errors, HC7xx app. AC8xx design: checks against the design reference, always acceptance. A pack listed in health.acceptance adds its checks as acceptance criteria with the same number (HC302 → AC302)."
         },
         "capture": {
           "$ref": "#/$defs/capture"
@@ -352,6 +373,24 @@
           "description": "Regions left out of pixel comparisons (clocks, ads, carousels): a selector, or a rectangle in page pixels of one viewport. kaloko stability suggests them.",
           "items": { "$ref": "#/$defs/ignoreRegion" }
         },
+        "details": {
+          "type": "array",
+          "maxItems": 20,
+          "description": "Named details for user guides and docs: one element in the part of the page around it (its section or card), outlined, captured in every locale and viewport. Docs show one with ![…](kaloko:<scenario>/<step>#<id>).",
+          "items": {
+            "type": "object",
+            "required": ["id", "name", "selector"],
+            "additionalProperties": false,
+            "properties": {
+              "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,59}$", "description": "Stable id, used in docs references (#add-to-cart) and file names." },
+              "name": { "$ref": "#/$defs/localized", "description": "What the reader looks at, e.g. \"Add to cart button\"; one text or one per locale." },
+              "selector": { "type": "string", "minLength": 1, "description": "CSS selector of the element; the first match is outlined." },
+              "context": { "type": "string", "minLength": 1, "description": "How much of the page around it: section (the nearest section or landmark), card (the nearest card, list item or framed box), page (one screen around it) or a CSS selector of an ancestor. Default: the nearest section or card at least 480 × 240 px, at most one screen." },
+              "padding": { "type": "integer", "minimum": 0, "maximum": 200, "description": "Pixels of page around the context (default 16)." },
+              "states": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,39}$" }, "description": "Step states to take it in (default: every state the step is captured in)." }
+            }
+          }
+        },
         "items": {
           "type": "object",
           "additionalProperties": false,
@@ -532,6 +571,9 @@
           "type": "string",
           "description": "CSS selector to outline in the screenshot."
         },
+        "refs": {
+          "$ref": "#/$defs/refs"
+        },
         "check": {
           "oneOf": [
             {
@@ -549,6 +591,15 @@
           "type": "string",
           "description": "Set by the CLI on criteria that came from a pack."
         },
+        "from": {
+          "type": "string",
+          "pattern": "^(HC|AC)[0-9]+$",
+          "description": "The health check this criterion was adopted from (kaloko health adopt), e.g. HC302. The step's pack then leaves that check out of its health, so it is not shown twice. AC302 (written before the HC ids) reads as HC302."
+        },
+        "acceptance": {
+          "type": "boolean",
+          "description": "Set by the CLI on criteria of a pack that counts for acceptance (design, or health.acceptance). Without it a pack criterion is a health check: advisory, never part of a verdict."
+        },
         "environments": {
           "type": "array",
           "minItems": 1,