Skip to content

Commit d78f22a

Browse files
committed
docs: drop hand-written prose now redundant with generated response lines
Five spots restated a verb's response envelope shape by hand, now fully covered by that verb's own generated "- response: ..." line: - monit.md: targets response-shape restatement removed; kept the updated_at="last seen, not online now" fact, which is real knowledge. - role.md: two bullets restating permission-list (items[]) and permission-factor-list (top-level array) shapes, both fully redundant. - team.md: infos and list gotchas trimmed to drop the shape restatement; kept the positional-args fact for infos. - channel.md: one bullet summarizing list + rule-list shapes collectively, now subsumed by the per-verb generated lines. - monit-query.md: rows bullet trimmed to drop the shape assertion; kept the values/fields semantics and the __value__ canonical key fact.
1 parent 2af6f67 commit d78f22a

5 files changed

Lines changed: 3 additions & 7 deletions

File tree

skills/flashduty/reference/channel.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -310,7 +310,6 @@ Update channel
310310
- **`channel create` requires `--channel-name` and `--team-id`** even though they are not marked `required` in the flag list — the server rejects the request without them.
311311
- **`delete` on a channel is irreversible** — all rules within it are also removed. Confirm the `channel-id` against `list` before proceeding.
312312
- **Empty rule list is authoritative** — if `escalate-rule-list` / `silence-rule-list` / etc. returns no rows, no rules exist; do not widen the query.
313-
- **`list` response is a top-level array** (pipe `jq '.[]'`); rule-list responses nest under `items[]` (pipe `jq '.items[]'`).
314313

315314
## Worked example — look up a channel and inspect its escalation policy
316315

skills/flashduty/reference/monit-query.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ Raw datasource passthrough (returns values/rows as the datasource itself would)
5252

5353
## Key concepts
5454

55-
- **`rows` = raw passthrough.** Response `data` is a **top-level array** of row objects — pipe `jq '.[]'`, NOT `.items[]`. Numeric fields under `values` (metric canonical key `__value__`); labels/columns under `fields`. **Time belongs in the query expression**, not in flags.
55+
- **`rows` = raw passthrough.** Numeric fields under `values` (metric canonical key `__value__`); labels/columns under `fields`. **Time belongs in the query expression**, not in flags.
5656
- **`diagnose` = pre-clustered evidence.** Its versioned response echoes the datasource, query, and RFC 3339 analysis window. Each result contains method-specific `pattern_evidence` (logs) or `series_evidence` (metrics), structured window statistics, and observations; log results also declare redaction and untrusted observed-data paths in `data_handling`. Takes `--time-start` / `--time-end` (relative like `-1h`, `now`, or unix seconds).
5757

5858
## Gotchas

skills/flashduty/reference/monit.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -374,7 +374,7 @@ Invoke target tools
374374

375375
**`query-diagnose` output**: results are versioned evidence, not the former summary-only pattern/series lists. Read `pattern_evidence` for logs or `series_evidence` for metrics; their optional comparison fields are absent when the edge has no evidence. Log output also includes `data_handling`, which declares redaction coverage and paths carrying untrusted observed data.
376376

377-
**`targets` response shape** — rows are under `items[]` (not `data[]`); pipe `jq '.items[]'`, not `jq '.[]'`. `updated_at` means "last seen", not "online now".
377+
**`targets`**: `updated_at` means "last seen", not "online now".
378378

379379
## Gotchas
380380

skills/flashduty/reference/role.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -118,8 +118,6 @@ Create or update a role
118118

119119
- **`permission-id` vs `permission-factor`**: `permission-list` returns coarse permission objects (id, name, class, scope, type=read|manage) — use these ids in `upsert --permission-ids`. `permission-factor-list` returns fine-grained factors (api/button/menu/url/visit strings like `template:read:info`) — useful for auditing what a permission covers, but not accepted by `upsert`.
120120
- **`permission-list --with-all`**: returns every permission in the system with `is_granted=true/false` for the requested `--role-ids`. Omit `--role-ids` + `--with-all` to see the full catalog without annotation.
121-
- **`permission-list` response shape**: rows are under `items[]` — pipe `jq '.items[]'`, NOT `.data.items[]`.
122-
- **`permission-factor-list` response shape**: top-level array — pipe `jq '.[]'`, NOT `.items[]`.
123121

124122
## Gotchas
125123

skills/flashduty/reference/team.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ Create or update a team
117117
## Key concepts
118118

119119
- **`status`** on `team list` rows: `enabled` | `disabled`. A disabled team still exists but is excluded from most operational contexts.
120-
- **`infos <team-id> [<id2>...]`** — takes team IDs as **positional args** (space-separated), not `--team-ids`. The response wraps under `items[]` (pipe `jq '.items[]'` with `--json`), NOT `.data.items[]`.
120+
- **`infos <team-id> [<id2>...]`** — takes team IDs as **positional args** (space-separated), not `--team-ids`.
121121
- **`upsert` lookup key** — matched by `--team-id` (if non-zero) or by `--team-name` (name collision). Pass `--reset-if-name-exist` to overwrite membership on a name match; omit it to leave the existing members untouched.
122122

123123
## Gotchas
@@ -126,7 +126,6 @@ Create or update a team
126126
- **`get` vs `info`** — both fetch a single team; `get` accepts `--id`/`--name`/`--ref-id`; `get [<id>]` also allows the ID as a positional arg. `info` uses `--team-id`/`--team-name`/`--ref-id` flags only. Prefer `get` for interactive lookup.
127127
- **`delete` is irreversible** and requires confirmation unless `--force` is set. Always confirm the correct `--id` (not `--name`) in scripts to avoid name-collision accidents.
128128
- **`infos` positional trap** — the `use` is `infos <team-id> [<id2>...]`; IDs are space-separated positional args, not a flag. `fduty team infos 101 102 103`, not `--team-ids 101,102,103`.
129-
- **`list` JSON shape**`--json` returns a top-level array; pipe `jq '.[]'`, NOT `.items[]`.
130129
- **`upsert` requires `--team-name`** even when updating by `--team-id`; omitting it returns a validation error.
131130

132131
## Worked example

0 commit comments

Comments
 (0)