gsd:docs generate bespoke architecture and diagrams

Author: Aitomates

docs/architecture.md

@@ -0,0 +1,65 @@
+# Architecture
+
+The **Autopilot Core** operates as an asynchronous, event-driven control plane for automatic code repair and AI operations across the organization's repositories. Rather than integrating deeply into every individual codebase, it utilizes a federated intake model mediated by standard GitHub Issues and GitHub Actions.
+
+## High-Level Workflow
+
+At its core, the architecture relies on a series of decoupled GitHub Actions workflows. A failure in an opted-in repository triggers an issue in `autopilot-core`, which acts as a central queue. An operator then processes this queue and proposes fixes.
+
+```mermaid
+sequenceDiagram
+    participant Repo as Opted-in Repository
+    participant Core as autopilot-core
+    participant Codex as AI / Codex
+    
+    rect rgb(30, 30, 30)
+    Note over Repo,Core: 1. Intake & Triaging
+    Repo->>Repo: CI/CD Pipeline Fails
+    Repo->>Core: Workflow Run triggers `autopilot-create-issue.yml`
+    Core-->>Core: Issue created with labels `autofix + queued`
+    end
+
+    rect rgb(30, 45, 60)
+    Note over Core,Codex: 2. Operator Execution
+    loop Every 5 Minutes (Schedule)
+        Core->>Core: `autopilot-operator.yml` scans for `autofix + queued` issues
+        alt Issue has `risky` or `needs-design` label
+            Core-->>Core: Skip execution
+        else Valid Issue
+            Core->>Codex: Prompt with issue details and codebase context
+            Codex-->>Core: Generate minimal patch/fix
+        end
+    end
+    end
+
+    rect rgb(30, 60, 45)
+    Note over Repo,Core: 3. Delivery & Verification
+    Core->>Repo: Commit fix to new branch
+    Core->>Repo: Open Pull Request
+    Repo->>Repo: PR triggers CI/CD validation
+    Repo->>Repo: Auto-merge or await human review
+    end
+```
+
+## System Components
+
+1. **Intake Workflows (`autopilot-create-issue.yml`)**
+   - Installed via `autopilot-org-installer.yml` into target repositories.
+   - Listens for `workflow_run` failure events.
+   - Formats the failure context (logs, failing tests) into a structured GitHub issue payload and dispatches it to the `autopilot-core` queue.
+
+2. **Operator (`autopilot-operator.yml`)**
+   - Runs periodically on a self-hosted environment (e.g., Windows runner).
+   - Polls `autopilot-core` issues.
+   - Provides context to the `ci-autopilot` runtime agent.
+   - Manages communication with the Codex / AI endpoints to generate a patch.
+
+3. **Installer (`autopilot-org-installer.yml`)**
+   - Scans the GitHub organization for repositories containing the `.autopilot/opt-in` marker.
+   - Distributes updates to the intake workflows, ensuring standard reporting capabilities without manual setup per repository.
+
+## Design Philosophy
+
+- **Decoupled State**: The queue lives in GitHub Issues. There is no external database, meaning all state transitions are visible and auditable.
+- **Fail-Safe Processing**: The operator acts with least-privilege tokens (`ORG_AUTOPILOT_TOKEN`), ensuring only opted-in codebases can be mutated.
+- **Human-in-the-Loop Fallback**: Pull Requests generated by the system are just like human PRs. They run standard CI and can require mandatory human review if the repository policy dictates.

docs/index.md

@@ -1,3 +1,25 @@
-# autopilot-core Documentation
+# Autopilot Core Documentation
 
-Welcome to the documentation for autopilot-core.
+Welcome to the **Autopilot Core** documentation. 
+
+`autopilot-core` serves as the centralized control plane for the Coding-Autopilot-System platform. It acts as an organizational AI autopilot, orchestrating autonomous issue intake, bug fixing, and pull request generation for opted-in repositories across the organization.
+
+## Overview
+
+The autopilot platform is composed of three primary parts:
+- **`autopilot-core` (This Repository)**: The control plane. Manages org-wide intake governance, schedules the operator, creates pull requests, and maintains rollout visibility.
+- **`ci-autopilot`**: The runtime pattern. Contains the Python agent and workflow assets executed by runners to perform the actual repairs.
+- **`autopilot-demo`**: A demonstration repository. Provides a safe target for illustrating the end-to-end failure-to-fix loop.
+
+## Key Features
+
+- **Centralized Control Plane**: Operates via explicit GitHub Issues queueing rather than making opaque direct mutations to source code.
+- **Auditable Lifecycle**: Every step—from CI failure to intake issue, operator run, fix branch generation, and PR creation—is transparent and traceable in GitHub.
+- **Guardrailed Execution**: Uses explicit label-gating (e.g., `autofix + queued`), skips risky work, and verifies fixes before creating Pull Requests.
+- **Automated Rollout**: An installer workflow automatically distributes the intake automation to any repository in the organization that opts in.
+
+## Getting Started
+
+To learn more about the technical details, read the [Architecture Guide](architecture.md).
+
+If you are looking to set up or configure the operator, please refer to the [Operator Runbook](runbooks/operator.md) and the [Repo Onboarding Runbook](runbooks/install-to-repo.md).