From 2152e85cd55b5b1a0c9bde29a8cf21894038aac5 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Thu, 23 Jul 2026 10:32:42 +0000
Subject: [PATCH] docs(s.unknown): add @example and fix header comment for
 description-form usage

s.unknown was the only s.* helper missing an @example block in its JSDoc.
All other helpers (s.array, s.object, s.record, s.enum, s.optional) already
show examples. The header comment also described it as s.unknown() implying
it must always be called, which differed from the "call as value or fn(desc)"
pattern documented for the primitive helpers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 skills/rig/rig.ts | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/skills/rig/rig.ts b/skills/rig/rig.ts
index d0a54a0..660979e 100644
--- a/skills/rig/rig.ts
+++ b/skills/rig/rig.ts
@@ -31,7 +31,7 @@
  * s.object(props,desc?) ObjectSchema; s.optional(inner) marks field optional; use for fixed-key shapes
  * s.record(valSchema,desc?) RecordSchema keyed by string; use for open-ended key→value maps
  * s.enum(...values|values,desc) EnumSchema
- * s.unknown() unconstrained JSON
+ * s.unknown unconstrained JSON; call as value or s.unknown("description")
  * p`...` PromptBuilder template tag; interpolates PromptIntent|string|PromptBuilder
  * p.bash(cmd,opts?) PromptIntent bash execution declaration (not run in-process)
  * p.read(path,opts?) PromptIntent file read declaration
@@ -200,7 +200,14 @@ export const s = {
   boolean: createTypedPrimitiveSchema<BooleanSchema>("boolean"),
   /** Schema for the JSON `null` literal. Call as `s.null` or `s.null("description")`. */
   null: createTypedPrimitiveSchema<NullSchema>("null"),
-  /** Schema for an unconstrained JSON value. Serializes to an empty schema object. */
+  /**
+   * Schema for an unconstrained JSON value. Serializes to an empty schema object.
+   * Call as `s.unknown` or `s.unknown("description")`.
+   *
+   * @example
+   * s.unknown                      // any JSON value
+   * s.unknown("raw API payload")   // any JSON value with description
+   */
   unknown: createUnknownSchema(),
   /**
    * Schema for a homogeneous array.