updates

Author: tmelliottjr

README.md

@@ -796,54 +796,64 @@ Options are:
 <summary>Projects</summary>
 
 - **project_read** - Read project information
-  - `after`: Forward pagination cursor. Use ONLY if the previous response pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep query, fields, and per_page identical for every page. (string, optional)
+  - `after`: Forward pagination cursor. Use when the previous response's pageInfo.hasNextPage=true. Supply pageInfo.nextCursor as 'after' and immediately request the next page. LOOP UNTIL pageInfo.hasNextPage=false (don't stop early). Keep query, fields, and per_page identical for every page. (string, optional)
   - `before`: Backward pagination cursor (rare): supply to move to the preceding page using pageInfo.prevCursor. Not needed for normal forward iteration. (string, optional)
   - `field_id`: Field ID (required for get_project_field) (number, optional)
   - `fields`: Field IDs to include (e.g. ["102589", "985201"]). CRITICAL: Always provide to get field values. Without this, only titles returned. Get IDs from list_project_fields first. (string[], optional)
   - `item_id`: Item ID (required for get_project_item) (number, optional)
   - `method`: Read operation: get_project, list_projects, get_project_field, list_project_fields (call FIRST for IDs), get_project_item, list_project_items (use query + fields) (string, required)
   - `owner`: GitHub username or org name (case-insensitive) (string, required)
   - `owner_type`: Owner type: 'user' or 'org' (string, required)
-  - `per_page`: Results per page (max 20). Keep constant across paginated requests; changing mid-sequence can complicate page traversal. (number, optional)
+  - `per_page`: Results per page (max 50). Keep constant across paginated requests; changing mid-sequence can complicate page traversal. (number, optional)
   - `project_number`: Project number (required for most methods) (number, optional)
-  - `query`: Query string to filter project items (highly recommended for list_project_items).
-		CRITICAL: Always include this when calling list_project_items.
-		
-		list_project_items instructions:
-
-		Derive the query from the user's natural language intent BEFORE invoking the tool. Map phrases directly:
-		- "open issues" => state:open is:issue
-		- "merged PRs" => state:merged is:pr
-		- "assigned to me" => assignee:@me is:issue
-		- "high priority bugs" => state:open is:issue label:bug priority:high
-		- "review-ready PRs" => is:pr status:"Ready for Review"
-
-		Content Type:
-		- Issues: is:issue
-		- Pull requests: is:pr (or is:pull-request)
-		Without one you'll get mixed types.
-
-		Logical Combination:
-		- Space-separated qualifiers = AND
-		- Commas inside a single qualifier = OR (label:bug,critical)
-		- Negation with leading dash: -label:wontfix
-
-		Format Rules:
-		- Qualifiers with spaces use hyphens: sprint-name, team-name, parent-issue
-		- Values with spaces use quotes: sprint-name:"Q1 Planning" status:"In Review"
-		- Single word values: no quotes (state:open priority:high)
-
-		Examples:
-		- state:open is:issue sprint-name:"Q1 Planning"
-		- is:pr team-name:"Backend Team" status:"In Review"
-		- parent-issue:"github/repo#123"
-
-		Common Filters:
-		is:issue/pr state:open/closed/merged assignee:@me/username label:name status:value priority:p1 updated:>@today-7d title:*text* -label:wontfix label:bug,critical priority:1..3 no:assignee has:label iteration:@current
-
-		Pagination:
-		When pageInfo.hasNextPage=true, use after=nextCursor to request the next page. Keep query, fields, and per_page identical for every page. Repeat until pageInfo.hasNextPage=false.
-		 (string, optional)
+  - `query`: Query string (used ONLY with list_projects and list_project_items). 
+
+Pattern Split:
+
+1. list_projects (project metadata only):
+   Scope: title text + open/closed state.
+   PERMITTED qualifiers: is:open, is:closed (state), simple title terms.
+   FORBIDDEN: is:issue, is:pr, assignee:, label:, status:, sprint-name:, parent-issue:, team-name:, priority:, etc.
+   Examples:
+     - roadmap is:open
+     - is:open feature planning
+   Reject & switch method if user intends items.
+
+2. list_project_items (issues / PRs inside ONE project):
+   MUST reflect user intent; strongly prefer explicit content type if narrowed:
+     - "open issues" → state:open is:issue
+     - "merged PRs" → state:merged is:pr
+     - "items updated this week" → updated:>@today-7d (omit type only if mixed desired)
+   Query Construction Heuristics:
+     a. Extract type nouns: issues → is:issue | PRs, Pulls, or Pull Requests → is:pr | tasks/tickets → is:issue (ask if ambiguity)
+     b. Map temporal phrases: "this week" → updated:>@today-7d
+     c. Map negations: "excluding wontfix" → -label:wontfix
+     d. Map priority adjectives: "high/sev1/p1" → priority:high OR priority:p1 (choose based on field presence)
+     e. Map blocking relations: "blocked by 123" → parent-issue:"owner/repo#123"
+
+Syntax Essentials (items):
+   AND: space-separated.
+   OR: comma inside one qualifier (label:bug,critical).
+   NOT: leading '-' (-label:wontfix).
+   Hyphenate multi-word field names.
+   Quote multi-word values.
+   Ranges: points:1..3, updated:<@today-30d.
+   Wildcards: title:*crash*, label:bug*.
+
+Common Qualifier Glossary (items):
+   is:issue | is:pr | state:open|closed|merged | assignee:@me|username | label:NAME | status:VALUE |
+   priority:p1|high | sprint-name:@current | team-name:"Backend Team" | parent-issue:"org/repo#123" |
+   updated:>@today-7d | title:*text* | -label:wontfix | label:bug,critical | no:assignee | has:label
+
+Pagination Mandate:
+   Do not analyze until ALL pages fetched (loop while pageInfo.hasNextPage=true). Always reuse identical query, fields, per_page.
+
+Recovery Guidance:
+   If user provides ambiguous request ("show project activity") → ask clarification OR return mixed set (omit is:issue/is:pr). If user mixes project + item qualifiers in one phrase → split: run list_projects for discovery, then list_project_items for detail.
+
+Never:
+   - Infer field IDs; fetch via list_project_fields.
+   - Drop 'fields' param on subsequent pages if field values are needed. (string, optional)
 
 - **project_write** - Modify project items
   - `item_id`: For add: issue/PR ID. For update/delete: project item ID (not issue/PR ID) (number, required)