docs: document GitHub App runner pool setup

README.md

@@ -222,7 +222,41 @@ See [examples/runner-pool-expiration](examples/runner-pool-expiration/README.md)
 When using `ImpVMRunnerPool` with GitHub Actions, GitHub does not read pool objects directly.
 It only sees registered self-hosted runner instances.
 
-Read: [github-capacity-signaling.md](https://github.com/syscode-labs/syscode-ai-internal-plans/blob/main/projects/imp/docs/runner-pool/github-capacity-signaling.md)
+For GitHub App authentication, configure the runner pool with the App credentials
+Secret, the organization or repository scope, and the GitHub runner group. The
+operator mints a one-use registration configuration for each VM and hands it to
+the guest runner without putting it in the VM spec, root filesystem, or logs.
+
+```yaml
+apiVersion: imp.dev/v1alpha1
+kind: ImpVMRunnerPool
+metadata:
+  name: ci-runner-pool
+  namespace: default
+spec:
+  templateName: ci-runner-template
+  labels: [imp]
+  platform:
+    type: github-actions
+    scope:
+      org: your-org
+    runnerGroup: omni-runner
+    credentialsSecret: github-imp-runners
+    tokenSource: github_app
+  scaling:
+    mode: polling
+    minIdle: 1
+    maxConcurrent: 1
+    scaleUpStep: 1
+    cooldownSeconds: 30
+    polling:
+      enabled: true
+      intervalSeconds: 30
+```
+
+The referenced Secret contains `github-app-id`, `github-app-installation-id`,
+and `github-app-private-key`. Use an external Secret provider in production;
+never commit these values.
 
 ## Runner Scaling Mode (GitHub-First)
 
@@ -368,21 +402,14 @@ Imp exposes operator and agent metrics so you can monitor VM lifecycle and platf
 ## Reconcile Sequence
 
 ```mermaid
-sequenceDiagram
-  participant U as User
-  participant APIS as K8s API
-  participant OP as Imp Operator
-  participant AG as Imp Agent (Node)
-  participant FC as Firecracker
-
-  U->>APIS: Create ImpVM + ImpNetwork
-  APIS->>OP: Watch event
-  OP->>OP: Resolve class/template + schedule node
-  OP->>AG: Desired VM runtime spec
-  AG->>FC: Create machine + start microVM
-  FC-->>AG: Runtime state, PID, network info
-  AG-->>APIS: Status updates
-  OP-->>APIS: Conditions / phase transitions
+flowchart LR
+  U[User] --> API[Kubernetes API]
+  API --> OP[Imp Operator]
+  OP --> AG[Imp Agent on selected node]
+  AG --> FC[Firecracker microVM]
+  FC --> AG
+  AG --> STATUS[ImpVM status]
+  OP --> STATUS
 ```
 
 ## Troubleshooting

examples/github-scaling-explicit/README.md

@@ -31,9 +31,15 @@ GitHub (`platform.type=github-actions`) is supported for this explicit scaling m
 
 ## Prerequisites
 
-- Secret `default/gh-runner-token` exists
+- Secret `default/github-imp-runners` exists with the GitHub App fields
+  `github-app-id`, `github-app-installation-id`, and `github-app-private-key`
 - Secret `default/gh-webhook-secret` exists
-- set `platform.scope.repo` to your repository
+- set `platform.scope.org` to your organization; a named GitHub runner group
+  requires organization scope
+
+Do not put a JIT registration value in the manifest or the base image. Imp mints
+one registration configuration per runner VM and passes it to the guest only at
+launch time.
 
 ## Apply
 

examples/github-scaling-explicit/impvmrunnerpool.yaml

@@ -10,8 +10,12 @@ spec:
   platform:
     type: github-actions
     scope:
-      repo: your-org/your-repo
-    credentialsSecret: gh-runner-token
+      org: your-org
+    runnerGroup: omni-runner
+    credentialsSecret: github-imp-runners
+    tokenSource: github_app
+  labels:
+    - imp
   scaling:
     mode: webhook
     minIdle: 0