feat: affiliate engine, paid spotlight tiers, modernized index & RitualDev Lab logo

data/affiliates.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "updatedAt": "2026-10-20T00:00:00.000Z",
+  "updatedAt": "2026-11-10T10:36:23.696Z",
   "description": "DevShelf Verified Developer Affiliate & Partner Perks Registry. Cleanly maps high-converting developer perks, free cloud credits, and verified partner links to directory dossiers without tracking param pollution.",
   "partners": [
     {
@@ -74,6 +74,42 @@
       "ctaText": "Get Free Postgres →",
       "badge": "⚡ Free Serverless DB",
       "active": true
+    },
+    {
+      "slug": "railway",
+      "toolName": "Railway",
+      "url": "https://railway.com/?ref=devshelf",
+      "vanityPath": "/go/railway.html",
+      "category": "cloud",
+      "perkTitle": "$5 Monthly Free Cloud & API Hosting",
+      "perkDescription": "Instant git-push deployments for Node.js, Python, Docker, MCP servers, and Postgres.",
+      "ctaText": "Deploy on Railway ->",
+      "badge": "⚡ Cloud Free Tier",
+      "active": true
+    },
+    {
+      "slug": "posthog",
+      "toolName": "PostHog",
+      "url": "https://posthog.com/?ref=devshelf",
+      "vanityPath": "/go/posthog.html",
+      "category": "testing",
+      "perkTitle": "1M Free Events + 5,000 Session Replays/mo",
+      "perkDescription": "Open-source product analytics, feature flags, session replay, and LLM observability.",
+      "ctaText": "Start Free on PostHog ->",
+      "badge": "⚡ 1M Free Events",
+      "active": true
+    },
+    {
+      "slug": "cloudflare",
+      "toolName": "Cloudflare",
+      "url": "https://www.cloudflare.com/?ref=devshelf",
+      "vanityPath": "/go/cloudflare.html",
+      "category": "cloud",
+      "perkTitle": "100,000 Free Daily Worker Invocations + Pages",
+      "perkDescription": "Global edge workers, zero-egress R2 storage, D1 SQLite, and unlimited static sites.",
+      "ctaText": "Launch on Cloudflare ->",
+      "badge": "⚡ Free Edge Workers",
+      "active": true
     }
   ]
 }

data/counts.json

@@ -13,5 +13,5 @@
     "testing-qa.json": 68
   },
   "reposCount": 363,
-  "updatedAt": "2026-11-08T15:03:56.508Z"
+  "updatedAt": "2026-11-10T11:55:55.479Z"
 }

schemas/tool.schema.json

@@ -84,6 +84,54 @@
         "format": "uri",
         "pattern": "^https?://",
         "description": "Tracked redirect target URL if destination moved"
+      },
+      "installCommand": {
+        "type": "string",
+        "description": "Explicit single install command overriding fallback git clone"
+      },
+      "installCommands": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Ordered multi-step install commands to run separately"
+      },
+      "installNote": {
+        "type": "string",
+        "description": "Short factual note accompanying explicit install commands"
+      },
+      "installDocsUrl": {
+        "type": "string",
+        "format": "uri",
+        "pattern": "^https?://",
+        "description": "Official installation documentation anchor URL"
+      },
+      "installDocsLabel": {
+        "type": "string",
+        "description": "Human-readable anchor label for official installation docs"
+      },
+      "customFaqs": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": ["question", "answer"],
+          "properties": {
+            "question": { "type": "string" },
+            "answer": { "type": "string" }
+          },
+          "additionalProperties": false
+        },
+        "description": "Custom promotional FAQs unlocked on Paid Spotlight and Category Leader tiers"
+      },
+      "spotlightPromo": {
+        "type": "object",
+        "properties": {
+          "badge": { "type": "string" },
+          "headline": { "type": "string" },
+          "summary": { "type": "string" },
+          "ctaLabel": { "type": "string" },
+          "ctaUrl": { "type": "string", "format": "uri", "pattern": "^https?://" }
+        },
+        "additionalProperties": false,
+        "description": "Promotional spotlight callout unlocked on Paid Spotlight and Category Leader tiers"
       }
     },
     "additionalProperties": false

scripts/activate-sponsor.ts

@@ -11,7 +11,16 @@ const DATA_DIR = path.join(ROOT_DIR, "data");
 
 export type ShelfCategory = "ai" | "cli" | "apis" | "cloud" | "testing" | "boilerplates" | "perks";
 
-export type SponsorTier = "starter" | "mcpPro" | "enterprise";
+export type SponsorTier =
+  | "starter"
+  | "mcpPro"
+  | "enterprise"
+  | "starter_9"
+  | "spotlight_19"
+  | "category_39"
+  | "leader_49"
+  | "combo_79"
+  | "custom";
 
 export interface ActivateSponsorOptions {
   name: string;
@@ -63,16 +72,46 @@ const TIER_MAP: Record<
     patronTier: "silver",
     sponsorTierLabel: "Verified Sponsor ★ (Starter)",
   },
+  starter_9: {
+    defaultUSD: 9,
+    patronTier: "silver",
+    sponsorTierLabel: "Verified Sponsor ★ (Starter)",
+  },
+  spotlight_19: {
+    defaultUSD: 19,
+    patronTier: "silver",
+    sponsorTierLabel: "Verified Sponsor ★ (Launch Spotlight)",
+  },
+  category_39: {
+    defaultUSD: 39,
+    patronTier: "gold",
+    sponsorTierLabel: "Verified Sponsor ★ (Category Exclusive)",
+  },
   mcpPro: {
     defaultUSD: 49,
     patronTier: "gold",
     sponsorTierLabel: "Verified Sponsor ★ (MCP Pro)",
   },
+  leader_49: {
+    defaultUSD: 49,
+    patronTier: "gold",
+    sponsorTierLabel: "Verified Sponsor ★ (Category Leader + MCP Pro)",
+  },
   enterprise: {
     defaultUSD: 79,
     patronTier: "enterprise",
     sponsorTierLabel: "Verified Sponsor ★ (Enterprise Partner)",
   },
+  combo_79: {
+    defaultUSD: 79,
+    patronTier: "enterprise",
+    sponsorTierLabel: "Verified Sponsor ★ (Category Combo Pack)",
+  },
+  custom: {
+    defaultUSD: 25,
+    patronTier: "gold",
+    sponsorTierLabel: "Verified Sponsor ★ (Custom Sponsor)",
+  },
 };
 
 const ALL_SHELF_FILES = [

scripts/build-site.ts

@@ -71,12 +71,20 @@ async function buildSiteData() {
     const digestSource = `${slug}:${tool.url || ""}:${tool.license || ""}:${tool.type || ""}`;
     const verificationDigest = crypto.createHash("sha256").update(digestSource).digest("hex");
 
-    let installCommand = tool.installCommand;
-    if (!installCommand && tool.url) {
+    const installCommands = Array.isArray(tool.installCommands)
+      ? tool.installCommands.filter(
+          (cmd: unknown) => typeof cmd === "string" && cmd.trim().length > 0,
+        )
+      : undefined;
+    let installCommand =
+      tool.installCommand ||
+      (installCommands && installCommands.length > 0 ? installCommands.join("\n") : undefined);
+    const repoOrUrl = tool.url || tool.repo;
+    if (!installCommand && repoOrUrl) {
       try {
-        const parsedUrl = new URL(tool.url);
+        const parsedUrl = new URL(repoOrUrl);
         if (parsedUrl.hostname === "github.com" || parsedUrl.hostname.endsWith(".github.com")) {
-          installCommand = `git clone ${tool.url}`;
+          installCommand = `git clone ${repoOrUrl}`;
         }
       } catch {
         // invalid URL string, skip default git clone command
@@ -104,6 +112,9 @@ async function buildSiteData() {
         verificationDigest,
       },
       installCommand,
+      ...(installCommands && installCommands.length > 0 ? { installCommands } : {}),
+      ...(tool.installNote ? { installNote: tool.installNote } : {}),
+      ...(tool.installDocsUrl ? { installDocsUrl: tool.installDocsUrl } : {}),
     };
   });
 

scripts/generate-seo.ts

@@ -19,6 +19,28 @@ function escapeHtml(str: string | undefined): string {
     .replace(/'/g, "'");
 }
 
+function safeHttpUrl(url: unknown): string {
+  if (typeof url !== "string" || !url.trim()) return "";
+  try {
+    const parsed = new URL(url.trim());
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.toString() : "";
+  } catch {
+    return "";
+  }
+}
+
+function resolveInstallSteps(item: any): string[] {
+  if (Array.isArray(item.installCommands) && item.installCommands.length > 0) {
+    return item.installCommands.filter(
+      (cmd: unknown): cmd is string => typeof cmd === "string" && cmd.trim().length > 0,
+    );
+  }
+  if (typeof item.installCommand === "string" && item.installCommand.trim().length > 0) {
+    return [item.installCommand.trim()];
+  }
+  return [];
+}
+
 async function generateSeo() {
   const root = process.cwd();
   const siteDir = path.join(root, "site");
@@ -207,11 +229,41 @@ async function generateSeo() {
       `  <url>\n    <loc>${pageUrl}</loc>\n    <lastmod>${today}</lastmod>\n    <changefreq>weekly</changefreq>\n    <priority>0.8</priority>\n  </url>`,
     );
 
+    const installSteps = resolveInstallSteps(item);
+    const installNote = typeof item.installNote === "string" ? item.installNote.trim() : "";
+    const installDocsUrl = safeHttpUrl(item.installDocsUrl);
+    const installDocsLabel =
+      typeof item.installDocsLabel === "string" && item.installDocsLabel.trim()
+        ? item.installDocsLabel.trim()
+        : "Official installation instructions";
+    const isPaidSpotlight = Boolean(item.featured || item.sponsorTier);
+    const customFaqs: { question: string; answer: string }[] =
+      isPaidSpotlight && Array.isArray(item.customFaqs)
+        ? item.customFaqs.filter(
+            (f: any) =>
+              f &&
+              typeof f.question === "string" &&
+              f.question.trim().length > 0 &&
+              typeof f.answer === "string" &&
+              f.answer.trim().length > 0,
+          )
+        : [];
+    const setupFaqAnswer =
+      installSteps.length > 0
+        ? `${installNote ? `${installNote} ` : ""}${installSteps.join(" | ")}${installDocsUrl ? ` — ${installDocsLabel}: ${installDocsUrl}` : ""}`
+        : item.repo
+          ? `See the official repository (${item.repo}) for installation and usage instructions.`
+          : `Visit the official site (${targetUrl}) for setup details.`;
+
     const faqs = [
       {
         question: `What free access does ${item.name} offer in ${currentYear}?`,
         answer: `As verified in ${currentYear}, ${pricing}${item.license ? ` License: ${item.license}.` : ""}`,
       },
+      {
+        question: `How do I install or run ${item.name}?`,
+        answer: setupFaqAnswer,
+      },
       ...(alternativeTo
         ? [
             {
@@ -226,6 +278,7 @@ async function generateSeo() {
           ? `Authentication requirement: ${item.auth}.`
           : "See the official site for authentication and access requirements.",
       },
+      ...customFaqs,
     ];
 
     const jsonLd = {
@@ -365,14 +418,63 @@ async function generateSeo() {
         </div>
       </div>`;
 
+    const quickInstallHtml =
+      installSteps.length > 0
+        ? `
+      <div class="mt-8 p-6 rounded-2xl bg-slate-950/90 border border-slate-800 space-y-3">
+        <div class="flex items-center justify-between flex-wrap gap-2">
+          <h3 class="text-xs font-mono font-bold text-emerald-400 uppercase tracking-wider">⚡ Quick Install &amp; Execution</h3>
+          ${
+            installDocsUrl
+              ? `<a href="${escapeHtml(installDocsUrl)}" target="_blank" rel="noopener noreferrer" class="text-xs font-mono text-purple-300 hover:text-purple-200 underline">${escapeHtml(installDocsLabel)} →</a>`
+              : ""
+          }
+        </div>
+        ${installNote ? `<p class="text-xs text-slate-300 leading-relaxed">${escapeHtml(installNote)}</p>` : ""}
+        <div class="space-y-2">
+          ${installSteps
+            .map(
+              (step) => `
+          <div class="p-3 rounded-xl bg-black/80 border border-slate-800 font-mono text-xs text-emerald-300 overflow-x-auto select-all">
+            ${escapeHtml(step)}
+          </div>`,
+            )
+            .join("")}
+        </div>
+      </div>`
+        : "";
+
+    const promoCtaUrl =
+      isPaidSpotlight && item.spotlightPromo ? safeHttpUrl(item.spotlightPromo.ctaUrl) : "";
+    const spotlightPromoHtml =
+      isPaidSpotlight && item.spotlightPromo
+        ? `
+      <div class="mt-8 p-5 rounded-2xl bg-gradient-to-r from-purple-950/60 via-slate-900 to-amber-950/40 border border-amber-500/40 flex flex-col sm:flex-row sm:items-center justify-between gap-4">
+        <div class="space-y-1">
+          <span class="text-[11px] font-mono font-bold uppercase tracking-wider text-amber-300">${escapeHtml(item.spotlightPromo.badge || "★ Paid Spotlight")}</span>
+          ${item.spotlightPromo.headline ? `<h3 class="text-sm font-bold text-white">${escapeHtml(item.spotlightPromo.headline)}</h3>` : ""}
+          ${item.spotlightPromo.summary ? `<p class="text-xs text-slate-300 leading-relaxed">${escapeHtml(item.spotlightPromo.summary)}</p>` : ""}
+        </div>
+        ${
+          promoCtaUrl
+            ? `<a href="${escapeHtml(promoCtaUrl)}" target="_blank" rel="noopener noreferrer sponsored" class="shrink-0 px-4 py-2 rounded-xl bg-amber-500 hover:bg-amber-400 text-slate-950 font-bold text-xs font-mono transition">${escapeHtml(item.spotlightPromo.ctaLabel || "Explore Tool →")}</a>`
+            : ""
+        }
+      </div>`
+        : "";
+
     const creatorPromoHtml = `
       <div class="mt-8 p-4 rounded-xl bg-slate-950/80 border border-slate-800 flex flex-col sm:flex-row items-center justify-between gap-3 text-xs">
         <div class="flex items-center space-x-2.5">
           <span class="text-base">🚀</span>
-          <span class="text-slate-300">Are you the creator of <strong>${escapeHtml(item.name)}</strong> or building a devtool in this category?</span>
+          <span class="text-slate-300">Maintainer of <strong>${escapeHtml(item.name)}</strong>? ${
+            isPaidSpotlight
+              ? "Active Featured / Paid Spotlight status unlocked."
+              : "Unlock custom promotional FAQs, highlighted install CTAs, and #1 category pinning."
+          }</span>
         </div>
-        <a href="../sponsors.html#mcp-sponsors" class="shrink-0 px-3 py-1.5 rounded-lg font-bold font-mono text-xs bg-purple-600/30 hover:bg-purple-600 border border-purple-500/50 text-purple-200 hover:text-white transition">
-          Feature in AI Chats ($49) →
+        <a href="https://ritualdev.in/partners" target="_blank" rel="noopener noreferrer" class="shrink-0 px-3 py-1.5 rounded-lg font-bold font-mono text-xs bg-purple-600/30 hover:bg-purple-600 border border-purple-500/50 text-purple-200 hover:text-white transition">
+          Launch Spotlight ($19–$49) →
         </a>
       </div>`;
 
@@ -635,6 +737,8 @@ async function generateSeo() {
 
       ${categorySponsorHtml}
       ${partnerPerkHtml}
+      ${spotlightPromoHtml}
+      ${quickInstallHtml}
       ${dockerSectionHtml}
       ${badgeSectionHtml}
       ${creatorPromoHtml}

shelf/cli-tools.json

@@ -1384,6 +1384,13 @@
     "repo": "https://github.com/akii-technologies-ltd/akii-seo-ai-search-optimizer",
     "language": "Claude Code plugin, Markdown skills and agents, Bash hooks, JSON manifests",
     "license": "MIT",
-    "featured": false
+    "featured": false,
+    "installNote": "To install the plugin, open Claude Code and run these as two separate commands:",
+    "installCommands": [
+      "/plugin marketplace add https://github.com/akii-technologies-ltd/akii-seo-ai-search-optimizer",
+      "/plugin install akii-seo-ai-search-optimizer@akii"
+    ],
+    "installDocsUrl": "https://github.com/akii-technologies-ltd/akii-seo-ai-search-optimizer#installation",
+    "installDocsLabel": "Official installation instructions"
   }
 ]