docs: define source and catalog responsibilities

Author: vitormattos

docs/architecture.md

@@ -7,10 +7,11 @@ SPDX-License-Identifier: AGPL-3.0-or-later
 
 ## Responsibility boundary
 
-`github-workflows` owns reusable CI and release automation.
+`github-workflows` is the source of truth for reusable CI, imported workflow adaptations, generated workflow templates and release automation.
 
-It does not manage repository rulesets. That responsibility belongs to
-`LibreCodeCoop/github-governance`.
+`LibreCodeCoop/.github` is the organization-facing catalog. Generated workflow templates can be published there so developers can discover them through GitHub's **Actions → New workflow** experience. The catalog is a distribution target, not the editing source.
+
+Repository rulesets remain the responsibility of `LibreCodeCoop/github-governance`.
 
 Consumer repositories own:
 
@@ -34,11 +35,13 @@ hash verification
         ↓
 explicit downstream patches
         ↓
-generated template
+generated `workflow-templates/` artifact
         ↓
 tests + actionlint + zizmor
         ↓
-versioned release
+publish catalog copy to `LibreCodeCoop/.github`
+        ↓
+versioned release / consumer update
 ```
 
 The source manifest is authoritative. A network response that does not match the
@@ -61,3 +64,12 @@ Release automation is split into two stages:
 - **apply:** explicit mutation and publication.
 
 Credentials remain in the consumer repository or protected environment.
+
+## Developer experience
+
+The distribution model has two complementary entry points:
+
+1. **Discovery / first install:** `LibreCodeCoop/.github/workflow-templates/` provides the GitHub-native template cards, metadata and optional icons.
+2. **Ongoing updates:** consumer repositories receive reviewable update pull requests generated from the tested templates in this repository.
+
+When a workflow can be expressed as a thin caller of a reusable workflow, prefer that model because fixes remain centralized. When GitHub Actions semantics require a full installed workflow, publish the generated workflow template and keep its downstream differences as explicit patches here.