@ree-auz/nook 0.1.0 → 0.1.2

package/integrations/linear/open-issue.mjs

@@ -1,147 +1,193 @@
-#!/usr/bin/env node
-// Opens a Linear issue in a Nook workspace, in a new terminal tab.
-// Linear runs this file through ~/.linear/coding-tools.json
-// (Work on issue -> Custom script). See README.md next to it.
-//
-//   node open-issue.mjs [agent]              started by Linear (no window)
-//   node open-issue.mjs --run <file> ...     inside the new tab
-import { spawn, spawnSync } from "node:child_process";
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
-import { delimiter, dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { normalizeName } from "../../src/names.mjs";
-
-const self = fileURLToPath(import.meta.url);
-const nk = fileURLToPath(new URL("../../bin/nk.mjs", import.meta.url));
-
-/**
- * Puts this Node's folder first on PATH. With a version manager such as fnm
- * or nvm, Linear starts without the shell setup that adds it, and global npm
- * commands (the agent, pnpm for hooks) live next to node.exe.
- */
-function withNodeOnPath(env = process.env) {
-  const key = Object.keys(env).find((name) => name.toUpperCase() === "PATH") ?? "PATH";
-  return { ...env, [key]: [dirname(process.execPath), env[key]].filter(Boolean).join(delimiter) };
-}
-
-/** Runs nk with this Node, so the prompt never passes through cmd.exe. */
-function runNk(args, opts = {}) {
-  return spawnSync(process.execPath, [nk, ...args], { stdio: "inherit", env: withNodeOnPath(), ...opts });
-}
-
-/** Creates the issue's workspace and starts the agent, or reopens it. */
-function startWork({ branch, agent, prompt }) {
-  const listed = spawnSync(process.execPath, [nk, "ls", "--json"], { encoding: "utf8", env: withNodeOnPath() });
-  const existing = listed.status === 0 ? JSON.parse(listed.stdout).find((ws) => !ws.main && (ws.branch === branch || ws.name === normalizeName(branch))) : null;
-  // Clicked again for the same issue: reopen the workspace without restarting the task.
-  // -y: the branch name Linear suggests is converted without asking.
-  const result = existing ? runNk([existing.name, agent]) : runNk(["-b", branch, agent, "-y", "-p", prompt]);
-  process.exitCode = result.status ?? 1;
-}
-
-/** Inside a tab another terminal opened: the prompt comes in a file. */
-export function insideTab([file, branch, agent, ...more]) {
-  const prompt = readFileSync(file, "utf8");
-  rmSync(file, { force: true });
-  // A Warp tab config written only for this launch.
-  if (more[0] === "--cleanup" && more[1]) rmSync(more[1], { force: true });
-  startWork({ branch, agent, prompt });
-}
-
-/** Windows Terminal: -w 0 opens a tab in the most recent window (or a new window). */
-function openInWindowsTerminal({ dir, id, inner }) {
-  spawn("wt.exe", ["-w", "0", "new-tab", "-d", dir, "--title", id, ...inner], { detached: true, stdio: "ignore" }).unref();
-}
-
-/** A PowerShell argument in single quotes. */
-const psQuote = (text) => `'${String(text).replaceAll("'", "''")}'`;
-
-/**
- * Warp: its URI scheme cannot run a command, so write a tab config that
- * does and open it with warp://tab_config/<name>, as Warp's docs advise.
- * The tab deletes the config once it starts.
- */
-export function openInWarp({ dir, id, inner, env = process.env, start = openUri }) {
-  const folder = join(env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "warp", "Warp", "data", "tab_configs");
-  mkdirSync(folder, { recursive: true });
-  const name = `nk-${id.toLowerCase().replace(/[^a-z0-9-]/g, "-")}-${process.pid}`;
-  const config = join(folder, `${name}.toml`);
-  const [node, ...args] = [...inner, "--cleanup", config];
-  const shell = which("pwsh") ? "pwsh" : "powershell";
-  const command = `& ${[node, ...args].map(psQuote).join(" ")}`;
-  writeFileSync(
-    config,
-    [`name = ${JSON.stringify(name)}`, `title = ${JSON.stringify(id)}`, "", "[[panes]]", 'id = "main"', 'type = "terminal"', `shell = ${JSON.stringify(shell)}`, `directory = ${JSON.stringify(dir)}`, `commands = [${JSON.stringify(command)}]`, ""].join("\n"),
-  );
-  start(`warp://tab_config/${name}`);
-  return config;
-}
-
-/** Opens a URI with its registered app, like PowerShell's Start-Process. */
-function openUri(uri) {
-  spawn("cmd.exe", ["/d", "/c", "start", '""', uri], { detached: true, stdio: "ignore", windowsVerbatimArguments: true }).unref();
-}
-
-/** A command on PATH, without running it. */
-function which(command) {
-  const result = spawnSync("where.exe", [command], { encoding: "utf8", windowsHide: true });
-  return result.status === 0;
-}
-
-const TERMINALS = { wt: openInWindowsTerminal, warp: openInWarp };
-
-/**
- * Closes the terminal window Linear opened for this script, once the work
- * runs in another terminal: its shell is this process's parent.
- */
-function closeLinearWindow() {
-  const parent = spawnSync("tasklist.exe", ["/FI", `PID eq ${process.ppid}`, "/FO", "CSV", "/NH"], { encoding: "utf8", windowsHide: true });
-  if (/^"(powershell|pwsh|cmd)\.exe"/i.test(parent.stdout ?? "")) process.kill(process.ppid);
-}
-
-/**
- * The agent named by a label in Linear's prompt, which lists the issue's
- * labels as <label>Group › Name</label>: with group "Agent", an issue
- * labelled "Agent › Claude" gets `claude`.
- */
-export function agentFromLabels(prompt, group) {
-  if (!group) return null;
-  for (const [, text] of prompt.matchAll(/<label>([^<]*)<\/label>/g)) {
-    const [labelGroup, name] = text.split("›").map((part) => part.trim());
-    if (name && labelGroup === group) return name.toLowerCase().replace(/\s+/g, "-");
-  }
-  return null;
-}
-
-/** `--name value` from the arguments Linear passes. */
-function option(argv, name) {
-  const at = argv.indexOf(name);
-  return at >= 0 ? argv[at + 1] : undefined;
-}
-
-function fromLinear(argv) {
-  const terminal = option(argv, "--terminal");
-  const agent = agentFromLabels(process.env.LINEAR_PROMPT ?? "", option(argv, "--agent-label")) ?? option(argv, "--agent") ?? "codex";
-  const { LINEAR_ISSUE_BRANCH_NAME: branch, LINEAR_WORK_DIR: dir, LINEAR_ISSUE_IDENTIFIER: id = "issue", LINEAR_PROMPT: prompt = "" } = process.env;
-  if (!branch || !dir) throw new Error("LINEAR_ISSUE_BRANCH_NAME and LINEAR_WORK_DIR are missing; list them under env in coding-tools.json");
-  // Default: work in the terminal Linear opened for the script.
-  if (!terminal) {
-    process.chdir(dir);
-    return startWork({ branch, agent, prompt });
-  }
-  const open = TERMINALS[terminal];
-  if (!open) throw new Error(`Unknown terminal "${terminal}"; use ${Object.keys(TERMINALS).join(" or ")}, or leave --terminal out`);
-  if (process.platform !== "win32") throw new Error("--terminal only works on Windows so far");
-  // The prompt is long Markdown with quotes and semicolons, so it travels in a file.
-  const file = join(tmpdir(), `nk-linear-${id}-${process.pid}.md`);
-  writeFileSync(file, prompt);
-  open({ dir, id, inner: [process.execPath, self, "--run", file, branch, agent] });
-  closeLinearWindow();
-}
-
-if (process.argv[1] && resolve(process.argv[1]) === self) {
-  const [first, ...rest] = process.argv.slice(2);
-  if (first === "--run") insideTab(rest);
-  else fromLinear(process.argv.slice(2));
-}
+#!/usr/bin/env node
+// Opens a Linear issue in a Nook workspace, in a new terminal tab.
+// Linear runs this file through ~/.linear/coding-tools.json
+// (Work on issue -> Custom script). See README.md next to it.
+//
+//   node open-issue.mjs [--agent a] [--terminal wt|warp|orca]   started by Linear
+//   node open-issue.mjs --run <file> ...     inside the new tab
+import { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { delimiter, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { agentCommand, windowsDirect } from "../../src/agents.mjs";
+import { normalizeName } from "../../src/names.mjs";
+import crossSpawn from "cross-spawn";
+
+const self = fileURLToPath(import.meta.url);
+const nk = fileURLToPath(new URL("../../bin/nk.mjs", import.meta.url));
+
+/**
+ * Puts this Node's folder first on PATH. With a version manager such as fnm
+ * or nvm, Linear starts without the shell setup that adds it, and global npm
+ * commands (the agent, pnpm for hooks) live next to node.exe.
+ */
+function withNodeOnPath(env = process.env) {
+  const key = Object.keys(env).find((name) => name.toUpperCase() === "PATH") ?? "PATH";
+  return { ...env, [key]: [dirname(process.execPath), env[key]].filter(Boolean).join(delimiter) };
+}
+
+/** Runs nk with this Node, so the prompt never passes through cmd.exe. */
+function runNk(args, opts = {}) {
+  return spawnSync(process.execPath, [nk, ...args], { stdio: "inherit", env: withNodeOnPath(), ...opts });
+}
+
+/** The issue's workspace from `nk ls --json`, if it exists. */
+function findWorkspace(branch) {
+  const listed = spawnSync(process.execPath, [nk, "ls", "--json"], { encoding: "utf8", env: withNodeOnPath() });
+  return listed.status === 0 ? JSON.parse(listed.stdout).find((ws) => !ws.main && (ws.branch === branch || ws.name === normalizeName(branch))) : null;
+}
+
+/** Creates the issue's workspace and starts the agent, or reopens it. */
+function startWork({ branch, agent, prompt }) {
+  const existing = findWorkspace(branch);
+  // Clicked again for the same issue: reopen the workspace without restarting the task.
+  // -y: the branch name Linear suggests is converted without asking.
+  const result = existing ? runNk([existing.name, agent]) : runNk(["-b", branch, agent, "-y", "-p", prompt]);
+  process.exitCode = result.status ?? 1;
+}
+
+/** Inside a tab another terminal opened: the prompt comes in a file. */
+export function insideTab([file, branch, agent, ...more]) {
+  const prompt = readFileSync(file, "utf8");
+  rmSync(file, { force: true });
+  // A Warp tab config written only for this launch.
+  if (more[0] === "--cleanup" && more[1]) rmSync(more[1], { force: true });
+  startWork({ branch, agent, prompt });
+}
+
+/** Windows Terminal: -w 0 opens a tab in the most recent window (or a new window). */
+function openInWindowsTerminal({ dir, id, inner }) {
+  spawn("wt.exe", ["-w", "0", "new-tab", "-d", dir, "--title", id, ...inner], { detached: true, stdio: "ignore" }).unref();
+}
+
+/** A PowerShell argument in single quotes. */
+const psQuote = (text) => `'${String(text).replaceAll("'", "''")}'`;
+
+/**
+ * Warp: its URI scheme cannot run a command, so write a tab config that
+ * does and open it with warp://tab_config/<name>, as Warp's docs advise.
+ * The tab deletes the config once it starts.
+ */
+export function openInWarp({ dir, id, inner, env = process.env, start = openUri }) {
+  const folder = join(env.APPDATA ?? join(homedir(), "AppData", "Roaming"), "warp", "Warp", "data", "tab_configs");
+  mkdirSync(folder, { recursive: true });
+  const name = `nk-${id.toLowerCase().replace(/[^a-z0-9-]/g, "-")}-${process.pid}`;
+  const config = join(folder, `${name}.toml`);
+  const [node, ...args] = [...inner, "--cleanup", config];
+  const shell = which("pwsh") ? "pwsh" : "powershell";
+  const command = `& ${[node, ...args].map(psQuote).join(" ")}`;
+  writeFileSync(
+    config,
+    [`name = ${JSON.stringify(name)}`, `title = ${JSON.stringify(id)}`, "", "[[panes]]", 'id = "main"', 'type = "terminal"', `shell = ${JSON.stringify(shell)}`, `directory = ${JSON.stringify(dir)}`, `commands = [${JSON.stringify(command)}]`, ""].join("\n"),
+  );
+  start(`warp://tab_config/${name}`);
+  return config;
+}
+
+/** Opens a URI with its registered app, like PowerShell's Start-Process. */
+function openUri(uri) {
+  spawn("cmd.exe", ["/d", "/c", "start", '""', uri], { detached: true, stdio: "ignore", windowsVerbatimArguments: true }).unref();
+}
+
+/** A command on PATH, without running it. */
+function which(command) {
+  const result = spawnSync("where.exe", [command], { encoding: "utf8", windowsHide: true });
+  return result.status === 0;
+}
+
+const TERMINALS = { wt: openInWindowsTerminal, warp: openInWarp };
+
+/**
+ * Orca: nk creates the workspace (hooks, ports, database), then Orca starts
+ * the agent in it, so Orca keeps its accounts and sessions. Orca shows
+ * worktrees it did not create. A new workspace gets Linear's prompt; one
+ * that exists only gets a new agent session.
+ */
+export function workInOrca({ branch, agent, prompt, orca = "orca", run = runOrca }) {
+  const existing = findWorkspace(branch);
+  if (!existing) {
+    const created = runNk(["-b", branch, "-y"]);
+    if (created.status !== 0) return created.status ?? 1;
+  }
+  const ws = existing ?? findWorkspace(branch);
+  if (!ws) throw new Error(`nk created no workspace for ${branch}`);
+  run(orca, ["open", "--json"]);
+  const args = ["agent", "launch", "--agent", agent, "--worktree", `path:${ws.path}`, "--focus", "--json"];
+  if (!existing && prompt) args.push("--prompt", prompt);
+  return run(orca, args);
+}
+
+/** Runs the Orca CLI, never through cmd.exe, which would cut the prompt. */
+function runOrca(orca, args) {
+  const env = withNodeOnPath();
+  const spec = windowsDirect({ command: agentCommand({}, orca, {}, env).command, args });
+  // cross-spawn: a .cmd shim still runs when the arguments have no line breaks.
+  const result = crossSpawn.sync(spec.command, spec.args, { stdio: ["ignore", "pipe", "inherit"], encoding: "utf8", env });
+  if (result.error) throw new Error(`could not run ${orca}: ${result.error.message}. Is Orca's command-line tool installed? Pass its path with --orca`);
+  // Orca answers in JSON; show it only when something went wrong.
+  if (result.status !== 0) process.stdout.write(result.stdout ?? "");
+  return result.status ?? 1;
+}
+
+/**
+ * Closes the terminal window Linear opened for this script, once the work
+ * runs in another terminal: its shell is this process's parent.
+ */
+function closeLinearWindow() {
+  const parent = spawnSync("tasklist.exe", ["/FI", `PID eq ${process.ppid}`, "/FO", "CSV", "/NH"], { encoding: "utf8", windowsHide: true });
+  if (/^"(powershell|pwsh|cmd)\.exe"/i.test(parent.stdout ?? "")) process.kill(process.ppid);
+}
+
+/**
+ * The agent named by a label in Linear's prompt, which lists the issue's
+ * labels as <label>Group › Name</label>: with group "Agent", an issue
+ * labelled "Agent › Claude" gets `claude`.
+ */
+export function agentFromLabels(prompt, group) {
+  if (!group) return null;
+  for (const [, text] of prompt.matchAll(/<label>([^<]*)<\/label>/g)) {
+    const [labelGroup, name] = text.split("›").map((part) => part.trim());
+    if (name && labelGroup === group) return name.toLowerCase().replace(/\s+/g, "-");
+  }
+  return null;
+}
+
+/** `--name value` from the arguments Linear passes. */
+function option(argv, name) {
+  const at = argv.indexOf(name);
+  return at >= 0 ? argv[at + 1] : undefined;
+}
+
+function fromLinear(argv) {
+  const terminal = option(argv, "--terminal");
+  const agent = agentFromLabels(process.env.LINEAR_PROMPT ?? "", option(argv, "--agent-label")) ?? option(argv, "--agent") ?? "codex";
+  const { LINEAR_ISSUE_BRANCH_NAME: branch, LINEAR_WORK_DIR: dir, LINEAR_ISSUE_IDENTIFIER: id = "issue", LINEAR_PROMPT: prompt = "" } = process.env;
+  if (!branch || !dir) throw new Error("LINEAR_ISSUE_BRANCH_NAME and LINEAR_WORK_DIR are missing; list them under env in coding-tools.json");
+  // Default: work in the terminal Linear opened for the script.
+  if (!terminal) {
+    process.chdir(dir);
+    return startWork({ branch, agent, prompt });
+  }
+  if (terminal === "orca") {
+    process.chdir(dir);
+    process.exitCode = workInOrca({ branch, agent, prompt, orca: option(argv, "--orca") ?? "orca" });
+    // Keep Linear's window open when something failed, so its output can be read.
+    if (process.exitCode === 0 && process.platform === "win32") closeLinearWindow();
+    return;
+  }
+  const open = TERMINALS[terminal];
+  if (!open) throw new Error(`Unknown terminal "${terminal}"; use ${[...Object.keys(TERMINALS), "orca"].join(", ")}, or leave --terminal out`);
+  if (process.platform !== "win32") throw new Error("--terminal only works on Windows so far");
+  // The prompt is long Markdown with quotes and semicolons, so it travels in a file.
+  const file = join(tmpdir(), `nk-linear-${id}-${process.pid}.md`);
+  writeFileSync(file, prompt);
+  open({ dir, id, inner: [process.execPath, self, "--run", file, branch, agent] });
+  closeLinearWindow();
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === self) {
+  const [first, ...rest] = process.argv.slice(2);
+  if (first === "--run") insideTab(rest);
+  else fromLinear(process.argv.slice(2));
+}

package/package.json

@@ -1,34 +1,34 @@
-{
-  "name": "@ree-auz/nook",
-  "version": "0.1.0",
-  "description": "One home folder for your git worktrees: create, open and remove workspaces with shared files, ports and hooks.",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "nk": "bin/nk.mjs",
-    "nook": "bin/nk.mjs"
-  },
-  "files": [
-    "bin",
-    "docs",
-    "integrations",
-    "skills",
-    "src"
-  ],
-  "engines": {
-    "node": ">=20.12"
-  },
-  "scripts": {
-    "test": "node --test --test-concurrency=1",
-    "corpus": "node scripts/corpus.mjs"
-  },
-  "dependencies": {
-    "cross-spawn": "7.0.6",
-    "smol-toml": "1.9.1",
-    "yaml": "2.9.1"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ree-auz/nook.git"
-  }
-}
+{
+  "name": "@ree-auz/nook",
+  "version": "0.1.2",
+  "description": "One home folder for your git worktrees: create, open and remove workspaces with shared files, ports and hooks.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "nk": "bin/nk.mjs",
+    "nook": "bin/nk.mjs"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "integrations",
+    "skills",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.12"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1",
+    "corpus": "node scripts/corpus.mjs"
+  },
+  "dependencies": {
+    "cross-spawn": "7.0.6",
+    "smol-toml": "1.9.1",
+    "yaml": "2.9.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ree-auz/nook.git"
+  }
+}

package/skills/nook/SKILL.md

@@ -1,71 +1,71 @@
----
-name: nook
-description: Use when working in a git worktree managed by nk (Nook), when asked to create, list, open, remove or clean up workspaces with nk, or to set up a repository's .nook hooks.
----
-
-# Working with Nook (`nk`)
-
-Nook keeps one git worktree per task under `~/nook/workspace/<repo>/<name>`.
-The workspace name is also the branch name and the folder name.
-
-## Am I in a workspace?
-
-`NOOK_WORKSPACE` is set when nk started you. These variables are also set:
-
-| Variable | Meaning |
-| --- | --- |
-| `NOOK_WORKSPACE` | workspace and branch name |
-| `NOOK_PATH` | this workspace's folder |
-| `NOOK_REPO` | the main checkout of the repository |
-| `NOOK_SHARED` | the repository's shared folder (holds files such as `.env`) |
-| `NOOK_PORT` | first of ten ports reserved for this workspace (`NOOK_PORT` to `NOOK_PORT + 9`) |
-
-Without the variables, `nk ls --json` lists every workspace with its `path`;
-you are in one when your working directory is inside that path.
-
-## Rules
-
-- Work and commit only inside your own workspace folder. Do not edit the main
-  checkout (`NOOK_REPO`) or another workspace.
-- Use ports from `NOOK_PORT` to `NOOK_PORT + 9` for servers you start, so
-  workspaces do not collide.
-- Files copied from the shared folder (such as `.env`) are local settings.
-  Do not commit them and do not print their contents.
-- Do not run `nk rm` or `nk clean` on your own workspace: nk refuses while
-  you are inside it. Leave removal to the person or the tool that started you.
-- Hooks in `.nook/` run with the person's approval. Do not edit them to get
-  past a failure; report the failure and the log path nk printed. Never pass
-  `--allow-hooks` yourself: the person reads and allows the hooks.
-
-## Setting up hooks
-
-When asked to set up Nook hooks: if you were started by `nk hooks write
-<agent>`, nk has already generated hooks from CI and the Compose file; finish what its prompt lists
-as not translated. Otherwise run `nk hooks write` first. Follow
-[docs/setup-hooks.md](https://github.com/ree-auz/nook/blob/main/docs/setup-hooks.md),
-run `nk hooks test` in the folder you work in and fix the hooks until it
-passes. Delete the first line of a generated hook you edit. Do not commit or
-push unless asked.
-
-## Commands
-
-| Command | Use |
-| --- | --- |
-| `nk -b <name> [agent] [-p <prompt>]` | Create a workspace from the default branch (or an existing branch of that name) |
-| `nk <name>` | Print a workspace's path; with an agent, start it there |
-| `nk ls --json` | Every workspace of this repository: `name`, `repo`, `path`, `port`, `changes`, `ahead`, `behind`, `pr` (`number`, `state`, `ci`) |
-| `nk rm <name>... -n` | Show what removing would back up and delete, change nothing |
-| `nk clean -n` | Show which workspaces are merged and would be removed |
-| `nk hooks test` | Run this folder's hooks in a temporary workspace; fails on leftovers |
-| `nk hooks` | The repository's hooks: allowed, tested |
-| `nk doctor` | Check nk's tools; exit 1 when something is broken |
-
-Pass `-y` to `nk rm` or `nk clean` only when the person asked for the
-removal. Both back up uncommitted changes and unpushed commits to
-`~/nook/backup/<repo>/` first.
-
-## Reading results
-
-Exit code 0 means success. On failure, stderr starts with `✗ what failed`,
-followed by `○` lines saying why and what to do next. Follow those lines
-instead of guessing.
+---
+name: nook
+description: Use when working in a git worktree managed by nk (Nook), when asked to create, list, open, remove or clean up workspaces with nk, or to set up a repository's .nook hooks.
+---
+
+# Working with Nook (`nk`)
+
+Nook keeps one git worktree per task under `~/nook/workspace/<repo>/<name>`.
+The workspace name is also the branch name and the folder name.
+
+## Am I in a workspace?
+
+`NOOK_WORKSPACE` is set when nk started you. These variables are also set:
+
+| Variable | Meaning |
+| --- | --- |
+| `NOOK_WORKSPACE` | workspace and branch name |
+| `NOOK_PATH` | this workspace's folder |
+| `NOOK_REPO` | the main checkout of the repository |
+| `NOOK_SHARED` | the repository's shared folder (holds files such as `.env`) |
+| `NOOK_PORT` | first of ten ports reserved for this workspace (`NOOK_PORT` to `NOOK_PORT + 9`) |
+
+Without the variables, `nk ls --json` lists every workspace with its `path`;
+you are in one when your working directory is inside that path.
+
+## Rules
+
+- Work and commit only inside your own workspace folder. Do not edit the main
+  checkout (`NOOK_REPO`) or another workspace.
+- Use ports from `NOOK_PORT` to `NOOK_PORT + 9` for servers you start, so
+  workspaces do not collide.
+- Files copied from the shared folder (such as `.env`) are local settings.
+  Do not commit them and do not print their contents.
+- Do not run `nk rm` or `nk clean` on your own workspace: nk refuses while
+  you are inside it. Leave removal to the person or the tool that started you.
+- Hooks in `.nook/` run with the person's approval. Do not edit them to get
+  past a failure; report the failure and the log path nk printed. Never pass
+  `--allow-hooks` yourself: the person reads and allows the hooks.
+
+## Setting up hooks
+
+When asked to set up Nook hooks: if you were started by `nk hooks write
+<agent>`, nk has already generated hooks from CI and the Compose file; finish what its prompt lists
+as not translated. Otherwise run `nk hooks write` first. Follow
+[docs/setup-hooks.md](https://github.com/ree-auz/nook/blob/main/docs/setup-hooks.md),
+run `nk hooks test` in the folder you work in and fix the hooks until it
+passes. Delete the first line of a generated hook you edit. Do not commit or
+push unless asked.
+
+## Commands
+
+| Command | Use |
+| --- | --- |
+| `nk -b <name> [agent] [-p <prompt>]` | Create a workspace from the default branch (or an existing branch of that name) |
+| `nk <name>` | Print a workspace's path; with an agent, start it there |
+| `nk ls --json` | Every workspace of this repository: `name`, `repo`, `path`, `port`, `changes`, `ahead`, `behind`, `pr` (`number`, `state`, `ci`) |
+| `nk rm <name>... -n` | Show what removing would back up and delete, change nothing |
+| `nk clean -n` | Show which workspaces are merged and would be removed |
+| `nk hooks test` | Run this folder's hooks in a temporary workspace; fails on leftovers |
+| `nk hooks` | The repository's hooks: allowed, tested |
+| `nk doctor` | Check nk's tools; exit 1 when something is broken |
+
+Pass `-y` to `nk rm` or `nk clean` only when the person asked for the
+removal. Both back up uncommitted changes and unpushed commits to
+`~/nook/backup/<repo>/` first.
+
+## Reading results
+
+Exit code 0 means success. On failure, stderr starts with `✗ what failed`,
+followed by `○` lines saying why and what to do next. Follow those lines
+instead of guessing.