Make cache-backed resource materialization concurrency-safe

apps/docs/api-reference/local/clear.mdx

@@ -1,6 +1,8 @@
 ---
-title: 'Clear cached resources'
+title: 'Clear cached BTCA resource data'
 openapi: 'POST /clear'
 ---
 
-Clears all locally cached resource clones.
+Clears cache-backed BTCA resource data, including git mirrors, temporary anonymous git caches, npm caches, temporary anonymous npm caches, and leftover legacy cache directories.
+
+This operation is lock-aware: it waits for active clear/resource locks and can reclaim stale locks before removing cached data.

apps/docs/api-reference/openapi.local.json

@@ -277,7 +277,8 @@
 		},
 		"/clear": {
 			"post": {
-				"summary": "Clear cached resource clones",
+				"summary": "Clear cached BTCA resource data",
+				"description": "Clears cache-backed BTCA resource data, including git mirrors, temporary anonymous git caches, npm caches, temporary anonymous npm caches, and leftover legacy cache directories. The operation is lock-aware and waits for active clear/resource locks, reclaiming stale locks when needed.",
 				"responses": {
 					"200": {
 						"description": "Clear result",
@@ -614,7 +615,8 @@
 				"required": ["cleared"],
 				"properties": {
 					"cleared": {
-						"type": "integer"
+						"type": "integer",
+						"description": "Number of cache directories removed."
 					}
 				}
 			}

apps/docs/btca.spec.md

@@ -313,7 +313,12 @@ Behavior:
 
 ### 4.11 `btca clear`
 
-Clears all locally cloned resources.
+Clears cache-backed BTCA resource data, not just git clones.
+
+Behavior:
+
+- Removes cached git mirrors, temporary anonymous git caches, npm cache directories, temporary anonymous npm caches, and leftover legacy cache directories
+- Uses the same lock-aware clearing flow as the local `/clear` endpoint so active resource work drains safely before cache data is removed
 
 ### 4.12 `btca serve`
 
@@ -534,14 +539,18 @@ Response:
 
 ### 6.11 `POST /clear`
 
-Clears all cached resource clones.
+Clears cache-backed BTCA resource data, including git mirrors, temporary anonymous git caches, npm caches, temporary anonymous npm caches, and leftover legacy cache directories.
+
+The operation is lock-aware: it waits for active clear/resource locks and can reclaim stale locks before removing cached data.
 
 Response:
 
 ```json
 { "cleared": 5 }
 ```
 
+`cleared` is the number of cache directories removed.
+
 ---
 
 ## 7. Streaming SSE Spec (`/question/stream`)

apps/docs/guides/cli-reference.mdx

@@ -124,7 +124,7 @@ You can also pass raw HTTPS git URLs directly instead of a configured resource n
 
 - They are normalized (for example, GitHub `.../blob/main/...` URLs become the base repo URL).
 - They use a short-lived cache key derived from a hash of the URL.
-- They are cloned into a temporary folder under `.tmp` and removed after the request finishes.
+- They are cloned into a unique BTCA-managed temp directory under the configured data directory (for example `.tmp/btca-anon-git-*`) and removed after the request finishes.
 - Branch detection tries `main`, then `master`, then `trunk`, then `dev`.
 - If none of those branches exist, the request fails with an instruction to add the repo as a named resource instead.
 
@@ -224,7 +224,13 @@ Behavior: Creates `btca.config.jsonc` and prompts for storage mode (`local` `.bt
 
 ## `btca clear`
 
-Clears all locally cloned resources.
+Clears cache-backed BTCA resource data, not just git clones.
+
+Behavior:
+
+- Removes cached git mirrors, temporary anonymous git caches, npm cache directories, temporary anonymous npm caches, and leftover legacy cache directories.
+- Uses a lock-aware clear flow so active resource work drains before cached data is removed.
+- Reclaims stale cache locks when needed before removing cached data.
 
 ## `btca wipe`
 

apps/docs/package.json

@@ -2,9 +2,9 @@
 	"name": "@btca/docs",
 	"private": true,
 	"scripts": {
-		"dev": "mint dev",
+		"dev": "bunx mint dev",
 		"format": "prettier --write .",
-		"check": "mint validate --disable-openapi && mint openapi-check api-reference/openapi.local.json && mint openapi-check api-reference/openapi.cloud.json"
+		"check": "bunx mint validate --disable-openapi && bunx mint openapi-check api-reference/openapi.local.json && bunx mint openapi-check api-reference/openapi.cloud.json"
 	},
 	"dependencies": {},
 	"devDependencies": {

apps/server/README.md

@@ -94,7 +94,7 @@ Remove a resource by name.
 POST /clear
 ```
 
-Clear all locally cloned resources.
+Clear BTCA-managed local resource caches, including named git mirrors, temporary anonymous git caches, and npm caches.
 
 ### Questions
 

apps/server/src/agent/agent.test.ts

@@ -146,7 +146,6 @@ describe('Agent', () => {
 						name: 'docs',
 						fsName: 'docs',
 						type: 'local',
-						path: '/docs',
 						repoSubPaths: [],
 						loadedAt: new Date().toISOString()
 					}
@@ -194,7 +193,6 @@ describe('Agent', () => {
 						name: 'docs',
 						fsName: 'docs',
 						type: 'local',
-						path: '/docs',
 						repoSubPaths: [],
 						loadedAt: new Date().toISOString()
 					}