@portel/photon 1.4.1 → 1.5.1

package/README.md

@@ -1,84 +1,38 @@
 
-![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
+**Build MCP servers from single TypeScript files.**
 
-**Universal runtime that turns single-file TypeScript into MCP server, CLI, and more.**
+Write business logic. Get an MCP server, CLI, and web UI — automatically.
 
-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) · [Features](#features) · [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:
+## Quick Start
 
+```bash
+npm install -g @portel/photon
+photon init my-tool
+photon                        # Open Beam UI in your browser
 ```
-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**:
+Create `analytics.photon.ts` — no boilerplate, no config files:
 
 ```typescript
 /**
- * Analytics - Query company analytics database
+ * Analytics - Query company analytics
  * @dependencies pg@^8.11.0
  */
 import { Client } from 'pg';
@@ -86,1285 +40,458 @@ import { Client } from 'pg';
 export default class Analytics {
   private db: Client;
 
-  constructor(
-    private host: string,
-    private database: string,
-    private password: string
-  ) {}
+  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
-    });
+    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)
-   */
+  /** Get revenue by date range */
   async revenue(params: { startDate: string; endDate: string }) {
-    const result = await this.db.query(
+    return (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;
+    )).rows;
   }
 }
 ```
 
-**40 lines. One file. Production-ready.**
-
-### Use It Everywhere
-
-That single file now works as both an **MCP server** and a **CLI tool**:
+Same file, three interfaces:
 
 ```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  │
-# └────────────┴──────────┘
+photon mcp analytics              # MCP server for Claude, Cursor, Zed
+photon cli analytics revenue      # CLI for humans
+photon                            # Beam web UI
 ```
 
-**Same code. Same logic. Two interfaces. Zero duplication.**
+<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>
 
 ---
 
-## Why One File Changes Everything
+## Beam
 
-### 🤖 AI-Native Design
+Beam is the human interface to MCP — browse, configure, test, and execute tools visually.
 
-AI agents can now understand your entire MCP in one context:
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-dashboard.png" alt="Beam Dashboard" width="700">
+</div>
 
-```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"
-```
+<br>
 
-Traditional MCPs require AI to piece together scattered files — Photons give complete context.
+<table>
+<tr>
+<td width="50%">
 
-### 👤 Human-Friendly
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-tool-form.png" alt="Auto-generated forms" width="100%">
 
-- **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
+**Auto-generated forms** — Built from your TypeScript types. Required fields marked, types validated.
 
-### 🔧 Fork-First Philosophy
+</td>
+<td width="50%">
 
-Every photon is designed to be customized:
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-execute.png" alt="Tool execution" width="100%">
 
-```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
-```
-
-**Use cases:**
-
-- Add company-specific authentication
-- Customize business logic
-- Merge multiple photons
-- Experiment without breaking originals
-
-### 🔒 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:**
+**Execute and verify** — Test every tool before deploying to AI. See exactly what AI will see.
 
-- Read 40 lines, understand everything
-- No hidden code scattered across imports
-- Fork and verify in minutes, not hours
-- Trust through transparency, not reputation
+</td>
+</tr>
+</table>
 
-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`):
+Constructor parameters become form fields, environment variables, and CLI flags automatically:
 
 ```typescript
-/**
- * @dependencies axios@^1.6.0, lodash@^4.17.21
- */
+constructor(
+  private host: string,      // → ANALYTICS_HOST env var → text field
+  private database: string,  // → ANALYTICS_DATABASE    → text field
+  private password: string   // → ANALYTICS_PASSWORD    → password field
+) {}
 ```
 
-No manual `npm install`. No `package.json`. Photon handles it.
-
 ---
 
-## Quick Start
+## Features
 
-### Install
+### Convention Over Configuration
 
-```bash
-npm install -g @portel/photon
-```
-
-### Use Ready-Made Photons
-
-The [**official Photon marketplace**](https://github.com/portel-dev/photons) comes pre-configured with 16+ production-ready photons:
+| 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 |
 
-```bash
-# Browse all photons
-photon info
-
-# Install any photon (filesystem, git, postgres, mongodb, slack, etc.)
-photon add filesystem
+### Full Platform
 
-# 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 
-```
+- **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
 
-### Build Photons with AI
+### Why Single File?
 
-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
+Traditional MCPs scatter logic across 4-6 files. Photon keeps everything in one:
 
-### 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
-```
+| | 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 |
 
 ---
 
-## The Value Proposition
-
-| 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... |
-
-[See detailed comparison →](COMPARISON.md)
-
----
+## Marketplace
 
-## CLI Interface
+<div align="center">
+<img src="https://raw.githubusercontent.com/portel-dev/photon/main/assets/beam-marketplace.png" alt="Marketplace" width="700">
+</div>
 
-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.
+<br>
 
-### Quick Example
+Install production-ready photons or create team marketplaces:
 
 ```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│
-└─────────┴────┘
-```
-
-**Lists** - Arrays of items:
-```bash
-$ photon cli lg-remote apps
-• Netflix (netflix)
-• YouTube (youtube.leanback.v4)
-• HDMI1 (com.webos.app.hdmi1)
-• Disney+ (disney)
-```
-
-**Trees** - Hierarchical data (shown as formatted JSON)
-**Primitives** - Simple values displayed directly
-
-### Format System
-
-Photon uses a smart format system with 5 standard types:
-
-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)
-
-**Hint the format** (optional):
-```typescript
-/**
- * Get current volume
- * @format table
- */
-async volume() {
-  return this._request('ssap://audio/getVolume');
-}
+photon search postgres            # Find photons
+photon add postgres               # Install
+photon upgrade                    # Keep current
 ```
 
-**Auto-detection**: If no `@format` tag is provided, Photon automatically detects the best format based on the return value structure.
-
-### CLI Command Reference
+**Available:** PostgreSQL, MongoDB, Redis, SQLite, AWS S3, Docker, Filesystem, Git, GitHub, Email, Slack, Google Calendar, Jira, and more.
 
-#### `photon cli <photon-name> [method] [args...]`
-
-**List all methods:**
 ```bash
-photon cli lg-remote
+# Create a team marketplace
+photon sync marketplace --claude-code
+git push origin main
+# Team members: photon marketplace add company/photons
 ```
 
-**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
-```
+## Commands
 
-**Get method help:**
 ```bash
-photon cli lg-remote volume --help
-```
-
-**Raw JSON output:**
-```bash
-photon cli lg-remote volume --json
-```
+# 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
 
-### One Codebase, Multiple Interfaces
+# 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
 
-The beauty of Photon's design: **improvements to business logic automatically work across all interfaces**.
+# Marketplace
+photon add <name>                 # Install photon
+photon search <query>             # Search
+photon upgrade                    # Upgrade all
 
-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);
-  }
-  // ... 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.
-
-### Context-Aware Error Messages
-
-Photons can provide helpful, context-aware errors:
-
-```bash
-$ photon cli lg-remote channels
-❌ Error: TV channels not available. Currently on HDMI1.
-   Switch to a TV tuner input to access channels.
-```
-
-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
+# Ops
+photon doctor                     # Diagnose environment
+photon audit                      # Security audit
+photon test                       # Run tests
+photon deploy                     # Deploy to production
 ```
 
 ---
 
-## How Photon Works
+## Documentation
 
-### Convention = Automation
+**Start here:**
 
-**File Name → MCP Name**
-```typescript
-// analytics.photon.ts → "analytics" MCP
-```
+| 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 |
 
-**Class Methods → Tools**
-```typescript
-async revenue() {}      // → "revenue" tool
-async topCustomers() {} // → "topCustomers" tool
-```
+**Deep dives:**
 
-**TypeScript Types → JSON Schemas**
-```typescript
-async create(params: { title: string; priority: number }) {}
-// Photon auto-generates JSON schema from TypeScript types
-```
+| 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 |
 
-**JSDoc → Tool Descriptions**
-```typescript
-/**
- * Get revenue by date range
- * @param startDate Start date (YYYY-MM-DD)
- */
-// Photon extracts descriptions automatically
-```
-
-**Constructor Parameters → Environment Variables**
-```typescript
-constructor(private host: string, private database: string) {}
-// Maps to: ANALYTICS_HOST, ANALYTICS_DATABASE
-```
-
-**JSDoc @dependencies → Auto-Install**
-```typescript
-/**
- * @dependencies pg@^8.11.0, lodash@^4.17.21
- */
-// Photon auto-installs on first run (like npx or uv)
-```
+**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)
 
 ---
 
-## Available Photons
-
-Production-ready photons from **[portel-dev/photons](https://github.com/portel-dev/photons)**:
+## Contributing
 
-| 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 |
+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).
 
-**Total: 16 photons, 148 focused tools**
+## License
 
-Browse and install:
-```bash
-photon info            # See all available photons
-photon add postgres   # Install any photon
-photon search git     # Search by keyword
-```
+[MIT](https://github.com/portel-dev/photon/blob/main/LICENSE)
 
 ---
 
-## Create Your Own Photon
-
-### 1. Initialize
+<div align="center">
 
-```bash
-photon init analytics
-```
+*Singular focus. Precise target.*
 
-Creates `analytics.photon.ts` in `~/.photon/` (accessible from anywhere).
+Made by [Portel](https://github.com/portel-dev)
 
-**Custom directory:**
-```bash
-photon --working-dir ./my-photons init analytics
-```
+</div>
 
-### 2. Write Business Logic
+<!-- PHOTON_MARKETPLACE_START -->
+# photon
 
-```typescript
-/**
- * Analytics - Query company analytics database
- * @dependencies pg@^8.11.0
- */
-import { Client } from 'pg';
+> **Singular focus. Precise target.**
 
-export default class Analytics {
-  private db: Client;
+**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.
 
-  constructor(
-    private host: string,
-    private database: string,
-    private password: string
-  ) {}
+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
 
-  async onInitialize() {
-    this.db = new Client({
-      host: this.host,
-      database: this.database,
-      password: this.password
-    });
-    await this.db.connect();
-  }
+## 📦 Available Photons
 
-  /**
-   * 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;
-  }
-
-  async onShutdown() {
-    await this.db.end();
-  }
-}
-```
-
-### 3. Run
-
-```bash
-# Development mode (hot reload)
-photon mcp analytics --dev
-
-# Production mode
-photon mcp analytics
-```
+| 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 | 🎨 |
 
-**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
 
-**You focus on:** Your business logic
-**Photon handles:** Everything else
+**Total:** 3 photons ready to use
 
 ---
 
-## Commands Reference
+## 🚀 Quick Start
 
-### Global Options
+### 1. Install Photon
 
 ```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
-```
-
-#### `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
+npm install -g @portel/photon
 ```
 
-**Options:**
-- `--mcp` - Output MCP server configuration for your client
-
-### Marketplace Commands
-
-#### `photon add <name>`
-Install a photon from a marketplace.
+### 2. Add Any Photon
 
 ```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
+photon add git
+photon add aws-s3
 ```
 
-Shows:
-- Description
-- Available tools
-- Configuration requirements
-- Marketplace source
-
-#### `photon upgrade [name]`
-Upgrade photons from marketplaces.
+### 3. Use It
 
 ```bash
-# Upgrade all photons
-photon upgrade
-
-# Upgrade specific photon
-photon upgrade filesystem
+# Run as MCP server
+photon mcp filesystem
 
-# Check for updates without upgrading
-photon upgrade --check
+# Get config for your MCP client
+photon get filesystem --mcp
 ```
 
-**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
+Output (paste directly into your MCP client config):
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "photon",
+      "args": ["mcp", "filesystem"]
+    }
+  }
+}
 ```
 
-#### `photon marketplace add <repo>`
-Add a new marketplace.
+Add the output to your MCP client's configuration. **Consult your client's documentation** for setup instructions.
 
-```bash
-# GitHub shorthand
-photon marketplace add username/repo
-
-# Full HTTPS URL
-photon marketplace add https://github.com/username/repo
+**That's it!** Your AI assistant now has 3 focused tools at its fingertips.
 
-# SSH URL
-photon marketplace add git@github.com:username/repo.git
+---
 
-# Direct URL
-photon marketplace add https://example.com/marketplace
+## 🎨 Claude Code Integration
 
-# Local path
-photon marketplace add ./my-local-marketplace
-```
+This marketplace is also available as a **Claude Code plugin**, enabling seamless installation of individual photons directly from Claude Code's plugin manager.
 
-#### `photon marketplace remove <name>`
-Remove a marketplace.
+### Install as Claude Code Plugin
 
 ```bash
-photon marketplace remove my-marketplace
-```
-
-#### `photon marketplace enable <name>`
-Enable a previously disabled marketplace.
-
-```bash
-photon marketplace enable my-marketplace
+# In Claude Code, run:
+/plugin marketplace add portel-dev/photons
 ```
 
-#### `photon marketplace disable <name>`
-Disable a marketplace without removing it.
+Once added, you can install individual photons:
 
 ```bash
-photon marketplace disable my-marketplace
+# Install specific photons you need
+/plugin install filesystem@photons-marketplace
+/plugin install git@photons-marketplace
+/plugin install knowledge-graph@photons-marketplace
 ```
 
-#### `photon marketplace update [name]`
-Update marketplace metadata from remote.
+### Benefits of Claude Code Plugin
 
-```bash
-# Update all marketplaces
-photon marketplace update
-
-# Update specific marketplace
-photon marketplace update portel-dev/photons
-```
+- **🎯 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
 
-### Advanced Commands
+### How This Plugin Is Built
 
-#### `photon sync marketplace [path]`
-Generate marketplace manifest and documentation.
+This marketplace doubles as a Claude Code plugin through automatic generation:
 
 ```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
+# Generate marketplace AND Claude Code plugin files
+photon maker sync --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).
+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
 
-#### `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
+**Result**: One source of truth, two distribution channels (Photon CLI + Claude Code).
 
 ---
 
-## Marketplace System
+## ⚛️ What Are Photons?
 
-### For Users: Install from Marketplace
+**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
 
-```bash
-# Install from official marketplace (portel-dev/photons)
-photon add github-issues
-photon add sqlite
-photon add memory
+Each photon delivers **singular focus** to a **precise target**.
 
-# Search for photons
-photon search slack
-```
+**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)
 
-### For Teams: Create Your Marketplace
+## 🎯 The Value Proposition
 
-**Build an internal marketplace for your organization:**
-
-```bash
-# 1. Organize your photons
-mkdir company-photons && cd company-photons
-cp ~/.photon/*.photon.ts .
+### Before Photon
 
-# 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
-```
+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
 
-**Benefits:**
-
-- 🔒 **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
-
-> **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.
-
-### Manage Marketplaces
+### With Photon
 
 ```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>
-```
-
----
-
-## 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?
-
-One marketplace, two distribution channels:
-
-**Via Photon CLI:**
-```bash
+# Install from marketplace
 photon add filesystem
-photon add git
-```
 
-**Via Claude Code Plugin:**
-```bash
-/plugin marketplace add your-org/your-marketplace
-/plugin install filesystem@your-marketplace
-/plugin install git@your-marketplace
+# Get MCP config
+photon get filesystem --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:
-
+Output (paste directly into your MCP client config):
 ```json
 {
-  "name": "your-marketplace",
-  "plugins": [
-    {
-      "name": "filesystem",
-      "description": "Filesystem - File and directory operations",
-      "mcpServers": {
-        "filesystem": {
-          "command": "photon",
-          "args": ["mcp", "filesystem"]
-        }
-      }
+  "mcpServers": {
+    "filesystem": {
+      "command": "photon",
+      "args": ["mcp", "filesystem"]
     }
-    // ... 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);
-  }
-}
-```
-
-### Static Resources (MCP Resources)
-
-```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);
-  }
-}
-```
-
-### Private Methods
-
-Methods starting with `_` are private (not exposed as tools):
-
-```typescript
-export default class MyPhoton {
-  // Public tool
-  async publicTool(params: {}) {
-    return this._helperMethod();
-  }
-
-  // Private helper (NOT exposed)
-  async _helperMethod() {
-    return "Internal logic only";
   }
 }
 ```
 
----
-
-## Examples
+**That's it.** No dependencies, no environment setup, no configuration files.
 
-The repository includes example photons in `examples/`:
+**Difference:**
+- ✅ One CLI, one command
+- ✅ Zero configuration
+- ✅ Instant installation
+- ✅ Auto-dependencies
+- ✅ Consistent experience
 
-### Content (Templates & Static Resources)
-```bash
-npx photon --working-dir examples mcp content --dev
-```
-Demonstrates Templates (MCP Prompts) and Static resources.
+## 💡 Use Cases
 
-### Calculator
+**For Claude Users:**
 ```bash
-npx photon --working-dir examples mcp math --dev
+photon add filesystem git github-issues
+photon get --mcp  # Get config for all three
 ```
-Basic arithmetic operations.
+Add to Claude Desktop → Now Claude can read files, manage repos, create issues
 
-### String Utilities
+**For Teams:**
 ```bash
-npx photon --working-dir examples mcp text --dev
+photon add postgres mongodb redis
+photon get --mcp
 ```
-Text manipulation tools.
+Give Claude access to your data infrastructure
 
-### Workflow
+**For Developers:**
 ```bash
-npx photon --working-dir examples mcp workflow --dev
-```
-Task management system.
-
----
-
-## Architecture
-
+photon add docker git slack
+photon get --mcp
 ```
-┌─────────────────────┐
-│  .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.)
-```
-
----
-
-## Philosophy
-
-> **"Singular focus. Precise target."**
-
-A **photon** is the smallest unit of light, delivering **singular focus** to a **precise target**.
-
-Each Photon module embodies this principle:
-
-- **Singular focus** - One responsibility, executed flawlessly
-- **Precise target** - Clear purpose, clean API
-- **Universal design** - Pure TypeScript, ready for future possibilities
-
----
-
-## FAQ
-
-### Do I need to extend a base class?
-
-No! Just export any class with async methods. Photon handles the rest.
+Automate your workflow through AI
 
-### 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/`
-
-### Where are my photons stored?
-
-**Default:** `~/.photon/`
-**Custom:** Use `--working-dir` flag
-
-### Can I fork and customize photons?
-
-Absolutely! That's the design. Copy any `.photon.ts` file, edit it, run it. No build config changes needed.
-
-### How do I update photons?
+## 🔍 Browse & Search
 
 ```bash
-photon upgrade        # Update all
-photon upgrade <name> # Update specific photon
-```
+# List all photons
+photon get
 
----
+# Search by keyword
+photon search calendar
 
-## Roadmap
+# View details
+photon get google-calendar
 
-### ✅ 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
+# Upgrade all
+photon upgrade
 ```
 
-NCP enables sophisticated MCP orchestration patterns, and `.photon.ts` files are designed to work seamlessly in this environment.
+## 🏢 For Enterprises
 
-#### Lumina - Anything API Server *(Coming Soon)*
-
-Turn any photon into a production API endpoint with zero configuration.
+Create your own marketplace:
 
 ```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
-```
-
-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
-
-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
-
-**One file. Many platforms. Pure business logic.**
-
----
-
-Photon's framework-agnostic design enables future deployment targets. More on the way.
-
----
-
-## Documentation
-
-- **[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
-
----
-
-## Contributing
-
-Contributions welcome! Please open issues and PRs at [github.com/portel-dev/photon-mcp](https://github.com/portel-dev/photon-mcp).
-
----
-
-## Related Projects
+# 1. Organize photons
+mkdir company-photons && cd company-photons
 
-- **[photons](https://github.com/portel-dev/photons)** - Official marketplace with 16+ production-ready photons
-- **@modelcontextprotocol/sdk** - Official MCP TypeScript SDK
+# 2. Generate marketplace
+photon maker sync
 
----
-
-## License
+# 3. Share with team
+git push origin main
 
-MIT © Portel
+# Team members use:
+photon marketplace add company/photons
+photon add your-internal-tool
+```
 
 ---
 
 **Built with singular focus. Deployed with precise targeting.**
 
 Made with ⚛️ by [Portel](https://github.com/portel-dev)
+
+<!-- PHOTON_MARKETPLACE_END -->