Changes before error encountered

Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/43fe0bab-512b-4dfa-81d1-6cbb5c09babc

Author: Copilot

.changeset/refactor-docs-ia.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Refactor docs information architecture: `docs/usage.md` is now a central hub page linking to individual feature pages under `docs/features/`, and pattern pages are consolidated under `docs/patterns/index.md`.

.github/issue-proposals/docs-pattern-persistent-state.md

@@ -39,5 +39,5 @@ A `Persistent State` pattern document would describe:
 - [ ] `--persist-state <path>` CLI flag (or equivalent) is implemented
 - [ ] Context classes can opt in to persistence by implementing a documented interface
 - [ ] `docs/patterns/persistent-state.md` is added following the established pattern format
-- [ ] The new pattern is linked in `docs/usage-patterns.md`
+- [ ] The new pattern is linked in `docs/patterns/index.md`
 - [ ] The reference doc is updated to describe the new CLI flag and context interface

.github/issue-proposals/docs-pattern-record-and-replay.md

@@ -30,5 +30,5 @@ A `Record and Replay` usage pattern document would describe:
 
 - [ ] A `--record` (or equivalent) CLI flag is implemented that writes captured responses to handler files
 - [ ] `docs/patterns/record-and-replay.md` is added following the established pattern format (Context, Problem, Solution, Example, Consequences, Related Patterns)
-- [ ] The new pattern is linked in `docs/usage-patterns.md`
+- [ ] The new pattern is linked in `docs/patterns/index.md`
 - [ ] The reference doc is updated to describe the new CLI flag

.github/issue-proposals/docs-pattern-webhook-simulation.md

@@ -34,5 +34,5 @@ A `Webhook Simulation` pattern document would describe:
 
 - [ ] An outbound-call mechanism (e.g., `$.webhook()` or `$.emit()`) is implemented and documented
 - [ ] `docs/patterns/webhook-simulation.md` is added following the established pattern format
-- [ ] The new pattern is linked in `docs/usage-patterns.md`
+- [ ] The new pattern is linked in `docs/patterns/index.md`
 - [ ] The reference doc is updated to describe the new API

README.md

@@ -178,8 +178,8 @@ In five minutes, you turned a static spec into a working system:
 | | |
 |---|---|
 | [Getting started](./docs/getting-started.md) | Detailed walkthrough with state, REPL, and proxy |
-| [Usage guide](./docs/usage.md) | Routes, context, REPL, proxy, middleware, programmatic API |
-| [Usage patterns](./docs/usage-patterns.md) | Failures, latency, AI sandboxes, integration tests |
+| [Usage](./docs/usage.md) | Feature index: routes, context, REPL, proxy, middleware, and more |
+| [Patterns](./docs/patterns/index.md) | Failures, latency, AI sandboxes, integration tests |
 | [Reference](./docs/reference.md) | `$` API, CLI flags, architecture |
 | [How it compares](./docs/comparison.md) | json-server, WireMock, Prism, Microcks, MSW |
 | [FAQ](./docs/faq.md) | State, types, regeneration |

docs/comparison.md

@@ -102,7 +102,7 @@ npx counterfact@latest https://petstore3.swagger.io/api/v3/openapi.json api
 ## See also
 
 - [Getting started](./getting-started.md)
-- [Usage patterns](./usage-patterns.md)
+- [Patterns](./patterns/index.md)
 - [Reference](./reference.md)
 - [FAQ](./faq.md)
-- [Usage guide](./usage.md)
+- [Usage](./usage.md)

docs/context-change.md

@@ -287,8 +287,7 @@ Wherever you tell it. The second argument to the CLI is the output directory. Us
 ## See also
 
 - [Getting started](./getting-started.md)
-- [Usage patterns](./usage-patterns.md)
+- [Patterns](./patterns/index.md)
 - [Reference](./reference.md)
 - [How it compares](./comparison.md)
-- [Generated code FAQ](./faq-generated-code.md)
-- [Usage guide](./usage.md)
+- [Usage](./usage.md)

docs/faq-generated-code.md

@@ -0,0 +1,16 @@
+# Generated Code
+
+Counterfact generates two directories from your OpenAPI document:
+
+- 📂 **`types/`** — fully typed request/response interfaces, auto-regenerated whenever the OpenAPI document changes. Don't edit these by hand.
+- 📂 **`routes/`** — one TypeScript file per API path. These are yours to edit. Out of the box each file returns a random, schema-valid response. You can leave them as-is or customize as much as you like.
+
+See the [FAQ](../faq.md) for common questions about source control, editing, and regeneration.
+
+No OpenAPI document? See [using Counterfact without OpenAPI](./without-openapi.md).
+
+## See also
+
+- [Routes](./routes.md) — writing route handlers, reading request data, building responses
+- [State](./state.md) — sharing state across routes with context objects
+- [Usage](../usage.md)