feat: Nexus portal documentation and entry for The Beacon

Closes #167

Adds documentation for integrating The Beacon as a portal in the Nexus world:
- docs/NEXUS_PORTAL.md: Complete integration guide
- portal-entry.json: Sample portal entry for portals.json

Covers three implementation options:
1. Simple iframe embed (recommended starting point)
2. State synchronization via postMessage
3. URL parameters for state passing

Includes security considerations, testing guide, and related issues.

docs/NEXUS_PORTAL.md

@@ -0,0 +1,165 @@
+# The Beacon — Nexus Portal Integration
+
+## Overview
+
+The Beacon can be embedded as a portal in the Nexus world, allowing users to play the game directly within the Nexus interface.
+
+## Portal Configuration
+
+Add the following entry to `portals.json` in the Nexus repository:
+
+```json
+{
+  "id": "the-beacon",
+  "name": "The Beacon",
+  "description": "An idle game about building a sovereign AI. Click to code, build, and rescue.",
+  "url": "https://the-beacon.alexanderwhitestone.com",
+  "icon": "🌟",
+  "category": "games",
+  "tags": ["idle", "game", "sovereign", "ai"],
+  "iframe": true,
+  "width": 1200,
+  "height": 800,
+  "sandbox": "allow-scripts allow-same-origin allow-forms",
+  "persistence": "localStorage",
+  "stateKey": "the-beacon-v2"
+}
+```
+
+## Requirements
+
+### 1. URL Hosting
+The Beacon must be hosted at a publicly accessible URL. Current deployment:
+- **Production:** https://the-beacon.alexanderwhitestone.com
+- **Local:** http://localhost:8080 (for development)
+
+### 2. Iframe Compatibility
+The Beacon is a standalone HTML file with no server-side dependencies. It can be embedded in an iframe without issues:
+- No `X-Frame-Options` restrictions
+- No `Content-Security-Policy` frame-ancestors restrictions
+- All assets are inline (CSS, JS) or from CDN
+
+### 3. Game State Persistence
+Game state is stored in `localStorage` with key `the-beacon-v2`:
+```javascript
+// Save
+localStorage.setItem('the-beacon-v2', JSON.stringify(gameState));
+
+// Load
+const saved = localStorage.getItem('the-beacon-v2');
+if (saved) {
+  const gameState = JSON.parse(saved);
+  // Restore game state
+}
+```
+
+### 4. Cross-Origin Considerations
+Since The Beacon is hosted on a different domain than Nexus:
+- `localStorage` is origin-specific
+- Game state won't persist across different domains
+- Solution: Use `postMessage` API for state synchronization
+
+## Implementation Options
+
+### Option 1: Simple iframe Embed
+The simplest approach — just embed The Beacon in an iframe:
+```html
+<iframe 
+  src="https://the-beacon.alexanderwhitestone.com" 
+  width="1200" 
+  height="800"
+  sandbox="allow-scripts allow-same-origin allow-forms"
+  title="The Beacon - Idle Game">
+</iframe>
+```
+
+**Pros:**
+- Simple, no code changes needed
+- Game runs in isolated context
+
+**Cons:**
+- State doesn't persist across Nexus sessions
+- No integration with Nexus UI
+
+### Option 2: State Synchronization
+Add postMessage communication between The Beacon and Nexus:
+
+1. **Beacon → Nexus:** Send state updates on save
+```javascript
+// In The Beacon
+window.parent.postMessage({
+  type: 'beacon-state',
+  state: gameState
+}, '*');
+```
+
+2. **Nexus → Beacon:** Send state on portal load
+```javascript
+// In Nexus portal
+beaconFrame.contentWindow.postMessage({
+  type: 'nexus-load-state',
+  state: savedState
+}, '*');
+```
+
+**Pros:**
+- State persists across sessions
+- Better integration
+
+**Cons:**
+- Requires code changes in both repos
+- More complex
+
+### Option 3: URL Parameters
+Pass initial state via URL parameters:
+```
+https://the-beacon.alexanderwhitestone.com?state=<base64-encoded-state>
+```
+
+**Pros:**
+- Simple, no cross-origin issues
+- Works with any iframe
+
+**Cons:**
+- URL length limits
+- State visible in URL
+- No automatic state saving
+
+## Recommended Approach
+
+**Start with Option 1** (simple iframe embed) to validate the portal works. Then implement Option 2 for state synchronization if needed.
+
+## Testing
+
+### Manual Test
+1. Add portal entry to Nexus portals.json
+2. Open Nexus world
+3. Click The Beacon portal
+4. Verify game loads in iframe
+5. Play game, save progress
+6. Close portal, reopen
+7. Verify state persistence (Option 2 required)
+
+### Automated Test
+```javascript
+// Test iframe loads
+const iframe = document.querySelector('iframe[src*="the-beacon"]');
+assert(iframe !== null, 'Portal iframe exists');
+
+// Test game loads
+iframe.onload = () => {
+  assert(iframe.contentDocument !== null, 'Game loaded');
+};
+```
+
+## Security Considerations
+
+1. **Sandbox Attribute:** Use `sandbox` to restrict iframe capabilities
+2. **Content Security:** The Beacon has no external dependencies except CDN fonts
+3. **Data Privacy:** Game state is stored locally, no server communication
+4. **XSS Protection:** The Beacon doesn't accept user input beyond game clicks
+
+## Related Issues
+
+- **#167:** Nexus portal for The Beacon — playable in-world
+- **#12:** Prestige New Game+ System (affects state persistence)

portal-entry.json

@@ -0,0 +1,20 @@
+{
+  "id": "the-beacon",
+  "name": "The Beacon",
+  "description": "An idle game about building a sovereign AI. Click to code, build, and rescue.",
+  "url": "https://the-beacon.alexanderwhitestone.com",
+  "icon": "\ud83c\udf1f",
+  "category": "games",
+  "tags": [
+    "idle",
+    "game",
+    "sovereign",
+    "ai"
+  ],
+  "iframe": true,
+  "width": 1200,
+  "height": 800,
+  "sandbox": "allow-scripts allow-same-origin allow-forms",
+  "persistence": "localStorage",
+  "stateKey": "the-beacon-v2"
+}