fix: skills reference swamp-troubleshooting for understanding internals

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

@@ -302,13 +302,22 @@ transparently resolves to the new name.
 - Reorganizing data after a model's purpose evolves
 - Fixing typos in data names without losing history
 
-```bash
-# Rename a data instance
-swamp data rename my-model old-name new-name
-
-# With explicit repo directory
-swamp data rename my-model old-name new-name --repo-dir ./my-repo
-```
+**Rename workflow:**
+
+1. **Verify** the new name doesn't already exist:
+   ```bash
+   swamp data get my-model new-name --no-content --json
+   ```
+   This should return an error (not found). If it succeeds, the name is taken.
+2. **Rename** the data instance:
+   ```bash
+   swamp data rename my-model old-name new-name
+   ```
+3. **Confirm** the forward reference works:
+   ```bash
+   swamp data get my-model old-name --no-content --json
+   ```
+   Should resolve to `new-name` via the forward reference.
 
 **What happens:**
 
@@ -334,13 +343,21 @@ overwrite the forward reference.
 
 Clean up expired data and old versions based on lifecycle settings.
 
-**Preview what would be deleted:**
+**IMPORTANT: Always dry-run first.** GC deletes data permanently. Follow this
+workflow:
 
-```bash
-swamp data gc --dry-run --json
-```
+1. **Preview** what will be deleted:
+   ```bash
+   swamp data gc --dry-run --json
+   ```
+2. **Review** the output — verify only expected items appear
+3. **Run** the actual GC only after confirming the dry-run output:
+   ```bash
+   swamp data gc --json
+   swamp data gc -f --json  # Skip confirmation prompt
+   ```
 
-**Output shape:**
+**Dry-run output shape:**
 
 ```json
 {
@@ -351,25 +368,12 @@ swamp data gc --dry-run --json
       "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
       "dataName": "cache",
       "reason": "lifetime:ephemeral"
-    },
-    {
-      "type": "other-type",
-      "modelId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
-      "dataName": "log",
-      "reason": "lifetime:1h"
     }
   ]
 }
 ```
 
-**Run garbage collection:**
-
-```bash
-swamp data gc --json
-swamp data gc -f --json  # Skip confirmation prompt
-```
-
-**Output shape:**
+**GC output shape:**
 
 ```json
 {
@@ -410,13 +414,14 @@ Data is stored in the `.swamp/data/` directory:
 
 ## When to Use Other Skills
 
-| Need                 | Use Skill                       |
-| -------------------- | ------------------------------- |
-| Create/run models    | `swamp-model`                   |
-| View model outputs   | `swamp-model` (output commands) |
-| Create/run workflows | `swamp-workflow`                |
-| Repository structure | `swamp-repo`                    |
-| Manage secrets       | `swamp-vault`                   |
+| Need                       | Use Skill                       |
+| -------------------------- | ------------------------------- |
+| Create/run models          | `swamp-model`                   |
+| View model outputs         | `swamp-model` (output commands) |
+| Create/run workflows       | `swamp-workflow`                |
+| Repository structure       | `swamp-repo`                    |
+| Manage secrets             | `swamp-vault`                   |
+| Understand swamp internals | `swamp-troubleshooting`         |
 
 ## References
 

.claude/skills/swamp-extension-datastore/SKILL.md

@@ -199,6 +199,7 @@ swamp datastore status --json
 | Create custom execution drivers     | `swamp-extension-driver` |
 | Repository setup and configuration  | `swamp-repo`             |
 | Manage secrets for datastore config | `swamp-vault`            |
+| Understand swamp internals          | `swamp-troubleshooting`  |
 
 ## References
 

.claude/skills/swamp-extension-driver/SKILL.md

@@ -233,3 +233,12 @@ driver file — swamp silently skips files that fail to compile.
 - **Troubleshooting**: See
   [references/troubleshooting.md](references/troubleshooting.md) for common
   issues (driver not found, output types, resolution priority)
+
+## When to Use Other Skills
+
+| Need                       | Use Skill               |
+| -------------------------- | ----------------------- |
+| Use existing models        | `swamp-model`           |
+| Create custom models       | `swamp-extension-model` |
+| Repository structure       | `swamp-repo`            |
+| Understand swamp internals | `swamp-troubleshooting` |

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

@@ -461,14 +461,15 @@ swamp model type describe @myorg/my-model --json  # Check schema
 
 ## When to Use Other Skills
 
-| Need                      | Use Skill        |
-| ------------------------- | ---------------- |
-| Use existing models       | `swamp-model`    |
-| Create/run workflows      | `swamp-workflow` |
-| Manage secrets for models | `swamp-vault`    |
-| Repository structure      | `swamp-repo`     |
-| Manage model data         | `swamp-data`     |
-| Create reports for models | `swamp-report`   |
+| Need                       | Use Skill               |
+| -------------------------- | ----------------------- |
+| Use existing models        | `swamp-model`           |
+| Create/run workflows       | `swamp-workflow`        |
+| Manage secrets for models  | `swamp-vault`           |
+| Repository structure       | `swamp-repo`            |
+| Manage model data          | `swamp-data`            |
+| Create reports for models  | `swamp-report`          |
+| Understand swamp internals | `swamp-troubleshooting` |
 
 ## References
 

.claude/skills/swamp-extension-vault/SKILL.md

@@ -211,6 +211,7 @@ swamp vault status --json
 | Create custom datastores           | `swamp-extension-datastore` |
 | Create custom execution drivers    | `swamp-extension-driver`    |
 | Repository setup and configuration | `swamp-repo`                |
+| Understand swamp internals         | `swamp-troubleshooting`     |
 
 ## References
 

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

@@ -428,96 +428,9 @@ variables are correct for the intended target. See
 
 ## Model Outputs
 
-### Search Outputs
-
-Find method execution outputs.
-
-```bash
-swamp model output search --json
-swamp model output search "my-shell" --json
-```
-
-**Output shape:**
-
-```json
-{
-  "query": "",
-  "results": [
-    {
-      "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
-      "modelName": "my-shell",
-      "method": "execute",
-      "status": "succeeded",
-      "createdAt": "2025-01-15T10:30:00Z"
-    }
-  ]
-}
-```
-
-### Get Output Details
-
-Get full details of a specific output or latest output for a model.
-
-```bash
-swamp model output get d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json
-swamp model output get my-shell --json  # Latest output for model
-```
-
-**Output shape:**
-
-```json
-{
-  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
-  "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
-  "modelName": "my-shell",
-  "type": "command/shell",
-  "method": "execute",
-  "status": "succeeded",
-  "startedAt": "2025-01-15T10:30:00Z",
-  "completedAt": "2025-01-15T10:30:00.150Z",
-  "artifacts": [
-    { "type": "resource", "path": "..." }
-  ]
-}
-```
-
-### View Output Logs
-
-Get log content from a method execution.
-
-```bash
-swamp model output logs d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json
-```
-
-**Output shape:**
-
-```json
-{
-  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
-  "logs": "Executing shell command...\nHello, world!\nCommand completed successfully."
-}
-```
-
-### View Output Data
-
-Get data artifact content from a method execution.
-
-```bash
-swamp model output data d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json
-```
-
-**Output shape:**
-
-```json
-{
-  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
-  "data": {
-    "exitCode": 0,
-    "command": "echo 'Hello, world!'",
-    "executedAt": "2025-01-15T10:30:00Z"
-  }
-}
-```
+Use `swamp model output search`, `output get`, `output logs`, and `output data`
+to inspect method execution results. See
+[references/outputs.md](references/outputs.md) for commands and output shapes.
 
 ## Workflow Example
 
@@ -562,9 +475,12 @@ validation.
 | Manage data lifecycle           | `swamp-data`            |
 | Create custom TypeScript models | `swamp-extension-model` |
 | Create reports for models       | `swamp-report`          |
+| Understand swamp internals      | `swamp-troubleshooting` |
 
 ## References
 
+- **Outputs**: See [references/outputs.md](references/outputs.md) for output
+  search, get, logs, and data commands with output shapes
 - **Examples**: See [references/examples.md](references/examples.md) for
   complete model workflows and CEL expression reference
 - **Troubleshooting**: See

.claude/skills/swamp-model/references/outputs.md

@@ -0,0 +1,92 @@
+# Model Outputs Reference
+
+## Search Outputs
+
+Find method execution outputs.
+
+```bash
+swamp model output search --json
+swamp model output search "my-shell" --json
+```
+
+**Output shape:**
+
+```json
+{
+  "query": "",
+  "results": [
+    {
+      "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
+      "modelName": "my-shell",
+      "method": "execute",
+      "status": "succeeded",
+      "createdAt": "2025-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+## Get Output Details
+
+Get full details of a specific output or latest output for a model.
+
+```bash
+swamp model output get d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json
+swamp model output get my-shell --json  # Latest output for model
+```
+
+**Output shape:**
+
+```json
+{
+  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
+  "modelId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
+  "modelName": "my-shell",
+  "type": "command/shell",
+  "method": "execute",
+  "status": "succeeded",
+  "startedAt": "2025-01-15T10:30:00Z",
+  "completedAt": "2025-01-15T10:30:00.150Z",
+  "artifacts": [
+    { "type": "resource", "path": "..." }
+  ]
+}
+```
+
+## View Output Logs
+
+Get log content from a method execution.
+
+```bash
+swamp model output logs d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json
+```
+
+**Output shape:**
+
+```json
+{
+  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
+  "logs": "Executing shell command...\nHello, world!\nCommand completed successfully."
+}
+```
+
+## View Output Data
+
+Get data artifact content from a method execution.
+
+```bash
+swamp model output data d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5 --json
+```
+
+**Output shape:**
+
+```json
+{
+  "outputId": "d1e2f3a4-b5c6-4d7e-f8a9-b0c1d2e3f4a5",
+  "data": {
+    "exitCode": 0,
+    "command": "echo 'Hello, world!'",
+    "executedAt": "2025-01-15T10:30:00Z"
+  }
+}
+```

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

@@ -268,6 +268,7 @@ export SWAMP_DATASTORE='@myorg/my-store:{"key":"val"}'
 | Create custom TypeScript models | `swamp-extension-model`     |
 | Create custom datastores        | `swamp-extension-datastore` |
 | Create custom drivers           | `swamp-extension-driver`    |
+| Understand swamp internals      | `swamp-troubleshooting`     |
 
 ## References
 

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

@@ -286,6 +286,7 @@ Failed reports appear as `{ "_error": "error message" }`.
 | Extend model with new method | `swamp-extension-model` |
 | Manage model data            | `swamp-data`            |
 | Repository structure         | `swamp-repo`            |
+| Understand swamp internals   | `swamp-troubleshooting` |
 
 ## References