docs: make Portainer deploy path optional

packages/mosaic/framework/defaults/TOOLS.md

@@ -46,7 +46,7 @@ whitelisted — see the tool header.
 | tmux       | `tools/tmux/agent-send.sh`                       | inter-agent messaging (see "Most-used" above)                            |
 | git        | `tools/git/*.sh`                                 | issues, PRs, milestones, CI queue guard (platform-auto-detected)         |
 | woodpecker | `tools/woodpecker/*.sh`                          | CI pipelines (`-a mosaic`\|`usc`; match git remote host)                 |
-| portainer  | `tools/portainer/*.sh`                           | Docker Swarm stacks (status/redeploy/list)                               |
+| portainer  | `tools/portainer/*.sh`                           | Optional Docker Swarm tools when a Portainer credential is available     |
 | coolify    | `tools/coolify/*.sh`                             | **DEPRECATED** — superseded by Portainer; do not use for new deployments |
 | authentik  | `tools/authentik/*.sh`                           | identity (users/groups/apps/flows)                                       |
 | cloudflare | `tools/cloudflare/*.sh`                          | DNS (zones/records; `-a` instance)                                       |

packages/mosaic/framework/guides/INFRASTRUCTURE.md

@@ -136,7 +136,8 @@ The human is escalation-only for missing access, hard policy conflicts, or irrev
 
 ### Supported Targets
 
-- **Portainer**: Deploy via `~/.config/mosaic/tools/portainer/stack-redeploy.sh`, then verify with `stack-status.sh`.
+- **Docker Swarm**: If a stack README documents `docker stack deploy` on the manager, use that deploy path and its stated verification procedure.
+- **Portainer (optional)**: Use only when the estate holds a Portainer credential. Do not propose Portainer otherwise. Deploy via `~/.config/mosaic/tools/portainer/stack-redeploy.sh`, then verify with `stack-status.sh`.
 - **Coolify**: Deploy via `~/.config/mosaic/tools/coolify/deploy.sh -u <uuid>`, then verify with `service-status.sh`.
 - **Vercel**: Deploy via `vercel` CLI or connected Git integration, then verify preview/production URL health.
 - **Other SaaS providers**: Use provider CLI/API/runbook with the same validation and rollback gates.

packages/mosaic/framework/skills/mosaic-deploy/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: mosaic-deploy
-description: 'Full end-to-end deploy flow for Mosaic Stack projects: push branch → open PR → wait for CI → merge → redeploy Portainer stack. Use when deploying a feature branch to production or staging, or when asked to ship a completed feature. Orchestrates mosaic-gitea, mosaic-woodpecker, and mosaic-portainer skills.'
+description: 'Full end-to-end deployment flow: push branch → open PR → wait for CI → merge → deploy using the path documented by the stack. Use when deploying a feature branch to production or staging, or when asked to ship a completed feature.'
 ---
 
 # mosaic-deploy
 
-End-to-end deployment flow for Mosaic Stack projects.
+End-to-end deployment flow.
 
 ## Full Deploy Sequence
 
 ```
-push branch → open PR → CI passes → merge → portainer redeploy
+push branch → open PR → CI passes → merge → documented deploy path
 ```
 
 ### Step 1: Push branch and open PR
@@ -49,25 +49,32 @@ review. Fix the cause; never route around it with a raw API call, a shared
 credential, or `force_merge`. Exceptional cases go to the operator or the
 coordinating seat, still merged through the wrapper.
 
-### Step 4: Redeploy Portainer stack
+### Step 4: Deploy Through the Documented Path
+
+Read the stack README before deploying:
+
+- If it documents `docker stack deploy` on the manager, use that deploy path and its verification procedure.
+- Use Portainer only when the estate holds a Portainer credential. Do not propose Portainer otherwise.
+
+For an authorized Portainer deployment:
 
 ```bash
 source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
 ~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name> -p
 ```
 
-Check deployment:
+Check a Portainer deployment:
 
 ```bash
 ~/.config/mosaic/tools/portainer/stack-status.sh -n <stack-name>
 ~/.config/mosaic/tools/portainer/stack-logs.sh -n <stack-name> -l 50
 ```
 
-## Stack Name Map
+## Optional Portainer Stack Map
 
-Maintain your estate's project → stack-name mapping in a skills-local override of
+For deployments that use Portainer, maintain a project → stack-name mapping in a
-this skill (local copies take precedence over the shipped canonical one). Example
+skills-local override of this skill (local copies take precedence over the shipped
-shape:
+canonical one). Example shape:
 
 | Project      | Stack Name        |
 | ------------ | ----------------- |
@@ -77,6 +84,6 @@ shape:
 ## Notes
 
 - Workers open PRs but **never merge** — orchestrator or Merge Guard handles step 3+
-- Docker Swarm image pinning: if `-p` doesn't pull a new image, SSH to the Docker node (e.g. `node-01`) and run `docker pull <image>` manually, then redeploy
+- Docker Swarm image pinning: `-p` does not change a digest-pinned image. Follow the stack README's documented deployment procedure.
 - Worktrees: all coding work in `~/src/<repo>-worktrees/<task-slug>`, never in main checkout
 - Always clean up worktree after push: `git worktree remove ~/src/<repo>-worktrees/<task-slug>`

packages/mosaic/framework/skills/mosaic-portainer/SKILL.md

@@ -1,15 +1,19 @@
 ---
 name: mosaic-portainer
-description: Manage Portainer stacks on the Mosaic infrastructure. Use when asked to list, start, stop, redeploy, or check logs of Docker Swarm stacks via Portainer. Wraps scripts in ~/.config/mosaic/tools/portainer/. Requires load_credentials portainer first.
+description: Manage Docker Swarm stacks through Portainer when a Portainer credential is available. Use when asked to list, start, stop, redeploy, or check logs through Portainer.
 ---
 
 # mosaic-portainer
 
-Manage Portainer stacks via pre-built Mosaic scripts.
+Manage Portainer stacks through supplied scripts.
+
+## Decision Gate
+
+Portainer is optional. Use this skill only when the estate holds a Portainer credential. If a stack README documents `docker stack deploy` on the manager, that is the deploy path. Do not propose Portainer otherwise.
 
 ## Setup
 
-Always load credentials before running scripts:
+After confirming a Portainer credential is available, load it before running scripts:
 
 ```bash
 source ~/.config/mosaic/tools/_lib/credentials.sh
@@ -33,11 +37,11 @@ All scripts live in `~/.config/mosaic/tools/portainer/`.
 
 ## Common Workflows
 
-**Redeploy a stack with fresh images:**
+**Redeploy a stack through Portainer:**
 
 ```bash
 source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
-~/.config/mosaic/tools/portainer/stack-redeploy.sh -n mosaic-stack -p
+~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name> -p
 ```
 
 **Check all stack statuses:**
@@ -51,12 +55,10 @@ source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
 
 ```bash
 source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
-~/.config/mosaic/tools/portainer/stack-logs.sh -n mosaic-stack -l 100
+~/.config/mosaic/tools/portainer/stack-logs.sh -n <stack-name> -l 100
 ```
 
 ## Notes
 
-- Portainer URL: `https://portainer.example.internal:9443`
+- `stack-redeploy.sh -p` does not override a digest-pinned image. Follow the stack README's documented deployment procedure for pinned images.
-- Primary Docker host: `node-01`, managed via Portainer agent
+- Credentials are loaded through `load_credentials portainer`.
-- Docker Swarm image updates: `stack-redeploy.sh -p` does NOT guarantee new image pull if digest is pinned; SSH to node and `docker pull` first if needed
-- Credentials: `load_credentials portainer` (framework credentials store)