@intentsolutionsio/vercel-pack 1.0.0 → 1.0.3

package/skills/vercel-advanced-troubleshooting/references/evidence-collection-framework.md

@@ -0,0 +1,34 @@
+# Evidence Collection Framework
+
+## Evidence Collection Framework
+
+### Comprehensive Debug Bundle
+
+```bash
+#!/bin/bash
+# advanced-vercel-debug.sh
+
+BUNDLE="vercel-advanced-debug-$(date +%Y%m%d-%H%M%S)"
+mkdir -p "$BUNDLE"/{logs,metrics,network,config,traces}
+
+# 1. Extended logs (1 hour window)
+kubectl logs -l app=vercel-integration --since=1h > "$BUNDLE/logs/pods.log"
+journalctl -u vercel-service --since "1 hour ago" > "$BUNDLE/logs/system.log"
+
+# 2. Metrics dump
+curl -s localhost:9090/api/v1/query?query=vercel_requests_total > "$BUNDLE/metrics/requests.json"
+curl -s localhost:9090/api/v1/query?query=vercel_errors_total > "$BUNDLE/metrics/errors.json"
+
+# 3. Network capture (30 seconds)
+timeout 30 tcpdump -i any port 443 -w "$BUNDLE/network/capture.pcap" &
+
+# 4. Distributed traces
+curl -s localhost:16686/api/traces?service=vercel > "$BUNDLE/traces/jaeger.json"
+
+# 5. Configuration state
+kubectl get cm vercel-config -o yaml > "$BUNDLE/config/configmap.yaml"
+kubectl get secret vercel-secrets -o yaml > "$BUNDLE/config/secrets-redacted.yaml"
+
+tar -czf "$BUNDLE.tar.gz" "$BUNDLE"
+echo "Advanced debug bundle: $BUNDLE.tar.gz"
+```

package/skills/vercel-advanced-troubleshooting/references/examples.md

@@ -0,0 +1,11 @@
+## Examples
+
+### Quick Layer Test
+
+```bash
+# Test each layer in sequence
+curl -v https://api.vercel.com/health 2>&1 | grep -E "(Connected|TLS|HTTP)"
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-advanced-troubleshooting/references/systematic-isolation.md

@@ -0,0 +1,56 @@
+# Systematic Isolation
+
+## Systematic Isolation
+
+### Layer-by-Layer Testing
+
+```typescript
+// Test each layer independently
+async function diagnoseVercelIssue(): Promise<DiagnosisReport> {
+  const results: DiagnosisResult[] = [];
+
+  // Layer 1: Network connectivity
+  results.push(await testNetworkConnectivity());
+
+  // Layer 2: DNS resolution
+  results.push(await testDNSResolution('api.vercel.com'));
+
+  // Layer 3: TLS handshake
+  results.push(await testTLSHandshake('api.vercel.com'));
+
+  // Layer 4: Authentication
+  results.push(await testAuthentication());
+
+  // Layer 5: API response
+  results.push(await testAPIResponse());
+
+  // Layer 6: Response parsing
+  results.push(await testResponseParsing());
+
+  return { results, firstFailure: results.find(r => !r.success) };
+}
+```
+
+### Minimal Reproduction
+
+```typescript
+// Strip down to absolute minimum
+async function minimalRepro(): Promise<void> {
+  // 1. Fresh client, no customization
+  const client = new VercelClient({
+    apiKey: process.env.VERCEL_API_KEY!,
+  });
+
+  // 2. Simplest possible call
+  try {
+    const result = await client.ping();
+    console.log('Ping successful:', result);
+  } catch (error) {
+    console.error('Ping failed:', {
+      message: error.message,
+      code: error.code,
+      stack: error.stack,
+    });
+  }
+}
+```

package/skills/vercel-advanced-troubleshooting/references/timing-analysis.md

@@ -0,0 +1,35 @@
+# Timing Analysis
+
+## Timing Analysis
+
+```typescript
+class TimingAnalyzer {
+  private timings: Map<string, number[]> = new Map();
+
+  async measure<T>(label: string, fn: () => Promise<T>): Promise<T> {
+    const start = performance.now();
+    try {
+      return await fn();
+    } finally {
+      const duration = performance.now() - start;
+      const existing = this.timings.get(label) || [];
+      existing.push(duration);
+      this.timings.set(label, existing);
+    }
+  }
+
+  report(): TimingReport {
+    const report: TimingReport = {};
+    for (const [label, times] of this.timings) {
+      report[label] = {
+        count: times.length,
+        min: Math.min(...times),
+        max: Math.max(...times),
+        avg: times.reduce((a, b) => a + b, 0) / times.length,
+        p95: this.percentile(times, 95),
+      };
+    }
+    return report;
+  }
+}
+```

package/skills/vercel-architecture-variants/SKILL.md

@@ -1,284 +1,295 @@
 ---
 name: vercel-architecture-variants
-description: |
-  Choose and implement Vercel validated architecture blueprints for different scales.
-  Use when designing new Vercel integrations, choosing between monolith/service/microservice
-  architectures, or planning migration paths for Vercel applications.
+description: 'Choose and implement Vercel architecture blueprints for different scales
+  and use cases.
+
+  Use when designing new Vercel projects, choosing between static, serverless, and
+  edge architectures,
+
+  or planning how to structure a multi-project Vercel deployment.
+
   Trigger with phrases like "vercel architecture", "vercel blueprint",
-  "how to structure vercel", "vercel project layout", "vercel microservice".
-allowed-tools: Read, Grep
+
+  "how to structure vercel", "vercel monorepo", "vercel multi-project".
+
+  '
+allowed-tools: Read, Write, Edit, Grep
 version: 1.0.0
 license: MIT
 author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+- saas
+- vercel
+- architecture
+- scaling
+- patterns
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
-
 # Vercel Architecture Variants
 
 ## Overview
-Three validated architecture blueprints for Vercel integrations.
+
+Choose the right Vercel architecture based on team size, traffic patterns, and technical requirements. Covers five validated blueprints from static site to multi-project enterprise deployment, with migration paths between them.
 
 ## Prerequisites
-- Understanding of team size and DAU requirements
-- Knowledge of deployment infrastructure
+
+- Understanding of team size and traffic requirements
+- Knowledge of Vercel deployment model (edge, serverless, static)
 - Clear SLA requirements
-- Growth projections available
 
-## Variant A: Monolith (Simple)
+## Instructions
+
+### Variant 1: Static Site (JAMstack)
 
-**Best for:** MVPs, small teams, < 10K daily active users
+**Best for:** Marketing sites, docs, blogs, landing pages
+**Team size:** 1-3 developers
+**Traffic:** Any (fully CDN-served)
 
 ```
-my-app/
+project/
+├── public/           # Static assets
 ├── src/
-│   ├── vercel/
-│   │   ├── client.ts          # Singleton client
-│   │   ├── types.ts           # Types
-│   │   └── middleware.ts      # Express middleware
-│   ├── routes/
-│   │   └── api/
-│   │       └── vercel.ts    # API routes
-│   └── index.ts
-├── tests/
-│   └── vercel.test.ts
+│   ├── pages/        # Static pages (SSG)
+│   └── components/   # React components
+├── vercel.json       # Headers, redirects
 └── package.json
 ```
 
-### Key Characteristics
-- Single deployment unit
-- Synchronous Vercel calls in request path
-- In-memory caching
-- Simple error handling
-
-### Code Pattern
-```typescript
-// Direct integration in route handler
-app.post('/api/create', async (req, res) => {
-  try {
-    const result = await vercelClient.create(req.body);
-    res.json(result);
-  } catch (error) {
-    res.status(500).json({ error: error.message });
-  }
-});
+```json
+// vercel.json
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "Cache-Control", "value": "public, max-age=3600, stale-while-revalidate=86400" }
+      ]
+    }
+  ]
+}
 ```
 
----
+**Key decisions:**
+
+- No serverless functions needed
+- All pages pre-rendered at build time
+- ISR for pages that update periodically
+- Cost: minimal (mostly bandwidth)
 
-## Variant B: Service Layer (Moderate)
+### Variant 2: Full-Stack Next.js (Most Common)
 
-**Best for:** Growing startups, 10K-100K DAU, multiple integrations
+**Best for:** SaaS applications, dashboards, e-commerce
+**Team size:** 2-10 developers
+**Traffic:** Low to high
 
 ```
-my-app/
+project/
 ├── src/
-│   ├── services/
-│   │   ├── vercel/
-│   │   │   ├── client.ts      # Client wrapper
-│   │   │   ├── service.ts     # Business logic
-│   │   │   ├── repository.ts  # Data access
-│   │   │   └── types.ts
-│   │   └── index.ts           # Service exports
-│   ├── controllers/
-│   │   └── vercel.ts
-│   ├── routes/
-│   ├── middleware/
-│   ├── queue/
-│   │   └── vercel-processor.ts  # Async processing
-│   └── index.ts
-├── config/
-│   └── vercel/
+│   ├── app/
+│   │   ├── api/           # Serverless API routes
+│   │   ├── (marketing)/   # Static public pages
+│   │   └── dashboard/     # Dynamic authenticated pages
+│   ├── lib/               # Shared utilities
+│   ├── components/        # UI components
+│   └── middleware.ts      # Edge auth + routing
+├── prisma/                # Database schema
+├── vercel.json
 └── package.json
 ```
 
-### Key Characteristics
-- Separation of concerns
-- Background job processing
-- Redis caching
-- Circuit breaker pattern
-- Structured error handling
-
-### Code Pattern
-```typescript
-// Service layer abstraction
-class VercelService {
-  constructor(
-    private client: VercelClient,
-    private cache: CacheService,
-    private queue: QueueService
-  ) {}
-
-  async createResource(data: CreateInput): Promise<Resource> {
-    // Business logic before API call
-    const validated = this.validate(data);
-
-    // Check cache
-    const cached = await this.cache.get(cacheKey);
-    if (cached) return cached;
-
-    // API call with retry
-    const result = await this.withRetry(() =>
-      this.client.create(validated)
-    );
-
-    // Cache result
-    await this.cache.set(cacheKey, result, 300);
-
-    // Async follow-up
-    await this.queue.enqueue('vercel.post-create', result);
-
-    return result;
+```json
+// vercel.json
+{
+  "regions": ["iad1"],
+  "functions": {
+    "src/app/api/**/*.ts": {
+      "maxDuration": 30,
+      "memory": 1024
+    }
   }
 }
 ```
 
----
+**Key decisions:**
 
-## Variant C: Microservice (Complex)
+- Mixed rendering: SSG for marketing, SSR for dashboard
+- API routes in `app/api/` for backend logic
+- Edge Middleware for auth (runs before every request)
+- Database in same region as functions
 
-**Best for:** Enterprise, 100K+ DAU, strict SLAs
+### Variant 3: API-Only Backend
+
+**Best for:** Mobile app backends, microservices, webhook processors
+**Team size:** 1-5 developers
+**Traffic:** API-driven
 
 ```
-vercel-service/              # Dedicated microservice
-├── src/
-│   ├── api/
-│   │   ├── grpc/
-│   │   │   └── vercel.proto
-│   │   └── rest/
-│   │       └── routes.ts
-│   ├── domain/
-│   │   ├── entities/
-│   │   ├── events/
-│   │   └── services/
-│   ├── infrastructure/
-│   │   ├── vercel/
-│   │   │   ├── client.ts
-│   │   │   ├── mapper.ts
-│   │   │   └── circuit-breaker.ts
-│   │   ├── cache/
-│   │   ├── queue/
-│   │   └── database/
-│   └── index.ts
-├── config/
-├── k8s/
-│   ├── deployment.yaml
-│   ├── service.yaml
-│   └── hpa.yaml
+project/
+├── api/                   # Serverless functions (one per route)
+│   ├── users/
+│   │   ├── index.ts       # GET/POST /api/users
+│   │   └── [id].ts        # GET/PUT/DELETE /api/users/:id
+│   ├── webhooks/
+│   │   └── stripe.ts      # POST /api/webhooks/stripe
+│   └── health.ts          # GET /api/health
+├── lib/                   # Shared utilities
+├── vercel.json
 └── package.json
+```
 
-other-services/
-├── order-service/       # Calls vercel-service
-├── payment-service/
-└── notification-service/
+```json
+// vercel.json
+{
+  "regions": ["iad1", "cdg1"],
+  "rewrites": [
+    { "source": "/v1/(.*)", "destination": "/api/$1" }
+  ],
+  "headers": [
+    {
+      "source": "/api/(.*)",
+      "headers": [
+        { "key": "Access-Control-Allow-Origin", "value": "https://myapp.com" },
+        { "key": "Access-Control-Allow-Methods", "value": "GET,POST,PUT,DELETE" }
+      ]
+    }
+  ]
+}
 ```
 
-### Key Characteristics
-- Dedicated Vercel microservice
-- gRPC for internal communication
-- Event-driven architecture
-- Database per service
-- Kubernetes autoscaling
-- Distributed tracing
-- Circuit breaker per service
-
-### Code Pattern
-```typescript
-// Event-driven with domain isolation
-class VercelAggregate {
-  private events: DomainEvent[] = [];
-
-  process(command: VercelCommand): void {
-    // Domain logic
-    const result = this.execute(command);
-
-    // Emit domain event
-    this.events.push(new VercelProcessedEvent(result));
-  }
+**Key decisions:**
 
-  getUncommittedEvents(): DomainEvent[] {
-    return [...this.events];
-  }
-}
+- No frontend — pure API
+- CORS headers for cross-origin access
+- Version routing via rewrites (`/v1/*` → `/api/*`)
+- Multi-region for global API latency
 
-// Event handler
-@EventHandler(VercelProcessedEvent)
-class VercelEventHandler {
-  async handle(event: VercelProcessedEvent): Promise<void> {
-    // Saga orchestration
-    await this.sagaOrchestrator.continue(event);
-  }
+### Variant 4: Monorepo with Turborepo
+
+**Best for:** Multiple related apps, shared component libraries
+**Team size:** 5-20 developers
+**Traffic:** Varies per app
+
+```
+monorepo/
+├── apps/
+│   ├── web/               # Main website (Vercel project 1)
+│   │   ├── src/
+│   │   ├── vercel.json
+│   │   └── package.json
+│   ├── docs/              # Documentation site (Vercel project 2)
+│   │   ├── src/
+│   │   ├── vercel.json
+│   │   └── package.json
+│   └── admin/             # Admin dashboard (Vercel project 3)
+│       ├── src/
+│       ├── vercel.json
+│       └── package.json
+├── packages/
+│   ├── ui/                # Shared component library
+│   ├── config/            # Shared ESLint, TS config
+│   └── utils/             # Shared utilities
+├── turbo.json
+├── pnpm-workspace.yaml
+└── package.json
+```
+
+Vercel auto-detects monorepos and builds only the affected app:
+
+```json
+// apps/web/vercel.json
+{
+  "ignoreCommand": "npx turbo-ignore"
 }
 ```
 
----
+Each app in `apps/` is a separate Vercel project with its own domain, env vars, and deployment settings.
 
-## Decision Matrix
+### Variant 5: Multi-Zone Micro-Frontends (Enterprise)
 
-| Factor | Monolith | Service Layer | Microservice |
-|--------|----------|---------------|--------------|
-| Team Size | 1-5 | 5-20 | 20+ |
-| DAU | < 10K | 10K-100K | 100K+ |
-| Deployment Frequency | Weekly | Daily | Continuous |
-| Failure Isolation | None | Partial | Full |
-| Operational Complexity | Low | Medium | High |
-| Time to Market | Fastest | Moderate | Slowest |
+**Best for:** Large organizations with independent teams
+**Team size:** 20+ developers across multiple teams
+**Traffic:** High
 
-## Migration Path
+```
+Each zone is an independent Vercel project:
+
+Zone 1: marketing.company.com → Marketing team's Next.js app
+Zone 2: app.company.com → Product team's Next.js app
+Zone 3: docs.company.com → Docs team's Next.js app
+Zone 4: api.company.com → Platform team's API-only project
 
+Main project uses multi-zones (next.config.js):
 ```
-Monolith → Service Layer:
-1. Extract Vercel code to service/
-2. Add caching layer
-3. Add background processing
-
-Service Layer → Microservice:
-1. Create dedicated vercel-service repo
-2. Define gRPC contract
-3. Add event bus
-4. Deploy to Kubernetes
-5. Migrate traffic gradually
+
+```javascript
+// Main app: next.config.js
+module.exports = {
+  async rewrites() {
+    return [
+      {
+        source: '/docs/:path*',
+        destination: 'https://docs.company.com/docs/:path*',
+      },
+      {
+        source: '/blog/:path*',
+        destination: 'https://marketing.company.com/blog/:path*',
+      },
+    ];
+  },
+};
 ```
 
-## Instructions
+**Key decisions:**
+
+- Independent deploy cycles per team
+- Shared auth via Edge Middleware or external IdP
+- Consistent design system via shared npm packages
+- Each zone has its own env vars and scaling
 
-### Step 1: Assess Requirements
-Use the decision matrix to identify appropriate variant.
+## Architecture Decision Matrix
 
-### Step 2: Choose Architecture
-Select Monolith, Service Layer, or Microservice based on needs.
+| Factor | Static | Full-Stack | API-Only | Monorepo | Multi-Zone |
+|--------|--------|-----------|----------|----------|------------|
+| Team size | 1-3 | 2-10 | 1-5 | 5-20 | 20+ |
+| Deploy independence | N/A | Single | Single | Per-app | Per-team |
+| Frontend | Yes | Yes | No | Yes | Yes |
+| Database | No | Yes | Yes | Per-app | Per-zone |
+| Complexity | Low | Medium | Low | Medium | High |
+| Cost | Low | Medium | Low | Medium | High |
 
-### Step 3: Implement Structure
-Set up project layout following the chosen blueprint.
+## Migration Path
 
-### Step 4: Plan Migration Path
-Document upgrade path for future scaling.
+```
+Static Site → Full-Stack Next.js → Monorepo → Multi-Zone
+     ↑              ↑                  ↑           ↑
+   Start here    Add API routes    Add shared    Split teams
+                 Add auth          packages      Independent
+                 Add database                    deployments
+```
 
 ## Output
-- Architecture variant selected
-- Project structure implemented
-- Migration path documented
-- Appropriate patterns applied
+
+- Architecture variant selected based on team size and requirements
+- Project structure implemented following the chosen blueprint
+- Vercel configuration optimized for the architecture
+- Migration path documented for future scaling
 
 ## Error Handling
-| Issue | Cause | Solution |
+
+| Error | Cause | Solution |
 |-------|-------|----------|
-| Over-engineering | Wrong variant choice | Start simpler |
-| Performance issues | Wrong layer | Add caching/async |
-| Team friction | Complex architecture | Simplify or train |
-| Deployment complexity | Microservice overhead | Consider service layer |
-
-## Examples
-
-### Quick Variant Check
-```bash
-# Count team size and DAU to select variant
-echo "Team: $(git log --format='%ae' | sort -u | wc -l) developers"
-echo "DAU: Check analytics dashboard"
-```
+| Monorepo builds all apps | Missing `ignoreCommand` | Add `npx turbo-ignore` |
+| Multi-zone routing conflict | Overlapping paths | Ensure rewrites don't conflict |
+| Shared package not found | pnpm workspace misconfigured | Check `pnpm-workspace.yaml` includes |
+| API-only 404 on root | No `public/index.html` | Add a minimal index or redirect |
 
 ## Resources
-- [Monolith First](https://martinfowler.com/bliki/MonolithFirst.html)
-- [Microservices Guide](https://martinfowler.com/microservices/)
-- [Vercel Architecture Guide](https://vercel.com/docs/architecture)
+
+- [Vercel Monorepos](https://vercel.com/docs/monorepos)
+- [Turborepo on Vercel](https://vercel.com/docs/monorepos/turborepo)
+- [Next.js Multi-Zones](https://nextjs.org/docs/app/building-your-application/deploying/multi-zones)
+- [Vercel Project Structure](https://vercel.com/docs/project-configuration)
 
 ## Next Steps
-For common anti-patterns, see `vercel-known-pitfalls`.
+
+For known pitfalls and anti-patterns, see `vercel-known-pitfalls`.

package/skills/vercel-architecture-variants/references/errors.md

@@ -0,0 +1,11 @@
+# Error Handling Reference
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Over-engineering | Wrong variant choice | Start simpler |
+| Performance issues | Wrong layer | Add caching/async |
+| Team friction | Complex architecture | Simplify or train |
+| Deployment complexity | Microservice overhead | Consider service layer |
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

package/skills/vercel-architecture-variants/references/examples.md

@@ -0,0 +1,12 @@
+## Examples
+
+### Quick Variant Check
+
+```bash
+# Count team size and DAU to select variant
+echo "Team: $(git log --format='%ae' | sort -u | wc -l) developers"
+echo "DAU: Check analytics dashboard"
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*