docs: lead with UI-first prototyping

.changeset/bright-uis-lead.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Lead the package documentation with Counterfact's UI-first prototyping workflow.

README.md

@@ -2,10 +2,13 @@
 
 <h1><img src="./counterfact.svg" alt="Counterfact" border="0"></h1>
 
-## Turn an OpenAPI document into an editable, stateful local API.
+## Prototype your UI before investing in backend development
 
 </div>
 
+Counterfact turns an OpenAPI document into an editable, stateful local API so
+your frontend can explore real workflows before the backend exists.
+
 Counterfact is organized as a monorepo. The published `counterfact` package,
 its complete overview, and its canonical user documentation live in
 [`packages/counterfact`](./packages/counterfact/README.md).

packages/counterfact/README.md

@@ -4,13 +4,15 @@
 
 ![MIT License](https://img.shields.io/badge/license-MIT-blue) [![Coverage Status](https://coveralls.io/repos/github/counterfact/api-simulator/badge.svg)](https://coveralls.io/github/counterfact/api-simulator) ![Swagger 2.0](https://img.shields.io/badge/Swagger-2.0-85EA2D) ![OpenAPI 3.0–3.2](https://img.shields.io/badge/OpenAPI-3.x-6BA539) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/counterfact/api-simulator)
 
-## Turn an OpenAPI document into an editable, stateful local API.
+## Prototype your UI before investing in backend development
 
 </div>
 
-Counterfact generates TypeScript handlers and request/response types for supported OpenAPI operations, then starts a local server. Begin with schema-derived sample responses; add shared state, failures, latency, middleware, or selective proxying as your workflow needs them. Route and context files hot-reload while their in-memory state stays available.
+Counterfact turns an OpenAPI document into an editable, stateful local API for your frontend. Build the UI early, use it to work out the workflow and behavior people need, then invest in a real backend with those decisions in hand. Give someone a prototype they can genuinely try: create data, return to it later, retry an action, or see a deliberate empty, error, or alternate state. Route and context files hot-reload while their in-memory state stays available.
 
-Counterfact checks contract shape while giving you a path to shape the behavior. Start with schema-derived responses, then turn them into deterministic, stateful scenarios by editing the generated typed handlers and adding shared context. Model the workflow your client needs, not the real backend's internal complexity. You can explore in seconds and keep the behavior you author as a repeatable local or CI fixture.
+Start with schema-derived sample responses, then turn them into deterministic, stateful scenarios by editing generated TypeScript handlers and adding shared context. Counterfact keeps the contract in the loop while you shape behavior: model the workflow a person needs to explore, not the real backend's internal complexity. The workflow you author remains a repeatable local or CI fixture when you are ready to automate it.
+
+For a single scripted screen, a hard-coded fixture or local component state is usually simpler. Use Counterfact when a prototype needs to withstand real exploration across requests, or when an unavailable or broken backend makes it hard to tell whether a problem is in the UI.
 
 ## Run a live API in 60 seconds
 
@@ -29,13 +31,14 @@ npx counterfact ./openapi.yaml api
 
 ## Start with the workflow you need
 
-| When you need to…                      | You can…                                                         | Start here                                                                                                                                                      |
-| -------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Build ahead of your backend            | Create a record, read it later, and shape the failure paths      | [Build a stateful flow](./docs/first-10-minutes.md#build-a-stateful-flow)                                                                                       |
-| Make failures repeatable               | Reset, fail, recover, and tear down the same way every run       | [Automate a deterministic test](./docs/first-10-minutes.md#automate-a-deterministic-test)                                                                       |
-| Give a coding agent a reliable sandbox | Leave a resettable context and an HTTP test for review           | [Give an agent a verifiable task](./docs/first-10-minutes.md#give-an-agent-a-verifiable-task)                                                                   |
-| Bring endpoints online gradually       | Keep one client base URL while paths move from local to upstream | [Run the checked hybrid path](https://github.com/counterfact/api-simulator/tree/main/examples/first-10-minutes#hybrid-path-ownership)                           |
-| Keep the contract in the loop          | Regenerate types and catch drift in your normal type check       | [See a contract change reach a client](https://github.com/counterfact/api-simulator/tree/main/examples/first-10-minutes#see-a-contract-change-reach-the-client) |
+| When you need to…                        | You can…                                                                            | Start here                                                                                                                                                      |
+| ---------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Prototype a UI before backend investment | Create data, revisit it later, and deliberately show errors or alternate outcomes   | [Build a stateful flow](./docs/first-10-minutes.md#build-a-stateful-flow)                                                                                       |
+| Build or debug a UI independently        | Use a controlled API world while the real backend is absent, unavailable, or broken | [Build a stateful flow](./docs/first-10-minutes.md#build-a-stateful-flow)                                                                                       |
+| Make failures repeatable                 | Reset, fail, recover, and tear down the same way every run                          | [Automate a deterministic test](./docs/first-10-minutes.md#automate-a-deterministic-test)                                                                       |
+| Give a coding agent a reliable sandbox   | Leave a resettable context and an HTTP test for review                              | [Give an agent a verifiable task](./docs/first-10-minutes.md#give-an-agent-a-verifiable-task)                                                                   |
+| Bring endpoints online gradually         | Keep one client base URL while paths move from local to upstream                    | [Run the checked hybrid path](https://github.com/counterfact/api-simulator/tree/main/examples/first-10-minutes#hybrid-path-ownership)                           |
+| Keep the contract in the loop            | Regenerate types and catch drift in your normal type check                          | [See a contract change reach a client](https://github.com/counterfact/api-simulator/tree/main/examples/first-10-minutes#see-a-contract-change-reach-the-client) |
 
 The [first-10-minutes guide](./docs/first-10-minutes.md) includes the shared setup, reset and isolation rules, CI lifecycle, and the boundary between contract checks and behavior realism.