feat: Update Docusaurus ebook manual to reflect Atlas integration and current pipeline

aiprompts/docusaurus/docusaurus_ebook_manual.md

@@ -8,7 +8,7 @@ To effectively create ebooks with HeroLib, it's crucial to understand the interp
 
 * **HeroScript**: A concise scripting language used to define the structure, configuration, and content flow of your Docusaurus site. It acts as the declarative interface for the entire process.
 * **Docusaurus**: A popular open-source static site generator. HeroLib uses Docusaurus as the underlying framework to render your ebook content into a navigable website.
-* **Doctree**: HeroLib's content management system. Doctree organizes your markdown files into "collections" and "pages," allowing for structured content retrieval and reuse across multiple projects.
+* **Atlas (and Doctree)**: HeroLib's document collection layer. In the current pipeline, Atlas exports markdown "collections" and "pages" that Docusaurus consumes via the Atlas client. Doctree and `doctreeclient` are legacy/alternative ways to provide the same collections.
 
 ## 2. Setting Up a Docusaurus Project with HeroLib
 
@@ -22,18 +22,26 @@ The `docusaurus.define` HeroScript directive configures the global settings for
 
 ```heroscript
 !!docusaurus.define
+    name:"my_ebook"                  // must match the site name from !!site.config
     path_build: "/tmp/my_ebook_build"
     path_publish: "/tmp/my_ebook_publish"
-    production: true
-    update: true
+    reset: true                      // clean build dir before building (optional)
+    install: true                    // run bun install if needed (optional)
+    template_update: true            // update the Docusaurus template (optional)
+    atlas_dir: "/tmp/atlas_export"   // where Atlas exports collections
+    use_atlas: true                  // use Atlas as content backend
 ```
 
 **Arguments:**
 
+* `name` (string, required): The site/factory name. Must match the `name` used in `!!site.config` so Docusaurus can find the corresponding site definition.
 * `path_build` (string, optional): The local path where the Docusaurus site will be built. Defaults to `~/hero/var/docusaurus/build`.
 * `path_publish` (string, optional): The local path where the final Docusaurus site will be published (e.g., for deployment). Defaults to `~/hero/var/docusaurus/publish`.
-* `production` (boolean, optional): If `true`, the site will be built for production (optimized). Default is `false`.
-* `update` (boolean, optional): If `true`, the Docusaurus template and dependencies will be updated. Default is `false`.
+* `reset` (boolean, optional): If `true`, clean the build directory before starting.
+* `install` (boolean, optional): If `true`, run dependency installation (e.g., `bun install`).
+* `template_update` (boolean, optional): If `true`, update the Docusaurus template.
+* `atlas_dir` (string, optional): Directory where Atlas exports collections (used by the Atlas client in `lib/data/atlas/client`).
+* `use_atlas` (boolean, optional): If `true`, use the Atlas client as the content backend (default behavior).
 
 ### 2.2. Adding a Docusaurus Site (`docusaurus.add`)
 
@@ -190,18 +198,18 @@ Configure the footer section of your Docusaurus site.
   * `href` (string, optional): External URL for the link.
   * `to` (string, optional): Internal Docusaurus path.
 
-### 3.4. Build Destinations (`site.build_dest`, `site.build_dest_dev`)
+### 3.4. Publish Destinations (`site.publish`, `site.publish_dev`)
 
 Specify where the built Docusaurus site should be deployed. This typically involves an SSH connection defined elsewhere (e.g., `!!site.ssh_connection`).
 
 **HeroScript Example:**
 
 ```heroscript
-!!site.build_dest
+!!site.publish
     ssh_name:"production_server" // Name of a pre-defined SSH connection
-    path:"/var/www/my-ebook" // Remote path on the server
+    path:"/var/www/my-ebook"     // Remote path on the server
 
-!!site.build_dest_dev
+!!site.publish_dev
     ssh_name:"dev_server"
     path:"/tmp/dev-ebook"
 ```
@@ -265,22 +273,29 @@ This is where you define the actual content pages and how they are organized int
   * `draft` (boolean, optional): If `true`, the page will be marked as a draft and not included in production builds.
   * `title_nr` (int, optional): If set, HeroLib will re-number the markdown headings (e.g., `title_nr:3` will make `# Heading` become `### Heading`). Useful for consistent heading levels across imported content.
 
-### 3.7. Doctree Integration Details
+### 3.7. Collections and Atlas/Doctree Integration
 
-The `site.page` directive's `src` parameter (`collection_name:page_name`) is the bridge to your Doctree content.
+The `site.page` directive's `src` parameter (`collection_name:page_name`) is the bridge to your content collections.
 
-**How Doctree Works:**
+**Current default: Atlas export**
+
+1. **Collections**: Atlas exports markdown files into collections under an `export_dir` (see `lib/data/atlas/client`).
+2. **Export step**: A separate process (Atlas) writes the collections into `atlas_dir` (e.g., `/tmp/atlas_export`), following the `content/` + `meta/` structure.
+3. **Docusaurus consumption**: The Docusaurus module uses the Atlas client (`atlas_client`) to resolve `collection_name:page_name` into markdown content and assets when generating docs.
+
+**Alternative: Doctree/`doctreeclient`**
+
+In older setups, or when explicitly configured, Doctree and `doctreeclient` can still be used to provide the same `collection:page` model:
 
 1. **Collections**: Doctree organizes markdown files into logical groups called "collections." A collection is typically a directory containing markdown files and an empty `.collection` file.
-2. **Scanning**: You define which collections Doctree should scan using `!!doctree.scan` in a HeroScript file (e.g., `doctree.heroscript`).
-    **Example `doctree.heroscript`:**
+2. **Scanning**: You define which collections Doctree should scan using `!!doctree.scan` in a HeroScript file (e.g., `doctree.heroscript`):
 
     ```heroscript
-    !!doctree.scan git_url:"https://git.threefold.info/tfgrid/docs_tfgrid4/src/branch/main/collections"
+    !!doctree.scan git_url:"https://git.ourworld.tf/tfgrid/docs_tfgrid4/src/branch/main/collections"
     ```
 
     This will pull the `collections` directory from the specified Git URL and make its contents available to Doctree.
-3. **Page Retrieval**: When `site.page` references `src:"my_collection:my_page"`, HeroLib's `doctreeclient` fetches the content of `my_page.md` from the `my_collection` collection that Doctree has scanned.
+3. **Page Retrieval**: When `site.page` references `src:"my_collection:my_page"`, the client (`atlas_client` or `doctreeclient`, depending on configuration) fetches the content of `my_page.md` from the `my_collection` collection.
 
 ## 4. Building and Developing Your Ebook