@clickminded/coauthor-cli 0.0.22 → 0.0.23
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 +61 -175
- package/dist/commands.js +269 -86
- package/dist/parser.js +1 -0
- package/package.json +1 -1
- package/scripts/build-cursor-rule.mjs +58 -0
- package/scripts/postinstall.mjs +60 -48
- package/scripts/verify-skill-sync.mjs +50 -42
- package/skills/coauthor/SKILL.md +62 -0
- package/skills/coauthor/references/brief-and-contract.md +151 -0
- package/skills/coauthor/references/credits-and-plans.md +26 -0
- package/skills/coauthor/references/editing-drafts.md +59 -0
- package/skills/coauthor/references/images-and-social.md +28 -0
- package/skills/coauthor/references/publishing-and-export.md +37 -0
- package/skills/coauthor/references/troubleshooting.md +45 -0
- package/skills/cursor/coauthor-cli.mdc +322 -139
- package/skills/agents/SKILL.md +0 -274
- package/skills/claude/SKILL.md +0 -274
- package/skills/codex/SKILL.md +0 -274
|
@@ -1,58 +1,96 @@
|
|
|
1
1
|
---
|
|
2
|
-
description:
|
|
3
|
-
alwaysApply:
|
|
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.
|
|
3
|
+
alwaysApply: false
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
-
|
|
36
|
-
|
|
37
|
-
- `
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
6
|
+
<!-- Generated from skills/coauthor by scripts/build-cursor-rule.mjs. Do not edit by hand. -->
|
|
7
|
+
|
|
8
|
+
# CoAuthor
|
|
9
|
+
|
|
10
|
+
CoAuthor turns a brief into a researched, cited article in the user's voice:
|
|
11
|
+
brief → outline → research plan → research → draft → images → edits → export.
|
|
12
|
+
You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the user's editor**: answer CoAuthor's questions from what you know, review each checkpoint critically, and bring the user in only for what you cannot know or decide.
|
|
13
|
+
|
|
14
|
+
## Before you start
|
|
15
|
+
|
|
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.
|
|
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
|
+
|
|
20
|
+
## Rules
|
|
21
|
+
|
|
22
|
+
- Always pass `--json` and read fields from the output. Failures arrive on stderr as JSON with `code`, `http_status`, and `details`.
|
|
23
|
+
- Keep each foreground command under your shell's time limit (Claude Code: 10 minutes). Prefix waiting commands with `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000`. If a command returns `timed_out` or `still_running`, run the resume or show command it gives you. Never start the same step twice.
|
|
24
|
+
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`.
|
|
25
|
+
- Every blocked or paused status says what to do next. Follow it instead of retrying (see "When something stops").
|
|
26
|
+
- Once a draft exists, do not save, generate, or approve the brief, outline, or research plan unless the user wants to restart the piece: that marks the draft stale. Edit the draft instead.
|
|
27
|
+
- Never send markdown to `draft save`.
|
|
28
|
+
|
|
29
|
+
## Write a piece
|
|
30
|
+
|
|
31
|
+
Typical timing: brief and outline under a minute; research and draft 3–10 minutes (deep research can take 20+); images about 20 seconds each; a revision 15–40 seconds. A typical article uses about 300 credits.
|
|
32
|
+
|
|
33
|
+
1. **Brief.** Gather topic, audience, angle, core promise, length, must-include points, and sources from the conversation and your context (the repo, docs, the user's site). Ask the user only what you cannot infer, in one message of at most 2–3 questions. Write the contract to a file (schema, field guide, and examples: `references/brief-and-contract.md`), then:
|
|
34
|
+
`coauthor project create --title "..." --contract @brief.json --json` → `data.project.id`
|
|
35
|
+
2. **Brief review.** `coauthor workflow run <id> --target contract --briefing-mode strict --json`. `status: "completed"` with no questions means the brief passed and is now approved. If `status` is `needs_clarification`, answer `data.clarification_questions` from your context, update the file, `coauthor contract save <id> --data @brief.json --json`, and run again. For a deeper interview, let CoAuthor question you: `coauthor chat <id> --stage contract --message "Interview me about this brief before we outline." --json`, read `data.text`, and reply the same way. Pass to the user only questions about their opinions, business facts, numbers, or risk tolerance.
|
|
36
|
+
3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it against the brief: every section serves the core promise, must-includes are covered, the order builds, nothing is generic or repeated. To change it, ask CoAuthor (`coauthor chat <id> --stage outline --message "Merge sections 3 and 4; replace the conclusion with a checklist." --json`) or save the complete edited list (`coauthor outline save <id> --data @outline.json --json` with `{"sections":[...]}`; omitted sections are removed). **Chat summaries can be wrong: after every chat edit, re-read with `coauthor outline show <id> --json` (sections are in `data.artifact`) and fix anything that didn't land with `outline save`.** Then `coauthor outline approve <id> --json`. If the user asked to see the outline, show it to them here and wait.
|
|
37
|
+
4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`; `research-plan show` returns them in `data.artifact`). Check every section has a task and every claim that needs proof points at the right sources, including URLs the user gave you. Adjust with `chat --stage research-plan` (then re-read) or `research-plan save` with `{"research_tasks":[...]}`, then `coauthor research-plan approve <id> --json`.
|
|
38
|
+
5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
|
|
39
|
+
6. **Quality pass.** `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
|
|
40
|
+
7. **Images.** `coauthor image list <id> --json`, then for each placeholder `coauthor image generate <id> --placeholder-id <placeholder id> --json` (the `id` UUID, not `placeholder_id`), then poll `coauthor image status <id> --json` until none are generating. CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`.
|
|
41
|
+
8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
|
|
42
|
+
9. **Deliver.** Give the user the final markdown (or `--format html`), a short decision log (what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). With their yes: share link, WordPress export, or X thread (`references/publishing-and-export.md`).
|
|
43
|
+
|
|
44
|
+
## When something stops
|
|
45
|
+
|
|
46
|
+
| Status or code | What to do |
|
|
47
|
+
| --- | --- |
|
|
48
|
+
| `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. |
|
|
49
|
+
| `timed_out`, `still_running` | Run the resume or show command in the output. Do not restart the step. |
|
|
50
|
+
| `research_structuring` | Normal after research. Keep waiting or resume toward draft. |
|
|
51
|
+
| `research_running_stale` | Research progress stopped for 30+ minutes. Show the user `coauthor research structured <id> --json` and ask before `coauthor workflow rewind <id> --target research --json`, which discards research done so far. |
|
|
52
|
+
| `credits_exhausted` | Tell the user `reset_at` and what remains. Resume after the reset. |
|
|
53
|
+
| `requires_key` | The user adds a provider key in CoAuthor's AI settings, then resume. |
|
|
54
|
+
| `stale_draft` | Someone changed the draft. Re-read it and reapply your edit. |
|
|
55
|
+
| `user_recently_editing` | The user is typing in the browser. Wait or ask; use `--force` only with their OK. |
|
|
56
|
+
| `revision_pending` | Apply or discard the open revision first. |
|
|
57
|
+
| `revise_unavailable` | Edit the draft directly with `draft get` and `draft save`. |
|
|
58
|
+
| `coauthor_access_required` | The CoAuthor subscription is inactive. Tell the user. |
|
|
59
|
+
|
|
60
|
+
Everything else, including auth problems: `references/troubleshooting.md`. Credits, plans, and models: `references/credits-and-plans.md`.
|
|
61
|
+
|
|
62
|
+
## Not in the CLI yet
|
|
63
|
+
|
|
64
|
+
Choosing a writer profile (projects use the profile most recently selected in the web app), uploading source documents (put URLs in the brief instead), adding more images than CoAuthor planned, LinkedIn, Facebook, and email versions, slideshows, and video. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
65
|
+
|
|
66
|
+
# Reference sections
|
|
67
|
+
|
|
68
|
+
The `references/*.md` files mentioned above are included below.
|
|
69
|
+
|
|
70
|
+
## references/brief-and-contract.md
|
|
71
|
+
|
|
72
|
+
## Brief and contract
|
|
73
|
+
|
|
74
|
+
The contract is CoAuthor's editorial brief. Everything downstream (outline, research, draft, images) is planned from it, so a sharp contract is the cheapest way to a good article.
|
|
75
|
+
|
|
76
|
+
Create a project with it:
|
|
77
|
+
|
|
78
|
+
```sh
|
|
79
|
+
coauthor project create --title "Working title" --contract @brief.json --json
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
All fields are optional and omitted ones get defaults, but always include at least `topic`, `target_audience`, `core_promise`, and either `angle` or `additional_editorial_guidance`. `--topic` and `--audience` flags fill those fields when the contract leaves them empty. Keep `--topic` plain prose; never put JSON in it.
|
|
83
|
+
|
|
84
|
+
### Writing a sharp brief
|
|
85
|
+
|
|
86
|
+
- **Angle over topic.** "Google Business Profile descriptions" is a topic. "Most descriptions fail Google's rules in the first sentence; here is a 20-minute fix" is an angle. Push for the specific claim the piece will make.
|
|
87
|
+
- **Name the reader.** Who they are, what they already know, and what they will do after reading.
|
|
88
|
+
- **Promise an outcome.** `core_promise` is what the reader can understand, decide, or do afterwards.
|
|
89
|
+
- **Put the user's sources in the brief.** URLs the user gives you go in `citation_expectations` (sources to cite), `must_include` (facts that must appear), or `liked_examples` (pieces to emulate). CoAuthor's research reads them.
|
|
90
|
+
- **Hard rules go in `non_negotiables`**, softer preferences in `must_avoid` and `style_rules`, and facts that must survive editing verbatim in `must_not_change`.
|
|
91
|
+
- **Record what you assumed** in `confidence_notes`, so the user and CoAuthor can see where the brief is uncertain.
|
|
92
|
+
|
|
93
|
+
### Schema
|
|
56
94
|
|
|
57
95
|
```ts
|
|
58
96
|
{
|
|
@@ -116,8 +154,7 @@ CoAuthor artifacts form a dependency chain: contract/brief -> outline -> researc
|
|
|
116
154
|
|
|
117
155
|
- Use `reading_commitment.kind: "preset"` with a preset id for quick length choices; use `"custom"` with explicit `length_guidance` when the user gives a custom range.
|
|
118
156
|
- Use top-level `canonical_entities`, `outline_seed`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`. A legacy nested `handoff` object may be normalized, but top-level fields are clearer for agents.
|
|
119
|
-
|
|
120
|
-
## Editorial Contract Field Guidance
|
|
157
|
+
### Field guide
|
|
121
158
|
|
|
122
159
|
- `topic`: The concrete subject or assignment. Include the search keyword, product, debate, or source brief if that is the true starting point.
|
|
123
160
|
- `angle`: The editorial thesis or framing. Use this to explain what makes this piece different from a generic article on the same topic.
|
|
@@ -145,105 +182,251 @@ CoAuthor artifacts form a dependency chain: contract/brief -> outline -> researc
|
|
|
145
182
|
- `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
|
|
146
183
|
- `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
|
|
147
184
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
Deep SEO comparison guide:
|
|
185
|
+
### Example: practical B2B guide
|
|
151
186
|
|
|
152
187
|
```json
|
|
153
188
|
{
|
|
154
|
-
"topic": "
|
|
155
|
-
"angle": "
|
|
156
|
-
"target_audience": "
|
|
157
|
-
"core_promise": "
|
|
158
|
-
"format": "
|
|
159
|
-
"reading_commitment": { "kind": "
|
|
160
|
-
"
|
|
161
|
-
"
|
|
162
|
-
"
|
|
163
|
-
"
|
|
164
|
-
"
|
|
165
|
-
"
|
|
166
|
-
"
|
|
167
|
-
"
|
|
168
|
-
"editorial_profile": { "tone": "balanced", "form": "guide", "depth": "deep", "humor": "none", "section_length": "adaptive", "cadence": "moderate", "notes": "Long-form SEO comparison guide; practical, fair, and category-aware." },
|
|
169
|
-
"canonical_entities": [
|
|
170
|
-
{ "actor_key": "clickminded_newsletter_generator", "character_name": "ClickMinded Newsletter Generator", "role_title": "AI newsletter generator and production workflow", "description": "A newsletter production layer. It is not an ESP.", "aliases": ["ClickMinded Newsletter Generator", "ClickMinded"], "must_preserve": true },
|
|
171
|
-
{ "actor_key": "mailchimp", "character_name": "Mailchimp", "role_title": "Email marketing platform / ESP", "description": "Email marketing software for list management, sending, automations, forms, templates, analytics, and related ESP functions.", "aliases": ["Mailchimp"], "must_preserve": true }
|
|
172
|
-
],
|
|
173
|
-
"outline_seed": [
|
|
174
|
-
{ "id": "intro_quick_comparison", "heading": "The Best Mailchimp Alternatives in 2026", "intent": "Satisfy core search intent quickly and clarify replacement versus production workflow.", "must_include_points": ["Primary keyword in H1 and intro", "Clarify that some tools replace Mailchimp and ClickMinded complements it by solving production"], "required_actor_keys": ["mailchimp", "clickminded_newsletter_generator"], "notes": "" }
|
|
175
|
-
],
|
|
176
|
-
"style_rules": ["Use Markdown headings and tables where helpful.", "Keep ClickMinded category-accurate and honest."],
|
|
177
|
-
"must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
|
|
178
|
-
"structure_preference": "Preserve the same 10-section structure from the existing draft while expanding depth and word count.",
|
|
179
|
-
"confidence_notes": "Based on a saved draft expansion request and a successful research run."
|
|
189
|
+
"topic": "How small accounting firms can cut month-end close from ten days to five",
|
|
190
|
+
"angle": "The delay is rarely the accounting work; it is waiting on client documents. Fix the intake process first.",
|
|
191
|
+
"target_audience": "Owners of 3-15 person accounting and bookkeeping firms who run month-end close for small-business clients.",
|
|
192
|
+
"core_promise": "Readers leave with a five-step intake process and a client message template they can use this month.",
|
|
193
|
+
"format": "how-to guide",
|
|
194
|
+
"reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
|
|
195
|
+
"audience_knowledge_assumptions": "Knows close procedures and common accounting software; has not formalized client intake.",
|
|
196
|
+
"must_include": ["A day-by-day close calendar", "A copy-paste client reminder email", "How to handle clients who send documents late"],
|
|
197
|
+
"must_avoid": ["Software vendor comparisons", "Generic productivity advice"],
|
|
198
|
+
"non_negotiables": ["Every time-saving claim is tied to a concrete step, not a statistic without a source."],
|
|
199
|
+
"citation_expectations": ["Cite primary sources for any statistic about close times."],
|
|
200
|
+
"editorial_profile": { "tone": "balanced", "form": "guide", "depth": "standard", "humor": "low", "section_length": "mostly_short", "cadence": "tight" },
|
|
201
|
+
"style_rules": ["Short paragraphs.", "Second person.", "Use numbered steps for the process."],
|
|
202
|
+
"confidence_notes": "Firm size and the ten-day baseline come from the user; the five-step process is the assistant's proposal."
|
|
180
203
|
}
|
|
181
204
|
```
|
|
182
205
|
|
|
183
|
-
|
|
206
|
+
### Example: short opinion piece
|
|
184
207
|
|
|
185
208
|
```json
|
|
186
209
|
{
|
|
187
|
-
"topic": "
|
|
188
|
-
"angle": "
|
|
189
|
-
"target_audience": "
|
|
190
|
-
"core_promise": "
|
|
191
|
-
"format": "
|
|
192
|
-
"reading_commitment": { "kind": "
|
|
193
|
-
"
|
|
194
|
-
"must_include": ["
|
|
195
|
-
"must_avoid": ["
|
|
196
|
-
"
|
|
197
|
-
"
|
|
198
|
-
"liked_examples": ["Zapier alternatives posts for skimmable structure and practical recommendations.", "MailerLite comparison page for direct competitor positioning."],
|
|
199
|
-
"rejected_examples": ["Thin SEO listicles that merely paraphrase feature pages without judgment.", "Vendor pages that pretend their tool is best for every use case."],
|
|
200
|
-
"editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Satisfy search intent first, then make the production-workflow insight feel obvious." },
|
|
201
|
-
"style_rules": ["Use short paragraphs.", "Use clear H2s/H3s matching search intent."],
|
|
202
|
-
"must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
|
|
203
|
-
"structure_preference": "Comparison/listicle with a strategic bridge section and a dedicated ClickMinded companion-workflow section.",
|
|
204
|
-
"confidence_notes": "Created from ClickMinded product context and SERP research."
|
|
210
|
+
"topic": "Why remote teams should stop recording every meeting",
|
|
211
|
+
"angle": "Recording everything feels transparent but kills candor and creates hours of footage nobody watches; record decisions, not discussions.",
|
|
212
|
+
"target_audience": "Managers of remote or hybrid teams of 5-50 people.",
|
|
213
|
+
"core_promise": "Readers get a simple rule for what to record and what to write down instead.",
|
|
214
|
+
"format": "opinion essay",
|
|
215
|
+
"reading_commitment": { "kind": "custom", "preset_id": null, "source": "user_explicit" },
|
|
216
|
+
"length_guidance": { "min_words": 700, "target_words": 900, "max_words": 1100 },
|
|
217
|
+
"must_include": ["A one-sentence rule the reader can adopt", "One concrete example of a decision log entry"],
|
|
218
|
+
"must_avoid": ["Strawmanning teams that record everything", "Unsourced statistics"],
|
|
219
|
+
"editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "notes": "Confident and direct, but fair to the opposing view." },
|
|
220
|
+
"style_rules": ["First person is fine.", "No hedging on the core argument."]
|
|
205
221
|
}
|
|
206
222
|
```
|
|
207
223
|
|
|
208
|
-
|
|
224
|
+
## references/credits-and-plans.md
|
|
225
|
+
|
|
226
|
+
## Credits, plans, and models
|
|
227
|
+
|
|
228
|
+
### Credits
|
|
229
|
+
|
|
230
|
+
`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.
|
|
231
|
+
|
|
232
|
+
Rough costs, to set expectations before starting:
|
|
233
|
+
|
|
234
|
+
- A complete article (brief through draft) is typically about 300 credits.
|
|
235
|
+
- Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
|
|
236
|
+
- Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
|
|
237
|
+
|
|
238
|
+
Tell the user the expected cost before large or repeated work, and report credits used at the end.
|
|
239
|
+
|
|
240
|
+
### When credits run out
|
|
241
|
+
|
|
242
|
+
- **Starter:** work pauses (`credits_exhausted`) and resumes after the reset. Starter can't use the user's own AI provider keys.
|
|
243
|
+
- **Pro:** CoAuthor can continue with the user's own provider key once included credits are used (`requires_key` if none is set). The user adds keys in CoAuthor's AI settings, never in chat.
|
|
244
|
+
|
|
245
|
+
Paused work is saved. Resume it with `coauthor workflow resume <id> --wait --json`.
|
|
246
|
+
|
|
247
|
+
### Models
|
|
248
|
+
|
|
249
|
+
- `coauthor models list` shows the planning and writing models available.
|
|
250
|
+
- Override for one run with `--planning-model <id>` (outline, research plan) and `--writing-model <id>` (draft, thread). There is no global `--model`.
|
|
251
|
+
- `coauthor models preferences show` and `coauthor models preferences set --planning-model <id> --writing-model <id>` read and change the saved defaults. Only change saved defaults when the user asks.
|
|
252
|
+
|
|
253
|
+
## references/editing-drafts.md
|
|
254
|
+
|
|
255
|
+
## Editing a draft
|
|
256
|
+
|
|
257
|
+
There are two ways to change a generated draft. Both work whether or not the user has opened the draft in CoAuthor's web editor. Do not use `coauthor chat --stage draft` to edit; use one of these.
|
|
258
|
+
|
|
259
|
+
### 1. Revise by instruction (prose changes)
|
|
260
|
+
|
|
261
|
+
CoAuthor's own editor rewrites the draft in the project's voice and proposes the change for review.
|
|
262
|
+
|
|
263
|
+
```sh
|
|
264
|
+
coauthor draft revise <id> --instruction "Cut the intro to two sentences and lead with the 750-character limit." --wait --json
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
- The result's `data.groups` lists each proposed change with `before_markdown` and `after_markdown`. Review every group against the brief: is it accurate, in voice, and limited to what was asked?
|
|
268
|
+
- Apply all groups: `coauthor draft revision apply <id> <revision-id> --json`. Keep only some with `--accept <group id>,<group id>`, or all but some with `--reject <group id>`, copying the ids (`review_…`) from `data.groups[].id`. Groups not named in `--accept` are dropped. Drop the whole revision with `coauthor draft revision discard <id> <revision-id> --json`.
|
|
269
|
+
- `status: "no_changes"` usually means CoAuthor asked a question instead of guessing. Read `data.assistant_message`, then run `draft revise` again with a clearer instruction.
|
|
270
|
+
- Name the place precisely ("the paragraph after the 'Write the first line' heading") and give numbers for cuts ("under 60 words"). Vague targets get a clarifying question back, and a vague "tighten" changes little.
|
|
271
|
+
- One revision can be open on a draft at a time, and an open one blocks the user's saves in the browser. Always apply or discard it. `revision_pending` means one is already open.
|
|
272
|
+
- If `--wait` returns `still_running`, check again with `coauthor draft revision show <id> <revision-id> --json`.
|
|
273
|
+
- `revise_unavailable` means this account cannot revise by instruction yet; use a direct edit.
|
|
274
|
+
|
|
275
|
+
### 2. Direct edit (exact text you already have)
|
|
276
|
+
|
|
277
|
+
1. `coauthor draft get <id> --format json --json`. Keep `data.document_id`, `data.version_number`, and `data.content_hash` (null on some drafts).
|
|
278
|
+
2. Edit nodes inside `data.content`, a ProseMirror document: `{"type":"doc","content":[...]}` of `heading`, `paragraph`, `bulletList`, `orderedList`, `blockquote`, and `imagePlaceholder` nodes, with text in `{"type":"text","text":"...","marks":[...]}`.
|
|
279
|
+
- Keep node attributes (ids) on nodes you keep, and keep `imagePlaceholder` nodes unless the user wants the image removed.
|
|
280
|
+
- Put inline code in a `code` mark and links in a `link` mark rather than typing markdown characters; literal `*`, `_`, and backticks are shown as typed.
|
|
281
|
+
- Keep one `orderedList` per list. A paragraph between items splits it into lists that each restart at 1; put extra paragraphs inside the `listItem` instead.
|
|
282
|
+
3. Write the payload to a file and save it:
|
|
209
283
|
|
|
210
284
|
```json
|
|
211
285
|
{
|
|
212
|
-
"
|
|
213
|
-
"
|
|
214
|
-
"
|
|
215
|
-
"
|
|
216
|
-
"format": "blog post",
|
|
217
|
-
"reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
|
|
218
|
-
"length_guidance": { "min_words": 1200, "target_words": 1500, "max_words": 1800 },
|
|
219
|
-
"must_include": ["Confrontational second-person opening hook about outrage at billionaire spending.", "Name external locus of control explicitly.", "Central reframe: stop outsourcing your sense of agency to what someone else does with their money."],
|
|
220
|
-
"must_avoid": ["Do not turn this into a money-printing, COVID-spending, or MMT thread.", "Do not use the word communism or slippery-slope-to-communism phrasing.", "Do not soften, hedge, or both-sides the core argument."],
|
|
221
|
-
"citation_expectations": ["Cost of a single NYC subway station.", "Annual US Medicare cost and approximate Elon Musk net worth for scale comparison.", "Rolex foundation ownership and limits on public profit claims."],
|
|
222
|
-
"editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Reasoned and persuasive; do not make it a pure political rant or strawman the opposing view." },
|
|
223
|
-
"style_rules": ["Confident first-person or direct second-person OK.", "No hedge-everything academic tone.", "Use concrete scale comparisons rather than abstract moralizing."]
|
|
286
|
+
"document_id": "<data.document_id>",
|
|
287
|
+
"expected_base_version": <data.version_number>,
|
|
288
|
+
"expected_content_hash": "<data.content_hash, if not null>",
|
|
289
|
+
"content": { "type": "doc", "content": [ ... ] }
|
|
224
290
|
}
|
|
225
291
|
```
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
-
|
|
238
|
-
-
|
|
239
|
-
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
-
|
|
246
|
-
-
|
|
247
|
-
-
|
|
248
|
-
|
|
249
|
-
|
|
292
|
+
|
|
293
|
+
```sh
|
|
294
|
+
coauthor draft save <id> --data @payload.json --json
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
4. Re-read with `coauthor draft get <id> --format markdown --json` to confirm the change.
|
|
298
|
+
|
|
299
|
+
Never send markdown or plain text as `content`; it is rejected. `--data @-` reads the payload from stdin.
|
|
300
|
+
|
|
301
|
+
### Conflicts
|
|
302
|
+
|
|
303
|
+
- `stale_draft`: the draft changed since you read it (`details.current` has the new version). Re-read, reapply your edit to the new content, and save. Never resend the old payload.
|
|
304
|
+
- `user_recently_editing`: the user saved in the browser in the last 90 seconds and may still be typing. Wait, or ask them; pass `--force` only with their OK.
|
|
305
|
+
- `review_pending` or `document_locked`: an AI review or edit is in progress in the editor. Wait for it, or apply or discard it.
|
|
306
|
+
|
|
307
|
+
### Don't restart the piece by accident
|
|
308
|
+
|
|
309
|
+
CoAuthor's stages form a chain: brief → outline → research plan → research → draft. Saving, generating, or approving an upstream stage after a draft exists marks the draft stale and can hide it in the web app.
|
|
310
|
+
|
|
311
|
+
- Before touching the brief, outline, or research plan on an existing project, check `coauthor workflow status <id> --json`. If the state is `draft_generated` or `editing`, edit the draft instead.
|
|
312
|
+
- Do not copy constraints you discover while editing back into the brief or outline "for the record".
|
|
313
|
+
- Change an upstream stage only when the user wants to restart from it and understands the draft will be regenerated. First save a copy with `coauthor draft get <id> --format json --json`, then finish the chain with `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`.
|
|
314
|
+
|
|
315
|
+
## references/images-and-social.md
|
|
316
|
+
|
|
317
|
+
## Images and social posts
|
|
318
|
+
|
|
319
|
+
### Article images
|
|
320
|
+
|
|
321
|
+
Draft generation plans image placeholders, including a featured image (`is_featured: true`) when one fits. It does not generate them. CoAuthor decides how many images a piece gets, sometimes only the featured image, and the CLI cannot add more placeholders. If the user expected several images, tell them more can be added in the web app editor.
|
|
322
|
+
|
|
323
|
+
1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
|
|
324
|
+
2. Generate each one: `coauthor image generate <id> --placeholder-id <id UUID> --json`. Use the `id` UUID; the descriptive `placeholder_id` string is not accepted. Optional: `--grounding-mode <mode>`, `--image-generation-model <id>`.
|
|
325
|
+
3. Generation is asynchronous. Poll `coauthor image status <id> --json` every 15–30 seconds until no placeholder's latest image is `generating`. Each takes about 20 seconds.
|
|
326
|
+
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
327
|
+
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
328
|
+
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
329
|
+
- Prices, dates, and text inside the image must match the article.
|
|
330
|
+
5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --json`, then poll `image status` again. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
|
|
331
|
+
6. Rewrite the SEO metadata for every generated image: `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json`. This is required, not polish: the stored alt text was written from the plan before the image existed and often describes things that aren't in the picture. Alt text must describe what is actually visible.
|
|
332
|
+
|
|
333
|
+
Images cost credits each time they are generated or edited, so check the brief and placeholder purpose before regenerating.
|
|
334
|
+
|
|
335
|
+
### X thread
|
|
336
|
+
|
|
337
|
+
1. `coauthor thread generate <id> --json` writes a thread from the saved draft (optional `--writing-model <id>`).
|
|
338
|
+
2. `coauthor thread show <id> --json` returns `data.thread.posts` (`[{ "id", "text", "image_placeholder_id" }]`) and the user's connected X accounts in `data.social_accounts`.
|
|
339
|
+
3. To edit, save the complete post list: `coauthor thread save <id> --data @thread.json --json` with `{"posts":[...]}`. Include `"destination_url"` to change the link, and `"selected_social_account_id"` to choose the X account (it is kept when you leave it out).
|
|
340
|
+
4. Publishing posts to X immediately and publicly. It needs the user's explicit yes and a token with publish permission (`coauthor auth login --with-publish`): `coauthor publish thread <id> --yes --json`.
|
|
341
|
+
|
|
342
|
+
### Other formats
|
|
343
|
+
|
|
344
|
+
LinkedIn, Facebook, and email newsletter versions, carousel slideshows, and short videos are generated in the CoAuthor web app (open the project and use Promote). The CLI cannot create them yet.
|
|
345
|
+
|
|
346
|
+
## references/publishing-and-export.md
|
|
347
|
+
|
|
348
|
+
## Publishing and export
|
|
349
|
+
|
|
350
|
+
### Get the finished draft
|
|
351
|
+
|
|
352
|
+
```sh
|
|
353
|
+
coauthor draft get <id> --format markdown --json # data.markdown, images as markdown image links
|
|
354
|
+
coauthor draft get <id> --format html --json # data.html, images as <img> tags
|
|
355
|
+
coauthor draft get <id> --format text --json # data.text, plain text with image URLs
|
|
356
|
+
coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
The markdown and HTML have no H1: they start with the featured image (once generated) and then the first section. Add the title yourself from `coauthor project show <id> --json` (`data.project.title`) when you hand over a file. Images appear only after they have been generated, and their URLs are public, so the markdown can be pasted anywhere.
|
|
360
|
+
|
|
361
|
+
### Share link (public)
|
|
362
|
+
|
|
363
|
+
`coauthor share <id> --json` returns `data.share_url`, a public read-only page anyone with the link can open. Create one only when the user asks for a link. Calling it again returns the same link.
|
|
364
|
+
|
|
365
|
+
### WordPress
|
|
366
|
+
|
|
367
|
+
Export creates a **draft post** in the user's WordPress site (it is not published), with images and SEO metadata.
|
|
368
|
+
|
|
369
|
+
1. The token needs publish permission. If an export fails with `insufficient_scope`, have the user run `coauthor auth login --with-publish` (in the background with `--no-browser`; they approve in the browser).
|
|
370
|
+
2. With the user's yes:
|
|
371
|
+
`coauthor export wordpress <id> --yes --slug <url-slug> --json`
|
|
372
|
+
3. If they have several WordPress sites connected, the error `wordpress_connection_required` lists them in `details.connections` (`id`, `label`, `site_base_url`). Ask which one, then add `--connection-id <id>`.
|
|
373
|
+
4. `wordpress_not_connected` means no site is connected yet. The user connects one in CoAuthor's settings (Publishing).
|
|
374
|
+
5. Give the user `wordpress_edit_url` from the response (also `wordpress_link`) so they can review and publish the post in WordPress.
|
|
375
|
+
|
|
376
|
+
`coauthor export list <id> --json` shows past exports.
|
|
377
|
+
|
|
378
|
+
### X thread
|
|
379
|
+
|
|
380
|
+
See `references/images-and-social.md`. Publishing a thread posts immediately and needs the user's yes.
|
|
381
|
+
|
|
382
|
+
### If a live action's result is unclear
|
|
383
|
+
|
|
384
|
+
After a network error or an unclear result on an export or publish, do not run it again straight away. Check `coauthor operation list --json` for the operation and its status first, then decide.
|
|
385
|
+
|
|
386
|
+
## references/troubleshooting.md
|
|
387
|
+
|
|
388
|
+
## Troubleshooting
|
|
389
|
+
|
|
390
|
+
Every failure prints JSON on stderr with `ok: false`, `error` (a readable message), `code`, `http_status`, and often `details` with the current state and next commands. Paused or blocked work is saved; nothing needs to be redone from scratch.
|
|
391
|
+
|
|
392
|
+
### Statuses and codes
|
|
393
|
+
|
|
394
|
+
| Status or code | Meaning | What to do |
|
|
395
|
+
| --- | --- | --- |
|
|
396
|
+
| `needs_clarification` | The brief is too thin to outline well. | Answer `data.clarification_questions` from your context (ask the user only what you can't know), update the contract, run again. |
|
|
397
|
+
| `timed_out` | The wait window ended; the work is still running on CoAuthor's side. | Run the resume command in `data.next_commands`, usually `coauthor workflow resume <id> --target draft --wait --json`. |
|
|
398
|
+
| `still_running` | Same, for a draft revision. | `coauthor draft revision show <id> <revision-id> --json`. |
|
|
399
|
+
| `research_structuring` | Research finished and is being organized for drafting. Normal. | Keep waiting or resume toward draft. Don't rewind. |
|
|
400
|
+
| `research_running_stale` | Research progress has not changed for 30+ minutes. | Check `coauthor research status <id> --json` a few minutes apart and look at `coauthor research structured <id> --json`. Rewinding (`coauthor workflow rewind <id> --target research --json`) discards the research done so far and costs credits to redo, so ask the user first. |
|
|
401
|
+
| `research_run_state_mismatch` | Research run and project state disagree. | Report it and use the `recovery_commands` in the output. |
|
|
402
|
+
| `blocked_by_research` | A draft was requested while research is still running. | Use the `recovery_commands`; usually just resume toward draft. |
|
|
403
|
+
| `credits_exhausted` | The plan's credits for this period are used up. Work is paused and saved. | Tell the user `reset_at`, `used`, and `remaining`. Resume with `coauthor workflow resume <id> --wait --json` after the reset. See `references/credits-and-plans.md`. |
|
|
404
|
+
| `requires_key` | Included credits are used up and the plan can continue with the user's own AI provider key. | The user adds a key in CoAuthor's AI settings (`settings_url`); never ask for it in chat. Then run `resume_command`. |
|
|
405
|
+
| `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
|
|
406
|
+
| `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
|
|
407
|
+
| `entitlement_sync_unavailable` | Subscription status couldn't be checked right now. | Don't retry in a loop. Try again in a few minutes. |
|
|
408
|
+
| `stale_draft` | The draft changed after you read it. | Re-read with `draft get`, reapply your edit, save. |
|
|
409
|
+
| `user_recently_editing` | The user saved in the browser in the last 90 seconds. | Wait, or ask them. `--force` only with their OK. |
|
|
410
|
+
| `review_pending`, `document_locked` | An AI review or edit is in progress in the editor. | Wait, or apply or discard it. |
|
|
411
|
+
| `revision_pending` | Another draft revision is open. | Apply or discard it (`details.revision_id`). |
|
|
412
|
+
| `revise_unavailable` | Revise by instruction isn't available on this account. | Use a direct edit (`references/editing-drafts.md`). |
|
|
413
|
+
| `invalid_document` | `draft save` content isn't an editor document. | Send the edited `data.content` from `draft get --format json`, never markdown. |
|
|
414
|
+
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
415
|
+
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
416
|
+
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
417
|
+
|
|
418
|
+
### Sign-in
|
|
419
|
+
|
|
420
|
+
- `Missing bearer token` or HTTP 401: run `coauthor auth login --no-browser` in the background and give the user the printed URL and code. The login waits up to 10 minutes for approval.
|
|
421
|
+
- `coauthor auth status --json` shows which account and permissions the saved token has.
|
|
422
|
+
- `coauthor auth logout` revokes the token on the server, then removes it locally.
|
|
423
|
+
|
|
424
|
+
### Waiting
|
|
425
|
+
|
|
426
|
+
- `COAUTHOR_CLI_WAIT_TIMEOUT_MS` caps any `--wait` (use `540000` to stay under a 10-minute shell limit).
|
|
427
|
+
- `COAUTHOR_CLI_WAIT_POLL_MS` sets how often `--wait` checks (default 3000).
|
|
428
|
+
- `COAUTHOR_CLI_RESEARCH_STALE_MS` sets how long research progress may stand still before `research_running_stale` (default 30 minutes).
|
|
429
|
+
|
|
430
|
+
### Before retrying anything
|
|
431
|
+
|
|
432
|
+
Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. Starting a step twice can spend credits twice.
|