docs re-org, audit fixes, build fixes

2026-01-05 09:35:33 +02:00
parent eca4e964d3
commit dfab8a29c3
173 changed files with 1276 additions and 560 deletions
--- a/docs/CONCELIER_CLI_QUICKSTART.md
+++ b/docs/CONCELIER_CLI_QUICKSTART.md
@@ -0,0 +1,102 @@
+# 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/INSTALL_GUIDE.md` (Compose profiles under `deploy/compose/`).
+- Offline/air-gap: follow `docs/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/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/API_CLI_REFERENCE.md`