deadends-dev 0.1.0__tar.gz

deadends_dev-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YuJin Hong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deadends_dev-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: deadends-dev
+Version: 0.1.0
+Summary: Structured failure knowledge for AI agents — dead ends, workarounds, error chains
+Author: YuJin Hong
+License-Expression: MIT
+Project-URL: Homepage, https://deadends.dev
+Project-URL: Repository, https://github.com/dbwls99706/deadends.dev
+Project-URL: API, https://deadends.dev/api/v1/index.json
+Keywords: error,debugging,dead-end,workaround,ai-agent,mcp,error-handling,troubleshooting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jinja2>=3.1
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: jsonschema>=4.20; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: jsonschema>=4.20; extra == "mcp"
+Provides-Extra: pipeline
+Requires-Dist: jsonschema>=4.20; extra == "pipeline"
+Requires-Dist: requests>=2.31; extra == "pipeline"
+Requires-Dist: anthropic>=0.25; extra == "pipeline"
+Dynamic: license-file
+
+# deadend.dev
+
+**Structured failure knowledge for AI coding agents.**
+
+87 error entries across 14 domains. When AI agents encounter errors, they waste tokens on approaches that are known to fail. deadend.dev tells agents what NOT to try, what actually works, and what error comes next.
+
+## Quick Start — Python SDK
+
+```python
+from generator.lookup import lookup
+
+result = lookup("ModuleNotFoundError: No module named 'torch'")
+
+# What NOT to try (saves tokens and time)
+for d in result["dead_ends"]:
+    print(f"AVOID: {d['action']} — fails {int(d['fail_rate']*100)}%")
+
+# What actually works
+for w in result["workarounds"]:
+    print(f"TRY: {w['action']} — works {int(w['success_rate']*100)}%")
+```
+
+## Quick Start — CLI
+
+```bash
+pip install -e .
+python -m generator.lookup "CUDA error: out of memory"
+python -m generator.lookup --list  # show all known errors
+```
+
+## Quick Start — MCP Server (Claude Desktop / Cursor)
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "deadend": {
+      "command": "python",
+      "args": ["-m", "mcp.server"],
+      "cwd": "/path/to/deadend.dev"
+    }
+  }
+}
+```
+
+Then Claude will automatically check deadend.dev when encountering errors.
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| [`/api/v1/match.json`](https://deadends.dev/api/v1/match.json) | Lightweight regex matching (fits in context window) |
+| [`/api/v1/index.json`](https://deadends.dev/api/v1/index.json) | Full error index with all metadata |
+| `/api/v1/{domain}/{slug}/{env}.json` | Individual error canon |
+| [`/api/v1/openapi.json`](https://deadends.dev/api/v1/openapi.json) | OpenAPI 3.1 spec |
+| [`/llms.txt`](https://deadends.dev/llms.txt) | LLM-optimized error listing ([llmstxt.org](https://llmstxt.org) standard) |
+| [`/llms-full.txt`](https://deadends.dev/llms-full.txt) | Complete database dump |
+| [`/.well-known/ai-plugin.json`](https://deadends.dev/.well-known/ai-plugin.json) | AI plugin manifest |
+
+## Covered Domains (14)
+
+| Domain | Errors | Examples |
+|--------|--------|----------|
+| python | 20 | ModuleNotFoundError, TypeError, KeyError, MemoryError |
+| node | 11 | ERR_MODULE_NOT_FOUND, EACCES, ERR_REQUIRE_ESM, heap OOM |
+| docker | 10 | permission denied, no space left, exec format error |
+| cuda | 9 | OOM, version mismatch, device-side assert, NCCL timeout |
+| git | 6 | failed to push refs, merge conflicts, pathspec errors |
+| pip | 6 | build wheel failed, conflicting dependencies |
+| typescript | 4 | TS2307, TS2322, TS2345, TS7006 |
+| rust | 3 | E0382 borrow, E0308 mismatch, E0277 trait bound |
+| go | 3 | undefined reference, imported not used, type mismatch |
+| kubernetes | 3 | CrashLoopBackOff, ImagePullBackOff, OOMKilled |
+| terraform | 3 | state lock, provider not present, cycle |
+| aws | 3 | AccessDenied, ExpiredToken, ResourceNotFound |
+| nextjs | 3 | hydration failed, module not found, server component hooks |
+| react | 3 | invalid hook call, too many re-renders, update while rendering |
+
+## ErrorCanon Data Format
+
+Each error is a JSON file with:
+
+```json
+{
+  "error": { "signature": "...", "regex": "...", "domain": "..." },
+  "verdict": { "resolvable": "true|partial|false", "fix_success_rate": 0.88 },
+  "dead_ends": [{ "action": "...", "why_fails": "...", "fail_rate": 0.75 }],
+  "workarounds": [{ "action": "...", "success_rate": 0.92, "how": "..." }],
+  "transition_graph": { "leads_to": [...], "preceded_by": [...] }
+}
+```
+
+## AI Agent Integration
+
+Every page on deadend.dev includes 8 machine-readable formats:
+
+1. **JSON API** — RESTful error data at `/api/v1/{id}.json`
+2. **match.json** — Compact regex-only file (load entire DB into context)
+3. **JSON-LD** — Schema.org TechArticle + FAQPage in every `<head>`
+4. **ai-summary** — `<pre id="ai-summary">` with KEY=VALUE pairs
+5. **llms.txt** — [llmstxt.org](https://llmstxt.org) standard
+6. **OpenAPI** — Full API specification
+7. **ai-plugin.json** — Plugin discovery manifest
+8. **robots.txt** — All AI crawlers explicitly welcomed
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+
+# Full pipeline (validate → generate → build → test)
+python -m generator.pipeline
+
+# Individual steps
+python -m generator.bulk_generate     # Generate canons from seeds
+python -m generator.build_site        # Build static site
+python -m generator.validate          # Validate data + site
+python -m pytest tests/ -v            # Run tests
+```
+
+## Contributing
+
+Add error definitions to `generator/bulk_generate.py` or create JSON files directly in `data/canons/`.
+
+```bash
+python -m generator.validate --data-only  # Validate before submitting
+```
+
+## License
+
+MIT (code) · CC BY 4.0 (data)

deadends_dev-0.1.0/README.md

@@ -0,0 +1,132 @@
+# deadend.dev
+
+**Structured failure knowledge for AI coding agents.**
+
+87 error entries across 14 domains. When AI agents encounter errors, they waste tokens on approaches that are known to fail. deadend.dev tells agents what NOT to try, what actually works, and what error comes next.
+
+## Quick Start — Python SDK
+
+```python
+from generator.lookup import lookup
+
+result = lookup("ModuleNotFoundError: No module named 'torch'")
+
+# What NOT to try (saves tokens and time)
+for d in result["dead_ends"]:
+    print(f"AVOID: {d['action']} — fails {int(d['fail_rate']*100)}%")
+
+# What actually works
+for w in result["workarounds"]:
+    print(f"TRY: {w['action']} — works {int(w['success_rate']*100)}%")
+```
+
+## Quick Start — CLI
+
+```bash
+pip install -e .
+python -m generator.lookup "CUDA error: out of memory"
+python -m generator.lookup --list  # show all known errors
+```
+
+## Quick Start — MCP Server (Claude Desktop / Cursor)
+
+Add to `~/.claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "deadend": {
+      "command": "python",
+      "args": ["-m", "mcp.server"],
+      "cwd": "/path/to/deadend.dev"
+    }
+  }
+}
+```
+
+Then Claude will automatically check deadend.dev when encountering errors.
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| [`/api/v1/match.json`](https://deadends.dev/api/v1/match.json) | Lightweight regex matching (fits in context window) |
+| [`/api/v1/index.json`](https://deadends.dev/api/v1/index.json) | Full error index with all metadata |
+| `/api/v1/{domain}/{slug}/{env}.json` | Individual error canon |
+| [`/api/v1/openapi.json`](https://deadends.dev/api/v1/openapi.json) | OpenAPI 3.1 spec |
+| [`/llms.txt`](https://deadends.dev/llms.txt) | LLM-optimized error listing ([llmstxt.org](https://llmstxt.org) standard) |
+| [`/llms-full.txt`](https://deadends.dev/llms-full.txt) | Complete database dump |
+| [`/.well-known/ai-plugin.json`](https://deadends.dev/.well-known/ai-plugin.json) | AI plugin manifest |
+
+## Covered Domains (14)
+
+| Domain | Errors | Examples |
+|--------|--------|----------|
+| python | 20 | ModuleNotFoundError, TypeError, KeyError, MemoryError |
+| node | 11 | ERR_MODULE_NOT_FOUND, EACCES, ERR_REQUIRE_ESM, heap OOM |
+| docker | 10 | permission denied, no space left, exec format error |
+| cuda | 9 | OOM, version mismatch, device-side assert, NCCL timeout |
+| git | 6 | failed to push refs, merge conflicts, pathspec errors |
+| pip | 6 | build wheel failed, conflicting dependencies |
+| typescript | 4 | TS2307, TS2322, TS2345, TS7006 |
+| rust | 3 | E0382 borrow, E0308 mismatch, E0277 trait bound |
+| go | 3 | undefined reference, imported not used, type mismatch |
+| kubernetes | 3 | CrashLoopBackOff, ImagePullBackOff, OOMKilled |
+| terraform | 3 | state lock, provider not present, cycle |
+| aws | 3 | AccessDenied, ExpiredToken, ResourceNotFound |
+| nextjs | 3 | hydration failed, module not found, server component hooks |
+| react | 3 | invalid hook call, too many re-renders, update while rendering |
+
+## ErrorCanon Data Format
+
+Each error is a JSON file with:
+
+```json
+{
+  "error": { "signature": "...", "regex": "...", "domain": "..." },
+  "verdict": { "resolvable": "true|partial|false", "fix_success_rate": 0.88 },
+  "dead_ends": [{ "action": "...", "why_fails": "...", "fail_rate": 0.75 }],
+  "workarounds": [{ "action": "...", "success_rate": 0.92, "how": "..." }],
+  "transition_graph": { "leads_to": [...], "preceded_by": [...] }
+}
+```
+
+## AI Agent Integration
+
+Every page on deadend.dev includes 8 machine-readable formats:
+
+1. **JSON API** — RESTful error data at `/api/v1/{id}.json`
+2. **match.json** — Compact regex-only file (load entire DB into context)
+3. **JSON-LD** — Schema.org TechArticle + FAQPage in every `<head>`
+4. **ai-summary** — `<pre id="ai-summary">` with KEY=VALUE pairs
+5. **llms.txt** — [llmstxt.org](https://llmstxt.org) standard
+6. **OpenAPI** — Full API specification
+7. **ai-plugin.json** — Plugin discovery manifest
+8. **robots.txt** — All AI crawlers explicitly welcomed
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+
+# Full pipeline (validate → generate → build → test)
+python -m generator.pipeline
+
+# Individual steps
+python -m generator.bulk_generate     # Generate canons from seeds
+python -m generator.build_site        # Build static site
+python -m generator.validate          # Validate data + site
+python -m pytest tests/ -v            # Run tests
+```
+
+## Contributing
+
+Add error definitions to `generator/bulk_generate.py` or create JSON files directly in `data/canons/`.
+
+```bash
+python -m generator.validate --data-only  # Validate before submitting
+```
+
+## License
+
+MIT (code) · CC BY 4.0 (data)

deadends_dev-0.1.0/data/canons/aws/access-denied-exception/awscli2-linux.json

@@ -0,0 +1,104 @@
+{
+  "schema_version": "1.0.0",
+  "id": "aws/access-denied-exception/awscli2-linux",
+  "url": "https://deadends.dev/aws/access-denied-exception/awscli2-linux",
+  "error": {
+    "signature": "An error occurred (AccessDeniedException) when calling the X operation",
+    "regex": "(AccessDeniedException|AccessDenied|403 Forbidden).*when calling",
+    "domain": "aws",
+    "category": "auth_error",
+    "first_seen": "2023-01-01",
+    "last_confirmed": "2026-02-11"
+  },
+  "environment": {
+    "runtime": {
+      "name": "aws",
+      "version_range": ">=2.0,<3.0"
+    },
+    "os": "linux"
+  },
+  "verdict": {
+    "resolvable": "true",
+    "fix_success_rate": 0.82,
+    "confidence": 0.85,
+    "last_updated": "2026-02-11",
+    "summary": "IAM permissions insufficient for the requested operation."
+  },
+  "dead_ends": [
+    {
+      "action": "Add AdministratorAccess policy",
+      "why_fails": "Severe security risk, violates least-privilege principle",
+      "fail_rate": 0.85,
+      "sources": [
+        "https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege"
+      ],
+      "condition": ""
+    },
+    {
+      "action": "Use root account credentials",
+      "why_fails": "Root should never be used for API calls, critical security issue",
+      "fail_rate": 0.95,
+      "sources": [
+        "https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#lock-away-credentials"
+      ],
+      "condition": ""
+    }
+  ],
+  "workarounds": [
+    {
+      "action": "Check which specific permission is needed using CloudTrail or IAM Access Analyzer",
+      "success_rate": 0.85,
+      "how": "aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventName,AttributeValue=OperationName",
+      "sources": [
+        "https://docs.aws.amazon.com/IAM/latest/UserGuide/access-analyzer-getting-started.html"
+      ],
+      "condition": ""
+    },
+    {
+      "action": "Add the minimum required IAM policy for the specific action and resource",
+      "success_rate": 0.82,
+      "sources": [
+        "https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html"
+      ],
+      "condition": ""
+    }
+  ],
+  "transition_graph": {
+    "leads_to": [
+      {
+        "error_id": "aws/expired-token-exception/awscli2-linux",
+        "probability": 0.15,
+        "condition": "Created temporary credentials that expire"
+      },
+      {
+        "error_id": "aws/resource-not-found/awscli2-linux",
+        "probability": 0.2,
+        "condition": "Has permissions but wrong region or resource name"
+      }
+    ],
+    "preceded_by": [
+      {
+        "error_id": "aws/expired-token-exception/awscli2-linux",
+        "probability": 0.25,
+        "condition": "Refreshed token but new role has insufficient permissions"
+      }
+    ],
+    "frequently_confused_with": [
+      {
+        "error_id": "aws/expired-token-exception/awscli2-linux",
+        "distinction": "ExpiredToken means valid permissions but expired session; AccessDenied means active session but insufficient permissions"
+      },
+      {
+        "error_id": "aws/resource-not-found/awscli2-linux",
+        "distinction": "ResourceNotFound means resource doesn't exist; AccessDenied means it may exist but you can't access it"
+      }
+    ]
+  },
+  "metadata": {
+    "generated_by": "bulk_generate.py",
+    "generation_date": "2026-02-11",
+    "review_status": "auto_generated",
+    "evidence_count": 355,
+    "last_verification": "2026-02-11"
+  }
+}

deadends_dev-0.1.0/data/canons/aws/expired-token-exception/awscli2-linux.json

@@ -0,0 +1,95 @@
+{
+  "schema_version": "1.0.0",
+  "id": "aws/expired-token-exception/awscli2-linux",
+  "url": "https://deadends.dev/aws/expired-token-exception/awscli2-linux",
+  "error": {
+    "signature": "An error occurred (ExpiredTokenException): The security token included in the request is expired",
+    "regex": "ExpiredTokenException|security token.+is expired|token.+has expired",
+    "domain": "aws",
+    "category": "auth_error",
+    "first_seen": "2023-01-01",
+    "last_confirmed": "2026-02-11"
+  },
+  "environment": {
+    "runtime": {
+      "name": "aws",
+      "version_range": ">=2.0,<3.0"
+    },
+    "os": "linux"
+  },
+  "verdict": {
+    "resolvable": "true",
+    "fix_success_rate": 0.9,
+    "confidence": 0.9,
+    "last_updated": "2026-02-11",
+    "summary": "AWS session token has expired. Common with STS temporary credentials and SSO sessions."
+  },
+  "dead_ends": [
+    {
+      "action": "Hardcode long-lived access keys",
+      "why_fails": "Security anti-pattern, keys can leak and don't rotate",
+      "fail_rate": 0.88,
+      "sources": [
+        "https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#rotate-credentials"
+      ],
+      "condition": ""
+    },
+    {
+      "action": "Extend token lifetime to maximum",
+      "why_fails": "Only delays the problem, tokens still expire",
+      "fail_rate": 0.55,
+      "sources": [
+        "https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html"
+      ],
+      "condition": ""
+    }
+  ],
+  "workarounds": [
+    {
+      "action": "Refresh credentials with aws sso login or aws sts assume-role",
+      "success_rate": 0.92,
+      "how": "aws sso login --profile my-profile",
+      "sources": [
+        "https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html"
+      ],
+      "condition": ""
+    },
+    {
+      "action": "Use credential_process or credential helpers for automatic refresh",
+      "success_rate": 0.85,
+      "sources": [
+        "https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html"
+      ],
+      "condition": ""
+    }
+  ],
+  "transition_graph": {
+    "leads_to": [
+      {
+        "error_id": "aws/access-denied-exception/awscli2-linux",
+        "probability": 0.2,
+        "condition": "Refreshed credentials may have different/fewer permissions"
+      }
+    ],
+    "preceded_by": [
+      {
+        "error_id": "aws/access-denied-exception/awscli2-linux",
+        "probability": 0.15,
+        "condition": "Assumed role with temporary credentials that later expire"
+      }
+    ],
+    "frequently_confused_with": [
+      {
+        "error_id": "aws/access-denied-exception/awscli2-linux",
+        "distinction": "AccessDenied means wrong permissions; ExpiredToken means right permissions but session has timed out"
+      }
+    ]
+  },
+  "metadata": {
+    "generated_by": "bulk_generate.py",
+    "generation_date": "2026-02-11",
+    "review_status": "auto_generated",
+    "evidence_count": 240,
+    "last_verification": "2026-02-11"
+  }
+}

deadends_dev-0.1.0/data/canons/aws/invalid-security-token/awscli2-linux.json

@@ -0,0 +1,78 @@
+{
+  "schema_version": "1.0.0",
+  "id": "aws/invalid-security-token/awscli2-linux",
+  "url": "https://deadends.dev/aws/invalid-security-token/awscli2-linux",
+  "error": {
+    "signature": "An error occurred (InvalidClientTokenId): The security token is invalid",
+    "regex": "InvalidClientTokenId|security token.*invalid|SignatureDoesNotMatch",
+    "domain": "aws",
+    "category": "auth_error",
+    "first_seen": "2023-01-01",
+    "last_confirmed": "2026-02-11"
+  },
+  "environment": {
+    "runtime": {
+      "name": "aws",
+      "version_range": ">=2.0"
+    },
+    "os": "linux"
+  },
+  "verdict": {
+    "resolvable": "true",
+    "fix_success_rate": 0.88,
+    "confidence": 0.9,
+    "last_updated": "2026-02-11",
+    "summary": "AWS credentials are wrong or expired. Common with temporary session tokens."
+  },
+  "dead_ends": [
+    {
+      "action": "Regenerate all access keys",
+      "why_fails": "May be unnecessary if it's just an expired session token",
+      "fail_rate": 0.5,
+      "sources": [
+        "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html"
+      ],
+      "condition": ""
+    },
+    {
+      "action": "Disable MFA requirement",
+      "why_fails": "Severe security downgrade, doesn't fix the token",
+      "fail_rate": 0.85,
+      "sources": [
+        "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html"
+      ],
+      "condition": ""
+    }
+  ],
+  "workarounds": [
+    {
+      "action": "Check if using temporary credentials that expired; refresh with aws sts get-session-token",
+      "success_rate": 0.9,
+      "sources": [
+        "https://docs.aws.amazon.com/cli/latest/reference/sts/get-session-token.html"
+      ],
+      "condition": ""
+    },
+    {
+      "action": "Verify correct AWS_PROFILE is set, check ~/.aws/credentials",
+      "success_rate": 0.88,
+      "how": "aws sts get-caller-identity  # shows which identity is being used",
+      "sources": [
+        "https://docs.aws.amazon.com/cli/latest/reference/sts/get-caller-identity.html"
+      ],
+      "condition": ""
+    }
+  ],
+  "transition_graph": {
+    "leads_to": [],
+    "preceded_by": [],
+    "frequently_confused_with": []
+  },
+  "metadata": {
+    "generated_by": "bulk_generate.py",
+    "generation_date": "2026-02-11",
+    "review_status": "auto_generated",
+    "evidence_count": 50,
+    "last_verification": "2026-02-11"
+  }
+}

deadends_dev-0.1.0/data/canons/aws/no-credentials-error/awscli2-linux.json

@@ -0,0 +1,78 @@
+{
+  "schema_version": "1.0.0",
+  "id": "aws/no-credentials-error/awscli2-linux",
+  "url": "https://deadends.dev/aws/no-credentials-error/awscli2-linux",
+  "error": {
+    "signature": "botocore.exceptions.NoCredentialsError: Unable to locate credentials",
+    "regex": "NoCredentialsError|Unable to locate credentials",
+    "domain": "aws",
+    "category": "auth_error",
+    "first_seen": "2023-01-01",
+    "last_confirmed": "2026-02-11"
+  },
+  "environment": {
+    "runtime": {
+      "name": "aws",
+      "version_range": ">=2.0"
+    },
+    "os": "linux"
+  },
+  "verdict": {
+    "resolvable": "true",
+    "fix_success_rate": 0.9,
+    "confidence": 0.92,
+    "last_updated": "2026-02-11",
+    "summary": "AWS SDK can't find credentials. Missing env vars, config, or IAM role."
+  },
+  "dead_ends": [
+    {
+      "action": "Hardcode credentials in source code",
+      "why_fails": "Security risk — credentials in git history",
+      "fail_rate": 0.95,
+      "sources": [
+        "https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html"
+      ],
+      "condition": ""
+    },
+    {
+      "action": "Set AWS_ACCESS_KEY_ID in .env and commit",
+      "why_fails": "Same security risk as hardcoding",
+      "fail_rate": 0.9,
+      "sources": [
+        "https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html"
+      ],
+      "condition": ""
+    }
+  ],
+  "workarounds": [
+    {
+      "action": "Configure credentials: aws configure, or set env vars, or use IAM role",
+      "success_rate": 0.95,
+      "how": "aws configure  # sets ~/.aws/credentials",
+      "sources": [
+        "https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html"
+      ],
+      "condition": ""
+    },
+    {
+      "action": "In EC2/ECS/Lambda: use IAM role (no credentials needed)",
+      "success_rate": 0.92,
+      "sources": [
+        "https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html"
+      ],
+      "condition": ""
+    }
+  ],
+  "transition_graph": {
+    "leads_to": [],
+    "preceded_by": [],
+    "frequently_confused_with": []
+  },
+  "metadata": {
+    "generated_by": "bulk_generate.py",
+    "generation_date": "2026-02-11",
+    "review_status": "auto_generated",
+    "evidence_count": 50,
+    "last_verification": "2026-02-11"
+  }
+}