@cad0p/napkin 0.8.1-20260601.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Liv
+
+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,346 @@
+# napkin
+
+🧻 Knowledge system for agents. Local-first, file-based, progressively disclosed.
+
+Every great idea started on a napkin.
+
+```bash
+# pnpm
+pnpm add -g @cad0p/napkin
+
+# npm
+npm install -g @cad0p/napkin
+```
+
+---
+
+## Quick Start
+
+```bash
+# Initialize a vault
+napkin init --template coding
+
+# See what's in it
+napkin overview
+
+# Search for something
+napkin search "authentication"
+
+# Read a file
+napkin read "Architecture"
+
+# Write
+napkin create "Decision" --template Decision
+napkin append "Decision" "We chose Postgres."
+napkin daily append "- [ ] Review PR"
+```
+
+---
+
+## SDK
+
+napkin is also a library. No CLI, no stdout - just data:
+
+```typescript
+import { Napkin } from "napkin-ai";
+
+// Always works - creates bare vault if needed
+const n = new Napkin("/path/to/project");
+
+// Progressive disclosure
+const overview = n.overview();
+const results = n.search("authentication");
+const file = n.read("Architecture");
+
+// Write
+n.create({ name: "New Note", content: "# Hello" });
+n.append("New Note", "\nMore content");
+
+// Daily notes
+n.dailyEnsure();
+n.dailyAppend("- Met with team");
+
+// Everything else
+n.tags();
+n.tasks({ todo: true });
+n.linksBack("Architecture");
+n.outline("Architecture");
+n.properties();
+n.bookmarks();
+n.config();
+```
+
+Scaffold with a template:
+
+```typescript
+Napkin.scaffold("/path/to/project", { template: "coding" });
+Napkin.vaultTemplates(); // list available templates
+```
+
+All SDK methods return typed data and throw errors on failure. No `console.log`, no `process.exit`.
+
+---
+
+## Progressive Disclosure
+
+napkin is designed as a memory system for agents. Instead of dumping the full vault into context, it reveals information gradually:
+
+| Level | Command | Tokens | What it does |
+|-------|---------|--------|-------------|
+| 0 | `NAPKIN.md` | ~200 | Project context note |
+| 1 | `napkin overview` | ~1-2k | L0 + vault map with TF-IDF keywords |
+| 2 | `napkin search <query>` | ~2-5k | Ranked results with snippets |
+| 3 | `napkin read <file>` | ~5-20k | Full file content |
+
+## Benchmarks
+
+napkin includes agentic retrieval benchmarks in `bench/`. The headline result is [LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025), which tests long-term conversational memory across 500 questions.
+
+| Dataset | Sessions | pi + napkin | Best prior system | GPT-4o full context |
+|---------|----------|-------------|-------------------|---------------------|
+| Oracle | 1-6 | **92.0%** | 92.4% | 92.4% |
+| S | ~40 | **91.0%** | 86% | 64% |
+| M | ~500 | **83.0%** | 72% | n/a |
+
+Zero preprocessing. No embeddings, no graphs, no summaries. Just BM25 search on markdown files.
+
+See [`bench/README.md`](bench/README.md) for details and usage.
+
+---
+
+## Vault Structure
+
+`.napkin/` holds config. Content lives in the project directory alongside `.obsidian/`:
+
+```
+my-project/
+  .napkin/                  # napkin config
+    config.json             # Unified config (syncs to .obsidian/)
+  .obsidian/                # Obsidian config (auto-generated)
+  NAPKIN.md                 # Context note (Level 0)
+  decisions/                # Template-defined directories
+  architecture/
+  Templates/                # Note templates
+  src/                      # Your project (not in vault)
+```
+
+## Templates
+
+Scaffold a vault with a domain-specific structure:
+
+```bash
+napkin init --template coding    # decisions/, architecture/, guides/, changelog/
+napkin init --template company   # people/, projects/, runbooks/, infrastructure/
+napkin init --template product   # features/, roadmap/, research/, specs/, releases/
+napkin init --template personal  # people/, projects/, areas/, references/
+napkin init --template research  # papers/, concepts/, questions/, experiments/
+```
+
+Each template includes directory structure, `_about.md` files, Obsidian note templates, and a `NAPKIN.md` skeleton.
+
+---
+
+## For Agents
+
+Every command supports `--json` for structured output and `-q` for raw output:
+
+```bash
+napkin overview --json          # Structured vault map
+napkin search "auth" --json     # Ranked results as JSON
+napkin read "Note" -q           # Raw markdown, nothing else
+```
+
+---
+
+## CLI Reference
+
+### Global Flags
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON |
+| `-q, --quiet` | Suppress output |
+| `--vault <path>` | Vault path (default: auto-detect from cwd) |
+| `--copy` | Copy output to clipboard |
+
+### Core
+
+```bash
+napkin vault                          # Vault info
+napkin overview                       # Vault map with keywords
+napkin read <file>                    # Read file contents
+napkin create "Note" $'# Hello\nFirst note.'   # Create with content
+napkin append "Note" $'\n## Update\nNew info.'   # Append to file
+napkin prepend "Note" $'---\ntags: [new]\n---'   # Prepend frontmatter
+napkin move "Note" Archive            # Move to folder
+napkin rename "Note" "Renamed"        # Rename file
+napkin delete "Note"                  # Move to .trash
+napkin search "meeting"               # Ranked search with snippets
+napkin search "TODO" --no-snippets    # Files only
+echo "piped content" | napkin append "Note"  # Stdin support
+```
+
+### Files & Folders - `napkin file`
+
+```bash
+napkin file info <name>               # File info (path, size, dates)
+napkin file list                      # List all files
+napkin file list --ext md             # Filter by extension
+napkin file list --folder Projects    # Filter by folder
+napkin file folder <path>             # Folder info
+napkin file folders                   # List all folders
+napkin file outline "note"            # Heading tree
+napkin file wordcount "note"          # Word + character count
+```
+
+### Daily Notes - `napkin daily`
+
+```bash
+napkin daily today                    # Create today's daily note
+napkin daily path                     # Print daily note path
+napkin daily read                     # Print daily note contents
+napkin daily append "- [ ] Buy groceries"
+napkin daily prepend "## Morning"
+```
+
+### Tags - `napkin tag`
+
+```bash
+napkin tag list                       # List all tags
+napkin tag list --counts              # With occurrence counts
+napkin tag list --sort count          # Sort by frequency
+napkin tag info --name "project"      # Tag info
+napkin tag aliases                    # List all aliases
+```
+
+### Properties - `napkin property`
+
+```bash
+napkin property list                  # List all properties
+napkin property list --file "note"    # Properties for a file
+napkin property read --file "note" --name title
+napkin property set --file "note" --name status --value done
+napkin property remove --file "note" --name status
+```
+
+### Tasks - `napkin task`
+
+```bash
+napkin task list                      # List all tasks
+napkin task list --todo               # Incomplete only
+napkin task list --done               # Completed only
+napkin task list --daily              # Today's daily note tasks
+napkin task show --file "note" --line 3 --toggle
+```
+
+### Links - `napkin link`
+
+```bash
+napkin link out --file "note"         # Outgoing links
+napkin link back --file "note"        # Backlinks
+napkin link unresolved                # Broken links
+napkin link orphans                   # No incoming links
+napkin link deadends                  # No outgoing links
+```
+
+### Bases - `napkin base`
+
+```bash
+napkin base list                      # List .base files
+napkin base views --file "projects"   # List views
+napkin base query --file "projects"   # Query default view
+napkin base query --file "projects" --view "Active" --format csv
+napkin base create --file "projects" --name "New Item"
+```
+
+### Canvas - `napkin canvas`
+
+```bash
+napkin canvas list                    # List .canvas files
+napkin canvas read --file "Board"     # Dump canvas
+napkin canvas nodes --file "Board"    # List nodes
+napkin canvas create --file "Board"   # Create empty canvas
+napkin canvas add-node --file "Board" --type text --text "# Hello"
+napkin canvas add-edge --file "Board" --from abc1 --to def2
+napkin canvas remove-node --file "Board" --id abc1
+```
+
+### Templates - `napkin template`
+
+```bash
+napkin template list                  # List note templates
+napkin template read --name "Daily Note"
+napkin template insert --file "note" --name "Template"
+```
+
+### Bookmarks - `napkin bookmark`
+
+```bash
+napkin bookmark list                  # List bookmarks
+napkin bookmark add --file "note"     # Bookmark a file
+```
+
+### Config - `napkin config`
+
+```bash
+napkin config show                    # Show full config
+napkin config get --key search.limit  # Get a value
+napkin config set --key search.limit --value 50
+```
+
+### Graph - `napkin graph`
+
+```bash
+napkin graph                          # Interactive vault graph
+```
+
+Force-directed graph of vault notes and wikilinks. Click nodes to read content in a sidebar.
+
+---
+
+## File Resolution
+
+Files can be referenced two ways:
+- **By name** (wikilink-style): `"Active Projects"` - searches all `.md` files by basename
+- **By path**: `"Projects/Active Projects.md"` - exact path from vault root
+
+---
+
+## Architecture
+
+```
+src/
+  index.ts       # SDK exports: Napkin class + all types
+  sdk.ts         # Napkin class wrapping core modules
+  main.ts        # CLI entry (Commander) - thin wrapper
+  core/          # Pure logic, returns data, no stdout
+  commands/      # CLI wrappers: parse args → sdk → format + print
+  utils/         # Shared utilities (files, frontmatter, markdown, etc.)
+```
+
+Core modules never call `console.log`, `process.exit`, or import output utilities. They return typed data and throw errors. The CLI commands are thin wrappers that instantiate the SDK, call methods, and format the output.
+
+---
+
+## Pi Integration
+
+For [pi](https://github.com/badlogic/pi) users, install [pi-napkin](https://github.com/cad0p/pi-napkin) — vault context injection, `kb_search`/`kb_read` tools, and automatic distillation.
+
+```bash
+pi install git:github.com/cad0p/pi-napkin
+```
+
+---
+
+## Development
+
+```bash
+bun install
+bun run dev -- vault --json
+bun test
+bun run check
+```
+
+## License
+
+MIT

package/bin/napkin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Launcher for the napkin CLI.
+//
+// napkin ships its TypeScript sources directly (no committed `dist/`). Node's
+// built-in type stripping refuses to run `.ts` files under `node_modules`
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), so this tiny `.js` stub —
+// which IS allowed under node_modules — uses jiti to load the real `.ts`
+// entry point. jiti strips types AND resolves the package's `.js` import
+// specifiers to their `.ts` sources, all in pure JS (no native toolchain).
+//
+// jiti is resolved relative to THIS file (not the caller's cwd) so the bin
+// works no matter where it is invoked from.
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const { createJiti } = require("jiti");
+
+const jiti = createJiti(import.meta.url, { moduleCache: false });
+await jiti.import("../src/main.ts");

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@cad0p/napkin",
+  "version": "0.8.1-20260601.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "description": "🧻 Knowledge system for agents. Local-first, file-based, progressively disclosed.",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "bin": {
+    "napkin": "./bin/napkin.js"
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "bun run src/main.ts",
+    "build:bun": "bun build --compile src/main.ts --outfile napkin",
+    "build:bun-linux": "bun build --compile --target=bun-linux-x64 src/main.ts --outfile napkin-linux-x64",
+    "build:bun-mac-arm": "bun build --compile --target=bun-darwin-arm64 src/main.ts --outfile napkin-darwin-arm64",
+    "build:bun-mac-x64": "bun build --compile --target=bun-darwin-x64 src/main.ts --outfile napkin-darwin-x64",
+    "test": "bun test",
+    "format": "bunx biome format --write src/",
+    "lint": "bunx biome lint src/",
+    "check": "bunx biome check src/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cad0p/napkin.git"
+  },
+  "homepage": "https://github.com/cad0p/napkin#readme",
+  "bugs": {
+    "url": "https://github.com/cad0p/napkin/issues"
+  },
+  "keywords": [
+    "obsidian",
+    "cli",
+    "markdown",
+    "vault",
+    "notes",
+    "tasks",
+    "tags",
+    "search",
+    "local-first"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.14",
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.6.0",
+    "typescript": "^5.8.0"
+  },
+  "dependencies": {
+    "jiti": "^2.6.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "gray-matter": "^4.0.3",
+    "jexl": "^2.3.0",
+    "js-yaml": "^4.1.0",
+    "minisearch": "^7.2.0",
+    "sql.js": "^1.14.0"
+  },
+  "optionalDependencies": {
+    "glimpseui": "^0.3.7"
+  },
+  "trustedDependencies": [
+    "glimpseui"
+  ]
+}

package/src/commands/aliases.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createTempVault } from "../utils/test-helpers.js";
+import { aliases } from "./aliases.js";
+
+let v: { path: string; vaultPath: string; cleanup: () => void };
+
+async function captureJson(
+  fn: () => Promise<void>,
+): Promise<Record<string, unknown>> {
+  const orig = console.log;
+  const logs: string[] = [];
+  console.log = (...args: unknown[]) => logs.push(args.map(String).join(" "));
+  await fn();
+  console.log = orig;
+  return JSON.parse(logs.join(""));
+}
+
+beforeEach(() => {
+  v = createTempVault({
+    "note1.md": "---\naliases:\n  - Alpha\n  - A1\n---\nBody",
+    "note2.md": "---\naliases: Beta\n---\nBody",
+    "note3.md": "No aliases here",
+  });
+});
+
+afterEach(() => {
+  v.cleanup();
+});
+
+describe("aliases", () => {
+  test("lists all aliases", async () => {
+    const data = await captureJson(() =>
+      aliases({ json: true, vault: v.path }),
+    );
+    const a = data.aliases as string[];
+    expect(a).toContain("Alpha");
+    expect(a).toContain("A1");
+    expect(a).toContain("Beta");
+    expect(a.length).toBe(3);
+  });
+
+  test("returns total", async () => {
+    const data = await captureJson(() =>
+      aliases({ json: true, vault: v.path, total: true }),
+    );
+    expect(data.total).toBe(3);
+  });
+
+  test("filters by file", async () => {
+    const data = await captureJson(() =>
+      aliases({ json: true, vault: v.path, file: "note1" }),
+    );
+    const a = data.aliases as string[];
+    expect(a).toEqual(["Alpha", "A1"]);
+  });
+
+  test("verbose includes file paths", async () => {
+    const data = await captureJson(() =>
+      aliases({ json: true, vault: v.path, verbose: true }),
+    );
+    const a = data.aliases as { alias: string; file: string }[];
+    expect(a[0].file).toBeTruthy();
+  });
+});

package/src/commands/aliases.ts

@@ -0,0 +1,31 @@
+import { Napkin } from "../sdk.js";
+import { dim, type OutputOptions, output } from "../utils/output.js";
+
+export async function aliases(
+  opts: OutputOptions & {
+    vault?: string;
+    file?: string;
+    total?: boolean;
+    verbose?: boolean;
+  },
+) {
+  const n = new Napkin(opts.vault || process.cwd());
+  const result = n.aliases(opts.file);
+
+  output(opts, {
+    json: () => {
+      if (opts.total) return { total: result.length };
+      if (opts.verbose) return { aliases: result };
+      return { aliases: result.map((r) => r.alias) };
+    },
+    human: () => {
+      if (opts.total) {
+        console.log(result.length);
+      } else {
+        for (const r of result) {
+          console.log(opts.verbose ? `${r.alias}\t${dim(r.file)}` : r.alias);
+        }
+      }
+    },
+  });
+}

package/src/commands/bases.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { createTempVault } from "../utils/test-helpers.js";
+import { baseQuery, bases, baseViews } from "./bases.js";
+
+let v: { path: string; vaultPath: string; cleanup: () => void };
+
+async function captureJson(
+  fn: () => Promise<void>,
+): Promise<Record<string, unknown>> {
+  const orig = console.log;
+  const logs: string[] = [];
+  console.log = (...args: unknown[]) => logs.push(args.map(String).join(" "));
+  await fn();
+  console.log = orig;
+  return JSON.parse(logs.join(""));
+}
+
+beforeEach(() => {
+  v = createTempVault({
+    "Projects/alpha.md": "---\ntitle: Alpha\nstatus: active\n---\n# Alpha",
+    "Projects/beta.md": "---\ntitle: Beta\nstatus: done\n---\n# Beta",
+    "Notes/random.md": "---\ntitle: Random\n---\n# Random",
+    "projects.base":
+      'filters:\n  file.inFolder("Projects")\nviews:\n  - type: table\n    name: "All Projects"\n  - type: table\n    name: "Active"\n    filters:\n      \'status == "active"\'',
+  });
+});
+
+afterEach(() => {
+  v.cleanup();
+});
+
+describe("bases", () => {
+  test("lists .base files", async () => {
+    const data = await captureJson(() => bases({ json: true, vault: v.path }));
+    const b = data.bases as string[];
+    expect(b).toContain("projects.base");
+  });
+});
+
+describe("baseViews", () => {
+  test("lists views in a base", async () => {
+    const data = await captureJson(() =>
+      baseViews({ json: true, vault: v.path, file: "projects" }),
+    );
+    const views = data.views as { name: string; type: string }[];
+    expect(views.length).toBe(2);
+    expect(views[0].name).toBe("All Projects");
+    expect(views[1].name).toBe("Active");
+  });
+});
+
+describe("baseQuery", () => {
+  test("queries default view", async () => {
+    const data = await captureJson(() =>
+      baseQuery({ json: true, vault: v.path, file: "projects" }),
+    );
+    const rows = data.rows as Record<string, unknown>[];
+    expect(rows.length).toBe(2); // Alpha + Beta in Projects folder
+  });
+
+  test("queries named view with filters", async () => {
+    const data = await captureJson(() =>
+      baseQuery({
+        json: true,
+        vault: v.path,
+        file: "projects",
+        view: "Active",
+      }),
+    );
+    const rows = data.rows as Record<string, unknown>[];
+    expect(rows.length).toBe(1);
+    expect(rows[0].title).toBe("Alpha");
+  });
+
+  test("outputs as paths", async () => {
+    const data = await captureJson(() =>
+      baseQuery({
+        json: true,
+        vault: v.path,
+        file: "projects",
+        format: "paths",
+      }),
+    );
+    const paths = data.paths as string[];
+    expect(paths).toContain("Projects/alpha.md");
+    expect(paths).toContain("Projects/beta.md");
+  });
+});