# Step 1 Prompt: System Setup

Source: `laravel/resources/prompts/_source/STEP-1-SYSTEM-SETUP.md`
Prompt version: 76c704a4673d

You are running Step 1 of the Agents HQ product-spec setup. Your job is to
prepare the local filesystem, validate Paperclip/governor health, create or
confirm the Paperclip company, seed policy files, and provision the Blast Radius
Specialist.

## Inputs To Collect

- Company name
- Company prefix for `~/Agents/{company-prefix}/`
- Paperclip base URL, default `http://127.0.0.1:3100`
- `ADAPTER_TYPE`, default `pi_local`
- Whether the user wants Laravel-backed custom connectors now

Initialize these variables before doing any write:

```bash
export PAPERCLIP_URL="${PAPERCLIP_URL:-http://127.0.0.1:3100}"
export ADAPTER_TYPE="${ADAPTER_TYPE:-pi_local}"
export COMPANY_NAME="REPLACE_WITH_COMPANY_NAME"
export COMPANY_PREFIX="REPLACE_WITH_COMPANY_PREFIX"
export BASE="$HOME/Agents/$COMPANY_PREFIX"
```

`COMPANY_PREFIX` must be lowercase kebab case. If the user gives a display name,
derive a prefix with only `a-z`, `0-9`, and `-`, then ask for confirmation.

## Filesystem Layout

Create this structure exactly:

```text
~/Agents/{company-prefix}/
  artifacts/
  policies/
  goals/
  projects/
    _inbox/
  agents/
  reviews/
  governance/
    dream-cycle/
      raw/
    no-gos/
  state/
```

Use commands equivalent to:

```bash
mkdir -p \
  "$BASE/artifacts" \
  "$BASE/policies" \
  "$BASE/goals" \
  "$BASE/projects/_inbox" \
  "$BASE/agents" \
  "$BASE/reviews" \
  "$BASE/governance/dream-cycle/raw" \
  "$BASE/governance/no-gos" \
  "$BASE/state"
```

Preserve `_inbox` exactly, including the leading underscore.

Seed per-bucket policy and goal files for:

- `cockpit`
- `wings`
- `left-engine`
- `right-engine`
- `fuel-tank`
- `fuselage`

Download seeded assets from Laravel:

- `http://agents.tractionstudio.ai/downloads/policies/company-policy.md`
- `http://agents.tractionstudio.ai/downloads/policies/bucket-policy.md`
- `http://agents.tractionstudio.ai/downloads/policies/bucket-goals.md`
- `http://agents.tractionstudio.ai/downloads/policies/blast-radius.md`
- `http://agents.tractionstudio.ai/downloads/policies/blast-radius-rules.md`
- `http://agents.tractionstudio.ai/downloads/policies/blast-radius-rules.json`
- `http://agents.tractionstudio.ai/downloads/policies/blast-radius-overrides.md`
- `http://agents.tractionstudio.ai/downloads/policies/blast-radius-overrides.json`
- `http://agents.tractionstudio.ai/downloads/policies/blast-radius-task-schema.md`
- `http://agents.tractionstudio.ai/downloads/policies/reviewer-policy.md`
- `http://agents.tractionstudio.ai/downloads/policies/dream-cycle.md`
- `http://agents.tractionstudio.ai/downloads/policies/blast-radius-specialist-agents-md.md`

Use commands equivalent to:

```bash
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/company-policy.md" -o "$BASE/policies/company.md"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/reviewer-policy.md" -o "$BASE/policies/reviewer.md"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/blast-radius.md" -o "$BASE/policies/blast-radius.md"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/blast-radius-rules.md" -o "$BASE/policies/blast-radius-rules.md"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/blast-radius-rules.json" -o "$BASE/policies/blast-radius-rules.json"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/blast-radius-overrides.md" -o "$BASE/policies/blast-radius-overrides.md"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/blast-radius-overrides.json" -o "$BASE/policies/blast-radius-overrides.json"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/blast-radius-task-schema.md" -o "$BASE/policies/blast-radius-task-schema.md"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/dream-cycle.md" -o "$BASE/governance/dream-cycle/policy.md"

cat > "$BASE/goals/company.md" <<'EOF'
# Company Goals

To be synthesized from business artifacts in Step 2.
EOF

for bucket in cockpit wings left-engine right-engine fuel-tank fuselage; do
  curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/bucket-policy.md" -o "$BASE/policies/$bucket.md"
  curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/bucket-goals.md" -o "$BASE/goals/$bucket.md"
  BUCKET="$bucket" COMPANY_NAME="$COMPANY_NAME" COMPANY_PREFIX="$COMPANY_PREFIX" \
    perl -0pi -e 's/\{\{\s*bucket\s*\}\}/$ENV{BUCKET}/g; s/\{\{\s*company_name\s*\}\}/$ENV{COMPANY_NAME}/g; s/\{\{\s*company_prefix\s*\}\}/$ENV{COMPANY_PREFIX}/g' \
    "$BASE/policies/$bucket.md" "$BASE/goals/$bucket.md"
done

COMPANY_NAME="$COMPANY_NAME" COMPANY_PREFIX="$COMPANY_PREFIX" \
  perl -0pi -e 's/\{\{\s*company_name\s*\}\}/$ENV{COMPANY_NAME}/g; s/\{\{\s*company_prefix\s*\}\}/$ENV{COMPANY_PREFIX}/g' \
  "$BASE/policies/company.md"
```

Use `perl -pi -e` or `perl -0pi -e` for replacements. Do not use `sed -i`.

Write an initial state file:

```bash
cat > "$BASE/state/setup.json" <<EOF
{
  "companyName": "$COMPANY_NAME",
  "companyPrefix": "$COMPANY_PREFIX",
  "base": "$BASE",
  "paperclipUrl": "$PAPERCLIP_URL",
  "adapterType": "$ADAPTER_TYPE",
  "step": "step-1.filesystem"
}
EOF
```

## Paperclip Health

Use the live server, defaulting to `http://127.0.0.1:3100`.

The current authenticated Paperclip runtime behaves like this when unauthenticated:

- `GET /api/health` returns `200` with `deploymentMode: "authenticated"`.
- `GET /api/companies` and `GET /api/plugins` return `403 Board access required`.
- `POST /api/plugins/paperclip-plugin-connectors/actions/governor.status`
  returns `403 Board access required`.

Treat `401` or `403 Board access required` on protected Paperclip routes as an
authentication failure, not as evidence that the route or plugin is missing.
Stop and ask the user to authenticate to the local Paperclip board before
continuing.

Run checks in this order:

```bash
curl -fsS "$PAPERCLIP_URL/api/health" | tee "$BASE/state/paperclip-health.json"

if ! curl -fsS "$PAPERCLIP_URL/api/companies" -o "$BASE/state/paperclip-companies.json"; then
  echo "Paperclip board access is required. Authenticate to $PAPERCLIP_URL, then retry Step 1."
  exit 1
fi

if ! curl -fsS "$PAPERCLIP_URL/api/plugins" -o "$BASE/state/paperclip-plugins.json"; then
  echo "Cannot read Paperclip plugins. Confirm board access and retry."
  exit 1
fi

if ! grep -q "paperclip-plugin-connectors" "$BASE/state/paperclip-plugins.json"; then
  echo "paperclip-plugin-connectors is not installed. Install or enable it, then retry Step 1."
  exit 1
fi

CONNECTORS_PLUGIN_STATUS="installed"
```

Stop if any required check fails:

1. Health endpoint responds.
2. Connectors plugin is installed.
3. Governor status is available and enabled through the connectors plugin.
4. Company create/update route is available.
5. Agent create/update route is available.
6. Instructions-bundle route is available at:
   `PATCH /api/agents/{agentIdOrShortname}/instructions-bundle?companyId={companyId}`.

For governor status, use the action endpoint first:

```bash
curl -fsS -X POST "$PAPERCLIP_URL/api/plugins/paperclip-plugin-connectors/actions/governor.status" \
  -H "Content-Type: application/json" \
  -d '{}' \
  -o "$BASE/state/governor.json"

GOVERNOR_ENABLED="$(jq -r '.enabled // .data.enabled // false' "$BASE/state/governor.json")"
if [ "$GOVERNOR_ENABLED" != "true" ]; then
  echo "Governor is disabled. Enable it in the connectors plugin settings, then retry Step 1."
  exit 1
fi

GOVERNOR_STATUS="enabled"
```

Legacy bridge paths may return `404` on the current runtime. Use the keyed
`/api/plugins/paperclip-plugin-connectors/actions/governor.status` endpoint as
the supported path.

## Company Creation

Create or confirm the Paperclip company after board authentication works.

```bash
PAPERCLIP_COMPANY_ID="$(jq -r --arg name "$COMPANY_NAME" '(.data // .companies // .)[]? | select(.name == $name) | .id' "$BASE/state/paperclip-companies.json" | head -1)"

if [ -z "$PAPERCLIP_COMPANY_ID" ] || [ "$PAPERCLIP_COMPANY_ID" = "null" ]; then
  curl -fsS -X POST "$PAPERCLIP_URL/api/companies" \
    -H "Content-Type: application/json" \
    -d "{\"name\":\"$COMPANY_NAME\",\"prefix\":\"$COMPANY_PREFIX\"}" \
    -o "$BASE/state/paperclip-company.json"
  PAPERCLIP_COMPANY_ID="$(jq -r '.id // .data.id // empty' "$BASE/state/paperclip-company.json")"
fi

test -n "$PAPERCLIP_COMPANY_ID" || {
  echo "Could not determine Paperclip company ID."
  exit 1
}
```

If Paperclip requires a first agent at company creation, create a stub `ceo` only
long enough to satisfy the runtime; Step 2 must rewrite the CEO AGENTS.md from
real artifacts. If Paperclip does not require the first agent, do not create a
stub CEO in Step 1.

## Blast Radius Specialist

Write:

```text
$BASE/agents/specialist-of-blast-radius/AGENTS.md
$BASE/agents/specialist-of-blast-radius/memory/
$BASE/agents/specialist-of-blast-radius/reviews/
```

Use commands equivalent to:

```bash
mkdir -p "$BASE/agents/specialist-of-blast-radius/memory" "$BASE/agents/specialist-of-blast-radius/reviews"
curl -fsSL "http://agents.tractionstudio.ai/downloads/policies/blast-radius-specialist-agents-md.md" \
  -o "$BASE/agents/specialist-of-blast-radius/AGENTS.md"
```

Create the agent with the role adapter. Do not include `agentsMdPath` at the top
level:

```json
{
  "name": "specialist-of-blast-radius",
  "role": "general",
  "adapterType": "$ADAPTER_TYPE",
  "adapterConfig": {},
  "runtimeConfig": {},
  "metadata": {
    "productRole": "specialist",
    "specialty": "blast-radius",
    "bucket": "cockpit",
    "reportsToName": "ceo",
    "blastRadiusCeiling": 4,
    "agentsMdPath": "$BASE/agents/specialist-of-blast-radius/AGENTS.md"
  }
}
```

Use a request equivalent to:

```bash
cat > "$BASE/state/blast-radius-agent-payload.json" <<EOF
{
  "name": "specialist-of-blast-radius",
  "role": "general",
  "adapterType": "$ADAPTER_TYPE",
  "adapterConfig": {},
  "runtimeConfig": {},
  "metadata": {
    "productRole": "specialist",
    "specialty": "blast-radius",
    "bucket": "cockpit",
    "reportsToName": "ceo",
    "blastRadiusCeiling": 4,
    "agentsMdPath": "$BASE/agents/specialist-of-blast-radius/AGENTS.md"
  }
}
EOF

curl -fsS -X POST "$PAPERCLIP_URL/api/companies/$PAPERCLIP_COMPANY_ID/agents" \
  -H "Content-Type: application/json" \
  -d @"$BASE/state/blast-radius-agent-payload.json" \
  -o "$BASE/state/blast-radius-agent.json"

BR_AGENT_ID="$(jq -r '.id // .data.id // .agent.id // empty' "$BASE/state/blast-radius-agent.json")"
test -n "$BR_AGENT_ID" || {
  echo "Could not determine Blast Radius Specialist Paperclip agent ID."
  exit 1
}
```

After the agent exists, update its instructions bundle to external mode:

```bash
curl -fsS -X PATCH "$PAPERCLIP_URL/api/agents/$BR_AGENT_ID/instructions-bundle?companyId=$PAPERCLIP_COMPANY_ID" \
  -H "Content-Type: application/json" \
  -d "{\"mode\":\"external\",\"rootPath\":\"$BASE/agents/specialist-of-blast-radius\",\"entryFile\":\"AGENTS.md\"}"
```

Save the returned Paperclip agent ID in:

```text
$BASE/state/agent-registry.json
```

Use JSON for future reports-to and span-of-control lookups.

Do not clobber `agent-registry.json`. Step 1 creates the first entry; Steps 2-4
must merge additional agents into the same JSON file.

```bash
REGISTRY="$BASE/state/agent-registry.json"
test -f "$REGISTRY" || printf '{"companyId":"%s","agents":{}}\n' "$PAPERCLIP_COMPANY_ID" > "$REGISTRY"

tmp="$(mktemp)"
jq \
  --arg companyId "$PAPERCLIP_COMPANY_ID" \
  --arg name "specialist-of-blast-radius" \
  --arg id "$BR_AGENT_ID" \
  --arg path "$BASE/agents/specialist-of-blast-radius/AGENTS.md" \
  '.companyId = $companyId
   | .agents = (.agents // {})
   | .agents[$name] = {
      paperclipAgentId: $id,
      productRole: "specialist",
      paperclipRole: "general",
      bucket: "cockpit",
      specialty: "blast-radius",
      reportsToName: "ceo",
      agentsMdPath: $path
    }' "$REGISTRY" > "$tmp" && mv "$tmp" "$REGISTRY"
```

## Optional Laravel Link

Laravel account linking is optional. Only require `AGENTS_HQ_USER_TOKEN` when
the user wants setup telemetry or Laravel-backed custom connectors.

If `AGENTS_HQ_USER_TOKEN` is missing and legacy `AGENTS_HQ_TOKEN` is set, treat
it as a bootstrap user-token alias and emit:
`AGENTS_HQ_TOKEN is deprecated for setup bootstrap; use AGENTS_HQ_USER_TOKEN.`

If `AGENTS_HQ_USER_TOKEN` is set, create a setup session before mutating local state:

```bash
curl -fsS -X POST "http://agents.tractionstudio.ai/api/v1/setup-sessions" \
  -H "Authorization: Bearer $AGENTS_HQ_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "running",
    "current_step": "step-1",
    "prompt_version": "76c704a4673d",
    "local_root_path": "'"$BASE"'",
    "company_prefix": "'"$COMPANY_PREFIX"'",
    "paperclip_base_url": "'"$PAPERCLIP_URL"'"
  }' \
  -o "$BASE/state/setup-session.json"

SETUP_SESSION_ID="$(jq -r '.data.id // empty' "$BASE/state/setup-session.json")"
```

Save the returned setup session ID in `$BASE/state/setup-session.json`. After
each blocking checkpoint, `PATCH /api/v1/setup-sessions/{id}` with `status`,
`current_step`, and `last_error` when applicable.

If the user wants custom connectors:

1. Confirm `AGENTS_HQ_USER_TOKEN` is set.
2. `POST http://agents.tractionstudio.ai/api/v1/companies/from-paperclip` after the Paperclip
   company ID exists. Include `setup_session_id` when telemetry is enabled and
   include `runtime_profile` fields:

```json
{
  "paperclip_team_id": "$PAPERCLIP_COMPANY_ID",
  "name": "$COMPANY_NAME",
  "setup_session_id": "$SETUP_SESSION_ID",
  "runtime_profile": {
    "company_prefix": "$COMPANY_PREFIX",
    "local_root_path": "$BASE",
    "paperclip_base_url": "$PAPERCLIP_URL",
    "policy_version": "76c704a4673d",
    "governor_status": "$GOVERNOR_STATUS",
    "plugin_status": "$CONNECTORS_PLUGIN_STATUS",
    "setup_step": "step-1g"
  }
}
```

3. Save `data.company_api_key.plain_key` to the connectors plugin company config
   as `AGENTS_HQ_COMPANY_TOKEN` only when `data.company_api_key.generated` is
   `true`. If `generated` is `false`, keep the existing saved company key.
   Never save `AGENTS_HQ_USER_TOKEN` to the plugin.

Use commands equivalent to:

```bash
LINK_RESPONSE="$(mktemp)"
curl -fsS -X POST "http://agents.tractionstudio.ai/api/v1/companies/from-paperclip" \
  -H "Authorization: Bearer $AGENTS_HQ_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d @- \
  -o "$LINK_RESPONSE" <<EOF
{
  "paperclip_team_id": "$PAPERCLIP_COMPANY_ID",
  "name": "$COMPANY_NAME",
  "setup_session_id": "$SETUP_SESSION_ID",
  "runtime_profile": {
    "company_prefix": "$COMPANY_PREFIX",
    "local_root_path": "$BASE",
    "paperclip_base_url": "$PAPERCLIP_URL",
    "policy_version": "76c704a4673d",
    "governor_status": "$GOVERNOR_STATUS",
    "plugin_status": "$CONNECTORS_PLUGIN_STATUS",
    "setup_step": "step-1g"
  }
}
EOF

AGENTS_HQ_COMPANY_TOKEN="$(jq -r '.data.company_api_key.plain_key // empty' "$LINK_RESPONSE")"
COMPANY_KEY_GENERATED="$(jq -r '.data.company_api_key.generated // false' "$LINK_RESPONSE")"
jq '{
  company_id: .data.company.id,
  company_api_key_id: .data.company_api_key.id,
  company_token_generated: .data.company_api_key.generated,
  company_token_saved: false
}' "$LINK_RESPONSE" > "$BASE/state/laravel-link.json"
rm -f "$LINK_RESPONSE"
```

Use the current plugin action endpoint first:

```bash
curl -fsS -X POST "$PAPERCLIP_URL/api/plugins/paperclip-plugin-connectors/actions/admin.laravel.config.company.save" \
  -H "Content-Type: application/json" \
  -d "{\"params\":{\"companyId\":\"$PAPERCLIP_COMPANY_ID\",\"baseUrl\":\"http://agents.tractionstudio.ai\",\"apiToken\":\"$AGENTS_HQ_COMPANY_TOKEN\"}}"

tmp="$(mktemp)"
jq '.company_token_saved = true' "$BASE/state/laravel-link.json" > "$tmp" && mv "$tmp" "$BASE/state/laravel-link.json"
```

If the user does not want custom connectors now, skip cleanly.

## Step 1 Done

Report the company prefix, Paperclip company ID, governor status, policy files
written, Blast Radius Specialist ID, and whether Laravel connector linking was
configured or skipped.