add: complete first-success init flow

.changeset/init-first-success.md

@@ -0,0 +1,9 @@
+---
+"notcms": minor
+---
+
+Complete CLI initialization through the first schema pull. `notcms init` now
+uses existing credentials or browser login, ensures `notcms` is a direct and
+resolvable project dependency with the safely detected package manager, writes
+the generated schema, and prints a safe runnable first-query example while
+preserving the standalone `login`, `pull`, and `pull --check` commands.

README.md

@@ -34,7 +34,7 @@ NotCMS makes it easy to create a CMS, from Notion. It provides a type-safe TypeS
 - 🎯 **Simple API**: Clean and intuitive API for fetching content
 - 📝 **Notion as Backend**: Use Notion's user-friendly editor for content creation
 - 🔄 **Framework Agnostic**: Works with any JavaScript framework (Next.js, React, Vue, etc.)
-- 🛠️ **CLI Tools**: Includes notcms-kit for easy project setup and schema management
+- 🛠️ **CLI Tools**: Includes the NotCMS CLI for project setup, browser login, and schema management
 
 ## Getting Started
 
@@ -46,42 +46,37 @@ npm install notcms
 
 ### Usage
 
-#### 0. Set Up Environment Variables
-
-Create a `.env` file in your project root:
-
-```env
-NOTCMS_SECRET_KEY=your_secret_key
-NOTCMS_WORKSPACE_ID=your_workspace_id
-```
-
-You can get these values from the NotCMS Dashboard.
-
 #### 1. Initialize a Project
 
-NotCMS Kit provides command-line tools to streamline your workflow. You can use it directly with npx:
+Run the CLI directly with npx:
 
 ```bash
-npx notcms-kit init
+npx notcms init
 ```
 
-This will create a `notcms.config.json` file in your project root.
+This creates `notcms.config.json`. If credentials are missing, it opens browser
+login and saves `NOTCMS_SECRET_KEY` and `NOTCMS_WORKSPACE_ID` to `.env.local`.
+It ensures `notcms` is both a direct dependency and available to the project,
+offering either the detected package manager's install command or an add
+command without replacing an existing dependency spec. It then pulls the
+schema and prints a runnable first query example.
 
-#### 2. Define Your Schema
+#### 2. Refresh Your Schema
 
-The easiest way to define your schema is to use NotCMS Kit:
+Run the standalone pull command whenever your Notion database schema changes:
 
 ```bash
-npx notcms-kit pull
+npx notcms pull
 ```
 
-This will automatically fetch your database schema from Notion and generate a TypeScript schema file.
+This fetches your database schema from NotCMS and regenerates the configured TypeScript file.
 
 For reference, the generated schema will look something like this:
 
 ```ts
 // src/notcms/schema.ts
-import { Client, Schema } from "notcms";
+import { Client } from "notcms";
+import type { Schema } from "notcms";
 
 export const schema = {
   blog: {
@@ -91,7 +86,7 @@ export const schema = {
       description: "rich_text",
       published: "checkbox",
       thumbnails: "files",
-      // Run notcms-kit pull again when properties are updated
+      // Run notcms pull again when properties are updated
     },
   },
 } satisfies Schema;
@@ -142,7 +137,7 @@ If you encounter schema-related errors:
 
 1. Make sure your Notion database IDs are correct
 2. Verify that the property types match what's in your Notion database
-3. Try running `npx notcms-kit pull` to regenerate your schema
+3. Try running `npx notcms pull` to regenerate your schema
 
 ## Contributing
 

docs/en/cli-commands/init.mdx

@@ -1,58 +1,109 @@
 ---
 title: init
-description: Initialize a new NotCMS project
+description: Initialize NotCMS through browser login and the first schema pull
 ---
 
 ## Overview
 
-The `init` command sets up NotCMS in your project with interactive configuration.
+The `init` command takes a project from configuration through its first schema
+pull in one interactive flow.
 
 ```bash
-npx notcms-kit init
+npx notcms init
 ```
 
 ## What it does
 
-1. Creates `notcms.config.json` configuration file
-2. Checks environment variables in `.env`
+1. Prompts for the generated schema path
+2. Creates `notcms.config.json`
+3. Loads existing credentials from `.env`, `.env.local`, or `.dev.vars`
+4. If credentials are missing, offers browser login and saves them to `.env.local`
+5. Ensures `notcms` is both a direct project dependency and resolvable
+6. Pulls the schema automatically
+7. Prints a first query using the generated `nc` client
+
+If you decline browser login, the config file remains available and the command
+shows how to run `notcms login` later. It does not attempt to pull without
+credentials.
 
 ## Options
 
 | Option | Description | Default |
-|--------|-------------|---------|
-| `--env` | Environment file path | `[".env", ".env.local", ".dev.vars"]` |
+| --- | --- | --- |
+| `-e, --env <PATH>` | Comma-separated environment file paths | `.env,.env.local,.dev.vars` |
+
+## Interactive setup
 
-## Interactive Setup
+The command first asks where to save the generated schema:
 
-The command will guide you through:
+```text
+? Enter the path to save the schema (src/notcms/schema.ts)
+```
 
-### 1. Configuration
+When credentials are missing, it asks before starting browser login:
 
+```text
+? No NotCMS credentials found. Log in via browser to set them up now? (Y/n)
 ```
-? Schema file path: ./src/notcms/schema.ts
+
+The browser flow displays a device code, lets you select a workspace, and
+returns credentials to the CLI. The same credentials are used immediately for
+the automatic schema pull.
+
+`init` considers setup complete only when `notcms` is declared directly in
+`dependencies` or `devDependencies` and can be resolved from the target project.
+If it is declared but not installed, `init` offers the package manager's plain
+install command so local, workspace, and pinned dependency specs are preserved:
+
+```text
+pnpm install
+npm install
+yarn install
+bun install
 ```
 
+If it is not declared directly, `init` offers the corresponding add command:
+
+```text
+pnpm add notcms
+npm install notcms
+yarn add notcms
+bun add notcms
+```
+
+It shows the exact command and asks before running it, with yes as the default.
+On POSIX platforms the package manager is executed directly with shell mode
+disabled. On Windows, fixed validated arguments are passed through `cmd.exe` to
+invoke the package manager's `.cmd` shim; project-controlled text is never
+interpolated into that command. If installation is declined, fails, or the
+session is non-interactive, schema generation continues and the manual
+installation command is printed as the final action.
+
+The package manager is selected from a valid `packageManager` field, the closest
+lockfiles, or the invoking package manager. An invalid explicit field, or
+conflicting closest lockfiles that the invoking package manager cannot
+disambiguate, stops automatic installation. Schema generation still completes
+and `init` explains how to resolve the package-manager configuration manually.
+
 ## Examples
 
 ### Basic initialization
 
 ```bash
-npx notcms-kit init
+npx notcms init
 ```
 
-### Specify environment file path
-
-Use this if you already have `.env` configured:
+### Load credentials from a custom env file
 
 ```bash
-npx notcms-kit init --env .env.development
+npx notcms --env .env.development init
 ```
 
-## Troubleshooting
+## Next steps
 
-## Next Steps
+Import the `nc` client from the generated schema file and run the query printed
+by the command. When the Notion database structure changes, refresh it with:
 
-After initialization, you can:
-
-1. Start using the NotCMS client in your code
-2. Run `npx notcms-kit pull` to update your schema
+```bash
+npx notcms pull
+```

docs/en/cli-commands/pull.mdx

@@ -1,51 +1,66 @@
 ---
 title: pull
-description: Generate TypeScript schema from Notion databases
+description: Generate a TypeScript schema from registered Notion databases
 ---
 
 ## Overview
 
-The `pull` command generates or updates your TypeScript schema from Notion databases.
+The `pull` command generates or updates the configured TypeScript schema from
+the databases registered in your NotCMS workspace.
 
 ```bash
-npx notcms-kit pull
+npx notcms pull
 ```
 
+`init` already performs the first pull. Run this standalone command after a
+database or its properties change.
+
 ## What it does
 
-1. Fetches database structure and properties
-2. Generates TypeScript types
-3. Updates your schema file
+1. Loads `NOTCMS_SECRET_KEY` and `NOTCMS_WORKSPACE_ID`
+2. Fetches the current workspace schema from NotCMS
+3. Generates the configured schema module and its `nc` client
+4. Prints a query for the first database
 
 ## Options
 
 | Option | Description | Default |
-|--------|-------------|---------|
-| `--env` | Environment file path | `[".env", ".env.local", ".dev.vars"]` |
+| --- | --- | --- |
+| `-e, --env <PATH>` | Comma-separated environment file paths | `.env,.env.local,.dev.vars` |
+| `--check` | Check whether the schema is current without writing | `false` |
+
+`--check` exits with code 1 when the generated file is missing or out of date,
+which makes it suitable for CI/CD.
 
 ## Examples
 
-### Basic pull
+### Update the schema
+
+```bash
+npx notcms pull
+```
+
+### Load credentials from a custom env file
 
 ```bash
-npx notcms-kit pull
+npx notcms --env .env.development pull
 ```
 
-### Specify environment file path
+### Check without writing
 
 ```bash
-npx notcms-kit pull --env .env.development
+npx notcms pull --check
 ```
 
-## Generated Schema
+## Generated schema
 
-The command generates a fully typed schema:
+The command generates both the typed schema and a ready-to-use client:
 
 ```typescript
-import { Schema } from 'notcms';
+import { Client } from "notcms";
+import type { Schema } from "notcms";
 
 export const schema = {
-  // example
   blog: {
     id: "abc123...",
     properties: {
@@ -54,20 +69,20 @@ export const schema = {
       published: "checkbox",
       publishDate: "date",
       author: "relation",
-      tags: "multi_select"
-    }
-  }
+      tags: "multi_select",
+    },
+  },
 } satisfies Schema;
-```
 
-## Schema Updates
+export const nc = new Client({ schema });
+```
 
-When you update Notion databases, the pull command will update your schema.
+You can add a package script for later updates:
 
 ```json
 {
   "scripts": {
-    "schema:pull": "notcms-kit pull",
+    "schema:pull": "notcms pull"
   }
 }
-```
+```

docs/en/examples/nextjs.mdx

@@ -20,13 +20,12 @@ cd my-blog
 
 ```bash
 npm install notcms
-npm install -D notcms-kit
 ```
 
 ### 3. Initialize NotCMS
 
 ```bash
-npx notcms-kit init
+npx notcms init
 ```
 
 ### 4. Configure Next.js
@@ -430,4 +429,4 @@ NOTCMS_WORKSPACE_ID=your-workspace-id
   <Card title="Explore usage" icon="gear" href="/en/usage/list">
     Explore usage of NotCMS
   </Card>
-</CardGroup>
+</CardGroup>