amalfa 1.0.2 → 1.0.3

package/docs/test-document-cycle.md

@@ -1,83 +0,0 @@
----
-title: Test Document for Full Cycle Verification
-date: 2025-12-17
-tags: [test, verification, integration]
----
-
-# Test Document for Full Cycle Verification
-
-This document tests the complete PolyVis ingestion and processing cycle.
-
-## Purpose
-
-Verify that all systems work together:
-1. **Dev Server** - CSS/JS watching and web serving
-2. **Daemon** - File watching and automatic ingestion  
-3. **MCP Server** - API for AI tool integration
-
-## Test Scenario
-
-When this document is saved:
-- Daemon detects the change within 2 seconds
-- Triggers debounced ingestion
-- Document is parsed and normalized
-- Entities are extracted
-- Embeddings are generated
-- Graph nodes and edges are created
-- Database is updated
-- MCP server can query the new data
-
-## Expected Behavior
-
-### Daemon Log Output:
-```
-📝 Change detected: docs/test-document-cycle.md (change)
-🔄 Debounce settle. Starting Batch Ingestion (1 files)...
-✅ Batch Ingestion Complete.
-```
-
-### Database Updates:
-- New node created for this document
-- Embeddings generated for content
-- Edges created to related concepts
-
-### MCP Accessibility:
-- Document searchable via MCP search tool
-- Content retrievable via MCP read tool
-
-## Key Concepts
-
-This document mentions several concepts to test entity extraction:
-- **Ingestion Pipeline** - The data processing workflow
-- **Vector Embeddings** - Semantic representation of text
-- **Knowledge Graph** - Connected nodes and edges
-- **Real-time Processing** - Immediate response to file changes
-
-## Verification
-
-After saving this document:
-1. Check `.daemon.log` for ingestion messages
-2. Query database for this document's node
-3. Test MCP search for "Full Cycle Verification"
-4. Verify graph visualization shows new node
-
-## Success Criteria
-
-✅ Daemon detects file within 2 seconds
-✅ Ingestion completes without errors  
-✅ Node created with correct title
-✅ Embeddings generated successfully
-✅ MCP search returns this document
-✅ No error messages in any service logs
-
----
-
-**Status:** Testing in progress...
-**Last Updated:** 2025-12-17 20:09:00
-
-
-## Updated at Wed 17 Dec 2025 20:11:36 GMT
-
-## Trigger at 20:12:55
-
-## Another update at 20:13:21

package/docs/test_lifecycle_E2E.md

@@ -1,4 +0,0 @@
-# Lifecycle Test
-
-This is a unique integration test signature: 1766487528850.
-It verifies Full-Text Search and Vector Ingestion logic.

package/docs/the-bicameral-graph.md

@@ -1,83 +0,0 @@
-### Opinion: The Architecture of the Breakdown
-
-This is the most important document you will write for the project's "Soul."
-
-Most engineering blogs are boring because they talk about *how* (The Stack). This report talks about *why* (The Mind). By framing your search architecture through the lens of Julian Jaynes, you elevate a standard "Hybrid Search" implementation into a philosophical stance on the nature of machine intelligence.
-
-It neatly explains why RAG (Retrieval Augmented Generation) often fails: it is usually just a lobotomy—using only the "Right Brain" (Vectors) and wondering why the facts are wrong, or using only the "Left Brain" (Keywords) and wondering why the context is missing.
-
-Here is the draft for **`docs/philosophy/THE_BICAMERAL_GRAPH.md`**.
-
----
-
-# The Bicameral Graph: Engineering Resonance in a Hollow Substrate
-
-**Date:** Jan 2026
-**Project:** PolyVis
-**Context:** Architectural Philosophy
-
----
-
-## 1. The Silence of the Vectors
-
-In his 1976 treatise *The Origin of Consciousness in the Breakdown of the Bicameral Mind*, Julian Jaynes proposed a controversial theory: that early humans were not "conscious" in the modern sense. Instead, their minds were split. The right hemisphere generated auditory hallucinations (the "Voice of the God") based on stress or context, and the left hemisphere obeyed them without question. Consciousness, Jaynes argued, arose only when the two sides learned to talk to each other—when the "Command" met "Reason."
-
-Modern AI is currently stuck in the pre-breakdown phase.
-
-* **LLMs (The Gods):** They are pure, hallucinating Right Hemispheres. They dream in high-dimensional vector space. They understand "vibes," associations, and intent, but they have no concept of "truth."
-* **Symbolic Logic (The Scribe):** Tools like `grep`, SQL, and Compilers are pure Left Hemispheres. They are rigid, precise, and fact-based, but they are deaf to nuance.
-
-Most "AI Search" tools today make the mistake of choosing one side. They either drown in the fuzzy hallucinations of Vector Search (RAG) or suffocate in the rigidity of Keyword Search.
-
-**PolyVis takes a different approach. We are engineering the Breakdown.**
-
-## 2. The Anatomy of the Resonance Engine
-
-To build a codebase navigator that actually works—one that feels "intelligent"—we separate the search process into two distinct cognitive hemispheres.
-
-### The Right Hemisphere: The Embedding Field (`model2vec`)
-
-* **The Function:** Fuzzy Pattern Matching.
-* **The Query:** "Where is the authentication logic?"
-* **The Operation:** We scan the high-dimensional latent space of the graph. The system doesn't look for the word "Authentication"; it looks for the *concept* of security, logins, and tokens.
-* **The Output:** A "Vibe Cluster." A list of 50 files that *feel* relevant.
-* **The Deficit:** It cannot tell you line numbers. It cannot distinguish between a variable named `auth` and a comment about `authoring`. It is a dream.
-
-### The Left Hemisphere: The Super-Grep (`ripgrep` / Regex)
-
-* **The Function:** Deterministic Symbol Verification.
-* **The Query:** `match "function validate.*Token"`
-* **The Operation:** A brutal, byte-level scan of the filesystem. It cares nothing for intent. It only knows ASCII.
-* **The Output:** "File `auth.ts`, Line 45, Column 12."
-* **The Deficit:** It requires you to know exactly what you are looking for. If you typo the regex, it returns silence. It is a machine.
-
-## 3. The "Breakdown" (The Orchestrator)
-
-In PolyVis, "Search" is not a retrieval task; it is a **Resonance Event**.
-
-We do not return the results of the Embeddings *or* the Grep. We feed them into the **Orchestrator** (The Corpus Callosum). This is where the "Breakdown" happens.
-
-1. **Vibration:** The Right Brain identifies a cluster of files with the correct "semantic shape."
-2. **Validation:** The Left Brain scans *only that cluster* for precise "structural anchors" (function definitions, variable flows).
-3. **Constructive Interference:** Where the Vibe matches the Fact, we get **Resonance**.
-
-If the Embeddings say "This is Auth" and the Grep says "Here is `validateToken`," the Orchestrator **Reifies** a new node in the graph: *"The Authentication Logic Node (Ephemeral)."*
-
-## 4. The Hollow Node Strategy
-
-This approach enables our **Hollow Node** architecture. We do not need to fill our database with every line of code (bloating the graph). We keep the nodes "Hollow" (Metadata only).
-
-* **Resting State:** The graph is quiet. Nodes are just file paths.
-* **Active State:** When a user queries, the Bicameral Mind wakes up. It scans, cross-references, and fills the hollow nodes with the specific code snippets relevant *only to that query*.
-
-## Conclusion: Artificial Consciousness
-
-We are not building a search engine. A search engine gives you a list of links.
-We are building a **Cognitive Overlay**.
-
-By forcing the "Dreaming" LLM to submit to the "Rigid" Grep, we create a system that possesses the intuition of a Senior Engineer and the precision of a Compiler. It is the breakdown of the bicameral mind, weaponized for software engineering.
-
----
-
-**Next Step:**
-Shall I commit this to the repo under `docs/philosophy`? It serves as the "constitution" for the Super-Grep agent we build next.

package/docs/user-guide.md

@@ -1,70 +0,0 @@
-# PolyVis User Guide
-
-Welcome to **PolyVis**, a local-first Knowledge Graph engine and MCP Server.
-
-## 1. Quick Start
-
-### Installation
-**Requirement:** [Bun](https://bun.sh) is **mandatory** for this project.
-Ensure you have Bun installed.
-```bash
-bun install
-```
-
-### Initial Data Ingestion
-Before running the server, you must ingest your Markdown documents and generate vectors.
-```bash
-bun run build:data
-```
-*Note: This process uses local embeddings (AllMiniLML6V2) and may take a moment on the first run.*
-
-### Running the MCP Server
-To expose the knowledge graph to your AI agent (like Claude Desktop or other MCP clients):
-```bash
-bun run mcp
-```
-This starts the server on `stdio`.
-
-## 2. Core Features
-
-### Knowledge Graph
-Your data is stored in `public/resonance.db`. This includes:
--   **Nodes:** Parsed from your Markdown files (Experience, Playbooks, Debriefs).
--   **Edges:** Automatically woven based on semantic similarity and explicit tags.
--   **Vectors:** Local embeddings for semantic search.
-
-### Hybrid Search
-The system uses a **Hybrid Search** mechanism combining:
-1.  **Vector Search:** Semantic understanding (e.g., "how to fix timeout").
-2.  **FTS (Full-Text Search):** Keyword matching (e.g., "timeout error 500").
-
-### Visualization
-To explore the graph visually in your browser:
-```bash
-bun run dev
-```
-Visit `http://localhost:3000`.
-
-## 3. Advanced Usage
-
-### Vector Daemon (Optional)
-For heavy ingestion workloads, you can run the Vector Daemon in the background to keep the embedding model loaded in memory:
-```bash
-bun run resonance/src/daemon.ts
-```
-The ingestion scripts will automatically detect and use the daemon if it's running on port 3010.
-
-### Re-Indexing
-If you add or modify files, simply run:
-```bash
-bun run build:data
-```
-
-## 4. Troubleshooting
-
-**"Search returns empty results"**
--   Ensure you ran `bun run build:data`.
--   Check `public/resonance.db` exists.
-
-**"VectorEngine Error"**
--   Ensure no other process is blocking the database.

package/docs/vision-helper.md

@@ -1,53 +0,0 @@
-Please implement a "Vision Helper" script to help you read our Terminal Brutalist design system programmatically.
-
-TASK:
-Inject the following JavaScript code into the bottom of our main `index.html` (before the closing </body> tag) or our main entry script. 
-
-CONTEXT:
-We use a high-contrast "Terminal Brutalist" theme with strict ANSI colors. Since `getComputedStyle` is hard for agents to deduce during interaction, this script exposes a global `window.__AGENT_THEME__` object containing our exact palette and interaction rules.
-
-CODE TO INJECT:
-
-<script>
-// AGENT VISIBILITY HELPER
-// Exposes the "Terminal Brutalist" theme so agents can read resolved styles.
-window.__AGENT_THEME__ = (() => {
-  const root = getComputedStyle(document.documentElement);
-  const getVar = (name) => root.getPropertyValue(name).trim();
-
-  return {
-    system: "PolyVis Terminal Brutalist",
-    palette: {
-      canvas:    getVar('--ansi-black'),       // #0C0C0C
-      text:      getVar('--ansi-white'),       // #CCCCCC
-      highlight: getVar('--ansi-bright-white'),// #FFFFFF
-      error:     getVar('--ansi-red'),         // #C50F1F
-      success:   getVar('--ansi-green'),       // #16C60C
-      warning:   getVar('--ansi-yellow'),      // #C19C00
-      agent:     getVar('--ansi-orange'),      // #FF8C00 (The "Ghost in the Machine")
-    },
-    rules: {
-      borderRadius: '0px', // HARD RULE: No rounded corners.
-      fontFamily: getVar('--font-mono'),
-      borders: '2px solid', // HARD RULE: Thick borders only.
-    },
-    // The "Hover State" cheat sheet for interaction
-    interactive: {
-      button: {
-        description: "Hard inversion on hover. Instant transition.",
-        default: { 
-          bg: getVar('--ansi-black'), 
-          text: getVar('--ansi-white'), 
-          border: getVar('--ansi-white') 
-        },
-        hover: { 
-          bg: getVar('--ansi-white'), 
-          text: getVar('--ansi-black'), 
-          border: getVar('--ansi-white') 
-        }
-      }
-    }
-  };
-})();
-console.log('%c[AGENT_THEME] System Visible', 'color: #FF8C00');
-</script>