@arthony/keybook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ariyapong W.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# keybook
+
+A self-contained, open-source **macOS TUI** for searching the keyboard
+shortcuts and short recipes of your most-used apps. Launch `keybook`,
+fuzzy-search by intent ("finder new tab", "terminal here"), and learn your
+shortcuts along the way.
+
+## Install
+
+```bash
+npm install -g @arthony/keybook
+# or run without installing:
+npx @arthony/keybook
+```
+
+Requires Node 22+ and macOS. The package is published under the `@arthony`
+scope, but the commands it installs are still `keybook` (and the `kb` alias).
+
+## Usage
+
+```bash
+keybook          # launch the TUI (alias: kb)
+keybook path     # print the data directory
+keybook edit     # open the data directory in $EDITOR
+keybook check    # validate your data files
+```
+
+In the TUI: type to fuzzy-search, ↑/↓ to move, ⏎ to copy the shortcut (or a
+recipe's command) to the clipboard, ⎋ to quit.
+
+## Your data
+
+Shortcuts live in plain YAML files you own — by default `~/.config/keybook/`
+(override with `$KEYBOOK_DATA_DIR`, e.g. point it at a synced/git folder to
+share across machines). On first run the directory is seeded from a bundled
+starter set; your edits are never overwritten.
+
+Each entry is a key combo **or** a short recipe:
+
+```yaml
+app: Finder
+entries:
+  - action: Open a new tab
+    keys: "⌘T"
+    tags: [new tab]
+  - action: Open Terminal at the current folder
+    steps: [Right-click the folder, Services → "New Terminal at Folder"]
+    tags: [terminal here]
+```
+
+Add entries by hand, or ask an AI assistant to append them and run
+`keybook check` before committing.
+
+## Development
+
+Requires Node 22+ and pnpm. One-shot setup after cloning:
+
+```bash
+git clone https://github.com/Ariyapong/keybook.git
+cd keybook
+./scripts/dev-setup.sh    # checks Node, enables pnpm, installs, runs tests
+```
+
+Or manually:
+
+```bash
+corepack enable           # enables pnpm (or: npm i -g pnpm)
+pnpm install
+pnpm test                 # run the suite
+pnpm build                # bundle to dist/cli.js
+pnpm dev                  # run the TUI from source (tsx)
+```
+
+Also available: `pnpm typecheck`, `pnpm lint`, `pnpm format`.
+
+**Layout:** `src/data` (zod schema + YAML loader), `src/config.ts` (data dir +
+first-run seeding), `src/search.ts` (fzf), `src/tui` (Ink components),
+`src/cli.ts` (commander entry), `seed/` (bundled starter data). Design docs are
+in `docs/superpowers/`.
+
+If `pnpm lint` reports a missing Biome binary, run `pnpm approve-builds`
+(pnpm skips package build scripts by default).
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawn } from "child_process";
+import { Command } from "commander";
+import { render } from "ink";
+import { createElement } from "react";
+
+// src/config.ts
+import { cpSync, existsSync, mkdirSync, readdirSync } from "fs";
+import { homedir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var YAML_RE = /\.ya?ml$/;
+function resolveDataDir(env = process.env) {
+  if (env.KEYBOOK_DATA_DIR) return { dir: env.KEYBOOK_DATA_DIR, source: "env" };
+  if (env.XDG_CONFIG_HOME) return { dir: join(env.XDG_CONFIG_HOME, "keybook"), source: "xdg" };
+  return { dir: join(homedir(), ".config", "keybook"), source: "default" };
+}
+function seedDir() {
+  return join(dirname(fileURLToPath(import.meta.url)), "..", "seed");
+}
+function ensureDataDir(dir, seed = seedDir()) {
+  const hasYaml = existsSync(dir) && readdirSync(dir).some((f) => YAML_RE.test(f));
+  if (hasYaml) return { initialized: false, fileCount: 0 };
+  mkdirSync(dir, { recursive: true });
+  const seedFiles = readdirSync(seed).filter((f) => YAML_RE.test(f));
+  for (const f of seedFiles) cpSync(join(seed, f), join(dir, f));
+  return { initialized: true, fileCount: seedFiles.length };
+}
+
+// src/data/loader.ts
+import { readFileSync, readdirSync as readdirSync2 } from "fs";
+import { join as join2 } from "path";
+import { parse as parseYaml } from "yaml";
+
+// src/data/schema.ts
+import { z } from "zod";
+var entrySchema = z.object({
+  action: z.string().min(1),
+  keys: z.string().min(1).optional(),
+  steps: z.array(z.string().min(1)).min(1).optional(),
+  command: z.string().min(1).optional(),
+  tags: z.array(z.string().min(1)).optional(),
+  notes: z.string().min(1).optional(),
+  source: z.string().min(1).optional()
+}).strict().refine((e) => Boolean(e.keys) || Boolean(e.steps) || Boolean(e.command), {
+  message: "entry must have at least one of: keys, steps, command"
+});
+var fileShape = z.object({
+  app: z.string().min(1),
+  entries: z.array(z.unknown()).min(1)
+}).strict();
+
+// src/data/loader.ts
+var YAML_RE2 = /\.ya?ml$/;
+function loadEntries(dataDir) {
+  const entries = [];
+  const errors = [];
+  let files;
+  try {
+    files = readdirSync2(dataDir).filter((f) => YAML_RE2.test(f)).sort();
+  } catch (err) {
+    errors.push({
+      file: dataDir,
+      entryIndex: null,
+      message: `cannot read data dir: ${err.message}`
+    });
+    return { entries, errors };
+  }
+  for (const file of files) {
+    let raw;
+    try {
+      raw = parseYaml(readFileSync(join2(dataDir, file), "utf8"));
+    } catch (err) {
+      errors.push({
+        file,
+        entryIndex: null,
+        message: `YAML parse error: ${err.message}`
+      });
+      continue;
+    }
+    const shape = fileShape.safeParse(raw);
+    if (!shape.success) {
+      errors.push({
+        file,
+        entryIndex: null,
+        message: shape.error.issues[0]?.message ?? "invalid file shape"
+      });
+      continue;
+    }
+    const { app, entries: rawEntries } = shape.data;
+    rawEntries.forEach((rawEntry, i) => {
+      const parsed = entrySchema.safeParse(rawEntry);
+      if (!parsed.success) {
+        errors.push({
+          file,
+          entryIndex: i,
+          message: parsed.error.issues.map((s) => s.message).join("; ")
+        });
+        return;
+      }
+      entries.push({ app, ...parsed.data });
+    });
+  }
+  return { entries, errors };
+}
+
+// src/commands.ts
+function runPath(env = process.env) {
+  const { dir, source } = resolveDataDir(env);
+  return `${dir}  (source: ${source})`;
+}
+function runCheck(dir) {
+  const { entries, errors } = loadEntries(dir);
+  if (errors.length === 0) return { ok: true, lines: [`\u2713 ${entries.length} entries OK`] };
+  return {
+    ok: false,
+    lines: errors.map(
+      (e) => `\u2717 ${e.file}${e.entryIndex !== null ? ` [entry ${e.entryIndex}]` : ""}: ${e.message}`
+    )
+  };
+}
+
+// src/tui/App.tsx
+import { Box as Box6, useApp, useInput, useStdout } from "ink";
+import { useMemo, useState } from "react";
+
+// src/clipboard.ts
+import { spawnSync } from "child_process";
+function copyToClipboard(text) {
+  try {
+    const res = spawnSync("pbcopy", { input: text });
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+// src/search.ts
+import { Fzf, extendedMatch } from "fzf";
+function haystack(e) {
+  return [e.action, (e.tags ?? []).join(" "), e.app, e.keys ?? "", e.notes ?? ""].filter(Boolean).join("  ");
+}
+function search(entries, query) {
+  const q = query.trim();
+  if (!q) {
+    return [...entries].sort(
+      (a, b) => a.app.localeCompare(b.app) || a.action.localeCompare(b.action)
+    );
+  }
+  const fzf = new Fzf(entries, { selector: haystack, match: extendedMatch });
+  return fzf.find(q).map((r) => r.item);
+}
+
+// src/tui/Footer.tsx
+import { Box, Text } from "ink";
+import { jsx, jsxs } from "react/jsx-runtime";
+function Footer({
+  flash,
+  errorCount,
+  resultCount
+}) {
+  return /* @__PURE__ */ jsxs(Box, { marginTop: 1, justifyContent: "space-between", children: [
+    /* @__PURE__ */ jsxs(Text, { color: "gray", children: [
+      "\u2191\u2193 move \u23CE copy \u238B quit (",
+      resultCount,
+      ")"
+    ] }),
+    flash ? /* @__PURE__ */ jsx(Text, { color: "green", children: flash }) : errorCount > 0 ? /* @__PURE__ */ jsxs(Text, { color: "yellow", children: [
+      "\u26A0 ",
+      errorCount,
+      " skipped \u2014 run `keybook check`"
+    ] }) : /* @__PURE__ */ jsx(Text, { children: " " })
+  ] });
+}
+
+// src/tui/PreviewPane.tsx
+import { Box as Box2, Text as Text2 } from "ink";
+
+// src/tui/keycaps.ts
+var GLYPHS = /* @__PURE__ */ new Set(["\u2318", "\u2325", "\u2303", "\u21E7", "\u21EA", "\u23CE", "\u238B", "\u232B", "\u21E5", "\u2423", "\u2191", "\u2193", "\u2190", "\u2192"]);
+function parseSegment(seg) {
+  const tokens = [];
+  let buf = "";
+  for (const ch of seg) {
+    if (GLYPHS.has(ch)) {
+      if (buf) {
+        tokens.push(buf);
+        buf = "";
+      }
+      tokens.push(ch);
+    } else if (ch === " ") {
+      if (buf) {
+        tokens.push(buf);
+        buf = "";
+      }
+    } else {
+      buf += ch;
+    }
+  }
+  if (buf) tokens.push(buf);
+  return tokens.length ? tokens : [seg];
+}
+function parseKeys(input) {
+  return input.split(",").map((s) => s.trim()).filter(Boolean).map(parseSegment);
+}
+
+// src/tui/PreviewPane.tsx
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function KeyCaps({ value }) {
+  const chords = parseKeys(value);
+  return /* @__PURE__ */ jsx2(Box2, { children: chords.map((seg, si) => (
+    // biome-ignore lint/suspicious/noArrayIndexKey: token order is stable; tokens can repeat (e.g. ⌃X⌃E) so the value is not a unique key
+    /* @__PURE__ */ jsxs2(Box2, { children: [
+      si > 0 ? /* @__PURE__ */ jsx2(Text2, { children: " , " }) : null,
+      seg.map((tok, ti) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: see above — repeated tokens make the value non-unique
+        /* @__PURE__ */ jsx2(Box2, { marginRight: 1, borderStyle: "round", paddingX: 1, children: /* @__PURE__ */ jsx2(Text2, { bold: true, children: tok }) }, ti)
+      ))
+    ] }, si)
+  )) });
+}
+function PreviewPane({ entry, width = "50%" }) {
+  if (!entry) return null;
+  return /* @__PURE__ */ jsxs2(Box2, { flexDirection: "column", width, paddingLeft: 2, children: [
+    /* @__PURE__ */ jsx2(Text2, { color: "cyan", children: entry.app }),
+    /* @__PURE__ */ jsx2(Text2, { bold: true, children: entry.action }),
+    /* @__PURE__ */ jsxs2(Box2, { marginTop: 1, flexDirection: "column", children: [
+      entry.keys ? /* @__PURE__ */ jsx2(KeyCaps, { value: entry.keys }) : null,
+      entry.steps?.map((s, i) => /* @__PURE__ */ jsxs2(Text2, { children: [
+        i + 1,
+        ". ",
+        s
+      ] }, s)),
+      entry.command ? /* @__PURE__ */ jsxs2(Text2, { color: "green", children: [
+        "$ ",
+        entry.command
+      ] }) : null
+    ] }),
+    entry.tags?.length ? /* @__PURE__ */ jsxs2(Text2, { color: "gray", children: [
+      "tags: ",
+      entry.tags.join(", ")
+    ] }) : null,
+    entry.notes ? /* @__PURE__ */ jsx2(Text2, { color: "gray", children: entry.notes }) : null
+  ] });
+}
+
+// src/tui/ResultList.tsx
+import { Box as Box4, Text as Text4 } from "ink";
+
+// src/tui/ResultRow.tsx
+import { Box as Box3, Text as Text3 } from "ink";
+import { jsxs as jsxs3 } from "react/jsx-runtime";
+function ResultRow({ entry, selected }) {
+  const right = entry.keys ?? "recipe";
+  return /* @__PURE__ */ jsxs3(Box3, { children: [
+    /* @__PURE__ */ jsxs3(Text3, { color: selected ? "cyan" : void 0, inverse: selected, children: [
+      selected ? "\u25B8 " : "  ",
+      entry.app,
+      " \xB7 ",
+      entry.action
+    ] }),
+    /* @__PURE__ */ jsxs3(Text3, { color: "gray", children: [
+      " ",
+      right
+    ] })
+  ] });
+}
+
+// src/tui/ResultList.tsx
+import { jsx as jsx3, jsxs as jsxs4 } from "react/jsx-runtime";
+function ResultList({
+  results,
+  selected,
+  query,
+  height = 12,
+  width = "50%"
+}) {
+  if (results.length === 0) {
+    return /* @__PURE__ */ jsx3(Box4, { width, justifyContent: "center", children: /* @__PURE__ */ jsxs4(Text4, { color: "gray", children: [
+      'No matches for "',
+      query,
+      '"'
+    ] }) });
+  }
+  const start = Math.max(0, Math.min(selected - Math.floor(height / 2), results.length - height));
+  const visible = results.slice(Math.max(0, start), Math.max(0, start) + height);
+  return /* @__PURE__ */ jsx3(Box4, { flexDirection: "column", width, children: visible.map((e, i) => /* @__PURE__ */ jsx3(
+    ResultRow,
+    {
+      entry: e,
+      selected: Math.max(0, start) + i === selected
+    },
+    `${e.app}:${e.action}`
+  )) });
+}
+
+// src/tui/SearchInput.tsx
+import { Box as Box5, Text as Text5 } from "ink";
+import { jsx as jsx4, jsxs as jsxs5 } from "react/jsx-runtime";
+function SearchInput({ query }) {
+  return /* @__PURE__ */ jsxs5(Box5, { children: [
+    /* @__PURE__ */ jsx4(Text5, { color: "cyan", children: "search: " }),
+    /* @__PURE__ */ jsx4(Text5, { children: query }),
+    /* @__PURE__ */ jsx4(Text5, { inverse: true, children: " " })
+  ] });
+}
+
+// src/tui/layout.ts
+var RESERVED_ROWS = 4;
+function visibleListHeight(terminalRows) {
+  const rows = terminalRows && terminalRows > 0 ? terminalRows : 24;
+  return Math.max(1, rows - RESERVED_ROWS);
+}
+function columnWidths(terminalCols) {
+  const cols = terminalCols && terminalCols > 0 ? terminalCols : 80;
+  const left = Math.floor(cols / 2);
+  return { left, right: cols - left };
+}
+
+// src/tui/App.tsx
+import { jsx as jsx5, jsxs as jsxs6 } from "react/jsx-runtime";
+function App({ entries, errorCount = 0, onCopy = copyToClipboard }) {
+  const { exit } = useApp();
+  const { stdout } = useStdout();
+  const [query, setQuery] = useState("");
+  const [selected, setSelected] = useState(0);
+  const [flash, setFlash] = useState("");
+  const results = useMemo(() => search(entries, query), [entries, query]);
+  const sel = results.length ? Math.min(selected, results.length - 1) : 0;
+  const current = results[sel];
+  const listHeight = visibleListHeight(stdout?.rows);
+  const { left, right } = columnWidths(stdout?.columns);
+  useInput((input, key) => {
+    if (!key.return && flash) setFlash("");
+    if (key.escape || key.ctrl && input === "c") {
+      exit();
+      return;
+    }
+    if (key.downArrow || key.ctrl && input === "n") {
+      setSelected((s) => Math.min(s + 1, results.length - 1));
+      return;
+    }
+    if (key.upArrow || key.ctrl && input === "p") {
+      setSelected((s) => Math.max(s - 1, 0));
+      return;
+    }
+    if (key.return) {
+      if (current) {
+        const text = current.keys ?? current.command ?? `${current.app}: ${current.action}`;
+        setFlash(onCopy(text) ? "\u2713 copied!" : "\u2717 copy failed");
+      }
+      return;
+    }
+    if (key.backspace || key.delete) {
+      setQuery((q) => q.slice(0, -1));
+      setSelected(0);
+      return;
+    }
+    if (input && !key.ctrl && !key.meta) {
+      setQuery((q) => q + input);
+      setSelected(0);
+    }
+  });
+  return /* @__PURE__ */ jsxs6(Box6, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsx5(SearchInput, { query }),
+    /* @__PURE__ */ jsxs6(Box6, { children: [
+      /* @__PURE__ */ jsx5(
+        ResultList,
+        {
+          results,
+          selected: sel,
+          query,
+          height: listHeight,
+          width: left
+        }
+      ),
+      /* @__PURE__ */ jsx5(PreviewPane, { entry: current, width: right })
+    ] }),
+    /* @__PURE__ */ jsx5(Footer, { flash, errorCount, resultCount: results.length })
+  ] });
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("keybook").description("Search keyboard shortcuts & recipes for your apps").version("0.1.0");
+program.command("path").description("Print the data directory").action(() => {
+  console.log(runPath());
+});
+program.command("edit").description("Open the data directory in $EDITOR").action(() => {
+  const { dir } = resolveDataDir();
+  ensureDataDir(dir);
+  const editor = process.env.EDITOR || "code";
+  const child = spawn(editor, [dir], { stdio: "inherit" });
+  child.on("error", () => spawn("open", [dir], { stdio: "inherit" }));
+});
+program.command("check").description("Validate all data files").action(() => {
+  const { dir } = resolveDataDir();
+  ensureDataDir(dir);
+  const result = runCheck(dir);
+  for (const line of result.lines) (result.ok ? console.log : console.error)(line);
+  process.exit(result.ok ? 0 : 1);
+});
+program.action(() => {
+  const { dir } = resolveDataDir();
+  const init = ensureDataDir(dir);
+  if (init.initialized) console.log(`Initialized ${dir} from seed (${init.fileCount} files).`);
+  const { entries, errors } = loadEntries(dir);
+  for (const e of errors) console.error(`\u26A0 ${e.file}: ${e.message}`);
+  render(createElement(App, { entries, errorCount: errors.length }));
+});
+program.parse();

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@arthony/keybook",
+  "version": "0.1.0",
+  "publishConfig": { "access": "public" },
+  "description": "A macOS TUI for searching keyboard shortcuts and recipes of your favorite apps",
+  "keywords": [
+    "cli",
+    "tui",
+    "ink",
+    "keyboard-shortcuts",
+    "shortcuts",
+    "cheatsheet",
+    "macos",
+    "terminal",
+    "productivity"
+  ],
+  "homepage": "https://github.com/Ariyapong/keybook#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/Ariyapong/keybook.git" },
+  "bugs": { "url": "https://github.com/Ariyapong/keybook/issues" },
+  "author": "Ariyapong Wimolnoch",
+  "type": "module",
+  "bin": { "keybook": "dist/cli.js", "kb": "dist/cli.js" },
+  "files": ["dist", "seed", "README.md", "LICENSE"],
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "fzf": "^0.5.2",
+    "ink": "^5.0.1",
+    "react": "^18.3.1",
+    "yaml": "^2.5.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.7.0",
+    "@types/react": "^18.3.0",
+    "ink-testing-library": "^4.0.0",
+    "tsup": "^8.3.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "license": "MIT"
+}

package/seed/claude.yaml

@@ -0,0 +1,21 @@
+app: Claude
+entries:
+  - action: Start a new chat
+    keys: "⌘N"
+    notes: Labeled "New Conversation" in the File menu.
+  - action: Send the message
+    keys: "⏎"
+  - action: Insert a newline in the message
+    keys: "⇧⏎"
+    tags: [new line]
+  - action: Search your chats
+    keys: "⌘K"
+    notes: In-app shortcut (not in the menu bar). Distinct from Edit → Find (⌘F).
+    tags: [search, find chats]
+  - action: Summon Claude from anywhere (global hotkey)
+    steps:
+      - Open Claude → Settings
+      - Set a global keyboard shortcut for the quick launcher
+      - Press that shortcut from any app to summon Claude
+    notes: The Claude desktop app supports a configurable global hotkey.
+    tags: [global, launcher, quick]

package/seed/edge.yaml

@@ -0,0 +1,39 @@
+app: Microsoft Edge
+entries:
+  - action: Open a new tab
+    keys: "⌘T"
+    tags: [new tab]
+  - action: Reopen the last closed tab
+    keys: "⌘⇧T"
+    tags: [restore tab]
+  - action: Open a new window
+    keys: "⌘N"
+  - action: Open a new InPrivate window
+    keys: "⌘⇧N"
+    tags: [incognito, private]
+  - action: Close the current tab
+    keys: "⌘W"
+  - action: Next / previous tab
+    keys: "⌃⇥, ⌃⇧⇥"
+  - action: Jump to tab 1–8
+    keys: "⌘1"
+    notes: ⌘1–⌘8 jump to that tab; ⌘9 jumps to the last tab.
+  - action: Focus the address bar
+    keys: "⌘L"
+    tags: [omnibox, url]
+  - action: Find on the page
+    keys: "⌘F"
+  - action: Reload / hard reload
+    keys: "⌘R, ⌘⇧R"
+  - action: Open Developer Tools
+    keys: "⌘⌥I"
+    tags: [devtools, inspect]
+  - action: Open History
+    keys: "⌘Y"
+  - action: Bookmark this page
+    keys: "⌘D"
+    tags: [favorite]
+  - action: Zoom in / out / reset
+    keys: "⌘+, ⌘-, ⌘0"
+  - action: Back / forward
+    keys: "⌘[, ⌘]"

package/seed/finder.yaml

@@ -0,0 +1,52 @@
+app: Finder
+entries:
+  - action: Open a new tab
+    keys: "⌘T"
+    tags: [new tab]
+  - action: Open a new Finder window
+    keys: "⌘N"
+  - action: Create a new folder
+    keys: "⌘⇧N"
+    tags: [new folder]
+  - action: Go to folder by path
+    keys: "⌘⇧G"
+    tags: [go to, path]
+  - action: Go up one folder
+    keys: "⌘↑"
+  - action: Open selected item
+    keys: "⌘↓"
+  - action: Back / Forward
+    keys: "⌘[, ⌘]"
+    tags: [history, navigate]
+  - action: Rename the selected item
+    keys: "⏎"
+    notes: In Finder, Return renames (it does not open).
+  - action: Quick Look the selected item
+    keys: "␣"
+    tags: [preview, space]
+  - action: Show or hide hidden files
+    keys: "⌘⇧."
+    tags: [dotfiles, hidden]
+  - action: Get Info
+    keys: "⌘I"
+  - action: Duplicate
+    keys: "⌘D"
+  - action: Move to Trash
+    keys: "⌘⌫"
+    tags: [delete]
+  - action: Move copied files here (cut/paste)
+    keys: "⌘⌥V"
+    tags: [move, cut, paste]
+  - action: Empty the Trash
+    keys: "⌘⇧⌫"
+  - action: View as list / columns / gallery
+    keys: "⌘2"
+    notes: ⌘1 icons, ⌘2 list, ⌘3 columns, ⌘4 gallery.
+  - action: Open Terminal at the current folder
+    steps:
+      - Right-click the folder (or its name in the path bar at the bottom)
+      - Choose Services → "New Terminal at Folder"
+    notes: >-
+      Enable once in System Settings → Keyboard → Keyboard Shortcuts →
+      Services → Files and Folders → "New Terminal at Folder".
+    tags: [terminal here, open terminal, cd]

package/seed/fork.yaml

@@ -0,0 +1,27 @@
+app: Fork
+entries:
+  - action: Open a repository
+    keys: "⌘O"
+  - action: Open a new tab
+    keys: "⌘T"
+  - action: Close the current tab
+    keys: "⌘W"
+  - action: Commit the staged changes
+    keys: "⌘⏎"
+    notes: From the commit message box. The Repository → Commit menu item is ⇧⌘C.
+  - action: Fetch
+    keys: "⇧⌘F"
+    notes: Add ⌥ for Quick Fetch (skips the dialog) — ⌥⇧⌘F.
+    tags: [fetch]
+  - action: Pull
+    keys: "⇧⌘L"
+    notes: Add ⌥ for Quick Pull — ⌥⇧⌘L.
+    tags: [pull]
+  - action: Push
+    keys: "⇧⌘P"
+    notes: Add ⌥ for Quick Push — ⌥⇧⌘P.
+    tags: [push]
+  - action: Open Quick Launch (command palette)
+    keys: "⌘P"
+    notes: Fork's fuzzy action launcher.
+    tags: [palette, actions]

package/seed/macos.yaml

@@ -0,0 +1,50 @@
+app: macOS
+entries:
+  - action: Open Spotlight search
+    keys: "⌘␣"
+    tags: [search, launch]
+  - action: Switch between open apps
+    keys: "⌘⇥"
+    tags: [app switcher]
+  - action: Switch between windows of the current app
+    keys: "⌘`"
+  - action: Screenshot a region to a file
+    keys: "⌘⇧4"
+    tags: [screenshot, capture]
+  - action: Screenshot the whole screen to a file
+    keys: "⌘⇧3"
+    tags: [screenshot]
+  - action: Screenshot a region to the clipboard
+    keys: "⌃⌘⇧4"
+    tags: [screenshot, copy]
+  - action: Open the screenshot / recording toolbar
+    keys: "⌘⇧5"
+    tags: [screenshot, record]
+  - action: Quit the current app
+    keys: "⌘Q"
+  - action: Hide the current app
+    keys: "⌘H"
+  - action: Minimize the window
+    keys: "⌘M"
+  - action: Close the window
+    keys: "⌘W"
+  - action: Toggle full screen
+    keys: "⌃⌘F"
+  - action: Open Mission Control
+    keys: "⌃↑"
+  - action: Move one space left / right
+    keys: "⌃←, ⌃→"
+  - action: Lock the screen
+    keys: "⌃⌘Q"
+  - action: Open the Force Quit dialog
+    keys: "⌥⌘⎋"
+    tags: [force quit]
+  - action: Open the emoji & symbols picker
+    keys: "⌃⌘␣"
+    tags: [emoji]
+  - action: Record your screen
+    steps:
+      - Press ⌘⇧5
+      - Choose "Record Entire Screen" or "Record Selected Portion", then click Record
+      - To stop, click the ⏹ stop button in the menu bar
+    tags: [screen recording]

package/seed/nano.yaml

@@ -0,0 +1,51 @@
+app: Nano
+entries:
+  - action: Save the file (write out)
+    keys: "⌃O"
+    tags: [save, write]
+  - action: Exit nano
+    keys: "⌃X"
+    tags: [quit, exit]
+  - action: Show help
+    keys: "⌃G"
+    tags: [help]
+  - action: Cut the current line
+    keys: "⌃K"
+    tags: [cut, delete]
+  - action: Paste (uncut) the cut text
+    keys: "⌃U"
+    tags: [paste, uncut]
+  - action: Set a mark, then move to select
+    keys: "⌃6"
+    notes: ⌃6 (or ⌃^) starts a selection; move the cursor to extend it, then ⌃K cuts it.
+    tags: [select, mark]
+  - action: Search
+    keys: "⌃W"
+    notes: After ⌃W, press ⏎ again to repeat the last search.
+    tags: [find, search]
+  - action: Search and replace
+    keys: "⌃\\"
+    tags: [replace]
+  - action: Go to line / column
+    keys: "⌃_"
+    tags: [goto, line]
+  - action: Go to top / bottom of the file
+    keys: "⌥\\, ⌥/"
+    tags: [top, bottom]
+  - action: Page up / down
+    keys: "⌃Y, ⌃V"
+    tags: [scroll, page]
+  - action: Undo / redo
+    keys: "⌥U, ⌥E"
+    tags: [undo, redo]
+  - action: Show the current cursor position
+    keys: "⌃C"
+    tags: [position, line number]
+  - action: Notation note (Control and Meta keys)
+    steps:
+      - nano writes ⌃ as "^" (Control) and ⌥ as "M-" (Meta)
+      - "Example: ^O means Control-O; M-U means Meta-U"
+    notes: >-
+      On macOS, Meta = Option. If ⌥ shortcuts don't work in Terminal, enable
+      Terminal → Settings → Profiles → Keyboard → "Use Option as Meta key".
+    tags: [notation, meta, help]

package/seed/terminal.yaml

@@ -0,0 +1,71 @@
+app: Terminal
+entries:
+  - action: Open a new tab
+    keys: "⌘T"
+    tags: [new tab]
+  - action: Open a new window
+    keys: "⌘N"
+  - action: Close the current tab
+    keys: "⌘W"
+  - action: Next / previous tab
+    keys: "⌃⇥, ⌃⇧⇥"
+    tags: [switch tab]
+  - action: Clear the screen and scrollback
+    keys: "⌘K"
+    tags: [clear]
+  - action: Find in the terminal
+    keys: "⌘F"
+  - action: Increase / decrease font size
+    keys: "⌘+, ⌘-"
+  - action: Jump to start / end of line
+    keys: "⌃A, ⌃E"
+    tags: [cursor, beginning, end, readline]
+  - action: Move back / forward one word
+    keys: "⌥B, ⌥F"
+    tags: [cursor, word, readline]
+  - action: Delete to end of line
+    keys: "⌃K"
+    tags: [readline, kill]
+  - action: Delete the previous word
+    keys: "⌃W"
+    tags: [readline]
+  - action: Clear the screen (keep the current line)
+    keys: "⌃L"
+    tags: [readline]
+  - action: Reverse-search command history
+    keys: "⌃R"
+    tags: [history, search, readline]
+  - action: Cancel the current command
+    keys: "⌃C"
+    tags: [interrupt]
+  - action: Delete to the start of the line
+    keys: "⌃U"
+    tags: [readline, kill]
+  - action: Delete the character under the cursor (or EOF / logout)
+    keys: "⌃D"
+    notes: On an empty line, ⌃D signals end-of-input and can close the shell.
+    tags: [readline, delete, eof]
+  - action: Paste the last killed (deleted) text
+    keys: "⌃Y"
+    tags: [readline, yank, paste]
+  - action: Delete the next word
+    keys: "⌥D"
+    tags: [readline, word]
+  - action: Swap (transpose) the last two characters
+    keys: "⌃T"
+    tags: [readline, transpose]
+  - action: Suspend the running program, then resume it
+    keys: "⌃Z"
+    command: fg
+    notes: ⌃Z suspends to the background; type `fg` to resume (or `bg` to run it in the background).
+    tags: [suspend, background, job]
+  - action: Repeat the last command / reuse its last argument
+    keys: "!!, !$"
+    notes: >-
+      !! re-runs the previous command (e.g. `sudo !!`); !$ expands to the last
+      argument of the previous command.
+    tags: [history, tip, bang]
+  - action: Edit the current command line in your $EDITOR
+    keys: "⌃X⌃E"
+    notes: Opens the half-typed command in $EDITOR; save and quit to run it (bash/zsh).
+    tags: [readline, editor, tip]

package/seed/text-editing.yaml

@@ -0,0 +1,44 @@
+app: Text editing
+entries:
+  - action: Move one word left / right
+    keys: "⌥←, ⌥→"
+    tags: [word, navigation, cursor]
+  - action: Move to start / end of the line
+    keys: "⌘←, ⌘→"
+    tags: [line, home, end]
+  - action: Move to start / end of the document
+    keys: "⌘↑, ⌘↓"
+    tags: [top, bottom, document]
+  - action: Delete the previous word
+    keys: "⌥⌫"
+    tags: [delete, word, backspace]
+  - action: Delete to the start of the line
+    keys: "⌘⌫"
+    tags: [delete, line]
+  - action: Delete the next word (forward)
+    keys: "fn⌥⌫"
+    notes: ⌫ is Delete (Backspace); fn turns it into Forward Delete (⌦).
+    tags: [delete, word, forward]
+  - action: Select one word left / right
+    keys: "⌥⇧←, ⌥⇧→"
+    tags: [select, word]
+  - action: Select to start / end of the line
+    keys: "⌘⇧←, ⌘⇧→"
+    tags: [select, line]
+  - action: Select to start / end of the document
+    keys: "⌘⇧↑, ⌘⇧↓"
+    tags: [select, document]
+  - action: Select all
+    keys: "⌘A"
+    tags: [select, all]
+  - action: Undo / redo
+    keys: "⌘Z, ⇧⌘Z"
+    tags: [undo, redo]
+  - action: Jump to start / end of line (emacs-style)
+    keys: "⌃A, ⌃E"
+    notes: Works in most macOS native (Cocoa) text fields, not every app.
+    tags: [cursor, readline]
+  - action: Delete to end of line (emacs-style)
+    keys: "⌃K"
+    notes: Cocoa text fields; pairs with ⌃Y to paste it back.
+    tags: [delete, kill]

package/seed/tmux.yaml

@@ -0,0 +1,61 @@
+app: tmux
+entries:
+  - action: Prefix key (press before each command below)
+    keys: "⌃B"
+    notes: Default tmux prefix.
+  - action: Create a new window
+    keys: "⌃B, c"
+  - action: Next / previous window
+    keys: "⌃B, n"
+    notes: n next, p previous.
+  - action: Go to window by number
+    keys: "⌃B, 0"
+    notes: 0–9.
+  - action: Split the pane left / right
+    keys: "⌃B, %"
+    tags: [vertical split]
+  - action: Split the pane top / bottom
+    keys: '⌃B, "'
+    tags: [horizontal split]
+  - action: Move between panes
+    keys: "⌃B, →"
+    notes: Use ↑ ↓ ← → to move.
+  - action: Toggle pane zoom
+    keys: "⌃B, z"
+    tags: [fullscreen pane, maximize]
+  - action: Close the current pane
+    keys: "⌃B, x"
+  - action: Detach from the session
+    keys: "⌃B, d"
+  - action: List sessions
+    keys: "⌃B, s"
+  - action: Rename the current window
+    keys: "⌃B, ,"
+  - action: Enter copy mode (scroll)
+    keys: "⌃B, ["
+    tags: [scroll, copy]
+  - action: Open the command prompt
+    keys: "⌃B, :"
+  - action: Reload the tmux config
+    command: tmux source-file ~/.tmux.conf
+    tags: [reload, config]
+  - action: Break the current pane into its own window
+    keys: "⌃B, !"
+    tags: [pane, window, break]
+  - action: Swap the current pane left / right
+    keys: "⌃B, {"
+    notes: "{ swaps with the previous pane; } swaps with the next."
+    tags: [pane, swap, move]
+  - action: Cycle through the preset pane layouts
+    keys: "⌃B, ␣"
+    tags: [layout, arrange]
+  - action: Show pane numbers (then press one to jump)
+    keys: "⌃B, q"
+    tags: [pane, jump]
+  - action: Kill the current window
+    keys: "⌃B, &"
+    notes: Asks for confirmation.
+    tags: [window, close, kill]
+  - action: Paste the most recent copy-mode buffer
+    keys: "⌃B, ]"
+    tags: [paste, copy]

package/seed/vim.yaml

@@ -0,0 +1,66 @@
+app: Vim
+entries:
+  - action: Enter Insert mode (before / after the cursor)
+    keys: "i, a"
+    tags: [insert, edit]
+  - action: Return to Normal mode
+    keys: "⎋"
+    tags: [normal, escape]
+  - action: Enter Visual / Visual-Block mode
+    keys: "v, ⌃V"
+    tags: [select, block]
+  - action: Save the file
+    keys: ":w⏎"
+    tags: [write, save]
+  - action: Save and quit
+    keys: ":wq⏎"
+    notes: ZZ does the same from Normal mode.
+    tags: [save, quit, exit]
+  - action: Quit without saving
+    keys: ":q!⏎"
+    tags: [quit, discard, exit]
+  - action: Go to start / end of line
+    keys: "0, $"
+    notes: "^ jumps to the first non-blank character."
+    tags: [line, motion]
+  - action: Go to top / bottom of file
+    keys: "gg, G"
+    notes: '":42⏎" jumps to line 42.'
+    tags: [motion, goto]
+  - action: Move word forward / back
+    keys: "w, b"
+    tags: [word, motion]
+  - action: Jump to the matching bracket
+    keys: "%"
+    tags: [bracket, paren, match]
+  - action: Delete / yank (copy) the current line
+    keys: "dd, yy"
+    tags: [delete, copy, cut]
+  - action: Paste after / before the cursor
+    keys: "p, P"
+    tags: [paste]
+  - action: Delete the character under the cursor
+    keys: "x"
+    tags: [delete, char]
+  - action: Undo / redo
+    keys: "u, ⌃R"
+    tags: [undo, redo]
+  - action: Repeat the last change
+    keys: "."
+    tags: [repeat, dot]
+  - action: Search, then next / previous match
+    keys: "/text⏎, n, N"
+    tags: [search, find]
+  - action: Replace every match in the file
+    keys: ":%s/old/new/g⏎"
+    notes: Add c at the end (…/gc) to confirm each replacement.
+    tags: [replace, substitute, tip]
+  - action: Change inside word / quotes / parens
+    keys: 'ciw, ci", ci('
+    notes: >-
+      Text objects — "change inner". Swap c for d to delete instead (diw, di").
+      Works with [], {}, <> too.
+    tags: [text object, tip, change]
+  - action: Indent / outdent the line or selection
+    keys: ">>, <<"
+    tags: [indent]

package/seed/vscode.yaml

@@ -0,0 +1,65 @@
+app: VS Code
+entries:
+  - action: Show the Command Palette
+    keys: "⌘⇧P"
+    tags: [commands, palette]
+  - action: Quick Open a file by name
+    keys: "⌘P"
+    tags: [open file, goto]
+  - action: Toggle the integrated terminal
+    keys: "⌃`"
+    tags: [terminal]
+  - action: Toggle the sidebar
+    keys: "⌘B"
+  - action: Add a cursor below
+    keys: "⌘⌥↓"
+    tags: [multi cursor]
+  - action: Select the next occurrence of the selection
+    keys: "⌘D"
+    tags: [multi cursor, select]
+  - action: Go to a line number
+    keys: "⌃G"
+  - action: Go to definition
+    keys: "F12"
+  - action: Rename the symbol
+    keys: "F2"
+    tags: [refactor]
+  - action: Find / Replace in the file
+    keys: "⌘F, ⌥⌘F"
+  - action: Find in all files
+    keys: "⌘⇧F"
+    tags: [search]
+  - action: Toggle line comment
+    keys: "⌘/"
+  - action: Move the current line up / down
+    keys: "⌥↑, ⌥↓"
+  - action: Copy the current line up / down
+    keys: "⇧⌥↑, ⇧⌥↓"
+  - action: Format the document
+    keys: "⇧⌥F"
+  - action: Split the editor
+    keys: "⌘\\"
+  - action: Trigger a Quick Fix
+    keys: "⌘."
+    tags: [lightbulb]
+  - action: Toggle Zen Mode
+    keys: "⌘K, Z"
+    tags: [focus, fullscreen]
+  - action: Delete the current line
+    keys: "⌘⇧K"
+    tags: [delete line]
+  - action: Insert a line below / above
+    keys: "⌘⏎, ⇧⌘⏎"
+    tags: [new line]
+  - action: Select all occurrences of the current selection
+    keys: "⌘⇧L"
+    tags: [multi cursor, select]
+  - action: Go to the next problem (error / warning)
+    keys: "F8"
+    tags: [errors, diagnostics]
+  - action: Navigate back / forward (cursor history)
+    keys: "⌃-, ⌃⇧-"
+    tags: [navigate, history, goto]
+  - action: Open Keyboard Shortcuts
+    keys: "⌘K, ⌘S"
+    tags: [keybindings, shortcuts]