@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

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

@@ -0,0 +1,57 @@
+---
+name: loop-budget
+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
+
+## Purpose
+
+Inspect and explain an existing loop's budget without mutating the loop.
+
+## Use When
+
+- 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.
+
+## Do Not Use When
+
+- 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`.
+
+## Workflow
+
+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.
+
+## 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

@@ -0,0 +1,59 @@
+---
+name: loop-intake
+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
+
+## Purpose
+
+Produce a report-only readiness assessment and proposed contract before any loop execution is approved.
+
+## Use When
+
+- 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.
+
+## Do Not Use When
+
+- 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.
+
+## Workflow
+
+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.
+
+## Output
+
+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.3",
+  "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 — skills, guard hooks, and code-review-graph tooling — 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.

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

@@ -0,0 +1,87 @@
+# Install the `aca` CLI
+
+The `aca` CLI is the primary surface for sandboxes. It delegates
+authentication to the Azure CLI — sign in once with `az login` and the
+same Entra identity is used by `aca`.
+
+## Linux / macOS
+
+```bash
+# This same one-liner is also the install path used INSIDE a sandbox or
+# container for agent-driven self-installs — no package manager needed.
+curl -fsSL https://aka.ms/aca-cli-install | sh
+```
+
+Pin a specific version:
+
+```bash
+curl -fsSL https://aka.ms/aca-cli-install \
+  | ACA_VERSION=aca-cli-v0.1.0-early-access sh
+```
+
+## Windows (PowerShell)
+
+```powershell
+# This same one-liner is also the install path used INSIDE a Windows
+# sandbox or container for agent-driven self-installs.
+irm https://aka.ms/aca-cli-install-ps | iex
+```
+
+Pin a specific version:
+
+```powershell
+& ([scriptblock]::Create((irm https://aka.ms/aca-cli-install-ps))) -Version aca-cli-v0.1.0-early-access
+```
+
+## Verify
+
+```bash
+aca --version
+```
+
+Then sign in and run the doctor. Both `az login` and `aca auth login`
+should be **gated on a status check** — calling either one
+unconditionally opens a browser / device-code flow even when a valid
+session is already cached, which is bad UX (and breaks in environments
+with no interactive browser):
+
+```bash
+# bash / zsh
+az account show -o none 2>/dev/null || az login
+aca auth status >/dev/null 2>&1 || aca auth login
+aca doctor
+```
+
+```powershell
+# PowerShell
+az account show -o none 2>$null
+if ($LASTEXITCODE -ne 0) { az login }
+aca auth status *> $null
+if ($LASTEXITCODE -ne 0) { aca auth login }
+aca doctor
+```
+
+> The CLI verb for `aca` sign-in is **`aca auth login`**. The top-level
+> `aca` binary does not have a bare `login` subcommand — always use the
+> `auth` namespace. `aca` delegates the underlying Entra flow to
+> `az login`, so the same identity / MFA apply.
+
+## Uninstall
+
+```bash
+# Linux / macOS
+curl -fsSL https://aka.ms/aca-cli-install | sh -s -- --uninstall
+```
+
+```powershell
+# Windows
+& ([scriptblock]::Create((irm https://aka.ms/aca-cli-install-ps))) -Uninstall
+```
+
+## Supported platforms
+
+| Platform | Architecture |
+|---|---|
+| Linux   | x64    |
+| macOS   | ARM64  |
+| Windows | x64    |