outrank-cli 0.2.0 → 0.4.0

package/README.md

@@ -48,8 +48,13 @@ This repo currently targets the agent endpoints that already exist in `outrank`:
 - `products linking target-config get|update`
 - `products linking targets list|add-manual|upsert|clear-customizations|delete`
 - `products backlinks get|update|credits|earned|unverified|check-removal|reverify|subscription|subscribe-quote`
-- `keywords list|get|export|generation-status|add|suggest|generate|reschedule|bulk-reschedule|delete|bulk-delete`
+- `keywords list|get|export|generation-status|add|update|suggest|generate|bulk-reschedule|delete|bulk-delete`
 - `articles list|get|get-content|update|update-content|replace|bulk-replace|upload-image|upload-featured-image|retry-publish|delete|precreate|generate`
+- `improvements settings get|update`
+- `improvements analyze`
+- `improvements candidates list|brief|edit-brief|schedule`
+- `improvements tasks list|reschedule|cancel|edit-brief|execute`
+- `improvements executions list|get|decisions|push`
 - `subscription status`
 - `usage stats`
 - `billing portal-url`
@@ -97,6 +102,7 @@ outrank-cli auth status
 outrank-cli auth whoami
 outrank-cli products list --limit 20
 outrank-cli keywords list --product 00000000-0000-0000-0000-000000000000 --scope all
+outrank-cli keywords list --product 00000000-0000-0000-0000-000000000000 --scope scheduled --q "best seo tools"
 outrank-cli keywords generation-status --product 00000000-0000-0000-0000-000000000000
 outrank-cli articles list --product 00000000-0000-0000-0000-000000000000 --status published
 outrank-cli articles get 00000000-0000-0000-0000-000000000000
@@ -109,6 +115,11 @@ outrank-cli articles replace 00000000-0000-0000-0000-000000000000 --json '{"find
 outrank-cli articles retry-publish 00000000-0000-0000-0000-000000000000
 outrank-cli articles precreate 00000000-0000-0000-0000-000000000000
 outrank-cli articles generate 00000000-0000-0000-0000-000000000000
+outrank-cli improvements settings get 00000000-0000-0000-0000-000000000000
+outrank-cli improvements candidates list 00000000-0000-0000-0000-000000000000 --type ctr_gap --limit 20
+outrank-cli improvements candidates schedule 00000000-0000-0000-0000-000000000000 --scheduled-for 2026-06-01
+outrank-cli improvements tasks execute 00000000-0000-0000-0000-000000000000
+outrank-cli improvements executions push 00000000-0000-0000-0000-000000000000
 outrank-cli subscription status
 outrank-cli usage stats
 outrank-cli products get 00000000-0000-0000-0000-000000000000
@@ -152,9 +163,10 @@ outrank-cli products integrations test 00000000-0000-0000-0000-000000000000 1111
 outrank-cli keywords suggest --product 00000000-0000-0000-0000-000000000000 --theme "email marketing"
 outrank-cli keywords generate --product 00000000-0000-0000-0000-000000000000 --count 10 --source both
 outrank-cli keywords add --product 00000000-0000-0000-0000-000000000000 --json-file ./keywords.json
+outrank-cli keywords update 00000000-0000-0000-0000-000000000000 --json '{"instructions":"Write for beginners and include a step-by-step setup section"}'
 outrank-cli keywords export --product 00000000-0000-0000-0000-000000000000
 outrank-cli products create --json-file ./product.json
-# products create now auto-queues the initial ~30-day keyword plan; poll with keywords generation-status / keywords list
+# products create auto-queues the initial ~30-day keyword plan; poll with keywords generation-status / keywords list
 outrank-cli billing portal-url
 outrank-cli products update 00000000-0000-0000-0000-000000000000 --json '{"daily_article_count":2}'
 outrank-cli products output-settings update 00000000-0000-0000-0000-000000000000 --json-file ./output-settings.json
@@ -188,7 +200,7 @@ outrank-cli products backlinks check-removal 00000000-0000-0000-0000-00000000000
 outrank-cli products backlinks reverify 00000000-0000-0000-0000-000000000000 11111111-1111-1111-1111-111111111111
 outrank-cli products backlinks subscription 00000000-0000-0000-0000-000000000000
 outrank-cli products backlinks subscribe-quote 00000000-0000-0000-0000-000000000000 --plan premium
-outrank-cli keywords reschedule 00000000-0000-0000-0000-000000000000 --scheduled-for 2026-05-20
+outrank-cli keywords update 00000000-0000-0000-0000-000000000000 --json '{"scheduled_for":"2026-05-20"}'
 outrank-cli billing purchase-products quote --additional-products 2
 ```
 
@@ -272,13 +284,22 @@ Example payload:
 ## Keyword mutation rules
 
 - Run `outrank-cli keywords generation-status --product <product-id>` before keyword writes when you are not sure the product is writable.
-- `keywords generate` now mirrors the dashboard Generate Keywords flow. Ask the human how many keywords to generate before calling it if they did not specify a count.
+- `keywords generate` mirrors the dashboard Generate Keywords flow. Ask the human how many keywords to generate before calling it if they did not specify a count.
 - The allowed generation count is 5-30, but the real upper bound depends on free scheduler slots. Check `keywords generation-status` first when you need the current capacity.
 - Stored keywords are read-only inventory. They can be promoted into the plan with `keywords add`, but they cannot be deleted directly.
 - Scheduled keywords with created or pre-created articles are read-only.
 - Keywords in `generating_article` are read-only until generation finishes.
 - Past keywords are read-only except past `scheduled` or `disabled` keywords without an article, which can still be rescheduled.
 - If the main subscription is `past_due`, keyword mutations are blocked and reads still work.
+- `keywords list` defaults to planner-first ordering for scheduled results, so page 1 prioritizes upcoming scheduled items before past ones.
+- Use `keywords list --product <product-id> --scope scheduled --q "<keyword>"` when looking for one planner keyword by text. If `next_offset` is not `null`, keep paging before claiming the keyword is absent.
+- Keyword records return top-level `article_type`, `article_subtype`, `expected_length`, and label fields. Read those from the keyword itself when answering article-type or expected-length questions; do not look in product output-settings for per-keyword length.
+- Use `keywords update <keyword-id> --json '{"instructions":"..."}'` to add or change per-keyword instructions after creation. This matches the dashboard flow, which creates the keyword first and updates the brief afterward.
+- Use `keywords update <keyword-id> --json '{"quality_questions":[{"id":"...","question":"...","answer":"..."}]}'` to answer or replace the keyword's quality questions through the same PATCH route.
+- Use `keywords update <keyword-id> --json '{"scheduled_for":"YYYY-MM-DD","instructions":"..."}'` when you need to change the date and brief in one PATCH request.
+- Use `keywords update <keyword-id> --json '{"scheduled_for":"YYYY-MM-DD"}'` for date-only rescheduling too; there is no separate reschedule command.
+- `keywords get <keyword-id>` returns `article_type_options`, which lists the valid dropdown values for `article_type`, `article_subtype`, and `expected_length`.
+- Use `keywords update --json '{"article_type":"guide","article_subtype":"explainer","expected_length":"long"}'` to mirror the scheduler card's "Article Type Settings" modal. The API rejects values outside the returned option lists.
 
 ## Article behavior notes
 
@@ -286,13 +307,29 @@ Example payload:
 - Featured image can be updated either by hosted URL through `articles update --json '{"image_url":"..."}'` or by local-file upload through `articles upload-featured-image`.
 - In-content images can be uploaded from a local file with `articles upload-image`; the command returns the hosted URL plus generated alt text so the agent can insert or replace the markdown image reference.
 - Per-article instructions are stored on the linked scheduled keyword, so `articles update --json '{"instructions":"..."}'` only works for articles that still have a linked planner keyword.
-- `articles update --json '{"status":"published"}'` now attempts a real publish through the product's active integration for eligible attached articles; it is not just a local status flip.
+- `articles get <article-id>` returns `article_type_options`, which lists the valid dropdown values for `article_type`, `article_subtype`, and `expected_length`.
+- Article records with a linked scheduled keyword also return top-level `article_type`, `article_subtype`, `expected_length`, and label fields for direct reads.
+- Use `articles update --json '{"article_type":"guide","article_subtype":"comparison","expected_length":"long"}'` to mirror the dashboard's "Article Type Settings" modal. The API rejects values outside the returned option lists.
+- `articles update --json '{"status":"published"}'` attempts a real publish through the product's active integration for eligible attached articles; it is not just a local status flip.
 - Slug is returned for read-only reference but cannot be changed through the agent API.
 - `articles generate <keyword-id>` is only valid for scheduled keywords due today; it mirrors the dashboard's create-and-publish action.
 - `articles precreate <keyword-id>` is only valid for eligible future scheduled keywords, is unavailable on trial subscriptions, and should be polled through the keyword state afterward.
 - `articles update --json '{"status":"published"}'` cannot be used to manually publish a future scheduled article before its due date.
 - `articles retry-publish <article-id>` is only valid for generated articles with a publish error.
 
+## Article improvements behavior notes
+
+- Article improvements are a separate surface from generation: they rewrite an already-published post based on Search Console signals, then push the result to the CMS. They require the All-in-One plan. On Basic plan, `improvements candidates list` returns an empty list and write actions return `PLAN_UPGRADE_REQUIRED`.
+- `improvements settings update --json '{"enabled":true}'` starts an unattended loop: weekly opportunity discovery, daily auto-scheduling on `publishing_days` (at most 2 weekday codes from Mon–Sun), and execution every ~15 minutes. Surface this to the human before enabling.
+- `improvements settings update --json '{"auto_push":true}'` publishes every successful rewrite to the CMS without human review (still skipped automatically on a hard validation failure or an unverified backlink injection).
+- `improvements settings get` returns `readiness`, which says whether the connected CMS can actually receive a pushed update (`ready`) or not (`not_connected`, `action_required`, `unsupported`). A push to an unsupported/disconnected CMS is reported as `skipped` with `requires_manual_publish`.
+- `improvements analyze`, `improvements candidates brief`, and `improvements tasks execute` run in Firebase and can take minutes. If the call times out at the network edge, the work still completes server-side — re-list candidates or poll the execution rather than retrying.
+- After `improvements candidates brief`, poll the candidate (via `improvements candidates list`) until its `brief_status` is `ready`. After `improvements tasks execute`, poll `improvements executions get <execution-id>` until `status` is `completed`, then read `review_status`.
+- A candidate (or its underlying article) can have only one active scheduled task at a time, and an article can have only one active (pending/running) execution. Conflicts return `409`.
+- `improvements executions get` returns `before`/`after`, paragraph-level `hunks` (each with an id), and `validation_issues`. Push with no JSON to accept all changes; send `{"decisions":{"<hunkId>":"rejected"},"edited_hunks":{"<hunkId>":"..."}}` to reject or edit specific hunks. `decisions` and `push` only work while `review_status` is `awaiting_review`.
+- A push updates the article inside Outrank first, then dispatches to the CMS. `CMS_PUSH_FAILED` means the content was saved in Outrank but the CMS rejected it; inspect `error.details.cms_response` and retry.
+- `improvements candidates list` and `improvements executions list` use offset pagination through `data.next_offset`.
+
 ## Linking behavior notes
 
 - Linking writes are blocked unless the product has an active backlink subscription.
@@ -337,7 +374,7 @@ Current scope note:
 
 - Webhook, Ghost, Shopify, Webflow, and Wix support direct validate/create/update/test. Framer supports validate, provider-specific discovery, create, and test for the newer Server API flow. WordPress Plugin supports prepare plus validate/create/update/test. Next.js Blog supports one-step create plus the shared list|get|delete surface, returning a one-time API key on create. WordPress.com supports OAuth connect plus poll, then the shared list|get|delete surface. Notion supports OAuth connect plus poll, provider-specific database/schema discovery, then update/test on the saved row.
 - V2 products are intended to keep one publishing integration. If `list` returns multiple rows, that usually means legacy V1 residue and stale rows should be reviewed and deleted.
-- Backlink exchange management now covers configuration, status reads, earned/unverified review queues, and reverification actions. Purchasing or changing backlink add-ons still requires the dashboard checkout flow.
+- Backlink exchange management covers configuration, status reads, earned/unverified review queues, and reverification actions. Purchasing or changing backlink add-ons still requires the dashboard checkout flow.
 - Other providers are still mostly read/delete only while create, update, test, and provider-specific discovery are added one by one.
 
 ## Custom API target (advanced)

package/SKILL.md

@@ -1,53 +1,60 @@
----
-name: outrank
-description: Drive the Outrank agent API from the terminal via outrank-cli. Use when the user asks to list/create/update Outrank products, inspect or manage publishing integrations, inspect or manage keyword plans, inspect or edit articles, manage article settings, target audiences, competitors, Google Search Console connections, internal linking configuration, or quote/buy product slots. Requires outrank-cli on PATH and an Outrank API key (env OUTRANK_API_KEY or stored via auth login).
----
-
-# Outrank Skill
-
-Use `outrank-cli` to drive Outrank from the terminal. The CLI is JSON-first and every command returns `agent_guidance`, so read that field after each step and let it steer the next call.
-
+---
+name: outrank
+description: Drive the Outrank agent API from the terminal via outrank-cli. Use when the user asks to list/create/update Outrank products, inspect or manage publishing integrations, inspect or manage keyword plans, inspect or edit articles, discover/schedule/run/review/publish article improvements for existing posts, manage article settings, target audiences, competitors, Google Search Console connections, internal linking configuration, or quote/buy product slots. Requires outrank-cli on PATH and an Outrank API key (env OUTRANK_API_KEY or stored via auth login).
+---
+
+# Outrank Skill
+
+Use `outrank-cli` to drive Outrank from the terminal. The CLI is JSON-first and every command returns `agent_guidance`, so read that field after each step and let it steer the next call.
+
 In human-facing responses, call `products get` / `products update` the product's General settings. These cover the non-editorial product basics such as name, URL, description, sitemap URL, blog root URL, publishing cadence, and similar core product fields.
 
 In human-facing responses, call product `output-settings` article settings or article preferences. Use `output-settings` only when you are quoting the literal CLI command or API path.
 Use `products backlinks ...` for backlink exchange settings, credits, review queues, and reverification actions.
-
-## Setup
-
+
+Use `improvements ...` for article improvements: discovering, briefing, scheduling, running, reviewing, and publishing AI rewrites of **existing published articles** based on Search Console performance. This is a distinct area from article generation (`articles generate`/`precreate`) — offer it whenever the human wants to refresh, update, optimize, or improve existing/older posts, or act on GSC opportunities. It needs the All-in-One plan.
+
+## Setup
+
 1. If `OUTRANK_API_KEY` is not set, ask the human for an Outrank API key from `https://outrank.so/dashboard/settings/api-keys`.
-2. Store it with `outrank-cli auth login <api-key>`.
-3. Verify access with `outrank-cli auth whoami`.
-4. If a command fails with auth errors, tell the human exactly how to refresh the key, then retry.
-5. If the environment blocks writes to the default home directory, set `OUTRANK_CONFIG_DIR` to a writable folder before using `auth login`.
+2. Store it with `outrank-cli auth login <api-key>`.
+3. Verify access with `outrank-cli auth whoami`.
+4. If a command fails with auth errors, tell the human exactly how to refresh the key, then retry.
+5. If the environment blocks writes to the default home directory, set `OUTRANK_CONFIG_DIR` to a writable folder before using `auth login`.
 6. If the API is hosted on a non-default Outrank deployment, set `OUTRANK_BASE_URL=<deployment-url>`. Use `--base-url <deployment-url>` only as a per-command override when needed.
-
-## Discovery
-
-Run `outrank-cli --help` first if you need the command tree.
-
-Run group help when needed:
-
-- `outrank-cli auth --help`
-- `outrank-cli products --help`
-- `outrank-cli keywords --help`
-- `outrank-cli articles --help`
-- `outrank-cli subscription --help`
-- `outrank-cli usage --help`
-- `outrank-cli billing --help`
-- `outrank-cli auth status`
-
-Prefer inspecting before mutating:
-
-- `outrank-cli products list --limit 20`
-- `outrank-cli products get <productId>` for General settings
-- `outrank-cli products output-settings get <productId>`
-- `outrank-cli keywords list --product <productId> --scope all`
-- `outrank-cli articles list --product <productId>`
-- `outrank-cli articles get <articleId>`
-- `outrank-cli articles get-content <articleId>`
-- `outrank-cli articles upload-image --file <path> --article <articleId>`
-- `outrank-cli articles upload-featured-image <articleId> --file <path>`
-- `outrank-cli keywords export --product <productId>`
+
+## Discovery
+
+Run `outrank-cli --help` first if you need the command tree.
+
+Run group help when needed:
+
+- `outrank-cli auth --help`
+- `outrank-cli products --help`
+- `outrank-cli keywords --help`
+- `outrank-cli articles --help`
+- `outrank-cli improvements --help`
+- `outrank-cli subscription --help`
+- `outrank-cli usage --help`
+- `outrank-cli billing --help`
+- `outrank-cli auth status`
+
+Prefer inspecting before mutating:
+
+- `outrank-cli products list --limit 20`
+- `outrank-cli products get <productId>` for General settings
+- `outrank-cli products output-settings get <productId>`
+- `outrank-cli keywords list --product <productId> --scope all`
+- `outrank-cli articles list --product <productId>`
+- `outrank-cli articles get <articleId>`
+- `outrank-cli articles get-content <articleId>`
+- `outrank-cli articles upload-image --file <path> --article <articleId>`
+- `outrank-cli articles upload-featured-image <articleId> --file <path>`
+- `outrank-cli improvements settings get <productId>`
+- `outrank-cli improvements candidates list <productId>`
+- `outrank-cli improvements tasks list <productId>`
+- `outrank-cli improvements executions list <productId>`
+- `outrank-cli keywords export --product <productId>`
 - `outrank-cli products target-audiences list <productId>`
 - `outrank-cli products competitors list <productId>`
 - `outrank-cli products integrations providers`
@@ -79,26 +86,26 @@ Prefer inspecting before mutating:
 - `outrank-cli products backlinks subscription <productId>`
 - `outrank-cli subscription status`
 - `outrank-cli usage stats`
-
-Interpret `auth whoami` carefully:
-
-- `organization.product_count` may represent purchased product slots, not the literal number of rows returned by `products list`.
-
-## Write pattern
-
-For complex writes, prefer JSON via file or stdin over long shell escaping.
-
-Accepted input forms:
-
-- `--json '{...}'`
-- `--json-file payload.json`
-- `--json-stdin`
-
-Write commands currently supported:
-
-- `outrank-cli products create --json-file product.json`
-  After create, the initial ~30-day keyword plan is queued automatically. Poll with `outrank-cli keywords generation-status --product <productId>` and then inspect `outrank-cli keywords list --product <productId>`. 
-- `outrank-cli products update <productId> --json-file patch.json` for General settings
+
+Interpret `auth whoami` carefully:
+
+- `organization.product_count` may represent purchased product slots, not the literal number of rows returned by `products list`.
+
+## Write pattern
+
+For complex writes, prefer JSON via file or stdin over long shell escaping.
+
+Accepted input forms:
+
+- `--json '{...}'`
+- `--json-file payload.json`
+- `--json-stdin`
+
+Write commands currently supported:
+
+- `outrank-cli products create --json-file product.json`
+  After create, the initial ~30-day keyword plan is queued automatically. Poll with `outrank-cli keywords generation-status --product <productId>` and then inspect `outrank-cli keywords list --product <productId>`. 
+- `outrank-cli products update <productId> --json-file patch.json` for General settings
 - `outrank-cli products output-settings update <productId> --json-file output-settings.json`
 - `outrank-cli products target-audiences replace <productId> --json-file target-audiences.json`
 - `outrank-cli products competitors replace <productId> --json-file competitors.json`
@@ -138,112 +145,113 @@ Write commands currently supported:
 - `outrank-cli products backlinks reverify <productId> <backlinkId>`
 - `outrank-cli products backlinks subscribe-quote <productId> --plan premium|enterprise`
 - `outrank-cli keywords add --product <productId> --json-file keywords.json`
+- `outrank-cli keywords update <keywordId> --json-file keyword-update.json`
 - `outrank-cli keywords bulk-reschedule --json-file keyword-reschedule.json`
 - `outrank-cli keywords bulk-delete --json-file keyword-delete.json`
-- `outrank-cli articles update <articleId> --json-file article-patch.json`
-- `outrank-cli articles update-content <articleId> --json-file article-content.json`
-- `outrank-cli articles replace <articleId> --json-file replace.json`
-- `outrank-cli articles bulk-replace --json-file bulk-replace.json`
-- `outrank-cli articles upload-image --file local-image.png --article <articleId>`
-- `outrank-cli articles upload-featured-image <articleId> --file hero.jpg`
-
-Billing-management helper:
-
-- `outrank-cli billing portal-url`
-
-## New-product preflight
-
-When the human asks to create or add a new product, do not jump straight to `products create` or a billing purchase.
-
-Treat product creation as blocked until you have either:
-
-1. Collected the key product and article-settings inputs, or
-2. Explicit human approval to keep the current defaults for anything they did not specify.
-
-Ask for missing information explicitly. Do not silently rely on defaults for editorial behavior.
-When the account already has products, inspect at least one existing product's article settings first so you can see the current backend's actual setting keys before you ask the human to configure a new one.
-
-Use this inspection pattern before asking article-setting questions:
-
-- `outrank-cli products list --limit 20`
-- `outrank-cli products output-settings get <existingProductId>`
-
-Use the returned `output-settings` object as the authoritative checklist of fields currently visible through the live API for that account. Do not rely on a hardcoded short list if the live object contains more agent-visible settings. Do not infer dashboard-only or internal generation fields that are intentionally hidden from the agent API, including `outline`, `outrank_prompt`, and `not_included_words`.
-
-When the response includes `data._meta`:
-
-- if `data._human` is present, use that as the default source for any human-facing summary
-- use `data._meta.sections` to decide which settings to show humans and how to group them
-- use `data._meta.fields.<field>.label` and `.description` instead of inventing meanings from snake_case names
-- use `data._meta.fields.<field>.options` for enum choices and `constraints` for numeric/color limits before proposing or writing a new value
-- treat `data._meta.hidden_from_human_summary_fields` as bookkeeping fields that usually should not be surfaced in prose
-- if a field is missing from `data._meta.fields`, do not guess what it means; say the live API did not define that field's semantics clearly
-- never mention database table names, raw API field names, raw enum keys, or internal ids in normal human-facing explanations unless the user explicitly asks for implementation details
-
-Minimum product brief to collect before creation:
-
-- product name
-- canonical website URL
-- product description
-- target audiences
-- competitor set
-- language
-- keyword region
-
-Article settings to confirm before creation or immediately before the first write:
-
-- tone and style
-- whether to auto-publish
-- whether to include a table of contents
-- whether to mention similar products
-- whether to include CTAs
-- whether to include YouTube videos, if that field exists in the inspected article settings
-- featured-image style, article-image style, or similar image fields, if those fields exist in the inspected article settings
-
-The list above is a minimum reminder, not the full agent-visible schema. If the inspected live output-settings object includes additional visible fields, ask about those too. Do not ask the human to configure hidden internal fields that are absent from the live object.
-
-For preset-backed fields, do not ask for free-form prose unless the backend clearly accepts arbitrary text. Many settings are select-style options. Examples may include tone, image style, or featured-image style.
-
-If the live API or current repo context does not expose the full allowed option list for a preset-backed field:
-
-- do not pretend the value is free-form
-- ask the human for the exact option label they want as it appears in Outrank
-- if helpful, show the current value from an existing product as a reference point
-- say clearly when the CLI exposes the field's current value but not the full enum catalog
-
+- `outrank-cli articles update <articleId> --json-file article-patch.json`
+- `outrank-cli articles update-content <articleId> --json-file article-content.json`
+- `outrank-cli articles replace <articleId> --json-file replace.json`
+- `outrank-cli articles bulk-replace --json-file bulk-replace.json`
+- `outrank-cli articles upload-image --file local-image.png --article <articleId>`
+- `outrank-cli articles upload-featured-image <articleId> --file hero.jpg`
+
+Billing-management helper:
+
+- `outrank-cli billing portal-url`
+
+## New-product preflight
+
+When the human asks to create or add a new product, do not jump straight to `products create` or a billing purchase.
+
+Treat product creation as blocked until you have either:
+
+1. Collected the key product and article-settings inputs, or
+2. Explicit human approval to keep the current defaults for anything they did not specify.
+
+Ask for missing information explicitly. Do not silently rely on defaults for editorial behavior.
+When the account already has products, inspect at least one existing product's article settings first so you can see the current backend's actual setting keys before you ask the human to configure a new one.
+
+Use this inspection pattern before asking article-setting questions:
+
+- `outrank-cli products list --limit 20`
+- `outrank-cli products output-settings get <existingProductId>`
+
+Use the returned `output-settings` object as the authoritative checklist of fields currently visible through the live API for that account. Do not rely on a hardcoded short list if the live object contains more agent-visible settings. Do not infer dashboard-only or internal generation fields that are intentionally hidden from the agent API, including `outline`, `outrank_prompt`, and `not_included_words`.
+
+When the response includes `data._meta`:
+
+- if `data._human` is present, use that as the default source for any human-facing summary
+- use `data._meta.sections` to decide which settings to show humans and how to group them
+- use `data._meta.fields.<field>.label` and `.description` instead of inventing meanings from snake_case names
+- use `data._meta.fields.<field>.options` for enum choices and `constraints` for numeric/color limits before proposing or writing a new value
+- treat `data._meta.hidden_from_human_summary_fields` as bookkeeping fields that usually should not be surfaced in prose
+- if a field is missing from `data._meta.fields`, do not guess what it means; say the live API did not define that field's semantics clearly
+- never mention database table names, raw API field names, raw enum keys, or internal ids in normal human-facing explanations unless the user explicitly asks for implementation details
+
+Minimum product brief to collect before creation:
+
+- product name
+- canonical website URL
+- product description
+- target audiences
+- competitor set
+- language
+- keyword region
+
+Article settings to confirm before creation or immediately before the first write:
+
+- tone and style
+- whether to auto-publish
+- whether to include a table of contents
+- whether to mention similar products
+- whether to include CTAs
+- whether to include YouTube videos, if that field exists in the inspected article settings
+- featured-image style, article-image style, or similar image fields, if those fields exist in the inspected article settings
+
+The list above is a minimum reminder, not the full agent-visible schema. If the inspected live output-settings object includes additional visible fields, ask about those too. Do not ask the human to configure hidden internal fields that are absent from the live object.
+
+For preset-backed fields, do not ask for free-form prose unless the backend clearly accepts arbitrary text. Many settings are select-style options. Examples may include tone, image style, or featured-image style.
+
+If the live API or current repo context does not expose the full allowed option list for a preset-backed field:
+
+- do not pretend the value is free-form
+- ask the human for the exact option label they want as it appears in Outrank
+- if helpful, show the current value from an existing product as a reference point
+- say clearly when the CLI exposes the field's current value but not the full enum catalog
+
 Business-critical settings that may matter before article generation:
-
-- blog URL or publishing destination
-- internal linking preferences
-- image style or image-generation preferences
-- article examples or brand-writing examples
-- publishing workflow preferences such as draft-first vs direct publish
-
-If the human has not provided those business-critical settings yet, say so clearly. Explain which of them are currently exposed by `outrank-cli` and which are not. Internal linking is now exposed through the `products linking ...` subtree. For settings that are not yet supported by the current CLI surface, do not invent commands. Instead, ask the human whether to:
-
-- proceed with existing/default Outrank settings for now, or
-- stop product creation until those settings are provided and/or configured elsewhere
-
-Before any billing or create step, present a short confirmation summary that includes:
-
-- what will be created
-- what competitors and audiences will be set
-- which article settings will be written
-- which fields were confirmed from the live output-settings schema versus inferred from docs/examples
-- which important settings are still defaulting because they were not provided or are not yet exposed in the CLI
-- whether a real billing charge approval is still required
-
-## Product workflow
-
+
+- blog URL or publishing destination
+- internal linking preferences
+- image style or image-generation preferences
+- article examples or brand-writing examples
+- publishing workflow preferences such as draft-first vs direct publish
+
+If the human has not provided those business-critical settings yet, say so clearly. Explain which of them are currently exposed by `outrank-cli` and which are not. Internal linking is exposed through the `products linking ...` subtree. For settings that are not yet supported by the current CLI surface, do not invent commands. Instead, ask the human whether to:
+
+- proceed with existing/default Outrank settings for now, or
+- stop product creation until those settings are provided and/or configured elsewhere
+
+Before any billing or create step, present a short confirmation summary that includes:
+
+- what will be created
+- what competitors and audiences will be set
+- which article settings will be written
+- which fields were confirmed from the live output-settings schema versus inferred from docs/examples
+- which important settings are still defaulting because they were not provided or are not yet exposed in the CLI
+- whether a real billing charge approval is still required
+
+## Product workflow
+
 For a new product:
-
-1. Gather the new-product preflight inputs above. If anything important is missing, ask the human before continuing.
-2. If another paid product slot is needed, quote the billing change before creating anything.
-3. After the human approves the plan, create it with `products create`.
-4. Read the returned `agent_guidance`.
-5. Tune article behavior with `products output-settings update`.
-6. Replace the target-audience set with `products target-audiences replace`.
-7. Replace the competitor set with `products competitors replace`.
+
+1. Gather the new-product preflight inputs above. If anything important is missing, ask the human before continuing.
+2. If another paid product slot is needed, quote the billing change before creating anything.
+3. After the human approves the plan, create it with `products create`.
+4. Read the returned `agent_guidance`.
+5. Tune article behavior with `products output-settings update`.
+6. Replace the target-audience set with `products target-audiences replace`.
+7. Replace the competitor set with `products competitors replace`.
 8. Re-read the product, article settings, target audiences, and competitors to confirm the final state.
 
 When you only need a small change, use `products update` rather than recreating the product.
@@ -371,22 +379,22 @@ Important behavior:
 - the current CLI surface still does not expose create, update, or test for some providers, and only WordPress.com and Notion currently expose an OAuth connect flow; if the human asks for unsupported operations, say they are not shipped in this CLI yet instead of inventing commands
 
 ## Keyword workflow
-
-Keyword plans now have two buckets:
-
-- scheduled keywords: already on the content calendar
-- stored keywords: unscheduled inventory waiting to be promoted into the plan
-
-Inspect before mutating:
-
-- `outrank-cli keywords list --product <productId> --scope scheduled`
-- `outrank-cli keywords list --product <productId> --scope stored`
-- `outrank-cli keywords list --product <productId> --scope all`
-- `outrank-cli keywords export --product <productId>`
-- `outrank-cli keywords generation-status --product <productId>`
-
-Use the returned `data.scope`, `data.scheduled`, and `data.stored` structure literally. Do not invent a different keyword model.
-
+
+Keyword plans have two buckets:
+
+- scheduled keywords: already on the content calendar
+- stored keywords: unscheduled inventory waiting to be promoted into the plan
+
+Inspect before mutating:
+
+- `outrank-cli keywords list --product <productId> --scope scheduled`
+- `outrank-cli keywords list --product <productId> --scope stored`
+- `outrank-cli keywords list --product <productId> --scope all`
+- `outrank-cli keywords export --product <productId>`
+- `outrank-cli keywords generation-status --product <productId>`
+
+Use the returned `data.scope`, `data.scheduled`, and `data.stored` structure literally. Do not invent a different keyword model.
+
 When the user asks for keyword ideas:
 
 - use `outrank-cli keywords suggest --product <productId> --theme "<theme>"` for related-keyword exploration around a theme or seed term
@@ -400,96 +408,135 @@ Before `keywords generate`:
 - if the human did not specify how many keywords to generate, ask them
 - the allowed range is 5-30, but the real maximum depends on free scheduler slots
 - check `outrank-cli keywords generation-status --product <productId>` when you need the current slot capacity
-
-To add keywords:
-
-- for direct adds, use `outrank-cli keywords add --product <productId> --json-file keywords.json`
-- for promoting existing stored keywords, include `stored_keyword_ids` in that JSON payload
-
-Important behavior to remember:
-
-- add is idempotent where possible; existing scheduled keywords come back as existing rather than being duplicated
-- stored keywords are unscheduled inventory, not disabled scheduled keywords
-- stored keywords are read-only inventory; they can be promoted into the plan but not deleted directly
-- auto-scheduling respects the backend's real planner logic, including publish days and pending downgrade limits
-- if keyword generation status says writes are blocked, treat both scheduled and stored keywords as read-only until the blocker clears
-- if the main subscription is `past_due`, keyword mutations are blocked and only reads are allowed
-- scheduled keywords with created or pre-created articles are read-only
-- keywords in `generating_article` are read-only until generation finishes
-- past keywords are read-only except past `scheduled` or `disabled` keywords without an article, which may still be rescheduled
-- if the response reports skipped keywords, explain the actual skip reason to the human instead of pretending the add fully succeeded
-
-For schedule changes:
-
-- check writability first when there is any doubt: `outrank-cli keywords generation-status --product <productId>`
-- reschedule one: `outrank-cli keywords reschedule <keywordId> --scheduled-for YYYY-MM-DD`
-- reschedule many: `outrank-cli keywords bulk-reschedule --json-file keyword-reschedule.json`
-
-For article actions:
-
-- `outrank-cli articles generate <keywordId>` is only for keywords scheduled for today
-- `outrank-cli articles precreate <keywordId>` is only for eligible future scheduled keywords
-- trial users cannot pre-create articles
-- past-due subscriptions block article actions
-- future scheduled articles cannot be manually published early through `articles update`
-
-For deletion:
-
-- delete one: `outrank-cli keywords delete <keywordId>`
-- delete many: `outrank-cli keywords bulk-delete --json-file keyword-delete.json`
-
-When answering humans, call the scheduled set the content plan or keyword plan. Call stored keywords unscheduled inventory or stored keywords. Do not talk about internal table names.
-
-## Pause and resume
-
-Use:
-
-- `outrank-cli products pause <productId>`
-- `outrank-cli products resume <productId>`
-
-These affect billing-adjacent product state. Read the returned guidance carefully and relay any human-only step.
-
-## Article workflow
-
-Inspect before mutating:
-
-- `outrank-cli articles list --product <productId>`
-- `outrank-cli articles get <articleId>`
-- `outrank-cli articles get-content <articleId>`
-
-Important behavior to remember:
-
+
+To add keywords:
+
+- for direct adds, use `outrank-cli keywords add --product <productId> --json-file keywords.json`
+- for promoting existing stored keywords, include `stored_keyword_ids` in that JSON payload
+
+Important behavior to remember:
+
+- add is idempotent where possible; existing scheduled keywords come back as existing rather than being duplicated
+- stored keywords are unscheduled inventory, not disabled scheduled keywords
+- stored keywords are read-only inventory; they can be promoted into the plan but not deleted directly
+- auto-scheduling respects the backend's real planner logic, including publish days and pending downgrade limits
+- if keyword generation status says writes are blocked, treat both scheduled and stored keywords as read-only until the blocker clears
+- if the main subscription is `past_due`, keyword mutations are blocked and only reads are allowed
+- scheduled keywords with created or pre-created articles are read-only
+- keywords in `generating_article` are read-only until generation finishes
+- past keywords are read-only except past `scheduled` or `disabled` keywords without an article, which may still be rescheduled
+- if the response reports skipped keywords, explain the actual skip reason to the human instead of pretending the add fully succeeded
+
+For schedule changes:
+
+- check writability first when there is any doubt: `outrank-cli keywords generation-status --product <productId>`
+- `keywords list` uses planner-first ordering for scheduled results, so page 1 prioritizes upcoming scheduled items before past ones
+- confirm keyword presence with `outrank-cli keywords list --product <productId> --scope scheduled --q "<keyword>"`; if `next_offset` is not `null`, keep paging before claiming it is missing
+- keyword records return top-level `article_type`, `article_subtype`, `expected_length`, and label fields; use those directly for article-type or expected-length questions instead of checking product output-settings
+- update one keyword's mutable fields: `outrank-cli keywords update <keywordId> --json '{"instructions":"..."}'`
+- answer or replace the keyword's quality questions with `outrank-cli keywords update <keywordId> --json '{"quality_questions":[{"id":"...","question":"...","answer":"..."}]}'`
+- `outrank-cli keywords get <keywordId>` returns `article_type_options`; use those values when patching `article_type`, `article_subtype`, or `expected_length`
+- `outrank-cli keywords update <keywordId> --json '{"article_type":"guide","article_subtype":"explainer","expected_length":"long"}'` mirrors the scheduler card Article Type Settings modal and rejects values outside the allowed option lists
+- reschedule one: `outrank-cli keywords update <keywordId> --json '{"scheduled_for":"YYYY-MM-DD"}'`
+- reschedule many: `outrank-cli keywords bulk-reschedule --json-file keyword-reschedule.json`
+
+For article actions:
+
+- `outrank-cli articles generate <keywordId>` is only for keywords scheduled for today
+- `outrank-cli articles precreate <keywordId>` is only for eligible future scheduled keywords
+- article records with a linked scheduled keyword also return top-level `article_type`, `article_subtype`, `expected_length`, and label fields
+- trial users cannot pre-create articles
+- past-due subscriptions block article actions
+- future scheduled articles cannot be manually published early through `articles update`
+
+For deletion:
+
+- delete one: `outrank-cli keywords delete <keywordId>`
+- delete many: `outrank-cli keywords bulk-delete --json-file keyword-delete.json`
+
+When answering humans, call the scheduled set the content plan or keyword plan. Call stored keywords unscheduled inventory or stored keywords. Do not talk about internal table names.
+
+## Pause and resume
+
+Use:
+
+- `outrank-cli products pause <productId>`
+- `outrank-cli products resume <productId>`
+
+These affect billing-adjacent product state. Read the returned guidance carefully and relay any human-only step.
+
+## Article workflow
+
+Inspect before mutating:
+
+- `outrank-cli articles list --product <productId>`
+- `outrank-cli articles get <articleId>`
+- `outrank-cli articles get-content <articleId>`
+
+Important behavior to remember:
+
 - article metadata and history mirror the current app behavior, including soft-delete instead of hard-delete
 - article bodies are markdown in the backend; `--format html` is rendered output, not the source of truth
 - featured image is separate from the markdown body and can be updated either through the normal article update payload via `image_url` or by local-file upload with `articles upload-featured-image`
 - in-content images can be uploaded from local files with `articles upload-image`; the command returns a hosted URL and alt text for markdown insertion or replacement
 - per-article instructions live on the linked scheduled keyword, so they are only editable while that planner relationship still exists and is writable
+- `articles get <articleId>` returns `article_type_options`; use those values when patching `article_type`, `article_subtype`, or `expected_length`
+- `articles update --json '{"article_type":"guide","article_subtype":"howTo","expected_length":"medium"}'` mirrors the dashboard Article Type Settings modal and rejects values outside the allowed option lists
 - `articles update --json '{"status":"published"}'` attempts a real publish through the product's active integration for eligible attached articles; if the remote publish fails, inspect the returned error and the article's `publish_error`
 - slug is readable for reference but read-only in the agent API
 - `articles generate <keywordId>` mirrors the current create-and-publish flow for a scheduled keyword
 - `articles precreate <keywordId>` mirrors the current pre-generation flow; after calling it, inspect the keyword state until it moves from `generating_article` to `pregenerated` or back to `scheduled`
-- `articles retry-publish <articleId>` only works for generated articles with a publish error
-- `articles bulk-replace` is preview-first; review the returned excerpts, then rerun with `"confirm": true` in the JSON payload to write changes
-
-## Buying more product slots
-
-Always do this in two steps:
-
-1. Quote the change: `outrank-cli billing purchase-products quote --additional-products <n>`
-2. If the human approves, submit the purchase with the exact quoted recurring total:
-   `outrank-cli billing purchase-products buy --additional-products <n> --confirm-charge-cents <quoted> --idempotency-key <stable-random-key>`
-
-Never guess `confirm-charge-cents`. Use the server-quoted number.
-Do not ask for billing approval until you have already clarified the intended product configuration and any defaulted article/publishing settings.
-
-## Error handling
-
-- If `ok` is `false`, read both `error.message` and `agent_guidance`.
-- For `401`, help the human refresh `OUTRANK_API_KEY`.
-- For `403` or `409`, the guidance usually tells you whether to inspect state, pause another product, or ask the human to approve a billing step.
-- For `402`, stop retrying and ask the human to fix billing.
-
+- `articles retry-publish <articleId>` only works for generated articles with a publish error
+- `articles bulk-replace` is preview-first; review the returned excerpts, then rerun with `"confirm": true` in the JSON payload to write changes
+
+## Article improvements workflow
+
+Article improvements take an already-published post, analyze its Search Console performance, draft a rewrite brief, run a multi-step rewrite, and push the improved version back to the CMS. This is a separate surface from article generation. It requires the All-in-One plan; on Basic plan candidate lists come back empty and write actions return `PLAN_UPGRADE_REQUIRED`.
+
+Inspect before mutating:
+
+- `outrank-cli improvements settings get <productId>` — shows `enabled`, `auto_push`, `publishing_days`, the CMS `readiness` (whether a push can actually land), and `activity` counts
+- `outrank-cli improvements candidates list <productId> [--type <opportunity_type>]` — opportunities available to schedule
+- `outrank-cli improvements tasks list <productId>` — scheduled tasks, each with its `latest_execution` for progress polling
+- `outrank-cli improvements executions list <productId> --review-status awaiting_review` — the review inbox
+
+Typical manual flow:
+
+1. `outrank-cli improvements analyze <productId>` — discover/refresh opportunities (heavy, multi-minute; re-list candidates after)
+2. `outrank-cli improvements candidates brief <candidateId>` — generate the rewrite brief (heavy; poll the candidate until `brief_status` is `ready`)
+3. optionally `outrank-cli improvements candidates edit-brief <candidateId> --json-file brief.json` to refine it
+4. `outrank-cli improvements candidates schedule <candidateId> --scheduled-for <iso-date>` — create the task
+5. `outrank-cli improvements tasks execute <taskId>` — run the rewrite now (heavy; poll `improvements executions get <executionId>` until `status` is `completed`)
+6. review and publish: `outrank-cli improvements executions get <executionId>`, then `outrank-cli improvements executions push <executionId>`
+
+Important behavior to remember:
+
+- turning settings `enabled` on starts an unattended loop — weekly opportunity discovery, daily auto-scheduling on `publishing_days` (max 2 weekdays), and execution every ~15 minutes. Always tell the human this before enabling.
+- with `auto_push` on, each successful rewrite is published to the CMS with no human review (still skipped automatically on a hard validation failure or an unverified backlink). Only enable it via `settings update` after the human confirms.
+- analyze, candidates brief, and tasks execute run in Firebase and can take minutes; if a call times out at the edge the work continues server-side, so re-list or poll the execution instead of retrying
+- `executions get` returns `before`/`after`, paragraph-level `hunks` (each with an id), and `validation_issues`; to accept everything, `executions push` with no JSON; to reject or edit specific hunks, send `{"decisions":{"<hunkId>":"rejected"},"edited_hunks":{"<hunkId>":"..."}}` to `executions decisions` or directly in the push body
+- decisions and push only work while `review_status` is `awaiting_review`
+- a push always updates the article inside Outrank first; if `cms_response.status` is `skipped` the CMS is not connected/supported for auto-push (publish manually); a `CMS_PUSH_FAILED` error means the CMS rejected it — inspect `error.details.cms_response` and retry
+- `tasks execute --improve-images false` skips image regeneration (default regenerates images)
+
+## Buying more product slots
+
+Always do this in two steps:
+
+1. Quote the change: `outrank-cli billing purchase-products quote --additional-products <n>`
+2. If the human approves, submit the purchase with the exact quoted recurring total:
+   `outrank-cli billing purchase-products buy --additional-products <n> --confirm-charge-cents <quoted> --idempotency-key <stable-random-key>`
+
+Never guess `confirm-charge-cents`. Use the server-quoted number.
+Do not ask for billing approval until you have already clarified the intended product configuration and any defaulted article/publishing settings.
+
+## Error handling
+
+- If `ok` is `false`, read both `error.message` and `agent_guidance`.
+- For `401`, help the human refresh `OUTRANK_API_KEY`.
+- For `403` or `409`, the guidance usually tells you whether to inspect state, pause another product, or ask the human to approve a billing step.
+- For `402`, stop retrying and ask the human to fix billing.
+
 ## Current limitation
 
-The implementation plan is broader than the current live API. Keywords, core article flows, linking, backlink exchange management, and the current integration-management flows are now exposed in `outrank-cli`, including direct setup for webhook, Ghost, Shopify, Webflow, Wix, Framer, WordPress Plugin, and Next.js Blog, plus OAuth flows for WordPress.com and Notion. Purchasing or changing backlink add-ons and some onboarding flows still require the dashboard. If the user asks for something not present in `outrank-cli --help`, say that exact command surface is not shipped yet and do not invent unsupported commands.
-
+The implementation plan is broader than the current live API. Keywords, core article flows, article improvements, linking, backlink exchange management, and the current integration-management flows are exposed in `outrank-cli`, including direct setup for webhook, Ghost, Shopify, Webflow, Wix, Framer, WordPress Plugin, and Next.js Blog, plus OAuth flows for WordPress.com and Notion. Purchasing or changing backlink add-ons and some onboarding flows still require the dashboard. If the user asks for something not present in `outrank-cli --help`, say that exact command surface is not shipped yet and do not invent unsupported commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "outrank-cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Agent-first CLI for the Outrank agent API",
   "type": "module",
   "files": [

package/src/commands/improvements.js

@@ -0,0 +1,277 @@
+import { parseArgs, getRequiredPositional, readJsonInput, hasFlag, parseIntegerOption, getOption } from '../core/args.js';
+import { requestAgentApi } from '../core/api.js';
+import { cliSuccess } from '../core/errors.js';
+
+export const IMPROVEMENTS_HELP = `Usage:
+  outrank-cli improvements settings get <product-id>
+  outrank-cli improvements settings update <product-id> --json <object>
+  outrank-cli improvements analyze <product-id>
+  outrank-cli improvements candidates list <product-id> [--type outsider|ctr_gap|declining|content_gap|thin_content] [--limit <n>] [--offset <n>]
+  outrank-cli improvements candidates brief <candidate-id> [--task <task-id>]
+  outrank-cli improvements candidates edit-brief <candidate-id> --json <object>
+  outrank-cli improvements candidates schedule <candidate-id> --scheduled-for <iso-date>
+  outrank-cli improvements tasks list <product-id>
+  outrank-cli improvements tasks reschedule <task-id> --scheduled-for <iso-date>
+  outrank-cli improvements tasks cancel <task-id>
+  outrank-cli improvements tasks edit-brief <task-id> --json <object>
+  outrank-cli improvements tasks execute <task-id> [--improve-images true|false]
+  outrank-cli improvements executions list <product-id> [--review-status awaiting_review|pushed|auto_pushed|rejected|all] [--limit <n>] [--offset <n>]
+  outrank-cli improvements executions get <execution-id>
+  outrank-cli improvements executions decisions <execution-id> --json <object>
+  outrank-cli improvements executions push <execution-id> [--json <object>]
+
+JSON Input:
+  Use one of: --json '<object>', --json-file payload.json, or --json-stdin
+
+Notes:
+  Article improvements need the All-in-One plan. Turning settings on starts an unattended loop
+  (weekly opportunity discovery, daily auto-scheduling on the configured publishing_days, and
+  execution every ~15 minutes). With auto_push on, each successful rewrite is published to the CMS
+  without review. analyze, candidates brief, and tasks execute are heavy multi-minute operations:
+  if a call times out at the edge, the work continues server-side — re-list/poll instead of retrying.
+
+Examples:
+  outrank-cli improvements settings get 00000000-0000-0000-0000-000000000000
+  outrank-cli improvements settings update 00000000-0000-0000-0000-000000000000 --json '{"enabled":true,"auto_push":false,"publishing_days":["Mon","Thu"]}'
+  outrank-cli improvements analyze 00000000-0000-0000-0000-000000000000
+  outrank-cli improvements candidates list 00000000-0000-0000-0000-000000000000 --type ctr_gap --limit 20
+  outrank-cli improvements candidates brief 00000000-0000-0000-0000-000000000000
+  outrank-cli improvements candidates edit-brief 00000000-0000-0000-0000-000000000000 --json-file brief.json
+  outrank-cli improvements candidates schedule 00000000-0000-0000-0000-000000000000 --scheduled-for 2026-06-01
+  outrank-cli improvements tasks list 00000000-0000-0000-0000-000000000000
+  outrank-cli improvements tasks execute 00000000-0000-0000-0000-000000000000 --improve-images false
+  outrank-cli improvements executions list 00000000-0000-0000-0000-000000000000 --review-status awaiting_review
+  outrank-cli improvements executions get 00000000-0000-0000-0000-000000000000
+  outrank-cli improvements executions push 00000000-0000-0000-0000-000000000000
+  outrank-cli improvements executions push 00000000-0000-0000-0000-000000000000 --json '{"decisions":{"para-3":"rejected"}}'
+`;
+
+const invalidUsage = (message, guidance) =>
+  Object.assign(new Error(message), {
+    cliCode: 'CLI_INVALID_USAGE',
+    guidance: guidance || 'Run `outrank-cli improvements --help` to see available improvement commands.',
+  });
+
+const buildQueryPath = (basePath, searchParams) => {
+  const url = new URL(`https://local${basePath}`);
+  for (const [key, value] of Object.entries(searchParams)) {
+    if (value !== undefined && value !== null && value !== '') {
+      url.searchParams.set(key, String(value));
+    }
+  }
+  return `${url.pathname}${url.search}`;
+};
+
+const hasJsonSource = (parsed) =>
+  Boolean(getOption(parsed, 'json') || getOption(parsed, 'json-file') || hasFlag(parsed, 'json-stdin'));
+
+const parseImproveImages = (parsed) => {
+  const raw = getOption(parsed, 'improve-images');
+  if (raw === undefined) return undefined;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  throw invalidUsage('--improve-images must be true or false.', 'Pass `--improve-images true` or `--improve-images false`, or omit it to use the default (images are regenerated).');
+};
+
+const requireScheduledFor = (parsed) => {
+  const value = getOption(parsed, 'scheduled-for');
+  if (!value) {
+    throw invalidUsage('Missing required option: --scheduled-for <iso-date>.', 'Pass a date or ISO timestamp, e.g. `--scheduled-for 2026-06-01`.');
+  }
+  return value;
+};
+
+const handleAnalyze = async (parsed) => {
+  const productId = getRequiredPositional(parsed, 0, '<product-id>');
+  const response = await requestAgentApi(parsed, {
+    method: 'POST',
+    path: `/products/${productId}/improvements/analyze`,
+  });
+  return response.payload;
+};
+
+const handleSettings = async (action, parsed) => {
+  const productId = getRequiredPositional(parsed, 0, '<product-id>');
+  if (action === 'get') {
+    const response = await requestAgentApi(parsed, {
+      method: 'GET',
+      path: `/products/${productId}/improvements/settings`,
+    });
+    return response.payload;
+  }
+  if (action === 'update') {
+    const body = await readJsonInput(parsed);
+    const response = await requestAgentApi(parsed, {
+      method: 'PATCH',
+      path: `/products/${productId}/improvements/settings`,
+      body,
+    });
+    return response.payload;
+  }
+  throw invalidUsage(`Unknown settings action: ${action ?? '(none)'}.`, 'Use: improvements settings get|update <product-id>.');
+};
+
+const handleCandidates = async (action, parsed) => {
+  if (action === 'list') {
+    const productId = getRequiredPositional(parsed, 0, '<product-id>');
+    const path = buildQueryPath(`/products/${productId}/improvements/candidates`, {
+      type: getOption(parsed, 'type'),
+      limit: parseIntegerOption(parsed, 'limit', { min: 1, max: 50 }),
+      offset: parseIntegerOption(parsed, 'offset', { min: 0 }),
+    });
+    const response = await requestAgentApi(parsed, { method: 'GET', path });
+    return response.payload;
+  }
+  if (action === 'brief') {
+    const candidateId = getRequiredPositional(parsed, 0, '<candidate-id>');
+    const taskId = getOption(parsed, 'task');
+    const response = await requestAgentApi(parsed, {
+      method: 'POST',
+      path: `/improvements/candidates/${candidateId}/brief`,
+      body: taskId ? { task_id: taskId } : {},
+    });
+    return response.payload;
+  }
+  if (action === 'edit-brief') {
+    const candidateId = getRequiredPositional(parsed, 0, '<candidate-id>');
+    const body = await readJsonInput(parsed);
+    const response = await requestAgentApi(parsed, {
+      method: 'PATCH',
+      path: `/improvements/candidates/${candidateId}/brief`,
+      body,
+    });
+    return response.payload;
+  }
+  if (action === 'schedule') {
+    const candidateId = getRequiredPositional(parsed, 0, '<candidate-id>');
+    const scheduledFor = requireScheduledFor(parsed);
+    const response = await requestAgentApi(parsed, {
+      method: 'POST',
+      path: `/improvements/candidates/${candidateId}/schedule`,
+      body: { scheduled_for: scheduledFor },
+    });
+    return response.payload;
+  }
+  throw invalidUsage(`Unknown candidates action: ${action ?? '(none)'}.`, 'Use: improvements candidates list|brief|edit-brief|schedule.');
+};
+
+const handleTasks = async (action, parsed) => {
+  if (action === 'list') {
+    const productId = getRequiredPositional(parsed, 0, '<product-id>');
+    const response = await requestAgentApi(parsed, {
+      method: 'GET',
+      path: `/products/${productId}/improvements/tasks`,
+    });
+    return response.payload;
+  }
+  if (action === 'reschedule') {
+    const taskId = getRequiredPositional(parsed, 0, '<task-id>');
+    const scheduledFor = requireScheduledFor(parsed);
+    const response = await requestAgentApi(parsed, {
+      method: 'PATCH',
+      path: `/improvements/tasks/${taskId}`,
+      body: { scheduled_for: scheduledFor },
+    });
+    return response.payload;
+  }
+  if (action === 'cancel') {
+    const taskId = getRequiredPositional(parsed, 0, '<task-id>');
+    const response = await requestAgentApi(parsed, {
+      method: 'DELETE',
+      path: `/improvements/tasks/${taskId}`,
+    });
+    return response.payload;
+  }
+  if (action === 'edit-brief') {
+    const taskId = getRequiredPositional(parsed, 0, '<task-id>');
+    const body = await readJsonInput(parsed);
+    const response = await requestAgentApi(parsed, {
+      method: 'PATCH',
+      path: `/improvements/tasks/${taskId}/brief`,
+      body,
+    });
+    return response.payload;
+  }
+  if (action === 'execute') {
+    const taskId = getRequiredPositional(parsed, 0, '<task-id>');
+    const improveImages = parseImproveImages(parsed);
+    const response = await requestAgentApi(parsed, {
+      method: 'POST',
+      path: `/improvements/tasks/${taskId}/execute`,
+      body: improveImages === undefined ? {} : { improve_images: improveImages },
+    });
+    return response.payload;
+  }
+  throw invalidUsage(`Unknown tasks action: ${action ?? '(none)'}.`, 'Use: improvements tasks list|reschedule|cancel|edit-brief|execute.');
+};
+
+const handleExecutions = async (action, parsed) => {
+  if (action === 'list') {
+    const productId = getRequiredPositional(parsed, 0, '<product-id>');
+    const path = buildQueryPath(`/products/${productId}/improvements/executions`, {
+      review_status: getOption(parsed, 'review-status'),
+      limit: parseIntegerOption(parsed, 'limit', { min: 1, max: 100 }),
+      offset: parseIntegerOption(parsed, 'offset', { min: 0 }),
+    });
+    const response = await requestAgentApi(parsed, { method: 'GET', path });
+    return response.payload;
+  }
+  if (action === 'get') {
+    const executionId = getRequiredPositional(parsed, 0, '<execution-id>');
+    const response = await requestAgentApi(parsed, {
+      method: 'GET',
+      path: `/improvements/executions/${executionId}`,
+    });
+    return response.payload;
+  }
+  if (action === 'decisions') {
+    const executionId = getRequiredPositional(parsed, 0, '<execution-id>');
+    const body = await readJsonInput(parsed);
+    const response = await requestAgentApi(parsed, {
+      method: 'PATCH',
+      path: `/improvements/executions/${executionId}/decisions`,
+      body,
+    });
+    return response.payload;
+  }
+  if (action === 'push') {
+    const executionId = getRequiredPositional(parsed, 0, '<execution-id>');
+    const body = hasJsonSource(parsed) ? await readJsonInput(parsed) : {};
+    const response = await requestAgentApi(parsed, {
+      method: 'POST',
+      path: `/improvements/executions/${executionId}/push`,
+      body,
+    });
+    return response.payload;
+  }
+  throw invalidUsage(`Unknown executions action: ${action ?? '(none)'}.`, 'Use: improvements executions list|get|decisions|push.');
+};
+
+export const handleImprovementsCommand = async (argv) => {
+  const subgroup = argv[0];
+  const wantsHelp =
+    !subgroup || subgroup === '--help' || subgroup === '-h' || subgroup === 'help';
+
+  if (wantsHelp) {
+    return cliSuccess(
+      {
+        usage: IMPROVEMENTS_HELP.trim(),
+      },
+      'Choose a sub-noun: settings, analyze, candidates, tasks, or executions. The typical flow is analyze -> candidates brief -> candidates schedule -> tasks execute -> executions push.',
+    );
+  }
+
+  if (subgroup === 'analyze') {
+    return handleAnalyze(parseArgs(argv.slice(1)));
+  }
+
+  const action = argv[1];
+  const parsed = parseArgs(argv.slice(2));
+
+  if (subgroup === 'settings') return handleSettings(action, parsed);
+  if (subgroup === 'candidates') return handleCandidates(action, parsed);
+  if (subgroup === 'tasks') return handleTasks(action, parsed);
+  if (subgroup === 'executions') return handleExecutions(action, parsed);
+
+  throw invalidUsage(`Unknown improvements sub-noun: ${subgroup}.`);
+};

package/src/commands/keywords.js

@@ -16,10 +16,10 @@ export const KEYWORDS_HELP = `Usage:
   outrank-cli keywords export --product <product-id>
   outrank-cli keywords generation-status --product <product-id>
   outrank-cli keywords add --product <product-id> --json <object>
+  outrank-cli keywords update <keyword-id> --json <object>
   outrank-cli keywords suggest --product <product-id> (--keyword <text> | --theme <text>) [--keyword-region <code>] [--limit <n>]
   outrank-cli keywords generate --product <product-id> --count <n> [--source competitors|audiences|both] [--competitor <competitor-id> ...] [--audience <text> ...]
   outrank-cli keywords bulk-process --product <product-id> --json <object> [--keyword-region <code>]
-  outrank-cli keywords reschedule <keyword-id> --scheduled-for <date>
   outrank-cli keywords bulk-reschedule --json <object>
   outrank-cli keywords delete <keyword-id>
   outrank-cli keywords bulk-delete --json <object>
@@ -29,14 +29,16 @@ JSON Input:
 
 Examples:
   outrank-cli keywords list --product 00000000-0000-0000-0000-000000000000 --scope all
+  outrank-cli keywords list --product 00000000-0000-0000-0000-000000000000 --scope scheduled --q "best seo tools"
   outrank-cli keywords export --product 00000000-0000-0000-0000-000000000000
   outrank-cli keywords generation-status --product 00000000-0000-0000-0000-000000000000
   outrank-cli keywords add --product 00000000-0000-0000-0000-000000000000 --json-file keywords.json
+  outrank-cli keywords update 00000000-0000-0000-0000-000000000000 --json '{"instructions":"Write for beginners and include a step-by-step setup section"}'
+  outrank-cli keywords update 00000000-0000-0000-0000-000000000000 --json '{"scheduled_for":"2026-05-20"}'
   outrank-cli keywords suggest --product 00000000-0000-0000-0000-000000000000 --theme "email marketing" --limit 8
   outrank-cli keywords generate --product 00000000-0000-0000-0000-000000000000 --count 10 --source both
   outrank-cli keywords generate --product 00000000-0000-0000-0000-000000000000 --count 5 --source competitors --competitor 11111111-1111-1111-1111-111111111111
   outrank-cli keywords bulk-process --product 00000000-0000-0000-0000-000000000000 --json '{"keywords":["keyword one","keyword two"]}'
-  outrank-cli keywords reschedule 00000000-0000-0000-0000-000000000000 --scheduled-for 2026-05-20
   outrank-cli keywords bulk-reschedule --json-file keyword-reschedule.json
   outrank-cli keywords delete 00000000-0000-0000-0000-000000000000
 `;
@@ -131,6 +133,17 @@ const handleKeywordsAdd = async (parsed) => {
   return response.payload;
 };
 
+const handleKeywordsUpdate = async (parsed) => {
+  const keywordId = getRequiredPositional(parsed, 0, '<keyword-id>');
+  const body = await readJsonInput(parsed);
+  const response = await requestAgentApi(parsed, {
+    method: 'PATCH',
+    path: `/keywords/${keywordId}`,
+    body,
+  });
+  return response.payload;
+};
+
 const handleKeywordsSuggest = async (parsed) => {
   const keyword = getOption(parsed, 'keyword');
   const theme = getOption(parsed, 'theme');
@@ -228,26 +241,6 @@ const handleKeywordsBulkProcess = async (parsed) => {
   return response.payload;
 };
 
-const handleKeywordsReschedule = async (parsed) => {
-  const keywordId = getRequiredPositional(parsed, 0, '<keyword-id>');
-  const scheduledFor = getOption(parsed, 'scheduled-for');
-  if (!scheduledFor) {
-    throw Object.assign(new Error('Missing required option: --scheduled-for <date>.'), {
-      cliCode: 'CLI_INVALID_USAGE',
-      guidance: 'Pass the target schedule date with `--scheduled-for YYYY-MM-DD` or an ISO timestamp.',
-    });
-  }
-
-  const response = await requestAgentApi(parsed, {
-    method: 'PATCH',
-    path: `/keywords/${keywordId}`,
-    body: {
-      scheduled_for: scheduledFor,
-    },
-  });
-  return response.payload;
-};
-
 const handleKeywordsBulkReschedule = async (parsed) => {
   const body = await readJsonInput(parsed);
   const response = await requestAgentApi(parsed, {
@@ -287,7 +280,7 @@ export const handleKeywordsCommand = async (argv) => {
       {
         usage: KEYWORDS_HELP.trim(),
       },
-      'Choose one of: list, get, export, generation-status, add, suggest, generate, bulk-process, reschedule, bulk-reschedule, delete, bulk-delete.',
+      'Choose one of: list, get, export, generation-status, add, update, suggest, generate, bulk-process, bulk-reschedule, delete, bulk-delete.',
     );
   }
 
@@ -296,10 +289,10 @@ export const handleKeywordsCommand = async (argv) => {
   if (subcommand === 'export') return handleKeywordsExport(parsed);
   if (subcommand === 'generation-status') return handleKeywordsGenerationStatus(parsed);
   if (subcommand === 'add') return handleKeywordsAdd(parsed);
+  if (subcommand === 'update') return handleKeywordsUpdate(parsed);
   if (subcommand === 'suggest') return handleKeywordsSuggest(parsed);
   if (subcommand === 'generate') return handleKeywordsGenerate(parsed);
   if (subcommand === 'bulk-process') return handleKeywordsBulkProcess(parsed);
-  if (subcommand === 'reschedule') return handleKeywordsReschedule(parsed);
   if (subcommand === 'bulk-reschedule') return handleKeywordsBulkReschedule(parsed);
   if (subcommand === 'delete') return handleKeywordsDelete(parsed);
   if (subcommand === 'bulk-delete') return handleKeywordsBulkDelete(parsed);

package/src/index.js

@@ -12,6 +12,7 @@ import { handleSubscriptionCommand } from './commands/subscription.js';
 import { handleUsageCommand } from './commands/usage.js';
 import { handleKeywordsCommand } from './commands/keywords.js';
 import { handleArticlesCommand } from './commands/articles.js';
+import { handleImprovementsCommand } from './commands/improvements.js';
 
 const getVersion = () => {
   try {
@@ -35,6 +36,7 @@ Groups:
   products    List, create, inspect, and configure products, integrations, article settings, Google Search Console, linking, and backlinks.
   keywords    Inspect, check write status, add, reschedule, delete, suggest, generate, and export keyword plans.
   articles    Inspect article metadata and bodies, edit content, retry publish, precreate, and generate.
+  improvements Discover, brief, schedule, run, review, and publish article improvements for existing posts.
   subscription Inspect plan, trial, quota, and add-on status.
   usage       Inspect current usage and quota consumption.
   billing     Product-slot purchase flows.
@@ -55,6 +57,8 @@ Examples:
   outrank-cli products list --limit 20
   outrank-cli keywords list --product 00000000-0000-0000-0000-000000000000 --scope all
   outrank-cli articles list --product 00000000-0000-0000-0000-000000000000 --status published
+  outrank-cli improvements candidates list 00000000-0000-0000-0000-000000000000 --type ctr_gap
+  outrank-cli improvements tasks execute 00000000-0000-0000-0000-000000000000
   outrank-cli subscription status
   outrank-cli usage stats
   outrank-cli products create --json-file product.json
@@ -111,6 +115,8 @@ const main = async () => {
     result = await handleKeywordsCommand(rest);
   } else if (group === 'articles') {
     result = await handleArticlesCommand(rest);
+  } else if (group === 'improvements') {
+    result = await handleImprovementsCommand(rest);
   } else if (group === 'subscription') {
     result = await handleSubscriptionCommand(rest);
   } else if (group === 'usage') {