Update investigation skill asset guidance (#1349)

* docs: update investigation skill asset guidance

* test: normalize ai context fixture line endings

* docs: clarify asset selector discovery

* docs: mirror asset variability warning

Author: thebiglabasky

packages/cli/src/ai-context/__tests__/references.spec.ts

@@ -0,0 +1,39 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const referencesDir = join(dirname(fileURLToPath(import.meta.url)), '../references')
+
+function readReference (name: string): Promise<string> {
+  return readFile(join(referencesDir, name), 'utf8')
+}
+
+function normalizeLineEndings (content: string): string {
+  return content.replace(/\r\n/g, '\n')
+}
+
+describe('AI context investigation references', () => {
+  it('points test-session asset retrieval at the assets commands', async () => {
+    const content = normalizeLineEndings(await readReference('investigate-test-sessions.md'))
+
+    expect(content).toContain('npx checkly assets list --test-session-id <test-session-id> --result-id <test-session-result-id>')
+    expect(content).toContain('npx checkly assets download --test-session-id <test-session-id> --result-id <test-session-result-id> --asset "<Asset>"')
+    expect(content).toContain('The default table output\nhas an `Asset` column; copy that value into `--asset` for single-file downloads.')
+    expect(content).toContain('"pagination": {\n    "length": 0\n  }')
+    expect(content).not.toContain('There is no dedicated `test-sessions download` command')
+    expect(content).not.toContain('download those URLs directly')
+  })
+
+  it('documents check result attempts and asset retrieval', async () => {
+    const content = normalizeLineEndings(await readReference('investigate-checks.md'))
+
+    expect(content).toContain('npx checkly checks get <check-id> --result <result-id> --include-attempts --output json')
+    expect(content).toContain('"result": {}')
+    expect(content).toContain('"attempts": []')
+    expect(content).toContain('npx checkly assets list --check-id <check-id> --result-id <result-id>')
+    expect(content).toContain('npx checkly assets download --check-id <check-id> --result-id <result-id> --asset "<Asset>"')
+    expect(content).toContain('The default table output\nhas an `Asset` column; copy that value into `--asset` for single-file downloads.')
+    expect(content).toContain('Do not invent asset names or assume every result has the same artifact set.')
+  })
+})

packages/cli/src/ai-context/context.ts

@@ -60,11 +60,11 @@ export const REFERENCES = [
 export const INVESTIGATE_REFERENCES = [
   {
     id: 'investigate-checks',
-    description: 'Inspecting checks (`checks list`, `checks get`) and triggering on-demand runs',
+    description: 'Inspect checks (`checks list`, `checks get`), retry attempts, result assets, and trigger on-demand runs',
   },
   {
     id: 'investigate-test-sessions',
-    description: 'Run and inspect recorded test sessions, drill into test-session error groups, run RCA, and retrieve result assets',
+    description: 'Run and inspect recorded test sessions, drill into test-session error groups, run RCA, and list/download result assets',
   },
 ] as const
 
@@ -103,7 +103,7 @@ export const ACTIONS = [
   },
   {
     id: 'investigate',
-    description: 'Access check and test-session status, analyze failures, and investigate errors.',
+    description: 'Access check and test-session status, analyze failures, inspect attempts/assets, and investigate errors.',
     references: INVESTIGATE_REFERENCES,
   },
   {

packages/cli/src/ai-context/references/investigate-checks.md

@@ -48,6 +48,7 @@ Flags:
 
 ```bash
 npx checkly checks get <check-id> --result <result-id>
+npx checkly checks get <check-id> --result <result-id> --output json
 ```
 
 ### View retry attempts for a result
@@ -60,8 +61,63 @@ error summary:
 
 ```bash
 npx checkly checks get <check-id> --result <result-id> --include-attempts
+npx checkly checks get <check-id> --result <result-id> --include-attempts --output json
 ```
 
+With `--include-attempts --output json`, the command returns a stable envelope:
+
+```json
+{
+  "result": {},
+  "attempts": []
+}
+```
+
+Use the `attempts` array to inspect intermediate retry failures. Use the `result`
+object for the requested result row.
+
+### List or download result assets
+
+Result detail output summarizes available screenshots, traces, and videos when
+present. Use the dedicated asset manifest commands to inspect exact asset names
+and download files:
+
+```bash
+npx checkly assets list --check-id <check-id> --result-id <result-id>
+npx checkly assets list --check-id <check-id> --result-id <result-id> --type trace --view tree
+npx checkly assets list --check-id <check-id> --result-id <result-id> --output json
+npx checkly assets download --check-id <check-id> --result-id <result-id> --asset "<Asset>"
+npx checkly assets download --check-id <check-id> --result-id <result-id> --type all --dir ./checkly-assets
+```
+
+Run `assets list` first to discover available files. The default table output
+has an `Asset` column; copy that value into `--asset` for single-file downloads.
+
+Flags:
+- `--type <type>` - filter/select by `log`, `trace`, `video`, `screenshot`, `pcap`, `report`, `file`, or `all`.
+- `--asset <value>` - exact Asset/Name value or glob. Prefer copying the `Asset` value from the default table output before downloading a single file.
+- `--dir <path>` - destination directory for downloads; defaults under `./checkly-assets/`.
+- `--force` / `--skip-existing` - overwrite or preserve existing files.
+
+`assets list --output json` uses a stable list envelope:
+
+```json
+{
+  "data": [],
+  "pagination": {
+    "length": 0
+  }
+}
+```
+
+`assets download` requires `--type` or `--asset` unless the manifest is a single
+archive bundle. Archive entries download as their containing archive; filters
+narrow the manifest list, not the archive bytes.
+
+Do not invent asset names or assume every result has the same artifact set. Some
+results have screenshots only, some have traces or videos, and some have no
+downloadable assets.
+
 ### View an error group
 
 ```bash

packages/cli/src/ai-context/references/investigate-test-sessions.md

@@ -78,7 +78,7 @@ Flags:
 
 The detail view shows the session status, metadata, result rows, test-session result IDs, check IDs when available, and test-session error group IDs. Prefer `--watch` before investigating failures so you do not act on partial results.
 
-Use `--output json` when you need exact fields, result links, or asset URLs. For Playwright Check Suite results, inspect result payload fields such as Playwright result details, traces, videos, screenshots, reports, and links when present.
+Use `--output json` when you need exact fields, result links, check IDs, or test-session result IDs. For downloadable logs, traces, videos, screenshots, reports, and files, use `checkly assets list` and `checkly assets download` with the test session ID and result ID.
 
 ## Inspect a test-session error group
 
@@ -116,13 +116,50 @@ If RCA is unavailable because of plan or entitlement limits, run `npx checkly ac
 
 ## Retrieve result assets
 
-There is no dedicated `test-sessions download` command. Use the JSON outputs and links exposed by the session or result payload.
+Use the asset manifest commands for recorded test-session result files. Start
+from `test-sessions get` to identify the `testSessionResultId` (and `checkId`
+when available) for the row you want to inspect.
 
 ```bash
 npx checkly test-sessions get <test-session-id> --output json
-npx checkly checks get <check-id> --result <test-session-result-id> --output json
+npx checkly assets list --test-session-id <test-session-id> --result-id <test-session-result-id>
+npx checkly assets list --test-session-id <test-session-id> --result-id <test-session-result-id> --type trace --view tree
+npx checkly assets list --test-session-id <test-session-id> --result-id <test-session-result-id> --output json
+npx checkly assets download --test-session-id <test-session-id> --result-id <test-session-result-id> --asset "<Asset>"
+npx checkly assets download --test-session-id <test-session-id> --result-id <test-session-result-id> --type all --dir ./checkly-assets
 ```
 
-Use `test-sessions get --output json` first. If a result includes public URLs or asset fields, download those URLs directly. If a result only gives `checkId` plus `testSessionResultId`, use `checks get <check-id> --result <test-session-result-id> --output json` to fetch detailed result data; terminal output summarizes available screenshots, traces, and videos, while JSON output exposes the underlying URLs/fields.
+Run `assets list` first to discover available files. The default table output
+has an `Asset` column; copy that value into `--asset` for single-file downloads.
 
-Do not invent asset names or assume every result has the same artifact set. Some results have screenshots only, some have traces or videos, and some have no downloadable assets.
+Flags:
+- `--type <type>` - filter/select by `log`, `trace`, `video`, `screenshot`, `pcap`, `report`, `file`, or `all`.
+- `--asset <value>` - exact Asset/Name value or glob. Prefer copying the `Asset` value from `assets list --view table` for single-file downloads.
+- `--dir <path>` - destination directory for downloads; defaults under `./checkly-assets/`.
+- `--force` / `--skip-existing` - overwrite or preserve existing files.
+
+`assets list --output json` uses a stable list envelope:
+
+```json
+{
+  "data": [],
+  "pagination": {
+    "length": 0
+  }
+}
+```
+
+`assets download` requires `--type` or `--asset` unless the manifest is a single
+archive bundle. Archive entries download as their containing archive; filters
+narrow the manifest list, not the archive bytes.
+
+If you also need the scheduled check result view for the same row, and the row
+has a `checkId`, use:
+
+```bash
+npx checkly checks get <check-id> --result <test-session-result-id>
+```
+
+Do not invent asset names or assume every result has the same artifact set. Some
+results have screenshots only, some have traces or videos, and some have no
+downloadable assets.

skills/checkly/SKILL.md

@@ -103,7 +103,7 @@ Learn how to initialize and set up a new Checkly CLI project from scratch.
 Learn how to create and manage monitoring checks using Checkly constructs and the CLI.
 
 ### `npx checkly skills investigate`
-Access check and test-session status, analyze failures, and investigate errors.
+Access check and test-session status, analyze failures, inspect attempts/assets, and investigate errors.
 
 ### `npx checkly skills communicate`
 Open incidents and lead customer communications via status pages.