# Service Mode And Paths

This note documents how an end-user (service) installation of AGILab wires the
different source trees together.  It complements the public documentation and
captures the expectations that baked-in automation (install scripts, the `AgiEnv`
bootstrapper, etc.) now assume.

## Terminology

- **Public checkout** – the open-source `agilab` repository containing the
  default apps and tooling.
- **Apps repository checkout** – an optional secondary repository referenced by
  the `APPS_REPOSITORY` environment variable. It can host additional app
  templates without requiring changes to the public checkout.
- **Service mode** – an end-user installation (`install_type == 0`) where the
  runtime lives under `~/agi-space` and pulls packages from wheels installed in
  a virtual environment.

## Key Files And Environment Variables

| Path / Variable | Purpose |
| ----------------| --------|
| `~/.local/share/agilab/.env` | Populated by the installer and read by
  `AgiEnv`.  When using an external apps repository it must contain the
  repository location via `APPS_REPOSITORY="/abs/path/to/apps-repository"`. |
| `~/.local/share/agilab/.agilab-path` | Records the canonical public checkout
  used when the installer ran.  When present it allows a fallback to the
  open-source apps. |
| `~/agi-space/.venv` | The virtual environment that executes the web interface in
  service mode. |
| `~/agi-space/apps` | Populated with symlinks to the selected app templates. |

## How App Symlinks Are Resolved

1. When `AgiEnv` initialises with `install_type == 0`, it first looks for
   `APPS_REPOSITORY/src/agilab/apps`.
2. Every `*_project` folder inside that repository directory is symlinked into
   the active end-user workspace (e.g. `~/agi-space/apps`). Existing links are
   recreated only when the target changed.
3. If the apps repository directory is missing or unset, `AgiEnv` falls back to the location
   stored in `~/.local/share/agilab/.agilab-path` and copies the public apps
   instead of linking them.

Because the apps repository (when configured) is the primary source of truth,
make sure the installer writes the up-to-date path to `APPS_REPOSITORY` and that
the repository exposes the expected sub-tree:

```
${APPS_REPOSITORY}/
  src/
    agilab/
      apps/
      apps-pages/
      ...
```

## Cleaning Up Broken Links

During startup `AgiEnv.get_projects()` automatically removes any dangling
symlinks under the end-user `apps` directory.  If you move or rename projects in
the apps repository, the next launch will drop stale links and recreate them
using the up-to-date path.

## Practical Checklist

1. Point `APPS_REPOSITORY` at the root of the apps repository (when used).
2. Run the installer (or rerun `install_apps.sh`) so `~/.local/share/agilab/.env`
   is refreshed.
3. Restart the end-user web interface app.  The sidebar project selector should now
  only list apps that resolve inside `APPS_REPOSITORY`.