@@ -158,53 +158,16 @@ func TestRunGenAll_FillsEveryCardAndSkipsCardless(t *testing.T) {
 	}
 }
 
-// sectionFor returns the slice of a generated fence from "### <verb>" up to
-// the next "### " heading (or end of string). Local copy of the helper
-// skilldoc's own tests use — kept private to each package since exporting it
-// would blur GenerateFence's real API surface just for test convenience.
-func sectionFor(fence, verb string) string {
-	start := strings.Index(fence, "### "+verb)
-	if start < 0 {
-		return ""
-	}
-	rest := fence[start+len("### "+verb):]
-	if next := strings.Index(rest, "\n### "); next >= 0 {
-		return fence[start : start+len("### "+verb)+next]
-	}
-	return fence[start:]
-}
-
-// TestGenerateFence_ScheduleList_ResponseShapeMatchesRealLong is the
-// ground-truth cross-check the response-shape feature exists for. Before this
-// change, skills/flashduty/reference/schedule.md carried zero envelope
-// guidance for any of its verbs (unlike incident.md/change.md/automation.md/
-// enrichment.md/monit.md, the only 5 hand-written cards that happened to
-// note their envelope shape). `schedule list` in particular is real,
-// commonly-invoked, and — per the actual live CLI tree, not a fixture —
-// documents an `{items: [...]}` page wrapper, NOT a bare top-level array
-// (that phrasing belongs to the deprecated `oncall schedule list` twin, which
-// calls the same SDK method but is a different command path with no card).
-//
-// The expected shape/fields below are derived by independently re-scanning
-// that real Long text with throwaway logic — not by calling skilldoc's own
-// extractor and not by pasting a literal expected string — so this fails if
-// the generator's extraction ever silently drifts from what cligen actually
-// wrote for this command.
-func TestGenerateFence_ScheduleList_ResponseShapeMatchesRealLong(t *testing.T) {
-	d := dump()
-
-	var long string
-	found := false
-	for _, c := range d.Commands {
-		if c.Path == "schedule list" {
-			long, found = c.Long, true
-			break
-		}
-	}
-	if !found {
-		t.Fatal("schedule list not found in the real CLI dump — has it been renamed?")
-	}
-
+// independentlyClassifyResponse re-derives a command's response envelope
+// shape ("object" | "array" | "wrapped") and its top-level (or, for the
+// wrapped shape, per-row) field names straight from its raw Long text, using
+// logic deliberately NOT shared with skilldoc's own responseShapeLine
+// extractor (internal/skilldoc/generate.go) — a from-scratch re-read of the
+// same ground truth, not a call into the code under test. ok is false when
+// Long documents no Response fields block, or the block yields zero fields
+// at the target depth (skilldoc's own extractor also emits nothing for that
+// case — nothing to cross-check).
+func independentlyClassifyResponse(long string) (shape string, fields []string, ok bool) {
 	lines := strings.Split(long, "\n")
 	headerLine := -1
 	for i, l := range lines {
@@ -214,44 +177,132 @@ func TestGenerateFence_ScheduleList_ResponseShapeMatchesRealLong(t *testing.T) {
 		}
 	}
 	if headerLine < 0 {
-		t.Fatal("schedule list's real Long carries no Response fields block — has cligen's output changed?")
+		return "", nil, false
 	}
-	if !strings.Contains(lines[headerLine], "nested under items[]") {
-		t.Fatalf("expected schedule list to be an items[]-wrapped page response; real header was:\n%s", lines[headerLine])
+
+	header := lines[headerLine]
+	switch {
+	case strings.Contains(header, "nested under items[]"):
+		shape = "wrapped"
+	case strings.Contains(header, "TOP-LEVEL array"):
+		shape = "array"
+	default:
+		shape = "object"
+	}
+	prefix := "  - "
+	if shape == "wrapped" {
+		prefix = "    - " // one level under the sole top-level "items" row
 	}
-	var wantFields []string
 	for _, l := range lines[headerLine+1:] {
 		if strings.TrimSpace(l) == "" {
 			break
 		}
-		if strings.HasPrefix(l, "    - ") { // one level under the sole top-level "items" row
-			name := strings.TrimPrefix(l, "    - ")
-			if sp := strings.IndexAny(name, " ("); sp >= 0 {
-				name = name[:sp]
-			}
-			wantFields = append(wantFields, name)
+		if !strings.HasPrefix(l, prefix) {
+			continue
 		}
+		name := strings.TrimPrefix(l, prefix)
+		if sp := strings.IndexAny(name, " ("); sp >= 0 {
+			name = name[:sp]
+		}
+		fields = append(fields, name)
 	}
-	if len(wantFields) == 0 {
-		t.Fatal("independent scan of the real Long found no row fields under items — test logic is broken")
-	}
+	return shape, fields, len(fields) > 0
+}
 
-	fresh := skilldoc.GenerateFence(d, "schedule")
-	listSection := sectionFor(fresh, "list")
-	if listSection == "" {
-		t.Fatal("generated schedule fence has no `list` section")
-	}
-	if !strings.Contains(listSection, "page wrapper") || !strings.Contains(listSection, "jq '.items[]'") {
-		t.Errorf("schedule list card section must document the items[] page wrapper, got:\n%s", listSection)
-	}
-	if strings.Contains(listSection, "TOP-LEVEL array") {
-		t.Errorf("schedule list is NOT a top-level array — must not carry that phrasing:\n%s", listSection)
+// isCligenWrapperWireName mirrors (independently — not by import) the three
+// wire names cligen's own listEnvelope (internal/cmd/cligen/main.go) treats
+// as a paginated-list envelope field.
+func isCligenWrapperWireName(name string) bool {
+	return name == "items" || name == "docs" || name == "list"
+}
+
+// responseLineOf returns the "- response: ..." bullet inside a rendered fence
+// section, and whether one was present.
+func responseLineOf(section string) (string, bool) {
+	for _, l := range strings.Split(section, "\n") {
+		if strings.HasPrefix(strings.TrimSpace(l), "- response: ") {
+			return l, true
+		}
 	}
-	for _, f := range wantFields {
-		if !strings.Contains(listSection, f+" (") {
-			t.Errorf("schedule list card section missing real row field %q (from live Long):\n%s", f, listSection)
+	return "", false
+}
+
+// TestGenerateFence_ResponseShapeMatchesRealLong_AllCommands is the
+// coverage-complete ground-truth cross-check: for every real command whose
+// live Long (built from the actual CLI tree, not a fixture) documents a
+// Response fields block, independently reclassify its envelope shape and
+// field names (independentlyClassifyResponse, above — separate logic from
+// the generator) and assert the fence GenerateFence renders for that verb
+// agrees. A single hand-picked example (`schedule list`) proved the
+// mechanism works but only ever covered one of ~200 documented commands;
+// this walks the whole real dump, so a classification drift ANYWHERE in the
+// generator fails the build, not just for the one verb someone happened to
+// write a test against.
+func TestGenerateFence_ResponseShapeMatchesRealLong_AllCommands(t *testing.T) {
+	d := dump()
+
+	checked := 0
+	for _, c := range d.Commands {
+		wantShape, wantFields, hasBlock := independentlyClassifyResponse(c.Long)
+		if !hasBlock {
+			continue
+		}
+		checked++
+
+		// Render this ONE command in isolation (a single-command dump filtered
+		// to its own group) rather than slicing a section out of the whole
+		// group's fence: several real groups (e.g. "incident") flatten
+		// same-named leaves from different subgroups — "incident get" and
+		// "incident war-room get" both render as a "### get" heading — so a
+		// substring/heading search across the full group fence can grab the
+		// wrong command's section. A single-command fence has exactly one
+		// response line, unambiguously.
+		fence := skilldoc.GenerateFence(skilldoc.Dump{Commands: []skilldoc.Command{c}}, c.Group)
+		gotLine, hasLine := responseLineOf(fence)
+
+		// Mirrors the wrapper-drift guard in responseShapeLine: a response
+		// this classifier reads as a top-level object whose sole field is one
+		// of cligen's own list-envelope wire names (items/docs/list, array
+		// type) is a case the generator deliberately suppresses rather than
+		// assert a possibly-wrong shape. No real command hits this today
+		// (cligen's own header would already say "wrapped" for it), but nothing
+		// here should hard-fail if drift ever makes one — that is the guard
+		// working as designed, not a bug.
+		if wantShape == "object" && len(wantFields) == 1 && isCligenWrapperWireName(wantFields[0]) {
+			if hasLine {
+				t.Errorf("%s: expected the wrapper-drift guard to suppress this line (sole field %q looks like a list envelope), got:\n%s", c.Path, wantFields[0], gotLine)
+			}
+			continue
+		}
+
+		if !hasLine {
+			t.Errorf("%s: generated fence has no response line for a documented Response fields block", c.Path)
+			continue
+		}
+		switch wantShape {
+		case "wrapped":
+			if !strings.Contains(gotLine, "page wrapper") || !strings.Contains(gotLine, "jq '.items[]'") {
+				t.Errorf("%s: want items[] page wrapper, got:\n%s", c.Path, gotLine)
+			}
+		case "array":
+			if !strings.Contains(gotLine, "TOP-LEVEL array") {
+				t.Errorf("%s: want TOP-LEVEL array, got:\n%s", c.Path, gotLine)
+			}
+		default: // "object"
+			if !strings.Contains(gotLine, "single object") {
+				t.Errorf("%s: want single object, got:\n%s", c.Path, gotLine)
+			}
 		}
+		for _, f := range wantFields {
+			if !strings.Contains(gotLine, f+" (") {
+				t.Errorf("%s: missing real field %q (from live Long) in generated line:\n%s", c.Path, f, gotLine)
+			}
+		}
+	}
+	if checked < 100 {
+		t.Fatalf("only cross-checked %d commands — expected on the order of 200; did Response-fields detection break, or has the real CLI shrunk?", checked)
 	}
+	t.Logf("cross-checked response shape/fields for %d real commands", checked)
 }
 
 func TestRunGen_FillsFence(t *testing.T) {
 
@@ -329,6 +329,16 @@ var responseHeaderRe = regexp.MustCompile(`^Response fields \((.*)\):$`)
 // "    - person_ids (array<integer>) ...". Capture groups: indent, name, type.
 var responseFieldRe = regexp.MustCompile(`^( *)- ([a-zA-Z0-9_]+) \(([^)]*)\)`)
 
+// wrapperWireNames are the exact wire names cligen's own listEnvelope
+// (internal/cmd/cligen/main.go) treats as a paginated-list envelope field:
+// a sole array-typed sibling named items, docs, or list. Mirrored here as a
+// sanity check, not a duplicate classifier — see the guard in
+// responseShapeLine below.
+var wrapperWireNames = map[string]bool{"items": true, "docs": true, "list": true}
+
+// respField is one parsed Response-fields bullet row.
+type respField struct{ name, typ string }
+
 // responseShapeLine renders the one-line response-shape summary for a
 // command's Long, or "" when Long documents no Response fields block (mutation
 // verbs with an empty body, and a few hand-written commands that predate
@@ -363,7 +373,7 @@ func responseShapeLine(long string) string {
 		fieldIndent = "    " // one level under the sole top-level "items" row
 	}
 
-	var fields []string
+	var fields []respField
 	for _, line := range lines[headerIdx+1:] {
 		if strings.TrimSpace(line) == "" {
 			break
@@ -372,12 +382,28 @@ func responseShapeLine(long string) string {
 		if m == nil || m[1] != fieldIndent {
 			continue
 		}
-		fields = append(fields, m[2]+" ("+m[3]+")")
+		fields = append(fields, respField{m[2], m[3]})
 	}
 	if len(fields) == 0 {
 		return ""
 	}
 
+	// Safety net: this parser only ever recognizes the wrapped shape by the
+	// literal substring "nested under items[]" in the header (see the doc
+	// comment above the const block). If cligen's wording for that header
+	// ever drifts without this parser being updated to match, `wrapped` goes
+	// false here even though the response really is a page wrapper — and the
+	// sole top-level field is then exactly one of cligen's own wrapper wire
+	// names (items/docs/list, from listEnvelope in cligen/main.go), holding
+	// an array. Asserting "single object" in that case would be confidently
+	// WRONG about the one thing this whole feature exists to get right, so
+	// refuse to guess: say nothing rather than assert a shape we can no
+	// longer be sure of. A missing line is recoverable via `--help`; a
+	// wrong one isn't.
+	if !wrapped && len(fields) == 1 && wrapperWireNames[fields[0].name] && strings.HasPrefix(fields[0].typ, "array") {
+		return ""
+	}
+
 	var shape string
 	switch {
 	case wrapped:
@@ -387,5 +413,9 @@ func responseShapeLine(long string) string {
 	default:
 		shape = "single object (`data` unwrapped to the top level)"
 	}
-	return fmt.Sprintf("- response: %s — fields: %s\n", shape, strings.Join(fields, "; "))
+	names := make([]string, len(fields))
+	for i, f := range fields {
+		names[i] = f.name + " (" + f.typ + ")"
+	}
+	return fmt.Sprintf("- response: %s — fields: %s\n", shape, strings.Join(names, "; "))
 }
@@ -48,6 +48,45 @@ Request fields:
   --schedule-id int (required) — Schedule ID.
 `
 
+// driftedWrapperHeaderLong simulates a future cligen wording change to the
+// items[]-wrapper header that no longer contains the literal substring
+// "nested under items[]" this parser keys on (e.g. cligen's header text was
+// reworded from "rows are nested under items[]" to "rows appear inside
+// items[]"). The response is STILL genuinely items[]-wrapped — same shape as
+// itemsWrappedShapeLong above, just described differently — so this must
+// never be reported as "single object".
+const driftedWrapperHeaderLong = `List schedules.
+
+Response fields ('data' envelope is unwrapped — rows appear inside items[]):
+  - items (array<object>) (required) — Schedules on this page.
+    - schedule_id (integer) (required) — Schedule ID.
+`
+
+// driftedWrapperHeaderDocsLong is the same drift scenario but with cligen's
+// "docs" wire name (listEnvelope in internal/cmd/cligen/main.go recognizes
+// items/docs/list interchangeably as a list-envelope field) instead of
+// "items", to prove the guard isn't hardcoded to one wire name.
+const driftedWrapperHeaderDocsLong = `List reports.
+
+Response fields ('data' envelope is unwrapped — rows appear inside docs[]):
+  - docs (array<object>) (required) — Reports on this page.
+    - report_id (integer) (required) — Report ID.
+`
+
+// singleArrayFieldObjectLong is a GENUINE single-object response (per
+// cligen's own header, and correctly so — this mirrors the real
+// Automations.RuleReadList shape, whose sole top-level field is "rules", not
+// one of cligen's own list-envelope wire names) whose one top-level field
+// happens to be an array. The guard must NOT suppress this: only the exact
+// wrapper wire names (items/docs/list) are a drift signal, not "any object
+// with one array field".
+const singleArrayFieldObjectLong = `List automation rules.
+
+Response fields ('data' envelope is unwrapped — these fields are at the top level):
+  - rules (array<object>) (required) — Automation rules.
+    - rule_id (string) (required) — Rule ID.
+`
+
 func TestResponseShapeLine_Object(t *testing.T) {
 	got := responseShapeLine(objectShapeLong)
 	if !strings.Contains(got, "single object") {
@@ -112,6 +151,45 @@ func TestResponseShapeLine_NoBlockIsEmpty(t *testing.T) {
 	}
 }
 
+// TestResponseShapeLine_DriftedWrapperHeaderYieldsNothingNotWrongClaim covers
+// the failure mode a reviewer traced: if cligen's items[]-wrapper header
+// wording ever drifts away from the literal "nested under items[]" substring
+// this parser matches on, the shape must NOT silently fall through to
+// "single object" — that would be the exact confidently-wrong claim this
+// whole feature exists to prevent. It must instead emit nothing. Covers both
+// wrapper wire names cligen's listEnvelope recognizes: "items" and "docs".
+func TestResponseShapeLine_DriftedWrapperHeaderYieldsNothingNotWrongClaim(t *testing.T) {
+	for _, tc := range []struct {
+		name string
+		long string
+	}{
+		{"items", driftedWrapperHeaderLong},
+		{"docs", driftedWrapperHeaderDocsLong},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := responseShapeLine(tc.long)
+			if got != "" {
+				t.Errorf("drifted wrapper header must yield no response line (not a false 'single object' claim), got:\n%s", got)
+			}
+		})
+	}
+}
+
+// TestResponseShapeLine_SingleArrayFieldObjectIsNotSuppressed proves the
+// drift guard is scoped to cligen's own wrapper wire names (items/docs/list),
+// not "any object shape with exactly one array field" — a real, correctly
+// classified single-object response (mirroring Automations.RuleReadList,
+// whose sole field is "rules") must still render normally.
+func TestResponseShapeLine_SingleArrayFieldObjectIsNotSuppressed(t *testing.T) {
+	got := responseShapeLine(singleArrayFieldObjectLong)
+	if !strings.Contains(got, "single object") {
+		t.Errorf("a genuine single-object response with one array field must not be suppressed by the wrapper-drift guard:\n%s", got)
+	}
+	if !strings.Contains(got, "rules (array<object>)") {
+		t.Errorf("missing the rules field:\n%s", got)
+	}
+}
+
 // TestGenerateFence_InjectsResponseShapePerVerb is the fence-level integration
 // check: a group with one verb of each shape must surface a "- response: "
 // line in that verb's own section, and a verb with no documented response