sumibako 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# sumibako
+
+File the plans, specs and notes your coding agent writes into your
+[Sumibako](https://sumibako.com) vault, and get a link you can send to someone.
+
+```bash
+npx sumibako login
+npx sumibako publish docs/plans/auth-rewrite.md --public
+```
+
+```
+Created Auth rewrite plan
+https://sumibako.com/vault/Auth-rewrite-plan-jd76...
+
+Share this: https://sumibako.com/p/Auth-rewrite-plan-jd76...
+```
+
+## Why
+
+Coding agents write a lot of prose that is worth keeping: implementation plans,
+specs, architecture decisions, migration checklists, handoff notes. It ends up
+as untracked Markdown in a working directory, or pasted into a chat, and then
+somebody asks "can you send me that plan" and there is nothing to send.
+
+Each agent has its own answer to this, and each answer only covers that agent's
+own output and lives on that vendor's domain. This is one place for all of them,
+in a vault you already own, where the document is a page you can keep editing.
+
+## Setup
+
+Create a token in Sumibako under **Settings, Coding agents**, then:
+
+```bash
+npx sumibako login
+```
+
+The token is stored in `~/.sumibako/config.json` with owner-only permissions.
+`SUMIBAKO_TOKEN` in the environment overrides it, which is what CI should use.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `sumibako login` | Save a token on this machine |
+| `sumibako publish <file.md>` | File a Markdown file as a page |
+| `sumibako publish <file.md> --public` | And put it on the web, printing the link |
+| `sumibako unpublish <file.md>` | Take the page off the web |
+| `sumibako append <file.md> "text"` | Add to the end of a page |
+| `sumibako edit <file.md> --find ... --replace ...` | Replace one exact piece of text |
+| `sumibako open <file.md>` | Print the links for a page (`--markdown` for the page) |
+| `sumibako search [words]` | Search your vault, or list it with no words |
+| `sumibako whoami` | Check the token, plan and usage |
+| `sumibako logout` | Forget the token on this machine |
+
+### Options for `publish`
+
+| Option | Meaning |
+| --- | --- |
+| `--public` | Publish it and print a shareable link |
+| `--title <title>` | Override the title, which otherwise comes from the first heading |
+| `--key <key>` | Set the artifact's identity yourself |
+| `--new` | File a new page even if this file was filed before |
+| `--parent <page-id>` | Nest it under an existing page |
+
+### Options for `append` and `edit`
+
+| Option | Meaning |
+| --- | --- |
+| `--prepend` | Add to the start of the page instead of the end |
+| `--find <text>` | The exact text to replace, as `open --markdown` prints it |
+| `--replace <text>` | What to put there; an empty string deletes the matched text |
+| `--title <title>` | Rename the page |
+| `--key <key>` | Name the page by its key rather than by a path or an id |
+
+## Changing a page without re-sending it
+
+`publish` replaces the whole page. When you only want to add a line, or fix a
+sentence in a page you no longer have on disk, read it and change that part:
+
+```bash
+sumibako open docs/plans/auth.md --markdown
+sumibako append docs/decisions.md "- chose Postgres over Dynamo"
+sumibako edit docs/plans/auth.md --find "ship in Q3" --replace "ship in Q4"
+```
+
+`--find` matches against the Markdown `open --markdown` prints, and has to
+match exactly once. If it appears twice the command refuses rather than picking
+one, because picking one is how the wrong paragraph gets rewritten and nobody
+finds out. Quote more of the surrounding lines.
+
+The page's previous version is kept for fourteen days either way, and **Version
+history** in the document menu puts it back.
+
+## Publishing the same file twice
+
+A file is filed under its path in the repository, so running `publish` again
+updates the same page rather than making another one. That is the behaviour you
+want when an agent revises a plan five times in a session: one page, one link,
+always current.
+
+Pass `--new` when you really do want a second page, or `--key` to choose the
+identity yourself (useful when the file moves but the artifact does not).
+
+## What survives the conversion
+
+Headings, paragraphs, bold, italic, strikethrough, inline code, links, bullet
+lists, numbered lists, task lists, nested lists, blockquotes, GitHub alerts
+(`> [!NOTE]`), tables, fenced code with syntax highlighting, images on their own
+line, and horizontal rules.
+
+Two things degrade, and the command says so when they do:
+
+- **Mermaid** renders as a plain code block. There is no diagram renderer.
+- **Raw HTML** is kept as text.
+
+## Privacy
+
+Pages are private until you pass `--public`. A published page has a link anyone
+can open, and carries `noindex` so search engines do not list it. Making a page
+findable in search is a separate opt-in that only you can give, per page, in the
+app - a token cannot do it.
+
+## For agents
+
+`SKILL.md` in this package is written for a coding agent to read. Point Claude
+Code, Codex or Cursor at it and they will use the CLI correctly, including the
+part about not creating duplicates.
+
+## If your agent has no shell
+
+Claude.ai and ChatGPT cannot run this. They can reach an MCP server, so there is
+one at `https://sumibako.com/api/mcp` offering the same things as tools:
+`write_page`, `read_page`, `edit_page`, `search_pages`, `publish_page` and
+`get_account`. Add it as an MCP server and send the same token as an
+`Authorization: Bearer` header.
+
+Prefer the CLI where a shell exists. An MCP tool call carries the whole document
+through the model's context to get there, so a 30KB plan costs 30KB of tokens;
+this reads the file off disk and the model never holds it.
+
+## Environment
+
+| Variable | Meaning |
+| --- | --- |
+| `SUMIBAKO_TOKEN` | Use this token instead of the saved one |
+| `SUMIBAKO_API` | Point at a different deployment |
+| `NO_COLOR` | Turn off colour |

package/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: sumibako
+description: File a plan, spec, ADR, handoff note or research report into the user's Sumibako vault and get back a link they can send to someone. Use when the user asks to save, file, publish or share a document you wrote, or asks for "a link to this", or says a teammate needs to read it. Also use to read, amend or take down a page already in the vault, and to search what is there before writing something new.
+---
+
+# Filing documents in Sumibako
+
+Sumibako is the user's notes vault. This skill puts a Markdown document you
+wrote into it and, on request, gives you a public link to hand back.
+
+## When to use this
+
+Reach for it when a document you produced needs to outlive the session or be
+read by somebody who is not in it:
+
+- The user says "save this", "file this", "put this in my notes", "publish
+  this", "give me a link", "send this to my team", "I need to share this".
+- You finished a plan, spec, design, ADR, migration checklist, incident
+  write-up, research summary or handoff note, and the user wants to keep it.
+- You are picking up work and want to know what is already written down:
+  `sumibako search`, or `sumibako search` with no words to see the vault.
+- The user wants something already filed changed: a section added to a running
+  log, a decision corrected, a page taken back off the web.
+
+Do **not** use it for things that belong in the repository. Code, tests,
+configuration and specs that are reviewed alongside a diff go in the repo and
+through a pull request. This is for the documents whose audience is a person,
+not a compiler, and often a person who will never open the repo.
+
+## Setup
+
+The user needs a token once, from Settings then Coding agents in Sumibako.
+
+```bash
+npx sumibako login            # prompts for the token
+npx sumibako whoami           # confirms it works
+```
+
+If a command reports no token, stop and ask the user to create one rather than
+guessing at credentials.
+
+## Filing a document
+
+Write the Markdown to a file first, then publish the file. Do not pipe a
+document through the command line.
+
+```bash
+npx sumibako publish docs/plans/auth-rewrite.md
+```
+
+To get a link the user can send to someone:
+
+```bash
+npx sumibako publish docs/plans/auth-rewrite.md --public
+```
+
+The command prints the page's link, and the public link when there is one.
+Give the user the public link verbatim. Do not paraphrase or shorten it.
+
+## The one rule that matters
+
+**A file is filed under its path in the repository, so publishing the same file
+again updates the same page.** Run it after every revision. You will not create
+duplicates, and the user's link keeps working and keeps showing the current
+version.
+
+Only pass `--new` when the user genuinely wants a second, separate page - a new
+incident, a different feature. Reaching for it out of caution is how a vault
+fills up with eleven copies of one plan.
+
+## Changing a page instead of replacing it
+
+`publish` replaces the whole page, which is right when you still hold the file.
+When you do not - the page was written in the app, or in a session that has
+ended - read it and change the part that is wrong:
+
+```bash
+npx sumibako open docs/plans/auth.md --markdown   # the page, as Markdown
+```
+
+That Markdown is the page. Add to it, or replace an exact piece of it:
+
+```bash
+# add a line to the end, without sending the rest back
+npx sumibako append docs/decisions.md "- 2026-09-06: chose Postgres over Dynamo"
+
+# correct one sentence
+npx sumibako edit docs/plans/auth.md \
+  --find "We will ship this in Q3." \
+  --replace "We will ship this in Q4, after the migration."
+
+# rename
+npx sumibako edit docs/plans/auth.md --title "Auth rewrite, revised"
+```
+
+**`--find` must match exactly once.** It is matched against the Markdown that
+`open --markdown` prints, not against the words as they look in the app, so
+read the page first and paste from what you read. If it appears twice the
+command refuses rather than guessing - quote more of the surrounding lines and
+try again. Do not work around this by replacing the whole page unless the user
+asked for a rewrite.
+
+Prefer `append` over reading and re-publishing a page you are only adding to.
+It sends one line instead of the whole document and cannot disturb the rest.
+
+## The rest of the commands
+
+```bash
+npx sumibako search "auth rewrite"       # what is already written down
+npx sumibako search                      # or list the newest pages
+npx sumibako open docs/plans/auth.md     # the links for a page
+npx sumibako open docs/plans/auth.md --markdown   # and the page itself
+npx sumibako unpublish docs/plans/auth.md     # take the link off the web
+```
+
+## Writing for it
+
+The document is rendered as a real page, so ordinary Markdown pays off:
+
+- **The first heading becomes the page title.** Start with one `#` line saying
+  what the document is. Or put `title:` in YAML frontmatter.
+- Headings, lists, task lists, tables, blockquotes, links and fenced code all
+  render properly. Tables are worth using for options and trade-offs.
+- Code fences keep their language and get syntax highlighting.
+- `> [!NOTE]` and `> [!WARNING]` become a bold label on the quote.
+
+Two things degrade, and the command tells you when they do:
+
+- **Mermaid diagrams** render as plain code, not pictures. A short prose
+  description alongside the diagram is worth adding.
+- **Raw HTML** is kept as text.
+
+## What it will not do
+
+- It cannot delete a page. The user does that in the app. `unpublish` takes the
+  link off the web and leaves the writing alone.
+- It cannot make a page findable by search engines. Published pages carry
+  `noindex`; the user turns that on themselves if they want it, per page.
+- It cannot read or write anyone else's vault.
+
+## Errors worth reading
+
+- `400` - the request was wrong, and the message says how. From an edit this
+  is usually a `--find` that matched nothing or matched twice. Read the page
+  with `open --markdown` and quote it exactly.
+- `401` - the token is missing, wrong or revoked. Ask the user for a new one.
+- `403` - the token is not allowed to publish. The user can create one that is.
+- `409` - the plan's page limit is reached. Report the message; it says which.
+- `413` - the document is too long. Split it.
+- `429` - too many requests. Wait the number of seconds it names.

package/index.mjs

@@ -0,0 +1,613 @@
+#!/usr/bin/env node
+/**
+ * sumibako - file what your coding agent wrote into your vault.
+ *
+ * Zero dependencies, one file, Node 18 or newer. That is a deliberate ceiling:
+ * this runs inside somebody else's agent session, often on a machine where the
+ * install has to be instant and silent, and a dependency tree is a thing that
+ * can break there in ways nobody will debug.
+ *
+ * Why a CLI at all, when the same job could be an MCP server. Two reasons that
+ * matter in practice. An MCP tool call carries the document through the model's
+ * context to get it to the server, so filing a 30KB plan means re-emitting
+ * 30KB of tokens; `sumibako publish plan.md` sends a file the agent has already
+ * written to disk, and the model never sees it twice. And a shell exists in
+ * every coding agent there is, while MCP support differs between them and
+ * changes with the spec. An MCP server can come later and reuse this same API.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import readline from "node:readline";
+
+const VERSION = "0.1.0";
+
+/** Where the token lives when it is not in the environment. */
+const CONFIG_DIR = path.join(os.homedir(), ".sumibako");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+
+/**
+ * Where the API lives.
+ *
+ * The app's own domain rather than the Convex deployment behind it. This string
+ * ends up in config files, CI secrets and other people's shell history, so it
+ * has to be one that stays true - `next.config.mjs` rewrites it onto whichever
+ * deployment is current.
+ */
+const DEFAULT_API = "https://sumibako.com/api/agent";
+
+// ---------------------------------------------------------------------------
+// Output
+// ---------------------------------------------------------------------------
+
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+/**
+ * ANSI colour, with the escape byte written as an escape rather than typed.
+ *
+ * A literal escape character in source is invisible in every diff and every
+ * review, and survives exactly until something normalises the file.
+ */
+const ESC = "\u001b";
+const paint = (code, text) =>
+  useColor ? `${ESC}[${code}m${text}${ESC}[0m` : text;
+const dim = (text) => paint("2", text);
+const bold = (text) => paint("1", text);
+const green = (text) => paint("32", text);
+const red = (text) => paint("31", text);
+const yellow = (text) => paint("33", text);
+
+function die(message, hint) {
+  console.error(`${red("error")}  ${message}`);
+  if (hint) console.error(dim(`        ${hint}`));
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + "\n", {
+    // The file holds a live credential. 0600 is the difference between "only
+    // me" and "every process running as any user on this machine", and it
+    // costs one argument. Windows ignores the mode, which is why the token is
+    // also accepted from the environment.
+    mode: 0o600,
+  });
+  try {
+    fs.chmodSync(CONFIG_FILE, 0o600);
+  } catch {
+    // Best effort: some filesystems do not support it.
+  }
+}
+
+/**
+ * The token, from the environment first and the config file second.
+ *
+ * Environment first so CI can inject one without writing to a home directory
+ * that may not persist, and so a person can override a stale saved token for
+ * one command without editing a file.
+ */
+function resolveToken() {
+  const fromEnv = process.env.SUMIBAKO_TOKEN?.trim();
+  if (fromEnv) return fromEnv;
+  return readConfig().token ?? null;
+}
+
+function resolveApi() {
+  return (
+    process.env.SUMIBAKO_API?.trim().replace(/\/+$/, "") ||
+    readConfig().api ||
+    DEFAULT_API
+  );
+}
+
+// ---------------------------------------------------------------------------
+// HTTP
+// ---------------------------------------------------------------------------
+
+async function callApi(method, endpoint, { body, token, query, api } = {}) {
+  const base = api ?? resolveApi();
+  const url = new URL(base + endpoint);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+  }
+
+  const authToken = token ?? resolveToken();
+  if (!authToken) {
+    die(
+      "No token. Run `npx sumibako login` first.",
+      "Create one in Sumibako under Settings, Coding agents.",
+    );
+  }
+
+  let response;
+  try {
+    response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+        ...(body ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+  } catch (error) {
+    die(
+      `Could not reach ${url.origin}.`,
+      error instanceof Error ? error.message : undefined,
+    );
+  }
+
+  const text = await response.text();
+  const contentType = response.headers.get("content-type") ?? "";
+
+  let payload = null;
+  if (text && contentType.includes("json")) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      // Handled below, along with every other not-our-API response.
+    }
+  }
+
+  /*
+    Reached a server, but not this API.
+
+    Overwhelmingly this means the base URL points at the web app rather than the
+    API, and the app answered with an HTML page. Printing that page is how a
+    one-line configuration mistake turns into a screenful of markup with the
+    actual problem nowhere in it, so the body is deliberately not shown.
+  */
+  if (payload === null) {
+    die(
+      `${base} is not answering as the Sumibako API (HTTP ${response.status}, ${contentType || "no content type"}).`,
+      "Check the address: pass --api <url>, or set SUMIBAKO_API.",
+    );
+  }
+
+  if (!response.ok) {
+    const message = payload?.error?.message ?? text.slice(0, 300) ?? "Request failed.";
+    const code = payload?.error?.code;
+
+    // The three failures worth explaining rather than just reporting, because
+    // each has a next step the person cannot guess from the message alone.
+    if (response.status === 401) {
+      die(message, "Run `npx sumibako login` with a fresh token.");
+    }
+    if (response.status === 403) {
+      die(message, "Create a token with publishing allowed, in Settings.");
+    }
+    if (response.status === 429) {
+      const retry = response.headers.get("Retry-After");
+      die(message, retry ? `Wait ${retry} seconds and try again.` : undefined);
+    }
+    die(`${message}${code ? dim(`  (${code})`) : ""}`);
+  }
+
+  return payload;
+}
+
+// ---------------------------------------------------------------------------
+// Arguments
+// ---------------------------------------------------------------------------
+
+/** Parses `--flag value`, `--flag=value` and `--boolean` into an object. */
+function parseFlags(argv) {
+  const flags = {};
+  const positional = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) {
+      positional.push(item);
+      continue;
+    }
+    const equals = item.indexOf("=");
+    if (equals !== -1) {
+      flags[item.slice(2, equals)] = item.slice(equals + 1);
+      continue;
+    }
+    const name = item.slice(2);
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      flags[name] = true;
+    } else {
+      flags[name] = next;
+      index += 1;
+    }
+  }
+
+  return { flags, positional };
+}
+
+/**
+ * The key a file is filed under, so re-running lands on one page.
+ *
+ * The repo-relative path, because that is the identity of an artifact that a
+ * person and an agent will both agree on: `docs/plans/auth.md` is the plan for
+ * auth, this week and next. Falls back to the path as given when the file sits
+ * outside a git repository.
+ *
+ * Normalised to forward slashes so the same file keyed from Windows and from
+ * CI resolves to the same page.
+ */
+function defaultKey(filePath) {
+  const absolute = path.resolve(filePath);
+  let directory = path.dirname(absolute);
+
+  for (let depth = 0; depth < 40; depth += 1) {
+    if (fs.existsSync(path.join(directory, ".git"))) {
+      return path.relative(directory, absolute).split(path.sep).join("/");
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+
+  return absolute.split(path.sep).join("/");
+}
+
+function readMarkdown(filePath) {
+  if (filePath === "-") {
+    return fs.readFileSync(0, "utf8");
+  }
+  if (!fs.existsSync(filePath)) {
+    die(`No such file: ${filePath}`);
+  }
+  const stats = fs.statSync(filePath);
+  if (stats.isDirectory()) {
+    die(`${filePath} is a directory. Point at one Markdown file.`);
+  }
+  return fs.readFileSync(filePath, "utf8");
+}
+
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+
+async function login(flags) {
+  let token = typeof flags.token === "string" ? flags.token.trim() : "";
+
+  if (!token) {
+    if (!process.stdin.isTTY) {
+      die(
+        "No token given.",
+        "Pass --token <token>, or set SUMIBAKO_TOKEN in the environment.",
+      );
+    }
+    console.log(
+      `Create a token in Sumibako under ${bold("Settings, Coding agents")}, then paste it here.`,
+    );
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    token = (await new Promise((resolve) => rl.question("Token: ", resolve))).trim();
+    rl.close();
+  }
+
+  if (!token) die("No token given.");
+
+  const api = typeof flags.api === "string" ? flags.api.replace(/\/+$/, "") : undefined;
+
+  // Checked before anything is saved, so a mistyped token or a wrong address
+  // fails here rather than halfway through the next session - and a failed
+  // login leaves whatever was configured before it untouched.
+  const who = await callApi("GET", "/v1/whoami", { token, api });
+
+  writeConfig({ ...readConfig(), token, ...(api ? { api } : {}) });
+
+  console.log(
+    `${green("Signed in.")} Plan ${bold(who.plan)}, can ${who.scopes
+      .map((scope) => scope.replace("pages:", ""))
+      .join(", ")}.`,
+  );
+  console.log(dim(`Token saved to ${CONFIG_FILE}`));
+}
+
+function logout() {
+  const config = readConfig();
+  delete config.token;
+  writeConfig(config);
+  console.log(`${green("Signed out.")} The token was removed from this machine.`);
+  console.log(dim("Revoke it in Settings if it may have leaked."));
+}
+
+async function publish(positional, flags) {
+  const file = positional[0];
+  if (!file) {
+    die("Which file?", "Usage: sumibako publish <file.md> [--public]");
+  }
+
+  const markdown = readMarkdown(file);
+  if (!markdown.trim()) die(`${file} is empty.`);
+
+  const key =
+    typeof flags.key === "string"
+      ? flags.key
+      : flags.new === true || file === "-"
+        ? undefined
+        : defaultKey(file);
+
+  const wantsPublic = flags.public === true || flags.publish === true;
+
+  const result = await callApi("POST", "/v1/pages", {
+    body: {
+      markdown,
+      externalId: key,
+      title: typeof flags.title === "string" ? flags.title : undefined,
+      parentDocument: typeof flags.parent === "string" ? flags.parent : undefined,
+      publish: wantsPublic ? true : undefined,
+    },
+  });
+
+  report(result, { verb: result.created ? "Created" : "Updated" });
+}
+
+/**
+ * Works out whether an argument names a file on disk or a page id.
+ *
+ * A file that exists is keyed by its repo path, the same way `publish` filed
+ * it. Anything else is taken to be a page id, which is what someone pastes
+ * after copying it out of a URL.
+ */
+function targetFor(argument, flags) {
+  if (typeof flags.key === "string") return { externalId: flags.key };
+  if (!argument) return {};
+  if (fs.existsSync(argument)) return { externalId: defaultKey(argument) };
+  return { documentId: argument };
+}
+
+/**
+ * Adds to a page without sending it back.
+ *
+ * The running-log case, which `publish` handles badly: filing a note at the
+ * end of a session with `publish` means reading the whole page, adding a line
+ * and writing all of it again. Here the text to add is the only thing that
+ * crosses the wire.
+ *
+ * Words after the target are the text. With none, it is read from stdin, so
+ * `git log -1 --format=%s | sumibako append CHANGELOG.md` works.
+ */
+async function append(positional, flags) {
+  const target = targetFor(positional[0], flags);
+  if (!target.documentId && !target.externalId) {
+    die("Which page?", "Usage: sumibako append <file.md | page-id> \"text\"");
+  }
+
+  const inline = positional.slice(1).join(" ");
+  const text = inline || fs.readFileSync(0, "utf8");
+  if (!text.trim()) {
+    die("Nothing to add.", "Pass the text as an argument or pipe it in.");
+  }
+
+  const result = await callApi("PATCH", "/v1/pages", {
+    body: {
+      ...target,
+      [flags.prepend === true ? "prepend" : "append"]: text,
+    },
+  });
+  report(result, {
+    verb: flags.prepend === true ? "Prepended to" : "Appended to",
+  });
+}
+
+/**
+ * Replaces one exact piece of text in a page.
+ *
+ * `--find` matches against the page's Markdown, which is what `open
+ * --markdown` prints, so the way to use this is to look first and paste. The
+ * API refuses a match that is not unique rather than guessing, so a failure
+ * here means "say more", not "try again".
+ */
+async function edit(positional, flags) {
+  const target = targetFor(positional[0], flags);
+  if (!target.documentId && !target.externalId) {
+    die(
+      "Which page?",
+      "Usage: sumibako edit <file.md | page-id> --find <old> --replace <new>",
+    );
+  }
+
+  const rename = typeof flags.title === "string" ? flags.title : undefined;
+  const find = typeof flags.find === "string" ? flags.find : undefined;
+  if (find === undefined && rename === undefined) {
+    die(
+      "Nothing to change.",
+      "Pass --find with --replace, or --title to rename the page.",
+    );
+  }
+  // An empty --replace is a deletion, and has to survive the default below.
+  const replace = typeof flags.replace === "string" ? flags.replace : "";
+
+  const result = await callApi("PATCH", "/v1/pages", {
+    body: {
+      ...target,
+      ...(find !== undefined ? { find, replace } : {}),
+      ...(rename !== undefined ? { title: rename } : {}),
+    },
+  });
+  report(result, { verb: "Edited" });
+}
+
+async function unpublish(positional, flags) {
+  const target = targetFor(positional[0], flags);
+  if (!target.documentId && !target.externalId) {
+    die("Which page?", "Usage: sumibako unpublish <file.md | page-id>");
+  }
+
+  const result = await callApi("POST", "/v1/pages/publish", {
+    body: { ...target, publish: false },
+  });
+  console.log(`${green("Taken down.")} ${bold(result.title)} is private again.`);
+  console.log(dim(result.url));
+}
+
+async function open(positional, flags) {
+  const target = targetFor(positional[0], flags);
+  if (!target.documentId && !target.externalId) {
+    die("Which page?", "Usage: sumibako open <file.md | page-id>");
+  }
+
+  const page = await callApi("GET", "/v1/pages", {
+    query: { id: target.documentId, externalId: target.externalId },
+  });
+  console.log(bold(page.title));
+  console.log(page.url);
+  if (page.publicUrl) console.log(green(page.publicUrl));
+
+  // Two names for one thing. `--text` came first and is in people's scripts;
+  // Markdown is strictly the better answer, because it is what you edit and
+  // send back, so both flags print it rather than keeping a worse output alive
+  // for the sake of a flag name.
+  if (flags.markdown === true || flags.text === true) {
+    console.log();
+    console.log(page.markdown || page.text);
+    for (const warning of page.markdownWarnings ?? []) {
+      console.log(yellow(`note   ${warning}`));
+    }
+  }
+}
+
+async function search(positional) {
+  // No words is a question too: "what is in here". It lists the newest pages
+  // rather than explaining the command to somebody who has just been handed a
+  // vault they have never seen.
+  const term = positional.join(" ").trim();
+
+  const { results } = await callApi("GET", "/v1/pages/search", {
+    query: { q: term || undefined, limit: term ? undefined : 20 },
+  });
+
+  if (results.length === 0) {
+    console.log(dim(term ? "Nothing matched." : "This vault has no pages yet."));
+    return;
+  }
+  for (const page of results) {
+    console.log(`${bold(page.title)}${page.publicUrl ? green("  public") : ""}`);
+    console.log(dim(`  ${page.publicUrl ?? page.url}`));
+  }
+}
+
+async function whoami() {
+  const who = await callApi("GET", "/v1/whoami");
+  const usage = await callApi("GET", "/v1/usage");
+  console.log(`Plan ${bold(who.plan)} at ${who.site}`);
+  console.log(`Permissions: ${who.scopes.join(", ")}`);
+  console.log(
+    `Pages: ${usage.documents} of ${limit(usage.maxDocuments)}   Published: ${usage.published} of ${limit(usage.maxPublished)}`,
+  );
+}
+
+const limit = (value) => (value === null || !Number.isFinite(value) ? "unlimited" : value);
+
+/** Prints the outcome of a write, link last so it is the easiest thing to copy. */
+function report(result, { verb }) {
+  console.log(`${green(verb)} ${bold(result.title)}`);
+  for (const warning of result.warnings ?? []) {
+    console.log(`${yellow("note")}   ${warning}`);
+  }
+  console.log(dim(result.url));
+  if (result.publicUrl) {
+    console.log();
+    console.log(`${bold("Share this:")} ${result.publicUrl}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Entry
+// ---------------------------------------------------------------------------
+
+const HELP = `
+${bold("sumibako")} - file what your coding agent wrote into your vault
+
+  ${bold("sumibako login")} [--token <t>] [--api <url>]  save a token on this machine
+  ${bold("sumibako publish")} <file.md> [--public]  file a Markdown file as a page
+  ${bold("sumibako unpublish")} <file.md>           take a published page off the web
+  ${bold("sumibako append")} <file.md> <text>       add to the end of a page
+  ${bold("sumibako edit")} <file.md> --find ...     replace one piece of text
+  ${bold("sumibako open")} <file.md> [--markdown]   print the links, or the page
+  ${bold("sumibako search")} [words]                search your vault, or list it
+  ${bold("sumibako whoami")}                        check the token and plan
+  ${bold("sumibako logout")}                        forget the token
+
+${bold("Options for publish")}
+  --public            publish it and print a shareable link
+  --title <title>     override the title (default: the first heading)
+  --key <key>         the identity of this artifact (default: its repo path)
+  --new               file a new page even if this file was filed before
+  --parent <page-id>  nest it under an existing page
+
+${bold("Options for append and edit")}
+  --prepend           add to the start of the page instead of the end
+  --find <text>       the exact text to replace, as open --markdown prints it
+  --replace <text>    what to put there; empty deletes the matched text
+  --title <title>     rename the page
+  --key <key>         name the page by its key rather than a path or an id
+
+${bold("Editing a page you did not write")}
+  open --markdown prints the page as Markdown, which is the same text --find
+  matches against. A --find that appears twice is refused rather than guessed
+  at, so quote enough of the surrounding lines to be unambiguous.
+
+${bold("How re-running works")}
+  A file is filed under its path in the repo, so publishing the same file again
+  updates the same page instead of making a second one. Pass --new when you
+  genuinely want another page, or --key to choose the identity yourself.
+
+${bold("Environment")}
+  SUMIBAKO_TOKEN      use this token instead of the saved one
+  SUMIBAKO_API        point at a different deployment
+`;
+
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const { flags, positional } = parseFlags(rest);
+
+  if (!command || command === "help" || flags.help === true) {
+    console.log(HELP);
+    return;
+  }
+  if (command === "--version" || command === "version") {
+    console.log(VERSION);
+    return;
+  }
+
+  switch (command) {
+    case "login":
+      return login(flags);
+    case "logout":
+      return logout();
+    case "publish":
+    case "push":
+      return publish(positional, flags);
+    case "unpublish":
+      return unpublish(positional, flags);
+    case "append":
+      return append(positional, flags);
+    case "edit":
+      return edit(positional, flags);
+    case "open":
+    case "get":
+      return open(positional, flags);
+    case "search":
+    case "list":
+      return search(positional);
+    case "whoami":
+      return whoami();
+    default:
+      die(`Unknown command: ${command}`, "Run `sumibako help` for the list.");
+  }
+}
+
+main().catch((error) => {
+  die(error instanceof Error ? error.message : String(error));
+});

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "sumibako",
+  "version": "0.1.0",
+  "description": "File the plans, specs and notes your coding agent writes into your Sumibako vault, and get a shareable link back.",
+  "type": "module",
+  "bin": {
+    "sumibako": "./index.mjs"
+  },
+  "main": "./index.mjs",
+  "files": [
+    "index.mjs",
+    "README.md",
+    "SKILL.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "sumibako",
+    "notes",
+    "markdown",
+    "publish",
+    "agent",
+    "agents",
+    "claude-code",
+    "codex",
+    "cursor",
+    "cli"
+  ],
+  "homepage": "https://sumibako.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PrashantShaw/Taskly.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/PrashantShaw/Taskly/issues"
+  },
+  "author": "Prashant Shaw",
+  "license": "MIT",
+  "dependencies": {}
+}