fenix-mcp 1.13.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

fenix_mcp/application/tools/knowledge.py

@@ -81,7 +81,7 @@ class KnowledgeAction(str, Enum):
     )
     WORK_MINE = (
         "work_mine",
-        "Lists work items assigned to the current user. Automatically excludes items with status 'done' or 'cancelled'. Supports pagination via limit and offset parameters.",
+        "START HERE for 'my tasks' or 'what am I working on'. Lists work items assigned to current user. Excludes done/cancelled. Supports limit and offset.",
     )
     WORK_BULK_CREATE = (
         "work_bulk_create",
@@ -105,25 +105,39 @@ class KnowledgeAction(str, Enum):
         "Lists work items linked to a sprint.",
     )
 
-    # Modes
-    MODE_CREATE = ("mode_create", "Creates a mode with content and optional metadata.")
-    MODE_LIST = ("mode_list", "Lists registered modes.")
-    MODE_GET = ("mode_get", "Gets full details of a mode.")
-    MODE_UPDATE = ("mode_update", "Updates properties of an existing mode.")
-    MODE_DELETE = ("mode_delete", "Removes a mode.")
-    MODE_RULE_ADD = ("mode_rule_add", "Associates a rule with a mode.")
-    MODE_RULE_REMOVE = (
-        "mode_rule_remove",
-        "Removes the association of a rule with a mode.",
-    )
-    MODE_RULES = ("mode_rules", "Lists rules associated with a mode.")
-
     # Rules
-    RULE_CREATE = ("rule_create", "Creates a rule with content and metadata.")
-    RULE_LIST = ("rule_list", "Lists registered rules.")
-    RULE_GET = ("rule_get", "Gets rule details.")
-    RULE_UPDATE = ("rule_update", "Updates an existing rule.")
-    RULE_DELETE = ("rule_delete", "Removes a rule.")
+    RULE_CREATE = (
+        "rule_create",
+        "Creates a new rule. REQUIRED: rule_scope (personal|team|organization|marketplace), rule_name, rule_content. Optional: rule_description, rule_slug. If scope=team, rule_team_id is also required.",
+    )
+    RULE_LIST = (
+        "rule_list",
+        "Lists rules accessible to the current user. Optional filters: rule_scope, query, limit, offset.",
+    )
+    RULE_GET = (
+        "rule_get",
+        "Gets full details of a rule. REQUIRED: rule_id (or id).",
+    )
+    RULE_UPDATE = (
+        "rule_update",
+        "Updates an existing rule. REQUIRED: rule_id (or id). Optional: rule_name, rule_description, rule_content, rule_is_active.",
+    )
+    RULE_DELETE = (
+        "rule_delete",
+        "Deletes a rule. REQUIRED: rule_id (or id).",
+    )
+    RULE_MARKETPLACE = (
+        "rule_marketplace",
+        "Lists public marketplace rules. Optional filters: query, limit, offset.",
+    )
+    RULE_FORK = (
+        "rule_fork",
+        "Forks a rule to a new scope. REQUIRED: rule_id (or id), rule_scope (personal|team|organization). Optional: rule_name, rule_team_id (required if scope=team).",
+    )
+    RULE_EXPORT = (
+        "rule_export",
+        "Exports a rule to a specific format. REQUIRED: rule_id (or id), rule_export_format (cursor|claude|copilot|windsurf).",
+    )
 
     # Documentation - Navigation workflow: doc_full_tree -> doc_children -> doc_get
     DOC_CREATE = (
@@ -136,7 +150,7 @@ class KnowledgeAction(str, Enum):
     )
     DOC_GET = (
         "doc_get",
-        "Reads document content by ID. Get the ID from doc_full_tree or doc_children first.",
+        "Reads document content by ID. PREREQUISITE: Get the ID from doc_full_tree first. Do NOT guess IDs.",
     )
     DOC_UPDATE = ("doc_update", "Updates a documentation item.")
     DOC_DELETE = ("doc_delete", "Removes a documentation item.")
@@ -153,13 +167,27 @@ class KnowledgeAction(str, Enum):
     DOC_TREE = ("doc_tree", "Retrieves tree starting from a specific document.")
     DOC_FULL_TREE = (
         "doc_full_tree",
-        "Retrieves complete documentation tree. Start here to find documents.",
+        "START HERE when looking for documentation. Returns complete folder structure with IDs. You NEED the ID from this to use doc_get. Workflow: 1) doc_full_tree to see all docs with IDs, 2) doc_get(id) to read content.",
     )
     DOC_MOVE = ("doc_move", "Moves a document to another parent.")
     DOC_PUBLISH = ("doc_publish", "Changes publication status of a document.")
     DOC_VERSION = ("doc_version", "Generates or retrieves a document version.")
     DOC_DUPLICATE = ("doc_duplicate", "Duplicates an existing document.")
 
+    # API Catalog
+    API_CATALOG_SEARCH = (
+        "api_catalog_search",
+        "Semantic search to find APIs by natural language query (e.g., 'API de usuários').",
+    )
+    API_CATALOG_LIST = (
+        "api_catalog_list",
+        "Lists API specifications with optional filters (status, tags).",
+    )
+    API_CATALOG_GET = (
+        "api_catalog_get",
+        "Gets full details of an API including all endpoints and environments.",
+    )
+
     HELP = ("knowledge_help", "Shows available actions and their uses.")
 
     @classmethod
@@ -177,10 +205,73 @@ class KnowledgeAction(str, Enum):
         return "\n".join(lines)
 
 
-ACTION_FIELD_DESCRIPTION = "Knowledge action. Choose one of the values: " + ", ".join(
-    f"`{member.value}` ({member.description.rstrip('.')})."
-    for member in KnowledgeAction
-)
+ACTION_FIELD_DESCRIPTION = """Knowledge action grouped by category:
+
+**WORK ITEMS** (tasks, bugs, features):
+- `work_mine`: YOUR assigned tasks (START HERE for "my tasks")
+- `work_list`: List with filters (status, priority, type)
+- `work_get`: Get details by ID or key (use work_key for "FENIX-123")
+- `work_create`: Create new (requires: work_title, work_category)
+- `work_update`: Update fields (title, description, priority, story_points, tags, due_date)
+- `work_search`: Search by text
+- `work_bulk_create`: Create multiple with hierarchy
+- `work_backlog`: Team backlog items
+- `work_children`: Child items of a parent
+- `work_by_sprint`: Items in a sprint
+- `work_by_board`: Items in a board
+- `work_by_epic`: Items in an epic
+- `work_status_update`: Update only status
+- `work_assign_sprint`: Assign items to sprint
+- `work_assign_to_me`: Assign item to yourself
+- `work_analytics`: Work item metrics
+
+**DOCUMENTATION**:
+- `doc_full_tree`: Complete tree (START HERE to find docs and get IDs)
+- `doc_get`: Read content (needs ID from doc_full_tree)
+- `doc_children`: Folder contents
+- `doc_create`: Create new doc (requires: doc_title, doc_emoji for non-folders)
+- `doc_update`: Update doc
+- `doc_delete`: Remove doc
+- `doc_roots`: Root folders
+- `doc_recent`: Recently accessed
+- `doc_tree`: Tree from specific doc
+- `doc_move`: Move to another parent
+- `doc_publish`: Change publication status
+- `doc_version`: Create/get version
+- `doc_duplicate`: Duplicate doc
+- `doc_analytics`: Doc metrics
+
+**SPRINTS**:
+- `sprint_active`: Current sprint (START HERE)
+- `sprint_list`: All sprints
+- `sprint_get`: Sprint details
+- `sprint_by_team`: Team sprints
+- `sprint_work_items`: Items in sprint
+
+**BOARDS**:
+- `board_list`: All boards
+- `board_get`: Board details
+- `board_by_team`: Team boards
+- `board_favorites`: Favorite boards
+- `board_columns`: Board columns
+
+**RULES** (coding standards):
+- `rule_list`: Team rules
+- `rule_get`: Rule content
+- `rule_create`: Create rule (requires: rule_scope, rule_name, rule_content)
+- `rule_update`: Update rule
+- `rule_delete`: Remove rule
+- `rule_export`: Export for IDE (cursor, claude, copilot, windsurf)
+- `rule_marketplace`: Public rules
+- `rule_fork`: Fork a rule
+
+**API CATALOG**:
+- `api_catalog_search`: Semantic search for APIs (natural language)
+- `api_catalog_list`: List all APIs
+- `api_catalog_get`: API details with endpoints
+
+`knowledge_help`: Show all actions with descriptions
+"""
 
 
 _ALLOWED_DOC_TYPES = {
@@ -283,40 +374,6 @@ class KnowledgeRequest(ToolRequest):
         ),
     )
 
-    # Mode fields
-    mode_id: Optional[UUIDStr] = Field(
-        default=None, description="Related mode ID (UUID)."
-    )
-    mode_name: Optional[TitleStr] = Field(default=None, description="Mode name.")
-    mode_description: Optional[DescriptionStr] = Field(
-        default=None, description="Mode description."
-    )
-    mode_content: Optional[MarkdownStr] = Field(
-        default=None, description="Mode content (Markdown)."
-    )
-    mode_is_default: Optional[bool] = Field(
-        default=None, description="Indicates if the mode is default."
-    )
-    mode_metadata: Optional[MarkdownStr] = Field(
-        default=None, description="Mode metadata for AI processing."
-    )
-
-    # Rule fields
-    rule_id: Optional[UUIDStr] = Field(
-        default=None, description="Related rule ID (UUID)."
-    )
-    rule_name: Optional[TitleStr] = Field(default=None, description="Rule name.")
-    rule_description: Optional[DescriptionStr] = Field(
-        default=None, description="Rule description."
-    )
-    rule_content: Optional[MarkdownStr] = Field(
-        default=None, description="Rule content (Markdown)."
-    )
-    rule_is_default: Optional[bool] = Field(default=None, description="Default rule.")
-    rule_metadata: Optional[MarkdownStr] = Field(
-        default=None, description="Rule metadata for AI processing."
-    )
-
     # Documentation fields
     doc_title: Optional[TitleStr] = Field(
         default=None, description="Documentation title."
@@ -369,10 +426,71 @@ class KnowledgeRequest(ToolRequest):
         default=None, description="Whether the document is public."
     )
 
+    # Rule fields
+    rule_id: Optional[UUIDStr] = Field(default=None, description="Rule ID (UUID).")
+    rule_scope: Optional[str] = Field(
+        default=None,
+        description="Rule scope. Values: personal, team, organization, marketplace.",
+    )
+    rule_name: Optional[TitleStr] = Field(default=None, description="Rule name.")
+    rule_slug: Optional[str] = Field(
+        default=None, description="Rule slug (auto-generated if not provided)."
+    )
+    rule_description: Optional[DescriptionStr] = Field(
+        default=None, description="Rule description."
+    )
+    rule_content: Optional[MarkdownStr] = Field(
+        default=None, description=f"Rule content (Markdown).{MERMAID_HINT}"
+    )
+    rule_team_id: Optional[UUIDStr] = Field(
+        default=None, description="Team ID for team-scoped rules (UUID)."
+    )
+    rule_export_format: Optional[str] = Field(
+        default=None,
+        description="Export format. Values: cursor, claude, copilot, windsurf.",
+    )
+    rule_is_active: Optional[bool] = Field(
+        default=None, description="Whether the rule is active."
+    )
+
+    # API Catalog fields
+    api_spec_id: Optional[UUIDStr] = Field(
+        default=None,
+        description="API specification ID (UUID). Can also use 'id' field instead.",
+    )
+
 
 class KnowledgeTool(Tool):
     name = "knowledge"
-    description = "Fenix Cloud knowledge operations (Work Items, Boards, Sprints, Modes, Rules, Docs)."
+    description = """Fenix knowledge base - use this tool when user asks about:
+
+WORK ITEMS (tasks, bugs, features):
+- "what are my tasks?" -> action: work_mine
+- "show task FENIX-123" -> action: work_get, work_key: "FENIX-123"
+- "what's in the backlog?" -> action: work_backlog
+- "create a task" -> action: work_create (requires: work_title, work_category)
+
+DOCUMENTATION:
+- "find docs about X" -> action: doc_full_tree (START HERE to get IDs)
+- "read the architecture doc" -> action: doc_get (needs ID from doc_full_tree)
+
+SPRINTS:
+- "current sprint?" -> action: sprint_active
+- "sprint items?" -> action: sprint_work_items
+
+RULES (coding standards):
+- "team coding standards?" -> action: rule_list
+- "export rules for cursor" -> action: rule_export
+
+API CATALOG:
+- "find user API" -> action: api_catalog_search
+- "list all APIs" -> action: api_catalog_list
+
+IMPORTANT WORKFLOWS:
+1. For MY tasks: Always use work_mine first
+2. For docs: Always use doc_full_tree first to get IDs, then doc_get
+3. For work item by key: Use work_key parameter (e.g., "FENIX-123")
+"""
     request_model = KnowledgeRequest
 
     def __init__(self, context: AppContext):
@@ -389,12 +507,12 @@ class KnowledgeTool(Tool):
             return await self._run_board(payload)
         if action.value.startswith("sprint_"):
             return await self._run_sprint(payload)
-        if action.value.startswith("mode_"):
-            return await self._run_mode(payload)
         if action.value.startswith("rule_"):
             return await self._run_rule(payload)
         if action.value.startswith("doc_"):
             return await self._run_doc(payload)
+        if action.value.startswith("api_catalog_"):
+            return await self._run_api_catalog(payload)
         return text(
             "❌ Invalid action for knowledge.\n\nChoose one of the values:\n"
             + "\n".join(f"- `{value}`" for value in KnowledgeAction.choices())
@@ -820,195 +938,123 @@ class KnowledgeTool(Tool):
             )
         )
 
-    # ------------------------------------------------------------------
-    # Modes
-    # ------------------------------------------------------------------
-    async def _run_mode(self, payload: KnowledgeRequest):
-        action = payload.action
-        if action is KnowledgeAction.MODE_CREATE:
-            if not payload.mode_name:
-                return text("❌ Provide mode_name to create the mode.")
-            mode = await self._service.mode_create(
-                {
-                    "name": payload.mode_name,
-                    "description": payload.mode_description,
-                    "content": payload.mode_content,
-                    "is_default": payload.mode_is_default,
-                    "metadata": payload.mode_metadata,
-                }
-            )
-            return text(_format_mode(mode, header="✅ Mode created"))
-
-        if action is KnowledgeAction.MODE_LIST:
-            modes = await self._service.mode_list(
-                include_rules=payload.return_metadata,
-                return_description=payload.return_description,
-                return_metadata=payload.return_metadata,
-            )
-            if not modes:
-                return text("🎭 No modes found.")
-            body = "\n\n".join(_format_mode(mode) for mode in modes)
-            return text(f"🎭 **Modes ({len(modes)}):**\n\n{body}")
-
-        if action is KnowledgeAction.MODE_GET:
-            if not payload.mode_id:
-                return text("❌ Provide mode_id to get details.")
-            mode = await self._service.mode_get(
-                payload.mode_id,
-                return_description=payload.return_description,
-                return_metadata=payload.return_metadata,
-            )
-            # Buscar rules associadas ao mode
-            associations = await self._service.mode_rules(payload.mode_id)
-            rules = [assoc.get("rule", assoc) for assoc in associations]
-
-            # Formatar resposta com rules (incluindo content)
-            output = _format_mode(mode, header="🎭 Mode details", show_content=True)
-            if rules:
-                rules_parts = []
-                for r in rules:
-                    rule_text = f"### 📋 {r.get('name', 'Unnamed')}\n"
-                    rule_text += f"ID: {r.get('id')}\n"
-                    if r.get("content"):
-                        rule_text += f"\n{r.get('content')}"
-                    rules_parts.append(rule_text)
-                output += f"\n\n**Rules ({len(rules)}):**\n\n" + "\n\n---\n\n".join(
-                    rules_parts
-                )
-            return text(output)
-
-        if action is KnowledgeAction.MODE_UPDATE:
-            if not payload.mode_id:
-                return text("❌ Provide mode_id to update.")
-            mode = await self._service.mode_update(
-                payload.mode_id,
-                {
-                    "name": payload.mode_name,
-                    "description": payload.mode_description,
-                    "content": payload.mode_content,
-                    "is_default": payload.mode_is_default,
-                    "metadata": payload.mode_metadata,
-                },
-            )
-            return text(_format_mode(mode, header="✅ Mode updated"))
-
-        if action is KnowledgeAction.MODE_DELETE:
-            if not payload.mode_id:
-                return text("❌ Provide mode_id to remove.")
-            await self._service.mode_delete(payload.mode_id)
-            return text(f"🗑️ Mode {payload.mode_id} removed.")
-
-        if action is KnowledgeAction.MODE_RULE_ADD:
-            if not payload.mode_id or not payload.rule_id:
-                return text("❌ Provide mode_id and rule_id to associate.")
-            link = await self._service.mode_rule_add(payload.mode_id, payload.rule_id)
-            return text(
-                "\n".join(
-                    [
-                        "🔗 **Rule associated with mode!**",
-                        f"Mode: {link.get('modeId', payload.mode_id)}",
-                        f"Rule: {link.get('ruleId', payload.rule_id)}",
-                    ]
-                )
-            )
-
-        if action is KnowledgeAction.MODE_RULE_REMOVE:
-            if not payload.mode_id or not payload.rule_id:
-                return text("❌ Provide mode_id and rule_id to remove the association.")
-            await self._service.mode_rule_remove(payload.mode_id, payload.rule_id)
-            return text("🔗 Association removed.")
-
-        if action is KnowledgeAction.MODE_RULES:
-            if payload.mode_id:
-                associations = await self._service.mode_rules(payload.mode_id)
-                context_label = f"mode {payload.mode_id}"
-                # API retorna [{id, mode_id, rule_id, rule: {...}}] - extrair rule
-                items = [assoc.get("rule", assoc) for assoc in associations]
-            elif payload.rule_id:
-                associations = await self._service.mode_rules_for_rule(payload.rule_id)
-                context_label = f"rule {payload.rule_id}"
-                # API retorna [{id, mode_id, rule_id, mode: {...}}] - extrair mode
-                items = [assoc.get("mode", assoc) for assoc in associations]
-            else:
-                return text("❌ Provide mode_id or rule_id to list associations.")
-            if not items:
-                return text("🔗 No associations found.")
-            body = "\n".join(
-                f"- {item.get('name', 'Unnamed')} (ID: {item.get('id')})"
-                for item in items
-            )
-            return text(f"🔗 **Associations for {context_label}:**\n{body}")
-
-        return text(
-            "❌ Unsupported mode action.\n\nChoose one of the values:\n"
-            + "\n".join(
-                f"- `{value}`"
-                for value in KnowledgeAction.choices()
-                if value.startswith("mode_")
-            )
-        )
-
     # ------------------------------------------------------------------
     # Rules
     # ------------------------------------------------------------------
     async def _run_rule(self, payload: KnowledgeRequest):
         action = payload.action
+
         if action is KnowledgeAction.RULE_CREATE:
-            if not payload.rule_name or not payload.rule_content:
-                return text("❌ Provide rule_name and rule_content.")
+            if not payload.rule_name:
+                return text("❌ Provide rule_name to create the rule.")
+            if not payload.rule_content:
+                return text("❌ Provide rule_content to create the rule.")
+            if not payload.rule_scope:
+                return text(
+                    "❌ Provide rule_scope to create the rule. "
+                    "Values: personal, team, organization, marketplace."
+                )
+            if payload.rule_scope == "team" and not payload.rule_team_id:
+                return text("❌ Provide rule_team_id for team-scoped rules.")
+
             rule = await self._service.rule_create(
                 {
+                    "scope": payload.rule_scope,
                     "name": payload.rule_name,
-                    "description": payload.rule_description,
+                    "slug": sanitize_null(payload.rule_slug),
+                    "description": sanitize_null(payload.rule_description),
                     "content": payload.rule_content,
-                    "is_default": payload.rule_is_default,
-                    "metadata": payload.rule_metadata,
+                    "team_id": sanitize_null(payload.rule_team_id),
                 }
             )
             return text(_format_rule(rule, header="✅ Rule created"))
 
         if action is KnowledgeAction.RULE_LIST:
             rules = await self._service.rule_list(
-                return_description=payload.return_description,
-                return_metadata=payload.return_metadata,
-                return_modes=payload.return_metadata,
+                limit=payload.limit,
+                offset=payload.offset,
+                scope=sanitize_null(payload.rule_scope),
+                query=sanitize_null(payload.query),
             )
             if not rules:
-                return text("📋 No rules found.")
+                return text("📜 No rules found.")
             body = "\n\n".join(_format_rule(rule) for rule in rules)
-            return text(f"📋 **Rules ({len(rules)}):**\n\n{body}")
+            return text(f"📜 **Rules ({len(rules)}):**\n\n{body}")
 
         if action is KnowledgeAction.RULE_GET:
-            if not payload.rule_id:
-                return text("❌ Provide rule_id to get details.")
-            rule = await self._service.rule_get(
-                payload.rule_id,
-                return_description=payload.return_description,
-                return_metadata=payload.return_metadata,
-                return_modes=payload.return_metadata,
-            )
-            return text(_format_rule(rule, header="📋 Rule details", show_content=True))
+            rule_id = payload.rule_id or payload.id
+            if not rule_id:
+                return text("❌ Provide rule_id or id to get the rule.")
+            rule = await self._service.rule_get(rule_id)
+            return text(_format_rule(rule, header="📜 Rule details", show_content=True))
 
         if action is KnowledgeAction.RULE_UPDATE:
-            if not payload.rule_id:
-                return text("❌ Provide rule_id to update.")
+            rule_id = payload.rule_id or payload.id
+            if not rule_id:
+                return text("❌ Provide rule_id or id to update the rule.")
             rule = await self._service.rule_update(
-                payload.rule_id,
+                rule_id,
                 {
-                    "name": payload.rule_name,
-                    "description": payload.rule_description,
-                    "content": payload.rule_content,
-                    "is_default": payload.rule_is_default,
-                    "metadata": payload.rule_metadata,
+                    "name": sanitize_null(payload.rule_name),
+                    "description": sanitize_null(payload.rule_description),
+                    "content": sanitize_null(payload.rule_content),
+                    "is_active": payload.rule_is_active,
                 },
             )
             return text(_format_rule(rule, header="✅ Rule updated"))
 
         if action is KnowledgeAction.RULE_DELETE:
-            if not payload.rule_id:
-                return text("❌ Provide rule_id to remove.")
-            await self._service.rule_delete(payload.rule_id)
-            return text(f"🗑️ Rule {payload.rule_id} removed.")
+            rule_id = payload.rule_id or payload.id
+            if not rule_id:
+                return text("❌ Provide rule_id or id to delete the rule.")
+            await self._service.rule_delete(rule_id)
+            return text(f"🗑️ Rule {rule_id} removed.")
+
+        if action is KnowledgeAction.RULE_MARKETPLACE:
+            rules = await self._service.rule_marketplace(
+                limit=payload.limit,
+                offset=payload.offset,
+                query=sanitize_null(payload.query),
+            )
+            if not rules:
+                return text("🏪 No marketplace rules found.")
+            body = "\n\n".join(_format_marketplace_rule(rule) for rule in rules)
+            return text(f"🏪 **Marketplace Rules ({len(rules)}):**\n\n{body}")
+
+        if action is KnowledgeAction.RULE_FORK:
+            rule_id = payload.rule_id or payload.id
+            if not rule_id:
+                return text("❌ Provide rule_id or id to fork the rule.")
+            if not payload.rule_scope:
+                return text(
+                    "❌ Provide rule_scope for the forked rule. "
+                    "Values: personal, team, organization."
+                )
+            rule = await self._service.rule_fork(
+                rule_id,
+                {
+                    "scope": payload.rule_scope,
+                    "name": sanitize_null(payload.rule_name),
+                    "team_id": sanitize_null(payload.rule_team_id),
+                },
+            )
+            return text(_format_rule(rule, header="✅ Rule forked"))
+
+        if action is KnowledgeAction.RULE_EXPORT:
+            rule_id = payload.rule_id or payload.id
+            if not rule_id:
+                return text("❌ Provide rule_id or id to export the rule.")
+            if not payload.rule_export_format:
+                return text(
+                    "❌ Provide rule_export_format. "
+                    "Values: cursor, claude, copilot, windsurf."
+                )
+            content = await self._service.rule_export(
+                rule_id, payload.rule_export_format
+            )
+            return text(
+                f"📤 **Export ({payload.rule_export_format}):**\n\n```\n{content}\n```"
+            )
 
         return text(
             "❌ Unsupported rule action.\n\nChoose one of the values:\n"
@@ -1219,6 +1265,63 @@ class KnowledgeTool(Tool):
             )
         )
 
+    # ------------------------------------------------------------------
+    # API Catalog
+    # ------------------------------------------------------------------
+    async def _run_api_catalog(self, payload: KnowledgeRequest):
+        action = payload.action
+
+        if action is KnowledgeAction.API_CATALOG_SEARCH:
+            query = sanitize_null(payload.query)
+            if not query:
+                return text("❌ Provide query to search APIs.")
+
+            result = await self._service.api_catalog_search(
+                query=query,
+                limit=payload.limit,
+            )
+
+            data = result.get("data", [])
+            if not data:
+                return text(
+                    f"🔍 No APIs found for: **{query}**\n\n"
+                    "Try a different search term or use `api_catalog_list` to see all APIs."
+                )
+
+            body = "\n\n".join(_format_api_search_result(api) for api in data)
+            total = len(data)
+
+            return text(f"🔍 **APIs found for '{query}'** ({total} results)\n\n{body}")
+
+        if action is KnowledgeAction.API_CATALOG_LIST:
+            apis = await self._service.api_catalog_list(
+                limit=payload.limit,
+                offset=payload.offset,
+            )
+
+            if not apis:
+                return text("📚 No APIs found in the catalog.")
+
+            body = "\n\n".join(_format_api_item(api) for api in apis)
+            return text(f"📚 **API Catalog ({len(apis)} APIs)**\n\n{body}")
+
+        if action is KnowledgeAction.API_CATALOG_GET:
+            spec_id = payload.api_spec_id or payload.id
+            if not spec_id:
+                return text("❌ Provide api_spec_id or id to get the API details.")
+
+            api = await self._service.api_catalog_get(spec_id)
+            return text(_format_api_detail(api))
+
+        return text(
+            "❌ Unsupported API Catalog action.\n\nChoose one of the values:\n"
+            + "\n".join(
+                f"- `{value}`"
+                for value in KnowledgeAction.choices()
+                if value.startswith("api_catalog_")
+            )
+        )
+
     async def _handle_help(self):
         workflow_guide = """
 ## 📖 How to find and read a document
@@ -1361,8 +1464,8 @@ def _format_sprint(sprint: Dict[str, Any], header: Optional[str] = None) -> str:
     return "\n".join(lines)
 
 
-def _format_mode(
-    mode: Dict[str, Any],
+def _format_doc(
+    doc: Dict[str, Any],
     *,
     header: Optional[str] = None,
     show_content: bool = False,
@@ -1373,17 +1476,23 @@ def _format_mode(
         lines.append("")
     lines.extend(
         [
-            f"🎭 **{mode.get('name', 'Unnamed')}**",
-            f"ID: {mode.get('id', 'N/A')}",
-            f"Default: {mode.get('is_default', False)}",
+            f"📄 **{doc.get('title') or doc.get('name', 'Untitled')}**",
+            f"ID: {doc.get('id', 'N/A')}",
+            f"Status: {doc.get('status', 'N/A')}",
+            f"Team: {doc.get('team_id', 'N/A')}",
         ]
     )
-    if mode.get("description"):
-        lines.append(f"Description: {mode['description']}")
-    if show_content and mode.get("content"):
+    if doc.get("updated_at") or doc.get("updatedAt"):
+        lines.append(
+            f"Updated at: {_format_date(doc.get('updated_at') or doc.get('updatedAt'))}"
+        )
+
+    # Show content only when explicitly requested (e.g., doc_get)
+    if show_content and doc.get("content"):
         lines.append("")
         lines.append("**Content:**")
-        lines.append(mode.get("content"))
+        lines.append(doc.get("content"))
+
     return "\n".join(lines)
 
 
@@ -1397,50 +1506,251 @@ def _format_rule(
     if header:
         lines.append(header)
         lines.append("")
+
+    name = rule.get("name", "Untitled")
+    scope = rule.get("scope", "unknown")
+    scope_emoji = {
+        "personal": "👤",
+        "team": "👥",
+        "organization": "🏢",
+        "marketplace": "🌍",
+    }.get(scope, "📜")
+
     lines.extend(
         [
-            f"📋 **{rule.get('name', 'Unnamed')}**",
+            f"{scope_emoji} **{name}**",
             f"ID: {rule.get('id', 'N/A')}",
-            f"Default: {rule.get('is_default', False)}",
+            f"Scope: {scope}",
+            f"Version: {rule.get('version', '1.0')}",
         ]
     )
+
     if rule.get("description"):
-        lines.append(f"Description: {rule['description']}")
+        lines.append(f"Description: {rule.get('description')}")
+
+    # Author info
+    author = rule.get("author")
+    if isinstance(author, dict):
+        lines.append(f"Author: {author.get('name', 'Unknown')}")
+
+    # Forked from info
+    forked_from = rule.get("forked_from")
+    if isinstance(forked_from, dict):
+        forked_author = forked_from.get("author", {})
+        author_name = (
+            forked_author.get("name", "Unknown")
+            if isinstance(forked_author, dict)
+            else "Unknown"
+        )
+        lines.append(
+            f"Forked from: {forked_from.get('name', 'Unknown')} by {author_name}"
+        )
+
+    if rule.get("is_active") is False:
+        lines.append("Status: Inactive")
+
+    if rule.get("updated_at") or rule.get("updatedAt"):
+        lines.append(
+            f"Updated: {_format_date(rule.get('updated_at') or rule.get('updatedAt'))}"
+        )
+
+    # Show content only when explicitly requested
     if show_content and rule.get("content"):
         lines.append("")
         lines.append("**Content:**")
         lines.append(rule.get("content"))
+
     return "\n".join(lines)
 
 
-def _format_doc(
-    doc: Dict[str, Any],
-    *,
-    header: Optional[str] = None,
-    show_content: bool = False,
-) -> str:
+def _format_marketplace_rule(rule: Dict[str, Any]) -> str:
+    """Format a marketplace rule with download/rating info."""
     lines: List[str] = []
-    if header:
-        lines.append(header)
+
+    name = rule.get("name", "Untitled")
+    downloads = rule.get("downloads", 0)
+    rating = rule.get("rating")
+
+    lines.append(f"🌍 **{name}**")
+    lines.append(f"ID: {rule.get('id', 'N/A')}")
+
+    if rule.get("description"):
+        lines.append(f"Description: {rule.get('description')}")
+
+    # Author info
+    author = rule.get("author")
+    if isinstance(author, dict):
+        lines.append(f"Author: {author.get('name', 'Unknown')}")
+
+    # Stats
+    stats_parts = [f"⬇️ {downloads}"]
+    if rating is not None:
+        stats_parts.append(f"⭐ {float(rating):.1f}")
+    lines.append(" | ".join(stats_parts))
+
+    return "\n".join(lines)
+
+
+def _format_api_search_result(api: Dict[str, Any]) -> str:
+    """Format an API search result with similarity and matched endpoint."""
+    lines: List[str] = []
+
+    title = api.get("title", "Untitled API")
+    slug = api.get("slug", "")
+    similarity = api.get("similarity")
+
+    # Title with similarity
+    if similarity is not None:
+        pct = float(similarity) * 100
+        lines.append(f"🔗 **{title}** ({pct:.0f}% match)")
+    else:
+        lines.append(f"🔗 **{title}**")
+
+    lines.append(f"Slug: {slug}")
+
+    # Status
+    status = api.get("lifecycle_status", "unknown")
+    lines.append(f"Status: {status}")
+
+    # Description (truncated)
+    desc = api.get("description")
+    if desc:
+        truncated = desc[:150] + "..." if len(desc) > 150 else desc
+        lines.append(f"Description: {truncated}")
+
+    # Team info
+    team = api.get("team")
+    if isinstance(team, dict):
+        lines.append(f"Team: {team.get('name', 'Unknown')}")
+
+    # Matched endpoint (for semantic search)
+    matched = api.get("matchedEndpoint")
+    if matched:
+        method = matched.get("method", "").upper()
+        path = matched.get("path", "")
+        summary = matched.get("summary", "")
+        lines.append(f"Best match: **{method} {path}**")
+        if summary:
+            lines.append(f"  └─ {summary}")
+
+    # Current version
+    version = api.get("current_version")
+    if isinstance(version, dict):
+        lines.append(f"Version: {version.get('version', 'N/A')}")
+
+    return "\n".join(lines)
+
+
+def _format_api_item(api: Dict[str, Any]) -> str:
+    """Format an API item for listing."""
+    lines: List[str] = []
+
+    title = api.get("title", "Untitled API")
+    slug = api.get("slug", "")
+    status = api.get("lifecycle_status", "unknown")
+
+    lines.append(f"📦 **{title}**")
+    lines.append(f"ID: {api.get('id', 'N/A')}")
+    lines.append(f"Slug: {slug}")
+    lines.append(f"Status: {status}")
+
+    # Tags
+    tags = api.get("tags", [])
+    if tags:
+        lines.append(f"Tags: {', '.join(tags)}")
+
+    # Team
+    team = api.get("team")
+    if isinstance(team, dict):
+        lines.append(f"Team: {team.get('name', 'Unknown')}")
+
+    # Version
+    version = api.get("current_version")
+    if isinstance(version, dict):
+        lines.append(f"Version: {version.get('version', 'N/A')}")
+
+    return "\n".join(lines)
+
+
+def _format_api_detail(api: Dict[str, Any]) -> str:
+    """Format detailed API specification view."""
+    lines: List[str] = []
+
+    title = api.get("title", "Untitled API")
+    slug = api.get("slug", "")
+
+    lines.append(f"📚 **{title}**")
+    lines.append("")
+    lines.append(f"ID: {api.get('id', 'N/A')}")
+    lines.append(f"Slug: {slug}")
+    lines.append(f"Status: {api.get('lifecycle_status', 'unknown')}")
+
+    # Description
+    desc = api.get("description")
+    if desc:
         lines.append("")
-    lines.extend(
-        [
-            f"📄 **{doc.get('title') or doc.get('name', 'Untitled')}**",
-            f"ID: {doc.get('id', 'N/A')}",
-            f"Status: {doc.get('status', 'N/A')}",
-            f"Team: {doc.get('team_id', 'N/A')}",
-        ]
-    )
-    if doc.get("updated_at") or doc.get("updatedAt"):
-        lines.append(
-            f"Updated at: {_format_date(doc.get('updated_at') or doc.get('updatedAt'))}"
-        )
+        lines.append("**Description:**")
+        lines.append(desc)
 
-    # Show content only when explicitly requested (e.g., doc_get)
-    if show_content and doc.get("content"):
+    # Tags
+    tags = api.get("tags", [])
+    if tags:
         lines.append("")
-        lines.append("**Content:**")
-        lines.append(doc.get("content"))
+        lines.append(f"Tags: {', '.join(tags)}")
+
+    # Team
+    team = api.get("team")
+    if isinstance(team, dict):
+        lines.append(f"Team: {team.get('name', 'Unknown')}")
+
+    # Current version
+    version = api.get("current_version")
+    if isinstance(version, dict):
+        lines.append("")
+        lines.append("**Current Version:**")
+        lines.append(f"- Version: {version.get('version', 'N/A')}")
+        lines.append(f"- OpenAPI: {version.get('openapi_version', 'N/A')}")
+
+        # Endpoints from current version
+        endpoints = version.get("endpoint_embeddings", [])
+        if endpoints:
+            lines.append(f"- Endpoints: {len(endpoints)}")
+            lines.append("")
+            lines.append("**Endpoints:**")
+            for ep in endpoints[:10]:  # Limit to 10
+                method = ep.get("method", "").upper()
+                path = ep.get("path", "")
+                summary = ep.get("summary", "")
+                if summary:
+                    lines.append(f"- **{method}** {path} - {summary}")
+                else:
+                    lines.append(f"- **{method}** {path}")
+            if len(endpoints) > 10:
+                lines.append(f"  ... and {len(endpoints) - 10} more endpoints")
+
+    # Environments
+    environments = api.get("environments", [])
+    if environments:
+        lines.append("")
+        lines.append("**Environments:**")
+        for env in environments:
+            name = env.get("name", "Unnamed")
+            url = env.get("base_url", "")
+            lines.append(f"- {name}: {url}")
+
+    # Permissions
+    permissions = api.get("permissions", {})
+    if permissions:
+        lines.append("")
+        lines.append("**Your Permissions:**")
+        if permissions.get("canEdit"):
+            lines.append("- ✅ Edit")
+        if permissions.get("canDelete"):
+            lines.append("- ✅ Delete")
+        if permissions.get("canPublish"):
+            lines.append("- ✅ Publish")
+        if permissions.get("canManageVersions"):
+            lines.append("- ✅ Manage Versions")
 
     return "\n".join(lines)