GIA/INSTALL.md

# INSTALL

This guide covers installation, environment configuration, and operational startup for GIA.

Use this first. Then read `README.md` for feature and operation-mode details.

## 1) Prerequisites

- Linux host with Podman.
- Git.
- Network access for service images and Python dependencies.

## 2) Clone and initialize

```bash
git clone <repo-url> GIA
cd GIA
cp stack.env.example stack.env
```

## 3) Configure environment (`stack.env`)

At minimum, set:

- `SECRET_KEY`
- `DOMAIN`
- `URL`
- `ALLOWED_HOSTS`
- `CSRF_TRUSTED_ORIGINS`
- `APP_DATABASE_FILE`
- `APP_LOCAL_SETTINGS`
- `STATIC_ROOT`

Enable transport services as needed:

- `SIGNAL_NUMBER`
- `SIGNAL_HTTP_URL`
- `WHATSAPP_ENABLED`
- `WHATSAPP_DB_DIR`
- `INSTAGRAM_ENABLED`
- `COMPOSE_WS_ENABLED`

XMPP bridge settings:

- `XMPP_ADDRESS`
- `XMPP_JID`
- `XMPP_PORT`
- `XMPP_SECRET`

Prosody container helpers:

- `QUADLET_PROSODY_CONFIG_FILE`
- `QUADLET_PROSODY_CERTS_DIR`
- `QUADLET_PROSODY_DATA_DIR`
- `QUADLET_PROSODY_LOGS_DIR`

Memory/wiki search helpers:

- `MEMORY_SEARCH_BACKEND` (`django` or `manticore`)
- `MANTICORE_HTTP_URL`
- `MANTICORE_MEMORY_TABLE`
- `MANTICORE_HTTP_TIMEOUT`

For XMPP media upload, configure one of:

- `XMPP_UPLOAD_SERVICE`
- `XMPP_UPLOAD_JID`

If omitted, runtime attempts XEP-0363 discovery.

## 4) Build and start

```bash
make build
make run
```

## 5) Bootstrap database and admin

```bash
make migrate
make auth
```

Optional static token helper:

```bash
make token TOKEN_USER=<your_username>
```

Local code-quality checks:

```bash
make pre-commit
make pre-commit-glibc
```

`make pre-commit-glibc` selects `env` on musl systems and `genv` on glibc systems.

## 6) Logs and health checks

Tail logs:

```bash
make log
```

Basic stack status:

```bash
make status
```

## 7) Restart conventions

### Full environment recycle (preferred when dependency state is broken)

```bash
make stop && make run
```

Use the explicit `make stop && make run` command sequence when a full recycle is needed.

### Single service restart

```bash
podman restart <container-name>
```

If single-service restart fails due to dependency/pod state, use full recycle above.

## 8) Runtime code change policy

After changing UR/runtime code (`core/clients/*`, transport, relay paths), restart runtime services before validating behavior.

Minimum target:

```bash
podman restart ur_gia
```

If blocked, use full recycle.

## 9) Service endpoints

- Home: `/`
- Signal service page: `/services/signal/`
- WhatsApp service page: `/services/whatsapp/`
- Instagram service page: `/services/instagram/`
- Manual compose: `/compose/page/`
- AI workspace: `/ai/workspace/`
- OSINT search: `/search/page/`
- Security encryption settings: `/settings/security/encryption/`
- Security permissions settings: `/settings/security/permissions/`
- Command routing settings: `/settings/command-routing/`
- Task automation settings: `/settings/tasks/`
- Task inbox / manual task creation: `/tasks/`

## 10) Security and capability controls

- `Require OMEMO encryption` rejects plaintext XMPP messages before command routing.
- `Encrypt gateway component chat replies with OMEMO` only affects gateway/component conversations.
- `Encrypt contact relay messages to your XMPP client with OMEMO` only affects relayed contact chats.
- Fine-grained capability policy is configured in `/settings/security/permissions/` and applies by scope, service, and optional channel pattern.
- Trusted OMEMO key enforcement depends on trusted key records, not only the most recently observed client key.

## 11) Common troubleshooting

### A) Compose restart errors / dependency improper state

Use:

```bash
make stop && make run
```

### B) XMPP attachment upload issues

- Confirm upload host TLS and cert chain are valid.
- Confirm `XMPP_UPLOAD_SERVICE`/`XMPP_UPLOAD_JID` is set, or discovery works.
- Check runtime logs for slot request and upload errors.

### D) Prosody container (lightweight, no systemd)

Use:

```bash
./utilities/prosody/manage_prosody_container.sh up
./utilities/prosody/manage_prosody_container.sh status
./utilities/prosody/manage_prosody_container.sh logs
```

Auth script path for Prosody config:

```lua
external_auth_command = "/code/utilities/prosody/auth_django.sh"
```

Certificate renewal helper (run as root on host):

```bash
./utilities/prosody/renew_prosody_cert.sh
```

### E) Manticore container for memory/wiki retrieval

```bash
./utilities/memory/manage_manticore_container.sh up
./utilities/memory/manage_manticore_container.sh status
./utilities/memory/manage_manticore_container.sh logs
```

Reindex memory into configured backend:

```bash
podman exec ur_gia /venv/bin/python manage.py memory_search_reindex --user-id 1 --statuses active
```

Query memory backend:

```bash
podman exec ur_gia /venv/bin/python manage.py memory_search_query --user-id 1 --query "reply style"
```

Generate proposed memories from recent inbound messages:

```bash
podman exec ur_gia /venv/bin/python manage.py memory_suggest_from_messages --user-id 1 --limit-messages 300 --max-items 30
```

Run memory hygiene (expiry decay + contradiction queueing):

```bash
podman exec ur_gia /venv/bin/python manage.py memory_hygiene --user-id 1
```

Performance defaults now applied in GIA:

- Batched Manticore reindex writes (`REPLACE ... VALUES (...)` in chunks) for lower ingest latency.
- Cached table-ensure checks to avoid `CREATE TABLE IF NOT EXISTS` overhead on every query.
- Runtime table maintenance available through MCP (`FLUSH RAMCHUNK`, `OPTIMIZE TABLE`) for steady query responsiveness.

### F) MCP server for task + memory tooling (VS Code)

The workspace includes an MCP config at `/code/xf/.vscode/mcp.json` for server `manticore`.

It launches inside the running `ur_gia` container and forces:

- `MEMORY_SEARCH_BACKEND=manticore`

`MANTICORE_HTTP_URL` is read from the container environment (`stack.env` / app settings).

Start requirements first:

```bash
make run
./utilities/memory/manage_manticore_container.sh up
```

Then approve/enable the `manticore` MCP server in VS Code when prompted.

The MCP task surface now supports canonical task creation/completion in GIA:

- `tasks.create`
- `tasks.complete`
- `tasks.create_note`
- `tasks.link_artifact`

Optional ultra-light Rust MCP worker:

```bash
cd /code/xf/GIA
make mcp-rust-build
```

Then enable `manticore-rust-worker` in `/code/xf/.vscode/mcp.json`.
It is intentionally `disabled: true` by default so the existing Python MCP server remains the baseline.

### H) Optional browser MCP for visual validation

To validate compose/tasks/settings flows visually, add a browser-capable MCP server in your editor workspace alongside `manticore`. A Playwright-style browser MCP is the intended integration point for GIA UI checks.

Recommended usage:

- keep browser MCP outside host-network mode
- point it at the local GIA app URL/port from the running stack
- use it for page-load, form-flow, and visual regression checks on compose/tasks/settings pages

### I) Task command shortcuts

Gateway / XMPP / chat task commands now include:

- `.l` -> list open tasks
- `.tasks add <project> :: <title>` -> create a canonical task in a named project
- `.task add <title>` -> create a task inside the current mapped chat scope

### C) Signal or WhatsApp send failures

- Verify account/link status in service pages.
- Verify `ur` service is running.
- Inspect `ur` logs for transport-specific errors.

### G) XMPP reconnect loop in logs

- Confirm `XMPP_ADDRESS`, `XMPP_JID`, `XMPP_PORT`, and `XMPP_SECRET` are populated in `stack.env`.
- `XMPP_PORT` is parsed as an integer in settings; invalid values can cause repeated reconnect failures.
- The runtime now uses a single reconnect loop with exponential backoff to avoid overlapping reconnect churn.