# Multi-Company — Activation & Pilot Runbook

> Everything built so far is **inert in production**: with no `company` scope assigned,
> every user sees exactly their home company (today's behavior). This is how to turn
> multi-company **read** on for a pilot user, verify it, and revoke it.
>
> Read-only by default — a `company` scope grants visibility, not write authority
> (see [write-path-and-permissions.md](write-path-and-permissions.md)).

## How it flows (recap)
`auth: user_scopes(scope_type=company, value=<companies.id>)` → fleet
`AccessibleCompanyResolver` reads it via `getUserScopes` (cached 60s) → maps each
company id to its owner via `companies.user_id` → `TenantScope` filters every flipped
model's queries by the accessible set.

**Id note:** the scope value is a `companies.id`. Auth and fleet share company ids
(`auth.companies.id === fleet.companies.id`, verified), so use the company's id from
either system.

## Step 1 — Seed the `company` scope type (auth service, once)
```bash
# in dadycar-auth-service
php artisan db:seed --class=ScopeTypeSeeder      # idempotent; adds the 'company' scope type
```

## Step 2 — Grant a pilot user access to another company (auth service)
`USER_ID` = the human's `users.id`; `COMPANY_ID` = the other company's `companies.id`
they should also see (their home company is always included automatically).
```bash
# in dadycar-auth-service — grant access to one (or more) specific companies
php artisan tinker --execute="app(App\Services\ScopeService::class)->assignScopesToUser(USER_ID, 'company', ['COMPANY_ID']);"

# OR grant unrestricted (all companies) — e.g. a group/platform operator:
php artisan tinker --execute="app(App\Services\ScopeService::class)->assignFullAccessToUser(USER_ID, 'company');"
```

## Step 3 — Verify (fleet)
As that user, hit any **flipped** model's list endpoint and confirm rows from the
granted company now appear alongside the home company's. Flipped so far (read):
`tickets`, `aen/rules`, `maintenance-plans`, `toll-badges`, `fuel-cards`,
`vehicle-orders`, `generic-reminders` (index).

- Allow up to ~60s for the auth scope cache to refresh (or clear it).
- A single-company user (no scope) must be **unchanged** — that's the inert guarantee.
- Writes (create/update/delete) still target the home company by design.

## Step 4 — Revoke
```bash
# in dadycar-auth-service
php artisan tinker --execute="app(App\Services\ScopeService::class)->removeScopesFromUser(USER_ID, 'company');"
```

## Safety checks for the pilot
- **Internal admins** (`users.internal_role` set) get full access automatically — admin
  cross-tenant screens keep working.
- **Not-yet-flipped** models still scope to home even for a multi-company user (their
  explicit `userCompany->id` filter is still in place) — expected during the rollout.
- If a flipped endpoint returns **nothing** for the pilot user, check: scope assigned to
  the right `USER_ID`? `COMPANY_ID` is a real `companies.id`? cache refreshed?