CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code when working with this repository.
4 
5## Project Overview
6 
7Node.js CLI tool for managing Claude Code components (agents, commands, MCPs, hooks, settings) with a static website for browsing and installing components. The dashboard and its API routes are deployed on Cloudflare Pages, with supporting cron and monitoring tasks running as Cloudflare Workers.
8 
9## Essential Commands
10 
11```bash
12# Development
13npm install                    # Install dependencies
14npm test                       # Run tests
15npm version patch|minor|major  # Bump version
16npm publish                    # Publish to npm
17 
18# Component catalog
19python scripts/generate_components_json.py  # Update docs/components.json
20 
21# Dashboard + API (Astro on Cloudflare Pages)
22cd dashboard && npm run build  # Build before deploy
23npm run deploy                 # Deploy www + app.aitmpl.com via wrangler
24```
25 
26> Deploys to production happen automatically via GitHub Actions on push to `main`
27> (changes in `dashboard/**`). Manual deploy uses `wrangler pages deploy`, not Vercel.
28 
29## Security Guidelines
30 
31### ⛔ CRITICAL: NEVER Hardcode Secrets or IDs
32 
33**NEVER write API keys, tokens, passwords, project IDs, org IDs, or any identifier in code.** This includes Cloudflare account/project IDs, Supabase URLs, Discord IDs, database connection strings, and any other infrastructure identifier. ALL must go in `.env` (or Cloudflare secrets via `wrangler secret put`).
34 
35```javascript
36// ❌ WRONG
37const API_KEY = "AIzaSy...";
38 
39// ✅ CORRECT
40const API_KEY = process.env.GOOGLE_API_KEY;
41```
42 
43**When creating scripts with API keys:**
441. Use `process.env` (Node.js) or `os.environ.get()` (Python)
452. Load from `.env` file using `dotenv`
463. Add variable to `.env.example` with placeholder
474. Verify `.env` is in `.gitignore`
48 
49**If you accidentally commit a secret:**
501. Revoke the key IMMEDIATELY
512. Generate new key
523. Update `.env`
534. Old key is compromised forever (git history)
54 
55## Component System
56 
57### Component Types
58 
59**Agents** (600+) - AI specialists for development tasks
60**Commands** (200+) - Custom slash commands for workflows
61**MCPs** (55+) - External service integrations
62**Settings** (60+) - Claude Code configuration files
63**Hooks** (39+) - Automation triggers
64**Loops** (18+) - Autonomous agentic workflows (goal + interval + stop condition) that reference other components
65**Templates** (14+) - Complete project configurations
66 
67### Installation Patterns
68 
69```bash
70# Single component
71npx claude-code-templates@latest --agent frontend-developer
72npx claude-code-templates@latest --command setup-testing
73npx claude-code-templates@latest --hook automation/simple-notifications
74npx claude-code-templates@latest --loop engineering/docs-sweep-loop  # also installs the loop's referenced components
75 
76# Batch installation
77npx claude-code-templates@latest --agent security-auditor --command security-audit --setting read-only-mode
78 
79# Interactive mode
80npx claude-code-templates@latest
81```
82 
83### Component Development
84 
85#### Adding New Components
86 
87**CRITICAL: Use the component-reviewer agent for ALL component changes**
88 
89When adding or modifying components, you MUST use the `component-reviewer` subagent to validate the component before committing:
90 
91```
92Use the component-reviewer agent to review [component-path]
93```
94 
95**Component Creation Workflow:**
96 
971. Create component file in `cli-tool/components/{type}/{category}/{name}.md`
982. Use descriptive hyphenated names (kebab-case)
993. Include clear descriptions and usage examples
1004. **REVIEW with component-reviewer agent** (validates format, security, naming)
1015. Fix any issues identified by the reviewer
1026. **TEST before generating/publishing**: ask the human in the session whether
103   they want to test the newly created/modified component(s) first. Do NOT run
104   `generate_components_json.py`, commit, or publish until testing is confirmed
105   or explicitly skipped by the user.
1067. Run `python scripts/generate_components_json.py` to update catalog
107 
108**The component-reviewer agent checks:**
109- ✅ Valid YAML frontmatter and required fields
110- ✅ Proper kebab-case naming conventions
111- ✅ No hardcoded secrets (API keys, tokens, passwords)
112- ✅ Relative paths only (no absolute paths)
113- ✅ Supporting files exist (for hooks with scripts)
114- ✅ Clear, specific descriptions
115- ✅ Correct category placement
116- ✅ Security best practices
117 
118**Example Usage:**
119```
120# After creating a new agent
121Use the component-reviewer agent to review cli-tool/components/agents/development-team/react-expert.md
122 
123# Before committing hook changes
124Use the component-reviewer agent to review cli-tool/components/hooks/git/prevent-force-push.json
125 
126# For PR reviews with multiple components
127Use the component-reviewer agent to review all modified components in cli-tool/components/
128```
129 
130The agent will provide prioritized feedback:
131- **❌ Critical Issues**: Must fix before merge (security, missing fields)
132- **⚠️ Warnings**: Should fix (clarity, best practices)
133- **📋 Suggestions**: Nice to have improvements
134 
135#### Skill Security Scanning (SkillSpector)
136 
137Skills under `cli-tool/components/skills/**` are scanned for security
138vulnerabilities by [SkillSpector](https://github.com/NVIDIA/skillspector)
139(NVIDIA, Apache-2.0) — a static analyzer with 64 vulnerability patterns
140(prompt injection, data exfiltration, supply chain, dangerous code/AST, taint
141tracking, YARA signatures, etc.). It runs in static-only mode (`--no-llm`), so
142no API key or secret is required.
143 
144Two GitHub Actions drive it, both via the batch orchestrator
145`scripts/skillspector_scan.py`:
146 
147- **`.github/workflows/skill-security-scan.yml`** (PR) — scans only the skills
148  changed in the PR (`git diff`), posts an idempotent report comment, and
149  **blocks** the check if any changed skill scores HIGH/CRITICAL (risk score
150  > 50). Uploads an aggregated SARIF to the Security tab.
151- **`.github/workflows/skill-security-scan-all.yml`** (weekly + manual) — scans
152  all skills, reports to the run summary and SARIF, and **never blocks**.
153 
154SkillSpector requires Python 3.12+ and is installed from NVIDIA's `main`
155branch (`pip install git+https://github.com/NVIDIA/skillspector.git@main`); it
156is not published to PyPI. Risk bands: 0-20 LOW, 21-50 MEDIUM, 51-80 HIGH,
15781-100 CRITICAL.
158 
159#### Statuslines with Python Scripts
160 
161Statuslines can reference Python scripts that are auto-downloaded to `.claude/scripts/`:
162 
163```javascript
164// In src/index.js:installIndividualSetting()
165if (settingName.includes('statusline/')) {
166  const pythonFileName = settingName.split('/')[1] + '.py';
167  const pythonUrl = githubUrl.replace('.json', '.py');
168  additionalFiles['.claude/scripts/' + pythonFileName] = {
169    content: pythonContent,
170    executable: true
171  };
172}
173```
174 
175### Publishing Workflow
176 
177```bash
178# 1. Update component catalog
179python scripts/generate_components_json.py
180 
181# 2. Run tests
182npm test
183 
184# 3. Check current npm version and align local version
185npm view claude-code-templates version  # check latest on registry
186# Edit package.json version to be one patch above the registry version
187 
188# 4. Commit version bump and push
189git add package.json && git commit -m "chore: Bump version to X.Y.Z"
190git push origin main
191 
192# 5. Publish to npm (requires granular access token with "Bypass 2FA" enabled)
193npm config set //registry.npmjs.org/:_authToken=YOUR_GRANULAR_TOKEN
194npm publish
195npm config delete //registry.npmjs.org/:_authToken  # always clean up after
196 
197# 6. Tag the release
198git tag vX.Y.Z && git push origin vX.Y.Z
199 
200# 7. Deploy website (dashboard on Cloudflare Pages)
201# Automatic on push to main (GitHub Actions). Manual: from dashboard/ run `npm run deploy`
202```
203 
204**npm Publishing Notes:**
205- Classic npm tokens were revoked Dec 2025. Use **granular access tokens** from [npmjs.com/settings/~/tokens](https://www.npmjs.com/settings/~/tokens)
206- The token must have **Read and Write** permissions for `claude-code-templates` and **"Bypass 2FA"** enabled
207- Always remove the token from npm config after publishing (`npm config delete`)
208- The local `package.json` version may drift from npm if published from CI — always check `npm view claude-code-templates version` first
209- Never hardcode or commit tokens
210 
211## API Architecture
212 
213### Critical Endpoints
214 
215API endpoints live as Astro API routes in `dashboard/src/pages/api/`:
216 
217**`/api/track-download-supabase`** (CRITICAL)
218- Tracks component downloads for analytics
219- Used by CLI on every installation
220- Database: Supabase (component_downloads table)
221 
222**`/api/discord/interactions`**
223- Discord bot slash commands
224- Features: /search, /info, /install, /popular
225 
226**`/api/claude-code-check`**
227- Monitors Claude Code releases
228- Triggered every 30 minutes by the `cloudflare-workers/crons` Worker (not a Vercel cron)
229- Database: Neon (claude_code_versions, claude_code_changes, discord_notifications_log, monitoring_metadata tables)
230 
231### Shared API Libraries
232 
233- `dashboard/src/lib/api/cors.ts` — CORS headers, `corsResponse()`, `jsonResponse()`
234- `dashboard/src/lib/api/neon.ts` — Neon client factory
235- `dashboard/src/lib/api/auth.ts` — Clerk JWT verification
236- `dashboard/src/lib/api/changelog-parser.ts` — Claude Code changelog parser
237 
238### Emergency Rollback
239 
240```bash
241# List recent Pages deployments
242npx wrangler pages deployment list --project-name=aitmpl-dashboard
243# Roll back to a previous deployment
244npx wrangler pages deployment rollback <deployment-id> --project-name=aitmpl-dashboard
245```
246 
247## Cloudflare Workers
248 
249The `cloudflare-workers/` directory contains Cloudflare Worker projects that run independently from the dashboard Pages project.
250 
251### crons
252 
253Replaces the old Vercel cron jobs. On a schedule it calls the dashboard API endpoints (which stay on Cloudflare Pages) with a shared `TRIGGER_SECRET`.
254 
255- `*/30 * * * *` → `/api/claude-code-check` (monitors Claude Code npm releases)
256- `0 * * * *` → `/api/health-check` (hourly; was every 15 min on Vercel, reduced to save invocations)
257 
258Errors and cron check-ins are reported to Sentry (`sentry.js`, DSN from the `aitmpl-workers` project — see Error Tracking below).
259 
260```bash
261cd cloudflare-workers/crons
262npm run dev          # Local dev
263npx wrangler deploy  # Deploy
264```
265 
266**Secrets (Cloudflare):** `DASHBOARD_URL` (e.g. `https://www.aitmpl.com`), `TRIGGER_SECRET`, `SENTRY_DSN` (optional).
267 
268### docs-monitor (DECOMMISSIONED 2026-07)
269 
270Monitored https://code.claude.com/docs hourly with Telegram notifications. **Deleted from Cloudflare** to free a cron-trigger slot for the newsletter worker (the account's free plan allows 5 cron triggers total). The code remains in `cloudflare-workers/docs-monitor/` and can be redeployed if a slot frees up (`npx wrangler deploy`).
271 
272### pulse (Weekly KPI Report)
273 
274Collects metrics from GitHub, Discord, Supabase, npm, and Google Analytics every Sunday at 14:00 UTC and sends a consolidated report via Telegram.
275 
276**Architecture:** Single `index.js` file (no npm dependencies at runtime). All source collectors, formatter, and Telegram sender in one file.
277 
278**Cron:** `0 14 * * 0` (Sundays 14:00 UTC / 11:00 AM Chile)
279 
280```bash
281cd cloudflare-workers/pulse
282npm run dev          # Local dev
283npx wrangler deploy  # Deploy
284 
285# Manual trigger
286curl -X POST https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger \
287  -H "Authorization: Bearer $TRIGGER_SECRET"
288 
289# Test single source
290curl -X POST "https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger?source=github" \
291  -H "Authorization: Bearer $TRIGGER_SECRET"
292 
293# Dry run (no Telegram)
294curl -X POST "https://pulse-weekly-report.SUBDOMAIN.workers.dev/trigger?send=false" \
295  -H "Authorization: Bearer $TRIGGER_SECRET"
296```
297 
298**Secrets (Cloudflare):**
299```bash
300TELEGRAM_BOT_TOKEN          # Shared with docs-monitor
301TELEGRAM_CHAT_ID            # Shared with docs-monitor
302GITHUB_TOKEN                # GitHub PAT (public_repo scope)
303SUPABASE_URL                # Supabase project URL
304SUPABASE_SERVICE_ROLE_KEY   # Supabase service role key
305DISCORD_BOT_TOKEN           # Discord bot token
306DISCORD_GUILD_ID            # Discord server ID
307TRIGGER_SECRET              # For manual /trigger endpoint
308GA_PROPERTY_ID              # GA4 property ID (optional)
309GA_SERVICE_ACCOUNT_JSON     # Base64 service account (optional)
310```
311 
312**Graceful degradation:** Each source catches its own errors. Missing secrets or API failures show `⚠️ Unavailable` instead of crashing the report. Failed collectors are also reported to Sentry via `sentry.js` (see Error Tracking below). The Vercel collector was removed (2026-07) since the dashboard no longer deploys to Vercel.
313 
314### newsletter (Weekly Community Components Email)
315 
316Composes and sends a simple weekly email via Resend featuring trending components (one Skill, Agent, MCP, Hook and Setting per send, in that fixed order). Selection is weighted-random by recent downloads and the copy (subject, catalog intro, per-component sentences, stats cited, closer) rotates from pools so no two emails read the same. Body is plain text plus a minimal HTML version (bold + underlined component titles, clickable component links). Data comes from the live `trending-data.json` + `components.json`.
317 
318**Delivery:** Resend **Broadcast** targeting the segment in `RESEND_SEGMENT_ID` — Resend injects the per-recipient unsubscribe link (`{{{RESEND_UNSUBSCRIBE_URL}}}` placeholder in the body) and manages the suppression list automatically. Replies go to `NEWSLETTER_REPLY_TO`. The segment is the safety gate: point it at a pilot segment for tests or the full-audience segment for community-wide sends. Open/click tracking is enabled on the `aitmpl.com` domain with tracking subdomain `track.aitmpl.com` (metrics per broadcast at resend.com/broadcasts). Cron: Sundays 16:00 UTC (slot freed by decommissioning docs-monitor). `GET /preview?format=text` composes without sending; `POST /trigger` sends (`?send=false` for dry run).
319 
320```bash
321cd cloudflare-workers/newsletter
322npm run dev          # Local dev
323npx wrangler deploy  # Deploy
324 
325# Preview content without sending (repeat to see the copy rotate)
326curl "https://aitmpl-newsletter.SUBDOMAIN.workers.dev/preview?format=text" \
327  -H "Authorization: Bearer $TRIGGER_SECRET"
328 
329# Real send: creates + sends a Broadcast to the segment in RESEND_SEGMENT_ID
330curl -X POST "https://aitmpl-newsletter.SUBDOMAIN.workers.dev/trigger" \
331  -H "Authorization: Bearer $TRIGGER_SECRET"
332```
333 
334**Secrets (Cloudflare):** `RESEND_API_KEY` (full access — broadcasts/segments), `RESEND_SEGMENT_ID`, `NEWSLETTER_REPLY_TO`, `TRIGGER_SECRET`, `SENTRY_DSN` (optional). Public vars in `wrangler.toml [vars]`: `DASHBOARD_URL`, `RESEND_FROM_EMAIL` (`daniel.avila@aitmpl.com`).
335 
336## Error Tracking (Sentry)
337 
338Free-tier Sentry, added to close the gap where automated cron/worker failures
339were previously invisible. No official `@sentry/*` SDK is used anywhere —
340every surface has its own tiny dependency-free client that posts directly to
341the Sentry envelope API via `fetch()`, matching this repo's zero-dependency
342worker style and avoiding Cloudflare Pages SSR friction with `@sentry/astro`.
343 
344**Status as of 2026-07-04: all 3 projects live and verified end-to-end** (each
345confirmed with a manual test event returning HTTP 200 from Sentry and
346appearing in its Issues dashboard).
347 
348- ✅ **Cloudflare Workers** (Sentry project `aitmpl-workers`) — `SENTRY_DSN`
349  secret set on all 3 workers (`aitmpl-crons`, `pulse-weekly-report`,
350  `claude-docs-monitor`) via `wrangler secret put SENTRY_DSN`.
351- ✅ **Dashboard** (Sentry project `aitmpl-dashboard`) — `SENTRY_DSN` set as a
352  Cloudflare Pages secret (`wrangler pages secret put SENTRY_DSN
353  --project-name=aitmpl-dashboard`). Wired into `captureApiError()` calls in
354  `claude-code-check`, `health-check`, and the three `track-*` endpoints.
355- ✅ **CLI** (Sentry project `aitmpl-cli`) — the DSN is public by design
356  (send-only, not a secret) and ships **hardcoded as the default** in
357  `cli-tool/src/error-reporting.js` (`DEFAULT_SENTRY_DSN`, overridable via
358  `CCT_SENTRY_DSN` for testing against a different project). Reporting
359  itself stays **opt-in**: requires the end user to set
360  `CCT_ERROR_REPORTING=true`, and always defers to the existing
361  `CCT_NO_TRACKING`/`CCT_NO_ANALYTICS`/`CI` opt-outs.
362 
363**Not yet configured (any surface):** Sentry alert rules to Discord/Telegram,
364and Cron Monitors dashboards for the workers' scheduled check-ins (the
365`checkIn()` calls already send `in_progress`/`ok`/`error` events — a Monitor
366just needs to be created in the Sentry UI with matching slugs:
367`claude-code-check`, `health-check`, `pulse-weekly-report`, `docs-monitor`).
368 
369**Files:** `cloudflare-workers/{crons,pulse,docs-monitor}/sentry.js` (workers),
370`dashboard/src/lib/api/error-tracking.ts` (dashboard), `cli-tool/src/error-reporting.js` (CLI).
371 
372## Dashboard (www.aitmpl.com)
373 
374Astro + React + Tailwind dashboard serving both `www.aitmpl.com` and `app.aitmpl.com`. Clerk auth for user collections. Source lives in `dashboard/`. All API endpoints are Astro API routes in the same project.
375 
376### Architecture
377 
378- **Framework**: Astro 5 with React islands, Tailwind v4, `output: 'server'`, `@astrojs/cloudflare` adapter (`mode: 'directory'`)
379- **Hosting**: Cloudflare Pages (project `aitmpl-dashboard`), SSR on Workers runtime
380- **Auth**: Clerk (`window.Clerk` global, no ClerkProvider per island)
381- **Data**: `components.json` and `trending-data.json` served from `dashboard/public/` (same-origin)
382- **APIs**: All endpoints in `dashboard/src/pages/api/` (Astro API routes, no separate serverless project)
383 
384### Featured Pages (`/featured/[slug]`)
385 
386Featured partner integrations shown on the dashboard homepage. Two files to edit:
387 
388**`dashboard/src/lib/constants.ts`** — `FEATURED_ITEMS` array. Each entry has:
389- `name`, `description`, `logo`, `url` (`/featured/slug`), `tag`, `tagColor`, `category`
390- `ctaLabel`, `ctaUrl`, `websiteUrl`
391- `installCommand` — shown in the sidebar Quick Install box
392- `metadata` — key/value pairs shown in the Details sidebar (e.g. `Components: '8'`)
393- `links` — sidebar links list
394 
395**`dashboard/src/pages/featured/[slug].astro`** — Content for each slug rendered via `{slug === 'brightdata' && (...)}` blocks. Each block contains the full HTML content for that partner page.
396 
397**When adding a skill to a featured page:**
3981. Add a new card `<div class="flex gap-3 ...">` inside the Skills Layer section of the relevant `{slug === '...'}` block
3992. Update `installCommand` in `constants.ts` to include the new skill
4003. Increment `metadata.Components` count in `constants.ts`
401 
402Current featured slugs: `brightdata`, `neon-instagres`, `claudekit`, `braingrid`
403 
404### Cloudflare Pages Project Setup
405 
406A single Cloudflare Pages project (`aitmpl-dashboard`) serves all domains. Config lives in `dashboard/wrangler.toml`:
407 
408| Project | Domains | Root Directory | Build output |
409|---------|---------|----------------|--------------|
410| `aitmpl-dashboard` | `www.aitmpl.com`, `aitmpl.com` (redirect), `app.aitmpl.com` | `dashboard` | `dist` |
411 
412`wrangler.toml` sets `pages_build_output_dir = "./dist"`, `compatibility_flags = ["nodejs_compat"]`, and the `PUBLIC_*` build-time vars in `[vars]`. Secrets are set via the Cloudflare Dashboard or `wrangler pages secret put`.
413 
414### Deployment
415 
416**ALWAYS use the deployer agent (`.claude/agents/deployer.md`) for all deployments.** It runs pre-deploy checks (auth, git status, build) and handles the full pipeline safely. Never deploy manually.
417 
418```bash
419npm run deploy             # Build + `wrangler pages deploy dist` for www + app.aitmpl.com
420npm run deploy:dashboard   # Same as above
421```
422 
423**CI/CD**: Pushes to `main` auto-deploy via GitHub Actions (`.github/workflows/deploy.yml`):
424- Changes in `dashboard/**` trigger a build and `wrangler pages deploy dist --project-name=aitmpl-dashboard`
425 
426**Required GitHub Secrets** (Settings > Secrets > Actions):
427- `CLOUDFLARE_API_TOKEN` — Cloudflare API token with Pages edit permission
428- `CLOUDFLARE_ACCOUNT_ID` — Cloudflare account ID
429 
430### Environment Variables (Cloudflare)
431 
432`PUBLIC_*` vars are build-time and live in `dashboard/wrangler.toml` `[vars]` (and are also passed to the GitHub Actions build step). Everything else is a Cloudflare secret (`wrangler pages secret put <NAME>` or the Pages dashboard):
433 
434```bash
435# Clerk
436PUBLIC_CLERK_PUBLISHABLE_KEY=xxx   # [vars] — build-time
437CLERK_SECRET_KEY=xxx               # secret
438 
439# Data
440PUBLIC_COMPONENTS_JSON_URL=/components.json   # [vars] — build-time
441 
442# GitHub OAuth
443PUBLIC_GITHUB_CLIENT_ID=xxx        # [vars] — build-time
444GITHUB_CLIENT_SECRET=xxx           # secret
445 
446# Supabase (download tracking)
447SUPABASE_URL=https://xxx.supabase.co        # secret
448SUPABASE_SERVICE_ROLE_KEY=xxx               # secret
449 
450# Neon Database
451NEON_DATABASE_URL=postgresql://user:pass@host/db?sslmode=require   # secret
452 
453# Discord
454DISCORD_APP_ID=xxx                 # secret
455DISCORD_BOT_TOKEN=xxx              # secret
456DISCORD_PUBLIC_KEY=xxx             # secret
457DISCORD_WEBHOOK_URL_CHANGELOG=https://discord.com/api/webhooks/xxx   # secret
458```
459 
460### Known Issues & Solutions
461 
462**Node built-ins in SSR**
463- The Cloudflare Workers runtime does not expose Node's `fs`/`path`/etc. by default. `astro.config.mjs` enables `nodejs_compat` (via `wrangler.toml`) and externalizes `node:fs`, `node:path`, `node:url`, `node:stream` in SSR. Avoid adding new hard dependencies on Node-only APIs in server code.
464 
465**`react-dom/server` on Cloudflare**
466- `astro.config.mjs` aliases `react-dom/server` to `react-dom/server.node` and marks `react-dom` as `noExternal` at build time so React SSR works on the Workers runtime. Don't remove this alias.
467 
468### Local Development
469 
470```bash
471cd dashboard
472npm install
473npx astro dev --port 4321   # Dashboard + APIs at http://localhost:4321
474```
475 
476## Data Files
477 
478### Component Catalog
479 
480- `docs/components.json` — Full generated catalog (source of truth), keeps `content` and `security` fields (needed by the legacy static site)
481- `dashboard/public/components.json` — Dashboard copy, **without** `content`/`security` (lighter payload; dashboard doesn't need them)
482- `dashboard/public/counts.json` — Per-type counts only (e.g. `{"agents": 421, ...}`), used by the sidebar/plugins pages instead of loading the full catalog
483- `dashboard/public/components/{type}.json` — One file per component type (agents.json, commands.json, etc.), loaded on demand by `ComponentGrid.tsx` for the active tab
484- `dashboard/public/search-index.json` — Flat array for `SearchModal.tsx`
485- `dashboard/public/component-content/{type}/{slug}.json` — Full per-component content (incl. markdown body), fetched on demand when a component's detail view or PR flow needs it
486- `dashboard/public/trending-data.json` — Trending/download stats
487 
488All of the above are served as static Cloudflare Pages assets with
489`cache-control: public, max-age=86400, stale-while-revalidate=3600` (see
490`dashboard/public/_headers`).
491 
492### Data Flow
493 
4941. `scripts/generate_components_json.py` scans `cli-tool/components/`
4952. Generates `docs/components.json` (full, with `content`/`security`) and the split dashboard artifacts (`dashboard/public/components.json`, `counts.json`, `components/{type}.json`, `search-index.json`, `component-content/{type}/{slug}.json`) — these two writes are decoupled, so the dashboard payload stays lean without touching the legacy catalog
4963. Dashboard islands (`ComponentGrid.tsx`, `SearchModal.tsx`, `Sidebar.astro`, `SendToRepoModal.tsx`) load the split artifacts instead of the full catalog
4974. Download tracking via `/api/track-download-supabase`
498 
499### Plugins & Marketplaces Catalog
500 
501- `scripts/generate_plugins_json.py` — scans the repos listed in `REPOS` via the `gh` CLI (needs `gh auth login`) and writes `dashboard/public/plugins.json`. This is a **manual, offline step** — it does not run during `npm run build` or CI/CD, so re-running it never affects deploy time.
502- For each marketplace it records `plugins_list[].components` (counts per type) and `plugins_list[].components_items` (`{name, description}` per command/agent/skill/hook/mcp/lsp, description parsed from the item's frontmatter). The dashboard's `/plugins/[slug].astro` page renders this through `MarketplacePluginsList.tsx`, which shows a search box and a "view details" modal per plugin.
503- **`max_local_scans = 50`** in `extract_marketplace_plugins_detail()` caps how many *locally-sourced* plugins (i.e. `source: "./plugins/..."` within the marketplace's own repo) get scanned for real component names/descriptions, per marketplace, to bound GitHub API calls. Plugins beyond that cap (or plugins hosted in an external repo, which are never scanned) fall back to showing only tag badges in the modal, with no itemized breakdown — this is a graceful degradation, not an error.
504  - As of 2026-07-11, `anthropics/claude-plugins-official` alone has 51 locally-sourced plugins (out of 255 total), i.e. already at the edge of this cap. Bump `max_local_scans` if more complete coverage is needed — GitHub's rate limit (5000 req/hour authenticated) is not the constraint, wall-clock run time is (each item now costs 1 extra API call to fetch its file content for the description).
505 
506### Legacy Static Site (docs/)
507 
508The `docs/` directory contains the old static HTML site (no longer deployed to www). Blog articles in `docs/blog/` are still referenced externally.
509 
510### Blog Article Creation
511 
512Use the CLI skill to create blog articles:
513 
514```bash
515/create-blog-article @cli-tool/components/{type}/{category}/{name}.json
516```
517 
518This automatically:
5191. Generates AI cover image
5202. Creates HTML with SEO optimization
5213. Updates `docs/blog/blog-articles.json`
522 
523## Code Standards
524 
525### Path Handling
526- Use relative paths: `.claude/scripts/`, `.claude/hooks/`
527- Never hardcode absolute paths or home directories
528- Use `path.join()` for cross-platform compatibility
529 
530### Naming Conventions
531- Files: `kebab-case.js`, `PascalCase.js` (for classes)
532- Functions/Variables: `camelCase`
533- Constants: `UPPER_SNAKE_CASE`
534- Components: `hyphenated-names`
535 
536### Error Handling
537- Use try/catch for async operations
538- Provide helpful error messages
539- Log errors with context
540- Implement fallback mechanisms
541 
542## Testing
543 
544```bash
545npm test                 # Run all tests
546npm run test:watch      # Watch mode
547npm run test:coverage   # Coverage report
548```
549 
550Aim for 70%+ test coverage. Test critical paths and error handling.
551 
552## Common Issues
553 
554**API endpoint returns 404 after deploy**
555- API routes must be in `dashboard/src/pages/api/` as Astro API routes
556- Export named HTTP methods: `export const POST: APIRoute`, `export const GET: APIRoute`
557 
558**Download tracking not working**
559- Check Cloudflare Pages logs: `npx wrangler pages deployment tail --project-name=aitmpl-dashboard`
560- Verify environment variables / secrets in the Cloudflare Pages dashboard
561- Test endpoint manually with curl
562 
563**Components not updating on website**
564- Run `python scripts/generate_components_json.py` (writes both `docs/components.json` and the split `dashboard/public/` artifacts directly — no manual copy step)
565- Deploy and clear browser cache (artifacts are cached 24h at the edge, see `dashboard/public/_headers`)
566 
567## Important Notes
568 
569- **Component catalog**: Always regenerate after adding/modifying components
570- **API tests**: Required before production deploy (breaks download tracking)
571- **Secrets**: Never commit API keys (use environment variables)
572- **Paths**: Use relative paths for all project files
573- **Backwards compatibility**: Don't break existing component installations
574