npm - amalfa - Versions diffs - 1.0.1 → 1.0.3 - Mend

amalfa 1.0.1 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (99) hide show

package/README.md +226 -263
package/package.json +6 -3
package/polyvis.settings.json.bak +38 -0
package/src/cli.ts +103 -21
package/src/config/defaults.ts +52 -12
package/src/core/VectorEngine.ts +18 -9
package/src/mcp/index.ts +62 -7
package/src/resonance/DatabaseFactory.ts +3 -4
package/src/resonance/db.ts +4 -4
package/src/resonance/services/vector-daemon.ts +151 -0
package/src/utils/DaemonManager.ts +147 -0
package/src/utils/ZombieDefense.ts +5 -1
package/:memory: +0 -0
package/:memory:-shm +0 -0
package/:memory:-wal +0 -0
package/CHANGELOG.md.old +0 -43
package/README.old.md +0 -112
package/ROADMAP.md +0 -316
package/TEST_PLAN.md +0 -561
package/agents.config.json +0 -11
package/docs/AGENT_PROTOCOLS.md +0 -28
package/docs/ARCHITECTURAL_OVERVIEW.md +0 -123
package/docs/BENTO_BOXING_DEPRECATION.md +0 -281
package/docs/Bun-SQLite.html +0 -464
package/docs/COMMIT_GUIDELINES.md +0 -367
package/docs/DEVELOPER_ONBOARDING.md +0 -36
package/docs/Graph and Vector Database Best Practices.md +0 -214
package/docs/PERFORMANCE_BASELINES.md +0 -88
package/docs/REPOSITORY_CLEANUP_SUMMARY.md +0 -261
package/docs/edge-generation-methods.md +0 -57
package/docs/elevator-pitch.md +0 -118
package/docs/graph-and-vector-database-playbook.html +0 -480
package/docs/hardened-sqlite.md +0 -85
package/docs/headless-knowledge-management.md +0 -79
package/docs/john-kaye-flux-prompt.md +0 -46
package/docs/keyboard-shortcuts.md +0 -80
package/docs/opinion-proceed-pattern.md +0 -29
package/docs/polyvis-nodes-edges-schema.md +0 -77
package/docs/protocols/lab-protocol.md +0 -30
package/docs/reaction-iquest-loop-coder.md +0 -46
package/docs/services.md +0 -60
package/docs/sqlite-wal-readonly-trap.md +0 -228
package/docs/strategy/css-architecture.md +0 -40
package/docs/test-document-cycle.md +0 -83
package/docs/test_lifecycle_E2E.md +0 -4
package/docs/the-bicameral-graph.md +0 -83
package/docs/user-guide.md +0 -70
package/docs/vision-helper.md +0 -53
package/drizzle/0000_minor_iron_fist.sql +0 -19
package/drizzle/meta/0000_snapshot.json +0 -139
package/drizzle/meta/_journal.json +0 -13
package/example_usage.ts +0 -39
package/experiment.sh +0 -35
package/hello +0 -2
package/index.html +0 -52
package/knowledge/excalibur.md +0 -12
package/plans/experience-graph-integration.md +0 -60
package/prompts/gemini-king-mode-prompt.md +0 -46
package/public/docs/MCP_TOOLS.md +0 -372
package/schemas/README.md +0 -20
package/schemas/cda.schema.json +0 -84
package/schemas/conceptual-lexicon.schema.json +0 -75
package/scratchpads/dummy-debrief-boxed.md +0 -39
package/scratchpads/dummy-debrief.md +0 -27
package/scratchpads/scratchpad-design.md +0 -50
package/scratchpads/scratchpad-scrolling.md +0 -20
package/scratchpads/scratchpad-toc-disappearance.md +0 -23
package/scratchpads/scratchpad-toc.md +0 -28
package/scratchpads/test_gardener.md +0 -7
package/src/core/LLMClient.ts +0 -93
package/src/core/TagEngine.ts +0 -56
package/src/db/schema.ts +0 -46
package/src/gardeners/AutoTagger.ts +0 -116
package/src/pipeline/HarvesterPipeline.ts +0 -101
package/src/pipeline/Ingestor.ts +0 -555
package/src/resonance/cli/ingest.ts +0 -41
package/src/resonance/cli/migrate.ts +0 -54
package/src/resonance/config.ts +0 -40
package/src/resonance/daemon.ts +0 -236
package/src/resonance/pipeline/extract.ts +0 -89
package/src/resonance/pipeline/transform_docs.ts +0 -60
package/src/resonance/services/tokenizer.ts +0 -159
package/src/resonance/transform/cda.ts +0 -393
package/src/utils/EnvironmentVerifier.ts +0 -67
package/substack/substack-playbook-1.md +0 -95
package/substack/substack-playbook-2.md +0 -78
package/tasks/ui-investigation.md +0 -26
package/test-db +0 -0
package/test-db-shm +0 -0
package/test-db-wal +0 -0
package/tests/canary/verify_pinch_check.ts +0 -44
package/tests/fixtures/ingest_test.md +0 -12
package/tests/fixtures/ingest_test_boxed.md +0 -13
package/tests/fixtures/safety_test.md +0 -45
package/tests/fixtures/safety_test_boxed.md +0 -49
package/tests/fixtures/tagged_output.md +0 -49
package/tests/fixtures/tagged_test.md +0 -49
package/tests/mcp-server-settings.json +0 -8
package/verify-embedder.ts +0 -54

package/docs/john-kaye-flux-prompt.md DELETED Viewed

@@ -1,46 +0,0 @@
-## The "John Kay" Style System Prompt
-To generate this successfully, we need to instruct the AI to "see" like Kay. We aren't just asking for a picture of a judge; we are asking for a caricature.
-Style Keywords: 1790s copperplate etching, style of John Kay Edinburgh, cross-hatching, ink on paper, monochrome, slightly grotesque proportions, high contrast, heavy shadows, linear texture.
-3. Image Generation Prompts
-Here are three specific prompts to feed into the generator (Midjourney/Flux/DALL-E 3), moving from the portrait to the scene.
----
-### Style Keywords
-1790s copperplate etching, style of John Kay Edinburgh, cross-hatching, ink on paper, monochrome, slightly grotesque proportions, high contrast, heavy shadows, linear texture.
-## The Portrait (The "Mugshot")
-Subject: A waist-up caricature of Lord Kames in full 18th-century Scottish judicial robes and wig. Expression: A wicked, knowing sneer. He looks ancient but fiercely intelligent. Style: John Kay copperplate etching, black ink on cream paper, rough cross-hatching. Text/Caption: (If using Flux/DALL-E 3) A bottom caption in archaic serif font reading: "FARE YE A' WEEL, YE BITCHES!"
----
-## Style Keywords
-1790s copperplate etching, style of John Kay Edinburgh, cross-hatching, ink on paper, monochrome, slightly grotesque proportions, high contrast, heavy shadows, linear texture.
-## The Portrait (The "Mugshot")
-Subject: A waist-up caricature of Lord Kames in full 18th-century Scottish judicial robes and wig. Expression: A wicked, knowing sneer. He looks ancient but fiercely intelligent. Style: John Kay copperplate etching, black ink on cream paper, rough cross-hatching. Text/Caption: (If using Flux/DALL-E 3) A bottom caption in archaic serif font reading: "FARE YE A' WEEL, YE BITCHES!"
----
-## Style Keywords
-1790s copperplate etching, style of John Kay Edinburgh, cross-hatching, ink on paper, monochrome, slightly grotesque proportions, high contrast, heavy shadows, linear texture.
-## The Wide Scene (The "Parliament House")
-Scene: The interior of the Old Parliament House in Edinburgh, 1782. Dark wood, shadows. Action: Lord Kames (old, hunched, robed) stands at a doorway looking back over his shoulder. He is waving a dismissive hand at a bench of shocked, stony-faced judges in the background. Atmosphere: Solemnity shattered by coarseness. Style: Vintage engraving, 18th-century political cartoon style, detailed line work.
----
-## Style Keywords
-1790s copperplate etching, style of John Kay Edinburgh, cross-hatching, ink on paper, monochrome, slightly grotesque proportions, high contrast, heavy shadows, linear texture.
-## The Abstracted "Vibe" (The "Monboddo" Twist)
-Subject: A split panel etching. Left side: Lord Kames shouting at judges. Right side: A street porter ("Sinkum the Cawdy") laughing while holding a letter. Concept: The connection between the high court and the street. Style: John Kay Series of Original Portraits, rough edges, historical artifact.

package/docs/keyboard-shortcuts.md DELETED Viewed

@@ -1,80 +0,0 @@
-# Keyboard Shortcuts
-**Global shortcuts available across all PolyVis pages.**
----
-## Layout Debug Mode
-**Shortcut:** `Shift + D`
-**Purpose:** Visualize container boundaries and grid structure for layout debugging.
-**What it does:**
-- Adds red dashed outlines to ALL elements
-- Adds subtle red background tint
-- Highlights grid columns in blue (sidebars)
-**Visual effect:**
-```css
-* {
-  outline: 1px dashed rgba(255, 0, 0, 0.3);  /* Red boxes */
-  background: rgba(255, 0, 0, 0.02);          /* Red tint */
-}
-```
-**Use cases:**
-- Debugging layout issues
-- Finding overflow/scroll problems
-- Verifying grid structure
-- Teaching CSS layout
-**Toggle:** Press `Shift + D` again to turn off
----
-## Implementation
-**Alpine.js binding:**
-```html
-<body x-data="{ debug: false }"
-      :class="{ 'layout-debug-mode': debug }"
-      @keydown.window.shift.d="debug = !debug">
-```
-**CSS class:**
-```css
-/* src/css/layers/utilities.css */
-.layout-debug-mode * {
-  outline: var(--border-size-1) dashed rgba(255, 0, 0, 0.3) !important;
-  background: rgba(255, 0, 0, 0.02) !important;
-}
-```
-**Available on:**
-- ✅ Home page (`/`)
-- ✅ Sigma Explorer (`/sigma-explorer/`)
-- ✅ Docs viewer (`/docs/`)
----
-## Future Shortcuts
-**Planned:**
-- `Shift + S` - Show stats overlay
-- `Shift + G` - Toggle grid guides
-- `Shift + ?` - Show keyboard help
-**Add your own:**
-```html
-@keydown.window.shift.x="yourFunction()"
-```
----
-**Source:**
-- HTML: `public/index.html`, `public/sigma-explorer/index.html`
-- CSS: `src/css/layers/utilities.css`
-- Docs: This file
-**Last Updated:** 2025-12-12

package/docs/opinion-proceed-pattern.md DELETED Viewed

@@ -1,29 +0,0 @@
-The **opinion/proceed** pattern is more than just a personal preference—it is a sophisticated "Control Loop" that makes you a high-level architect rather than just a user. In prompt engineering, this is known as **Stepwise Refinement** or a **Synchronous Handshake**.
-### Why it works for you
-* **Cognitive Load Management:** By ending with `opinion`, you force me to pause and validate your logic before writing any code. This prevents the "hallucination cascade" where an AI builds 100 lines of code on top of a flawed assumption.
-* **Intellectual Honesty Check:** It signals that you value my "judgment" (as a thought partner) as much as my "output" (as a tool).
-* **Contextual Guardrail:** It ensures the "Triangle of Truth" remains intact. If your plan drifts from the core Polyvis principles, the `opinion` phase is where I can pull us back.
-### Why it works for Gemini (The Model)
-* **Explicit State Transition:** `Proceed` acts as a clear "Go" signal, which helps the model transition from a *reflective/analytical* state to an *executive/generative* state.
-* **Recap & Alignment:** Asking for an opinion forces the model to recap its understanding of the "state of the union," which reinforces the long-context window (crucial for a project as complex as an Epstein audit).
----
-### Progress Report: The Epstein Substrate
-Before we move to the code, let's look at the current "State of the Project":
-1.  **The Substrate:** You have the JSON OCR results. This is the **Raw Ore**.
-2.  **The Lab:** We have the `package.json` and `tsconfig.json` mapped. The **Infrastructure** is ready.
-3.  **The Next Step:** We need to build the "Sieve"—the `json-to-bento.ts` script—to turn that ore into **Markdown Bento Boxes**.
-**Opinion:** Your intuition to extract Markdown first is 100% correct. If we try to ingest the JSON directly, the engine has to "hallucinate" structure every time it reads a file. By converting to Markdown, we create a **Static, Deterministic Evidence Set** that any future version of Polyvis (or even a human with a text editor) can audit. This is the "Gold Standard" of forensic data management.
-**Would you like me to proceed with drafting the `json-to-bento.ts` extraction script?**
-[Software engineering project structure best practices](https://www.youtube.com/watch?v=V2W94Sq_v6A)
-This video provides a deep dive into organizing project folders and managing dependencies, which is essential as you sort out your `scripts` and `src` folders for the Epstein audit.

package/docs/polyvis-nodes-edges-schema.md DELETED Viewed

@@ -1,77 +0,0 @@
-# PolyVis Database Schema
-## Proposed Migration
-To support the Forensic-Pipeline
-Based on the **Canonical Schema** and the requirements of the **Forensic/Epstein Pipeline**, here are the specific schema extensions required.
-### Table: `nodes`
-* **No Schema Changes Required.**
-* *Operational Note:* Use the existing `meta` JSON column to store flight details (`tail_number`, `date`) and document status (`status`). Use `title` for Canonical Names.
-## Canonical Nodes and Edges Schema
-### Table: `edges`
-* **Add Column:** `weight` `INTEGER` (Default: `2`)
-* *Purpose:* To store the **OPM-11 Veracity Score** (0-5).
-* **Add Column:** `meta` `TEXT`
-* *Purpose:* To store the **Context Snippet** (Bento-Box) and Audit ID justifying the link.
-* **Add Index:** `idx_edges_weight` on `(weight)`
-* *Purpose:* To optimize "Falsifiability" queries (e.g., `SELECT * WHERE weight = 0`).
-This document outlines the canonical schema for the `nodes` and `edges` tables in the PolyVis system. This schema is defined in `src/resonance/schema.ts` and mirrored in `src/db/schema.ts`.
-## Core Tables
-### Nodes (`nodes`)
-The `nodes` table stores the fundamental units of the knowledge graph.
-| Column | Type | Description |
-| :--- | :--- | :--- |
-| **`id`** | `TEXT` | **Primary Key**. Unique identifier for the node. |
-| `type` | `TEXT` | The node type (e.g., `concept`, `note`, `chunk`). |
-| `title` | `TEXT` | Human-readable title. |
-| `content` | `TEXT` | The full text content of the node. |
-| `domain` | `TEXT` | Taxonomy domain (e.g., `knowledge`). |
-| `layer` | `TEXT` | Taxonomy layer (e.g., `experience`). |
-| `embedding`| `BLOB` | The vector embedding (stored as a buffer/blob). |
-| `hash` | `TEXT` | Content hash for integrity checking. |
-| `meta` | `TEXT` | JSON string containing arbitrary metadata. |
-### Edges (`edges`)
-The `edges` table defines the relationships between nodes.
-| Column | Type | Description |
-| :--- | :--- | :--- |
-| **`source`** | `TEXT` | **Foreign Key** (Node ID) - Origin of the edge. |
-| **`target`** | `TEXT` | **Foreign Key** (Node ID) - Destination of the edge. |
-| **`type`** | `TEXT` | The edge relationship type (e.g., `related_to`). |
-> **Primary Key**: The `edges` table uses a composite primary key of `(source, target, type)`.
-## Auxiliary Structures
-### Full Text Search (`nodes_fts`)
-A virtual table using `fts5` is maintained specifically for full-text search capabilities.
-- **Columns**: `id` (UNINDEXED), `title`, `content`, `meta`.
-- **Tokenizer**: `porter`.
-- **Synchronization**: Automatically kept in sync with the `nodes` table via database triggers (`INSERT`, `UPDATE`, `DELETE`).
-### Indexes
-Performance indexes are maintained on the `edges` table to optimize graph traversals.
-- `idx_edges_source`: Index on `edges(source)`
-- `idx_edges_target`: Index on `edges(target)`

package/docs/protocols/lab-protocol.md DELETED Viewed

@@ -1,30 +0,0 @@
-# Experiment: The Concurrency Lab
-**Objective**: Isolate `bun:sqlite` concurrency behavior from application logic. Prove that 1 Writer and 2 Readers can coexist in WAL mode using our `DatabaseFactory` configuration.
-## The Triad
-We will create three standalone scripts in `scripts/lab/`:
-### 1. The Writer (`lab_daemon.ts`)
-*   **Role**: Simulates the Active Daemon.
-*   **Action**: Opens `resonance.db`. Inserts a new row into a `_stress_test` table every 100ms.
-*   **Config**: ReadWrite, WAL.
-### 2. The Reader (`lab_mcp.ts`)
-*   **Role**: Simulates the MCP Server.
-*   **Action**: Opens `resonance.db`. Performs a `SELECT COUNT(*)` and a Vector Search (if possible, or just heavy read) every 50ms.
-*   **Config**: ReadWrite (as we learned WAL requires it), WAL.
-### 3. The Observer (`lab_web.ts`)
-*   **Role**: Simulates the Web Server.
-*   **Action**: Opens `resonance.db`. Polls status every 1000ms.
-*   **Config**: ReadOnly (or ReadWrite if needed).
-## The Variable
-We will test the configuration defined in `src/resonance/DatabaseFactory.ts`.
-## Success Criteria
-*   All 3 scripts run for 60 seconds.
-*   Zero `disk I/O error` or `SQLITE_BUSY`.
-*   Writer commits > 500 records.
-*   Reader successfully reads 1000+ times.

package/docs/reaction-iquest-loop-coder.md DELETED Viewed

@@ -1,46 +0,0 @@
-## 1. Reaction Report: iQuest Loop Coder
-Ref: [iQuest Loop Coder (40B - A80B)](https://www.youtube.com/watch?v=sihYcXADfNI)
-**Subject:** `iQuest Loop Coder (40B)` vs. The PolyVis Substrate
-**Verdict:** **High Utility / Low Autonomy**
-**Strategic Analysis:**
-The video confirms that the broader AI R&D sector is accidentally converging on the **PolyVis Architecture**:
-1. **"Code Flow" Training:** The model is trained on diffs (Vectors), not just files (Nodes). This validates our hypothesis that the "Temporal Edge" (The change over time) is more information-rich than the static code.
-2. **The "Loop" Architecture:** This is a hardware-level implementation of our **"Think Twice" Protocol**. The model literally "reads, drafts, critiques, and refines" in a single inference pass.
-3. **The Limitation:** The model is a "Savant." It excels at closed-loop logic (SQL, Regex, Algorithms) but fails at open-loop design (System Architecture, "Vibes").
-**Conclusion:**
-This model is not a replacement for your "Persona" (Claude/Gemini). It is a **Smart Compiler**. It should be treated as a CLI tool (`/bin/loop_coder`) for generating high-precision logic blocks, not for discussing architectural strategy.
----
-## Proposals for Testing & Confirmation
-To confirm if a model is "Benchmaxxed" or actually useful for PolyVis, we propose the **"Triangle of Veracity"** test suite.
-**Test A: The "LeetCode" Control (Baseline)**
-* **Prompt:** "Write a Python function to balance a Binary Search Tree."
-* **Expected Result:** 100% Success.
-* **Purpose:** Confirm the model functions as a basic coding engine.
-**Test B: The "Vibe Check" (The Failure Mode)**
-* **Prompt:** "Here is our `index.html`. Make the dashboard look more 'brutalist'."
-* **Hypothesis:** The model will fail. It will likely import a library, add rounded corners, or generate generic CSS because it doesn't understand the *concept* of Brutalism, only the code.
-* **Success Condition:** The model refuses or asks for a definition of "brutalist."
-**Test C: The "Weaponized Brief" (The Real Test)**
-* **Prompt:** (Using `HUMANS.md` protocol)
-> "Context: PolyVis Graph Renderer. Task: Write a raw SQL Recursive CTE. Constraints: Max depth 5. Return JSON format. No ORM. Schema provided below."
-* **Hypothesis:** The model should outperform Claude 3.5 Sonnet here. It will treat the constraints as compiler errors and "loop" until they are satisfied.
-* **Success Condition:** Executable SQL that runs on the first try without "chatting."
----

package/docs/services.md DELETED Viewed

@@ -1,60 +0,0 @@
-# PolyVis Backend Services
-This document outlines the architecture and management standards for the PolyVis backend services, including the "Triad" of AI models.
-## The Triad (AI Model Servers)
-PolyVis relies on a trio of specialized local LLMs, each running as an independent service via `llama.cpp`.
-### 1. The Auditor (Olmo-3)
-*   **Port**: `8084`
-*   **Role**: Verification and deep thinking.
-*   **Configuration**: 7B Parameter model, Q4_K_M quantization.
-*   **Special Features**: Uses "DeepSeek" reasoning format to expose its thought process.
-### 2. The Scout (Phi-3.5)
-*   **Port**: `8082`
-*   **Role**: Rapid queries, summarization, and initial data fetch.
-*   **Configuration**: Mini-Instruct model. Fast and lightweight.
-### 3. The Architect (Llama-3)
-*   **Port**: `8083` (Vectored) / `8085` (Unvectored)
-*   **Role**: Synthesis, structure, and professional output.
-*   **Configuration**: 8B Instruct model.
-*   **Steering**:
-    *   **Vectored (`llama`)**: Uses a Control Vector at scale **-0.11** ("The Accountant"). This suppresses "chatty" behaviors and enforces structured, professional responses.
-    *   **Unvectored (`llamauv`)**: The raw base model for comparison.
-## Management Standard: "ServiceLifecycle"
-To ensure reliability, all backend services MUST strictly adhere to the `ServiceLifecycle` pattern (`src/utils/ServiceLifecycle.ts`). This provides:
-*   **Unified CLI Interface**: Every service supports `start`, `stop`, `restart`, and `status`.
-*   **Zombie Defense**: Automatic detection and cleanup of rogue processes on startup.
-*   **PID Management**: Reliable tracking of running services via PID files.
-### Global Status Dashboard
-A singular command exists to view the health of the entire backend:
-`bun run servers`
-Example Output:
-```
-SERVICE        PORT      COMMAND        STATUS         PID
-----------------------------------------------------------------------
-Dev Server     3000      dev            ⚪️ STOPPED     -
-Daemon         3010      daemon         ⚪️ STOPPED     -
-MCP            Stdio     mcp            ⚪️ STOPPED     -
-Olmo-3         8084      olmo3          🟢 RUNNING     6526
-Phi-3.5        8082      phi            ⚪️ STOPPED     -
-Llama-3        8083      llama          🟢 RUNNING     15561
-Llama-3-UV     8085      llamauv        🟢 RUNNING     10641
-----------------------------------------------------------------------
-```
-## Adding New Services
-When introducing a new long-running process to PolyVis:
-1.  **Do not** write ad-hoc scripts.
-2.  **Create a wrapper** in `src/services/` that implements `ServiceLifecycle`.
-3.  **Register** the service in `package.json`, `ZombieDefense.ts`, and `scripts/cli/servers.ts`.

package/docs/sqlite-wal-readonly-trap.md DELETED Viewed

@@ -1,228 +0,0 @@
-# The SQLite WAL Readonly Trap
-**TL;DR:** If you use WAL mode (and you should), **never open connections with `readonly: true`**. Even readers need write access to the `-shm` shared memory file. Violating this causes `disk I/O error` and database corruption.
----
-## The Problem
-You enable WAL mode for concurrency. You open a "readonly" connection to query data. Your app crashes with:
-```
-Error: disk I/O error
-SQLITE_IOERR
-```
-**What happened?** WAL mode requires ALL connections (readers and writers) to update the `-shm` (shared memory) file. A "readonly" connection can't do this, so SQLite fails.
----
-## Why This Happens
-### Legacy: Pre-WAL SQLite (pre-2010)
-Before WAL (Write-Ahead Logging), SQLite had two access modes:
-- **ReadWrite:** Can modify the database
-- **Readonly:** Safe for concurrent readers, no locks needed
-This made sense when the journal was file-based. Readers didn't touch anything.
-### WAL Mode (2010+)
-WAL introduced a shared memory file (`dbname-shm`) to coordinate between processes.
-- Register itself as an active reader
-- Track which WAL frames it has read
-- Coordinate checkpointing
-**The trap:** Many developers (and AI agents) assume "readonly" still works because it did pre-2010. The mental model is 16 years out of date.
-**Why LLMs get this wrong:** Training data is dominated by pre-2010 SQLite tutorials, StackOverflow answers from 2008-2012, and books written when DELETE mode was default. LLMs confidently suggest `readonly: true` because that's what the corpus says, not because it works in WAL.
----
-## The Hard-Earned Fix
-### ❌ Wrong (Causes Corruption)
-```javascript
-// Bun/Node.js
-const Database = require('bun:sqlite');
-const db = new Database('app.db', { readonly: true });  // ☠️ BROKEN IN WAL
-// Python
-import sqlite3
-conn = sqlite3.connect('app.db', uri=True, readonly=True)  # ☠️ BROKEN IN WAL
-// Golang
-db, _ := sql.Open("sqlite3", "file:app.db?mode=ro")  // ☠️ BROKEN IN WAL
-```
-### ✅ Correct (Always Works)
-```javascript
-// Bun/Node.js - Use default ReadWrite
-const Database = require('bun:sqlite');
-const db = new Database('app.db');  // ✅ Works in WAL
-// Python - Omit readonly
-import sqlite3
-conn = sqlite3.connect('app.db')  # ✅ Works in WAL
-// Golang - Use default mode
-db, _ := sql.Open("sqlite3", "app.db")  // ✅ Works in WAL
-```
-**Key insight:** In WAL mode, "readonly" is a behavioral constraint you enforce in your code, not a database-level flag.
----
-## Best Practices: The Polyvis Standard
-We learned this the hard way through a process we call **"Harden and Flense"** - fortify the critical paths (Harden) and strip away assumptions that no longer hold (Flense).
-Here's our battle-tested approach:
-### 1. Enforce WAL + Timeout at Connection Time
-Every connection gets these pragmas immediately:
-```sql
-PRAGMA busy_timeout = 5000;    -- Wait 5s for locks (MUST BE FIRST)
-PRAGMA journal_mode = WAL;      -- Enable concurrent reads
-PRAGMA synchronous = NORMAL;    -- Balance safety/speed
-PRAGMA foreign_keys = ON;       -- Data integrity
-PRAGMA temp_store = memory;     -- Performance
-```
-### 2. Use a Factory Pattern
-Never instantiate connections directly. Use a factory that enforces standards:
-```typescript
-// DatabaseFactory.ts
-export const DatabaseFactory = {
-  connect(path: string, options = {}) {
-    const db = new Database(path);  // Never use { readonly: true }
-    db.run("PRAGMA busy_timeout = 5000;");  // FIRST!
-    const current = db.query("PRAGMA journal_mode;").get();
-    if (current.journal_mode !== "wal") {
-      db.run("PRAGMA journal_mode = WAL;");
-    }
-    db.run("PRAGMA synchronous = NORMAL;");
-    db.run("PRAGMA foreign_keys = ON;");
-    db.run("PRAGMA temp_store = memory;");
-    return db;
-  }
-};
-```
-### 3. Behavioral Readonly (Not Database-Level)
-If you need readonly semantics, enforce it in your application:
-```typescript
-class ReadonlyDatabase {
-  constructor(path: string) {
-    this.db = DatabaseFactory.connect(path);  // Full access
-  }
-  query(sql: string, ...params) {
-    if (sql.trim().toUpperCase().startsWith('SELECT')) {
-      return this.db.query(sql).all(...params);
-    }
-    throw new Error('Readonly database: SELECT only');
-  }
-}
-```
-### 4. Centralize Configuration (Harden)
-Don't scatter pragma calls across your codebase. Create one source of truth:
-```
-playbooks/sqlite-standards.md  ← Document the why
-DatabaseFactory.ts              ← Enforce the how
-```
-When you forget (and you will), the factory catches you.
-**The Harden principle:** Make the correct path automatic. Incorrect paths should require deliberate effort to achieve.
-### 5. Strip Legacy Assumptions (Flense)
-Audit your codebase for outdated patterns:
-- `readonly: true` in database connections
-- `journal_mode = DELETE` assumptions
-- Missing `busy_timeout` settings
-- Direct `new Database()` calls without pragma setup
-**The Flense principle:** Remove what no longer serves. Pre-2010 patterns are technical debt.
----
-## Signs You've Hit This Bug
-- ✅ Works perfectly in dev (low concurrency)
-- ☠️ Crashes in production (high concurrency)
-- ☠️ Error message: `disk I/O error`, `SQLITE_IOERR`, or `SQLITE_READONLY`
-- ☠️ Happens when multiple processes access the database
-- ☠️ `-shm` or `-wal` files exist but connection fails
----
-## When This Doesn't Apply
-You're safe to skip this if:
-- You use `journal_mode = DELETE` (old default)
-- You have exactly one process, one connection, no concurrency
-- Your database is truly readonly (burned to CD-ROM)
-**But if you're here, you probably need WAL.**
----
-## The Deeper Why: WAL Architecture
-WAL changed SQLite from a single-writer model to a concurrent model:
-```
-Pre-2010 (DELETE mode):
-┌─────────┐
-│ main DB │ ← Writers lock entire file
-└─────────┘   Readers wait
-2010+ (WAL mode):
-┌─────────┐     ┌─────────┐     ┌─────────┐
-│ main DB │ ←── │   WAL   │ ──→ │   SHM   │
-└─────────┘     └─────────┘     └─────────┘
-                                  ↑ ALL connections must access
-```
-The `-shm` file is a POSIX shared memory segment. It's not optional. It's not a cache. It's the coordination mechanism that makes WAL work.
-Opening a connection without write access to `-shm` is like trying to join a meeting without being able to raise your hand. The system doesn't know you exist.
----
-## Recommended Reading
-- [SQLite WAL Mode Docs](https://www.sqlite.org/wal.html) - Official explanation
-- [Appropriate Uses For SQLite](https://www.sqlite.org/whentouse.html) - When to use WAL
-- [File Locking And Concurrency](https://www.sqlite.org/lockingv3.html) - Deep dive
----
-## License & Attribution
-This document is born from production failures at Polyvis. Copy it. Share it. Save someone else the debugging pain.
-**Polyvis Standard:** See our full implementation in:
-- `src/resonance/DatabaseFactory.ts` - Factory pattern
-- `playbooks/sqlite-standards.md` - Team playbook
-- `debriefs/2025-12-16-database-stabilization.md` - The war stories
----
-## Version History
-- **v1.0** (2026-01-05) - Initial release after repeated production incidents

package/docs/strategy/css-architecture.md DELETED Viewed

@@ -1,40 +0,0 @@
-# CSS Architecture Strategy: "Zero Magic, High Predictability"
-## The Problem
-We are currently "fighting the framework".
-1.  **Tailwind Preflight** aggressively strips all defaults (cursors, backgrounds) to ensure a blank canvas.
-2.  **Open Props** provides tokens but expects us to wire them up.
-3.  **Our Custom CSS** attempts to put styles back, but often clashes with the aggressive reset.
-4.  **The Build System** (Static Files) created a "Zombie Code" scenario where changes weren't reflected.
-## The Solution
-### 1. The Build: "Fresh Start" Protocol
-We must guarantee that `http://localhost:3000` never serves stale code.
-*   **Action:** Update `scripts/cli/dev.ts` to **DELETE** `public/css/app.css` on startup.
-*   **Result:** If the build fails, the site breaks (Good). If it works, it is fresh (Good). No more "Dark on Dark" ghosts.
-### 2. The Reset: "PolyVis Base"
-Instead of importing a generic reset (like `open-props/normalize`) which previously broke our layout, we officially designate `src/css/layers/base.css` as our **Explicit Reset**.
-*   **Rule:** If Tailwind strips it (like `cursor: pointer`), we explicitly put it back in `base.css`.
-*   **Benefit:** We control the defaults. No hidden external styles.
-### 3. The Future: "Utility-First"
-We should stop writing component classes like `.btn-structural` in CSS files.
-*   **Direction:** Move styles into HTML using Tailwind classes (e.g., `class="cursor-pointer bg-surface-hover..."`).
-*   **Benefit:** The HTML tells the truth. No CSS file hunting.
-## Immediate Next Steps
-1.  [x] **Fix Cursors:** Done in `base.css`.
-2.  [ ] **Fix Build:** Modify `scripts/cli/dev.ts` to clean stale artifacts.
-## Lessons Learned (2025-12-15)
-*   **Layout Hierarchy:** Trying to control width via *Content* (Buttons) inside a Flex *Container* (Sidebar) creates friction and unpredictable stretching. Always control the **Container** first.
-*   **Utility vs. Layout:** Utility classes are excellent for discrete styling (colors, spacing) but should be used carefully for varying layout contexts.
-*   **Revert Culture:** If an experiment fails (like fixed-width buttons), revert to the known stable state (Content-based sizing) rather than patching the bad assumption.
-## Phase 2: The CSS Remediation Plan
-To eliminate "CSS Friction":
-1.  **Strict Layering:** Enforce `reset` -> `theme` -> `layout` -> `utilities`.
-2.  **Container Queries:** Explore `@container` for components that need to adapt (like sidebar buttons) without relying on global viewport queries.
-3.  **Theme Variables for Layout:** Define layout constants (Sidebar Width, Header Height) in `theme.css` to centralize control, but allow components to read them, not drive them.
-4.  **Audit:** Systematically review `index.html` to remove mixed metaphors (e.g., inline styles fighting Tailwind classes).