feat: add web v2 docs and landing updates

AGENTS.md

@@ -21,10 +21,25 @@ APIs.
 - Keep JSDoc strings short and useful
 - while writing JSDoc follow it's standards, such as tags
 
+## References
+
+If you need to inspect source code of libraries or packages, prefer inspecting
+cloned source repositories when available, rather than library dist files.
+
+These directories already contain source checkouts for some packages:
+
+- `~/ref/fumadocs` - fumadocs framework / package.
+
 ## Behavior
 
 - When asked opinion questions, answer only. Do not edit code unless explicitly asked.
 - Never commit, push, or run database migrations unless explicitly asked.
+- Never create a partial commit from files that also contain unstaged changes.
+  If a requested commit overlaps dirty files, either commit the full intended
+  change or stop and ask. Do not rely on hooks stashing/hiding unstaged changes.
+- If a commit hook fails while hiding or restoring unstaged changes, stop
+  immediately and recover the user's unstaged work before retrying or committing
+  anything.
 - When generating migrations, always provide a name.
 - Never edit past migrations; create a new migration instead.
 - Never run "deploy" scripts to test anything, only if explicitly asked

apps/web/content/docs/concepts/cli.mdx → apps/web/content/docs/cli.mdx

@@ -5,9 +5,11 @@ description: Project initialization and plan management from the command line.
 
 PayKit includes a CLI tool for project setup, database migrations, and plan syncing. Install it once and use it throughout the project lifecycle.
 
-## `paykitjs init`
+## paykitjs init
 
-<PackageRun command="paykitjs init" />
+```bash
+npx paykitjs init
+```
 
 An interactive setup wizard that scaffolds everything you need to get started. It configures Stripe, then generates:
 
@@ -17,9 +19,11 @@ An interactive setup wizard that scaffolds everything you need to get started. I
 
 Run this once when starting a new project.
 
-## `paykitjs push`
+## paykitjs push
 
-<PackageRun command="paykitjs push" />
+```bash
+npx paykitjs push
+```
 
 The command you'll run most often. It does two things:
 
@@ -42,9 +46,11 @@ paykitjs push -y && next build
 
 This is similar to how you'd run database migrations on deploy. The `-y` flag skips the confirmation prompt.
 
-## `paykitjs status`
+## paykitjs status
 
-<PackageRun command="paykitjs status" />
+```bash
+npx paykitjs status
+```
 
 Validates your entire PayKit setup without making any changes. Useful when debugging a broken environment. It checks:
 
@@ -56,7 +62,9 @@ Validates your entire PayKit setup without making any changes. Useful when debug
 
 Pass `--throw` to exit with code 1 on failures, useful for CI pipelines:
 
-<PackageRun command="paykitjs status --throw" />
+```bash
+npx paykitjs status --throw
+```
 
 ## Telemetry
 

apps/web/content/docs/concepts/client.mdx → apps/web/content/docs/client.mdx

@@ -16,13 +16,13 @@ import type { paykit } from "@/server/paykit";
 export const paykitClient = createPayKitClient<typeof paykit>();
 ```
 
-The client resolves the current customer automatically on each request. You need `identify` configured on your server instance for this to work. See [customer identification](/docs/concepts/customers#customer-identification-client) for details.
+The client resolves the current customer automatically on each request. You need `identify` configured on your server instance for this to work. See [customer identification](/docs/customers#customer-identification-client) for details.
 
 ## Available methods
 
 The client exposes `subscribe` and `customerPortal`. Neither requires a `customerId` since it's resolved from the incoming request via `identify`.
 
-## `subscribe`
+## subscribe
 
 Works the same as the server-side `subscribe`, but without `customerId`. Returns `{ paymentUrl }`.
 
@@ -44,7 +44,7 @@ Works the same as the server-side `subscribe`, but without `customerId`. Returns
 </Button>
 ```
 
-## `customerPortal`
+## customerPortal
 
 Opens the provider's customer portal. Returns `{ url }`.
 
@@ -72,4 +72,4 @@ You can also pass an absolute URL like `https://example.com/custom`.
 
 ## Type safety
 
-The client infers available plan IDs directly from your server instance type. If you pass an invalid `planId`, TypeScript catches it at compile time. See [TypeScript](/docs/concepts/typescript) for more on how type inference works across the stack.
+The client infers available plan IDs directly from your server instance type. If you pass an invalid `planId`, TypeScript catches it at compile time. See [TypeScript](/docs/typescript) for more on how type inference works across the stack.

apps/web/content/docs/concepts/database.mdx → apps/web/content/docs/database.mdx

@@ -51,7 +51,9 @@ PayKit creates tables prefixed with `paykit_`. The key ones are:
 
 `paykitjs push` applies any pending migrations. Run it on initial setup and whenever you update your plan configuration.
 
-<PackageRun command="paykitjs push" />
+```bash
+npx paykitjs push
+```
 
 ## What's synced
 

apps/web/content/docs/get-started/installation.mdx → apps/web/content/docs/installation.mdx

@@ -1,28 +1,25 @@
 ---
 title: Installation
-description: Install PayKit, configure your billing instance, and mount the route handler in your app.
+description: how to install and configure PayKit in your app
 ---
 
+## Steps
+
 <Steps>
 
 <Step>
-## Install the package
+<StepTitle>Install the package</StepTitle>
 
 Let's start by adding PayKit to your project:
 
-
-
-<PackageInstall package="paykitjs" />
-
-<Callout type="info">
-  If you're using a separate client and server setup, make sure to install
-  the package in both apps.
-</Callout>
+```bash
+npm install paykitjs
+```
 
 </Step>
 
 <Step>
-## Create the PayKit instance
+<StepTitle>Create the PayKit instance</StepTitle>
 
 Create a file named `paykit.ts` anywhere in your app. 
 
@@ -42,7 +39,7 @@ export const paykit = createPayKit({
 </Step>
 
 <Step>
-## Configure Stripe
+<StepTitle>Configure Stripe</StepTitle>
 
 PayKit uses Stripe for billing. Pass your Stripe keys directly to the PayKit instance.
 
@@ -59,7 +56,7 @@ export const paykit = createPayKit({
 </Step>
 
 <Step>
-## Configure database
+<StepTitle>Configure database</StepTitle>
 
 PayKit needs a database to store billing state, such as subscriptions. You can create a separate database, or simply plug it into the app's own db.
 
@@ -77,13 +74,13 @@ export const paykit = createPayKit({
 ```
 
 <Callout type="info">
-  It works by creating a few tables prefixed with `paykit_`. You can learn more [here](/docs/concepts/database).
+  It works by creating a few tables prefixed with `paykit_`. You can learn more [here](/docs/database).
 </Callout>
 
 </Step>
 
 <Step>
-## Mount request handler
+<StepTitle>Mount request handler</StepTitle>
 
 To handle webhooks and client API requests, you need to set up a request handler on your server.
 
@@ -135,7 +132,7 @@ Create a new file or route in your framework's designated catch-all route handle
 </Step>
 
 <Step>
-## Create client instance
+<StepTitle>Create client instance</StepTitle>
 
 The client-side library helps you interact with the server. PayKit client sdk suitable for almost all modern frameworks, including React.
 
@@ -167,7 +164,7 @@ export const paykit = createPayKit({
 </Step>
 
 <Step>
-## Define your products
+<StepTitle>Define your products</StepTitle>
 
 Optionally. PayKit provides a code-first way to create your plans, and a very useful usage billing with `track()` and `report()` out of the box. 
 
@@ -221,21 +218,21 @@ export const paykit = createPayKit({
 </Step>
 
 <Step>
-## Push changes to DB
+<StepTitle>Push changes to DB</StepTitle>
 
 PayKit includes a CLI tool to keep your database in sync with your configuration.
 
-<PackageRun command="paykitjs push" />
+```bash
+npx paykitjs push
+```
 
 <Callout>
   This applies database migrations and syncs your plan definitions to provider's
   products.
 <br/>Run it once on setup, and every time after you change your products configuration.
-<br/>For production deployments, see the [CLI reference](/docs/concepts/cli#production-usage).
+<br/>For production deployments, see the [CLI reference](/docs/cli#production-usage).
 </Callout>
 
 </Step>
 
- __You're now ready to use PayKit in your app!__ 🚀
-
 </Steps>

apps/web/content/docs/get-started/index.mdx → apps/web/content/docs/introduction.mdx

@@ -10,5 +10,3 @@ PayKit is an embedded Stripe billing framework for TypeScript apps. It provides
 PayKit aims to be a complete billing framework. It provides a wide range of features out of the box and allows you to extend it with plugins.
 
 <Features />
-
-...and more to come!

apps/web/content/docs/meta.json

@@ -2,16 +2,24 @@
   "root": true,
   "pages": [
     "---Get Started---",
-    "get-started",
+    "introduction",
+    "installation",
+    "quickstart",
     "---Concepts---",
-    "concepts",
+    "plans-and-features",
+    "customers",
+    "subscriptions",
+    "entitlements",
+    "webhook-events",
+    "database",
+    "plugins",
+    "client",
+    "cli",
+    "typescript",
     "---Flows---",
-    "flows",
-    "---Providers---",
-    "providers",
+    "subscription-billing",
+    "metered-usage",
     "---Plugins---",
-    "plugins",
-    "---Guides---",
-    "guides"
+    "dashboard"
   ]
 }