@bpinhosilva/agent-orchestrator 1.0.0-alpha.4 → 1.0.0-alpha.40

package/CHANGELOG.md

@@ -1,3 +1,280 @@
+# [1.0.0-alpha.40](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.39...v1.0.0-alpha.40) (2026-04-17)
+
+
+### Features
+
+* add Ollama provider and model support ([7c24c38](https://github.com/bpinhosilva/agent-orchestrator/commit/7c24c38704975c0083485e1e2a4552997cd17e34))
+
+# [1.0.0-alpha.39](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.38...v1.0.0-alpha.39) (2026-04-17)
+
+
+### Features
+
+* **docs:** add HOST configuration to README and CLI documentation ([8e7820e](https://github.com/bpinhosilva/agent-orchestrator/commit/8e7820e554088bc976559780088927c469f5d059))
+
+# [1.0.0-alpha.38](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.37...v1.0.0-alpha.38) (2026-04-17)
+
+
+### Features
+
+* **TaskManager:** refactor task management with lazy loading and improved state handling ([8988277](https://github.com/bpinhosilva/agent-orchestrator/commit/898827701c7824c93b063fc6ab88862a7d79110b))
+
+# [1.0.0-alpha.37](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.36...v1.0.0-alpha.37) (2026-04-13)
+
+
+### Features
+
+* **models:** implement model deletion with agent association check and enhance UI for model mgn ([e4cc599](https://github.com/bpinhosilva/agent-orchestrator/commit/e4cc599263f910e80e00116218e9408ec2ac2bf3))
+
+# [1.0.0-alpha.36](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.35...v1.0.0-alpha.36) (2026-04-13)
+
+
+### Performance Improvements
+
+* **db:** optimize schema with composite and missing indexes ([091d7c4](https://github.com/bpinhosilva/agent-orchestrator/commit/091d7c417d9b3291d704754f8cd0b22924aec871))
+
+# [1.0.0-alpha.35](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.34...v1.0.0-alpha.35) (2026-04-11)
+
+
+### Features
+
+* add Spanish release notes and update task priority handling ([42484db](https://github.com/bpinhosilva/agent-orchestrator/commit/42484db728a48eed290c00be180598718ca572a5))
+
+# [1.0.0-alpha.34](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.33...v1.0.0-alpha.34) (2026-04-09)
+
+
+### Features
+
+* enhance file path validation and logging in uploads, add ExecLogModal component ([2d9ca31](https://github.com/bpinhosilva/agent-orchestrator/commit/2d9ca31fd67924958f417d113ec974252858782d))
+* **migrations:** add migration to set default UUIDs for ID columns ([ea9289b](https://github.com/bpinhosilva/agent-orchestrator/commit/ea9289b8623d244737dfb7340a58637c8967edf8))
+* refactor task and comment entities to use Artifact interface for artifacts ([806fde7](https://github.com/bpinhosilva/agent-orchestrator/commit/806fde736b734de0cb3cb9a7a05c5c3eb2d7f171))
+* **ui:** integrate MarkdownField for task description input and enhance TaskExecutions ([d4b91e8](https://github.com/bpinhosilva/agent-orchestrator/commit/d4b91e8b9c392f77a2cab3c0a5bcc641110bced2))
+
+# [1.0.0-alpha.33](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.32...v1.0.0-alpha.33) (2026-04-06)
+
+
+### Features
+
+* **cli:** refactor project, split into multiple components ([f18903b](https://github.com/bpinhosilva/agent-orchestrator/commit/f18903be0b1b09a1e651918d081d96267bfe2bc6))
+
+# [1.0.0-alpha.32](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.31...v1.0.0-alpha.32) (2026-04-06)
+
+
+### Features
+
+* enhance task scheduling with dynamic settings and improved error handling ([cbb5097](https://github.com/bpinhosilva/agent-orchestrator/commit/cbb50979f8e79e6cdc581ed29fa0933f82c3e4ee))
+
+# [1.0.0-alpha.31](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.30...v1.0.0-alpha.31) (2026-04-06)
+
+
+### Features
+
+* add environment variable setup and JWT refresh secret handling ([c9dfd05](https://github.com/bpinhosilva/agent-orchestrator/commit/c9dfd05070dfc4bc0e34e3853d0efe85d84d404a))
+
+# [1.0.0-alpha.30](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.29...v1.0.0-alpha.30) (2026-04-05)
+
+
+### Features
+
+* add UsersPage component with user management features and tests ([bb46646](https://github.com/bpinhosilva/agent-orchestrator/commit/bb466468849b01dd30bc228e3c0375b6aea874e8))
+* integrate Personality Matrix component, refactor storage service ([2aa80d3](https://github.com/bpinhosilva/agent-orchestrator/commit/2aa80d3b64cd6431ba0113182dcb5d871075fcfd))
+* integrate wait-on for improved dev workflow ([af26318](https://github.com/bpinhosilva/agent-orchestrator/commit/af2631820f5fc95b7b85c9f6ec52157b7df74264))
+
+# [1.0.0-alpha.29](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.28...v1.0.0-alpha.29) (2026-04-04)
+
+
+### Features
+
+* **migrations:** add seed and backfill migrations ([5991146](https://github.com/bpinhosilva/agent-orchestrator/commit/5991146cbb3bc971bddf73295dcf7dbd3e2b74e4))
+
+# [1.0.0-alpha.28](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.27...v1.0.0-alpha.28) (2026-04-04)
+
+
+### Features
+
+* **migrations:** add initial schema with users, providers, models, agents, projects, tasks ([e08e338](https://github.com/bpinhosilva/agent-orchestrator/commit/e08e3388794e8a556be3584daedd30252a8904fb))
+* **migrations:** db schema ([a0a98b7](https://github.com/bpinhosilva/agent-orchestrator/commit/a0a98b725e09f6d3a9a8fc2305704772195fe2d8))
+
+# [1.0.0-alpha.27](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.26...v1.0.0-alpha.27) (2026-04-04)
+
+
+### Features
+
+* update default port to 15789 for production, enhance migration handling, and refactor env ([e59ba31](https://github.com/bpinhosilva/agent-orchestrator/commit/e59ba3105c5ce7367281bf3ee637bcc3bc124dcc))
+* update mascot image format and adjust display size in README ([6779313](https://github.com/bpinhosilva/agent-orchestrator/commit/6779313a26a6906ecb47a8819789dc8312f3d6fc))
+
+# [1.0.0-alpha.26](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.25...v1.0.0-alpha.26) (2026-04-04)
+
+
+### Features
+
+* add AGENTS.md file ([51c706f](https://github.com/bpinhosilva/agent-orchestrator/commit/51c706f8784dd354280d853f605bb8c69e53175c))
+* implement containerization, add health check endpoint, and update RBAC ([17149d3](https://github.com/bpinhosilva/agent-orchestrator/commit/17149d32a623f532308ba0f415a4b2ba332ec794))
+* **refactor:** project terminology and update UI components ([47e5cb4](https://github.com/bpinhosilva/agent-orchestrator/commit/47e5cb4d45c05f893ebdd898f02ceeadcd213652))
+
+# [1.0.0-alpha.25](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.24...v1.0.0-alpha.25) (2026-04-03)
+
+
+### Features
+
+* **cli:** enhance setup command with detailed configuration options and improved process ([2b7f51d](https://github.com/bpinhosilva/agent-orchestrator/commit/2b7f51d16e8f1949e222c03968d925030e4b0574))
+
+# [1.0.0-alpha.24](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.23...v1.0.0-alpha.24) (2026-04-02)
+
+
+### Features
+
+* update README and documentation files with additional references and streamlined content ([ae7b1ac](https://github.com/bpinhosilva/agent-orchestrator/commit/ae7b1acbd47eebbc91b154f2b54da83eb8da0be8))
+
+# [1.0.0-alpha.23](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.22...v1.0.0-alpha.23) (2026-04-02)
+
+
+### Features
+
+* enhance project management with user roles and member management ([877832f](https://github.com/bpinhosilva/agent-orchestrator/commit/877832fc4ad8d77499124a4da23c14a1270622a4))
+* implement release workflow with semantic release and build steps; remove old release.yml ([f17eb48](https://github.com/bpinhosilva/agent-orchestrator/commit/f17eb48c64b165c8fd05e142d175716f7990f670))
+* update CI workflow to include E2E and UI tests; bump lodash version ([b8ceee6](https://github.com/bpinhosilva/agent-orchestrator/commit/b8ceee6adf0855b54d4a45d959e87ec338c55887))
+
+# [1.0.0-alpha.22](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.21...v1.0.0-alpha.22) (2026-04-02)
+
+
+### Features
+
+* add InitialsAvatar component and do some refactor ([417eff3](https://github.com/bpinhosilva/agent-orchestrator/commit/417eff3bdf4ac8cf072c99fc56744a3a93807a31))
+
+# [1.0.0-alpha.21](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.20...v1.0.0-alpha.21) (2026-03-30)
+
+
+### Features
+
+* enhance JWT security by specifying HS256 algorithm and improve logging in services ([349c94b](https://github.com/bpinhosilva/agent-orchestrator/commit/349c94b31bfdcc2f397cd81848bb2fd3b977a438))
+
+# [1.0.0-alpha.20](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.19...v1.0.0-alpha.20) (2026-03-30)
+
+
+### Features
+
+* implement security fixes ([f570f92](https://github.com/bpinhosilva/agent-orchestrator/commit/f570f92a10cf1473c36a0145c160f6e23905bb1f))
+
+# [1.0.0-alpha.19](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.18...v1.0.0-alpha.19) (2026-03-30)
+
+
+### Features
+
+* implement transaction management in services and tests for improved data integrity ([7b213da](https://github.com/bpinhosilva/agent-orchestrator/commit/7b213da8e9ee46da2e40f3e51e3d61c8a50ac850))
+
+# [1.0.0-alpha.18](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.17...v1.0.0-alpha.18) (2026-03-29)
+
+
+### Features
+
+* implement automated database migrations and interactive admin user setup in CLI ([6868b13](https://github.com/bpinhosilva/agent-orchestrator/commit/6868b137ad80c85d4ffc56b884b8016df8a3c533))
+
+# [1.0.0-alpha.17](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.16...v1.0.0-alpha.17) (2026-03-29)
+
+
+### Features
+
+* implement recurrent task scheduling system with backend services and UI management modal ([b3c699a](https://github.com/bpinhosilva/agent-orchestrator/commit/b3c699a5b7eb261458d97a7a0d40e5071e33fb1e))
+
+# [1.0.0-alpha.16](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.15...v1.0.0-alpha.16) (2026-03-28)
+
+
+### Features
+
+* implement scheduler page, add database indexes for performance, and update release workflow ([b4e067a](https://github.com/bpinhosilva/agent-orchestrator/commit/b4e067a1b20e4275214309c1241c163b456260da))
+
+# [1.0.0-alpha.15](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.14...v1.0.0-alpha.15) (2026-03-28)
+
+
+### Features
+
+* implement user authentication system with JWT, registration, and login functionality ([63582fa](https://github.com/bpinhosilva/agent-orchestrator/commit/63582fa8f318c8a6bc174795364a4d3cbd221d45))
+
+# [1.0.0-alpha.14](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.13...v1.0.0-alpha.14) (2026-03-27)
+
+
+### Features
+
+* add CreateTaskDto ([1604945](https://github.com/bpinhosilva/agent-orchestrator/commit/1604945737b5df5480c6c0814c369902f7cc9142))
+* implement transient agent instances with dynamic configurationn ([5d57b08](https://github.com/bpinhosilva/agent-orchestrator/commit/5d57b0886edf4b14d93ab76f245f4311b6657f7d))
+
+# [1.0.0-alpha.13](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.12...v1.0.0-alpha.13) (2026-03-26)
+
+
+### Features
+
+* add Claude agent implementation with Anthropic SDK and refactor agent-provider ([1400a0d](https://github.com/bpinhosilva/agent-orchestrator/commit/1400a0dec6beb8393ddc4c5a23b9b860532079e8))
+
+# [1.0.0-alpha.12](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.11...v1.0.0-alpha.12) (2026-03-24)
+
+
+### Features
+
+* add .npmrc to enable legacy peer dependencies ([2f41a07](https://github.com/bpinhosilva/agent-orchestrator/commit/2f41a0747e3cc862241f90c24405c6ad0976557b))
+* implement comprehensive project management, task comments with attachments ([10eb382](https://github.com/bpinhosilva/agent-orchestrator/commit/10eb38268d50ff9418a3e7af1788d55c759522a9))
+* implement task detail view with comment polling, numeric priorities, and enhanced task card ([7a38155](https://github.com/bpinhosilva/agent-orchestrator/commit/7a38155ac796dbe528d48a340a0e6be7fa0150a3))
+* introduce a task scheduler service for automated agent task assignment and execution ([d756f10](https://github.com/bpinhosilva/agent-orchestrator/commit/d756f10c441aadb3b31335a55926700b5518ec9e))
+
+# [1.0.0-alpha.11](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.10...v1.0.0-alpha.11) (2026-03-24)
+
+
+### Bug Fixes
+
+* downgrade class-validator from ^0.15.1 to ^0.14.1 ([6d9bb29](https://github.com/bpinhosilva/agent-orchestrator/commit/6d9bb291145cdfad7d8c5f4fc8a7ac6ee48ee776))
+
+
+### Features
+
+* introduce task management UI with draggable cards and refactor provider ([1002dd1](https://github.com/bpinhosilva/agent-orchestrator/commit/1002dd1ac373fe4f6c3acb2eb6e9345b3ec35aba))
+
+# [1.0.0-alpha.10](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.9...v1.0.0-alpha.10) (2026-03-22)
+
+
+### Features
+
+* add agent probing functionality with a new API endpoint, service logic ([f71abb6](https://github.com/bpinhosilva/agent-orchestrator/commit/f71abb601745b7f2ae5c1f8be53143429302c1d2))
+
+# [1.0.0-alpha.9](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.8...v1.0.0-alpha.9) (2026-03-22)
+
+
+### Features
+
+* implement provider and model management UI and API, and enhance agent configuration ([01dbe34](https://github.com/bpinhosilva/agent-orchestrator/commit/01dbe345b8763da433682d7bc185c017e5b5d5d9))
+
+# [1.0.0-alpha.8](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.7...v1.0.0-alpha.8) (2026-03-22)
+
+
+### Features
+
+* add initial user interface for agent management and orchestration ([7a27019](https://github.com/bpinhosilva/agent-orchestrator/commit/7a270197691453384e5827987574f94e93cad7fb))
+
+# [1.0.0-alpha.7](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.6...v1.0.0-alpha.7) (2026-03-21)
+
+
+### Features
+
+* add user management module, introduce task output field, and include a design document ([7d0717d](https://github.com/bpinhosilva/agent-orchestrator/commit/7d0717d5a566435641e46b2f4b40101df0f62ed6))
+
+# [1.0.0-alpha.6](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.5...v1.0.0-alpha.6) (2026-03-21)
+
+
+### Features
+
+* implement project and task management modules, including entities, DTOs, services, controllers ([3df2c2a](https://github.com/bpinhosilva/agent-orchestrator/commit/3df2c2a6d0bdf4e3e4edbf12f544a8e12970e2dd))
+
+# [1.0.0-alpha.5](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.4...v1.0.0-alpha.5) (2026-03-21)
+
+
+### Bug Fixes
+
+* **ci:** use legacy-peer-deps to resolve peer dependency conflicts ([b450b45](https://github.com/bpinhosilva/agent-orchestrator/commit/b450b4500ff02addb1bca6cc7f6a40c93e442e7f))
+
+
+### Features
+
+* implement models and providers modules add swagger documentation, and update agents ([b6e8245](https://github.com/bpinhosilva/agent-orchestrator/commit/b6e824547f4f603cecf0352b383d20a078fe6662))
+
 # [1.0.0-alpha.4](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.3...v1.0.0-alpha.4) (2026-03-20)
 
 

package/README.md

@@ -1,75 +1,296 @@
 # Agent Orchestrator
 
-[![CI](https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/ci.yml)
-[![Release](https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/release.yml/badge.svg)](https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/release.yml)
-[![Gitleaks](https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/gitleaks.yml/badge.svg)](https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/gitleaks.yml)
-
-Agent Orchestrator is an open-source project designed to manage and orchestrate AI agents using both back-end services and front-end applications. It provides an automated agentic execution environment where you can create multiple agent profiles (e.g., Head Agent, Researcher, CMO) and delegate tasks to them through automated workflows.
-
-## Features (In Progress & Planned)
-- **Agent Delegation**: Delegate tasks to specialized AI agents.
-- **Job Scheduler**: Create and schedule recurring agentic tasks.
-- **Workflow Engine**: Drag-and-drop workflow builder supporting triggers, agent chaining, and outputs.
-- **Agent Capabilities**: File reading/writing, web search, email capabilities, and image generation using NanoBanana.
-- **TUI/CLI Tooling**: CLI executables to manage the installation and local agent configuration.
-
-## Current Architecture
-- **Backend Framework**: NestJS + TypeScript
-- **Frontend SPA**: React (Currently served as a single placeholder HTML file by the backend for MVP)
-- **Database**: PostgreSQL (via Docker Compose)
-- **Testing**: Jest (TDD Approach with Unit & E2E)
-- **Architecture**: 3-Tier (Controller, Service, DAL/Adapter Interfaces)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/bpinhosilva/agent-orchestrator/main/docs/assets/lupy-mascot.webp" alt="Lupy, the Agent Orchestrator mascot" width="500" />
+</p>
+
+<p align="center"><em>Lupy, the project mascot, inspired by Bruno's dog and companion of 10 years.</em></p>
+
+<p align="center">
+  <a href="https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/ci.yml"><img src="https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/gitleaks.yml"><img src="https://github.com/bpinhosilva/agent-orchestrator/actions/workflows/gitleaks.yml/badge.svg" alt="Gitleaks" /></a>
+  <a href="https://socket.dev/npm/package/@bpinhosilva/agent-orchestrator"><img src="https://socket.dev/api/badge/npm/package/@bpinhosilva/agent-orchestrator" alt="Socket Badge" /></a>
+</p>
+
+<p align="center">
+  <a href="docs/i18n/pt-br/README.md">🇧🇷 Português (Brasil)</a> &nbsp;&middot;&nbsp;
+  <a href="docs/i18n/es-es/README.md">🇪🇸 Español (España)</a>
+</p>
+
+Agent Orchestrator is an open-source platform for managing AI agents, tasks, and project-scoped automation across multiple model providers. It combines a NestJS API, a React dashboard, a packaged CLI/runtime, and Docker deployment options for both local use and production-style environments.
+
+## Current capabilities
+
+- Multi-provider agent execution with Google Gemini, Anthropic Claude, and Ollama (local or cloud)
+- Agent profiles with provider/model selection
+- Project management with project membership and RBAC
+- Task execution plus recurring scheduling
+- File upload and artifact-backed task workflows
+- Packaged CLI/runtime for setup, run, status, logs, stop, and migrate
+- React dashboard served by the backend or packaged runtime
+
+## Planned direction
+
+- Richer workflow orchestration and agent chaining
+- Broader agent tool integrations
+- Expanded runtime and deployment ergonomics
+
+## Architecture at a glance
+
+| Area | Stack |
+| --- | --- |
+| Backend | NestJS 11 + TypeScript 5 |
+| Frontend | React SPA |
+| Database | PostgreSQL (production) / SQLite via `better-sqlite3` (local/runtime) |
+| ORM | TypeORM |
+| Auth | JWT access/refresh tokens via httpOnly cookies |
+| Packaging | npm package with bundled backend, CLI, and UI assets |
 
 ## Prerequisites
-- [Node.js](https://nodejs.org/) (v18+)
-- [Docker](https://www.docker.com/) and Docker Compose (Optional for local PostgreSQL deployment)
-- A [Google Gemini API Key](https://aistudio.google.com/)
 
-## Installation
+- [Node.js](https://nodejs.org/) 24 or newer
+- npm
+- [Docker](https://www.docker.com/) and Docker Compose (optional)
+- At least one provider API key or local model server to execute agents:
+  - [Google Gemini API key](https://aistudio.google.com/)
+  - [Anthropic API key](https://console.anthropic.com/)
+  - [Ollama](https://ollama.com/) running locally (no key required) or a cloud Ollama endpoint
+
+## Quick start
+
+Choose the path that matches how you want to use the project:
+
+- **Packaged CLI/runtime**: quickest way to run the app locally as an installed tool
+- **Source checkout**: best path for development and contributing
+
+### Option A: packaged CLI/runtime
+
+```bash
+npm install -g @bpinhosilva/agent-orchestrator
+agent-orchestrator setup
+agent-orchestrator run
+agent-orchestrator restart
+agent-orchestrator status
+```
+
+`setup` can create the runtime `.env`, run migrations, seed an admin user, and prompt you to apply pending migrations after package updates. `run` does not upgrade the database automatically. The default runtime home is `~/.agent-orchestrator`, or `${AGENT_ORCHESTRATOR_HOME}` if you set it explicitly.
+
+For deeper CLI usage, see [docs/CLI.md](docs/CLI.md).
+
+### Option B: source checkout
+
+```bash
+git clone https://github.com/bpinhosilva/agent-orchestrator.git
+cd agent-orchestrator
+npm install
+npm rebuild
+npm run build:all
+```
+
+> **Note**: The repository uses `ignore-scripts=true` in `.npmrc` for supply-chain hardening. After `npm install`, run `npm rebuild --ignore-scripts=false` so native modules such as `bcrypt` and `better-sqlite3` are actually compiled.
+
+If you want to use the packaged CLI behavior from a source checkout, run the built entrypoint directly:
+
+```bash
+node dist/cli/index.js --help
+```
+
+## Configure the runtime
+
+The app loads configuration from:
+
+- `${AGENT_ORCHESTRATOR_HOME}/.env` when `AGENT_ORCHESTRATOR_HOME` is set
+- `.env` in the project/package root otherwise
+
+Example `.env`:
+
+```bash
+# Required
+JWT_SECRET="replace-with-a-secret-at-least-32-characters-long"
+JWT_REFRESH_SECRET="replace-with-another-secret-at-least-32-characters-long"
+
+# Provider keys (optional until you want to execute agents)
+GEMINI_API_KEY=""
+ANTHROPIC_API_KEY=""
+
+# Ollama (local by default, fill in OLLAMA_HOST and OLLAMA_API_KEY for cloud usage)
+OLLAMA_HOST=http://127.0.0.1:11434
+OLLAMA_API_KEY=""
+
+# Database
+DB_TYPE=sqlite
+DATABASE_URL=
+
+# Runtime
+HOST=127.0.0.1
+PORT=15789
+NODE_ENV=production
+ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000
+SCHEDULER_ENABLED=true
+DB_LOGGING=false
+SERVE_STATIC_UI=true
+CHECK_PENDING_MIGRATIONS_ON_STARTUP=false
+LOG_LEVEL=error
+```
+
+## Database setup
+
+### SQLite
+
+SQLite is the default local/runtime option when `DATABASE_URL` is not set. The database file lives at:
+
+- `local.sqlite` in the project/package root, or
+- `${AGENT_ORCHESTRATOR_HOME}/local.sqlite` when runtime home is set
+
+### PostgreSQL
+
+Use PostgreSQL by setting `DATABASE_URL` or `DB_TYPE=postgres`:
+
+```bash
+export DATABASE_URL="postgresql://orchestrator:orchestrator_password@localhost:5433/agent_orchestrator"
+```
+
+### Initialize the schema
+
+Run migrations before the first app start:
 
 ```bash
-$ npm install
+npm run migration:run
 ```
 
-## Running the app
+Create the initial admin user if you want to sign in through the dashboard:
+
+```bash
+npm run seed:admin
+```
+
+If you use the packaged CLI, `agent-orchestrator setup` can perform both steps for you.
+
+## Run the application
 
-Before running the application, ensure you have set the `GEMINI_API_KEY` in your environment variables, as the default agent is the `GeminiAgent`.
+### Local development
 
 ```bash
-# Start the PostgreSQL Database
-$ docker compose up -d
+npm run dev
+```
+
+That starts:
+
+- UI dev server: `http://localhost:5173` (accessible from your network)
+- API: `http://localhost:3000/api/v1` (accessible from your network)
+- Swagger UI: `http://localhost:3000/api` (non-production only)
+- Health endpoint: `http://localhost:3000/health`
 
-# development
-$ GEMINI_API_KEY="your-api-key" npm run start
+By default, the development servers bind to `0.0.0.0`, allowing access from other devices on the same network using your machine's local IP address.
 
-# watch mode
-$ GEMINI_API_KEY="your-api-key" npm run start:dev
+If you only want the API in watch mode:
 
-# production mode
-$ GEMINI_API_KEY="your-api-key" npm run start:prod
+```bash
+npm run start:dev
 ```
 
-Once running, you can access the frontend dashboard container URL at `http://localhost:3000`. The API endpoints are accessible via `http://localhost:3000/api/v1/`.
+### Packaged/runtime mode
+
+```bash
+agent-orchestrator setup
+agent-orchestrator run
+agent-orchestrator status
+agent-orchestrator logs --lines 50
+agent-orchestrator restart
+agent-orchestrator stop
+```
+
+When running the packaged app or a production build with static UI enabled, the dashboard is served from `http://localhost:15789` by default.
+
+## Docker
+
+The repository ships three Compose entrypoints:
+
+All Compose stacks now require the database variables in the project `.env` file: `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, and `POSTGRES_TEST_DB` for the integration stack.
 
-## Testing
+| File | Purpose |
+| --- | --- |
+| `docker-compose.yml` | Production-style stack with PostgreSQL, API, and Caddy-served UI |
+| `docker-compose.dev.yml` | Development stack with API hot reload and Vite UI dev server |
+| `docker-compose.test.yml` | Integration stack for migration, CLI/runtime, API, and UI checks |
+
+### Production-style stack
 
 ```bash
-# unit tests
-$ npm run test
+npm run docker:up
+docker compose run --rm api dist/cli/index.js migrate --yes
+```
+
+Endpoints:
 
-# e2e tests
-$ npm run test:e2e
+- UI: `https://localhost` or `https://agent-orchestrator.localhost`
+- API: `https://localhost/api/v1` or `https://agent-orchestrator.localhost/api/v1`
 
-# test coverage
-$ npm run test:cov
+In this stack the UI is served by **Caddy**, not by the Nest app. Docker explicitly sets `SERVE_STATIC_UI=false` so the backend only serves the API.
+
+### Development stack
+
+```bash
+npm run docker:dev
 ```
 
-## API usage
+Endpoints:
 
-**Endpoint**: `POST /api/v1/agents/process`
-**Payload**:
-```json
-{
-  "input": "Write a short poem about automation."
-}
+- UI: `http://localhost:5173`
+- API: `http://localhost:3000/api/v1`
+- PostgreSQL: `localhost:5433`
+
+### Integration stack
+
+Use `docker-compose.test.yml` when you want to exercise migration behavior, packaged CLI/runtime flows, API startup, and UI reachability together.
+
+```bash
+npm run docker:test
+docker compose -f docker-compose.test.yml --profile tools run --rm migrate
+docker compose -f docker-compose.test.yml --profile tools run --rm cli
 ```
+
+Endpoints:
+
+- UI: `https://localhost:8444` or `https://agent-orchestrator.localhost:8444`
+- API: `https://localhost:8444/api/v1` or `https://agent-orchestrator.localhost:8444/api/v1`
+
+## Development workflow
+
+| Task | Command |
+| --- | --- |
+| Start API + UI | `npm run dev` |
+| Start API only | `npm run start:dev` |
+| Lint API + UI | `npm run lint:all` |
+| Run API + UI + E2E tests | `npm run test:all` |
+| Run coverage | `npm run test:cov` |
+| Run E2E tests | `npm run test:e2e` |
+| Build backend + UI package output | `npm run build:all` |
+| Apply migrations | `npm run migration:run` |
+
+## Auth and access model
+
+- Access and refresh tokens are issued by the auth service and transported via **httpOnly cookies**
+- System roles are **`admin`** and **`user`**
+- Project membership roles are **`owner`** and **`member`**
+- Routes are protected by default; use `@Public()` for public endpoints
+- Global throttling defaults to `60/min`, with stricter limits on auth endpoints
+
+## Useful docs
+
+- [CLI reference](docs/CLI.md)
+- [CI/CD pipeline](docs/CI_CD.md)
+- [Release process](docs/RELEASE.md)
+- [Contributing guide](CONTRIBUTING.md)
+
+## Troubleshooting
+
+- **Native module errors after install**: run `npm rebuild`
+- **`JWT_SECRET` rejected**: it must be at least 32 characters
+- **Agent execution fails immediately**: confirm `GEMINI_API_KEY`, `ANTHROPIC_API_KEY`, or Ollama (`OLLAMA_HOST`) are set correctly for the provider in use
+- **Schema/startup issues**: run `npm run migration:run`
+- **Need to undo the latest migration**: run `npm run migration:revert`
+
+## License
+
+See [LICENSE](LICENSE).

package/dist/agents/agent-emoji.constants.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAgentEmoji = exports.isAgentEmojiValue = exports.DEFAULT_AGENT_EMOJI = exports.AGENT_EMOJI_VALUES = void 0;
+exports.AGENT_EMOJI_VALUES = [
+    '🧠',
+    '🤖',
+    '🧪',
+    '🛠️',
+    '📊',
+    '🔍',
+    '🧭',
+    '📝',
+    '⚙️',
+    '🚀',
+];
+exports.DEFAULT_AGENT_EMOJI = '🧠';
+const isAgentEmojiValue = (value) => typeof value === 'string' &&
+    exports.AGENT_EMOJI_VALUES.includes(value);
+exports.isAgentEmojiValue = isAgentEmojiValue;
+const normalizeAgentEmoji = (value) => (0, exports.isAgentEmojiValue)(value) ? value : exports.DEFAULT_AGENT_EMOJI;
+exports.normalizeAgentEmoji = normalizeAgentEmoji;