feat(comms): content strategy and Comms agent infrastructure

.gitignore

@@ -149,3 +149,4 @@ test.py
 experiments/log.jsonl
 # Agent daily reports (generated per heartbeat, can be large)
 experiments/reports/
+agents/backup/

docs/comms/README.md

@@ -0,0 +1,36 @@
+# FFmemes Content Strategy
+
+Content workspace for @ffmemes Telegram channel (https://t.me/ffmemes).
+
+**Target cadence**: ~1 post per day
+**Language**: Russian only
+**Tone**: dania-zip rules (https://github.com/ohld/dania-zip)
+**Approval**: All posts require CEO approval before publishing
+
+## Structure
+
+```
+docs/comms/
+  content-plan.md    # Post categories, ideas, suggested schedule
+  brand-guide.md     # Visual identity: colors, font, chart palette
+  lore/              # Historical archive (channel history, vc.ru article, milestones)
+  drafts/            # Comms agent drafts awaiting CEO approval
+  published/         # Published post archive for reference
+```
+
+## Workflow
+
+1. Comms agent reads content plan + Analyst reports
+2. Picks next post from schedule or creates data-driven post
+3. Drafts post as Paperclip issue with text + visual description
+4. CEO reviews and approves
+5. Agent posts to @ffmemes channel
+6. Post moved to `published/` with date prefix
+
+## Links
+
+- Content plan: [content-plan.md](content-plan.md)
+- Brand guide: [brand-guide.md](brand-guide.md)
+- Lore archive: [lore/](lore/)
+- Tone of voice: https://github.com/ohld/dania-zip
+- Comms agent spec: [../../agents/comms/AGENTS.md](../../agents/comms/AGENTS.md)

docs/comms/brand-guide.md

@@ -0,0 +1,128 @@
+# Brand Guide — FFmemes
+
+Minimal visual identity. Iterate after 10+ posts.
+
+## Name
+
+- Full: **Fast Food Memes**
+- Short: **FFmemes**
+- Bot: **@ffmemesbot**
+- Channel (RU): **@ffmemes** (t.me/fastfoodmemes)
+- Channel (EN): **@fast_food_memes** (t.me/fast_food_memes)
+
+## Logo
+
+Hamburger avatar. Used on:
+- @ffmemesbot Telegram bot
+- @ffmemes Telegram channel
+- Paperclip company profile
+
+No SVG/PNG file exists yet. Source: Telegram avatar.
+
+## Typography
+
+- **Primary**: Work Sans Medium (used in watermarks, `src/storage/watermark.py`)
+- **Posts**: System fonts (Telegram renders text natively)
+- **Charts**: Work Sans or system sans-serif
+
+## Color Palette
+
+Derived from the hamburger. Use these for charts, diagrams, infographics.
+
+| Name | Hex | Usage |
+|------|-----|-------|
+| Bun (primary) | `#FF6B35` | Primary accent, chart highlights, headers |
+| Dark | `#1A1A2E` | Chart backgrounds, text on light |
+| Positive | `#4CAF50` | Likes, growth, success |
+| Negative | `#E74C3C` | Dislikes, drops, alerts |
+| Neutral | `#95A5A6` | Muted elements, axes, borders |
+| Light | `#F5F5F5` | Chart backgrounds (light mode) |
+
+### Chart palette (for matplotlib/PIL)
+
+```python
+BRAND_COLORS = {
+    "primary": "#FF6B35",
+    "dark": "#1A1A2E",
+    "positive": "#4CAF50",
+    "negative": "#E74C3C",
+    "neutral": "#95A5A6",
+    "light": "#F5F5F5",
+}
+
+# For multi-series charts
+CHART_SERIES = ["#FF6B35", "#4CAF50", "#3498DB", "#9B59B6", "#E74C3C"]
+```
+
+## Tone of Voice
+
+Full reference: https://github.com/ohld/dania-zip
+
+Key rules:
+- Russian language (always)
+- No greetings ("Привет, друзья!" is forbidden)
+- Hook first — first 1-2 lines grab attention
+- Emoji bullets only (structural, not decorative). Max 1-3 per post
+- One thought per line. Short sentences.
+- Max 15-25 lines. Cut aggressively.
+- First person: "Я сделал", "Вот что узнал"
+- Shows process, not just result
+- Casual, like talking to a friend who codes
+- Never corporate, never dry
+- RU-EN tech term mixing: "навайбкодить", "рисерчить"
+
+Anti-patterns (NEVER):
+- "Привет, друзья!" or any greeting
+- "В рамках данной статьи", "мы рады сообщить" (corporate)
+- Numbered lists (1. 2. 3.) — use emoji bullets
+- Humble-bragging
+- Hedging: ИМХО, наверное, мне кажется
+- "Давайте разберёмся"
+
+Signature patterns:
+- "И ХОБА" — surprise twist
+- `~ @danokhlopkov ~` — post signature
+- Casual: мб, кмк, хз, кайф, жиза, го, чел
+
+## Visual Post Formats
+
+Every post must include an image. Types:
+
+### 1. Bot Screenshots
+For feature spotlights. Take via browse skill or manually.
+- Crop to relevant area
+- No personal data visible
+
+### 2. Memes from DB
+For "meme of the day/week". Already watermarked with @ffmemesbot.
+- Pick memes that metaphorically relate to the post topic
+- Use the meme's telegram_file_id to send directly
+
+### 3. Charts
+For data posts. Generate with matplotlib or PIL.
+- Use brand palette above
+- Dark background (`#1A1A2E`) for dramatic effect
+- Or light background (`#F5F5F5`) for clean look
+- Always include axis labels
+- Add @ffmemesbot watermark in corner
+
+### 4. Diagrams
+For engineering/architecture posts.
+- Simple, clean lines
+- Brand colors
+- Max 5-7 elements (don't overwhelm)
+
+### 5. Stat Cards
+For daily pulse posts (C6).
+- Single big number + context
+- Brand primary color accent
+- Clean, minimal design
+
+## Watermark
+
+Existing implementation in `src/storage/watermark.py`:
+- Text: "@ffmemesbot"
+- Font: Work Sans Medium, 5% of image width
+- Placement: least-detailed corner (smart algorithm)
+- Opacity: 35%
+- Auto contrast: white on dark, black on light

docs/comms/content-plan.md

@@ -0,0 +1,135 @@
+# Content Plan — @ffmemes
+
+~1 post per day. All posts in Russian. CEO approves each post.
+
+Visual rule: every post should have an image (screenshot, chart, meme from DB, or diagram). No text-only posts.
+
+---
+
+## Categories
+
+### A: Feature Spotlights
+
+Deep dives into what the bot can do. One feature per post.
+
+| # | Topic | Status | Visual | Notes |
+|---|-------|--------|--------|-------|
+| A1 | Inline meme search | BLOCKED | Bot screenshot of inline results | Wait for E2E test |
+| A2 | Group chat AI agent | READY | Screenshot of bot replying in group | Include "Add to chat" deep link button |
+| A3 | Burger economy | READY | Screenshot of /kitchen + /leaderboard | What burgers are, how to earn/spend |
+| A4 | OCR meme descriptions | BLOCKED | Before/after: meme + extracted text | Wait for OCR_ENABLED=True |
+| A5 | Stars purchases | READY | Screenshot of buy menu | Buy burgers with Telegram Stars |
+| A6 | How recommendations work | READY | Diagram: "your like -> better memes" | Non-technical, simplified |
+| A7 | Upload your own memes | READY | Screenshot of upload flow | Show the moderation queue |
+| A8 | Weekly leaderboard | READY | Screenshot of /leaderboard | Top meme senders get burgers |
+
+### B: Historical / Lore
+
+The journey. Build-in-public spirit. Reference the archive in `lore/`.
+
+| # | Topic | Visual |
+|---|-------|--------|
+| B1 | "How it started" — vc.ru throwback, Oct 2020 | Screenshot of vc.ru article header |
+| B2 | "535K memes collected, 205K approved" | Infographic: funnel from sources to ok |
+| B3 | "22M reactions and counting" | Chart: reactions growth over time |
+| B4 | "9 recommendation engines" | Simple diagram of engine names |
+| B5 | "AI agents now run the bot" | Agent org chart from COMPANY.md |
+| B6 | Channel milestones throwback | Screenshots of old posts from archive |
+| B7 | "From 2.5K to 22K users" | Timeline graphic |
+
+### C: Data Insights
+
+Real numbers. Charts. From Analyst reports or direct DB queries.
+
+| # | Topic | Visual | Data source |
+|---|-------|--------|-------------|
+| C1 | Weekly engagement snapshot | DAU/WAU/MAU chart | docs/analyst/metrics.sql |
+| C2 | Meme of the week (most liked) | The actual meme | meme_stats ORDER BY nlikes |
+| C3 | Top meme sources this week | Bar chart by like rate | meme_source_stats |
+| C4 | Session length update | Line chart | North Star metric |
+| C5 | Like rate by language/time | Heatmap or bar chart | user_meme_reaction analysis |
+| C6 | "X new memes today from Y sources" | Simple stat card | Daily meme count |
+| C7 | Interesting data anomaly | Chart + explanation | Ad-hoc analysis |
+
+### D: Engagement / Interactive
+
+Drive action. Giveaways, CTAs, voting.
+
+| # | Topic | Mechanism | Status |
+|---|-------|-----------|--------|
+| D1 | "77 burgers to first 100 clickers" | Deep link `?start=giveaway_77` | BLOCKED (needs handler) |
+| D2 | "Rate which features to build" | Star voting InlineKeyboard | BLOCKED (needs handler) |
+| D3 | "Add bot to your group chat" | `?startgroup=true` deep link button | READY (needs constant) |
+| D4 | "Share your meme stats" card | PIL-generated personalized card | BLOCKED (needs implementation) |
+
+### E: Recurring Formats
+
+Predictable cadence. Readers know when to expect what.
+
+| # | Format | Schedule | Status |
+|---|--------|----------|--------|
+| E1 | Weekly burger balance report | Sunday 14:00 MSK | BLOCKED (needs Prefect flow) |
+| E2 | "Meme of the day" — top meme from yesterday | Daily morning | READY |
+| E3 | Weekly what-we-shipped digest | Friday | READY |
+
+### F: Behind-the-scenes / Engineering
+
+Nerdy content. How things work under the hood.
+
+| # | Topic | Visual |
+|---|-------|--------|
+| F1 | "How our parsers collect memes" | Pipeline diagram |
+| F2 | "Watermark algorithm finds the quietest corner" | Before/after meme with watermark |
+| F3 | "PostgreSQL handles 22M reactions" | Architecture diagram |
+| F4 | "Prefect runs 23 scheduled jobs" | Dashboard screenshot or job list |
+| F5 | "AI describes every meme" — vision model pipeline | Meme + generated description side-by-side |
+
+---
+
+## Suggested First 2 Weeks
+
+| Day | Post | Category | Why this order |
+|-----|------|----------|----------------|
+| 1 | Origin story throwback (B1) | Lore | Sets the "we're back" tone |
+| 2 | Daily pulse: X memes from Y sources (C6) | Data | Easy, automated, shows scale |
+| 3 | Burger economy reveal (A3) | Feature | Teases what's coming |
+| 4 | Meme of the day (E2) | Recurring | Start the daily habit |
+| 5 | 535K memes collected (B2) | Lore | Impressive number |
+| 6 | Upload your own memes (A7) | Feature | Actionable CTA |
+| 7 | First weekly burger report (E1) | Recurring | Sunday 14:00 MSK |
+| 8 | Watermark algorithm (F2) | Engineering | Nerdy but fun |
+| 9 | 77 burger giveaway (D1) | Engagement | Drive clicks |
+| 10 | Meme of the week (C2) | Data | The actual best meme |
+| 11 | Group chat AI (A2) | Feature | "Add to chat" button |
+| 12 | AI agents run the bot (B5) | Lore | Mind-blowing for audience |
+| 13 | Weekly engagement snapshot (C1) | Data | DAU/WAU/MAU chart |
+| 14 | What we shipped this week (E3) | Recurring | Friday digest |
+
+---
+
+## Visual Guidelines
+
+Every post should include an image. Types:
+
+1. **Bot screenshots** — for feature spotlights (A-category). Take via browse skill or manually.
+2. **Memes from DB** — for "meme of the day/week" (C2, E2). Already watermarked.
+3. **Charts** — for data posts (C-category). Generate with PIL/matplotlib using brand palette.
+4. **Diagrams** — for engineering posts (F-category). Simple, clean, brand colors.
+5. **Infographics** — for lore posts (B-category). Timeline/funnel style.
+
+See [brand-guide.md](brand-guide.md) for colors, fonts, and chart styling.
+
+---
+
+## Blockers
+
+| What | Blocks | Action needed |
+|------|--------|---------------|
+| E2E test of inline search | A1 | Run E2E tests on bot |
+| OCR_ENABLED=False | A4 | Enable OCR in prod |
+| Giveaway deep link handler | D1 | Code: new handler in start.py |
+| Star voting handler | D2 | Code: new InlineKeyboard handler |
+| Personalized stats card | D4 | Code: PIL card generation |
+| Weekly report Prefect flow | E1 | Code: weekly_report.py |
+| ADD_TO_GROUP_DEEPLINK | A2, D3 | Code: constant in constants.py |
+| Chart generation utils | C1, C3, C4 | Code: matplotlib/PIL helpers |

docs/comms/lore/README.md

@@ -0,0 +1,33 @@
+# FFmemes Lore — Historical Archive
+
+Timeline of the project from inception to autonomous AI team.
+
+## Key Milestones
+
+| Date | Event | Source |
+|------|-------|--------|
+| ~2020 | Bot created by Dan Okhlopkov with a friend | vc.ru article |
+| Oct 2, 2020 | vc.ru article published — "Я задолбался искать смешные мемы" | [vc-ru-origin-story-2020-10.md](vc-ru-origin-story-2020-10.md) |
+| Oct 2020 | 12K users, 2.5K WAU, 50K memes, 1.8M reactions | vc.ru article |
+| Oct 2020 | Inline search alpha launched (attracted 98 users organically) | vc.ru article |
+| Oct 2020 | 50+ moderators, 66% like rate, 25 memes/session | vc.ru article |
+| ... | _Gap: need to fill from channel archive_ | @ffmemes channel |
+| Mar 2026 | 22.4K users, 530 WAU, 535K memes, 22M+ reactions | DB metrics |
+| Mar 2026 | 9 recommendation engines, 750+ sources | Current codebase |
+| Mar 2026 | AI agent team runs bot autonomously | Paperclip/agents/ |
+| Mar 2026 | Burger economy (Telegram Stars) launched | Treasury system |
+| Mar 2026 | Group chat AI agent with DeepSeek | Chat handlers |
+
+## Archive Files
+
+- [vc-ru-origin-story-2020-10.md](vc-ru-origin-story-2020-10.md) — The original vc.ru banger article
+- `ffmemes-channel-archive.md` — TODO: Comms agent to browse t.me/s/fastfoodmemes and extract all posts
+- `danokhlopkov-mentions.md` — TODO: Comms agent to browse t.me/s/danokhlopkov and find ffmemes mentions
+
+## How to Use This Archive
+
+The Comms agent references this archive for:
+- B-category posts (Historical/Lore) in the content plan
+- "Then vs now" comparisons using real numbers
+- Throwback posts with screenshots of old channel posts
+- Building the narrative arc of the project