# Concelier + CLI Quickstart

This quickstart gets an operator to a working advisory ingestion loop:
- Run Concelier (advisory ingestion + deterministic normalization).
- Trigger ingestion/export jobs.
- Inspect results via the `stella` CLI.

This document stays high level and defers detailed configuration and connector behavior to the Concelier module dossier.

## 1) Prerequisites
- Deployment: follow `docs/21_INSTALL_GUIDE.md` (Compose profiles under `deploy/compose/`).
- Offline/air-gap: follow `docs/24_OFFLINE_KIT.md` and `docs/airgap/overview.md`.
- Local dev (optional): .NET SDK version pinned by `global.json`.

## 2) Run Concelier

### Option A: Run via deployment bundles (recommended)
Use the deterministic Compose profiles under `deploy/compose/` and enable Concelier in the selected profile.

Start here:
- `docs/21_INSTALL_GUIDE.md`
- `docs/modules/concelier/operations/`

### Option B: Run the service from source (dev/debug)
```bash
dotnet run --project src/Concelier/StellaOps.Concelier.WebService
```

Concelier reads `etc/concelier.yaml` by default (and supports environment overrides). See:
- `docs/modules/concelier/architecture.md`
- `docs/modules/concelier/operations/`

## 3) Configure Concelier (minimum)
1. Copy the sample config:
   ```bash
   mkdir -p etc
   cp etc/concelier.yaml.sample etc/concelier.yaml
   ```
2. Update storage/DSN and any connector configuration needed for your sources.
3. Keep configuration deterministic and offline-friendly (no hidden outbound calls in air-gap profiles).

Connector deep dives and operational guidance live under:
- `docs/modules/concelier/operations/connectors/`

## 4) Harden the `/jobs*` surface with Authority (recommended)
Concelier job triggers are operationally sensitive. In production-style installs, require Authority-issued tokens.

Operator entry point:
- `docs/modules/concelier/operations/authority-audit-runbook.md`

At minimum, ensure:
- Authority enforcement is enabled.
- Anonymous fallback is disabled outside controlled rollout windows.
- Any bypass CIDRs are explicitly approved and monitored.

## 5) Use the CLI for ingestion and exports

This guide uses `stella` as the CLI command name. If your packaging uses a different filename, add a local shim/symlink.

### 5.1 Point the CLI at Concelier
Set the backend base URL (example):
```bash
export STELLAOPS_BACKEND_URL="https://concelier.example.internal"
```

Authenticate using the configured Authority credentials:
```bash
stella auth login
stella auth whoami
```

See: `docs/modules/cli/guides/commands/auth.md`.

### 5.2 Trigger connector stages
Trigger a connector stage (example):
```bash
stella db fetch --source osv --stage fetch
stella db fetch --source osv --stage parse
stella db fetch --source osv --stage map
```

### 5.3 Reconcile merges (when needed)
```bash
stella db merge
```

### 5.4 Produce exports
```bash
stella db export --format json
```

See: `docs/modules/cli/guides/commands/db.md`.

### 5.5 Inspect advisory results
For read-only inspection (list/get/export), use:
- `docs/modules/cli/guides/commands/advisory.md`

## 6) Next links
- Concelier module dossier: `docs/modules/concelier/README.md`
- Concelier operations: `docs/modules/concelier/operations/`
- CLI command guides: `docs/modules/cli/guides/commands/`
- API + CLI reference index: `docs/09_API_CLI_REFERENCE.md`