Document 01 of 14 · SPEC.md

artisanpdfstudio.com, Project Spec v1

One line: A studio of well-designed PDF templates you customize in the browser, then buy and download. Each template is composed by hand, prints true on a home printer, and is made yours in about a minute.

Tagline (recommended): Well-made PDF templates, made yours.

This document is the source of truth. It becomes the seed for CLAUDE.md when the repo is bootstrapped. Every decision below is made unless it is listed in section 11. Companion documents: ARCHITECTURE.md (how a PDF gets made, paid for and delivered), DESIGN.md (identity and the customizer), CATALOG.md (the roster), SETUP.md (what the owner creates before session one).

---

0. What is there today, and what happens to it

This is a consolidation of every earlier PDF farm attempt into one relaunch: one name, one repo, one database, one standard. Checked 2026-09-16 from the repo, the Lovable workspace, the Supabase org and DNS; the Lovable workspace and GitHub were also searched for farm, template, printable, document, certificate, invoice and studio, and nothing beyond the rows below turned up. Nothing below holds a customer, an order, a subscriber or a design worth carrying, so the replacement is a clean one.

Why one database rather than a new one: PDF Farm is already in the Synergy org, already paid for, in the same region Vercel deploys to, and empty. Resetting it is two migrations and a dashboard visit, and it leaves the org with one PDF project instead of two.

Why replace rather than extend: the old build renders PDFs on the client with react-pdf, so the preview and the file were two different pieces of code and could disagree; an account stood between a visitor and a $2 file; the look was default shadcn; and the two databases between them hold zero rows of anything. Starting clean costs nothing and keeps nothing that would have needed defending later.

1. Positioning & mission

• This is a relaunch: the earlier PDF farm attempts consolidated under one name, one repo, one database and one standard, and reimagined rather than patched.
• We are a design studio that sells its work as PDFs, not a template dump. Volume comes from a template system (one design, several color themes, two paper sizes, dated and undated variants), never from lowering the bar.
• Every template page answers one question completely: "Is this the one, and can I make it mine?" The visitor sees the real page at true size, tries a theme, and either downloads the plain version or customizes and buys.
• The customization is the product. The plain design is free to see and free to print. Money changes hands when the page carries the visitor's name, dates, colors, logo and wording, in both paper sizes, with no credit line.
• Trust is the moat, the same way it is on measureandbuy. Here trust means: it prints exactly as previewed, the fonts are licensed, the price is stated before the work starts, and a broken file gets refunded without an argument.
• We never dress the site up as an AI product. Claude helps write wording in a text box when asked, and helps us draft page copy behind the scenes. The templates are designed by a person and checked on paper. "Artisan" is a claim we have to be able to defend.

2. Stack & pipeline

• Built in Claude Code. No Lovable, no framework, no bundler. Plain HTML, CSS and JavaScript for every page the visitor sees, same structural DNA as measureandbuy and one-page-toys.
• Vercel hosts the static site and runs a handful of Node functions from an api/ folder (checkout, webhook, render, order lookup, draft assist, subscribe). Vercel's "Other" preset serves api/*.js beside static files with no build. That is the one place code runs on a server, and it is the only place secrets live.
• Supabase holds orders and the finished PDFs (Postgres + a private Storage bucket). No visitor accounts in v1. Accounts arrive with the all-access pass in Phase 3, via magic link.
• Stripe Checkout (hosted page) takes the money. The webhook is the source of truth for "paid". Stripe Tax handles sales tax and EU VAT on digital goods if the owner turns it on.
• Resend sends the receipt with the download link, the re-download link, and later the "new this month" broadcast to the list.
• Cloudflare does three jobs. DNS for the site (grey cloud, DNS only, the way measureandbuy runs). Turnstile in front of the draft-assist and subscribe endpoints; it works without proxying. And Browser Run (the service formerly called Browser Rendering) makes the paid PDFs: one HTTPS call from the Vercel function with the template HTML and the visitor's values, PDF bytes back. No Chromium binary in the deploy, no version pairing to babysit. The Workers Paid plan ($5 a month, ten browser-hours included) is the launch setting, because the free tier allows one render every ten seconds and a launch-day rush would queue. ARCHITECTURE.md section 4 carries the fallback (Chromium inside the Vercel function) if this ever needs replacing.
• Anthropic API (claude-opus-5 by default) powers "Write it for me" on long-text fields and the hand-run copy drafting script. It is never in the checkout or render path. See ARCHITECTURE.md section 7.
• GitHub → Vercel auto-deploy on main. No CI build. A GitHub Action may run hand-written checks (link sweep, render smoke test) but nothing runs at deploy time. Same reading of "no build step" as measureandbuy's generators decision: hand-run design tools whose output is committed static files.
• Analytics: GA4 with the same host guard measureandbuy uses (nothing injects on localhost or preview hosts), Search Console by DNS TXT, Stripe dashboard for money, a Supabase view for orders. Pinterest tag is Phase 2.
• All copy passes the human-voice lint before shipping. Template descriptions, FAQs, pin text, and every email.

3. Repo structure

artisanpdfstudio/
  index.html                      # homepage: working mini-customizer + roster
  templates/
    planners/index.html           # category page (generated)
    planners/weekly-planner/
      index.html                  # template page, indexable (generated)
      customize/index.html        # the customizer, noindex (generated)
      free/weekly-planner-letter.pdf   # the plain version, pre-rendered, static
    ...
  studio/                         # TEMPLATE SOURCES, the actual design work
    weekly-planner/
      template.html               # the sheet(s): plain HTML with data-bind hooks
      template.css                # print-first CSS, @page size, .sheet dimensions
      fields.json                 # what the customizer exposes, with limits + defaults
      meta.json                   # title, category, price, sizes, themes, SEO phrase
      shots/                      # preview.png, og.png, pin.png (generated)
  assets/
    css/site.css                  # shell only: header, footer, grids, prose, sheet frame
    css/studio.css                # the customizer UI
    js/site.js                    # footer, GA4 guard, related grid (CATALOG constant)
    js/studio.js                  # THE RUNTIME: apply(values) -> DOM; shared by preview and render
    fonts/                        # self-hosted, OFL only; one file per face actually used
  api/
    checkout.js                   # POST: validate values, create order, open Stripe session
    stripe-webhook.js             # POST: verify signature, mark paid, kick render, email
    render.js                     # internal: template + values -> PDF -> Storage
    order.js                      # GET: status + signed URLs for success page / email link
    draft.js                      # POST: Claude writes a field's text (Turnstile + limits)
    subscribe.js                  # POST: add to the Resend audience (Turnstile)
  data/
    catalog.json                  # generated index of every template (one list, many consumers)
    fonts.md                      # append-only: face, license, source URL, date, where used
  studio-src/                     # hand-run generators and checks, NOT a build step
    build.mjs                     # studio/* -> templates/* pages + catalog.json + sitemap
    shots.mjs                     # preview / OG / pin images from the real template
    free.mjs                      # pre-render the plain PDFs
    copy.mjs                      # Claude drafts description/FAQ/pin text to review
    sweep.cjs                     # drive every page at 1440 and 390, assert, fail loudly
    serve.py                      # no-store local server (copied from measureandbuy)
  supabase/migrations/            # SQL, applied by hand with the CLI or MCP
  og/, pins/                      # generated share images
  help/                           # six evergreen print-help pages (the link magnets)
  license/, terms/, privacy/, refunds/   # the legal four, plain HTML
  SPEC.md, DESIGN_SYSTEM.md, CLAUDE.md, .ai/memory/

Rules:

• A template folder is portable. studio/<slug>/ plus assets/js/studio.js and the fonts it names is everything needed to preview and render it. Nothing about a template lives in the database. The database holds orders, not designs.
• template.html is the one source of the design. The customizer preview, the free PDF, the paid PDF, the preview image, the OG card and the pin are all rendered from that file. There is no second copy that can drift.
• The runtime never designs, the template never computes. studio.js sets text, swaps theme variables, toggles sections and fills repeated rows from values. A template may declare a small compute hook in fields.json (invoice totals) and that hook is the only arithmetic. Same rule as measureandbuy's diagram layer, for the same reason.
• data/fonts.md is append-only. Every face that ships is logged with its license and where it came from. A face that cannot be traced to an OFL or equivalent commercial-use license does not ship. This is the audit trail that makes "artisan" defensible.
• Shared CSS is shell only. Template styles live in the template. The customizer's own UI lives in studio.css.

4. Page anatomy

4.1 Template page (/templates/<category>/<slug>/, the page that ranks)

1. Breadcrumb, H1, promise. Exact-match H1 ("Weekly Planner Template"), one sentence under it that says what it is for and what you can change. No preamble.
2. The sheet, live. The real template rendered at true aspect ratio (8.5 by 11), on a desk surface with a paper shadow. Under it, the theme swatches: tap one and the sheet repaints. This is the same runtime the customizer uses, with only the theme exposed. Multi-page templates show page one with the page count stated.
3. Two calls to action, side by side, with the price on the paid one. "Make it yours, $7" opens the customizer. "Download the plain version, free" is a direct link to the static PDF. The free one says exactly what it lacks (one theme, Letter, small credit line at the foot).
4. What is inside. A spec list, not prose: pages, sizes, what you can change, what the free version includes, fonts used (named, because they are licensed and that is a selling point), file format, license tier.
5. Description, 300 to 600 words. Who it is for, how the layout is meant to be used, what to print it on, the one design decision worth explaining. Written by a person or drafted by copy.mjs and then rewritten by a person. Human-voice lint before commit.
6. Print notes. "Print at 100%, not fit to page." Paper weight suggestion. Double-sided guidance for multi-page sets. Links to the relevant /help/ page.
7. FAQ, 3 to 5 questions with FAQPage schema. Only questions the page actually answers.
8. Related templates: same category, then same family (the monthly planner beside the weekly). Rendered from catalog.json.
9. Footer.

Schema on this page: Product with an Offer (price, currency, availability, URL) and image, BreadcrumbList, FAQPage. Never an AggregateRating we did not earn. og:type is product with product:price:amount so Pinterest reads it as a Rich Pin. Every page has an OG card (1200 by 630) and a pin image (1000 by 1500), both rendered from the template itself.

4.2 Customizer (/templates/<category>/<slug>/customize/, noindex)

Desktop: a 380px form column on the left, the sheet on the right, scaled to fit, with a "PROOF" pattern over it. Fields are grouped (Text, Dates, Colors, Options, Logo, Paper size). A sticky top bar carries the template name, the price and the one button: "Download your PDF, $7". Mobile: the sheet on top at about 40% of the screen height (tap to expand), the form under it, a fixed bottom bar with price and button, shown until the real button scrolls into view (the measureandbuy answer-bar pattern).

Rules that make it trustworthy:

• Instant. No apply button. Every keystroke repaints the sheet.
• It refuses to sell a broken page. Text boxes have limits from fields.json, and the runtime measures overflow inside fixed boxes. Overflow shows a plain warning on the field and disables the buy button until it fits. No vendor does this; every one of them lets you buy a certificate whose name runs off the ribbon.
• Autosaves the values to localStorage keyed by slug, so a phone interruption does not lose the work.
• Says what happens next, under the button: "Pay on Stripe, then your PDF is ready in about ten seconds, in Letter and A4. We email you a link that works for a year."
• "Write it for me" appears only on long-text fields whose fields.json marks assist: true (certificate wording, invitation lines, an "about" paragraph). It drafts into the field; it does not send anything anywhere else.

4.3 Success page (/order/?id=…&t=…)

Polls /api/order until the PDF is ready, then shows two download buttons (Letter, A4), the order number, "sent to your email", and "Make another" links back to the category. A failed render shows a real message with the order number and the support address, never a spinner forever.

4.4 Category page (/templates/<category>/)

Short intro (100 to 200 words, written for the reader, not the crawler), then the templates as sheets in a grid, newest first, with price and "free version" marked. Category pages are the internal-linking spine.

4.5 Homepage

The hero is a working mini-customizer: a certificate (or the current featured template) with two fields, name and title. Type and the sheet sets your name in the display face. Same runtime, same template. Under it: "New this month" as a row of sheets, then the categories as a labeled drawer list, then the Studio Standard as six short promises the visitor can check, then the email signup, then the footer. Same principle as measureandbuy's homepage calculator: demonstrate the product instead of describing it.

5. The Studio Standard (guardrails, no ship without all six)

1. Designed by hand, checked on paper. Every template is composed in HTML and CSS with a deliberate type system, then printed at 100% on a home inkjet and looked at. Margins stay inside 0.5 in on every edge. Nothing ships that has only been seen on a screen.
2. Prints true. Letter and A4 both, from one file, via @page rules and a .sheet sized in inches or millimetres. Every template ships a light-ink theme because home printers are paid for by the cartridge. What the customizer shows is rendered by the same file that makes the PDF; there is no "final may differ".
3. Licensed everything. Fonts are OFL or an equivalent commercial-use license, logged in data/fonts.md, self-hosted as static instances, embedded in the PDF (the file check proves it on every template). No stock photography, no clip art we cannot source. Decoration is drawn in CSS or SVG we made.
4. Customizable where it matters, locked where it does not. A template exposes the fields a person needs and no more. Every text field has a length limit and the customizer refuses overflow. A template with fifty knobs is a design that has not been finished.
5. Honest commerce. The price is on the template page before any work starts. The free version is real and its limits are stated. No countdown timers, no fake "only 3 left", no dark-pattern upsell at checkout. A broken file is refunded on request, and the refund policy says so in one paragraph. Receipts by email. Re-download for a year.
6. Human-voice pass on every description, FAQ, pin, email and the help pages before commit.

Two exclusions, on the same reasoning as measureandbuy's no-electrical rule: no legal documents (leases, contracts, wills, bills of sale, NDAs) and no medical or financial forms that carry regulatory weight. A pretty lease is legal advice in a PDF and we are not lawyers. Invoices, receipts and quotes are fine; they are stationery.

6. Free and paid, the model

Why a free version at all: the search intent behind "printable weekly planner" is overwhelmingly free-seeking, and Pinterest traffic bounces off a paywall it cannot see through. The free PDF is what earns links, saves and repeat visits, and the credit line on every one of them is the cheapest advertising we will ever buy. The paid product is not the design, it is the design with the visitor on it, in both sizes, in their colors. Templates whose whole point is personalization (invoice, certificate, invitation, letterhead) lose nothing to the free version, because a plain sample with someone else's company name is useless to a business.

No email gate on the free download in v1. The signup offer appears once the download has started. Gating can be added later behind one flag once there is traffic to measure it on.

Prices (recommended, section 11 lists them as an owner decision): three tiers, $4 for paper and simple trackers, $7 for planners, certificates and cards, $12 for business stationery and event-suite pieces. Whole families sell as bundles at about two and a half singles (Planner set $19, Business set $29, Wedding suite $29, Certificate set $15, Classroom set $15). The research in CATALOG.md section 4 is what moved these up from a first draft of $3 / $5 / $8: Etsy's going rates are $12 to $40 for business templates and $15 to $50 for wedding suites with browser editing included, and a site that sells the plain version for free is not competing on price with them anyway. An all-access pass is Phase 3 and needs accounts first.

The list is a channel, not a nicety. Email drives about 42% of sales on Gumroad against 23% from social. So the free download is not gated, but the moment it starts the page offers one thing: "Get the paper set free and one new template a month," which puts the subscriber on the Resend list in exchange for a real bundle, not a promise. The monthly broadcast is the cheapest repeat traffic the site will have.

7. Launch roster

Thirty templates across seven categories, in CATALOG.md, in build order. The first three are the ones that set the pattern, and the fourth is the one that scales:

Judge nothing until all thirty are live and the sitemap has sat in Search Console for eight weeks, the same rule measureandbuy runs on.

8. new-template skill (sibling of new-tool)

Written after the invoice proves the pattern. It carries:

• The research step: the search phrase, what the top results look like, what they get wrong on paper
• The template contract: template.html hooks, template.css rules for print, fields.json schema with limits, meta.json, themes
• The paper check: print at 100%, measure the margins, photograph it into the session
• shots.mjs for preview, OG and pin; free.mjs for the plain PDF
• Copy: description, FAQ, pin text, drafted then rewritten, human-voice pass
• Registration: catalog.json via build.mjs, category page, sitemap, related grids, homepage "new this month"
• Verify by driving: the sweep at 1440 and 390, a test-mode purchase, the PDF opened in Preview and Acrobat, pdffonts showing every face embedded

Target: one template = one design session + one build prompt.

9. Phases

• Phase 0, accounts and scaffold. Owner does SETUP.md (about an hour): disconnects Lovable from the repo and from PDF Farm, merges the rebuild branch to main, creates the Vercel project, deletes PDF Farm's old edge functions and renames it, puts Stripe in test mode, verifies the Resend domain, sets the env vars. One session: the two migrations applied to PDF Farm (reset, then the orders schema), site shell, design system, homepage with the hero wired to a placeholder template, the four legal pages, /help/ with two articles. Live at www as soon as it is pushed, since main is the production branch and the domain is already on Vercel (amended 2026-09-16: the owner moved the domain at separation and accepted a holding page until Phase 0; DECISIONS.md).
• Phase 1, the invoice, end to end. Runtime, customizer, checkout, webhook, render, storage, email, success page, free PDF, template page generator, share-image generator, sweep. Done means: a test-mode purchase from a phone, the PDF opens in Preview and Acrobat with fonts embedded in Letter and A4, the email lands inside a minute, the re-download link still works the next day, and a refund from the Stripe dashboard marks the order. Then what is left of SETUP.md section 7: the Stripe webhook, the legacy keys, the old products, Search Console (the domain move and the Lovable deletion happened at separation, 2026-09-16). Then extract the new-template skill.
• Phase 2, the roster and the surface. Templates 2 to 30 through the skill. Category pages, six help articles, sitemap submitted, Search Console, GA4, Pinterest business account with a pin per template, the Resend audience and the first "new this month" broadcast. Switch Stripe to live keys. This is where "PDF farm" happens, and it happens through the system, not by hand.
• Phase 3, growth (only with the eight-week read in hand). "Write it for me" on every long-text field. Bundles. Dated calendars for the next year, generated from the same source. Accounts by magic link, "my downloads", the all-access pass on Stripe Billing with the customer portal. Saved drafts server-side.
• Phase 4, only if the numbers say so. Localized A4-first pages for UK, AU and EU. Seasonal collections. A guest-designer program, if the standard can be enforced on outside work, which is doubtful.

10. What makes this defensible

A template marketplace has the scale. A single-product SaaS has the editor. Neither has all of these at once, and each is cheap for us because of how the site is built:

1. The preview is the file. One HTML source renders the page on screen and on paper. Marketplaces show a JPEG and hope.
2. It refuses to sell a broken page. The overflow guard. Canva will happily export a certificate with the name cut off.
3. Two paper sizes from one purchase, because @page makes it free for us and every marketplace sells them as two listings.
4. A real, stated free version with a credit line, so the free traffic works for the paid product instead of against it.
5. Licensed fonts, named on the page. Most printables sellers cannot tell you what license their fonts carry.
6. Print help that is actually useful (/help/): how to print at actual size, what paper to use, double-siding a planner. These are the pages that earn links from people who never buy anything, and that is fine.
7. No billing tricks. The largest competitor in the space advertises a $1.99 single template and then bills a year's subscription; its review score shows what that costs. A single price, paid once, stated before the work starts, is a feature we get for free by being honest, and the FAQ on every template page says so in one line.

11. Open items (owner decisions, small)

• The direction. Mockups at https://claude.ai/artifact/88arHMUX5p2ekQXW6gDEVo show Direction A (the studio desk) built out and two low-fi alternates, Darkroom and Letterpress. Recommended A, for the reasons in DESIGN.md section 1.
• Free version yes or no. Recommended yes, exactly as section 6. The alternative, strictly paid, is one flag and a copy change.
• Price tiers. Recommended $4 / $7 / $12 with bundles at $15 to $29; the research and the reasoning are in section 6 and CATALOG.md section 4.
• Tagline. Recommended "Well-made PDF templates, made yours." Alternates: "Pick a design. Make it yours. Print it." and "Templates worth printing."
• Business name on Stripe receipts and in the footer. "Synergy" per the house rule; the legal entity name only where Stripe requires it.
• Stripe Tax on or off at launch. On is the safer default if any EU or UK sales are expected; it also adds the digital-goods withdrawal consent line to Checkout.
• Cookie consent. GA4 sets cookies. If EU traffic matters, a consent bar is required for it. Recommended: launch GA4 with the host guard and add the bar in Phase 2 when the Pinterest tag arrives, so both are handled once.
• Which three templates first. Recommended invoice, weekly planner, certificate, in that order, for the reasons in section 7.
• Cutover clean-up. Decided 2026-09-16: PDF Farm is kept and reset as the database; the owner deletes the Lovable project and any Lovable attachment to PDF Farm once www serves the new site.
• Which Claude Project this lives in (recommend: Web Tools now, promote later if it grows, same as measureandbuy).