Put the adoption rules where agents look first

.github/workflows/README.md

@@ -13,11 +13,26 @@ application, which inputs it accepts, and how to solve common problems.
 Each workflow file also starts with a comment block that shows a full example call.
 `self-check.yml` is the CI of this repository. Do not call it.
 
-> **AI coding agents:** read [`AGENTS.md`](../../AGENTS.md) at the repository
-> root first. To add these workflows to a repository, follow
-> [Adopt in an existing repository](#adopt-in-an-existing-repository). SciFY
-> developers with the `scify-devops` Claude Code plugin can run `/ci-setup`,
-> which follows the same procedure.
+**Read this first** (people and AI coding agents). To add these workflows to a
+repository, follow [Adopt in an existing repository](#adopt-in-an-existing-repository).
+These five rules prevent the common mistakes:
+
+1. **Start from a template** in [`workflow-templates/`](../../workflow-templates).
+   It sets the triggers, `concurrency` and `permissions`. Do not write the
+   caller file from scratch.
+2. **Use the short tag `@v0.1`.** Never pin an exact release such as
+   `@v0.1.4`: an exact tag never moves, so the repository stops receiving fixes.
+3. **Replace only CI and security workflows.** Keep every other workflow, for
+   example deployment, Dependabot auto-merge or release workflows.
+4. **Do not guess inputs.** Read the repository's own configuration first: the
+   database in `phpunit.xml`, the scripts in `composer.json` and
+   `package.json`. Leave an input commented out when its default is right.
+5. **Verify.** Run the repository's own checks, open a pull request, and read
+   the job logs. The required check becomes `ci / CI`.
+
+AI coding agents: [`AGENTS.md`](../../AGENTS.md) at the repository root has
+more rules. SciFY developers with the `scify-devops` Claude Code plugin can run
+`/ci-setup`, which follows the same procedure.
 
 ## Contents
 
@@ -135,9 +150,12 @@ workflows. It applies to people and to AI coding agents.
    Replace `$default-branch` with the default branch, for example `main`.
 4. **Map each existing command to an input.** Keep the repository's own
    commands where they exist, for example `lint-command: composer check`. Leave
-   an input commented out when its default already does the same thing.
-5. **Remove what the shared workflows replace.** Delete the old workflow
-   files and every local copy of `scan-dev-configs` or `verify-npm-hardening`.
+   an input commented out when its default already does the same thing. Do not
+   guess: for example, `php-extensions` follows the database in `phpunit.xml`.
+5. **Remove only what the shared workflows replace.** Delete the old CI and
+   security workflow files and every local copy of `scan-dev-configs` or
+   `verify-npm-hardening`. Keep every other workflow, for example deployment,
+   Dependabot auto-merge or release workflows.
 6. **Run the repository's own checks on the new files.** Run its formatters and
    linters, for example `npm run check` or `composer check`, and
    `actionlint .github/workflows/*.yml`.
@@ -153,7 +171,8 @@ workflows. It applies to people and to AI coding agents.
 | Pitfall | What happens | Do this |
 | --- | --- | --- |
 | An action from `scify/.github` pinned by tag | The run fails: the organisation requires actions pinned by SHA | Call `security.yml`, which loads its actions by itself. For a direct use, pin the action by SHA |
-| A reusable workflow pinned by SHA | The repository stops receiving fixes | Use `@v0.1` |
+| A reusable workflow pinned by SHA or by an exact release such as `@v0.1.4` | The repository stops receiving fixes | Use the short tag `@v0.1` |
+| A caller file written from scratch | Missing triggers, for example no CI on pull requests | Start from the template (step 3) |
 | The repository's formatter does not run before the push | CI fails, for example Prettier on the new workflow file | Run the repository's own checks first (step 6) |
 | A commented-out input under `# with:` | Prettier moves the comment, and the uncommented input no longer sits under `with:` | Keep the extra indentation after the `#`, as in the templates: `#   input: value` |
 | Two inputs run the same tool | Double run time, for example `composer check` that already includes `check:types` | Give each input a command that does not overlap with the others |

.github/workflows/laravel-ci.yml

@@ -1,5 +1,9 @@
 # Reusable CI workflow for Laravel repositories.
 #
+# To use it: start from workflow-templates/laravel-ci.yml and pin the short tag @v0.1
+# (never an exact release such as @v0.1.4). Procedure for people and AI agents:
+# https://github.com/scify/.github/blob/main/.github/workflows/README.md#adopt-in-an-existing-repository
+#
 # Minimal call (every value below is a default and can be left out):
 #
 #   jobs:

.github/workflows/node-ci.yml

@@ -1,5 +1,9 @@
 # Reusable CI workflow for npm-only repositories (Vue, React, TypeScript SPAs).
 #
+# To use it: start from workflow-templates/node-ci.yml and pin the short tag @v0.1
+# (never an exact release such as @v0.1.4). Procedure for people and AI agents:
+# https://github.com/scify/.github/blob/main/.github/workflows/README.md#adopt-in-an-existing-repository
+#
 # Minimal call (every value below is a default and can be left out):
 #
 #   jobs:

.github/workflows/security.yml

@@ -1,5 +1,9 @@
 # Reusable security workflow for SciFY repositories.
 #
+# To use it: start from workflow-templates/security.yml and pin the short tag @v0.1
+# (never an exact release such as @v0.1.4). Procedure for people and AI agents:
+# https://github.com/scify/.github/blob/main/.github/workflows/README.md#adopt-in-an-existing-repository
+#
 # Call it from a repository workflow:
 #
 #   on:

AGENTS.md

@@ -15,7 +15,9 @@ in a different repository, `scify/scify-agent-tools`.
 
 ## Part 1: Use the shared workflows in another repository
 
-**Current release tag: `v0.1`.** Call every workflow with `@v0.1`.
+**Current release tag: `v0.1`.** Call every workflow with `@v0.1`. This short
+tag moves to each fix release. Never pin an exact release such as `@v0.1.4`,
+even when the release list shows it as "Latest".
 
 | Repository type | Workflows to call | Template |
 | --- | --- | --- |
@@ -40,20 +42,25 @@ gh api 'repos/scify/.github/contents/.github/workflows/README.md?ref=v0.1' \
 
 Rules that cause failures when you break them:
 
-1. **Workflows by tag, actions by SHA.** Call a reusable workflow with `@v0.1`.
+1. **Start from the template** and keep its triggers, `concurrency` and
+   `permissions`. **Replace only CI and security workflows**; keep deployment,
+   Dependabot auto-merge and other workflows. **Do not guess inputs**: read
+   `phpunit.xml`, `composer.json` and `package.json` first.
+
+2. **Workflows by tag, actions by SHA.** Call a reusable workflow with `@v0.1`.
    The organisation requires every action in a step to be pinned by full commit
    SHA, also actions from `scify/.github`. Do not call
    `scify/.github/.github/actions/<name>@v0.1`: it fails. Use `security.yml`
    instead, which runs both actions.
-2. **Run the target repository's own checks before you push.** Its formatters
+3. **Run the target repository's own checks before you push.** Its formatters
    and linters also check the new workflow files. Then run
    `actionlint .github/workflows/*.yml`.
-3. **The required check becomes `ci / CI`.** Tell the user to update the branch
+4. **The required check becomes `ci / CI`.** Tell the user to update the branch
    ruleset or branch protection. Do not change repository settings without the
    user's approval.
-4. **Read the job logs.** A green job can mean that a step was skipped, for
+5. **Read the job logs.** A green job can mean that a step was skipped, for
    example "No package.json, skipping".
-5. **Delete replaced files**: old CI or security workflows, and local copies of
+6. **Delete replaced files**: old CI or security workflows, and local copies of
    `scan-dev-configs` or `verify-npm-hardening`.
 
 The npm rules that `security.yml` enforces are in the