YAWRN.STUDIO — DOCUMENTATION PLAN (raw)
=======================================
status: PLAN. nothing below is written yet; this page is the map of what will be.
served at /docs from docs/documentation-plan.md. edit the file, the page follows.
last touched: 2026-10-01 (v1.11.2)

HOW THE DOCS WILL WORK
----------------------
- one page per feature, at /docs/<slug>. this page becomes the index.
- every page has the same bones:
    what it is (one paragraph, plain words, no jargon)
    how to do it (numbered steps, one screenshot per step)
    things to know (limits, gotchas, what it costs)
    when it goes wrong (the errors you can see and what they mean)
    related (links)
- two readers, two depths: the person making a site (most pages), and the person running the studio (admin + ops pages). a page says which at the top.
- screenshots are taken by the Playwright UI tests (YS_SHOTS=…), so they refresh with every version instead of rotting.
- reading level: a 10-year-old or an 80-year-old. short sentences. no "simply". every button named exactly as it reads on screen.
- each page ends with "last checked against v1.x.y".
- format: markdown in docs/pages/<slug>.md, rendered by the same raw route as this page until a proper docs shell exists (a later plan item).

PRIORITY ORDER (what to write first)
------------------------------------
P1  getting started: account, welcome tour, dashboard, the four ways to start, publishing.
P2  the editor: canvas, adding blocks, text, inspector, phone view, undo/history, pages.
P3  the AI builder, rebuilding a site, copying a style.
P4  growing: site settings, custom domains, analytics, form replies.
P5  admin + ops.
P6  reference: every block, every section, every animation, every setting, shortcuts.

1. GETTING STARTED
------------------
1.1  creating an account
     covers: sign up (name, email, password), invite codes (when sign-up is invite-only), email confirmation (when mail is on), what "closed" sign-up means, signing in, forgot password, sessions and signing out everywhere.
     screens: /signup, /login, the check-your-email screen, /account sessions list.
     notes: password rules; the admin account on first start; rate limits on login/sign-up.

1.2  the welcome tour (new in 1.11)
     covers: what the first-sign-in welcome offers, the free portfolio site it starts you with, the nine steps of the tour, skipping, taking it again ("Show me around first" on the empty dashboard), where the tour record lives (account settings).
     screens: the welcome card; each tour step in the editor.

1.3  the dashboard
     covers: site cards (thumbnail, cost pill, edited/live/visitors/replies), Edit / Analytics / Replies / Preview draft / Export / Delete, the settings gear, the AI spend line, the version in the footer and the update log.
     screens: dashboard with 2–3 sites; the cost breakdown.

1.4  starting a site — the four ways
     covers: build it with AI (interview), start from a template (Blank / Landing / Portfolio, with live previews), rebuild an existing site. when to pick which.
     screens: the New-site modal; the template picker.

1.5  publishing
     covers: Publish, the live address (/s/<slug>), changing the slug, what "published" freezes, republishing, previews (/p/<id>) vs live, version history and restoring, export (zip of the site), deleting.
     notes: publishing stores settings too (password, robots, 404).

2. THE EDITOR
-------------
2.1  a look around
     covers: the top bar (site name, page picker, device, zoom, move mode, grid, play, save state, undo/redo, history, code, shortcuts, command palette, Preview, Analytics, Publish), the left panel (Add / AI / Layers / Pages), the canvas, the inspector.
     screens: annotated editor.

2.2  the canvas
     covers: selecting, the selection bar (parent, drag, duplicate, delete), resize handles, hover outlines, scrolling and zoom (fit, ⌘0, pinch, ⌘+/−), panning, the empty-page hint, clicking an empty container to add into it. the canvas is as tall as the page (no ceiling).
     screens: selection with handles; zoom menu.

2.3  adding blocks and sections
     covers: the Add panel, the hover demos (what each item does before you add it), drag onto the page or click to add where you are, sections vs blocks, the command palette (⌘K → "pricing"), search.
     screens: the palette; a demo popover; a drop line; drop-into highlight.

2.4  moving things
     covers: Flow mode (reorder by dragging), Free mode (position anywhere, cqw units on design sections), the grid and snapping, the Layers panel (drag to reorder, hide with the eye, rename), wrap/unwrap in a box.
     screens: layers panel; free move.

2.5  text
     covers: click to edit, double-click to select a word, the text toolbar (bold, italic, underline, link, clear), rotating words {a|b|c}, headings and levels, the rewrite-with-AI action.
     screens: text toolbar; rotating words on the published page.

2.6  the inspector — content
     covers: per block: props (text, links, image picker, icon grid, lists such as nav links and form fields, the 3D model picker, video URL, embed HTML).
     screens: one per block type's content panel.

2.7  the inspector — looks
     covers: Layout (flex direction, wrap, gap, alignment, columns count and stacking), Size (width/height/min/max), Position, Spacing (padding/margin box model), Typography (font, size, weight, leading, tracking, colour, align), Background (colour, gradient, image), Border (width, colour, radius), Effects (shadow, opacity, blur), Visibility & CSS (hide on devices, custom class/CSS).
     screens: each section open.

2.8  responsive design
     covers: Desktop / Tablet / Mobile; how a style set on a smaller device overrides the larger; columns stacking; hiding a block on one device; what visitors' phones actually see.
     screens: the three device widths on the same section.

2.9  the theme (site-wide look)
     covers: Colours (primary, secondary, accent, backgrounds, text, muted, border, gradient), Typography (heading/body/display fonts from Google Fonts, weights, the type scale), Shape & width (corners, buttons, shadow, content width), texture, Motion (none/subtle/lively, intro, progress bar, page transitions), copying the style of a website into the theme.
     screens: the theme panel; before/after of a colour change.

2.10 animation and play mode
     covers: entrances (fade, up, pop, word by word, typewriter, count up, draw…), scroll effects (parallax, reveal, pin, sideways…), loops (float, pulse, gradient…), hover (lift, tilt, magnetic…), section backdrops (aurora…), the quick picks, the full Animation panel, Play mode (P) and Replay, the "one by one" stagger on containers, reduced-motion behaviour.
     screens: the animation panel; play mode on.
2.13 Animation mode (v2.11.0): the timeline under the page (A), layers and bars, the playhead and scrubbing, Space, editing bars and diamonds, K, Record, copy / paste, the shortcuts, how it links to the inspector. See docs/animation.md.
2.14 Animation mode, further (v2.12.0): the graph editor (E — the ease into a key as a curve with handles, the named curves, the value preview), motion paths (T — the route on the page, drag a key), the device switch (D — desktop / tablet / phone motion, inherits and reset, in the drawer and the inspector), animated effect sliders (~ on a slider: with the scroll or over time, from / to), the shortcuts sheet. See docs/animation.md.
2.12 Effects (v2.10.0): the library's five packs, the Effect block (backdrop or band), element effects from a block's Effects section, the sliders, what phones get, the page's effect budget and the publish warning. See docs/animation.md.
2.11 the Timeline (keyframes, v2.8.0): tracks (when it comes into view, when the page opens, with the scroll, under the pointer), the nine channels (move across / down, scale, rotate, tilt back / side, skew, opacity, blur), the strip (click to add a key, drag to retime), the playhead, the presets, "From the animation above", undo; what the AI uses and what it discards. See docs/animation.md.
     screens: the timeline panel with three keys; the scrubber mid-track.

2.11 pages
     covers: adding, renaming, paths, titles and descriptions (search results), reordering, duplicating, deleting, anchors and links between pages (/about, #team), the 404 page text.
     screens: pages panel; page meta.

2.12 undo, versions and the code drawer
     covers: undo/redo, autosave and the save state, Version history (restore any earlier state, the AI's named versions), the page code drawer (HTML/CSS, editing HTML and applying it back), export.
     screens: history modal; code drawer.

2.12a resizing the side panels (new in 1.11.1): the handle, double-click to reset, where the width is kept.

2.13 keyboard shortcuts and the command palette
     covers: the full sheet (?), ⌘K actions (add, jump to page, publish, AI edit), context menu (right-click).
     screens: the shortcut sheet.

2.14 edit by asking the AI
     covers: the AI tab (⌘J): describe a change in words, the edits it proposes, applying/undoing, what it can and cannot touch, cost per edit, the analytics-insight shortcut (#ai=…).
     screens: the AI panel with a request and the applied result.

3. BLOCKS (reference, one short page each)
------------------------------------------
3.1  section   3.2 box   3.3 columns   3.4 spacer   3.5 divider
3.6  heading   3.7 text   3.8 button   3.9 image (upload, fit, treatments duotone/blob/tilt/float/frame/glass, parallax)
3.10 icon (the library, custom SVG path)   3.11 SVG shape (vector)   3.12 video   3.13 embed
3.14 3D model (upload .glb/.gltf, the libraries: Kenney built-ins, poly.pizza, Poly Haven; credit; auto-rotate; scroll zoom switch)
3.15 navbar (logo text/image, links, button, sticky; phone menu)   3.16 form (fields, required, submit label, success text, post to your own URL)
3.17 pop-up (new in 1.10): triggers (delay, scroll depth, exit, at once, from a link), once per visit/day/ever/always, size, position, dim, anchor; how it looks on the canvas vs live.
     each page: what it is, its props, a screenshot on the canvas, a screenshot live, tips.

4. SECTIONS (reference: the prebuilt kinds)
-------------------------------------------
     one line each + a screenshot, grouped as the palette groups them:
     Navigation: navbar, footer.
     Hero: hero, heroSplit, heroLayered, spotlight.
     Content: features, about, text, gallery, team, steps, faq, timeline, bento, story, bigNumber, marquee.
     Social proof: testimonials, quoteBig, logos, stats.
     Commerce: pricing.
     Conversion: cta, ctaSplit, contact, pop-up.
     + "custom" (what the AI builds when nothing fits).

5. PICTURES, FILES AND UPLOADS
------------------------------
5.1  uploading pictures: formats (PNG/JPG/GIF/WebP/AVIF/SVG), size limits, where they live (/uploads), the site's file list, deleting.
5.2  what the AI sees in a picture: the caption/kind/colours the vision model notes, how the builder uses them, turning it off (VISION_AI_MODEL=off).
5.3  remove the background (the cut-out tool): when it works, the model behind it, cost (none — local).
5.4  storage limits per plan; the nightly sweep of orphan files.
5.5  fonts: Google Fonts; self-hosted faces (theme.fonts.faces).

6. THE AI BUILDER
-----------------
6.1  the interview: what it asks and why (purpose, audience, pages, tone, call to action, colours as designed palettes, fonts, imagery, facts, contact), uploading a logo and photos during it ("must appear" ticks), the whole-brief box on the start screen, changing the brief, the draft site that holds uploads.
6.2  the brief: every field explained; editing it before the build; what "facts" do.
6.3  the build: concept (24 archetypes, layouts, no two sites alike), plan, pages written in parallel, assembly, the polish pass (the critic looks at screenshots), the 3D placement, required pictures placed and checked; the build page, its cost ticker, its clock bar and the time on every step; picking a build back up after a reload; stopping a build.
6.4  Precision Development: what changes (the same scope on the most capable model, three times the clock), what it costs, when it is worth it (the in-depth, ambitious site).
6.5  costs: what each step costs, the cost pill per site, the studio's monthly spend limit and what "paused" means.
6.6  after the build: it is all ordinary blocks; the named versions; publishing.
6.7  the build clock (v2.7.0): a build may have a time limit the way it has a cost cap — none unless the admin sets one (since 2.12.1; the earlier five-minute default cut steps and shipped incomplete sites), three times it for Precision Development. The scope of a fast build is three concepts judged on boards, two review rounds and a photo check. The concept, the plan, every page and the assembly always finish, so the site is always whole; what the time does not allow is left out in a fixed order — the second review round first, then the picture check, then the review itself; three concepts become one only when even the required steps would leave no room for the boards and the judge; the 3D search and the remaining picture searches stop at the deadline — and a critic look still running at the deadline is cut off, the page keeping what the build made. The build page says what was left out and why (the clock or the cap), and the site records what each step took. How long a step takes here is learned from past builds (the mean of each kind of call), so the estimates on the build page and the planning get better with use.

7. REBUILD AN EXISTING SITE
---------------------------
7.1  what it does: paste an address, choose keep-their-look or a new look, tick the permission box, press Read the site and build it. no interview (new in 1.10).
7.2  what gets read: pages (up to eight, from the site's own navigation), headings/copy/lists/buttons, contact details, hours, socials, the look, every picture (saved into the new site, all required), pop-ups (kept), screenshots.
7.3  the permission record: what is stored and why; the audit log.
7.4  the brief written from the site; the notes box; Precision on the same screen.
7.5  what to expect and what to fix afterwards; limits (8 pages, 150 s, 40 pictures, 12 MB each); sites that block crawlers.

8. COPY THE STYLE OF A WEBSITE
------------------------------
8.1  reading a style guide from one to three sites (fonts, colours, corners, buttons, layout language, rules), the sample, saving and reusing guides, using one for a new build, applying one to the theme in the editor.
8.2  what it costs; what it cannot read (canvas-drawn sites, walled logins).

9. (removed: the Figma import left in v2.3.0)

10. SITE SETTINGS AND DOMAINS
-----------------------------
10.1 site settings: name and address, favicon, social image, head tags, password protection, noindex, the 404 text, form mail and webhooks.
10.2 custom domains: CNAME/A records, connecting (DNS check → certificate → live), what can go wrong, removing, the studio's own address vs the domain.
10.3 sitemap and robots; how previews are kept out of search.

11. ANALYTICS
-------------
11.1 the report: visitors, pageviews, time, scroll depth, pages, entries/exits, referrers and channels, UTM, audience (country, device, browser, language), sections, clicks, rage clicks, goals and conversion, vitals, the weekday×hour heat, the funnel, live visitors, CSV export.
11.2 privacy: cookieless, what the beacon sends, the daily-salted visitor id, bots dropped, 13-month retention, geo from a local database.
11.3 AI insights: what they are, once a day per range, the suggested edit.
11.4 alerts and the weekly digest (account settings).

12. FORMS AND REPLIES
---------------------
12.1 the form block; replies in the dashboard; mail to the owner (account + site switches); webhooks (Slack, Discord, Zapier, Make); posting to your own endpoint; spam (honeypot, timing); exporting.

13. YOUR ACCOUNT AND PLAN
-------------------------
13.1 profile (name, email), password, sessions (sign out a device), notifications (digest, alerts, form mail), the tour record.
13.2 plans and limits: free / pro / business (sites, AI builds and edits per month, storage, domains, pageviews), what happens at a limit, admin overrides.

14. ADMIN (for whoever runs the studio)
---------------------------------------
14.1 overview: users, sites, spend, the corpus counts.
14.2 users: roles, status (suspend), plan and per-user limits, impersonate (and the banner), invites.
14.3 settings: sign-up mode (open / invite / closed), the announcement strip, the passcode, monthly AI spend limit and pause, the limit per build ($) and the time limit per build (seconds) with their drop orders.
14.4 the log: audit events, the mail outbox (every message sent or queued, with its status), AI usage.
14.6 email (new in 1.11.1): the six templates and what each is for; editing one in the editor (the 600px canvas, the subject in the top bar, the variables and where each may go, Embed for the HTML ones); Preview and Send me a test; Reset; sending a message to people (chosen, everyone, a plan, typed addresses), the preview, the confirmation, the progress and the log; what happens without a Resend key.
14.7 your own templates and schedules (new in 1.11.2): New template (blank or a copy), rename/delete, the variables they take; Schedule… from the Send form, the kinds (once, daily, weekly, monthly), time zones, who is included at each run, Run now, pause/resume, the last-run line, what a failed run does.
14.5 the training corpus: what is recorded (builds, edits, publishes), export as JSONL.

15. RUNNING IT (ops)
--------------------
15.1 install: Node 24, .env (every variable explained: PORT, PUBLIC_ORIGIN, BUILDER_PASSCODE, SESSION_SECRET, DATA_DIR, ANTHROPIC_API_KEY, AI_MODEL, VISION_AI_MODEL, COST_MULTIPLIER, RESEND_API_KEY, SERVER_IP, GEOIP_DB, POLY_PIZZA_API_KEY, JOBS, DOMAINS_DRY_RUN), the systemd units, nginx, certbot.
15.2 data: DATA_DIR layout (studio.sqlite, corpus.sqlite, uploads, styles, sources, fig, backups), nightly backups (seven kept), migrations, moving a studio.
15.3 dev and prod on one box: the two checkouts, promoting (deploy/promote.sh), the version label, the update log.
15.4 optional pieces: headless Chromium (style read, rebuild, polish), the remove-bg model, the 3D packs, the GeoIP database, mail.
15.5 tests: npm test (offline), npm run test:ui (browser, against a dev server), test:ai (real API, costs money).

16. SECURITY AND PRIVACY (one page, plain)
------------------------------------------
     accounts and sessions, what is stored about visitors, uploads served safely (nosniff, SVG sandbox), published-site passwords, the permission record for rebuilds, what the AI is sent, what the corpus keeps, deleting a site or an account.

17. THE UPDATE LOG
------------------
     /updates: every version and what it brought. the docs link to it; each doc page names the version it was checked against.

18. LATER
---------
- a docs shell (sidebar, search) once the pages exist; until then the raw route serves markdown as-is.
- in-product links: every panel head gets a "?" that opens its page.
- a "first five minutes" video, captured from the tour.
- translations: none planned; the tour's copy is written to translate easily (short, literal).