@wildo-ai/framework-knowledge 1.1.12 → 1.1.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/dist/claude-marketplace/.claude-plugin/marketplace.json +1 -1
  2. package/dist/claude-marketplace/plugins/wildo/.claude-plugin/plugin.json +1 -1
  3. package/dist/claude-marketplace/plugins/wildo/references/composites-and-the-loop.md +12 -4
  4. package/dist/claude-marketplace/plugins/wildo/skills/build/SKILL.md +4 -0
  5. package/dist/esm/framework-knowledge.definitions.d.ts +1 -1
  6. package/dist/esm/framework-knowledge.definitions.d.ts.map +1 -1
  7. package/dist/esm/framework-knowledge.definitions.js +10 -0
  8. package/dist/esm/framework-knowledge.definitions.js.map +1 -1
  9. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts +2 -1
  10. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.d.ts.map +1 -1
  11. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js +8 -1
  12. package/dist/esm/playbooks/bottom_up.foundation/playbook.definition.js.map +1 -1
  13. package/dist/knowledge/assurance-authority-bases/wildo-safe-baseline-v1/external-framework-mapping.json +1 -1
  14. package/dist/knowledge/manifest.json +7 -7
  15. package/dist/knowledge/playbooks/bottom_up.foundation/method.md +6 -0
  16. package/dist/knowledge/playbooks/bottom_up.foundation/playbook.json +6 -3
  17. package/dist/knowledge/playbooks/bottom_up.maturity-reading/method.md +9 -0
  18. package/dist/knowledge/playbooks/bottom_up.maturity-reading/playbook.json +1 -1
  19. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/method.md +11 -2
  20. package/dist/knowledge/playbooks/refinement.compliance-document-candidate/playbook.json +1 -1
  21. package/dist/knowledge/playbooks/top_down.requirements-definition/method.md +14 -0
  22. package/dist/knowledge/playbooks/top_down.requirements-definition/playbook.json +1 -1
  23. package/dist/knowledge/references/application-maturity.config.md +43 -0
  24. package/dist/knowledge/references/engine.client-bundle.allow-list.md +6 -0
  25. package/dist/knowledge/references/example.backend.addon-wiring.module.md +5 -1
  26. package/dist/knowledge/references/example.backend.custom-operation.declared-refusal-code.md +6 -0
  27. package/dist/knowledge/references/example.config.navigation.full.md +14 -0
  28. package/dist/knowledge/references/example.infra.environment-config.local.md +2 -2
  29. package/dist/knowledge/references/example.resource.config-wiring.retention-policy-operations.md +21 -0
  30. package/dist/knowledge/references/example.resource.status-lifecycle.quote.md +1 -1
  31. package/dist/knowledge/references/example.resource.ui-behavior.operation-icon.md +8 -2
  32. package/dist/knowledge/references/platform.config.environment.deployment.md +60 -4
  33. package/dist/knowledge/references/platform.config.infrastructure-host.md +1 -0
  34. package/dist/knowledge/references/platform.config.platform-key-management.md +5 -2
  35. package/dist/knowledge/references/requirements.engine-substance.md +38 -0
  36. package/dist/knowledge/references/requirements.functional-requirement.config.md +11 -0
  37. package/dist/knowledge/references/requirements.non-functional-requirement.config.md +11 -0
  38. package/dist/knowledge/references/saas.approval-seals.admin-endpoints.md +20 -0
  39. package/dist/knowledge/references/saas.backend.custom-operation.hook-transaction-posture.md +12 -1
  40. package/dist/knowledge/references/saas.backend.flows-actors.function-tool.md +72 -0
  41. package/dist/knowledge/references/saas.backend.system-access-service.md +30 -1
  42. package/dist/knowledge/references/saas.frontend.app-shell.shell-motion-contract.md +30 -0
  43. package/dist/knowledge/references/saas.frontend.chart-dashboard-view.md +3 -3
  44. package/dist/knowledge/references/saas.frontend.chart-dashboard.md +38 -35
  45. package/dist/knowledge/references/saas.models.chart-dashboard-tile-sizes.md +40 -0
  46. package/dist/knowledge/references/saas.models.flows-actors.agent-content-guardrails-environment.md +52 -0
  47. package/dist/knowledge/references/saas.models.frontend-provider-public-config-contract.md +6 -0
  48. package/dist/knowledge/references/saas.models.organization-dashboard-layout.md +61 -0
  49. package/dist/knowledge/references/saas.models.privacy.data-residency.md +188 -31
  50. package/dist/knowledge/references/saas.models.providers.compliance-choice.md +9 -0
  51. package/dist/knowledge/references/saas.models.resource-config.operation-condition-parameters.md +8 -1
  52. package/dist/knowledge/references/saas.specifications.processor-register.md +10 -0
  53. package/dist/knowledge/registries/assurance-authority-bases.json +1 -1
  54. package/dist/knowledge/registries/framework-topics.json +41 -1
  55. package/dist/knowledge/registries/playbooks.json +1 -1
  56. package/dist/knowledge/registries/source-tags.json +1147 -1077
  57. package/dist/knowledge/skills/backend-addon-wiring/SKILL.md +5 -1
  58. package/dist/knowledge/skills/backend-custom-operation/references/declared-refusal-codes.md +28 -1
  59. package/dist/knowledge/skills/backend-custom-operation/references/framework-hook-transaction-posture-api.md +32 -1
  60. package/dist/knowledge/skills/compliance-document-authoring/references/document-composition-privacy-notice.md +11 -2
  61. package/dist/knowledge/skills/compliance-document-authoring/references/framework-processor-register-authoring.md +16 -0
  62. package/dist/knowledge/skills/compliance-document-authoring/references/framework-provider-compliance-choice-api.md +197 -31
  63. package/dist/knowledge/skills/config-app-shell/references/framework-shell-layout-api.md +30 -0
  64. package/dist/knowledge/skills/config-navigation/SKILL.md +14 -0
  65. package/dist/knowledge/skills/config-saas/references/compliance-declarations.md +19 -0
  66. package/dist/knowledge/skills/config-saas/references/framework-key-management-api.md +58 -1
  67. package/dist/knowledge/skills/electronic-signature-deliverables/references/what-makes-a-request-signed.md +20 -3
  68. package/dist/knowledge/skills/flows-actors-autonomous-agents/SKILL.md +12 -2
  69. package/dist/knowledge/skills/flows-actors-chat-assistant/SKILL.md +16 -4
  70. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-agent-content-guardrails-api.md +144 -6
  71. package/dist/knowledge/skills/flows-actors-chat-assistant/references/framework-flows-actors-tool-api.md +72 -0
  72. package/dist/knowledge/skills/flows-actors-declared-flow/SKILL.md +12 -2
  73. package/dist/knowledge/skills/flows-actors-llm-agent-invocation/SKILL.md +12 -2
  74. package/dist/knowledge/skills/frontend-component-catalog/SKILL.md +1 -1
  75. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-catalog.md +3 -2
  76. package/dist/knowledge/skills/frontend-component-catalog/references/framework-component-usage.md +13 -0
  77. package/dist/knowledge/skills/infra-environment-config/SKILL.md +36 -8
  78. package/dist/knowledge/skills/infra-environment-config/references/framework-agent-content-guardrails-environment-api.md +67 -0
  79. package/dist/knowledge/skills/infra-environment-config/references/framework-environment-deployment-api.md +60 -4
  80. package/dist/knowledge/skills/infra-environment-config/references/framework-infrastructure-host-api.md +1 -0
  81. package/dist/knowledge/skills/infra-environment-config/references/framework-platform-key-management-api.md +5 -2
  82. package/dist/knowledge/skills/layout-2d-adoption/references/framework-shell-motion-api.md +30 -0
  83. package/dist/knowledge/skills/provider-backend-package/SKILL.md +17 -3
  84. package/dist/knowledge/skills/provider-frontend-file-picker/references/framework-frontend-public-config-api.md +6 -0
  85. package/dist/knowledge/skills/provider-frontend-module/references/package-frontend-facets.md +4 -1
  86. package/dist/knowledge/skills/resource-config-wiring/SKILL.md +6 -2
  87. package/dist/knowledge/skills/resource-config-wiring/references/framework-operation-audit-api.md +4 -2
  88. package/dist/knowledge/skills/resource-config-wiring/references/framework-retention-policy-operations.md +21 -0
  89. package/dist/knowledge/skills/resource-config-wiring/references/framework-system-access-reads-api.md +30 -1
  90. package/dist/knowledge/skills/resource-status-lifecycle/SKILL.md +3 -2
  91. package/dist/knowledge/skills/resource-status-lifecycle/references/framework-operation-condition-parameters-api.md +8 -1
  92. package/dist/knowledge/skills/resource-status-lifecycle/references/quote-lifecycle-worked-example.md +3 -3
  93. package/dist/knowledge/skills/resource-ui-behavior/SKILL.md +8 -2
  94. package/dist/knowledge/skills/views-chart-authoring/SKILL.md +5 -1
  95. package/dist/knowledge/skills/views-composite-authoring/SKILL.md +1 -1
  96. package/dist/knowledge/skills/views-composite-authoring/references/framework-chart-dashboard-api.md +166 -39
  97. package/dist/knowledge/skills/website-bundle-discipline/SKILL.md +6 -0
  98. package/dist/knowledge/skills/website-bundle-discipline/references/website-bundle-rules.md +6 -0
  99. package/dist/knowledge/topic-index.json +292 -153
  100. package/dist/tsconfig.build.tsbuildinfo +1 -1
  101. package/package.json +4 -4
@@ -242,6 +242,20 @@ export const navigationLayoutConfig: NavigationLayout = {
242
242
  transitions: {
243
243
  /* A reference inside the pane stacks in the pane; back returns to the todo beneath. */
244
244
  [CoreResourceOperation.READ]: NavigationTransition.PUSH,
245
+ /*
246
+ * Mutations open a dialog from the pane exactly as they do from the page. A zone's map answers only for
247
+ * navigations started IN that zone (the resolver borrows primary's map for an overlay source, never for a
248
+ * pane), so a pane that named only READ sent "Edit" on a todo to the framework fallback: the form was pushed
249
+ * into the pane, took the todo's place, and wrote its URL (#3764). The layout's stated rule above is
250
+ * "mutations → overlay", and a todo is edited from the pane more often than from anywhere else.
251
+ */
252
+ [CoreResourceOperation.CREATE]: NavigationTransition.OVERLAY,
253
+ [CoreResourceOperation.UPDATE]: NavigationTransition.OVERLAY,
254
+ [CoreResourceOperation.DELETE]: NavigationTransition.OVERLAY,
255
+ [CoreResourceOperation.SEARCH]: NavigationTransition.OVERLAY,
256
+ },
257
+ appearance: {
258
+ overlay: OverlayAppearance.DIALOG,
245
259
  },
246
260
  onEmpty: ZoneEmptyBehavior.COLLAPSE,
247
261
  responsiveCollapse: {
@@ -80,6 +80,25 @@ never holds a residency `wildo config sync` would refuse. A provider with severa
80
80
  deployment model to choose, or a region of yours outside is left to you and listed by `wildo context
81
81
  launch-blockers` with the regions that would do; place it, then run the foundation again.
82
82
 
83
+ Many SaaS vendors keep data AT REST in the region you pick but process it elsewhere (support tools, chat,
84
+ document workspaces). Under `territories` alone they are refused. If you are willing to make the weaker promise
85
+ for them, add `storedAtRestTerritories` beside `territories`:
86
+
87
+ ```ts
88
+ operatorComplianceIdentity: {
89
+ dataResidency: { territories: ['eu'], storedAtRestTerritories: ['eu'] },
90
+ },
91
+ ```
92
+
93
+ A vendor whose chosen region processes outside `territories` is then admitted when every place that region keeps
94
+ data at rest, as its provider profile states (`storageRegionTerritories`), lies inside `storedAtRestTerritories`.
95
+ It never counts as inside the processing residency: its entry reads `inside-at-rest`, and the governed documents
96
+ say for it that the data is stored in the region and may be processed elsewhere. A vendor whose profile states no
97
+ storage places is still refused. The foundation keeps the list when it writes `territories`, places a provider on
98
+ it only when none of the provider's regions processes inside, and, when you have declared none, tells you which
99
+ regions declaring one over the same places would admit. It never declares one for you: the promise is yours.
100
+ An organization may narrow both lists, and one that declares no at-rest list admits no storage-only vendor.
101
+
83
102
  To see every part still owed, with the rest of what stands between the application and launch:
84
103
 
85
104
  ```bash
@@ -326,6 +326,16 @@ export const ApprovalSealsAdminEndpointPath = {
326
326
  * which no copy can be made (`reason` names why, `detail` says more).
327
327
  */
328
328
  MANIFESTED_COPY_REBUILD: '/manifested-copy/rebuild',
329
+ /**
330
+ * POST — whether ONE seal's approval is still CURRENT over the record it is about (#2914): `{ "sealId": "…" }` →
331
+ * {@link ApprovalSealCurrencyResult}. The seal's presentation carries the values of the fields its tool declared the
332
+ * approval covers (`sealedRecordFields`); they are compared with the record as it is now. CURRENT right after the
333
+ * approval, NO_LONGER_CURRENT once one of them changed, SUBJECT_GONE when the record is gone, NO_SEALED_FIELD_SET when
334
+ * the seal covers no record field. Names which fields moved, never a value, so it is not recorded on the trail. 404 for
335
+ * an unknown seal (a seal its approver's erasure retained is not read here); 409 for one whose presentation file is
336
+ * unreadable or not the one its row recorded.
337
+ */
338
+ CURRENCY: '/currency',
329
339
  } as const;
330
340
 
331
341
  /**
@@ -411,6 +421,16 @@ export interface ApprovalSealRetryResult {
411
421
  readonly sealed: boolean;
412
422
  }
413
423
 
424
+ /** `POST /currency`'s answer (#2914). Names no person and no value. */
425
+ export interface ApprovalSealCurrencyResult {
426
+ readonly sealId: string;
427
+ readonly standing: ApprovalSealSubjectCurrency;
428
+ /** The record compared, as the seal names it; absent for NO_SEALED_FIELD_SET. */
429
+ readonly subject?: { readonly resourceType: string; readonly resourceId: string };
430
+ /** Each sealed field's currency (CURRENT / CHANGED / ABSENT); absent unless compared. */
431
+ readonly fields?: readonly { readonly key: string; readonly currency: HumanDecision_PresentedFieldCurrency }[];
432
+ }
433
+
414
434
  /** `POST /manifested-copy/rebuild`'s answer. */
415
435
  export interface ApprovalSealManifestedCopyRebuildResult {
416
436
  readonly sealId: string;
@@ -455,7 +475,7 @@ record of its key, the issuer, and the disclosures the row still holds (the peop
455
475
  statement). Each export is recorded (`approval_seal_exported`); a seal kept after its approver's erasure
456
476
  needs `--operator` and `--justification`. A person's own data export also carries their seals' key
457
477
  records (`verificationKeys`), and leaves out the requester and what was presented, which are other
458
- people's data. Seals are not part of a portability export: the operator made them. To verify a seal, `wildo seal verify <bundle.json>` reads `{ jws, keys, expectedIssuer?, disclosures?, erasedClaims?, deliverableFile?, manifestedCopy? }`, where each key is its stored record (`publishedVerificationKeys`: kid, public JWK,
478
+ people's data. Seals are not part of a portability export: the operator made them. To verify a seal, `wildo seal verify <bundle.json>` reads `{ jws, keys, expectedIssuer?, disclosures?, erasedClaims?, deliverableFile?, manifestedCopy?, vendorSignedCopies? }`, where each key is its stored record (`publishedVerificationKeys`: kid, public JWK,
459
479
  scope, scope id, issuer, state) and calls nothing. It pins ES256 from the key record, ignores any key
460
480
  the token names, refuses an organization key used for another tenant, checks each disclosure against
461
481
  its commitment, and reports content the seal commits to and the bundle does not give without failing
@@ -479,6 +499,29 @@ changed byte and the seal does not verify. A file the engine cannot hash (a remo
479
499
  keeps the bytes, a missing file, a file of another organization) is shown and sealed as not bound, never
480
500
  bound to an empty hash.
481
501
 
502
+ When the person approves what a RECORD says (a month's figures signed off, an invoice's amounts), declare
503
+ the fields the approval covers, `sealedRecordFields` on the function tool, beside
504
+ `argumentsResource: { resourceType, rowIdArgument }`. The card then shows those fields of the row the call
505
+ names, read when the card is built, and the seal commits to them inside its presentation, so you can ask
506
+ later whether the approval still holds: `wildo seal currency <sealId>` (the operator door
507
+ `POST /internal/admin/approval-seals/currency`) answers CURRENT, NO_LONGER_CURRENT with the fields that
508
+ moved (never their values), SUBJECT_GONE, or NO_SEALED_FIELD_SET; offline,
509
+ `wildo seal verify <bundle.json> --subject-record <record.json>` compares the same values with the record
510
+ you give, and reports a change without failing the seal. Name only what the approval is about, never a
511
+ status, a timestamp or the column the approved call writes the seal's id into: those change when the
512
+ approval is recorded, and would make every approval stale at once. A card read before one of the values
513
+ changed is refused as stale. In your own code, `assessApprovalSealCurrency` (from
514
+ `@wildo-ai/saas-backend-lib`) and `approvalSealSubjectCurrencyOf` (from `@wildo-ai/saas-models`) give the
515
+ same answer. A record of another organization than the decision's is shown and sealed with no values, and
516
+ so is an answer clicked on a chat card: no chat card shows the record, so its seal claims none of it.
517
+
518
+ When the same decision is taken again on a record after the record was reopened (signed off, reopened,
519
+ signed off again), it is a NEW decision, and its seal names no predecessor unless you declare
520
+ `approvalReplacesEarlierApprovalOfRow: true` on the tool: its seal then supersedes the latest seal of that
521
+ tool on that record (`supersedesSealId`, and `supersedes` in the signed claims), as a decision answered
522
+ again supersedes its own earlier answer, and the trail records the earlier one `approval_seal_superseded`.
523
+ An approval made through another tool on the same row is never superseded.
524
+
482
525
  When the approved file is a PDF, the engine also makes its **manifested copy** as it seals: a separate
483
526
  file holding the original byte for byte, followed by a last page naming the approver, the date and time
484
527
  of the decision, the meaning and outcome and the seal's identity, with the seal's JWS attached
@@ -506,6 +549,20 @@ checks the seal, not the document. A copy that was not made, or is gone, is rebu
506
549
  `wildo seal rebuild-copy <sealId> --justification "…"`, recorded on the audit trail as
507
550
  `approval_seal_manifested_copy_rebuilt`; a seal whose copy is present is refused.
508
551
 
552
+ The same original may also have been signed through an electronic-signature vendor (the
553
+ `ELECTRONIC_SIGNATURE` capability): the vendor's copy is another file derived from it, with lineage role
554
+ `VENDOR_SIGNED_COPY`. A seal's bundle names every such copy of a SIGNED request that followed the seal
555
+ (`vendorSignedCopies`: the file id, the file its row says it derives from, the hash its row recorded).
556
+ `wildo seal verify <bundle.json> --vendor-signed-copy <file>` (repeatable) checks that the copy's first
557
+ revision, ending at a `%%EOF`, is the approved file, and reports which original it derives from. A copy
558
+ whose row names another original, or that does not start with the approved file, fails the seal (and,
559
+ when you call the verifier yourself, so do bytes that are not the ones the row recorded). Only a copy the
560
+ bundle names with these exact bytes is reported as
561
+ the signed copy your application recorded; a file the bundle does not name is reported as starting with
562
+ the approved file and nothing more, since anyone holding the original can append to it. The vendor's own
563
+ signature is not re-checked here: the engine validated it when the signed document arrived, and that
564
+ evidence is the signature request's `validationEvidence` file.
565
+
509
566
  ## Pinning your keys
510
567
 
511
568
  The host holds the keys and publishes their public halves, so on its own your application can only
@@ -40,8 +40,23 @@ signer or a lower level ends it FAILED.
40
40
 
41
41
  A SIGNED request names two files of its own, written in the same move: the signed PDF (a vendor-signed copy of the
42
42
  original) and the validation's evidence as JSON (each signature, its chain, the check date, and every CRL and OCSP
43
- response used). They go with the request when its record goes, and the record's legal holds keep them. The audit trail
44
- records each sending, each move (with the hashes and the signers), each late event and each cancellation.
43
+ response used). They go with the request when its record goes, and the record's legal holds keep them. Where your
44
+ application scans files, the signed PDF is linked to its request once its scan ends; the poll does it, so nothing is lost
45
+ while the scan runs. The audit trail records each sending, each move (with the hashes and the signers), each late event
46
+ and each cancellation.
47
+
48
+ ## Watching it
49
+
50
+ The poll's batch output counts what each run sent, moved, linked and left pending. The metrics answer whether signing is
51
+ healthy without reading the audit rows:
52
+
53
+ | Metric | Labels | Worth an alert when |
54
+ |---|---|---|
55
+ | `signature_request_sent_total` | `outcome` (`sent` or the refusal), `required_level` | a refusal other than `already_open` keeps appearing |
56
+ | `signature_request_moved_total` | `provider`, `to` | `to="failed"` appears (a signer or level that can never be met) |
57
+ | `signature_request_evidence_refused_total` | `provider`, `failure` | any `failure` but `rejected`: the engine cannot validate or keep evidence |
58
+ | `signature_request_vendor_not_read_total` | `provider` | it rises steadily: the vendor is down |
59
+ | `signature_request_evidence_link_total` | `outcome` | `outcome="lost"`: a SIGNED request names evidence nothing keeps |
45
60
 
46
61
  ## Notifications
47
62
 
@@ -58,4 +73,6 @@ poll re-reads that request within five minutes.
58
73
  it delegated to, and current).
59
74
  - OCSP is read when the signature carries it, never fetched; the CRL is fetched instead.
60
75
  - The appearance a signature field draws is not inspected.
61
- - Contact data comes from the operator's database, unless the vendor's identity proofing does not rely on it.
76
+ - Signers are invited, and their certificate's e-mail compared, at the address in your database. Someone who can change
77
+ a signer's address can receive their invitation. Requiring identity proofing that does not rely on that data (an
78
+ identity document or eID checked by the vendor, proved by the certificate it issues) is designed and not yet available.
@@ -83,8 +83,18 @@ A screening or moderation declaration with no content-safety provider makes the
83
83
  fails closed, by design, and it does so in EVERY environment that cannot serve it, so a provider and its
84
84
  secrets authored for `local` only leave the agent refusing every turn in staging and production. The
85
85
  backend warns at startup, one line per such agent, and `wildo local doctor` lists every authored
86
- environment that cannot serve it. Until the application selects a provider, declare `personalData`, and write one
87
- line at the agent saying which of the other two it will declare and why. A guardrail that cannot treat
86
+ environment that cannot serve it. On the development machine the classifier is usually a local double: the
87
+ provider's host secret names `127.0.0.1:<port>`, and `wildo local dev` starts the double on that port when the
88
+ application's root `package.json` declares `"@wildo-ai/provider-simulators": "*"` in its `devDependencies` (add it
89
+ in the same task that selects the provider). Without it nothing answers there, and every guarded turn is withheld
90
+ locally as `OUTPUT_NOT_MODERATED`. Two registry providers serve it: `azure-content-safety` screens and moderates
91
+ (its own Azure resource), `openai-moderation` moderates only, free, with an OpenAI key. An environment that is meant to
92
+ run without one (a staging stack with no key for it, while production has one) does not drop the declaration: it
93
+ states `agentContentGuardrails: { withoutClassifier: RUN_UNGUARDED, reason }` in its `wildo.infra.<env>.config.ts`, and
94
+ the agent runs unguarded there, named at startup. Never author that for an environment because a provider's setup is
95
+ pending; it is the operator's decision, and the infra-environment-config skill describes it. Until the application
96
+ selects a provider, declare `personalData`, and write one line at the agent saying which of the other two it will
97
+ declare and why. A guardrail that cannot treat
88
98
  anything (an agent with no tools and no conversation, fed only text your code composes) is not declared at
89
99
  all: a declaration that does nothing reads as a control. The contract and every refusal are in the
90
100
  `flows-actors-chat-assistant` skill, `references/framework-agent-content-guardrails-api.md`.
@@ -162,7 +162,9 @@ where none can serve it the agent refuses every turn, the backend warns at start
162
162
  environment. To keep what it
163
163
  **writes** within a content policy (no hate, sexual content, violence or self-harm reaching a person, a record or a
164
164
  message), declare `contentGuardrails.outputModeration` with the severity to withhold per category. See
165
- `references/framework-agent-content-guardrails-api.md`.
165
+ `references/framework-agent-content-guardrails-api.md`. When a reply instead reads *"This reply couldn't be checked
166
+ against the content policy"*, the classifier is configured and did not answer (on a development machine, usually its
167
+ local double is not running): that reference's section of the same name diagnoses it from the turn's audit event.
166
168
 
167
169
  Every agent call leaves an **operation record** (`agentOperationRecords`): the model the provider answered with, each tool
168
170
  call and how it ended, what the guardrails decided and how the call ended, never what a tool returned. You write
@@ -213,8 +215,18 @@ A screening or moderation declaration with no content-safety provider makes the
213
215
  fails closed, by design, and it does so in EVERY environment that cannot serve it, so a provider and its
214
216
  secrets authored for `local` only leave the agent refusing every turn in staging and production. The
215
217
  backend warns at startup, one line per such agent, and `wildo local doctor` lists every authored
216
- environment that cannot serve it. Until the application selects a provider, declare `personalData`, and write one
217
- line at the agent saying which of the other two it will declare and why. A guardrail that cannot treat
218
+ environment that cannot serve it. On the development machine the classifier is usually a local double: the
219
+ provider's host secret names `127.0.0.1:<port>`, and `wildo local dev` starts the double on that port when the
220
+ application's root `package.json` declares `"@wildo-ai/provider-simulators": "*"` in its `devDependencies` (add it
221
+ in the same task that selects the provider). Without it nothing answers there, and every guarded turn is withheld
222
+ locally as `OUTPUT_NOT_MODERATED`. Two registry providers serve it: `azure-content-safety` screens and moderates
223
+ (its own Azure resource), `openai-moderation` moderates only, free, with an OpenAI key. An environment that is meant to
224
+ run without one (a staging stack with no key for it, while production has one) does not drop the declaration: it
225
+ states `agentContentGuardrails: { withoutClassifier: RUN_UNGUARDED, reason }` in its `wildo.infra.<env>.config.ts`, and
226
+ the agent runs unguarded there, named at startup. Never author that for an environment because a provider's setup is
227
+ pending; it is the operator's decision, and the infra-environment-config skill describes it. Until the application
228
+ selects a provider, declare `personalData`, and write one line at the agent saying which of the other two it will
229
+ declare and why. A guardrail that cannot treat
218
230
  anything (an agent with no tools and no conversation, fed only text your code composes) is not declared at
219
231
  all: a declaration that does nothing reads as a control. The contract and every refusal are in the
220
232
  `flows-actors-chat-assistant` skill, `references/framework-agent-content-guardrails-api.md`.
@@ -576,7 +588,7 @@ export const moduleBackend_FlowsActorsRegistry: {
576
588
  - `references/framework-present-records-tool-api.md` — `presentRecordsTool()`: the agent shows its person records as summary cards in the conversation, kept as a reference and fetched with the viewer's session
577
589
  - `references/framework-retrieval-tool-api.md` — `retrievalTool()`: the agent searches your `.ragSource()` fields as its person, cites the record and field of each passage, and reads `outcome` before answering
578
590
  - `references/framework-ask-person-tool-api.md` — `askPersonTool()`: the agent pauses its turn to ask its person a structured question, answered through a form, and gets typed answers back
579
- - `references/framework-agent-content-guardrails-api.md` — `contentGuardrails.personalData` (what the model is sent in place of a personal field's value, who reads the real values back, the `personalDataOutput` every tool declares), `contentGuardrails.promptInjection` (screening what others wrote before the model reads it), `contentGuardrails.outputModeration` (judging what the model writes before anyone reads, stores or sends it) and `argumentsResource` on every write tool (what a guarded write may store)
591
+ - `references/framework-agent-content-guardrails-api.md` — `contentGuardrails.personalData` (what the model is sent in place of a personal field's value, who reads the real values back, the `personalDataOutput` every tool declares), `contentGuardrails.promptInjection` (screening what others wrote before the model reads it), `contentGuardrails.outputModeration` (judging what the model writes before anyone reads, stores or sends it), `argumentsResource` on every write tool (what a guarded write may store), and how to diagnose a reply withheld because the classifier did not answer (`OUTPUT_NOT_MODERATED`, the local double `wildo local dev` starts)
580
592
  - `references/framework-agent-suspension-api.md` — an administrator's runtime off switch for one agent: who may suspend and resume it (an organization's administrator, or the application's super-administrator for everybody), what a suspended agent's caller and conversation see, what is audited, and what a suspension does not stop
581
593
  - `references/framework-agent-operation-record-api.md` — the `agentOperationRecords` row every agent call leaves: the model the provider reported, each tool call and how it ended, the guardrail verdicts and the end, never a tool's result; how to read it per run and as counts through the evidence door, and its retention
582
594
  - `references/framework-agent-behavior-reports-api.md` — a person reports an agent's reply from the conversation (a closed category, an optional comment; the report points at the reply and never copies it), the organization's administrators triage, resolve or dismiss it against declared deadlines, and how it is audited, erased and measured
@@ -107,9 +107,9 @@ contentGuardrails: { promptInjection: { screening: FlowsActors_PromptInjectionSc
107
107
  naming where the content came from, and routed to the organization's SIEM.
108
108
  4. A failed tool tells the model only the kind of failure: an error's text can carry what a third party wrote.
109
109
  5. The classifier is the provider selected for `EngineCapability.AI_CONTENT_SAFETY`. Without one, or where provider calls
110
- are not recorded, the agent refuses to run: running unscreened is what the declaration prevents. The first provider is
111
- Azure AI Content Safety's Prompt Shields: `wildo registry add wildo/providers/azure-content-safety`, then follow its
112
- own skill.
110
+ are not recorded, the agent refuses to run: running unscreened is what the declaration prevents. The provider that
111
+ screens is Azure AI Content Safety's Prompt Shields: `wildo registry add wildo/providers/azure-content-safety`, then
112
+ follow its own skill. (`openai-moderation` moderates output only and does not screen.)
113
113
 
114
114
  Not screened, deliberately: the message of a person driving their own conversation, and the answer they give to the
115
115
  agent's question (`askPersonTool`), which are their own words on their own authority.
@@ -140,8 +140,15 @@ contentGuardrails: {
140
140
  4. Each withholding is recorded on the audit trail (`agent_output_withheld`, `agent_output_moderation_failed`) with the
141
141
  categories and severities, never the text. What the provider generated is still metered.
142
142
  5. The classifier is the provider selected for `EngineCapability.AI_CONTENT_SAFETY`, and it must assess every category
143
- your policy names; Azure AI Content Safety assesses all four. Without one, or where provider calls are not recorded,
144
- the agent refuses to run. Under `personalData` the classifier receives the placeholders, never the values.
143
+ your policy names. Two registry providers moderate output, and both assess all four:
144
+
145
+ | provider | grades severity | cost | also screens prompt injection |
146
+ |---|---|---|---|
147
+ | `azure-content-safety` | LOW / MEDIUM / HIGH | the application's Azure resource (a free tier exists) | yes |
148
+ | `openai-moderation` | no: a flag reads as HIGH, so every threshold withholds what OpenAI flags | free, an OpenAI API key | no |
149
+
150
+ Without one, or where provider calls are not recorded, the agent refuses to run. Under `personalData` the classifier
151
+ receives the placeholders, never the values.
145
152
 
146
153
  A call the person APPROVED is not judged again when it runs: its input was judged when the turn paused for approval.
147
154
 
@@ -171,10 +178,141 @@ Two places say so before a person's turn does:
171
178
  dev companion is running, and otherwise passes saying the agents were not probed.
172
179
 
173
180
  The remedy is the same in both: in each environment named, enable `EngineCapability.AI_CONTENT_SAFETY`, give the
174
- backend scope a provider that serves it, and author that provider's secrets; or remove the declaration from the agent.
181
+ backend scope a provider that serves it, and author that provider's secrets; or remove the declaration from the agent;
182
+ or, deliberately, declare that the environment runs its agents unguarded (next section).
175
183
  An organization's policy that switches screening or moderation on is refused when it is saved unless a classifier can
176
184
  serve it then; if the environment later loses its classifier, the startup count above is where that shows.
177
185
 
186
+ ## Running an environment without a classifier, on purpose
187
+
188
+ Some environments are meant to run without a classifier: a staging stack nobody pays a vendor for, or a production
189
+ launched before one is bought. Not a good practice, and a common one. Do not delete the declaration from the agent for
190
+ that, and do not look for a classifier that answers "safe" to everything (there is none, on purpose: an agent that looks
191
+ guarded and is not is worse than one that refuses). STATE it, in that environment's
192
+ `infrastructure/<env>/wildo.infra.<env>.config.ts`:
193
+
194
+ ```ts
195
+ agentContentGuardrails: {
196
+ withoutClassifier: AgentContentGuardrailsWithoutClassifier.RUN_UNGUARDED,
197
+ reason: 'Staging has no Azure Content Safety key; production authors one.',
198
+ },
199
+ ```
200
+
201
+ ## Import Origins
202
+
203
+ - `@wildo-ai/saas-models`
204
+
205
+ ## Source Excerpts
206
+
207
+ ### Origin Package: `@wildo-ai/saas-models`
208
+
209
+ ```typescript
210
+ *
211
+ * What an environment does with an agent's classifier-backed content guardrails (`contentGuardrails.promptInjection`,
212
+ * `contentGuardrails.outputModeration`) when NO classifier for the guardrail is present there: its configuration declares
213
+ * no provider for `EngineCapability.AI_CONTENT_SAFETY`, the provider it selects does not offer that guardrail, or that
214
+ * provider's credentials are not authored in this environment's `secrets.json → providerEnv`. Imported
215
+ * from `@wildo-ai/saas-models`; authored as `agentContentGuardrails` in `infrastructure/<env>/wildo.infra.<env>.config.ts`.
216
+ */
217
+ export enum AgentContentGuardrailsWithoutClassifier {
218
+ /** The default, and what an environment that authors nothing gets: the agent refuses every turn. */
219
+ REFUSE = 'refuse',
220
+ /**
221
+ * The agent runs without each guardrail no classifier is present for here (its tool results unscreened, or its output
222
+ * unmoderated). A classifier that is there and cannot be used is never waived: a declared provider that did not load or
223
+ * a category it does not assess still refuses the turn, and a key that is set and refused, or an outage, still
224
+ * withholds the output. Named at startup, and listed by launch-blockers outside a local environment.
225
+ */
226
+ RUN_UNGUARDED = 'run_unguarded',
227
+ }
228
+
229
+ /**
230
+ * The environment's declaration. `reason` is required with `RUN_UNGUARDED`: it is printed beside every agent the backend
231
+ * leaves unguarded, so the next reader knows it was decided, and by whom or why.
232
+ *
233
+ * ```ts
234
+ * agentContentGuardrails: {
235
+ * withoutClassifier: AgentContentGuardrailsWithoutClassifier.RUN_UNGUARDED,
236
+ * reason: 'Staging has no Azure Content Safety key; production authors one.',
237
+ * },
238
+ * ```
239
+ */
240
+ export const EnvironmentAgentContentGuardrailsSchema = z.discriminatedUnion('withoutClassifier', [
241
+ z.strictObject({
242
+ withoutClassifier: z.literal(AgentContentGuardrailsWithoutClassifier.REFUSE),
243
+ }),
244
+ z.strictObject({
245
+ withoutClassifier: z.literal(AgentContentGuardrailsWithoutClassifier.RUN_UNGUARDED),
246
+ reason: z.string().trim().min(10, 'Say why this environment runs its agents unguarded (at least 10 characters).').max(500),
247
+ }),
248
+ ]);
249
+ export type EnvironmentAgentContentGuardrails = z.output<typeof EnvironmentAgentContentGuardrailsSchema>;
250
+ ```
251
+
252
+ Then run `wildo config sync`. What changes in that environment only:
253
+
254
+ 1. A guardrail for which NO classifier is present there runs without it: none is declared for `AI_CONTENT_SAFETY`, the selected one does not offer that guardrail
255
+ (`openai-moderation` does not screen), or its credentials (its key, or the host slot it reads) are not authored in
256
+ this environment's `secrets.json → providerEnv`.
257
+ Its tool results and inbound deliveries reach the model unscreened, or its output leaves unmoderated. A classifier
258
+ that offers moderation but not screening (`openai-moderation`) waives only screening. The classifier is declared once
259
+ for the application in `wildo.saas.config.ts`, so leaving its credentials out of one environment is how that
260
+ environment runs without it while another has it.
261
+ 2. A classifier that IS there and cannot be used is NOT waived: that is a failure. A provider declared and not loaded,
262
+ or a category it does not assess, refuses the turn; a key that is set and refused, or the vendor down, withholds the
263
+ output.
264
+ 3. The backend's startup log names every such agent as `RUNS UNGUARDED`, with your `reason`, on every boot.
265
+ 4. Outside a local environment, `wildo context launch-blockers` lists the environment until a classifier is selected
266
+ there or the declaration is removed.
267
+ 5. An organization's administrator still cannot switch screening or moderation ON there: the write is refused, because
268
+ nothing could provide it.
269
+
270
+ The declaration on the agent stays, so the environment that selects a classifier enforces it with no edit. An
271
+ application that wants no guardrail anywhere simply declares none on its agents.
272
+
273
+ ## "This reply couldn't be checked against the content policy"
274
+
275
+ That is what a person reads when a reply, or a tool call the model wrote, was withheld as `OUTPUT_NOT_MODERATED`: a
276
+ classifier IS configured, and it did not give a verdict for this turn. Both checks above pass in that case (they read
277
+ configuration, not whether the classifier answers), so diagnose it from what the turn recorded:
278
+
279
+ 1. Find the `agent_output_moderation_failed` audit event for the turn (or the backend's
280
+ `An agent's output was withheld by its output moderation` WARN with the same `executionId`). Its `failureReason`
281
+ names the cause and its `outputKind` what was being judged (`text`, `tool_input`, …). Never the text itself.
282
+ 2. Read the cause:
283
+
284
+ | `failureReason` says | Cause | Remedy |
285
+ |---|---|---|
286
+ | `was unreachable … ECONNREFUSED` | Nothing answers at the provider's host. On a development machine, the local double is not running | See "On a development machine" below |
287
+ | the provider answered `401` / `403` | The key in `providerEnv` is not the one the classifier (or the double) accepts | Re-author the key slot with `wildo secrets set` |
288
+ | a spend ceiling | The application's screening allowance is used up | Raise the ceiling or wait for its period (`references/framework-model-spend-limits-api.md`) |
289
+ | a category left out | The classifier does not assess a category the policy names | Drop the category from the policy, or select a classifier that assesses it |
290
+
291
+ Once the cause is fixed the person can send the message again, after checking what the turn already did: no reply was
292
+ stored and the withheld output's tool call (with the other calls of its step) did not run, but a tool called in an
293
+ EARLIER step of the same turn did. The turn's trace lists those calls; resending repeats a write that already landed.
294
+
295
+ ### On a development machine
296
+
297
+ A provider whose LOCAL host secret names this machine (`AZURE_CONTENT_SAFETY_HOST=127.0.0.1:<port>`, in
298
+ `infrastructure/local/secrets/secrets.json → providerEnv`) is served by a local double, not by the vendor.
299
+ `wildo local dev` starts that double itself, on that port and accepting that key, before the application's processes,
300
+ and restarts it if it stops: look for `Starting the azure-content-safety double` in its output. It needs the doubles'
301
+ package: add `"@wildo-ai/provider-simulators": "*"` to the `devDependencies` of the application's root `package.json`,
302
+ then run `wildo config sync` and `pnpm install`. Without it, `wildo local dev` warns that the double cannot be started,
303
+ and every guarded agent's turn is withheld until something answers on the port.
304
+
305
+ If the stack is already running and the double has died, restart `wildo local dev`. Or run the double alone in another
306
+ terminal, with the port and key from the two secrets:
307
+
308
+ ```bash
309
+ CONTENT_SAFETY_MOCK_PORT=<port> CONTENT_SAFETY_MOCK_API_KEY=<key> pnpm exec wildo-provider-simulators-content-safety
310
+ ```
311
+
312
+ The double judges every text SAFE unless it carries a harm marker (`WILDO-SIMULATED-HARM-Violence` reaches the top
313
+ severity in Violence), which is how a test makes it withhold. It proves the guardrails are wired, not that real content
314
+ is moderated well: that needs the real classifier in a deployed environment.
315
+
178
316
  ## An organization can only tighten them
179
317
 
180
318
  Each organization can make the guardrails of the agents that work on its records STRICTER than they declare, never
@@ -434,6 +434,42 @@ export interface FunctionTool {
434
434
  * has no top-level string argument of that name. A tool without it is unaffected.
435
435
  */
436
436
  deliverableFileArgument?: string;
437
+ /**
438
+ * The fields of the row the call acts on that the approval COVERS (#2914): the record's SEALED FIELD SET. Declare it
439
+ * on an approval-gated tool whose approval is a statement about a record's values (a month's figures signed off, an
440
+ * invoice's amounts approved), so that whether the approval still holds can be answered later:
441
+ *
442
+ * - the decision's card shows these values of the row named by `argumentsResource.rowIdArgument`, read as the system
443
+ * when the card is built, so the person approves what they read; a card read before one of them changed is refused
444
+ * as stale;
445
+ * - the approval's seal commits to them inside its presentation, and the currency check
446
+ * (`approvalSealSubjectCurrencyOf`, the operator door `POST /internal/admin/approval-seals/currency`, and
447
+ * `wildo seal verify --subject-record`) compares them with the record as it is: CURRENT right after the approval,
448
+ * NO_LONGER_CURRENT once one of them changes.
449
+ *
450
+ * Name only what the approval is ABOUT. Never a lifecycle or approval field (a status, `updatedAt`, the column the
451
+ * approved call writes the seal's id or the signer into): the approved call's own write would otherwise make its own
452
+ * seal look stale. A row of another organization than the decision's, or one that cannot be read, is shown and sealed
453
+ * with no record values, and so is an answer given on a chat card: no notice card shows the row, so its SENT seal
454
+ * claims none of it (its currency reads NO_SEALED_FIELD_SET).
455
+ *
456
+ * Registration refuses it on a tool that is not approval-gated, on a question tool, without
457
+ * `argumentsResource.rowIdArgument`, and when it names no field, a field twice, or a field the resource's main schema
458
+ * does not declare (checked when the resource is registered).
459
+ */
460
+ sealedRecordFields?: readonly string[];
461
+ /**
462
+ * An approval of this tool on a row REPLACES the latest earlier approval of this tool on the same row (#2914): its seal
463
+ * names that earlier seal as the one it supersedes, as a decision answered again supersedes its own earlier seal. For a
464
+ * decision that is taken again on the same record after the record was reopened (a month signed off, reopened and
465
+ * signed off again): the two are different decisions, and without this the second seal names no predecessor, so a
466
+ * verifier sees two approvals of one record and nothing saying which one stands.
467
+ *
468
+ * Only the latest seal of the same source, the same record (`argumentsResource.rowIdArgument`) and the same tool is
469
+ * superseded, never an approval made through another tool on that row; a decision answered again still supersedes its
470
+ * own earlier answer first. Requires an approval gate and `argumentsResource.rowIdArgument`.
471
+ */
472
+ approvalReplacesEarlierApprovalOfRow?: boolean;
437
473
  /**
438
474
  * The electronic signature the file deliverable needs once the person approved it (#2293): after the approval's seal is
439
475
  * SEALED, the engine sends the approved file (`deliverableFileArgument`, bound by its hash) to the vendor selected for
@@ -1116,6 +1152,42 @@ export function functionToolDeliverableDeclarationProblems(
1116
1152
  return problems;
1117
1153
  }
1118
1154
 
1155
+ /**
1156
+ * What is wrong with a tool's record-approval declarations (`sealedRecordFields`, `approvalReplacesEarlierApprovalOfRow`,
1157
+ * #2914), one sentence per problem with its remedy; empty when they are sound or absent. `declaredFieldsOf` answers the
1158
+ * fields the resource's main schema declares, or undefined when the resource is not registered (its fields are then not
1159
+ * checked here: a field the row does not hold is shown and sealed as absent).
1160
+ */
1161
+ export function functionToolRecordApprovalDeclarationProblems(
1162
+ tool: Pick<FunctionTool, 'functionRef' | 'sealedRecordFields' | 'approvalReplacesEarlierApprovalOfRow' | 'argumentsResource' | 'requiresHumanApproval' | 'humanApproval' | 'asksThePerson'>,
1163
+ declaredFieldsOf?: (resourceType: string) => readonly string[] | undefined,
1164
+ ): string[] {
1165
+ const fields = tool.sealedRecordFields;
1166
+ const replaces = tool.approvalReplacesEarlierApprovalOfRow === true;
1167
+ if (fields === undefined && !replaces) return [];
1168
+ const problems: string[] = [];
1169
+ const named = `Function tool "${tool.functionRef}" declares ${fields !== undefined ? 'sealedRecordFields' : 'approvalReplacesEarlierApprovalOfRow'}`;
1170
+ if (!tool.humanApproval && !tool.requiresHumanApproval) {
1171
+ problems.push(`${named} and is not approval-gated: it describes what an approval covers, so gate it (humanApproval or requiresHumanApproval).`);
1172
+ }
1173
+ if (tool.asksThePerson) problems.push(`${named} and asks the person: a question approves no record.`);
1174
+ if (!tool.argumentsResource?.rowIdArgument) {
1175
+ problems.push(`${named} without argumentsResource.rowIdArgument: name the argument holding the id of the row the approval is about.`);
1176
+ }
1177
+ if (fields !== undefined) {
1178
+ if (!Array.isArray(fields) || fields.length === 0 || fields.some((field) => typeof field !== 'string' || field.trim().length === 0)) {
1179
+ problems.push(`${named}, which names no field: list the fields of the row the approval covers.`);
1180
+ } else {
1181
+ const duplicated = fields.filter((field, index) => fields.indexOf(field) !== index);
1182
+ if (duplicated.length > 0) problems.push(`${named}, which names ${[...new Set(duplicated)].join(', ')} more than once.`);
1183
+ const declared = tool.argumentsResource ? declaredFieldsOf?.(tool.argumentsResource.resourceType) : undefined;
1184
+ const unknown = declared ? fields.filter((field) => !declared.includes(field)) : [];
1185
+ if (unknown.length > 0) problems.push(`${named}, naming ${unknown.join(', ')}, which ${tool.argumentsResource!.resourceType} does not declare.`);
1186
+ }
1187
+ }
1188
+ return problems;
1189
+ }
1190
+
1119
1191
  /** Whether an argument schema is a string once its optional, nullable and default wrappers are removed. */
1120
1192
  function isStringArgumentSchema(schema: z.ZodTypeAny): boolean {
1121
1193
  let current: z.ZodTypeAny = schema;
@@ -81,8 +81,18 @@ A screening or moderation declaration with no content-safety provider makes the
81
81
  fails closed, by design, and it does so in EVERY environment that cannot serve it, so a provider and its
82
82
  secrets authored for `local` only leave the agent refusing every turn in staging and production. The
83
83
  backend warns at startup, one line per such agent, and `wildo local doctor` lists every authored
84
- environment that cannot serve it. Until the application selects a provider, declare `personalData`, and write one
85
- line at the agent saying which of the other two it will declare and why. A guardrail that cannot treat
84
+ environment that cannot serve it. On the development machine the classifier is usually a local double: the
85
+ provider's host secret names `127.0.0.1:<port>`, and `wildo local dev` starts the double on that port when the
86
+ application's root `package.json` declares `"@wildo-ai/provider-simulators": "*"` in its `devDependencies` (add it
87
+ in the same task that selects the provider). Without it nothing answers there, and every guarded turn is withheld
88
+ locally as `OUTPUT_NOT_MODERATED`. Two registry providers serve it: `azure-content-safety` screens and moderates
89
+ (its own Azure resource), `openai-moderation` moderates only, free, with an OpenAI key. An environment that is meant to
90
+ run without one (a staging stack with no key for it, while production has one) does not drop the declaration: it
91
+ states `agentContentGuardrails: { withoutClassifier: RUN_UNGUARDED, reason }` in its `wildo.infra.<env>.config.ts`, and
92
+ the agent runs unguarded there, named at startup. Never author that for an environment because a provider's setup is
93
+ pending; it is the operator's decision, and the infra-environment-config skill describes it. Until the application
94
+ selects a provider, declare `personalData`, and write one line at the agent saying which of the other two it will
95
+ declare and why. A guardrail that cannot treat
86
96
  anything (an agent with no tools and no conversation, fed only text your code composes) is not declared at
87
97
  all: a declaration that does nothing reads as a control. The contract and every refusal are in the
88
98
  `flows-actors-chat-assistant` skill, `references/framework-agent-content-guardrails-api.md`.
@@ -115,8 +115,18 @@ A screening or moderation declaration with no content-safety provider makes the
115
115
  fails closed, by design, and it does so in EVERY environment that cannot serve it, so a provider and its
116
116
  secrets authored for `local` only leave the agent refusing every turn in staging and production. The
117
117
  backend warns at startup, one line per such agent, and `wildo local doctor` lists every authored
118
- environment that cannot serve it. Until the application selects a provider, declare `personalData`, and write one
119
- line at the agent saying which of the other two it will declare and why. A guardrail that cannot treat
118
+ environment that cannot serve it. On the development machine the classifier is usually a local double: the
119
+ provider's host secret names `127.0.0.1:<port>`, and `wildo local dev` starts the double on that port when the
120
+ application's root `package.json` declares `"@wildo-ai/provider-simulators": "*"` in its `devDependencies` (add it
121
+ in the same task that selects the provider). Without it nothing answers there, and every guarded turn is withheld
122
+ locally as `OUTPUT_NOT_MODERATED`. Two registry providers serve it: `azure-content-safety` screens and moderates
123
+ (its own Azure resource), `openai-moderation` moderates only, free, with an OpenAI key. An environment that is meant to
124
+ run without one (a staging stack with no key for it, while production has one) does not drop the declaration: it
125
+ states `agentContentGuardrails: { withoutClassifier: RUN_UNGUARDED, reason }` in its `wildo.infra.<env>.config.ts`, and
126
+ the agent runs unguarded there, named at startup. Never author that for an environment because a provider's setup is
127
+ pending; it is the operator's decision, and the infra-environment-config skill describes it. Until the application
128
+ selects a provider, declare `personalData`, and write one line at the agent saying which of the other two it will
129
+ declare and why. A guardrail that cannot treat
120
130
  anything (an agent with no tools and no conversation, fed only text your code composes) is not declared at
121
131
  all: a declaration that does nothing reads as a control. The contract and every refusal are in the
122
132
  `flows-actors-chat-assistant` skill, `references/framework-agent-content-guardrails-api.md`.
@@ -230,7 +230,7 @@ once you have a candidate.
230
230
  - **App** (11) — `AppLayout_ConsentGate`, `AppLayout_DocumentAcceptanceGate`, `AppLayout_ErrorBoundary`, `AppLayout_Home`, `AppLayout_MainContainer`, `AppLayout_RouterErrorBoundary`, `Files_UploadGrantDrop`, `PublicLayout_LegalNotice`, `PublicLayout_MainContainer`, `PublicLayout_StaticContentContainer`, `PublicLayout_Terms`
231
231
  - **Auth** (15) — `Auth_AuthCallback`, `Auth_ChatIdentityLink`, `Auth_ConfirmEmail`, `Auth_EnrollmentRequired`, `Auth_Invitation`, `Auth_MagicLinkVerify`, `Auth_Main`, `Auth_MfaChallenge`, `Auth_OAuthConsent`, `Auth_OAuthLoggedOut`, `Auth_OAuthLogoutConfirm`, `Auth_OneOffSession`, `Auth_OrganizationOnboarding`, `Auth_PasswordLost`, `Auth_Register`
232
232
  - **Billing** (6) — `BillingPortalLink`, `InvoiceHistory`, `PlanChangePreview`, `PricingTable`, `SubscriptionStatus`, `UsageDashboard`
233
- - **Data Display** (10) — `Avatar`, `Badge`, `DescriptionDetails`, `DescriptionList`, `DescriptionTerm`, `Duration`, `Identifier`, `Kbd`, `NotificationIndicator`, `Timeline`
233
+ - **Data Display** (11) — `Avatar`, `Badge`, `DescriptionDetails`, `DescriptionList`, `DescriptionTerm`, `Duration`, `Identifier`, `Kbd`, `NotificationIndicator`, `RecordApprovalSeal`, `Timeline`
234
234
  - **Data Display / Formatters** (25) — `DisplayFieldAddress`, `DisplayFieldBigDecimal`, `DisplayFieldBoolean`, `DisplayFieldCode`, `DisplayFieldDate`, `DisplayFieldDateTime`, `DisplayFieldDuration`, `DisplayFieldEnum`, `DisplayFieldFile`, `DisplayFieldFileAudio`, `DisplayFieldFileDocument`, `DisplayFieldFileGallery`, `DisplayFieldFileImage`, `DisplayFieldFileVideo`, `DisplayFieldMoney`, `DisplayFieldNumber`, `DisplayFieldPhone`, `DisplayFieldRangeBigDecimal`, `DisplayFieldRangeDate`, `DisplayFieldRangeDateTime`, `DisplayFieldRangeMoney`, `DisplayFieldRangeNumber`, `DisplayFieldRangeTime`, `DisplayFieldString`, `DisplayFieldTime`
235
235
  - **Feedback** (10) — `AppCelebrationOverlay`, `DangerZone`, `EmptyState`, `ErrorDisplay`, `LoadingOverlay`, `LoadingSpinner`, `OperationsConfirmCritical`, `Progress`, `Skeleton`, `Toaster`
236
236
  - **Feedback / Features** (4) — `FeatureLimitIndicator`, `FeatureLockBadge`, `FeatureUnavailableDialog`, `FeatureUnavailablePrompt`
@@ -162,7 +162,7 @@ an application reaches those through configuration, never through JSX.
162
162
  | `SubscriptionStatus` | Unavailable slices render an explicit unavailable state instead of empty or zero data; independently available billing panels remain usable. Read-only status panel with optional actions to manage billing. | Use on account settings and billing overview routes. | Avoid for users without an active billing subject. |
163
163
  | `UsageDashboard` | Unavailable slices render an explicit unavailable state instead of empty or zero data; usage and credit balance availability are independent, so either section can remain usable when the other fails. Dashboard cards/charts fed by billing usage APIs. | Use when plans include metered entitlements or quota warnings. | Avoid when billing is flat-rate without usage signals. |
164
164
 
165
- ## Data Display (10)
165
+ ## Data Display (11)
166
166
 
167
167
  | Component | Renders | Use when | Avoid when |
168
168
  | --- | --- | --- | --- |
@@ -175,6 +175,7 @@ an application reaches those through configuration, never through JSX.
175
175
  | `Identifier` | Monospaced, wrapping, receding behind the prose it identifies; the same treatment the field pipeline gives StringDisplayMode.IDENTIFIER. | Use wherever a surface renders an address a machine assigned rather than words a person wrote, including on hand-built rows outside the field pipeline. | Avoid for prose, for a human-authored name, and for a code BLOCK (use the code artifact element, which owns scrolling and copy). |
176
176
  | `Kbd` | A small quiet key cap in the monospaced face on the inset surface; the same cap wherever an application names a key. | Use wherever a surface tells a reader what to press: a shortcut hint on a control, a hotkey help list, a keyboard-driven list that says so. | Avoid for a machine address (Identifier) and for inline code (the CODE typography variant): a key cap depicts a control, not a value. |
177
177
  | `NotificationIndicator` | A small count bubble, a colored signal dot, or nothing — surfaced on nav items and shell affordances. | Use to surface a notification-badge definition’s live count/dot on a sidebar item or shell control. | Avoid for arbitrary status chips (use `Badge`); this is driven by a resolved notification-badge count. |
178
+ | `RecordApprovalSeal` | A card on a record's READ surface. Its badge names the seal's state (sealed, pending, seal failed, superseded, approver erased, no seal); its facts name the approver from the seal itself, so an approver who has left the organization still shows; a record changed since the approval lists the changed fields by their labels, never their values; a signed seal offers a check of its signature, a download of the deliverable's manifested copy, and a link to the public check page. | Use `RecordApprovalSeal field="<the record's seal id field>"` in the DISPLAY template of a resource that stores an approval seal's id when the approved effect happens (a close storing `signOffApprovalSealId` when it is signed off). | Do not use for a record that stores no seal id: a seal is shown only where the record names it, so the component cannot find one by itself. Do not use for who-decided fields alone (`signedOffByUserId`): show those as fields. Do not use for an electronic signature request sent to a signature vendor; that is the signature request's own status. |
178
179
  | `Timeline` | Compound: `Timeline` (the rail, an ordered list), `TimelineEntry` (tone, optional custom marker; under a `selectable` rail, `option` + `selected` make it a pickable grid row — never a listbox option, because an entry carries `TimelineActions` and an option may not contain a control), `TimelineMarker`, `TimelineTime`, `TimelineBody`, `TimelineActions`. Renders in DOM order; ordering, filtering, elapsed clocks and words are the consumer's. | Use for any stream of things that happened in order — runs, dispatches, writes, a flow execution's events, an audit trail — wherever a reader asks what happened, then what. | Avoid for a sequence a person WALKS (the stepper), for an unordered set (a list card), and for a reasoning trace with nested content (the chain-of-thought elements). |
179
180
 
180
181
  ## Data Display / Formatters (25)
@@ -189,7 +190,7 @@ an application reaches those through configuration, never through JSX.
189
190
  | `DisplayFieldDateTime` | Timestamp display for point-in-time fields. | Use for audit timestamps, “last updated”, and scheduling instants. | Avoid for wall-time-only values; consider date or time slots. |
190
191
  | `DisplayFieldDuration` | Readable duration formatter for interval-backed fields. | Use when the schema represents a time span rather than an instant. | Avoid for single timestamps; use date, datetime, or time slots. |
191
192
  | `DisplayFieldEnum` | Read-only enum label resolver for constrained string/enum fields. | Use when displaying picklist values in resource read views or summaries. | Avoid when the raw stored token should remain visible for debugging; use the string slot instead. |
192
- | `DisplayFieldFile` | File reference display cell with optional actions. | Use for arbitrary file attachments where MIME-specific previews are not required. | Avoid when a dedicated image, video, or audio preview slot is registered for the same shape. |
193
+ | `DisplayFieldFile` | File reference display cell with optional actions. On a record's DISPLAY surface, a single file a person approved by its hash (an approval seal's deliverable, #2913) shows that seal under it (`FileApprovalSeal`): who approved it, when, as what, its signed copy and a check; a file no seal attests shows nothing more, and a SUMMARY never asks. | Use for arbitrary file attachments where MIME-specific previews are not required. | Avoid when a dedicated image, video, or audio preview slot is registered for the same shape. |
193
194
  | `DisplayFieldFileAudio` | Read-only audio attachment cell. | Use for podcast clips, voicemails, or other audio blobs. | Avoid when only a download link is required; the generic file slot may suffice. |
194
195
  | `DisplayFieldFileDocument` | Read-only document attachment cell. | Use for contracts, PDFs, and office documents. | Avoid for inline text extraction views; those belong in higher-level readers. |
195
196
  | `DisplayFieldFileGallery` | Read-only gallery layout for several image files. | Use when the field stores multiple images shown together. | Avoid for a single image; prefer the image file slot. |