/html-portal-generator

name: html-portal-generator
description: Convert a codebase into a self-contained HTML portal app for ingestion into AI application systems. Produces a single deployable HTML file with embedded CSS, JS, and data.
version: 1.0.0

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 and detail panel | | Validation/checking | Split editor (textarea input) and results panel | | Analysis/metrics | Input, stat cards, and bar charts | | Configuration/creation | Form inputs, live preview, and 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, and 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 comma