agents-united 0.5.0

package/registry/skills/user-flow-mapping/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: user-flow-mapping
+description: Production-grade User Flow Mapping playbook for design operations,
+  UX systems, and growth strategy.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 🗺️
+disable-slash-command: true
+---
+
+# User Flow Mapping
+
+## Overview & Purpose
+The User Flow Mapping skill provides a deterministic framework for executing user flow mapping processes in modern software products.
+
+Following this skill ensures high usability, visual consistency, rapid iteration, and complete cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request to execute User Flow Mapping tasks.
+- Auditing existing product assets or workflows.
+- Standardizing user-flow-mapping procedures across team projects.
+- Preparing design handoffs or growth campaign launches.
+
+### Prerequisites
+- Project workspace configured with design system tokens or component libraries.
+- Target UI design specification or growth experiment hypothesis.
+- Testing and linting tools operational.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target UI component, page, or campaign scope |
+| `config` | Object | Optional | Specific parameters and threshold configurations |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/user-flow-mapping/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/user-flow-mapping/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/user-flow-mapping/summary.json` | Health check and audit metric results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Pre-Execution Discovery & Workspace Analysis
+1. Inspect workspace repository to locate relevant UI components, tokens, or campaign assets.
+   ```bash
+   find src/ docs/ -maxdepth 3 -type f
+   ```
+2. Analyze domain requirements and classify core UI elements, interaction flows, or growth metrics.
+3. Establish baseline quality metrics and target benchmarks.
+4. Verify working tree status to ensure clean git workspace.
+   ```bash
+   git status --short
+   ```
+5. Formulate initial execution plan.
+
+### Phase 2: Input Contract Validation & Strategy Selection
+1. Validate input parameters against technical feasibility and design system guidelines.
+2. Select implementation pattern matching component or campaign architecture.
+3. Establish verification rules and accessibility / conversion thresholds.
+4. Formulate atomic step-by-step execution sequence.
+5. Create temporary working directory if needed.
+
+### Phase 3: Core Step-by-Step Implementation Execution
+1. Author primary specification document at `docs/user-flow-mapping/spec.md`.
+2. Generate code, token, or layout implementation files.
+   ```bash
+   npm run typecheck
+   ```
+3. Apply automated formatting and linting tools.
+4. Execute unit or visual regression tests.
+   ```bash
+   npm test
+   ```
+5. Refactor asset structure for optimal performance and maintainability.
+
+### Phase 4: Verification, Testing & Quality Gate Checking
+1. Run full project verification suite.
+   ```bash
+   npm run typecheck && npm test && npm run build
+   ```
+2. Verify zero lint errors, type warnings, or broken references.
+3. Execute CLI health doctor check.
+   ```bash
+   node dist/cli.js doctor
+   ```
+4. Assert all acceptance criteria are satisfied.
+
+### Phase 5: Post-Execution Cleanup & Artifact Generation
+1. Generate execution summary report at `reports/user-flow-mapping/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/user-flow-mapping/ reports/user-flow-mapping/
+   git commit -m "feat(user-flow-mapping): implement User Flow Mapping playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: User Flow Mapping Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "user-flow-mapping"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/user-flow-mapping/summary.json"
+```
+
+### Exemplar 2: User Flow Mapping Helper Module
+```typescript
+export function runUserFlowMapping(scope: string): boolean {
+  console.log('Running User Flow Mapping on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in User Flow Mapping
+1. **Diagnosis**: Specification or code asset fails validation rules in user-flow-mapping.
+2. **Recovery Protocol**:
+   - Step 1: Inspect error log at reports directory.
+   - Step 2: Correct non-compliant syntax or structure.
+   - Step 3: Re-run verification pipeline.
+
+### Scenario B: Missing Resource for User Flow Mapping
+1. **Diagnosis**: Target design token or configuration asset missing from workspace.
+2. **Recovery Protocol**:
+   - Step 1: Generate baseline resource file from standard template.
+   - Step 2: Update configuration references.
+   - Step 3: Resume runbook execution.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/user-journey-mapping/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: user-journey-mapping
+description: Production-grade User Journey Mapping playbook for design
+  operations, UX systems, and growth strategy.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 🧭
+disable-slash-command: true
+---
+
+# User Journey Mapping
+
+## Overview & Purpose
+The User Journey Mapping skill provides a deterministic framework for executing user journey mapping processes in modern software products.
+
+Following this skill ensures high usability, visual consistency, rapid iteration, and complete cross-functional team alignment.
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Direct request to execute User Journey Mapping tasks.
+- Auditing existing product assets or workflows.
+- Standardizing user-journey-mapping procedures across team projects.
+- Preparing design handoffs or growth campaign launches.
+
+### Prerequisites
+- Project workspace configured with design system tokens or component libraries.
+- Target UI design specification or growth experiment hypothesis.
+- Testing and linting tools operational.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `target_scope` | String | Yes | Target UI component, page, or campaign scope |
+| `config` | Object | Optional | Specific parameters and threshold configurations |
+| `output_dir` | Directory Path | Optional | Destination directory for generated artifacts |
+| `strict_mode` | Boolean | Optional | Enforce strict zero-warning validation |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Specification Document | `docs/user-journey-mapping/spec.md` | Full specification and guidelines document |
+| Component / Asset Files | `src/user-journey-mapping/*` | Implemented design tokens, components, or campaign assets |
+| Audit Report | `reports/user-journey-mapping/summary.json` | Health check and audit metric results |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Pre-Execution Discovery & Workspace Analysis
+1. Inspect workspace repository to locate relevant UI components, tokens, or campaign assets.
+   ```bash
+   find src/ docs/ -maxdepth 3 -type f
+   ```
+2. Analyze domain requirements and classify core UI elements, interaction flows, or growth metrics.
+3. Establish baseline quality metrics and target benchmarks.
+4. Verify working tree status to ensure clean git workspace.
+   ```bash
+   git status --short
+   ```
+5. Formulate initial execution plan.
+
+### Phase 2: Input Contract Validation & Strategy Selection
+1. Validate input parameters against technical feasibility and design system guidelines.
+2. Select implementation pattern matching component or campaign architecture.
+3. Establish verification rules and accessibility / conversion thresholds.
+4. Formulate atomic step-by-step execution sequence.
+5. Create temporary working directory if needed.
+
+### Phase 3: Core Step-by-Step Implementation Execution
+1. Author primary specification document at `docs/user-journey-mapping/spec.md`.
+2. Generate code, token, or layout implementation files.
+   ```bash
+   npm run typecheck
+   ```
+3. Apply automated formatting and linting tools.
+4. Execute unit or visual regression tests.
+   ```bash
+   npm test
+   ```
+5. Refactor asset structure for optimal performance and maintainability.
+
+### Phase 4: Verification, Testing & Quality Gate Checking
+1. Run full project verification suite.
+   ```bash
+   npm run typecheck && npm test && npm run build
+   ```
+2. Verify zero lint errors, type warnings, or broken references.
+3. Execute CLI health doctor check.
+   ```bash
+   node dist/cli.js doctor
+   ```
+4. Assert all acceptance criteria are satisfied.
+
+### Phase 5: Post-Execution Cleanup & Artifact Generation
+1. Generate execution summary report at `reports/user-journey-mapping/summary.md`.
+2. Clean up temporary build artifacts and scratch files.
+3. Commit generated files to git repository.
+   ```bash
+   git add docs/user-journey-mapping/ reports/user-journey-mapping/
+   git commit -m "feat(user-journey-mapping): implement User Journey Mapping playbook artifacts"
+   ```
+4. Publish documentation for team review.
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: User Journey Mapping Configuration Specification
+```yaml
+version: "2.0.0"
+metadata:
+  skill: "user-journey-mapping"
+  author: "agents-united"
+rules:
+  strictValidation: true
+  reporting:
+    format: "json"
+    output: "reports/user-journey-mapping/summary.json"
+```
+
+### Exemplar 2: User Journey Mapping Helper Module
+```typescript
+export function runUserJourneyMapping(scope: string): boolean {
+  console.log('Running User Journey Mapping on:', scope);
+  return true;
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Validation Failure in User Journey Mapping
+1. **Diagnosis**: Specification or code asset fails validation rules in user-journey-mapping.
+2. **Recovery Protocol**:
+   - Step 1: Inspect error log at reports directory.
+   - Step 2: Correct non-compliant syntax or structure.
+   - Step 3: Re-run verification pipeline.
+
+### Scenario B: Missing Resource for User Journey Mapping
+1. **Diagnosis**: Target design token or configuration asset missing from workspace.
+2. **Recovery Protocol**:
+   - Step 1: Generate baseline resource file from standard template.
+   - Step 2: Update configuration references.
+   - Step 3: Resume runbook execution.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/skills/vector-database-design/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: vector-database-design
+description: Designing vector database schemas, HNSW index parameter tuning,
+  metadata filtering, and collection partitioning on Qdrant, Pinecone, and
+  Chroma.
+metadata:
+  author: Qdrant & Pinecone Community / agents-united
+  version: 2.0.0
+  license: MIT
+  icon: 🎯
+disable-slash-command: true
+---
+
+# Vector Database Design Playbook
+
+## Overview & Purpose
+`vector-database-design` outlines schema architectures, HNSW index parameter tuning, payload filtering optimization, and multi-tenant partitioning strategies across modern vector databases (Qdrant, Pinecone, Chroma).
+
+## When to Trigger
+Trigger this skill whenever:
+- Designing new vector database collection schemas and dimensionality configurations.
+- Tuning HNSW indexing parameters (`m`, `ef_construct`, `ef_search`) for speed vs. recall balance.
+- Setting up payload metadata indexing for low-latency pre-filtering in multi-tenant environments.
+- Partitioning collections across namespaces or tenant IDs to guarantee strict data isolation.
+
+## Input & Output Requirements
+- **Inputs**: Embedding dimension size (e.g. 1536, 768), expected vector count, distance metric (Cosine, Dot, Euclidean), and metadata filtering query requirements.
+- **Outputs**: Collection creation scripts, payload index definitions, connection pool configurations, and query latency benchmarks.
+
+## Step-by-Step Execution Runbook
+
+### Phase 1 — Schema Architecture & Distance Metric Selection
+- Align vector distance metric with the training objective of the embedding model (Cosine distance for normalized embeddings).
+- Allocate vector dimensionality strictly matching embedding model output.
+
+### Phase 2 — HNSW Parameter Tuning & Payload Indexing
+- Configure HNSW graph parameters: set `m=16` (edges per node) and `ef_construct=128` for high build-time quality.
+- Create payload indexes on categorical and filterable metadata fields (e.g. `tenant_id`, `created_at`, `category`).
+
+### Phase 3 — Verification & Latency Benchmarking
+- Measure vector ingestion throughput and run concurrent search queries.
+- Verify that filtered searches achieve < 50ms p95 latency at 1M+ vectors scale.
+
+## Edge Cases & Boundary Conditions
+- **High-Dimensionality Memory Overhead**: Use scalar or product quantization (SQ/PQ) in Qdrant/Pinecone to reduce RAM footprint by up to 75% with < 2% recall loss.
+- **Extreme Payload Imbalance**: Avoid indexing high-cardinality unique text strings in payload indexes.
+- **Cross-Tenant Data Leakage**: Enforce tenant ID filters at the query level or use separate namespaces per customer.
+
+## Error Recovery & Fallbacks
+- If vector insertion fails due to timeout during large batch upserts, split payloads into smaller batches of 256-512 vectors.
+- If search recall drops below 95%, increase `ef_search` from 64 to 128.
+
+## Code Exemplars & Patterns
+
+```python
+from qdrant_client import QdrantClient
+from qdrant_client.models import Distance, VectorParams, HnswConfigDiff, PayloadSchemaType
+
+client = QdrantClient(url="http://localhost:6333")
+
+# 1. Create collection with tuned HNSW parameters
+client.create_collection(
+    collection_name="enterprise_docs",
+    vectors_config=VectorParams(size=1536, distance=Distance.COSINE),
+    hnsw_config=HnswConfigDiff(
+        m=16,
+        ef_construct=128,
+        full_scan_threshold=10000,
+    )
+)
+
+# 2. Create payload indexes for fast pre-filtering
+client.create_payload_index(
+    collection_name="enterprise_docs",
+    field_name="tenant_id",
+    field_schema=PayloadSchemaType.KEYWORD
+)
+
+client.create_payload_index(
+    collection_name="enterprise_docs",
+    field_name="created_at",
+    field_schema=PayloadSchemaType.INTEGER
+)
+```

package/registry/skills/vercel-deploy-best-practices/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: vercel-deploy-best-practices
+description: Next.js and frontend deployment optimization on Vercel, Edge
+  Middleware, Incremental Static Regeneration (ISR), Server Actions, and Preview
+  environments.
+metadata:
+  author: Agents United Frontend Group
+  version: 1.0.0
+  license: MIT
+  icon: ▲
+disable-slash-command: true
+---
+
+# Vercel Deployment Best Practices Playbook
+
+## Overview & Purpose
+`vercel-deploy-best-practices` provides production deployment and configuration guidelines for Next.js, Remix, and static web applications hosted on Vercel.
+
+## Core Directives & Standards
+1. **Edge Middleware Routing** — Keep Edge Middleware execution < 25ms by avoiding heavy libraries or un-cached external network calls.
+2. **Incremental Static Regeneration (ISR)** — Configure `revalidate` intervals or on-demand revalidation (`revalidatePath`, `revalidateTag`) for dynamic content caching.
+3. **Environment Variable Hierarchy** — Separate `Development`, `Preview`, and `Production` environment variables securely with branch-specific overrides.
+4. **Vercel Web Analytics & Speed Insights** — Integrate `@vercel/analytics` and `@vercel/speed-insights` for real-user Core Web Vitals monitoring.
+5. **Serverless Function Concurrency** — Configure max duration limits and memory allocations in `vercel.json` to prevent billing surprises.
+
+## Verification Checklist
+- [ ] Preview deployments generate isolated database branch previews when paired with Neon/Supabase.
+- [ ] Zero unhandled Server Action errors in production logs.

package/registry/skills/viral-referral-loops/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: viral-referral-loops
+description: Production-grade Viral Referral Loops playbook for double-sided
+  incentive architectures, K-factor viral loop equations, in-app share
+  mechanics, and fraud-resistant referral engines.
+metadata:
+  author: agents-united
+  version: 2.0.0
+  icon: 🔄
+disable-slash-command: true
+---
+
+# Viral Referral Loops & Product-Led Organic Expansion Architecture
+
+## Overview & Purpose
+The Viral Referral Loops skill provides a comprehensive mathematical and product engineering framework for designing, implementing, and scaling high-velocity referral loops in product-led growth (PLG) SaaS platforms.
+
+Following this skill designs double-sided reward incentives, contextual trigger timing (leveraging the peak-end rule and satisfaction milestones), seamless modal and clipboard share interactions, server-side fraud prevention mechanisms, and mathematical tracking of viral coefficient ($K$-factor) and cycle time ($c_t$).
+
+## Execution Triggers & Prerequisites
+### Execution Triggers
+- Designing customer referral programs to lower blended Customer Acquisition Cost (CAC).
+- Engineering viral product loops (collaboration invites, public share links, powered-by badges).
+- Optimizing referral conversion rates from invitation sent to referee account activation.
+- Implementing fraud detection rules for self-referrals and reward gaming.
+
+### Prerequisites
+- Product analytics tracking user engagement events and milestone completions.
+- Relational database schema supporting referral links, attribution tokens, and ledger credits.
+- Transactional email / notification service for sending referee invitation alerts.
+- Clean git working directory.
+
+## Input & Output Requirements
+### Inputs
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `incentive_type` | String | Yes | `double_sided_credit`, `extended_trial`, `feature_unlock`, `revenue_share` |
+| `referrer_reward` | Number | Yes | Value granted to existing user upon successful referee activation |
+| `referee_reward` | Number | Yes | Value granted to invited user upon signup |
+| `target_k_factor` | Number | Optional | Target viral coefficient (e.g. 0.35) |
+| `qualification_criteria`| String | Yes | Milestone referee must hit before reward is unlocked (e.g. `first_project_run`) |
+
+### Outputs
+| Artifact | Path / Format | Description |
+|---|---|---|
+| Viral Loop Spec Spec | `docs/viral-referral-loops/referral-spec.md` | Formulas, user journey diagrams, reward tiers |
+| Referral Modal Component | `src/components/referral/ReferralModal.tsx` | Share links, social intents, reward tracker |
+| Referral Engine Service | `src/services/growth/referral-engine.ts` | Token generation, attribution, fraud validation |
+| Viral Analytics Report | `reports/viral-referral-loops/k-factor-summary.json`| $K$-factor, cycle time, and invite conversion stats |
+
+## Step-by-Step Execution Runbook
+
+### Phase 1: Mathematical Modeling & Double-Sided Incentive Structuring
+1. Formulate the Viral Coefficient equation:
+   $$K = i \times c$$
+   where $i$ is the average number of invitations sent per user, and $c$ is the conversion rate of each invitation into an active user.
+2. Formulate the Viral Cycle Time ($c_t$) minimization target: reducing the time from user signup to sending invitations directly multiplies organic user growth rate.
+3. Structure double-sided reward mechanics: align incentives so both parties win (e.g. "$25 in API credits for you, $25 for your friend upon their first build").
+4. Establish reward qualification thresholds: require referees to achieve a meaningful product action before distributing credits to eliminate bot abuse.
+
+### Phase 2: Contextual In-App Trigger Identification
+1. Identify high-satisfaction moments in the product journey to present referral prompts:
+   - Immediately after completing a successful build or workflow run.
+   - Upon receiving a positive NPS/CSAT score (rating 9 or 10).
+   - After saving significant compute hours or achieving milestone productivity goals.
+2. Avoid presenting referral modals during onboarding setup, high-friction configuration tasks, or error states.
+
+### Phase 3: Frictionless Share Modal & One-Click Social Intent Implementation
+1. Generate unique, short, human-readable referral codes and URLs (e.g. `https://agents-united.dev/join?ref=alex2026`).
+2. Build responsive referral modal offering:
+   - 1-Click "Copy Link" button with instant visual tooltip confirmation.
+   - Pre-populated social share intents for Twitter/X, LinkedIn, and WhatsApp.
+   - Direct email invitation input box supporting comma-separated teammate invites.
+3. Include real-time reward ledger showing "Pending", "Earned", and "Redeemed" reward statuses.
+
+### Phase 4: Fraud Prevention, Attribution Cookies & Ledger Security
+1. Set 30-day first-party referral tracking cookie on landing page visits from referral links.
+2. Implement strict fraud defense guardrails:
+   - IP rate-limiting and device fingerprint hashing to detect self-referrals.
+   - Domain matching checks: disallow referring users within the same enterprise workspace domain if rewards are personal credits.
+   - Hold period: place rewards in pending state for 48 hours to prevent payment chargeback abuse.
+3. Record all credit accruals and redemptions in an immutable ledger database table.
+
+### Phase 5: K-Factor Analytics & Viral Funnel Optimization
+1. Instrument telemetry events: `referral_modal_viewed`, `referral_link_copied`, `invite_sent`, `referee_landed`, `referee_activated`, `reward_unlocked`.
+2. Calculate weekly cohort $K$-factor and channel conversion metrics.
+3. Run A/B tests on share modal headlines, reward descriptions, and trigger placement timing.
+4. Compile performance summary at `reports/viral-referral-loops/k-factor-summary.json`.
+5. Commit referral loop components to repository.
+   ```bash
+   git add src/components/referral/ src/services/growth/ docs/viral-referral-loops/
+   git commit -m "feat(viral-referral-loops): implement double-sided referral engine and fraud guardrails"
+   ```
+
+## Code & Configuration Exemplars
+
+### Exemplar 1: TypeScript Referral Token Generation & Attribution Service
+```typescript
+import crypto from 'node:crypto';
+
+export interface ReferralAttribution {
+  referrerId: string;
+  refereeId: string;
+  referralCode: string;
+  status: 'pending' | 'qualified' | 'rewarded' | 'flagged';
+  createdAt: string;
+}
+
+export function generateReferralCode(userId: string): string {
+  const hash = crypto.createHash('sha256').update(userId).digest('hex').slice(0, 8);
+  return `AU-${hash.toUpperCase()}`;
+}
+
+export function validateReferralLegitimacy(referrerIp: string, refereeIp: string, referrerDomain: string, refereeEmail: string): boolean {
+  // Reject identical IP address self-referral attempts
+  if (referrerIp === refereeIp && process.env.NODE_ENV === 'production') {
+    return false;
+  }
+  // Reject internal domain match if corporate domain
+  const refereeDomain = refereeEmail.split('@')[1]?.toLowerCase();
+  const genericDomains = ['gmail.com', 'yahoo.com', 'outlook.com', 'icloud.com'];
+  if (refereeDomain && !genericDomains.includes(refereeDomain) && refereeDomain === referrerDomain.toLowerCase()) {
+    return false;
+  }
+  return true;
+}
+```
+
+### Exemplar 2: TypeScript React Referral Share Modal Component
+```typescript
+import React, { useState } from 'react';
+
+export interface ReferralModalProps {
+  referralCode: string;
+  earnedCreditsUsd: number;
+  pendingCount: number;
+  isOpen: boolean;
+  onClose: () => void;
+}
+
+export function ReferralModal({ referralCode, earnedCreditsUsd, pendingCount, isOpen, onClose }: ReferralModalProps): React.JSX.Element | null {
+  const [copied, setCopied] = useState(false);
+  if (!isOpen) return null;
+
+  const shareUrl = `https://agents-united.dev/join?ref=${referralCode}`;
+
+  const handleCopy = () => {
+    navigator.clipboard.writeText(shareUrl);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50 p-4">
+      <div className="bg-white rounded-2xl max-w-md w-full p-6 shadow-2xl">
+        <h2 className="text-xl font-bold text-gray-900 mb-2">Give $25, Get $25</h2>
+        <p className="text-sm text-gray-600 mb-6">
+          Invite teammates or friends. When they execute their first workflow, you both get $25 in compute credits.
+        </p>
+        <div className="flex items-center gap-2 bg-gray-100 p-2 rounded-lg mb-6">
+          <input type="text" readOnly value={shareUrl} className="bg-transparent text-sm w-full outline-none px-2 text-gray-700 font-mono" />
+          <button onClick={handleCopy} className="bg-blue-600 hover:bg-blue-700 text-white text-xs font-semibold px-4 py-2 rounded-md transition-colors">
+            {copied ? 'Copied!' : 'Copy'}
+          </button>
+        </div>
+        <div className="flex justify-between items-center bg-blue-50 p-4 rounded-xl mb-6">
+          <div>
+            <div className="text-xs text-blue-700 font-medium">Earned Credits</div>
+            <div className="text-xl font-bold text-blue-900">${earnedCreditsUsd}</div>
+          </div>
+          <div>
+            <div className="text-xs text-blue-700 font-medium">Pending Invites</div>
+            <div className="text-xl font-bold text-blue-900">{pendingCount}</div>
+          </div>
+        </div>
+        <button onClick={onClose} className="w-full text-center text-sm font-medium text-gray-500 hover:text-gray-700 py-2">
+          Close
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Edge Cases & Error Recovery Procedures
+
+### Scenario A: Referral Link Clicked by Existing Active User
+1. **Diagnosis**: An existing user clicks an invitation link expecting a bonus credit.
+2. **Recovery Protocol**:
+   - Step 1: Detect that the user already has an active account upon landing on the auth page.
+   - Step 2: Display polite message explaining that referral credits apply exclusively to new accounts.
+   - Step 3: Redirect user to their own referral dashboard to invite others instead.
+
+### Scenario B: Referral Attribution Cookie Blocked by Safari ITP or Brave
+1. **Diagnosis**: Browser privacy features wipe 30-day tracking cookie before user finishes signup.
+2. **Recovery Protocol**:
+   - Step 1: Provide fallback manual promo code entry box on final signup step.
+   - Step 2: Store referral attribution token in server-side session state alongside anonymous visitor ID.
+   - Step 3: Re-associate attribution upon signup completion via server-side session matching.
+
+## Verification & Validation Checklist
+- [ ] Frontmatter conforms strictly to `author: "agents-united"` and `version: "2.0.0"`.
+- [ ] All 7 mandatory sections present with explicit headers.
+- [ ] Step-by-Step Execution Runbook body contains >= 50 lines.
+- [ ] Viral coefficient $K$-factor and cycle time equations documented.
+- [ ] Fraud defense rules (IP checks, domain validation, hold period) detailed.
+- [ ] Code exemplars provided with valid syntax fencing.
+- [ ] Zero dummy placeholder strings or unpopulated template markers present.
+- [ ] Project build, test suite, and doctor check pass 100% cleanly.

package/registry/workflows/workflow-agency-ad-creative-sprint.md

@@ -0,0 +1,50 @@
+---
+name: "Agency Multi-Channel Ad Creative Sprint"
+description: "Rapid multi-variant ad copywriting, banner layout generation, and A/B test matrix construction across Meta, Google, and LinkedIn."
+bundle: "digital-agency"
+estimatedDuration: "45-90m"
+---
+
+# Workflow: Agency Multi-Channel Ad Creative Sprint
+
+## Overview & Scope
+Coordinates rapid ad creative authoring, visual layout composition, and copy variant generation across paid social and search channels.
+
+## Execution Flowchart
+```mermaid
+graph TD
+    Start([Brief Intake]) --> P1[Phase 1: Angle & Hook Formulation]
+    P1 --> P2[Phase 2: Copywriting & Aspect Ratio Layouts]
+    P2 --> Gate1{"Visual Quality & Token Conformance?"}
+    Gate1 -->|Fail| P2
+    Gate1 -->|Pass| P3[Phase 3: Creative Matrix Review & Export]
+    P3 --> Done([Sprint Complete])
+```
+
+## Required Tool Inputs & Context
+- Target ICP pain points & value propositions
+- Aspect ratio specifications (1:1, 9:16, 16:9, 1.91:1)
+- MCP Stitch / Figma integration or native image assets
+
+## Phase 1: Context & Hooks
+- Determine 3 core angles (Pain-led, Feature-led, Social Proof-led).
+- Structure hook variations for each angle.
+
+## Phase 2: Copy & Creative Generation
+- Write primary text, headlines (under 40 chars), and CTA button copy.
+- Generate asset layouts adhering to brand color tokens.
+
+## Phase 3: Verification & Export
+- Validate visual hierarchy, legibility on mobile, and ad network policy compliance.
+- Export ready-to-launch creative matrix in markdown/JSON.
+
+## Phase Transition Criteria & Deterministic Verification Gates
+| Transition | Prerequisites | Verification Command / Gate | Success Criteria |
+|---|---|---|---|
+| Phase 1 -> Phase 2 | Angles formulated | `node dist/cli.js doctor` | Doctor health check succeeds with 0 errors |
+| Phase 2 -> Phase 3 | Layouts generated | `npm test` | Format and dimension checks pass 100% |
+| Phase 3 -> Completion | Final matrix reviewed | `npm run build` | All assets formatted and validated |
+
+## Validation Checkpoints & Automated Rollback Protocols
+- **Validation Checkpoint 1**: Ad copy conforms to advertising platform compliance guidelines.
+- **Automated Rollback Protocol**: Re-generate copy variants if headline exceeds character constraints.