@bpinhosilva/agent-orchestrator 1.0.0-alpha.3 → 1.0.0-alpha.30

package/CHANGELOG.md

@@ -1,3 +1,214 @@
+# [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)
+
+
+### Features
+
+* update Google Gemini API client library, adapt agent implementation and tests ([46a52dd](https://github.com/bpinhosilva/agent-orchestrator/commit/46a52dd518f27cded3213248e9646300b6bc2fb8))
+
 # [1.0.0-alpha.3](https://github.com/bpinhosilva/agent-orchestrator/compare/v1.0.0-alpha.2...v1.0.0-alpha.3) (2026-03-17)
 
 

package/README.md

@@ -1,75 +1,278 @@
 # 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>
+
+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 and Anthropic Claude
+- 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 to execute agents:
+  - [Google Gemini API key](https://aistudio.google.com/)
+  - [Anthropic API key](https://console.anthropic.com/)
+
+## 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
+npm install -g @bpinhosilva/agent-orchestrator
+agent-orchestrator setup
+agent-orchestrator run
+agent-orchestrator status
 ```
 
-## Running the app
+`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).
 
-Before running the application, ensure you have set the `GEMINI_API_KEY` in your environment variables, as the default agent is the `GeminiAgent`.
+### Option B: source checkout
 
 ```bash
-# Start the PostgreSQL Database
-$ docker compose up -d
+git clone https://github.com/bpinhosilva/agent-orchestrator.git
+cd agent-orchestrator
+npm install
+npm rebuild
+npm run build:all
+```
 
-# development
-$ GEMINI_API_KEY="your-api-key" npm run start
+> **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.
 
-# watch mode
-$ GEMINI_API_KEY="your-api-key" npm run start:dev
+If you want to use the packaged CLI behavior from a source checkout, run the built entrypoint directly:
 
-# production mode
-$ GEMINI_API_KEY="your-api-key" npm run start:prod
+```bash
+node dist/cli/index.js --help
 ```
 
-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/`.
+## Configure the runtime
+
+The app loads configuration from:
 
-## Testing
+- `${AGENT_ORCHESTRATOR_HOME}/.env` when `AGENT_ORCHESTRATOR_HOME` is set
+- `.env` in the project/package root otherwise
+
+Example `.env`:
 
 ```bash
-# unit tests
-$ npm run test
+# Required
+JWT_SECRET="replace-with-a-secret-at-least-32-characters-long"
+
+# Provider keys (optional until you want to execute agents)
+GEMINI_API_KEY=""
+ANTHROPIC_API_KEY=""
 
-# e2e tests
-$ npm run test:e2e
+# Database
+DB_TYPE=sqlite
+DATABASE_URL=
 
-# test coverage
-$ npm run test:cov
+# Runtime
+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
 ```
 
-## API usage
+## 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
 
-**Endpoint**: `POST /api/v1/agents/process`
-**Payload**:
-```json
-{
-  "input": "Write a short poem about automation."
-}
+### 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 run migration:run
+```
+
+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
+
+### Local development
+
+```bash
+npm run dev
+```
+
+That starts:
+
+- UI dev server: `http://localhost:5173`
+- API: `http://localhost:3000/api/v1`
+- Swagger UI: `http://localhost:3000/api` (non-production only)
+- Health endpoint: `http://localhost:3000/health`
+
+If you only want the API in watch mode:
+
+```bash
+npm run start:dev
+```
+
+### Packaged/runtime mode
+
+```bash
+agent-orchestrator run
+agent-orchestrator status
+agent-orchestrator logs --lines 50
+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.
+
+| 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
+npm run docker:up
+docker compose run --rm api dist/cli/index.js migrate --yes
+```
+
+Endpoints:
+
+- UI: `https://localhost` or `https://agent-orchestrator.localhost`
+- API: `https://localhost/api/v1` or `https://agent-orchestrator.localhost/api/v1`
+
+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
+```
+
+Endpoints:
+
+- 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` and/or `ANTHROPIC_API_KEY` are set
+- **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.d.ts

@@ -0,0 +1,5 @@
+export declare const AGENT_EMOJI_VALUES: readonly ["🧠", "🤖", "🧪", "🛠️", "📊", "🔍", "🧭", "📝", "⚙️", "🚀"];
+export type AgentEmojiValue = (typeof AGENT_EMOJI_VALUES)[number];
+export declare const DEFAULT_AGENT_EMOJI: AgentEmojiValue;
+export declare const isAgentEmojiValue: (value: unknown) => value is AgentEmojiValue;
+export declare const normalizeAgentEmoji: (value?: string | null) => AgentEmojiValue;

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;

package/dist/agents/agents.controller.d.ts

@@ -1,8 +1,16 @@
 import { AgentsService } from './agents.service';
 import { AgentRequestDto } from './dto/agent-request.dto';
 import { AgentResponse } from './interfaces/agent.interface';
+import { CreateAgentDto } from './dto/create-agent.dto';
+import { UpdateAgentDto } from './dto/update-agent.dto';
 export declare class AgentsController {
     private readonly agentsService;
     constructor(agentsService: AgentsService);
+    create(createAgentDto: CreateAgentDto): Promise<import("./entities/agent.entity").AgentEntity>;
+    findAll(): Promise<import("./entities/agent.entity").AgentEntity[]>;
+    findOne(id: string): Promise<import("./entities/agent.entity").AgentEntity>;
+    update(id: string, updateAgentDto: UpdateAgentDto): Promise<import("./entities/agent.entity").AgentEntity>;
+    remove(id: string): Promise<void>;
     processText(requestDto: AgentRequestDto): Promise<AgentResponse>;
+    probe(requestDto: AgentRequestDto): Promise<AgentResponse>;
 }