# HUMANABLE

The Sovereign Recruitment Engine for HCMS — **Pillar I** of the HCMS App Suite.

> Owned by HCMS N.V. (subsidiary of K&K Heritage Group N.V.), Paramaribo, Suriname.
> Phase 14 (Hardening + Launch) — **all 14 FO §20.2 phases complete**.
> Laravel 13 · PHP 8.3 · React 18 + Inertia · Filament 4 admin · Fortify TOTP MFA ·
> 9 custom artisan commands · 8 AI agents · WhatsApp + Twilio + Asana real clients ·
> outbound webhook broadcasts · PostgreSQL FTS · Compliance Shield 1-8 wired ·
> App Suite bridges · QoH engine · `harden:audit` + `launch:readiness` + `backup:run` +
> production / Zoho-cutover / launch runbooks.
> Authoritative spec: [`docs/specs/HCMS-FO-HUMANABLE-Final-v1.3-Selfcontained-2026.md`](docs/specs/HCMS-FO-HUMANABLE-Final-v1.3-Selfcontained-2026.md).

---

## Local development (SQLite)

```bash
# 1. Install PHP 8.3+ and Composer 2.x, Node 20+, npm 10+
composer install
npm install

# 2. Bootstrap env
cp .env.example .env
php artisan key:generate
touch database/database.sqlite
php artisan migrate --seed

# 3. Run the dev stack (one process; uses concurrently)
composer dev
#   → http://127.0.0.1:8000              Inertia/React welcome
#   → http://127.0.0.1:8000/admin        Filament admin
#   → http://127.0.0.1:8000/pulse        Pulse dashboard
```

Default seeded admin:

| Email                  | Password                     |
| ---------------------- | ---------------------------- |
| `admin@hcmsnv.com`     | `change-me-on-first-login`   |

Override via env: `HUMANABLE_ADMIN_EMAIL`, `HUMANABLE_ADMIN_PASSWORD`.

### What you cannot do locally

- pgvector / AI matching (PG-only). Test on staging.
- Compliance Shield round-trips (service runs at port 8003 on the shared VPS).
- WhatsApp Business + Twilio + Google Drive backups (configured per env on staging).

## Production / staging stack (FO §29)

- PostgreSQL 16 + pgvector (shared schema `humanable` on the LiquidNet US VPS)
- Nginx + Let's Encrypt TLS, internal port `8001`
- systemd-managed Laravel queue worker (database queue driver)
- systemd timer for Laravel scheduler (or cron — see `deploy/`)
- Laravel Pulse for in-app monitoring
- Self-hosted Sentry for exception capture

VPS install artifacts live in [`deploy/`](deploy/README.md).

## Hard constraints (FO §29)

- ❌ No Docker. No Redis. No Meilisearch. No AWS managed services.
- ❌ No Laravel Horizon. No Supabase / Firebase.
- ✅ Laravel 13 + PHP 8.3 + Filament 4 (see [`docs/handoffs/phase-0.md`](docs/handoffs/phase-0.md) for the Filament 3 → 4 deviation rationale).
- ✅ SQLite local / PostgreSQL 16 + pgvector prod.
- ✅ Claude API primary, Gemini fallback, manual-required degrade (see `app/Support/AI/AiFailureChain.php`).
- ✅ Compliance Shield consumed via `App\Services\ComplianceShield\ComplianceShieldClient`.

## CI

- `.github/workflows/ci.yml` — Pint + PHPUnit + Vite build + forbidden-artifacts guard.
- `.github/workflows/deploy-staging.yml` — Push to `develop` → staging VPS.

## Documentation

- [`CLAUDE.md`](CLAUDE.md) — Working agreement for AI engineers (Claude Code).
- [`deploy/README.md`](deploy/README.md) — VPS install checklist (DevOps).
- [`docs/handoffs/phase-0.md`](docs/handoffs/phase-0.md) — Phase 0 handoff report.
- [`docs/handoffs/phase-1.md`](docs/handoffs/phase-1.md) — Phase 1 handoff report.
- [`docs/handoffs/phase-2.md`](docs/handoffs/phase-2.md) — Phase 2 handoff report.
- [`docs/handoffs/phase-3.md`](docs/handoffs/phase-3.md) — Phase 3 handoff report.
- [`docs/handoffs/phase-4.md`](docs/handoffs/phase-4.md) — Phase 4 handoff report.
- [`docs/handoffs/phase-5.md`](docs/handoffs/phase-5.md) — Phase 5 handoff report.
- [`docs/handoffs/phase-6.md`](docs/handoffs/phase-6.md) — Phase 6 handoff report.
- [`docs/handoffs/phase-7.md`](docs/handoffs/phase-7.md) — Phase 7 handoff report.
- [`docs/handoffs/phase-8.md`](docs/handoffs/phase-8.md) — Phase 8 handoff report.
- [`docs/handoffs/phase-9.md`](docs/handoffs/phase-9.md) — Phase 9 handoff report.
- [`docs/handoffs/phase-10.md`](docs/handoffs/phase-10.md) — Phase 10 handoff report.
- [`docs/handoffs/phase-11.md`](docs/handoffs/phase-11.md) — Phase 11 handoff report.
- [`docs/handoffs/phase-12.md`](docs/handoffs/phase-12.md) — Phase 12 handoff report.
- [`docs/handoffs/phase-13.md`](docs/handoffs/phase-13.md) — Phase 13 handoff report.
- [`docs/handoffs/phase-14.md`](docs/handoffs/phase-14.md) — Phase 14 handoff report.
- [`docs/runbooks/production-deploy.md`](docs/runbooks/production-deploy.md) — LiquidNet deploy runbook.
- [`docs/runbooks/zoho-cutover.md`](docs/runbooks/zoho-cutover.md) — Zoho Recruit cutover runbook.
- [`docs/runbooks/launch-checklist.md`](docs/runbooks/launch-checklist.md) — Soft + Full launch gate list.
- [`docs/specs/`](docs/specs/) — Authoritative FO documents (HUMANABLE + Compliance Shield).

## License

Proprietary © HCMS N.V. All rights reserved.