name	agent-computer
description	Generate the agent-computers spec docs for a VM — an interior COMPUTER.md (the in-VM map) and an exterior OPERATOR.md (the host-side runbook). Use when the user wants to document a VM/sandbox for agent usage, create or refresh a COMPUTER.md / OPERATOR.md, or map a machine an agent will operate.
argument-hint	[vm-name-or-path]
allowed-tools	Bash, Read, Write, Grep, Glob

agent-computer — generate the spec docs for a VM

You are creating the two agent-computers spec documents for a VM:

COMPUTER.md — the interior map, written from inside the VM, for an agent acting from within. It lives at a standard path inside the VM (e.g. /COMPUTER.md).
OPERATOR.md — the exterior runbook, written from the host's view, for an agent acting from without. It lives host-side and is never copied into the VM.

Templates for both live next to this file: templates/COMPUTER.template.md and templates/OPERATOR.template.md. Read them first and fill every <…> placeholder.

The two-audience rule (do not violate)

The reason there are two files is that two different agents read them, in two different frames of reference:

Interior agent → already has access → needs a map in the VM's own frame (/workspace, 0.0.0.0:80).
Exterior agent → needs to reach and operate the VM in the host's frame (vm name, proxied ssh, mapped ports).

Therefore:

COMPUTER.md contains no secret values and no access credentials. Record where a secret comes from (an env var name, a service), never the value. ssh keys, passwords, and proxy commands describe how to reach the VM — they go in OPERATOR.md.
OPERATOR.md must not be mounted or copied into the VM. It is the access map and may point at credentials; keep it off the guest.

Procedure

Identify the target. Use the argument (a vm name or a project path) if given, otherwise ask. Determine whether you can run commands inside the VM (e.g. via heyvm exec <vm> -- <cmd> or an already-open shell) or only have host access.
Probe what you can, for the interior map. Prefer reading ground truth over guessing. Useful, low-risk probes (adapt to the VM and what is available):
- OS / package manager: cat /etc/os-release; check for apt, dnf, apk, pacman.
- tooling + versions: command -v <tool> then <tool> --version (e.g. node, bun, cargo, nginx, python).
- project dirs: look under common roots (/workspace, /data, /srv, /app), and read any build/run config you find.
- services + ports: ss -ltnp (or netstat -ltnp) to see what is listening; map each listener to the service that owns it.
- secret sources: which env var names the main process expects (read names from the running process env or app config — never the values).
- restrictions: idle/sleep policy, sudo availability, outbound network limits.
Gather the exterior facts, for the runbook. vm name, hypervisor, location; the connect command (e.g. heyvm ssh <vm>, or ssh via heyvm ssh-proxy <vm>); how ports map to the host (--open-port → 127.0.0.1:<mapped>); lifecycle commands (start/stop/snapshot/fork); file-transfer method; and a pointer to where credentials live. Build the interior↔exterior address-translation table from the listeners and mounts you found.
Ask only for what you cannot infer. Purpose/intent of the machine, credential location, idle policy, and any "don't touch X" guardrails are usually worth a direct question. Do not fabricate values — leave a clearly-marked <TODO> rather than guess.
Write both files from the templates. Default output locations:
- COMPUTER.md at the project/VM root (and, if you can reach the VM, install it at /COMPUTER.md inside the guest).
- OPERATOR.md host-side, alongside the project — and add it to .gitignore/exclusions if it will reference credentials. Keep the section style of the templates (plain ## SECTION headers with - key: value bullets) so the docs stay skimmable and machine-parseable.
Re-read the result and self-check before finishing:
- No secret values anywhere; no credentials in COMPUTER.md.
- Every listening service in the VM appears in both the interior services list and the exterior address-translation table.
- Every <…> placeholder is filled or marked <TODO: …>.

If the VM is one you cannot reach yet, produce OPERATOR.md first (it is what tells an agent how to connect), then generate COMPUTER.md once a shell is available.

agent-computer — generate the spec docs for a VM

You are creating the two agent-computers spec documents for a VM:

COMPUTER.md — the interior map, written from inside the VM, for an agent acting from within. It lives at a standard path inside the VM (e.g. /COMPUTER.md).

OPERATOR.md — the exterior runbook, written from the host's view, for an agent acting from without. It lives host-side and is never copied into the VM.

Templates for both live next to this file: templates/COMPUTER.template.md and templates/OPERATOR.template.md. Read them first and fill every <…> placeholder.

The two-audience rule (do not violate)

The reason there are two files is that two different agents read them, in two different frames of reference:

Interior agent → already has access → needs a map in the VM's own frame (/workspace, 0.0.0.0:80).

Exterior agent → needs to reach and operate the VM in the host's frame (vm name, proxied ssh, mapped ports).

Therefore:

COMPUTER.md contains no secret values and no access credentials. Record where a secret comes from (an env var name, a service), never the value. ssh keys, passwords, and proxy commands describe how to reach the VM — they go in OPERATOR.md.

OPERATOR.md must not be mounted or copied into the VM. It is the access map and may point at credentials; keep it off the guest.

Procedure

Identify the target. Use the argument (a vm name or a project path) if given, otherwise ask. Determine whether you can run commands inside the VM (e.g. via heyvm exec <vm> -- <cmd> or an already-open shell) or only have host access.

Probe what you can, for the interior map. Prefer reading ground truth over guessing. Useful, low-risk probes (adapt to the VM and what is available):

OS / package manager: cat /etc/os-release; check for apt, dnf, apk, pacman.
tooling + versions: command -v <tool> then <tool> --version (e.g. node, bun, cargo, nginx, python).
project dirs: look under common roots (/workspace, /data, /srv, /app), and read any build/run config you find.
services + ports: ss -ltnp (or netstat -ltnp) to see what is listening; map each listener to the service that owns it.
secret sources: which env var names the main process expects (read names from the running process env or app config — never the values).
restrictions: idle/sleep policy, sudo availability, outbound network limits.

Gather the exterior facts, for the runbook. vm name, hypervisor, location; the connect command (e.g. heyvm ssh <vm>, or ssh via heyvm ssh-proxy <vm>); how ports map to the host (--open-port → 127.0.0.1:<mapped>); lifecycle commands (start/stop/snapshot/fork); file-transfer method; and a pointer to where credentials live. Build the interior↔exterior address-translation table from the listeners and mounts you found.

Ask only for what you cannot infer. Purpose/intent of the machine, credential location, idle policy, and any "don't touch X" guardrails are usually worth a direct question. Do not fabricate values — leave a clearly-marked <TODO> rather than guess.

Write both files from the templates. Default output locations:

COMPUTER.md at the project/VM root (and, if you can reach the VM, install it at /COMPUTER.md inside the guest).
OPERATOR.md host-side, alongside the project — and add it to .gitignore/exclusions if it will reference credentials. Keep the section style of the templates (plain ## SECTION headers with - key: value bullets) so the docs stay skimmable and machine-parseable.

Re-read the result and self-check before finishing:

No secret values anywhere; no credentials in COMPUTER.md.
Every listening service in the VM appears in both the interior services list and the exterior address-translation table.
Every <…> placeholder is filled or marked <TODO: …>.

If the VM is one you cannot reach yet, produce OPERATOR.md first (it is what tells an agent how to connect), then generate COMPUTER.md once a shell is available.