Read this overview, then Appendix A — Scope Contract & Endpoint Reconciliation, Appendix B — Agent Work Packages & Acceptance Tests, and Appendix C — Migration, Rollout & Rollback Runbook.
Execution entry point: Appendix B, T00. It contains 15 dependency-ordered work packages (T00–T14) and a copy-ready agent brief. Appendix A defines the nine proposed scopes and sheet corrections; Appendix C defines the safe migration algorithm, rollout gates and rollback floor. All implementation work is currently planned, not executed.
Branching is mandatory: follow the verified repository matrix in section 6A. Application work starts from the testing-stage branch and progresses through staging → pre-live → production; SDK/docs work starts from main. Use exact repository-specific spellings and the documented exceptions, not a universal prelive or main assumption.
<aside> 🧭
Agent handoff · 9 September 2026 · Proposed implementation design, not a deployed change. This plan preserves existing clients while introducing granular scopes for new clients. Read this page and all three implementation appendices before changing code. Policy choices marked D1–D6 require recorded approval before production activation; safe discovery, tests, and feature-flagged implementation can proceed first.
</aside>
Owner confirmation received on 9 September 2026: quran/qf-form-handler was retired when the Developer Console was introduced. Treat it as historical reference only, not an active provisioning service or an implementation/release dependency. Its source files, branches and old deployment workflow do not establish current operational use. This corrects the earlier inference from repository contents.
Do not create a Form Handler PR, update its scopes/templates/workflows, deploy or reactivate it, or establish new environment branches for it as part of this work. New developer provisioning follows the Developer Console → Platform API path; relevant Admin Dashboard operations remain in scope. Existing clients originally created by the retired service remain eligible for the normal migration based on their actual current rights and lifecycle state, including clients not yet linked in Platform.
The requested outcome is an additive, backward-compatible migration: newly issued OAuth clients receive the approved granular scopes instead of the legacy content umbrella; existing eligible clients retain their original scopes and gain only equivalent successor permissions. Update every active provisioning path, authorization layer, SDK token-request path, and documentation source together.
The initiating evidence is the user's quoted request plus Osama Raafat's 7 September 2026 spreadsheet-sharing email, located through Gmail. The retrieved email links the sheet; it does not itself contain the full quoted implementation request. Sources: Gmail sharing message and QF_API_Endpoints.
The sheet was read across A1:L209 in tab QF_API_Endpoints.csv. It has 208 data rows: 95 Content, 106 User, 6 OAuth2, and 1 Search. Column A is actually API Family, not a literal OAuth scope. Column F contains proposed human-readable labels. Columns G/I/J/K/L supply auth type, consent category, API path, operation ID, and environment. Those distinctions must survive normalization.
The initial source-code review inspected selected authorization, provisioning, schema, SDK, route, and documentation files across ten repositories, plus related release guidance and open promotion PR metadata. Following the owner's retirement correction, nine repositories remain in the core implementation impact assessment; qf-form-handler is historical reference only. Optional starter/template follow-through remains conditional on T12. It is not a runtime security audit, a complete review of every repository file, a production client inventory, or an execution of tests. Inspected default-branch commits are recorded below; none proves what is deployed.
Use a versioned scope contract, not distributed string replacements. Keep gateway authorization, client provisioning, migration expansion, SDK selection, and documentation generated or validated against the same approved contract version. Proposed canonical home: qf-api-docs/contracts/content-scopes/v1.json, with a schema, immutable source snapshot, approval record, and checksum. Consumers vendor or generate pinned copies at build time; do not fetch a live spreadsheet or another repository's mutable main branch during API requests.
The Platform API should own managed-client grant state and migration orchestration. Hydra remains the token issuer and client configuration authority for token issuance. The gateway enforces actual token scopes. Users Backend owns consent handling and the QuranReflect downstream behavior. New developer provisioning follows Developer Console → Platform API. Relevant Admin Dashboard Hydra-management operations remain in scope and must preserve the same grant policy. Form Handler was retired when the Developer Console was introduced, per owner confirmation; it is not an active writer or a rollout dependency.
flowchart TD
Contract["Approved versioned scope contract"] --> Writers["Developer Console via Platform + Admin provisioning policies"]
Writers --> Grants["Durable grant state and migration ledger"]
Grants --> Hydra["Hydra client allowed scopes"]
Client["Confidential application / SDK"] -->|"Explicit requested scopes"| Hydra
Hydra -->|"Access token with granted scopes"| Client
Client --> Gateway["Gateway: route policy + token checks + stable quota policy"]
Contract --> Gateway
Gateway --> Origin["Content API / public QuranReflect routes"]
Contract --> SDK["Pinned SDK operation metadata and docs"]
SDK --> Client
Separate three concepts everywhere: client-allowed scopes, scopes granted in a particular token, and scopes required by an endpoint. Expanding the first must not silently rewrite the second. Preserve existing token validation and user-consent boundaries.