Add thread relationships, duplicate detection, CLI tips, and README improvements

Author: thrialectics

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
         "source": "url",
         "url": "https://github.com/thrialectics/threadlinking.git"
       },
-      "version": "3.0.0",
+      "version": "3.0.1",
       "description": "Preserve decision-making context across sessions by linking files to the decisions behind them"
     }
   ]

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "threadlinking",
   "description": "Preserve decision-making context across sessions by linking files to the decisions behind them",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "author": {
     "name": "Marianne"
   },

README.md

@@ -1,16 +1,12 @@
 # Threadlinking
 
-> Preserve the decisions behind your code
+> Git tracks what changed. Threadlinking tracks **why**.
 
-Threadlinking is a Claude Code native tool for preserving decision-making context alongside the files you create.
+You built something three weeks ago. Now you're staring at it, trying to remember why you made that choice. The commit message says "add auth module" -- but why JWT? Why not sessions? What constraint drove that decision?
 
-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:
+Threadlinking captures decision rationale alongside your code. It works natively with Claude Code -- Claude detects decisions as you make them, saves the reasoning, and surfaces it when you (or a teammate) come back later.
 
-> "Why was it built this way? What were we thinking?"
-
-Threadlinking solves this by capturing decision rationale for your files and code, so you can trace your "why" across sessions, teammates, and repos.
-
-A thread is a container for an **idea or project**, not just 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.
+A **thread** is a container for an idea or project, not a task. One thread spans months of work, dozens of files, and hundreds of context snippets. When you start a new session weeks later, threadlinking connects it back to the earlier decisions.
 
 ---
 
@@ -20,22 +16,22 @@ Threadlinking ships as a **Claude Code plugin** — when you run `threadlinking
 
 ### MCP Tools
 
-These are the tools Claude gets when the MCP server is active:
+Threadlinking exposes 12 tools to Claude Code via MCP:
 
-| Tool | What it does |
+| Tool | Description |
 |------|-------------|
-| `threadlinking_snippet` | Save decision context to a thread |
+| `threadlinking_snippet` | Add a context snippet to a thread (auto-creates thread if needed) |
 | `threadlinking_create` | Create a new empty thread |
 | `threadlinking_attach` | Link a file to a thread |
-| `threadlinking_detach` | Unlink a file from a thread |
-| `threadlinking_explain` | Show why a file exists |
-| `threadlinking_show` | View full thread details |
-| `threadlinking_list` | List all threads + pending files |
-| `threadlinking_search` | Keyword search across threads |
-| `threadlinking_semantic_search` | Natural language search by meaning |
-| `threadlinking_analytics` | Usage stats and insights |
-| `threadlinking_export` | Export threads (markdown, JSON, timeline) |
-| `threadlinking_status` | Check available features and version |
+| `threadlinking_detach` | Remove a file link from a thread |
+| `threadlinking_explain` | Show why a file exists — the decisions and reasoning behind it |
+| `threadlinking_show` | View full thread details including all snippets and linked files |
+| `threadlinking_list` | List all threads and pending unlinked files |
+| `threadlinking_search` | Search threads by keyword |
+| `threadlinking_semantic_search` | Search threads by semantic similarity |
+| `threadlinking_analytics` | Get usage analytics and insights |
+| `threadlinking_export` | Export thread(s) in markdown, JSON, or timeline format |
+| `threadlinking_status` | Check available features and index status |
 
 ### Slash Commands
 

src/commands/attach.ts

@@ -10,6 +10,9 @@ export const attachCommand = new Command('attach')
 
     if (!result.success) {
       console.error(`Error: ${result.message}`);
+      if (result.message?.includes('not found')) {
+        console.error('Tip: Run `threadlinking list` to see available threads.');
+      }
       process.exitCode = 1;
       return;
     }

src/commands/create.ts

@@ -15,6 +15,9 @@ export const createCommand = new Command('create')
 
     if (!result.success) {
       console.error(`Error: ${result.message}`);
+      if (result.message?.includes('already exists')) {
+        console.error('Tip: Use `threadlinking show <thread>` to view it, or choose a different name.');
+      }
       process.exitCode = 1;
       return;
     }

src/commands/delete.ts

@@ -14,6 +14,7 @@ export const deleteCommand = new Command('delete')
       const meta = loadMetaIndex();
       if (!meta.threads[validatedId]) {
         console.error(`Thread ID '${validatedId}' not found.`);
+        console.error('Tip: Run `threadlinking list` to see available threads.');
         process.exitCode = 1;
         return;
       }

src/commands/detach.ts

@@ -10,6 +10,9 @@ export const detachCommand = new Command('detach')
 
     if (!result.success) {
       console.error(`Error: ${result.message}`);
+      if (result.message?.includes('not found')) {
+        console.error('Tip: Run `threadlinking list` to see available threads.');
+      }
       process.exitCode = 1;
       return;
     }

src/commands/explain.ts

@@ -11,6 +11,9 @@ export const explainCommand = new Command('explain')
 
     if (!result.success) {
       console.error(`Error: ${result.message}`);
+      if (result.message?.includes('not found')) {
+        console.error('Tip: Run `threadlinking list` to see available threads.');
+      }
       process.exitCode = 1;
       return;
     }

src/commands/init.ts

@@ -511,7 +511,8 @@ export const initCommand = new Command('init')
       }
       if (shouldInstall) {
         writeFileSync(GLOBAL_IGNORE_PATH, getDefaultIgnoreContent(), 'utf-8');
-        console.log('      \u2713 Ignore file created\n');
+        console.log('      \u2713 Ignore file created');
+        console.log('      Tip: Run `threadlinking prune` to remove ignored files from pending.\n');
       } else {
         console.log('      Skipped\n');
       }

src/commands/reindex.ts

@@ -17,6 +17,9 @@ export const reindexCommand = new Command('reindex')
           console.log(JSON.stringify({ error: result.message }, null, 2));
         } else {
           console.error(`Error: ${result.message}`);
+          if (result.message?.includes('No threads') || result.message?.includes('No content')) {
+            console.error('Tip: Create some snippets first with `threadlinking snippet <thread> "context"`');
+          }
         }
         process.exit(1);
       }