outrank-cli 0.3.0 → 0.5.0

package/README.md

@@ -50,6 +50,14 @@ This repo currently targets the agent endpoints that already exist in `outrank`:
 - `products backlinks get|update|credits|earned|unverified|check-removal|reverify|subscription|subscribe-quote`
 - `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`
+- `marketplace seller status|onboard|eligibility|settings|integrations|stripe|complete-onboarding|placements|earnings|content-history`
+- `marketplace notifications list|mark-read`
+- `marketplace buyer status|billing-status|subscription|subscribe-quote|checkout|change-plan|target-pages|participation|placements|article|credits`
 - `subscription status`
 - `usage stats`
 - `billing portal-url`
@@ -110,6 +118,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
@@ -192,6 +205,11 @@ 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 update 00000000-0000-0000-0000-000000000000 --json '{"scheduled_for":"2026-05-20"}'
 outrank-cli billing purchase-products quote --additional-products 2
+outrank-cli marketplace seller status 00000000-0000-0000-0000-000000000000
+outrank-cli marketplace seller onboard 00000000-0000-0000-0000-000000000000 --country US
+outrank-cli marketplace seller placements list 00000000-0000-0000-0000-000000000000 --status needs_approval
+outrank-cli marketplace seller earnings 00000000-0000-0000-0000-000000000000
+outrank-cli marketplace buyer status 00000000-0000-0000-0000-000000000000
 ```
 
 ## Google Search Console workflow
@@ -271,6 +289,23 @@ Example payload:
 }
 ```
 
+## Marketplace workflow
+
+Seller side (live):
+
+- Start with `outrank-cli marketplace seller status <product-id>` — its guidance walks the onboarding wizard (Blog -> Articles -> Integration -> Payouts).
+- `outrank-cli marketplace seller onboard <product-id> [--country <ISO2>]` orchestrates onboarding: it reports remaining steps, adopts an existing reusable CMS automatically (never ask the user to pick a platform when one is reusable), and creates the Stripe Express account once the earlier steps are done and a country is provided.
+- Stripe identity/bank onboarding happens in a browser — surface the returned `onboardingUrl` to the human.
+- Finish with `outrank-cli marketplace seller complete-onboarding <product-id>` and always report the eligibility check results (`marketplace seller eligibility`) to the human.
+- Day-to-day: `placements list|approve|decline|publish|regenerate`, `earnings`, `settings get|update`, `stripe manage`, `content-history`, and `marketplace notifications list --role seller`.
+- Admin-only (server-enforced against the key creator's current role): settings update, integrations writes, stripe commands, complete-onboarding, placements decline.
+
+Buyer side:
+
+- Start with `outrank-cli marketplace buyer status <product-id>` — its guidance drives the setup sequence.
+- The mandatory sequence: Enterprise backlink plan (`buyer subscribe-quote`, a human org admin completes checkout — purchasing is admin-only) -> add target pages (`buyer target-pages discover|add`) -> `buyer participation on`.
+- Then `buyer placements list|regenerate|revalidate`, `buyer article get|edit`, `buyer credits history`, and `marketplace notifications list --role buyer`.
+
 ## Keyword mutation rules
 
 - Run `outrank-cli keywords generation-status --product <product-id>` before keyword writes when you are not sure the product is writable.
@@ -283,10 +318,10 @@ Example payload:
 - 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.
+- 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.
@@ -307,6 +342,19 @@ Example payload:
 - `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.

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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).
+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, quote/buy product slots, or work with the Outrank Marketplace (seller onboarding, eligibility, placements, earnings, Stripe payouts, buyer target pages and placements). Requires outrank-cli on PATH and an Outrank API key (env OUTRANK_API_KEY or stored via auth login).
 ---
 
 # Outrank Skill
@@ -12,6 +12,10 @@ In human-facing responses, call `products get` / `products update` the product's
 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.
 
+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.
+
+Use `marketplace ...` for the Outrank Marketplace: seller onboarding and eligibility, placement approval/decline/publishing, earnings and Stripe Express payouts, marketplace notifications, and buyer target pages, placements, and credits. This is distinct from `products backlinks ...`, which is the classic backlink exchange.
+
 ## 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`.
@@ -31,6 +35,8 @@ Run group help when needed:
 - `outrank-cli products --help`
 - `outrank-cli keywords --help`
 - `outrank-cli articles --help`
+- `outrank-cli improvements --help`
+- `outrank-cli marketplace --help`
 - `outrank-cli subscription --help`
 - `outrank-cli usage --help`
 - `outrank-cli billing --help`
@@ -47,6 +53,10 @@ Prefer inspecting before mutating:
 - `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>`
@@ -77,6 +87,13 @@ Prefer inspecting before mutating:
 - `outrank-cli products backlinks earned <productId>`
 - `outrank-cli products backlinks unverified <productId>`
 - `outrank-cli products backlinks subscription <productId>`
+- `outrank-cli marketplace seller status <productId>`
+- `outrank-cli marketplace seller eligibility <productId>`
+- `outrank-cli marketplace seller placements list <productId>`
+- `outrank-cli marketplace seller earnings <productId>`
+- `outrank-cli marketplace buyer status <productId>`
+- `outrank-cli marketplace buyer target-pages list <productId>`
+- `outrank-cli marketplace notifications list <productId> --role seller`
 - `outrank-cli subscription status`
 - `outrank-cli usage stats`
 
@@ -395,6 +412,7 @@ When the user asks for keyword ideas:
 
 Treat `keywords suggest` as candidate-generation only. It does not change the content plan until you add keywords.
 Treat `keywords generate` as the dashboard Generate Keywords action. It creates scheduled keywords through the same backend pipeline.
+Product-wide keyword research instructions live in product article settings as `global_keyword_prompt` (`products output-settings get|update`). They steer every keyword research run for the product and are separate from per-keyword `instructions`. When the human wants a standing rule for all future keyword research (topics, angles, audiences to focus on), update `global_keyword_prompt` instead of repeating it per keyword.
 
 Before `keywords generate`:
 
@@ -482,6 +500,36 @@ Important behavior to remember:
 - `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:
@@ -493,6 +541,52 @@ Always do this in two steps:
 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.
 
+## Marketplace workflow
+
+The Outrank Marketplace connects sellers (sites that host backlink placements inside their upcoming Outrank articles and get paid per placement) with buyers (sites that spend backlink credits to place links on high-authority articles). Use `outrank-cli marketplace ...` for everything.
+
+Role note: several marketplace commands are admin-only server-side — they succeed only when the user who created the API key currently holds an org admin role. Admin-only: `seller settings update`, all `seller integrations` writes, all `seller stripe` commands, `seller complete-onboarding`, `seller placements decline`, and the buyer billing/participation writes (checkout, change-plan, participation on/off). Buyer target-page writes (add, pause/activate, delete) are open to every org member. If a command returns `ADMIN_ROLE_REQUIRED`, tell the human an organization admin must do it (dashboard or an admin-created key).
+
+### Seller onboarding
+
+The wizard order matches the dashboard: Blog -> Articles -> Integration -> Payouts, then complete. Start every session with:
+
+- `outrank-cli marketplace seller status <productId>` — composite report (enrollment, per-step onboarding state, settings, gate state) whose guidance tells you the next step
+- `outrank-cli marketplace seller onboard <productId> [--country <ISO2>]` — the orchestrator: reports remaining steps, and performs the safe automatic actions for you
+
+Step-by-step, prompting the human for the same data the dashboard collects:
+
+1. **Blog** — collect/confirm the product's content details (`products get` / `products update`) and connect Google Search Console (`products gsc connect`, human opens the URL, then `gsc poll` and `gsc set-property`). GSC is mandatory before continuing.
+2. **Articles** — review article settings (`products output-settings get/update`) and set the marketplace publishing schedule: `marketplace seller settings update <productId> --json '{"dailyArticleLimit":<1-3>,"publishingDays":[<weekday numbers, at least 3>]}'` (defaults: 2/day on Mon/Wed/Fri).
+3. **Integration** — if the product already has a reusable CMS integration, **adopt it automatically and just inform the human — never ask them to pick a platform** (`marketplace seller integrations adopt`; `seller onboard` does this for you). Only when there is no reusable integration: run `marketplace seller integrations status` for the supported platforms, connect one with the `products integrations` commands, then `marketplace seller integrations claim <productId> --integration <id> --type <platform>`. Next.js Blog cannot be reused, and plugin-managed Framer setups need a new Framer connection — the error messages say so.
+4. **Payouts** — when the earlier steps are done it is safe to create the Stripe Express account: `marketplace seller stripe onboard <productId> --country <ISO2>` (ask the human for the two-letter country of their payout bank account). Surface the returned `onboardingUrl` — the human completes identity and bank details in a browser; the agent cannot.
+5. **Finish** — `marketplace seller complete-onboarding <productId>`, then check `marketplace seller eligibility <productId>`.
+
+Always report the eligibility check results to the human — all five checks with actual vs required: GSC connected, Domain Rating >= 40, >= 100 avg monthly organic clicks (90-day window), >= 3 months of Search Console history, marketplace CMS connected. GSC and the CMS are fixable now; DR/clicks/history only grow over time — enrollment still completes, and the seller dashboard opens automatically once the site qualifies (re-checked automatically; force with `marketplace seller eligibility recheck`).
+
+### Seller operations (after onboarding)
+
+- `marketplace seller placements list <productId> [--status needs_approval|planned|live|link_not_found|lost]` — the placement pipeline with counts
+- `marketplace seller placements approve <placementId>` — only `pending_approval`; publishes immediately when the scheduled date is due
+- `marketplace seller placements decline <placementId>` — admin-only; only `matched`/`pending_approval`; refunds the buyer and cleans up the pre-generated article
+- `marketplace seller placements publish <placementId>` — publish early once the article is pregenerated and due
+- `marketplace seller placements regenerate <placementId>` — retry a failed generation
+- `marketplace seller earnings <productId>` — cents; payout states are available (cleared the 14-day hold), pending, paid
+- `marketplace seller stripe manage <productId>` — Stripe Express dashboard login link for the human
+- `marketplace seller settings get/update <productId>` — isActive (cannot enable while ineligible), approvalMode, dailyArticleLimit, publishingDays
+- `marketplace seller content-history <productId>` — marketplace-only articles (articles list with track_scope=marketplace)
+- `marketplace notifications list <productId> --role seller` and `mark-read`
+
+### Buyer
+
+Start with `marketplace buyer status <productId>` — its guidance drives the whole setup sequence. The mandatory order:
+
+1. **Enterprise backlink plan** — `marketplace buyer billing-status <productId>`; if none, `marketplace buyer subscribe-quote <productId>` and surface `subscription_management_url` to the human (checkout is an interactive Stripe flow the agent cannot complete, and purchasing is restricted to org admins)
+2. **Target pages (mandatory before the dashboard opens)** — discover with `marketplace buyer target-pages discover <productId> [--source sitemap|root_url|integration]`, present candidates to the human, add with `marketplace buyer target-pages add <productId> --urls <u1,u2,...>` (own-domain only, max 10 pages, batches of up to 50), manage with `pause`/`activate`/`delete`
+3. **Participation** — `marketplace buyer participation on <productId>` (requires the plan plus >= 1 active target page)
+
+Then: `placements list`, `placements regenerate|revalidate`, `article get/edit <placementId>` (editable only while the placement is matched or publishing and unpublished; keep the placement backlink intact), `credits history`, and `notifications --role buyer`. Each placement costs the host site's Domain Rating x 3 in backlink credits. Plan upgrades via `change-plan` are dashboard-only (interactive payment confirmation); downgrades, cancellations, and restores work from the CLI.
+
 ## Error handling
 
 - If `ok` is `false`, read both `error.message` and `agent_guidance`.
@@ -502,4 +596,4 @@ Do not ask for billing approval until you have already clarified the intended pr
 
 ## 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 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, marketplace seller and buyer flows, 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, marketplace Enterprise checkout, Stripe Express identity/bank onboarding, and marketplace plan upgrades still require the dashboard or a browser. 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.3.0",
+  "version": "0.5.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}.`);
+};