LabNow-ai · haobibo · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026 · Jun 25, 2026
diff --git a/.agents/skills b/.agents/skills
@@ -0,0 +1 @@
+../doc/skills
diff --git a/.claude/skills b/.claude/skills
@@ -0,0 +1 @@
+../doc/skills
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1 @@
+../AGENTS.md
diff --git a/.github/skills b/.github/skills
@@ -0,0 +1 @@
+../doc/skills
diff --git a/.gitignore b/.gitignore
@@ -133,3 +133,7 @@ dmypy.json
 
 # Agents
 .codex
+
+# Generated README inside package folder
+pkg/README.md
+
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -1,35 +1,95 @@
 # Aloha
 
-## What is it?
-
-`aloha` is a versatile Python utility package for building microservices.
-
 [![License](https://img.shields.io/github/license/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/blob/main/LICENSE)
 [![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/LabNow-ai/aloha-python/build.yml?branch=main)](https://github.com/LabNow-ai/aloha-python/actions)
 [![PyPI version](https://img.shields.io/pypi/v/aloha)](https://pypi.python.org/pypi/aloha/)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/aloha)](https://pepy.tech/badge/aloha/)
 [![Code Activity](https://img.shields.io/github/commit-activity/m/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/pulse)
 [![Recent Code Update](https://img.shields.io/github/last-commit/LabNow-ai/aloha-python.svg)](https://github.com/LabNow-ai/aloha-python/stargazers)
 
+`aloha-python` is a modern project template (boilerplate) and a versatile utility library (`aloha` package) designed to build robust, containerized microservices in Python.
+
+---
+
 Please generously STAR★ our project or donate to us!
 [![GitHub Starts](https://img.shields.io/github/stars/LabNow-ai/aloha-python.svg?label=Stars&style=social)](https://github.com/LabNow-ai/aloha-python/stargazers)
 
 - To understand the package, read the [📚docs](https://aloha-python.readthedocs.io/) or [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/LabNow-ai/lab-foundation)
 
 - To contribute or talk to a human: [![Open an Issue on GitHub](https://img.shields.io/github/issues/LabNow-ai/aloha-python)](https://github.com/LabNow-ai/aloha-python/issues) [![Join the Discord Chat](https://img.shields.io/badge/Discuss_on-Discord-green)](https://discord.gg/kHUzgQxgbJ) [![Join the Gitter Chat](https://img.shields.io/gitter/room/nwjs/nw.js.svg)](https://gitter.im/LabNow-ai/)
 
+---
+
+## 🚀 Key Features
+
+- **Configuration Management (`aloha.config`)**: Lazy-loaded settings (`SETTINGS`) using HOCON (Human-Optimized Config Object Notation), supporting environment profile overrides (`ENV_PROFILE` / `FILES_CONFIG`) and environment variable injection.
+- **Concurrent-Safe Logging (`aloha.logger`)**: Multi-process safe daily rotating log file handler, console output, and automatic log paths configuration.
+- **Database Operators (`aloha.db`)**: Pre-built SQLAlchemy-backed connections for PostgreSQL, MySQL, SQLite, DuckDB, MongoDB, Redis, Elasticsearch, and Kafka, with password resolution via a secure `PasswordVault` wrapper.
+- **Encryption & Utilities (`aloha.encrypt`)**: Fast helpers for AES (ECB/CBC) encryption, RSA asymmetric key-pair generation/signatures, JWT encoding/decoding, and Base62 hashing.
+- **Testing Harness (`aloha.testing`)**: Extended `UnitTestCase` and integration `ServiceTestCase` structures for testing HTTP endpoints.
+- **Binary Code Protection (`aloha compile`)**: Utility compiler using Cython to package python source files (`.py`) into platform-native compiled dynamic libraries (`.so`/`.pyd`), protecting intellectual property.
+
+---
+
+## 📁 Repository Layout
+
+- **[`src/`](src)**: Application-specific codebase, configuration files (`src/resource/config/`), and unit/integration tests (`src/tests/`).
+- **[`pkg/`](pkg)**: The core `aloha` utility library source code.
+- **[`tool/`](tool)**: Local CI/CD files and setup helpers (e.g. docker-compose configurations, lifecycle scripts).
+- **[`doc/`](doc)**: Documentation files and AI Agent Skills.
+- **[`notebook/`](notebook)**: Jupyter notebooks for interactive analysis.
+
+---
+
+## 🛠️ Local Development Quick Start
+
+Local development is fully containerized using Docker & Docker Compose to maintain environment consistency.
+
+### 1. Launch Dev Container
 
-## Getting started
+Run the lifecycle helper script:
 
-Refer to 📚 [Document](https://aloha-python.readthedocs.io/) & [中文文档](https://aloha-python.readthedocs.io/zh-cn/main/) for detailed introduction.
+```bash
+# Check port availability and spin up the development container
+./tool/cicd/run-dev.sh up
 
-```shell
-pip install aloha[all]
+# Open an interactive terminal inside the container
+./tool/cicd/run-dev.sh enter
 ```
 
-And then:
+_Note: Development ports (`PORT_APP` and `PORT_WEB`) are dynamically computed based on your User ID (`UID`) to avoid conflicts on shared servers._
 
-```python
-from aloha.logger import LOG
-from aloha.settings import SETTINGS as S
+### 2. Run Tests
+
+Inside the running container terminal:
+
+```bash
+# Execute pytest suite
+pytest src/
+
+# Run tests with code coverage report
+pytest --cov=src src/
+```
+
+### 3. Production Packaging
+
+To build a production-ready Docker image with optional binary compilation enabled:
+
+```bash
+source tool/tool.sh
+build_image app_common latest src/app-demo.Dockerfile
 ```
+
+---
+
+## ✍️ Coding Guidelines
+
+When developing in this project, variables should place their **type or primary characteristics/role prefix first**:
+
+- _Correct_: `name_service`, `port_service`, `svc_ingress`, `cfg_postgres`.
+- _Incorrect_: `service_name`, `service_port`, `ingress_service`, `postgres_config`.
+
+For details on local setups, CI/CD specifications, and sub-module APIs, inspect our agent instruction files:
+
+- **[Aloha Python Skills Guide](doc/skills/aloha_python/SKILL.md)**
+- **[Aloha CI/CD & Scaffolding Guide](doc/skills/aloha_cicd/SKILL.md)**
diff --git a/doc/.readthedocs.yaml b/doc/.readthedocs.yaml
@@ -22,7 +22,6 @@ mkdocs:
 
 python:
   install:
-    - requirements: ./doc/requirements.txt
     - method: pip
       path: ./pkg
       extra_requirements:

diff --git a/doc/requirements.txt b/doc/requirements.txt
diff --git a/doc/skills/aloha_cicd/SKILL.md b/doc/skills/aloha_cicd/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: aloha-cicd
+description: Guides on project scaffolding, multi-agent setup, local containerized development via run-dev.sh, and building Docker images for production.
+---
+
+# Aloha Project Scaffolding and Docker CI/CD Skill
+
+This skill outlines the process for setting up boilerplate codebases, orchestrating containerized local development environments, and building production Docker images.
+
+---
+
+## 1. Project Scaffolding & Multi-Agent setup
+
+To set up your project folders and ensure consistent AI assistant behaviors (across Antigravity, Claude Code, and Copilot), refer to the **[Project Scaffolding & Multi-Agent Setup reference](doc/skills/aloha_cicd/references/scaffolding.md)**. This guide covers:
+
+- Core directory layout conventions (`src/`, `doc/`, `notebook/`, `tool/`).
+- Handing library isolation (excluding `pkg/` from new app template repositories).
+- Centralized rules (`AGENTS.md`) and centralized skills (`doc/skills/`) configuration via symlinks.
+
+---
+
+## 2. Local Development Environment
+
+To start, run, and enter the development container with auto-allocated user ports and volume mappings, refer to the **[Local Development Container & Compose reference](doc/skills/aloha_cicd/references/dev_env.md)**. This guide covers:
+
+- Lifecycle management using `./tool/cicd/run-dev.sh` (`up`, `enter`, `logs`, `restart`, `down`).
+- User-specific dynamic port calculation (`PORT_APP` and `PORT_WEB`).
+- Mounting credentials and setting the `PYTHONPATH`.
+- Specs for `dev-demo.Dockerfile` and shared DB compose configurations.
+
+---
+
+## 3. Production Compilation & Packaging
+
+To compile your code into binary extension libraries (`.so` files) and package them into a lightweight container image:
+
+1. **Production Dockerfile ([src/app-demo.Dockerfile](app-demo.Dockerfile))**:
+   - Uses a two-stage build layout.
+   - Converts normal Python `.py` files into binary dynamic libraries inside the builder stage (using `aloha compile`) if `ENABLE_CODE_BUILD="true"`.
+   - Packs compiled assets into a clean minimal environment, exposing `PORT_SVC` (default 80) and launching via `aloha start`.
+2. **Build Trigger Command**:
+   ```bash
+   source tool/tool.sh
+   build_image app_common latest src/app-demo.Dockerfile
+   ```
+
+---
+
+## 4. Running Tests & Code Coverage
+
+Tests are executed using `pytest` inside the running dev container:
+
+1. Start and enter the development container:
+   ```bash
+   ./tool/cicd/run-dev.sh up
+   ./tool/cicd/run-dev.sh enter
+   ```
+2. Run your tests from the root directory:
+
+   ```bash
+   # Run all unit and integration tests
+   pytest src/
+
+   # Run tests with code coverage report
+   pytest --cov=src src/
+   ```
diff --git a/doc/skills/aloha_cicd/references/dev_env.md b/doc/skills/aloha_cicd/references/dev_env.md
@@ -0,0 +1,40 @@
+# Local Development Container & Docker Compose
+
+This sub-module guides you through setting up and using the containerized local development environment via `docker-compose` and the `run-dev.sh` lifecycle helper.
+
+---
+
+## 1. Local Development Containerization (`run-dev.sh`)
+
+To guarantee environment consistency, local development is fully containerized. The `./tool/cicd/run-dev.sh` script manages this container.
+
+### Commands
+
+| Command                          | Action                                                                          |
+| :------------------------------- | :------------------------------------------------------------------------------ |
+| `./tool/cicd/run-dev.sh up`      | Checks port availability and starts the development container in detached mode. |
+| `./tool/cicd/run-dev.sh enter`   | Spawns an interactive bash terminal inside the running container.               |
+| `./tool/cicd/run-dev.sh logs`    | Tails and streams container logs to stdout.                                     |
+| `./tool/cicd/run-dev.sh restart` | Restarts the development container.                                             |
+| `./tool/cicd/run-dev.sh down`    | Stops and removes the development container.                                    |
+
+### Configuration Details
+
+- **User-Specific Port Mapping**: To prevent port clashes on shared, multi-user systems, host ports are computed dynamically using the user's numeric ID (`UID`):
+  - **Application Port (`PORT_APP`)**: `30000 + UID` (exposes port 9000).
+  - **Web Port (`PORT_WEB`)**: `33000 + UID` (exposes port 3000).
+- **Import Environments**: The container mounts the project root to `/root/app:rw` and automatically sets `PYTHONPATH=/root/app/pkg:/root/app/src:/root/app/notebook` for clean imports.
+- **Agent Credentials Mounts**: Volume-mounts local config directories (`~/.gemini`, `~/.claude`, `~/.copilot`) to keep credential cache and auth profiles active.
+
+---
+
+## 2. Docker Compose & Dockerfiles Specs
+
+- **Development Dockerfile ([src/dev-demo.Dockerfile](src/dev-demo.Dockerfile))**:
+  - Defines the base environment for development.
+  - Installs Node.js (`pnpm`), Python (`jupyterlab`), package requirements from [src/pyproject.toml](src/pyproject.toml), and PostgreSQL client CLI.
+- **Development Compose ([tool/cicd/docker-compose.app-demo.DEV.yml](tool/cicd/docker-compose.app-demo.DEV.yml))**:
+  - Configures the development service container, exposing computed ports, mounting workspace files, and setting environment variables.
+- **Common Database Server ([tool/cicd/docker-compose.db.yml](tool/cicd/docker-compose.db.yml))**:
+  - Launches a shared PostgreSQL 17 database service (`db-postgres-common`) on port 5432.
+  - Preloaded with database extensions: `pg_duckdb`, `pg_search`, `pg_cron`.
diff --git a/doc/skills/aloha_cicd/references/scaffolding.md b/doc/skills/aloha_cicd/references/scaffolding.md
@@ -0,0 +1,42 @@
+# Project Scaffolding & Multi-Agent Setup
+
+This sub-module guides you through setting up project directories, directory conventions, and configuring a multi-agent workspace.
+
+---
+
+## 1. Directory Structure & Conventions
+
+When using `aloha-python` as a boilerplate for a new project, follow these structural rules:
+
+- **`src/` (Core Application & Tests)**: Place all application-specific code and tests here.
+  - **`src/resource/config/`**: HOCON configuration files (e.g. `main.conf`, `deploy-DEV.conf`).
+  - **`src/tests/`**: All test files (prefixed with `test_*.py`) and test resources.
+- **`doc/` (Documentation & Agent Skills)**: Project Markdown documentation and AI Agent Skills (stored under `doc/skills/`).
+- **`notebook/` (Jupyter Notebooks)**: For data analysis, rapid prototyping, and interactive experimentation.
+- **`tool/` (CI/CD & Shell Helpers)**: Holds docker compose setups, dockerfiles, and helper scripts.
+- **`pkg/` (Library Source - Exclude in Boilerplate Apps)**: This is the core `aloha` package itself. Do not clone/copy the `pkg/` directory when creating a new application project based on this template; your application code should live in `src/`.
+
+---
+
+## 2. Multi-Agent Scaffolding Script
+
+To ensure consistent guidelines, style rules, and skill access across different AI tools (such as Antigravity/Gemini, Claude Code, and GitHub Copilot), run the following scaffolding commands to link config directories:
+
+```bash
+# Create scaffolding directories
+mkdir -pv .github/workflows doc/skills src/tests tool/cicd
+
+# Create agent config directories and symlink the centralized rules and skills
+mkdir -pv doc/skills .agents .claude \
+  && touch AGENTS.md \
+  && ln -sf AGENTS.md CLAUDE.md \
+  && ln -sf ../AGENTS.md .github/copilot-instructions.md \
+  && ln -sf ../doc/skills .agents/ \
+  && ln -sf ../doc/skills .claude/ \
+  && ln -sf ../doc/skills .github/
+```
+
+### Integrated Workspace Layout
+
+- **Centralized Rules (`AGENTS.md`)**: The single source of truth for code styling, conventions, and constraints.
+- **Centralized Skills (`doc/skills/`)**: Symlinked dynamically to `.agents/skills`, `.claude/skills`, and `.github/skills`. All agents automatically share the same custom instructions.