onboarding

# Onboarding Skill

## Purpose

Help new users set up their investment profile through a natural, conversational flow. The agent gathers preferences and stores them as rich, descriptive text that future conversations can reference for personalized advice.

This skill provides 5 tools:
- `get_user_data` - Read user data
- `update_user_data` - Create or update user data
- `remove_user_data` - Delete user data
- `manage_workspaces` - Create workspaces (via action="create")
- `ptc_agent` - Dispatch a research question to a workspace

You should call these tools directly instead of using ExecuteCode tool.

---

## Tool Reference

### Tool 1: get_user_data

Retrieve user data by entity type.

| Entity | Description | entity_id |
|--------|-------------|-----------|
| `all` | Complete user data (profile, preferences, watchlists with items, portfolio) | Not used |
| `profile` | User info (name, timezone, locale) | Not used |
| `preferences` | All preferences (risk, investment, agent) | Not used |
| `watchlists` | List of all watchlists | Not used |
| `watchlist_items` | Items in a specific watchlist | Optional watchlist_id |
| `portfolio` | All portfolio holdings | Not used |

```python
# Get complete user data (recommended at start of onboarding)
get_user_data(entity="all")
```

### Tool 2: update_user_data

Create or update user data (upsert semantics). Preference entities merge by default.

| Entity | Description |
|--------|-------------|
| `profile` | User info (name, timezone, locale, onboarding_completed) |
| `risk_preference` | Risk tolerance settings |
| `investment_preference` | Investment style settings |
| `agent_preference` | Agent behavior settings |
| `watchlist` | Create or update a watchlist |
| `watchlist_item` | Add or update item in watchlist |
| `portfolio_holding` | Add or update a portfolio holding |

All preference fields accept **any descriptive string**. Extra fields are allowed and persisted.

```python
# Good - rich context that helps future conversations
update_user_data(entity="risk_preference", data={
    "risk_tolerance": "Moderate - comfortable with market swings but avoids concentrated bets",
    "notes": "Lost money in 2022 tech crash, now prefers diversification"
})

# Bad - keyword with no context
update_user_data(entity="risk_preference", data={"risk_tolerance": "medium"})
```

### Tool 3: remove_user_data

Delete user data by entity type.

| Entity | Identifier fields |
|--------|-------------------|
| `watchlist` | `watchlist_id` or `name` |
| `watchlist_item` | `symbol` (+ optional `watchlist_id`) |
| `portfolio_holding` | `symbol` (+ optional `account_name`) |

### Tool 4: manage_workspaces (action="create")

Create the user's first workspace. This requires user approval — the user sees a card and must approve.

| Parameter | Type | Description |
|-----------|------|-------------|
| `action` | string | Must be `"create"` |
| `name` | string | Name for the workspace (e.g. "My Portfolio Analysis") |
| `description` | string | Brief description of the workspace purpose |

```python
manage_workspaces(action="create", name="My Portfolio Analysis", description="Track and analyze my stock portfolio")
```

Returns `{ success: true, workspace_id: "...", workspace_name: "..." }` on approval, or `"User declined workspace creation."` on rejection.

### Tool 5: ptc_agent

Dispatch a personalized research question to a workspace. This requires user approval — the user sees the question and can approve to start the analysis.

| Parameter | Type | Description |
|-----------|------|-------------|
| `question` | string | An actionable question related to the user's interests |
| `workspace_id` | string | The workspace ID (from `manage_workspaces` result) |

```python
ptc_agent(
    question="Analyze my NVDA position — what's the current technical setup and any upcoming catalysts I should watch for?",
    workspace_id="abc-123"
)
```

Returns `{ success: true, workspace_id: "...", thread_id: "...", status: "dispatched" }` on approval, or `"User declined research dispatch."` on rejection.

---

## What to Gather

### Stocks (Required, Structured)

At least one stock must be added to the watchlist or portfolio before onboarding can complete. Use the structured `watchlist_item` or `portfolio_holding` entities.

```python
# Watchlist item
update_user_data(entity="watchlist_item", data={
    "symbol": "NVDA", "notes": "Watching for AI chip growth"
})

# Portfolio holding
update_user_data(entity="portfolio_holding", data={
    "symbol": "AAPL", "quantity": 50, "average_cost": 175.0
})
```

### Risk & Investment Profile (Required, Flexible)

Gather enough context so future conversations can give personalized advice. At minimum, capture `risk_tolerance` on `risk_preference`. Topics to explore:

- **Risk comfort** - How much volatility can they handle? Any past experiences that shaped their risk view?
- **Investment style** - Growth, value, income, ESG? Any sectors they avoid or focus on?
- **Time horizon** - Short-term trading, long-term holding, or flexible?
- **Analysis preference** - Do they care most about growth metrics, valuation, competitive moat, or risk factors?

Store these as descriptive text across `risk_preference` and `investment_preference`:

```python
update_user_data(entity="risk_preference", data={
    "risk_tolerance": "Conservative - prioritizes capital preservation, uncomfortable with >10% drawdowns",
    "notes": "Nearing retirement in 5 years, shifting from growth to income"
})

update_user_data(entity="investment_preference", data={
    "company_interest": "Dividend-paying blue chips and REITs for income",
    "holding_period": "Long-term (5+ years), rarely sells",
    "analysis_focus": "Dividend sustainability, payout ratio, and balance sheet strength",
    "avoid_sectors": "Crypto, speculative biotech"
})
```

### Agent Preferences (Optional, Flexible)

How does the user want the agent to behave? Topics to explore:

- **Output style** - Quick bullet poin