claudeck 1.0.2 → 1.0.4

package/README.md

@@ -24,16 +24,19 @@
 # One-command launch (no install needed)
 npx claudeck
 
+# Custom port
+npx claudeck --port 3000
+
 # Or install globally
 npm install -g claudeck
 claudeck
 ```
 
-Open **http://localhost:9009** in your browser.
+On first run, Claudeck will ask you to choose a port (default: `9009`), then open your browser to the URL shown in the terminal. The port is saved to `~/.claudeck/.env` for future runs.
 
 > Requires **Node.js 18+** and Claude Code CLI authentication (`claude auth login`).
 
-On first run, Claudeck creates `~/.claudeck/` with your config, database, and plugins directory — safe for NPX upgrades.
+User data lives in `~/.claudeck/` (config, database, plugins) — safe for NPX upgrades.
 
 ---
 
@@ -207,7 +210,15 @@ Claudeck includes 6 built-in plugins and supports user plugins via `~/.claudeck/
 | **Event Stream** | Real-time WebSocket event viewer |
 | **Games** | Tic-tac-toe and Sudoku |
 
-Create your own: add a `plugins/<name>/` directory with `client.js` and optionally `server.js`, `client.css`, `config.json`. See [CONFIGURATION.md](docs/CONFIGURATION.md#plugins) for details.
+**Create your own** — drop files in `~/.claudeck/plugins/<name>/` (persists across upgrades) with `client.js` and optionally `server.js`, `client.css`, `config.json`. No fork needed. See [CONFIGURATION.md](docs/CONFIGURATION.md#user-plugins) for details.
+
+**Scaffold with Claude Code** — install the plugin creator skill and let Claude build plugins for you:
+
+```bash
+npx skills add https://github.com/hamedafarag/claudeck-skills
+# Then in Claude Code:
+/claudeck-plugin-create my-widget A dashboard showing system metrics
+```
 
 ---
 
@@ -222,6 +233,21 @@ Create your own: add a `plugins/<name>/` directory with `client.js` and optional
 
 ---
 
+## Contributing
+
+Contributions are welcome! Fork the repo, make your changes, and open a PR.
+
+```bash
+git clone https://github.com/hamedafarag/claudeck.git
+cd claudeck
+npm install
+npm start
+```
+
+See [DOCUMENTATION.md](docs/DOCUMENTATION.md) for architecture details and [CONFIGURATION.md](docs/CONFIGURATION.md) for the config system.
+
+---
+
 ## License
 
 [MIT](LICENSE)

package/cli.js

@@ -1,2 +1,67 @@
 #!/usr/bin/env node
-import("./server.js");
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { createInterface } from "readline";
+
+const DEFAULT_PORT = 9009;
+const envDir = process.env.CLAUDECK_HOME || join(homedir(), ".claudeck");
+const envPath = join(envDir, ".env");
+mkdirSync(envDir, { recursive: true });
+
+function readEnv() {
+  try { return readFileSync(envPath, "utf-8"); } catch { return ""; }
+}
+
+function savePort(port) {
+  let content = readEnv();
+  if (/^PORT=.*/m.test(content)) {
+    content = content.replace(/^PORT=.*/m, `PORT=${port}`);
+  } else {
+    content = content.trimEnd() + `\nPORT=${port}\n`;
+  }
+  writeFileSync(envPath, content);
+}
+
+function getSavedPort() {
+  const match = readEnv().match(/^PORT=(\d+)/m);
+  return match ? match[1] : null;
+}
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+async function main() {
+  // --port flag takes priority
+  const portArg = process.argv.find(a => a.startsWith('--port'));
+  if (portArg) {
+    const port = portArg.includes('=') ? portArg.split('=')[1] : process.argv[process.argv.indexOf(portArg) + 1];
+    if (port) {
+      process.env.PORT = port;
+      savePort(port);
+      return import("./server.js");
+    }
+  }
+
+  // If port already saved, use it
+  const saved = getSavedPort();
+  if (saved) {
+    process.env.PORT = saved;
+    return import("./server.js");
+  }
+
+  // First run — ask user
+  console.log(`\n\x1b[36m  Claudeck\x1b[0m — first-time setup\n`);
+  const answer = await ask(`  Which port would you like to use? \x1b[2m(default: ${DEFAULT_PORT})\x1b[0m `);
+  const port = answer && /^\d+$/.test(answer) ? answer : String(DEFAULT_PORT);
+  process.env.PORT = port;
+  savePort(port);
+  console.log(`\x1b[2m  Saved to ~/.claudeck/.env\x1b[0m\n`);
+  return import("./server.js");
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeck",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "type": "module",
   "description": "A browser-based UI for Claude Code — chat, run workflows, manage MCP servers, track costs, and orchestrate autonomous agents from a local web interface. Installable as a PWA.",
   "main": "server.js",

package/plugins/repos/client.css

@@ -547,3 +547,114 @@
   background: var(--accent-dim);
   color: var(--accent);
 }
+
+/* ── Path row with browse button ────────────────────── */
+.repos-path-row {
+  display: flex;
+  gap: 4px;
+  align-items: center;
+}
+
+.repos-path-input {
+  flex: 1;
+  min-width: 0;
+  cursor: pointer;
+}
+
+.repos-browse-btn {
+  flex-shrink: 0;
+  padding: 5px 10px !important;
+  font-size: 10px !important;
+}
+
+/* ── Inline folder browser ──────────────────────────── */
+.repos-browser {
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--bg);
+  max-height: 200px;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.repos-browser-breadcrumb {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  padding: 5px 8px;
+  font-size: 10px;
+  font-family: var(--font-mono);
+  color: var(--text-dim);
+  border-bottom: 1px solid var(--border);
+  overflow-x: auto;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
+.repos-browser-breadcrumb::-webkit-scrollbar { display: none; }
+
+.repos-browser-crumb {
+  cursor: pointer;
+  color: var(--accent);
+  padding: 1px 3px;
+  border-radius: 2px;
+  transition: background 0.1s;
+}
+
+.repos-browser-crumb:hover {
+  background: var(--accent-dim);
+}
+
+.repos-browser-crumb:last-child {
+  color: var(--text);
+  font-weight: 600;
+}
+
+.repos-browser-sep {
+  color: var(--text-dim);
+  opacity: 0.4;
+}
+
+.repos-browser-list {
+  overflow-y: auto;
+  flex: 1;
+}
+
+.repos-browser-list::-webkit-scrollbar { width: 4px; }
+.repos-browser-list::-webkit-scrollbar-thumb { background: var(--border); border-radius: 2px; }
+
+.repos-browser-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 8px;
+  font-size: 11px;
+  font-family: var(--font-mono);
+  color: var(--text);
+  cursor: pointer;
+  transition: background 0.1s;
+}
+
+.repos-browser-item:hover {
+  background: var(--bg-tertiary);
+}
+
+.repos-browser-item svg {
+  width: 12px;
+  height: 12px;
+  flex-shrink: 0;
+  color: var(--accent);
+}
+
+.repos-browser-parent {
+  color: var(--text-dim);
+}
+
+.repos-browser-empty {
+  padding: 12px 8px;
+  font-size: 10px;
+  color: var(--text-dim);
+  text-align: center;
+  font-family: var(--font-mono);
+}

package/plugins/repos/client.js

@@ -227,7 +227,7 @@ registerTab({
         row.querySelector('.repos-inline-input').addEventListener('blur', handleInlineEditBlur);
         setTimeout(() => row.querySelector('.repos-inline-input')?.focus(), 0);
       } else {
-        const pathShort = repo.path ? repo.path.replace(/^\/Users\/[^/]+/, '~') : '';
+        const pathShort = repo.path ? repo.path.replace(/^\/Users\/[^/]+/, '~').replace(/^[A-Z]:\\Users\\[^\\]+/, '~') : '';
         row.innerHTML = `
           <span class="repos-chevron-spacer"></span>
           ${ICONS.repo}
@@ -355,8 +355,15 @@ registerTab({
             <input type="text" class="repos-dialog-input" name="name" placeholder="my-project" autocomplete="off">
           </label>
           <label class="repos-dialog-label">Local Path
-            <input type="text" class="repos-dialog-input" name="path" placeholder="/path/to/repo" autocomplete="off">
+            <div class="repos-path-row">
+              <input type="text" class="repos-dialog-input repos-path-input" name="path" placeholder="/path/to/repo" autocomplete="off" readonly>
+              <button class="repos-btn repos-browse-btn" type="button" title="Browse folders">Browse</button>
+            </div>
           </label>
+          <div class="repos-browser" style="display:none;">
+            <div class="repos-browser-breadcrumb"></div>
+            <div class="repos-browser-list"></div>
+          </div>
           <label class="repos-dialog-label">Remote URL
             <input type="text" class="repos-dialog-input" name="url" placeholder="https://github.com/..." autocomplete="off">
           </label>
@@ -373,6 +380,64 @@ registerTab({
         </div>
       `;
 
+      const browserEl = overlay.querySelector('.repos-browser');
+      const breadcrumbEl = overlay.querySelector('.repos-browser-breadcrumb');
+      const browserListEl = overlay.querySelector('.repos-browser-list');
+      const pathInput = overlay.querySelector('[name="path"]');
+      let browserVisible = false;
+
+      async function navigateBrowser(dir) {
+        try {
+          const data = await ctx.api.browseFolders(dir || undefined);
+          pathInput.value = data.current;
+
+          // Breadcrumb
+          const parts = data.current.split(/[/\\]/).filter(Boolean);
+          let crumbPath = data.current.startsWith('/') ? '/' : '';
+          let crumbHtml = '';
+          // Root
+          const rootLabel = data.current.startsWith('/') ? '/' : parts[0];
+          const rootPath = data.current.startsWith('/') ? '/' : parts[0] + '\\';
+          crumbHtml += `<span class="repos-browser-crumb" data-path="${escapeHtml(rootPath)}">${escapeHtml(rootLabel)}</span>`;
+          const startIdx = data.current.startsWith('/') ? 0 : 1;
+          for (let i = startIdx; i < parts.length; i++) {
+            crumbPath += (i > 0 || !data.current.startsWith('/') ? (data.current.includes('\\') ? '\\' : '/') : '') + parts[i];
+            if (i >= startIdx) {
+              crumbHtml += `<span class="repos-browser-sep">/</span><span class="repos-browser-crumb" data-path="${escapeHtml(crumbPath)}">${escapeHtml(parts[i])}</span>`;
+            }
+          }
+          breadcrumbEl.innerHTML = crumbHtml;
+          breadcrumbEl.querySelectorAll('.repos-browser-crumb').forEach(crumb => {
+            crumb.addEventListener('click', () => navigateBrowser(crumb.dataset.path));
+          });
+
+          // Directory list
+          let listHtml = '';
+          if (data.parent) {
+            listHtml += `<div class="repos-browser-item repos-browser-parent" data-path="${escapeHtml(data.parent)}">${ICONS.folderClosed} <span>..</span></div>`;
+          }
+          for (const d of data.dirs) {
+            const fullPath = data.current + (data.current.endsWith('/') || data.current.endsWith('\\') ? '' : '/') + d.name;
+            listHtml += `<div class="repos-browser-item" data-path="${escapeHtml(fullPath)}">${ICONS.folderClosed} <span>${escapeHtml(d.name)}</span></div>`;
+          }
+          if (!data.dirs.length && !data.parent) {
+            listHtml = '<div class="repos-browser-empty">No subdirectories</div>';
+          }
+          browserListEl.innerHTML = listHtml;
+          browserListEl.querySelectorAll('.repos-browser-item').forEach(item => {
+            item.addEventListener('click', () => navigateBrowser(item.dataset.path));
+          });
+        } catch (err) {
+          browserListEl.innerHTML = `<div class="repos-browser-empty">Error: ${escapeHtml(err.message)}</div>`;
+        }
+      }
+
+      overlay.querySelector('.repos-browse-btn').addEventListener('click', () => {
+        browserVisible = !browserVisible;
+        browserEl.style.display = browserVisible ? '' : 'none';
+        if (browserVisible) navigateBrowser(pathInput.value || undefined);
+      });
+
       overlay.querySelector('.repos-dialog-cancel').addEventListener('click', () => overlay.remove());
       overlay.addEventListener('click', (e) => { if (e.target === overlay) overlay.remove(); });
 
@@ -510,7 +575,12 @@ registerTab({
 
       if (repo.path) {
         ctxMenu.appendChild(createMenuItem('Open in VS Code', () => ctx.api.execCommand('code .', repo.path)));
-        ctxMenu.appendChild(createMenuItem('Open in Terminal', () => ctx.api.execCommand('open -a Terminal .', repo.path)));
+        ctxMenu.appendChild(createMenuItem('Open in Terminal', () => {
+          const isWin = navigator.platform.startsWith('Win');
+          const isMac = navigator.platform.startsWith('Mac');
+          const cmd = isWin ? 'start cmd /k' : isMac ? 'open -a Terminal .' : 'x-terminal-emulator || xterm';
+          ctx.api.execCommand(cmd, repo.path);
+        }));
         ctxMenu.appendChild(createMenuItem('Copy Path', () => navigator.clipboard.writeText(repo.path)));
       }
 

package/public/css/panels/dev-docs.css

@@ -176,9 +176,14 @@
   margin: 0 0 12px;
 }
 
-.dev-docs-content ul {
+.dev-docs-content ul,
+.dev-docs-content ol {
   margin: 0 0 12px;
-  padding-left: 18px;
+  padding-left: 22px;
+}
+
+.dev-docs-content ol {
+  list-style-type: decimal;
 }
 
 .dev-docs-content li {

package/public/js/panels/dev-docs.js

@@ -25,10 +25,11 @@ registerDocSection({
     <h2>Tab SDK — Plugin Guide</h2>
     <p>Register custom tabs in the right panel with a single function call.
     No HTML or <code>dom.js</code> changes needed — the SDK handles DOM creation,
-    lifecycle hooks, badges, and state management.</p>
+    lifecycle hooks, badges, state management, and marketplace integration.</p>
 
     <h3>Quick Start</h3>
-    <pre><code>// plugins/my-tab/client.js
+    <pre><code>// ~/.claudeck/plugins/my-tab/client.js  (user plugin)
+// — or plugins/my-tab/client.js         (built-in plugin)
 import { registerTab } from '/js/ui/tab-sdk.js';
 
 registerTab({
@@ -158,50 +159,94 @@ registerDocSection({
   icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M12 2a15.3 15.3 0 0 1 4 10 15.3 15.3 0 0 1-4 10 15.3 15.3 0 0 1-4-10 15.3 15.3 0 0 1 4-10z"/></svg>',
   render: () => `
     <h2>Architecture Overview</h2>
-    <p>Claudeck is a vanilla ES module frontend with no bundler. All modules are loaded via <code>&lt;script type="module"&gt;</code> from <code>main.js</code>.</p>
+    <p>Claudeck is a vanilla ES module frontend with no bundler. All modules are loaded via <code>&lt;script type="module"&gt;</code> from <code>main.js</code>. Server port is configurable (default 9009).</p>
 
     <h3>Module Loading Order</h3>
     <pre><code>main.js
-  ├── store.js        → Reactive state store
-  ├── dom.js          → Centralized DOM references
-  ├── constants.js    → Shared constants
-  ├── events.js       → Event bus (on/emit/off)
-  ├── utils.js        → Shared utilities
-  ├── ...             → Feature modules
-  ├── right-panel.js  → Right panel + Tab SDK init
-  ├── plugin-loader.js → Loads enabled plugins from plugins/
-  └── ...</code></pre>
+  ├── core/
+  │   ├── store.js          → Reactive state store (getState/setState/on)
+  │   ├── dom.js            → Centralized DOM references ($)
+  │   ├── constants.js      → Shared constants
+  │   ├── events.js         → Event bus (on/emit)
+  │   ├── utils.js          → Shared utilities
+  │   ├── api.js            → All fetch() helpers
+  │   └── ws.js             → WebSocket connection manager
+  ├── ui/
+  │   ├── formatting.js     → Markdown rendering, code highlighting
+  │   ├── diff.js           → Code diff viewer
+  │   ├── commands.js       → Slash command registry
+  │   ├── messages.js       → Chat message rendering
+  │   ├── parallel.js       → 2×2 parallel chat mode
+  │   ├── notifications.js  → Push notifications + sound
+  │   ├── permissions.js    → Tool approval modes
+  │   ├── model-selector.js → Model picker (Opus/Sonnet/Haiku)
+  │   ├── right-panel.js    → Right panel + Tab SDK init
+  │   ├── context-gauge.js  → Token usage indicator
+  │   └── shortcuts.js      → Keyboard shortcuts
+  ├── features/
+  │   ├── sessions.js       → Session management + search
+  │   ├── projects.js       → Project picker + system prompts
+  │   ├── chat.js           → Main chat loop
+  │   ├── prompts.js        → Prompt templates
+  │   ├── workflows.js      → Multi-step workflows
+  │   ├── agents.js         → Agent definitions, chains, DAGs
+  │   ├── home.js           → Home screen + activity grid
+  │   ├── attachments.js    → File/image attachments
+  │   ├── voice-input.js    → Web Speech API input
+  │   ├── telegram.js       → Telegram integration
+  │   └── welcome.js        → Guided tour (Driver.js)
+  ├── panels/
+  │   ├── file-explorer.js  → File tree + preview
+  │   ├── git-panel.js      → Git status, staging, commit
+  │   ├── mcp-manager.js    → MCP server management
+  │   ├── tips-feed.js      → Tips &amp; shortcuts feed
+  │   ├── assistant-bot.js  → Whaly bot assistant
+  │   └── dev-docs.js       → This documentation modal
+  └── plugin-loader.js      → Auto-discovers &amp; loads plugins</code></pre>
 
     <h3>Key Patterns</h3>
     <ul>
-      <li><strong>Event Bus</strong> — <code>events.js</code> provides <code>on(event, fn)</code>, <code>emit(event, data)</code>, <code>off(event, fn)</code>. All cross-module communication uses this.</li>
+      <li><strong>Event Bus</strong> — <code>events.js</code> provides <code>on(event, fn)</code> and <code>emit(event, data)</code>. All cross-module communication uses this.</li>
       <li><strong>Reactive Store</strong> — <code>store.js</code> provides <code>getState(key)</code>, <code>setState(key, val)</code>, and <code>on(key, fn)</code> for reactive subscriptions.</li>
       <li><strong>DOM Registry</strong> — <code>dom.js</code> exports <code>$</code> object with cached element references. Only used for built-in (HTML-defined) elements.</li>
-      <li><strong>API Layer</strong> — <code>api.js</code> contains all <code>fetch()</code> calls. Server runs on port 9009.</li>
+      <li><strong>API Layer</strong> — <code>api.js</code> contains all <code>fetch()</code> calls for server communication.</li>
+      <li><strong>Plugin System</strong> — Plugins are auto-discovered from <code>plugins/</code> (built-in) and <code>~/.claudeck/plugins/</code> (user). Managed via the Marketplace (<code>+</code> button in tab bar).</li>
     </ul>
 
-    <h3>Common Events</h3>
+    <h3>Event Bus Events</h3>
     <table class="param-table">
       <thead><tr><th>Event</th><th>Payload</th></tr></thead>
       <tbody>
         <tr><td>ws:message</td><td>Parsed WebSocket message object</td></tr>
-        <tr><td>session:changed</td><td>New session ID</td></tr>
-        <tr><td>rightPanel:opened</td><td>Active tab name</td></tr>
-        <tr><td>rightPanel:tabChanged</td><td>New tab name</td></tr>
+        <tr><td>ws:connected</td><td><em>none</em> — initial connection established</td></tr>
+        <tr><td>ws:reconnected</td><td><em>none</em> — reconnected after disconnect</td></tr>
+        <tr><td>ws:disconnected</td><td><em>none</em> — connection lost</td></tr>
+        <tr><td>rightPanel:opened</td><td>Active tab name (string)</td></tr>
+        <tr><td>rightPanel:tabChanged</td><td>New tab name (string)</td></tr>
       </tbody>
     </table>
 
     <h3>Store Keys</h3>
     <table class="param-table">
-      <thead><tr><th>Key</th><th>Description</th></tr></thead>
+      <thead><tr><th>Key</th><th>Type</th><th>Description</th></tr></thead>
       <tbody>
-        <tr><td>sessionId</td><td>Current active session ID</td></tr>
-        <tr><td>projectPath</td><td>Current project path</td></tr>
-        <tr><td>isStreaming</td><td>Whether AI is currently responding</td></tr>
+        <tr><td>view</td><td>string</td><td>Current view: <code>"home"</code> or <code>"chat"</code></td></tr>
+        <tr><td>sessionId</td><td>string|null</td><td>Current active session ID</td></tr>
+        <tr><td>parallelMode</td><td>boolean</td><td>Whether 2×2 parallel mode is active</td></tr>
+        <tr><td>streamingCharCount</td><td>number</td><td>Character count during streaming</td></tr>
+        <tr><td>notificationsEnabled</td><td>boolean</td><td>Whether push notifications are on</td></tr>
+        <tr><td>sessionTokens</td><td>object</td><td><code>{ input, output, cacheRead, cacheCreation }</code></td></tr>
+        <tr><td>prompts</td><td>array</td><td>Loaded prompt templates</td></tr>
+        <tr><td>workflows</td><td>array</td><td>Loaded workflow definitions</td></tr>
+        <tr><td>agents</td><td>array</td><td>Loaded agent definitions</td></tr>
+        <tr><td>projectsData</td><td>array</td><td>Configured projects list</td></tr>
+        <tr><td>attachedFiles</td><td>array</td><td>Files attached to current message</td></tr>
+        <tr><td>imageAttachments</td><td>array</td><td>Images attached to current message</td></tr>
+        <tr><td>backgroundSessions</td><td>Map</td><td>Sessions running in background</td></tr>
       </tbody>
     </table>
 
-    <div class="callout">All modules are independent — import only what you need. No global state beyond the event bus and store.</div>
+    <div class="callout">All modules are independent — import only what you need. No global state beyond the event bus and store. Plugins get access to both via the <code>ctx</code> object in <code>init()</code>.</div>
   `,
 });
 
@@ -209,15 +254,15 @@ registerDocSection({
 
 registerDocSection({
   id: 'adding-features',
-  title: 'Adding Features',
+  title: 'Contributing',
   icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/></svg>',
   render: () => `
-    <h2>Adding New Features</h2>
-    <p>Follow these patterns when extending the application.</p>
+    <h2>Contributing to Claudeck</h2>
+    <p>This guide is for contributors who have <strong>forked or cloned the Claudeck repo</strong> and want to extend the core application. If you're using Claudeck via <code>npx claudeck</code> and want to create your own plugins, see the <strong>User Plugins</strong> section instead.</p>
 
-    <h3>Adding a New Plugin Tab</h3>
+    <h3>Adding a Built-in Plugin</h3>
     <ol>
-      <li>Create a directory: <code>plugins/my-feature/</code></li>
+      <li>Create a directory: <code>plugins/my-feature/</code> in the repo</li>
       <li>Create <code>plugins/my-feature/client.js</code> — import <code>registerTab()</code> from <code>/js/ui/tab-sdk.js</code></li>
       <li>Build all DOM inside <code>init(ctx)</code></li>
       <li>Optionally add <code>client.css</code> in the same directory (auto-injected)</li>
@@ -246,7 +291,7 @@ registerDocSection({
       <li>Use CSS variables from <code>variables.css</code> for consistency</li>
     </ol>
 
-    <h3>Plugin Structure</h3>
+    <h3>Built-in Plugin Structure</h3>
     <ul>
       <li>Plugin directories: <code>plugins/kebab-case/</code></li>
       <li>Client module: <code>client.js</code> (required)</li>
@@ -260,6 +305,123 @@ registerDocSection({
   `,
 });
 
+// ── Built-in: User Plugins Guide ────────────────────────
+
+registerDocSection({
+  id: 'user-plugins',
+  title: 'User Plugins',
+  icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M16 18l6-6-6-6"/><path d="M8 6l-6 6 6 6"/></svg>',
+  render: () => `
+    <h2>User Plugins</h2>
+    <p>This guide is for developers using Claudeck via <code>npx claudeck</code> who want to create their own plugins. User plugins live in <code>~/.claudeck/plugins/</code>, persist across npm upgrades, and work identically to built-in plugins — no need to fork the repo.</p>
+
+    <h3>Creating a User Plugin</h3>
+    <ol>
+      <li>Create a directory in <code>~/.claudeck/plugins/</code>:
+        <pre><code>mkdir -p ~/.claudeck/plugins/my-plugin</code></pre>
+      </li>
+      <li>Create <code>client.js</code> with a <code>registerTab()</code> call:
+        <pre><code>// ~/.claudeck/plugins/my-plugin/client.js
+import { registerTab } from '/js/ui/tab-sdk.js';
+
+registerTab({
+  id: 'my-plugin',
+  title: 'My Plugin',
+  lazy: true,
+  init(ctx) {
+    const root = document.createElement('div');
+    root.innerHTML = '&lt;h3&gt;Hello from my plugin!&lt;/h3&gt;';
+    return root;
+  },
+});</code></pre>
+      </li>
+      <li>Optionally add <code>client.css</code> for styles (auto-injected)</li>
+      <li>Optionally add <code>server.js</code> for backend routes (requires <code>CLAUDECK_USER_SERVER_PLUGINS=true</code> in <code>~/.claudeck/.env</code>)</li>
+      <li>Optionally add <code>config.json</code> for default settings (auto-copied to <code>~/.claudeck/config/</code>)</li>
+    </ol>
+
+    <h3>Plugin Directories</h3>
+    <table class="param-table">
+      <thead><tr><th>Directory</th><th>URL Path</th><th>Writable</th></tr></thead>
+      <tbody>
+        <tr><td><code>&lt;package&gt;/plugins/</code></td><td><code>/plugins/</code></td><td>No (built-in)</td></tr>
+        <tr><td><code>~/.claudeck/plugins/</code></td><td><code>/user-plugins/</code></td><td>Yes (user)</td></tr>
+      </tbody>
+    </table>
+
+    <h3>Server-Side Routes</h3>
+    <p>If your plugin has a <code>server.js</code>, it exports an Express router that is auto-mounted at <code>/api/plugins/&lt;name&gt;/</code>:</p>
+    <pre><code>// ~/.claudeck/plugins/my-plugin/server.js
+import { Router } from 'express';
+const router = Router();
+
+router.get('/data', (req, res) =&gt; {
+  res.json({ message: 'Hello from server!' });
+});
+
+export default router;</code></pre>
+    <div class="callout"><strong>Security:</strong> User server plugins are disabled by default. Set <code>CLAUDECK_USER_SERVER_PLUGINS=true</code> in <code>~/.claudeck/.env</code> to enable them.</div>
+
+    <h3>Discovery</h3>
+    <p>Plugins are auto-discovered on page load. No server restart is needed for client-only plugins. The Marketplace tab shows all plugins with their source (<code>builtin</code> or <code>user</code>).</p>
+
+    <h3>Scaffolding Plugins with Claude Code</h3>
+    <p>Install the Claudeck plugin creator skill, then let Claude Code scaffold plugins for you:</p>
+    <pre><code>npx skills add https://github.com/hamedafarag/claudeck-skills</code></pre>
+    <p>Then in Claude Code, run:</p>
+    <pre><code>/claudeck-plugin-create my-plugin A tab that shows GitHub notifications</code></pre>
+    <p>Claude will generate the full plugin files in <code>~/.claudeck/plugins/</code> based on your description. Examples:</p>
+    <ul>
+      <li><code>/claudeck-plugin-create github-notifs Show my GitHub notifications</code></li>
+      <li><code>/claudeck-plugin-create sys-metrics A dashboard showing system metrics</code></li>
+      <li><code>/claudeck-plugin-create api-proxy A plugin with a server route that proxies an external API</code></li>
+    </ul>
+  `,
+});
+
+// ── Built-in: Links & Resources ─────────────────────────
+
+registerDocSection({
+  id: 'resources',
+  title: 'Resources',
+  icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/></svg>',
+  render: () => `
+    <h2>Resources &amp; Links</h2>
+
+    <h3>GitHub</h3>
+    <ul>
+      <li><a href="https://github.com/hamedafarag/claudeck" target="_blank" style="color:var(--accent)">github.com/hamedafarag/claudeck</a> — Source code, issues, and discussions</li>
+      <li><a href="https://github.com/hamedafarag/claudeck/issues" target="_blank" style="color:var(--accent)">Issues</a> — Report bugs or request features</li>
+      <li><a href="https://github.com/hamedafarag/claudeck/blob/main/docs/DOCUMENTATION.md" target="_blank" style="color:var(--accent)">Full Documentation</a> — Complete feature docs and API reference</li>
+      <li><a href="https://github.com/hamedafarag/claudeck/blob/main/docs/CONFIGURATION.md" target="_blank" style="color:var(--accent)">Configuration Guide</a> — User data directory, config files, plugin system</li>
+    </ul>
+
+    <h3>npm</h3>
+    <ul>
+      <li><a href="https://www.npmjs.com/package/claudeck" target="_blank" style="color:var(--accent)">npmjs.com/package/claudeck</a> — Package page</li>
+    </ul>
+
+    <h3>Claude Code Skills</h3>
+    <ul>
+      <li><a href="https://github.com/hamedafarag/claudeck-skills" target="_blank" style="color:var(--accent)">github.com/hamedafarag/claudeck-skills</a> — Plugin creator skill for Claude Code</li>
+    </ul>
+    <pre><code>npx skills add https://github.com/hamedafarag/claudeck-skills</code></pre>
+
+    <h3>Quick Reference</h3>
+    <table class="param-table">
+      <thead><tr><th>Command</th><th>Description</th></tr></thead>
+      <tbody>
+        <tr><td><code>npx claudeck</code></td><td>Launch Claudeck (installs if needed)</td></tr>
+        <tr><td><code>npx claudeck --port 3000</code></td><td>Launch on a custom port</td></tr>
+        <tr><td><code>npm i -g claudeck</code></td><td>Install globally</td></tr>
+      </tbody>
+    </table>
+
+    <h3>License</h3>
+    <p>Claudeck is open-source under the <strong>MIT License</strong>. Contributions are welcome!</p>
+  `,
+});
+
 // ── Modal renderer ──────────────────────────────────────
 
 let overlayEl = null;

package/public/js/ui/notifications.js

@@ -162,6 +162,18 @@ async function unsubscribeFromPush() {
 export async function toggleNotifications() {
   const current = getState('notificationsEnabled');
   if (!current) {
+    if (!('Notification' in window)) {
+      alert('Notifications are not supported in this browser.');
+      return false;
+    }
+    if (Notification.permission === 'denied') {
+      alert('Notifications are blocked. Please enable them in your browser settings for this site.');
+      return false;
+    }
+    if (window.location.protocol !== 'https:' && window.location.hostname !== 'localhost' && window.location.hostname !== '127.0.0.1') {
+      alert('Notifications require HTTPS or localhost. Please access Claudeck via https:// or http://localhost.');
+      return false;
+    }
     const granted = await requestNotificationPermission();
     if (!granted) return false;
     setState('notificationsEnabled', true);

package/server/routes/exec.js

@@ -23,9 +23,11 @@ router.post("/", (req, res) => {
     });
   };
 
-  // Use execFile for simple "binary ." commands to avoid shell escaping issues
+  // On Windows, always use exec (shell) so PATH-resolved commands like "code" work
+  // On Unix, use execFile for simple commands to avoid shell escaping issues
   const parts = command.split(/\s+/);
-  if (parts.length <= 2 && !command.includes("|") && !command.includes(">") && !command.includes("&")) {
+  const isSimple = parts.length <= 2 && !command.includes("|") && !command.includes(">") && !command.includes("&");
+  if (isSimple && process.platform !== "win32") {
     execFile(parts[0], parts.slice(1), execOpts, callback);
   } else {
     exec(command, execOpts, callback);

package/server/routes/stats.js

@@ -42,7 +42,10 @@ router.get("/account", async (req, res) => {
   }
   try {
     const data = await new Promise((resolve, reject) => {
-      execFile(claudeBin, ["auth", "status"], { timeout: 10000 }, (err, stdout) => {
+      const opts = { timeout: 10000 };
+      // On Windows, use shell to resolve claude from PATH
+      if (process.platform === "win32") opts.shell = true;
+      execFile(claudeBin, ["auth", "status"], opts, (err, stdout) => {
         if (err) return reject(err);
         try { resolve(JSON.parse(stdout)); } catch (e) { reject(e); }
       });

package/server.js

@@ -164,7 +164,21 @@ const PORT = process.env.PORT || 9009;
 // Mount full-stack plugin routes, then start server
 mountPluginRoutes(app, fullStackPluginsDir).then(() => {
   server.listen(PORT, () => {
-    console.log(`Claudeck running at http://localhost:${PORT}`);
+    const url = `http://localhost:${PORT}`;
+    console.log(`
+\x1b[36m   _____ _                 _           _
+  / ____| |               | |         | |
+ | |    | | __ _ _   _  __| | ___  ___| | __
+ | |    | |/ _\` | | | |/ _\` |/ _ \\/ __| |/ /
+ | |____| | (_| | |_| | (_| |  __/ (__|   <
+  \\_____|_|\\__,_|\\__,_|\\__,_|\\___|\\___|_|\\_\\\x1b[0m
+
+\x1b[2m  Browser UI for Claude Code\x1b[0m
+
+  \x1b[1m\x1b[32m➜\x1b[0m  \x1b[1mReady:\x1b[0m   ${url}
+  \x1b[2m➜  Port:\x1b[0m    ${PORT}
+  \x1b[2m➜  Data:\x1b[0m    ~/.claudeck/
+`);
   });
 });