Problem

The developer FAQ articles under docs/faq/ (view layer, access configuration, theme tokens, customer component library, i18n, upgrade 7.11 → 8.0, ...) were reachable only through the engine's CLAUDE.md. Many of them apply equally when building an application on top of the engine, but an application workspace has neither the engine's CLAUDE.md nor its docs/ folder. There, the articles were practically undiscoverable — for a developer as well as for an AI coding agent.

Solution

Developer documentation in the module jars

All articles ship in the jar of the module that owns the topic, below

<module>/src/main/java/META-INF/tl-docs/

• The path without .md is the article name, e.g. view-layer/tables.
• A folder is a chapter, described by its index.md. Folders of the same path in several modules form one chapter, so a module adds articles to the chapter of another one. A chapter page lists its entries automatically.
• Each file starts with a front matter block: description says when to read the article, the optional order places it in its chapter (entries without an order follow, all others are sorted by title).
• Articles link to each other with the doc: scheme and the article name relative to the documentation root, also across modules: [spacing](doc:view-layer/basics#spacing-model).

---
description: Read before configuring a <table> in a .view.xml ...
order: 60
---

# Tables

An application thus sees exactly the articles of the engine version and the modules it depends on. docs/faq/ is gone: the former React view layer FAQ is split into the chapter view-layer (14 articles from tl-layout-view and tl-react-flow-server, including articles on channels and flow diagrams migrated from design documents), the engine-only topics form the chapter engine ("Extending the engine"). The documentation model (com.top_logic.basic.docs.DevDocs: loading, chapters, rendering, checks) is part of tl-basic.

Consistency check

test.com.top_logic.basic.TestDocumentation runs in the TestAll of every module (like TestComment; switched by test-documentation) and checks the articles the module ships against its class path:

• every chapter and article has a description;
• every doc: link names an article on the class path and, if it names a section, a heading of that article — so an article links only to articles of its own module and of the modules it depends on;
• every #section link names a heading of the article itself;
• no link points to a file outside the documentation;
• no Markdown file is left in docs/faq/ of the workspace.

Documentation window

The development menu of the React UI has an entry "Documentation" (group "Reference", shown while UI inspection is switched on). It opens a side window with

• a tree of the chapters and articles with section numbers ("1.8 Tables") and a full-text search,
• the selected article rendered from Markdown (tables, a table of contents of its sections; a chapter lists its entries), titled with the file it comes from (tl-layout-view: META-INF/tl-docs/view-layer/tables.md),
• doc: links that select their target article and scroll to the section; external links open in a window of their own,
• the selected article in the URL of the window and a Back command; a jump to a section within an article is a history step of its own.

New reusable parts of the view layer:

• <html>: <on-link> command run for a link that carries its target in a data-tl-link attribute (allowed by the HTML safety check), instead of browser navigation; a #section link scrolls without changing the address of the page.
• <history-back/>: view action taking the window one step back in its history.
• pushLocalStep (tl-react-bridge): a history step within the displayed page, shown again by the client on back / forward without a server round trip.

AI agents

The tl-mcp server (tl-mcp-server 0.1.3) collects the documentation from the reactor sources and the dependency jars, serves it through the tools list_docs and read_doc (which takes a doc: link as it stands) and writes an index of all articles to target/tl-docs-index.md. A SessionStart hook of the tl-claude-tools plugin announces that index in every agent session.