# KIP Interfaces — System Specification v0.1.46

**Scope:** Source-reviewed v0.1.46 development architecture; inherited claims below require test evidence before release acceptance. The external updater is independently installed and remains incompatible with the current staging gate if its installed version is v0.1.22.

## System purpose and boundaries
KIP Interfaces is a PHP website management application for registering managed client sites, administering GitHub access, comparing source state, managing release installation, and exposing a constrained read-only AI API. The application and its external updater are separate deployable directories. GitHub authorization does not prove deployed files match a repository.

## Component and source map

| Component | Source | Responsibility |
|---|---|---|
| Website and documentation index | `index.php`, `assets/tabs.js`, `assets/app.css` | Home navigation and document links |
| Client administration | `admin.php`, `client.php` | Client registration, roots, permissions and verification |
| GitHub operations | `github.php`, `lib/github.php`, `github-client-options.php` | Credential and repository workflows; GitHub calls |
| Read-only AI API | `ai-api.php`, `lib/ai-api.php`, `ai-api-tokens.php` | Bearer-token authorization and GET operations |
| Site management | `site.php`, `source.php` | Managed-site operations and source inspection |
| Application update | `self-update.php`, `system-update.php` | Application update preparation and handoff |
| Independent updater | `KIP-Interfaces-Updater/install.php`, `lib/updater.php`, `lib/rollback.php`, `recover.php` | External installation, rollback and recovery code |
| Shared utilities | `config.php`, `lib/common.php` | Application settings and common helpers |
| Documentation pipeline | `tools/build-documentation.py`, `tools/audit-documentation.py`, `tools/validate-release.py` | Document rendering, structural audit, package validation |

## Deployment layout
A release ZIP includes `KIP-Interfaces/` and a complete sibling `KIP-Interfaces-Updater/`; a copy of the updater is also bundled under the application tree. The external updater is installed independently; its presence in a release ZIP does not demonstrate that it is installed on the server. The application maintains version and release checksums in `config.php` and `release-manifest.json`.

## Identity, credentials and authorization
Client identities, GitHub named credentials, repository enrollment and client assignments are separate objects. A read-only AI token is issued for a registered client only after the client has a Read assignment. API tokens are presented in the `Authorization: Bearer` header, not URL query strings. API tokens are stored by SHA-256 hash in `ai-api-tokens.json` under the application's external data directory. The exact live directory configuration must be verified on the server.

The API checks the assigned credential, its development role, enrolled repository and Read permission before accessing GitHub. The API does not provide write or commit endpoints. See [AI API Reference](AI-API-Reference.html).

## Read-only AI API data flow
1. Client sends an HTTPS GET to `ai-api.php` with a bearer token.
2. The entry point validates HTTP method and token, then selects the operation.
3. Repository-scoped operations validate client assignment and repository enrollment.
4. The GitHub library calls GitHub and the entry point returns JSON or a structured error.
5. For file reads, the requested ref is resolved to a specific commit SHA before retrieving content. File size is limited to 1 MiB.

## State and persistence
Runtime client, credential, token, and assignment state is external to the release archive and must not be replaced by a code deployment. The exact directory inventory, record schemas, and backup guarantees are **not fully verified** in this specification; inspect `lib/common.php`, `lib/github.php` and deployed configuration before migration or recovery.

## Update, rollback and recovery
Application self-update and independent updater installation are different operations. Source contains recovery code and a previous-version recovery workflow; availability and safety on the live server remain **NOT VERIFIED**. Retained previous installations, separately backed-up persistent data, and a validated recovery path are prerequisites for administrator-initiated rollback. No archive-ZIP restore capability is claimed. See [Installation and Updater Guide](Installation-Updater-Guide.html).

## Security and failure boundaries
Authenticated administrators manage sensitive credentials and release operations. Read-only AI clients receive only the repository access assigned to them. The API responds with JSON and uses 400, 401, 403, 405 and 502 error categories. Failure of a GitHub call is not a successful read. Credentials and tokens must not be logged or committed to source control.

## Implementation status and limitations
- **Source-backed:** PHP components and read-only API routes listed above exist in the supplied v0.1.46 working package.
- **Not verified:** live server parity, external updater compatibility, live GitHub access, rollback behavior, backup retention and acceptance.
- **Planned:** GitHub write API and automated unit-test framework beginning Phase 4; neither is asserted to be implemented.

## Related documents
[Functional Specification](Functional-Specification.html) · [API Reference](AI-API-Reference.html) · [Release Specification](Release-Specification.html) · [Test Report](Release-Test-Report-v0.1.46.html) · [Release Notes](Release-Notes-v0.1.46.html)

## Historical release notes and development appendices

Earlier checkpoint descriptions are retained in the versioned `Release-Notes-v0.1.41.md` through `Release-Notes-v0.1.44.md` and historical continuity records. They do not describe current v0.1.46 behavior.