@portel/photon 1.4.1 → 1.6.0

package/README.md

@@ -1,1370 +1,519 @@
 
-![Photon Logo](https://raw.githubusercontent.com/portel-dev/photon/refs/heads/main/assets/photon-logo.png)
+<div align="center">
 
-[![npm version](https://badgen.net/npm/v/@portel/photon)](https://www.npmjs.com/package/@portel/photon)
-[![npm downloads](https://badgen.net/npm/dm/@portel/photon)](https://www.npmjs.com/package/@portel/photon)
-[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-logo.png" alt="Photon" width="500">
 
-# Photon
+**Simplify the creation of CLI tools, MCP servers, and web applications.**
 
-**Universal runtime that turns single-file TypeScript into MCP server, CLI, and more.**
+A framework, runtime, and ecosystem. Batteries included.
 
-Photon TS files are Single file. Zero boilerplate. Pure business logic.
+[![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)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/portel-dev/photon/blob/main/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178c6.svg)](https://www.typescriptlang.org)
+[![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)
 
----
-
-## TL;DR
-
-**The Problem with MCPs Today:**
-
-- Popular MCPs don't exactly match your specific requirements
-- **Security risk**: Malicious MCPs can steal your data through prompt injection—not just credentials
-- Scattered across 4-6 files, making security audits impractical
-- Too complex to fork and customize safely
-
-**Photon's Solution:** Single-file TypeScript format. Pure business logic, zero boilerplate. Fork-first design where every `.photon.ts` is trivial to audit and customize.
-
-Think of it like **NPM and Node, but for MCP**.
-
-### Write Once, Use Everywhere
-
-The same `.photon.ts` file automatically becomes:
-- 🤖 **MCP Server** - Tools for Claude Desktop, Cursor, and AI assistants
-- 💻 **CLI Tool** - Beautiful command-line interface for humans
-- 🔌 **Platform Integrations** - NCP, Lumina, and future runtimes
-
-```bash
-# Same file, multiple interfaces:
-photon mcp analytics              # Run as MCP server for AI
-photon cli analytics revenue      # Use as CLI tool for humans
-```
-
-**Zero extra code. Pure business logic. Infinite deployment targets.**
-
-### The Photon Ecosystem Flywheel
-
-![Photon Ecosystem](https://raw.githubusercontent.com/portel-dev/photon/refs/heads/main/assets/photon-ecosystem.png)
+[Quick Start](#quick-start) · [How It Works](#how-it-works) · [Beam UI](#beam) · [Marketplace](#marketplace) · [Docs](#documentation)
 
-The ecosystem creates a virtuous cycle: AI generates photons → Runtime executes them → Community shares → AI gets smarter.
+</div>
 
 ---
 
-## The Problem
-
-Traditional MCP servers scatter your logic across 4-6 files:
-
-```
-traditional-mcp/
-├── server.ts         (50 lines of boilerplate)
-├── transport.ts      (40 lines of setup)
-├── schemas.ts        (40 lines of type definitions)
-├── types.ts          (30 lines more types)
-├── package.json      (dependencies)
-└── business.ts       (20 lines of YOUR CODE)
-```
-
-**This creates real problems:**
-
-- ❌ **For AI agents**: Scattered context across files makes understanding difficult
-- ❌ **For humans**: Jump between files to understand one feature
-- ❌ **For teams**: 200+ lines before you write business logic
-- ❌ **For maintenance**: Changes require updating multiple files and configs
-
----
-
-## The Solution
-
-Photon puts everything in **one file**:
-
-```typescript
-/**
- * Analytics - Query company analytics database
- * @dependencies pg@^8.11.0
- */
-import { Client } from 'pg';
-
-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
-   * @param startDate Start date (YYYY-MM-DD)
-   * @param endDate End date (YYYY-MM-DD)
-   */
-  async revenue(params: { startDate: string; endDate: string }) {
-    const result = await this.db.query(
-      'SELECT date, SUM(amount) FROM orders WHERE date BETWEEN $1 AND $2 GROUP BY date',
-      [params.startDate, params.endDate]
-    );
-    return result.rows;
-  }
-}
-```
+## What Is This Thing?
 
-**40 lines. One file. Production-ready.**
+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:
 
-### Use It Everywhere
+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).
 
-That single file now works as both an **MCP server** and a **CLI tool**:
+It looks like this:
 
-```bash
-# As an MCP server (for AI assistants)
-photon mcp analytics
-# → Claude Desktop can now call revenue() as a tool
-
-# As a CLI (for humans)
-photon cli analytics revenue --startDate 2024-01-01 --endDate 2024-12-31
-# → Beautiful formatted output:
-# ┌────────────┬──────────┐
-# │ Date       │ Revenue  │
-# ├────────────┼──────────┤
-# │ 2024-01-01 │ $12,450  │
-# │ 2024-01-02 │ $15,320  │
-# └────────────┴──────────┘
 ```
-
-**Same code. Same logic. Two interfaces. Zero duplication.**
-
----
-
-## Why One File Changes Everything
-
-### 🤖 AI-Native Design
-
-AI agents can now understand your entire MCP in one context:
-
-```bash
-# AI can read, understand, and suggest improvements
-"Read my analytics.photon.ts and explain how it works"
-"Review this photon for security issues"
-"Add error handling to this photon"
+  analytics.photon.ts  →  MCP Server  |  CLI Tool  |  Web UI
 ```
 
-Traditional MCPs require AI to piece together scattered files — Photons give complete context.
-
-### 👤 Human-Friendly
+You just write the logic. Photon deals with the protocols, schemas, and the boring stuff that usually makes you question your life choices.
 
-- **Understand**: Read one file, understand the whole system
-- **Review**: Code reviews are one file, one story
-- **Debug**: All logic in one place, no jumping around
-- **Learn**: New team members read one file
+### The Basics
 
-### 🔧 Fork-First Philosophy
+If you are just skimming, here is what you need to know:
 
-Every photon is designed to be customized:
-
-```bash
-# Copy, modify, done — no build configs to update
-cp ~/.photon/jira.photon.ts ~/.photon/my-jira.photon.ts
-# Edit my-jira.photon.ts however you want
-photon mcp my-jira  # Works immediately
-```
+| 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) |
 
-**Use cases:**
+### Who Is This For?
 
-- Add company-specific authentication
-- Customize business logic
-- Merge multiple photons
-- Experiment without breaking originals
+*   **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.
 
-### 🔒 Security Through Transparency
-
-Prompt injection attacks are the new supply-chain threat. A malicious MCP can manipulate AI responses to exfiltrate your entire conversation history—not just credentials.
-
-**One file = one audit:**
-
-- Read 40 lines, understand everything
-- No hidden code scattered across imports
-- Fork and verify in minutes, not hours
-- Trust through transparency, not reputation
-
-When you can't trust a photon, you can **safely fork and audit it**. Traditional MCPs with scattered logic? Nearly impossible to verify.
-
-### 📦 Zero-Friction Dependencies
-
-Dependencies are auto-installed via JSDoc (like `npx` or `uv`):
-
-```typescript
-/**
- * @dependencies axios@^1.6.0, lodash@^4.17.21
- */
-```
-
-No manual `npm install`. No `package.json`. Photon handles it.
+You don't need to know what "MCP" actually stands for. If you can write a TypeScript class, you are qualified.
 
 ---
 
 ## Quick Start
 
-### Install
+If you are the type who likes to just run commands and see what happens:
 
 ```bash
 npm install -g @portel/photon
+photon maker new my-tool       # Makes a new photon
+photon                         # Opens the Beam UI
 ```
 
-### Use Ready-Made Photons
-
-The [**official Photon marketplace**](https://github.com/portel-dev/photons) comes pre-configured with 16+ production-ready photons:
+Or if you don't want to install anything (I get it):
 
 ```bash
-# Browse all photons
-photon info
-
-# Install any photon (filesystem, git, postgres, mongodb, slack, etc.)
-photon add filesystem
-
-# or else copy your own .photon.ts file to 
-# .photon folder in your user folder 
-
-# Call info command with mcp option
-photon info filesystem --mcp
-# Get client config json
-{
-  "filesystem": {
-    "command": "photon",
-    "args": [
-      "mcp",
-      "filesystem"
-    ],
-    "env": {
-      "FILESYSTEM_WORKDIR": "/Users/arul/Documents",
-      "FILESYSTEM_MAX_FILE_SIZE": "10485760",
-      "FILESYSTEM_ALLOW_HIDDEN": "false"
-    }
-  }
-}
-# Add to your client 
+npx @portel/photon maker new my-tool
+npx @portel/photon
 ```
 
-### Build Photons with AI
-
-Use the [**photon-skill**](https://github.com/portel-dev/photon-skill) for Claude Desktop or Claude Code to generate `.photon.ts` files:
-- Single TypeScript files with metadata
-- AI understands complete context in one file
-- Zero boilerplate, just business logic
-
-### Add Your Own Marketplace
-
-```bash
-# Add custom marketplace from GitHub
-photon marketplace add your-org/your-photons
-
-# Install from your marketplace
-photon add your-custom-tool
-```
+> **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`.
 
 ---
 
-## The Value Proposition
+## How It Works
 
-| Metric | Traditional MCP | Photon |
-|--------|-----------------|--------|
-| **Setup Time** | 40 minutes | 5 minutes |
-| **Lines of Code** | 200+ | ~40 |
-| **Files Needed** | 4-6 files | 1 file |
-| **Boilerplate** | Manual | Auto-handled |
-| **Schema Generation** | Manual | Automatic from TypeScript |
-| **Dependencies** | Manual npm install | Auto-installed from @dependencies |
-| **Hot Reload** | Configure yourself | Built-in with --dev |
-| **AI Context** | Scattered | Single file |
-| **CLI Interface** | Write separate code | Automatic from same code |
-| **Deployment Targets** | MCP only | MCP, CLI, NCP, Lumina, APIs... |
+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.
 
-[See detailed comparison →](COMPARISON.md)
+I’ll show you.
 
----
+### Step 1: The Bare Minimum
 
-## CLI Interface
+Here is a class with one method. This is a valid photon.
 
-Every photon automatically provides a beautiful CLI interface with zero additional code. The same business logic that powers your MCP tools becomes instantly available from the terminal.
-
-### Quick Example
-
-```bash
-# List all methods
-photon cli lg-remote
-
-# Call methods with natural syntax
-photon cli lg-remote volume 50
-photon cli lg-remote volume +5
-photon cli lg-remote channel 7
-photon cli lg-remote app netflix
-
-# Get method help
-photon cli lg-remote volume --help
-```
-
-### Beautiful Output Formats
-
-Photon automatically formats output based on data structure:
-
-**Tables** - Key-value pairs and flat objects:
-```bash
-$ photon cli lg-remote volume
-┌─────────┬────┐
-│ volume  │ 45 │
-├─────────┼────┤
-│ muted   │ no │
-├─────────┼────┤
-│ maxVol  │ 100│
-└─────────┴────┘
+```typescript
+export default class Weather {
+  async forecast(params: { city: string }) {
+    return `Weather for ${params.city}: Sunny, 72°F`;
+  }
+}
 ```
 
-**Lists** - Arrays of items:
-```bash
-$ photon cli lg-remote apps
-• Netflix (netflix)
-• YouTube (youtube.leanback.v4)
-• HDMI1 (com.webos.app.hdmi1)
-• Disney+ (disney)
-```
+**What happens:** Beam sees this and makes a form with a text box labeled "city". You click a button, and it runs.
 
-**Trees** - Hierarchical data (shown as formatted JSON)
-**Primitives** - Simple values displayed directly
+**What you get:**
+*   `photon mcp weather` (The server for Claude)
+*   `photon cli weather forecast --city Paris` (The command line tool)
+*   `photon` (The web UI)
 
-### Format System
+<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">
+</div>
 
-Photon uses a smart format system with 5 standard types:
+### Step 2: Adding Descriptions
 
-1. **`primitive`** - String, number, boolean
-2. **`table`** - Flat object or array of flat objects
-3. **`tree`** - Nested/hierarchical data
-4. **`list`** - Array of simple items
-5. **`none`** - No return value (void operations)
+If you add JSDoc comments, they show up as descriptions.
 
-**Hint the format** (optional):
 ```typescript
 /**
- * Get current volume
- * @format table
+ * Weather - Check weather forecasts worldwide
+ *
+ * Provides current conditions.
  */
-async volume() {
-  return this._request('ssap://audio/getVolume');
+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`;
+  }
 }
 ```
 
-**Auto-detection**: If no `@format` tag is provided, Photon automatically detects the best format based on the return value structure.
-
-### CLI Command Reference
-
-#### `photon cli <photon-name> [method] [args...]`
-
-**List all methods:**
-```bash
-photon cli lg-remote
-```
-
-**Call a method:**
-```bash
-# No parameters
-photon cli lg-remote status
-
-# Single parameter
-photon cli lg-remote volume 50
-
-# Multiple parameters
-photon cli lg-remote search query "breaking bad" limit 10
-
-# Relative adjustments
-photon cli lg-remote volume +5
-photon cli lg-remote channel +1
-```
-
-**Get method help:**
-```bash
-photon cli lg-remote volume --help
-```
+**What happens:** Now the UI has helpful text. Also, the AI client reads this to understand what the tool does.
 
-**Raw JSON output:**
-```bash
-photon cli lg-remote volume --json
-```
+<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>
 
-### One Codebase, Multiple Interfaces
+### Step 3: Configuration (The clever bit)
 
-The beauty of Photon's design: **improvements to business logic automatically work across all interfaces**.
+If you need an API key, put it in the constructor.
 
-Write your logic once:
 ```typescript
-async volume(params?: { level?: number | string } | number | string) {
-  // Handle relative adjustments
-  if (typeof level === 'string' && level.startsWith('+')) {
-    const delta = parseInt(level);
-    const current = await this._getCurrentVolume();
-    const newVolume = current + delta;
-    await this._setVolume(newVolume);
+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();
   }
-  // ... rest of logic
-  return this._getCurrentVolume(); // Always return current state
 }
 ```
 
-**Works everywhere:**
-- ✅ **MCP**: Claude Desktop, Cursor, etc.
-- ✅ **CLI**: `photon cli lg-remote volume +5`
-- ✅ **Future interfaces**: HTTP, WebSocket, etc.
+**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.
 
-### Context-Aware Error Messages
+<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>
 
-Photons can provide helpful, context-aware errors:
+### Step 4: Validation (Stop bad inputs)
 
-```bash
-$ photon cli lg-remote channels
-❌ Error: TV channels not available. Currently on HDMI1.
-   Switch to a TV tuner input to access channels.
-```
+You can add tags to valid inputs.
 
-The same error quality appears in MCP tools—because it's the same code.
-
-### Exit Codes
-
-The CLI properly returns exit codes for automation:
-- **0**: Success
-- **1**: Error (tool execution failed, invalid parameters, etc.)
-
-Perfect for shell scripts and CI/CD:
-```bash
-if photon cli lg-remote volume 50; then
-  echo "Volume set successfully"
-else
-  echo "Failed to set volume"
-  exit 1
-fi
-```
-
----
-
-## How Photon Works
-
-### Convention = Automation
-
-**File Name → MCP Name**
 ```typescript
-// analytics.photon.ts → "analytics" MCP
-```
+/**
+ * Weather - Check weather forecasts worldwide
+ * @dependencies node-fetch@^3.0.0
+ */
+export default class Weather {
+  constructor(
+    private apiKey: string,
+    private units: string = 'metric'
+  ) {}
 
-**Class Methods → Tools**
-```typescript
-async revenue() {}      // → "revenue" tool
-async topCustomers() {} // → "topCustomers" tool
+  /**
+   * 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...
+  }
+}
 ```
 
-**TypeScript Types → JSON Schemas**
-```typescript
-async create(params: { title: string; priority: number }) {}
-// Photon auto-generates JSON schema from TypeScript types
-```
+**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`.
 
-**JSDoc → Tool Descriptions**
-```typescript
-/**
- * Get revenue by date range
- * @param startDate Start date (YYYY-MM-DD)
- */
-// Photon extracts descriptions automatically
-```
+#### System CLI Dependencies
 
-**Constructor Parameters → Environment Variables**
-```typescript
-constructor(private host: string, private database: string) {}
-// Maps to: ANALYTICS_HOST, ANALYTICS_DATABASE
-```
+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.
 
-**JSDoc @dependencies → Auto-Install**
 ```typescript
 /**
- * @dependencies pg@^8.11.0, lodash@^4.17.21
+ * Video processor
+ * @cli ffmpeg - https://ffmpeg.org/download.html
+ * @cli imagemagick - https://imagemagick.org/script/download.php
  */
-// Photon auto-installs on first run (like npx or uv)
+export default class VideoProcessor {
+  async convert({ input, format }: { input: string; format: string }) {
+    // ffmpeg is guaranteed to exist if this method runs
+  }
+}
 ```
 
----
-
-## Available Photons
-
-Production-ready photons from **[portel-dev/photons](https://github.com/portel-dev/photons)**:
-
-| Category | Photons | Total Tools |
-|----------|---------|-------------|
-| **Databases** | PostgreSQL (7), MongoDB (13), Redis (18), SQLite (9) | 47 |
-| **Infrastructure** | AWS S3 (11), Docker (10), Filesystem (13) | 34 |
-| **Development** | Git (11), GitHub Issues (7) | 18 |
-| **Communication** | Email (8), Slack (7) | 15 |
-| **Productivity** | Google Calendar (9), Jira (10) | 19 |
-| **Utilities** | Fetch (2), Time (3), Memory (10) | 15 |
+If `ffmpeg` is not installed, the photon won't load and the user sees:
 
-**Total: 16 photons, 148 focused tools**
-
-Browse and install:
-```bash
-photon info            # See all available photons
-photon add postgres   # Install any photon
-photon search git     # Search by keyword
 ```
-
----
-
-## Create Your Own Photon
-
-### 1. Initialize
-
-```bash
-photon init analytics
+VideoProcessor requires the following CLI tools to be installed:
+  - ffmpeg: Install from https://ffmpeg.org/download.html
 ```
 
-Creates `analytics.photon.ts` in `~/.photon/` (accessible from anywhere).
+> See the full [Tag Reference](./DOCBLOCK-TAGS.md) for all available tags. There are 30+ covering validation, UI hints, scheduling, webhooks, and more.
 
-**Custom directory:**
-```bash
-photon --working-dir ./my-photons init analytics
-```
+<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>
 
-### 2. Write Business Logic
+### Step 5: Custom UI (When you want to be fancy)
+
+If the auto-generated form is too boring, you can write your own HTML.
 
 ```typescript
 /**
- * Analytics - Query company analytics database
- * @dependencies pg@^8.11.0
+ * Weather - Check weather forecasts worldwide
+ * @dependencies node-fetch@^3.0.0
+ * @ui dashboard ./ui/weather.html
  */
-import { Client } from 'pg';
-
-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();
-  }
+export default class Weather {
+  constructor(private apiKey: string, private units: string = 'metric') {}
 
   /**
-   * Get revenue by date range
-   * @param startDate Start date (YYYY-MM-DD)
-   * @param endDate End date (YYYY-MM-DD)
+   * Get the weather forecast for a city
+   * @ui dashboard
+   * @format table
    */
-  async revenue(params: { startDate: string; endDate: string }) {
-    const result = await this.db.query(
-      'SELECT date, SUM(amount) FROM orders WHERE date BETWEEN $1 AND $2 GROUP BY date',
-      [params.startDate, params.endDate]
-    );
-    return result.rows;
-  }
-
-  async onShutdown() {
-    await this.db.end();
+  async forecast(params: { city: string; days?: number }) {
+    // returns structured weather data
   }
 }
 ```
 
-### 3. Run
-
-```bash
-# Development mode (hot reload)
-photon mcp analytics --dev
-
-# Production mode
-photon mcp analytics
+```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>
 ```
 
-**That's it!** Photon handles:
-- ✅ TypeScript compilation (via esbuild)
-- ✅ Schema generation from types
-- ✅ MCP protocol implementation
-- ✅ Environment variable mapping
-- ✅ Dependency installation (@dependencies)
-- ✅ Hot reload in dev mode
+**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.
 
-**You focus on:** Your business logic
-**Photon handles:** Everything else
+> 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>
 
-## Commands Reference
+### In Summary
 
-### Global Options
-
-```bash
---working-dir <dir>   # Use custom directory instead of ~/.photon
--V, --version         # Show version number
--h, --help            # Show help
-```
-
-### Development Commands
-
-#### `photon init <name>`
-Create a new `.photon.ts` file from template.
-
-```bash
-# Create in default directory (~/.photon)
-photon init calculator
-
-# Create in custom directory
-photon --working-dir ./my-photons init calculator
-```
+| 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 |
 
-#### `photon validate <name>`
-Validate syntax and extract schemas without running.
-
-```bash
-photon validate calculator
-```
-
-Useful for:
-- Checking syntax errors
-- Testing schema generation
-- CI/CD validation
-
-### Running Photons
-
-#### `photon mcp <name>`
-Run a photon as an MCP server.
-
-```bash
-# Production mode
-photon mcp calculator
-
-# Development mode (hot reload on file changes)
-photon mcp calculator --dev
-
-# Validate configuration without running
-photon mcp calculator --validate
-
-# Show MCP configuration template
-photon mcp calculator --config
-```
-
-**Options:**
-- `--dev` - Enable hot reload for development
-- `--validate` - Validate configuration without running server
-- `--config` - Show configuration template and exit
-
-#### `photon cli <photon-name> [method] [args...]`
-Run photon methods directly from the command line.
-
-```bash
-# List all available methods
-photon cli calculator
-
-# Call a method with arguments
-photon cli calculator add 5 10
-
-# Get method-specific help
-photon cli calculator add --help
-
-# Output raw JSON instead of formatted output
-photon cli calculator add 5 10 --json
-```
-
-**Arguments:**
-- Arguments are automatically coerced to expected types (string, number, boolean)
-- Strings starting with `+` or `-` are preserved for relative adjustments
-- Arrays and objects can be passed as JSON strings
-
-**Options:**
-- `--help` - Show help for the photon or specific method
-- `--json` - Output raw JSON instead of formatted output
-
-**Exit Codes:**
-- `0` - Success
-- `1` - Error (invalid arguments, execution failure, etc.)
-
-**Examples:**
-
-```bash
-# Smart home control
-photon cli lg-remote volume 50
-photon cli lg-remote volume +5      # Relative adjustment
-photon cli lg-remote channel 7
-photon cli lg-remote app netflix
-
-# Database queries
-photon cli postgres query "SELECT * FROM users LIMIT 10"
-
-# File operations
-photon cli filesystem read-file path "/home/user/document.txt"
-
-# Git operations
-photon cli git commit message "feat: add new feature"
-```
-
-### Inspect & Configure
-
-#### `photon info [name]`
-List all photons or show details for a specific one.
-
-```bash
-# List all installed photons
-photon info
-
-# Show details for one photon
-photon info calculator
-
-# Get MCP client configuration
-photon info calculator --mcp
-```
-
-**Options:**
-- `--mcp` - Output MCP server configuration for your client
-
-### Marketplace Commands
-
-#### `photon add <name>`
-Install a photon from a marketplace.
-
-```bash
-# Install from any enabled marketplace
-photon add filesystem
-
-# Install from specific marketplace
-photon add filesystem --marketplace portel-dev/photons
-```
-
-**Options:**
-- `--marketplace <name>` - Specify which marketplace to use
-
-#### `photon search <query>`
-Search for photons across all enabled marketplaces.
-
-```bash
-photon search database
-photon search git
-```
-
-#### `photon info <name>`
-Show detailed information about a photon from marketplaces.
-
-```bash
-photon info postgres
-```
-
-Shows:
-- Description
-- Available tools
-- Configuration requirements
-- Marketplace source
-
-#### `photon upgrade [name]`
-Upgrade photons from marketplaces.
-
-```bash
-# Upgrade all photons
-photon upgrade
-
-# Upgrade specific photon
-photon upgrade filesystem
-
-# Check for updates without upgrading
-photon upgrade --check
-```
-
-**Options:**
-- `--check` - Only check for updates, don't install
-
-#### `photon conflicts`
-Show photons available in multiple marketplaces.
-
-```bash
-photon conflicts
-```
-
-Useful when same photon name exists in different marketplaces.
-
-### Marketplace Management
-
-#### `photon marketplace list`
-List all configured marketplaces.
-
-```bash
-photon marketplace list
-```
-
-#### `photon marketplace add <repo>`
-Add a new marketplace.
-
-```bash
-# GitHub shorthand
-photon marketplace add username/repo
-
-# Full HTTPS URL
-photon marketplace add https://github.com/username/repo
-
-# SSH URL
-photon marketplace add git@github.com:username/repo.git
-
-# Direct URL
-photon marketplace add https://example.com/marketplace
-
-# Local path
-photon marketplace add ./my-local-marketplace
-```
-
-#### `photon marketplace remove <name>`
-Remove a marketplace.
-
-```bash
-photon marketplace remove my-marketplace
-```
-
-#### `photon marketplace enable <name>`
-Enable a previously disabled marketplace.
-
-```bash
-photon marketplace enable my-marketplace
-```
-
-#### `photon marketplace disable <name>`
-Disable a marketplace without removing it.
-
-```bash
-photon marketplace disable my-marketplace
-```
-
-#### `photon marketplace update [name]`
-Update marketplace metadata from remote.
-
-```bash
-# Update all marketplaces
-photon marketplace update
-
-# Update specific marketplace
-photon marketplace update portel-dev/photons
-```
-
-### Advanced Commands
-
-#### `photon sync marketplace [path]`
-Generate marketplace manifest and documentation.
-
-```bash
-# Sync current directory
-photon sync marketplace
-
-# Sync specific directory
-photon sync marketplace ./my-marketplace
-
-# Generate Claude Code plugin files too
-photon sync marketplace --claude-code
-```
-
-**Options:**
-- `--claude-code` - Also generate Claude Code plugin files (`.claude-plugin/`)
-- `--name <name>` - Override marketplace name
-- `--description <desc>` - Set marketplace description
-- `--owner <owner>` - Set owner name
-
-Used when creating your own marketplace. See [Marketplace System](#marketplace-system) and [Claude Code Plugins](#claude-code-plugins).
-
-#### `photon audit [name]`
-Security audit of photon dependencies.
-
-```bash
-# Audit all photons
-photon audit
-
-# Audit specific photon
-photon audit postgres
-```
-
-Checks for:
-- Vulnerable dependencies
-- Outdated packages
-- Security advisories
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/photon-ecosystem.png" alt="Photon Ecosystem" width="600">
+</div>
 
 ---
 
-## Marketplace System
-
-### For Users: Install from Marketplace
-
-```bash
-# Install from official marketplace (portel-dev/photons)
-photon add github-issues
-photon add sqlite
-photon add memory
-
-# Search for photons
-photon search slack
-```
-
-### For Teams: Create Your Marketplace
-
-**Build an internal marketplace for your organization:**
-
-```bash
-# 1. Organize your photons
-mkdir company-photons && cd company-photons
-cp ~/.photon/*.photon.ts .
-
-# 2. Generate marketplace manifest (and optionally Claude Code plugin)
-photon sync marketplace --claude-code
-
-# 3. Push to GitHub/Git
-git init
-git add .
-git commit -m "Initial marketplace"
-git push origin main
-
-# 4. Team members install (via CLI or Claude Code)
-photon marketplace add company/photons
-photon add internal-crm
-photon add analytics-db
-```
-
-**Benefits:**
+## Beam
 
-- 🔒 **Secure**: Your code, your infrastructure, your control
-- 📦 **Easy**: Single-file photons are trivial to maintain
-- 🎯 **Focused**: Build exact tools for your workflows
-- 📊 **Traceable**: Git-based versioning and attribution
-- 🔌 **Dual Distribution**: With `--claude-code`, also works as Claude Code plugin
+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.
 
-> **Tip:** Use `--claude-code` flag to enable installation via both Photon CLI and Claude Code plugin manager. See [Claude Code Plugins](#claude-code-plugins) for details.
+Run `photon`. That’s it.
 
-### Manage Marketplaces
-
-```bash
-# List all marketplaces
-photon marketplace list
-
-# Add marketplace (multiple formats supported)
-photon marketplace add username/repo              # GitHub shorthand
-photon marketplace add https://github.com/u/repo  # HTTPS
-photon marketplace add git@github.com:u/repo.git  # SSH
-photon marketplace add https://example.com/mkt    # Direct URL
-photon marketplace add ./local-photons            # Local path
-
-# Remove marketplace
-photon marketplace remove <name>
-
-# Search across all marketplaces
-photon search <keyword>
-```
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="700">
+</div>
 
 ---
 
-## Claude Code Plugins
-
-Photon marketplaces can be automatically published as **Claude Code plugins**, enabling users to install individual photons directly from Claude Code's plugin manager.
-
-### Why Dual Distribution?
+## Connecting to AI
 
-One marketplace, two distribution channels:
-
-**Via Photon CLI:**
-```bash
-photon add filesystem
-photon add git
-```
+If you want to use this with Claude or Cursor, you need the config.
 
-**Via Claude Code Plugin:**
 ```bash
-/plugin marketplace add your-org/your-marketplace
-/plugin install filesystem@your-marketplace
-/plugin install git@your-marketplace
+photon info weather --mcp
 ```
 
-**Benefits:**
-- 🎯 **Granular Installation**: Claude Code users can install only the photons they need
-- 🔄 **Auto-Sync**: Plugin stays in sync with your marketplace
-- ⚡ **Zero Config**: Photon CLI auto-installs on first use
-- 🛡️ **Secure**: Credentials never shared with AI (interactive setup available)
-- 📦 **Same Source**: One marketplace serves both CLI and plugin users
-
-### Generate Plugin Files
-
-When creating your marketplace, add the `--claude-code` flag:
-
-```bash
-# In your marketplace directory
-photon sync marketplace --claude-code
-```
-
-This generates:
-- `.claude-plugin/marketplace.json` - Plugin manifest with individual photon entries
-- `.claude-plugin/hooks.json` - SessionStart hook to auto-install Photon CLI
-- `.claude-plugin/scripts/check-photon.sh` - Auto-installer script
-- `.claude-plugin/scripts/setup-photon.sh` - Interactive credential setup tool
-
-### What Gets Generated
-
-**Individual Plugins:** Each photon becomes a separate installable plugin in Claude Code:
+It spits out some JSON:
 
 ```json
 {
-  "name": "your-marketplace",
-  "plugins": [
-    {
-      "name": "filesystem",
-      "description": "Filesystem - File and directory operations",
-      "mcpServers": {
-        "filesystem": {
-          "command": "photon",
-          "args": ["mcp", "filesystem"]
-        }
-      }
+  "mcpServers": {
+    "weather": {
+      "command": "photon",
+      "args": ["mcp", "weather"]
     }
-    // ... one entry per photon
-  ]
-}
-```
-
-**Auto-Install Hook:** When users install your plugin, Claude Code automatically:
-1. Checks if `photon` CLI is installed
-2. Installs it globally via npm if missing
-3. Makes all photon tools available immediately
-
-### Example: Official Photons Marketplace
-
-The [official photons marketplace](https://github.com/portel-dev/photons) uses this approach:
-
-```bash
-# In the photons repo
-photon sync marketplace --claude-code
-git commit -m "chore: update marketplace"
-git push
-```
-
-Users can then install via Claude Code:
-```bash
-/plugin marketplace add portel-dev/photons
-/plugin install knowledge-graph@photons-marketplace
-/plugin install git@photons-marketplace
-```
-
-### Automated Git Hooks
-
-Add this to your `.git/hooks/pre-commit` to auto-sync:
-
-```bash
-#!/bin/bash
-photon sync marketplace --claude-code
-git add .marketplace/ .claude-plugin/ README.md *.md
-```
-
-Now your marketplace AND plugin files stay in sync automatically.
-
-### Distribution Strategy
-
-**Recommended approach:**
-
-1. **Commit both** `.marketplace/` and `.claude-plugin/` to your repo
-2. **Single command** keeps them in sync
-3. **Users choose** their preferred installation method
-4. **Same photons**, whether via CLI or Claude Code
-
-**Result:** Maximum reach with minimal maintenance.
-
----
-
-## Advanced Features
-
-### Lifecycle Hooks
-
-```typescript
-export default class MyPhoton {
-  async onInitialize() {
-    // Called when photon loads
-    console.error('Photon initialized');
-  }
-
-  async onShutdown() {
-    // Called on shutdown
-    console.error('Photon shutting down');
-  }
-
-  async myTool(params: { input: string }) {
-    return `Processed: ${params.input}`;
   }
 }
 ```
 
-### Templates (MCP Prompts)
-
-```typescript
-import { Template, asTemplate } from '@portel/photon';
-
-export default class MyPhoton {
-  /**
-   * Generate a code review prompt
-   * @Template
-   * @param language Programming language
-   * @param code Code to review
-   */
-  async codeReview(params: { language: string; code: string }): Promise<Template> {
-    const prompt = `Review this ${params.language} code:\n\`\`\`\n${params.code}\n\`\`\``;
-    return asTemplate(prompt);
-  }
-}
-```
+Copy that. Paste it into your AI client’s config file. Done.
 
-### Static Resources (MCP Resources)
+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).
 
-```typescript
-import { Static, asStatic } from '@portel/photon';
+---
 
-export default class MyPhoton {
-  /**
-   * Get API documentation
-   * @Static api://docs
-   * @mimeType text/markdown
-   */
-  async apiDocs(params: {}): Promise<Static> {
-    const docs = `# API Documentation\n\n...`;
-    return asStatic(docs);
-  }
-}
-```
+## Why did we build this?
 
-### Private Methods
+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.
 
-Methods starting with `_` are private (not exposed as tools):
+With Photon, it’s one file.
 
-```typescript
-export default class MyPhoton {
-  // Public tool
-  async publicTool(params: {}) {
-    return this._helperMethod();
-  }
+| | 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 |
 
-  // Private helper (NOT exposed)
-  async _helperMethod() {
-    return "Internal logic only";
-  }
-}
-```
+It is unnecessarily difficult to do it the old way. So we stopped doing it.
 
 ---
 
-## Examples
+## Marketplace
 
-The repository includes example photons in `examples/`:
+We also have a marketplace. 31 photons and counting.
 
-### Content (Templates & Static Resources)
-```bash
-npx photon --working-dir examples mcp content --dev
-```
-Demonstrates Templates (MCP Prompts) and Static resources.
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="700">
+</div>
 
-### Calculator
 ```bash
-npx photon --working-dir examples mcp math --dev
+photon search postgres
+photon add postgres
 ```
-Basic arithmetic operations.
 
-### String Utilities
-```bash
-npx photon --working-dir examples mcp text --dev
-```
-Text manipulation tools.
+### Available Photons
 
-### Workflow
-```bash
-npx photon --working-dir examples mcp workflow --dev
-```
-Task management system.
+**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 |
 
-## Architecture
+**Infrastructure**
 
-```
-┌─────────────────────┐
-│  .photon.ts file    │  ← Your single TypeScript file
-└──────────┬──────────┘
-           │
-           ↓
-   ┌───────────────┐
-   │ Auto-Install  │  ← Reads @dependencies, installs packages
-   └───────┬───────┘
-           │
-           ↓
-   ┌───────────────┐
-   │    Loader     │  ← Compiles TypeScript with esbuild
-   └───────┬───────┘    Loads class dynamically
-           │
-           ↓
- ┌─────────────────────┐
- │  Schema Extractor   │  ← Parses JSDoc + TypeScript types
- └──────────┬──────────┘    Generates JSON schemas
-            │
-            ↓
-    ┌──────────────┐
-    │  MCP Server  │  ← Implements MCP protocol
-    └──────┬───────┘    Using @modelcontextprotocol/sdk
-           │
-           ↓
-   ┌─────────────-─┐
-   │ stdio/JSON-RPC│  ← Communicates with MCP clients
-   └─────────────-─┘    (Claude Desktop, Cursor, Zed, etc.)
-```
-
----
+| 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 |
 
-## Philosophy
+**Databases**
 
-> **"Singular focus. Precise target."**
+| 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 |
 
-A **photon** is the smallest unit of light, delivering **singular focus** to a **precise target**.
+**Utilities and Demos**
 
-Each Photon module embodies this principle:
+| 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 |
 
-- **Singular focus** - One responsibility, executed flawlessly
-- **Precise target** - Clear purpose, clean API
-- **Universal design** - Pure TypeScript, ready for future possibilities
+You can also make a private marketplace for your team, so internal tools stay off the public internet.
 
 ---
 
-## FAQ
-
-### Do I need to extend a base class?
-
-No! Just export any class with async methods. Photon handles the rest.
-
-### How are parameters validated?
-
-Photon extracts JSON schemas from your TypeScript types. MCP clients validate parameters before calling your tools.
-
-### Can I use external packages?
-
-Yes! Dependencies are **auto-installed** from JSDoc `@dependencies` tags (like `npx` or `uv`).
-
-### How does hot reload work?
-
-In `--dev` mode, Photon watches your `.photon.ts` file and recompiles on save.
-
-### Where are compiled files cached?
-
-`~/.cache/photon-mcp/compiled/`
+## Commands
 
-### Where are my photons stored?
+A few commands you might use:
 
-**Default:** `~/.photon/`
-**Custom:** Use `--working-dir` flag
+```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
 
-### Can I fork and customize photons?
+# Create
+photon maker new <name>           # Scaffold a new photon
 
-Absolutely! That's the design. Copy any `.photon.ts` file, edit it, run it. No build config changes needed.
+# Manage
+photon info                       # List all photons
+photon info <name> --mcp          # Get MCP client config (paste into Claude/Cursor)
+photon validate <name>            # Check for errors
 
-### How do I update photons?
+# Marketplace
+photon add <name>                 # Install photon
+photon search <query>             # Search marketplace
+photon upgrade                    # Upgrade all
 
-```bash
-photon upgrade        # Update all
-photon upgrade <name> # Update specific photon
+# Ops
+photon doctor                     # Diagnose environment
+photon audit                      # Security audit
+photon test                       # Run tests
 ```
 
 ---
 
-## Roadmap
-
-### ✅ MCP Servers & CLI Interface (Available Now)
-
-**MCP Servers:**
-Build and run photons as MCP servers for AI assistants. Works with Claude Desktop, Cursor, Zed, Continue, Cline, and any MCP-compatible client.
-
-**CLI Interface:**
-Run photon methods directly from the command line with beautiful formatted output. Every photon automatically becomes a CLI tool with zero additional code.
-
-**Write once, deploy everywhere:** The same business logic powers both your MCP tools and CLI commands.
-
-### 🔌 Ecosystem Integrations
-
-Photon files are first-class citizens across multiple platforms:
-
-#### NCP - Intelligent MCP Orchestration
-
-[NCP](https://github.com/portel-dev/ncp) runs as an MCP client hosting many MCPs intelligently, while acting as an MCP server for any client. Photon files integrate seamlessly as context providers.
-
-```bash
-# Photons work natively with NCP
-ncp add analytics.photon.ts
-```
-
-NCP enables sophisticated MCP orchestration patterns, and `.photon.ts` files are designed to work seamlessly in this environment.
+## Tag Reference (Quick Overview)
 
-#### Lumina - Anything API Server *(Coming Soon)*
+Tags are JSDoc annotations that control how Photon processes your code. Here are the most commonly used ones:
 
-Turn any photon into a production API endpoint with zero configuration.
+| 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 |
 
-```bash
-# Same photon, now an HTTP API
-lumina serve analytics.photon.ts
-# → POST /revenue with JSON params
-# → GET /status
-# → Full REST API from your photon methods
-```
+> This is a subset. See the full [Tag Reference](./DOCBLOCK-TAGS.md) for all 30+ tags with examples.
 
-Lumina will make photons available as HTTP/WebSocket endpoints, enabling web apps, mobile clients, and traditional API consumers to use the same business logic.
+---
 
-#### Future Platforms
+## Documentation
 
-The `.photon.ts` format is designed to be consumed by any runtime:
-- WebSocket servers
-- Serverless functions (AWS Lambda, Cloudflare Workers)
-- Native desktop applications
-- Browser extensions
-- GraphQL servers
+**Start here:**
 
-**One file. Many platforms. Pure business logic.**
+| 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 |
 
----
+**Build more:**
 
-Photon's framework-agnostic design enables future deployment targets. More on the way.
+| 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 |
 
----
+**Operate:**
 
-## Documentation
+| 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 |
 
-- **[GUIDE.md](GUIDE.md)** - Complete tutorial for creating photons
-- **[ADVANCED.md](ADVANCED.md)** - Lifecycle hooks, performance, production deployment
-- **[COMPARISON.md](COMPARISON.md)** - Detailed comparison vs traditional MCP
-- **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common issues and solutions
-- **[CHANGELOG.md](CHANGELOG.md)** - Version history
+**Reference:** [Architecture](./ARCHITECTURE.md) · [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md)
 
 ---
 
 ## Contributing
 
-Contributions welcome! Please open issues and PRs at [github.com/portel-dev/photon-mcp](https://github.com/portel-dev/photon-mcp).
-
----
+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).
 
-## Related Projects
+## License
 
-- **[photons](https://github.com/portel-dev/photons)** - Official marketplace with 16+ production-ready photons
-- **@modelcontextprotocol/sdk** - Official MCP TypeScript SDK
+[MIT](./LICENSE). Do what you want with it.
 
 ---
 
-## License
+<div align="center">
 
-MIT © Portel
+*Singular focus. Precise target.*
 
----
+Made by [Portel](https://github.com/portel-dev)
 
-**Built with singular focus. Deployed with precise targeting.**
+</div>
 
-Made with ⚛️ by [Portel](https://github.com/portel-dev)