docs: normalize structure, expand stubs, add production checklist

Sweep across the documentation to fix structural and consistency
issues that broke the VitePress sidebar outline and made navigation
uneven.

- Normalize heading hierarchy: every page now starts subsections at
  ## (was ### or #### in 60+ files), so the in-page outline renders.
- Standardize outline frontmatter to [2, 3] across the entire site.
- Standardize admonition style: drop bold in `::: tip **X**` headers.
- Refactor Quickstart with intro, prerequisites, and Next Steps.
- Add Next Steps footers to Getting Started pages (hello_world,
  samples) and clean up about.md layout (drop <br> hacks).
- Expand the stub pages advanced/local.md and advanced/stateful.md
  with When-to-Use / decision-table guidance.
- Add configuration/checklist.md as a linear path from dev install
  to production, and wire it into the sidebar/nav as the
  Configuration entry point.

https://claude.ai/code/session_011kvL4ihgqWYQa2SSufEaKv

Author: claude

docs/.vitepress/config.mjs

@@ -61,7 +61,7 @@ export default defineConfig({
         items: [
           { text: "Introduction", link: "/get_started/about" },
           { text: "Cookbook", link: "/development/general" },
-          { text: "Configuration", link: "/configuration/setup" },
+          { text: "Configuration", link: "/configuration/checklist" },
           { text: "Advanced Topics", link: "/advanced/downporting" },
           { text: "Technical Insights", link: "/technical/concept" },
           { text: "Resources", link: "/resources/addons" },
@@ -179,9 +179,10 @@ export default defineConfig({
       },
       {
         text: "Configuration",
-        link: "/configuration/setup",
+        link: "/configuration/checklist",
         collapsed: true,
         items: [
+          { text: "Production Checklist", link: "/configuration/checklist" },
           { text: "General", link: "/configuration/setup" },
           { text: "Security", link: "/configuration/security" },
           { text: "Authorization", link: "/configuration/authorization" },

docs/advanced/builds.md

@@ -1,5 +1,5 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Builder
 
@@ -8,7 +8,7 @@ For heavy abap2UI5 use, consider building your own version by defining a custom
 - Install multiple instances of abap2UI5 and upgrade each one at its own pace.
 - Build a custom abap2UI5 release with frontend components and add-ons matched to your needs.
 
-#### Builder
+## Builder
 Make your own abap2UI5 build with the [builder](https://github.com/abap2UI5/builder).
 
 <img width="700" alt="abap2UI5 builder interface for generating custom namespaced builds" src="https://github.com/user-attachments/assets/7c7f55d4-6667-4036-bc71-4cd7472f2ae9" />

docs/advanced/downporting.md

@@ -1,11 +1,11 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Downporting
 
 abap2UI5 works right away on ABAP 7.50 and later. On an earlier release, install the downported version, which supports R/3 NetWeaver 7.02 and later.
 
-#### Branch
+## Branch
 To install on an older system, use the `702` branch:
 | Branch    | System                |
 |-----------| ----------------------------|
@@ -14,5 +14,5 @@ To install on an older system, use the `702` branch:
 
 Some sample projects and other repositories also ship a downported version. Check whether a `702` branch is available.
 
-#### Functionality
+## Functionality
 For more on the downport feature, see the blog post [Running abap2UI5 on older R/3 Releases](https://www.linkedin.com/pulse/running-abap2ui5-older-r3-releases-downport-compatibility-abaplint-mjkle).

docs/advanced/extensibility/custom_control.md

@@ -1,16 +1,16 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Custom Controls
 
 You can build your own UI5 custom controls and use them in abap2UI5 apps.
 
 First, set up your VS Code environment with the abap2UI5 frontend artifacts, following the [Frontend](/advanced/extensibility/frontend) page.
 
-#### Frontend
+## Frontend
 
 Write the JS code for your new custom control. Copy an existing control from [App.controller.js](https://github.com/abap2UI5/abap2UI5/blob/main/app/webapp/controller/App.controller.js) and adapt it.
 
-#### Backend
+## Backend
 Extend the custom control view class by adding a method and defining the new control's properties:
 [z2ui5_cl_xml_view_cc.clas.abap](https://github.com/abap2UI5/abap2UI5/blob/main/src/02/z2ui5_cl_xml_view_cc.clas.abap)

docs/advanced/extensibility/custom_js.md

@@ -1,5 +1,5 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Custom JS
 

docs/advanced/extensibility/frontend.md

@@ -1,11 +1,11 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Frontend
 
 The abap2UI5 frontend artifacts live in the `app` folder. To adjust them:
 
-#### Setup
+## Setup
 Open VS Code (or your editor of choice), then run in the terminal:
 ```sh
 git clone https://github.com/abap2UI5/abap2UI5
@@ -15,7 +15,7 @@ Point all three files to your ABAP backend system:
 
 <img width="400" alt="Frontend config files where the backend system URL must be replaced" src="https://github.com/user-attachments/assets/155c9a3f-8a0a-494b-8fc4-a4bba2bf0e90">
 
-#### Build & Test
+## Build & Test
 Set the backend system in the YAML files.<br>
 Replace `/sap/bc/z2ui5` with your endpoint in the manifest, then run:
 ```sh
@@ -25,7 +25,7 @@ npm run start-noflp
 You'll see output like this:
 <img width="1000" alt="npm run start-noflp output showing the local dev server running" src="https://github.com/user-attachments/assets/3e0118e8-d05f-48d1-bcc0-28073adf6e47">
 
-#### Before PR (Optional)
+## Before PR (Optional)
 Convert the UI5 app to stringified ABAP:
 ```sh
 cd ..

docs/advanced/extensibility/user_exits.md

@@ -1,5 +1,5 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # User Exits
 

docs/advanced/fiori.md

@@ -1,13 +1,13 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Integration into Fiori Elements Apps
 
 Extend the object page of a Fiori list report app with an abap2UI5 app. See the [ABAP2UI5_COMP_CONT repository](https://github.com/axelmohnen/ABAP2UI5_COMP_CONT) for a complete example.
 
 <img width="747" height="387" alt="abap2UI5 app embedded in Fiori Elements object page" src="https://github.com/user-attachments/assets/c14d5732-3b8c-4fa5-83ab-6d188a4d87db" />
 
-### Guide
+## Guide
 
 1. Register the FLP integration in the component.js:
 

docs/advanced/local.md

@@ -1,8 +1,25 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Local
 
-abap2UI5-local is a special build that bundles all artifacts into a single HTTP handler. Create one extra database table, and you can run abap2UI5 independently of any other installation on the system.
+`abap2UI5-local` is a special build that bundles all framework artifacts into a single HTTP handler class. With one additional database table for session storage, you can run abap2UI5 self-contained — no separate framework installation required.
 
-For full details, see the repository: [abap2UI5-local](https://github.com/abap2UI5/abap2UI5-local)
+For full sources and the latest build, see the [abap2UI5-local repository](https://github.com/abap2UI5/abap2UI5-local).
+
+## When to Use
+
+- **Restricted systems** — environments where you cannot install full abap2UI5 via abapGit but can still create a class and an HTTP handler.
+- **Demos and PoCs** — drop a single class into a sandbox system and have a working UI5 app within minutes.
+- **Distribution** — ship a self-contained app that does not depend on an existing abap2UI5 installation on the target system.
+
+## When Not to Use
+
+- **Productive multi-app setups** — for systems running several abap2UI5 apps, the standard installation is leaner: one shared framework instead of a copy embedded into every handler.
+- **Frequent framework updates** — `abap2UI5-local` is a generated build. Updating means replacing the bundled class instead of pulling abapGit changes.
+
+## How It Works
+
+The `abap2UI5-local` build is produced by [abapmerge](/technical/tools/abapmerge): all framework classes are merged into one class. You install that class plus a database table for session storage, then point an HTTP service at it the same way as in the [Quickstart](/get_started/quickstart).
+
+The resulting app behaves like any other abap2UI5 app — same APIs, same view DSL, same event flow. The difference is purely in how the framework reaches the system.

docs/advanced/renaming.md

@@ -1,5 +1,5 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Renaming
 
@@ -10,7 +10,7 @@ The entire abap2UI5 project lives under the `z2ui5` namespace. You may need to r
 
 abap2UI5 works with the abaplint renaming feature and supports namespaces up to 9 characters, e.g., `zabap2ui5`.
 
-#### Functionality
+## Functionality
 For more on renaming ABAP artifacts, see:
 [Automagic standalone renaming of ABAP objects](https://community.sap.com/t5/application-development-blog-posts/automagic-standalone-renaming-of-abap-objects/ba-p/13499851)