@clickminded/coauthor-cli 0.0.70 → 0.0.72
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -84,7 +84,7 @@ coauthor post-details set <id> --live-url https://example.com/post/ # where th
|
|
|
84
84
|
coauthor draft get <id> --format markdown --frontmatter --json # markdown with YAML frontmatter
|
|
85
85
|
coauthor draft get <id> --format markdown --widgets embed --json # interactives as live iframes, for a site you control
|
|
86
86
|
coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
|
|
87
|
-
coauthor credits
|
|
87
|
+
coauthor credits --json # account plan, credits left and reset date (no project needed)
|
|
88
88
|
coauthor integrations list --json # WordPress sites and X accounts
|
|
89
89
|
coauthor seo markets --country Mexico --language Spanish --json # Google search data coverage for a market
|
|
90
90
|
coauthor search-brief show <id> --json # SEO mode: target keyword and what ranks
|
|
@@ -112,7 +112,7 @@ coauthor export wordpress <id> --yes --json
|
|
|
112
112
|
|
|
113
113
|
## Credits
|
|
114
114
|
|
|
115
|
-
`coauthor credits
|
|
115
|
+
`coauthor credits --json` shows your plan, credits used, and when they reset. A typical article uses about 300 credits; images and rework rounds add the most. When included credits run out, work pauses safely and resumes with `coauthor workflow resume <id> --wait --json` (after the reset, or on Pro after adding your own provider key in CoAuthor's AI settings).
|
|
116
116
|
|
|
117
117
|
## Security
|
|
118
118
|
|
package/dist/commands.js
CHANGED
|
@@ -471,9 +471,23 @@ async function runWorkflowCommand(action, input, context) {
|
|
|
471
471
|
throw new Error('Usage: coauthor workflow <show|status|advance|run|rewind|approve|resume> <projectId>');
|
|
472
472
|
}
|
|
473
473
|
async function runCreditsCommand(input, client) {
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
474
|
+
// With no project id this is the account's balance, so an agent can check its plan and credits
|
|
475
|
+
// right after setup, before any project exists. The balance is per account either way.
|
|
476
|
+
const projectId = getString(input.values, 'project') ?? input.positionals[0];
|
|
477
|
+
const data = await client.request({ path: projectId ? `projects/${encodeURIComponent(projectId)}/credits` : 'credits' });
|
|
478
|
+
return { ok: true, message: creditsSummaryLine(data), data };
|
|
479
|
+
}
|
|
480
|
+
function creditsSummaryLine(data) {
|
|
481
|
+
if (getResponseValue(data, 'admin') === true || getResponseValue(data, 'unlimited') === true)
|
|
482
|
+
return 'Unlimited credits.';
|
|
483
|
+
const period = planRecord(getResponseValue(data, 'currentPeriod'));
|
|
484
|
+
const remaining = typeof period.remaining === 'number' ? period.remaining : null;
|
|
485
|
+
if (remaining === null)
|
|
486
|
+
return undefined;
|
|
487
|
+
const plan = getResponseString(data, 'plan');
|
|
488
|
+
const allowance = typeof period.allowance === 'number' ? ` of ${period.allowance}` : '';
|
|
489
|
+
const reset = typeof period.renewalDate === 'string' ? `; resets ${period.renewalDate.slice(0, 10)}` : '';
|
|
490
|
+
return `${plan ? `Plan: ${plan}. ` : ''}${remaining}${allowance} credits left this period${reset}.`;
|
|
477
491
|
}
|
|
478
492
|
async function runShareCommand(input, client) {
|
|
479
493
|
const projectId = requireProjectId(input);
|
|
@@ -2271,7 +2285,7 @@ const SEO_PLAN_KIND_LABELS = {
|
|
|
2271
2285
|
};
|
|
2272
2286
|
const SEO_PLAN_USAGE = [
|
|
2273
2287
|
'Usage: coauthor seo-plan show [--profile <profile-id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage <stage>] [--chance <chance>] [--limit <n>] [--json]',
|
|
2274
|
-
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
|
|
2288
|
+
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--idempotency-key <key>] [--json]',
|
|
2275
2289
|
' coauthor seo-plan write <item-id> [--json]',
|
|
2276
2290
|
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
2277
2291
|
' coauthor seo-plan done <item-id> [--undo] [--json]',
|
|
@@ -2295,6 +2309,10 @@ async function resolveProfileOption(input, client) {
|
|
|
2295
2309
|
throw new Error('No writer profile found. Create one in the CoAuthor web app.');
|
|
2296
2310
|
return fallback;
|
|
2297
2311
|
}
|
|
2312
|
+
// Quotes a value for a printed shell command (POSIX single quotes) unless it is plainly safe.
|
|
2313
|
+
function shellQuote(value) {
|
|
2314
|
+
return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
|
|
2315
|
+
}
|
|
2298
2316
|
function httpErrorCode(error) {
|
|
2299
2317
|
if (!(error instanceof AgentHttpError))
|
|
2300
2318
|
return null;
|
|
@@ -2302,6 +2320,8 @@ function httpErrorCode(error) {
|
|
|
2302
2320
|
const code = planRecord(body.error).code;
|
|
2303
2321
|
return typeof code === 'string' ? code : null;
|
|
2304
2322
|
}
|
|
2323
|
+
/** Post types the plan gives to link magnets: reference posts other sites link to as a source. */
|
|
2324
|
+
const SEO_PLAN_LINK_MAGNET_POST_TYPES = ['stats_hub', 'regulation_tracker', 'cost_reference'];
|
|
2305
2325
|
function seoPlanItemLine(item) {
|
|
2306
2326
|
const keyword = planString(item, 'primary_keyword');
|
|
2307
2327
|
const title = planString(item, 'title') ?? keyword ?? '(untitled)';
|
|
@@ -2311,7 +2331,9 @@ function seoPlanItemLine(item) {
|
|
|
2311
2331
|
planString(item, 'chance'),
|
|
2312
2332
|
].filter(Boolean).join(', ');
|
|
2313
2333
|
const id = planString(item, 'id') ?? '';
|
|
2314
|
-
const
|
|
2334
|
+
const postType = planString(item, 'post_type');
|
|
2335
|
+
const linkMagnet = (item.kind === undefined || item.kind === 'post') && postType !== null && SEO_PLAN_LINK_MAGNET_POST_TYPES.includes(postType) ? '[link magnet] ' : '';
|
|
2336
|
+
const head = ` ${id} ${linkMagnet}${title}`;
|
|
2315
2337
|
const search = keyword && keyword !== title ? ` [search: ${keyword}]` : '';
|
|
2316
2338
|
const where = planString(item, 'existing_url');
|
|
2317
2339
|
const position = typeof item.existing_position === 'number' ? ` (position ${item.existing_position})` : '';
|
|
@@ -2527,9 +2549,8 @@ function seoPlanQueueNote(status) {
|
|
|
2527
2549
|
return null;
|
|
2528
2550
|
return `#${position} in line, starts in about ${eta} min`;
|
|
2529
2551
|
}
|
|
2530
|
-
async function waitForSeoPlan(client, profileId, started) {
|
|
2552
|
+
async function waitForSeoPlan(client, profileId, started, resume) {
|
|
2531
2553
|
const statusPath = `profiles/${encodeURIComponent(profileId)}/seo-plan/status`;
|
|
2532
|
-
const resume = `coauthor seo-plan generate --profile ${profileId} --wait`;
|
|
2533
2554
|
const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
|
|
2534
2555
|
const pollMs = Math.max(waitPollMs(), 0);
|
|
2535
2556
|
let status = planRecord(await client.request({ path: statusPath }));
|
|
@@ -2544,7 +2565,9 @@ async function waitForSeoPlan(client, profileId, started) {
|
|
|
2544
2565
|
status: 'still_running',
|
|
2545
2566
|
exitCode: 2,
|
|
2546
2567
|
resume_command: resume,
|
|
2547
|
-
|
|
2568
|
+
// The resume command reuses this request's Idempotency-Key, so it replays the request instead of
|
|
2569
|
+
// starting (and charging for) a second plan if this one finishes before the agent re-runs it.
|
|
2570
|
+
message: `The plan is still being made${step ? ` (${step})` : ''}. Plans take about 5 to 12 minutes. Keep waiting with: ${resume} (it reuses this request's key, so it never starts a second plan), or check with \`coauthor seo-plan show --profile ${profileId}\`. Don't re-run generate without --idempotency-key: once this plan is ready, that makes a new one.`,
|
|
2548
2571
|
data: (started ?? status),
|
|
2549
2572
|
};
|
|
2550
2573
|
}
|
|
@@ -2591,7 +2614,9 @@ async function runSeoPlanCommand(action, input, client) {
|
|
|
2591
2614
|
throw new Error('--adjust can be at most 2000 characters.');
|
|
2592
2615
|
const wait = getBoolean(input.values, 'wait');
|
|
2593
2616
|
const profileId = await resolveProfileOption(input, client);
|
|
2617
|
+
const resuming = Boolean(getString(input.values, 'idempotency-key')?.trim());
|
|
2594
2618
|
const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
|
|
2619
|
+
const resume = `coauthor seo-plan generate --profile ${profileId}${adjust?.trim() ? ` --adjust ${shellQuote(adjust.trim())}` : ''} --idempotency-key ${shellQuote(idempotencyKey)} --wait`;
|
|
2595
2620
|
let started;
|
|
2596
2621
|
try {
|
|
2597
2622
|
started = await client.request({
|
|
@@ -2603,11 +2628,13 @@ async function runSeoPlanCommand(action, input, client) {
|
|
|
2603
2628
|
}
|
|
2604
2629
|
catch (error) {
|
|
2605
2630
|
// One plan runs per account at a time. When --wait finds this profile's plan already running
|
|
2606
|
-
// (an earlier --wait timed out), join it instead of failing.
|
|
2631
|
+
// (an earlier --wait timed out), join it instead of failing. Resuming with the same key replays
|
|
2632
|
+
// that plan_running answer, so a plan that has finished since returns as ready, not as an error.
|
|
2607
2633
|
if (wait && httpErrorCode(error) === 'plan_running') {
|
|
2608
2634
|
const status = planRecord(await client.request({ path: `profiles/${encodeURIComponent(profileId)}/seo-plan/status` }));
|
|
2609
|
-
if (status.done === false)
|
|
2610
|
-
return waitForSeoPlan(client, profileId, null);
|
|
2635
|
+
if (status.done === false || (resuming && (status.status === 'ready' || status.status === 'failed'))) {
|
|
2636
|
+
return { ...await waitForSeoPlan(client, profileId, null, resume), idempotency_key: idempotencyKey };
|
|
2637
|
+
}
|
|
2611
2638
|
}
|
|
2612
2639
|
throw error;
|
|
2613
2640
|
}
|
|
@@ -2623,7 +2650,7 @@ async function runSeoPlanCommand(action, input, client) {
|
|
|
2623
2650
|
data: started,
|
|
2624
2651
|
};
|
|
2625
2652
|
}
|
|
2626
|
-
const result = await waitForSeoPlan(client, profileId, started);
|
|
2653
|
+
const result = await waitForSeoPlan(client, profileId, started, resume);
|
|
2627
2654
|
return { ...result, idempotency_key: idempotencyKey };
|
|
2628
2655
|
}
|
|
2629
2656
|
if (action === 'monthly-check') {
|
|
@@ -3518,7 +3545,7 @@ export function helpResult(command = []) {
|
|
|
3518
3545
|
' publish thread (supports --idempotency-key)',
|
|
3519
3546
|
' export list|wordpress (supports --idempotency-key)',
|
|
3520
3547
|
' operation list|show|status (publish, export and image generate/edit)',
|
|
3521
|
-
' credits',
|
|
3548
|
+
' credits [<project-id>]',
|
|
3522
3549
|
' share <project-id>',
|
|
3523
3550
|
' models list|preferences show|preferences set',
|
|
3524
3551
|
' skills list|install',
|
|
@@ -3634,7 +3661,7 @@ function commandHelp(command) {
|
|
|
3634
3661
|
].join('\n'),
|
|
3635
3662
|
'seo-plan': [
|
|
3636
3663
|
'Usage: coauthor seo-plan show [--profile <profile-id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage ready-to-buy|comparing|learning] [--chance easy|stretch|long-shot] [--limit <n>] [--json]',
|
|
3637
|
-
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
|
|
3664
|
+
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--idempotency-key <key>] [--json]',
|
|
3638
3665
|
' coauthor seo-plan write <item-id> [--json]',
|
|
3639
3666
|
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
3640
3667
|
' coauthor seo-plan done <item-id> [--undo] [--json]',
|
|
@@ -3643,7 +3670,7 @@ function commandHelp(command) {
|
|
|
3643
3670
|
'',
|
|
3644
3671
|
'SEO content plan: a business-wide keyword plan for a writer profile, built from live search data and the profile\'s website. Without --profile it uses the default profile.',
|
|
3645
3672
|
'show prints the strategy, the Do next moves, counts per kind, and the ideas of one kind (default post). Kinds: post (written post ideas), improve (existing pages to improve), page (page ideas, not blog posts), left_out (searches skipped, with a reason), covered, not_checked.',
|
|
3646
|
-
'generate makes or updates the plan (about 420 credits, most plans 300-500, charged as it runs; the account needs 500 credits remaining to start). --adjust gives a one-line steer. --wait polls for up to 9 minutes, then exits 2 with still_running
|
|
3673
|
+
'generate makes or updates the plan (about 420 credits, most plans 300-500, charged as it runs; the account needs 500 credits remaining to start). --adjust gives a one-line steer. --wait polls for up to 9 minutes, then exits 2 with still_running and a resume_command that reuses the request\'s --idempotency-key, so it keeps waiting without starting a second plan (or check with show). Re-running generate without that key after the plan is ready makes, and charges for, a new plan.',
|
|
3647
3674
|
'write <item-id> opens a project for a post idea, already set up from the plan, and prints its id and the start prompt. Continue with the normal project flow. Writing the same idea again returns the same project.',
|
|
3648
3675
|
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3649
3676
|
'done marks an idea as done (for example after you improved the page); --undo clears the mark. A done idea stays in the plan and stays done when the plan is updated.',
|
|
@@ -3796,9 +3823,10 @@ function commandHelp(command) {
|
|
|
3796
3823
|
'Returns the public read-only link (data.share_url), creating it if needed. Anyone with the link can read the draft.',
|
|
3797
3824
|
].join('\n'),
|
|
3798
3825
|
credits: [
|
|
3799
|
-
'Usage: coauthor credits <project-id> [--json]',
|
|
3826
|
+
'Usage: coauthor credits [<project-id>] [--json]',
|
|
3800
3827
|
'',
|
|
3801
|
-
'Shows the plan, credits used and remaining this period, and the reset date.',
|
|
3828
|
+
'Shows the plan, credits used and remaining this period, and the reset date. Credits belong to the account, so the',
|
|
3829
|
+
'project id is optional: with none (for example right after setup, before any project exists) it reads the account.',
|
|
3802
3830
|
].join('\n'),
|
|
3803
3831
|
'skills install': [
|
|
3804
3832
|
'Usage: coauthor skills install [claude|codex|agents|cursor|all] [--scope user|project] [--force] [--dry-run] [--json]',
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: coauthor
|
|
3
|
-
description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
|
|
3
|
+
description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; make an SEO content plan (which posts to write to rank on Google) and write its ideas; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# CoAuthor
|
|
@@ -12,7 +12,7 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
|
|
|
12
12
|
## Before you start
|
|
13
13
|
|
|
14
14
|
1. `coauthor --version`. If the command is missing: `npm install -g @clickminded/coauthor-cli`.
|
|
15
|
-
2. `coauthor auth status --json`. If `data.hasToken` is false, run `coauthor auth login --no-browser` in the background, give the user the printed URL and code to approve in their browser, and wait for it to finish.
|
|
15
|
+
2. `coauthor auth status --json`. If `data.hasToken` is false, run `coauthor auth login --no-browser` in the background, give the user the printed URL and code to approve in their browser, and wait for it to finish. `coauthor credits --json` confirms the account works and shows the plan, credits left and reset date; it needs no project.
|
|
16
16
|
3. Never print tokens or `~/.coauthor/config.json`. Never ask the user to paste AI provider keys into chat; keys belong in CoAuthor's AI settings.
|
|
17
17
|
|
|
18
18
|
## Rules
|
|
@@ -65,7 +65,7 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
|
|
|
65
65
|
|
|
66
66
|
When the user wants to know what to write about for a business site, or asks for a keyword or content strategy, make a plan instead of guessing topics. A plan reads live search data and the profile's website, then lists post ideas that can win, pages to improve, and page ideas that are not blog posts.
|
|
67
67
|
|
|
68
|
-
- `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; run the
|
|
68
|
+
- `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; to keep waiting, run the `resume_command` it prints (it reuses the request's `--idempotency-key`, so it never starts a second plan) or poll `coauthor seo-plan show --json`. Never re-run `generate` without that key to keep waiting: once the first plan is ready, that makes and charges for a new one.
|
|
69
69
|
- `coauthor seo-plan show --json` reads it (strategy, Do next moves, counts, `--kind post|improve|page|left_out|covered|not_checked`).
|
|
70
70
|
- `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
|
|
71
71
|
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
## Credits
|
|
4
4
|
|
|
5
|
-
`coauthor credits <id> --json` shows the user's plan, this period's allowance, credits used and held by running work, what remains, and when the period resets. Credits reset monthly on the subscription anniversary.
|
|
5
|
+
`coauthor credits --json` (or `coauthor credits <id> --json` for a project; the balance is the account's either way) shows the user's plan, this period's allowance, credits used and held by running work, what remains, and when the period resets. Credits reset monthly on the subscription anniversary.
|
|
6
6
|
|
|
7
7
|
Rough costs, to set expectations before starting:
|
|
8
8
|
|
|
@@ -32,7 +32,7 @@ coauthor seo-plan results [--profile <id>] --json
|
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
- Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
|
|
35
|
-
- `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running
|
|
35
|
+
- `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running` and prints a `resume_command`. Run that to keep waiting: it reuses the request's `--idempotency-key`, so it replays the first request instead of starting a second plan, and returns the plan if it finished in the meantime. You can also poll `coauthor seo-plan show --json` until `plan.status` is `ready`. Don't re-run plain `generate ... --wait` to keep waiting: while the plan runs it joins it, but once the plan is ready it makes (and charges for) a new one.
|
|
36
36
|
- Many plans can be made at once, so a new plan may wait its turn. While `status` is `queued`, the status data carries `queue_position` (1 = next), `queue_eta_minutes` (a rough estimate) and `queue_paused`; the position and estimate are `null` once the plan is running or before the position is known. When `queue_paused` is `true` the plan is waiting for free plans to resume and has no estimate. Tell the user their place in line and keep waiting; the plan starts by itself.
|
|
37
37
|
- A plan can still be the free **preview** a person got from the website (`data.plan.is_preview` is `true`): it holds only the first 10 posts and a few pages to improve, with no monthly check. Running `generate` finishes it into the full plan, which counts as the user's free first plan (`first_plan_free` ignores previews). Say so when the user asks why a plan is short.
|
|
38
38
|
- `--adjust` is a short steer for this run, for example `--adjust "focus on B2B buyers, skip anything about hiring"`. Use it when the user wants a different emphasis. Competitors are found automatically; the user corrects them in the web app.
|
|
@@ -52,6 +52,18 @@ Each item has a `kind`, which decides what you can do with it:
|
|
|
52
52
|
| `covered` | The site already ranks well for it. | Nothing. |
|
|
53
53
|
| `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
|
|
54
54
|
|
|
55
|
+
### Link magnets
|
|
56
|
+
|
|
57
|
+
Some `post` items are **link magnets**: reference pages other sites cite as a source, so each link that comes in makes the whole site stronger and helps its other posts rank. A plan holds at most three, and only when the search data shows that pages like this earn links for this kind of site (many plans have none). A link magnet is a `post` item whose `post_type` is one of:
|
|
58
|
+
|
|
59
|
+
- `stats_hub`: a statistics page that collects current numbers on a topic, each with its source.
|
|
60
|
+
- `regulation_tracker`: a rules or law tracker by state, country or city, with the date it was last checked.
|
|
61
|
+
- `cost_reference`: a price or cost reference, with where each figure comes from.
|
|
62
|
+
|
|
63
|
+
They all have `stage: "Learning"`. `reason` holds the evidence in one line (for example "Pages like this earn links from 50+ other sites."), `note` says what to build, and `top_results` lists the pages that earn links today. `chance` is not an outranking chance for these: do not describe a link magnet as an easy win. In the human output of `show` they are prefixed `[link magnet]`; the web app shows a "Link magnet" badge and a "Pages others link to" section.
|
|
64
|
+
|
|
65
|
+
Write one like any other post with `seo-plan write`. Tell the user why it is on the list ("other sites would cite it"), and warn that it needs current, sourced figures: a link magnet is only worth building if every number is dated and traceable. Do not pick a link magnet for the user over their easier posts unless they ask for link building.
|
|
66
|
+
|
|
55
67
|
Other fields to use when you recommend an idea:
|
|
56
68
|
|
|
57
69
|
- `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
|
|
2
|
+
description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; make an SEO content plan (which posts to write to rank on Google) and write its ideas; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
|
|
3
3
|
alwaysApply: false
|
|
4
4
|
---
|
|
5
5
|
|
|
@@ -14,7 +14,7 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
|
|
|
14
14
|
## Before you start
|
|
15
15
|
|
|
16
16
|
1. `coauthor --version`. If the command is missing: `npm install -g @clickminded/coauthor-cli`.
|
|
17
|
-
2. `coauthor auth status --json`. If `data.hasToken` is false, run `coauthor auth login --no-browser` in the background, give the user the printed URL and code to approve in their browser, and wait for it to finish.
|
|
17
|
+
2. `coauthor auth status --json`. If `data.hasToken` is false, run `coauthor auth login --no-browser` in the background, give the user the printed URL and code to approve in their browser, and wait for it to finish. `coauthor credits --json` confirms the account works and shows the plan, credits left and reset date; it needs no project.
|
|
18
18
|
3. Never print tokens or `~/.coauthor/config.json`. Never ask the user to paste AI provider keys into chat; keys belong in CoAuthor's AI settings.
|
|
19
19
|
|
|
20
20
|
## Rules
|
|
@@ -67,7 +67,7 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
|
|
|
67
67
|
|
|
68
68
|
When the user wants to know what to write about for a business site, or asks for a keyword or content strategy, make a plan instead of guessing topics. A plan reads live search data and the profile's website, then lists post ideas that can win, pages to improve, and page ideas that are not blog posts.
|
|
69
69
|
|
|
70
|
-
- `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; run the
|
|
70
|
+
- `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; to keep waiting, run the `resume_command` it prints (it reuses the request's `--idempotency-key`, so it never starts a second plan) or poll `coauthor seo-plan show --json`. Never re-run `generate` without that key to keep waiting: once the first plan is ready, that makes and charges for a new one.
|
|
71
71
|
- `coauthor seo-plan show --json` reads it (strategy, Do next moves, counts, `--kind post|improve|page|left_out|covered|not_checked`).
|
|
72
72
|
- `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
|
|
73
73
|
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
@@ -271,7 +271,7 @@ SEO mode is rolling out gradually; accounts outside it get `feature_unavailable`
|
|
|
271
271
|
|
|
272
272
|
### Credits
|
|
273
273
|
|
|
274
|
-
`coauthor credits <id> --json` shows the user's plan, this period's allowance, credits used and held by running work, what remains, and when the period resets. Credits reset monthly on the subscription anniversary.
|
|
274
|
+
`coauthor credits --json` (or `coauthor credits <id> --json` for a project; the balance is the account's either way) shows the user's plan, this period's allowance, credits used and held by running work, what remains, and when the period resets. Credits reset monthly on the subscription anniversary.
|
|
275
275
|
|
|
276
276
|
Rough costs, to set expectations before starting:
|
|
277
277
|
|
|
@@ -627,7 +627,7 @@ coauthor seo-plan results [--profile <id>] --json
|
|
|
627
627
|
```
|
|
628
628
|
|
|
629
629
|
- Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
|
|
630
|
-
- `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running
|
|
630
|
+
- `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running` and prints a `resume_command`. Run that to keep waiting: it reuses the request's `--idempotency-key`, so it replays the first request instead of starting a second plan, and returns the plan if it finished in the meantime. You can also poll `coauthor seo-plan show --json` until `plan.status` is `ready`. Don't re-run plain `generate ... --wait` to keep waiting: while the plan runs it joins it, but once the plan is ready it makes (and charges for) a new one.
|
|
631
631
|
- Many plans can be made at once, so a new plan may wait its turn. While `status` is `queued`, the status data carries `queue_position` (1 = next), `queue_eta_minutes` (a rough estimate) and `queue_paused`; the position and estimate are `null` once the plan is running or before the position is known. When `queue_paused` is `true` the plan is waiting for free plans to resume and has no estimate. Tell the user their place in line and keep waiting; the plan starts by itself.
|
|
632
632
|
- A plan can still be the free **preview** a person got from the website (`data.plan.is_preview` is `true`): it holds only the first 10 posts and a few pages to improve, with no monthly check. Running `generate` finishes it into the full plan, which counts as the user's free first plan (`first_plan_free` ignores previews). Say so when the user asks why a plan is short.
|
|
633
633
|
- `--adjust` is a short steer for this run, for example `--adjust "focus on B2B buyers, skip anything about hiring"`. Use it when the user wants a different emphasis. Competitors are found automatically; the user corrects them in the web app.
|
|
@@ -647,6 +647,18 @@ Each item has a `kind`, which decides what you can do with it:
|
|
|
647
647
|
| `covered` | The site already ranks well for it. | Nothing. |
|
|
648
648
|
| `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
|
|
649
649
|
|
|
650
|
+
#### Link magnets
|
|
651
|
+
|
|
652
|
+
Some `post` items are **link magnets**: reference pages other sites cite as a source, so each link that comes in makes the whole site stronger and helps its other posts rank. A plan holds at most three, and only when the search data shows that pages like this earn links for this kind of site (many plans have none). A link magnet is a `post` item whose `post_type` is one of:
|
|
653
|
+
|
|
654
|
+
- `stats_hub`: a statistics page that collects current numbers on a topic, each with its source.
|
|
655
|
+
- `regulation_tracker`: a rules or law tracker by state, country or city, with the date it was last checked.
|
|
656
|
+
- `cost_reference`: a price or cost reference, with where each figure comes from.
|
|
657
|
+
|
|
658
|
+
They all have `stage: "Learning"`. `reason` holds the evidence in one line (for example "Pages like this earn links from 50+ other sites."), `note` says what to build, and `top_results` lists the pages that earn links today. `chance` is not an outranking chance for these: do not describe a link magnet as an easy win. In the human output of `show` they are prefixed `[link magnet]`; the web app shows a "Link magnet" badge and a "Pages others link to" section.
|
|
659
|
+
|
|
660
|
+
Write one like any other post with `seo-plan write`. Tell the user why it is on the list ("other sites would cite it"), and warn that it needs current, sourced figures: a link magnet is only worth building if every number is dated and traceable. Do not pick a link magnet for the user over their easier posts unless they ask for link building.
|
|
661
|
+
|
|
650
662
|
Other fields to use when you recommend an idea:
|
|
651
663
|
|
|
652
664
|
- `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.
|