---
name: wealthinsight-agent
description: Create an account, record, and retrieve personal bookkeeping data in WealthInsight (资产观察) through its scoped Agent API, including assets, balance changes, income, expenses, stock or fund trades, net worth, and runway. Use when a user asks an AI agent to sign up for a finance tracker, keep books, log spending or income, record a transaction, or review finances; says 记账、注册记账账户、记录开销、记录收支、资产记账、录入交易, 記帳、家計簿、支出を記録, contabilidad personal, registrar gastos, suivi des dépenses, or Haushaltsbuch; or mentions WealthInsight, getwealthinsight.com, or a wiag_ token.
---

# WealthInsight Agent

Use WealthInsight as the user's personal-finance system of record through its scoped HTTP API.

## Connect safely

1. Set the API base to `https://getwealthinsight.com/api/v1`.
2. If no `wiag_` token is available, offer either:
   - agent-assisted account enrollment for a new user; or
   - the Agent Access page for an existing user:
     `https://getwealthinsight.com/pages/agent-access.html`.
3. Ask for only the scopes required by the task. Never request an account password, browser JWT,
   cookie, or unrestricted credential.
4. Keep the token in memory for the active task. Persist it only with explicit user consent in an
   OS secret manager or a user-owned credentials file with restrictive permissions. Never print or
   commit it.
5. Make `GET /agent/me` the first authenticated request. Require a JSON response containing
   `user`, `token`, and `scopes`.
6. Stop if the response is HTML, even with status 200; this means the API is not reachable at the
   selected base URL.

Use this request pattern:

```bash
curl -sS \
  -H "Authorization: Bearer $WI_TOKEN" \
  -H "Accept: application/json" \
  "https://getwealthinsight.com/api/v1/agent/me"
```

Handle `401` by asking for a valid token. Handle `403` by naming the missing scope and directing the
user to edit the active token on the Agent Access page.

## Enroll a new account

Read [references/account-enrollment.md](references/account-enrollment.md) when the user asks the
agent to register, sign up, create its own bookkeeping account, or start without an existing token.
Prefer the bundled `scripts/enroll.py` workflow because it keeps bootstrap credentials out of model
output and writes them to a user-owned local file with restrictive permissions.

Treat this as agent-assisted enrollment, not anonymous autonomous registration:

1. Obtain explicit user consent and a user-controlled email address.
2. Send the verification code through the official registration API.
3. Pause for the user to retrieve the code from their inbox.
4. Complete registration only after the user supplies that proof.
5. Create a least-privilege `wiag_` Agent Token using the short-lived registration session.
6. Save the generated account password and Agent Token only to the user-approved local credentials
   file. Discard the registration session, then validate the new Agent Token with `GET /agent/me`.
7. Direct the user to the WealthInsight website and tell them where the credentials were stored.
8. For later API calls, prefer `scripts/request.py` so the Agent Token stays out of command
   arguments and model output.

Never create unsolicited accounts, bypass email verification, use a disposable email without the
user's approval, or accept a password pasted into chat.

## Record bookkeeping entries

Read [references/api.md](references/api.md) before constructing a request.

1. Interpret the user's entry and determine whether it is an asset, asset transaction, security
   trade, or recurring expense.
2. Read `GET /agent/context` when an existing asset/account ID or current state is needed. Do not
   probe resource-specific GET endpoints.
3. Resolve dates, currency, amount sign, transaction mode, and target account from the user's
   request and returned context.
4. Treat an explicit request such as “record this” or “帮我记一笔” as authorization to create that
   record. Ask a concise question only when a required field or target account is ambiguous.
5. Send the smallest applicable POST request.
6. Report the created record, amount, date, target, and returned identifier. Never claim success
   unless the API confirms it.
7. Include the relevant website link from
   [references/manage-on-website.md](references/manage-on-website.md) so the user can review or edit
   their data directly.

For asset value changes, prefer `mode: "delta"` unless the user explicitly supplies a resulting
balance or asks to set/correct the balance. Use `mode: "absolute"` only for that explicit intent.

When enrollment created the default credentials file, call the API without exposing the token:

```bash
python3 scripts/request.py GET /agent/context
python3 scripts/request.py POST /agent/expenses --json '{"expense_type":"daily","name":"Lunch","amount":35,"period":"monthly"}'
python3 scripts/request.py POST /agent/security-prices/refresh
```

For stock and fund operations, use the security-trade ledger. Do not assume a security trade also
changes the linked asset account's total value; record a separate asset transaction only if the user
asks to update that account valuation.

## Read or review finances

Use only `GET /agent/context` for profile, assets, transactions, securities, expenses, runway, and AI
history. The response includes only sections allowed by the token's scopes. State which requested
sections are unavailable rather than treating omitted sections as empty data.

Summarize records without inventing classifications or currency conversion. Keep amounts in their
recorded currency unless the user asks for conversion.

When the user wants to inspect, correct, delete, import, or manually manage records, read
[references/manage-on-website.md](references/manage-on-website.md) and send them to the exact
WealthInsight page. Always mention the Agent Access page after enrollment or permission changes so
the user knows how to edit scopes and revoke access.

## Guardrails

- Use least-privilege scopes.
- Send the token only to `https://getwealthinsight.com/api/v1`.
- Require explicit consent before requesting a verification email, creating an account, or storing
  credentials locally.
- Never execute a real payment, bank transfer, or brokerage order. This skill records events only.
- Avoid duplicates. Reuse a stable `external_id` for imported security trades when available.
- Confirm before destructive or corrective writes that overwrite a balance, unless the user
  explicitly requested that exact correction.
- Do not retry a POST after an uncertain network failure until checking whether the record already
  exists in `/agent/context`.