Prepare pi-codecks 0.14.1: scoped searches and child counts

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## [0.14.1] - 2026-09-28
+
+### Changed
+
+- Filter paged card searches by resolved Deck ID at the server while still checking Deck and milestone scopes locally. Deck-scoped scan limits now count server-returned Deck cards; milestone-only searches still scan token-visible account cards.
+- Request `count:childCards` for card-search and effort-preview summaries instead of fetching child references just to count them. Full detail views still fetch children, and count-only search output retains its facets. Missing or invalid counts remain unknown rather than observed zero; previously ambiguous missing child data could appear as zero.
+
+### Fixed
+
+- Preserve bounded permission/query diagnostics and scan progress on rejected scoped card pages without retrying a broader query or exposing earlier rows.
+- Order optional diagnostic relation probes with supported fields and reject unsupported probes locally instead of sending invalid pagination.
+
 ## [0.14.0] - 2026-09-28
 
 ### Added

README.md

@@ -188,7 +188,7 @@ Use `codecks_card_get_batch` for full details of 1-25 known short-code and/or `s
 
 Use `codecks_card_get_formatted` when the agent needs to present human-readable card details to a user.
 
-Use `codecks_card_search` when title/location criteria may match multiple cards and the agent needs disambiguation. Supplying `deck` or `milestone` without `location` infers the corresponding scope instead of running a broad search. Deck and milestone filters can be combined for intersection searches such as cards in the Alpha milestone and Dev deck. If an agent accidentally passes a visible deck name such as `Design Docs` or `Vertical Slice` as `location`, the registration layer treats it as `deck` when no explicit deck/milestone was supplied. Title searches support `*` / `?` glob wildcards and accent/punctuation-insensitive matching. Use `text` with `searchIn: "title_or_content"` (or `content`) for body searches, and `includeDone: false` for open/undone-only searches. Structured search results include planning metadata such as effort, card type, child count, deck/milestone identity, matched fields, update dates, and reusable `cardRef` / `accountSeqRef` values when Codecks returns those fields. Bounded scans report `scannedCards`, `complete`, `scanLimitReached`, request count, queue wait, and elapsed time. `complete` means complete only within token-visible projects, not necessarily the organization; invisible cards are not deleted cards. Account scans are concurrency-bounded: do not launch parallel full-account or high-`scanLimit` searches; prefer one shared-scope bulk preview or narrow sequential searches. Search output defaults to compact mode and caps returned card rows to protect session context; use `outputMode: "counts"` for bulk scope/effort analysis and `outputMode: "detailed"` only when every returned card row is truly needed. No-match searches return successful empty results with search tips instead of tool errors.
+Use `codecks_card_search` when title/location criteria may match multiple cards and the agent needs disambiguation. Supplying `deck` or `milestone` without `location` infers the corresponding scope instead of running a broad search. Deck and milestone filters can be combined for intersection searches such as cards in the Alpha milestone and Dev deck. If an agent accidentally passes a visible deck name such as `Design Docs` or `Vertical Slice` as `location`, the registration layer treats it as `deck` when no explicit deck/milestone was supplied. Title searches support `*` / `?` glob wildcards and accent/punctuation-insensitive matching. Use `text` with `searchIn: "title_or_content"` (or `content`) for body searches, and `includeDone: false` for open/undone-only searches. Structured search results include planning metadata such as effort, card type, child count, deck/milestone identity, matched fields, update dates, and reusable `cardRef` / `accountSeqRef` values when Codecks returns those fields. Bounded scans report `scannedCards`, `complete`, `scanLimitReached`, request count, queue wait, and elapsed time. `complete` means complete only within token-visible projects, not necessarily the organization; invisible cards are not deleted cards. Account scans are concurrency-bounded: do not launch parallel full-account or high-`scanLimit` searches; prefer one shared-scope bulk preview or narrow sequential searches. Search output defaults to compact mode and caps returned card rows to protect session context; use `outputMode: "counts"` for bulk scope/effort analysis and `outputMode: "detailed"` only when every returned card row is truly needed. No-match searches return successful empty results with search tips instead of tool errors. Deck-scoped paged account-card searches now send the resolved deck ID to Codecks and verify returned deck relations locally; `scanLimit` counts server-returned deck rows, not all account cards. A combined Deck + milestone search sends only the Deck filter and checks the milestone locally; milestone-only searches still scan token-visible account cards. A rejected scoped query fails rather than silently falling back to a broad scan. Compact search and missing-effort summaries request the numeric child-card count rather than child identities; zero is reported only when observed, and a missing or invalid aggregate remains unknown. `outputMode: "counts"` still calculates all its facets across scanned cards. Full card detail reads continue to fetch child cards.
 
 Use `codecks_card_bulk_create` and `codecks_card_bulk_update` for CSV/import-style tracker work after mapping source rows into strict card objects. Both default to dry-run and apply must pass that dry run's `previewFingerprint` as `expectedPreviewFingerprint`; a matching authorization covers the matching apply without another interaction, but ask again when the preview differs or exceeds the approved scope. Unsupported fields are rejected before requests; use `assigneeId` from `codecks_user_lookup`, not `assignee`. After approval, submit one bulk operation: the package paces every physical request at 40 requests per five seconds, so do not manually chunk records or count requests.
 

docs/resolvable-inbox-heuristics.md

@@ -99,4 +99,4 @@ Enable debug tools and use:
 - `codecks_debug_logged_in_user_resolvable_participation`
 - `codecks_debug_logged_in_user_resolvables`
 
-These tools are intended for low-frequency diagnostics only.
+These tools are intended for low-frequency diagnostics only. Optional relation probes paginate only schema-confirmed sortable has-many relations; unsupported, single-row, or array-backed relations report a local unsupported probe result instead of sending an invalid `$limit` query. Probe failures do not establish that a user has no notifications or participants.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-codecks",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Pi tools, skills, and prompts for safe Codecks project-management workflows.",
   "type": "module",
   "license": "MIT",

skills/using-codecks/references/card-operations.md

@@ -22,9 +22,9 @@ Read this reference for card lookup, creation, ordinary updates, lifecycle chang
 ## Search
 
 - `codecks_card_search` excludes archived/deleted cards by default; set `includeArchived=true` only when explicitly needed.
-- Supplying a Deck or milestone without `location` infers that scope. Deck and milestone may be combined for an intersection.
+- Supplying a Deck or milestone without `location` infers that scope. Deck-scoped paged account-card searches push the resolved Deck ID to the server, then defensively verify each result; `scanLimit` counts returned Deck rows. Deck + milestone intersections push only the Deck filter and verify the milestone locally; milestone-only searches still scan token-visible account cards. A rejected scoped query never falls back to a broad scan.
 - `title` supports partial and glob-style `*`/`?` matching. Use `text` with `searchIn: "title_or_content"` or `"content"` for bodies.
-- Compact output is the default. Prefer `outputMode: "counts"` for aggregate analysis and `"detailed"` only when every row is required.
+- Compact output is the default. Prefer `outputMode: "counts"` for multifacet analysis and `"detailed"` only when every row is required. Summary child counts use a numeric aggregate without fetching child identities; absent or invalid counts remain unknown rather than zero. Full detail reads retain child-card relations.
 - No-match results are successful empty searches. Inspect criteria/tips rather than treating them as failures.
 - For open/undone cards, use `includeDone=false` instead of post-filtering done cards.
 - Do not launch parallel full-account or high-`scanLimit` searches. Treat `complete=false`, cancellation, timeout, or queue rejection as incomplete evidence, never a definitive empty result.