BEREA ART WATCH — UPDATE ZIP FORMAT 1
Applies to the v2.0.0 update manager and compatible future releases.

DEPLOYMENT ZIP VERSUS UPDATE ZIP
The full ai-ready-to-deploy-v2.0.0.zip contains the complete ai/ website.
Upload its ai/ contents over the files in your EXISTING ai/ directory.
It is NOT an update-manager ZIP. Keep the same server path to retain the
existing private SQLite database, images, password, notes and settings.
There is no installer, build, database import or dependency download.

Future surgical update ZIPs use the format below. Give this text file and
the current full site source to anyone preparing the next update.

ZIP LAYOUT (no outer ai/ or project directory)
  update.json
  files/
    app.js
    style.css
    ...only the complete files being added or replaced...

update.json is UTF-8 JSON:
{
  "format": 1,
  "app": "berea-art-watch",
  "base_version": "2.0.0",
  "version": "2.0.1",
  "notes": "Explain the user-visible changes.",
  "files": {
    "app.js": "PUT_THE_EXACT_64_CHARACTER_LOWERCASE_SHA256_HERE",
    "style.css": "PUT_THE_EXACT_64_CHARACTER_LOWERCASE_SHA256_HERE"
  },
  "delete": []
}

The digest placeholders above must be replaced with real SHA-256 values.
Hash the exact bytes put into the ZIP, including line endings. Never hash
an earlier copy and then edit or normalize the file. No build step runs
on the server. Every replacement is already complete and ready to run.

REQUIRED MANIFEST FIELDS
format       Integer 1.
app          Exactly berea-art-watch.
base_version The exact CURRENT version shown by Updates & versions.
version      A different version label; MAJOR.MINOR.PATCH, optionally followed
             by a hyphen and an alphanumeric/dot/hyphen prerelease label.
files        Object mapping destination paths to lowercase SHA-256 digests.
             A deletion-only update may use an empty object {}.
delete       Array of currently managed destination paths to remove; [] if none.
notes        Optional plain text summary, up to 2,000 bytes.

PATH RULES
Destinations are relative to the directory containing index.php.
For app.js, the ZIP entry MUST be files/app.js, with matching case.
For assets/example.css, the ZIP entry MUST be files/assets/example.css.
Do not prefix paths with ai/, public_html/, a slash, or a drive name.
Directory segments may contain letters, digits, underscores and hyphens.
Filenames may additionally contain dots, but no path may contain '..'.
Allowed extensions: php js css json txt html svg png jpg jpeg webp gif woff2 ico.
No hidden files, backslashes, NUL bytes, parent paths, symbolic links, special
files, encrypted entries, duplicate paths or case-duplicate ZIP entries.
Every regular ZIP entry must be update.json or a declared files/ entry.
Directory-only entries are optional and must be inside files/.
A path cannot appear in both files and delete.
An existing untracked file cannot be overwritten or deleted.
Required application files cannot be deleted: index.php, api.php, core.php,
reports.php, app.js, style.css. Replace these with complete working files.

PINNED RECOVERY FILES
maintenance.php, maintenance.js, maintenance.css and guard.php CANNOT be
replaced or deleted by update ZIPs. They remain available when an update
breaks the application. Changes to recovery infrastructure require a new
full deployment package reviewed and uploaded through hosting file access.
Keep the guard.php require at the start of index.php and core.php, before
any output or session access. New PHP entry points must take the same guard
lock before opening the shared admin session. Keep core.php's private-data
path and session identity compatible with these stable recovery files.

LIMITS / REQUIREMENTS
PHP 8.1+; existing PDO SQLite and GD requirements remain.
The update manager additionally uses PHP's standard ZIP (ZipArchive)
extension. Code backups/restores do not need ZIP.
Application directories must be writable by PHP for in-site code updates.
Private storage must remain writable and outside the document root.
Upload limit: 32 MiB ZIP, subject to lower hosting upload_max_filesize and
post_max_size settings. Max 1,000 entries, 20 MiB per expanded file, 64 MiB
expanded archive. Total managed code snapshot limit: 128 MiB.
Keep data, videos, original images and database files out of update ZIPs.
These are code/asset updates, not a content-import or database-restore system.

INSTALL FLOW
1. Sign in using the existing admin account.
2. Open Updates & versions (or maintenance.php directly).
3. Choose the update ZIP and select Review update.
4. Check the version, notes, replacements and deletions.
5. Select Back up & install update.
The manager validates the ZIP twice, including all file hashes, checks the
starting version, creates and verifies a full managed-code snapshot, and
then replaces only the declared files. It also saves the resulting version.
A review token expires after 30 minutes. Re-upload to review again.

BACKUPS AND RESTORES
The first authenticated use of the update manager saves the installed
v2.0.0 code as its baseline. Versions predating the initial full deployment
are not reconstructed or imported automatically.
Each update and restore creates another code backup BEFORE changing files.
Back up now creates an additional snapshot without installing anything.
Saved versions remain available; there is no automatic backup pruning.
Load this version restores its entire managed-code state, including removed
files, and removes managed files introduced after that snapshot.
Unrelated, unmanaged files are preserved. A name conflict blocks restoration.
Images, folders, folder visibility, manual records, notes, password and
settings in the private database stay at their CURRENT values.
A code backup is NOT a database or hosting disaster-recovery backup.

INTERRUPTED / BROKEN UPDATES
Code writes use temporary files and renames. An exclusive update lock blocks
new guarded requests while files change. A private transaction journal and
the verified pre-change backup support rollback after a failed operation.
If a request stops mid-install, open maintenance.php and sign in if needed.
The next authenticated manager request restores the previous saved code
before proceeding. If the filesystem is full or unwritable, recovery remains
pending until storage is writable again. Normal guarded entry points show
a maintenance message while recovery is pending.
If syntactically valid packaging contains broken application code, use this
independent recovery page to load a known working version. Hash validation
checks integrity and path safety, not application correctness or authorship.
Only install update ZIPs whose code you intend to run as the site owner.

FUTURE UPDATE COMPATIBILITY
Keep all existing database content. Schema changes must be additive and
backward compatible so older code can still use current data after rollback.
Do not drop, rename or repurpose existing columns/tables in a surgical ZIP.
Preserve authentication, CSRF checks, gallery permissions, crop-folder access
checks and original image data. Keep crops out of the gallery's analytics.
Bump cache query versions in index.php when changing JavaScript or CSS.
Update README.txt and visible version labels together with the manifest.
Test PHP, JavaScript, public/private permissions, install and restore before
sharing the update. The updater does not execute migration scripts, shell
commands, Composer, npm, or any post-install hook.