🐛 fix: fix an issue with Makefile when commands have more than one hyphen

Author: bassemkaroui

template/Makefile.jinja

@@ -12,11 +12,6 @@ actions = \
 	coverage \
 	{%- if with_doppler %}
 	dc \
-	doppler-create-config \
-	doppler-create-token \
-	doppler-set-token \
-	doppler-delete-config \
-	doppler-upload-secrets \
 	{%- endif %}
 	{%- if dockerfile %}
 	docker-build \
@@ -30,7 +25,6 @@ actions = \
 	docs-deploy \
 	{%- endif %}
 	format \
-	mise-setup-completions \
 	{%- if publish_to_pypi %}
 	publish \
 	{%- endif %}
@@ -56,6 +50,23 @@ _check-mise:
 $(actions): _check-mise
 	@mise run "$(subst -,:,$@)"
 
+{%- if with_doppler %}
+doppler_actions = \
+	doppler-create-config \
+	doppler-create-token \
+	doppler-set-token \
+	doppler-delete-config \
+	doppler-upload-secrets
+
+.PHONY: $(doppler_actions)
+$(doppler_actions): _check-mise
+	@mise run "doppler:$(patsubst doppler-%,%,$@)"
+{%- endif %}
+
+.PHONY: mise-setup-completions
+mise-setup-completions: _check-mise
+	@mise run "mise:setup-completions"
+
 .PHONY: pre-commit
 pre-commit: _check-mise
 	@mise run "pre-commit"

template/docs/development/setup.md.jinja

@@ -68,11 +68,50 @@ docker compose up --build
 
 This project uses [Doppler](https://www.doppler.com/) for secrets management.
 
+### Initial Setup
+
+Authenticate and link this directory to a Doppler config:
+
 ```bash
 doppler setup
 ```
 
 Once configured, secrets are automatically injected into your environment when running tasks through mise.
+
+### Common Tasks
+
+| Task | mise |
+|------|------|
+| Upload a local `.env` to Doppler | `mise run doppler:upload-secrets` |
+| Create a branch config | `mise run doppler:create-config` |
+| Delete a branch config | `mise run doppler:delete-config` |
+| Create a service token | `mise run doppler:create-token` |
+| Set a preexisting service token | `mise run doppler:set-token` |
+
+> For the full list of options and flags, see the [Task Runner](task-runner.md#doppler-secrets-management) guide.
+
+### Branch Configs
+
+Each developer or feature branch can have its own Doppler config:
+
+```bash
+mise run doppler:create-config --config dev.alice
+mise run doppler:delete-config --config dev.alice
+```
+
+### Service Tokens
+
+Provision a read-only token for CI or another environment:
+
+```bash
+mise run doppler:create-token --token-name ci-token
+```
+
+Or configure an existing token interactively:
+
+```bash
+mise run doppler:set-token
+```
 {% endif %}
 {%- if tox %}
 

template/docs/development/task-runner.md.jinja

@@ -11,14 +11,21 @@ mise tasks    # same thing, via mise directly
 
 ## How It Works
 
-The Makefile proxies every target to mise by converting hyphens to colons:
+Most Makefile targets are proxied to mise by converting hyphens to colons:
 
 ```
 make docker-build  →  mise run docker:build
 make check-all     →  mise run check:all
 ```
 
-This is done via `$(subst -,:,$@)` in the Makefile. You never need to edit both files for existing tasks — the Makefile target list (`actions`) and the mise task definition are the only two places a task is registered.
+This is done via `$(subst -,:,$@)` in the Makefile for targets in the `actions` list.
+
+Multi-word targets where the mise task name retains a hyphen in the action part (e.g. `doppler:create-config`, `mise:setup-completions`) require explicit rules, since the generic substitution would incorrectly convert every hyphen:
+
+```
+make doppler-create-config  →  mise run doppler:create-config  (explicit rule)
+make mise-setup-completions →  mise run mise:setup-completions  (explicit rule)
+```
 
 ## Task Reference
 
@@ -158,14 +165,24 @@ mise run release --dry-run
     run = "echo hello"
     ```
 
-2. Add the hyphenated target name to the `actions` list in `Makefile`:
+2. Register the target in `Makefile`:
 
-    ```makefile
-    actions = \
-        ...
-        mycat-mytask \
-        ...
-    ```
+    - **Simple two-part tasks** (`category:action` → `category-action`): add to the `actions` list — the generic `$(subst -,:,$@)` substitution handles the rest.
+
+        ```makefile
+        actions = \
+            ...
+            mycat-mytask \
+            ...
+        ```
+
+    - **Multi-part tasks where the action contains a hyphen** (e.g. `mycat:do-thing`): add an explicit rule so the hyphen in the action part is preserved.
+
+        ```makefile
+        .PHONY: mycat-do-thing
+        mycat-do-thing: _check-mise
+            @mise run "mycat:do-thing"
+        ```
 
 Naming convention: colons (`:`) in mise, hyphens (`-`) in make.