Whisker & Wrench

Tools, plans and software to help animal shelters and animal control. Website: whiskerandwrench.com.

Current Capabilities

• Website (site/): home page, build plans index, 404 page. Plain HTML and CSS, no framework, dark mode, works on phones.
• Plan 001: PVC Shelter Cot (plans/001-shelter-cot/): an interactive, LEGO-style build guide for a raised dog cot made only from big-box plumbing parts. Served at /plans/001-shelter-cot/. Draft, not yet build-tested.
• Automated checks: every push builds the site, validates the HTML, checks internal and external links, and runs the engineering constitution's checks.
• Auto-deploy: pushes to main deploy to Cloudflare Pages once the checks pass.
• Software: research only so far (see docs/).
• Demo: demo.html is a one-file tour you can open from a clone; it's also live at whiskerandwrench.com/demo.html.

flowchart LR
    plans["plans/*/guide.html"] --> build["scripts/build-site.sh"]
    site["site/"] --> build
    build --> dist["dist/"] --> checks["HTML + link checks"] --> cf["Cloudflare Pages"]

Quick Start

Supported platforms: Windows, macOS, Linux.

You need Git, Node.js 22+, Python 3, and Bash (Git Bash on Windows).

git clone --recurse-submodules https://github.com/esanacore/whisker-and-wrench.git
cd whisker-and-wrench
npm ci
npx playwright install chromium

The last line downloads the browser the tests use (once per machine).

Run

Build the site into dist/, then serve it at http://localhost:8788.

bash scripts/build-site.sh
python -m http.server 8788 --directory dist

bash scripts/build-site.sh
python3 -m http.server 8788 --directory dist

You can also open plans/001-shelter-cot/guide.html straight in a browser. Use the arrow keys or swipe to step through.

Test

Same command on every platform (use Git Bash on Windows):

bash scripts/test-site.sh

It builds dist/, validates every page with html-validate, checks every internal link and anchor, runs the link checker's own tests, then opens the site in headless Chromium (Playwright) to click through the Plan 001 steps, check every page fits a 375px phone screen, and run axe accessibility checks. CI also checks external links with lychee. See docs/TEST_PLAN.md.

Deploy

Push to main. GitHub Actions runs the checks and deploys with wrangler. One-time Cloudflare setup, rollback and DNS notes are in docs/OPERATIONS.md.

Project Structure

README.md                     This file
CLAUDE.md                     Context for Claude Code sessions
ROADMAP.md                    Plan series and software roadmap
TODO.md / CHANGELOG.md        Living task list and release notes
site/                         Website source (home, plans index, CSS, headers)
demo.html                     Self-contained demo page (served at /demo.html)
plans/
  LICENSE                     CC BY-NC 4.0 for all build plans
  001-shelter-cot/            Plan 001: guide.html, guide.css, guide.js + README spec
scripts/
  build-site.sh               Assemble dist/ from site/ and plans/
  test-site.sh                Full test suite
  check_links.py              Internal link checker
  serve-dist.mjs              Local server for dist/ (browser tests)
tests/browser/                Playwright stepper, mobile and axe tests
docs/
  business-model.md           Pricing, funding, nonprofit vs LLC notes
  research/                   Market research (furniture + software)
  product/app-vision.md       Admin + adopter app concept
  OPERATIONS.md               Deploy, rollback, Cloudflare setup
  ARCHITECTURE.md, TEST_PLAN.md, ...  Constitution docs
constitution/                 Engineering constitution (git submodule)
.github/workflows/            CI and deploy

Documentation

• ROADMAP.md: what's next for plans and software.
• docs/OPERATIONS.md: deploys, rollback, Cloudflare and DNS.
• docs/ARCHITECTURE.md: how the site is put together.
• docs/TEST_PLAN.md: what's tested and known gaps.
• docs/research/, docs/product/, docs/business-model.md: background.

Picking this up in Claude Code

cd C:\Projects\whisker-and-wrench
claude

Claude Code reads CLAUDE.md automatically for context.

Contributing

Built a plan? Found a mistake? Open an issue. See .github/CONTRIBUTING.md.

License

• Code (site scripts, CI, tooling): MIT.
• Build plans and guides (everything in plans/, and the plan pages on the site): CC BY-NC 4.0. Build them, share them, adapt them for your shelter, just credit Whisker & Wrench and don't sell them.