Expert overview
This manual assumes a reader who has run a blog at least once, has handled git and Python in a terminal, and has handed writing or code to Claude Code or Codex before. You don’t need the Blogger API or AdSense policy memorized. The automated publishing piece and the OAuth credential piece are unpacked in the sections that follow.
What this section covers is not a command reference but “why it’s shaped this way.” Pass through the reasoning once, then move to architecture, and verification and publishing will read as something more than a list of commands.
The problem in one line
Section titled “The problem in one line”Hand a blog post to AI and the first two or three paragraphs come out fine. After that the prose breaks down. Em-dashes land three to a paragraph, “not just X but Y” repeats, intros open with the conclusion, and generic adjectives fill the density. On top of that, low-value signals that trip AdSense creep in, the Korean and English versions drift apart, and posts that rank in search but never get cited by Claude or ChatGPT pile up. blog-studio is a starting point with a gate or a track planted at each of those spots.
Two gates before publishing
Section titled “Two gates before publishing”The AI-smell gate
Section titled “The AI-smell gate”ai-pattern-check scores AI-flavored prose from 0 to 100. The higher the score, the heavier the AI flavor.
| Verdict | Score | Action |
|---|---|---|
| Pass | Under 30 | Proceed to Phase 5 publishing |
| Warn | 30 to 60 | Fix the obvious spots first; proceed only if full automation was requested, and record the reason in the report |
| Fail | Over 60 | Block publishing. Hand back to Phase 2 for a rewrite, up to twice. If it still fails, hand back to the user |
scripts/deploy_to_blogger.py refuses to upload a failing post. The gate is enforced at the code level, so calling the script directly to bypass the orchestrator still gets blocked. --skip-gate is an emergency exit kept only for republishing or urgent cases.
The AdSense gate
Section titled “The AdSense gate”A post that might trip ad policy has to clear review before it publishes. Low-value content gets flagged automatically, and a post AdSense has already flagged drops into a “revert to draft” workflow. That tracking stays local and is not committed to git.
Two tracks: writing and marketing
Section titled “Two tracks: writing and marketing”The entry point forks in two.
blog-orchestrator writes the post. It carries you from Phase 0 (orientation) through Strategy, Production, Quality, the AI Pattern Gate, and Publish. The trigger is natural language. Utterances like “write a post about X,” “just review it,” and “publish it” decide the Phase range required.
marketing-director handles distribution after publishing. It spreads the post across X threads, Reddit, and Hacker News, and uses AI-SEO to raise the odds of an LLM citation. It’s a separate entry point from the writing track, so you can run only the distribution of an already-published post without writing anything.
The two tracks come back together over agent teams and the Phase flow in architecture.
One post, two languages
Section titled “One post, two languages”Korean is the source. blog-localization produces the English translation, and the two pile up as a mirror under _workspace/posts/{ko,en}/. The hreflang tags are planted automatically through the frontmatter’s hreflang_en and hreflang_ko, binding the two together. One post holds two language URLs, and the frontmatter contract keeps the two bodies from drifting apart.
The automation entry point points at one place
Section titled “The automation entry point points at one place”The Claude Code entry point is .claude/agents/ and .claude/skills/. The Codex entry point is the repository root AGENTS.md. Both end up reading one file.
AI_AUTOMATION.md. The runtime mapping, the Module Source Map, the directory contract, the supported user intents, the Phase 0–5 flow, and the security baseline S1–S8 all live there. Because both automation tools share one canonical document, a decision made in a Claude Code session carries over into a Codex session. The AI-smell gate’s score thresholds are the same in blog-orchestrator and this document, and aren’t redefined on either side.
What’s missing right now
Section titled “What’s missing right now”This base honestly has unfinished parts. The manual and landing are public, but the template itself is a commercial license model, and the payment flow and buyer verification aren’t wired up yet. COMMERCIAL-LICENSE.md is still a draft and hasn’t passed lawyer review. Both need to be finished before real sales.
There are empty spots on the content side too. Right after a fork, _workspace/ is just a skeleton, and the blog identity (.claude/product-marketing-context.md) is a placeholder. What this manual teaches is the procedure by which that empty skeleton fills in through /start and the Phase flow, not a sample of posts shipped inside blog-studio.
What this manual does not assume
Section titled “What this manual does not assume”OS-by-OS install branches, picking a Python version manager, screenshots of issuing OAuth credentials in the Google Cloud console, step-by-step guidance for someone new to the terminal — none of that is here. If you need it, see the beginner manual. It’s the same base told at a different pace.
The next section is architecture. It covers how the six agents mesh across Phase 0–5, where the writing and marketing tracks fork, and how the contract that isolates every output inside one _workspace/ folder is shaped, with two diagrams.