Blog Integration & Adoption — Friction-Reduction Vision

Last Updated: 2026-05-01 Status: Planning reference (idea catalog) Service: spans @vlozi/blog, dashboard, brain-service, newsletter-service, blog-service Related: layouts-vision.md, hosted-blog-vision.md, blog-engine-vision.md, sdk-backlog.md (current bug/improvement queue)

The premise: layouts collapse "what should the blog look like?" Hosted blog collapses "I don't have a website." This doc catalogs everything else that still hurts on the path from "I want a blog" → "shipped, polished, in production." Each item is a candidate for the roadmap; some are small and immediate, some are bigger projects that earn their own vision docs when prioritized.

TL;DR

Layouts MVP gets a customer from "what should it look like?" to "picked." Still missing: most of the mechanical setup (CLI, framework support, code generation, content migration) and most of the first-post activation (templates, AI assist, brand-color extraction).

Top 7 ideas, in priority order:

1. npx @vlozi/blog setup interactive CLI — biggest single lever for technical customers
2. Dashboard "Connect your site" wizard with live status panel — for everyone else
3. "Open PR on GitHub" one-click integration — zero copy-paste
4. Framework adapters beyond Next.js (Astro, Remix, Vite, TanStack Start)
5. One-click import from Substack / Medium / WordPress / Ghost / Notion
6. "Brand color from logo" auto-detection in onboarding
7. "First post" starter template + AI-assisted draft

Two of these (CLI and importers) deserve their own vision docs when they get prioritized. The other five are small enough to be sized as direct implementation work.

1. The friction map

The customer's journey from discovering vlozi to having a polished, live blog:

discover → sign up → get API key → install SDK → read integration prompt
   → create routes → set env vars → patch next.config.js → match brand
   → write first post → publish → share

Where customers stall today:

Layouts MVP fixes one row. The other six rows are this doc.

2. The seven high-leverage ideas

🥇 Idea #1 — npx @vlozi/blog setup CLI

The single biggest lever for technical customers. Today the integration prompt shows ~5 files of code to paste; the CLI does it in 30 seconds.

npx @vlozi/blog@latest setup

The CLI's job:

1. Detect framework by reading package.json (Next.js App / Pages, Astro, Remix, Vite + react-router, TanStack Start)
2. Prompt: tenant slug, layout pick (with ASCII previews + screenshot URL), API key
3. Create the route file(s) at the framework-correct path
4. Patch next.config.js (or equivalent) with the tenant's media remotePatterns
5. Add the SDK CSS import to the right entry file (app/layout.tsx for App Router, _app.tsx for Pages, etc.)
6. Write .env.local with the env vars; add .env.example for the team
7. Print the test URL and a link to publish the first post in the dashboard

Why it's #1: same pattern as npx shadcn add, npx create-t3-app, npx supabase init. Every SDK that did this saw integration friction drop ~80%. It's table stakes for 2026 SDK launches.

Effort: ~1 week. ~5 files of CLI code (commander.js + simple file ops + a few prompts). Ships as packages/blog-cli with a bin field exposed via @vlozi/blog.

Design notes:

• The CLI calls a dashboard-side endpoint to fetch the customer's tenant config (layout pick, tokens, media domain). One source of truth.
• For frameworks the CLI doesn't yet support, fall back to "here's the code, paste it" mode.
• Include a --dry-run flag — show what files would change without writing anything.
• Idempotent — re-running the CLI should detect existing setup and offer "update" vs "skip."

Deserves its own vision doc when prioritized. Sketch it out before implementation — there are decisions about CLI UX, framework detection heuristics, and what the dashboard endpoint looks like that benefit from being thought through.

🥈 Idea #2 — Dashboard "Connect your site" wizard

The CLI is for technical users. The wizard is for everyone else (founders who hire devs but want to run the integration themselves, marketing people, agencies handing off to a junior dev).

A new page at Settings → Blog → Connect site:

1. "What's your stack?" — picker (Next.js / Astro / Remix / Vite / "I'll paste it manually" / "I don't have a site yet — use hosted")
2. Customized code snippet — auto-generated for that stack with the tenant's API key, layout, tokens already filled in
3. Three install options:
   • Copy code (manual paste)
   • Run this CLI (copy a one-line npx command — leverages idea #1)
   • Open PR on GitHub (idea #3 ↓)
4. Live status panel — pings the customer's /blog URL on a timer; shows green when posts are flowing
5. "Test publish" — publishes a Hello World demo post and refreshes the status panel

Why the status panel matters more than people realize: today, customers integrate the SDK, hit publish in the dashboard, and don't know if it worked until they manually navigate to their /blog URL. The dashboard knowing the customer's site exists and showing 🟢 Connected — 1 post live closes the activation loop in real time.

Effort: ~3-4 days for the wizard UI + status-check endpoint. Status check is just a fetch(customerSite + '/blog') from a server-side worker that looks for the SDK's marker.

Design notes:

• Status panel needs a "verify manually" button — the customer might not have deployed yet
• Snippet generation should ship the layout's screenshot inline so the customer sees what they're getting
• Track in telemetry: how many customers reach "🟢 Connected" within 24h of signup

🥉 Idea #3 — "Open PR on GitHub" one-click integration

Built on top of #2. Customer's GitHub repo connects via OAuth (one-time). Wizard generates the integration code; dashboard opens a real PR on their repo:

Title: "Add Vlozi Blog"
 
Files changed:
  app/blog/[[...slug]]/page.tsx     (new)
  app/layout.tsx                     (modified — add SDK CSS import)
  next.config.js                     (modified — add image remotePatterns)
  .env.example                       (modified — add VLOZI_API_KEY)

Customer reviews the PR like any vendor integration, merges, deploys.

Zero copy-paste. This is what:

• Vercel does for project setup
• Sentry does for error tracking
• PostHog does for analytics
• Stripe does for Stripe Connect
• Linear does for GitHub-issue sync

The pattern is proven. Customers love it because they get a code review of the vendor integration before it lands in their codebase.

Effort: ~1 week. Needs a GitHub App (one-time setup) + PR template generation per framework. The hardest part is the OAuth flow + repo permission scoping. The rest is glue code.

Design notes:

• Customer can disconnect the GitHub App at any time (revoke token)
• Only request minimum scopes: read repo metadata + create PRs
• Show a preview of the PR diff inside the dashboard before opening it
• Auto-commit message includes the layout + token config so the PR explains itself

Idea #4 — Framework adapters beyond Next.js

The SDK currently ships only @vlozi/blog/next (helpers for generateMetadata, generateStaticParams). Most other React-using frameworks need their own thin adapter:

Each adapter unlocks an entire framework ecosystem. Most are 1-2 day projects because the heavy lifting (the components, hooks, styles) is done — the adapter is just data-fetching glue.

Why this is huge: Astro alone is probably 20-30% of the missed indie-blog market today. Right now those customers see "no Astro support" and bounce.

Effort: ~1 week total to ship the four most-asked-for. Could ship one at a time as customer demand surfaces them.

Design notes:

• Each adapter is a separate exports entry — @vlozi/blog/astro, @vlozi/blog/remix, etc.
• Astro adapter is the most complex because of the content-collection conventions; possibly worth its own ADR.
• Remix is being absorbed into React Router 7 — adapter should target both names if possible.

Idea #5 — One-click import from existing platforms

Switching costs are the #1 reason customers don't move blogs. Vlozi can offer:

Settings → Blog → Import → Pick source:
 
  📨  Substack export (.zip)
  📰  Medium export (.zip)
  🐢  Ghost JSON export
  🔷  WordPress XML
  📡  RSS feed URL
  📂  Markdown folder upload
  🗒  Notion page (via OAuth)
  ⚡  dev.to API

Each importer:

1. Parses the source format
2. Normalizes to vlozi's post schema
3. Uploads images to vlozi's media-service (rewriting URLs)
4. Bulk-creates posts as drafts (customer reviews + bulk-publishes)

This is THE unlock for moving customers off competitors. Ghost itself shipped its WordPress importer as the #1 priority because it was the deciding factor in switching. The same pattern applies for vlozi.

Effort: 2 weeks for the top 4 importers (Substack, Medium, WordPress, Markdown). Each is ~2 days + testing.

Design notes:

• Substack export ships .zip with HTML + metadata — well-documented format
• Medium export is HTML-heavy with proprietary tags; needs cleanup
• WordPress XML is messy but standardized (WXR)
• Markdown folder is the easiest — just frontmatter + body + images
• Notion via OAuth is the most magical (no export step) but needs Notion API integration
• Failed imports must show line-by-line error reports — not just "import failed"

Deserves its own vision doc when prioritized. There are real product decisions:

• Do we import as drafts or auto-publish?
• How do we handle category/tag taxonomy mismatches?
• What about images hosted on the source platform's CDN that go away?
• Do we run migration in a sandbox first and let customers preview?

These belong in a focused doc, not as an inline plan in this catalog.

Idea #6 — "Brand color from logo" auto-detection

Tiny but high-leverage. During signup:

1. Customer uploads a logo (already a step in onboarding)
2. Vlozi extracts the dominant non-white color via a colorthief-style algorithm
3. Pre-fills accent token with that color
4. Customer sees their blog instantly themed to their brand without ever touching a color picker

60-70% of customers will accept the auto-detected color. The other 30-40% override it. Either way, no friction at the most important decision point: "what color should my blog be?"

Effort: ~half a day. The color extraction is a known algorithm (~50 lines of TypeScript using Canvas API on the server). Already a solved problem; just integrate.

Design notes:

• Run extraction server-side (logo upload goes through media-service anyway — extract there)
• Show 3 candidate colors and let customer pick, default to the most-saturated one
• Show what the blog will look like with that accent in real time (use the layout preview)
• Never block: if extraction fails for any reason, fall back to layout default

Idea #7 — "First post" template + AI-assisted draft

The hardest part for many founders isn't the integration — it's writing the first post. They install the SDK, see an empty /blog page, freeze for 3 weeks before publishing anything.

After layout selection in the dashboard, offer:

• "Write your first post" → opens the editor with a starter template:
  • Title: "Welcome to my blog"
  • Body sections: "Why I'm writing", "What I'll cover", "How to follow"
  • All sections are placeholder text the customer overwrites
• "AI-assisted draft" → 3-question wizard:
  1. What's your blog about?
  2. Who's it for?
  3. What's your tone? (casual / technical / conversational / formal)
  4. → AI drafts a 300-400-word starter post

When the customer clicks Publish, the blog is no longer empty. Their /blog URL has content. They've crossed the activation threshold.

Why this matters more than it looks: a customer who publishes their first post within 5 minutes of signup is dramatically more likely to publish a second post in the next 7 days. The activation curve compounds. Empty-blog limbo is a churn machine.

Effort: ~3-4 days. AI assist plugs into existing brain-service infrastructure (Anthropic API + prompt templates). Editor template is a static JSON.

Design notes:

• Make the "skip — I'll write later" option visually weaker than the templates. Default action is to write, not to defer.
• AI draft is a starting point, not a finished post — frame it that way ("Here's a draft to edit. We never auto-publish anything.")
• Track activation: signup → first post published. Goal: <10 minutes.
• Prompt templates live in apps/brain-service and can be tuned without redeploying the dashboard.

3. Second-tier ideas (worth tracking, not urgent)

These are smaller wins that don't reduce integration friction much but compound after the customer is already onboarded. Worth keeping on the list.

4. Recommended phasing

A realistic sequence given a small team:

Phase A — alongside layouts MVP (~1 week)

Two ideas that are small enough to land at v1.0 without delaying anything, and that compound directly with the layout pick:

• Idea #6: "Brand color from logo" (~half day) — ships at v1.0 onboarding
• Idea #1: npx setup CLI (~1 week) — ships at v1.0; dramatically improves the "first 5 minutes" of integration

Phase B — right after layouts MVP (~2 weeks)

Activation-focused work:

• Idea #7: First-post AI assist (~3-4 days) — drives signup-to-published-post conversion
• Idea #4: Astro + Remix adapters (~4 days for both) — doubles the addressable framework reach

Phase C — ~3-4 weeks after launch (~2 weeks)

Higher-effort but high-impact items:

• Idea #2: Dashboard "Connect your site" wizard (~4 days) — for non-CLI users
• Idea #3: GitHub PR integration (~1 week) — zero-copy-paste integration

Phase D — ~6-8 weeks after launch (~2-3 weeks)

The migration story:

• Idea #5: Substack importer (~3 days) — highest-priority import path
• Idea #5: Medium + WordPress + Markdown importers (~1 week)
• Idea #5 + dedicated vision doc for the rest of the catalog

Phase E — opportunistic

Pull from the second-tier list as customer requests arrive. Don't pre-build features without signal.

5. What this means for layouts MVP

Two ideas should be promoted into the layouts MVP itself:

• #6 (brand color from logo) — half day of work, ships in onboarding alongside layout picker. No reason to defer.
• #1 (npx setup CLI) — 1 week of work, ships alongside the layouts SDK release. The CLI's "Pick a layout" prompt fits naturally with the layout-picker dashboard UI.

Both fit inside the existing 3.5-week MVP estimate without slipping it. They make the "first 5 minutes" experience the strongest part of the product instead of just the layout pick.

The other five ideas (#2 wizard, #3 GitHub PR, #4 framework adapters, #5 importers, #7 first-post AI) are post-MVP — each ships when prioritized.

6. The two ideas that need their own vision docs

Two of the seven are big enough to deserve their own focused vision doc when they get prioritized:

6.1 npx @vlozi/blog setup — CLI vision (to be written)

When prioritized, write docs/blog/cli-vision.md covering:

• CLI UX design (prompts, flags, dry-run, idempotency)
• Framework detection heuristics
• The dashboard endpoint for fetching tenant config
• File-modification strategy (AST-aware vs. string-based for next.config.js)
• Update / re-run flow
• Telemetry on CLI usage (success rate per framework, drop-off points)

6.2 Content import — vision (to be written)

When prioritized, write docs/blog/import-vision.md covering:

• Per-source format specs and edge cases
• Image rehosting strategy (media-service rewrites, broken-link handling)
• Category/tag taxonomy mapping (the source platform's tags don't 1:1 with vlozi's)
• Draft vs. auto-publish decision
• Sandbox preview before commit
• Error reporting UX
• Migration audit log (so customers can see what changed)
• Re-import / partial-import flows for ongoing migrations

Both docs are at the right scope to be written just before implementation, not now.

7. Open questions

8. What this isn't

This doc is not a roadmap. It's a catalog of friction-reduction ideas, sized and priority-ranked, that we can pull from when we need to plan a sprint or a quarter.

It's also not exhaustive. As we ship layouts MVP and learn from real customer behavior, new friction points will surface that aren't on this list. The goal of writing them down now is to (a) avoid losing good ideas, (b) make sure we're not double-building the same thing, and (c) sequence the work so each phase compounds with the next.

Pick from this list when planning. Add to it when customers tell us what hurts. Remove items when they become irrelevant.

9. Summary

Layouts MVP is the biggest single unlock for blog adoption. It removes the "what should it look like?" decision tax.

The seven ideas in this doc remove the other decision taxes:

• the mechanical setup tax (CLI, wizard, GitHub PR, framework adapters)
• the migration tax (importers)
• the brand-decision tax (color from logo)
• the blank-page tax (first-post template + AI)

Combined, they take blog adoption from "doable in an afternoon" to "doable in 5 minutes by anyone with a domain and a pulse." That's the bar.

Promote #1 (CLI) and #6 (brand-color) into layouts MVP. Sequence the rest after. Write deep-dive vision docs for #1 and #5 when their time comes.