docs(skill): document --files attachments for kane-cli generate (#83)

Adds the `--files` flag (attach local files as generation context) to the
generate skill, references, user guide, and the Kiro integration. Docs-only —
no behavior change. Builds on the generate docs from #67 / #79.

- references/generate.md + SKILL.md section 6: the `--files` flag, an
  "Attaching files" section (supported types, 10-file / 50 MB caps, atomic
  up-front validation, new/refine-only, the `@` TUI hint), and the
  `--files` + `--save` invalid combo.
- references/generate-parsing.md: the `generate_upload` NDJSON event (one per
  file, before `generate_start`; `uploading` -> `done`/`failed`).
- .claude/ and .agents/ skill mirrors kept byte-identical to the source.
- docs/user-guide/generate-test-cases/{overview,workflow}: `--files` option,
  an "Attaching files for context" section, the `@` TUI row, a workflow
  example, and corrected the now-stale "files not part of the CLI" notes.
- Kiro power: `--files` in the kane-cli-generate steering file and the
  maintenance mapping.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: shravan-lambdatest

.agents/skills/kane-cli/SKILL.md

@@ -287,6 +287,8 @@ Then offer the next commands from the terminal line's Refine / Save hints (they
 
 **Clarification → refine (do not skip):** if the turn ends with a clarification, that's **exit 0 — not an error**. Act on it: answer it yourself, or ask your own user, then **re-invoke** `kane-cli generate "<answer>" --refine --req <id> --agent`. Never drop a clarification.
 
+**Attach files:** `--files a,b,c` adds local files (docs / images / PDF / CSV — up to 10, ≤ 50 MB each) as generation context on a **new** or **`--refine`** turn (not `--save`); each emits a `generate_upload` line before `generate_start`. Details in `references/generate.md`.
+
 **Save is Functional-only:** `--save` writes only **Functional** cases to `_test.md` (under `<cwd>/.testmuai/tests` by default). Non-functional cases (Security, Performance, …) are generated and shown but not saved. Run saved files with **`kane-cli testmd run`** (`references/testmd.md`) — that's the generate → testmd pipeline.
 
 Internal event/field names (`generate_snapshot`, `request_id`, …) are for parsing only — never show them to the user (§5 rule). Wire schema: `references/generate-parsing.md`.

.agents/skills/kane-cli/references/generate-parsing.md

@@ -23,6 +23,7 @@ Generate-specific (typed `generate_*`):
 
 | `type` | Key fields | Meaning → what to do |
 |---|---|---|
+| `generate_upload` | `file`, `index`, `total`, `status` | Only when `--files` is used. Emitted once per attached file **before `generate_start`**, while the file uploads; `status` goes `"uploading"` → `"done"` (or `"failed"`). Progress only — narrate "attaching <file>…" or ignore. A failed upload surfaces as an `error` + non-zero exit. |
 | `generate_start` | `request_id`, `objective_chars`, `scenario_limit`, `per_scenario_limit`, `is_refine` | Turn began. **Capture `request_id`** — it's the handle for every later `--refine` / `--save`. `is_refine` distinguishes a new request from a continuation. |
 | `generate_thinking` | `took_ms` | Liveness only. Narrate "thinking…" or ignore. |
 | `generate_progress` | `pct` | Milestone (25 / 50 / 75 / 100). Optional progress display — not a completion signal. |

.agents/skills/kane-cli/references/generate.md

@@ -6,7 +6,7 @@
 
 **Use this whenever a task needs test cases or scenarios written — don't hand-author them in chat or a scratch file.** Reach for it to: turn a requirement / feature description into a test suite; expand or refine coverage (more edge cases, negative paths, a narrower or broader focus); or save the Functional cases as runnable `_test.md`. It is **not** for driving a browser — that's `kane-cli run` (§3 of SKILL.md).
 
-> For the full web-product picture (richer inputs, dashboards), see the public docs: <https://www.testmuai.com/support/docs/generate-test-cases-with-ai/>. The CLI surface here is **text-objective only**.
+> For the full web-product picture (dashboards, issue-link inputs), see the public docs: <https://www.testmuai.com/support/docs/generate-test-cases-with-ai/>. The CLI takes a **text objective**, optionally with local files attached via **`--files`** (see "Attaching files" below).
 
 ## The three modes — one turn per invocation, then exit
 
@@ -30,11 +30,27 @@ There is **no interactive session**. Each invocation runs exactly one generation
 | `--name <name>` | Names the run and the saved suite folder |
 | `--scenario-limit <n>` / `--per-scenario-limit <n>` | Cap scenarios / cases-per-scenario |
 | `--memory` | Use the memory layer — reuse relevant existing cases, reduce duplicates |
+| `--files <paths>` | Comma-separated local files to attach as context (new / refine only — see "Attaching files") |
 | `--project <id>` / `--folder <id>` | Test Manager project / folder |
 | `--env prod\|stage` · `--username` / `--access-key` | Environment / auth (same as `run`) |
 
 If neither `--project`/`--folder` nor a saved project/folder is set when generation starts, kane-cli auto-resolves one headlessly and emits a `project_folder_auto_defaulted` event before `generate_start`. Translate it to a one-line note for the user — full handling lives in `references/test-manager.md`.
 
+## Attaching files
+
+Pass local files as extra context with `--files <comma-separated paths>` on a **new** generation or a **`--refine`** (not `--save`). The generator reads them and reflects them in the scenarios + cases — attach a spec, a screenshot of the UI, a PDF / Word doc, or a CSV of inputs.
+
+```bash
+kane-cli generate "test the login flow described in the attached spec" --files ./login-spec.pdf,./wireframe.png --agent
+```
+
+- **Supported types** — documents (`.txt .json .xml .csv .pdf .docx .xlsx`), images (`.jpg .jpeg .png .gif .bmp .webp`), audio (`.mp3 .wav .m4a`), video (`.mp4 .mov .webm .mpeg .mpga`).
+- **Limits** — up to **10 files**, each **≤ 50 MB**.
+- **Validated as a set, up front** — if any path is missing, an unsupported type, too large, or over the count, the whole command is rejected (exit `2`) **before anything is sent** and the offending paths are listed; fix and re-run. Files outside the current directory are allowed but flagged with a warning on stderr.
+- **`new` / `--refine` only** — combining `--files` with `--save` exits `2`.
+
+Under `--agent`, each file emits a `generate_upload` line (`status` `uploading` → `done`) **before** `generate_start` — see `references/generate-parsing.md`. *(Interactively in the TUI, type `@` in the generate prompt to attach a file inline.)*
+
 ## Presenting a result (adaptive)
 
 The terminal data carries the full scenarios + cases. **Present it based on size**:
@@ -114,6 +130,7 @@ Invalid flag combinations exit `2` with a message on stderr. The full set:
 - `--save` without `--req`
 - `--save` with a description (it takes none)
 - `--out` without `--save`
+- `--files` with `--save` (files attach to a new generation or a refine, not a save)
 - `--req` without `--refine` or `--save`
 - a new generation with no description
 

.claude/skills/kane-cli/SKILL.md

@@ -287,6 +287,8 @@ Then offer the next commands from the terminal line's Refine / Save hints (they
 
 **Clarification → refine (do not skip):** if the turn ends with a clarification, that's **exit 0 — not an error**. Act on it: answer it yourself, or ask your own user, then **re-invoke** `kane-cli generate "<answer>" --refine --req <id> --agent`. Never drop a clarification.
 
+**Attach files:** `--files a,b,c` adds local files (docs / images / PDF / CSV — up to 10, ≤ 50 MB each) as generation context on a **new** or **`--refine`** turn (not `--save`); each emits a `generate_upload` line before `generate_start`. Details in `references/generate.md`.
+
 **Save is Functional-only:** `--save` writes only **Functional** cases to `_test.md` (under `<cwd>/.testmuai/tests` by default). Non-functional cases (Security, Performance, …) are generated and shown but not saved. Run saved files with **`kane-cli testmd run`** (`references/testmd.md`) — that's the generate → testmd pipeline.
 
 Internal event/field names (`generate_snapshot`, `request_id`, …) are for parsing only — never show them to the user (§5 rule). Wire schema: `references/generate-parsing.md`.

.claude/skills/kane-cli/references/generate-parsing.md

@@ -23,6 +23,7 @@ Generate-specific (typed `generate_*`):
 
 | `type` | Key fields | Meaning → what to do |
 |---|---|---|
+| `generate_upload` | `file`, `index`, `total`, `status` | Only when `--files` is used. Emitted once per attached file **before `generate_start`**, while the file uploads; `status` goes `"uploading"` → `"done"` (or `"failed"`). Progress only — narrate "attaching <file>…" or ignore. A failed upload surfaces as an `error` + non-zero exit. |
 | `generate_start` | `request_id`, `objective_chars`, `scenario_limit`, `per_scenario_limit`, `is_refine` | Turn began. **Capture `request_id`** — it's the handle for every later `--refine` / `--save`. `is_refine` distinguishes a new request from a continuation. |
 | `generate_thinking` | `took_ms` | Liveness only. Narrate "thinking…" or ignore. |
 | `generate_progress` | `pct` | Milestone (25 / 50 / 75 / 100). Optional progress display — not a completion signal. |

.claude/skills/kane-cli/references/generate.md

@@ -6,7 +6,7 @@
 
 **Use this whenever a task needs test cases or scenarios written — don't hand-author them in chat or a scratch file.** Reach for it to: turn a requirement / feature description into a test suite; expand or refine coverage (more edge cases, negative paths, a narrower or broader focus); or save the Functional cases as runnable `_test.md`. It is **not** for driving a browser — that's `kane-cli run` (§3 of SKILL.md).
 
-> For the full web-product picture (richer inputs, dashboards), see the public docs: <https://www.testmuai.com/support/docs/generate-test-cases-with-ai/>. The CLI surface here is **text-objective only**.
+> For the full web-product picture (dashboards, issue-link inputs), see the public docs: <https://www.testmuai.com/support/docs/generate-test-cases-with-ai/>. The CLI takes a **text objective**, optionally with local files attached via **`--files`** (see "Attaching files" below).
 
 ## The three modes — one turn per invocation, then exit
 
@@ -30,11 +30,27 @@ There is **no interactive session**. Each invocation runs exactly one generation
 | `--name <name>` | Names the run and the saved suite folder |
 | `--scenario-limit <n>` / `--per-scenario-limit <n>` | Cap scenarios / cases-per-scenario |
 | `--memory` | Use the memory layer — reuse relevant existing cases, reduce duplicates |
+| `--files <paths>` | Comma-separated local files to attach as context (new / refine only — see "Attaching files") |
 | `--project <id>` / `--folder <id>` | Test Manager project / folder |
 | `--env prod\|stage` · `--username` / `--access-key` | Environment / auth (same as `run`) |
 
 If neither `--project`/`--folder` nor a saved project/folder is set when generation starts, kane-cli auto-resolves one headlessly and emits a `project_folder_auto_defaulted` event before `generate_start`. Translate it to a one-line note for the user — full handling lives in `references/test-manager.md`.
 
+## Attaching files
+
+Pass local files as extra context with `--files <comma-separated paths>` on a **new** generation or a **`--refine`** (not `--save`). The generator reads them and reflects them in the scenarios + cases — attach a spec, a screenshot of the UI, a PDF / Word doc, or a CSV of inputs.
+
+```bash
+kane-cli generate "test the login flow described in the attached spec" --files ./login-spec.pdf,./wireframe.png --agent
+```
+
+- **Supported types** — documents (`.txt .json .xml .csv .pdf .docx .xlsx`), images (`.jpg .jpeg .png .gif .bmp .webp`), audio (`.mp3 .wav .m4a`), video (`.mp4 .mov .webm .mpeg .mpga`).
+- **Limits** — up to **10 files**, each **≤ 50 MB**.
+- **Validated as a set, up front** — if any path is missing, an unsupported type, too large, or over the count, the whole command is rejected (exit `2`) **before anything is sent** and the offending paths are listed; fix and re-run. Files outside the current directory are allowed but flagged with a warning on stderr.
+- **`new` / `--refine` only** — combining `--files` with `--save` exits `2`.
+
+Under `--agent`, each file emits a `generate_upload` line (`status` `uploading` → `done`) **before** `generate_start` — see `references/generate-parsing.md`. *(Interactively in the TUI, type `@` in the generate prompt to attach a file inline.)*
+
 ## Presenting a result (adaptive)
 
 The terminal data carries the full scenarios + cases. **Present it based on size**:
@@ -114,6 +130,7 @@ Invalid flag combinations exit `2` with a message on stderr. The full set:
 - `--save` without `--req`
 - `--save` with a description (it takes none)
 - `--out` without `--save`
+- `--files` with `--save` (files attach to a new generation or a refine, not a save)
 - `--req` without `--refine` or `--save`
 - a new generation with no description
 

docs/user-guide/generate-test-cases/overview.md

@@ -9,7 +9,7 @@ A generation produces:
 
 You generate, review the result, **refine** it in plain language as many times as you like, and optionally **save** the functional cases as runnable `_test.md` files that [`kane-cli testmd`](../testmd/running.md) can execute and replay.
 
-> For the full picture of AI test-case generation — including richer inputs (files, PDFs, issue links) and pushing cases into Test Manager or automation — see the docs at <https://www.testmuai.com/support/docs/generate-test-cases-with-ai/>. The **CLI here takes a text description** and writes local `_test.md` files. See [Limits and scope](#limits-and-scope).
+> For the full picture of AI test-case generation — including issue-link inputs, dashboards, and pushing cases into Test Manager or automation — see the docs at <https://www.testmuai.com/support/docs/generate-test-cases-with-ai/>. The **CLI takes a text description** (optionally with local files attached via [`--files`](#attaching-files-for-context)) and writes local `_test.md` files. See [Limits and scope](#limits-and-scope).
 
 ## Quick start
 
@@ -52,10 +52,28 @@ The request id (`23271` above) is printed at the end of each generation and is h
 | `--scenario-limit <n>` | Maximum number of scenarios to generate. |
 | `--per-scenario-limit <n>` | Maximum test cases per scenario. |
 | `--memory` | Use the **memory layer** — reuse relevant existing test cases and reduce duplicates. |
+| `--files <paths>` | Comma-separated local files to attach as context (new generations and refines only). See [Attaching files for context](#attaching-files-for-context). |
 | `--project <id>` / `--folder <id>` | Test Manager project / folder. |
 | `--agent` | Emit structured NDJSON on stdout (auto-on when run non-interactively / piped). |
 | `--env`, `--username`, `--access-key` | Environment and authentication — same as [`kane-cli run`](../running-tests.md). See [Authentication](../authentication.md). |
 
+## Attaching files for context
+
+Give the generator more to work from by attaching local files with `--files` — a comma-separated list of paths — on a **new** generation or a **refine**:
+
+```bash
+kane-cli generate "test the login flow described in the attached spec" --files ./login-spec.pdf,./wireframe.png
+```
+
+The files are sent along with your description and reflected in the generated scenarios and cases — attach a spec, a screenshot of the UI, a PDF or Word document, or a CSV of inputs.
+
+- **Supported types** — documents (`.txt`, `.json`, `.xml`, `.csv`, `.pdf`, `.docx`, `.xlsx`), images (`.jpg`, `.jpeg`, `.png`, `.gif`, `.bmp`, `.webp`), audio (`.mp3`, `.wav`, `.m4a`), and video (`.mp4`, `.mov`, `.webm`, `.mpeg`, `.mpga`).
+- **Limits** — up to **10 files**, each **50 MB** or smaller.
+- **Checked before anything is sent** — all paths are validated as a set; if any is missing, an unsupported type, too large, or over the count, the command stops and lists the offending paths so nothing is uploaded by mistake. Files outside the current directory are allowed but flagged with a warning.
+- **Not with `--save`** — files attach to a generation or refine, not a save (`--files` with `--save` is rejected).
+
+In the interactive TUI, type `@` in the generate prompt to attach a file inline instead of passing `--files`.
+
 ## Interactive mode (TUI)
 
 The commands above are the scripted surface. The kane-cli TUI **launches in Run mode** (for running tests) by default — switch to **Generate mode** with **`/generate`**, and back with `/run`. Or jump straight in: running `kane-cli generate "<objective>"` in a terminal (without `--agent`) opens the TUI directly in Generate mode and submits your objective.
@@ -65,6 +83,7 @@ Unlike the one-turn command-line surface, the TUI is a **live session** — gene
 | Input | Action |
 |---|---|
 | *(type any text)* | **Refine** — describe a change in plain language; the set updates in place |
+| `@<file>` | **Attach a file** — type `@` to pick a local file to add as context (same files as `--files`) |
 | `/view [S<n>]` | Open the **scenario browser** — drill scenarios → cases → case detail |
 | `/save` | Save the functional cases to `<cwd>/.testmuai/tests/…` |
 | `/cancel` | Cancel the current generation |
@@ -95,7 +114,7 @@ This is the intended path: **generate authors test cases → testmd runs them.**
 
 ## Limits and scope
 
-- **Input is a text description.** File, PDF, audio, and issue-link inputs (and the web product's "Create / Create and Automate") are not part of the CLI.
+- **Input is a text description, optionally with attached files.** Attach local files with `--files` (see [Attaching files for context](#attaching-files-for-context)); issue-link inputs and the web product's "Create / Create and Automate" are not part of the CLI.
 - **Refinement is whole-request.** You refine the request as a whole in plain language; targeting an individual scenario or case from the CLI is not yet supported.
 - **Scenario and per-scenario counts** are bounded by `--scenario-limit` / `--per-scenario-limit`.
 

docs/user-guide/generate-test-cases/workflow.md

@@ -38,6 +38,14 @@ kane-cli generate "checkout flow on a shopping site" --scenario-limit 4 --per-sc
 
 Add `--memory` to reuse relevant existing cases and avoid duplicating coverage you already have.
 
+Attach local files as context — a spec, a screenshot, a PDF or CSV — with `--files` (on a new generation or a refine):
+
+```bash
+kane-cli generate "cover the flows described in the attached spec" --files ./spec.pdf,./flows.csv
+```
+
+Up to 10 files, each 50 MB or smaller (documents, images, audio, video); all paths are validated before anything is sent. See [Attaching files for context](./overview.md#attaching-files-for-context).
+
 ## 2. Refine
 
 Refinement is a plain-language conversation. Each refine is a fresh command with `--refine --req <id>`: