100xprism 2.3.1

package/modules/referral-program/references/affiliate-programs.md

@@ -0,0 +1,164 @@
+# Affiliate Program Design
+
+Detailed guidance for building and managing affiliate programs.
+
+## Contents
+- Commission Structures
+- Cookie Duration
+- Affiliate Recruitment
+- Affiliate Enablement
+- Tools & Platforms (Referral Program Tools, Affiliate Program Tools, Choosing a Tool)
+- Fraud Prevention (Common Referral Fraud, Prevention Measures)
+
+## Commission Structures
+
+**Percentage of sale:**
+- Standard: 10-30% of first sale or first year
+- Works for: E-commerce, SaaS with clear pricing
+- Example: "Earn 25% of every sale you refer"
+
+**Flat fee per action:**
+- Standard: $5-500 depending on value
+- Works for: Lead gen, trials, freemium
+- Example: "$50 for every qualified demo"
+
+**Recurring commission:**
+- Standard: 10-25% of recurring revenue
+- Works for: Subscription products
+- Example: "20% of subscription for 12 months"
+
+**Tiered commission:**
+- Works for: Motivating high performers
+- Example: "20% for 1-10 sales, 25% for 11-25, 30% for 26+"
+
+---
+
+## Cookie Duration
+
+How long after click does affiliate get credit?
+
+| Duration | Use Case |
+|----------|----------|
+| 24 hours | High-volume, low-consideration purchases |
+| 7-14 days | Standard e-commerce |
+| 30 days | Standard SaaS/B2B |
+| 60-90 days | Long sales cycles, enterprise |
+| Lifetime | Premium affiliate relationships |
+
+---
+
+## Affiliate Recruitment
+
+### Where to find affiliates:
+- Existing customers who create content
+- Industry bloggers and reviewers
+- YouTubers in your niche
+- Newsletter writers
+- Complementary tool companies
+- Consultants and agencies
+
+### Outreach template:
+```
+Subject: Partnership opportunity — [Your Product]
+
+Hi [Name],
+
+I've been following your content on [topic] — particularly [specific piece] — and think there could be a great fit for a partnership.
+
+[Your Product] helps [audience] [achieve outcome], and I think your audience would find it valuable.
+
+We offer [commission structure] for partners, plus [additional benefits: early access, co-marketing, etc.].
+
+Would you be open to learning more?
+
+[Your name]
+```
+
+---
+
+## Affiliate Enablement
+
+Provide affiliates with:
+- [ ] Unique tracking links/codes
+- [ ] Product overview and key benefits
+- [ ] Target audience description
+- [ ] Comparison to competitors
+- [ ] Creative assets (logos, banners, images)
+- [ ] Sample copy and talking points
+- [ ] Case studies and testimonials
+- [ ] Demo access or free account
+- [ ] FAQ and objection handling
+- [ ] Payment terms and schedule
+
+---
+
+## Tools & Platforms
+
+### Referral Program Tools
+
+**Full-featured platforms:**
+- ReferralCandy — E-commerce focused
+- Ambassador — Enterprise referral programs
+- Friendbuy — E-commerce and subscription
+- GrowSurf — SaaS and tech companies
+- Mention Me — AI-powered referral marketing
+- Viral Loops — Template-based campaigns
+
+**Built-in options:**
+- Stripe (basic referral tracking)
+- HubSpot (CRM-integrated)
+- Segment (tracking and analytics)
+
+### Affiliate Program Tools
+
+**Affiliate networks:**
+- ShareASale — Large merchant network
+- Impact — Enterprise partnerships
+- PartnerStack — SaaS focused
+- Tapfiliate — Simple SaaS affiliate tracking
+- FirstPromoter — SaaS affiliate management
+
+**Self-hosted:**
+- Rewardful — Stripe-integrated affiliates
+- Refersion — E-commerce affiliates
+
+### Choosing a Tool
+
+Consider:
+- Integration with your payment system
+- Fraud detection capabilities
+- Payout management
+- Reporting and analytics
+- Customization options
+- Price vs. program scale
+
+---
+
+## Fraud Prevention
+
+### Common Referral Fraud
+- Self-referrals (creating fake accounts)
+- Referral rings (groups referring each other)
+- Coupon sites posting referral codes
+- Fake email addresses
+- VPN/device spoofing
+
+### Prevention Measures
+
+**Technical:**
+- Email verification required
+- Device fingerprinting
+- IP address monitoring
+- Delayed reward payout (after activation)
+- Minimum activity threshold
+
+**Policy:**
+- Clear terms of service
+- Maximum referrals per period
+- Reward clawback for refunds/chargebacks
+- Manual review for suspicious patterns
+
+**Structural:**
+- Require referred user to take meaningful action
+- Cap lifetime rewards
+- Pay rewards in product credit (less attractive to fraudsters)

package/modules/referral-program/references/program-examples.md

@@ -0,0 +1,143 @@
+# Referral Program Examples
+
+Real-world examples of successful referral programs.
+
+## Contents
+- Dropbox (Classic)
+- Uber/Lyft
+- Morning Brew
+- Notion
+- Incentive Types Comparison
+- Incentive Sizing Framework
+- Viral Coefficient & Metrics (Key Metrics, Calculating Referral Program ROI)
+
+## Dropbox (Classic)
+
+**Program:** Give 500MB storage, get 500MB storage
+
+**Why it worked:**
+- Reward directly tied to product value
+- Low friction (just an email)
+- Both parties benefit equally
+- Gamified with progress tracking
+
+---
+
+## Uber/Lyft
+
+**Program:** Give $10 ride credit, get $10 when they ride
+
+**Why it worked:**
+- Immediate, clear value
+- Double-sided incentive
+- Easy to share (code/link)
+- Triggered at natural moments
+
+---
+
+## Morning Brew
+
+**Program:** Tiered rewards for subscriber referrals
+- 3 referrals: Newsletter stickers
+- 5 referrals: T-shirt
+- 10 referrals: Mug
+- 25 referrals: Hoodie
+
+**Why it worked:**
+- Gamification drives ongoing engagement
+- Physical rewards are shareable (more referrals)
+- Low cost relative to subscriber value
+- Built status/identity
+
+---
+
+## Notion
+
+**Program:** $10 credit per referral (education)
+
+**Why it worked:**
+- Targeted high-sharing audience (students)
+- Product naturally spreads in teams
+- Credit keeps users engaged
+
+---
+
+## Incentive Types Comparison
+
+| Type | Pros | Cons | Best For |
+|------|------|------|----------|
+| Cash/credit | Universally valued | Feels transactional | Marketplaces, fintech |
+| Product credit | Drives usage | Only valuable if they'll use it | SaaS, subscriptions |
+| Free months | Clear value | May attract freebie-seekers | Subscription products |
+| Feature unlock | Low cost to you | Only works for gated features | Freemium products |
+| Swag/gifts | Memorable, shareable | Logistics complexity | Brand-focused companies |
+| Charity donation | Feel-good | Lower personal motivation | Mission-driven brands |
+
+---
+
+## Incentive Sizing Framework
+
+**Calculate your maximum incentive:**
+```
+Max Referral Reward = (Customer LTV × Gross Margin) - Target CAC
+```
+
+**Example:**
+- LTV: $1,200
+- Gross margin: 70%
+- Target CAC: $200
+- Max reward: ($1,200 × 0.70) - $200 = $640
+
+**Typical referral rewards:**
+- B2C: $10-50 or 10-25% of first purchase
+- B2B SaaS: $50-500 or 1-3 months free
+- Enterprise: Higher, often custom
+
+---
+
+## Viral Coefficient & Metrics
+
+### Key Metrics
+
+**Viral coefficient (K-factor):**
+```
+K = Invitations × Conversion Rate
+
+K > 1 = Viral growth (each user brings more than 1 new user)
+K < 1 = Amplified growth (referrals supplement other acquisition)
+```
+
+**Example:**
+- Average customer sends 3 invitations
+- 15% of invitations convert
+- K = 3 × 0.15 = 0.45
+
+**Referral rate:**
+```
+Referral Rate = (Customers who refer) / (Total customers)
+```
+
+Benchmarks:
+- Good: 10-25% of customers refer
+- Great: 25-50%
+- Exceptional: 50%+
+
+**Referrals per referrer:**
+
+Benchmarks:
+- Average: 1-2 referrals per referrer
+- Good: 2-5
+- Exceptional: 5+
+
+### Calculating Referral Program ROI
+
+```
+Referral Program ROI = (Revenue from referred customers - Program costs) / Program costs
+
+Program costs = Rewards paid + Tool costs + Management time
+```
+
+**Track separately:**
+- Cost per referred customer (CAC via referral)
+- LTV of referred customers (often higher than average)
+- Payback period for referral rewards

package/modules/release/SKILL.md

@@ -0,0 +1,293 @@
+---
+name: release
+description: You are a release engineer. Execute each phase in order. Each must fully complete before advancing. Do NOT ask for permission. Do NOT skip phases.
+category: lifecycle
+tier: core
+slash_command: /release
+---
+
+# Release — Local Gate → Install Test → Version Bump → Tag → Publish → Verify
+
+You are a release engineer. Execute each phase in order. Each must fully complete before advancing. Do NOT ask for permission. Do NOT skip phases.
+
+## Usage
+
+```
+/release patch    # 1.2.3 → 1.2.4
+/release minor    # 1.2.3 → 1.3.0
+/release major    # 1.2.3 → 2.0.0
+/release 1.4.0    # explicit version
+```
+
+If no argument is given, ask: `patch, minor, or major?`
+
+---
+
+## Phase 0 — Detect registries
+
+```bash
+PROJECT_ROOT=$(git rev-parse --show-toplevel)
+cd "$PROJECT_ROOT"
+
+{ [ -f pyproject.toml ] || [ -f setup.py ]; } && PYPI=true || PYPI=false
+[ -f package.json ] && node -e "const d=require('./package.json'); process.exit(d.private ? 1 : 0)" 2>/dev/null && NPM=true || NPM=false
+[ -f Dockerfile ] && DOCKER=true || DOCKER=false
+```
+
+Print detected registries before continuing:
+
+```
+Detected registries:
+  PyPI:       true | false
+  npm:        true | false
+  Docker:     true | false
+```
+
+---
+
+## Phase 1 — Quality Gate (MANDATORY)
+
+Run the **gate** workflow. Do NOT continue until it reports `✅ ALL GATES PASSED`.
+
+---
+
+## Phase 2 — Confirm current version
+
+Print current → new version before proceeding. Do not proceed without confirming the version transition is correct.
+
+```bash
+python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])" 2>/dev/null || true
+node -e "console.log(require('./package.json').version)" 2>/dev/null || true
+```
+
+Print:
+```
+Current version: X.Y.Z
+New version:     A.B.C
+```
+
+---
+
+## Phase 3 — Build packages locally
+
+### PyPI (if PYPI=true)
+
+```bash
+pip install build twine --quiet
+python -m build
+twine check dist/*
+```
+
+GATE: `twine check` must report PASSED for all distributions. If it fails → STOP.
+
+### npm (if NPM=true)
+
+```bash
+npm pack --dry-run
+```
+
+GATE: must complete with no errors. If it fails → STOP.
+
+### Docker (if DOCKER=true)
+
+```bash
+docker build -t "$(basename "$PROJECT_ROOT"):release-candidate" .
+```
+
+GATE: build must succeed. If it fails → STOP.
+
+---
+
+## Phase 4 — Local install smoke test (BEFORE tagging)
+
+This is the most important phase. It catches broken imports, missing files, and broken CLI entrypoints BEFORE anything is published.
+
+### PyPI smoke test (if PYPI=true)
+
+```bash
+python3 -m venv /tmp/release-test-venv
+/tmp/release-test-venv/bin/pip install dist/*.whl --quiet
+PACKAGE_NAME=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['name'].replace('-','_'))")
+/tmp/release-test-venv/bin/python -c "import $PACKAGE_NAME; print('Import OK')"
+CLI_CMD=$(python3 -c "import tomllib; scripts=tomllib.load(open('pyproject.toml','rb')).get('project',{}).get('scripts',{}); print(list(scripts.keys())[0] if scripts else '')" 2>/dev/null)
+[ -n "$CLI_CMD" ] && /tmp/release-test-venv/bin/$CLI_CMD --version || echo "No CLI entrypoint"
+rm -rf /tmp/release-test-venv
+```
+
+### Docker smoke test (if DOCKER=true)
+
+```bash
+IMAGE="$(basename "$PROJECT_ROOT"):release-candidate"
+docker run --rm "$IMAGE" --version 2>/dev/null || \
+docker run --rm "$IMAGE" --help 2>/dev/null || \
+docker run --rm "$IMAGE" echo "container starts OK"
+```
+
+**GATE: All smoke tests must pass. If any fail → STOP. Fix the package, re-run from Phase 3.**
+
+Print summary:
+
+```
+Phase 4 Smoke Tests:
+  PyPI install:   ✅ PASSED | ❌ FAILED
+  Docker run:     ✅ PASSED | ❌ FAILED | ⬜ skipped
+```
+
+---
+
+## Phase 5 — Bump version
+
+### pyproject.toml (if PYPI=true)
+
+```bash
+OLD_VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+sed -i.bak "s/^version = \"$OLD_VERSION\"/version = \"$NEW_VERSION\"/" pyproject.toml && rm pyproject.toml.bak
+```
+
+### package.json (if NPM=true)
+
+```bash
+npm version $NEW_VERSION --no-git-tag-version
+```
+
+Verify the bump applied by printing the new version from each file.
+
+---
+
+## Phase 6 — Update CHANGELOG
+
+```bash
+if [ -f CHANGELOG.md ]; then
+  TODAY=$(date +%Y-%m-%d)
+  sed -i.bak "s/^## \[Unreleased\]/## [$NEW_VERSION] - $TODAY/" CHANGELOG.md && rm -f CHANGELOG.md.bak
+  python3 -c "
+content = open('CHANGELOG.md').read()
+content = content.replace('## [$NEW_VERSION]', '## [Unreleased]\n\n## [$NEW_VERSION]', 1)
+open('CHANGELOG.md', 'w').write(content)
+"
+  echo "CHANGELOG.md updated for v$NEW_VERSION"
+else
+  echo "No CHANGELOG.md — skipping"
+fi
+```
+
+---
+
+## Phase 7 — Commit version bump + tag
+
+```bash
+git add pyproject.toml package.json CHANGELOG.md 2>/dev/null || true
+git add -u
+git commit -m "$(cat <<EOF
+chore(release): bump version to $NEW_VERSION
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+EOF
+)"
+git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
+git log --oneline -2
+```
+
+---
+
+## Phase 8 — Push tag
+
+```bash
+DEFAULT_BRANCH=$(git symbolic-ref --short HEAD)
+git push origin "$DEFAULT_BRANCH"
+git push origin "v$NEW_VERSION"
+```
+
+Print: `Tag v$NEW_VERSION pushed → CI release pipeline triggered`
+
+---
+
+## Phase 9 — Watch CI release run
+
+```bash
+sleep 10
+RUN_ID=$(gh run list --workflow=release.yml --limit 1 --json databaseId -q '.[0].databaseId' 2>/dev/null)
+[ -n "$RUN_ID" ] && gh run watch "$RUN_ID" || echo "No release.yml found — check manually: gh run list --limit 5"
+```
+
+If CI fails: read logs with `gh run view "$RUN_ID" --log | tail -100`, fix locally, push fix to main (do NOT re-tag). Max 3 attempts, then escalate with full diagnosis.
+
+```
+CI FAILED — Attempt N/3
+Failure:  [error summary]
+Fix:      [what was done]
+Action:   Committing fix, pushing to main...
+```
+
+After 3 failed attempts → STOP and escalate:
+
+```
+╔══════════════════════════════════════════════════════╗
+║         CI RELEASE FAILED — ESCALATING TO HUMAN     ║
+╠══════════════════════════════════════════════════════╣
+║ Attempts:   N/3 exhausted                            ║
+║ Last error: [error summary]                          ║
+║ Diagnosis:  [root cause analysis]                    ║
+║ Suggestion: [recommended fix]                        ║
+╠══════════════════════════════════════════════════════╣
+║ This requires human judgment. Auto-fix not possible. ║
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## Phase 10 — Post-release verification (from live registry)
+
+After CI passes, verify packages are installable from the live registry.
+
+### PyPI (if PYPI=true)
+
+```bash
+python3 -m venv /tmp/pypi-verify-venv
+echo "Waiting for PyPI propagation..."
+for i in 1 2 3 4 5; do
+  sleep 20
+  /tmp/pypi-verify-venv/bin/pip install "$PACKAGE_NAME==$NEW_VERSION" --quiet 2>/dev/null && break
+  echo "Attempt $i/5 — not yet available, retrying..."
+done
+/tmp/pypi-verify-venv/bin/python -c "import $PACKAGE_NAME; print('PyPI install verified OK')"
+rm -rf /tmp/pypi-verify-venv
+```
+
+### Docker Hub (if DOCKER=true)
+
+```bash
+DOCKER_REPO=$(grep -m1 'DOCKERHUB_REPO' .env.release 2>/dev/null | cut -d= -f2 || echo "")
+[ -n "$DOCKER_REPO" ] && docker pull "$DOCKER_REPO:$NEW_VERSION" && docker run --rm "$DOCKER_REPO:$NEW_VERSION" --version || echo "Docker Hub verify skipped — set DOCKERHUB_REPO in .env.release"
+```
+
+---
+
+## Output
+
+```
+=== Release Complete ===
+Version:    v$NEW_VERSION
+Tag:        ✅ pushed
+CI:         ✅ release.yml passed
+
+Registries:
+  PyPI:       ✅ verified installable | ⬜ skipped
+  npm:        ✅ verified | ⬜ skipped
+  Docker Hub: ✅ verified | ⬜ skipped
+
+Status:     RELEASED ✅
+```
+
+---
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `twine check` fails | Fix metadata in `pyproject.toml` |
+| PyPI smoke test fails (ImportError) | Missing file in `[tool.setuptools] packages` |
+| Docker smoke test fails | Add `CMD ["--version"]` to Dockerfile |
+| Version already exists on PyPI | PyPI versions are immutable — bump again, create new tag |
+| CI release run not found | Workflow must be named `release.yml` triggered on `push: tags: ["v*.*.*"]` |
+| Homebrew update fails | `HOMEBREW_TAP_TOKEN` secret not set |