Compatibility and release-status addendum — v0.1.31

The API/interface contract below is historical and has not undergone complete endpoint-by-endpoint regression verification for v0.1.31. Do not treat older compatibility/version claims as current certification. Current release specification: docs/Release-Specification.md. GitHub client access is distinct from deployed-site synchronization. Any integration changes must be tested and recorded before claiming API compatibility.

KIP-Interfaces Integration Specification

Interface Specification: v0.6
Compatible KIP-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 KIP-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 KIP-Interfaces administration belong in public_html/KIP-Interfaces.

1. Shared Infrastructure

The shared installation is:

• Web path: /KIP-Interfaces/
• Physical directory: public_html/KIP-Interfaces
• Client operations page: /KIP-Interfaces/?client=<client-id> or the client card reached from the KIP-Interfaces home page
• Client deployment page: /KIP-Interfaces/client.php?client=<client-id>
• Administration: /KIP-Interfaces/admin.php

Do not copy KIP-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 KIP-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:

Mars-Documentation-v1.3.zip
└── Mars/
    ├── index.php
    ├── catalog.php
    └── ...complete website...

The package must be a complete deployable website, not a patch. KIP-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 KIP-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:

'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

KIP-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 KIP-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

KIP-Interfaces v0.0.4 provides shared authentication for KIP-Interfaces operations. It does not yet define a supported API/session contract for a client application to consume KIP-Interfaces login state internally.

Therefore a website-building chat must not assume that including common.php, reading KIP-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 KIP-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.

KIP-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, KIP-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 KIP-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 KIP-Interfaces update.
7. Provide a download link for the generated ZIP.
8. Immediately below the ZIP link, provide the appropriate clickable KIP-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/KIP-Interfaces/?client=mars
• Deployment page: https://www.tiltedlogic.org/KIP-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 KIP-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 KIP-Interfaces internals.

When a shared interface changes incompatibly:

1. update this specification;
2. advance its Interface Specification version;
3. advance KIP-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/KIP-Interfaces/.

Managed and related websites may link to this page using the label KIP 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. KIP-Interfaces Self Update — v0.4

The reserved client ID kip-interfaces represents the KIP-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/KIP-Interfaces installation and its package root must be exactly KIP-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 KIP-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/KIP-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 KIP-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 KIP-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 kip-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 KIP-Interfaces release ZIP contains exactly one deployable top-level KIP-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 kip-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.

KIP-Interfaces v0.0.9 is compatible with KIP-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.