@uge/payo 0.1.6 → 0.2.0

package/README.md

@@ -13,6 +13,10 @@ project's conventions instead of guessing.
 [![Bun](https://img.shields.io/badge/Bun-%3E%3D1.1.0-black?logo=bun)](https://bun.sh)
 [![Made with TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
+<br />
+
+![Payo demo](https://raw.githubusercontent.com/uttam-gelot/payo/main/assets/demo.gif)
+
 </div>
 
 ---
@@ -20,6 +24,7 @@ project's conventions instead of guessing.
 ## Contents
 
 - [What is Payo?](#what-is-payo)
+- [Why Payo?](#why-payo)
 - [Who is this for?](#who-is-this-for)
 - [Quick Start](#quick-start)
 - [How to use — a walkthrough](#how-to-use--a-walkthrough)
@@ -29,6 +34,7 @@ project's conventions instead of guessing.
 - [Bootstrap prompt](#bootstrap-prompt)
 - [Resume anytime](#resume-anytime)
 - [Requirements](#requirements)
+- [Run locally](#run-locally)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -44,6 +50,38 @@ Where the assistant ships a headless CLI, Payo drives that tool's own AI to
 write rich, project-specific docs; where it doesn't, Payo falls back to solid
 templates — so you always end up with usable output.
 
+## Why Payo?
+
+Every AI coding session starts cold. Your assistant doesn't know you use Drizzle
+over Prisma, that handlers live in `src/routes`, that you write Vitest specs
+beside the file, or that commits follow Conventional Commits. So you re-explain
+it — in chat after chat — and still get code that ignores half of it.
+
+The fix is the guidance files each tool already reads (`CLAUDE.md`,
+`.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.md`). But writing them
+by hand is tedious, easy to get wrong, and different for every tool. Most people
+never do it, or do it once and let it rot.
+
+Payo writes them for you in about two minutes — tailored to your actual stack,
+in each tool's native format — so your assistant follows _your_ conventions from
+the first prompt instead of guessing.
+
+### Vibe coding, without the mess
+
+Vibe coding is fast and fun — you prompt, the AI improvises, code appears. The
+problem isn't the speed, it's that the assistant has no rules to improvise
+_within_. So it guesses: a different ORM than the rest of the repo, files
+scattered wherever, its own naming, your tests and commit conventions skipped.
+Fine for a throwaway demo; on a real codebase it quietly piles up inconsistency
+you pay for later in reviews, bugs, and refactors — and each new chat starts the
+guessing over.
+
+Payo gives that improvisation a guardrail. It generates the guidance files your
+assistant already reads, so the AI reaches for _your_ framework, _your_ folder
+layout, _your_ testing and git rules every time — without you stopping to explain
+them. You keep vibe coding at full speed; the output just fits the project
+instead of fighting it.
+
 ## Who is this for?
 
 - **Devs starting a new repo** who want their AI assistant productive from
@@ -161,7 +199,32 @@ generating what's missing. Finished runs clean the directory up automatically.
 
 ## Requirements
 
-- [Bun](https://bun.sh) **>= 1.1.0**
+**To run Payo:** [Node.js](https://nodejs.org) **>= 18**. That's it — `npx @uge/payo`
+runs the published, Node-targeted binary, so **you do not need Bun to use Payo.**
+If you prefer Bun, `bunx @uge/payo` works too.
+
+**To develop Payo:** [Bun](https://bun.sh) **>= 1.1.0** (the project builds, tests,
+and runs from source with Bun — see [Run locally](#run-locally)).
+
+## Run locally
+
+Hacking on Payo or running it from source:
+
+```bash
+git clone https://github.com/uttam-gelot/payo.git
+cd payo
+bun install        # Bun >= 1.1.0
+bun run dev        # runs src/index.ts directly
+```
+
+Other useful scripts:
+
+```bash
+bun test           # run the test suite
+bun run typecheck  # tsc --noEmit
+bun run lint       # eslint
+bun run build      # bundle to dist/ (Node target)
+```
 
 ## Contributing