@portel/photon 1.5.1 → 1.6.0

package/README.md

@@ -3,9 +3,9 @@
 
 <img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-logo.png" alt="Photon" width="500">
 
-**Build MCP servers from single TypeScript files.**
+**Simplify the creation of CLI tools, MCP servers, and web applications.**
 
-Write business logic. Get an MCP server, CLI, and web UI — automatically.
+A framework, runtime, and ecosystem. Batteries included.
 
 [![npm version](https://img.shields.io/npm/v/@portel/photon?color=cb3837&label=npm)](https://www.npmjs.com/package/@portel/photon)
 [![npm downloads](https://img.shields.io/npm/dm/@portel/photon?color=cb3837)](https://www.npmjs.com/package/@portel/photon)
@@ -14,484 +14,506 @@ Write business logic. Get an MCP server, CLI, and web UI — automatically.
 [![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) · [Features](#features) · [Beam UI](#beam) · [Marketplace](#marketplace) · [Docs](#documentation)
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Beam UI](#beam) · [Marketplace](#marketplace) · [Docs](#documentation)
 
 </div>
 
 ---
 
-## Quick Start
+## What Is This Thing?
 
-```bash
-npm install -g @portel/photon
-photon init my-tool
-photon                        # Open Beam UI in your browser
-```
+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:
 
-Create `analytics.photon.ts` — no boilerplate, no config files:
+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).
+3.  **A web application** (a visual dashboard called "Beam" that makes forms for you).
 
-```typescript
-/**
- * Analytics - Query company analytics
- * @dependencies pg@^8.11.0
- */
-import { Client } from 'pg';
+It looks like this:
 
-export default class Analytics {
-  private db: Client;
-
-  constructor(private host: string, private database: string, private password: string) {}
-
-  async onInitialize() {
-    this.db = new Client({ host: this.host, database: this.database, password: this.password });
-    await this.db.connect();
-  }
-
-  /** Get revenue by date range */
-  async revenue(params: { startDate: string; endDate: string }) {
-    return (await this.db.query(
-      'SELECT date, SUM(amount) FROM orders WHERE date BETWEEN $1 AND $2 GROUP BY date',
-      [params.startDate, params.endDate]
-    )).rows;
-  }
-}
 ```
-
-Same file, three interfaces:
-
-```bash
-photon mcp analytics              # MCP server for Claude, Cursor, Zed
-photon cli analytics revenue      # CLI for humans
-photon                            # Beam web UI
+  analytics.photon.ts  →  MCP Server  |  CLI Tool  |  Web UI
 ```
 
-<div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-concept.jpg" alt="Photon — One file, three interfaces" width="700">
-</div>
+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
 
-## Beam
+If you are just skimming, here is what you need to know:
 
-Beam is the human interface to MCP — browse, configure, test, and execute tools visually.
+| 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) |
 
-<div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="700">
-</div>
+### Who Is This For?
 
-<br>
+*   **Developers** who want to give AI access to their database but are too lazy to write a full server.
+*   **Teams** who want to share tools without emailing zip files.
+*   **Anyone** who wants a CLI and a web UI without writing the boilerplate.
 
-<table>
-<tr>
-<td width="50%">
+You don't need to know what "MCP" actually stands for. If you can write a TypeScript class, you are qualified.
 
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-tool-form.png" alt="Auto-generated forms" width="100%">
-
-**Auto-generated forms** — Built from your TypeScript types. Required fields marked, types validated.
-
-</td>
-<td width="50%">
+---
 
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-execute.png" alt="Tool execution" width="100%">
+## Quick Start
 
-**Execute and verify** — Test every tool before deploying to AI. See exactly what AI will see.
+If you are the type who likes to just run commands and see what happens:
 
-</td>
-</tr>
-</table>
+```bash
+npm install -g @portel/photon
+photon maker new my-tool       # Makes a new photon
+photon                         # Opens the Beam UI
+```
 
-Constructor parameters become form fields, environment variables, and CLI flags automatically:
+Or if you don't want to install anything (I get it):
 
-```typescript
-constructor(
-  private host: string,      // → ANALYTICS_HOST env var → text field
-  private database: string,  // → ANALYTICS_DATABASE    → text field
-  private password: string   // → ANALYTICS_PASSWORD    → password field
-) {}
+```bash
+npx @portel/photon maker new my-tool
+npx @portel/photon
 ```
 
----
+> **Note:** You need [Node.js 18+](https://nodejs.org). Also, TypeScript helps, but Photon handles the compiling, so you don't have to fight with `tsconfig.json`.
 
-## Features
-
-### Convention Over Configuration
+---
 
-| What You Write | What Photon Does |
-|----------------|-----------------|
-| `analytics.photon.ts` | MCP server name: `analytics` |
-| `async revenue()` | MCP tool: `revenue` |
-| TypeScript types | JSON Schema (auto-generated) |
-| JSDoc comments | Tool descriptions |
-| Constructor params | Env vars + config UI |
-| `@dependencies pg@^8.11.0` | Auto-install on first run |
+## How It Works
 
-### Full Platform
+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.
 
-- **Hot Reload** — `--dev` flag watches for changes and reloads instantly
-- **Daemon Protocol** — Pub/sub channels, distributed locks, scheduled jobs, webhooks
-- **Custom UIs** — Build rich interfaces with `window.photon` API
-- **OAuth** — Built-in OAuth 2.1 with Google, GitHub, Microsoft providers
-- **MCP Composition** — Call other MCP servers with `@mcp` tag
-- **Deployment** — Docker, Cloudflare Workers, AWS Lambda, Systemd
+I’ll show you.
 
-### Why Single File?
+### Step 1: The Bare Minimum
 
-Traditional MCPs scatter logic across 4-6 files. Photon keeps everything in one:
+Here is a class with one method. This is a valid photon.
 
-| | Traditional MCP | Photon |
-|---|---|---|
-| **Files** | 4-6 (server, transport, schemas, types, config) | 1 |
-| **Boilerplate** | 150+ lines before business logic | 0 |
-| **Security audit** | Hours across multiple files | Minutes, one file |
-| **Fork and customize** | Build config, dependency management | Copy, edit, run |
-| **AI context** | Scattered, multi-file coordination | Complete in one read |
+```typescript
+export default class Weather {
+  async forecast(params: { city: string }) {
+    return `Weather for ${params.city}: Sunny, 72°F`;
+  }
+}
+```
 
----
+**What happens:** Beam sees this and makes a form with a text box labeled "city". You click a button, and it runs.
 
-## Marketplace
+**What you get:**
+*   `photon mcp weather` (The server for Claude)
+*   `photon cli weather forecast --city Paris` (The command line tool)
+*   `photon` (The web UI)
 
 <div align="center">
-<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="700">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/readme-step-1.png" alt="Step 1 — Bare method in Beam" width="600">
 </div>
 
-<br>
+### Step 2: Adding Descriptions
 
-Install production-ready photons or create team marketplaces:
+If you add JSDoc comments, they show up as descriptions.
 
-```bash
-photon search postgres            # Find photons
-photon add postgres               # Install
-photon upgrade                    # Keep current
+```typescript
+/**
+ * Weather - Check weather forecasts worldwide
+ *
+ * Provides current conditions.
+ */
+export default class Weather {
+  /**
+   * Get the weather forecast
+   * @param city City name (e.g., "London")
+   */
+  async forecast(params: { city: string }) {
+    return `Weather for ${params.city}: Sunny, 72°F`;
+  }
+}
 ```
 
-**Available:** PostgreSQL, MongoDB, Redis, SQLite, AWS S3, Docker, Filesystem, Git, GitHub, Email, Slack, Google Calendar, Jira, and more.
+**What happens:** Now the UI has helpful text. Also, the AI client reads this to understand what the tool does.
 
-```bash
-# Create a team marketplace
-photon sync marketplace --claude-code
-git push origin main
-# Team members: photon marketplace add company/photons
-```
+<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">
+</div>
 
----
+### Step 3: Configuration (The clever bit)
 
-## Commands
+If you need an API key, put it in the constructor.
 
-```bash
-# Run
-photon                            # Open Beam UI
-photon mcp <name>                 # MCP server
-photon mcp <name> --dev           # MCP server with hot reload
-photon cli <name> [method]        # CLI interface
+```typescript
+export default class Weather {
+  constructor(
+    private apiKey: string,
+    private units: string = 'metric'
+  ) {}
+
+  async forecast(params: { city: string }) {
+    const res = await fetch(
+      `https://api.openweathermap.org/data/2.5/weather?q=${params.city}&appid=${this.apiKey}&units=${this.units}`
+    );
+    return await res.json();
+  }
+}
+```
 
-# Manage
-photon init <name>                # Create new photon
-photon info                       # List all photons
-photon info <name> --mcp          # Get MCP client config
-photon validate <name>            # Check for errors
+**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.
 
-# Marketplace
-photon add <name>                 # Install photon
-photon search <query>             # Search
-photon upgrade                    # Upgrade all
+<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">
+</div>
 
-# Ops
-photon doctor                     # Diagnose environment
-photon audit                      # Security audit
-photon test                       # Run tests
-photon deploy                     # Deploy to production
-```
+### Step 4: Validation (Stop bad inputs)
 
----
+You can add tags to valid inputs.
 
-## Documentation
+```typescript
+/**
+ * Weather - Check weather forecasts worldwide
+ * @dependencies node-fetch@^3.0.0
+ */
+export default class Weather {
+  constructor(
+    private apiKey: string,
+    private units: string = 'metric'
+  ) {}
+
+  /**
+   * Get the weather forecast for a city
+   * @param city City name {@example London} {@pattern ^[a-zA-Z\s]+$}
+   * @param days Number of days {@min 1} {@max 7}
+   * @format table
+   */
+  async forecast(params: { city: string; days?: number }) {
+    // fetch and return forecast data...
+  }
+}
+```
 
-**Start here:**
+**What happens:**
+*   The `city` input validates the regex.
+*   The `days` input becomes a number spinner (1-7).
+*   The result is formatted as a table.
+*   `@dependencies` makes Photon install `node-fetch` automatically. You don't even run `npm install`.
 
-| Guide | |
-|-------|-|
-| [Getting Started](https://github.com/portel-dev/photon/blob/main/GUIDE.md) | Create your first photon, step by step |
-| [Advanced](https://github.com/portel-dev/photon/blob/main/ADVANCED.md) | Lifecycle hooks, performance, testing |
-| [Docblock Tags](https://github.com/portel-dev/photon/blob/main/DOCBLOCK-TAGS.md) | Complete JSDoc tag reference |
-| [Troubleshooting](https://github.com/portel-dev/photon/blob/main/TROUBLESHOOTING.md) | Common issues and solutions |
+#### System CLI Dependencies
 
-**Deep dives:**
+If your photon wraps a command-line tool (e.g. `ffmpeg`, `git`, `docker`), declare it with `@cli`. Photon checks for the tool at load time and refuses to load if it's missing.
 
-| Topic | |
-|-------|-|
-| [Custom UI](https://github.com/portel-dev/photon/blob/main/CUSTOM-UI.md) | Build rich interactive interfaces |
-| [Auth](https://github.com/portel-dev/photon/blob/main/AUTH.md) | OAuth 2.1 with built-in providers |
-| [Daemon Pub/Sub](https://github.com/portel-dev/photon/blob/main/DAEMON-PUBSUB.md) | Real-time cross-process messaging |
-| [Webhooks](https://github.com/portel-dev/photon/blob/main/WEBHOOKS.md) | HTTP endpoints for external services |
-| [Deployment](https://github.com/portel-dev/photon/blob/main/DEPLOYMENT.md) | Docker, Lambda, Workers, Systemd |
-| [Security](https://github.com/portel-dev/photon/blob/main/SECURITY.md) | Best practices and audit checklist |
-| [Marketplace Publishing](https://github.com/portel-dev/photon/blob/main/MARKETPLACE-PUBLISHING.md) | Create and share marketplaces |
+```typescript
+/**
+ * Video processor
+ * @cli ffmpeg - https://ffmpeg.org/download.html
+ * @cli imagemagick - https://imagemagick.org/script/download.php
+ */
+export default class VideoProcessor {
+  async convert({ input, format }: { input: string; format: string }) {
+    // ffmpeg is guaranteed to exist if this method runs
+  }
+}
+```
 
-**Reference:** [Architecture](https://github.com/portel-dev/photon/blob/main/ARCHITECTURE.md) · [Best Practices](https://github.com/portel-dev/photon/blob/main/PHOTON_BEST_PRACTICES.md) · [Naming Conventions](https://github.com/portel-dev/photon/blob/main/NAMING-CONVENTIONS.md) · [Comparison](https://github.com/portel-dev/photon/blob/main/COMPARISON.md) · [Changelog](https://github.com/portel-dev/photon/blob/main/CHANGELOG.md)
+If `ffmpeg` is not installed, the photon won't load and the user sees:
 
----
+```
+VideoProcessor requires the following CLI tools to be installed:
+  - ffmpeg: Install from https://ffmpeg.org/download.html
+```
 
-## Contributing
+> See the full [Tag Reference](./DOCBLOCK-TAGS.md) for all available tags. There are 30+ covering validation, UI hints, scheduling, webhooks, and more.
 
-See [CONTRIBUTING.md](https://github.com/portel-dev/photon/blob/main/CONTRIBUTING.md) and [ARCHITECTURE.md](https://github.com/portel-dev/photon/blob/main/ARCHITECTURE.md).
+<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">
+</div>
 
-## License
+### Step 5: Custom UI (When you want to be fancy)
 
-[MIT](https://github.com/portel-dev/photon/blob/main/LICENSE)
+If the auto-generated form is too boring, you can write your own HTML.
 
----
+```typescript
+/**
+ * Weather - Check weather forecasts worldwide
+ * @dependencies node-fetch@^3.0.0
+ * @ui dashboard ./ui/weather.html
+ */
+export default class Weather {
+  constructor(private apiKey: string, private units: string = 'metric') {}
+
+  /**
+   * Get the weather forecast for a city
+   * @ui dashboard
+   * @format table
+   */
+  async forecast(params: { city: string; days?: number }) {
+    // returns structured weather data
+  }
+}
+```
 
-<div align="center">
+```html
+<!-- ui/weather.html -->
+<div id="weather-app">
+  <div id="forecast"></div>
+</div>
+<script>
+  window.photon.onResult(data => {
+    document.getElementById('forecast').innerHTML = renderWeather(data);
+  });
+</script>
+```
 
-*Singular focus. Precise target.*
+**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.
 
-Made by [Portel](https://github.com/portel-dev)
+> 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).
 
+<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">
 </div>
 
-<!-- PHOTON_MARKETPLACE_START -->
-# photon
+### In Summary
 
-> **Singular focus. Precise target.**
+| Step | You write | Photon generates |
+|------|---------|-----------------|
+| **1. Methods** | A function | Tools, CLI commands, Forms |
+| **2. JSDoc** | Comments | Descriptions for AI and Humans |
+| **3. Constructor** | Arguments | Config UI, Env vars |
+| **4. Tags** | `@tags` | Validation, Installers, Formatting |
+| **5. Custom UI** | HTML | A custom app |
 
-**Photons** are single-file TypeScript MCP servers that supercharge AI assistants with focused capabilities. Each photon delivers ONE thing exceptionally well - from filesystem operations to cloud integrations.
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png" alt="Photon Ecosystem" width="600">
+</div>
 
-Built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), photons are:
-- 📦 **One-command install** via [Photon CLI](https://github.com/portel-dev/photon)
-- 🎯 **Laser-focused** on singular capabilities
-- ⚡ **Zero-config** with auto-dependency management
-- 🔌 **Universal** - works with Claude Desktop, Claude Code, and any MCP client
+---
 
-## 📦 Available Photons
+## Beam
 
-| Photon | Focus | Tools | Features |
-|--------|-------|-------|----------|
-| [**Code Diagram**](code-diagram.md) | Generate Mermaid diagrams from TypeScript/JavaScript code | 3 | 🔌📦 |
-| [**Truth Serum**](serum.md) | Forces unfiltered honesty, no hedging or diplomacy @description Powerful prompt serums that force specific cognitive behaviors @icon 💉 /
-export default class Serum {
-  / | 10 | - |
-| [**Test Ui**](test-ui.md) | Test Custom UI | 1 | 🎨 |
+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.
 
-**Total:** 3 photons ready to use
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="700">
+</div>
 
 ---
 
-## 🚀 Quick Start
+## Connecting to AI
 
-### 1. Install Photon
+If you want to use this with Claude or Cursor, you need the config.
 
 ```bash
-npm install -g @portel/photon
+photon info weather --mcp
 ```
 
-### 2. Add Any Photon
+It spits out some JSON:
 
-```bash
-photon add filesystem
-photon add git
-photon add aws-s3
-```
-
-### 3. Use It
-
-```bash
-# Run as MCP server
-photon mcp filesystem
-
-# Get config for your MCP client
-photon get filesystem --mcp
-```
-
-Output (paste directly into your MCP client config):
 ```json
 {
   "mcpServers": {
-    "filesystem": {
+    "weather": {
       "command": "photon",
-      "args": ["mcp", "filesystem"]
+      "args": ["mcp", "weather"]
     }
   }
 }
 ```
 
-Add the output to your MCP client's configuration. **Consult your client's documentation** for setup instructions.
+Copy that. Paste it into your AI client’s config file. Done.
 
-**That's it!** Your AI assistant now has 3 focused tools at its fingertips.
+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).
 
 ---
 
-## 🎨 Claude Code Integration
+## Why did we build this?
 
-This marketplace is also available as a **Claude Code plugin**, enabling seamless installation of individual photons directly from Claude Code's plugin manager.
+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.
 
-### Install as Claude Code Plugin
+With Photon, it’s one file.
 
-```bash
-# In Claude Code, run:
-/plugin marketplace add portel-dev/photons
-```
+| | 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 |
 
-Once added, you can install individual photons:
+It is unnecessarily difficult to do it the old way. So we stopped doing it.
 
-```bash
-# Install specific photons you need
-/plugin install filesystem@photons-marketplace
-/plugin install git@photons-marketplace
-/plugin install knowledge-graph@photons-marketplace
-```
-
-### Benefits of Claude Code Plugin
+---
 
-- **🎯 Granular Installation**: Install only the photons you need
-- **🔄 Auto-Updates**: Plugin stays synced with marketplace
-- **⚡ Zero Config**: Photon CLI auto-installs on first use
-- **🛡️ Secure**: No credentials shared with AI (interactive setup available)
-- **📦 Individual MCPs**: Each photon is a separate installable plugin
+## Marketplace
 
-### How This Plugin Is Built
+We also have a marketplace. 31 photons and counting.
 
-This marketplace doubles as a Claude Code plugin through automatic generation:
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="700">
+</div>
 
 ```bash
-# Generate marketplace AND Claude Code plugin files
-photon maker sync --claude-code
+photon search postgres
+photon add postgres
 ```
 
-This single command:
-1. Scans all `.photon.ts` files
-2. Generates `.marketplace/photons.json` manifest
-3. Creates `.claude-plugin/marketplace.json` for Claude Code
-4. Generates documentation for each photon
-5. Creates auto-install hooks for seamless setup
-
-**Result**: One source of truth, two distribution channels (Photon CLI + Claude Code).
+### 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 |
+
+You can also make a private marketplace for your team, so internal tools stay off the public internet.
 
 ---
 
-## ⚛️ What Are Photons?
+## Commands
 
-**Photons** are laser-focused modules - each does ONE thing exceptionally well:
-- 📁 **Filesystem** - File operations
-- 🐙 **Git** - Repository management
-- ☁️ **AWS S3** - Cloud storage
-- 📅 **Google Calendar** - Calendar integration
-- 🕐 **Time** - Timezone operations
-- ... and more
+A few commands you might use:
 
-Each photon delivers **singular focus** to a **precise target**.
+```bash
+# Run
+photon                            # Open Beam UI
+photon mcp <name>                 # Run as MCP server
+photon mcp <name> --dev           # MCP server with hot reload
+photon cli <name> [method]        # Run as CLI tool
 
-**Key Features:**
-- 🎯 Each photon does one thing perfectly
-- 📦 3 production-ready photons available
-- ⚡ Auto-installs dependencies
-- 🔧 Works out of the box
-- 📄 Single-file design (easy to fork and customize)
+# Create
+photon maker new <name>           # Scaffold a new photon
 
-## 🎯 The Value Proposition
+# Manage
+photon info                       # List all photons
+photon info <name> --mcp          # Get MCP client config (paste into Claude/Cursor)
+photon validate <name>            # Check for errors
 
-### Before Photon
+# Marketplace
+photon add <name>                 # Install photon
+photon search <query>             # Search marketplace
+photon upgrade                    # Upgrade all
 
-For each MCP server:
-1. Find and clone the repository
-2. Install dependencies manually
-3. Configure environment variables
-4. Write MCP client config JSON by hand
-5. Repeat for every server
+# Ops
+photon doctor                     # Diagnose environment
+photon audit                      # Security audit
+photon test                       # Run tests
+```
 
-### With Photon
+---
 
-```bash
-# Install from marketplace
-photon add filesystem
+## Tag Reference (Quick Overview)
 
-# Get MCP config
-photon get filesystem --mcp
-```
+Tags are JSDoc annotations that control how Photon processes your code. Here are the most commonly used ones:
 
-Output (paste directly into your MCP client config):
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "photon",
-      "args": ["mcp", "filesystem"]
-    }
-  }
-}
-```
+| Tag | Where | What it does |
+|-----|-------|-------------|
+| `@dependencies` | Class | Auto-install npm packages on first run |
+| `@cli` | Class | Declare system CLI tool dependencies, checked at load time |
+| `@format` | Method | Control result rendering (table, list, markdown, code, etc.) |
+| `@param ... {@choice a,b,c}` | Param | Dropdown selection in Beam |
+| `@param ... {@format email}` | Param | Input validation and field type |
+| `@param ... {@min N} {@max N}` | Param | Numeric range constraints |
+| `@ui` | Class/Method | Link a custom HTML template |
+| `@webhook` | Method | Expose as HTTP endpoint |
+| `@scheduled` | Method | Run on a cron schedule |
+| `@locked` | Method | Distributed lock across processes |
+| `@autorun` | Method | Auto-execute when selected in Beam |
+| `@mcp` | Class | Inject another MCP server as a dependency |
+| `@icon` | Class/Method | Set emoji icon |
 
-**That's it.** No dependencies, no environment setup, no configuration files.
+> This is a subset. See the full [Tag Reference](./DOCBLOCK-TAGS.md) for all 30+ tags with examples.
 
-**Difference:**
-- ✅ One CLI, one command
-- ✅ Zero configuration
-- ✅ Instant installation
-- ✅ Auto-dependencies
-- ✅ Consistent experience
+---
 
-## 💡 Use Cases
+## Documentation
 
-**For Claude Users:**
-```bash
-photon add filesystem git github-issues
-photon get --mcp  # Get config for all three
-```
-Add to Claude Desktop → Now Claude can read files, manage repos, create issues
+**Start here:**
 
-**For Teams:**
-```bash
-photon add postgres mongodb redis
-photon get --mcp
-```
-Give Claude access to your data infrastructure
+| 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 |
 
-**For Developers:**
-```bash
-photon add docker git slack
-photon get --mcp
-```
-Automate your workflow through AI
+**Build more:**
 
-## 🔍 Browse & Search
+| 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 |
 
-```bash
-# List all photons
-photon get
+**Operate:**
 
-# Search by keyword
-photon search calendar
+| 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 |
 
-# View details
-photon get google-calendar
+**Reference:** [Architecture](./ARCHITECTURE.md) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
 
-# Upgrade all
-photon upgrade
-```
+---
 
-## 🏢 For Enterprises
+## Contributing
 
-Create your own marketplace:
+If you find a bug, or if my code offends you, feel free to open an issue or a PR. See [CONTRIBUTING.md](./CONTRIBUTING.md).
 
-```bash
-# 1. Organize photons
-mkdir company-photons && cd company-photons
+## License
 
-# 2. Generate marketplace
-photon maker sync
+[MIT](./LICENSE). Do what you want with it.
 
-# 3. Share with team
-git push origin main
+---
 
-# Team members use:
-photon marketplace add company/photons
-photon add your-internal-tool
-```
+<div align="center">
 
----
+*Singular focus. Precise target.*
 
-**Built with singular focus. Deployed with precise targeting.**
+Made by [Portel](https://github.com/portel-dev)
 
-Made with ⚛️ by [Portel](https://github.com/portel-dev)
+</div>
 
-<!-- PHOTON_MARKETPLACE_END -->