codexkit 1.0.3 → 1.0.5

package/.codex/.template-manifest.json

@@ -1,14 +1,14 @@
 {
-  "version": "1.0.3",
+  "version": "1.0.4",
   "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": "32644bd80c9804612a851907c900ccc2edd84683a3470b224d173e29ee318a6a",
+    ".codex/config.toml": "2079664ff35b0b5b05187c1fa5e6b4fdb0b8df24fff5e69ab9297956459d1b16",
     ".codex/.env.example": "1827612829279fad025404b763ea214412bd5cd53474ad315909a8c275f12b84",
-    ".codex/.version": "f5e5c9534532840fcd45bb002e69ed85c61dba2753450e26b448b7df1481e24d",
+    ".codex/.version": "d1b77b88f4b9f675a900e4143ac768a21218623cfe1703ca43162388c3271bd6",
     ".codex/agents/builder.toml": "b4e887e5ad5202337b0fda9815588db0eec2deee8fdfbdb8dad6bf2df6bf3d30",
     ".codex/agents/debugger.toml": "e67fdaee1807c2d8c40b2752737d6e1f535a0c52d863cc76eb9c8059f292bc13",
     ".codex/agents/general.toml": "274489e5d726ee11fc5d9ec43d44c4b7bc1ac22b435ad536af8818c6d430d46c",
@@ -17,7 +17,7 @@
     ".codex/agents/refactorer.toml": "0de4d73931352edbef9dcff4bfd6ad4fb61ff10ba5fcf330d724e5f4193fdd67",
     ".codex/agents/reviewer.toml": "8634aac733cbf2e9c8d5ad81fc22a17c239156c1d78edb15e94b6f63488c1177",
     ".codex/agents/runner.toml": "cb3baca8eb358ace7c4b63f39ec6de0833b6e46655ccf816b0a553ec25faa677",
-    ".codex/agents/scout.toml": "e06fa68c87261d0bfa8f2e61f34117f2291702236ca98df49d25b2faedeaf55c",
+    ".codex/agents/scout.toml": "ff411e1a10f9ff99cdc92e345be92e5bfa674f6d9dd03ca03dab7d5b31895252",
     ".codex/agents/shipper.toml": "940c3ffd2c467e11def4c4d87bae4c5244deee42bc48009cabbf1a07009eac4b",
     ".codex/agents/vision.toml": "430a3b9ae1f8d2322791b2683ea7cf1ca5dad353f00f2b6c2c09fd8bfe9acbe4",
     ".codex/prompts/compound.md": "2f3f713031c6a2591cf257a47f8909874ff0f94cf7a6663eeb8fe30fc1ae2a2e",
@@ -31,8 +31,9 @@
     ".codex/prompts/plan.md": "f47aeb00d01167d5fee372115043fbfcac86216d59987ec16f67e7058aad6c42",
     ".codex/prompts/pr.md": "0866ed92ac74447ce01c955f49b00f055c5a244f80bd12a5f679f3860b776212",
     ".codex/prompts/research.md": "0ab8c8652d789ffc62a13ef6f7d533f63db77d8292dfaba4888a13a8eddb9d23",
-    ".codex/prompts/resume.md": "e3d9c00cb1eb05eb367f627a039c0519c694458cf5be83b5ed9873e623e4c8e3",
+    ".codex/prompts/resume.md": "02b286294fcd2c58a2e3c0a77995eefc9c76319dbbc54e35fc1208f06c7fca99",
     ".codex/prompts/review-codebase.md": "07f6ea450c02f820871edb2c5432d364dfa8e87bd662f13ba305ccb2cc25a5de",
+    ".codex/prompts/search.md": "f648fbfa84e16654981e262fb233a1e23b2525790f0698da5bc2bbc8aea60ad0",
     ".codex/prompts/ship.md": "bf0eee8272c2ffab78574aef940be07e7dcf4129b7aa9d1368d850be16cde099",
     ".codex/prompts/start.md": "4abc1166ae6657070ec3162610504e8e4ba19df595e4552fe30bae70561999e3",
     ".codex/prompts/status.md": "c742f0b64b08f59fceb3eb90e1693a81de421c2311eb553f85793faed19e1bca",
@@ -323,12 +324,12 @@
     ".codex/skills/cloudflare/references/zaraz/README.md": "c1fd43e131dd57576c84b10c4bc12b92d17ce8a837d042c0ed0e9ec5ab2fd256",
     ".codex/skills/code-navigation/SKILL.md": "bd35077d9afd8becb5f0813e9ced5c214daf6e5aad3926270091cb731fe58e28",
     ".codex/skills/code-review/SKILL.md": "3f7d6b61adbe4eb68bc6907721d1ad7d74c474a6eb0a6784ea0163945d272cad",
-    ".codex/skills/compaction/SKILL.md": "0d623d5c435d62d8bc5082b40b52871080a22be47f14418ce5ffd17d0fe4985b",
+    ".codex/skills/compaction/SKILL.md": "d85f33180d26148d500ef6501e421513bec349f9078d4a5a47f70341088a2a01",
     ".codex/skills/condition-based-waiting/SKILL.md": "cf3c747488745c6e51e62bbf1e84b3cb868aac05ff3f8c245e65aa9ab4a0c5a8",
     ".codex/skills/condition-based-waiting/example.ts": "e35f816255c50db93421c8b5f165a6efbc3baa0856ce66a44edc7b34c0bd3608",
     ".codex/skills/context-engineering/SKILL.md": "1dcd750d778aebbf11f5ac09ace26b5ebd69f4d7e68994f53c22464a74e430b5",
     ".codex/skills/context-initialization/SKILL.md": "5fbf8502303789fffba37f62fa274f9e7fece31935859d5c9f0be3bfd3b14764",
-    ".codex/skills/context-management/SKILL.md": "1666a72e8388e4cbd4a3addf52546966122d617d9091b1eb983b520ae0177dae",
+    ".codex/skills/context-management/SKILL.md": "e6e39288a95776860126c1b65a8b4143046858455960b9b1b19f055de6d24fb8",
     ".codex/skills/core-data-expert/SKILL.md": "f8db3769edd501b86795d3ea43dd32060060dd1ab9f905055fea9301f07009a6",
     ".codex/skills/core-data-expert/references/batch-operations.md": "96ab160c97b15b661de854bd24a2e5e3a9b8ec05a51009f5fe98ad887e52e0e7",
     ".codex/skills/core-data-expert/references/cloudkit-integration.md": "550039d328a43519a2fb50ce3d8d8572a2ab8253991aa919ec33b849b60b56a8",
@@ -455,7 +456,7 @@
     ".codex/skills/root-cause-tracing/SKILL.md": "ff1002204c1ec1b1de54a77886edb0cd7c7d1d97a2b571a861818b2a466bba85",
     ".codex/skills/root-cause-tracing/find-polluter.sh": "6462747eae9b175ac145b78bcfaeab755654a75e32637f08eb633f065a9e1d7c",
     ".codex/skills/safe-implementation/SKILL.md": "fd92709e320b3ccbaa76fe5259424439ab769a67e8d72830f780fde8210ce2da",
-    ".codex/skills/session-management/SKILL.md": "57353a9f7f75f9ac1a7e658b0218780e3c51e51f200fd5c88fc82cd884e77b93",
+    ".codex/skills/session-management/SKILL.md": "53532fa06e003a7dfd62afa0b8b7d4f1c8ac0967b35f1d5bd8734668417d276b",
     ".codex/skills/sharing-skills/SKILL.md": "c662da5bd3907b987121854efddd90a266db902d1662e62b4e6054e3f03d07dd",
     ".codex/skills/skill-creator/SKILL.md": "c574e634e616905287338f6cad0359ef471a6f241cd888cabcebfa1710d2a71d",
     ".codex/skills/source-code-research/SKILL.md": "0ec5a37e92c81505de40e37c190f1d64c870e8c5e75636ea76901f1d05fc265f",
@@ -585,10 +586,10 @@
     ".codex/hooks/stop.sh": "7008c4a7a6fba302b0f589c65370b0bf8444a2c7b2114117521b9ea09041cfc3",
     ".codex/scripts/append_worklog.sh": "44b7d6f00f4be6aec77081c7c74d9891cb12b6096f29204903ae544991172591",
     ".codex/scripts/apply_worklog_archive.sh": "416958f91d760a09183235c2d7a67faa0a006351652bf743da7045273129c49c",
-    ".codex/scripts/audit_memory_hygiene.sh": "aab875482c959e85d7d2d27434639849bed27ed77d74514d2ac60e2fe0e33083",
+    ".codex/scripts/audit_memory_hygiene.sh": "9739a42d176db2002d81f0626c3458eda2004a4fdeeefe2c0b2797d10cb240b1",
     ".codex/scripts/build_memory_index.sh": "247ecaed52d305dcf6651f137c8e762e7b4661781af16df8a296b3da19ad96b8",
     ".codex/scripts/build_prior_related_work.sh": "08d226f318eb4859529f774b9e03daaee4c70d17e814422cddb6f1c1efd52313",
-    ".codex/scripts/build_startup_brief.sh": "880a7156e0999d94729e9cea174ccb4291ef5752d4a572851dc24c7eb9818f92",
+    ".codex/scripts/build_startup_brief.sh": "7130ae1c5a56c79f66c6450a558f3f6b9642ed34df8696b2fde82d1d287caddf",
     ".codex/scripts/close_bead.sh": "90944f59945a440280b958924858e1bb515e60bbc36805e26387da77ef657022",
     ".codex/scripts/detect_changed_files.sh": "10633eda525c32ac0a1410239117f8ede5d23ae7faba4108b3f3e9096ffed366",
     ".codex/scripts/ensure_beads.sh": "9f69036f7fdb332f2089b4a58afdc55d982612cc004d98628bfd0b311f74e078",
@@ -599,10 +600,10 @@
     ".codex/scripts/sync_bead_context.sh": "6b8d6908cffbbf8fdbf5bf548e09788d504daddce092bd7112eee695882a64a7",
     ".codex/scripts/validate_memory_docs.sh": "a0a2b184db21dae92c88a0ea837be8bcaf7a47150392034d3110842f266c4afc",
     ".codex/scripts/verify_bead.sh": "16571365aa54f300ec2554573f13bd74c37b22bfc54e1c09d5b55553855a0add",
-    ".codex/mcp/README.md": "06c66bf958de327cdb3e14367beb4ad7d82d1ba4a93eb4a2191fe134678ba430",
+    ".codex/mcp/README.md": "e03cb3c5cd228692c5f573b1ead8e2b0f2effda361ec43721617029d561f3083",
     ".codex/mcp/basic-memory.toml.example": "b40ef19861a8f29d3d78d7b166474cc4d44e79362bf5fc81942754609ff4ee3c",
-    ".codex/mcp/context7.toml.example": "d016f67a43a1e578bb2c0311ba61a6e63e58aff3dc783b084eb082141f79a42b",
-    ".codex/mcp/exa.toml.example": "7aea5ab1c227ca3cf4ca9c976ec270897f39526954e8618c89764a47ec23f69b",
+    ".codex/mcp/context7.toml.example": "658967017443c6c9d6b181694767c3f97180c2febdc050cc3747de2b3ae2b761",
+    ".codex/mcp/exa.toml.example": "bc746ddc0fc9e88cbaa14d8b6cff1b3d3a5e04e587722b7a82d79d18a6cd21d4",
     ".codex/mcp/memory-bridge.toml.example": "3689f1b04410463c2e648e437e16c30901a7b1c5e165255e03b3552c9a4b03e8",
     ".codex/mcp/memory.toml.example": "3c5575ebd822729023220c7a6c7f7a6a7e0ac9e43edbf7e0665d4e06938fb8e7",
     ".codex/mcp/ref.toml.example": "a7a5d84b04f9d7a35282e91eb45111a0d7ddb185cdc8326461a8306d9b5d802b",
@@ -621,15 +622,15 @@
     ".codex/memory/_templates/gotcha.md": "bf06bb72050dd71afb543d9ac9480f35ac240100fe8221ae855cf286dc94c0a7",
     ".codex/memory/_templates/handoff.md": "1d83137e655733453a2895b8a2f6cb29238eeff26ed276250164ebeecdd5e204",
     ".codex/memory/_templates/prd.md": "11f80e3af46896c7980bef37088381350e5cbc90e2f22399c50ed9dcab3f2bc1",
-    ".codex/memory/_templates/project.md": "9481f5cf842ff23e7d8d09288a83df023e969f702309edf7a3ba65536dc6a8b5",
+    ".codex/memory/_templates/project.md": "21e720af0d9bbe600f6707ca6bdc88af75e4d134563b825680738d9aa2d2499e",
     ".codex/memory/_templates/proposal.md": "5ad769245bd83279bbd70fc37976b23c08190d2a4b416eb46cb696b22d437e19",
     ".codex/memory/_templates/research.md": "6966290f90233087979cca5c49c075216c817b9c63c0ae444fea0f4b667ed016",
     ".codex/memory/_templates/roadmap.md": "6945f7fa459554d7195104bc1e8f1debdd3c5d37f869e63ae2a60ecb37065045",
-    ".codex/memory/_templates/session-context.md": "515d6be5bbbb9dfb2d97618f0ca6a0c895c1a91a5c036d9667d658ea113d9551",
-    ".codex/memory/_templates/state.md": "4af203c29a565479547fcba0945118cd66014e32710f0ba75c9f0572e65d46b1",
+    ".codex/memory/_templates/session-context.md": "fb39fb199be3323d1417982ecdfd7eb758a5a3ef06662eab5df10696d6c3eba5",
+    ".codex/memory/_templates/state.md": "98286fa2aa00e216dc29dcc7fe7d9da1401cb33d36af5a482f88e8188bcc788c",
     ".codex/memory/_templates/tasks.md": "54119ce84fd0aa6ecd0148355f33808c061147da774475c94bf7e47bb18f73dd",
-    ".codex/memory/_templates/tech-stack.md": "06cfafa736d9f32876aecfad9cfe54785a4db7dcecf94abdb09b7895761d763f",
-    ".codex/memory/_templates/user.md": "4156bd3195edab1b196ac3f398ca7ec90295b91c3a5b028673be065463e5fdaf",
+    ".codex/memory/_templates/tech-stack.md": "38c0e2255360cc777295bcb89202510f3e0ee0927d7a23422ca55b33a6ef9448",
+    ".codex/memory/_templates/user.md": "d12ba5cdc382dbeeda5128a0b0ffe81993fbebfd882edaa46e6778cf7088cf73",
     ".codex/memory/project/gotchas.md": "05ce128ced24deffbb51a8b7167000c4e4816c4e3275a98f439fddb0e95c2bd6",
     ".codex/memory/project/project.md": "94a76028472946ba9782534de4920e9a77cfdf0f4daa063a97569660ccc06e21",
     ".codex/memory/project/roadmap.md": "6027b3bd3eaeed02b16a59037e760200ce8505f3007375faf2543b4b58bcee6e",

package/.codex/.version

@@ -1 +1 @@
-1.0.3
+1.0.4

package/.codex/agents/scout.toml

@@ -50,7 +50,7 @@ Before starting research, check which tools are available and adapt your strateg
 | grepsearch | GitHub real-world code examples  | Built-in      | Always available            |
 
 > **All three external MCPs are primary.** For best results, use them together in parallel:
-> - **exa** — broadest: web search (`exa_web_search_exa`) + code context (`exa_get_code_context_exa`)
+> - **exa** — broadest: web search (`web_search_exa`) + code context (`get_code_context_exa`)
 > - **ref** — broadest docs: searches docs, private repos, and PDFs (has credit system)
 > - **context7** — deepest library API: precise function signatures, code examples, version-specific docs
 >
@@ -58,6 +58,47 @@ Before starting research, check which tools are available and adapt your strateg
 > research output. Fallback only applies when a tool is **unavailable** (not configured,
 > out of credits, or timing out) — not because it's less important.
 
+### Context7 Workflow (Two-Step)
+
+Context7 requires a two-step lookup:
+
+1. **resolve-library-id**: Search for library → get Context7 library ID
+   - Input: `libraryName` (e.g. "next.js") + `query` (what you need)
+   - Pick best match by: name similarity > trust score > snippet count
+   - Max 3 calls per question
+
+2. **query-docs**: Fetch docs/code using library ID from step 1
+   - Input: `libraryId` (e.g. "/vercel/next.js") + `query` (specific question)
+   - Be specific: "How to set up JWT auth in Express.js" > "auth"
+   - Include language + framework + version in queries
+   - Max 3 calls per question
+
+### Exa Tool Selection
+
+Choose the right Exa tool for each task:
+
+| Task                          | Tool                    | Notes                               |
+|-------------------------------|-------------------------|-------------------------------------|
+| General web research          | `web_search_exa`        | News, trends, current info          |
+| Code examples & API usage     | `get_code_context_exa`  | GitHub, StackOverflow, official docs |
+| Read specific URL content     | `crawling_exa`          | Full page content extraction        |
+| Complex multi-source question | `deep_search_exa`       | Query expansion + synthesis         |
+
+Tips:
+- Use `numResults=5-8` for focused queries, `10+` for broad exploration
+- Include current year in queries for recent info
+- `get_code_context_exa` is best for "how do I use X library" questions
+- `crawling_exa` is best when you already have a URL to read
+
+### Ref Tool Selection
+
+| Tool                       | Purpose                                        |
+|----------------------------|------------------------------------------------|
+| `ref_search_documentation` | Search public docs, private repos, PDFs        |
+| `ref_read_url`             | Read content of a URL from search results      |
+
+Include `ref_src=private` in query to search user's private docs.
+
 ### Fallback Chain (when a tool is unavailable)
 
 Only used when a tool is not configured or fails. Under normal operation, all three run together.

package/.codex/config.toml

@@ -144,8 +144,27 @@ persistence = "save-all"
 # 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
-# - do not treat it as a replacement for `.codex/context/` or `.codex/memory/`
-# - keep repo-visible docs as the canonical source of truth even if native memory matures
+
+# ─── Memories ──────────────────────────────────────────────────────
+#
+# Codex CLI has a native memories subsystem (MemoriesToml) that manages
+# persistent conversation context and summarization across sessions.
+#
+# Status: Available in Codex CLI but still maturing. Codexkit treats it as
+# opt-in. Repo-visible docs (.codex/context/ and .codex/memory/) remain
+# the canonical source of truth for project knowledge.
+#
+# To enable native Codex memories:
+#   [features]
+#   memories = true
+#
+# To configure the memories subsystem (when supported by your Codex version):
+#   [memories]
+#   # max_history_tokens = 4096
+#   # summarization_enabled = true
+#
+# Guidance:
+# - Enable only after verifying your Codex version supports [memories] config
+# - Do not treat native memories as a replacement for .codex/context/ or .codex/memory/
+# - Keep repo-visible docs as the canonical source of truth
+# - Native memories complement file-based context; they do not replace it

package/.codex/mcp/README.md

@@ -37,6 +37,13 @@ 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.
 
+**Two-step workflow:**
+
+1. `resolve-library-id` — search for library by name → get Context7 library ID
+2. `query-docs` — fetch docs/code examples using the library ID from step 1
+
+Best practices: include language + framework in queries, be specific, max 3 calls per tool per question.
+
 **STDIO (recommended)** — free for basic use, no API key required:
 
 ```toml
@@ -77,7 +84,19 @@ Get your key at [ref.tools](https://ref.tools) → Dashboard.
 
 ### Exa — Web search & code context (Primary)
 
-**Primary** for web research and code context. Most versatile tool — handles general web search (`exa_web_search_exa`) and programming-specific code context (`exa_get_code_context_exa`).
+**Primary** for web research and code context. Most versatile tool.
+
+**Default tools**: `web_search_exa` (general web search), `get_code_context_exa` (code from GitHub/StackOverflow/docs)
+
+**Optional tools** (enable via `?tools=` URL parameter): `crawling_exa` (read full page content), `deep_search_exa` (multi-source synthesis), `company_research_exa`, `linkedin_search_exa`
+
+Tool selection:
+- `web_search_exa` → general queries, news, trends
+- `get_code_context_exa` → programming questions, API usage, library examples
+- `crawling_exa` → when you have a specific URL to read
+- `deep_search_exa` → complex questions needing multi-source answers
+
+**Default config** (minimal, fastest):
 
 ```toml
 [mcp_servers.exa]
@@ -85,6 +104,14 @@ url = "https://mcp.exa.ai/mcp"
 bearer_token_env_var = "EXA_API_KEY"
 ```
 
+**Research config** (for scout agent, adds page crawling + deep search):
+
+```toml
+[mcp_servers.exa]
+url = "https://mcp.exa.ai/mcp?tools=web_search_exa,get_code_context_exa,crawling_exa,deep_search_exa"
+bearer_token_env_var = "EXA_API_KEY"
+```
+
 Get your key at [exa.ai](https://exa.ai) → Dashboard.
 
 ### Optional: Basic Memory — real long-term memory

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

@@ -1,13 +1,31 @@
-# Context7 — Library documentation search
-# Provides: resolve-library-id, get-library-docs
+# Context7 — Library documentation and code examples
+# Provides: resolve-library-id, query-docs
 # Free for basic use (rate-limited). API key for higher limits: https://context7.com/dashboard
 #
+# ─── Workflow ───────────────────────────────────────────────────────────
+# Context7 uses a TWO-STEP workflow:
+#
+#   Step 1: resolve-library-id  → search for library, get Context7 library ID
+#           Input: libraryName + query (what you need help with)
+#           Output: library ID (e.g. /vercel/next.js), name, snippet count, trust score
+#
+#   Step 2: query-docs          → fetch documentation and code examples
+#           Input: libraryId (from step 1) + query (specific question)
+#           Output: relevant code snippets + documentation text
+#
+# Best practices:
+#   - Always include language + framework in queries (e.g. "React useState hook examples")
+#   - Be specific: "How to set up JWT auth in Express.js" > "auth"
+#   - Select libraries by: name match > trust score > snippet count > benchmark score
+#   - Max 3 resolve-library-id calls per question; use best result if not found
+#   - Max 3 query-docs calls per question; combine results if needed
+#
+# ─── Setup Options ──────────────────────────────────────────────────────
+#
 # Option A — STDIO (recommended, no API key required for basic use):
 #   codex mcp add context7 -- npx -y @upstash/context7-mcp
 #
 # Option B — STDIO with API key (higher rate limits):
-#   Add to ~/.codex/config.toml:
-#
 #   [mcp_servers.context7]
 #   command = "npx"
 #   args = ["-y", "@upstash/context7-mcp"]
@@ -16,9 +34,6 @@
 #   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" }

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

@@ -1,13 +1,39 @@
-# Exa — Web search and code context
-# Default tools: exa_web_search_exa, exa_get_code_context_exa
+# Exa — Web search, code context, and deep research
 # 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
+# ─── Available Tools ────────────────────────────────────────────────────
 #
-# 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"
+# Default (always enabled):
+#   web_search_exa          — General web search with clean content extraction
+#   get_code_context_exa    — Code snippets from GitHub, StackOverflow, official docs
+#
+# Optional (enable via ?tools= URL parameter):
+#   crawling_exa            — Read full page content from a specific URL
+#   deep_search_exa         — Query expansion + synthesized multi-source answers
+#   company_research_exa    — Company profile lookup (funding, headcount, tech stack)
+#   linkedin_search_exa     — LinkedIn profile search
+#   deep_researcher_start   — Start async deep research job
+#   deep_researcher_check   — Check deep research job status and results
+#
+# ─── Recommended Configurations ─────────────────────────────────────────
+#
+# Minimal (daily development — fastest, lowest cost):
+#   url = "https://mcp.exa.ai/mcp"
+#
+# Research (scout agent — adds page crawling and deep search):
+#   url = "https://mcp.exa.ai/mcp?tools=web_search_exa,get_code_context_exa,crawling_exa,deep_search_exa"
+#
+# Full (all tools enabled):
+#   url = "https://mcp.exa.ai/mcp?tools=web_search_exa,get_code_context_exa,crawling_exa,deep_search_exa,company_research_exa,linkedin_search_exa"
+#
+# ─── Best Practices ─────────────────────────────────────────────────────
+#
+#   - web_search_exa: general queries, news, trends, current info
+#   - get_code_context_exa: programming questions, API usage, library examples
+#   - crawling_exa: when you have a specific URL and need full page content
+#   - deep_search_exa: complex questions needing multi-source synthesis
+#   - Use numResults=5-8 for focused queries, 10+ for broad exploration
+#   - Include year in search queries for current info (e.g. "React 19 features 2026")
 #
 # Keep the key in your shell or .codex/.env, then launch Codex with:
 #   codexkit run

package/.codex/memory/_templates/project.md

@@ -2,8 +2,16 @@
 
 ## Vision
 
+- Describe the long-term purpose of this project.
+
 ## Goals
 
+- List near-term and durable goals here.
+
 ## Success Criteria
 
+- Define what "done" or "successful" looks like.
+
 ## Context Notes
+
+- Add any additional project context or constraints here.

package/.codex/memory/_templates/session-context.md

@@ -1,7 +1,15 @@
 # Session Context
 
+Use this file for compact session state that should survive context compaction.
+
 ## Current Focus
 
+- None recorded.
+
 ## Open Questions
 
+- None recorded.
+
 ## Next Actions
+
+- None recorded.

package/.codex/memory/_templates/state.md

@@ -2,10 +2,20 @@
 
 ## Status
 
+- Record the current milestone and operating state here.
+
 ## Recent Completed Work
 
+- Summarize recently completed work here.
+
 ## Active Decisions
 
+- Capture decisions currently steering implementation here.
+
 ## Blockers
 
+- Record active blockers here. Remove when resolved.
+
 ## Next Actions
+
+- Record the next durable actions here. Keep to 3-5 items.

package/.codex/memory/_templates/tech-stack.md

@@ -2,8 +2,17 @@
 
 ## Languages
 
+- Add primary implementation languages here.
+
 ## Runtime
 
+- Add runtime and framework notes here.
+
 ## Tooling
 
+- Add build tools, formatters, and other tooling here.
+
 ## Verification Commands
+
+- Add the main verification commands for this project here.
+- Example: `npm run typecheck`, `npm run lint`, `npm test`

package/.codex/memory/_templates/user.md

@@ -2,6 +2,12 @@
 
 ## Preferences
 
+- Add collaboration preferences for this project's user here.
+
 ## Workflow
 
+- Add workflow preferences or operating preferences here.
+
 ## Communication Notes
+
+- Record communication style or response format preferences here.

package/.codex/prompts/resume.md

@@ -8,6 +8,12 @@ agent: build
 
 Pick up where a previous session left off. Recover context, verify state, continue.
 
+> **Two resume paths:**
+> - **Thread-based**: `codex resume` restores a previous Codex session transcript (best for short interruptions within the same thread).
+> - **File-based**: This prompt recovers context from repo-visible files (best for cross-session continuity, different machines, or when thread history is unavailable).
+>
+> Use `codex resume` when you want the exact conversation back. Use this prompt when you need structured context recovery from durable project files.
+
 ## Load Skills
 
 - `$beads`

package/.codex/prompts/search.md

@@ -0,0 +1,78 @@
+---
+description: Search project memory and context for prior decisions, patterns, and knowledge
+argument-hint: "<query> [--limit <n>] [--decisions-only]"
+agent: explore
+---
+
+# Search: $ARGUMENTS
+
+Search durable project memory and context docs for relevant prior knowledge.
+
+## Load Skills
+
+- `$memory-system` — memory file structure and update protocol
+
+## Phase 1: Parse Query
+
+| Argument          | Default | Description                              |
+| ----------------- | ------- | ---------------------------------------- |
+| `<query>`         | required | Search terms (natural language or keywords) |
+| `--limit <n>`     | 5       | Max results to return                    |
+| `--decisions-only`| false   | Restrict to decision-log entries only    |
+
+## Phase 2: Run Search
+
+Execute the local memory search:
+
+```bash
+bash .codex/scripts/memory_search.sh $ARGUMENTS
+```
+
+If the derived index does not exist, it will be built automatically on first run.
+
+## Phase 3: Present Results
+
+For each result:
+
+1. Show the source file path and heading
+2. Show the relevance score and match reasons
+3. Show the snippet (first 180 characters)
+
+If results reference decision-log entries, highlight them separately under "Related Decisions".
+
+## Phase 4: Offer Next Steps
+
+Based on results, suggest:
+
+- Read the full source file for more context
+- Update stale entries if information has changed
+- Create new memory entries if the query topic has no coverage
+
+## Output
+
+```text
+Search: <query>
+━━━━━━━━━━━━━━━━━━━
+
+Results: <n> matches
+
+1. [score=<n>] <path>
+   Heading: <heading>
+   Snippet: <text>
+
+...
+
+Related Decisions:
+  1. <decision heading> — <snippet>
+
+Suggestions:
+  - <next step>
+```
+
+## Related Commands
+
+| Need              | Command                    |
+| ----------------- | -------------------------- |
+| Full audit        | `bash .codex/scripts/audit_memory_hygiene.sh` |
+| Resume session    | `/prompts:resume`          |
+| Project status    | `/prompts:status`          |

package/.codex/scripts/audit_memory_hygiene.sh

@@ -3,9 +3,17 @@ set -euo pipefail
 
 # Script: audit_memory_hygiene
 # Audits context/memory health without mutating repository files.
+# Use --auto-fix to auto-generate worklog archive drafts when budget is exceeded.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
+AUTO_FIX=false
+for arg in "$@"; do
+  case "$arg" in
+    --auto-fix) AUTO_FIX=true ;;
+  esac
+done
+
 WORKLOG="$SCRIPT_DIR/context/worklog.md"
 DECISION_LOG="$SCRIPT_DIR/context/decision-log.md"
 SESSION_CONTEXT="$SCRIPT_DIR/context/session-context.md"
@@ -94,9 +102,66 @@ echo "Counts:"
 printf "INFO     %-28s %s\n" "worklog entries" "$worklog_entries"
 printf "INFO     %-28s %s\n" "decision-log entries" "$decision_count"
 
+echo
+echo "Token budget (context docs, target <4000 tokens):"
+CONTEXT_DIR="$SCRIPT_DIR/context"
+total_tokens=0
+# Only count top-level .md files; context/archive/ is intentionally excluded by the non-recursive glob.
+if [[ -d "$CONTEXT_DIR" ]]; then
+  for ctx_file in "$CONTEXT_DIR"/*.md; do
+    [[ -f "$ctx_file" ]] || continue
+    word_count=$(wc -w < "$ctx_file" 2>/dev/null | tr -d ' ')
+    est_tokens=$(( (word_count * 13 + 9) / 10 ))
+    total_tokens=$((total_tokens + est_tokens))
+  done
+fi
+if [[ "$total_tokens" -le 4000 ]]; then
+  printf "OK       %-28s ~%s tokens (budget: 4000)\n" "context/ total" "$total_tokens"
+else
+  printf "WARN     %-28s ~%s tokens (budget: 4000)\n" "context/ total" "$total_tokens"
+fi
+
+echo
+echo "Staleness checks:"
+STALE_DAYS=30
+now_epoch=$(date +%s)
+for stale_file in "$SESSION_CONTEXT" "$STATE_FILE"; do
+  if [[ -f "$stale_file" ]]; then
+    file_label="${stale_file#$SCRIPT_DIR/}"
+    file_mtime=$(stat -f '%m' "$stale_file" 2>/dev/null || stat -c '%Y' "$stale_file" 2>/dev/null || echo "0")
+    age_days=$(( (now_epoch - file_mtime) / 86400 ))
+    if [[ "$age_days" -ge "$STALE_DAYS" ]]; then
+      printf "WARN     %-28s %s days old (threshold: %s)\n" "$file_label" "$age_days" "$STALE_DAYS"
+    else
+      printf "OK       %-28s %s days old\n" "$file_label" "$age_days"
+    fi
+  fi
+done
+
 echo
 echo "Recommended next actions:"
 echo "- Run .codex/scripts/prepare_worklog_archive.sh <archive-path> if worklog needs pruning."
 echo "- After reviewing both drafts, run .codex/scripts/apply_worklog_archive.sh <archive-draft> <retained-draft> to update worklog.md and save an archive copy."
 echo "- Trim duplicate next-action bullets so session-context.md stays the precise restart cue."
 echo "- Keep only still-relevant durable decisions in decision-log.md."
+echo "- Review stale files (>$STALE_DAYS days) and update or clear outdated content."
+
+# Auto-fix: generate worklog archive drafts if budget is exceeded
+if $AUTO_FIX; then
+  worklog_lines=$(wc -l < "$WORKLOG" 2>/dev/null | tr -d ' ')
+  worklog_lines="${worklog_lines:-0}"
+  if [[ "$worklog_lines" -gt 200 ]]; then
+    archive_draft="/tmp/codexkit-worklog-archive-draft.md"
+    retained_draft="/tmp/codexkit-worklog-retained-draft.md"
+    echo
+    echo "Auto-fix: worklog exceeds 200 lines ($worklog_lines). Generating archive drafts..."
+    "$SCRIPT_DIR/scripts/prepare_worklog_archive.sh" "$archive_draft" 20 --retained-output "$retained_draft"
+    echo "  Archive draft: $archive_draft"
+    echo "  Retained draft: $retained_draft"
+    echo "  Review both, then run:"
+    echo "    bash .codex/scripts/apply_worklog_archive.sh $archive_draft $retained_draft"
+  else
+    echo
+    echo "Auto-fix: worklog is within budget ($worklog_lines/200 lines). No action needed."
+  fi
+fi

package/.codex/scripts/build_startup_brief.sh

@@ -2,9 +2,24 @@
 set -euo pipefail
 # Script: build_startup_brief
 # Generates session startup context and prints to stdout.
+# Also rebuilds the derived memory index if source files have changed.
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
+# Rebuild derived memory index if source files are newer
+INDEX_DB="$SCRIPT_DIR/memory/.index/memory-index.db"
+if [[ -f "$SCRIPT_DIR/scripts/build_memory_index.sh" ]]; then
+  SOURCE_CHANGED=false
+  if [[ ! -f "$INDEX_DB" ]]; then
+    SOURCE_CHANGED=true
+  elif find "$SCRIPT_DIR/context" "$SCRIPT_DIR/memory/project" "$SCRIPT_DIR/memory/research" -type f -name '*.md' -newer "$INDEX_DB" -print -quit 2>/dev/null | grep -q .; then
+    SOURCE_CHANGED=true
+  fi
+  if $SOURCE_CHANGED; then
+    "$SCRIPT_DIR/scripts/build_memory_index.sh" >/dev/null 2>&1 || true
+  fi
+fi
+
 echo "━━━ Startup Brief ━━━"
 
 # Current git branch and status