innernote 0.1.2 → 0.3.1

package/README.md

@@ -78,18 +78,28 @@ any time.
 
 ## Commands
 
+The table below is asserted by `cli/src/parity.test.ts`: a command missing
+from it fails the suite, so what you read here is what the binary has.
+
 | Command | What it does |
 | --- | --- |
 | `login [code]` | connect this machine |
 | `logout` | forget the token stored here |
-| `whoami` | show which account is connected |
+| `whoami` | show which account is connected, and what this key can do |
+| `context` | what you post about: your pillars and your series |
 | `capture <text>` | save an idea to your inbox |
 | `write [topic]` | draft a post in your voice |
+| `shape <shape...>` | push a post shorter, punchier, warmer |
+| `ask <anything>` | talk to the post in your own words |
+| `save` | keep the draft you are holding |
+| `show` | reprint the post you are holding |
+| `drop` | put down whatever you are holding |
+| `open <n or id>` | pull a post out of the last list and work on it |
 | `ideas [status]` | list what you have captured |
-| `drafts [status]` | list your posts, with their ids |
+| `drafts [status]` | list your posts, numbered |
 | `week` | what is scheduled for the next seven days |
-| `shape <shape...>` | push a post shorter, punchier, warmer (reads stdin) |
 | `queue <post-id>` | schedule a post into your next open slot |
+| `unqueue <post-id>` | pull it back out before it goes live |
 
 ### write
 

package/dist/index.js

@@ -286,44 +286,44 @@ function wordmark(name, gap = 1) {
 function widest(rows) {
   return Math.max(...rows.map((r) => r.length));
 }
-function lockup(name = "innernote", tagline) {
-  const room = (process.stdout.columns ?? 80) - 5;
-  const mark = logo(2);
-  const markWidth = widest(mark);
+function lockup(name = "innernote", sub) {
+  const room = (process.stdout.columns || 80) - 5;
+  const subs = sub == null ? [] : Array.isArray(sub) ? sub : [sub];
+  const mark = logo(2).map((r) => r.trimEnd());
+  const ink = widest(mark);
   const word = wordmark(name);
   if (word) {
-    const gap2 = 3;
-    if (markWidth + gap2 + widest(word) <= room) {
+    const gap = 2;
+    const wide = Math.max(widest(word), ...subs.map((s) => width(s)));
+    if (ink + gap + wide <= room) {
       const rows2 = mark.map((r, i) => {
         const right = word[i] ?? "";
-        return right ? `${caramel(r.padEnd(markWidth))}${" ".repeat(gap2)}${bold2(caramel(right))}` : caramel(r.trimEnd());
+        return right ? `${caramel(r.padEnd(ink))}${" ".repeat(gap)}${bold2(caramel(right))}` : caramel(r);
       });
-      if (tagline)
-        rows2.push("", `  ${dim2(tagline)}`);
+      const indent = " ".repeat(ink + gap);
+      for (const line of subs)
+        rows2.push(`${indent}${line}`);
       return rows2;
     }
   }
-  const gap = 3;
-  const beside = Math.max(name.length, tagline?.length ?? 0);
-  if (markWidth + gap + beside <= room) {
-    const mid = Math.floor(mark.length / 2);
-    return mark.map((r, i) => {
-      const left = caramel(r.padEnd(markWidth)) + " ".repeat(gap);
-      if (i === mid)
-        return left + bold2(caramel(name));
-      if (i === mid + 1 && tagline)
-        return left + dim2(tagline);
-      return caramel(r.trimEnd());
-    });
-  }
-  const rows = mark.map((r) => caramel(r.trimEnd()));
-  rows.push("", bold2(caramel(name)));
-  if (tagline)
-    rows.push(dim2(tagline));
-  return rows;
+  const mid = Math.floor(mark.length / 2);
+  const below = [];
+  const rows = mark.map((r, i) => {
+    const left = caramel(r.padEnd(ink)) + "   ";
+    if (i === mid)
+      return left + bold2(caramel(name));
+    const sub2 = subs[i - mid - 1];
+    if (i > mid && sub2 !== undefined) {
+      if (ink + 3 + width(sub2) <= room)
+        return left + sub2;
+      below.push(sub2);
+    }
+    return caramel(r);
+  });
+  return [...rows, ...below];
 }
 function banner(tagline = "your voice, from the terminal") {
-  return lockup("innernote", tagline).map((r) => "  " + r).join(`
+  return lockup("innernote", dim2(tagline)).map((r) => "  " + r).join(`
 `);
 }
 function bar(score, width2 = 10) {
@@ -609,6 +609,42 @@ async function week(args) {
   }
   return 0;
 }
+async function context(args) {
+  const { json } = parseFlags(args);
+  const [pillars, series] = await Promise.all([
+    request("/api/pillars"),
+    request("/api/campaigns")
+  ]);
+  if (json) {
+    out(JSON.stringify({ pillars: pillars.pillars, series: series.campaigns }, null, 2));
+    return 0;
+  }
+  out();
+  if (pillars.pillars.length) {
+    out(`  ${bold2("What you post about")}`);
+    for (const p of pillars.pillars) {
+      out(`    ${caramel(p.name)}${typeof p.weight === "number" ? dim2(`   ${p.weight}%`) : ""}`);
+    }
+  } else {
+    out(`  ${dim2("No content pillars yet. Set them in Settings.")}`);
+  }
+  out();
+  if (series.campaigns.length) {
+    out(`  ${bold2("Series")}${dim2("   write into one with")} ${caramel('write --series "<name>"')}`);
+    for (const c of series.campaigns) {
+      const count = typeof c.postCount === "number" && c.postCount > 0 ? dim2(`   ${c.postCount} ${c.postCount === 1 ? "post" : "posts"}`) : "";
+      out(`    ${caramel(c.name)}${count}`);
+      if (c.brief)
+        out(`      ${dim2(oneLine(c.brief, 64))}`);
+      if (c.goal)
+        out(`      ${dim2(`goal: ${oneLine(c.goal, 58)}`)}`);
+    }
+  } else {
+    out(`  ${dim2("No series running.")}`);
+  }
+  out();
+  return 0;
+}
 
 // src/commands/read.ts
 function parseFlags2(args) {
@@ -1078,6 +1114,23 @@ async function drop() {
   note(dim2("`write` to start something, or `drafts` to pick one up"));
   return 0;
 }
+async function unqueue(args) {
+  const { json, rest } = parseFlags2(args);
+  const ref = rest[0] ? resolveRef(rest[0]) : null;
+  if (!ref) {
+    fail("Which post?");
+    note(dim2(`${CMD} unqueue <post-id>   (\`${CMD} week\` shows what is queued)`));
+    return 1;
+  }
+  const result = await request(`/api/linkedin/schedule/${encodeURIComponent(ref.id)}`, { method: "DELETE" });
+  if (json) {
+    out(JSON.stringify(result, null, 2));
+    return 0;
+  }
+  ok("Pulled back out of the queue. It is a draft again.");
+  note(dim2("`drafts` to find it, `queue` to send it back"));
+  return 0;
+}
 
 // src/ui.ts
 var useColor2 = process.stdout.isTTY === true && !process.env.NO_COLOR && process.env.TERM !== "dumb";
@@ -1122,6 +1175,9 @@ var dim4 = sgr2("2");
 var green4 = sgr2("32");
 var yellow4 = sgr2("33");
 var red4 = sgr2("31");
+function width2(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+}
 var canAnimate2 = isTTY2 && process.env.TERM !== "dumb" && !process.env.CI;
 var MARK_GRID2 = [
   "....#....",
@@ -1160,44 +1216,44 @@ function wordmark2(name, gap = 1) {
 function widest2(rows) {
   return Math.max(...rows.map((r) => r.length));
 }
-function lockup2(name = "innernote", tagline) {
-  const room = (process.stdout.columns ?? 80) - 5;
-  const mark = logo2(2);
-  const markWidth = widest2(mark);
+function lockup2(name = "innernote", sub) {
+  const room = (process.stdout.columns || 80) - 5;
+  const subs = sub == null ? [] : Array.isArray(sub) ? sub : [sub];
+  const mark = logo2(2).map((r) => r.trimEnd());
+  const ink = widest2(mark);
   const word = wordmark2(name);
   if (word) {
-    const gap2 = 3;
-    if (markWidth + gap2 + widest2(word) <= room) {
+    const gap = 2;
+    const wide = Math.max(widest2(word), ...subs.map((s) => width2(s)));
+    if (ink + gap + wide <= room) {
       const rows2 = mark.map((r, i) => {
         const right = word[i] ?? "";
-        return right ? `${caramel2(r.padEnd(markWidth))}${" ".repeat(gap2)}${bold4(caramel2(right))}` : caramel2(r.trimEnd());
+        return right ? `${caramel2(r.padEnd(ink))}${" ".repeat(gap)}${bold4(caramel2(right))}` : caramel2(r);
       });
-      if (tagline)
-        rows2.push("", `  ${dim4(tagline)}`);
+      const indent = " ".repeat(ink + gap);
+      for (const line of subs)
+        rows2.push(`${indent}${line}`);
       return rows2;
     }
   }
-  const gap = 3;
-  const beside = Math.max(name.length, tagline?.length ?? 0);
-  if (markWidth + gap + beside <= room) {
-    const mid = Math.floor(mark.length / 2);
-    return mark.map((r, i) => {
-      const left = caramel2(r.padEnd(markWidth)) + " ".repeat(gap);
-      if (i === mid)
-        return left + bold4(caramel2(name));
-      if (i === mid + 1 && tagline)
-        return left + dim4(tagline);
-      return caramel2(r.trimEnd());
-    });
-  }
-  const rows = mark.map((r) => caramel2(r.trimEnd()));
-  rows.push("", bold4(caramel2(name)));
-  if (tagline)
-    rows.push(dim4(tagline));
-  return rows;
+  const mid = Math.floor(mark.length / 2);
+  const below = [];
+  const rows = mark.map((r, i) => {
+    const left = caramel2(r.padEnd(ink)) + "   ";
+    if (i === mid)
+      return left + bold4(caramel2(name));
+    const sub2 = subs[i - mid - 1];
+    if (i > mid && sub2 !== undefined) {
+      if (ink + 3 + width2(sub2) <= room)
+        return left + sub2;
+      below.push(sub2);
+    }
+    return caramel2(r);
+  });
+  return [...rows, ...below];
 }
 function banner2(tagline = "your voice, from the terminal") {
-  return lockup2("innernote", tagline).map((r) => "  " + r).join(`
+  return lockup2("innernote", dim4(tagline)).map((r) => "  " + r).join(`
 `);
 }
 
@@ -1313,6 +1369,18 @@ var COMMANDS = {
     usage: "innernote week",
     detail: "Seven days across, so the gaps are visible before you read a word. Published is filled, scheduled is open."
   },
+  unqueue: {
+    summary: "pull a post back out of the queue before it goes live",
+    usage: "innernote unqueue <post-id>",
+    detail: "The undo for queue, while there is still time. The post returns to your drafts and nothing goes live. Once it has been published this refuses, because a live post cannot be unsent this way.",
+    examples: ["innernote unqueue p17abc...", "innernote unqueue 3"]
+  },
+  context: {
+    summary: "what you post about: your pillars and your series",
+    usage: "innernote context",
+    detail: "Your standing context: content pillars with their weights, and every running series with what it is about and what it is for. This is the thing to read before deciding what to write, and the thing an agent should read first for the same reason. --json prints the raw payload for scripts and models.",
+    examples: ["innernote context", "innernote context --json"]
+  },
   queue: {
     summary: "schedule a post into your next open slot",
     usage: "innernote queue <post-id>",
@@ -1342,12 +1410,12 @@ function commandHelp(name) {
   return lines.join(`
 `);
 }
-function wrap3(text, width2, indent) {
+function wrap3(text, width3, indent) {
   const words = text.split(/\s+/);
   const lines = [];
   let line = "";
   for (const w of words) {
-    if ((line + " " + w).trim().length > width2) {
+    if ((line + " " + w).trim().length > width3) {
       lines.push(indent + line.trim());
       line = w;
     } else {
@@ -1369,67 +1437,68 @@ function margin(rows) {
 `);
 }
 function landing(state) {
-  const rows = ["", ...lockup("innernote"), ""];
-  if (state.name) {
-    rows.push(state.name + (state.plan ? dim2(`   ${state.plan}`) : ""));
-  }
-  const sub = [];
+  const small = [];
+  if (state.plan)
+    small.push(state.plan);
   if (state.powers)
-    sub.push(state.powers);
-  if (typeof state.expiresInDays === "number" && state.expiresInDays <= 14) {
-    sub.push(`key expires in ${state.expiresInDays} ${state.expiresInDays === 1 ? "day" : "days"}`);
-  }
+    small.push(state.powers);
   if (state.version)
-    sub.push(`v${state.version}`);
-  if (sub.length)
-    rows.push(dim2(sub.join("   ")));
-  if (state.week?.length) {
-    rows.push("", ...state.week);
+    small.push(`v${state.version}`);
+  const sub = [];
+  if (state.name)
+    sub.push(`${bold2(state.name)}   ${dim2(small.join("   "))}`);
+  else if (small.length)
+    sub.push(dim2(small.join("   ")));
+  if (typeof state.expiresInDays === "number" && state.expiresInDays <= 14) {
+    sub.push(yellow2(`key expires in ${state.expiresInDays} ${state.expiresInDays === 1 ? "day" : "days"}`));
   }
+  const rows = ["", ...lockup("innernote", sub), ""];
+  if (state.week?.length)
+    rows.push(...state.week, "");
   const counts = [];
   if (state.ideas)
     counts.push(`${state.ideas} ${state.ideas === 1 ? "idea" : "ideas"} waiting`);
   if (state.drafts)
-    counts.push(`${state.drafts} drafts`);
+    counts.push(`${state.drafts} ${state.drafts === 1 ? "draft" : "drafts"}`);
   if (counts.length)
-    rows.push("", dim2(counts.join("   ")));
+    rows.push(dim2(counts.join("   ")));
   if (state.next) {
-    rows.push("", `${caramel(state.next.command)}${pad("", Math.max(1, 20 - width(state.next.command)))}${dim2(state.next.why)}`);
+    rows.push(`${caramel(state.next.command)}   ${dim2(state.next.why)}`);
   }
   rows.push("");
   return margin(rows);
 }
 function landingDisconnected(apiUrl, version) {
+  const host = apiUrl.replace(/^https?:\/\//, "");
+  const sub = [dim2("LinkedIn posts in your voice, from the terminal")];
+  if (version)
+    sub.push(dim2(`v${version}`));
   return margin([
     "",
-    ...lockup("innernote", "your voice, from the terminal"),
-    ...version ? [`  ${dim2(`v${version}`)}`] : [],
-    "",
-    dim2("Write LinkedIn posts in your voice, without leaving here."),
-    "",
-    `${caramel(`${CMD} login`)}${pad("", Math.max(3, 20 - width(`${CMD} login`)))}${dim2("connect this machine")}`,
-    dim2(`Get a code at ${apiUrl.replace(/^https?:\/\//, "")}/dashboard/settings`),
+    ...lockup("innernote", sub),
     "",
-    `${dim2("No account yet?")}  ${caramel(apiUrl.replace(/^https?:\/\//, ""))}`,
+    `${caramel(`${CMD} login`)}   ${dim2("connect this machine")}`,
+    dim2(`Get a code at ${host}/dashboard/settings`),
+    `${dim2("No account yet?")}   ${caramel(host)}`,
     ""
   ]);
 }
 function suggest(state) {
   if (state.scheduled === 0 && state.ideas > 0) {
-    return { command: `${CMD} ideas`, why: "nothing scheduled, and you have things saved" };
+    return { command: "ideas", why: "nothing scheduled, and you have things saved" };
   }
   if (state.scheduled === 0) {
-    return { command: `${CMD} write`, why: "the week is empty" };
+    return { command: "write", why: "the week is empty" };
   }
   if (state.ideas >= 5) {
-    return { command: `${CMD} ideas`, why: "your inbox is filling up" };
+    return { command: "ideas", why: "your inbox is filling up" };
   }
-  return { command: `${CMD} write`, why: "start something" };
+  return { command: "write", why: "start something" };
 }
 // package.json
 var package_default = {
   name: "innernote",
-  version: "0.1.2",
+  version: "0.3.1",
   description: "Write LinkedIn posts in your voice, from the terminal.",
   type: "module",
   bin: {
@@ -1437,6 +1506,7 @@ var package_default = {
   },
   files: [
     "dist",
+    "skills",
     "README.md"
   ],
   scripts: {
@@ -1466,7 +1536,7 @@ function powers2(scopes) {
     return scopes[0];
   return `${scopes.slice(0, -1).join(", ")} and ${scopes[scopes.length - 1]}`;
 }
-async function home() {
+async function home(inSession = false) {
   const config = await loadConfig();
   if (!config.token) {
     out();
@@ -1498,11 +1568,14 @@ async function home() {
 `).map((l) => l.replace(/^ {2}/, "")) : null,
     ideas: ideas2?.ideas.length,
     drafts: drafts2?.posts.length,
-    next: suggest({
-      scheduled,
-      ideas: ideas2?.ideas.length ?? 0,
-      drafts: drafts2?.posts.length ?? 0
-    })
+    next: (() => {
+      const n = suggest({
+        scheduled,
+        ideas: ideas2?.ideas.length ?? 0,
+        drafts: drafts2?.posts.length ?? 0
+      });
+      return inSession ? n : { ...n, command: `${CMD} ${n.command}` };
+    })()
   }));
   out();
   return 0;
@@ -1511,6 +1584,30 @@ async function home() {
 // src/session.ts
 import { createInterface } from "node:readline";
 
+// src/ghost.ts
+function ghostFor(line2, cursor, history, names) {
+  if (!line2 || cursor !== line2.length)
+    return null;
+  if (line2.startsWith(" "))
+    return null;
+  const fromHistory = history.find((h) => h.startsWith(line2) && h.length > line2.length);
+  if (fromHistory)
+    return fromHistory.slice(line2.length);
+  if (!line2.includes(" ")) {
+    const name = names.find((n) => n.startsWith(line2) && n.length > line2.length);
+    return name ? name.slice(line2.length) : null;
+  }
+  if (line2.startsWith("help ")) {
+    const arg = line2.slice(5);
+    if (arg && !arg.includes(" ")) {
+      const name = names.find((n) => n.startsWith(arg) && n.length > arg.length);
+      if (name)
+        return name.slice(arg.length);
+    }
+  }
+  return null;
+}
+
 // src/help.ts
 var COMMANDS2 = {
   login: {
@@ -1623,6 +1720,18 @@ var COMMANDS2 = {
     usage: "innernote week",
     detail: "Seven days across, so the gaps are visible before you read a word. Published is filled, scheduled is open."
   },
+  unqueue: {
+    summary: "pull a post back out of the queue before it goes live",
+    usage: "innernote unqueue <post-id>",
+    detail: "The undo for queue, while there is still time. The post returns to your drafts and nothing goes live. Once it has been published this refuses, because a live post cannot be unsent this way.",
+    examples: ["innernote unqueue p17abc...", "innernote unqueue 3"]
+  },
+  context: {
+    summary: "what you post about: your pillars and your series",
+    usage: "innernote context",
+    detail: "Your standing context: content pillars with their weights, and every running series with what it is about and what it is for. This is the thing to read before deciding what to write, and the thing an agent should read first for the same reason. --json prints the raw payload for scripts and models.",
+    examples: ["innernote context", "innernote context --json"]
+  },
   queue: {
     summary: "schedule a post into your next open slot",
     usage: "innernote queue <post-id>",
@@ -1652,12 +1761,12 @@ function commandHelp2(name) {
   return lines.join(`
 `);
 }
-function wrap4(text, width2, indent) {
+function wrap4(text, width3, indent) {
   const words = text.split(/\s+/);
   const lines = [];
   let line2 = "";
   for (const w of words) {
-    if ((line2 + " " + w).trim().length > width2) {
+    if ((line2 + " " + w).trim().length > width3) {
       lines.push(indent + line2.trim());
       line2 = w;
     } else {
@@ -1729,6 +1838,40 @@ function indented(run) {
   };
   return run().finally(restore);
 }
+function armGhost(rl, names, promptWidth) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY)
+    return;
+  if (dim2("x") === "x")
+    return;
+  const inner = rl;
+  let shown = null;
+  const clear = () => {
+    if (shown == null)
+      return;
+    process.stdout.write("\x1B[K");
+    shown = null;
+  };
+  const draw = () => {
+    if (process.stdin.isPaused())
+      return;
+    const rest = ghostFor(inner.line ?? "", inner.cursor ?? 0, inner.history ?? [], names);
+    if (!rest)
+      return;
+    const cols = process.stdout.columns || 80;
+    if (promptWidth() + (inner.line?.length ?? 0) + rest.length >= cols - 1)
+      return;
+    process.stdout.write(`${dim2(rest)}\x1B[${rest.length}D`);
+    shown = rest;
+  };
+  process.stdin.prependListener("keypress", (_ch, key) => {
+    const offered = shown;
+    clear();
+    if (key?.name === "right" && offered && inner.cursor === inner.line.length) {
+      rl.write(offered);
+    }
+    setImmediate(draw);
+  });
+}
 async function session(opts) {
   await opts.intro();
   const names = [...Object.keys(COMMANDS2), ...BUILTINS];
@@ -1746,7 +1889,8 @@ async function session(opts) {
       return [hits.length ? hits : names, line2];
     }
   });
-  console.log(`  ${dim2("Type a command, or")} ${caramel("help")}${dim2(". Ctrl-C twice to leave.")}
+  armGhost(rl, names, () => width(promptFor()));
+  console.log(`  ${dim2("Type a command, or")} ${caramel("help")}${dim2(". Right arrow takes the hint. Ctrl-C twice to leave.")}
 `);
   rl.prompt();
   return new Promise((resolve) => {
@@ -1848,8 +1992,8 @@ function whatThereIs() {
   ];
   const groups = [
     ["Writing", ["write", "shape", "ask", "save", "capture"]],
-    ["Looking", ["show", "ideas", "drafts", "open", "week", "whoami"]],
-    ["Shipping", ["queue"]],
+    ["Looking", ["show", "ideas", "drafts", "open", "week", "context", "whoami"]],
+    ["Shipping", ["queue", "unqueue"]],
     ["Connection", ["login", "logout"]]
   ];
   for (const [title, cmds] of groups) {
@@ -1878,8 +2022,8 @@ function commandList() {
   const groups = [
     ["Getting connected", ["login", "logout", "whoami"]],
     ["Writing", ["write", "shape", "ask", "save", "capture"]],
-    ["Looking", ["show", "ideas", "drafts", "open", "week"]],
-    ["Shipping", ["queue"]]
+    ["Looking", ["show", "ideas", "drafts", "open", "week", "context"]],
+    ["Shipping", ["queue", "unqueue"]]
   ];
   const lines = [];
   for (const [title, names] of groups) {
@@ -1904,6 +2048,7 @@ var HELP = () => [
 ].join(`
 `);
 var COMMANDS3 = {
+  context,
   login,
   logout: () => logout(),
   whoami,
@@ -1918,7 +2063,8 @@ var COMMANDS3 = {
   drafts,
   open,
   week,
-  queue
+  queue,
+  unqueue
 };
 async function main() {
   const [, , command, ...args] = process.argv;
@@ -1927,7 +2073,7 @@ async function main() {
       return home();
     return session({
       intro: async () => {
-        await home();
+        await home(true);
       },
       status: () => {
         const d = getDraft2();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "innernote",
-  "version": "0.1.2",
+  "version": "0.3.1",
   "description": "Write LinkedIn posts in your voice, from the terminal.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "scripts": {

package/skills/innernote-cli/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: innernote-cli
+description: Drive the innernote CLI (`npx innernote`) to help someone write, save and schedule LinkedIn posts in their own voice from the terminal. Use this whenever the user mentions innernote, asks to draft or queue a LinkedIn post from the command line, wants their posting week or captured ideas checked, or asks you to capture a thought for later, even if they do not name the CLI. Also use it before touching any `innernote` command in a script.
+---
+
+# Driving the innernote CLI
+
+innernote holds this person's writing voice: how they write, what they post
+about, and their posting schedule. The CLI is a thin client over the same
+service the app uses, so a draft made here sounds like THEM, not like you,
+and everything you save appears in their app.
+
+## The contract, before any command
+
+- **stdout is data, stderr is narration.** The post text, JSON and ids go to
+  stdout; spinners, notes and errors go to stderr. Pipe stdout with
+  confidence, and never parse the human-facing view: every read command takes
+  `--json`, which prints the API payload and nothing else.
+- **Exit codes are the protocol.** `0` worked. `1` failed, reason on stderr.
+  `2` not connected: stop and ask the user to run `npx innernote login`.
+  `3` the account cannot do this right now: a paywall or a spent allowance,
+  never a bug. Only `1` is worth debugging.
+- **A refusal is a sentence for the user, not an obstacle for you.** When a
+  command refuses (a limit, a missing cadence, no such post), the message is
+  already written for the person. Show it to them verbatim and stop. Do not
+  retry, and do not work around it.
+
+## Connecting
+
+Check with `innernote whoami` (exit `2` means not connected). Connecting
+needs a pairing code from the user's Settings page at
+innernote.space/dashboard/settings; you cannot get one yourself. Ask them
+for it, then run `innernote login THEIR-CODE`. The code works once and
+expires in ten minutes. `INNERNOTE_TOKEN` in the environment overrides the
+stored key, which is how CI and scripts authenticate.
+
+## Read before you write
+
+Suggestions that ignore what this person posts about are generic advice,
+which is the one thing innernote exists to prevent.
+
+```bash
+innernote context --json    # their content pillars and running series
+innernote week --json       # what is scheduled over the next seven days
+innernote ideas --json      # thoughts they captured and have not written
+innernote drafts --json     # saved posts, newest first, with ids
+```
+
+Start with `context` and `week` when helping them decide what to write: an
+empty week is a real answer, and a post should land inside a pillar or a
+series they have committed to.
+
+## The writing loop
+
+**Capture** the moment something is worth posting about later:
+
+```bash
+innernote capture "their thought, in their words"
+git log --oneline -20 | innernote capture      # stdin works too
+```
+
+Capture their framing, not your tidied summary. Their phrasing carries their
+voice; a summary throws it away.
+
+**Draft and keep** in one command:
+
+```bash
+innernote write "their rough thought or topic, in their words" --save
+innernote write "next part of the hiring story" --series "Build in Public" --save
+```
+
+Pass their OWN WORDS as the argument, as fully as you have them. `write`
+takes a whole messy thought, and any shaping you already know they want
+(shorter, no list, warmer ending) belongs in that ask, phrased plainly.
+`--series` takes the series NAME; a wrong name refuses with the real list,
+so correct from that and retry once. The saved id is printed on stderr and
+`innernote drafts --json` lists it first.
+
+**Shaping an already-saved post is not yours to finish here.** Each CLI
+invocation is a fresh process, so the flag form of `shape` transforms
+stdin to stdout without saving:
+
+```bash
+innernote shape shorter punchier < draft.txt   # transformed text, NOT saved
+```
+
+Use that for showing the person options. To revise and keep, fold the
+direction into a fresh `write ... --save`, or hand them to the app or the
+interactive session (`innernote` on its own), where reshaping a held draft
+does persist.
+
+## Scheduling: the one action that reaches other people
+
+`innernote queue <id>` schedules a saved post into their next open slot,
+and it then goes live on LinkedIn on its own. Nobody presses anything
+again, and a live post cannot be unsent.
+
+So queue ONLY when the user has clearly told you to queue that specific
+post. Never as a helpful next step, never to tidy up. If they have not said
+so, tell them it is saved and stop. The undo exists while it is still
+pending:
+
+```bash
+innernote queue p17abc...     # their explicit ask, and only then
+innernote unqueue p17abc...   # back to drafts, nothing goes out
+```
+
+If `queue` exits `3`, their plan or allowance is the reason; show the
+message, which says where to fix it, and leave the decision with them.
+
+## Worked example
+
+The user says: "turn what I told you about interview homework into a post
+for my build-in-public series, keep it short, and line it up for this week."
+
+```bash
+innernote context --json          # confirm the series name
+innernote week --json             # is there an open day?
+innernote write "interview homework filters for free time, not talent. we swapped ours for a paid 40 minute working session and offer accepts went up. keep it short." --series "Build in Public" --save
+innernote drafts --json           # take the first id
+innernote queue <that-id>         # they said "line it up": that is the go-ahead
+```
+
+Then tell them what was drafted, where it was queued, and that `unqueue`
+takes it back any time before it goes live.