doc: update after adding placeholders guide

doc: add placeholders info
2026-01-05 22:59:59 +07:00 · 2026-01-05 22:49:40 +07:00
4 changed files with 325 additions and 109 deletions
--- a/INDEX.md
+++ b/INDEX.md
@ -1,8 +1,8 @@
 # Banatie Strategy Documentation Index

-**Last Updated:** December 30, 2025
-**Total Documents:** 19 (numbered in strategy/execution) + research (prefixed)
-**Next Available Number:** 19
+**Last Updated:** January 2, 2026
+**Total Documents:** 20 (numbered in strategy/execution) + research (prefixed)
+**Next Available Number:** 20
 **Project Stage:** Pre-launch / MVP Development

 ---
@ -34,7 +34,9 @@
 - 17 - Week 1 Launch Checklist
 - 18 - Production Infrastructure

-**Next to assign:** 19
+- 19 - Placeholder SEO Sprint
+
+**Next to assign:** 20

 ---

@ -56,7 +58,8 @@
 - [Pricing Strategy](execution/10-pricing-strategy.md)
 - [Validation Plan](execution/08-validation-plan.md)

-**For SEO & Content:** ⭐ NEW
+**For SEO & Content:** ⭐ ACTIVE
+- [Placeholder SEO Sprint](execution/19-placeholder-seo-sprint.md) - Current sprint plan ⭐
 - [SEO Keyword Research: Placeholder Images](research/seo-keyword-research-placeholder-images.md) - Entry point cluster
 - [Research Index](research/INDEX.md) - All research documentation

@ -195,6 +198,12 @@ Includes: Pre-launch checklist, launch day schedule, Reddit/Discord copy templat
 Status: ✅ Live
 Includes: VPS setup, Cloudflare config, SEO, Analytics, Performance metrics

+**[19 - Placeholder SEO Sprint](execution/19-placeholder-seo-sprint.md)** (Jan 2, 2026) ⭐ ACTIVE
+*Capture 31K+ monthly placeholder image searches*
+Status: 🔄 Active Sprint
+Tracks: Landing page `/placeholder-images`, Docs `/docs/placeholders/`, Homepage quick wins
+Target: Zero-KD keywords + 14,800 vol main keyword
+
 ### Technical Documentation

 **[12 - Current Tech State](execution/12-the-current-tech-state.md)** (v1.0, Nov 1)
@ -417,5 +426,5 @@ research/seo-keyword-research-*.md → ROADMAP.md (Content Sprint) → blog arti
 ---

 **Last maintained by:** @men
-**Version:** 4.2 (Project Knowledge integration docs added Dec 29-30)
-**Next review:** After Content Marketing Sprint (January 2025)
+**Version:** 4.3 (Placeholder SEO Sprint added Jan 2, 2026)
+**Next review:** End of Placeholder SEO Sprint (mid-January 2026)
--- a/ROADMAP.md
+++ b/ROADMAP.md
@ -15,11 +15,13 @@

 ## 🎯 Current Status

-**Phase:** Pre-launch / Full Stack Deployed (Testing WIP)
-**Sprint:** Production Infrastructure + Testing
-**Focus:** API Testing + SEO Foundation + Content Marketing Prep
-**Next Milestone:** Customer Interviews + Content Marketing
-**Last Updated:** December 30, 2025
+**Phase:** Pre-launch / Full Stack Deployed  
+**Sprint:** Placeholder SEO Sprint ⭐ ACTIVE (Track A remaining)  
+**Focus:** Capture 31K+ monthly placeholder image searches  
+**Next Task:** Create landing page `/placeholder-images`  
+**Last Updated:** January 5, 2026
+
+**See:** [19-placeholder-seo-sprint.md](execution/19-placeholder-seo-sprint.md)

 ---

@ -41,59 +43,67 @@
 - [x] **Master API key generated**
 - [x] **Caddy reverse proxy configured** for all endpoints
 - [x] **DNS records added** (api, cdn, storage subdomains)
- [ ] **Full API testing** (generation, upload, CDN URLs) — planned by Dec 27
+- [ ] **Full API testing** (generation, upload, CDN URLs) — planned

 **See:** [18-production-infrastructure.md](execution/18-production-infrastructure.md)

-### DataForSEO Integration (Dec 26, 2025) ⭐ NEW
+### DataForSEO Integration (Dec 26, 2025)
 - [x] **DataForSEO MCP Server connected** to Claude Code
 - [x] **First keyword research completed** — "placeholder images" cluster
 - [x] **Research methodology validated** — $0.14 per full research cycle
 - [x] **Content opportunities identified** — 5 articles with clear targets

-**See:** [research/seo-keyword-research-placeholder-images.md](research/seo-keyword-research-placeholder-images.md)
-
-### Project Knowledge Integration (Dec 29-30, 2025) ⭐ NEW
+### Project Knowledge Integration (Dec 29-30, 2025)
 - [x] **BANATIE-CONTENT-INTEGRATION.md** created in Project Knowledge
-  - Navigation map for banatie-content repository
-  - Multi-agent system (9 agents), content pipeline, research structure
-  - Strategic input channels defined (inbox, Perplexity threads)
 - [x] **BANATIE-SERVICE-INTEGRATION.md** created in Project Knowledge
-  - Navigation map for banatie-service technical repository
-  - Monorepo structure, API docs paths, landing components
-  - Production URLs, deployment commands, key differentiators
-
-**Purpose:** Enable @men to find authoritative information across repositories during strategy sessions.
-
-### Known Issues (Minor)
- [ ] Healthcheck: containers show "unhealthy" (no curl in images)
- [ ] Cache permission: landing warns about `.next/cache`

 ---

-## 🔄 Active Sprint: ICP External Validation + SEO Foundation
+## ✅ Completed: Placeholder SEO Sprint — Tracks B+C (Jan 2-5, 2026)

-### Interview Preparation
- [ ] Create interview scripts for each segment (4 scripts)
- [ ] Identify specific outreach targets
- [ ] Prepare validation scorecard
+### Research Findings (Jan 2, 2026)
+- [x] **Deep dive completed** — 31K+ monthly searches discovered
+- [x] **Zero-KD keywords identified** — 10+ keywords with KD 0-5
+- [x] **Direct user validation found** — r/ClaudeAI quote about MCP for placeholders
+- [x] **Execution plan created** — 19-placeholder-seo-sprint.md

-### Content Marketing System
- [x] Multi-agent content pipeline designed (8 agents)
- [x] Author personas defined (Henry, Nina)
- [x] **DataForSEO integrated for real keyword data** ⭐ NEW
- [ ] First batch of articles for dev.to, Hashnode
+### Track C: Homepage Quick Wins ✅ COMPLETE
+- [x] **Keywords in metadata** — added placeholder-related keywords
+- [x] **PromptUrlsSection** — updated to mention placeholders first

-### SEO Foundation ⭐ NEW (High Priority)
- [ ] **Create `/placeholder-images` landing page** — target: 14,800 searches/mo
- [ ] **Write "Placeholder Images API" tutorial** — target KD 12, dev.to + blog
- [ ] Integrate DataForSEO into @spy/@strategist agents
- [ ] Research additional keyword clusters (use-case, tech stack)
+### Track B: Docs Section ✅ COMPLETE
+- [x] **Live URLs docs enhanced** — added placeholder section with examples
+- [x] **Guides section created** — `/docs/guides/`
+- [x] **Placeholder Images guide** — `/docs/guides/placeholder-images/`
+  - Templates (general, photorealistic, illustration, etc.)
+  - Dark mode and color control
+  - Common use cases (avatars, heroes, products)
+  - File-based workflow

-### Production Testing
- [ ] Test image generation via API
- [ ] Verify CDN URLs working correctly
- [ ] Document API for early users
+---
+
+## 🔄 Active: Placeholder SEO Sprint — Track A
+
+### Track A: Landing Page `/placeholder-images` ⏳ TODO
+
+**Goal:** Capture 14,800+ monthly searches for core "placeholder image" keyword
+
+**Target Keywords:**
+| Keyword | Volume | KD |
+|---------|--------|-----|
+| placeholder image | 14,800 | 18 |
+| image placeholder | 14,800 | 17 |
+| ai placeholder images | — | — |
+| placeholder image generator | 480 | 32 |
+
+**Page Structure:**
+- Hero with instant demo
+- How It Works (3 steps)
+- Interactive size grid
+- Comparison table (vs placehold.co, picsum)
+- Production bridge CTA
+
+**File:** `apps/landing/src/app/(landings)/placeholder-images/page.tsx`

 ---

@ -102,40 +112,25 @@
 | URL | Purpose | Status |
 |-----|---------|--------|
 | https://banatie.app/ | Landing page | ✅ Live |
-| https://api.banatie.app/ | API service | 🔄 Deployed (testing pending) |
-| https://cdn.banatie.app/ | Image CDN | 🔄 Deployed (testing pending) |
-| https://storage.banatie.app/ | MinIO Console | 🔄 Deployed (testing pending) |
+| https://banatie.app/docs/guides/placeholder-images | Placeholder guide | ✅ Live |
+| https://api.banatie.app/ | API service | 🔄 Deployed |
+| https://cdn.banatie.app/ | Image CDN | 🔄 Deployed |

 ---

-## 📅 Upcoming: Content Marketing Sprint (January 2025)
+## 📅 Next Up: Content Marketing Sprint (After Placeholder Landing)

-**Duration:** 2 weeks intensive
-**Goal:** Establish thought leadership, drive organic traffic
+### SEO-Driven Content (from keyword research)

-### SEO-Driven Content (from keyword research) ⭐ NEW
-
-| Priority | Content Type | Target Keyword | Volume | KD | Platform |
-|----------|--------------|----------------|--------|-----|----------|
-| 🥇 | Landing page | placeholder images | 14,800 | 32 | banatie.app |
-| 🥇 | Dev tutorial | placeholder images api | 90 | 12 | dev.to + blog |
-| 🥈 | Listicle | placeholder image generator | 480 | 32 | dev.to + blog |
-| 🥈 | Tutorial | image placeholder html | 320 | 34 | blog |
-| 🥉 | Blog post | random image api | 110 | 17 | blog |
-
-**See:** [research/seo-keyword-research-placeholder-images.md](research/seo-keyword-research-placeholder-images.md)
+| Priority | Content Type | Target Keyword | Volume | KD |
+|----------|--------------|----------------|--------|-----|
+| 🥇 | Landing page | placeholder images | 14,800 | 18 |
+| 🥈 | Dev tutorial | placeholder images api | 90 | 12 |
+| 🥈 | Tutorial | image placeholder html | 320 | 34 |

 ### Additional Planned Content
 - Personal articles (dev.to, LinkedIn): 2-3 pieces
- Henry persona articles (dev.to, Hashnode): 4-6 pieces
- Nina persona (Instagram, creative): ongoing
-
-### Platforms
- dev.to
- Hashnode
- daily.dev
- LinkedIn
- Product Hunt (later)
+- Henry persona articles: 4-6 pieces

 ---

@ -165,41 +160,23 @@

 ---

-### GATE 3: PMF Validation (Target: Q2-Q3 2025)
-
-**Success criteria:**
- $1-2K MRR achieved
- <5% monthly churn
- Organic word-of-mouth
-
---
-
 ## 📋 Backlog

 ### Technical
 - [ ] Docs page with API examples
- [ ] Signup flow automation
 - [ ] MCP Server implementation
 - [ ] SDK TypeScript/Python
 - [ ] CLI tool
- [ ] Image transformations

 ### Marketing
 - [ ] Reddit r/cursor launch post
- [ ] Discord Cursor community engagement
 - [ ] Product Hunt launch
 - [ ] Case studies

-### SEO & Content ⭐ NEW
+### SEO & Content
 - [ ] Research additional keyword clusters
- [ ] Expand content-system to cover website pages
 - [ ] Competitor keyword gap analysis (fal.ai, runware.ai)

-### Infrastructure
- [ ] Healthcheck fix in Dockerfiles
- [ ] Self-hosted Umami migration
- [ ] Email service integration
-
 ---

 ## 🎯 Success Definitions
@ -207,30 +184,25 @@
 ### Current Phase Success
 - ✅ Full stack deployed and working
 - ✅ Landing page live with good SEO
- ✅ Keyword research methodology validated ⭐ NEW
+- ✅ Keyword research methodology validated
+- ✅ Placeholder docs/guide created
+- ⏳ Placeholder landing page
 - ⏳ ICP validated externally
 - ⏳ First paying customers

 ### Q1 2025 Success
 - $500-1K MRR
 - 10-20 active users
- Clear PMF signals
- Top-10 rankings for target keywords ⭐ NEW
-
-### Q2 2025 Success
- $2-3K MRR
- Sustainable growth
- Content marketing working
+- Top-10 rankings for target keywords

 ---

-**Roadmap Owner:** @men + Oleg
-**Last Updated:** December 26, 2025
-**Next Review:** After ICP validation interviews
-**Version:** 4.2 (Project Knowledge integration docs added Dec 29-30)
+**Roadmap Owner:** @men + Oleg  
+**Last Updated:** January 5, 2026  
+**Next Review:** After placeholder landing page deployment  
+**Version:** 4.4 (Sprint progress updated Jan 5, 2026)

 **Key Documents:**
- [research/seo-keyword-research-placeholder-images.md](research/seo-keyword-research-placeholder-images.md) - Keyword research ⭐ NEW
- [18-production-infrastructure.md](execution/18-production-infrastructure.md) - Deployment details
- [13-competitive-analysis.md](strategy/13-competitive-analysis.md) - Competitive landscape
- [14-icp-segmentation-unified.md](strategy/14-icp-segmentation-unified.md) - Unified ICP segments
+- [19-placeholder-seo-sprint.md](execution/19-placeholder-seo-sprint.md) — Current sprint ⭐
+- [research/seo-keyword-research-placeholder-images.md](research/seo-keyword-research-placeholder-images.md) — Keyword research
+- [18-production-infrastructure.md](execution/18-production-infrastructure.md) — Deployment details
--- a/execution/19-placeholder-seo-sprint.md
+++ b/execution/19-placeholder-seo-sprint.md
@ -0,0 +1,171 @@
+# Placeholder SEO Sprint
+
+**Date Created:** January 2, 2026  
+**Status:** Active — Track A remaining  
+**Priority:** HIGH  
+**Owner:** Oleg  
+**Last Updated:** January 5, 2026
+
+---
+
+## Sprint Summary
+
+@spy research uncovered major SEO opportunity:
+
+| Metric | Value |
+|--------|-------|
+| Total search volume | 31,000+/month |
+| Zero-KD keywords | 10+ keywords (profile, ios, dark mode) |
+| AI competitors | **ZERO** |
+| Direct user validation | r/ClaudeAI quote about MCP for placeholders |
+
+**Strategic approach:** "Trojan Horse" — capture placeholder traffic, convert to full generation users.
+
+**Source:** `/banatie-content/research/keywords/placeholder-niche-deep-dive-2026-01-02.md`
+
+---
+
+## Research Key Findings
+
+### Top Keywords by Priority
+
+| Keyword | Volume | KD | Status |
+|---------|--------|-----|--------|
+| placeholder image | 14,800 | 18 | → Landing page |
+| image placeholder dark | 4,400 | 2 | ✅ Covered in guide |
+| app placeholder image | 1,900 | 2 | ✅ Covered in guide |
+| profile placeholder image | 720 | 0 | ✅ Covered in guide |
+| placeholder image url | 390 | 21 | ✅ Covered in Live URLs docs |
+
+### Zero-KD Opportunities (all covered in guide)
+
+- profile placeholder image — 720 vol, KD 0
+- ios placeholder image — 590 vol, KD 0
+- loading image placeholder — 170 vol, KD 0
+- image placeholder dark — 4,400 vol, KD 2
+- app placeholder image — 1,900 vol, KD 2
+
+### Direct User Validation
+
+From r/ClaudeAI:
+> "right now my instructions are to just do placeholder image in various sizes... I am wondering if there is an mcp that can create or fetch these images for Claude instead."
+
+---
+
+## Execution Status
+
+### Track A: Landing Page `/placeholder-images` ⏳ TODO
+
+**Goal:** Capture 14,800+ monthly searches for core placeholder keywords
+
+**Target Keywords:**
+- placeholder image (14,800)
+- image placeholder (14,800)
+- ai placeholder images
+- placeholder image generator
+- placeholder image url
+
+**Page Structure:**
+```
+1. HERO
+   ├── H1: "AI Placeholder Images"
+   ├── Subhead: "Generate contextual placeholders instantly"
+   └── CTA: "Try It Free"
+
+2. HOW IT WORKS (3 steps)
+
+3. SIZE GRID (interactive)
+   ├── Avatar (200×200)
+   ├── Thumbnail (300×200)
+   ├── Card (400×300)
+   └── Hero (1200×630)
+
+4. COMPARISON TABLE
+   | placehold.co | Gray boxes |
+   | picsum.photos | Random stock |
+   | Banatie | AI-generated, contextual |
+
+5. PRODUCTION BRIDGE
+   └── "Same images work in production"
+
+6. FOOTER CTA
+```
+
+**File to create:**
+- `apps/landing/src/app/(landings)/placeholder-images/page.tsx`
+
+---
+
+### Track B: Docs Updates ✅ COMPLETE
+
+| Task | Status | Location |
+|------|--------|----------|
+| Live URLs — placeholder section | ✅ Done | `/docs/live-urls/` |
+| Guides section created | ✅ Done | `/docs/guides/` |
+| Placeholder Images guide | ✅ Done | `/docs/guides/placeholder-images/` |
+
+**Guide covers:**
+- Quick Start with Live URLs
+- Templates (general, photorealistic, illustration, etc.)
+- Dark mode and color control
+- Common use cases (avatars, heroes, products, testimonials)
+- File-based workflow (API download)
+
+---
+
+### Track C: Homepage Quick Wins ✅ COMPLETE
+
+| Task | Status |
+|------|--------|
+| Keywords in metadata | ✅ Added placeholder-related keywords |
+| PromptUrlsSection subtitle | ✅ Updated to mention placeholders |
+
+---
+
+## Success Metrics
+
+### Completed ✅
+- [x] Placeholder guide live at `/docs/guides/placeholder-images/`
+- [x] Live URLs docs enhanced with placeholder examples
+- [x] Homepage keywords updated
+- [x] All pages in sitemap
+
+### Week 1 Targets
+- [ ] `/placeholder-images` landing live and indexed
+- [ ] GSC submission for new pages
+
+### Month 1 Targets
+- [ ] GSC shows impressions for placeholder keywords
+- [ ] First organic clicks from placeholder searches
+
+### Month 3 Targets
+- [ ] Top 20 for "placeholder image" (14,800 vol)
+- [ ] Top 10 for "image placeholder dark" (4,400 vol, KD 2)
+
+---
+
+## Next Steps
+
+1. **Create landing page** `/placeholder-images`
+   - Use research findings for structure
+   - Include interactive size grid
+   - Show comparison with competitors
+
+2. **Submit to GSC** after deployment
+
+3. **Monitor rankings** for target keywords
+
+---
+
+## Reference Documents
+
+- Research: `/banatie-content/research/keywords/placeholder-niche-deep-dive-2026-01-02.md`
+- Guide revision task: `/banatie-service/inbox/task-placeholder-guide-revision.md` (if created)
+- Docs SEO analysis: `/banatie-content/research/keywords/docs-seo-analysis-2026-01-02.md`
+
+---
+
+**Document Owner:** @men  
+**Last Updated:** January 5, 2026  
+**Next Review:** After landing page deployment  
+**Status:** Track B+C complete, Track A in progress
--- a/inbox/2026-01-02-mcp-competitive-landscape.md
+++ b/inbox/2026-01-02-mcp-competitive-landscape.md
@ -0,0 +1,64 @@
+# Strategy Alert: MCP Integration Now Industry Standard
+
+**Date:** 2026-01-02
+**Type:** Technology Shift
+**Urgency:** High
+
+## Summary
+
+Both Replicate and fal.ai now have official MCP (Model Context Protocol) servers documented and promoted. This means MCP integration has moved from "nice-to-have" differentiator to table stakes for AI image APIs targeting developers using Claude Code and Cursor.
+
+## Details
+
+**Replicate MCP:**
+- Official server at replicate.com/docs/reference/mcp
+- Supports model discovery, running predictions via natural language
+- Enables: "Search Replicate for upscaler models and compare them"
+
+**fal.ai MCP:**
+- Official integration at docs.fal.ai/model-apis/mcp
+- Documented specifically for Cursor integration
+- Full fal ecosystem accessible from IDE
+
+**Runware:**
+- No visible MCP integration
+- May be falling behind on developer experience
+
+**Community:**
+- Multiple third-party MCP servers for image generation on GitHub
+- r/mcp subreddit (82K subscribers) actively discussing AI image MCP servers
+- Cursor users expect MCP integration for AI services
+
+## Strategic Implications
+
+1. **Our MCP server is no longer a differentiator — it's required**
+   - Must ship and document MCP to compete with Replicate/fal.ai
+   - Delaying MCP means losing developer mindshare
+
+2. **Documentation must match competitor quality**
+   - Both competitors have dedicated MCP pages
+   - Include Cursor setup, Claude Desktop, Claude Code guides
+   - Show real workflow examples
+
+3. **Live URLs + MCP = Unique Combination**
+   - Neither competitor has URL-based generation without API calls
+   - MCP + Live URLs enables: "Generate a placeholder image at this URL"
+   - This is our defensible position
+
+4. **Market validation**
+   - MCP adoption confirms AI-first developers are target audience
+   - IDE integration is the battleground for developer workflows
+
+## Recommended Actions
+
+1. **Prioritize MCP server shipping** — move up in roadmap if not already top priority
+2. **Pre-write documentation** — have MCP docs ready when feature ships
+3. **Emphasize Live URLs in MCP context** — unique capability competitors lack
+4. **Monitor Runware** — if they ship MCP, market is fully consolidated on this expectation
+
+## Sources
+
+- https://replicate.com/docs/reference/mcp
+- https://docs.fal.ai/model-apis/mcp
+- https://www.reddit.com/r/mcp/comments/1p1l9tn/falai_mcp_server_enables_claude_desktop_and_other/
+- https://cursorintro.com/mcp-fal
Author	SHA1	Message	Date
Oleg Proskurin	0a7697c2dd	doc: update after adding placeholders guide	2026-01-05 22:59:59 +07:00
Oleg Proskurin	5b0bfa56b9	doc: add placeholders info	2026-01-05 22:49:40 +07:00