amalfa 1.0.1 → 1.0.2

package/public/docs/MCP_TOOLS.md

@@ -1,372 +0,0 @@
-# AMALFA MCP Tools
-
-Documentation for Model Context Protocol (MCP) tools provided by AMALFA.
-
-## Overview
-
-AMALFA exposes 5 tools through the MCP protocol for AI agents to interact with your knowledge graph:
-
-1. **search_documents** - Semantic vector search
-2. **read_node_content** - Read full markdown content
-3. **explore_links** - Graph traversal (find related nodes)
-4. **list_directory_structure** - View document organization
-5. **inject_tags** - Add semantic tags to files (experimental)
-
-## Tools
-
-### 1. search_documents
-
-**Purpose**: Search the knowledge graph using semantic vector search.
-
-**Parameters**:
-```json
-{
-  "query": "string (required)",
-  "limit": "number (optional, default: 20)"
-}
-```
-
-**Example Request**:
-```json
-{
-  "name": "search_documents",
-  "arguments": {
-    "query": "machine learning architectures",
-    "limit": 10
-  }
-}
-```
-
-**Example Response**:
-```json
-[
-  {
-    "id": "neural-networks",
-    "score": "0.847",
-    "preview": "Neural networks are computing systems inspired by biological neural networks...",
-    "source": "vector"
-  },
-  {
-    "id": "deep-learning",
-    "score": "0.823",
-    "preview": "Deep learning is part of a broader family of machine learning methods...",
-    "source": "vector"
-  }
-]
-```
-
-**Notes**:
-- Uses 384-dimensional vector embeddings (BAAI/bge-small-en-v1.5)
-- Scores range from 0.0 to 1.0 (cosine similarity)
-- Results are sorted by relevance (highest score first)
-- Preview is first 200 characters of content
-
-### 2. read_node_content
-
-**Purpose**: Retrieve the full markdown content of a specific document.
-
-**Parameters**:
-```json
-{
-  "id": "string (required)"
-}
-```
-
-**Example Request**:
-```json
-{
-  "name": "read_node_content",
-  "arguments": {
-    "id": "neural-networks"
-  }
-}
-```
-
-**Example Response**:
-```markdown
-# Neural Networks
-
-Neural networks are computing systems inspired by biological neural networks...
-
-## Architecture
-
-[[Deep Learning]] architectures consist of multiple layers:
-
-1. Input layer
-2. Hidden layers
-3. Output layer
-
-<!-- tags: [DOMAIN: machine-learning] -->
-```
-
-**Notes**:
-- Returns raw markdown content from source file
-- Implements "Hollow Nodes" pattern (content not stored in database)
-- Includes frontmatter, WikiLinks, and metadata
-- Returns error if node ID not found or file missing
-
-### 3. explore_links
-
-**Purpose**: Find related documents through graph traversal.
-
-**Parameters**:
-```json
-{
-  "id": "string (required)",
-  "relation": "string (optional)"
-}
-```
-
-**Relation Types**:
-- `CITES` - WikiLink references (`[[Document]]`)
-- `TAGGED_AS` - Semantic tags (`[tag: Concept]`)
-- `EXEMPLIFIES` - Legacy tag references (`tag-concept`)
-- `RELATED_TO` - Generic relationships
-- Custom - User-defined metadata tags
-
-**Example Request**:
-```json
-{
-  "name": "explore_links",
-  "arguments": {
-    "id": "neural-networks",
-    "relation": "CITES"
-  }
-}
-```
-
-**Example Response**:
-```json
-[
-  { "target": "deep-learning", "type": "CITES" },
-  { "target": "backpropagation", "type": "CITES" },
-  { "target": "gradient-descent", "type": "CITES" }
-]
-```
-
-**Example Request (All Relations)**:
-```json
-{
-  "name": "explore_links",
-  "arguments": {
-    "id": "neural-networks"
-  }
-}
-```
-
-**Notes**:
-- Without `relation` parameter, returns all outgoing edges
-- Only shows direct connections (1-hop traversal)
-- For multi-hop exploration, call recursively on target nodes
-- Empty array if node has no outgoing edges
-
-### 4. list_directory_structure
-
-**Purpose**: View the high-level organization of documents.
-
-**Parameters**: None
-
-**Example Request**:
-```json
-{
-  "name": "list_directory_structure",
-  "arguments": {}
-}
-```
-
-**Example Response**:
-```json
-[
-  "docs/",
-  "notes/"
-]
-```
-
-**Notes**:
-- Currently returns hardcoded structure
-- TODO: Make configurable via `amalfa.config.ts`
-- Useful for understanding document organization before search
-
-### 5. inject_tags
-
-**Purpose**: Add semantic tags to a markdown file programmatically.
-
-⚠️ **Experimental**: Modifies source files. Use with caution.
-
-**Parameters**:
-```json
-{
-  "file_path": "string (required)",
-  "tags": "array<string> (required)"
-}
-```
-
-**Example Request**:
-```json
-{
-  "name": "inject_tags",
-  "arguments": {
-    "file_path": "./docs/neural-networks.md",
-    "tags": ["DOMAIN: machine-learning", "COMPLEXITY: advanced"]
-  }
-}
-```
-
-**Example Response**:
-```json
-{
-  "text": "Injected 2 tags into ./docs/neural-networks.md"
-}
-```
-
-**What It Does**:
-Appends metadata block to end of file:
-```markdown
-<!-- tags: DOMAIN: machine-learning, COMPLEXITY: advanced -->
-```
-
-**Notes**:
-- **Modifies source files** - Changes persist on disk
-- Triggers file watcher (if daemon running) for re-ingestion
-- Tags follow metadata format: `<!-- tags: [KEY: value] -->`
-- Use for "Gardener Agent" workflows (automated knowledge curation)
-
-## Resources
-
-AMALFA also provides MCP resources:
-
-### amalfa://stats/summary
-
-Returns knowledge graph statistics (nodes, edges, embeddings, database size).
-
-## Integration Examples
-
-### Claude Desktop
-
-Configure in `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "amalfa": {
-      "command": "amalfa",
-      "args": ["serve"]
-    }
-  }
-}
-```
-
-### Example Conversation
-
-**User**: "What do I have about machine learning?"
-
-**Claude** (uses search_documents):
-```json
-{
-  "query": "machine learning",
-  "limit": 5
-}
-```
-
-**User**: "Show me the full content of neural-networks"
-
-**Claude** (uses read_node_content):
-```json
-{
-  "id": "neural-networks"
-}
-```
-
-**User**: "What documents link to this?"
-
-**Claude** (uses explore_links):
-```json
-{
-  "id": "neural-networks",
-  "relation": "CITES"
-}
-```
-
-## Error Handling
-
-All tools return errors in this format:
-
-```json
-{
-  "content": [
-    {
-      "type": "text",
-      "text": "Error: <error message>"
-    }
-  ],
-  "isError": true
-}
-```
-
-Common errors:
-- `Node not found` - ID doesn't exist in database
-- `File not found` - Source markdown file missing
-- `Search Error` - Vector search failed (embeddings missing)
-- `Tool <name> not found` - Invalid tool name
-
-## Performance
-
-- **search_documents**: ~10-50ms (depends on corpus size)
-- **read_node_content**: <5ms (filesystem read)
-- **explore_links**: <5ms (SQLite query)
-- **list_directory_structure**: <1ms (in-memory)
-- **inject_tags**: <10ms (file write)
-
-Database remains open during MCP session for optimal performance.
-
-## Limitations
-
-1. **Read-only by default**: Only `inject_tags` modifies files
-2. **No batch operations**: Each tool call processes single request
-3. **No pagination**: Large result sets return all at once (use `limit` parameter)
-4. **Synchronous only**: No streaming results
-
-## Future Tools (Roadmap)
-
-- `create_document` - Create new markdown files
-- `update_document` - Edit existing files
-- `delete_document` - Remove files and nodes
-- `graph_stats` - Detailed graph analytics
-- `find_path` - Multi-hop pathfinding between nodes
-- `cluster_analysis` - Community detection
-
-## Technical Details
-
-### Transport
-
-AMALFA uses **stdio transport** for MCP communication:
-- stdin: Receives JSON-RPC requests
-- stdout: Returns JSON-RPC responses
-- stderr: Logging (captured in `.mcp.log`)
-
-### Database Access
-
-Each tool call creates a fresh database connection:
-```typescript
-const db = new ResonanceDB(".amalfa/resonance.db");
-const vectorEngine = new VectorEngine(db.getRawDb());
-// ... use tools ...
-db.close(); // Cleanup after request
-```
-
-### Vector Search Algorithm
-
-1. Generate query embedding (384-dim vector)
-2. Normalize to unit length (L2 norm)
-3. Compute dot product with all document embeddings
-4. Sort by similarity score (descending)
-5. Return top-k results
-
-No vector database required - pure SQLite with BLOB storage.
-
----
-
-**For more information**:
-- [AMALFA GitHub](https://github.com/pjsvis/amalfa)
-- [Model Context Protocol Spec](https://modelcontextprotocol.io)
-- [FastEmbed Documentation](https://github.com/qdrant/fastembed)

package/schemas/README.md

@@ -1,20 +0,0 @@
-# Data Schemas
-
-This directory contains the canonical [JSON Schema](https://json-schema.org/) files that define the official data structures for the `polyvis` project.
-
-These schemas serve as the single source of truth for validating the project's core data artifacts.
-
-## Files
-
-- `cda.schema.json`: Defines the required structure for a Core Directive Array (CDA) file.
-- `conceptual-lexicon.schema.json`: Defines the required structure for a Conceptual Lexicon (CL) file.
-
-## Purpose
-
-1.  **Validation:** To programmatically ensure that any data file (either the private source files or public examples) conforms to the expected structure before it is processed by any build scripts.
-2.  **Documentation:** To act as precise, machine-readable documentation for the project's data models.
-3.  **Tooling Integration:** To enable editor features like autocompletion and real-time validation when editing the corresponding JSON data files.
-
-## Future Use
-
-These schemas are intended to be integrated into the `scripts/build_db.ts` process as a preliminary validation step. The build will fail if the source data files do not adhere to these structures, ensuring data integrity throughout the pipeline.

package/schemas/cda.schema.json

@@ -1,84 +0,0 @@
-{
-	"$schema": "http://json-schema.org/draft-07/schema#",
-	"title": "Core Directive Array (CDA) Schema",
-	"description": "Defines the structure for a Core Directive Array file, which contains sections of operational directives.",
-	"type": "object",
-	"properties": {
-		"cda_version": {
-			"description": "The version number of the CDA document.",
-			"type": "string"
-		},
-		"entry_count": {
-			"description": "The total number of individual directive entries.",
-			"type": "integer"
-		},
-		"title": {
-			"description": "The overall title of this Core Directive Array.",
-			"type": "string"
-		},
-		"purpose": {
-			"description": "A high-level statement explaining the purpose of this CDA.",
-			"type": "string"
-		},
-		"directives": {
-			"description": "An array of directive sections, which group related entries.",
-			"type": "array",
-			"items": {
-				"$ref": "#/definitions/directiveSection"
-			}
-		}
-	},
-	"required": ["cda_version", "title", "directives"],
-	"definitions": {
-		"directiveSection": {
-			"type": "object",
-			"title": "Directive Section",
-			"description": "A group of related directive entries under a common heading.",
-			"properties": {
-				"section": {
-					"description": "The name of the section (e.g., 'CIP: Core Identity & Persona').",
-					"type": "string"
-				},
-				"entries": {
-					"description": "An array of individual directive entries within this section.",
-					"type": "array",
-					"items": {
-						"$ref": "#/definitions/directiveEntry"
-					}
-				}
-			},
-			"required": ["section", "entries"]
-		},
-		"directiveEntry": {
-			"type": "object",
-			"title": "Directive Entry",
-			"description": "A single, atomic directive, concept, or principle.",
-			"properties": {
-				"id": {
-					"description": "The unique identifier for the entry (e.g., 'Concept-01', 'CIP-1').",
-					"type": "string"
-				},
-				"term": {
-					"description": "A concise term for the entry, often used for foundational concepts.",
-					"type": "string"
-				},
-				"title": {
-					"description": "A descriptive title for the entry, often used for directives.",
-					"type": "string"
-				},
-				"definition": {
-					"description": "The full definition or explanation of the directive.",
-					"type": ["string", "object"]
-				},
-				"tags": {
-					"description": "An optional array of tags for establishing relationships (e.g., '[Substrate_Issue: Biddability]').",
-					"type": "array",
-					"items": {
-						"type": "string"
-					}
-				}
-			},
-			"required": ["id", "definition"]
-		}
-	}
-}

package/schemas/conceptual-lexicon.schema.json

@@ -1,75 +0,0 @@
-{
-	"$schema": "http://json-schema.org/draft-07/schema#",
-	"title": "Conceptual Lexicon (CL) Schema",
-	"description": "Defines the structure for a Conceptual Lexicon file, which is an array of term and heuristic entries.",
-	"type": "array",
-	"items": {
-		"$ref": "#/definitions/lexiconEntry"
-	},
-	"definitions": {
-		"lexiconEntry": {
-			"type": "object",
-			"title": "Lexicon Entry",
-			"description": "A single entry (term or heuristic) in the Conceptual Lexicon.",
-			"properties": {
-				"id": {
-					"description": "The unique identifier for the entry (e.g., 'term-001', 'OH-040').",
-					"type": "string",
-					"pattern": "^[a-zA-Z0-9_-]+$"
-				},
-				"title": {
-					"description": "The human-readable title of the term or heuristic.",
-					"type": "string"
-				},
-				"description": {
-					"description": "The full definition of the entry. Can be a simple string or a structured object for complex definitions.",
-					"type": ["string", "object"]
-				},
-				"type": {
-					"description": "The type of the entry, e.g., 'term', 'operational-heuristic'.",
-					"type": "string"
-				},
-				"category": {
-					"description": "The category of the entry, e.g., 'Core Concept', 'Operational Heuristic'.",
-					"type": "string"
-				},
-				"tags": {
-					"description": "An optional array of tags for establishing relationships (e.g., '[Implements: COG-5]').",
-					"type": "array",
-					"items": {
-						"type": "string"
-					}
-				},
-				"source": {
-					"description": "The origin of the entry, typically 'cl'.",
-					"type": "string"
-				},
-				"external_refs": {
-					"description": "A list of external grounding resources (URLs, Citations, Code).",
-					"type": "array",
-					"items": {
-						"type": "object",
-						"properties": {
-							"label": {
-								"description": "Human-readable link text (e.g., 'Wikipedia', 'Source Code').",
-								"type": "string"
-							},
-							"url": {
-								"description": "The fully qualified URI.",
-								"type": "string",
-								"format": "uri"
-							},
-							"type": {
-								"description": "The nature of the reference.",
-								"type": "string",
-								"enum": ["source", "citation", "implementation", "example"]
-							}
-						},
-						"required": ["label", "url", "type"]
-					}
-				}
-			},
-			"required": ["id", "title", "description", "type"]
-		}
-	}
-}

package/scratchpads/dummy-debrief-boxed.md

@@ -1,39 +0,0 @@
-# Debrief: Project Alpha (Dummy)
-
-**Date:** 2025-12-12
-**Status:** Success
-
-
-<!-- bento-id: bento-f4290ac6 -->
-<!-- type: section -->
-## 1. Overview
-We successfully deployed the Alpha version. It was great.
-
-
-<!-- bento-id: bento-4dd57b85 -->
-<!-- type: section -->
-## 2. Technical Details
-We used a lot of code.
-
-### The Algorithm
-Here is the core loop:
-
-```typescript
-function coreLoop() {
-  console.log("Don't split me!");
-  // This is a comment inside code
-}
-```
-
-
-<!-- bento-id: bento-8cc779e9 -->
-<!-- type: section -->
-## 3. Lessons Learned
-- Don't eat yellow snow.
-- **Testing:** Is important.
-
-
-<!-- bento-id: bento-e4cea28f -->
-<!-- type: section -->
-## 4. Future Work
-We need to do more stuff.

package/scratchpads/dummy-debrief.md

@@ -1,27 +0,0 @@
-# Debrief: Project Alpha (Dummy)
-
-**Date:** 2025-12-12
-**Status:** Success
-
-## 1. Overview
-We successfully deployed the Alpha version. It was great.
-
-## 2. Technical Details
-We used a lot of code.
-
-### The Algorithm
-Here is the core loop:
-
-```typescript
-function coreLoop() {
-  console.log("Don't split me!");
-  // This is a comment inside code
-}
-```
-
-## 3. Lessons Learned
-- Don't eat yellow snow.
-- **Testing:** Is important.
-
-## 4. Future Work
-We need to do more stuff.

package/scratchpads/scratchpad-design.md

@@ -1,50 +0,0 @@
-# Design Scratchpad: AntiGravity Emulation
-
-**Goal**: Adopt the visual language of Google's AntiGravity agent.
-
-## 1. Core Philosophy
-- **High Contrast Dark Mode**: Deep backgrounds (`#202124` or darker), crisp white text (`#ffffff`), and subtle borders.
-- **Typography**: Clean, geometric sans-serif (Google Sans / Inter).
-- **Fluidity**: Responsive sizing for typography and spacing.
-- **"The Card"**: Distinct surfaces with subtle borders and rounded corners.
-
-## 2. Color Palette (Dark Mode)
-
-| Semantic Name | Value | Description |
-| :--- | :--- | :--- |
-| `--primary` | `#202124` | Main Background (Deep Gray) |
-| `--secondary` | `#ffffff` | Primary Text (Crisp White) |
-| `--accent` | `#303134` | Secondary Background / Sidebar |
-| `--surface-1` | `#202124` | App Background |
-| `--surface-2` | `#303134` | Card / Panel Background |
-| `--surface-hover` | `#3c4043` | Hover State |
-| `--border-base` | `#5f6368` | Subtle Borders |
-| `--link` | `#8ab4f8` | Google Blue (Links) |
-| `--link-visited` | `#c58af9` | Google Violet (Visited) |
-
-## 3. Typography
-
-- **Font Family**: `Inter, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif`
-- **Scale**:
-    - `xs`: `0.75rem`
-    - `sm`: `0.875rem`
-    - `base`: `1rem`
-    - `lg`: `1.125rem`
-    - `xl`: `1.25rem`
-    - `2xl`: `1.5rem`
-
-## 4. Spacing (Fluid)
-
-Using Open Props `size-fluid-*` where appropriate, but anchoring on a 4px grid.
-
-- `--spacing-1`: `4px`
-- `--spacing-2`: `8px`
-- `--spacing-3`: `12px`
-- `--spacing-4`: `16px` (Standard Gap)
-- `--spacing-5`: `20px`
-- `--spacing-6`: `24px`
-
-## 5. Implementation Strategy
-1.  **Update `theme.css`**: Replace existing color variables with the new palette.
-2.  **Refine Typography**: Ensure `Inter` is loaded or falls back gracefully.
-3.  **Component Audit**: Check Sidebars, Cards, and TOC for contrast issues.

package/scratchpads/scratchpad-scrolling.md

@@ -1,20 +0,0 @@
-# Scratchpad: Sidebar Scrolling Experiments
-
-## Problem Space
-The sidebars in `v3.html` are not scrolling.
-Structure: `aside` (Grid Cell) -> `div` (Container) -> `nav` (List).
-Current State: Both `aside` and `nav` might have overflow properties, or `nav` is not constrained.
-
-## Hypothesis 1: Nested Scroll Conflict
-If `aside` allows scrolling, the inner `div` grows to fit the content.
-If `div` grows, `nav` grows.
-Result: `nav` never overflows its container, so its scrollbar never triggers. The `aside` scrollbar *should* trigger, but might be hidden or behaving oddly due to `app-shell` grid constraints.
-
-## Experiment 1: Lock Parent, Scroll Child
-**Goal**: Make `nav` the *only* scrollable element.
-1.  `aside`: `overflow: hidden` (Don't scroll).
-2.  `div.docs-directory`: `h-full flex flex-col overflow: hidden` (Constrain height, don't scroll).
-3.  `nav`: `flex-1 overflow-y-auto min-h-0` (Fill space, scroll if needed, allow shrinking).
-
-## Log
--   [ ] Experiment 1