@W-22799934: Onboarding walkthrough

packages/b2c-vs-extension/media/walkthrough/.vscode-walkthrough-reference.md

@@ -0,0 +1,320 @@
+# VS Code Walkthrough Quick Reference
+
+This document provides technical reference for maintaining and extending the B2C DX walkthrough.
+
+## VS Code Walkthrough API
+
+### Package.json Structure
+
+```json
+{
+  "contributes": {
+    "walkthroughs": [
+      {
+        "id": "unique.walkthrough.id",
+        "title": "Display Title",
+        "description": "Short description shown in welcome page",
+        "when": "context-condition",
+        "steps": [...]
+      }
+    ]
+  }
+}
+```
+
+### Step Structure
+
+```json
+{
+  "id": "unique.step.id",
+  "title": "Step Title",
+  "description": "Markdown content with [links](command:commandId)",
+  "media": {
+    "markdown": "path/to/file.md"
+    // OR
+    "image": "path/to/image.png",
+    "altText": "Accessible description"
+  },
+  "completionEvents": [
+    "onCommand:commandId",
+    "onView:viewId",
+    "onContext:contextKey"
+  ]
+}
+```
+
+## Completion Events
+
+### Available Event Types
+
+| Event Type | Syntax | Example | When It Fires |
+|------------|--------|---------|---------------|
+| Command | `onCommand:id` | `onCommand:b2c-dx.codeSync.deploy` | When command executes |
+| View Open | `onView:id` | `onView:b2cWebdavExplorer` | When view becomes visible |
+| Context | `onContext:key` | `onContext:workspaceContains:dw.json` | When context becomes true |
+| Link | `onLink:uri` | `onLink:https://example.com` | When link is clicked |
+
+### Common Context Keys
+
+- `workspaceContains:pattern` - File matching pattern exists
+- `editorLangId == language` - Active editor language
+- `resourceExtname == .ext` - File extension matches
+- Custom contexts set via `vscode.commands.executeCommand('setContext', key, value)`
+
+## Command Links in Markdown
+
+### Basic Command Link
+```markdown
+[Link Text](command:commandId)
+```
+
+### Command with Arguments
+Arguments must be URL-encoded JSON:
+```markdown
+[Open File](command:workbench.action.quickOpen?%22filename.json%22)
+```
+
+To encode arguments:
+```javascript
+const args = ["filename.json"];
+const encoded = encodeURIComponent(JSON.stringify(args));
+// Use: command:commandId?${encoded}
+```
+
+### Common Built-in Commands
+
+| Command | Description |
+|---------|-------------|
+| `workbench.action.quickOpen?args` | Open Quick Open with pre-filled text |
+| `workbench.action.openWalkthrough` | Open a specific walkthrough |
+| `workbench.view.extension.id` | Open extension view container |
+| `workbench.action.openSettings` | Open settings |
+| `workbench.action.files.openFile` | Open file picker |
+
+## Media Types
+
+### Markdown Media
+Best for text-heavy steps with formatting needs:
+```json
+{
+  "media": {
+    "markdown": "path/to/content.md"
+  }
+}
+```
+
+**Pros:**
+- Rich formatting (headings, lists, code blocks)
+- Easy to maintain and update
+- No image assets needed
+- Command links work naturally
+
+**Cons:**
+- Less visual than images
+- Can be text-heavy
+
+### Image Media
+Best for visual demonstrations:
+```json
+{
+  "media": {
+    "image": "path/to/image.png",
+    "altText": "Descriptive text for screen readers"
+  }
+}
+```
+
+**Pros:**
+- Highly visual
+- Quick to understand
+- Professional appearance
+
+**Cons:**
+- Requires image creation/maintenance
+- Can become outdated
+- Larger file sizes
+
+### SVG Media
+Best for diagrams and scalable graphics:
+```json
+{
+  "media": {
+    "svg": "path/to/diagram.svg",
+    "altText": "Descriptive text"
+  }
+}
+```
+
+**Pros:**
+- Scalable (no pixelation)
+- Small file size
+- Can be version-controlled easily
+- Can include text
+
+### Video Media (Experimental)
+```json
+{
+  "media": {
+    "video": "path/to/video.mp4"
+  }
+}
+```
+
+## Conditional Display
+
+### When Clause
+Controls when walkthrough appears:
+
+```json
+{
+  "when": "workspaceFolderCount > 0"
+}
+```
+
+Common conditions:
+- `workspaceFolderCount > 0` - Workspace is open
+- `!isWeb` - Not running in browser
+- `extensionId:installed` - Another extension is installed
+
+### Step Visibility
+Currently, steps cannot be conditionally hidden. All steps show in sequence.
+
+**Workaround:** Use description text to explain prerequisites:
+```markdown
+**Note:** This step requires OAuth credentials. If you skipped Step 3, come back later.
+```
+
+## Best Practices
+
+### Content Guidelines
+
+1. **Keep steps focused** - One main action per step
+2. **Use active voice** - "Deploy your cartridge" not "Cartridges can be deployed"
+3. **Provide context** - Explain *why* not just *how*
+4. **Include examples** - Code snippets, sample configs
+5. **Add troubleshooting** - Common errors and solutions
+
+### Writing Descriptions
+
+```markdown
+# Good
+Configure your instance by creating a `dw.json` file.
+
+[Create dw.json](command:b2c-dx.walkthrough.createDwJson)
+
+**Tip:** Add dw.json to .gitignore to avoid committing credentials.
+
+# Less Good
+You need to configure your instance. Click the button to create a file.
+```
+
+### Completion Events
+
+**Do:**
+- Use clear, specific events
+- Test completion triggers
+- Provide multiple completion paths if possible
+
+**Don't:**
+- Rely on events that might not trigger
+- Use too many completion events (makes step too easy to complete by accident)
+- Use events from commands that might fail
+
+### Accessibility
+
+1. **Always provide altText** for images
+2. **Use semantic markdown** (headings, lists)
+3. **Don't rely only on color** to convey information
+4. **Test with screen readers** if possible
+5. **Keep command links descriptive** (not "click here")
+
+## Testing Checklist
+
+- [ ] Build extension without errors
+- [ ] Walkthrough appears in Welcome screen
+- [ ] All steps load without errors
+- [ ] Markdown renders correctly
+- [ ] Command links work
+- [ ] Completion events trigger correctly
+- [ ] Images load (if using images)
+- [ ] AltText is descriptive
+- [ ] Content is accurate and up-to-date
+- [ ] Links to external resources work
+- [ ] Tested in Extension Development Host
+
+## Debugging
+
+### Extension Host Console
+View walkthrough errors:
+1. Help → Toggle Developer Tools
+2. Console tab
+3. Look for walkthrough-related errors
+
+### Common Issues
+
+**"Walkthrough not found"**
+- Check walkthrough ID matches exactly
+- Verify package.json is valid JSON
+- Rebuild extension
+
+**"Step media not loading"**
+- Check file path is relative to extension root
+- Verify markdown file exists
+- Check for typos in path
+
+**"Completion events not firing"**
+- Verify command ID exists in package.json
+- Check context key syntax
+- Test event manually
+
+**"Command link does nothing"**
+- Verify command is registered
+- Check URL encoding of arguments
+- Look for errors in Extension Host console
+
+## Internationalization (i18n)
+
+Currently not implemented, but can be added:
+
+```json
+{
+  "title": "%walkthrough.title%",
+  "description": "%walkthrough.description%"
+}
+```
+
+With corresponding `package.nls.json`:
+```json
+{
+  "walkthrough.title": "Get Started with B2C Commerce",
+  "walkthrough.description": "Learn the basics in 30 minutes"
+}
+```
+
+## Performance Considerations
+
+- Markdown files are loaded lazily (only when step is viewed)
+- Images are cached by VS Code
+- Large images (>500KB) may slow initial load
+- Keep GIFs under 2MB if possible
+- Consider using SVG for diagrams
+
+## Version Compatibility
+
+- **Walkthroughs API**: VS Code 1.56.0+ (May 2021)
+- **Completion events**: VS Code 1.56.0+
+- **Link events**: VS Code 1.58.0+
+- **Video support**: Experimental, not recommended
+
+Current engine requirement: `^1.105.1`
+
+## Resources
+
+- [VS Code Walkthrough API Docs](https://code.visualstudio.com/api/references/contribution-points#contributes.walkthroughs)
+- [VS Code Extension Samples](https://github.com/microsoft/vscode-extension-samples/tree/main/getting-started-sample)
+- [GitHub Flavored Markdown Spec](https://github.github.com/gfm/)
+- [VS Code Built-in Commands](https://code.visualstudio.com/api/references/commands)
+
+---
+
+**Last Updated:** 2026-04-28