@jlongo78/agent-spaces 0.10.0-beta.2 → 0.10.0-beta.4

package/.next/standalone/docs/superpowers/specs/2026-03-16-cortex-lobes-design.md

@@ -1,263 +0,0 @@
-# Cortex Lobes: Knowledge Compartments and Sharing
-
-**Date:** 2026-03-16
-**Status:** Design approved, pending implementation plan
-**Scope:** Add knowledge compartmentalization ("lobes") to Cortex with workspace-level access control, privacy, exclusions, and cross-user sharing
-
-## Overview
-
-Every workspace in Spaces has a **lobe** — its compartment of learned knowledge within Cortex. By default, your workspaces can pull knowledge from each other's lobes. Workspaces can be marked private, excluded from specific other workspaces, or shared with other users. Other users' lobes are closed by default and require explicit sharing + acceptance.
-
-### Terminology
-
-- **Lobe** — a compartment of knowledge associated with a workspace, team, department, or organization. Named after the lobes of the cerebral cortex. Each lobe specializes in the knowledge accumulated from its context.
-- **Subscription** — when a workspace pulls knowledge from a lobe
-- **Sharing** — when a user makes their lobe available to other users
-
-## Access Rules
-
-### Same User (default behavior)
-
-| Scenario | Access |
-|----------|--------|
-| Workspace A queries Workspace B's lobe | **Allowed** (default) |
-| Workspace A queries a private workspace's lobe | **Denied** |
-| Workspace A has Workspace B excluded | **Denied** |
-| Workspace A queries personal lobe | **Allowed** (always) |
-| Workspace A queries team/dept/org lobes | **Allowed** (via entity graph inheritance) |
-
-**Default:** All your workspaces can see all your other workspaces' lobes. Open by default, restrict when needed.
-
-### Cross-User
-
-| Scenario | Access |
-|----------|--------|
-| User A queries User B's lobe | **Denied** (default) |
-| User B shares a lobe with User A, User A accepts | **Allowed** |
-| User B revokes sharing | **Denied** again |
-| Team lobe (shared by team membership) | **Allowed** for team members |
-| Org lobe (trickled-down decisions) | **Allowed** for org members |
-
-**Default:** Other users' workspace lobes are invisible. Team/dept/org lobes are accessible through the entity graph hierarchy (already implemented in the Boundary Engine).
-
-## Data Model
-
-### Workspace Lobe Configuration
-
-Each workspace gets a lobe configuration stored as JSON in the workspaces table:
-
-```typescript
-interface LobeConfig {
-  // Privacy
-  isPrivate: boolean;          // If true, no other workspace can pull from this lobe
-
-  // Exclusions — workspaces that CANNOT pull from this lobe
-  excludedFrom: number[];      // workspace IDs that are blocked
-
-  // Inclusions — additional lobes this workspace subscribes to
-  subscriptions: LobeSubscription[];
-
-  // Tags on this workspace's lobe (for tag-based subscription)
-  tags: string[];
-}
-
-interface LobeSubscription {
-  type: 'workspace' | 'user' | 'tag' | 'team' | 'department' | 'organization';
-  id: string;        // workspace ID, user entity ID, tag name, etc.
-  label: string;     // display name
-  accepted: boolean; // for cross-user: has the subscriber accepted?
-}
-```
-
-### Cross-User Sharing
-
-Sharing is a two-step handshake:
-
-1. **Owner shares:** User B marks their lobe as shared with User A (creates a share record)
-2. **Recipient accepts:** User A sees the shared lobe offer and accepts it (adds subscription)
-
-```typescript
-interface LobeShare {
-  id: string;
-  ownerUserId: string;          // who is sharing
-  ownerWorkspaceId: number;     // which workspace's lobe
-  ownerLobeName: string;        // display name
-  sharedWithUserId: string;     // who it's shared with
-  accepted: boolean;            // has recipient accepted?
-  created: string;
-}
-```
-
-Storage: `lobe_shares` table in the entity graph SQLite database.
-
-### Defaults
-
-New workspace lobe config:
-```json
-{
-  "isPrivate": false,
-  "excludedFrom": [],
-  "subscriptions": [],
-  "tags": []
-}
-```
-
-This means: open to all your workspaces, no exclusions, no extra subscriptions, no tags. The workspace automatically inherits from personal + team + dept + org lobes through the entity graph.
-
-## How It Integrates with Context Assembly
-
-### Current Flow (Pillar 3)
-
-The Context Assembly Engine's `computeSourceWeights()` currently searches three hardcoded layers: personal, workspace, team.
-
-### New Flow
-
-Replace the hardcoded layer list with a dynamic scope list built from the workspace's lobe configuration:
-
-```
-1. Start with workspace's own lobe (always included)
-2. Add personal lobe (always included)
-3. Add inherited lobes from entity graph (team → dept → org)
-4. Add explicit subscriptions from LobeConfig
-5. Remove any that are private or excluded
-6. Remove any cross-user lobes that aren't shared+accepted
-7. Pass remaining scopes to the Context Assembly Engine
-```
-
-The weight computation stays the same — graph proximity determines weight. Subscribed lobes that aren't in the natural graph path get a base weight of 0.4 (lower than inherited but still present).
-
-### Storage Mapping
-
-Each workspace's lobe corresponds to a LanceDB storage path:
-- Workspace 42's lobe → `workspace/42` (already exists)
-- Personal lobe → `personal` (already exists)
-- Team lobe → `team` (already exists)
-
-No new storage structures needed. Lobes are a **view layer** on top of existing knowledge storage, controlling which storage paths are searched.
-
-## API Changes
-
-### New Endpoints
-
-```
-GET    /api/cortex/lobes                     — list all accessible lobes for current user
-GET    /api/cortex/lobes/:workspaceId        — get lobe config for a workspace
-PUT    /api/cortex/lobes/:workspaceId        — update lobe config (privacy, exclusions, tags)
-POST   /api/cortex/lobes/:workspaceId/subscribe — add a subscription
-DELETE /api/cortex/lobes/:workspaceId/subscribe/:id — remove a subscription
-POST   /api/cortex/lobes/share               — share a lobe with another user
-POST   /api/cortex/lobes/share/:id/accept    — accept a shared lobe
-DELETE /api/cortex/lobes/share/:id            — revoke or decline a share
-GET    /api/cortex/lobes/shares              — list incoming/outgoing shares
-```
-
-### Modified Endpoints
-
-```
-GET /api/cortex/context — now accepts optional workspace_id to resolve lobe config
-```
-
-## UI
-
-### Workspace Settings → "Knowledge Lobes" Section
-
-Simple settings panel within existing workspace settings:
-
-**Status line:** "This workspace draws from 4 lobes" (count of active sources)
-
-**Privacy toggle:** "Private lobe — other workspaces can't access this knowledge"
-
-**Tags input:** chip-style tag input for labeling this workspace's lobe
-
-**Active sources list:** shows all lobes this workspace pulls from:
-- Own workspace (always, can't remove)
-- Personal (always, can't remove)
-- Team: Platform (inherited, can mute)
-- Org: Acme Corp (inherited, can mute)
-- Workspace: Auth Service (subscribed, can remove)
-- Tag: infrastructure (subscribed, can remove)
-- Shared: Bob's Security workspace (cross-user, can remove)
-
-**"Add source" button:** dropdown/search to subscribe to:
-- Another workspace (by name)
-- A tag
-- A team/department
-- A shared lobe from another user
-
-**Exclusions section** (collapsed by default): "Exclude specific workspaces from accessing this lobe" — multi-select of workspace names.
-
-### Shared Lobes Section (in main Cortex page or settings)
-
-**Incoming shares:** "Bob shared 'Security Workspace' with you" — Accept / Decline buttons
-**Outgoing shares:** "You shared 'Platform' with Alice" — Revoke button
-
-## Implementation Notes
-
-### Where Lobe Config Lives
-
-Option A: JSON column on workspaces table (`lobe_config TEXT DEFAULT '{}'`)
-Option B: Separate `workspace_lobe_config` table
-
-**Recommendation: Option A** — it's simpler, the config is small, and it's always loaded with the workspace. Add a migration to add the column.
-
-### Integration with Boundary Engine
-
-The lobe system sits ABOVE the boundary engine. Lobes determine which scopes are searched. The boundary engine then filters individual results by sensitivity/policy/creator-override within those scopes. They compose naturally:
-
-```
-Lobe Config → determines searchable scopes
-    ↓
-Context Assembly Engine → searches those scopes
-    ↓
-Boundary Engine → filters results by access control
-    ↓
-User sees results
-```
-
-### Cross-User Sharing Security
-
-When User A searches a lobe shared by User B:
-- The search runs against User B's workspace storage
-- The Boundary Engine still applies — confidential/restricted knowledge is filtered
-- The sensitivity auto-classifier already marks sensitive content appropriately
-- Audit trail logs cross-user access for compliance
-
-### Consulting Firm Scenario
-
-Setup for a consulting firm with clients Initech and Globex:
-
-1. Create workspaces: "Initech Project", "Globex Project", "Internal"
-2. Mark "Initech Project" with tag `initech`, mark private
-3. Mark "Globex Project" with tag `globex`, mark private
-4. "Internal" workspace: default (pulls from everything non-private)
-5. "Initech Project": remove "Globex Project" from accessible lobes (it's already excluded by privacy, belt + suspenders)
-6. Result: Initech workspace sees only its own knowledge + personal + team + org. Never sees Globex. Globex never sees Initech. Internal sees both (org-level patterns only, not private workspace knowledge).
-
-## File Structure
-
-```
-New files:
-├── src/lib/cortex/lobes/config.ts        — LobeConfig types and defaults
-├── src/lib/cortex/lobes/resolver.ts      — Resolve accessible lobes for a workspace
-├── src/lib/cortex/lobes/shares.ts        — Cross-user sharing logic
-├── src/lib/cortex/lobes/index.ts         — Barrel export
-├── src/app/api/cortex/lobes/route.ts     — List/get lobes
-├── src/app/api/cortex/lobes/[id]/route.ts — Update lobe config
-├── src/app/api/cortex/lobes/share/route.ts — Share management
-├── src/components/cortex/lobe-settings.tsx — UI component
-
-Modified files:
-├── src/lib/cortex/retrieval/context-engine.ts — Use lobe resolver for search scopes
-├── src/lib/db/queries.ts                      — Add lobe_config column to workspaces
-├── src/app/(desktop)/cortex/page.tsx          — Add Lobes tab or integrate into Settings
-```
-
-## Success Criteria
-
-- New workspaces see knowledge from all non-private sibling workspaces by default
-- Marking a workspace private immediately hides its knowledge from other workspaces
-- Excluding a workspace prevents bidirectional knowledge access
-- Cross-user sharing requires explicit share + accept handshake
-- Consulting scenario works: private client workspaces with no cross-contamination
-- Context Assembly Engine respects lobe config within <150ms (no performance regression)
-- All access decisions logged in audit trail

package/.next/standalone/docs/superpowers/specs/2026-03-16-cortex-v2-ui-design.md

@@ -1,240 +0,0 @@
-# Cortex v2 UI Components
-
-**Date:** 2026-03-16
-**Status:** Design approved, pending implementation plan
-**Scope:** Three UI additions for Cortex v2: entity graph visualization, enhanced knowledge cards, and context assembly dashboard
-
-## Overview
-
-Add a dedicated `/cortex` page to Spaces with four tabs (Graph, Knowledge, Context, Settings) plus enhancements to the existing right-side panel. The graph uses a canvas-based force layout for interactive exploration. Knowledge cards gain v2 field display (scope, sensitivity, evidence, origin). A context assembly tab lets users inspect how the retrieval engine works.
-
-### Design Principles
-
-- Follow existing dark theme and Tailwind patterns (no component library)
-- Minimal backend changes — 3 small modifications to existing endpoints (documented below)
-- One new npm dependency: `force-graph` for canvas rendering
-- Progressive enhancement — v1 data renders fine, v2 fields show when present
-- Custom `nodeCanvasObject` callback for entity-type shapes (force-graph renders circles by default; diamonds/rectangles need manual Canvas 2D drawing)
-
-## Component 1: Entity Graph Page
-
-### Route: `/app/(desktop)/cortex/page.tsx`
-
-Full-page layout with tab navigation. The "Cortex" icon (Brain from Lucide) is added to the sidebar below existing nav items, gated by `useTier().hasCortex`.
-
-### Tab Bar
-
-Four tabs across the top: **Graph** | **Knowledge** | **Context** | **Settings**
-
-Right-aligned stats in the tab bar: entity count, edge count, knowledge unit count (from `/api/cortex/status` + `/api/cortex/graph/entities`).
-
-### Graph Tab (default)
-
-Two-column layout:
-
-**Left: Force Graph Canvas (~70% width)**
-- Renders via `force-graph` npm package (canvas-based, handles 1000+ nodes)
-- Nodes colored and shaped by entity type:
-  - Person: circle, purple (#7c3aed)
-  - Team/Project: rounded rectangle, green (#10b981)
-  - System: diamond, amber (#f59e0b)
-  - Topic: small circle, cyan (#06b6d4)
-  - Department/Organization: larger rounded rect, blue (#3b82f1)
-- Edges rendered as lines, opacity based on weight
-- Interactions: drag nodes, zoom (scroll), pan (drag background), click to select
-- Overlay controls: zoom +/-, recenter button (bottom-left)
-- Legend overlay (top-right): shows shape/color mapping
-
-**Right: Detail Panel (~30% width, 260px min)**
-
-When no node selected: shows graph stats summary (entity counts by type, edge counts by relation).
-
-When a node is selected:
-- Entity header: icon + name + type + metadata (role, email, etc.)
-- Relationships section: list of edges from/to this entity, each showing relation type, target name, weight
-- Related Knowledge section: knowledge units linked to this entity (via entity_links or scope), shown as mini knowledge cards
-- Actions: "Add Edge" button (opens simple form), "Delete Entity" with confirmation
-
-### Data Fetching
-
-```
-GET /api/cortex/graph/entities → all nodes
-GET /api/cortex/graph/edges?from={id} → edges for selected node
-GET /api/cortex/graph/edges?to={id} → edges to selected node
-GET /api/cortex/search?q=&layer=personal&limit=5 → related knowledge (when node selected)
-GET /api/cortex/status → stats for tab bar
-```
-
-For the graph canvas, fetch ALL entities and ALL edges on mount (the graph is small — hundreds of nodes, not millions). Build the node/link arrays for force-graph from the API response.
-
-To get all edges, add a new lightweight endpoint or use a query parameter:
-```
-GET /api/cortex/graph/edges?all=true → all edges (for graph rendering)
-```
-
-## Component 2: Enhanced Knowledge Cards
-
-### Modify: `src/components/cortex/knowledge-card.tsx`
-
-The existing card shows: type badge, age, text, confidence bar, delete button.
-
-Add v2 fields (displayed only when present — backward compatible with v1 data):
-
-**Badge row (top):**
-- Existing type badge (decision, error_fix, etc.)
-- NEW: Sensitivity badge — color-coded:
-  - public: green (#10b981)
-  - internal: blue (#6366f1)
-  - restricted: amber (#f59e0b)
-  - confidential: red (#ef4444)
-- NEW: Scope badge — shows scope level (personal, team, department, organization) in muted purple
-
-**Attribution row (below text):**
-- Creator: `by {origin.creator_entity_id}` (strip "person-" prefix for display)
-- Source: `via {origin.source_type}` (conversation, git_commit, document, etc.)
-- Corroborations: `{corroborations} corroborations` in green if > 0
-- Contradictions: `{contradiction_refs.length} contested` in amber if > 0
-
-**Evidence bar (replaces confidence bar):**
-- If `evidence_score` is present, show it instead of `confidence`
-- Label: "0.72 evidence" instead of "85% confidence"
-- Same visual style (horizontal bar with fill)
-
-**Conflict indicator:**
-- If `contradiction_refs.length > 0`, show an amber warning icon and "Contested" text
-
-All new fields use optional chaining — if undefined, the row/badge simply doesn't render.
-
-## Component 3: Context Assembly Tab
-
-### Tab content within `/cortex` page
-
-A query input at the top. User types a question and clicks "Analyze" (or presses Enter). The tab calls `GET /api/cortex/context/?q={query}&limit=5` and displays the full pipeline breakdown.
-
-**Layout (top to bottom):**
-
-1. **Query input** — text field + Analyze button
-
-2. **Pipeline summary cards** (3 columns):
-   - Intent card: detected intent name (color-coded), confidence score
-   - Entities card: list of resolved entities with type badges
-   - Timing card: total ms (large number), breakdown (intent, entity, search)
-
-3. **Source weights** — horizontal bars showing each source's computed weight. Three bars: Personal, Team, Org. Bar fill proportional to weight, numeric label.
-
-4. **Results list** — ranked knowledge units with:
-   - Type badge
-   - Text snippet
-   - Relevance score (right-aligned)
-   - Source attribution
-
-5. **Conflict callout** (if any) — amber box showing conflicting pairs
-
-6. **Raw context preview** — collapsible section showing the `<cortex-context>` XML that would be injected into a Claude prompt
-
-### Data Fetching
-
-Single API call: `GET /api/cortex/context/?q={query}&limit=5`
-
-Response shape (requires backend modifications — see Backend Changes section):
-```typescript
-{
-  results: ScoredKnowledge[]
-  context: string          // pre-formatted XML
-  intent: { intent, confidence, biases }
-  entities: ResolvedEntity[]  // NEW: resolved entity references
-  conflicts: ConflictPair[]   // CHANGED: full pairs, not just count
-  sourceWeights: Array<{ layerKey: string; scopeLevel: string; weight: number }>  // NEW
-  timing: { intentMs, entityMs, searchMs, totalMs }
-}
-```
-
-## Component 4: Existing Panel Enhancement
-
-### Modify: `src/components/cortex/cortex-panel.tsx`
-
-Minimal changes to the existing right-side panel:
-
-1. Add "Open full view" link at the top → navigates to `/cortex` using Next.js router
-2. Replace `KnowledgeCard` import to use the enhanced version (same component, just has new optional fields)
-3. No layout changes — panel stays at 384px width with existing tabs
-
-## Component 5: Sidebar Navigation
-
-### Modify: `src/components/layout/sidebar.tsx`
-
-Add a "Cortex" nav item to the sidebar:
-- Icon: Brain from lucide-react (already used by CortexIndicator)
-- Position: after existing nav items (Terminal, Sessions, etc.)
-- Route: `/cortex`
-- Gated by `useTier().hasCortex`
-- Active state: indigo background (`bg-indigo-950 text-indigo-300`) consistent with other sidebar items
-
-The existing CortexIndicator (bottom of sidebar) remains — it shows the knowledge count badge and toggles the right panel.
-
-## Backend Changes (3 modifications)
-
-### 1. `EntityGraph.listAllEdges()` + edges route `all=true`
-
-Add a `listAllEdges(): Edge[]` method to `EntityGraph` class:
-```typescript
-listAllEdges(): Edge[] {
-  return (this.db.prepare('SELECT * FROM edges').all() as any[]).map(r => this.rowToEdge(r));
-}
-```
-
-Modify `src/app/api/cortex/graph/edges/route.ts` GET handler: if `all=true` query param is present, call `cortex.graph.listAllEdges()` and return all edges (bypassing the `from`/`to` requirement). No pagination needed — graph is small.
-
-### 2. Context API response expansion
-
-Modify `src/app/api/cortex/context/route.ts` to include three additional fields from `AssemblyResult`:
-- `entities: result.entities` — resolved entity references (currently dropped)
-- `conflicts: result.conflicts` — full `ConflictPair[]` array (currently flattened to count)
-- `sourceWeights` — requires exposing the computed source weights from `ContextEngine`
-
-To expose source weights, add a `sourceWeights` field to `AssemblyResult` in `context-engine.ts` and populate it from the `computeSourceWeights()` output (currently private, just return the array of `{ layerKey, scopeLevel, weight }` objects).
-
-### 3. Sidebar active state
-
-Use the existing indigo active state pattern (`bg-indigo-950 text-indigo-300`) for the Cortex nav item, consistent with other sidebar items. The purple (#7c3aed) is used inside the Cortex page for graph elements, not for sidebar navigation.
-
-### Settings tab
-
-The Settings tab renders the existing `<CortexSettings />` component (`src/components/cortex/cortex-settings.tsx`). No new settings content needed.
-
-## File Structure
-
-```
-New files:
-├── src/app/(desktop)/cortex/page.tsx          — Main /cortex page with tabs
-├── src/components/cortex/entity-graph.tsx      — Force graph canvas component
-├── src/components/cortex/entity-detail.tsx     — Right-side entity detail panel
-├── src/components/cortex/context-tab.tsx       — Context assembly tab content
-├── src/components/cortex/knowledge-tab.tsx     — Knowledge list tab (reuses enhanced cards)
-
-Modified files:
-├── src/components/cortex/knowledge-card.tsx    — Add v2 field display
-├── src/components/cortex/cortex-panel.tsx      — Add "Open full view" link
-├── src/components/layout/sidebar.tsx           — Add Cortex nav item
-├── src/app/api/cortex/graph/edges/route.ts    — Support all=true parameter + listAllEdges()
-├── src/lib/cortex/graph/entity-graph.ts       — Add listAllEdges() method
-├── src/app/api/cortex/context/route.ts        — Expand response (entities, conflicts, sourceWeights)
-├── src/lib/cortex/retrieval/context-engine.ts — Expose sourceWeights in AssemblyResult
-```
-
-## npm Dependency
-
-```
-force-graph: ^1.44.0
-```
-
-Canvas-based force-directed graph renderer. ~30KB gzipped. Wraps d3-force with a Canvas/WebGL renderer. Supports zoom, drag, click, hover out of the box. The `entity-graph.tsx` component (not the backend `entity-graph.ts`) is the dynamic import target: `const ForceGraph = dynamic(() => import('./entity-graph'), { ssr: false })`. The parent page handles the loading state.
-
-## Success Criteria
-
-- Entity graph renders all entities and edges with correct colors/shapes
-- Clicking a node shows its relationships and related knowledge
-- Knowledge cards show v2 fields when present, degrade gracefully for v1 data
-- Context tab shows full pipeline breakdown (intent, entities, weights, timing, results)
-- All within existing dark theme, no visual inconsistencies
-- Page loads in <1s, graph interaction is smooth (60fps)

package/.next/standalone/docs/superpowers/specs/2026-03-16-pane-ux-design.md

@@ -1,77 +0,0 @@
-# Pane UX Improvements: Agent Ordering + New Folder
-
-**Date:** 2026-03-16
-**Status:** Design approved, pending implementation plan
-**Scope:** Two small UX improvements: reorder agent types with Claude Code as default, add "New Folder" button to directory picker
-
-## Change 1: Agent Type Ordering
-
-### File: `src/lib/agents.ts`
-
-Reorder `AGENT_TYPES` record so Claude Code is first:
-
-1. claude (default)
-2. codex
-3. gemini
-4. aider
-5. shell
-6. custom
-
-### File: `src/app/(desktop)/terminal/page.tsx`
-
-Change the default agent type state from `'shell'` to `'claude'`:
-
-```typescript
-// From:
-const [newAgentType, setNewAgentType] = useState('shell');
-// To:
-const [newAgentType, setNewAgentType] = useState('claude');
-```
-
-## Change 2: New Folder in Directory Picker
-
-### File: `src/components/common/dev-directory-picker.tsx`
-
-Add a "New Folder" button in the browse view (between the "Select this folder" button and the subfolder list). When clicked:
-
-1. Shows an inline text input with a "Create" button
-2. On submit, calls `POST /api/folders` with `{ parent: data.current, name: inputValue }`
-3. On success, navigates into the new folder and selects it
-4. On error, shows inline error message
-
-The button only appears in browse mode (not in the dev directory list view).
-
-### File: `src/app/api/folders/route.ts`
-
-Add a POST handler alongside the existing GET:
-
-```typescript
-export async function POST(request: NextRequest) {
-  const user = getAuthUser(request);
-  const config = readConfig(user);
-  const body = await request.json();
-  const { parent, name } = body;
-
-  // Validate parent is within allowed dev directories
-  // Validate name (no path separators, no dots-only, reasonable length)
-  // Create directory with fs.mkdirSync
-  // Return { path: newPath }
-}
-```
-
-Validation rules:
-- `parent` must be within an allowed dev directory (same check as GET)
-- `name` must not contain path separators (`/`, `\`)
-- `name` must not be `.` or `..`
-- `name` must be 1-255 characters
-- Directory must not already exist (return 409)
-
-## Files Changed
-
-```
-Modified:
-├── src/lib/agents.ts                           — Reorder agents
-├── src/app/(desktop)/terminal/page.tsx          — Default to 'claude'
-├── src/components/common/dev-directory-picker.tsx — Add New Folder button + UI
-├── src/app/api/folders/route.ts                 — Add POST handler
-```