Improvement Guides
Lifecycle of an improvement guide, Plan.md execution, write targets (live/shadow/local), and revert.
What Improvement Guides Are
Improvement guides are AEKO's "units of execution" — cards generated automatically from your tracking and diagnostic data. Each card holds what to fix, why it matters, and how to apply it. Every card carries a Plan.md rendered deterministically from a template at card-create time — copy it to your clipboard and Claude can execute it as-is. The card creation itself makes no LLM call; the actual content writing happens when Claude (Sonnet) runs the Plan.
Why this shape
Most SEO tools hand you a list of "things to improve." AEKO goes one step further: every guide is already turned into an execution plan that Claude, Cursor, or Codex can run end-to-end. You stay in the loop as the reviewer, not the operator.
Three Tracks
Improvement guides are routed automatically into the three pages of the Improve section.
1. Technical Checkup — site scope
/dashboard/improve/technical
Site-level items — llms.txt, robots.txt, sitemap, homepage JSON-LD. One application affects every page. Artifact types: llms_txt, robots_txt_patch, technical_bundle.
2. PDP Fixes — product page scope
/dashboard/improve/pdp
Rewrites for a specific product's description, meta, and JSON-LD, plus content variation guides that repurpose the same product for your own blog or external media. Artifact types: pdp_html, json_ld, own_store_markdown, external_media_markdown.
3. Brand Settings — context input
/dashboard/improve/brand
The input for the other two tracks. Without a filled-in Brand Kit and ICPs, PDP and technical guides produce generic output. This page doesn't generate guide cards — it provides the context other cards consume. See the Brand Kit & Personas guide.
Guide Lifecycle
New cards start in ready immediately — Plan.md renders synchronously at create time. From there, status changes when you mark it done or dismiss it. Each appears on the card as a status badge.
| Status | Meaning |
|---|---|
| ready | Default state for a new card — Plan.md is already rendered. "Copy" and "Run in Claude" buttons are enabled immediately. |
| completed | You marked it done — output saved, audit log entry written |
| failed | Render or downstream tool error — check last_error, regenerate |
| dismissed | You chose not to run it — hidden from lists, kept in audit log |
The DB enum retains pending and generating_prose, but these are legacy values from the pre-Phase-3 async Sonnet pipeline and aren't written by any current route.
Priority badge
Separate from status, each card carries a critical / high / medium / low priority. Critical signals regressions or security impact; low is a micro-optimization.
Plan.md and Copy-for-AI
Plan.md is more than instructions — it's a command that Claude, Codex, or Cursor can run as-is. The header carries metadata (target URL, brand kit ID, artifact type, etc.); the body is a fixed step-by-step template interpolated with the card's context (product, persona, forbidden list, etc.).
Two ways to execute
- Copy: command goes to your clipboard → paste with Cmd/Ctrl+V into an open Claude Desktop or Code window
- Run in Claude (web): opens a new claude.ai chat with the command pre-filled — just press Enter and aeko-mcp runs the Plan
What aeko-mcp does automatically
The MCP tool aeko_get_action_plan fetches Plan.md, loads brand kit + personas + existing PDP as context, and produces the final artifact. When the run finishes it calls aeko_complete_action_item so the card flips to completed automatically. (MCP tool names stay as-is for API compatibility.)
Write Target — Live / Shadow / Local
When you create a PDP guide you choose where the output goes. The choice is recorded as the card's write_target.
| Write Target | Behavior |
|---|---|
| live | Pushes directly to your Shopify or Cafe24 store — audit-logged and revertable |
| shadow | Saves the output in AEKO only — preview, then promote manually |
| local | Output goes to the clipboard or a local file — Claude runs the Plan and hands you the result |
Start with shadow
live changes your live site immediately. Run the first one or two cards as shadow to review output. Once tone and structure feel right, switch to live. Every live write is audit-logged and revertable.
Tier Gating
Every improvement-guide artifact works on every paid plan. The backend's ARTIFACT_TIER_REQUIRED map is the single source of truth, and every entry is gated to starter or higher.
| Feature | Min tier |
|---|---|
PDP HTML rewrite (pdp_html) | Starter |
Product JSON-LD (json_ld) | Starter |
| Technical guides (llms.txt, robots.txt, technical_bundle) | Starter |
Live store writes (write_target=live) | Starter |
Content variation — own blog (own_store_markdown) | Starter |
Content variation — external media (external_media_markdown) | Starter |
Where plans differ is in tracked prompts, domains, and market limits — see the Subscription Plans guide for those.
Reverting a Store Write
Every live write is recorded in Settings → Store Integrations → Store Write Audit. Expand any row to compare before/after values, and use the "Revert" button to restore the prior state in one click.
What the audit log keeps
- Actor (user or MCP) + timestamp
- Platform (Shopify, Cafe24) + external product ID
- Operation (description, json_ld, tags, meta, etc.)
- Full before/after JSONB snapshots
- Status (success/failure) + revert reference ID
Caveat
Revert restores only the fields AEKO wrote. Any direct edits you made in the store between the write and the revert are not preserved, so spot-check the live page before reverting.
End-to-End Example
Running one PDP card all the way through
- 1. Open
/dashboard/improve/pdp, search the catalog, pick a low-citability product - 2. Click "Create improvement guide" → set write_target=
shadow - 3. Card lands in
readyimmediately - 4. Click "Copy" → paste into Claude Desktop with Cmd+V → Enter
- 5. aeko-mcp runs the Plan and saves the rewritten HTML + JSON-LD into the card result view
- 6. If the output looks right, re-create the same card with write_target=
live, or click "Apply live" in the result view - 7. A few days later, check Measure → Readiness for
content_change_detectedfollowed bycitability_improved
Can I use this without MCP?
Yes. The card's result view shows the generated HTML and JSON-LD, which you can copy and paste into your site manually. MCP is an automation option, not a requirement. For MCP install, see the Agents Setup guide.