# ChatGPT-Interfaces Integration Specification **Interface Specification:** v0.6 **Compatible ChatGPT-Interfaces:** v0.0.9 **Site:** tiltedlogic.org ## Purpose This document is the handoff contract for a ChatGPT conversation that creates or updates a website which will be managed through the shared `ChatGPT-Interfaces` infrastructure. Use this specification instead of inventing project-specific deployment or administration machinery. A client website should contain the website/application itself. Shared deployment, rollback, user management, and ChatGPT-Interfaces administration belong in `public_html/ChatGPT-Interfaces`. ## 1. Shared Infrastructure The shared installation is: - Web path: `/ChatGPT-Interfaces/` - Physical directory: `public_html/ChatGPT-Interfaces` - Client operations page: `/ChatGPT-Interfaces/?client=` or the client card reached from the ChatGPT-Interfaces home page - Client deployment page: `/ChatGPT-Interfaces/client.php?client=` - Administration: `/ChatGPT-Interfaces/admin.php` Do not copy ChatGPT-Interfaces code into a client website. ## 2. Client Identity Every managed website has a stable lowercase client ID, for example: - `mars` — Mars Documentation - `kip` — KIP Apiary (when integrated) The ChatGPT-Interfaces client configuration records at minimum: - Client ID - Display name - Public website URL - Physical website target directory - Top-level directory expected in the deployment ZIP - Version/identity file expected by the deployment engine - Public-viewing and modification-access policy A website-building chat should state the intended client ID and package-root directory in its release notes. ## 3. Deployment Package Contract — Current v0.1 For the current deployment engine, a deployable ZIP must contain exactly one project top-level directory matching the configured `package_root`. Example for Mars: ```text Mars-Documentation-v1.3.zip └── Mars/ ├── index.php ├── catalog.php └── ...complete website... ``` The package must be a **complete deployable website**, not a patch. ChatGPT-Interfaces stages the package, preserves the current installation for rollback, installs the complete replacement, performs a basic post-install check, and restores/preserves the previous installation if deployment fails. The current deployment engine requires: - a readable ZIP; - the configured top-level `package_root` directory; - `index.php` in that directory; - the configured version file (currently `catalog.php` for standard documentation clients); - safe relative ZIP paths (no traversal or absolute paths). If a new website does not fit this contract—for example, it is not PHP, has no `index.php`, or uses a different version manifest—the website-building chat must identify that incompatibility. Do not silently reshape the application merely to pass the current validator. Extend ChatGPT-Interfaces deliberately instead. ## 4. Version Identity — Current Documentation Client Contract For documentation clients using the current deployment engine, `catalog.php` exposes machine-readable values in the form: ```php 'version' => '0.7.3', 'document_package' => '1.3', ``` These mean: - `version` — Documentation System/software version - `document_package` — content/document package version A content-only release increments the Document Package version. A website-system/software change increments the Documentation System version according to that project's standing workflow. A different class of application may require different version semantics. Define those explicitly before registering it as a client rather than pretending it is a documentation package. ## 5. Access Model ChatGPT-Interfaces currently has three access states: - **Public** — may view public client websites. - **Normal User** — may perform routine authenticated deployment/update operations. - **Administrator** — may manage users/credentials, clients/site configuration, rollback, and ChatGPT-Interfaces administration. Routine website/data/document updates should not require Administrator access unless a future client has a specific reason to impose that restriction. ### Important authentication boundary ChatGPT-Interfaces v0.0.4 provides shared authentication for **ChatGPT-Interfaces operations**. It does **not yet define a supported API/session contract for a client application to consume ChatGPT-Interfaces login state internally**. Therefore a website-building chat must not assume that including `common.php`, reading ChatGPT-Interfaces session files, or inspecting its private data files is a supported client authentication interface. If an application such as KIP needs its own authenticated editing UI, define and add a proper shared-auth interface to ChatGPT-Interfaces first. Public viewing may remain independent. ## 6. Division of Responsibility ### Client website owns - its public pages and application behavior; - its project-specific content/data; - its project-specific UI; - its own internal data model; - its machine-readable release identity required by its registered deployment contract. ### ChatGPT-Interfaces owns - deployment upload UI; - deployment validation/staging; - preservation of the previous installation; - rollback; - shared operational login; - user/role administration; - client registration/configuration; - common deployment status/results. For deployment uploads, ChatGPT-Interfaces v0.0.5 provides immediate visible phase feedback: **Uploading** while the browser sends the package, **Installing** after upload transfer completes while server-side deployment is running, then the final **Success** or **Failure** result. The active deployment control is disabled to prevent accidental duplicate submission. A percentage progress bar is not part of the interface contract. Server-rendered final results remain available when JavaScript enhancement is unavailable. Do not duplicate these shared functions in each client. ## 7. Website-Building Chat Release Requirements When a chat creates or updates a managed website, it should: 1. Start from the project's authoritative current package/repository, not from remembered snippets. 2. Read this integration specification before changing deployment/authentication integration. 3. Preserve the registered client ID and package-root contract unless a coordinated ChatGPT-Interfaces change is being made. 4. Generate a complete deployable ZIP, not a patch. 5. Update the appropriate project version identity. 6. Clearly state whether the release requires a ChatGPT-Interfaces update. 7. Provide a download link for the generated ZIP. 8. Immediately below the ZIP link, provide the appropriate clickable ChatGPT-Interfaces update/deployment-page link. 9. After successful deployment is confirmed, follow that project's rules for advancing its authoritative Current package. ## 8. Mars Example Mars is registered as client `mars`. - Public website: `https://www.tiltedlogic.org/Mars/` - Operations entry: `https://www.tiltedlogic.org/ChatGPT-Interfaces/?client=mars` - Deployment page: `https://www.tiltedlogic.org/ChatGPT-Interfaces/client.php?client=mars` - ZIP package root: `Mars` - Version file: `catalog.php` - Routine deployment role: Normal User or Administrator A Mars documentation chat should finish a generated release with the package download link followed immediately by a clickable **Update Mars Documents** link. ## 9. New Client Checklist Before producing the first deployable package for a new website, establish: - stable client ID; - display name; - public URL; - target directory under `public_html`; - ZIP top-level package root; - application type and required entry file(s); - machine-readable version/identity format; - public-viewing policy; - required role for routine modifications; - whether the current deployment validator supports the application; - whether the application needs shared authentication inside the client itself. If the last two items require new infrastructure, update ChatGPT-Interfaces first and advance this interface specification as necessary. ## 10. Compatibility Rule Treat this file as an interface contract. Website-building chats may rely on documented behavior here, but should not rely on undocumented ChatGPT-Interfaces internals. When a shared interface changes incompatibly: 1. update this specification; 2. advance its Interface Specification version; 3. advance ChatGPT-Interfaces as appropriate; 4. state which client releases require coordinated changes. This keeps individual website projects decoupled from the implementation details of the shared infrastructure. ## 11. Shared Website Entry Point — v0.3 The stable shared operations entry point is `https://www.tiltedlogic.org/ChatGPT-Interfaces/`. Managed and related websites may link to this page using the label **ChatGPT Interfaces**. The entry page identifies the current access state, provides links to managed public websites, exposes routine update operations to authorized Normal Users and Administrators, exposes Administration to Administrators, and provides a return link to the tiltedlogic.org root site. A public visitor may open the entry page without authentication. Operations that modify managed websites remain protected by the existing role requirements. Adding a navigation link to this shared entry point does not grant additional privileges. ## 12. ChatGPT-Interfaces Self Update — v0.4 The reserved client ID `chatgpt-interfaces` represents the ChatGPT-Interfaces application itself. It is the primary self-client identity and must never use the normal client deployment engine. Before self update is enabled, its configured target directory must resolve to the active `public_html/ChatGPT-Interfaces` installation and its package root must be exactly `ChatGPT-Interfaces`. Path/package-root recognition remains a defensive compatibility check, not the primary identity. Self update is **Administrator-only**. A release ZIP must contain one complete top-level `ChatGPT-Interfaces` directory. The running application validates that the required application files exist and that the packaged `system_version` is newer than the installed version, then stages the validated release in the private `chatgpt-interface-data` directory. The actual replacement is performed by the companion bootstrap installed at `public_html/ChatGPT-Interfaces-Updater`, outside the replaceable application directory. The bootstrap accepts only a short-lived authorization generated by the authenticated staging operation. It preserves the previous ChatGPT-Interfaces installation, installs the staged release, verifies the expected version and required files, and restores the previous installation if installation or verification fails. The updater bootstrap is infrastructure, not a managed client. It is installed once and retained across ordinary ChatGPT-Interfaces self updates. A release that requires a bootstrap change must state that requirement explicitly and provide coordinated bootstrap installation instructions. ## 13. Self Client Identity and Package Layout — v0.5 The stable self-client ID is `chatgpt-interfaces`. The self client is Administrator-only for modification and cannot be deleted through normal client administration. A malformed self-client configuration must fail closed rather than fall through to ordinary document deployment. A ChatGPT-Interfaces release ZIP contains exactly one deployable top-level `ChatGPT-Interfaces` directory. The active application files (`index.php`, `config.php`, `lib/common.php`, and the integration specification) must be directly inside that directory at their normal relative paths. Do not place another release directory or duplicate application tree beneath the package root. ## 14. Reserved Self-Client Administration — v0.6 The reserved `chatgpt-interfaces` client is part of the shared infrastructure and is not removable through ordinary client administration. Administration must not display a **Delete Client** action for this client, and server-side deletion requests for the reserved client must be rejected. Other client records retain their normal deletion controls. ChatGPT-Interfaces v0.0.9 is compatible with ChatGPT-Interfaces-Updater Bootstrap v1 and is intended to validate the browser self-update path introduced in v0.0.7 and corrected in v0.0.8.