@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

package/extensions/enact-loop/skills/loop-budget/SKILL.md

@@ -1,40 +1,57 @@
 ---
 name: loop-budget
-description: This skill should be used when inspecting enact-loop budget status, execution limits, host token availability, 80 percent warnings, exhausted budgets, or why a loop will not run another command or grader.
+description: This skill should be used to inspect enact-loop execution limits, warnings, exhausted budgets, host token availability, and a loop's permitted next action.
+disable-model-invocation: false
 ---
 
 # Enact Loop Budget
 
-Use this skill to inspect and explain an existing loop's execution budget. It is an operational-read path, not a loop driver.
+## Purpose
 
-## Safety boundary
+Inspect and explain an existing loop's budget without mutating the loop.
 
-- Read state only through `loop_operations_snapshot` or `enact-loop operations --json`.
-- NEVER edit `~/.enact/` files directly.
-- MUST NOT call `loop_start`, `loop_grade`, `loop_grader_dispatch`, `loop_advance`, `loop_retarget`, `loop_complete`, `loop_block`, `loop_abort`, `loop_pause`, or `loop_resume`.
-- Do not invent host-reported token use. If `hostReportedTokens.availability` is `unavailable`, report exactly that a trusted host usage adapter is not configured.
+## Use When
 
-## Read and report
+- A loop warns at 80 percent or refuses another mechanical attempt or judgment dispatch.
+- A loop is blocked by attempt or failure limits.
+- Host token availability or budget counters need an evidence-backed explanation.
 
-1. Call `loop_operations_snapshot` from the loop workspace. If MCP is unavailable, run `enact-loop operations --json` from that workspace.
-2. Report the loop id, phase, goal, ledger entry count, and latest event kind.
-3. For each budget counter, preserve its status exactly:
-   - `unbounded`: no configured cap.
-   - `normal`: below 80% of a configured cap.
-   - `warning`: at least 80% used but not exhausted.
-   - `exhausted`: the cap is reached; the next matching mechanical command or grader dispatch is refused.
-4. Separate engine-observed counters from host-owned data. Mechanical attempts and grader dispatches are durable runtime facts. Host tokens remain unavailable unless a future trusted adapter attests them.
-5. Recommend an explicit, human-approved next action; do not execute it in this skill.
+## Do Not Use When
 
-## Contract fields
+- Starting, running, dispatching judgment, advancing, retargeting, blocking, pausing, resuming, aborting, or completing a loop.
+- Editing runtime files or guessing host-reported token use.
+- Proposing a new contract; use `loop-intake`.
 
-An execution contract may declare:
+## Workflow
 
-```yaml
-executionBudget:
-  maxMechanicalAttempts: 3       # per mechanical stage; 0 is an explicit no-op
-  maxTotalMechanicalAttempts: 8  # total engine-run mechanical commands; 0 is an explicit no-op
-  maxTotalGraderDispatches: 2    # total host grader launches; 0 is an explicit no-op
-```
+1. Read `loop_operations_snapshot` and `loop_status`; if MCP is unavailable, run `enact-loop operations --json`.
+2. Report loop id, phase, goal, latest event, blocked reason, mechanical-failure counts, and each budget counter.
+3. Preserve each counter status: `unbounded`, `normal`, `warning`, or `exhausted`.
+4. Separate durable engine counters from host tokens. If the trusted adapter reports `unavailable`, report that exact state.
+5. Recommend one explicit human-approved next action without executing it.
 
-At 80% the projection warns. At 100% the runtime refuses the next matching action. A zero cap is a deliberate no-op, never an inferred lack of data.
+## Output
+
+Return a read-only budget report with current counters, their status, blockers, and the next permitted action.
+
+## State Contract
+
+Mechanical attempts and StageVerifier or LoopGrader dispatches are runtime facts. Budget exhaustion and failure policy are separate controls; a zero cap is an explicit no-op.
+
+## Boundaries
+
+### In scope
+
+Read-only budget, operation, phase, block-reason, and host-availability inspection.
+
+### Out of scope
+
+Lifecycle mutations, direct ledger access, fabricated token counts, and automatic remediation.
+
+### Fog of war
+
+If MCP or trusted host usage data is unavailable, state the unavailable source and do not substitute an estimate.
+
+## Completion
+
+Prove the report source with `enact-loop operations --json` or `loop_operations_snapshot`, then identify the next permitted action without running it.

package/extensions/enact-loop/skills/loop-intake/SKILL.md

@@ -1,47 +1,59 @@
 ---
 name: loop-intake
-description: This skill should be used when triaging ambiguous work, an issue, CI failure, or PR into a proposed enact-loop contract and readiness report before any execution loop is approved.
+description: Triage an ambiguous requested outcome into a proposed generic Loop contract and readiness report before approval to execute.
+disable-model-invocation: false
 ---
 
 # Enact Loop Intake
 
-Turn incoming work into a report-only readiness assessment and a proposed contract. This skill plans; it does not start, mutate, or drive a loop.
+## Purpose
 
-## Hard boundary
+Produce a report-only readiness assessment and proposed contract before any loop execution is approved.
 
-- MUST NOT call `loop_start`, `loop_grade`, `loop_grader_dispatch`, `loop_advance`, `loop_retarget`, `loop_complete`, `loop_block`, `loop_abort`, `loop_pause`, or `loop_resume`.
-- MUST NOT edit `~/.enact/`, create a state file, change a factory board, modify a worktree, or run a mutating command.
-- MAY call `loop_operations_snapshot`, `loop_status`, `enact-loop operations --json`, and other read-only inspection commands.
-- Every result ends with `approvalRequired: true`. A proposed contract is not approval to execute it.
+## Use When
 
-## Intake procedure
+- A requested outcome needs a bounded Stage contract.
+- Scope, acceptance, dependencies, risk, or ownership need explicit assessment.
+- An existing loop may affect the requested work.
 
-1. Capture the request verbatim: desired outcome, affected workspace, constraints, deadline/risk, and available evidence (issue, CI log, PR, or reproduction).
-2. Inspect only the named workspace and any existing loop through `loop_operations_snapshot` or `loop_status`. If an active loop exists, report its id/phase and do not replace or retarget it.
-3. Identify unknowns that could change scope, acceptance, risk, or ownership. Ask concise questions instead of assuming those facts.
-4. Produce a proposed contract only when the goal and acceptance evidence are sufficient. Keep mechanical stages executable and evidence-based; use judgment stages only where an independent assessment is genuinely required.
-5. State dependencies, blockers, expected evidence, and the suggested budget. Set every budget cap deliberately; use `0` only for an explicit no-op.
+## Do Not Use When
 
-## Required report shape
+- Execution has already been approved; use `enact-loop`.
+- Only a running loop's budget needs inspection; use `loop-budget`.
+- A mutating command or state-file change is required.
 
-```yaml
-intake:
-  outcome: ready | needs-clarification | blocked | active-loop-present
-  scope: <one sentence>
-  evidence: [<facts inspected>]
-  openQuestions: [<questions>]
-  risks: [<risks>]
-  proposedContract: <contract object or null>
-  approvalRequired: true
-  proposedNextAction: <human approval or clarification only>
-```
+## Workflow
 
-When `outcome` is not `ready`, set `proposedContract: null`. When it is ready, return the contract in the report only; do not write it to disk or invoke any loop lifecycle tool.
+1. Capture the requested outcome, workspace, constraints, deadline or risk, and supplied evidence.
+2. Inspect only the named workspace and existing loop state with read-only loop operations.
+3. Report an active loop without replacing or retargeting it.
+4. Identify unknowns that could change scope, acceptance, risk, or ownership.
+5. When evidence is sufficient, return a proposed contract with executable mechanical Stages, distinct StageVerifier or LoopGrader Stages when needed, deliberate budgets, blockers, and expected evidence.
 
-## Contract checklist
+## Output
 
-- Unique stage ids and an acyclic `requires` graph.
-- Required mechanical stages have a resolvable command and a concrete pass criterion.
-- Judgment stages name a model distinct from the executor and specify the needed number of rounds.
-- `executionBudget` includes only deliberate limits: per-stage mechanical attempts, total mechanical attempts, and total grader dispatches.
-- Host token data is not part of the proposal unless a trusted host adapter is explicitly available; otherwise mark it unavailable.
+Return `outcome`, `scope`, `evidence`, `openQuestions`, `risks`, `proposedContract`, `approvalRequired: true`, and `proposedNextAction`.
+
+## State Contract
+
+When a caller supplies an opaque prompt envelope, `loop-intake` preserves its exact `text`, `sha256`, optional `templateId`, and `version`. It does not resolve caller-owned templates, skill ids, domain policy, hierarchy, routing, or external state; it remains report-only and returns unresolved facts.
+
+This skill is read-only. A proposed contract is not approval. MUST NOT call `loop_start`, write state, or pass work to a lifecycle tool.
+
+## Boundaries
+
+### In scope
+
+Evidence-based intake, readiness assessment, proposed contracts, and clarification requests.
+
+### Out of scope
+
+`loop_start`, Stage execution, judgment dispatch, lifecycle mutation, caller-artifact edits, and external-system changes.
+
+### Fog of war
+
+If the requested outcome or acceptance evidence is insufficient, return `needs-clarification` with `proposedContract: null`.
+
+## Completion
+
+Prove the existing-loop check with `loop_operations_snapshot` or `loop_status`; the final report must retain `approvalRequired: true`.

package/extensions/enact-repo/.agents/plugin.json

@@ -0,0 +1,55 @@
+{
+  "name": "enact-repo",
+  "version": "0.1.4",
+  "description": "Baseline agent setup for any repository: the full Enact skill catalog plus guard, briefing, and code-review-graph hooks and MCP tooling, installed at repo scope.",
+  "author": {
+    "name": "amsterdamdatalabs"
+  },
+  "homepage": "https://amsterdamdatalabs.com",
+  "repository": "https://dev.azure.com/amsterdamdatalabs/Enact/_git/enact-extensions",
+  "license": "UNLICENSED",
+  "keywords": [
+    "enact",
+    "repo",
+    "baseline",
+    "skills",
+    "hooks",
+    "code-review-graph"
+  ],
+  "targets": [
+    "claude",
+    "codex",
+    "cursor",
+    "enact",
+    "kimi",
+    "opencode"
+  ],
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json",
+  "assets": [
+    "./lean-ctx"
+  ],
+  "interface": {
+    "displayName": "Enact Repo",
+    "shortDescription": "Drop Enact's baseline agent setup \u2014 skills, guard hooks, and code-review-graph tooling \u2014 into any repository.",
+    "longDescription": "Gives a repository Enact's default agent setup in one install: the full first-party skill catalog, a destructive-Bash guard, skill-matching on prompt submit, a session-start briefing, and code-review-graph MCP tools with after-edit and session-stop hooks. Intended for project (repo-local) install rather than global/user install; every hook command invokes the global `enact-hook` binary (built separately in enact-vps), not a bundled script.",
+    "developerName": "Amsterdam Data Labs",
+    "category": "Developer Tools",
+    "capabilities": [
+      "first-party skill catalog",
+      "destructive-command guard",
+      "prompt-submit skill matching",
+      "session-start briefing",
+      "code-review-graph MCP tools"
+    ]
+  },
+  "factory": {
+    "firstParty": true,
+    "bundledMcpProviders": [
+      "code-review-graph",
+      "lean-ctx"
+    ],
+    "operatorScope": "project"
+  }
+}

package/extensions/enact-repo/.mcp.json

@@ -0,0 +1,20 @@
+{
+  "mcpServers": {
+    "azure-devops": {
+      "command": "azure-devops-mcp",
+      "args": []
+    },
+    "code-review-graph": {
+      "command": "crg",
+      "args": [
+        "serve",
+        "--tools",
+        "get_minimal_context_tool,query_graph_tool,detect_changes_tool,semantic_search_nodes_tool,list_graph_stats_tool"
+      ]
+    },
+    "lean-ctx": {
+      "command": "enact-hook",
+      "args": ["lean-ctx", "mcp"]
+    }
+  }
+}

package/extensions/enact-repo/README.md

@@ -0,0 +1,90 @@
+# enact-repo plugin
+
+Gives any repository Enact's baseline agent setup in one install.
+
+## Purpose
+
+`enact-repo` is a fresh, first-party bundle intended for **project (repo-local) install**,
+not global/user install — see `factory.operatorScope: "project"` in
+`.agents/plugin.json`. It is not deduplicated against other bundles (e.g. `engineering`,
+`enact-factory`); overlap with those is expected and accepted.
+
+## What it bundles
+
+- `skills/` — the full first-party Enact skill catalog (38 skills, copied verbatim from
+  `enact-m5`'s `.agents/skill-catalog/`), covering debugging, refactors, TDD, code review,
+  research, orchestration, and more.
+- `.mcp.json` — `code-review-graph` (`crg serve`), `lean-ctx` (stdio passthrough to
+  `lean-ctx mcp`, run via `enact-hook lean-ctx mcp` so repo-local `LEAN_CTX_*` dirs are
+  resolved at runtime from `cwd`), and `azure-devops` (`azure-devops-mcp`) MCP servers.
+  `azure-devops-mcp` is a global binary, not repo-local tooling: it is built and installed
+  fleet-wide from `enact-vps`'s `azure-devops-mcp/` subproject via the `global-tools`
+  bun-compile manager, and requires an Agent Vault broker (`AGENT_VAULT_ADDR`/
+  `AGENT_VAULT_TOKEN`) configured on the host.
+- `hooks/hooks.json` — canonical nested hook config, `PreToolUse` in order: (1) `Bash`
+  destructive-command guard, (2) `Bash` `crg pre-commit` (the runtime itself detects
+  `git commit` in the shell command and no-ops otherwise), (3) `lean-ctx pre-tool-use`
+  (no matcher — runs for every tool; the runtime picks the right `lean-ctx` hook
+  subcommand from host + payload tool name, no-op where not applicable). Also:
+  `UserPromptSubmit` skill matching, `SessionStart` briefing, `PostToolUse` (file-write
+  tools) crg after-file-edit plus `lean-ctx post-tool-use` (no matcher, same runtime
+  dispatch as above), and `SessionEnd` crg session-stop.
+- `lean-ctx/config.toml`, `lean-ctx/layout.toml` — the baseline `lean-ctx` config shipped
+  with the bundle and installed to `.agents/lean-ctx/config/lean-ctx/` in every repo-local
+  install (see "Repo-local install" below). Machine-specific values (absolute paths,
+  usernames, hostnames, tokens, and any per-machine runtime state such as
+  `[gain] last_auto_publish`) are stripped from the committed baseline;
+  `shell_allowlist_extra` is kept intact.
+
+## Hook runtime
+
+Every hook command in `hooks/hooks.json` invokes the global `enact-hook` binary — a single
+fleet-wide executable built and installed separately from `enact-vps` (the same `global-tools`
+bun-compile model as `azure-devops-mcp`), not a repo-local script. There is no `runtime/`
+directory in this bundle: `enact-hook` is expected to already be on `PATH` on any host this
+plugin is installed to.
+
+CLI contract: `enact-hook <kind> [subcommand] --host=<claude|codex|cursor|kimi|opencode>`, with
+the hook payload as JSON on stdin. Kinds:
+- `pre-tool-use`, `user-prompt-submit`, `briefing`
+- `crg <after-file-edit|pre-commit|session-stop>` — `pre-commit` runs on `PreToolUse` with the
+  same `Bash` matcher as the destructive-command guard; the runtime detects `git commit` in the
+  shell command itself and no-ops otherwise, so the canonical hook needs no extra matching logic.
+- `lean-ctx mcp` — stdio passthrough to `lean-ctx mcp`, used directly as the `.mcp.json`
+  `lean-ctx` server command (not a hook).
+- `lean-ctx pre-tool-use` / `lean-ctx post-tool-use` — registered with **no matcher**, so they
+  run on every tool call; the runtime itself picks the right `lean-ctx` hook subcommand from
+  `--host` plus the payload's tool name, and no-ops where lean-ctx has nothing to do for that
+  tool. Every host projection here (Claude/Codex's nested schema, Cursor's flattening, the Kimi
+  hook array, and the generated OpenCode plugin) treats an absent matcher as "match all tools",
+  per that host's own documented matcher semantics — see `tests/host-flag-projection.test.mjs`.
+
+The canonical `hooks/hooks.json` in this bundle omits `--host`; each per-platform projection
+(Claude plugin bundle, Codex plugin bundle, Cursor's flattened hooks.json, the Kimi hooks array,
+and the generated OpenCode plugin) appends `--host=<that platform>` at projection time, via the
+shared `withHostFlag` helper (`src/internal/hooks.ts`) so `enact-hook` can render each host's
+expected output format. `withHostFlag` only ever touches hook commands — MCP server commands in
+`.mcp.json` (including `lean-ctx`'s `enact-hook lean-ctx mcp`) are projected unchanged on every
+host, with no `--host` appended.
+
+## Repo-local install
+
+Install into a repository with `enact-extensions install enact-repo --repo <repo-root>` (see the
+top-level README, "Repo-local install"). Every host gets committed, relative files; skills are shared
+from `.agents/skills/` (Claude uses its plugin copy). Kimi hooks are global-only: they are installed
+by enact-vps, not by this bundle. The installer also marks the repo as managed through root
+`enact-config.toml` (the file `enact-hook` checks): it creates the file with `version = 1` when
+missing, or appends a `[skills]` block (`version = 1`) as text, touching no other byte and never
+writing `[hooks]`; installs the baseline `lean-ctx/config.toml` and
+`lean-ctx/layout.toml` as managed whole files at `.agents/lean-ctx/config/lean-ctx/` (tracked by
+the lock like any other managed file — drift detection, `--force` takeover with originals
+restore on uninstall, all reused from the existing managed-file machinery); and ignores
+`lean-ctx`'s runtime-generated dirs via `.agents/.gitignore` (`/lean-ctx/data/`,
+`/lean-ctx/cache/`, `/lean-ctx/state/`, `/lean-ctx/bin/` — the `config/` dir itself stays
+committed).
+
+## Canonical install path
+
+The canonical install entrypoint is `extensions/enact-repo/.agents/plugin.json`. Host surfaces
+(`.claude-plugin/`, `.codex-plugin/`, `.cursor-plugin/`) are generated by `enact-extensions
+sync`/`install` and are not committed.

package/extensions/enact-repo/hooks/hooks.json

@@ -0,0 +1,98 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-hook pre-tool-use",
+            "statusMessage": "enact-repo: destructive-command guard",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-hook crg pre-commit",
+            "statusMessage": "enact-repo: crg pre-commit",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-hook lean-ctx pre-tool-use",
+            "statusMessage": "enact-repo: lean-ctx pre-tool-use",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-hook user-prompt-submit",
+            "statusMessage": "enact-repo: matching skills",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-hook briefing",
+            "statusMessage": "enact-repo: session briefing",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|StrReplace|str_replace_editor|edit_file|str_replace|replace_in_file|create_file|write_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-hook crg after-file-edit",
+            "statusMessage": "enact-repo: crg after-file-edit",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-hook lean-ctx post-tool-use",
+            "statusMessage": "enact-repo: lean-ctx post-tool-use",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-hook crg session-stop",
+            "statusMessage": "enact-repo: crg session-stop",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/extensions/enact-repo/lean-ctx/config.toml

@@ -0,0 +1,35 @@
+minimal_overhead = true
+structure_first = true
+journal_enabled = true
+auto_capture = true
+shell_allowlist_extra = [
+    "pi",
+    "install",
+    "script",
+    "expect",
+    "bash",
+    "claude",
+    "codex",
+    "just",
+    "crg",
+    "search",
+    "atlas",
+    "rustfmt",
+    "cursor-agent",
+    "kimi",
+    "opencode",
+    "pi-acp",
+    "enact",
+    "enact-repo-controls",
+    "orca",
+    "agent",
+    "az",
+    "trash",
+    "launchctl",
+    "ssh",
+    "base64",
+    "wasmtime",
+    "orca-ide",
+    "time",
+    "ast-grep"
+]

package/extensions/enact-repo/lean-ctx/layout.toml

@@ -0,0 +1,5 @@
+# lean-ctx layout pin (GL #623) — managed by lean-ctx, do not edit.
+# Marks this install as committed to the XDG four-dir layout so a stray
+# ~/.lean-ctx never re-collapses config/data/state/cache. Remove via
+# `lean-ctx doctor` only if you intentionally revert to a single-dir layout.
+mode = "xdg"

package/extensions/enact-repo/skills/aca-sandboxes/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: aca-sandboxes
+description: "Use when the user wants to create, manage, or operate Azure Container Apps sandboxes — hardware-isolated microVMs driven by the `aca` CLI. USE FOR: create sandbox group, create sandbox, aca doctor, aca auth login, install aca, exec in sandbox, sandbox shell, fs read/write, expose port, mount volume, snapshot/suspend/resume sandbox, commit to disk, egress rules, secrets, identity, list disk images, Python SDK install, Azure portal sandbox surface, compare to Dynamic Sessions or Container Apps, scenarios like coding agents, code interpreter, agent swarms, computer-use, web apps, MCP hosting. DO NOT USE FOR: regular Azure Container Apps (`Microsoft.App/containerApps`), AKS, or VM workloads."
+disable-model-invocation: false
+---
+
+# Sandboxes
+
+Hardware-isolated microVMs on Azure Container Apps. Snapshot/resume,
+scale-to-zero, sub-second startup, deny-default egress. This skill
+drives sandboxes through the **`aca` CLI** — one command surface, no
+ambiguity. Self-contained — everything is under `references/` in this
+folder.
+
+## Use When
+
+- Creating, managing, or operating Azure Container Apps sandboxes (hardware-isolated microVMs) via the `aca` CLI or its Python SDK.
+- Tasks like: create a sandbox group/sandbox, `aca doctor`, `aca auth login`, install `aca`, exec/shell in a sandbox, read/write files, expose a port, mount a volume, snapshot/suspend/resume, commit to disk, egress rules, secrets, managed identity, list disk images.
+- Scenarios: coding agents in a sandbox, code interpreter, agent swarms, computer-use, web apps, MCP hosting, developer workflows.
+
+## Do Not Use When
+
+- Regular Azure Container Apps (`Microsoft.App/containerApps`), AKS, or VM workloads.
+- `azd` project scaffolding, ACR/Docker image builds, other Azure data services, Kubernetes/`kubectl`, or Functions/App Service deployment — see [references/response-cues.md](references/response-cues.md) for the full out-of-scope redirect table and the required one-paragraph redirect pattern.
+
+## What it is
+
+- **Resource type:** `Microsoft.App/SandboxGroups` (preview).
+- **Isolation:** each sandbox is its own microVM, safe for untrusted code.
+- **Startup:** sub-second from a prewarmed pool; suspend/resume preserves
+  full memory + disk.
+- **Scale:** zero to thousands; pay nothing when idle.
+- **Auth:** `aca` delegates to `az login` — same identity, same MFA.
+
+## Get started
+
+| | Where |
+|---|---|
+| **Install** | [references/install.md](references/install.md) |
+| **Prerequisites** | [references/prerequisites.md](references/prerequisites.md) |
+| **Quick start (+ common mistakes)** | [references/quickstart.md](references/quickstart.md) |
+| **Full CLI reference** | [references/reference.md](references/reference.md), [references/reference-advanced.md](references/reference-advanced.md) (YAML spec, selectors, output formats, verbose/debug, Python SDK) |
+| **Capabilities & scenarios** | [references/capabilities.md](references/capabilities.md), [references/scenarios.md](references/scenarios.md) |
+| **Response cues, out-of-scope table, try-asking examples** | [references/response-cues.md](references/response-cues.md) |
+
+After install, always confirm setup with `aca doctor` — it resolves
+subscription / RG / group / region / role and tells you which check
+is red.
+
+Before composing any response, check
+[references/response-cues.md](references/response-cues.md) for the
+required cues for that response type — non-negotiable acceptance
+criteria, not suggestions.

package/extensions/enact-repo/skills/aca-sandboxes/references/capabilities.md

@@ -0,0 +1,52 @@
+# Capabilities and scenarios
+
+## Capabilities
+
+Everything the platform exposes. Each row is the starting point — open
+[reference.md](reference.md) for full flags and options.
+
+> Command rows below show only the **shape**. In real invocations:
+> - every `aca sandbox <verb>` takes `--id <sandbox-id>`;
+> - every `aca sandboxgroup <noun> <verb>` mutation takes `--name <group>`
+>   (or relies on the default group set via `--set-config`);
+> - omit these from copies into the shell and you'll get a CLI parse error.
+
+| #  | Capability                | What it does                                                                 | `aca` CLI |
+|----|---------------------------|------------------------------------------------------------------------------|-----------|
+| 00 | **Sandbox groups**        | Provision, list/get, assign Data Owner role, tear down.                      | `aca sandboxgroup create / list / get / role create / delete` |
+| 01 | **Sandboxes**             | Create, list, get, delete; cpu/memory/labels/env; parallel.                  | `aca sandbox create / list / get / delete` (+ `--cpu --memory --label --env`) |
+| 02 | **Snapshots**             | Freeze a running sandbox; boot new ones from that point.                     | `aca sandbox snapshot --id <id> --name X` · `aca sandbox create --snapshot X` |
+| 03 | **Disks**                 | Public disks, build from container image, commit a running sandbox.          | `aca sandboxgroup disk list-public / create --image` · `aca sandbox commit --id <id> --name X` · `aca sandbox create --disk <public-name>` (or `--disk-id <id>` for private/committed disks) |
+| 04 | **Volumes**               | `AzureBlob` (shared) or `DataDisk` (block); mount at create or post-create.  | `aca sandboxgroup volume create --type AzureBlob` · `aca sandbox mount --volume X --path /mnt/x` |
+| 05 | **Lifecycle**             | Stop/resume; auto-suspend after idle; auto-delete after TTL.                 | `aca sandbox stop / resume` · `aca sandbox lifecycle set --auto-suspend 60` |
+| 06 | **Ports**                 | Expose an HTTP port; anonymous or Entra-gated (`--auth entra --allow-principal`); revoke.   | `aca sandbox port add --port 8080 [--anonymous \| --auth entra --allow-principal <object-id>]` · `port list / remove` |
+| 07 | **Files**                 | write / read / list / stat / mkdir / delete inside the sandbox.              | `aca sandbox fs write --file ./local` · `fs cat / ls` · `fs cp <src> <dst>` (positional, `sbx-id:/path` syntax) |
+| 08 | **Egress**                | Deny-default outbound + host allow-list; audit decisions; YAML transforms.   | `aca sandbox egress set --default Deny --rule "*.host.com:Allow"` · `egress show / decisions / apply` |
+| 09 | **Secrets**               | Group-scoped key/value, fetched at runtime from inside the sandbox.          | `aca sandboxgroup secret set --name X --key K --value V` · `secret list / show / remove / delete` |
+| 10 | **Managed identity**      | System- or User-assigned MI on the group; grant RBAC for cross-group orchestration. | `aca sandboxgroup identity assign --system-assigned` (or `--user-assigned <res-id>`) · `identity show / remove` |
+| 11 | **Labels & selectors**    | `--label k=v` at create time (repeatable); AND-filter on list. Fleet management pattern. | `aca sandbox create --label role=worker --label tenant=t42` · `aca sandbox list -l role=worker` |
+| 12 | **Interactive shell**     | Real PTY into a running sandbox.                                             | `aca sandbox shell --id <id>` |
+| 13 | **YAML spec / `apply`**   | Declarative infra-as-code: `init`, `validate`, `apply`, `schema`.            | `aca sandbox init > sandbox.yaml` · `validate` · `apply --file sandbox.yaml` |
+| 14 | **`aca doctor`**          | Diagnose subscription / RG / group / region / role.                          | `aca doctor` |
+
+## Scenarios
+
+Composed patterns that combine the capabilities above. Full sketches
+in [scenarios.md](scenarios.md).
+
+- **Web apps** — start a server, expose a port anonymously, hit the URL.
+- **Coding agents in a sandbox** — run Copilot CLI / Claude Code / Codex
+  with deny-default egress and (optionally) token-swap rules.
+- **Code interpreter** — LLM generates → exec → observe → iterate;
+  snapshot between turns for rewind.
+- **Swarms** — orchestrator fans work across N worker sandboxes by
+  label selector.
+- **Sandbox inception** — orchestrator runs *inside* a sandbox and uses
+  its managed identity to drive a separate worker group. No credentials
+  in agent code.
+- **Computer-use** — LLM drives a real browser; watch live via noVNC.
+- **MCP hosting** — host an MCP server in a sandbox; expose via port or
+  Dev Tunnel.
+- **Data processing** — producer/consumer pipelines on shared
+  `AzureBlob` volumes.
+- **Developer workflows** — PR builds, ephemeral CI, on-demand dev envs.