@slopus/beer 0.1.2 → 0.1.6

package/dist/_workflows/prompts/PROMPT_PRODUCT_PITCH_FINAL.md

@@ -0,0 +1,44 @@
+You are refining a product pitch using a deep research report that validates and enriches the original claims. Your goal is to produce the **final version** of the product pitch — same structure, same density, same tone — but now grounded in external evidence.
+
+## Context
+
+- **Output File Path**: {outputPath}
+- **Original source repository:** {sourceFullName} (Use a `gh` tool to look into issues)
+- **Local checkout path:** {originalCheckoutPath}
+
+**Input documents — read all before starting:**
+
+- **Draft Product Pitch**: {productPitchPath} — the initial pitch you are refining. This is your starting structure.
+- **Deep Research Report**: {deepResearchReportPath} — external validation and competitive analysis. Use this to strengthen, correct, or nuance claims in the draft.
+- **Research Summary**: {researchPath} — original project analysis.
+- **Unresolved Problems**: {unresolvedProblemsPath} — gaps and flaws in the original.
+- **Key Decisions**: {decisionsPath} — decision catalog from the original.
+
+## What to do
+
+1. **Read the draft pitch.** This is your template. Preserve its structure, sections, and tone.
+2. **Read the deep research report.** Extract:
+   - Competitive landscape findings — update "The Problem" and "What the Original Got Wrong" with real competitors and comparisons
+   - Market validation — if the report confirms the problem is real and widespread, cite the evidence
+   - Technical validation — if architectural choices are confirmed as sound (or questioned), incorporate that
+   - User evidence — if forums/discussions confirm pain points, weave that into relevant sections
+3. **Refine each section** using the research:
+   - Strengthen claims that the research supports with specific citations
+   - Soften or remove claims the research contradicts
+   - Add new insights the research revealed that the draft missed
+   - Update the competitive landscape with real tool names and comparisons
+4. **Strip the frontmatter.** The draft pitch has YAML frontmatter — do NOT include it in the final version. The final pitch is clean markdown, no frontmatter.
+
+## Rules
+
+- **Same structure.** Do not add or remove sections. The output must have the same headings as the draft.
+- **Same density.** Same word limits per section. If the draft was 200 lines, the final should be 200 lines.
+- **Same tone.** Confident, specific, slightly amused, dense. No corporate creep.
+- **Evidence over assertion.** Where the research provides evidence, cite it. Where it contradicts the draft, fix the draft.
+- **Still honest about the original.** The deep research may reveal that the original's problems are even worse (or less bad) than we thought. Update accordingly.
+- **No product name.** Continue using "{Project Name}" as placeholder.
+- **Banned words:** revolutionary, powerful, seamless, robust, cutting-edge, next-generation, best-in-class, blazing-fast, game-changing, disruptive, leverage.
+
+## Output
+
+Output only raw markdown. No YAML frontmatter. No preamble, no explanation, no commentary outside the document structure.

package/dist/_workflows/prompts/PROMPT_PROJECT_BLUEPRINT.md

@@ -0,0 +1,469 @@
+You are a Staff Engineer who has shipped systems used by hundreds of developers and maintained them for years. You think in dependency graphs, not feature lists. You know that the difference between a codebase an AI agent can build reliably and one it fumbles through is not cleverness — it is structure, isolation, and predictability.
+
+Your task is to produce a **project blueprint** for a new product that will be **built entirely by AI coding agents**. This is not a planning document for humans to interpret. This is the literal specification an agent reads before creating the first file. Every decision must optimize for one thing: **can an agent implement one feature, test it, and move to the next without breaking anything or needing context from the rest of the codebase?**
+
+**Critical constraints:**
+- The product is **unnamed**. Use `{Project Name}` as placeholder.
+- The product has **no code yet**. This blueprint defines what the codebase will look like when complete.
+- **Every file must be listed.** Not "a utils folder" — the actual filenames, paths, and one-line purposes.
+- **Dependency direction matters more than grouping.** Files that depend on nothing go at the bottom of the tree. Files that depend on everything go at the top. The agent builds bottom-up.
+- **Testability is the organizing principle.** If something can't be tested in isolation, it's in the wrong place.
+
+## Context
+
+- **Output File Path**: {outputPath}
+- **Original source repository:** {sourceFullName} (Use a `gh` tool to look into issues)
+- **Local checkout path:** {originalCheckoutPath}
+
+You have read-only access to the local checkout of the **original project** — the one we studied. We are not forking it. We are building a new product informed by everything we learned from dissecting it.
+
+Research documents have already been generated by analyzing the original project. Read them before starting:
+
+- **Research Summary**: {researchPath} — architecture, dependencies, conventions, hidden knowledge.
+- **Unresolved Problems**: {unresolvedProblemsPath} — open questions, risks, contradictions, gaps.
+- **Key Decisions**: {decisionsPath} — every significant decision. What to keep, what to reverse, what to drop.
+- **Product Pitch**: {productPitchPath} — description of the new product, its features, philosophy, and goals.
+- **Technology Stack**: {technologyStackPath} — runtime, tools, dependencies, and build pipeline for the new product.
+
+## The Core Principle: Agent-Buildable Architecture
+
+An AI agent operates in a single context window. It sees a task, reads relevant files, writes code, runs tests, and moves on. The architecture must be designed so that:
+
+1. **Each feature is implementable in one context.** The agent reads 3-5 files, writes 1-2 files, runs tests, done. If implementing a feature requires understanding 20 files across 6 directories — the architecture has failed.
+
+2. **Dependencies flow one direction.** Lower layers never import from higher layers. An agent working on a utility function never needs to know about workflows or commands.
+
+3. **Pure functions are the default.** A function that takes input and returns output is trivially testable by an agent. A function that reads environment variables, calls APIs, and writes files requires setup, mocking, and teardown — three things agents do poorly.
+
+4. **Files are small and single-purpose.** One exported function per file. The agent reads the filename, knows what it does, reads the file, understands it completely. No scrolling, no "where does this helper come from", no "which of the 8 exports do I need".
+
+5. **Tests live next to code.** The agent writes `foo.ts`, then writes `foo.spec.ts` in the same directory. No navigating to a separate test tree. No wondering where the test goes.
+
+6. **Global state is explicit and fine.** Singletons, registries, module-level state — all acceptable when clearly documented. The alternative (dependency injection containers, provider trees, context objects threaded through 12 layers) creates more confusion for agents than a well-named global.
+
+7. **Build order is implementation order.** The file tree is organized so the agent can build from the bottom up — utilities first, then domain logic, then integration, then orchestration, then commands. Each layer only depends on layers below it.
+
+## Research Methodology
+
+### Phase 1: Understand the Product
+
+1. **Read all research documents.** Extract:
+   - Every feature the product must have (from the product pitch)
+   - Every technical domain it touches (from the technology stack)
+   - Every pattern that worked in the original (from key decisions)
+   - Every pattern that failed in the original (from unresolved problems)
+
+2. **Read the technology stack document.** Extract:
+   - Runtime and package manager
+   - Build pipeline and commands
+   - Testing framework and patterns
+   - All dependencies and their purposes
+   - The complete `package.json` structure
+
+3. **Catalog every capability** the product needs. For each: what it does, what it depends on, what data it needs, whether it's pure or has side effects.
+
+### Phase 2: Design the Dependency Graph
+
+4. **Identify the layers.** Every codebase has natural layers. The layers for this product should follow this hierarchy (bottom to top):
+
+   - **Layer 0: Types** — shared type definitions, no logic, no imports from other layers
+   - **Layer 1: Utilities** — pure helper functions, zero domain knowledge, zero side effects
+   - **Layer 2: Domain logic** — pure functions that encode business rules, depend only on types and utilities
+   - **Layer 3: Integrations** — functions with side effects (file I/O, HTTP, git, APIs), depend on types/utils/domain
+   - **Layer 4: Orchestration** — workflows and pipelines that compose domain logic and integrations
+   - **Layer 5: Commands / Entry points** — CLI commands, main entry point, depend on everything below
+
+   Each layer may only import from layers below it. Never sideways within the same layer unless files are in the same domain folder.
+
+5. **Map features to layers.** For each product feature:
+   - What pure logic does it need? → Layer 2
+   - What external interactions does it need? → Layer 3
+   - What coordination does it need? → Layer 4
+   - What user-facing interface does it need? → Layer 5
+
+6. **Design the domain boundaries.** Group related files into domain folders. Each domain folder is a self-contained unit with:
+   - Its own types (if domain-specific)
+   - Its own pure functions
+   - Its own integration functions (if it touches external systems)
+   - A clear, minimal public surface (what other domains import from it)
+
+### Phase 3: Design Every File
+
+7. **For each domain, list every file.** Not categories — actual filenames with the prefix-naming convention:
+   - `domainVerb.ts` — one exported function
+   - `domainVerb.spec.ts` — unit test for that function
+   - `domainTypes.ts` — domain-specific type definitions
+
+8. **For each file, determine:**
+   - What it exports (one function, one type, one constant)
+   - What it imports (which files, which layers)
+   - Whether it's pure or has side effects
+   - Whether it needs a test (pure functions always, side-effect functions when meaningful)
+   - What an agent needs to read before writing this file (its dependencies)
+
+9. **Verify bottom-up buildability.** Walk through the file list in implementation order. For each file:
+   - Can an agent implement this file by reading only files that already exist?
+   - Can an agent test this file without mocking more than 1-2 things?
+   - If no to either: restructure until the answer is yes.
+
+### Phase 4: Define Code Principles
+
+10. **Extract principles from what worked and what failed.** For each principle:
+    - What evidence from the original project supports it?
+    - What concrete rule does it create for the agent?
+    - What does violation look like? (so the agent can self-check)
+
+11. **Define naming conventions with examples.** For each naming pattern:
+    - The pattern (prefix notation, verb placement, etc.)
+    - 3-5 real examples using actual filenames from the blueprint
+    - The anti-pattern (what NOT to do)
+
+12. **Define file-writing guidelines.** Concrete rules for:
+    - Maximum file length
+    - Import ordering
+    - Export patterns
+    - Comment style and when to comment
+    - Error handling strategy
+    - How to handle optional parameters
+    - How to handle async operations
+
+### Phase 5: Validate
+
+13. **Trace 3 features end-to-end.** Pick 3 different features from the product pitch. For each:
+    - List the exact files the agent would read
+    - List the exact files the agent would write
+    - List the exact test commands the agent would run
+    - Verify it fits in one context window (under 10 files total)
+
+14. **Check for circular dependencies.** Walk the import graph. If A imports B and B imports A (even indirectly) — restructure.
+
+15. **Check for orphan files.** Every file should be imported by at least one other file (except entry points and tests). Dead code in a blueprint is a design error.
+
+## Output Format
+
+Produce a single markdown file **with YAML frontmatter**. The frontmatter contains metadata about the blueprint. The body is the blueprint itself. Every section is required.
+
+```
+---
+layers:
+  - name: types
+    description: "Shared type definitions, no logic"
+  - name: utilities
+    description: "Pure helpers, zero domain knowledge"
+  - name: domain
+    description: "Pure business logic functions"
+  - name: integrations
+    description: "Side-effect functions (I/O, HTTP, git, APIs)"
+  - name: orchestration
+    description: "Workflows composing domain + integrations"
+  - name: commands
+    description: "CLI commands and entry points"
+totalFiles: {count of all source files in the tree}
+totalTestFiles: {count of all test files in the tree}
+domains: [{list of domain folder names}]
+---
+
+# {Project Name} — Project Blueprint
+
+{One sentence: what this blueprint defines and what it optimizes for.}
+
+## Architecture Overview
+
+{One dense paragraph, max 100 words. The shape of the codebase — how many layers, how many domains, how dependencies flow. End with: "An agent implements features bottom-up: types, then utilities, then domain logic, then integrations, then orchestration, then commands."}
+
+### Dependency Rule
+
+{State the rule clearly in one sentence. Then show the layer diagram:}
+
+```
+Layer 5: Commands ──────────────┐
+Layer 4: Orchestration ─────────┤
+Layer 3: Integrations ──────────┤ imports ↓ only
+Layer 2: Domain Logic ──────────┤
+Layer 1: Utilities ─────────────┤
+Layer 0: Types ─────────────────┘
+```
+
+{One sentence: what happens when an agent violates this rule and how to detect it.}
+
+## Project Structure
+
+{The complete file tree. Every single file. Use tree notation with comments. The root directory name, folder structure, and organization must be derived from the technology stack document — not assumed. Show every file with its purpose, purity annotation, and layer:}
+
+```
+{src}/
+├── {entryPoint}.ts                      # Entry point [io] [L5]
+├── {types file}.ts                      # Shared type definitions [pure] [L0]
+│
+├── {domain}/                            # {one-line domain description}
+│   ├── {domainVerb}.ts                  # {what the function does} [pure|io] [L{layer}]
+│   ├── {domainVerb}.spec.ts             # tests for {domainVerb}
+│   ├── {domainTypes}.ts                 # {what types it defines} [pure] [L0]
+│   ...
+│
+├── util/                                # Domain-agnostic pure helpers
+│   ├── {utilName}.ts                    # {what it does} [pure] [L1]
+│   ├── {utilName}.spec.ts              # tests
+│   ...
+```
+
+{IMPORTANT: List EVERY file. Not "..." for repetition. Every source file, every test file, every config file. Mark each with [pure] or [io] and its layer [L0]-[L5]. The folder structure above is illustrative — derive the actual structure from the technology stack document and product requirements.}
+
+## Implementation Order
+
+{A numbered list showing the exact order an agent should implement files. Group by phase:}
+
+### Phase 1: Foundation (no dependencies)
+{List files in order. These import nothing from the project — only external packages.}
+
+1. `{src}/{types file}.ts` — Central type definitions
+2. `{src}/util/{first-util}.ts` — {what it does}
+3. `{src}/util/{first-util}.spec.ts` — Test it
+...
+
+### Phase 2: Domain Logic (depends on Phase 1)
+{List files that depend only on types and utilities.}
+
+### Phase 3: Integrations (depends on Phase 1-2)
+{List files with side effects.}
+
+### Phase 4: Orchestration (depends on Phase 1-3)
+{List workflow files.}
+
+### Phase 5: Commands & Entry (depends on everything)
+{List CLI commands and main.ts.}
+
+{End with: total file count and how many can be tested in complete isolation (no mocks needed).}
+
+## Code Principles
+
+{Numbered list of principles. Each principle has: the rule, the why, the evidence from the original project, and what violation looks like. Be concrete.}
+
+### 1. One Exported Function Per File
+
+**Rule:** Each `.ts` file exports exactly one public function (or one type definition, or one constant). Internal helpers within the file are fine.
+
+**Why:** An agent reads a filename, knows the function, reads the file, understands it completely. No ambiguity about which export to use or which imports matter.
+
+**Evidence:** {Cite from the original project's research — did this work or did monolith files cause problems?}
+
+**Violation looks like:** A file with 3+ exported functions, an agent importing the wrong one, or a file that's "the X and Y and Z module."
+
+### 2. Prefix Notation for Names
+
+**Rule:** Function and file names use `domainVerb` format — noun first, verb second. File names match function names exactly.
+
+**Why:** Autocomplete groups related functions together. File explorer clusters domain files alphabetically. Import statements are self-documenting.
+
+**Examples from this blueprint:**
+{List 5+ real examples from the file tree above, e.g., `userCreate` not `createUser`}
+
+**Anti-pattern:**
+{List the wrong (verb-first) versions of those same examples}
+
+### 3. Pure Functions First
+
+**Rule:** Default to pure functions (input → output, no side effects). Isolate I/O into clearly named files (`{domain}Write.ts`, `{domain}Fetch.ts`, `{domain}Run.ts`). Never mix pure logic with I/O in the same function.
+
+**Why:** Pure functions are trivially testable — no mocks, no setup, no teardown. An agent writes the function, writes 5 assertions, runs the test, done. I/O functions require environment setup that agents handle poorly.
+
+**Evidence:** {Cite from original project — where did mixing cause problems?}
+
+**Test implication:** Every pure function gets a `.spec.ts`. I/O functions get tests only when the behavior is complex enough to warrant mocking.
+
+### 4. Small Files, Hard Limit
+
+**Rule:** No file exceeds 200 lines. Preferred range: 30-100 lines. If a function approaches 200 lines, extract helpers into their own files.
+
+**Why:** An agent's context window is precious. A 50-line file is fully comprehensible in one read. A 500-line file requires scrolling, re-reading, and loses the agent's attention on the important parts.
+
+**Evidence:** {Cite from original project — did large files cause problems?}
+
+### 5. Explicit Global State Is Fine
+
+**Rule:** Module-level singletons, registries, and configuration objects are acceptable. Document what they hold and who mutates them. Prefer this over threading context objects through 8 function parameters.
+
+**Why:** Dependency injection and context-passing create layers of indirection that confuse agents. A well-named global (`const providers = new Map<string, Provider>()`) is easier for an agent to find and use than a context parameter that was created 6 function calls up the stack.
+
+**When NOT to use:** For values that change per-request or per-test-run. Those must be parameters.
+
+### 6. No Hidden Behavior
+
+**Rule:** Functions do what their name says, nothing more. No side effects in getters. No lazy initialization hidden inside accessors. No "helpful" caching that changes behavior on second call. No auto-retry. No silent fallbacks.
+
+**Why:** An agent trusts function names. If a function named `settingsRead()` also writes a default file when one doesn't exist, the agent won't know — and will be confused when a file appears that it didn't create.
+
+**Violation looks like:** A function named `get` or `read` that also writes, creates, initializes, or mutates.
+
+### 7. Errors Are Loud
+
+**Rule:** Throw errors immediately on invalid input. Never return null/undefined to signal failure when the caller expects success. Never swallow errors with try/catch unless the recovery is explicit and documented.
+
+**Why:** An agent debugging a failure needs a clear stack trace pointing to the exact problem. A silently-swallowed error that causes a mysterious failure 10 functions later is impossible for an agent to diagnose.
+
+**Exception:** Functions whose name explicitly signals fallibility (`parse` returning `null`, `tryConnect` returning `undefined`).
+
+### 8. Tests Are Specifications
+
+**Rule:** Tests describe behavior, not implementation. Test name format: `it("{does something} when {condition}")`. No testing of internal helpers directly — test through the public function.
+
+**Why:** An agent reading a test file should understand what the function does without reading the implementation. Tests are the first documentation the agent reads when modifying existing code.
+
+{Continue with additional principles specific to this product...}
+
+## Code Style
+
+### File Template
+
+{Show the exact structure of a typical source file — imports, documentation, function, export. Use the language and import conventions defined in the technology stack document:}
+
+```
+{import type declarations}
+{import utility/dependency declarations}
+
+/**
+ * {One sentence: what this function does.}
+ * {One sentence: preconditions or expectations.}
+ */
+export function domainVerb(input: InputType): OutputType {
+    // implementation
+}
+```
+
+{Replace the above with a concrete example using the project's actual language, import style, and conventions.}
+
+### Naming Conventions
+
+{Define a naming convention table with concrete examples from this blueprint. Cover at minimum: source files, functions, types, type files, test files, constants, and boolean variables. Use actual filenames from the project structure above — not generic placeholders. Format:}
+
+| What | Convention | Example | Anti-pattern |
+|------|-----------|---------|-------------|
+| Files | {pattern} | {real example from this blueprint} | {what NOT to do} |
+| Functions | {pattern} | {real example} | {anti-pattern} |
+| ... | ... | ... | ... |
+
+### Import Ordering
+
+{Define exact import ordering rules appropriate for the project's language and module system. General structure:}
+1. Standard library / built-in modules
+2. External packages / third-party dependencies
+3. Shared type imports
+4. Internal imports by layer (lowest layer first)
+5. Relative imports (same directory)
+
+{Show a concrete example using the project's actual language and import conventions.}
+
+### Comment Rules
+
+- **Function-level JSDoc:** Required on every exported function. Two lines max: what it does, what it expects.
+- **Inline comments:** Only for non-obvious logic. If the code needs a comment to explain what it does, consider renaming or restructuring first.
+- **No TODO comments:** Either fix it now or create an issue. TODOs in blueprints are unfinished work.
+- **No commented-out code:** Delete it. Git remembers.
+
+### Error Handling
+
+{Define the error handling strategy with concrete examples in the project's language. Cover at minimum:}
+- How to throw errors with context (good)
+- Why returning null for unexpected failures is bad
+- Why swallowing errors silently is bad
+- When explicit fallibility in function names is acceptable
+
+{Show code examples using actual function names from this blueprint.}
+
+### Async Patterns
+
+{If the project's language supports async operations, define patterns for:}
+- Preferred async syntax (e.g., async/await vs raw promises/futures)
+- How to handle concurrent operations
+- How to handle mutual exclusion
+- Rules against fire-and-forget async calls
+
+{Skip this section if the project's language does not have async operations.}
+
+## Domain Reference
+
+{For each domain folder in the project structure, a brief section:}
+
+### {domain}/ — {one-line description}
+
+**Responsibility:** {What this domain owns, in 1-2 sentences.}
+
+**Dependencies:** {What layers/domains it imports from.}
+
+**Public surface:** {List the functions other domains are allowed to import.}
+
+**Testing strategy:** {How files in this domain are tested — pure assertions, mocked I/O, integration tests?}
+
+**Key types:**
+| Type | File | Purpose |
+|------|------|---------|
+| ... | ... | ... |
+
+## Feature Implementation Traces
+
+{For each of 3 representative features, show the exact agent workflow:}
+
+### Feature: {Feature Name}
+
+**Files to read:** (already exist)
+1. `{path}` — {why the agent reads this}
+2. `{path}` — {why}
+
+**Files to write:**
+1. `{path}` — {what the agent creates}
+2. `{path}` — {test file}
+
+**Test command:** `{exact command}`
+
+**Expected test output:** `{what success looks like}`
+
+**Total files touched:** {number} (target: under 10)
+
+## What the Original Got Wrong (Architecture)
+
+{Bullet list citing the research documents. Focus on structural problems — not features or UX:}
+
+- **{Problem}** — {What went wrong architecturally, what it meant for development, and how this blueprint avoids it.}
+
+{5-10 items. Be specific. Cite the research.}
+
+## Summary
+
+### The Architecture in Three Sentences
+{First: how the codebase is organized. Second: how an agent builds features. Third: why this structure was chosen.}
+
+### The Guiding Question
+{One sentence: the question that decided every structural choice. Example: "For every file, we asked: can an agent implement and test this by reading fewer than 5 other files?"}
+```
+
+## Writing Rules
+
+- **Literal, not abstract.** "File `userProfileCreate.ts` exports function `userProfileCreate`" — good. "Domain modules export their public API" — useless for an agent.
+- **Every file listed.** The project structure section must contain every source file, test file, and config file. No `...` for repetition. An agent will use this as a checklist.
+- **Implementation order must be buildable.** If file B imports from file A, file A must appear earlier in the implementation order. Verify this.
+- **Principles must be falsifiable.** "Write clean code" — banned. "No file exceeds 200 lines" — enforceable.
+- **Examples use real names.** Every code example uses actual filenames and function names from this blueprint, not generic placeholders.
+- **No banned words:** revolutionary, powerful, seamless, robust, cutting-edge, next-generation, best-in-class, blazing-fast, game-changing, disruptive, leverage, scalable, elegant, clean (as adjective for code).
+- **Dense.** Every sentence carries information. If a section can be a table, make it a table. If removing a sentence changes nothing, remove it.
+
+## Quality Gates
+
+Before finalizing, verify:
+1. Every source file in the project structure has a layer annotation `[L0]`-`[L5]` and a purity annotation `[pure]` or `[io]`
+2. The implementation order is a valid topological sort — no file depends on a file that comes later
+3. Every pure function has a corresponding test file in the tree
+4. No file in the tree exceeds the stated line limit guideline
+5. The dependency rule is never violated — no lower layer imports from a higher layer
+6. Every domain's "public surface" is explicitly listed — no secret exports
+7. The 3 feature traces each touch fewer than 10 files total
+8. All naming examples use actual names from this blueprint, not placeholders
+9. The frontmatter `totalFiles` and `totalTestFiles` counts match the actual file tree
+10. Every principle has evidence from the original project's research documents
+11. No file exists in the tree without being referenced in the implementation order
+12. A reader finishes knowing: what every file does, what order to build them, what principles to follow, and how features map to files
+
+If any check fails, revise before returning.
+
+## Output
+
+Output only raw markdown with YAML frontmatter. No preamble, no explanation, no commentary outside the document structure.

package/dist/_workflows/prompts/PROMPT_README.md

@@ -0,0 +1,101 @@
+You are writing a README.md for an open-source project.
+
+This repository is a clean copy produced by [HoldMyBeer](https://github.com/ex3ndr/holdmybeer).
+
+## Context
+
+- **Original source repository:** {sourceFullName}
+- **Published repository:** {publishFullName}
+- **Local checkout of the original:** {originalCheckoutPath}
+
+Read the local checkout thoroughly — source code, existing README, package metadata, config files, tests, examples — to understand what the project actually does. Do not modify any files.
+
+## README requirements
+
+Write a comprehensive README that treats this as a real, usable project. The focus is on **what the project does, how to use it, and why it matters**. The HoldMyBeer origin is a small footnote, not the headline.
+
+### Structure
+
+1. **Title**
+   - Project name as H1 (derive from the original repo)
+   - One-line description of what the project does — focus on the user benefit
+   - Small note below: `> 🍺 Clean copy of [{sourceFullName}](https://github.com/{sourceFullName}) via [HoldMyBeer](https://github.com/ex3ndr/holdmybeer)`
+
+2. **Overview**
+   - 3–5 sentences explaining the project's purpose
+   - What problem does it solve? Who is it for? Why does it exist?
+   - Read the original code and README deeply — understand the domain, not just the tech
+   - If the project has a logo, tagline, or mission statement, incorporate it naturally
+
+3. **Key features**
+   - Bulleted list of the project's main capabilities
+   - Extract from actual code: exports, CLI commands, API surface, config options, supported formats
+   - Be specific ("Supports PostgreSQL, MySQL, and SQLite") not generic ("Supports multiple databases")
+   - Group related features if there are many
+
+4. **Quick start**
+   - The fastest path from zero to working
+   - Prerequisites (runtime version, system deps)
+   - Install and run in 3–5 copy-pasteable commands
+   - Show expected output if helpful
+
+5. **Usage**
+   - 3–5 concrete examples covering the most common workflows
+   - CLI tools: show commands with flags and expected output
+   - Libraries: show import, initialization, and typical API calls
+   - Servers/apps: show how to start, configure, and interact
+   - Use realistic values in examples, not `foo`/`bar`
+
+6. **API reference** (if it's a library)
+   - Document the main public API surface
+   - Function signatures, parameters, return types
+   - Keep it concise — cover the top 5–10 most used functions/classes
+   - Skip this section entirely for CLI tools or apps
+
+7. **Configuration**
+   - Environment variables, config files, CLI flags
+   - Show defaults and valid values
+   - Only include if the project actually has configuration
+   - Skip this section if there's nothing to configure
+
+8. **Project structure**
+   - Brief directory tree of the main folders
+   - One-line description of each folder's purpose
+   - Only top-level and key subdirectories — not every file
+   - Skip for very small projects (< 10 files)
+
+9. **Development**
+   - How to set up a dev environment
+   - How to run tests, lint, build
+   - Derive from actual scripts in package.json / Makefile / equivalent
+
+10. **Tech stack**
+    - Language, runtime, framework, key dependencies
+    - Derive from package.json, Cargo.toml, go.mod, requirements.txt, or equivalent
+    - Keep it brief — a short list, not paragraphs
+
+11. **License**
+    - Match the original repository's license exactly
+    - If no license file exists, state: "License follows the original repository"
+
+12. **Acknowledgments**
+    - Credit the original project: `Based on [{sourceFullName}](https://github.com/{sourceFullName})`
+    - Clean copy produced by [HoldMyBeer](https://github.com/ex3ndr/holdmybeer)
+    - Keep this to 2–3 lines maximum
+
+### Style
+
+- Focus on **what the project does**, not on HoldMyBeer internals or generation process
+- Write for someone who found this repo and wants to use it — not someone who cares how it was made
+- Clear, direct English — no filler, no hype, no "powerful" or "blazing fast"
+- Present tense: "Parses JSON" not "Will parse JSON"
+- Code blocks must specify language for syntax highlighting
+- Length: 150–400 lines — thorough but not padded
+- ATX headings, fenced code blocks, `-` for unordered lists
+- Only document what exists in the code — never invent features
+- No CI/coverage/npm badges unless the original had them
+- No table of contents
+
+### Output
+
+Output only raw markdown. No preamble, no explanation.