@neuralis/brain-core 0.3.0 → 0.3.2

package/app/filesystem/lib/sourceKindForm.ts

@@ -1,8 +1,10 @@
 /**
- * How a connector kind's ROOT field renders in the Add-Source form — derived
+ * How a connector kind's config fields render in the Add-Source form — derived
  * from the DECLARATION, never from the kind name and never from `isDocker`.
+ * The ROOT field first; the other fields' closed control set is `fieldControl`
+ * below.
  *
- * Every other field in that form already renders from its declared
+ * Every other field in that form renders from its declared
  * `x-neuralis.ui`; `root` was the one hand-written, kind-BLIND exception, which
  * is why the Host Machine kind used to show the `local` connector's Docker
  * volume picker, its `pnpm neuralis:mount add` callout and a `/mounts/...`
@@ -12,10 +14,10 @@
  * `control` carries the distinction that matters:
  *   - `container-path` — the root lives in the CONTAINER filesystem, so the
  *     `/mounts` volume picker, the mount-CLI callout and Browse all apply.
- *   - `host-path` — the root lives on the operator's machine, reached through
- *     the host broker. None of that chrome applies, and Browse least of all:
+ *   - `host-path` — the root lives on a paired device, reached through that
+ *     device's broker. None of that chrome applies, and Browse least of all:
  *     `GET /sources/browse` readdirs in the SERVER process, i.e. the wrong
- *     machine. A host root's authority is the operator-owned broker ceiling.
+ *     machine. A host root is bounded by that device's own allowlist.
  *   - `path` (or absent) — the pre-existing form. Treated as container-plane,
  *     so an externally authored connector keeps working unchanged.
  *
@@ -64,3 +66,105 @@ export function rootFieldMeta(meta: SourceKindFormMeta | null | undefined): Root
     placeholder: typeof ui?.placeholder === 'string' ? ui.placeholder : '',
   };
 }
+
+/**
+ * How a NON-root config field renders. A CLOSED set: `text` (the default — a
+ * plain input, `number` for a numeric type) and `select`, whose options a
+ * route in the DECLARING package answers (`x-neuralis.ui.optionsRoute`).
+ *
+ * The list a `select` shows is UX only: the declaring package re-checks the
+ * picked value when the source is created (a host source's `device` is
+ * re-checked by the device's owner rule), so the form never decides who may
+ * attach what. An `optionsRoute` the form refuses (absolute, a scheme, a `..`
+ * segment, an escape) renders the field as `text` and names the refusal —
+ * never a request to somewhere the declaration did not mean.
+ */
+export type FieldControl =
+  | { control: 'text'; numeric: boolean; refused?: string }
+  | { control: 'select'; numeric: boolean; options: OptionsRoute };
+
+/** A validated options route: one package-relative path + its query. */
+export type OptionsRoute = { slug: string; path: string; params: Record<string, string> };
+
+const ROUTE_PATH = /^[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/[A-Za-z0-9._~-]+)*$/;
+const ROUTE_QUERY_PART = /^[A-Za-z0-9._~-]+$/;
+
+/**
+ * The `/api/packages/<slug>` segment of a registry id: the first-party scope is
+ * dropped (`@neuralis/agent-core` → `agent-core`, the same rule the route
+ * gateway resolves), any other id travels as ONE encoded segment.
+ */
+export function packageRouteSlug(packageId: string): string {
+  return encodeURIComponent(packageId.replace(/^@neuralis\//, ''));
+}
+
+/**
+ * Parse a declared `optionsRoute` against the package that declares the field.
+ * Relative only, plain path segments (no `.`/`..`, no `%`, no `\`), an optional
+ * `key=value&…` query of the same characters, ≤ 200 characters.
+ */
+export function parseOptionsRoute(raw: unknown, packageId: string): OptionsRoute | { refused: string } {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > 200) {
+    return { refused: 'optionsRoute must be a non-empty string of at most 200 characters' };
+  }
+  if (!packageId) return { refused: 'optionsRoute has no declaring package' };
+  const [path, query, extra] = raw.split('?');
+  if (extra !== undefined || !ROUTE_PATH.test(path ?? '')) {
+    return { refused: 'optionsRoute must be a relative route inside the declaring package' };
+  }
+  if ((path ?? '').split('/').some((segment) => segment === '.' || segment === '..')) {
+    return { refused: 'optionsRoute must be a relative route inside the declaring package' };
+  }
+  const params: Record<string, string> = {};
+  if (query !== undefined) {
+    for (const pair of query.split('&')) {
+      const [key, value, more] = pair.split('=');
+      if (more !== undefined || !key || !ROUTE_QUERY_PART.test(key) || (value !== undefined && value !== '' && !ROUTE_QUERY_PART.test(value))) {
+        return { refused: 'optionsRoute query must be plain key=value pairs' };
+      }
+      params[key] = value ?? '';
+    }
+  }
+  return { slug: packageRouteSlug(packageId), path: path as string, params };
+}
+
+export function fieldControl(prop: unknown, packageId: string): FieldControl {
+  const p = (prop ?? {}) as { type?: unknown; 'x-neuralis'?: { ui?: { control?: unknown; optionsRoute?: unknown } } };
+  const numeric = p.type === 'number' || p.type === 'integer';
+  const ui = p['x-neuralis']?.ui;
+  if (ui?.control !== 'select') return { control: 'text', numeric };
+  const route = parseOptionsRoute(ui.optionsRoute, packageId);
+  if ('refused' in route) return { control: 'text', numeric, refused: route.refused };
+  return { control: 'select', numeric, options: route };
+}
+
+/** One row of a `select`: the stored value, its label, and whether it reads dimmed. */
+export type SelectOption = { value: string; label: string; dimmed: boolean };
+
+/**
+ * The options an `optionsRoute` answered. The answer is a JSON object whose
+ * FIRST array-valued property lists the rows; a row is `{id, name?, status?,
+ * confinement?}` (the shape of a device list). The label is
+ * `name · status · confinement`; a `revoked` row is not offered at all; any
+ * status other than `online` reads dimmed but stays selectable — attaching a
+ * source to an offline device is allowed, it simply answers once the device is
+ * back. Rows without a string `id` are dropped.
+ */
+export function selectOptionsFrom(answer: unknown): SelectOption[] {
+  if (!answer || typeof answer !== 'object') return [];
+  const rows = Object.values(answer as Record<string, unknown>).find(Array.isArray) as unknown[] | undefined;
+  if (!rows) return [];
+  const out: SelectOption[] = [];
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') continue;
+    const r = row as { id?: unknown; name?: unknown; status?: unknown; confinement?: unknown };
+    if (typeof r.id !== 'string' || r.id.length === 0) continue;
+    const status = typeof r.status === 'string' ? r.status : undefined;
+    if (status === 'revoked') continue;
+    const parts = [typeof r.name === 'string' && r.name ? r.name : r.id];
+    if (status) parts.push(status.replace(/_/g, ' '));
+    if (typeof r.confinement === 'string') parts.push(r.confinement);
+    out.push({ value: r.id, label: parts.join(' · '), dimmed: status !== undefined && status !== 'online' });
+  }
+  return out;
+}

package/app/filesystem/store/filesystemStore.ts

@@ -900,6 +900,13 @@ interface FilesystemStore extends FileSystemState, SearchSliceActions, ListSlice
   activeFolderPath: string | null;
 
   uploading: boolean;
+  /**
+   * Bumped once per burst of `devices` frames (and on a hub reconnect): a
+   * paired device changed state. Consumers holding their own device fetch —
+   * the source form's device `select` — re-read on it. Not per context and
+   * never persisted.
+   */
+  deviceRevision: number;
   workspacePanels: Record<WorkspacePanelId, boolean>;
   // `'git-diff'` (G2.2) and `'git-commit'` (G2.4/C2 — the multi-file stacked
   // commit/outgoing view) are VIEWS, not toggleable panels — they live outside
@@ -1088,9 +1095,11 @@ const FILESYSTEM_WIDGET_TYPE = 'filesystem';
 /**
  * File-tree sidebar is a **fixed pixel** column (mirrors the admin widget):
  * its width is independent of the outer widget size, so resizing the widget in
- * the workspace never reflows the tree. The width is user-draggable and survives
- * reloads via localStorage. The drag handle clamps the upper bound to the live
- * container width so the tree can fully cover the file editor.
+ * the workspace never reflows the tree until the widget edge reaches it — then
+ * the rendered width is capped to the container and grows back to this stored
+ * width on widening. The width is user-draggable and survives reloads via
+ * localStorage. The drag handle clamps the upper bound to the live container
+ * width so the tree can fully cover the file editor.
  */
 export const FILESYSTEM_SIDEBAR_MIN_WIDTH = 120;
 const SIDEBAR_WIDTH_DEFAULT = 240;
@@ -1178,6 +1187,7 @@ export function createFilesystemStore(init: FilesystemStoreInit): FilesystemStor
   activeRepoRel: '',
   activeFolderPath: 'brain://docs',
   uploading: false,
+  deviceRevision: 0,
   workspacePanels: { upload: false, sources: false, packages: false, pending: false },
   activeWorkspaceTab: 'file',
   pendingSourceSuggestion: null,

package/app/filesystem/ui/DiscoverDock.tsx

@@ -56,9 +56,13 @@ export function DiscoverDock({ suggestions, expanded, onToggleExpanded, onPick,
   return (
     <div
       className={cn(
-        'group/discover shrink-0 border-t border-white/[0.06] bg-[#0b0b0f]/95',
+        'group/discover shrink-0 border-t border-white/[0.06]',
         overlay ? 'absolute inset-x-0 bottom-0 z-20 shadow-[0_-8px_24px_rgba(0,0,0,0.45)]' : '',
       )}
+      // Collapsed it carries no surface of its own (the panel chrome owns it);
+      // only the overlay form needs a scrim, derived from the theme so it
+      // matches every workspace theme.
+      style={overlay ? { backgroundColor: 'rgba(var(--w-bg-rgb), 0.96)' } : undefined}
       data-testid="discover-dock"
     >
       <div className="flex items-center justify-between px-2 pt-1.5 pb-1">

package/app/filesystem/ui/FileTree.tsx

@@ -1,7 +1,7 @@
 'use client';
 
 import { useFilesystemStore, useFilesystemStoreApi, type SidebarView } from '../store/filesystemStore';
-import React, { useMemo, useState, useCallback, useRef, useEffect } from 'react';
+import React, { useMemo, useState, useCallback, useRef, useEffect, useLayoutEffect } from 'react';
 import { SkillLauncher } from '@neuralis/package-system/client';
 import { meetsRequires } from '@neuralis/package-system/access';
 import { useVirtualizer } from '@tanstack/react-virtual';
@@ -439,9 +439,9 @@ export function FileTree(props: { agentId: string; sidebarView?: SidebarView })
     return uris.map((u) => files[u]).filter(Boolean) as FileNode[];
   }, [contextMenu, selection, files]);
 
-  // HIDE-ONLY mirror of the reindex route's `drive.sync` gate — the route decides.
+  // HIDE-ONLY mirror of the reindex route's `sources.sync` gate — the route decides.
   const canSync = useMemo(
-    () => meetsRequires({ grantedFeatures: [...(host.grantedFeatures ?? [])] }, { features: ['drive.sync'] }),
+    () => meetsRequires({ grantedFeatures: [...(host.grantedFeatures ?? [])] }, { features: ['sources.sync'] }),
     [host.grantedFeatures],
   );
   const [reembedTarget, setReembedTarget] = useState<ReembedTarget | null>(null);
@@ -700,7 +700,7 @@ export function FileTree(props: { agentId: string; sidebarView?: SidebarView })
     () => sourceInfos.every((info) => !sourceBranchExpanded[info.uri_root]),
     [sourceInfos, sourceBranchExpanded],
   );
-  // HIDE-ONLY feature gate. The server list is already `drive.read`-gated and
+  // HIDE-ONLY feature gate. The server list is already `files.read`-gated and
   // `seeRequires`-filtered, so this hides an affordance the caller could not use
   // and authorizes NOTHING — the attach route stays the boundary. Hidden
   // entirely, never a locked row (the S2 discipline). Evaluated with the ONE
@@ -709,7 +709,7 @@ export function FileTree(props: { agentId: string; sidebarView?: SidebarView })
     // The host value keeps the list `readonly` so no UI file can mutate the
     // caller's grants; the kernel predicate takes a mutable array, so copy at
     // the boundary rather than widening the contract.
-    () => meetsRequires({ grantedFeatures: [...(host.grantedFeatures ?? [])] }, { features: ['drive.mount'] }),
+    () => meetsRequires({ grantedFeatures: [...(host.grantedFeatures ?? [])] }, { features: ['sources.mount'] }),
     [host.grantedFeatures],
   );
   // FETCH: lazily, only once the dock could actually render. An eager fetch on
@@ -779,6 +779,32 @@ export function FileTree(props: { agentId: string; sidebarView?: SidebarView })
     getItemKey,
   });
 
+  // The scroller UNMOUNTS whenever the git panel or a loading/empty state replaces
+  // the tree, but the virtualizer instance survives with its old scroll offset. On
+  // re-attach virtual-core writes that offset onto the NEW element; when the new
+  // content is still too short the browser clamps `scrollTop` to 0 without firing
+  // a scroll event, and the virtualizer keeps windowing from the stale offset — the
+  // first rows stay unrendered above a blank gap until the user scrolls. One read
+  // per attach (declared after `useVirtualizer`, so it runs after its `_willUpdate`)
+  // re-feeds the real offset through the virtualizer's own scroll listener — in a
+  // microtask, because that listener re-renders with `flushSync`, which React
+  // refuses inside a commit; the microtask still lands before the frame paints.
+  const scrollerAttachedRef = useRef(false);
+  const attachScroller = useCallback((el: HTMLDivElement | null) => {
+    parentRef.current = el;
+    if (el) scrollerAttachedRef.current = true;
+  }, []);
+  useLayoutEffect(() => {
+    if (!scrollerAttachedRef.current) return;
+    scrollerAttachedRef.current = false;
+    const el = parentRef.current;
+    if (el && el.scrollTop !== (virtualizer.scrollOffset ?? 0)) {
+      queueMicrotask(() => {
+        if (parentRef.current === el) el.dispatchEvent(new Event('scroll'));
+      });
+    }
+  });
+
   // Git Control view (G2.1, Q1) — the panel REPLACES the tree + search IN PLACE,
   // exactly like search does. Early-return AFTER all hooks (so none are skipped)
   // and BEFORE the loading/empty tree short-circuits (the git panel owns its own
@@ -806,7 +832,7 @@ export function FileTree(props: { agentId: string; sidebarView?: SidebarView })
 
   // Root-listing failure (the SERVICE answered nothing — a single source's
   // failure is its own header's `error` state). Without this surface the tree
-  // was silently "Empty Drive": the store wrote `snapshotError` and nothing read
+  // was silently "No files yet": the store wrote `snapshotError` and nothing read
   // it. Retry re-runs the same root listing; a listing that answers clears it.
   const snapshotBanner = snapshotError && !showSearch ? (
     <div
@@ -835,7 +861,7 @@ export function FileTree(props: { agentId: string; sidebarView?: SidebarView })
   ) : null;
 
   if (!allNodes.length && !showSearch && !hasSources) {
-    return snapshotBanner ?? <div className="p-4 text-center text-xs text-white/30">Empty Drive</div>;
+    return snapshotBanner ?? <div className="p-4 text-center text-xs text-white/30">No files yet</div>;
   }
 
   const renderNode = (node: FileNode, depth: number) => {
@@ -881,7 +907,7 @@ export function FileTree(props: { agentId: string; sidebarView?: SidebarView })
     // `relative` anchors the dock's EXPANDED overlay form.
     <div className="relative flex min-h-0 flex-1 flex-col">
     <div
-      ref={parentRef}
+      ref={attachScroller}
       tabIndex={0}
       onKeyDown={handleTreeKeyDown}
       onContextMenu={handleBackgroundContextMenu}

package/app/filesystem/ui/FilesystemWidget.tsx

@@ -28,6 +28,7 @@ export function FilesystemWidget(props: { agentId: string; projectId?: string |
   const setSidebarView = useFilesystemStore((s) => s.setSidebarView);
   const lastAppliedNavRef = useRef<string | null>(null);
   const splitRef = useRef<HTMLDivElement | null>(null);
+  const sidebarRef = useRef<HTMLDivElement | null>(null);
   const dragRef = useRef<{ startX: number; startWidth: number } | null>(null);
   const [dragging, setDragging] = useState(false);
 
@@ -103,11 +104,16 @@ export function FilesystemWidget(props: { agentId: string; projectId?: string |
   // the move keeps tracking even when the cursor leaves the thin handle. The
   // upper bound is the live container width (minus the handle), so the tree can
   // be dragged all the way over the editor, leaving only tree + chat visible.
+  // The RENDERED width is capped by CSS at the same bound: a narrowing widget
+  // eats the editor first, then the tree, and widening grows the tree back to
+  // the stored width — so the drag starts from the rendered width, never the
+  // stored one, or a capped tree would not follow the pointer at first.
   const HANDLE_WIDTH = 8;
   const onHandlePointerDown = useCallback(
     (e: React.PointerEvent<HTMLDivElement>) => {
       e.preventDefault();
-      dragRef.current = { startX: e.clientX, startWidth: sidebarWidth };
+      const rendered = sidebarRef.current?.offsetWidth;
+      dragRef.current = { startX: e.clientX, startWidth: rendered && rendered < sidebarWidth ? rendered : sidebarWidth };
       setDragging(true);
       e.currentTarget.setPointerCapture(e.pointerId);
     },
@@ -150,9 +156,11 @@ export function FilesystemWidget(props: { agentId: string; projectId?: string |
         className={`flex-1 min-h-0 flex flex-row ${dragging ? 'select-none cursor-col-resize' : ''}`}
       >
         <div
+          ref={sidebarRef}
           className="h-full flex flex-col min-h-0 shrink-0 overflow-hidden"
           style={{
             width: sidebarOpen ? sidebarWidth : 0,
+            maxWidth: `calc(100% - ${HANDLE_WIDTH}px)`,
             backgroundColor: 'transparent',
             borderRight: sidebarOpen ? '1px solid rgba(255,255,255,0.05)' : 'none',
           }}
@@ -238,7 +246,7 @@ export function FilesystemWidget(props: { agentId: string; projectId?: string |
           </div>
         )}
 
-        <div className="flex-1 min-w-0 min-h-0">
+        <div className="flex-1 min-w-0 min-h-0 overflow-hidden">
           <FileEditor />
         </div>
       </div>

package/app/filesystem/ui/GitControlPanel.tsx

@@ -84,7 +84,7 @@ import {
  * Stage / Unstage / Discard, a commit box (message + optional amend), and a
  * branch-switcher quick-pick (checkout / create / delete). Each write is the
  * HUMAN face of the git engine — the click IS the consent (server gates
- * `drive.write` + uri-policy `write` + audits); a DESTRUCTIVE op (discard,
+ * `files.write` + uri-policy `write` + audits); a DESTRUCTIVE op (discard,
  * branch delete) is behind a CONFIRM dialog AND the server unconditionally
  * auto-snapshots (Q6) — the returned rescue ref powers a best-effort recovery
  * notice. On success the N3 badge SSE refreshes the panel; we ALSO
@@ -592,7 +592,7 @@ export function GitControlPanel({ agentId }: { agentId: string }) {
   );
   // Show the write affordances (Stage/Unstage/Discard/Commit/branch-write) IFF the
   // caller can actually write — `git.canWrite` is computed SERVER-side per-caller as
-  // the SAME two-plane gate the write routes enforce (the `drive.write` FEATURE ∧ the
+  // the SAME two-plane gate the write routes enforce (the `files.write` FEATURE ∧ the
   // caller's RESOLVED uri-policy `write` on the source root). This is authoritative:
   // it must NOT read `SourceInfo.permissions.write` (the source's DEFAULT block), which
   // hid the owner's write UI on a `default write:false` source where the owner gains

package/app/filesystem/ui/PendingChangesPanel.tsx

@@ -216,7 +216,7 @@ const NO_FILTERS: ChangeFilters = { kind: 'all', source: '', repo: '', branch: '
 export function PendingChangesPanel({ agentId, projectId }: Props) {
   const client = useFilesystemStore((s) => s.client);
   const host = useFilesystemHost();
-  const canWrite = hasFeature({ grantedFeatures: [...(host.grantedFeatures ?? [])] }, 'drive.write');
+  const canWrite = hasFeature({ grantedFeatures: [...(host.grantedFeatures ?? [])] }, 'files.write');
   const storeApi = useFilesystemStoreApi();
   const sources = useFilesystemStore(s => s.sources);
   const liveRevisions = useFilesystemStore(s => s.sourceChangeRevision);

package/app/filesystem/ui/README.md

@@ -17,7 +17,7 @@ Re-exported from `app/filesystem/ui/index.ts`:
 - `FileTree`, `FileTreeNode`, `FileTreeSearch`, `SourceBranchHeader` — virtualised tree components (uses `@tanstack/react-virtual`). `FileTreeSearch` is the search PANEL body only (mode selector `keyword|semantic|grep`, filter row, results) — the query input rides inline in the sidebar HEADER (`FilesystemWidget`), panel visibility keys on `sidebarView === 'search'` alone (the header toggle/Escape clears + closes even with text), and the ≥2-char gate inside the panel only switches results-vs-hint. The store keeps the answer's `requested_mode`/`effective_mode`/`embedding_degraded`/`warning` as `searchEffect` (a `contextResetPatch` key) and the panel prints ONE `searchEffectLine` ("Searched as keyword — semantic search unavailable (<reason>)") plus an `embedding missing|stale` badge per row.
 - `FileTreeContextMenu`, `TreeDeleteConfirm` — the VS Code-style file-management surface (see the section below).
 - `ReembedDialog` — the ONE estimate-first embed dialog, shared by the Sources panel (a whole source) and the tree's context menu (a folder or a file): opening it asks `sources/reindex` for a sample-based ESTIMATE only (no queue job, no sync-marker change); the work starts on its button and nowhere else. `kind="reembed"` (default) = the forced re-embed of every file with the active model; `kind="pending"` = **Embed pending…**, the `embeddingOnly` debt pass (only missing/stale embeddings; the estimate is the scope's upper bound). Portaled like `TreeDeleteConfirm`.
-- `DiscoverDock` — the **Discover** list of attachable-but-unattached sources (`GET /sources/discoverable`), pinned below the tree. **It is a SIBLING of the virtualized scroller, never a `FlatItemKind`**: a sixth item kind would have to join the `rowEstimate`/`isMeasuredRow` contract for a list that is never long enough to need virtualizing. Two placements, one component — COLLAPSED it sits in normal flow below the scroller (takes height, covers nothing, bounded to 5 rows); EXPANDED the tree renders it as an `absolute bottom-0` overlay, the ONLY state in which it may hide tree rows. Never both, so the scroller's height cannot change while the overlay is up. Visible only while EVERY source branch is collapsed (`sourceBranchExpanded`, the React-local BRANCH state — not the store's `expandedFolders`) and only for a caller holding `drive.mount`. **Consequence to know:** `activeFile` is persisted and `FileTree`'s auto-expand opens its source branch, so a returning user with an open tab lands with the dock hidden until they collapse that branch. Clicking a row hands the whole suggestion to the Sources panel through the store (`pendingSourceSuggestion`) and opens it — the prefill body lives in `SourcesPanel.applySuggestion`, ONE body shared with the panel's own Discoverable list.
+- `DiscoverDock` — the **Discover** list of attachable-but-unattached sources (`GET /sources/discoverable`), pinned below the tree. **It is a SIBLING of the virtualized scroller, never a `FlatItemKind`**: a sixth item kind would have to join the `rowEstimate`/`isMeasuredRow` contract for a list that is never long enough to need virtualizing. Two placements, one component — COLLAPSED it sits in normal flow below the scroller (takes height, covers nothing, bounded to 5 rows); EXPANDED the tree renders it as an `absolute bottom-0` overlay, the ONLY state in which it may hide tree rows — and the only one with a surface: a scrim derived from `--w-bg-rgb`, so it matches every theme (collapsed it has none). Never both, so the scroller's height cannot change while the overlay is up. Visible only while EVERY source branch is collapsed (`sourceBranchExpanded`, the React-local BRANCH state — not the store's `expandedFolders`) and only for a caller holding `sources.mount`. **Consequence to know:** `activeFile` is persisted and `FileTree`'s auto-expand opens its source branch, so a returning user with an open tab lands with the dock hidden until they collapse that branch. Clicking a row hands the whole suggestion to the Sources panel through the store (`pendingSourceSuggestion`) and opens it — the prefill body lives in `SourcesPanel.applySuggestion`, ONE body shared with the panel's own Discoverable list.
 - `FileEditor`, `FileTab`, `FileMetaBar`, `CodeEditor`, `ReviewDiffView`, `EditorTabBar`, `DiffModeToggle` — the **VS Code-like editor stack**.
   - **`CodeEditor`** (CodeMirror 6 + an in-repo Shiki bridge under `codeEditor/`) is the ONE editor instance behind BOTH the read view (`readOnly`) and edit — toggling Edit only flips the `readOnly` Compartment, so the `EditorView` never remounts (no flash / scroll loss / re-tokenize). Syntax colors are the exact VS Code `dark-plus` TextMate grammars via Shiki's **JavaScript regex engine** — so **no web worker, no `.wasm`, no host CSP change** (`codeEditor/shikiHighlighter.ts` = the memoized core + `tokenizeLines` for the git-diff path — the core, the engine, both themes and all 50 `@shikijs/langs` grammars are dynamic imports, one split chunk each, so nothing of Shiki is on the module's cold path; the 15 base grammars load WITH the core so a markdown fence in one of them colours at once, the rest on first use; `codeEditor/shikiChunks.ts` = the INCREMENTAL tokenizer — position-anchored, line-aligned chunks closed at 64 lines OR 4 KB of text (whichever first) with TextMate grammar-state continuation, chunk-relative token offsets, the visible chunks tokenized synchronously under a 16 KB per-paint character budget (CodeMirror's `visibleRanges` right after a whole-document replace spans thousands of unmeasured lines — the budget, not the viewport estimate, bounds the sync path) and the prefix + a 4-chunk horizon after the viewport in idle slices (a slice is at least one chunk: measured ~90 ms worst case on dense TS/TSX and on long-line markdown, ~50 ms typical code, ~2–5 ms short-line prose — chunks past the horizon wait until scrolled to, so opening a file costs the viewport, not the document), a keystroke re-tokenizing its own chunk and walking forward only until the grammar state converges, a far scroll coloured provisionally first and corrected by the idle pass, and a whole-document replace (every file switch / reload / revert is one) split back into chunks eagerly so the first paint never tokenizes the whole file; `codeEditor/shikiDecorations.ts` = the per-view `ViewPlugin`→`DecorationSet` bridge that owns one engine per editor, because `@shikijs/codemirror` does not exist). The 120k wall is gone; `MAX_HIGHLIGHT_CHARS` (2 MB) is a memory guard on the document (above it the file renders plain), not a tokenization budget. Shared 12px/18px base theme (`codeEditor/editorTheme.ts`).
   - **`ReviewDiffView`** renders the vector-sync **pending-review** diff on `@codemirror/merge` (unified / split, read-only, accept/reject chunk controls disabled — Approve/Revert stays the banner's job) on the SAME base theme, so the editor↔diff transition never jumps.
@@ -49,23 +49,24 @@ Re-exported from `app/filesystem/ui/index.ts`:
 - `VectorHealthPanel` = **janitor** — the panel's role is "remove leftover records" (deleted past retention, orphaned chunks, duplicate report). Full per-source vector wipe lives on `SourceDeleteConfirm`, not here. `dryRun` default is `false` (clicking actually deletes); destructive buttons need a 2-click confirm; the Deleted stat card shows a `before → after (−Δ)` line after `GC`. Per-action explainer copy + tooltips spell out what each button does (GC / Repair are destructive; Deduplicate is read-only on the service side).
 - `VectorHealthPanel` is **lazy** — `SourcesPanel` renders it ONLY when the "Vector Health" section is expanded (`{healthOpen && …}`, the store's `vectorHealthOpen`, so a notification's `open-vector-health` nav can open it; a `contextResetPatch` key), never a CSS-only collapse, because the panel auto-fetches on mount; a mounted-but-hidden panel would fire the health request every time the Sources tab opens. On open it fetches the CHEAP count stats (`checkVectorHealth` → `/health`, count-only). The **Orphans** card and **Duplicate groups** count come from the EXPENSIVE on-demand scan (`scanVectorHealth` → `/health/scan`) behind an explicit **"Scan for problems"** button — they show `—` until the user runs it (and re-scan after a destructive action only if a scan was already loaded). This is the "ne lassítson 1 dolog mindent" rule: opening Sources triggers no collection walk.
 - `SourcesPanel` add form, the ROOT field — **derived from the declaration, not from `isDocker` and not from the kind name** (`lib/sourceKindForm.ts` `rootFieldMeta`, drift-tested against the real manifests in `test/ui/sourceKindForm.test.ts`). Every other field in that form already rendered from its declared `x-neuralis.ui`; `root` was the one hand-written, kind-BLIND exception, which is why the **Host Machine** kind used to show the `local` connector's `/mounts` volume picker, its `pnpm neuralis:mount add` callout and a `/mounts/...` placeholder while its own declaration said `Host root path` / `/home/you/projects` (warded-wren, closing the UI half of F-B5). The discriminator is the declared `x-neuralis.ui.control` on `root`: `container-path` gets the volume picker + callout + Browse; `host-path` gets none of them; a bare legacy `path` (or an absent control) is treated as container-plane, so an externally authored connector is unchanged. **Not `isHostPlaneKind`** — that is a NAME test whose own docstring says a future `ssh`/`smb` kind joins the plane by being added to its body, so a negative test on it would hand the container chrome to every future non-`local` kind. Browse is additionally gated on `canMount` (the shared `meetsRequires` mirror `FileTree` uses) and stays absent for host-plane roots at all times: `GET /sources/browse` readdirs in the SERVER process, the wrong machine for a broker-resolved host root — a host-plane root browser would need a broker-backed listing route, which does not exist.
+- `SourcesPanel` add form, every OTHER field — renders from the closed control set in the same file (`fieldControl`): a text input (numeric for a number type), or `control: "select"`, whose options come from `x-neuralis.ui.optionsRoute` — a relative route in the DECLARING package (`kinds[].packageId`), read once per form through that package's own route client and quietly again after each burst of `devices` frames (the store's `deviceRevision`, bumped by `useFilesystemSSE`'s ONE `devices` subscription, which also re-reads the source summaries so a host source's liveness follows its device), label `name · status · confinement`, a `revoked` row never offered, any other non-`online` row dimmed but selectable (the host connector's `device` field lists `devices?scope=mine`). An `optionsRoute` that is absolute, carries a scheme, a `.`/`..` segment or a `%`/`\` is refused and the field renders as text with the reason. The list is UX only — the declaring package re-checks the value at create.
 - `SourcesPanel` description field — the VALUE is empty whenever the description is RESOLVED rather than stored (`description_effective`), and that is load-bearing: prefilling the value would freeze a copy of the package's wording into this source's config and stop it tracking the package. The resolved text therefore rides as the **placeholder** in edit state (with a one-line note saying an empty box keeps following the package) and as **labelled** text — `"… (from the package)"` — in the read state and the collapsed summary. **Both states must carry the label**: live-testing warded-wren caught it present in the read state and absent in the edit state, where the box simply looked empty; an opacity difference alone is not a label, because it does not survive the state that matters (editing).
 
 - `SourceDeleteConfirm` — inline rose-tinted popover under the row (no modal, matches the panel's "no overlay" pattern). Headline + one-line reminder that the host folder is not touched + `[ ] Purge vector index entries (~N point(s))` checkbox (default OFF — conservative) + Docker-bind-mount warning ribbon when `connection.config.hostRoot` is set, telling the user to run `neuralis mount remove <slug>` before restarting the container. On confirm, `SourcesPanel.handleDelete` calls `deleteSource({ purgeVectors })` and surfaces a transient `successMsg` ("Deleted "<source>" (vectors purged: N)").
 - **`SkillLauncher` coverage** (`@neuralis/package-system/client`, additive "+" launchers) — every filesystem function the LLM can drive has a visible composer-prefill trace. Clicking a launcher PREFILLS the chat composer with the skill (+ scripts) like a `/` slash pick; it never sends/streams. **No launcher states a feature list**: visibility is DERIVED from the host's per-caller skill catalog, so it cannot drift from each skill's own `SKILL.md` `requiredFeatures` and an unresolved catalog renders nothing (the gate named per row below is the SKILL's, documented here, not repeated in the JSX). `packageId` is the REGISTRY id (`@neuralis/brain-core`), matched as an exact pair with the skill id. The launchers resolve the `WorkspaceHostPort` from the `WorkspaceHostPortProvider` mounted once in `host/installFilesystemHostComponents.tsx` — without it they render `null` silently. Current placements:
-  - `Toolbar` — `sync` (`drive.sync`, icon-`brain`, script-less) next to the Sources panel toggle, and `manage-files` (`drive.write`; `scripts: mkdir, copy, modify`) as the general file-ops handoff. The tree's CONTEXT MENU deliberately carries none: it is a keyboard-navigable click-to-act list with one uniform item model, and a composer-prefill affordance would need a bespoke item kind there.
-  - `SourcesPanel` header — `manage-sources` (`drive.read`, attached-left to the `+ Source` button).
-  - `SourcesPanel` per-source **Permissions** header — `manage-uri-policy` (`drive.policy` — no grant below the `admin` tier, grantable to any custom role) hands the URI-policy / path-permission edit for that source to the agent, alongside the `PolicyEditor`.
-  - `FileTree` empty-state — `manage-files` (`drive.write`, label; `scripts: upload, modify`) to populate a source.
-  - `GitControlPanel` header — `git` (`drive.read`) next to the refresh button. The `git` skill drives the SAME `/git/*` routes this panel does — its own SKILL.md says so — and the panel shipped with no way to reach it until 2026-07-28.
-  - `PendingChangesPanel` toolbar — `manage-files` (`drive.write`) for bulk review; the per-row approve/revert buttons stay the primary path.
-  - `VectorHealthPanel` actions row — `manage-sources` (`drive.read`). The index is per-SOURCE, so the agent-side equivalent of scan/repair is a source reindex plus a sync-status readout.
+  - `Toolbar` — `sync` (`sources.sync`, icon-`brain`, script-less) next to the Sources panel toggle, and `manage-files` (`files.write`; `scripts: mkdir, copy, modify`) as the general file-ops handoff. The tree's CONTEXT MENU deliberately carries none: it is a keyboard-navigable click-to-act list with one uniform item model, and a composer-prefill affordance would need a bespoke item kind there.
+  - `SourcesPanel` header — `manage-sources` (`files.read`, attached-left to the `+ Source` button).
+  - `SourcesPanel` per-source **Permissions** header — `manage-uri-policy` (`sources.policy` — no grant below the `admin` tier, grantable to any custom role) hands the URI-policy / path-permission edit for that source to the agent, alongside the `PolicyEditor`.
+  - `FileTree` empty-state — `manage-files` (`files.write`, label; `scripts: upload, modify`) to populate a source.
+  - `GitControlPanel` header — `git` (`files.read`) next to the refresh button. The `git` skill drives the SAME `/git/*` routes this panel does — its own SKILL.md says so — and the panel shipped with no way to reach it until 2026-07-28.
+  - `PendingChangesPanel` toolbar — `manage-files` (`files.write`) for bulk review; the per-row approve/revert buttons stay the primary path.
+  - `VectorHealthPanel` actions row — `manage-sources` (`files.read`). The index is per-SOURCE, so the agent-side equivalent of scan/repair is a source reindex plus a sync-status readout.
   - `PackagesPanel` header — `create-package` (label, script-less) hands the whole authoring flow (scaffold, manifest, tools, surfaces, connectors, build — including the WASM pipeline) to the agent; additive to the per-row `Build` button. This is the ONE launcher that narrows further, with `alsoRequires={["packages.author"]}`, even though the SKILL ships ungated (so it stays importable): it scaffolds into `packages://`, which needs write + install/build capability the default `member` role does not hold, so showing it to a caller whose first action would be denied is worse UX than hiding it. `alsoRequires` can only ever hide a launcher, never reveal one, so this cannot become a disclosure. Deliberate — do not "align" it with the skill frontmatter.
 
 ## How it plugs into the package-system kernel
 
 - Every component consumes the `useFilesystemHost()` context for agent state, file marks, accent colors, SSE URLs, and optional content renderers (the host can pass a markdown / code-highlight component).
-- API calls go through the `api/` module which wraps the kernel `PackageApi` — the brain-core route layer enforces `drive.read`, `drive.write`, `drive.search`, `drive.mount` features and source-scope checks server-side.
+- API calls go through the `api/` module which wraps the kernel `PackageApi` — the brain-core route layer enforces `files.read`, `files.write`, `files.search`, `sources.mount` features and source-scope checks server-side.
 - `PackagesPanel` calls host-side routes (`/api/packages/runtime`, `/api/projects/:id/packages/:slug/{build,trust,access-feature}`) through `api/projectPackages.ts`. The widget surfaces project-package operations here because they are project-scoped — they are NOT brain-core package routes.
 
 ### `recognizesPackages` source toggle + package access-feature governance
@@ -76,7 +77,7 @@ Re-exported from `app/filesystem/ui/index.ts`:
 ## Security & scope
 
 - Components never display raw `_meta` payloads (runtime billing telemetry); only `content` and `structuredContent` are rendered.
-- Cross-agent file marks and source observations are gated server-side by `filesystem.observeScoped` — the UI surfaces what the route returns and never tries to bypass the gate.
+- Cross-agent file marks and source observations are gated server-side by `files.readOthers` — the UI surfaces what the route returns and never tries to bypass the gate.
 - `PackagesPanel.setPackageTrust` / `setPackageAccessFeature` write to the platform zone via host routes; both require owner / admin role (`canManagePackages`). The access-feature override is restrict-only — it can attach a required feature, never grant access. Owner-only UI controls (the `recognizesPackages` toggle, the access-feature override) hide for non-owners via `host.currentRole`, but the server route is the enforcement floor.
 
 ## VS Code-style file management (context menu · drag · inline edit)
@@ -97,7 +98,7 @@ agent share the same server path, deny-by-default, server re-gated):
   target (rename = single file OR folder; New Folder disabled on `brain://`; Paste
   needs a clipboard; Re-embed… = a single file or folder, not on `brain://` — its
   content lives in the vector store, there is no file to read again — and only
-  for a `drive.sync` holder, the reindex route's gate, mirrored hide-only).
+  for a `sources.sync` holder, the reindex route's gate, mirrored hide-only).
 - **Multi-select** — Ctrl/⌘-click toggles, Shift-click ranges over the flat visible
   list; bulk delete/cut/copy fan out client-side, each server-gated.
 - **Inline rename + inline New File / New Folder** — an `<input>` in the tree row
@@ -156,11 +157,11 @@ EPHEMERAL (never persisted).
 - **The virtualizer's `estimateSize` / `getItemKey` are STABLE `useCallback`s reading the row list through a ref** — `getItemKey` is the only memo dependency of virtual-core's measurement options, so an inline arrow (a new identity per render) invalidated the measurement cache and re-ran the estimator for every unmeasured row on each render. No `measureElement` override: the default measurer already reads `offsetHeight`.
 - **The tab strip keeps the ACTIVE tab in view and scrolls on a vertical wheel.** The strip lives in `FileEditor`'s `data-tab-scroller` div, whose scrollbar is an invisible overlay until hover. Measured 2026-09-04 in a 536 px widget with a 327 px sidebar: the strip is 165 px, and a third opened tab was ACTIVE yet fully outside it, with nothing on screen saying the strip scrolls. `EditorTabBar` applies two exported pure rules — `tabScrollDelta` (the active tab's overflow, applied to the scroller's `scrollLeft`; never `scrollIntoView`, which would also scroll the stage) and `wheelToHorizontal` (a native non-passive `wheel` listener — React's `onWheel` is passive and cannot `preventDefault`). The panel CLIPS the strip: a tab rect past the panel edge is geometry, not paint (`elementFromPoint` there hits the neighbour), so the defect was the invisible active tab, never an overflow.
 - **A tab's content is fetched by the STORE, never by a widget effect.** `rehydrateActiveTab` runs from `loadList` (a same-context mount — page reload) and from `setActiveFile` (a tab click), against the store's own active pair and the read STATE (`hasCompletedRead`: a string baseline or an error — a folder listing materialises content-less nodes, so FileNode presence means nothing). The effect it replaced decided from its render closure and re-opened the PREVIOUS agent's tab under the new one after a switch, and skipped the read for a listed-but-unread sibling tab ("Empty file" on click). While a read is pending the editor's placeholder says "Loading…"; "Empty file" is reserved for a completed read. The whole widget state is per context: a switch stashes the outgoing `(user, project, agent)` context's tree, tabs, caches and panels and restores the incoming one's (`contextStateByKey`, `../store/README.md`), so switching back finds the tree and the editor where they were.
-- **Root-listing failure is visible.** `loadList`'s catch sets `snapshotError`; the tree renders it as a rose banner with Retry (re-runs the root listing) and Dismiss, in place of "Empty Drive" when no source is known yet. A listing that answers clears it.
+- **Root-listing failure is visible.** `loadList`'s catch sets `snapshotError`; the tree renders it as a rose banner with Retry (re-runs the root listing) and Dismiss, in place of "No files yet" when no source is known yet. A listing that answers clears it.
 - **Overlays.** `position: fixed` inside the widget is panel-anchored and panel-clipped at `dim` and `opaque` (the panel's `backdrop-filter`, load-bearing) and viewport-level only at `transparent` — so every toast and confirm dialog here (`PackagesPanel`'s toast + build log, `GitControlPanel`'s destructive-op confirm) is `createPortal`ed to `document.body` like `TreeDeleteConfirm`. The three header-picker click-away catchers in `GitControlPanel` are NOT scrims any more: their popovers stay inside the panel's isolated stacking context, so a body-level scrim would paint over them — they are one `useClickAway` capture-phase `mousedown` listener on the picker's zone, which also closes the picker on a click outside the widget (the clipped scrim never could).
 - The editor diff is `whitespace-pre` + horizontal scroll (long lines scroll), NOT wrapping — matching the chat card (a deliberate change from the old `<table>` `whitespace-pre-wrap break-all`).
 - **Getting the pre-edit baseline: ONE current read.** The canonical way for the file editor and chat card modify diff is a single `readFiles({ agentId, files:[uri] })` whose response carries `version.baseline.content` (the pre-edit snapshot, locked while `pending_review`) — parse it with `parseFilePrev` (`store/helpers.ts`). The pending baseline is **cumulative** (locked to pre-FIRST-edit); approval preserves the stored baseline, so ONE read gives the editor both sides of the diff. `src/routes/read.ts` used to DROP `read_version`/`line_start`/`line_end`/`include_ids` from the body, which made a `read_version:'baseline'` request over the route silently return CURRENT; it now forwards all four, so that request works — but it still answers with the baseline ALONE, and the diff needs both sides. Keep the single current read for those surfaces; Changes instead uses the bounded pending preview, whose receipt fences subsequent resolution.
-- The file-tree sidebar is a **fixed-pixel** column (mirrors the admin widget), not a percentage split: resizing the outer widget never reflows the tree. Its width is drag-resizable via a custom pointer-capture handle and persisted in the store / `localStorage` (`sidebarWidth`, min `FILESYSTEM_SIDEBAR_MIN_WIDTH = 120`px). The drag upper bound is the live container width, so the tree can fully cover the editor (tree + chat only). The `sidebarOpen` toggle collapses the column to width `0`.
+- The file-tree sidebar is a **fixed-pixel** column (mirrors the admin widget), not a percentage split: resizing the outer widget never reflows the tree until the widget edge reaches it — then the rendered width is capped at the container (`max-width`, CSS only) and grows back to the stored width on widening, and a drag starts from the rendered width; the editor column clips (`overflow-hidden`), so at zero width its empty state and line/char metrics never paint over the tree. Its width is drag-resizable via a custom pointer-capture handle and persisted in the store / `localStorage` (`sidebarWidth`, min `FILESYSTEM_SIDEBAR_MIN_WIDTH = 120`px). The drag upper bound is the live container width, so the tree can fully cover the editor (tree + chat only). The `sidebarOpen` toggle collapses the column to width `0`.
 - `FilesystemWidget` triggers `loadList()` when the agent, project or user id changes (the user comes from `port.useUserId()` through the install entry and is part of the context key); the in-flight dedupe in the list slice prevents thrash during rapid switches.
 
 ## Tests