init

CLAUDE.md

@@ -0,0 +1,29 @@
+# Document-MCP Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2025-11-15
+
+## Active Technologies
+
+- Python 3.11+ + FastAPI, FastMCP, python-frontmatter, PyJWT, huggingface_hub, SQLite (stdlib) (001-obsidian-docs-viewer)
+
+## Project Structure
+
+```text
+src/
+tests/
+```
+
+## Commands
+
+cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .
+
+## Code Style
+
+Python 3.11+: Follow standard conventions
+
+## Recent Changes
+
+- 001-obsidian-docs-viewer: Added Python 3.11+ + FastAPI, FastMCP, python-frontmatter, PyJWT, huggingface_hub, SQLite (stdlib)
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

specs/001-obsidian-docs-viewer/contracts/http-api.yaml

@@ -0,0 +1,925 @@
+openapi: 3.1.0
+info:
+  title: Obsidian-Like Docs Viewer API
+  version: 1.0.0
+  description: |
+    Multi-tenant Obsidian-like documentation viewer with full-text search, wikilinks, and tags.
+
+    ## Authentication
+    All endpoints require Bearer JWT authentication via the `Authorization` header (except in local mode).
+
+    ## Multi-tenancy
+    All operations are scoped to the authenticated user's vault. Users cannot access other users' notes.
+
+    ## Path Encoding
+    Note paths in URLs must be URL-encoded (e.g., `api/design.md` becomes `api%2Fdesign.md`).
+  contact:
+    name: API Support
+  license:
+    name: MIT
+
+servers:
+  - url: http://localhost:8000
+    description: Local development server
+  - url: https://your-space.hf.space
+    description: Hugging Face Space deployment
+
+security:
+  - BearerAuth: []
+
+tags:
+  - name: Authentication
+    description: User authentication and token management
+  - name: Notes
+    description: CRUD operations for notes
+  - name: Search
+    description: Full-text search and navigation
+  - name: Index
+    description: Index health and rebuild operations
+
+paths:
+  /api/tokens:
+    post:
+      summary: Issue JWT token
+      description: Issue a new JWT access token for the authenticated user (90-day expiration)
+      operationId: issueToken
+      tags:
+        - Authentication
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Token issued successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TokenResponse'
+              example:
+                token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImlhdCI6MTczNjk1NjgwMCwiZXhwIjoxNzQ0NzMyODAwfQ.signature
+                token_type: bearer
+                expires_at: "2025-04-15T10:30:00Z"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /api/me:
+    get:
+      summary: Get current user info
+      description: Retrieve authenticated user information including HF profile
+      operationId: getCurrentUser
+      tags:
+        - Authentication
+      responses:
+        '200':
+          description: User information retrieved
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+              example:
+                user_id: alice
+                hf_profile:
+                  username: alice
+                  name: Alice Smith
+                  avatar_url: https://cdn-avatars.huggingface.co/v1/alice
+                vault_path: /data/vaults/alice
+                created: "2025-01-15T10:30:00Z"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /api/notes:
+    get:
+      summary: List notes
+      description: List all notes in the user's vault with optional folder filtering
+      operationId: listNotes
+      tags:
+        - Notes
+      parameters:
+        - name: folder
+          in: query
+          description: Filter notes by folder path (e.g., "api" or "guides/tutorials")
+          required: false
+          schema:
+            type: string
+            maxLength: 256
+          example: api
+      responses:
+        '200':
+          description: List of notes
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/NoteSummary'
+              example:
+                - note_path: api/design.md
+                  title: API Design
+                  updated: "2025-01-15T14:30:00Z"
+                - note_path: api/endpoints.md
+                  title: API Endpoints
+                  updated: "2025-01-14T09:15:00Z"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /api/notes/{path}:
+    get:
+      summary: Get note
+      description: Retrieve full note content including metadata, body, and version
+      operationId: getNote
+      tags:
+        - Notes
+      parameters:
+        - $ref: '#/components/parameters/NotePath'
+      responses:
+        '200':
+          description: Note retrieved successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Note'
+              example:
+                user_id: alice
+                note_path: api/design.md
+                version: 5
+                title: API Design
+                metadata:
+                  tags:
+                    - backend
+                    - api
+                  project: auth-service
+                body: "# API Design\n\nThis document describes the API architecture...\n\n## Endpoints\n\nSee [[Endpoints]] for details."
+                created: "2025-01-10T09:00:00Z"
+                updated: "2025-01-15T14:30:00Z"
+                size_bytes: 4096
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Note not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: not_found
+                message: Note not found
+                detail:
+                  note_path: api/design.md
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    put:
+      summary: Create or update note
+      description: Create a new note or update an existing note with optional optimistic concurrency control
+      operationId: createOrUpdateNote
+      tags:
+        - Notes
+      parameters:
+        - $ref: '#/components/parameters/NotePath'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NoteUpdate'
+            example:
+              title: API Design
+              metadata:
+                tags:
+                  - backend
+                  - api
+                project: auth-service
+              body: "# API Design\n\nThis document describes the API architecture..."
+              if_version: 4
+      responses:
+        '200':
+          description: Note updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NoteResponse'
+              example:
+                status: ok
+                path: api/design.md
+                version: 5
+        '201':
+          description: Note created successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NoteResponse'
+              example:
+                status: ok
+                path: api/design.md
+                version: 1
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '413':
+          $ref: '#/components/responses/PayloadTooLarge'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    delete:
+      summary: Delete note
+      description: Delete a note and remove it from all indices
+      operationId: deleteNote
+      tags:
+        - Notes
+      parameters:
+        - $ref: '#/components/parameters/NotePath'
+      responses:
+        '200':
+          description: Note deleted successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/DeleteResponse'
+              example:
+                status: ok
+                path: api/design.md
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          description: Note not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: not_found
+                message: Note not found
+                detail:
+                  note_path: api/design.md
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /api/search:
+    get:
+      summary: Search notes
+      description: Full-text search across all notes with ranking (title 3x weight, body 1x, recency bonus)
+      operationId: searchNotes
+      tags:
+        - Search
+      parameters:
+        - name: q
+          in: query
+          description: Search query (tokenized, case-insensitive)
+          required: true
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 256
+          example: authentication
+        - name: limit
+          in: query
+          description: Maximum number of results to return
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 50
+      responses:
+        '200':
+          description: Search results
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/SearchResult'
+              example:
+                - note_path: api/auth.md
+                  title: Authentication Flow
+                  snippet: "...describes the <mark>authentication</mark> process using JWT tokens..."
+                  score: 8.5
+                  updated: "2025-01-15T14:30:00Z"
+                - note_path: guides/setup.md
+                  title: Setup Guide
+                  snippet: "...configure <mark>authentication</mark> settings in the config file..."
+                  score: 3.2
+                  updated: "2025-01-10T09:00:00Z"
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /api/backlinks/{path}:
+    get:
+      summary: Get backlinks
+      description: Get all notes that reference the specified note via wikilinks
+      operationId: getBacklinks
+      tags:
+        - Search
+      parameters:
+        - name: path
+          in: path
+          description: URL-encoded note path (includes .md extension)
+          required: true
+          schema:
+            type: string
+            maxLength: 256
+          example: api%2Fdesign.md
+      responses:
+        '200':
+          description: Backlinks retrieved
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/BacklinkResult'
+              example:
+                - note_path: guides/architecture.md
+                  title: Architecture Overview
+                - note_path: api/endpoints.md
+                  title: API Endpoints
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Note not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: not_found
+                message: Note not found
+                detail:
+                  note_path: api/design.md
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /api/tags:
+    get:
+      summary: List all tags
+      description: Get all tags used in the user's vault with note counts
+      operationId: listTags
+      tags:
+        - Search
+      responses:
+        '200':
+          description: List of tags
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Tag'
+              example:
+                - tag: backend
+                  count: 15
+                - tag: api
+                  count: 12
+                - tag: frontend
+                  count: 8
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /api/index/health:
+    get:
+      summary: Get index health status
+      description: Retrieve index health metrics including note count and last update timestamps
+      operationId: getIndexHealth
+      tags:
+        - Index
+      responses:
+        '200':
+          description: Index health metrics
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IndexHealth'
+              example:
+                user_id: alice
+                note_count: 142
+                last_full_rebuild: "2025-01-01T00:00:00Z"
+                last_incremental_update: "2025-01-15T14:30:00Z"
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /api/index/rebuild:
+    post:
+      summary: Trigger full index rebuild
+      description: Manually rebuild all indices from scratch by re-scanning vault files
+      operationId: rebuildIndex
+      tags:
+        - Index
+      responses:
+        '200':
+          description: Index rebuild completed
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RebuildResponse'
+              example:
+                status: ok
+                notes_indexed: 142
+                duration_ms: 1250
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT token obtained from POST /api/tokens
+
+  parameters:
+    NotePath:
+      name: path
+      in: path
+      description: URL-encoded note path (includes .md extension, e.g., "api%2Fdesign.md")
+      required: true
+      schema:
+        type: string
+        maxLength: 256
+      example: api%2Fdesign.md
+
+  schemas:
+    User:
+      type: object
+      required:
+        - user_id
+        - vault_path
+        - created
+      properties:
+        user_id:
+          type: string
+          minLength: 1
+          maxLength: 64
+          description: Internal user identifier
+          example: alice
+        hf_profile:
+          $ref: '#/components/schemas/HFProfile'
+        vault_path:
+          type: string
+          description: Absolute path to user's vault directory
+          example: /data/vaults/alice
+        created:
+          type: string
+          format: date-time
+          description: Account creation timestamp (ISO 8601)
+          example: "2025-01-15T10:30:00Z"
+
+    HFProfile:
+      type: object
+      properties:
+        username:
+          type: string
+          description: Hugging Face username
+          example: alice
+        name:
+          type: string
+          nullable: true
+          description: Display name from HF profile
+          example: Alice Smith
+        avatar_url:
+          type: string
+          format: uri
+          nullable: true
+          description: Profile picture URL
+          example: https://cdn-avatars.huggingface.co/v1/alice
+
+    NoteMetadata:
+      type: object
+      description: Arbitrary frontmatter key-value pairs (YAML)
+      properties:
+        title:
+          type: string
+          nullable: true
+        tags:
+          type: array
+          items:
+            type: string
+          nullable: true
+        project:
+          type: string
+          nullable: true
+        created:
+          type: string
+          format: date-time
+          nullable: true
+        updated:
+          type: string
+          format: date-time
+          nullable: true
+      additionalProperties: true
+      example:
+        tags:
+          - backend
+          - api
+        project: auth-service
+
+    Note:
+      type: object
+      required:
+        - user_id
+        - note_path
+        - version
+        - title
+        - body
+        - created
+        - updated
+        - size_bytes
+      properties:
+        user_id:
+          type: string
+          description: Owner user ID
+          example: alice
+        note_path:
+          type: string
+          minLength: 1
+          maxLength: 256
+          description: Relative path to vault root (includes .md)
+          example: api/design.md
+        version:
+          type: integer
+          minimum: 1
+          description: Optimistic concurrency version counter
+          example: 5
+        title:
+          type: string
+          minLength: 1
+          description: Display title (from frontmatter, H1, or filename)
+          example: API Design
+        metadata:
+          $ref: '#/components/schemas/NoteMetadata'
+        body:
+          type: string
+          description: Markdown content (excluding frontmatter)
+          example: "# API Design\n\nThis document describes..."
+        created:
+          type: string
+          format: date-time
+          description: Creation timestamp (ISO 8601)
+          example: "2025-01-10T09:00:00Z"
+        updated:
+          type: string
+          format: date-time
+          description: Last modification timestamp (ISO 8601)
+          example: "2025-01-15T14:30:00Z"
+        size_bytes:
+          type: integer
+          minimum: 0
+          maximum: 1048576
+          description: File size in bytes (max 1 MiB)
+          example: 4096
+
+    NoteSummary:
+      type: object
+      required:
+        - note_path
+        - title
+        - updated
+      properties:
+        note_path:
+          type: string
+          example: api/design.md
+        title:
+          type: string
+          example: API Design
+        updated:
+          type: string
+          format: date-time
+          example: "2025-01-15T14:30:00Z"
+
+    NoteUpdate:
+      type: object
+      required:
+        - body
+      properties:
+        title:
+          type: string
+          nullable: true
+          description: Override title (if not set, will be extracted from frontmatter or body)
+        metadata:
+          $ref: '#/components/schemas/NoteMetadata'
+        body:
+          type: string
+          maxLength: 1048576
+          description: Markdown content (max 1 MiB UTF-8)
+        if_version:
+          type: integer
+          minimum: 1
+          nullable: true
+          description: Expected version for optimistic concurrency (409 if mismatch)
+          example: 4
+
+    NoteResponse:
+      type: object
+      required:
+        - status
+        - path
+        - version
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        path:
+          type: string
+          example: api/design.md
+        version:
+          type: integer
+          example: 5
+
+    DeleteResponse:
+      type: object
+      required:
+        - status
+        - path
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        path:
+          type: string
+          example: api/design.md
+
+    SearchResult:
+      type: object
+      required:
+        - note_path
+        - title
+        - snippet
+        - score
+        - updated
+      properties:
+        note_path:
+          type: string
+          example: api/auth.md
+        title:
+          type: string
+          example: Authentication Flow
+        snippet:
+          type: string
+          description: Highlighted excerpt with <mark> tags
+          example: "...describes the <mark>authentication</mark> process using JWT..."
+        score:
+          type: number
+          format: float
+          description: Relevance score (title 3x, body 1x, recency bonus)
+          example: 8.5
+        updated:
+          type: string
+          format: date-time
+          example: "2025-01-15T14:30:00Z"
+
+    BacklinkResult:
+      type: object
+      required:
+        - note_path
+        - title
+      properties:
+        note_path:
+          type: string
+          example: guides/architecture.md
+        title:
+          type: string
+          example: Architecture Overview
+
+    Tag:
+      type: object
+      required:
+        - tag
+        - count
+      properties:
+        tag:
+          type: string
+          description: Tag name (lowercase, normalized)
+          example: backend
+        count:
+          type: integer
+          minimum: 0
+          description: Number of notes with this tag
+          example: 15
+
+    IndexHealth:
+      type: object
+      required:
+        - user_id
+        - note_count
+      properties:
+        user_id:
+          type: string
+          example: alice
+        note_count:
+          type: integer
+          minimum: 0
+          description: Total notes indexed
+          example: 142
+        last_full_rebuild:
+          type: string
+          format: date-time
+          nullable: true
+          description: Timestamp of last manual rebuild
+          example: "2025-01-01T00:00:00Z"
+        last_incremental_update:
+          type: string
+          format: date-time
+          nullable: true
+          description: Timestamp of last write/delete operation
+          example: "2025-01-15T14:30:00Z"
+
+    RebuildResponse:
+      type: object
+      required:
+        - status
+        - notes_indexed
+        - duration_ms
+      properties:
+        status:
+          type: string
+          enum:
+            - ok
+        notes_indexed:
+          type: integer
+          minimum: 0
+          example: 142
+        duration_ms:
+          type: integer
+          minimum: 0
+          description: Rebuild duration in milliseconds
+          example: 1250
+
+    TokenResponse:
+      type: object
+      required:
+        - token
+        - token_type
+        - expires_at
+      properties:
+        token:
+          type: string
+          description: JWT access token
+          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+        token_type:
+          type: string
+          enum:
+            - bearer
+          example: bearer
+        expires_at:
+          type: string
+          format: date-time
+          description: Token expiration timestamp (90 days from issuance)
+          example: "2025-04-15T10:30:00Z"
+
+    Error:
+      type: object
+      required:
+        - error
+        - message
+      properties:
+        error:
+          type: string
+          description: Error code (machine-readable)
+          example: validation_error
+        message:
+          type: string
+          description: Human-readable error message
+          example: Invalid note path format
+        detail:
+          type: object
+          nullable: true
+          description: Additional error context
+          additionalProperties: true
+          example:
+            field: note_path
+            reason: Path must end with .md
+
+  responses:
+    BadRequest:
+      description: Bad request (invalid input)
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            invalidPath:
+              summary: Invalid note path
+              value:
+                error: validation_error
+                message: Invalid note path format
+                detail:
+                  field: note_path
+                  reason: Path must end with .md
+            emptyQuery:
+              summary: Empty search query
+              value:
+                error: validation_error
+                message: Search query cannot be empty
+                detail:
+                  field: query
+                  reason: Query must be at least 1 character
+
+    Unauthorized:
+      description: Authentication required or token invalid/expired
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            missingToken:
+              summary: Missing authorization header
+              value:
+                error: unauthorized
+                message: Authorization header required
+            expiredToken:
+              summary: Expired JWT token
+              value:
+                error: token_expired
+                message: Token expired, please re-authenticate
+            invalidToken:
+              summary: Invalid JWT token
+              value:
+                error: invalid_token
+                message: Invalid token signature
+
+    Forbidden:
+      description: Forbidden (vault limit exceeded or permission denied)
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            vaultLimitExceeded:
+              summary: Vault note limit exceeded
+              value:
+                error: vault_note_limit_exceeded
+                message: Vault has reached maximum of 5,000 notes
+                detail:
+                  current_count: 5000
+                  max_limit: 5000
+            pathTraversal:
+              summary: Path traversal attempt
+              value:
+                error: forbidden
+                message: Path escapes vault root
+                detail:
+                  note_path: ../../../etc/passwd
+
+    Conflict:
+      description: Version conflict (optimistic concurrency failure)
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: version_conflict
+            message: Note was modified since you opened it
+            detail:
+              expected_version: 4
+              current_version: 6
+              note_path: api/design.md
+
+    PayloadTooLarge:
+      description: Note content exceeds 1 MiB limit
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: payload_too_large
+            message: Note content exceeds maximum size of 1 MiB
+            detail:
+              size_bytes: 1572864
+              max_size_bytes: 1048576
+
+    InternalServerError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            error: internal_error
+            message: An unexpected error occurred
+            detail:
+              request_id: req_abc123

specs/001-obsidian-docs-viewer/contracts/mcp-tools.json

@@ -0,0 +1,581 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "title": "MCP Tools for Obsidian-Like Docs Viewer",
+  "description": "FastMCP tool definitions for multi-tenant documentation viewer with JSON Schema validation (Pydantic)",
+  "tools": [
+    {
+      "name": "list_notes",
+      "title": "List Notes",
+      "description": "List all notes in the authenticated user's vault with optional folder filtering. Returns lightweight summaries with path, title, and last modified timestamp.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "folder": {
+            "type": "string",
+            "description": "Optional folder path to filter notes (e.g., 'api' or 'guides/tutorials'). If omitted, returns all notes in the vault.",
+            "maxLength": 256,
+            "examples": ["api", "guides/tutorials", ""]
+          }
+        },
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "array",
+        "description": "Array of note summaries, sorted by most recently updated first",
+        "items": {
+          "type": "object",
+          "required": ["path", "title", "last_modified"],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "Relative path to vault root (includes .md extension)",
+              "examples": ["api/design.md", "README.md"]
+            },
+            "title": {
+              "type": "string",
+              "description": "Display title (from frontmatter, H1, or filename)",
+              "examples": ["API Design", "README"]
+            },
+            "last_modified": {
+              "type": "string",
+              "format": "date-time",
+              "description": "Last modification timestamp (ISO 8601)",
+              "examples": ["2025-01-15T14:30:00Z"]
+            }
+          }
+        },
+        "examples": [
+          [
+            {
+              "path": "api/design.md",
+              "title": "API Design",
+              "last_modified": "2025-01-15T14:30:00Z"
+            },
+            {
+              "path": "api/endpoints.md",
+              "title": "API Endpoints",
+              "last_modified": "2025-01-14T09:15:00Z"
+            }
+          ]
+        ]
+      }
+    },
+    {
+      "name": "read_note",
+      "title": "Read Note",
+      "description": "Retrieve full note content including metadata (frontmatter), body (markdown), and system-managed fields (version, timestamps). Use this to access existing documentation.",
+      "inputSchema": {
+        "type": "object",
+        "required": ["path"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Relative path to vault root (includes .md extension, e.g., 'api/design.md')",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^[^/].*\\.md$",
+            "examples": ["api/design.md", "README.md", "guides/setup.md"]
+          }
+        },
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "object",
+        "required": ["path", "title", "metadata", "body"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Note path (echo of input)",
+            "examples": ["api/design.md"]
+          },
+          "title": {
+            "type": "string",
+            "description": "Display title",
+            "examples": ["API Design"]
+          },
+          "metadata": {
+            "type": "object",
+            "description": "Frontmatter key-value pairs (arbitrary structure)",
+            "properties": {
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "project": {
+                "type": "string"
+              },
+              "created": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "updated": {
+                "type": "string",
+                "format": "date-time"
+              }
+            },
+            "additionalProperties": true,
+            "examples": [
+              {
+                "tags": ["backend", "api"],
+                "project": "auth-service"
+              }
+            ]
+          },
+          "body": {
+            "type": "string",
+            "description": "Markdown content (excluding frontmatter YAML)",
+            "examples": ["# API Design\n\nThis document describes the API architecture...\n\n## Endpoints\n\nSee [[Endpoints]] for details."]
+          }
+        },
+        "examples": [
+          {
+            "path": "api/design.md",
+            "title": "API Design",
+            "metadata": {
+              "tags": ["backend", "api"],
+              "project": "auth-service"
+            },
+            "body": "# API Design\n\nThis document describes the API architecture..."
+          }
+        ]
+      }
+    },
+    {
+      "name": "write_note",
+      "title": "Write Note",
+      "description": "Create a new note or update an existing note. Automatically manages version, created/updated timestamps, and index updates. Uses last-write-wins strategy (no version conflict detection for MCP writes).",
+      "inputSchema": {
+        "type": "object",
+        "required": ["path", "body"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Relative path to vault root (includes .md extension). Must not contain '..', use Unix separators (/), and be relative (no leading /).",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^[^/].*\\.md$",
+            "examples": ["api/design.md", "README.md", "guides/new-feature.md"]
+          },
+          "title": {
+            "type": "string",
+            "description": "Optional title override (if omitted, will be extracted from frontmatter or first H1 heading in body)",
+            "examples": ["API Design", "New Feature Guide"]
+          },
+          "metadata": {
+            "type": "object",
+            "description": "Optional frontmatter metadata (arbitrary key-value pairs). Common fields: tags (array), project (string), etc.",
+            "properties": {
+              "tags": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "description": "Tag names for categorization"
+              },
+              "project": {
+                "type": "string",
+                "description": "Project identifier"
+              }
+            },
+            "additionalProperties": true,
+            "examples": [
+              {
+                "tags": ["backend", "api"],
+                "project": "auth-service"
+              }
+            ]
+          },
+          "body": {
+            "type": "string",
+            "description": "Markdown content (max 1 MiB UTF-8). Can contain wikilinks using [[link text]] syntax.",
+            "maxLength": 1048576,
+            "examples": ["# API Design\n\nThis document describes the API architecture...\n\n## Related\n\nSee [[Endpoints]] for endpoint details."]
+          }
+        },
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "object",
+        "required": ["status", "path"],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["ok"],
+            "description": "Operation status"
+          },
+          "path": {
+            "type": "string",
+            "description": "Path of the created/updated note",
+            "examples": ["api/design.md"]
+          }
+        },
+        "examples": [
+          {
+            "status": "ok",
+            "path": "api/design.md"
+          }
+        ]
+      }
+    },
+    {
+      "name": "delete_note",
+      "title": "Delete Note",
+      "description": "Permanently delete a note from the vault and remove it from all indices (full-text, tags, links). Any wikilinks referencing this note will become unresolved.",
+      "inputSchema": {
+        "type": "object",
+        "required": ["path"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Relative path to vault root (includes .md extension)",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^[^/].*\\.md$",
+            "examples": ["api/design.md", "obsolete/old-doc.md"]
+          }
+        },
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "object",
+        "required": ["status"],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": ["ok"],
+            "description": "Operation status"
+          }
+        },
+        "examples": [
+          {
+            "status": "ok"
+          }
+        ]
+      }
+    },
+    {
+      "name": "search_notes",
+      "title": "Search Notes",
+      "description": "Full-text search across all notes in the user's vault. Results are ranked using: (3 * title_matches) + (1 * body_matches) + recency_bonus. Returns snippets with highlighted matches.",
+      "inputSchema": {
+        "type": "object",
+        "required": ["query"],
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search query (tokenized, case-insensitive). Supports simple keyword search with automatic stemming (e.g., 'running' matches 'run').",
+            "minLength": 1,
+            "maxLength": 256,
+            "examples": ["authentication", "API design", "database schema"]
+          }
+        },
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "array",
+        "description": "Search results sorted by relevance score (descending). Limited to top 50 results.",
+        "maxItems": 50,
+        "items": {
+          "type": "object",
+          "required": ["path", "title", "snippet"],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "Note path",
+              "examples": ["api/auth.md"]
+            },
+            "title": {
+              "type": "string",
+              "description": "Note title",
+              "examples": ["Authentication Flow"]
+            },
+            "snippet": {
+              "type": "string",
+              "description": "Highlighted excerpt from body (max ~200 chars, with <mark> tags around matches)",
+              "examples": ["...describes the <mark>authentication</mark> process using JWT tokens..."]
+            }
+          }
+        },
+        "examples": [
+          [
+            {
+              "path": "api/auth.md",
+              "title": "Authentication Flow",
+              "snippet": "...describes the <mark>authentication</mark> process using JWT tokens..."
+            },
+            {
+              "path": "guides/setup.md",
+              "title": "Setup Guide",
+              "snippet": "...configure <mark>authentication</mark> settings in the config file..."
+            }
+          ]
+        ]
+      }
+    },
+    {
+      "name": "get_backlinks",
+      "title": "Get Backlinks",
+      "description": "Get all notes that reference the specified note via wikilinks (e.g., [[Note Name]]). Useful for discovering related documentation and navigation.",
+      "inputSchema": {
+        "type": "object",
+        "required": ["path"],
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Relative path to vault root (includes .md extension)",
+            "minLength": 1,
+            "maxLength": 256,
+            "pattern": "^[^/].*\\.md$",
+            "examples": ["api/design.md", "README.md"]
+          }
+        },
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "array",
+        "description": "Array of notes that link to the target note, sorted by most recently updated first",
+        "items": {
+          "type": "object",
+          "required": ["path", "title"],
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "Path of the linking note",
+              "examples": ["guides/architecture.md"]
+            },
+            "title": {
+              "type": "string",
+              "description": "Title of the linking note",
+              "examples": ["Architecture Overview"]
+            }
+          }
+        },
+        "examples": [
+          [
+            {
+              "path": "guides/architecture.md",
+              "title": "Architecture Overview"
+            },
+            {
+              "path": "api/endpoints.md",
+              "title": "API Endpoints"
+            }
+          ]
+        ]
+      }
+    },
+    {
+      "name": "get_tags",
+      "title": "Get Tags",
+      "description": "List all tags used across the user's vault with note counts. Tags are extracted from frontmatter 'tags' field and normalized (lowercase).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {},
+        "additionalProperties": false
+      },
+      "outputSchema": {
+        "type": "array",
+        "description": "Array of tags sorted by count (descending)",
+        "items": {
+          "type": "object",
+          "required": ["tag", "count"],
+          "properties": {
+            "tag": {
+              "type": "string",
+              "description": "Tag name (lowercase, normalized)",
+              "examples": ["backend", "api", "frontend"]
+            },
+            "count": {
+              "type": "integer",
+              "minimum": 0,
+              "description": "Number of notes with this tag",
+              "examples": [15, 12, 8]
+            }
+          }
+        },
+        "examples": [
+          [
+            {
+              "tag": "backend",
+              "count": 15
+            },
+            {
+              "tag": "api",
+              "count": 12
+            },
+            {
+              "tag": "frontend",
+              "count": 8
+            }
+          ]
+        ]
+      }
+    }
+  ],
+  "authentication": {
+    "type": "bearer",
+    "description": "MCP HTTP transport requires Bearer JWT token via 'auth' parameter. STDIO transport (local mode) does not require authentication.",
+    "tokenSource": "POST /api/tokens",
+    "tokenExpiration": "90 days"
+  },
+  "errors": {
+    "description": "All MCP tools follow FastMCP error handling conventions. Common error scenarios:",
+    "errorCodes": [
+      {
+        "code": "AUTHENTICATION_REQUIRED",
+        "description": "Missing or invalid JWT token (HTTP transport only)",
+        "httpStatus": 401
+      },
+      {
+        "code": "PERMISSION_DENIED",
+        "description": "Vault note limit exceeded (5,000 notes) or path traversal attempt",
+        "httpStatus": 403
+      },
+      {
+        "code": "NOT_FOUND",
+        "description": "Note path does not exist in vault",
+        "httpStatus": 404
+      },
+      {
+        "code": "VALIDATION_ERROR",
+        "description": "Invalid input parameters (e.g., path format, content size)",
+        "httpStatus": 400,
+        "details": {
+          "invalidPath": "Path must end with .md, not contain '..' or '\\', and be relative",
+          "payloadTooLarge": "Note body exceeds 1 MiB UTF-8 text limit",
+          "emptyQuery": "Search query must be at least 1 character"
+        }
+      },
+      {
+        "code": "INTERNAL_ERROR",
+        "description": "Unexpected server error (filesystem, database, etc.)",
+        "httpStatus": 500
+      }
+    ]
+  },
+  "examples": {
+    "description": "Common usage patterns for AI agents via MCP",
+    "scenarios": [
+      {
+        "name": "Create documentation structure",
+        "description": "AI agent creates initial project documentation with organized folders",
+        "steps": [
+          {
+            "tool": "write_note",
+            "input": {
+              "path": "README.md",
+              "title": "Project Overview",
+              "metadata": {
+                "tags": ["overview", "documentation"]
+              },
+              "body": "# Project Overview\n\nWelcome to the project.\n\n## Structure\n\n- [[API Documentation]] - API design and endpoints\n- [[Guides]] - User guides and tutorials"
+            }
+          },
+          {
+            "tool": "write_note",
+            "input": {
+              "path": "api/README.md",
+              "title": "API Documentation",
+              "metadata": {
+                "tags": ["api", "backend"]
+              },
+              "body": "# API Documentation\n\nSee:\n- [[Authentication]] for auth flows\n- [[Endpoints]] for endpoint specs"
+            }
+          }
+        ]
+      },
+      {
+        "name": "Update documentation with search",
+        "description": "AI agent searches for existing docs before updating",
+        "steps": [
+          {
+            "tool": "search_notes",
+            "input": {
+              "query": "authentication"
+            },
+            "output": [
+              {
+                "path": "api/auth.md",
+                "title": "Authentication Flow",
+                "snippet": "...JWT token-based authentication..."
+              }
+            ]
+          },
+          {
+            "tool": "read_note",
+            "input": {
+              "path": "api/auth.md"
+            }
+          },
+          {
+            "tool": "write_note",
+            "input": {
+              "path": "api/auth.md",
+              "body": "# Authentication Flow\n\n[Updated content with new OAuth section...]"
+            }
+          }
+        ]
+      },
+      {
+        "name": "Discover related documentation",
+        "description": "AI agent uses backlinks to find related docs",
+        "steps": [
+          {
+            "tool": "get_backlinks",
+            "input": {
+              "path": "api/design.md"
+            },
+            "output": [
+              {
+                "path": "guides/architecture.md",
+                "title": "Architecture Overview"
+              },
+              {
+                "path": "api/endpoints.md",
+                "title": "API Endpoints"
+              }
+            ]
+          },
+          {
+            "tool": "read_note",
+            "input": {
+              "path": "guides/architecture.md"
+            }
+          }
+        ]
+      }
+    ]
+  },
+  "validation": {
+    "description": "Input validation rules enforced by FastMCP/Pydantic",
+    "rules": {
+      "notePath": {
+        "pattern": "^[^/].*\\.md$",
+        "minLength": 1,
+        "maxLength": 256,
+        "mustNotContain": ["..", "\\"],
+        "mustEndWith": ".md",
+        "invalidChars": ["<", ">", ":", "\"", "|", "?", "*"]
+      },
+      "noteBody": {
+        "maxLength": 1048576,
+        "encoding": "UTF-8"
+      },
+      "searchQuery": {
+        "minLength": 1,
+        "maxLength": 256
+      },
+      "folder": {
+        "maxLength": 256,
+        "optional": true
+      },
+      "metadata": {
+        "type": "object",
+        "reservedFields": ["version"],
+        "tagsFormat": "array of strings"
+      }
+    }
+  }
+}

specs/001-obsidian-docs-viewer/data-model.md

@@ -0,0 +1,1483 @@
+# Data Model: Multi-Tenant Obsidian-Like Docs Viewer
+
+**Feature Branch**: `001-obsidian-docs-viewer`
+**Created**: 2025-11-15
+**Status**: Draft
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Entity Relationship Diagram](#entity-relationship-diagram)
+3. [Core Entities](#core-entities)
+4. [Index Entities](#index-entities)
+5. [Authentication Entities](#authentication-entities)
+6. [SQLite Schema](#sqlite-schema)
+7. [Pydantic Models](#pydantic-models)
+8. [TypeScript Type Definitions](#typescript-type-definitions)
+9. [Validation Rules](#validation-rules)
+10. [State Transitions](#state-transitions)
+11. [Relationships and Constraints](#relationships-and-constraints)
+
+---
+
+## Overview
+
+This document defines the complete data model for a multi-tenant Obsidian-like documentation viewer. The system stores:
+
+- **User accounts** with HF OAuth identity mapping
+- **Vaults** as per-user directory trees containing Markdown notes
+- **Notes** with YAML frontmatter, version tracking, and full-text indexing
+- **Wikilinks** for bidirectional linking between notes
+- **Tags** for categorization and filtering
+- **Index metadata** for search optimization and health monitoring
+
+**Design principles**:
+- **Per-user isolation**: All data scoped by `user_id`
+- **Filesystem-backed**: Notes stored as `.md` files, metadata in SQLite
+- **Version-controlled**: Integer version counter for optimistic concurrency
+- **Search-optimized**: SQLite FTS5 for full-text search, separate indexes for tags and links
+
+---
+
+## Entity Relationship Diagram
+
+```mermaid
+erDiagram
+    USER ||--o{ VAULT : owns
+    VAULT ||--o{ NOTE : contains
+    NOTE ||--o{ WIKILINK : has_outgoing
+    NOTE ||--o{ WIKILINK : has_incoming
+    NOTE ||--o{ TAG : tagged_with
+    USER ||--|| INDEX_HEALTH : tracks
+    USER ||--o{ TOKEN : issues
+
+    USER {
+        string user_id PK
+        string hf_username
+        string hf_name
+        string hf_avatar_url
+        datetime created
+    }
+
+    VAULT {
+        string user_id FK
+        string root_path
+        int note_count
+    }
+
+    NOTE {
+        string user_id FK
+        string note_path PK
+        int version
+        string title
+        json metadata
+        string body
+        datetime created
+        datetime updated
+        int size_bytes
+    }
+
+    WIKILINK {
+        string user_id FK
+        string source_path FK
+        string target_path FK
+        string link_text
+        bool is_resolved
+    }
+
+    TAG {
+        string user_id FK
+        string tag_name
+        string note_path FK
+    }
+
+    INDEX_HEALTH {
+        string user_id PK
+        int note_count
+        datetime last_full_rebuild
+        datetime last_incremental_update
+    }
+
+    TOKEN {
+        string token_id PK
+        string user_id FK
+        datetime issued_at
+        datetime expires_at
+        string token_type
+    }
+```
+
+**Key relationships**:
+- One user owns one vault (1:1)
+- One vault contains many notes (1:N)
+- One note has many outgoing wikilinks (1:N)
+- One note may be referenced by many backlinks (1:N)
+- One note can have many tags (N:M via junction table)
+- One user has one index health record (1:1)
+- One user can issue many tokens (1:N)
+
+---
+
+## Core Entities
+
+### User
+
+Represents an authenticated user with HF OAuth identity.
+
+**Attributes**:
+- `user_id` (string, PK): Internal unique identifier, derived from HF username or UUID
+- `hf_username` (string, nullable): HuggingFace username (e.g., "alice")
+- `hf_name` (string, nullable): Display name from HF profile
+- `hf_avatar_url` (string, nullable): Profile picture URL
+- `created` (datetime): Account creation timestamp (ISO 8601)
+
+**Notes**:
+- In local mode, `user_id = "local-dev"` with null HF fields
+- In HF Space mode, `user_id = hf_username` (normalized to lowercase)
+- `created` timestamp set on first OAuth login (vault initialization)
+
+**Lifecycle**:
+1. User authenticates via HF OAuth
+2. Backend maps HF identity to `user_id`
+3. If new user, create vault directory and initialize index
+4. Return user info to frontend
+
+---
+
+### Vault
+
+A per-user directory tree containing Markdown notes.
+
+**Attributes**:
+- `user_id` (string, FK): Owner of the vault
+- `root_path` (string): Absolute filesystem path to vault root (e.g., `/data/vaults/alice/`)
+- `note_count` (int): Cached count of notes in vault (denormalized from index)
+
+**Constraints**:
+- Max 5,000 notes per vault (enforced by FR-008)
+- Root path must exist and be writable
+- Directory structure is arbitrary (user-defined nested folders)
+
+**Filesystem layout example**:
+```
+/data/vaults/alice/
+├── README.md
+├── api/
+│   ├── design.md
+│   └── endpoints.md
+├── guides/
+│   ├── setup.md
+│   └── deployment.md
+└── notes/
+    └── meeting-2025-01-15.md
+```
+
+---
+
+### Note
+
+A Markdown file with optional YAML frontmatter and body content.
+
+**Attributes**:
+- `user_id` (string, FK): Owner of the note
+- `note_path` (string, PK): Relative path to vault root, includes `.md` (e.g., `api/design.md`)
+- `version` (int): Optimistic concurrency version counter (starts at 1, increments on write)
+- `title` (string): Display title (from frontmatter, first H1, or filename stem)
+- `metadata` (JSON): Frontmatter key-value pairs (excludes auto-managed fields)
+- `body` (string): Markdown content (excluding frontmatter)
+- `created` (datetime, ISO 8601): Creation timestamp (auto-set if not in frontmatter)
+- `updated` (datetime, ISO 8601): Last modification timestamp (auto-set on every write)
+- `size_bytes` (int): UTF-8 byte size of full file content (frontmatter + body)
+
+**Constraints**:
+- `note_path` max 256 characters, Unix-style separators (`/`), no `..` allowed
+- `size_bytes` max 1 MiB (1,048,576 bytes) per FR-007
+- `version` stored in index, NOT in frontmatter
+- `created` and `updated` stored in index, MAY appear in frontmatter (frontmatter is source of truth on read)
+
+**Title resolution priority** (FR-006):
+1. `metadata.get('title')` from frontmatter
+2. First `# Heading` in body (H1 only)
+3. Filename stem (e.g., `design.md` → "design")
+
+**Metadata fields** (common, but arbitrary):
+- `tags` (array of strings): Tag names for categorization
+- `project` (string): Project identifier
+- `created` (datetime): User-provided creation timestamp
+- `updated` (datetime): User-provided update timestamp
+- Custom fields allowed (JSON object)
+
+---
+
+## Index Entities
+
+### Wikilink
+
+Represents a bidirectional link between two notes.
+
+**Attributes**:
+- `user_id` (string, FK): Owner of the notes
+- `source_path` (string, FK): Path of note containing the wikilink
+- `target_path` (string, nullable, FK): Resolved path of linked note (null if unresolved)
+- `link_text` (string): Original text from `[[link text]]`
+- `is_resolved` (bool): True if `target_path` is non-null, false if broken link
+
+**Extraction**:
+- Regex pattern: `\[\[([^\]]+)\]\]`
+- Extract all matches from note body on every write
+
+**Resolution algorithm** (FR-015, FR-016):
+1. Normalize `link_text` to slug: lowercase, replace spaces/underscores with dash, strip non-alphanumeric
+2. Match normalized slug against:
+   - Normalized filename stems (e.g., `api-design.md` → "api-design")
+   - Normalized frontmatter titles (e.g., `title: "API Design"` → "api-design")
+3. If multiple matches:
+   - Prefer same-folder match (e.g., `api/[[design]]` → `api/design.md` over `guides/design.md`)
+   - Tiebreaker: lexicographically smallest path
+4. If no match: `target_path = null`, `is_resolved = false`
+
+**Slug normalization function**:
+```python
+import re
+
+def normalize_slug(text: str) -> str:
+    text = text.lower()
+    text = re.sub(r'[\s_]+', '-', text)  # Spaces/underscores → dash
+    text = re.sub(r'[^a-z0-9-]', '', text)  # Keep alphanumeric + dash
+    text = re.sub(r'-+', '-', text)  # Collapse dashes
+    return text.strip('-')
+```
+
+**Backlinks**:
+- To get backlinks for `note_path`, query: `WHERE target_path = note_path`
+- Backlinks are automatically updated when any note's wikilinks change
+
+---
+
+### Tag
+
+A metadata label applied to notes for categorization.
+
+**Attributes**:
+- `user_id` (string, FK): Owner of the notes
+- `note_path` (string, FK): Path of tagged note
+- `tag_name` (string): Tag identifier (lowercase, alphanumeric + hyphens)
+
+**Constraints**:
+- Many-to-many relationship: one note can have multiple tags, one tag can apply to multiple notes
+- Tag names normalized: lowercase, strip whitespace
+- Extracted from frontmatter `tags: [tag1, tag2]` array
+
+**Tag count**:
+- Computed via `COUNT(DISTINCT note_path) GROUP BY tag_name`
+- Used for tag cloud and filtering UI
+
+---
+
+### Index Health
+
+Tracks the state and freshness of per-user indices.
+
+**Attributes**:
+- `user_id` (string, PK): Owner of the index
+- `note_count` (int): Total number of notes indexed
+- `last_full_rebuild` (datetime, nullable, ISO 8601): Timestamp of last full index rebuild
+- `last_incremental_update` (datetime, nullable, ISO 8601): Timestamp of last incremental update (write/delete)
+
+**Usage**:
+- Displayed in UI as index health indicator
+- Used to detect stale indices (e.g., `note_count` mismatch with actual file count)
+- Manual rebuild sets `last_full_rebuild = now()` (FR-019)
+- Every write/delete sets `last_incremental_update = now()` (FR-018)
+
+---
+
+## Authentication Entities
+
+### Token (JWT)
+
+A signed JSON Web Token used for API and MCP authentication.
+
+**JWT Claims** (payload):
+- `sub` (string): Subject (user_id)
+- `iat` (int): Issued at timestamp (Unix epoch)
+- `exp` (int): Expiration timestamp (Unix epoch, iat + 90 days)
+
+**Header**:
+- `alg: "HS256"`: HMAC SHA-256 signature algorithm
+- `typ: "JWT"`: Token type
+
+**Signature**:
+- Signed with server secret (env var `JWT_SECRET_KEY`)
+- Validated on every API/MCP request via `Authorization: Bearer <token>` header
+
+**Token lifecycle**:
+1. User authenticates via HF OAuth
+2. User calls `POST /api/tokens` to issue JWT
+3. Frontend stores token in memory (React context)
+4. MCP clients pass token to `auth` parameter (FastMCP HTTP transport)
+5. Server validates token on every request, extracts `user_id` from `sub` claim
+6. Token expires after 90 days, user must re-authenticate
+
+**Example token**:
+```json
+{
+  "header": {
+    "alg": "HS256",
+    "typ": "JWT"
+  },
+  "payload": {
+    "sub": "alice",
+    "iat": 1736956800,
+    "exp": 1744732800
+  },
+  "signature": "<HMAC-SHA256-signature>"
+}
+```
+
+Encoded: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhbGljZSIsImlhdCI6MTczNjk1NjgwMCwiZXhwIjoxNzQ0NzMyODAwfQ.<signature>`
+
+---
+
+## SQLite Schema
+
+Complete DDL for multi-index storage with per-user isolation.
+
+### Core Tables
+
+#### note_metadata
+
+Stores note metadata for fast lookups and version tracking.
+
+```sql
+CREATE TABLE IF NOT EXISTS note_metadata (
+    user_id TEXT NOT NULL,
+    note_path TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1,
+    title TEXT NOT NULL,
+    created TEXT NOT NULL,  -- ISO 8601 timestamp
+    updated TEXT NOT NULL,  -- ISO 8601 timestamp
+    size_bytes INTEGER NOT NULL DEFAULT 0,
+    normalized_title_slug TEXT,  -- Pre-computed for wikilink resolution
+    normalized_path_slug TEXT,   -- Pre-computed for wikilink resolution
+    PRIMARY KEY (user_id, note_path)
+);
+
+CREATE INDEX idx_metadata_user ON note_metadata(user_id);
+CREATE INDEX idx_metadata_updated ON note_metadata(user_id, updated DESC);
+CREATE INDEX idx_metadata_title_slug ON note_metadata(user_id, normalized_title_slug);
+CREATE INDEX idx_metadata_path_slug ON note_metadata(user_id, normalized_path_slug);
+```
+
+**Notes**:
+- Composite primary key: `(user_id, note_path)`
+- `version` starts at 1, increments on every write
+- `normalized_*_slug` columns enable O(1) wikilink resolution
+- Index on `updated DESC` for recency-based sorting
+
+---
+
+#### note_fts
+
+Full-text search index using SQLite FTS5.
+
+```sql
+CREATE VIRTUAL TABLE IF NOT EXISTS note_fts USING fts5(
+    user_id UNINDEXED,
+    note_path UNINDEXED,
+    title,
+    body,
+    content='',  -- Contentless (external content pattern)
+    tokenize='porter unicode61',  -- Stemming + Unicode support
+    prefix='2 3'  -- Prefix indexes for autocomplete
+);
+```
+
+**Notes**:
+- `content=''` (contentless): We manually INSERT/DELETE rows, no automatic sync
+- `UNINDEXED` columns are retrievable but not searchable (used for IDs)
+- `porter` tokenizer: English stemming (e.g., "running" matches "run")
+- `prefix='2 3'`: Enables fast `MATCH 'prefix*'` queries (2-char and 3-char prefixes)
+- Manual row management: On write, `DELETE` old row + `INSERT` new row
+- Ranking: Use `bm25(note_fts, 3.0, 1.0)` for title weight=3x, body weight=1x
+
+**Query example**:
+```sql
+SELECT
+    note_path,
+    title,
+    bm25(note_fts, 3.0, 1.0) AS rank
+FROM note_fts
+WHERE user_id = ? AND note_fts MATCH ?
+ORDER BY rank DESC
+LIMIT 50;
+```
+
+---
+
+#### note_tags
+
+Many-to-many junction table for note-tag relationships.
+
+```sql
+CREATE TABLE IF NOT EXISTS note_tags (
+    user_id TEXT NOT NULL,
+    note_path TEXT NOT NULL,
+    tag TEXT NOT NULL,
+    PRIMARY KEY (user_id, note_path, tag)
+);
+
+CREATE INDEX idx_tags_user_tag ON note_tags(user_id, tag);
+CREATE INDEX idx_tags_user_path ON note_tags(user_id, note_path);
+```
+
+**Notes**:
+- Composite primary key prevents duplicate tag assignments
+- Index on `(user_id, tag)` for "all notes with tag X" queries
+- Index on `(user_id, note_path)` for "all tags for note Y" queries
+
+**Query examples**:
+```sql
+-- Get all notes with tag "backend"
+SELECT DISTINCT note_path, title
+FROM note_tags t
+JOIN note_metadata m USING (user_id, note_path)
+WHERE t.user_id = ? AND t.tag = ?
+ORDER BY m.updated DESC;
+
+-- Get tag counts for user
+SELECT tag, COUNT(DISTINCT note_path) as count
+FROM note_tags
+WHERE user_id = ?
+GROUP BY tag
+ORDER BY count DESC;
+```
+
+---
+
+#### note_links
+
+Stores wikilink graph for backlink navigation.
+
+```sql
+CREATE TABLE IF NOT EXISTS note_links (
+    user_id TEXT NOT NULL,
+    source_path TEXT NOT NULL,
+    target_path TEXT,  -- NULL if unresolved
+    link_text TEXT NOT NULL,
+    is_resolved INTEGER NOT NULL DEFAULT 0,  -- Boolean: 0=broken, 1=resolved
+    PRIMARY KEY (user_id, source_path, link_text)
+);
+
+CREATE INDEX idx_links_user_source ON note_links(user_id, source_path);
+CREATE INDEX idx_links_user_target ON note_links(user_id, target_path);
+CREATE INDEX idx_links_unresolved ON note_links(user_id, is_resolved);
+```
+
+**Notes**:
+- `target_path` is nullable (null = broken link)
+- `is_resolved` is integer (0 or 1) for SQLite boolean representation
+- Composite primary key prevents duplicate links from same source with same text
+- Index on `target_path` enables fast backlink queries
+
+**Query examples**:
+```sql
+-- Get backlinks for a note
+SELECT DISTINCT l.source_path, m.title
+FROM note_links l
+JOIN note_metadata m ON l.user_id = m.user_id AND l.source_path = m.note_path
+WHERE l.user_id = ? AND l.target_path = ?
+ORDER BY m.updated DESC;
+
+-- Get all unresolved links for user
+SELECT source_path, link_text
+FROM note_links
+WHERE user_id = ? AND is_resolved = 0;
+```
+
+---
+
+#### index_health
+
+Tracks index state and freshness per user.
+
+```sql
+CREATE TABLE IF NOT EXISTS index_health (
+    user_id TEXT PRIMARY KEY,
+    note_count INTEGER NOT NULL DEFAULT 0,
+    last_full_rebuild TEXT,  -- ISO 8601 timestamp
+    last_incremental_update TEXT  -- ISO 8601 timestamp
+);
+```
+
+**Notes**:
+- One row per user
+- `last_full_rebuild` set on manual rebuild (FR-042)
+- `last_incremental_update` set on every write/delete (FR-018)
+- `note_count` is denormalized cache for quick health checks
+
+---
+
+### Initialization Script
+
+Complete schema initialization:
+
+```sql
+-- Enable FTS5 extension (usually built-in)
+-- PRAGMA compile_options;  -- Check if FTS5 is available
+
+BEGIN TRANSACTION;
+
+-- Core metadata table
+CREATE TABLE IF NOT EXISTS note_metadata (
+    user_id TEXT NOT NULL,
+    note_path TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1,
+    title TEXT NOT NULL,
+    created TEXT NOT NULL,
+    updated TEXT NOT NULL,
+    size_bytes INTEGER NOT NULL DEFAULT 0,
+    normalized_title_slug TEXT,
+    normalized_path_slug TEXT,
+    PRIMARY KEY (user_id, note_path)
+);
+
+CREATE INDEX IF NOT EXISTS idx_metadata_user ON note_metadata(user_id);
+CREATE INDEX IF NOT EXISTS idx_metadata_updated ON note_metadata(user_id, updated DESC);
+CREATE INDEX IF NOT EXISTS idx_metadata_title_slug ON note_metadata(user_id, normalized_title_slug);
+CREATE INDEX IF NOT EXISTS idx_metadata_path_slug ON note_metadata(user_id, normalized_path_slug);
+
+-- Full-text search index
+CREATE VIRTUAL TABLE IF NOT EXISTS note_fts USING fts5(
+    user_id UNINDEXED,
+    note_path UNINDEXED,
+    title,
+    body,
+    content='',
+    tokenize='porter unicode61',
+    prefix='2 3'
+);
+
+-- Tag index
+CREATE TABLE IF NOT EXISTS note_tags (
+    user_id TEXT NOT NULL,
+    note_path TEXT NOT NULL,
+    tag TEXT NOT NULL,
+    PRIMARY KEY (user_id, note_path, tag)
+);
+
+CREATE INDEX IF NOT EXISTS idx_tags_user_tag ON note_tags(user_id, tag);
+CREATE INDEX IF NOT EXISTS idx_tags_user_path ON note_tags(user_id, note_path);
+
+-- Link graph
+CREATE TABLE IF NOT EXISTS note_links (
+    user_id TEXT NOT NULL,
+    source_path TEXT NOT NULL,
+    target_path TEXT,
+    link_text TEXT NOT NULL,
+    is_resolved INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (user_id, source_path, link_text)
+);
+
+CREATE INDEX IF NOT EXISTS idx_links_user_source ON note_links(user_id, source_path);
+CREATE INDEX IF NOT EXISTS idx_links_user_target ON note_links(user_id, target_path);
+CREATE INDEX IF NOT EXISTS idx_links_unresolved ON note_links(user_id, is_resolved);
+
+-- Index health tracking
+CREATE TABLE IF NOT EXISTS index_health (
+    user_id TEXT PRIMARY KEY,
+    note_count INTEGER NOT NULL DEFAULT 0,
+    last_full_rebuild TEXT,
+    last_incremental_update TEXT
+);
+
+COMMIT;
+```
+
+---
+
+## Pydantic Models
+
+Python data models using Pydantic for validation and serialization.
+
+### User Models
+
+```python
+from pydantic import BaseModel, Field
+from datetime import datetime
+from typing import Optional
+
+
+class HFProfile(BaseModel):
+    """HuggingFace OAuth profile information."""
+    username: str = Field(..., description="HF username")
+    name: Optional[str] = Field(None, description="Display name")
+    avatar_url: Optional[str] = Field(None, description="Profile picture URL")
+
+
+class User(BaseModel):
+    """User account with authentication info."""
+    user_id: str = Field(..., min_length=1, max_length=64, description="Internal user ID")
+    hf_profile: Optional[HFProfile] = Field(None, description="HF OAuth profile")
+    vault_path: str = Field(..., description="Absolute path to user's vault")
+    created: datetime = Field(..., description="Account creation timestamp")
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "user_id": "alice",
+                "hf_profile": {
+                    "username": "alice",
+                    "name": "Alice Smith",
+                    "avatar_url": "https://cdn-avatars.huggingface.co/v1/alice"
+                },
+                "vault_path": "/data/vaults/alice",
+                "created": "2025-01-15T10:30:00Z"
+            }
+        }
+```
+
+---
+
+### Note Models
+
+```python
+from pathlib import Path
+import re
+
+
+class NoteMetadata(BaseModel):
+    """Frontmatter metadata (arbitrary key-value pairs)."""
+    title: Optional[str] = None
+    tags: Optional[list[str]] = None
+    project: Optional[str] = None
+    created: Optional[datetime] = None
+    updated: Optional[datetime] = None
+
+    class Config:
+        extra = "allow"  # Allow arbitrary fields
+
+
+class Note(BaseModel):
+    """Complete note with content and metadata."""
+    user_id: str = Field(..., description="Owner user ID")
+    note_path: str = Field(
+        ...,
+        min_length=1,
+        max_length=256,
+        description="Relative path to vault root (includes .md)"
+    )
+    version: int = Field(..., ge=1, description="Optimistic concurrency version")
+    title: str = Field(..., min_length=1, description="Display title")
+    metadata: NoteMetadata = Field(default_factory=NoteMetadata, description="Frontmatter")
+    body: str = Field(..., description="Markdown content")
+    created: datetime = Field(..., description="Creation timestamp")
+    updated: datetime = Field(..., description="Last update timestamp")
+    size_bytes: int = Field(..., ge=0, le=1_048_576, description="File size in bytes")
+
+    @validator("note_path")
+    def validate_path(cls, v):
+        """Validate note path format."""
+        # Must end with .md
+        if not v.endswith('.md'):
+            raise ValueError("Note path must end with .md")
+
+        # Must not contain ..
+        if '..' in v:
+            raise ValueError("Note path must not contain '..'")
+
+        # Must use Unix-style separators
+        if '\\' in v:
+            raise ValueError("Note path must use Unix-style separators (/)")
+
+        # Must not start with /
+        if v.startswith('/'):
+            raise ValueError("Note path must be relative (no leading /)")
+
+        return v
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "user_id": "alice",
+                "note_path": "api/design.md",
+                "version": 5,
+                "title": "API Design",
+                "metadata": {
+                    "tags": ["backend", "api"],
+                    "project": "auth-service"
+                },
+                "body": "# API Design\n\nThis document describes...",
+                "created": "2025-01-10T09:00:00Z",
+                "updated": "2025-01-15T14:30:00Z",
+                "size_bytes": 4096
+            }
+        }
+
+
+class NoteCreate(BaseModel):
+    """Request to create a new note."""
+    note_path: str = Field(..., min_length=1, max_length=256)
+    title: Optional[str] = None
+    metadata: Optional[NoteMetadata] = None
+    body: str = Field(..., max_length=1_048_576)
+
+
+class NoteUpdate(BaseModel):
+    """Request to update an existing note."""
+    title: Optional[str] = None
+    metadata: Optional[NoteMetadata] = None
+    body: str = Field(..., max_length=1_048_576)
+    if_version: Optional[int] = Field(None, ge=1, description="Expected version for concurrency check")
+
+
+class NoteSummary(BaseModel):
+    """Lightweight note summary for listings."""
+    note_path: str
+    title: str
+    updated: datetime
+```
+
+---
+
+### Index Models
+
+```python
+class Wikilink(BaseModel):
+    """Bidirectional link between notes."""
+    user_id: str
+    source_path: str
+    target_path: Optional[str] = Field(None, description="Null if unresolved")
+    link_text: str
+    is_resolved: bool
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "user_id": "alice",
+                "source_path": "api/design.md",
+                "target_path": "api/endpoints.md",
+                "link_text": "Endpoints",
+                "is_resolved": True
+            }
+        }
+
+
+class Tag(BaseModel):
+    """Tag with note count."""
+    tag_name: str
+    count: int = Field(..., ge=0)
+
+
+class IndexHealth(BaseModel):
+    """Index state and freshness metrics."""
+    user_id: str
+    note_count: int = Field(..., ge=0)
+    last_full_rebuild: Optional[datetime] = None
+    last_incremental_update: Optional[datetime] = None
+
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "user_id": "alice",
+                "note_count": 142,
+                "last_full_rebuild": "2025-01-01T00:00:00Z",
+                "last_incremental_update": "2025-01-15T14:30:00Z"
+            }
+        }
+```
+
+---
+
+### Search Models
+
+```python
+class SearchResult(BaseModel):
+    """Full-text search result with snippet."""
+    note_path: str
+    title: str
+    snippet: str = Field(..., description="Highlighted excerpt from body")
+    score: float = Field(..., description="Relevance score (title 3x, body 1x, recency bonus)")
+    updated: datetime
+
+
+class SearchRequest(BaseModel):
+    """Full-text search query."""
+    query: str = Field(..., min_length=1, max_length=256)
+    limit: int = Field(50, ge=1, le=100)
+```
+
+---
+
+### Authentication Models
+
+```python
+class TokenResponse(BaseModel):
+    """JWT token issuance response."""
+    token: str = Field(..., description="JWT access token")
+    token_type: str = Field("bearer", description="Token type")
+    expires_at: datetime = Field(..., description="Expiration timestamp")
+
+
+class JWTPayload(BaseModel):
+    """JWT claims payload."""
+    sub: str = Field(..., description="Subject (user_id)")
+    iat: int = Field(..., description="Issued at (Unix timestamp)")
+    exp: int = Field(..., description="Expiration (Unix timestamp)")
+```
+
+---
+
+## TypeScript Type Definitions
+
+Frontend type definitions for API contracts.
+
+### Core Types
+
+```typescript
+/**
+ * User account with HF profile
+ */
+export interface User {
+  user_id: string;
+  hf_profile?: {
+    username: string;
+    name?: string;
+    avatar_url?: string;
+  };
+  vault_path: string;
+  created: string;  // ISO 8601
+}
+
+/**
+ * Note metadata (frontmatter)
+ */
+export interface NoteMetadata {
+  title?: string;
+  tags?: string[];
+  project?: string;
+  created?: string;  // ISO 8601
+  updated?: string;  // ISO 8601
+  [key: string]: unknown;  // Arbitrary fields
+}
+
+/**
+ * Complete note with content
+ */
+export interface Note {
+  user_id: string;
+  note_path: string;
+  version: number;
+  title: string;
+  metadata: NoteMetadata;
+  body: string;
+  created: string;  // ISO 8601
+  updated: string;  // ISO 8601
+  size_bytes: number;
+}
+
+/**
+ * Lightweight note summary for listings
+ */
+export interface NoteSummary {
+  note_path: string;
+  title: string;
+  updated: string;  // ISO 8601
+}
+
+/**
+ * Request to create a note
+ */
+export interface NoteCreateRequest {
+  note_path: string;
+  title?: string;
+  metadata?: NoteMetadata;
+  body: string;
+}
+
+/**
+ * Request to update a note
+ */
+export interface NoteUpdateRequest {
+  title?: string;
+  metadata?: NoteMetadata;
+  body: string;
+  if_version?: number;  // Optimistic concurrency
+}
+
+/**
+ * Wikilink with resolution status
+ */
+export interface Wikilink {
+  user_id: string;
+  source_path: string;
+  target_path: string | null;  // Null if unresolved
+  link_text: string;
+  is_resolved: boolean;
+}
+
+/**
+ * Tag with note count
+ */
+export interface Tag {
+  tag_name: string;
+  count: number;
+}
+
+/**
+ * Index health metrics
+ */
+export interface IndexHealth {
+  user_id: string;
+  note_count: number;
+  last_full_rebuild: string | null;  // ISO 8601
+  last_incremental_update: string | null;  // ISO 8601
+}
+
+/**
+ * Search result with snippet
+ */
+export interface SearchResult {
+  note_path: string;
+  title: string;
+  snippet: string;
+  score: number;
+  updated: string;  // ISO 8601
+}
+
+/**
+ * JWT token response
+ */
+export interface TokenResponse {
+  token: string;
+  token_type: "bearer";
+  expires_at: string;  // ISO 8601
+}
+
+/**
+ * API error response
+ */
+export interface APIError {
+  error: string;
+  message: string;
+  detail?: Record<string, unknown>;
+}
+```
+
+---
+
+### Validation Helpers
+
+```typescript
+/**
+ * Validate note path format
+ */
+export function isValidNotePath(path: string): boolean {
+  return (
+    path.length > 0 &&
+    path.length <= 256 &&
+    path.endsWith('.md') &&
+    !path.includes('..') &&
+    !path.includes('\\') &&
+    !path.startsWith('/')
+  );
+}
+
+/**
+ * Normalize tag name (lowercase, trim)
+ */
+export function normalizeTag(tag: string): string {
+  return tag.toLowerCase().trim();
+}
+
+/**
+ * Normalize slug for wikilink resolution
+ */
+export function normalizeSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')  // Spaces/underscores → dash
+    .replace(/[^a-z0-9-]/g, '')  // Keep alphanumeric + dash
+    .replace(/-+/g, '-')  // Collapse dashes
+    .replace(/^-+|-+$/g, '');  // Trim dashes
+}
+
+/**
+ * Extract wikilinks from markdown body
+ */
+export function extractWikilinks(markdown: string): string[] {
+  const pattern = /\[\[([^\]]+)\]\]/g;
+  const matches: string[] = [];
+  let match;
+
+  while ((match = pattern.exec(markdown)) !== null) {
+    matches.push(match[1]);
+  }
+
+  return matches;
+}
+```
+
+---
+
+## Validation Rules
+
+Comprehensive validation constraints for all entities.
+
+### Note Path Validation
+
+```python
+import re
+from pathlib import Path
+
+def validate_note_path(path: str) -> tuple[bool, str]:
+    """
+    Validate note path format.
+
+    Returns (is_valid, error_message).
+    """
+    # Length check
+    if not path or len(path) > 256:
+        return False, "Path must be 1-256 characters"
+
+    # Must end with .md
+    if not path.endswith('.md'):
+        return False, "Path must end with .md"
+
+    # Must not contain ..
+    if '..' in path:
+        return False, "Path must not contain '..'"
+
+    # Must use Unix-style separators
+    if '\\' in path:
+        return False, "Path must use Unix separators (/)"
+
+    # Must be relative
+    if path.startswith('/'):
+        return False, "Path must be relative (no leading /)"
+
+    # Must not have invalid characters
+    invalid_chars = ['<', '>', ':', '"', '|', '?', '*']
+    if any(c in path for c in invalid_chars):
+        return False, f"Path contains invalid characters: {invalid_chars}"
+
+    return True, ""
+
+
+def sanitize_path(user_id: str, vault_root: str, note_path: str) -> Path:
+    """
+    Sanitize and resolve note path within vault.
+
+    Raises ValueError if path escapes vault root.
+    """
+    vault = Path(vault_root) / user_id
+    full_path = (vault / note_path).resolve()
+
+    # Ensure path is within vault
+    if not str(full_path).startswith(str(vault.resolve())):
+        raise ValueError(f"Path escapes vault root: {note_path}")
+
+    return full_path
+```
+
+---
+
+### Note Content Validation
+
+```python
+def validate_note_content(body: str) -> tuple[bool, str]:
+    """
+    Validate note content.
+
+    Returns (is_valid, error_message).
+    """
+    # Size check (1 MiB max)
+    size_bytes = len(body.encode('utf-8'))
+    if size_bytes > 1_048_576:
+        return False, f"Note exceeds 1 MiB limit ({size_bytes} bytes)"
+
+    # UTF-8 validity
+    try:
+        body.encode('utf-8')
+    except UnicodeEncodeError as e:
+        return False, f"Invalid UTF-8 encoding: {e}"
+
+    return True, ""
+
+
+def validate_frontmatter(metadata: dict) -> tuple[bool, str]:
+    """
+    Validate frontmatter metadata.
+
+    Returns (is_valid, error_message).
+    """
+    # Check for reserved fields
+    reserved = ['version']  # Version is managed by index, not frontmatter
+    for key in metadata.keys():
+        if key in reserved:
+            return False, f"Field '{key}' is reserved and cannot be set in frontmatter"
+
+    # Validate tags format
+    if 'tags' in metadata:
+        tags = metadata['tags']
+        if not isinstance(tags, list):
+            return False, "Field 'tags' must be an array"
+
+        if not all(isinstance(t, str) for t in tags):
+            return False, "All tags must be strings"
+
+    return True, ""
+```
+
+---
+
+### Vault Limits
+
+```python
+def check_vault_limit(user_id: str, db) -> tuple[bool, str]:
+    """
+    Check if vault is within note limit.
+
+    Returns (is_allowed, error_message).
+    """
+    cursor = db.execute(
+        "SELECT note_count FROM index_health WHERE user_id = ?",
+        (user_id,)
+    )
+    row = cursor.fetchone()
+
+    if row is None:
+        return True, ""  # New vault, no limit yet
+
+    note_count = row[0]
+
+    if note_count >= 5000:
+        return False, "Vault note limit exceeded (max 5,000 notes)"
+
+    return True, ""
+```
+
+---
+
+### Token Validation
+
+```python
+import jwt
+from datetime import datetime, timedelta
+
+SECRET_KEY = "your-secret-key"  # From env var
+
+def create_jwt(user_id: str) -> str:
+    """Create JWT with 90-day expiration."""
+    now = datetime.utcnow()
+    payload = {
+        "sub": user_id,
+        "iat": int(now.timestamp()),
+        "exp": int((now + timedelta(days=90)).timestamp())
+    }
+    return jwt.encode(payload, SECRET_KEY, algorithm="HS256")
+
+
+def validate_jwt(token: str) -> tuple[bool, str, str]:
+    """
+    Validate JWT and extract user_id.
+
+    Returns (is_valid, user_id, error_message).
+    """
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
+        user_id = payload["sub"]
+        return True, user_id, ""
+
+    except jwt.ExpiredSignatureError:
+        return False, "", "Token expired"
+
+    except jwt.InvalidTokenError as e:
+        return False, "", f"Invalid token: {e}"
+```
+
+---
+
+## State Transitions
+
+State machines for entity lifecycle and version management.
+
+### Note Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> Creating: write_note (new path)
+    Creating --> Active: save to filesystem + insert metadata
+    Active --> Updating: write_note (existing path)
+    Updating --> Active: increment version + update index
+    Active --> Deleting: delete_note
+    Deleting --> [*]: remove file + delete index rows
+
+    Updating --> ConflictDetected: if_version mismatch (UI writes only)
+    ConflictDetected --> Active: reload or discard changes
+```
+
+**State descriptions**:
+
+1. **Creating**: Note does not exist, first write in progress
+   - Validate path and content
+   - Set `version = 1`, `created = now()`, `updated = now()`
+   - Write file to filesystem
+   - Insert rows into `note_metadata`, `note_fts`, `note_tags`, `note_links`
+
+2. **Active**: Note exists and is readable/editable
+   - Can be read via API/MCP
+   - Can be updated via write_note
+   - Can be deleted via delete_note
+
+3. **Updating**: Modification in progress
+   - Load current metadata (version, timestamps)
+   - If UI write: check `if_version` matches current version
+   - If version mismatch: transition to ConflictDetected
+   - If MCP write: skip version check (last-write-wins)
+   - Increment `version`, set `updated = now()`
+   - Update file content
+   - Update all index rows (delete old, insert new)
+
+4. **ConflictDetected**: Optimistic concurrency conflict (UI only)
+   - Return `409 Conflict` with current and expected versions
+   - UI displays error: "Note changed since you opened it"
+   - User options: reload, save as copy, or discard changes
+
+5. **Deleting**: Removal in progress
+   - Delete file from filesystem
+   - Delete rows from `note_metadata`, `note_fts`, `note_tags`, `note_links`
+   - Update backlinks (any note linking to deleted note now has unresolved link)
+   - Decrement `index_health.note_count`
+
+---
+
+### Version Increment Logic
+
+```python
+def increment_version(user_id: str, note_path: str, if_version: int | None, db) -> int:
+    """
+    Increment note version with optional concurrency check.
+
+    Returns new version number.
+    Raises ConflictError if if_version doesn't match.
+    """
+    # Get current version
+    cursor = db.execute(
+        "SELECT version FROM note_metadata WHERE user_id = ? AND note_path = ?",
+        (user_id, note_path)
+    )
+    row = cursor.fetchone()
+
+    if row is None:
+        # New note
+        return 1
+
+    current_version = row[0]
+
+    # Optimistic concurrency check (UI writes only)
+    if if_version is not None and current_version != if_version:
+        raise ConflictError(
+            f"Version conflict: expected {if_version}, current is {current_version}"
+        )
+
+    # Increment version
+    new_version = current_version + 1
+
+    return new_version
+```
+
+---
+
+### Index Update Workflow
+
+```mermaid
+stateDiagram-v2
+    [*] --> IncrementalUpdate: write_note or delete_note
+    IncrementalUpdate --> DeleteOldRows: start transaction
+    DeleteOldRows --> ExtractMetadata: parse frontmatter + body
+    ExtractMetadata --> InsertNewRows: insert into all index tables
+    InsertNewRows --> UpdateHealth: set last_incremental_update
+    UpdateHealth --> [*]: commit transaction
+
+    [*] --> FullRebuild: POST /api/index/rebuild
+    FullRebuild --> DropUserRows: delete all rows for user_id
+    DropUserRows --> ScanVault: walk filesystem tree
+    ScanVault --> ProcessNote: for each .md file
+    ProcessNote --> ExtractMetadata
+    ProcessNote --> ScanVault: next file
+    ScanVault --> UpdateHealth: set last_full_rebuild
+    UpdateHealth --> [*]: commit transaction
+```
+
+**Incremental update** (on every write/delete):
+1. Start SQLite transaction
+2. Delete all existing rows for `(user_id, note_path)` from:
+   - `note_metadata`
+   - `note_fts`
+   - `note_tags`
+   - `note_links`
+3. Parse note content (frontmatter + body)
+4. Extract: title, tags, wikilinks
+5. Insert new rows into all index tables
+6. Resolve wikilinks and update `is_resolved` flags
+7. Update `index_health.last_incremental_update = now()`
+8. Commit transaction
+
+**Full rebuild** (manual trigger):
+1. Start SQLite transaction
+2. Delete all rows for `user_id` from all index tables
+3. Walk vault directory tree, find all `.md` files
+4. For each file:
+   - Parse frontmatter + body
+   - Extract metadata, tags, wikilinks
+   - Insert rows into all index tables
+5. Resolve all wikilinks (second pass after all notes indexed)
+6. Update `index_health.note_count` and `last_full_rebuild = now()`
+7. Commit transaction
+
+---
+
+## Relationships and Constraints
+
+### Foreign Key Relationships
+
+While SQLite supports foreign keys, we don't enforce them for performance reasons (multi-tenant with user-scoped queries). Instead, we rely on application-level referential integrity.
+
+**Logical relationships**:
+- `note_metadata.user_id` → `User.user_id`
+- `note_tags.note_path` → `note_metadata.note_path`
+- `note_links.source_path` → `note_metadata.note_path`
+- `note_links.target_path` → `note_metadata.note_path` (nullable)
+
+**Cascade semantics** (application-enforced):
+- On delete note: cascade delete from `note_tags`, `note_links` (source), `note_fts`
+- On delete note: update `note_links` (target) to set `is_resolved = false`
+
+---
+
+### Uniqueness Constraints
+
+| Table | Unique Constraint | Enforced By |
+|-------|------------------|-------------|
+| `note_metadata` | `(user_id, note_path)` | PRIMARY KEY |
+| `note_tags` | `(user_id, note_path, tag)` | PRIMARY KEY |
+| `note_links` | `(user_id, source_path, link_text)` | PRIMARY KEY |
+| `index_health` | `user_id` | PRIMARY KEY |
+
+---
+
+### Cardinality
+
+| Relationship | Type | Notes |
+|-------------|------|-------|
+| User → Vault | 1:1 | One user owns one vault |
+| Vault → Notes | 1:N | One vault contains many notes (max 5,000) |
+| Note → Tags | N:M | Many-to-many via `note_tags` junction table |
+| Note → Outgoing Links | 1:N | One note has many outgoing wikilinks |
+| Note → Backlinks | 1:N | One note may be referenced by many backlinks |
+| User → Tokens | 1:N | One user can issue multiple JWT tokens |
+
+---
+
+### Invariants
+
+Critical invariants maintained by the system:
+
+1. **Version monotonicity**: `note.version` only increases (never decreases or resets)
+2. **Timestamp ordering**: `note.created <= note.updated` always
+3. **Path uniqueness**: No two notes with same `(user_id, note_path)` can exist
+4. **Size limit**: `note.size_bytes <= 1_048_576` always enforced
+5. **Vault limit**: `COUNT(*) WHERE user_id = X <= 5000` enforced before writes
+6. **Link consistency**: If `note_links.target_path` is not null, target note must exist
+7. **Tag normalization**: All `note_tags.tag` values are lowercase
+8. **Index freshness**: `index_health.last_incremental_update` is always >= most recent `note_metadata.updated` for that user
+
+---
+
+## Appendix
+
+### Common Queries Reference
+
+```sql
+-- Get all notes for user, sorted by recent update
+SELECT note_path, title, updated
+FROM note_metadata
+WHERE user_id = ?
+ORDER BY updated DESC
+LIMIT 100;
+
+-- Full-text search with title boost
+SELECT
+    note_path,
+    title,
+    snippet(note_fts, 3, '<mark>', '</mark>', '...', 32) AS snippet,
+    bm25(note_fts, 3.0, 1.0) AS score
+FROM note_fts
+WHERE user_id = ? AND note_fts MATCH ?
+ORDER BY score DESC
+LIMIT 50;
+
+-- Get all tags with counts
+SELECT tag, COUNT(DISTINCT note_path) as count
+FROM note_tags
+WHERE user_id = ?
+GROUP BY tag
+ORDER BY count DESC;
+
+-- Get backlinks for a note
+SELECT DISTINCT l.source_path, m.title
+FROM note_links l
+JOIN note_metadata m ON l.user_id = m.user_id AND l.source_path = m.note_path
+WHERE l.user_id = ? AND l.target_path = ?
+ORDER BY m.updated DESC;
+
+-- Get all unresolved wikilinks for a user
+SELECT source_path, link_text, COUNT(*) as occurrences
+FROM note_links
+WHERE user_id = ? AND is_resolved = 0
+GROUP BY source_path, link_text
+ORDER BY occurrences DESC;
+
+-- Check index health
+SELECT note_count, last_full_rebuild, last_incremental_update
+FROM index_health
+WHERE user_id = ?;
+```
+
+---
+
+### Migration Strategy
+
+For future schema changes:
+
+```python
+# Example migration: Add column to note_metadata
+def migrate_v1_to_v2(db):
+    """Add normalized_title_slug column."""
+    db.execute("""
+        ALTER TABLE note_metadata
+        ADD COLUMN normalized_title_slug TEXT;
+    """)
+
+    # Backfill existing notes
+    db.execute("""
+        UPDATE note_metadata
+        SET normalized_title_slug = LOWER(
+            REPLACE(REPLACE(title, ' ', '-'), '_', '-')
+        );
+    """)
+
+    db.execute("""
+        CREATE INDEX idx_metadata_title_slug
+        ON note_metadata(user_id, normalized_title_slug);
+    """)
+
+    db.commit()
+```
+
+---
+
+**Document Status**: Draft
+**Last Updated**: 2025-11-15
+**Next Review**: After Phase 1 implementation

specs/001-obsidian-docs-viewer/plan.md

@@ -186,4 +186,60 @@ README.md                # Setup instructions, MCP client config examples
 
 ---
 
-**Plan Status**: Phase 0 and Phase 1 execution in progress below...
+## Execution Summary
+
+### Phase 0: Research & Technical Decisions ✅ COMPLETE
+
+**Generated**: `research.md` (1,407 lines)
+
+**Researched and Resolved**:
+1. ✅ FastMCP HTTP transport authentication patterns → Bearer token with `BearerAuth`, JWT validation
+2. ✅ Hugging Face Space OAuth integration → `attach_huggingface_oauth` + `parse_huggingface_oauth` helpers
+3. ✅ SQLite schema design → FTS5 contentless + separate tags/links tables with per-user isolation
+4. ✅ Wikilink normalization → Case-insensitive normalized slug matching, same-folder preference
+5. ✅ React + shadcn/ui directory tree → shadcn-extension Tree View with TanStack Virtual virtualization
+6. ✅ Optimistic concurrency → Version counter in SQLite + `if_version` parameter, 409 on mismatch
+7. ✅ Markdown frontmatter parsing → `python-frontmatter` with try-except fallback for malformed YAML
+8. ✅ JWT token management → Memory storage (MVP) or memory + HttpOnly cookie (production)
+
+**Key Decisions**:
+- FTS5 with porter tokenizer and `prefix='2 3'` for autocomplete
+- shadcn-extension tree handles 5,000+ notes with <200ms render
+- Version counter is simpler and faster than content hashing
+- Hybrid JWT approach (memory + HttpOnly) is 2025 security best practice
+
+### Phase 1: Data Model & Contracts ✅ COMPLETE
+
+**Generated**:
+- `data-model.md` - Complete entity definitions, Pydantic models, TypeScript types, SQLite schema, validation rules, state transitions
+- `contracts/http-api.yaml` - OpenAPI 3.1 spec with 11 endpoints, auth, all error responses, examples
+- `contracts/mcp-tools.json` - 7 MCP tool schemas with JSON Schema validation, usage examples
+- `quickstart.md` - Complete setup, run, test, deploy guide for local PoC and HF Space
+
+**Data Model Highlights**:
+- 7 core entities (User, Vault, Note, Wikilink, Tag, Index, Token)
+- Complete Pydantic models with validators
+- TypeScript types for frontend
+- SQLite DDL with 5 tables (metadata, FTS, tags, links, health)
+- State machines for note lifecycle and index updates
+
+**API Contract Highlights**:
+- HTTP API: 11 endpoints (auth, CRUD, search, navigation, index)
+- MCP Tools: 7 tools (list, read, write, delete, search, backlinks, tags)
+- All error codes documented (400, 401, 403, 409, 413, 500)
+- Request/response examples for all operations
+
+**Agent Context Updated**:
+- ✅ Updated `/home/wolfe/Projects/Document-MCP/CLAUDE.md` with Python 3.11+, FastAPI, FastMCP, SQLite tech stack
+
+### Constitution Re-Check ✅ N/A
+
+**Status**: No project constitution exists. Design decisions documented in research.md can form future constitution baseline.
+
+---
+
+## Next Steps
+
+Run `/speckit.tasks` to generate dependency-ordered implementation tasks based on this plan, data model, and contracts.
+
+**Planning Phase Complete**: 2025-11-15

specs/001-obsidian-docs-viewer/quickstart.md

@@ -0,0 +1,1455 @@
+# Quickstart Guide: Multi-Tenant Obsidian-Like Docs Viewer
+
+**Feature Branch**: `001-obsidian-docs-viewer`
+**Created**: 2025-11-15
+**Status**: Draft
+
+---
+
+## Table of Contents
+
+1. [Prerequisites](#prerequisites)
+2. [Local Development Setup](#local-development-setup)
+3. [Running the Backend](#running-the-backend)
+4. [Running the Frontend](#running-the-frontend)
+5. [MCP Client Configuration](#mcp-client-configuration)
+6. [Testing Workflows](#testing-workflows)
+7. [Development Workflows](#development-workflows)
+8. [Hugging Face Space Deployment](#hugging-face-space-deployment)
+9. [Troubleshooting](#troubleshooting)
+
+---
+
+## Prerequisites
+
+Before starting, ensure you have the following installed:
+
+### Required Software
+
+- **Python**: 3.11 or higher
+  - Check version: `python --version` or `python3 --version`
+  - Download: https://www.python.org/downloads/
+
+- **Node.js**: 18 or higher
+  - Check version: `node --version`
+  - Download: https://nodejs.org/
+
+- **Git**: Any recent version
+  - Check version: `git --version`
+  - Download: https://git-scm.com/downloads/
+
+### Optional Tools
+
+- **Poetry** (recommended for Python dependency management): `pip install poetry`
+- **Claude Desktop** or **Claude Code** (for MCP STDIO integration)
+- **Docker** (for containerized deployment testing)
+
+---
+
+## Local Development Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone <repository-url>
+cd Document-MCP
+```
+
+### 2. Create Environment Configuration
+
+Copy the example environment file and customize it:
+
+```bash
+cp .env.example .env
+```
+
+**`.env.example` contents**:
+
+```bash
+# Application Mode
+# Options: "local" (single-user development) or "space" (multi-tenant HF Space)
+MODE=local
+
+# JWT Secret Key
+# IMPORTANT: Generate a secure random string for production
+# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+JWT_SECRET_KEY=your-secret-key-change-in-production
+
+# Vault Storage
+# Base directory for per-user vault storage
+VAULT_BASE_DIR=./data/vaults
+
+# SQLite Database
+# Path to SQLite database file
+DB_PATH=./data/index.db
+
+# Local Mode Configuration
+# Default user ID for local development (no authentication)
+LOCAL_USER_ID=local-dev
+
+# Optional: Static Bearer Token for Local Mode
+# Leave empty to disable token requirement in local mode
+# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+LOCAL_STATIC_TOKEN=
+
+# Hugging Face Space Configuration (only needed for HF deployment)
+# HF_OAUTH_CLIENT_ID=your-hf-client-id
+# HF_OAUTH_CLIENT_SECRET=your-hf-client-secret
+# HF_SPACE_HOST=https://your-space.hf.space
+
+# Backend Server
+BACKEND_HOST=0.0.0.0
+BACKEND_PORT=8000
+
+# Frontend Development
+VITE_API_BASE_URL=http://localhost:8000
+```
+
+**Generate secure secrets**:
+
+```bash
+# Generate JWT secret
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+
+# Generate optional local static token
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+Update `.env` with generated values.
+
+### 3. Backend Setup
+
+Navigate to the backend directory:
+
+```bash
+cd backend
+```
+
+#### Option A: Using Poetry (Recommended)
+
+```bash
+# Install Poetry if not already installed
+pip install poetry
+
+# Install dependencies
+poetry install
+
+# Activate virtual environment
+poetry shell
+```
+
+#### Option B: Using pip with venv
+
+```bash
+# Create virtual environment
+python -m venv venv
+
+# Activate virtual environment
+# On Windows:
+venv\Scripts\activate
+# On macOS/Linux:
+source venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+**`requirements.txt` example**:
+
+```txt
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+fastmcp==0.3.0
+python-frontmatter==1.0.1
+PyJWT==2.8.0
+huggingface-hub==0.19.4
+pydantic==2.5.0
+python-multipart==0.0.6
+aiosqlite==0.19.0
+```
+
+### 4. Initialize Database Schema
+
+Run the database initialization script:
+
+```bash
+# From backend/ directory
+python -m src.services.init_db
+```
+
+**`src/services/init_db.py` (create this file)**:
+
+```python
+"""
+Database initialization script.
+Creates SQLite schema and indexes.
+"""
+import sqlite3
+import os
+from pathlib import Path
+
+def init_database(db_path: str):
+    """Initialize SQLite database with schema."""
+    # Ensure directory exists
+    db_file = Path(db_path)
+    db_file.parent.mkdir(parents=True, exist_ok=True)
+
+    conn = sqlite3.connect(db_path)
+    cursor = conn.cursor()
+
+    # Begin transaction
+    cursor.execute("BEGIN TRANSACTION")
+
+    # Core metadata table
+    cursor.execute("""
+        CREATE TABLE IF NOT EXISTS note_metadata (
+            user_id TEXT NOT NULL,
+            note_path TEXT NOT NULL,
+            version INTEGER NOT NULL DEFAULT 1,
+            title TEXT NOT NULL,
+            created TEXT NOT NULL,
+            updated TEXT NOT NULL,
+            size_bytes INTEGER NOT NULL DEFAULT 0,
+            normalized_title_slug TEXT,
+            normalized_path_slug TEXT,
+            PRIMARY KEY (user_id, note_path)
+        )
+    """)
+
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_metadata_user ON note_metadata(user_id)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_metadata_updated ON note_metadata(user_id, updated DESC)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_metadata_title_slug ON note_metadata(user_id, normalized_title_slug)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_metadata_path_slug ON note_metadata(user_id, normalized_path_slug)")
+
+    # Full-text search index
+    cursor.execute("""
+        CREATE VIRTUAL TABLE IF NOT EXISTS note_fts USING fts5(
+            user_id UNINDEXED,
+            note_path UNINDEXED,
+            title,
+            body,
+            content='',
+            tokenize='porter unicode61',
+            prefix='2 3'
+        )
+    """)
+
+    # Tag index
+    cursor.execute("""
+        CREATE TABLE IF NOT EXISTS note_tags (
+            user_id TEXT NOT NULL,
+            note_path TEXT NOT NULL,
+            tag TEXT NOT NULL,
+            PRIMARY KEY (user_id, note_path, tag)
+        )
+    """)
+
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_tags_user_tag ON note_tags(user_id, tag)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_tags_user_path ON note_tags(user_id, note_path)")
+
+    # Link graph
+    cursor.execute("""
+        CREATE TABLE IF NOT EXISTS note_links (
+            user_id TEXT NOT NULL,
+            source_path TEXT NOT NULL,
+            target_path TEXT,
+            link_text TEXT NOT NULL,
+            is_resolved INTEGER NOT NULL DEFAULT 0,
+            PRIMARY KEY (user_id, source_path, link_text)
+        )
+    """)
+
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_links_user_source ON note_links(user_id, source_path)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_links_user_target ON note_links(user_id, target_path)")
+    cursor.execute("CREATE INDEX IF NOT EXISTS idx_links_unresolved ON note_links(user_id, is_resolved)")
+
+    # Index health tracking
+    cursor.execute("""
+        CREATE TABLE IF NOT EXISTS index_health (
+            user_id TEXT PRIMARY KEY,
+            note_count INTEGER NOT NULL DEFAULT 0,
+            last_full_rebuild TEXT,
+            last_incremental_update TEXT
+        )
+    """)
+
+    # Commit transaction
+    cursor.execute("COMMIT")
+
+    conn.close()
+    print(f"Database initialized at: {db_path}")
+
+if __name__ == "__main__":
+    # Load DB path from environment or use default
+    db_path = os.getenv("DB_PATH", "./data/index.db")
+    init_database(db_path)
+```
+
+Run initialization:
+
+```bash
+python -m src.services.init_db
+```
+
+Expected output:
+```
+Database initialized at: ./data/index.db
+```
+
+### 5. Create Vault Directory Structure
+
+```bash
+# From project root
+mkdir -p data/vaults/local-dev
+
+# Create a test note
+cat > data/vaults/local-dev/README.md << 'EOF'
+---
+title: Welcome to Your Vault
+tags: [getting-started]
+created: 2025-01-15T10:00:00Z
+updated: 2025-01-15T10:00:00Z
+---
+
+# Welcome to Your Vault
+
+This is your personal documentation vault.
+
+## Features
+
+- **AI-powered writing**: Use MCP tools to create and update notes
+- **Full-text search**: Search across all notes instantly
+- **Wikilinks**: Link notes together with `[[Note Name]]` syntax
+- **Tags**: Organize notes with frontmatter tags
+
+## Getting Started
+
+Try creating your first note:
+- Via MCP: Use the `write_note` tool
+- Via UI: Click "New Note" in the sidebar
+
+Check out [[Quick Start Guide]] for more details.
+EOF
+```
+
+### 6. Frontend Setup
+
+Open a new terminal and navigate to the frontend directory:
+
+```bash
+cd frontend
+```
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+**`package.json` example**:
+
+```json
+{
+  "name": "obsidian-docs-viewer-frontend",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:e2e": "playwright test",
+    "lint": "eslint src --ext ts,tsx"
+  },
+  "dependencies": {
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-router-dom": "^6.20.0",
+    "react-markdown": "^9.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "@radix-ui/react-dialog": "^1.0.5",
+    "@radix-ui/react-dropdown-menu": "^2.0.6",
+    "@radix-ui/react-scroll-area": "^1.0.5",
+    "@radix-ui/react-separator": "^1.0.3",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.0.0",
+    "tailwind-merge": "^2.1.0",
+    "lucide-react": "^0.295.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.43",
+    "@types/react-dom": "^18.2.17",
+    "@typescript-eslint/eslint-plugin": "^6.14.0",
+    "@typescript-eslint/parser": "^6.14.0",
+    "@vitejs/plugin-react": "^4.2.1",
+    "autoprefixer": "^10.4.16",
+    "eslint": "^8.55.0",
+    "postcss": "^8.4.32",
+    "tailwindcss": "^3.3.6",
+    "typescript": "^5.2.2",
+    "vite": "^5.0.8",
+    "vitest": "^1.0.4",
+    "@playwright/test": "^1.40.0"
+  }
+}
+```
+
+Configure API base URL (if not already in `.env`):
+
+```bash
+# frontend/.env
+VITE_API_BASE_URL=http://localhost:8000
+```
+
+---
+
+## Running the Backend
+
+The backend can be run in multiple modes depending on your use case.
+
+### Mode 1: FastAPI HTTP Server (for UI access)
+
+Start the FastAPI development server:
+
+```bash
+# From backend/ directory (with venv activated)
+uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+Expected output:
+```
+INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [12345] using StatReload
+INFO:     Started server process [12346]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+```
+
+**Test the API**:
+
+```bash
+# Health check
+curl http://localhost:8000/api/health
+
+# Expected response:
+# {"status": "ok", "mode": "local"}
+
+# Get user info (local mode)
+curl http://localhost:8000/api/me
+
+# Expected response:
+# {"user_id": "local-dev", "vault_path": "./data/vaults/local-dev"}
+```
+
+### Mode 2: MCP STDIO Server (for Claude Code/Desktop)
+
+Start the MCP server in STDIO mode:
+
+```bash
+# From backend/ directory
+python -m src.mcp.server
+```
+
+Expected output:
+```
+MCP server starting in STDIO mode...
+Listening for MCP requests on stdin/stdout...
+```
+
+This server communicates via standard input/output and is designed to be invoked by MCP clients like Claude Desktop.
+
+### Mode 3: MCP HTTP Server (for remote MCP access)
+
+Start the MCP server with HTTP transport:
+
+```bash
+# From backend/ directory
+python -m src.mcp.server --http --port 8001
+```
+
+Expected output:
+```
+MCP server starting in HTTP mode...
+Server running at: http://0.0.0.0:8001
+Authentication: Bearer token required
+```
+
+**Test MCP HTTP endpoint**:
+
+```bash
+# Issue a token first (if using authentication)
+curl -X POST http://localhost:8000/api/tokens
+
+# Use token to call MCP tool
+curl -X POST http://localhost:8001/mcp/call \
+  -H "Authorization: Bearer <your-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "list_notes",
+    "arguments": {}
+  }'
+```
+
+### Run All Backend Services (Production Mode)
+
+For production, run both servers together:
+
+```bash
+# Terminal 1: FastAPI server
+uvicorn src.api.main:app --host 0.0.0.0 --port 8000
+
+# Terminal 2: MCP HTTP server
+python -m src.mcp.server --http --port 8001
+```
+
+Or use a process manager like `supervisord` or `pm2`.
+
+---
+
+## Running the Frontend
+
+Start the Vite development server:
+
+```bash
+# From frontend/ directory
+npm run dev
+```
+
+Expected output:
+```
+  VITE v5.0.8  ready in 523 ms
+
+  ➜  Local:   http://localhost:5173/
+  ➜  Network: use --host to expose
+  ➜  press h to show help
+```
+
+Open your browser to **http://localhost:5173**
+
+### Local Mode UI Flow
+
+1. **Landing page**: In local mode, you'll be automatically authenticated as `local-dev`
+2. **Directory pane** (left sidebar):
+   - Shows vault folder structure
+   - Click on folders to expand/collapse
+   - Click on notes to view content
+3. **Search bar** (top of left sidebar):
+   - Type to search notes
+   - Results appear in dropdown with snippets
+4. **Main pane** (right side):
+   - View rendered Markdown
+   - Click "Edit" to enter edit mode
+   - Click wikilinks to navigate between notes
+5. **Footer** (below main pane):
+   - View tags (clickable chips)
+   - See created/updated timestamps
+   - View backlinks (notes that reference current note)
+
+### Configure Static Token (Optional)
+
+If you set `LOCAL_STATIC_TOKEN` in `.env`, configure the frontend:
+
+**In browser console** (http://localhost:5173):
+
+```javascript
+localStorage.setItem('auth_token', 'your-static-token-from-env');
+location.reload();
+```
+
+Or update `frontend/src/services/auth.ts` to automatically use the token in local mode.
+
+---
+
+## MCP Client Configuration
+
+### Claude Desktop (STDIO)
+
+Configure Claude Desktop to use the MCP STDIO server.
+
+**Config file location**:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+**`claude_desktop_config.json`**:
+
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "command": "python",
+      "args": [
+        "-m",
+        "src.mcp.server"
+      ],
+      "cwd": "/absolute/path/to/Document-MCP/backend",
+      "env": {
+        "MODE": "local",
+        "VAULT_BASE_DIR": "/absolute/path/to/Document-MCP/data/vaults",
+        "DB_PATH": "/absolute/path/to/Document-MCP/data/index.db",
+        "LOCAL_USER_ID": "local-dev"
+      }
+    }
+  }
+}
+```
+
+**Important**: Replace `/absolute/path/to/Document-MCP` with your actual project path.
+
+**Test in Claude Desktop**:
+
+1. Restart Claude Desktop
+2. Open a conversation
+3. Try: "List all notes in my vault"
+4. Claude should call the `list_notes` MCP tool
+
+### Claude Code (STDIO)
+
+Claude Code uses a similar configuration. Create or edit `~/.claude/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "command": "python",
+      "args": ["-m", "src.mcp.server"],
+      "cwd": "/absolute/path/to/Document-MCP/backend",
+      "env": {
+        "MODE": "local",
+        "VAULT_BASE_DIR": "/absolute/path/to/Document-MCP/data/vaults",
+        "DB_PATH": "/absolute/path/to/Document-MCP/data/index.db"
+      }
+    }
+  }
+}
+```
+
+### MCP HTTP Transport (Remote Access)
+
+For remote access (e.g., from HF Space or external tools), use HTTP transport.
+
+**Setup**:
+
+1. Start MCP HTTP server:
+   ```bash
+   python -m src.mcp.server --http --port 8001
+   ```
+
+2. Issue a JWT token:
+   ```bash
+   curl -X POST http://localhost:8000/api/tokens
+   ```
+
+   Response:
+   ```json
+   {
+     "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+     "token_type": "bearer",
+     "expires_at": "2025-04-15T10:30:00Z"
+   }
+   ```
+
+3. Configure MCP client with HTTP endpoint:
+
+**Example HTTP MCP client configuration** (pseudo-code):
+
+```json
+{
+  "mcp_endpoint": "http://localhost:8001/mcp",
+  "auth": {
+    "type": "bearer",
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+**Manual HTTP MCP call**:
+
+```bash
+curl -X POST http://localhost:8001/mcp/call \
+  -H "Authorization: Bearer <your-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "write_note",
+    "arguments": {
+      "path": "test/hello.md",
+      "title": "Hello World",
+      "body": "# Hello World\n\nThis is a test note created via MCP HTTP."
+    }
+  }'
+```
+
+Expected response:
+```json
+{
+  "status": "ok",
+  "path": "test/hello.md"
+}
+```
+
+---
+
+## Testing Workflows
+
+### Backend Unit Tests
+
+Run pytest for unit tests:
+
+```bash
+# From backend/ directory
+pytest tests/unit -v
+```
+
+**Example test structure**:
+
+```
+backend/tests/
+├── unit/
+│   ├── test_vault.py          # Vault service tests
+│   ├── test_indexer.py        # Indexer service tests
+│   ├── test_auth.py           # Auth service tests
+│   └── test_wikilink.py       # Wikilink resolution tests
+├── integration/
+│   ├── test_api_notes.py      # API integration tests
+│   ├── test_api_search.py     # Search API tests
+│   └── test_mcp_tools.py      # MCP tool integration tests
+└── contract/
+    ├── test_http_api_contract.py   # OpenAPI contract validation
+    └── test_mcp_contract.py        # MCP tool schema validation
+```
+
+**Run specific test file**:
+
+```bash
+pytest tests/unit/test_vault.py -v
+```
+
+**Expected output**:
+
+```
+tests/unit/test_vault.py::test_create_note PASSED
+tests/unit/test_vault.py::test_read_note PASSED
+tests/unit/test_vault.py::test_update_note PASSED
+tests/unit/test_vault.py::test_delete_note PASSED
+tests/unit/test_vault.py::test_path_validation PASSED
+tests/unit/test_vault.py::test_path_traversal_blocked PASSED
+
+====== 6 passed in 0.23s ======
+```
+
+### Backend Integration Tests
+
+Test full API workflows:
+
+```bash
+# From backend/ directory
+pytest tests/integration -v
+```
+
+Expected output:
+```
+tests/integration/test_api_notes.py::test_create_and_read_note PASSED
+tests/integration/test_api_notes.py::test_update_note_with_version PASSED
+tests/integration/test_api_notes.py::test_version_conflict_409 PASSED
+tests/integration/test_api_search.py::test_full_text_search PASSED
+tests/integration/test_api_search.py::test_search_ranking PASSED
+tests/integration/test_mcp_tools.py::test_write_note_tool PASSED
+tests/integration/test_mcp_tools.py::test_search_notes_tool PASSED
+
+====== 7 passed in 1.45s ======
+```
+
+### Backend Contract Tests
+
+Validate API contracts against OpenAPI spec:
+
+```bash
+pytest tests/contract -v
+```
+
+Expected output:
+```
+tests/contract/test_http_api_contract.py::test_openapi_spec_valid PASSED
+tests/contract/test_http_api_contract.py::test_all_endpoints_match_spec PASSED
+tests/contract/test_mcp_contract.py::test_mcp_tool_schemas_valid PASSED
+
+====== 3 passed in 0.34s ======
+```
+
+### Frontend Unit Tests
+
+Run Vitest for component tests:
+
+```bash
+# From frontend/ directory
+npm test
+```
+
+**Example test structure**:
+
+```
+frontend/tests/
+├── unit/
+│   ├── DirectoryTree.test.tsx
+│   ├── NoteViewer.test.tsx
+│   ├── NoteEditor.test.tsx
+│   ├── SearchBar.test.tsx
+│   └── wikilink.test.ts
+└── e2e/
+    ├── note-crud.spec.ts
+    ├── search.spec.ts
+    └── navigation.spec.ts
+```
+
+**Run specific test**:
+
+```bash
+npm test -- DirectoryTree.test.tsx
+```
+
+Expected output:
+```
+✓ tests/unit/DirectoryTree.test.tsx (5)
+  ✓ renders folder tree structure
+  ✓ expands/collapses folders on click
+  ✓ selects note on click
+  ✓ highlights selected note
+  ✓ updates tree when notes change
+
+Test Files  1 passed (1)
+Tests  5 passed (5)
+```
+
+### Frontend E2E Tests
+
+Run Playwright for end-to-end tests:
+
+```bash
+# From frontend/ directory
+npm run test:e2e
+```
+
+**Setup Playwright** (first time):
+
+```bash
+npx playwright install
+```
+
+Expected output:
+```
+Running 8 tests using 4 workers
+
+  ✓ [chromium] › note-crud.spec.ts:3:1 › create new note (1.2s)
+  ✓ [chromium] › note-crud.spec.ts:15:1 › edit existing note (0.9s)
+  ✓ [chromium] › note-crud.spec.ts:28:1 › delete note (0.7s)
+  ✓ [chromium] › search.spec.ts:3:1 › search notes by title (0.8s)
+  ✓ [chromium] › search.spec.ts:12:1 › search notes by content (0.9s)
+  ✓ [chromium] › navigation.spec.ts:3:1 › navigate via directory tree (0.6s)
+  ✓ [chromium] › navigation.spec.ts:14:1 › navigate via wikilink click (1.1s)
+  ✓ [chromium] › navigation.spec.ts:25:1 › view backlinks (0.8s)
+
+  8 passed (6.0s)
+```
+
+---
+
+## Development Workflows
+
+### Workflow 1: AI Agent Writes a Note via MCP
+
+**Scenario**: Use Claude Desktop to create a new design document.
+
+1. **Open Claude Desktop** (with MCP configured)
+
+2. **Prompt Claude**:
+   ```
+   Create a new note at "design/api-authentication.md" with the following:
+
+   Title: API Authentication Design
+   Tags: backend, security, api
+
+   Content:
+   # API Authentication Design
+
+   ## Overview
+   This document describes the authentication strategy for our API.
+
+   ## JWT Token Flow
+   1. User authenticates via HF OAuth
+   2. Server issues JWT with 90-day expiration
+   3. Client includes token in Authorization header
+
+   ## Token Validation
+   - Validate signature using HS256
+   - Check expiration timestamp
+   - Extract user_id from 'sub' claim
+
+   See [[Security Best Practices]] for more details.
+   ```
+
+3. **Claude executes**:
+   - Calls `write_note` MCP tool
+   - Creates file at `data/vaults/local-dev/design/api-authentication.md`
+   - Writes frontmatter with title, tags, timestamps
+   - Writes markdown body
+   - Updates index (full-text search, tag index, wikilink graph)
+
+4. **Verify in UI**:
+   - Refresh browser at http://localhost:5173
+   - Expand "design" folder in directory tree
+   - Click "api-authentication.md"
+   - See rendered note with wikilink to "Security Best Practices"
+
+### Workflow 2: Human Edits a Note in UI
+
+**Scenario**: Fix a typo in the note created above.
+
+1. **Navigate to note**:
+   - Open http://localhost:5173
+   - Click on "design/api-authentication.md" in directory tree
+
+2. **Enter edit mode**:
+   - Click "Edit" button in top-right
+   - UI switches to split view: markdown editor (left) and live preview (right)
+
+3. **Make changes**:
+   - Fix typo: "authenication" → "authentication"
+   - Add a new section:
+     ```markdown
+     ## Token Expiration
+     Tokens expire after 90 days. Users must re-authenticate.
+     ```
+
+4. **Save changes**:
+   - Click "Save" button
+   - UI sends `PUT /api/notes/design/api-authentication.md` with `if_version: 1`
+   - Backend increments version to 2, updates timestamp
+   - UI switches back to read mode with updated content
+
+5. **Verify version tracking**:
+   - Check footer: "Updated: <timestamp>"
+   - Try editing again (version is now 2)
+
+### Workflow 3: Search for Notes
+
+**Scenario**: Find all notes about "authentication".
+
+1. **Use search bar**:
+   - Type "authentication" in search bar (top of left sidebar)
+   - Search debounces and calls `GET /api/search?q=authentication`
+
+2. **View results**:
+   - Results dropdown shows:
+     - "API Authentication Design" (title match, high score)
+     - "Security Best Practices" (body match, lower score)
+   - Snippets highlight matching text: "...API <mark>authentication</mark> strategy..."
+
+3. **Navigate to result**:
+   - Click on "API Authentication Design"
+   - Main pane renders the note
+
+### Workflow 4: Follow Wikilinks and View Backlinks
+
+**Scenario**: Navigate from "API Authentication Design" to "Security Best Practices" via wikilink.
+
+1. **View note with wikilink**:
+   - Open "design/api-authentication.md"
+   - See wikilink: `[[Security Best Practices]]` rendered as clickable link
+
+2. **Click wikilink**:
+   - UI resolves slug: "security-best-practices"
+   - Navigates to "security-best-practices.md" (or prompts to create if not exists)
+
+3. **View backlinks**:
+   - Footer shows "Referenced by:" section
+   - Lists "design/api-authentication.md" as a backlink
+   - Click backlink to navigate back
+
+### Workflow 5: Rebuild Index
+
+**Scenario**: Manually added notes outside the app, need to rebuild index.
+
+1. **Add notes manually**:
+   ```bash
+   # From terminal
+   cat > data/vaults/local-dev/notes/meeting-2025-01-16.md << 'EOF'
+   ---
+   title: Team Meeting Notes
+   tags: [meetings]
+   ---
+
+   # Team Meeting - Jan 16, 2025
+
+   ## Attendees
+   - Alice, Bob, Charlie
+
+   ## Topics
+   - Reviewed [[API Authentication Design]]
+   - Discussed deployment strategy
+   EOF
+   ```
+
+2. **Rebuild index**:
+   ```bash
+   curl -X POST http://localhost:8000/api/index/rebuild
+   ```
+
+   Response:
+   ```json
+   {
+     "status": "ok",
+     "note_count": 3,
+     "rebuilt_at": "2025-01-16T14:30:00Z"
+   }
+   ```
+
+3. **Verify in UI**:
+   - Refresh browser
+   - See new note in directory tree
+   - Note is searchable
+   - Backlink from "API Authentication Design" now shows "Team Meeting Notes"
+
+---
+
+## Hugging Face Space Deployment
+
+Deploy the application to Hugging Face Spaces for multi-tenant access.
+
+### Prerequisites
+
+1. **HuggingFace account**: https://huggingface.co/join
+2. **Create a Space**:
+   - Go to https://huggingface.co/new-space
+   - Choose "Docker" as SDK
+   - Enable "OAuth" in Space settings
+
+### 1. Configure OAuth
+
+In your Space settings, enable OAuth and note:
+- **Client ID**: `hf_oauth_client_id_xxxxx`
+- **Client Secret**: `hf_oauth_client_secret_xxxxx`
+
+### 2. Set Environment Variables
+
+In Space settings → Variables, add:
+
+| Variable | Value | Visibility |
+|----------|-------|------------|
+| `MODE` | `space` | Public |
+| `JWT_SECRET_KEY` | (generate secure secret) | Secret |
+| `VAULT_BASE_DIR` | `/data/vaults` | Public |
+| `DB_PATH` | `/data/index.db` | Public |
+| `HF_OAUTH_CLIENT_ID` | (from OAuth settings) | Secret |
+| `HF_OAUTH_CLIENT_SECRET` | (from OAuth settings) | Secret |
+| `HF_SPACE_HOST` | `https://your-space.hf.space` | Public |
+
+### 3. Create Dockerfile
+
+**`Dockerfile`**:
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install Node.js for frontend build
+RUN apt-get update && apt-get install -y \
+    nodejs \
+    npm \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy backend
+COPY backend/ /app/backend/
+WORKDIR /app/backend
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Initialize database
+RUN python -m src.services.init_db
+
+# Copy frontend
+COPY frontend/ /app/frontend/
+WORKDIR /app/frontend
+
+# Build frontend
+RUN npm install && npm run build
+
+# Copy built frontend to backend static directory
+RUN mkdir -p /app/backend/static && \
+    cp -r /app/frontend/dist/* /app/backend/static/
+
+# Set working directory back to backend
+WORKDIR /app/backend
+
+# Create data directories
+RUN mkdir -p /data/vaults
+
+# Expose ports
+EXPOSE 7860 8001
+
+# Start backend (FastAPI + MCP HTTP)
+CMD ["sh", "-c", "uvicorn src.api.main:app --host 0.0.0.0 --port 7860 & python -m src.mcp.server --http --port 8001 & wait"]
+```
+
+### 4. Configure Backend to Serve Frontend
+
+**`backend/src/api/main.py`** (add static file serving):
+
+```python
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+import os
+
+app = FastAPI(title="Obsidian Docs Viewer API")
+
+# ... (existing API routes) ...
+
+# Serve frontend static files
+static_dir = os.path.join(os.path.dirname(__file__), "../../static")
+if os.path.exists(static_dir):
+    app.mount("/assets", StaticFiles(directory=f"{static_dir}/assets"), name="assets")
+
+    @app.get("/{full_path:path}")
+    async def serve_frontend(full_path: str):
+        """Serve frontend SPA (fallback to index.html for client-side routing)."""
+        if full_path.startswith("api/"):
+            # API routes handled by existing endpoints
+            return {"error": "Not found"}
+
+        file_path = os.path.join(static_dir, full_path)
+        if os.path.exists(file_path) and os.path.isfile(file_path):
+            return FileResponse(file_path)
+
+        # Fallback to index.html for SPA routing
+        return FileResponse(f"{static_dir}/index.html")
+```
+
+### 5. Build Frontend with HF Space URL
+
+Update **`frontend/.env.production`**:
+
+```bash
+VITE_API_BASE_URL=https://your-space.hf.space
+```
+
+Build:
+
+```bash
+cd frontend
+npm run build
+```
+
+### 6. Push to HF Space
+
+```bash
+# From project root
+git init
+git add .
+git commit -m "Initial commit"
+
+# Add HF Space remote
+git remote add space https://huggingface.co/spaces/your-username/your-space-name
+git push space main
+```
+
+### 7. Verify Deployment
+
+1. Visit `https://your-space.hf.space`
+2. Click "Sign in with Hugging Face"
+3. Authorize the app
+4. You should see the main UI with your isolated vault
+
+### 8. Configure MCP HTTP Client for HF Space
+
+1. Sign in to the Space and navigate to Settings
+2. Click "Issue API Token"
+3. Copy the JWT token
+4. Configure your local MCP client:
+
+**MCP HTTP client config**:
+
+```json
+{
+  "mcp_endpoint": "https://your-space.hf.space:8001/mcp",
+  "auth": {
+    "type": "bearer",
+    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+  }
+}
+```
+
+5. Test from command line:
+
+```bash
+curl -X POST https://your-space.hf.space:8001/mcp/call \
+  -H "Authorization: Bearer <your-token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "list_notes",
+    "arguments": {}
+  }'
+```
+
+---
+
+## Troubleshooting
+
+### Common Errors
+
+#### Error: `401 Unauthorized - Invalid token`
+
+**Cause**: JWT token is invalid, expired, or missing.
+
+**Solution**:
+1. Check token expiration:
+   ```bash
+   # Decode JWT (requires `pyjwt` library)
+   python -c "import jwt; print(jwt.decode('your-token', options={'verify_signature': False}))"
+   ```
+2. Issue a new token:
+   ```bash
+   curl -X POST http://localhost:8000/api/tokens
+   ```
+3. Update token in client configuration
+
+#### Error: `400 Bad Request - Path traversal blocked`
+
+**Cause**: Note path contains `..` or absolute path components.
+
+**Example**: `write_note(path="../etc/passwd")`
+
+**Solution**: Use relative paths only, no `..` allowed
+```python
+# ✅ Correct
+write_note(path="design/api.md")
+
+# ❌ Incorrect
+write_note(path="../design/api.md")
+write_note(path="/design/api.md")
+```
+
+#### Error: `409 Conflict - Version mismatch`
+
+**Cause**: Note was updated by another user/agent since you last read it.
+
+**Example**:
+1. You load note with version 5
+2. Claude updates it via MCP (version → 6)
+3. You click "Save" with `if_version: 5`
+4. Server returns `409 Conflict`
+
+**Solution**:
+1. Reload the note to get latest version
+2. Re-apply your changes
+3. Save with new version number
+
+**UI handling**:
+```typescript
+// In NoteEditor component
+try {
+  await updateNote(path, { body, if_version: currentVersion });
+} catch (error) {
+  if (error.status === 409) {
+    alert("This note changed since you opened it. Please reload before saving.");
+    // Optionally: reload note automatically
+  }
+}
+```
+
+#### Error: `413 Payload Too Large`
+
+**Cause**: Note content exceeds 1 MiB (1,048,576 bytes).
+
+**Solution**: Split large notes into smaller files
+```bash
+# Check note size
+wc -c data/vaults/local-dev/large-note.md
+
+# If > 1 MiB, split into multiple notes
+```
+
+#### Error: `403 Forbidden - Vault note limit exceeded`
+
+**Cause**: Vault has reached 5,000 note limit.
+
+**Solution**:
+1. Delete unused notes
+2. Archive old notes to external storage
+3. Request limit increase (requires code change in `FR-008`)
+
+#### Error: `SQLite database is locked`
+
+**Cause**: Concurrent writes to SQLite database.
+
+**Solution**:
+1. Ensure only one backend process is running
+2. Use connection pooling (in production)
+3. Consider upgrading to PostgreSQL for high concurrency
+
+**Quick fix**:
+```bash
+# Kill all backend processes
+pkill -f uvicorn
+pkill -f "python -m src.mcp.server"
+
+# Restart backend
+uvicorn src.api.main:app --reload
+```
+
+#### Error: `FTS5 extension not available`
+
+**Cause**: SQLite was compiled without FTS5 support.
+
+**Solution**:
+1. Check if FTS5 is available:
+   ```python
+   import sqlite3
+   conn = sqlite3.connect(":memory:")
+   cursor = conn.cursor()
+   cursor.execute("PRAGMA compile_options")
+   print([row[0] for row in cursor.fetchall()])
+   # Look for 'ENABLE_FTS5' in output
+   ```
+
+2. If not available, reinstall SQLite with FTS5:
+   ```bash
+   # macOS (Homebrew)
+   brew reinstall sqlite3
+
+   # Linux (Ubuntu/Debian)
+   sudo apt-get install --reinstall libsqlite3-0
+
+   # Python (rebuild pysqlite3 with FTS5)
+   pip install pysqlite3-binary
+   ```
+
+### Debug Mode
+
+Enable debug logging for troubleshooting:
+
+**Backend** (`.env`):
+```bash
+LOG_LEVEL=DEBUG
+```
+
+**Frontend** (`frontend/.env`):
+```bash
+VITE_DEBUG=true
+```
+
+**View logs**:
+
+```bash
+# Backend logs (if using uvicorn)
+tail -f backend.log
+
+# Or run with verbose output
+uvicorn src.api.main:app --reload --log-level debug
+```
+
+**Frontend logs**: Open browser DevTools → Console
+
+### Health Checks
+
+#### Check API Health
+
+```bash
+curl http://localhost:8000/api/health
+```
+
+Expected response:
+```json
+{
+  "status": "ok",
+  "mode": "local",
+  "vault_base_dir": "./data/vaults",
+  "db_path": "./data/index.db"
+}
+```
+
+#### Check Index Health
+
+```bash
+curl http://localhost:8000/api/index/health
+```
+
+Expected response:
+```json
+{
+  "user_id": "local-dev",
+  "note_count": 15,
+  "last_full_rebuild": "2025-01-15T10:00:00Z",
+  "last_incremental_update": "2025-01-16T14:30:00Z"
+}
+```
+
+#### Verify MCP Server
+
+```bash
+# Test STDIO server (requires MCP client)
+echo '{"tool": "list_notes", "arguments": {}}' | python -m src.mcp.server
+
+# Test HTTP server
+curl -X POST http://localhost:8001/mcp/call \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"tool": "list_notes", "arguments": {}}'
+```
+
+### Performance Profiling
+
+#### Backend API Response Time
+
+```bash
+# Use curl with timing
+curl -w "@curl-format.txt" -o /dev/null -s http://localhost:8000/api/notes
+
+# curl-format.txt:
+# time_namelookup:  %{time_namelookup}s\n
+# time_connect:     %{time_connect}s\n
+# time_appconnect:  %{time_appconnect}s\n
+# time_total:       %{time_total}s\n
+```
+
+Expected: `time_total < 2s` for directory listing
+
+#### Search Query Performance
+
+```bash
+time curl -s "http://localhost:8000/api/search?q=authentication" > /dev/null
+```
+
+Expected: `< 1s` for vaults with up to 5,000 notes
+
+#### Index Rebuild Time
+
+```bash
+time curl -X POST http://localhost:8000/api/index/rebuild
+```
+
+Expected: `< 30s` for 1,000 notes
+
+---
+
+## Next Steps
+
+1. **Read the full specification**: See `specs/001-obsidian-docs-viewer/spec.md`
+2. **Review data model**: See `specs/001-obsidian-docs-viewer/data-model.md`
+3. **Check API contracts**: See `specs/001-obsidian-docs-viewer/contracts/`
+4. **Start implementation**: Run `/speckit.tasks` to generate implementation tasks
+
+---
+
+## Additional Resources
+
+- **FastAPI Documentation**: https://fastapi.tiangolo.com/
+- **FastMCP Documentation**: https://github.com/jlowin/fastmcp
+- **React + shadcn/ui**: https://ui.shadcn.com/
+- **HuggingFace Spaces**: https://huggingface.co/docs/hub/spaces
+- **MCP Protocol**: https://modelcontextprotocol.io/
+
+---
+
+**Last Updated**: 2025-11-15
+**Status**: Ready for implementation

specs/001-obsidian-docs-viewer/research.md

@@ -0,0 +1,1407 @@
+# Research: Multi-Tenant Obsidian-Like Docs Viewer
+
+**Branch**: `001-obsidian-docs-viewer` | **Date**: 2025-11-15 | **Plan**: [plan.md](./plan.md)
+
+## Overview
+
+This document captures technical research and decisions for the implementation of a multi-tenant Obsidian-like documentation viewer. Each section addresses a specific research topic from Phase 0 of the implementation plan.
+
+---
+
+## 1. FastMCP HTTP Transport Authentication (Bearer Token)
+
+### Decision
+
+Use FastMCP's built-in `BearerAuth` mechanism with JWT token validation for HTTP transport authentication.
+
+**Implementation approach**:
+- Server: Configure FastMCP HTTP transport to accept `Authorization: Bearer <token>` header
+- Client: Pass JWT token as string to `auth` parameter (FastMCP adds "Bearer" prefix automatically)
+- Token format: JWT with claims `sub=user_id`, `exp=now+90days`, signed with `HS256` and server secret
+
+### Rationale
+
+1. **Native FastMCP support**: FastMCP provides first-class Bearer token authentication via `BearerAuth` class and string token shortcuts
+2. **Minimal configuration**: Client code is as simple as `Client("https://...", auth="<token>")`
+3. **Standard compliance**: Uses industry-standard `Authorization: Bearer` header pattern
+4. **Transport flexibility**: Works seamlessly with both HTTP and SSE (Server-Sent Events) transports
+5. **Non-interactive workflow**: Perfect for AI agents and service accounts that need programmatic access
+
+### Alternatives Considered
+
+**Alternative 1: Custom header authentication**
+- **Rejected**: FastMCP supports custom headers but requires manual implementation of auth logic
+- **Why rejected**: More complex, loses benefit of FastMCP's built-in token handling and validation
+
+**Alternative 2: OAuth flow for MCP clients**
+- **Rejected**: FastMCP supports full OAuth 2.1 flows with browser-based authentication
+- **Why rejected**: Overly complex for AI agent use case; requires interactive browser flow which doesn't suit MCP STDIO or programmatic access patterns
+
+**Alternative 3: API key-based authentication**
+- **Rejected**: Could use simple API keys instead of JWTs
+- **Why rejected**: JWTs provide expiration, claims, and stateless validation; better security posture for multi-tenant system
+
+### Implementation Notes
+
+**Server-side setup**:
+```python
+from fastmcp import FastMCP
+from fastmcp.server.auth import BearerAuthProvider
+import jwt
+
+# For token validation (if using external issuer)
+auth_provider = BearerAuthProvider(
+    public_key="<RSA_PUBLIC_KEY>",
+    issuer="https://your-issuer.com",
+    audience="your-api"
+)
+
+# For internal JWT validation (our use case)
+# Validate manually in middleware/dependency injection
+def validate_jwt(token: str) -> str:
+    payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
+    return payload["sub"]  # user_id
+```
+
+**Client-side setup**:
+```python
+from fastmcp import Client
+
+# Simplest approach - pass token as string
+async with Client(
+    "https://fastmcp.cloud/mcp",
+    auth="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+) as client:
+    await client.call_tool("list_notes", {})
+
+# Explicit approach - use BearerAuth class
+from fastmcp.client.auth import BearerAuth
+
+async with Client(
+    "https://fastmcp.cloud/mcp",
+    auth=BearerAuth(token="eyJhbGci...")
+) as client:
+    await client.call_tool("list_notes", {})
+```
+
+**Key points**:
+- Do NOT include "Bearer" prefix when passing token - FastMCP adds it automatically
+- Token validation happens on every MCP tool call via HTTP transport
+- STDIO transport bypasses authentication (local development only)
+- For HF Space deployment, combine with HF OAuth to issue user-specific JWTs
+
+**References**:
+- FastMCP Bearer Auth docs: https://gofastmcp.com/clients/auth/bearer
+- FastMCP authentication patterns: https://gyliu513.github.io/jekyll/update/2025/08/12/fastmcp-auth-patterns.html
+
+---
+
+## 2. Hugging Face Space OAuth Integration
+
+### Decision
+
+Use `huggingface_hub` library's built-in OAuth helpers (`attach_huggingface_oauth`, `parse_huggingface_oauth`) for zero-configuration OAuth integration in HF Spaces.
+
+**Implementation approach**:
+- Add `hf_oauth: true` to Space metadata in README.md
+- Call `attach_huggingface_oauth(app)` to auto-register OAuth endpoints (`/oauth/huggingface/login`, `/oauth/huggingface/logout`, `/oauth/huggingface/callback`)
+- Call `parse_huggingface_oauth(request)` in route handlers to extract authenticated user info
+- Map HF username/ID to internal `user_id` for vault scoping
+
+### Rationale
+
+1. **Zero-configuration**: HF Spaces automatically injects OAuth environment variables (`OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OAUTH_SCOPES`) when `hf_oauth: true` is set
+2. **Local dev friendly**: `parse_huggingface_oauth` returns mock user in local mode, enabling seamless development without OAuth setup
+3. **Minimal code**: Two function calls provide complete OAuth flow (login redirect, callback handling, session management)
+4. **First-class support**: Official HF library with guaranteed compatibility with Spaces platform
+5. **Standard OAuth 2.0**: Under the hood, implements industry-standard OAuth with PKCE
+
+### Alternatives Considered
+
+**Alternative 1: Manual OAuth implementation**
+- **Rejected**: Implement OAuth flow manually using `authlib` or `requests-oauthlib`
+- **Why rejected**: Significantly more code, requires manual handling of PKCE, state validation, and token exchange; error-prone and loses HF Spaces auto-configuration
+
+**Alternative 2: Third-party auth provider (Auth0, WorkOS)**
+- **Rejected**: Use external auth service and connect HF as identity provider
+- **Why rejected**: Adds unnecessary complexity and external dependencies for a system designed specifically for HF Spaces deployment
+
+**Alternative 3: Session-based auth without OAuth**
+- **Rejected**: Use simple username/password with cookie sessions
+- **Why rejected**: Poor UX (users already have HF accounts), requires password management, doesn't leverage HF ecosystem integration
+
+### Implementation Notes
+
+**Space configuration** (README.md frontmatter):
+```yaml
+---
+title: Obsidian Docs Viewer
+emoji: 📚
+colorFrom: blue
+colorTo: green
+sdk: docker
+app_port: 8000
+hf_oauth: true  # <-- Enable OAuth
+---
+```
+
+**Backend integration** (FastAPI):
+```python
+from fastapi import FastAPI, Request
+from huggingface_hub import attach_huggingface_oauth, parse_huggingface_oauth
+
+app = FastAPI()
+
+# Auto-register OAuth endpoints
+attach_huggingface_oauth(app)
+
+@app.get("/")
+def index(request: Request):
+    oauth_info = parse_huggingface_oauth(request)
+
+    if oauth_info is None:
+        return {"message": "Not logged in", "login_url": "/oauth/huggingface/login"}
+
+    # Extract user info
+    user_id = oauth_info.user_info.preferred_username  # or use 'sub' for UUID
+    display_name = oauth_info.user_info.name
+    avatar = oauth_info.user_info.picture
+
+    return {
+        "user_id": user_id,
+        "display_name": display_name,
+        "avatar": avatar
+    }
+
+@app.get("/api/me")
+def get_current_user(request: Request):
+    oauth_info = parse_huggingface_oauth(request)
+    if oauth_info is None:
+        raise HTTPException(status_code=401, detail="Not authenticated")
+
+    # Map to internal user model
+    user_id = oauth_info.user_info.preferred_username
+
+    # Initialize vault on first login if needed
+    vault_service.ensure_vault_exists(user_id)
+
+    return {
+        "user_id": user_id,
+        "hf_profile": {
+            "username": oauth_info.user_info.preferred_username,
+            "name": oauth_info.user_info.name,
+            "avatar": oauth_info.user_info.picture
+        }
+    }
+```
+
+**Frontend integration** (React):
+```typescript
+// Check auth status on app load
+useEffect(() => {
+  fetch('/api/me')
+    .then(res => {
+      if (res.ok) return res.json();
+      throw new Error('Not authenticated');
+    })
+    .then(user => setCurrentUser(user))
+    .catch(() => window.location.href = '/oauth/huggingface/login');
+}, []);
+```
+
+**Key points**:
+- `attach_huggingface_oauth` must be called BEFORE defining routes that need auth
+- `parse_huggingface_oauth` returns `None` if not authenticated (check before accessing user_info)
+- In local development, returns mocked user with deterministic username (e.g., "local-user")
+- OAuth tokens/sessions are managed by `huggingface_hub` (stored in cookies)
+- For API/MCP access, issue separate JWT after OAuth login via `POST /api/tokens`
+
+**Environment variables** (auto-injected in HF Space):
+- `OAUTH_CLIENT_ID`: Public client identifier
+- `OAUTH_CLIENT_SECRET`: Secret for token exchange
+- `OAUTH_SCOPES`: Space-specific scopes (typically `openid profile`)
+
+**References**:
+- HF OAuth docs: https://huggingface.co/docs/hub/spaces-oauth
+- huggingface_hub API: https://huggingface.co/docs/huggingface_hub/en/package_reference/oauth
+
+---
+
+## 3. SQLite Schema Design for Multi-Index Storage
+
+### Decision
+
+Use SQLite with FTS5 (Full-Text Search 5) for full-text indexing, plus separate regular tables for tags and link graph. Implement per-user isolation via `user_id` column in all tables.
+
+**Schema approach**:
+- **Full-text index**: FTS5 virtual table with `title` and `body` columns, using `porter` tokenizer for stemming
+- **Tag index**: Regular table with `user_id`, `tag`, `note_path` (many-to-many relationship)
+- **Link graph**: Regular table with `user_id`, `source_path`, `target_path`, `link_text`, `is_resolved`
+- **Metadata index**: Regular table with `user_id`, `note_path`, `version`, `created`, `updated`, `title` for fast lookups
+- **Index health**: Regular table with `user_id`, `note_count`, `last_full_rebuild`, `last_incremental_update`
+
+### Rationale
+
+1. **FTS5 performance**: Native full-text search with inverted index, sub-100ms query times for thousands of documents
+2. **Separate concerns**: Full-text (FTS5), tags (simple lookup), and links (graph traversal) have different query patterns; separate tables optimize each
+3. **Per-user isolation**: `user_id` column in all tables enables simple WHERE filtering without complex row-level security
+4. **External content pattern**: FTS5 with `content=''` (contentless) avoids storing document text twice (already in filesystem)
+5. **Version tracking**: Metadata table stores version counter for optimistic concurrency without polluting frontmatter
+6. **Prefix indexes**: FTS5 `prefix='2 3'` option enables fast autocomplete/prefix search
+
+### Alternatives Considered
+
+**Alternative 1: Single FTS5 table for everything**
+- **Rejected**: Store tags and links as UNINDEXED columns in FTS5 table
+- **Why rejected**: FTS5 is optimized for full-text, not structured data; complex queries (e.g., "all notes with tag X") would require scanning all rows; tags/links don't benefit from tokenization
+
+**Alternative 2: Separate SQLite database per user**
+- **Rejected**: One `.db` file per user instead of `user_id` column
+- **Why rejected**: Increases file I/O overhead, complicates connection pooling, harder to implement global admin queries (e.g., total user count)
+
+**Alternative 3: PostgreSQL with pg_trgm or RUM indexes**
+- **Rejected**: Use full Postgres instead of SQLite
+- **Why rejected**: Overkill for single-server deployment, adds deployment complexity, SQLite is sufficient for target scale (5,000 notes/user, 10 concurrent users)
+
+**Alternative 4: In-memory index only**
+- **Rejected**: Build inverted index in Python dict, no persistence
+- **Why rejected**: Slow startup (rebuild on every restart), no durability, doesn't scale beyond single process
+
+### Implementation Notes
+
+**Schema definition**:
+```sql
+-- Metadata index (fast lookups, version tracking)
+CREATE TABLE IF NOT EXISTS note_metadata (
+    user_id TEXT NOT NULL,
+    note_path TEXT NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1,
+    title TEXT NOT NULL,
+    created TEXT NOT NULL,  -- ISO 8601 timestamp
+    updated TEXT NOT NULL,  -- ISO 8601 timestamp
+    PRIMARY KEY (user_id, note_path)
+);
+CREATE INDEX idx_metadata_user ON note_metadata(user_id);
+CREATE INDEX idx_metadata_updated ON note_metadata(user_id, updated DESC);
+
+-- Full-text search index (FTS5, contentless)
+CREATE VIRTUAL TABLE IF NOT EXISTS note_fts USING fts5(
+    user_id UNINDEXED,
+    note_path UNINDEXED,
+    title,
+    body,
+    content='',  -- Contentless (we don't store the actual text)
+    tokenize='porter unicode61',  -- Stemming + Unicode support
+    prefix='2 3'  -- Prefix indexes for autocomplete
+);
+
+-- Tag index (many-to-many: notes <-> tags)
+CREATE TABLE IF NOT EXISTS note_tags (
+    user_id TEXT NOT NULL,
+    note_path TEXT NOT NULL,
+    tag TEXT NOT NULL,
+    PRIMARY KEY (user_id, note_path, tag)
+);
+CREATE INDEX idx_tags_user_tag ON note_tags(user_id, tag);
+CREATE INDEX idx_tags_user_path ON note_tags(user_id, note_path);
+
+-- Link graph (outgoing links from notes)
+CREATE TABLE IF NOT EXISTS note_links (
+    user_id TEXT NOT NULL,
+    source_path TEXT NOT NULL,
+    target_path TEXT,  -- NULL if unresolved
+    link_text TEXT NOT NULL,  -- Original [[link text]]
+    is_resolved INTEGER NOT NULL DEFAULT 0,  -- Boolean: 0=broken, 1=resolved
+    PRIMARY KEY (user_id, source_path, link_text)
+);
+CREATE INDEX idx_links_user_source ON note_links(user_id, source_path);
+CREATE INDEX idx_links_user_target ON note_links(user_id, target_path);
+CREATE INDEX idx_links_unresolved ON note_links(user_id, is_resolved);
+
+-- Index health tracking
+CREATE TABLE IF NOT EXISTS index_health (
+    user_id TEXT PRIMARY KEY,
+    note_count INTEGER NOT NULL DEFAULT 0,
+    last_full_rebuild TEXT,  -- ISO 8601 timestamp
+    last_incremental_update TEXT  -- ISO 8601 timestamp
+);
+```
+
+**Query patterns**:
+```python
+# Full-text search with ranking
+cursor.execute("""
+    SELECT
+        note_path,
+        title,
+        bm25(note_fts, 3.0, 1.0) AS rank  -- Title weight=3, body weight=1
+    FROM note_fts
+    WHERE user_id = ? AND note_fts MATCH ?
+    ORDER BY rank DESC
+    LIMIT 50
+""", (user_id, query))
+
+# Get all notes with a specific tag
+cursor.execute("""
+    SELECT DISTINCT note_path, title
+    FROM note_tags t
+    JOIN note_metadata m USING (user_id, note_path)
+    WHERE t.user_id = ? AND t.tag = ?
+    ORDER BY m.updated DESC
+""", (user_id, tag))
+
+# Get backlinks for a note
+cursor.execute("""
+    SELECT DISTINCT l.source_path, m.title
+    FROM note_links l
+    JOIN note_metadata m ON l.user_id = m.user_id AND l.source_path = m.note_path
+    WHERE l.user_id = ? AND l.target_path = ?
+    ORDER BY m.updated DESC
+""", (user_id, target_path))
+
+# Get all unresolved links for UI display
+cursor.execute("""
+    SELECT source_path, link_text
+    FROM note_links
+    WHERE user_id = ? AND is_resolved = 0
+""", (user_id,))
+```
+
+**Incremental update strategy**:
+1. On `write_note`: Delete all existing rows for `(user_id, note_path)`, then insert new rows
+2. Use transactions to ensure atomicity (delete old + insert new = single atomic operation)
+3. Update `index_health.last_incremental_update` on every write
+
+**Full rebuild strategy**:
+1. Delete all index rows for `user_id`
+2. Scan all `.md` files in vault directory
+3. Parse each file and insert into all indexes
+4. Update `index_health.note_count` and `last_full_rebuild`
+
+**Key points**:
+- FTS5 with `content=''` is contentless - we must manually INSERT/DELETE rows (no automatic synchronization)
+- Use `porter` tokenizer for English stemming (search "running" matches "run")
+- `bm25()` function provides relevance ranking (better than simple MATCH count)
+- Prefix indexes (`prefix='2 3'`) enable fast `MATCH 'prefix*'` queries
+- `UNINDEXED` columns in FTS5 are retrievable but not searchable (good for IDs)
+
+**References**:
+- SQLite FTS5 docs: https://www.sqlite.org/fts5.html
+- FTS5 structure deep dive: https://darksi.de/13.sqlite-fts5-structure/
+
+---
+
+## 4. Wikilink Normalization and Resolution
+
+### Decision
+
+Implement case-insensitive normalized slug matching with deterministic ambiguity resolution based on Obsidian's behavior.
+
+**Normalization algorithm**:
+1. Extract link text from `[[link text]]`
+2. Normalize: lowercase, replace spaces/hyphens/underscores with single dash, remove non-alphanumeric except dashes
+3. Match normalized slug against normalized filename stems AND normalized frontmatter titles
+4. If multiple matches: prefer same-folder match, then lexicographically smallest path
+
+**Slug normalization function**:
+```python
+import re
+
+def normalize_slug(text: str) -> str:
+    """Normalize text to slug for case-insensitive matching."""
+    text = text.lower()
+    text = re.sub(r'[\s_]+', '-', text)  # Spaces/underscores → dash
+    text = re.sub(r'[^a-z0-9-]', '', text)  # Keep only alphanumeric + dash
+    text = re.sub(r'-+', '-', text)  # Collapse multiple dashes
+    return text.strip('-')
+```
+
+### Rationale
+
+1. **Obsidian compatibility**: Matches Obsidian's link resolution behavior (case-insensitive, flexible matching)
+2. **User-friendly**: Users don't need to remember exact case or spacing (e.g., `[[API Design]]` matches `api-design.md`)
+3. **Deterministic**: Same-folder preference + lexicographic tiebreaker ensures consistent resolution
+4. **Efficient indexing**: Normalized slugs can be pre-computed and indexed for O(1) lookup
+5. **Graceful fallback**: Broken links are tracked and displayed distinctly in UI
+
+### Alternatives Considered
+
+**Alternative 1: Exact case-sensitive matching**
+- **Rejected**: Require `[[exact-filename]]` to match `exact-filename.md`
+- **Why rejected**: Brittle user experience, doesn't match Obsidian behavior, forces users to remember exact capitalization
+
+**Alternative 2: Fuzzy matching (Levenshtein distance)**
+- **Rejected**: Use string similarity to find "close enough" matches
+- **Why rejected**: Non-deterministic, slower, can match wrong notes ("Setup" matches "Startup"), confusing UX
+
+**Alternative 3: Path-based links only**
+- **Rejected**: Require full paths like `[[guides/setup]]` instead of `[[Setup]]`
+- **Why rejected**: Verbose, doesn't match Obsidian's short-link paradigm, poor UX for large vaults
+
+**Alternative 4: UUID-based links**
+- **Rejected**: Use unique IDs like `[[#uuid-123]]` for stable references
+- **Why rejected**: Not human-readable, requires additional metadata, doesn't match Obsidian convention
+
+### Implementation Notes
+
+**Resolution algorithm** (priority order):
+```python
+def resolve_wikilink(user_id: str, link_text: str, current_note_folder: str) -> str | None:
+    """Resolve wikilink to note path, or None if unresolved."""
+    normalized = normalize_slug(link_text)
+
+    # Build candidate index: normalized_slug -> [note_paths]
+    candidates = defaultdict(list)
+
+    # Scan all notes for this user
+    for note in list_all_notes(user_id):
+        # Match against filename stem
+        stem = Path(note.path).stem
+        if normalize_slug(stem) == normalized:
+            candidates[note.path].append(note.path)
+
+        # Match against frontmatter title
+        if note.title and normalize_slug(note.title) == normalized:
+            candidates[note.path].append(note.path)
+
+    if not candidates:
+        return None  # Unresolved link
+
+    paths = list(set(candidates.keys()))  # Deduplicate
+
+    if len(paths) == 1:
+        return paths[0]  # Unique match
+
+    # Ambiguity resolution
+    # 1. Prefer same-folder match
+    same_folder = [p for p in paths if Path(p).parent == current_note_folder]
+    if same_folder:
+        return sorted(same_folder)[0]  # Lexicographic tiebreaker
+
+    # 2. Lexicographically smallest path
+    return sorted(paths)[0]
+```
+
+**Index optimization**:
+Pre-compute normalized slugs for all notes and store in `note_metadata` table:
+```sql
+ALTER TABLE note_metadata ADD COLUMN normalized_title_slug TEXT;
+ALTER TABLE note_metadata ADD COLUMN normalized_path_slug TEXT;
+CREATE INDEX idx_metadata_title_slug ON note_metadata(user_id, normalized_title_slug);
+CREATE INDEX idx_metadata_path_slug ON note_metadata(user_id, normalized_path_slug);
+```
+
+**Link extraction from Markdown**:
+```python
+import re
+
+def extract_wikilinks(markdown_body: str) -> list[str]:
+    """Extract all wikilink texts from markdown body."""
+    pattern = r'\[\[([^\]]+)\]\]'
+    return re.findall(pattern, markdown_body)
+```
+
+**Update link graph on write**:
+```python
+def update_link_graph(user_id: str, note_path: str, body: str):
+    """Update outgoing links and backlinks for a note."""
+    current_folder = str(Path(note_path).parent)
+
+    # Extract wikilinks from body
+    link_texts = extract_wikilinks(body)
+
+    # Delete old links from this note
+    db.execute("DELETE FROM note_links WHERE user_id=? AND source_path=?",
+               (user_id, note_path))
+
+    # Insert new links
+    for link_text in link_texts:
+        target_path = resolve_wikilink(user_id, link_text, current_folder)
+        is_resolved = 1 if target_path else 0
+
+        db.execute("""
+            INSERT INTO note_links (user_id, source_path, target_path, link_text, is_resolved)
+            VALUES (?, ?, ?, ?, ?)
+        """, (user_id, note_path, target_path, link_text, is_resolved))
+```
+
+**UI rendering**:
+```typescript
+// Transform wikilinks to clickable links in rendered Markdown
+function transformWikilinks(markdown: string, linkIndex: Record<string, string>): string {
+  return markdown.replace(/\[\[([^\]]+)\]\]/g, (match, linkText) => {
+    const targetPath = linkIndex[linkText];
+
+    if (targetPath) {
+      // Resolved link
+      return `<a href="#/note/${encodeURIComponent(targetPath)}" class="wikilink">${linkText}</a>`;
+    } else {
+      // Broken link
+      return `<a href="#/create/${encodeURIComponent(linkText)}" class="wikilink broken">${linkText}</a>`;
+    }
+  });
+}
+```
+
+**Key points**:
+- Pre-compute and cache slug mappings for performance (avoid re-scanning on every link resolution)
+- Same-folder preference matches Obsidian's behavior (local references are intuitive)
+- Lexicographic tiebreaker ensures determinism (same input always resolves to same output)
+- Track `is_resolved` flag to identify broken links for UI warnings/affordances
+- Update entire link graph on every note write (incremental update, not rebuild)
+
+**Edge cases**:
+- Empty link text `[[]]` - ignore/skip
+- Nested brackets `[[foo [[bar]]]]` - naive regex fails; use proper parser or limit to non-nested pattern
+- Link with pipe `[[link|display]]` - out of scope for MVP; treat entire string as link text
+
+---
+
+## 5. React + shadcn/ui Directory Tree Component
+
+### Decision
+
+Use **shadcn-extension Tree View** component with built-in virtualization via `@tanstack/react-virtual` for directory tree rendering.
+
+**Component choice**: `shadcn-extension` Tree View
+- **Installation**: Available at https://shadcn-extension.vercel.app/docs/tree-view
+- **Features**: Virtualization, accordion-based expand/collapse, keyboard navigation, selection, custom icons
+- **Why this one**: Only shadcn tree component with native virtualization support; critical for large vaults (5,000 notes)
+
+### Rationale
+
+1. **Virtualization required**: 5,000 notes would create 5,000+ DOM nodes without virtualization; TanStack Virtual renders only visible rows (~20-50 nodes)
+2. **Performance**: Virtualization reduces initial render from ~2s to <100ms for large trees
+3. **shadcn ecosystem**: Consistent styling with other shadcn/ui components (Button, ScrollArea, etc.)
+4. **Accessibility**: Built on Radix UI primitives with keyboard navigation and ARIA support
+5. **Customizable**: Supports custom icons per node, expand/collapse callbacks, and selection handling
+
+### Alternatives Considered
+
+**Alternative 1: MrLightful's shadcn Tree View**
+- **Rejected**: Feature-rich component with drag-and-drop, custom icons
+- **Why rejected**: No virtualization support; would cause performance issues with 1,000+ notes
+
+**Alternative 2: Neigebaie's shadcn Tree View**
+- **Rejected**: Advanced features (multi-select, checkboxes, context menus)
+- **Why rejected**: No virtualization; overkill for simple directory browsing
+
+**Alternative 3: react-arborist**
+- **Rejected**: Powerful tree view library with virtualization and drag-and-drop
+- **Why rejected**: Not part of shadcn ecosystem; requires custom styling to match UI; heavier dependency
+
+**Alternative 4: Custom implementation with react-window**
+- **Rejected**: Build tree view from scratch using `react-window` or `react-virtual`
+- **Why rejected**: Significant development effort; reinventing the wheel; shadcn-extension already provides this
+
+### Implementation Notes
+
+**Installation**:
+```bash
+npx shadcn add https://shadcn-extension.vercel.app/registry/tree-view.json
+```
+
+**Component usage**:
+```tsx
+import { Tree, TreeNode } from "@/components/ui/tree-view";
+
+interface FileTreeNode {
+  id: string;
+  name: string;
+  path: string;
+  isFolder: boolean;
+  children?: FileTreeNode[];
+}
+
+function DirectoryTree({ vault, onSelectNote }: Props) {
+  // Transform vault notes into tree structure
+  const treeData = useMemo(() => buildTree(vault.notes), [vault.notes]);
+
+  return (
+    <Tree
+      data={treeData}
+      onSelectChange={(nodeId) => {
+        const node = findNode(treeData, nodeId);
+        if (!node.isFolder) {
+          onSelectNote(node.path);
+        }
+      }}
+      // Virtualization is enabled by default
+      className="w-full h-full"
+    />
+  );
+}
+
+// Transform flat list of note paths into hierarchical tree
+function buildTree(notes: Note[]): TreeNode[] {
+  const root: Map<string, TreeNode> = new Map();
+
+  for (const note of notes) {
+    const parts = note.path.split('/');
+    let currentLevel = root;
+
+    for (let i = 0; i < parts.length; i++) {
+      const part = parts[i];
+      const isFile = i === parts.length - 1;
+      const id = parts.slice(0, i + 1).join('/');
+
+      if (!currentLevel.has(part)) {
+        currentLevel.set(part, {
+          id,
+          name: isFile ? note.title : part,
+          path: id,
+          isFolder: !isFile,
+          children: isFile ? undefined : new Map()
+        });
+      }
+
+      if (!isFile) {
+        currentLevel = currentLevel.get(part)!.children!;
+      }
+    }
+  }
+
+  return Array.from(root.values());
+}
+```
+
+**Styling for Obsidian-like appearance**:
+```css
+/* Custom styles for file tree */
+.tree-view-node {
+  @apply py-1 px-2 rounded hover:bg-accent transition-colors;
+}
+
+.tree-view-node.selected {
+  @apply bg-accent text-accent-foreground font-medium;
+}
+
+.tree-view-folder {
+  @apply flex items-center gap-2;
+}
+
+.tree-view-file {
+  @apply flex items-center gap-2 text-sm;
+}
+
+/* Icons */
+.folder-icon {
+  @apply text-yellow-500;
+}
+
+.file-icon {
+  @apply text-gray-500;
+}
+```
+
+**Collapsible behavior**:
+```tsx
+// Track expanded folders in state
+const [expanded, setExpanded] = useState<Set<string>>(new Set(['root']));
+
+<Tree
+  data={treeData}
+  expanded={expanded}
+  onExpandedChange={setExpanded}
+  // Auto-expand to selected note's folder
+  onSelectChange={(nodeId) => {
+    const path = nodeId.split('/');
+    const folders = path.slice(0, -1);
+    setExpanded(new Set([...expanded, ...folders]));
+  }}
+/>
+```
+
+**Key points**:
+- Virtualization is automatic with shadcn-extension Tree View (uses TanStack Virtual internally)
+- Must transform flat note list into nested tree structure (use `buildTree` utility)
+- Track expanded/collapsed state separately from tree data
+- Custom icons per node type (folder vs file) via `icon` prop
+- Use `ScrollArea` component from shadcn to wrap tree for custom scrollbars
+
+**Performance targets**:
+- Initial render: <200ms for 5,000 notes
+- Expand/collapse: <50ms per folder
+- Search filter: <100ms to re-render filtered tree
+
+**Accessibility**:
+- Keyboard navigation: Arrow keys to navigate, Enter to select, Space to expand/collapse
+- Screen reader support: ARIA labels for folders/files, expand/collapse state
+- Focus management: Visible focus indicators, focus restoration after selection
+
+---
+
+## 6. Optimistic Concurrency Implementation
+
+### Decision
+
+Use **version counter** (integer) stored in SQLite index with `if_version` parameter for UI writes. Implement **ETag-like validation** via `If-Match` header in HTTP API.
+
+**Approach**:
+- Version counter: Integer field in `note_metadata` table, incremented on every write
+- UI writes: Include `if_version: N` in `PUT /api/notes/{path}` body
+- Server validation: Compare `if_version` with current version; return `409 Conflict` if mismatch
+- MCP writes: No version checking (last-write-wins)
+- ETag header: Return `ETag: "<version>"` in `GET /api/notes/{path}` response for HTTP compliance
+
+### Rationale
+
+1. **Simple implementation**: Integer counter is trivial to increment and compare
+2. **Explicit versioning**: Version in request body makes intent clear ("I'm updating version 5")
+3. **Database-backed**: Version persists in index, not frontmatter (keeps note content clean)
+4. **HTTP-friendly**: Can expose as ETag header for standards compliance
+5. **Performance**: Integer comparison is O(1), no hash computation needed
+
+### Alternatives Considered
+
+**Alternative 1: ETag with content hash**
+- **Rejected**: Compute MD5/SHA hash of note content, return as ETag header
+- **Why rejected**: Hash computation on every read adds latency; version counter is sufficient and faster
+
+**Alternative 2: Last-Modified timestamps**
+- **Rejected**: Use `updated` timestamp + `If-Unmodified-Since` header
+- **Why rejected**: Timestamp precision issues (SQLite stores ISO strings, not microsecond precision); race conditions if multiple updates within same second
+
+**Alternative 3: Version in frontmatter**
+- **Rejected**: Store `version: 5` in YAML frontmatter
+- **Why rejected**: Pollutes user-facing metadata; incrementing version requires parsing/re-serializing frontmatter; harder to manage
+
+**Alternative 4: MVCC (Multi-Version Concurrency Control)**
+- **Rejected**: Store multiple versions of each note, allow rollback
+- **Why rejected**: Complex implementation; storage overhead; out of scope for MVP (no version history requirement)
+
+### Implementation Notes
+
+**Schema addition**:
+```sql
+-- Version counter in note_metadata table
+ALTER TABLE note_metadata ADD COLUMN version INTEGER NOT NULL DEFAULT 1;
+```
+
+**API endpoint implementation**:
+```python
+from fastapi import HTTPException, Header
+from typing import Optional
+
+@app.put("/api/notes/{path}")
+async def update_note(
+    path: str,
+    body: NoteUpdateRequest,
+    user_id: str = Depends(get_current_user),
+    if_match: Optional[str] = Header(None)  # ETag header support
+):
+    # Get current version
+    current = get_note_metadata(user_id, path)
+
+    # Check if_version in body OR If-Match header
+    expected_version = body.if_version or (int(if_match.strip('"')) if if_match else None)
+
+    if expected_version is not None and current.version != expected_version:
+        raise HTTPException(
+            status_code=409,
+            detail={
+                "error": "version_conflict",
+                "message": "Note was updated by another process",
+                "current_version": current.version,
+                "provided_version": expected_version
+            }
+        )
+
+    # Update note and increment version
+    new_version = current.version + 1
+    save_note(user_id, path, body.content)
+    update_metadata(user_id, path, version=new_version, updated=now())
+
+    return {
+        "status": "ok",
+        "version": new_version
+    }
+
+@app.get("/api/notes/{path}")
+async def get_note(
+    path: str,
+    user_id: str = Depends(get_current_user)
+):
+    note = load_note(user_id, path)
+
+    return JSONResponse(
+        content={
+            "path": note.path,
+            "title": note.title,
+            "metadata": note.metadata,
+            "body": note.body,
+            "version": note.version,
+            "created": note.created,
+            "updated": note.updated
+        },
+        headers={
+            "ETag": f'"{note.version}"',  # Expose version as ETag
+            "Cache-Control": "no-cache"   # Prevent stale reads
+        }
+    )
+```
+
+**Frontend implementation** (React):
+```typescript
+interface Note {
+  path: string;
+  title: string;
+  body: string;
+  version: number;
+  // ...
+}
+
+async function saveNote(note: Note, newBody: string) {
+  try {
+    const response = await fetch(`/api/notes/${encodeURIComponent(note.path)}`, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+        // Option 1: Version in body
+      },
+      body: JSON.stringify({
+        body: newBody,
+        if_version: note.version  // Optimistic concurrency check
+      })
+    });
+
+    if (response.status === 409) {
+      const error = await response.json();
+      alert(`Conflict: Note was updated (current version: ${error.current_version}). Please reload and try again.`);
+      return;
+    }
+
+    const updated = await response.json();
+    // Update local state with new version
+    setNote({ ...note, body: newBody, version: updated.version });
+
+  } catch (error) {
+    console.error('Save failed:', error);
+  }
+}
+```
+
+**MCP tool implementation** (last-write-wins):
+```python
+@mcp.tool()
+async def write_note(path: str, body: str, title: str = None) -> dict:
+    """Write note via MCP (no version checking)."""
+    user_id = get_user_from_context()
+
+    # Load existing note to get current version (if exists)
+    try:
+        current = get_note_metadata(user_id, path)
+        new_version = current.version + 1
+    except NotFoundError:
+        new_version = 1  # New note
+
+    # Write without version check (last-write-wins)
+    save_note(user_id, path, body, title)
+    update_metadata(user_id, path, version=new_version, updated=now())
+
+    return {"status": "ok", "path": path, "version": new_version}
+```
+
+**Conflict resolution UI**:
+```tsx
+function ConflictDialog({ currentVersion, serverVersion }: Props) {
+  return (
+    <Alert variant="destructive">
+      <AlertTitle>Version Conflict</AlertTitle>
+      <AlertDescription>
+        This note was updated while you were editing (version {currentVersion} → {serverVersion}).
+        <div className="mt-4 space-x-2">
+          <Button onClick={reload}>Reload and Discard Changes</Button>
+          <Button variant="outline" onClick={saveAsCopy}>Save as Copy</Button>
+        </div>
+      </AlertDescription>
+    </Alert>
+  );
+}
+```
+
+**Key points**:
+- Version counter starts at 1 for new notes, increments on every write
+- HTTP API returns `409 Conflict` with detailed error message (current vs provided version)
+- ETag header is optional but recommended for HTTP standards compliance
+- MCP writes skip version check (AI agents don't need optimistic concurrency)
+- Frontend shows clear error message with options: reload, save as copy, or manual merge
+
+**Performance considerations**:
+- Version check is single integer comparison (O(1))
+- No need to read entire note content for validation
+- Version update is atomic (SQLite transaction)
+
+**References**:
+- Optimistic concurrency patterns: https://event-driven.io/en/how_to_use_etag_header_for_optimistic_concurrency/
+- HTTP conditional requests: https://developer.mozilla.org/en-US/docs/Web/HTTP/Conditional_requests
+
+---
+
+## 7. Markdown Frontmatter Parsing with Fallback
+
+### Decision
+
+Use `python-frontmatter` library for YAML parsing with try-except wrapper to handle malformed frontmatter gracefully. Implement fallback strategy: malformed YAML → treat as no frontmatter, extract title from first `# Heading` or filename stem.
+
+**Parsing approach**:
+```python
+import frontmatter
+from pathlib import Path
+
+def parse_note(file_path: str) -> dict:
+    """Parse note with frontmatter fallback."""
+    try:
+        # Attempt to parse frontmatter
+        post = frontmatter.load(file_path)
+        metadata = dict(post.metadata)
+        body = post.content
+
+    except (yaml.scanner.ScannerError, yaml.parser.ParserError) as e:
+        # Malformed YAML - treat entire file as body
+        with open(file_path, 'r', encoding='utf-8') as f:
+            full_text = f.read()
+
+        metadata = {}
+        body = full_text
+
+        # Log warning for debugging
+        logger.warning(f"Malformed frontmatter in {file_path}: {e}")
+
+    # Extract title (priority: frontmatter > first H1 > filename)
+    title = (
+        metadata.get('title') or
+        extract_first_heading(body) or
+        Path(file_path).stem
+    )
+
+    return {
+        'title': title,
+        'metadata': metadata,
+        'body': body
+    }
+
+def extract_first_heading(markdown: str) -> str | None:
+    """Extract first # Heading from markdown body."""
+    match = re.match(r'^#\s+(.+)$', markdown, re.MULTILINE)
+    return match.group(1).strip() if match else None
+```
+
+### Rationale
+
+1. **Graceful degradation**: Malformed YAML doesn't break the system; note is still readable
+2. **User-friendly**: Non-technical users may create invalid YAML; system should be forgiving
+3. **Simple implementation**: Try-except wrapper is minimal code; `python-frontmatter` handles valid cases
+4. **Fallback chain**: Title extraction has clear priority order (explicit > inferred > default)
+5. **Debugging support**: Log warnings for malformed YAML so admins can fix source files
+
+### Alternatives Considered
+
+**Alternative 1: Strict parsing (fail on malformed YAML)**
+- **Rejected**: Raise error and reject note with invalid frontmatter
+- **Why rejected**: Poor UX; users may accidentally create invalid YAML (e.g., unquoted colons); breaks read-first workflow
+
+**Alternative 2: TOML or JSON frontmatter**
+- **Rejected**: Use `+++` TOML or `{{{ }}}` JSON delimiters instead of YAML
+- **Why rejected**: Obsidian uses YAML exclusively; compatibility is critical
+
+**Alternative 3: Lenient YAML parser**
+- **Rejected**: Use `ruamel.yaml` with error recovery instead of PyYAML
+- **Why rejected**: Adds complexity; `python-frontmatter` uses PyYAML internally; fallback strategy is simpler
+
+**Alternative 4: Partial frontmatter extraction**
+- **Rejected**: Parse valid keys, ignore malformed keys
+- **Why rejected**: Difficult to implement; unclear semantics (which keys are valid?); safer to treat all as invalid
+
+### Implementation Notes
+
+**Error types to catch**:
+```python
+import yaml
+
+try:
+    post = frontmatter.load(file_path)
+except (
+    yaml.scanner.ScannerError,  # Invalid YAML syntax (e.g., unmatched quotes)
+    yaml.parser.ParserError,    # Invalid YAML structure
+    UnicodeDecodeError          # Non-UTF8 file encoding
+) as e:
+    # Fallback to no frontmatter
+    pass
+```
+
+**Common malformed YAML examples**:
+```yaml
+---
+title: API Design: Overview  # Unquoted colon - INVALID
+tags: [backend, api]
+---
+
+---
+title: "Setup Guide
+description: Installation steps  # Unclosed quote - INVALID
+---
+
+---
+  title: Indented incorrectly  # Bad indentation - INVALID
+tags:
+- frontend
+---
+```
+
+**Auto-fix on write** (optional enhancement):
+```python
+def save_note(user_id: str, path: str, title: str, metadata: dict, body: str):
+    """Save note with valid frontmatter (auto-fix on write)."""
+    # Merge title into metadata
+    metadata['title'] = title
+
+    # Create Post object with validated metadata
+    post = frontmatter.Post(body, **metadata)
+
+    # Serialize with valid YAML
+    file_content = frontmatter.dumps(post)
+
+    # Write to file
+    full_path = get_vault_path(user_id) / path
+    full_path.write_text(file_content, encoding='utf-8')
+```
+
+**Title extraction regex**:
+```python
+def extract_first_heading(markdown: str) -> str | None:
+    """Extract first # Heading (must be H1, not H2/H3)."""
+    # Match # Heading (H1 only, not ## or ###)
+    pattern = r'^#\s+(.+?)(?:\s+\{[^}]+\})?\s*$'
+    match = re.search(pattern, markdown, re.MULTILINE)
+
+    if match:
+        heading = match.group(1).strip()
+        # Remove Markdown formatting (e.g., **bold**, *italic*)
+        heading = re.sub(r'[*_`]', '', heading)
+        return heading
+
+    return None
+```
+
+**Fallback priority**:
+1. `metadata.get('title')` - Explicit frontmatter title
+2. `extract_first_heading(body)` - First `# Heading` in body
+3. `Path(file_path).stem` - Filename without `.md` extension
+
+**Validation warnings**:
+```python
+# Add validation warnings to API response
+if malformed_frontmatter:
+    warnings.append({
+        "type": "malformed_frontmatter",
+        "message": "YAML frontmatter is invalid and was ignored",
+        "line": error.problem_mark.line if hasattr(error, 'problem_mark') else None
+    })
+```
+
+**UI display for warnings**:
+```tsx
+function NoteViewer({ note, warnings }: Props) {
+  return (
+    <div>
+      {warnings.map(w => (
+        <Alert key={w.type} variant="warning">
+          <AlertTitle>Warning</AlertTitle>
+          <AlertDescription>{w.message}</AlertDescription>
+        </Alert>
+      ))}
+      <Markdown>{note.body}</Markdown>
+    </div>
+  );
+}
+```
+
+**Key points**:
+- Always catch `yaml.scanner.ScannerError` and `yaml.parser.ParserError` from PyYAML
+- Log warnings with file path and error details for admin debugging
+- Prefer graceful fallback over strict validation (read-first workflow)
+- Auto-fix on write ensures newly saved notes have valid frontmatter
+- Extract title from first `# Heading`, not `## Subheading` (H1 only)
+
+**References**:
+- python-frontmatter docs: https://python-frontmatter.readthedocs.io/
+- PyYAML error handling: https://pyyaml.org/wiki/PyYAMLDocumentation
+
+---
+
+## 8. JWT Token Management in React
+
+### Decision
+
+Use **hybrid approach**: Store short-lived access token (JWT) in **memory** (React state/context), store long-lived refresh token in **HttpOnly cookie** (server-managed). For MVP without refresh tokens, store JWT in **memory only** with 90-day expiration.
+
+**MVP approach** (no refresh tokens):
+- Store JWT in React Context (memory)
+- Token expires after 90 days (long-lived)
+- On app load, check if token exists in memory → if not, redirect to login
+- No localStorage (XSS vulnerability mitigation)
+- No refresh flow (acceptable for MVP scale)
+
+**Production approach** (with refresh tokens):
+- Access token: 15-minute expiration, stored in memory
+- Refresh token: 90-day expiration, stored in HttpOnly cookie
+- Automatic refresh before access token expires
+- Refresh endpoint: `POST /api/auth/refresh` (validates cookie, issues new access token)
+
+### Rationale
+
+1. **XSS protection**: Memory storage prevents JavaScript-based token theft (localStorage is vulnerable to XSS)
+2. **CSRF protection**: HttpOnly cookies can't be accessed by JS, mitigating CSRF (when combined with SameSite attribute)
+3. **Industry best practice (2025)**: Hybrid approach is current security standard for React SPAs
+4. **Acceptable UX**: User logs in once per 90 days (or once per session if memory-only)
+5. **No additional dependencies**: Built-in React Context API handles memory storage
+
+### Alternatives Considered
+
+**Alternative 1: localStorage for JWT**
+- **Rejected**: Store JWT in `localStorage.setItem('token', jwt)`
+- **Why rejected**: Vulnerable to XSS attacks (malicious scripts can read localStorage); still in OWASP Top 10; unacceptable security risk for multi-tenant system
+
+**Alternative 2: sessionStorage for JWT**
+- **Rejected**: Store JWT in `sessionStorage` (cleared on tab close)
+- **Why rejected**: Poor UX (re-login on every new tab); still vulnerable to XSS
+
+**Alternative 3: Cookies for both access and refresh tokens**
+- **Rejected**: Store JWT in regular cookies (not HttpOnly)
+- **Why rejected**: Vulnerable to CSRF if not using HttpOnly; vulnerable to XSS if accessible to JS
+
+**Alternative 4: No token storage (re-authenticate on every request)**
+- **Rejected**: Use HF OAuth on every API call
+- **Why rejected**: Unacceptable latency; OAuth flow is slow (~2-3s per request)
+
+### Implementation Notes
+
+**MVP implementation** (memory-only, 90-day JWT):
+
+```typescript
+// Auth context (memory storage)
+import { createContext, useContext, useState, useEffect } from 'react';
+
+interface AuthContextType {
+  token: string | null;
+  setToken: (token: string) => void;
+  logout: () => void;
+}
+
+const AuthContext = createContext<AuthContextType | null>(null);
+
+export function AuthProvider({ children }: { children: React.ReactNode }) {
+  const [token, setTokenState] = useState<string | null>(null);
+
+  const setToken = (newToken: string) => {
+    setTokenState(newToken);
+  };
+
+  const logout = () => {
+    setTokenState(null);
+    window.location.href = '/oauth/huggingface/logout';
+  };
+
+  return (
+    <AuthContext.Provider value={{ token, setToken, logout }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth() {
+  const context = useContext(AuthContext);
+  if (!context) throw new Error('useAuth must be used within AuthProvider');
+  return context;
+}
+```
+
+```typescript
+// App initialization (fetch token after OAuth)
+function App() {
+  const { token, setToken } = useAuth();
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Check if authenticated via HF OAuth
+    fetch('/api/me')
+      .then(res => {
+        if (!res.ok) throw new Error('Not authenticated');
+        return res.json();
+      })
+      .then(user => {
+        // Issue JWT token for API access
+        return fetch('/api/tokens', { method: 'POST' });
+      })
+      .then(res => res.json())
+      .then(data => {
+        setToken(data.token);
+        setLoading(false);
+      })
+      .catch(() => {
+        // Redirect to OAuth login
+        window.location.href = '/oauth/huggingface/login';
+      });
+  }, []);
+
+  if (loading) return <div>Loading...</div>;
+
+  return <MainApp />;
+}
+```
+
+```typescript
+// API client (include token in headers)
+async function apiRequest(endpoint: string, options: RequestInit = {}) {
+  const { token } = useAuth();
+
+  const response = await fetch(`/api${endpoint}`, {
+    ...options,
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${token}`,
+      ...options.headers
+    }
+  });
+
+  if (response.status === 401) {
+    // Token expired or invalid
+    logout();
+    throw new Error('Unauthorized');
+  }
+
+  return response;
+}
+```
+
+**Production implementation** (with refresh tokens):
+
+```typescript
+// Token refresh logic
+let refreshPromise: Promise<string> | null = null;
+
+async function refreshAccessToken(): Promise<string> {
+  // Prevent multiple concurrent refresh calls
+  if (refreshPromise) return refreshPromise;
+
+  refreshPromise = fetch('/api/auth/refresh', {
+    method: 'POST',
+    credentials: 'include'  // Send HttpOnly cookie
+  })
+    .then(res => {
+      if (!res.ok) throw new Error('Refresh failed');
+      return res.json();
+    })
+    .then(data => {
+      setToken(data.access_token);
+      refreshPromise = null;
+      return data.access_token;
+    })
+    .catch(err => {
+      refreshPromise = null;
+      logout();
+      throw err;
+    });
+
+  return refreshPromise;
+}
+
+// Automatic refresh before token expires
+useEffect(() => {
+  if (!token) return;
+
+  // Parse token to get expiration
+  const payload = JSON.parse(atob(token.split('.')[1]));
+  const expiresAt = payload.exp * 1000;
+  const now = Date.now();
+  const refreshAt = expiresAt - (5 * 60 * 1000);  // 5 minutes before expiry
+
+  const timeoutId = setTimeout(() => {
+    refreshAccessToken();
+  }, refreshAt - now);
+
+  return () => clearTimeout(timeoutId);
+}, [token]);
+```
+
+**Backend refresh endpoint**:
+```python
+from fastapi import Cookie, HTTPException
+
+@app.post("/api/auth/refresh")
+async def refresh_token(
+    refresh_token: str = Cookie(None, httponly=True, samesite='strict')
+):
+    if not refresh_token:
+        raise HTTPException(status_code=401, detail="No refresh token")
+
+    # Validate refresh token
+    try:
+        payload = jwt.decode(refresh_token, SECRET_KEY, algorithms=["HS256"])
+        user_id = payload["sub"]
+    except jwt.ExpiredSignatureError:
+        raise HTTPException(status_code=401, detail="Refresh token expired")
+    except jwt.InvalidTokenError:
+        raise HTTPException(status_code=401, detail="Invalid refresh token")
+
+    # Issue new access token (15-minute expiry)
+    access_token = create_jwt(user_id, expiration_minutes=15)
+
+    return {"access_token": access_token, "token_type": "bearer"}
+```
+
+**Key points**:
+- Memory storage = token lost on page refresh (re-login required) → acceptable for MVP
+- HttpOnly cookies cannot be accessed by JavaScript (XSS protection)
+- Set `SameSite=strict` on refresh token cookie (CSRF protection)
+- Refresh token rotation: issue new refresh token on each refresh (advanced security)
+- Use `credentials: 'include'` in fetch to send HttpOnly cookies
+- Parse JWT client-side to schedule refresh (or use server-sent expiry hint)
+
+**Security checklist**:
+- ✅ Access token in memory (XSS-resistant)
+- ✅ Refresh token in HttpOnly cookie (XSS-resistant)
+- ✅ SameSite=strict on cookies (CSRF-resistant)
+- ✅ HTTPS required (prevent MITM)
+- ✅ Short access token expiry (limit blast radius)
+- ✅ Token refresh before expiry (seamless UX)
+- ✅ Logout clears both tokens
+
+**MVP vs Production tradeoff**:
+- **MVP**: 90-day JWT in memory → simpler, acceptable for hackathon/PoC
+- **Production**: 15-min access + 90-day refresh → better security, more complex
+
+**References**:
+- JWT storage best practices: https://www.descope.com/blog/post/developer-guide-jwt-storage
+- HttpOnly cookies vs localStorage: https://www.wisp.blog/blog/understanding-token-storage-local-storage-vs-httponly-cookies
+- React authentication patterns: https://marmelab.com/blog/2020/07/02/manage-your-jwt-react-admin-authentication-in-memory.html
+
+---
+
+## Summary of Key Decisions
+
+| Topic | Decision | Primary Rationale |
+|-------|----------|-------------------|
+| **FastMCP Auth** | Bearer token with JWT validation | Native FastMCP support, minimal config, standard-compliant |
+| **HF OAuth** | `attach_huggingface_oauth` + `parse_huggingface_oauth` | Zero-config, local dev friendly, official HF support |
+| **SQLite Schema** | FTS5 for full-text + separate tables for tags/links | Performance, per-user isolation, optimized query patterns |
+| **Wikilink Resolution** | Case-insensitive slug matching + same-folder preference | Obsidian compatibility, user-friendly, deterministic |
+| **Directory Tree** | shadcn-extension Tree View with virtualization | Only shadcn option with virtualization for 5K+ notes |
+| **Optimistic Concurrency** | Version counter in SQLite + `if_version` param | Simple, fast, HTTP-friendly, no content hashing overhead |
+| **Frontmatter Parsing** | `python-frontmatter` + fallback to no frontmatter | Graceful degradation, user-friendly error handling |
+| **JWT Management** | Memory storage (MVP) or memory + HttpOnly cookie (prod) | XSS protection, industry best practice (2025) |
+
+---
+
+## Next Steps
+
+With research complete, proceed to **Phase 1: Data Model & Contracts**:
+
+1. Create `data-model.md` with detailed Pydantic models and SQLite schemas
+2. Create `contracts/http-api.yaml` with OpenAPI 3.1 specification
+3. Create `contracts/mcp-tools.json` with MCP tool schemas (JSON Schema format)
+4. Create `quickstart.md` with setup instructions and testing workflows
+
+After Phase 1, run `/speckit.tasks` to generate dependency-ordered implementation tasks.

specs/001-obsidian-docs-viewer/tasks.md

@@ -0,0 +1,300 @@
+# Implementation Tasks: Multi-Tenant Obsidian-Like Docs Viewer
+
+**Feature Branch**: `001-obsidian-docs-viewer`
+**Created**: 2025-11-15
+**Status**: Ready for Implementation
+
+## Implementation Strategy
+
+**MVP = User Story 1 (AI Agent Writes) + User Story 2 (Human Reads UI)**
+
+The MVP delivers immediate value:
+- AI agents (via MCP STDIO) can create and maintain documentation
+- Humans can browse, search, and read documentation in the web UI
+- Full-text search, wikilinks, tags, and backlinks work end-to-end
+
+**Post-MVP enhancements**:
+- User Story 3: Human editing with version conflict detection
+- User Story 4: Multi-tenant HF OAuth for production deployment
+- User Story 5: Advanced search ranking and index health monitoring
+
+---
+
+## Phase 1: Setup
+
+**Goal**: Initialize project structure, dependencies, and database schema.
+
+- [ ] [T001] Create project directory structure at /home/wolfe/Projects/Document-MCP
+- [ ] [T002] [P] Create backend/src/models/ directory and __init__.py
+- [ ] [T003] [P] Create backend/src/services/ directory and __init__.py
+- [ ] [T004] [P] Create backend/src/api/routes/ directory and __init__.py
+- [ ] [T005] [P] Create backend/src/api/middleware/ directory and __init__.py
+- [ ] [T006] [P] Create backend/src/mcp/ directory and __init__.py
+- [ ] [T007] [P] Create backend/tests/unit/ directory and __init__.py
+- [ ] [T008] [P] Create backend/tests/integration/ directory and __init__.py
+- [ ] [T009] [P] Create backend/tests/contract/ directory and __init__.py
+- [ ] [T010] [P] Create frontend/src/components/ui/ directory
+- [ ] [T011] [P] Create frontend/src/pages/ directory
+- [ ] [T012] [P] Create frontend/src/services/ directory
+- [ ] [T013] [P] Create frontend/src/lib/ directory
+- [ ] [T014] [P] Create frontend/src/types/ directory
+- [ ] [T015] [P] Create frontend/tests/unit/ directory
+- [ ] [T016] [P] Create frontend/tests/e2e/ directory
+- [ ] [T017] [P] Create data/vaults/ directory for runtime vault storage
+- [ ] [T018] Create backend/pyproject.toml with dependencies: fastapi, fastmcp, python-frontmatter, pyjwt, huggingface_hub, uvicorn
+- [ ] [T019] Create frontend/package.json with dependencies: react, vite, typescript, shadcn/ui, react-markdown
+- [ ] [T020] Create frontend/vite.config.ts with proxy to backend API
+- [ ] [T021] Create .env.example with JWT_SECRET_KEY, HF_OAUTH_CLIENT_ID, HF_OAUTH_CLIENT_SECRET, VAULT_BASE_PATH
+- [ ] [T022] Create .gitignore to exclude data/, .env, node_modules/, __pycache__, dist/
+- [ ] [T023] Create backend/src/services/database.py with SQLite initialization DDL from data-model.md
+- [ ] [T024] Execute SQLite schema initialization (note_metadata, note_fts, note_tags, note_links, index_health tables)
+
+---
+
+## Phase 2: Foundational
+
+**Goal**: Build core infrastructure required by all user stories.
+
+- [ ] [T025] Create backend/src/services/config.py to load env vars: JWT_SECRET_KEY, VAULT_BASE_PATH, HF_OAUTH_CLIENT_ID, HF_OAUTH_CLIENT_SECRET
+- [ ] [T026] [P] Create backend/src/models/user.py with User and HFProfile Pydantic models from data-model.md
+- [ ] [T027] [P] Create backend/src/models/note.py with Note, NoteMetadata, NoteCreate, NoteUpdate, NoteSummary Pydantic models from data-model.md
+- [ ] [T028] [P] Create backend/src/models/index.py with Wikilink, Tag, IndexHealth Pydantic models from data-model.md
+- [ ] [T029] [P] Create backend/src/models/search.py with SearchResult, SearchRequest Pydantic models from data-model.md
+- [ ] [T030] [P] Create backend/src/models/auth.py with TokenResponse, JWTPayload Pydantic models from data-model.md
+- [ ] [T031] [P] Create frontend/src/types/user.ts with User and HFProfile TypeScript types from data-model.md
+- [ ] [T032] [P] Create frontend/src/types/note.ts with Note, NoteMetadata, NoteSummary, NoteCreateRequest, NoteUpdateRequest TypeScript types from data-model.md
+- [ ] [T033] [P] Create frontend/src/types/search.ts with SearchResult, Tag, IndexHealth TypeScript types from data-model.md
+- [ ] [T034] [P] Create frontend/src/types/auth.ts with TokenResponse, APIError TypeScript types from data-model.md
+- [ ] [T035] Create backend/src/services/vault.py with VaultService class: path validation, sanitization (sanitize_path function from data-model.md), vault directory initialization
+- [ ] [T036] Create backend/src/services/auth.py with AuthService class: JWT creation (create_jwt), validation (validate_jwt), placeholder for HF OAuth
+- [ ] [T037] Create backend/src/api/middleware/auth_middleware.py with extract_user_id_from_jwt function to validate Authorization: Bearer header
+- [ ] [T038] Create backend/src/api/middleware/error_handlers.py with FastAPI exception handlers for 400, 401, 403, 404, 409, 413, 500 from http-api.yaml
+
+---
+
+## Phase 3: User Story 1 - AI Agent Writes (P1)
+
+**Goal**: Enable AI agents to write/update docs via MCP STDIO, with automatic indexing.
+
+- [ ] [T039] [US1] Create backend/src/services/vault.py VaultService.read_note method: read file, parse frontmatter with python-frontmatter, extract title (priority: frontmatter > H1 > filename stem)
+- [ ] [T040] [US1] Create backend/src/services/vault.py VaultService.write_note method: validate path/content, create parent dirs, write frontmatter + body, return absolute path
+- [ ] [T041] [US1] Create backend/src/services/vault.py VaultService.delete_note method: validate path, remove file, handle FileNotFoundError
+- [ ] [T042] [US1] Create backend/src/services/vault.py VaultService.list_notes method: walk vault tree, filter by folder param, return paths and titles
+- [ ] [T043] [US1] Create backend/src/services/indexer.py IndexerService class with db connection management
+- [ ] [T044] [US1] Create backend/src/services/indexer.py IndexerService.index_note method: delete old rows for (user_id, note_path), insert into note_metadata, note_fts, note_tags, note_links
+- [ ] [T045] [US1] Create backend/src/services/indexer.py IndexerService.extract_wikilinks method: regex pattern \[\[([^\]]+)\]\] to extract link_text from body
+- [ ] [T046] [US1] Create backend/src/services/indexer.py IndexerService.resolve_wikilinks method: normalize slug (data-model.md algorithm), match against normalized_title_slug and normalized_path_slug, prefer same-folder, update is_resolved
+- [ ] [T047] [US1] Create backend/src/services/indexer.py IndexerService.increment_version method: get current version or default to 1, increment, return new version
+- [ ] [T048] [US1] Create backend/src/services/indexer.py IndexerService.update_index_health method: update note_count, last_incremental_update timestamp
+- [ ] [T049] [US1] Create backend/src/services/indexer.py IndexerService.delete_note_index method: delete rows from all index tables, update backlinks to set is_resolved=false
+- [ ] [T050] [US1] Create backend/src/mcp/server.py FastMCP server initialization with name="obsidian-docs-viewer"
+- [ ] [T051] [US1] Create backend/src/mcp/server.py list_notes MCP tool: call VaultService.list_notes, return [{path, title, last_modified}]
+- [ ] [T052] [US1] Create backend/src/mcp/server.py read_note MCP tool: call VaultService.read_note, return {path, title, metadata, body}
+- [ ] [T053] [US1] Create backend/src/mcp/server.py write_note MCP tool: call VaultService.write_note, then IndexerService.index_note, return {status: "ok", path}
+- [ ] [T054] [US1] Create backend/src/mcp/server.py delete_note MCP tool: call VaultService.delete_note, then IndexerService.delete_note_index, return {status: "ok"}
+- [ ] [T055] [US1] Create backend/src/mcp/server.py search_notes MCP tool: query note_fts with bm25 ranking (3.0 title weight, 1.0 body weight), add recency bonus, return [{path, title, snippet}]
+- [ ] [T056] [US1] Create backend/src/mcp/server.py get_backlinks MCP tool: query note_links WHERE target_path=?, join note_metadata, return [{path, title}]
+- [ ] [T057] [US1] Create backend/src/mcp/server.py get_tags MCP tool: query note_tags GROUP BY tag, return [{tag, count}]
+- [ ] [T058] [US1] Create backend/src/mcp/server.py STDIO transport mode: if __name__ == "__main__", run FastMCP with stdio transport for local development
+- [ ] [T059] [US1] Add recency bonus calculation to search_notes: +1.0 for updated in last 7 days, +0.5 for last 30 days, 0 otherwise
+
+---
+
+## Phase 4: User Story 2 - Human Reads UI (P1)
+
+**Goal**: Web UI for browsing, searching, and reading notes with wikilinks and backlinks.
+
+- [ ] [T060] [US2] Create backend/src/api/routes/notes.py with GET /api/notes endpoint: call VaultService.list_notes, return NoteSummary[] from http-api.yaml
+- [ ] [T061] [US2] Create backend/src/api/routes/notes.py with GET /api/notes/{path} endpoint: URL-decode path, call VaultService.read_note, return Note from http-api.yaml
+- [ ] [T062] [US2] Create backend/src/api/routes/search.py with GET /api/search endpoint: call IndexerService search with query param, return SearchResult[] from http-api.yaml
+- [ ] [T063] [US2] Create backend/src/api/routes/search.py with GET /api/backlinks/{path} endpoint: URL-decode path, query note_links, return BacklinkResult[] from http-api.yaml
+- [ ] [T064] [US2] Create backend/src/api/routes/search.py with GET /api/tags endpoint: query note_tags, return Tag[] from http-api.yaml
+- [ ] [T065] [US2] Create backend/src/api/main.py FastAPI app with CORS middleware, mount routes, include error handlers
+- [ ] [T066] [US2] Create frontend/src/services/api.ts API client with fetch wrapper: add Authorization: Bearer header, handle JSON responses, throw APIError on non-200
+- [ ] [T067] [US2] Create frontend/src/services/api.ts listNotes function: GET /api/notes?folder=, return NoteSummary[]
+- [ ] [T068] [US2] Create frontend/src/services/api.ts getNote function: GET /api/notes/{encodeURIComponent(path)}, return Note
+- [ ] [T069] [US2] Create frontend/src/services/api.ts searchNotes function: GET /api/search?q=, return SearchResult[]
+- [ ] [T070] [US2] Create frontend/src/services/api.ts getBacklinks function: GET /api/backlinks/{encodeURIComponent(path)}, return BacklinkResult[]
+- [ ] [T071] [US2] Create frontend/src/services/api.ts getTags function: GET /api/tags, return Tag[]
+- [ ] [T072] [US2] Create frontend/src/lib/wikilink.ts with extractWikilinks function: regex /\[\[([^\]]+)\]\]/g
+- [ ] [T073] [US2] Create frontend/src/lib/wikilink.ts with normalizeSlug function: lowercase, replace spaces/underscores with dash, strip non-alphanumeric
+- [ ] [T074] [US2] Create frontend/src/lib/markdown.ts with react-markdown config: code highlighting, wikilink custom renderer
+- [ ] [T075] [US2] Initialize shadcn/ui in frontend/: run npx shadcn-ui@latest init, select default theme
+- [ ] [T076] [US2] Install shadcn/ui components: ScrollArea, Button, Input, Card, Badge
+- [ ] [T077] [US2] Create frontend/src/components/DirectoryTree.tsx: recursive tree view with collapsible folders, leaf items for notes, onClick handler to load note
+- [ ] [T078] [US2] Create frontend/src/components/NoteViewer.tsx: render note title, metadata (tags as badges, timestamps), react-markdown body with wikilink links, backlinks section in footer
+- [ ] [T079] [US2] Create frontend/src/components/SearchBar.tsx: Input with debounced onChange (300ms), dropdown results with onClick to navigate to note
+- [ ] [T080] [US2] Create frontend/src/pages/App.tsx: two-pane layout (left: DirectoryTree + SearchBar in ScrollArea, right: NoteViewer), state management for selected note path
+- [ ] [T081] [US2] Add wikilink click handler in NoteViewer: onClick [[link]] → normalizeSlug → API lookup → navigate to resolved note
+- [ ] [T082] [US2] Add broken wikilink styling in NoteViewer: render unresolved [[links]] with distinct color/style
+- [ ] [T083] [US2] Create frontend/src/pages/App.tsx useEffect to load directory tree on mount: call listNotes()
+- [ ] [T084] [US2] Create frontend/src/pages/App.tsx useEffect to load note when path changes: call getNote(path) and getBacklinks(path)
+
+---
+
+## Phase 5: User Story 3 - Human Edits UI (P2)
+
+**Goal**: Split-pane editor with optimistic concurrency protection.
+
+- [ ] [T085] [US3] Create backend/src/api/routes/notes.py with PUT /api/notes/{path} endpoint: URL-decode path, validate request body (NoteUpdate), check if_version, call VaultService.write_note, return NoteResponse from http-api.yaml
+- [ ] [T086] [US3] Add optimistic concurrency check in IndexerService.increment_version: if if_version provided and != current version, raise ConflictError
+- [ ] [T087] [US3] Create ConflictError exception in backend/src/models/errors.py, map to 409 Conflict in error_handlers.py
+- [ ] [T088] [US3] Create frontend/src/services/api.ts updateNote function: PUT /api/notes/{encodeURIComponent(path)} with {title?, metadata?, body, if_version?}, handle 409 response
+- [ ] [T089] [US3] Create frontend/src/components/NoteEditor.tsx: split-pane layout (left: textarea for markdown source, right: live preview with react-markdown)
+- [ ] [T090] [US3] Create frontend/src/components/NoteEditor.tsx with Save button: onClick → call updateNote with if_version from initial note load, handle success → switch to read mode
+- [ ] [T091] [US3] Create frontend/src/components/NoteEditor.tsx with Cancel button: onClick → discard changes, switch to read mode
+- [ ] [T092] [US3] Add 409 Conflict error handling in NoteEditor: display alert "Note changed since you opened it, please reload before saving"
+- [ ] [T093] [US3] Add Edit button to NoteViewer: onClick → switch main pane to NoteEditor mode, pass current note version
+- [ ] [T094] [US3] Update frontend/src/pages/App.tsx to toggle between NoteViewer and NoteEditor based on edit mode state
+
+---
+
+## Phase 6: User Story 4 - Multi-Tenant OAuth (P2)
+
+**Goal**: HF OAuth login, per-user vaults, JWT tokens for API and MCP HTTP.
+
+- [ ] [T095] [US4] Create backend/src/services/auth.py HF OAuth integration: use huggingface_hub.attach_huggingface_oauth and parse_huggingface_oauth helpers
+- [ ] [T096] [US4] Create backend/src/api/routes/auth.py with GET /auth/login endpoint: redirect to HF OAuth authorize URL
+- [ ] [T097] [US4] Create backend/src/api/routes/auth.py with GET /auth/callback endpoint: parse_huggingface_oauth, map HF username to user_id, create vault if new user, set session cookie
+- [ ] [T098] [US4] Create backend/src/api/routes/auth.py with POST /api/tokens endpoint: validate authenticated user, call AuthService.create_jwt, return TokenResponse from http-api.yaml
+- [ ] [T099] [US4] Create backend/src/api/routes/auth.py with GET /api/me endpoint: validate Bearer token, return User from http-api.yaml
+- [ ] [T100] [US4] Update backend/src/api/middleware/auth_middleware.py to extract user_id from JWT sub claim, attach to request.state.user_id
+- [ ] [T101] [US4] Update backend/src/services/vault.py to scope all operations by user_id: vault path = VAULT_BASE_PATH / user_id
+- [ ] [T102] [US4] Update backend/src/services/indexer.py to scope all queries by user_id: WHERE user_id = ?
+- [ ] [T103] [US4] Initialize vault and index on first user login: create vault dir, insert initial index_health row
+- [ ] [T104] [US4] Create backend/src/mcp/server.py HTTP transport mode: FastMCP with http transport, BearerAuth validation, extract user_id from JWT
+- [ ] [T105] [US4] Create frontend/src/services/auth.ts with login function: redirect to /auth/login
+- [ ] [T106] [US4] Create frontend/src/services/auth.ts with getCurrentUser function: GET /api/me, return User
+- [ ] [T107] [US4] Create frontend/src/services/auth.ts with getToken function: POST /api/tokens, return TokenResponse, store token in memory
+- [ ] [T108] [US4] Create frontend/src/pages/Login.tsx: "Sign in with Hugging Face" button → onClick call auth.login()
+- [ ] [T109] [US4] Create frontend/src/pages/Settings.tsx: display user profile (user_id, HF avatar), API token with copy button for MCP config
+- [ ] [T110] [US4] Update frontend/src/pages/App.tsx to call getCurrentUser on mount, redirect to Login if 401
+- [ ] [T111] [US4] Update frontend/src/services/api.ts to include token from auth.getToken() in Authorization header
+
+---
+
+## Phase 7: User Story 5 - Advanced Search (P3)
+
+**Goal**: Enhanced search ranking and index health monitoring.
+
+- [ ] [T112] [US5] Update backend/src/services/indexer.py search_notes to calculate recency bonus: +1.0 for updated in last 7 days, +0.5 for last 30 days, 0 otherwise
+- [ ] [T113] [US5] Update backend/src/services/indexer.py search_notes to calculate final score: (3 * title_bm25) + (1 * body_bm25) + recency_bonus
+- [ ] [T114] [US5] Create backend/src/api/routes/index.py with GET /api/index/health endpoint: query index_health, return IndexHealth from http-api.yaml
+- [ ] [T115] [US5] Create backend/src/api/routes/index.py with POST /api/index/rebuild endpoint: call IndexerService.rebuild_index, return RebuildResponse from http-api.yaml
+- [ ] [T116] [US5] Create backend/src/services/indexer.py IndexerService.rebuild_index method: delete all user rows, walk vault, parse all notes, re-insert into all index tables, update index_health
+- [ ] [T117] [US5] Create frontend/src/services/api.ts getIndexHealth function: GET /api/index/health, return IndexHealth
+- [ ] [T118] [US5] Create frontend/src/services/api.ts rebuildIndex function: POST /api/index/rebuild, return RebuildResponse
+- [ ] [T119] [US5] Add index health indicator to frontend/src/pages/App.tsx: display note count and last updated timestamp in footer
+- [ ] [T120] [US5] Add "Rebuild Index" button to frontend/src/pages/Settings.tsx: onClick → call rebuildIndex, show progress/completion message
+
+---
+
+## Phase 8: Polish & Cross-Cutting
+
+**Goal**: Documentation, configuration, logging, error handling improvements.
+
+- [ ] [T121] Create README.md with project overview, tech stack, local setup instructions (backend venv + npm install)
+- [ ] [T122] Add README.md section: "Running Backend" with uvicorn command for HTTP API and python -m backend.src.mcp.server for MCP STDIO
+- [ ] [T123] Add README.md section: "Running Frontend" with npm run dev command
+- [ ] [T124] Add README.md section: "MCP Client Configuration" with Claude Code/Desktop STDIO example from mcp-tools.json
+- [ ] [T125] Add README.md section: "Deploying to Hugging Face Space" with environment variables and OAuth setup
+- [ ] [T126] Update .env.example with all variables: JWT_SECRET_KEY, VAULT_BASE_PATH, HF_OAUTH_CLIENT_ID, HF_OAUTH_CLIENT_SECRET, DATABASE_PATH
+- [ ] [T127] Add structured logging to backend/src/services/vault.py: log file operations with user_id, note_path, operation type
+- [ ] [T128] Add structured logging to backend/src/services/indexer.py: log index updates with user_id, note_path, duration_ms
+- [ ] [T129] Add structured logging to backend/src/mcp/server.py: log MCP tool calls with tool_name, user_id, duration_ms
+- [ ] [T130] Improve error messages in backend/src/api/middleware/error_handlers.py: include detail objects with field names and reasons
+- [ ] [T131] Add input validation to all HTTP API routes: validate path format, content size, required fields
+- [ ] [T132] Add input validation to all MCP tools: validate path format, content size via Pydantic models
+- [ ] [T133] Add rate limiting consideration to README.md: note potential need for per-user rate limits in production
+- [ ] [T134] Add performance optimization notes to README.md: FTS5 prefix indexes, SQLite WAL mode for concurrency
+
+---
+
+## Dependencies
+
+### Story Completion Order
+
+**Must complete in this order**:
+1. **Phase 1** (Setup) → **Phase 2** (Foundational) → **Phase 3** (US1) + **Phase 4** (US2) in parallel
+2. **Phase 5** (US3) depends on Phase 4 (needs HTTP API routes from US2)
+3. **Phase 6** (US4) depends on Phase 2 (needs auth foundation) and Phase 3 (needs vault/indexer)
+4. **Phase 7** (US5) depends on Phase 3 (needs indexer) and Phase 4 (needs HTTP API)
+5. **Phase 8** (Polish) can run anytime after Phase 4 (MVP complete)
+
+### Task Dependencies
+
+**Critical path** (must be sequential):
+- T023 (SQLite schema) → T043 (IndexerService) → T044 (index_note)
+- T035 (VaultService foundation) → T039 (read_note) → T040 (write_note)
+- T050 (FastMCP init) → T051-T057 (MCP tools)
+- T065 (FastAPI app) → T060-T064 (HTTP routes)
+
+**Parallelizable within phases** (marked with [P]):
+- All directory creation tasks (T002-T017)
+- All Pydantic model tasks (T026-T030)
+- All TypeScript type tasks (T031-T034)
+- All frontend component tasks within US2 (T077-T079)
+
+---
+
+## Parallel Execution Examples
+
+### User Story 1 (AI Agent Writes) - Parallel Work
+
+**Team A**: VaultService implementation (T039-T042)
+**Team B**: IndexerService implementation (T043-T049)
+**Team C**: MCP tools implementation (T051-T057)
+
+After T050 (FastMCP init) completes, Team C can implement all 7 MCP tools in parallel since they're independent endpoints.
+
+### User Story 2 (Human Reads UI) - Parallel Work
+
+**Team A**: Backend HTTP API routes (T060-T064)
+**Team B**: Frontend API client (T066-T071)
+**Team C**: Frontend components (T077-T079)
+
+After T065 (FastAPI app) and T075-T076 (shadcn/ui setup) complete, all three teams can work in parallel.
+
+### User Story 4 (Multi-Tenant OAuth) - Parallel Work
+
+**Team A**: Backend OAuth integration (T095-T104)
+**Team B**: Frontend auth flow (T105-T111)
+
+Both teams can work in parallel after Phase 2 (Foundational) completes.
+
+---
+
+## Summary
+
+**Total Tasks**: 134
+- **Phase 1 (Setup)**: 24 tasks
+- **Phase 2 (Foundational)**: 14 tasks
+- **Phase 3 (US1 - AI Agent Writes)**: 21 tasks
+- **Phase 4 (US2 - Human Reads UI)**: 25 tasks
+- **Phase 5 (US3 - Human Edits UI)**: 10 tasks
+- **Phase 6 (US4 - Multi-Tenant OAuth)**: 17 tasks
+- **Phase 7 (US5 - Advanced Search)**: 9 tasks
+- **Phase 8 (Polish)**: 14 tasks
+
+**MVP Tasks** (US1 + US2): 84 tasks (Phases 1-4)
+**Post-MVP Tasks** (US3 + US4 + US5): 36 tasks (Phases 5-7)
+**Polish Tasks**: 14 tasks (Phase 8)
+
+**Estimated Effort**:
+- MVP (US1 + US2): ~2-3 weeks (1-2 developers)
+- Post-MVP (US3 + US4 + US5): ~1-2 weeks
+- Polish: ~3-5 days
+- **Total**: ~4-6 weeks for complete implementation
+
+**Key Milestones**:
+1. **Week 1**: Complete Phase 1-2 (Setup + Foundational)
+2. **Week 2**: Complete Phase 3 (US1 - MCP STDIO working)
+3. **Week 3**: Complete Phase 4 (US2 - Web UI working, MVP delivered)
+4. **Week 4**: Complete Phase 5-6 (US3 editing + US4 multi-tenant)
+5. **Week 5**: Complete Phase 7-8 (US5 advanced search + Polish)
+
+**Next Steps**:
+1. Review this task breakdown with stakeholders
+2. Assign initial tasks (Phase 1 Setup) to team
+3. Create GitHub issues from tasks using `/speckit.taskstoissues`
+4. Begin implementation with T001 (project structure)