Clarify SDK and client responsibilities, configure release workflow

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# The primary maintainer must review all contributions from other identities.
+* @atldays

.github/workflows/release.yml

@@ -1,25 +1,35 @@
 name: Release
 
 on:
-    push:
-        branches:
-            - main
+    workflow_dispatch:
 
 concurrency:
     group: release-main
     cancel-in-progress: false
 
 permissions:
-    contents: write
+    contents: read
     id-token: write
 
 jobs:
     release:
         runs-on: ubuntu-latest
         steps:
+            - name: Create release App token
+              id: release-app-token
+              uses: actions/create-github-app-token@v2
+              with:
+                  app-id: ${{ vars.RELEASE_APP_ID }}
+                  private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+                  owner: addon-stack
+                  repositories: addon-pay
             - uses: actions/checkout@v6
               with:
                   fetch-depth: 0
+                  token: ${{ steps.release-app-token.outputs.token }}
+            - name: Verify release branch
+              run: |
+                  test "$GITHUB_REF" = "refs/heads/main"
             - uses: pnpm/action-setup@v4
               with:
                   version: 11.1.2
@@ -37,5 +47,5 @@ jobs:
             - name: Version, release, and publish changed packages
               run: pnpm exec nx release --yes
               env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+                  GITHUB_TOKEN: ${{ steps.release-app-token.outputs.token }}
                   NPM_CONFIG_PROVENANCE: "true"

README.md

@@ -88,7 +88,9 @@ Use Conventional Commits. The commit-msg hook and CI validate the format. Nx Rel
 
 ## Release model
 
-After a Conventional Commit is merged into `main`, the release workflow validates the workspace, runs `nx release`, creates the version commit and tags, writes per-package GitHub Releases, and publishes only changed release packages. It uses npm Trusted Publishing, so releases after bootstrap require no npm token and receive npm provenance.
+Conventional Commits merge into `main` through pull requests and accumulate until a maintainer starts the **Release** workflow manually from `main` in GitHub Actions. The workflow validates the workspace, runs `nx release`, creates the version commit and tags, writes per-package GitHub Releases, and publishes only changed release packages. It writes to GitHub through the repository-only `addon-stack-addon-pay-release` GitHub App, while npm Trusted Publishing supplies short-lived OIDC credentials for publishing with provenance.
+
+Always start the workflow from `main`; it rejects any other branch. Nx Release considers all unreleased Conventional Commits since the previous package tag, so several fixes can be published together in one patch release and a `feat` in the same package produces one minor release.
 
 ## First publication for a new package
 

nx.json

@@ -10,7 +10,7 @@
       "pattern": "{projectName}@{version}"
     },
     "conventionalCommits": {
-      "useCommitScope": false
+      "useCommitScope": true
     },
     "version": {
       "conventionalCommits": true,

packages/@addon-pay/client/README.md

@@ -1,3 +1,3 @@
 # @addon-pay/client
 
-Control-plane API client for configuring AddonPay.
+Control-plane API client for configuring AddonPay. It will automate the same plans, entitlements, and service configuration that developers manage in the AddonPay dashboard.

packages/@addon-pay/sdk/README.md

@@ -1,3 +1,3 @@
 # @addon-pay/sdk
 
-Client runtime SDK for AddonPay applications.
+Client runtime SDK for AddonPay applications. It exposes the application-facing data needed to evaluate entitlements, inspect plans, and retrieve paywall configuration.