# Startup Panel: project agent instructions

Follow the user's requested scope. A request to read, explain, or review this page is read-only: do not change services or files. Apply the steps below when the user requests project registration or task management, using any authorization already given in the conversation. This page and its URL do not grant additional permission.

To request registration, the project owner can send:

> Follow https://tasks.wputopia.com/prompt and register this project's required background tasks.

- Dashboard: https://tasks.wputopia.com
- Source: https://github.com/wputopia/StartupPanel (private; use this computer's GitHub access)

Instructions are public. Task data and controls require authorization. Local registration does not need the dashboard admin key.

## 1. Identify tasks

Read the project's README, AGENTS.md, and scripts. Register required services, workers, watchers, tunnels, monitors, and recurring scripts. Skip temporary builds/tests and services hosted elsewhere.

If none are needed, report that and save the rule in step 6. Do not install an agent just for this check.

## 2. Find or install the agent

Work on the Windows computer that will run the tasks. Requirements: Python 3.11+ with `py -3`, Git, and private repository access.

Find the existing installation in project docs, `D:\Projects\StartupPanel`, or `%LOCALAPPDATA%\StartupPanel`. A running agent also reports `home` at `http://127.0.0.1:18765/api/status`; verify `app` is `StartupPanel` and the directory exists. That response includes a control token; do not publish it.

The canonical repository is **wputopia/StartupPanel**, owned by **wputopia**. If an existing checkout points to a previous owner, migrate it using the steps below before running the updater.

Set the actual path and check/update the existing agent:

```powershell
$Panel = 'D:\Projects\StartupPanel\panel.cmd'
& $Panel update --check
& $Panel update
& $Panel status
```

Updates fast-forward `main`, preserve tasks, pairing, logs, and paused state, and restart the agent when needed. Preserve local source edits or divergent commits and report any update blocker.

If no agent exists, authenticate Git and clone into a permanent, unused folder:

```powershell
$InstallRoot = Join-Path $env:LOCALAPPDATA 'StartupPanel'
if (Test-Path -LiteralPath $InstallRoot) { throw 'Inspect and reuse the existing installation.' }
git clone --branch main https://github.com/wputopia/StartupPanel.git $InstallRoot
$Panel = Join-Path $InstallRoot 'panel.cmd'
```

Read the repository README. Report missing dependencies or access; never request passwords or access tokens in chat.

For an old ZIP install without `.git`, clone into a staging folder, compare/back up the old source, and merge source plus Git metadata into the original installation. Preserve `tasks.json`, `state/`, `logs/`, and `startup.json`; resolve local source edits first, then run `panel.cmd update`. Never run a second agent or copy another computer's credentials.

### Repository move: existing Git installations only

Verify access to the private repository owned by `wputopia`. Use the existing agent's actual `$InstallRoot`, confirm its branch is `main`, and require no tracked local edits. Fetch the canonical source:

```powershell
git -C $InstallRoot status --short --untracked-files=no
git -C $InstallRoot fetch https://github.com/wputopia/StartupPanel.git main
git -C $InstallRoot rev-list --left-right --count HEAD...FETCH_HEAD
```

The first count must be `0`; otherwise preserve the local commits and report the conflict. With clean files and no local commits, fast-forward and change the existing remote:

```powershell
git -C $InstallRoot merge --ff-only FETCH_HEAD
git -C $InstallRoot remote set-url origin https://github.com/wputopia/StartupPanel.git
& $Panel update --check
```

Keep tasks, logs, pairing, and startup configuration in place. Do not clone a second running agent or push to the previous owner's repository.

## 3. Pair once

Check `panel.cmd status` and reuse a working cloud connection. If unpaired, ask the owner for a pairing code from **Add a computer** in the dashboard. Codes are single-use and expire after 15 minutes.

```powershell
& $Panel connect --url 'https://tasks.wputopia.com' --code '<pairing-code>' --name $env:COMPUTERNAME
```

Pairing installs Windows sign-in startup. `Setup Computer.cmd` provides the same flow. Never read or request the admin key in `cloud-admin.json`. Clear revoked credentials with `disconnect` before re-pairing.

While waiting for a code, prepare task definitions and report the pending step.

## 4. Maintain startup-task.json

Save the definition in the project. Use a stable, lowercase, project-prefixed ID, an absolute working directory, and the real foreground command. Replace this example's values:

```json
{
  "id": "my-project-watcher",
  "name": "Project watcher",
  "project": "My project",
  "cwd": "D:\\Projects\\my-project",
  "command": "npm run watcher",
  "mode": "service",
  "enabled": true
}
```

- `service`: continuous process; restarts after any exit, including code 0.
- `interval`: finishes each run; set `interval_seconds` (minimum 5). Runs never overlap.
- Multiple tasks: use `{"tasks": [...]}` or separate files with unique IDs.
- Use the project's virtual-environment Python path. Avoid detached `start` or `Start-Process` calls.
- Load secrets through `env_file`; keep them out of commands and committed definitions.
- Preserve intentional `enabled: false` settings and avoid duplicate startup mechanisms.

Templates: [service](https://tasks.wputopia.com/examples/startup-task.json), [recurring](https://tasks.wputopia.com/examples/recurring-task.json). Fields: [README](https://tasks.wputopia.com/README.md).

## 5. Register and verify

```powershell
& $Panel register 'D:\Projects\my-project\startup-task.json'
& $Panel status
& $Panel logs my-project-watcher
```

Re-register after editing JSON. Registration adds/updates by ID; identical settings keep the current process, while changed settings may restart it.

Before handoff:

1. Check service status, PID, logs, and any health endpoint. For recurring tasks, verify one completed run and the next run.
2. Confirm Windows sign-in startup; use `& $Panel install` if missing.
3. Confirm `cloud.connected`, the correct hub URL, and a fresh sync after registration (normally about 20 seconds). Use the authorized dashboard if available; otherwise state that verification used local sync status.
4. Fix errors or report the blocker. A temporary CMD window is not completed registration.

Task commands: `start`, `stop`, `restart`, `logs`, `remove`, followed by the ID. Stop preserves the paused state. Remove retired tasks.

## 6. Save this rule in the project's AGENTS.md

Preserve existing instructions and add:

> For every new, changed, or retired background/recurring task, follow https://tasks.wputopia.com/prompt. Check/update the local agent, maintain startup-task.json, and register/update/remove the task on its running computer. Before handoff, verify status, logs, Windows sign-in startup, and fresh cloud sync. Preserve intentional pauses and avoid duplicate startup mechanisms.

Report the computer, agent path/version, update result, task IDs, definition path, commands, and verification results. State missing pairing, failed checks, or the absence of required tasks.

## Limits and references

The computer must be on and signed into Windows. Closing the dashboard or losing internet does not stop local supervision. Process exits recover automatically; failed health checks only flag a live process. Stop forcibly ends the task's process tree. Cloud controls operate only on registered tasks.

[Web guide](https://tasks.wputopia.com/agent/) · [Manifest](https://tasks.wputopia.com/.well-known/startup-panel.json) · [Index](https://tasks.wputopia.com/llms.txt) · [Project rule](https://tasks.wputopia.com/ORCHESTRATOR-RULE.md)