feat: update CLAUDE.md with additional development commands and guidelines

Author: jung-thomas

CLAUDE.md

@@ -17,6 +17,10 @@ Most code contribution work targets either `exercises/*/README.md` (docs) or `so
 npm ci                             # Install dependencies
 npm start                          # Start CAP server (cds-serve)
 npm run watch-interaction_items    # Start/watch with Fiori UI open
+npm run watch-hybrid               # Watch with hybrid profile (remote HANA + local service)
+npm run deploy-hana                # Deploy DB artifacts to HANA Cloud HDI container
+npm run create-xsuaa               # Create XSUAA service instance and bind locally
+npm run start-router               # Start AppRouter locally with bound services
 npx eslint .                       # Lint (uses @sap/cds ESLint config)
 npx cds build --production         # Production build / MTA pre-build step
 ```
@@ -40,27 +44,44 @@ Auth flow: XSUAA → AppRouter → CAP service (`cds.requires.auth = xsuaa`).
 ## Conventions and guardrails
 
 ### Layer boundaries
+
 Keep concerns in their correct layer — do not leak DB semantics into service handlers or UI annotations into `srv/`:
 - `db/*` — data model and HANA-native artifacts
 - `srv/*` — service projections, authorization, handlers
 - `app/*` — UI annotations and Fiori metadata
 
 ### Auth and deployment config — cross-file consistency
+
 When changing auth, routing, or deployment, verify all four files stay aligned:
 - `solution/MyHANAApp/xs-security.json`
 - `solution/MyHANAApp/package.json` (`cds.requires.auth`)
 - `solution/MyHANAApp/app/router/xs-app.json` (destination `srv-api`)
 - `solution/MyHANAApp/mta.yaml` (provides destination `srv-api`)
 
 ### ESLint
+
 The ESLint baseline is `solution/MyHANAApp/eslint.config.mjs` using `@sap/cds` recommended config. Do not introduce an alternative config.
 
 ### Node.js version
+
 Use even-numbered LTS versions (18, 20, 22, 24). Odd versions lack native module support for some CAP dependencies.
 
 ### HANA graphical calculation view editing
+
 The graphical calculation view editor is BAS-only. Do not suggest unsupported local alternatives.
 
+### Development environments
+
+Participants use SAP Business Application Studio, GitHub Codespaces, or the `.devcontainer/` (Node 24-bookworm). See `prerequisites.md` for the full setup matrix — do not duplicate it here.
+
+### CI/CD
+
+`deploy-docs.yml` (GitHub Actions) builds and deploys the VitePress site. The `Jenkinsfile` in the solution app is a SAP CI/CD Service bootstrap — it is not actively used for this repo.
+
+### Sibling AI instruction files
+
+This repo also ships `.clinerules`, `.cursorrules`, `.windsurfrules`, `AGENT_INSTRUCTIONS.md`, and `.github/copilot-instructions.md` — all covering the same conventions for other AI tools. Do not contradict them. If updating conventions, this CLAUDE.md is the source of truth; the others are generated downstream.
+
 ## Documentation style (exercise READMEs)
 
 - Conversational, concise, action-oriented workshop tone
@@ -78,35 +99,16 @@ The VitePress site lives in `docs/`. Each exercise has a thin wrapper page at `d
 ```bash
 npm run docs:dev    # Start dev server
 npm run docs:build  # Production build → docs/.vitepress/dist/
-npm test            # Run Vitest unit tests (20 tests)
+npm test            # Run Vitest unit tests (23 tests)
 ```
 
 ### External tutorial inline expansion
 
-Exercise READMEs link to SAP tutorials on `developers.sap.com`. The VitePress build automatically expands these links inline — fetching the tutorial markdown from GitHub at build time and replacing the link paragraph with the full tutorial steps plus an attribution banner.
-
-**How it works:**
-
-- Any block in a README that contains `👉` **and** a `developers.sap.com/tutorials/{ID}.html` link where `{ID}` is a key in the config map gets expanded inline.
-- Source READMEs are never modified — expansion happens during VitePress rendering only.
-- Two `👉` paragraph variants are both handled:
-  - `👉 Perform all the steps in the tutorial: [Title](URL)` (ex1–ex4, ex8)
-  - `Perform all the steps in 👉 [tutorial: Title](URL)` (ex5–ex7)
+Exercise READMEs link to SAP tutorials on `developers.sap.com`. The VitePress build expands these links inline at build time — fetching tutorial markdown from GitHub, transforming it, and replacing the link paragraph with full tutorial steps plus an attribution banner. Source READMEs are never modified.
 
-**To add a new tutorial expansion:**
+**Detection:** any paragraph containing `👉` and a `developers.sap.com/tutorials/{ID}.html` link where `{ID}` is a key in the config map. Two paragraph variants exist across exercises — both are handled.
 
-1. Confirm the tutorial markdown exists in the upstream repo. The URL pattern is:
-   `https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/{ID}/{ID}.md`
-   Verify with: `curl -s -o /dev/null -w "%{http_code}" <url>`
-
-2. Add one entry to [`docs/.vitepress/external-tutorials.config.ts`](docs/.vitepress/external-tutorials.config.ts):
-
-   ```ts
-   'tutorial-id-here':
-     'https://raw.githubusercontent.com/sap-tutorials/Tutorials/master/tutorials/tutorial-id-here/tutorial-id-here.md',
-   ```
-
-3. Run `npm run docs:build` from `docs/` and verify the page shows exactly 1 attribution banner per tutorial link.
+**To add a new tutorial:** add one entry to `docs/.vitepress/external-tutorials.config.ts`, verify the raw GitHub URL returns 200, then run `npm run docs:build` from `docs/`. Most tutorials live in `sap-tutorials/Tutorials` on `master`, but some are in other repos (e.g. `appstudio-onboarding` → `sap-tutorials/btp-adai` on `main`). If a URL returns 404, check the tutorial's GitHub link on `developers.sap.com`.
 
 **Key files:**
 
@@ -115,8 +117,5 @@ Exercise READMEs link to SAP tutorials on `developers.sap.com`. The VitePress bu
 | `docs/.vitepress/external-tutorials.config.ts` | Config map: tutorial ID → raw GitHub URL |
 | `docs/.vitepress/plugins/external-tutorials.ts` | Vite plugin: fetches tutorials at build start |
 | `docs/.vitepress/plugins/md-expand-tutorials.ts` | markdown-it plugin: substitutes link blocks with expanded content |
-| `docs/.vitepress/plugins/transform-tutorial.ts` | Pure transform pipeline: strips frontmatter/intro, rewrites image paths and cross-links, shifts headings |
-| `docs/.vitepress/plugins/transform-tutorial.test.ts` | 13 unit tests for the transform pipeline |
-| `docs/.vitepress/plugins/md-expand-tutorials.test.ts` | 7 unit tests for the expansion/detection logic |
-
-**Note:** Most tutorials live in `sap-tutorials/Tutorials` on `master`, but some have moved to other repos (e.g. `appstudio-onboarding` is in `sap-tutorials/btp-adai` on `main`). If a raw URL returns 404, check the tutorial's GitHub link on the `developers.sap.com` page to find the correct repo and branch.
+| `docs/.vitepress/plugins/transform-tutorial.ts` | Pure transform: strips frontmatter, rewrites images/links, shifts headings |
+| `docs/.vitepress/plugins/*.test.ts` | 23 unit tests (13 transform + 10 expansion/detection) |