Improvement Guides
Lifecycle of an improvement guide, Plan.md execution, write targets (live/shadow/local), and revert.
What Improvement Guides Are
Improvement guides are task cards built from AEKO's tracking and diagnostic data. Each one explains what to improve, why it matters, and which evidence needs review. Select View AI brief to see a natural-language prompt built from the current evidence and constraints inside AEKO. Nothing is sent to an AI provider at this point.
Why this shape
Most SEO tools stop at a list of "things to improve." AEKO also prepares the evidence and working constraints. Review the brief first, then copy it or open it in Claude or Codex.
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 "View AI brief" button first shows a brief grounded in the current product record and failed checks.
2. Content optimization
/dashboard/improve/content
Check whether cited pages contain your brand name, then review ideas based on confirmed channel gaps. Cited evidence, your own ideas, and saved history all use the same brief-first flow.
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. From there, status changes when you mark one done or dismiss it. Each state appears on the card as a badge.
| Status | Meaning |
|---|---|
| ready | Default state for a new card — you can open an AI brief and review its evidence and constraints. |
| 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.
AI briefs and advanced workflows
The dashboard AI brief combines the selected item's evidence, constraints, requested output, and verification steps in one natural-language prompt. Product details and cited sources are included only after authorization checks; sensitive values and internal execution instructions are excluded. MCP and plugin workflows that use Plan.md remain available as a separate advanced feature.
How to use a brief
- 1. Review first: the first click only opens the brief inside AEKO. Check its evidence and any missing information.
- 2. Choose an AI: copy the exact brief or open it in Claude or Codex.
- 3. Confirm before sending: provider actions prefill the brief but do not send it. Review it once more in the AI app.
The brief is a preparation step
Opening a brief does not change your store or an external page, and it does not mark the card completed. Review any AI-generated draft yourself before using or publishing it.
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.