Coding-Autopilot-System · OgeonX-Ai · Jul 8, 2026 · Jul 8, 2026
diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md
@@ -0,0 +1,40 @@
+# Architecture
+
+`autopilot-core` implements the intake-governance and operator-scheduling half of the CAS
+autofix loop. It never touches target-repo code directly — it schedules the Codex-driven fix
+generation and lets a pull request carry the change through normal review.
+
+```mermaid
+flowchart LR
+    A[CI Failure in\nopted-in repo] --> B[autopilot-create-issue.yml]
+    B --> C[Issue: autofix + queued]
+    C --> D[autopilot-operator.yml\nself-hosted Windows runner]
+    D --> E[Codex fix generation]
+    E --> F[Pull Request opened\nin target repo]
+    F --> G[Auto-merge / human review]
+    H[autopilot-org-installer.yml\nhourly scan] -.installs intake into.-> B
+```
+
+<!-- codex:generate-image prompt="A control tower overlooking rail yards, each track representing a GitHub repo; the tower issues a green dispatch ticket only after a failure signal arrives, an automated crane installs new track sections labeled autofix + queued; isometric, enterprise blue/graphite palette" style="isometric, enterprise, clean" replaces="mermaid-above" -->
+
+## Components
+
+| Component | Trigger | Purpose |
+|---|---|---|
+| `autopilot-create-issue.yml` | `workflow_run` failure | Creates the intake issue labeled `autofix + queued` |
+| `autopilot-operator.yml` | schedule + `workflow_dispatch` | Scans issues, invokes Codex, opens PRs |
+| `autopilot-org-installer.yml` | hourly + dispatch | Installs the intake workflow into repos that opt in via `.autopilot/opt-in` |
+| `autopilot-docs-daily.yml` | daily | Refreshes the dashboard status page |
+
+## Trust boundaries
+
+- The operator only acts on issues labeled `autofix + queued` and skips `risky` or
+  `needs-design` labels.
+- Diffs are minimal by design — no secrets, no destructive operations — and required
+  verification runs before a PR is opened.
+- The operator requires the `ORG_AUTOPILOT_TOKEN` secret, scoped least-privilege for
+  cross-repo mutation; it runs on a self-hosted Windows runner, not GitHub-hosted compute.
+- This repo does not provision or deploy any cloud infrastructure; it is GitHub Actions
+  orchestration plus a locally-hosted runner.
+
+<!-- docs-verified: cd76345f0837ce2f710ad8bad7bbc9e3de9d5ff0 2026-07-08 -->
diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md
@@ -0,0 +1,20 @@
+# Decisions
+
+This repo tracks two decision trails:
+
+## Phase summaries (`.planning/phases/`)
+
+| Phase | Topic |
+|---|---|
+| [01-enterprise-audit](../../.planning/phases/01-enterprise-audit/) | Enterprise hardening audit — CODEOWNERS, workflow permission tightening, operator timeout coverage, Pester unit-test extension (see commit `cd76345`) |
+
+## Architecture Decision Records (`docs/adr/`)
+
+The [`docs/adr/`](../adr/README.md) directory is the formal ADR home for this repo, governed by
+the rule that any major technical decision or new dependency must be recorded there (Context /
+Decision / Consequences, sequentially numbered). No ADR files have been recorded yet as of this
+writing — the directory currently holds only the governance README describing the convention.
+Future architectural decisions (e.g., changes to the intake/operator contract) should land there
+and be indexed on this page.
+
+<!-- docs-verified: cd76345f0837ce2f710ad8bad7bbc9e3de9d5ff0 2026-07-08 -->
diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md
@@ -0,0 +1,33 @@
+# autopilot-core Wiki
+
+`autopilot-core` is the **control plane** of the Coding-Autopilot-System autonomous CI-repair
+platform. It owns org-wide intake governance, operator scheduling, PR creation, and rollout
+visibility for the autofix loop.
+
+## Role in the CAS portfolio
+
+CAS ships three cooperating repos for CI self-repair:
+
+| Repo | Role |
+|---|---|
+| **autopilot-core** (this repo) | Control plane: org-wide intake governance, operator scheduling, PR creation |
+| [ci-autopilot](https://github.com/Coding-Autopilot-System/ci-autopilot) | Worker/runtime: self-hosted-runner agent that inventories the issue queue |
+| [autopilot-demo](https://github.com/Coding-Autopilot-System/autopilot-demo) | Proof repo: safe target demonstrating the full failure-to-fix loop |
+
+## Quickstart
+
+1. Set the org variable `ORG` in GitHub Actions for this repo.
+2. Configure the least-privilege `ORG_AUTOPILOT_TOKEN` secret for opted-in repository mutations.
+3. Install `autopilot-create-issue.yml` into target repos, or use `autopilot-org-installer.yml`.
+4. Ensure a self-hosted Windows runner with Codex and `OPENAI_API_KEY` is online.
+5. Trigger `autopilot-operator.yml` manually to validate the setup.
+
+Full detail: [README Quick start](../../README.md#quick-start).
+
+## Where to go next
+
+- [Architecture](Architecture.md) — the intake-to-PR flow and its trust boundaries
+- [Operations](Operations.md) — verified run/test/CI commands
+- [Decisions](Decisions.md) — index of recorded architectural decisions
+
+<!-- docs-verified: cd76345f0837ce2f710ad8bad7bbc9e3de9d5ff0 2026-07-08 -->
diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md
@@ -0,0 +1,53 @@
+# Operations
+
+## Run the test suite
+
+```powershell
+pwsh ./tests/run-tests.ps1
+```
+
+This runs workflow YAML validation, control-plane contract tests, and Pester 5 unit tests in
+one command — the same entry point CI uses.
+
+## CI gate (`.github/workflows/ci.yml`)
+
+CI runs on `ubuntu-latest` for every push/PR to `main` and performs, in order:
+
+1. `python tests/validate_workflows.py` — validates workflow YAML.
+2. `./tests/contract-tests.ps1` — validates control-plane contracts.
+3. Pester 5.5.0+ unit tests over `./tests` with `Invoke-Pester` (`Run.Exit = $true`,
+   `Output.Verbosity = 'Detailed'`).
+
+Pester coverage focuses on the safety- and payload-critical logic: `Assert-SafeChangeSet`
+(sensitive-path and diff-budget guards), `Get-ChangedFile` (porcelain parsing), `Search-Issue`
+(GraphQL request construction), and the `Autopilot.Common` helpers (`Get-RepoName`,
+`Invoke-GhJson`, `Get-LogTail`).
+
+There is no branch-coverage percentage gate in this repo's CI as of this writing — the gate is
+pass/fail on the validation, contract, and Pester steps, not a coverage threshold.
+
+## Other CI workflows
+
+| Workflow | Trigger | Purpose |
+|---|---|---|
+| `codeql.yml` | scheduled + push | CodeQL static analysis |
+| `pr-lint.yml` | PR | PR metadata/title linting |
+| `stale.yml` | scheduled | Stale issue/PR sweep |
+| `pages.yml` | push to `main` | Publishes the dashboard to GitHub Pages |
+
+## Manual dispatch
+
+Trigger the operator manually to validate a setup change:
+
+```bash
+gh workflow run autopilot-operator.yml -R Coding-Autopilot-System/autopilot-core
+```
+
+## Runbooks
+
+- [docs/status.md](../status.md) — status snapshot
+- [docs/runbooks/operator.md](../runbooks/operator.md) — operator runbook
+- [docs/runbooks/install-to-repo.md](../runbooks/install-to-repo.md) — repo onboarding runbook
+- [docs/demos/demo-repo.md](../demos/demo-repo.md) — demo walkthrough using `autopilot-demo`
+
+<!-- docs-verified: cd76345f0837ce2f710ad8bad7bbc9e3de9d5ff0 2026-07-08 -->