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 work is available through these three workflows.
1. Technical and product checks
/dashboard/improve/technical
Review site structure and AEO signals for active product pages. Each product's "Improve with AI" button opens a Claude task scoped to that product.
2. Content optimization
/dashboard/improve/content
Check whether cited pages contain your brand name, then review ideas based on confirmed channel gaps. You can also prepare your own content idea and hand it off to AI from this page.
3. Context — customer situation input
/dashboard/analyze/context
Save customer situations from reviews or manual notes. Saved contexts tell AEKO which shopper the AI is answering for in prompt tracking and content-generation flows. See the Contexts 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 |
Older records may still show pending, generating_prose, or in_progress. The UI displays those values for compatibility but offers ready and completed as choices (the API also accepts in_progress).
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, artifact type, etc.); the body is a fixed step-by-step template interpolated with the card's context (product, saved context, 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 saved context and the existing PDP as input, 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.)
Product-page delivery — preview first
Every product-page improvement starts with a local preview. Plan.md's write_target is internal routing metadata, not permission to change a store. After reviewing the preview, choose one of the options the connected store actually supports.
| Choice | Behavior |
|---|---|
| Keep the preview only | Keeps the local result without changing the store. |
| Save as a private draft product | Appears only when the connected store exposes a real draft-creation capability. A normal product update is never relabeled as a draft. |
| Apply to the current product page | Requires a second explicit confirmation after you review the exact before/after, risks, and undo path. |
The preview is not optional
Choosing the current page does not write immediately. The AI first shows the exact change, risk, and undo plan, then asks for a separate confirmation. A cancellation or unclear reply keeps the preview only.
Tier Gating
Minimum plans differ by artifact. The backend's ARTIFACT_TIER_REQUIRED map is the source of truth; AI product-page improvement and content creation require Pro or higher.
| Feature | Min tier |
|---|---|
PDP HTML rewrite (pdp_html) | Pro |
Product JSON-LD (json_ld) | Starter |
| Technical guides (llms.txt, robots.txt, technical_bundle) | Starter |
| Apply to current product page (PDP improvement) | Pro |
Content variation — own blog (own_store_markdown) | Pro |
Content variation — external media (external_media_markdown) | Pro |
JSON-LD and technical guides remain available on Starter. See Subscription Plans for the complete limits.
Reverting a Store Write
Every current-page write is recorded in the store-write audit log. Reviewing history and reverting happens through the AEKO Agents (MCP) connection — in Claude, list past writes with aeko_list_store_writes and restore a prior state with aeko_revert_store_write.
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 improvement
- 1. Open
/dashboard/improve/technicaland choose a product to improve - 2. Click "Improve with AI" on the product row to open the Claude task
- 3. The plugin reuses the product's existing work item or creates one if needed
- 4. Review the product copy and JSON-LD that Claude prepares before applying it
- 5. After applying the change, check Technical and Measure for updated signals
To use Improve with AI
Connect the AEKO plugin and MCP first. Product-level structural checks remain available before setup. See Agents Setup for installation.