@nestr/mcp 0.1.73 → 0.1.90

package/build/help/cross-links.js

@@ -0,0 +1,61 @@
+/**
+ * Cross-links between the curated internal `nestr_help` topics and the public
+ * help-article corpus (nestr.io/help/articles/<slug>).
+ *
+ * Two directions, two small hand-curated tables:
+ *  - TOPIC_TO_ARTICLES: an internal topic points to deeper end-user articles
+ *    (an internal topic may suggest several).
+ *  - ARTICLE_TO_TOPIC: an article points back to the single most relevant
+ *    internal topic (agent-flavoured tool-call guidance).
+ *
+ * Slugs are validated by hand against https://nestr.io/sitemap.xml; topic keys
+ * must exist in HELP_TOPICS (asserted in tests). When a topic and an article
+ * cover the same ground, add the pair to BOTH tables.
+ */
+export const TOPIC_TO_ARTICLES = {
+    "core-concepts": ["nestr-the-basic-building-blocks", "structure-and-governance-in-nestr"],
+    "nest-model": ["nestr-the-basic-building-blocks"],
+    "labels": ["nestr-the-power-of-labels"],
+    "search": ["nestr-search"],
+    "operating-modes": ["structure-and-governance-in-nestr"],
+    "workspace-types": ["structure-and-governance-in-nestr", "building-your-org-structure-roles-circles"],
+    "matching-work-to-roles": ["building-your-org-structure-roles-circles"],
+    "tension-processing": ["tensions-and-governance-proposals"],
+    "scrum": ["scrum-agile-app"],
+    "inbox": ["projects-and-todos-creating-tracking-managing-work"],
+    "daily-plan": ["projects-and-todos-creating-tracking-managing-work"],
+    "doing-work": ["projects-and-todos-creating-tracking-managing-work"],
+    "notifications": ["chat-channels-and-communication-in-nestr"],
+    "authentication": ["nestr-mcp-connect-ai-assistants-to-your-workspace", "using-the-nestr-api"],
+    "mcp-apps": ["nestr-mcp-connect-ai-assistants-to-your-workspace"],
+    "linking": ["navigating-nestr"],
+    "web-app-links": ["navigating-nestr"],
+    "workspace-setup": ["setting-up-a-new-collaborative-workspace"],
+    "best-practices": ["getting-started-with-nestr"],
+};
+export const ARTICLE_TO_TOPIC = {
+    "nestr-the-basic-building-blocks": "nest-model",
+    "structure-and-governance-in-nestr": "core-concepts",
+    "nestr-the-power-of-labels": "labels",
+    "nestr-search": "search",
+    "building-your-org-structure-roles-circles": "matching-work-to-roles",
+    "tensions-and-governance-proposals": "tension-processing",
+    "running-meetings-in-nestr": "tension-processing",
+    "scrum-agile-app": "scrum",
+    "projects-and-todos-creating-tracking-managing-work": "doing-work",
+    "chat-channels-and-communication-in-nestr": "notifications",
+    "nestr-mcp-connect-ai-assistants-to-your-workspace": "mcp-apps",
+    "using-the-nestr-api": "authentication",
+    "navigating-nestr": "web-app-links",
+    "setting-up-a-new-collaborative-workspace": "workspace-setup",
+    "getting-started-with-nestr": "best-practices",
+};
+/** Public help articles that go deeper on a curated internal topic. */
+export function relatedArticlesForTopic(topicKey) {
+    return TOPIC_TO_ARTICLES[topicKey] ?? [];
+}
+/** The internal topic (if any) that gives agent-flavoured guidance for an article. */
+export function relatedTopicForArticle(slug) {
+    return ARTICLE_TO_TOPIC[slug.replace(/^\/+|\/+$/g, "")];
+}
+//# sourceMappingURL=cross-links.js.map

package/build/help/cross-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-links.js","sourceRoot":"","sources":["../../src/help/cross-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAA6B;IACzD,eAAe,EAAE,CAAC,iCAAiC,EAAE,mCAAmC,CAAC;IACzF,YAAY,EAAE,CAAC,iCAAiC,CAAC;IACjD,QAAQ,EAAE,CAAC,2BAA2B,CAAC;IACvC,QAAQ,EAAE,CAAC,cAAc,CAAC;IAC1B,iBAAiB,EAAE,CAAC,mCAAmC,CAAC;IACxD,iBAAiB,EAAE,CAAC,mCAAmC,EAAE,2CAA2C,CAAC;IACrG,wBAAwB,EAAE,CAAC,2CAA2C,CAAC;IACvE,oBAAoB,EAAE,CAAC,mCAAmC,CAAC;IAC3D,OAAO,EAAE,CAAC,iBAAiB,CAAC;IAC5B,OAAO,EAAE,CAAC,oDAAoD,CAAC;IAC/D,YAAY,EAAE,CAAC,oDAAoD,CAAC;IACpE,YAAY,EAAE,CAAC,oDAAoD,CAAC;IACpE,eAAe,EAAE,CAAC,0CAA0C,CAAC;IAC7D,gBAAgB,EAAE,CAAC,mDAAmD,EAAE,qBAAqB,CAAC;IAC9F,UAAU,EAAE,CAAC,mDAAmD,CAAC;IACjE,SAAS,EAAE,CAAC,kBAAkB,CAAC;IAC/B,eAAe,EAAE,CAAC,kBAAkB,CAAC;IACrC,iBAAiB,EAAE,CAAC,0CAA0C,CAAC;IAC/D,gBAAgB,EAAE,CAAC,4BAA4B,CAAC;CACjD,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACtD,iCAAiC,EAAE,YAAY;IAC/C,mCAAmC,EAAE,eAAe;IACpD,2BAA2B,EAAE,QAAQ;IACrC,cAAc,EAAE,QAAQ;IACxB,2CAA2C,EAAE,wBAAwB;IACrE,mCAAmC,EAAE,oBAAoB;IACzD,2BAA2B,EAAE,oBAAoB;IACjD,iBAAiB,EAAE,OAAO;IAC1B,oDAAoD,EAAE,YAAY;IAClE,0CAA0C,EAAE,eAAe;IAC3D,mDAAmD,EAAE,UAAU;IAC/D,qBAAqB,EAAE,gBAAgB;IACvC,kBAAkB,EAAE,eAAe;IACnC,0CAA0C,EAAE,iBAAiB;IAC7D,4BAA4B,EAAE,gBAAgB;CAC/C,CAAC;AAEF,uEAAuE;AACvE,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,OAAO,iBAAiB,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;AAC3C,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,CAAC;AAC1D,CAAC"}

package/build/help/topics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["../../src/help/topics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA2rC9C,CAAC"}
+{"version":3,"file":"topics.d.ts","sourceRoot":"","sources":["../../src/help/topics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAy+C9C,CAAC"}

package/build/help/topics.js

@@ -10,6 +10,8 @@ import { WORKSPACE_SETUP_INSTRUCTIONS } from "../skills/workspace-setup.js";
 export const HELP_TOPICS = {
     "topics": `Available nestr_help topics (call with any topic key):
 
+The internal topics below are curated MCP-flavoured guidance — tool call patterns, mode behaviour, and conventions. For end-user UI walkthroughs and feature how-tos, call \`nestr_help({ search: "<query>" })\` to search the public help-article corpus at nestr.io/help/articles, or pass an article slug directly as \`topic\` (e.g. \`topic: "getting-started-with-nestr"\`).
+
 - topics: This list
 - operating-modes: Detailed assistant/role-filler/workspace mode behaviors
 - matching-work-to-roles: How to determine which role owns work
@@ -30,7 +32,9 @@ export const HELP_TOPICS = {
 - best-practices: Recommended patterns for working with Nestr
 - doing-work: How work flows from purpose through strategy to execution
 - tension-processing: Listening for, creating, and processing tensions
-- workspace-setup: Guided setup wizard for new workspaces and circles`,
+- workspace-setup: Guided setup wizard for new workspaces and circles
+- scrum: Scrum/Agile workspace app — user stories, sprints, epics, burndown
+- okr: Objectives & Key Results workspace app — goals, key results, contributions`,
     "operating-modes": `### Mode-Specific Behavior Summary
 
 **Role-filler agents should:**
@@ -102,22 +106,26 @@ When determining work assignments, consider:
 3. Are there multiple roles whose accountabilities overlap? Surface this for clarification.`,
     "linking": `## Linking to Nests
 
-**Always link to nests when mentioning them.** The URL format is:
+**When generating clickable links to nests in chat output, comments, or descriptions, always use the canonical pattern:** \`https://app.nestr.io/n/{nestId}\` (NOT \`/nests/{nestId}\`, \`/nest/\`, or any other variation — only \`/n/\`).
 
-\`https://app.nestr.io/n/{nestId}\`
+Every nest returned by this MCP server includes a precomputed \`url\` field — **prefer that field over constructing the URL yourself**. The server already applies the context rules below.
 
-If you know the context (circle or workspace) of the nest, include it as a prefix:
+### URL construction rules (when you must build a URL yourself)
 
-\`https://app.nestr.io/n/{contextId}/{nestId}\`
+1. If you know the nest's parent (circle, project, role, etc.), include it as the context prefix:
+   \`https://app.nestr.io/n/{parentId}/{nestId}\`
+2. If the nest has no parent, or its parent is \`inbox\`, fall back to the bare form:
+   \`https://app.nestr.io/n/{nestId}\`
 
-Where \`{contextId}\` is the nest's containing circle or workspace (found in the \`ancestors\` array). If you don't know the context ID, just use \`/n/{nestId}\` — it will still work.
+The parent context (when present) opens the nest in its detail pane on desktop. The bare form always works.
 
-**IMPORTANT:** The URL path is \`/n/\`, NOT \`/nest/\`, \`/nests/\`, or any other variation. Always use \`/n/\`.
+### Examples
 
-Examples:
 - Role in a circle: \`[Developer](https://app.nestr.io/n/circleId/roleId)\`
+- Task in a project: \`[Fix bug](https://app.nestr.io/n/projectId/taskId)\`
 - Top-level workspace: \`[My Workspace](https://app.nestr.io/n/workspaceId)\`
-- Task (circle unknown): \`[Fix bug](https://app.nestr.io/n/taskId)\``,
+- Inbox item: \`[Quick capture](https://app.nestr.io/n/itemId)\` (parent is 'inbox' — drop the context)
+- Nest of unknown context: \`[Fix bug](https://app.nestr.io/n/taskId)\``,
     "workspace-types": `## Workspace Types
 
 Most workspaces are organizational, representing a self-organized team. Check the workspace's labels to determine the type:
@@ -172,7 +180,7 @@ Nestr uses different formats for different fields:
 - **\`purpose\`**: The aspirational future state this nest is working towards. **Most important for workspaces, circles, and roles** — it defines the north star and context boundary for the organization, circle, or role. Everything within that container should serve its purpose. For other nests (tasks, projects, etc.), prefer \`description\` or \`fields\` for detailed information — but purpose can be set if it serves the user. Supports HTML.
 - **\`description\`**: The primary field for detailed information about a nest. Use for project details, task context, acceptance criteria, Definition of Done, and any persistent information about the nest. Supports HTML.
 - **\`fields\`**: Structured data defined by labels (e.g., \`fields['project.status']\`, \`fields['metric.frequency']\`). Use for structured, label-specific information.
-- **Comment \`body\`**: HTML supported (same tags as above, including base64 images). Supports @mentions using the format \`@{userId|email|circle|everyone}\`: \`@{userId}\` mentions by user ID, \`@{email}\` mentions by any email the user is registered with in Nestr, \`@{circle}\` notifies all role fillers in the nearest ancestor circle, \`@{everyone}\` is available in the UI but not yet via the API. **Use comments for progress updates**, status changes, and conversation — not purpose or description.
+- **Comment \`body\`**: HTML supported (same tags as above, including base64 images). Supports @mentions — **mentions MUST be wrapped in literal curly braces**: write \`@{aBcD1234eFgH5678i:roleNestId}\`, NOT \`@aBcD1234eFgH5678i\`. Without the braces the platform does not parse the mention, the user is not notified, and no link is rendered. Forms: **\`@{userId:roleId}\` is the preferred form when mentioning a user** — it addresses them in the context of a specific role (or a circle, for "individual action on a circle"), so they know which hat they're being addressed in. \`@{userId}\` mentions by user ID without role context (legacy — avoid when a role is known), \`@{email}\` mentions by any email the user is registered with in Nestr, \`@{circle}\` notifies all role fillers in the nearest ancestor circle, \`@{everyone}\` is available in the UI but not yet via the API. **Use comments for progress updates**, status changes, and conversation — not purpose or description.
 - **\`data\`**: Generic key-value store. Also used internally by Nestr and other integrations — **never overwrite or remove existing keys**. When adding your own data, namespace it under \`mcp.\` (e.g., \`{ "mcp.lastSync": "2025-01-01" }\`) to avoid conflicts. Not rendered in UI.
 
 **Where to put information:**
@@ -378,7 +386,7 @@ Labels define what type a nest is. The API strips the "circleplus-" prefix, so u
 
 **Meetings & Operations:**
 - \`metric\` - A metric tracked by a role/circle
-- \`checklist\` - A recurring checklist item
+- \`checklist\` - A **recurring** check processed during the Checklist Review section of a tactical meeting (Holacracy semantic): a regular yes/no/n-a confirmation that a role-filler is performing an ongoing activity. Must live under a role or circle. **NOT a general checklist item** — do not use for one-off tasks, todos, or generic "things to check off" (those are plain nests with no system label; see Work Tracking below).
 - \`governance\` - Combined with \`meeting\` label to create a governance meeting (processes governance tensions/proposals)
 - \`circle-meeting\` - Combined with \`meeting\` label to create a circle/tactical meeting (processes operational tensions — projects, todos, inter-role requests)
 
@@ -395,12 +403,20 @@ Labels define what type a nest is. The API strips the "circleplus-" prefix, so u
 **AI Knowledge:**
 - \`skill\` - A process, piece of knowledge, or learned pattern that a role or circle holds. Lives directly under a role or circle. Used by AI agents to persist and retrieve operational knowledge across sessions. When doing work that is likely to be repeated, capture it as a skill for future reference.
 
+**Workspace App labels** (only present when the corresponding app is enabled — check with \`nestr_get_workspace_apps\`):
+- \`userstory\`, \`sprint\`, \`epic\`, \`milestone\` — Scrum/Agile app. See \`nestr_help({ topic: "scrum" })\` for the data model, fields, and graph relations.
+- \`goal\`, \`result\`, \`resultwork\` — OKR app. See \`nestr_help({ topic: "okr" })\` for the Objective / Key Result / contribution pattern.
+
 **System Labels** (define structure, not categorization):
 \`circle\`, \`anchor-circle\`, \`role\`, \`policy\`, \`domain\`, \`accountability\`, \`project\`, \`tension\`, \`skill\`, \`goal\`, \`result\`, \`contact\`, \`deal\`, \`organisation\`, \`metric\`, \`checklist\`, \`meeting\`, \`feedback\`
 - \`note\` - A simple note
 - \`meeting\` - A calendar meeting
 - \`tension\` - The fundamental unit of organizational communication — a gap between current reality and potential. Used for inter-role communication, meeting agenda items, governance proposals, and general tension processing. Supports \`fields['tension.feeling']\` and \`fields['tension.needs']\` for separating personal context from organizational response. Use the dedicated tension tools (\`nestr_create_tension\`, \`nestr_list_my_tensions\`, etc.) to create and manage tensions.
 
+### Prime Labels (one per nest)
+
+These labels define a nest's core identity and are mutually exclusive — a nest can have at most one of them: \`project\`, \`tension\`, \`role\`, \`circle\`, \`anchor-circle\`, \`meeting\`, \`metric\`, \`goal\`, \`result\`, \`checklist\`, \`feedback\`, \`userstory\`, \`sprint\`, \`epic\`, \`milestone\`. A project is not also a tension, a role is not also a metric, a sprint is not also an epic. The MCP layer will reject calls to \`nestr_create_nest\`, \`nestr_update_nest\`, or \`nestr_add_label\` that would put two prime labels on the same nest. **Sole exception:** \`userstory\` + \`project\` may coexist — \`userstory\` implies \`project\` in Nestr's data model, so every story is also a project. \`sprint\`, \`epic\`, and \`milestone\` must NOT be combined with \`project\` (or with each other); stories relate to those containers via graph links (\`userstory_sprint\` / \`userstory_epic\` / \`userstory_milestone\`), never by sharing labels. If you need to express a relationship between two such entities, create separate nests and link them with \`nestr_add_graph_link\`. Modifier labels like \`governance\` and \`circle-meeting\` (which pair with \`meeting\`) are not prime and can coexist.
+
 ## Label Architecture
 
 Labels give nests meaning and define their behavior. There are three types of labels:
@@ -460,6 +476,8 @@ Use this when you need to know what values are valid for a field, especially bef
 
 The \`nestr_search\` tool supports powerful query operators. Combine multiple operators with spaces (AND logic) or use commas within an operator (OR logic).
 
+**Linking search results:** Every returned nest includes a precomputed \`url\` field — use it directly when generating clickable links to results. The canonical pattern is \`https://app.nestr.io/n/{nestId}\` (NOT \`/nests/{nestId}\`). See \`nestr_help('linking')\` for full URL construction rules.
+
 ### Common Search Operators
 
 | Operator | Example | Description |
@@ -501,6 +519,25 @@ Search by label-specific field values using \`label->field:value\`:
 - \`project->status:Current,Future\` - Status is Current OR Future
 - \`project->status:!Done\` - Status is NOT Done
 
+### Term-field Search
+
+For fields of type \`term\` (date ranges stored as \`{from, to}\` ISO date strings — e.g. \`sprint_term\`, \`goal_term\`), the standard \`{labelId}->{fieldCode}:value\` operator accepts date / range / named-range values and produces an **overlap** query: "the term overlaps this point or range".
+
+| Query | Means |
+|---|---|
+| \`sprint->term:now\` | Sprints active today |
+| \`sprint->term:2026-03-15\` | Sprints active on that date |
+| \`sprint->term:2026-01-01_2026-03-31\` | Sprints overlapping Q1 2026 |
+| \`sprint->term:2026-01-01_now\` | Sprints overlapping the range up to today |
+| \`goal->term:this_quarter\` | Objectives running any portion of this quarter |
+| \`sprint->term:!now\` | Sprints NOT currently active |
+
+Accepted value forms: \`now\`, ISO \`YYYY-MM-DD\`, \`DATE_DATE\` range (same \`_\`-separated convention as \`completed:DATE_DATE\`), or named ranges (\`past_7_days\`, \`this_month\`, \`last_month\`, \`this_quarter\`, \`last_quarter\`, \`this_year\`, \`last_year\`, etc. — the same set as \`completed:\` and \`updated-date:\`).
+
+Prefix the value with \`!\` to invert (no overlap).
+
+**Endpoint-specific queries** (e.g. "sprints that ended last week" vs. "sprints that overlapped last week") are not yet supported as a single operator — the overlap form is the supported primitive. For "is field set / unset" use the existing \`fieldValues.X:exists\` / \`fieldValues.X:!exists\`.
+
 ### Search Examples
 
 \`\`\`
@@ -581,9 +618,9 @@ Use \`sort:\` to specify the sort field and \`sort-order:\` to set direction.
 - \`sort-order:asc\` - Ascending (default)
 - \`sort-order:desc\` - Descending
 
-**Defaults:**
-- Roles and circles: \`sort:title\` (alphabetical)
-- Work items (tasks, projects): \`sort:searchOrder\` (manual ordering set by users)
+**Default:** without an explicit sort, results come back in the API's natural order — always pass a sort when ordering matters.
+
+**Same sorting on fetch tools:** the list/fetch tools (\`nestr_get_projects\`, \`nestr_get_nest_children\`, \`nestr_list_circles\`, \`nestr_list_roles\`, \`nestr_get_circle_roles\`, \`nestr_list_workspaces\`, \`nestr_list_tensions\`) accept the same fields via their \`sort\` parameter — prefix with \`-\` for descending (e.g. \`sort: '-updatedAt'\`). No need to switch to search just to order results.
 
 **Examples:**
 \`\`\`
@@ -639,9 +676,12 @@ in:roleId label:project project->status:Current
 The \`completed:\` operator accepts:
 - \`completed:false\` - Only uncompleted items (recommended default for work queries)
 - \`completed:true\` - Only completed items
+- \`completed:any\` - Both completed AND uncompleted (skips the default 1-week-old filter). Use when you need full history.
 - Presets: \`completed:past_7_days\`, \`completed:this_month\`, \`completed:last_quarter\`, etc.
 - Custom date range: \`completed:2024-01-01_2024-03-31\` (format: \`YYYY-MM-DD_YYYY-MM-DD\`)
 
+**Strict variant** (\`completed-strict:false\` / \`completed-strict:true\`): drops the \`_p.completable || _p.eventable\` guard that \`completed:false\` adds. Use when the rest of the search already restricts to labels declared \`completable: false\` at the label level but whose status field has \`completed: true\` options — e.g. \`label:sprint completed-strict:false\` returns planned + active sprints (hiding closed/cancelled). Without the strict variant the sprint label's \`completable: false\` would filter out every sprint.
+
 **Examples:**
 \`\`\`
 assignee:me completed:false
@@ -1188,13 +1228,273 @@ All work in Nestr — projects, tasks, comments, tensions, and skills — forms
 1. **Start by listing workspaces** to get the workspace ID and check if it has the "anchor-circle" label
 2. **Use search** to find specific items rather than browsing through hierarchies
 3. **Check labels** to understand what type of nest you're working with
-4. **Use @mentions** in comments to notify team members: \`@{userId}\`, \`@{email}\`, or \`@{circle}\` for all role fillers
+4. **Use @mentions** in comments to notify team members. **The literal \`{\` and \`}\` braces are required** — \`@aBcD1234eFgH5678i\` does NOT mention anyone; \`@{aBcD1234eFgH5678i:roleNestId}\` does. Prefer \`@{userId:roleId}\` so the user knows which role they're being addressed in (the second part can be a role nest or a circle nest for "individual action on a circle"). Fall back to \`@{userId}\` only when no role context applies, or use \`@{email}\` / \`@{circle}\` (notifies all role fillers in the nearest ancestor circle)
 5. **Respect the hierarchy**: nests live under parents (workspace → circle → role/project → task)
 6. **Maintain skills on roles and circles** for AI knowledge persistence:
    - Before doing work from a role, check for existing skills under that role or its circle — they contain processes, patterns, and domain knowledge from prior sessions
    - When completing work that is likely repeatable, capture it as a skill under the appropriate role or circle
    - Skills are the primary mechanism for AI context persistence — they're visible, searchable, and transfer with the role when it's reassigned
    - The \`data\` field is shared with Nestr internals and other integrations — never overwrite or remove existing keys. If you must store custom data, namespace under \`mcp.\` (e.g., \`data: { "mcp.lastSync": "..." }\`)`,
+    "scrum": `## Scrum / Agile App
+
+The Scrum app adds four label types (\`userstory\`, \`sprint\`, \`epic\`, \`milestone\`) plus the graph relations and field rollups that make a real Scrum board work. It is a **workspace app** — the labels and tools below only behave correctly when the app is enabled.
+
+### Detect whether Scrum is enabled
+
+Call \`nestr_get_workspace_apps({ workspaceId })\` and look for \`id: 'scrum'\`. If it's absent, the labels won't exist in the workspace and any \`label:userstory\` / \`label:sprint\` / \`label:epic\` / \`label:milestone\` queries will return empty.
+
+Sprints, epics, and milestones can each be individually disabled at the workspace level even when the app is on — check \`workspace.data['appfield-scrum-sprints-enabled']\` (and the \`-epics-\` / \`-milestones-\` variants). When a sub-feature is set to \`false\`, the corresponding graph-field on user stories is hidden in the UI; the labels still resolve, so search and graph-link tools keep working.
+
+### The four labels
+
+| Label | Role | Lives under |
+|---|---|---|
+| \`userstory\` | A unit of Scrum work. **Always carries the \`project\` label** (\`implies: ['project']\`), so every story is also a project — \`nestr_get_projects\` finds them, \`project.status\` drives Done, and workspace-wide project reporting includes them. | role, circle, anchor-circle |
+| \`sprint\` | A time-boxed iteration. Holds active work via the \`userstory_sprint\` graph relation. Sprint goal is stored in the \`purpose\` field. | circle, anchor-circle |
+| \`epic\` | A scope axis (feature / initiative) grouping stories across sprints. **Termless** — scope-boxed, not time-boxed. Can nest under another epic. | role, circle, anchor-circle, epic |
+| \`milestone\` | A time-boxed delivery target — release, version, or phase. Time-boxed (has a \`term\`). Conceptually larger in scope than a sprint (typically spans several), but in the data model it is a peer container alongside the sprint, not its parent: both live directly under the circle. | circle, anchor-circle |
+
+All four are **prime labels** — a nest is a story OR a sprint OR an epic OR a milestone, never several at once, and the MCP rejects label combinations among them. The sole allowed pairing is \`userstory\` + \`project\` (automatic via the implication above); \`sprint\`, \`epic\`, and \`milestone\` must never carry the \`project\` label. Relationships between stories and containers are expressed exclusively through graph links, not by stacking labels.
+
+The three "container" labels (\`sprint\`, \`epic\`, \`milestone\`) are independent grouping axes: a single user story can be linked to any combination of one sprint, one epic, and one milestone via three separate graph relations. There is no hierarchy between the containers themselves — milestones do not contain sprints, epics do not contain sprints. Each carries the same shape: a status field, derived points totals/burned (summed via \`sum_reverse_graphselect\` across linked stories), and a burndown dataseries. Sprint and milestone are term-bound; epic burndown tracks calendar time.
+
+### Story fields (\`userstory\`)
+
+Discover the live schema with \`nestr_get_label({ workspaceId, labelId: 'userstory' })\` or by fetching any story with \`fieldsMetaData=true\`.
+
+| Field code | Field id | Type | Notes |
+|---|---|---|---|
+| \`sprint\` | \`userstory_sprint\` | graphselect → sprint | Outgoing graph link. Read/write via \`nestr_get_graph_links({ relation: 'userstory_sprint' })\` / \`nestr_add_graph_link\` / \`nestr_remove_graph_link\`. Hidden when sprints are disabled at the workspace. |
+| \`epic\` | \`userstory_epic\` | graphselect → epic | Same pattern with relation \`userstory_epic\`. Hidden when epics are disabled. |
+| \`milestone\` | \`userstory_milestone\` | graphselect → milestone | Same pattern with relation \`userstory_milestone\`. Hidden when milestones are disabled. |
+| \`points\` | \`userstory_points\` | select | Fibonacci values: 1, 2, 3, 5, 8, 13. A leading \`__unset__\` "Not estimated" sentinel is the unset state — \`points_burned\` stays hidden until the story is estimated. |
+| \`points_burned\` | \`userstory_points_burned\` | range (0 → points) | Max equals the story's \`userstory_points\`. Server auto-snaps to full points when the story flips to Done (via \`project.status\`), to 0 when undone. |
+| \`change_request_url\` | \`userstory_change_request_url\` | text | URL of a linked PR / merge request. Always visible so it can be set from the UI. |
+
+A story uses \`project.status\` for Done (via the \`project\` implication). There is no \`userstory_type\` field — feature/bug/chore/spike was dropped in V1.
+
+### Sprint fields (\`sprint\`)
+
+| Field code | Field id | Type | Notes |
+|---|---|---|---|
+| \`status\` | \`sprint_status\` | select | \`planned\` / \`active\` / \`closed\` (completed) / \`cancelled\` (completed). Terminal options carry \`completed: true\` so the nest's \`completed\` flag flips when the sprint closes. **Canonical "active sprint" signal — prefer this over term-overlap.** Default: \`planned\`. |
+| \`term\` | \`sprint_term\` | term ({from, to}) | Server mirrors \`term.to\` into the sprint's \`due\` field so overdue rendering works. |
+| \`capacity\` | \`sprint_capacity\` | number | Team capacity in points. |
+| \`points_total\` | \`sprint_points_total\` | number (derived) | Sum of \`userstory_points\` across linked stories. Read-only. |
+| \`points_burned\` | \`sprint_points_burned\` | number (derived) | Sum of \`userstory_points_burned\` across linked stories. Read-only. |
+| \`sprint_burndown\` | \`sprint_burndown\` | dataseries | Two-series chart: \`remaining\` (primary, descends from total → 0 via \`invertAgainst\`) and \`total\` (grey step-line). Window-bounded by \`sprint_term\`. |
+
+Sprint goal lives in the standard \`purpose\` field (relabeled "Sprint goal" in the UI).
+
+### Milestone fields (\`milestone\`)
+
+| Field code | Field id | Type | Notes |
+|---|---|---|---|
+| \`status\` | \`milestone_status\` | select | \`planned\` / \`in_progress\` / \`released\` (completed) / \`cancelled\`. Only \`released\` marks the milestone completed — shipped milestones are "done", cancelled ones stay uncompleted. |
+| \`term\` | \`milestone_term\` | term ({from, to}) | The release window. |
+| \`points_total\` / \`points_burned\` / \`milestone_burndown\` | — | derived | Same shape as the sprint trio, summing across \`userstory_milestone\` instead of \`userstory_sprint\`. |
+
+### Epic fields (\`epic\`)
+
+| Field code | Field id | Type | Notes |
+|---|---|---|---|
+| \`status\` | \`epic_status\` | select | \`proposed\` / \`in_progress\` / \`done\` (completed). |
+| \`points_total\` / \`points_burned\` / \`epic_burndown\` | — | derived | Same shape as sprint/milestone, summing across \`userstory_epic\`. **Termless burndown** — tracks on every value change (no \`trackTerm\`), so the chart shows calendar-time trajectory regardless of sprint cadence. |
+
+### Common workflows
+
+**Find the active sprint**
+
+The canonical signal is the lifecycle field:
+
+\`\`\`
+nestr_search({ workspaceId, query: "label:sprint fieldValues.sprint_status:active in:<circleId>" })
+\`\`\`
+
+Drop \`in:\` for workspace-wide. To find sprints whose term overlaps today (regardless of status — e.g. a \`planned\` sprint that should have started but hasn't been activated):
+
+\`\`\`
+nestr_search({ workspaceId, query: "label:sprint sprint->term:now" })
+\`\`\`
+
+To list all sprints including closed/cancelled ones (the default search hides completed work), add \`completed:any\` or \`completed-strict:false\`:
+
+\`\`\`
+nestr_search({ workspaceId, query: "label:sprint completed:any sort:fieldValues.sprint_term.to sort-order:desc" })
+\`\`\`
+
+See \`nestr_help({ topic: "search" })\` for the term-field operator and the \`completed-strict\` / \`completed:any\` DSLs.
+
+**List the stories in a sprint, epic, or milestone**
+
+All three use the same pattern — \`incoming\` because the graph edge is stored on the story:
+
+\`\`\`
+nestr_get_graph_links({ nestId: <sprintId>,    relation: "userstory_sprint",    direction: "incoming" })
+nestr_get_graph_links({ nestId: <epicId>,      relation: "userstory_epic",      direction: "incoming" })
+nestr_get_graph_links({ nestId: <milestoneId>, relation: "userstory_milestone", direction: "incoming" })
+\`\`\`
+
+**List the backlog (stories with no sprint)**
+
+\`\`\`
+nestr_search({ workspaceId, query: "label:userstory completed:false fieldValues.userstory_sprint:!exists in:<circleId>" })
+\`\`\`
+
+The \`:!exists\` check on \`fieldValues.userstory_sprint\` selects stories not linked to any sprint. Swap the field id for \`userstory_epic\` / \`userstory_milestone\` to find stories without an epic or milestone instead.
+
+**Read progress on a sprint / epic / milestone**
+
+Fetch with \`nestr_get_nest({ nestId, fieldsMetaData: true })\`. The derived rollups land in \`fields['sprint.points_total']\` / \`fields['sprint.points_burned']\` (and the equivalents for epic / milestone). The burndown history lives in the metrics collection — surface it through the regular insights / metric tools rather than recomputing.
+
+**Create a sprint**
+
+\`\`\`
+nestr_create_nest({
+  workspaceId,
+  parentId: <circleId>,
+  labels: ["sprint"],
+  purpose: "Ship the search filter to beta users",
+  fields: { "sprint.term": { from: "2026-06-01", to: "2026-06-14" }, "sprint.capacity": 40 }
+})
+\`\`\`
+
+\`sprint_status\` defaults to \`planned\` — set it to \`active\` when the sprint starts, \`closed\` when it ends.
+
+**Create a user story**
+
+\`\`\`
+nestr_create_nest({
+  workspaceId,
+  parentId: <roleOrCircleId>,
+  labels: ["userstory"],
+  title: "Search filter respects archived items",
+  fields: { "userstory.points": "5" }
+})
+\`\`\`
+
+Leave \`userstory.points\` unset for unestimated stories. Link to sprint / epic / milestone after creation with \`nestr_add_graph_link({ relation: "userstory_sprint" | "userstory_epic" | "userstory_milestone", targetId })\`.
+
+**Move a story between sprints**
+
+Remove the old link, add the new one. The sprint-level rollups update automatically through the \`sum_reverse_graphselect\` derivation.
+
+### Mode-specific guidance
+
+**Assistant mode** — Defer planning decisions to the user. Surface candidate stories (e.g., "Here are unsprinted high-priority stories in your backlog"), draft \`nestr_create_nest\` payloads, but let the human commit. Show the active sprint's burndown when asked about progress; don't editorialise it.
+
+**Role-filler mode** — If you energise a role that owns work in a sprint, treat \`fieldValues.sprint_status:active\` as your current operating context. Auto-link stories you create to that sprint when the role's accountabilities match the work. Update \`userstory_points_burned\` as you complete work; do not wait for the human to mark the story Done if the work objectively wraps an accountability. Capture repeatable scrum patterns as skill nests under the role.
+
+**Workspace mode** — Use for sprint / milestone setup, capacity tracking, and reporting across circles. Avoid user-scoped flows.`,
+    "okr": `## OKR App (Objectives & Key Results)
+
+The OKR app adds three labels — \`goal\` (Objective), \`result\` (Key Result), and \`resultwork\` (work that contributes to a result). It works the same in any workspace where the app is enabled; the goal/result labels are part of \`nestr:core\`, but the surfacing UI and the conventions below assume the OKR pattern.
+
+### The three labels
+
+| Label | Role | Lives under |
+|---|---|---|
+| \`goal\` | An Objective. Can nest under another goal to express hierarchy. | anchor-circle, circle, role, goal |
+| \`result\` | A Key Result. Always lives under a \`goal\`. | goal (only) |
+| \`resultwork\` | A completable nest that contributes to a key result. Links to its result via a graph relation. | anywhere (typically under a role or project) |
+
+### Objective fields (\`goal\`)
+
+| Field code | Field id | Type | Notes |
+|---|---|---|---|
+| \`term\` | \`goal_term\` | term ({from, to}) | The period the Objective runs in (quarter, year, custom). Follows the ancestor goal when set on a parent. |
+| \`goal_complete\` | \`goal_complete\` | percentage (derived) | Average progress of the Objective's Key Results. Read-only. |
+| \`goal-data\` | \`goal-data\` | dataseries | Progress history. Tracks \`goal_complete\` over \`goal_term\`. |
+
+### Key Result fields (\`result\`)
+
+| Field code | Field id | Type | Notes |
+|---|---|---|---|
+| \`term\` | \`goal_term\` | term ({from, to}) | Inherits from the parent goal by default. |
+| \`target_complete\` | \`goal_complete\` | range (0 → 100) | The user's progress slider. Aggregates upward into the parent Objective's \`goal_complete\`. |
+| \`goal-data\` | \`goal-data\` | dataseries | Same history pattern as goals. |
+
+### Work contribution (\`resultwork\`)
+
+| Field code | Field id | Type | Notes |
+|---|---|---|---|
+| \`result\` | \`completable_result\` | graphselect → goal/result | Links the completable to the Key Result (or Objective) it contributes to. |
+
+### Common workflows
+
+**Find the current Objectives for a circle**
+
+\`\`\`
+nestr_search({ workspaceId, query: "label:goal goal->term:now in:<circleId>" })
+\`\`\`
+
+For all Objectives running this quarter:
+
+\`\`\`
+nestr_search({ workspaceId, query: "label:goal goal->term:this_quarter" })
+\`\`\`
+
+See \`nestr_help({ topic: "search" })\` → "Term-field Search" for the full value forms.
+
+**List Key Results under an Objective**
+
+\`\`\`
+nestr_get_nest_children({ nestId: <goalId> })
+\`\`\`
+
+Key Results are always direct children of their goal.
+
+**Find work contributing to a Key Result**
+
+\`\`\`
+nestr_get_graph_links({ nestId: <resultId>, relation: "completable_result", direction: "incoming" })
+\`\`\`
+
+**Read Objective progress**
+
+Fetch with \`nestr_get_nest({ nestId, fieldsMetaData: true })\`. \`fields['goal.goal_complete']\` holds the averaged percentage; \`fields['goal.goal-data']\` exposes the history series.
+
+**Create an Objective**
+
+\`\`\`
+nestr_create_nest({
+  workspaceId,
+  parentId: <circleId | roleId | anchorId>,
+  labels: ["goal"],
+  title: "Trial conversion above 30%",
+  purpose: "Lift sustainable revenue without raising acquisition spend",
+  fields: { "goal.term": { from: "2026-04-01", to: "2026-06-30" } }
+})
+\`\`\`
+
+**Create a Key Result**
+
+\`\`\`
+nestr_create_nest({
+  workspaceId,
+  parentId: <goalId>,
+  labels: ["result"],
+  title: "Convert 35% of new trials within 14 days"
+})
+\`\`\`
+
+The KR inherits \`goal_term\` from the parent automatically.
+
+**Mark progress on a Key Result**
+
+\`\`\`
+nestr_update_nest({ nestId: <resultId>, fields: { "result.target_complete": 60 } })
+\`\`\`
+
+The parent Objective's \`goal_complete\` updates from the average of its KRs.
+
+### Mode-specific guidance
+
+**Assistant mode** — Help the user articulate Objectives that are aspirational, time-bound, and outcome-shaped (past-tense or measurable). Coach them to keep KRs measurable; resist the urge to fill in numbers without their input. When asked "how are we doing on OKRs?", read the period (\`goal.term=this_quarter\` is the usual frame) and report progress objectively.
+
+**Role-filler mode** — If your role owns an Objective or contributes \`resultwork\` to a Key Result, update your contribution as part of your operational rhythm. Reading the parent goal's \`term\` tells you the window you're working in. Capture repeatable measurement patterns as skill nests.
+
+**Workspace mode** — Use for cross-circle reporting and period-level rollups. Pair \`goal.term=this_quarter\` queries with insights tools to build dashboards.`,
     "doing-work": DOING_WORK_INSTRUCTIONS,
     "tension-processing": TENSION_PROCESSING_INSTRUCTIONS,
     "workspace-setup": WORKSPACE_SETUP_INSTRUCTIONS,

package/build/help/topics.js.map

@@ -1 +1 @@
-{"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;;;;;;;;;;;;;;;;;;;;;;sEAsB0D;IAEpE,iBAAiB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sGAoDiF;IAEpG,wBAAwB,EAAE;;;;;;;;;;;;;;;4FAegE;IAE1F,SAAS,EAAE;;;;;;;;;;;;;;;;;sEAiByD;IAEpE,iBAAiB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4GAqCuF;IAE1G,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CZ;IAEL,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gOAkKgN;IAE9N,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2OA6F+N;IAEzO,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwOL;IAEL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAwCa;IAE9B,OAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuEJ;IAEL,YAAY,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkET;IAEL,eAAe,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qGAyCkF;IAEnG,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0FA6B4E;IAExF,UAAU,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgHP;IAEL,gBAAgB,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gLA6F4J;IAE9K,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4TAkCgT;IAE1T,gBAAgB,EAAE;;;;;;;;;;;6NAWyM;IAE3N,YAAY,EAAE,uBAAuB;IAErC,oBAAoB,EAAE,+BAA+B;IAErD,iBAAiB,EAAE,4BAA4B;CAChD,CAAC"}
+{"version":3,"file":"topics.js","sourceRoot":"","sources":["../../src/help/topics.ts"],"names":[],"mappings":"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"}

package/build/http.d.ts

@@ -42,6 +42,7 @@ export interface SessionData {
     mcpClient?: string;
     mcpClientVersion?: string;
     isApiKey: boolean;
+    isPublic?: boolean;
     wantsJsonOnly: boolean;
     hasStoredOAuthSession: boolean;
     userId?: string;
@@ -76,19 +77,9 @@ export interface SessionData {
     sessionCorrelationId?: string;
 }
 export declare const sessions: Record<string, SessionData>;
-/**
- * Find a prior session that a re-initializing client is likely trying to replace.
- *
- * Matches on (authToken, mcpClient) within a 10-minute window. The POST /mcp
- * init path closes and drops the match so the client gets a fresh, clean
- * session — this prevents "Server already initialized" 400s when a client
- * reconnects after an SSE drop (the transport can only be initialized once).
- */
-export declare const SESSION_COALESCE_WINDOW_MS: number;
-export declare function findCoalescableSession(authToken: string, mcpClient: string | undefined): {
-    sessionId: string;
-    session: SessionData;
-} | undefined;
+export declare const publicSessions: Record<string, SessionData>;
+export declare const SSE_DEAD_IDLE_TIMEOUT_MS: number;
+export declare function sweepStaleSessions(map: Record<string, SessionData>, now: number): void;
 /**
  * Extract authentication token from request headers
  *

package/build/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAgB,EAAE,OAAO,EAAE,QAAQ,EAAgB,MAAM,SAAS,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AA2BnG,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,oBAAoB,CAAC;AAmB5B,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,EAAE,IAAI,MAAM,CAEjE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C;AAED,eAAO,MAAM,GAAG,6CAAY,CAAC;AA25B7B,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,6BAA6B,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,aAAa,EAAE,OAAO,CAAC;IACvB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,6FAA6F;IAC7F,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAMD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAM,CAAC;AAIxD;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,QAAiB,CAAC;AAkFzD,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GAAG,SAAS,CAwBhJ;AAgUD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAcxD"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAgB,EAAE,OAAO,EAAE,QAAQ,EAAgB,MAAM,SAAS,CAAC;AAEnE,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AA+BnG,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,oBAAoB,CAAC;AAmB5B,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,EAAE,IAAI,MAAM,CAEjE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C;AAED,eAAO,MAAM,GAAG,6CAAY,CAAC;AA86B7B,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,6BAA6B,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtE,6FAA6F;IAC7F,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAMD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAM,CAAC;AAKxD,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAM,CAAC;AAS9D,eAAO,MAAM,wBAAwB,QAAiB,CAAC;AAcvD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAgBtF;AAgYD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAcxD"}