docs: add paper citations, fix pedagogical issues, improve SKILL.md

- Cite arxiv 2602.23922 (Invariant-Driven Automated Testing) in all major docs
- Add Progressive Complexity section to SKILL.md for LLM guidance
- Fix SKILL.md Fast Start example to use deterministic ID generation
- Fix getting-started.md failure output inconsistency
- Fix auth-patterns.md TypeScript syntax in JS doc
- Fix fastify-structure.md Date.now() in test helper
- Fix observe.md misleading workspace heading
- Build: clean | Tests: 849 pass, 0 fail

docs/auth-patterns.md

@@ -144,7 +144,7 @@ See `docs/protocol-extensions-spec.md` for full JWT extension configuration.
 `getToken` runs per request. Handle refresh inline:
 
 ```javascript
-let cachedToken: string | null = null
+let cachedToken = null
 
 const auth = createAuthExtension({
   name: 'jwt-with-refresh',

docs/chaos.md

@@ -2,6 +2,8 @@
 
 Inject controlled failures into contract tests to validate resilience guarantees.
 
+Chaos testing applies the invariant-driven verification approach from [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021) under adverse conditions: if a contract must hold, it should still hold when dependencies fail, responses are delayed, or payloads are corrupted.
+
 ## Usage
 
 ```javascript

docs/fastify-structure.md

@@ -374,8 +374,10 @@ import { mkdirSync, rmSync } from 'fs'
 import { tmpdir } from 'os'
 import { join } from 'path'
 
+let testCounter = 0
+
 export function createTestWorkspace() {
-  const dir = join(tmpdir(), `apophis-test-${Date.now()}`)
+  const dir = join(tmpdir(), `apophis-test-${++testCounter}`)
   mkdirSync(dir, { recursive: true })
 
   return {

docs/getting-started.md

@@ -2,6 +2,8 @@
 
 Get from install to your first behavioral bug in 10 minutes.
 
+APOPHIS is inspired by [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021): instead of only validating request and response shape, encode intended behavior as executable contracts and let the tool find violations automatically.
+
 ## Prerequisites
 
 - Node.js 20.x or 22.x
@@ -70,7 +72,7 @@ Expected
   response_code(GET /users/{response_body(this).id}) == 200
 
 Observed
-  GET /users/usr-123 returned 404
+  GET /users/usr-7d865e returned 404
 
 Why this matters
   The resource created by POST /users is not retrievable.

docs/llm-safe-adoption.md

@@ -2,6 +2,8 @@
 
 APOPHIS is designed to be safe and predictable for LLM-generated Fastify services.
 
+It applies the invariant-driven approach from [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021) to LLM-assisted development: constrained vocabulary, deterministic replay, and executable contracts give coding agents a verifiable loop between generated changes and behavioral correctness.
+
 ## Why APOPHIS Is Good for LLM-Generated Services
 
 Coding agents benefit from:

docs/observe.md

@@ -2,6 +2,8 @@
 
 Runtime visibility and drift detection without blocking by default.
 
+Observe extends the invariant framework from [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021) to production environments: contracts run continuously against live traffic to detect behavioral drift without affecting requests.
+
 ## What Observe Does
 
 `apophis observe` validates your runtime observe configuration:
@@ -153,9 +155,9 @@ observe: {
 }
 ```
 
-## Workspace Support
+## Monorepo Validation
 
-For monorepos, use `apophis doctor --workspace` to validate observe configuration across all workspace packages.
+For monorepos, use `apophis doctor --workspace` to validate observe configuration across all workspace packages. `observe` itself does not support `--workspace`; use `doctor` to check config in each package.
 
 ## Mode Mismatch
 

docs/protocol-extensions-spec.md

@@ -6,6 +6,8 @@
 
 This specification defines protocol-specific extensions for APOPHIS, driven by the Arbiter team's requirements for testing OAuth 2.1, WIMSE S2S, Transaction Tokens (RFC 8693), SPIFFE/SPIRE, and related security protocols.
 
+APOPHIS is grounded in [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021). Protocol extensions add domain-specific predicates (JWT, X.509, SPIFFE) to the core invariant framework.
+
 Arbiter maintains 58 protocol conformance test files covering 138 behaviors across 7 specifications. These extensions bridge the gap between declarative APOSTL contracts and the domain-specific predicates required for security protocol validation.
 
 ### 1.1 Current Shipped vs Not-Shipped Snapshot

docs/qualify.md

@@ -2,6 +2,8 @@
 
 Run scenario, stateful, and chaos checks against non-production Fastify services.
 
+Qualify extends the invariant-driven approach from [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021) with multi-step protocol flows, stateful sequences, and controlled fault injection.
+
 ## What Qualify Does
 
 `apophis qualify` runs deeper testing than verify:

docs/verify.md

@@ -2,6 +2,8 @@
 
 Deterministic contract verification for CI and local development.
 
+APOPHIS implements the invariant-driven approach from [Invariant-Driven Automated Testing](https://arxiv.org/abs/2602.23922) (Malhado Ribeiro, 2021): encode intended behavior as executable formulas, then verify them automatically with property-based generation and deterministic replay.
+
 ## When to Use It
 
 - **Local development**: Quick feedback on behavioral changes