@clickminded/coauthor-cli 0.0.22 → 0.0.24

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.
@@ -0,0 +1,58 @@
1
+ #!/usr/bin/env node
2
+ // Builds the Cursor rule from the canonical skill (skills/coauthor). Cursor
3
+ // rules cannot load reference files on demand, so the references are appended
4
+ // as sections. `--check` exits non-zero when the committed rule is out of date.
5
+
6
+ import { readFile, readdir, writeFile } from 'node:fs/promises'
7
+ import { dirname, join } from 'node:path'
8
+ import { fileURLToPath } from 'node:url'
9
+
10
+ const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
11
+ const skillDir = join(packageRoot, 'skills', 'coauthor')
12
+ export const cursorRulePath = join(packageRoot, 'skills', 'cursor', 'coauthor-cli.mdc')
13
+
14
+ export async function buildCursorRule() {
15
+ const skill = await readFile(join(skillDir, 'SKILL.md'), 'utf8')
16
+ const match = /^---\n([\s\S]*?)\n---\n/.exec(skill)
17
+ if (!match) throw new Error('skills/coauthor/SKILL.md is missing its frontmatter')
18
+ const description = /^description: (.*)$/m.exec(match[1])?.[1]
19
+ if (!description) throw new Error('skills/coauthor/SKILL.md frontmatter has no description')
20
+ const body = skill.slice(match[0].length).trim()
21
+ const referenceNames = (await readdir(join(skillDir, 'references'))).filter((name) => name.endsWith('.md')).sort()
22
+ const references = await Promise.all(referenceNames.map(async (name) => {
23
+ const text = (await readFile(join(skillDir, 'references', name), 'utf8')).trim()
24
+ // Demote headings one level so each reference nests under its own section.
25
+ return `## references/${name}\n\n${text.replace(/^(#+) /gm, '#$1 ')}`
26
+ }))
27
+ return [
28
+ '---',
29
+ `description: ${description}`,
30
+ 'alwaysApply: false',
31
+ '---',
32
+ '',
33
+ '<!-- Generated from skills/coauthor by scripts/build-cursor-rule.mjs. Do not edit by hand. -->',
34
+ '',
35
+ body,
36
+ '',
37
+ '# Reference sections',
38
+ '',
39
+ 'The `references/*.md` files mentioned above are included below.',
40
+ '',
41
+ references.join('\n\n'),
42
+ '',
43
+ ].join('\n')
44
+ }
45
+
46
+ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
47
+ const rule = await buildCursorRule()
48
+ if (process.argv.includes('--check')) {
49
+ const current = await readFile(cursorRulePath, 'utf8').catch(() => '')
50
+ if (current !== rule) {
51
+ console.error('skills/cursor/coauthor-cli.mdc is out of date. Run: node scripts/build-cursor-rule.mjs')
52
+ process.exit(1)
53
+ }
54
+ } else {
55
+ await writeFile(cursorRulePath, rule)
56
+ console.log('Wrote skills/cursor/coauthor-cli.mdc')
57
+ }
58
+ }
@@ -1,80 +1,82 @@
1
+ // Keeps installed CoAuthor skills current when the CLI package is upgraded.
2
+ // Only files the CLI wrote and the user has not edited are replaced; files the
3
+ // user deleted are not re-created. Never fails the install.
4
+
1
5
  import { createHash } from 'node:crypto'
2
- import { mkdir, readFile, writeFile } from 'node:fs/promises'
6
+ import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
3
7
  import { dirname, join } from 'node:path'
4
8
  import { fileURLToPath } from 'node:url'
5
9
  import { homedir } from 'node:os'
6
10
 
7
11
  const packageRoot = fileURLToPath(new URL('..', import.meta.url))
8
- const registryPath = join(homedir(), '.config', 'coauthor', 'managed-skills.json')
12
+ const registryPath = process.env.COAUTHOR_MANAGED_SKILLS_REGISTRY || join(homedir(), '.config', 'coauthor', 'managed-skills.json')
13
+ const SKILL_DIR_TEMPLATE = '../skills/coauthor'
14
+ // Before 0.0.23 each agent had its own single-file template.
15
+ const LEGACY_TEMPLATES = new Set(['../skills/claude/SKILL.md', '../skills/codex/SKILL.md', '../skills/agents/SKILL.md'])
9
16
 
10
17
  async function main() {
11
18
  const registry = await readRegistry()
12
19
  if (registry.skills.length === 0) return
13
20
 
14
- let changed = false
15
21
  const nextSkills = []
16
- for (const skill of registry.skills) {
17
- const templatePath = resolveTemplatePath(skill.template)
18
- if (!templatePath) {
19
- nextSkills.push(skill)
20
- continue
21
- }
22
-
23
- const template = await readFile(templatePath, 'utf8').catch(() => null)
24
- if (template === null) {
25
- nextSkills.push(skill)
22
+ const skillRoots = new Map()
23
+ for (const entry of registry.skills) {
24
+ const template = LEGACY_TEMPLATES.has(entry.template) ? `${SKILL_DIR_TEMPLATE}/SKILL.md` : entry.template
25
+ const contents = await readTemplate(template)
26
+ if (contents === null) {
27
+ nextSkills.push(entry)
26
28
  continue
27
29
  }
28
-
29
- const current = await readFile(skill.path, 'utf8').catch((error) => {
30
- return error && error.code === 'ENOENT' ? '' : null
31
- })
30
+ const current = await readFile(entry.path, 'utf8').catch((error) => (error && error.code === 'ENOENT' ? undefined : null))
31
+ if (current === undefined) continue // the user deleted it: stop managing it
32
32
  if (current === null) {
33
- nextSkills.push(skill)
33
+ nextSkills.push(entry)
34
34
  continue
35
35
  }
36
-
37
36
  const currentHash = sha256(current)
38
- const nextHash = sha256(template)
39
- const safeToUpdate = current === '' || currentHash === skill.templateHash || currentHash === nextHash
40
- if (!safeToUpdate) {
41
- nextSkills.push(skill)
37
+ const nextHash = sha256(contents)
38
+ if (currentHash !== entry.templateHash && currentHash !== nextHash) {
39
+ nextSkills.push(entry) // edited locally: leave it alone
42
40
  continue
43
41
  }
42
+ if (currentHash !== nextHash) await writeFile(entry.path, contents, { mode: 0o644 })
43
+ nextSkills.push({ ...entry, template, templateHash: nextHash, updatedAt: new Date().toISOString() })
44
+ if (template === `${SKILL_DIR_TEMPLATE}/SKILL.md`) skillRoots.set(dirname(entry.path), entry.skill)
45
+ }
44
46
 
45
- if (currentHash !== nextHash) {
46
- await mkdir(dirname(skill.path), { recursive: true })
47
- await writeFile(skill.path, template, { mode: 0o644 })
47
+ // A managed skill folder gets any reference files added in this version.
48
+ const templateFiles = await listFiles(join(packageRoot, 'skills', 'coauthor'))
49
+ for (const [root, skill] of skillRoots) {
50
+ for (const file of templateFiles) {
51
+ if (file === 'SKILL.md') continue
52
+ const path = join(root, ...file.split('/'))
53
+ if (nextSkills.some((entry) => entry.path === path)) continue
54
+ const existing = await readFile(path, 'utf8').catch(() => null)
55
+ const contents = await readTemplate(`${SKILL_DIR_TEMPLATE}/${file}`)
56
+ if (contents === null || (existing !== null && existing !== contents)) continue
57
+ if (existing === null) {
58
+ await mkdir(dirname(path), { recursive: true })
59
+ await writeFile(path, contents, { mode: 0o644 })
60
+ }
61
+ nextSkills.push({ skill, path, template: `${SKILL_DIR_TEMPLATE}/${file}`, templateHash: sha256(contents), updatedAt: new Date().toISOString() })
48
62
  }
49
-
50
- nextSkills.push({
51
- ...skill,
52
- templateHash: nextHash,
53
- updatedAt: new Date().toISOString(),
54
- })
55
- changed = true
56
63
  }
57
64
 
58
- if (changed) {
59
- await mkdir(dirname(registryPath), { recursive: true })
60
- await writeFile(registryPath, `${JSON.stringify({ version: 1, skills: nextSkills }, null, 2)}\n`, { mode: 0o644 })
61
- }
65
+ await mkdir(dirname(registryPath), { recursive: true })
66
+ await writeFile(registryPath, `${JSON.stringify({ version: 1, skills: nextSkills }, null, 2)}\n`, { mode: 0o644 })
62
67
  }
63
68
 
64
69
  async function readRegistry() {
65
70
  try {
66
- const raw = await readFile(registryPath, 'utf8')
67
- const parsed = JSON.parse(raw)
71
+ const parsed = JSON.parse(await readFile(registryPath, 'utf8'))
68
72
  if (parsed?.version !== 1 || !Array.isArray(parsed.skills)) return { version: 1, skills: [] }
69
73
  return {
70
74
  version: 1,
71
- skills: parsed.skills.filter((skill) => {
72
- return skill
73
- && typeof skill.skill === 'string'
74
- && typeof skill.path === 'string'
75
- && typeof skill.template === 'string'
76
- && typeof skill.templateHash === 'string'
77
- }),
75
+ skills: parsed.skills.filter((skill) => skill
76
+ && typeof skill.skill === 'string'
77
+ && typeof skill.path === 'string'
78
+ && typeof skill.template === 'string'
79
+ && typeof skill.templateHash === 'string'),
78
80
  }
79
81
  } catch (error) {
80
82
  if (error && error.code === 'ENOENT') return { version: 1, skills: [] }
@@ -82,9 +84,19 @@ async function readRegistry() {
82
84
  }
83
85
  }
84
86
 
85
- function resolveTemplatePath(template) {
87
+ async function readTemplate(template) {
86
88
  if (!template.startsWith('../skills/')) return null
87
- return join(packageRoot, template.replace(/^\.\.\//, ''))
89
+ return readFile(join(packageRoot, template.replace(/^\.\.\//, '')), 'utf8').catch(() => null)
90
+ }
91
+
92
+ async function listFiles(dir, prefix = '') {
93
+ const files = []
94
+ for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
95
+ const relative = prefix ? `${prefix}/${entry.name}` : entry.name
96
+ if (entry.isDirectory()) files.push(...await listFiles(join(dir, entry.name), relative))
97
+ else files.push(relative)
98
+ }
99
+ return files
88
100
  }
89
101
 
90
102
  function sha256(value) {
@@ -1,59 +1,67 @@
1
1
  #!/usr/bin/env node
2
+ // The customer skill lives in packages/cli/skills/coauthor and ships to npm.
3
+ // The repo keeps exact copies for developers' own agents; operator-only notes
4
+ // live in a separate coauthor-internal skill that never ships.
2
5
 
3
- import { readFile } from 'node:fs/promises'
4
- import { dirname, resolve } from 'node:path'
6
+ import { readFile, readdir } from 'node:fs/promises'
7
+ import { dirname, join, relative, resolve } from 'node:path'
5
8
  import { fileURLToPath } from 'node:url'
9
+ import { buildCursorRule, cursorRulePath } from './build-cursor-rule.mjs'
6
10
 
7
11
  const scriptDir = dirname(fileURLToPath(import.meta.url))
12
+ const packageRoot = resolve(scriptDir, '..')
8
13
  const repoRoot = resolve(scriptDir, '../../../..')
14
+ const skillDir = join(packageRoot, 'skills', 'coauthor')
15
+ const repoSkillCopies = ['coauthor/.claude/skills/coauthor', 'coauthor/.agents/skills/coauthor']
16
+ const repoCursorCopy = 'coauthor/.cursor/rules/coauthor-cli.mdc'
17
+ // Internal-only material must never reach the published skill.
18
+ const forbidden = [/\bDrip\b/, /WooCommerce/, /\badmins\b table/i, /service[- ]role/i, /localhost/, /export (blog|clickminded)\b/]
9
19
 
10
- const groups = [
11
- {
12
- canonical: 'coauthor/packages/cli/skills/agents/SKILL.md',
13
- copies: [
14
- 'coauthor/packages/cli/skills/codex/SKILL.md',
15
- 'coauthor/packages/cli/skills/claude/SKILL.md',
16
- 'coauthor/.agents/skills/coauthor/SKILL.md',
17
- 'coauthor/.claude/skills/coauthor/SKILL.md',
18
- ],
19
- optionalCopies: ['.agents/skills/coauthor/SKILL.md'],
20
- },
21
- {
22
- canonical: 'coauthor/packages/cli/skills/cursor/coauthor-cli.mdc',
23
- copies: ['coauthor/.cursor/rules/coauthor-cli.mdc'],
24
- },
25
- ]
20
+ async function walk(dir) {
21
+ const files = []
22
+ for (const entry of await readdir(dir, { withFileTypes: true })) {
23
+ const path = join(dir, entry.name)
24
+ if (entry.isDirectory()) files.push(...await walk(path))
25
+ else files.push(path)
26
+ }
27
+ return files
28
+ }
26
29
 
27
30
  const mismatches = []
31
+ const skillFiles = (await walk(skillDir)).map((path) => relative(skillDir, path)).sort()
32
+
33
+ for (const file of skillFiles) {
34
+ const text = await readFile(join(skillDir, file), 'utf8')
35
+ for (const pattern of forbidden) {
36
+ if (pattern.test(text)) mismatches.push(`skills/coauthor/${file} contains internal-only text matching ${pattern}`)
37
+ }
38
+ }
28
39
 
29
- for (const group of groups) {
30
- const canonical = await read(group.canonical)
31
- for (const copyPath of group.copies) {
32
- const copy = await read(copyPath)
33
- if (copy !== canonical) {
34
- mismatches.push(`${copyPath} differs from ${group.canonical}`)
35
- }
40
+ for (const copy of repoSkillCopies) {
41
+ const copyDir = join(repoRoot, copy)
42
+ const copyFiles = (await walk(copyDir).catch(() => [])).map((path) => relative(copyDir, path)).sort()
43
+ if (copyFiles.join('\n') !== skillFiles.join('\n')) {
44
+ mismatches.push(`${copy} has files [${copyFiles.join(', ')}], expected [${skillFiles.join(', ')}]`)
45
+ continue
36
46
  }
37
- for (const copyPath of group.optionalCopies ?? []) {
38
- const copy = await read(copyPath, { optional: true })
39
- if (copy !== null && copy !== canonical) {
40
- mismatches.push(`${copyPath} differs from ${group.canonical}`)
41
- }
47
+ for (const file of skillFiles) {
48
+ const [canonical, mirrored] = await Promise.all([readFile(join(skillDir, file), 'utf8'), readFile(join(copyDir, file), 'utf8')])
49
+ if (canonical !== mirrored) mismatches.push(`${copy}/${file} differs from packages/cli/skills/coauthor/${file}`)
42
50
  }
43
51
  }
44
52
 
45
- if (mismatches.length > 0) {
46
- process.stderr.write(`CoAuthor skill synchronization failed:\n- ${mismatches.join('\n- ')}\n`)
47
- process.exitCode = 1
48
- } else {
49
- process.stdout.write('CoAuthor skill copies are synchronized.\n')
53
+ const rule = await buildCursorRule()
54
+ if ((await readFile(cursorRulePath, 'utf8').catch(() => '')) !== rule) {
55
+ mismatches.push('packages/cli/skills/cursor/coauthor-cli.mdc is out of date. Run: node scripts/build-cursor-rule.mjs')
56
+ }
57
+ if ((await readFile(join(repoRoot, repoCursorCopy), 'utf8').catch(() => '')) !== rule) {
58
+ mismatches.push(`${repoCursorCopy} differs from the generated Cursor rule`)
50
59
  }
51
60
 
52
- async function read(relativePath, options = {}) {
53
- try {
54
- return await readFile(resolve(repoRoot, relativePath), 'utf8')
55
- } catch (error) {
56
- if (options.optional && error.code === 'ENOENT') return null
57
- throw new Error(`Could not read ${relativePath}: ${error.message}`)
58
- }
61
+ if (mismatches.length > 0) {
62
+ console.error('CoAuthor skill copies are not synchronized:')
63
+ for (const mismatch of mismatches) console.error(`- ${mismatch}`)
64
+ process.exit(1)
59
65
  }
66
+
67
+ console.log('CoAuthor skill copies are synchronized.')
@@ -0,0 +1,63 @@
1
+ ---
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.
4
+ ---
5
+
6
+ # CoAuthor
7
+
8
+ CoAuthor turns a brief into a researched, cited article in the user's voice:
9
+ brief → outline → research plan → research → draft → images → edits → export.
10
+ 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.
11
+
12
+ ## Before you start
13
+
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.
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
+
18
+ ## Rules
19
+
20
+ - Always pass `--json` and read fields from the output. Failures arrive on stderr as JSON with `code`, `http_status`, and `details`.
21
+ - 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.
22
+ - Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`.
23
+ - Every blocked or paused status says what to do next. Follow it instead of retrying (see "When something stops").
24
+ - 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.
25
+ - Never send markdown to `draft save`.
26
+
27
+ ## Write a piece
28
+
29
+ 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.
30
+
31
+ 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:
32
+ `coauthor project create --title "..." --contract @brief.json --json` → `data.project.id`
33
+ 2. **Brief review.** `coauthor brief review <id> --json`. CoAuthor critiques the brief and returns `data.verdict`, `data.concerns`, and `data.questions`, each with `why`, the `field` it changes, and `answerable_by`. Answer the `agent` questions from your context; take `human` ones (opinions, private business facts, numbers, risk tolerance) to the user in one message, or, if they asked not to be interrupted, answer them as assumptions. Write `{"answers":[{"question","answer","source":"agent|user|assumption"}]}` to a file (add `"apply_suggested_patch": <data.suggested_patch>` if its suggestions are good) and run `coauthor brief answer <id> --data @answers.json --json`. Repeat once if the verdict was `needs_answers`, then approve: `coauthor contract approve <id> --json`. Log what you assumed: `coauthor log add <id> --kind assumption --message "..." --json`.
34
+ 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. 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.
35
+ 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.
36
+ 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`.
37
+ 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.
38
+ 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`.
39
+ 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`.
40
+ 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, WordPress export, or X thread (`references/publishing-and-export.md`).
41
+
42
+ ## When something stops
43
+
44
+ | Status or code | What to do |
45
+ | --- | --- |
46
+ | `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. (Prefer `brief review` / `brief answer`.) |
47
+ | `draft_exists`, `downstream_exists` | A later stage already depends on this one. Edit the draft instead; pass `--force` only if the user wants to restart from here. |
48
+ | `timed_out`, `still_running` | Run the resume or show command in the output. Do not restart the step. |
49
+ | `research_structuring` | Normal after research. Keep waiting or resume toward draft. |
50
+ | `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. |
51
+ | `credits_exhausted` | Tell the user `reset_at` and what remains. Resume after the reset. |
52
+ | `requires_key` | The user adds a provider key in CoAuthor's AI settings, then resume. |
53
+ | `stale_draft` | Someone changed the draft. Re-read it and reapply your edit. |
54
+ | `user_recently_editing` | The user is typing in the browser. Wait or ask; use `--force` only with their OK. |
55
+ | `revision_pending` | Apply or discard the open revision first. |
56
+ | `revise_unavailable` | Edit the draft directly with `draft get` and `draft save`. |
57
+ | `coauthor_access_required` | The CoAuthor subscription is inactive. Tell the user. |
58
+
59
+ Everything else, including auth problems: `references/troubleshooting.md`. Credits, plans, and models: `references/credits-and-plans.md`.
60
+
61
+ ## Not in the CLI yet
62
+
63
+ 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.
@@ -0,0 +1,151 @@
1
+ # Brief and contract
2
+
3
+ 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.
4
+
5
+ Create a project with it:
6
+
7
+ ```sh
8
+ coauthor project create --title "Working title" --contract @brief.json --json
9
+ ```
10
+
11
+ 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.
12
+
13
+ ## Writing a sharp brief
14
+
15
+ - **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.
16
+ - **Name the reader.** Who they are, what they already know, and what they will do after reading.
17
+ - **Promise an outcome.** `core_promise` is what the reader can understand, decide, or do afterwards.
18
+ - **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.
19
+ - **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`.
20
+ - **Record what you assumed** in `confidence_notes`, so the user and CoAuthor can see where the brief is uncertain.
21
+
22
+ ## Schema
23
+
24
+ ```ts
25
+ {
26
+ topic?: string
27
+ angle?: string
28
+ target_audience?: string
29
+ core_promise?: string
30
+ format?: string
31
+ reading_commitment?: null | {
32
+ kind: "preset" | "custom"
33
+ preset_id?: null | "quick_read" | "balanced_post" | "deep_dive"
34
+ source: "user_explicit" | "user_choice" | "assistant_inferred" | "system_default"
35
+ }
36
+ length_guidance?: {
37
+ min_words?: number | null
38
+ target_words?: number | null
39
+ max_words?: number | null
40
+ }
41
+ audience_knowledge_assumptions?: string
42
+ desired_reader_experience?: string
43
+ structure_preferences?: string[]
44
+ must_include?: string[]
45
+ must_avoid?: string[]
46
+ non_negotiables?: string[]
47
+ evidence_expectations?: string[]
48
+ citation_expectations?: string[]
49
+ liked_examples?: string[]
50
+ rejected_examples?: string[]
51
+ additional_editorial_guidance?: string
52
+ editorial_profile?: {
53
+ tone?: "light" | "balanced" | "serious"
54
+ form?: "essay" | "listicle" | "guide" | "case_study" | "analysis" | "mixed"
55
+ depth?: "scannable" | "standard" | "deep"
56
+ humor?: "none" | "low" | "medium" | "high"
57
+ section_length?: "adaptive" | "mostly_short" | "mostly_long" | "mixed"
58
+ cadence?: "tight" | "moderate" | "expansive"
59
+ notes?: string
60
+ }
61
+ canonical_entities?: Array<{
62
+ actor_key?: string
63
+ character_name?: string
64
+ role_title?: string
65
+ description?: string
66
+ aliases?: string[]
67
+ must_preserve?: boolean
68
+ }>
69
+ outline_seed?: Array<{
70
+ id?: string
71
+ heading?: string
72
+ intent?: string
73
+ must_include_points?: string[]
74
+ required_actor_keys?: string[]
75
+ notes?: string
76
+ }>
77
+ style_rules?: string[]
78
+ must_not_change?: string[]
79
+ structure_preference?: string
80
+ confidence_notes?: string
81
+ }
82
+ ```
83
+
84
+ - 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.
85
+ - 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.
86
+ ## Field guide
87
+
88
+ - `topic`: The concrete subject or assignment. Include the search keyword, product, debate, or source brief if that is the true starting point.
89
+ - `angle`: The editorial thesis or framing. Use this to explain what makes this piece different from a generic article on the same topic.
90
+ - `target_audience`: Who the piece is for, including their sophistication, context, objections, and buying or reading intent.
91
+ - `core_promise`: The reader outcome. Phrase it as what the reader will understand, decide, or be able to do after reading.
92
+ - `format`: Human-readable format label, such as `blog post`, `guide`, `listicle`, `case study`, or `long-form SEO comparison guide`.
93
+ - `reading_commitment`: Use a preset when the user picked or implied a length tier. Use `custom` plus `length_guidance` when the user gave a specific range.
94
+ - `length_guidance`: Word-count bounds. Use positive integers or `null`; keep `min_words <= target_words <= max_words` when known.
95
+ - `audience_knowledge_assumptions`: What the reader already knows, so the draft does not over-explain or under-explain.
96
+ - `desired_reader_experience`: How the finished piece should feel to read, such as fast and scannable, authoritative and comprehensive, funny but informative, or practical and no-fluff.
97
+ - `structure_preferences`: List of preferred sections, ordering, comparison/table requirements, intro/conclusion instructions, or other structural choices.
98
+ - `must_include`: Specific points, keywords, URLs, products, claims, examples, or sections that must appear.
99
+ - `must_avoid`: Things to leave out, weak arguments, banned phrasings, unsupported claims, or misleading positioning.
100
+ - `non_negotiables`: Hard constraints that would make the draft wrong if violated. Use this for stricter requirements than ordinary `must_avoid` guidance.
101
+ - `evidence_expectations`: What kind of support the argument needs, such as official docs, pricing pages, public data, examples, or completed research.
102
+ - `citation_expectations`: Which claims need links or citations, preferred source types, and any source URLs that should be used.
103
+ - `liked_examples`: URLs, titles, patterns, or descriptions of examples to emulate.
104
+ - `rejected_examples`: URLs, titles, patterns, or descriptions of examples to avoid.
105
+ - `additional_editorial_guidance`: Any important prose brief that does not fit another field, including voice, pacing, product positioning, or inherited brief details.
106
+ - `editorial_profile`: Structured style controls. Use `notes` for nuance that enum values cannot capture.
107
+ - `canonical_entities`: Stable names for products, people, companies, characters, or concepts that must be referred to consistently. `actor_key` is the stable snake-case id used by `outline_seed.required_actor_keys`.
108
+ - `outline_seed`: Suggested section plan. Use `required_actor_keys` to tie sections to entries in `canonical_entities`.
109
+ - `style_rules`: Reusable sentence-level or formatting rules, such as short paragraphs, markdown tables, direct second person, or no academic hedging.
110
+ - `must_not_change`: Facts, names, positioning statements, URLs, or product limitations that must survive editing unchanged.
111
+ - `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
112
+ - `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
113
+
114
+ ## Example: practical B2B guide
115
+
116
+ ```json
117
+ {
118
+ "topic": "How small accounting firms can cut month-end close from ten days to five",
119
+ "angle": "The delay is rarely the accounting work; it is waiting on client documents. Fix the intake process first.",
120
+ "target_audience": "Owners of 3-15 person accounting and bookkeeping firms who run month-end close for small-business clients.",
121
+ "core_promise": "Readers leave with a five-step intake process and a client message template they can use this month.",
122
+ "format": "how-to guide",
123
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
124
+ "audience_knowledge_assumptions": "Knows close procedures and common accounting software; has not formalized client intake.",
125
+ "must_include": ["A day-by-day close calendar", "A copy-paste client reminder email", "How to handle clients who send documents late"],
126
+ "must_avoid": ["Software vendor comparisons", "Generic productivity advice"],
127
+ "non_negotiables": ["Every time-saving claim is tied to a concrete step, not a statistic without a source."],
128
+ "citation_expectations": ["Cite primary sources for any statistic about close times."],
129
+ "editorial_profile": { "tone": "balanced", "form": "guide", "depth": "standard", "humor": "low", "section_length": "mostly_short", "cadence": "tight" },
130
+ "style_rules": ["Short paragraphs.", "Second person.", "Use numbered steps for the process."],
131
+ "confidence_notes": "Firm size and the ten-day baseline come from the user; the five-step process is the assistant's proposal."
132
+ }
133
+ ```
134
+
135
+ ## Example: short opinion piece
136
+
137
+ ```json
138
+ {
139
+ "topic": "Why remote teams should stop recording every meeting",
140
+ "angle": "Recording everything feels transparent but kills candor and creates hours of footage nobody watches; record decisions, not discussions.",
141
+ "target_audience": "Managers of remote or hybrid teams of 5-50 people.",
142
+ "core_promise": "Readers get a simple rule for what to record and what to write down instead.",
143
+ "format": "opinion essay",
144
+ "reading_commitment": { "kind": "custom", "preset_id": null, "source": "user_explicit" },
145
+ "length_guidance": { "min_words": 700, "target_words": 900, "max_words": 1100 },
146
+ "must_include": ["A one-sentence rule the reader can adopt", "One concrete example of a decision log entry"],
147
+ "must_avoid": ["Strawmanning teams that record everything", "Unsourced statistics"],
148
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "notes": "Confident and direct, but fair to the opposing view." },
149
+ "style_rules": ["First person is fine.", "No hedging on the core argument."]
150
+ }
151
+ ```
@@ -0,0 +1,26 @@
1
+ # Credits, plans, and models
2
+
3
+ ## Credits
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.
6
+
7
+ Rough costs, to set expectations before starting:
8
+
9
+ - A complete article (brief through draft) is typically about 300 credits.
10
+ - Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
11
+ - Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
12
+
13
+ Tell the user the expected cost before large or repeated work, and report credits used at the end.
14
+
15
+ ## When credits run out
16
+
17
+ - **Starter:** work pauses (`credits_exhausted`) and resumes after the reset. Starter can't use the user's own AI provider keys.
18
+ - **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.
19
+
20
+ Paused work is saved. Resume it with `coauthor workflow resume <id> --wait --json`.
21
+
22
+ ## Models
23
+
24
+ - `coauthor models list` shows the planning and writing models available.
25
+ - Override for one run with `--planning-model <id>` (outline, research plan) and `--writing-model <id>` (draft, thread). There is no global `--model`.
26
+ - `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.
@@ -0,0 +1,59 @@
1
+ # Editing a draft
2
+
3
+ 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.
4
+
5
+ ## 1. Revise by instruction (prose changes)
6
+
7
+ CoAuthor's own editor rewrites the draft in the project's voice and proposes the change for review.
8
+
9
+ ```sh
10
+ coauthor draft revise <id> --instruction "Cut the intro to two sentences and lead with the 750-character limit." --wait --json
11
+ ```
12
+
13
+ - 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?
14
+ - 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`.
15
+ - `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.
16
+ - 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.
17
+ - 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.
18
+ - If `--wait` returns `still_running`, check again with `coauthor draft revision show <id> <revision-id> --json`.
19
+ - `revise_unavailable` means this account cannot revise by instruction yet; use a direct edit.
20
+
21
+ ## 2. Direct edit (exact text you already have)
22
+
23
+ 1. `coauthor draft get <id> --format json --json`. Keep `data.document_id`, `data.version_number`, and `data.content_hash` (null on some drafts).
24
+ 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":[...]}`.
25
+ - Keep node attributes (ids) on nodes you keep, and keep `imagePlaceholder` nodes unless the user wants the image removed.
26
+ - 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.
27
+ - 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.
28
+ 3. Write the payload to a file and save it:
29
+
30
+ ```json
31
+ {
32
+ "document_id": "<data.document_id>",
33
+ "expected_base_version": <data.version_number>,
34
+ "expected_content_hash": "<data.content_hash, if not null>",
35
+ "content": { "type": "doc", "content": [ ... ] }
36
+ }
37
+ ```
38
+
39
+ ```sh
40
+ coauthor draft save <id> --data @payload.json --json
41
+ ```
42
+
43
+ 4. Re-read with `coauthor draft get <id> --format markdown --json` to confirm the change.
44
+
45
+ Never send markdown or plain text as `content`; it is rejected. `--data @-` reads the payload from stdin.
46
+
47
+ ## Conflicts
48
+
49
+ - `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.
50
+ - `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.
51
+ - `review_pending` or `document_locked`: an AI review or edit is in progress in the editor. Wait for it, or apply or discard it.
52
+
53
+ ## Don't restart the piece by accident
54
+
55
+ 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.
56
+
57
+ - 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.
58
+ - Do not copy constraints you discover while editing back into the brief or outline "for the record".
59
+ - 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`.