@skilder-ai/runtime 0.9.16 → 0.9.18

package/dist/index.js

@@ -87716,10 +87716,14 @@ var OPTIMIZATION_INSIGHTS_TIMEFRAMES = [
 ];
 var DEFAULT_OPTIMIZATION_INSIGHTS_LOOKBACK_SECONDS = 30 * 24 * 60 * 60;
 
-// ../common/src/constants.node.ts
-var MCP_CALL_TOOL_TIMEOUT = parseInt(process.env.MCP_CALL_TOOL_TIMEOUT ?? "60000", 10);
-var DEFAULT_REQUEST_TIMEOUT = parseInt(process.env.DEFAULT_REQUEST_TIMEOUT ?? "10000", 10);
-var SCRIPT_ROUTE_TIMEOUT_MS = 31e4;
+// ../common/src/node-helpers/env.ts
+function parseStringEnv(name21, fallback) {
+  const raw = process.env[name21];
+  return raw === void 0 || raw === "" ? fallback : raw;
+}
+function parseUrlEnv(name21, fallback) {
+  return parseStringEnv(name21, fallback).replace(/\/+$/, "");
+}
 function parsePositiveIntEnv(name21, fallback) {
   const raw = process.env[name21];
   if (raw === void 0 || raw === "") return fallback;
@@ -87729,6 +87733,11 @@ function parsePositiveIntEnv(name21, fallback) {
   }
   return parsed;
 }
+
+// ../common/src/constants.node.ts
+var MCP_CALL_TOOL_TIMEOUT = parseInt(process.env.MCP_CALL_TOOL_TIMEOUT ?? "60000", 10);
+var DEFAULT_REQUEST_TIMEOUT = parseInt(process.env.DEFAULT_REQUEST_TIMEOUT ?? "10000", 10);
+var SCRIPT_ROUTE_TIMEOUT_MS = 31e4;
 var DCR_REFRESH_STARTUP_DELAY_MS = parsePositiveIntEnv("DCR_REFRESH_STARTUP_DELAY_MS", 3e4);
 var DCR_REFRESH_INTERVAL_MS = parsePositiveIntEnv("DCR_REFRESH_INTERVAL_MS", 60 * 60 * 1e3);
 var DCR_REFRESH_STALE_AFTER_MS = parsePositiveIntEnv("DCR_REFRESH_STALE_AFTER_MS", 6 * 60 * 60 * 1e3);
@@ -87739,6 +87748,41 @@ var DCR_REFRESH_MAX_FAILURE_WINDOW_MS = parsePositiveIntEnv(
   72 * 60 * 60 * 1e3
 );
 
+// ../common/src/provisioning.constants.ts
+var SKILDER_HAT_DEFAULTS = {
+  slug: "skilder",
+  name: "Skilder",
+  /** HatColor enum value (string-compatible). */
+  color: "BLUE",
+  description: "A gentle and smart assistant that knows the Skilder platform inside and out. Helps users create and manage skills, hats, tools, and automations.",
+  instructions: `You are the Skilder Assistant \u2014 a gentle, knowledgeable, and proactive AI helper.
+
+Your role is to help users get the most out of the Skilder platform. You know every feature, concept, and workflow: hats, skills, MCP servers, tools, runtimes, organizational hierarchy, and the Studio conversation interface.
+
+Behavior guidelines:
+- Be welcoming and patient, especially with new users
+- Explain concepts in plain language before using technical terms
+- Proactively suggest next steps and quick wins
+- When asked to build something, use your Skilder tools to do it \u2014 don't just explain how
+- If you're unsure about the user's intent, ask a clarifying question
+- Keep responses concise but complete
+
+You have access to Skilder MCP tools for managing skills, hats, org units, and tool configurations. Use them to take action on behalf of the user when appropriate.
+
+## Tool honesty (critical)
+
+- ONLY call tools that are explicitly listed under the "Available Tools" of a skill you have learned. Call them by their exact name.
+- NEVER invent or guess a tool name, and NEVER invent a script (e.g. a "create_hat.py") that wasn't listed. If a plausible tool isn't in your learned skills, it does not exist for you.
+- NEVER claim an action succeeded unless the tool actually returned a successful result. If a tool call errors or is unavailable, say so plainly \u2014 do not pretend it worked.
+- If you need a capability you don't have a tool for, STOP and tell the user the skill is missing that tool, then suggest they either (i) browse the **Library** to add an existing tool/skill, or (ii) configure a new tool/MCP server. Do not work around a missing tool by faking it.`
+};
+var SKILDER_SKILL_IDS = [
+  "skilder-skill-architect",
+  "skilder-platform-expert",
+  "skilder-hat-designer",
+  "human-discovery"
+];
+
 // ../../node_modules/.pnpm/bcryptjs@3.0.3/node_modules/bcryptjs/index.js
 var nextTick = typeof setImmediate === "function" ? setImmediate : typeof scheduler === "object" && typeof scheduler.postTask === "function" ? scheduler.postTask.bind(scheduler) : setTimeout;
 var BASE64_CODE = "./ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789".split("");
@@ -110765,6 +110809,1121 @@ function buildStreamTransport(transport) {
 var CONNECTED_WINDOW_HOURS = 24;
 var CONNECTED_WINDOW_MS = CONNECTED_WINDOW_HOURS * 60 * 60 * 1e3;
 
+// ../common/src/skill-catalog-meta.ts
+var SKILDER_META_FEATURED_SKILLS = [
+  {
+    slug: "skilder-skill-architect",
+    name: "Skilder Skill Architect",
+    description: "Craft high-quality Skilder skills: instructions writing, and attaching references/scripts",
+    tags: ["skilder", "meta", "skill-building"],
+    instructions: `Craft high-quality Skilder skills using these principles.
+
+For multi-step workflows, use the **delegate** static tool which spawns a sub-agent with full Skilder MCP access.
+
+## Writing Effective Instructions
+
+- Keep instructions **concise** \u2014 they are revealed on \`learn\` as a quick guide.
+- Use **progressive disclosure**: link deep-dive content as named reference documents.
+- Write in **imperative voice**: "Query the database using..." not "The database can be queried..."
+- Include **concrete examples** for non-obvious parameters or workflows.
+
+See instructions-guide.md for length guidelines, templates, and common mistakes.
+
+## Attaching References & Scripts
+
+- Attach named documents (references) for deep-dive content agents can fetch on demand.
+- Attach executable scripts for automation the agent can run via \`execute_script\`.
+- Agents will see learning paths and execution paths automatically in the learn response.
+
+See related-resources.md for naming conventions and content guidelines.`,
+    related: [
+      {
+        name: "instructions-guide.md",
+        description: "Writing instructions: tone, length, structure, and common mistakes",
+        mimetype: "text/markdown",
+        content: `# Writing Effective Skill Instructions
+
+## Principles
+
+**Be concise.** Instructions are shown on \`learn\`. Keep them scannable \u2014 agents read to act, not to study.
+
+**Imperative voice.** Write "Query the database using the filter parameter" not "The database can be queried using..."
+
+**Progressive disclosure.** Put deep detail in \`@references/...\` documents.
+- Instructions = orientation (what this skill does and how to start)
+- References = manual (edge cases, full field lists, error codes)
+
+**Give examples.** When a parameter or workflow is non-obvious, include a one-liner example inline.
+
+---
+
+## Recommended Structure
+
+\`\`\`markdown
+Brief description of what this skill does and when to use it.
+
+## Core Concepts
+- Key term 1: brief definition
+- Key term 2: brief definition
+
+## How To Use
+1. First step with example
+2. Second step
+3. Third step
+
+## Important Constraints
+- Limitation or gotcha 1
+- Limitation or gotcha 2
+
+For deeper guidance, see:
+- @references/doc-name.md \u2014 what it covers
+\`\`\`
+
+---
+
+## Length Guidelines
+
+| Skill complexity        | Instructions length |
+|-------------------------|---------------------|
+| Simple (1\u20133 tools)      | 50\u2013150 words        |
+| Moderate (4\u20138 tools)    | 150\u2013300 words       |
+| Complex (workflow)      | 200\u2013400 words       |
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Listing all tool parameters inline | Move to a reference document |
+| "Use the tools as needed" (too vague) | Give concrete step-by-step guidance |
+| No examples for ambiguous inputs | Add a one-liner example per non-obvious param |
+| Missing constraints | State rate limits, permissions, error conditions |
+| Instructions longer than 500 words | Split into references |
+`
+      },
+      {
+        name: "related-resources.md",
+        description: "How to attach, name, and document references and scripts",
+        mimetype: "text/markdown",
+        content: `# Attaching References and Scripts
+
+## References
+
+References are named markdown documents attached to a skill. They appear in the learn response as paths the agent can fetch on demand.
+
+### Creating a Reference
+
+In the Studio UI: **Skill \u2192 References tab \u2192 Add Reference**
+Via Skilder MCP server: \`create_skill_reference\` tool
+
+### Naming Conventions
+
+Use descriptive, hyphenated names with \`.md\` extension:
+- \`api-guide.md\` \u2014 REST endpoint documentation
+- \`field-mapping.md\` \u2014 Input/output field mappings
+- \`error-codes.md\` \u2014 Error code reference
+- \`examples.md\` \u2014 Request/response examples
+
+### Mentioning in Instructions
+
+Use \`@references/filename.md\` anywhere in the instructions text. The learn response automatically generates the learning path:
+
+\`\`\`
+learn --path "/Skill Name/references/filename.md"
+\`\`\`
+
+### Content Guidelines
+
+- References should be **self-contained** documents
+- Use headers, tables, and code blocks freely
+- Include examples, not just definitions
+- References can be updated independently of skill instructions
+
+---
+
+## Scripts
+
+Scripts are executable code attached to a skill. They run on the linked edge runtime.
+
+### Supported Types
+
+- **Python** \u2014 \`.py\` files
+- **Bash** \u2014 \`.sh\` files (on compatible runtimes)
+
+### Mentioning in Instructions
+
+Use \`@scripts/filename.py\` in instructions. The learn response shows the execution path:
+
+\`\`\`
+execute_script --path "/Skill Name/scripts/filename.py --arg=value"
+\`\`\`
+
+### Best Practices
+
+- Add a \`--help\` argument to scripts for self-documentation
+- Use descriptive argument names
+- Keep scripts focused \u2014 one script per distinct operation
+- Document expected inputs and outputs in the script header comment
+`
+      }
+    ]
+  },
+  {
+    slug: "skilder-platform-expert",
+    name: "Skilder Platform Expert",
+    description: "Full conceptual guide: entities, relationships, constraints, and common workflows for managing a Skilder workspace",
+    tags: ["skilder", "meta", "platform"],
+    instructions: `Master the Skilder platform entities and their relationships.
+
+## Core Entities
+
+- **Workspace** \u2014 Tenant boundary. All resources (hats, skills, runtimes) are workspace-scoped.
+- **Hat** \u2014 A named, color-coded collection of skills. Represents a role or persona for an agent.
+- **Skill** \u2014 A unit of capability: instructions + MCP tools + references + scripts.
+- **MCP Tool** \u2014 A callable tool exposed by an external MCP server, linked to a skill.
+- **Reference** \u2014 A named markdown document attached to a skill for contextual knowledge.
+- **Script** \u2014 Executable code (Python, Bash) attached to a skill, run via \`execute_script\`.
+- **Runtime** \u2014 An edge runtime instance that connects external MCP servers to Skilder.
+
+## Key Relationships
+
+\`\`\`
+Workspace
+\u2514\u2500\u2500 Hats \u2192 Skills \u2192 MCP Tools (served by Runtimes)
+              \u2514\u2500\u2500 References (markdown knowledge)
+              \u2514\u2500\u2500 Scripts (executable automation)
+\`\`\`
+
+## Common Workflows
+
+1. **Add a skill**: Create skill \u2192 attach MCP tools from a runtime \u2192 add references \u2192 assign to a hat
+2. **Agent connects**: \`init_skilder\` \u2192 \`learn /hats/Hat Name\` or \`learn /Skill Name\` \u2192 use unlocked tools
+3. **Import from GitHub**: Use the GitHub import to pull SKILL.md + references from a repo
+
+For deeper guidance, see:
+- entities.md \u2014 full entity reference with all fields and constraints
+- workflows.md \u2014 step-by-step common workflows with the Skilder MCP server
+- mcp-tools.md \u2014 how MCP tools are registered, routed, and exposed to agents`,
+    related: [
+      {
+        name: "entities.md",
+        description: "Full entity reference with all fields and constraints",
+        mimetype: "text/markdown",
+        content: `# Skilder Entity Reference
+
+## Workspace
+
+The top-level organizational boundary. Every resource belongs to exactly one workspace.
+
+| Field | Type | Notes |
+|---|---|---|
+| id | ID | Immutable |
+| name | String | Display name |
+| slug | String | URL-safe identifier |
+| members | [User] | Workspace members with roles |
+
+**Constraints:** Skills, hats, and runtimes cannot be shared across workspaces.
+
+---
+
+## Hat
+
+A named, color-coded collection of skills representing a role.
+
+| Field | Type | Notes |
+|---|---|---|
+| id | ID | Immutable |
+| name | String | Role name shown to agents |
+| description | String | Brief role description (shown in init_skilder) |
+| instructions | String | Full hat-level guidance revealed on learn |
+| color | String | Hex color (e.g., \`#3B82F6\`) |
+| skills | [Skill] | Ordered list of skills in this hat |
+| disabled | Boolean | If true, hidden from agents |
+
+**Constraints:** A skill can belong to multiple hats. A hat must have at least one enabled skill to appear in \`init_skilder\`.
+
+---
+
+## Skill
+
+A unit of capability: instructions, tools, references, and scripts.
+
+| Field | Type | Notes |
+|---|---|---|
+| id | ID | Immutable |
+| name | String | Used as the learn path segment (e.g., \`learn "/My Skill"\`) |
+| description | String | \u2264 500 chars; shown before the agent learns the skill |
+| instructions | String | Full instructions revealed on \`learn\` |
+| mcpTools | [MCPTool] | Tools exposed when skill is learned |
+| references | [SkillReference] | Named knowledge documents |
+| scripts | [SkillScript] | Executable scripts |
+| disabled | Boolean | If true, hidden from agents and the catalog |
+
+**Constraints:** Skill names must be unique within a workspace. Description is capped at 500 characters.
+
+---
+
+## MCP Tool
+
+An individual callable tool from an external MCP server.
+
+| Field | Type | Notes |
+|---|---|---|
+| id | ID | Immutable |
+| name | String | Tool name as registered in the MCP server |
+| description | String | Shown in the agent's tool list |
+| inputSchema | JSON | JSON Schema for tool arguments |
+| mcpServer | MCPServer | The server that provides this tool |
+
+**Constraints:** Tool names must be globally unique within a workspace (they are merged into a single tool list per agent session).
+
+---
+
+## Skill Reference
+
+A named markdown document attached to a skill.
+
+| Field | Type | Notes |
+|---|---|---|
+| id | ID | Immutable |
+| name | String | Filename used in the learn path (e.g., \`api-guide.md\`) |
+| description | String | Brief description shown in the References section |
+| instructions | String | Full markdown content of the document |
+
+**Access path:** \`learn "/Skill Name/references/filename.md"\`
+
+---
+
+## Skill Script
+
+Executable code attached to a skill.
+
+| Field | Type | Notes |
+|---|---|---|
+| id | ID | Immutable |
+| name | String | Filename used in the execute path (e.g., \`transform.py\`) |
+| type | ScriptType | PYTHON | BASH |
+| code | String | Script source code |
+| runtime | Runtime | The edge runtime that will execute the script |
+
+**Execution path:** \`execute_script "/Skill Name/scripts/filename.py --arg=value"\`
+
+---
+
+## Runtime
+
+An edge runtime instance that connects external MCP servers to Skilder.
+
+| Field | Type | Notes |
+|---|---|---|
+| id | ID | Immutable |
+| name | String | Display name |
+| runtimeId | String | Unique runtime identifier for NATS routing |
+| mcpServers | [MCPServer] | MCP servers managed by this runtime |
+
+**Notes:** Scripts are linked to a specific runtime. MCP tools are linked to an MCP server, which belongs to a runtime.
+`
+      },
+      {
+        name: "workflows.md",
+        description: "Step-by-step common workflows with the Skilder MCP server",
+        mimetype: "text/markdown",
+        content: `# Common Skilder Workflows
+
+These workflows use the Skilder MCP server tools available after connecting.
+
+---
+
+## Create a Skill
+
+1. **Create the skill** using \`create_skill\` with name and description.
+2. **Add instructions** via \`update_skill\` \u2014 keep them concise (see Skilder Skill Architect skill).
+3. **Attach MCP tools** using \`add_mcp_tool_to_skill\` \u2014 tools must already exist on a runtime.
+4. **Add references** using \`create_skill_reference\` for each knowledge document.
+5. **Assign to a hat** using \`add_skill_to_hat\` \u2014 or create a new hat first.
+
+---
+
+## Create a Hat
+
+1. **Create the hat** using \`create_hat\` with name, description, and color.
+2. **Add skills** using \`add_skill_to_hat\` \u2014 skills must already exist.
+3. **Set hat instructions** (optional) via \`update_hat\` for hat-level agent guidance.
+
+---
+
+## Import a Skill from GitHub
+
+Use \`import_skill_from_github\` with the repository URL and path to the SKILL.md file.
+
+The import reads:
+- \`SKILL.md\` \u2014 skill metadata (name, description) and instructions
+- \`references/\` directory \u2014 all \`.md\` files become skill references
+- \`scripts/\` directory \u2014 all script files become skill scripts (linked to a specified runtime)
+
+---
+
+## Update a Skill's Instructions
+
+Use \`update_skill\` with the \`instructions\` field. Changes take effect on the next agent session (the catalog is rebuilt on each user handshake).
+
+---
+
+## Disable a Skill or Hat
+
+Use \`update_skill\` or \`update_hat\` with \`disabled: true\`. The resource is hidden from agents immediately (the catalog is refreshed on next connection).
+
+---
+
+## Agent Session Lifecycle
+
+1. Agent connects to the Skilder runtime (via MCP server URL).
+2. Runtime receives the workspace catalog from the backend via NATS.
+3. Agent calls \`init_skilder\` \u2014 sees available hats and skills (name + description only).
+4. Agent calls \`learn "/hats/Hat Name"\` or \`learn "/Skill Name"\` \u2014 receives full instructions + tool list.
+5. Newly unlocked MCP tools appear in the agent's tool list immediately.
+6. Agent calls \`execute_script\` to run attached scripts on the edge runtime.
+`
+      },
+      {
+        name: "mcp-tools.md",
+        description: "How MCP tools are registered, routed, and exposed to agents",
+        mimetype: "text/markdown",
+        content: `# MCP Tool Registration and Routing
+
+## Overview
+
+MCP tools in Skilder are not defined directly \u2014 they are **discovered** from external MCP servers running on edge runtimes. The flow is:
+
+\`\`\`
+External MCP Server \u2192 Runtime (discovers tools) \u2192 Skilder (stores MCPTool nodes) \u2192 Skill (attaches tools) \u2192 Agent (uses tools)
+\`\`\`
+
+---
+
+## Registration
+
+When an edge runtime starts, it:
+1. Spawns or connects to the external MCP servers configured for that runtime.
+2. Calls \`tools/list\` on each MCP server.
+3. Registers the discovered tools as \`MCPTool\` nodes in Skilder (linked to the runtime's MCP server).
+
+Tools are re-registered on runtime restart. If a tool's input schema changes, the stored node is updated.
+
+---
+
+## Routing
+
+When an agent calls an MCP tool:
+
+1. The user runtime looks up the tool's routing info (\`skillId\`, \`runtimeId\`).
+2. It publishes a \`SkillCallToolRequest\` to NATS subject: \`{workspaceId}.call-tool.{toolId}.{runtimeId}\`
+3. The target edge runtime receives the request and forwards it to the appropriate MCP server.
+4. The response is returned via NATS and forwarded to the agent.
+
+**Timeout:** Default tool call timeout is configurable; long-running operations should use scripts instead.
+
+---
+
+## Tool Name Uniqueness
+
+Tool names must be **globally unique** within a workspace. If two MCP servers provide a tool with the same name, only one can be linked to a skill. Use the MCP server's tool name prefix feature to disambiguate.
+
+---
+
+## Progressive Exposure
+
+Tools are not visible to the agent until the skill they belong to is learned. This keeps the agent's tool list focused on what is relevant for the current task.
+
+- After \`init_skilder\`: only static tools are visible (\`init_skilder\`, \`learn\`, \`execute_script\`, \`feedback_skill\`).
+- After \`learn "/Skill Name"\`: all tools linked to that skill are added to the tool list.
+- After \`learn "/hats/Hat Name"\`: all tools from all skills in that hat are added.
+`
+      }
+    ]
+  },
+  {
+    slug: "skilder-hat-designer",
+    name: "Skilder Hat Designer",
+    description: "Design role-based hat collections: org unit mapping, skill selection, and color conventions",
+    tags: ["skilder", "meta", "hats"],
+    instructions: `Design effective hat collections that give agents focused, role-appropriate context.
+
+## What Is a Hat?
+
+A hat is a named role a workspace assigns to an agent. It bundles a set of skills the agent needs for that role, using a color for quick visual identification in the Studio UI.
+
+## Design Principles
+
+- **One hat per role** \u2014 Align hats with job functions (e.g., "Customer Support Specialist", "Finance Analyst"), not tasks.
+- **Minimal skill sets** \u2014 Include only skills the role actually needs. Smaller hats mean faster, more focused agents.
+- **Clear names** \u2014 Use role names agents can recognize: "Senior DevOps Engineer" not "Hat 1".
+- **Hat-level instructions** \u2014 Use the hat's \`instructions\` field for role-level context that applies to all skills in the hat.
+
+## Org Unit Mapping
+
+Map hats to organizational units (teams, departments, functions):
+- A hat can be shared across multiple org units if roles overlap.
+- Create separate hats for roles with meaningfully different skill sets, even within the same team.
+- Avoid creating redundant hats for minor variations \u2014 use skill \`instructions\` differences instead.
+
+## Color Conventions
+
+Colors should reflect the function or urgency of the role. See color-palette.md for exact hex codes.
+
+| Role type | Color family | Example |
+|---|---|---|
+| Technical / Engineering | Blue | \`#3B82F6\` |
+| Operations / Support | Green | \`#10B981\` |
+| Customer-facing / Sales | Orange | \`#F59E0B\` |
+| Admin / Governance | Red | \`#EF4444\` |
+| Creative / Strategy | Purple | \`#8B5CF6\` |
+| Data / Analytics | Teal | \`#14B8A6\` |
+
+For a complete hat design guide with examples and anti-patterns, see hat-design-guide.md.`,
+    related: [
+      {
+        name: "hat-design-guide.md",
+        description: "Complete hat design guide with examples, anti-patterns, and org mapping templates",
+        mimetype: "text/markdown",
+        content: `# Hat Design Guide
+
+## Anatomy of a Well-Designed Hat
+
+A good hat has:
+- **A focused role name** that an agent can understand without ambiguity
+- **A concise description** (1\u20132 sentences) explaining the role's purpose
+- **Hat-level instructions** for context that applies across all skills in the hat (e.g., tone, constraints, escalation rules)
+- **3\u20138 skills** \u2014 enough to cover the role's needs without overwhelming the agent
+- **A consistent color** that matches the role's function
+
+---
+
+## Examples
+
+### Good Hat Design: "Customer Support Tier 1"
+
+\`\`\`
+Name: Customer Support Tier 1
+Description: Handle inbound customer inquiries, ticket triage, and FAQ resolution
+Color: #F59E0B (orange \u2014 customer-facing)
+Skills:
+  - Ticket Management (create, update, close tickets)
+  - Knowledge Base Search (large article set)
+  - Customer Profile Lookup (read-only CRM access)
+Instructions: "Always greet customers by first name. Escalate to Tier 2 if resolution
+              requires more than 3 tool calls. Log all interactions."
+\`\`\`
+
+### Anti-Pattern: "Everything Hat"
+
+\`\`\`
+Name: General Assistant
+Skills: (20 skills covering billing, HR, DevOps, marketing, legal...)
+\`\`\`
+
+**Problem:** The agent sees every tool from every skill after learning the hat. This floods the tool list and dilutes focus.
+
+**Fix:** Split into role-specific hats. Use \`learn "/Skill Name"\` for ad-hoc access to individual skills.
+
+---
+
+## Skill Selection Checklist
+
+For each skill you consider adding to a hat, ask:
+- [ ] Does this role need this capability in their typical workflow?
+- [ ] Would an agent in this role be authorized to use these tools?
+- [ ] Does this skill's instructions align with this role's context?
+- [ ] Are there fewer than 10 skills in the hat already?
+
+---
+
+## Org Unit Mapping Template
+
+| Org Unit | Primary Hat | Secondary Hat (optional) |
+|---|---|---|
+| Engineering | "Software Engineer" | "DevOps Operator" |
+| Finance | "Finance Analyst" | "Finance Admin" |
+| HR | "HR Business Partner" | \u2014 |
+| Customer Support | "CS Tier 1" | "CS Tier 2" |
+| Legal | "Legal Reviewer" | \u2014 |
+
+**Note:** Agents typically wear one hat per session. Design hats for the most common single-session workflow, not for covering every possible task.
+
+---
+
+## Hat Instructions Best Practices
+
+Hat-level \`instructions\` appear when an agent learns the hat (before individual skill instructions). Use them for:
+- Role identity framing ("You are a Senior Support Specialist...")
+- Cross-skill constraints ("Always check the customer's entitlement before using billing tools")
+- Escalation rules ("If unsure, prefer learn over act")
+- Tone and communication style guidance
+
+Keep hat instructions under 200 words \u2014 they are shown alongside each skill's instructions, so context adds up quickly.
+`
+      },
+      {
+        name: "color-palette.md",
+        description: "Exact color codes and usage conventions for each role type",
+        mimetype: "text/markdown",
+        content: `# Hat Color Palette
+
+Colors are stored as hex strings (e.g., \`#3B82F6\`). Use the role-type conventions below for consistency across your workspace.
+
+---
+
+## Technical / Engineering
+
+| Shade | Hex | Usage |
+|---|---|---|
+| Blue 500 | \`#3B82F6\` | General engineering roles |
+| Blue 700 | \`#1D4ED8\` | Senior / lead engineering roles |
+| Indigo 500 | \`#6366F1\` | Platform / infrastructure roles |
+| Cyan 500 | \`#06B6D4\` | Backend / API roles |
+
+---
+
+## Operations / Support
+
+| Shade | Hex | Usage |
+|---|---|---|
+| Green 500 | \`#10B981\` | General operations |
+| Green 700 | \`#047857\` | Operations leads |
+| Lime 500 | \`#84CC16\` | IT support |
+| Emerald 500 | \`#10B981\` | Service reliability |
+
+---
+
+## Customer-Facing / Sales
+
+| Shade | Hex | Usage |
+|---|---|---|
+| Amber 500 | \`#F59E0B\` | Customer support |
+| Orange 500 | \`#F97316\` | Sales / Account management |
+| Yellow 500 | \`#EAB308\` | Marketing |
+
+---
+
+## Admin / Governance
+
+| Shade | Hex | Usage |
+|---|---|---|
+| Red 500 | \`#EF4444\` | Admin roles |
+| Rose 500 | \`#F43F5E\` | Compliance / Legal |
+| Red 700 | \`#B91C1C\` | Security / Audit |
+
+---
+
+## Creative / Strategy
+
+| Shade | Hex | Usage |
+|---|---|---|
+| Purple 500 | \`#8B5CF6\` | Product / Strategy |
+| Violet 500 | \`#7C3AED\` | Design / UX |
+| Fuchsia 500 | \`#D946EF\` | Creative / Content |
+
+---
+
+## Data / Analytics
+
+| Shade | Hex | Usage |
+|---|---|---|
+| Teal 500 | \`#14B8A6\` | Data analysts |
+| Sky 500 | \`#0EA5E9\` | Data engineers |
+| Slate 500 | \`#64748B\` | Reporting / BI |
+
+---
+
+## Neutral / Cross-Functional
+
+| Shade | Hex | Usage |
+|---|---|---|
+| Gray 500 | \`#6B7280\` | Cross-functional or temporary roles |
+| Stone 500 | \`#78716C\` | General purpose / sandbox |
+
+---
+
+## Tips
+
+- Use **darker shades** for senior/lead variants of a role.
+- Keep color assignments **consistent** across your workspace \u2014 the same role type should always use the same color family.
+- Avoid using the same hex for two different hats in the same workspace \u2014 agents and users will confuse them.
+`
+      }
+    ]
+  }
+];
+
+// ../common/src/skill-catalog-onboarding.ts
+var ONBOARDING_FEATURED_SKILLS = [
+  {
+    slug: "human-discovery",
+    name: "Human Discovery",
+    description: `Use this skill to help a person discover what AI skill would be most useful for their job. Trigger whenever someone says things like "I don't know where to start with AI", "what skill should I create", "help me find a use case", "I'm not technical but want to use AI", "suggest a skill for my job", or anything that implies they want AI help but don't know how. Walk them through a guided discovery process: understand their job in 4 questions or fewer, suggest 3 pain points addressable by a Claude skill (no heavy integrations), let them pick one, interview them briefly, then write the skill together.`,
+    tags: ["discovery", "onboarding", "first-time-user"],
+    instructions: `# Skill Discovery for first time user \u2014 Find the Right AI Skill for Any Job
+
+You are helping a non-technical person discover which AI skill would make the biggest difference in their work. Your tone should be **warm, curious, and jargon-free**. Never use terms like "LLM", "prompt", "API", "workflow automation". Speak like a friendly colleague, not a consultant. Apply ALWAYS if the user say he is new, first time using, don't know what to do with AI.
+
+---
+
+## Phase 1: Discover the Human (max 4 questions)
+
+Your goal is to build a clear picture of who this person is and where they struggle \u2014 in 4 questions or fewer. Use \`ask_user_input_v0\` for every question. **Do not ask all 4 at once.** Ask one (or at most two related ones) at a time, let their answer guide what you ask next.
+
+### Question arc
+
+**Q1 \u2014 Role/Activity** (free text, always first)
+
+> "What's your job, or what do you mainly spend your time doing?"
+
+**Q2 \u2014 Hierarchy position** (single select) Options: Individual contributor / Team lead or manager / Senior leader or executive / Freelancer or solo / Other
+
+**Q3 \u2014 Company domain and size** (two quick selects, ask together)
+
+- Domain: Technology / Finance & legal / Healthcare / Education / Retail & commerce / Industrial & manufacturing / Public sector / Services & consulting / Other
+- Size: Just me / Small team (2\u201320) / Mid-size company (20\u2013500) / Large organization (500+)
+
+**Q4 \u2014 Bonus question** (free text, optional feel)
+
+> "Is there any part of your job you'd love to hand off to someone else \u2014 even partially?"
+
+This last question is the golden one: it surfaces self-identified pain in their own words, which feeds directly into Phase 2.
+
+### Never skip Q4
+
+Even if you feel you have enough context after Q3, always ask Q4. The bonus question often reveals the most actionable pain point and gives you their exact vocabulary to use in the skill.
+
+---
+
+## Phase 2: Suggest 3 Pain Points
+
+Based on what you learned, **reason carefully** about what genuinely frustrates people in this role. Then propose exactly **3 pain points**, each one:
+
+- A real, recurring frustration (not a vague category)
+- Solvable by Claude working with text, documents, or structured thinking
+- Requiring **no system integrations** (or at most: "paste text in" / "upload a file")
+- Described in plain human language
+
+### Format for each pain point card
+
+Present them conversationally, like this:
+
+---
+
+**1. [Short, vivid title]** *What happens:* [1 sentence describing the frustration in their words/world] *What a skill could do:* [1 concrete sentence \u2014 what Claude would actually produce] *Effort to set up:* Zero \u2014 just paste or upload
+
+---
+
+After presenting all 3, ask:
+
+> "Do any of these ring a bell? Pick the one that would save you the most time or headaches."
+
+Use \`ask_user_input_v0\` with the 3 titles as options (plus "None of these feel right").
+
+If they say "none of these", ask one follow-up: "What's the thing at work that you keep putting off because it feels tedious?" Then generate 3 new suggestions.
+
+---
+
+## Phase 3: Interview Before Writing
+
+Once they've picked a pain point, **don't jump straight to writing the skill**. Ask 2\u20133 short, focused questions to understand:
+
+1. **A concrete example** \u2014 "Can you describe a real situation where this came up recently? Even roughly."
+2. **What good looks like** \u2014 "When it goes well, what does the result look like? (An email? A summary? A checklist?)"
+3. **The raw material** \u2014 "What do you usually start with? (A document, notes, an email thread, something else?)"
+
+Keep these conversational. Use \`ask_user_input_v0\` where options make sense (e.g. output format), free text where you need specifics.
+
+---
+
+## Phase 4: Write the Skill Together
+
+Now write a SKILL.md tailored to their pain point. Follow these principles:
+
+### Skill writing rules for non-technical users
+
+- **Name**: Short, verb-first, plain English (e.g. \`contract-plain-language\`, \`meeting-notes-to-actions\`)
+- **Description**: Written so skilder knows exactly when to offer this skill \u2014 include the phrases this person would naturally say
+- **Instructions**: Written as if explaining to a smart colleague, not a machine. No jargon.
+- **Input**: Always "paste your text below" or "upload your document" \u2014 never assume integrations
+- **Output**: One clear, usable thing (a draft, a list, a summary, a set of questions \u2014 not "analysis")
+
+### Skill structure to follow
+
+\`\`\`plaintext
+---
+name: [verb-noun]
+description: >
+  Use this skill when [person's role] needs to [specific task].
+  Trigger when they say things like "[natural phrase 1]", "[natural phrase 2]".
+---
+
+# [Skill Name]
+
+## What this does
+[1\u20132 sentences. Plain language.]
+
+## How to use it
+[2\u20133 steps. Ultra simple. "Paste your text." "Tell skilder what you need." "Get your result."]
+
+## What skilder will produce
+[Describe the output concretely.]
+
+## Example
+Input: [short realistic example]
+Output: [what skilder would return]
+\`\`\`
+
+### After writing
+
+Show them the full skill file and ask:
+
+> "Does this feel right? Is there anything about your situation I've got wrong or missed?"
+
+Incorporate their feedback, then present the final \`.skill\` file for adding to workspace. If they ask about integrations (ex. spreadsheet folder, email, other systems or database), verify the tool list to see what's configured and accessible. If nothing exist or match, you must suggest to save the skill as-is and add Tools later. NEVER encourage manual work.
+
+---
+
+## Tone reminders (apply throughout)
+
+- Never say "workflow", "automate", "prompt", "LLM", "model", or "integrate"
+- Say "save you time", "take care of the tedious part", "handle the first draft"
+- If they seem unsure or intimidated, reassure: "You don't need to know anything technical \u2014 we're just figuring out what would be most useful for you."
+- Keep every message short. One idea at a time.`,
+    related: []
+  }
+];
+
+// ../common/src/skill-catalog-business.ts
+var BUSINESS_FEATURED_SKILLS = [
+  {
+    slug: "product-and-service-catalog",
+    name: "Product & Service Catalog",
+    description: `Use this skill to answer employee questions about what the company sells: products, services, descriptions, pricing, packages, and who owns each line. Trigger on questions like "what's the price of X", "do we offer Y", "describe service Z", "what's included in our Premium plan", "who do I talk to for X".`,
+    tags: ["business", "reference", "template"],
+    instructions: `Answer employee questions about the company's products and services using the catalog reference document.
+
+## How to use
+
+1. Read @references/product-catalog.md to find the matching product or service entry.
+2. Quote the relevant fields directly (name, description, price, status, contact).
+3. If the question is comparative ("which plan fits a small team?"), summarise the relevant rows in plain language \u2014 don't dump the full table.
+4. If the data hasn't been filled in yet (placeholders like {Product Name} still present), tell the user the catalog hasn't been populated and point them at the template.
+
+## Constraints
+
+- **Do not invent products, prices, or features.** If it isn't in the catalog, say so and offer to flag it for the catalog owner.
+- **Mention status fields** when present (e.g. "Discontinued", "Beta", "Coming soon"). Don't quote prices for inactive items without flagging the status.
+- **Internal pricing or margin info** stays internal \u2014 if the reference marks a row as "Confidential", do not share with external-facing roles without confirming the requester's permission.
+
+## Maintenance
+
+The catalog template lives in @references/product-catalog.md. Replace placeholder rows with your real product lines; the structure is intentionally flat to make updates fast. Owners are expected to keep status and pricing accurate.`,
+    related: [
+      {
+        name: "product-catalog.md",
+        description: "Template product & service catalog \u2014 replace placeholder rows with real data.",
+        mimetype: "text/markdown",
+        content: `# Product & Service Catalog
+
+> **Template \u2014 replace the example rows with your real products and services.** Keep the column structure so the agent can read the data reliably.
+
+## Active products & services
+
+| Name | Category | Description | Price | Unit | Status | Owner |
+|---|---|---|---|---|---|---|
+| {Product A} | {Hardware / Software / Service} | {One-line description of what it does} | {0.00} | {per unit / per month / per project} | Active | {Owner name or team} |
+| {Product B} | {Category} | {Description} | {0.00} | {Unit} | Active | {Owner} |
+| {Service C} | Service | {Description} | {0.00} | per hour | Active | {Owner} |
+
+## Packages & bundles
+
+| Bundle | Includes | Price | Notes |
+|---|---|---|---|
+| {Starter Pack} | {Product A + Product B} | {0.00} | {Volume discount, contract length, etc.} |
+
+## Inactive / archived
+
+| Name | Status | Replaced by |
+|---|---|---|
+| {Old Product} | Discontinued ({date}) | {New Product} |
+
+## Maintenance notes
+
+- Update the **Status** column whenever a product is launched, paused, or retired.
+- Mark rows **Confidential** in the Notes column if internal-only pricing should not be shared externally.
+- Keep one row per SKU \u2014 split bundles into the Packages section.
+`
+      }
+    ]
+  },
+  {
+    slug: "customer-directory",
+    name: "Customer Directory",
+    description: `Use this skill to look up information about the company's customers: contact details, account manager, account status, recent interactions. Trigger on questions like "who is X", "what's the account manager for Y", "how do we contact Z", "what's the status of customer X", "when did we last talk to Y".`,
+    tags: ["business", "reference", "template"],
+    instructions: `Help employees find customer information using the customer directory reference document.
+
+## How to use
+
+1. Read @references/customer-directory.md to locate the customer by name, company, or account ID.
+2. Share the requested field(s): contact, account manager, status, last interaction date.
+3. For broader questions ("which customers are inactive?"), summarise the matching rows.
+4. If the data still contains placeholders, tell the user the directory hasn't been populated yet.
+
+## Privacy & access
+
+- @references/customer-access-policy.md defines what to share with whom. Follow it.
+- Default to sharing only **business contact info** (name, role, work email/phone, account status).
+- **Do not share** financial details, contract terms, or personal info to roles not listed as "Full access" in the access policy.
+- If unsure who has access, ask the requester to confirm their role before answering.
+
+## Constraints
+
+- Don't invent or guess contact details. If a customer isn't listed, say so.
+- For sensitive lookups (account churn, contract value), confirm the requester's role first.
+
+## Maintenance
+
+Keep @references/customer-directory.md up to date when account managers change or status flips. The access policy is the source of truth for who can see what.`,
+    related: [
+      {
+        name: "customer-directory.md",
+        description: "Template customer directory \u2014 replace placeholder rows with real customers.",
+        mimetype: "text/markdown",
+        content: `# Customer Directory
+
+> **Template \u2014 replace the example rows with your real customer list.** Keep the columns so the agent can answer lookups reliably.
+
+| Account ID | Company | Primary Contact | Role | Email | Phone | Account Manager | Status | Last Interaction | Notes |
+|---|---|---|---|---|---|---|---|---|---|
+| {ACME-001} | {Acme Corp} | {Jane Doe} | {Head of Ops} | {jane@acme.example} | {+1 555 0100} | {Account Manager Name} | Active | {YYYY-MM-DD} | {Renewal Q3} |
+| {GLOBEX-002} | {Globex} | {John Smith} | {VP Sales} | {john@globex.example} | {+1 555 0101} | {Account Manager Name} | At-risk | {YYYY-MM-DD} | {Pricing escalation open} |
+| {INITECH-003} | {Initech} | {Alex Wong} | {Procurement Lead} | {alex@initech.example} | {+1 555 0102} | {Account Manager Name} | Inactive | {YYYY-MM-DD} | {Contract ended {date}} |
+
+## Status legend
+
+- **Active** \u2014 current paying customer
+- **At-risk** \u2014 flagged by account manager; escalation in flight
+- **Inactive** \u2014 no current contract; do not contact without approval
+- **Prospect** \u2014 in sales pipeline, not yet a customer
+
+## Maintenance notes
+
+- Update **Status** and **Last Interaction** after each meaningful touchpoint.
+- Mark Notes as **Confidential** if they reference negotiation or churn risk.
+`
+      },
+      {
+        name: "customer-access-policy.md",
+        description: "Template access policy \u2014 who can see which customer fields.",
+        mimetype: "text/markdown",
+        content: `# Customer Information Access Policy
+
+> **Template \u2014 replace placeholder roles with the actual roles in your workspace.** This policy controls what the Business Assistant will share with each requester.
+
+## Access levels
+
+| Role | Contact info | Account status | Account manager | Financial / contract | Sensitive notes |
+|---|---|---|---|---|---|
+| {Sales team} | \u2705 | \u2705 | \u2705 | \u2705 | \u2705 |
+| {Customer support} | \u2705 | \u2705 | \u2705 | \u274C | \u274C |
+| {Operations / delivery} | \u2705 | \u2705 | \u2705 | \u274C | \u274C |
+| {General employee} | \u2705 business email only | \u2705 | \u2705 | \u274C | \u274C |
+| {External / unknown} | \u274C | \u274C | \u274C | \u274C | \u274C |
+
+## When to refuse
+
+- The requester's role isn't listed \u2192 ask them to confirm their role first.
+- The customer is marked **Inactive** \u2192 require explicit approval from the listed account manager before sharing.
+- Notes are flagged **Confidential** \u2192 do not share unless the role has "Sensitive notes" access.
+
+## When to escalate
+
+- Requests for bulk export of the directory \u2192 escalate to the data owner.
+- Repeated lookups across many customers from a single user \u2192 flag to the workspace admin.
+`
+      }
+    ]
+  },
+  {
+    slug: "supplier-directory",
+    name: "Supplier Directory",
+    description: `Use this skill to look up information about the company's suppliers and vendors: who supplies what, contact details, contract end dates, lead times, payment terms. Trigger on questions like "who supplies X", "how do we contact supplier Y", "when does our contract with Z expire", "what's our lead time for component A".`,
+    tags: ["business", "reference", "template"],
+    instructions: `Answer employee questions about suppliers and vendors using the supplier directory reference document.
+
+## How to use
+
+1. Read @references/supplier-directory.md to find the supplier by name, category, or what they provide.
+2. Share the requested fields: contact, contract end date, lead time, payment terms.
+3. For "who supplies X" questions, scan the Category and What we buy columns; list all matches.
+4. If the data still contains placeholders, tell the user the directory hasn't been populated yet.
+
+## Constraints
+
+- **Don't invent suppliers or contract terms.** If something isn't listed, say so.
+- **Flag expiring contracts** proactively when the user asks about a supplier whose contract end date is within 60 days.
+- **Confidential pricing** (marked in the Notes column) should not be shared outside procurement without confirmation.
+
+## Maintenance
+
+The directory at @references/supplier-directory.md is the source of truth. Procurement owners are expected to keep contract dates and contacts current; flag stale entries (no interaction in 12+ months) for review.`,
+    related: [
+      {
+        name: "supplier-directory.md",
+        description: "Template supplier directory \u2014 replace placeholder rows with real suppliers.",
+        mimetype: "text/markdown",
+        content: `# Supplier Directory
+
+> **Template \u2014 replace the example rows with your real suppliers.** Keep the columns so the agent can answer lookups reliably.
+
+| Supplier | Category | What we buy | Primary Contact | Email | Phone | Contract End | Lead Time | Payment Terms | Notes |
+|---|---|---|---|---|---|---|---|---|---|
+| {Supplier A} | {Hardware} | {Specific components} | {Contact name} | {contact@supplierA.example} | {+1 555 0200} | {YYYY-MM-DD} | {2 weeks} | {Net 30} | {Preferred vendor} |
+| {Supplier B} | {Services} | {Cleaning, facilities} | {Contact name} | {contact@supplierB.example} | {+1 555 0201} | {YYYY-MM-DD} | {N/A} | {Net 15} | {Auto-renews annually} |
+| {Supplier C} | {Software / SaaS} | {Specific tool} | {Contact name} | {contact@supplierC.example} | {+1 555 0202} | {YYYY-MM-DD} | {Immediate} | {Annual prepay} | {Confidential pricing} |
+
+## Category legend
+
+Common categories: Hardware, Software / SaaS, Services, Logistics, Marketing, Professional services, Utilities.
+
+## Maintenance notes
+
+- Update **Contract End** whenever a renewal or termination happens.
+- Mark Notes as **Confidential** for negotiated pricing or sensitive terms.
+- Archive (don't delete) ended suppliers \u2014 keep a row with Status: Archived for institutional memory.
+`
+      }
+    ]
+  },
+  {
+    slug: "team-weekly-planning",
+    name: "Team Weekly Planning",
+    description: `Use this skill to answer questions about who's working on what this week, who's on leave, project assignments, and team availability. Trigger on questions like "who's working on X this week", "is Y available", "who's on PTO this week", "what's the team doing", "who can I ask about project Z".`,
+    tags: ["business", "reference", "template"],
+    instructions: `Answer employee questions about team availability and assignments using the weekly planning reference document.
+
+## How to use
+
+1. Read @references/weekly-planning.md for the current week's assignments and availability.
+2. For "who's working on X", list the assigned team members and their availability for the week.
+3. For "is Y available", report the requested person's PTO and assignment load for the week.
+4. For "who's on PTO", list everyone with a PTO entry for the requested week.
+5. If the planning is stale (week marker is in the past), call this out and recommend asking the team lead for the current week.
+
+## Constraints
+
+- **Don't invent assignments or PTO.** If someone isn't listed, say so and suggest asking their manager.
+- **The planning reflects intent, not real-time status.** If the user needs live availability (e.g. "can Y join a call now?"), tell them to message the person directly.
+- **PTO reasons stay private.** Share "on PTO" but not the reason unless explicitly listed as public.
+
+## Maintenance
+
+The planning at @references/weekly-planning.md should be refreshed weekly (typically at week start by the team lead). Stale planning is worse than no planning \u2014 flag week dates older than 7 days for refresh.`,
+    related: [
+      {
+        name: "weekly-planning.md",
+        description: "Template weekly planning \u2014 replace placeholder rows with real assignments.",
+        mimetype: "text/markdown",
+        content: `# Team Weekly Planning
+
+> **Template \u2014 replace placeholders with this week's real assignments.** Update at the start of each week (typically Monday).
+
+## Week of {YYYY-MM-DD}
+
+### Assignments
+
+| Person | Role | Primary project | Other work | Availability | Notes |
+|---|---|---|---|---|---|
+| {Alice} | {Engineer} | {Project Alpha} | {Code reviews, on-call Tue} | Full week | {Focus blocks 9\u201312 daily} |
+| {Bob} | {Designer} | {Project Beta} | {Design system} | Mon\u2013Wed | {PTO Thu\u2013Fri} |
+| {Carol} | {PM} | {Project Alpha, Project Beta} | {Roadmap planning} | Full week | {} |
+| {Dan} | {Engineer} | \u2014 | \u2014 | PTO full week | {Back {YYYY-MM-DD}} |
+
+### Out of office this week
+
+| Person | Dates | Cover |
+|---|---|---|
+| {Dan} | {Mon\u2013Fri} | {Alice covers on-call} |
+| {Bob} | {Thu\u2013Fri} | {N/A \u2014 async} |
+
+### Project leads (current quarter)
+
+| Project | Lead | Backup |
+|---|---|---|
+| {Project Alpha} | {Carol} | {Alice} |
+| {Project Beta} | {Carol} | {Bob} |
+
+## Maintenance notes
+
+- Update **Week of** date every Monday. Stale dates make the agent give wrong answers.
+- Use **PTO**, **Half-day**, **Remote-only** in the Availability column for quick scanning.
+- Keep Project leads stable across the quarter \u2014 they're how people know who to escalate to.
+`
+      }
+    ]
+  }
+];
+
+// ../common/src/skill-catalog.ts
+var FEATURED_SKILLS = [
+  ...SKILDER_META_FEATURED_SKILLS,
+  ...ONBOARDING_FEATURED_SKILLS,
+  ...BUSINESS_FEATURED_SKILLS
+];
+
+// ../common/src/hat-catalog.ts
+var FEATURED_HATS = [
+  {
+    slug: "business-assistant",
+    name: "Business Assistant",
+    description: "Central internal info desk: any employee can ask about products, customers, suppliers, or this week's team plan and get a fast, sourced answer.",
+    color: "BLUE",
+    tags: ["business", "reference", "template"],
+    skillSlugs: [
+      "product-and-service-catalog",
+      "customer-directory",
+      "supplier-directory",
+      "team-weekly-planning"
+    ],
+    instructions: `You are the company's internal Business Assistant. Any employee can ask you about what we sell, who our customers and suppliers are, and what the team is working on this week. Your job is to give a fast, sourced answer \u2014 or to clearly say when you don't have the data.
+
+## Which skill to use
+
+- **What we sell** (products, services, pricing, packages) \u2192 Product & Service Catalog
+- **A specific customer** (contact, account manager, status) \u2192 Customer Directory
+- **A supplier or vendor** (contact, contract, lead time) \u2192 Supplier Directory
+- **Who's working on what / who's available** \u2192 Team Weekly Planning
+
+If a question spans skills (e.g. "which account manager handles Acme, and is she on PTO?"), use both skills in turn and combine the answer.
+
+## Operating principles
+
+- **Source every answer.** Quote the relevant rows from the reference document, don't paraphrase from memory.
+- **Don't invent data.** If the requested item isn't in the reference, say so plainly and suggest who owns the catalog so the user can ask for it to be added.
+- **Respect access policies.** The Customer Directory skill carries an access policy \u2014 follow it. If unsure who can see what, ask before sharing.
+- **Flag stale templates.** If a reference still contains placeholder values (\`{Product Name}\`, \`{Acme Corp}\`), tell the user the workspace hasn't populated it yet and point them at the template.
+- **Be concise.** Employees want a quick answer, not a wall of text. One or two lines for simple lookups; a short list for "who" or "which" questions.
+
+## Template hat \u2014 first-time setup
+
+This hat ships as a template. The bundled skills each include a reference document with placeholder content. Before this assistant is useful in your workspace, an owner needs to fill in the actual product list, customer directory, supplier directory, and weekly planning. The templates are intentionally simple markdown tables \u2014 open each skill's references tab and replace placeholders with your real data.`
+  },
+  {
+    slug: SKILDER_HAT_DEFAULTS.slug,
+    name: SKILDER_HAT_DEFAULTS.name,
+    description: SKILDER_HAT_DEFAULTS.description,
+    color: SKILDER_HAT_DEFAULTS.color,
+    tags: ["skilder", "meta", "admin"],
+    skillSlugs: [...SKILDER_SKILL_IDS],
+    instructions: SKILDER_HAT_DEFAULTS.instructions
+  }
+];
+
 // ../common/src/services/logger.service.ts
 var import_pino = __toESM(require_pino(), 1);
 var import_pino_pretty = __toESM(require_pino_pretty(), 1);
@@ -111426,6 +112585,51 @@ var EncryptionService = class EncryptionService2 {
   isEncrypted(value) {
     return value.startsWith(ENCRYPTED_PREFIX);
   }
+  /**
+   * Compute a SHA-256 hash (hex) of an opaque value.
+   *
+   * Used for one-way hashing of high-entropy secrets (OAuth access/refresh tokens,
+   * authorization codes, client secrets, registration access tokens) so that only
+   * the hash is stored at rest and lookups happen by hash. Plain SHA-256 is
+   * appropriate here because the inputs are 256-bit random opaque values with no
+   * brute-force surface; this is NOT for hashing low-entropy user passwords.
+   */
+  sha256Hash(value) {
+    return (0, import_crypto.createHash)("sha256").update(value).digest("hex");
+  }
+  /**
+   * Constant-time equality of two strings compared as UTF-8 bytes. Returns false
+   * on any length mismatch (and for empty input). Use for comparing fixed-length,
+   * high-entropy values that are already in their final comparable form — e.g. a
+   * recomputed PKCE S256 challenge against the stored one — without leaking
+   * content via timing. For comparing a raw secret against a stored hash, use
+   * {@link verifySha256Hash} instead.
+   */
+  constantTimeEquals(a3, b2) {
+    const ab = Buffer.from(a3, "utf8");
+    const bb = Buffer.from(b2, "utf8");
+    if (ab.length !== bb.length || ab.length === 0) {
+      return false;
+    }
+    return (0, import_crypto.timingSafeEqual)(ab, bb);
+  }
+  /**
+   * Constant-time comparison of a raw value against a stored SHA-256 hex hash.
+   * Avoids timing side channels when verifying secrets.
+   */
+  verifySha256Hash(rawValue, storedHash) {
+    const computed = Buffer.from(this.sha256Hash(rawValue), "hex");
+    let expected;
+    try {
+      expected = Buffer.from(storedHash, "hex");
+    } catch {
+      return false;
+    }
+    if (computed.length !== expected.length || expected.length === 0) {
+      return false;
+    }
+    return (0, import_crypto.timingSafeEqual)(computed, expected);
+  }
 };
 EncryptionService = __decorate3([
   W(),
@@ -139057,7 +140261,8 @@ function detectRelatedMentions(content, related) {
     }
     searchTerms.push(r2.name);
     for (const term of searchTerms) {
-      if (seen.has(qualifiedName)) break;
+      if (seen.has(qualifiedName))
+        break;
       try {
         const pattern = buildSearchPattern(term);
         if (pattern.test(content)) {
@@ -139069,17 +140274,12 @@ function detectRelatedMentions(content, related) {
           });
         }
       } catch (error48) {
-        console.warn(
-          `[detectRelatedMentions] Failed to match term "${term}" for resource "${r2.name}":`,
-          error48
-        );
+        console.warn(`[detectRelatedMentions] Failed to match term "${term}" for resource "${r2.name}":`, error48);
         continue;
       }
     }
   }
-  return Array.from(seen.values()).sort(
-    (a3, b2) => a3.qualifiedName.localeCompare(b2.qualifiedName)
-  );
+  return Array.from(seen.values()).sort((a3, b2) => a3.qualifiedName.localeCompare(b2.qualifiedName));
 }
 
 // src/utils.ts
@@ -144219,6 +145419,25 @@ var path2 = __toESM(require("path"));
 var import_node_crypto3 = require("node:crypto");
 var import_promises = require("node:stream/promises");
 var import_node_stream = require("node:stream");
+
+// src/config/urls.ts
+function publicMcpUrl() {
+  return parseUrlEnv("PUBLIC_MCP_URL", "http://localhost:3001/mcp");
+}
+function publicAuthorizationServerUrl() {
+  return parseUrlEnv("PUBLIC_BACKEND_URL", "http://localhost:3000");
+}
+function privateMcpUrl() {
+  return parseUrlEnv("PRIVATE_MCP_URL", "http://localhost:3001/mcp");
+}
+function privateBackendUrl() {
+  return parseUrlEnv("PRIVATE_BACKEND_URL", "http://localhost:3000");
+}
+function natsServers() {
+  return parseUrlEnv("NATS_SERVERS", "localhost:4222");
+}
+
+// src/services/file.service.ts
 var __decorate8 = function(decorators, target, key, desc) {
   var c3 = arguments.length, r2 = c3 < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d2;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r2 = Reflect.decorate(decorators, target, key, desc);
@@ -144294,8 +145513,9 @@ var FileService = class FileService2 extends LifecycleService {
       SKILDER_ALLOWED_PATHS: this.allowedPaths.join(":"),
       SKILDER_MAX_FILE_SIZE_MB: String(this.maxFileSizeMB)
     };
-    if (process.env.SKILDER_BACKEND_URL) {
-      env.SKILDER_BACKEND_URL = process.env.SKILDER_BACKEND_URL;
+    const backendUrl = process.env.SKILDER_BACKEND_URL || (process.env.PRIVATE_BACKEND_URL ? privateBackendUrl() : void 0);
+    if (backendUrl) {
+      env.SKILDER_BACKEND_URL = backendUrl;
     }
     return env;
   }
@@ -144595,9 +145815,9 @@ var DelegateService = class DelegateService2 {
       const modelString = modelOverride || defaultModel;
       const { slug, modelName } = this.aiProviderService.parseModelString(modelString);
       const model = this.aiProviderService.getProviderModel(provider, modelName, providerConfig, slug);
-      const runtimeUrl = process.env.RUNTIME_MCP_URL || "http://localhost:3001/mcp";
-      if (!process.env.RUNTIME_MCP_URL) {
-        this.logger.warn({ runtimeUrl, event: "delegate_mcp_url_fallback" }, "RUNTIME_MCP_URL not set, falling back to default");
+      const runtimeUrl = privateMcpUrl();
+      if (!process.env.PRIVATE_MCP_URL) {
+        this.logger.warn({ runtimeUrl, event: "delegate_mcp_url_fallback" }, "PRIVATE_MCP_URL not set, falling back to default");
       }
       if (!userKey) {
         return { isError: true, content: [{ type: "text", text: "Error: User key not available for delegate MCP connection." }] };
@@ -145187,7 +146407,7 @@ var _a35;
 var CONTENT_CACHE_LRU_SIZE = 256;
 var CONTENT_CACHE_TTL_MS = 3e5;
 function getBackendUrl2() {
-  return process.env.SKILDER_BACKEND_URL || "http://localhost:3000";
+  return privateBackendUrl();
 }
 var SkillContentService = class SkillContentService2 {
   constructor(loggerService) {
@@ -145847,7 +147067,7 @@ ${JSON.stringify(toolConfig.inputSchema, null, 2)}`
 // src/services/static-tools/download-asset.handler.ts
 var import_node_stream2 = require("node:stream");
 function getBackendUrl3() {
-  return (process.env.SKILDER_BACKEND_URL || "http://localhost:3000").replace(/\/$/, "");
+  return privateBackendUrl();
 }
 var DownloadAssetError = class extends Error {
   constructor(userMessage, skillId) {
@@ -146090,7 +147310,7 @@ var MIME_BY_EXTENSION = {
   ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
 };
 function getBackendUrl4() {
-  return (process.env.SKILDER_BACKEND_URL || "http://localhost:3000").replace(/\/$/, "");
+  return privateBackendUrl();
 }
 function mimeFromExtension(filePath) {
   const ext = path4.extname(filePath).toLowerCase();
@@ -147289,7 +148509,11 @@ var FastifyManagerService = class FastifyManagerService2 extends LifecycleServic
       // Allow credentials (cookies, authorization headers, etc.)
       methods: ["GET", "POST", "OPTIONS", "PUT", "DELETE"],
       // Explicitly allow methods including GET for SSE
-      exposedHeaders: ["Mcp-Session-Id"],
+      // WWW-Authenticate must be exposed so browser-based MCP clients (e.g. the
+      // MCP Inspector in direct mode) can read the RFC 9728 `resource_metadata`
+      // challenge on a 401 and discover the Authorization Server. Without it the
+      // browser hides the header and the client falls back to the wrong origin.
+      exposedHeaders: ["Mcp-Session-Id", "WWW-Authenticate"],
       allowedHeaders: [
         "Content-Type",
         "mcp-session-id",
@@ -148376,7 +149600,7 @@ function injectCorsHeaders(request, reply) {
     }
     finalHeaders["Access-Control-Allow-Origin"] = origin;
     finalHeaders["Access-Control-Allow-Credentials"] = "true";
-    finalHeaders["Access-Control-Expose-Headers"] = "Mcp-Session-Id";
+    finalHeaders["Access-Control-Expose-Headers"] = "Mcp-Session-Id, WWW-Authenticate";
     if (finalStatusMessage) {
       return originalWriteHead(statusCode, finalStatusMessage, finalHeaders);
     } else {
@@ -148507,12 +149731,21 @@ function getStringHeader(headers, name21) {
   const value = headers[name21];
   return typeof value === "string" && value ? value : void 0;
 }
+function getBearerToken(headers) {
+  const value = headers["authorization"];
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  const match = /^Bearer\s+(.+)$/i.exec(value.trim());
+  const token = match?.[1].trim();
+  return token ? token : void 0;
+}
 function extractAuthHeaders(request) {
   const headers = request.headers;
   const query = request.query;
   const skillIds = query?.skillIds?.split(",").filter(Boolean);
   const hatIds = query?.hatIds?.split(",").filter(Boolean);
-  const userKey = query?.key || getStringHeader(headers, "user_key") || getStringHeader(headers, "x-api-key");
+  const userKey = query?.key || getBearerToken(headers) || getStringHeader(headers, "user_key") || getStringHeader(headers, "x-api-key");
   const rawDepth = getStringHeader(headers, "x-delegate-depth");
   const parsedDepth = rawDepth != null ? parseInt(rawDepth, 10) : void 0;
   const delegateDepth = parsedDepth != null && Number.isFinite(parsedDepth) && parsedDepth >= 0 ? Math.min(parsedDepth, MAX_DELEGATE_DEPTH) : void 0;
@@ -148589,6 +149822,37 @@ function getSessionForRequest(sessionId, sessions) {
   return session;
 }
 
+// src/helpers/oauth-challenge.helper.ts
+function getPublicMcpUrl() {
+  return publicMcpUrl();
+}
+function getPublicAuthorizationServerUrl() {
+  return publicAuthorizationServerUrl();
+}
+function getProtectedResourceMetadataUrl() {
+  const u2 = new URL(getPublicMcpUrl());
+  const resourcePath = u2.pathname.replace(/\/+$/, "");
+  return `${u2.origin}/.well-known/oauth-protected-resource${resourcePath}`;
+}
+function getProtectedResourceMetadata() {
+  return {
+    resource: getPublicMcpUrl(),
+    authorization_servers: [getPublicAuthorizationServerUrl()],
+    scopes_supported: ["mcp"],
+    bearer_methods_supported: ["header"]
+  };
+}
+function getOAuthChallengeHeaderValue() {
+  return `Bearer resource_metadata="${getProtectedResourceMetadataUrl()}"`;
+}
+function setOAuthChallengeHeader(reply) {
+  reply.header("WWW-Authenticate", getOAuthChallengeHeaderValue());
+}
+function sendOAuthDiscoveryChallenge(reply, message = "Authentication required") {
+  setOAuthChallengeHeader(reply);
+  sendJsonRpcError(reply, JsonRpcErrorCode.SERVER_ERROR, message, 401);
+}
+
 // src/helpers/mcp-handlers.helper.ts
 var McpRequestHandlers = class {
   /**
@@ -148873,6 +150137,11 @@ var McpSseService = class McpSseService2 extends LifecycleService {
         if (!this.validateSecurityHeaders(request, reply)) {
           return;
         }
+        if (!extractAuthHeaders(request).userKey) {
+          this.logger.debug("Unauthenticated /sse request \u2014 returning OAuth discovery challenge");
+          sendOAuthDiscoveryChallenge(reply);
+          return;
+        }
         const identity = await authenticateSession(request, this.loggerService, this.natsService, this.runtimeExecutionId);
         this.logger.info(`Authenticated SSE connection for skill: ${identity.name}`);
         const skillService = await createSkillService(identity, this.loggerService, this.natsService, this.cacheService, this.healthService, this.scriptService, this.delegateService, this.fileService, this.skillContentService, this.staticToolRegistry, this.runtimeCatalogService, this.authService?.getIdentity()?.id ?? void 0);
@@ -148893,6 +150162,7 @@ var McpSseService = class McpSseService2 extends LifecycleService {
       } catch (error48) {
         this.logger.error({ err: error48 }, "Error handling SSE connection");
         if (error48 instanceof Error && error48.message.includes("Authentication failed")) {
+          setOAuthChallengeHeader(reply);
           sendJsonRpcError(reply, JsonRpcErrorCode.SERVER_ERROR, error48.message, 401);
         } else if (error48 instanceof Error && error48.message.includes("Invalid")) {
           sendJsonRpcError(reply, JsonRpcErrorCode.INVALID_REQUEST, error48.message, 400);
@@ -150291,8 +151561,23 @@ var McpStreamableService = class McpStreamableService2 extends LifecycleService
   async setupTransport() {
     this.logger.info(`Setting up ${this.name} transport`);
     this.registerMcpRoute();
+    this.registerProtectedResourceMetadataRoute();
     this.logger.info(`${this.name} transport configured`);
   }
+  /**
+   * Register the RFC 9728 Protected Resource Metadata endpoint on this MCP
+   * server's own origin. Public + unauthenticated by design. We serve both the
+   * root well-known path and the path-aware variants (`/.well-known/oauth-protected-resource/*`)
+   * so clients that derive the metadata URL from the resource path also resolve.
+   */
+  registerProtectedResourceMetadataRoute() {
+    const fastify2 = this.fastifyManager.getInstance();
+    const handler = async (_request, reply) => {
+      return reply.header("cache-control", "no-store").send(getProtectedResourceMetadata());
+    };
+    fastify2.get("/.well-known/oauth-protected-resource", handler);
+    fastify2.get("/.well-known/oauth-protected-resource/*", handler);
+  }
   /**
    * Register the /mcp route handler for streamable HTTP transport.
    * Handles GET (listen streams), POST (JSON-RPC messages), and DELETE (session termination).
@@ -150468,6 +151753,14 @@ var McpStreamableService = class McpStreamableService2 extends LifecycleService
    * Creates a new session for an authenticated request
    */
   async createNewSession(request, reply) {
+    if (!extractAuthHeaders(request).userKey) {
+      this.logger.debug("Unauthenticated /mcp request \u2014 returning OAuth discovery challenge");
+      setOAuthChallengeHeader(reply);
+      return reply.status(401).send({
+        error: "Unauthorized",
+        message: "Authentication required"
+      });
+    }
     try {
       const identity = await authenticateSession(request, this.loggerService, this.natsService, this.runtimeExecutionId);
       this.logger.info(`Authenticated new stream connection for skill: ${identity.name}`);
@@ -150481,6 +151774,7 @@ var McpStreamableService = class McpStreamableService2 extends LifecycleService
       const isAuthError = error48 instanceof Error && (msg.includes("unauthorized") || msg.includes("authentication") || msg.includes("forbidden"));
       if (isAuthError) {
         this.logger.error({ err: error48 }, "Authentication failed");
+        setOAuthChallengeHeader(reply);
         return reply.status(401).send({
           error: "Unauthorized",
           message: `Authentication failed: ${error48 instanceof Error ? error48.message : String(error48)}`
@@ -156565,10 +157859,9 @@ var start = () => {
   }
   const randomSuffix = (0, import_crypto3.randomBytes)(2).toString("hex");
   const runtimeId = "runtime:" + randomSuffix;
-  const natsServers = process.env.NATS_SERVERS || "localhost:4222";
   const natsName = process.env.NATS_NAME || runtimeId;
   container.bind(NATS_CONNECTION_OPTIONS).toConstantValue({
-    servers: natsServers,
+    servers: natsServers(),
     name: natsName,
     reconnect: true,
     maxReconnectAttempts: -1,