CmdForge Web UI Design

Purpose

Deliver a professional web front-end that explains CmdForge, helps users discover tools, and supports a collaborative ecosystem. The site should drive sustainable revenue without undermining trust or usability.

Mission Alignment

This web UI serves the broader CmdForge mission: to provide a universally accessible development ecosystem that empowers regular people to collaborate and build upon each other's progress rather than compete. Revenue generated supports:

Maintaining and expanding the project
Future hosting of AI models for users with less access to paid services
Building a sustainable, community-first platform

The UI design must reflect these values through its structure, content, and monetization approach.

Guiding Principles

Utility first: Documentation, tutorials, and examples are the primary draw.
Trust and clarity: Ads and monetization are transparent, minimal, and never block core flows.
Collaboration over competition: Highlight contributors, shared projects, and community learning.
Performance and accessibility: Fast, readable, WCAG 2.1 AA target.
Unix philosophy: Composable, provider-agnostic, YAML-based tools—the UI should communicate this clearly.

Information Architecture

Public, ad-supported (Tier 1):

/ landing
/docs/* documentation
/tutorials/*
/examples
/blog
/about
/donate

Registry (Tier 2, ad-free):

/tools
/tools/{owner}/{name}
/categories
/categories/{name}
/search

Community (Tier 3, light ads):

/forum
/contributors
/announcements

Publisher dashboard (auth-only):

/register, /login
/dashboard/tools
/dashboard/connections (manage connected apps)
/dashboard/settings

API:

/api/v1/* (shared with CLI)

Visual Design System

Color Palette

Role	Color	Hex	Usage
Primary	Indigo	`#6366F1`	CTAs, active states, brand identity
Secondary	Cyan	`#06B6D4`	Secondary actions, accents, links
Background	Off-white	`#F9FAFB`	Page background
Surface	White	`#FFFFFF`	Cards, content areas
Text Primary	Dark gray	`#1F2937`	Headlines, body text
Text Secondary	Medium gray	`#6B7280`	Descriptions, metadata
Text Muted	Light gray	`#9CA3AF`	Timestamps, hints
Border	Light gray	`#E5E7EB`	Card borders, dividers
Success	Green	`#10B981`	Success states, confirmations
Warning	Amber	`#F59E0B`	Warnings, deprecation notices
Error	Red	`#EF4444`	Error states, critical alerts
Header	Dark slate	`#2C3E50`	Header background
Ad Container	Light blue	`#DBEAFE`	Ad zone background (distinct from content)
Sponsored	Light amber	`#FEF3C7`	Sponsored content background

Contrast Requirements:

Body text: minimum 4.5:1 ratio (WCAG AA)
Large text (18px+): minimum 3:1 ratio
UI components: minimum 3:1 ratio against adjacent colors

Typography

Element	Font	Size	Weight	Line Height
H1	Inter/system-ui	36px (2.25rem)	700	1.2
H2	Inter/system-ui	24px (1.5rem)	700	1.3
H3	Inter/system-ui	20px (1.25rem)	600	1.4
H4	Inter/system-ui	18px (1.125rem)	600	1.4
Body	Inter/system-ui	16px (1rem)	400	1.6
Small	Inter/system-ui	14px (0.875rem)	400	1.5
Code	JetBrains Mono/monospace	14px	400	1.5
Code block	JetBrains Mono/monospace	13px	400	1.6

Font Stack:

--font-sans: 'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif;
--font-mono: 'JetBrains Mono', ui-monospace, 'Cascadia Code', monospace;

Spacing System

Use an 8px base grid for consistent spacing:

Token	Value	Usage
`--space-1`	4px	Tight spacing, icon margins
`--space-2`	8px	Element gaps
`--space-3`	12px	Small component padding
`--space-4`	16px	Card padding, section gaps
`--space-6`	24px	Section padding
`--space-8`	32px	Large gaps
`--space-12`	48px	Section margins
`--space-16`	64px	Major section separators

Border Radius

Token	Value	Usage
`--radius-sm`	4px	Buttons, badges
`--radius-md`	8px	Cards, inputs
`--radius-lg`	12px	Modals, large cards
`--radius-full`	9999px	Avatars, pills

Shadow System

--shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
--shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1);
--shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1);
--shadow-hover: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1);

Page Requirements

Landing Page (`/`)

Purpose: Convert visitors to users by clearly communicating CmdForge' value proposition and providing immediate paths to explore.

Reference mockup: discussions/diagrams/cmdforge-registry_rob_6.svg

Section 1: Hero (Above the Fold)

┌─────────────────────────────────────────────────────────────────┐
│  [CmdForge]  Docs  Tutorials  Registry  Community  About  🔍  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│    Build Custom AI Commands in YAML                              │
│    ─────────────────────────────────────────────────────────    │
│    Create Unix-style pipeable tools that work with any AI       │
│    provider. Provider-agnostic and composable.                   │
│                                                                  │
│    ┌──────────────────────────────────────────────────────┐     │
│    │ $ pip install cmdforge && cmdforge init          │ [📋]│
│    └──────────────────────────────────────────────────────┘     │
│                                                                  │
│    [Get Started]  [View Tutorials]                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Content:

Headline: "Build Custom AI Commands in YAML" (benefit-focused, differentiating)
Subheadline: "Create Unix-style pipeable tools that work with any AI provider. Provider-agnostic and composable for ultimate flexibility."
Install snippet: pip install cmdforge && cmdforge init with copy button
Primary CTA: "Get Started" → links to /docs/getting-started (indigo background)
Secondary CTA: "View Tutorials" → links to /tutorials (outlined, cyan border)

Design Notes:

Hero background: white card (#FFFFFF) with subtle shadow on off-white page
Maximum content width: 1100px centered
Install snippet: monospace font, light gray background (#E0E0E0), copy icon on right

Section 2: Three Pillars (Why CmdForge?)

┌─────────────────────────────────────────────────────────────────┐
│  Why CmdForge?                                                 │
├──────────────────┬──────────────────┬────────────────────────────┤
│   [✓] Easy       │   [⚡] Powerful   │   [👥] Community           │
│                  │                  │                            │
│   Simple YAML    │   Any AI         │   Share, discover,         │
│   configuration  │   provider,      │   contribute to a          │
│   for quick      │   compose        │   growing ecosystem.       │
│   setup.         │   complex        │                            │
│                  │   workflows.     │                            │
└──────────────────┴──────────────────┴────────────────────────────┘

Content:

Pillar 1 - Easy to Use: Icon in indigo circle, "Simple YAML configuration for quick setup."
Pillar 2 - Powerful: Icon in cyan circle, "Leverage any AI provider, compose complex workflows."
Pillar 3 - Community: Icon in indigo circle, "Share, discover, and contribute to a growing ecosystem."

Design Notes:

Each pillar: white card with 1px border, subtle shadow on hover
Icon circles: 40px diameter with pillar icon centered
Equal width columns (3 across on desktop)

Section 3: Featured Tools & Projects

┌─────────────────────────────────────────────────────────────────┐
│  Featured Tools & Projects                                       │
├──────────────────┬──────────────────┬────────────────────────────┤
│  [Category]      │  [Category]      │  [Category]                │
│  ● Tool Title    │  ● Tool Title    │  ● Tool Title              │
│  Description...  │  Description...  │  Description...            │
│  Author: name    │  Author: name    │  Author: name              │
│  Downloads: 1.2K │  Downloads: 800  │  Downloads: 2.5K           │
│  ┌────────────┐  │  ┌────────────┐  │  ┌────────────┐            │
│  │run command │  │  │run command │  │  │run command │            │
│  └────────────┘  │  └────────────┘  │  └────────────┘            │
├──────────────────┼──────────────────┼────────────────────────────┤
│  [Row 2...]      │  [Row 2...]      │  [Row 2...]                │
└──────────────────┴──────────────────┴────────────────────────────┘

Content (per card):

Category badge (top-right, cyan pill)
Tool icon/avatar (indigo circle)
Tool name (bold, 18px)
Short description (14px, secondary text)
Author attribution
Download count with icon
One-line install command in code box

Data Source: GET /api/v1/tools?sort=downloads&limit=6

Design Notes:

3 columns on desktop, 2 on tablet, 1 on mobile
Cards have subtle shadow, lift on hover
"View All Tools" link below grid → /tools

Section 4: Getting Started

┌─────────────────────────────────────────────────────────────────┐
│  Getting Started                                                 │
├──────────────────┬──────────────────┬────────────────────────────┤
│  Tutorial 1:     │  Tutorial 2:     │  Tutorial 3:               │
│  Basic Setup     │  Your First Tool │  Advanced Workflows        │
│  Learn how to... │  Create a        │  Combine multiple          │
│                  │  simple AI...    │  tools for...              │
│  [Read More]     │  [Read More]     │  [Read More]               │
└──────────────────┴──────────────────┴────────────────────────────┘

Content:

3 tutorial cards highlighting core learning paths
Each card: title (bold), description (2 lines max), CTA button

Design Notes:

Matches tool card styling for visual consistency
"Read More" buttons in primary indigo

Section 5: Featured Contributor

┌─────────────────────────────────────────────────────────────────┐
│  Featured Contributor                                            │
├─────────────────────────────────────────────────────────────────┤
│  [Avatar]  Name Here                                             │
│            Creator of "Tool Name" and active community member.   │
│            [View Profile]                                        │
└─────────────────────────────────────────────────────────────────┘

Content:

Monthly rotating spotlight
Avatar (60px circle), name, brief bio, profile link

Data Source: Manual curation or GET /api/v1/contributors/featured

┌─────────────────────────────────────────────────────────────────┐
│  [Advertisement: Support CmdForge Development]                 │
└─────────────────────────────────────────────────────────────────┘

Design Notes:

Light blue background (#DBEAFE) to distinguish from content
Clearly labeled as advertisement
Optional based on ad fill rate

┌─────────────────────────────────────────────────────────────────┐
│  CmdForge                                                      │
│  ─────────────────────────────────────────────────────────────  │
│  Docs  |  Registry  |  Community  |  About  |  Donate           │
│  Privacy  |  Terms  |  GitHub  |  Twitter                        │
│                                                                  │
│  © 2025 CmdForge. Open source under MIT License.              │
└─────────────────────────────────────────────────────────────────┘

Docs/Tutorials Pages (`/docs/`, `/tutorials/`)

Layout:

┌───────────────────────────────────────────────────────────────────────┐
│  [Header Navigation]                                                   │
├──────────────┬────────────────────────────────────────────┬───────────┤
│  TOC         │  Content Area (70%)                        │  Sidebar  │
│  (Desktop)   │                                            │  (Ads)    │
│              │  # Page Title                              │           │
│  - Section 1 │                                            │  [Ad]     │
│  - Section 2 │  Content with code blocks...               │           │
│  - Section 3 │                                            │           │
│              │  ```python                                 │           │
│              │  # Code with syntax highlighting           │           │
│              │  ```                           [Copy]      │           │
│              │                                            │           │
│              │  [Embedded Video]                          │           │
│              │                                            │           │
└──────────────┴────────────────────────────────────────────┴───────────┘

Content Requirements:

Persistent left TOC on desktop (scroll-spy highlighting current section)
Code blocks with syntax highlighting and copy button
Video embeds (YouTube) with play button overlay, lazy-loaded
Callout boxes for tips, warnings, info (color-coded)
Related articles at bottom

Design Notes:

TOC: fixed on scroll, 200px width
Content area: max-width 700px, generous line-height (1.6-1.8)
Sidebar ads: 300px width, only on desktop
Mobile: TOC collapses to hamburger, sidebar hidden

Tool Detail Page (`/tools/{owner}/{name}`)

Layout:

┌───────────────────────────────────────────────────────────────────────┐
│  [Header Navigation]                                                   │
├─────────────────────────────────────────────────────┬─────────────────┤
│  README Content (70%)                                │  Sidebar (30%) │
│                                                      │                │
│  # tool-name                                         │  ┌───────────┐ │
│                                                      │  │Install    │ │
│  Rendered markdown from README.md...                 │  │           │ │
│                                                      │  │$ run cmd  │ │
│  - Usage examples                                    │  └───────────┘ │
│  - Configuration                                     │                │
│  - Step definitions                                  │  Versions:     │
│                                                      │  v1.2.0 ●      │
│                                                      │  v1.1.0        │
│                                                      │  v1.0.0        │
│                                                      │                │
│                                                      │  Downloads:    │
│                                                      │  1,234         │
│                                                      │                │
│                                                      │  Category:     │
│                                                      │  [text-proc]   │
│                                                      │                │
│                                                      │  Tags:         │
│                                                      │  [ai] [cli]    │
│                                                      │                │
│                                                      │  [Report]      │
└─────────────────────────────────────────────────────┴─────────────────┘

Sidebar Elements:

Install command with copy button (prominent)
Version selector/list (current version highlighted)
Download statistics
Category badge (linked)
Tags (linked to search)
Report abuse button
Publisher info (avatar, name, link to profile)

NO ADS on tool detail pages (Tier 2 - registry is ad-free)

Registry Browse Page (`/tools`)

Layout:

┌───────────────────────────────────────────────────────────────────────┐
│  [Header Navigation]                                                   │
├───────────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │ 🔍 Search tools...                    [Category ▼] [Sort ▼]     │  │
│  └─────────────────────────────────────────────────────────────────┘  │
├───────────────────────────────────────────────────────────────────────┤
│  Showing 142 tools                                                    │
├──────────────────┬──────────────────┬──────────────────┬──────────────┤
│  [Tool Card]     │  [Tool Card]     │  [Tool Card]     │  [Tool Card] │
│                  │                  │                  │              │
├──────────────────┼──────────────────┼──────────────────┼──────────────┤
│  [Tool Card]     │  [Tool Card]     │  [Tool Card]     │  [Tool Card] │
│                  │                  │                  │              │
├───────────────────────────────────────────────────────────────────────┤
│  [← Previous]  Page 1 of 8  [Next →]                                  │
└───────────────────────────────────────────────────────────────────────┘

Search/Filter Features:

Full-text search with debounce (300ms)
Category dropdown filter
Sort options: Popular (downloads), Recent, Name
Results count display
Pagination (20 per page)

Tool Card (compact):

Tool name + owner
Short description (2 lines max, truncated)
Download count
Last updated date
Category tag

NO ADS on browse pages (Tier 2)

Publisher Dashboard (`/dashboard`)

Layout:

┌───────────────────────────────────────────────────────────────────────┐
│  [Header with user menu]                                               │
├─────────────────┬─────────────────────────────────────────────────────┤
│  Sidebar        │  Content Area                                       │
│                 │                                                      │
│  Overview       │  ┌─ Tab: My Tools ──────────────────────────────┐   │
│  My Tools       │  │                                              │   │
│  Connections    │  │  Published Tools (3)          [+ New Tool]   │   │
│  Settings       │  │  ┌─────────────────────────────────────────┐ │   │
│                 │  │  │ summarize v1.2.0  |  142 downloads      │ │   │
│                 │  │  │ [Edit] [View] [Yank]                    │ │   │
│                 │  │  └─────────────────────────────────────────┘ │   │
│                 │  │                                              │   │
│                 │  │  Pending PRs (1)                             │   │
│                 │  │  ┌─────────────────────────────────────────┐ │   │
│                 │  │  │ new-tool v1.0.0  |  Awaiting review     │ │   │
│                 │  │  │ [View PR]                               │ │   │
│                 │  │  └─────────────────────────────────────────┘ │   │
│                 │  └──────────────────────────────────────────────┘   │
└─────────────────┴─────────────────────────────────────────────────────┘

Tabs:

Overview: Dashboard with stats (tools count, downloads, connections)
My Tools: List of published tools with stats, edit/view/yank actions
Connections: Manage connected apps (CLI/TUI instances linked to account)
Settings: Profile editing (display name, bio, website), password change

Connections Page:

The Connections page (/dashboard/connections) replaces the old API Tokens page with a simpler app pairing flow:

Connect New App: Button opens modal with pairing instructions
1. Shows command: cmdforge config connect <username>
2. Or use the TUI: open cmdforge ui and click Connect
3. "I've Run the Command" button shows pending connections
4. Approve pending connection with one click
Connected Apps: List of connected devices showing:
- Device hostname
- Connection date
- Last used timestamp
- Disconnect button to revoke access

This eliminates the need to manually copy API tokens - users just approve connections from the web UI.

Design Notes:

Clean, utilitarian design
Clear action buttons
Status indicators for pending PRs
Pairing modal guides users through connection flow

Donate Page (`/donate`)

Content:

Mission statement (emotional, connecting to values)
Clear explanation of fund usage (hosting, development, future AI hosting)
Multiple donation options (GitHub Sponsors, PayPal, Ko-fi)
Optional donor recognition section
Transparency about current costs/goals

Design Notes:

Clean, trustworthy design
Clear CTAs for each donation method
No ads on this page

Component Library

Buttons

Primary Button:

<button class="btn-primary">Get Started</button>

Background: Primary indigo (#6366F1)
Text: White, 16px, font-weight 600
Padding: 12px 24px
Border-radius: 4px
Hover: Darken 10%, subtle shadow
Focus: 2px outline offset

Secondary Button:

<button class="btn-secondary">View Tutorials</button>

Background: Transparent
Border: 2px solid cyan (#06B6D4)
Text: Cyan, 16px, font-weight 600
Hover: Light cyan background (#ECFEFF)

Ghost Button:

<button class="btn-ghost">Read More</button>

Background: Transparent
Text: Primary indigo
Hover: Light indigo background

Danger Button:

<button class="btn-danger">Revoke Token</button>

Background: Error red (#EF4444)
Text: White
Used for destructive actions

Cards

Tool Card:

┌───────────────────────────────────────┐
│                          [Category]   │
│  [●] Tool Name                        │
│  Short description of the tool that   │
│  may span two lines maximum...        │
│                                       │
│  Author: owner-name                   │
│  ⬇ 1,234 downloads                    │
│                                       │
│  ┌─────────────────────────────────┐  │
│  │ cmdforge run owner/tool       │  │
│  └─────────────────────────────────┘  │
└───────────────────────────────────────┘

Background: White (#FFFFFF)
Border: 1px solid border color (#E5E7EB)
Border-radius: 8px
Shadow: shadow-sm, shadow-md on hover
Padding: 16px
Category badge: absolute top-right, cyan background, white text, 12px

Tutorial Card:

┌───────────────────────────────────────┐
│  [Optional Thumbnail Image]           │
│                                       │
│  Tutorial Title Here                  │
│  Brief description of what the        │
│  tutorial covers...                   │
│                                       │
│  [Read More →]                        │
└───────────────────────────────────────┘

Same base styling as tool card
Optional thumbnail: aspect-ratio 16:9, lazy-loaded

Contributor Card:

┌───────────────────────────────────────┐
│  [Avatar]  Contributor Name           │
│            @github-handle             │
│            Creator of "Tool Name"     │
│            [View Profile]             │
└───────────────────────────────────────┘

Avatar: 48px circle
Horizontal layout for spotlight, vertical for grid

Header Navigation:

┌─────────────────────────────────────────────────────────────────────────┐
│  [Logo]           [Docs] [Tutorials] [Registry] [Community] [About]  🔍  │
│                                                              [Donate]   │
└─────────────────────────────────────────────────────────────────────────┘

Background: Dark slate (#2C3E50)
Logo: White text, 24px, bold
Nav links: White text, 16px
Active/hover: Underline or slight background
Mobile: Hamburger menu with slide-out drawer

Breadcrumbs:

Registry > owner > tool-name > v1.2.0

Separator: > or /
Current page: bold, not linked
Previous pages: linked, secondary color

Form Elements

Text Input:

<input type="text" class="input" placeholder="Search tools...">

Border: 1px solid border color
Border-radius: 8px
Padding: 12px 16px
Focus: Primary indigo border, subtle shadow
Height: 44px (touch target compliance)

Search Input with Icon:

┌─────────────────────────────────────┐
│ 🔍 Search tools...                  │
└─────────────────────────────────────┘

Icon: Left-aligned, muted color
Placeholder: Secondary text color

Select/Dropdown:

┌─────────────────────────────────────┐
│ Category                          ▼ │
└─────────────────────────────────────┘

Same styling as text input
Chevron icon on right

Badges and Tags

Category Badge:

<span class="badge badge-category">text-processing</span>

Background: Cyan (#06B6D4)
Text: White, 12px
Padding: 4px 8px
Border-radius: 4px

Tag:

<span class="tag">ai</span>

Background: Light gray (#F3F4F6)
Text: Secondary gray, 12px
Border: 1px solid border color
Border-radius: 9999px (pill)
Clickable (links to search)

Status Badge:

<span class="badge badge-success">Published</span>
<span class="badge badge-warning">Pending</span>
<span class="badge badge-error">Yanked</span>

Success: Green background
Warning: Amber background
Error: Red background

Code Blocks

Inline Code:

<code>cmdforge run foo</code>

Background: Light gray (#F3F4F6)
Font: Monospace
Padding: 2px 6px
Border-radius: 4px

Code Block with Copy:

┌───────────────────────────────────────────────────────┐
│ ```python                                        [📋] │
│ def hello():                                          │
│     print("Hello, World!")                            │
│ ```                                                   │
└───────────────────────────────────────────────────────┘

Background: Dark (#1F2937) or light (#F9FAFB)
Syntax highlighting (Prism.js or Highlight.js)
Copy button: top-right, appears on hover
Line numbers: optional, enabled for tutorials

Callout Boxes

Info Callout:

┌─────────────────────────────────────────────────────┐
│ ℹ️ Note                                              │
│ This is helpful information for the user.           │
└─────────────────────────────────────────────────────┘

Background: Light blue (#DBEAFE)
Border-left: 4px solid blue (#3B82F6)

Warning Callout:

┌─────────────────────────────────────────────────────┐
│ ⚠️ Warning                                           │
│ Be careful with this configuration.                 │
└─────────────────────────────────────────────────────┘

Background: Light amber (#FEF3C7)
Border-left: 4px solid amber (#F59E0B)

Error Callout:

┌─────────────────────────────────────────────────────┐
│ ❌ Important                                         │
│ This action cannot be undone.                       │
└─────────────────────────────────────────────────────┘

Background: Light red (#FEE2E2)
Border-left: 4px solid red (#EF4444)

Tip Callout:

┌─────────────────────────────────────────────────────┐
│ 💡 Tip                                               │
│ You can also use this shortcut...                   │
└─────────────────────────────────────────────────────┘

Background: Light green (#D1FAE5)
Border-left: 4px solid green (#10B981)

Loading States

Skeleton Loader:

┌───────────────────────────────────────┐
│  ████████████████                     │
│  ████████████████████████████████     │
│  ████████████                         │
└───────────────────────────────────────┘

Animated shimmer effect
Matches component dimensions
Used for cards, text blocks

Spinner:

Circular spinner for buttons, inline loading
Primary indigo color
Size: 16px (small), 24px (medium), 32px (large)

Progress Bar:

Used for multi-step operations
Shows percentage or step count

Responsive Design

Breakpoints

Breakpoint	Width	Name	Grid Columns
xs	< 480px	Extra small phones	1
sm	480-639px	Phones	1
md	640-767px	Large phones / small tablets	2
lg	768-1023px	Tablets	2-3
xl	1024-1279px	Small desktops	3-4
2xl	≥ 1280px	Large desktops	4

Layout Adaptations

Mobile (< 640px):

Single-column layout
Navigation: hamburger menu with slide-out drawer
Hero: stacked content, centered
Tool cards: full-width, stacked
TOC: collapsible accordion at top of page
Sidebar ads: hidden
Footer ads: optional, minimal

Tablet (640-1023px):

Two-column grid for cards
Navigation: horizontal but condensed
TOC: collapsible sidebar
Sidebar ads: may show below content

Desktop (≥ 1024px):

Full multi-column layout
Navigation: full horizontal with all links visible
TOC: fixed left sidebar
Sidebar ads: visible in right column
Maximum content width: 1280px with centered container

Touch Targets

All interactive elements must meet minimum touch target size:

Minimum size: 44×44px (WCAG 2.1 AA)
Spacing between targets: minimum 8px
Applies to: buttons, links, form inputs, navigation items

Mobile-Specific Considerations

No horizontal scrolling
Images: responsive with max-width: 100%
Tables: horizontal scroll wrapper on small screens
Code blocks: horizontal scroll with visible scrollbar
Modals: full-screen on mobile, centered on desktop
Keyboard: virtual keyboard should not obscure inputs

Performance Budgets

Core Web Vitals Targets

Metric	Target	Maximum
Largest Contentful Paint (LCP)	< 1.5s	< 2.5s
First Input Delay (FID)	< 50ms	< 100ms
Cumulative Layout Shift (CLS)	< 0.05	< 0.1
First Contentful Paint (FCP)	< 1.0s	< 1.8s
Time to Interactive (TTI)	< 2.5s	< 3.5s

Resource Budgets

Resource	Budget	Notes
Total page weight	< 500KB	Excluding ads
JavaScript (compressed)	< 100KB	Main bundle
CSS (compressed)	< 50KB	Main stylesheet
Images (above fold)	< 200KB	Hero, featured tools
Fonts	< 100KB	Subset, WOFF2 format
Third-party scripts	< 150KB	Analytics, ads (lazy)

Loading Strategy

Critical Path (synchronous):

HTML document
Critical CSS (inlined in <head>)
Above-the-fold content

Deferred Loading:

Non-critical CSS (preload, async)
JavaScript (defer)
Below-fold images (lazy-load with loading="lazy")
Third-party scripts (ads, analytics)
Video embeds (lazy, placeholder until visible)

Caching Strategy

Resource	Cache-Control	Notes
Static assets (CSS, JS)	`max-age=31536000, immutable`	Hashed filenames
Images	`max-age=86400`	1 day
HTML pages	`max-age=300, stale-while-revalidate=60`	5 min, background refresh
API responses	`max-age=60`	1 min for tool lists
Tool downloads	`max-age=3600, immutable`	Immutable versions

Performance Monitoring

Monitor Core Web Vitals in production
Set up alerts for degradation (>10% threshold)
Track page load times by route
Monitor JavaScript error rates

Error States and Fallbacks

Network Errors

API Unavailable:

┌─────────────────────────────────────────────────────┐
│  ⚠️ Registry Temporarily Unavailable                 │
│                                                      │
│  We're having trouble connecting to the registry.   │
│  Please try again in a few moments.                 │
│                                                      │
│  [Retry]                                             │
└─────────────────────────────────────────────────────┘

Slow Connection:

Show skeleton loaders for content
Progressive loading with visible feedback
Timeout after 10 seconds with retry option

Tool Not Found (404):

┌─────────────────────────────────────────────────────┐
│  Tool Not Found                                      │
│                                                      │
│  The tool "owner/tool-name" doesn't exist or may    │
│  have been removed.                                  │
│                                                      │
│  [Browse Tools]  [Search Registry]                   │
└─────────────────────────────────────────────────────┘

Search No Results:

┌─────────────────────────────────────────────────────┐
│  No tools found for "query"                          │
│                                                      │
│  Suggestions:                                        │
│  • Try different keywords                            │
│  • Check spelling                                    │
│  • Browse by category                                │
│                                                      │
│  [Browse All Tools]                                  │
└─────────────────────────────────────────────────────┘

Offline Mode

If service worker is implemented:

Show cached pages when offline
Indicate offline status in header
Queue actions (report, install) for when online

Form Errors

Inline Validation:

Show error message below field
Red border on invalid fields
Error icon in field

Form Submission Error:

Toast notification for transient errors
Inline error summary for validation failures
Preserve form state on error

Ad and Revenue Strategy

Ad placement: One sidebar unit on long-form docs/tut pages, optional footer banner on landing, none on registry pages.
No ads in install flows, login/registration, or tool browsing details.
Sponsored content: Clearly labeled and separated from organic rankings.
YouTube: Embed tutorials with transcripts; also drive to channel.

Monetization Extensions (Optional)

Donations: Single page with clear use-of-funds.
Featured projects: Curated or sponsored slots with explicit labeling.
Premium publisher tier: More tools, enhanced analytics, priority review.
Training/consulting: Workshops or enterprise onboarding.

Data and Governance

Proposed minimal tables (web-only):

promotions (featured tools/projects, start/end, placement, audit).
featured_projects (title, description, owner, url, status).
content_pages (docs/tutorials metadata for listing).
announcements (title, body, published_at).

Roles and permissions:

admin: can publish announcements, manage promotions, moderate reports.
editor: can create/update docs, tutorials, featured projects.
publisher: can manage their own tools and profile only.
contributor: can partisipate in discussions in the forums.

Audit fields (required on content tables):

created_by, updated_by, created_at, updated_at.

Ranking rules:

Organic search uses relevance and downloads.
Sponsored placements appear in dedicated sections and do not alter organic order.

Promotions placement rules:

Slots are deterministic (e.g., positions 1 and 5 in lists).
Promotions are clearly labeled and never mixed into organic ranking.
promotions includes placement, priority, start_at, end_at, status.

Consent banner for analytics/ads.
Minimal tracking, anonymized IPs.
Clear privacy policy and retention policy.

Consent storage:

Store a consents record keyed by client_id (anonymous) or user id (logged-in).
Respect opt-outs by disabling analytics/ads on server-rendered pages.

UX and Accessibility

Keyboard navigation for all interactive elements.
High contrast and readable typography.
Mobile-first layout; ads hidden on mobile except optional footer.
Avoid popups and auto-play media.

Responsive breakpoints (baseline):

Mobile: <640px
Tablet: 640–1024px
Desktop: >1024px

Tech Stack (Phase 7 Target)

Flask + Jinja + Tailwind for SEO-friendly server-rendered pages.
Optional htmx or Alpine.js for small interactivity.
Shared registry API for data.

Auth and Session Model

Server-side sessions (DB-backed) for dashboard views.
Cookies: HttpOnly, SameSite=Lax, Secure in production.
CSRF protection on all POST/PUT/DELETE web forms.
Session TTL: 7 days with rotation on login.
Logout invalidates session server-side.

API Surfaces for Web UI

Read-only UI calls should use the existing API:

/api/v1/tools, /api/v1/tools/search, /api/v1/categories, /api/v1/stats/popular.

Publisher dashboard uses auth endpoints:

/api/v1/login, /api/v1/tokens, /api/v1/me/tools.

Payments and Donations (Optional)

Decide early on a processor (Stripe, Ko-fi, paypal, bitcoin/crypto) to avoid churn.
Webhook handling must verify signatures and enforce idempotency keys.
Store donation/subscription state with status, amount, currency, provider_id, created_at.

Moderation and Abuse Reporting

Tool detail pages require a minimal abuse report endpoint.
Create reports table with tool_id, reporter, reason, status.
Add rate limit to the report endpoint to prevent spam.

Media and Asset Handling

Images/screenshots stored in object storage (preferred) or a dedicated assets/ bucket.
Enforce size limits and content-type validation.
Generate thumbnails for cards and lazy-load in UI.

Caching and SEO Serving

Public pages include ETag/Last-Modified for CDN caching.
Dashboard pages are non-cacheable and user-specific.
Avoid cache poisoning by varying on auth cookies.

SEO Strategy

Technical SEO

URL Structure:

/                           # Landing page
/tools                      # Registry browse
/tools/{owner}/{name}       # Tool detail (canonical)
/tools/{owner}/{name}/v/1.0 # Specific version
/categories/{slug}          # Category listing
/docs/{section}/{page}      # Documentation
/tutorials/{slug}           # Tutorial pages

Meta Tags (per page type):

Landing page:

<title>CmdForge - Build Custom AI Commands in YAML</title>
<meta name="description" content="Create Unix-style pipeable tools that work with any AI provider. Provider-agnostic, composable, and community-driven.">
<meta name="keywords" content="ai cli tools, yaml automation, ai commands, cmdforge">

Tool detail page:

<title>{tool-name} by {owner} - CmdForge Registry</title>
<meta name="description" content="{tool description, max 160 chars}">

Structured Data (Schema.org)

SoftwareApplication (for tools):

{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "summarize",
  "applicationCategory": "DeveloperApplication",
  "operatingSystem": "Linux, macOS, Windows",
  "author": {
    "@type": "Person",
    "name": "owner-name"
  },
  "downloadUrl": "https://cmdforge.brrd.tech/tools/owner/summarize",
  "softwareVersion": "1.2.0",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "ratingCount": "142"
  }
}

Organization (site-wide):

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "CmdForge",
  "url": "https://cmdforge.dev",
  "logo": "https://cmdforge.dev/logo.png",
  "sameAs": [
    "https://github.com/your-org/cmdforge",
    "https://twitter.com/cmdforge"
  ]
}

Article (for tutorials/blog):

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Getting Started with CmdForge",
  "author": {"@type": "Person", "name": "Author Name"},
  "datePublished": "2025-01-15",
  "dateModified": "2025-01-20"
}

<!-- Open Graph -->
<meta property="og:title" content="CmdForge - AI CLI Tools">
<meta property="og:description" content="Build custom AI commands...">
<meta property="og:image" content="https://cmdforge.dev/og-image.png">
<meta property="og:url" content="https://cmdforge.dev">
<meta property="og:type" content="website">

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@cmdforge">
<meta name="twitter:title" content="CmdForge">
<meta name="twitter:description" content="Build custom AI commands...">
<meta name="twitter:image" content="https://cmdforge.dev/twitter-card.png">

Sitemap

Auto-generate sitemap.xml:

All public pages
Tool detail pages (updated on publish)
Category pages
Documentation pages
Priority based on page importance

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://cmdforge.dev/</loc>
    <priority>1.0</priority>
    <changefreq>daily</changefreq>
  </url>
  <url>
    <loc>https://cmdforge.dev/tools</loc>
    <priority>0.9</priority>
    <changefreq>daily</changefreq>
  </url>
  <!-- Tool pages, docs, etc. -->
</urlset>

robots.txt

User-agent: *
Allow: /

# Block auth pages from indexing
Disallow: /login
Disallow: /register
Disallow: /dashboard
Disallow: /api/

Sitemap: https://cmdforge.dev/sitemap.xml

Canonical URLs

Each page has a single canonical URL
Use <link rel="canonical" href="..."> tag
Avoid duplicate content issues
Tool versions link to latest as canonical

Performance for SEO

Server-side rendering for all public pages (Flask + Jinja)
No JavaScript required for content visibility
Fast TTFB (< 200ms target)
Mobile-friendly (responsive design)
Core Web Vitals in "good" range

Content Strategy

Core tutorials that mirror CLI workflows.
"Project spotlights" to showcase real usage.
Contributor recognition (monthly spotlight).
Announcements and changelog summaries.
Encourage AI parsing to increase adsense revenue.

Risks and Mitigations

Ad overload: strict placement rules, no ads in registry.
Moderation burden and load: Implement AI enabled moderation with flags to alert human intervention to keep things moving and simplefy maintenence.
Content drift: quarterly doc reviews tied to releases.
Consent and tracking: default to privacy-preserving settings.

Phase 7 Implementation Checklist

7.1 Foundation & Setup

Set up Flask project structure with blueprints
Configure Jinja2 templates with base layout
Integrate Tailwind CSS (build pipeline)
Set up static asset handling (CSS, JS, images)
Configure development/production environments
Set up database models for web-specific tables

7.2 Core Templates & Components

Create base template with header/footer
Implement navigation component (desktop + mobile)
Build reusable card components (tool, tutorial, contributor)
Create form components (inputs, buttons, dropdowns)
Implement callout/alert components
Build code block component with copy functionality
Create loading states (skeleton, spinner)
Implement responsive grid system

7.3 Landing Page

Hero section with install snippet
Three pillars section (Easy, Powerful, Community)
Featured tools grid (API integration)
Getting started tutorial cards
Featured contributor spotlight
Footer with links and optional ad zone

7.4 Registry Pages (Ad-Free)

7.5 Documentation & Tutorials

Docs landing page with section links
Tutorial listing page
Content page template with TOC
Scroll-spy for TOC highlighting
Code syntax highlighting (Prism/Highlight.js)
Video embed component (YouTube)
Related articles section
Sidebar ad placement (desktop only)

7.6 Authentication & Dashboard

Registration page and flow
Login page with error handling
Password reset flow (if implementing)
Session management (cookies, CSRF)
Dashboard layout with sidebar
My Tools tab with tool list
Connections tab with app pairing flow
Settings tab with profile edit
Logout functionality

7.8 Ads & Monetization

AdSense integration (account setup)
Ad container components
Lazy loading for ad scripts
Ad placement rules enforcement
Sponsored content styling (if applicable)
Donate page with donation options

7.9 SEO & Performance

7.10 Testing & QA

Responsive design testing (all breakpoints)
Accessibility testing (WCAG 2.1 AA)
Cross-browser testing (Chrome, Firefox, Safari, Edge)
Performance testing (Lighthouse scores)
Form validation testing
Error state testing
Mobile usability testing

7.11 Launch Preparation

Content creation (initial docs, tutorials)
Seed featured tools selection
Initial contributor spotlight
Analytics setup (privacy-respecting)
Error monitoring (Sentry or similar)
SSL certificate configuration
CDN setup (optional)
Backup and recovery procedures

API Endpoints for Web UI

The web UI consumes these existing API endpoints:

Public (read-only):

GET /api/v1/tools - List tools with pagination/filters
GET /api/v1/tools/search?q=... - Search tools
GET /api/v1/tools/{owner}/{name} - Tool details
GET /api/v1/tools/{owner}/{name}/versions - Version list
GET /api/v1/categories - Category list
GET /api/v1/stats/popular - Popular tools

Authenticated (dashboard):

POST /api/v1/login - User login (returns session)
POST /api/v1/register - User registration
GET /api/v1/me/tools - User's published tools
GET /api/v1/pairing/connected-apps - List connected apps
POST /api/v1/pairing/initiate - Start app pairing flow
GET /api/v1/pairing/status - Get pending pairing requests
POST /api/v1/pairing/claim/{pairing_id} - Approve a pending connection
DELETE /api/v1/tokens/{id} - Disconnect/revoke an app
PUT /api/v1/me/settings - Update profile

New endpoints for web UI:

GET /api/v1/featured/tools - Curated featured tools
GET /api/v1/featured/contributors - Featured contributor
GET /api/v1/content/announcements - Site announcements
POST /api/v1/reports - Abuse report submission

Diagram References

Landing page mockup: discussions/diagrams/cmdforge-registry_rob_6.svg
System overview: discussions/diagrams/cmdforge-registry_rob_1.puml
Data flows: discussions/diagrams/cmdforge-registry_rob_5.puml
Web UI strategy: discussions/diagrams/cmdforge-web-ui-strategy.puml
UI visual strategy: discussions/diagrams/cmdforge-web-ui-visual-strategy.puml

Deployment Guide

Requirements

Python 3.11+
pip/virtualenv
SQLite 3 (included with Python)

Quick Start (Development)

# Clone the repository
git clone https://gitea.brrd.tech/rob/CmdForge.git
cd CmdForge

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install with registry extras
pip install -e ".[registry]"

# Run the web server
python -m cmdforge.web.app

The server will start on http://localhost:5000.

Production Deployment

1. Environment Variables

# Required
export CMDFORGE_REGISTRY_DB=/path/to/registry.db
export PORT=5050

# Optional
export CMDFORGE_ENV=production  # Enables secure cookies
export CMDFORGE_SHOW_ADS=true   # Enable ad placeholders

2. Database Location

By default, the registry uses ~/.cmdforge/registry.db. For production:

# Create dedicated directory
mkdir -p /var/lib/cmdforge
export CMDFORGE_REGISTRY_DB=/var/lib/cmdforge/registry.db

Note: If using a merged filesystem (e.g., mergerfs), store the database on a single disk or in /tmp to avoid SQLite WAL mode issues:

export CMDFORGE_REGISTRY_DB=/tmp/cmdforge-registry/registry.db

3. Running with systemd

Create /etc/systemd/system/cmdforge-registry.service:

[Unit]
Description=CmdForge Registry Web Server
After=network.target

[Service]
Type=simple
User=cmdforge
WorkingDirectory=/opt/cmdforge
Environment=CMDFORGE_REGISTRY_DB=/var/lib/cmdforge/registry.db
Environment=PORT=5050
Environment=CMDFORGE_ENV=production
ExecStart=/opt/cmdforge/venv/bin/python -m cmdforge.web.app
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable cmdforge-registry
sudo systemctl start cmdforge-registry

4. Reverse Proxy (nginx)

server {
    listen 80;
    server_name cmdforge.brrd.tech;

    location / {
        proxy_pass http://127.0.0.1:5050;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static {
        alias /opt/cmdforge/src/cmdforge/web/static;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

5. SSL with Certbot

sudo certbot --nginx -d cmdforge.brrd.tech

Tailwind CSS Build

The CSS is pre-built and committed. To rebuild after changes:

# Install dependencies
npm install

# Build for production
npx tailwindcss -i src/cmdforge/web/static/css/input.css \
                -o src/cmdforge/web/static/css/main.css \
                --minify

Health Check

curl http://localhost:5050/api/v1/tools
# Returns: {"data":[],"meta":{"page":1,"per_page":20,"total":0,"total_pages":1}}

Troubleshooting

Issue	Solution
`disk I/O error`	Move database to non-merged filesystem
Port already in use	Change PORT environment variable
500 errors	Check `/tmp/cmdforge.log` for stack traces
Static files not loading	Verify static folder path in deployment

Future Considerations (Phase 8+)

Forum integration: External (Discourse) or built-in discussions
Newsletter signup: Email collection with double opt-in
A/B testing: Hero messaging, CTA variations
Analytics dashboard: Traffic insights for publishers
Premium features: Private registries, enhanced analytics
Internationalization: Multi-language support
Dark mode: Theme toggle with persistence
PWA features: Offline support, install prompt

Purpose​

Mission Alignment​

Guiding Principles​

Information Architecture​

Visual Design System​

Color Palette​

Typography​

Spacing System​

Border Radius​

Shadow System​

Page Requirements​

Landing Page (/)​

Section 1: Hero (Above the Fold)​

Section 2: Three Pillars (Why CmdForge?)​

Section 3: Featured Tools & Projects​

Section 4: Getting Started​

Section 5: Featured Contributor​

Section 6: Footer Ad Zone (Optional)​

Section 7: Footer​

Docs/Tutorials Pages (/docs/*, /tutorials/*)​

Tool Detail Page (/tools/{owner}/{name})​

Registry Browse Page (/tools)​

Publisher Dashboard (/dashboard)​

Donate Page (/donate)​

Component Library​

Buttons​

Cards​

Navigation​

Form Elements​

Badges and Tags​

Code Blocks​

Callout Boxes​

Loading States​

Responsive Design​

Breakpoints​

Layout Adaptations​

Touch Targets​

Mobile-Specific Considerations​

Performance Budgets​

Core Web Vitals Targets​

Resource Budgets​

Loading Strategy​

Caching Strategy​

Performance Monitoring​

Error States and Fallbacks​

Network Errors​

Tool Not Found (404):​

Search No Results:​

Offline Mode​

Form Errors​

Ad and Revenue Strategy​

Monetization Extensions (Optional)​

Data and Governance​

Privacy and Consent​

UX and Accessibility​

Tech Stack (Phase 7 Target)​

Auth and Session Model​

API Surfaces for Web UI​

Payments and Donations (Optional)​

Moderation and Abuse Reporting​

Media and Asset Handling​

Caching and SEO Serving​

SEO Strategy​

Technical SEO​

Structured Data (Schema.org)​

Open Graph & Social Sharing​

Sitemap​

robots.txt​

Canonical URLs​

Performance for SEO​

Content Strategy​

Risks and Mitigations​

Phase 7 Implementation Checklist​

7.1 Foundation & Setup​

7.2 Core Templates & Components​

7.3 Landing Page​

7.4 Registry Pages (Ad-Free)​

7.5 Documentation & Tutorials​

7.6 Authentication & Dashboard​

7.7 Privacy & Consent​

Purpose

Mission Alignment

Guiding Principles

Information Architecture

Visual Design System

Color Palette

Typography

Spacing System

Border Radius

Shadow System

Page Requirements

Landing Page (`/`)

Section 1: Hero (Above the Fold)

Section 2: Three Pillars (Why CmdForge?)

Section 3: Featured Tools & Projects

Section 4: Getting Started

Section 5: Featured Contributor

Section 6: Footer Ad Zone (Optional)

Section 7: Footer

Docs/Tutorials Pages (`/docs/`, `/tutorials/`)

Tool Detail Page (`/tools/{owner}/{name}`)

Registry Browse Page (`/tools`)

Publisher Dashboard (`/dashboard`)

Donate Page (`/donate`)

Component Library

Buttons

Cards

Navigation

Form Elements

Badges and Tags

Code Blocks

Callout Boxes

Loading States

Responsive Design

Breakpoints

Layout Adaptations

Touch Targets

Mobile-Specific Considerations

Performance Budgets

Core Web Vitals Targets

Resource Budgets

Loading Strategy

Caching Strategy

Performance Monitoring

Error States and Fallbacks

Network Errors

Tool Not Found (404):

Search No Results:

Offline Mode

Form Errors

Ad and Revenue Strategy

Monetization Extensions (Optional)

Data and Governance

Privacy and Consent

UX and Accessibility

Tech Stack (Phase 7 Target)

Auth and Session Model

API Surfaces for Web UI

Payments and Donations (Optional)

Moderation and Abuse Reporting

Media and Asset Handling

Caching and SEO Serving

SEO Strategy

Technical SEO

Structured Data (Schema.org)

Open Graph & Social Sharing

Sitemap

robots.txt

Canonical URLs

Performance for SEO

Content Strategy

Risks and Mitigations

Phase 7 Implementation Checklist

7.1 Foundation & Setup

7.2 Core Templates & Components

7.3 Landing Page

7.4 Registry Pages (Ad-Free)

7.5 Documentation & Tutorials

7.6 Authentication & Dashboard

7.7 Privacy & Consent