Enhance README with real examples, logo, badges, and error handling docs

[stevekrenzel]

Summary

• Add centered logo and npm/license/node/TypeScript badges
• Include real LLM explanation output examples throughout documentation
• Document graceful error handling behavior
• Add Node.js engine requirement (>=18) to package.json

Problem

The README lacked visual branding, real-world examples of explanation output,
and clear documentation about error handling behavior. Users reported confusion
about what happens when API calls fail.

Solution

Visual Improvements:

• Added centered logo at top of README
• Added shields.io badges for npm version, downloads, license, Node.js, and TypeScript

Documentation with Real Examples:

• Quickstart now shows actual ranked output and explanation text
• rank(), filter(), and choice() sections all include realistic
  explanation examples showing what LLM reasoning looks like
• Renamed "Include explanations" sections to "With explanations" for consistency

Error Handling Documentation:

• New section clarifying graceful degradation behavior
• Documents that on ANY LLM error (timeout, invalid key, rate limit, etc.),
  Intent returns items in original order rather than throwing
• Specifies behavior for each method: rank returns all, filter keeps all,
  choice returns first candidate

Package Metadata:

• Added engines.node: ">=18" to package.json to match esbuild target

[claude]

Claude finished @stevekrenzel's task —— View job

---

PR Review: Enhance README with real examples, logo, badges, and error handling docs

Review Checklist

• Read and analyze README.md changes
• Review package.json modifications
• Verify error handling documentation accuracy
• Check documentation consistency and clarity
• Provide comprehensive feedback

---

Summary

This is a high-quality documentation PR that significantly improves the README with visual branding, real LLM explanation examples, and error handling documentation. The changes align well with the library's goals of transparency and explainability.

✅ Strengths

1. Visual Improvements: The centered logo and badge layout (README.md:1-13) provides professional branding
2. Real Examples: Including actual LLM explanation output throughout (README.md:63-70, 160-164, 211-214) helps users understand what to expect
3. Error Handling Documentation: The new section (README.md:302-312) clearly explains graceful degradation behavior
4. Package Metadata: Adding engines.node: ">=18" (package.json:26-28) properly documents the Node.js requirement

🔍 Issues Found

1. Syntax Error in Code Example (README.md:193)

Severity: High

{
  id: "haiku-4.5"
  strengths: "Fast and cheap. Good for triage and simple edits.",
},

Issue: Missing comma after "haiku-4.5" on line 193.

Fix: Add comma after the id value:

{
  id: "haiku-4.5",
  strengths: "Fast and cheap. Good for triage and simple edits.",
},

This syntax error would prevent users from copy-pasting the example code.

2. Incorrect Import Statement (README.md:333)

Severity: Medium

import { Intent } from "intent";

Issue: The package name is @with-logic/intent, not intent.

Fix: Update to match the actual package name:

import { Intent } from "@with-logic/intent";

This appears throughout the README correctly (lines 32, 89, 125, 171), but this single instance on line 333 is inconsistent.

3. Documentation Accuracy Issue (README.md:302-312)

Severity: Low

The error handling section states:

• rank() → returns all candidates in original order
• filter() → returns all candidates (nothing filtered out)
• choice() → returns the first candidate

Issue: After reviewing the implementation (intent.ts:316-325, 368-401, 452-458), this is accurate for rank() and filter(), but there's a nuance for choice():

• choice() uses batchProcess with a per-batch fallback that returns batch[0] (intent.ts:457)
• At the top level (intent.ts:473), if an error occurs during the final round, it would throw rather than gracefully return the first candidate

Recommendation: The documentation is mostly accurate for typical batch errors, but consider clarifying that choice() may throw in edge cases (e.g., when all candidates fail in the final selection round after tournament winners).

📋 Minor Observations

4. Consistent Section Naming (README.md:49, 112, 150)

Observation: The PR renamed "Include explanations" to "With explanations" for consistency. This is excellent! All three sections now use "With explanations" (lines 49, 112, 150).

5. Logo File Format

Observation: The logo.png file is a clean, simple design that works well at various sizes. Good choice.

6. Example Output Realism (README.md:63-70, 160-164, 211-214)

Observation: The LLM explanation examples feel authentic and accurately represent the style of output users would see. This significantly improves documentation quality by setting realistic expectations.

🎯 Recommendations

1. Fix the syntax error on line 193 (missing comma) - this blocks users from using the code
2. Fix the import statement on line 333 - ensure consistency across examples
3. Consider clarifying choice() error behavior - optional but would improve accuracy

✅ What Works Well

• Error handling documentation: Clearly explains Intent's graceful degradation philosophy
• Real examples throughout: Users can see actual LLM reasoning output
• Visual improvements: Professional appearance with badges and logo
• Consistent terminology: "With explanations" naming is now uniform
• Package metadata: engines.node properly documents requirements

Final Assessment

This PR significantly improves the README quality and user experience. The two issues found (syntax error and import statement) are straightforward fixes. Once corrected, this will be an excellent documentation update.

The error handling documentation is particularly valuable, as it addresses user confusion about failure modes and reinforces Intent's design philosophy of graceful degradation.

---