docs(Maintain): expand README with comprehensive documentation

NikolaRHristov · NikolaRHristov · commit f474c383d0ec · 2026-04-05T09:10:35.000+03:00
Add extensive documentation to the Maintain component README including: Key Features section detailing Rhai scripting, configuration editing, and CLI capabilities; Core Architecture Principles table covering Scriptability, Type Safety, Modularity, and Environment Awareness; Land Ecosystem role mapping with Build Orchestrator, Scripting Host, Configuration Manager, and CLI Provider; Mermaid architecture diagram; Project Structure directory tree; Deep Dive section with source file references; Getting Started guide with installation instructions and usage patterns; expanded license explanation; and changelog reference.

Aligns with broader docs initiative to provide comprehensive onboarding documentation for the build system component.
diff --git a/README.md b/README.md
@@ -37,36 +37,85 @@ Land
 </tr>
 </table>
 
-
 ---
 
 # **Maintain**&#x2001;💪🏻
 
-> **Build pipelines that change behavior based on environment variables, implicit tool versions, or undeclared dependencies make debugging production issues impossible. The same commit produces different output on different machines.**
+The Build System & CI/CD Toolkit for Land 🏞️
+
+> **Build pipelines that change behavior based on environment variables,
+> implicit tool versions, or undeclared dependencies make debugging production
+> issues impossible. The same commit produces different output on different
+> machines.**
 
 _"Deterministic builds. Same commit, same output, guaranteed."_
 
 [![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://github.com/CodeEditorLand/Maintain/tree/Current/LICENSE)
-[![Crates.io](https://img.shields.io/crates/v/Maintain.svg)](https://crates.io/crates/Maintain)
-[![Rust Version](https://img.shields.io/badge/Rust-1.75+-orange.svg)](https://www.rust-lang.org/)
+[<img src="https://editor.land/Image/Rust.svg" width="14" alt="Rust" />](https://www.rust-lang.org/)&#x2001;[![Crates.io](https://img.shields.io/crates/v/Maintain.svg)](https://crates.io/crates/Maintain)
+[<img src="https://editor.land/Image/Rust.svg" width="14" alt="Rust" />](https://www.rust-lang.org/)&#x2001;[![Rust Version](https://img.shields.io/badge/Rust-1.75+-orange.svg)](https://www.rust-lang.org/)
 [![Rhai Version](https://img.shields.io/badge/Rhai-latest-blue.svg)](https://rhai.rs/)
 
-Maintain builds the entire Land ecosystem with Rhai scripting for flexible build logic, compile-time validated TOML and JSON5 configurations, and deterministic artifact generation. GritQL queries handle automated refactoring across the codebase. The same commit always produces the same output across all machines.
+📖
+**[Rust API Documentation](https://Rust.Documentation.Editor.Land/Maintain/)**
+
+Welcome to **Maintain**, the Rust-based build system and CI/CD toolkit for the
+**Land Code Editor** ecosystem. Maintain provides comprehensive build
+orchestration, Rhai scripting capabilities, and configuration management for
+TOML and JSON5 files.
+
+**Maintain** is engineered to:
+
+1. **Orchestrate Builds:** Provide a central build system for the entire Land
+   ecosystem with configurable build groups.
+2. **Enable Scripting:** Embed the Rhai scripting language for flexible build
+   logic and custom automation.
+3. **Manage Configuration:** Offer type-safe TOML and JSON5 editing capabilities
+   for Cargo.toml and other configuration files.
+4. **Provide CLI Interface:** Deliver a command-line interface for build
+   operations with environment variable resolution.
+
+---
+
+## Key Features&#x2001;🔐
 
-📖 **[Rust API Documentation](https://Rust.Documentation.Maintain.Editor.Land/)**
+- **Rhai Scripting Engine:** Embedded Rhai interpreter for flexible build
+  configuration and custom automation logic.
+- **Configuration Editing:** Type-safe TOML and JSON5 editing for Cargo.toml and
+  other configuration files with validation.
+- **Environment Resolution:** Dynamic environment variable handling with
+  scriptable resolvers for build-time configuration.
+- **CLI Interface:** Comprehensive command-line interface with subcommands for
+  build, debug, release, and profile operations.
+- **Build Orchestration:** Central coordination of multi-stage builds across the
+  Land ecosystem.
 
 ---
 
-## What It Does&#x2001;🔐
+## Core Architecture Principles&#x2001;🏗️
 
-- **Rhai scripting.** Flexible build logic without shell script fragility.
-- **Deterministic output.** Same commit, same artifacts, across all machines and CI environments.
-- **GritQL refactoring.** Automated codebase-wide refactoring with structural pattern matching.
-- **Compile-time config.** TOML and JSON5 configurations validated at build time.
+| Principle                 | Description                                                                               | Key Components Involved                  |
+| :------------------------ | :---------------------------------------------------------------------------------------- | :--------------------------------------- |
+| **Scriptability**         | Enable flexible build logic through embedded Rhai scripting with full environment access. | `Rhai/ConfigLoader`, `Rhai/ScriptRunner` |
+| **Type Safety**           | Provide compile-time checked configuration access with validation for TOML/JSON5.         | `toml_edit`, `json5` crates              |
+| **Modularity**            | Separate concerns between CLI, scripting, and configuration editing components.           | `CLI.rs`, `Rhai/`, `Build/*`             |
+| **Environment Awareness** | Dynamic resolution of environment variables for flexible build configurations.            | `EnvironmentResolver.rs`                 |
 
 ---
 
-## In the Ecosystem&#x2001;💪🏻 + 🏞️
+## `Maintain` in the Land Ecosystem&#x2001;💪🏻 + 🏞️
+
+| Component                 | Role & Key Responsibilities                                  |
+| :------------------------ | :----------------------------------------------------------- |
+| **Build Orchestrator**    | Central coordination of builds across all Land elements.     |
+| **Scripting Host**        | Rhai engine for custom build logic and automation.           |
+| **Configuration Manager** | TOML/JSON5 editing for Cargo.toml and project configuration. |
+| **CLI Provider**          | Command-line interface for developers and CI/CD pipelines.   |
+
+---
+
+## System Architecture Diagram&#x2001;🏗️
+
+This diagram illustrates `Maintain`'s build orchestration architecture.
 
 ```mermaid
 graph LR
@@ -106,18 +155,114 @@ ConfigEditor --> JSON5Config
 
 ---
 
-## Development&#x2001;🛠️
+## Project Structure&#x2001;🗺️
 
-Maintain is a component of the Land workspace. Follow the
-[Land Repository](https://github.com/CodeEditorLand/Land) instructions to
-build and run.
+```
+Element/Maintain/
+├── Source/
+│   ├── Library.rs       # Main entry point
+│   └── Build/
+│       ├── CLI.rs        # Command-line interface with clap
+│       ├── Constant.rs   # Build constants
+│       ├── Definition.rs # Build definitions
+│       ├── Fn.rs         # Build functions
+│       ├── Rhai/         # Rhai scripting engine
+│       │   ├── ConfigLoader.rs
+│       │   ├── EnvironmentResolver.rs
+│       │   └── ScriptRunner.rs
+│       └── ...
+├── Debug/                # Debug scripts
+│   ├── All.sh
+│   ├── Build.sh
+│   ├── Run.sh
+│   └── Wind.sh
+├── Debug.sh              # Debug mode execution
+├── Dev-Mountain.sh       # Mountain development mode
+├── Profile.sh            # Performance profiling
+└── Release.sh            # Release build
+```
 
 ---
 
-## License&#x2001;⚖️
+## Deep Dive & Component Breakdown&#x2001;🔬
+
+To understand how `Maintain`'s internal components interact to provide the build
+orchestration functionality, see the following source files:
+
+- **[`Source/Library.rs`](https://github.com/CodeEditorLand/Maintain/tree/Current/Source/Library.rs)** -
+  Main entry point and module declarations
+- **[`Source/Build/CLI.rs`](https://github.com/CodeEditorLand/Maintain/tree/Current/Source/Build/CLI.rs)** -
+  Command-line interface with clap
+- **[`Source/Build/Rhai/`](https://github.com/CodeEditorLand/Maintain/tree/Current/Source/Build/Rhai/)** -
+  Rhai scripting engine integration
+    - [`ConfigLoader.rs`](https://github.com/CodeEditorLand/Maintain/tree/Current/Source/Build/Rhai/ConfigLoader.rs) -
+      Configuration file loading
+    - [`EnvironmentResolver.rs`](https://github.com/CodeEditorLand/Maintain/tree/Current/Source/Build/Rhai/EnvironmentResolver.rs) -
+      Environment variable resolution
+    - [`ScriptRunner.rs`](https://github.com/CodeEditorLand/Maintain/tree/Current/Source/Build/Rhai/ScriptRunner.rs) -
+      Script execution engine
 
-CC0 1.0 Universal. Public domain. No restrictions.
-[LICENSE](https://github.com/CodeEditorLand/Maintain/tree/Current/LICENSE)
+The source files explain the Rhai scripting integration, TOML/JSON5 editing
+capabilities, and the build orchestration patterns.
+
+---
+
+## Getting Started&#x2001;🚀
+
+### Installation&#x2001;📥
+
+To add `Maintain` as a dependency:
+
+```toml
+[dependencies]
+Maintain = { git = "https://github.com/CodeEditorLand/Maintain.git", branch = "Current" }
+```
+
+Or install the CLI globally:
+
+```sh
+cargo install Maintain
+```
+
+**Key Dependencies:**
+
+- `rhai`: Embedded scripting engine
+- `clap`: CLI argument parsing
+- `toml_edit`: TOML parsing and editing
+- `json5`: JSON5 configuration support
+- `chrono`: Date/time handling
+- `colored`: Colored terminal output
+- `log` / `env_logger`: Logging framework
+
+### Usage Pattern&#x2001;🚀
+
+`Maintain` is typically invoked through its included shell scripts:
+
+```sh
+# Debug build
+./Maintain/Debug.sh
+
+# Development mode for Mountain
+./Maintain/Dev-Mountain.sh
+
+# Release build
+./Maintain/Release.sh
+```
+
+As a binary:
+
+```sh
+Maintain [OPTIONS] [COMMAND]
+```
+
+As a library:
+
+```rust
+use Maintain::Build;
+
+let Build = Build::new();
+Build.execute()?;
+```
 
 ---
 
@@ -130,12 +275,33 @@ CC0 1.0 Universal. Public domain. No restrictions.
 - [Rest](https://github.com/CodeEditorLand/Rest)
 - [Output](https://github.com/CodeEditorLand/Output)
 
+---
+
+## License&#x2001;⚖️
+
+This project is released into the public domain under the **Creative Commons CC0
+Universal** license. You are free to use, modify, distribute, and build upon
+this work for any purpose, without any restrictions. For the full legal text,
+see the [`LICENSE`](https://github.com/CodeEditorLand/Maintain/tree/Current/)
+file.
+
+---
+
+## Changelog&#x2001;📜
+
+Stay updated with our progress! See
+[`CHANGELOG.md`](https://github.com/CodeEditorLand/Maintain/tree/Current/) for a
+history of changes specific to **Maintain**.
+
+---
 
-## Funding & Acknowledgements 🙏🏻
+## Funding \& Acknowledgements&#x2001;🙏🏻
 
-Code Editor Land is funded through the NGI0 Commons Fund, established by NLnet
-with financial support from the European Commission's Next Generation Internet
-programme, under grant agreement No. 101135429.
+**Maintain** is a core element of the **Land** ecosystem. This project is funded
+through [NGI0 Commons Fund](https://NLnet.NL/commonsfund), a fund established by
+[NLnet](https://NLnet.NL) with financial support from the European Commission's
+[Next Generation Internet](https://ngi.eu) program. Learn more at the
+[NLnet project page](https://NLnet.NL/project/Land).
 
 The project is operated by PlayForm, based in Sofia, Bulgaria.
 
