Merge branch 'feature/mcp-json-config'

thrialectics · thrialectics · commit 08f0a996debe · 2026-03-03T10:16:44.000-05:00
:wq
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -8,7 +8,7 @@
       "name": "threadlinking",
       "source": "..",
       "version": "2.0.0",
-      "description": "Preserve conversation context across sessions by linking files to their origin stories"
+      "description": "Preserve decision-making context across sessions by linking files to the decisions behind them"
     }
   ]
 }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "threadlinking",
-  "description": "Preserve conversation context across sessions by linking files to their origin stories",
+  "description": "Preserve decision-making context across sessions by linking files to the decisions behind them",
   "version": "2.0.0",
   "author": {
     "name": "Marianne"
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -2,7 +2,7 @@
 
 Git tracks what changed. Threadlinking tracks **why**.
 
-A local-first tool for preserving AI conversation context alongside the files you create. When you return to code weeks later, threadlinking tells you the reasoning behind it.
+A local-first tool for preserving decision-making context alongside the files you create. When you return to code weeks later, threadlinking tells you the reasoning behind it.
 
 ---
 
diff --git a/README.md b/README.md
@@ -1,16 +1,16 @@
 # Threadlinking
 
-> Connect your files with their origin stories
+> Preserve the decisions behind your code
 
-Threadlinking is a Claude Code native tool for preserving conversation context alongside the files you create.
+Threadlinking is a Claude Code native tool for preserving decision-making context alongside the files you create.
 
-You're working with Claude on a project. It creates files, makes design decisions, solves problems. A week later, you're looking at the code wondering:
+Your team is working on a project. Files get created, design decisions are made, problems get solved. A week later, someone's looking at the code wondering:
 
-> "What was the context? What was I thinking?"
+> "Why was it built this way? What were we thinking?"
 
-Threadlinking solves this. Claude automatically saves the relevant conversation snippets when creating files, so you can always trace back to the "why."
+Threadlinking solves this. It captures the reasoning behind decisions when creating files, so you can always trace back to the "why" — even across sessions, teammates, and repos.
 
-**The key insight:** A thread is a container for an **idea or project**, not a feature or task. One thread might span months of work, dozens of files, and hundreds of snippets across multiple repos. When you start a new Claude session next week, threadlinking connects it back to the earlier conversations - preserving context across the gaps.
+**The key insight:** A thread is a container for an **idea or project**, not a feature or task. One thread might span months of work, dozens of files, and hundreds of snippets across multiple repos. When someone starts a new session next week, threadlinking connects it back to the earlier decisions — preserving context across the gaps.
 
 ---
 
@@ -122,11 +122,11 @@ All components are optional and can be skipped during init.
 
 ## How It Works
 
-Claude automatically detects when you're doing work worth preserving and prompts you:
+Claude automatically detects when decisions are being made and prompts you:
 
 ```
 You: "Let's build a new authentication system using JWT"
-Claude: "This looks like work worth preserving context for. Should I create
+Claude: "This looks like a decision worth preserving. Should I create
         a thread for this? I'd suggest 'myproject' - or name it something else."
 You: "Call it auth_system"
 Claude: [remembers: current thread = auth_system]
@@ -137,7 +137,7 @@ Claude: [runs] threadlinking attach auth_system src/auth/jwt.ts
 
 Once you confirm a thread, Claude uses it automatically for the rest of the session.
 
-Later, when you revisit the code (maybe weeks later, in a new session):
+Later, when anyone revisits the code (maybe weeks later, in a new session):
 
 ```
 You: "Why did we build auth this way?"
@@ -149,20 +149,20 @@ Claude: "You chose JWT over sessions because you wanted a stateless API..."
 
 ## Automatic Thread Detection
 
-Claude looks for signals that work should be tracked:
+Claude looks for signals that decisions are being made:
 
 - **Project mentions:** "We're working on myproject" or "This is for client X"
-- **Significant new work:** Creating files that represent architectural decisions
+- **Architectural choices:** Creating files that represent design decisions
+- **Trade-off discussions:** Choosing between approaches (REST vs GraphQL, etc.)
 - **Explicit requests:** "Remember this" or "Save this context"
-- **Design discussions:** Making choices between approaches (REST vs GraphQL, etc.)
 
-When Claude detects these signals, it prompts you to create or use a thread. You stay in control - Claude asks, you confirm.
+When Claude detects these signals, it prompts you to create or use a thread. You stay in control — Claude asks, you confirm.
 
 ---
 
 ## Cross-Session Context
 
-Threads persist across Claude sessions. One thread accumulates context over the life of a project:
+Threads persist across sessions and teammates. One thread accumulates decision context over the life of a project:
 
 ```bash
 # Week 1: Starting the project
@@ -178,7 +178,7 @@ threadlinking snippet myproject "Pivoted to cursor pagination after scale issues
 threadlinking attach myproject src/api/pagination.ts
 ```
 
-One thread, many sessions, complete context. Works across repos too - the thread lives in `~/.threadlinking/`, not in your project.
+One thread, many sessions, complete decision history. Works across repos too — the thread lives in `~/.threadlinking/`, not in your project.
 
 ---
 
@@ -301,7 +301,7 @@ threadlinking export --format markdown myproject # Single thread
 
 ## Data Storage
 
-Everything is stored locally at `~/.threadlinking/thread_index.json`. No cloud, no sync, just a simple JSON file you control.
+Everything is stored locally at `~/.threadlinking/thread_index.json`. No cloud, no sync — just a simple JSON file your team controls.
 
 ---
 
diff --git a/commands/explain.md b/commands/explain.md
@@ -1,10 +1,10 @@
 ---
-description: Show why a file exists - its origin story from threadlinking
+description: Show why a file exists - the decisions behind it from threadlinking
 ---
 
 # /explain
 
-Show the origin story and context for a file.
+Show the decisions and reasoning behind a file.
 
 ## Usage
 
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "threadlinking",
   "version": "2.0.11",
-  "description": "Connect your files with their origin stories",
+  "description": "Preserve the decisions behind your code",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -35,6 +35,7 @@
     "@modelcontextprotocol/sdk": "^1.25.2",
     "@xenova/transformers": "^2.17.2",
     "commander": "^12.0.0",
+    "ignore": "^7.0.5",
     "proper-lockfile": "^4.1.2",
     "vectra": "^0.12.3",
     "zod": "^4.3.5"
diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "threadlinking",
   "version": "2.0.0",
-  "description": "Preserve AI conversation context across sessions. Connect files with their origin stories.",
+  "description": "Preserve decision-making context across sessions. Connect files to the decisions behind them.",
   "author": {
     "name": "Marianne",
     "url": "https://github.com/thrialectics"
diff --git a/plugin/.mcp.json b/plugin/.mcp.json
@@ -2,6 +2,6 @@
   "threadlinking": {
     "command": "npx",
     "args": ["threadlinking-mcp"],
-    "description": "Preserve AI conversation context across sessions"
+    "description": "Preserve decision-making context across sessions"
   }
 }
diff --git a/plugin/README.md b/plugin/README.md
@@ -2,7 +2,7 @@
 
 Git tracks what changed. Threadlinking tracks **why**.
 
-Preserve AI conversation context across sessions. Connect files with their origin stories.
+Preserve decision-making context across sessions. Connect files to the decisions behind them.
 
 ## Installation
 
@@ -49,7 +49,7 @@ The plugin bundles the threadlinking MCP server with these tools:
 - `threadlinking_snippet` - Add context to a thread
 - `threadlinking_attach` - Link a file to a thread
 - `threadlinking_detach` - Unlink a file
-- `threadlinking_explain` - Show file's origin story
+- `threadlinking_explain` - Show the decisions behind a file
 - `threadlinking_show` - View thread details
 - `threadlinking_list` - List all threads
 - `threadlinking_search` - Keyword search
diff --git a/plugin/skills/explain-file/SKILL.md b/plugin/skills/explain-file/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: explain-file
-description: Show why a file exists - its origin story and the decisions that led to its creation.
+description: Show why a file exists — the decisions and reasoning that led to its creation.
 argument-hint: [file-path]
 user-invocable: true
 ---
diff --git a/skills/threadlinking/SKILL.md b/skills/threadlinking/SKILL.md
@@ -1,16 +1,16 @@
 ---
 name: threadlinking
-description: Preserve conversation context across sessions by linking files to their origin stories
+description: Preserve decision-making context across sessions by linking files to the decisions behind them
 alwaysApply: false
 ---
 
 # threadlinking Skill
 
-You have access to threadlinking - a system for preserving context across sessions.
+You have access to threadlinking - a system for preserving decision-making context across sessions.
 
 ## Core Concept
 
-Every file has an origin story. Threadlinking captures *why* code exists, not just *what* it does. This context persists across sessions, so future conversations can understand past decisions.
+Every file has decisions behind it. Threadlinking captures *why* code exists, not just *what* it does. This context persists across sessions, so anyone returning to the code can understand the reasoning.
 
 ## When to Use Threadlinking
 
@@ -23,7 +23,7 @@ Every file has an origin story. Threadlinking captures *why* code exists, not ju
 
 ### Prompt the user when you detect thread-worthy work:
 
-> "This looks like work worth preserving. Should I save this context to a thread called 'projectname'?"
+> "This looks like a decision worth preserving. Should I save this context to a thread called 'projectname'?"
 
 Once confirmed, **remember the thread name for the session** and use it automatically.
 
@@ -89,5 +89,5 @@ When ending significant work:
 Users can also use these shortcuts:
 
 - `/threadlink <thread> "content" [file]` - Save and optionally attach
-- `/explain <file>` - Show file's origin story
+- `/explain <file>` - Show the decisions behind a file
 - `/context [thread]` - List threads or show details
diff --git a/src/commands/init.ts b/src/commands/init.ts
@@ -37,7 +37,7 @@ const MCP_SERVER_CONFIG = {
 const CLAUDE_MD_BLOCK = `
 ## Threadlinking
 
-**Threadlinking preserves conversation context across sessions.** Use it actively.
+**Threadlinking preserves decision-making context across sessions.** Use it actively.
 
 ### Session Protocol
 
diff --git a/src/index.ts b/src/index.ts
@@ -25,7 +25,7 @@ const program = new Command();
 
 program
   .name('threadlinking')
-  .description('Connect your files with their origin stories')
+  .description('Preserve the decisions behind your code')
   .version(VERSION);
 
 // Core commands
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
@@ -31,16 +31,16 @@ export function createServer(): McpServer {
       capabilities: {
         tools: {},
       },
-      instructions: `threadlinking preserves AI conversation context across sessions.
+      instructions: `threadlinking preserves decision-making context across sessions.
 
 Key concepts:
 - **Threads**: Named containers for context (use project names, not task names)
 - **Snippets**: Context excerpts explaining decisions
-- **File links**: Connect files to their origin stories
+- **File links**: Connect files to the decisions behind them
 
 Proactively save context when:
-- Creating new files from conversation decisions
-- Making architectural choices
+- Making architectural choices or trade-off decisions
+- Creating new files based on design decisions
 - User asks to "remember why" something was done`,
     }
   );
@@ -167,7 +167,7 @@ Proactively save context when:
   // threadlinking_explain - Get context for a file
   server.tool(
     'threadlinking_explain',
-    'Show why a file exists - its origin story and the decisions that led to it.',
+    'Show why a file exists — the decisions and reasoning that led to it.',
     {
       file_path: z.string().describe('Path to the file to explain'),
     },
diff --git a/tests/cli.test.ts b/tests/cli.test.ts
@@ -29,7 +29,7 @@ describe('CLI', () => {
   it('should show help', () => {
     const { stdout, exitCode } = runCli('--help');
     expect(exitCode).toBe(0);
-    expect(stdout).toContain('Connect your files with their origin stories');
+    expect(stdout).toContain('Preserve the decisions behind your code');
     expect(stdout).toContain('Commands:');
   });
 

Original file line number	Diff line number	Diff line change
`@@ -8,7 +8,7 @@`
`8`	`8`	`"name": "threadlinking",`
`9`	`9`	`"source": "..",`
`10`	`10`	`"version": "2.0.0",`
`11`		`- "description": "Preserve conversation context across sessions by linking files to their origin stories"`
	`11`	`+ "description": "Preserve decision-making context across sessions by linking files to the decisions behind them"`
`12`	`12`	`}`
`13`	`13`	`]`
`14`	`14`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "threadlinking",`
`3`		`- "description": "Preserve conversation context across sessions by linking files to their origin stories",`
	`3`	`+ "description": "Preserve decision-making context across sessions by linking files to the decisions behind them",`
`4`	`4`	`"version": "2.0.0",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Marianne"`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "threadlinking",`
`3`	`3`	`"version": "2.0.0",`
`4`		`- "description": "Preserve AI conversation context across sessions. Connect files with their origin stories.",`
	`4`	`+ "description": "Preserve decision-making context across sessions. Connect files to the decisions behind them.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Marianne",`
`7`	`7`	`"url": "https://github.com/thrialectics"`
Original file line number	Diff line number	Diff line change
`@@ -2,6 +2,6 @@`
`2`	`2`	`"threadlinking": {`
`3`	`3`	`"command": "npx",`
`4`	`4`	`"args": ["threadlinking-mcp"],`
`5`		`- "description": "Preserve AI conversation context across sessions"`
	`5`	`+ "description": "Preserve decision-making context across sessions"`
`6`	`6`	`}`
`7`	`7`	`}`