CompactCool Migration Batch 6.0A — API Foundation
======================================================

PURPOSE
-------
Bring the permanent device API online at:

    https://api.compactcool.com/

without changing any installed timer endpoint yet.

EXPECTED SERVER LAYOUT
----------------------
/home/kkfcpofj/portal/
├── api/          <- document root of api.compactcool.com
├── includes/     <- NOT web accessible
├── storage/
│   └── logs/     <- NOT web accessible
└── public/       <- document root of portal.compactcool.com

DATABASE
--------
Database: compamrx_portal
Engine: MariaDB 10.5.x
Charset: utf8mb4

THIS BATCH DOES NOT
-------------------
- Redirect or disable compactcool-portal.co.za/api/
- Change installed timer firmware
- Change firmware endpoint constants
- Move the human portal
- Add new product functionality
- Overwrite your private secrets.php

FILES TO UPLOAD
---------------
Extract the ZIP into:

    /home/kkfcpofj/

The ZIP contains a `portal/` directory. It will merge into the portal directory
you already created.

Create / merge:
    portal/api/.htaccess
    portal/api/_auth_helper.php
    portal/api/ack_command.php
    portal/api/claim_check.php
    portal/api/commands_poll.php
    portal/api/enroll.php
    portal/api/firmware_manifest.php
    portal/api/firmware_status.php
    portal/api/ingest.php
    portal/api/poll_commands.php
    portal/api/receive_data.php
    portal/api/migration_check.php

    portal/includes/db.php
    portal/includes/secrets.php.example
    portal/includes/.htaccess

    portal/storage/logs/.htaccess
    portal/storage/logs/.keep

PRIVATE CONFIGURATION
---------------------
This package intentionally does NOT contain your database password, API token,
or secure test code.

If `/home/kkfcpofj/portal/includes/secrets.php` already exists and contains the
new database details, DO NOT overwrite it.

It must contain at least:

    DB_HOST = localhost
    DB_NAME = compamrx_portal
    DB_USER = compamrx_garth
    DB_PASS = your actual password
    DB_CHARSET = utf8mb4

During the transition, keep the SAME API_TOKEN and SECURE_TEST_CODE currently
used by the working production system. Changing them in the migration would
break legacy timer communication.

STEP 1 — UPLOAD ONLY
--------------------
Upload/extract this batch. Do not modify DNS, redirects, timer firmware, or the
old API.

STEP 2 — RUN THE PROTECTED DIAGNOSTIC
-------------------------------------
Open:

https://api.compactcool.com/migration_check.php?key=f75d7e524806d355409e7cd3c5046cac

Expected:

    "ok": true

The diagnostic verifies:
- HTTPS
- correct api.compactcool.com host
- /portal/api document-root location
- DB adapter and private secrets file
- connection to compamrx_portal
- MariaDB 10.5+
- required device/OTA tables
- required endpoint files
- utf8mb4
- writable private log directory

If any check fails, STOP. Do not test an installed timer against the new API yet.

STEP 3 — BASIC UNAUTHENTICATED SAFETY TESTS
-------------------------------------------
These tests should reject unauthenticated callers rather than throw HTTP 500:

    https://api.compactcool.com/firmware_manifest.php
    https://api.compactcool.com/firmware_status.php
    https://api.compactcool.com/receive_data.php

401/403/400 JSON responses are acceptable.
HTTP 500 is not acceptable.

STEP 4 — STOP POINT
-------------------
When the diagnostic passes and the three endpoints reject unauthenticated
requests cleanly, report the results back.

Do NOT migrate a timer yet.

The next batch/step will perform a controlled authenticated test against the new
API using an existing controller credential without changing the timer endpoint.

ROLLBACK
--------
Nothing in 6.0A modifies the old production API. If the new subdomain has a
problem, simply stop using api.compactcool.com and correct it. Existing timers
continue communicating with the old endpoint.

SECURITY NOTES
--------------
- `secrets.php` remains outside both web document roots.
- Device logs are moved outside the API document root.
- Directory listing is disabled.
- Debug telemetry-body logging is disabled by default.
- The migration diagnostic is protected by a temporary random key.
- Remove migration_check.php after migration validation is complete.
