Improve docs starter experience

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.