docs: restructure documentation for AI agent optimization (#612)

* docs: restructure documentation for AI agent optimization

- Organized documentation into guidance, requirements, specifications, and development directories
- Separated corporate steering from project-level technical architecture
- Moved high-level goals into a new PRD (launchpad-prd.md)
- Updated README.md to reflect the new structure
- Removed obsolete top-level docs/*.md files

Signed-off-by: James Nesbitt <jnesbitt@mirantis.com>

Author: james-nesbitt

AI_AGENTS.md

@@ -0,0 +1,51 @@
+# AI Agent Guidelines for Mirantis Launchpad
+
+This document defines guidelines for AI agents working on the Launchpad project. These instructions take precedence over general tool defaults.
+
+---
+
+## Core Principles
+
+1. **Generalization**: Support all AI agents, not just specific providers.
+2. **Consistency**: Follow Launchpad’s architectural patterns and conventions.
+3. **Clarity**: Document decisions and reasoning for human reviewers.
+
+---
+
+## Documentation Structure
+
+Documentation is organized to minimize context overhead for agents:
+- `docs/guidance/`: Foundational principles and project vision.
+- `docs/requirements/`: High-level product requirements (PRDs).
+- `docs/specifications/`: Technical specifications, architecture, and design.
+- `docs/development/`: Development workflows, building, and testing.
+- `docs/usage/`: User-facing documentation.
+
+---
+
+## Agent Workflow
+
+### 1. Research Phase
+- Read `docs/guidance/project.md` to understand core architectural principles.
+- For feature requests, review the relevant PRD in `docs/requirements/`.
+- For bug fixes, review the relevant specification in `docs/specifications/`.
+
+### 2. Strategy Phase
+- Propose changes that align with the **Phase Manager** architecture (`docs/specifications/architecture.md`).
+- Ensure changes are backwards compatible or include migrations (`docs/specifications/architecture.md`).
+- Document trade-offs and decisions in the PR description.
+
+### 3. Execution Phase
+- All commits MUST be signed.
+- Follow the testing strategy outlined in `docs/development/workflow.md`.
+- Use `make local` for rapid iteration and validation.
+
+---
+
+## Technical Constraints
+
+- **Language**: Go (Golang).
+- **Core Library**: [k0sproject Rig](https://github.com/k0sproject/rig) for host management.
+- **Build System**: Goreleaser (invoked via `Makefile`).
+- **Telemetry**: Maintain existing telemetry patterns for installation, upgrades, and errors.
+- **State**: Launchpad is stateless between runs; use phases for discovery.

README.md

@@ -1,21 +1,30 @@
 # Mirantis Launchpad CLI Tool
 
-The Mirantis custom binary cli tool to assist installing, upgrading and resetting MKE3 & MCR clusters on provisioned compute node resources. Launchpad provides advantages over manually installing MCR and MKE3 in it automates the process without limiting how the underlying cluster is provisioned or managed. The tool is a golang cli written leveraging the k0sproject rig library for managing compute nodes/machines.
+The Mirantis Launchpad CLI tool automates the installation, upgrading, and resetting of MKE (Mirantis Kubernetes Engine) and MCR (Mirantis Container Runtime) clusters on provisioned compute node resources.
 
-Launchpad is an open source tool, steered by Mirantis.
+## Documentation Index
 
-Launchpad was open sourced in early 2025, during which time development moved from an internal process to a GitHub based bublic process. Older pull requests include internal ticket numbers for reference.
+Documentation is organized to provide clear, context-efficient guidance for both users and AI agents:
 
-## Development 
+- **[AI Agent Mandates](GEMINI.md)**: Foundational instructions for AI agents working in this repository.
+- **[Requirements (PRDs)](docs/requirements/launchpad-prd.md)**: High-level objectives and product requirements.
+- **[Corporate Guidance](docs/guidance/corporate.md)**: Steering and contribution principles from Mirantis.
+- **[Project Guidance](docs/guidance/project.md)**: Core architectural principles and technical frameworks.
+- **[Technical Specification](docs/specifications/architecture.md)**: Details on the Phase Manager and internal components.
+- **[Development Workflow](docs/development/workflow.md)**: Building, testing, and contribution rules.
+- **[User Guide](docs/usage/getting-started.md)**: Installation, provisioning, and running instructions.
 
-Issues are reported as Github issues. Feature requests can also be submitted as Issues.
+## Quick Start
 
-Pull requests are accepted, but it is requested that contributors first read through the [developer's guide](docs/developer.md)
+1.  **Download**: Get the latest binary from [GitHub Releases](https://github.com/Mirantis/launchpad/releases).
+2.  **Provision**: Set up your compute nodes (optionally using [Mirantis Terraform helpers](docs/usage/getting-started.md#terraform-helpers)).
+3.  **Configure**: Create a `launchpad.yaml`.
+4.  **Execute**: Run `launchpad apply`.
 
-Steering is heavily guided by Mirantis, mainly in order to avoid breaking changes, and to avoid adding complexity that serves only rare use-cases.
+For detailed usage, refer to the [public documentation](https://docs.mirantis.com/mke/3.8/launchpad.html).
 
-## Usage 
+## Contributing
 
-Launchpad is installed pulling directly from the Launchpad GitHub releases. Before executing, clusters need to be provisioned and a configuration file needs to be provided.
+We welcome contributions! Please read our [Contribution Rules](docs/guidance/corporate.md#contribution-rules-signed-commits-required) and [Development Workflow](docs/development/workflow.md) before submitting a pull request.
 
-Users can get oriented using the [usage guide](docs/usage.md) but should read the [public documentation](https://docs.mirantis.com/mke/3.8/launchpad.html) for real usage.
+**All commits MUST be signed.**

docs/README.md

@@ -0,0 +1,40 @@
+# Development Workflow: Mirantis Launchpad
+
+This guide covers building, testing, and contributing to the Launchpad codebase.
+
+## Building Locally
+
+Launchpad uses `goreleaser` for production builds, but provides a `Makefile` for local development.
+
+- **`make local`**: Builds a single, platform-specific binary for rapid testing.
+- **`make build-release`**: Performs a full production build, requiring a clean repository and release tag.
+- **`make sign-release`**: Signs the Windows binary (requires specific environment variables).
+
+## Testing Strategy
+
+Launchpad's system-centric nature requires a layered testing approach:
+
+### 1. Unit and Functional Tests (`pkg/`, `test/functional/`)
+- **Unit**: Small tests for individual functions or components.
+- **Functional**: Tests that verify specific functional components.
+- **Run**: `go test ./pkg/...` and `go test ./test/functional/...`.
+
+### 2. Integration Tests (`test/integration/`)
+- **Focus**: Verifies functional elements on actual clusters provisioned by the test suite.
+- **Run**: `go test ./test/integration/...`.
+
+### 3. Smoke Tests (`test/smoke/`)
+- **Focus**: End-to-end command testing (`apply`, `reset`, etc.) using a real compute cluster.
+- **Smoke Small**: Provision a small number of machines.
+- **Smoke Large**: Provision a large and varied cluster.
+- **Run**: `go test ./test/smoke/...`.
+
+## Contributing Principles
+
+- **Signed Commits**: All commits must be signed using `git commit -s`.
+- **Feature Options**: Make new features optional via configuration or command flags.
+- **Phase Integration**: Implement new functionality as phases whenever possible for reusability.
+- **Schema Safety**: Avoid changes to the configuration syntax. If a change is necessary:
+  - Bump the version.
+  - Include an in-memory migration in `pkg/config/migration/`.
+- **Linting**: Ensure all changes pass `golangci-lint`.

docs/design.md

@@ -0,0 +1,19 @@
+# Mirantis Corporate Guidance for Launchpad
+
+Launchpad is an open-source tool steered by Mirantis to provide a seamless installation experience for MKE and MCR clusters.
+
+## Steering Principles
+
+- **Avoid Breaking Changes**: Backward compatibility is a primary concern. Any changes to the configuration schema must include a migration strategy.
+- **Maintain Focus**: Avoid adding complexity that serves only niche or rare use-cases.
+- **Consistency**: The tool must align with Mirantis product standards and existing ecosystem tools like `testkit`.
+
+## Contribution Rules (Signed Commits Required)
+
+- **Issues**: All changes should have a corresponding GitHub issue for high-level discussion before implementation.
+- **Pull Requests**:
+  - Maintain a 1-to-1 relationship between PRs and issues whenever possible.
+  - Commits MUST be signed (use `git commit -s`).
+  - PRs must be rebased off of the `main` branch.
+  - Changes must pass all `golangci-lint` checks.
+- **Contact**: Ping `@james-nesbitt` on GitHub for feedback if it is not received in a timely manner.

docs/developer.md

@@ -0,0 +1,18 @@
+# Launchpad Project Guidance
+
+Launchpad is a Go-based CLI tool designed for installing, upgrading, and resetting MKE and MCR clusters.
+
+## Core Architectural Principles
+
+- **Infrastructure Agnostic**: The tool must work on any infrastructure (on-prem, public cloud, private cloud, hybrid, bare-metal).
+- **No Mandatory External Dependencies**: Do not require pre-installed tools on cluster machines.
+- **Built-in Telemetry**: Always include telemetry for installation and upgrade phases, including error reporting.
+- **Diagnostic-Focused**: Provide meaningful output for diagnostics (e.g., `error.log`, `install.log`).
+- **Statelessness**: Launchpad does not maintain persistent state between runs. Use discovery phases to determine cluster state at runtime.
+
+## Technical Framework
+
+- **Go (Golang)**: The primary language for the CLI and its core components.
+- **k0sproject Rig**: Used for managing compute nodes/machines over SSH or WinRM.
+- **Phase Manager**: All operations (install, upgrade, reset) are organized into reusable **Phases** that can be conditionally executed.
+- **Configuration Migrations**: Maintain backward compatibility by providing in-memory migrations for older configuration formats.