feat(web): surface KB location — create-path preview, custom path, KB-root setting

- CreateKbDialog shows a live "Will be created at <root>/<name>" preview (fetched
  from /api/v1/kbs root) and an optional Custom path field that overrides it.
- Settings › General adds a Knowledge base root field (top-level kb_root merge-patch;
  empty -> null/default) with a note when it's pinned by OPENKB_KB_ROOT.
- KbList cards show each KB's path (now that KBs can live outside the root).

Claude-Session: https://claude.ai/code/session_01XMxbhmAkxxVV8CFWCZDBaG

Author: KylinMountain

frontend/src/api/config.ts

@@ -11,6 +11,11 @@ export interface GlobalConfig {
   openai_api_base?: string | null
   /** Presence flag only — the raw key value is NEVER returned by the API. */
   has_api_key?: boolean
+  /** Effective KB root directory — where `<root>/<name>` KBs are created. */
+  kb_root: string
+  /** True when OPENKB_KB_ROOT is set in the environment, which overrides any
+   *  UI-set root; edits here won't take effect until the env var is unset. */
+  kb_root_env_pinned?: boolean
 }
 
 /**
@@ -28,6 +33,9 @@ export interface GlobalConfigPatch {
   }
   api_key?: string | null
   openai_api_base?: string | null
+  /** Effective KB root. A value sets it; `null` (or empty) reverts to the
+   *  built-in default. Placed top-level, mirroring api_key/openai_api_base. */
+  kb_root?: string | null
 }
 
 export function getGlobalConfig(): Promise<GlobalConfig> {

frontend/src/api/kb.ts

@@ -5,6 +5,8 @@ export interface KbSummary {
   document_count: number
   last_compile: string | null
   has_raw: boolean
+  /** Absolute directory of this KB (may sit outside the default root). */
+  path?: string
 }
 
 export interface KbListResponse {
@@ -18,12 +20,14 @@ export function listKbs(): Promise<KbListResponse> {
 
 /** Body for POST /api/v1/init. Only `kb` is required; model/credentials are
  *  omitted here and left to inherit global defaults (set later via the per-KB
- *  gear / KbSettingsSheet). */
+ *  gear / KbSettingsSheet). When `path` is given, the KB is created at that
+ *  absolute directory instead of the default `<root>/<name>`. */
 export interface InitRequest {
   kb: string
   model?: string
   api_key?: string
   openai_api_base?: string
+  path?: string
 }
 
 export interface InitResponse {

frontend/src/components/CreateKbDialog.tsx

@@ -3,8 +3,9 @@ import { useNavigate } from 'react-router'
 import { useTranslation } from 'react-i18next'
 import * as Dialog from '@radix-ui/react-dialog'
 import { AnimatePresence, motion, useReducedMotion } from 'motion/react'
-import { Loader2, Plus } from 'lucide-react'
-import { createKb } from '@/api/kb'
+import { ChevronDown, Loader2, Plus } from 'lucide-react'
+import { createKb, listKbs } from '@/api/kb'
+import { cn } from '@/lib/utils'
 
 const errMsg = (e: unknown) => (e instanceof Error ? e.message : String(e))
 
@@ -26,36 +27,61 @@ export default function CreateKbDialog({ children }: { children: ReactNode }) {
   const [name, setName] = useState('')
   const [error, setError] = useState<string | null>(null)
   const [submitting, setSubmitting] = useState(false)
+  // Effective KB root, fetched on open, used to render the live target-path
+  // preview (`<root>/<name>`). Null until the fetch lands (or if it fails).
+  const [root, setRoot] = useState<string | null>(null)
+  // Optional advanced override: an absolute directory to create the KB at
+  // instead of `<root>/<name>`. Hidden behind the "Custom path" toggle.
+  const [customPath, setCustomPath] = useState('')
+  const [showAdvanced, setShowAdvanced] = useState(false)
 
   // Reset transient form state on every open/close so a reopened dialog is
   // clean and a Radix-initiated close (Escape / scrim) can't strand an error.
+  // On open we (re)fetch the KB root so the preview reflects the current root.
   const onOpenChange = useCallback((next: boolean) => {
     if (submitting) return
     setOpen(next)
     setName('')
     setError(null)
+    setCustomPath('')
+    setShowAdvanced(false)
+    if (next) {
+      setRoot(null)
+      listKbs()
+        .then((r) => setRoot(r.root))
+        .catch(() => setRoot(null))
+    }
   }, [submitting])
 
   const trimmed = name.trim()
+  const customTrimmed = customPath.trim()
+
+  // What the create will actually target: an explicit custom path wins;
+  // otherwise `<root>/<name>` (with an ellipsis stand-in before a name is typed).
+  const previewPath = customTrimmed || (root ? `${root}/${trimmed || '…'}` : '')
 
   const submit = useCallback(async () => {
     if (!trimmed || submitting) return
     setSubmitting(true)
     setError(null)
     try {
-      await createKb({ kb: trimmed })
+      const path = customPath.trim()
+      // Resolution is by name regardless of path, so navigation is unchanged.
+      await createKb(path ? { kb: trimmed, path } : { kb: trimmed })
       // Broadcast so any live KB list (e.g. AppSidebar) re-fetches without a
       // full reload; mirrors the old app's `openkb:reload-kbs` signal.
       window.dispatchEvent(new CustomEvent('openkb:reload-kbs'))
       setSubmitting(false)
       setOpen(false)
       setName('')
+      setCustomPath('')
+      setShowAdvanced(false)
       navigate(`/kb/${encodeURIComponent(trimmed)}`)
     } catch (e) {
       setError(errMsg(e))
       setSubmitting(false)
     }
-  }, [trimmed, submitting, navigate])
+  }, [trimmed, customPath, submitting, navigate])
 
   return (
     <Dialog.Root open={open} onOpenChange={onOpenChange}>
@@ -114,6 +140,49 @@ export default function CreateKbDialog({ children }: { children: ReactNode }) {
                       className="mt-1.5 w-full h-9 rounded-md border border-input bg-transparent px-3 text-[13px] font-mono2 outline-none focus-visible:ring-2 focus-visible:ring-ring focus:border-accent-brand"
                     />
 
+                    {/* Live target-path preview: `<root>/<name>`, or the custom
+                        path when one is set. Only shown once the root is known. */}
+                    {previewPath && (
+                      <p className="mt-1.5 text-[11.5px] text-muted-foreground font-mono2 break-all">
+                        {t('create.previewLabel', { path: previewPath })}
+                      </p>
+                    )}
+
+                    {/* Unobtrusive advanced override: a text toggle that reveals
+                        an absolute custom-path field; empty = use default root. */}
+                    <button
+                      type="button"
+                      onClick={() => setShowAdvanced((v) => !v)}
+                      disabled={submitting}
+                      className="mt-2.5 inline-flex items-center gap-1 text-[12px] font-medium text-muted-foreground hover:text-foreground transition-colors disabled:opacity-60"
+                    >
+                      <ChevronDown
+                        className={cn('w-3.5 h-3.5 transition-transform', showAdvanced && 'rotate-180')}
+                      />
+                      {t('create.advancedToggle')}
+                    </button>
+                    {showAdvanced && (
+                      <div className="mt-2">
+                        <label htmlFor="create-kb-path" className="text-[12px] font-medium text-muted-foreground">
+                          {t('create.customPathLabel')}
+                        </label>
+                        <input
+                          id="create-kb-path"
+                          value={customPath}
+                          disabled={submitting}
+                          onChange={(e) => {
+                            setCustomPath(e.target.value)
+                            if (error) setError(null)
+                          }}
+                          placeholder={t('create.customPathPlaceholder')}
+                          className="mt-1.5 w-full h-9 rounded-md border border-input bg-transparent px-3 text-[13px] font-mono2 outline-none focus-visible:ring-2 focus-visible:ring-ring focus:border-accent-brand"
+                        />
+                        <p className="mt-1.5 text-[11.5px] text-muted-foreground">
+                          {t('create.customPathHint')}
+                        </p>
+                      </div>
+                    )}
+
                     {error && (
                       <div className="mt-2.5 rounded-lg bg-red-50 dark:bg-red-500/10 border border-red-200/70 dark:border-red-500/25 px-3 py-2 text-[12.5px] text-red-600 dark:text-red-400">
                         {error}

frontend/src/locales/en/kbList.json

@@ -12,6 +12,11 @@
     "namePlaceholder": "e.g. my-kb",
     "cancel": "Cancel",
     "submit": "Create",
-    "submitting": "Creating…"
+    "submitting": "Creating…",
+    "previewLabel": "Will be created at {{path}}",
+    "advancedToggle": "Custom path",
+    "customPathLabel": "Custom path",
+    "customPathPlaceholder": "/absolute/path/to/kb",
+    "customPathHint": "Leave empty to use the default root"
   }
 }

frontend/src/locales/en/settings.json

@@ -19,7 +19,11 @@
     "undoClear": "Undo"
   },
   "general": {
-    "langDesc": "The output language written into the compile prompt, e.g. en / 中文 / 日本語"
+    "langDesc": "The output language written into the compile prompt, e.g. en / 中文 / 日本語",
+    "kbRootLabel": "Knowledge base root",
+    "kbRootDesc": "Default location for new knowledge bases (<root>/<name>); leave empty to restore the built-in default. Individual KBs can set a custom path at creation.",
+    "kbRootPlaceholder": "e.g. ~/openkb",
+    "kbRootEnvPinned": "Pinned by the OPENKB_KB_ROOT environment variable; edits here won't take effect until it's unset."
   },
   "conn": {
     "note": "Cloud data-source connectors (OAuth / S3) are in development and not yet available; for now, upload local files from the KB detail page. Want a connector? Click a card below to vote on GitHub and help us prioritize."

frontend/src/locales/zh/kbList.json

@@ -12,6 +12,11 @@
     "namePlaceholder": "例如 my-kb",
     "cancel": "取消",
     "submit": "创建",
-    "submitting": "创建中…"
+    "submitting": "创建中…",
+    "previewLabel": "将创建于 {{path}}",
+    "advancedToggle": "自定义路径",
+    "customPathLabel": "自定义路径",
+    "customPathPlaceholder": "/绝对/路径/到/知识库",
+    "customPathHint": "留空则使用默认根目录"
   }
 }

frontend/src/locales/zh/settings.json

@@ -19,7 +19,11 @@
     "undoClear": "撤销"
   },
   "general": {
-    "langDesc": "写入编译 prompt 的输出语言，例如 en / 中文 / 日本語"
+    "langDesc": "写入编译 prompt 的输出语言，例如 en / 中文 / 日本語",
+    "kbRootLabel": "知识库根目录",
+    "kbRootDesc": "新建知识库的默认位置（<根目录>/<名称>）；留空则恢复内置默认值。单个知识库可在创建时设置自定义路径。",
+    "kbRootPlaceholder": "例如 ~/openkb",
+    "kbRootEnvPinned": "已由环境变量 OPENKB_KB_ROOT 固定，此处的修改在取消该环境变量前不会生效。"
   },
   "conn": {
     "note": "云端数据源连接器（OAuth / S3）开发中，尚不可用；当前请在知识库详情页手动上传本地文件。想要某个连接器？点下方卡片去 GitHub 投票，帮我们排优先级。"

frontend/src/pages/KbList.tsx

@@ -55,6 +55,14 @@ export default function KbList() {
                 <span className="text-[16px] font-bold text-foreground">{kb.name}</span>
               </div>
 
+              {/* Directory in small muted mono so scattered (custom-path) KBs
+                  stay legible. `title` exposes the full path when truncated. */}
+              {kb.path && (
+                <div className="mt-1.5 text-[11px] text-muted-foreground font-mono2 truncate" title={kb.path}>
+                  {kb.path}
+                </div>
+              )}
+
               <div className="mt-4">
                 <div className="inline-flex items-center gap-3 rounded-xl bg-muted/50 border border-[hsl(var(--glass-border))] px-3.5 py-2.5">
                   <FileText className="w-4 h-4 text-muted-foreground" />

frontend/src/pages/Settings.tsx

@@ -39,6 +39,9 @@ export default function Settings() {
   const [model, setModel] = useState('')
   const [language, setLanguage] = useState('')
   const [threshold, setThreshold] = useState('')
+  // KB root directory. Emptying a previously-set root clears it (null → default),
+  // mirroring the credential-base's empty→null discipline in buildPatch.
+  const [kbRoot, setKbRoot] = useState('')
   // Global-default credentials (written to ~/.config/openkb/.env). The API key
   // is write-only: its value is never fetched, so the input starts empty and a
   // non-empty value means "rotate". `clearKey` defers an explicit-null removal
@@ -55,6 +58,7 @@ export default function Settings() {
     setModel(c.model)
     setLanguage(c.language)
     setThreshold(String(c.pageindex_threshold))
+    setKbRoot(c.kb_root ?? '')
     setApiBase(c.openai_api_base ?? '')
     setApiKey('')
     setClearKey(false)
@@ -97,13 +101,16 @@ export default function Settings() {
       cfg.pageindex_threshold = n
     }
     if (Object.keys(cfg).length > 0) patch.config = cfg
+    const rootTrim = kbRoot.trim()
+    const currentRoot = config.kb_root ?? ''
+    if (rootTrim !== currentRoot) patch.kb_root = rootTrim === '' ? null : rootTrim
     const baseTrim = apiBase.trim()
     const currentBase = config.openai_api_base ?? ''
     if (baseTrim !== currentBase) patch.openai_api_base = baseTrim === '' ? null : baseTrim
     if (clearKey) patch.api_key = null
     else if (apiKey !== '') patch.api_key = apiKey
     return { patch, dirty: Object.keys(patch).length > 0 }
-  }, [config, model, language, threshold, apiBase, apiKey, clearKey])
+  }, [config, model, language, threshold, kbRoot, apiBase, apiKey, clearKey])
 
   const dirty = useMemo(() => buildPatch().dirty, [buildPatch])
 
@@ -279,6 +286,21 @@ export default function Settings() {
                 />
                 <UnLanguageDatalist />
               </div>
+
+              <div>
+                <label className="text-[13px] font-semibold text-foreground">{t('settings:general.kbRootLabel')}</label>
+                <p className="mt-0.5 text-[12px] text-muted-foreground">{t('settings:general.kbRootDesc')}</p>
+                <input
+                  value={kbRoot}
+                  disabled={loading || !config}
+                  onChange={(e) => setKbRoot(e.target.value)}
+                  placeholder={t('settings:general.kbRootPlaceholder')}
+                  className={cn(inputCls, 'max-w-[420px]')}
+                />
+                {config?.kb_root_env_pinned && (
+                  <p className="mt-1.5 text-[11.5px] text-muted-foreground">{t('settings:general.kbRootEnvPinned')}</p>
+                )}
+              </div>
             </div>
 
             <SaveBar dirty={dirty} saving={saving} onSave={save} disabled={loading || !config} />