chore: Improve skills description and guidance

Author: ludovicianul

src/main/resources/skills/dochia-fuzz/SKILL.md

@@ -29,9 +29,9 @@ requests to discover unexpected vulnerabilities and edge cases.
 ## Prerequisites
 
 - Dochia CLI installed (any of the following):
-  - `brew install dochia-dev/tap/dochia-cli`
-  - `curl -sSL get.dochia.dev | sh`
-  - `docker pull dochiadev/dochia-cli`
+    - `brew install dochia-dev/tap/dochia-cli`
+    - `curl -sSL get.dochia.dev | sh`
+    - `docker pull dochiadev/dochia-cli`
 - An OpenAPI specification file (YAML or JSON)
 - A running API server to fuzz
 

src/main/resources/skills/dochia-list/SKILL.md

@@ -68,6 +68,27 @@ dochia list --paths -c openapi.yml --tag users
 | `--tag`           | Filter paths by OpenAPI tag                  |
 | `-j, --json`      | Output in JSON format                        |
 
+## Understanding Resource Dependencies
+
+Use `--paths` to inspect the API structure before running tests. This helps identify resource dependencies
+that require a specific testing order:
+
+```bash
+# List all paths to understand the resource hierarchy
+dochia list --paths -c openapi.yml
+
+# Inspect a specific path to see its query parameters, http headers, response codes, and methods
+dochia list --paths -c openapi.yml --path /pet/{petId}
+```
+
+Look for patterns like:
+- `POST /resource` (creates) → `GET/PUT/DELETE /resource/{id}` (needs the created ID)
+- `POST /resource/{id}/subresource` (needs parent resource ID first)
+
+This is important because Dochia is stateless. When testing endpoints that require existing resource IDs,
+you should first create resources using the `HappyPath` playbook on creation endpoints, then supply the
+IDs via `-R` or `--reference-data`. See the `dochia-test` skill for the full stateful testing workflow.
+
 ## Documentation
 
 Full reference: https://docs.dochia.dev/cli/list

src/main/resources/skills/dochia-replay/SKILL.md

@@ -28,9 +28,9 @@ debugging failures, and validating fixes.
 ## Prerequisites
 
 - Dochia CLI installed (any of the following):
-  - `brew install dochia-dev/tap/dochia-cli`
-  - `curl -sSL get.dochia.dev | sh`
-  - `docker pull dochiadev/dochia-cli`
+    - `brew install dochia-dev/tap/dochia-cli`
+    - `curl -sSL get.dochia.dev | sh`
+    - `docker pull dochiadev/dochia-cli`
 - A previous test run with reports in `./dochia-report` (or custom output directory)
 - A running API server
 

src/main/resources/skills/dochia-test/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Run comprehensive API testing against OpenAPI specifications using Dochia. Use when the user wants to
   test APIs, run negative/boundary tests, validate API behavior, check for 5XX errors, run security-focused
   API tests, or verify input validation. Also use when the user mentions chaos testing, fuzzing playbooks,
-  API hardening, or contract testing. Requires an OpenAPI spec file and a running server.
+  API hardening, or contract testing. Requires an OpenAPI spec file and a running server. (1 supporting files)
 metadata:
   triggers: |
     test my API
@@ -19,6 +19,8 @@ metadata:
     chaos testing
     contract testing
     run dochia
+    test endpoints with dependencies
+    supply reference data
   examples: |
     dochia test -c openapi.yml -s http://localhost:8080 -b
     dochia test -c openapi.yml -s http://localhost:8080 --playbooks "MalformedJson,BypassAuthentication" -b
@@ -33,9 +35,9 @@ API endpoints based on an OpenAPI specification.
 ## Prerequisites
 
 - Dochia CLI installed (any of the following):
-  - `brew install dochia-dev/tap/dochia-cli`
-  - `curl -sSL get.dochia.dev | sh`
-  - `docker pull dochiadev/dochia-cli`
+    - `brew install dochia-dev/tap/dochia-cli`
+    - `curl -sSL get.dochia.dev | sh`
+    - `docker pull dochiadev/dochia-cli`
 - An OpenAPI specification file (YAML or JSON)
 - A running API server to test against
 
@@ -150,12 +152,14 @@ dochia test -c openapi.yml -s https://localhost:8443 --ssl-keystore keystore.jks
 Reports are generated in `./dochia-report` by default. Use `--output` to change the directory.
 
 Each test produces:
+
 - `TestN.html` — human-readable report
 - `TestN.json` — machine-readable result with full request/response details
 
 A `dochia-summary-report.json` is also generated with a compact array of all test results.
 
-See [the report output reference](references/report-output.md) for the full JSON schemas and `jq` examples for parsing results programmatically.
+See [the report output reference](references/report-output.md) for the full JSON schemas and `jq` examples for parsing
+results programmatically.
 
 ### Quick Report Analysis
 
@@ -176,6 +180,79 @@ cat dochia-report/Test449.json | jq .
 cat dochia-report/dochia-summary-report.json | jq -r '[.testCases[] | select(.result == "error") | .id] | join(",")'
 ```
 
+## Stateful Testing Workflow
+
+Dochia is stateless — it does not automatically create or manage resources between requests. When testing APIs
+with resource dependencies (e.g. `PUT /pet/{petId}` requires a `petId` from `POST /pet`), you need to
+orchestrate the workflow yourself.
+
+### Step 1: Understand the resource hierarchy
+
+Use `dochia list --paths` to inspect the API structure and identify parent/child resource relationships:
+
+```bash
+dochia list --paths -c openapi.yml
+dochia list --paths -c openapi.yml --path /pet/{petId}
+```
+
+Look for patterns like:
+
+- `POST /resource` (creates) → `GET/PUT/DELETE /resource/{id}` (requires ID)
+- `POST /resource/{id}/subresource` (requires parent ID)
+
+### Step 2: Create resources first using HappyPath
+
+Run the `HappyPath` playbook on creation endpoints (typically POST) to generate valid resources.
+Inspect the response body from the JSON report to extract the resource ID.
+
+> **Note:** The ID field name varies by API. Check the OpenAPI spec or the raw response body to find the correct
+> field. For example, for a Pet resource, it might be `.id`, `.petId`, `.idOfPet`, `.petIdentifier`, etc.
+
+```bash
+# Run only HappyPath on the creation endpoint
+dochia test -c openapi.yml -s http://localhost:8080 --path "/pet" --http-method POST --playbooks HappyPath -o /tmp/setup-report
+
+# First, inspect the full response to find the correct ID field name
+cat /tmp/setup-report/Test1.json | jq '.response.body'
+
+# Then extract using the actual field name from your API
+cat /tmp/setup-report/Test1.json | jq '.response.body.id'         # adjust field name as needed
+```
+
+### Step 3: Supply reference data with -R
+
+Use `-R` to pass fixed field values that Dochia will inject into path parameters and request bodies:
+
+```bash
+# Inline reference data (applied to all paths)
+dochia test -c openapi.yml -s http://localhost:8080 -R "petId=123" -b
+
+# Per-path reference data via YAML file
+dochia test -c openapi.yml -s http://localhost:8080 --reference-data refData.yml -b
+```
+
+The reference data YAML file format supports per-path and global (`all`) values:
+
+```yaml
+/pet/{petId}:
+  petId: "123"
+/store/order/{orderId}:
+  orderId: "456"
+all:
+  apiVersion: "v2"
+```
+
+### Recommended agent workflow
+
+When testing an API with resource dependencies:
+
+1. Run `dochia list --paths -c openapi.yml` to understand the API structure
+2. Identify which endpoints create resources (typically POST without path parameters)
+3. Run `dochia test` with `--playbooks HappyPath` on creation endpoints first
+4. Extract resource IDs from the JSON response in the report
+5. Run the full test suite on dependent endpoints using `-R` to supply the extracted IDs
+6. Analyze results and replay failures with `dochia replay`
+
 ## Listing Available Playbooks
 
 ```bash

src/main/resources/skills/dochia-test/references/report-output.md

@@ -131,16 +131,16 @@ Each `TestN.json` file contains the full details of a single test case:
 
 ### Summary Key Fields
 
-| Field               | Description                                               |
-|---------------------|-----------------------------------------------------------|
+| Field               | Description                                                              |
+|---------------------|--------------------------------------------------------------------------|
 | `id`                | Test identifier (e.g. "Test 1"). Filename strips the space: `Test1.json` |
-| `result`            | `"error"`, `"warning"`, `"success"`, or `"skipped"`       |
-| `playbook`          | Playbook name                                             |
-| `path`              | OpenAPI path                                              |
-| `httpMethod`        | HTTP method                                               |
-| `httpResponseCode`  | Response status code                                      |
-| `timeToExecuteInMs` | Execution time                                            |
-| `switchedResult`    | Whether the result was switched by a filter               |
+| `result`            | `"error"`, `"warning"`, `"success"`, or `"skipped"`                      |
+| `playbook`          | Playbook name                                                            |
+| `path`              | OpenAPI path                                                             |
+| `httpMethod`        | HTTP method                                                              |
+| `httpResponseCode`  | Response status code                                                     |
+| `timeToExecuteInMs` | Execution time                                                           |
+| `switchedResult`    | Whether the result was switched by a filter                              |
 
 ### Summary Metadata Fields