diff --git a/aiprompts/README.md b/aiprompts/README.md new file mode 100644 index 00000000..472dee5d --- /dev/null +++ b/aiprompts/README.md @@ -0,0 +1,77 @@ +# HeroLib AI Prompts (`aiprompts/`) + +This directory contains AI-oriented instructions and manuals for working with the Hero tool and the `herolib` codebase. + +It is the **entry point for AI agents** that generate or modify code/docs in this repository. + +## Scope + +- **Global rules for AI and V/Hero usage** + See: + - `herolib_start_here.md` + - `vlang_herolib_core.md` +- **Herolib core modules** + See: + - `herolib_core/` (core HeroLib modules) + - `herolib_advanced/` (advanced topics) +- **Docusaurus & Site module (Hero docs)** + See: + - `docusaurus/docusaurus_ebook_manual.md` + - `lib/web/docusaurus/README.md` (authoritative module doc) + - `lib/web/site/ai_instructions.md` and `lib/web/site/readme.md` +- **HeroModels / HeroDB** + See: + - `ai_instructions_hero_models.md` + - `heromodel_instruct.md` +- **V language & web server docs** (upstream-style, mostly language-level) + See: + - `v_core/`, `v_advanced/` + - `v_veb_webserver/` + +## Sources of Truth + +For any domain, **code and module-level docs are authoritative**: + +- Core install & usage: `herolib/README.md`, scripts under `scripts/` +- Site module: `lib/web/site/ai_instructions.md`, `lib/web/site/readme.md` +- Docusaurus module: `lib/web/docusaurus/README.md`, `lib/web/docusaurus/*.v` +- Atlas client: `lib/data/atlas/client/README.md` +- HeroModels: `lib/hero/heromodels/*.v` + tests + +`aiprompts/` files **must not contradict** these. When in doubt, follow the code / module docs first and treat prompts as guidance. + +## Directory Overview + +- `herolib_start_here.md` / `vlang_herolib_core.md` + Global AI rules and V/Hero basics. +- `herolib_core/` & `herolib_advanced/` + Per-module instructions for core/advanced HeroLib features. +- `docusaurus/` + AI manual for building Hero docs/ebooks with the Docusaurus + Site + Atlas pipeline. +- `instructions/` + Active, higher-level instructions (e.g. HeroDB base filesystem). +- `instructions_archive/` + **Legacy / historical** prompt material. See `instructions_archive/README.md`. +- `todo/` + Meta design/refactor notes (not up-to-date instructions for normal usage). +- `v_core/`, `v_advanced/`, `v_veb_webserver/` + V language and web framework references used when generating V code. +- `bizmodel/`, `unpolly/`, `doctree/`, `documentor/` + Domain-specific or feature-specific instructions. + +## How to Treat Legacy Material + +- Content under `instructions_archive/` is **kept for reference** and may describe older flows (e.g. older documentation or prompt pipelines). + Do **not** use it as a primary source for new work unless explicitly requested. +- Some prompts mention **Doctree**; the current default docs pipeline uses **Atlas**. Doctree/`doctreeclient` is an alternative/legacy backend. + +## Guidelines for AI Agents + +- Always: + - Respect global rules in `herolib_start_here.md` and `vlang_herolib_core.md`. + - Prefer module docs under `lib/` when behavior or parameters differ. + - Avoid modifying generated files (e.g. `*_ .v` or other generated artifacts) as instructed. +- When instructions conflict, resolve as: + 1. **Code & module docs in `lib/`** + 2. **AI instructions in `aiprompts/`** + 3. **Archived docs (`instructions_archive/`) only when explicitly needed**. diff --git a/aiprompts/ai_instructions_hero_models.md b/aiprompts/ai_instructions_hero_models.md index 5f4630b5..1142afb5 100644 --- a/aiprompts/ai_instructions_hero_models.md +++ b/aiprompts/ai_instructions_hero_models.md @@ -2,9 +2,9 @@ ## Overview -This document provides clear instructions for AI agents to create new HeroDB models similar to `message.v`. +This document provides clear instructions for AI agents to create new HeroDB models similar to `message.v`. These models are used to store structured data in Redis using the HeroDB system. -The message.v can be found in `lib/hero/heromodels/message.v`.s +The `message.v` example can be found in `lib/hero/heromodels/message.v`. ## Key Concepts @@ -108,7 +108,7 @@ Add your model to the ModelsFactory struct in `factory.v`: ```v pub struct ModelsFactory { pub mut: - messages DBCalendar + calendar DBCalendar // ... other models } ``` diff --git a/aiprompts/doctree/doctree_specs.md b/aiprompts/doctree/doctree_specs.md index d18e288c..56844580 100644 --- a/aiprompts/doctree/doctree_specs.md +++ b/aiprompts/doctree/doctree_specs.md @@ -1,3 +1,5 @@ +> NOTE: Atlas is the default document collections/export pipeline used by the current Docusaurus integration (see `lib/data/atlas/client`). The Doctree module described here is an alternative/legacy export mechanism that still exists but is not the primary path. Use Atlas by default unless you explicitly need Doctree. + # Doctree Export Specification ## Overview diff --git a/aiprompts/docusaurus/docusaurus_ebook_manual.md b/aiprompts/docusaurus/docusaurus_ebook_manual.md index bd0b2073..ad2a8166 100644 --- a/aiprompts/docusaurus/docusaurus_ebook_manual.md +++ b/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`) @@ -53,7 +61,7 @@ The `docusaurus.add` directive defines an individual Docusaurus site (your ebook ```heroscript !!docusaurus.add name:"tfgrid_tech_ebook" - git_url:"https://git.threefold.info/tfgrid/docs_tfgrid4/src/branch/main/ebooks/tech" + git_url:"https://git.ourworld.tf/tfgrid/docs_tfgrid4/src/branch/main/ebooks/tech" git_reset:true // Reset Git repository before pulling git_pull:true // Pull latest changes git_root:"/tmp/git_clones" // Optional: specify a root directory for git clones @@ -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" ``` @@ -219,7 +227,7 @@ This powerful feature allows you to pull markdown content and assets from other ```heroscript !!site.import - url:'https://git.threefold.info/tfgrid/docs_tfgrid4/src/branch/main/collections/cloud_reinvented' + url:'https://git.ourworld.tf/tfgrid/docs_tfgrid4/src/branch/main/collections/cloud_reinvented' dest:'cloud_reinvented' // Destination subdirectory within your Docusaurus docs folder replace:'NAME:MyName, URGENCY:red' // Optional: comma-separated key:value pairs for text replacement ``` @@ -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 diff --git a/aiprompts/herolib_core/core_heroscript_basics.md b/aiprompts/herolib_core/core_heroscript_basics.md index c5ed9c77..293ba897 100644 --- a/aiprompts/herolib_core/core_heroscript_basics.md +++ b/aiprompts/herolib_core/core_heroscript_basics.md @@ -35,11 +35,11 @@ pub fn play(mut plbook PlayBook) ! { if plbook.exists_once(filter: 'docusaurus.define') { mut action := plbook.get(filter: 'docusaurus.define')! mut p := action.params - //example how we get parameters from the action see core_params.md for more details - ds = new( - path: p.get_default('path_publish', '')! - production: p.get_default_false('production') - )! + //example how we get parameters from the action see aiprompts/herolib_core/core_params.md for more details + path_build := p.get_default('path_build', '')! + path_publish := p.get_default('path_publish', '')! + reset := p.get_default_false('reset') + use_atlas := p.get_default_false('use_atlas') } // Process 'docusaurus.add' actions to configure individual Docusaurus sites @@ -51,4 +51,4 @@ pub fn play(mut plbook PlayBook) ! { } ``` -For detailed information on parameter retrieval methods (e.g., `p.get()`, `p.get_int()`, `p.get_default_true()`), refer to `aiprompts/ai_core/core_params.md`. +For detailed information on parameter retrieval methods (e.g., `p.get()`, `p.get_int()`, `p.get_default_true()`), refer to `aiprompts/herolib_core/core_params.md`. diff --git a/aiprompts/instructions/herodb_base_fs.md b/aiprompts/instructions/herodb_base_fs.md index 2a098b9c..fa6f1198 100644 --- a/aiprompts/instructions/herodb_base_fs.md +++ b/aiprompts/instructions/herodb_base_fs.md @@ -1,3 +1,5 @@ +> NOTE: This document is an example snapshot of a developer's filesystem layout for HeroDB/HeroModels. Paths under `/Users/despiegk/...` are illustrative only. For the current, authoritative structure always use the live repository tree (this checkout) and the modules under `lib/hero/heromodels` and `lib/hero/db`. + /Users/despiegk/code/github/incubaid/herolib ├── .github diff --git a/aiprompts/instructions_archive/README.md b/aiprompts/instructions_archive/README.md new file mode 100644 index 00000000..2cf6d6d4 --- /dev/null +++ b/aiprompts/instructions_archive/README.md @@ -0,0 +1,15 @@ +# Instructions Archive (Legacy Prompts) + +This directory contains **archived / legacy AI prompt material** for `herolib`. + +- Files here may describe **older workflows** (e.g. previous documentation generation or model pipelines). +- They are kept for **historical reference** and to help understand how things evolved. +- They are **not** guaranteed to match the current `herolib` implementation. + +## Usage Guidelines + +- Do **not** use these files as the primary source for new features or refactors. +- When generating code or documentation, prefer: + 1. Code and module docs under `lib/` (e.g. `lib/web/site/ai_instructions.md`, `lib/web/docusaurus/README.md`). + 2. Up-to-date AI instructions under `aiprompts/` (outside of `instructions_archive/`). +- Only consult this directory when you explicitly need to understand **historical behavior** or migrate old flows. diff --git a/aiprompts/vlang_herolib_core.md b/aiprompts/vlang_herolib_core.md index d57d39f8..e1e77cf0 100644 --- a/aiprompts/vlang_herolib_core.md +++ b/aiprompts/vlang_herolib_core.md @@ -122,12 +122,12 @@ pub fn play(mut plbook PlayBook) ! { if plbook.exists_once(filter: 'docusaurus.define') { mut action := plbook.get(filter: 'docusaurus.define')! mut p := action.params - //example how we get parameters from the action see core_params.md for more details - ds = new( - path: p.get_default('path_publish', '')! - production: p.get_default_false('production') - )! - } + //example how we get parameters from the action see aiprompts/herolib_core/core_params.md for more details + path_build := p.get_default('path_build', '')! + path_publish := p.get_default('path_publish', '')! + reset := p.get_default_false('reset') + use_atlas := p.get_default_false('use_atlas') + } // Process 'docusaurus.add' actions to configure individual Docusaurus sites actions := plbook.find(filter: 'docusaurus.add')! @@ -138,7 +138,7 @@ pub fn play(mut plbook PlayBook) ! { } ``` -For detailed information on parameter retrieval methods (e.g., `p.get()`, `p.get_int()`, `p.get_default_true()`), refer to `aiprompts/ai_core/core_params.md`. +For detailed information on parameter retrieval methods (e.g., `p.get()`, `p.get_int()`, `p.get_default_true()`), refer to `aiprompts/herolib_core/core_params.md`. # PlayBook, process heroscripts