# WORKBENCH You are an AI assistant. A person gave you this file, or pasted a link to it and nothing else. It is written for you, not for them. They do not need to tell you anything about themselves or how to behave; this file does that. Start by acting, not by asking what they want you to do with it. Assume the person has never opened a terminal, does not know what a file path is, and will do exactly what you say and nothing more. Your job is to take them from nothing to a working page built from their own data, at a private web address if they want one, and to leave them able to repeat it without you. One step per message. What they end up with: a folder on their computer that an AI coding tool (Claude Code) works inside. The folder carries the working rules, guardrails, a design system, three page templates, a data converter, a deploy recipe, and optional add-ons. After setup they open the folder, type one sentence like "build me a dashboard from this spreadsheet", and get a finished page. This file is the setup and the first lesson. ## How to behave, the whole time - **One step per message.** When the person has to do something, the message ends with exactly that one thing and the line: "Do that, then tell me what you see." When you did the work yourself (PART B), end with what happened in one or two sentences, and a question only if there is one. - **One command per message when the person types it,** in its own code block, with the words "copy this, paste it, press Enter". Never two commands for them in one message. Commands you run yourself in PART B are not subject to this. - **Say where to click.** "Press the Windows key, type PowerShell, press Enter." Not "open a terminal". - **Define jargon the first time in five words or fewer.** Terminal: "a window you type commands into". Folder: "a place on your computer that holds files". Deploy: "put it on the internet". - **When they paste an error, you read it and fix it.** Give the next single step. Never ask them what they think it means. - **Never skip a step because it looks obvious.** Never combine steps because the person seems capable. - **If they say they already have something, verify it with one command** instead of believing them. - **Never ask "would you like me to".** Do the next step. Ask a question only when the answer changes what you do next. - **Never say "should work".** Run the check, read the output, then say it works. - **Plain words. No hype, no cheerleading, no em-dashes.** "Done. Next:" is a fine transition. - **If they get stuck twice on the same step, stop and give the simplest possible alternative,** even if it is slower. - **Red text is not always an error.** When a command prints a warning that does not matter, say "that red line is fine" before the next step. - **During setup, this file's message rules win.** The kit's `CLAUDE.md` asks for a file path or a summary at the end of replies; while you are walking someone through this file, the last line is the one thing for them to do. Switch to the `CLAUDE.md` reply rules once setup is finished. - **Claude Code asks before it runs each command.** The person sees "Do you want to proceed?" and you do not. Tell them once, at the start of PART B and again in A7: "When you see 'Do you want to proceed?', press Enter for Yes. If it offers 'Yes, and don't ask again', pick that." - **The chart library loads from the internet.** If B4 shows the page without its chart, the computer is offline; everything else works offline. ## Step 0: work out where you are running - You are a chat assistant with no access to the person's computer (claude.ai in a browser, the Claude phone app, or another chat product). You cannot run commands or create files on their machine. **Run PART A.** - You have a terminal and a file system on the person's computer (Claude Code, or a similar coding agent). **Run PART B.** - Not sure? Ask: "Are you typing to me in a web browser, or in a black terminal window on your computer?" Browser means PART A. Terminal means PART B. ## The intake questions Ten questions. Ask one per message, wait for each answer, never guess one. Questions 1 to 4 are asked in PART A (or at the start of PART B if PART A never happened). Questions 5 to 10 are asked in PART B at the point where the answer is needed, so the person is not interviewed before they see anything. If the person answers several at once, accept them and skip the ones covered. Unclear answer: ask that one again in simpler words. 1. **Computer.** "Are you on a Windows computer or a Mac?" If they say Linux: use the Mac commands, swap Homebrew for their package manager, and expect them to know their terminal. 2. **Comfort.** "Have you ever typed a command into a terminal, the black window? Yes or no." No means define every term and never combine steps. Yes means you may skip the definitions, but still one step per message. 3. **Claude plan.** "Do you pay for Claude: Pro, Max, Team, or Enterprise? Yes, no, or not sure." Not sure: "In claude.ai, open Settings, then Billing, and read the plan name." No: Claude Code needs a paid plan; send them to https://claude.ai/upgrade and wait until they say it is done. 4. **Already installed.** "Have you used Claude Code before, the version that runs in a terminal? Yes or no." Yes still gets verified with one command; never trust it. 5. **First build.** "What do you want to make first: a dashboard (numbers and charts from a spreadsheet), a one-page report you can print or send as a PDF, or a web page for people to land on?" 6. **Data.** "Do you have the data for it already? If yes, what is it: an Excel file, a CSV, a Google Sheet, or something else? If no, say no and we will use sample data." 7. **Online.** "When it is built, do you want it at a private web address you can send to people? It is free but takes a Cloudflare account. Yes or no." 8. **Domain.** Only if 7 was yes: "Do you already own a web address, like yourname.com? Yes or no." 9. **Colour.** "Name one colour you want as the main accent." 10. **Systems.** "Do you work with any of these: Vivenu (ticketing), HubSpot (CRM), Excel files, sending email, pages that need to remember things or run on a schedule, or jobs that should run while your computer is off? Name any that apply, or say none." In PART B, write every answer as you get it into `.claude/intake.txt` in the kit folder, one `key=value` per line (keys: computer, terminal-before, plan, claude-code-before, first-build, data, online, own-domain, colour, systems). Any restart reads that file instead of asking again. --- ## PART A: you are in a web chat. Get them into Claude Code. Your only goal in PART A is to get Claude Code installed, running inside a new folder, and reading this file. Nothing else. Do not try to build anything from a web chat. **A1. Tell them the plan.** Three sentences: what they will have at the end (a folder that builds and publishes pages from their data), that it takes about twenty minutes plus installs, and that you will go one step at a time. Then ask intake questions 1 to 4, one per message. **A2. Plan check.** If question 3 was no, do not continue until they confirm the upgrade is done. **A3. Windows only: install Git for Windows.** Skip on Mac. Claude Code needs it for its command tool and for the kit's guardrails; without it nothing below works the same way. "Press the Windows key, type PowerShell, press Enter. A window opens. Copy this, paste it into that window, press Enter." ``` winget install --id Git.Git -e --accept-source-agreements --accept-package-agreements ``` If `winget` is not recognized, send them to https://git-scm.com/download/win, tell them to run the installer and click Next on every screen. When it finishes: "Close that window completely." **A4. Install Claude Code.** Skip to A5 if question 4 was yes. Otherwise, matching question 1: Windows. "Press the Windows key, type PowerShell, press Enter. Copy this, paste it, press Enter." ``` irm https://claude.ai/install.ps1 | iex ``` Mac. "Press Command and Space together, type Terminal, press Enter. A window opens. Copy this, paste it, press Enter." ``` curl -fsSL https://claude.ai/install.sh | bash ``` On a Mac that has never run developer tools, a popup may offer to install "command line developer tools". Tell them: that popup is expected, click Install, wait for it to finish, then run the command again. When it finishes: "Close that window completely, then open it again the same way." Alternative if the install fails twice: the Claude desktop app from https://claude.ai/download has Claude Code built in (the Code tab at the top). Install it, open the Code tab, use its folder picker to create and open a folder named Workbench inside their home folder, then continue at A8. **A5. Verify the install.** In the fresh window: ``` claude --version ``` A version number means it worked. "Not recognized" or "command not found" means the window was not reopened, or the install failed; reopen first, then reinstall. **A6. Make the folder.** One command, matching the computer: Windows: ``` New-Item -ItemType Directory -Force "$HOME\Workbench" | Out-Null; cd "$HOME\Workbench" ``` Mac: ``` mkdir -p ~/Workbench && cd ~/Workbench ``` Tell them: "This made a folder called Workbench in your home folder and moved you into it." Then show them the line they will type every time they come back, on its own: Windows `cd "$HOME\Workbench"`, Mac `cd ~/Workbench`. Call it "the cd line" from here on. **A7. Start Claude Code.** ``` claude ``` Tell them what the first run looks like, in order, so nothing surprises them: a colour theme picker (press Enter), a login choice (choose the Claude account option, press Enter), a browser tab asking them to log in to Claude (approve it; if the terminal then asks for a code, copy the code the browser shows and paste it), a security notice (press Enter), and a question about trusting the folder (press Enter for yes). Then they see a prompt where they can type. Tell them one more thing now: "From here on, Claude Code will ask 'Do you want to proceed?' before it runs each command. Press Enter for Yes each time. If it offers 'Yes, and don't ask again', pick that." **A8. Hand over.** Fill in the intake answers, then tell them to copy the block below, paste it into Claude Code, and press Enter. This is the whole handoff. ``` Download https://workbench.seantippen.com/WORKBENCH.md into this folder with curl, then read the saved file and follow it from PART B. Intake: computer=; terminal-before=; plan=yes; claude-code-before= ``` Say "download with curl, then read the file" exactly like that. A fetch tool that summarises web pages loses the commands; the file has to be on disk and read whole. If Claude Code cannot download it: tell the person to open https://workbench.seantippen.com/WORKBENCH.md in their browser, press Ctrl+S (Mac: Command+S), save it into the Workbench folder, and paste "Read WORKBENCH.md in this folder and follow it from PART B" plus the same Intake line. **A9. Close out.** Tell them this chat's part is done, that everything from here happens in the Claude Code window, and that they can come back here and paste any error if they get stuck. Stop. --- ## PART B: you have a terminal. Set the kit up, then teach them to use it. You are running on the person's computer. You can run commands and write files. Do the work yourself; ask the person only for things you cannot know (their data, their password). Show them what happened after each step in one or two plain sentences. **Resuming.** If `CLAUDE.md` already exists in this folder, the kit is installed and a previous session got partway. Read `.claude/intake.txt` and `.claude/progress.txt` (the last completed step). If progress.txt is missing, B1 is done. If intake.txt has no `python=` line, do B2 next. Otherwise continue from the step after the one in progress.txt. Never redo B1. When the person types `continue` after a restart, this rule is what you follow. **Intake.** Read the Intake line in the message that pointed you here. If there is none: you are already running inside Claude Code, so questions 3 and 4 are answered (write `plan=yes` and `claude-code-before=yes`), question 1 comes from `uname -s` (`MINGW` or `MSYS` means Windows, `Darwin` means Mac, `Linux` means Linux), and only question 2 needs asking. Write the answers to `.claude/intake.txt` (create the folder if needed). After every completed step below, write the step name to `.claude/progress.txt`. Before the first command you run, tell them about the "Do you want to proceed?" prompt (see How to behave). **B0. Confirm the folder.** Run `pwd`. The folder should be named Workbench (or whatever they chose) and be empty apart from this file. If Claude Code was started somewhere else, do not try to fix it from inside: tell them to type `/exit`, then the `cd` line from A6, then `claude`, then paste the same handoff again. Claude Code binds its rules and guardrails to the folder it was started in. **B1. Get the kit.** It is hosted at `https://workbench.seantippen.com/`. Try these in order; stop at the first that works. 1. Download the zip and unpack it here. The unpack command differs by system (Git Bash on Windows cannot read a zip with `tar`, so it hands that part to PowerShell): Windows: ``` curl -fsSL -o workbench.zip https://workbench.seantippen.com/workbench.zip && powershell -NoProfile -Command "Expand-Archive -Force workbench.zip ." && rm workbench.zip ``` Mac or Linux: ``` curl -fsSL -o workbench.zip https://workbench.seantippen.com/workbench.zip && unzip -oq workbench.zip && rm workbench.zip ``` The zip has no wrapper folder; its contents land directly here. Confirm with `ls -a`; you should see `CLAUDE.md`, `.claude`, `design`, `templates`, `data`, `deploy`, `addons`. 2. If the zip fails: download `https://workbench.seantippen.com/files.json` with curl (never a page-fetch tool; those summarise). It lists every file path in the kit. Download each one from `https://workbench.seantippen.com/` with curl to the same relative path here. Fonts (`.woff2`) are binary; download them, never paste them. 3. If the site is unreachable from this tool: build the kit from the APPENDIX at the bottom of this file. Write every file exactly as shown, at the path shown. For the CSS, fonts, favicon, and design contract, download them with `curl -fsSL -o ` from `https://design.seantippen.com/` (paths in the appendix). If nothing can be fetched at all but the person's browser works, have them download those files by hand into `design/`. Then verify: confirm these exist (if any is missing, download it from `https://workbench.seantippen.com/` before going on): `CLAUDE.md`, `.claude/settings.json`, `.claude/hooks/run-hook.sh`, `.claude/skills/`, `design/tokens.css`, `design/components.css`, `templates/dashboard/index.html`, `data/csv_to_data.py`, `deploy/DEPLOY.md`, `deploy/stage.py`. Read `CLAUDE.md` now. Those are your working rules from here on. **B2. Python check.** The guardrails and the data converter need Python 3. Find the name it answers to on this machine by running, one at a time, `python3 --version`, `python --version`, `py -3 --version`. Windows note: a fresh Windows answers `python3` and `python` with a Microsoft Store message, not a version; that does not count. Mac note: if a popup offers to install command line developer tools, that is expected; click Install, wait, run the command again. If none answers with a version: - Windows: `winget install --id Python.Python.3.12 -e --accept-source-agreements --accept-package-agreements`. If winget is missing, send them to https://www.python.org/downloads/ and tell them to run the installer and tick "Add python.exe to PATH" on its first screen. - Mac: `brew install python` if `brew --version` answers, otherwise https://www.python.org/downloads/ and the big yellow button. After an install the new program is not visible until the window is reopened. Tell them: "Type `/exit` and press Enter. Close this window completely. Open it again the same way as before. Type the `cd` line, press Enter. Type `claude -c` and press Enter (the `-c` brings this conversation back). Then type `continue` and press Enter." Then re-run the version check. Write the working name into `.claude/intake.txt` as `python=` (for example `python=py -3`). Every command below that says `PY` means that name. The guardrails find the interpreter themselves through `.claude/hooks/run-hook.sh`, so nothing in `.claude/settings.json` needs editing. **B3. Reload so the guardrails apply.** Hooks and skills under `.claude/` load when a session starts in this folder. Write `B3` to `.claude/progress.txt` first. Then tell them: "Type `/exit` and press Enter. Type `claude -c` and press Enter. Then type `continue` and press Enter." When you come back, the Resuming rule at the top of PART B applies and you continue at B4. If they started a plain `claude` instead and you have no memory of this, the Resuming rule still finds the files. **B4. Show them it works.** Regenerate the sample data: ``` PY data/csv_to_data.py data/sample.csv templates/dashboard/data.js ``` Then open `templates/dashboard/index.html` in their browser (`start templates/dashboard/index.html` on Windows Git Bash, `open` on Mac, `xdg-open` on Linux). Tell them: "A dark page with four numbers at the top, a bar chart, and two tables opened in your browser. That is the template. Every number on it came from data/sample.csv." Ask if they see it. Fix it if they do not. **B5. Build their first page.** Ask intake question 5 (what to build) and question 6 (data). Then branch by template. Every new page lives in `pages//`, a folder at the same depth as the templates, so the stylesheet links keep working. Name it in plain words with spaces (`pages/Sales Dashboard/`). *Getting the data in, if they have any.* Open the kit folder for them (`explorer .` on Windows, `open .` on Mac) and tell them to drag the file into the `data` folder. Wait for "done", confirm with `ls data`. Google Sheet: tell them "In the sheet, click File, then Download, then Comma Separated Values, then drag that file into the data folder." Excel: read it with Python and openpyxl (`PY -m pip install --user openpyxl` if missing; if pip refuses on a Mac or Linux, the simpler route is "open it in Excel, File, Save As, choose CSV"), read the first sheet, write it as CSV in `data/`. Anything else: ask for a CSV or Excel export; if there is none, use the sample. Confirm the column names and row count back to them in one sentence. *Dashboard.* Copy `templates/dashboard` to `pages/`. Run the converter into that folder's `data.js`. At the top of the page script, edit the `COL` mapping so `month`, `group`, `value`, and `count` point at their real columns: `month` is any time or period column (labels sort by date only when they look like `YYYY-MM` or `YYYY-MM-DD`; anything else keeps the file's order), `group` is any category, `value` is the number that matters, `count` is a second number. If there is no time column, use the category for `month` and drop the "By month" section. If there is no count column, delete the Orders and Avg order stat cells and the matching table columns; the script tolerates missing elements, so nothing else needs editing. If the value is not money, set `FMT.moneyValue` to `false` and `FMT.valueName` to the word for it, just below `COL`. Edit the title, subtitle, the two rail links, stat labels, chart caption, and table headers to match. Everything above the line that reads `WIRING BELOW` is yours to edit; do not touch anything below it. *Report.* Copy `templates/report` to `pages/`. The report has no `data.js`; its figures are typed in. Compute every figure from the CSV with Python first (totals, best period, per-category table with shares), then type those exact values into the spine, the table, and the stats band. Rewrite the two paragraphs to say only what the data shows. Delete any stat you cannot compute from the file. Also edit the meta strip (the small line above the masthead), the masthead phrase, and the footer name; delete the "Full detail online" block unless there is a live address to put in it. *Site.* Copy `templates/site` to `pages/`. No data. Ask them, one question at a time, for: the name to show at the top, who the page is for, the one sentence that says what they offer, three things they do, an email address, and a city. Rewrite every piece of copy from those answers: the nav brand, the hero, the three work rows, and the contact row. Rewrite the "How it works" rows from what they told you or delete that section and the callout if nothing fits. No sentence from the template survives unless it is true for them. Then open the page and verify every headline number against the source file (the `verify-data` skill). Say "confirmed correct" or "error found" for each. Fix errors before showing it off. **B6. Make it theirs.** Ask intake question 9 (colour). Map it to a hue for `--accent-h` in `design/tokens.css` using the table in `design/THEME.md`: red 25, orange 55, yellow or gold 85, green 150, teal 185, cyan 195, blue or navy 240, pink 340. Purple: explain that hues 270 to 285 are fenced off in this system because they read as generic, and offer blue (240) or pink (340). Grey, black, or white: keep the accent at 195 and set `--contrast` to 0.9. Set `--secondary-h` about 150 degrees away from the accent. If `design/tokens.css` is not present because the page links the hosted CSS, add `` after the stylesheet links in the page instead; the hosted sheet reads the same knob. Tell them to refresh the page (F5) and confirm the accent changed: the section numbers, links, and highlights change; the chart bars keep their own series colours on purpose. Point at `design/THEME.md` as the explanation of those four numbers. **B7. Put it on the internet.** Ask intake question 7. If no, skip to B8. If yes, ask question 8, then follow `deploy/DEPLOY.md` exactly, one command per message: 1. Check Node.js: `node --version`. If missing: Windows `winget install --id OpenJS.NodeJS.LTS -e --accept-source-agreements --accept-package-agreements`, Mac `brew install node` if brew exists, otherwise https://nodejs.org (the LTS button). After an install: `/exit`, close the window completely, reopen it, the `cd` line, `claude -c`, then `continue`, then re-check. 2. Do not install wrangler globally. Use `npx wrangler@latest` for every wrangler command; the first run downloads it. Check with `npx wrangler@latest --version`. 3. Cloudflare account: send them to https://dash.cloudflare.com/sign-up, free plan. Tell them to click the verification link in the email Cloudflare sends; Pages refuses to create projects until the email is verified. Wait for "done". 4. `npx wrangler@latest login`. A browser tab opens; they click Allow. Run this command with a long timeout (ten minutes) because it waits for the click. 5. Pick a project name with them: lowercase, letters and hyphens, and it must be unique across all of Cloudflare, so include their name or business (`acme-sales`, not `sales`). Run `npx wrangler@latest pages project create --production-branch main --force`. The `--force` is needed: current wrangler otherwise tries to hand the command to a newer Pages product and fails with "Could not detect a directory containing static files". Pass `--force` on this create command only, never on the deploy. If it says the name is taken, add a word and retry. 6. Ask them for a password visitors will type: letters and digits only, no spaces or symbols, so it survives every shell and form. Generate a random 40-character string of letters and digits for the secret. Set both without an interactive prompt (the command hangs if you let it prompt): ``` printf '%s' '' | npx wrangler@latest pages secret put SITE_PASSWORD --project-name printf '%s' '' | npx wrangler@latest pages secret put SITE_SECRET --project-name ``` 7. Stage the page. Never deploy the kit folder itself; that would publish their data file and the kit internals. Run `PY deploy/stage.py "pages/"`. It writes `_deploy//` containing the page, a copy of `design/`, the password middleware, the no-index headers, and robots, with the stylesheet links rewritten. Then deploy from inside that folder with its absolute path: ``` (cd "_deploy/" && npx wrangler@latest pages deploy "$(pwd)" --project-name --branch main --commit-dirty=true) ``` `--branch main` is mandatory. The guardrail blocks the command without it. The parentheses keep you in the kit folder afterwards. 8. Verify. The password gate answers every host, including the preview address, with a login page, so a plain curl proves only that something is live. Log in with curl and grep for a string only their page contains: ``` curl -s -c jar.txt --data-urlencode 'password=' https://.pages.dev/ -o /dev/null && curl -s -b jar.txt https://.pages.dev/ | grep -c ""; rm -f jar.txt ``` A count of 1 or more is a pass. Then tell them to open `https://.pages.dev` in their browser, enter the password, and confirm they see their numbers. If they see an old version, say "press Ctrl+Shift+R" before anything else. 9. If question 8 was yes, offer the custom-domain steps from `deploy/DEPLOY.md`. Otherwise the `.pages.dev` address is theirs. Give them the full address on its own line. **B8. Add-ons, only if asked for.** Ask intake question 10 (systems). The kit ships optional layers under `addons/`, none loaded by default. For each system they named, and later whenever they ask for one by name, read `addons/INDEX.md` and install that add-on exactly as its `ADDON.md` says (copy its skill, register its hook if it has one, set its environment variables, run its Verify step, add the line to `CLAUDE.md`). Install only what was asked for. If the kit folder has no `addons/` directory, fetch the add-on's files from `https://workbench.seantippen.com/addons//` using `files.json` at the site root for the exact paths. **B9. Teach the loop and stop.** Write a file named `START-HERE.txt` in the kit folder with exactly this, filled in for their machine (quote the path): ``` To work on your pages: 1. Open PowerShell (Windows) or Terminal (Mac). 2. Type: cd "" and press Enter. 3. Type: claude and press Enter. 4. Say what you want, in plain words. Examples: build me a dashboard from data/whatever.csv make a one-page report from the same data change the accent colour to green deploy the Sales Dashboard check the numbers on the Sales Dashboard against the source file install the vivenu add-on (or hubspot, spreadsheets, email, cloudflare-workers, memory, vps-jobs) Claude reads CLAUDE.md in this folder every time, so it already knows the rules. ``` Read it back to them in the chat. Then say, in two sentences, that setup is finished and what they built. Stop. --- ## APPENDIX: every file in the kit Fallback for B1 step 3 only. Write each file at the path shown, byte for byte. Paths are relative to the kit folder. Download these binary or large files with curl instead of typing them: - `design/tokens.css` from `https://design.seantippen.com/tokens.css`, then replace every `https://design.seantippen.com/fonts/` inside it with `fonts/` - `design/components.css` from `https://design.seantippen.com/components.css` - `design/print.css` from `https://design.seantippen.com/print.css` - `design/favicon.svg` from `https://design.seantippen.com/favicon.svg` - `design/agents.md` from `https://design.seantippen.com/agents.md`; in its section 1 head snippet, change the two `href` values to `design/tokens.css` and `design/components.css` - `design/fonts/inter-latin-var.woff2`, `design/fonts/jetbrains-mono-latin-var.woff2`, `design/fonts/big-shoulders-display-latin-var.woff2` from `https://design.seantippen.com/fonts/` - `templates/dashboard/data.js` is generated: run `PY data/csv_to_data.py data/sample.csv templates/dashboard/data.js` after writing the converter and the sample. - `addons/` is not inlined here; only `addons/INDEX.md` is. Fetch an add-on's files from `https://workbench.seantippen.com/addons//` when one is requested; `files.json` lists every path. ### `CLAUDE.md` ```markdown # Workbench rules These rules apply to every page, report, dashboard, and tool built in this folder. They are the working method, not a style. The look is set in `design/THEME.md`. ## How to work - Do the work. When a tool can check something, check it instead of asking. Make a reasonable assumption, state it in one line, finish the whole task, report once. - Finish means zero remaining items. If something is blocked, finish everything else and say exactly what is left and why. - Every reply that produced or changed a file ends with that file's full path, or the live URL if it was deployed. One path, not a list of everything touched. - No "done" without evidence from this session. Tests: run them and read the output. Deploys: curl the live URL and grep for the new content. Data: reconcile against the source file. Say "confirmed correct" or "error found", never "looks right". - Believe bug reports. Never open with "works on my end". Investigate first. - Edit files surgically. Rewrite a file only when the change is most of the file. - Keep changes to what the task asks for. Report other problems you notice as follow-ups at the end; do not fix them unasked. ## Building pages - One HTML file per page. CSS and JS inline. No build step, no framework, no bundler. - Data lives in `data.js` next to the page as `window.DATA = {...}`. The page reads it; it never inlines numbers by hand. `data/csv_to_data.py` turns a CSV into that file. The one exception is the print `report`: it is a fixed 8.5 by 11 inch sheet with no script, so its figures are computed from the source with Python and typed in, then verified. - External libraries load from a CDN with a pinned version and an integrity hash. Chart.js is pinned at 4.4.7. - Start from a template in `templates/`. Copy it to `pages//`, then edit content. Do not compose a page from scratch when a template covers the medium. - Pick the template by medium: `dashboard` for anything read in a browser that reports data, `report` for a one-page piece that gets printed or saved as a PDF, `site` for a public page people land on. - Every page gets a ``, a viewport meta, a `robots` noindex meta unless it is meant to be found, and a favicon. ## Design - Read `design/agents.md` before writing any CSS or page structure. It is the contract; the class registry in it is the component set. - Use `var(--token)` in CSS and `tok('--token')` in Chart.js. Never a hex, rgba, hsl, or oklch literal in page CSS. - One accent per layout. Status colours mean status. Nothing is coloured just to look coloured. - No gradient backgrounds, no gradient text, no decorative overlays, no blur on flat cards, no scale on hover, no literal `border-radius`. - Dense data goes in a table with border-bottom rows, never a stack of cards. A list of things is a row list. Boxes never nest inside boxes. - Navigation for a multi-section dashboard is the rail plus banded sections. A public site uses the top nav. Never tabs; tabs hide content behind clicks. - Every uppercase label uses the label token. On screen, `font-size` only takes a `--text-*` token and nothing is smaller than `--text-xs`. The print tier (`report`) sizes in points and is exempt. - Tables wrap in `.table-scroll`, charts in `.scroll-x`. The page body never scrolls sideways on a phone. - Numbers use tabular figures. Keep the data; fix noise by fixing structure. - Badges carry state you cannot otherwise see. A badge that restates the content is cut. ## Data - Verify completeness before reporting a count. Loop pagination until empty, check totals, confirm a grep was not truncated. - One value per table cell. Financial figures show how they were built. - No personal data in `data.js` without the owner saying so in writing. - Spreadsheets are read with Python and openpyxl, not by eye. ## Deploy - Target is Cloudflare Pages. Steps are in `deploy/DEPLOY.md`. The `/deploy` skill runs them. - If the folder is a git repo, `git status` before every deploy. Wrangler ships the working directory whether or not it is committed. - Always pass `--branch main` (or the project's production branch). Without it the custom domain serves stale content. - Verify live by logging in with curl (post the password, keep the cookie) and grep the page for a string that only the new version contains. A 401 from a gated project proves the gate is up, not that the content is right. - Cache is the first suspect after a deploy. Say "hard refresh" before debugging code. - End every deploy reply with the full live URL on its own line. - Gated by default. Stage with `deploy/stage.py`, which copies the gate in, and set the two secrets. Never deploy the kit folder itself; it holds data files. Every gated deploy is also no-index by design. Leave a page open (`--open`, which drops the no-index headers) only when the owner says so. - Pages live in `pages/<Name>/`, the same depth as the templates, so the `../../design/` links resolve. Never copy a template to the kit root. ## Writing - Plain, literal, direct. Lead with the answer. Short sentences. No hype, no fake warmth, no metaphor where a literal phrase exists. - No em-dashes anywhere: replies, page copy, commit messages. Commas, periods, semicolons, parentheses. - No label that marks a page as private or team-only in anything a reader outside the team could see. The write-quality hook holds the list and blocks them. - Long replies end with a two-sentence summary. Short replies do not get one. - Name a file, function, or flag in prose only when the reader has to go there. ## Folder hygiene - A project folder shows the deliverable and one `archive/` folder. Helper scripts, old versions, intermediate data, and logs move into `archive/` when the work is finished. - Move, never delete. - Scratch files never go in the home folder, Downloads, Desktop, or Documents. They go in the project tree or a scratch folder. ``` ### `.gitignore` ```text node_modules/ .wrangler/ .DS_Store *.log Thumbs.db _deploy/ .claude/intake.txt .claude/progress.txt .claude/recall-state/ __pycache__/ ``` ### `.claude/settings.json` ```json { "hooks": { "PreToolUse": [ { "matcher": "Write|Edit|MultiEdit", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" write-quality.py" } ] }, { "matcher": "Bash", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh\" deploy-branch.py" } ] } ], "PostToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/deploy-verify.sh\"" } ] } ] } } ``` ### `.claude/hooks/run-hook.sh` ```bash #!/bin/bash # Runs a Python hook with whichever Python 3 this machine has. # Usage (from .claude/settings.json): # bash "$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh" write-quality.py # # Tries python3, python, then the Windows launcher, and skips the # Microsoft Store stub that answers to "python3" on a fresh Windows. # The hook's own exit code is passed through (2 means block). # Fails open: if no interpreter is found, the call is allowed and one # line says so. HERE="$(cd "$(dirname "$0")" && pwd)" SCRIPT="$HERE/$1" INPUT="$(cat)" run_with() { printf '%s' "$INPUT" | "$@" "$SCRIPT" } while IFS= read -r exe; do [ -n "$exe" ] || continue case "$exe" in *WindowsApps*) continue ;; esac if "$exe" -c "import sys; sys.exit(0 if sys.version_info[0] == 3 else 1)" >/dev/null 2>&1; then run_with "$exe" exit $? fi done < <(type -aP python3 python 2>/dev/null) if command -v py >/dev/null 2>&1; then run_with py -3 exit $? fi echo "[run-hook] No Python 3 found; $1 skipped. Install Python (see B2) so the guardrails run." exit 0 ``` ### `.claude/hooks/write-quality.py` ```python """PreToolUse hook for Write, Edit, and MultiEdit. Blocks two things in prose files (.md, .html, .htm, .txt): 1. Em-dashes (U+2014). The house style uses commas, periods, semicolons, and parentheses instead. 2. Labels that mark a document as private or team-only, which should never reach a reader outside the team. The list is BANNED_PATTERNS below; the literals are split so this file never trips its own scan. Anything under a .claude/ folder is exempt, as is CLAUDE.md itself, because those files talk about the rules. Edit BANNED_PATTERNS to add your own phrases. Each entry is a regex and a label. """ import sys, json, re from pathlib import Path def block(reason): """Block the tool call in every Claude Code version: exit 2 with the reason on stderr is honoured everywhere; the JSON on stdout covers the documented PreToolUse forms.""" print(json.dumps({ "decision": "block", "reason": reason, "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": reason, }, })) sys.stderr.write(reason + "\n") sys.exit(2) try: # Read bytes and decode as UTF-8 ourselves: on Windows the text stream # can use the system code page, which turns an em-dash into three chars. data = json.loads(sys.stdin.buffer.read().decode("utf-8", "replace")) except Exception: sys.exit(0) tool_name = data.get("tool_name", "") tool_input = data.get("tool_input", {}) or {} checks = [] if tool_name == "Write": fp = tool_input.get("file_path", "") if fp: checks.append((fp, tool_input.get("content", "") or "")) elif tool_name == "Edit": fp = tool_input.get("file_path", "") if fp: checks.append((fp, tool_input.get("new_string", "") or "")) elif tool_name == "MultiEdit": fp = tool_input.get("file_path", "") for e in tool_input.get("edits", []) or []: if fp and e.get("new_string"): checks.append((fp, e["new_string"])) else: sys.exit(0) EXTS = {".md", ".html", ".htm", ".txt"} EXEMPT_NAMES = {"CLAUDE.md"} BANNED_PATTERNS = [ (r"\bconfid" r"ential\b", "confid" "ential"), (r"\binternal use" r" only\b", "internal use" " only"), (r"\bfor internal" r" use\b", "for internal" " use"), (r"\binternal" r" only\b", "internal" " only"), ] def is_exempt(fp_str): norm = fp_str.replace("\\", "/").lower() return "/.claude/" in norm or Path(fp_str).name in EXEMPT_NAMES problems = [] for fp, content in checks: if is_exempt(fp): continue p = Path(fp) if p.suffix.lower() not in EXTS: continue for pat, label in BANNED_PATTERNS: if re.search(pat, content, re.IGNORECASE): problems.append(f"{p.name}: banned phrase '{label}'") EMDASH = chr(0x2014) if EMDASH in content: n = content.count(EMDASH) problems.append(f"{p.name}: {n} em-dash(es). Use a comma, period, semicolon, or parentheses.") if problems: block("BLOCKED by write-quality hook:\n- " + "\n- ".join(problems)) sys.exit(0) ``` ### `.claude/hooks/deploy-branch.py` ```python """PreToolUse hook for Bash: block `wrangler pages deploy` without --branch. Without --branch, Cloudflare creates a preview deployment and the custom domain keeps serving the old production build. This is the single most common "I deployed but nothing changed" cause, so it is blocked at the tool boundary. Any branch value is accepted; most projects use main. """ import sys, json, re def block(reason): """Block the tool call in every Claude Code version: exit 2 with the reason on stderr is honoured everywhere; the JSON on stdout covers the documented PreToolUse forms.""" print(json.dumps({ "decision": "block", "reason": reason, "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": reason, }, })) sys.stderr.write(reason + "\n") sys.exit(2) try: # Read bytes and decode as UTF-8 ourselves: on Windows the text stream # can use the system code page, which turns an em-dash into three chars. data = json.loads(sys.stdin.buffer.read().decode("utf-8", "replace")) except Exception: sys.exit(0) cmd = data.get("tool_input", {}).get("command", "") or "" segments = re.split(r"&&|\|\||;|\|(?!\|)", cmd) deploy_segment = None for seg in segments: s = seg.strip() while re.match(r"^\w+=\S+\s+", s): s = re.sub(r"^\w+=\S+\s+", "", s) if re.match(r"^(npx\s+)?wrangler(@\S+)?\s+pages\s+deploy\b", s): deploy_segment = s break if deploy_segment is None: sys.exit(0) if not re.search(r"--branch(\s+|=)\S+", deploy_segment): block( "BLOCKED: wrangler pages deploy must include --branch <branch>. " "Without it Cloudflare makes a preview deploy and the custom domain " "serves stale content. Add --branch main." ) sys.exit(0) ``` ### `.claude/hooks/deploy-verify.sh` ```bash #!/bin/bash # PostToolUse hook for Bash: after `wrangler pages deploy`, curl the # project's pages.dev host and report whether it answered. # # A password-gated project answers 401 with its login page on every host, # which still proves the deploy is live. Content is verified separately by # logging in with curl (see deploy/DEPLOY.md). # # Runs on every Bash call, so it exits before doing anything unless the # command was a deploy. Needs no Python. INPUT=$(cat) case "$INPUT" in *"wrangler pages deploy"*|*"wrangler@"*" pages deploy"*) ;; *) exit 0 ;; esac # Pull the command string out of the JSON without an interpreter: the # --project-name value is the only thing we need. PROJECT=$(printf '%s' "$INPUT" | sed -n 's/.*--project-name[ =]\{0,1\}\([A-Za-z0-9._-]*\).*/\1/p' | head -1) say() { printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s"}}\n' "$1" } if [ -z "$PROJECT" ]; then say "[deploy-verify] Could not read --project-name from the deploy command. Verify manually." exit 0 fi URL="https://${PROJECT}.pages.dev" sleep 5 STATUS=$(curl -s -o /dev/null --max-time 15 -w "%{http_code}" "$URL" 2>/dev/null) case "$STATUS" in 200|304) say "[deploy-verify] $URL returned HTTP $STATUS. Live. Now grep it for a string only the new version contains." ;; 401) say "[deploy-verify] $URL returned HTTP 401: the password gate is up and the deploy is live. Log in with curl (see deploy/DEPLOY.md) and grep for the new content." ;; 000|"") say "[deploy-verify] WARNING: $URL did not respond. Verify manually." ;; *) say "[deploy-verify] WARNING: $URL returned HTTP $STATUS. Wait and retry, then verify manually." ;; esac exit 0 ``` ### `.claude/skills/design/SKILL.md` ```markdown --- name: design description: Use before writing or editing any CSS, HTML structure, layout, colour, typography, or spacing. Loads the design contract and picks the right template for the medium. user_invocable: true --- # Design Before you touch a line of CSS or page structure: 1. **Pick the medium.** Ask one question: what is the output and who reads it? - Read in a browser, reports data: `templates/dashboard/`. Dark canvas, rail nav, banded sections, stat band, tables, charts. - Printed or saved as a one-page PDF: `templates/report/`. Ink on white, one masthead, one solid accent band. - A public page people land on: `templates/site/`. Top nav, hero, plain sections. 2. **Read `design/agents.md` in full.** Not the summary. It holds the hard rules, the token names, the page shell, the class registry, and the Chart.js wiring. The class registry is the component set; use those classes before inventing anything. 3. **Copy the template, then edit content.** Do not hand-compose a page from parts. A template already has the shell, the nav wiring, the chart defaults, and the theme toggle. 4. **Check the look is set in `design/THEME.md`, not in page CSS.** Page CSS holds layout only. Colour, type, spacing, and radius come from tokens. ## While building - `var(--token)` in CSS, `tok('--token')` in Chart.js. Never a colour literal in page CSS. - One accent per layout. Status colours mean status. - Dense data is a table with border-bottom rows. Not cards. A list is a row list. No box inside a box. - Multi-section pages use the rail plus banded sections. No tabs. - `font-size` only takes a `--text-*` token. Every uppercase label is `--text-label`. - Tables in `.table-scroll`, charts in `.scroll-x` with a height-bearing parent. - No gradient backgrounds, no gradient text, no blur on flat cards, no `transform: scale()` on hover, no literal `border-radius`. ## Before shipping Run the checklist at the end of `design/agents.md`. Then grep the finished page for locally redefined component class names (`.badge`, `.card`, `.tabs`, `.kpi`, `.data-table`, `.toolbar`, `.nav`); a redefinition is the tell that a component was reinvented instead of used. ``` ### `.claude/skills/build/SKILL.md` ```markdown --- name: build description: Build a dashboard, one-page report, or landing page from a data file or a brief. Use when asked to "build me a dashboard from X", "make a report of Y", or "put up a page for Z". user_invocable: true --- # Build Turns a data file (CSV, XLSX, Google Sheet export) or a written brief into a finished page under `pages/<Name>/`. ## Steps 1. **Read the source first.** Open the data file and confirm you can parse it. Note the columns, the row count, the date range, and any totals you can compute. XLSX: read with openpyxl and write a CSV into `data/` first (the `spreadsheets` add-on has the careful version). If the read fails, stop and say so. 2. **Pick the medium and the template** (the `design` skill has the routing). Copy the template folder to `pages/<Name>/`, a folder at the same depth as the templates so the `../../design/` links resolve. Name it in plain words with spaces (`pages/Sales Summary/`). 3. **Dashboard:** run `PY data/csv_to_data.py <source.csv> "pages/<Name>/data.js"` (`PY` is the Python name in `.claude/intake.txt`; if that line is missing, find it: try `python3 --version`, `python --version`, `py -3 --version`, and record the first that answers). Edit the `COL` mapping at the top of the page script so `month`, `group`, `value`, and `count` name the real columns. No time column: use the category for `month` and remove the "By month" section. No count column: remove the Orders and Avg order stats and columns. Value not money: set `FMT.moneyValue` to `false` and `FMT.valueName` to the word for it (`units`, `visits`). Then edit the title, subtitle, the two rail links, stat labels, chart caption, and table headers. Everything above the `WIRING BELOW` line is editable; nothing below it is. Never type a number into the HTML. 4. **Report:** there is no `data.js`. Compute every figure from the source with Python, then type those exact values into the spine, the table, and the stats band. Rewrite the two paragraphs to say only what the data shows. Delete any stat you cannot compute. 5. **Site:** no data. Fill the copy from the brief. Nothing structural changes. 6. **Render it and look.** If Chrome or Edge is installed, open the page headlessly and take one screenshot at 1440 wide (Windows: `"C:/Program Files/Google/Chrome/Application/chrome.exe"` or `"C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"`, Mac: `"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"`, flags `--headless=new --disable-gpu --screenshot=<png> --window-size=1440,1400 <file url>`). If neither exists, open the page in the person's browser and ask what they see. Check: the numbers match the source, the chart has data, the table scrolls inside its box, the table header does not overprint the first row. Headless Chrome will not go narrower than about 500px, so check the phone layout by DOM probe instead: at `--window-size=500,1200` run a script that compares `document.documentElement.scrollWidth` to `document.documentElement.clientWidth`; equal means no sideways scroll. The print report is a fixed-width sheet and is exempt. 7. **Verify the numbers.** Run the `verify-data` skill against the source. Report "confirmed correct" or "error found" per figure. 8. **Report.** One line on what was built, the verification result, and the full path to the page. If asked to deploy, run the `deploy` skill and end with the live URL. ## Rules that get broken most - A page is one HTML file plus `data.js`. Nothing else. - Chart.js 4.4.7 from the CDN with the integrity hash in the template. Do not change the version. - No new CSS classes for things the registry already has. Extend the nearest registry class if something is missing, and say so. - No em-dashes in page copy. Plain, literal labels. "Revenue by month", not "Your revenue journey". ``` ### `.claude/skills/deploy/SKILL.md` ````markdown --- name: deploy description: Deploy a page folder to Cloudflare Pages behind the password gate, verify it is live, and report the URL. Use when asked to deploy, publish, or put a page online. user_invocable: true --- # Deploy Ships one page from `pages/<Name>/` to Cloudflare Pages and proves it is live. Full setup notes are in `deploy/DEPLOY.md`. Use `npx wrangler@latest` for every wrangler command; nothing is installed globally. ## Steps 1. **Confirm the page.** It lives in `pages/<Name>/` and has an `index.html`. If the folder is a git repo, run `git status` so you know what state is shipping. 2. **First deploy of a new project only.** ``` npx wrangler@latest pages project create <project-name> --production-branch main --force printf '%s' '<password>' | npx wrangler@latest pages secret put SITE_PASSWORD --project-name <project-name> printf '%s' '<random 40 chars>' | npx wrangler@latest pages secret put SITE_SECRET --project-name <project-name> ``` `--force` is required on create with current wrangler (it otherwise delegates to a newer product and fails); never pass it on a deploy. Project names are global across Cloudflare; if the name is taken, add a word. Pipe the secret values in; the command hangs if it prompts. Secrets take effect on the next deploy. 3. **Stage.** Never deploy the kit folder or the page folder directly. ``` PY deploy/stage.py "pages/<Name>" ``` (`PY` is the Python name recorded in `.claude/intake.txt`; if missing, try `python3`, `python`, `py -3` and use the first that answers.) This writes `_deploy/<Name>/` with the page, a copy of `design/`, the gate, the no-index headers, and robots, and rewrites the stylesheet links. Add `--open` only when the owner has said the page is public; that also drops the no-index headers so the page can be found. 4. **Deploy from inside the staged folder** so the gate compiles: ``` (cd "_deploy/<Name>" && npx wrangler@latest pages deploy "$(pwd)" --project-name <project-name> --branch main --commit-dirty=true) ``` `--branch main` is mandatory; the hook blocks the command without it. The parentheses keep you in the kit root. 5. **Verify.** The hook reports whether the host answered; a 401 is the gate working. Then prove the content: log in with curl and grep for a string only the new version contains. ``` curl -s -c jar.txt --data-urlencode 'password=<password>' https://<project-name>.pages.dev/ -o /dev/null && curl -s -b jar.txt https://<project-name>.pages.dev/ | grep -c "<unique new string>"; rm -f jar.txt ``` A count of 1 or more passes. If the old content serves, wait ten seconds and retry once, then check `npx wrangler@latest pages deployment list --project-name <project-name>` for a deploy marked Preview instead of Production, which means a missed `--branch`. 6. **Custom domain (optional, first time only).** Steps in `deploy/DEPLOY.md`. 7. **Report.** One line on what shipped, the verification evidence (status code plus the string match), and the full live URL on its own line. Never say "deployed" if verification failed. ```` ### `.claude/skills/verify-data/SKILL.md` ```markdown --- name: verify-data description: Check every number on a page against its source file and report pass or fail per figure, with definitive language. user_invocable: true --- # Verify data Read-only. Cross-checks a page's numbers against the file they came from. ## Steps 1. **Read the source file.** Confirm it parses. If not, stop and say so. 2. **Read the target.** The page's `data.js`, or the rendered HTML for the print report, whose figures are typed in by design. On a dashboard, an inlined number is itself an error to report. 3. **Cross-reference every figure.** Totals, counts, averages, breakdowns, derived metrics, date ranges, and row counts. 4. **Report per figure** with one of three labels: - CONFIRMED CORRECT: source says X, page says X. - ERROR: expected X, found Y, with the source row or cell. - CANNOT VERIFY: the source does not contain it, and why. 5. **No hedging.** Never "plausible", "seems right", "looks correct". It matches or it does not. 6. **Do not edit anything** unless asked to fix the errors. 7. **Close with the count.** "X of Y figures confirmed correct. Z errors found." ``` ### `.claude/skills/verify-before-done/SKILL.md` ```markdown --- name: verify-before-done description: Use before claiming anything is complete, fixed, deployed, or passing. Run the command that proves it and read the output first. --- # Verify before done No success claim without fresh evidence from this session. - **Every "done" needs a command that proved it.** Tests: run them, read the output. Deploys: curl the live host and grep for the new content. Data: reconcile against the source before reporting a count. - **Definitive language only.** "Confirmed correct" or "error found". Never "should work", "seems right", or "plausible". - **Report failures verbatim.** If a test fails, say so and paste the output. If a step was skipped, say that. Never round a partial result up to complete. - **Completeness is correctness.** Loop pagination until empty, check totals, confirm a grep was not cut off by a head limit. - **Check your own output.** After writing a file, confirm it landed where claimed and grep it for what you expect to be in it. After a visual change, render it and look at it. - **If context is running low,** write a handoff note in the project folder instead of claiming completion with caveats. ``` ### `design/THEME.md` ````markdown # Theme The look is not in the rules. It is four numbers at the top of `tokens.css`. Change them and every page in the repo re-skins, because every colour in the system derives from them. ```css :root { --accent-h: 195; /* the one accent hue. 0 to 360 */ --secondary-h: 320; /* second-series and state hue only */ --base-h: 252; /* the neutral hue behind every surface and text step */ --contrast: 1; /* 0.85 calm ... 1.2 high contrast */ } ``` ## Picking values - `--accent-h` is the colour people will remember. Reds sit around 20 to 30, oranges 40 to 70, yellows and golds 80 to 95, greens 140 to 160, teals 170 to 200, cyan 195, blues and navy 230 to 250, pinks 330 to 350. Keep it away from 270 to 285 (blurple), which reads as generic; for purple, use blue or pink instead. - `--secondary-h` should sit far from the accent, roughly 120 degrees or more, so a two-series chart stays legible. It is never a page theme. - `--base-h` tints the greys. Match it to the accent for a warm or cool feel, or leave it neutral. - `--contrast` above 1 sharpens text against the canvas; below 1 softens it. Stay inside 0.85 to 1.2. Light mode is built in. Add `class="light"` on `<html>` or set `data-theme="light"`; every token re-derives. The dashboard template ships a toggle that persists the choice. ## Fonts Three faces, self-hosted in `fonts/`, loaded by `tokens.css`. No font service link is needed and none should be added. | Role | Face | Used for | |---|---|---| | `--font-display` | Big Shoulders Display | the one hero heading per page | | `--font-sans` | Inter | every other heading, body, UI | | `--font-mono` | JetBrains Mono | numbers, code, uppercase labels | To swap a face: drop a variable `woff2` into `fonts/`, change the matching `@font-face` block and the `--font-*` token in `tokens.css`. Keep the three-role split. Display for one heading, sans for everything else, mono for numbers. That split is what makes dense pages read calmly. ## What not to change - Token names. Pages reference them; renaming one breaks every page. - `--radius`. It is 0 on purpose. Pills and dots use `--radius-full`. - The status hues (`--color-success`, `--color-warning`, `--color-danger`, `--color-info`). They mean what they mean on every page. - The chart series hexes (`--green`, `--blue`, and so on). Chart.js paints to a canvas and cannot read OKLCH, so those eight stay hex. ## Using the hosted copy instead If you would rather not vendor the CSS, the same files are served at `https://design.seantippen.com/tokens.css` and `/components.css` with long cache headers. Link those two instead of the local files. The four knobs still work: set them in a `<style>:root{--accent-h:150}</style>` block placed after the two links. ```` ### `data/csv_to_data.py` ```python """Turn a CSV into the data.js a template page reads. Usage: python3 data/csv_to_data.py data/sample.csv templates/dashboard/data.js Output shape (window.DATA): { "source": "sample.csv", "generated": "2026-09-19T18:04:00", "columns": ["month", "region", "revenue", "orders"], "rows": [ {"month": "2026-01", "region": "North", "revenue": 84210, "orders": 612}, ... ] } Numbers become numbers: 1200, 1,200.50, $1,200.50, -$45, $-45, and (1,234) as a negative. Everything else stays text, including three cases on purpose: percentages ("12%"), values with a leading zero ("00501", ids and ZIP codes), and comma-decimal values ("12,5"). The script prints which columns kept text so nothing is silently miscounted. No aggregation happens here; the page computes its own totals from rows so every number on screen can be traced back to the file. """ import csv import json import re import sys from collections import Counter from datetime import datetime from pathlib import Path CURRENCY = "$" + chr(0xA3) + chr(0x20AC) NUM = re.compile(r"^\(?[-+]?[" + re.escape(CURRENCY) + r"]?\s*[-+]?(\d{1,3}(,\d{3})+|\d+)?(\.\d+)?\)?$") LEADING_ZERO = re.compile(r"^0\d+$") TEXT_KEPT = Counter() def coerce(v, col=""): if v is None: return None s = v.strip() if s == "": return None if s.endswith("%") or LEADING_ZERO.match(s): TEXT_KEPT[col] += 1 return s if NUM.match(s) and any(ch.isdigit() for ch in s): neg = s.startswith("(") and s.endswith(")") n = s.strip("()").replace(",", "") for ch in CURRENCY: n = n.replace(ch, "") n = n.strip().lstrip("+") try: val = int(n) if re.fullmatch(r"-?\d+", n) else float(n) except ValueError: TEXT_KEPT[col] += 1 return s return -val if neg else val # Looks like it was meant to be a number (only digits, commas, dots) but did not parse: "12,5". if re.fullmatch(r"[\d.,]+", s.strip("()").replace(" ", "")): TEXT_KEPT[col] += 1 return s def main(src, dst): src, dst = Path(src), Path(dst) with src.open(newline="", encoding="utf-8-sig") as f: reader = csv.DictReader(f) columns = [c.strip() for c in reader.fieldnames or []] dupes = sorted({c for c in columns if columns.count(c) > 1}) if dupes: sys.exit(f"{src} has duplicate column names: {dupes}. Rename them first.") rows = [] for i, r in enumerate(reader, 2): if None in r: sys.exit(f"{src} row {i} has more fields than the header. Fix that row first.") rows.append({c.strip(): coerce(v, c.strip()) for c, v in r.items()}) if not rows: sys.exit(f"{src} has no data rows") payload = { "source": src.name, "generated": datetime.now().replace(microsecond=0).isoformat(), "columns": columns, "rows": rows, } dst.parent.mkdir(parents=True, exist_ok=True) dst.write_text("window.DATA = " + json.dumps(payload, indent=2) + ";\n", encoding="utf-8") print(f"wrote {dst} ({len(rows)} rows, {len(columns)} columns)") if TEXT_KEPT: kept = ", ".join(f"{c} ({n})" for c, n in TEXT_KEPT.most_common()) print(f"kept as text, not numbers: {kept}. Percentages, leading-zero codes, and comma decimals stay text on purpose.") if __name__ == "__main__": if len(sys.argv) != 3: sys.exit("usage: csv_to_data.py <source.csv> <target/data.js>") main(sys.argv[1], sys.argv[2]) ``` ### `data/sample.csv` ```csv month,region,revenue,orders 2026-01,North,59280,487 2026-01,South,51227,427 2026-01,East,40491,319 2026-01,West,27209,209 2026-02,North,53707,418 2026-02,South,44286,368 2026-02,East,37817,274 2026-02,West,26164,212 2026-03,North,68366,485 2026-03,South,55617,436 2026-03,East,47589,399 2026-03,West,34004,272 2026-04,North,67901,561 2026-04,South,57230,415 2026-04,East,45092,341 2026-04,West,35328,278 2026-05,North,79603,666 2026-05,South,60215,489 2026-05,East,53644,418 2026-05,West,36792,278 2026-06,North,87340,697 2026-06,South,75558,560 2026-06,East,55701,422 2026-06,West,42410,305 2026-07,North,97450,780 2026-07,South,83001,686 2026-07,East,61227,449 2026-07,West,42607,328 2026-08,North,84290,628 2026-08,South,77778,590 2026-08,East,63668,507 2026-08,West,45044,340 2026-09,North,85073,659 2026-09,South,72626,516 2026-09,East,55210,412 2026-09,West,37485,278 2026-10,North,78812,555 2026-10,South,66392,531 2026-10,East,49891,372 2026-10,West,34136,264 2026-11,North,67229,556 2026-11,South,54111,396 2026-11,East,44080,355 2026-11,West,33485,241 2026-12,North,77430,601 2026-12,South,68598,492 2026-12,East,57578,415 2026-12,West,38427,300 ``` ### `templates/dashboard/index.html` ```html <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="dark"> <meta name="darkreader-lock"> <meta name="theme-color" content="#0a0c12"> <meta name="robots" content="noindex, nofollow"> <meta name="description" content="Dashboard template. Copy the folder, replace data.js, edit the labels."> <title>Dashboard
WbDashboard
01

Sales summary.

Revenue and orders by region, . Source: , generated .

Revenue
all regions, full range
Orders
count
Avg order
revenue / orders
Best month
02

By month

Revenue per month, one bar per region, stacked.

03

By region

Totals per region across the full range. Share is the region's part of total revenue.

RegionRevenueOrdersAvg orderShare
04

Detail

Every row in the source file. Type to filter.

MonthRegionRevenueOrdersAvg order
``` ### `templates/report/index.html` ```html Monthly summary
Chrome print dialog: Margins Default, Scale 100, Background graphics ON, headers and footers OFF. One page.
Sales · 2026 2026-12-31 · No.01
Year in numbers

Revenue and orders across four regions for the twelve months of 2026. Figures come from the same file that drives the dashboard, so the two always agree.

Revenue
$2.72M
Orders
20,987
Best month
July

What moved. North carried a third of revenue, with South, East, and West behind it in that order. July was the strongest month and February the weakest.

How to read it. Every figure on this sheet is computed from the same CSV that drives the dashboard. Replace the paragraphs with what your own data shows, and delete any statistic you cannot compute from the file.

RegionRevenueShare
North$906,48133.3%
South$766,63928.2%
East$611,98822.5%
West$433,09115.9%
Avg order
$130
Top region
North
33.3% of revenue
Months
12
Full detail online.
example.com/sales
Every row, filterable, updated monthly.
QR
Scan to open
Your name report v1
``` ### `templates/site/index.html` ```html Site
What this is

Reports and tools built from your own data.

One sentence on who this is for and what they get. Keep it literal. The heading says what, this line says for whom.

See the work Get in touch
01

Work

Three things, each described in one line.

Dashboards
A single page that reads a data file and shows the numbers that matter, with a chart and a table.
One-page reports
A printed or PDF sheet with the headline figures and two paragraphs of what changed.
Small tools
A page that does one job: a calculator, a lookup, a form, a tracker.
02

How it works

Plain steps. No process diagram.

1. Send the data
A spreadsheet or an export. Nothing needs cleaning first.
2. Get a draft
A working page within a day, at a private link.
3. Adjust
Labels, order, what is on top. Then it is yours.
Note
Everything is a single file with no build step, so it keeps working without anyone maintaining it.
03

Contact

Emailyou@example.com
LocationCity, State
``` ### `deploy/DEPLOY.md` ````markdown # Deploy to Cloudflare Pages Every page in this kit is static files, so it hosts anywhere. Cloudflare Pages is the default because it is free, fast, has no build step, and the password gate in this folder runs on it. Nothing is installed globally: every wrangler command is `npx wrangler@latest ...`, which downloads it on first use. ## One-time setup 1. Node.js 18 or newer. Check `node --version`. Install from https://nodejs.org (the LTS button), or `winget install --id OpenJS.NodeJS.LTS -e --accept-source-agreements --accept-package-agreements` on Windows, `brew install node` on a Mac with Homebrew. Reopen the terminal after installing. 2. A Cloudflare account at https://dash.cloudflare.com/sign-up (free plan). Click the verification link in the email they send; Pages refuses to create projects until the address is verified. 3. Log in once: `npx wrangler@latest login`. A browser tab opens; click Allow. Give the command ten minutes; it waits for the click. ## Per project 1. Create the project once. Names are global across Cloudflare, so include your name or business: ``` npx wrangler@latest pages project create --production-branch main --force ``` `--force` is required on the create command with current wrangler, which otherwise tries to delegate to a newer Pages product and fails with "Could not detect a directory containing static files". Do not pass it on deploys. The name becomes the free address `https://.pages.dev`. If it is taken, add a word. 2. Set the two secrets. Pipe the values in; the command hangs if it prompts: ``` printf '%s' '' | npx wrangler@latest pages secret put SITE_PASSWORD --project-name printf '%s' '' | npx wrangler@latest pages secret put SITE_SECRET --project-name ``` `SITE_PASSWORD` is what visitors type; letters and digits only so it survives every shell and form. `SITE_SECRET` signs the login cookie; letters and digits, 40 of them. Optional: `SITE_DISPLAY_NAME` sets the heading on the login page (defaults to the first label of the host name). Secrets take effect on the next deploy. 3. Stage the page. Never deploy the kit folder or a page folder directly: the kit folder holds your data files and internals, and a page folder's stylesheet links point outside it. ``` python3 deploy/stage.py "pages/" ``` (Use the Python name that works on your machine.) This writes `_deploy//` with the page, a copy of `design/`, the gate in `functions/`, the no-index headers, and robots, with the links rewritten. Add `--open` for a page that should have no password; that also leaves out the no-index headers and robots file so search engines can find it. 4. Deploy from inside the staged folder, so Cloudflare compiles the gate: ``` (cd "_deploy/" && npx wrangler@latest pages deploy "$(pwd)" --project-name --branch main --commit-dirty=true) ``` `--branch main` is not optional. Without it Cloudflare makes a preview build and the real address keeps serving the old version. A correct deploy prints "Compiled Worker successfully" and "Uploading Functions bundle"; if those lines are missing, the gate did not ship. 5. Verify. The gate answers every host, including preview hashes, with a 401 login page, so a plain request only proves something is live. Log in with curl and grep for a string only your page contains: ``` curl -s -c jar.txt --data-urlencode 'password=' https://.pages.dev/ -o /dev/null && curl -s -b jar.txt https://.pages.dev/ | grep -c ""; rm -f jar.txt ``` A count of 1 or more passes. Then open the address in a browser, enter the password, and look. If you see an old version, hard refresh (Ctrl+Shift+R) before assuming anything else is wrong. ## Custom domain (optional) In the Cloudflare dashboard: Workers & Pages, pick the project, Custom domains, Set up a custom domain, type `.`. If the domain's DNS is on Cloudflare the record is created for you. Otherwise add a CNAME from `` to `.pages.dev` at your DNS host. Allow a few minutes for the certificate. ## What the gate does `functions/_middleware.js` runs on Cloudflare's edge before any file is served. No valid session cookie means the visitor gets the login page and nothing else. The password lives in a Cloudflare secret, never in the page, so view-source shows nothing. Sessions last 30 days. Every response also carries no-index and no-cache headers. ## Things that go wrong - **Deployed but nothing changed.** Missing `--branch main` on this or an earlier deploy. Run `npx wrangler@latest pages deployment list --project-name ` and look for "Preview" where "Production" should be. - **"Configuration error: secrets not set."** The two secrets were not set, or were set after the last deploy. Set them, deploy again. - **No login page, the site is just open.** The deploy ran from the wrong folder, so `functions/` shipped as plain files instead of compiling. Always `cd` into `_deploy/` first. - **The secret command hangs.** It is waiting for you to type the value. Pipe it in with `printf` as shown. - **Unstyled page online.** The page was deployed without `design/` beside it. Stage with `deploy/stage.py`; it copies the folder and rewrites the links. - **A file you removed still shows.** The edge keeps serving a removed path from cache. Deploy a harmless replacement file at that exact path once. ```` ### `deploy/stage.py` ```python """Stage one page folder for deploy. Usage: python3 deploy/stage.py "pages/Sales Dashboard" (gated, the default) python3 deploy/stage.py "pages/Sales Dashboard" --open (no password gate, and no no-index headers, so it can be found) Writes _deploy// next to the kit root containing: index.html and data.js (and anything else in the page folder) design/ the stylesheets, fonts, and favicon the page links functions/_middleware.js the password gate (unless --open) _headers, robots.txt no-index headers and rewrites every "../../design/" reference in the page's HTML to "design/". Deploy from INSIDE that folder so Cloudflare compiles the middleware: cd "_deploy/" && npx wrangler@latest pages deploy "$(pwd)" --project-name --branch main --commit-dirty=true Never deploy the kit folder itself. It holds your data files and the kit internals. """ import shutil import sys from pathlib import Path ROOT = Path(__file__).resolve().parent.parent DEPLOY_DIR = ROOT / "deploy" def main(argv): if not argv or argv[0].startswith("--"): sys.exit(__doc__) src = (ROOT / argv[0]).resolve() if not Path(argv[0]).is_absolute() else Path(argv[0]) gate = "--open" not in argv if not (src / "index.html").exists(): sys.exit(f"{src} has no index.html") out = ROOT / "_deploy" / src.name if out.exists(): shutil.rmtree(out) shutil.copytree(src, out, ignore=shutil.ignore_patterns("functions", "_deploy", "*.xlsx", "*.csv")) shutil.copytree(ROOT / "design", out / "design", ignore=shutil.ignore_patterns("agents.md", "THEME.md")) for html in out.rglob("*.html"): text = html.read_text(encoding="utf-8") html.write_text(text.replace("../../design/", "design/"), encoding="utf-8") if gate: shutil.copy2(DEPLOY_DIR / "_headers", out / "_headers") shutil.copy2(DEPLOY_DIR / "robots.txt", out / "robots.txt") else: (out / "_headers").write_text("/*\n X-Content-Type-Options: nosniff\n", encoding="utf-8") if gate: (out / "functions").mkdir() shutil.copy2(DEPLOY_DIR / "functions" / "_middleware.js", out / "functions" / "_middleware.js") files = sum(1 for p in out.rglob("*") if p.is_file()) print(f"staged {out} ({files} files, {'gated' if gate else 'open'})") print(f'next: cd "{out}" && npx wrangler@latest pages deploy "$(pwd)" --project-name --branch main --commit-dirty=true') if __name__ == "__main__": main(sys.argv[1:]) ``` ### `deploy/_headers` ```text /* X-Robots-Tag: noindex, nofollow, noarchive X-Content-Type-Options: nosniff ``` ### `deploy/robots.txt` ```text User-agent: * Disallow: / ``` ### `deploy/functions/_middleware.js` ```javascript /** * Cloudflare Pages Function: Server-Side Password Middleware * * This runs on Cloudflare's edge BEFORE any static asset is served. * The password is stored as a CF environment secret (SITE_PASSWORD), * never in client-side code. Visitors cannot view-source around this. * * Auth flow: * 1. Check for valid signed session cookie * 2. If missing/invalid → serve login page (from Worker, not static files) * 3. On POST → validate password against env secret * 4. On match → set HttpOnly signed cookie, redirect to content * 5. On fail → show error */ const COOKIE_NAME = '__site_auth'; const SESSION_TTL = 60 * 60 * 24 * 30; // 30 days // --- Timing-safe comparison --- async function timingSafeEqual(a, b) { const enc = new TextEncoder(); const keyA = await crypto.subtle.importKey('raw', enc.encode(a), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']); const keyB = await crypto.subtle.importKey('raw', enc.encode(b), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']); const sigA = new Uint8Array(await crypto.subtle.sign('HMAC', keyA, enc.encode('cmp'))); const sigB = new Uint8Array(await crypto.subtle.sign('HMAC', keyB, enc.encode('cmp'))); let diff = 0; for (let i = 0; i < sigA.length; i++) diff |= sigA[i] ^ sigB[i]; return diff === 0; } // --- Crypto helpers --- async function deriveKey(secret) { const enc = new TextEncoder(); const keyMaterial = await crypto.subtle.importKey( 'raw', enc.encode(secret), 'PBKDF2', false, ['deriveKey'] ); return crypto.subtle.deriveKey( { name: 'PBKDF2', salt: enc.encode('site-auth-salt'), iterations: 100000, hash: 'SHA-256' }, keyMaterial, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt'] ); } async function signToken(payload, secret) { const key = await deriveKey(secret); const enc = new TextEncoder(); const iv = crypto.getRandomValues(new Uint8Array(12)); const ciphertext = await crypto.subtle.encrypt( { name: 'AES-GCM', iv }, key, enc.encode(JSON.stringify(payload)) ); const data = { iv: btoa(String.fromCharCode(...iv)), ct: btoa(String.fromCharCode(...new Uint8Array(ciphertext))) }; return btoa(JSON.stringify(data)); } async function verifyToken(token, secret) { try { const key = await deriveKey(secret); const { iv, ct } = JSON.parse(atob(token)); const ivBytes = Uint8Array.from(atob(iv), c => c.charCodeAt(0)); const ctBytes = Uint8Array.from(atob(ct), c => c.charCodeAt(0)); const plaintext = await crypto.subtle.decrypt( { name: 'AES-GCM', iv: ivBytes }, key, ctBytes ); const payload = JSON.parse(new TextDecoder().decode(plaintext)); if (payload.exp && payload.exp > Date.now()) return payload; return null; } catch { return null; } } // --- Login page HTML --- function loginPage(error = '', clientName = '', displayOverride = '') { const displayName = displayOverride || (clientName ? clientName.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ') : 'Sign in'); return ` ${displayName} `; } // --- Middleware --- export async function onRequest(context) { const { request, env, next } = context; const url = new URL(request.url); // Allow robots.txt to be served (it blocks everything) if (url.pathname === '/robots.txt') { return new Response('User-agent: *\nDisallow: /', { headers: { 'Content-Type': 'text/plain' } }); } // BOM-strip defensively: wrangler/PowerShell pipes can prepend U+FEFF // to secret values, which silently breaks string equality. const stripBom = s => (s || '').replace(/^\uFEFF/, '').trim(); const secret = stripBom(env.SITE_SECRET); const password = stripBom(env.SITE_PASSWORD); if (!password || !secret) { return new Response('Configuration error: secrets not set', { status: 500 }); } // Login page heading: SITE_DISPLAY_NAME if set, else the first label of the host name const hostname = url.hostname; const clientName = hostname.split('.')[0] || ''; // Check existing session cookie const cookies = request.headers.get('Cookie') || ''; const match = cookies.match(new RegExp(COOKIE_NAME + '=([^;]+)')); if (match) { let rawToken; try { rawToken = decodeURIComponent(match[1]); } catch { rawToken = null; } const session = rawToken ? await verifyToken(rawToken, secret) : null; if (session) { // Valid session, serve the content with security headers const response = await next(); const newResponse = new Response(response.body, response); newResponse.headers.set('X-Robots-Tag', 'noindex, nofollow, noarchive, nosnippet, noimageindex'); newResponse.headers.set('X-Content-Type-Options', 'nosniff'); newResponse.headers.set('X-Frame-Options', 'DENY'); newResponse.headers.set('Cache-Control', 'no-store, no-cache, must-revalidate, private'); newResponse.headers.set('Pragma', 'no-cache'); return newResponse; } } const displayOverride = env.SITE_DISPLAY_NAME || ''; // Handle login form submission if (request.method === 'POST') { let submitted; try { const formData = await request.formData(); submitted = formData.get('password') || ''; } catch { return new Response(loginPage('Invalid request.', clientName, displayOverride), { status: 400, headers: { 'Content-Type': 'text/html', 'X-Robots-Tag': 'noindex, nofollow' } }); } if (await timingSafeEqual(submitted, password)) { // Password correct, create session const token = await signToken( { sub: clientName, exp: Date.now() + (SESSION_TTL * 1000) }, secret ); return new Response(null, { status: 302, headers: { 'Location': url.pathname === '/' ? '/' : url.pathname, 'Set-Cookie': `${COOKIE_NAME}=${encodeURIComponent(token)}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${SESSION_TTL}`, } }); } else { // Wrong password return new Response(loginPage('Wrong password. Try again.', clientName, displayOverride), { status: 401, headers: { 'Content-Type': 'text/html', 'X-Robots-Tag': 'noindex, nofollow', } }); } } // No valid session, show login page return new Response(loginPage('', clientName, displayOverride), { status: 401, headers: { 'Content-Type': 'text/html', 'X-Robots-Tag': 'noindex, nofollow', } }); } ``` ### `addons/INDEX.md` ````markdown # Add-ons Optional layers. None is loaded by default. Install one when the person asks for it by name, when the intake answers name the system it covers, or when a task clearly needs it (for example, they hand you a ticketing export and say "Vivenu"). | Add-on | Use it when | What it adds | |---|---|---| | `vivenu` | The person sells tickets through Vivenu and wants reports, counts, or checks built from its API | The rules that make ticket numbers come out right (orders not tickets, paid means paid, transfers, scans, shops), `vivenu_client.py` with pagination, the `vivenu` skill, and the template script `templates/event_sales_report.py` (paid orders, tickets by type, money collected for one event) | | `hubspot` | The person's contacts, companies, or deals live in HubSpot | Read patterns for the CRM API, property discovery, search paging, `hubspot_client.py`, a hard rule and the `hubspot-write-guard.py` hook that block writes without written confirmation, and the `hubspot` skill | | `cloudflare-workers` | A page needs to remember something, redirect, store files, or run on a schedule | Four small Workers with their config: KV-backed board, D1 link shortener, R2 file store, cron monitor. Each is a working starting point. Plus the `cloudflare-workers` skill | | `memory` | The person wants the AI to remember facts, preferences, and corrections across sessions | A file-per-fact memory folder, an index, the `recall-memory.py` hook that recalls matching memories on every prompt, and the `remember` skill | | `spreadsheets` | The person's data lives in Excel files, not CSV | `xlsx_to_csv.py` and `write_xlsx.py`, which read and write `.xlsx` with openpyxl without losing dates, merged headers, or formulas; the export path to `data.js`; and the `spreadsheets` skill | | `email` | A page or a script needs to send email | `send_email.py`, which sends through Resend with a plain-text default, the `email-send-guard.py` hook that blocks any send not confirmed in writing, and the `email` skill | | `vps-jobs` | The person wants jobs that run while their computer is off: nightly pulls, report emails, monitors | A small always-on Linux server pattern: `setup.sh` bootstrap, a systemd timer job template with once-per-break alerts, `install-job.sh`, and a `vps-jobs` skill for running it over SSH through git | ## How to install one 1. Read `addons//ADDON.md` in full. It is written for you. 2. Do what its Install section says. Usually: copy `addons//skill/SKILL.md` to `.claude/skills//SKILL.md`, copy any hook it ships into `.claude/hooks/`, register it in `.claude/settings.json`, and set the environment variables it names. Every hook is registered in the same form, `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/run-hook.sh"