rd13_copilot_setup/docs/ADMIN.md

# Administrator-Handbuch – rd13_copilot_setup

> Zielgruppe: **Administratoren & DevOps** – Menschen, die das Setup deployen und auf Systemen verwalten.

---

## Systemvoraussetzungen

| Komponente | Anforderung |
|---|---|
| Git | ≥ 2.28 |
| Shell | POSIX sh (bash, dash) oder fish ≥ 3.x |
| VS Code / VS Code Server | beliebige aktuelle Version |
| OS | Linux oder macOS |

---

## Deployment auf einem neuen System

```bash
git clone <repo-url> ~/dotfiles/copilot-setup
cd ~/dotfiles/copilot-setup

bash scripts/deploy.sh        # bash (macOS + Linux)
# oder
fish scripts/deploy.fish      # fish (Linux)
```

### Was das Deploy-Skript tut

| Schritt | Was | Ziel |
|---|---|---|
| 1 | VS Code User-dir ermitteln | plattformspezifisch (Server / lokal / macOS) |
| 2 | `settings.json` deployen | `~/.vscode-server/data/User/` (oder Äquivalent) |
| 3 | Prompt Files deployen | `~/.vscode-server/data/User/prompts/` |
| 4 | Git-Templates deployen | `~/.git-templates/` inkl. Hooks, Docs, History-Template |
| 5 | Bootstrap-Skript installieren | `~/.local/bin/copilot-bootstrap.sh` |
| 6 | Git-Alias setzen | `~/.gitconfig` → `git init` ruft Bootstrap automatisch auf |

---

## Git-Templates verwalten

Die Templates unter `git-templates/` werden beim Deployen nach `~/.git-templates/` kopiert.
Sie werden bei **jedem** `git init` automatisch in neue Repos kopiert (via `init.templateDir`).

**Struktur nach Deploy:**
```
~/.git-templates/
├── .github/copilot-instructions.md
├── .vscode/settings.json
├── .vscode/extensions.json
├── hooks/
│   └── pre-commit          ← Agent Quality Gate (ausführbar)
├── docs/
│   ├── USER.md
│   ├── ADMIN.md
│   └── MAINTAINER.md
└── history/
    └── summary/
        └── PROJECT_CONTEXT.md
```

---

## pre-commit Hook verwalten

Der Hook liegt in `git-templates/hooks/pre-commit` und wird automatisch deployed.

**Hook aktivieren in bestehenden Repos (manuell):**
```bash
cp ~/.git-templates/hooks/pre-commit /path/to/repo/.git/hooks/pre-commit
chmod +x /path/to/repo/.git/hooks/pre-commit
```

**Hook deaktivieren (pro Commit):**
```bash
git commit --no-verify -m "..."
```

**Hook dauerhaft deaktivieren (pro Repo):**
```bash
chmod -x .git/hooks/pre-commit
```

---

## Bestehende Repos ausstatten

```bash
cd /path/to/existing-repo
copilot-bootstrap.sh
# oder von überall:
sh ~/.local/bin/copilot-bootstrap.sh /path/to/repo
```

Das Bootstrap-Skript legt idempotent an:
- `.github/copilot-instructions.md`
- `.vscode/settings.json` + `.vscode/extensions.json`
- `data/` (gitignored)
- `history/prompts/` (committed) + `history/summary/PROJECT_CONTEXT.md`
- `docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md`
- `.git/hooks/pre-commit`
- `.gitignore`-Einträge für `data/**/*`

---

## `~/.local/bin/` im PATH?

Das Bootstrap-Skript wird in `~/.local/bin/` installiert. Sicherstellen dass dieser Pfad im `$PATH` ist:

**bash/zsh** (`~/.bashrc` / `~/.zshrc`):
```bash
export PATH="$HOME/.local/bin:$PATH"
```

**fish** (`~/.config/fish/config.fish`):
```fish
fish_add_path ~/.local/bin
```

---

## Troubleshooting

| Problem | Ursache | Lösung |
|---|---|---|
| `copilot-bootstrap.sh: command not found` | `~/.local/bin` nicht im PATH | Siehe "PATH" oben |
| `git init` ruft Bootstrap nicht auf | Git-Alias nicht gesetzt | `deploy.sh` erneut ausführen |
| Hook schlägt fehl obwohl alles ok | Falsch-positiver Match | `git commit --no-verify` |
| Hook nicht aktiv nach `git clone` | Hooks werden bei `clone` nicht kopiert | `copilot-bootstrap.sh` im geklonten Repo ausführen |