natureco-cli 5.18.2 → 5.19.0

package/skills/lark-workflow-meeting-summary/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: lark-workflow-meeting-summary
+version: 1.0.0
+description: "会议纪要整理工作流：汇总指定时间范围内的会议纪要并生成结构化报告。当用户需要整理会议纪要、生成会议周报、回顾一段时间内的会议内容时使用。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+---
+
+# 会议纪要汇总工作流
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**。然后阅读 [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md)，了解会议纪要相关操作。
+
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
+> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
+> 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**
+> 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
+> 4. 了解会议总结、分析和信息提取的标准流程
+
+## 适用场景
+
+- "帮我整理这周的会议纪要" / "总结最近的会议" / "生成会议周报"
+- "看看今天开了哪些会" / "回顾过去一周开了哪些会"
+
+## 前置条件
+
+仅支持 **user 身份**。执行前确保已授权：
+
+```bash
+lark-cli auth login --domain vc        # 基础（查询+纪要）
+lark-cli auth login --domain vc,drive   # 含读取纪要文档正文、生成文档
+```
+
+## 工作流
+
+```
+{时间范围} ─► vc +search ──► 会议列表 (meeting_ids)
+                   │
+                   ▼
+               vc +detail ──► 获取 note_id 
+                   │
+                   ▼
+               note +detail ──► 纪要文档 tokens
+                   │
+                   ▼
+               drive metas batch_query 纪要元数据
+                   │
+                   ▼
+               结构化报告
+```
+
+### Step 1: 确定时间范围
+
+默认**过去 7 天**。推断规则："今天"→当天，"这周"→本周一~now，"上周"→上周一~上周日，"这个月"→1日~now。
+
+> **注意**：日期转换必须调用系统命令（如 `date`），不要心算。时间范围参数需根据 CLI 实际要求格式化（通常为 `YYYY-MM-DD` 或 ISO 8601）。
+
+### Step 2: 查询会议记录
+
+```bash
+# page-size 最大为 30
+lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --format json --page-size 30
+```
+
+- 时间范围拆分：搜索的时间范围最大为 1 个月。搜索更长时间范围的会议，需要拆分为多次时间范围为一个月查询。
+- `--end` 为**包含当天**的日期（即查"今天"时 start 和 end 都填今天）
+- `--format json` 输出 JSON 格式，你更佳擅长解析 JSON 数据。
+- `--page-size 30` 每页最多 30 条。
+- 有 `page_token` 时必须继续翻页，收集所有 `id` 字段（meeting-id）
+
+### Step 3: 获取纪要元数据
+
+1. 查询会议关联的纪要信息
+```bash
+# 首先获取 note_id 和 minute_token
+lark-cli vc +detail --meeting-ids "id1,id2,...,idN"
+
+# 然后用 note_id 获取文档 tokens（如有多个需分别获取）
+lark-cli note +detail --note-id "note_id"
+```
+- 根据上一步搜集到的 `meeting-id` 查询。
+- 单次最多查询 50 个，超过 50 个需分批调用。
+- 部分会议没有 `note_id` 或报错 `no notes available`，在最终输出中标注"无纪要"。
+- 记录每个纪要的 `note_id`（纪要 ID）、`note_display_type`（展示类型：`unknown` / `normal` / `unified`）、`note_doc_token`（纪要文档 Token）和 `verbatim_doc_token`（逐字稿文档 Token）。
+
+> **逐字稿路由按 `note_display_type` 决定**（详见 [vc-domain-boundaries.md](../lark-vc/references/vc-domain-boundaries.md) 的 Note 域）：
+> - `normal`：逐字稿是独立文档，链接/正文走 `verbatim_doc_token`。
+> - `unified`：逐字稿**不是独立文档**，没有可分享的逐字稿文档链接；需要逐字稿内容时用 `note +transcript --note-id <note_id>`（[lark-note](../lark-note/SKILL.md)）拉取到本地，报告中标注"unified 纪要"即可。
+
+2. 获取纪要文档和逐字稿文档链接
+```bash
+# 学习命令使用方式
+lark-cli schema drive.metas.batch_query
+
+# 批量获取纪要文档与逐字稿链接: 一次最多查询 10 个文档
+# 仅对 note_doc_token 与 normal 纪要的 verbatim_doc_token 查询链接
+lark-cli drive metas batch_query --data '{"request_docs": [{"doc_type": "docx", "doc_token": "<doc_token>"}], "with_url": true}'
+```
+
+### Step 4: 整理纪要报告
+
+根据时间跨度选择输出格式：
+
+- **单日汇总**（"今天"/"昨天"）：用"今日会议概览"标题，逐会议列出会议时间、主题、纪要链接、逐字稿链接（`unified` 纪要无逐字稿链接，标注"unified 纪要，逐字稿需 `note +transcript` 拉取"）。
+- **多日/周报**（"这周"/"过去 7 天"等）：用"会议纪要周报"标题，含概览统计、逐会议详情。
+
+### Step 5: 生成文档（可选，用户要求时）
+
+阅读 [`../lark-doc/SKILL.md`](../lark-doc/SKILL.md) 学习云文档技能。
+
+```bash
+lark-cli docs +create --api-version v2 --doc-format markdown --content $'<title>会议纪要汇总 (<start> - <end>)</title>\n<内容>'
+# 或追加到已有文档
+lark-cli docs +update --api-version v2 --doc "<url_or_token>" --command append --doc-format markdown --content $'<内容>'
+```
+
+## 参考
+
+- [lark-shared](../lark-shared/SKILL.md) — 认证、权限（必读）
+- [lark-vc](../lark-vc/SKILL.md) — `+search`、`+detail` 详细用法
+- [lark-note](../lark-note/SKILL.md) — `note +detail`、`note +transcript`（unified 纪要逐字稿）
+- [lark-doc](../lark-doc/SKILL.md) — `+fetch`、`+create`、`+update` 详细用法

package/skills/linting-neostandard-eslint9/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: linting-neostandard-eslint9
+description: Configures ESLint v9 flat config and neostandard for JavaScript and TypeScript projects, including migrating from legacy `.eslintrc*` files or the `standard` package. Use when you need to set up or fix linting with `eslint.config.js` or `eslint.config.mjs`, troubleshoot lint errors, configure neostandard rules, migrate from `.eslintrc` to flat config, or integrate linting into CI pipelines and pre-commit hooks.
+metadata:
+  tags: linting, neostandard, eslint, eslint9, flat-config, javascript, typescript
+---
+
+## When to use
+
+Use this skill when you need to:
+- Set up linting in a JavaScript or TypeScript project
+- Use `neostandard` as a Standard-like ESLint v9 flat-config baseline
+- Configure `eslint@9` with the flat config system (`eslint.config.js`/`eslint.config.mjs`)
+- Migrate from `standard` to `neostandard` or ESLint v9
+- Migrate from legacy `.eslintrc*` configuration to ESLint v9
+- Run linting consistently in CI and local development
+
+## Quick start: basic neostandard setup
+
+Install dependencies and create a minimal `eslint.config.js`:
+
+```bash
+npm install --save-dev eslint@9 neostandard
+```
+
+```js
+// eslint.config.js
+import neostandard from 'neostandard'
+
+export default neostandard()
+```
+
+Verify the config works:
+
+```bash
+npx eslint .
+```
+
+## Common setup workflow (new project)
+
+1. Install `eslint@9` and `neostandard` (see Quick start above)
+2. Create `eslint.config.js` with `neostandard()` as the base
+3. Add any project-specific rule overrides on top
+4. Run `npx eslint .` to confirm no config errors
+5. Add a lint script to `package.json`: `"lint": "eslint ."`
+6. Integrate into CI with a non-fix run; use `--fix` only in local workflows
+
+## How to use
+
+Read individual rule files for implementation details and examples:
+
+- [rules/neostandard.md](rules/neostandard.md) - Install, configure, and extend neostandard with ESLint
+- [rules/eslint-v9-flat-config.md](rules/eslint-v9-flat-config.md) - Build ESLint v9 flat config for JS/TS projects
+- [rules/migration-from-standard.md](rules/migration-from-standard.md) - Migrate from `standard` to `neostandard` or ESLint v9
+- [rules/migration-from-legacy-eslint.md](rules/migration-from-legacy-eslint.md) - Migrate from `.eslintrc*` to flat config safely
+- [rules/ci-and-editor-integration.md](rules/ci-and-editor-integration.md) - CI scripts, pre-commit, and editor setup
+
+## Core principles
+
+- Prefer reproducible linting with pinned major versions
+- Keep config minimal and explicit
+- Use flat config for ESLint v9 projects
+- Treat lint failures as quality gates in CI
+- Enable auto-fix for local workflows, but validate with non-fix CI runs

package/skills/loop-me/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: loop-me
+description: Grill me about specs for the workflows I want to build, within this workspace.
+disable-model-invocation: true
+argument-hint: "A workflow to design, or nothing to go find one"
+---
+
+Run a stateful `/grilling` session whose only output is **workflow** specs. Use the grilling discipline — relentless, one question at a time, a recommended answer attached to each — aimed at the vocabulary and goal below. Create, edit, and delete specs as the grilling resolves things.
+
+## The loop lens
+
+A **loop** is a recurring pattern in the user's life: their career, their week, their morning, a single repeated activity. Picturing a life as loops within loops reveals how predictable its activities really are — which is what makes them worth **delegating**. Use the lens to find loops worth specifying, and propose ones the user hasn't noticed.
+
+A **workflow** is the spec of one loop, made real. You run a workflow on a loop — the loop is its running instantiation. Workflows live in `workflows/*.md` and are the source of truth.
+
+## Vocabulary
+
+A shared language, reached for only when a workflow calls for it — never a checklist. **Mandate nothing structural**: a workflow needs no AI, no checkpoint, and no schedule unless the grilling shows it does.
+
+- **Trigger** — what fires each run: an **event** (a new email, a new issue) or a **schedule** (every morning). Event-triggering is usually the more efficient.
+- **Checkpoint** — a human-in-the-loop point where the user is asked to verify or decide. Some workflows have none and run autonomously; some use no AI at all.
+- **Push right** — defer the checkpoint as far as it will go. Do maximal work before involving the human, so they are asked once, late, with everything prepared.
+- **Brief** — what a checkpoint presents: a tight, decision-ready summary — what was produced, why, and a link down to the asset itself — never the raw output. The user reads a brief, not a draft. Speed of review is imperative.
+
+## Definition of done
+
+A workflow spec is done when an implementer agent could build it without asking a single question. Grill until then; nothing is done while a question remains.
+
+## The workspace
+
+- `workflows/*.md` — one spec per workflow.
+- `NOTES.md` — raw notes on the user's world: the tools they use, the channels they process, and their own terminology for both. When it is empty or thin, interview them about their world before specifying anything. Sharpen fuzzy terms into canonical ones as they surface, and record them here.

package/skills/microsoft-foundry/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: microsoft-foundry
+description: "Deploy, evaluate, fine-tune, and manage Foundry agents end-to-end with azd: hosted agent scaffold/run/deploy, prompt agent create, batch eval, continuous eval, prompt optimizer, Agent Optimizer scaffold, agent.yaml, dataset curation from traces, model fine-tuning (SFT/DPO/RFT). USE FOR: azd ai agent, azd provision/deploy, deploy agent, hosted agent, create agent, add tool to agent, invoke agent, evaluate agent, continuous eval, continuous monitoring, optimize prompt, improve prompt, optimize agent instructions, agent optimizer, deploy model, Foundry project, RBAC, role assignment, permissions, quota, capacity, region, troubleshoot agent, deployment failure, AI Services, create Foundry resource, provision, knowledge index, customize deployment, onboard, availability, fine-tune, SFT, DPO, RFT, training-data, grader, distillation, fine-tuned model, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare)."
+license: MIT
+metadata:
+  author: Microsoft
+  version: "1.1.27"
+---
+
+# Microsoft Foundry Skill
+
+This skill helps developers work with Microsoft Foundry resources, covering model discovery and deployment, complete dev lifecycle of AI agent, evaluation workflows, and troubleshooting.
+
+## Pre-Execution Requirements
+
+Before using Foundry MCP operations, call the Azure MCP `foundry` tool and inspect the available Foundry MCP tools and related parameters. Treat this as the discovery/help step for MCP-based workflows.
+
+## Sub-Skills
+
+> **MANDATORY: Before executing ANY workflow-specific steps, you MUST read the corresponding sub-skill document.** Do not call workflow-specific MCP tools for a workflow without reading its skill document. This applies even if you already know the MCP tool parameters — the skill document contains required workflow steps, pre-checks, and validation logic that must be followed. This rule applies on every new user message that triggers a different workflow, even if the skill is already loaded.
+
+This skill includes specialized sub-skills for specific workflows. **Use these instead of the main skill when they match your task:**
+
+| Sub-Skill | When to Use | Reference |
+|-----------|-------------|-----------|
+| **deploy** | Deploy hosted agents to Foundry, smoke-test a deployment, create or update prompt agents, and manage agent versions and multi-environment deploys. | [deploy](foundry-agent/deploy/deploy.md) |
+| **invoke** | Send messages to an agent, single or multi-turn conversations | [invoke](foundry-agent/invoke/invoke.md) |
+| **invocations-ws** | Build, deploy, and connect to hosted agents that speak the `invocations_ws` duplex WebSocket protocol — voice agents, real-time streams, and signaling for out-of-band media transports. | [invocations-ws](foundry-agent/invocations-ws/invocations-ws.md) |
+| **observe** | Evaluate agent quality, run batch evals, analyze failures, optimize prompts, improve agent instructions, compare versions, set up CI/CD monitoring, and enable continuous production evaluation | [observe](foundry-agent/observe/observe.md) |
+| **trace** | Query traces, analyze latency/failures, correlate eval results to specific responses via App Insights `customEvents` | [trace](foundry-agent/trace/trace.md) |
+| **troubleshoot** | View hosted agent logs, query telemetry, diagnose failures | [troubleshoot](foundry-agent/troubleshoot/troubleshoot.md) |
+| **create (quick start)** | Create a new hosted Foundry agent from scratch end-to-end — scaffold, provision a new Foundry project, deploy, and smoke-test. Opinionated happy-path that accepts common overrides (language, region, sample, topic, existing project, existing model). For anything not covered by the quickstart, use **create**. | [create/quick-start-hosted.md](foundry-agent/create/quick-start-hosted.md) |
+| **create** | Use when the standard end-to-end happy path doesn't fit — lifting existing agent code into the project, deploying outside the default code path, wiring connections at scaffold time, advanced setup, or recovering from a failed quickstart run. | [create](foundry-agent/create/create-hosted.md) |
+| **agent-optimizer** | Make existing Python hosted-agent code optimization-ready, configure eval.yaml, run Agent Optimizer jobs, apply candidates locally, and deploy through azd after review. | [agent-optimizer](foundry-agent/agent-optimizer/agent-optimizer.md) |
+| **eval-datasets** | Harvest production traces into evaluation datasets, manage dataset versions and splits, track evaluation metrics over time, detect regressions, and maintain full lineage from trace to deployment. Use for: create dataset from traces, dataset versioning, evaluation trending, regression detection, dataset comparison, eval lineage. | [eval-datasets](foundry-agent/eval-datasets/eval-datasets.md) |
+| **project/create** | Creating a new Azure AI Foundry project for hosting agents and models. Use when onboarding to Foundry or setting up new infrastructure. | [project/create/create-foundry-project.md](project/create/create-foundry-project.md) |
+| **resource/create** | Creating Azure AI Services multi-service resource (Foundry resource) using Azure CLI. Use when manually provisioning AI Services resources with granular control. | [resource/create/create-foundry-resource.md](resource/create/create-foundry-resource.md) |
+| **private-network** | Answer questions about Foundry network isolation **and** deploy Foundry with VNet isolation (BYO VNet, Managed VNet, hybrid). Covers architecture concepts, template selection, deployment, and post-deployment validation. | [resource/private-network/private-network.md](resource/private-network/private-network.md) |
+| **models/deploy-model** | Unified model deployment with intelligent routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI), and capacity discovery across regions. Routes to sub-skills: `preset` (quick deploy), `customize` (full control), `capacity` (find availability). | [models/deploy-model/SKILL.md](models/deploy-model/SKILL.md) |
+| **quota** | Managing quotas and capacity for Microsoft Foundry resources. Use when checking quota usage, troubleshooting deployment failures due to insufficient quota, requesting quota increases, or planning capacity. | [quota/quota.md](quota/quota.md) |
+| **rbac** | Managing RBAC permissions, role assignments, managed identities, and service principals for Microsoft Foundry resources. Use for access control, auditing permissions, and CI/CD setup. | [rbac/rbac.md](rbac/rbac.md) |
+| **finetuning** | Fine-tune models on Azure AI Foundry — SFT distillation, DPO preference optimization, RFT with graders and tool calling. Dataset preparation, grader calibration, training, checkpoint selection, deployment, evaluation. Use for: fine-tune, SFT, DPO, RFT, training data, grader, distillation, fine-tuned model, large file upload. | [finetuning/SKILL.md](finetuning/SKILL.md) |
+
+> 💡 **Tip:** For a complete onboarding flow: `project/create` (public) or `private-network` (VNet isolation) → `models/deploy-model` → agent workflows (`create` → `deploy` → `invoke`).
+
+> 💡 **Fine-Tuning:** Use `finetuning` for all model customization — SFT distillation, DPO preference optimization, and RFT with graders. Includes quickstart, grader calibration, and training curve analysis.
+
+> 💡 **Model Deployment:** Use `models/deploy-model` for all deployment scenarios — it intelligently routes between quick preset deployment, customized deployment with full control, and capacity discovery across regions.
+
+> 💡 **Prompt Optimization:** For requests like "optimize my prompt" or "improve my agent instructions," load [observe](foundry-agent/observe/observe.md) and use the `prompt_optimize` MCP tool through that eval-driven workflow.
+
+## Infrastructure Lifecycle
+
+Match user intent to the correct infrastructure workflow.
+
+| User Intent | Workflow |
+|-------------|---------|
+| "Create Foundry" / "Set up Foundry" (ambiguous) | Use `AskUserQuestion`: (a) just an AI Services resource, (b) a project with public access, or (c) a project with network isolation? Route: (a) → [resource/create](resource/create/create-foundry-resource.md), (b) → [project/create](project/create/create-foundry-project.md), (c) → [private-network](resource/private-network/private-network.md) |
+| Set up Foundry with VNet isolation | [private-network](resource/private-network/private-network.md) |
+| Create a Foundry project (public) | [project/create](project/create/create-foundry-project.md) |
+| Create a bare Foundry resource | [resource/create](resource/create/create-foundry-resource.md) |
+
+## Agent Development Lifecycle
+
+Match user intent to the correct agent workflow. Read each sub-skill in order before executing.
+
+| User Intent | Workflow (read in order) |
+|-------------|------------------------|
+| Create a new hosted agent end-to-end (scaffold + deploy + test) | [quick-start-hosted](foundry-agent/create/quick-start-hosted.md) (self-contained end-to-end) |
+| Anything beyond the standard quickstart (existing code, deployment customization, scaffold-time connections, recovery) | [create](foundry-agent/create/create-hosted.md) → [deploy](foundry-agent/deploy/deploy.md) → [invoke](foundry-agent/invoke/invoke.md) |
+| Optimize existing Python hosted agent | [agent-optimizer](foundry-agent/agent-optimizer/agent-optimizer.md) → scaffold/review → eval.yaml → optimize → apply candidate → deploy → invoke |
+| Deploy an agent (code already exists) | deploy (includes eval-suite setup) → invoke → observe (evaluate/optimize) |
+| Update/redeploy an agent after code changes | deploy (includes eval-suite setup) → invoke → observe (evaluate/optimize) |
+| Invoke/test/chat with an agent | invoke |
+| Optimize / improve agent prompt or instructions | observe (Step 4: Optimize) |
+| Evaluate and optimize agent (full loop) | observe |
+| Enable continuous evaluation monitoring | observe (Step 6: CI/CD & Monitoring) |
+| Troubleshoot an agent issue | invoke → troubleshoot |
+| Fix a broken agent (troubleshoot + redeploy) | invoke → troubleshoot → apply fixes → deploy → invoke |
+
+## Agent: .foundry Workspace Standard
+
+Every agent source folder can keep Foundry-specific cache and overlay state under `.foundry/`:
+
+```text
+<agent-root>/
+  .foundry/
+    agent-metadata.yaml
+    agent-metadata.prod.yaml
+    suites/
+    datasets/
+    evaluators/
+    results/
+```
+
+- In azd projects, derive deployment context (project endpoint, agent name/version, ACR, App Insights) from `azure.yaml` plus `azd env get-values`; do not duplicate those values in metadata when azd already provides them.
+- `agent-metadata.yaml` is the preferred local/dev overlay for non-azd values, remote Foundry suite references, local cache paths, result summaries, and explicit overrides. Optional sidecar files such as `agent-metadata.prod.yaml` can hold a single prod or CI-targeted overlay without mixing multiple environments in one file.
+- `suites/`, `datasets/`, and `evaluators/` are local cache folders. Reuse them when they are current, and ask before refreshing or overwriting them.
+- See [Agent Metadata Contract](references/agent-metadata-contract.md) for the canonical schema and workflow rules.
+
+## Agent: Setup References
+
+- [Standard Agent Setup](references/standard-agent-setup.md) — advanced setup for production workloads that need data-residency control (bring-your-own Cosmos DB / Storage / AI Search via a Foundry capability host). The default `azd ai agent` flow uses **Basic Agent Setup** and does **not** provision `capabilityHosts/agents` — do not flag its absence as a bug. For default post-provision state, see the "Expected env-var fingerprint" section in [foundry-agent/create/create-hosted.md](foundry-agent/create/create-hosted.md).
+
+## Agent: Common Project Context Resolution
+
+Agent skills should run this step **only when they need configuration values they don't already have**. If a value (for example, agent root, environment, project endpoint, or agent name) is already known from the user's message or a previous skill in the same session, skip resolution for that value.
+
+### Step 1: Discover Agent Roots and azd Context
+
+First check whether the workspace has `azure.yaml` with services using `host: azure.ai.agent`.
+
+- **One azd agent service** -> use that service's `project` folder as the agent root.
+- **Multiple azd agent services** -> require the user to choose the target service/folder.
+- **No azd agent service** -> search the workspace for `.foundry/` folders that contain `agent-metadata.yaml` or `agent-metadata.<env>.yaml`.
+  - **One match** -> use that agent root.
+  - **Multiple matches** -> require the user to choose the target agent folder.
+  - **No matches** -> for create/deploy workflows, seed a new `.foundry/` folder during setup; for all other workflows, stop and ask the user which agent source folder to initialize.
+
+After selecting an agent root, keep all local `.foundry` cache inspection, source inspection, evaluator suggestions, dataset suggestions, and prompt-optimization context inside that folder only. Do **not** scan sibling agent folders unless the user explicitly switches roots.
+
+### Step 2: Resolve Environment and Deployment Context
+
+If `azure.yaml` is present, resolve the azd environment first:
+
+1. Environment explicitly named by the user
+2. `AZURE_ENV_NAME` from `azd env get-values`
+3. azd default environment from `.azure/config.json`
+4. Environment already selected earlier in the session
+
+Run `azd env get-values` for the selected environment when project/deployment values are not already known. Prefer azd values for deployment context:
+
+| azd Variable | Resolves To |
+|-------------|-------------|
+| `AZURE_AI_PROJECT_ENDPOINT` or `AZURE_AIPROJECT_ENDPOINT` | Project endpoint |
+| `AGENT_<SERVICE>_NAME` | Agent name for the selected azd service |
+| `AGENT_<SERVICE>_VERSION` | Agent version for the selected azd service |
+| `AZURE_CONTAINER_REGISTRY_NAME` or `AZURE_CONTAINER_REGISTRY_ENDPOINT` | ACR registry name / image URL prefix |
+| `APPLICATIONINSIGHTS_CONNECTION_STRING` | App Insights connection string for trace workflows |
+| `AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, `AZURE_AI_ACCOUNT_NAME`, `AZURE_AI_PROJECT_NAME` | Azure resource lookup and Playground links |
+
+When azd supplies these values, use them as the source of truth and do not copy them into `.foundry/agent-metadata*.yaml` on metadata writes.
+
+### Step 3: Select Metadata Overlay and Resolve Environment
+
+Inside the selected agent root, choose the metadata file in this order:
+1. Metadata filename or path explicitly provided by the user or workflow
+2. If an explicit environment is already known and `.foundry/agent-metadata.<env>.yaml` exists, use that file
+3. `.foundry/agent-metadata.yaml`
+4. If multiple metadata files remain and no rule above selects one, prompt the user to choose
+
+Read the selected metadata file and resolve any remaining environment choice in this order:
+1. Environment explicitly named by the user
+2. If the selected metadata file defines exactly one environment, use it
+3. Environment already selected earlier in the session
+4. `defaultEnvironment` from metadata
+
+If the selected metadata file still contains multiple environments and none of the rules above selects one, prompt the user to choose. Keep the selected agent root, metadata file, environment, and whether context came from azd or metadata visible in every workflow summary.
+
+If the selected environment exposes older `testSuites[]` metadata but not `evaluationSuites[]`, treat `testSuites[]` as the source for this session and normalize each entry in memory to the `evaluationSuites[]` shape before continuing. If the metadata is older still and only exposes legacy `testCases[]`, normalize that list the same way. Preserve dataset and evaluator fields, keep any existing `tags`, and map legacy `priority` to `tags.tier` only when `tags.tier` is missing: `P0` -> `smoke`, `P1` -> `regression`, `P2` -> `coverage`.
+
+### Step 4: Resolve eval.yaml Local Evaluation Intent
+
+If `eval.yaml` exists in the selected agent root, parse it before generating new suites:
+
+- `agent.name` -> target agent candidate; verify it matches the selected azd/metadata agent before using it.
+- `dataset.local_uri` -> local seed dataset candidate; legacy `dataset_file` may be normalized in memory.
+- `dataset.name` / `dataset.version` -> registered dataset candidate.
+- `validation_dataset` -> optional validation dataset candidate.
+- `evaluators[]` -> candidate Foundry evaluator names; verify with `evaluator_catalog_get` before treating them as remote evaluators.
+- `name` -> local eval/suite candidate; verify remotely before persisting as `suiteName`.
+- `options.eval_model`, `options.optimization_model`, `options.max_candidates`, `options.optimization_config.model_search_space`, `options.pass_threshold`, `max_samples`, `trace_days`, and `generation_instruction` -> setup defaults.
+
+Treat `eval.yaml` as local evaluation intent, not proof that a Foundry suite exists. Persist synced suite/dataset/evaluator references to `.foundry` only after remote lookup or registration succeeds.
+
+### Step 5: Resolve Common Configuration
+
+Layer sources in this order:
+
+1. Explicit user input and values already selected in the session
+2. azd environment values for deployment context
+3. `.foundry/agent-metadata*.yaml` overlay values and remote suite/cache references
+4. `agent.yaml` and `eval.yaml` local source configuration
+5. User prompts for anything still missing
+
+If azd and metadata both provide the same value and they differ, stop and ask which source is authoritative. If they match, use the azd value and avoid rewriting the duplicate on future metadata writes.
+
+| Effective Value | Preferred Source | Used By |
+|-----------------|------------------|---------|
+| Project endpoint | azd env | deploy, invoke, observe, trace, troubleshoot |
+| Agent name/version | azd agent variables, then `agent.yaml` | invoke, observe, trace, troubleshoot |
+| ACR | azd env | deploy |
+| Evaluation suites and cache paths | `.foundry/agent-metadata*.yaml` | observe, eval-datasets |
+| Local seed dataset/evaluator intent | `eval.yaml` | observe, eval-datasets |
+
+### Step 6: Write Metadata Overlay (Create/Deploy/Observe Only)
+
+On any metadata write (deploy, auto-setup, dataset refresh, or trace-to-dataset update), persist only non-derivable overlay/cache state in the selected metadata file:
+
+- azd binding (`azd.environmentName`, `azd.service`) when useful for future resolution
+- `evaluationSuites[]` with remote suite/dataset/evaluator references and local cache paths
+- `lastEval`, result files, comparison summaries, or explicit non-azd overrides
+
+Do not copy azd-owned deployment values into metadata when azd already provides them. If the selected file is a preferred single-environment file, rewrite only that one environment block. If the selected file is a legacy multi-environment file, rewrite only the selected environment block. Never copy or merge environments across sibling metadata files automatically. If the selected environment still uses older `testSuites[]` or legacy `testCases[]`, rewrite it to `evaluationSuites[]` and remove migrated `priority` fields from the rewritten entries.
+
+### Step 7: Collect Missing Values
+
+Use the `ask_user` or `askQuestions` tool **only for values not resolved** from the user's message, session context, metadata, or azd bootstrap. Common values skills may need:
+- **Agent root** — Target azd service project folder or folder containing `.foundry/agent-metadata*.yaml`
+- **Metadata file** — `agent-metadata.yaml` for local/dev, or an explicit sidecar such as `agent-metadata.prod.yaml`
+- **Environment** — azd environment, `dev`, `prod`, or another environment key from metadata
+- **Project endpoint** — AI Foundry project endpoint URL
+- **Agent name** — Name of the target agent
+
+> 💡 **Tip:** If the user already provides the agent path, environment, project endpoint, or agent name, extract it directly — do not ask again.
+
+## Agent: Agent Types
+
+All agent skills support two agent types:
+
+| Type | Kind | Description |
+|------|------|-------------|
+| **Prompt** | `"prompt"` | LLM-based agents backed by a model deployment |
+| **Hosted** | `"hosted"` | Container-based agents running custom code |
+
+Use `agent_get` MCP tool to determine an agent's type when needed.
+
+## Tool Usage Conventions
+
+- Use the `ask_user` or `askQuestions` tool whenever collecting information from the user
+- Use the `task` or `runSubagent` tool to delegate long-running or independent sub-tasks (e.g., env var scanning, status polling, Dockerfile generation)
+- Prefer Azure MCP tools over direct CLI commands when available
+- Reference official Microsoft documentation URLs instead of embedding CLI command syntax
+
+## Additional Resources
+
+- [Foundry Hosted Agents](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
+- [Foundry Agent Runtime Components](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/runtime-components?view=foundry)
+
+## SDK Quick Reference
+
+- [Python](references/sdk/foundry-sdk-py.md)
+
+## Network Isolation Errors
+
+Applies to **any** call against a Foundry project or its parent Foundry account — Foundry MCP tools, `azd`, `az` CLI, `curl`, REST, or SDK.
+
+If an error matches `Public access is disabled` / `PublicNetworkAccessDisabled` / `403 Forbidden` from a private endpoint / connection timeout / the project endpoint FQDN resolves to a public IP, this typically means the parent Foundry account has `publicNetworkAccess=Disabled` or `Enabled from selected IP addresses`, and the current shell is outside its VNet.
+
+Only if the error is ambiguous, confirm against the Foundry account using a management-plane call (works from anywhere with reader access):
+
+```bash
+az cognitiveservices account show \
+  --name <account> --resource-group <rg> \
+  --query "properties.{publicNetworkAccess:publicNetworkAccess, networkAcls:networkAcls, privateEndpointConnections:privateEndpointConnections[].properties.privateLinkServiceConnectionState.status}"
+```
+
+`publicNetworkAccess: "Disabled"` — or `"Enabled"` together with non-empty `networkAcls.ipRules` / `virtualNetworkRules` — confirms isolation. If `publicNetworkAccess: "Enabled"` and `networkAcls` is empty, the failure is a caller-side network issue (e.g. Private DNS resolving the FQDN to a public IP from inside a VNet with a private endpoint), not an account-config issue.
+
+If it's indeed a network isolation issue, supported connection options are documented in [Choose a secure connection method to Foundry](https://learn.microsoft.com/azure/foundry/how-to/configure-private-link#choose-a-secure-connection-method-to-foundry).
+
+> ℹ️ Foundry MCP tools cannot reach a VNet-isolated project even from inside the VNet.

package/skills/migrate-to-shoehorn/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: migrate-to-shoehorn
+description: Migrate test files from `as` type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace `as` in tests, or needs partial test data.
+---
+
+# Migrate to Shoehorn
+
+## Why shoehorn?
+
+`shoehorn` lets you pass partial data in tests while keeping TypeScript happy. It replaces `as` assertions with type-safe alternatives.
+
+**Test code only.** Never use shoehorn in production code.
+
+Problems with `as` in tests:
+
+- Trained not to use it
+- Must manually specify target type
+- Double-as (`as unknown as Type`) for intentionally wrong data
+
+## Install
+
+```bash
+npm i @total-typescript/shoehorn
+```
+
+## Migration patterns
+
+### Large objects with few needed properties
+
+Before:
+
+```ts
+type Request = {
+  body: { id: string };
+  headers: Record<string, string>;
+  cookies: Record<string, string>;
+  // ...20 more properties
+};
+
+it("gets user by id", () => {
+  // Only care about body.id but must fake entire Request
+  getUser({
+    body: { id: "123" },
+    headers: {},
+    cookies: {},
+    // ...fake all 20 properties
+  });
+});
+```
+
+After:
+
+```ts
+import { fromPartial } from "@total-typescript/shoehorn";
+
+it("gets user by id", () => {
+  getUser(
+    fromPartial({
+      body: { id: "123" },
+    }),
+  );
+});
+```
+
+### `as Type` → `fromPartial()`
+
+Before:
+
+```ts
+getUser({ body: { id: "123" } } as Request);
+```
+
+After:
+
+```ts
+import { fromPartial } from "@total-typescript/shoehorn";
+
+getUser(fromPartial({ body: { id: "123" } }));
+```
+
+### `as unknown as Type` → `fromAny()`
+
+Before:
+
+```ts
+getUser({ body: { id: 123 } } as unknown as Request); // wrong type on purpose
+```
+
+After:
+
+```ts
+import { fromAny } from "@total-typescript/shoehorn";
+
+getUser(fromAny({ body: { id: 123 } }));
+```
+
+## When to use each
+
+| Function        | Use case                                           |
+| --------------- | -------------------------------------------------- |
+| `fromPartial()` | Pass partial data that still type-checks           |
+| `fromAny()`     | Pass intentionally wrong data (keeps autocomplete) |
+| `fromExact()`   | Force full object (swap with fromPartial later)    |
+
+## Workflow
+
+1. **Gather requirements** - ask user:
+   - What test files have `as` assertions causing problems?
+   - Are they dealing with large objects where only some properties matter?
+   - Do they need to pass intentionally wrong data for error testing?
+
+2. **Install and migrate**:
+   - [ ] Install: `npm i @total-typescript/shoehorn`
+   - [ ] Find test files with `as` assertions: `grep -r " as [A-Z]" --include="*.test.ts" --include="*.spec.ts"`
+   - [ ] Replace `as Type` with `fromPartial()`
+   - [ ] Replace `as unknown as Type` with `fromAny()`
+   - [ ] Add imports from `@total-typescript/shoehorn`
+   - [ ] Run type check to verify