puzzletide CLI: word search, crossword, and sudoku generator with printables, evals, and agent skills

Local-first puzzle toolkit extracted from the puzzletide.com generators:

- Word search, crossword, and sudoku engines (seeded, deterministic,
  property-tested; sudoku puzzles verified to have a unique solution)
- 1,560 bundled themed word banks (25 categories, 14k+ unique words)
- Terminal, JSON, SVG, and printable PDF output (puzzle + solution pages)
- Textavia-style command model: ptide <ns> <op>, ptide run <tool-id>,
  tools list/search/info/docs, agent manifest
- Verifiable eval tasks for benchmarking agents (by-construction grading)
- Hangman and daily sudoku in the terminal
- Five SKILL.md agent skills, loadable via: pi install npm:puzzletide

Author: catorch

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm test

.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.DS_Store

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caravaca Labs
+
+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.

README.md

@@ -0,0 +1,205 @@
+<!--
+Keyword rationale: "puzzle generator", "word search generator/maker", "crossword maker",
+"sudoku generator/solver", "printable puzzles PDF" — the phrases people type on npm/GitHub/pi.dev.
+Contiguous phrases to keep intact: "puzzle generator CLI", "word search", "crossword", "sudoku",
+"printable PDF", "agent skills".
+Banned claims (not shipped): MCP server, PNG output, AI clue generation, nonograms/cryptograms,
+speed guarantees for expert sudoku, "full English dictionary" (word tools use the bundled banks).
+-->
+
+# PuzzleTide CLI
+
+[![npm package](https://img.shields.io/npm/v/puzzletide?label=npm)](https://www.npmjs.com/package/puzzletide)
+[![Docs](https://img.shields.io/badge/docs-GitHub-24292F)](https://github.com/Caravaca-Labs/puzzletide-cli/tree/main/docs)
+[![Agent skills](https://img.shields.io/badge/agent_skills-SKILL.md-0F766E)](https://github.com/Caravaca-Labs/puzzletide-cli/blob/main/docs/agent-skills.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+
+Local-first puzzle generator CLI: word search, crossword, and sudoku — with
+printable PDF worksheets, 1,560 themed word banks, verifiable agent evals,
+and bundled agent skills. From the makers of [puzzletide.com](https://puzzletide.com).
+
+```sh
+npm install -g puzzletide
+ptide --version
+```
+
+The package installs both binaries:
+
+- `ptide`
+- `puzzletide`
+
+## Why a CLI for puzzles
+
+Ask a language model to write a word search and you get a grid where half the
+words are broken; ask it for a sudoku and you usually get one with several
+solutions, or none. Grids are exactly the kind of output LLMs are bad at and
+deterministic code is good at.
+
+PuzzleTide CLI is that deterministic code, extracted from the generators that
+run [puzzletide.com](https://puzzletide.com):
+
+- Every word search word is placed and verifiable — placement coordinates are
+  part of the output, and the generators are property-tested.
+- Every generated sudoku is checked to have exactly one solution.
+- Every crossword is validated against its own clues before it's returned.
+- Same `--seed` in, same puzzle out, on any machine.
+
+The package also ships `SKILL.md` agent skills, so coding agents (Pi, Hermes,
+OpenClaw, and other SKILL.md-based systems) reach for the CLI instead of
+hand-writing grids.
+
+## Command model
+
+```sh
+ptide <namespace> <operation> [input] [options]   # for humans
+ptide run <tool-id> [input] [options] --json      # canonical, for scripts/agents
+ptide tools list | search <q> | info <id> | docs <id>
+ptide agent manifest
+```
+
+Use short commands interactively and canonical tool ids in automation:
+
+```sh
+ptide sudoku generate --difficulty hard
+ptide run puzzle.sudoku.generate --difficulty hard --json
+```
+
+## Examples
+
+```sh
+# Word search from your own words, printed in the terminal
+ptide wordsearch generate --words "coral,shark,kelp,wave,tide"
+
+# Themed word search as a printable PDF (puzzle page + solution page)
+ptide wordsearch generate --theme animals/ocean-animals --pdf ocean.pdf
+
+# Crossword with your clues
+ptide crossword generate --words "PARIS: Capital of France; TOKYO: Capital of Japan"
+
+# Sudoku: generate, solve, and check
+ptide sudoku generate --difficulty expert --seed 42
+ptide sudoku solve "53..7....6..195....98....6.8...6...34..8.3..17...2...6.6....28....419..5....8..79"
+ptide sudoku validate --file puzzle.txt
+
+# Browse the bundled word banks
+ptide words themes --search dinosaur
+ptide words match "c_r_l"        # crossword-style pattern matching
+ptide words anagram coral
+
+# Today's puzzle
+ptide daily
+```
+
+## Tool families
+
+- **Word search** — 8 placement directions with easy/medium/hard presets,
+  auto-sized grids (6–30), accent/space/hyphen normalization, word list from
+  flags, files, or themes.
+- **Crossword** — interlocking placement with standard numbering, clue-grid
+  validation, deterministic fallback clues for theme words, unplaceable words
+  reported instead of dropped.
+- **Sudoku** — easy/medium/hard/expert generation with a uniqueness
+  guarantee, instant solver, validator that reports conflicts, solvability,
+  and solution uniqueness.
+- **Word banks** — 1,560 themed word lists (14,000+ unique words) across 25
+  categories: browse, search, pattern-match, anagrams, random picks.
+- **Evals** — reproducible puzzle task sets graded by construction, for
+  benchmarking models and agents (see below).
+- **Play** — hangman in the terminal and a shared daily sudoku.
+
+Output formats everywhere: terminal text, `--json` structured data,
+`--svg <file>` vector images, `--pdf <file>` printable worksheets
+(`--paper letter|a4`, solution page included unless `--no-solution-page`).
+
+## Agent skills
+
+Pi can load the bundled skills directly from this npm package:
+
+```sh
+pi install npm:puzzletide
+```
+
+The package manifest declares:
+
+```json
+{
+  "pi": {
+    "skills": ["./skills"]
+  }
+}
+```
+
+Five skills are included: word search, crossword, sudoku, printable puzzles,
+and agent evals. Each prefers the local CLI and checks `ptide`, `puzzletide`,
+then `npx puzzletide`. Skills never auto-install anything; agents should ask
+the user before installing.
+
+## Verifiable evals for agents
+
+Puzzle answers are checkable without an answer key: a sudoku answer either
+satisfies the rules and preserves the givens or it doesn't; a word search
+answer either spells the word along a straight line in the grid or it
+doesn't. That makes puzzles clean benchmark tasks — no LLM judge needed.
+
+```sh
+ptide eval generate --type sudoku --n 20 --difficulty hard --seed 1 --out tasks.json
+# ...run your model on tasks.json, collect [{id, answer}] ...
+ptide eval check --tasks tasks.json --answers answers.json --json
+```
+
+The (type, difficulty, n, seed) tuple fully determines the task set, so it
+names a reproducible benchmark.
+
+## Library usage
+
+The engines are importable TypeScript with no CLI involved:
+
+```ts
+import { generateSudoku, generateWordSearch, wordSearchPdf } from 'puzzletide';
+
+const sudoku = generateSudoku({ difficulty: 'hard', seed: 42 });
+const search = generateWordSearch({
+  words: ['coral', 'shark', 'kelp'],
+  directions: ['E', 'S', 'SE'],
+  seed: 7,
+});
+const pdfBytes = await wordSearchPdf(search, { title: 'Ocean Animals' });
+```
+
+More docs:
+
+- [CLI commands](./docs/cli.md)
+- [Tool registry](./docs/registry.md)
+- [Agent skills](./docs/agent-skills.md)
+
+## Online versions
+
+Prefer a browser?
+
+- [PuzzleTide word search](https://puzzletide.com/word-search)
+- [PuzzleTide crossword](https://puzzletide.com/crossword)
+- [PuzzleTide sudoku](https://puzzletide.com/sudoku)
+- [PuzzleTide hangman](https://puzzletide.com/hangman)
+- [Printable puzzles](https://puzzletide.com/printable)
+- [Make your own puzzle](https://puzzletide.com/maker)
+
+## Privacy
+
+Everything runs locally. No account, no API key, no telemetry, no network
+access.
+
+## Development
+
+```sh
+npm install
+npm run build     # tsc → dist/
+npm test          # vitest + fast-check property tests (build first: CLI tests run dist/)
+```
+
+The bundled word banks are compiled from the puzzletide.com dataset with
+`npm run build:wordbanks` (maintainers only; the compiled
+`data/wordbanks.json` is checked in).
+
+## License
+
+MIT © Caravaca Labs

data/wordbanks.json

@@ -0,0 +1,66 @@
+# Agent skills
+
+The npm package bundles `SKILL.md` agent skills for Pi, Hermes, OpenClaw, and
+other SKILL.md-based agent systems. Pi loads them straight from npm:
+
+```sh
+pi install npm:puzzletide
+```
+
+The package manifest declares:
+
+```json
+{
+  "pi": {
+    "skills": ["./skills"]
+  }
+}
+```
+
+Each skill prefers the local CLI and checks `ptide`, `puzzletide`, then
+`npx puzzletide`. Skills never auto-install dependencies; agents should ask
+the user before installing anything.
+
+## puzzletide-word-search
+
+Generate word search puzzles — themed or from custom word lists, terminal or
+printable PDF. The core instruction to agents: never hand-write a letter
+grid; the CLI guarantees every word is actually findable.
+
+## puzzletide-crossword
+
+Generate crosswords with valid interlocking grids and standard numbering.
+Agents write the clues (they're good at that); the CLI builds the grid (it's
+good at that).
+
+## puzzletide-sudoku
+
+Generate sudoku with a unique-solution guarantee, solve any puzzle from its
+81-character string, and validate user-provided grids for conflicts and
+uniqueness.
+
+## puzzletide-printable-puzzles
+
+Print-ready PDF worksheets (puzzle + solution pages, letter or A4) for
+classrooms, parties, and activity packets, including multi-sheet packets via
+`--seed`.
+
+## puzzletide-agent-evals
+
+Reproducible puzzle task sets with by-construction grading — sudoku answers
+are verified against the rules and givens, word search answers against the
+grid — for benchmarking models and agents without an LLM judge.
+
+## Skill layout
+
+```
+skills/
+  puzzletide-word-search/SKILL.md
+  puzzletide-crossword/SKILL.md
+  puzzletide-sudoku/SKILL.md
+  puzzletide-printable-puzzles/SKILL.md
+  puzzletide-agent-evals/SKILL.md
+```
+
+The frontmatter carries `openclaw` and `hermes` metadata (tags, required
+binaries, install hints) alongside the standard name/description fields.