feat: add pagination support with --limit and --offset flags

- Add --limit flag to control number of results (default: 20)
- Add --offset flag for pagination (skip N results)
- Include pagination metadata in JSON response
- Support page navigation with has_next/has_previous indicators
- Update help examples to demonstrate pagination usage
- Enables LLMs to access all search results, not just first 20

Made-with: Cursor

Author: lukegalbraithrussell

cmd/docs/docs.go

@@ -32,6 +32,8 @@ import (
 
 var searchMode bool
 var outputFormat string
+var searchLimit int
+var searchOffset int
 
 func NewCommand(clients *shared.ClientFactory) *cobra.Command {
 	cmd := &cobra.Command{
@@ -52,8 +54,12 @@ func NewCommand(clients *shared.ClientFactory) *cobra.Command {
 				Command: "docs --search \"Block Kit\" --output=json",
 			},
 			{
-				Meaning: "Search and open in browser (default)",
-				Command: "docs --search \"Block Kit\" --output=browser",
+				Meaning: "Search with custom limit",
+				Command: "docs --search \"Block Kit\" --output=json --limit=50",
+			},
+			{
+				Meaning: "Search with pagination",
+				Command: "docs --search \"Block Kit\" --output=json --limit=20 --offset=20",
 			},
 		}),
 		RunE: func(cmd *cobra.Command, args []string) error {
@@ -63,6 +69,8 @@ func NewCommand(clients *shared.ClientFactory) *cobra.Command {
 
 	cmd.Flags().BoolVar(&searchMode, "search", false, "search Slack docs with optional query")
 	cmd.Flags().StringVar(&outputFormat, "output", "browser", "output format: browser, json")
+	cmd.Flags().IntVar(&searchLimit, "limit", 20, "maximum number of results to return")
+	cmd.Flags().IntVar(&searchOffset, "offset", 0, "number of results to skip (for pagination)")
 
 	return cmd
 }
@@ -85,7 +93,7 @@ func findDocsRepo() string {
 // runProgrammaticSearch executes the local search
 func runProgrammaticSearch(query string, docsPath string) (*ProgrammaticSearchOutput, error) {
 	contentDir := filepath.Join(docsPath, "content")
-	return search.SearchDocs(query, "", 20, contentDir)
+	return search.SearchDocs(query, "", searchLimit, searchOffset, contentDir)
 }
 
 // runDocsCommand opens Slack developer docs in the browser or performs programmatic search

internal/search/search.go

@@ -37,11 +37,21 @@ type SearchResult struct {
 
 // SearchResponse represents the complete search response
 type SearchResponse struct {
-	Query   string         `json:"query"`
-	Filter  string         `json:"filter"`
-	Results []SearchResult `json:"results"`
-	Total   int            `json:"total"`
-	Showing int            `json:"showing"`
+	Query      string          `json:"query"`
+	Filter     string          `json:"filter"`
+	Results    []SearchResult  `json:"results"`
+	Total      int             `json:"total"`
+	Showing    int             `json:"showing"`
+	Pagination *PaginationInfo `json:"pagination,omitempty"`
+}
+
+// PaginationInfo provides pagination metadata
+type PaginationInfo struct {
+	Limit      int  `json:"limit"`
+	Offset     int  `json:"offset"`
+	Page       int  `json:"page"`        // 1-based page number
+	HasNext    bool `json:"has_next"`
+	HasPrevious bool `json:"has_previous"`
 }
 
 // FrontMatter represents the YAML frontmatter in markdown files
@@ -302,7 +312,7 @@ func findMarkdownFiles(dir string) ([]string, error) {
 }
 
 // SearchDocs performs a programmatic search of documentation files
-func SearchDocs(query, filter string, limit int, contentDir string) (*SearchResponse, error) {
+func SearchDocs(query, filter string, limit, offset int, contentDir string) (*SearchResponse, error) {
 	if contentDir == "" {
 		return nil, fmt.Errorf("content directory not specified")
 	}
@@ -385,22 +395,48 @@ func SearchDocs(query, filter string, limit int, contentDir string) (*SearchResp
 		return results[i].Score > results[j].Score
 	})
 
-	// Limit results
+	// Apply pagination
 	total := len(results)
+	
+	// Handle offset
+	if offset >= total {
+		results = []SearchResult{} // No results if offset too high
+	} else if offset > 0 {
+		results = results[offset:]
+	}
+	
+	// Handle limit
 	if limit > 0 && limit < len(results) {
 		results = results[:limit]
 	}
-
+	
 	if filter == "" {
 		filter = "all"
 	}
 
+	// Calculate pagination info
+	var pagination *PaginationInfo
+	if limit > 0 {
+		page := (offset / limit) + 1
+		hasNext := offset+len(results) < total
+		hasPrevious := offset > 0
+		
+		pagination = &PaginationInfo{
+			Limit:       limit,
+			Offset:      offset,
+			Page:        page,
+			HasNext:     hasNext,
+			HasPrevious: hasPrevious,
+		}
+	}
+
 	response := &SearchResponse{
-		Query:   query,
-		Filter:  filter,
-		Results: results,
-		Total:   total,
-		Showing: len(results),
+		Query:      query,
+		Filter:     filter,
+		Results:    results,
+		Total:      total,
+		Showing:    len(results),
+		Pagination: pagination,
 	}
 
 	return response, nil