Improve developer and author getting-started guidance

.mcp.json

@@ -0,0 +1,26 @@
+{
+	"mcpServers": {
+		"dropins": {
+			"type": "local",
+			"command": "npx",
+			"args": [
+				"--yes",
+				"@dropins/ai-tools"
+			],
+			"tools": [
+				"*"
+			]
+		},
+		"playwright": {
+			"type": "local",
+			"command": "npx",
+			"args": [
+				"-y",
+				"@playwright/mcp@latest"
+			],
+			"tools": [
+				"*"
+			]
+		}
+	}
+}

.scout/scout.config.yaml

@@ -0,0 +1,16 @@
+# Scout per-repo config template.
+#
+# Seeded into `<repo>/.scout/scout.config.yaml` by `scout attach` when the
+# repo has no config yet.  Templates here only carry the repo-specific
+# ignore / dampen / boost / tune overrides; defaults for
+# repository/markdown/ranking/index/projects are filled in at load time.
+ignore:
+  - '**/CHANGELOG.md'
+  - '**/CHANGELOG*'
+  - '**/CHANGES.md'
+  - '**/HISTORY.md'
+
+dampen:
+  - factor: 0.3
+    patterns:
+      - '**/package.json'

.vscode/mcp.json

@@ -1,14 +1,4 @@
 {
   "servers": {
-    "playwright": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@playwright/mcp@latest"]
-    },
-    "dropins": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["--yes", "@dropins/ai-tools"]
-    }
   }
 }

CONTRIBUTING.md

@@ -586,6 +586,16 @@ import TableWrapper from '@components/TableWrapper.astro';
 - Include both light and dark mode versions when possible
 - Keep file sizes reasonable (< 1MB for screenshots)
 
+### Diagrams in dark mode
+
+For a simple diagram with a white background and dark labels, add the `adaptColors` prop to its `<Diagram>` component. The component uses the same image in both themes. It slightly increases contrast in light mode and changes the white background to dark gray in dark mode. The zoomed image follows the same colors, and print uses the light appearance.
+
+Use this option only after checking the image in both themes and in the zoomed view. Filters change every pixel, so do not use it for screenshots, photographs, or diagrams that require exact colors. Mermaid diagrams are unchanged.
+
+Check normal text for a contrast ratio of at least 4.5:1 against its background. Meaningful lines and icons need at least 3:1. The filter does not guarantee that every diagram meets these Web Content Accessibility Guidelines (WCAG) contrast requirements. If colors still fail, adjust the source diagram or use a separately designed dark version.
+
+With the local development server running, use `node scripts/test-diagram-colors.mjs` to check the author diagram's source colors, theme switching, zoom, print, and mobile layout in Chromium. This check covers the sampled colors, not full WCAG conformance.
+
 ### Screenshots
 
 **Best Practices:**
@@ -1074,4 +1084,3 @@ For questions about this guide or documentation processes, contact:
 
 _Last updated: [Current Date]_
 _Version: 1.0_
-

astro.sidebar.mjs

@@ -25,16 +25,17 @@ export function generateSidebar() {
           collapsed: false,
           items: [
             { label: 'Overview', link: '/get-started/' },
-            { label: 'Prerequisites', link: '/get-started/before-you-start/' },
-            { label: 'Backend options', link: '/get-started/backends/' },
             { label: 'Create a storefront', link: '/get-started/create-storefront/' },
+            { label: 'Run your storefront locally', link: '/get-started/run-locally/' },
+            { label: 'Make your first change', link: '/get-started/first-change/' },
+            { label: 'Install the AI tools', link: '/ai/' },
+            { label: 'Make a change with AI', link: '/ai/develop-with-ai/' },
           ],
         },
         {
-          label: 'AI tools',
-          collapsed: false,
+          label: 'AI tools reference',
+          collapsed: true,
           items: [
-            { label: 'Install the AI tools', link: '/ai/' },
             { label: 'Boilerplate skills', link: '/ai/boilerplate-skills/' },
             { label: 'Dropins AI tools', link: '/ai/dropins-ai-tools/' },
             { label: 'Wayfinder', link: '/ai/wayfinder/' },
@@ -56,6 +57,16 @@ export function generateSidebar() {
             { label: 'Event bus', link: '/dropins/all/events/' },
           ],
         },
+        {
+          label: 'Project setup',
+          collapsed: true,
+          items: [
+            { label: 'Prerequisites', link: '/get-started/before-you-start/' },
+            { label: 'Backend options', link: '/get-started/backends/' },
+            { label: 'Storefront configuration', link: '/setup/configuration/commerce-configuration/' },
+            { label: 'Verify your storefront setup', link: '/get-started/verify-setup/' },
+          ],
+        },
         {
           label: 'Boilerplate',
           collapsed: true,
@@ -124,7 +135,6 @@ export function generateSidebar() {
           collapsed: true,
           items: [
             { label: 'Overview', link: '/setup/configuration/' },
-            { label: 'Storefront configuration', link: '/setup/configuration/commerce-configuration/' },
             {
               label: 'Compatibility Package',
               collapsed: true,