Add docid, line-numbers, handelize, and fix displayPath format

Features:
- Add short document IDs (docid) - first 6 chars of hash - to all search outputs
- Add --line-numbers CLI option and lineNumbers param for MCP tools
- Add handelize() function for token-friendly filenames (lowercase, special chars to dash, preserves extension)
- Convert triple underscore `___` to folder separator in filenames
- Change displayPath format to include collection name (collection/path)
- Make line-numbers default for MCP search snippets

Changes:
- store.ts: Add getDocid(), findDocumentByDocid(), handelize() functions
- formatter.ts: Add docid to all formatters, addLineNumbers() helper
- qmd.ts: Add --line-numbers option, use handelize during indexing
- mcp.ts: Remove resource listing, lineNumbers default for snippets
- Update all tests to expect new displayPath format and handelize behavior
- Update CLAUDE.md with docid documentation

All 274 tests pass.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

.beads/issues.jsonl

@@ -3,6 +3,7 @@
 {"id":"qmd-1xd","title":"Update tests for YAML-based collections","description":"Update all tests to use YAML config instead of DB collections. Update test helpers to create temporary YAML configs.","notes":"Test suite has been updated for YAML-based collections. 92 tests passing, 4 skipped, 10 failing.\n\nThe 4 skipped tests call getStatus() which has a bug (queries non-existent collections table).\n\nThe 10 failing tests are due to bugs in store.ts functions (findDocument, getDocumentBody, getDocument, findSimilarFiles, matchFilesByGlob) that need to be updated to use YAML configuration. These are production code bugs, not test bugs.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T09:54:53.349545-05:00","updated_at":"2025-12-13T11:37:16.935866-05:00","closed_at":"2025-12-13T11:37:16.935866-05:00","dependencies":[{"issue_id":"qmd-1xd","depends_on_id":"qmd-thw","type":"blocks","created_at":"2025-12-13T09:55:08.14305-05:00","created_by":"daemon"}]}
 {"id":"qmd-29c","title":"Move all database operations from qmd.ts to store.ts","description":"Currently qmd.ts has ~70 direct database operations (db.prepare, db.exec). All database operations should be moved to store.ts to improve separation of concerns. qmd.ts should only use high-level methods from store.ts that don't require direct SQL knowledge.","notes":"Phase 1 complete: Moved collection operations (listCollections, removeCollection, renameCollection) to store.ts. Created 4 subtasks for remaining work: document indexing, context management, embeddings, and cleanup operations.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T16:32:13.722223-05:00","updated_at":"2025-12-12T16:49:53.829124-05:00","closed_at":"2025-12-12T16:49:53.829124-05:00"}
 {"id":"qmd-2gn","title":"Fix store.ts functions to use YAML collections","description":"Update findDocument(), getDocumentBody(), getDocument(), findSimilarFiles(), matchFilesByGlob(), and getStatus() to use YAML collection configuration instead of querying the collections table. These functions currently fail because they try to query the non-existent collections table.","notes":"Fixed:\n- FTS schema (filepath, title, body columns) \n- getStatus() to use YAML collections\n- searchFTS() to not query collections table\n- findDocument() absolute path matching\n\nTest results: 93 passing (up from 92), 4 skipped, 9 failing\n\nRemaining failures:\n- getDocumentBody (2 tests)\n- getDocument (1 test)  \n- findSimilarFiles (2 tests)\n- matchFilesByGlob (1 test)\n- Integration/context tests (3 tests)","status":"in_progress","priority":1,"issue_type":"bug","created_at":"2025-12-13T11:37:22.706882-05:00","updated_at":"2025-12-13T12:32:38.336752-05:00"}
+{"id":"qmd-3qi","title":"Document docid hash usage in CLAUDE.md","description":"Update CLAUDE.md to document that short hash IDs (#abc123) work with get and multi-get commands. Include examples.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-15T12:54:30.634116-05:00","updated_at":"2025-12-15T13:12:38.91973-05:00","closed_at":"2025-12-15T13:12:38.91973-05:00","dependencies":[{"issue_id":"qmd-3qi","depends_on_id":"qmd-lwo","type":"parent-child","created_at":"2025-12-15T12:54:52.002856-05:00","created_by":"daemon"},{"issue_id":"qmd-3qi","depends_on_id":"qmd-apl","type":"blocks","created_at":"2025-12-15T12:54:52.066036-05:00","created_by":"daemon"}]}
 {"id":"qmd-3z9","title":"Design YAML schema and create collections.ts module","description":"Create collections.ts to manage YAML-based collection configuration at ~/.config/qmd/index.yml. Define TypeScript types for collections and contexts. Implement load/save functions with Bun's native YAML support.","design":"YAML structure:\n```yaml\n# Global context for all collections\nglobal_context: \"...\"\n\ncollections:\n  name:\n    path: /absolute/path\n    pattern: \"**/*.md\"\n    context:\n      \"/path/prefix\": \"Description\"\n      \"/\": \"Root context\"\n```\n\nTypeScript types:\n- Collection: { path, pattern, context }\n- CollectionConfig: { global_context?, collections }\n- Functions: loadConfig(), saveConfig(), getCollection(), listCollections()","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T09:54:52.586027-05:00","updated_at":"2025-12-13T09:56:57.309927-05:00","closed_at":"2025-12-13T09:56:57.309927-05:00"}
 {"id":"qmd-4ru","title":"Update document retrieval for new schema","description":"Functions like getDocument, findDocument, getMultipleDocuments need to work with new schema (path instead of filepath, content joins, virtual paths).","status":"closed","priority":0,"issue_type":"task","created_at":"2025-12-12T15:29:53.911881-05:00","updated_at":"2025-12-12T15:56:11.054888-05:00","closed_at":"2025-12-12T15:56:11.054888-05:00","dependencies":[{"issue_id":"qmd-4ru","depends_on_id":"qmd-ama","type":"discovered-from","created_at":"2025-12-12T15:29:53.912607-05:00","created_by":"daemon"}]}
 {"id":"qmd-4u4","title":"Move embedding/vector DB operations to store.ts","description":"Move vector indexing DB operations from vectorIndex() to store.ts. Create methods like getHashesForEmbedding(), insertEmbedding(), clearEmbeddings(), etc.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T16:36:21.683434-05:00","updated_at":"2025-12-12T16:42:40.42653-05:00","closed_at":"2025-12-12T16:42:40.42653-05:00","dependencies":[{"issue_id":"qmd-4u4","depends_on_id":"qmd-29c","type":"parent-child","created_at":"2025-12-12T16:37:02.944591-05:00","created_by":"daemon"}]}
@@ -12,6 +13,7 @@
 {"id":"qmd-9ua","title":"Update all qmd commands for YAML-based collections","description":"Update qmd.ts commands: collection add/list/remove/rename, status, update, ls. All should use collections.ts instead of store.ts collection functions.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T09:54:53.14644-05:00","updated_at":"2025-12-13T10:17:39.67707-05:00","closed_at":"2025-12-13T10:17:39.67707-05:00","dependencies":[{"issue_id":"qmd-9ua","depends_on_id":"qmd-u84","type":"blocks","created_at":"2025-12-13T09:55:07.893268-05:00","created_by":"daemon"},{"issue_id":"qmd-9ua","depends_on_id":"qmd-oxy","type":"blocks","created_at":"2025-12-13T09:55:07.942221-05:00","created_by":"daemon"}]}
 {"id":"qmd-afe","title":"implement qmd collection rename, which changes the global path prefix for the collection","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T15:55:54.779325-05:00","updated_at":"2025-12-12T16:29:24.153196-05:00","closed_at":"2025-12-12T16:29:24.153196-05:00"}
 {"id":"qmd-ama","title":"Refactor database system","description":"All documents should be stored as content addressable hash, e.g. hash, doc, created_at,\n┃ updated_at. documents should be a file system layer on top e.g. collection, path, hash,\n┃ created_at, updated_at. (collection,path)\n┃\n┃\n\n┃ All documents should be stored as content addressable hash, e.g. hash, doc, created_at,\n┃ updated_at. documents should be a file system layer on top e.g. collection_id, path, hash,\n┃ created_at, updated_at. (collection,path) is unique. There is also collection which stores PWD\n┃ + glob pattern, name (\\w+). Every document is treated as path qmd://collection.name/","notes":"## Completed\n- ✅ Implemented content-addressable storage (content table with hash→doc mapping)\n- ✅ Refactored documents table as file system layer (collection_id, path, hash)\n- ✅ Added collection names (e.g., \"pages\", \"journals\", \"archive\")\n- ✅ Implemented virtual paths (qmd://collection-name/path/to/file.md)\n- ✅ Added hierarchical context support (collection-scoped)\n- ✅ Successfully migrated existing database\n- ✅ Updated search functions to work with new schema\n- ✅ Updated indexing logic to use content-addressable storage\n- ✅ Orphaned content hash cleanup\n\n## Still TODO\n- Fix migration SQL to properly extract basename (currently needs manual fix)\n- Implement `qmd collection add . --name \u003cname\u003e --mask '**/*.md'`\n- Implement `qmd ls [path]` for exploring virtual file tree","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:57:35.497489-05:00","updated_at":"2025-12-12T15:39:48.879143-05:00","closed_at":"2025-12-12T15:39:48.879143-05:00"}
+{"id":"qmd-apl","title":"Support docid hash lookup in get and multi-get commands","description":"Allow get and multi-get to accept #hash (6 char) as a file identifier. Add lookup function to resolve short hash to full document path. Handle collisions gracefully.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T12:54:30.448466-05:00","updated_at":"2025-12-15T13:12:38.741755-05:00","closed_at":"2025-12-15T13:12:38.741755-05:00","dependencies":[{"issue_id":"qmd-apl","depends_on_id":"qmd-lwo","type":"parent-child","created_at":"2025-12-15T12:54:51.903613-05:00","created_by":"daemon"},{"issue_id":"qmd-apl","depends_on_id":"qmd-gbt","type":"blocks","created_at":"2025-12-15T12:54:52.031069-05:00","created_by":"daemon"}]}
 {"id":"qmd-bs8","title":"Update documentation for YAML configuration","description":"Update CLAUDE.md, README.md with new YAML configuration approach. Document index.yml format and manual editing instructions.","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T09:54:53.449584-05:00","updated_at":"2025-12-13T09:54:53.449584-05:00","dependencies":[{"issue_id":"qmd-bs8","depends_on_id":"qmd-1xd","type":"blocks","created_at":"2025-12-13T09:55:08.264615-05:00","created_by":"daemon"}]}
 {"id":"qmd-bx1","title":"Fix migration SQL for proper basename extraction","description":"The migration currently generates collection names incorrectly (uses full path instead of basename). Need to fix the SQL in migrateToContentAddressable to properly extract the directory basename.","status":"closed","priority":1,"issue_type":"bug","created_at":"2025-12-12T15:29:53.757723-05:00","updated_at":"2025-12-12T15:50:29.349134-05:00","closed_at":"2025-12-12T15:50:29.349134-05:00","dependencies":[{"issue_id":"qmd-bx1","depends_on_id":"qmd-ama","type":"discovered-from","created_at":"2025-12-12T15:29:53.758524-05:00","created_by":"daemon"}]}
 {"id":"qmd-c0m","title":"Comprehensive CLI review and consistency pass","description":"Review entire CLI command structure:\n- Consistent naming (add vs create, remove vs delete)\n- Consistent flag usage (--name, --mask, etc)\n- Update help text for all commands\n- Ensure virtual paths work everywhere\n- Test all commands end-to-end","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-12T15:29:38.083564-05:00","updated_at":"2025-12-12T16:06:51.544695-05:00","closed_at":"2025-12-12T16:06:51.544695-05:00"}
@@ -20,10 +22,15 @@
 {"id":"qmd-dmi","title":"Implement 'qmd collection' commands","description":"Add explicit collection management:\n- qmd collection add . --name \u003cname\u003e --mask '**/*.md'\n- qmd collection list\n- qmd collection remove \u003cname\u003e\n\nThis gives users control over collection names and patterns.","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-12T15:29:53.810666-05:00","updated_at":"2025-12-12T16:02:08.079158-05:00","closed_at":"2025-12-12T16:02:08.079158-05:00","dependencies":[{"issue_id":"qmd-dmi","depends_on_id":"qmd-ama","type":"discovered-from","created_at":"2025-12-12T15:29:53.811294-05:00","created_by":"daemon"}]}
 {"id":"qmd-dt1","title":"Redesign context add command for better usability","description":"Current issues: \n1. Virtual path qmd://journals/ is rejected as invalid\n2. Syntax is confusing - sometimes path is first arg, sometimes second\n3. Need to support collection root context (qmd://name/)\n4. Should be intuitive: qmd context add \u003cwhere\u003e \u003cwhat\u003e\nDesign goals:\n- Support qmd://collection/ for collection root context\n- Support qmd://collection/path for path-specific context\n- Clear, consistent syntax\n- Good error messages","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T09:39:19.764114-05:00","updated_at":"2025-12-13T09:41:38.467861-05:00","closed_at":"2025-12-13T09:41:38.467861-05:00"}
 {"id":"qmd-e2c","title":"Implement 'qmd ls' command","description":"Add command to explore virtual file tree:\n- qmd ls → list all collections\n- qmd ls \u003ccollection\u003e → list files in collection\n- qmd ls \u003ccollection\u003e/\u003cpath\u003e → list files under path\nOutput: flat list of qmd:// paths","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-12-12T15:29:53.859804-05:00","updated_at":"2025-12-12T15:55:12.777701-05:00","closed_at":"2025-12-12T15:55:12.777701-05:00","dependencies":[{"issue_id":"qmd-e2c","depends_on_id":"qmd-ama","type":"discovered-from","created_at":"2025-12-12T15:29:53.860535-05:00","created_by":"daemon"}]}
+{"id":"qmd-gbt","title":"Add docid field (first 6 chars of hash) to search results","description":"Include docid formatted as #hash[0:5] in all search output formats (CLI, JSON, CSV, Markdown, XML, files). The docid should be the first 6 characters of the document's SHA256 hash.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T12:54:30.388094-05:00","updated_at":"2025-12-15T13:12:27.553492-05:00","closed_at":"2025-12-15T13:12:27.553492-05:00","dependencies":[{"issue_id":"qmd-gbt","depends_on_id":"qmd-lwo","type":"parent-child","created_at":"2025-12-15T12:54:51.846848-05:00","created_by":"daemon"}]}
+{"id":"qmd-ht6","title":"Add --line-numbers CLI option for line-numbered output","description":"Add --line-numbers flag to CLI that formats output with line numbers: each line becomes \"{lineNum}: {content}\". Apply to get, multi-get, and search snippet output.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T12:54:30.51773-05:00","updated_at":"2025-12-15T13:12:38.810032-05:00","closed_at":"2025-12-15T13:12:38.810032-05:00","dependencies":[{"issue_id":"qmd-ht6","depends_on_id":"qmd-lwo","type":"parent-child","created_at":"2025-12-15T12:54:51.941635-05:00","created_by":"daemon"}]}
+{"id":"qmd-hw2","title":"Fix MCP resource listing and display paths","description":"Remove MCP resource listing, fix display paths to include collection name, handelize filenames during indexing, make line-numbers default for MCP snippets.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-16T12:00:02.815946-05:00","updated_at":"2025-12-16T12:26:17.690252-05:00","closed_at":"2025-12-16T12:26:17.690252-05:00"}
 {"id":"qmd-i3t","title":"Move context management DB operations to store.ts","description":"Move path_contexts INSERT/DELETE/SELECT operations from addContext(), listContexts(), removeContext() to store.ts. Create methods like insertContext(), deleteContext(), etc.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T16:36:21.561746-05:00","updated_at":"2025-12-12T16:48:57.271485-05:00","closed_at":"2025-12-12T16:48:57.271485-05:00","dependencies":[{"issue_id":"qmd-i3t","depends_on_id":"qmd-29c","type":"parent-child","created_at":"2025-12-12T16:37:02.866006-05:00","created_by":"daemon"}]}
 {"id":"qmd-j9z","title":"Add unit tests for content addressable hashes","description":"add same file from multiple places and verify that they both point at same hash. drop one collection and the content stays.","status":"closed","priority":3,"issue_type":"task","created_at":"2025-12-12T15:39:15.459504-05:00","updated_at":"2025-12-12T16:21:35.473776-05:00","closed_at":"2025-12-12T16:21:35.473776-05:00"}
 {"id":"qmd-kf8","title":"Move document indexing DB operations to store.ts","description":"Move INSERT/UPDATE/DELETE operations for documents and content tables from indexFiles() to store.ts. Create methods like insertDocument(), updateDocument(), deactivateDocuments(), etc.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T16:36:14.558702-05:00","updated_at":"2025-12-12T16:45:38.830978-05:00","closed_at":"2025-12-12T16:45:38.830978-05:00","dependencies":[{"issue_id":"qmd-kf8","depends_on_id":"qmd-29c","type":"parent-child","created_at":"2025-12-12T16:37:02.770251-05:00","created_by":"daemon"}]}
 {"id":"qmd-ltg","title":"look for missing context","description":"i ran qmd context list and thats only one bit of context, i had a lot more. i think the path matching isn't quite working right","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T16:42:57.324769-05:00","updated_at":"2025-12-12T17:16:27.835047-05:00","closed_at":"2025-12-12T17:16:27.835047-05:00"}
+{"id":"qmd-lwo","title":"Add short docid hash references and line numbers to output","description":"Add short 6-character hash IDs (docid #abc123) to search results and document retrieval, support these IDs in get/multi-get commands, and add --line-numbers option for line-numbered output.","status":"closed","priority":1,"issue_type":"epic","created_at":"2025-12-15T12:54:30.335556-05:00","updated_at":"2025-12-15T13:12:43.758557-05:00","closed_at":"2025-12-15T13:12:43.758557-05:00"}
+{"id":"qmd-mro","title":"Add lineNumbers boolean to MCP tools","description":"Add lineNumbers boolean parameter to MCP get, multi_get, and search tools. When true, return content with line numbers prefixed to each line.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-15T12:54:30.581671-05:00","updated_at":"2025-12-15T13:12:38.8682-05:00","closed_at":"2025-12-15T13:12:38.8682-05:00","dependencies":[{"issue_id":"qmd-mro","depends_on_id":"qmd-lwo","type":"parent-child","created_at":"2025-12-15T12:54:51.970363-05:00","created_by":"daemon"}]}
 {"id":"qmd-oxy","title":"Update context system to use YAML","description":"Remove path_contexts table. Implement context management in collections.ts. Update context add/list/rm commands to modify YAML file instead of database.","status":"closed","priority":1,"issue_type":"task","created_at":"2025-12-13T09:54:53.042839-05:00","updated_at":"2025-12-13T10:16:07.680285-05:00","closed_at":"2025-12-13T10:16:07.680285-05:00","dependencies":[{"issue_id":"qmd-oxy","depends_on_id":"qmd-3z9","type":"blocks","created_at":"2025-12-13T09:55:07.842488-05:00","created_by":"daemon"}]}
 {"id":"qmd-p1h","title":"Create collection add|remove","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-10T10:57:00.717864-05:00","updated_at":"2025-12-12T16:12:00.557003-05:00","closed_at":"2025-12-12T16:12:00.557003-05:00"}
 {"id":"qmd-rck","title":"move the source files to src/*, clean up teh directory","description":"","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-12T16:40:19.198119-05:00","updated_at":"2025-12-12T17:12:22.502746-05:00","closed_at":"2025-12-12T17:12:22.502746-05:00"}

CLAUDE.md

@@ -16,7 +16,7 @@ qmd context add [path] "text"     # Add context for path (defaults to current di
 qmd context list                  # List all contexts
 qmd context check                 # Check for collections/paths missing context
 qmd context rm <path>             # Remove context
-qmd get <file>                    # Get document content (fuzzy matches if not found)
+qmd get <file>                    # Get document by path or docid (#abc123)
 qmd multi-get <pattern>           # Get multiple docs by glob or comma-separated list
 qmd status                        # Show index status and collections
 qmd update [--pull]               # Re-index all collections (--pull: git pull first)
@@ -76,6 +76,24 @@ qmd context rm qmd://journals/2024
 qmd context rm /  # Remove global context
 ```
 
+## Document IDs (docid)
+
+Each document has a unique short ID (docid) - the first 6 characters of its content hash.
+Docids are shown in search results as `#abc123` and can be used with `get` and `multi-get`:
+
+```sh
+# Search returns docid in results
+qmd search "query" --json
+# Output: [{"docid": "#abc123", "score": 0.85, "file": "docs/readme.md", ...}]
+
+# Get document by docid
+qmd get "#abc123"
+qmd get abc123              # Leading # is optional
+
+# Docids also work in multi-get comma-separated lists
+qmd multi-get "#abc123, #def456"
+```
+
 ## Options
 
 ```sh
@@ -85,6 +103,7 @@ qmd context rm /  # Remove global context
 --all                    # Return all matches
 --min-score <num>        # Minimum score threshold
 --full                   # Show full document content
+--line-numbers           # Add line numbers to output
 
 # Multi-get specific
 -l <num>                 # Maximum lines per file

src/cli.test.ts

@@ -579,7 +579,8 @@ describe("CLI ls Command", () => {
   test("lists files in a collection", async () => {
     const { stdout, exitCode } = await runQmd(["ls", "fixtures"], { dbPath: localDbPath });
     expect(exitCode).toBe(0);
-    expect(stdout).toContain("qmd://fixtures/README.md");
+    // handelize converts to lowercase
+    expect(stdout).toContain("qmd://fixtures/readme.md");
     expect(stdout).toContain("qmd://fixtures/notes/meeting.md");
   });
 
@@ -588,8 +589,8 @@ describe("CLI ls Command", () => {
     expect(exitCode).toBe(0);
     expect(stdout).toContain("qmd://fixtures/notes/meeting.md");
     expect(stdout).toContain("qmd://fixtures/notes/ideas.md");
-    // Should not include files outside the prefix
-    expect(stdout).not.toContain("qmd://fixtures/README.md");
+    // Should not include files outside the prefix (handelize converts to lowercase)
+    expect(stdout).not.toContain("qmd://fixtures/readme.md");
   });
 
   test("lists files with virtual path", async () => {

src/formatter.ts

@@ -21,8 +21,31 @@ export type FormatOptions = {
   full?: boolean;       // Show full document content instead of snippet
   query?: string;       // Query for snippet extraction and highlighting
   useColor?: boolean;   // Enable terminal colors (default: false for non-CLI)
+  lineNumbers?: boolean;// Add line numbers to output
 };
 
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Add line numbers to text content.
+ * Each line becomes: "{lineNum}: {content}"
+ * @param text The text to add line numbers to
+ * @param startLine Optional starting line number (default: 1)
+ */
+export function addLineNumbers(text: string, startLine: number = 1): string {
+  const lines = text.split('\n');
+  return lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
+}
+
+/**
+ * Extract short docid from a full hash (first 6 characters).
+ */
+export function getDocid(hash: string): string {
+  return hash.slice(0, 6);
+}
+
 // =============================================================================
 // Escape Helpers
 // =============================================================================
@@ -56,14 +79,27 @@ export function searchResultsToJson(
   results: SearchResult[],
   opts: FormatOptions = {}
 ): string {
-  const output = results.map(row => ({
-    score: Math.round(row.score * 100) / 100,
-    file: row.displayPath,
-    title: row.title,
-    ...(row.context && { context: row.context }),
-    ...(opts.full && { body: row.body }),
-    ...(!opts.full && opts.query && { snippet: extractSnippet(row.body, opts.query, 300, row.chunkPos).snippet }),
-  }));
+  const query = opts.query || "";
+  const output = results.map(row => {
+    const bodyStr = row.body || "";
+    let body = opts.full ? bodyStr : undefined;
+    let snippet = !opts.full ? extractSnippet(bodyStr, query, 300, row.chunkPos).snippet : undefined;
+
+    if (opts.lineNumbers) {
+      if (body) body = addLineNumbers(body);
+      if (snippet) snippet = addLineNumbers(snippet);
+    }
+
+    return {
+      docid: `#${row.docid}`,
+      score: Math.round(row.score * 100) / 100,
+      file: row.displayPath,
+      title: row.title,
+      ...(row.context && { context: row.context }),
+      ...(body && { body }),
+      ...(snippet && { snippet }),
+    };
+  });
   return JSON.stringify(output, null, 2);
 }
 
@@ -75,11 +111,16 @@ export function searchResultsToCsv(
   opts: FormatOptions = {}
 ): string {
   const query = opts.query || "";
-  const header = "score,file,title,context,line,snippet";
+  const header = "docid,score,file,title,context,line,snippet";
   const rows = results.map(row => {
-    const { line, snippet } = extractSnippet(row.body, query, 500, row.chunkPos);
-    const content = opts.full ? row.body : snippet;
+    const bodyStr = row.body || "";
+    const { line, snippet } = extractSnippet(bodyStr, query, 500, row.chunkPos);
+    let content = opts.full ? bodyStr : snippet;
+    if (opts.lineNumbers && content) {
+      content = addLineNumbers(content);
+    }
     return [
+      `#${row.docid}`,
       row.score.toFixed(4),
       escapeCSV(row.displayPath),
       escapeCSV(row.title),
@@ -92,12 +133,12 @@ export function searchResultsToCsv(
 }
 
 /**
- * Format search results as simple files list (score,filepath,context)
+ * Format search results as simple files list (docid,score,filepath,context)
  */
 export function searchResultsToFiles(results: SearchResult[]): string {
   return results.map(row => {
     const ctx = row.context ? `,"${row.context.replace(/"/g, '""')}"` : "";
-    return `${row.score.toFixed(2)},${row.displayPath}${ctx}`;
+    return `#${row.docid},${row.score.toFixed(2)},${row.displayPath}${ctx}`;
   }).join("\n");
 }
 
@@ -111,12 +152,17 @@ export function searchResultsToMarkdown(
   const query = opts.query || "";
   return results.map(row => {
     const heading = row.title || row.displayPath;
+    const bodyStr = row.body || "";
+    let content: string;
     if (opts.full) {
-      return `---\n# ${heading}\n\n${row.body}\n`;
+      content = bodyStr;
     } else {
-      const { snippet } = extractSnippet(row.body, query, 500, row.chunkPos);
-      return `---\n# ${heading}\n\n${snippet}\n`;
+      content = extractSnippet(bodyStr, query, 500, row.chunkPos).snippet;
     }
+    if (opts.lineNumbers) {
+      content = addLineNumbers(content);
+    }
+    return `---\n# ${heading}\n\n**docid:** \`#${row.docid}\`\n\n${content}\n`;
   }).join("\n");
 }
 
@@ -130,8 +176,12 @@ export function searchResultsToXml(
   const query = opts.query || "";
   const items = results.map(row => {
     const titleAttr = row.title ? ` title="${escapeXml(row.title)}"` : "";
-    const content = opts.full ? row.body : extractSnippet(row.body, query, 500, row.chunkPos).snippet;
-    return `<file name="${escapeXml(row.displayPath)}"${titleAttr}>\n${escapeXml(content)}\n</file>`;
+    const bodyStr = row.body || "";
+    let content = opts.full ? bodyStr : extractSnippet(bodyStr, query, 500, row.chunkPos).snippet;
+    if (opts.lineNumbers) {
+      content = addLineNumbers(content);
+    }
+    return `<file docid="#${row.docid}" name="${escapeXml(row.displayPath)}"${titleAttr}>\n${escapeXml(content)}\n</file>`;
   });
   return items.join("\n\n");
 }
@@ -140,11 +190,11 @@ export function searchResultsToXml(
  * Format search results for MCP (simpler CSV format with pre-extracted snippets)
  */
 export function searchResultsToMcpCsv(
-  results: { file: string; title: string; score: number; context: string | null; snippet: string }[]
+  results: { docid: string; file: string; title: string; score: number; context: string | null; snippet: string }[]
 ): string {
-  const header = "file,title,score,context,snippet";
+  const header = "docid,file,title,score,context,snippet";
   const rows = results.map(r =>
-    [r.file, r.title, r.score, r.context || "", r.snippet].map(escapeCSV).join(",")
+    [`#${r.docid}`, r.file, r.title, r.score, r.context || "", r.snippet].map(escapeCSV).join(",")
   );
   return [header, ...rows].join("\n");
 }

src/mcp.test.ts

@@ -307,7 +307,7 @@ describe("MCP Server", () => {
     test("returns results for matching query", () => {
       const results = searchFTS(testDb, "readme", 10);
       expect(results.length).toBeGreaterThan(0);
-      expect(results[0].displayPath).toBe("readme.md");
+      expect(results[0].displayPath).toBe("docs/readme.md");
     });
 
     test("returns empty for non-matching query", () => {
@@ -449,7 +449,7 @@ describe("MCP Server", () => {
       const result = getDocument(testDb, "readme.md");
       expect("error" in result).toBe(false);
       if (!("error" in result)) {
-        expect(result.displayPath).toBe("readme.md");
+        expect(result.displayPath).toBe("docs/readme.md");
         expect(result.body).toContain("Project README");
       }
     });
@@ -527,8 +527,8 @@ describe("MCP Server", () => {
       const { files, errors } = getMultipleDocuments(testDb, "meetings/*.md");
       expect(errors.length).toBe(0);
       expect(files.length).toBe(2);
-      expect(files.some(f => f.displayPath === "meetings/meeting-2024-01.md")).toBe(true);
-      expect(files.some(f => f.displayPath === "meetings/meeting-2024-02.md")).toBe(true);
+      expect(files.some(f => f.displayPath === "docs/meetings/meeting-2024-01.md")).toBe(true);
+      expect(files.some(f => f.displayPath === "docs/meetings/meeting-2024-02.md")).toBe(true);
     });
 
     test("retrieves documents by comma-separated list", () => {
@@ -546,7 +546,7 @@ describe("MCP Server", () => {
 
     test("skips files larger than maxBytes", () => {
       const { files } = getMultipleDocuments(testDb, "*.md", undefined, 1000); // 1KB limit
-      const largeFile = files.find(f => f.displayPath === "large-file.md");
+      const largeFile = files.find(f => f.displayPath === "docs/large-file.md");
       expect(largeFile).toBeDefined();
       expect(largeFile?.skipped).toBe(true);
       if (largeFile?.skipped) {
@@ -908,7 +908,7 @@ QMD is your on-device search engine for markdown knowledge bases.`;
           mimeType: "text/markdown",
           text: result.body,
         };
-        expect(resource.name).toBe("readme.md");
+        expect(resource.name).toBe("docs/readme.md");
         expect(resource.title).toBe("Project README");
         expect(resource.mimeType).toBe("text/markdown");
       }

src/mcp.ts

@@ -27,6 +27,7 @@ import type { RankedResult } from "./store.js";
 // =============================================================================
 
 type SearchResultItem = {
+  docid: string;  // Short docid (#abc123) for quick reference
   file: string;
   title: string;
   score: number;
@@ -69,11 +70,20 @@ function formatSearchSummary(results: SearchResultItem[], query: string): string
   }
   const lines = [`Found ${results.length} result${results.length === 1 ? '' : 's'} for "${query}":\n`];
   for (const r of results) {
-    lines.push(`${Math.round(r.score * 100)}% ${r.file} - ${r.title}`);
+    lines.push(`${r.docid} ${Math.round(r.score * 100)}% ${r.file} - ${r.title}`);
   }
   return lines.join('\n');
 }
 
+/**
+ * Add line numbers to text content.
+ * Each line becomes: "{lineNum}: {content}"
+ */
+function addLineNumbers(text: string, startLine: number = 1): string {
+  const lines = text.split('\n');
+  return lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
+}
+
 // =============================================================================
 // MCP Server
 // =============================================================================
@@ -88,35 +98,16 @@ export async function startMcpServer(): Promise<void> {
   });
 
   // ---------------------------------------------------------------------------
-  // Resource: qmd://{path}
+  // Resource: qmd://{path} - read-only access to documents by path
+  // Note: No list() - documents are discovered via search tools
   // ---------------------------------------------------------------------------
 
   server.registerResource(
     "document",
-    new ResourceTemplate("qmd://{+path}", {
-      list: async () => {
-        // List all indexed documents
-        const docs = store.db.prepare(`
-          SELECT path, title, collection
-          FROM documents
-          WHERE active = 1
-          ORDER BY modified_at DESC
-          LIMIT 1000
-        `).all() as { path: string; title: string; collection: string }[];
-
-        return {
-          resources: docs.map(doc => ({
-            uri: `qmd://${doc.collection}/${encodeQmdPath(doc.path)}`,
-            name: `${doc.collection}/${doc.path}`,
-            title: doc.title || doc.path,
-            mimeType: "text/markdown",
-          })),
-        };
-      },
-    }),
+    new ResourceTemplate("qmd://{+path}", {}),
     {
       title: "QMD Document",
-      description: "A markdown document from your QMD knowledge base",
+      description: "A markdown document from your QMD knowledge base. Use search tools to discover documents.",
       mimeType: "text/markdown",
     },
     async (uri, { path }) => {
@@ -155,7 +146,7 @@ export async function startMcpServer(): Promise<void> {
       const virtualPath = `qmd://${doc.collection}/${doc.path}`;
       const context = store.getContextForFile(virtualPath);
 
-      let text = doc.body;
+      let text = addLineNumbers(doc.body);  // Default to line numbers
       if (context) {
         text = `<!-- Context: ${context} -->\n\n` + text;
       }
@@ -281,13 +272,17 @@ You can also access documents directly via the \`qmd://\` URI scheme:
         .filter(r => !collection || r.collectionName === collection);
       const filtered: SearchResultItem[] = results
         .filter(r => r.score >= (minScore || 0))
-        .map(r => ({
-          file: r.displayPath,
-          title: r.title,
-          score: Math.round(r.score * 100) / 100,
-          context: store.getContextForFile(r.file),
-          snippet: extractSnippet(r.body, query, 300, r.chunkPos).snippet,
-        }));
+        .map(r => {
+          const { line, snippet } = extractSnippet(r.body || "", query, 300, r.chunkPos);
+          return {
+            docid: `#${r.docid}`,
+            file: r.displayPath,
+            title: r.title,
+            score: Math.round(r.score * 100) / 100,
+            context: store.getContextForFile(r.filepath),
+            snippet: addLineNumbers(snippet, line),  // Default to line numbers
+          };
+        });
 
       return {
         content: [{ type: "text", text: formatSearchSummary(filtered, query) }],
@@ -325,14 +320,14 @@ You can also access documents directly via the \`qmd://\` URI scheme:
       const queries = await store.expandQuery(query, DEFAULT_QUERY_MODEL);
 
       // Collect results (filter by collection after search)
-      const allResults = new Map<string, { file: string; displayPath: string; title: string; body: string; score: number }>();
+      const allResults = new Map<string, { file: string; displayPath: string; title: string; body: string; score: number; docid: string }>();
       for (const q of queries) {
         const vecResults = await store.searchVec(q, DEFAULT_EMBED_MODEL, limit || 10)
           .then(results => results.filter(r => !collection || r.collectionName === collection));
         for (const r of vecResults) {
-          const existing = allResults.get(r.file);
+          const existing = allResults.get(r.filepath);
           if (!existing || r.score > existing.score) {
-            allResults.set(r.file, { file: r.file, displayPath: r.displayPath, title: r.title, body: r.body, score: r.score });
+            allResults.set(r.filepath, { file: r.filepath, displayPath: r.displayPath, title: r.title, body: r.body || "", score: r.score, docid: r.docid });
           }
         }
       }
@@ -341,13 +336,17 @@ You can also access documents directly via the \`qmd://\` URI scheme:
         .sort((a, b) => b.score - a.score)
         .slice(0, limit || 10)
         .filter(r => r.score >= (minScore || 0.3))
-        .map(r => ({
-          file: r.displayPath,
-          title: r.title,
-          score: Math.round(r.score * 100) / 100,
-          context: store.getContextForFile(r.file),
-          snippet: extractSnippet(r.body, query, 300).snippet,
-        }));
+        .map(r => {
+          const { line, snippet } = extractSnippet(r.body || "", query, 300);
+          return {
+            docid: `#${r.docid}`,
+            file: r.displayPath,
+            title: r.title,
+            score: Math.round(r.score * 100) / 100,
+            context: store.getContextForFile(r.file),
+            snippet: addLineNumbers(snippet, line),  // Default to line numbers
+          };
+        });
 
       return {
         content: [{ type: "text", text: formatSearchSummary(filtered, query) }],
@@ -378,19 +377,22 @@ You can also access documents directly via the \`qmd://\` URI scheme:
 
       // Collect ranked lists (filter by collection after search)
       const rankedLists: RankedResult[][] = [];
+      const docidMap = new Map<string, string>(); // filepath -> docid
       const hasVectors = !!store.db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
 
       for (const q of queries) {
         const ftsResults = store.searchFTS(q, 20)
           .filter(r => !collection || r.collectionName === collection);
         if (ftsResults.length > 0) {
-          rankedLists.push(ftsResults.map(r => ({ file: r.file, displayPath: r.displayPath, title: r.title, body: r.body, score: r.score })));
+          for (const r of ftsResults) docidMap.set(r.filepath, r.docid);
+          rankedLists.push(ftsResults.map(r => ({ file: r.filepath, displayPath: r.displayPath, title: r.title, body: r.body || "", score: r.score })));
         }
         if (hasVectors) {
           const vecResults = await store.searchVec(q, DEFAULT_EMBED_MODEL, 20)
             .then(results => results.filter(r => !collection || r.collectionName === collection));
           if (vecResults.length > 0) {
-            rankedLists.push(vecResults.map(r => ({ file: r.file, displayPath: r.displayPath, title: r.title, body: r.body, score: r.score })));
+            for (const r of vecResults) docidMap.set(r.filepath, r.docid);
+            rankedLists.push(vecResults.map(r => ({ file: r.filepath, displayPath: r.displayPath, title: r.title, body: r.body || "", score: r.score })));
           }
         }
       }
@@ -420,12 +422,14 @@ You can also access documents directly via the \`qmd://\` URI scheme:
         const rrfScore = 1 / rrfRank;
         const blendedScore = rrfWeight * rrfScore + (1 - rrfWeight) * r.score;
         const candidate = candidateMap.get(r.file);
+        const { line, snippet } = extractSnippet(candidate?.body || "", query, 300);
         return {
+          docid: `#${docidMap.get(r.file) || ""}`,
           file: candidate?.displayPath || "",
           title: candidate?.title || "",
           score: Math.round(blendedScore * 100) / 100,
           context: store.getContextForFile(r.file),
-          snippet: extractSnippet(candidate?.body || "", query, 300).snippet,
+          snippet: addLineNumbers(snippet, line),  // Default to line numbers
         };
       }).filter(r => r.score >= (minScore || 0)).slice(0, limit || 10);
 
@@ -444,14 +448,15 @@ You can also access documents directly via the \`qmd://\` URI scheme:
     "get",
     {
       title: "Get Document",
-      description: "Retrieve the full content of a document by its file path. Use paths from search results. Suggests similar files if not found.",
+      description: "Retrieve the full content of a document by its file path or docid. Use paths or docids (#abc123) from search results. Suggests similar files if not found.",
       inputSchema: {
-        file: z.string().describe("File path from search results (e.g., 'pages/meeting.md' or 'pages/meeting.md:100' to start at line 100)"),
+        file: z.string().describe("File path or docid from search results (e.g., 'pages/meeting.md', '#abc123', or 'pages/meeting.md:100' to start at line 100)"),
         fromLine: z.number().optional().describe("Start from this line number (1-indexed)"),
         maxLines: z.number().optional().describe("Maximum number of lines to return"),
+        lineNumbers: z.boolean().optional().default(false).describe("Add line numbers to output (format: 'N: content')"),
       },
     },
-    async ({ file, fromLine, maxLines }) => {
+    async ({ file, fromLine, maxLines, lineNumbers }) => {
       const result = store.getDocument(file, fromLine, maxLines);
 
       if ("error" in result) {
@@ -466,6 +471,10 @@ You can also access documents directly via the \`qmd://\` URI scheme:
       }
 
       let text = result.body;
+      if (lineNumbers) {
+        const startLine = fromLine || 1;
+        text = addLineNumbers(text, startLine);
+      }
       if (result.context) {
         text = `<!-- Context: ${result.context} -->\n\n` + text;
       }
@@ -498,9 +507,10 @@ You can also access documents directly via the \`qmd://\` URI scheme:
         pattern: z.string().describe("Glob pattern or comma-separated list of file paths"),
         maxLines: z.number().optional().describe("Maximum lines per file"),
         maxBytes: z.number().optional().default(10240).describe("Skip files larger than this (default: 10240 = 10KB)"),
+        lineNumbers: z.boolean().optional().default(false).describe("Add line numbers to output (format: 'N: content')"),
       },
     },
-    async ({ pattern, maxLines, maxBytes }) => {
+    async ({ pattern, maxLines, maxBytes, lineNumbers }) => {
       const { files, errors } = store.getMultipleDocuments(pattern, maxLines, maxBytes || DEFAULT_MULTI_GET_MAX_BYTES);
 
       if (files.length === 0 && errors.length === 0) {
@@ -526,6 +536,9 @@ You can also access documents directly via the \`qmd://\` URI scheme:
         }
 
         let text = file.body;
+        if (lineNumbers) {
+          text = addLineNumbers(text);
+        }
         if (file.context) {
           text = `<!-- Context: ${file.context} -->\n\n` + text;
         }

src/qmd.ts

@@ -61,6 +61,7 @@ import {
   vacuumDatabase,
   getCollectionsWithoutContext,
   getTopLevelPathsWithoutContext,
+  handelize,
   OLLAMA_URL,
   DEFAULT_EMBED_MODEL,
   DEFAULT_QUERY_MODEL,
@@ -1448,7 +1449,7 @@ async function indexFiles(pwd?: string, globPattern: string = DEFAULT_GLOB, coll
 
   for (const relativeFile of files) {
     const filepath = getRealPath(resolve(resolvedPwd, relativeFile));
-    const path = relativeFile; // Use relative path as-is
+    const path = handelize(relativeFile); // Normalize path for token-friendliness
     seenPaths.add(path);
 
     const content = await Bun.file(filepath).text();
@@ -1751,6 +1752,7 @@ type OutputOptions = {
   minScore: number;
   all?: boolean;
   collection?: string;  // Filter by collection name (pwd suffix match)
+  lineNumbers?: boolean; // Add line numbers to output
 };
 
 // Extract snippet with more context lines for CLI display
@@ -1824,7 +1826,13 @@ function shortPath(dirpath: string): string {
   return dirpath;
 }
 
-function outputResults(results: { file: string; displayPath: string; title: string; body: string; score: number; context?: string | null; chunkPos?: number }[], query: string, opts: OutputOptions): void {
+// Add line numbers to text content
+function addLineNumbers(text: string, startLine: number = 1): string {
+  const lines = text.split('\n');
+  return lines.map((line, i) => `${startLine + i}: ${line}`).join('\n');
+}
+
+function outputResults(results: { file: string; displayPath: string; title: string; body: string; score: number; context?: string | null; chunkPos?: number; hash?: string; docid?: string }[], query: string, opts: OutputOptions): void {
   const filtered = results.filter(r => r.score >= opts.minScore).slice(0, opts.limit);
 
   if (filtered.length === 0) {
@@ -1834,30 +1842,43 @@ function outputResults(results: { file: string; displayPath: string; title: stri
 
   if (opts.format === "json") {
     // JSON output for LLM consumption
-    const output = filtered.map(row => ({
-      score: Math.round(row.score * 100) / 100,
-      file: row.displayPath,
-      title: row.title,
-      ...(row.context && { context: row.context }),
-      ...(opts.full && { body: row.body }),
-      ...(!opts.full && { snippet: extractSnippet(row.body, query, 300, row.chunkPos).snippet }),
-    }));
+    const output = filtered.map(row => {
+      const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : undefined);
+      let body = opts.full ? row.body : undefined;
+      let snippet = !opts.full ? extractSnippet(row.body, query, 300, row.chunkPos).snippet : undefined;
+      if (opts.lineNumbers) {
+        if (body) body = addLineNumbers(body);
+        if (snippet) snippet = addLineNumbers(snippet);
+      }
+      return {
+        ...(docid && { docid: `#${docid}` }),
+        score: Math.round(row.score * 100) / 100,
+        file: row.displayPath,
+        title: row.title,
+        ...(row.context && { context: row.context }),
+        ...(body && { body }),
+        ...(snippet && { snippet }),
+      };
+    });
     console.log(JSON.stringify(output, null, 2));
   } else if (opts.format === "files") {
-    // Simple score,filepath,context output
+    // Simple docid,score,filepath,context output
     for (const row of filtered) {
+      const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : "");
       const ctx = row.context ? `,"${row.context.replace(/"/g, '""')}"` : "";
-      console.log(`${row.score.toFixed(2)},${row.displayPath}${ctx}`);
+      console.log(`#${docid},${row.score.toFixed(2)},${row.displayPath}${ctx}`);
     }
   } else if (opts.format === "cli") {
     for (let i = 0; i < filtered.length; i++) {
       const row = filtered[i];
       const { line, snippet, hasMatch } = extractSnippetWithContext(row.body, query, 2, row.chunkPos);
+      const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : undefined);
 
-      // Line 1: filepath
+      // Line 1: filepath with docid
       const path = row.displayPath;
       const lineInfo = hasMatch ? `:${line}` : "";
-      console.log(`${c.cyan}${path}${c.dim}${lineInfo}${c.reset}`);
+      const docidStr = docid ? ` ${c.dim}#${docid}${c.reset}` : "";
+      console.log(`${c.cyan}${path}${c.dim}${lineInfo}${c.reset}${docidStr}`);
 
       // Line 2: Title (if available)
       if (row.title) {
@@ -1875,7 +1896,8 @@ function outputResults(results: { file: string; displayPath: string; title: stri
       console.log();
 
       // Snippet with highlighting (no leading | chars for better word wrap)
-      const highlighted = highlightTerms(snippet, query);
+      let displaySnippet = opts.lineNumbers ? addLineNumbers(snippet, line) : snippet;
+      const highlighted = highlightTerms(displaySnippet, query);
       console.log(highlighted);
 
       // Double empty line between results
@@ -1884,30 +1906,35 @@ function outputResults(results: { file: string; displayPath: string; title: stri
   } else if (opts.format === "md") {
     for (const row of filtered) {
       const heading = row.title || row.displayPath;
-      if (opts.full) {
-        console.log(`---\n# ${heading}\n\n${row.body}\n`);
-      } else {
-        const { snippet } = extractSnippet(row.body, query, 500, row.chunkPos);
-        console.log(`---\n# ${heading}\n\n${snippet}\n`);
+      const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : undefined);
+      let content = opts.full ? row.body : extractSnippet(row.body, query, 500, row.chunkPos).snippet;
+      if (opts.lineNumbers) {
+        content = addLineNumbers(content);
       }
+      const docidLine = docid ? `\n**docid:** \`#${docid}\`\n` : "";
+      console.log(`---\n# ${heading}${docidLine}\n${content}\n`);
     }
   } else if (opts.format === "xml") {
     for (const row of filtered) {
       const titleAttr = row.title ? ` title="${row.title.replace(/"/g, '&quot;')}"` : "";
-      if (opts.full) {
-        console.log(`<file name="${row.displayPath}"${titleAttr}>\n${row.body}\n</file>\n`);
-      } else {
-        const { snippet } = extractSnippet(row.body, query, 500, row.chunkPos);
-        console.log(`<file name="${row.displayPath}"${titleAttr}>\n${snippet}\n</file>\n`);
+      const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : "");
+      let content = opts.full ? row.body : extractSnippet(row.body, query, 500, row.chunkPos).snippet;
+      if (opts.lineNumbers) {
+        content = addLineNumbers(content);
       }
+      console.log(`<file docid="#${docid}" name="${row.displayPath}"${titleAttr}>\n${content}\n</file>\n`);
     }
   } else {
     // CSV format
-    console.log("score,file,title,line,snippet");
+    console.log("docid,score,file,title,line,snippet");
     for (const row of filtered) {
       const { line, snippet } = extractSnippet(row.body, query, 500, row.chunkPos);
-      const content = opts.full ? row.body : snippet;
-      console.log(`${row.score.toFixed(4)},${escapeCSV(row.displayPath)},${escapeCSV(row.title)},${line},${escapeCSV(content)}`);
+      let content = opts.full ? row.body : snippet;
+      if (opts.lineNumbers) {
+        content = addLineNumbers(content, line);
+      }
+      const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : "");
+      console.log(`#${docid},${row.score.toFixed(4)},${escapeCSV(row.displayPath)},${escapeCSV(row.title)},${line},${escapeCSV(content)}`);
     }
   }
 }
@@ -2204,6 +2231,7 @@ function parseCLI() {
       l: { type: "string" },  // max lines
       from: { type: "string" },  // start line
       "max-bytes": { type: "string" },  // max bytes for multi-get
+      "line-numbers": { type: "boolean" },  // add line numbers to output
     },
     allowPositionals: true,
     strict: false, // Allow unknown options to pass through
@@ -2234,6 +2262,7 @@ function parseCLI() {
     minScore: values["min-score"] ? parseFloat(values["min-score"]) || 0 : 0,
     all: isAll,
     collection: values.collection as string | undefined,
+    lineNumbers: values["line-numbers"] || false,
   };
 
   return {
@@ -2274,7 +2303,8 @@ function showHelp(): void {
   console.log("  --all                      - Return all matches (use with --min-score to filter)");
   console.log("  --min-score <num>          - Minimum similarity score");
   console.log("  --full                     - Output full document instead of snippet");
-  console.log("  --files                    - Output score,filepath,context (default: 20 results)");
+  console.log("  --line-numbers             - Add line numbers to output");
+  console.log("  --files                    - Output docid,score,filepath,context (default: 20 results)");
   console.log("  --json                     - JSON output with snippets (default: 20 results)");
   console.log("  --csv                      - CSV output with snippets");
   console.log("  --md                       - Markdown output");

src/store.test.ts

@@ -27,6 +27,7 @@ import {
   reciprocalRankFusion,
   extractSnippet,
   getCacheKey,
+  handelize,
   OLLAMA_URL,
   type Store,
   type DocumentResult,
@@ -356,6 +357,97 @@ describe("Path Utilities", () => {
   });
 });
 
+// =============================================================================
+// Handelize Tests - path normalization for token-friendly filenames
+// =============================================================================
+
+describe("handelize", () => {
+  test("converts to lowercase", () => {
+    expect(handelize("README.md")).toBe("readme.md");
+    expect(handelize("MyFile.MD")).toBe("myfile.md");
+  });
+
+  test("preserves folder structure", () => {
+    expect(handelize("a/b/c/d.md")).toBe("a/b/c/d.md");
+    expect(handelize("docs/api/README.md")).toBe("docs/api/readme.md");
+  });
+
+  test("replaces non-word characters with dash", () => {
+    expect(handelize("hello world.md")).toBe("hello-world.md");
+    expect(handelize("file (1).md")).toBe("file-1.md");
+    expect(handelize("foo@bar#baz.md")).toBe("foo-bar-baz.md");
+  });
+
+  test("collapses multiple special chars into single dash", () => {
+    expect(handelize("hello   world.md")).toBe("hello-world.md");
+    expect(handelize("foo---bar.md")).toBe("foo-bar.md");
+    expect(handelize("a  -  b.md")).toBe("a-b.md");
+  });
+
+  test("removes leading and trailing dashes from segments", () => {
+    expect(handelize("-hello-.md")).toBe("hello.md");
+    expect(handelize("--test--.md")).toBe("test.md");
+    expect(handelize("a/-b-/c.md")).toBe("a/b/c.md");
+  });
+
+  test("converts triple underscore to folder separator", () => {
+    expect(handelize("foo___bar.md")).toBe("foo/bar.md");
+    expect(handelize("notes___2025___january.md")).toBe("notes/2025/january.md");
+    expect(handelize("a/b___c/d.md")).toBe("a/b/c/d.md");
+  });
+
+  test("handles complex real-world meeting notes", () => {
+    // Example: "Money Movement Licensing Review - 2025／11／19 10:25 EST - Notes by Gemini.md"
+    const complexName = "Money Movement Licensing Review - 2025／11／19 10:25 EST - Notes by Gemini.md";
+    const result = handelize(complexName);
+    expect(result).toBe("money-movement-licensing-review-2025-11-19-10-25-est-notes-by-gemini.md");
+    expect(result).not.toContain(" ");
+    expect(result).not.toContain("／");
+    expect(result).not.toContain(":");
+  });
+
+  test("handles unicode characters", () => {
+    // Pure unicode with no alphanumerics throws error
+    expect(() => handelize("日本語.md")).toThrow("no valid filename content");
+    // Mixed unicode/ascii preserves the ascii parts
+    expect(handelize("café-notes.md")).toBe("caf-notes.md");
+    expect(handelize("naïve.md")).toBe("na-ve.md");
+    expect(handelize("日本語-notes.md")).toBe("notes.md");
+  });
+
+  test("handles dates and times in filenames", () => {
+    expect(handelize("meeting-2025-01-15.md")).toBe("meeting-2025-01-15.md");
+    expect(handelize("notes 2025/01/15.md")).toBe("notes-2025/01/15.md");
+    expect(handelize("call_10:30_AM.md")).toBe("call-10-30-am.md");
+  });
+
+  test("handles special project naming patterns", () => {
+    expect(handelize("PROJECT_ABC_v2.0.md")).toBe("project-abc-v2-0.md");
+    expect(handelize("[WIP] Feature Request.md")).toBe("wip-feature-request.md");
+    expect(handelize("(DRAFT) Proposal v1.md")).toBe("draft-proposal-v1.md");
+  });
+
+  test("filters out empty segments", () => {
+    expect(handelize("a//b/c.md")).toBe("a/b/c.md");
+    expect(handelize("/a/b/")).toBe("a/b");
+    expect(handelize("///test///")).toBe("test");
+  });
+
+  test("throws error for invalid inputs", () => {
+    expect(() => handelize("")).toThrow("path cannot be empty");
+    expect(() => handelize("   ")).toThrow("path cannot be empty");
+    expect(() => handelize(".md")).toThrow("no valid filename content");
+    expect(() => handelize("...")).toThrow("no valid filename content");
+    expect(() => handelize("___")).toThrow("no valid filename content");
+  });
+
+  test("handles minimal valid inputs", () => {
+    expect(handelize("a")).toBe("a");
+    expect(handelize("1")).toBe("1");
+    expect(handelize("a.md")).toBe("a.md");
+  });
+});
+
 // =============================================================================
 // Store Creation Tests
 // =============================================================================
@@ -678,7 +770,7 @@ describe("FTS Search", () => {
 
     const results = store.searchFTS("fox", 10);
     expect(results.length).toBeGreaterThan(0);
-    expect(results[0].displayPath).toBe("test/doc1.md");
+    expect(results[0].displayPath).toBe(`${collectionName}/test/doc1.md`);
     expect(results[0].filepath).toBe(`qmd://${collectionName}/test/doc1.md`);
     expect(results[0].source).toBe("fts");
 
@@ -709,7 +801,7 @@ describe("FTS Search", () => {
     // Both documents contain "fox" in the body now, so we should get 2 results
     expect(results.length).toBe(2);
     // Title/name match should rank higher due to BM25 weights
-    expect(results[0].displayPath).toBe("test/title.md");
+    expect(results[0].displayPath).toBe(`${collectionName}/test/title.md`);
 
     await cleanupTestDb(store);
   });
@@ -800,7 +892,7 @@ describe("FTS Search", () => {
 
     const results = store.searchFTS("findme", 10);
     expect(results).toHaveLength(1);
-    expect(results[0].displayPath).toBe("test/active.md");
+    expect(results[0].displayPath).toBe(`${collectionName}/test/active.md`);
     expect(results[0].filepath).toBe(`qmd://${collectionName}/test/active.md`);
 
     await cleanupTestDb(store);
@@ -827,7 +919,7 @@ describe("Document Retrieval", () => {
       expect("error" in result).toBe(false);
       if (!("error" in result)) {
         expect(result.title).toBe("My Document");
-        expect(result.displayPath).toBe("mydoc.md");
+        expect(result.displayPath).toBe(`${collectionName}/mydoc.md`);
         expect(result.filepath).toBe(`qmd://${collectionName}/mydoc.md`);
         expect(result.body).toBeUndefined(); // body not included by default
       }
@@ -1646,13 +1738,13 @@ describe("Integration", () => {
     await insertTestDocument(store1.db, col1, {
       name: "doc1",
       body: "unique content for store1",
-      displayPath: "store1/doc.md",
+      displayPath: "doc.md",
     });
 
     await insertTestDocument(store2.db, col2, {
       name: "doc2",
       body: "different content for store2",
-      displayPath: "store2/doc.md",
+      displayPath: "doc.md",
     });
 
     // Each store should only see its own documents
@@ -1661,11 +1753,11 @@ describe("Integration", () => {
 
     expect(results1).toHaveLength(1);
     expect(results1[0].displayPath).toBe("store1/doc.md");
-    expect(results1[0].filepath).toBe("qmd://store1/store1/doc.md");
+    expect(results1[0].filepath).toBe("qmd://store1/doc.md");
 
     expect(results2).toHaveLength(1);
     expect(results2[0].displayPath).toBe("store2/doc.md");
-    expect(results2[0].filepath).toBe("qmd://store2/store2/doc.md");
+    expect(results2[0].filepath).toBe("qmd://store2/doc.md");
 
     // Cross-check: store1 shouldn't find store2's content
     const cross1 = store1.searchFTS("different", 10);
@@ -1791,7 +1883,7 @@ describe("Ollama Integration (Mocked)", () => {
 
     const results = await store.searchVec("test query", "embeddinggemma", 10);
     expect(results).toHaveLength(1);
-    expect(results[0].displayPath).toBe("doc1.md");
+    expect(results[0].displayPath).toBe(`${collectionName}/doc1.md`);
     expect(results[0].filepath).toBe(`qmd://${collectionName}/doc1.md`);
     expect(results[0].source).toBe("vec");
 

src/store.ts

@@ -388,9 +388,10 @@ export type Store = {
   getDocument: (filename: string, fromLine?: number, maxLines?: number) => (DocumentResult & { body: string }) | DocumentNotFound;
   getMultipleDocuments: (pattern: string, maxLines?: number, maxBytes?: number) => { files: MultiGetFile[]; errors: string[] };
 
-  // Fuzzy matching
+  // Fuzzy matching and docid lookup
   findSimilarFiles: (query: string, maxDistance?: number, limit?: number) => string[];
   matchFilesByGlob: (pattern: string) => { filepath: string; displayPath: string; bodyLength: number }[];
+  findDocumentByDocid: (docid: string) => { filepath: string; hash: string } | null;
 
   // Document indexing operations
   insertContent: (hash: string, content: string, createdAt: string) => void;
@@ -475,9 +476,10 @@ export function createStore(dbPath?: string): Store {
     getDocument: (filename: string, fromLine?: number, maxLines?: number) => getDocument(db, filename, fromLine, maxLines),
     getMultipleDocuments: (pattern: string, maxLines?: number, maxBytes?: number) => getMultipleDocuments(db, pattern, maxLines, maxBytes),
 
-    // Fuzzy matching
+    // Fuzzy matching and docid lookup
     findSimilarFiles: (query: string, maxDistance?: number, limit?: number) => findSimilarFiles(db, query, maxDistance, limit),
     matchFilesByGlob: (pattern: string) => matchFilesByGlob(db, pattern),
+    findDocumentByDocid: (docid: string) => findDocumentByDocid(db, docid),
 
     // Document indexing operations
     insertContent: (hash: string, content: string, createdAt: string) => insertContent(db, hash, content, createdAt),
@@ -549,12 +551,79 @@ export type DocumentResult = {
   title: string;              // Document title (from first heading or filename)
   context: string | null;     // Folder context description if configured
   hash: string;               // Content hash for caching/change detection
+  docid: string;              // Short docid (first 6 chars of hash) for quick reference
   collectionName: string;     // Parent collection name
   modifiedAt: string;         // Last modification timestamp
   bodyLength: number;         // Body length in bytes (useful before loading)
   body?: string;              // Document body (optional, load with getDocumentBody)
 };
 
+/**
+ * Extract short docid from a full hash (first 6 characters).
+ */
+export function getDocid(hash: string): string {
+  return hash.slice(0, 6);
+}
+
+/**
+ * Handelize a filename to be more token-friendly.
+ * - Convert triple underscore `___` to `/` (folder separator)
+ * - Convert to lowercase
+ * - Replace sequences of non-word chars (except /) with single dash
+ * - Remove leading/trailing dashes from path segments
+ * - Preserve folder structure (a/b/c/d.md stays structured)
+ * - Preserve file extension
+ */
+export function handelize(path: string): string {
+  if (!path || path.trim() === '') {
+    throw new Error('handelize: path cannot be empty');
+  }
+
+  // Check for paths that are just extensions or only dots/special chars
+  // A valid path must have at least one alphanumeric character before processing
+  const segments = path.split('/').filter(Boolean);
+  const lastSegment = segments[segments.length - 1] || '';
+  const filenameWithoutExt = lastSegment.replace(/\.[^.]+$/, '');
+  const hasValidContent = /[a-zA-Z0-9]/.test(filenameWithoutExt);
+  if (!hasValidContent) {
+    throw new Error(`handelize: path "${path}" has no valid filename content`);
+  }
+
+  const result = path
+    .replace(/___/g, '/')       // Triple underscore becomes folder separator
+    .toLowerCase()
+    .split('/')
+    .map((segment, idx, arr) => {
+      const isLastSegment = idx === arr.length - 1;
+
+      if (isLastSegment) {
+        // For the filename (last segment), preserve the extension
+        const extMatch = segment.match(/(\.[a-z0-9]+)$/i);
+        const ext = extMatch ? extMatch[1] : '';
+        const nameWithoutExt = ext ? segment.slice(0, -ext.length) : segment;
+
+        const cleanedName = nameWithoutExt
+          .replace(/[\W_]+/g, '-')  // Replace non-word chars with dash
+          .replace(/^-+|-+$/g, ''); // Remove leading/trailing dashes
+
+        return cleanedName + ext;
+      } else {
+        // For directories, just clean normally
+        return segment
+          .replace(/[\W_]+/g, '-')
+          .replace(/^-+|-+$/g, '');
+      }
+    })
+    .filter(Boolean)
+    .join('/');
+
+  if (!result) {
+    throw new Error(`handelize: path "${path}" resulted in empty string after processing`);
+  }
+
+  return result;
+}
+
 /**
  * Search result extends DocumentResult with score and source info
  */
@@ -970,6 +1039,28 @@ function levenshtein(a: string, b: string): number {
   return dp[m][n];
 }
 
+/**
+ * Find a document by its short docid (first 6 characters of hash).
+ * Returns the document's virtual path if found, null otherwise.
+ * If multiple documents match the same short hash (collision), returns the first one.
+ */
+export function findDocumentByDocid(db: Database, docid: string): { filepath: string; hash: string } | null {
+  // Normalize: remove leading # if present
+  const shortHash = docid.startsWith('#') ? docid.slice(1) : docid;
+
+  if (shortHash.length < 1) return null;
+
+  // Look up documents where hash starts with the short hash
+  const doc = db.prepare(`
+    SELECT 'qmd://' || d.collection || '/' || d.path as filepath, d.hash
+    FROM documents d
+    WHERE d.hash LIKE ? AND d.active = 1
+    LIMIT 1
+  `).get(`${shortHash}%`) as { filepath: string; hash: string } | null;
+
+  return doc;
+}
+
 export function findSimilarFiles(db: Database, query: string, maxDistance: number = 3, limit: number = 5): string[] {
   const allFiles = db.prepare(`
     SELECT d.path
@@ -1425,7 +1516,7 @@ export function searchFTS(db: Database, query: string, limit: number = 20, colle
   let sql = `
     SELECT
       'qmd://' || d.collection || '/' || d.path as filepath,
-      d.path as display_path,
+      d.collection || '/' || d.path as display_path,
       d.title,
       content.doc as body,
       d.hash,
@@ -1458,6 +1549,7 @@ export function searchFTS(db: Database, query: string, limit: number = 20, colle
       displayPath: row.display_path,
       title: row.title,
       hash: row.hash,
+      docid: getDocid(row.hash),
       collectionName,
       modifiedAt: "",  // Not available in FTS query
       bodyLength: row.body.length,
@@ -1486,7 +1578,7 @@ export async function searchVec(db: Database, query: string, model: string, limi
       v.hash_seq,
       v.distance,
       'qmd://' || d.collection || '/' || d.path as filepath,
-      d.path as display_path,
+      d.collection || '/' || d.path as display_path,
       d.title,
       content.doc as body,
       cv.hash,
@@ -1527,6 +1619,7 @@ export async function searchVec(db: Database, query: string, model: string, limi
         displayPath: row.display_path,
         title: row.title,
         hash: row.hash,
+        docid: getDocid(row.hash),
         collectionName,
         modifiedAt: "",  // Not available in vec query
         bodyLength: row.body.length,
@@ -1719,8 +1812,14 @@ type DbDocRow = {
 };
 
 /**
- * Find a document by filename/path (with fuzzy matching)
- * Returns document metadata without body by default
+ * Find a document by filename/path, docid (#hash), or with fuzzy matching.
+ * Returns document metadata without body by default.
+ *
+ * Supports:
+ * - Virtual paths: qmd://collection/path/to/file.md
+ * - Absolute paths: /path/to/file.md
+ * - Relative paths: path/to/file.md
+ * - Short docid: #abc123 (first 6 chars of hash)
  */
 export function findDocument(db: Database, filename: string, options: { includeBody?: boolean } = {}): DocumentResult | DocumentNotFound {
   let filepath = filename;
@@ -1729,6 +1828,16 @@ export function findDocument(db: Database, filename: string, options: { includeB
     filepath = filepath.slice(0, -colonMatch[0].length);
   }
 
+  // Check if this is a docid lookup (#hash or just 6-char hex)
+  if (filepath.startsWith('#') || /^[a-f0-9]{6}$/i.test(filepath)) {
+    const docidMatch = findDocumentByDocid(db, filepath);
+    if (docidMatch) {
+      filepath = docidMatch.filepath;
+    } else {
+      return { error: "not_found", query: filename, similarFiles: [] };
+    }
+  }
+
   if (filepath.startsWith('~/')) {
     filepath = homedir() + filepath.slice(1);
   }
@@ -1739,7 +1848,7 @@ export function findDocument(db: Database, filename: string, options: { includeB
   // Note: absoluteFilepath is computed from YAML collections after query
   const selectCols = `
     'qmd://' || d.collection || '/' || d.path as virtual_path,
-    d.path as display_path,
+    d.collection || '/' || d.path as display_path,
     d.title,
     d.hash,
     d.collection,
@@ -1809,6 +1918,7 @@ export function findDocument(db: Database, filename: string, options: { includeB
     title: doc.title,
     context,
     hash: doc.hash,
+    docid: getDocid(doc.hash),
     collectionName: doc.collection,
     modifiedAt: doc.modified_at,
     bodyLength: doc.body_length,
@@ -1910,7 +2020,7 @@ export function findDocuments(
   const bodyCol = options.includeBody ? `, content.doc as body` : ``;
   const selectCols = `
     'qmd://' || d.collection || '/' || d.path as virtual_path,
-    d.path as display_path,
+    d.collection || '/' || d.path as display_path,
     d.title,
     d.hash,
     d.collection,
@@ -1991,6 +2101,7 @@ export function findDocuments(
         title: row.title || row.display_path.split('/').pop() || row.display_path,
         context,
         hash: row.hash,
+        docid: getDocid(row.hash),
         collectionName: row.collection,
         modifiedAt: row.modified_at,
         bodyLength: row.body_length,