# CLAUDE.md — app.theclientspeaks.com

This app was provisioned by **SpinUp** and follows the RestartWorks `/public` docroot standard. This file is working memory — read it first, every session, before touching this repo.

## Directory layout

```
app.theclientspeaks.com/                      <- repo root == ~/Apps/app.theclientspeaks.com locally
├── .env                          <- secrets/config, gitignored, NEVER committed
├── logs/                         <- app.log, deploy.log — gitignored content
├── docs/
│   └── STATUS.md                 <- THIS app's current status/notes — check it, it's the source of truth for what's actually done vs. planned
└── public/                       <- web-accessible docroot (cPanel points here)
    ├── index.php                 <- post-login landing page ("Welcome - {email}" + Sign Out), if Login Page has been deployed
    ├── login.php                 <- sign-in page (Google/Microsoft), if Login Page has been deployed
    ├── terms.php                 <- ToS boilerplate, if Login Page has been deployed — edit [COMPANY_NAME]/[CONTACT_EMAIL] before relying on it
    ├── logout.php                <- destroys session, redirects to /login.php
    ├── includes/
    │   ├── env.php                <- loads .env once — the ONLY file that should parse it
    │   ├── session.php            <- session config + auth_required()/current_user_id()/destroy_stale_session()
    │   └── db.php                 <- PDO connection ($pdo)
    ├── api/auth/
    │   ├── google.php             <- Google OAuth handler, if wired
    │   └── ms.php                 <- Microsoft OAuth handler, if wired
    └── deploy.php                 <- gitignored webhook receiver, hand-placed by SpinUp — never hand-edit or commit this
```

## What SpinUp can/does wire in

Don't assume any of this is actually turned on for THIS app — check `docs/STATUS.md` and/or SpinUp's Edit domain tab (button colors: green = configured, red = not) before relying on it. Anything below not yet wired can be added via SpinUp without hand-editing this repo.

- **Databases** — dev+prod MySQL, credentials in `.env` (`DB_HOST`/`DB_NAME`/`DB_USER`/`DB_PASS`).
- **Git + deploy pipeline** — GitHub repo (`main`+`dev` branches), webhook-triggered `git pull` on push, `DEPLOY_WEBHOOK_SECRET` in `.env`.
- **Google OAuth** — this app's own Client ID/Secret (never shared across apps), `.env`'s `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI`, handler at `public/api/auth/google.php`.
- **MS OAuth** — same per-app model, `.env`'s `MS_CLIENT_ID`/`MS_CLIENT_SECRET`/`MS_REDIRECT_URI`/`MS_TENANT_ID`, handler at `public/api/auth/ms.php`.
- **Login Page** — `login.php` only shows the sign-in button for whichever provider is actually configured (no ordering dependency), plus `terms.php`/`index.php`/`logout.php`.
- Google and MS OAuth share **one generic `users` table** — `auth_provider` column (`'google'` vs `'microsoft'`) is the only difference.

## How to work in this repo — follow exactly

- **Always edit files in the LOCAL clone at `~/Apps/app.theclientspeaks.com` first.** Never SSH/hand-edit anything git-tracked directly on the live dev/prod server — an untracked file sitting in the working tree silently breaks `deploy.php`'s `git pull` on the next push, with no visible error.
- **Push to `dev` after every commit** — that's what gets tested. Don't stack up multiple local commits before pushing.
- **Never merge or push to `main` (prod) without explicit, in-the-moment permission.** Don't infer it from "dev's been stable for a while" — always ask first.
- Run `git remote -v` before any push — confirm you're pointed at the right repo before doing anything.
- `.env` is gitignored — never commit it. Secrets live only in `.env` on each environment, never in git history.
- GitHub fine-grained PAT, for pushing to `dev` when the Mac's own SSH auth to GitHub isn't available in the current environment (e.g. a sandboxed session):
  ```
  git remote set-url origin https://x-access-token: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@github.com/davidkillion/app.theclientspeaks.com.git
  ```
  Set the remote back to normal (or remove this temporary one) once the push is done, if it isn't the environment's usual remote.
- Every file gets a version header + CHANGELOG (format `v1.0.0000`, increment the last 4 digits per edit) — matches every other SpinUp-scaffolded file in this repo.