# 000 — `olsitec-foundation` Baseline (Overlay)

> This project follows the **canonical Olsitec agentic baseline**.
>
> **Canonical source**: `../../ai-baseline/000_baseline.md` (git repo `ai-baseline`, hosted at
> `forge.olsitec.de/olsitec/ai-baseline` once the foundation is up). Read it for the full operating
> model, modes, prime directives, documentation thresholds, delegation, and session protocols.
>
> This file lists only **foundation-specific deviations**. Where this overlay and the canonical
> baseline disagree, **this overlay wins for foundation work**.

---

## Foundation-Specific Deviations

### D1 — Default mode is HIGH-RISK / INFRA
Almost all foundation work touches a VM, Docker, Vault, Postgres, or secrets. Treat **BOOTSTRAP /
day-zero work as HIGH-RISK / INFRA by default**: verify host/cwd/branch, log commands, snapshot
before destructive steps (canonical §2.3, §11). Drop to BUILD only for pure docs/package edits.

### D2 — The master passphrase is sacred
- `PULUMI_CONFIG_PASSPHRASE` is the single root of trust (PLAN-002 §4, ADR-002).
- **Never** print, echo, log, or commit the passphrase, the Vault root token, or Vault unseal keys —
  except as the already-encrypted `secure: v1:…` values inside `Pulumi.foundation.yaml`.
- Secrets at rest live **only** in: passphrase-encrypted Pulumi config, or Vault. Never in plain
  files, never in docs, never in command logs.

### D3 — Hosting is Forgejo, not gitlab.com
- The canonical baseline / ADR-003 references `gitlab.com:olsitec-nci/*`. For the foundation, the
  source of truth is **foundation-Forgejo** (`forge.olsitec.de/olsitec/*`). GitLab is what we are
  **replacing**.
- During day-zero (before handover) the canonical remote may be a local clone + offsite mirror; after
  PLAN-002 Phase 7, origin is Forgejo.

### D4 — Pulumi runs against a remote VM over SSH
- `bootstrap/` deploys via `@pulumi/docker` over SSH to the foundation VM. Before any `pulumi up`:
  confirm **which VM** the Docker provider targets, the SSH key, and that you are on the intended
  stack (`pulumi stack ls`). A local edit is **not** present on the VM until applied.

### D5 — Determinism is a hard requirement
- Pin every image and tool by **digest** in `VERSIONS`. No floating tags. `preflight/` enforces it.
- Credentials: random (high-entropy, via `@pulumi/random` → Vault) vs derived (deterministic from
  config). The only external secret is the passphrase (PLAN-002 §4.2).

### D6 — MCP may not know this project yet
- `olsitec-foundation` is **not** registered in Olsitec MCP at authoring time (verified: MCP returns
  only omnibook/fishreg/olsitrack2/svelte_common/third_party_apis/external_data_sync/seaspots).
- Treat **this repo as the source of truth**; register the project in MCP once stable (PLAN-002 §8).

### D7 — Repo topology
- Read [000_TOPOLOGY.md](000_TOPOLOGY.md) before creating files: know whether your change belongs in
  `bootstrap/`, a `packages/pulumi-*`, `documentation/`, or the separate `ai-baseline` repo.
- Never bypass the four foundation interfaces (repo in Forgejo, image/chart in Forgejo registry,
  secret in Vault, CI in Forgejo Actions) once they exist.

### D8 — Document homes
- Planning & strategy → `documentation/planning/`.
- Architecture decisions → `documentation/decisions/` (ADR-NNN).
- Interface contracts (T00) → `documentation/contracts/` (CONTRACT-NNN).
- Per-task agent workspaces → `documentation/agents/task_NNN_*/` (canonical §7.2).

---

## Quick pointers

| Need | Go to |
|------|-------|
| Full workflow rules | `../../ai-baseline/000_baseline.md` |
| Why the platform is layered | `decisions/ADR_004_layered_platform_foundation.md` |
| Repo boundaries / module strategy | `decisions/ADR_005_repo_topology.md`, `000_TOPOLOGY.md` |
| The vision | `planning/PLAN-001-forgejo.md` |
| The implementation strategy & task list | `planning/PLAN-002-foundation-implementation.md` |