docs: automate production catalog handoff

Author: rspurgeon

app/_how-tos/konnect-platform/konnect-reference-platform.md

@@ -282,17 +282,23 @@ to the owning service and promote a new artifact.
 
 ## Synchronize production Catalog state
 
-After the production Gateway synchronization succeeds, manually dispatch the service's
-production Catalog workflow from the exact promoted commit. Protect the job
-with a production GitHub Environment and run:
+After the production Gateway synchronization succeeds, have the platform
+workflow read each changed provenance file and dispatch the owning service's
+production Catalog workflow with the exact promoted commit. Use a narrowly
+scoped GitHub App token for the cross-repository dispatch. Keep the service job
+behind its own production GitHub Environment so the Service Team approves the
+Catalog publication using its repository's Konnect identity:
 
 ```sh
 kongctl sync -f konnect/prod.yaml --base-dir . \
   --require-namespace <service>-prod
 ```
 
-This ordering ensures the governed runtime change exists before the service
-publishes its production Catalog state.
+The service workflow verifies that it checked out the requested commit before
+running kongctl. This ordering ensures the governed runtime change exists
+before the service publishes its production Catalog state. Keep manual
+workflow dispatch available as an explicit recovery path, not the normal
+release process.
 
 ## Scope deletion safely
 

app/_landing_pages/konnect-reference-platform.yaml

@@ -147,7 +147,8 @@ rows:
                   Main --> Promote[Open platform promotion PR]
                   Promote --> Review[Platform review]
                   Review --> Gateway[Aggregate production Gateway sync]
-                  Gateway --> Catalog[Approved production Catalog sync]
+                  Gateway --> Dispatch[Dispatch from provenance]
+                  Dispatch --> Catalog[Approved production Catalog sync]
 
   - header:
       type: h2

app/konnect-reference-platform/apiops.md

@@ -155,9 +155,11 @@ Production uses an explicit ownership boundary:
 4. The Platform Team reviews and merges the Gateway change.
 5. The platform workflow synchronizes all four production files in one kongctl
    `_deck` operation against `kongairlines-prod`.
-6. The Service Team manually dispatches its production Catalog synchronization from the
-   exact promoted service commit.
-7. A protected GitHub Environment supplies production approval.
+6. After the Gateway synchronization succeeds, the platform workflow reads
+   the changed provenance and dispatches the owning service's production
+   Catalog workflow with the exact promoted commit.
+7. The Service Team approves its protected GitHub Environment, and the
+   service-owned identity synchronizes the Catalog state.
 
 <!--vale off -->
 {% mermaid %}
@@ -170,6 +172,7 @@ sequenceDiagram
   S->>P: Open promotion PR with provenance
   P->>P: Platform review
   P->>G: Aggregate kongctl sync with _deck
+  P->>S: Dispatch Catalog sync from provenance
   S->>C: Approved kongctl sync from promoted commit
 {% endmermaid %}
 <!--vale on -->

app/konnect-reference-platform/faq.md

@@ -132,8 +132,10 @@ assigns each existing account to its service team. The Platform Team owns the
 shared roles that repository accounts inherit. Issuing each service account
 token and storing it in the repository's development and protected production
 environments are human bootstrap steps. Production promotion uses a separate
-GitHub credential that can open a PR in the platform repository and is never
-exposed to fork jobs.
+GitHub App credential that can open a PR in the platform repository and
+dispatch the owning service's protected production Catalog workflow after the
+Gateway synchronization succeeds. It is never exposed to fork jobs and does
+not receive a service's Konnect token.
 
 ## What if a synchronization fails immediately after an RBAC change?