Feature/gemini integration

[SimonBlancoE]

This is my attempt at integrating the PAI system into Gemini code while preserving the existing installations. Claude and Gemini should be able to coexist in the same system as well.

It looked like a quick fix at first...

Summary

Implements first-class support for the Google Gemini CLI while refactoring the system into a "Safe Distro" model. This elevates PAI into an independent infrastructure layer (~/.config/pai) capable of serving multiple AI clients (Claude Code, Gemini) simultaneously, ensuring shared memory, identity, and skills across all tools.

• New: gemini-pai adapter for full PAI context injection and hook simulation.
• Refactor: install.ts standardized to XDG paths (~/.config/pai) with multi-tool integration.
• Safety: Automated shell profile backups and self-aware path resolution.
• Quality: Comprehensive automated test suite for installation and configuration logic.

Motivation

Previously, PAI was tightly coupled to the ~/.claude directory structure. To integrate Google Gemini support, we faced a choice: hack it in as a sidecar, or elevate PAI to a proper infrastructure layer.

We chose the latter. This PR decouples the "Brain" (PAI) from the "Interface" (Claude/Gemini). By standardizing on PAI_DIR, we allow the user to switch tools seamlessly while maintaining a single source of truth for their AI's personality and memory.

What's Changed

Core Infrastructure

File	Change
Tools/gemini-pai.ts	NEW Intelligent wrapper that injects PAI context into Gemini. Supports both interactive sessions and one-shot piping.
Bundles/Kai/install.ts	REFACTOR Now defaults to ~/.config/pai. Implements installSymlinks with proactive backup logic (.old) to safely integrate with Claude Code. Decoupled IO for testability.
Packs/kai-hook-system/src/initialize-session.ts	UPDATE Added detection for PAI_SOURCE_APP to correctly identify the calling tool (Claude vs Gemini) for observability logs.

Documentation & Standards

File	Change
Packs/kai-core-install/src/skills/CORE/SKILL.md	UPDATE Updated "Operating Environment" section to reflect support for "Claude Code / Gemini CLI".
Packs/kai-prompting-skill/src/skills/Prompting/Standards.md	UPDATE Added specific prompting standards for Gemini models (handling context windows, specific formatting quirks).
Bundles/Kai/README.md	UPDATE Revised installation instructions to cover the new ~/.config/pai default and Gemini setup.
Tools/VERIFY.md	NEW Added verification steps for validating the Gemini integration and cross-tool symlinking.

Testing

File	Change
tests/install-config.test.ts	NEW Test suite verifying installation flows, configuration preservation during updates, and path customization.
tests/gemini-pai.test.ts	NEW Unit tests for the adapter's context injection and argument parsing logic.
tests/install-logic.test.ts	NEW Tests for environment variable parsing and helper utilities.

Key Improvements

1. The "Safe Distro" Pattern

Instead of hijacking the gemini binary, we introduce gemini-pai. This adapter is self-aware: it locates the PAI installation relative to itself or via explicit aliases generated by the installer. This eliminates environment dependency bugs and allows for isolated testing.

2. Multi-Tool Architecture (Smart Symlinks)

The installer now treats PAI as the host and tools as clients:

• Centralization: Everything lives in ~/.config/pai (XDG standard).
• Legacy Compatibility: If an existing ~/.claude directory is detected, the installer safely backs up its internal folders (skills, hooks, etc.) to .old and replaces them with symlinks to PAI.
• Result: Claude Code and Gemini now physically share the same memory and skills. Updates made in one tool are immediately available in the other.

3. Gemini Context Injection Strategy

Since Gemini CLI lacks a native "system prompt" config file, we implemented a lightweight but robust injection strategy:

• Mechanism: The gemini-pai wrapper prepends the PAI SYSTEM INITIALIZATION block directly to the user's prompt.
• Intelligence: It automatically distinguishes between modes. If you run gemini-pai "hello", it responds and exits (respecting pipes). If you run gemini-pai alone, it launches a full interactive session with the infrastructure loaded.

4. Refactoring: console.log → InstallerIO

While the core goal was Gemini integration, we refactored the installation logic to use an InstallerIO interface. This was necessary to:

• Enable Testing: We cannot verify the installer's behavior (especially safety checks) if it prints directly to stdout. The io abstraction allows tests to capture and validate output without running a real terminal.
• Prevent Regressions: As the installer grows to support multiple platforms (Claude, Gemini), manual testing becomes risky. This change allows for automated test coverage of the installation flow.
• Standardize UX: Ensures consistent prompts and formatting across all interaction points, crucial for a "Safe Distro" experience.

Aligns with PAI Principles

This PR implements the "Safe Distro" model for Gemini integration, strictly adhering to the following PAI principles:

• Principle 3: Scaffolding > Model The Tools/gemini-pai.ts wrapper acts as intelligent scaffolding. It ensures that the AI always receives the correct system context, identity (CLIO), and available skill index before a session begins, making the model's performance more reliable through architectural support.

• Principle 5: Code Before Prompts Logic for environment detection, .env loading, and dynamic context assembly is handled deterministically in TypeScript. This prevents "hallucinated context" by providing hard-coded truth to the model via the wrapper.

• Principle 6: Spec / Test / Evals First This feature includes a comprehensive test suite (tests/gemini-pai.test.ts, tests/install-logic.test.ts) that verifies context injection and environment loading, ensuring the integration works as specified before it hits production.

• Principle 7: UNIX Philosophy (Modular Tooling) The gemini-pai adapter is a composable tool that follows the "do one thing well" rule—it manages the PAI-to-Gemini bridge while respecting standard streams and existing CLI flags.

• Principle 8: ENG / SRE Principles By adopting the "Safe Distro" approach (wrapper scripts instead of alias hijacking), we ensure the system is robust, easy to debug, and simple to roll back without corrupting the underlying shell environment.

• Principle 9: CLI as Interface The integration reinforces the CLI-first nature of PAI, providing a seamless way to invoke advanced AI capabilities directly from the terminal with full access to local scripts and tools.

Testing Status

Exhaustively verified on Linux (Ubuntu) and via sandbox environments:

• ✅ Automated Tests: 11/11 tests passing (bun test), covering environment parsing, path logic, and configuration preservation.
• ✅ Fresh Install: Correctly creates the structure in ~/.config/pai.
• ✅ Update Mode: Detects previous configurations and migrates them without data loss.
• ✅ Claude Integration: Verified that existing ~/.claude folders are correctly converted to symlinks, forcing Claude to adopt the PAI identity.