Invest Setup

Invest Setup Skill

Single responsibility: turn an empty openInvest deployment into a working one. Triggers only on the user's first-time setup — run once, then step aside (the invest skill takes over all day-to-day interaction).

When to Use

• User explicitly says "set up invest" / "initialize invest" / "帮我初始化 invest"
• The invest skill's doctor returns status: "needs_setup" (memory / user_profile missing)
• User wants to reconfigure (explicitly says "reset" / "重新配置"; requires --force): on an existing install --force only updates name and risk tolerance in user.md — holdings, tracking, strategy and history stay as they are; change allocations with set_allocations, caps and tracking with track_asset / untrack_asset
• v1 → v2 schema migration: doctor's portfolio_schema check says needs_migration (an install made by an older version; status shows cash 0). Run the exact command in that check's hint — it backs up portfolio.md and converts it. Do not rerun init for this

When NOT to Use

• User is already onboarded (doctor returns status: "ready") → switch to the invest skill
• User wants to view holdings / P&L / run the committee → use the invest skill
• User wants to track a new asset but is already onboarded → the invest skill's POST /api/holdings endpoint
• User wants to commit / push code → that's a git operation, unrelated to setup

If you (the agent) entered this skill by mistake, exit immediately and tell the user to use the invest skill instead.

Two onboarding paths

Phrasings that trigger Path B: "connect to my hub / 连接我的 hub" / "it's already installed on my server / 我服务器上已经装好了" / "share one portfolio across machines / 多台电脑共用持仓" / "connect to my existing deployment".

Path B: connect to an existing hub (no init)

1. Ask two questions:
   • Hub address? (e.g. https://invest.example.com or http://10.0.0.6:8765)
   • Does the hub have auth enabled? A token (INVEST_API_TOKEN) or a Cloudflare Access service token (CF_ACCESS_CLIENT_ID/SECRET)? Skip if not enabled.
2. Write the answers into $INVEST_HOME/.env (only these two or three lines are needed; no DeepSeek key / Gmail / 5-question flow — those all live on the hub):

   INVEST_API_BASE=https://invest.example.com
   INVEST_API_TOKEN=...        # optional

3. Verify: run run.sh doctor → it should return status: "ready" plus a remote section (api_base / auth method). If it can't connect, the error JSON's hint tells you whether the problem is the address, the token, or the hub service not running.
4. Done — hand over to the invest skill.

Note: Path B must not run init (init is disabled in remote mode and will error); no memory/ is created on this machine — all data stays on the hub.

Flow (4 steps)

1. Run doctor first to confirm setup is really needed

~/.claude/skills/invest-setup/scripts/run.sh doctor

Returns status: "ready" → exit immediately and tell the user "you're already onboarded — just use the invest skill".

Returns status: "needs_setup" → go to step 2.

2. Ask the user 5 questions (use AskUserQuestion on the Coordinator path, your conversational tool on the Direct path)

Q4 natural language (key change 2026-05)

Do not ask field by field. Let the user describe their holdings in one sentence:

"510300 CSI 300 ETF, 3000 shares at 4.2 CNY; 80k in CMB Zhaozhaobao; 50 grams of ICBC gold accumulation at 750 average cost" "AAPL 100 shares at 150 USD cost, 0.3 BTC, 50k CNY cash" "Nothing at all, just 10k CNY"

When the backend cmd_init sees a holdings_description field it calls DeepSeek to parse it into the v2 schema. Without a DeepSeek key it falls back to profile.current_assets (only cash_cny / aud_cash get written into the portfolio) — so always copy the cash amounts the user mentioned into current_assets too, and tell the user about this.

Boundary rules to tell the user (not enforced):

• For A-shares, just say the code (510300) — no .SS suffix needed
• For HK / US stocks, say the ticker (0700.HK or "Tencent")
• For crypto, just say the coin (BTC / ETH)
• Yu'ebao / Zhaozhaobao / money-market funds → the parser routes them into cash, not holdings

3. wealth_context (optional but recommended)

If the user reveals "this account is pocket money" / "I have an emergency reserve" / "family backup" → ask one more question:

Do you have an emergency fund / family backup outside this portfolio? Roughly how much? (Family funds cannot be used for investing — they only serve to prevent the "low cash = high risk" misjudgment.)

Record it into wealth_context:

wealth_context:
  emergency_buffer_cny: 200000  # or whatever number the user gives
  family_backup_available: true
  account_purpose: "pocket-money account"  # the user's own words
  lifestyle_notes: "..."

See docs/wiki/12-verification.md claim 7 (WealthContextOfficer) for details.