docs(client): restore boundary rationale

packages/client/ui-chat/src/client/conversation-nodes/event-projection.ts

@@ -34,6 +34,7 @@ function joined(names: string[]): string | null {
   return names.length > 0 ? names.join(', ') : null
 }
 
+/** Forms Chat presents structurally; unknown merge-extensible values remain opaque. */
 const KNOWN_FORMS: readonly KnownContextForm[] = [
   'instructions', 'catalog', 'snapshot', 'notice', 'relay', 'recall',
 ]
@@ -70,6 +71,8 @@ export function contextProvenance(source: unknown): ContextProvenanceView {
     case 'skill-invocation':
       return { role: 'inject', label: readString(record, 'name') ?? kind }
     default:
+      // MessageSourceMap is merge-extensible; keep an unknown producer
+      // visible by its durable kind.
       return { role: 'inject', label: kind }
   }
 }
@@ -138,6 +141,8 @@ export function displayFailure(failure: unknown): DisplayFailure {
   if (failure === null || typeof failure !== 'object') return { message: String(failure) }
   const record = failure as { code?: unknown; message?: unknown }
   const code = typeof record.code === 'string' ? record.code : undefined
+  // Provider AUTH messages may echo a masked or partially preserved credential.
+  // Keep the raw diagnostic in the Session log, but never retain it in UI state.
   if (code === 'AUTH') return { code, message: '' }
   return {
     ...(code === undefined ? {} : { code }),

packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.tsx

@@ -48,9 +48,18 @@ import css from './DirectoryBrowser.module.css'
 export interface DirectoryBrowserProps {
   /** Dialog visibility (owner-local; closed unmounts nothing but resets on reopen). */
   open: boolean
-  /** List one directory level (absent path = the Host home directory); the signal aborts a superseded scan on the wire. */
+  /**
+   * List one directory level (absent path = the Host home directory); the
+   * signal aborts a superseded scan on the wire. A rejection may carry
+   * `{ rpcError: { message: string } }`; the dialog prefers that Host
+   * business message over the ordinary Error text.
+   */
   listDirectory: (path?: string, signal?: AbortSignal) => Promise<DirectoryListing>
-  /** Create one child directory under an existing parent. */
+  /**
+   * Create one child directory under an existing parent. A rejection may
+   * carry `{ rpcError: { message: string } }`; the dialog prefers that Host
+   * business message over the ordinary Error text.
+   */
   createDirectory: (path: string, name: string) => Promise<string>
   /** The operator confirmed a directory (the selection, else the listed level). */
   onOpen: (path: string) => void

packages/client/ui-trajectory/src/client/trajectory-event-projection.ts

@@ -34,6 +34,7 @@ function joined(names: string[]): string | null {
   return names.length > 0 ? names.join(', ') : null
 }
 
+/** Forms Trajectory presents structurally; unknown merge-extensible values remain opaque. */
 const KNOWN_FORMS: readonly KnownContextForm[] = [
   'instructions', 'catalog', 'snapshot', 'notice', 'relay', 'recall',
 ]
@@ -70,6 +71,8 @@ export function contextProvenance(source: unknown): ContextProvenanceView {
     case 'skill-invocation':
       return { role: 'inject', label: readString(record, 'name') ?? kind }
     default:
+      // MessageSourceMap is merge-extensible; keep an unknown producer
+      // visible by its durable kind.
       return { role: 'inject', label: kind }
   }
 }
@@ -127,6 +130,8 @@ export function displayFailure(failure: unknown): DisplayFailure {
   if (failure === null || typeof failure !== 'object') return { message: String(failure) }
   const record = failure as { code?: unknown; message?: unknown }
   const code = typeof record.code === 'string' ? record.code : undefined
+  // Provider AUTH messages may echo a masked or partially preserved credential.
+  // Keep the raw diagnostic in the Session log, but never retain it in UI state.
   if (code === 'AUTH') return { code, message: '' }
   return {
     ...(code === undefined ? {} : { code }),

packages/util/workspace-path/src/index.ts

@@ -40,6 +40,7 @@ export function abbreviateHomePath(path: string, home?: string): string {
 
 /**
  * Read the final non-empty segment of a Workspace path for display.
+ * Workspace-label surfaces use this helper instead of deriving another basename.
  * @param path - Workspace directory path using POSIX or Windows separators.
  * @returns the final segment, or an empty string for a separator-only path.
  */