Start Guide
===========

Getting started with Agency Server
----------------------------------

**agency-server** is the Docker Compose host for the **agency-django** package.
Together with **agency-ui** (Vue source, published into the package), it runs the full stack.

For multi-repo layout and philosophy, see `agency-workspace <https://github.com/txemavs/agency-workspace>`_ (submodules under one folder) and :doc:`architecture`.

Prerequisites
-------------

- Docker and Docker Compose (on WSL2, set ``DOCKER_HOST`` to the Docker Desktop socket if needed — see :doc:`development/workspace`)
- Git
- (Optional) Node ≥ 20.19 for UI source work in **agency-ui**

Installation
------------

1. Open the co-dev workspace (siblings)::

      agency/
        agency-django/
        agency-server/   ← this repo
        agency-ui/

2. Prefer the umbrella helper from ``agency-workspace``::

      ./dev up

   Or from ``agency-server``::

      ./dev up
      # equivalent: docker compose up   (foreground; add -d if you want detached)

   Boot scripts run migrate, collectstatic, and seed defaults (superuser,
   workspace, Ollama / OpenAI / FAL providers, curated ChatGPT models).

3. Access the application:

   - Product SPA: http://localhost/ (login: http://localhost/login/)
   - Admin: http://localhost/admin/
   - API / OpenAPI: http://localhost/api/
   - Docs: http://localhost/static/documentation/

Core concepts
-------------

Domain concepts: Agent, Mission, Execution, Thread, Run, Checkpoint, Interruption.

* Glossary: :doc:`concepts`
* Tutorials: :doc:`tutorials/index` (first Agent, Mission, HITL)
* Package README: sibling ``agency-django/README.md``

Services overview
-----------------

- **django (WSGI)**: HTTP / REST / admin / product SPA shell at ``/``
- **asgi**: WebSockets (``/channel/``)
- **Celery** (work / beat / flower): background transport
- **nginx**: reverse proxy and ``/static/``
- **PostgreSQL**, **Redis**, plus reference **ChromaDB** / **Ollama**

UI development
--------------

Edit Vue/TS in **agency-ui** (``npm run dev`` against the stack).
Publish with umbrella ``./dev ui`` or ``npm run build:django``, commit dist in **agency-django**, then ``collectstatic``.

Canonical checklist: ``DEVELOPMENT.md`` (this repo) and sibling ``agency-ui/DEVELOPMENT.md``.
UI / WebSocket contracts: :doc:`framework/connections`, :doc:`development/ui/index`.

Next steps
----------

- :doc:`tutorials/first-agent`
- :doc:`framework/deployment`
- :doc:`tests/index`