Improve docs starter experience

site/content/tutorials/brand-vs-product.md

@@ -0,0 +1,73 @@
+---
+title: Brand vs product
+tagline: "The setup choice that keeps Impeccable from applying the wrong design defaults."
+order: 3
+description: "Understand the brand/product choice in /impeccable init: marketing surfaces where the impression is the product, and app surfaces where design helps users finish a task."
+---
+
+## The short version
+
+During `/impeccable init`, the first important choice is this:
+
+- **Brand surface:** marketing site, landing page, campaign, portfolio, editorial page. The visitor's impression is the product.
+- **Product surface:** app UI, dashboard, admin screen, workflow tool, settings page. The user is trying to finish a task.
+
+The docs call this choice **register**. You do not need to use that word. You only need to answer which kind of surface you are working on.
+
+## Why it matters
+
+The same visual move can be right in one surface and wrong in another.
+
+A campaign page can afford a huge image, a strange type choice, one dominant idea per screen, and more expressive motion. It needs to create an impression.
+
+A dashboard usually needs density, predictable components, readable states, stable navigation, and quieter motion. It needs to help someone act quickly.
+
+When `PRODUCT.md` stores the right choice, every command adjusts. `/impeccable typeset` will not push editorial display type into a dense admin screen. `/impeccable colorize` will not make a campaign page timid because product UIs usually need restraint.
+
+## How to choose
+
+Ask what the person came to do.
+
+If they came to evaluate, trust, remember, compare, or feel a brand: choose **brand**.
+
+Examples:
+
+- SaaS landing page
+- Product launch page
+- Agency portfolio
+- Restaurant homepage
+- Conference site
+- Case study page
+
+If they came to configure, monitor, submit, search, compare data, or complete a workflow: choose **product**.
+
+Examples:
+
+- Analytics dashboard
+- Checkout flow
+- Settings screen
+- Admin table
+- Onboarding flow inside an app
+- Internal operations tool
+
+## Mixed projects
+
+Many codebases have both. A SaaS project can have a brand landing page and a product dashboard.
+
+Set the project default to the surface you work on most, then be specific in the command:
+
+```
+/impeccable polish the marketing homepage as a brand surface
+```
+
+```
+/impeccable audit the billing settings as a product surface
+```
+
+You can also edit `PRODUCT.md` directly if the default is wrong.
+
+## Common mistakes
+
+- **Calling everything product because it is a software company.** A landing page is still a brand surface.
+- **Calling everything brand because the visual identity matters.** A dashboard can be on-brand and still be a product surface.
+- **Skipping the choice.** Impeccable can still work, but it will ask more questions and lean on safer defaults.

site/content/tutorials/critique-with-overlay.md

@@ -35,7 +35,7 @@ It labels the tab it opens with `[LLM]` in the title so you can tell which one i
 
 ### What the automated detector does
 
-The second assessment runs `npx impeccable detect` against the page. This is deterministic: around thirty specific pattern checks that fire or do not fire. Gradient text, purple palettes, side-tab borders, nested cards, line length problems, low contrast, tiny body text, and the rest. The [full catalog](/anti-patterns) lists every rule and which layer (CLI, browser, or LLM-only) catches it.
+The second assessment runs `npx impeccable detect` against the page. This is deterministic: specific pattern checks that fire or do not fire. Gradient text, purple palettes, side-tab borders, nested cards, line length problems, low contrast, tiny body text, and the rest. The [full catalog](/slop#catalog) lists every rule and which layer (CLI, browser, or LLM-only) catches it.
 
 You get back a JSON list of every finding with its element selector, the rule that fired, and a short description.
 

site/content/tutorials/getting-started.md

@@ -1,13 +1,13 @@
 ---
 title: Getting started
-tagline: "From zero to your first polish pass in five minutes."
+tagline: "From install to your first polish pass in about ten minutes."
 order: 1
 description: "Install Impeccable, run /impeccable init once to establish project context, and run /impeccable polish on something that already exists. The fastest path to seeing what Impeccable changes about AI-generated design."
 ---
 
 ## What you'll build
 
-You will end this tutorial with Impeccable installed in your project, a `PRODUCT.md` plus `DESIGN.md` pair that captures your brand, audience, and visual system, and one hand-polished page that went through a polish pass. Total time: about ten minutes.
+You will end this tutorial with Impeccable installed, project context saved, and one existing page improved with a polish pass. Total time: about ten minutes.
 
 ## Prerequisites
 
@@ -16,7 +16,7 @@ You will end this tutorial with Impeccable installed in your project, a `PRODUCT
 
 ## How Impeccable works
 
-Impeccable installs as a single agent skill called `impeccable`. You access all 23 sub-commands through it:
+Impeccable installs as a single agent skill called `impeccable`. You access all 23 commands through it:
 
 ```
 /impeccable <command> <target>
@@ -26,6 +26,14 @@ For example: `/impeccable polish the pricing page`, or `/impeccable audit the ch
 
 If you use a command often, pin it with `/impeccable pin <command>` to create a standalone shortcut (for example, `/impeccable pin audit` gives you `/audit` directly).
 
+If you only remember one sequence, make it this:
+
+```
+npx impeccable skills install
+/impeccable init
+/impeccable polish the page you care about
+```
+
 ## Step 1. Install
 
 From the root of your project, run:
@@ -34,7 +42,7 @@ From the root of your project, run:
 npx impeccable skills install
 ```
 
-This auto-detects your harness and writes the build compiled for it to the right location (e.g., `.claude/skills/`, `.cursor/skills/`). It works with Cursor, Claude Code, GitHub Copilot, Gemini CLI, Codex CLI, and every other major harness. Reload your harness and type `/`. You should see `/impeccable` in the autocomplete. Type it and the skill's argument hint will show all available commands.
+This auto-detects your AI coding tool and writes the right skill files for it (for example, `.claude/skills/` or `.cursor/skills/`). It works with Cursor, Claude Code, GitHub Copilot, Gemini CLI, Codex CLI, and every other major harness. Reload your tool and type `/`. You should see `/impeccable` in the autocomplete. Type it and the argument hint will show the available commands.
 
 Prefer a different setup? Claude Code users can install the plugin with `/plugin marketplace add pbakaus/impeccable`, and the general-purpose `npx skills add pbakaus/impeccable` still works (though it installs one shared build for all harnesses rather than the one compiled for yours).
 
@@ -42,7 +50,7 @@ When a new version ships later, run `npx impeccable skills update` from the same
 
 ## Step 2. Set up Impeccable for your project
 
-This is the most important step. Design without context produces generic output. The `/impeccable init` command runs a short discovery interview and writes a `PRODUCT.md` file at the root of your project.
+This is the most important step. Design without context produces generic output. The `/impeccable init` command runs a short setup interview and writes `PRODUCT.md` at the root of your project.
 
 Run:
 
@@ -50,7 +58,12 @@ Run:
 /impeccable init
 ```
 
-The first question is about **register**: is this a brand surface (marketing site, landing page, portfolio, where design IS the product) or a product surface (app UI, dashboard, tools, where design SERVES the product)? Register shapes every downstream default, from type lanes to motion energy. See [brand vs product](/tutorials/brand-vs-product) for how the two diverge. Init will form a hypothesis from your codebase and ask you to confirm, rather than starting cold.
+The first question is simple: is this a **brand surface** or a **product surface**?
+
+- **Brand surface:** marketing site, landing page, campaign, portfolio. The impression is the product.
+- **Product surface:** app UI, dashboard, admin, workflow tool. The design helps someone finish a task.
+
+The docs call this choice **register**. It changes the defaults Impeccable uses for type, color, density, and motion. See [Brand vs product](/tutorials/brand-vs-product) for examples. Init forms a hypothesis from your codebase and asks you to confirm it.
 
 Then a handful of shorter questions:
 
@@ -59,15 +72,15 @@ Then a handful of shorter questions:
 - **Any visual references?** Named brands, products, or printed objects, not adjectives. "Klim Type Foundry specimen pages", not "technical and clean".
 - **Anti-references?** Things the product should explicitly not look like, equally named.
 
-Answer in your own words. The skill writes `PRODUCT.md` with the answers. Every future command run reads it automatically.
+Answer in your own words. The skill writes `PRODUCT.md` with the answers, and every future command reads it automatically.
 
 Open `PRODUCT.md` and read what it wrote. Edit anything that does not feel right. The file is yours.
 
 ## Step 2.5. Capture the visual system
 
-At the end of `/impeccable init`, the skill offers to run `/impeccable document` for you. Say yes. It scans your tokens (CSS custom properties, Tailwind config, CSS-in-JS themes), extracts colors and typography, asks one grouped question for the parts that need creative input (a Creative North Star, descriptive color names), and writes a `DESIGN.md` that follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
+At the end of `/impeccable init`, the skill offers to run `/impeccable document` for you. Say yes. It looks at your existing colors, type, components, and tokens, then writes `DESIGN.md` in the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/).
 
-On a fresh project with no tokens yet, document runs in seed mode: five quick questions about color strategy, type direction, and motion energy, and writes a scaffold you can refresh once there is code.
+On a fresh project with no visual system yet, document asks a few setup questions and writes a starting scaffold. Refresh it once there is real code.
 
 `PRODUCT.md` carries strategy (who, what, why). `DESIGN.md` carries visuals (colors, typography, components). Every command reads both before generating.