docs(template-sync): document APP_CLIENT_ID and external ci.yaml ownership

.github/workflows/template-sync.yaml

@@ -11,10 +11,13 @@ jobs:
   template-sync:
     # Skipped in the template repo itself (it is the sync source); runs in every
     # instance created from this template, where it opens a PR with template
-    # changes. Outside devantler-tech the org-provided APP_PRIVATE_KEY secret is
+    # changes. Outside devantler-tech the org-provided App credentials are
     # absent and the scheduled run would only fail — so personal-account
-    # instances are off by default and opt in by adding the secret plus a
-    # repository variable TEMPLATE_SYNC_ENABLED=true.
+    # instances are off by default and opt in by supplying their OWN GitHub App
+    # (one that can open PRs): the APP_PRIVATE_KEY secret plus the APP_CLIENT_ID
+    # repository variable (the reusable workflow mints its token from that
+    # variable/secret pair), and setting the repository variable
+    # TEMPLATE_SYNC_ENABLED=true.
     if: >-
       github.repository != 'devantler-tech/go-template' &&
       (github.repository_owner == 'devantler-tech' || vars.TEMPLATE_SYNC_ENABLED == 'true')

.templatesyncignore

@@ -15,9 +15,13 @@
 # the shared lint configs (.mega-linter.yml, .pre-commit-config.yaml,
 # .editorconfig, .gitattributes — NOT .golangci.yml, which instances own; see
 # below), the mockery pre-commit hook scripts, and the
-# CLAUDE.md/GEMINI.md shims. (ci.yaml is deliberately template-owned here —
-# unlike the stack-neutral gitops-tenant-template, every Go instance shares the
-# same required-checks aggregation, so CI fixes must propagate.)
+# CLAUDE.md/GEMINI.md shims. (ci.yaml is deliberately template-owned for
+# devantler-tech instances — they all share the same ruleset-injected
+# build/test workflows and this required-checks aggregation, so CI fixes must
+# propagate. An instance OUTSIDE devantler-tech does not inherit those org
+# rulesets and must replace ci.yaml with real build/test jobs — after doing
+# so, add `.github/workflows/ci.yaml` to this file, which the instance owns,
+# so a later sync cannot revert it.)
 
 # --- Identity & docs (instance-specific) ---
 AGENTS.md

README.md

@@ -64,10 +64,16 @@ file falls into one of three ownership classes:
   by sync afterwards, so you can delete them and they stay gone.
 
 The sync workflow no-ops in this template repository itself. In devantler-tech
-instances it works out of the box (the org provides the `APP_PRIVATE_KEY`
-secret); an instance elsewhere is off by default — opt in by adding an
-`APP_PRIVATE_KEY` secret (a GitHub App key that can open PRs) and setting the
-repository variable `TEMPLATE_SYNC_ENABLED=true`.
+instances it works out of the box (the org provides the App credentials); an
+instance elsewhere is off by default — opt in by supplying your own GitHub App
+(one allowed to open PRs in your repository): add its private key as the
+`APP_PRIVATE_KEY` secret, its client ID as the `APP_CLIENT_ID` repository
+variable (the reusable workflow mints its token from that variable/secret
+pair), and set the repository variable `TEMPLATE_SYNC_ENABLED=true`. Note that
+outside devantler-tech the synced `ci.yaml` is only an empty required-check
+aggregator (the real build/test workflows are injected by devantler-tech org
+rulesets): replace it with your own CI and add `.github/workflows/ci.yaml` to
+your `.templatesyncignore` so later syncs preserve your version.
 
 ## 📝 Usage