agent-devkit 0.2.0 → 0.3.0

package/runtime/cli/README.md

@@ -199,6 +199,37 @@ O comando retorna erro apenas para problemas estruturais do runtime, como raiz
 inexistente. Provider opcional ausente, LLM sem chave ou CLI de host nao
 instalada aparecem no bloco de diagnostico e podem ser resolvidos sob demanda.
 
+## Onboarding
+
+Executar apenas `agent` inicia o status/wizard local. Para planejar setup sem
+executar instalacoes externas:
+
+```bash
+agent onboard minimal
+agent onboard complete
+```
+
+`minimal` cobre identidade, coordenador LLM, mini-cerebro Qwen3-0.6B via
+Ollama e memoria local. `complete` inclui tambem toolchain, providers/sources,
+catalogo de agentes, automacoes locais, tarefas, notificacoes, knowledge e
+memoria compartilhada. Instalacoes externas continuam exigindo opt-in.
+
+Backups locais de memoria e personalidade sao gerenciados por:
+
+```bash
+agent memory backup create --title "Antes da migracao"
+export AGENT_DEVKIT_BACKUP_PASSPHRASE="frase longa"
+agent memory backup create --title "Antes da migracao" --encrypted --passphrase-env AGENT_DEVKIT_BACKUP_PASSPHRASE
+agent memory backup list
+agent memory backup restore <backup-id> --yes
+agent memory backup restore --file ./backup.adkmb --passphrase-env AGENT_DEVKIT_BACKUP_PASSPHRASE --yes
+agent memory backup delete <backup-id> --yes
+```
+
+O backup criptografado gera um pacote portatil `.adkmb` e remove a copia local
+em claro dentro da pasta do backup. Esse fluxo nao executa upload remoto. Sync
+remoto continua exigindo provider, criptografia e opt-in explicito.
+
 ## Backends LLM
 
 O modo `agent "<prompt>"` exige um backend LLM. O Agent DevKit suporta tres
@@ -292,10 +323,10 @@ agent llm doctor openrouter
 ```bash
 agent ollama status
 agent ollama models
-agent ollama pull qwen2.5-coder --dry-run
-agent ollama pull qwen2.5-coder --yes
+agent ollama pull qwen3:0.6b --dry-run
+agent ollama pull qwen3:0.6b --yes
 ollama serve
-agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.6b --set-default
 agent llm doctor ollama
 ```
 
@@ -319,7 +350,7 @@ agent llm list
 agent llm configure openai --api-key-env OPENAI_API_KEY --set-default
 agent llm configure anthropic --api-key-env ANTHROPIC_API_KEY --set-default
 agent llm configure openrouter --api-key-env OPENROUTER_API_KEY --set-default
-agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen2.5-coder --set-default
+agent llm configure ollama --base-url http://localhost:11434/v1 --model qwen3:0.6b --set-default
 agent llm configure codex-cli --set-default
 agent llm configure claude-code --set-default
 agent llm set-default codex-cli

package/runtime/cli/aikit/__init__.py

@@ -1,3 +1,3 @@
 """Public CLI implementation for AI DevKit."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

package/runtime/cli/aikit/agent_registry.py

@@ -5,8 +5,6 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any
 
-import yaml
-
 from cli.aikit.write_policy import normalize_write_policy, write_policy_public_fields
 
 
@@ -96,6 +94,10 @@ def find_capability(registry: dict[str, Any], agent_id: str, capability_id: str)
 
 
 def read_yaml(path: Path) -> dict[str, Any]:
+    try:
+        import yaml  # type: ignore
+    except ImportError as exc:
+        raise RuntimeError("PyYAML is required to read Agent DevKit manifests. Install requirements.txt.") from exc
     data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
     return data if isinstance(data, dict) else {}
 

package/runtime/cli/aikit/agentic_commands.py

@@ -0,0 +1,158 @@
+"""Explicit agentic planning and orchestration CLI commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cli.aikit.core.requests import AgentPromptRequest
+from cli.aikit.errors import DevKitError
+from cli.aikit.natural_prompt_runtime import run_agent_prompt_request
+from cli.aikit.orchestrator import build_execution_plan
+from cli.aikit.runtime_paths import ROOT
+
+
+def agentic_plan(root: Path, prompt_parts: list[str] | tuple[str, ...] | None) -> dict[str, Any]:
+    prompt = normalize_prompt(prompt_parts, command="plan")
+    plan = build_execution_plan(root, prompt, dry_run=True)
+    return {
+        "kind": "agentic-plan",
+        "status": plan.get("status") or "planned",
+        "ok": True,
+        "dry_run": True,
+        "prompt_received": True,
+        "prompt_length": len(prompt),
+        "summary": plan_summary(plan),
+        "execution_plan": plan,
+        "orchestration_trace": plan.get("trace", []),
+        "response": "Plano agentico gerado sem executar LLM, automacoes ou escritas externas.",
+    }
+
+
+def agentic_execute(
+    prompt_parts: list[str] | tuple[str, ...] | None,
+    *,
+    llm: str | None = None,
+    dry_run: bool = False,
+    session_id: str | None = None,
+    new_session: bool = False,
+    no_llm_fallback: bool = False,
+    prog_name: str = "agent",
+    project: str | None = None,
+    mode: str = "execute",
+) -> dict[str, Any]:
+    prompt = normalize_prompt(prompt_parts, command=mode)
+    if dry_run:
+        payload = agentic_plan(ROOT, [prompt])
+        payload["command_mode"] = mode
+        return payload
+    result = run_agent_prompt_request(
+        AgentPromptRequest(
+            prompt=prompt,
+            llm=llm,
+            dry_run=False,
+            session_id=session_id,
+            new_session=new_session,
+            no_llm_fallback=no_llm_fallback,
+            prog_name=prog_name,
+            project=project,
+        )
+    )
+    return attach_agentic_metadata(result, prompt=prompt, mode=mode)
+
+
+def normalize_prompt(prompt_parts: list[str] | tuple[str, ...] | None, *, command: str) -> str:
+    prompt = " ".join(str(part) for part in (prompt_parts or [])).strip()
+    if not prompt:
+        raise DevKitError(f"agent {command} requires a natural-language prompt")
+    return prompt
+
+
+def plan_summary(plan: dict[str, Any]) -> dict[str, Any]:
+    specialist_tasks = [task for task in plan.get("specialist_tasks") or [] if isinstance(task, dict)]
+    configuration_tasks = [task for task in plan.get("configuration_tasks") or [] if isinstance(task, dict)]
+    review_task = plan.get("review_task") if isinstance(plan.get("review_task"), dict) else {}
+    model_plan = plan.get("model_plan") if isinstance(plan.get("model_plan"), dict) else {}
+    routing_decision = plan.get("routing_decision") if isinstance(plan.get("routing_decision"), dict) else {}
+    autonomy = plan.get("autonomy_contract") if isinstance(plan.get("autonomy_contract"), dict) else {}
+    needs_input = (
+        plan.get("status") == "needs-input"
+        or bool(configuration_tasks)
+        or model_plan.get("strategy") == "human"
+        or autonomy.get("requires_human") is True
+        or autonomy.get("status") == "needs-input"
+    )
+    return {
+        "routing_status": routing_decision.get("status"),
+        "selected_agent_id": routing_decision.get("selected_agent_id"),
+        "selected_capability_id": routing_decision.get("selected_capability_id"),
+        "model_strategy": model_plan.get("strategy"),
+        "local_llm_selected": model_plan.get("local_llm_selected"),
+        "specialist_tasks": len(specialist_tasks),
+        "configuration_tasks": len(configuration_tasks),
+        "review_required": bool(review_task.get("required") or review_task.get("status") in {"pending", "required"}),
+        "collaboration_enabled": bool(plan.get("collaboration_enabled")),
+        "controller_enabled": bool(plan.get("controller_enabled")),
+        "needs_input": needs_input,
+    }
+
+
+def attach_agentic_metadata(result: dict[str, Any], *, prompt: str, mode: str) -> dict[str, Any]:
+    plan = result.get("execution_plan") if isinstance(result.get("execution_plan"), dict) else None
+    if plan is None:
+        plan = local_shortcut_execution_plan(prompt=prompt, result=result, mode=mode)
+        result["execution_plan"] = plan
+    result.setdefault("orchestration_trace", plan.get("trace", []))
+    result["agentic_summary"] = plan_summary(plan)
+    result["command_mode"] = mode
+    result["agentic_command"] = mode
+    return result
+
+
+def local_shortcut_execution_plan(*, prompt: str, result: dict[str, Any], mode: str) -> dict[str, Any]:
+    status = str(result.get("status") or "ok")
+    local_mode = str(result.get("mode") or result.get("action") or "local-shortcut")
+    ok = result.get("ok") is not False and status not in {"blocked", "failed", "needs-input", "needs-review"}
+    return {
+        "schema_version": "ai-devkit.agentic-plan/v1",
+        "status": "completed" if ok else status,
+        "prompt": prompt,
+        "dry_run": False,
+        "command_mode": mode,
+        "routing_decision": {
+            "status": "selected",
+            "selected_agent_id": "agent-devkit",
+            "selected_capability_id": local_mode,
+            "method": "local-shortcut",
+            "confidence": 1.0,
+        },
+        "model_plan": {
+            "strategy": "deterministic-local",
+            "local_llm_selected": False,
+            "local_llm_recommended": False,
+            "fallback": None,
+        },
+        "specialist_tasks": [],
+        "configuration_tasks": [],
+        "review_task": {
+            "agent_id": "execution-reviewer",
+            "capability_id": "review-final-output",
+            "status": "not-required",
+            "required": False,
+        },
+        "review_gate": {
+            "required": False,
+            "status": "not-required",
+            "reason": "local deterministic shortcut",
+        },
+        "collaboration_enabled": False,
+        "controller_enabled": False,
+        "trace": [
+            {
+                "agent_id": "task-orchestrator",
+                "action": "local-shortcut",
+                "mode": local_mode,
+                "status": status,
+            }
+        ],
+    }

package/runtime/cli/aikit/app_home.py

@@ -20,6 +20,7 @@ APP_DIRS = (
     "memory",
     "sessions",
     "tasks",
+    "backups",
     "policies",
     "audit",
     "secrets",

package/runtime/cli/aikit/audit.py

@@ -58,7 +58,7 @@ def record_audit(
     execution_id = f"exec_{now_utc().strftime('%Y%m%d%H%M%S')}_{uuid.uuid4().hex[:8]}"
     prompt = extract_prompt(args)
     try:
-        safe_result = redact_value(result or {})
+        safe_result = redact_value(result or {}, redact_access_keys=True)
         safe_prompt = redact_secrets(prompt) if prompt else None
         safe_error = redact_secrets(error) if error else None
     except Exception as exc:  # noqa: BLE001 - never write an unredacted audit fallback.
@@ -227,25 +227,35 @@ def find_audit_json(execution_id: str) -> Path:
     return matches[0]
 
 
-def redact_value(value: Any) -> Any:
+def redact_value(value: Any, *, redact_access_keys: bool = False, parent_key: str | None = None) -> Any:
     if isinstance(value, str):
         return redact_secrets(value)
     if isinstance(value, list):
-        return [redact_value(item) for item in value]
+        return [redact_value(item, redact_access_keys=redact_access_keys, parent_key=parent_key) for item in value]
     if isinstance(value, tuple):
-        return [redact_value(item) for item in value]
+        return [redact_value(item, redact_access_keys=redact_access_keys, parent_key=parent_key) for item in value]
     if isinstance(value, dict):
         redacted: dict[str, Any] = {}
         for key, item in value.items():
             key_text = str(key)
-            if secret_key(key_text):
+            if secret_key(key_text) or access_key(key_text, parent_key=parent_key, enabled=redact_access_keys):
                 redacted[key_text] = "[REDACTED_SECRET]"
             else:
-                redacted[key_text] = redact_value(item)
+                redacted[key_text] = redact_value(item, redact_access_keys=redact_access_keys, parent_key=key_text)
         return redacted
     return value
 
 
+def access_key(key: str, *, parent_key: str | None, enabled: bool) -> bool:
+    if not enabled:
+        return False
+    normalized = key.lower().replace("-", "_")
+    if normalized in {"owner_key", "contributor_key", "shared_key"}:
+        return True
+    parent = (parent_key or "").lower().replace("-", "_")
+    return normalized == "key" and parent in {"owner_access", "contributor_access", "shared_access"}
+
+
 def secret_key(key: str) -> bool:
     normalized = key.lower().replace("-", "_")
     if normalized in {"token_estimate", "tokens", "prompt_tokens", "completion_tokens", "total_tokens"}:

package/runtime/cli/aikit/catalog.py

@@ -2,24 +2,28 @@
 
 from __future__ import annotations
 
+import json
 import re
 from pathlib import Path
 from typing import Any
 
+from cli.aikit.app_home import cache_home
 from cli.aikit.agent_registry import load_agent_registry
 from cli.aikit.errors import DevKitError
+from cli.aikit.extensions import local_extensions_list
+from cli.aikit.local_artifacts import local_agent_list, local_automation_list, script_list, skill_list
 from cli.aikit.providers import ProviderRegistryError, list_providers
 from cli.aikit.runtime_paths import ROOT
+from cli.aikit.toolchain import list_toolchain
+from cli.aikit.workflows import workflow_list
 
 
 CATALOG_SCHEMA_VERSION = "agent-devkit.catalog/v1"
 
 
-def catalog_list(root: Path | None = None, *, item_type: str | None = None) -> dict[str, Any]:
+def catalog_list(root: Path | None = None, *, item_type: str | None = None, filters: dict[str, Any] | None = None) -> dict[str, Any]:
     root = root or ROOT
-    items = catalog_items(root)
-    if item_type:
-        items = [item for item in items if item["type"] == item_type]
+    items = filtered_catalog_items(root, item_type=item_type, filters=filters)
     return {
         "kind": "catalog",
         "schema_version": CATALOG_SCHEMA_VERSION,
@@ -28,20 +32,19 @@ def catalog_list(root: Path | None = None, *, item_type: str | None = None) -> d
         "query": None,
         "type": item_type,
         "count": len(items),
+        "filters": public_filters(item_type=item_type, filters=filters),
         "items": items,
     }
 
 
-def catalog_search(query: str, root: Path | None = None, *, item_type: str | None = None) -> dict[str, Any]:
+def catalog_search(query: str, root: Path | None = None, *, item_type: str | None = None, filters: dict[str, Any] | None = None) -> dict[str, Any]:
     root = root or ROOT
     query = (query or "").strip()
     if not query:
         raise DevKitError("catalog search requires a query")
     tokens = tokenize(query)
     scored: list[tuple[int, dict[str, Any]]] = []
-    for item in catalog_items(root):
-        if item_type and item["type"] != item_type:
-            continue
+    for item in filtered_catalog_items(root, item_type=item_type, filters=filters):
         score = match_score(item, tokens)
         if score > 0:
             enriched = dict(item)
@@ -56,6 +59,7 @@ def catalog_search(query: str, root: Path | None = None, *, item_type: str | Non
         "query": query,
         "type": item_type,
         "count": len(scored),
+        "filters": public_filters(item_type=item_type, filters=filters),
         "items": [item for _score, item in scored],
     }
 
@@ -80,6 +84,25 @@ def catalog_show(item_id: str, root: Path | None = None, *, item_type: str | Non
     raise DevKitError(f"catalog item not found{suffix}: {item_id}")
 
 
+def catalog_rebuild_index(root: Path | None = None) -> dict[str, Any]:
+    root = root or ROOT
+    items = catalog_items(root)
+    path = catalog_index_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "schema_version": CATALOG_SCHEMA_VERSION,
+        "items": items,
+    }
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return {
+        "kind": "catalog-index",
+        "schema_version": CATALOG_SCHEMA_VERSION,
+        "status": "rebuilt",
+        "path": str(path),
+        "count": len(items),
+    }
+
+
 def catalog_items(root: Path) -> list[dict[str, Any]]:
     registry = load_agent_registry(root)
     items: list[dict[str, Any]] = []
@@ -90,6 +113,33 @@ def catalog_items(root: Path) -> list[dict[str, Any]]:
         if isinstance(capability, dict):
             items.append(capability_item(capability))
     items.extend(provider_items(root))
+    items.extend(workflow_items())
+    items.extend(tool_items(root))
+    items.extend(skill_items(root))
+    items.extend(plugin_items(root))
+    items.extend(extension_items())
+    items.extend(local_artifact_items())
+    return items
+
+
+def filtered_catalog_items(root: Path, *, item_type: str | None = None, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+    filters = {key: value for key, value in (filters or {}).items() if value not in {None, ""}}
+    items = catalog_items(root)
+    if item_type:
+        items = [
+            item
+            for item in items
+            if item["type"] == item_type or item.get("local_kind") == item_type
+        ]
+    for key, value in filters.items():
+        if key == "provider":
+            items = [item for item in items if value in (item.get("providers_required") or []) or item.get("provider") == value]
+        elif key == "status":
+            items = [item for item in items if item.get("status") == value]
+        elif key == "write_policy":
+            items = [item for item in items if item.get("write_policy") == value]
+        elif key == "readiness":
+            items = [item for item in items if (item.get("readiness") or {}).get("status") == value]
     return items
 
 
@@ -105,6 +155,7 @@ def agent_item(agent: dict[str, Any]) -> dict[str, Any]:
         "write_policy": agent.get("write_policy"),
         "write_policy_metadata": agent.get("write_policy_metadata"),
         "source_contract": None,
+        "provider": None,
         "providers_required": [],
         "runner": None,
         "agent_mode": agent.get("agent_mode") or {},
@@ -142,6 +193,7 @@ def capability_item(capability: dict[str, Any]) -> dict[str, Any]:
         "write_policy": capability.get("write_policy"),
         "write_policy_metadata": capability.get("write_policy_metadata"),
         "source_contract": capability.get("source_contract") or capability.get("source"),
+        "provider": provider,
         "providers_required": providers_required,
         "runner": capability.get("runner") or (capability.get("runtime") or {}).get("runner"),
         "agent_mode": None,
@@ -174,6 +226,7 @@ def provider_items(root: Path) -> list[dict[str, Any]]:
                 "path": provider.get("path"),
                 "write_policy": "read_only",
                 "source_contract": None,
+                "provider": provider.get("id"),
                 "providers_required": [],
                 "runner": None,
                 "agent_mode": None,
@@ -185,6 +238,223 @@ def provider_items(root: Path) -> list[dict[str, Any]]:
     return items
 
 
+def workflow_items() -> list[dict[str, Any]]:
+    try:
+        payload = workflow_list()
+    except Exception:
+        return []
+    return [
+        {
+            "id": str(workflow.get("id") or ""),
+            "type": "workflow",
+            "description": workflow.get("description") or workflow.get("title") or "",
+            "status": "ok",
+            "version": None,
+            "path": workflow.get("path"),
+            "write_policy": workflow.get("write_policy"),
+            "source_contract": None,
+            "provider": None,
+            "providers_required": workflow.get("providers_required") or [],
+            "runner": "workflow",
+            "agent_mode": None,
+            "routing": {},
+            "prompt_examples": workflow.get("examples") or [],
+            "readiness": {"status": "ready"},
+            "next_step": f"agent workflow show {workflow.get('id')}",
+        }
+        for workflow in payload.get("items") or []
+        if isinstance(workflow, dict)
+    ]
+
+
+def tool_items(root: Path) -> list[dict[str, Any]]:
+    try:
+        payload = list_toolchain(root)
+    except Exception:
+        return []
+    return [
+        {
+            "id": str(tool.get("id") or ""),
+            "type": "tool",
+            "description": tool.get("notes") or tool.get("label") or "",
+            "status": "required" if tool.get("required") else "optional",
+            "version": None,
+            "path": None,
+            "write_policy": "confirm",
+            "source_contract": None,
+            "provider": None,
+            "providers_required": [],
+            "runner": tool.get("command"),
+            "agent_mode": None,
+            "routing": {},
+            "prompt_examples": [],
+            "readiness": {"status": "requires-install-check", "command": tool.get("command")},
+            "next_step": f"agent toolchain doctor {tool.get('id')}",
+        }
+        for tool in payload.get("items") or []
+        if isinstance(tool, dict)
+    ]
+
+
+def skill_items(root: Path) -> list[dict[str, Any]]:
+    catalog = parse_markdown_catalog(root / "vendor" / "skills" / "CATALOG.md", item_type="skill")
+    if catalog:
+        return catalog
+    return filesystem_items(root / "vendor" / "skills", item_type="skill", marker="SKILL.md")
+
+
+def plugin_items(root: Path) -> list[dict[str, Any]]:
+    catalog = parse_markdown_catalog(root / "vendor" / "plugins" / "CATALOG.md", item_type="plugin")
+    if catalog:
+        return catalog
+    return filesystem_items(root / "vendor" / "plugins", item_type="plugin", marker="README.md")
+
+
+def extension_items() -> list[dict[str, Any]]:
+    try:
+        payload = local_extensions_list()
+    except Exception:
+        return []
+    return [
+        {
+            "id": str(item.get("id") or ""),
+            "type": "extension",
+            "description": f"Local extension at {item.get('path')}",
+            "status": "enabled" if item.get("enabled") else "disabled",
+            "version": None,
+            "path": item.get("path"),
+            "write_policy": "local_config_write",
+            "source_contract": None,
+            "provider": None,
+            "providers_required": [],
+            "runner": None,
+            "agent_mode": None,
+            "routing": {},
+            "prompt_examples": [],
+            "readiness": {"status": "ready" if item.get("enabled") else "disabled"},
+            "next_step": f"agent local validate {item.get('id')}",
+        }
+        for item in payload.get("items") or []
+        if isinstance(item, dict)
+    ]
+
+
+def local_artifact_items() -> list[dict[str, Any]]:
+    payloads = []
+    for factory, item_type, command in (
+        (skill_list, "skill", "agent skill show"),
+        (script_list, "script", "agent script run"),
+        (local_agent_list, "agent", "agent agents validate"),
+        (local_automation_list, "automation", "agent local automation show"),
+    ):
+        try:
+            payload = factory()
+        except Exception:
+            continue
+        for item in payload.get("items") or []:
+            if not isinstance(item, dict):
+                continue
+            payloads.append(
+                {
+                    "id": str(item.get("id") or ""),
+                    "type": item_type,
+                    "local_kind": item.get("kind"),
+                    "origin": "local",
+                    "description": f"Local {item_type} at {item.get('path')}",
+                    "status": "enabled" if item.get("enabled") else "disabled",
+                    "version": None,
+                    "path": item.get("path"),
+                    "write_policy": "local_config_write",
+                    "source_contract": None,
+                    "provider": None,
+                    "providers_required": [],
+                    "runner": None,
+                    "agent_mode": None,
+                    "routing": {},
+                    "prompt_examples": [],
+                    "readiness": {"status": "ready" if item.get("enabled") else "disabled"},
+                    "next_step": f"{command} {item.get('id')}",
+                }
+            )
+    return payloads
+
+
+def parse_markdown_catalog(path: Path, *, item_type: str) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    items: list[dict[str, Any]] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("| `"):
+            continue
+        cells = [cell.strip() for cell in stripped.strip("|").split("|")]
+        if len(cells) < 3:
+            continue
+        item_id = cells[0].strip("` ")
+        description = cells[1]
+        path_cell = cells[-1].strip("` ")
+        items.append(
+            {
+                "id": item_id,
+                "type": item_type,
+                "description": description,
+                "status": "available",
+                "version": None,
+                "path": path_cell,
+                "write_policy": "read_only",
+                "source_contract": None,
+                "provider": None,
+                "providers_required": [],
+                "runner": None,
+                "agent_mode": None,
+                "routing": {},
+                "prompt_examples": [],
+                "readiness": {"status": "available"},
+                "next_step": f"Use {item_type} {item_id} when relevant.",
+            }
+        )
+    return items
+
+
+def filesystem_items(root: Path, *, item_type: str, marker: str) -> list[dict[str, Any]]:
+    if not root.exists():
+        return []
+    items = []
+    for marker_path in sorted(root.glob(f"**/{marker}")):
+        item_root = marker_path.parent
+        items.append(
+            {
+                "id": item_root.name,
+                "type": item_type,
+                "description": "",
+                "status": "available",
+                "version": None,
+                "path": str(item_root.relative_to(ROOT)) if item_root.is_relative_to(ROOT) else str(item_root),
+                "write_policy": "read_only",
+                "source_contract": None,
+                "provider": None,
+                "providers_required": [],
+                "runner": None,
+                "agent_mode": None,
+                "routing": {},
+                "prompt_examples": [],
+                "readiness": {"status": "available"},
+            }
+        )
+    return items
+
+
+def catalog_index_path() -> Path:
+    return cache_home() / "catalog-index.json"
+
+
+def public_filters(*, item_type: str | None, filters: dict[str, Any] | None) -> dict[str, Any]:
+    payload = {key: value for key, value in (filters or {}).items() if value not in {None, ""}}
+    if item_type:
+        payload["type"] = item_type
+    return payload
+
+
 def tokenize(value: str) -> set[str]:
     tokens = {token for token in re.findall(r"[a-z0-9]+", value.lower()) if token}
     return expand_query_tokens(tokens)