tpmjs/LAUNCH_REVIEW.md

TPMJS Launch Review & Checklist

STATUS: COMPLETED - All critical issues have been fixed.

A comprehensive review of all public-facing content for Hacker News launch readiness.

---

Executive Summary

Overall Readiness: 7/10 - Needs Work Before Launch

The website has excellent technical content and professional design, but fails the "5-second test" - a first-time visitor cannot quickly understand what TPMJS is or why they need it. The documentation is strong for existing users but assumes too much prior knowledge about AI agents and tooling.

Critical Issues (Must Fix)

1. Landing page doesn't explain what TPMJS is - Hero section uses jargon without definition
2. "Tool" vs "Package" never defined - Core concepts assumed, not explained
3. Knowledge gaps - Assumes familiarity with AI agents, Zod, semantic search
4. Category inconsistency - HOW_TO_PUBLISH and NPM_MIRROR have different category lists
5. NPM_MIRROR.md conflicts with other docs - Appears outdated, creates confusion

What's Working Well

• Publishing guide (HOW_TO_PUBLISH_A_TOOL.md) is excellent
• How It Works page has great technical depth
• Developer testimonials are concrete with real metrics
• No obvious AI-generated language on website
• Code examples are practical and well-placed

---

The 5-Second Test: FAILED

Question: Can a developer understand what TPMJS is within 5 seconds of landing on the homepage?

Answer: No.

What They See First

TOOL REGISTRY FOR AI AGENTS
Discover, share, and integrate tools that give your agents superpowers

What's Missing

• What is a "tool" in this context?
• What is an "AI agent"?
• Why would I use this vs npm directly?
• Is this a package manager? A marketplace? An SDK?

The "Aha Moment" is Unclear

A visitor still doesn't know:

• WHO should use TPMJS (tool builders? agent developers? both?)
• WHEN they would use it (at development time? runtime?)
• HOW it differs from regular npm packages
• WHY they can't just install packages normally

---

Page-by-Page Clarity Ratings

Page	Clarity	Human Feel	Issues
Landing Page	5/10	Yes	No 5-second explanation, jargon-heavy
Hero Section	3/10	Yes	"Tool registry" undefined, circular language
Problem Section	7/10	Yes	Best section - concrete pain points
Vision Section	5/10	Yes	"Semantic search" unexplained
Developer Stories	7/10	Yes	Good metrics, but code unexplained
Publish Section	6/10	Yes	Assumes visitor is a tool builder
How It Works	9/10	Excellent	Minor density issues
FAQ	8/10	Yes	Missing some common questions
Publish Guide	8.5/10	Yes	Tier system could be clearer upfront
Spec Page	8.5/10	Yes	Assumes Zod/AI SDK knowledge
Docs Page	9/10	Excellent	Overwhelming length
SDK Page	8.5/10	Yes	Assumes Vercel AI SDK familiarity
Privacy	8/10	Yes	Hardcoded email address
Terms	8/10	Yes	Hardcoded date

---

Documentation Clarity Ratings

Document	Clarity	Necessary	Critical Issues
README.md	8/10	YES	Missing "what is TPMJS" explanation
HOW_TO_PUBLISH_A_TOOL.md	9/10	YES	Minor - excellent overall
DEPLOYMENT.md	8/10	YES	Confusing exit code explanation
QUALITY-GATES.md	7/10	OPTIONAL	Could merge into README
MANUAL_TOOLS.md	8.5/10	YES	Good for maintainers
NPM_MIRROR.md	6.5/10	REMOVE	Conflicts with other docs, appears outdated

---

Knowledge Gaps (Things Visitors Won't Understand)

Not Explained Anywhere

1. What is an "AI Agent"? - The entire site assumes you know this
2. What is a "Tool" vs a "Package"? - Used interchangeably, never defined
3. Why semantic search matters - Just says "semantic" without explaining benefit
4. What frameworks are supported - Mentioned in FAQ but not prominently
5. The Package → Tool relationship - Can one package have multiple tools?

Assumed Technical Knowledge

• Zod schemas (used throughout, never introduced)
• AI SDK tool format (referenced as "standard" but what standard?)
• esm.sh and Deno sandboxing (mentioned in How It Works)
• BM25 ranking algorithm (mentioned in docs)

Missing Use Cases

• "Use TPMJS when..." section doesn't exist
• No comparison to alternatives (why not just npm?)
• No "before/after" showing the problem solved

---

Human-Written Assessment

Reads Like Human: YES ✓

• Developer stories use specific metrics ("500 lines to 3")
• Technical explanations show genuine understanding
• Problem section addresses real pain points
• No buzzword soup or meaningless marketing phrases

Minor AI-Sounding Phrases Found

Location	Phrase	Issue
NPM_MIRROR.md:7	"automated NPM-integrated registry"	Marketing speak
NPM_MIRROR.md:27	"✨ Listed automatically"	Emoji in technical doc
NPM_MIRROR.md:500	"Built with ❤️"	Remove emoji
HOW_TO_PUBLISH:389	"AI-friendly descriptions"	Vague - what makes it "AI-friendly"?
Vision Section	"gives agents superpowers"	Metaphor without substance

---

Critical Inconsistencies Found

Category Lists Don't Match

HOW_TO_PUBLISH_A_TOOL.md says:

text-analysis, code-generation, data-processing,
image-generation, audio-processing, search, integration, other

NPM_MIRROR.md says:

web-scraping, data-processing, file-operations, communication,
database, api-integration, image-processing, text-analysis,
automation, ai-ml, security, monitoring

These are completely different! Which is correct?

Quality Score Formula Conflicts

• HOW_TO_PUBLISH: "Tier: Rich (1.0) > Basic (0.5) > Minimal (0.25)"
• MANUAL_TOOLS: "Rich tier tools get 4x quality score multiplier"
• NPM_MIRROR: Different formula entirely

Field Names Inconsistent

• name used in MANUAL_TOOLS but not in HOW_TO_PUBLISH
• Deprecated fields (parameters, returns) mentioned but unclear when deprecated

---

Hardcoded Values to Fix

File	Issue	Line
FAQ, Privacy, Terms	thomasalwyndavis@gmail.com hardcoded	Multiple
Privacy, Terms	Date "December 14, 2025" hardcoded	Multiple
Changelog page	Package list hardcoded in code	~95-110
Developer Stories	Fictional company names (Support.ai, DocFlow)	homePageData.ts

---

Launch Checklist

Must Fix Before Launch (Blocking) - ALL DONE ✓

• Rewrite hero section to explain TPMJS in one sentence

  • Current: "TOOL REGISTRY FOR AI AGENTS"
  • Suggested: "TPMJS lets AI agents discover and use npm packages as tools at runtime. Publish once to npm, get discovered automatically."

• Add "What is TPMJS?" section to landing page

  • Define: What is an AI agent?
  • Define: What is a "tool" in this context?
  • Explain: Why not just use npm directly?
  • Show: 3-step "how it works" visual

• Reconcile category lists between docs (deleted NPM_MIRROR.md)

  • Pick one canonical list
  • Update all docs to match
  • Add categories to types package

• Delete or archive NPM_MIRROR.md (deleted)

  • Conflicts with HOW_TO_PUBLISH
  • Appears to be old design doc, not current state
  • Move to /docs/internal/ if historical value

• Fix hardcoded values (emails → hello@tpmjs.com, dates → December 2024)

  • Email addresses → environment variable
  • Dates → dynamic or remove
  • Package lists → generated from filesystem

Should Fix (High Priority) - MOSTLY DONE

• Add "Use TPMJS when..." section to landing page (covered in "What is TPMJS?" section)

  • List concrete scenarios: "Building a chatbot that needs web access"
  • "Agent that processes different file formats"
  • "Tool that should be discoverable by other agents"

• Explain Package vs Tool distinction (covered in "What is TPMJS?" section)

  • Add glossary or definitions section
  • Clarify: 1 package can have N tools

• Add framework compatibility section (mentioned in hero and publish sections)

  • Which AI frameworks work with TPMJS?
  • Are there adapters needed?
  • Show code for each framework

• Simplify developer stories code

  • Current code snippet unexplained:

    const agent = new Agent({ tools: await tpmjs.search(...) })
    

  • Add: Where does Agent come from? What's happening here?

• Add README context (completely rewritten with clear explanation)

  • What is TPMJS for?
  • Link to tpmjs.com
  • Explain discovery mechanism

Nice to Have (Post-Launch)

• Add video walkthrough (30-60 seconds)
• Interactive playground link from homepage
• "Compare to alternatives" section
• Case studies with real company names
• Quick links sidebar for docs page
• Status badges for each quality gate

---

Recommended Hero Section Rewrite

Current

TOOL REGISTRY FOR AI AGENTS
Discover, share, and integrate tools that give your agents superpowers
The registry for AI tools

Suggested

MAKE YOUR AI AGENT SMARTER
TPMJS connects your AI agent to 2,500+ npm packages at runtime.
No config files. No manual imports. Just describe what you need.

"Find me a tool that can scrape websites" → Your agent gets web-scraper
"I need to process markdown" → Your agent gets markdown-formatter

Publish your npm package → It's discoverable by every AI agent in 15 minutes.

This version:

• Explains what it DOES (connects agents to npm packages)
• Shows HOW it works (natural language → tool)
• States the VALUE (no config, automatic discovery)
• Gives concrete examples

---

Recommended "What is TPMJS?" Section

Add after hero, before featured tools:

## What is TPMJS?

**The Problem:** AI agents need tools (web scraping, file processing, API calls)
but developers must manually configure each one. As the ecosystem grows,
this becomes unmanageable.

**The Solution:** TPMJS is a registry that automatically discovers npm packages
designed for AI agents. Agents can search for tools by description and load them
at runtime.

**For Tool Builders:** Add `tpmjs` keyword to your package.json.
Your tool appears on tpmjs.com within 15 minutes.

**For Agent Developers:** Use semantic search to find tools:
```javascript
import { searchRegistry } from '@tpmjs/sdk';
const tools = await searchRegistry('send emails and slack messages');
// Returns: email-sender, slack-notifier, ...

One registry. Thousands of tools. Zero configuration.

---

## Final Assessment

### Ready for Launch?
**Not yet.** The core product is solid but messaging fails first-time visitors.

### Estimated Fixes
- Hero rewrite: 30 minutes
- "What is TPMJS?" section: 1 hour
- Category reconciliation: 1 hour
- Hardcoded values: 30 minutes
- README updates: 30 minutes
- NPM_MIRROR cleanup: 15 minutes

**Total: ~4 hours of work**

### After Fixes
The site will be launch-ready. The technical content is excellent - it just needs a better front door.

---

## Appendix: Positive Highlights

Things that are already great and should NOT change:

1. **How It Works page** - Excellent technical depth, clear structure
2. **Publishing guide** - Best-in-class documentation, real examples
3. **Problem section** - Concrete pain points, relatable issues
4. **Spec page** - Clear field reference, good validation info
5. **SDK documentation** - Quick start is excellent
6. **Code examples throughout** - Practical, copy-pasteable
7. **Visual design** - Clean, professional, developer-focused
8. **Quality scoring explanation** - Transparent, well-documented