feat: request read-data-schema + notebook OAuth scopes and document the scope set

.claude/skills/wizard-development/references/MAINTAINING-SKILLS.md

@@ -76,6 +76,10 @@ Skills carry a `version` field in their frontmatter. Bump it as follows:
 
 When you bump a version, also bump the `version` in any reference file that shipped as part of the change. Version churn is itself a maintenance signal — a skill that's bumped majors three times in a year is probably teaching an abstraction that hasn't stabilized.
 
+## Keep the README's OAuth scopes in sync with `constants.ts`
+
+`WIZARD_OAUTH_SCOPES` in `src/lib/constants.ts` is the source of truth. When you add or remove a scope there, update the README's "OAuth Scopes" list in the same change, and confirm the scope is granted on the OAuth application in every region (US / EU) or the matching tool calls fail at runtime.
+
 ## The maintainer's question
 
 When you finish updating a skill, ask: "If a contributor with no prior context follows this exactly, will they produce work the architecture currently asks for?" Not "will they produce something that works" — works is necessary but not sufficient. The skill should produce idiomatic output, not just functional output. If following the skill produces a bin.ts edit that the registry would have done automatically, the skill is asking for work that should be automatic.

README.md

@@ -106,6 +106,28 @@ The following CLI arguments are available:
 | `--api-key`       | PostHog personal API key (phx_xxx) for authentication            | string  |         |                                                      | `POSTHOG_WIZARD_API_KEY`       |
 
 
+# OAuth Scopes
+
+`npx @posthog/wizard` authenticates via OAuth, requesting:
+
+| Scope                       | Why                                                          |
+| --------------------------- | ----------------------------------------------------------- |
+| `user:read`                 | Identify the user for analytics + agent context             |
+| `project:read`              | Look up the provisioned project and its API token           |
+| `llm_gateway:read`          | Authenticate the agent's LLM calls to the gateway           |
+| `dashboard:write`           | Create the onboarding dashboard                             |
+| `insight:write`             | Create the onboarding insights                             |
+| `query:read`                | Run HogQL queries when the agent needs data                 |
+| `event_definition:read`     | Read event schema (`read-data-schema` MCP tool)             |
+| `property_definition:read`  | Read property schema (`read-data-schema` MCP tool)          |
+| `health_issue:read`         | Power `wizard doctor` health checks                         |
+| `wizard_session:read`       | List / retrieve / stream wizard sessions                    |
+| `wizard_session:write`      | Stream run state to `/api/projects/{id}/wizard/sessions/`   |
+| `notebook:write`            | Create / edit notebooks via the notebooks MCP tools         |
+
+Grant every scope on the PostHog OAuth app in both regions (US / EU) or the matching tool calls fail. Source of truth: `WIZARD_OAUTH_SCOPES` in `src/lib/constants.ts` — keep this list in sync.
+
+
 # CI Mode
 
 > ⚠️ **CI mode is not currently supported in published builds.** PostHog's LLM

src/lib/constants.ts

@@ -124,15 +124,25 @@ export const WIZARD_PROVISIONING_SCOPES = [
  * Scopes the wizard requests during the OAuth login flow. Superset of
  * `WIZARD_PROVISIONING_SCOPES` with scopes that only apply to the login
  * path and are not in the provisioning allowlist:
- * - health_issue:read     used by `wizard doctor`
- * - wizard_session:read   list / retrieve / stream sessions
- * - wizard_session:write  stream run state to /api/projects/{id}/wizard/sessions/
+ * - health_issue:read        used by `wizard doctor`
+ * - wizard_session:read      list / retrieve / stream sessions
+ * - wizard_session:write     stream run state to /api/projects/{id}/wizard/sessions/
+ * - notebook:write           create / edit notebooks via the notebooks MCP tools
+ * - event_definition:read    read event schema via the read-data-schema MCP tool
+ * - property_definition:read read property schema via the read-data-schema MCP tool
+ *
+ * Each scope here must also be granted on the PostHog OAuth application in
+ * every region (US / EU). When this list changes, update the "OAuth Scopes"
+ * section of README.md to match — it documents this constant for operators.
  */
 export const WIZARD_OAUTH_SCOPES = [
   ...WIZARD_PROVISIONING_SCOPES,
   'health_issue:read',
   'wizard_session:read',
   'wizard_session:write',
+  'notebook:write',
+  'event_definition:read',
+  'property_definition:read',
 ] as const;
 
 // ── Wizard run / variants ───────────────────────────────────────────