@developer.krd/discord-dashboard 0.1.2 → 0.1.5

package/README.md

@@ -1,673 +1,294 @@
 # @developer.krd/discord-dashboard
 
-Advanced plug-and-play Discord dashboard package for bot developers.
-
-- No frontend coding required.
-- Built-in Discord OAuth2 login flow.
-- Ready-made dashboard UI.
-- Guild access control.
-- Discord-like server rail with user/guild avatars.
-- Invite-on-click flow for guilds where bot is not installed.
-- Extensible plugin panels + server actions.
-- Flexible Home Builder with editable sections and save actions.
-- Fluent designer API for setup/user/guild dashboard separation.
-- Fluent `.setupDesign(...)` API for dashboard main colors.
-- Home section width presets: `100` (default), `50`, `33`, `20`.
-- Built-in Discord utility helpers in actions (`getChannel`, `getRole`, `getGuildRoles`, etc.).
-- Overview-first tabs with separate module categories (like pets, permissions, etc.).
-- Website autocomplete field types for role/channel selection with filtering.
-
-## Install
+An advanced, plug-and-play Discord dashboard package for bot developers.
 
-```bash
-npm install @developer.krd/discord-dashboard
-```
+Build a full web dashboard for your bot without writing frontend code. The package provides built-in rendering, Discord OAuth2 flow, and adapters for Express, Elysia, and Fastify.
 
-## Ways to Create a Dashboard
+## ✨ Features
 
-You can build your dashboard in multiple styles depending on your project:
+- **No frontend app required:** Server-rendered dashboard UI with built-in client script.
+- **Multiple adapters:** `createExpressAdapter`, `createElysiaAdapter`, `createFastifyAdapter`.
+- **Discord OAuth2 flow:** Login, callback exchange, and session persistence.
+- **Theming and layouts:** Built-in layouts/themes (`default`, `compact`, `shadcn-magic`) plus custom renderers.
+- **Home & plugin builders:** Dynamic sections/panels with typed action handlers.
+- **Discord helper API:** Role/channel/member fetch & search helpers inside action context.
+- **TypeScript-first:** Strict typed options, context, fields, and plugin contracts.
 
-1. **Direct Config (`createDashboard`)**
-  - Fastest way for simple dashboards.
-  - Use `home`, `plugins`, and `getOverviewCards` directly.
+---
 
-2. **Fluent Designer (`createDashboardDesigner`)**
-  - Best for larger bots and modular structure.
-  - Use `setupCategory`, `userCategory`, `guildCategory`, and `onHomeAction`.
+## 🎨 Templates
 
-3. **Discord-like Lifecycle Pages**
-  - Use `setupPage + onLoad/onSave` (also `onload/onsave`).
-  - Great when pages need dynamic loading and per-page save handlers.
+Browse built-in templates and screenshot placeholders in [src/templates/templates.md](src/templates/templates.md).
 
-4. **Template-based UI/UX**
-  - Choose built-in template (`default`, `compact`) with `uiTemplate`.
-  - Register custom full HTML templates with `uiTemplates` or Designer `addTemplate`.
+---
 
-## Language Support
+## 📦 Installation
 
-This package supports TypeScript, JavaScript (`.js`), and ESM JavaScript (`.mjs`).
+```bash
+npm install @developer.krd/discord-dashboard discord.js
+```
 
-TypeScript / ESM:
+Install only the server stack you use:
 
-```ts
-import { createDashboard } from "@developer.krd/discord-dashboard";
-```
+```bash
+# Express
+npm install express express-session
 
-JavaScript ESM (`.mjs`):
+# Elysia
+npm install elysia
 
-```js
-import { createDashboard } from "@developer.krd/discord-dashboard";
+# Fastify
+npm install fastify @fastify/cookie @fastify/session
 ```
 
-JavaScript CommonJS (`.js` with `require`):
+Node.js `>=18` is required.
 
-```js
-const { createDashboard } = require("@developer.krd/discord-dashboard");
-```
+---
 
-## Quick Start
+## 🚀 Quick Start (Express)
 
 ```ts
 import express from "express";
-import { createDashboard } from "@developer.krd/discord-dashboard";
+import { Client, GatewayIntentBits } from "discord.js";
+import { createExpressAdapter } from "@developer.krd/discord-dashboard";
 
 const app = express();
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
 
-const dashboard = createDashboard({
+createExpressAdapter({
   app,
+  client,
   basePath: "/dashboard",
-  dashboardName: "KRD Bot Control",
+  dashboardName: "My Bot Control",
+
   botToken: process.env.DISCORD_BOT_TOKEN!,
   clientId: process.env.DISCORD_CLIENT_ID!,
   clientSecret: process.env.DISCORD_CLIENT_SECRET!,
   redirectUri: "http://localhost:3000/dashboard/callback",
   sessionSecret: process.env.DASHBOARD_SESSION_SECRET!,
-  ownerIds: ["123456789012345678"],
+
+  uiTemplate: "shadcn-magic",
+  uiTheme: "shadcn-magic",
+
   getOverviewCards: async (context) => [
     {
       id: "uptime",
       title: "Bot Uptime",
       value: `${Math.floor(process.uptime() / 60)} min`,
-      subtitle: `Logged in as ${context.user.username}`
+      subtitle: `Logged in as ${context.user.username}`,
     },
     {
       id: "guilds",
-      title: "Guilds",
-      value: context.guilds.length
-    }
+      title: "Manageable Guilds",
+      value: context.guilds.length,
+    },
   ],
+
   home: {
     async getSections(context) {
       return [
         {
           id: "welcome",
           title: "Welcome Settings",
+          categoryId: "general",
           description: context.selectedGuildId ? "Guild-specific setup" : "User-level setup",
           fields: [
             { id: "enabled", label: "Enable Welcome", type: "boolean", value: true },
-            { id: "channel", label: "Channel ID", type: "text", value: "" },
-            { id: "message", label: "Message", type: "textarea", value: "Welcome to the server!" }
+            { id: "message", label: "Message", type: "textarea", value: "Welcome to the server!" },
           ],
-          actions: [{ id: "saveWelcome", label: "Save", variant: "primary" }]
-        }
+          actions: [{ id: "saveWelcome", label: "Save", variant: "primary" }],
+        },
       ];
     },
     actions: {
       async saveWelcome(context, payload) {
-        console.log("Saving", context.selectedGuildId, payload.values);
+        console.log("Saving data for", context.selectedGuildId, payload.values);
         return { ok: true, message: "Welcome settings saved", refresh: false };
-      }
-    }
-  },
-  plugins: [
-    {
-      id: "moderation",
-      name: "Moderation",
-      description: "Live moderation controls",
-      async getPanels(context) {
-        return [
-          {
-            id: "status",
-            title: "Status",
-            fields: [
-              { label: "Selected Guild", value: context.selectedGuildId ?? "None" },
-              { label: "Access", value: "Ready" }
-            ],
-            actions: [
-              { id: "sync", label: "Sync Rules", variant: "primary" }
-            ]
-          }
-        ];
       },
-      actions: {
-        async sync() {
-          return { ok: true, message: "Moderation rules synced.", refresh: true };
-        }
-      }
-    }
-  ]
+    },
+  },
 });
 
+await client.login(process.env.DISCORD_BOT_TOKEN!);
 app.listen(3000, () => {
-  console.log("Dashboard: http://localhost:3000/dashboard");
+  console.log("Dashboard live at: http://localhost:3000/dashboard");
 });
 ```
 
-## Fluent Dashboard Designer (Recommended)
-
-Use a clean modular structure instead of putting all configuration in one place:
-
-- `setup(...)` for important defaults
-- `setupDesign(...)` for dashboard colors (`primary`, `bg`, `rail`, `panel`, etc.)
-- `setupCategory(...)` for one-time setup UI
-- `userCategory(...)` for user dashboard sections
-- `guildCategory(...)` for server dashboard sections
-- `onHomeAction(...)` for save handlers
+## 🚀 Quick Start (Elysia)
 
 ```ts
-import { createDashboard, createDashboardDesigner } from "@developer.krd/discord-dashboard";
+import { Elysia } from "elysia";
+import { Client, GatewayIntentBits } from "discord.js";
+import { createElysiaAdapter } from "@developer.krd/discord-dashboard";
 
-const designer = createDashboardDesigner({
-  app,
-  botToken,
-  clientId,
-  clientSecret,
-  redirectUri,
-  sessionSecret
-})
-  .setup({ ownerIds: ["123"], botInvitePermissions: "8" })
-  .setupDesign({ primary: "#4f46e5", rail: "#181a20", panel: "#2f3136" })
-  .userCategory("pets", "Pets", (category) => {
-    category.section({
-      id: "pets-user",
-      title: "User Pets",
-      width: 50,
-      fields: [{ id: "petName", label: "Pet Name", type: "text", value: "Luna" }],
-      actions: [{ id: "saveUserPets", label: "Save", variant: "primary" }]
-    });
-  })
-  .guildCategory("pets", "Pets", (category) => {
-    category.section({
-      id: "pets-guild",
-      title: "Guild Pets",
-      fields: [{ id: "petsChannelId", label: "Pets Channel", type: "text", value: "" }],
-      actions: [{ id: "saveGuildPets", label: "Save", variant: "primary" }]
-    });
-  })
-  .onHomeAction("saveGuildPets", async (context, payload) => {
-    const channelId = String(payload.values.petsChannelId ?? "");
-    const channel = await context.helpers.getChannel(channelId);
-    if (!channel) return { ok: false, message: "Channel not found" };
-    return { ok: true, message: "Saved", refresh: true };
-  });
-
-createDashboard({ ...designer.build() });
-```
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+const app = new Elysia();
 
-## Discord-Style Flexible Flow (`onLoad` / `onSave`)
+createElysiaAdapter({
+  app,
+  client,
+  basePath: "/dashboard",
+  dashboardName: "My Bot Control",
 
-You can also build pages in a Discord-client-like style:
+  botToken: process.env.DISCORD_BOT_TOKEN!,
+  clientId: process.env.DISCORD_CLIENT_ID!,
+  clientSecret: process.env.DISCORD_CLIENT_SECRET!,
+  redirectUri: "http://localhost:3000/dashboard/callback",
+  sessionSecret: process.env.DASHBOARD_SESSION_SECRET!,
 
-```ts
-import { createDashboard, createDashboardDesigner } from "@developer.krd/discord-dashboard";
+  uiTemplate: "shadcn-magic",
+  uiTheme: "shadcn-magic",
+});
 
-const dashboard = createDashboardDesigner({
-  app,
-  botToken,
-  clientId,
-  clientSecret,
-  redirectUri,
-  sessionSecret
-})
-  .setupPage({
-    id: "profile",
-    title: "Profile",
-    scope: "user",
-    width: 50,
-    fields: [
-      { id: "bio", label: "Bio", type: "textarea", value: "" },
-      { id: "notifications", label: "Notifications", type: "boolean", value: true }
-    ]
-  })
-  .onLoad("profile", async (ctx, section) => ({
-    ...section,
-    description: `Loaded for ${ctx.user.username}`
-  }))
-  .onSave("profile", async (ctx, payload) => {
-    console.log("save profile", ctx.user.id, payload.values);
-    return { ok: true, message: "Profile saved", refresh: true };
-  });
-
-createDashboard({ ...dashboard.build() });
+await client.login(process.env.DISCORD_BOT_TOKEN!);
+app.listen({ port: 3000 });
+console.log("Dashboard live at: http://localhost:3000/dashboard");
 ```
 
-Notes:
+## 🚀 Quick Start (Fastify)
 
-- `setupPage(...)` creates a page/section with optional fields/actions.
-- `onLoad(pageId, handler)` (or lowercase `onload`) runs when that page is resolved.
-- `onSave(pageId, handler)` (or lowercase `onsave`) auto-adds a default **Save** action if missing.
+```ts
+import Fastify from "fastify";
+import fastifyCookie from "@fastify/cookie";
+import fastifySession from "@fastify/session";
+import { Client, GatewayIntentBits } from "discord.js";
+import { createFastifyAdapter } from "@developer.krd/discord-dashboard";
+
+const fastify = Fastify({ logger: true });
+const client = new Client({ intents: [GatewayIntentBits.Guilds] });
+
+await fastify.register(fastifyCookie);
+await fastify.register(fastifySession, {
+  secret: process.env.DASHBOARD_SESSION_SECRET!,
+  cookie: { secure: false },
+});
 
-## Designer API Reference
+createFastifyAdapter(fastify, {
+  client,
+  basePath: "/dashboard",
+  dashboardName: "My Bot Control",
 
-`createDashboardDesigner(baseOptions)` supports:
+  botToken: process.env.DISCORD_BOT_TOKEN!,
+  clientId: process.env.DISCORD_CLIENT_ID!,
+  clientSecret: process.env.DISCORD_CLIENT_SECRET!,
+  redirectUri: "http://localhost:3000/dashboard/callback",
+  sessionSecret: process.env.DASHBOARD_SESSION_SECRET!,
 
-- `setup({...})`: core setup (`ownerIds`, invite permissions/scopes, name/path, `uiTemplate`).
-- `setupDesign({...})`: color/theme tokens for built-in templates.
-- `setupCategory(id, label, build)`
-- `userCategory(id, label, build)`
-- `guildCategory(id, label, build)`
-- `onHomeAction(actionId, handler)`
-- `setupPage({...})`: page-style section definition.
-- `onLoad(pageId, handler)` + alias `onload(...)`.
-- `onSave(pageId, handler)` + alias `onsave(...)`.
-- `addTemplate(templateId, renderer)` + `useTemplate(templateId)`.
-- `build()`: returns full `DashboardOptions` for `createDashboard(...)`.
+  uiTemplate: "shadcn-magic",
+  uiTheme: "shadcn-magic",
+});
 
-## UI Template System (for package developers)
+await client.login(process.env.DISCORD_BOT_TOKEN!);
+await fastify.listen({ port: 3000, host: "0.0.0.0" });
+console.log("Dashboard live at: http://localhost:3000/dashboard");
+```
 
-You can ship multiple UI/UX templates and choose one by id.
+---
 
-Built-in templates:
+## 🔌 Adapter Notes
 
-- `default`
-- `compact`
+- **Express:** `createExpressAdapter(options)`
+- **Elysia:** `createElysiaAdapter(options)`
+- **Fastify:** `createFastifyAdapter(fastify, options)`
 
-Use built-in compact mode:
+For Fastify, you must register `@fastify/cookie` and `@fastify/session` before wiring the adapter, since dashboard routes read/write `request.session`.
 
-```ts
-createDashboard({
-  app,
-  botToken,
-  clientId,
-  clientSecret,
-  redirectUri,
-  sessionSecret,
-  uiTemplate: "compact"
-});
-```
+---
 
-Direct `createDashboard(...)` usage:
+## 🛠️ Extensible Plugins
 
 ```ts
-import { createDashboard } from "@developer.krd/discord-dashboard";
-
-createDashboard({
-  app,
-  botToken,
-  clientId,
-  clientSecret,
-  redirectUri,
-  sessionSecret,
-  uiTemplate: "glass",
-  uiTemplates: {
-    glass: ({ dashboardName, basePath }) => `
-      <!doctype html>
-      <html>
-        <head><title>${dashboardName}</title></head>
-        <body>
-          <h1>${dashboardName}</h1>
-          <p>Custom template active. Base path: ${basePath}</p>
-        </body>
-      </html>
-    `
-  }
+createExpressAdapter({
+  // ... core config ...
+  plugins: [
+    {
+      id: "runtime",
+      name: "System Runtime",
+      description: "Live bot diagnostics",
+      getPanels: async () => [
+        {
+          id: "runtime-status",
+          title: "Diagnostics",
+          fields: [
+            { label: "Logged in as", value: client.user?.tag ?? "Unknown" },
+            { label: "Uptime", value: `${Math.floor(process.uptime())}s` },
+          ],
+          actions: [{ id: "refreshRuntime", label: "Refresh", variant: "primary", collectFields: false }],
+        },
+      ],
+      actions: {
+        refreshRuntime: async () => ({ ok: true, message: "Data refreshed", refresh: true }),
+      },
+    },
+  ],
 });
 ```
 
-Designer usage:
+---
 
-```ts
-const designer = createDashboardDesigner({
-  app,
-  botToken,
-  clientId,
-  clientSecret,
-  redirectUri,
-  sessionSecret
-})
-  .addTemplate("glass", ({ dashboardName }) => `<html><body><h1>${dashboardName}</h1></body></html>`)
-  .useTemplate("glass");
-
-createDashboard({ ...designer.build() });
-```
-
-Template renderer signature:
+## 🧩 Built-in Helper Functions
 
-- Input: `{ dashboardName, basePath, setupDesign }`
-- Output: full HTML string (complete document/template, not only CSS overrides)
-
-Template files in this package are organized under [src/templates](src/templates).
-
-## Built-in Helper Functions
-
-Available in `context.helpers` inside home/plugin actions:
+Inside `home.actions` and `plugins.actions`, use `context.helpers`:
 
+- `getGuildIconUrl(guildId, iconHash)`
+- `getUserAvatarUrl(userId, avatarHash)`
 - `getChannel(channelId)`
 - `getGuildChannels(guildId)`
+- `searchGuildChannels(guildId, query, options?)`
 - `getRole(guildId, roleId)`
 - `getGuildRoles(guildId)`
+- `searchGuildRoles(guildId, query, options?)`
+- `searchGuildMembers(guildId, query, options?)`
 - `getGuildMember(guildId, userId)`
 
-## Plugin Scopes and Form Actions
-
-Plugins can now be separated by target dashboard scope:
+---
 
-- `scope: "user"` → shown only on user dashboard
-- `scope: "guild"` → shown only on guild dashboard
-- `scope: "both"` (default) → shown on both
+## 🔍 Lookup Fields
 
-Plugin action forms:
-
-- Mark a panel field with `editable: true` and set `type` (text, textarea, select, boolean, role-search, channel-search, member-search, url).
-- Use `type: "string-list"` for drag-and-drop ordered labels (great for poll buttons).
-- Set action `collectFields: true` to send panel values in the action payload.
-- Action body format:
-  - `panelId`
-  - `values` (contains selected lookup objects and typed field values)
-
-## Lookup Field Types (Website UI)
-
-Use these in home sections to let users type and select Discord objects:
-
-- `role-search`: type role name, get matching roles, select one, submit role object data.
-- `channel-search`: type channel name, get matching channels with filters, select one, submit channel object data.
-
-Lookup filters:
-
-- `limit`
-- `minQueryLength`
-- `includeManaged` (roles)
-- `nsfw` (channels)
-- `channelTypes` (channels)
-
-## Required Discord OAuth2 Setup
-
-1. Open the Discord Developer Portal for your application.
-2. In OAuth2 settings, add your redirect URI (example: `http://localhost:3000/dashboard/callback`).
-3. Make sure scopes include at least `identify guilds`.
-4. Use your app `CLIENT_ID` and `CLIENT_SECRET` in `createDashboard()`.
-
-## API Reference
-
-### `createDashboard(options)`
-
-Creates and mounts a complete dashboard with OAuth2 + UI.
-
-Key `options`:
-
-- `app?`: existing Express app instance.
-- `basePath?`: dashboard route prefix. Default: `/dashboard`.
-- `dashboardName?`: topbar/dashboard title.
-- `setupDesign?`: override CSS theme variables (`primary`, `bg`, `rail`, `panel`, etc.).
-- `uiTemplate?`: template id to render (`default`, `compact`, or your custom id).
-- `uiTemplates?`: custom full-HTML template renderers.
-- `botToken`: bot token (for your own plugin logic).
-- `clientId`, `clientSecret`, `redirectUri`: Discord OAuth2 credentials.
-- `sessionSecret`: secret for encrypted session cookies.
-- `sessionName?`, `sessionMaxAgeMs?`: cookie/session configuration.
-- `scopes?`: OAuth scopes for login (default includes `identify guilds`).
-- `botInvitePermissions?`, `botInviteScopes?`: controls invite link generation.
-- `ownerIds?`: optional allow-list of Discord user IDs.
-- `guildFilter?`: async filter for guild visibility.
-- `getOverviewCards?`: dynamic card resolver.
-- `home?`: configurable homepage sections + save handlers.
-- `home.getOverviewSections?`: add overview-scoped sections.
-- `home.getCategories?`: define category tabs (setup/user/guild).
-- `home.getSections?`: define sections for active scope.
-- `home.actions?`: action handlers for section actions.
-- `plugins?`: plugin definitions with panels/actions.
-- `trustProxy?`: proxy configuration when running behind reverse proxies.
-- `host?`, `port?`: only used when you call `dashboard.start()` without passing `app`.
-
-Return value:
-
-- `app`: Express app instance.
-- `start()`: starts internal server only if you didn’t pass `app`.
-- `stop()`: stops internal server.
-
-## Security Notes
-
-- Uses secure HTTP-only session cookies.
-- Uses OAuth2 `state` validation for callback integrity.
-- Use HTTPS in production and strong `sessionSecret`.
-- Optionally set trusted proxy with `trustProxy`.
-
-## Local Development
-
-```bash
-npm install
-npm run typecheck
-npm run build
-```
-
-Run the example app:
-
-```bash
-cp .env.example .env
-# Fill .env with your Discord app credentials first
-npm run example
-```
-
-Run the real-bot entry directly:
-
-```bash
-npm run real-bot
-```
-
-## Real Bot Code Examples
-
-The real-bot sample is in:
-
-- [examples/real-bot/main.ts](examples/real-bot/main.ts)
-- [examples/real-bot/dashboard.ts](examples/real-bot/dashboard.ts)
-- [examples/real-bot/commands](examples/real-bot/commands)
-- [examples/real-bot/events](examples/real-bot/events)
-
-### Slash command example (`/ping`)
+Field types include `role-search`, `channel-search`, and `member-search`, and you can provide lookup options in field config (for limits and filters).
 
 ```ts
-import { SlashCommandBuilder } from "discord.js";
-import type { BotCommand } from "../types";
-
-const command: BotCommand = {
-  data: new SlashCommandBuilder().setName("ping").setDescription("Check latency"),
-  async execute(context, interaction) {
-    const wsPing = context.client.ws.ping;
-    const start = interaction.createdTimestamp;
-    const response = await interaction.reply({ content: "Pinging...", fetchReply: true });
-    const apiPing = response.createdTimestamp - start;
-    await interaction.editReply(`🏓 Pong! WS: ${wsPing}ms | API: ${apiPing}ms`);
-  }
-};
-
-export default command;
+{
+  id: "logChannel",
+  label: "Logs",
+  type: "channel-search",
+  lookup: {
+    limit: 5,
+    channelTypes: [0, 5],
+  },
+}
 ```
 
-### Event example (`interactionCreate`)
+---
 
-```ts
-import type { BotEvent } from "../types";
+## 📚 API Reference
 
-const event: BotEvent<"interactionCreate"> = {
-  name: "interactionCreate",
-  async execute(context, interaction) {
-    if (!interaction.isChatInputCommand()) return;
+`DashboardOptions` includes:
 
-    const command = context.commands.get(interaction.commandName);
-    if (!command) {
-      await interaction.reply({ content: "Command not found.", ephemeral: true });
-      return;
-    }
+- OAuth/session config (`clientId`, `clientSecret`, `redirectUri`, `sessionSecret`, ...)
+- Dashboard presentation (`dashboardName`, `basePath`, `uiTemplate`, `uiTheme`, `setupDesign`)
+- Dynamic content (`getOverviewCards`, `home`, `plugins`)
+- Runtime dependencies (`client`, optional framework app where supported)
 
-    await command.execute(context, interaction);
-  }
-};
+Also exported:
 
-export default event;
-```
+- `DashboardEngine`
+- `DashboardDesigner`
 
-### Dashboard creation example (classic + flexible pages)
+---
 
-```ts
-createDashboard({
-  app,
-  botToken,
-  clientId,
-  clientSecret,
-  redirectUri,
-  sessionSecret,
-  uiTemplate: "compact",
-  home: {
-    async getSections(ctx) {
-      return [{
-        id: "classic",
-        title: "Classic Home",
-        scope: ctx.selectedGuildId ? "guild" : "user",
-        fields: [{ id: "mode", label: "Mode", type: "text", value: ctx.selectedGuildId ? "Guild" : "User", readOnly: true }]
-      }];
-    }
-  }
-});
+## 🔒 Required Discord OAuth2 Setup
 
-// Flexible style:
-createDashboard({
-  ...createDashboardDesigner({ app, botToken, clientId, clientSecret, redirectUri, sessionSecret })
-    .setupPage({ id: "profile", title: "Profile", scope: "user", fields: [{ id: "bio", label: "Bio", type: "textarea" }] })
-    .onLoad("profile", async (ctx, section) => ({ ...section, description: `Loaded for ${ctx.user.username}` }))
-    .onSave("profile", async () => ({ ok: true, message: "Saved", refresh: true }))
-    .build()
-});
-```
-
-While using the real-bot example, live edits and bot activity are persisted to [examples/dashboard-demo-state.json](examples/dashboard-demo-state.json).
-
-## Common Recipes
-
-### Welcome System (Guild Home Section)
-
-```ts
-import { createDashboard, createDashboardDesigner } from "@developer.krd/discord-dashboard";
-
-const designer = createDashboardDesigner({ app, botToken, clientId, clientSecret, redirectUri, sessionSecret })
-  .guildCategory("welcome", "Welcome", (category) => {
-    category.section({
-      id: "welcome-settings",
-      title: "Welcome Settings",
-      fields: [
-        { id: "enabled", label: "Enabled", type: "boolean", value: true },
-        { id: "channel", label: "Welcome Channel", type: "channel-search", placeholder: "Search channel..." },
-        { id: "message", label: "Message", type: "textarea", value: "Welcome to the server, {user}!" }
-      ],
-      actions: [{ id: "saveWelcome", label: "Save Welcome", variant: "primary" }]
-    });
-  })
-  .onHomeAction("saveWelcome", async (context, payload) => {
-    if (!context.selectedGuildId) return { ok: false, message: "Select a guild first" };
-    const channel = payload.values.channel as { id?: string; name?: string } | null;
-    return { ok: true, message: `Welcome config saved for ${context.selectedGuildId} in #${channel?.name ?? "unknown"}` };
-  });
-
-createDashboard({ ...designer.build() });
-```
+1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).
+2. Open your Application → **OAuth2**.
+3. Add your redirect URI (example: `http://localhost:3000/dashboard/callback`).
+4. Use your `CLIENT_ID` and `CLIENT_SECRET` in dashboard config.
 
-### Moderation Toggles + Limits
+Use a strong `sessionSecret` in production and serve behind HTTPS.
 
-```ts
-home: {
-  getSections: async (context) => [
-    {
-      id: "moderation-core",
-      title: "Moderation",
-      scope: "guild",
-      fields: [
-        { id: "antiSpam", label: "Anti-Spam", type: "boolean", value: true },
-        { id: "antiLinks", label: "Block Suspicious Links", type: "boolean", value: true },
-        { id: "maxMentions", label: "Max Mentions", type: "number", value: 5 }
-      ],
-      actions: [{ id: "saveModeration", label: "Save Moderation", variant: "primary" }]
-    }
-  ],
-  actions: {
-    saveModeration: async (_context, payload) => ({
-      ok: true,
-      message: `Saved moderation: antiSpam=${Boolean(payload.values.antiSpam)}, maxMentions=${Number(payload.values.maxMentions ?? 0)}`,
-      refresh: true
-    })
-  }
-}
-```
-
-### Ticket Panel Builder (Plugin)
-
-```ts
-plugins: [
-  {
-    id: "tickets",
-    name: "Tickets",
-    scope: "guild",
-    getPanels: async () => [
-      {
-        id: "ticket-panel",
-        title: "Ticket Panel",
-        fields: [
-          { id: "targetChannel", label: "Target Channel", type: "channel-search", editable: true, value: "" },
-          { id: "title", label: "Embed Title", type: "text", editable: true, value: "Need help?" },
-          { id: "description", label: "Embed Description", type: "textarea", editable: true, value: "Click below to open a ticket." },
-          { id: "buttonLabel", label: "Button Label", type: "text", editable: true, value: "Open Ticket" }
-        ],
-        actions: [{ id: "publishTicketPanel", label: "Publish", variant: "primary", collectFields: true }]
-      }
-    ],
-    actions: {
-      publishTicketPanel: async (_context, body) => {
-        const data = body as { values?: Record<string, unknown> };
-        const values = data.values ?? {};
-        return { ok: true, message: `Ticket panel published as '${String(values.title ?? "Need help?")}'`, data: values };
-      }
-    }
-  }
-]
-```
-
-### Announcement Composer (with Role Mention)
-
-```ts
-plugins: [
-  {
-    id: "announcements",
-    name: "Announcements",
-    scope: "guild",
-    getPanels: async () => [
-      {
-        id: "announce",
-        title: "Announcement Composer",
-        fields: [
-          { id: "channel", label: "Channel", type: "channel-search", editable: true, value: "" },
-          { id: "role", label: "Mention Role", type: "role-search", editable: true, value: "" },
-          { id: "content", label: "Content", type: "textarea", editable: true, value: "Server update goes here..." }
-        ],
-        actions: [{ id: "sendAnnouncement", label: "Send", variant: "primary", collectFields: true }]
-      }
-    ],
-    actions: {
-      sendAnnouncement: async (_context, body) => {
-        const payload = body as { values?: Record<string, unknown> };
-        const channel = payload.values?.channel as { id?: string; name?: string } | null;
-        const role = payload.values?.role as { id?: string; name?: string } | null;
-        const mention = role?.id ? `<@&${role.id}> ` : "";
-        const content = String(payload.values?.content ?? "");
-
-        return {
-          ok: true,
-          message: `Announcement queued for #${channel?.name ?? "unknown"}`,
-          data: { message: mention + content, channel }
-        };
-      }
-    }
-  }
-]
-```
+---
 
-## License
+## 📄 License
 
 MIT