sdtk-wiki-kit 0.2.1 → 0.2.2

package/README.md

@@ -369,6 +369,14 @@ Preconditions:
 - local `wiki.ask` entitlement must be valid
 - local premium/runtime Ask pack must be available
 
+When `--source` is given, Ask grounds on the chosen doc **plus its directly-related
+siblings** — other docs that share the same BK issue, knowledge id, skill, or family.
+The related docs are bounded (capped) and labelled as related, so a question about
+one spec also sees its plan, test cases, and knowledge objects. No-filter (all docs)
+grounding is unchanged.
+
+The viewer's **Ask** panel has a scope picker ("Ask within"): All Docs (default), By folder (path-prefix filter with live count list), This doc + related (mapped to `--source` / `current-focus` with hyperedge expansion), and Selected docs (explicit attachment). Each answer shows a collapsible **Sources used (N)** panel with `primary` / `related` labels.
+
 Query history is off by default. `--save-query` writes one redacted JSON record
 under `.sdtk/wiki/queries` only after a successful answer.
 

package/assets/atlas/doc_atlas_viewer_template.html

@@ -359,6 +359,7 @@ body.nav-open .page-nav-toggle{display:none}
 #atlas-ask-model-select{flex:0 0 136px;width:136px}
 #atlas-ask-mode-select{flex:1 1 140px;width:140px}
 #atlas-ask-info-toggle{flex:0 0 36px}
+#atlas-ask-path-filter{padding:0 12px;background-image:none;flex:1 1 120px}
 .atlas-ask-send{display:inline-flex;align-items:center;justify-content:center;flex:0 0 42px;width:42px;height:42px;border-radius:999px;border:0;background:linear-gradient(135deg,#4f78ff 0%,#3156c9 100%);color:#ffffff;cursor:pointer;font-size:20px;font-weight:900;box-shadow:0 14px 24px rgba(49,86,201,0.26)}
 .atlas-ask-send:hover{filter:brightness(1.03)}
 .atlas-ask-send:disabled{opacity:.5;cursor:not-allowed}
@@ -407,6 +408,47 @@ body.nav-open .page-nav-toggle{display:none}
 .atlas-ask-history-item strong{font-size:12px;color:#24344d}
 .atlas-ask-history-meta{font-size:11px;color:#6d7d95;line-height:1.4}
 .atlas-ask-history-preview{font-size:12px;color:#52606f;line-height:1.45}
+.ask-scope-wrap{position:relative;flex:1 1 150px;min-width:0}
+.ask-scope-btn{display:flex;align-items:center;gap:8px;width:100%;height:36px;padding:0 12px;border-radius:999px;border:1px solid #d9cfbf;background:#fff;color:#24344d;font-size:12px;font-weight:700;cursor:pointer;box-shadow:0 8px 18px rgba(15,23,42,0.04);text-align:left}
+.ask-scope-btn:hover{border-color:#aebfe7;background:#f6f8ff}
+.ask-scope-btn .scope-ico{flex:0 0 auto}
+.ask-scope-btn .scope-label{flex:1 1 auto;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.ask-scope-btn .scope-caret{flex:0 0 auto;color:#7d8fa8;font-size:9px}
+.ask-scope-menu{display:none;position:absolute;left:0;bottom:calc(100% + 8px);z-index:5;flex-direction:column;gap:2px;padding:8px;min-width:248px;max-width:320px;background:rgba(255,255,255,0.99);border:1px solid #d9cfbf;border-radius:18px;box-shadow:0 18px 30px rgba(94,83,63,0.18);max-height:340px;overflow:auto}
+.ask-scope-wrap.open .ask-scope-menu{display:flex}
+.ask-scope-opt{display:flex;align-items:center;gap:10px;padding:9px 10px;border-radius:12px;cursor:pointer;color:#24344d}
+.ask-scope-opt:hover{background:#f7f9ff}
+.ask-scope-opt.active{background:#eef3ff;border:1px solid #cad7ff;padding:8px 9px}
+.ask-scope-opt.disabled{opacity:.45;cursor:not-allowed;pointer-events:none}
+.ask-scope-opt .opt-ico{flex:0 0 18px;text-align:center}
+.ask-scope-opt .opt-copy{display:flex;align-items:center;min-width:0;flex:1}
+.ask-scope-opt .opt-copy strong{font-size:12.5px;font-weight:700;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.ask-scope-opt .opt-check{flex:0 0 auto;color:#3156c9;font-weight:900;visibility:hidden}
+.ask-scope-opt.active .opt-check{visibility:visible}
+.ask-scope-sep{height:1px;background:#ece4d8;margin:4px 2px}
+.ask-folder-block{display:none;flex-direction:column;gap:6px;padding:4px 4px 6px;margin:2px 0 0;border-top:1px dashed #e6ded1}
+.ask-folder-block.open{display:flex}
+.ask-folder-filter{height:32px;border-radius:999px;border:1px solid #d9cfbf;background:#fff;padding:0 12px;font:inherit;font-size:12px;color:#24344d}
+.ask-folder-filter:focus{outline:none;border-color:#5f89ff;box-shadow:0 0 0 3px rgba(95,137,255,0.12)}
+.ask-folder-list{display:flex;flex-direction:column;gap:1px;max-height:170px;overflow:auto}
+.ask-folder-item{display:flex;align-items:center;justify-content:space-between;gap:10px;padding:7px 10px;border-radius:10px;cursor:pointer;font-size:12px}
+.ask-folder-item:hover{background:#f7f9ff}
+.ask-folder-item.active{background:#eef3ff}
+.ask-folder-item .f-path{font-family:'SF Mono',Consolas,monospace;color:#354153;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.ask-folder-item .f-count{flex:0 0 auto;font-size:11px;font-weight:800;color:#6d7d95;background:#f3efe7;border:1px solid #e6ded1;border-radius:999px;padding:1px 8px}
+.ask-sources{margin-top:2px;border:1px solid #e6ded1;border-radius:14px;background:rgba(255,255,255,0.9);overflow:hidden}
+.ask-sources-head{display:flex;align-items:center;gap:8px;width:100%;padding:10px 12px;background:none;border:0;cursor:pointer;color:#52606f;font-size:12px;font-weight:700;text-align:left}
+.ask-sources-head:hover{background:#f7f9ff}
+.ask-sources-caret{transition:transform .15s ease;color:#7d8fa8;font-size:10px}
+.ask-sources.open .ask-sources-caret{transform:rotate(90deg)}
+.ask-sources-badge{display:inline-flex;align-items:center;justify-content:center;min-width:20px;height:18px;padding:0 6px;border-radius:999px;background:#3156c9;color:#fff;font-size:11px;font-weight:800}
+.ask-sources-body{display:none;flex-direction:column;gap:6px;padding:4px 12px 12px}
+.ask-sources.open .ask-sources-body{display:flex}
+.ask-source-row{display:flex;align-items:center;justify-content:space-between;gap:10px;padding:7px 10px;border:1px solid #ece4d8;border-radius:10px;background:#fff}
+.ask-source-row .s-path{font-family:'SF Mono',Consolas,monospace;font-size:11.5px;color:#354153;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.s-chip{flex:0 0 auto;font-size:10px;font-weight:800;letter-spacing:.04em;text-transform:uppercase;border-radius:999px;padding:2px 8px}
+.s-chip.primary{color:#2f8f5b;background:#e7f6ee;border:1px solid #bfe6cf}
+.s-chip.related{color:#3156c9;background:#eef3ff;border:1px solid #cad7ff}
 @media (max-width: 1180px){
   .atlas-ask-dock{position:relative;left:auto;top:auto;bottom:auto;width:100%;max-width:none;margin-top:14px}
   .atlas-ask-dock:not(.open){width:100%}
@@ -614,7 +656,7 @@ body.nav-open .page-nav-toggle{display:none}
                 <button class="graph-focus-toggle atlas-ask-collapse" id="atlas-ask-toggle" title="Hide Ask SDTK-WIKI" onclick="toggleWikiAsk(false)">&#9662;</button>
                 <div class="atlas-ask-attachments" id="atlas-ask-attachments"></div>
                 <div class="atlas-ask-input-wrap">
-                  <textarea class="atlas-ask-input" id="atlas-ask-input" placeholder="Ask about the visible graph group, current focus, or attached docs..."></textarea>
+                  <textarea class="atlas-ask-input" id="atlas-ask-input" placeholder="Ask something about your docs..."></textarea>
                   <div class="atlas-ask-mention-results" id="atlas-ask-mention-results"></div>
                 </div>
                 <div class="atlas-ask-source-summary" id="atlas-ask-source-summary"></div>
@@ -622,11 +664,40 @@ body.nav-open .page-nav-toggle{display:none}
                   <div class="atlas-ask-controls">
                     <select class="atlas-ask-mode-select" id="atlas-ask-runtime-select" onchange="setWikiAskRuntimeAgent(this.value)" aria-label="Select runtime agent"></select>
                     <select class="atlas-ask-mode-select" id="atlas-ask-model-select" onchange="setWikiAskModel(this.value)" aria-label="Select model"></select>
-                    <select class="atlas-ask-mode-select" id="atlas-ask-mode-select" onchange="setWikiAskMode(this.value)" aria-label="Select grounding mode">
-                      <option value="visible-group">Visible Group</option>
-                      <option value="current-focus">Current Focus</option>
-                      <option value="selected-docs">Selected Docs</option>
-                    </select>
+                    <div class="ask-scope-wrap" id="ask-scope-wrap">
+                      <button class="ask-scope-btn" id="ask-scope-btn" onclick="toggleWikiAskScopeMenu(event)" aria-haspopup="listbox" aria-expanded="false" title="Select Ask scope">
+                        <span class="scope-ico" id="ask-scope-ico">&#128218;</span>
+                        <span class="scope-label" id="ask-scope-label">All Docs</span>
+                        <span class="scope-caret">&#9650;</span>
+                      </button>
+                      <div class="ask-scope-menu" id="ask-scope-menu" role="listbox">
+                        <div class="ask-scope-opt active" data-scope="all" role="option" tabindex="0" onclick="pickWikiAskScope('all')" title="Hỏi trên toàn bộ tài liệu đã index (mặc định).">
+                          <span class="opt-ico">&#128218;</span>
+                          <span class="opt-copy"><strong>All Docs</strong></span>
+                          <span class="opt-check">&#10003;</span>
+                        </div>
+                        <div class="ask-scope-opt" id="ask-scope-opt-folder" data-scope="folder" role="option" tabindex="0" onclick="toggleWikiAskFolderBlock(event)" title="Chọn một thư mục có thật để giới hạn phạm vi hỏi.">
+                          <span class="opt-ico">&#128193;</span>
+                          <span class="opt-copy"><strong>By folder</strong></span>
+                          <span class="opt-check">&#10003;</span>
+                        </div>
+                        <div class="ask-folder-block" id="ask-folder-block">
+                          <input class="ask-folder-filter" id="ask-folder-filter" type="text" placeholder="Filter folders&#x2026;" oninput="filterWikiAskFolders(this.value)" aria-label="Filter folders by name">
+                          <div class="ask-folder-list" id="ask-folder-list"></div>
+                        </div>
+                        <div class="ask-scope-sep"></div>
+                        <div class="ask-scope-opt" id="ask-scope-opt-focus" data-scope="focus" role="option" tabindex="0" onclick="pickWikiAskScope('focus')" title="T&#xE0;i li&#x1EC7;u &#x111;ang focus + c&#xE1;c t&#xE0;i li&#x1EC7;u li&#xEA;n quan c&#xF9;ng BK / knowledge / skill.">
+                          <span class="opt-ico">&#127919;</span>
+                          <span class="opt-copy"><strong>This doc + related</strong></span>
+                          <span class="opt-check">&#10003;</span>
+                        </div>
+                        <div class="ask-scope-opt" id="ask-scope-opt-selected" data-scope="selected" role="option" tabindex="0" onclick="pickWikiAskScope('selected')" title="Ch&#x1EC9; h&#x1ECF;i tr&#xEA;n c&#xE1;c t&#xE0;i li&#x1EC7;u b&#x1EA1;n &#x111;&#xE3; &#x111;&#xED;nh k&#xE8;m.">
+                          <span class="opt-ico">&#10003;</span>
+                          <span class="opt-copy"><strong id="ask-scope-selected-label">Selected docs</strong></span>
+                          <span class="opt-check">&#10003;</span>
+                        </div>
+                      </div>
+                    </div>
                     <button class="atlas-ask-icon-btn" id="atlas-ask-info-toggle" title="Show grounding info" onclick="toggleWikiAskAdvanced()">i</button>
                   </div>
                   <button class="atlas-ask-send" id="atlas-ask-submit" onclick="submitWikiAsk()" aria-label="Submit SDTK-WIKI Ask" title="Submit SDTK-WIKI Ask">&#8593;</button>
@@ -879,7 +950,8 @@ const graphState = {
 };
 const wikiAskState = {
   open: false,
-  mode: 'visible-group',
+  mode: 'all-docs',
+  docPathFilter: '',
   selectedDocIds: [],
   status: 'idle',
   answer: null,
@@ -1433,8 +1505,165 @@ function openGraphToolbarPeek(event) {
   toggleGraphToolbarMinimized(false);
 }
 function getWikiAskModeLabel(mode) {
-  return ({ 'current-focus': 'Current Focus', 'visible-group': 'Visible Group', 'selected-docs': 'Selected Docs' }[mode]) || 'Ask SDTK-WIKI';
+  return ({ 'all-docs': 'All Docs', 'current-focus': 'This doc + related', 'visible-group': 'All Docs', 'selected-docs': 'Selected docs' }[mode]) || 'Ask SDTK-WIKI';
+}
+function getWikiAskAllDocIds(pathFilter) {
+  const filter = (pathFilter || '').trim().toLowerCase();
+  return docs.filter(d => {
+    if (!filter) return true;
+    const docPath = (d.sourcePath || d.path || d.id || '').toLowerCase();
+    return docPath.startsWith(filter);
+  }).map(d => d.id);
+}
+function setWikiAskDocPathFilter(value) {
+  wikiAskState.docPathFilter = value || '';
+  renderWikiAsk();
+}
+function getWikiAskFolderList() {
+  var counts = {};
+  for (var i = 0; i < docs.length; i++) {
+    var d = docs[i];
+    var sp = (d.sourcePath || d.path || d.id || '').replace(/\\/g, '/');
+    if (!sp) continue;
+    var parts = sp.split('/');
+    if (parts.length >= 2) {
+      var prefix = parts.slice(0, 2).join('/') + '/';
+      counts[prefix] = (counts[prefix] || 0) + 1;
+    }
+  }
+  return Object.entries(counts)
+    .sort(function(a, b) { return b[1] - a[1] || a[0].localeCompare(b[0]); })
+    .slice(0, 8)
+    .map(function(e) { return { path: e[0], count: e[1] }; });
+}
+function renderWikiAskFolderList() {
+  var list = document.getElementById('ask-folder-list');
+  if (!list) return;
+  var folders = getWikiAskFolderList();
+  if (!folders.length) {
+    list.innerHTML = '<div style="padding:8px 10px;font-size:12px;color:#6d7d95">No folders found.</div>';
+    return;
+  }
+  list.innerHTML = folders.map(function(f) {
+    var active = wikiAskState.docPathFilter === f.path ? ' active' : '';
+    return '<div class="ask-folder-item' + active + '" data-path="' + escapeHtml(f.path) + '" onclick="pickWikiAskFolder(' + JSON.stringify(f.path) + ')"><span class="f-path">' + escapeHtml(f.path) + '</span><span class="f-count">' + f.count + '</span></div>';
+  }).join('');
+}
+function toggleWikiAskScopeMenu(event) {
+  if (event) event.stopPropagation();
+  var wrap = document.getElementById('ask-scope-wrap');
+  if (!wrap) return;
+  var isOpen = wrap.classList.contains('open');
+  if (!isOpen) {
+    renderWikiAskFolderList();
+    syncWikiAskScopeMenu();
+  }
+  wrap.classList.toggle('open', !isOpen);
+  var btn = document.getElementById('ask-scope-btn');
+  if (btn) btn.setAttribute('aria-expanded', String(!isOpen));
+}
+function closeWikiAskScopeMenu() {
+  var wrap = document.getElementById('ask-scope-wrap');
+  if (wrap) {
+    wrap.classList.remove('open');
+    var btn = document.getElementById('ask-scope-btn');
+    if (btn) btn.setAttribute('aria-expanded', 'false');
+  }
+}
+function syncWikiAskScopeMenu() {
+  var menu = document.getElementById('ask-scope-menu');
+  if (!menu) return;
+  menu.querySelectorAll('.ask-scope-opt').forEach(function(opt) { opt.classList.remove('active'); });
+  var scope = wikiAskState.mode === 'current-focus' ? 'focus'
+    : wikiAskState.mode === 'selected-docs' ? 'selected'
+    : wikiAskState.docPathFilter ? 'folder'
+    : 'all';
+  var target = menu.querySelector('[data-scope="' + scope + '"]');
+  if (target) target.classList.add('active');
+  var focusOpt = document.getElementById('ask-scope-opt-focus');
+  var focusId = typeof getGraphFocusId !== 'undefined' ? getGraphFocusId() : null;
+  if (focusOpt) {
+    if (focusId) { focusOpt.classList.remove('disabled'); focusOpt.removeAttribute('aria-disabled'); }
+    else { focusOpt.classList.add('disabled'); focusOpt.setAttribute('aria-disabled', 'true'); }
+  }
+  var selectedOpt = document.getElementById('ask-scope-opt-selected');
+  if (selectedOpt) {
+    var selLabel = document.getElementById('ask-scope-selected-label');
+    if (wikiAskState.selectedDocIds.length > 0) {
+      selectedOpt.style.display = '';
+      if (selLabel) selLabel.textContent = 'Selected docs (' + wikiAskState.selectedDocIds.length + ')';
+    } else { selectedOpt.style.display = 'none'; }
+  }
+  if (scope === 'folder') {
+    var folderBlock = document.getElementById('ask-folder-block');
+    if (folderBlock) folderBlock.classList.add('open');
+    document.querySelectorAll('#ask-folder-list .ask-folder-item').forEach(function(item) {
+      item.classList.toggle('active', item.dataset.path === wikiAskState.docPathFilter);
+    });
+  }
+}
+function pickWikiAskScope(scope) {
+  if (scope === 'focus') {
+    var focusId = typeof getGraphFocusId !== 'undefined' ? getGraphFocusId() : null;
+    if (!focusId) return;
+    wikiAskState.mode = 'current-focus';
+    wikiAskState.docPathFilter = '';
+  } else if (scope === 'selected') {
+    wikiAskState.mode = 'selected-docs';
+    wikiAskState.docPathFilter = '';
+  } else {
+    wikiAskState.mode = 'all-docs';
+    wikiAskState.docPathFilter = '';
+  }
+  closeWikiAskScopeMenu();
+  renderWikiAsk();
+}
+function toggleWikiAskFolderBlock(event) {
+  if (event) event.stopPropagation();
+  var block = document.getElementById('ask-folder-block');
+  if (!block) return;
+  var isOpen = block.classList.contains('open');
+  block.classList.toggle('open', !isOpen);
+  if (!isOpen) { var filter = document.getElementById('ask-folder-filter'); if (filter) filter.focus(); }
+}
+function pickWikiAskFolder(path) {
+  wikiAskState.mode = 'all-docs';
+  wikiAskState.docPathFilter = path;
+  document.querySelectorAll('#ask-folder-list .ask-folder-item').forEach(function(item) {
+    item.classList.toggle('active', item.dataset.path === path);
+  });
+  closeWikiAskScopeMenu();
+  renderWikiAsk();
+}
+function filterWikiAskFolders(q) {
+  var query = (q || '').trim().toLowerCase();
+  document.querySelectorAll('#ask-folder-list .ask-folder-item').forEach(function(item) {
+    var p = item.dataset.path.toLowerCase();
+    item.style.display = (!query || p.indexOf(query) !== -1) ? '' : 'none';
+  });
+}
+function renderWikiAskSourcesPanel(context) {
+  if (!context) return '';
+  var sourcePaths = Array.isArray(context.source_paths) ? context.source_paths : [];
+  var relationMap = context.truncated && typeof context.truncated === 'object' && context.truncated.relation ? context.truncated.relation : {};
+  var total = sourcePaths.length;
+  if (!total) return '';
+  var rows = sourcePaths.map(function(p) {
+    var rel = relationMap[p];
+    var chipHtml;
+    if (!rel || rel === 'primary') {
+      chipHtml = '<span class="s-chip primary">primary</span>';
+    } else {
+      var facetsRaw = rel.replace(/^shares\s+/, '');
+      var bkMatch = facetsRaw.match(/issue:([^,\s]+)/);
+      var relLabel = bkMatch ? 'related \u00b7 ' + bkMatch[1] : 'related';
+      chipHtml = '<span class="s-chip related">' + escapeHtml(relLabel) + '</span>';
+    }
+    return '<div class="ask-source-row"><span class="s-path">' + escapeHtml(p) + '</span>' + chipHtml + '</div>';
+  }).join('');
+  return '<div class="ask-sources"><button class="ask-sources-head" onclick="this.parentElement.classList.toggle(\'open\')" title="Toggle sources used panel"><span class="ask-sources-caret">&#9658;</span><span>Sources used</span><span class="ask-sources-badge">' + total + '</span></button><div class="ask-sources-body">' + rows + '</div></div>';
 }
+
 function getWikiAskVisibleDocIds() {
   return getVisibleDocs().map(doc => doc.id);
 }
@@ -1569,7 +1798,8 @@ function loadWikiAskHistoryItem(id) {
   wikiAskState.question = '';
   wikiAskState.pendingQuestion = '';
   wikiAskState.lastQuestion = item.question || '';
-  wikiAskState.mode = item.mode || 'visible-group';
+  wikiAskState.mode = (item.mode === 'visible-group' ? 'all-docs' : (item.mode || 'all-docs'));
+  wikiAskState.docPathFilter = item.doc_path_filter || '';
   wikiAskState.selectedDocIds = Array.isArray(item.selected_doc_ids) ? [...item.selected_doc_ids] : [];
   wikiAskState.answer = {
     question: item.question || '',
@@ -1696,20 +1926,23 @@ function clearWikiAskSources() {
   renderWikiAsk();
 }
 function getWikiAskSourceSummaryHtml() {
-  const visibleCount = getWikiAskVisibleDocIds().length;
   const selectedCount = wikiAskState.selectedDocIds.length;
   const focusId = getGraphFocusId();
-  const focusLabel = focusId ? ((docById[focusId] && (docById[focusId].title || focusId)) || focusId) : 'None';
+  const focusLabel = focusId ? ((docById[focusId] && (docById[focusId].title || focusId)) || focusId) : null;
+  if (wikiAskState.mode === 'all-docs') {
+    const filteredIds = getWikiAskAllDocIds(wikiAskState.docPathFilter);
+    if (wikiAskState.docPathFilter) {
+      return `<strong>Scope:</strong> By folder <code>${escapeHtml(wikiAskState.docPathFilter)}</code> — ${filteredIds.length} of ${docs.length} docs.`;
+    }
+    return `<strong>Scope:</strong> All Docs — ${filteredIds.length} docs indexed.`;
+  }
   if (wikiAskState.mode === 'current-focus') {
     if (focusId) {
-      return `<strong>Grounding:</strong> Current focus source. <strong>Focus:</strong> ${escapeHtml(focusLabel)}. <strong>Visible group:</strong> ${visibleCount} docs.`;
+      return `<strong>Scope:</strong> This doc + related — <strong>${escapeHtml(focusLabel)}</strong> and its related siblings.`;
     }
-    return `<strong>Grounding:</strong> Current focus source. Select a graph note to anchor this ask. <strong>Visible group:</strong> ${visibleCount} docs.`;
-  }
-  if (wikiAskState.mode === 'visible-group') {
-    return `<strong>Grounding:</strong> Visible graph group. <strong>Visible docs:</strong> ${visibleCount}.${selectedCount ? ` <strong>Explicit docs:</strong> ${selectedCount}.` : ''}`;
+    return `<strong>Scope:</strong> This doc + related — <em>focus a graph node first.</em>`;
   }
-  return `<strong>Grounding:</strong> Explicit source pack. <strong>Selected docs:</strong> ${selectedCount}.${selectedCount ? '' : ' Use graph search results or @mention docs before asking.'}`;
+  return `<strong>Scope:</strong> Selected docs — ${selectedCount} doc${selectedCount !== 1 ? 's' : ''} attached.${selectedCount ? '' : ' Attach docs via @mention or graph search.'}`;
 }
 function getWikiAskAdvancedSummaryText() {
   const bits = [];
@@ -1837,7 +2070,6 @@ function renderWikiAsk() {
   );
   const runtimeSelect = document.getElementById('atlas-ask-runtime-select');
   const modelSelect = document.getElementById('atlas-ask-model-select');
-  const modeSelect = document.getElementById('atlas-ask-mode-select');
   const input = document.getElementById('atlas-ask-input');
   const attachments = document.getElementById('atlas-ask-attachments');
   const sourceSummary = document.getElementById('atlas-ask-source-summary');
@@ -1857,7 +2089,24 @@ function renderWikiAsk() {
     modelSelect.innerHTML = modelOptions.map(model => `<option value="${model}">${escapeHtml(getWikiAskModelLabel(model))}</option>`).join('');
     if (modelSelect.value !== wikiAskState.model) modelSelect.value = wikiAskState.model;
   }
-  if (modeSelect && modeSelect.value !== wikiAskState.mode) modeSelect.value = wikiAskState.mode;
+  const scopeIco = document.getElementById('ask-scope-ico');
+  const scopeLbl = document.getElementById('ask-scope-label');
+  if (scopeIco && scopeLbl) {
+    if (wikiAskState.mode === 'current-focus') {
+      scopeIco.textContent = '\u{1F3AF}';
+      scopeLbl.textContent = 'This doc + related';
+    } else if (wikiAskState.mode === 'selected-docs') {
+      scopeIco.textContent = '\u2713';
+      const selCnt = wikiAskState.selectedDocIds.length;
+      scopeLbl.textContent = selCnt > 0 ? `Selected docs (${selCnt})` : 'Selected docs';
+    } else if (wikiAskState.docPathFilter) {
+      scopeIco.textContent = '\u{1F4C1}';
+      scopeLbl.textContent = wikiAskState.docPathFilter;
+    } else {
+      scopeIco.textContent = '\u{1F4DA}';
+      scopeLbl.textContent = 'All Docs';
+    }
+  }
   if (sourceSummary) sourceSummary.innerHTML = getWikiAskSourceSummaryHtml();
   if (mentionResults) renderWikiAskMentions();
   if (attachments) {
@@ -1903,7 +2152,8 @@ function renderWikiAsk() {
       ? `<ul>${turn.citations.map(item => `<li><button class="wiki-link" onclick="focusGraphNode('${item.path}')">${escapeHtml(item.title || item.path)}</button> &middot; ${escapeHtml(item.reason || 'Grounded source')}</li>`).join('')}</ul>`
       : '<p class="muted">No citations were returned.</p>';
     blocks.push(`<div class="atlas-ask-message user"><div class="atlas-ask-message-label">You</div><div class="atlas-ask-message-bubble">${escapeHtml(turn.question || '')}</div></div>`);
-    blocks.push(`<div class="atlas-ask-message assistant"><div class="atlas-ask-message-label">SDTK-WIKI Ask</div><div class="atlas-ask-answer-card"><div class="graph-note-prose">${renderMarkdownFragment(turn.answer_markdown || '')}</div>${turn.disclaimer ? `<span class="muted">${escapeHtml(turn.disclaimer)}</span>` : ''}</div><div class="atlas-ask-answer-card"><h3>Citations</h3>${citationHtml}</div></div>`);
+    const sourcesHtml = renderWikiAskSourcesPanel(turn.context || null);
+    blocks.push(`<div class="atlas-ask-message assistant"><div class="atlas-ask-message-label">SDTK-WIKI Ask</div><div class="atlas-ask-answer-card"><div class="graph-note-prose">${renderMarkdownFragment(turn.answer_markdown || '')}</div>${turn.disclaimer ? `<span class="muted">${escapeHtml(turn.disclaimer)}</span>` : ''}</div><div class="atlas-ask-answer-card"><h3>Citations</h3>${citationHtml}</div>${sourcesHtml}</div>`);
   });
 
   if (wikiAskState.pendingQuestion) {
@@ -1912,7 +2162,7 @@ function renderWikiAsk() {
   }
 
   if (!blocks.length) {
-    answer.innerHTML = '<div class="atlas-ask-empty">Ask SDTK-WIKI from the visible graph group by default, or narrow the source pack with a selected node or attached docs.</div>';
+    answer.innerHTML = '<div class="atlas-ask-empty">Use <strong>Ask within</strong> to choose your scope: All Docs for full coverage, By folder to narrow by path, This doc + related to focus on the current graph node, or Selected docs for pinned sources.</div>';
     return;
   }
 
@@ -1930,14 +2180,18 @@ async function submitWikiAsk() {
     renderWikiAsk();
     return;
   }
+  const allDocIds = wikiAskState.mode === 'all-docs'
+    ? getWikiAskAllDocIds(wikiAskState.docPathFilter)
+    : getWikiAskVisibleDocIds();
   const payload = {
     question: draftQuestion,
     mode: wikiAskState.mode,
     runtime_agent: wikiAskState.runtimeAgent,
     model: wikiAskState.model,
     focus_doc_id: getGraphFocusId() || '',
-    visible_doc_ids: getWikiAskVisibleDocIds(),
+    visible_doc_ids: allDocIds,
     selected_doc_ids: [...wikiAskState.selectedDocIds],
+    doc_path_filter: wikiAskState.mode === 'all-docs' ? (wikiAskState.docPathFilter || '') : '',
   };
   wikiAskState.pendingQuestion = draftQuestion;
   wikiAskState.question = '';
@@ -2416,6 +2670,10 @@ document.addEventListener('mousedown', event => {
     graphState.settingsOpen = false;
     syncGraphSettings();
   }
+  const scopeWrap = document.getElementById('ask-scope-wrap');
+  if (scopeWrap && scopeWrap.classList.contains('open') && !scopeWrap.contains(event.target)) {
+    closeWikiAskScopeMenu();
+  }
 });
 window.addEventListener('mousemove', dragWikiAsk);
 window.addEventListener('mouseup', stopWikiAskDrag);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdtk-wiki-kit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Project-local wiki and knowledge graph toolkit for SDTK workspaces.",
   "bin": {
     "sdtk-wiki": "bin/sdtk-wiki.js"

package/src/commands/ask.js

@@ -57,6 +57,8 @@ Inputs:
 Behavior:
   Executes a local premium wiki.ask runtime pack when entitlement and graph preconditions pass.
   Fails closed when the graph, entitlement, or runtime pack is missing.
+  --source grounds on the chosen doc plus its directly-related siblings (docs sharing
+  the same BK issue, knowledge id, skill, or family), bounded and labelled as related.
   Query history is off by default.
   --save-query writes one redacted JSON record under .sdtk/wiki/queries after a successful answer.
   Full question and full answer are not stored by default.`);

package/src/commands/init.js

@@ -32,7 +32,7 @@ BK-102 behavior:
 Options:
   --project-path <path>   Project root. Defaults to current working directory.
   --output-dir <path>     Graph output dir under .sdtk/wiki. Defaults to .sdtk/wiki/graph.
-  --scan-root <path>      Repeatable markdown scan root.
+  --scan-root <path>      Repeatable markdown scan root. Defaults to ./docs if it exists, otherwise the project root.
   --force                 Overwrite existing config.
   --no-build              Write config only.
   --no-open               Build graph but do not launch viewer.

package/src/lib/wiki-ask.js

@@ -9,6 +9,11 @@ const { loadWikiAskHandler } = require("./wiki-premium-loader");
 const INDEX_FILE = "SDTK_DOC_INDEX.json";
 const GRAPH_FILE = "SDTK_DOC_GRAPH.json";
 const DEFAULT_MAX_SOURCES = 6;
+// BK-269 hyperedge-aware context expansion (--source filter only).
+// Mirrors run_doc_atlas_server.py so both grounding surfaces behave identically.
+const DEFAULT_MAX_HYPEREDGE_EXPANSION = 6;
+const DEFAULT_MIN_HYPEREDGE_CO_MEMBERSHIP = 1;
+const DEFAULT_MAX_FAMILY_HYPEREDGE_CONTRIB = 3;
 
 function readJsonFile(filePath, label) {
   try {
@@ -69,28 +74,251 @@ function extractDocumentText(document) {
   return "";
 }
 
-function buildSources(index, sourceFilters, maxSources) {
+function docId(document) {
+  return document.id || extractDocumentPath(document);
+}
+
+function docFacetKeys(document) {
+  const keys = [];
+  const groups = [
+    ["issue", document.issues],
+    ["knowledge", document.knowledge_ids],
+    ["skill", document.skill_refs],
+    ["lane", document.lane_refs],
+  ];
+  for (const [namespace, values] of groups) {
+    if (!Array.isArray(values)) {
+      continue;
+    }
+    for (const value of values) {
+      const text = String(value == null ? "" : value).trim();
+      if (text) {
+        keys.push(`${namespace}:${text}`);
+      }
+    }
+  }
+  const family = String(document.family == null ? "" : document.family).trim();
+  if (family) {
+    keys.push(`family:${family}`);
+  }
+  return keys;
+}
+
+// Invert shared reference facets into hyperedges (groups with >=2 docs). Pure and
+// deterministic; mirrors _derive_hyperedges in run_doc_atlas_server.py.
+function deriveHyperedges(documents) {
+  const facetToDocs = new Map();
+  for (const document of documents) {
+    if (!document || typeof document !== "object") {
+      continue;
+    }
+    const id = docId(document);
+    if (!id) {
+      continue;
+    }
+    for (const facetKey of docFacetKeys(document)) {
+      let members = facetToDocs.get(facetKey);
+      if (!members) {
+        members = [];
+        facetToDocs.set(facetKey, members);
+      }
+      if (!members.includes(id)) {
+        members.push(id);
+      }
+    }
+  }
+  const hyperedges = new Map();
+  for (const [facet, ids] of facetToDocs) {
+    if (ids.length >= 2) {
+      hyperedges.set(facet, ids.slice().sort());
+    }
+  }
+  const docHyperedges = new Map();
+  for (const [facet, ids] of hyperedges) {
+    for (const id of ids) {
+      let facets = docHyperedges.get(id);
+      if (!facets) {
+        facets = new Set();
+        docHyperedges.set(id, facets);
+      }
+      facets.add(facet);
+    }
+  }
+  return { hyperedges, docHyperedges };
+}
+
+function computeNodeDegree(graph, docIdSet) {
+  const degree = new Map();
+  const edges = graph && Array.isArray(graph.edges) ? graph.edges : [];
+  for (const edge of edges) {
+    const source = edge && edge.source;
+    const target = edge && edge.target;
+    if (docIdSet.has(source) && docIdSet.has(target)) {
+      degree.set(source, (degree.get(source) || 0) + 1);
+      degree.set(target, (degree.get(target) || 0) + 1);
+    }
+  }
+  return degree;
+}
+
+// Bounded hyperedge co-member expansion. Returns ranked expansion entries
+// ({ id, facets, relation }). Mirrors _expand_via_hyperedges in the Python server:
+// shared-facet-count desc -> node_degree desc -> title/id lexical, with a family cap.
+function expandSourcesViaHyperedges(seedIds, derived, nodeDegree, docsById, options) {
+  const opts = options || {};
+  const maxExpansion = Number.isInteger(opts.maxExpansion)
+    ? opts.maxExpansion
+    : DEFAULT_MAX_HYPEREDGE_EXPANSION;
+  const minCoMembership = Number.isInteger(opts.minCoMembership)
+    ? opts.minCoMembership
+    : DEFAULT_MIN_HYPEREDGE_CO_MEMBERSHIP;
+  const familyCap = Number.isInteger(opts.familyCap)
+    ? opts.familyCap
+    : DEFAULT_MAX_FAMILY_HYPEREDGE_CONTRIB;
+  if (maxExpansion <= 0) {
+    return [];
+  }
+  const seedSet = new Set(seedIds);
+  const seedFacets = new Set();
+  for (const seedId of seedIds) {
+    const facets = derived.docHyperedges.get(seedId);
+    if (facets) {
+      for (const facet of facets) {
+        seedFacets.add(facet);
+      }
+    }
+  }
+  if (seedFacets.size === 0) {
+    return [];
+  }
+  const candidateFacets = new Map();
+  for (const facet of seedFacets) {
+    const members = derived.hyperedges.get(facet) || [];
+    for (const id of members) {
+      if (seedSet.has(id)) {
+        continue;
+      }
+      let facets = candidateFacets.get(id);
+      if (!facets) {
+        facets = new Set();
+        candidateFacets.set(id, facets);
+      }
+      facets.add(facet);
+    }
+  }
+  const candidates = [];
+  for (const [id, facets] of candidateFacets) {
+    if (facets.size >= minCoMembership) {
+      candidates.push({ id, facets });
+    }
+  }
+  candidates.sort((a, b) => {
+    if (b.facets.size !== a.facets.size) {
+      return b.facets.size - a.facets.size;
+    }
+    const degreeDelta = (nodeDegree.get(b.id) || 0) - (nodeDegree.get(a.id) || 0);
+    if (degreeDelta !== 0) {
+      return degreeDelta;
+    }
+    const titleA = String((docsById.get(a.id) || {}).title || a.id).toLowerCase();
+    const titleB = String((docsById.get(b.id) || {}).title || b.id).toLowerCase();
+    if (titleA !== titleB) {
+      return titleA < titleB ? -1 : 1;
+    }
+    const idA = a.id.toLowerCase();
+    const idB = b.id.toLowerCase();
+    if (idA !== idB) {
+      return idA < idB ? -1 : 1;
+    }
+    return 0;
+  });
+  const selected = [];
+  let familyOnlyAdmitted = 0;
+  for (const candidate of candidates) {
+    if (selected.length >= maxExpansion) {
+      break;
+    }
+    let hasNonFamily = false;
+    for (const facet of candidate.facets) {
+      if (!facet.startsWith("family:")) {
+        hasNonFamily = true;
+        break;
+      }
+    }
+    if (!hasNonFamily) {
+      // OQ-C: cap how many docs can enter via a family facet alone.
+      if (familyOnlyAdmitted >= familyCap) {
+        continue;
+      }
+      familyOnlyAdmitted += 1;
+    }
+    const sortedFacets = Array.from(candidate.facets).sort();
+    selected.push({
+      id: candidate.id,
+      facets: sortedFacets,
+      relation: `shares ${sortedFacets.join(", ")}`,
+    });
+  }
+  return selected;
+}
+
+function buildSources(index, sourceFilters, maxSources, graph) {
   const documents = Array.isArray(index.documents) ? index.documents : [];
   const filters = (sourceFilters || []).map((item) => item.trim()).filter(Boolean);
   const limit = Number.isInteger(maxSources) && maxSources > 0 ? maxSources : DEFAULT_MAX_SOURCES;
 
-  return documents
-    .map((document) => {
-      const sourcePath = extractDocumentPath(document);
-      return {
-        id: document.id || sourcePath,
-        path: sourcePath,
-        title: document.title || sourcePath,
-        text: extractDocumentText(document),
-      };
-    })
-    .filter((source) => {
-      if (filters.length === 0) {
-        return true;
-      }
-      return filters.some((filter) => source.id === filter || source.path === filter);
-    })
-    .slice(0, limit);
+  const mapped = documents.map((document) => {
+    const sourcePath = extractDocumentPath(document);
+    return {
+      id: document.id || sourcePath,
+      path: sourcePath,
+      title: document.title || sourcePath,
+      text: extractDocumentText(document),
+      relation: "primary",
+    };
+  });
+
+  // No explicit --source filter: ground on all docs, unchanged (no expansion).
+  if (filters.length === 0) {
+    return mapped.slice(0, limit);
+  }
+
+  const primaries = mapped.filter((source) =>
+    filters.some((filter) => source.id === filter || source.path === filter)
+  );
+
+  // BK-269: append the filtered docs' hyperedge co-members (capped, labelled),
+  // so `--source <doc>` also grounds on its directly-related siblings.
+  const sourceById = new Map(mapped.map((source) => [source.id, source]));
+  const docsById = new Map();
+  for (const document of documents) {
+    if (!document || typeof document !== "object") {
+      continue;
+    }
+    const id = docId(document);
+    if (id && !docsById.has(id)) {
+      docsById.set(id, document);
+    }
+  }
+  const derived = deriveHyperedges(documents);
+  const nodeDegree = computeNodeDegree(graph, new Set(docsById.keys()));
+  const seedIds = primaries.map((source) => source.id);
+  const expansion = expandSourcesViaHyperedges(seedIds, derived, nodeDegree, docsById, {});
+
+  const result = primaries.slice();
+  const seen = new Set(seedIds);
+  for (const item of expansion) {
+    if (seen.has(item.id)) {
+      continue;
+    }
+    const base = sourceById.get(item.id);
+    if (!base) {
+      continue;
+    }
+    seen.add(item.id);
+    result.push({ ...base, relation: item.relation });
+  }
+  return result.slice(0, limit);
 }
 
 function normalizeCitations(citations) {
@@ -126,6 +354,7 @@ function normalizeAskResult(rawResult, context) {
     citations: normalizeCitations(result.citations),
     confidence: result.confidence,
     graphPath: context.graphPath,
+    expandedDocCount: Number.isInteger(context.expandedDocCount) ? context.expandedDocCount : 0,
   };
 }
 
@@ -139,7 +368,10 @@ async function runWikiAsk(options) {
   const graphInfo = assertWikiGraphReady(projectPath);
   const index = readJsonFile(graphInfo.indexPath, INDEX_FILE);
   const graph = readJsonFile(graphInfo.graphFilePath, GRAPH_FILE);
-  const sources = buildSources(index, options.sources, options.maxSources);
+  const sources = buildSources(index, options.sources, options.maxSources, graph);
+  const expandedDocCount = sources.filter(
+    (source) => source.relation && source.relation !== "primary"
+  ).length;
 
   const handlerState = await loadWikiAskHandler();
   if (!handlerState.ok) {
@@ -155,6 +387,7 @@ async function runWikiAsk(options) {
     graphFilePath: graphInfo.graphFilePath,
     graph,
     sources,
+    expandedDocCount,
     maxSources: options.maxSources,
   };
 
@@ -170,6 +403,8 @@ async function runWikiAsk(options) {
 
 module.exports = {
   buildSources,
+  deriveHyperedges,
+  expandSourcesViaHyperedges,
   normalizeAskResult,
   runWikiAsk,
 };

package/src/lib/wiki-config.js

@@ -71,7 +71,9 @@ function resolveWikiConfig(flags = {}) {
   ) {
     scanRoots = persisted.scanRoots.map((r) => path.resolve(r));
   } else {
-    scanRoots = [projectPath];
+    const docsDir = path.join(projectPath, "docs");
+    const hasDocsDir = fs.existsSync(docsDir) && fs.statSync(docsDir).isDirectory();
+    scanRoots = [hasDocsDir ? docsDir : projectPath];
   }
 
   const excludes =