v0.1.46 development documentation: Procedures are reviewed against packaged source; live production operation and updater migration remain unverified. Do not treat this draft as deployment approval.

KIP Interfaces — Administrator Guide v0.1.46

Purpose and access

This guide is for authorized administrators configuring managed websites, GitHub access and application updates. Administrative pages require appropriate sign-in. Do not use production credentials or clients for destructive tests.

Understand the four GitHub configuration objects

A client identifies the website or AI consumer that will request access. A named credential is the authentication identity KIP Interfaces uses when contacting GitHub. A repository enrollment associates a repository with that credential. A client assignment grants a registered client specific operations against the enrolled repository. None of these objects substitutes for another.

Set up a client and its GitHub access

1. Register the client. Open Administration → Clients. Inspect or create the client, then configure its website root, repository, branch and optional source directory. Save and confirm the displayed client identity.
2. Create or select a named credential. Open GitHub Operations → Named Credentials. A credential is required because GitHub must authenticate the request made on the client's behalf. Use a GitHub credential authorized for the intended repositories, choose the supported development role for API reads, and save it through the credential form. The precise supported credential input fields and creation mechanism should be confirmed on the installed form before entering a production secret. Never paste credentials into documentation, logs or release ZIPs.
3. Enroll the repository. Open GitHub Operations → Repositories. Select the intended owner/repository, use Configure, associate it with the named credential, and save. Enrollment establishes which repository the credential may serve through the application; it is not a client permission by itself.
4. Grant client access. Open GitHub Operations → Client Assignments. Select the registered client, choose the named credential and grant the minimum necessary operations (typically Read for API access and GitHub Verify). Save and inspect the assignment.
5. Verify. Return to Administration → Clients, choose the client and run GitHub Verify. Review authorization and synchronization separately. An Authorized result proves repository access, not that deployed files match GitHub.

Create and maintain API tokens

The read-only AI API uses a separate client bearer token; it does not expose the underlying GitHub credential to the API caller. After the client's Read assignment exists, open the administrator AI API Tokens page, select the registered client and issue a labeled token. Copy the token to the client's secret store at issuance; do not put it in a URL or source control. To retire or rotate access, revoke the old token and issue a new one, then update the consuming client. See API Reference for a first-request walkthrough.

Routine maintenance

• Review client assignments when clients are renamed or deleted; confirm repository and branch settings before diagnosing synchronization.
• Recheck repository enrollment and development-role credential if GitHub Verify reports denied access.
• Rotate compromised or retired tokens through token management and replace corresponding client secrets.
• Treat Not synchronized as a source/deployment identity issue, not proof that authentication failed.

Application updates and previous-version recovery

Self Update changes KIP Interfaces. Managed website deployment changes a client site. The external updater is a separate installation and is not upgraded simply because updater files appear in an application ZIP. Before update, confirm current installed version, verified previous release, external persistent-data backup and independently working recovery path. See Installation and Updater Guide.

For previous-version recovery, verify the live external updater supports it, then use Administration → Previous Version Recovery if present. Review retained installations, choose the intended version and confirm. Check the audit result and application health afterward. Live availability and end-to-end safety are not verified by this documentation release. Restoring an arbitrary archived ZIP is not established.

Troubleshooting

• No repository access: Confirm Named Credentials, repository enrollment, client assignment and Read permission separately.
• API 401: Check the bearer token and whether it has been revoked.
• API 403: Check the client's assigned development credential, repository enrollment and Read permission.
• Not synchronized: Inspect deployed-file identity, branch and source directory.
• Update failed: Preserve the exact ZIP and error message; do not overwrite the same release version with changed bytes.

Related guides

User Guide · AI API Reference · System Specification · Release Specification

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.