@codyswann/lisa 2.225.5 → 2.226.1

package/README.md

@@ -84,6 +84,13 @@ Skill bodies are not copied into the project and unrelated Lisa stacks are not
 loaded. Project settings use `[features].hooks`; the deprecated `codex_hooks`
 key is removed during reconciliation.
 
+Remote coding environments use one vendor-neutral AWS bootstrap rather than
+repository-specific or agent-specific IAM users. Run `/lisa:setup-remote-aws`
+to install the common setup script and native Cursor/Copilot adapters; Claude,
+Codex, Cursor, Copilot, and user-managed Antigravity/OpenCode hosts all consume
+the same `LISA_AWS_BOOTSTRAP_JSON` bundle. See
+[Remote coding-agent AWS access](docs/remote-agent-aws.md).
+
 The supported stacks, setup flags, and exact invocation evolve as the project grows, so ask for the current set rather than copying a list that may have moved on:
 
 > **Prompt for your coding agent**

package/all/create-only/scripts/remote-agent-aws-setup.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# Installed by Lisa. The authoritative implementation is shipped by the
+# lisa-setup-remote-aws skill and the @codyswann/lisa package.
+
+set -euo pipefail
+
+LOCAL_LISA_SCRIPT="$(npm root 2>/dev/null)/@codyswann/lisa/plugins/lisa/scripts/remote-agent-aws-setup.sh"
+[ -x "$LOCAL_LISA_SCRIPT" ] && exec "$LOCAL_LISA_SCRIPT" "$@"
+
+echo "remote-agent-aws-setup: install @codyswann/lisa before running this setup script" >&2
+exit 1

package/package.json

@@ -102,7 +102,7 @@
     "form-data": ">=4.0.6"
   },
   "name": "@codyswann/lisa",
-  "version": "2.225.5",
+  "version": "2.226.1",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

package/plugins/lisa/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.225.5",
+  "version": "2.226.1",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.225.5",
+  "version": "2.226.1",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/.codex-plugin/skills/lisa-analyze-claude-remote/SKILL.md

@@ -150,24 +150,27 @@ Group the findings as:
      Terraform providers).
    - `aws sso login`, `aws:signin:*`, `sso_start_url`, `sso_account_id`, `sso_role_name`, or
      `sso_session` in docs or config.
-   - `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_DEFAULT_REGION`,
-     `AWS_PROFILE`, role ARN, external ID, account, or CloudWatch/STS references.
+   - `LISA_AWS_BOOTSTRAP_JSON`, legacy `AWS_ACCESS_KEY_ID` /
+     `AWS_SECRET_ACCESS_KEY`, `AWS_PROFILE`, role ARN, external ID, account, or
+     CloudWatch/STS references.
 
    If AWS is present, emit an AWS credential finding and inventory entry. If the repo's current
    local path is `aws sso login` or an `aws:signin:*` script, classify that local path as a `GAP`
    for headless remote routines: it is an interactive browser/device-authorization flow and cannot
    complete in the cloud. Route to the AWS row in the Credential reference instead of suggesting
-   SSO auth. The finding must name the headless substrate: a dedicated IAM principal (user or role)
-   with only permission to `sts:AssumeRole`, environment credentials in the routine UI, and
-   `~/.aws/config` profiles using `role_arn`, `credential_source = Environment`, optional
-   `external_id`, and `region`.
+   SSO auth. The finding must name Lisa's headless substrate: one dedicated IAM
+   user with only `sts:AssumeRole`; one complete Secrets Manager SecretString
+   set as `LISA_AWS_BOOTSTRAP_JSON`; and `/lisa:setup-remote-aws`, which writes a
+   named source profile plus automatically refreshed role profiles. Explicitly
+   reject standard `AWS_ACCESS_KEY_ID` variables because they can bypass the
+   intended assume-role profile.
 
    When the repository contains concrete non-secret AWS metadata (role ARNs, account aliases,
    profile names, regions, or ExternalId values), include it in an `awsProfiles` inventory array so
    `/lisa:generate-claude-remote-build-script` can write matching `~/.aws/config` profiles. Never
-   invent account IDs, ExternalIds, role names, or regions. If AWS is detected but profile metadata
-   is absent, emit the required AWS secret names plus an action to add project-specific profile
-   metadata to the generated artifact or environment notes.
+   invent account IDs, ExternalIds, role names, or regions. If AWS is detected
+   but profile metadata is absent, require a cdkstarter bootstrap bundle rather
+   than asking the repository to reconstruct account metadata by hand.
 
 5. **MCP servers** — read every committed `.mcp.json`. For each server report transport and auth.
    Project-scoped HTTP/SSE servers with no interactive auth are `OK`. Flag stdio servers as
@@ -276,14 +279,14 @@ unsuffixed `…_TOKEN`/`…_KEY` is the simplest to set in a single-account rout
 - Access: the personal API key inherits the user's workspace permissions — the user must be able to read/create/update Issues in the destination team.
 
 ### AWS — host-project operations, logs, deploys, CDK/Serverless/SST, or AWS SDK usage
-- Headless substrate: a dedicated IAM principal (user or role) with long-lived bootstrap credentials
-  stored in the routine environment, used only to call `sts:AssumeRole` into per-account operational
-  roles. The routine writes `~/.aws/config` profiles with `role_arn`, `credential_source =
-  Environment`, optional `external_id`, and `region`; agents use `aws --profile <profile> ...`.
-- Env: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`; optional `AWS_SESSION_TOKEN` for temporary
-  bootstrap credentials; `AWS_DEFAULT_REGION` when no profile region is provided. Role ARNs,
-  ExternalIds, profile names, and regions are non-secret project metadata and belong in generated
-  artifacts or project docs, not in the skill's global guidance.
+- Headless substrate: cdkstarter's vendor-neutral remote-agent kit. Its single
+  Secrets Manager SecretString contains the assume-only access key, ExternalId,
+  and per-account role metadata. `/lisa:setup-remote-aws` writes a private named
+  source profile and renewable role profiles; agents use
+  `aws --profile <profile> ...`.
+- Env: `LISA_AWS_BOOTSTRAP_JSON` (secret, required) and
+  `LISA_REMOTE_AGENT` (plain platform label). Do not set `AWS_ACCESS_KEY_ID` or
+  `AWS_SECRET_ACCESS_KEY` in the remote environment.
 - Allowlist: `*.amazonaws.com`, or narrower service hosts such as `sts.amazonaws.com`,
   `logs.<region>.amazonaws.com`, `cloudwatch.<region>.amazonaws.com`,
   `xray.<region>.amazonaws.com`, `ssm.<region>.amazonaws.com`, and service-specific endpoints the
@@ -366,7 +369,7 @@ so the generator can render acquisition comments into its template:
     {
       "name": "dev",
       "roleArn": "arn:aws:iam::<account-id>:role/<role-name>",
-      "credentialSource": "Environment",
+      "credentialSource": "lisa-remote-agent-bootstrap",
       "externalId": "<project-external-id>",
       "region": "us-east-1"
     }

package/plugins/lisa/.codex-plugin/skills/lisa-generate-claude-remote-build-script/SKILL.md

@@ -71,9 +71,9 @@ tracker/source, plus the host project's own package manager and tooling — not
    include `JAM_PAT`, `SONAR_TOKEN`, or similar documented substrate env vars
    only as optional secrets, with their acquire/scope comments when the analysis
    supplied them. Never invent values or promote dormant substrates to required.
-   When AWS entries are present, list `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, optional
-   `AWS_SESSION_TOKEN`, and `AWS_DEFAULT_REGION` exactly as the analysis reported. State that these
-   bootstrap credentials are for STS assume-role only; do not emit or recommend `aws sso login`.
+   When AWS entries are present, list only `LISA_AWS_BOOTSTRAP_JSON` as the
+   required secret and `LISA_REMOTE_AGENT=claude` as plain configuration. Never
+   emit standard `AWS_ACCESS_KEY_ID` variables and never recommend `aws sso login`.
 
 3a. **Emit substrate setup snippets.** When the inventory marks an MCP
    `headlessUsable: true` through a documented substrate, render the matching
@@ -91,18 +91,11 @@ tracker/source, plus the host project's own package manager and tooling — not
      transport supports static-token auth. Do not print a Jam `.mcp.json` header snippet because
      Jam's preferred headless substrate is its PAT-authenticated CLI.
 
-3b. **Emit AWS assume-role profile setup.** When the inventory includes `awsProfiles`, write an
-   idempotent `~/.aws/config` block gated on `[ -n "${AWS_ACCESS_KEY_ID:-}" ]`. The generated block
-   must:
-   - `mkdir -p "$HOME/.aws"` and create or append profile stanzas without writing secrets.
-   - Emit one `[profile <name>]` stanza per inventory profile with `role_arn`,
-     `credential_source = Environment`, `region` when present, and `external_id` when present.
-   - Keep regions and ExternalIds as non-secret project metadata from the inventory; never invent
-     account IDs, role names, profile names, regions, or ExternalIds.
-   - Warn and skip profile writing when AWS profile metadata is absent, while still listing the
-     required `AWS_*` env var names in the secret template.
-   - Include a comment that agents should use `aws --profile <name> ...` and must not run
-     `aws sso login` in headless routines.
+3b. **Install the shared AWS bootstrap.** When AWS is present, invoke
+   `/lisa:setup-remote-aws --platform=claude`. Reuse the resulting
+   `scripts/remote-agent-aws-setup.sh`; do not generate a second credential or
+   profile implementation. Add `bash scripts/remote-agent-aws-setup.sh` to the
+   generated cloud setup after required package installation.
 
 4. **Emit the allowlist + gaps notice.** List any custom domains the setup or runtime reaches
    (from `networkAccess.allowlistDomains`, falling back to legacy `allowlistDomains`) that the user
@@ -139,9 +132,9 @@ shape, not a fixed payload):
 #   # Note: GH_TOKEN is for gh CLI only. Raw git uses Claude's connected-GitHub proxy/identity;
 #   # sibling repos reached only by raw git do not need to be in this token scope.
 #   - GH_TOKEN=<token>                          # REQUIRED, github is the active tracker+source
-#   - AWS_ACCESS_KEY_ID=<access-key-id>          # REQUIRED when AWS inventory is active
-#   - AWS_SECRET_ACCESS_KEY=<secret-access-key>  # REQUIRED when AWS inventory is active
-#   - AWS_SESSION_TOKEN=<session-token>          # OPTIONAL for temporary bootstrap creds
+#   - LISA_AWS_BOOTSTRAP_JSON=<complete SecretString> # REQUIRED for AWS
+# PLAIN:
+#   - LISA_REMOTE_AGENT=claude
 # NETWORK: set the environment to Custom and allowlist these non-default domains if not on Full:
 #   - <networkAccess.allowlistDomains, if any>
 set -uo pipefail
@@ -184,13 +177,8 @@ need gh || (sudo apt-get update -y && sudo apt-get install -y gh)
 need jq || sudo apt-get install -y jq
 require gh; require jq
 
-# --- AWS assume-role profiles, when inventory includes awsProfiles ---
-if [ -n "${AWS_ACCESS_KEY_ID:-}" ]; then
-  mkdir -p "$HOME/.aws"
-  # Generated stanzas use credential_source=Environment and contain no secrets.
-  # Agents should run: aws --profile <profile> ...
-  # Do not run aws sso login in headless routines; SSO requires an interactive browser/device flow.
-fi
+# --- AWS assume-role profiles, when AWS inventory is active ---
+bash scripts/remote-agent-aws-setup.sh
 
 # --- optional, only with --include-optional ---
 # (docker / ruby / chromium / etc., guarded)
@@ -213,8 +201,8 @@ to stop are: the analysis could not run, or the `--out` path is not writable.
   raw git/cross-repo clone guidance must not expand the token scope to sibling repositories.
 - Never emit an install for a tool the analysis did not surface, and never install `OPTIONAL` tools
   unless `--include-optional` is set.
-- When AWS is in the inventory, generate environment-backed assume-role profile stanzas from
-  `awsProfiles`; never emit `aws sso login` as a remote setup step.
+- When AWS is in the inventory, reuse `/lisa:setup-remote-aws` and its shared
+  setup script; never emit a second profile implementation or `aws sso login`.
 - Prefer `networkAccess.allowlistDomains` over legacy top-level `allowlistDomains`; never emit
   domains already covered by the routine environment's default Trusted list.
 - Keep the script idempotent and detect-before-install so it is safe to re-run and cache.

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-aws/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: lisa-setup-remote-aws
+description: "Install and validate Lisa's…"
+allowed-tools: ["Bash", "Read", "Write", "Glob", "Grep"]
+---
+
+# Set up remote-agent AWS access: $ARGUMENTS
+
+Install the vendor-neutral AWS bootstrap into the current repository.
+
+## Arguments
+
+- `--platform=all|claude|codex|cursor|copilot|agy|opencode` (default `all`)
+- `--project=<path>` (default current working directory)
+- `--secret-name=<name>` (default `remote-agent-credentials`)
+
+## Procedure
+
+1. Resolve the plugin root from `PLUGIN_ROOT`, `CLAUDE_PLUGIN_ROOT`,
+   `CURSOR_PLUGIN_ROOT`, or the installed `@codyswann/lisa/plugins/lisa` package.
+2. Run:
+
+   ```bash
+   node "$PLUGIN_ROOT/scripts/install-remote-agent-aws.mjs" $ARGUMENTS
+   ```
+
+3. Inspect every path returned by the installer. It must install
+   `scripts/remote-agent-aws-setup.sh`; for Cursor it merges
+   `.cursor/environment.json`; for Copilot it creates or merges
+   `.github/workflows/copilot-setup-steps.yml`; and it always writes
+   `docs/remote-agent-aws.md`.
+4. Run `bash -n scripts/remote-agent-aws-setup.sh`.
+5. Never write or request the actual bootstrap SecretString in repository
+   files. Tell the operator to retrieve the `remote-agent-credentials` secret
+   from the shared AWS account and paste its complete SecretString into the
+   platform secret named `LISA_AWS_BOOTSTRAP_JSON`. The default cdkstarter
+   secret name is `remote-agent-credentials`; downstream infrastructure may
+   configure a different name. Pass that name with `--secret-name` so the
+   generated runbook contains the exact retrieval command.
+6. Report the external step that remains: configure that one secret in the
+   remote environment and launch a smoke session.
+
+## Contract
+
+A future coding agent is supported without an AWS change when its remote
+environment provides a Linux shell, a setup/start hook, one opaque secret,
+a writable home directory, and HTTPS access to AWS STS plus the allowed service
+endpoints. Set `LISA_REMOTE_AGENT` to a stable lowercase platform label; it is
+used only as `role_session_name`.
+
+Do not create per-repository or per-agent IAM users. Do not expose the bootstrap
+key through standard `AWS_ACCESS_KEY_ID` variables. Do not add production repair
+permissions; production repair is a human-driven local-workstation workflow.

package/plugins/lisa/.codex-plugin/skills/lisa-setup-remote-aws/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Setup Remote AWS"
+short_description: "Install and validate Lisa's…"
+default_prompt:
+  - "Use $lisa-setup-remote-aws: Install and validate Lisa's…."

package/plugins/lisa/commands/setup-remote-aws.md

@@ -0,0 +1,6 @@
+---
+description: "Install Lisa's vendor-neutral AWS CLI bootstrap and platform adapters for remote coding environments."
+argument-hint: "[--platform=all|claude|codex|cursor|copilot|agy|opencode] [--project=<path>] [--secret-name=<name>]"
+---
+
+Use the /lisa-setup-remote-aws skill to install and validate remote coding-agent AWS access. $ARGUMENTS

package/plugins/lisa/scripts/install-remote-agent-aws.mjs

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+/**
+ * Install Lisa's vendor-neutral remote AWS bootstrap into a host project.
+ *
+ * This installer writes only non-secret repository artifacts. The bootstrap
+ * SecretString is configured directly in each remote-agent platform.
+ * @module install-remote-agent-aws
+ */
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_NAME = "remote-agent-aws-setup.sh";
+const INSTALL_COMMAND = `bash scripts/${SCRIPT_NAME}`;
+const VALID_PLATFORMS = new Set([
+  "all",
+  "claude",
+  "codex",
+  "cursor",
+  "copilot",
+  "agy",
+  "opencode",
+]);
+
+function parseArguments(arguments_) {
+  let project = process.cwd();
+  let platform = "all";
+  let secretName = "remote-agent-credentials";
+  for (const argument of arguments_) {
+    if (argument.startsWith("--project=")) {
+      project = path.resolve(argument.slice("--project=".length));
+    } else if (argument.startsWith("--platform=")) {
+      platform = argument.slice("--platform=".length).toLowerCase();
+    } else if (argument.startsWith("--secret-name=")) {
+      secretName = argument.slice("--secret-name=".length);
+    } else {
+      throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+  if (!VALID_PLATFORMS.has(platform)) {
+    throw new Error(
+      `Unsupported platform '${platform}'. Expected one of: ${[...VALID_PLATFORMS].join(", ")}`
+    );
+  }
+  if (!/^[A-Za-z0-9/_+=.@-]+$/.test(secretName)) {
+    throw new Error("--secret-name must be a valid Secrets Manager name");
+  }
+  return { project, platform, secretName };
+}
+
+function writeSetupScript(project) {
+  const source = path.join(
+    path.dirname(fileURLToPath(import.meta.url)),
+    SCRIPT_NAME
+  );
+  const destination = path.join(project, "scripts", SCRIPT_NAME);
+  mkdirSync(path.dirname(destination), { recursive: true });
+  writeFileSync(destination, readFileSync(source));
+  chmodSync(destination, 0o700);
+  return path.relative(project, destination);
+}
+
+function installCursorAdapter(project) {
+  const environmentPath = path.join(project, ".cursor", "environment.json");
+  mkdirSync(path.dirname(environmentPath), { recursive: true });
+
+  const environment = existsSync(environmentPath)
+    ? JSON.parse(readFileSync(environmentPath, "utf8"))
+    : {};
+  const existingInstall = environment.install;
+  if (existingInstall !== undefined && typeof existingInstall !== "string") {
+    throw new Error(
+      `.cursor/environment.json install must be a string before Lisa can merge ${INSTALL_COMMAND}`
+    );
+  }
+  const lisaInstall = `LISA_REMOTE_AGENT=cursor ${INSTALL_COMMAND}`;
+  if (!existingInstall?.includes(SCRIPT_NAME)) {
+    environment.install = existingInstall
+      ? `${lisaInstall} && ${existingInstall}`
+      : lisaInstall;
+  }
+  writeFileSync(environmentPath, `${JSON.stringify(environment, null, 2)}\n`);
+  return path.relative(project, environmentPath);
+}
+
+function installCopilotAdapter(project) {
+  const workflowPath = path.join(
+    project,
+    ".github",
+    "workflows",
+    "copilot-setup-steps.yml"
+  );
+  mkdirSync(path.dirname(workflowPath), { recursive: true });
+  const marker = "Lisa remote AWS bootstrap";
+  const secretEnvironment =
+    "          LISA_AWS_BOOTSTRAP_JSON: ${{ secrets.LISA_AWS_BOOTSTRAP_JSON }}";
+  const checkoutStep = [
+    "      - uses: actions/checkout@v4",
+    "        with:",
+    "          persist-credentials: false",
+  ].join("\n");
+  const step = [
+    `      - name: ${marker}`,
+    "        env:",
+    secretEnvironment,
+    "          LISA_REMOTE_AGENT: copilot",
+    `        run: ${INSTALL_COMMAND}`,
+  ].join("\n");
+
+  if (!existsSync(workflowPath)) {
+    writeFileSync(
+      workflowPath,
+      [
+        'name: "Copilot Setup Steps"',
+        "on:",
+        "  workflow_dispatch:",
+        "jobs:",
+        "  copilot-setup-steps:",
+        "    runs-on: ubuntu-latest",
+        "    permissions:",
+        "      contents: read",
+        "    steps:",
+        checkoutStep,
+        step,
+        "",
+      ].join("\n")
+    );
+    return path.relative(project, workflowPath);
+  }
+
+  const current = readFileSync(workflowPath, "utf8");
+  const lines = current.split("\n");
+  const jobIndex = lines.findIndex(line =>
+    /^\s{2}copilot-setup-steps:\s*$/.test(line)
+  );
+  const jobEndIndex = lines.findIndex(
+    (line, index) => index > jobIndex && /^\s{2}\S[^:]*:\s*$/.test(line)
+  );
+  const stepsIndex = lines.findIndex(
+    (line, index) =>
+      index > jobIndex &&
+      (jobEndIndex < 0 || index < jobEndIndex) &&
+      /^\s{4}steps:\s*$/.test(line)
+  );
+  if (jobIndex < 0 || stepsIndex < 0) {
+    throw new Error(
+      "Existing copilot-setup-steps.yml must contain jobs.copilot-setup-steps.steps before Lisa can merge the AWS bootstrap step"
+    );
+  }
+
+  let changed = false;
+  const checkoutIndex = lines.findIndex(
+    (line, index) =>
+      index > stepsIndex &&
+      (jobEndIndex < 0 || index < jobEndIndex) &&
+      /^\s{6}-\s+uses:\s+actions\/checkout@/.test(line)
+  );
+  if (checkoutIndex >= 0) {
+    const nextStepIndex = lines.findIndex(
+      (line, index) => index > checkoutIndex && /^\s{6}-\s/.test(line)
+    );
+    const checkoutEnd = nextStepIndex < 0 ? lines.length : nextStepIndex;
+    const withIndex = lines.findIndex(
+      (line, index) =>
+        index > checkoutIndex &&
+        index < checkoutEnd &&
+        /^\s{8}with:\s*$/.test(line)
+    );
+    const persistenceIndex = lines.findIndex(
+      (line, index) =>
+        index > checkoutIndex &&
+        index < checkoutEnd &&
+        /^\s{10}persist-credentials:\s*/.test(line)
+    );
+    if (persistenceIndex >= 0) {
+      if (lines[persistenceIndex] !== "          persist-credentials: false") {
+        lines[persistenceIndex] = "          persist-credentials: false";
+        changed = true;
+      }
+    } else if (withIndex >= 0) {
+      lines.splice(withIndex + 1, 0, "          persist-credentials: false");
+      changed = true;
+    } else {
+      lines.splice(
+        checkoutIndex + 1,
+        0,
+        "        with:",
+        "          persist-credentials: false"
+      );
+      changed = true;
+    }
+  }
+
+  const markerIndex = lines.findIndex(line => line.includes(marker));
+  if (markerIndex >= 0) {
+    const nextStepIndex = lines.findIndex(
+      (line, index) => index > markerIndex && /^\s{6}-\s/.test(line)
+    );
+    const managedStepEnd = nextStepIndex < 0 ? lines.length : nextStepIndex;
+    const managedStep = lines.slice(markerIndex, managedStepEnd);
+    if (!managedStep.includes(secretEnvironment)) {
+      const environmentIndex = lines.findIndex(
+        (line, index) =>
+          index > markerIndex &&
+          index < managedStepEnd &&
+          /^\s{8}env:\s*$/.test(line)
+      );
+      if (environmentIndex < 0) {
+        throw new Error(
+          "Existing Lisa remote AWS bootstrap step must contain an env block"
+        );
+      }
+      lines.splice(environmentIndex + 1, 0, secretEnvironment);
+      changed = true;
+    }
+    if (checkoutIndex < 0) {
+      lines.splice(stepsIndex + 1, 0, ...checkoutStep.split("\n"));
+      changed = true;
+    }
+    if (changed) writeFileSync(workflowPath, lines.join("\n"));
+    return path.relative(project, workflowPath);
+  }
+  const additions = checkoutIndex >= 0 ? [step] : [checkoutStep, step];
+  const nextCheckoutStepIndex = lines.findIndex(
+    (line, index) => index > checkoutIndex && /^\s{6}-\s/.test(line)
+  );
+  const updatedJobEndIndex = lines.findIndex(
+    (line, index) => index > jobIndex && /^\s{2}\S[^:]*:\s*$/.test(line)
+  );
+  const additionIndex =
+    checkoutIndex < 0
+      ? stepsIndex + 1
+      : nextCheckoutStepIndex >= 0
+        ? nextCheckoutStepIndex
+        : updatedJobEndIndex >= 0
+          ? updatedJobEndIndex
+          : lines.length;
+  lines.splice(additionIndex, 0, ...additions);
+  writeFileSync(workflowPath, lines.join("\n"));
+  return path.relative(project, workflowPath);
+}
+
+function writeGuide(project, platform, secretName) {
+  const guidePath = path.join(project, "docs", "remote-agent-aws.md");
+  mkdirSync(path.dirname(guidePath), { recursive: true });
+  writeFileSync(
+    guidePath,
+    `# Remote coding-agent AWS access
+
+## Context
+
+This repository uses Lisa's vendor-neutral AWS bootstrap. Configure the complete
+Secrets Manager SecretString as the secret \`LISA_AWS_BOOTSTRAP_JSON\`; do not
+split it into \`AWS_ACCESS_KEY_ID\` and \`AWS_SECRET_ACCESS_KEY\` environment
+variables. The setup script writes a named source profile whose only permission
+is \`sts:AssumeRole\`, then creates automatically refreshed role profiles.
+
+## Goal
+
+Give supported remote coding agents renewable, least-privilege AWS CLI access
+without borrowing a developer identity or granting direct production repair.
+
+## Changes
+
+| Runtime | Setup |
+|---|---|
+| Claude | Add \`LISA_AWS_BOOTSTRAP_JSON\` to the cloud environment, set \`LISA_REMOTE_AGENT=claude\`, and run \`${INSTALL_COMMAND}\` in the setup script. |
+| Codex | Add \`LISA_AWS_BOOTSTRAP_JSON\` as a setup secret, set \`LISA_REMOTE_AGENT=codex\`, and run \`${INSTALL_COMMAND}\` in the setup script. Permit required AWS endpoints during the agent phase. |
+| Cursor | Add the secret to the selected cloud environment. \`.cursor/environment.json\` runs the setup script with \`LISA_REMOTE_AGENT=cursor\`. |
+| Copilot | Add the value as an organization-level **Agents** secret. \`copilot-setup-steps.yml\` runs the setup script with \`LISA_REMOTE_AGENT=copilot\`. |
+| Antigravity | Direct AWS CLI is supported only on a user-managed remote host. Google's managed preview currently documents proxy-injected HTTP credentials, not arbitrary AWS credential files. |
+| OpenCode | Run the setup script on the VPS/container that hosts \`opencode serve\`, with \`LISA_REMOTE_AGENT=opencode\`. OpenCode does not supply the host. |
+
+Generated for: \`${platform}\`.
+
+## Implementation
+
+The bootstrap bundle defines the available profile names. \`dev\` is the
+default when present. Select another account explicitly, for example:
+
+\`\`\`bash
+aws --profile staging sts get-caller-identity
+aws --profile production cloudformation describe-stacks
+\`\`\`
+
+Production and shared profiles are observer-only. Production repair remains a
+human-driven local-workstation operation.
+
+After the infrastructure pipeline deploys the remote-agent IAM stacks, retrieve
+the complete bundle from the shared account. Do not extract or distribute its
+individual access-key fields:
+
+\`\`\`bash
+aws --profile shared secretsmanager get-secret-value \\
+  --secret-id ${secretName} \\
+  --query SecretString \\
+  --output text
+\`\`\`
+
+Store that exact output as the masked secret \`LISA_AWS_BOOTSTRAP_JSON\` on each
+remote-agent platform. Run the setup command and require its live
+\`sts:GetCallerIdentity\` check to pass before considering the platform ready.
+
+## Notes
+
+Rotate by replacing the bootstrap IAM access key through infrastructure and
+then updating this one secret on every configured platform. Disabling or
+deleting the bootstrap user immediately prevents new role sessions.
+`
+  );
+  return path.relative(project, guidePath);
+}
+
+export function installRemoteAgentAws(arguments_ = process.argv.slice(2)) {
+  const { project, platform, secretName } = parseArguments(arguments_);
+  if (!existsSync(project))
+    throw new Error(`Project does not exist: ${project}`);
+
+  const written = [writeSetupScript(project)];
+  if (platform === "all" || platform === "cursor") {
+    written.push(installCursorAdapter(project));
+  }
+  if (platform === "all" || platform === "copilot") {
+    written.push(installCopilotAdapter(project));
+  }
+  written.push(writeGuide(project, platform, secretName));
+  return { project, platform, secretName, written };
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  try {
+    process.stdout.write(
+      `${JSON.stringify(installRemoteAgentAws(), null, 2)}\n`
+    );
+  } catch (error) {
+    process.stderr.write(
+      `install-remote-agent-aws: ${error instanceof Error ? error.message : String(error)}\n`
+    );
+    process.exitCode = 1;
+  }
+}