Example missions (boot seed)
============================

Fresh boot seeds **Veronica** and a maintained set of example **Missions** from
``agency-django/src/agency/fixtures/example_missions.json``. They are reference
workflows for operators and for :doc:`../veronica`, not throwaway demo rows.

Namespaces
----------

Each example mission has:

* **name** — short title stored in the DB (e.g. ``First hello``)
* **namespace** — dotted stable id (e.g. ``mission.example.first_hello``)

Mission Control explorers group ``mission.example.*`` under a collapsible
**Example** section. List rows show ``Example · {name}`` for familiarity; the
detail form shows **Name** and an editable **Namespace** field (dotted lowercase;
blank infers from the name). Explorers regroup live after save.

Boot is **create-only by name** — existing rows with the same name are not
overwritten. Shipped content upgrades use ``system_key`` + ``shipped_content_hash``
(see :doc:`../veronica`).

Catalog
-------

.. list-table::
   :header-rows: 1
   :widths: 22 34 44

   * - Name (DB)
     - Namespace
     - Demonstrates
   * - First hello
     - ``mission.example.first_hello``
     - Oneshot greeting
   * - Conversation closure
     - ``mission.example.conversation_closure``
     - Loop + time tool; confirm with "Vale" during ``waiting``
   * - Multi-step checklist
     - ``mission.example.multi_step_checklist``
     - Loop across tool steps
   * - HITL ask human
     - ``mission.example.hitl_ask_human``
     - ``ask_human`` interrupt
   * - Agency Help
     - ``mission.example.agency_help``
     - ``read_agency_help`` via Veronica
   * - Dispatch mission
     - ``mission.example.dispatch_mission``
     - ``list_available_missions`` + ``dispatch_mission``
   * - Open Help window
     - ``mission.example.open_help_window``
     - ``open_window(window='help')``
   * - Close Help window
     - ``mission.example.close_help_window``
     - ``close_window(window='help')``
   * - Generate tool icon
     - ``mission.example.tool_icon``
     - ``list_catalog_tools(missing_icon)`` + catalog pictogram + ``generate_agency_icon``
   * - Fantasy display wallpaper
     - ``mission.example.fantasy_wallpaper``
     - Loop: ComfyUI ``generate_image`` (1024×768 cinematic fantasy). ``show_media``
       puts it on the operator Media player. Named Display preview +
       ``show_image_on_display`` only if the operator named a screen; never every
       kiosk. Wait after showing; “basta” completes. Never the dock-icon tool.

Try in Mission Control
----------------------

1. Open **Missions** from the dock.
2. Expand **Example** in the sidebar; select **Example · First hello**.
3. In the mission header, choose **Veronica** (or your active agent) and
   **Execute**.

Dispatch without ``agent_id`` uses the signed-in user's active agent
(``UserPreferences.active_agent``); see :doc:`first-mission`.

Adding examples
---------------

When shipping a new capability worth demonstrating:

1. Append to ``fixtures/example_missions.json`` with unique **name** and
   ``mission.example.<slug>`` namespace.
2. Update this page (or :doc:`../veronica`) with what it shows.

The loader is create-only by name, so a seeded mistake persists in every
database that already booted — agree on a new example before adding it, and
keep the hand-allocated ``pk`` series collision-free.

Related: :doc:`../veronica`.