@pickled-dev/cli 0.1.0 → 0.3.0

package/README.md

@@ -2,122 +2,131 @@
 
 > Stay fresh in AI 🥒
 
-Your developer tool is great. But does AI know that?
-
-Pickled checks how often AI models actually recommend your tool when developers ask questions. Point it at a GitHub repo, and we'll tell you if you're well preserved—or starting to spoil.
+Test how well AI responds to questions about your developer tool. Define scenarios, run checks, and see your freshness score.
 
 ## Installation
 
 ```bash
-# Global install
 bun add -g @pickled-dev/cli
-
-# Or run directly
-bunx @pickled-dev/cli check github.com/org/repo
 ```
 
-You'll need an Anthropic API key:
+## Usage
+
+### 1. Initialize config
 
 ```bash
-export ANTHROPIC_API_KEY=your-key-here
+pickled init
 ```
 
-## Usage
+Creates a `pickled.yml` file:
 
-```bash
-pickled check <repo>
-```
+```yaml
+tool:
+  name: "your-tool"
+  description: "What your tool does"
 
-That's it. We'll handle the rest.
+scenarios:
+  - name: "Installation"
+    prompt: "How do I install this tool?"
 
-### Options
+  - name: "Getting started"
+    prompt: "How do I set up this tool for my project?"
 
-| Flag | What it does |
-|------|--------------|
-| `--json` | Output as fresh JSON |
-| `-o, --output <file>` | Save your freshness report (.json or .xml) |
-| `-v, --verbose` | Show the full pickling process |
-| `-c, --competitors <list>` | Bring your own shelf mates (skip auto-discovery) |
+  - name: "Basic usage"
+    prompt: "Show me a basic example of using this tool"
+```
+
+### 2. Edit your config
 
-### Examples
+Update `pickled.yml` with your actual tool info and scenarios developers might ask about.
+
+### 3. Run check
 
 ```bash
-# How fresh is zod?
-pickled check github.com/colinhacks/zod
+pickled check
+```
 
-# Check against specific competitors
-pickled check github.com/colinhacks/zod -c "yup,joi,valibot"
+## Commands
 
-# Save the report
-pickled check github.com/colinhacks/zod -o report.json
+### `pickled init [path]`
 
-# Watch the whole process
-pickled check github.com/colinhacks/zod -v
-```
+Create a starter `pickled.yml` config file.
+
+### `pickled check [path]`
+
+Run freshness checks and report results.
 
-## What You'll See
+| Option                | Description            |
+| --------------------- | ---------------------- |
+| `--json`              | Output as JSON         |
+| `-o, --output <file>` | Save report to file    |
+| `-v, --verbose`       | Show detailed progress |
+| `-t, --threshold <n>` | Min score % to pass    |
+
+## Example Output
 
 ```
-🥒 Freshness Report: zod
+🥒 Freshness Check
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-📦 What's in the jar: zod - TypeScript-first schema validation
-🏷️  Domain: validation
-🫙 Who else is on the shelf: yup, joi, valibot
+Tool: zod
+
+  [default] ✓ "Installation" - Well preserved (92%)
+  [default] ✓ "Basic parsing" - Fresh (85%)
+  [default] ⚠ "Error handling" - Going stale (65%)
+      Missing: safeParse details
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📊 HOW FRESH ARE YOU?
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Freshness Score: 81% 🥒🥒🥒🥒░
 
-Topic: "TypeScript validation library"
-  🥒 zod: 8/10 (80%) - Well preserved!
-  ├─ yup: 5/10 (50%)
-  └─ joi: 2/10 (20%)
+🥒 Looking fresh! Your docs are doing well.
+```
 
-Topic: "Runtime type checking"
-  🥒 zod: 7/10 (70%) - Well preserved!
-  ├─ valibot: 6/10 (60%)
-  └─ yup: 3/10 (30%)
+## Freshness Scores
 
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📈 FRESHNESS SUMMARY
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+| Score | Status | Meaning |
+|-------|--------|---------|
+| 90%+ | Well preserved | AI nails it |
+| 70-89% | Fresh | Good, minor gaps |
+| 50-69% | Going stale | Needs attention |
+| <50% | Gone sour | Major documentation gaps |
 
-Overall freshness: 75% - Looking Fresh 🥒
-Top of the shelf in: 2/2 topics
+## Config Reference
 
-🥒 You're kind of a big dill!
-Stay fresh! 🥒
-```
+```yaml
+tool:
+  name: "tool-name"       # Required: your tool's name
+  description: "desc"     # Required: what it does
 
-## How It Works
+scenarios:                # Required: scenarios to check
+  - name: "Scenario name" # Display name
+    prompt: "The question" # What to ask AI
+    target: target-name   # Optional: specific target
 
-1. **Opens the jar** — Fetches your GitHub repo
-2. **Checks what's inside** — Extracts product info from README and package.json
-3. **Sees who else is on the shelf** — Discovers competitors in your space
-4. **Picks the right questions** — Generates topics developers actually ask about
-5. **Checks your freshness** — Queries AI with those questions
-6. **Gives you the truth** — Reports how often you get picked vs the competition
+targets:                  # Optional: named targets
+  claude-sonnet:
+    category: cli
+    provider: claude-code
+    model: claude-sonnet-4-20250514
 
-## Why This Matters
+threshold: 80             # Optional: min score % to pass
+```
+
+## CI/CD Integration
 
-AI assistants are becoming the new Stack Overflow. When a developer asks "what's the best validation library?", you want to be the answer.
+```yaml
+# GitHub Actions
+- name: Check AI freshness
+  run: pickled check --threshold 80
+```
 
-If you're not getting recommended, your visibility is spoiling. Time to do something about it.
+Fail the build if AI can't answer questions about your tool correctly.
 
 ## Local Development
 
 ```bash
 # From the monorepo root
 bun install
-
-# Copy the example env file and add your API key
-cp apps/cli/.env.example .env
-
-# Run the CLI
-bun dev:cli check github.com/org/repo
+bun run dev:cli -- init
+bun run dev:cli -- check
 ```
-
----
-
-Built with 🥒 by the Pickled team