# Quick setup — first time on this backend

From a fresh clone to a running API, the docs viewer, and coding agents that
follow the project rules. About 10 minutes. Do the steps in order.

## 0. You need

| Tool | Version | Notes |
|------|---------|-------|
| PHP | 8.3+ | Extensions: `pdo_mysql`, `pdo_sqlite` (tests), `mbstring`, `intl`, `gd` or `imagick` (media) |
| Composer | 2.x | |
| MySQL | 8.x | One empty database for development |
| Redis | optional | Only when you switch cache/queue to Redis |

## 1. Install

```bash
composer install
cp .env.example .env
```

## 2. Fill `.env` — before running any other command

| Key | Set it to | Why |
|-----|-----------|-----|
| `APP_NAME` | the project name, e.g. `"My Shop"` | The only place the name lives: docs title, MCP server name (`my-shop-docs`) and agents follow it. **New project from this base?** Set it in `.env.example` too (or ask your agent to run `project-init` step 0). |
| `APP_ENV` | `local` | The docs viewer, API console, docs MCP server and Laravel Boost all run outside production only. |
| `APP_URL` | `http://localhost:8000` (or your host) | The MCP connection snippets on `/docs` are built from it. |
| `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` | your local MySQL database | |
| `QUEUE_CONNECTION` | keep `database` | Creating users queues jobs; see [Known issues](#known-issues). |

Then generate the two secrets (each writes into `.env`):

```bash
php artisan key:generate     # APP_KEY — without it every web page and test fails
php artisan jwt:secret       # JWT_SECRET — without it no login or token works
```

## 3. Database

```sql
CREATE DATABASE your_project CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

```bash
php artisan migrate --seed
```

The seed creates the demo accounts (password `12345678`). The API console's
**Quick Auth** signs in as them:

| Account | Login |
|---------|-------|
| Super admin | `admin@info.com` |
| Supervisor | `supervisor@info.com` |
| Client | `client@info.com` |

## 4. Run and check

```bash
php artisan serve                 # http://localhost:8000
php artisan test --compact        # tests use in-memory sqlite, your database is never touched
```

| Open | You should see |
|------|----------------|
| `http://localhost:8000/docs` | Docs dashboard: project brain, decisions, app surfaces, MCP connection snippets |
| `http://localhost:8000/tester` | API console → **⚡ Quick Auth** → *Super Admin* → send any admin request |
| `php artisan docs:brief client` | The client surface's feature brief (empty list until the BRD is added) |

## 5. Coding agents

The rules, skills and MCP servers are in the repo; each agent picks them up on its own:

| Agent | What to do once |
|-------|-----------------|
| Claude Code | Open the repo; approve the two project MCP servers it asks about (`laravel-boost`, `project-docs`). Check with `/mcp`. |
| Codex | Trust the project when asked (loads `.codex/config.toml` and `.codex/rules/project.rules`). |
| Kiro | Nothing — `.kiro/steering/` and the Postman hook load automatically. |
| OpenCode / Antigravity | Nothing — `opencode.json` / `.agents/mcp_config.json`. |
| Anything else | Point it at `AGENTS.md`. |

Then ask the agent: *"Run `php artisan docs:brief client` and tell me the status."* If it
answers from the brief instead of opening big files, it is set up correctly.

App developers (Flutter / React) connect their own agents to these docs with
[MCP_AGENT_GUIDE.md](MCP_AGENT_GUIDE.md).

## 6. Shared dev / staging server

Docs, the API console and the MCP server are **open on every environment except
production**. On any server reachable from the internet, set a token:

```dotenv
DOCS_TOKEN=<long random string>     # required by /docs, /tester and /mcp/docs
```

Production (`APP_ENV=production` or `prod`) keeps them hidden (404) unless both
`DOCS_ENABLED=true` and `DOCS_TOKEN` are set, and never issues Quick Auth tokens.

## 7. Next: add the BRD and screens

1. BRD (PDF, DOCX or markdown) → `docs/brd/` ([format](brd/README.md)).
2. Screens → `docs/app_screens/{surface}/` ([naming](app_screens/README.md)).
3. Ask your agent to run the **`project-init`** skill — step 1 confirms the apps
   (guards, Flutter or React), step 2 ingests the BRD, step 3 indexes the screens.
4. Build features with **`project-feature`**; every feature starts from
   `php artisan docs:brief {surface} {feature}`.

## Known issues

| Symptom | Cause | Until fixed |
|---------|-------|-------------|
| `queue:work` reports failed `NotifyParticipantsJob` jobs | It uses `App\Services\Utilities\Notifications\NotifyOrchestrator`, which does not exist in this base | Harmless for setup; don't run a queue worker until notifications are built, or clear them with `php artisan queue:flush` |
| `migrate --seed` crashes with *Target class … NotifyOrchestrator* | `QUEUE_CONNECTION=sync` runs that job during seeding | Keep `QUEUE_CONNECTION=database` |
| `Secret is not set` | `JWT_SECRET` missing | `php artisan jwt:secret` |
| `MissingAppKeyException` | `APP_KEY` missing | `php artisan key:generate` |
| `/docs` answers 404 | `APP_ENV=production`, or `DOCS_ENABLED=false` | Use `APP_ENV=local` |
