project-mcp 3.2.2 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "project-mcp",
-	"version": "3.2.2",
+	"version": "3.3.0",
 	"description": "Intent-based MCP server for project documentation search. Maps natural language queries to the right sources automatically—no configuration needed. The standard for AI agent documentation search.",
 	"type": "module",
 	"main": "src/index.js",

package/src/lib/constants.js

@@ -14,19 +14,29 @@ export const ARCHIVE_DIR = join(PROJECT_DIR, 'archive');
 export const BACKLOG_FILE = join(PROJECT_DIR, 'BACKLOG.md');
 export const THOUGHTS_DIR = join(PROJECT_DIR, 'thoughts');
 export const THOUGHTS_TODOS_DIR = join(THOUGHTS_DIR, 'todos');
+export const THOUGHTS_ARCHIVE_DIR = join(THOUGHTS_TODOS_DIR, '.archive');
 
 /**
  * Intent to source mapping.
  * Maps user intent to which directories should be searched.
+ *
+ * IMPORTANT DISTINCTION:
+ * - "project" (operational) → .project/ management files (status, todos, roadmap, backlog)
+ * - "project_docs" (documentation) → docs/ folder + DECISIONS.md (application documentation)
+ *
+ * When users say "project docs" or "project documentation", they mean APPLICATION
+ * documentation (how the system works), NOT project management (tracking work).
  */
 export const INTENT_SOURCES = {
 	project: ['project', 'root', 'docs'], // .project/, root files, docs/
 	docs: ['docs'], // Only docs/
+	project_docs: ['docs', 'decisions'], // Application documentation: docs/ + DECISIONS.md
 	plan: ['project'], // Only .project/
 	todos: ['project'],
 	roadmap: ['project'],
 	status: ['project'],
 	operational: ['project'],
+	decisions: ['decisions'], // Architecture decisions only (DECISIONS.md)
 };
 
 /**

package/src/lib/files.js

@@ -5,7 +5,14 @@
 import { readFile, readdir, stat, writeFile, mkdir, unlink, rename } from 'fs/promises';
 import { join, extname, basename } from 'path';
 import matter from 'gray-matter';
-import { PROJECT_DIR, TODOS_DIR, ARCHIVE_DIR, THOUGHTS_DIR, THOUGHTS_TODOS_DIR } from './constants.js';
+import {
+	PROJECT_DIR,
+	TODOS_DIR,
+	ARCHIVE_DIR,
+	THOUGHTS_DIR,
+	THOUGHTS_TODOS_DIR,
+	THOUGHTS_ARCHIVE_DIR,
+} from './constants.js';
 
 /**
  * Ensure .project directory exists
@@ -62,6 +69,17 @@ export async function ensureThoughtsTodosDir() {
 	}
 }
 
+/**
+ * Ensure .project/thoughts/todos/.archive directory exists
+ */
+export async function ensureThoughtsArchiveDir() {
+	try {
+		await mkdir(THOUGHTS_ARCHIVE_DIR, { recursive: true });
+	} catch (error) {
+		// Directory might already exist
+	}
+}
+
 /**
  * Check if a file exists
  * @param {string} filePath - Path to check

package/src/lib/search.js

@@ -31,12 +31,28 @@ export function detectIntent(query, explicitIntent) {
 
 	const queryLower = query.toLowerCase();
 
-	// Check for operational keywords
-	if (/\b(plan|plans|todo|todos|roadmap|status|operational|current state|decisions)\b/.test(queryLower)) {
+	// Check for "project docs/documents/documentation" - this means APPLICATION documentation
+	// NOT project management. Routes to docs/ folder + DECISIONS.md
+	if (
+		/\b(project\s+doc(s|ument(s|ation)?)?|update\s+(project\s+)?doc(s|ument(s|ation)?)?|application\s+doc(s|ument(s|ation)?)?)\b/.test(
+			queryLower
+		)
+	) {
+		return 'project_docs';
+	}
+
+	// Check for architecture decisions specifically
+	if (/\b(decision(s)?|adr|architecture\s+decision(s)?|technical\s+decision(s)?)\b/.test(queryLower)) {
+		return 'decisions';
+	}
+
+	// Check for operational/project management keywords (status, todos, roadmap, backlog)
+	// This is DIFFERENT from "project docs" - this is about tracking work, not documenting the system
+	if (/\b(plan|plans|todo|todos|roadmap|status|operational|current state|backlog)\b/.test(queryLower)) {
 		return 'plan';
 	}
 
-	// Check for docs-specific keywords
+	// Check for docs-only keywords (just "docs" or "documentation" without "project")
 	if (/\b(docs|documentation|reference|guide|guides|api docs)\b/.test(queryLower)) {
 		return 'docs';
 	}
@@ -51,7 +67,12 @@ export function detectIntent(query, explicitIntent) {
  * @returns {string[]} Array of source names
  */
 export function getSourcesForIntent(intent) {
-	return INTENT_SOURCES[intent] || INTENT_SOURCES.project;
+	const sources = INTENT_SOURCES[intent] || INTENT_SOURCES.project;
+
+	// 'decisions' is a virtual source that maps to DECISIONS.md in .project/
+	// When we see 'decisions' in the sources, we need to include it for filtering
+	// The actual loading happens in loadAllFiles() which tags DECISIONS.md with source='decisions'
+	return sources;
 }
 
 /**
@@ -67,8 +88,21 @@ export async function loadAllFiles(force = false) {
 	const allFiles = [];
 
 	// Load .project/ directory
+	// DECISIONS.md gets special treatment - it's tagged as both 'project' and 'decisions'
+	// because it's application documentation (explains WHY the system is built this way)
+	// not just project management
 	try {
-		await scanDirectory(PROJECT_DIR, '.project', allFiles, 'project');
+		const projectFiles = [];
+		await scanDirectory(PROJECT_DIR, '.project', projectFiles, 'project');
+
+		// Tag DECISIONS.md with source='decisions' so it appears in project_docs queries
+		for (const file of projectFiles) {
+			if (file.path.endsWith('DECISIONS.md')) {
+				// DECISIONS.md is application documentation, not just project management
+				file.source = 'decisions';
+			}
+			allFiles.push(file);
+		}
 	} catch (error) {
 		// .project/ might not exist
 	}

package/src/prompts/definitions.js

@@ -24,6 +24,7 @@ export const promptToolMapping = {
 	get_backlog: ['get_backlog'],
 	add_decision: ['add_decision'],
 	update_status: ['update_project_status'],
+	update_project_docs: ['search_project', 'get_doc', 'add_decision', 'list_docs'],
 };
 
 /**
@@ -204,6 +205,25 @@ export const prompts = [
 			},
 		],
 	},
+	{
+		name: 'update_project_docs',
+		description:
+			'Update project documentation - the APPLICATION documentation that explains how the system works. Use when user says "update project docs", "update project documents", "update project documentation", "update application docs", or "document this". This is DIFFERENT from project management (status, todos, roadmap) - this updates the docs/ folder and DECISIONS.md which contain reference documentation about the application itself.',
+		arguments: [
+			{
+				name: 'content',
+				description:
+					'What to document or update. The model will determine whether this belongs in docs/ (application documentation) or DECISIONS.md (architecture decisions).',
+				required: true,
+			},
+			{
+				name: 'doc_type',
+				description:
+					'Hint for documentation type: "decision" for architecture decisions (DECISIONS.md), "release" for release notes, "guide" for user guides, "api" for API docs, or "auto" to let the model decide based on content.',
+				required: false,
+			},
+		],
+	},
 ];
 
 /**

package/src/prompts/index.js

@@ -203,6 +203,32 @@ This adds a timestamped status entry to STATUS.md.`,
 				},
 			},
 		],
+		update_project_docs: [
+			{
+				role: 'user',
+				content: {
+					type: 'text',
+					text: `Update project documentation with: "${args.content || '[CONTENT]'}".
+
+IMPORTANT: This is about APPLICATION DOCUMENTATION (how the system works), NOT project management (status, todos, roadmap).
+
+${args.doc_type === 'decision' ? `This is an architecture decision. Use the \`add_decision\` tool to add it to DECISIONS.md.` : args.doc_type === 'release' ? `This is a release note. Look in docs/releases/ and update the appropriate file.` : `Based on the content, determine where this documentation belongs:
+
+1. **Architecture Decision?** (design choice, trade-off, technical rationale)
+   → Use \`add_decision\` tool to add to DECISIONS.md
+
+2. **Application Documentation?** (how-to, API docs, guides, reference)
+   → First use \`search_project\` with intent "project_docs" to find relevant existing docs
+   → Then use \`list_docs\` to see the docs/ structure
+   → Update the appropriate file in docs/
+
+3. **Release Notes?** (version changes, features, fixes)
+   → Check docs/releases/ for the right file
+
+The model decides where this content best fits based on its nature.`}`,
+				},
+			},
+		],
 	};
 
 	return (
@@ -236,6 +262,7 @@ export function getMessageHandlerKeys() {
 		get_backlog: true,
 		add_decision: true,
 		update_status: true,
+		update_project_docs: true,
 	};
 	return Object.keys(messages);
 }

package/src/tools/lint.js

@@ -378,42 +378,52 @@ ${project_description}
 
 ## Contract for AI Agents
 
-When a user says **"project"**, **"the project"**, or **"my project"**, the canonical sources of truth are:
+### Critical Distinction: Project Management vs Project Documentation
 
-1. **\`.project/\`** — Current state, plans, todos, decisions (operational truth)
-2. **Root markdown files** — README.md, CONTRIBUTING.md, etc.
-3. **\`docs/\`** — Long-form reference documentation
+| Term | Means | Sources |
+|------|-------|---------|
+| **"project docs"** / **"project documentation"** | Application documentation (HOW the system works) | \`docs/\` + \`DECISIONS.md\` |
+| **"project status"** / **"todos"** / **"roadmap"** | Project management (WHAT we're doing) | \`.project/\` management files |
+
+**DECISIONS.md is special**: It's application documentation (explains WHY decisions were made) even though it lives in \`.project/\`.
 
 ## Source Mappings
 
-### "project" / "the project"
-Searches: \`.project/\` + root files + \`docs/\`
+### "project docs" / "project documents" / "project documentation"
+APPLICATION documentation — how the system works, why it was built this way.
+Searches: \`docs/\` + \`DECISIONS.md\`
 
-### "docs" / "documentation"
+### "docs" / "documentation" / "reference"
+Reference documentation only.
 Searches: \`docs/\` only
 
-### "plan" / "todos" / "roadmap" / "status"
-Searches: \`.project/\` only
+### "plan" / "todos" / "roadmap" / "status" / "backlog"
+Project MANAGEMENT — tracking work, not documenting the system.
+Searches: \`.project/\` (excluding DECISIONS.md)
+
+### "project" / "the project"
+Everything (when intent is ambiguous).
+Searches: \`.project/\` + root files + \`docs/\`
 
 ## File Structure
 
-| File | Purpose |
-|------|---------|
-| \`index.md\` | This file - contract and source mappings |
-| \`BACKLOG.md\` | Prioritized work queue (future tasks) |
-| \`TODO.md\` | Task dashboard (active work, auto-generated) |
-| \`ROADMAP.md\` | Project phases and milestones |
-| \`STATUS.md\` | Current project health and progress |
-| \`DECISIONS.md\` | Architecture decisions and rationale |
-| \`todos/\` | Active task files (10-30 items, not hundreds) |
-| \`archive/\` | Completed tasks (for history) |
+| File | Type | Purpose |
+|------|------|---------|
+| \`index.md\` | Contract | This file - source mappings |
+| \`DECISIONS.md\` | **Documentation** | Architecture decisions (WHY) |
+| \`BACKLOG.md\` | Management | Prioritized work queue |
+| \`TODO.md\` | Management | Task dashboard |
+| \`ROADMAP.md\` | Management | Project phases/milestones |
+| \`STATUS.md\` | Management | Project health/progress |
+| \`todos/\` | Management | Active task files |
+| \`archive/\` | Management | Completed tasks |
 
 ## Principles
 
-- **Natural language stays natural** — Users say "project" not ".project/"
+- **"Project docs" ≠ "Project management"** — Users saying "update project docs" want application documentation updated, not task tracking
+- **DECISIONS.md is documentation** — It explains the system, not tracks work
+- **Natural language stays natural** — "Project docs" maps to docs/ + DECISIONS.md
 - **Agents don't guess** — Explicit mappings defined here
-- **Intent over structure** — Language maps to intent, not directory names
-- **Operational truth** — This directory is the source of truth for current state
 
 ---
 *Last Updated: ${date}*

package/src/tools/search.js

@@ -16,7 +16,7 @@ export const definitions = [
 	{
 		name: 'search_project',
 		description:
-			'Search across all project sources: .project/ (operational truth), root-level files, and docs/ (reference truth). Use this when the user says "project", "the project", or asks about project status, plans, todos, or roadmap. Maps natural language to appropriate sources automatically.',
+			'Search across project sources with smart intent detection. IMPORTANT: "project docs" means APPLICATION documentation (docs/ + DECISIONS.md), NOT project management. Use intent "project_docs" when user says "project docs/documents/documentation" to search application documentation. Use intent "plan" for project management (status, todos, roadmap, backlog).',
 		inputSchema: {
 			type: 'object',
 			properties: {
@@ -28,8 +28,19 @@ export const definitions = [
 				intent: {
 					type: 'string',
 					description:
-						'Optional: Intent type to map to sources. Options: "project" (searches .project/, root, docs), "docs" (only docs/), "plan/todos/roadmap/status/operational" (only .project/). If not specified, automatically detects from query.',
-					enum: ['project', 'docs', 'plan', 'todos', 'roadmap', 'status', 'operational', ''],
+						'Intent type to map to sources. "project_docs" searches docs/ + DECISIONS.md (application documentation). "docs" searches only docs/. "plan/todos/roadmap/status/operational" searches .project/ (project management). "project" searches everything. "decisions" searches only DECISIONS.md.',
+					enum: [
+						'project',
+						'project_docs',
+						'docs',
+						'decisions',
+						'plan',
+						'todos',
+						'roadmap',
+						'status',
+						'operational',
+						'',
+					],
 				},
 				maxResults: {
 					type: 'number',

package/src/tools/thoughts.js

@@ -1,17 +1,29 @@
 /**
  * Thought processing tools.
- * Handles: process_thoughts, list_thoughts, get_thought
+ * Handles: process_thoughts, list_thoughts, get_thought, archive_thought, list_archived_thoughts
  *
  * This tool reads brain dump files and provides context for the LLM to analyze.
  * The LLM does the natural language understanding - the tool just gathers data.
  */
 
 import { readdir } from 'fs/promises';
-import { THOUGHTS_TODOS_DIR, PROJECT_DIR } from '../lib/constants.js';
-import { readFile, join, fileExists, ensureThoughtsTodosDir, matter } from '../lib/files.js';
+import { THOUGHTS_TODOS_DIR, THOUGHTS_ARCHIVE_DIR } from '../lib/constants.js';
+import {
+	readFile,
+	writeFile,
+	rename,
+	join,
+	fileExists,
+	ensureThoughtsTodosDir,
+	ensureThoughtsArchiveDir,
+	matter,
+} from '../lib/files.js';
+import { getISODate, getCurrentDate } from '../lib/dates.js';
 import { loadAllTasks } from '../lib/tasks.js';
 import { loadAllFiles, getCachedFiles } from '../lib/search.js';
 
+const ARCHIVE_LOG_FILE = '.archive-log.md';
+
 /**
  * Tool definitions
  */
@@ -30,6 +42,7 @@ YOU (the LLM) should then analyze the content to:
 - Identify logical task groupings (consolidate related items)
 - Determine appropriate priorities based on context
 - Create well-structured tasks using create_task
+- **After creating tasks, use archive_thought to archive the processed file**
 
 The tool does NOT automatically create tasks - it provides you with everything needed to make intelligent decisions about task creation.`,
 		inputSchema: {
@@ -48,6 +61,31 @@ The tool does NOT automatically create tasks - it provides you with everything n
 			required: ['project'],
 		},
 	},
+	{
+		name: 'archive_thought',
+		description: `Archives a processed thought file by moving it to .project/thoughts/todos/.archive/. 
+Use this after you've created tasks from a thought file to keep the active thoughts folder clean.
+Also logs the archive action with timestamp and created task IDs.`,
+		inputSchema: {
+			type: 'object',
+			properties: {
+				file: {
+					type: 'string',
+					description: 'The thought file to archive (e.g., "my-ideas.md").',
+				},
+				created_tasks: {
+					type: 'array',
+					items: { type: 'string' },
+					description: 'Array of task IDs that were created from this thought (e.g., ["AUTH-001", "AUTH-002"]).',
+				},
+				notes: {
+					type: 'string',
+					description: 'Optional notes about the processing (e.g., "Consolidated 5 items into 2 tasks").',
+				},
+			},
+			required: ['file'],
+		},
+	},
 	{
 		name: 'list_thoughts',
 		description:
@@ -60,6 +98,26 @@ The tool does NOT automatically create tasks - it provides you with everything n
 					description: 'Optional: Filter by thought category. Currently supported: "todos".',
 					enum: ['todos', ''],
 				},
+				include_archived: {
+					type: 'boolean',
+					description: 'Include archived thoughts in the listing. Default: false.',
+					default: false,
+				},
+			},
+		},
+	},
+	{
+		name: 'list_archived_thoughts',
+		description:
+			'Lists all archived thought files with their processing history. Shows what thoughts were processed, when, and what tasks were created.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				limit: {
+					type: 'number',
+					description: 'Maximum number of archived thoughts to show. Default: 20.',
+					default: 20,
+				},
 			},
 		},
 	},
@@ -78,6 +136,11 @@ The tool does NOT automatically create tasks - it provides you with everything n
 					description: 'The category/subdirectory. Default: "todos".',
 					default: 'todos',
 				},
+				from_archive: {
+					type: 'boolean',
+					description: 'Read from archive instead of active thoughts. Default: false.',
+					default: false,
+				},
 			},
 			required: ['file'],
 		},
@@ -113,7 +176,7 @@ async function getProjectContext() {
 		// Get roadmap content
 		const roadmapFile = files.find(f => f.path.includes('ROADMAP'));
 		if (roadmapFile) {
-			context.roadmap = roadmapFile.content.substring(0, 2000); // First 2000 chars
+			context.roadmap = roadmapFile.content.substring(0, 2000);
 		}
 
 		// Get decisions
@@ -126,7 +189,7 @@ async function getProjectContext() {
 		// Get current status
 		const statusFile = files.find(f => f.path.includes('STATUS'));
 		if (statusFile) {
-			context.status = statusFile.content.substring(0, 1000); // First 1000 chars
+			context.status = statusFile.content.substring(0, 1000);
 		}
 	} catch {
 		// Context loading failed, continue without it
@@ -163,7 +226,7 @@ async function processThoughts(args) {
 		try {
 			const files = await readdir(THOUGHTS_TODOS_DIR);
 			filesToProcess = files
-				.filter(f => f.endsWith('.md'))
+				.filter(f => f.endsWith('.md') && !f.startsWith('.'))
 				.map(f => ({ name: f, path: join(THOUGHTS_TODOS_DIR, f) }));
 		} catch {
 			// Directory might not exist yet
@@ -227,6 +290,10 @@ Analyze the thought content below and create appropriate tasks. Consider:
    - tags: Relevant categorization
    - subtasks: Array of subtask strings (for consolidated items)
 
+5. **After creating tasks, archive the thought file** using \`archive_thought\`:
+   - Pass the filename and array of created task IDs
+   - This keeps the thoughts folder clean and maintains a processing log
+
 ---
 
 ## Thought Files to Process
@@ -275,6 +342,7 @@ Use this to understand what already exists and align new tasks appropriately.
 		}
 	}
 
+	const filenames = thoughtContents.map(t => t.filename).join('", "');
 	result += `
 ---
 
@@ -285,6 +353,10 @@ Now analyze the thought content above and:
 1. Identify the distinct tasks/initiatives (consolidate related items)
 2. For each task, determine title, priority, and relevant context
 3. Use \`create_task\` to create well-structured tasks
+4. **After creating tasks, use \`archive_thought\`** to archive each processed file:
+   \`\`\`
+   archive_thought(file: "${thoughtContents[0]?.filename || 'filename.md'}", created_tasks: ["${project.toUpperCase()}-001", ...])
+   \`\`\`
 
 Remember: Quality over quantity. Create fewer, well-scoped tasks rather than many granular ones.
 `;
@@ -294,11 +366,171 @@ Remember: Quality over quantity. Create fewer, well-scoped tasks rather than man
 	};
 }
 
+/**
+ * Archive thought handler
+ */
+async function archiveThought(args) {
+	const { file, created_tasks = [], notes } = args;
+
+	await ensureThoughtsTodosDir();
+	await ensureThoughtsArchiveDir();
+
+	const sourcePath = join(THOUGHTS_TODOS_DIR, file);
+	const archivePath = join(THOUGHTS_ARCHIVE_DIR, file);
+	const logPath = join(THOUGHTS_ARCHIVE_DIR, ARCHIVE_LOG_FILE);
+
+	// Check if file exists
+	if (!(await fileExists(sourcePath))) {
+		return {
+			content: [
+				{
+					type: 'text',
+					text: `❌ File not found: ${file}\n\nUse \`list_thoughts\` to see available files.`,
+				},
+			],
+			isError: true,
+		};
+	}
+
+	// Read the original content for the log
+	const originalContent = await readFile(sourcePath, 'utf-8');
+	const lineCount = originalContent.split('\n').length;
+
+	// Move file to archive
+	await rename(sourcePath, archivePath);
+
+	// Update archive log
+	let logContent = '';
+	try {
+		if (await fileExists(logPath)) {
+			logContent = await readFile(logPath, 'utf-8');
+		}
+	} catch {
+		// Log file doesn't exist yet
+	}
+
+	// Create log entry
+	const logEntry = `
+## ${file}
+
+**Archived:** ${getCurrentDate()}
+**Original Lines:** ${lineCount}
+**Tasks Created:** ${created_tasks.length > 0 ? created_tasks.join(', ') : 'None specified'}
+${notes ? `**Notes:** ${notes}` : ''}
+
+---
+`;
+
+	// Prepend new entry to log (newest first)
+	if (!logContent.includes('# Thought Archive Log')) {
+		logContent = `# Thought Archive Log
+
+This file tracks all processed thoughts and the tasks created from them.
+
+---
+${logEntry}`;
+	} else {
+		logContent = logContent.replace(
+			'---\n',
+			`---
+${logEntry}`
+		);
+	}
+
+	await writeFile(logPath, logContent, 'utf-8');
+
+	let result = `## Thought Archived: ${file}\n\n`;
+	result += `**Moved to:** \`.project/thoughts/todos/.archive/${file}\`\n`;
+	result += `**Archived:** ${getCurrentDate()}\n`;
+	result += `**Lines:** ${lineCount}\n`;
+
+	if (created_tasks.length > 0) {
+		result += `\n**Tasks Created:**\n`;
+		for (const taskId of created_tasks) {
+			result += `- ${taskId}\n`;
+		}
+	}
+
+	if (notes) {
+		result += `\n**Notes:** ${notes}\n`;
+	}
+
+	result += `\n✅ Thought file archived successfully. Use \`list_archived_thoughts\` to see archive history.`;
+
+	return {
+		content: [{ type: 'text', text: result }],
+	};
+}
+
+/**
+ * List archived thoughts handler
+ */
+async function listArchivedThoughts(args) {
+	const { limit = 20 } = args || {};
+
+	await ensureThoughtsArchiveDir();
+
+	let result = `## Archived Thoughts\n\n`;
+	result += `**Path:** \`.project/thoughts/todos/.archive/\`\n\n`;
+
+	// Read archive log if exists
+	const logPath = join(THOUGHTS_ARCHIVE_DIR, ARCHIVE_LOG_FILE);
+	let logContent = '';
+
+	try {
+		if (await fileExists(logPath)) {
+			logContent = await readFile(logPath, 'utf-8');
+		}
+	} catch {
+		// Log doesn't exist
+	}
+
+	if (logContent) {
+		result += `### Archive Log\n\n`;
+		// Show the log content (it's already formatted)
+		const entries = logContent.split('## ').slice(1, limit + 1);
+		for (const entry of entries) {
+			result += `## ${entry}\n`;
+		}
+	}
+
+	// Also list actual files in archive
+	try {
+		const files = await readdir(THOUGHTS_ARCHIVE_DIR);
+		const mdFiles = files.filter(f => f.endsWith('.md') && f !== ARCHIVE_LOG_FILE);
+
+		if (mdFiles.length > 0) {
+			result += `\n### Archived Files (${mdFiles.length})\n\n`;
+			result += `| File | Size |\n`;
+			result += `|------|------|\n`;
+			for (const file of mdFiles.slice(0, limit)) {
+				const filePath = join(THOUGHTS_ARCHIVE_DIR, file);
+				const content = await readFile(filePath, 'utf-8');
+				const lines = content.split('\n').length;
+				result += `| ${file} | ${lines} lines |\n`;
+			}
+		}
+	} catch {
+		// Archive directory might not exist
+	}
+
+	if (!logContent && result.includes('Archived Files') === false) {
+		result += `*No archived thoughts yet. Use \`archive_thought\` after processing thoughts.*\n`;
+	}
+
+	result += `\n---\n`;
+	result += `**Tools:** \`get_thought\` with \`from_archive: true\` to read archived files`;
+
+	return {
+		content: [{ type: 'text', text: result }],
+	};
+}
+
 /**
  * List thoughts handler
  */
 async function listThoughts(args) {
-	const { category } = args || {};
+	const { category, include_archived = false } = args || {};
 
 	await ensureThoughtsTodosDir();
 
@@ -311,7 +543,7 @@ async function listThoughts(args) {
 		try {
 			if (await fileExists(catDir)) {
 				const files = await readdir(catDir);
-				const mdFiles = files.filter(f => f.endsWith('.md'));
+				const mdFiles = files.filter(f => f.endsWith('.md') && !f.startsWith('.'));
 
 				results[cat] = [];
 				for (const file of mdFiles) {
@@ -353,9 +585,24 @@ async function listThoughts(args) {
 		}
 	}
 
+	// Show archived count if requested
+	if (include_archived) {
+		try {
+			await ensureThoughtsArchiveDir();
+			const archivedFiles = await readdir(THOUGHTS_ARCHIVE_DIR);
+			const archivedMd = archivedFiles.filter(f => f.endsWith('.md') && f !== ARCHIVE_LOG_FILE);
+			if (archivedMd.length > 0) {
+				result += `### 📦 .archive/ (${archivedMd.length} files)\n\n`;
+				result += `Use \`list_archived_thoughts\` to see details.\n\n`;
+			}
+		} catch {
+			// Archive doesn't exist
+		}
+	}
+
 	result += `---\n`;
-	result += `**Total files:** ${totalFiles}\n\n`;
-	result += `**Tools:** \`get_thought\` to read | \`process_thoughts\` to analyze`;
+	result += `**Total active files:** ${totalFiles}\n\n`;
+	result += `**Tools:** \`get_thought\` to read | \`process_thoughts\` to analyze | \`archive_thought\` after processing`;
 
 	return {
 		content: [{ type: 'text', text: result }],
@@ -366,19 +613,27 @@ async function listThoughts(args) {
  * Get thought handler
  */
 async function getThought(args) {
-	const { file, category = 'todos' } = args;
+	const { file, category = 'todos', from_archive = false } = args;
 
 	await ensureThoughtsTodosDir();
 
-	const catDir = category === 'todos' ? THOUGHTS_TODOS_DIR : join(THOUGHTS_TODOS_DIR, '..', category);
+	let catDir;
+	if (from_archive) {
+		await ensureThoughtsArchiveDir();
+		catDir = THOUGHTS_ARCHIVE_DIR;
+	} else {
+		catDir = category === 'todos' ? THOUGHTS_TODOS_DIR : join(THOUGHTS_TODOS_DIR, '..', category);
+	}
+
 	const filePath = join(catDir, file);
 
 	if (!(await fileExists(filePath))) {
+		const location = from_archive ? '.archive' : category;
 		return {
 			content: [
 				{
 					type: 'text',
-					text: `❌ File not found: \`.project/thoughts/${category}/${file}\`\n\nUse \`list_thoughts\` to see available files.`,
+					text: `❌ File not found: \`.project/thoughts/todos/${location}/${file}\`\n\nUse \`list_thoughts\` or \`list_archived_thoughts\` to see available files.`,
 				},
 			],
 			isError: true,
@@ -388,9 +643,10 @@ async function getThought(args) {
 	const content = await readFile(filePath, 'utf-8');
 	const parsed = matter(content);
 
+	const location = from_archive ? 'todos/.archive' : category;
 	let result = `## Thought File: ${file}\n\n`;
-	result += `**Path:** \`.project/thoughts/${category}/${file}\`\n`;
-	result += `**Category:** ${category}\n\n`;
+	result += `**Path:** \`.project/thoughts/${location}/${file}\`\n`;
+	result += `**Status:** ${from_archive ? '📦 Archived' : '📝 Active'}\n\n`;
 
 	if (Object.keys(parsed.data).length > 0) {
 		result += `### Frontmatter\n\n`;
@@ -405,7 +661,11 @@ async function getThought(args) {
 	result += parsed.content;
 
 	result += `\n\n---\n`;
-	result += `**Tools:** \`process_thoughts\` to analyze and create tasks`;
+	if (from_archive) {
+		result += `**This file has been archived.** It was already processed into tasks.`;
+	} else {
+		result += `**Tools:** \`process_thoughts\` to analyze | \`archive_thought\` after creating tasks`;
+	}
 
 	return {
 		content: [{ type: 'text', text: result }],
@@ -417,6 +677,8 @@ async function getThought(args) {
  */
 export const handlers = {
 	process_thoughts: processThoughts,
+	archive_thought: archiveThought,
 	list_thoughts: listThoughts,
+	list_archived_thoughts: listArchivedThoughts,
 	get_thought: getThought,
 };