Merge remote-tracking branch 'origin/bracket-nonsense'

# Conflicts:
#	plugin/scripts/search-server.cjs
This commit is contained in:
Alex Newman
2025-11-30 22:59:50 -05:00
13 changed files with 217 additions and 194 deletions
File diff suppressed because one or more lines are too long
+4 -4
View File
@@ -98,9 +98,9 @@ curl "http://localhost:37777/api/prompt/5421"
**Filters (optional):**
- `type` - Filter to "observations", "sessions", or "prompts"
- `project` - Filter by project name
- `dateRange[start]` - Start date (YYYY-MM-DD)
- `dateRange[end]` - End date (YYYY-MM-DD)
- `obs_type` - Filter observations by: bugfix, feature, decision, discovery, change
- `dateStart` - Start date (YYYY-MM-DD or epoch timestamp)
- `dateEnd` - End date (YYYY-MM-DD or epoch timestamp)
- `obs_type` - Filter observations by type (comma-separated): bugfix, feature, decision, discovery, change
## Examples
@@ -111,7 +111,7 @@ curl "http://localhost:37777/api/search?query=bug&type=observations&obs_type=bug
**Find what happened last week:**
```bash
curl "http://localhost:37777/api/search?query=&type=observations&dateRange[start]=2025-11-11&format=index&limit=10"
curl "http://localhost:37777/api/search?query=&type=observations&dateStart=2025-11-11&format=index&limit=10"
```
**Search everything:**
@@ -28,7 +28,7 @@ curl -s "http://localhost:37777/api/search/by-concept?concept=discovery&format=i
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -24,7 +24,7 @@ curl -s "http://localhost:37777/api/search/by-file?filePath=src/services/worker-
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -118,7 +118,7 @@ Response: "No observations found for 'nonexistent.ts'. Try a partial path or che
1. Use format=index first to see overview of all changes
2. Start with partial paths (e.g., filename only) for broader matches
3. Use full paths when you need specific file matches
4. Combine with dateRange to see recent changes: `?filePath=worker.ts&dateRange[start]=2024-11-01`
4. Combine with dateStart to see recent changes: `?filePath=worker.ts&dateStart=2024-11-01`
5. Use directory searches to see all work in a module
**Token Efficiency:**
@@ -27,7 +27,7 @@ curl -s "http://localhost:37777/api/search/by-type?type=bugfix&format=index&limi
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -114,7 +114,7 @@ Fix: Use one of the valid type values
1. Use format=index first to see overview
2. Start with limit=5-10 to avoid token overload
3. Combine with dateRange for recent work: `?type=bugfix&dateRange[start]=2024-11-01`
3. Combine with dateStart for recent work: `?type=bugfix&dateStart=2024-11-01`
4. Use project filtering when working on one codebase
**Token Efficiency:**
@@ -186,7 +186,7 @@ Then choose anchor manually.
1. **Combine filters** for precision:
```bash
curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&dateRange[start]=2024-11-01&format=index&limit=10"
curl -s "http://localhost:37777/api/search/observations?query=authentication&type=feature&dateStart=2024-11-01&format=index&limit=10"
```
2. **Review filtered results**
@@ -207,7 +207,7 @@ Found 10 authentication features added in November:
**Why this workflow:**
- Multiple filters narrow results before requesting full details
- Type + query + dateRange = precise targeting
- Type + query + dateStart/dateEnd = precise targeting
- Progressive disclosure: index first, full details selectively
---
@@ -228,7 +228,7 @@ Found 10 authentication features added in November:
1. **Start with index format** - Always use `format=index` first
2. **Use specialized tools** - by-type, by-file, by-concept when applicable
3. **Compose operations** - Combine search + timeline for investigations
4. **Filter early** - Use type, dateRange, project to narrow before expanding
4. **Filter early** - Use type, dateStart/dateEnd, project to narrow before expanding
5. **Progressive disclosure** - Load full details only for relevant items
## Token Budget Awareness
+3 -3
View File
@@ -106,9 +106,9 @@ Many endpoints share these parameters:
- **limit**: Number of results to return
- **offset**: Number of results to skip (for pagination)
- **project**: Filter by project name
- **dateRange**: Filter by date range
- `dateRange[start]`: Start date (ISO string or epoch)
- `dateRange[end]`: End date (ISO string or epoch)
- **dateStart/dateEnd**: Filter by date range
- `dateStart`: Start date (YYYY-MM-DD or epoch timestamp)
- `dateEnd`: End date (YYYY-MM-DD or epoch timestamp)
## Error Handling
@@ -21,12 +21,12 @@ curl -s "http://localhost:37777/api/search/observations?query=authentication&for
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional) - `dateRange[start]` and/or `dateRange[end]`
- **obs_type**: Filter by observation type: bugfix, feature, refactor, decision, discovery, change (optional)
- **concepts**: Filter by concept tags (optional)
- **files**: Filter by file paths (optional)
- **dateStart/dateEnd**: Filter by date range (optional) - `dateStart` and/or `dateEnd` (YYYY-MM-DD format or epoch timestamp)
- **obs_type**: Filter by observation type (comma-separated): bugfix, feature, refactor, decision, discovery, change (optional)
- **concepts**: Filter by concept tags (comma-separated, optional)
- **files**: Filter by file paths (comma-separated, optional)
**Important**: When omitting `query`, you MUST provide at least one filter (project, dateRange, obs_type, concepts, or files)
**Important**: When omitting `query`, you MUST provide at least one filter (project, dateStart/dateEnd, obs_type, concepts, or files)
## When to Use Each Format
@@ -88,13 +88,13 @@ Search without query text (direct SQLite filtering):
```bash
# Get all observations from November 2025
curl -s "http://localhost:37777/api/search?type=observations&dateRange[start]=2025-11-01&format=index"
curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-01&format=index"
# Get all bug fixes from a specific project
curl -s "http://localhost:37777/api/search?type=observations&obs_type=bugfix&project=api-server&format=index"
# Get all observations from last 7 days
curl -s "http://localhost:37777/api/search?type=observations&dateRange[start]=2025-11-11&format=index"
curl -s "http://localhost:37777/api/search?type=observations&dateStart=2025-11-11&format=index"
```
## Error Handling
@@ -103,7 +103,7 @@ curl -s "http://localhost:37777/api/search?type=observations&dateRange[start]=20
```json
{"error": "Either query or filters required for search"}
```
Fix: Provide either a query parameter OR at least one filter (project, dateRange, obs_type, concepts, files)
Fix: Provide either a query parameter OR at least one filter (project, dateStart/dateEnd, obs_type, concepts, files)
**No results found:**
```json
@@ -21,7 +21,7 @@ curl -s "http://localhost:37777/api/search/prompts?query=authentication&format=i
- **format**: "index" (truncated prompts) or "full" (complete prompt text). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -99,7 +99,7 @@ Response: "No user prompts found for 'foobar'. Try different search terms."
1. Use exact phrases in quotes: `?query="how do I"` for precise matches
2. Start with format=index to see preview, then get full text if needed
3. Use dateRange to find recent questions: `?query=bug&dateRange[start]=2024-11-01`
3. Use dateStart to find recent questions: `?query=bug&dateStart=2024-11-01`
4. Prompts show what was asked, sessions/observations show what was done
5. Combine with session search to see both question and answer
@@ -21,7 +21,7 @@ curl -s "http://localhost:37777/api/search/sessions?query=authentication&format=
- **format**: "index" (summary) or "full" (complete details). Default: "full"
- **limit**: Number of results (default: 20, max: 100)
- **project**: Filter by project name (optional)
- **dateRange**: Filter by date range (optional)
- **dateStart/dateEnd**: Filter by date range (optional)
## When to Use Each Format
@@ -102,7 +102,7 @@ Response: "No sessions found for 'foobar'. Try different search terms."
1. Be specific: "JWT authentication implementation" > "auth"
2. Start with format=index and limit=5-10
3. Use dateRange for recent sessions: `?query=auth&dateRange[start]=2024-11-01`
3. Use dateStart for recent sessions: `?query=auth&dateStart=2024-11-01`
4. Sessions provide high-level overview, observations provide details
5. Use project filtering when working on one codebase
@@ -69,7 +69,7 @@ curl -s "http://localhost:37777/api/search/observations?query=authentication&for
### Step 4: Refine with Filters (If Needed)
**Techniques:**
- Use `type`, `dateRange`, `concepts`, `files` filters
- Use `type`, `dateStart`/`dateEnd`, `concepts`, `files` filters
- Narrow scope BEFORE requesting more results
- Use `offset` for pagination instead of large limits