# Agent Identity Provisioning — Agent Guidelines

> **Governing baseline:** [`BASELINE-PROMPT.md`](https://git.knownelement.com/TSYSGroupCorporate/TSYSGroupAIOS/src/branch/master/BASELINE-PROMPT.md) (from TSYSGroupAIOS framework).
> **Read STATUS.md and questions-v1.md first, every session.**

This project provides Playwright-based automation for provisioning AI agent identities across the TSYS Group stack.

---

## Quick Start

1. **Set up the environment:** `bash scripts/setup-hooks.sh`
2. **Read STATUS.md** — current state.
3. **Check for understanding** — summarize the rules (see below).
4. **Build and run:**
   ```bash
   cp agents.yaml.example agents.yaml  # fill in invite links
   cp .env.example .env                # fill in BW credentials
   docker compose up --build
   ```

## Project Overview

Playwright automation that:
1. Enrolls AI agent identities in Cloudron (accept invite, set password, enable 2FA)
2. Logs into Gitea/Discourse/Redmine via Cloudron SSO
3. Generates per-agent API keys in each system
4. Stores all credentials in Bitwarden (per-agent collections)
5. Verifies API keys work

Architecture and full plan: `~/Q3/agent-identity-bootstrap.md`

## Repository Layout

```
agent-identity-provisioning/
├── AGENTS.md              ← THIS FILE
├── STATUS.md              ← agent scratchpad
├── WORKING.md             ← session task tracker
├── questions-v1.md        ← questions for the human
├── provision-agent.py     ← main Playwright script
├── bw-helper.py           ← Bitwarden CLI wrapper
├── agents.yaml.example    ← manifest template
├── Dockerfile             ← Playwright + bw CLI
├── docker-compose.yml     ← container lifecycle
├── requirements.txt       ← Python dependencies
├── Makefile               ← convenience dispatch
├── scripts/               ← TSYSGroupAIOS framework (hooks, rules engine)
└── state/                 ← provisioning state (gitignored)
```

## Systems of Record

- **Redmine** (#442) is the system of record for this work.
- **No Discourse doc** yet — will be created when the provisioning runbook is finalized.
- Git is the source of truth for the automation code.

## Git Workflow

- Work off master. Commit + push after every logical unit.
- Conventional format: `feat(provision): ...`, `fix(bw): ...`, etc.
- Shellcheck on all shell scripts (zero warnings, including info-level).
- Every commit references `[#442]`.

## Conventions

- **Python** for the Playwright automation. Type hints, docstrings.
- **Bitwarden CLI** for all credential operations — never hardcode credentials.
- **No browser state persistence** — each provisioning run starts fresh.
- **Container naming:** `tsys-agent-provisioner`.
- **Image pinning:** all images pinned to specific versions.