diff --git a/.orchestrator/architecture-summary.md b/.orchestrator/architecture-summary.md
new file mode 100644
index 000000000..c040593cd
--- /dev/null
+++ b/.orchestrator/architecture-summary.md
@@ -0,0 +1,158 @@
+# Admin SDK Tutorial Prototype — Architecture Summary
+
+## What we built
+
+We built a prototype package at `packages/admin-sdk-tutorial` that demonstrates an interactive, browser-based learning flow for the Meteor Admin SDK.
+
+The prototype includes:
+
+- a split tutorial layout with lesson content on the left
+- an in-browser code editor on the right
+- a dummy admin preview shell
+- a small mocked Admin SDK bridge
+- browser-side code execution for learner input
+- three end-to-end lessons:
+ - notifications
+ - menu items
+ - locations / positions
+
+## Main architecture pieces
+
+### 1. Tutorial shell
+
+The app shell lives in `App.vue` and coordinates:
+
+- active lesson selection
+- current editor code
+- reset/run state
+- runtime state for the preview
+- execution feedback for the output panel
+
+### 2. Lesson model
+
+Lesson content is currently hardcoded in `src/lessons/lessons.ts` and typed in `src/types/lesson.ts`.
+
+Each lesson defines:
+
+- title and summary
+- explanatory description
+- learning objective
+- starter code
+- preview/output labels
+
+### 3. Editor layer
+
+The editor is intentionally lightweight:
+
+- `CodeEditorPanel.vue`
+- single-file editing (`main.ts` affordance)
+- textarea-based input
+- reset and run controls
+
+This keeps the prototype simple while proving the interaction model.
+
+### 4. Dummy admin runtime
+
+The preview is rendered through:
+
+- `PreviewPanel.vue`
+- `DummyAdminShell.vue`
+
+The dummy admin visualizes:
+
+- notifications
+- navigation entries
+- extension surfaces / positions
+
+It is not intended to mirror the real Shopware Administration UI exactly. It is designed to teach concepts with minimal visual noise.
+
+### 5. Runtime state model
+
+Preview state is represented as structured runtime data in `src/types/runtime.ts` and initialized through `src/runtime/createRuntimeState.ts`.
+
+This separates:
+
+- lesson content
+- runtime/UI state
+- execution behavior
+
+### 6. Mock Admin SDK bridge
+
+`src/runtime/sdkBridge.ts` provides a narrow bridge API for the prototype:
+
+- `sdk.notification.dispatch(...)`
+- `sdk.menu.add(...)`
+- `sdk.location.render(...)`
+
+Instead of talking to a real admin host, these methods mutate the dummy runtime state.
+
+### 7. Code execution flow
+
+`src/runtime/executeLessonCode.ts` executes learner code in the browser using a constrained runtime approach.
+
+The flow is:
+
+1. reset runtime state for the active lesson
+2. execute learner code with access to the mock `sdk`
+3. update preview from bridge mutations
+4. show success/error feedback in the output panel
+
+## Why this structure works
+
+This prototype architecture is useful because it keeps responsibilities separate:
+
+- lessons define teaching content
+- the editor manages learner input
+- execution runs user code
+- the bridge translates API calls into state changes
+- the preview only renders runtime state
+
+That makes it easier to evolve the prototype without tightly coupling everything together.
+
+---
+
+# What a second pass could look like
+
+## UX and visual polish
+
+- make the dummy admin feel more product-like while staying minimal
+- improve typography, spacing, and hierarchy
+- reduce duplicated information between toast, empty state, and output areas
+- improve mobile ergonomics further
+
+## Editor improvements
+
+- replace textarea with a richer code editor
+- support locked/editable regions
+- add inline hints or lesson tasks
+- add formatting or syntax highlighting
+
+## Better execution model
+
+- move from naive `Function(...)` execution to a safer constrained execution layer
+- support more structured lesson scaffolds
+- capture richer runtime diagnostics
+
+## Stronger lesson system
+
+- add validation rules per lesson
+- define expected outcomes instead of only freeform execution
+- move lesson content into markdown/MDX or another authoring format
+
+## More realistic SDK teaching
+
+- expand the bridge with more Admin SDK APIs
+- add more realistic host events and state transitions
+- simulate communication patterns more explicitly
+
+## Better preview fidelity
+
+- represent locations and positions with more accurate conceptual models
+- add clearer UI states for registered menu items and notifications
+- introduce optional “host frame vs extension frame” visualization if needed
+
+## Productization path
+
+- decide whether this should remain a package app or move into a dedicated docs/tutorial surface
+- define how the tutorial would integrate with Admin SDK documentation
+- add analytics/progress only if the concept is validated first
diff --git a/.orchestrator/final-architecture-summary.md b/.orchestrator/final-architecture-summary.md
new file mode 100644
index 000000000..9052c1056
--- /dev/null
+++ b/.orchestrator/final-architecture-summary.md
@@ -0,0 +1,93 @@
+# Admin SDK Tutorial Prototype — Final Architecture Summary
+
+## What the prototype now does
+
+The tutorial prototype now runs the **real Meteor Admin SDK** inside lesson iframes and uses a **dummy admin host shell** in the parent app to handle the resulting postMessage traffic.
+
+This means the learner-facing code is no longer powered by a fake SDK bridge for the main lessons.
+
+## Runtime architecture
+
+### 1. Parent app = tutorial shell + dummy host
+
+The main Vue app is responsible for:
+
+- lesson selection
+- editor state
+- preview shell UI
+- output/status UI
+- host-side Admin SDK handler registration
+- simplified dummy admin state rendering
+
+### 2. Lesson runtime = real iframe context
+
+Each lesson run is executed in an iframe runtime that:
+
+- imports the real `@shopware-ag/meteor-admin-sdk`
+- receives lesson code from the parent
+- executes that code in an iframe context
+- communicates with the parent through real SDK `postMessage` traffic
+
+### 3. Host-side handler layer
+
+The parent host listens for and handles real SDK messages, including:
+
+- `__registerWindow__`
+- `notificationDispatch`
+- `menuItemAdd`
+- `uiComponentSectionRenderer`
+- `locationUpdateHeight`
+
+These handlers translate SDK messages into simplified dummy-admin UI state.
+
+## Lesson architecture
+
+### Notifications
+
+- learner code uses the real notification API shape
+- iframe sends real notification traffic
+- host renders the notification in the dummy admin shell
+
+### Menu items
+
+- learner code uses `ui.menu.addMenuItem(...)`
+- iframe sends real menu registration traffic
+- host updates dummy sidebar navigation
+
+### Locations / positions
+
+- learner code uses real concepts like:
+ - `location.MAIN_HIDDEN`
+ - `ui.componentSection.add(...)`
+ - `location.is(...)`
+ - `location.updateHeight(...)`
+- host renders simplified extension surfaces
+- matching location iframes are mounted into the chosen host slot
+
+## UI architecture
+
+The visible tutorial experience has four main parts:
+
+- tutorial sidebar
+- real code editor
+- dummy admin preview shell
+- output/status panel
+
+The preview uses a landscape-oriented host frame so the dummy admin feels closer to a real monitor-based admin environment.
+
+## Current strengths
+
+- real SDK package is used for the main lessons
+- real iframe/host message flow is in place
+- simplified host shell is enough to teach the concepts clearly
+- success/error states are visible to the learner
+- desktop and mobile layouts both work
+
+## Remaining minor quirks
+
+- the iframe runtime display can still show slightly imperfect code text across repeated runs
+- some preserved error-state visuals could still be polished further
+
+## Bottom line
+
+The prototype now teaches the Admin SDK with a **real runtime architecture** and a **simplified host UI**, rather than only simulating the API surface.
diff --git a/.orchestrator/implementation-brief.md b/.orchestrator/implementation-brief.md
new file mode 100644
index 000000000..0ffc22018
--- /dev/null
+++ b/.orchestrator/implementation-brief.md
@@ -0,0 +1,246 @@
+# Interactive Admin SDK Tutorial Prototype — Implementation Brief
+
+## Goal
+
+Build a first interactive prototype for learning the Meteor Admin SDK inside this monorepo.
+
+The prototype should:
+
+- be inspired by the Solid tutorial split layout
+- not depend on TutorialKit or StackBlitz
+- run entirely in the browser
+- let the user edit code live
+- execute that code against a minimal dummy admin runtime
+- focus on understanding Admin SDK concepts, not replicating the full Shopware Administration UI
+
+## Confirmed Direction
+
+- **Deliverable:** clickable UI prototype
+- **Monorepo placement preference:** additional package/app in the repo
+- **Coding experience:** real editable code running in-browser
+- **Initial lesson topics:** notifications, menu items, locations/positions
+- **Layout direction:** Solid-like split layout
+- **Dummy admin fidelity:** minimal wireframe / lightweight UI
+- **Process:** implementation brief first, then approval before coding
+
+## Product Intent
+
+The user should learn Admin SDK concepts by writing code directly in the browser and immediately seeing how the dummy admin reacts.
+
+The dummy admin should be deliberately minimal. It only needs enough UI and behavior so learners understand concepts like:
+
+- triggering notifications
+- adding navigation or menu items
+- rendering content into locations / positions
+
+For locations and position IDs, a simplified visualization is sufficient, e.g. cards with clearly labeled iframe-like surfaces.
+
+## Monorepo Placement
+
+The user explicitly chose:
+
+`packages/admin-sdk-tutorial`
+
+Even though `examples/` would also fit a prototype app, all implementation work should now assume the tutorial lives under `packages/`.
+
+## Suggested Stack
+
+- Vue 3
+- Vite
+- TypeScript
+- optional reuse of `@shopware-ag/meteor-component-library` for selected UI pieces
+- reuse/reference of `@shopware-ag/meteor-admin-sdk` where helpful, but mock runtime behavior locally for the prototype
+
+## Prototype Scope
+
+This first prototype should prove the overall learning experience, not solve the full long-term platform.
+
+### Included
+
+- split-screen tutorial shell
+- lesson/navigation panel on the left
+- in-browser code editor on the right
+- live preview area on the right
+- minimal dummy admin runtime
+- mocked Admin SDK behavior for the first concepts
+- three prototype lessons/steps
+
+### Excluded for now
+
+- full production authoring system
+- persistent learner progress
+- backend services or storage
+- full Shopware Administration embedding
+- full Admin SDK API coverage
+- general-purpose WebContainer-like project sandbox
+- production-grade assessment engine
+
+## Proposed UX Structure
+
+## Layout
+
+- **Left column**
+ - lesson title
+ - explanation/content
+ - step navigation
+ - hints / expected outcome
+- **Right column**
+ - editor tabs or a compact single-file editor
+ - live preview of the dummy admin
+ - optional output/console panel
+
+## Lessons for the Prototype
+
+### 1. Notifications
+
+Learner writes code that triggers a notification.
+
+Preview behavior:
+
+- display a toast/message area in the dummy admin
+- show notification type and text clearly
+
+### 2. Menu items
+
+Learner writes code that adds a menu item.
+
+Preview behavior:
+
+- update a fake navigation/sidebar area
+- make the new item visible and understandable immediately
+
+### 3. Locations / positions
+
+Learner writes code that targets extension surfaces.
+
+Preview behavior:
+
+- show simplified location containers
+- use cards/panels with labeled slots
+- visually communicate which content lands in which location/position
+
+## Proposed Technical Architecture
+
+### 1. Tutorial Shell
+
+A dedicated app that renders:
+
+- lesson content
+- active step metadata
+- editor state
+- preview state
+
+For the prototype, lesson content can be hardcoded in TypeScript/JSON rather than introducing a full content pipeline.
+
+### 2. Editor Layer
+
+For the prototype, keep the editing model intentionally small:
+
+- preferably a single editable file per lesson (e.g. `main.ts` or `lesson.ts`)
+- support reset to initial state
+- optionally support small locked/unlocked regions later
+
+### 3. Execution / Sandbox Layer
+
+Run learner code entirely in the browser.
+
+Recommended approach for the prototype:
+
+- sandbox the preview in an iframe
+- inject a controlled runtime/mock bridge
+- execute only the code needed for the lesson environment
+
+Avoid building a fully generic multi-file browser IDE at this stage.
+
+### 4. Dummy Admin Runtime
+
+Build a minimal fake admin shell that exposes only the UI surfaces needed by the lessons.
+
+Suggested UI primitives:
+
+- sidebar / navigation list
+- header or toolbar area
+- notification area
+- content cards/panels
+- labeled extension slots / pseudo-iframes
+
+The visual language should remain lightweight and instructional, not a copy of the real Shopware UI.
+
+### 5. Mock Admin SDK Bridge
+
+Provide a thin compatibility layer so learner code can call familiar APIs while the prototype runtime translates those calls into dummy admin UI updates.
+
+Core initial behaviors:
+
+- create/show notifications
+- register/add menu items
+- register/render content into named locations/positions
+
+## Architectural Principles
+
+- optimize for teaching clarity over visual realism
+- keep the runtime deterministic and easy to inspect
+- prefer a constrained lesson environment over a generic platform
+- keep lessons small and focused
+- make the relation between learner code and UI result obvious
+
+## Key Open Decisions / Risks
+
+### 1. Placement: `examples/` vs `packages/`
+
+The current repo structure suggests `examples/` is the best fit for a prototype app, even though the initial idea mentioned an additional package.
+
+### 2. Fidelity of the mock SDK
+
+We need to decide how closely the prototype runtime should mirror the real Admin SDK.
+
+Recommendation:
+
+- keep it minimal for now
+- stay semantically close where easy
+- avoid early overinvestment in API parity
+
+### 3. Editor scope
+
+Single-file editing is the fastest way to validate the tutorial concept.
+
+Recommendation:
+
+- start with single-file editing
+- add multi-file support only if it becomes necessary for lesson clarity
+
+### 4. Browser execution complexity
+
+A fully general code execution environment can become expensive quickly.
+
+Recommendation:
+
+- use a narrowly scoped execution model for prototype lessons
+- do not emulate a full project sandbox yet
+
+## Recommended Build Plan
+
+1. create the prototype app in the monorepo
+2. implement the split tutorial shell
+3. add a minimal browser editor
+4. add sandboxed preview execution
+5. build the dummy admin shell
+6. implement mock Admin SDK actions for notifications, menu items, and locations/positions
+7. create three prototype lessons
+8. polish interaction and visual clarity
+
+## Working Assumptions for Subagents
+
+- This is a **prototype**, not a production tutorial system.
+- The UI should be **minimal and instructional**.
+- The result should feel close to the **Solid tutorial interaction model**.
+- The learner must be able to **edit code directly in the browser**.
+- Everything should happen **client-side in the browser**.
+- Avoid introducing dependencies on StackBlitz/TutorialKit/WebContainer-style infrastructure.
+- Prefer the existing monorepo conventions and lightweight reuse over building a large new framework.
+
+## Confirmed Package Target
+
+Proceed with implementation in:
+
+`packages/admin-sdk-tutorial`
diff --git a/.orchestrator/implementation-plan.md b/.orchestrator/implementation-plan.md
new file mode 100644
index 000000000..8acc75b71
--- /dev/null
+++ b/.orchestrator/implementation-plan.md
@@ -0,0 +1,720 @@
+# Interactive Admin SDK Tutorial Prototype — Implementation Plan
+
+## Plan Context
+
+- The prototype must live under `packages/`
+- Recommended target package: `packages/admin-sdk-tutorial`
+- The work is intentionally split into very small executable tasks
+- Each task should be scoped to roughly **5 minutes or less**
+- This plan is optimized for delegation to subagents
+
+## Execution Rules
+
+- Complete tasks in order unless explicitly marked parallelizable
+- Keep each task narrowly scoped
+- Prefer visible progress over early abstraction
+- Do not expand scope beyond the prototype goals in `implementation-brief.md`
+
+---
+
+## Phase 1 — Package Setup
+
+### 1.1 Create package folder structure
+- Create `packages/admin-sdk-tutorial`
+- Create initial `src/` folder
+- Create placeholder folders for `components/`, `lessons/`, `runtime/`, and `types/`
+
+### 1.2 Add package manifest
+- Create `packages/admin-sdk-tutorial/package.json`
+- Set package name
+- Mark package as private if appropriate for prototype stage
+- Add initial scripts (`dev`, `build`, `preview`, `typecheck`)
+
+### 1.3 Add TypeScript config
+- Create local `tsconfig.json`
+- Align with repo conventions where possible
+
+### 1.4 Add Vite config
+- Create `vite.config.ts`
+- Enable Vue support
+
+### 1.5 Add app HTML entry
+- Create `index.html`
+- Add root mount element
+
+### 1.6 Add source entrypoint
+- Create `src/main.ts`
+- Mount the root Vue app
+
+### 1.7 Add root app component
+- Create `src/App.vue`
+- Render simple placeholder text to confirm bootstrapping
+
+### 1.8 Register workspace dependencies
+- Add initial dependencies and devDependencies
+- Use workspace references where needed
+
+### 1.9 Ensure package is included by workspace conventions
+- Verify no extra workspace configuration is required
+- Confirm package path matches monorepo patterns
+
+---
+
+## Phase 2 — Prototype Shell
+
+### 2.1 Replace placeholder with split layout shell
+- Create left and right column layout in `App.vue`
+- Add semantic container sections
+
+### 2.2 Add base shell styling
+- Add initial layout CSS
+- Ensure full-height app shell works
+
+### 2.3 Create lesson sidebar component
+- Add `src/components/TutorialSidebar.vue`
+- Render title, description, and step list placeholders
+
+### 2.4 Create workspace panel component
+- Add `src/components/TutorialWorkspace.vue`
+- Render editor and preview placeholders
+
+### 2.5 Wire shell components into root app
+- Replace inline layout with reusable components
+
+### 2.6 Add mobile-safe fallback layout behavior
+- Add basic responsive stacking behavior
+- Do not over-polish yet
+
+---
+
+## Phase 3 — Lesson Data Model
+
+### 3.1 Create lesson type definitions
+- Add `src/types/lesson.ts`
+- Define minimal lesson and step interfaces
+
+### 3.2 Create prototype lesson data file
+- Add `src/lessons/lessons.ts`
+- Seed three lessons: notifications, menu items, locations/positions
+
+### 3.3 Add active lesson state in app shell
+- Store selected lesson/step in root state
+
+### 3.4 Render lesson metadata in sidebar
+- Show active title, summary, and step list
+
+### 3.5 Add lesson switching behavior
+- Enable click-to-select lesson/step
+
+### 3.6 Add reset-on-lesson-change behavior
+- Reset editor/preview state when changing lessons
+
+---
+
+## Phase 4 — Editor Prototype
+
+### 4.1 Create editor component shell
+- Add `src/components/CodeEditorPanel.vue`
+- Render labeled editor area placeholder
+
+### 4.2 Add editable text area as first editor
+- Use a textarea-based implementation first
+- Do not introduce a heavy editor dependency yet
+
+### 4.3 Bind editor to lesson starter code
+- Load starter code for active lesson
+
+### 4.4 Add local editor state updates
+- Keep current code reactive
+
+### 4.5 Add reset button
+- Reset editor content back to lesson starter code
+
+### 4.6 Add basic file/tab affordance
+- Show a single file name like `main.ts`
+- Keep actual editing single-file only
+
+---
+
+## Phase 5 — Preview Shell
+
+### 5.1 Create preview container component
+- Add `src/components/PreviewPanel.vue`
+- Render preview header and placeholder body
+
+### 5.2 Add dummy admin shell component
+- Add `src/components/DummyAdminShell.vue`
+- Render simple nav, content area, and notification region
+
+### 5.3 Add preview composition
+- Mount dummy admin shell inside preview panel
+
+### 5.4 Add output/status area
+- Render a small status or output region below preview
+
+### 5.5 Add empty-state messaging
+- Show friendly message before first successful run if needed
+
+---
+
+## Phase 6 — Runtime State Model
+
+### 6.1 Create runtime type definitions
+- Add `src/types/runtime.ts`
+- Define notification, menu item, and location state types
+
+### 6.2 Create runtime state factory
+- Add `src/runtime/createRuntimeState.ts`
+- Return initial empty runtime state
+
+### 6.3 Add runtime state to root app
+- Store active preview/runtime state at app level
+
+### 6.4 Pass runtime state into preview shell
+- Bind reactive runtime state into dummy admin UI
+
+### 6.5 Add runtime reset helper
+- Reset runtime to lesson defaults before each run
+
+---
+
+## Phase 7 — Mock Admin SDK Bridge
+
+### 7.1 Create bridge module skeleton
+- Add `src/runtime/sdkBridge.ts`
+- Export minimal bridge factory
+
+### 7.2 Add notification API surface
+- Implement method(s) for creating notifications
+
+### 7.3 Add menu item API surface
+- Implement method(s) for registering menu items
+
+### 7.4 Add location registration API surface
+- Implement method(s) for registering location content
+
+### 7.5 Connect bridge methods to runtime state
+- Ensure bridge mutates preview state deterministically
+
+### 7.6 Add bridge reset behavior
+- Ensure each execution starts cleanly
+
+---
+
+## Phase 8 — In-Browser Execution
+
+### 8.1 Create execution module skeleton
+- Add `src/runtime/executeLessonCode.ts`
+- Define a narrow execution entrypoint
+
+### 8.2 Define execution input contract
+- Pass current code and bridge/runtime context into executor
+
+### 8.3 Implement first naive evaluation flow
+- Use a constrained prototype approach suitable for the current lesson code shape
+
+### 8.4 Capture runtime errors
+- Return execution errors instead of crashing the app
+
+### 8.5 Trigger execution from UI
+- Add a Run button or initial autorun behavior
+
+### 8.6 Reset runtime before execution
+- Ensure each run starts from fresh lesson state
+
+### 8.7 Surface errors in output panel
+- Show readable execution error messages
+
+---
+
+## Phase 9 — Notifications Lesson
+
+### 9.1 Add notification lesson starter code
+- Seed realistic starter code for notification concept
+
+### 9.2 Add notification lesson text
+- Explain the concept and expected result
+
+### 9.3 Render notifications in dummy admin
+- Show toast/message items in preview
+
+### 9.4 Verify notification code path
+- Ensure starter code produces visible result
+
+### 9.5 Refine notification visuals
+- Make the result easy to understand at a glance
+
+---
+
+## Phase 10 — Menu Items Lesson
+
+### 10.1 Add menu item lesson starter code
+- Seed realistic starter code for menu registration
+
+### 10.2 Add menu item lesson text
+- Explain what the learner should observe
+
+### 10.3 Render menu items in dummy sidebar
+- Show registered menu items in navigation area
+
+### 10.4 Verify menu registration code path
+- Ensure the preview updates correctly
+
+### 10.5 Refine menu visuals
+- Make added items visually distinct from static shell UI
+
+---
+
+## Phase 11 — Locations / Positions Lesson
+
+### 11.1 Add locations lesson starter code
+- Seed starter code for location/position behavior
+
+### 11.2 Add locations lesson text
+- Explain named slots and why they matter
+
+### 11.3 Add labeled location containers to dummy admin
+- Render two or more clear extension surfaces
+
+### 11.4 Render registered location content
+- Show learner-defined content inside the correct surface
+
+### 11.5 Verify positions concept visually
+- Make placement obvious without copying full Shopware UI
+
+### 11.6 Refine location card visuals
+- Improve labels and boundaries for comprehension
+
+---
+
+## Phase 12 — UX Polish
+
+### 12.1 Add lesson progress affordance
+- Show current lesson/step state clearly
+
+### 12.2 Improve shell spacing and typography
+- Make the tutorial easier to scan
+
+### 12.3 Improve button labels and helper text
+- Reduce ambiguity in controls
+
+### 12.4 Improve preview empty/error states
+- Make failure and reset flows understandable
+
+### 12.5 Add minimal branding alignment
+- Keep visuals lightweight and consistent with repo context
+
+---
+
+## Phase 13 — Verification
+
+### 13.1 Start dev app and verify boot
+- Confirm the package runs locally
+
+### 13.2 Verify lesson switching
+- Confirm editor and preview state update correctly
+
+### 13.3 Verify notifications lesson manually
+- Confirm learner edits affect preview
+
+### 13.4 Verify menu items lesson manually
+- Confirm learner edits affect preview
+
+### 13.5 Verify locations lesson manually
+- Confirm learner edits affect preview
+
+### 13.6 Verify responsive layout manually
+- Check desktop and narrow viewport behavior
+
+### 13.7 Fix any obvious prototype regressions
+- Resolve blocking issues only
+
+---
+
+## Optional Follow-Up Tasks
+
+These are intentionally out of current scope, but may be scheduled later.
+
+### O.1 Replace textarea with richer code editor
+### O.2 Add locked/editable code regions
+### O.3 Add inline task validation
+### O.4 Move lesson content to markdown/MDX-like source
+### O.5 Add browser-based visual review pass
+### O.6 Expand supported Admin SDK concepts
+
+---
+
+## Suggested First Delegation Batch
+
+If subagents are used, a good first sequence is:
+
+1. Phase 1 — Package Setup
+2. Phase 2 — Prototype Shell
+3. Phase 3 — Lesson Data Model
+4. Phase 4 — Editor Prototype
+5. Phase 5 — Preview Shell
+
+Then continue with runtime and lesson behavior.
+
+---
+
+## Delegation Batches
+
+The tasks above are intentionally tiny. For actual execution, they should be grouped into small delegation batches that still preserve fast feedback and low merge risk.
+
+Each batch below is designed to be:
+
+- coherent enough for a subagent to complete independently
+- small enough to review quickly
+- low-risk to integrate before the next batch starts
+
+## Batch A — Scaffold the package
+
+### Goal
+Create a bootable package under `packages/admin-sdk-tutorial` that renders a placeholder Vue app.
+
+### Includes
+- 1.1 Create package folder structure
+- 1.2 Add package manifest
+- 1.3 Add TypeScript config
+- 1.4 Add Vite config
+- 1.5 Add app HTML entry
+- 1.6 Add source entrypoint
+- 1.7 Add root app component
+- 1.8 Register workspace dependencies
+- 1.9 Ensure package is included by workspace conventions
+
+### Suggested agent type
+- `general` or direct implementation by parent session
+
+### Expected output
+- package exists
+- app boots locally
+- placeholder UI renders
+
+### Validation
+- install/build tooling resolves
+- dev server starts
+- root component mounts successfully
+
+## Batch B — Build the split tutorial shell
+
+### Goal
+Establish the Solid-inspired split-screen experience with a stable left/right layout.
+
+### Includes
+- 2.1 Replace placeholder with split layout shell
+- 2.2 Add base shell styling
+- 2.3 Create lesson sidebar component
+- 2.4 Create workspace panel component
+- 2.5 Wire shell components into root app
+- 2.6 Add mobile-safe fallback layout behavior
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- tutorial shell exists
+- left panel shows lesson area placeholder
+- right panel shows workspace area placeholder
+- narrow viewport stacks acceptably
+
+### Validation
+- desktop layout reads clearly
+- responsive fallback does not break app shell
+
+## Batch C — Add lesson data and navigation
+
+### Goal
+Make the shell data-driven with three prototype lessons and clickable switching.
+
+### Includes
+- 3.1 Create lesson type definitions
+- 3.2 Create prototype lesson data file
+- 3.3 Add active lesson state in app shell
+- 3.4 Render lesson metadata in sidebar
+- 3.5 Add lesson switching behavior
+- 3.6 Add reset-on-lesson-change behavior
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- three lessons exist in structured data
+- lesson list renders in sidebar
+- active lesson can be changed
+- shell state resets when lesson changes
+
+### Validation
+- lesson titles and descriptions render correctly
+- switching updates the active view without stale state
+
+## Batch D — Add the first editor experience
+
+### Goal
+Give the learner a simple but working in-browser editing area.
+
+### Includes
+- 4.1 Create editor component shell
+- 4.2 Add editable text area as first editor
+- 4.3 Bind editor to lesson starter code
+- 4.4 Add local editor state updates
+- 4.5 Add reset button
+- 4.6 Add basic file/tab affordance
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- active lesson starter code loads in editor
+- learner can edit code
+- reset restores starter content
+- UI looks like a lightweight single-file editor
+
+### Validation
+- edits are reactive
+- lesson change reloads correct starter code
+- reset behaves deterministically
+
+## Batch E — Add preview shell and dummy admin skeleton
+
+### Goal
+Create the visual target area where Admin SDK behavior will appear.
+
+### Includes
+- 5.1 Create preview container component
+- 5.2 Add dummy admin shell component
+- 5.3 Add preview composition
+- 5.4 Add output/status area
+- 5.5 Add empty-state messaging
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- preview area is visible
+- dummy admin shell renders with nav/content/notification regions
+- output panel exists for status/errors
+
+### Validation
+- shell is visually understandable without any execution yet
+- preview and output areas remain stable during lesson switching
+
+## Batch F — Add runtime state plumbing
+
+### Goal
+Introduce deterministic preview state that the mock SDK bridge can mutate.
+
+### Includes
+- 6.1 Create runtime type definitions
+- 6.2 Create runtime state factory
+- 6.3 Add runtime state to root app
+- 6.4 Pass runtime state into preview shell
+- 6.5 Add runtime reset helper
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- runtime state model exists
+- preview consumes runtime state reactively
+- runtime can be reset cleanly
+
+### Validation
+- reset returns preview to baseline state
+- no lesson data is hardcoded into preview rendering paths
+
+## Batch G — Implement the mock Admin SDK bridge
+
+### Goal
+Create a narrow bridge API that converts learner actions into dummy admin state changes.
+
+### Includes
+- 7.1 Create bridge module skeleton
+- 7.2 Add notification API surface
+- 7.3 Add menu item API surface
+- 7.4 Add location registration API surface
+- 7.5 Connect bridge methods to runtime state
+- 7.6 Add bridge reset behavior
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- bridge exposes minimal APIs for all three concepts
+- bridge updates runtime state deterministically
+
+### Validation
+- isolated smoke calls update runtime state as expected
+- reset clears all prior bridge effects
+
+## Batch H — Add code execution flow
+
+### Goal
+Execute learner code in-browser and connect it to the mock bridge.
+
+### Includes
+- 8.1 Create execution module skeleton
+- 8.2 Define execution input contract
+- 8.3 Implement first naive evaluation flow
+- 8.4 Capture runtime errors
+- 8.5 Trigger execution from UI
+- 8.6 Reset runtime before execution
+- 8.7 Surface errors in output panel
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- learner code can run from the UI
+- bridge methods affect preview
+- execution errors are visible but non-fatal
+
+### Validation
+- success path updates preview
+- error path updates output panel and preserves app stability
+
+## Batch I — Finish the notifications lesson
+
+### Goal
+Deliver the first complete end-to-end teaching slice.
+
+### Includes
+- 9.1 Add notification lesson starter code
+- 9.2 Add notification lesson text
+- 9.3 Render notifications in dummy admin
+- 9.4 Verify notification code path
+- 9.5 Refine notification visuals
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- notification lesson is understandable and runnable
+- learner edits visibly change notification behavior
+
+### Validation
+- starter code produces a visible notification
+- modified code changes message/type/behavior predictably
+
+## Batch J — Finish the menu items lesson
+
+### Goal
+Deliver the second complete teaching slice.
+
+### Includes
+- 10.1 Add menu item lesson starter code
+- 10.2 Add menu item lesson text
+- 10.3 Render menu items in dummy sidebar
+- 10.4 Verify menu registration code path
+- 10.5 Refine menu visuals
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- menu lesson is understandable and runnable
+- learner edits visibly change the sidebar result
+
+### Validation
+- starter code adds menu content to preview
+- modified code changes label/order/appearance predictably
+
+## Batch K — Finish the locations / positions lesson
+
+### Goal
+Deliver the third complete teaching slice focused on comprehension of extension placement.
+
+### Includes
+- 11.1 Add locations lesson starter code
+- 11.2 Add locations lesson text
+- 11.3 Add labeled location containers to dummy admin
+- 11.4 Render registered location content
+- 11.5 Verify positions concept visually
+- 11.6 Refine location card visuals
+
+### Suggested agent type
+- `general`
+
+### Expected output
+- location lesson is understandable and runnable
+- preview clearly explains placement/targeting
+
+### Validation
+- starter code renders content in named surfaces
+- content appears in the correct visual slot after edits
+
+## Batch L — Polish and verify
+
+### Goal
+Improve readability and remove obvious prototype blockers.
+
+### Includes
+- 12.1 Add lesson progress affordance
+- 12.2 Improve shell spacing and typography
+- 12.3 Improve button labels and helper text
+- 12.4 Improve preview empty/error states
+- 12.5 Add minimal branding alignment
+- 13.1 Start dev app and verify boot
+- 13.2 Verify lesson switching
+- 13.3 Verify notifications lesson manually
+- 13.4 Verify menu items lesson manually
+- 13.5 Verify locations lesson manually
+- 13.6 Verify responsive layout manually
+- 13.7 Fix any obvious prototype regressions
+
+### Suggested agent type
+- `general` for implementation and verification
+- `browser-operator` later if a browser review pass is requested
+
+### Expected output
+- prototype is coherent and demoable
+- major teaching flows work without obvious breakage
+
+### Validation
+- all three lessons work end-to-end
+- layout is understandable on desktop and narrow screens
+
+---
+
+## Recommended Execution Order
+
+Run batches in this order:
+
+1. Batch A — Scaffold the package
+2. Batch B — Build the split tutorial shell
+3. Batch C — Add lesson data and navigation
+4. Batch D — Add the first editor experience
+5. Batch E — Add preview shell and dummy admin skeleton
+6. Batch F — Add runtime state plumbing
+7. Batch G — Implement the mock Admin SDK bridge
+8. Batch H — Add code execution flow
+9. Batch I — Finish the notifications lesson
+10. Batch J — Finish the menu items lesson
+11. Batch K — Finish the locations / positions lesson
+12. Batch L — Polish and verify
+
+## Parallelization Notes
+
+Most batches should remain sequential because they build on shared app structure.
+
+Limited safe parallelism:
+
+- Batch C can begin once Batch B has stable component boundaries
+- Batch D and Batch E can partially proceed in parallel after Batch B if interfaces are agreed up front
+- Lesson copy work inside Batches I/J/K can be parallelized after runtime and execution foundations are complete
+
+Avoid parallelizing:
+
+- runtime-state and bridge changes across multiple agents at the same time
+- overlapping edits to `App.vue` and shared shell composition without explicit coordination
+
+## Handoff Guidance for Subagents
+
+Each delegated batch should include:
+
+- the brief in `.orchestrator/implementation-brief.md`
+- this plan file
+- the exact batch name and included tasks
+- a reminder to stay within prototype scope
+- a request to summarize changed files, assumptions, and follow-up risks
diff --git a/.orchestrator/next-pass-recommendation.md b/.orchestrator/next-pass-recommendation.md
new file mode 100644
index 000000000..50a8d6ae3
--- /dev/null
+++ b/.orchestrator/next-pass-recommendation.md
@@ -0,0 +1,97 @@
+# Admin SDK Tutorial Prototype — Recommended Next Pass
+
+## Recommendation
+
+The best next implementation pass is:
+
+## 1. Upgrade the editor experience
+
+### Why
+
+The current prototype already proves:
+
+- the split tutorial layout works
+- the lesson loop works
+- the dummy admin teaching model works
+- in-browser execution is understandable enough for a prototype
+
+The weakest remaining part of the experience is now the editor.
+
+The textarea is sufficient for proving the concept, but it is now the main thing making the tutorial feel less product-ready.
+
+### Recommended scope
+
+- replace the textarea with a real editor component
+- add syntax highlighting for TypeScript/JavaScript
+- preserve the simple single-file model
+- do **not** add multi-file editing yet
+- do **not** add heavy IDE/platform behavior yet
+
+### Good outcome for this pass
+
+- the tutorial feels more trustworthy and enjoyable to edit in
+- learner code is easier to scan
+- the overall prototype feels much closer to a real interactive tutorial
+
+---
+
+## 2. Add lightweight lesson validation after the editor upgrade
+
+### Why
+
+Once the editor feels credible, the next biggest product improvement is helping the learner know when they succeeded.
+
+### Recommended scope
+
+- add simple per-lesson validation
+- define success checks for the three existing lessons
+- show a lightweight solved/unsolved state
+- optionally add a “Check” or “Solve” affordance if needed
+
+### Example validation targets
+
+- **Notifications:** title/message/tone changed and preview updated
+- **Menu items:** dynamic item exists with expected label/position
+- **Locations:** content rendered into the expected slot
+
+---
+
+## 3. Reassess execution safety after validation is in place
+
+### Why
+
+The current execution approach is acceptable for a prototype, but if the tutorial becomes more widely used internally or externally, the execution model should become more constrained.
+
+### Recommended scope
+
+- keep the current execution model for now if iteration speed is still the priority
+- plan a safer constrained execution layer once editor + validation are stable
+
+---
+
+## Concepts to add after that
+
+After editor + validation, the next Admin SDK concepts to consider are:
+
+- action buttons
+- context / payload access
+- modals or overlays
+- basic communication/event flows
+
+---
+
+## Packaging / integration direction
+
+For now, keeping this work in:
+
+`packages/admin-sdk-tutorial`
+
+is still reasonable while the interaction model evolves.
+
+Once the concept is validated, the next product decision should be whether this remains a standalone package app or becomes part of the Admin SDK documentation experience.
+
+---
+
+## Final recommendation in one sentence
+
+**Next, replace the textarea with a real code editor, then add lightweight per-lesson validation before investing in a safer execution model or broader lesson coverage.**
diff --git a/.orchestrator/real-sdk-integration-plan.md b/.orchestrator/real-sdk-integration-plan.md
new file mode 100644
index 000000000..eec63c2ce
--- /dev/null
+++ b/.orchestrator/real-sdk-integration-plan.md
@@ -0,0 +1,743 @@
+# Admin SDK Tutorial Prototype — Real SDK + Dummy Host Integration Plan
+
+## Goal
+
+Replace the current fake bridge approach with an architecture where:
+
+- learner code runs inside a lesson iframe
+- learner code imports and uses the **real** `@shopware-ag/meteor-admin-sdk` package
+- the dummy admin shell acts as a **host application**
+- the host catches and handles the SDK's real `postMessage` traffic
+- the preview stays visually simplified, but the runtime flow is close to the real Shopware Admin SDK model
+
+This means the browser tutorial should no longer teach fake APIs like:
+
+- `sdk.menu.add(...)`
+- `sdk.location.render(...)`
+
+Instead, it should execute real Admin SDK code and respond to real message types.
+
+---
+
+## Clarified direction
+
+Confirmed requirements for this plan:
+
+- real SDK code should execute **inside the lesson iframe**
+- the dummy admin host should be **close to the real postMessage flow**
+- first end-to-end concepts should be:
+ - notifications
+ - menu items
+ - locations / positions
+- learner code should use **real imports** from the Admin SDK package
+- locations should use **real host concepts with simplified visuals**
+- this plan should be based on actual SDK internals/docs, not just API renaming
+
+---
+
+## What the real SDK does
+
+## 1. Connection model
+
+The SDK initializes its messaging channel on load and sends a `__registerWindow__` message to the parent.
+
+The host is expected to register the iframe window and origin in the source registry.
+
+Important implication:
+
+- we should not simulate an invented runtime protocol
+- we should let the real SDK boot and talk to a real parent host window
+
+## 2. Transport model
+
+The real SDK uses:
+
+- `window.postMessage`
+- JSON string payloads
+- `_type`, `_data`, `_callbackId` request envelopes
+- `_type`, `_response`, `_callbackId` response envelopes
+
+It also supports serialized function callbacks via internal `__function__` transport.
+
+Important implication:
+
+- host-side message handling should preferably use the SDK's own channel helpers instead of custom ad hoc parsing
+
+## 3. Real concepts we need to support
+
+### Notifications
+
+Real concept:
+
+- `notification.dispatch(...)`
+
+### Menu items
+
+Real concept:
+
+- `ui.menu.addMenuItem(...)`
+
+### Locations / positions
+
+Real concept is more architectural:
+
+- host UI is extended at a `positionId`
+- content/view routing is based on `locationId`
+- the extension decides what to render using `location.is(...)`
+- host may react to `locationUpdateHeight` / `locationUpdateUrl`
+
+Important implication:
+
+- locations should not be modeled as a single fake `render(...)` call
+- the tutorial needs a host shell that owns surfaces and iframes/iframe-like views per location
+
+---
+
+## Proposed target architecture
+
+## A. Parent app = tutorial shell + dummy admin host
+
+The parent app should own:
+
+- the lesson UI
+- the code editor
+- the preview frame chrome
+- the dummy admin host state
+- the host-side Admin SDK handlers
+
+The parent should also host one or more iframes that represent extension runtime contexts.
+
+## B. Lesson iframe = real extension runtime
+
+The learner code should run inside an iframe that:
+
+- imports the real `@shopware-ag/meteor-admin-sdk`
+- executes real SDK calls
+- talks to the parent using the SDK's real channel implementation
+
+This iframe should receive a URL containing the correct `location-id` query parameter so real location APIs work.
+
+## C. Dummy admin host = real handler layer + simplified UI
+
+The dummy host should register handlers for the real message types and update simplified host UI state.
+
+Recommended implementation:
+
+- use the SDK's channel handling utilities from the package
+- do not hand-roll a fake message system unless absolutely necessary
+
+---
+
+## Implementation phases
+
+## Phase 1 — Build a real iframe runtime container
+
+### Goal
+Create a lesson runtime iframe that can execute real Admin SDK code.
+
+### Tasks
+- create a dedicated iframe runtime entry in `packages/admin-sdk-tutorial`
+- load the runtime in an iframe from the parent preview
+- make the iframe accept lesson code input
+- make the iframe execute lesson code with real imports from `@shopware-ag/meteor-admin-sdk`
+- include the right `location-id` in the iframe URL
+
+### Expected result
+- learner code runs in a real iframe context
+- real Admin SDK package loads there
+- the parent sees real SDK postMessages
+
+### Tiny executable tasks
+
+#### 1.1 Create iframe runtime directory
+- add `src/iframe-runtime/` structure
+- create placeholder entry files
+
+#### 1.2 Add iframe runtime app entry
+- create a minimal iframe runtime bootstrap file
+- ensure it can mount independently from the parent app
+
+#### 1.3 Add iframe HTML route/entry strategy
+- decide whether the iframe uses a separate html entry or routed app entry
+- wire Vite accordingly
+
+#### 1.4 Render a minimal iframe shell
+- show a simple mounted runtime placeholder in the iframe
+
+#### 1.5 Mount iframe inside preview panel
+- render a real iframe in the preview area
+- confirm parent and iframe both load successfully
+
+#### 1.6 Pass starter code into iframe
+- define a parent-to-iframe code handoff mechanism
+- keep it simple for the first pass
+
+#### 1.7 Add location-id query param to iframe URL
+- include a configurable `location-id` in iframe src
+
+#### 1.8 Verify iframe receives URL params correctly
+- confirm runtime can read the expected `location-id`
+
+#### 1.9 Add real SDK import to iframe bootstrap
+- import the real admin-sdk package in the iframe runtime
+- confirm it loads without crashing
+
+#### 1.10 Verify parent sees first SDK postMessage
+- confirm the real SDK posts to the parent window
+
+---
+
+## Phase 2 — Build host-side source registration and channel handling
+
+### Goal
+Make the dummy host behave like a real parent host for the SDK channel.
+
+### Tasks
+- inspect/use the SDK channel helpers from the real package
+- support `__registerWindow__` handling and source registration
+- ensure iframe window + origin are stored correctly for replies
+- validate origin/source safely in the tutorial host
+- keep the host-side messaging logic isolated in a dedicated runtime module
+
+### Expected result
+- iframe and parent are connected through the real SDK handshake
+- host can answer real SDK requests
+
+### Tiny executable tasks
+
+#### 2.1 Create host runtime directory
+- add `src/host/` structure for parent-side SDK runtime logic
+
+#### 2.2 Add host bootstrap module
+- centralize host runtime startup in one module
+
+#### 2.3 Inspect usable SDK channel imports
+- confirm exact import path(s) to use from the real package for host-side helpers
+
+#### 2.4 Register minimal message listener in parent
+- add a non-invasive message observer for debugging/verification
+
+#### 2.5 Implement `__registerWindow__` handling
+- catch the initial SDK registration message
+
+#### 2.6 Store iframe window reference safely
+- track iframe window/source in host runtime state
+
+#### 2.7 Store origin/referrer metadata safely
+- keep enough origin information for replies and validation
+
+#### 2.8 Add source validation guardrails
+- reject clearly invalid/unexpected sources
+
+#### 2.9 Move message logic out of components
+- keep handler setup in host runtime modules, not Vue component bodies
+
+#### 2.10 Verify request-response flow with one trivial handler
+- confirm the parent can answer a real SDK-originated request
+
+---
+
+## Phase 3 — Implement real notification handling
+
+### Goal
+Support real `notification.dispatch(...)` from iframe code.
+
+### Tasks
+- replace lesson code with real notification imports and calls
+- implement host handler for notification dispatch message type
+- map the real payload shape into dummy host notification UI
+- support at least title/message/variant
+- optionally support callback actions only if the handler path is stable enough
+
+### Expected result
+- learner writes real notification SDK code
+- dummy host shows a notification based on real SDK messaging
+
+### Tiny executable tasks
+
+#### 3.1 Replace notifications starter code with real imports
+- update lesson code to import the real notification API
+
+#### 3.2 Replace fake notification payload fields
+- switch from fake fields like `tone` to real SDK fields like `variant`
+
+#### 3.3 Add notification execution path in iframe
+- ensure lesson code runs successfully from the iframe runtime
+
+#### 3.4 Register host notification handler
+- implement handling for the real notification message type
+
+#### 3.5 Map notification payload into host state
+- update dummy host state from real payload values
+
+#### 3.6 Render real notification result in preview
+- show the resulting notification in the dummy host UI
+
+#### 3.7 Verify end-to-end notification flow
+- run real lesson code and confirm host updates from postMessage
+
+#### 3.8 Verify error handling for notification lesson
+- confirm invalid code still fails gracefully
+
+---
+
+## Phase 4 — Implement real menu item handling
+
+### Goal
+Support real `ui.menu.addMenuItem(...)` from iframe code.
+
+### Tasks
+- replace lesson code with real menu API imports/calls
+- implement host handler for the real menu item add message type
+- store host-side menu items in dummy admin state
+- render those items in the sidebar
+- on click, open or route to the related `locationId`
+
+### Expected result
+- learner writes real menu SDK code
+- dummy host sidebar updates from real SDK messaging
+
+### Tiny executable tasks
+
+#### 4.1 Replace menu lesson starter code with real imports
+- update lesson code to import real menu APIs
+
+#### 4.2 Use real `ui.menu.addMenuItem(...)` lesson code
+- remove the fake menu call from the learner-facing lesson
+
+#### 4.3 Add menu message handler in host runtime
+- implement handling for the real menu item add message type
+
+#### 4.4 Persist dynamic menu items in host state
+- store host-side menu items from real SDK requests
+
+#### 4.5 Render dynamic menu items in sidebar
+- reflect real handler output in dummy admin navigation
+
+#### 4.6 Add click handling for menu items
+- let sidebar clicks switch/open the related location view
+
+#### 4.7 Wire menu item locationId into iframe selection
+- update active iframe/location based on menu interaction
+
+#### 4.8 Verify end-to-end menu flow
+- confirm real SDK lesson code updates host navigation correctly
+
+---
+
+## Phase 5 — Implement real location/position flow
+
+### Goal
+Teach real location and position concepts, even with simplified visuals.
+
+### Tasks
+- rewrite the lesson around real concepts:
+ - `positionId`
+ - `locationId`
+ - `location.is(...)`
+- add host-owned extension surfaces/cards labeled by position
+- create location-specific iframe views using query params like `?location-id=...`
+- support host handling for `locationUpdateHeight`
+- optionally support `locationUpdateUrl` if useful for the tutorial flow
+
+### Expected result
+- learner code uses real location concepts
+- dummy host visualizes where extension views belong
+- the extension iframe can determine its current location using the real SDK API
+
+### Tiny executable tasks
+
+#### 5.1 Rewrite lesson copy around real location concepts
+- update copy to teach `positionId`, `locationId`, and `location.is(...)`
+
+#### 5.2 Rewrite locations starter code with real imports
+- remove fake render-style lesson code
+
+#### 5.3 Add host-owned position surfaces
+- render labeled host surfaces/cards for simplified positions
+
+#### 5.4 Add location-specific iframe URL generation
+- build iframe URLs with the right `location-id`
+
+#### 5.5 Add support for switching visible location view
+- allow the parent host to show the correct runtime view for a location
+
+#### 5.6 Implement `locationUpdateHeight` handler
+- resize iframe or tracked host view height from real SDK messages
+
+#### 5.7 Decide whether to support `locationUpdateUrl` now
+- explicitly choose keep/skip for this first pass
+
+#### 5.8 If included, implement `locationUpdateUrl` handler
+- store/update route state safely in the dummy host
+
+#### 5.9 Verify `location.is(...)` behavior in iframe
+- confirm the lesson runtime sees the expected location from URL params
+
+#### 5.10 Verify end-to-end locations flow
+- confirm real lesson code updates the correct host surface
+
+---
+
+## Phase 6 — Replace mock bridge lesson execution path
+
+### Goal
+Remove the current fake bridge from the core lesson path.
+
+### Tasks
+- stop using the mock bridge for the three primary lessons
+- route Run/Reset through the iframe runtime instead
+- keep the old mock code only temporarily if needed during migration
+- remove deprecated fake lesson APIs after the real path is stable
+
+### Expected result
+- the prototype is primarily powered by the real SDK package
+- the dummy admin shell acts as a real host adapter, not a fake API simulator
+
+### Tiny executable tasks
+
+#### 6.1 Identify current fake bridge dependencies
+- list which components/modules still depend on the mock bridge
+
+#### 6.2 Route Run through iframe execution
+- make Run use the iframe runtime instead of the mock bridge path
+
+#### 6.3 Route Reset through iframe runtime
+- make Reset restore lesson state via the iframe path
+
+#### 6.4 Keep temporary compatibility layer only where needed
+- isolate any remaining bridge code behind a temporary adapter
+
+#### 6.5 Remove fake notifications path
+- stop using the old mock notification behavior for the main lesson flow
+
+#### 6.6 Remove fake menu path
+- stop using the old mock menu behavior for the main lesson flow
+
+#### 6.7 Remove fake locations path
+- stop using the old mock location behavior for the main lesson flow
+
+#### 6.8 Delete deprecated bridge code once unused
+- remove dead mock runtime pieces after migration is stable
+
+---
+
+## Phase 7 — Validate parity and teaching clarity
+
+### Goal
+Ensure the new architecture is both correct and understandable.
+
+### Tasks
+- verify notification lesson end-to-end in browser
+- verify menu lesson end-to-end in browser
+- verify location lesson end-to-end in browser
+- confirm postMessage flow is working as expected
+- check console/network/runtime logs for handler issues
+- simplify copy where real SDK complexity becomes too noisy
+
+### Expected result
+- prototype still feels approachable
+- but now teaches real SDK behavior and terminology
+
+### Tiny executable tasks
+
+#### 7.1 Browser-verify notifications lesson
+- test the real notification lesson end-to-end
+
+#### 7.2 Browser-verify menu lesson
+- test the real menu lesson end-to-end
+
+#### 7.3 Browser-verify locations lesson
+- test the real locations lesson end-to-end
+
+#### 7.4 Check message traffic sanity
+- confirm request/response flow behaves as expected in browser/devtools
+
+#### 7.5 Check console for handler/runtime issues
+- identify any host or iframe runtime warnings/errors
+
+#### 7.6 Check iframe sizing behavior
+- verify height updates behave reasonably in the dummy host
+
+#### 7.7 Tighten teaching copy where needed
+- simplify any lesson text that became too implementation-heavy
+
+#### 7.8 Final browser sanity pass
+- confirm the prototype still feels coherent and teachable
+
+---
+
+## Required host-side capabilities
+
+The dummy host should be prepared to handle at least:
+
+- `__registerWindow__`
+- notification dispatch message(s)
+- menu item add message(s)
+- location-related update messages such as height updates
+
+Potentially useful additional support later:
+
+- callback transport for action buttons
+- URL update handling
+- more UI extension APIs
+
+---
+
+## Recommended implementation modules
+
+Suggested new areas inside `packages/admin-sdk-tutorial`:
+
+- `src/host/`
+ - source registry / host bootstrap
+ - channel handler registration
+ - host state adapters
+- `src/iframe-runtime/`
+ - iframe app entry
+ - lesson runtime bootstrap
+ - real SDK execution wrapper
+- `src/lessons/`
+ - updated lesson code using real SDK imports
+- `src/preview/`
+ - dummy host surfaces / location frame rendering
+
+---
+
+## Constraints and gotchas
+
+- the real SDK depends on parent/iframe messaging assumptions, so the iframe runtime must be a genuine iframe
+- function callbacks require correct SDK serializer/deserializer support; avoid custom raw message handling if possible
+- `location.is(...)` depends on URL query parameters, so iframe URLs must be managed deliberately
+- the tutorial host should still validate message source/origin even in local prototype mode
+- a hidden bootstrap location such as `sw-main-hidden` may be useful for registration-style lesson flows
+
+---
+
+## Migration strategy
+
+Recommended order:
+
+1. notifications
+2. menu items
+3. locations / positions
+
+Reason:
+
+- notifications are the smallest end-to-end real handler slice
+- menu adds real host navigation behavior with manageable complexity
+- locations require the deepest conceptual and architectural change
+
+---
+
+## Suggested execution batches
+
+These tiny tasks can be grouped into practical implementation batches.
+
+### Batch A — Real iframe runtime bootstrap
+- 1.1 through 1.10
+
+### Batch B — Host registration and channel setup
+- 2.1 through 2.10
+
+### Batch C — Real notifications vertical slice
+- 3.1 through 3.8
+
+### Batch D — Real menu vertical slice
+- 4.1 through 4.8
+
+### Batch E — Real locations vertical slice
+- 5.1 through 5.10
+
+### Batch F — Remove fake bridge path
+- 6.1 through 6.8
+
+### Batch G — End-to-end validation and polish
+- 7.1 through 7.8
+
+---
+
+## Source-of-truth references
+
+### Core internals
+- `packages/admin-sdk/src/channel.ts`
+- `packages/admin-sdk/src/message-types.ts`
+- `packages/admin-sdk/src/_internals/serializer/function-serializer.ts`
+
+### Feature APIs
+- `packages/admin-sdk/src/notification/index.ts`
+- `packages/admin-sdk/src/ui/menu/index.ts`
+- `packages/admin-sdk/src/location/index.ts`
+- `packages/admin-sdk/src/ui/component-section/index.ts`
+- `packages/admin-sdk/src/ui/tabs/index.ts`
+
+### Docs
+- `docs/admin-sdk/internals/how-it-works.md`
+- `docs/admin-sdk/api-reference/notification.md`
+- `docs/admin-sdk/api-reference/ui/menu.md`
+- `docs/admin-sdk/api-reference/location.md`
+- `docs/admin-sdk/api-reference/ui/component-section.md`
+- `docs/admin-sdk/api-reference/ui/tabs.md`
+- `docs/admin-sdk/concepts/locations.md`
+- `docs/admin-sdk/concepts/component-sections.md`
+- `docs/admin-sdk/concepts/positions.md`
+
+---
+
+## Recommendation
+
+The correct next direction is:
+
+- **do not just rename the fake bridge APIs**
+- **do use the real Admin SDK package inside a lesson iframe**
+- **do implement real host-side handlers in the dummy admin shell**
+- **keep the visuals simplified, but make the runtime architecture real**
+
+---
+
+## Current implementation status
+
+### Finished batches
+
+#### Batch A — Real iframe runtime bootstrap
+Status: **finished**
+
+Completed:
+- real iframe runtime entry exists
+- iframe loads inside the preview
+- real `@shopware-ag/meteor-admin-sdk` is imported in the iframe runtime
+- lesson code is sent from parent to iframe
+- parent observes real SDK traffic
+- `__registerWindow__` is acknowledged so bootstrap does not time out
+
+#### Batch B — Host registration and channel setup
+Status: **finished**
+
+Completed:
+- parent-side host runtime module exists
+- host-side message observation was moved out of the component body
+- source registration count is surfaced in the UI
+- real channel bootstrap is stable in browser
+
+#### Batch C — Real notifications vertical slice
+Status: **finished**
+
+Completed:
+- notifications lesson now uses the real API shape
+- real notification traffic flows from iframe to host
+- dummy host updates notification UI from real handler results
+- success/error states work
+- last successful notification state is preserved on error
+
+#### Batch D — Real menu vertical slice
+Status: **finished**
+
+Completed:
+- menu lesson now uses the real API shape: `ui.menu.addMenuItem(...)`
+- real `menuItemAdd` traffic is sent from iframe to host
+- menu success/error states work
+- no obvious console issues
+
+Completed:
+- edited menu payloads now update the dummy host sidebar correctly
+- dynamic menu item ordering reacts to changed position values
+- menu success/error states are preserved through the real iframe/host path
+
+Minor remaining note:
+- the iframe runtime display can still show concatenated old + new code text during repeated runs, but host behavior is now correct
+
+#### Batch E — Real locations vertical slice
+Status: **finished**
+
+Completed:
+- locations lesson now uses real concepts:
+ - `location.MAIN_HIDDEN`
+ - `ui.componentSection.add(...)`
+ - `location.is(...)`
+ - `location.updateHeight(...)`
+- real `uiComponentSectionRenderer` traffic flows from iframe to host
+- dummy host renders location iframes inside the chosen host slot
+- host slot changes correctly when `positionId` changes
+- height updates are handled via real `locationUpdateHeight` traffic
+- success/error states work through the real iframe/host path
+
+#### Batch F — Remove fake bridge path
+Status: **finished**
+
+Completed:
+- old fake bridge execution path was removed from the active lesson flow
+- old fake runtime executor was removed
+- all three lessons now work through the real iframe + host message flow
+- verification confirmed no visible dependency on the old mock bridge remains
+
+---
+
+## What is currently broken
+
+### Main broken area
+
+There is currently **no blocking migration issue** in Batches A-F.
+
+The remaining work is now primarily **polish and cleanup**, not a core runtime blocker.
+
+### Remaining rough edges
+
+- the iframe runtime display can still show concatenated old + new code text during repeated runs
+- some error output can still feel slightly repetitive depending on the lesson
+- code and runtime synchronization should still be simplified and cleaned up before final polish/commit
+
+### Likely cleanup area
+
+The remaining issue appears to be mostly in the **iframe runtime display/synchronization layer**, not in the real host handler flow.
+
+---
+
+## Follow-up task breakdown for cleanup and validation
+
+### Task group 1 — Clean up iframe runtime display behavior
+
+#### 1.1 Reproduce concatenated iframe code display deterministically
+- confirm the exact circumstances where old + new code are both shown
+
+#### 1.2 Compare editor value vs iframe displayed value
+- confirm whether the iframe is receiving the same code shown in the editor
+
+#### 1.3 Compare iframe displayed value vs executed value
+- confirm whether the code displayed in the iframe is the code actually being executed
+
+#### 1.4 Simplify runtime code display source
+- make the iframe display only the current run snapshot or current editor state, not both ambiguously
+
+### Task group 2 — Polish error/output messaging
+
+#### 2.1 Reduce repeated failure wording
+- simplify output cards so one failure message is enough
+
+#### 2.2 Align failure copy across all three lessons
+- ensure notifications, menu, and locations all use equally clear output wording
+
+#### 2.3 Verify preserved-success-state behavior still reads clearly
+- make sure preserved host state on error feels intentional, not confusing
+
+### Task group 3 — Final validation / polish
+
+#### 3.1 Re-run notifications lesson end-to-end
+#### 3.2 Re-run menu lesson end-to-end
+#### 3.3 Re-run locations lesson end-to-end
+#### 3.4 Verify desktop layout still feels coherent
+#### 3.5 Verify mobile layout still feels coherent
+
+### Task group 4 — Prepare final commit/summary
+
+#### 4.1 Summarize runtime architecture as implemented
+#### 4.2 Note remaining known quirks explicitly
+#### 4.3 Prepare clean commit once Batch G is complete
+
+---
+
+## Resume point
+
+When implementation resumes, the next focus should be:
+
+1. finish Batch G validation/polish
+2. clean up remaining minor iframe-display quirks if worthwhile
+3. prepare a clean summary + commit
diff --git a/.orchestrator/second-pass-plan.md b/.orchestrator/second-pass-plan.md
new file mode 100644
index 000000000..4deb8d0b5
--- /dev/null
+++ b/.orchestrator/second-pass-plan.md
@@ -0,0 +1,351 @@
+# Admin SDK Tutorial Prototype — Second Pass Plan
+
+## Goal
+
+Run a focused second pass on the prototype to improve:
+
+- visual quality
+- teaching clarity
+- interaction polish
+- readiness for a richer editor/execution phase later
+
+This pass should still stay within prototype scope. It should not become a full platform rebuild.
+
+---
+
+## Phase 1 — Refine the teaching experience
+
+### Goal
+Make each lesson easier to understand at a glance.
+
+### Tasks
+- reduce duplicated information between preview, output, and empty states
+- make the primary lesson task more prominent
+- improve wording for lesson descriptions and objectives
+- make success/error states feel more intentional
+
+### Output
+- clearer lesson framing
+- less noisy preview state
+- stronger “what should I do now?” guidance
+
+### Tiny executable tasks
+
+#### 1.1 Inventory duplicated lesson information
+- note repeated information across sidebar, preview, toast, and output
+- identify what should remain primary vs secondary
+
+#### 1.2 Make the current task more prominent
+- highlight the active lesson objective more clearly
+- ensure it is visible without scanning multiple panels
+
+#### 1.3 Tighten notifications lesson description
+- shorten or clarify the description text
+- make the expected learner action explicit
+
+#### 1.4 Tighten menu lesson description
+- shorten or clarify the description text
+- make the expected learner action explicit
+
+#### 1.5 Tighten locations lesson description
+- shorten or clarify the description text
+- make the expected learner action explicit
+
+#### 1.6 Improve lesson objective wording
+- standardize objective phrasing across all lessons
+- keep objectives action-oriented
+
+#### 1.7 Improve output success message copy
+- replace generic success text with more lesson-aware feedback
+
+#### 1.8 Improve output error message copy
+- make failure messaging feel more intentional and useful
+
+#### 1.9 Reduce repeated preview copy
+- remove or simplify duplicated text in empty state / toast / output where possible
+
+#### 1.10 Verify all three lessons still read clearly
+- manually review lesson copy coherence after edits
+
+---
+
+## Phase 2 — Improve the visual shell
+
+### Goal
+Make the tutorial feel more polished and cohesive.
+
+### Tasks
+- refine sidebar spacing, hierarchy, and progress treatment
+- improve editor/preview balance and panel styling
+- tighten typography and spacing across the shell
+- improve badge, label, and card semantics
+- make the dummy admin feel more deliberate and less placeholder-like
+
+### Output
+- more convincing split-layout tutorial UI
+- better scanability
+- stronger visual rhythm
+
+### Tiny executable tasks
+
+#### 2.1 Refine sidebar spacing
+- adjust gaps, padding, and section spacing in the left column
+
+#### 2.2 Improve sidebar hierarchy
+- strengthen distinctions between title, description, progress, and task sections
+
+#### 2.3 Improve progress treatment
+- refine the step count / progress presentation
+
+#### 2.4 Improve lesson card states
+- make active/inactive lesson items feel clearer
+
+#### 2.5 Refine workspace panel spacing
+- balance internal padding and gaps across editor/preview/output panels
+
+#### 2.6 Improve panel headers
+- align label, title, actions, and metadata more cleanly
+
+#### 2.7 Tighten editor/preview proportions
+- slightly adjust layout balance if one side feels too heavy
+
+#### 2.8 Refine typography scale
+- improve consistency of heading/body/label sizes
+
+#### 2.9 Improve semantic badge styling
+- refine status chips, labels, and small badges
+
+#### 2.10 Verify desktop shell coherence
+- confirm the full split layout feels visually consistent
+
+---
+
+## Phase 3 — Upgrade the dummy admin model
+
+### Goal
+Make the preview better at teaching Admin SDK concepts.
+
+### Tasks
+- improve notification presentation so it feels closer to a teaching toast
+- improve dynamic sidebar/menu item treatment
+- improve extension slot cards and location labels
+- clarify host-vs-extension mental model where useful
+
+### Output
+- notifications look more intentional
+- menu additions are easier to read
+- locations/positions are even more understandable
+
+### Tiny executable tasks
+
+#### 3.1 Refine notification container layout
+- improve internal spacing and hierarchy of the toast-like UI
+
+#### 3.2 Improve notification tone styling
+- make info/success states more distinct but still minimal
+
+#### 3.3 Improve dynamic menu item readability
+- refine spacing between label and “new” marker
+
+#### 3.4 Improve menu item semantics
+- make dynamic items feel intentionally added, not just appended text
+
+#### 3.5 Refine extension slot labels
+- improve wording/formatting of slot labels and titles
+
+#### 3.6 Improve injected content treatment
+- make injected content visually distinct from the host slot container
+
+#### 3.7 Clarify host surface mental model
+- make it clearer which UI belongs to the host vs extension slot
+
+#### 3.8 Verify each concept is visually obvious
+- check notification/menu/location concepts one by one in the preview
+
+---
+
+## Phase 4 — Improve interaction polish
+
+### Goal
+Make run/reset/output flows feel cleaner and more trustworthy.
+
+### Tasks
+- decide whether Reset should also re-run automatically
+- improve output messaging for success/error/reset states
+- make run feedback feel immediate
+- add small interaction affordances where useful
+
+### Output
+- fewer confusing states
+- smoother teaching loop
+- more coherent execution feedback
+
+### Tiny executable tasks
+
+#### 4.1 Decide Reset behavior
+- choose whether Reset should only restore code or also auto-run
+
+#### 4.2 Implement chosen Reset behavior
+- update reset flow accordingly
+
+#### 4.3 Improve run success feedback
+- make success feedback more immediate and less generic
+
+#### 4.4 Improve reset feedback
+- make reset state understandable without reading too much text
+
+#### 4.5 Improve error feedback presentation
+- clarify placement and styling of execution errors
+
+#### 4.6 Add subtle run-state affordance
+- add a small UI signal that a run occurred if useful
+
+#### 4.7 Review control labels
+- ensure Run/Reset labels still feel correct after behavior changes
+
+#### 4.8 Verify the execution loop feels coherent
+- manually test edit → run → reset → run again
+
+---
+
+## Phase 5 — Browser review and iteration
+
+### Goal
+Validate the second pass visually in a real browser and tighten obvious issues.
+
+### Tasks
+- verify desktop layout
+- verify narrow/mobile layout
+- compare lesson flows side-by-side
+- fix obvious spacing, overflow, and clarity issues
+
+### Output
+- a more demo-ready prototype
+- fewer visual rough edges
+
+### Tiny executable tasks
+
+#### 5.1 Desktop browser check
+- review the prototype on desktop viewport
+
+#### 5.2 Mobile browser check
+- review the prototype on narrow/mobile viewport
+
+#### 5.3 Verify notifications flow visually
+- run through the full notifications lesson in-browser
+
+#### 5.4 Verify menu flow visually
+- run through the full menu lesson in-browser
+
+#### 5.5 Verify locations flow visually
+- run through the full locations lesson in-browser
+
+#### 5.6 Note layout issues
+- capture spacing, overflow, and hierarchy issues found in browser
+
+#### 5.7 Fix first browser issue
+- resolve the highest-priority UI issue found
+
+#### 5.8 Re-check in browser
+- verify that the first fix worked
+
+#### 5.9 Fix second browser issue if needed
+- resolve one more obvious issue only if it materially improves the prototype
+
+#### 5.10 Final browser pass
+- confirm the prototype feels demo-ready enough for the second pass goal
+
+---
+
+## Phase 6 — Optional follow-up after the second pass
+
+These should happen only after the visual/product pass feels strong enough.
+
+### Candidate next steps
+- replace textarea with a real code editor
+- add lesson validation / “Solve” states
+- move to a safer execution model
+- add more Admin SDK concepts
+- define documentation integration path
+
+### Tiny executable planning tasks
+
+#### 6.1 Decide whether editor upgrade is next
+- assess if textarea is blocking further prototype learning value
+
+#### 6.2 Define editor upgrade scope
+- decide whether syntax highlighting alone is enough or if a fuller editor is needed
+
+#### 6.3 Define lesson validation scope
+- outline what “success” means for each current lesson
+
+#### 6.4 Reassess execution safety needs
+- decide whether current execution approach is still acceptable for prototype use
+
+#### 6.5 Identify next Admin SDK concepts
+- shortlist the next most valuable concepts after the first three lessons
+
+#### 6.6 Decide docs integration direction
+- outline whether this should remain a package app or connect into docs later
+
+#### 6.7 Write recommendation for next implementation pass
+- summarize the best next technical/product step after the second pass
+
+---
+
+## Recommended execution order
+
+1. Phase 1 — Refine the teaching experience
+2. Phase 2 — Improve the visual shell
+3. Phase 3 — Upgrade the dummy admin model
+4. Phase 4 — Improve interaction polish
+5. Phase 5 — Browser review and iteration
+6. Phase 6 — Optional follow-up
+
+---
+
+## Suggested second-pass execution batches
+
+These tiny tasks can be grouped into small execution batches.
+
+### Batch A — Lesson clarity
+- 1.1 through 1.6
+
+### Batch B — Feedback copy and repetition cleanup
+- 1.7 through 1.10
+
+### Batch C — Sidebar and shell polish
+- 2.1 through 2.5
+
+### Batch D — Typography, badges, and layout refinement
+- 2.6 through 2.10
+
+### Batch E — Notification and menu preview polish
+- 3.1 through 3.4
+
+### Batch F — Locations preview polish
+- 3.5 through 3.8
+
+### Batch G — Interaction polish
+- 4.1 through 4.8
+
+### Batch H — Browser review and iteration
+- 5.1 through 5.10
+
+### Batch I — Decide next implementation pass
+- 6.1 through 6.7
+
+---
+
+## Scope guardrails
+
+During this second pass:
+
+- do not introduce a full authoring system
+- do not introduce persistence or backend services
+- do not overbuild the execution environment
+- do not optimize for production parity yet
+
+The main question for this pass is:
+
+**Does the prototype now feel compelling enough that it is clearly worth evolving further?**
diff --git a/packages/admin-sdk-tutorial/.gitignore b/packages/admin-sdk-tutorial/.gitignore
new file mode 100644
index 000000000..f06235c46
--- /dev/null
+++ b/packages/admin-sdk-tutorial/.gitignore
@@ -0,0 +1,2 @@
+node_modules
+dist
diff --git a/packages/admin-sdk-tutorial/dummy-admin-shell.html b/packages/admin-sdk-tutorial/dummy-admin-shell.html
new file mode 100644
index 000000000..5a8383d1d
--- /dev/null
+++ b/packages/admin-sdk-tutorial/dummy-admin-shell.html
@@ -0,0 +1,12 @@
+
+
+