claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/skills/redis-patterns/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: redis-patterns
+description: Redis patterns — caching (cache-aside, write-through), sessions, pub/sub, work queues, distributed locks, data structures (sorted sets, streams, hashes). Covers ioredis, node-redis, Redis 7+. Use when designing Redis usage in Node.js/TypeScript apps
+tokens: 2081
+user-invocable: false
+---
+
+# Redis Patterns
+
+Production patterns for Redis as a cache, session store, pub/sub bus, work-queue backbone, and distributed-coordination primitive in Node.js/TypeScript (ioredis, node-redis, Redis 7+).
+
+## Use this skill when
+
+- Implementing caching (cache-aside, write-through, write-back)
+- Setting up pub/sub or BLPOP-based work queues
+- Using Redis data structures (Sorted Sets, Streams, Hash, Sets, Lists)
+- Configuring ioredis for Node.js production
+- Designing key naming and TTL strategies
+- Implementing distributed locks with atomic `SET NX PX`
+
+## Do not use this skill when
+
+- You need a message broker with guaranteed delivery — use BullMQ, RabbitMQ, or Kafka
+- The task is Redis server-level configuration / cluster setup
+
+## Hard Rules
+
+1. **TTL on every SET** — the only no-TTL exception is queue keys (persistent until consumed). Locks always carry an expiry.
+2. **SCAN, never `KEYS *`** in production — `KEYS *` blocks the server on large keyspaces.
+3. **Dedicated subscriber connection** — a connection in subscribe mode cannot issue other commands.
+4. **Error handler on every client** — an unhandled `error` event crashes the Node.js process.
+5. **BullMQ clients set `maxRetriesPerRequest: null`** — otherwise connections fail under load.
+6. **Shut down with `quit()`, not `disconnect()`** — `quit()` drains in-flight commands; `disconnect()` drops them.
+
+## Workflow
+
+1. Identify the use case: caching, pub/sub, queue, session, or rate limiting.
+2. Choose the data structure that fits the access pattern (see Data Structures table).
+3. Design keys with the `scope:entity:id` convention.
+4. Set TTL on every key; the only no-TTL exception is queue keys (Hard Rule 1) — locks always carry an expiry.
+5. Validate error handling (Hard Rule 4) and graceful shutdown (Hard Rule 6).
+
+Done when: every key has a deliberate TTL or is a documented queue key, the client has an error handler attached before connecting, and shutdown calls `quit()`.
+
+## Connection (ioredis — recommended for Node.js)
+
+```typescript
+import Redis from 'ioredis';
+
+export const redis = new Redis({
+  host: process.env.REDIS_HOST,
+  port: 6379,
+  lazyConnect: true,
+  connectionName: 'api-server',
+  retryStrategy(times) {
+    return Math.min(times * 200, 2000);
+  },
+});
+
+redis.on('error', (err) => logger.error({ err }, 'redis'));
+redis.on('ready', () => logger.info('redis ready'));
+```
+
+- Singleton client; `lazyConnect` defers connection until first command
+- `retryStrategy` for exponential backoff
+- Separate dedicated **subscriber** connection for pub/sub (Hard Rule 3)
+- **BullMQ**: set `maxRetriesPerRequest: null` (Hard Rule 5)
+
+## Cache-Aside Pattern
+
+```typescript
+async function getUser(id: string): Promise<User | null> {
+  const key = `cache:user:${id}`;
+  const cached = await redis.get(key);
+  if (cached) return JSON.parse(cached);
+
+  const user = await db.users.findUnique({ where: { id } });
+  if (user) await redis.set(key, JSON.stringify(user), 'EX', 300);
+  return user;
+}
+
+async function invalidateUser(id: string) {
+  await redis.del(`cache:user:${id}`);
+}
+```
+
+TTL strategy:
+- Volatile data (counters, hot lists): seconds
+- Stable data (config, user profiles): minutes to hours
+- Rarely-changing reference data: hours to days
+
+Bulk invalidation: `SCAN` + `DEL` (Hard Rule 2).
+
+## Pub/Sub
+
+```typescript
+// Publisher (regular connection)
+await redis.publish('orders:new', JSON.stringify({ orderId: 123 }));
+
+// Subscriber (DEDICATED connection — can't issue other commands)
+const sub = new Redis({ ...config });
+await sub.subscribe('orders:new');
+sub.on('message', (channel, message) => {
+  const data = JSON.parse(message);
+  handleOrder(data);
+});
+```
+
+Pub/sub is fire-and-forget — messages dropped if no subscriber. For durable messaging use **Streams**.
+
+## BLPOP Wake Queue
+
+```typescript
+// Producer
+await redis.lpush('queue:emails', JSON.stringify(payload));
+
+// Consumer (blocks until item arrives)
+while (true) {
+  const [, raw] = await redis.brpop('queue:emails', 0);
+  await processEmail(JSON.parse(raw));
+}
+```
+
+Instant wake-up without polling. For complex queue needs use **BullMQ**, built on this primitive.
+
+## Data Structures
+
+| Structure | Use case |
+|-----------|----------|
+| **Sorted Set** | Leaderboards, sliding-window rate limit, scheduled jobs by score |
+| **Stream** (`XADD`/`XREAD`) | Event sourcing, consumer groups, persistent log |
+| **Hash** (`HSET`/`HGETALL`) | Object storage with partial updates (user sessions) |
+| **Set** | Unique tag membership, set operations (union, intersect, diff) |
+| **List** | FIFO/LIFO queues; recent activity via `LPUSH` + `LTRIM` |
+
+## Batch Operations
+
+```typescript
+// Pipeline — multiple commands, one round-trip (no atomicity)
+const results = await redis
+  .pipeline()
+  .get('a')
+  .get('b')
+  .incr('counter')
+  .exec();
+
+// Multi/Exec — atomic transaction (all-or-nothing)
+const txResults = await redis
+  .multi()
+  .decrby('inventory:x', 1)
+  .lpush('orders', orderId)
+  .exec();
+```
+
+Pipeline for **performance**, multi/exec for **atomicity**.
+
+## Distributed Locks
+
+```typescript
+async function acquireLock(key: string, ttlMs: number, token: string): Promise<boolean> {
+  const r = await redis.set(key, token, 'PX', ttlMs, 'NX');
+  return r === 'OK';
+}
+
+const releaseScript = `
+  if redis.call('get', KEYS[1]) == ARGV[1] then
+    return redis.call('del', KEYS[1])
+  else
+    return 0
+  end
+`;
+
+async function releaseLock(key: string, token: string) {
+  await redis.eval(releaseScript, 1, key, token);
+}
+```
+
+The Lua release script prevents one process releasing another's lock. Always set expiry (the `PX` above) to prevent deadlock on crash — locks are never a no-TTL key (Hard Rule 1).
+
+For production-grade locking with renewal use the **Redlock** algorithm or a hosted lock service.
+
+## Lua Scripts
+
+`redis.defineCommand()` caches EVALSHA automatically:
+
+```typescript
+redis.defineCommand('rateLimit', {
+  numberOfKeys: 1,
+  lua: `
+    local current = redis.call('incr', KEYS[1])
+    if current == 1 then redis.call('expire', KEYS[1], ARGV[1]) end
+    return current
+  `,
+});
+
+const count = await redis.rateLimit(`rate:${userId}`, 60);
+```
+
+Use for atomic read-modify-write that can't be expressed with `MULTI`/`EXEC`.
+
+## Key Naming Convention
+
+Pattern: `scope:entity:id`
+
+- `session:user:123`
+- `cache:products:featured`
+- `lock:payment:456`
+- `rate:api:user:789`
+- `queue:emails:high`
+- `stream:events:user-activity`
+
+Consistent colon separator enables prefix-based scanning and invalidation.
+
+## TTL Strategy Guide
+
+| Use case | Suggested TTL |
+|----------|---------------|
+| User session | 24h – 7 days |
+| API response cache | 1 min – 1 hour |
+| Rate limit window | = window size (60s for per-minute) |
+| Distributed lock | Slightly longer than expected op duration |
+| BLPOP queue keys | No TTL (persistent until consumed) |
+
+## Eviction Policies
+
+| Policy | Behavior | Use case |
+|--------|----------|----------|
+| `allkeys-lru` | Evict LRU from all keys | Pure caching |
+| `volatile-lru` | Evict LRU from keys with TTL | Protect persistent queues |
+| `allkeys-lfu` | Evict LFU | Repeated-access patterns |
+| `noeviction` | Error on write when full | Required for BullMQ |
+
+## Graceful Shutdown
+
+```typescript
+process.on('SIGTERM', async () => {
+  await redis.quit();  // waits for pending commands
+  process.exit(0);
+});
+```
+
+Use `quit()`, not `disconnect()` (Hard Rule 6).
+
+## Common Mistakes (symptom → cause)
+
+- Redis stalls on a large keyspace → `KEYS *` in a hot path (Hard Rule 2).
+- Node.js process crashes on a connection blip → no `error` handler attached before connect (Hard Rule 4).
+- "Connection in subscriber mode" errors → subscribe + commands mixed on one connection (Hard Rule 3).
+- Unbounded memory growth → cache keys written without TTL (Hard Rule 1).
+- Jobs lost / commands dropped on deploy → `disconnect()` in shutdown instead of `quit()` (Hard Rule 6).
+- BullMQ connection failures under load → missing `maxRetriesPerRequest: null` (Hard Rule 5).
+
+## Recap — non-negotiables
+
+- TTL on every SET except queue keys; locks always expire.
+- SCAN, never `KEYS *`, in production.
+- Dedicated subscriber connection; error handler on every client.
+- BullMQ clients set `maxRetriesPerRequest: null`.
+- Shutdown via `quit()`, not `disconnect()`.
+
+Adapted from VKirill/codex-starter-kit (community skill).

package/packages/core/skills/ru-text/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: ru-text
+description: Russian typography and editorial standards — quotes, dashes, NBSP, number formatting, info-style anti-patterns. Use when writing, editing, or reviewing Russian text (UI copy, articles, emails, marketing, microcopy)
+tokens: 1771
+user-invocable: false
+---
+
+# ru-text — Russian Text Quality
+
+Russian typography and editorial reference. Apply to ALL Russian-language output unless the user requests a different style.
+
+## Use when
+
+- UI copy: buttons, errors, hints, empty states, microcopy
+- Articles, blog posts, marketing content
+- Email, messenger, business correspondence
+- Reviewing existing Russian text for typography / style issues
+
+## Do not use when
+
+- The output is not in Russian.
+- Inside code, identifiers, URLs, file paths, or email addresses — leave machine punctuation untouched.
+- The user explicitly requests a conflicting style (casual, academic, SEO, literary). Their prompt overrides these defaults on conflict — this is the Style Priority escape hatch.
+
+## Hard Rules
+
+Apply to every Russian sentence you emit:
+
+1. Quotes: outer «ёлочки», nested „лапки“ — never ASCII straight quotes (U+0022) in the delivered text.
+2. Dashes: `—` (em) in running text, `–` (en) in ranges, `-` (hyphen) only inside words. Max 1–2 em dashes per paragraph.
+3. NBSP (U+00A0) after single-letter prepositions and between number+unit, so they never wrap alone.
+4. Numbers: decimal comma (`3,14`), thin-space digit groups (`1 000 000`).
+5. Write `ё` where it removes ambiguity (`все`/`всё`, `небо`/`нёбо`) and in proper names.
+6. Headings use sentence case, not Title Case.
+7. Cut office-speak (`являться`, `осуществлять`, `в целях`, `ввиду того что`).
+
+## Typography Rules Table
+
+In every example below, `␣` marks a non-breaking space (U+00A0) — otherwise invisible.
+
+| Rule | Wrong | Correct |
+|---|---|---|
+| Primary quotes: guillemets | "текст" | «текст» |
+| Nested quotes: lapki (U+201C closing) | «"вложенные"» | «„вложенные“» |
+| Em dash with spaces | слово - слово | слово — слово |
+| En dash for ranges, no spaces | 10-15 дней | 10–15 дней |
+| NBSP after single-letter prepositions | в начале (space wraps) | в␣начале |
+| Ellipsis: single character | ... | … |
+| Digit groups with thin spaces | 1000000 | 1 000 000 |
+| Decimal comma (not dot) | 3.14 | 3,14 |
+| Ordinal with hyphen | 1ый, 2ой | 1-й, 2-й |
+| Numero sign | No. 5, #5 | №␣5 |
+| Abbreviations with NBSP | т.д., т.е. | т.␣д., т.␣е. |
+| Ruble symbol after number with NBSP | 1500 руб | 1␣500␣₽ |
+
+## NBSP — Critical Cases
+
+`␣` = NBSP (U+00A0). Insert a real non-breaking space at each `␣` position; place it between:
+
+- Single-letter prepositions and the next word: `в␣начале`, `к␣концу`, `с␣пятого`, `о␣проекте`, `у␣меня`, `и␣тогда`, `а␣потом`
+- Number and unit: `5␣кг`, `1␣500␣₽`, `№␣5`
+- Abbreviation parts: `т.␣д.`, `т.␣е.`, `и.␣о.`
+- Initials and surname: `А.␣С.␣Пушкин`
+
+## Dashes — Three Different Marks
+
+- `—` (em dash, U+2014) — in running text, between subject and predicate, before direct speech
+- `–` (en dash, U+2013) — for numerical ranges: `10–15 дней`, `2024–2026`
+- `-` (hyphen) — only inside compound words: `кто-то`, `по-русски`, `1-й`
+
+**Limit:** max 1–2 em dashes per paragraph. Overuse signals weak writing.
+
+## Numbers and Money
+
+| Wrong | Correct |
+|---|---|
+| 1500руб | 1␣500␣₽ |
+| 3.14 | 3,14 |
+| 1000000 | 1 000 000 |
+| 50 % / 50% (context) | UI copy: `50%` · print: `50␣%` |
+| 25 С | 25 °C |
+
+**Percent:** in UI/web copy write `50%` with no space (dominant web practice). In print or formal typography use `50␣%` with NBSP (GOST / Milchin). Default to UI style for interface copy.
+
+## Capitalization (Russian-specific)
+
+- Sentence case for headings (NOT title case as in English): `Как настроить уведомления` (not `Как Настроить Уведомления`)
+- Days of week, months: lowercase (`понедельник`, `март`)
+- Nationalities, languages: lowercase (`русский`, `англичанин`)
+- Job titles: lowercase unless at start of sentence (`директор`, `менеджер`)
+- Brand names: keep original casing (`iPhone`, `GitHub`)
+
+## Top Stop-Words to Remove or Replace
+
+| Stop-word (Russian) | Replace with |
+|---|---|
+| является | — (em dash) or restructure |
+| осуществлять | делать, проводить |
+| в настоящее время | сейчас |
+| данный | этот |
+| определённый | (name the specific thing) |
+| произвести оплату | оплатить |
+| высококачественный | (name the specific quality) |
+| был осуществлён | (active voice + actor) |
+| на сегодняшний день | сегодня |
+| в целях | чтобы |
+| в случае если | если |
+| ввиду того что | потому что |
+| с целью | чтобы |
+| при условии что | если |
+
+## UX Writing — Microcopy Rules
+
+Example strings are shown in backticks (`` ` ``); the backticks are delimiters, not part of the copy.
+
+- **Buttons:** verb + object — `Сохранить изменения`, `Отправить заявку` (not `Сохранение`, `Отправка`)
+- **Errors:** state what went wrong + what to do — `Не удалось сохранить. Проверьте подключение и попробуйте ещё раз` (not `Ошибка сохранения`)
+- **Empty states:** explain why + suggest action — `Здесь пока пусто. Создайте первый заказ` (not `Нет данных`)
+- **Confirmations:** clear, no ambiguity — `Удалить заказ №␣123?` with explicit `Удалить` / `Отмена` buttons (not `OK` / `Cancel`)
+- **Hints:** answer «что это» or «что делать», short — `Например, ivan@example.com` (not `Введите email`)
+
+## Common Anti-Patterns
+
+1. **Russian text with English punctuation:** ASCII straight quotes (U+0022) and hyphens (`-`) where dashes belong, instead of «ёлочки» and `—`
+2. **Missed NBSP:** `в начале` (ordinary space, wraps to a new line) instead of `в␣начале` (`␣` = NBSP) — a lone `в` at a line end reads badly on narrow screens
+3. **Decimal point instead of comma:** Russian standard is `3,14`
+4. **Double spaces:** typewriter habit; modern typography uses a single space
+5. **Title Case as in English:** Russian uses sentence case
+6. **Overuse of `являться`:** removes life from sentences — use an em dash or active verb
+7. **Office-speak:** `осуществлять`, `проводить мероприятия`, `в целях оптимизации` → plain verbs
+8. **Foreign loanwords with Russian endings:** `юзать`, `контентмейкер`, `митап` — acceptable in casual context, jarring in formal
+
+## Quality Checklist
+
+Before delivering Russian text, confirm every box (`␣` = NBSP):
+
+- [ ] Quotes: «ёлочки» primary, „лапки“ nested (U+201C closing, never ASCII)
+- [ ] Dashes: — in text, – in ranges, - only in compounds; max 1–2 per paragraph
+- [ ] NBSP after single-letter prepositions (в, к, с, о, у, и, а)
+- [ ] Ellipsis: … (single char)
+- [ ] Abbreviations: т.␣д., т.␣п. (with NBSP)
+- [ ] No double spaces, no space before punctuation
+- [ ] Numbers: thin spaces for groups, comma for decimal
+- [ ] Currency: 1␣500␣₽ (NBSP both sides)
+- [ ] Heading case: sentence case, not Title Case
+- [ ] No office-speak: являться, осуществлять, в целях, ввиду
+
+## Recap — non-negotiables
+
+- Outer «ёлочки», nested „лапки“ (U+201C closing) — no ASCII straight quotes in delivered text.
+- Three dash marks kept distinct: — text, – ranges, - compounds; 1–2 em dashes per paragraph.
+- NBSP after single-letter prepositions and inside number+unit; decimal comma; thin-space digit groups.
+- Sentence-case headings; no office-speak.
+- Run the Quality Checklist before delivering.
+
+Credit: based on Arseniy Kamyshev's ru-text reference (via VKirill/codex-starter-kit). Full editorial reference at https://ru-text.org.

package/packages/core/skills/telegram-bot-builder/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: telegram-bot-builder
+description: Expert in building Telegram bots — bot architecture, the Telegram Bot API, inline keyboards, conversation flows, payments, scaling. Use when the task mentions Telegram bot, bot API, tg bot, Telegraf, grammY, aiogram, pyrogram, or telethon
+tokens: 1480
+user-invocable: false
+---
+
+# Telegram Bot Builder
+
+Design and build Telegram bots — architecture, the Bot API, inline keyboards, conversation flows, payments, and scaling — with conversations that feel natural and retain users.
+
+## Use this skill when
+
+- Building a new Telegram bot or extending an existing one
+- Designing inline keyboards, conversation flows, or command handlers
+- Planning monetization via Telegram Payments or freemium models
+- Setting up webhooks, graceful shutdown, or background processing
+
+## Do not use this skill when
+
+- The task is a Telegram Mini App UI — that is regular frontend web work (React/Vue running inside a WebApp), not covered by this kit's skills. This skill covers only the Bot API side.
+- You need general backend architecture unrelated to Telegram APIs.
+
+## Hard Rules
+
+1. NEVER run blocking or long I/O synchronously inside a handler — Telegram enforces tight timeouts. Acknowledge immediately (`ctx.sendChatAction('typing')` or a confirmation message), then process in the background.
+2. ALWAYS call `ctx.answerCbQuery()` for every callback query, or the user sees a spinner forever.
+3. NEVER expose internal errors or stack traces in replies — register a global `bot.catch` and send a friendly message instead.
+4. ALWAYS handle the `successful_payment` event and activate the paid feature BEFORE replying.
+5. ALWAYS register `SIGINT` and `SIGTERM` handlers that stop the bot cleanly (`bot.stop()`).
+6. ALWAYS validate user input, and check usage limits before any paid or rate-limited action.
+7. Keep replies concise — Telegram users read on mobile.
+
+## Stack Selection (decide first)
+
+Pick the library by detection, in order; stop at the first match:
+
+1. An existing bot dependency in `package.json` / `pyproject.toml` (telegraf, grammy, aiogram, python-telegram-bot, pyrogram, telethon) → keep it; do not migrate.
+2. New TypeScript/Node project → **grammY** (TypeScript-first, modern async) or **Telegraf** (mature, larger ecosystem). Prefer grammY for a fresh TS codebase; pick Telegraf if the team already knows it.
+3. New Python project → **aiogram** (async, scales) for anything beyond a prototype; **python-telegram-bot** for a quick prototype.
+4. Userbot / low-level MTProto client features (not a bot token) → **pyrogram** or **telethon**.
+5. Default when nothing above matches → grammY (Node) or aiogram (Python).
+
+## Bot Architecture
+
+Separate concerns:
+
+```
+src/
+├── bot.ts        # initialization, handler registration
+├── commands/     # one file per /command
+├── handlers/     # message + callback query handlers
+├── keyboards/    # reusable inline keyboard builders
+├── middleware/   # auth, logging, rate-limit, i18n
+├── services/     # business logic, DB access
+└── config.ts     # env parsing
+```
+
+`bot.ts` registers command, text, and callback query handlers, then starts the bot: `bot.launch()` (Telegraf) or `bot.start()` (grammY). Wire graceful shutdown per Hard Rule 5.
+
+## Inline Keyboards
+
+Build with `Markup.inlineKeyboard()` — an array of rows, each row an array of buttons. One button per row = vertical menu; several buttons per row = a horizontal row (yes/no, pagination). Use `Markup.button.url()` for external links and payment pages.
+
+```typescript
+import { Markup } from 'telegraf';
+
+Markup.inlineKeyboard([
+  [Markup.button.callback('Option A', 'opt_a')],          // vertical menu
+  [Markup.button.callback('Yes', 'yes'),
+   Markup.button.callback('No', 'no')],                   // one row, two buttons
+  [Markup.button.url('Docs', 'https://example.com')],     // external link
+]);
+```
+
+Paginated list — slice by page, then append nav buttons only when they exist:
+
+```typescript
+function pageKeyboard(items, page, perPage) {
+  const start = page * perPage;
+  const rows = items.slice(start, start + perPage)
+    .map((it) => [Markup.button.callback(it.label, `pick:${it.id}`)]);
+  const nav = [];
+  if (page > 0) nav.push(Markup.button.callback('« Prev', `page:${page - 1}`));
+  if (start + perPage < items.length) nav.push(Markup.button.callback('Next »', `page:${page + 1}`));
+  if (nav.length) rows.push(nav);
+  return Markup.inlineKeyboard(rows);
+}
+
+bot.action(/^page:(\d+)$/, async (ctx) => {
+  await ctx.answerCbQuery();                               // Hard Rule 2
+  const page = Number(ctx.match[1]);
+  const items = await listItems();                         // your data source
+  await ctx.editMessageText('Page ' + (page + 1), pageKeyboard(items, page, 5));
+});
+```
+
+## Monetization
+
+Revenue models, ordered low → high on both effort and revenue:
+
+1. Ads / affiliate links — low effort, low revenue.
+2. Per-use payments — low effort, via Telegram Payments.
+3. Freemium with usage limits — medium effort, common pattern.
+4. Subscription — medium effort, needs retention work.
+
+Telegram Payments flow: create the invoice with `ctx.replyWithInvoice({ title, description, payload, provider_token, currency, prices })`; answer the `pre_checkout_query` with `ctx.answerPreCheckoutQuery(true)`; on `successful_payment`, activate the feature before replying (Hard Rule 4).
+
+Freemium: store per-`userId` usage in the DB, check the daily limit before each gated action, and prompt an upgrade when the limit is reached.
+
+## Error Handling
+
+Register one global handler so no request times out (Hard Rule 3). Log with enough context to debug; apply rate limiting to prevent abuse.
+
+```typescript
+bot.catch((err, ctx) => {
+  logger.error({ err, update: ctx.update }, 'bot error');
+  ctx.reply('Что-то пошло не так. Уже разбираемся.').catch(() => {});
+});
+```
+
+## Background Processing
+
+For work longer than Telegram's response timeout (~10s for webhooks, ~30s for long polling): acknowledge immediately (typing indicator or a "processing…" message), do the work in the background, then send or edit-in the result. For heavier loads use a queue (BullMQ, Celery, RabbitMQ) and edit the "processing…" message on completion.
+
+## Webhook vs Long Polling
+
+| Aspect | Webhook | Long polling |
+|--------|---------|--------------|
+| Latency | Low | Higher |
+| Hosting | Public HTTPS endpoint required | Any environment |
+| Scaling | Horizontal (load balancer) | Single process (or distributed via shared queue) |
+| Dev experience | Needs ngrok / cloudflared locally | Just run |
+| Best for | Production | Local dev, low traffic |
+
+Production: Telegraf `bot.createWebhook()` / grammY `webhookCallback()`, mounted on your web framework.
+
+## Recap — non-negotiables
+
+- Never block in a handler; acknowledge long work immediately and finish it in the background.
+- Answer every callback query (`ctx.answerCbQuery()`); never leak stack traces — use `bot.catch`.
+- Activate paid features on `successful_payment` before replying; check usage limits before gated actions.
+- Register `SIGINT`/`SIGTERM` shutdown, validate input, and keep replies short.
+
+Adapted from vibeship-spawner-skills (Apache 2.0).