notion-onboarding git:20260314.95c3228A

Immutable. This exact content is served forever at /api/v1/blob/fe4d2945684bab41.

---
name: notion-onboarding
description: >
  Discover and map a user's Notion workspace for the first time.
  Run this before any Notion workflows when no workspace state exists.
  Identifies key databases (projects, tasks, OKRs, home page, etc.)
  through guided discovery and saves them to a persistent state file
  so future interactions don't need to re-discover. Use when: first
  Notion setup, user says "set up Notion", "map my workspace",
  "onboard Notion", or when ~/.config/notion/workspace.json is missing.
---

# Notion Workspace Onboarding

Maps the user's Notion workspace and saves a state file that all future Notion skills read.

**State file:** `~/.config/notion/workspace.json`

## Step 0 — Check existing state

```bash
cat ~/.config/notion/workspace.json 2>/dev/null
```

If it exists: show the current mapping, ask the user if they want to update it or continue. If absent: proceed with full onboarding.

## Step 1 — Verify auth & get user

```bash
notion user me
```

Confirm the integration is working. Note the workspace name.

## Step 2 — Discover all accessible databases

```bash
notion inspect ws --compact
notion inspect ws --json
```

This lists all databases the integration can see. Present the list clearly to the user (name + ID).

## Step 3 — Guided identification

Ask the user to identify which databases correspond to each role. Be conversational — not all workspaces have all of these:

```
I found these databases in your workspace:
[list from step 2]

Can you tell me:
1. Which one is your main Tasks / To-do database? (where day-to-day work lives)
2. Which one is your Projects database? (higher-level work containers)
3. Do you have a Goals, OKRs, or Objectives database?
4. Is there a main Home or Dashboard page (not a database) I should know about?
5. Any other databases that are central to how you work? (e.g., CRM, Notes, Areas)
```

## Step 4 — Inspect each identified database

For each confirmed database, run:

```bash
notion inspect context <db_id>
notion inspect schema <db_id> --llm
```

Extract from the output:
- The exact `titleProp` name (the property of type `title`)
- The `statusProp` name and valid status values (if any)
- Key properties used for filtering (priority, assignee, due date, etc.)

## Step 5 — Build and save the state file

Write `~/.config/notion/workspace.json` following the schema in `references/state-schema.md`.

```bash
mkdir -p ~/.config/notion
# write the JSON file
```

Example minimal state:
```json
{
  "version": 1,
  "onboardedAt": "YYYY-MM-DD",
  "updatedAt": "YYYY-MM-DD",
  "workspace": { "name": "Acme" },
  "databases": {
    "tasks": {
      "id": "abc-123",
      "title": "Tasks",
      "titleProp": "Name",
      "statusProp": "Status",
      "statuses": ["Todo", "In Progress", "Done"]
    }
  }
}
```

## Step 6 — Confirm with user

Show a human-readable summary of what was saved. Ask: "Does this look right? Anything to adjust?"

Apply any corrections, save the final file.

## After onboarding

Tell the user: "Your workspace is now mapped. Any Notion task I do will use these databases by default — no need to look up IDs. Run this onboarding again anytime to update."

For full state schema see: `references/state-schema.md`