feat: add context discovery and session management documentation

- Add context-discovery.md with dynamic context loading and manifest indexing
- Add session-management.md with lazy initialization and cleanup policies
- Implement keyword search and delegation patterns for context files
- Define session isolation and error handling strategies

.opencode/context/core/context-discovery.md

@@ -0,0 +1,226 @@
+# Context Discovery
+
+## Purpose
+
+**Dynamically load relevant context files when delegating to subagents**
+
+Allows subagents to discover and access context created earlier in the session, preventing information loss across delegation boundaries.
+
+## How It Works
+
+### 1. Context File Creation
+
+When creating a context file, add metadata to manifest:
+
+```json
+"context_files": {
+  "features/user-auth-context.md": {
+    "created": "2025-01-18T14:30:22Z",
+    "for": "@subagents/core/task-manager",
+    "keywords": ["user-auth", "authentication", "features"]
+  }
+}
+```
+
+**Metadata Fields**:
+- `created`: Timestamp of file creation
+- `for`: Target subagent (which agent will use this)
+- `keywords`: Array of searchable keywords for discovery
+
+### 2. Context Indexing
+
+Manifest maintains keyword index for fast lookup:
+
+```json
+"context_index": {
+  "user-auth": [
+    "features/user-auth-context.md",
+    "tasks/user-auth-tasks.md"
+  ],
+  "api": [
+    "documentation/api-docs-context.md"
+  ]
+}
+```
+
+**Index Structure**:
+- Key: Keyword (from context file metadata)
+- Value: Array of file paths containing that keyword
+
+### 3. Context Discovery Process
+
+When delegating to subagent:
+
+1. **Extract keywords** from user request or task context
+2. **Search manifest** `context_index` for matching keywords
+3. **Find related files** by category or keyword match
+4. **Pass file paths** to subagent in delegation prompt
+5. **Subagent reads** context files as needed
+
+### 4. Delegation Pattern
+
+**Context Reference Format**:
+```
+Related context available at: .tmp/sessions/{session-id}/features/user-auth-context.md
+```
+
+**Full Delegation Example**:
+```
+Delegating to @subagents/code/coder-agent:
+
+"Implement user authentication login component.
+
+Related context available at:
+- .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
+- .tmp/sessions/20250118-143022-a4f2/tasks/user-auth-tasks.md
+
+Read these files for full context on requirements and task breakdown."
+```
+
+## When to Create Context Files
+
+**Only create when ALL of these apply**:
+- Delegating to a subagent
+- Context description is verbose (>2 sentences) OR
+- Risk of misinterpretation without detailed context
+
+**Don't create for**:
+- Simple, one-line instructions
+- Direct execution (no delegation)
+- Conversational questions
+
+## Context File Categories
+
+```
+features/     - Feature development context
+documentation/ - Documentation tasks
+code/         - Code-related tasks
+refactoring/  - Refactoring tasks
+testing/      - Testing tasks
+tasks/        - Task breakdowns created by task-manager
+general/      - General tasks that don't fit other categories
+```
+
+## Context File Template
+
+```markdown
+# Context: {Task Name}
+Session: {session-id}
+
+## Request Summary
+[Brief description of what needs to be done]
+
+## Background
+[Relevant context and information]
+
+## Expected Output
+[What the subagent should produce]
+
+## Constraints
+[Any limitations or requirements]
+
+## Related Context
+[Links to other context files if applicable]
+```
+
+## Discovery Strategies
+
+### By Keyword
+Search `context_index` for exact keyword matches:
+```
+User: "Add login validation"
+Keywords: ["login", "validation", "user-auth"]
+→ Finds: features/user-auth-context.md, tasks/user-auth-tasks.md
+```
+
+### By Category
+Search `context_files` for matching category:
+```
+Delegating to @documentation agent
+Category: "documentation"
+→ Finds all files in documentation/ folder
+```
+
+### By Target Agent
+Search `context_files` for files created for specific agent:
+```
+Delegating to @task-manager
+Filter: "for": "@subagents/core/task-manager"
+→ Finds all context files created for task-manager
+```
+
+## Example Workflow
+
+```
+1. User: "Build user authentication system"
+   → OpenAgent creates: features/user-auth-context.md
+   → Manifest updated with keywords: ["user-auth", "authentication", "features"]
+   → Delegates to @task-manager with context file path
+   
+2. Task-manager creates: tasks/user-auth-tasks.md
+   → Manifest updated with keywords: ["user-auth", "tasks", "breakdown"]
+   → Both files now indexed under "user-auth"
+   
+3. User: "Implement the login component"
+   → OpenAgent searches manifest for "user-auth" OR "login"
+   → Finds: features/user-auth-context.md, tasks/user-auth-tasks.md
+   → Delegates to @coder-agent with references to BOTH files
+   → Coder-agent reads both files to understand full context
+   
+4. User: "Add password reset feature"
+   → OpenAgent searches manifest for "user-auth" OR "password"
+   → Finds existing user-auth context
+   → Creates new: features/password-reset-context.md
+   → Links to existing user-auth context
+   → Delegates with all related context files
+```
+
+## Benefits
+
+✅ **No context loss**: Information persists across subagent calls
+✅ **Automatic discovery**: Related context found by keywords
+✅ **Flexible**: Subagents read only what they need
+✅ **Traceable**: Manifest shows all context relationships
+✅ **Scalable**: Works with multiple context files per session
+✅ **Reusable**: Later tasks can reference earlier context
+
+## Context Inheritance
+
+**Load related context files from manifest before delegating**
+
+When delegating to a subagent:
+1. Check if session exists
+2. Read manifest if available
+3. Search for related context by keyword/category
+4. Include relevant context file paths in delegation
+5. Subagent reads context files as first step
+
+This ensures subagents have full context from earlier in the session.
+
+## Error Handling
+
+### Manifest Not Found
+- Session not initialized yet
+- Continue without context discovery
+- Create new session if context file needed
+
+### Context File Missing
+- File was deleted or moved
+- Warn user about missing context
+- Continue with available context
+- Update manifest to remove missing file
+
+### Keyword Collision
+- Multiple files match same keyword
+- Include all matching files in delegation
+- Let subagent determine relevance
+- Consider more specific keywords in future
+
+## Best Practices
+
+1. **Use specific keywords**: "user-auth" better than "auth"
+2. **Include category in keywords**: ["features", "user-auth"]
+3. **Link related context**: Reference other context files
+4. **Update manifest immediately**: Don't delay indexing
+5. **Clean up stale context**: Remove when task complete
+6. **Validate file exists**: Before passing to subagent

.opencode/context/core/session-management.md

@@ -0,0 +1,144 @@
+# Session Management
+
+## Lazy Initialization
+
+**Only create session when first context file needed**
+
+- Don't create sessions for simple questions or direct execution
+- Initialize on first delegation that requires context file
+- Session ID format: `{timestamp}-{random-4-chars}`
+- Example: `20250118-143022-a4f2`
+
+## Session Structure
+
+```
+.tmp/sessions/{session-id}/
+├── .manifest.json
+├── features/
+│   └── {task-name}-context.md
+├── documentation/
+│   └── {task-name}-context.md
+├── code/
+│   └── {task-name}-context.md
+├── tasks/
+│   └── {task-name}-tasks.md
+└── general/
+    └── {task-name}-context.md
+```
+
+## Session Isolation
+
+**Each session has unique ID - prevents concurrent agent conflicts**
+
+✅ Multiple agent instances can run simultaneously
+✅ No file conflicts between sessions
+✅ Each session tracks only its own files
+✅ Safe cleanup - only deletes own session folder
+
+## Manifest Structure
+
+**Location**: `.tmp/sessions/{session-id}/.manifest.json`
+
+```json
+{
+  "session_id": "20250118-143022-a4f2",
+  "created_at": "2025-01-18T14:30:22Z",
+  "last_activity": "2025-01-18T14:35:10Z",
+  "context_files": {
+    "features/user-auth-context.md": {
+      "created": "2025-01-18T14:30:22Z",
+      "for": "@subagents/core/task-manager",
+      "keywords": ["user-auth", "authentication", "features"]
+    },
+    "tasks/user-auth-tasks.md": {
+      "created": "2025-01-18T14:32:15Z",
+      "for": "@subagents/core/task-manager",
+      "keywords": ["user-auth", "tasks", "breakdown"]
+    }
+  },
+  "context_index": {
+    "user-auth": [
+      "features/user-auth-context.md",
+      "tasks/user-auth-tasks.md"
+    ]
+  }
+}
+```
+
+## Activity Tracking
+
+**Update timestamp after each context file creation or delegation**
+
+- Update `last_activity` field in manifest
+- Used for stale session detection
+- Helps identify active vs abandoned sessions
+
+## Cleanup Policy
+
+### Manual Cleanup (Preferred)
+**Ask user confirmation before cleanup**
+
+After task completion:
+1. Ask: "Should I clean up temporary session files at `.tmp/sessions/{session-id}/`?"
+2. Wait for user confirmation
+3. Only delete files tracked in current session's manifest
+4. Remove entire session folder: `.tmp/sessions/{session-id}/`
+
+### Safety Rules
+- **NEVER** delete files outside current session
+- **ONLY** delete files tracked in manifest
+- **ALWAYS** confirm with user before cleanup
+
+### Stale Session Cleanup
+**Auto-remove sessions >24 hours old**
+
+- Check `last_activity` timestamp in manifest
+- Safe to run periodically (see `scripts/cleanup-stale-sessions.sh`)
+- Won't affect active sessions
+
+## Error Handling
+
+### Subagent Failure
+- Report error to user
+- Ask if should retry or abort
+- Don't auto-retry without approval
+
+### Context File Error
+- Fall back to inline context in delegation prompt
+- Warn user that context file creation failed
+- Continue with task if possible
+
+### Session Creation Error
+- Continue without session
+- Warn user
+- Use inline context for delegation
+- Don't block task execution
+
+## Best Practices
+
+1. **Lazy Init**: Only create session when actually needed
+2. **Track Everything**: Add all context files to manifest
+3. **Update Activity**: Touch `last_activity` on each operation
+4. **Clean Promptly**: Remove files after task completion
+5. **Isolate Sessions**: Never access files from other sessions
+6. **Confirm Cleanup**: Always ask user before deleting
+
+## Example Workflow
+
+```bash
+# User: "Build user authentication system"
+# → Complex task, needs context file
+# → Create session: 20250118-143022-a4f2
+# → Create: .tmp/sessions/20250118-143022-a4f2/features/user-auth-context.md
+# → Delegate to @task-manager
+
+# User: "Implement login component"
+# → Same session, add context
+# → Create: .tmp/sessions/20250118-143022-a4f2/code/login-context.md
+# → Delegate to @coder-agent
+
+# Task complete
+# → Ask: "Clean up session files?"
+# → User confirms
+# → Delete: .tmp/sessions/20250118-143022-a4f2/
+```