Initial commit with translated description

2026-03-29 13:13:54 +08:00
commit 8ad6a822e8
14 changed files with 3037 additions and 0 deletions
--- a/references/analytics-loop.md
+++ b/references/analytics-loop.md
@@ -0,0 +1,151 @@
+# Analytics & Feedback Loop
+
+## Performance Tracking
+
+### Postiz Analytics API
+
+**Platform analytics** (followers, views, likes, comments, shares over time):
+```
+GET https://api.postiz.com/public/v1/analytics/{integrationId}
+Authorization: {apiKey}
+```
+
+Response:
+```json
+[
+  { "label": "Followers", "percentageChange": 2.4, "data": [{ "total": "1250", "date": "2025-01-01" }] },
+  { "label": "Views", "percentageChange": 4, "data": [{ "total": "5000", "date": "2025-01-01" }] },
+  { "label": "Total Likes", "data": [{ "total": "6709", "date": "2026-02-15" }] },
+  { "label": "Recent Likes", "data": [{ "total": "6354", "date": "2026-02-15" }] },
+  { "label": "Recent Comments", "data": [{ "total": "148", "date": "2026-02-15" }] },
+  { "label": "Recent Shares", "data": [{ "total": "119", "date": "2026-02-15" }] },
+  { "label": "Videos", "data": [{ "total": "43", "date": "2026-02-15" }] }
+]
+```
+
+**Per-post analytics** (likes, comments per post):
+```
+GET https://api.postiz.com/public/v1/analytics/post/{postId}
+Authorization: {apiKey}
+```
+
+Response:
+```json
+[
+  { "label": "Likes", "percentageChange": 16.7, "data": [{ "total": "150", "date": "2025-01-01" }, { "total": "175", "date": "2025-01-02" }] },
+  { "label": "Comments", "percentageChange": 20, "data": [{ "total": "25", "date": "2025-01-01" }, { "total": "30", "date": "2025-01-02" }] }
+]
+```
+
+Note: Per-post analytics availability depends on the platform. TikTok may return empty arrays for some posts — in this case, fall back to the **delta method**: track platform-level view totals before and after each post to estimate per-post views.
+
+**List posts** (to get post IDs for analytics):
+```
+GET https://api.postiz.com/public/v1/posts?startDate={ISO}&endDate={ISO}
+Authorization: {apiKey}
+```
+
+### RevenueCat Integration (Optional)
+
+If the user has RevenueCat, track conversions from TikTok:
+- Downloads → Trial starts → Paid conversions
+- UTM parameters in App Store link
+- Compare conversion spikes with post timing
+
+## The Feedback Loop
+
+### After Every Post (24h)
+Record in `hook-performance.json`:
+```json
+{
+  "posts": [
+    {
+      "date": "2026-02-15",
+      "hook": "boyfriend said flat looks like catalogue",
+      "hookCategory": "person-conflict-ai",
+      "views": 15000,
+      "likes": 450,
+      "comments": 23,
+      "saves": 89,
+      "postId": "postiz-id",
+      "appCategory": "home"
+    }
+  ]
+}
+```
+
+### Weekly Review
+1. Sort posts by views
+2. Identify top 3 hooks → create variations
+3. Identify bottom 3 hooks → drop or radically change
+4. Check if any hook CATEGORY consistently wins
+5. Update prompt templates with learnings
+
+### Decision Rules
+
+| Views | Action |
+|-------|--------|
+| 50K+ | DOUBLE DOWN — make 3 variations immediately |
+| 10K-50K | Good — keep in rotation, test tweaks |
+| 1K-10K | Okay — try 1 more variation before dropping |
+| <1K (twice) | DROP — radically different approach needed |
+
+### What to Vary When Iterating
+- **Same hook, different person:** "landlord" → "mum" → "boyfriend"
+- **Same structure, different room/feature:** bedroom → kitchen → bathroom
+- **Same images, different text:** proven images can be reused with new hooks
+- **Same hook, different time:** morning vs evening posting
+
+## Conversion Tracking
+
+### Funnel
+```
+Views → Profile Visits → Link Clicks → App Store → Download → Trial → Paid
+```
+
+### Benchmarks
+- 1% conversion (views → download) = average
+- 1.5-3% = good
+- 3%+ = great
+
+### Attribution Tips
+- Track download spikes within 24h of viral post
+- Use unique UTM links per campaign if possible
+- RevenueCat `$attribution` for source tracking
+- Compare weekly MRR growth with weekly view totals
+
+## Daily Analytics Cron
+
+Set up a cron job to run every morning before the first post (e.g. 7:00 AM user's timezone):
+
+```
+Task: node scripts/daily-report.js --config tiktok-marketing/config.json --days 3
+Output: tiktok-marketing/reports/YYYY-MM-DD.md
+```
+
+The daily report:
+1. Fetches all posts from the last 3 days via Postiz API
+2. Pulls per-post analytics (views, likes, comments, shares)
+3. If RevenueCat is connected, pulls conversion events (trials, purchases) in the same window
+4. Cross-references: maps conversion timestamps to post publish times (24-72h attribution window)
+5. Applies the diagnostic framework:
+   - High views + High conversions → SCALE (make variations)
+   - High views + Low conversions → FIX CTA (hook works, downstream is broken)
+   - Low views + High conversions → FIX HOOKS (content converts, needs more eyeballs)
+   - Low views + Low conversions → FULL RESET (try radically different approach)
+6. Suggests 3-5 new hooks based on what's working
+7. Updates `hook-performance.json` with latest data
+8. Messages the user with a summary
+
+### Why 3 Days?
+- TikTok posts peak at 24-48 hours (not instant like Twitter)
+- Conversion attribution takes up to 72 hours (user sees post → downloads → trials → pays)
+- 3-day window captures the full lifecycle of each post
+
+### RevenueCat Integration
+When connected, the daily report pulls:
+- **Trial starts** within 24-72h of each post → maps to which hooks drive installs
+- **Paid conversions** (initial purchase + trial converted) → maps to which CTAs convert
+- **Revenue** per period → tracks actual MRR impact of content
+
+This is the difference between "this post got 50K views" (vanity) and "this post generated $47 in new subscriptions" (intelligence).
--- a/references/app-categories.md
+++ b/references/app-categories.md
@@ -0,0 +1,68 @@
+# App Category Templates
+
+## Home / Interior Design
+
+**Slide concept:** Same room, same angle, different interior styles.
+
+**Base prompt template (adapt wording for your image gen provider):**
+```
+Realistic photo of a [STYLE] [room type] in a small flat. [Room dimensions].
+Shot from [position]. [Window details]. [Door details]. [Key furniture with exact
+positions]. [Floor type]. [Ceiling details]. Natural lighting, phone camera quality.
+Portrait orientation.
+```
+
+**"Before" rules:**
+- Modern but tired, NOT ancient
+- Include flat screen TV on wall
+- Everyday items: mugs, remote, magazines
+- Magnolia walls, basic curtains, no decor
+
+**Style transforms:** Mid-century modern, Scandinavian, Industrial luxe, Coastal, Japandi, Maximalist bohemian
+
+---
+
+## Beauty / Cosmetics
+
+**Slide concept:** Same face, same angle, progressive enhancement.
+
+**Base prompt template:**
+```
+Close-up portrait photo of a young woman, [age], [ethnicity], [features],
+[hair], [makeup level]. [Expression], looking directly at camera. Natural 
+indoor lighting from window to the left. Plain wall background. Phone selfie 
+quality, natural skin texture with visible pores. Portrait orientation.
+```
+
+**Preservation rules:**
+- Face shape PIXEL-PERFECT identical
+- Nose, eyes EXACTLY the same
+- ALL skin texture preserved (pores, freckles)
+- NO skin smoothing or beauty filters
+- ONLY change the target feature (lips, lashes, etc.)
+
+---
+
+## Fitness / Body
+
+**Slide concept:** Same person, same pose, progressive transformation.
+
+**Base prompt:** Mirror selfie or gym photo, consistent lighting and background.
+
+**Transform progression:** Current → 1 month → 3 months → 6 months (subtle, believable changes)
+
+---
+
+## Productivity / SaaS
+
+**Slide concept:** Before/after workflow visualization OR results demonstration.
+
+**Approach:** Can use screenshots with text overlays rather than AI images. Show the messy "before" (spreadsheets, chaos) vs clean "after" (organized, automated).
+
+---
+
+## Food / Recipe
+
+**Slide concept:** Same dish, different presentations or same ingredients, different meals.
+
+**Base prompt:** Overhead shot of food on table, consistent tableware and background.
--- a/references/competitor-research.md
+++ b/references/competitor-research.md
@@ -0,0 +1,101 @@
+# Competitor Research Guide
+
+## Why This Matters
+
+Before creating content, you MUST understand the landscape. What hooks are competitors using? What's getting views? What gaps exist? This research directly drives your hook strategy and content differentiation.
+
+## Research Process
+
+### 1. Ask for Browser Permission
+
+Always ask the user before browsing. Something like:
+
+> "I want to research what your competitors are doing on TikTok — what's getting views, what hooks they use, what's working. Can I use the browser to look around?"
+
+### 2. TikTok Research
+
+Search TikTok for the app's niche. Look for:
+
+- **Competitor accounts** posting similar content (aim for 3-5)
+- **Top-performing videos** in the niche — what hooks do they use?
+- **Slide formats** — before/after, listicle, POV, tutorial, reaction
+- **View counts** — what's average vs exceptional in this niche?
+- **Posting frequency** — how often do successful accounts post?
+- **CTAs** — "link in bio", "search on App Store", app name in text, etc.
+- **Trending sounds** — what music/sounds are popular in this niche?
+- **Comment sentiment** — what do people ask about? What complaints?
+
+### 3. App Store Research
+
+Check the app's category on App Store / Google Play:
+
+- Competitor apps in the same category
+- Their screenshots, descriptions, ratings
+- What features they highlight
+- Their pricing model (free, freemium, subscription)
+- Review sentiment — what do users love/hate about competitors?
+
+### 4. Gap Analysis
+
+The most valuable output is identifying what competitors AREN'T doing:
+
+- **Content gaps:** Formats no one is using (listicles? tutorials? comparisons?)
+- **Hook gaps:** Emotional angles no one has tried
+- **Platform gaps:** Are competitors only on TikTok? Instagram opportunity?
+- **Audience gaps:** Is there an underserved segment?
+- **Quality gaps:** Are competitor images/videos low effort? Can we do better?
+
+### 5. Save Findings
+
+Store in `tiktok-marketing/competitor-research.json`:
+
+```json
+{
+  "researchDate": "2026-02-16",
+  "competitors": [
+    {
+      "name": "CompetitorApp",
+      "tiktokHandle": "@competitor",
+      "followers": 50000,
+      "topHooks": ["hook text 1", "hook text 2"],
+      "avgViews": 15000,
+      "bestVideo": {
+        "views": 500000,
+        "hook": "The hook that went viral",
+        "format": "before-after slideshow",
+        "url": "https://tiktok.com/..."
+      },
+      "format": "before-after slideshows",
+      "postingFrequency": "daily",
+      "cta": "link in bio",
+      "strengths": "Great visuals, consistent posting",
+      "weaknesses": "Same hooks every time, no storytelling"
+    }
+  ],
+  "nicheInsights": {
+    "trendingSounds": ["sound name 1"],
+    "commonFormats": ["before-after", "POV"],
+    "averageViews": 15000,
+    "topPerformingViews": 500000,
+    "gapOpportunities": "Nobody is doing person+conflict hooks in this niche",
+    "avoidPatterns": "Price comparison posts get <1K views consistently"
+  }
+}
+```
+
+### 6. Share Findings Conversationally
+
+Don't dump the JSON. Talk about it:
+
+> "So I looked at what's out there in [niche]. The main players are [A], [B], and [C]. [A] is doing well with [format] — their best post got [X] views. But I noticed nobody's really doing [gap]. That's where I think we can win. Here's my plan..."
+
+## Ongoing Research
+
+Don't just research once. During weekly reviews:
+
+- Check if competitors have posted new viral content
+- Look for new entrants in the niche
+- Monitor trending sounds and formats
+- Update `competitor-research.json` with new findings
+
+Reference competitor data when suggesting hooks — "Competitor X got 200K views with a landlord hook, let's try our version."
--- a/references/revenuecat-integration.md
+++ b/references/revenuecat-integration.md
@@ -0,0 +1,123 @@
+# RevenueCat Integration
+
+## Setup
+
+Add RevenueCat config to `config.json`:
+
+```json
+{
+  "revenuecat": {
+    "v1SecretKey": "sk_...",
+    "projectId": "your-project-id"
+  }
+}
+```
+
+Get the **V1 Secret API Key** from RevenueCat Dashboard → Project Settings → API Keys. Use the **secret** key (sk_), NOT the public key.
+
+## API Endpoints
+
+### Get Overview Metrics
+RevenueCat doesn't expose dashboard overview via API. Use the V1 subscriber endpoint to track individual conversions, or scrape the dashboard via browser automation.
+
+**Alternative: Webhooks.** Set up RevenueCat webhooks to log events (trial_started, initial_purchase, renewal, cancellation) to a local JSON file that the skill can read.
+
+### Get Subscriber Info (V1)
+```
+GET https://api.revenuecat.com/v1/subscribers/{app_user_id}
+Authorization: Bearer {v1SecretKey}
+```
+
+Returns: active subscriptions, entitlements, purchase history, management URL.
+
+### List Subscribers (V2 — if available)
+```
+GET https://api.revenuecat.com/v2/projects/{projectId}/customers
+Authorization: Bearer {v2SecretKey}
+```
+
+## Daily Report Script
+
+`scripts/daily-report.js` runs daily to:
+
+1. **Pull TikTok analytics** from Postiz (last 3 days of posts)
+2. **Pull conversion data** from RevenueCat webhook logs OR manual input
+3. **Cross-reference** post timing with conversion spikes
+4. **Generate report** identifying which hooks drove actual revenue
+
+### Cross-Reference Logic
+
+```
+For each day in last 3 days:
+  1. Get all TikTok posts and their view counts
+  2. Get all new trials + paid conversions from RevenueCat
+  3. Correlate: conversion spikes within 24h of high-view posts
+  4. Score each hook: (conversions in 24h window) / (views / 1000) = conversion rate per 1K views
+  5. Rank hooks by conversion rate, not just views
+```
+
+### Why 3 Days?
+- TikTok posts peak at 24-48h then tail off
+- Conversion attribution window is ~24-72h
+- Shorter = miss delayed conversions, longer = too noisy
+
+## Webhook Setup (Recommended)
+
+In RevenueCat Dashboard → Project Settings → Webhooks:
+
+1. Set webhook URL to your server OR log to file
+2. Events to track:
+   - `INITIAL_PURCHASE` — new paid subscriber
+   - `TRIAL_STARTED` — new trial
+   - `TRIAL_CONVERTED` — trial → paid
+   - `RENEWAL` — existing subscriber renewed
+   - `CANCELLATION` — subscriber cancelled
+   - `EXPIRATION` — subscription expired
+
+Store events in `tiktok-marketing/rc-events.json`:
+```json
+[
+  {
+    "event": "INITIAL_PURCHASE",
+    "timestamp": "2026-02-15T14:00:00Z",
+    "product": "fullAccessMonthly",
+    "revenue": 4.99,
+    "currency": "USD"
+  }
+]
+```
+
+If no webhook available, the user can manually update this file or the agent can prompt for daily numbers:
+- "How many new trials today?"
+- "How many paid conversions?"
+- "Current MRR?"
+
+## Report Output
+
+The daily report generates `tiktok-marketing/reports/YYYY-MM-DD.md`:
+
+```markdown
+# Daily Marketing Report — Feb 15, 2026
+
+## TikTok Performance (Last 3 Days)
+| Date | Hook | Views | Likes | Saves |
+|------|------|-------|-------|-------|
+| Feb 15 | boyfriend + catalogue | 12,400 | 340 | 67 |
+| Feb 14 | sister prison cell | 8,200 | 215 | 43 |
+| Feb 13 | nan hook | 3,100 | 89 | 12 |
+
+## Conversions (Last 3 Days)
+- New trials: 14
+- Trial → Paid: 6
+- New direct purchases: 2
+- Revenue: $47.92
+
+## Attribution
+- Feb 15 spike (8 trials) correlates with "boyfriend + catalogue" post (12.4K views)
+- Estimated conversion rate: 0.65 per 1K views (GOOD)
+
+## Recommendations
+- DOUBLE DOWN on relationship conflict hooks (boyfriend/sister/nan)
+- Drop listicle format (Feb 13 — low views, 0 correlating conversions)
+- Test: "My [person] didn't believe AI could redesign our [room]"
+```
--- a/references/slide-structure.md
+++ b/references/slide-structure.md
@@ -0,0 +1,111 @@
+# Slide Structure & Hook Writing
+
+## The 6-Slide Formula (EXACTLY 6 — TikTok minimum)
+
+| Slide | Purpose | Text Style |
+|-------|---------|------------|
+| 1 | HOOK — stop the scroll | Relatable problem, full hook text |
+| 2 | PROBLEM — amplify pain | Build tension |
+| 3 | DISCOVERY — turning point | "So I tried this" / "Then I found..." |
+| 4 | TRANSFORMATION 1 — first result | Reaction: "Wait... this actually looks good?" |
+| 5 | TRANSFORMATION 2 — escalate | Reaction: "Okay I'm obsessed" |
+| 6 | CTA — call to action | App name + "link in bio" |
+
+**SAME subject, SAME angle, DIFFERENT styles across all 6 slides.**
+
+## Proven Hook Formulas
+
+### Tier 1: Person + Conflict → AI → Changed Mind (BEST)
+- "I showed my mum what AI thinks our [room] should look like" (161K views)
+- "My landlord said I can't change anything so I showed her this" (124K views)
+- "My boyfriend said our flat looks like [insult] so I showed him"
+- "My flatmate wouldn't believe this is the same room"
+
+### Tier 2: Relatable Budget Pain
+- "POV: You have good taste but no budget"
+- "IKEA budget, designer taste"
+- "I can't afford an interior designer so I tried AI"
+
+### Tier 3: Curiosity / Self-Discovery
+- "I've always wondered what I'd look like with..."
+- "I had to see if it would even suit me"
+- "Everyone's getting [thing] but would it suit MY face?"
+
+### What DOESN'T Work
+- Self-focused complaints without conflict: "My flat is ugly" (low views)
+- Fear/insecurity hooks for beauty: "Am I ugly without..." (people scroll past)
+- Price comparison without story: "$500 vs $5000" (needs character)
+
+## Hook Adaptation by Category
+
+### Home/Interior Apps
+Replace [room] and [style] with user's app focus:
+- "My [person] said our [room] looks like [insult]"
+- "I showed my [person] what AI thinks our [room] should look like"
+- "[Person] wouldn't let me redecorate until I showed them this"
+
+### Beauty Apps
+- "My [person] got [treatment] and now I can't stop thinking about it"
+- "I've always had [feature] and never known what [change] would look like"
+- "Everyone keeps asking if I got [treatment] done"
+
+### Fitness Apps
+- "My trainer said I'd never look like [goal]"
+- "I showed my gym buddy what AI thinks I could look like in 6 months"
+
+### Productivity Apps
+- "My boss said my workflow is a mess so I showed her this"
+- "I was spending 4 hours on [task] until I found this"
+
+## Image Prompt Template
+
+Write ONE base description, reuse across all 6 slides:
+
+```
+[For AI image gen providers:]
+iPhone photo of a [CONTEXT]. [DETAILED DESCRIPTION OF SUBJECT].
+Shot from [CAMERA POSITION]. [SPECIFIC ARCHITECTURAL/PHYSICAL DETAILS].
+Natural phone camera quality, realistic lighting. Portrait orientation.
+
+[SLIDE-SPECIFIC STYLE CHANGES ONLY]
+```
+
+Adapt prompt style to your image gen provider — the key principles (same subject, same angle, different styles) apply regardless of which tool generates the images.
+
+### What to Lock (same across all 6):
+- Subject dimensions/features
+- Camera angle/position
+- Lighting direction
+- Background elements
+- Physical structure (windows, doors, body proportions)
+
+### What Changes Per Slide (ONLY):
+- Style/aesthetic
+- Colors/textures
+- Decor/accessories
+- Expression (for faces)
+
+## Caption Template
+
+```
+[hook matching slide 1] 😭 [2-3 sentences of relatable struggle].
+So I found this app called [APP NAME] that [what it does in one sentence] -
+you just [simple action] and it [result]. I tried [style 1] and [style 2]
+and honestly?? [emotional reaction]. [funny/relatable closer] 
+#[niche1] #[niche2] #[niche3] #[niche4] #fyp
+```
+
+Keep it conversational. Tell a mini-story. Mention the app naturally, not salesy.
+
+## Music (CRITICAL — Do NOT Skip)
+
+Posts are published as **drafts (SELF_ONLY)** to TikTok inbox. Before publishing:
+
+1. Open the draft in TikTok
+2. Tap "Add sound" and browse trending sounds in your niche
+3. Pick something popular — trending audio gets algorithmic boost
+4. Preview the slideshow with the sound, then publish
+
+**Why drafts?** TikTok's algorithm massively favours posts with trending sounds. Silent slideshows look like ads and get buried. Adding the right music is the difference between 1K and 100K views. An API can't pick what's trending right now — you need to browse the sound library.
+
+This takes 30 seconds per post. Don't skip it.