vibtools · victorsteele · Aug 6, 2026 · Aug 6, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -3,6 +3,7 @@ name: CI
 on:
   push:
     branches: [main]
+    tags: ['v*']
   pull_request:
   workflow_dispatch:
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,7 +8,7 @@ All notable public-release changes are recorded here. Historical project notes r
 
 - Continue reviewed Zero Freedom development after the v5.1.0 installer release.
 
-## [5.1.0] - 2026-07-23
+## [5.1.0] - 2026-08-06
 
 ### Added
 
@@ -33,6 +33,14 @@ All notable public-release changes are recorded here. Historical project notes r
 
 - Enforced the installation lock for same-session requests to installer steps 1-8 after successful installation.
 - Restricted the completion screen to one pending view and cleared completion-session state before the admin-login redirect.
+- Prevented private installer configuration from pinning the source release version during future upgrades.
+- Removed exception messages, source paths, line numbers, and absolute installer paths from public responses.
+- Rejected Base URLs containing embedded credentials, query parameters, or fragments.
+- Rejected CR/LF characters in Mail From Name and validated installer-generated secrets before activation.
+- Refreshed cached file-status data before checking the `includes` directory and made the permission regression test portable across root-based CI containers.
+- Added a safe actionable diagnostic for database accounts that lack the `TRIGGER` privilege required by the existing schema.
+- Replaced release packaging based on the live directory with validated `git archive` packaging and SHA-256 output.
+- Corrected release, configuration, metadata, FAQ, compatibility, troubleshooting, and upgrade documentation for v5.1.0.
 
 ### Compatibility
 

diff --git a/PHASE2_INSTALLER_SUMMARY.md b/PHASE2_INSTALLER_SUMMARY.md
@@ -6,6 +6,7 @@
 - Stable base: `v5.0.1.1`
 - Base commit: `7fafd2c34b3425df6ef310b9f25ffa426588d294`
 - Development mode: Zero Freedom Development
+- Final release date: `2026-08-06`
 
 ## Implementation summary
 
@@ -101,6 +102,22 @@ The raw generated API credential is never displayed or logged.
 - Installer lock after completion
 - Existing configured database outage does not reopen installer
 
+
+## Final release hardening
+
+The unpublished v5.1.0 line was finalized before tagging with the following compatibility-preserving corrections:
+
+- Generic public exception responses and safe diagnostic references
+- Safe installer error mapping, including missing `TRIGGER` privilege
+- Hidden absolute server paths in requirement output
+- Base URL credential/query/fragment rejection
+- Mail From Name CR/LF rejection
+- Installer-generated secret validation
+- Source version precedence over preserved private configuration
+- Cached writability-state refresh and portable permission regression coverage
+- Git-ref-only release packaging with SHA-256 output
+- Corrected release and configuration documentation
+
 ## Upgrade compatibility
 
 - v5.0.1 and v5.0.1.1 private configuration remains supported.
@@ -125,3 +142,6 @@ Automated coverage includes:
 - Non-secret installation flag
 - Preserved schema/migration/frontend hashes
 - Preserved API and route markers
+- Safe exception and installer-error output
+- URL, mail-header, and generated-secret validation
+- Release-version consistency and Git-ref packaging
diff --git a/README.md b/README.md
@@ -68,16 +68,25 @@ The application is a server-rendered PHP project with no Composer runtime depend
 
 ## Quick start
 
+### Fresh installation
+
 1. Place the project in a non-public staging environment.
-2. Create an empty database and import `database.sql`, or open `install.php` once.
-3. Configure `includes/config.local.php` or environment variables.
-4. Sign in at `admin/login.php` using the temporary local-only account:
-   - Username: `admin`
-   - Password: `ChangeMe!2026`
-5. Change the password immediately from **Admin Users**.
-6. Delete or deny access to `install.php`.
+2. Create an empty MySQL/MariaDB database and a database account with the schema privileges required by `database.sql`, including `TRIGGER`.
+3. Open `install.php` or `/install` and complete the ten-step wizard.
+4. Create the first administrator in the wizard; no default password is retained after successful wizard installation.
+5. Confirm that `includes/config.local.php` and `includes/.licora-installed` were created and are not web-accessible.
+6. Sign in at `admin/login.php`, open `admin/health.php`, and complete an API/license/device smoke test.
 7. Configure HTTPS, cron, backups, and web-server deny rules before production use.
 
+### Manual import
+
+Importing `database.sql` directly creates a temporary local-only account:
+
+- Username: `admin`
+- Password: `ChangeMe!2026`
+
+Change that password immediately and create `includes/config.local.php` from `config.sample.php`.
+
 Complete steps: [docs/INSTALLATION.md](docs/INSTALLATION.md).
 
 ## API quick example
@@ -105,10 +114,13 @@ The application accepts deployment-specific values through environment variables
 | Purpose | Preferred variable | Default |
 |---|---|---|
 | Database host | `LICENSE_DB_HOST` | `localhost` |
+| Database port | `LICENSE_DB_PORT` | `3306` |
 | Database name | `LICENSE_DB_NAME` | empty |
 | Database user | `LICENSE_DB_USER` | empty |
 | Database password | `LICENSE_DB_PASS` | empty |
+| Application name | `APP_NAME` | `Licora` |
 | Application URL | `APP_URL` | `http://localhost` |
+| Application version | `APP_VERSION` | `5.1.0` |
 | Environment | `APP_ENV` | `production` |
 | Encryption key | `LICENSE_ENCRYPTION_KEY` | empty fallback |
 | API limit | `API_RATE_LIMIT` | `1000` |
@@ -122,7 +134,7 @@ Full reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 bash scripts/validate.sh
 ```
 
-The validation script checks PHP syntax, JavaScript syntax when Node.js is available, public-release secret markers, expected repository files, and the built-in security smoke test. Database-backed behavior requires a disposable MySQL/MariaDB instance and is not simulated by the static validation suite.
+The validation script checks PHP syntax, security behavior, compatibility invariants, installer parsing and lock behavior, release-version consistency, safe public errors, JavaScript syntax, public-release secret markers, and SQL seed scope. Database-backed behavior still requires a disposable MySQL/MariaDB instance.
 
 ## Documentation
 
@@ -137,6 +149,7 @@ The validation script checks PHP syntax, JavaScript syntax when Node.js is avail
 - [Maintenance](docs/MAINTENANCE.md)
 - [Release guide](docs/RELEASE.md)
 - [Troubleshooting](docs/TROUBLESHOOTING.md)
+- [v5.1.0 release notes](RELEASE_NOTES_v5.1.0.md)
 - [v5.0.1 release notes](RELEASE_NOTES-v5.0.1.md)
 - [v5.0.0 release notes](RELEASE_NOTES.md)
 - [Forensic audit](audit/FORENSIC_AUDIT_REPORT.md)
@@ -145,7 +158,14 @@ The validation script checks PHP syntax, JavaScript syntax when Node.js is avail
 
 ## Known limitations
 
-The audit intentionally records unresolved behavior rather than silently changing application logic. Important items include a legacy unauthenticated verification endpoint, Bearer-header parsing inconsistencies, an unused session-timeout method, settings that are stored but not enforced, unauthenticated encryption, destructive admin actions implemented through query strings, and CDN supply-chain exposure. Review the audit before production deployment.
+- The legacy `/api/check_license.php` endpoint remains unauthenticated for compatibility; new clients should use `/api/verify.php` with an API key.
+- Several stored settings remain informational or only partially connected to runtime enforcement.
+- The admin interface depends on public CDN assets unless a deployment vendors them locally.
+- Nginx and LiteSpeed operators must reproduce the supplied Apache deny rules.
+- The standard schema requires database privileges including `TRIGGER`; some free shared hosts do not provide them.
+- Full browser and database-backed regression testing remains a release/deployment responsibility.
+
+Review [SECURITY.md](SECURITY.md), [docs/COMPATIBILITY_MATRIX.md](docs/COMPATIBILITY_MATRIX.md), and the forensic audit before production deployment.
 
 ## Roadmap
 

diff --git a/RELEASE_COMMANDS_v5.1.0.md b/RELEASE_COMMANDS_v5.1.0.md
@@ -0,0 +1,157 @@
+# Licora v5.1.0 Release Commands for Windows
+
+These commands assume the repository is located at:
+
+```text
+D:\VibTools_Workspace\02_Websites\01_Licora_Open_Source_Cental_License_System\github_release
+```
+
+## 1. Preserve the current v5.1.1 branch work
+
+Run before extracting the v5.1.0 delta patch:
+
+```bat
+cd /d D:\VibTools_Workspace\02_Websites\01_Licora_Open_Source_Cental_License_System\github_release
+
+git status
+git stash push -u -m "backup-before-v5.1.0-final-release"
+git fetch origin --prune --tags
+git switch main
+git pull --ff-only origin main
+git switch -c release/v5.1.0-final
+```
+
+Extract the delta ZIP into the repository root and allow overwrite/replace.
+
+Do not extract the patch while still on `feature/v5.1.1-quality-stability`.
+
+## 2. Validate the patched source
+
+From Git Bash:
+
+```bash
+bash scripts/validate.sh
+```
+
+From Command Prompt:
+
+```bat
+git diff --check
+git status --short
+```
+
+Complete the manual release gate described in `docs/RELEASE.md` before tagging.
+
+## 3. Review and commit
+
+```bat
+git status
+git diff --stat
+git diff --check
+git add -A
+git diff --cached --check
+git diff --cached --stat
+git commit -m "release: finalize Licora v5.1.0 installer"
+git push -u origin release/v5.1.0-final
+```
+
+## 4. Create and merge the pull request
+
+With GitHub CLI:
+
+```bat
+gh pr create ^
+  --base main ^
+  --head release/v5.1.0-final ^
+  --title "release: Licora v5.1.0 Smart Installer" ^
+  --body-file RELEASE_NOTES_v5.1.0.md
+
+gh pr checks --watch
+gh pr merge --merge
+```
+
+If branch protection requires a PR number, use:
+
+```bat
+gh pr view --web
+```
+
+After merge:
+
+```bat
+git switch main
+git pull --ff-only origin main
+git status
+git log --oneline --decorate -10
+```
+
+## 5. Run final validation on `main`
+
+From Git Bash:
+
+```bash
+bash scripts/validate.sh
+```
+
+Confirm the exact version markers:
+
+```bat
+git grep -n "5.1.0" -- includes/config.php includes/installation.php install.php config.sample.php CHANGELOG.md RELEASE_NOTES_v5.1.0.md
+```
+
+## 6. Create the annotated tag
+
+```bat
+git tag -a v5.1.0 -m "Licora v5.1.0 - Smart Installer and First-Run Wizard"
+git show --stat --oneline v5.1.0
+git push origin v5.1.0
+```
+
+## 7. Build the release ZIP and checksum
+
+Run from Git Bash:
+
+```bash
+bash scripts/package-release.sh v5.1.0 v5.1.0
+```
+
+Expected files in the parent directory:
+
+```text
+Licora-v5.1.0.zip
+Licora-v5.1.0.zip.sha256
+```
+
+## 8. Publish the GitHub Release
+
+From Command Prompt, adjust the asset paths if your repository parent differs:
+
+```bat
+gh release create v5.1.0 ^
+  ..\Licora-v5.1.0.zip ^
+  ..\Licora-v5.1.0.zip.sha256 ^
+  --verify-tag ^
+  --title "Licora v5.1.0 - Smart Installer and First-Run Wizard" ^
+  --notes-file RELEASE_NOTES_v5.1.0.md ^
+  --latest
+```
+
+## 9. Verify the published release
+
+```bat
+gh release view v5.1.0 --web
+git status
+git tag --sort=-v:refname
+```
+
+Download the published ZIP, verify its checksum, extract it into a disposable folder, run `bash scripts/validate.sh`, and complete one fresh installation plus one authenticated `/api/verify.php` test.
+
+## Recovery of the preserved branch work
+
+The original v5.1.1 work remains in the stash and its remote branch. To inspect the stash later:
+
+```bat
+git stash list
+```
+
+Do not apply that stash onto the v5.1.0 release branch.
diff --git a/RELEASE_NOTES_v5.1.0.md b/RELEASE_NOTES_v5.1.0.md
@@ -1,5 +1,6 @@
 # Licora v5.1.0 — Smart Installer & First-Run Wizard
 
+**Release date:** 2026-08-06
 **Release type:** Backward-compatible installer feature release
 **Stable base:** `v5.0.1.1`
 **Database migration:** None
@@ -111,6 +112,21 @@ Demo records can be removed with:
 php scripts/remove-demo-data.php
 ```
 
+
+## Release hardening included
+
+Before publication, the v5.1.0 line received additional release-readiness fixes without changing the database schema, license engine, or API contracts:
+
+- Public exception responses no longer expose exception messages, source paths, or line numbers.
+- Installer requirement output no longer exposes absolute server paths.
+- Base URLs containing embedded credentials, query strings, or fragments are rejected.
+- Mail From Name rejects CR/LF characters.
+- Installer-generated application and security secrets are validated before finalization.
+- Runtime release identity resolves before preserved private configuration, preventing version pinning during future upgrades.
+- Cached filesystem status is refreshed before checking whether `includes/` is writable.
+- Database `TRIGGER` permission denial is mapped to an actionable, non-secret installer message.
+- Release packaging uses a validated Git ref and produces a SHA-256 checksum.
+
 ## Compatibility guarantees
 
 This release does not change:
@@ -164,6 +180,11 @@ The repository validation suite covers:
 - JavaScript syntax
 - Public-release marker scanning
 - SQL seed-scope validation
+- Release-version consistency
+- Safe public-error mapping
+- Base URL and mail-header validation
+- Installer permission-state ordering
+- Git-ref release packaging markers
 
 ## Documentation
 
@@ -172,4 +193,19 @@ The repository validation suite covers:
 - `docs/FIRST_RUN_GUIDE.md`
 - `docs/UPGRADE_GUIDE.md`
 - `docs/DEMO_DATA.md`
+- `docs/FAQ.md`
+- `docs/COMPATIBILITY_MATRIX.md`
+- `docs/RELEASE.md`
+- `RELEASE_COMMANDS_v5.1.0.md`
 - `PHASE2_INSTALLER_SUMMARY.md`
+
+## Hosting privilege note
+
+The unchanged Licora schema contains MySQL/MariaDB triggers. The standard installer therefore requires a database account with the privileges needed to create those triggers. Some free shared hosts deny `TRIGGER`; v5.1.0 reports that condition safely but does not silently remove schema objects.
+
+## Release assets
+
+The official release should include:
+
+- `Licora-v5.1.0.zip`
+- `Licora-v5.1.0.zip.sha256`
diff --git a/REPOSITORY_METADATA.md b/REPOSITORY_METADATA.md
@@ -4,7 +4,7 @@
 
 - **Name:** `Licora`
 - **Title:** Licora — Open-Source Central License Management System
-- **Description:** Licora is an open-source, self-hosted PHP and MySQL/MariaDB central license management system with license validation, API-key binding, device controls, administration, audit logs, and backups.
+- **Description:** Licora is an open-source, self-hosted PHP and MySQL/MariaDB central license management system with authenticated license validation, API-key/application binding, device controls, administration, audit logs, and backups.
 - **Homepage:** `https://vib.tools/`
 - **Visibility:** Public
 - **Default branch:** `main`
@@ -14,10 +14,15 @@
 
 `php`, `mysql`, `mariadb`, `license-management`, `license-server`, `license-key`, `api-key`, `device-management`, `admin-dashboard`, `self-hosted`, `php8`, `csrf-protection`, `rate-limiting`, `audit-log`, `vibtools`
 
-## Release title
+## v5.1.0 release
 
-`v5.0.1 — Branding and Company Information Hotfix`
+- **Tag:** `v5.1.0`
+- **Target:** reviewed `main` commit containing the final installer-lock and release-readiness fixes
+- **Title:** `Licora v5.1.0 — Smart Installer & First-Run Wizard`
+- **Latest release:** Yes, after all release-gate checks pass
+- **Release notes:** `RELEASE_NOTES_v5.1.0.md`
+- **Assets:** `Licora-v5.1.0.zip` and `Licora-v5.1.0.zip.sha256`
 
 ## Release summary
 
-Documentation-only hotfix that applies the Licora product identity, corrects Vib Tools company information, updates repository links, and replaces the private support contact without changing application behavior.
+Licora v5.1.0 adds a ten-step first-run installer, delimiter-aware schema execution, secure administrator and secret generation, atomic private configuration, installation locking, optional demo data, database-port support, safe installer diagnostics, and expanded regression validation. The release preserves the existing license engine, API contracts, database schema, routes, admin UI, cron entry points, and encrypted-data compatibility.