@clickminded/coauthor-cli 0.0.21 → 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 +278 -87
- 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
package/scripts/postinstall.mjs
CHANGED
|
@@ -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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
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
|
-
|
|
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(
|
|
33
|
+
nextSkills.push(entry)
|
|
34
34
|
continue
|
|
35
35
|
}
|
|
36
|
-
|
|
37
36
|
const currentHash = sha256(current)
|
|
38
|
-
const nextHash = sha256(
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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
|
-
|
|
59
|
-
|
|
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
|
|
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
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
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
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
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
|
|
30
|
-
const
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
|
38
|
-
const
|
|
39
|
-
if (
|
|
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
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
}
|
|
49
|
-
|
|
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
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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,62 @@
|
|
|
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 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.
|
|
34
|
+
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.
|
|
35
|
+
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`.
|
|
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`), 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`).
|
|
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. |
|
|
47
|
+
| `timed_out`, `still_running` | Run the resume or show command in the output. Do not restart the step. |
|
|
48
|
+
| `research_structuring` | Normal after research. Keep waiting or resume toward draft. |
|
|
49
|
+
| `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. |
|
|
50
|
+
| `credits_exhausted` | Tell the user `reset_at` and what remains. Resume after the reset. |
|
|
51
|
+
| `requires_key` | The user adds a provider key in CoAuthor's AI settings, then resume. |
|
|
52
|
+
| `stale_draft` | Someone changed the draft. Re-read it and reapply your edit. |
|
|
53
|
+
| `user_recently_editing` | The user is typing in the browser. Wait or ask; use `--force` only with their OK. |
|
|
54
|
+
| `revision_pending` | Apply or discard the open revision first. |
|
|
55
|
+
| `revise_unavailable` | Edit the draft directly with `draft get` and `draft save`. |
|
|
56
|
+
| `coauthor_access_required` | The CoAuthor subscription is inactive. Tell the user. |
|
|
57
|
+
|
|
58
|
+
Everything else, including auth problems: `references/troubleshooting.md`. Credits, plans, and models: `references/credits-and-plans.md`.
|
|
59
|
+
|
|
60
|
+
## Not in the CLI yet
|
|
61
|
+
|
|
62
|
+
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`.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Images and social posts
|
|
2
|
+
|
|
3
|
+
## Article images
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
|
|
8
|
+
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>`.
|
|
9
|
+
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.
|
|
10
|
+
4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
|
|
11
|
+
- Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
|
|
12
|
+
- Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
|
|
13
|
+
- Prices, dates, and text inside the image must match the article.
|
|
14
|
+
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`).
|
|
15
|
+
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.
|
|
16
|
+
|
|
17
|
+
Images cost credits each time they are generated or edited, so check the brief and placeholder purpose before regenerating.
|
|
18
|
+
|
|
19
|
+
## X thread
|
|
20
|
+
|
|
21
|
+
1. `coauthor thread generate <id> --json` writes a thread from the saved draft (optional `--writing-model <id>`).
|
|
22
|
+
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`.
|
|
23
|
+
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).
|
|
24
|
+
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`.
|
|
25
|
+
|
|
26
|
+
## Other formats
|
|
27
|
+
|
|
28
|
+
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.
|