Add session documentation system (migration + MCP tools)

Phase 1-2 complete: Database schema + 9 MCP tools for session docs

Database Changes (migration 016):
- session_notes table (accomplishments, decisions, gotchas, etc.)
- session_plans table (plan mode plans with lifecycle tracking)
- project_documentation table (persistent project docs)
- sessions.documentation column (auto-generated markdown)
- HNSW indexes for semantic search across all doc types

MCP Tools Added (session-docs.ts):
1. session_note_add - Add structured notes to session
2. session_notes_list - List notes by type
3. session_plan_save - Save plan with embedding
4. session_plan_update_status - Track plan lifecycle
5. session_plan_list - List session plans
6. project_doc_upsert - Create/update project docs
7. project_doc_get - Get specific doc by type
8. project_doc_list - List all project docs
9. session_documentation_generate - Auto-generate markdown

Replaces: CLAUDE.md files, ~/.claude/plans/ directory

Next: Update session-start/end scripts for temp file management

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

migrations/016_session_documentation.sql

@@ -0,0 +1,211 @@
+-- Migration 016: Session Documentation System
+-- Purpose: Migrate from file-based documentation (CLAUDE.md, plan files) to database
+-- Dependencies: 010_sessions.sql (sessions table), 001_base_schema.sql (pgvector)
+
+-- ============================================================================
+-- SESSION NOTES: Structured notes within sessions
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS session_notes (
+    id SERIAL PRIMARY KEY,
+    session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    note_type TEXT NOT NULL CHECK (note_type IN (
+        'accomplishment',
+        'decision',
+        'gotcha',
+        'next_steps',
+        'context'
+    )),
+    content TEXT NOT NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    embedding vector(1024)  -- For semantic search of notes
+);
+
+-- Indexes for efficient querying
+CREATE INDEX idx_session_notes_session ON session_notes(session_id);
+CREATE INDEX idx_session_notes_type ON session_notes(note_type);
+CREATE INDEX idx_session_notes_created ON session_notes(created_at DESC);
+
+-- HNSW index for semantic similarity search
+CREATE INDEX idx_session_notes_embedding ON session_notes
+    USING hnsw (embedding vector_cosine_ops);
+
+COMMENT ON TABLE session_notes IS 'Structured notes within sessions (replaces ad-hoc note files)';
+COMMENT ON COLUMN session_notes.note_type IS 'Category of note: accomplishment, decision, gotcha, next_steps, context';
+COMMENT ON COLUMN session_notes.embedding IS 'Vector embedding for semantic search across notes';
+
+-- ============================================================================
+-- SESSION PLANS: Plan mode plans with lifecycle tracking
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS session_plans (
+    id SERIAL PRIMARY KEY,
+    session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+    plan_file_name TEXT,  -- Original filename (e.g., "transient-forging-reddy.md")
+    plan_content TEXT NOT NULL,
+    status TEXT DEFAULT 'draft' CHECK (status IN (
+        'draft',
+        'approved',
+        'executed',
+        'abandoned'
+    )),
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    approved_at TIMESTAMP WITH TIME ZONE,
+    completed_at TIMESTAMP WITH TIME ZONE,
+    embedding vector(1024)  -- For semantic search of plans
+);
+
+-- Indexes for efficient querying
+CREATE INDEX idx_session_plans_session ON session_plans(session_id);
+CREATE INDEX idx_session_plans_status ON session_plans(status);
+CREATE INDEX idx_session_plans_created ON session_plans(created_at DESC);
+
+-- HNSW index for semantic similarity search
+CREATE INDEX idx_session_plans_embedding ON session_plans
+    USING hnsw (embedding vector_cosine_ops);
+
+COMMENT ON TABLE session_plans IS 'Plan mode plans with lifecycle tracking (replaces ~/.claude/plans/)';
+COMMENT ON COLUMN session_plans.plan_file_name IS 'Original filename from plan mode (e.g., eloquent-yellow-cat.md)';
+COMMENT ON COLUMN session_plans.status IS 'Plan lifecycle: draft → approved → executed/abandoned';
+COMMENT ON COLUMN session_plans.embedding IS 'Vector embedding for semantic search across plans';
+
+-- ============================================================================
+-- PROJECT DOCUMENTATION: Persistent project-level docs
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS project_documentation (
+    id SERIAL PRIMARY KEY,
+    project TEXT NOT NULL REFERENCES projects(key) ON DELETE CASCADE,
+    doc_type TEXT NOT NULL CHECK (doc_type IN (
+        'overview',
+        'architecture',
+        'guidelines',
+        'history'
+    )),
+    title TEXT NOT NULL,
+    content TEXT NOT NULL,
+    last_updated_session TEXT REFERENCES sessions(id) ON DELETE SET NULL,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+    UNIQUE(project, doc_type)  -- One doc of each type per project
+);
+
+-- Indexes for efficient querying
+CREATE INDEX idx_project_docs_project ON project_documentation(project);
+CREATE INDEX idx_project_docs_type ON project_documentation(doc_type);
+CREATE INDEX idx_project_docs_updated ON project_documentation(updated_at DESC);
+
+COMMENT ON TABLE project_documentation IS 'Persistent project documentation (replaces CLAUDE.md sections)';
+COMMENT ON COLUMN project_documentation.doc_type IS 'Type of documentation: overview, architecture, guidelines, history';
+COMMENT ON COLUMN project_documentation.last_updated_session IS 'Session that last updated this documentation';
+
+-- ============================================================================
+-- SESSIONS TABLE ENHANCEMENTS
+-- ============================================================================
+
+-- Add documentation column for full markdown documentation
+ALTER TABLE sessions
+    ADD COLUMN IF NOT EXISTS documentation TEXT;
+
+-- Add migration flag to track CLAUDE.md migration status
+ALTER TABLE sessions
+    ADD COLUMN IF NOT EXISTS claude_md_migrated BOOLEAN DEFAULT FALSE;
+
+COMMENT ON COLUMN sessions.documentation IS 'Full markdown documentation for session (auto-generated at end)';
+COMMENT ON COLUMN sessions.claude_md_migrated IS 'Flag indicating this session migrated from CLAUDE.md file';
+
+-- ============================================================================
+-- HELPER VIEWS
+-- ============================================================================
+
+-- View: Session with note counts
+CREATE OR REPLACE VIEW session_documentation_summary AS
+SELECT
+    s.id,
+    s.project,
+    s.session_number,
+    s.started_at,
+    s.ended_at,
+    s.status,
+    s.summary,
+    COUNT(DISTINCT sn.id) as note_count,
+    COUNT(DISTINCT sp.id) as plan_count,
+    ARRAY_AGG(DISTINCT sn.note_type) FILTER (WHERE sn.note_type IS NOT NULL) as note_types,
+    MAX(sn.created_at) as last_note_at,
+    MAX(sp.created_at) as last_plan_at
+FROM sessions s
+LEFT JOIN session_notes sn ON s.id = sn.session_id
+LEFT JOIN session_plans sp ON s.id = sp.session_id
+GROUP BY s.id, s.project, s.session_number, s.started_at, s.ended_at, s.status, s.summary;
+
+COMMENT ON VIEW session_documentation_summary IS 'Sessions with note and plan counts for quick overview';
+
+-- View: Latest project documentation
+CREATE OR REPLACE VIEW latest_project_docs AS
+SELECT
+    pd.project,
+    pd.doc_type,
+    pd.title,
+    LEFT(pd.content, 200) as content_preview,
+    pd.updated_at,
+    s.session_number as last_updated_session_number,
+    s.started_at as last_updated_session_date
+FROM project_documentation pd
+LEFT JOIN sessions s ON pd.last_updated_session = s.id
+ORDER BY pd.project, pd.doc_type;
+
+COMMENT ON VIEW latest_project_docs IS 'Latest project documentation with session context';
+
+-- ============================================================================
+-- MAINTENANCE FUNCTIONS
+-- ============================================================================
+
+-- Function to clean up old session notes (optional retention policy)
+CREATE OR REPLACE FUNCTION cleanup_old_session_notes(retention_days INTEGER DEFAULT 180)
+RETURNS INTEGER AS $$
+DECLARE
+    deleted_count INTEGER;
+BEGIN
+    DELETE FROM session_notes
+    WHERE created_at < NOW() - (retention_days || ' days')::INTERVAL
+      AND session_id IN (
+          SELECT id FROM sessions WHERE status = 'completed'
+      );
+
+    GET DIAGNOSTICS deleted_count = ROW_COUNT;
+    RETURN deleted_count;
+END;
+$$ LANGUAGE plpgsql;
+
+COMMENT ON FUNCTION cleanup_old_session_notes IS 'Clean up notes from completed sessions older than retention period (default 180 days)';
+
+-- Function to generate session documentation stats
+CREATE OR REPLACE FUNCTION session_documentation_stats(p_project TEXT DEFAULT NULL)
+RETURNS TABLE(
+    total_sessions BIGINT,
+    sessions_with_notes BIGINT,
+    sessions_with_plans BIGINT,
+    total_notes BIGINT,
+    total_plans BIGINT,
+    avg_notes_per_session NUMERIC,
+    avg_plans_per_session NUMERIC
+) AS $$
+BEGIN
+    RETURN QUERY
+    SELECT
+        COUNT(DISTINCT s.id) as total_sessions,
+        COUNT(DISTINCT CASE WHEN sn.id IS NOT NULL THEN s.id END) as sessions_with_notes,
+        COUNT(DISTINCT CASE WHEN sp.id IS NOT NULL THEN s.id END) as sessions_with_plans,
+        COUNT(sn.id) as total_notes,
+        COUNT(sp.id) as total_plans,
+        ROUND(COUNT(sn.id)::NUMERIC / NULLIF(COUNT(DISTINCT s.id), 0), 2) as avg_notes_per_session,
+        ROUND(COUNT(sp.id)::NUMERIC / NULLIF(COUNT(DISTINCT s.id), 0), 2) as avg_plans_per_session
+    FROM sessions s
+    LEFT JOIN session_notes sn ON s.id = sn.session_id
+    LEFT JOIN session_plans sp ON s.id = sp.session_id
+    WHERE (p_project IS NULL OR s.project = p_project)
+      AND s.status = 'completed';
+END;
+$$ LANGUAGE plpgsql;
+
+COMMENT ON FUNCTION session_documentation_stats IS 'Generate statistics about session documentation usage';

regenerate_tool_docs_embeddings.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import pg from 'pg';
+const { Pool } = pg;
+
+// Database configuration
+const pool = new Pool({
+  host: 'infra.agiliton.internal',
+  port: 5432,
+  database: 'agiliton',
+  user: 'agiliton',
+  password: 'QtqiwCOAUpQNF6pjzOMAREzUny2bY8V1',
+  max: 5,
+});
+
+// LiteLLM API configuration
+const LLM_API_URL = 'https://api.agiliton.cloud/llm';
+const LLM_API_KEY = 'sk-litellm-master-key';
+
+async function getEmbedding(text) {
+  try {
+    const response = await fetch(`${LLM_API_URL}/v1/embeddings`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${LLM_API_KEY}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: 'mxbai-embed-large',
+        input: text,
+      }),
+    });
+
+    if (!response.ok) {
+      console.error('Embedding API error:', response.status, await response.text());
+      return null;
+    }
+
+    const data = await response.json();
+    return data.data?.[0]?.embedding || null;
+  } catch (error) {
+    console.error('Embedding generation failed:', error);
+    return null;
+  }
+}
+
+async function regenerateEmbeddings() {
+  try {
+    // Fetch all tool_docs
+    const result = await pool.query(
+      'SELECT id, tool_name, title, description, notes, tags FROM tool_docs WHERE embedding IS NULL'
+    );
+
+    console.log(`Found ${result.rows.length} tool_docs without embeddings`);
+
+    let successCount = 0;
+    let failCount = 0;
+
+    for (const row of result.rows) {
+      const embedText = `${row.title}. ${row.description}. ${row.tags?.join(' ') || ''}. ${row.notes || ''}`;
+
+      console.log(`Generating embedding for: ${row.tool_name}`);
+      const embedding = await getEmbedding(embedText);
+
+      if (embedding) {
+        const embeddingStr = `[${embedding.join(',')}]`;
+        await pool.query(
+          'UPDATE tool_docs SET embedding = $1 WHERE id = $2',
+          [embeddingStr, row.id]
+        );
+        successCount++;
+        console.log(`  ✓ ${row.tool_name} (${successCount}/${result.rows.length})`);
+      } else {
+        failCount++;
+        console.log(`  ✗ ${row.tool_name} - Failed to generate embedding`);
+      }
+
+      // Small delay to avoid rate limiting
+      await new Promise(resolve => setTimeout(resolve, 100));
+    }
+
+    console.log(`\n✅ Complete: ${successCount} successful, ${failCount} failed`);
+  } catch (error) {
+    console.error('Error:', error);
+  } finally {
+    await pool.end();
+  }
+}
+
+regenerateEmbeddings();

src/index.ts

@@ -49,6 +49,17 @@ import {
   buildRecord,
   sessionCommitLink,
 } from './tools/sessions.js';
+import {
+  sessionNoteAdd,
+  sessionNotesList,
+  sessionPlanSave,
+  sessionPlanUpdateStatus,
+  sessionPlanList,
+  projectDocUpsert,
+  projectDocGet,
+  projectDocList,
+  sessionDocumentationGenerate,
+} from './tools/session-docs.js';
 
 // Create MCP server
 const server = new Server(
@@ -476,6 +487,82 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         );
         break;
 
+      // Session Documentation
+      case 'session_note_add':
+        result = await sessionNoteAdd({
+          session_id: a.session_id,
+          note_type: a.note_type,
+          content: a.content,
+        });
+        break;
+      case 'session_notes_list':
+        result = JSON.stringify(
+          await sessionNotesList({
+            session_id: a.session_id,
+            note_type: a.note_type,
+          }),
+          null,
+          2
+        );
+        break;
+      case 'session_plan_save':
+        result = await sessionPlanSave({
+          session_id: a.session_id,
+          plan_content: a.plan_content,
+          plan_file_name: a.plan_file_name,
+          status: a.status,
+        });
+        break;
+      case 'session_plan_update_status':
+        result = await sessionPlanUpdateStatus({
+          plan_id: a.plan_id,
+          status: a.status,
+        });
+        break;
+      case 'session_plan_list':
+        result = JSON.stringify(
+          await sessionPlanList({
+            session_id: a.session_id,
+            status: a.status,
+          }),
+          null,
+          2
+        );
+        break;
+      case 'project_doc_upsert':
+        result = await projectDocUpsert({
+          project: a.project,
+          doc_type: a.doc_type,
+          title: a.title,
+          content: a.content,
+          session_id: a.session_id,
+        });
+        break;
+      case 'project_doc_get':
+        result = JSON.stringify(
+          await projectDocGet({
+            project: a.project,
+            doc_type: a.doc_type,
+          }),
+          null,
+          2
+        );
+        break;
+      case 'project_doc_list':
+        result = JSON.stringify(
+          await projectDocList({
+            project: a.project,
+          }),
+          null,
+          2
+        );
+        break;
+      case 'session_documentation_generate':
+        result = await sessionDocumentationGenerate({
+          session_id: a.session_id,
+        });
+        break;
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

src/tools/index.ts

@@ -825,4 +825,118 @@ export const toolDefinitions = [
       required: ['session_id', 'commit_sha', 'repo'],
     },
   },
+
+  // Session Documentation Tools
+  {
+    name: 'session_note_add',
+    description: 'Add a note to current session with auto-generated embedding',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+        note_type: { type: 'string', enum: ['accomplishment', 'decision', 'gotcha', 'next_steps', 'context'], description: 'Category of note' },
+        content: { type: 'string', description: 'Note content' },
+      },
+      required: ['session_id', 'note_type', 'content'],
+    },
+  },
+  {
+    name: 'session_notes_list',
+    description: 'List all notes for a session, optionally filtered by type',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+        note_type: { type: 'string', enum: ['accomplishment', 'decision', 'gotcha', 'next_steps', 'context'], description: 'Filter by note type (optional)' },
+      },
+      required: ['session_id'],
+    },
+  },
+  {
+    name: 'session_plan_save',
+    description: 'Save a plan to database with semantic embedding',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+        plan_content: { type: 'string', description: 'Plan content in markdown' },
+        plan_file_name: { type: 'string', description: 'Original filename (e.g., eloquent-yellow-cat.md) - optional' },
+        status: { type: 'string', enum: ['draft', 'approved', 'executed', 'abandoned'], description: 'Plan status (default: draft)' },
+      },
+      required: ['session_id', 'plan_content'],
+    },
+  },
+  {
+    name: 'session_plan_update_status',
+    description: 'Update plan status (draft → approved → executed)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        plan_id: { type: 'number', description: 'Plan ID to update' },
+        status: { type: 'string', enum: ['draft', 'approved', 'executed', 'abandoned'], description: 'New status' },
+      },
+      required: ['plan_id', 'status'],
+    },
+  },
+  {
+    name: 'session_plan_list',
+    description: 'List plans for a session',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+        status: { type: 'string', enum: ['draft', 'approved', 'executed', 'abandoned'], description: 'Filter by status (optional)' },
+      },
+      required: ['session_id'],
+    },
+  },
+  {
+    name: 'project_doc_upsert',
+    description: 'Create or update project documentation (replaces CLAUDE.md sections)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project key (e.g., CF, VPN)' },
+        doc_type: { type: 'string', enum: ['overview', 'architecture', 'guidelines', 'history'], description: 'Documentation type' },
+        title: { type: 'string', description: 'Document title' },
+        content: { type: 'string', description: 'Document content in markdown' },
+        session_id: { type: 'string', description: 'Session ID (optional)' },
+      },
+      required: ['project', 'doc_type', 'title', 'content'],
+    },
+  },
+  {
+    name: 'project_doc_get',
+    description: 'Get specific project documentation by type',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project key' },
+        doc_type: { type: 'string', enum: ['overview', 'architecture', 'guidelines', 'history'], description: 'Documentation type' },
+      },
+      required: ['project', 'doc_type'],
+    },
+  },
+  {
+    name: 'project_doc_list',
+    description: 'List all documentation for a project',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string', description: 'Project key' },
+      },
+      required: ['project'],
+    },
+  },
+  {
+    name: 'session_documentation_generate',
+    description: 'Auto-generate full markdown documentation for a session (tasks, commits, notes, plans)',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: { type: 'string', description: 'Session ID' },
+      },
+      required: ['session_id'],
+    },
+  },
 ];

src/tools/session-docs.ts

@@ -0,0 +1,424 @@
+// Session documentation operations - notes, plans, and project documentation
+// Replaces file-based CLAUDE.md and plan files with database storage
+
+import { query, queryOne, execute } from '../db.js';
+import { getEmbedding, formatEmbedding } from '../embeddings.js';
+
+// ============================================================================
+// SESSION NOTES
+// ============================================================================
+
+interface SessionNoteAddArgs {
+  session_id: string;
+  note_type: 'accomplishment' | 'decision' | 'gotcha' | 'next_steps' | 'context';
+  content: string;
+}
+
+interface SessionNotesListArgs {
+  session_id: string;
+  note_type?: 'accomplishment' | 'decision' | 'gotcha' | 'next_steps' | 'context';
+}
+
+interface SessionNote {
+  id: number;
+  session_id: string;
+  note_type: string;
+  content: string;
+  created_at: string;
+}
+
+/**
+ * Add a note to current session
+ * Auto-generates embedding for semantic search
+ */
+export async function sessionNoteAdd(args: SessionNoteAddArgs): Promise<string> {
+  const { session_id, note_type, content } = args;
+
+  // Generate embedding for semantic search
+  const embedding = await getEmbedding(content);
+  const embeddingFormatted = embedding ? formatEmbedding(embedding) : null;
+
+  await execute(
+    `INSERT INTO session_notes (session_id, note_type, content, embedding)
+     VALUES ($1, $2, $3, $4)`,
+    [session_id, note_type, content, embeddingFormatted]
+  );
+
+  return `Note added to session ${session_id} (type: ${note_type})`;
+}
+
+/**
+ * List all notes for a session, optionally filtered by type
+ */
+export async function sessionNotesList(args: SessionNotesListArgs): Promise<SessionNote[]> {
+  const { session_id, note_type } = args;
+
+  let sql = `
+    SELECT id, session_id, note_type, content, created_at
+    FROM session_notes
+    WHERE session_id = $1
+  `;
+
+  const params: unknown[] = [session_id];
+
+  if (note_type) {
+    sql += ` AND note_type = $2`;
+    params.push(note_type);
+  }
+
+  sql += ` ORDER BY created_at ASC`;
+
+  const notes = await query<SessionNote>(sql, params);
+  return notes;
+}
+
+// ============================================================================
+// SESSION PLANS
+// ============================================================================
+
+interface SessionPlanSaveArgs {
+  session_id: string;
+  plan_content: string;
+  plan_file_name?: string;
+  status?: 'draft' | 'approved' | 'executed' | 'abandoned';
+}
+
+interface SessionPlanUpdateStatusArgs {
+  plan_id: number;
+  status: 'draft' | 'approved' | 'executed' | 'abandoned';
+}
+
+interface SessionPlanListArgs {
+  session_id: string;
+  status?: 'draft' | 'approved' | 'executed' | 'abandoned';
+}
+
+interface SessionPlan {
+  id: number;
+  session_id: string;
+  plan_file_name: string | null;
+  plan_content: string;
+  status: string;
+  created_at: string;
+  approved_at: string | null;
+  completed_at: string | null;
+}
+
+/**
+ * Save a plan to database
+ * Extracts embedding from plan content for semantic search
+ */
+export async function sessionPlanSave(args: SessionPlanSaveArgs): Promise<string> {
+  const { session_id, plan_content, plan_file_name, status = 'draft' } = args;
+
+  // Generate embedding for semantic search
+  const embedding = await getEmbedding(plan_content);
+  const embeddingFormatted = embedding ? formatEmbedding(embedding) : null;
+
+  const result = await queryOne<{ id: number }>(
+    `INSERT INTO session_plans (session_id, plan_file_name, plan_content, status, embedding)
+     VALUES ($1, $2, $3, $4, $5)
+     RETURNING id`,
+    [session_id, plan_file_name || null, plan_content, status, embeddingFormatted]
+  );
+
+  const planId = result?.id || 0;
+
+  return `Plan saved to session ${session_id} (plan_id: ${planId}, status: ${status})`;
+}
+
+/**
+ * Update plan status (draft → approved → executed)
+ */
+export async function sessionPlanUpdateStatus(args: SessionPlanUpdateStatusArgs): Promise<string> {
+  const { plan_id, status } = args;
+
+  // Set timestamps based on status
+  let sql = 'UPDATE session_plans SET status = $1';
+  const params: unknown[] = [status, plan_id];
+
+  if (status === 'approved') {
+    sql += ', approved_at = NOW()';
+  } else if (status === 'executed' || status === 'abandoned') {
+    sql += ', completed_at = NOW()';
+  }
+
+  sql += ' WHERE id = $2';
+
+  await execute(sql, params);
+
+  return `Plan ${plan_id} status updated to: ${status}`;
+}
+
+/**
+ * List plans for a session
+ */
+export async function sessionPlanList(args: SessionPlanListArgs): Promise<SessionPlan[]> {
+  const { session_id, status } = args;
+
+  let sql = `
+    SELECT id, session_id, plan_file_name, plan_content, status,
+           created_at, approved_at, completed_at
+    FROM session_plans
+    WHERE session_id = $1
+  `;
+
+  const params: unknown[] = [session_id];
+
+  if (status) {
+    sql += ` AND status = $2`;
+    params.push(status);
+  }
+
+  sql += ` ORDER BY created_at DESC`;
+
+  const plans = await query<SessionPlan>(sql, params);
+  return plans;
+}
+
+// ============================================================================
+// PROJECT DOCUMENTATION
+// ============================================================================
+
+interface ProjectDocUpsertArgs {
+  project: string;
+  doc_type: 'overview' | 'architecture' | 'guidelines' | 'history';
+  title: string;
+  content: string;
+  session_id?: string;
+}
+
+interface ProjectDocGetArgs {
+  project: string;
+  doc_type: 'overview' | 'architecture' | 'guidelines' | 'history';
+}
+
+interface ProjectDocListArgs {
+  project: string;
+}
+
+interface ProjectDoc {
+  id: number;
+  project: string;
+  doc_type: string;
+  title: string;
+  content: string;
+  last_updated_session: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+/**
+ * Create or update project documentation
+ * Links to current session
+ */
+export async function projectDocUpsert(args: ProjectDocUpsertArgs): Promise<string> {
+  const { project, doc_type, title, content, session_id } = args;
+
+  await execute(
+    `INSERT INTO project_documentation (project, doc_type, title, content, last_updated_session, updated_at)
+     VALUES ($1, $2, $3, $4, $5, NOW())
+     ON CONFLICT (project, doc_type)
+     DO UPDATE SET
+       title = EXCLUDED.title,
+       content = EXCLUDED.content,
+       last_updated_session = EXCLUDED.last_updated_session,
+       updated_at = NOW()`,
+    [project, doc_type, title, content, session_id || null]
+  );
+
+  return `Project documentation updated: ${project} (${doc_type})`;
+}
+
+/**
+ * Get specific project documentation by type
+ */
+export async function projectDocGet(args: ProjectDocGetArgs): Promise<ProjectDoc | null> {
+  const { project, doc_type } = args;
+
+  const doc = await queryOne<ProjectDoc>(
+    `SELECT id, project, doc_type, title, content, last_updated_session, created_at, updated_at
+     FROM project_documentation
+     WHERE project = $1 AND doc_type = $2`,
+    [project, doc_type]
+  );
+
+  return doc;
+}
+
+/**
+ * List all documentation for a project
+ */
+export async function projectDocList(args: ProjectDocListArgs): Promise<ProjectDoc[]> {
+  const { project } = args;
+
+  const docs = await query<ProjectDoc>(
+    `SELECT id, project, doc_type, title, content, last_updated_session, created_at, updated_at
+     FROM project_documentation
+     WHERE project = $1
+     ORDER BY doc_type`,
+    [project]
+  );
+
+  return docs;
+}
+
+// ============================================================================
+// SESSION DOCUMENTATION GENERATION
+// ============================================================================
+
+interface SessionDocumentationGenerateArgs {
+  session_id: string;
+}
+
+/**
+ * Auto-generate full markdown documentation for a session
+ * Aggregates: tasks, commits, notes, decisions, plans
+ * Stores in sessions.documentation field
+ */
+export async function sessionDocumentationGenerate(args: SessionDocumentationGenerateArgs): Promise<string> {
+  const { session_id } = args;
+
+  // Fetch session details
+  const session = await queryOne<{
+    id: string;
+    project: string;
+    session_number: number;
+    started_at: string;
+    ended_at: string;
+    duration_minutes: number;
+    summary: string;
+    git_branch: string;
+  }>(
+    `SELECT id, project, session_number, started_at, ended_at, duration_minutes, summary, git_branch
+     FROM sessions
+     WHERE id = $1`,
+    [session_id]
+  );
+
+  if (!session) {
+    throw new Error(`Session not found: ${session_id}`);
+  }
+
+  // Fetch tasks worked on
+  const tasks = await query<{ task_id: string; title: string; status: string }>(
+    `SELECT DISTINCT t.id as task_id, t.title, t.status
+     FROM task_activity ta
+     JOIN tasks t ON ta.task_id = t.id
+     WHERE ta.session_id = $1
+     ORDER BY t.id`,
+    [session_id]
+  );
+
+  // Fetch commits made
+  const commits = await query<{ commit_sha: string; commit_message: string }>(
+    `SELECT commit_sha, commit_message
+     FROM session_commits
+     WHERE session_id = $1
+     ORDER BY committed_at`,
+    [session_id]
+  );
+
+  // Fetch notes
+  const notes = await query<{ note_type: string; content: string }>(
+    `SELECT note_type, content
+     FROM session_notes
+     WHERE session_id = $1
+     ORDER BY created_at`,
+    [session_id]
+  );
+
+  // Fetch plans
+  const plans = await query<{ plan_content: string; status: string }>(
+    `SELECT plan_content, status
+     FROM session_plans
+     WHERE session_id = $1
+     ORDER BY created_at DESC
+     LIMIT 1`,
+    [session_id]
+  );
+
+  // Build markdown documentation
+  let doc = `# Session ${session.session_number} - ${session.project}\n\n`;
+  doc += `**Date:** ${new Date(session.started_at).toLocaleDateString()}\n`;
+  doc += `**Duration:** ${session.duration_minutes || 0} minutes\n`;
+  doc += `**Status:** ${session.summary ? '✅ Complete' : '⚠️ In Progress'}\n`;
+  if (session.git_branch) {
+    doc += `**Branch:** ${session.git_branch}\n`;
+  }
+  doc += `\n---\n\n`;
+
+  // Summary
+  if (session.summary) {
+    doc += `## Summary\n\n${session.summary}\n\n`;
+  }
+
+  // Tasks
+  if (tasks.length > 0) {
+    doc += `## Tasks Completed\n\n`;
+    tasks.forEach(task => {
+      doc += `- **${task.task_id}**: ${task.title} (${task.status})\n`;
+    });
+    doc += `\n`;
+  }
+
+  // Commits
+  if (commits.length > 0) {
+    doc += `## Commits\n\n`;
+    commits.forEach(commit => {
+      const shortSha = commit.commit_sha.substring(0, 7);
+      doc += `- \`${shortSha}\` - ${commit.commit_message || 'No message'}\n`;
+    });
+    doc += `\n`;
+  }
+
+  // Notes by type
+  const notesByType: Record<string, string[]> = {};
+  notes.forEach(note => {
+    if (!notesByType[note.note_type]) {
+      notesByType[note.note_type] = [];
+    }
+    notesByType[note.note_type].push(note.content);
+  });
+
+  if (notesByType.accomplishment && notesByType.accomplishment.length > 0) {
+    doc += `## Accomplishments\n\n`;
+    notesByType.accomplishment.forEach(content => {
+      doc += `${content}\n\n`;
+    });
+  }
+
+  if (notesByType.decision && notesByType.decision.length > 0) {
+    doc += `## Key Decisions\n\n`;
+    notesByType.decision.forEach(content => {
+      doc += `${content}\n\n`;
+    });
+  }
+
+  if (notesByType.gotcha && notesByType.gotcha.length > 0) {
+    doc += `## Gotchas & Learnings\n\n`;
+    notesByType.gotcha.forEach(content => {
+      doc += `${content}\n\n`;
+    });
+  }
+
+  if (notesByType.next_steps && notesByType.next_steps.length > 0) {
+    doc += `## Next Steps\n\n`;
+    notesByType.next_steps.forEach(content => {
+      doc += `${content}\n\n`;
+    });
+  }
+
+  // Plan (if exists)
+  if (plans.length > 0 && plans[0].status === 'executed') {
+    doc += `## Plan\n\n${plans[0].plan_content}\n\n`;
+  }
+
+  // Store documentation in sessions table
+  await execute(
+    `UPDATE sessions SET documentation = $1 WHERE id = $2`,
+    [doc, session_id]
+  );
+
+  return `Documentation generated for session ${session_id} (${doc.length} characters)`;
+}