# AgentCore-Light: local installation, Hook setup, and verification guide

You are a local AI coding agent (for example Claude Code, Codex, Cursor, or
another agent with terminal access). The customer has asked you to install and
test AgentCore-Light. Follow this guide exactly. Do not invent download URLs,
checksums, commands, or test results.

## What AgentCore-Light is

AgentCore-Light is a local companion application for an AgentCore physical
status light. It runs in the customer's own Windows or Linux account, connects
to the light through USB serial or BLE, and translates AI coding-agent activity
into light states such as working, success, and idle. The optional AI Hook lets
the customer's selected coding tool send those activity events automatically.
The background service keeps the light connection available without leaving a
terminal open. This installation does not upload the customer's prompts or
source code; it configures local software and the selected local AI Hook.

## What success means

1. AgentCore-Light is installed for the current desktop user.
2. Its background service is enabled and does not occupy a terminal.
3. The USB/BLE device service is healthy; physical-light tests are confirmed by
   the customer, not guessed by you.
4. The Hook for the selected AI tool is installed and reported as successful.
5. You give the customer a concise result and a short repeatable test flow.

## Consent and safety rules

- Before downloading, installing, changing a Hook, or running a privileged
  command, summarize the action and ask for confirmation if the customer has
  not already explicitly requested it.
- Work only in a customer-chosen stable folder. Never use `/tmp` as the final
  installation location.
- Verify a published SHA-256 checksum before executing a downloaded program.
- Never run `AgentCore-Light` itself with `sudo` or as root.
- On Linux, `sudo` is allowed only for the one-time `dialout` permission and
  optional systemd linger setup described below.
- Do not manually edit a Hook JSON file when the built-in Hook command is
  available. It preserves the customer's existing configuration and backups.
- Never claim that a physical light changed unless the customer confirms it.

## Publisher-controlled release manifest

Use this single source of truth for every download, version, size, and
SHA-256 value:

https://light.buildfpga.com/v1-exe-json/latest.json

Fetch the manifest immediately before download. The shared `version` field is
required. For Windows, use its top-level `url`, `sha256`, and `size` fields.
For Linux, use `linux.url`, `linux.sha256`, and `linux.size`. Stop and report a
publishing error if a required field is missing, an URL returns an error, the
downloaded size differs, or its checksum does not match.

Do not substitute a package from another website. The Linux binary in the
manifest must be compiled on Ubuntu 20 (or another glibc 2.31-compatible
environment) for Ubuntu 20 customers. The publisher updates `latest.json` for
each release; this txt file does not need a hash or version change per release.

## Identify the target and select the correct package

1. Determine the operating system and CPU architecture before downloading.
2. Support Windows x64 and Linux x86_64 only. If the platform is unsupported,
   explain that clearly and stop before installation.
3. Ask whether the customer is using USB serial or BLE. Do not flash firmware
   and do not change firmware as part of this installation.
4. Ask the customer to use a USB Type-C data cable and to postpone attaching
   permanent adhesive until all tests pass.

## Windows installation

Run the following PowerShell commands as the ordinary customer user. They
download and verify the current published Windows binary:

```powershell
$manifestUrl = "https://light.buildfpga.com/v1-exe-json/latest.json"
$manifest = Invoke-RestMethod -Uri $manifestUrl
$version = [string]$manifest.version
$appUrl = [string]$manifest.url
$expectedHash = [string]$manifest.sha256
$expectedSize = [Int64]$manifest.size
if ([string]::IsNullOrWhiteSpace($version) -or [string]::IsNullOrWhiteSpace($appUrl) -or [string]::IsNullOrWhiteSpace($expectedHash) -or $expectedSize -le 0) { throw "Windows 更新清单不完整" }
$downloadDir = Join-Path $env:LOCALAPPDATA "AgentCore-Light\downloads\$version"
New-Item -ItemType Directory -Force -Path $downloadDir | Out-Null
$app = Join-Path $downloadDir "AgentCore-Light.exe"
Invoke-WebRequest -Uri $appUrl -OutFile $app
if ((Get-Item $app).Length -ne $expectedSize) { throw "AgentCore-Light package size mismatch" }
if ((Get-FileHash -Algorithm SHA256 $app).Hash.ToLower() -ne $expectedHash.ToLower()) { throw "AgentCore-Light package SHA-256 mismatch" }
& $app install
```

The verified download folder is only a download location. The app deploys
itself to `%LOCALAPPDATA%\Programs\AgentCoreLightSerial`. On Windows this is
a per-user background process configured to start at user logon (Task
Scheduler, with an HKCU Run fallback); it is not a Windows system service and
does not start before logon.

Run `& $app status`, parse its JSON, and retain the result. Do not
treat exit code `0` as success: require
`service.service_running` to be `true`; record `service.autostart.enabled`,
`service.service_health.connected`, and `service.service_health.last_error`.
If the service is not running, report the error instead of continuing to Hook
installation.

## Linux installation and background service

1. Run these commands as the ordinary customer user.

   ```bash
   set -euo pipefail
   install_dir="$HOME/.local/opt/AgentCore-Light"
   binary="$install_dir/AgentCore-Light"
   manifest_url="https://light.buildfpga.com/v1-exe-json/latest.json"
   metadata="$(python3 - "$manifest_url" <<'PY'
import json
import sys
import urllib.request

with urllib.request.urlopen(sys.argv[1], timeout=20) as response:
    manifest = json.load(response)
package = manifest.get("linux")
if not str(manifest.get("version") or "").strip() or not isinstance(package, dict) or not all(package.get(key) for key in ("url", "sha256", "size")):
    raise SystemExit("Linux 更新清单不完整")
print(package["url"], package["sha256"].lower(), int(package["size"]))
PY
)"
   read -r binary_url expected_hash expected_size <<EOF
$metadata
EOF
   mkdir -p "$install_dir"
   curl -fL "$binary_url" -o "$binary"
   test "$(stat -c %s "$binary")" = "$expected_size"
   printf '%s  %s\n' "$expected_hash" "$binary" | sha256sum -c -
   chmod +x "$binary"
   cd "$install_dir"
   ```

   Stop immediately if any command fails, particularly the checksum check.

2. USB serial users need `dialout` permission. Check whether the current login
   session is already in that group. If it is not, request confirmation and run:

   `sudo usermod -aG dialout $USER`

   Tell the customer to log out and log in again (or reboot). Do not pretend
   that serial access has been fixed until the new login session is active. In
   this case, stop here and resume with step 3 only after the new session.

3. Install the background service as the ordinary customer user:

   `./AgentCore-Light install`

   This creates `~/.config/systemd/user/agentcore-light.service`; it does not
   occupy a terminal after installation completes. The app copies its fixed
   runtime installation to `~/.local/share/AgentCoreLight`.

4. If the customer wants the service to start after boot even before desktop
   login, request confirmation and run this one-time command:

   `sudo loginctl enable-linger $USER`

5. Verify the service:

   `systemctl --user status agentcore-light.service --no-pager`

   `./AgentCore-Light status`

   Parse the JSON result: `service.service_running` and
   `service.autostart.enabled` must be `true`; record
   `service.service_health.connected` and `service.service_health.last_error`.
   A zero command exit code alone does not establish that the device is
   connected.

If the app detects `/dev/ttyACM*` or `/dev/ttyUSB*` but reports permission
denied, state that this is a Linux user-group issue. Give the customer the
exact `dialout` command above and the logout/login requirement; do not advise
running the application itself with `sudo`.

## Install the correct AI Hook

Ask which AI tool the customer wants to connect. If the customer did not name a
tool but your own runtime is clearly Claude Code, Codex, or another mapped tool,
state that you will install the Hook for that current runtime and proceed only
with that one. Do not install Hooks for additional tools. Use the following tool
IDs:

- Claude Code: `claude_code`
- Codex / ChatGPT: `codex`
- Cursor: `cursor`
- Qoder: `qoder`
- CodeBuddy: `codebuddy`
- Antigravity / Gemini: `gemini_antigravity`
- GitHub Copilot: `github_copilot`
- Trae: `trae`
- opencode: `opencode`

Install the selected Hook from the verified application executable:

- Linux: `./AgentCore-Light hook install <tool_id>`
- Windows PowerShell: `& $app hook install <tool_id>`

Read and report the JSON result. A non-zero exit code or `"ok": false` is a
failed installation; do not describe it as successful. Verify the resulting
configuration with:

- Linux: `./AgentCore-Light hook status`
- Windows PowerShell: `& $app hook status`

The top-level `"ok": true` only means the status command ran. Find the selected
tool in `tools` and require both `installed: true` and the expected
`config_path` before reporting Hook success.

If this command says `Unknown command: hook`, the downloaded build is too old
for unattended AI installation. Report that the customer needs a newer release
instead of manually writing Hook configuration.

For Codex / ChatGPT desktop-app users, explain that they may need to open
Settings -> Hooks and trust each newly installed Hook. For every tool, restart
the AI application and start a new conversation before the event test.

## Functional test procedure

Perform only after the service reports healthy and the device is connected.

1. Run `AgentCore-Light status` and record: service state, connection state,
   port/device name, and any error.
2. Send an activity state as a best-effort event trigger:

   `AgentCore-Light send THINKING --source control_panel`

3. Immediately re-check `status` and inspect its connection/error fields. Then
   ask the customer whether the physical light changed to the expected working
   indication. Record their answer exactly. A successful `send` exit code or
   empty JSON output does not prove delivery.
4. Send completion and idle states, waiting about two seconds between them:

   `AgentCore-Light send SUCCESS --source control_panel`

   `AgentCore-Light send IDLE --source control_panel`

5. Ask the customer to create a new conversation in the selected AI tool and
   send one harmless prompt. Confirm that the physical light reacts to the
   agent's state. Do not request, read, or expose private prompt contents.
6. If a Hook test does not react, confirm the Hook command output, restart the
   AI tool, start a new conversation, and check the app's service status before
   making further changes.

## Final report to the customer

Report these fields clearly:

- A one-sentence product summary: AgentCore-Light is installed locally to
  connect the customer's physical status light to the selected AI coding tool.
- OS and package/version installed
- Background-service result and whether it starts before login (Linux linger)
- Device transport and connection result
- Selected AI tool and Hook installation result
- Automated command results
- Physical-light confirmation: confirmed / not confirmed / not tested
- Any remaining manual action, especially Codex Hook trust or Linux relogin

Use this concise customer-facing test flow after installation:

1. Confirm AgentCore-Light is connected in its local control panel.
2. Start a new conversation in the AI tool.
3. Send a harmless prompt and observe the light change to the working state.
4. Let the AI finish and observe the completion/idle state.
5. If it does not react, restart the AI tool, start a new conversation, then
   check AgentCore-Light service status before contacting support.