codexkit 1.0.1 → 1.0.3

package/.codex/.template-manifest.json

@@ -1,43 +1,44 @@
 {
-  "version": "1.0.1",
+  "version": "1.0.3",
   "generator": "codexkit",
   "files": {
     "templates/global/AGENTS.override.md": "11039408f8776171820ce34165b5da6d52a703d26a938fb773e231a159eefe2c",
     "templates/global/.codex-config-template.toml": "aa3490d544eded2ab1eff3eee89823884d1d0085c502eceb604d89408a94848d",
     "templates/project/.codex-config-template.toml": "dc8ded8af4deaf39155d5fdddeabf0763af5293f24e3477ec871d59fd8530e80",
     "templates/project/AGENTS.md.template": "acb5ea31fd561ddbbc79c6baf6de98b990bbac693ba6d836406d270a1f27a981",
-    ".codex/config.toml": "4f87b2685b6daefea111792f5845388f7f0bbc2c0153d1d4c7428f795d437274",
+    ".codex/config.toml": "32644bd80c9804612a851907c900ccc2edd84683a3470b224d173e29ee318a6a",
     ".codex/.env.example": "1827612829279fad025404b763ea214412bd5cd53474ad315909a8c275f12b84",
-    ".codex/.version": "44e161e4495cac2cf7858043e9e6418e9579f0ddcfae826f9a372622968ce066",
-    ".codex/agents/builder.toml": "90da25e01967639be3d7b5a204be69d1dfa67ea3fea2d6bf93e0deb7be3bbb8b",
-    ".codex/agents/debugger.toml": "d709c5f64ae2ec8ee901766441b9687ce9ea40d5a8966aec594d757dc5327d9e",
-    ".codex/agents/general.toml": "a2fa240c01bcc33272c585d1bfa996cf1c0686204b7cc909f0fd1cdad1f5c830",
-    ".codex/agents/painter.toml": "3f537a94344dd5ed6787b907f85a14962b4ee9a29a003d53d94e06a5f1703f38",
-    ".codex/agents/planner.toml": "3d1fcc13de5d9cc74b9cfbe74850198d31f2ec6600728ae9d765cdc25400344f",
-    ".codex/agents/refactorer.toml": "70e8b8a1719941608ce769fa0272b49b0f7a06ad0c6b0d456a4f1dc1a271f6c1",
-    ".codex/agents/reviewer.toml": "3aa6d01c470f0c336c2d4e21a759ebcaaa3569707e4148eb9dbc777a85cc65dc",
-    ".codex/agents/runner.toml": "5012edd1d0fbd2ea161f6fbfd039b6bfd0588574dd92ad0fb3d1fc298c96e776",
-    ".codex/agents/scout.toml": "d91ba06a4bf2d3a7e8fca3a9f9706d3fc80ff8cf32943535f9a2a49df6ddd8c8",
-    ".codex/agents/shipper.toml": "5ec8eb612dd893b4e56a42867dcfdfbcbb3d7df7edf24b48629fe05062004e2b",
-    ".codex/agents/vision.toml": "b396ef6e6ded4b88326d4537bc771b8d4212ce63fbbd8503081e77667448b7ae",
+    ".codex/.version": "f5e5c9534532840fcd45bb002e69ed85c61dba2753450e26b448b7df1481e24d",
+    ".codex/agents/builder.toml": "b4e887e5ad5202337b0fda9815588db0eec2deee8fdfbdb8dad6bf2df6bf3d30",
+    ".codex/agents/debugger.toml": "e67fdaee1807c2d8c40b2752737d6e1f535a0c52d863cc76eb9c8059f292bc13",
+    ".codex/agents/general.toml": "274489e5d726ee11fc5d9ec43d44c4b7bc1ac22b435ad536af8818c6d430d46c",
+    ".codex/agents/painter.toml": "bf03cc1cfe383aaa8b46c1a9632b917c79c0cea122ab3dedb3ed79afad580cec",
+    ".codex/agents/planner.toml": "3b195c6e89065481a0825d652884485883dfca8da07281f113a1025b0971c9e6",
+    ".codex/agents/refactorer.toml": "0de4d73931352edbef9dcff4bfd6ad4fb61ff10ba5fcf330d724e5f4193fdd67",
+    ".codex/agents/reviewer.toml": "8634aac733cbf2e9c8d5ad81fc22a17c239156c1d78edb15e94b6f63488c1177",
+    ".codex/agents/runner.toml": "cb3baca8eb358ace7c4b63f39ec6de0833b6e46655ccf816b0a553ec25faa677",
+    ".codex/agents/scout.toml": "e06fa68c87261d0bfa8f2e61f34117f2291702236ca98df49d25b2faedeaf55c",
+    ".codex/agents/shipper.toml": "940c3ffd2c467e11def4c4d87bae4c5244deee42bc48009cabbf1a07009eac4b",
+    ".codex/agents/vision.toml": "430a3b9ae1f8d2322791b2683ea7cf1ca5dad353f00f2b6c2c09fd8bfe9acbe4",
     ".codex/prompts/compound.md": "2f3f713031c6a2591cf257a47f8909874ff0f94cf7a6663eeb8fe30fc1ae2a2e",
-    ".codex/prompts/create.md": "83216a93dcedfcd2e599e4fe6e1aa20c846bbc80d36ca85cf10b2f1adc0cde1a",
+    ".codex/prompts/create.md": "f8bbe26011ddf5b95a6420ba41ecac2b605d39cf767367b0d3681024b7338dec",
     ".codex/prompts/design.md": "ee5dd7883a9ceb28a5c77526c35b040e1127e3de8022654fba2e26b9d42ec529",
     ".codex/prompts/handoff.md": "c3a1429739c5e83da931e6fcca7e7c645b92fb70c2c31088446aa6378958e05d",
     ".codex/prompts/init-context.md": "1df06b3abbddb8b3b920dbe72f4ea4b1ed2af58e3c4a9067dad128657bae3681",
     ".codex/prompts/init-user.md": "2904015a4a699918f27136b8be33a5647543e748ed8c546869d6c7d8e79216b8",
-    ".codex/prompts/init.md": "ec8750b029e9376bb7b085863658113624c0378c4129aa4e72a3aa75000e0e9f",
+    ".codex/prompts/init.md": "9c17f422ee0c196d5e04e0def022d71050396630be82bf97f55139e187a960e5",
     ".codex/prompts/lfg.md": "d8d3f99522524f92d35360a9c00fb9410424b8818903ec3bb821cebef8579011",
     ".codex/prompts/plan.md": "f47aeb00d01167d5fee372115043fbfcac86216d59987ec16f67e7058aad6c42",
     ".codex/prompts/pr.md": "0866ed92ac74447ce01c955f49b00f055c5a244f80bd12a5f679f3860b776212",
     ".codex/prompts/research.md": "0ab8c8652d789ffc62a13ef6f7d533f63db77d8292dfaba4888a13a8eddb9d23",
     ".codex/prompts/resume.md": "e3d9c00cb1eb05eb367f627a039c0519c694458cf5be83b5ed9873e623e4c8e3",
     ".codex/prompts/review-codebase.md": "07f6ea450c02f820871edb2c5432d364dfa8e87bd662f13ba305ccb2cc25a5de",
-    ".codex/prompts/ship.md": "422e001f19490faa1d751c35c11825c8c77f5302eaef333bccce59a5816a6e56",
-    ".codex/prompts/start.md": "a85e5dd88f597f814cd2ebd97e0030aced0d460de3f095f0f4e3980ea87c030a",
+    ".codex/prompts/ship.md": "bf0eee8272c2ffab78574aef940be07e7dcf4129b7aa9d1368d850be16cde099",
+    ".codex/prompts/start.md": "4abc1166ae6657070ec3162610504e8e4ba19df595e4552fe30bae70561999e3",
     ".codex/prompts/status.md": "c742f0b64b08f59fceb3eb90e1693a81de421c2311eb553f85793faed19e1bca",
     ".codex/prompts/ui-inspire.md": "4562892c1b3600d5b936cb5f62f3a45cd2d48dfba16f02a26de9d087e2b15ed6",
     ".codex/prompts/ui-review.md": "4b33aa90df5e6bed0a2a5d9a077b8a778577cb0271b3a03a3f41587b6132db09",
+    ".codex/prompts/ui-slop-check.md": "19e9888ad59cd74ffeb0352b0ea813a8642320774bcdd0b34877e29ae3672e14",
     ".codex/prompts/verify.md": "d38dc229c7565c5c9a45869a1a5d17f1c3f6f5fee2f2e94ffe7ac10f9837a2e5",
     ".codex/skills/accessibility-audit/SKILL.md": "7cab0faa18ead1d87b62cb33a1f6774d9a485bf570a9b4c3538d811993eefc80",
     ".codex/skills/agent-browser/SKILL.md": "953a56fe1c7b40dd16842935f72f91b05bd25635e18196969bce982b7f8ae82a",
@@ -355,7 +356,14 @@
     ".codex/skills/figma/SKILL.md": "d9799488d3b8db3b86d633627320fea3ed6deafa11e573a0d4b9aa8e78c50ceb",
     ".codex/skills/figma/mcp.json": "1268189eaf6051544d129c9fec82454bb7df4101d22231c65f9a75e5bc1b98d6",
     ".codex/skills/finishing-a-development-branch/SKILL.md": "df9295cc756c22775779b7700997ea432b9aafab36d739c8d0b72db25d2e162f",
-    ".codex/skills/frontend-design/SKILL.md": "938575973881f39427dc9f07db72a9bda60d79d62fe8ffffb2eea2db4ef7095a",
+    ".codex/skills/frontend-design/SKILL.md": "f7ced66f8871c2015fcdc47fc699012fa515a10763de803cd52d9926e6d3f5c5",
+    ".codex/skills/frontend-design/references/color-system.md": "c602d11206390802a502592ed2035b964dfc0dada9b61558426752f36b5dda34",
+    ".codex/skills/frontend-design/references/interaction.md": "98f7f7f5021150eec6e44ede1b9b8c97c025da655dfcea7106dd6ce65569f059",
+    ".codex/skills/frontend-design/references/motion-core.md": "03ae880a0639e4add78a9dd9974b04eab09a0d43292361e86e53b4c8262b814d",
+    ".codex/skills/frontend-design/references/responsive-design.md": "38a2c5cad62b3384a56f756942fe13856c0dd164f37abdfaf3181ccd6d8bf685",
+    ".codex/skills/frontend-design/references/spatial-design.md": "e773f1d77a62696371ed680d58bb78cb94bd16d66e0976b683eb483dfd738a7e",
+    ".codex/skills/frontend-design/references/typography-rules.md": "9e8d063ce1ef57755b0231e937c05e0b4501a18c00034b7f9d89d1fcfca16d67",
+    ".codex/skills/frontend-design/references/ux-writing.md": "f0ccd5432eab0b4e8b4ccf38a17551c833df15e14a59c7a9011f45f34d9c3c3c",
     ".codex/skills/gemini-large-context/SKILL.md": "9851f1ced0c4bd99f6021cd4bf8c90ac445da25026ed96c99e8c6f38929cea7f",
     ".codex/skills/git-pr-prep/SKILL.md": "57e48b83fb11101c1376e727f39332500bbc416838f0e20e4d72d87de2ea6f3a",
     ".codex/skills/index-knowledge/SKILL.md": "b1188ba08c583d346be20d8efb0f72f834c968ff5fc708e0f04fdc32aa4d9952",
@@ -587,14 +595,14 @@
     ".codex/scripts/memory_search.sh": "4c94a2785ce337f981aa234c8b3a935af9de42117cfbacf979c078718ac9952c",
     ".codex/scripts/prepare_worklog_archive.sh": "51d606d69a0e6c73d0e1978cbdcdb581ee9187391bcf8dfbf181d55306edc16f",
     ".codex/scripts/search_bead_context.sh": "c2040a7eb6039db278422045196333f70a520f0a6ff2843c5fa06cc08f424060",
-    ".codex/scripts/start_bead.sh": "076381f9678d1043711f8dfe6a3416317c054ffb83930e233596190b604127fe",
+    ".codex/scripts/start_bead.sh": "2c86e405df67d2f0dc6d3a616c2a92a13984c2745cbf5c5d5ab4b25a90584eb2",
     ".codex/scripts/sync_bead_context.sh": "6b8d6908cffbbf8fdbf5bf548e09788d504daddce092bd7112eee695882a64a7",
     ".codex/scripts/validate_memory_docs.sh": "a0a2b184db21dae92c88a0ea837be8bcaf7a47150392034d3110842f266c4afc",
-    ".codex/scripts/verify_bead.sh": "0d943a1020d77d47d73b4a779f8aed3eea6995c886e7b98ca4ea8ba3a55dc806",
-    ".codex/mcp/README.md": "e258fb621cdb86fa1e7ff2d9ea6c04d134e22af6fafe88abf6e2ef7d579196a4",
+    ".codex/scripts/verify_bead.sh": "16571365aa54f300ec2554573f13bd74c37b22bfc54e1c09d5b55553855a0add",
+    ".codex/mcp/README.md": "06c66bf958de327cdb3e14367beb4ad7d82d1ba4a93eb4a2191fe134678ba430",
     ".codex/mcp/basic-memory.toml.example": "b40ef19861a8f29d3d78d7b166474cc4d44e79362bf5fc81942754609ff4ee3c",
-    ".codex/mcp/context7.toml.example": "bc8c1628d16f8675617692c1766d455b9d4c08e7caf42ca575ff9f6f25867af0",
-    ".codex/mcp/exa.toml.example": "81433f4660aca0480d5513d62a19e1321a0d3a650991689eb5d4ac56eddb64ca",
+    ".codex/mcp/context7.toml.example": "d016f67a43a1e578bb2c0311ba61a6e63e58aff3dc783b084eb082141f79a42b",
+    ".codex/mcp/exa.toml.example": "7aea5ab1c227ca3cf4ca9c976ec270897f39526954e8618c89764a47ec23f69b",
     ".codex/mcp/memory-bridge.toml.example": "3689f1b04410463c2e648e437e16c30901a7b1c5e165255e03b3552c9a4b03e8",
     ".codex/mcp/memory.toml.example": "3c5575ebd822729023220c7a6c7f7a6a7e0ac9e43edbf7e0665d4e06938fb8e7",
     ".codex/mcp/ref.toml.example": "a7a5d84b04f9d7a35282e91eb45111a0d7ddb185cdc8326461a8306d9b5d802b",

package/.codex/.version

@@ -1 +1 @@
-1.0.1
+1.0.3

package/.codex/agents/builder.toml

@@ -1,5 +1,6 @@
 # Builder Agent — Primary implementation specialist
 
+name = "builder"
 description = "Primary implementation agent — writes production code with verification and deviation rules."
 model = "gpt-5.3-codex"
 model_reasoning_effort = "medium"
@@ -25,7 +26,11 @@ During and after execution:
 
 ## Operating Rules
 
-- Read files before editing.
+- **Read files before editing** — runtime enforced for existing files.
+  Codex rejects Write/Edit on an existing file that has not been Read in
+  the current session (`File has not been read in this session. Read the file before editing.`).
+  New files can be written freely; the guard only fires for files already on disk.
+  Prefer Edit for partial modifications; use Write for new files or full replacements after Read.
 - Keep edits minimal and directly tied to the request.
 - Prefer existing utilities and patterns before creating new abstractions.
 - Ask before irreversible actions (delete data/files, push, merge, destructive commands).

package/.codex/agents/debugger.toml

@@ -1,6 +1,7 @@
 # Debugger Agent — Bug investigation and root cause analysis
 # Systematic debugging with hypothesis-driven investigation
 
+name = "debugger"
 description = "Bug investigation specialist — finds root causes through systematic hypothesis testing."
 model = "gpt-5.3-codex"
 model_reasoning_effort = "high"

package/.codex/agents/general.toml

@@ -1,5 +1,6 @@
 # General Agent — Small scoped implementation subtasks
 
+name = "general"
 description = "Small, well-defined implementation subtasks with limited scope."
 model = "gpt-5.3-codex"
 model_reasoning_effort = "medium"
@@ -27,7 +28,11 @@ module, one concrete acceptance target.
 ## Rules
 
 - Stay within the assigned scope.
-- Read affected files before editing.
+- **Read affected files before editing** — runtime enforced for existing files.
+  Codex rejects Write/Edit on an existing file that has not been Read in
+  the current session (`File has not been read in this session. Read the file before editing.`).
+  New files can be written freely; the guard only fires for files already on disk.
+  Prefer Edit for partial modifications; use Write for new files or full replacements after Read.
 - Run the smallest verification that proves your slice works.
 - Do not broaden the task without evidence that the current scope is blocked.
 

package/.codex/agents/painter.toml

@@ -1,5 +1,6 @@
 # Painter Agent — Visual and image-oriented ideation
 
+name = "painter"
 description = "Image generation and visual asset planning specialist."
 model = "gpt-5.4"
 model_reasoning_effort = "medium"

package/.codex/agents/planner.toml

@@ -1,6 +1,7 @@
 # Planner Agent — Architecture and implementation planning
 # Codexkit planner agent definition
 
+name = "planner"
 description = "Plans implementation approach with goal-backward decomposition before coding begins."
 model = "gpt-5.4"
 model_reasoning_effort = "high"

package/.codex/agents/refactorer.toml

@@ -1,6 +1,7 @@
 # Refactorer Agent — Safe refactoring specialist
 # Behavior-preserving code improvements with test verification
 
+name = "refactorer"
 description = "Safe refactoring specialist — improves code structure while preserving behavior."
 model = "gpt-5.3-codex"
 model_reasoning_effort = "medium"

package/.codex/agents/reviewer.toml

@@ -1,6 +1,7 @@
 # Reviewer Agent — Code review and debugging specialist
 # Codexkit reviewer agent definition
 
+name = "reviewer"
 description = "Reviews code quality, correctness, security, and test coverage."
 model = "gpt-5.4"
 model_reasoning_effort = "high"

package/.codex/agents/runner.toml

@@ -1,5 +1,6 @@
 # Runner Agent — Lightweight shell and repository operations
 
+name = "runner"
 description = "Lightweight shell, git, and filesystem operations for scoped execution tasks."
 model = "gpt-5.3-codex"
 model_reasoning_effort = "low"

package/.codex/agents/scout.toml

@@ -1,6 +1,7 @@
 # Scout Agent — External research and documentation specialist
 # Codexkit scout agent definition
 
+name = "scout"
 description = "Research specialist for library docs, API references, and external patterns."
 model = "gpt-5.4"
 model_reasoning_effort = "medium"

package/.codex/agents/shipper.toml

@@ -1,6 +1,7 @@
 # Shipper Agent — Release preparation and PR workflow
 # Codexkit shipper agent definition
 
+name = "shipper"
 description = "Prepares and validates code for shipping — PR prep, changelog, final verification."
 model = "gpt-5.3-codex"
 sandbox_mode = "workspace-write"

package/.codex/agents/vision.toml

@@ -1,6 +1,7 @@
 # Vision Agent — UI/UX analysis and accessibility specialist
 # Codexkit vision agent definition
 
+name = "vision"
 description = "Visual analysis specialist for UI/UX review, accessibility audits, design consistency, and grounded inspiration scouting."
 model = "gpt-5.4"
 model_reasoning_effort = "high"

package/.codex/config.toml

@@ -54,13 +54,16 @@ approval_policy = "on-request"
 
 # ─── Agents ─────────────────────────────────────────────────────────
 #
-# Multi-agent roles. Each role has a .toml config in .codex/agents/.
+# Multi-agent roles. Each role has a standalone .toml file in .codex/agents/.
 # Built-in roles (default, explorer, worker) are always available.
-# See: https://developers.openai.com/codex/config-advanced/#agent-roles
+# Codex auto-discovers standalone agent files (must define name, description,
+# developer_instructions). The explicit registrations below provide description
+# visibility in config and are still supported. See: https://developers.openai.com/codex/subagents
 
 [agents]
 max_threads = 6
 max_depth = 1
+# job_max_runtime_seconds = 1800  # Default timeout per worker for spawn_agents_on_csv
 
 [agents.planner]
 description = "Plans implementation approach with goal-backward decomposition before coding begins."
@@ -138,7 +141,9 @@ persistence = "save-all"
 # ─── Feature Flags ─────────────────────────────────────────────────
 
 [features]
-multi_agent = true
+# multi_agent — enabled by default since Codex v0.115.0; explicit flag no longer required.
+# Uncomment only if you need to disable subagents:
+# multi_agent = false
 # memories = true
 # Experimental / watchlist only:
 # - enable only after public Codex docs make the feature stable enough for your workflow

package/.codex/mcp/README.md

@@ -37,15 +37,31 @@ From the target project, create `.codex/.env` from `.codex/.env.example` and lau
 
 **Primary** for precise library API lookups — function signatures, code examples, version-specific docs. Deepest coverage for known libraries.
 
+**STDIO (recommended)** — free for basic use, no API key required:
+
+```toml
+[mcp_servers.context7]
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]
+```
+
+Or via CLI: `codex mcp add context7 -- npx -y @upstash/context7-mcp`
+
+For higher rate limits, add an API key from [context7.com](https://context7.com) → Dashboard:
+
+```toml
+[mcp_servers.context7.env]
+CONTEXT7_API_KEY = "your-key-here"
+```
+
+**Alternative — HTTP remote:**
+
 ```toml
 [mcp_servers.context7]
 url = "https://mcp.context7.com/mcp"
 env_http_headers = { "CONTEXT7_API_KEY" = "CONTEXT7_API_KEY" }
-startup_timeout_ms = 20_000
 ```
 
-Get your key at [context7.com](https://context7.com) → Dashboard.
-
 ### Ref — Documentation search (Primary)
 
 **Primary** for broad documentation search — covers official docs, private repos, and PDFs. Has a credit system. Broadest documentation coverage.

package/.codex/mcp/context7.toml.example

@@ -1,13 +1,30 @@
 # Context7 — Library documentation search
-# Provides: context7_resolve-library-id, context7_query-docs
-# Requires: CONTEXT7_API_KEY (get from https://context7.com → Dashboard)
+# Provides: resolve-library-id, get-library-docs
+# Free for basic use (rate-limited). API key for higher limits: https://context7.com/dashboard
 #
-# Keep the key in your shell or .codex/.env, then launch Codex with:
-#   codexkit run
+# Option A — STDIO (recommended, no API key required for basic use):
+#   codex mcp add context7 -- npx -y @upstash/context7-mcp
 #
-# Add this to ~/.codex/config.toml (NOT project-level config):
+# Option B — STDIO with API key (higher rate limits):
+#   Add to ~/.codex/config.toml:
+#
+#   [mcp_servers.context7]
+#   command = "npx"
+#   args = ["-y", "@upstash/context7-mcp"]
+#
+#   [mcp_servers.context7.env]
+#   CONTEXT7_API_KEY = "your-key-here"
+#
+# Option C — HTTP remote (alternative transport):
+#   Keep the key in your shell or .codex/.env, then launch Codex with:
+#     codexkit run
+#
+#   [mcp_servers.context7]
+#   url = "https://mcp.context7.com/mcp"
+#   env_http_headers = { "CONTEXT7_API_KEY" = "CONTEXT7_API_KEY" }
+#
+# Add to ~/.codex/config.toml (NOT project-level config):
 
 [mcp_servers.context7]
-url = "https://mcp.context7.com/mcp"
-env_http_headers = { "CONTEXT7_API_KEY" = "CONTEXT7_API_KEY" }
-startup_timeout_ms = 20_000
+command = "npx"
+args = ["-y", "@upstash/context7-mcp"]

package/.codex/mcp/exa.toml.example

@@ -1,7 +1,14 @@
 # Exa — Web search and code context
-# Provides: exa_web_search_exa, exa_get_code_context_exa
+# Default tools: exa_web_search_exa, exa_get_code_context_exa
 # Requires: EXA_API_KEY (get from https://exa.ai → Dashboard)
 #
+# Additional tools available via URL params (not enabled by default):
+#   deep_search_exa, crawling_exa, company_research_exa,
+#   linkedin_search_exa, deep_researcher_start, deep_researcher_check
+#
+# To enable extra tools, append ?tools= to the URL:
+#   url = "https://mcp.exa.ai/mcp?tools=web_search_exa,get_code_context_exa,deep_search_exa,crawling_exa"
+#
 # Keep the key in your shell or .codex/.env, then launch Codex with:
 #   codexkit run
 #

package/.codex/prompts/create.md

@@ -76,16 +76,41 @@ If `--type` is provided, use it directly. Otherwise classify and confirm:
 - **bug**: broken behavior
 - **task**: tactical change with clear scope
 
-## Phase 3: Choose Research Depth
+## Phase 3: Detect Research Scope
+
+Scan `$ARGUMENTS` for signals of external dependencies:
+
+| Category      | Signal Words                                            |
+| ------------- | ------------------------------------------------------- |
+| Payment       | stripe, paypal, paddle, lemonsqueezy, payment, billing  |
+| Auth          | auth0, clerk, supabase auth, firebase auth, oauth, SAML |
+| Email         | resend, sendgrid, postmark, ses, transactional email    |
+| Cloud         | aws, gcp, azure, vercel, cloudflare, fly.io             |
+| Database SaaS | supabase, planetscale, neon, turso, firebase            |
+| Analytics     | posthog, amplitude, mixpanel, plausible                 |
+| AI/ML         | openai, anthropic, gemini, huggingface, replicate       |
+| Storage       | s3, r2, cloudinary, uploadthing                         |
+| Task Tracking | beads_rust, linear, jira                                |
+
+**Classification:**
+
+- **internal-only**: No signals detected → all research depths available
+- **external-required**: Signal detected → Minimal and Skip are **blocked**; minimum Standard depth
+
+If external dependency is detected, tell the user: "External dependency detected ([category]). Research depth must be Standard or Deep."
+
+## Phase 4: Choose Research Depth
 
 > **Choose one:**
 >
 > 1. **Deep (Recommended)** — 3-5 investigations: patterns, tests, dependencies, and best practices (~2 min)
 > 2. **Standard** — 2 investigations: patterns + tests (~1 min)
-> 3. **Minimal** — 1 investigation: quick file scan (~30 sec)
-> 4. **Skip** — use current project knowledge only
+> 3. **Minimal** — 1 investigation: quick file scan (~30 sec) ⚠️ _Blocked if external deps detected_
+> 4. **Skip** — use current project knowledge only ⚠️ _Blocked if external deps detected_
 
-## Phase 4: Gather Context (Delegation by Depth)
+**Auto-escalation rule:** If Phase 3 classified as `external-required`, options 3 and 4 are unavailable. Default to Standard.
+
+## Phase 5: Gather Context (Delegation by Depth)
 
 Based on selected depth:
 
@@ -108,9 +133,20 @@ Based on selected depth:
 
 - No delegation; use existing `AGENTS.md` + `.codex/context/`
 
+**External dependency research (when Phase 3 = external-required):**
+
+For any depth (Deep or Standard), `@scout` **must** search for:
+
+- Official documentation / API reference for the detected service
+- Current pricing and rate limits
+- Integration examples in the project's language/framework
+- Known gotchas or breaking changes
+
+Include source URLs in all research findings. Save findings to `.beads/artifacts/<bead-id>/research.md`.
+
 While context is gathered, ask clarifying questions for missing scope/outcomes. For bugs, require repro steps and expected vs actual behavior.
 
-## Phase 5: Search Prior Related Work
+## Phase 6: Search Prior Related Work
 
 Before creating a new PRD, search durable project context for relevant prior bead work:
 
@@ -134,7 +170,7 @@ When you are ready to write the PRD, you may build that section directly with:
 .codex/scripts/build_prior_related_work.sh "$ARGUMENTS" --limit 3
 ```
 
-## Phase 6: Create Bead
+## Phase 7: Create Bead
 
 Extract title/description from `$ARGUMENTS`:
 
@@ -157,7 +193,7 @@ Create and reserve these files up front so later prompts have predictable inputs
 ```text
 .beads/artifacts/<bead-id>/
 ├── prd.md
-├── research.md        # if Phase 4 used scout/explore findings
+├── research.md        # if Phase 5 used scout/explore findings
 ├── design.md          # if design tradeoffs matter
 └── notes.md           # optional clarifications gathered during create
 ```
@@ -165,24 +201,24 @@ Create and reserve these files up front so later prompts have predictable inputs
 If the task is epic-sized, define candidate child-bead boundaries in the PRD even if the
 child beads are not created yet.
 
-## Phase 7: Write PRD
+## Phase 8: Write PRD
 
 Use the `$prd` skill template to write `.beads/artifacts/<bead-id>/prd.md`. Fill every section from gathered context — no placeholders allowed.
 
 ### Required Sections
 
-| Section           | Source                                                     | Required          |
-| ----------------- | ---------------------------------------------------------- | ----------------- |
-| Problem Statement | User description + clarifying questions                    | Always            |
-| Scope (In/Out)    | User input + codebase exploration                          | Always            |
-| Proposed Solution | Codebase patterns + user intent                            | Always            |
-| Success Criteria  | User verification + test commands (must include `Verify:`) | Always            |
-| Technical Context | Exploration findings                                       | Always            |
-| Affected Files    | Exploration findings (real paths from Phase 4)             | Always            |
-| Prior Related Work | Synced bead summaries and decision/worklog search         | If relevant       |
-| Tasks             | Derived from scope + solution                              | Always            |
-| Risks             | Codebase exploration                                       | Feature/epic only |
-| Open Questions    | Unresolved items from Phase 4                              | If any exist      |
+| Section            | Source                                                     | Required          |
+| ------------------ | ---------------------------------------------------------- | ----------------- |
+| Problem Statement  | User description + clarifying questions                    | Always            |
+| Scope (In/Out)     | User input + codebase exploration                          | Always            |
+| Proposed Solution  | Codebase patterns + user intent                            | Always            |
+| Success Criteria   | User verification + test commands (must include `Verify:`) | Always            |
+| Technical Context  | Exploration findings                                       | Always            |
+| Affected Files     | Exploration findings (real paths from Phase 5)             | Always            |
+| Prior Related Work | Synced bead summaries and decision/worklog search          | If relevant       |
+| Tasks              | Derived from scope + solution                              | Always            |
+| Risks              | Codebase exploration                                       | Feature/epic only |
+| Open Questions     | Unresolved items from Phase 5                              | If any exist      |
 
 ### Task Format
 
@@ -202,7 +238,7 @@ For feature/epic work, add a short `Execution Strategy` section covering:
 - whether child beads are recommended
 - what must be manually verified by a human
 
-## Phase 8: Validate PRD
+## Phase 9: Validate PRD
 
 Before finalizing, verify:
 
@@ -214,10 +250,11 @@ Before finalizing, verify:
 - [ ] Tasks use `[category]` headings
 - [ ] Every task includes verification
 - [ ] No implementation code in PRD
+- [ ] If external deps detected in Phase 3: `research.md` exists in artifacts with source URLs
 
 If any check fails, fix it without asking.
 
-## Phase 9: Report
+## Phase 10: Report
 
 Output:
 
@@ -232,7 +269,7 @@ br comments add $bead_id "Created prd.md with [N] tasks, [M] success criteria"
 
 ## Related Commands
 
-| Need            | Command               |
-| --------------- | --------------------- |
-| Start working   | `/prompts:start <id>` |
-| Implement next  | `/prompts:ship <id>`  |
+| Need           | Command               |
+| -------------- | --------------------- |
+| Start working  | `/prompts:start <id>` |
+| Implement next | `/prompts:ship <id>`  |

package/.codex/prompts/init.md

@@ -53,6 +53,30 @@ Create or improve `AGENTS.md` (target <60 lines, max 150):
 - Boundaries: always / ask-first / never
 - Gotchas
 
+### File Operation Guard (include in generated AGENTS.md)
+
+Document the runtime-enforced Read-before-Write/Edit rule:
+
+```markdown
+## File Operations
+
+Codex enforces a **Read-before-Write** guard at runtime for existing files:
+
+- **Existing files**: Must be Read before any Write or Edit. The runtime
+  rejects the operation with:
+  > `File has not been read in this session. Read the file before editing.`
+- **New files**: Can be written freely — the guard only fires for files
+  that already exist on disk.
+
+**Preferred tool selection:**
+
+| Intent                                 | Tool  |
+| -------------------------------------- | ----- |
+| Modify part of an existing file        | Edit  |
+| Full replacement of an existing file   | Write (after Read) |
+| Create a file that does not exist yet  | Write |
+```
+
 Principles: examples over explanation; pointers over copies; merge existing custom rules.
 
 ## Phase 4: Create Tech Stack + Context Docs