feat(skilldoc): name a page-wrapper response's pagination siblings

The response-shape line for a `{items: [...]}` page-wrapper response only
ever named the row fields nested under "items" -- it silently dropped the
wrapper's OTHER top-level fields (total, has_next_page, search_after_ctx,
and similar pagination metadata cligen's listEnvelope documents alongside
"items"). A card would show a --search-after-ctx request flag for
pagination but never say where the returned cursor actually lives in the
response.

Name those siblings in the wrapper descriptor itself, e.g.:

  - response: `{items: [...], has_next_page, search_after_ctx, total}`
    page wrapper -- ... -- items fields: ...

("items fields:" replaces "fields:" for this shape only, so the row list
stays visually distinct from the siblings just named). Wrapper responses
with no such siblings render unchanged.

This also corrects two page-wrapper response instances (schedule `list`,
rum `application-list`) that used to render as duplicates of an unrelated
command's response purely because both had their real siblings dropped --
each now renders its own accurate shape.

Author: ysyneu

internal/skilldoc/generate.go

@@ -373,13 +373,21 @@ type respField struct{ name, typ string }
 //   - top-level object: the block's own fields are the response.
 //   - top-level array: `--json` is a bare array of these row objects — pipe
 //     `jq '.[]'`, never `.items[]`.
-//   - `{items: [...]}` page wrapper: the block's sole top-level field is
-//     `items`; the row fields are nested one level (2 spaces) deeper under it.
+//   - `{items: [...]}` page wrapper: the block's top-level array field is
+//     `items` (row fields nested one level deeper under it), alongside
+//     scalar pagination siblings — `total`, `has_next_page`,
+//     `search_after_ctx`, … (cligen's listEnvelope requires every
+//     non-`items` top-level field to be a scalar, so these are always
+//     pagination metadata, never more row data).
 //
 // Field names (with their documented type) are read from whichever indent
 // depth holds the actual row/object fields for the detected shape, so the
 // summary always names the fields an agent would pipe `jq` at — not the
-// wrapper key.
+// wrapper key. For the wrapper shape, the pagination siblings are named too
+// (by name only — their type is implied by cligen's scalar-sibling
+// invariant), since an agent told to paginate via `--search-after-ctx` still
+// needs to know the returned cursor lives at `.search_after_ctx` next to
+// `.items`, not buried in a field list it never sees.
 func responseShapeLine(long string) string {
 	lines := strings.Split(long, "\n")
 	headerIdx, header := -1, ""
@@ -396,19 +404,31 @@ func responseShapeLine(long string) string {
 	wrapped := strings.Contains(header, "nested under items[]")
 	fieldIndent := "  "
 	if wrapped {
-		fieldIndent = "    " // one level under the sole top-level "items" row
+		fieldIndent = "    " // one level under the top-level "items" row
 	}
 
-	var fields []respField
+	// fields holds the row-level fields the summary's "fields:" list names
+	// (top-level for object/array shapes, one level under "items" for the
+	// wrapper shape). siblings holds the wrapper shape's OTHER top-level
+	// fields — pagination metadata alongside "items" (total, has_next_page,
+	// search_after_ctx, …) — collected only when wrapped, since the
+	// unwrapped shapes have no such siblings to speak of.
+	var fields, siblings []respField
 	for _, line := range lines[headerIdx+1:] {
 		if strings.TrimSpace(line) == "" {
 			break
 		}
 		m := responseFieldRe.FindStringSubmatch(line)
-		if m == nil || m[1] != fieldIndent {
+		if m == nil {
 			continue
 		}
-		fields = append(fields, respField{m[2], m[3]})
+		indent, name, typ := m[1], m[2], m[3]
+		switch {
+		case indent == fieldIndent:
+			fields = append(fields, respField{name, typ})
+		case wrapped && indent == "  " && !wrapperWireNames[name]:
+			siblings = append(siblings, respField{name, typ})
+		}
 	}
 	if len(fields) == 0 {
 		return ""
@@ -430,18 +450,37 @@ func responseShapeLine(long string) string {
 		return ""
 	}
 
-	var shape string
+	var shape, fieldsLabel string
 	switch {
 	case wrapped:
-		shape = "`{items: [...]}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`)"
+		shape = fmt.Sprintf("`{items: [...]%s}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`)", siblingSuffix(siblings))
+		fieldsLabel = "items fields" // disambiguates row fields from the wrapper's own pagination siblings named above
 	case strings.Contains(header, "TOP-LEVEL array"):
 		shape = "TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`)"
+		fieldsLabel = "fields"
 	default:
 		shape = "single object (`data` unwrapped to the top level)"
+		fieldsLabel = "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, "; "))
+	return fmt.Sprintf("- response: %s — %s: %s\n", shape, fieldsLabel, strings.Join(names, "; "))
+}
+
+// siblingSuffix renders a wrapped response's top-level pagination-metadata
+// siblings — e.g. ", total, has_next_page, search_after_ctx" — appended
+// inside the `{items: [...]}` wrapper descriptor, in the order cligen
+// documented them. Empty when the envelope carries no siblings beyond the
+// row array itself.
+func siblingSuffix(siblings []respField) string {
+	if len(siblings) == 0 {
+		return ""
+	}
+	names := make([]string, len(siblings))
+	for i, s := range siblings {
+		names[i] = s.name
+	}
+	return ", " + strings.Join(names, ", ")
 }

internal/skilldoc/response_shape_test.go

@@ -48,6 +48,24 @@ Request fields:
   --schedule-id int (required) — Schedule ID.
 `
 
+// itemsWrappedWithPaginationSiblingsShapeLong reproduces the real shape of
+// `fduty insight incident-list` (internal/cli/zz_generated_analytics.go): a
+// page-wrapper response whose top level carries "items" ALONGSIDE scalar
+// pagination metadata — has_next_page, search_after_ctx, total — not just
+// "items" alone. cligen's listEnvelope requires every non-"items" top-level
+// field here to be a scalar, so these three are always pagination metadata,
+// never more row data.
+const itemsWrappedWithPaginationSiblingsShapeLong = `List insight incidents.
+
+Response fields ('data' envelope is unwrapped — rows are nested under items[]; pipe 'jq '.items[]'', NOT '.data.items[]'):
+  - has_next_page (boolean)
+  - items (array<object>)
+    - incident_id (string)
+    - title (string)
+  - search_after_ctx (string) — Cursor token to fetch the next page. Pass it back in the next request's 'search_after_ctx'.
+  - total (integer) — Total matching incidents.
+`
+
 // 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
@@ -145,6 +163,48 @@ func TestResponseShapeLine_ItemsWrapped(t *testing.T) {
 	}
 }
 
+// TestResponseShapeLine_ItemsWrappedNamesPaginationSiblings covers the real
+// `insight incident-list` shape: the wrapper's top level carries "items"
+// ALONGSIDE scalar pagination metadata (has_next_page, search_after_ctx,
+// total). Those siblings must be named in the wrapper descriptor itself —
+// an agent told to paginate via `--search-after-ctx` needs to know the
+// returned cursor lives at `.search_after_ctx` next to `.items`, not silently
+// dropped because the parser only ever looked one level under "items".
+func TestResponseShapeLine_ItemsWrappedNamesPaginationSiblings(t *testing.T) {
+	got := responseShapeLine(itemsWrappedWithPaginationSiblingsShapeLong)
+	if !strings.Contains(got, "items: [...]") || !strings.Contains(got, "page wrapper") {
+		t.Errorf("items[] wrapper shape not detected:\n%s", got)
+	}
+	// The siblings are named inside the wrapper descriptor, in the order
+	// cligen documented them (source order, already alphabetical here).
+	if !strings.Contains(got, "{items: [...], has_next_page, search_after_ctx, total}") {
+		t.Errorf("wrapper descriptor must name the pagination siblings:\n%s", got)
+	}
+	// The row fields (nested under items) are still named, under a label that
+	// disambiguates them from the siblings just named above.
+	if !strings.Contains(got, "items fields: incident_id (string); title (string)") {
+		t.Errorf("row fields must still be listed under an unambiguous label:\n%s", got)
+	}
+	// The siblings must not ALSO appear duplicated in the row-field list.
+	fieldsPart := strings.SplitN(got, "items fields:", 2)[1]
+	for _, sib := range []string{"has_next_page", "search_after_ctx", "total"} {
+		if strings.Contains(fieldsPart, sib) {
+			t.Errorf("pagination sibling %q must not be duplicated in the row-field list:\n%s", sib, got)
+		}
+	}
+}
+
+// TestResponseShapeLine_ItemsWrappedNoSiblingsUnchanged proves the sibling
+// feature is additive: a wrapper with no pagination siblings beyond "items"
+// (itemsWrappedShapeLong) renders the exact same wrapper descriptor as
+// before — no trailing ", " artifact from an empty sibling list.
+func TestResponseShapeLine_ItemsWrappedNoSiblingsUnchanged(t *testing.T) {
+	got := responseShapeLine(itemsWrappedShapeLong)
+	if !strings.Contains(got, "`{items: [...]}` page wrapper") {
+		t.Errorf("wrapper with no siblings must render the bare descriptor, got:\n%s", got)
+	}
+}
+
 func TestResponseShapeLine_NoBlockIsEmpty(t *testing.T) {
 	if got := responseShapeLine(noResponseBlockLong); got != "" {
 		t.Errorf("command with no Response fields block must yield no response line, got:\n%s", got)

skills/flashduty/reference/alert.md

@@ -60,7 +60,7 @@ List events for an alert
 - `--limit` int64 — Page size. Defaults to 20 and cannot exceed 100. (0-100)
 - `--page` int64 — Page number starting at 1. Used when 'search_after_ctx' is omitted. (min 0)
 - `--search-after-ctx` string — Cursor returned by the previous page. When supplied, cursor pagination is used instead of page-number pagination.
-- response: `{items: [...]}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — fields: account_id (integer); alert_id (string); alert_key (string); channel_id (integer); created_at (integer); data_source_id (integer); deleted_at (integer); description (string); event_id (string); event_severity (string); event_status (string); event_time (integer); images (array<object>); integration_id (integer); integration_type (string); labels (object); title (string); title_rule (string); updated_at (integer)
+- response: `{items: [...], has_next_page, search_after_ctx, total}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — items fields: account_id (integer); alert_id (string); alert_key (string); channel_id (integer); created_at (integer); data_source_id (integer); deleted_at (integer); description (string); event_id (string); event_severity (string); event_status (string); event_time (integer); images (array<object>); integration_id (integer); integration_type (string); labels (object); title (string); title_rule (string); updated_at (integer)
 
 ### events <alert_id>
 List alert events
@@ -74,7 +74,7 @@ List alert activity feed
 - `--page` int64 — Page number, starting at 1.
 - `--search-after-ctx` string
 - `--types` stringSlice — Filter by feed types.
-- response: `{items: [...]}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — fields: account_id (integer); created_at (integer); creator_id (integer); detail (object); ref_id (string); type (string); updated_at (integer)
+- response: `{items: [...], has_next_page}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — items fields: account_id (integer); created_at (integer); creator_id (integer); detail (object); ref_id (string); type (string); updated_at (integer)
 
 ### get <alert_id>
 Get alert detail
@@ -102,7 +102,7 @@ List alerts
 ### list-by-ids <alert-id> [<id2>...]
 List alerts by IDs
 - `<alert-ids>` (positional, required) stringSlice — List of alert IDs (ObjectID hex strings).
-- response: `{items: [...]}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — fields: account_id (integer); alert_id (string); alert_key (string); alert_severity (string); alert_status (string); channel_id (integer); channel_name (string); channel_status (string); created_at (integer); data_source_id (integer); data_source_name (string); data_source_ref_id (string); data_source_type (string); description (string); end_time (integer); event_cnt (integer); events (array<object>); ever_muted (boolean); images (array<object>); incident (object); integration_id (integer); integration_name (string); integration_ref_id (string); integration_type (string); labels (object); last_time (integer); responder_email (string); responder_name (string); start_time (integer); title (string); title_rule (string); updated_at (integer)
+- response: `{items: [...], has_next_page, search_after_ctx, total}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — items fields: account_id (integer); alert_id (string); alert_key (string); alert_severity (string); alert_status (string); channel_id (integer); channel_name (string); channel_status (string); created_at (integer); data_source_id (integer); data_source_name (string); data_source_ref_id (string); data_source_type (string); description (string); end_time (integer); event_cnt (integer); events (array<object>); ever_muted (boolean); images (array<object>); incident (object); integration_id (integer); integration_name (string); integration_ref_id (string); integration_type (string); labels (object); last_time (integer); responder_email (string); responder_name (string); start_time (integer); title (string); title_rule (string); updated_at (integer)
 
 ### merge <alert-id> [<id2>...]
 Merge alerts into an incident
@@ -120,7 +120,7 @@ Get alert pipeline
 ### pipeline-list <integration-id> [<id2>...]
 List alert pipelines
 - `<integration-ids>` (positional, required) intSlice — Integration IDs.
-- response: `{items: [...]}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — fields: created_at (integer); creator_id (integer); integration_id (integer); rules (array<object>); status (string); updated_at (integer); updated_by (integer)
+- response: `{items: [...]}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — items fields: created_at (integer); creator_id (integer); integration_id (integer); rules (array<object>); status (string); updated_at (integer); updated_by (integer)
 
 ### pipeline-upsert <integration-id>
 Create or update alert pipeline

skills/flashduty/reference/calendar.md

@@ -83,7 +83,7 @@ List calendar events
 - `--day` int64 — Day (1-31). 0 means no day filter. (0-31)
 - `--month` int64 — Month (1-12). 0 means no month filter. (0-12)
 - `--year` int64 — Year. Defaults to the current year when omitted. (min 2023)
-- response: `{items: [...]}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — fields: account_id (integer); cal_id (string); created_at (integer); creator_id (integer); description (string); end_at (string); event_id (string); is_off (boolean); start_at (string); summary (string); updated_at (integer)
+- response: `{items: [...], total}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — items fields: account_id (integer); cal_id (string); created_at (integer); creator_id (integer); description (string); end_at (string); event_id (string); is_off (boolean); start_at (string); summary (string); updated_at (integer)
 
 ### event-upsert <cal-id>
 Upsert calendar event
@@ -105,7 +105,7 @@ Get calendar info
 List calendars
 - `--kind` string — Calendar kind filter. Defaults to personal when empty. · enum: region.official.holiday | personal
 - `--no-locale` bool — Disable locale filtering when listing public-holiday calendars.
-- response: `{items: [...]}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — fields: account_id (integer); cal_id (string); cal_name (string); created_at (integer); creator_id (integer); description (string); extra_cal_ids (array<string>); kind (string); status (string); team_id (integer); timezone (string); updated_at (integer); updated_by (integer); workdays (array<integer>)
+- response: `{items: [...], total}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — items fields: account_id (integer); cal_id (string); cal_name (string); created_at (integer); creator_id (integer); description (string); extra_cal_ids (array<string>); kind (string); status (string); team_id (integer); timezone (string); updated_at (integer); updated_by (integer); workdays (array<integer>)
 
 ### update <cal-id>
 Update calendar