Refine the README: concise two-paragraph intro + ten variants#1839
Refine the README: concise two-paragraph intro + ten variants#1839pmcelhaney merged 2 commits intomainfrom
Conversation
Agent-Logs-Url: https://github.com/counterfact/api-simulator/sessions/f5305cda-5a3a-4f29-a203-45d0c9a137fd Co-authored-by: pmcelhaney <51504+pmcelhaney@users.noreply.github.com>
|
One more idea: Counterfact is a counterfeit server generator for REST APIs. It's designed to produce mocks that are indistinguishable from the real thing, while costing practically nothing to build, run, and maintain. It's built to explore counterfactuals -- scenarios and edge cases that show up in production but are hard to replicate in testing and development. It was designed by an experienced engineer who asked: what if building against an API was like a pit stop at an F1 race? What if we removed all of the friction? All of it. Get up and running in seconds. Define the API's behavior with hot-reloading TypeScript. View and change state directly with a JavaScript REPL. Let your AI loose to run thousands of experiments without hitting rate limits or running up your bill. Try it now: [npx command] |
There was a problem hiding this comment.
Pull request overview
This PR refactors the project’s README into a concise two-paragraph introduction with a quick-start command and “Go deeper” links, and adds 10 alternative README variants under docs/readme-variants/ for team selection.
Changes:
- Replaced the long README walkthrough with a short intro + quick-start + link table.
- Added ten alternate README drafts in
docs/readme-variants/. - Added a patch changeset documenting the README refinement.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Replaces the long walkthrough with a concise intro, quick-start, and deeper-doc links. |
| docs/readme-variants/variant-1.md | Adds an alternate concise README draft (variant 1). |
| docs/readme-variants/variant-2.md | Adds an alternate concise README draft (variant 2). |
| docs/readme-variants/variant-3.md | Adds an alternate concise README draft (variant 3). |
| docs/readme-variants/variant-4.md | Adds an alternate concise README draft (variant 4). |
| docs/readme-variants/variant-5.md | Adds an alternate concise README draft (variant 5). |
| docs/readme-variants/variant-6.md | Adds an alternate concise README draft (variant 6). |
| docs/readme-variants/variant-7.md | Adds an alternate concise README draft (variant 7; matches the selected README direction). |
| docs/readme-variants/variant-8.md | Adds an alternate concise README draft (variant 8). |
| docs/readme-variants/variant-9.md | Adds an alternate concise README draft (variant 9). |
| docs/readme-variants/variant-10.md | Adds an alternate concise README draft (variant 10). |
| .changeset/refine-readme.md | Documents the README rewrite and addition of variants as a patch changeset. |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
|
|
||
| ## Go deeper | ||
|
|
||
| | | | |
There was a problem hiding this comment.
The "Go deeper" table has an empty header row (| | |), leaving column headers unlabeled for screen readers. Add explicit column names (e.g., "Link" / "Description").
| | | | | |
| | Link | Description | |
Summary
Replaces the 192-line five-minute walkthrough README with a tight two-paragraph intro that explains what Counterfact is and why it's different from static mock servers—without the tutorial/marketing framing. Adds ten alternative variants under
docs/readme-variants/for the team to pick from.Original Prompt
It shouldn't be a marketing pitch. It should be a simple, confident explanation of what it is. A couple of paragraphs. Followed by the links to go deeper.
Some key ideas:
Create ten variants of the README.
Manual acceptance tests
docs/getting-started.md,docs/usage.md, etc.)docs/readme-variants/renders cleanly in GitHub Markdown previewnpx counterfact@latest …) matches the previous version exactlyTasks
README.mdusing the "you've used mock servers" angle (variant 7): opens with the known limitations of static mocks, names the REPL as the key differentiator, mentions frontend devs / test engineers / AI agents as audiences, then quick-start + "Go deeper" linksdocs/readme-variants/variant-{1..10}.md— ten distinct takes covering: direct/technical, problem-first, agentic-forward, REPL-forward, minimal, backend-not-ready, peer-to-peer, bold-assertion, three-sentence-summary, and future/agentic anglespatch)