feat(cli): add optional GitHub token support for higher API rate limits (#294)

* fix: V-001 security vulnerability

Automated security fix generated by Orbis Security AI

* feat(cli): add optional GitHub token support with proper UX and docs

- Rename env var from GITHUB_TOKEN to UI_PRO_MAX_GITHUB_TOKEN (primary),
  with GITHUB_TOKEN as fallback — avoids silently attaching CI workflow
  credentials that GitHub Actions injects automatically
- Add whitespace trim guard to prevent malformed Authorization headers
- Add getGitHubTokenGuidance() helper exported from github.ts so rate-limit
  errors and spinner warnings tell users exactly how to fix the problem
- Thread optional token param through fetchReleases, getLatestRelease,
  downloadRelease signatures
- Add --token flag to init, versions, update commands (Commander.js wiring)
- Update rate-limit catch in tryGitHubInstall to show token guidance
- Document token options (flag, env var, fallback) in cli/README.md with
  CI warning about GITHUB_TOKEN scope

Supersedes the narrower env-only approach in PR #294 and incorporates the
safeguards requested during review of closed PR #186.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "UI/UX design intelligence skill with 67 styles, 161 palettes, 57 font pairings, 25 charts, and 15 stack guidelines",
-    "version": "2.5.0"
+    "version": "2.6.2"
   },
   "plugins": [
     {
       "name": "ui-ux-pro-max",
       "source": "./",
       "description": "Professional UI/UX design intelligence for AI coding assistants. Includes searchable databases of styles, colors, typography, charts, and UX guidelines for React, Next.js, Astro, Vue, Nuxt.js, Nuxt UI, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and Jetpack Compose.",
-      "version": "2.5.0",
+      "version": "2.6.2",
       "author": {
         "name": "nextlevelbuilder"
       },

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ui-ux-pro-max",
   "description": "UI/UX design intelligence. 67 styles, 161 palettes, 57 font pairings, 25 charts, 15 stacks (React, Next.js, Vue, Svelte, Astro, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, Nuxt, Jetpack Compose). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, mobile app. Elements: button, modal, navbar, sidebar, card, table, form, chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, flat design. Topics: color palette, accessibility, animation, layout, typography, font pairing, spacing, hover, shadow, gradient.",
-  "version": "2.5.0",
+  "version": "2.6.2",
   "author": {
     "name": "nextlevelbuilder"
   },

.claude/skills/banner-design/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ckm:banner-design
+name: ckm-banner-design
 description: "Design banners for social media, ads, website heroes, creative assets, and print. Multiple art direction options with AI-generated visuals. Actions: design, create, generate banner. Platforms: Facebook, Twitter/X, LinkedIn, YouTube, Instagram, Google Display, website hero, print. Styles: minimalist, gradient, bold typography, photo-based, illustrated, geometric, retro, glassmorphism, 3D, neon, duotone, editorial, collage. Uses ui-ux-pro-max, frontend-design, ai-artist, ai-multimodal skills."
 argument-hint: "[platform] [style] [dimensions]"
 license: MIT

.claude/skills/brand/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ckm:brand
+name: ckm-brand
 description: Brand voice, visual identity, messaging frameworks, asset management, brand consistency. Activate for branded content, tone of voice, marketing assets, brand compliance, style guides.
 argument-hint: "[update|review|create] [args]"
 metadata:

.claude/skills/design-system/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ckm:design-system
+name: ckm-design-system
 description: Token architecture, component specifications, and slide generation. Three-layer tokens (primitive→semantic→component), CSS variables, spacing/typography scales, component specs, strategic slide creation. Use for design tokens, systematic design, brand-compliant presentations.
 argument-hint: "[component or token]"
 license: MIT

.claude/skills/design/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ckm:design
+name: ckm-design
 description: "Comprehensive design skill: brand identity, design tokens, UI styling, logo generation (55 styles, Gemini AI), corporate identity program (50 deliverables, CIP mockups), HTML presentations (Chart.js), banner design (22 styles, social/ads/web/print), icon design (15 styles, SVG, Gemini 3.1 Pro), social photos (HTML→screenshot, multi-platform). Actions: design logo, create CIP, generate mockups, build slides, design banner, generate icon, create social photos, social media images, brand identity, design system. Platforms: Facebook, Twitter, LinkedIn, YouTube, Instagram, Pinterest, TikTok, Threads, Google Ads."
 argument-hint: "[design-type] [context]"
 license: MIT

.claude/skills/slides/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ckm:slides
+name: ckm-slides
 description: Create strategic HTML presentations with Chart.js, design tokens, responsive layouts, copywriting formulas, and contextual slide strategies.
 argument-hint: "[topic] [slide-count]"
 metadata:

.claude/skills/ui-styling/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ckm:ui-styling
+name: ckm-ui-styling
 description: Create beautiful, accessible user interfaces with shadcn/ui components (built on Radix UI + Tailwind), Tailwind CSS utility-first styling, and canvas-based visual designs. Use when building user interfaces, implementing design systems, creating responsive layouts, adding accessible components (dialogs, dropdowns, forms, tables), customizing themes and colors, implementing dark mode, generating visual designs and posters, or establishing consistent styling patterns across applications.
 argument-hint: "[component or layout]"
 license: MIT

.claude/skills/ui-styling/scripts/shadcn_add.py

@@ -64,6 +64,20 @@ class ShadcnInstaller:
         except (json.JSONDecodeError, KeyError, OSError):
             return []
 
+    def _get_shadcn_version(self) -> str:
+        """Read shadcn version from project package.json; fall back to a pinned default."""
+        pkg_json = self.project_root / "package.json"
+        if pkg_json.exists():
+            try:
+                pkg = json.loads(pkg_json.read_text())
+                for section in ("dependencies", "devDependencies"):
+                    version = pkg.get(section, {}).get("shadcn")
+                    if version:
+                        return version.lstrip("^~>=<").split()[0]
+            except (json.JSONDecodeError, KeyError):
+                pass
+        return "2.3.0"  # pinned fallback; update when newer stable release is needed
+
     def add_components(
         self, components: List[str], overwrite: bool = False
     ) -> tuple[bool, str]:
@@ -98,7 +112,8 @@ class ShadcnInstaller:
             )
 
         # Build command
-        cmd = ["npx", "shadcn@latest", "add"] + components
+        shadcn_version = self._get_shadcn_version()
+        cmd = ["npx", f"shadcn@{shadcn_version}", "add"] + components
 
         if overwrite:
             cmd.append("--overwrite")
@@ -144,7 +159,8 @@ class ShadcnInstaller:
                 "shadcn not initialized. Run 'npx shadcn@latest init' first",
             )
 
-        cmd = ["npx", "shadcn@latest", "add", "--all"]
+        shadcn_version = self._get_shadcn_version()
+        cmd = ["npx", f"shadcn@{shadcn_version}", "add", "--all"]
 
         if overwrite:
             cmd.append("--overwrite")

CONTRIBUTING.md

@@ -0,0 +1,181 @@
+# Contributing to UI/UX Pro Max
+
+Thank you for taking the time to contribute! 🎉  
+This guide will help you get started quickly.
+
+---
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Project Structure](#project-structure)
+- [Ways to Contribute](#ways-to-contribute)
+- [Development Workflow](#development-workflow)
+- [Commit Message Format](#commit-message-format)
+- [Pull Request Guidelines](#pull-request-guidelines)
+- [Reporting Bugs](#reporting-bugs)
+- [Code of Conduct](#code-of-conduct)
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** 18+ and **npm**
+- **Python 3.x**
+- **Bun** (for building the CLI)
+- **Git**
+
+### Fork & Clone
+
+```bash
+# 1. Fork the repo on GitHub, then clone your fork
+git clone https://github.com/YOUR_USERNAME/ui-ux-pro-max-skill.git
+cd ui-ux-pro-max-skill
+
+# 2. Add the upstream remote
+git remote add upstream https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git
+
+# 3. Install CLI dependencies
+cd cli && npm install && cd ..
+```
+
+---
+
+## Project Structure
+
+```
+ui-ux-pro-max-skill/
+├── src/ui-ux-pro-max/          # Source of truth — edit here, not in .claude/
+│   ├── data/                   # CSV databases (styles, colors, typography, rules)
+│   ├── scripts/                # Python search engine & design system generator
+│   └── templates/              # Platform-specific skill templates
+├── cli/                        # npm CLI installer (uipro-cli)
+├── .claude/                    # Local dev/test files for Claude Code
+├── .factory/                   # Local dev/test files for Droid (Factory)
+├── docs/                       # Documentation
+└── preview/                    # Preview screenshots and demos
+```
+
+> **Important:** Always make data/script changes in `src/ui-ux-pro-max/`, then sync to the CLI (see below). Do not edit `.claude/` or `.factory/` directly for permanent changes.
+
+---
+
+## Ways to Contribute
+
+### 🐛 Bug Fixes
+Check the [Issues tab](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/issues) for bugs labeled `bug`. Comment on the issue before starting so we don't duplicate work.
+
+### ✨ New UI Styles
+Add a new entry to `src/ui-ux-pro-max/data/styles.csv`. Each row needs:
+- Style name
+- Description
+- Best for (use cases)
+- Key CSS properties/effects
+
+### 🎨 New Color Palettes
+Add entries to `src/ui-ux-pro-max/data/colors.csv`. Match the existing format (primary, secondary, CTA, background, text, notes).
+
+### 🏭 New Industry Reasoning Rules
+Add rules to `src/ui-ux-pro-max/data/rules.csv`. Each rule needs a product type, recommended pattern, style priority, color mood, typography mood, key effects, and anti-patterns.
+
+### 🌍 Translations
+Translate `README.md` into your language and save it as `README.[lang].md` (e.g., `README.zh.md`, `README.es.md`).
+
+### 📝 Documentation Improvements
+Fix typos, clarify confusing sections, or add missing examples in `README.md` or `docs/`.
+
+### 🔧 CLI Improvements
+Improvements to the `cli/` installer. Run `cd cli && bun run build` to test locally.
+
+---
+
+## Development Workflow
+
+```bash
+# 1. Create a feature branch from main
+git checkout -b feat/your-feature-name
+
+# 2. Make your changes in src/ui-ux-pro-max/
+
+# 3. Sync changes to CLI assets
+cp -r src/ui-ux-pro-max/data/* cli/assets/data/
+cp -r src/ui-ux-pro-max/scripts/* cli/assets/scripts/
+cp -r src/ui-ux-pro-max/templates/* cli/assets/templates/
+
+# 4. Build and test the CLI locally
+cd cli && bun run build
+mkdir /tmp/test-project && cd /tmp/test-project
+node /path/to/cli/dist/index.js init --ai claude --offline
+
+# 5. Test the Python search script
+cd /path/to/repo
+python3 src/ui-ux-pro-max/scripts/search.py "your query" --design-system
+
+# 6. Push your branch
+git push -u origin feat/your-feature-name
+```
+
+---
+
+## Commit Message Format
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>: <short description>
+
+Types:
+  feat     → New feature or content (new style, rule, palette)
+  fix      → Bug fix
+  docs     → Documentation only
+  refactor → Code change without new feature or fix
+  chore    → Build process, dependency updates
+  test     → Adding or fixing tests
+```
+
+**Examples:**
+```
+feat: add Skeuomorphism 2.0 style to general styles
+fix: correct color palette for fintech industry rule
+docs: translate README to Spanish
+chore: update uipro-cli to v2.6.0
+```
+
+---
+
+## Pull Request Guidelines
+
+1. **One PR per change** — keep PRs focused and small
+2. **Reference related issues** — use `Closes #123` in the PR description
+3. **Fill out the PR template** — describe what you changed and why
+4. **Never push directly to `main`** — always use a feature branch
+5. **Wait for review** — a maintainer will review within a few days
+
+---
+
+## Reporting Bugs
+
+Please [open an issue](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/issues/new) and include:
+
+- Your OS and terminal
+- The AI assistant you're using (Claude Code, Cursor, etc.)
+- The exact command or prompt that triggered the bug
+- Expected vs. actual behavior
+- Any error messages or screenshots
+
+---
+
+## Code of Conduct
+
+Be kind, constructive, and respectful. We're all here to build something useful together.  
+Harassment, spam, or low-effort contributions will be closed without review.
+
+---
+
+## Questions?
+
+Open a [Discussion](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/discussions) or check the [README](README.md) first.
+
+Happy contributing! 🚀

cli/README.md

@@ -36,6 +36,31 @@ uipro versions              # List available versions
 uipro update                # Update to latest version
 ```
 
+## GitHub Authentication
+
+GitHub's unauthenticated API allows 60 requests/hour per IP. If you hit rate limits, you can provide a GitHub Personal Access Token (PAT) to raise the limit to 5,000 requests/hour.
+
+**Options (in order of precedence):**
+
+```bash
+# 1. Pass directly as a flag (one-off use)
+uipro init --token ghp_yourtoken
+uipro versions --token ghp_yourtoken
+uipro update --token ghp_yourtoken
+
+# 2. Set as a project-scoped environment variable (recommended)
+export UI_PRO_MAX_GITHUB_TOKEN=ghp_yourtoken
+uipro init
+
+# 3. Fallback: GITHUB_TOKEN is also read if UI_PRO_MAX_GITHUB_TOKEN is not set
+export GITHUB_TOKEN=ghp_yourtoken
+uipro init
+```
+
+**Creating a token:** Go to <https://github.com/settings/tokens>, click **Generate new token (classic)**, and select **no scopes** — public repo access requires no permissions. Copy the token and store it as an environment secret; never hardcode it in source files.
+
+> **Warning:** `GITHUB_TOKEN` is automatically injected by GitHub Actions with broad repo permissions. Prefer `UI_PRO_MAX_GITHUB_TOKEN` in CI to avoid accidentally attaching workflow credentials to release download requests.
+
 ## How It Works
 
 By default, `uipro init` tries to download the latest release from GitHub to ensure you get the most up-to-date version. If the download fails (network error, rate limit), it automatically falls back to the bundled assets included in the CLI package.

cli/src/commands/init.ts

@@ -13,6 +13,7 @@ import {
   getLatestRelease,
   getAssetUrl,
   downloadRelease,
+  getGitHubTokenGuidance,
   GitHubRateLimitError,
   GitHubDownloadError,
 } from '../utils/github.js';
@@ -27,6 +28,7 @@ interface InitOptions {
   offline?: boolean;
   legacy?: boolean; // Use old ZIP-based install
   global?: boolean; // Install to home directory (global mode)
+  token?: string; // GitHub PAT for higher API rate limits
 }
 
 /**
@@ -36,13 +38,14 @@ interface InitOptions {
 async function tryGitHubInstall(
   targetDir: string,
   aiType: AIType,
-  spinner: ReturnType<typeof ora>
+  spinner: ReturnType<typeof ora>,
+  token?: string
 ): Promise<string[] | null> {
   let tempDir: string | null = null;
 
   try {
     spinner.text = 'Fetching latest release from GitHub...';
-    const release = await getLatestRelease();
+    const release = await getLatestRelease(token);
     const assetUrl = getAssetUrl(release);
 
     if (!assetUrl) {
@@ -53,7 +56,7 @@ async function tryGitHubInstall(
     tempDir = await createTempDir();
     const zipPath = join(tempDir, 'release.zip');
 
-    await downloadRelease(assetUrl, zipPath);
+    await downloadRelease(assetUrl, zipPath, token);
 
     spinner.text = 'Extracting and installing files...';
     const { copiedFolders, tempDir: extractedTempDir } = await installFromZip(
@@ -73,7 +76,7 @@ async function tryGitHubInstall(
     }
 
     if (error instanceof GitHubRateLimitError) {
-      spinner.warn('GitHub rate limit reached, using template generation...');
+      spinner.warn(`GitHub rate limit reached, falling back to bundled assets.\n${getGitHubTokenGuidance()}`);
       return null;
     }
 
@@ -164,7 +167,7 @@ export async function initCommand(options: InitOptions): Promise<void> {
       }
       // Try GitHub download first (unless offline mode)
       if (!options.offline) {
-        const githubResult = await tryGitHubInstall(cwd, aiType, spinner);
+        const githubResult = await tryGitHubInstall(cwd, aiType, spinner, options.token);
         if (githubResult) {
           copiedFolders = githubResult;
           installMethod = 'github';

cli/src/commands/update.ts

@@ -7,6 +7,7 @@ import type { AIType } from '../types/index.js';
 
 interface UpdateOptions {
   ai?: AIType;
+  token?: string;
 }
 
 export async function updateCommand(options: UpdateOptions): Promise<void> {
@@ -15,7 +16,7 @@ export async function updateCommand(options: UpdateOptions): Promise<void> {
   const spinner = ora('Checking for updates...').start();
 
   try {
-    const release = await getLatestRelease();
+    const release = await getLatestRelease(options.token);
     spinner.succeed(`Latest version: ${chalk.cyan(release.tag_name)}`);
 
     console.log();
@@ -25,6 +26,7 @@ export async function updateCommand(options: UpdateOptions): Promise<void> {
     await initCommand({
       ai: options.ai,
       force: true,
+      token: options.token,
     });
   } catch (error) {
     spinner.fail('Update check failed');

cli/src/commands/versions.ts

@@ -3,11 +3,15 @@ import ora from 'ora';
 import { fetchReleases } from '../utils/github.js';
 import { logger } from '../utils/logger.js';
 
-export async function versionsCommand(): Promise<void> {
+interface VersionsOptions {
+  token?: string;
+}
+
+export async function versionsCommand(options: VersionsOptions = {}): Promise<void> {
   const spinner = ora('Fetching available versions...').start();
 
   try {
-    const releases = await fetchReleases();
+    const releases = await fetchReleases(options.token);
 
     if (releases.length === 0) {
       spinner.warn('No releases found');

cli/src/index.ts

@@ -29,6 +29,7 @@ program
   .option('-f, --force', 'Overwrite existing files')
   .option('-o, --offline', 'Skip GitHub download, use bundled assets only')
   .option('-g, --global', 'Install globally to home directory (~/) instead of current project')
+  .option('-t, --token <token>', 'GitHub Personal Access Token for higher API rate limits')
   .action(async (options) => {
     if (options.ai && !AI_TYPES.includes(options.ai)) {
       console.error(`Invalid AI type: ${options.ai}`);
@@ -40,18 +41,21 @@ program
       force: options.force,
       offline: options.offline,
       global: options.global,
+      token: options.token,
     });
   });
 
 program
   .command('versions')
   .description('List available versions')
+  .option('-t, --token <token>', 'GitHub Personal Access Token for higher API rate limits')
   .action(versionsCommand);
 
 program
   .command('update')
   .description('Update UI/UX Pro Max to latest version')
   .option('-a, --ai <type>', `AI assistant type (${AI_TYPES.join(', ')})`)
+  .option('-t, --token <token>', 'GitHub Personal Access Token for higher API rate limits')
   .action(async (options) => {
     if (options.ai && !AI_TYPES.includes(options.ai)) {
       console.error(`Invalid AI type: ${options.ai}`);
@@ -60,6 +64,7 @@ program
     }
     await updateCommand({
       ai: options.ai as AIType | undefined,
+      token: options.token,
     });
   });
 

cli/src/utils/github.ts

@@ -19,25 +19,45 @@ export class GitHubDownloadError extends Error {
   }
 }
 
+export function getGitHubTokenGuidance(): string {
+  return (
+    'To increase your GitHub API rate limit, set the UI_PRO_MAX_GITHUB_TOKEN environment variable\n' +
+    'to a GitHub Personal Access Token (no scopes needed for public repos).\n' +
+    'Create one at: https://github.com/settings/tokens\n' +
+    'Example: UI_PRO_MAX_GITHUB_TOKEN=ghp_xxx uipro init\n' +
+    'Or pass it directly: uipro init --token ghp_xxx'
+  );
+}
+
 function checkRateLimit(response: Response): void {
   const remaining = response.headers.get('x-ratelimit-remaining');
   if (response.status === 403 && remaining === '0') {
     const resetTime = response.headers.get('x-ratelimit-reset');
     const resetDate = resetTime ? new Date(parseInt(resetTime) * 1000).toLocaleTimeString() : 'unknown';
-    throw new GitHubRateLimitError(`GitHub API rate limit exceeded. Resets at ${resetDate}`);
+    throw new GitHubRateLimitError(
+      `GitHub API rate limit exceeded. Resets at ${resetDate}.\n${getGitHubTokenGuidance()}`
+    );
   }
   if (response.status === 429) {
-    throw new GitHubRateLimitError('GitHub API rate limit exceeded (429 Too Many Requests)');
+    throw new GitHubRateLimitError(
+      `GitHub API rate limit exceeded (429 Too Many Requests).\n${getGitHubTokenGuidance()}`
+    );
   }
 }
 
-export async function fetchReleases(): Promise<Release[]> {
+function getAuthHeaders(token?: string): Record<string, string> {
+  const resolved = (token || process.env['UI_PRO_MAX_GITHUB_TOKEN'] || process.env['GITHUB_TOKEN'])?.trim();
+  return resolved ? { 'Authorization': `Bearer ${resolved}` } : {};
+}
+
+export async function fetchReleases(token?: string): Promise<Release[]> {
   const url = `${API_BASE}/repos/${REPO_OWNER}/${REPO_NAME}/releases`;
 
   const response = await fetch(url, {
     headers: {
       'Accept': 'application/vnd.github.v3+json',
       'User-Agent': 'uipro-cli',
+      ...getAuthHeaders(token),
     },
   });
 
@@ -50,13 +70,14 @@ export async function fetchReleases(): Promise<Release[]> {
   return response.json();
 }
 
-export async function getLatestRelease(): Promise<Release> {
+export async function getLatestRelease(token?: string): Promise<Release> {
   const url = `${API_BASE}/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest`;
 
   const response = await fetch(url, {
     headers: {
       'Accept': 'application/vnd.github.v3+json',
       'User-Agent': 'uipro-cli',
+      ...getAuthHeaders(token),
     },
   });
 
@@ -69,11 +90,12 @@ export async function getLatestRelease(): Promise<Release> {
   return response.json();
 }
 
-export async function downloadRelease(url: string, dest: string): Promise<void> {
+export async function downloadRelease(url: string, dest: string, token?: string): Promise<void> {
   const response = await fetch(url, {
     headers: {
       'User-Agent': 'uipro-cli',
       'Accept': 'application/octet-stream',
+      ...getAuthHeaders(token),
     },
   });
 

skill.json

@@ -2,7 +2,7 @@
   "name": "ui-ux-pro-max",
   "displayName": "UI/UX Pro Max",
   "description": "AI-powered design intelligence with 67 UI styles, 161 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 15+ tech stacks.",
-  "version": "2.5.0",
+  "version": "2.6.2",
   "author": "NextLevelBuilder",
   "license": "MIT",
   "homepage": "https://uupm.cc",