Merge pull request #49 from abap2UI5/claude/improve-docs-nwiCf

Claude/improve docs nwi cf

Author: oblomov-dev

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" },
@@ -243,18 +244,31 @@ export default defineConfig({
           { text: "UI5 Over-the-Wire", link: "/technical/concept" },
           { text: "ABAP Thinking, UI5 Results", link: "/technical/dx" },
           { text: "Cloud Readiness", link: "/technical/cloud" },
-          { text: "Behind the Scenes", link: "/technical/how_it_all_works" },
           {
-            text: "Technology",
+            text: "Deep Dive",
+            link: "/technical/how_it_all_works",
+            collapsed: false,
+            items: [
+              { text: "Behind the Scenes", link: "/technical/how_it_all_works" },
+              { text: "1. Foundations", link: "/technical/deep_dive/foundations" },
+              { text: "2. The abap2UI5 Architecture", link: "/technical/deep_dive/architecture" },
+              { text: "3. Inside an App", link: "/technical/deep_dive/lifecycle" },
+              { text: "4. Trade-offs and Compatibility", link: "/technical/deep_dive/tradeoffs" },
+            ],
+          },
+          {
+            text: "Comparisons",
             link: "/technical/technology/overview",
+            collapsed: true,
             items: [
-              { text: "RAP", link: "/technical/technology/rap" },
-              { text: "UI5 Freestyle", link: "/technical/technology/ui5" },
+              { text: "Technology Overview", link: "/technical/technology/overview" },
+              { text: "RAP vs. abap2UI5", link: "/technical/technology/rap" },
+              { text: "UI5 Freestyle vs. abap2UI5", link: "/technical/technology/ui5" },
             ],
           },
           {
             text: "Tools",
-            collapsed: false,
+            collapsed: true,
             items: [
               { text: "abapGit", link: "/technical/tools/abapgit" },
               { text: "ajson", link: "/technical/tools/ajson" },
@@ -265,6 +279,7 @@ export default defineConfig({
               { text: "abapmerge", link: "/technical/tools/abapmerge" },
             ],
           },
+          { text: "Glossary", link: "/technical/glossary" },
         ],
       },
       {
@@ -273,6 +288,7 @@ export default defineConfig({
         collapsed: true,
         items: [
           { text: "Add-ons", link: "/resources/addons" },
+          { text: "Samples Index", link: "/resources/samples_index" },
           { text: "References", link: "/resources/references" },
           { text: "Who Uses abap2UI5?", link: "/resources/who_uses" },
           { text: "Releases", link: "/resources/changelog" },

docs/advanced/builds.md

@@ -1,5 +1,5 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Builder
 
@@ -8,7 +8,13 @@ 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" />
+
+## See Also
+
+- **[Renaming](/advanced/renaming)** — picking a custom namespace.
+- **[Local](/advanced/local)** — bundle the framework into a single class instead of a custom build.
+- **[abapmerge](/technical/tools/abapmerge)** — the merge tool used by the local build.

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,10 @@ 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).
+
+## See Also
+
+- **[Trade-offs and Compatibility](/technical/deep_dive/tradeoffs#compatibility-and-downporting)** — why abap2UI5 keeps a single codebase compatible with both Standard ABAP and ABAP Cloud.
+- **[abaplint](/technical/tools/abaplint)** — the tool that produces the `702` branch automatically.

docs/advanced/extensibility/custom_control.md

@@ -1,16 +1,22 @@
 ---
-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)
+
+## See Also
+
+- **[Inside an App → Sending JavaScript Over the Wire](/technical/deep_dive/lifecycle#sending-javascript-over-the-wire)** — the underlying mechanism that lets you ship JS to the frontend.
+- **[Custom JS](/advanced/extensibility/custom_js)** — for one-off JavaScript without building a full control.
+- **[Frontend](/advanced/extensibility/frontend)** — local setup for building and testing controls.

docs/advanced/extensibility/custom_js.md

@@ -1,5 +1,5 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Custom JS
 
@@ -30,3 +30,8 @@ Below is a starting point that works. The `_generic` method creates a custom XML
 
 ENDMETHOD.
 ```
+
+## See Also
+
+- **[Inside an App → Sending JavaScript Over the Wire](/technical/deep_dive/lifecycle#sending-javascript-over-the-wire)** — why this works and how the framework forwards JavaScript to the frontend.
+- **[Custom Control](/advanced/extensibility/custom_control)** — wrap reusable JS into proper UI5 controls.

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,9 +25,14 @@ 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 ..
 npm run auto_app2abap
 ```
+
+## See Also
+
+- **[Inside an App → The Initial Request](/technical/deep_dive/lifecycle#the-initial-request)** — why the static frontend shell lives as a string inside the HTTP handler.
+- **[Custom Control](/advanced/extensibility/custom_control)** — extend the shell with new UI5 controls.

docs/advanced/extensibility/user_exits.md

@@ -1,5 +1,5 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # User Exits
 
@@ -36,3 +36,9 @@ CLASS zcl_a2ui5_user_exit IMPLEMENTATION.
 
 ENDCLASS.
 ```
+
+## See Also
+
+- **[Inside an App → The Initial Request](/technical/deep_dive/lifecycle#the-initial-request)** — what `set_config_http_get` actually customizes.
+- **[Inside an App → Drafts](/technical/deep_dive/lifecycle#drafts-stateful-feel-stateless-backend)** — what `draft_exp_time_in_hours` controls under the hood.
+- **[General Setup](/configuration/setup)** — common things to configure via the user exit.

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:
 
@@ -88,3 +88,8 @@ On the ABAP side, the app receives the Fiori startup parameters (like the app cl
 
   ENDMETHOD.
 ```
+
+## See Also
+
+- **[RAP vs. abap2UI5](/technical/technology/rap)** — how the two approaches differ, and where they complement each other.
+- **[Fiori Launchpad](/configuration/launchpad)** — embedding standalone abap2UI5 apps in the launchpad (as opposed to inside an FE object page).

docs/advanced/local.md

@@ -1,8 +1,31 @@
 ---
-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.
+
+## See Also
+
+- **[abapmerge](/technical/tools/abapmerge)** — the tool that produces the local build.
+- **[Builder](/advanced/builds)** — for full custom builds with namespace + add-ons.
+- **[Trade-offs → System Footprint](/technical/deep_dive/tradeoffs#system-footprint)** — why the framework is small enough to bundle into a single class.

docs/advanced/renaming.md

@@ -1,5 +1,5 @@
 ---
-outline: [2, 4]
+outline: [2, 3]
 ---
 # Renaming
 
@@ -10,9 +10,14 @@ 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)
 
 For more background, see the blog post:
 [Renaming of ABAP Artifacts - The Power of abaplint and abapGit in ABAP Development](https://www.linkedin.com/pulse/renaming-abap-artifacts-power-abaplint-github-actions-development-kqede/).
+
+## See Also
+
+- **[abaplint](/technical/tools/abaplint)** — the tool that performs the rename.
+- **[Builder](/advanced/builds)** — for shipping a custom-namespaced abap2UI5 build.