docs: add concurrency guidance and lock contention warnings to skills

.claude/skills/swamp-model/SKILL.md

@@ -259,7 +259,9 @@ Inputs are provided at runtime with `--input` or `--input-file` and referenced
 in globalArguments using `${{ inputs.<name> }}` expressions.
 
 **Factory pattern:** Use inputs to create multiple instances from one model
-definition — see
+definition — for **data reuse** (same schema, different parameters) and
+**concurrency** (separate instances hold separate locks, so long-running methods
+on one instance don't block other instances). See
 [references/scenarios.md#scenario-5](references/scenarios.md#scenario-5-factory-pattern-for-model-reuse).
 
 ## Edit a Model
@@ -477,6 +479,22 @@ primary pattern.
 
 ## Workflow Example
 
+**Design check — before creating a model, ask the user:**
+
+1. Will this model have **multiple methods** that might run at the same time
+   (e.g., a long-running build AND an SSH session)?
+2. Will any method be **long-running** (builds, deployments, large data
+   transfers)?
+
+If yes to either: each independent concern should be a **separate model
+instance**. Swamp holds an exclusive per-model lock for the entire duration of a
+method execution — a 20-minute build locks out every other method on that model.
+Use the factory pattern to split concerns into separate instances so they can
+run concurrently. See
+[references/scenarios.md#scenario-5](references/scenarios.md#scenario-5-factory-pattern-for-model-reuse).
+
+**Steps:**
+
 1. **Search** for the right type: `swamp model type search "shell" --json`
 2. **Search community** if no local type:
    `swamp extension search <query> --json` — if a matching extension exists,

.claude/skills/swamp-workflow/references/data-chaining.md

@@ -429,7 +429,14 @@ For a complete walkthrough, see the
 ### Calling One Model Multiple Times
 
 Steps within a job run in parallel. Each step calls the same `modelIdOrName`
-with different inputs:
+with different inputs.
+
+> **Lock contention:** Steps targeting the **same model** serialize on the
+> per-model lock — they won't actually run in parallel. For true parallelism,
+> use separate model instances (factory pattern) so each instance holds its own
+> lock. This matters most for long-running methods like builds or deployments.
+
+Example:
 
 ```yaml
 jobs: