@portel/photon 1.6.1 → 1.8.0

package/README.md

@@ -14,7 +14,9 @@ A framework, runtime, and ecosystem. Batteries included.
 [![Node](https://img.shields.io/badge/node-%3E%3D18-43853d.svg)](https://nodejs.org)
 [![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed.svg)](https://modelcontextprotocol.io)
 
-[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Beam UI](#beam) · [Marketplace](#marketplace) · [Docs](#documentation)
+[Quick Start](#quick-start) · [Why Photon](#why-did-we-build-this) · [Beam UI](#beam) · [How It Works](#how-it-works) · [Docs](#documentation)
+
+[![Watch: Why Photon? (2 min)](https://img.youtube.com/vi/FI0M8s6ZKv4/maxresdefault.jpg)](https://www.youtube.com/watch?v=FI0M8s6ZKv4)
 
 </div>
 
@@ -22,7 +24,7 @@ A framework, runtime, and ecosystem. Batteries included.
 
 ## What Is This Thing?
 
-So, here is the situation. You write a single TypeScript file. Just one. And somehow, through some dark magic I don’t fully understand either, you get three things at once:
+So, here is the situation. You write a single TypeScript file. Just one. And somehow, through some dark magic I don't fully understand either, you get three things at once:
 
 1.  **An MCP server** (so Claude or Cursor can use your tools).
 2.  **A CLI tool** (so you can run it from the terminal like a normal human).
@@ -36,20 +38,6 @@ It looks like this:
 
 You just write the logic. Photon deals with the protocols, schemas, and the boring stuff that usually makes you question your life choices.
 
-### The Basics
-
-If you are just skimming, here is what you need to know:
-
-| Concept | What it is | Learn more |
-|---------|-----------|------------|
-| **MCP** | A way for AI to use your tools. It’s a standard. | [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) |
-| **Photon file** | A `.photon.ts` file. You define tools as methods in a class. | [Guide](./GUIDE.md) |
-| **Beam** | A web dashboard. It shows your tools as forms. | [Beam UI](#beam) |
-| **Marketplace** | A way to get other people’s photons. | [Marketplace](#marketplace) |
-| **Daemon** | A background thing that handles messages and jobs. | [Daemon Pub/Sub](./DAEMON-PUBSUB.md) |
-| **Tags** | JSDoc comments that tell Photon what to do. | [Tag Reference](./DOCBLOCK-TAGS.md) |
-| **Custom UI** | When the auto-generated forms aren't enough. | [Custom UI Guide](./CUSTOM-UI.md) |
-
 ### Who Is This For?
 
 *   **Developers** who want to give AI access to their database but are too lazy to write a full server.
@@ -60,6 +48,18 @@ You don't need to know what "MCP" actually stands for. If you can write a TypeSc
 
 ---
 
+## Why did we build this?
+
+Three reasons, if you want the short version. ([Read the longer version](./WHY-PHOTON.md))
+
+**MCP is personal.** The best MCP is the one built for exactly one use case. Yours. Your team's. Your company's. When you stop building for everyone, the code gets absurdly simple. One file. Twelve lines. Not twelve hundred.
+
+**Solve once, run forever.** If an LLM figured out your workflow the first time, why ask it to re-derive the same answer from scratch every time? Photon lets you keep the answer. No middleman, no tokens, no latency.
+
+**Same door, every key.** AI calls it through MCP. You call it through CLI. You open it in Beam. Same methods, same data, same result. And half the time, you don't need AI at all. You just need the data.
+
+---
+
 ## Quick Start
 
 If you are the type who likes to just run commands and see what happens:
@@ -81,11 +81,69 @@ npx @portel/photon
 
 ---
 
+## Beam
+
+Beam is the dashboard. It's where you go to poke your tools and see if they work before you let an AI loose on them.
+
+Run `photon`. That's it.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="100%">
+</div>
+
+---
+
+## Connecting to AI
+
+If you want to use this with Claude or Cursor, you need the config.
+
+```bash
+photon info weather --mcp
+```
+
+It spits out some JSON:
+
+```json
+{
+  "mcpServers": {
+    "weather": {
+      "command": "photon",
+      "args": ["mcp", "weather"]
+    }
+  }
+}
+```
+
+Copy that. Paste it into your AI client's config file. Done.
+
+Works with [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and any [MCP-compatible client](https://modelcontextprotocol.io).
+
+---
+
+## Marketplace
+
+We also have a marketplace. 35 photons and counting.
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="100%">
+</div>
+
+```bash
+photon search postgres
+photon add postgres
+```
+
+Browse the full catalog and documentation in the [official photons repository](https://github.com/portel-dev/photons).
+
+You can also make a private marketplace for your team, so internal tools stay off the public internet.
+
+---
+
 ## How It Works
 
 A photon is just a TypeScript class. The **public methods become tools**. Photon reads your code, looks at the types, reads your comments, and then generates everything else.
 
-I’ll show you.
+I'll show you.
 
 ### Step 1: The Bare Minimum
 
@@ -107,7 +165,7 @@ export default class Weather {
 *   `photon` (The web UI)
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-1.png" alt="Step 1 — Bare method in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-1.png" alt="Step 1 — Bare method in Beam" width="100%">
 </div>
 
 ### Step 2: Adding Descriptions
@@ -134,7 +192,7 @@ export default class Weather {
 **What happens:** Now the UI has helpful text. Also, the AI client reads this to understand what the tool does.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-2.png" alt="Step 2 — JSDoc descriptions in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-2.png" alt="Step 2 — JSDoc descriptions in Beam" width="100%">
 </div>
 
 ### Step 3: Configuration (The clever bit)
@@ -160,7 +218,7 @@ export default class Weather {
 **What happens:** Beam creates a settings panel. `apiKey` becomes a password field. It also maps to environment variables like `WEATHER_API_KEY`. It just works.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-3.png" alt="Step 3 — Configuration panel in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-3.png" alt="Step 3 — Configuration panel in Beam" width="100%">
 </div>
 
 ### Step 4: Validation (Stop bad inputs)
@@ -220,10 +278,10 @@ VideoProcessor requires the following CLI tools to be installed:
   - ffmpeg: Install from https://ffmpeg.org/download.html
 ```
 
-> See the full [Tag Reference](./DOCBLOCK-TAGS.md) for all available tags. There are 30+ covering validation, UI hints, scheduling, webhooks, and more.
+> See the full [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) for all available tags. There are 30+ covering validation, UI hints, scheduling, webhooks, and more.
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-4.png" alt="Step 4 — Validation and formatting in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-4.png" alt="Step 4 — Validation and formatting in Beam" width="100%">
 </div>
 
 ### Step 5: Custom UI (When you want to be fancy)
@@ -264,10 +322,10 @@ export default class Weather {
 
 **What changes in Beam:** Instead of the auto-generated table, results render inside your custom HTML (a weather dashboard with icons, charts, or any visualization you build). The `window.photon` API bridges your UI to the tool system.
 
-> Custom UIs follow the [MCP Apps Extension (SEP-1865)](https://github.com/nicolo-ribaudo/modelcontextprotocol/blob/nicolo/sep-1865/docs/specification/draft/extensions/apps.mdx) standard and work across compatible hosts. See the [Custom UI Guide](./CUSTOM-UI.md).
+> Custom UIs follow the [MCP Apps Extension (SEP-1865)](https://github.com/nicolo-ribaudo/modelcontextprotocol/blob/nicolo/sep-1865/docs/specification/draft/extensions/apps.mdx) standard and work across compatible hosts. See the [Custom UI Guide](./docs/guides/CUSTOM-UI.md).
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-5.png" alt="Step 5 — Custom UI result in Beam" width="600">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-5.png" alt="Step 5 — Custom UI result in Beam" width="100%">
 </div>
 
 ### In Summary
@@ -281,129 +339,24 @@ export default class Weather {
 | **5. Custom UI** | HTML | A custom app |
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png" alt="Photon Ecosystem" width="600">
-</div>
-
----
-
-## Beam
-
-Beam is the dashboard. It’s where you go to poke your tools and see if they work before you let an AI loose on them.
-
-Run `photon`. That’s it.
-
-<div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="700">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png" alt="Photon Ecosystem" width="100%">
 </div>
 
 ---
 
-## Connecting to AI
-
-If you want to use this with Claude or Cursor, you need the config.
-
-```bash
-photon info weather --mcp
-```
-
-It spits out some JSON:
+## The Basics
 
-```json
-{
-  "mcpServers": {
-    "weather": {
-      "command": "photon",
-      "args": ["mcp", "weather"]
-    }
-  }
-}
-```
-
-Copy that. Paste it into your AI client’s config file. Done.
-
-Works with [Claude Desktop](https://claude.ai/download), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.com), and any [MCP-compatible client](https://modelcontextprotocol.io).
-
----
-
-## Why did we build this?
-
-Writing an MCP server usually involves 4 to 6 files and about 150 lines of code before you even start writing the thing you actually wanted to write.
-
-With Photon, it’s one file.
-
-| | Traditional MCP | Photon |
-|---|---|---|
-| **Files** | 4-6 (server, transport, schemas, types, config) | 1 |
-| **Boilerplate** | 150+ lines | 0 |
-| **Dependencies** | Manual `npm install` | Automatic |
-| **Schema** | Hand-written JSON Schema | Generated from TS types |
-| **Config** | Manual env var parsing | Automatic from Constructor |
-
-It is unnecessarily difficult to do it the old way. So we stopped doing it.
-
----
-
-## Marketplace
-
-We also have a marketplace. 31 photons and counting.
-
-<div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="700">
-</div>
-
-```bash
-photon search postgres
-photon add postgres
-```
-
-### Available Photons
-
-**Productivity**
-
-| Photon | What it does | Tools |
-|--------|-------------|-------|
-| 📌 **kanban** | Multi-tenant task boards for humans and AI | 33 |
-| 📬 **git-box** | Mailbox-style Git interface, manage repos like an inbox | 58 |
-| 📬 **form-inbox** | Webhook-powered form submission collector | 12 |
-| 📅 **google-calendar** | Calendar integration via OAuth | 9 |
-| 🎫 **jira** | Project management and issue tracking | 10 |
-| 💬 **slack** | Send messages and manage Slack workspaces | 7 |
-| 📧 **email** | Send and receive via SMTP/IMAP | 8 |
-
-**Infrastructure**
-
-| Photon | What it does | Tools |
-|--------|-------------|-------|
-| 📁 **filesystem** | Safe, cross-platform file operations | 13 |
-| 🔀 **git** | Local git repository operations | 11 |
-| 🐙 **github-issues** | Manage GitHub issues and comments | 7 |
-| 🐳 **docker** | Container and image management | 10 |
-| ☁️ **aws-s3** | S3 object storage operations | 11 |
-| 🌐 **web** | DuckDuckGo search + Readability extraction | 2 |
-
-**Databases**
-
-| Photon | What it does | Tools |
-|--------|-------------|-------|
-| 🐘 **postgres** | PostgreSQL queries and schema ops | 7 |
-| 🗄️ **sqlite** | SQLite database operations | 9 |
-| 🍃 **mongodb** | MongoDB document CRUD and aggregation | 13 |
-| ⚡ **redis** | Key-value store, lists, sets, pub/sub | 18 |
-
-**Utilities and Demos**
-
-| Photon | What it does | Tools |
-|--------|-------------|-------|
-| 🕐 **time** | Timezone conversion and queries | 3 |
-| 🧮 **math** | Expression evaluator (trig, stats, etc.) | 1 |
-| 📊 **code-diagram** | Generate Mermaid diagrams from code | 3 |
-| 🔴 **connect-four** | Play against AI with distributed locks | 8 |
-| 🍳 **kitchen-sink** | Every runtime feature in one file | 25 |
-| 📋 **dashboard** | MCP Apps UI demo | 6 |
-| 📺 **team-dashboard** | TV/monitor-optimized team display | 20 |
-| 🎭 **mcp-orchestrator** | Combine multiple MCPs into workflows | 10 |
+If you are just skimming, here is what you need to know:
 
-You can also make a private marketplace for your team, so internal tools stay off the public internet.
+| Concept | What it is | Learn more |
+|---------|-----------|------------|
+| **MCP** | A way for AI to use your tools. It's a standard. | [modelcontextprotocol.io](https://modelcontextprotocol.io/introduction) |
+| **Photon file** | A `.photon.ts` file. You define tools as methods in a class. | [Guide](./docs/GUIDE.md) |
+| **Beam** | A web dashboard. It shows your tools as forms. | [Beam UI](#beam) |
+| **Marketplace** | A way to get other people's photons. | [Marketplace](#marketplace) |
+| **Daemon** | A background thing that handles messages and jobs. | [Daemon Pub/Sub](./docs/core/DAEMON-PUBSUB.md) |
+| **Tags** | JSDoc comments that tell Photon what to do. | [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) |
+| **Custom UI** | When the auto-generated forms aren't enough. | [Custom UI Guide](./docs/guides/CUSTOM-UI.md) |
 
 ---
 
@@ -424,7 +377,7 @@ photon maker new <name>           # Scaffold a new photon
 # Manage
 photon info                       # List all photons
 photon info <name> --mcp          # Get MCP client config (paste into Claude/Cursor)
-photon validate <name>            # Check for errors
+photon maker validate <name>      # Check for errors
 
 # Marketplace
 photon add <name>                 # Install photon
@@ -433,7 +386,6 @@ photon upgrade                    # Upgrade all
 
 # Ops
 photon doctor                     # Diagnose environment
-photon audit                      # Security audit
 photon test                       # Run tests
 ```
 
@@ -459,7 +411,7 @@ Tags are JSDoc annotations that control how Photon processes your code. Here are
 | `@mcp` | Class | Inject another MCP server as a dependency |
 | `@icon` | Class/Method | Set emoji icon |
 
-> This is a subset. See the full [Tag Reference](./DOCBLOCK-TAGS.md) for all 30+ tags with examples.
+> This is a subset. See the full [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) for all 30+ tags with examples.
 
 ---
 
@@ -469,33 +421,33 @@ Tags are JSDoc annotations that control how Photon processes your code. Here are
 
 | Guide | |
 |-------|-|
-| [Getting Started](./GUIDE.md) | Create your first photon, step by step |
-| [Tag Reference](./DOCBLOCK-TAGS.md) | Complete JSDoc tag reference with examples |
-| [Naming Conventions](./NAMING-CONVENTIONS.md) | How to name methods so they read naturally as CLI commands |
-| [Troubleshooting](./TROUBLESHOOTING.md) | Common issues and solutions |
+| [Getting Started](./docs/GUIDE.md) | Create your first photon, step by step |
+| [Tag Reference](./docs/reference/DOCBLOCK-TAGS.md) | Complete JSDoc tag reference with examples |
+| [Naming Conventions](./docs/guides/NAMING-CONVENTIONS.md) | How to name methods so they read naturally as CLI commands |
+| [Troubleshooting](./docs/TROUBLESHOOTING.md) | Common issues and solutions |
 
 **Build more:**
 
 | Topic | |
 |-------|-|
-| [Custom UI](./CUSTOM-UI.md) | Build rich interactive interfaces with `window.photon` |
-| [OAuth](./AUTH.md) | Built-in OAuth 2.1 with Google, GitHub, Microsoft |
-| [Daemon Pub/Sub](./DAEMON-PUBSUB.md) | Real-time cross-process messaging |
-| [Webhooks](./WEBHOOKS.md) | HTTP endpoints for external services |
-| [Locks](./LOCKS.md) | Distributed locks for exclusive access |
-| [Advanced Patterns](./ADVANCED.md) | Lifecycle hooks, dependency injection, interactive workflows |
-| [Deployment](./DEPLOYMENT.md) | Docker, Cloudflare Workers, AWS Lambda, Systemd |
+| [Custom UI](./docs/guides/CUSTOM-UI.md) | Build rich interactive interfaces with `window.photon` |
+| [OAuth](./docs/guides/AUTH.md) | Built-in OAuth 2.1 with Google, GitHub, Microsoft |
+| [Daemon Pub/Sub](./docs/core/DAEMON-PUBSUB.md) | Real-time cross-process messaging |
+| [Webhooks](./docs/reference/WEBHOOKS.md) | HTTP endpoints for external services |
+| [Locks](./docs/reference/LOCKS.md) | Distributed locks for exclusive access |
+| [Advanced Patterns](./docs/guides/ADVANCED.md) | Lifecycle hooks, dependency injection, interactive workflows |
+| [Deployment](./docs/guides/DEPLOYMENT.md) | Docker, Cloudflare Workers, AWS Lambda, Systemd |
 
 **Operate:**
 
 | Topic | |
 |-------|-|
 | [Security](./SECURITY.md) | Best practices and audit checklist |
-| [Marketplace Publishing](./MARKETPLACE-PUBLISHING.md) | Create and share team marketplaces |
-| [Best Practices](./PHOTON_BEST_PRACTICES.md) | Patterns for production photons |
-| [Comparison](./COMPARISON.md) | Benchmarks vs official MCP implementations |
+| [Marketplace Publishing](./docs/guides/MARKETPLACE-PUBLISHING.md) | Create and share team marketplaces |
+| [Best Practices](./docs/guides/BEST-PRACTICES.md) | Patterns for production photons |
+| [Comparison](./docs/COMPARISON.md) | Benchmarks vs official MCP implementations |
 
-**Reference:** [Architecture](./ARCHITECTURE.md) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
+**Reference:** [Architecture](./docs/core/ARCHITECTURE.md) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
 
 ---
 
@@ -516,4 +468,3 @@ If you find a bug, or if my code offends you, feel free to open an issue or a PR
 Made by [Portel](https://github.com/portel-dev)
 
 </div>
-

package/dist/auto-ui/beam.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"beam.d.ts","sourceRoot":"","sources":["../../src/auto-ui/beam.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA0xBH,wBAAsB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAs8ElF;AAkYD;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAsB9C"}
+{"version":3,"file":"beam.d.ts","sourceRoot":"","sources":["../../src/auto-ui/beam.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2xBH,wBAAsB,SAAS,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwkFlF;AAiYD;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAsB9C"}