@aperdomoll90/ledger-ai 1.2.0 → 1.4.0

package/README.md

@@ -41,7 +41,7 @@ ledger init    # connect to existing Supabase, pull persona, set up platform
 
 **For you:** Define who you are, how you want AI to behave, your coding conventions, communication style. Do it once. Every AI agent on every device follows the same rules.
 
-**For your agents:** Semantic search over your knowledge base. Notes are embedded with OpenAI and stored in Postgres with pgvector. Agents find relevant context by meaning, not keywords.
+**For your agents:** A full RAG (Retrieval-Augmented Generation) system. Notes are embedded with OpenAI and stored in Postgres with pgvector. Agents find relevant context by semantic meaning, not keywords. Retrieved context is injected into agent prompts automatically via MCP.
 
 **For your workflow:** Automatic sync at session start, conflict detection, session-end checks. Hooks enforce rules (block credential file access, auto-ingest notes to Ledger).
 
@@ -153,10 +153,16 @@ npm run release    # version bump → build → test → publish to npm
 
 ## Roadmap
 
-- Multi-provider embeddings (Supabase built-in, OpenAI, others)
+### RAG Enhancements
+- Hybrid search (vector + BM25 keyword via PostgreSQL full-text search)
+- Re-ranking — score retrieved chunks before feeding to LLM
+- Chunking strategies for large documents (auto-split on ingest)
+- Multi-format ingest (PDF, Excel, images, audio)
+- Multi-provider embeddings (Supabase built-in, OpenAI, Ollama, Cohere)
+
+### Platform
 - Note versioning / history
 - Soft delete (trash)
-- Multi-format ingest (PDF, Excel, images, audio)
 - Web dashboard
 - Skills system (context-aware convention enforcement)
 - VS Code extension

package/dist/cli.js

@@ -6,7 +6,7 @@ const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
 import { pull } from './commands/pull.js';
 import { push } from './commands/push.js';
-import { check } from './commands/check.js';
+import { check, checkChunks } from './commands/check.js';
 import { sync } from './commands/sync.js';
 import { show } from './commands/show.js';
 import { exportNote } from './commands/export.js';
@@ -24,6 +24,7 @@ import { update } from './commands/update.js';
 import { deleteNote } from './commands/delete.js';
 import { list } from './commands/list.js';
 import { tag } from './commands/tag.js';
+import { lint } from './commands/lint.js';
 process.on('unhandledRejection', (err) => {
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);
@@ -51,10 +52,16 @@ program
 });
 program
     .command('check')
-    .description('Compare local files vs Ledger, report sync status (alias for sync --dry-run)')
-    .action(async () => {
+    .description('Compare local files vs Ledger, report sync status')
+    .option('--chunks', 'Check chunk group integrity')
+    .action(async (opts) => {
     const config = loadConfig();
-    await check(config);
+    if (opts.chunks) {
+        await checkChunks(config);
+    }
+    else {
+        await check(config);
+    }
 });
 program
     .command('sync')
@@ -272,4 +279,12 @@ program
         scope: options.scope,
     });
 });
+program
+    .command('lint')
+    .description('Add lint configs to the current project based on detected stack')
+    .option('--personal', 'include personal conventions (BEM, SCSS patterns)')
+    .option('--diff', 'compare local configs against Ledger versions')
+    .action(async (options) => {
+    await lint({ personal: options.personal ?? false, diff: options.diff ?? false });
+});
 program.parse();

package/dist/commands/add.js

@@ -39,7 +39,7 @@ export async function add(config, content, options) {
                     console.error(nameError);
                     process.exit(1);
                 }
-                const deliveryChoice = await choose('Delivery tier?', ['persona', 'project', 'knowledge']);
+                const deliveryChoice = await choose('Delivery tier?', ['persona', 'project', 'knowledge', 'protected']);
                 registerType(type, deliveryChoice);
                 console.error(`Registered type "${type}" with delivery "${deliveryChoice}".`);
             }

package/dist/commands/check.js

@@ -1,6 +1,6 @@
 import { readFileSync, readdirSync, existsSync } from 'fs';
 import { resolve } from 'path';
-import { fetchNoteHashes } from '../lib/notes.js';
+import { fetchNoteHashes, checkChunkIntegrity } from '../lib/notes.js';
 import { contentHash } from '../lib/hash.js';
 export async function check(config) {
     const result = {
@@ -77,3 +77,15 @@ export async function check(config) {
     }
     return result;
 }
+export async function checkChunks(config) {
+    console.error('Checking chunk integrity...');
+    const result = await checkChunkIntegrity(config.supabase);
+    if (result.incompleteGroups.length === 0) {
+        console.log('All chunk groups are complete.');
+        return;
+    }
+    console.error(`Found ${result.incompleteGroups.length} incomplete chunk group(s):`);
+    for (const group of result.incompleteGroups) {
+        console.error(`  group ${group.groupId}: expected ${group.expected} chunks, found ${group.found}`);
+    }
+}

package/dist/commands/config.js

@@ -155,8 +155,8 @@ export async function configSet(key, value, clients) {
     if (key.startsWith('types.')) {
         const typeName = key.slice(6);
         const delivery = value;
-        if (!['persona', 'project', 'knowledge'].includes(delivery)) {
-            console.error(`Invalid delivery tier: "${value}". Must be: persona, project, or knowledge.`);
+        if (!['persona', 'project', 'knowledge', 'protected'].includes(delivery)) {
+            console.error(`Invalid delivery tier: "${value}". Must be: persona, project, knowledge, or protected.`);
             process.exit(1);
         }
         const nameError = validateTypeName(typeName);

package/dist/commands/ingest.js

@@ -108,7 +108,7 @@ async function ingestFile(config, filePath, existingNotes) {
     const defaultDelivery = inferDelivery(noteType);
     const deliveryChoice = await choose(`Delivery tier (default: ${defaultDelivery}):`, [
         `${defaultDelivery} (default)`,
-        ...['persona', 'project', 'knowledge'].filter(d => d !== defaultDelivery),
+        ...['persona', 'project', 'knowledge', 'protected'].filter(d => d !== defaultDelivery),
     ]);
     const delivery = deliveryChoice.replace(' (default)', '');
     const { openai } = config;

package/dist/commands/lint.js

@@ -0,0 +1,179 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { execSync } from 'child_process';
+import { createInterface } from 'readline';
+import { detectStack, getConfigsForStack, ESLINT_TS, ESLINT_TS_REACT, STYLELINT_UNIVERSAL, } from '../lib/lint-configs.js';
+// --- Helpers ---
+async function confirm(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.trim() === 'y' || answer.trim() === 'yes');
+        });
+    });
+}
+// --- writeConfig ---
+export async function writeConfig(projectDir, config) {
+    const filePath = resolve(projectDir, config.filename);
+    if (existsSync(filePath)) {
+        const existing = readFileSync(filePath, 'utf-8');
+        if (existing === config.content) {
+            console.error(`  ${config.filename} — already up to date`);
+            return;
+        }
+        const overwrite = await confirm(`  ${config.filename} already exists. Overwrite?`);
+        if (!overwrite) {
+            console.error(`  ${config.filename} — skipped`);
+            return;
+        }
+    }
+    writeFileSync(filePath, config.content, 'utf-8');
+    console.error(`  ${config.filename} — written`);
+}
+function getUniversalConfigs(hasReact) {
+    return {
+        eslint: { filename: 'eslint.config.js', content: hasReact ? ESLINT_TS_REACT : ESLINT_TS },
+        stylelint: { filename: '.stylelintrc.json', content: STYLELINT_UNIVERSAL },
+    };
+}
+export async function handleDiff(projectDir, configs, universalConfigs) {
+    const toCheck = [];
+    if (configs.eslint) {
+        toCheck.push({ filename: configs.eslint.filename, template: configs.eslint.content });
+        // Also check universal if writing personal
+        if (configs.eslint.filename !== universalConfigs.eslint.filename) {
+            toCheck.push({ filename: universalConfigs.eslint.filename, template: universalConfigs.eslint.content });
+        }
+    }
+    if (configs.stylelint) {
+        toCheck.push({ filename: configs.stylelint.filename, template: configs.stylelint.content });
+        if (configs.stylelint.filename !== universalConfigs.stylelint.filename) {
+            toCheck.push({ filename: universalConfigs.stylelint.filename, template: universalConfigs.stylelint.content });
+        }
+    }
+    if (toCheck.length === 0) {
+        console.error('No lint configs applicable for this project stack.');
+        return;
+    }
+    let anyDiff = false;
+    for (const { filename, template } of toCheck) {
+        const filePath = resolve(projectDir, filename);
+        if (!existsSync(filePath)) {
+            console.error(`  ${filename} — not found (run without --diff to create)`);
+            anyDiff = true;
+            continue;
+        }
+        const existing = readFileSync(filePath, 'utf-8');
+        if (existing === template) {
+            console.error(`  ${filename} — up to date`);
+        }
+        else {
+            console.error(`  ${filename} — differs from Ledger template`);
+            anyDiff = true;
+            const update = await confirm(`  Update ${filename} to Ledger version?`);
+            if (update) {
+                writeFileSync(filePath, template, 'utf-8');
+                console.error(`  ${filename} — updated`);
+            }
+        }
+    }
+    if (!anyDiff) {
+        console.error('\nAll configs are up to date.');
+    }
+}
+// --- checkDependencies ---
+const ESLINT_TS_DEPS = ['typescript-eslint', 'eslint-plugin-import'];
+const ESLINT_REACT_DEPS = ['eslint-plugin-react', 'eslint-plugin-jsx-a11y'];
+const STYLELINT_DEPS = ['stylelint', 'stylelint-config-standard-scss'];
+export async function checkDependencies(projectDir, stack, personal) {
+    const packageJsonPath = resolve(projectDir, 'package.json');
+    if (!existsSync(packageJsonPath))
+        return;
+    let pkg;
+    try {
+        pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    }
+    catch {
+        return;
+    }
+    const installed = new Set([
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.devDependencies ?? {}),
+    ]);
+    const needed = [];
+    const needsEslint = stack.hasTypeScript || stack.hasReact;
+    const needsStylelint = stack.hasScss;
+    if (needsEslint) {
+        for (const dep of ESLINT_TS_DEPS) {
+            if (!installed.has(dep))
+                needed.push(dep);
+        }
+        if (stack.hasReact) {
+            for (const dep of ESLINT_REACT_DEPS) {
+                if (!installed.has(dep))
+                    needed.push(dep);
+            }
+        }
+    }
+    if (needsStylelint) {
+        for (const dep of STYLELINT_DEPS) {
+            if (!installed.has(dep))
+                needed.push(dep);
+        }
+    }
+    if (personal) {
+        // no extra deps for personal configs
+    }
+    if (needed.length === 0)
+        return;
+    console.error('\nMissing devDependencies:');
+    for (const dep of needed) {
+        console.error(`  - ${dep}`);
+    }
+    const install = await confirm('\nInstall missing dependencies now?');
+    if (install) {
+        execSync(`npm install --save-dev ${needed.join(' ')}`, { stdio: 'inherit', cwd: projectDir });
+    }
+}
+// --- Main lint command ---
+export async function lint(options) {
+    const projectDir = process.cwd();
+    console.error('Detecting project stack...');
+    const stack = detectStack(projectDir);
+    console.error(`  package.json: ${stack.hasPackageJson}`);
+    console.error(`  TypeScript:   ${stack.hasTypeScript}`);
+    console.error(`  React:        ${stack.hasReact}`);
+    console.error(`  SCSS:         ${stack.hasScss}`);
+    console.error('');
+    const configs = getConfigsForStack(stack, options.personal);
+    const universalConfigs = getUniversalConfigs(stack.hasReact);
+    if (!configs.eslint && !configs.stylelint) {
+        console.error('No lint configs applicable for this stack (needs TypeScript, React, or SCSS).');
+        return;
+    }
+    if (options.diff) {
+        console.error('Comparing local configs against Ledger templates...\n');
+        await handleDiff(projectDir, configs, universalConfigs);
+        return;
+    }
+    console.error('Writing lint configs...\n');
+    // When personal, also write the universal configs that personal ones extend
+    if (options.personal) {
+        if (configs.eslint) {
+            await writeConfig(projectDir, universalConfigs.eslint);
+        }
+        if (configs.stylelint) {
+            await writeConfig(projectDir, universalConfigs.stylelint);
+        }
+    }
+    if (configs.eslint) {
+        await writeConfig(projectDir, configs.eslint);
+    }
+    if (configs.stylelint) {
+        await writeConfig(projectDir, configs.stylelint);
+    }
+    console.error('');
+    await checkDependencies(projectDir, stack, options.personal);
+    console.error('\nDone.');
+}

package/dist/lib/lint-configs.js

@@ -0,0 +1,163 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { resolve, join } from 'path';
+// --- Config Templates ---
+// Keep shared TS rules in sync between ESLINT_TS and ESLINT_TS_REACT
+export const ESLINT_TS = `import tseslint from 'typescript-eslint';
+import importPlugin from 'eslint-plugin-import';
+
+export default tseslint.config(
+  ...tseslint.configs.recommended,
+  {
+    plugins: {
+      import: importPlugin,
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      'import/no-default-export': 'error',
+      'max-lines': ['warn', { max: 200, skipBlankLines: true, skipComments: true }],
+      'no-console': ['warn', { allow: ['error', 'warn'] }],
+    },
+  },
+);
+`;
+export const ESLINT_TS_REACT = `import tseslint from 'typescript-eslint';
+import reactPlugin from 'eslint-plugin-react';
+import jsxA11yPlugin from 'eslint-plugin-jsx-a11y';
+import importPlugin from 'eslint-plugin-import';
+
+export default tseslint.config(
+  ...tseslint.configs.recommended,
+  {
+    plugins: {
+      react: reactPlugin,
+      'jsx-a11y': jsxA11yPlugin,
+      import: importPlugin,
+    },
+    settings: {
+      react: { version: 'detect' },
+    },
+    rules: {
+      '@typescript-eslint/no-explicit-any': 'error',
+      '@typescript-eslint/consistent-type-definitions': ['error', 'interface'],
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
+      'react/button-has-type': 'error',
+      'import/no-default-export': 'error',
+      'jsx-a11y/anchor-is-valid': 'warn',
+      'jsx-a11y/click-events-have-key-events': 'warn',
+      'max-lines': ['warn', { max: 200, skipBlankLines: true, skipComments: true }],
+      'no-console': ['warn', { allow: ['error', 'warn'] }],
+    },
+  },
+);
+`;
+// Backwards compat alias
+export const ESLINT_UNIVERSAL = ESLINT_TS_REACT;
+export const ESLINT_PERSONAL = `import universalConfig from './eslint.config.js';
+
+export default [
+  ...universalConfig,
+  {
+    rules: {
+      'no-warning-comments': ['warn', { terms: ['TODO', 'FIXME', 'HACK'] }],
+    },
+  },
+];
+`;
+export const STYLELINT_UNIVERSAL = JSON.stringify({
+    extends: ['stylelint-config-standard-scss'],
+    rules: {
+        'unit-disallowed-list': ['vh', 'vw'],
+        'declaration-property-unit-allowed-list': {
+            padding: ['rem', '%'],
+            margin: ['rem', '%'],
+            gap: ['rem', '%'],
+            'border-width': ['px'],
+            'font-size': ['rem'],
+        },
+        'color-no-hex': [true, { severity: 'warning' }],
+        'declaration-no-important': true,
+        'declaration-block-no-duplicate-properties': true,
+        'shorthand-property-no-redundant-values': [true, { severity: 'warning' }],
+    },
+}, null, 2);
+export const STYLELINT_PERSONAL = JSON.stringify({
+    extends: ['./.stylelintrc.json'],
+    rules: {
+        'selector-class-pattern': [
+            '^c-[a-z][a-z0-9]*(__[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*)?$',
+            {
+                message: 'Class names must use BEM with c- prefix (e.g. c-block__element-modifier)',
+            },
+        ],
+        'unit-disallowed-list': ['vh', 'vw', 'dvh'],
+        'media-feature-name-disallowed-list': ['max-width'],
+        'max-nesting-depth': [3, { severity: 'warning' }],
+    },
+}, null, 2);
+function hasScssFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (entry === 'node_modules')
+            continue;
+        const fullPath = join(dir, entry);
+        let stat;
+        try {
+            stat = statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            if (hasScssFiles(fullPath))
+                return true;
+        }
+        else if (entry.endsWith('.scss')) {
+            return true;
+        }
+    }
+    return false;
+}
+export function detectStack(projectDir) {
+    const packageJsonPath = resolve(projectDir, 'package.json');
+    const tsConfigPath = resolve(projectDir, 'tsconfig.json');
+    const hasPackageJson = existsSync(packageJsonPath);
+    const hasTypeScript = existsSync(tsConfigPath);
+    let hasReact = false;
+    if (hasPackageJson) {
+        try {
+            const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            hasReact = 'react' in deps;
+        }
+        catch {
+            // leave hasReact false
+        }
+    }
+    const hasScss = hasScssFiles(projectDir);
+    return { hasPackageJson, hasTypeScript, hasReact, hasScss };
+}
+export function getConfigsForStack(stack, personal) {
+    const needsEslint = stack.hasTypeScript || stack.hasReact;
+    const needsStylelint = stack.hasScss;
+    const eslint = needsEslint
+        ? {
+            filename: personal ? 'eslint.config.personal.js' : 'eslint.config.js',
+            content: personal ? ESLINT_PERSONAL : (stack.hasReact ? ESLINT_TS_REACT : ESLINT_TS),
+        }
+        : null;
+    const stylelint = needsStylelint
+        ? {
+            filename: personal ? '.stylelintrc.personal.json' : '.stylelintrc.json',
+            content: personal ? STYLELINT_PERSONAL : STYLELINT_UNIVERSAL,
+        }
+        : null;
+    return { eslint, stylelint };
+}

package/dist/lib/notes.js

@@ -72,7 +72,6 @@ export async function findNoteByFile(supabase, filename) {
         .from('notes')
         .select('id, metadata')
         .eq('metadata->>local_file', filename)
-        .limit(1)
         .single();
     if (byFile)
         return byFile;
@@ -81,7 +80,6 @@ export async function findNoteByFile(supabase, filename) {
         .from('notes')
         .select('id, metadata')
         .eq('metadata->>upsert_key', upsertKey)
-        .limit(1)
         .single();
     return byKey || null;
 }
@@ -485,7 +483,6 @@ export async function opAddNote(clients, content, type, agent, metadata, force,
             .from('notes')
             .select('id, metadata, created_at')
             .eq('metadata->>upsert_key', upsertKey)
-            .limit(1)
             .single();
         if (existing) {
             return upsertExistingNote(clients, existing, content, fullMetadata);
@@ -586,6 +583,16 @@ export async function opUpdateNote(clients, id, content, metadata, confirmed = f
     if (fetchError || !existing) {
         return { status: 'error', message: `Error: note ${id} not found.` };
     }
+    // Protected delivery gate — skill-reference and other protected notes require explicit confirmation
+    const existingDelivery = existing.metadata.delivery;
+    if (existingDelivery === 'protected' && !confirmed) {
+        const existingType = existing.metadata.type;
+        const uKey = existing.metadata.upsert_key;
+        return {
+            status: 'confirm',
+            message: `⚠️ PROTECTED NOTE — "${uKey || `id ${id}`}" (type: ${existingType || 'unknown'}) has protected delivery.\n\nThis is a skill-reference note. Are you sure you want to update it? Skill reference documents are protected to prevent accidental overwrites.\n\nTo proceed, call update_note again with confirmed: true.`,
+        };
+    }
     // Confirmation gate
     if (!confirmed) {
         const currentPreview = formatNotePreview(existing.id, existing.metadata, existing.content);
@@ -657,7 +664,7 @@ export async function opUpdateNote(clients, id, content, metadata, confirmed = f
     }
     return { status: 'ok', message: `Note updated as ${chunks.length} chunks (ids: ${ids.join(', ')}, group: ${newGroupId})` };
 }
-export async function opUpdateMetadata(clients, id, metadata) {
+export async function opUpdateMetadata(clients, id, metadata, confirmed = false) {
     const { data: existing, error: fetchError } = await clients.supabase
         .from('notes')
         .select('id, metadata')
@@ -666,6 +673,16 @@ export async function opUpdateMetadata(clients, id, metadata) {
     if (fetchError || !existing) {
         return { status: 'error', message: `Error: note ${id} not found.` };
     }
+    // Protected delivery gate
+    const existingDelivery = existing.metadata.delivery;
+    if (existingDelivery === 'protected' && !confirmed) {
+        const existingType = existing.metadata.type;
+        const uKey = existing.metadata.upsert_key;
+        return {
+            status: 'confirm',
+            message: `⚠️ PROTECTED NOTE — "${uKey || `id ${id}`}" (type: ${existingType || 'unknown'}) has protected delivery.\n\nThis is a skill-reference note. Are you sure you want to update its metadata?\n\nTo proceed, call update_metadata again with confirmed: true.`,
+        };
+    }
     const merged = { ...existing.metadata, ...metadata };
     const { error } = await clients.supabase
         .from('notes')
@@ -687,6 +704,15 @@ export async function opDeleteNote(clients, id, confirmed = false) {
     }
     const meta = existing.metadata;
     const groupId = meta.chunk_group;
+    // Protected delivery gate
+    if (meta.delivery === 'protected' && !confirmed) {
+        const uKey = meta.upsert_key;
+        const existingType = meta.type;
+        return {
+            status: 'confirm',
+            message: `⚠️ PROTECTED NOTE — "${uKey || `id ${id}`}" (type: ${existingType || 'unknown'}) has protected delivery.\n\nThis is a skill-reference note. Are you sure you want to delete it? This action cannot be undone.\n\nTo proceed, call delete_note again with confirmed: true.`,
+        };
+    }
     // Confirmation gate
     if (!confirmed) {
         const chunkInfo = groupId ? ` (chunked, all chunks will be deleted)` : '';
@@ -707,3 +733,31 @@ export async function opDeleteNote(clients, id, confirmed = false) {
         return { status: 'error', message: `Error: ${error.message}` };
     return { status: 'ok', message: `Note ${id} deleted.` };
 }
+export async function checkChunkIntegrity(supabase) {
+    const { data: chunkedNotes, error } = await supabase
+        .from('notes')
+        .select('id, metadata')
+        .not('metadata->>chunk_group', 'is', null);
+    if (error || !chunkedNotes)
+        return { incompleteGroups: [] };
+    const groups = new Map();
+    for (const note of chunkedNotes) {
+        const meta = note.metadata;
+        const groupId = meta.chunk_group;
+        if (!groups.has(groupId))
+            groups.set(groupId, []);
+        groups.get(groupId).push({
+            id: note.id,
+            index: meta.chunk_index,
+            total: meta.total_chunks,
+        });
+    }
+    const incompleteGroups = [];
+    for (const [groupId, chunks] of groups) {
+        const expected = chunks[0].total;
+        if (chunks.length !== expected) {
+            incompleteGroups.push({ groupId, expected, found: chunks.length });
+        }
+    }
+    return { incompleteGroups };
+}

package/dist/lib/op-add-note-types.test.js

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+/**
+ * Tests for opAddNote's type registry integration:
+ * - Unknown type → confirm prompt
+ * - Unknown type + register_type → registers then saves
+ * - Unknown type + register_type + invalid name → error
+ * - Alias resolution in add flow
+ *
+ * These tests mock config (filesystem) and force interactive OFF
+ * so we only hit the type-checking code path before any DB calls.
+ */
+const mockConfigState = { current: {} };
+vi.mock('./config.js', () => ({
+    loadConfigFile: () => mockConfigState.current,
+    saveConfigFile: (config) => { mockConfigState.current = config; },
+}));
+// Mock hash module (used in opAddNote for content_hash)
+vi.mock('./hash.js', () => ({
+    contentHash: (s) => `hash-${s.length}`,
+}));
+const { opAddNote, BUILTIN_TYPES } = await import('./notes.js');
+// --- Mock Clients ---
+function createMockClients() {
+    const insertResult = { data: { id: 999, created_at: '2026-01-01' }, error: null };
+    const selectChain = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        limit: vi.fn().mockReturnThis(),
+        single: vi.fn().mockResolvedValue({ data: null, error: null }),
+    };
+    const insertChain = {
+        select: vi.fn().mockReturnValue({
+            single: vi.fn().mockResolvedValue(insertResult),
+        }),
+    };
+    const supabase = {
+        from: vi.fn().mockReturnValue({
+            ...selectChain,
+            insert: vi.fn().mockReturnValue(insertChain),
+        }),
+        rpc: vi.fn().mockResolvedValue({ data: [], error: null }),
+    };
+    const openai = {
+        embeddings: {
+            create: vi.fn().mockResolvedValue({
+                data: [{ embedding: new Array(1536).fill(0) }],
+            }),
+        },
+    };
+    return { supabase, openai };
+}
+// --- Helpers ---
+function resetConfig() {
+    mockConfigState.current = { naming: { interactive: false } };
+}
+beforeEach(() => {
+    resetConfig();
+});
+// ============================================================
+// Unknown type → confirm prompt
+// ============================================================
+describe('opAddNote — unknown type handling', () => {
+    it('returns confirm when type is unknown and register_type is false', async () => {
+        const clients = createMockClients();
+        const result = await opAddNote(clients, 'Some content', 'wine-log', 'claude-code', { upsert_key: 'test', description: 'test' }, false, // force
+        false);
+        expect(result.status).toBe('confirm');
+        expect(result.message).toContain('wine-log');
+        expect(result.message).toContain('not registered');
+        expect(result.message).toContain('Options');
+    });
+    it('confirm message lists all registered types', async () => {
+        const clients = createMockClients();
+        const result = await opAddNote(clients, 'Content', 'unknown-type', 'agent', { upsert_key: 'test', description: 'test' }, false, false);
+        expect(result.status).toBe('confirm');
+        // Should list built-in types
+        expect(result.message).toContain('code-craft');
+        expect(result.message).toContain('architecture-decision');
+        expect(result.message).toContain('reference');
+    });
+});
+// ============================================================
+// Unknown type + register_type → registers then proceeds
+// ============================================================
+describe('opAddNote — type registration', () => {
+    it('registers type and saves note when register_type is true', async () => {
+        const clients = createMockClients();
+        const result = await opAddNote(clients, 'Tasting notes for 2024 Malbec', 'wine-log', 'claude-code', { upsert_key: 'wine-2024-malbec', description: 'Tasting notes', delivery: 'project' }, false, true);
+        // Should succeed (type got registered mid-call)
+        expect(result.status).toBe('ok');
+        // Type should now be in config
+        expect(mockConfigState.current.types?.['wine-log']).toBe('project');
+    });
+    it('defaults delivery to knowledge when not specified', async () => {
+        const clients = createMockClients();
+        await opAddNote(clients, 'My recipe content', 'recipe', 'claude-code', { upsert_key: 'recipe-pasta', description: 'Pasta recipe' }, false, true);
+        expect(mockConfigState.current.types?.['recipe']).toBe('knowledge');
+    });
+    it('registered type persists for subsequent calls', async () => {
+        const clients = createMockClients();
+        // First call: register
+        await opAddNote(clients, 'First wine note', 'wine-log', 'claude-code', { upsert_key: 'wine-1', description: 'First', delivery: 'project' }, false, true);
+        // Second call: should NOT need register_type anymore
+        const result = await opAddNote(clients, 'Second wine note', 'wine-log', 'claude-code', { upsert_key: 'wine-2', description: 'Second' }, false, false);
+        expect(result.status).toBe('ok');
+    });
+});
+// ============================================================
+// Invalid type name with register_type
+// ============================================================
+describe('opAddNote — invalid type name rejection', () => {
+    it('returns error for uppercase type name', async () => {
+        const clients = createMockClients();
+        const result = await opAddNote(clients, 'Content', 'Wine-Log', 'agent', { upsert_key: 'test', description: 'test' }, false, true);
+        expect(result.status).toBe('error');
+        expect(result.message).toContain('Invalid type name');
+    });
+    it('returns error for single-character type name', async () => {
+        const clients = createMockClients();
+        const result = await opAddNote(clients, 'Content', 'x', 'agent', { upsert_key: 'test', description: 'test' }, false, true);
+        expect(result.status).toBe('error');
+        expect(result.message).toContain('at least 2');
+    });
+    it('returns error for type name with underscores', async () => {
+        const clients = createMockClients();
+        const result = await opAddNote(clients, 'Content', 'wine_log', 'agent', { upsert_key: 'test', description: 'test' }, false, true);
+        expect(result.status).toBe('error');
+        expect(result.message).toContain('Invalid type name');
+    });
+});
+// ============================================================
+// Alias resolution in opAddNote
+// ============================================================
+describe('opAddNote — alias resolution', () => {
+    it('feedback alias resolves to general and saves successfully', async () => {
+        const clients = createMockClients();
+        const result = await opAddNote(clients, 'Some feedback content', 'feedback', 'claude-code', { upsert_key: 'test-feedback', description: 'Test feedback' }, false, false);
+        // 'feedback' aliases to 'general' which is a built-in — should work
+        expect(result.status).toBe('ok');
+    });
+});
+// ============================================================
+// Built-in types work without registration
+// ============================================================
+describe('opAddNote — built-in types', () => {
+    it('accepts all built-in types without register_type flag', async () => {
+        const clients = createMockClients();
+        for (const builtinType of Object.keys(BUILTIN_TYPES)) {
+            const result = await opAddNote(clients, `Content for ${builtinType}`, builtinType, 'claude-code', {
+                upsert_key: `test-${builtinType}`,
+                description: `Test ${builtinType}`,
+                ...(builtinType === 'architecture-decision' || builtinType === 'project-status' || builtinType === 'event' || builtinType === 'error'
+                    ? { status: 'active' }
+                    : {}),
+            }, false, false);
+            expect(result.status, `Built-in type "${builtinType}" should be accepted`).toBe('ok');
+        }
+    });
+});

package/dist/lib/type-registry.test.js

@@ -0,0 +1,258 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+// Mock config module — isolates tests from filesystem
+const mockConfigState = { current: {} };
+vi.mock('./config.js', () => ({
+    loadConfigFile: () => mockConfigState.current,
+    saveConfigFile: (config) => { mockConfigState.current = config; },
+}));
+// Import AFTER mock setup so modules pick up the mocked config
+const { BUILTIN_TYPES, getTypeRegistry, inferDelivery, getRegisteredTypes, isRegisteredType, registerType, validateTypeName, checkMetadataCompleteness, } = await import('./notes.js');
+// --- Helpers ---
+function setUserTypes(types) {
+    mockConfigState.current = { types };
+}
+function resetConfig() {
+    mockConfigState.current = {};
+}
+// --- Tests ---
+beforeEach(() => {
+    resetConfig();
+});
+// ============================================================
+// 1. getTypeRegistry
+// ============================================================
+describe('getTypeRegistry', () => {
+    it('returns built-ins when no user config', () => {
+        const registry = getTypeRegistry();
+        expect(registry).toEqual(BUILTIN_TYPES);
+    });
+    it('merges user overrides with built-ins', () => {
+        setUserTypes({ 'wine-log': 'project' });
+        const registry = getTypeRegistry();
+        expect(registry['wine-log']).toBe('project');
+        expect(registry['code-craft']).toBe('persona'); // built-in still present
+    });
+    it('user overrides win over built-in defaults', () => {
+        setUserTypes({ 'code-craft': 'knowledge' });
+        const registry = getTypeRegistry();
+        expect(registry['code-craft']).toBe('knowledge');
+    });
+});
+// ============================================================
+// 2. inferDelivery
+// ============================================================
+describe('inferDelivery', () => {
+    it('returns correct tier for built-in types', () => {
+        expect(inferDelivery('persona-rule')).toBe('persona');
+        expect(inferDelivery('architecture-decision')).toBe('project');
+        expect(inferDelivery('reference')).toBe('knowledge');
+    });
+    it('respects user overrides', () => {
+        setUserTypes({ 'code-craft': 'project' });
+        expect(inferDelivery('code-craft')).toBe('project');
+    });
+    it('defaults unknown types to knowledge', () => {
+        expect(inferDelivery('nonexistent-type')).toBe('knowledge');
+    });
+    it('resolves aliases — feedback maps to general (knowledge)', () => {
+        expect(inferDelivery('feedback')).toBe('knowledge');
+    });
+    it('resolves aliases before checking overrides', () => {
+        // Override 'general' (which 'feedback' aliases to)
+        setUserTypes({ 'general': 'project' });
+        expect(inferDelivery('feedback')).toBe('project');
+    });
+});
+// ============================================================
+// 3. isRegisteredType
+// ============================================================
+describe('isRegisteredType', () => {
+    it('returns true for built-in types', () => {
+        expect(isRegisteredType('code-craft')).toBe(true);
+        expect(isRegisteredType('event')).toBe(true);
+    });
+    it('returns true for custom types', () => {
+        setUserTypes({ 'wine-log': 'project' });
+        expect(isRegisteredType('wine-log')).toBe(true);
+    });
+    it('returns false for unknown types', () => {
+        expect(isRegisteredType('nonexistent')).toBe(false);
+    });
+    it('returns true for aliased types (feedback → general)', () => {
+        expect(isRegisteredType('feedback')).toBe(true);
+    });
+});
+// ============================================================
+// 4. getRegisteredTypes
+// ============================================================
+describe('getRegisteredTypes', () => {
+    it('returns all built-in type names when no custom types', () => {
+        const types = getRegisteredTypes();
+        expect(types).toContain('code-craft');
+        expect(types).toContain('architecture-decision');
+        expect(types).toContain('reference');
+        expect(types.length).toBe(Object.keys(BUILTIN_TYPES).length);
+    });
+    it('includes custom types in the list', () => {
+        setUserTypes({ 'wine-log': 'project', 'recipe': 'knowledge' });
+        const types = getRegisteredTypes();
+        expect(types).toContain('wine-log');
+        expect(types).toContain('recipe');
+        expect(types.length).toBe(Object.keys(BUILTIN_TYPES).length + 2);
+    });
+    it('does not duplicate when overriding a built-in', () => {
+        setUserTypes({ 'code-craft': 'knowledge' });
+        const types = getRegisteredTypes();
+        const codeCraftCount = types.filter(t => t === 'code-craft').length;
+        expect(codeCraftCount).toBe(1);
+        expect(types.length).toBe(Object.keys(BUILTIN_TYPES).length);
+    });
+});
+// ============================================================
+// 5. registerType
+// ============================================================
+describe('registerType', () => {
+    it('writes a new custom type to config', () => {
+        registerType('wine-log', 'project');
+        expect(mockConfigState.current.types?.['wine-log']).toBe('project');
+    });
+    it('does not clobber existing config keys', () => {
+        mockConfigState.current = {
+            device: { alias: 'test-machine' },
+            types: { 'existing': 'knowledge' },
+        };
+        registerType('wine-log', 'project');
+        expect(mockConfigState.current.device?.alias).toBe('test-machine');
+        expect(mockConfigState.current.types?.['existing']).toBe('knowledge');
+        expect(mockConfigState.current.types?.['wine-log']).toBe('project');
+    });
+    it('initializes types object if missing', () => {
+        mockConfigState.current = {};
+        registerType('recipe', 'knowledge');
+        expect(mockConfigState.current.types).toBeDefined();
+        expect(mockConfigState.current.types?.['recipe']).toBe('knowledge');
+    });
+    it('registered type becomes discoverable immediately', () => {
+        expect(isRegisteredType('wine-log')).toBe(false);
+        registerType('wine-log', 'project');
+        expect(isRegisteredType('wine-log')).toBe(true);
+        expect(inferDelivery('wine-log')).toBe('project');
+    });
+});
+// ============================================================
+// 6. validateTypeName
+// ============================================================
+describe('validateTypeName', () => {
+    it('accepts valid names', () => {
+        expect(validateTypeName('wine-log')).toBeNull();
+        expect(validateTypeName('ab')).toBeNull();
+        expect(validateTypeName('my-custom-type-123')).toBeNull();
+        expect(validateTypeName('a1')).toBeNull();
+    });
+    it('rejects empty string', () => {
+        expect(validateTypeName('')).toContain('at least 2');
+    });
+    it('rejects single character', () => {
+        expect(validateTypeName('a')).toContain('at least 2');
+    });
+    it('rejects names over 50 characters', () => {
+        const longName = 'a' + '-long'.repeat(10) + '-name';
+        expect(validateTypeName(longName.length > 50 ? longName : 'a'.repeat(51))).toContain('50 characters');
+    });
+    it('rejects uppercase letters', () => {
+        expect(validateTypeName('Wine-Log')).toContain('lowercase');
+    });
+    it('rejects names starting with a number', () => {
+        expect(validateTypeName('1-bad')).toContain('lowercase');
+    });
+    it('rejects special characters', () => {
+        expect(validateTypeName('wine_log')).toContain('lowercase');
+        expect(validateTypeName('wine.log')).toContain('lowercase');
+        expect(validateTypeName('wine log')).toContain('lowercase');
+    });
+    it('rejects consecutive hyphens', () => {
+        expect(validateTypeName('wine--log')).toContain('lowercase');
+    });
+    it('rejects trailing hyphen', () => {
+        expect(validateTypeName('wine-')).toContain('lowercase');
+    });
+});
+// ============================================================
+// 7. checkMetadataCompleteness (dynamic delivery check)
+// ============================================================
+describe('checkMetadataCompleteness', () => {
+    it('returns null when all fields are present for project type', () => {
+        const result = checkMetadataCompleteness({ description: 'test', upsert_key: 'test-key', status: 'active' }, 'architecture-decision');
+        expect(result).toBeNull();
+    });
+    it('returns null when all fields are present for persona type (no status needed)', () => {
+        const result = checkMetadataCompleteness({ description: 'test', upsert_key: 'test-key' }, 'code-craft');
+        expect(result).toBeNull();
+    });
+    it('prompts for status on project-delivery types', () => {
+        const result = checkMetadataCompleteness({ description: 'test', upsert_key: 'test-key' }, 'architecture-decision');
+        expect(result).toContain('status');
+    });
+    it('does NOT prompt for status on persona-delivery types', () => {
+        const result = checkMetadataCompleteness({ description: 'test', upsert_key: 'test-key' }, 'persona-rule');
+        expect(result).toBeNull();
+    });
+    it('uses inferDelivery for custom types — project custom type requires status', () => {
+        setUserTypes({ 'wine-log': 'project' });
+        const result = checkMetadataCompleteness({ description: 'test', upsert_key: 'test-key' }, 'wine-log');
+        expect(result).toContain('status');
+    });
+    it('uses inferDelivery for custom types — knowledge custom type skips status', () => {
+        setUserTypes({ 'recipe': 'knowledge' });
+        const result = checkMetadataCompleteness({ description: 'test', upsert_key: 'test-key' }, 'recipe');
+        expect(result).toBeNull();
+    });
+    it('prompts for missing description and upsert_key', () => {
+        const result = checkMetadataCompleteness({}, 'general');
+        expect(result).toContain('description');
+        expect(result).toContain('upsert_key');
+    });
+});
+// ============================================================
+// 8. Type alias resolution (feedback → general)
+// ============================================================
+describe('type alias resolution', () => {
+    it('feedback resolves to general in inferDelivery', () => {
+        expect(inferDelivery('feedback')).toBe(inferDelivery('general'));
+    });
+    it('feedback is recognized as registered', () => {
+        expect(isRegisteredType('feedback')).toBe(true);
+    });
+    it('unknown aliases pass through unchanged', () => {
+        expect(isRegisteredType('totally-unknown')).toBe(false);
+        expect(inferDelivery('totally-unknown')).toBe('knowledge');
+    });
+});
+// ============================================================
+// 9. Edge cases
+// ============================================================
+describe('edge cases', () => {
+    it('empty config file (no types key) falls back to built-ins', () => {
+        mockConfigState.current = {};
+        const registry = getTypeRegistry();
+        expect(registry).toEqual(BUILTIN_TYPES);
+    });
+    it('config with empty types object works', () => {
+        mockConfigState.current = { types: {} };
+        const registry = getTypeRegistry();
+        expect(registry).toEqual(BUILTIN_TYPES);
+    });
+    it('overriding a built-in then unsetting reverts to default', () => {
+        setUserTypes({ 'code-craft': 'knowledge' });
+        expect(inferDelivery('code-craft')).toBe('knowledge');
+        // Simulate unsetting — remove from user types
+        mockConfigState.current = {};
+        expect(inferDelivery('code-craft')).toBe('persona'); // reverts to built-in
+    });
+    it('registering mid-session is immediately visible', () => {
+        expect(getRegisteredTypes()).not.toContain('wine-log');
+        registerType('wine-log', 'project');
+        expect(getRegisteredTypes()).toContain('wine-log');
+        expect(inferDelivery('wine-log')).toBe('project');
+    });
+});

package/dist/mcp-server.js

@@ -81,12 +81,13 @@ server.tool('delete_note', 'Delete a note from the knowledge base by ID. If the
     const result = await opDeleteNote(clients, id, confirmed);
     return { content: [{ type: 'text', text: result.message }] };
 });
-// Tool: Update metadata only (no content change, no confirmation needed)
-server.tool('update_metadata', 'Update metadata fields on an existing note without changing content. Useful for adding descriptions, tags, project, or scope.', {
+// Tool: Update metadata only (confirmation required for protected notes)
+server.tool('update_metadata', 'Update metadata fields on an existing note without changing content. Useful for adding descriptions, tags, project, or scope. Protected notes (delivery: protected) require confirmed: true.', {
     id: z.coerce.number().describe('The note ID to update'),
     metadata: z.record(z.string(), z.unknown()).describe('Metadata fields to merge (existing fields are preserved unless overwritten)'),
-}, async ({ id, metadata }) => {
-    const result = await opUpdateMetadata(clients, id, metadata);
+    confirmed: z.boolean().default(false).describe('Set to true to confirm update of protected notes. Required when the note has delivery: protected.'),
+}, async ({ id, metadata, confirmed }) => {
+    const result = await opUpdateMetadata(clients, id, metadata, confirmed);
     return { content: [{ type: 'text', text: result.message }] };
 });
 // --- Start ---

package/dist/migrations/migrations/004-upsert-key-unique.sql

@@ -0,0 +1,6 @@
+-- Partial unique index on upsert_key (only where not null)
+-- Using INDEX instead of CONSTRAINT because JSONB->>key expressions
+-- can't be used in ALTER TABLE ADD CONSTRAINT
+CREATE UNIQUE INDEX IF NOT EXISTS uq_upsert_key
+  ON notes ((metadata->>'upsert_key'))
+  WHERE metadata->>'upsert_key' IS NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aperdomoll90/ledger-ai",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "AI identity and memory system — portable persona, knowledge sync, semantic search across agents and devices",
   "type": "module",
   "bin": {