docs: add scenario examples, fix sampling docs, improve pedagogical completeness

- Add actual scenario definition example to qualify.md
- Add stateful test API example to qualify.md
- Fix observe.md sampling section to show explicit config and rates
- Build: clean | Tests: 849 pass, 0 fail

docs/observe.md

@@ -67,7 +67,18 @@ profiles: {
 }
 ```
 
-The `platform-observe` preset enables sampling at the preset level.
+The `platform-observe` preset enables sampling. Configure the rate explicitly:
+
+```javascript
+profiles: {
+  'staging-observe': {
+    mode: 'observe',
+    preset: 'platform-observe',
+    routes: [],
+    sampling: 1.0  // 100% of requests observed
+  }
+}
+```
 
 ## Staging vs Production
 
@@ -76,7 +87,18 @@ The `platform-observe` preset enables sampling at the preset level.
 | Staging | No (default) | 100% | Yes |
 | Production | No (default) | 100% | Yes |
 
-Default is 1.0 (100%). Configure lower rates for production explicitly.
+Default is `1.0` (100%). Configure lower rates for production explicitly:
+
+```javascript
+profiles: {
+  'prod-observe': {
+    mode: 'observe',
+    preset: 'platform-observe',
+    routes: [],
+    sampling: 0.1  // 10% of requests observed
+  }
+}
+```
 
 ## `--check-config` Flag
 

docs/qualify.md

@@ -51,6 +51,38 @@ profiles: {
 }
 ```
 
+## Scenario Definitions
+
+Scenarios are multi-step flows with capture and rebind:
+
+```javascript
+await fastify.apophis.scenario({
+  name: 'oauth-basic',
+  steps: [
+    {
+      name: 'authorize',
+      request: { method: 'GET', url: '/oauth/authorize?client_id=web&response_type=code' },
+      expect: ['status:200', 'response_payload(this).code != null'],
+      capture: { code: 'response_payload(this).code' }
+    },
+    {
+      name: 'token',
+      request: {
+        method: 'POST',
+        url: '/oauth/token',
+        form: { grant_type: 'authorization_code', code: '$authorize.code' }
+      },
+      expect: ['status:200', 'response_payload(this).access_token != null']
+    }
+  ]
+})
+```
+
+Scenario behavior:
+1. Cookie jar persists `Set-Cookie` values across steps.
+2. Step-level `headers.cookie` overrides jar values for that step.
+3. `form` sends `application/x-www-form-urlencoded` payloads.
+
 ## Stateful Testing
 
 Stateful tests generate sequences of operations and track resources:
@@ -62,6 +94,13 @@ Stateful tests generate sequences of operations and track resources:
 
 APOPHIS tracks created resources and runs cleanup after test completion.
 
+Run stateful tests via the API:
+
+```javascript
+const stateful = await fastify.apophis.stateful({ depth: 'standard', seed: 42 })
+console.log('Stateful tests:', stateful.summary)
+```
+
 ## Route Transparency
 
 Artifacts include `executedRoutes` and `skippedRoutes` arrays. `skippedRoutes` contains reasons such as mode mismatch, environment policy, or route filter exclusion.