html-portal-generator

# HTML Portal Generator

Convert any codebase into a single, self-contained HTML portal application. The output is one `.html` file with embedded styles, scripts, and data that works offline, on `file://` protocol, and can be uploaded into AI application portals.

## When to Use

- You have a codebase (CLI tool, library, API, framework) and need an interactive HTML representation of its functionality
- The HTML will be uploaded into a smart AI portal or application integration system
- You need all features to work standalone without a running server
- You want users to explore, validate, analyze, and interact with the product from a browser

## Process

Follow these phases in order. Each phase builds on the previous.

### Phase 1: Codebase Analysis

Understand what the product does before writing any HTML.

1. **Read project documentation**: README, CLAUDE.md, architecture docs, changelogs
2. **Identify core crates/packages**: Map each module's purpose and public API
3. **Catalog user-facing features**: CLI commands, API endpoints, configuration options
4. **Extract data structures**: Response types, configuration schemas, enum values
5. **Find existing UI code**: Dashboards, templates, stylesheets (reuse their design language)

Produce a mental inventory:
- Feature list (what the product does)
- Data catalog (what entities/types exist)
- Command/API reference (how users interact)
- Visual identity (colors, fonts, layout patterns from existing UI)

### Phase 2: Reference Analysis (if provided)

If the user provides a reference HTML app:

1. Read the first and last ~3KB to understand structure (large files may be minified)
2. Identify the design pattern: CSS variables, layout system, component structure
3. Note the interaction model: controls bar, status bar, grid layout, tab navigation
4. Extract the color palette and typography from CSS custom properties

### Phase 3: Architecture Design

Design the portal as a single-page app with tab navigation.

**Required structural elements:**
- Sticky header with product name, version badge, and summary stats
- Tab navigation bar for switching between views
- Main container with `max-width` for readability
- Sticky status bar footer with links to docs/repo
- Toast notification system for user feedback

**View planning - map each product feature to a view:**

| Feature Type | View Pattern |
|---|---|
| Entity browsing (skills, packages, endpoints) | Card grid with search/filter/sort + detail panel |
| Validation/checking | Split editor (textarea input) + results panel |
| Analysis/metrics | Input + stat cards + bar charts |
| Configuration/creation | Form inputs + live preview + download |
| Format conversion | Side-by-side input/output with target selector |
| Reference docs (commands, APIs) | Searchable/filterable list with copy-on-click |
| Status/compatibility | Matrix grid or table |
| Dashboard/overview | Stat cards + quick actions + recent items |

**Every view must work 100% standalone.** No external API calls required. Embed demo data. Add optional live-server connection as a bonus.

### Phase 4: Data Embedding

Convert real product data into JavaScript arrays embedded in the HTML.

1. **Scan the actual codebase** for entities (skills, commands, endpoints, types)
2. **Extract metadata** from source files (frontmatter, doc comments, type definitions)
3. **Generate realistic validation states** based on actual product rules
4. **Include failure reasons** as tooltip/detail text so users understand why things pass/fail
5. **Store as `const` arrays** in the `<script>` block - no external JSON files

For large datasets (100+ items), use a build script to extract and format the data rather than hand-writing it.

If the product has local files users might want to scan:
- Add a "Scan Local" button using the File System Access API (`showDirectoryPicker`)
- Walk directories recursively, parse file frontmatter/headers
- Replace the embedded data with live-scanned results
- Store full file content on scanned items for downstream analysis

### Phase 5: Implementation

Build the HTML file following these rules:

**Single-file architecture:**
```
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Product - Portal</title>
  <style>/* All CSS here */</style>
</head>
<body>
  <!-- All HTML here -->
  <script>/* All JS here, wrapped in IIFE */</script>
</body>
</html>
```

**CSS requirements:**
- Use CSS custom properties (`:root { --bg: ...; }`) for theming
- Support dark mode (default) and light mode via `@media (prefers-color-scheme: light)`
- Reuse the product's existing color palette if it has one
- Mobile-responsive with `@media (max-width: ...)` breakpoints
- Style scrollbars, focus states, and transitions

**JavaScript requirements:**
- Wrap everything in an IIFE: `(function() { 'use strict'; ... })();`
- No inline `onclick` handlers - use `addEventListener` exclusively
- Clipboard operations must fall back to `document.execCommand('copy')` for `file://` protocol
- Every click should produce visible feedback (toast, navigation, highlight)
- Autocomplete/datalist for name inputs that reference the embedded data
- Tab navigation via `data-view` attributes and `.active` class toggling

**Interactivity checklist - every element the user can see must do something when clicked:**
- Cards/list items: select, show detail, or navigate
- Buttons: perform action with toast feedback
- Reference items: copy to clipboard on click
- Status indicators: show tooltip with explanation on hover
- External links: open in new tab with `target="_blank" rel="noopener"`
- Quick actions: run in-browser if possible, otherwise copy CLI command + link to docs

### Phase 6: Feature Implementation Patterns

**Entity Browser (the main catalog view):**
```
- Search input (filters by name + description)
- Source/category dropdown filter
- Quality/status dropdown filter
- Sort selector (al