impact-compass 0.2.2 → 0.3.0

package/DOCUMENTATION.md

@@ -1,40 +1,151 @@
 # Impact Compass Documentation
 
-Impact Compass is a purely statistical, deterministic CLI tool that runs your startup idea against public evidence from seven major platforms. It uses zero AI. It calculates demand, pain, momentum, and competition volume using strict mathematical formulas to generate a ruthless product-market fit score.
+Impact Compass is a purely statistical, deterministic CLI tool that runs your project idea against public evidence from seven major platforms. It uses zero AI. It calculates demand, pain, momentum, competition fit, activity, channel fit, and evidence quality using strict scoring logic to generate a ruthless project validation score.
 
 ## Creating Your Idea File
 
-The CLI requires a JSON file containing the core elements of your startup idea. You do not need to overthink this. Just write down what you know. 
+The CLI requires a JSON file containing your idea brief and the keyword bundle it should search. You do not need to overthink this, but do not feed it lazy keywords like `app` or `software` unless you enjoy drowning in garbage data.
 
 Create a file named `idea.json` with the following structure:
 
 ```json
 {
-  "name": "Your Idea Name",
-  "targetUser": "Who is going to use this?",
-  "lens": "What category does this fall under? (e.g. Developer Tools, Productivity)",
-  "problem": "What specific problem are you solving?",
-  "audienceKeywords": ["keyword1", "keyword2"],
-  "problemKeywords": ["complaint1", "pain point 2"],
-  "solutionKeywords": ["solution name", "technology"],
-  "competitorKeywords": ["existing app 1", "competitor 2"],
-  "exclusions": ["unrelated meaning"]
+  "idea": {
+    "name": "Your Idea Name",
+    "problem": "What specific problem are you solving?",
+    "targetUser": "Who is going to use this?",
+    "lens": "What category does this fall under?"
+  },
+  "queryBundleForm": {
+    "problemKeywords": "complaint one, pain point two",
+    "solutionKeywords": "solution name, technology",
+    "audienceKeywords": "target user, buyer persona",
+    "competitorKeywords": "existing app one, competitor two",
+    "exclusions": "unrelated meaning, wrong market"
+  }
 }
 ```
 
 ### Keywords Matter
-The scoring engine is merciless. If you use generic keywords like "app" or "software", the engine will pull in thousands of irrelevant results. Use the `exclusions` array to filter out noise. If your tool is for "React State Management," put "React Native" in the exclusions if you don't support mobile.
+The scoring engine is merciless. If you use generic keywords, the engine will pull in thousands of irrelevant results and confidently tell you the ocean is soup. Use `exclusions` to filter out wrong meanings. If your tool is for React state management, put `vue` and `angular` in exclusions if you do not care about those worlds.
 
 ## Running the Evaluation
 
 Execute the CLI by passing your input file and a destination for the report:
 
 ```bash
-npm run cli idea.json output.json
+npm i impact-compass
+npx impact-compass idea.json output.json
 ```
 
 The tool takes about 5-10 seconds to scrape the live APIs. It does not use cached data. It will then print an ASCII dashboard to your terminal and save the raw data to your output file.
 
+## Output JSON Schema
+
+The output file is a full report, not just a cute score slapped in a JSON trench coat.
+
+```json
+{
+  "methodologyVersion": "0.1",
+  "idea": {
+    "name": "A fast global state manager for React",
+    "problem": "Redux has too much boilerplate...",
+    "targetUser": "React Developers",
+    "lens": "Developer Tools"
+  },
+  "queryBundle": {
+    "version": 1,
+    "locked": true,
+    "problemKeywords": ["react state management"],
+    "solutionKeywords": ["atomic state"],
+    "audienceKeywords": ["frontend developer"],
+    "competitorKeywords": ["zustand"],
+    "painPhrases": ["manual process", "workaround"],
+    "exclusions": ["vue", "angular"]
+  },
+  "queryQuality": {
+    "label": "Strong",
+    "warning": "Ambiguity controlled with audience terms and exclusions."
+  },
+  "pillars": [
+    {
+      "key": "demand",
+      "label": "Demand",
+      "score": 100,
+      "note": "Demand reads public-search targets..."
+    }
+  ],
+  "formulas": [
+    {
+      "pillar": "Demand",
+      "score": 100,
+      "formula": "0.45 volume + 0.25 unique authors + ...",
+      "formulaLatex": "0.45V + ...",
+      "inputs": ["mention volume", "unique authors"]
+    }
+  ],
+  "summary": {
+    "score": 69,
+    "uncertainty": 9,
+    "confidence": "Medium",
+    "range": {
+      "lower": 60,
+      "upper": 78
+    }
+  },
+  "integrity": {
+    "finalScoreAvailable": true,
+    "confidenceCap": "Low",
+    "warnings": []
+  },
+  "evidence": [
+    {
+      "id": "gh-123",
+      "source": "GitHub",
+      "sourceType": "repo",
+      "date": "2026-05-24",
+      "query": "atomic state",
+      "snippet": "owner/repo-name",
+      "link": "https://github.com/owner/repo-name",
+      "metricContribution": "Activity",
+      "included": true,
+      "reason": "25 stars",
+      "duplicateCluster": "gh-123",
+      "signalStrength": 42
+    }
+  ],
+  "strongestPillar": {
+    "key": "demand",
+    "label": "Demand",
+    "score": 100,
+    "note": "..."
+  },
+  "weakestPillar": {
+    "key": "competitionFit",
+    "label": "Competition Fit",
+    "score": 22,
+    "note": "..."
+  },
+  "interpretation": "Public evidence supports deeper validation...",
+  "disclaimer": "This score reflects public evidence..."
+}
+```
+
+### Output Fields
+
+- `methodologyVersion`: Report logic version.
+- `idea`: The idea brief you submitted.
+- `queryBundle`: The locked, parsed keyword bundle the engine actually used.
+- `queryQuality`: A label and warning about whether your keywords are too broad, too narrow, ambiguous, good enough, or strong.
+- `pillars`: The seven score pillars: Demand, Pain, Momentum, Competition Fit, Activity, Channel Fit, and Evidence Quality.
+- `formulas`: Human-readable formula notes for each pillar. `formulaLatex` is included for tools that can render it, but the README keeps things readable for normal humans.
+- `summary`: Final score, uncertainty, confidence label, and score range.
+- `integrity`: Whether a final score is available and any confidence warnings from weak evidence, low diversity, or noisy queries.
+- `evidence`: The normalized source hits used by the report. This is where the bodies are buried.
+- `strongestPillar` / `weakestPillar`: Fast diagnosis of what is carrying the idea and what is trying to sink it.
+- `interpretation`: The blunt verdict text printed by the engine.
+- `disclaimer`: Reminder that public signal is not destiny, it is just better than asking a chatbot to bless your startup.
+
 ## Interpreting the Score
 
 - **90 - 100:** You found a unicorn. Massive demand, massive pain, almost zero competition. Start building immediately.

package/README.md

@@ -2,13 +2,26 @@
 
 *grab a compass before you sail soldier*
 
-A purely statistical, deterministic project idea validator and market research CLI.
+```bash
+npm i impact-compass
+npx impact-compass idea.json output.json
+```
+
+[Documentation](DOCUMENTATION.md) / [Agent Skill Guide](SKILLS.md)
+
+A purely statistical, deterministic startup idea validator and market research CLI for founders, indie hackers, builders, and developer-tool maniacs.
 
-Impact Compass fetches keyword rankings and engagement signals from real sources like GitHub, npm, Reddit, Stack Exchange, Hacker News, Wikipedia, and the App Store. It checks the *hype* around your project before you waste six months, a billion tokens, and enough coffee to make your keyboard anxious.
+Impact Compass runs product-market fit checks, demand validation, competitive analysis, and market saturation scoring from public evidence. It fetches keyword rankings and engagement signals from real sources like GitHub, npm, Reddit, Stack Exchange, Hacker News, Wikipedia, and the App Store. It checks the *hype* around your project before you waste six months, a billion tokens, and enough coffee to make your keyboard anxious.
 
 No AI. No vibes. No GPT wrapper whispering "*yo this idea is goated*" right before it lies to your face and stabs you in the roadmap.
 
-Impact Compass is a deterministic engine. It pulls live, real-world evidence through an API-based keyword scoring pipeline, then runs that data through a brutal scoring engine to tell you if you found a blue ocean or if you are walking into another brilliant project that nobody wants.
+Impact Compass is a deterministic validation engine. It pulls live, real-world evidence through an API-based keyword scoring pipeline, then runs that data through a brutal scoring engine to tell you if you found a blue ocean or if you are walking into another brilliant project that nobody wants.
+
+Built for:
+- founders doing startup validation before writing code
+- indie hackers checking if a niche has actual demand
+- developers comparing saturated markets before shipping another clone
+- AI coding agents that need real market evidence before they start generating files like caffeinated interns
 
 ## The Problem
 
@@ -22,19 +35,6 @@ Why? Because you didn't measure the noise. High demand means nothing if the mark
 
 Impact Compass takes your idea and compiles a query bundle (problems, solutions, target audiences, and competitors). It then pulls live data from seven pillars of public evidence and runs an advanced logarithmic scoring algorithm. 
 
-```mermaid
-flowchart TD
-  A["Idea brief JSON"] --> B["Query bundle compiler"]
-  B --> C["35 source adapters"]
-  C --> D["Public APIs: GitHub, Reddit, npm, Hacker News, Stack Exchange, Wikipedia, App Store"]
-  D --> E["Evidence normalizer"]
-  E --> F["Relevance filter: weak keyword match loses 60% signal"]
-  F --> G["Pillar scorers: demand, pain, momentum, activity, competition, channel fit, evidence quality"]
-  G --> H["Weighted score engine"]
-  H --> I["Red ocean saturation penalty"]
-  I --> J["Final score, confidence, interpretation, JSON report"]
-```
-
 It measures:
 - **Demand & Pain:** Are people actually complaining about this, or is the problem minor?
 - **Momentum & Activity:** Are developers and founders actively building in this space right now?
@@ -53,17 +53,13 @@ Translation: big demand is good, but big demand plus a crushed competition score
 
 The engine spits out a final score out of 100, along with a brutally honest interpretation of whether you should build it, pivot, or drop the idea entirely.
 
-<p align="center">
-  <!-- Demo GIF coming after npm publish: CLI run, ASCII art, and React State Management score. -->
-</p>
-
 ## Quickstart
 
-Install dependencies, then run an evaluation:
+Install the published package, then run an evaluation:
 
 ```bash
-npm install
-npm run cli example-react.json output.json
+npm i impact-compass
+npx impact-compass idea.json output.json
 ```
 
 ### The Input Schema

package/SKILLS.md

@@ -25,7 +25,7 @@ When the user asks you to "validate this idea" or "is this a good startup idea":
 
 1. **Ask clarifying questions (if needed):** Ensure you understand the specific target audience, the exact problem, and any known competitors.
 2. **Draft the Query Bundle:** Create an `idea.json` file in the workspace representing the user's idea. Keep the keywords highly specific to avoid false positives.
-3. **Run the CLI:** Execute `npm run cli idea.json output.json` (assuming Impact Compass is installed in the current workspace or accessible globally).
+3. **Run the CLI:** Execute `npx impact-compass idea.json output.json` after installing the package with `npm i impact-compass`, or use the local project script when working inside the source repo.
 4. **Read the Output:** Read the resulting `output.json` file.
 5. **Report to the User:** Do not just paste the JSON. Interpret the score for the user. Highlight their strongest pillar (e.g. Demand) and their weakest pillar (e.g. Competition Fit). If the score was heavily penalized due to market saturation (Red Ocean), warn them.
 
@@ -35,18 +35,115 @@ Write this to `idea.json` before running the CLI:
 
 ```json
 {
-  "name": "Visual SQL Builder",
-  "targetUser": "Data Analysts",
-  "lens": "Developer Tools",
-  "problem": "Writing complex joins is error-prone for junior analysts.",
-  "audienceKeywords": ["data analyst", "BI developer"],
-  "problemKeywords": ["sql join error", "too many sql tables"],
-  "solutionKeywords": ["visual sql", "no-code sql"],
-  "competitorKeywords": ["metabase", "looker"],
-  "exclusions": ["nosql", "mongodb"]
+  "idea": {
+    "name": "Visual SQL Builder",
+    "problem": "Writing complex joins is error-prone for junior analysts.",
+    "targetUser": "Data Analysts",
+    "lens": "Developer Tools"
+  },
+  "queryBundleForm": {
+    "problemKeywords": "sql join error, too many sql tables",
+    "solutionKeywords": "visual sql, no-code sql",
+    "audienceKeywords": "data analyst, BI developer",
+    "competitorKeywords": "metabase, looker",
+    "exclusions": "nosql, mongodb"
+  }
 }
 ```
 
+## Output JSON Schema
+
+After the CLI runs, read `output.json`. Treat it as the evidence packet, not just a number.
+
+```json
+{
+  "methodologyVersion": "0.1",
+  "idea": {
+    "name": "Visual SQL Builder",
+    "problem": "Writing complex joins is error-prone for junior analysts.",
+    "targetUser": "Data Analysts",
+    "lens": "Developer Tools"
+  },
+  "queryBundle": {
+    "version": 1,
+    "locked": true,
+    "problemKeywords": ["sql join error"],
+    "solutionKeywords": ["visual sql"],
+    "audienceKeywords": ["data analyst"],
+    "competitorKeywords": ["metabase"],
+    "painPhrases": ["manual process", "workaround"],
+    "exclusions": ["nosql"]
+  },
+  "queryQuality": {
+    "label": "Strong",
+    "warning": "Ambiguity controlled with audience terms and exclusions."
+  },
+  "pillars": [
+    {
+      "key": "demand",
+      "label": "Demand",
+      "score": 82,
+      "note": "Demand reads public-search targets..."
+    }
+  ],
+  "formulas": [
+    {
+      "pillar": "Demand",
+      "score": 82,
+      "formula": "0.45 volume + 0.25 unique authors + ...",
+      "formulaLatex": "0.45V + ...",
+      "inputs": ["mention volume", "unique authors"]
+    }
+  ],
+  "summary": {
+    "score": 67,
+    "uncertainty": 10,
+    "confidence": "Medium",
+    "range": {
+      "lower": 57,
+      "upper": 77
+    }
+  },
+  "integrity": {
+    "finalScoreAvailable": true,
+    "confidenceCap": "Low",
+    "warnings": []
+  },
+  "evidence": [
+    {
+      "id": "gh-123",
+      "source": "GitHub",
+      "sourceType": "repo",
+      "date": "2026-05-24",
+      "query": "visual sql",
+      "snippet": "owner/repo-name",
+      "link": "https://github.com/owner/repo-name",
+      "metricContribution": "Activity",
+      "included": true,
+      "reason": "25 stars",
+      "duplicateCluster": "gh-123",
+      "signalStrength": 42
+    }
+  ],
+  "strongestPillar": {
+    "key": "demand",
+    "label": "Demand",
+    "score": 82,
+    "note": "..."
+  },
+  "weakestPillar": {
+    "key": "competitionFit",
+    "label": "Competition Fit",
+    "score": 28,
+    "note": "..."
+  },
+  "interpretation": "Public evidence supports deeper validation...",
+  "disclaimer": "This score reflects public evidence..."
+}
+```
+
+When reporting back, prioritize `summary`, `strongestPillar`, `weakestPillar`, `integrity.warnings`, and the top `evidence` items. The user does not need a JSON dump. They need to know whether the market is alive, saturated, noisy, or fake.
+
 ## Why This Matters
 
 As an AI agent, you are great at writing code, but you suffer from hallucinations when guessing what people actually want to buy. Impact Compass prevents you from building "ghost town" products. The tool itself contains zero AI. By relying on its deterministic, mathematical scoring of live public evidence from GitHub, Hacker News, Reddit, and Stack Exchange, you anchor your development roadmap in cold, hard reality.

package/bin/impact-compass.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-require-imports */
+const { spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const tsxCli = require.resolve("tsx/cli");
+const cliEntry = path.resolve(__dirname, "../src/cli.ts");
+const result = spawnSync(process.execPath, [tsxCli, cliEntry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "impact-compass",
-  "version": "0.2.2",
-  "description": "Deterministic market research CLI for startup idea validation, demand scoring, and competitive analysis.",
+  "version": "0.3.0",
+  "description": "Startup idea validator and market research CLI for product-market fit, demand validation, and competitive analysis.",
+  "author": "Aditya Chauhan",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -12,24 +13,39 @@
     "url": "https://github.com/adityachauhan0/impact-compass/issues"
   },
   "private": false,
+  "bin": {
+    "impact-compass": "./bin/impact-compass.js"
+  },
   "keywords": [
     "market-research",
     "idea-validation",
     "startup-validation",
+    "startup-idea-validator",
     "product-validation",
     "market-validation",
     "competitive-analysis",
     "product-market-fit",
+    "pmf",
     "demand-validation",
     "demand-analysis",
     "market-analysis",
+    "market-saturation",
+    "red-ocean",
+    "blue-ocean",
+    "trend-analysis",
+    "public-evidence",
     "startup",
+    "startup-ideas",
+    "saas",
     "founder-tools",
     "indie-hacker",
+    "indie-hackers",
     "mvp",
     "cli",
+    "npx",
     "analytics",
     "developer-tools",
+    "ai-agents",
     "scoring",
     "deterministic",
     "no-ai",
@@ -40,6 +56,7 @@
     "stackexchange"
   ],
   "files": [
+    "bin/",
     "src/",
     "DOCUMENTATION.md",
     "SKILLS.md",
@@ -54,12 +71,16 @@
     "lint": "eslint",
     "cli": "npx tsx src/cli.ts"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "katex": "^0.17.0",
     "lucide-react": "^1.16.0",
     "next": "16.2.6",
     "react": "19.2.4",
-    "react-dom": "19.2.4"
+    "react-dom": "19.2.4",
+    "tsx": "^4.22.3"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",

package/src/cli.ts

@@ -59,7 +59,7 @@ function wrapText(text: string, width: number): string[] {
 async function main() {
   const args = process.argv.slice(2);
   if (args.length < 2) {
-    console.error(`Usage: npm run cli <input.json> <output.json>`);
+    console.error(`Usage: impact-compass <input.json> <output.json>`);
     process.exit(1);
   }