@nestr/mcp 0.1.105 → 0.1.107

package/build/help/topics.js

@@ -20,7 +20,8 @@ The internal topics below are curated MCP-flavoured guidance — tool call patte
 - core-concepts: Workspace, nest, circle, role, label basics and content format
 - nest-model: Nest fields, hierarchy, hints, and fieldsMetaData
 - labels: Important labels, label architecture, and field schema customization
-- search: Full search query syntax with all operators and examples
+- search: Full search query syntax with all operators and examples, including strict:true
+- api-surface: nestr_api_spec, for checking whether an endpoint exists at all
 - fields: Adding custom fields to labels when Nestr has no field for something yet
 - web-app-links: Every web-app URL shape, the content tab hashes, and the two-pane hash form
 - workspace-settings: Where workspace settings are, every tab, and the link to hand over
@@ -468,6 +469,37 @@ Example response with hints:
 }
 \`\`\`
 
+**Hints have a level, and a listing should not ask for the expensive one.** \`hints\` takes
+\`'full'\`, \`'summary'\` or \`false\`. \`summary\` keeps everything that varies per nest — type,
+severity, count, url, and the \`query\` below — and drops the two things identical for every
+nest of that type: \`detail\`, the teaching paragraph, and \`endpoints\`. A page of fifty nests
+at \`full\` carries fifty copies of one paragraph; \`nestr_help\` carries it once, and
+\`helpTopic\` on the hint names which topic. Single reads default to \`full\`, listings to
+\`summary\`. Narrow further with \`hintTypes\` and \`minSeverity\`.
+
+**A hint can tell you how to find every other nest with the same problem.** Where the
+predicate is expressible as a search, the hint carries a \`query\`:
+
+\`\`\`json
+{ "type": "project_waiting_no_reason", "severity": "warning",
+  "query": {
+    "search": "label:project fields.project.status:Waiting fields.project.waiting_reason:!exists",
+    "scope": "<circleId>", "url": "https://.../api/nests/<circleId>/search?search=...",
+    "exact": false,
+    "caveat": "A reason saved as empty markup triggers the hint but is not matched by !exists." } }
+\`\`\`
+
+Read \`exact\` before you trust a count from it. \`true\` means the search reproduces the hint's
+predicate; \`false\` means it gets close and \`caveat\` says which way it is wrong. Where the
+predicate cannot be expressed at all there is no \`query\` — deliberately, because a search
+that quietly disagrees with its hint is worse than none.
+
+**To count rather than to list, use \`nestr_hints_rollup\`.** It returns how many nests under
+a circle or workspace carry each hint type, with a small sample, in one call instead of one
+per nest. Read its \`notComputed\`: it names the types it cannot count in a single query, so a
+type listed there is unknown, not zero. Do not sum counts across types — one nest can carry
+several.
+
 **Inline images.** An image pasted into a nest's text is stored as a file and left in the
 content as a markdown reference: \`![name](/file/download?id=FILE_ID&name=NAME)\`. These are
 deliberately absent from \`nestr_get_nest_files\`, because they belong to the text rather than
@@ -692,6 +724,26 @@ The \`nestr_search\` tool supports powerful query operators. Combine multiple op
 | \`groupby:\` | \`groupby:parent\` | Group results into sections (app + tabs; inert here) |
 | \`groupbycol:\` | \`groupbycol:project->status\` | Same grouping as board columns — see "Grouping and Layout" below |
 
+### Knowing your filter applied: \`strict:true\`
+
+An operator this parser does not recognise, an unknown label, or a field filter naming a
+field that does not exist are all **dropped silently**. The search still runs, returns a
+broader result, and nothing says a filter went missing. Fine when browsing, wrong when
+counting: a mistyped filter reads as a real, larger answer.
+
+Add \`strict:true\` and any dropped term becomes an error instead:
+
+\`\`\`
+label:project fields.project.stauts:Waiting strict:true
+  -> rejected, naming the unknown field, instead of returning every project
+\`\`\`
+
+\`nestr_search\` also takes \`strict: true\` as a parameter, which appends the operator for you.
+Use it whenever the number matters: counting, reporting, or deciding something on the result.
+
+For "does this deployment have X at all", \`strict:true\` answers it for the search language
+and \`nestr_api_spec\` answers it for the HTTP surface.
+
 ### The \`has:\` Operator
 
 The \`has:\` operator checks for property existence. Supports \`!\` prefix for negation (e.g., \`has:!due\`).
@@ -707,6 +759,10 @@ The \`has:\` operator checks for property existence. Supports \`!\` prefix for n
 - \`has:tabs\` - Items with tabs configured
 - \`has:header\` - Items with a header
 
+An unlisted value is not an error: \`has:<x>\` falls through to the nest property \`_p.<x>\`,
+so \`has:completable\` (items that can be completed) and \`has:eventable\` both work. The names
+above are the ones with special handling, not the whole set.
+
 ### Field Value Search
 
 Search by label-specific field values using \`label->field:value\`:
@@ -911,6 +967,24 @@ in:roleId label:project project->status:Current
 - All work in a circle: \`in:circleId completed:false\` (includes all nested items)
 - Direct tasks under a project: \`in:projectId depth:1 completed:false\`
 
+**Two ways to scope, and when to use which.** \`in:nestId\` scopes a workspace-wide
+\`nestr_search\`. \`nestr_get_nest_children\` takes a \`search\` that is already scoped to that
+nest, so the same question is shorter:
+
+\`\`\`
+nestr_search({ query: "in:circleId label:role depth:1" })
+nestr_get_nest_children({ nestId: circleId, search: "label:role" })
+  -> the same roles
+\`\`\`
+
+The children route applies \`depth:1\` when your query sets no depth, and says so in
+\`appliedDefaults\` on the response, which also names how to widen it. Reach for it when you
+already hold the nest id; reach for \`in:\` when you are composing one query across several
+scopes.
+
+Either way, ask for the subset you want rather than fetching a mixed set and sorting it
+out afterwards. "What type is this nest" is a question you can avoid asking.
+
 ### Filtering by Completion Status
 
 **Important:** When fetching work items (tasks, projects), always use \`completed:false\` unless you specifically need completed items. This avoids cluttering results with old completed work.
@@ -1324,6 +1398,47 @@ When a user asks about trends or patterns (e.g., "Are we getting better at gover
 - **All plans**: Workspace-level insights (aggregated across the whole organization)
 - **Pro plan only**: Circle-level insights (\`nestId\` parameter) and user-level insights (\`userId\` parameter). If the workspace is not on a Pro plan, these filters will return a 402 error.
 - \`userId\` and \`nestId\` cannot be combined — user metrics are always workspace-level.`,
+    "api-surface": `## Checking whether the API has something
+
+There is a difference between "I did not find it" and "it is not there", and only the
+second is safe to act on. \`nestr_api_spec\` is how you get the second.
+
+It returns this deployment's own OpenAPI document, reduced to something readable:
+
+- **No arguments**: the operation index. Method, path, and a one-line summary for every
+  operation the deployment serves, plus \`totalOperations\`.
+- **\`search\`**: filter that index by keyword against path and summary. The counts are the
+  answer as much as the rows are. \`matchedOperations: 0\` out of \`totalOperations: 94\` for
+  "duration" means this API has nothing about duration, full stop.
+- **\`path\`**: the full schema for one operation, including every parameter it accepts and
+  what each does. Use this before assuming a parameter exists.
+
+### When to reach for it
+
+- A user asks whether Nestr can do X through the API and you are about to say "I do not
+  think so". Check first, then say it with certainty.
+- You are about to pass a parameter you have not seen documented. \`path\` tells you whether
+  it exists rather than having it silently ignored.
+- Something is missing and you need to say whether it is unsupported or merely not exposed
+  through a tool. Those are different answers with different next steps.
+
+### The neighbouring questions
+
+\`nestr_api_spec\` answers "does the HTTP surface have this". Two others answer nearby
+questions, and mixing them up wastes a call:
+
+- **Does my search filter apply?** \`strict: true\` on \`nestr_search\`. An unrecognised
+  operator or field is otherwise dropped silently and the search returns a broader result.
+  See \`nestr_help('search')\`.
+- **Does this label have this field?** \`nestr_get_label\` returns a label's fields with their
+  codes, types and options. That is the data model rather than the HTTP surface, so a field
+  can exist here and have no dedicated endpoint.
+
+### What it does not tell you
+
+The spec describes routes, not permissions. An operation being listed does not mean this
+caller may call it: read-only keys, key profiles and per-nest rights all still apply. For
+"why can I not do this", use \`nestr_explain_nest\`; for auth failures, \`nestr_diagnose\`.`,
     "mcp-apps": `## MCP Apps (Interactive UI)
 
 Nestr provides interactive UI components that can be embedded in MCP clients that support the \`ui://\` resource protocol.

package/build/help/topics.js.map

@@ -1 +1 @@
-{"version":3,"file":"topics.js","sourceRoot":"","sources":["../../src/help/topics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"topics.js","sourceRoot":"","sources":["../../src/help/topics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,EAAE,+BAA+B,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAE5E,MAAM,CAAC,MAAM,WAAW,GAA2B;IACjD,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+EA+BmE;IAE7E,SAAS,EAAE;;;;;;;;;;;;;;;;;;;;6RAoBgR;IAE3R,iBAAiB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sGAqDiF;IAEpG,wBAAwB,EAAE;;;;;;;;;;;;;;;4FAegE;IAE1F,SAAS,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0FAyF6E;IAExF,iBAAiB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4GAqCuF;IAE1G,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CZ;IAEL,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gOAgOgN;IAE9N,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2OAyH+N;IAEzO,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mFA6CuE;IAEjF,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4VL;IAEL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kDAoG+B;IAEhD,oBAAoB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCAwCa;IAEnC,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuEJ;IAEL,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkET;IAEL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qGAyCkF;IAEnG,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0FA6B4E;IAExF,aAAa,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4FAwC2E;IAE1F,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgHP;IAEL,gBAAgB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gLA6F4J;IAE9K,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4TAkCgT;IAE1T,gBAAgB,EAAE;;;;;;;;;;;6NAWyM;IAE3N,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iIAsJsH;IAE/H,KAAK,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+JA4GsJ;IAE7J,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oJA2CsI;IAElJ,YAAY,EAAE,uBAAuB;IAErC,oBAAoB,EAAE,+BAA+B;IAErD,iBAAiB,EAAE,4BAA4B;CAChD,CAAC"}