docs: Update all search API documentation for simplified parameters
Update all documentation to reflect the new simplified URL parameter format: - Replace dateRange[start]/dateRange[end] with dateStart/dateEnd - Clarify that concepts, files, and obs_type accept comma-separated values - Update all code examples in skill documentation - Update comments in search-server.ts Files updated: - SKILL.md - Main skill documentation - operations/*.md - 8 operation guides (observations, prompts, sessions, by-file, by-type, by-concept, common-workflows, help) - principles/progressive-disclosure.md - Design pattern doc - src/servers/search-server.ts - Code comment All examples now use clean URLs without bracket encoding: - Old: ?dateRange[start]=2025-11-01&concepts[]=decision - New: ?dateStart=2025-11-01&concepts=decision 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Alex Newman
@@ -543,7 +543,7 @@ Search workflow:
|
||||
1. Initial search: Use default (index) format to see titles, dates, and sources
|
||||
2. Review results: Identify which items are most relevant to your needs
|
||||
3. Deep dive: Only then use format: "full" on specific items of interest
|
||||
4. Narrow down: Use filters (type, dateRange, concepts, files) to refine results
|
||||
4. Narrow down: Use filters (type, dateStart/dateEnd, concepts, files) to refine results
|
||||
|
||||
Other tips:
|
||||
\u2022 To search by concept: Use find_by_concept tool
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -127,7 +127,7 @@ Search workflow:
|
||||
1. Initial search: Use default (index) format to see titles, dates, and sources
|
||||
2. Review results: Identify which items are most relevant to your needs
|
||||
3. Deep dive: Only then use format: "full" on specific items of interest
|
||||
4. Narrow down: Use filters (type, dateRange, concepts, files) to refine results
|
||||
4. Narrow down: Use filters (type, dateStart/dateEnd, concepts, files) to refine results
|
||||
|
||||
Other tips:
|
||||
• To search by concept: Use find_by_concept tool
|
||||
|
||||
Reference in New Issue
Block a user