@clickminded/coauthor-cli 0.0.83 → 0.0.85

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/dist/commands.js CHANGED
@@ -816,6 +816,13 @@ async function runPostDetailsCommand(action, input, client) {
816
816
  }
817
817
  if (action === 'set') {
818
818
  const body = parseJsonOption(input.values);
819
+ // The display title (H1, the post title in exports) is stored as the project title. It cannot be cleared.
820
+ const title = getString(input.values, 'title');
821
+ if (title !== undefined) {
822
+ if (!title.trim())
823
+ throw new Error('--title needs a title (1 to 300 characters); a post always has one.');
824
+ body.title = title.trim();
825
+ }
819
826
  for (const [flag, field] of POST_DETAILS_FLAG_FIELDS) {
820
827
  const value = getString(input.values, flag);
821
828
  if (value !== undefined)
@@ -849,7 +856,7 @@ async function runPostDetailsCommand(action, input, client) {
849
856
  body.tracking_keyword = null;
850
857
  }
851
858
  if (Object.keys(body).length === 0) {
852
- throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search]');
859
+ throw new Error('Usage: coauthor post-details set <projectId> [--title "..."] [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search]');
853
860
  }
854
861
  return { ok: true, data: await client.request({ method: 'PATCH', path, body }) };
855
862
  }
@@ -3782,7 +3789,7 @@ function commandHelp(command) {
3782
3789
  'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--widgets image|embed] [--json]',
3783
3790
  '',
3784
3791
  'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
3785
- '--frontmatter (markdown only) prepends YAML frontmatter from the post details: title, seo_title, description, slug, excerpt, and the featured image. Posts without post details get no frontmatter.',
3792
+ '--frontmatter (markdown only) prepends YAML frontmatter from the post details: title (the display title), seo_title, description, slug, excerpt, and the featured image. Posts without post details get no frontmatter.',
3786
3793
  '--widgets (markdown or html only) chooses how built interactives export. image (default) is the linked poster image, safe for email and newsletters. embed is the live sandboxed iframe plus one embed.js script, for a website you control (Astro, Hugo, Next, custom HTML). In markdown the iframe is a raw HTML block that is also valid MDX.',
3787
3794
  ].join('\n'),
3788
3795
  'draft save': [
@@ -3797,6 +3804,7 @@ function commandHelp(command) {
3797
3804
  '',
3798
3805
  'create: --title, --topic, --audience, --contract <json|@file>. show: one project.',
3799
3806
  'list: --limit <n> (1-100), --cursor <next_cursor from the previous page>, --status <state> (a project_state such as research_running or editing, or the publication status submitted|published).',
3807
+ 'rename <project-id> --title "...": changes the post\'s display title (its H1 and the post title in exports, the same as post-details set --title). A drafted post keeps a renamed title when the draft is regenerated.',
3800
3808
  'duplicate <project-id> [--title "..."]: copies the brief, outline, research, chats, draft, images and repurposed posts into a new project that keeps the same profile (default title is "<title> (Copy)"). Prints the new project id.',
3801
3809
  ].join('\n'),
3802
3810
  profile: [
@@ -3963,10 +3971,11 @@ function commandHelp(command) {
3963
3971
  ].join('\n'),
3964
3972
  'post-details': [
3965
3973
  'Usage: coauthor post-details show <project-id> [--json]',
3966
- ' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search] [--json]',
3974
+ ' coauthor post-details set <project-id> [--title "..."] [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search] [--json]',
3967
3975
  '',
3968
3976
  'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
3969
- 'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
3977
+ 'title is the post\'s display title: its H1 and the post title in WordPress, ClickMinded and Markdown exports. It is the project title (CoAuthor writes it with the draft; `project rename` changes it too). seo_title is only the title shown in search results and the meta title in exports.',
3978
+ 'set changes only the fields you pass; an empty value clears a field (except --title: a post always has a title). Edited fields, including a title you set or renamed, are kept when the draft is regenerated.',
3970
3979
  'The live URL is where the post is published. show returns published_url and published_url_source (export, manual, auto_detect or cleared). --live-url sets it by hand (an http or https address) and wins over later exports; --clear-live-url removes it, and CoAuthor then does not look for it again.',
3971
3980
  'Posts written without a target search (mostly drafted before SEO mode) are tracked by the monthly check anyway: CoAuthor finds the live page and picks a search. show returns tracking (published_url, published_url_source, tracking_keyword, tracking_keyword_source: ranked or suggested = CoAuthor picked it, manual = you did). --track-search sets the search to track (1 to 120 characters; wins over later picks); --clear-track-search has CoAuthor pick again at the next check. To stop tracking such a post, use --clear-live-url. --track-search is for posts without a target search (a post with one answers post_has_target_search).',
3972
3981
  'Posts drafted before post details launched have no SEO fields (show returns post_details: null; setting SEO fields returns post_details_unavailable), but --live-url, --clear-live-url and --track-search still work for them.',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.83",
3
+ "version": "0.0.85",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -36,7 +36,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
36
36
  3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. `data.not_applied` lists any requested change CoAuthor did not make, each with `request` and `reason`; resend those with clearer wording or tell the user why they were left out. When `data.research_plan.stale` is true (the outline changed after a research plan was made; `sections_without_tasks` lists sections it does not cover), run `coauthor research-plan generate <id> --json` after approving the outline instead of approving the old plan. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
37
37
  4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
38
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 already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, and links (cut-short or malformed URLs, dead pages, citations that open a page about something else). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `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.
39
+ 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items (and every figure they give, plus sentences claiming the post has no data the brief supplies), non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, links (cut-short or malformed URLs, dead pages, citations that open a page about something else), and sentences that cite a research source: figures that are not in that source, a report edition that differs from the one cited ("the 2027 report" linked to the 2026 page), and up to 15 rules or figures checked against the source text (contradicted ones are corrected from the source when it can; the rest are reported). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `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
40
  7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). 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, and that its alt text matches what is visible (CoAuthor writes alt text from the finished image; fix it with `image metadata` only when it is wrong). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
41
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
42
  9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
@@ -10,24 +10,27 @@ coauthor draft get <id> --format text --json # data.text, plain text with
10
10
  coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
11
11
  ```
12
12
 
13
- 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.
13
+ 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 post-details show <id> --json` (`data.post_details.title`, or `data.project.title` from `coauthor project show` for drafts without post details) 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.
14
14
 
15
15
  For a markdown file going into a static-site generator (Astro, Hugo, Next.js, Ghost), add `--frontmatter`: the markdown then starts with a YAML block holding the title, SEO title, meta description, slug, excerpt, and featured image from the post details. Drafts made before post details launched get no frontmatter. SEO posts also get `keyword` and `secondary_keywords`. Every `draft get` response includes `search` in its metadata: `{keyword, secondary_keywords, market}` for SEO posts, `null` otherwise.
16
16
 
17
- ## Post details (SEO title, meta description, slug, excerpt)
17
+ ## Post details (title, SEO title, meta description, slug, excerpt)
18
18
 
19
19
  After a draft, CoAuthor writes the post's SEO title, meta description, slug, and excerpt. Exports use them as defaults, so set them once here rather than on every export.
20
20
 
21
+ `post_details.title` is the display title: the post's H1 and the post title in WordPress, ClickMinded and Markdown exports. It is the project title, which CoAuthor writes with the draft. `seo_title` is only the title shown in search results (keyword first, about 60 characters) and the meta title in exports, so never use it as the H1. Change the display title with `--title` (or `project rename`, which is the same thing); it cannot be cleared.
22
+
21
23
  ```sh
22
24
  coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
23
25
  coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
26
+ coauthor post-details set <id> --title "The Post's Headline" --json # display title (H1); kept when the draft is regenerated
24
27
  coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
25
28
  coauthor post-details set <id> --clear-live-url --json
26
29
  coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
27
30
  coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
28
31
  ```
29
32
 
30
- `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field.
33
+ `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated, and so is a title set with `--title` or `project rename` (`user_edited_fields` then lists `title`). Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field or the title; rename such a post with `project rename`.
31
34
 
32
35
  The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
33
36
 
@@ -59,7 +59,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
59
59
  | `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
60
60
  | `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
61
61
  | `post_details_unavailable` | The draft was made before post details launched, so it has no SEO fields to edit (`--live-url` and `--track-search` still work). | Pass the slug and description to the export directly. |
62
- | `invalid_post_details` | `post-details set` got something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
62
+ | `invalid_post_details` | `post-details set` got an empty or over-300-character `--title`, something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass a title of 1 to 300 characters with `--title`, plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
63
63
  | `post_has_target_search` | `post-details set --track-search` on a post that was written for a target search. | Nothing to do: that post is tracked with its target search. Change it with `search-brief set-keyword` if the user wants another. |
64
64
  | `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
65
65
  | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
@@ -104,4 +104,4 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
104
104
 
105
105
  ## Before retrying anything
106
106
 
107
- 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`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
107
+ 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`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes; `kind: claim_not_supported_by_source` is a sentence with a number or a rule whose cited source says something else or does not say it (including figures missing from the cited page and a report year that differs from the cited edition), with the sentence and what the source supports in `detail`; `claim_check` gives that part's own `status` and how many sentences it `checked`, and its `failed` means only that part could not run) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
@@ -38,7 +38,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
38
38
  3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. `data.not_applied` lists any requested change CoAuthor did not make, each with `request` and `reason`; resend those with clearer wording or tell the user why they were left out. When `data.research_plan.stale` is true (the outline changed after a research plan was made; `sections_without_tasks` lists sections it does not cover), run `coauthor research-plan generate <id> --json` after approving the outline instead of approving the old plan. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
39
39
  4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
40
40
  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`.
41
- 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, and links (cut-short or malformed URLs, dead pages, citations that open a page about something else). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `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.
41
+ 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items (and every figure they give, plus sentences claiming the post has no data the brief supplies), non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, links (cut-short or malformed URLs, dead pages, citations that open a page about something else), and sentences that cite a research source: figures that are not in that source, a report edition that differs from the one cited ("the 2027 report" linked to the 2026 page), and up to 15 rules or figures checked against the source text (contradicted ones are corrected from the source when it can; the rest are reported). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `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.
42
42
  7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). 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, and that its alt text matches what is visible (CoAuthor writes alt text from the finished image; fix it with `image metadata` only when it is wrong). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
43
43
  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`.
44
44
  9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
@@ -460,24 +460,27 @@ coauthor draft get <id> --format text --json # data.text, plain text with
460
460
  coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
461
461
  ```
462
462
 
463
- 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.
463
+ 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 post-details show <id> --json` (`data.post_details.title`, or `data.project.title` from `coauthor project show` for drafts without post details) 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.
464
464
 
465
465
  For a markdown file going into a static-site generator (Astro, Hugo, Next.js, Ghost), add `--frontmatter`: the markdown then starts with a YAML block holding the title, SEO title, meta description, slug, excerpt, and featured image from the post details. Drafts made before post details launched get no frontmatter. SEO posts also get `keyword` and `secondary_keywords`. Every `draft get` response includes `search` in its metadata: `{keyword, secondary_keywords, market}` for SEO posts, `null` otherwise.
466
466
 
467
- ### Post details (SEO title, meta description, slug, excerpt)
467
+ ### Post details (title, SEO title, meta description, slug, excerpt)
468
468
 
469
469
  After a draft, CoAuthor writes the post's SEO title, meta description, slug, and excerpt. Exports use them as defaults, so set them once here rather than on every export.
470
470
 
471
+ `post_details.title` is the display title: the post's H1 and the post title in WordPress, ClickMinded and Markdown exports. It is the project title, which CoAuthor writes with the draft. `seo_title` is only the title shown in search results (keyword first, about 60 characters) and the meta title in exports, so never use it as the H1. Change the display title with `--title` (or `project rename`, which is the same thing); it cannot be cleared.
472
+
471
473
  ```sh
472
474
  coauthor post-details show <id> --json # data.post_details (null for drafts made before post details launched)
473
475
  coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
476
+ coauthor post-details set <id> --title "The Post's Headline" --json # display title (H1); kept when the draft is regenerated
474
477
  coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
475
478
  coauthor post-details set <id> --clear-live-url --json
476
479
  coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
477
480
  coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
478
481
  ```
479
482
 
480
- `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field.
483
+ `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated, and so is a title set with `--title` or `project rename` (`user_edited_fields` then lists `title`). Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field or the title; rename such a post with `project rename`.
481
484
 
482
485
  The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
483
486
 
@@ -780,7 +783,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
780
783
  | `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
781
784
  | `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
782
785
  | `post_details_unavailable` | The draft was made before post details launched, so it has no SEO fields to edit (`--live-url` and `--track-search` still work). | Pass the slug and description to the export directly. |
783
- | `invalid_post_details` | `post-details set` got something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
786
+ | `invalid_post_details` | `post-details set` got an empty or over-300-character `--title`, something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass a title of 1 to 300 characters with `--title`, plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
784
787
  | `post_has_target_search` | `post-details set --track-search` on a post that was written for a target search. | Nothing to do: that post is tracked with its target search. Change it with `search-brief set-keyword` if the user wants another. |
785
788
  | `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
786
789
  | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
@@ -825,4 +828,4 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
825
828
 
826
829
  ### Before retrying anything
827
830
 
828
- 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`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
831
+ 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`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes; `kind: claim_not_supported_by_source` is a sentence with a number or a rule whose cited source says something else or does not say it (including figures missing from the cited page and a report year that differs from the cited edition), with the sentence and what the source supports in `detail`; `claim_check` gives that part's own `status` and how many sentences it `checked`, and its `failed` means only that part could not run) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.