​

Document 1: Spaces Dashboard Design — Complete Feature Breakdown

​

For Junior Developers New to the aiConnected OS Project

​

What This Document Covers

​

Context: Where Spaces Fits in the Platform

1. aiConnected OS — the entire platform
2. Instances — individual project/workspace containers (like “projects” in ChatGPT or Claude)
3. Instance Dashboard — the home screen when you open an Instance
4. Spaces — a tab/section within the Instance Dashboard that unifies all non-chat artifacts

​

FEATURE 1: Spaces Home View (The “Control Room”)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Scope Selector — a dropdown or toggle with two options:
  • This Instance (default) — shows content from the current Instance only
  • All Instances — shows content aggregated across every Instance the user has (this is a future/power-user feature)
• Global Search Bar — searches across all content types within the current scope (tasks, docs, chats, files, etc.)
• Filter Bar — three filter dimensions:
  • Type: Tasks, Docs, Whiteboard, Chats, Files, Snippets, Folders, Links, Exports
  • Time: Today, This week, This month, Custom date range
  • Source: All, AI-created, User-created, Imported

• A stat summary (e.g., “12 Open | 3 Due Today” for Tasks)
• Quick-action buttons (e.g., View all, New Task)
• A preview strip showing the most recent 2-3 items

• Tasks — “12 Open | 3 Due Today” — Buttons: View all, New Task — Shows next 3 tasks
• Whiteboard — “1 Whiteboard | 42 pinned items” — Buttons: Open whiteboard, View pinned items list — Shows recently pinned strip
• Live Documents — “6 Documents | Last updated 2 hours ago” — Buttons: View all, New document — Recently updated docs list
• Chats — “32 Chats | 5 linked to this instance” — Buttons: View chats, Start chat from task — Last 3 active chats
• Folders — “4 Folders | 21 items inside” — Buttons: View all folders, New folder
• Files — “63 Files | 18 Images, 11 PDFs, 4 Audio, 30 Other” — Buttons: Browse files — Recent uploads
• Code Snippets — “9 Snippets” — Buttons: View all, New snippet
• Links — “15 Links” — Buttons: View all, Add link
• Exports — “7 Exports | 3 Presentations, 4 Docs” — Buttons: View all, Create export

​

Technical Notes for Developers

• Each overview card needs a real-time or near-real-time count query against the Instance’s content store
• The scope selector changes the data source for every card simultaneously
• Search should be full-text across all content types with type-faceted results
• Cards should be rendered as reusable components since the same data model drives both the overview card and the full dedicated view

​

FEATURE 2: Tabbed Sub-Navigation

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Horizontal tab bar, scrollable if tabs overflow the viewport width on smaller screens
• Clicking a tab replaces the main content panel (not a page navigation — this is a client-side view switch)
• The currently active tab should be visually highlighted
• Each tab view is its own component/page with dedicated layout, filters, and actions
• URL routing should reflect the active tab (e.g., /instance/:id/spaces/tasks) for deep-linking and browser history support

​

FEATURE 3: Tasks Space

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Task name (text)
• Source — which chat, message, or whiteboard item created it. Clicking opens the original source.
• Status — Open, In Progress, Done (start with just Open / Done for v1)
• Due date — optional date picker
• Tags — free-text tags (e.g., “PRD”, “UI”, “Sales”)
• Actions column

• Status: Open / In Progress / Done
• Timing: Due Today / This Week / Overdue
• Origin: Created from chat / Created manually / Created by AI

• Open in chat — jumps to the original message that spawned this task
• Start new chat from task — creates a new conversation pre-seeded with the task description
• Convert to live document — promotes the task into a Live Document
• Create reminder / external notification — sends to email, Slack, etc. (future integration)
• Pin to whiteboard — adds the task as a node on the Instance’s Whiteboard

Task {
  id: string
  instance_id: string
  title: string
  status: "todo" | "in_progress" | "done"
  source_type: "message" | "manual" | "whiteboard" | "reference"
  source_chat_id?: string
  source_message_id?: string
  due_date?: Date
  tags: string[]
  created_at: Date
  updated_at: Date
}

• Tasks are scoped per Instance. There is no global task list in v1, but later a “All Tasks” rollup across Instances may be added.
• The Tasks feature can be toggled ON/OFF per Instance Type in settings (not every Instance needs tasks).
• Creating a task from a chat message pre-fills the title from the message content.
• Status changes should be single-click (checkbox or status pill toggle).

​

FEATURE 4: Whiteboard Space

​

What It Is

​

What It Does

• A primary Open Whiteboard button to launch the full canvas
• A list/table of all pinned items currently on the Whiteboard, with: Type (message, image, export, link, note), Source chat, Short preview, When it was pinned

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Open Whiteboard button launches the full canvas view (separate component, defined in Doc 5)
• Pinned items table with filters by type
• Each row allows: Open in original chat, Unpin, Convert to Task, Convert to Live Document section, Convert to Export draft

​

FEATURE 5: Live Documents Space

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Document list with columns and status badges
• Click a document to open it in an editor panel (rich text editor)
• “Linked chats” shows which conversations contributed content (clickable links back to source chats)
• “Add section from chat” lets users push content from any chat message into a specific section of the doc
• “Create export” generates a downloadable PDF, presentation, or other format from the Live Document
• Status workflow: Draft → In Review → Final

​

FEATURE 6: Chats Space

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Chat list with metadata columns
• “Relationships” panel per chat showing: Parent/child linked conversations, Referenced conversations (context pull-ins)
• Actions: Open chat, Add to folder, Mark as “primary” for a topic
• Links to artifacts that were created from each chat (tasks, docs, whiteboard pins)

​

FEATURE 7: Folders Space

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Folder list at the top level
• Inside each folder: a mini-Spaces view with tabs Summary | Chats | Tasks | Docs | Files
• A folder is essentially a “sub-space” — same UI patterns, narrower scope
• Folders are optional — users don’t have to use them

​

FEATURE 8: Files Space

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Grid view (thumbnails) and list view toggle
• Filters by type, source, and linked items
• Actions per file: Open viewer, Attach to live doc or export, Pin to whiteboard, Insert into chat, Add to folder
• Files should be automatically indexed when created (in chat, by AI, or by upload)

​

FEATURE 9: Code Snippets Space

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Snippet list with language syntax highlighting in previews
• Actions: Copy to clipboard, Insert into chat, Insert into live doc, Attach to folder
• Snippets can be created from chat (contextual “Save as snippet” action on code blocks) or directly within Snippets Space

​

FEATURE 10: Links Space

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• Link list with type badges
• Actions: Open link, Add to folder, Convert to task (“Follow up on this resource”)
• Links can be saved from chat messages (contextual “Save link” action) or created directly

​

FEATURE 11: Exports Space

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Export list with source traceability
• Actions: Download, Regenerate (if source material changed), Share link, Attach to email (future integration), Add to folder
• Regeneration should re-run the compilation from the current state of the source document/whiteboard

​

FEATURE 12: Content Flow Into Spaces (Automatic Collection)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Save as task → appears in Tasks Space
• Pin to whiteboard → appears in Whiteboard Space
• Add to live document → appears in Live Docs Space
• Save snippet → appears in Snippets Space
• Save link → appears in Links Space
• Attach file to... → appears in Files Space

• Export created from a doc → appears in Exports Space
• File uploaded in chat → appears in Files Space
• AI generates an image → appears in Files Space

• Users can create tasks, docs, folders, snippets, and links directly from within Spaces, without going back to a chat.

​

FEATURE 13: Dashboard ↔ Spaces Relationship

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• Instance View has tabs like: Chat, Spaces, Settings
• Spaces inside each Instance is scoped by default to that Instance
• The scope selector in Spaces allows switching to “All Instances” for a cross-Instance aggregate view
• The global Dashboard (above Instance level) may show a Spaces summary widget with stats across all Instances

​

Example User Flow (End-to-End)

1. User is brainstorming in a chat and writes: “We should create an onboarding flow for developers submitting engines.”
2. User clicks Save as Task on that message.
3. The task appears under Spaces → Tasks for the Instance.
4. Next day, user opens Spaces → Tasks, sees the task, clicks Start chat from task.
5. A new chat opens, pre-seeded with the task description.
6. User and AI discuss the onboarding flow. User selects key messages and clicks Add to Live Document.
7. A Live Document section is updated with the new decisions.
8. In Spaces, user can now see:
   • One task (status: In Progress)
   • One Live Document with updated sections
   • Two chats linked together
   • All living in one organized place

​

Key Implementation Principles

1. Spaces is not a separate app — it’s a view within the Instance Dashboard
2. Everything is scoped to the Instance by default — global views come later
3. Content flows in automatically from chats — users don’t manually “import”
4. Every item traces back to its source — tasks know which message created them, files know which chat generated them
5. Spaces is both read and write — users can browse existing content AND create new content directly
6. The feature set is toggleable — not every Instance Type needs Tasks or Code Snippets; these can be turned on/off in Instance Settings
7. Start simple, add views later — v1 is list views with filters; Kanban boards, graph views, and advanced layouts come in later versions

​

Document 2: Task Feature Spec — Complete Feature Breakdown

​

For Junior Developers New to the aiConnected OS Project

​

What This Document Covers

​

Context: Why Tasks Exist

​

FEATURE 1: Core Task Object (Data Model)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

Task {
  id: string                    // Unique identifier
  instance_id: string           // Which Instance this task belongs to
  title: string                 // Short, human-readable description
  status: "todo" | "done"       // Start with just two states (add "in_progress" later)
  source_type: "message" | "manual" | "whiteboard" | "reference"
  source_reference: {
    conversation_id?: string    // Which chat it came from
    message_id?: string         // Which specific message
    whiteboard_item_id?: string // Which whiteboard node
  }
  created_at: DateTime
  completed_at?: DateTime       // When status changed to "done"
}

  notes?: string                // Longer description or context
  due_at?: DateTime             // Optional due date
  priority?: "low" | "normal" | "high"  // Optional priority level
  updated_at: DateTime

  reminder_at?: DateTime                    // When to trigger a reminder
  reminder_channels?: string[]              // ["in_app", "email", "slack"]
  email_recipients?: string[]               // Email addresses for email action
  slack_destination?: {                     // Slack workspace + channel/user
    workspace: string
    channel_or_user: string
  }
  automation_profile?: string               // Named preset like "default reminder"

​

Technical Notes

• The v1 data model should be title, status, source_reference, created_at at minimum. Everything else is optional and can be added incrementally.
• source_reference is critical — it’s what lets users jump back to the original message or whiteboard item that spawned the task. Never lose this link.
• Later, the agentic fields can be broken into separate tables (TaskReminders, TaskNotifications) for cleaner separation of concerns.

​

FEATURE 2: Creating Tasks from Chat Messages

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

1. User is in a chat conversation
2. User clicks ⋯ on a specific message
3. User selects “Add to Tasks” (or “Remind me about this later”)
4. Small inline modal appears with:
   • Task title — pre-filled with an AI-generated smart summary of the message (e.g., “Update X document based on this idea”). User can edit this.
   • Due date — optional date picker
   • Notes — optional text area for additional context
   • [Save] button
5. System stores the task with:
   • source_type = "message"
   • conversation_id and message_id from the current chat
   • instance_id from the current Instance
6. In the Tasks panel, the task shows a small “From message” badge. Clicking it jumps back to the exact message in the original chat.

• The “smart summary” for the title should be generated by the AI — take the message content and produce a concise action-oriented title. If AI is unavailable or too slow, fall back to truncating the first ~80 characters of the message.
• The modal should be lightweight (not a full-page form). Think: inline popover or small slide-in panel.
• After saving, show a brief confirmation toast: “Task saved” with a link to the Tasks panel.

​

FEATURE 3: Creating Tasks Manually

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Simple text input at the top of the Tasks panel with placeholder text: “Add a task…”
• Press Enter to create the task instantly
• Optional: a small “More” button next to the input that expands to show Notes, Due date, and Priority fields
• v1 can be just the one-line input. Advanced fields come later.
• Tasks created this way can optionally be linked to the current conversation generically (store the conversation_id but no specific message_id)

​

FEATURE 4: Creating Tasks from the Whiteboard

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Same modal as the message-based creation flow
• Title pre-filled from the whiteboard item’s text content
• source_type = "whiteboard", whiteboard_item_id stored
• In the Tasks panel, clicking the source badge opens the whiteboard and highlights the originating item

​

FEATURE 5: Tasks Panel (Viewing & Managing Tasks)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Panel title: “Tasks for this Instance”
• Segmented filter bar: All | To Do | Done
• List of task rows, each showing:
  • Checkbox (click to toggle todo ↔ done)
  • Title (click to open detail drawer)
  • Source badge: “From message” / “Manual” / “From whiteboard” (small icon + text)
  • Due date (if set)

• Full notes (if any)
• “Open source” button — jumps back to the original message or whiteboard item
• Edit title, notes, due date, priority
• Action buttons (Remind, Email, Start Chat, Notify — see agentic features below)

• Default: status (To Do first) then created_at (newest first)
• v2: drag-and-drop reorder

​

FEATURE 6: AI-Assisted Task Creation (“Sweep my chat”)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

1. User triggers the command (via chat input or a “Scan for tasks” button in the Tasks panel)
2. AI processes the recent conversation history for the current chat
3. AI returns a list of proposed tasks with suggested titles:
   • “Draft PRD section on instance dashboard”
   • “Update Cognigraph doc with learning sub-architecture”
   • “Create UI sketches for tasks pane”
4. Modal displays the proposed tasks with checkboxes (all checked by default)
5. User unchecks any they don’t want, optionally edits titles
6. User clicks “Create Tasks”
7. System batch-creates all selected tasks with source_type = "message" and references to the relevant messages

​

FEATURE 7: Set Reminder on a Task

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• When: date/time picker, or quick options (“In 1 hour”, “Tomorrow morning”, “Next Monday”)
• Channels: checkboxes for In-app, Email, Slack
• Save button

• In-app: notification badge in the app, plus a toast/banner when the user is active
• Email: system sends an email with subject “Task reminder – [Task Title]”, body includes task title, notes, Instance name, and a deep link back to the task
• Slack: system posts to the configured Slack channel/DM with task title, Instance name, notes, and a link

• Store reminder_at and reminder_channels on the task
• A scheduled job (cron, n8n workflow, or internal scheduler) checks for due reminders and dispatches them
• Events emitted: task.reminder.triggered → consumed by email service, Slack integration, in-app notification service

​

FEATURE 8: Start New Chat from Task

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

1. User clicks “Start Chat from Task” on any task
2. System creates a new chat in the current Instance
3. The chat’s initial context includes:
   • The task title and notes
   • The content of the source message/whiteboard item (if available)
   • A system message: “This conversation is about Task #[id]: [title]”
4. The task record is updated with a link to the new chat: active_chat_id
5. In the Tasks panel, the task shows “Active chat: [link]”
6. In the new chat, a header or system message shows “This conversation is about Task #123” with a link back to the task and the ability to toggle status or update notes directly
7. User can start working immediately: “Break this task into smaller steps,” “Draft the initial PRD outline,” etc.

​

FEATURE 9: Email from Task

​

What It Is

​

What It Does

• System composes an email with the task title, notes, Instance name, a link back to the task, and optionally an AI-generated summary of the source message/whiteboard content.
• One-click send.

• Modal with: Recipients (free-form email addresses + optional contact picker), CC/BCC fields
• Toggle: “Have AI draft the email for me”
  • If ON, AI reads the task context (title, notes, Instance info, source message) and drafts a professional email
  • Example output: “Hey [Name], I’m working on the aiConnected chat dashboard and I need your input on the task system design. Specifically, I want feedback on…”
• User can edit the draft before sending

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• “Email” action in the task’s action menu
• Sub-menu: “Email → Me” (quick send) or “Email → Someone Else” (opens modal)
• Backend sends email via configured email provider (SendGrid, Gmail API, etc.)
• Email contains a deep link back to the task in the app
• Log the email action on the task record for audit trail

​

FEATURE 10: Notify in External Apps (Slack)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• OAuth flow to connect Slack workspace
• Choose default channel or DM
• Store connection in user settings

1. User clicks “Notify → Slack” on a task
2. Modal shows: Destination (default channel, or pick another), Pre-filled message template:

New task: [Task Title]
Instance: [Instance Name]
[Optional notes]
[Link to view task]

3. Optional: “Write a more detailed message” toggle — AI generates a longer explanation using task context
4. User can edit the message
5. Click “Send”
6. System posts to Slack via Slack API

• Event emitted: task.slack.notified
• Handled by Slack integration service (or n8n workflow)
• Store notification log on the task

​

FEATURE 11: AI Task Agent (“What should I do next?”)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

1. User asks in chat or clicks a “Prioritize” button in Tasks panel
2. AI reads all open tasks for the current Instance
3. AI considers: due dates (overdue first), priority levels, time since creation, last activity
4. AI responds with a ranked recommendation:

For this instance, the top three tasks to focus on next are:
1. Finalize task action design (due today)
2. Outline whiteboard UX
3. Document folder rules for instances vs. conversations

Want me to start a focused chat from Task #1?

5. If user says yes, system triggers “Start Chat from Task” automatically

• “Set reminders for all tasks due this week”
• “Email me a summary of all open tasks for this Instance”
• “Post all high-priority tasks into Slack”

1. Identifies matching tasks
2. Batch-creates the requested actions (reminders, emails, Slack posts)
3. Confirms what it did: “Set a Slack reminder for 3 tasks, emailed you a summary of 7 open tasks”

​

FEATURE 12: Integration with Conversation Linking

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• Store conversation_id and message_id at creation time
• When displaying source links, also check if the source message appears in any ConversationLink records
• If links exist, show “Related conversations” in the task detail drawer
• v1: just store the IDs correctly so linkage can be exploited later. Don’t over-engineer the display.

​

FEATURE 13: Integration with Folders

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• In folder views, query task counts per Instance and display as badges
• Future: folder-level aggregation view that combines task lists from all child Instances
• Do NOT add a folder_id to the Task model — tasks belong to Instances, not folders

​

FEATURE 14: Instance Type Settings (Toggle Tasks On/Off)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

DashboardModules {
  whiteboard: boolean   // On/Off
  pins: boolean         // On/Off
  tasks: boolean        // On/Off
  folders: boolean      // On/Off
  references: boolean   // On/Off
}

TaskActions {
  reminders: boolean    // On/Off
  email: boolean        // On/Off
  slack_external: boolean // On/Off
  ai_task_agent: boolean  // On/Off
}

• “Deep Project / Build Instance”: Tasks ON, all actions ON
• “Casual Chat / Q&A Instance”: Tasks OFF (or Tasks ON but all actions OFF — just local notes)

• Each Instance’s Settings panel has a toggle: “Enable tasks for this instance” that overrides the Type default

​

FEATURE 15: Backend Event Architecture

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• task.created — a new task was created
• task.completed — a task was marked done
• task.reminder.created — a reminder was set
• task.reminder.triggered — a reminder fired (time elapsed)
• task.chat.started — a new chat was started from a task
• task.email.created — an email was sent from a task
• task.slack.notified — a Slack notification was sent

{
  "event": "task.reminder.triggered",
  "task_id": "abc123",
  "instance_id": "inst456",
  "user_id": "user789",
  "channels": ["in_app", "email"],
  "timestamp": "2026-02-12T09:00:00Z"
}

• In-app notification service → shows badge/toast
• Email service → sends email via provider
• Slack service → posts message via Slack API
• Automation layer (n8n) → can listen and trigger arbitrary workflows

​

Key Implementation Principles

1. Start minimal — v1 is title, status, source_reference, created_at. Ship that first.
2. Source traceability is sacred — every task must know where it came from (message, whiteboard item, or manual). Never lose this link.
3. Tasks are launchpads, not checkboxes — the power isn’t in checking things off, it’s in the actions you can take FROM a task (start chat, send email, notify Slack, set reminder).
4. Lightweight over heavyweight — start with To Do and Done only. Add In Progress, priority, subtasks, and drag-reorder ONLY when user feedback demands it.
5. Toggleable per Instance Type — Tasks should never appear in Instances where they’d be clutter.
6. Event-driven backend — every action emits an event. Never hardcode integration logic in the frontend.
7. AI enhances, doesn’t replace — AI can propose tasks, draft emails, and prioritize lists, but the user always confirms before anything happens.

​

Document 3: Live Document Feature Spec — Complete Feature Breakdown

​

For Junior Developers New to the aiConnected OS Project

​

What This Document Covers

​

Context: The Problem Live Documents Solve

• Edit the same document from different conversations
• Have the AI update a document while you’re chatting about something related
• Track which conversations contributed to which sections of a document
• Export a polished, branded document directly from the platform

​

Context: Where Live Documents Fit in the Platform

• Chat = chronological conversation (messy, exploratory, real-time thinking)
• Whiteboard = nonlinear, spatial canvas for brainstorming and clustering ideas (visual)
• Tasks = action items (“do this later”)
• Live Documents = linear, structured, formalized documentation (the “official” output)
• Folders = organizational structure for grouping chats/content

​

FEATURE 1: The Live Document Object (Core Definition)

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

Key Characteristics

• Instance-scoped, chat-agnostic — the document belongs to the Instance, any chat can access it
• Message → Document flow — you pull content from messages into the document (not the other way around). The document becomes its own editable artifact.
• AI-editable, human-readable — stored as structured markdown or a block model. The AI can target specific sections for editing.
• Versioned — every edit (human or AI) creates a new version. You can view history and revert.
• Multiple output types — same underlying object can be rendered as a document, presentation outline, or other formats

​

FEATURE 2: Data Model

​

What It Is

​

What It Does

​

How It Should Be Built

LiveDocument {
  id: string
  instance_id: string              // Which Instance this belongs to
  title: string                    // e.g., "Cognigraph PRD v1"
  type: "text_document" | "presentation_outline" | ...
  status: "draft" | "in_progress" | "review" | "final"
  created_by_user_id: string
  created_at: DateTime
  updated_at: DateTime
}

LiveDocumentContent {
  document_id: string
  content_markdown: string          // Full markdown blob
  version_number: integer
  updated_by: string                // User ID or "ai"
  updated_at: DateTime
}

LiveDocumentBlock {
  id: string
  document_id: string
  type: "paragraph" | "heading" | "list" | "quote" | "code" | "image" | "table"
  content: string                   // Markdown or structured text for this block
  origin: {                         // Where this block came from (optional)
    conversation_id?: string
    message_id?: string
  }
  order_index: integer              // Position in the document
}

DocumentMessageLink {
  document_id: string
  block_id?: string                 // If using block model
  conversation_id: string
  message_id: string
}

​

Technical Notes

• Start with Option A (single markdown blob) for v1. It’s simpler to implement and sufficient for initial launch.
• Plan the database schema so migrating to Option B (blocks) later doesn’t require a full rewrite. For example, even in Option A, you could store section headers as metadata.
• Version history is critical from day 1 — AI edits can sometimes produce bad output, and users must be able to revert.

​

FEATURE 3: Opening Live Documents from Chat

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• “Live Docs” icon/button in the chat top bar or right sidebar
• Clicking opens a panel (right side of the screen, like an artifact/canvas panel)

• If the Instance has multiple Live Documents: show a list view first with document titles, types, and last-updated timestamps. User clicks to open one.
• If the Instance has a “primary” document pinned: open it directly
• The panel opens alongside the chat — split view: chat on the left, document editor on the right
• User can toggle between split view and full-page document view

• The document panel is a separate component that can be rendered alongside any chat
• It shares the same Instance context, so the AI knows which document is open
• The panel should support resize/collapse gestures
• Auto-save the panel state (which document was open, scroll position) so reopening the panel returns to where the user left off

​

FEATURE 4: Adding Messages to a Live Document

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

1. User is in a chat conversation
2. User clicks ⋯ on any message
3. User selects “Add to Live Document…”
4. Small modal appears with:
   • Which document: dropdown of all Live Documents in this Instance (or “Create new”)
   • How to add:
     • Append to bottom — adds the raw message content at the end
     • New section titled: [___] — creates a new heading + content (title auto-detected or user-entered)
     • Summarize this message and add — AI condenses the message into a tighter summary before adding
     • Extract bullet points and add — AI pulls out key points as a bulleted list
   • [Add] button
5. System behavior:
   • Pulls the text (or AI-processed version) into the document
   • Creates a new block or appends to content_markdown
   • Creates a DocumentMessageLink record with conversation_id + message_id
   • Shows a toast: “Added to ‘Cognigraph PRD’ under ‘Feature C – Live Docs’”

• The “Summarize” and “Extract bullet points” options require an AI call — this should be fast (use a lightweight model or cached prompt)
• Always store the DocumentMessageLink even if the content is summarized — the user should be able to trace back to the original message
• If the user selects multiple messages (via multi-select in the chat), allow bulk-adding them to the document as a group

​

FEATURE 5: Editing the Document While Chatting (Dual-Stream Editing)

​

What It Is

​

What It Does

• “Update the Live Document: add a section called ‘Live Document – Editing Across Chats’ that summarizes what we just discussed.”
• “Rewrite the introduction to emphasize that live docs are cross-chat artifacts.”
• “Create a table in the doc comparing Whiteboard vs Live Document vs Tasks.”

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Standard rich-text/markdown editor (consider Tiptap, Lexical, or ProseMirror for the frontend)
• Support for: headings (H1-H4), bold, italic, bullet lists, numbered lists, code blocks, tables, images, links, callout boxes
• Auto-save on every change (debounced, e.g., save after 2 seconds of inactivity)
• Each save creates a new version entry

• When a Live Document panel is open, the current document content (or a relevant slice) is injected into the AI’s context for the current chat
• The AI interprets “the document” or “the live doc” as the currently open Live Document
• AI produces a patch (new content, replacement content, or structural change)
• System applies the patch to content_markdown or specific blocks
• A new version is saved automatically
• The document panel refreshes to show the change in real-time

• For the block-based model (Option B), AI edits can target specific blocks by ID or heading name
• For the simple model (Option A), AI rewrites the full markdown and the system diffs + saves
• AI edits MUST generate new versions — users must be able to undo bad AI rewrites
• Consider showing a brief diff or “AI edited these sections” indicator after an AI edit

​

FEATURE 6: Instance Dashboard Document Hub

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Table with sortable columns: Title, Type, Status, Last Edited, Linked Chats
• Actions per row: Open, Duplicate, Archive, Delete

• Opens a full-page editor (more space than the in-chat side panel)
• Document outline sidebar on the left (table of contents based on headings)
• Editor in the center
• “Linked Conversations” panel showing which chats contributed content
• Export options accessible from the top bar

• “New Live Document” button
• Choose: Title, Type (document, presentation outline, etc.), initial template (blank, PRD template, spec template, etc.)
• Document is immediately available in all chats within the Instance

​

FEATURE 7: Document Chat (Talking to the Document from the Dashboard)

​

What It Is

​

What It Does

• “Tighten up the wording in section 3.2.”
• “Add an executive summary at the top.”
• “Generate slide titles from each H2 and add a ‘Presentation Outline’ section at the bottom.”
• “Insert a risk table.”
• “Summarize key decisions in a table.”

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Small chat input bar at the bottom of the document editor (or collapsible chat panel on the side)
• All prompts automatically include the document content as context
• AI responses are applied as document edits (not shown as chat messages — though a brief “Edit applied” confirmation is appropriate)
• Each AI edit creates a new version
• The chat history here is ephemeral (or optionally saved as “Document Edit History”)

​

FEATURE 8: Export System

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

1. Google Docs
   • Use the Google Docs API to create a new document and push structured content (headings, lists, tables, images)
   • Optionally store the Google Doc URL back on the LiveDocument record for quick access
   • Requires OAuth connection to Google (user authenticates once)
2. PDF
   • Render the markdown/blocks to HTML, then convert to PDF (server-side rendering using Puppeteer, wkhtmltopdf, or similar)
   • Apply branding options (header logo, company name, footer text)
   • Apply style preset (Simple PRD, Formal Spec, etc.)
3. Presentation Format (PowerPoint / Google Slides)
   • Map each H1 or H2 heading to a slide
   • Use the first paragraph/bullets under each heading as slide body
   • AI can propose speaker notes for each slide
   • Export as .pptx or push to Google Slides via API
4. Markdown Download
   • Raw markdown file download for developers or users who want to import into other tools

​

FEATURE 9: Layout & Branding Options

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• Header logo: upload an image
• Company name: text field
• Footer text: customizable (e.g., “Confidential – Oxford Pierpont / aiConnected”)

• “Simple PRD” — clean, minimal formatting
• “Formal Spec” — more structured, section numbering
• “Presentation Outline” — slide-friendly formatting
• Custom presets can be created later

​

FEATURE 10: Rich Content Support

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• Tables — insertable via toolbar or AI command (“create a comparison table”)
• Images — embed from upload, from Files Space, or from AI-generated diagrams
• Code blocks — syntax-highlighted, language-selectable
• Callout boxes — styled blocks for Notes, Risks, Decisions, Warnings (visually distinct from body text)

​

FEATURE 11: Version History

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Every save (manual or AI) creates a new version entry in LiveDocumentContent
• “Show previous versions” button in the editor opens a version list
• Each version shows: version number, timestamp, author (user name or “AI”), diff summary
• “Preview” opens a read-only view of that version
• “Restore” replaces the current content with the selected version (and creates a new version entry for the restoration)
• Version storage can use full snapshots (simple) or diffs (storage-efficient but more complex)

​

FEATURE 12: Relationship to Whiteboard

​

What It Is

​

What It Does

​

Intended Purpose

​

Key Distinctions

• Whiteboard: nonlinear, spatial layout, great for brainstorming, clustering, concept mapping. Think Miro/Excalidraw.
• Live Document: linear narrative, organized spec/plan/write-up, ready to send to others as “official” docs. Think Google Docs.

​

Future Bridge Actions (not v1, but plan for them):

• From Whiteboard → “Generate Document from selected items” (AI reads selected nodes and produces a structured document)
• From Document → “Send this section to whiteboard as sticky notes” (breaks a section into visual nodes on the canvas)

​

FEATURE 13: Relationship to Tasks

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• Highlight text in the document → context menu shows “Create Task”
• Task stores: source_type = "document", document_id, block_id (if using block model)
• In the Tasks panel, clicking the source badge opens the document and scrolls to the relevant section

​

FEATURE 14: Conversation Referencing & Linking

​

What It Is

​

What It Does

• In a chat that has contributed content to a document: shows “This conversation is linked to Documents: [Cognigraph PRD]”
• In the document: shows “Linked Chats: [Chat A], [Chat B], [Chat C]” with clickable links

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• DocumentMessageLink table tracks all message→document contributions
• Query this table to produce:
  • Per-document: list of unique conversation_id values → “Linked Chats”
  • Per-conversation: list of unique document_id values → “Linked Documents”
• Display as clickable badges/links in both the chat UI and the document UI

​

FEATURE 15: Collaboration & Multi-Edit Handling

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• Auto-save every N seconds or on change (debounced)
• Version history on every save
• AI edits clearly marked in version history

• Soft-locking: “Bob is editing this document” banner
• Conflict resolution: last-write-wins with version history as the safety net
• Eventually: operational transforms (OT) or CRDTs for real-time collaborative editing (like Google Docs)

​

FEATURE 16: MVP vs Extended Scope

​

What It Is

​

MVP (Build First)

• Per-Instance Live Documents table/list
• Basic text/markdown editor (not block-based yet)
• In-chat: “Live Docs” panel to open a document alongside the chat
• In-chat: “Add to Live Document…” action on messages (append + optional summarize)
• AI editing: “Update the live document…” commands that append new sections or rewrite specific sections by heading name
• Export: Markdown download + PDF export
• Simple version history (view + restore)

​

Extended (Build Later)

• Block-based content model with precise AI editing per block
• Presentation export (PowerPoint / Google Slides)
• Google Docs sync (push to Docs, store URL back)
• Whiteboard ↔ Live Document bridges
• Task creation from highlighted document content
• Rich branding/layout options for exports
• Fine-grained permissions and multi-user collaborative editing
• Document templates (PRD template, Spec template, etc.)

​

Key Implementation Principles

1. Instance-scoped, chat-agnostic — Live Documents belong to the Instance. Any chat in the Instance can open and edit them. Never tie a document to a single chat.
2. Source traceability is non-negotiable — always store DocumentMessageLink records so every piece of content can be traced back to its origin conversation and message.
3. Version everything — every human and AI edit creates a version. This is the safety net for the entire feature.
4. Start with markdown, plan for blocks — v1 stores content as a single markdown blob. But design the schema and API so migrating to a block model later is straightforward.
5. The document is an AI context — when a Live Document is open, the AI should have its content (or relevant sections) in context. This is what enables natural-language document editing.
6. Export is the payoff — Live Documents only matter because they can be exported as real deliverables. If the export system is bad, the whole feature feels pointless. Invest in clean PDF and Google Docs export from day 1.
7. Two editing streams, one document — manual editing and AI editing coexist on the same document. Both create versions. Neither should block the other.

​

Document 4: Folder System Design — Complete Feature Breakdown

​

For Junior Developers New to the aiConnected OS Project

​

What This Document Covers

​

Context: The Problem Folders Solve

​

Context: Where Folders Fit in the Hierarchy

Platform
  └── Instance (e.g., "aiConnected")
        ├── Whiteboard (one per Instance, shared across all folders)
        ├── No Folder (root-level chats — the default)
        └── Folders
              ├── "User Interface & UX" (folder)
              │     ├── Chat: "Persona creation modal design"
              │     └── Chat: "Dashboard layout v2"
              ├── "Hiring & Teams" (folder)
              │     ├── Chat: "Sales team tier structure"
              │     └── Chat: "Onboarding flow for SDRs"
              └── "Marketing & Sales" (folder)
                    └── Chat: "GTM narrative v1"

​

FEATURE 1: What a Folder Actually Is

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

Folder {
  id: string
  instance_id: string          // FK to parent Instance
  name: string                 // e.g., "User Interface & UX"
  description?: string         // Optional, e.g., "All conversations related to chat UI, dashboard, and persona controls"
  icon?: string                // For visual scanning in the sidebar
  color?: string               // Color coding
  instructions?: string        // Folder-specific system prompt / behavioral rules
  default_persona_id?: string  // Default persona for new chats in this folder
  default_model?: string       // Default AI model for this folder
  default_tools?: string[]     // Default tool/integration set
  created_at: DateTime
  updated_at: DateTime
}

• ❌ No folder-level Whiteboard (the Whiteboard stays one per Instance, above everything)
• ❌ No separate memory space (folders share the Instance’s memory)

​

FEATURE 2: Folders Are Strictly Optional

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• Every chat has an optional folder_id field
• If folder_id = null → the chat lives at the “root” of the Instance (called “No Folder”)
• If folder_id = some_id → the chat lives inside that folder

1. Only chats, no folders — everything lives at root. The Instance feels like a simple chat list.
2. Only folders — every chat is organized into a folder. The Instance feels like a project with departments.
3. A mix — some chats in folders, some loose at root. The most common real-world usage.

​

FEATURE 3: Instruction & Context Inheritance (The Stacked Instructions Model)

​

What It Is

​

What It Does

1. Global system / platform rules (safety, core behavior) — always present
2. Instance-level instructions (e.g., “You are working on aiConnected, an AI automation marketplace…”)
3. Folder-level instructions (e.g., “In this folder, prioritize UX clarity and React/Tailwind patterns…”)
4. Chat-level instructions (e.g., “In this chat, we are only working on the persona dropdown behaviors”)
5. Message-level modifiers (e.g., “Right now, think like a skeptical investor”)

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

Context stack: Platform → Instance → Chat

Context stack: Platform → Instance → Folder → Chat

• Lower layers can extend or override higher layers on specific fields
• Example: Instance says “Talk in warm, professional tone.” Folder says “In this folder, be more technical and concise.” Result: technical + concise wins within that folder.
• If a lower layer doesn’t specify something, the higher layer’s value is inherited

• Accessible from chat settings or a debug/transparency view
• Shows which instructions are active at each layer
• Shows what’s being overridden (e.g., tone, priority, tools)
• Helps power users understand and debug AI behavior

1. Load instance.instructions
2. Load folder.instructions (if chat is in a folder)
3. Load chat.custom_instructions (if any)
4. Merge them in precedence order
5. Send merged context as the system prompt

​

FEATURE 4: Memory & Retrieval Across Folders

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

1. Prioritize: Chats + artifacts in the current folder first
2. Expand: If relevant info isn’t found locally, automatically widen search to all folders within the same Instance
3. Mark the origin: When citing past work, show where it came from:
   • “Found related spec in: aiConnected → Marketing → GTM Narrative v1”

• Index all chats/messages at the Instance level in the vector store / knowledge graph
• Use folder_id as a boosting factor when scoring relevance (not a filter)
• This means folder context is always preferred, but Instance-wide knowledge is never excluded

​

FEATURE 5: Sidebar UI & Navigation

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

aiConnected
  > Whiteboard
  > All Chats (combined view)
  > No Folder
      - Chat: "Brainstorm engine pricing"
      - Chat: "Random idea dump"
  > Folders
      - User Interface & UX
          - Chat: "Persona creation modal"
          - Chat: "Dashboard layout v2"
      - Hiring & Teams
          - Chat: "Sales team tier structure"
      - Marketing & Sales
          - Chat: "GTM narrative v1"
      - Cognigraph Architecture
          - Chat: "Memory model design"
  > Unsorted / Inbox

• “Move to folder…”
• “Link to other chat…”
• “Add to whiteboard”

• “Edit folder settings”
• “Duplicate folder settings to another folder”
• “Create chat with these folder defaults”

• From any chat, user can “Link existing chat…” → search any chat in the Instance → link it
• UI surfaces: “Linked: [Market Research – ICP] (Marketing folder)”
• User can click the link to jump to that chat and come back

​

FEATURE 6: Whiteboard Integration with Folders

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

origin_instance: string
origin_folder?: string    // null if from root-level chat
origin_chat: string

• By folder: “Show only items from User Interface & UX”
• By multiple folders: “Show items from UI and Cognigraph”
• All: “Show everything” (default)

​

FEATURE 7: Moving Chats In and Out of Folders

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

• “Move to folder…” → folder picker (searchable list + “No Folder” option + “Create new folder”)
• “Remove from folder (send to No Folder)”

• Moving INTO a folder: future turns inherit the folder’s instructions
• Moving OUT of a folder: future turns lose the folder’s instructions, revert to Instance-only
• Past messages are NOT affected (they were generated under the old instructions)

​

FEATURE 8: New Chat Creation Flow

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• If user is currently viewing a specific folder: new chat defaults to that folder
• If user is viewing “All Chats” or “No Folder”: new chat defaults to root
• A small dropdown or toggle lets the user choose a different location before creating:
  • “No Folder”
  • “User Interface & UX”
  • “Hiring & Teams”
  • etc.

​

FEATURE 9: Bulk Move — Multi-Select Chats & Files to Folders

​

What It Is

​

What It Does

​

Intended Purpose

​

Why Anyone Should Care

​

How It Should Be Built

1. User clicks “Select” / “Manage” button in the chat list or file list
2. Checkboxes appear on every row
3. User can: click individual checkboxes, Shift-click to select a range, “Select all” for current filtered view
4. A bulk action bar appears (sticky bottom bar): Selected count | Move | Delete | Cancel

1. User clicks “Move” in the bulk action bar
2. Modal opens: “Move items”
3. Step 1: Choose destination type:
   • “Existing folder” — shows searchable dropdown of folders + “No Folder (root)”
   • “New folder…” — expands to show: Folder name, Optional description, Optional advanced settings (default persona, default model)
4. Step 2: Confirm
   • “Move 12 chats” button
5. System moves all items atomically (all succeed or none succeed)

• Toast notification: “Moved 7 chats to ‘Cognigraph Architecture’” with a clickable link to that folder
• Folder sidebar updates with new count
• Optional “Undo” button in the toast

POST /instances/{id}/chats/bulk-move
  Body: { chat_ids: [...], target_folder_id: "..." | null }

POST /instances/{id}/files/bulk-move
  Body: { file_ids: [...], target_folder_id: "..." | null }

POST /instances/{id}/bulk-move-to-new-folder
  Body: { type: "chats" | "files", item_ids: [...], folder_name: "...", folder_settings: { ... } }

• Items from different folders can be selected and moved together — the move just reassigns all their folder_id values
• Moving chats does NOT remove their whiteboard items — whiteboard items keep their original origin_chat_id
• Moving chats from root to a folder, folder to root, or folder A to folder B all use the same flow

​

FEATURE 10: Search, Filtering, and Cross-Folder References

​

What It Is

​

What It Does

​

Intended Purpose

​

How It Should Be Built

• Default: searches all chats in the Instance regardless of folder
• Filter options: by entire Instance, by specific folder, by “No Folder” only

• One per Instance
• Items can come from folder chats or root chats
• Filter whiteboard items by origin folder or show everything

• Cross-folder linking is fully supported
• Example: link a root-level brainstorm chat to a formal spec in the UI folder
• UI shows: “Linked: [Initial brainstorm] (No Folder)” / “Linked: [UI State Machine Spec] (User Interface & UX)”
• Folder boundaries do NOT restrict linking

​

FEATURE 11: Data Model & Architecture

​

What It Is

​

How It Should Be Built

instances {
  id: string
  name: string
  instructions: string
  settings: JSON
}

folders {
  id: string
  instance_id: string (FK → instances)
  name: string
  description?: string
  instructions?: string
  settings: JSON (default model, default tools, etc.)
  icon?: string
  color?: string
  created_at: DateTime
  updated_at: DateTime
}

chats {
  id: string
  instance_id: string (FK → instances)
  folder_id?: string (FK → folders, nullable for "No Folder" / root)
  title: string
  custom_instructions?: string
  created_at: DateTime
  updated_at: DateTime
}

chat_links {
  id: string
  chat_id: string (FK → chats)
  linked_chat_id: string (FK → chats)
  relationship_type: "continued-from" | "related-to" | "branched-from"
}

function assembleContext(chat) {
  const context = [];
  
  // Layer 1: Platform rules (always)
  context.push(PLATFORM_RULES);
  
  // Layer 2: Instance instructions
  const instance = getInstance(chat.instance_id);
  context.push(instance.instructions);
  
  // Layer 3: Folder instructions (if in a folder)
  if (chat.folder_id) {
    const folder = getFolder(chat.folder_id);
    context.push(folder.instructions);
  }
  
  // Layer 4: Chat-level instructions
  if (chat.custom_instructions) {
    context.push(chat.custom_instructions);
  }
  
  // Merge with precedence (lower layers override higher on conflicts)
  return mergeInstructions(context);
}

function retrieveMemory(query, chat) {
  const results = searchInstanceMemory(chat.instance_id, query);
  
  // Boost results from same folder
  if (chat.folder_id) {
    results.forEach(result => {
      if (result.folder_id === chat.folder_id) {
        result.score *= 1.5; // Boost same-folder results
      }
    });
  }
  
  return results.sort((a, b) => b.score - a.score);
}

​

FEATURE 12: Real-World Usage Examples

​

What It Is

​

Example 1: “User Interface & UX” Folder

• “Prioritize UX clarity, React/Tailwind patterns, coherence of chat + dashboard.”
• “Avoid deep dives into sales comp models unless explicitly asked.”

​

Example 2: “Hiring & Teams” Folder

• “Prioritize role definitions, compensation design, and scaling sales teams.”
• “Don’t drift into UI details; keep it people/process focused.”

​

FEATURE 13: Design Principle (For the PRD)

​

What It Is

​

The Principle

• Chats MAY be assigned to a folder, but are not required to be.
• Chats with no folder assignment are treated as root-level “No Folder” chats.
• All chats in an instance share the same memory space, regardless of folder, with retrieval optionally biased toward the current folder but never restricted to it.
• Folder-level instructions apply only to chats inside that folder and never to root chats.
• Users can go full folders, no folders, or hybrid, and the cognition still behaves like one unified brain for the instance.

​

Key Implementation Principles

1. Folders are optional, never mandatory — a user who never creates a folder should have a perfectly clean experience with no folder UI clutter.
2. Memory is Instance-wide, not folder-scoped — folders bias retrieval but never wall off knowledge. The AI in the UI folder can still access marketing decisions.
3. Instruction inheritance is the power feature — Platform → Instance → Folder → Chat. Each layer extends or overrides the one above. This is what makes folders genuinely useful, not just visual grouping.
4. Moving is cheap and non-destructive — changing a chat’s folder_id changes its future instructions but preserves all content, memory, and whiteboard links.
5. Bulk move is essential for adoption — if moving items one-at-a-time is the only option, users won’t organize. Multi-select + move is a must-have for v1.
6. Atomic operations — “create folder + move items” is one operation. No partial states.
7. Cross-folder linking is unrestricted — folder boundaries never prevent linking, referencing, or searching across the Instance.

​

Document 6: Chat Filters & Linked Conversations

​

Junior Developer Breakdown

• Scroll collapse in long conversations
• Lost context when topics branch
• Disconnected conversation threads
• No way to find specific content types within a chat

​

FEATURE 1: Multi-Select Filter Bar

• All — mutually exclusive with other chips; shows everything
• Sent — user’s messages only
• Received — AI’s messages only
• Pinned — only pinned messages
• Links — messages containing URLs
• Media — messages with attachments (images, audio, video, files)
• Search — opens inline search field

• Sent/Received/Pinned/Links/Media are multi-select (AND logic)
• When any chip selected, “All” turns off
• Examples:
  • Sent + Pinned → only user’s pinned messages
  • Received + Links → only AI messages containing URLs
  • Pinned + Links + Media → messages that are pinned AND contain links AND have media

• Horizontally scrollable on mobile
• Chips should be visually distinct when active vs inactive
• “All” resets everything when clicked

​

FEATURE 2: Message Metadata for Filtering

type ChatMessage = {
  id: string;
  chatId: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  createdAt: string;
  isPinned: boolean;
  pinnedAt?: string | null;
  hasLinks: boolean;        // derived from URL scanning
  hasMedia: boolean;        // derived from attachments
  mediaTypes?: ('image' | 'audio' | 'video' | 'file')[];
};

• hasLinks can be computed by scanning content for URL patterns
• hasMedia derived from attachment metadata
• Can be computed on-the-fly or persisted for performance in long threads
• Enables fast filtering without scanning full message content each time

​

FEATURE 3: Search Integration

1. All messages → apply filter chips → apply search query
2. Case-insensitive substring match against message content
3. Optionally matches filenames and alt text

• Search acts as further narrowing on already-filtered set
• Can search within Pinned only, within Sent only, etc.
• Clearing search returns to filter-chip result
• Closing search clears query and returns to normal filtered view
• Search field appears inline when Search toggle clicked (not as modal)

​

FEATURE 4: Filter State Management

type ViewFilter = {
  sent: boolean;
  received: boolean;
  pinned: boolean;
  links: boolean;
  media: boolean;
  searchQuery: string;
  mode: 'all' | 'custom';
};

• “All” button sets mode='all' and all chip booleans to false
• Clicking any chip sets mode='custom' and “All” visual state turns off
• Failsafe: if all chips false and search empty in custom mode, revert to mode='all' to prevent empty view

1. Apply role filters (sent/received)
2. Apply metadata filters (pinned/links/media)
3. Apply search narrowing

• All filter state is client-side for instant response
• Filters are non-destructive views over same conversation data

​

FEATURE 5: Linked Conversations (Conversation Graph)

• “Move to new chat” (with selected messages)
• “Start new chat from selection”

type ConversationLink = {
  id: string;
  fromChatId: string;
  toChatId: string;
  originMessageIds: string[];
  createdAt: string;
  label?: string;
};

• Every chat = node in a graph
• Every branch = link (edge) between nodes
• Enables navigation between related conversations while maintaining clean topic separation
• Links are bidirectional — both chats know about the relationship

​

FEATURE 6: Branch Indicators and Navigation

• Selected messages that spawned new chat get subtle link indicator icon
• Tooltip: “Branched chat: [name]”
• Clicking navigates to the branched chat

• Banner at top: “Branched from ‘[original chat name]’ based on N messages”
• [View in original chat] button
• Clicking highlights origin messages in original chat

​

FEATURE 7: Linked Conversations Menu

• Parent chat (if branched from another)
• Child chats (if others branched from this one)
• Sibling chats (other branches from same parent)

• Chat name
• Branch date
• Origin message count

• Click any entry → navigate to that chat
• Supports conversation chains: Chat A → Chat B → Chat C
• From Chat C, user can see parent (B) and grandparent (A) as “related via chain”

​

FEATURE 8: Bulk Operations with Filters

1. User applies filters (e.g., Pinned + Received + Search="Cognigraph")
2. Clicks “Move visible messages to new chat”
3. System receives messageIds[] list (the visible filtered set)
4. Creates new chat or Workspace components
5. Establishes ConversationLink with those specific message IDs as origin context

​

API Endpoints

​

User Flows

​

Implementation Principles

1. Filters are non-destructive views over the same conversation data
2. All filter state is client-side for instant response
3. Message metadata (hasLinks, hasMedia) can be computed or cached depending on performance needs
4. Linked conversations create bidirectional relationships — both chats know about the link
5. ConversationLink stores specific message IDs that formed the branch for precise traceability
6. Filter bar should be horizontally scrollable on mobile
7. Search field appears inline when Search toggle clicked, not as modal
8. Filters enable powerful workflows: filter to specific content type → export/move/analyze that subset → maintain connection to original context through links

​

Document 7: Pin Message Feature & Instance Whiteboard

​

Junior Developer Breakdown

• Doc 5 covers the Whiteboard as a Dashboard tab (Board integration, compile panel)
• Doc 6 covers the filter system in detail (chips, state, search)
• This doc is the origin story for both, plus the Workspace concept

​

FEATURE 1: Pin Message Core Behavior

• Every message (user + AI) has a pin icon
• Desktop: pin icon visible in message header row (or on hover)
• Mobile: always visible, or appears on long-press → “Pin message” in actions sheet
• States: Unpinned (pin outline) → Pinned (solid pin)
• Click pin → pinned. Click again → unpinned. Saved immediately (no extra “Save” step)
• Pins are per conversation (scoped to the chat, not global)

type ChatMessage = {
  // ...existing fields
  isPinned: boolean;
  pinnedAt?: string | null;  // optional: for pin-time sorting
};

• pinnedAt enables sorting pinned messages by pin time vs message time — chronological by message time is usually better for narrative flow
• Pin toggle fires: PATCH /chats/:chatId/messages/:messageId { isPinned: true | false }
• Or: POST /chats/:chatId/messages/:messageId/pin { pinned: true | false }

​

FEATURE 2: Pinned Messages View (Toggle Mode)

const visibleMessages = viewMode === 'all'
  ? messages
  : messages.filter(m => m.isPinned);

• Regeneration: If a pinned AI message is regenerated, the pin stays on that message slot — new content replaces old, pin persists
• Mobile: Same toggle at top of chat. Long-press message → “Pin / Unpin message”

​

FEATURE 3: Export from Pinned/Filtered View

• Copy as Markdown
• Download .md
• Download .json

• Move visible messages to a new chat
• Move visible messages to another instance
• Move visible messages to Workspace/Whiteboard
• Share as public link or via mobile share menu

​

FEATURE 4: Instance Workspace (Component-Based Knowledge Surface)

• Every instance gets one Workspace
• The Workspace holds Components — discrete chunks of content (not chat messages)
• Components come from pinned messages, filtered exports, or direct creation

• Idea snippet: “Cognigraph needs a dedicated sub-architecture for learning”
• Structured spec: “Chat Filter Bar – Requirements + Toggles”
• Code block: Next.js API route or n8n JSON
• Document fragment: “Section 3: Instance Workspace Concept”
• Visual/link: Link to Figma, diagram, etc.

type WorkspaceComponent = {
  id: string;
  workspaceId: string;
  title: string;
  contentMarkdown: string;
  type: 'idea' | 'requirement' | 'decision' | 'task' | 'code' | 'snippet' | 'reference';
  section: string;              // grouping label
  tags: string[];               // e.g., ['memory-architecture', 'UX', 'v1']
  sourceChatId?: string | null;
  sourceMessageIds?: string[];
  relatedComponentIds?: string[];
  createdAt: string;
  updatedAt: string;
};

​

FEATURE 5: Chat-to-Workspace Content Flow

1. On any message, click “Add to Workspace”
2. Dialog opens with: suggested title (first line), type selector, target workspace
3. On save: creates Component, links back to source message via metadata

1. Apply filters (e.g., Pinned + Received + Search="Cognigraph")
2. Click “Move visible messages to Workspace”
3. For each visible message: create Component with auto-suggested title and type
   • User messages → Idea or Question
   • AI messages → Answer or Spec
4. Optionally group into a section: “Import from Chat — Dec 10 Brainstorm”

• Chat = chronological conversation (messy thinking)
• Instance Memory (Cognigraph) = automatic knowledge graph (behind the scenes)
• Workspace = user-curated, intentional surface of the most important pieces (source of truth)

​

FEATURE 6: AI Interactions with Workspace

• “Turn everything under ‘Architecture’ into a structured PRD section”
• “Compare these three Components and tell me the conflicts”
• “Generate TypeScript interfaces from these code-spec Components”
• “Write an executive summary of all Components tagged ‘v1’”

1. Engine receives text of selected Components (or all in a section)
2. Plus a prompt defining the task (summarize, convert, refactor, etc.)
3. Output becomes either a new Component or updates an existing one

​

FEATURE 7: Instance Whiteboard (Spatial Canvas)

• One whiteboard per instance (by default; can allow multiples later)
• Each item is a Node pointing back to source content
• Think of the board as a visual layer on top of all pinned/filtered content

type WhiteboardNode = {
  id: string;
  whiteboardId: string;
  type: 'message' | 'message-group' | 'image' | 'file' | 'link' | 'note' | 'code';
  label?: string;
  position: { x: number; y: number; width?: number; height?: number; rotation?: number };
  contentPreview?: string;
  source?: {
    chatId?: string;
    messageIds?: string[];
    fileId?: string;
    imageId?: string;
    url?: string;
  };
  meta?: {
    tags?: string[];
    color?: string;
  };
  createdAt: string;
  updatedAt: string;
};

type WhiteboardEdge = {
  id: string;
  whiteboardId: string;
  fromNodeId: string;
  toNodeId: string;
  relationType?: 'relates_to' | 'supports' | 'contradicts' | 'depends_on';
};

• Single pinned AI answer → 1 Node titled “Learning Sub-Architecture Idea”
• Batch of 25 filtered messages → 1 Node of type message-group with preview: “25 messages from Chat: ‘Cognigraph – Learning‘“

​

FEATURE 8: Chat-to-Whiteboard Content Flow

• On any message: “Add to Whiteboard”
• Creates Node with type=message, source=chatId + messageId
• Auto-placed near last added node
• Toast: “Added to Whiteboard”

• From filtered chat view: “Send visible messages to Whiteboard”
• Creates single Node of type message-group with all visible messageIds
• Label suggestion: “Cluster from – ”
• User can rename after

• AI-generated images, uploaded files, links/videos
• “Add to Whiteboard” on attachment bubble
• Each becomes a Node with type=image/file/link and appropriate preview

​

FEATURE 9: Spatial Canvas Editing

• Infinite scroll/pan/zoom
• Nodes can be dragged, resized, grouped

• Select — click and move nodes
• Rectangle/Frame — group container (like Figma frames)
• Connector/Arrow — draw relationships between nodes
• Sticky Note / Text Box — freeform annotation

• Draw a frame around related nodes → label it (e.g., “Learning Sub-Architecture”, “Chat Filter UX”)
• Use connectors between nodes to show relationships:
  • “This idea supports that spec”
  • “This cluster evolves into that PRD”
• Under the hood, each connector = { fromNodeId, toNodeId, relationType }
• Relation types optional in v1, can add (supports, contradicts, depends-on) later

​

FEATURE 10: AI-on-Board (Board Chat Panel)

• “Take everything in this frame and turn it into a PRD”
• “Summarize this cluster”
• “Generate a step-by-step workflow from these Nodes”
• “Compare this idea cluster to that spec cluster and tell me conflicts”

1. No selection: Use everything on the board (or everything visible)
2. Selection mode: If nodes are selected when user types, only those nodes provide context
3. Frame-specific: Right-click a frame → “Ask AI about this frame…” → next prompt scoped to that frame’s nodes

{
  "instanceId": "...",
  "whiteboardId": "...",
  "nodeIds": ["...", "..."],
  "prompt": "Turn all of this into a PRD."
}

1. Resolve nodeIds → full underlying content (messages, text, image descriptions, links)
2. Feed content + user prompt into model
3. Return result

• Appears in the Board Chat panel
• Optionally saved as a new AI Output Node on the canvas (e.g., “Draft PRD v1”)
• New node can then be connected, refined, or exported

​

Three-Layer Architecture Summary

​

API Endpoints

​

Database Tables

​

User Flow: End-to-End Example

1. User brainstorms across 5-10 chats about Cognigraph, memory architecture, chat filters
2. In each chat: pin key answers, filter to Pinned + Received, search “Cognigraph”
3. Use “Move visible messages → Workspace” (or “Send to Whiteboard”)
4. All pinned AI answers become Components/Nodes in the instance’s Workspace/Whiteboard
5. In Workspace: organize into sections (Concept Overview, Memory Layers, Learning Sub-Architecture)
6. In Whiteboard: arrange spatially, draw frames, connect related clusters
7. Ask AI (Workspace chat or Board chat): “Generate a v1 PRD for learning sub-architecture based on everything in this section/frame”
8. Output saved as new Component/Node: “Learning Sub-Architecture – PRD v1”
9. Instead of Cognigraph being scattered across 30 chats, the instance has a single canonical surface with all curated pieces

​

Implementation Principles

1. Pins are per-message metadata — simplest possible data extension
2. The Workspace is structured (list/board); the Whiteboard is spatial (canvas) — both serve the same purpose at different fidelity levels
3. Ship Workspace list view as v1, Board/Kanban as v1.5, spatial Whiteboard as v2
4. Components and Nodes always maintain source traceability (chatId, messageIds)
5. AI-on-Board requests are scoped by selection — context is explicitly defined by what nodes the user selects
6. The board is a visual layer on top of Cognigraph, not a replacement for it
7. Every node/component can link back to its original chat message for full context
8. Workspace/Whiteboard is per-instance — one canonical surface per project

​

Document 8: Cognition Console UI Design

​

Junior Developer Breakdown

• Doc 7 covers Workspace and Whiteboard (visual curation surfaces)
• Doc 9 covers Collaborative Personas (multi-persona interactions)
• Doc 15 covers Persona memory architecture in detail (identity, instruction, experience, skill layers)

​

FEATURE 1: Core Data Model — The Objects Users See

​

1a. Persona

type Persona = {
  id: string;
  name: string;                    // "Neuro Architect", "Legal Analyst"
  role: string;                    // What this Persona is for
  style: string;                   // Tone, detail level, assumptions
  linkedMemoryScope: string;       // Which Cognigraph slice it uses
  safetyProfile: string;           // Guardrails, forbidden topics
};

​

1b. Project

type Project = {
  id: string;
  name: string;
  description: string;             // Goal statement
  status: 'active' | 'paused' | 'archived';
  primaryPersonaId?: string;
  relatedPersonaIds: string[];
  pinnedMemoryIds: string[];       // Key long-term memories
  artifactIds: string[];           // Docs, specs, uploads
  createdAt: string;
  updatedAt: string;
};

​

1c. Session (replaces “chats”)

type Session = {
  id: string;
  projectId: string;
  personaId: string;
  title: string;                   // "Memory architecture brainstorm #1"
  contextConfig: object;           // Which memories/topics are attached
  createdAt: string;
  lastActiveAt: string;
};

​

1d. Message

type Message = {
  id: string;
  sessionId: string;
  author: 'user' | 'persona' | 'system';
  content: string;
  createdAt: string;
  tags: string[];                  // Auto-suggested topics
  linkedMemoryIds: string[];       // Which MemoryNodes this contributed to
  promoted: boolean;               // If selected & promoted to long-term memory
};

​

1e. MemoryNode (Cognigraph node)

type MemoryNode = {
  id: string;
  scope: 'global' | 'persona' | 'project' | 'session';
  layer: 'open' | 'closed';       // Open Thinking (ephemeral) vs Closed Thinking (committed)
  category: string;                // "Business", "Health", "aiConnected architecture"
  concept: string;                 // "Cognigraph memory model", "BrowserEngine PRD"
  topic: string;                   // "Open vs Closed Thinking Layers UI"
  type: 'fact' | 'preference' | 'rule' | 'plan' | 'story' | 'pattern' | 'question' | 'decision';
  content: string;                 // Distilled memory text
  sourceMessageIds: string[];
  originPersonaId?: string;
  importanceScore: number;         // How central this is
  stabilityScore: number;          // How "settled" vs "tentative"
  lastAccessedAt: string;
  createdAt: string;
};

​

1f. Artifact

type Artifact = {
  id: string;
  projectId: string;
  type: 'file' | 'url' | 'note' | 'spec' | 'dataset';
  title: string;
  description: string;
  link?: string;
  fileMetadata?: object;
  generatedByPersonaId?: string;
  createdAt: string;
};

​

FEATURE 2: Core Screens & Layout

1. Home / Persona Hub
2. Project Dashboard
3. Session View (chat + memory drawer)
4. Memory Explorer

• Left sidebar: Persona selector (avatar + name + status), Projects list, Global Memory link, Settings, Daily Memory Report link
• Main area: Contextual content (Projects list, Session, Memory Explorer, etc.)
• Right drawer (toggle): “Context & Memory” for current Session — active memory slice, pinned nodes, recently used nodes, quick edit/add

​

FEATURE 3: Project Dashboard

​

FEATURE 4: Session View (The Chat Experience)

• Persona avatar + name
• Project name
• Session title

• Tiny tags under messages: #Cognigraph, #MemoryModel, #UI
• Indicator if memory was created/updated: small icon “3 memories updated”
• On hover/click:
  • “View linked memories”
  • “Promote this to long-term memory” (if AI suggested a candidate)
  • “Remove from memory”

1. Active Context — memory nodes currently attached to this Session as chips/cards showing title, type, scope icon (global/persona/project). User can pin/unpin, temporarily disable a node for this Session.
2. Suggestions — memory nodes the engine thinks would be useful. “Add to context” button.
3. Scratchpad (Open Thinking Layer) — ephemeral notes for this Session only. AI may write transient reasoning here. User can click “Commit to closed memory” to solidify.

​

FEATURE 5: Memory Explorer (“The Brain” UI)

• Filters: Persona, Project, Scope (global/persona/project), Type (fact/rule/preference/etc.), Time window (created/last accessed)
• Views:
  • Tree view — Category → Concept → Topic → nodes
  • List view — sortable table
  • Graph view (later) — visual knowledge graph

• Content
• Type, scope, layer, scores (importance, stability)
• Source Sessions/Messages
• Links:
  • “Jump to source message”
  • “Edit & version history”
  • “Attach to current Session”
  • “Change scope” (promote from project → global)
  • “Mark outdated” (lowers stability, hides from default context)

​

FEATURE 6: Daily Memory Report

• “New long-term memories created today”
• “Updated memories”
• “Potential conflicts or contradictions”

• Approve / adjust / delete nodes
• Re-scope (“this belongs only in aiConnected, not global”)

​

FEATURE 7: Message-to-Memory Pipeline (UI Side)

1. User and Persona talk in a Session
2. Cognigraph (behind the scenes) extracts candidate memories, links to existing nodes or creates new ones
3. UI surfaces this two ways:
   • Inline: subtle indicator on messages (“2 new memories extracted”)
   • End-of-session summary: “Here’s what I learned / updated”
4. User has explicit control:
   • Accept / reject / edit new nodes
   • Or defer and handle via Daily Memory Report

​

FEATURE 8: Projects as True Context Bundles

• Default memory scopes
• Relevant categories (e.g., “Engineering: Cognition”, “Business: aiConnected”)
• Style preferences (short vs long, more code vs more explanation)

• Lead Persona for this domain
• Secondary assisting Personas

• Pinned MemoryNodes representing key assumptions/decisions
• The Project reads like a living spec

Starting Session with:
  • Persona: Neuro Architect
  • Project: Cognigraph Front-End
  • Context: 17 memory nodes (rules, decisions, architecture)
  • Artifacts: PRD v1, wireframe sketches, previous conversation summaries

​

FEATURE 9: Open Thinking Layer vs Closed Thinking Layer (UI Mapping)

1. User can always see which layer they are editing
2. Promotion: “Convert this scratchpad element to a permanent memory”
3. Demotion: “Move this memory back to scratch / mark as tentative”

• OTL: lighter color, “pencil” icon, ephemeral feel
• CTL: solid color, “book” icon, durable feel

​

FEATURE 10: MVP vs Full Vision

​

MVP Must-Haves

1. Personas — Persona picker + simple settings
2. Projects — Create/edit, attach Personas
3. Sessions — Conversation view, basic list under Project
4. Memory (CTL) — Auto-extracted memories as list, simple filters (type/time), edit/delete/pin
5. Context Drawer — Shows memory nodes in Session, toggle on/off
6. Daily Memory Report — Simple list of new/updated nodes grouped by Project

​

Later Enhancements

• Full Memory Explorer tree + graph view
• Tasks integrated with memory
• Cross-project similarity suggestions
• Timeline visualizations (“what the AI learned this week”)
• Story mode / narrative of Project history

​

Paradigm Shift Summary

​

Implementation Principles

1. The UI is a control panel over Cognigraph — every memory layer should be visible and editable
2. Messages are evidence; MemoryNodes are the distilled knowledge. Don’t confuse the two
3. Memory should feel deliberate, not spooky — always show what was learned, let users govern it
4. Projects are the organizational backbone, not chats. Sessions live inside Projects
5. The Context Drawer is the user’s real-time view into what the AI “knows” right now
6. Ship simple (list views, basic filters) first. Graph views and cross-project intelligence come later
7. Daily Memory Report is the key governance mechanism — don’t skip it in MVP
8. Scratchpad (OTL) and Memory Explorer (CTL) should be visually distinct so users always know what’s ephemeral vs permanent

​

Document 9: Collaborative Personas Planning

​

Junior Developer Breakdown

• Doc 8 covers Cognition Console (Persona/Project/Session model)
• Doc 14 covers Build Plan (Chat Kernel, multi-persona capabilities)
• Doc 15 covers Persona memory layers (identity, instruction, experience, skill)

​

FEATURE 1: Chat as Shared Context Container

• Text conversation
• Documents
• Images
• Live screen sharing
• Voice
• Tools, timelines, decisions

• A chat can start with one Persona or many
• Personas can be added/removed dynamically
• The conversation context is preserved regardless of who joins or leaves
• Each Persona remembers their participation independently

​

FEATURE 2: Three Collaboration Modes

​

Mode 1: Invite Mode (Drop-In Collaboration)

• “Let me bring the developer into this discussion”
• Later: “Thanks, you can step out”

​

Mode 2: Open Chat Mode (Commons / Lounge)

• Like a chaotic group messenger (Yahoo Messenger / Slack channel)
• Personas speak only when they pass a Contribution Threshold
• Ideal for brainstorming and exploratory thinking

​

Mode 3: Multi-Persona Start

• “I’m starting a thread with finance, ops, and legal”
• Same mechanism as invite mode — just all links created at chat start time

​

FEATURE 3: Participation Link (Core Data Structure)

type ParticipationLink = {
  id: string;
  conversationId: string;
  personaId: string;
  joinedAt: string;
  leftAt?: string | null;
  contextScope: 'full' | 'recent' | 'summary';  // how much of thread they see
  memoryPolicy: 'allowed' | 'restricted' | 'none'; // what they can store
  roleInThread: 'collaborator' | 'advisor' | 'implementer' | 'reviewer' | 'observer';
  summarySnapshotId?: string;  // system-generated catch-up
};