docs: make the blank-screen-after-navigation pitfall prominent for AI agents

- agent.md: warning box in the lifecycle section, new hard-rules table
  entry and an extra sentence in the ready-made AI prompt - always call
  view_display( ) in the check_on_navigated branch
- add public/llms.txt so AI crawlers and assistants pick up the agent
  briefing and this pitfall directly from the site root

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018pLmFwyFsNPqgaKMDjdG2s

Author: claude

docs/advanced/agent.md

@@ -63,6 +63,10 @@ ENDIF.
 
 → [Life Cycle](/cookbook/event_navigation/life_cycle)
 
+::: warning The #1 lifecycle bug: blank screen after navigation
+Always call `view_display( )` in the `check_on_navigated( )` branch. When a called sub-app took over the screen and returns via `nav_app_leave( )`, the browser still shows the sub-app's view — the framework does not restore the previous view automatically. All class attributes survived the roundtrip serialization, so no data re-read is needed — just render the view again. Skipping this leaves the user on a blank or stale screen after navigating back.
+:::
+
 #### 3. State lives in **public** class attributes
 
 Anything bound to the view must be `PUBLIC`. The framework serializes public attributes between roundtrips automatically — no session handling needed.
@@ -250,7 +254,7 @@ When an AI needs deeper information than this page provides:
 
 A prompt that gives an AI assistant enough context to produce a working app:
 
-> You are building an abap2UI5 app. Read <https://abap2ui5.github.io/docs/advanced/agent.html> first — it is the single source of truth for app-building (template, client API, lifecycle, view builder, deprecated controls, documentation map). For working examples, browse <https://github.com/abap2UI5/samples/tree/main/src> (250+ apps, one feature per app). Use `z2ui5_cl_util_xml` as the view builder. Look up any UI5 control at <https://ui5.sap.com/#/api> and translate the XML 1:1 to ABAP. Do not use any control listed in this page's "Deprecated UI5 Controls" section.
+> You are building an abap2UI5 app. Read <https://abap2ui5.github.io/docs/advanced/agent.html> first — it is the single source of truth for app-building (template, client API, lifecycle, view builder, deprecated controls, documentation map). For working examples, browse <https://github.com/abap2UI5/samples/tree/main/src> (250+ apps, one feature per app). Use `z2ui5_cl_util_xml` as the view builder. Look up any UI5 control at <https://ui5.sap.com/#/api> and translate the XML 1:1 to ABAP. Do not use any control listed in this page's "Deprecated UI5 Controls" section. Always call `view_display( )` in the `check_on_navigated( )` branch — otherwise the screen is blank after returning from a called sub-app.
 
 ## Hard Rules (Cheat Sheet)
 
@@ -259,6 +263,7 @@ A prompt that gives an AI assistant enough context to produce a working app:
 | Implement `z2ui5_if_app` with a single `main` method | The only entry point the framework calls |
 | Bound attributes must be `PUBLIC` | The framework binds via dynamic ASSIGN; `PROTECTED`/`PRIVATE` are silently ignored |
 | Use `IF` / `ELSEIF` with `check_on_init` / `check_on_event( 'NAME' )` / `check_on_navigated` | Canonical dispatcher pattern |
+| Always call `view_display( )` in the `check_on_navigated` branch | The browser still shows the called sub-app's view after `nav_app_leave( )` — without a re-display the screen stays blank |
 | Use `z2ui5_cl_util_xml` for AI-generated views | Maps 1:1 to UI5 SDK; no wrapper to learn |
 | Pass XML boolean attributes as string literals `'true'` / `'false'` | `abap_true` / `abap_false` produce invalid or empty attributes |
 | Use backtick string literals (`` ` ``), not single quotes | Project-wide convention enforced by abaplint |

docs/public/llms.txt

@@ -0,0 +1,23 @@
+# abap2UI5
+
+> abap2UI5 is an open-source framework for building SAP UI5 apps purely in ABAP — no JavaScript, OData or RAP required. An app implements the interface `z2ui5_if_app` with a single `main( )` method; the framework calls it on every HTTP roundtrip.
+
+Key facts for AI assistants generating abap2UI5 apps:
+
+- The canonical AI briefing is https://abap2ui5.github.io/docs/advanced/agent.html — read it before generating any app code.
+- Dispatch inside `main( )` with `IF` / `ELSEIF` over `client->check_on_init( )`, `client->check_on_navigated( )` and `client->check_on_event( 'NAME' )`.
+- CRITICAL — most common bug: always call `view_display( )` in the `check_on_navigated( )` branch. After returning from a sub-app called via `nav_app_call( )`, the browser still shows the sub-app's view — the framework does not restore the previous view automatically. App state survives the roundtrip serialization, so no data re-read is needed; only the view must be rendered again. Skipping this leaves a blank screen after navigating back.
+- Build views as UI5 XML strings with `z2ui5_cl_util_xml` (1:1 translation of UI5 SDK XML, recommended for AI) or `z2ui5_cl_xml_view` (fluent API).
+- Attributes bound with `_bind` / `_bind_edit` must be PUBLIC; use backtick string literals.
+
+## Docs
+
+- [AI Agent Briefing](https://abap2ui5.github.io/docs/advanced/agent.html): single source of truth for app-building (template, client API, lifecycle, view builders, deprecated controls)
+- [Life Cycle](https://abap2ui5.github.io/docs/cookbook/event_navigation/life_cycle.html): lifecycle checks and pitfalls, including the blank-screen-after-navigation bug
+- [Navigation](https://abap2ui5.github.io/docs/cookbook/event_navigation/navigation.html): cross-app navigation and re-displaying the view on return
+- [Quickstart](https://abap2ui5.github.io/docs/get_started/quickstart.html): installation and first app
+
+## Examples
+
+- [Samples repository](https://github.com/abap2UI5/samples): 250+ working demo apps, one feature per app
+- [Framework repository](https://github.com/abap2UI5/abap2UI5): core framework, architecture documented in AGENTS.md