bikeshed-now 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Bikeshed contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,68 @@
+Bikeshed
+Copyright 2026 Bikeshed contributors
+
+This product includes software developed by the Bikeshed contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+
+-------------------------------------------------------------------------------
+THIRD-PARTY MATERIAL INCLUDED IN THIS DISTRIBUTION
+-------------------------------------------------------------------------------
+
+Runtime and build dependencies are not vendored; they are fetched by npm and
+their licenses are listed in THIRD_PARTY_LICENSES.md. The items below are files
+that ship inside this repository and are not covered by the Apache License above.
+
+
+1. docs/acf/** and .claude/scripts/
+   -------------------------------------------------------------------------
+   Agentic Coding Framework (ACF) documentation and helper scripts.
+   Copyright (c) 2025 Fibonacci Seven, LLC. All rights reserved.
+
+   KNOWN LICENSE CONFLICT — READ BEFORE REDISTRIBUTING.
+
+   These files originate from a work published under a PROPRIETARY LICENSE whose
+   terms state, in relevant part, that you may NOT "copy, modify, merge,
+   publish, distribute, sublicense, or sell copies of the Software" and may NOT
+   "redistribute the Software in any form, modified or unmodified."
+
+   They are present here at the express direction of this repository's author,
+   who is also the author of the substantial majority of the upstream work, and
+   who accepted this risk knowingly after it was raised. Their presence is
+   recorded here rather than left silent.
+
+   Consequences a downstream recipient must understand:
+
+     - These paths are NOT licensed to you under Apache-2.0. Nothing in the
+       LICENSE file grants any right in them.
+     - At least one upstream commit is authored by a third party, so the
+       author's own rights may not cover the whole of the material.
+     - Before publishing, forking, mirroring or redistributing this repository,
+       obtain written permission from Fibonacci Seven, LLC (acf@fib7.ai), or
+       remove these paths.
+
+   Removing them is safe and affects no product behaviour: they are
+   agent-workflow documentation and a shell status line. Nothing in app/,
+   functions/, scripts/, cli/ or content/ reads them at build time or at
+   runtime.
+
+
+2. app/public/fonts/*.woff2 — "Bikeshed Sans"
+   -------------------------------------------------------------------------
+   A subset of an upstream typeface released under the SIL Open Font License,
+   Version 1.1. Subsetting is a modification, so under the OFL's Reserved Font
+   Name clause the modified file is distributed under a different name.
+
+   The upstream face, its author, and the full OFL text are recorded in
+   app/public/fonts/OFL.txt and in THIRD_PARTY_LICENSES.md. The OFL applies to
+   the font files only and does not extend to any other part of this work.

package/README.md

@@ -0,0 +1,57 @@
+# bikeshed
+
+Publish a document to a [Bikeshed](https://bikeshed.now) deployment, then read
+the comments people left on it — each one with the exact sentence it is about.
+
+Bikeshed is self-hosted. This client talks to whichever deployment you point it
+at, over HTTPS, with a personal access token that carries exactly your own
+permissions.
+
+```bash
+npm i -g bikeshed-now
+bikeshed login            # asks for the deployment and a token
+```
+
+Create a token in the deployment's interface, under **Account → Access tokens**.
+It is shown once. `BIKESHED_ORIGIN` and `BIKESHED_TOKEN` work instead of
+`login` where an interactive command cannot run — a CI job, or an agent.
+
+## The loop
+
+```bash
+bikeshed publish proposal.md --title "Storage migration"
+# published storage-migration v1 — https://<deployment>/d/storage-migration
+
+# Somebody highlights a sentence and says what is wrong with it.
+bikeshed comments storage-migration
+
+# Fix that sentence, publish the revision, and say what you changed.
+bikeshed update storage-migration proposal.md
+bikeshed reply storage-migration <thread> "Rewritten to describe the dual-write period."
+```
+
+Publishing identical bytes is a no-op: the bundle is hashed, and a matching hash
+mints no new version. So `update` is safe in a loop, in CI, or after a change you
+are not sure you made.
+
+`bikeshed --help` lists the rest — listing documents, folders, and installing the
+agent skills a deployment serves.
+
+## Sharing is not automated
+
+There is no command that shares a document, changes who can read it, or sets an
+expiry. Those are decisions a person makes in the interface, deliberately.
+
+## For agents
+
+A deployment serves its own instructions at `https://<deployment>/llms.txt`, and
+the skills behind them at `/skills/index.json`. `bikeshed skills install <dir>`
+writes them where your harness reads skills from.
+
+Everything done with a token is stamped with the channel it came through, so a
+reviewer can always tell which feedback came from a person.
+
+## Licence
+
+Apache-2.0. The deployment it talks to is the same repository:
+[DeputyHumans/bikeshed-now](https://github.com/DeputyHumans/bikeshed-now).

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "bikeshed-now",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "description": "Publish and revise documents on a Bikeshed deployment from the terminal.",
+  "keywords": [
+    "bikeshed",
+    "documents",
+    "publishing",
+    "review",
+    "comments",
+    "mcp",
+    "agents"
+  ],
+  "homepage": "https://bikeshed.now",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DeputyHumans/bikeshed-now.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/DeputyHumans/bikeshed-now/issues"
+  },
+  "bin": {
+    "bikeshed": "./src/index.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "prepack": "cp ../LICENSE ../NOTICE .",
+    "postpack": "rm -f LICENSE NOTICE"
+  }
+}

package/src/client.mjs

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+// The HTTP and MCP client the CLI is built on (SPEC §19).
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+
+export const CLIENT_NAME = "bikeshed-cli/0.1.0";
+
+/**
+ * Two surfaces, and the split is deliberate rather than untidy.
+ *
+ *   POST /publish   takes RAW BYTES, so it is the only way to send a .zip
+ *                   bundle without base64-inflating it through JSON. It is
+ *                   also the exact endpoint the browser uploader calls.
+ *   POST /mcp       is the API for everything else — list, read, update,
+ *                   comments, reply — because those tools already exist and
+ *                   adding a parallel REST surface would mean two
+ *                   implementations of the same six operations.
+ *
+ * Both carry the same Bearer token, and both stamp provenance server-side. The
+ * `X-Bikeshed-Client` and `X-Bikeshed-Agent` headers are self-reported and are
+ * recorded as such: they are for a human reading an activity feed, not for
+ * anything that makes a decision.
+ */
+
+function headers(token, extra = {}) {
+  return {
+    Authorization: `Bearer ${token}`,
+    "X-Bikeshed-Client": CLIENT_NAME,
+    ...(process.env.BIKESHED_AGENT ? { "X-Bikeshed-Agent": process.env.BIKESHED_AGENT } : {}),
+    ...extra,
+  };
+}
+
+export class CliError extends Error {}
+
+async function readError(res, fallback) {
+  try {
+    const body = await res.json();
+    if (body?.error) return body.error;
+  } catch {
+    /* keep the fallback */
+  }
+  return fallback;
+}
+
+/** Call one MCP tool and return its structured result. */
+export async function callTool(origin, token, name, args = {}) {
+  const res = await fetch(`${origin}/mcp`, {
+    method: "POST",
+    headers: headers(token, { "Content-Type": "application/json" }),
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "tools/call",
+      params: { name, arguments: args },
+    }),
+  });
+
+  if (res.status === 401) {
+    throw new CliError(
+      "That token was not accepted. Run `bikeshed login` again, or check BIKESHED_ORIGIN.",
+    );
+  }
+  if (!res.ok) {
+    throw new CliError(await readError(res, `The server returned ${res.status}.`));
+  }
+
+  const body = await res.json();
+  if (body.error) throw new CliError(body.error.message);
+
+  const result = body.result;
+  if (result?.isError) {
+    // A tool failure arrives INSIDE the result rather than as a transport
+    // error, because the protocol reserves transport errors for transport
+    // problems — and the message is the part worth showing.
+    throw new CliError(result.content?.[0]?.text ?? "That did not work.");
+  }
+  return result?.structuredContent ?? result;
+}
+
+/** Upload a file as a NEW document, exactly as the browser uploader does. */
+export async function uploadFile(origin, token, path, { title, folder } = {}) {
+  const bytes = readFileSync(path);
+  const params = new URLSearchParams({ filename: basename(path) });
+  if (title) params.set("title", title);
+  if (folder) params.set("folderId", folder);
+
+  const res = await fetch(`${origin}/publish?${params}`, {
+    method: "POST",
+    headers: headers(token, { "Content-Type": "application/octet-stream" }),
+    body: bytes,
+  });
+
+  if (res.status === 401) {
+    throw new CliError("That token was not accepted. Run `bikeshed login` again.");
+  }
+  if (!res.ok) {
+    throw new CliError(await readError(res, `Upload failed (${res.status}).`));
+  }
+  return res.json();
+}
+
+/**
+ * The skills a deployment publishes, and their text.
+ *
+ * Unauthenticated on purpose: these are static files beside `/llms.txt`,
+ * describing what the deployment can do, not anything belonging to an account.
+ * Asking for a token to read public instructions would mean an agent has to be
+ * credentialed before it can learn how to ask for credentials.
+ */
+export async function listSkills(origin) {
+  const res = await fetch(`${origin}/skills/index.json`);
+  if (!res.ok) {
+    throw new CliError(
+      `${origin} publishes no skills (${res.status}). It may be an older deployment.`,
+    );
+  }
+  const body = await res.json().catch(() => null);
+  if (!Array.isArray(body?.skills)) {
+    // A Hosting catch-all rewrite answers a missing file with the SPA's
+    // index.html and a 200, so "it parsed as JSON" is the real test of whether
+    // the endpoint exists — not the status code.
+    throw new CliError(`${origin} returned something that is not a skill index.`);
+  }
+  return body;
+}
+
+/** Fetch one skill's Markdown, by the path its index gave. */
+export async function fetchSkill(origin, skill) {
+  const res = await fetch(`${origin}/${skill.path}`);
+  if (!res.ok) throw new CliError(`could not read ${skill.name} (${res.status})`);
+  return res.text();
+}
+
+/** Check that a token works, and say who it belongs to. */
+export async function whoami(origin, token) {
+  // list_documents is the cheapest authenticated call, and a token that can
+  // list is a token that works.
+  await callTool(origin, token, "list_documents", { limit: 1 });
+  return true;
+}

package/src/config.mjs

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+// Where the CLI keeps its credential, and how it finds the deployment (SPEC §19).
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+/**
+ * The token file.
+ *
+ * Under XDG_CONFIG_HOME when set, so it lands where the rest of a person's
+ * tooling lives, and mode 0600 because it holds a credential that can do
+ * everything its owner can do. Never in the project directory: a token in a
+ * repository is a token in somebody's next commit.
+ */
+function configDir() {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  return xdg ? join(xdg, "bikeshed") : join(homedir(), ".config", "bikeshed");
+}
+
+export const CONFIG_PATH = join(configDir(), "config.json");
+
+export function readConfig() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfig(config) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, `${JSON.stringify(config, null, 2)}\n`);
+  try {
+    chmodSync(CONFIG_PATH, 0o600);
+  } catch {
+    // Best effort: some filesystems (and Windows) do not support it. The token
+    // is still no more exposed than any other file in a home directory.
+  }
+}
+
+/**
+ * Resolve the deployment and the token.
+ *
+ * Environment first, so a CI job can supply both without writing a file, and so
+ * a token can be scoped to one shell rather than to the whole machine.
+ */
+export function resolveAuth(flags = {}) {
+  const config = readConfig();
+  const origin = (
+    flags.origin ||
+    process.env.BIKESHED_ORIGIN ||
+    config.origin ||
+    "https://bikeshed.now"
+  ).replace(/\/+$/, "");
+  const token = flags.token || process.env.BIKESHED_TOKEN || config.token || "";
+  return { origin, token };
+}

package/src/index.mjs

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// `bikeshed` — publish and revise documents from the terminal (SPEC §19).
+
+import { parseArgs } from "node:util";
+import { mkdirSync, readFileSync, watch, writeFileSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { CONFIG_PATH, readConfig, resolveAuth, writeConfig } from "./config.mjs";
+import { CliError, callTool, fetchSkill, listSkills, uploadFile, whoami } from "./client.mjs";
+
+/**
+ * This is the END-USER tool, and it is deliberately not the same thing as the
+ * scripts in `scripts/`. Conflating the two is how somebody runs a teardown
+ * against production, so the difference is stated in `--help`, in the README,
+ * and here:
+ *
+ *   scripts/*.mjs   whoever owns the deployment. Admin credentials. Talks to
+ *                   Firestore and Storage directly. Provisions and withdraws.
+ *   bikeshed        any signed-up user. A personal access token. Talks to the
+ *                   deployment over HTTPS. Publishes and revises documents.
+ *
+ * Every command takes `--json`, so it composes inside a script or an agent's
+ * shell without anybody parsing human-readable output.
+ */
+
+const USAGE = `bikeshed — publish and revise documents
+
+  bikeshed login                       store a personal access token
+  bikeshed list                        documents you can read
+  bikeshed publish <file>              create a new document
+  bikeshed update <id> <file>          publish a new version
+  bikeshed get <id>                    print a document's source
+  bikeshed comments <id>               unresolved feedback, with its anchored text
+  bikeshed reply <id> <thread> <text>  reply in a thread
+  bikeshed open <id>                   open it in a browser
+
+Organising
+  bikeshed folders                     the folder tree, with ids
+  bikeshed mkdir <name> [--parent <id>]  create a folder
+  bikeshed mv <id> <folder|root>       move a document
+
+Skills
+  bikeshed skills                      skills this deployment publishes
+  bikeshed skills install <dir>        write them into an agent's skills directory
+                                       (Claude Code: ~/.claude/skills)
+
+Options
+  --json                 machine-readable output
+  --title <text>         title for publish
+  --folder <id>          destination folder for publish
+  --parent <id>          parent folder for mkdir
+  --watch                with publish/update: republish on every save
+  --origin <url>         the deployment (default: the one you logged in to)
+  --token <token>        override the stored token
+  --help                 this
+
+Environment
+  BIKESHED_ORIGIN, BIKESHED_TOKEN, BIKESHED_AGENT
+
+This is the end-user tool. The scripts in scripts/ are the OPERATOR tools: they
+use admin credentials, talk to the database directly, and can tear a deployment
+down. They are not the same thing.
+`;
+
+function fail(message) {
+  console.error(`error: ${message}`);
+  process.exit(1);
+}
+
+function out(json, value, human) {
+  if (json) {
+    console.log(JSON.stringify(value, null, 2));
+    return;
+  }
+  human();
+}
+
+// --- Commands --------------------------------------------------------------
+
+async function login(flags) {
+  const { origin } = resolveAuth(flags);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const where =
+      flags.origin ||
+      (await rl.question(`Deployment [${origin}]: `)).trim() ||
+      origin;
+    console.log(`\nCreate a token at ${where}/account — choose "Command line".`);
+    console.log("It is shown once, so copy it now.\n");
+    const token = (await rl.question("Token: ")).trim();
+    if (!token) fail("no token given");
+
+    // Verified before it is stored, so a typo fails here rather than on the
+    // next command with a confusing message.
+    await whoami(where, token);
+    writeConfig({ ...readConfig(), origin: where, token });
+    console.log(`\nSaved to ${CONFIG_PATH} (readable only by you).`);
+  } finally {
+    rl.close();
+  }
+}
+
+async function list(flags) {
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "list_documents", {
+    limit: Number(flags.limit) || 20,
+  });
+  out(flags.json, result, () => {
+    if (result.documents.length === 0) {
+      console.log("Nothing yet. `bikeshed publish <file>` to start.");
+      return;
+    }
+    for (const doc of result.documents) {
+      const marker = doc.visibility === "private" ? " " : doc.visibility === "public" ? "◉" : "◐";
+      console.log(`${marker} ${doc.id.padEnd(34)} ${doc.version.padEnd(5)} ${doc.title}`);
+    }
+    if (result.nextCursor) console.log(`\n… more: --cursor ${result.nextCursor}`);
+  });
+}
+
+async function publish(flags, [path]) {
+  if (!path) fail("usage: bikeshed publish <file>");
+  const { origin, token } = resolveAuth(flags);
+  const file = resolve(path);
+
+  const once = async () => {
+    const result = await uploadFile(origin, token, file, {
+      title: flags.title,
+      folder: flags.folder,
+    });
+    // The address is in the human line already; `--json` carried only the id, so
+    // anything reading it had to know how to build a URL out of a docId.
+    out(flags.json, { ...result, url: result.url ?? `${origin}/d/${result.docId}` }, () =>
+      console.log(`published ${result.docId} ${result.versionId} — ${origin}/d/${result.docId}`),
+    );
+    return result;
+  };
+
+  const first = await once();
+  if (flags.watch) {
+    // Watch republishes as UPDATES after the first, or every save would create
+    // another document.
+    await watchFile(file, () =>
+      update({ ...flags, watch: false }, [first.docId, file]),
+    );
+  }
+}
+
+async function update(flags, [id, path]) {
+  if (!id || !path) fail("usage: bikeshed update <id> <file>");
+  const { origin, token } = resolveAuth(flags);
+  const file = resolve(path);
+
+  const once = async () => {
+    const content = readFileSync(file, "utf8");
+    const result = await callTool(origin, token, "update_document", { id, content });
+    out(flags.json, { ...result, url: result.url ?? `${origin}/d/${id}` }, () =>
+      console.log(
+        result.deduped
+          ? `no change — identical to ${result.versionId}`
+          : `published ${result.versionId} (${result.fileCount} file(s), ${result.bytes} bytes)`,
+      ),
+    );
+    return result;
+  };
+
+  await once();
+  if (flags.watch) await watchFile(file, once);
+}
+
+async function get(flags, [id]) {
+  if (!id) fail("usage: bikeshed get <id>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "get_document", { id });
+  out(flags.json, result, () => process.stdout.write(result.source));
+}
+
+async function comments(flags, [id]) {
+  if (!id) fail("usage: bikeshed comments <id>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "get_comments", {
+    id,
+    includeResolved: Boolean(flags.all),
+  });
+  out(flags.json, result, () => {
+    if (result.threads.length === 0) {
+      console.log("No open comments.");
+      return;
+    }
+    for (const thread of result.threads) {
+      // The QUOTE first, because it is what makes a comment actionable: it says
+      // which passage to change without opening the document.
+      console.log(`\n── ${thread.threadId}${thread.section ? `  (${thread.section})` : ""}`);
+      if (thread.quote) console.log(`   “${thread.quote}”`);
+      for (const comment of thread.comments) {
+        const via = comment.via && comment.via !== "web" ? ` [via ${comment.via}]` : "";
+        console.log(`   ${comment.author}${via}: ${comment.body}`);
+      }
+    }
+    console.log("");
+  });
+}
+
+async function reply(flags, [id, threadId, ...rest]) {
+  const body = rest.join(" ");
+  if (!id || !threadId || !body) fail("usage: bikeshed reply <id> <thread> <text>");
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "reply_to_comment", { id, threadId, body });
+  out(flags.json, result, () => console.log(`replied in ${threadId}`));
+}
+
+async function folders(flags) {
+  const { origin, token } = resolveAuth(flags);
+  const result = await callTool(origin, token, "list_folders", {});
+  out(flags.json, result, () => {
+    if (result.folders.length === 0) {
+      console.log("No folders. `bikeshed mkdir <name>` to make one.");
+      return;
+    }
+    for (const folder of result.folders) {
+      // Indentation comes from the PATH, not from walking parents: a folder
+      // whose parent is not shared with you still sits at its real depth, and
+      // its path already says so with an ellipsis for the level you cannot see.
+      const depth = folder.path.split("/").length - 1;
+      const label = `${"  ".repeat(depth)}${folder.name}`;
+      const note = folder.canWrite ? "" : "  (read-only)";
+      console.log(`${label.padEnd(40)} ${folder.id}${note}`);
+    }
+    if (result.truncated) {
+      console.log("\nThere are more folders than this listing shows.");
+    }
+  });
+}
+
+async function mkdir(flags, rest) {
+  const name = rest.join(" ");
+  if (!name) fail("usage: bikeshed mkdir <name> [--parent <id>]");
+  const { origin, token } = resolveAuth(flags);
+  const args = { name };
+  if (flags.parent) args.parent = flags.parent;
+  const result = await callTool(origin, token, "create_folder", args);
+  out(flags.json, result, () => console.log(`${result.name}  ${result.folderId}`));
+}
+
+async function mv(flags, [id, dest]) {
+  /**
+   * The destination is REQUIRED, and the workspace root has to be spelled.
+   *
+   * On the MCP side an omitted `folder` means the root, because the protocol
+   * has no way to send an empty one. A positional argument does: leaving it off
+   * is something a person does by accident, and "bikeshed mv report" silently
+   * pulling a document out of the folder it was filed in is not a mistake the
+   * interface should make easy.
+   */
+  if (!id || !dest) fail("usage: bikeshed mv <id> <folder|root>");
+  const { origin, token } = resolveAuth(flags);
+  const args = dest === "root" ? { id } : { id, folder: dest };
+  const result = await callTool(origin, token, "move_document", args);
+  out(flags.json, result, () =>
+    console.log(result.folder ? `moved ${id} into ${result.folder}` : `moved ${id} to the root`),
+  );
+}
+
+/**
+ * Skills are instructions, not code, and they are fetched from the DEPLOYMENT
+ * rather than bundled with this CLI on purpose: a deployment running an older
+ * version should hand out the skills that describe what it can actually do.
+ *
+ * No token is needed — they are public static files, the same ones `/llms.txt`
+ * points at.
+ */
+async function skillsCommand(flags, [sub, dir]) {
+  const { origin } = resolveAuth(flags);
+  const index = await listSkills(origin);
+
+  if (!sub) {
+    out(flags.json, index, () => {
+      for (const skill of index.skills) {
+        console.log(`${skill.name}\n  ${skill.description}\n`);
+      }
+      console.log(`bikeshed skills install <dir>   — Claude Code: ~/.claude/skills`);
+    });
+    return;
+  }
+  if (sub !== "install") fail("usage: bikeshed skills [install <dir>]");
+  if (!dir) fail("usage: bikeshed skills install <dir>");
+
+  const root = resolve(dir);
+  const written = [];
+  for (const skill of index.skills) {
+    // The name decides a path on this machine, so it is validated here rather
+    // than trusted from the response. A deployment is not an adversary, but a
+    // name is still the wrong place to find out it could have been one.
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(skill.name)) {
+      fail(`refusing a skill with an unusable name: ${skill.name}`);
+    }
+    const body = await fetchSkill(origin, skill);
+    const target = join(root, skill.name);
+    mkdirSync(target, { recursive: true });
+    writeFileSync(join(target, "SKILL.md"), body);
+    written.push(join(skill.name, "SKILL.md"));
+  }
+  out(flags.json, { installed: written, into: root }, () => {
+    for (const file of written) console.log(`${root}/${file}`);
+  });
+}
+
+async function open(flags, [id]) {
+  if (!id) fail("usage: bikeshed open <id>");
+  const { origin } = resolveAuth(flags);
+  const url = `${origin}/d/${id}`;
+  const { spawn } = await import("node:child_process");
+  const opener =
+    process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+  spawn(opener, [url], { stdio: "ignore", detached: true }).unref();
+  console.log(url);
+}
+
+/**
+ * Re-run on every save, debounced.
+ *
+ * Editors write in bursts — a truncate, then a write, sometimes a rename — so a
+ * naive watcher fires three times per save and publishes twice more than it
+ * should. The content hash would make the extra calls no-ops, but they would
+ * still be three round trips per keystroke-pause.
+ */
+async function watchFile(file, run) {
+  console.log(`watching ${basename(file)} — ctrl-C to stop`);
+  let timer = null;
+  watch(file, () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      run().catch((e) => console.error(`error: ${e.message}`));
+    }, 250);
+  });
+  await new Promise(() => {}); // until interrupted
+}
+
+// --- Entry point -----------------------------------------------------------
+
+const COMMANDS = {
+  login,
+  list,
+  publish,
+  update,
+  get,
+  comments,
+  reply,
+  open,
+  folders,
+  mkdir,
+  mv,
+  skills: skillsCommand,
+};
+
+/** Commands that reach a deployment without authenticating as anybody. */
+const NO_TOKEN = new Set(["login", "open", "skills"]);
+
+async function main() {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    allowPositionals: true,
+    strict: false,
+    options: {
+      json: { type: "boolean", default: false },
+      watch: { type: "boolean", default: false },
+      all: { type: "boolean", default: false },
+      help: { type: "boolean", default: false },
+      title: { type: "string" },
+      folder: { type: "string" },
+      parent: { type: "string" },
+      origin: { type: "string" },
+      token: { type: "string" },
+      limit: { type: "string" },
+      cursor: { type: "string" },
+    },
+  });
+
+  const [name, ...rest] = positionals;
+  if (values.help || !name) {
+    console.log(USAGE);
+    return;
+  }
+
+  const command = COMMANDS[name];
+  if (!command) fail(`unknown command: ${name}\n\n${USAGE}`);
+
+  const { token } = resolveAuth(values);
+  if (!token && !NO_TOKEN.has(name)) {
+    fail("no token. Run `bikeshed login`, or set BIKESHED_TOKEN.");
+  }
+
+  await command(values, rest);
+}
+
+main().catch((e) => {
+  if (e instanceof CliError) fail(e.message);
+  fail(e?.message ?? String(e));
+});