kanban-lite 1.2.2 → 1.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kanban-lite",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "description": "Kanban board manager - VSCode extension, CLI, MCP server, and standalone web app",
   "license": "MIT",
   "repository": {

package/src/mcp-server/index.ts

@@ -789,7 +789,7 @@ async function main(): Promise<void> {
 
   server.tool(
     'trigger_action',
-    'Trigger a named action on a card. The action name must match one of the card\'s configured actions. Calls the configured action webhook URL with the action name and card details.',
+    'Trigger a named action on a card. The action name must match one of the card\'s configured actions. Emits a card.action.triggered event delivered to registered webhooks.',
     {
       card_id: z.string().describe('Card ID (partial match supported)'),
       action: z.string().describe('Action name to trigger'),

package/src/sdk/KanbanSDK.d.ts

@@ -958,21 +958,17 @@ export declare class KanbanSDK {
      */
     submitForm(input: SubmitFormInput): Promise<SubmitFormResult>;
     /**
-     * Triggers a named action for a card by POSTing to the global `actionWebhookUrl`
-     * configured in `.kanban.json`.
+     * Triggers a named action for a card.
      *
-     * The payload sent to the webhook is:
-     * ```json
-     * { "action": "retry", "board": "default", "list": "in-progress", "card": { ...sanitizedCard } }
-     * ```
+     * Validates the card, appends an activity log entry, and emits the
+     * `card.action.triggered` after-event so registered webhooks receive
+     * the action payload automatically.
      *
      * @param cardId - The ID of the card to trigger the action for.
      * @param action - The action name string (e.g. `'retry'`, `'sendEmail'`).
      * @param boardId - Optional board ID. Defaults to the workspace's default board.
-     * @returns A promise resolving when the webhook responds with 2xx.
-     * @throws {Error} If no `actionWebhookUrl` is configured in `.kanban.json`.
+     * @returns A promise that resolves when the action has been processed.
      * @throws {Error} If the card is not found.
-     * @throws {Error} If the webhook responds with a non-2xx status.
      *
      * @example
      * ```ts

package/src/sdk/KanbanSDK.ts

@@ -1737,21 +1737,17 @@ export class KanbanSDK {
   }
 
   /**
-   * Triggers a named action for a card by POSTing to the global `actionWebhookUrl`
-   * configured in `.kanban.json`.
+   * Triggers a named action for a card.
    *
-   * The payload sent to the webhook is:
-   * ```json
-   * { "action": "retry", "board": "default", "list": "in-progress", "card": { ...sanitizedCard } }
-   * ```
+   * Validates the card, appends an activity log entry, and emits the
+   * `card.action.triggered` after-event so registered webhooks receive
+   * the action payload automatically.
    *
    * @param cardId - The ID of the card to trigger the action for.
    * @param action - The action name string (e.g. `'retry'`, `'sendEmail'`).
    * @param boardId - Optional board ID. Defaults to the workspace's default board.
-   * @returns A promise resolving when the webhook responds with 2xx.
-   * @throws {Error} If no `actionWebhookUrl` is configured in `.kanban.json`.
+   * @returns A promise that resolves when the action has been processed.
    * @throws {Error} If the card is not found.
-   * @throws {Error} If the webhook responds with a non-2xx status.
    *
    * @example
    * ```ts
@@ -1761,7 +1757,8 @@ export class KanbanSDK {
    */
   async triggerAction(cardId: string, action: string, boardId?: string): Promise<void> {
     const mergedInput = await this._runBeforeEvent<MethodInput<typeof Cards.triggerAction>>('card.action.trigger', { cardId, action, boardId }, undefined, boardId)
-    return Cards.triggerAction(this, mergedInput)
+    const payload = await Cards.triggerAction(this, mergedInput)
+    this._runAfterEvent('card.action.triggered', payload, undefined, payload.board)
   }
 
   /**

package/src/sdk/integrationCatalog.ts

@@ -171,6 +171,7 @@ const AFTER_ENTRIES = [
   { event: 'board.updated'    as SDKAfterEventType, resource: 'board'      as KanbanResource, label: 'Board updated' },
   { event: 'board.deleted'    as SDKAfterEventType, resource: 'board'      as KanbanResource, label: 'Board deleted' },
   { event: 'board.action'     as SDKAfterEventType, resource: 'board'      as KanbanResource, label: 'Board action triggered' },
+  { event: 'card.action.triggered' as SDKAfterEventType, resource: 'card' as KanbanResource, label: 'Card action triggered' },
   { event: 'board.log.added'  as SDKAfterEventType, resource: 'board'      as KanbanResource, label: 'Board log added' },
   { event: 'board.log.cleared' as SDKAfterEventType, resource: 'board'     as KanbanResource, label: 'Board log cleared' },
   // card logs

package/src/sdk/modules/cards.ts

@@ -452,39 +452,21 @@ export async function updateCard(
 }
 
 /**
- * Triggers a named action for a card by POSTing to the global `actionWebhookUrl`.
+ * Triggers a named action for a card.
+ *
+ * Validates the card exists, appends an activity log entry, and returns the
+ * action payload. Webhook delivery is handled by the webhook plugin via the
+ * `card.action.triggered` after-event emitted by {@link KanbanSDK.triggerAction}.
  */
 export async function triggerAction(
   ctx: SDKContext,
   { cardId, action, boardId }: { cardId: string; action: string; boardId?: string }
-): Promise<void> {
-  const config = readConfig(ctx.workspaceRoot)
-  const { actionWebhookUrl } = config
-  if (!actionWebhookUrl) {
-    throw new Error('No action webhook URL configured. Set actionWebhookUrl in .kanban.json')
-  }
-
+): Promise<{ action: string; board: string; list: string; card: Omit<Card, 'filePath'> }> {
   const card = await getCard(ctx, { cardId, boardId })
   if (!card) throw new Error(`Card not found: ${cardId}`)
 
   const resolvedBoardId = card.boardId || ctx._resolveBoardId(boardId)
 
-  const payload = {
-    action,
-    board: resolvedBoardId,
-    list: card.status,
-    card: sanitizeCard(card),
-  }
-
-  const response = await fetch(actionWebhookUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(payload),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Action webhook responded with ${response.status}: ${response.statusText}`)
-  }
   await appendActivityLog(ctx, {
     cardId,
     boardId: resolvedBoardId,
@@ -494,6 +476,13 @@ export async function triggerAction(
       action,
     },
   }).catch(() => {})
+
+  return {
+    action,
+    board: resolvedBoardId,
+    list: card.status,
+    card: sanitizeCard(card),
+  }
 }
 
 /**

package/src/sdk/plugins/index.ts

@@ -138,6 +138,8 @@ interface AuthPluginModule {
   readonly createRbacIdentityPlugin?: unknown
   /** Optional factory for a configurable policy plugin. When present it is called with the provider options from `.kanban.json` so plugins can apply per-deployment overrides such as a custom RBAC matrix. */
   readonly createAuthPolicyPlugin?: ((options?: Record<string, unknown>) => unknown) | unknown
+  /** Optional factory for a configurable identity plugin. When present it is called with the provider options from `.kanban.json` so plugins can apply per-deployment overrides such as an explicit API token. */
+  readonly createAuthIdentityPlugin?: ((options?: Record<string, unknown>) => unknown) | unknown
   readonly default?: unknown
 }
 
@@ -345,7 +347,7 @@ function resolveAuthIdentityPlugin(ref: ProviderRef): AuthIdentityPlugin {
   if (ref.provider === 'noop') return NOOP_IDENTITY_PLUGIN
   if (ref.provider === 'rbac') return RBAC_IDENTITY_PLUGIN
   const packageName = AUTH_PROVIDER_ALIASES.get(ref.provider) ?? ref.provider
-  return loadExternalAuthIdentityPlugin(packageName, ref.provider)
+  return loadExternalAuthIdentityPlugin(packageName, ref.provider, ref.options)
 }
 
 function resolveAuthPolicyPlugin(ref: ProviderRef): AuthPolicyPlugin {
@@ -1087,8 +1089,14 @@ function selectAuthPolicyPlugin(mod: AuthPluginModule, providerId: string): Auth
   return null
 }
 
-function loadExternalAuthIdentityPlugin(packageName: string, providerId: string): AuthIdentityPlugin {
+function loadExternalAuthIdentityPlugin(packageName: string, providerId: string, options?: Record<string, unknown>): AuthIdentityPlugin {
   const mod = loadExternalModule(packageName) as AuthPluginModule
+
+  if (options !== undefined && typeof mod.createAuthIdentityPlugin === 'function') {
+    const created = (mod.createAuthIdentityPlugin as (opts?: Record<string, unknown>) => unknown)(options)
+    if (isValidAuthIdentityPlugin(created, providerId)) return created
+  }
+
   const plugin = selectAuthIdentityPlugin(mod, providerId)
   if (!plugin) {
     throw new Error(

package/src/sdk/types.d.ts

@@ -58,7 +58,7 @@ export type SDKBeforeEventType = 'card.create' | 'card.update' | 'card.move' | '
  *
  * @see AfterEventPayload for the payload envelope passed to after-event listeners.
  */
-export type SDKAfterEventType = 'task.created' | 'task.updated' | 'task.moved' | 'task.deleted' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'column.created' | 'column.updated' | 'column.deleted' | 'attachment.added' | 'attachment.removed' | 'settings.updated' | 'board.created' | 'board.updated' | 'board.deleted' | 'board.action' | 'board.log.added' | 'board.log.cleared' | 'log.added' | 'log.cleared' | 'storage.migrated' | 'form.submitted' | 'auth.allowed' | 'auth.denied';
+export type SDKAfterEventType = 'task.created' | 'task.updated' | 'task.moved' | 'task.deleted' | 'comment.created' | 'comment.updated' | 'comment.deleted' | 'column.created' | 'column.updated' | 'column.deleted' | 'attachment.added' | 'attachment.removed' | 'settings.updated' | 'board.created' | 'board.updated' | 'board.deleted' | 'board.action' | 'card.action.triggered' | 'board.log.added' | 'board.log.cleared' | 'log.added' | 'log.cleared' | 'storage.migrated' | 'form.submitted' | 'auth.allowed' | 'auth.denied';
 /**
  * Union of all SDK event types (before-events and after-events).
  *

package/src/sdk/types.ts

@@ -118,6 +118,7 @@ export type SDKAfterEventType =
   | 'board.updated'
   | 'board.deleted'
   | 'board.action'
+  | 'card.action.triggered'
   | 'board.log.added'
   | 'board.log.cleared'
   | 'log.added'

package/src/sdk/webhooks.ts

@@ -32,10 +32,15 @@ import type { SDKEventType } from './types'
 export function fireWebhooks(workspaceRoot: string, event: SDKEventType, data: unknown): void {
   const config = readConfig(workspaceRoot)
   const webhooks = config.webhooks || []
+  console.log(`[kanban-lite/webhooks] fireWebhooks: event=${event} | total=${webhooks.length} registered`)
   const matching = webhooks.filter(
     w => w.active && (w.events.includes('*') || w.events.includes(event))
   )
-  if (matching.length === 0) return
+  if (matching.length === 0) {
+    console.log(`[kanban-lite/webhooks] no matching webhooks for event=${event} (${webhooks.filter(w => !w.active).length} inactive)`)
+    return
+  }
+  console.log(`[kanban-lite/webhooks] firing ${matching.length} webhook(s) for event=${event}: ${matching.map(w => w.id).join(', ')}`)
 
   const payload = JSON.stringify({
     event,
@@ -73,6 +78,7 @@ async function deliverWebhook(webhook: Webhook, event: string, payload: string):
     'X-Webhook-Event': event
   }
 
+  const hasSecret = !!webhook.secret
   if (webhook.secret) {
     const signature = crypto
       .createHmac('sha256', webhook.secret)
@@ -81,6 +87,10 @@ async function deliverWebhook(webhook: Webhook, event: string, payload: string):
     headers['X-Webhook-Signature'] = `sha256=${signature}`
   }
 
+  console.log(
+    `[kanban-lite/webhooks] → POST ${webhook.url} | event=${event} | id=${webhook.id} | secret=${hasSecret ? 'yes' : 'no'} | payloadBytes=${Buffer.byteLength(payload)}`,
+  )
+
   return new Promise((resolve, reject) => {
     const req = transport.request(
       {
@@ -92,6 +102,9 @@ async function deliverWebhook(webhook: Webhook, event: string, payload: string):
         timeout: 10000
       },
       (res) => {
+        console.log(
+          `[kanban-lite/webhooks] ← ${res.statusCode} ${res.statusMessage ?? ''} | id=${webhook.id} | url=${webhook.url}`,
+        )
         res.resume() // drain response
         if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
           resolve()
@@ -100,8 +113,12 @@ async function deliverWebhook(webhook: Webhook, event: string, payload: string):
         }
       }
     )
-    req.on('error', reject)
+    req.on('error', (err) => {
+      console.error(`[kanban-lite/webhooks] request error | id=${webhook.id} | url=${webhook.url}:`, err.message)
+      reject(err)
+    })
     req.on('timeout', () => {
+      console.error(`[kanban-lite/webhooks] timeout | id=${webhook.id} | url=${webhook.url}`)
       req.destroy()
       reject(new Error('Timeout'))
     })

package/src/shared/config.ts

@@ -191,7 +191,10 @@ export interface KanbanConfig {
   webhooks?: Webhook[]
   /** Label definitions keyed by label name, with color and optional group. */
   labels?: Record<string, LabelDefinition>
-  /** Optional URL to POST to when a card action is triggered. */
+  /**
+   * @deprecated Removed in favour of the webhook plugin. Register a webhook
+   * for the `card.action.triggered` event instead.
+   */
   actionWebhookUrl?: string
   /**
    * Global auto-increment card ID counter shared across all boards.
@@ -271,6 +274,13 @@ export interface KanbanConfig {
   customHeadHtml?: string
   /** Path to an HTML file (relative to workspace root) whose content is injected into the standalone board's `<head>` element. Takes precedence over `customHeadHtml`. */
   customHeadHtmlFile?: string
+  /**
+   * Optional URL base path prefix for subfolder reverse-proxy deployments
+   * (e.g. `'/kanban'`). Must start with `/` and have no trailing slash.
+   * When set, all asset URLs, the WebSocket endpoint, and API routes are
+   * served under this prefix. Only applies to the standalone server.
+   */
+  basePath?: string
 }
 
 // Legacy v1 config (for migration)
@@ -419,11 +429,99 @@ function migrateConfigV1ToV2(raw: Record<string, unknown>): KanbanConfig {
   return v2
 }
 
+/**
+ * Loads key–value pairs from a `.env` file in the given directory into
+ * `process.env`. Existing environment variables are never overwritten so that
+ * real OS-level values always take precedence over file-based defaults.
+ * Silently does nothing if the file does not exist.
+ *
+ * @param dir - Directory that may contain a `.env` file.
+ */
+function loadDotEnv(dir: string): void {
+  const envPath = path.join(dir, '.env')
+  let content: string
+  try {
+    content = fs.readFileSync(envPath, 'utf-8')
+  } catch {
+    return
+  }
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eqIdx = trimmed.indexOf('=')
+    if (eqIdx < 1) continue
+    const key = trimmed.slice(0, eqIdx).trim()
+    let val = trimmed.slice(eqIdx + 1).trim()
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1)
+    }
+    if (process.env[key] === undefined) {
+      process.env[key] = val
+    }
+  }
+}
+
+/**
+ * Recursively resolves `${VAR_NAME}` placeholders in all string values of a
+ * parsed config object against `process.env`. Mutates the object in place.
+ *
+ * Throws a descriptive error when a referenced environment variable is not
+ * set, including the JSON path to the offending value so the operator can
+ * locate it quickly. Example error message:
+ *
+ * ```
+ * missing ALICE_PASSWORD_HASH in .kanban.json: .plugins."auth.identity".options.users[3].password "${ALICE_PASSWORD_HASH}"
+ * ```
+ *
+ * Keys that contain non-identifier characters (e.g. dots) are quoted in the
+ * path segment, matching the convention used in `.kanban.json` error messages.
+ *
+ * @param node - The current node to process (object, array, string, or scalar).
+ * @param configFileName - Config filename used in error messages (e.g. `'.kanban.json'`).
+ * @param nodePath - JSON path accumulated so far (empty string at root).
+ * @returns The processed node (same reference for objects/arrays; new primitive for strings).
+ */
+function resolveConfigEnvVars(node: unknown, configFileName: string, nodePath = ''): unknown {
+  if (typeof node === 'string') {
+    return node.replace(/\$\{([^}]+)\}/g, (_match, varName: string) => {
+      const envValue = process.env[varName]
+      if (envValue === undefined) {
+        throw new Error(
+          `missing ${varName} in ${configFileName}: ${nodePath} "${node}"`
+        )
+      }
+      return envValue
+    })
+  }
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      node[i] = resolveConfigEnvVars(node[i], configFileName, `${nodePath}[${i}]`)
+    }
+    return node
+  }
+  if (node !== null && typeof node === 'object') {
+    const obj = node as Record<string, unknown>
+    for (const key of Object.keys(obj)) {
+      const jsonKey = /[^a-zA-Z0-9_]/.test(key) ? `"${key}"` : key
+      const childPath = nodePath ? `${nodePath}.${jsonKey}` : `.${jsonKey}`
+      obj[key] = resolveConfigEnvVars(obj[key], configFileName, childPath)
+    }
+    return obj
+  }
+  return node
+}
+
 /**
  * Reads the kanban config from disk. If the file is missing or unreadable,
  * returns the default config. If the file contains a v1 config, it is
  * automatically migrated to v2 format and persisted back to disk.
  *
+ * Any `${VAR_NAME}` placeholders found in string values are resolved against
+ * `process.env` before the config is returned. If a referenced environment
+ * variable is not set the process will throw a descriptive error rather than
+ * silently falling back to defaults, because an unresolved secret is never a
+ * safe default.
+ *
  * @param workspaceRoot - Absolute path to the workspace root directory.
  * @returns The parsed (and possibly migrated) kanban configuration.
  *
@@ -434,8 +532,32 @@ function migrateConfigV1ToV2(raw: Record<string, unknown>): KanbanConfig {
 export function readConfig(workspaceRoot: string): KanbanConfig {
   const filePath = configPath(workspaceRoot)
   const defaults = { ...DEFAULT_CONFIG, boards: { default: { ...DEFAULT_BOARD_CONFIG, columns: [...DEFAULT_COLUMNS] } } }
+
+  // Parse the file first; fall back to defaults only for read/parse failures.
+  let raw: Record<string, unknown>
+  try {
+    raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+  } catch {
+    return defaults
+  }
+
+  // Load .env from workspace root before resolving placeholders so that
+  // variables defined there are available without requiring the operator to
+  // export them in their shell.
+  loadDotEnv(workspaceRoot)
+
+  // Resolve ${VAR_NAME} env placeholders. A missing env variable is a known,
+  // operator-caused misconfiguration and should produce a clean, actionable
+  // error rather than a Node.js stack trace.
+  try {
+    resolveConfigEnvVars(raw, CONFIG_FILENAME)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    process.stderr.write(`\nConfiguration error: ${msg}\n\nSet the missing environment variable before starting the server.\n\n`)
+    process.exit(1)
+  }
+
   try {
-    const raw = JSON.parse(fs.readFileSync(filePath, 'utf-8'))
     // True v1: explicitly version 1, OR version absent AND no boards object
     // A versionless modern config (has a boards object) must NOT be treated as v1
     const isV1 = raw.version === 1 || (!raw.version && !(typeof raw.boards === 'object' && raw.boards !== null && !Array.isArray(raw.boards)))

package/src/standalone/internal/runtime.ts

@@ -6,20 +6,25 @@ import { KanbanSDK } from '../../sdk/KanbanSDK'
 import type { StandaloneContext } from '../context'
 import { broadcastLogsUpdatedToEditingClients, getClientsEditingCard } from '../broadcastService'
 
-export const indexHtml = `<!DOCTYPE html>
+export function getIndexHtml(basePath = ''): string {
+  return `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="icon" type="image/svg+xml" href="/favicon.svg">
-  <link href="/style.css" rel="stylesheet">
+  <link rel="icon" type="image/svg+xml" href="${basePath}/favicon.svg">
+  <link href="${basePath}/style.css" rel="stylesheet">
   <title>Kanban Board</title>
+  <script>window.__KB_BASE__ = ${JSON.stringify(basePath)}<\/script>
 </head>
 <body>
   <div id="root"></div>
-  <script type="module" src="/index.js"></script>
+  <script type="module" src="${basePath}/index.js"><\/script>
 </body>
 </html>`
+}
+
+export const indexHtml = getIndexHtml()
 
 export interface StandaloneRuntime {
   absoluteKanbanDir: string
@@ -46,13 +51,13 @@ function resolveStandaloneWebviewDir(webviewDir?: string): string {
   return candidates[0]
 }
 
-export function createStandaloneRuntime(kanbanDir: string, webviewDir?: string, httpServer?: http.Server): StandaloneRuntime {
+export function createStandaloneRuntime(kanbanDir: string, webviewDir?: string, httpServer?: http.Server, basePath?: string): StandaloneRuntime {
   const absoluteKanbanDir = path.resolve(kanbanDir)
   const workspaceRoot = path.dirname(absoluteKanbanDir)
   const resolvedWebviewDir = resolveStandaloneWebviewDir(webviewDir)
 
   const server = httpServer ?? http.createServer()
-  const wss = new WebSocketServer({ server, path: '/ws' })
+  const wss = new WebSocketServer({ server, path: (basePath || '') + '/ws' })
 
   const ctx = {} as StandaloneContext
   const sdk = new KanbanSDK(absoluteKanbanDir, {

package/src/standalone/server.ts

@@ -9,7 +9,7 @@ import type { StandaloneHttpHandler, StandaloneHttpPlugin } from '../sdk'
 import { createRouteMatcher, type StandaloneRequestContext, type StandaloneRouteHandler } from './internal/common'
 import { KANBAN_OPENAPI_SPEC } from './internal/openapi-spec'
 import { handleCardFileRoute, setupStandaloneLifecycle } from './internal/lifecycle'
-import { createStandaloneRuntime, indexHtml } from './internal/runtime'
+import { createStandaloneRuntime, getIndexHtml } from './internal/runtime'
 import { handleBoardRoutes } from './internal/routes/boards'
 import { handleSystemRoutes } from './internal/routes/system'
 import { handleTaskRoutes } from './internal/routes/tasks'
@@ -249,11 +249,15 @@ export function startServer(kanbanDir: string, port: number, webviewDir?: string
     ? { type: 'image/svg+xml', content: fs.readFileSync(swaggerUiLogoPath) }
     : null
 
-  const runtime = createStandaloneRuntime(kanbanDir, webviewDir, fastify.server)
+  const workspaceRoot = path.dirname(path.resolve(kanbanDir))
+  const config = readConfig(workspaceRoot)
+  const rawBase = config.basePath ?? ''
+  const basePath = rawBase ? (rawBase.startsWith('/') ? rawBase : '/' + rawBase).replace(/\/+$/, '') : ''
+
+  const runtime = createStandaloneRuntime(kanbanDir, webviewDir, fastify.server, basePath)
   const { ctx, resolvedWebviewDir } = runtime
 
-  const config = readConfig(ctx.workspaceRoot)
-  let resolvedIndexHtml = indexHtml
+  let resolvedIndexHtml = getIndexHtml(basePath)
   let customHead = config.customHeadHtml || ''
   if (config.customHeadHtmlFile) {
     try {
@@ -262,7 +266,7 @@ export function startServer(kanbanDir: string, port: number, webviewDir?: string
     } catch { /* file not found, fall back to customHeadHtml */ }
   }
   if (customHead) {
-    resolvedIndexHtml = indexHtml.replace('</head>', `${customHead}\n</head>`)
+    resolvedIndexHtml = resolvedIndexHtml.replace('</head>', `${customHead}\n</head>`)
   }
   const standaloneHttpPlugins = ctx.sdk.capabilities?.standaloneHttpPlugins ?? []
   const standaloneOpenApiSpec = buildStandaloneOpenApiSpec(standaloneHttpPlugins)
@@ -270,7 +274,7 @@ export function startServer(kanbanDir: string, port: number, webviewDir?: string
   // OpenAPI spec and interactive docs (served before the catch-all so Fastify prefers these routes)
   fastify.register(swagger, { openapi: standaloneOpenApiSpec as any })
   fastify.register(swaggerUi, {
-    routePrefix: '/api/docs',
+    routePrefix: `${basePath}/api/docs`,
     uiConfig: { docExpansion: 'list', deepLinking: false },
     logo: swaggerUiLogo,
     ...(swaggerUiStaticDir ? { baseDir: swaggerUiStaticDir } : {}),
@@ -313,6 +317,16 @@ export function startServer(kanbanDir: string, port: number, webviewDir?: string
       req._rawBody = request.body
     }
 
+    // Strip base path prefix so internal route handlers see root-relative paths
+    if (basePath) {
+      const rawUrl = req.url ?? '/'
+      if (rawUrl === basePath) {
+        req.url = '/'
+      } else if (rawUrl.startsWith(basePath + '/') || rawUrl.startsWith(basePath + '?')) {
+        req.url = rawUrl.slice(basePath.length)
+      }
+    }
+
     const requestContext = createRequestContext(ctx, req, reply.raw, resolvedWebviewDir, resolvedIndexHtml)
 
     await dispatchRequest(requestContext, middlewareHandlers)
@@ -334,7 +348,7 @@ export function startServer(kanbanDir: string, port: number, webviewDir?: string
       console.error('Failed to start server:', err)
       process.exit(1)
     }
-    console.log(`Kanban board running at http://localhost:${port}`)
+    console.log(`Kanban board running at http://localhost:${port}${basePath}`)
     console.log(`API available at http://localhost:${port}/api`)
     console.log(`Kanban config: ${effectiveConfigPath}`)
     console.log(`Kanban directory: ${ctx.absoluteKanbanDir}`)

package/src/standalone/watcherSetup.ts

@@ -110,4 +110,13 @@ export function setupWatcher(ctx: StandaloneContext, server: http.Server): void
       ctx.wss.close()
     })
   }
+
+  // Watch .kanban.json for config changes and re-broadcast init on change
+  const configFilePath = path.join(ctx.workspaceRoot, '.kanban.json')
+  const configWatcher = chokidar.watch(configFilePath, {
+    ignoreInitial: true,
+    awaitWriteFinish: { stabilityThreshold: 100 }
+  })
+  configWatcher.on('change', () => handleFileChange(ctx, debounceRef))
+  server.on('close', () => configWatcher.close())
 }

package/src/webview/standalone-shim.ts

@@ -6,7 +6,8 @@ import type { ConnectionStatusMessage, ExtensionMessage, WebviewMessage } from '
 
 if (!('acquireVsCodeApi' in window)) {
 
-const WS_URL = `ws://${window.location.host}/ws`
+const kbBase = (window as unknown as { __KB_BASE__?: string }).__KB_BASE__ ?? ''
+const WS_URL = `${window.location.protocol === 'https:' ? 'wss' : 'ws'}://${window.location.host}${kbBase}/ws`
 const RECONNECT_DELAYS_MS = [250, 500, 1000, 2000, 4000] as const
 const MAX_RETRIES = RECONNECT_DELAYS_MS.length