# Session Summary + Reusable Playbook (Secrets Hygiene, Guardrails)

> **Audience:** Agents working on LysnrAI (or any BytelystAI repo) who need a repeatable checklist.
> **Scope:** Secrets hygiene + repo guardrails (commit/push blockers) for `learning_voice_ai_agent`.
> **Source playbook:** `../learning_multimodal_memory_agents/docs/WINDSURF/CODEX_SESSION_SUMMARY_AND_PLAYBOOK.md`
> **Last updated:** 2026-02-14

---

## What We Did (This Repo)

### 1. Stopped Committing Secret Values

- Added tracked templates (placeholders only):
  - `.env.example`
  - `backend/.env.example`
  - `services/*/.env.example`
  - `admin-dashboard-web/.env.local.example`
  - `user-dashboard-web/.env.local.example`
  - `tracker-dashboard-web/.env.local.example`
- Updated docs to reference `*.example` templates.
- Updated `.gitignore` to ignore local env files (`.env`, `.env.local`, `.env.*.local`) and common key/cert formats (`*.pem`, `*.p12`, `*.pfx`, `*.key`).

**Important:** If any secret value ever landed in git history, treat it as compromised and rotate it.

### 2. Added Guardrails So Secrets Don’t Land In Git Again

Scripts:

- Staged-diff scan (blocks commits): `scripts/secret-scan-staged.sh`
- Tracked-file scan (blocks pushes / manual checks): `scripts/secret-scan-repo.sh`

Git hooks (repo-local, no extra tooling):

- `.githooks/pre-commit` runs `scripts/secret-scan-staged.sh`
- `.githooks/pre-push` runs `scripts/secret-scan-repo.sh`
- `scripts/setup-git-hooks.sh` configures `core.hooksPath=.githooks`

Quality checks:

- `scripts/check.sh` now runs the tracked-file secret scan first
- `make check` includes `make secrets` (tracked-file secret scan)

---

## Reusable Playbook (Apply To Other Repos)

Use this as a checklist for a new repo or a repo that accidentally leaked secrets.

### A. Secrets Hygiene (Do This First)

- [ ] Inventory all secrets the repo uses (Cosmos, Storage, OpenAI, Speech, Notification Hub, App Insights, Stripe, etc.).
- [ ] Create/choose an Azure Key Vault per environment (`kv-<env>`).
- [ ] Pick canonical secret names (prefix by product): `mindlyst-*`, `lysnr-*`, etc.
- [ ] Move secret **values** into Key Vault.
- [ ] Remove secret **values** from:
  - [ ] Markdown docs
  - [ ] `.env*` files
  - [ ] source code
  - [ ] CI logs / README examples
- [ ] If a secret ever landed in git history:
  - [ ] Treat it as compromised
  - [ ] Rotate it (do not delay for “later cleanup”)

### B. Guardrails (Prevent Regressions)

- [ ] Add `.gitignore` entries:
  - [ ] `.env`, `.env.local`, `.env.*.local`
  - [ ] `*.pem`, `*.p12`, `*.pfx`, `*.key`
- [ ] Add staged secret scanning (commit blocker):
  - [ ] `scripts/secret-scan-staged.sh`
  - [ ] Hook it via Husky / `core.hooksPath` / pre-commit framework
- [ ] Add tracked-file scanning (push blocker):
  - [ ] `scripts/secret-scan-repo.sh`
  - [ ] Hook it via Husky / `core.hooksPath` / pre-commit framework

### C. Basic Abuse Controls For Any LLM Routes (Denial-of-Wallet Protection)

- [ ] Identify every route that calls an LLM provider (Azure OpenAI/OpenAI/etc.).
- [ ] Add request body caps.
- [ ] Add rate limiting (per-user preferred; fallback per-IP).
- [ ] Add field-level guards (max message/content chars; max history length + total chars).
- [ ] Document defaults + env knobs in a single doc.
- [ ] For production / multi-instance: replace in-memory rate limiting with Redis/Upstash/platform-native limiting.

### D. Beta Readiness Tracking

- [ ] Create a single “go/no-go” checklist doc and keep it current:
  - [ ] Verified checks (lint/build/tests, secret scan)
  - [ ] Remaining blockers (auth, hosting, KV integration, monitoring, backups)

---

## Quick Commands (Local Agent Workflow)

```bash
# One-time: enable repo-local git hooks
bash scripts/setup-git-hooks.sh

# Secret scan (tracked files)
bash scripts/secret-scan-repo.sh

# Full local checks (includes secret scan)
bash scripts/check.sh
make check
```
