From 14ac03b55105e8e66133a33dfc8d8fe4445f52da Mon Sep 17 00:00:00 2001
From: hzhang <hzhang@hangman-lab.top>
Date: Sun, 31 May 2026 15:03:50 +0100
Subject: [PATCH] =?UTF-8?q?feat(knowledge-base):=20Knowledge=20Base=20UI?=
 =?UTF-8?q?=20=E2=80=94=20browse/edit,=20modal,=20project=20links?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Knowledge Bases list page + sidebar entry + "+ New" create modal
- Detail page with a recursive structure tree: add/edit/delete topics,
  categories and facts inline, including name + description editing
- Create/metadata-edit modal (title, description)
- Project edit modal gains a link/remove knowledge base section
- Types and routes for /knowledge-bases and /knowledge-bases/:id
- Scoped .kb-* styles (contained panel, topic cards, hierarchy guides)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 src/App.tsx                               |   4 +
 src/components/KnowledgeBaseFormModal.tsx | 104 ++++++++
 src/components/KnowledgeBaseTree.tsx      | 275 ++++++++++++++++++++++
 src/components/ProjectFormModal.tsx       |  78 +++++-
 src/components/Sidebar.tsx                |   1 +
 src/index.css                             | 124 ++++++++++
 src/pages/KnowledgeBaseDetailPage.tsx     |  87 +++++++
 src/pages/KnowledgeBasesPage.tsx          |  51 ++++
 src/types/index.ts                        |  45 ++++
 9 files changed, 768 insertions(+), 1 deletion(-)
 create mode 100644 src/components/KnowledgeBaseFormModal.tsx
 create mode 100644 src/components/KnowledgeBaseTree.tsx
 create mode 100644 src/pages/KnowledgeBaseDetailPage.tsx
 create mode 100644 src/pages/KnowledgeBasesPage.tsx

diff --git a/src/App.tsx b/src/App.tsx
index 964d63c..0a0322a 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -8,6 +8,8 @@ import TasksPage from '@/pages/TasksPage'
 import TaskDetailPage from '@/pages/TaskDetailPage'
 import ProjectsPage from '@/pages/ProjectsPage'
 import ProjectDetailPage from '@/pages/ProjectDetailPage'
+import KnowledgeBasesPage from '@/pages/KnowledgeBasesPage'
+import KnowledgeBaseDetailPage from '@/pages/KnowledgeBaseDetailPage'
 import MilestonesPage from '@/pages/MilestonesPage'
 import MilestoneDetailPage from '@/pages/MilestoneDetailPage'
 import NotificationsPage from '@/pages/NotificationsPage'
@@ -130,6 +132,8 @@ export default function App() {
             <Route path="/tasks/:taskCode" element={<TaskDetailPage />} />
             <Route path="/projects" element={<ProjectsPage />} />
             <Route path="/projects/:id" element={<ProjectDetailPage />} />
+            <Route path="/knowledge-bases" element={<KnowledgeBasesPage />} />
+            <Route path="/knowledge-bases/:id" element={<KnowledgeBaseDetailPage />} />
             <Route path="/milestones" element={<MilestonesPage />} />
             <Route path="/milestones/:milestoneCode" element={<MilestoneDetailPage />} />
             <Route path="/proposals" element={<ProposalsPage />} />
diff --git a/src/components/KnowledgeBaseFormModal.tsx b/src/components/KnowledgeBaseFormModal.tsx
new file mode 100644
index 0000000..e15e7b7
--- /dev/null
+++ b/src/components/KnowledgeBaseFormModal.tsx
@@ -0,0 +1,104 @@
+import { useEffect, useState } from 'react'
+import api from '@/services/api'
+import type { KnowledgeBase } from '@/types'
+
+type Props = {
+  isOpen: boolean
+  onClose: () => void
+  onSaved?: (kb: KnowledgeBase) => void | Promise<void>
+  knowledgeBase?: KnowledgeBase | null
+}
+
+type FormState = {
+  title: string
+  description: string
+}
+
+const emptyForm: FormState = { title: '', description: '' }
+
+export default function KnowledgeBaseFormModal({ isOpen, onClose, onSaved, knowledgeBase }: Props) {
+  const [saving, setSaving] = useState(false)
+  const [error, setError] = useState('')
+  const [form, setForm] = useState<FormState>(emptyForm)
+
+  useEffect(() => {
+    if (!isOpen) return
+    setError('')
+    if (knowledgeBase) {
+      setForm({ title: knowledgeBase.title, description: knowledgeBase.description || '' })
+    } else {
+      setForm(emptyForm)
+    }
+  }, [isOpen, knowledgeBase])
+
+  const submit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    setSaving(true)
+    setError('')
+    try {
+      if (knowledgeBase) {
+        const { data } = await api.patch<KnowledgeBase>(`/knowledge-bases/${knowledgeBase.id}`, {
+          title: form.title,
+          description: form.description || null,
+        })
+        await onSaved?.(data)
+      } else {
+        const { data } = await api.post<KnowledgeBase>('/knowledge-bases', {
+          title: form.title,
+          description: form.description || null,
+        })
+        await onSaved?.(data)
+      }
+      onClose()
+    } catch (err: any) {
+      setError(err?.response?.data?.detail || 'Failed to save knowledge base')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  if (!isOpen) return null
+
+  return (
+    <div className="modal-overlay" onClick={onClose}>
+      <div className="modal" onClick={(e) => e.stopPropagation()}>
+        <div className="modal-header">
+          <h3>{knowledgeBase ? 'Edit Knowledge Base' : 'Create Knowledge Base'}</h3>
+          <button type="button" className="btn-secondary" onClick={onClose}>✕</button>
+        </div>
+
+        <form className="task-create-form" onSubmit={submit}>
+          <label>
+            Title
+            <input
+              data-testid="kb-title-input"
+              required
+              placeholder="Knowledge base title"
+              value={form.title}
+              onChange={(e) => setForm((f) => ({ ...f, title: e.target.value }))}
+            />
+          </label>
+
+          <label>
+            Description
+            <textarea
+              data-testid="kb-description-input"
+              placeholder="Description (optional)"
+              value={form.description}
+              onChange={(e) => setForm((f) => ({ ...f, description: e.target.value }))}
+            />
+          </label>
+
+          {error && <p className="error-text" style={{ color: 'var(--danger, #e5534b)' }}>{error}</p>}
+
+          <div className="modal-actions">
+            <button type="submit" className="btn-primary" disabled={saving}>
+              {saving ? 'Saving...' : (knowledgeBase ? 'Save' : 'Create')}
+            </button>
+            <button type="button" className="btn-secondary" onClick={onClose} disabled={saving}>Cancel</button>
+          </div>
+        </form>
+      </div>
+    </div>
+  )
+}
diff --git a/src/components/KnowledgeBaseTree.tsx b/src/components/KnowledgeBaseTree.tsx
new file mode 100644
index 0000000..4a4811e
--- /dev/null
+++ b/src/components/KnowledgeBaseTree.tsx
@@ -0,0 +1,275 @@
+import { useState } from 'react'
+import api from '@/services/api'
+import type { KnowledgeBaseTree as Tree, KnowledgeTopicNode, KnowledgeCategoryNode, KnowledgeFact } from '@/types'
+
+type Reload = () => void | Promise<void>
+
+function errMsg(err: any, fallback: string): string {
+  return err?.response?.data?.detail || fallback
+}
+
+/** A toggle button that reveals a single-line input with save/cancel. */
+function InlineForm({ label, placeholder, onSubmit }: {
+  label: string
+  placeholder: string
+  onSubmit: (value: string) => Promise<void>
+}) {
+  const [open, setOpen] = useState(false)
+  const [value, setValue] = useState('')
+  const [busy, setBusy] = useState(false)
+
+  if (!open) {
+    return <button className="kb-mini-btn" onClick={() => { setValue(''); setOpen(true) }}>{label}</button>
+  }
+  const save = async () => {
+    if (!value.trim()) return
+    setBusy(true)
+    try { await onSubmit(value.trim()); setOpen(false) }
+    finally { setBusy(false) }
+  }
+  return (
+    <span className="kb-inline-form">
+      <input
+        autoFocus
+        placeholder={placeholder}
+        value={value}
+        disabled={busy}
+        onChange={(e) => setValue(e.target.value)}
+        onKeyDown={(e) => { if (e.key === 'Enter') save(); if (e.key === 'Escape') setOpen(false) }}
+      />
+      <button className="kb-mini-btn" disabled={busy} onClick={save}>✓</button>
+      <button className="kb-mini-btn" disabled={busy} onClick={() => setOpen(false)}>✕</button>
+    </span>
+  )
+}
+
+/** Inline editor for a node's name + description (used by topics & categories). */
+function NodeEditForm({ initialName, initialDesc, namePlaceholder, onSave, onCancel }: {
+  initialName: string
+  initialDesc: string
+  namePlaceholder: string
+  onSave: (name: string, description: string) => Promise<void>
+  onCancel: () => void
+}) {
+  const [name, setName] = useState(initialName)
+  const [desc, setDesc] = useState(initialDesc)
+  const [busy, setBusy] = useState(false)
+
+  const save = async () => {
+    if (!name.trim()) return
+    setBusy(true)
+    try { await onSave(name.trim(), desc) } finally { setBusy(false) }
+  }
+  return (
+    <div className="kb-edit-form">
+      <input
+        autoFocus
+        placeholder={namePlaceholder}
+        value={name}
+        disabled={busy}
+        onChange={(e) => setName(e.target.value)}
+        onKeyDown={(e) => { if (e.key === 'Enter') save(); if (e.key === 'Escape') onCancel() }}
+      />
+      <textarea
+        placeholder="Description (optional)"
+        rows={2}
+        value={desc}
+        disabled={busy}
+        onChange={(e) => setDesc(e.target.value)}
+      />
+      <span className="kb-row-actions">
+        <button className="kb-mini-btn" disabled={busy} onClick={save}>save</button>
+        <button className="kb-mini-btn" disabled={busy} onClick={onCancel}>cancel</button>
+      </span>
+    </div>
+  )
+}
+
+function FactRow({ fact, onChange }: { fact: KnowledgeFact; onChange: Reload }) {
+  const [editing, setEditing] = useState(false)
+  const [value, setValue] = useState(fact.fact)
+
+  const save = async () => {
+    try {
+      await api.patch(`/knowledge-facts/${fact.id}`, { fact: value })
+      setEditing(false)
+      await onChange()
+    } catch (err) { alert(errMsg(err, 'Failed to update fact')) }
+  }
+  const remove = async () => {
+    if (!confirm('Delete this fact?')) return
+    try { await api.delete(`/knowledge-facts/${fact.id}`); await onChange() }
+    catch (err) { alert(errMsg(err, 'Failed to delete fact')) }
+  }
+
+  return (
+    <div className="kb-fact">
+      <span className="kb-bullet">•</span>
+      {editing ? (
+        <span className="kb-inline-form kb-inline-grow">
+          <input autoFocus value={value} onChange={(e) => setValue(e.target.value)}
+            onKeyDown={(e) => { if (e.key === 'Enter') save(); if (e.key === 'Escape') setEditing(false) }} />
+          <button className="kb-mini-btn" onClick={save}>✓</button>
+          <button className="kb-mini-btn" onClick={() => { setValue(fact.fact); setEditing(false) }}>✕</button>
+        </span>
+      ) : (
+        <>
+          <span className="kb-fact-text">{fact.fact}</span>
+          <span className="kb-row-actions">
+            <button className="kb-mini-btn" onClick={() => setEditing(true)}>edit</button>
+            <button className="kb-mini-btn kb-danger" onClick={remove}>del</button>
+          </span>
+        </>
+      )}
+    </div>
+  )
+}
+
+function CategoryNode({ cat, onChange }: { cat: KnowledgeCategoryNode; onChange: Reload }) {
+  const [editing, setEditing] = useState(false)
+
+  const saveEdit = async (name: string, description: string) => {
+    try {
+      await api.patch(`/knowledge-categories/${cat.id}`, { name, description: description || null })
+      setEditing(false)
+      await onChange()
+    } catch (err) { alert(errMsg(err, 'Failed to update category')) }
+  }
+  const remove = async () => {
+    if (!confirm('Delete this category and everything under it?')) return
+    try { await api.delete(`/knowledge-categories/${cat.id}`); await onChange() }
+    catch (err) { alert(errMsg(err, 'Failed to delete category')) }
+  }
+  const addSubcategory = async (value: string) => {
+    try { await api.post('/knowledge-categories', { topic_id: cat.topic_id, parent: cat.id, name: value }); await onChange() }
+    catch (err) { alert(errMsg(err, 'Failed to add category')) }
+  }
+  const addFact = async (value: string) => {
+    try { await api.post('/knowledge-facts', { topic_id: cat.topic_id, category_id: cat.id, fact: value }); await onChange() }
+    catch (err) { alert(errMsg(err, 'Failed to add fact')) }
+  }
+
+  return (
+    <div className="kb-node kb-category">
+      {editing ? (
+        <div className="kb-node-header">
+          <NodeEditForm
+            initialName={cat.name}
+            initialDesc={cat.description || ''}
+            namePlaceholder="Category name"
+            onSave={saveEdit}
+            onCancel={() => setEditing(false)}
+          />
+        </div>
+      ) : (
+        <>
+          <div className="kb-node-header">
+            <span className="kb-node-title">📂 {cat.name}</span>
+            <span className="kb-row-actions">
+              <InlineForm label="+ category" placeholder="Category name" onSubmit={addSubcategory} />
+              <InlineForm label="+ fact" placeholder="Fact" onSubmit={addFact} />
+              <button className="kb-mini-btn" onClick={() => setEditing(true)}>edit</button>
+              <button className="kb-mini-btn kb-danger" onClick={remove}>del</button>
+            </span>
+          </div>
+          {cat.description && <div className="kb-node-desc">{cat.description}</div>}
+        </>
+      )}
+      <div className="kb-children">
+        {cat.facts.map((f) => <FactRow key={f.id} fact={f} onChange={onChange} />)}
+        {cat.categories.map((c) => <CategoryNode key={c.id} cat={c} onChange={onChange} />)}
+      </div>
+    </div>
+  )
+}
+
+function TopicNode({ topic, onChange }: { topic: KnowledgeTopicNode; onChange: Reload }) {
+  const [editing, setEditing] = useState(false)
+
+  const saveEdit = async (name: string, description: string) => {
+    try {
+      await api.patch(`/knowledge-topics/${topic.id}`, { topic: name, description: description || null })
+      setEditing(false)
+      await onChange()
+    } catch (err) { alert(errMsg(err, 'Failed to update topic')) }
+  }
+  const remove = async () => {
+    if (!confirm('Delete this topic and everything under it?')) return
+    try { await api.delete(`/knowledge-topics/${topic.id}`); await onChange() }
+    catch (err) { alert(errMsg(err, 'Failed to delete topic')) }
+  }
+  const addCategory = async (value: string) => {
+    try { await api.post('/knowledge-categories', { topic_id: topic.id, name: value }); await onChange() }
+    catch (err) { alert(errMsg(err, 'Failed to add category')) }
+  }
+  const addFact = async (value: string) => {
+    try { await api.post('/knowledge-facts', { topic_id: topic.id, fact: value }); await onChange() }
+    catch (err) { alert(errMsg(err, 'Failed to add fact')) }
+  }
+
+  return (
+    <div className="kb-node kb-topic">
+      {editing ? (
+        <div className="kb-node-header">
+          <NodeEditForm
+            initialName={topic.topic}
+            initialDesc={topic.description || ''}
+            namePlaceholder="Topic name"
+            onSave={saveEdit}
+            onCancel={() => setEditing(false)}
+          />
+        </div>
+      ) : (
+        <>
+          <div className="kb-node-header">
+            <span className="kb-node-title kb-topic-title"># {topic.topic}</span>
+            <span className="kb-row-actions">
+              <InlineForm label="+ category" placeholder="Category name" onSubmit={addCategory} />
+              <InlineForm label="+ fact" placeholder="Fact" onSubmit={addFact} />
+              <button className="kb-mini-btn" onClick={() => setEditing(true)}>edit</button>
+              <button className="kb-mini-btn kb-danger" onClick={remove}>del</button>
+            </span>
+          </div>
+          {topic.description && <div className="kb-node-desc">{topic.description}</div>}
+        </>
+      )}
+      <div className="kb-children">
+        {topic.facts.map((f) => <FactRow key={f.id} fact={f} onChange={onChange} />)}
+        {topic.categories.map((c) => <CategoryNode key={c.id} cat={c} onChange={onChange} />)}
+      </div>
+    </div>
+  )
+}
+
+export default function KnowledgeBaseTree({ tree, onChange }: { tree: Tree; onChange: Reload }) {
+  const [addingTopic, setAddingTopic] = useState(false)
+  const [topicName, setTopicName] = useState('')
+
+  const addTopic = async () => {
+    if (!topicName.trim()) return
+    try {
+      await api.post(`/knowledge-bases/${tree.id}/topics`, { topic: topicName.trim() })
+      setTopicName(''); setAddingTopic(false)
+      await onChange()
+    } catch (err) { alert(errMsg(err, 'Failed to add topic')) }
+  }
+
+  return (
+    <div className="kb-tree">
+      <div className="kb-tree-toolbar">
+        {addingTopic ? (
+          <span className="kb-inline-form">
+            <input autoFocus placeholder="Topic name" value={topicName} onChange={(e) => setTopicName(e.target.value)}
+              onKeyDown={(e) => { if (e.key === 'Enter') addTopic(); if (e.key === 'Escape') setAddingTopic(false) }} />
+            <button className="kb-mini-btn" onClick={addTopic}>✓</button>
+            <button className="kb-mini-btn" onClick={() => setAddingTopic(false)}>✕</button>
+          </span>
+        ) : (
+          <button className="btn-secondary" onClick={() => setAddingTopic(true)}>+ Add topic</button>
+        )}
+      </div>
+      {tree.topics.length === 0 && <p className="empty">No topics yet. Add one above.</p>}
+      {tree.topics.map((t) => <TopicNode key={t.id} topic={t} onChange={onChange} />)}
+    </div>
+  )
+}
diff --git a/src/components/ProjectFormModal.tsx b/src/components/ProjectFormModal.tsx
index b450303..f3e4713 100644
--- a/src/components/ProjectFormModal.tsx
+++ b/src/components/ProjectFormModal.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useMemo, useState } from 'react'
 import api from '@/services/api'
-import type { Project, User } from '@/types'
+import type { Project, User, KnowledgeBase } from '@/types'
 
 type Props = {
   isOpen: boolean
@@ -34,6 +34,15 @@ export default function ProjectFormModal({ isOpen, onClose, onSaved, project }:
   const [projects, setProjects] = useState<Project[]>([])
   const [saving, setSaving] = useState(false)
   const [form, setForm] = useState<FormState>(emptyForm)
+  const [allKBs, setAllKBs] = useState<KnowledgeBase[]>([])
+  const [linkedKBs, setLinkedKBs] = useState<KnowledgeBase[]>([])
+  const [kbToLink, setKbToLink] = useState('')
+
+  const refreshLinkedKBs = async () => {
+    if (!project) return
+    const { data } = await api.get<KnowledgeBase[]>(`/projects/${project.id}/knowledge-bases`)
+    setLinkedKBs(data)
+  }
 
   useEffect(() => {
     if (!isOpen) return
@@ -46,6 +55,21 @@ export default function ProjectFormModal({ isOpen, onClose, onSaved, project }:
       setUsers(userData)
       setProjects(projectData)
 
+      // Knowledge-base linking is only meaningful for an existing project.
+      if (project) {
+        try {
+          const [{ data: kbs }, { data: linked }] = await Promise.all([
+            api.get<KnowledgeBase[]>('/knowledge-bases'),
+            api.get<KnowledgeBase[]>(`/projects/${project.id}/knowledge-bases`),
+          ])
+          setAllKBs(kbs)
+          setLinkedKBs(linked)
+        } catch {
+          setAllKBs([])
+          setLinkedKBs([])
+        }
+      }
+
       if (project) {
         setForm({
           name: project.name,
@@ -79,6 +103,32 @@ export default function ProjectFormModal({ isOpen, onClose, onSaved, project }:
     setForm((f) => ({ ...f, [field]: values }))
   }
 
+  const linkableKBs = useMemo(
+    () => allKBs.filter((kb) => !linkedKBs.some((l) => l.id === kb.id)),
+    [allKBs, linkedKBs]
+  )
+
+  const linkKB = async () => {
+    if (!project || !kbToLink) return
+    try {
+      await api.post(`/projects/${project.id}/knowledge-bases`, { knowledge_base: kbToLink })
+      setKbToLink('')
+      await refreshLinkedKBs()
+    } catch (err: any) {
+      alert(err?.response?.data?.detail || 'Failed to link knowledge base')
+    }
+  }
+
+  const unlinkKB = async (kbId: number) => {
+    if (!project) return
+    try {
+      await api.delete(`/projects/${project.id}/knowledge-bases/${kbId}`)
+      await refreshLinkedKBs()
+    } catch (err: any) {
+      alert(err?.response?.data?.detail || 'Failed to unlink knowledge base')
+    }
+  }
+
   const submit = async (e: React.FormEvent) => {
     e.preventDefault()
     setSaving(true)
@@ -193,6 +243,32 @@ export default function ProjectFormModal({ isOpen, onClose, onSaved, project }:
             </select>
           </label>
 
+          {project && (
+            <div className="kb-link-section">
+              <label style={{ marginBottom: 4 }}>Knowledge Bases</label>
+              {linkedKBs.length === 0 && <p className="text-dim" style={{ margin: '4px 0' }}>None linked.</p>}
+              <ul className="kb-link-list">
+                {linkedKBs.map((kb) => (
+                  <li key={kb.id}>
+                    <span>{kb.knowledge_base_code ? `${kb.knowledge_base_code} · ` : ''}{kb.title}</span>
+                    <button type="button" className="kb-mini-btn kb-danger" onClick={() => unlinkKB(kb.id)}>remove</button>
+                  </li>
+                ))}
+              </ul>
+              <div className="kb-link-add">
+                <select value={kbToLink} onChange={(e) => setKbToLink(e.target.value)}>
+                  <option value="">— select a knowledge base —</option>
+                  {linkableKBs.map((kb) => (
+                    <option key={kb.id} value={kb.knowledge_base_code || String(kb.id)}>
+                      {kb.knowledge_base_code ? `${kb.knowledge_base_code} · ` : ''}{kb.title}
+                    </option>
+                  ))}
+                </select>
+                <button type="button" className="btn-secondary" disabled={!kbToLink} onClick={linkKB}>Link</button>
+              </div>
+            </div>
+          )}
+
           <div className="modal-actions">
             <button type="submit" className="btn-primary" disabled={saving}>{saving ? 'Saving...' : (project ? 'Save' : 'Create')}</button>
             <button type="button" className="btn-secondary" onClick={onClose} disabled={saving}>Cancel</button>
diff --git a/src/components/Sidebar.tsx b/src/components/Sidebar.tsx
index 8d995aa..660c278 100644
--- a/src/components/Sidebar.tsx
+++ b/src/components/Sidebar.tsx
@@ -35,6 +35,7 @@ export default function Sidebar({ user, onLogout }: Props) {
   const links = user ? [
     { to: '/', icon: '📊', label: 'Dashboard' },
     { to: '/projects', icon: '📁', label: 'Projects' },
+    { to: '/knowledge-bases', icon: '📚', label: 'Knowledge Bases' },
     { to: '/proposals', icon: '💡', label: 'Proposals' },
     { to: '/calendar', icon: '📅', label: 'Calendar' },
     { to: '/notifications', icon: '🔔', label: 'Notifications' + (unreadCount > 0 ? ' (' + unreadCount + ')' : '') },
diff --git a/src/index.css b/src/index.css
index d99a9b1..11ce3aa 100644
--- a/src/index.css
+++ b/src/index.css
@@ -708,3 +708,127 @@ dd { font-size: .92rem; font-family: 'JetBrains Mono', monospace; }
   .main-content { padding: 22px 18px; }
   .task-create-grid { grid-template-columns: 1fr; }
 }
+
+/* ── Knowledge Base tree (browse + structure edit) ───────────────────── */
+.kb-tree {
+  background: var(--bg-card);
+  border: var(--hair);
+  border-radius: 8px;
+  padding: 16px 18px;
+  max-width: 960px;
+}
+.kb-tree-toolbar { margin-bottom: 14px; }
+
+.kb-node { margin: 0; }
+
+/* Each topic is a self-contained block */
+.kb-topic {
+  border: var(--hair);
+  border-radius: 6px;
+  background: var(--bg-sink);
+  padding: 10px 14px;
+  margin-bottom: 12px;
+}
+.kb-topic:last-child { margin-bottom: 0; }
+
+.kb-node-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+  min-height: 30px;
+}
+.kb-node-title { color: var(--text); font-weight: 600; font-size: .94rem; }
+.kb-topic-title {
+  color: var(--accent);
+  font-family: 'Saira Condensed', sans-serif;
+  text-transform: uppercase;
+  letter-spacing: .05em;
+  font-size: 1.05rem;
+  font-weight: 700;
+}
+.kb-category > .kb-node-header > .kb-node-title { color: var(--steel); }
+
+/* Nested children indent under a guide line */
+.kb-children {
+  margin: 6px 0 0 6px;
+  padding-left: 16px;
+  border-left: 2px solid var(--border);
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.kb-category { padding: 3px 0; }
+
+.kb-fact {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 6px;
+  font-size: .9rem;
+  color: var(--text);
+  border-radius: var(--radius);
+}
+.kb-fact:hover { background: var(--bg-hover); }
+.kb-bullet { color: var(--accent); }
+.kb-fact-text { flex: 1; min-width: 0; word-break: break-word; }
+.kb-row-actions { display: inline-flex; gap: 6px; align-items: center; flex-wrap: wrap; margin-left: auto; }
+/* reveal node actions on hover to keep the tree calm */
+.kb-node-header .kb-row-actions,
+.kb-fact .kb-row-actions { opacity: 0; transition: opacity .12s; }
+.kb-node-header:hover .kb-row-actions,
+.kb-topic:hover > .kb-node-header > .kb-row-actions,
+.kb-fact:hover .kb-row-actions { opacity: 1; }
+.kb-mini-btn {
+  background: transparent;
+  border: var(--hair);
+  color: var(--text-dim);
+  border-radius: var(--radius);
+  padding: 2px 8px;
+  font-size: .78rem;
+  cursor: pointer;
+  transition: .12s;
+  white-space: nowrap;
+}
+.kb-mini-btn:hover { border-color: var(--accent); color: var(--accent); }
+.kb-mini-btn.kb-danger:hover { border-color: var(--danger); color: var(--danger); }
+.kb-mini-btn:disabled { opacity: .5; cursor: default; }
+.kb-inline-form { display: inline-flex; gap: 4px; align-items: center; }
+.kb-inline-form input {
+  background: var(--bg-sink);
+  border: var(--hair);
+  color: var(--text);
+  border-radius: var(--radius);
+  padding: 2px 8px;
+  font-size: .9rem;
+}
+.kb-inline-grow { flex: 1; }
+.kb-inline-grow input { flex: 1; }
+
+/* Project-modal: linked knowledge bases */
+.kb-link-section { border-top: var(--hair); padding-top: 12px; margin-top: 4px; }
+.kb-link-list { list-style: none; padding: 0; margin: 6px 0; display: flex; flex-direction: column; gap: 4px; }
+.kb-link-list li { display: flex; align-items: center; justify-content: space-between; gap: 8px; font-size: .9rem; }
+.kb-link-add { display: flex; gap: 8px; align-items: center; margin-top: 6px; }
+.kb-link-add select { flex: 1; }
+
+/* KB node edit form (name + description) and description display */
+.kb-edit-form { display: flex; flex-direction: column; gap: 6px; width: 100%; max-width: 560px; }
+.kb-edit-form input,
+.kb-edit-form textarea {
+  background: var(--bg-sink);
+  border: var(--hair);
+  color: var(--text);
+  border-radius: var(--radius);
+  padding: 4px 8px;
+  font: inherit;
+  font-size: .9rem;
+}
+.kb-edit-form textarea { resize: vertical; }
+.kb-node-desc {
+  color: var(--text-dim);
+  font-size: .85rem;
+  margin: 4px 0 2px 22px;
+  white-space: pre-wrap;
+  line-height: 1.45;
+}
diff --git a/src/pages/KnowledgeBaseDetailPage.tsx b/src/pages/KnowledgeBaseDetailPage.tsx
new file mode 100644
index 0000000..47757c5
--- /dev/null
+++ b/src/pages/KnowledgeBaseDetailPage.tsx
@@ -0,0 +1,87 @@
+import { useCallback, useEffect, useState } from 'react'
+import { useNavigate, useParams } from 'react-router-dom'
+import api from '@/services/api'
+import type { KnowledgeBase, KnowledgeBaseTree as Tree } from '@/types'
+import KnowledgeBaseTree from '@/components/KnowledgeBaseTree'
+import KnowledgeBaseFormModal from '@/components/KnowledgeBaseFormModal'
+
+export default function KnowledgeBaseDetailPage() {
+  const { id } = useParams<{ id: string }>()
+  const navigate = useNavigate()
+  const [kb, setKb] = useState<KnowledgeBase | null>(null)
+  const [tree, setTree] = useState<Tree | null>(null)
+  const [showEdit, setShowEdit] = useState(false)
+  const [error, setError] = useState('')
+
+  const loadTree = useCallback(async () => {
+    if (!id) return
+    const { data } = await api.get<Tree>(`/knowledge-bases/${id}/tree`)
+    setTree(data)
+  }, [id])
+
+  const loadMeta = useCallback(async () => {
+    if (!id) return
+    const { data } = await api.get<KnowledgeBase>(`/knowledge-bases/${id}`)
+    setKb(data)
+  }, [id])
+
+  useEffect(() => {
+    setError('')
+    Promise.all([loadMeta(), loadTree()]).catch((err) => {
+      setError(err?.response?.data?.detail || 'Failed to load knowledge base')
+    })
+  }, [loadMeta, loadTree])
+
+  const onDelete = async () => {
+    if (!kb) return
+    if (!confirm(`Delete knowledge base "${kb.title}" and all its content?`)) return
+    try {
+      await api.delete(`/knowledge-bases/${kb.id}`)
+      navigate('/knowledge-bases')
+    } catch (err: any) {
+      alert(err?.response?.data?.detail || 'Failed to delete knowledge base')
+    }
+  }
+
+  if (error) {
+    return (
+      <div className="project-detail-page">
+        <button className="btn-back" onClick={() => navigate('/knowledge-bases')}>← Knowledge Bases</button>
+        <p className="empty">{error}</p>
+      </div>
+    )
+  }
+
+  if (!kb) return <div className="loading">Loading…</div>
+
+  return (
+    <div className="project-detail-page">
+      <button className="btn-back" onClick={() => navigate('/knowledge-bases')}>← Knowledge Bases</button>
+
+      <div className="page-header">
+        <h2>
+          📚 {kb.title}
+          {kb.knowledge_base_code && <span className="badge" style={{ marginLeft: 8 }}>{kb.knowledge_base_code}</span>}
+        </h2>
+        <div style={{ display: 'flex', gap: 8 }}>
+          <button className="btn-secondary" onClick={() => setShowEdit(true)}>Edit</button>
+          <button className="btn-danger" onClick={onDelete}>Delete</button>
+        </div>
+      </div>
+
+      {kb.description && <p className="project-desc">{kb.description}</p>}
+
+      <KnowledgeBaseFormModal
+        isOpen={showEdit}
+        knowledgeBase={kb}
+        onClose={() => setShowEdit(false)}
+        onSaved={async () => { await loadMeta() }}
+      />
+
+      <div className="section">
+        <h3>Structure</h3>
+        {tree && <KnowledgeBaseTree tree={tree} onChange={loadTree} />}
+      </div>
+    </div>
+  )
+}
diff --git a/src/pages/KnowledgeBasesPage.tsx b/src/pages/KnowledgeBasesPage.tsx
new file mode 100644
index 0000000..cf88852
--- /dev/null
+++ b/src/pages/KnowledgeBasesPage.tsx
@@ -0,0 +1,51 @@
+import { useState, useEffect } from 'react'
+import { useNavigate } from 'react-router-dom'
+import api from '@/services/api'
+import type { KnowledgeBase } from '@/types'
+import dayjs from 'dayjs'
+import KnowledgeBaseFormModal from '@/components/KnowledgeBaseFormModal'
+
+export default function KnowledgeBasesPage() {
+  const [items, setItems] = useState<KnowledgeBase[]>([])
+  const [showCreate, setShowCreate] = useState(false)
+  const navigate = useNavigate()
+
+  const fetchItems = () => {
+    api.get<KnowledgeBase[]>('/knowledge-bases').then(({ data }) => setItems(data)).catch(() => setItems([]))
+  }
+
+  useEffect(() => { fetchItems() }, [])
+
+  return (
+    <div className="projects-page">
+      <div className="page-header">
+        <h2>📚 Knowledge Bases ({items.length})</h2>
+        <button className="btn-primary" onClick={() => setShowCreate(true)}>+ New</button>
+      </div>
+
+      <KnowledgeBaseFormModal
+        isOpen={showCreate}
+        onClose={() => setShowCreate(false)}
+        onSaved={() => fetchItems()}
+      />
+
+      <div className="project-grid">
+        {items.map((kb) => (
+          <div
+            key={kb.id}
+            className="project-card"
+            onClick={() => navigate(`/knowledge-bases/${kb.knowledge_base_code || kb.id}`)}
+          >
+            <h3>{kb.title}</h3>
+            {kb.knowledge_base_code && <span className="badge" style={{ marginLeft: 8 }}>{kb.knowledge_base_code}</span>}
+            <p className="project-desc">{kb.description || 'No description'}</p>
+            <div className="project-meta">
+              <span>Created {kb.created_at ? dayjs(kb.created_at).format('YYYY-MM-DD') : '—'}</span>
+            </div>
+          </div>
+        ))}
+        {items.length === 0 && <p className="empty">No knowledge bases yet. Create one above.</p>}
+      </div>
+    </div>
+  )
+}
diff --git a/src/types/index.ts b/src/types/index.ts
index c392391..758c037 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -26,6 +26,51 @@ export interface Project {
   created_at: string
 }
 
+export interface KnowledgeBase {
+  id: number
+  knowledge_base_code: string | null
+  title: string
+  description: string | null
+  created_by: number
+  created_at: string | null
+  last_updated_at: string | null
+}
+
+export interface KnowledgeFact {
+  id: number
+  category_id: number | null
+  topic_id: number
+  fact: string
+  last_updated_at: string | null
+}
+
+export interface KnowledgeCategoryNode {
+  id: number
+  name: string
+  parent: number | null
+  topic_id: number
+  description: string | null
+  categories: KnowledgeCategoryNode[]
+  facts: KnowledgeFact[]
+}
+
+export interface KnowledgeTopicNode {
+  id: number
+  topic: string
+  knowledge_base_id: number
+  description: string | null
+  categories: KnowledgeCategoryNode[]
+  facts: KnowledgeFact[]
+}
+
+export interface KnowledgeBaseTree {
+  id: number
+  knowledge_base_code: string | null
+  title: string
+  description: string | null
+  topics: KnowledgeTopicNode[]
+}
+
 export interface ProjectMember {
   id: number
   user_id: number