@aperdomoll90/ledger-ai 1.1.1 → 1.1.2

package/README.md

@@ -15,24 +15,26 @@ Requires Node.js 20+.
 ## Quick Start
 
 ```bash
-# 1. Set up credentials and database
+# One command does everything:
 ledger init
+```
 
-# 2. Connect your AI agent
-ledger setup claude    # Claude Code (live sync, MCP, hooks)
-ledger setup openclaw  # OpenClaw (persona files, CLI sync)
-ledger setup chatgpt   # ChatGPT (static system prompt export)
+The init wizard walks you through:
+1. **Credentials** — Supabase + OpenAI keys
+2. **Database** — connect and set up schema
+3. **Device** — name this machine (optional)
+4. **Persona** — profile, communication style, rules
+5. **Platforms** — install Claude Code, OpenClaw, or ChatGPT
+6. **Sync** — pull everything down
+7. **Migrate** — detect stray local files
 
-# 3. Create your persona
-ledger onboard
-```
+Smart step-skipping — re-run anytime, it only does what's needed.
 
-Second device? Same Ledger, same persona:
+### Second device? Same Ledger, same persona:
 
 ```bash
 npm install -g @aperdomoll90/ledger-ai
-ledger init            # connect to existing Supabase project
-ledger setup claude    # pull persona, install hooks
+ledger init    # connect to existing Supabase, pull persona, set up platform
 ```
 
 ## What It Does
@@ -47,19 +49,53 @@ ledger setup claude    # pull persona, install hooks
 
 | Command | Description |
 |---|---|
-| `ledger init` | Set up credentials and database schema |
-| `ledger setup <platform>` | Configure an agent (claude, openclaw, chatgpt) |
-| `ledger onboard` | Create your persona (interactive wizard) |
+| `ledger init` | Guided setup wizard (credentials, persona, platforms, sync) |
+| `ledger setup <platform>` | Configure an agent (claude-code, openclaw, chatgpt) |
+| `ledger onboard` | Create your persona (interactive questionnaire) |
+| `ledger sync` | Bidirectional sync between Ledger and local cache |
 | `ledger pull` | Download notes from Ledger to local cache |
 | `ledger push <file>` | Upload a local file to Ledger |
-| `ledger check` | Compare local files vs Ledger |
+| `ledger check` | Compare local files vs Ledger (dry-run sync) |
 | `ledger show <query>` | Search by meaning, open matching note |
 | `ledger export <query>` | Download a note to any path (untracked) |
 | `ledger ingest [file]` | Add files to Ledger with duplicate detection |
+| `ledger migrate` | Migrate local files to Ledger (backup, compare, merge) |
+| `ledger add` | Add a new note (interactive metadata prompts) |
+| `ledger update <id>` | Update a note by ID |
+| `ledger delete <id>` | Delete a note by ID |
+| `ledger list` | List recent notes |
+| `ledger tag <id>` | Update metadata on a note |
 | `ledger backup` | Backup all notes to ~/.ledger/backups/ |
 | `ledger restore <file>` | Restore from backup |
 | `ledger config list` | View settings |
-| `ledger config set <key> <value>` | Change settings |
+
+## Note Metadata
+
+Every note has structured metadata for organization and discovery:
+
+| Field | Purpose | Example |
+|---|---|---|
+| `type` | Categorization | `feedback`, `user-preference`, `architecture-decision`, `reference` |
+| `upsert_key` | Unique identifier, dedup | `feedback-communication-style`, `ledger-spec-init` |
+| `description` | What the note IS and what it's FOR | `"How to communicate with Adrian"` |
+| `status` | Lifecycle stage | `idea`, `planning`, `active`, `done` |
+| `project` | Which project | `ledger`, `ai-studio` |
+| `delivery` | Sync tier | `persona` (everywhere), `project` (per-repo), `knowledge` (search only) |
+
+### Interactive prompting
+
+When creating notes, Ledger prompts for missing metadata by default — both via MCP (agents) and CLI. This helps keep notes organized without requiring users to memorize the schema.
+
+Skip prompts with `--force` (CLI) or `interactive_skip: true` (MCP). Disable globally: `ledger config set naming.interactive false`.
+
+### Naming enforcement (opt-in)
+
+Enable strict naming validation: `ledger config set naming.enforce true`
+
+Keys follow the pattern `{prefix}-{topic}` or `{project}-{prefix}-{topic}`:
+- `feedback-communication-style`
+- `ledger-spec-init`
+- `user-profile`
 
 ## Stack
 
@@ -77,11 +113,11 @@ Your devices / agents
     v
 ledger CLI ←→ Supabase (Postgres + pgvector)
     |
-    ├── pull: download notes → local cache files + CLAUDE.md
-    ├── push: upload local changes → Ledger (re-embeds)
-    ├── check: compare hashes, detect drift
+    ├── init: guided wizard (credentials → persona → platforms → sync)
+    ├── sync: bidirectional, hash-based conflict detection
     ├── show: semantic search → open in editor
-    └── MCP server: Claude Code talks to Ledger natively
+    ├── add: interactive metadata prompts → duplicate guard → save
+    └── MCP server: Claude Code talks to Ledger natively (6 tools)
 ```
 
 Notes are stored with content + metadata + vector embeddings. Search finds relevant notes by meaning. Sync uses SHA-256 content hashes to detect changes without markers.
@@ -94,6 +130,15 @@ Notes are stored with content + metadata + vector embeddings. Search finds relev
 | OpenClaw | CLI | Bidirectional via `ledger` commands |
 | ChatGPT | None | Static snapshot, re-run to update |
 
+Platform management is built into the wizard — install, reinstall, or uninstall from `ledger init`.
+
+## Development
+
+```bash
+npm run ship       # typecheck → test → commit → push
+npm run release    # version bump → build → test → publish to npm
+```
+
 ## Requirements
 
 - Node.js 20+
@@ -102,9 +147,9 @@ Notes are stored with content + metadata + vector embeddings. Search finds relev
 
 ## Known Limitations
 
-- **Embeddings require OpenAI** — currently uses `text-embedding-3-small` only. Supabase built-in embeddings (free, no API key) and multi-provider support planned for v2.0.
+- **Embeddings require OpenAI** — currently uses `text-embedding-3-small` only. Multi-provider support planned.
 - **Anthropic has no embedding API** — Claude is for text generation. Even Claude users need an OpenAI key for embeddings.
-- **English-optimized** — semantic search works best with English content. Multilingual support depends on the embedding model.
+- **English-optimized** — semantic search works best with English content.
 
 ## Roadmap
 
@@ -113,6 +158,7 @@ Notes are stored with content + metadata + vector embeddings. Search finds relev
 - Soft delete (trash)
 - Multi-format ingest (PDF, Excel, images, audio)
 - Web dashboard
+- Skills system (context-aware convention enforcement)
 - VS Code extension
 
 ## License

package/dist/cli.js

@@ -192,11 +192,13 @@ program
     .command('add')
     .description('Add a new note to Ledger (with duplicate detection)')
     .requiredOption('-c, --content <content>', 'note content (or use stdin)')
-    .requiredOption('-t, --type <type>', 'note type (feedback, reference, event, etc.)')
+    .option('-t, --type <type>', 'note type (feedback, reference, event, etc.)')
     .option('-a, --agent <agent>', 'agent name', 'cli')
     .option('-p, --project <project>', 'project name')
     .option('-k, --upsert-key <key>', 'upsert key for dedup')
-    .option('-f, --force', 'skip duplicate check')
+    .option('-d, --description <text>', 'one-line description of the note')
+    .option('-s, --status <status>', 'note status (idea, planning, active, done)')
+    .option('-f, --force', 'skip duplicate check and interactive prompts')
     .action(async (options) => {
     const config = loadConfig();
     await add(config, options.content, {
@@ -204,6 +206,8 @@ program
         agent: options.agent,
         project: options.project,
         upsertKey: options.upsertKey,
+        description: options.description,
+        status: options.status,
         force: options.force ?? false,
     });
 });

package/dist/commands/add.js

@@ -1,17 +1,71 @@
-import { opAddNote } from '../lib/notes.js';
-import { confirm } from '../lib/prompt.js';
+import { loadConfigFile } from '../lib/config.js';
+import { opAddNote, NOTE_TYPES, NOTE_STATUSES } from '../lib/notes.js';
+import { ask, confirm, choose } from '../lib/prompt.js';
 export async function add(config, content, options) {
+    const configFile = loadConfigFile();
+    const interactive = configFile.naming?.interactive !== false;
+    let type = options.type || '';
     const metadata = {};
     if (options.project)
         metadata.project = options.project;
     if (options.upsertKey)
         metadata.upsert_key = options.upsertKey;
-    const result = await opAddNote({ supabase: config.supabase, openai: config.openai }, content, options.type, options.agent || 'cli', metadata, options.force ?? false);
+    if (options.description)
+        metadata.description = options.description;
+    if (options.status)
+        metadata.status = options.status;
+    // Interactive prompting for missing fields (CLI only)
+    if (interactive && !options.force) {
+        // Type
+        if (!type) {
+            const typeChoice = await choose('What type of note is this?', [
+                ...NOTE_TYPES,
+                'skip — use default (general)',
+            ]);
+            type = typeChoice.startsWith('skip') ? 'general' : typeChoice;
+        }
+        // Description
+        if (!metadata.description) {
+            const desc = await ask('One-line description (what is this note for?): ');
+            if (desc)
+                metadata.description = desc;
+        }
+        // upsert_key
+        if (!metadata.upsert_key) {
+            const key = await ask('Unique key for this note (lowercase-hyphenated, or Enter to auto-generate): ');
+            if (key)
+                metadata.upsert_key = key;
+        }
+        // Project
+        if (!metadata.project) {
+            const proj = await ask('Project name (or Enter to skip): ');
+            if (proj)
+                metadata.project = proj;
+        }
+        // Status (only for project-scoped types)
+        const projectTypes = ['architecture-decision', 'project-status', 'event', 'error'];
+        if (projectTypes.includes(type) && !metadata.status) {
+            const statusChoice = await choose('What stage is this?', [
+                ...NOTE_STATUSES,
+                'skip — no status',
+            ]);
+            if (!statusChoice.startsWith('skip')) {
+                metadata.status = statusChoice;
+            }
+        }
+    }
+    // Default type if still empty
+    if (!type)
+        type = 'general';
+    // Mark as having gone through interactive (or skipped it)
+    // so opAddNote doesn't re-prompt via MCP confirm flow
+    metadata.interactive_skip = true;
+    const result = await opAddNote({ supabase: config.supabase, openai: config.openai }, content, type, options.agent || 'cli', metadata, options.force ?? false);
     if (result.status === 'confirm') {
         console.error(result.message);
         const proceed = await confirm('\nCreate new note anyway?');
         if (proceed) {
-            const forced = await opAddNote({ supabase: config.supabase, openai: config.openai }, content, options.type, options.agent || 'cli', metadata, true);
+            const forced = await opAddNote({ supabase: config.supabase, openai: config.openai }, content, type, options.agent || 'cli', { ...metadata, interactive_skip: true }, true);
             console.error(forced.message);
         }
         else {

package/dist/commands/onboard.js

@@ -34,22 +34,25 @@ const DEFAULT_SECURITY_RULES = `- Never read .env files or any files containing
 const DEFAULT_KNOWLEDGE_RULES = `- Ledger is the source of truth for all knowledge
 - Local files are cache — update Ledger first, then local
 - Use ledger CLI for syncing between Ledger and local files`;
-// --- Onboard ---
-export async function onboard(config) {
+export async function onboard(config, options = {}) {
     const envPath = resolve(getLedgerDir(), '.env');
     if (!existsSync(envPath)) {
         console.error('Ledger not initialized. Run `ledger init` first.');
         process.exit(1);
     }
-    // Check if persona already exists
-    const existing = await fetchPersonaNotes(config.supabase);
-    const hasProfile = existing.some(n => n.metadata.type === 'user-preference');
-    const hasFeedback = existing.some(n => n.metadata.type === 'feedback');
-    if (hasProfile || hasFeedback) {
-        const proceed = await confirm('Persona notes already exist in Ledger. Run onboarding again? (will add, not replace)');
-        if (!proceed) {
-            console.error('Cancelled.');
-            return;
+    // Check if persona already exists (skip when called from wizard, which handles this itself)
+    if (!options.skipExistingCheck) {
+        const existing = await fetchPersonaNotes(config.supabase);
+        const hasProfile = existing.some(n => n.metadata.type === 'user-preference');
+        const hasFeedback = existing.some(n => n.metadata.type === 'feedback');
+        if (hasProfile || hasFeedback) {
+            console.error('You already have persona notes in Ledger (profile, communication style, etc.).');
+            console.error('Running onboarding again will create new notes for any missing fields — existing ones are kept as-is.\n');
+            const proceed = await confirm('Continue?');
+            if (!proceed) {
+                console.error('Cancelled.');
+                return;
+            }
         }
     }
     console.error('\nLet\'s set up your AI persona.\n');

package/dist/commands/wizard.js

@@ -91,12 +91,12 @@ export async function wizard() {
         console.error(`Step 4: Persona: found\n`);
         const update = await confirm('  Update persona?');
         if (update) {
-            await onboard(config);
+            await onboard(config, { skipExistingCheck: true });
         }
     }
     else {
         console.error('Step 4: Build persona\n');
-        await runSkippable('Persona', () => onboard(config));
+        await runSkippable('Persona', () => onboard(config, { skipExistingCheck: true }));
     }
     // Step 5: Platforms
     console.error('Step 5: Platform setup\n');

package/dist/lib/notes.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'crypto';
 import { fatal, ExitCode } from './errors.js';
 import { contentHash } from './hash.js';
+import { loadConfigFile } from './config.js';
 const DELIVERY_BY_TYPE = {
     'user-preference': 'persona',
     'feedback': 'persona',
@@ -158,6 +159,116 @@ function formatNotePreview(id, meta, content, maxLen = 300) {
     const descLine = desc ? `\nDescription: ${desc}` : '';
     return `"${label}" (id: ${id}) | type: ${noteType || '-'} | project: ${project || '-'}${descLine}\n  ${preview}${truncated}`;
 }
+// --- Naming Conventions ---
+/** Valid type prefixes for upsert_key naming. */
+const TYPE_PREFIXES = {
+    'feedback': ['feedback'],
+    'user-preference': ['user'],
+    'architecture-decision': ['spec', 'architecture'],
+    'project-status': ['project-status'],
+    'reference': ['reference'],
+    'event': ['devlog', 'event'],
+    'error': ['errorlog', 'error'],
+    'general': ['general'],
+};
+/**
+ * Validate upsert_key format: {prefix}-{topic} or {project}-{prefix}-{topic}
+ * Returns null if valid, error message if invalid.
+ */
+export function validateNaming(upsertKey, type, description) {
+    if (!upsertKey) {
+        return 'upsert_key is required when naming enforcement is enabled.';
+    }
+    if (!description) {
+        return 'description is required when naming enforcement is enabled. Add a one-line description of what this note IS and what it\'s FOR.';
+    }
+    // Check format: lowercase, hyphens, no underscores or special chars
+    if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(upsertKey)) {
+        return `Invalid upsert_key format "${upsertKey}". Use lowercase-hyphenated (e.g., "feedback-communication-style").`;
+    }
+    // Check that the key contains a valid prefix for this type
+    const validPrefixes = TYPE_PREFIXES[type];
+    if (validPrefixes) {
+        const parts = upsertKey.split('-');
+        // Match prefix at start, or after a project name segment
+        const hasValidPrefix = validPrefixes.some(prefix => {
+            const prefixParts = prefix.split('-');
+            // Direct match: prefix-topic
+            if (parts.slice(0, prefixParts.length).join('-') === prefix)
+                return true;
+            // Project-scoped: project-prefix or project-prefix-topic
+            if (parts.length >= prefixParts.length + 1) {
+                const afterProject = parts.slice(1, 1 + prefixParts.length).join('-');
+                if (afterProject === prefix)
+                    return true;
+            }
+            return false;
+        });
+        if (!hasValidPrefix) {
+            return `upsert_key "${upsertKey}" doesn't match type "${type}". Expected prefix: ${validPrefixes.join(' or ')}. Examples: "${validPrefixes[0]}-my-topic" or "myproject-${validPrefixes[0]}-my-topic".`;
+        }
+    }
+    return null;
+}
+/** Derive local_file from upsert_key: feedback-style → feedback_style.md */
+export function deriveLocalFile(upsertKey) {
+    return upsertKey.replace(/-/g, '_') + '.md';
+}
+/** Check if naming enforcement is enabled in config. */
+function isNamingEnforced() {
+    const config = loadConfigFile();
+    return config.naming?.enforce === true;
+}
+/** Check if interactive metadata prompting is enabled (default: true). */
+function isInteractive() {
+    const config = loadConfigFile();
+    return config.naming?.interactive !== false;
+}
+/** Valid note types for the interactive prompt. */
+export const NOTE_TYPES = [
+    'user-preference',
+    'feedback',
+    'architecture-decision',
+    'project-status',
+    'reference',
+    'event',
+    'error',
+    'knowledge-guide',
+    'general',
+];
+/** Valid statuses for notes. */
+export const NOTE_STATUSES = ['idea', 'planning', 'active', 'done'];
+/**
+ * Check if metadata is complete enough to skip interactive prompting.
+ * Returns null if complete, or a structured prompt message if fields are missing.
+ */
+export function checkMetadataCompleteness(metadata, type) {
+    const missing = [];
+    if (!metadata.description) {
+        missing.push('description');
+    }
+    if (!metadata.upsert_key) {
+        missing.push('upsert_key');
+    }
+    // Only ask for status on project-scoped types
+    const projectTypes = ['architecture-decision', 'project-status', 'event', 'error'];
+    if (projectTypes.includes(type) && !metadata.status) {
+        missing.push('status');
+    }
+    if (missing.length === 0)
+        return null;
+    const fields = [];
+    if (missing.includes('description')) {
+        fields.push('- **description**: One line explaining what this note IS and what it\'s FOR');
+    }
+    if (missing.includes('upsert_key')) {
+        fields.push('- **upsert_key**: A unique identifier for this note (lowercase-hyphenated, e.g., "feedback-my-rule" or "myproject-spec-feature")');
+    }
+    if (missing.includes('status')) {
+        fields.push('- **status**: What stage is this? Options: idea, planning, active, done');
+    }
+    return `METADATA NEEDED — ask the user for these fields before saving:\n\n${fields.join('\n')}\n\nIf the user wants to skip, re-call add_note with metadata field \`interactive_skip: true\` to use defaults.`;
+}
 // --- Shared Operations (called by both MCP and CLI) ---
 export async function opSearchNotes(clients, query, threshold, limit, type, project) {
     const embedding = await getEmbedding(clients.openai, query);
@@ -257,8 +368,34 @@ export async function opListNotes(clients, limit, type, project) {
     return { status: 'ok', message: formatted };
 }
 export async function opAddNote(clients, content, type, agent, metadata, force) {
-    const fullMetadata = { ...metadata, type, agent, content_hash: contentHash(content) };
     const upsertKey = metadata.upsert_key;
+    const description = metadata.description;
+    const skippedInteractive = metadata.interactive_skip === true;
+    // Interactive metadata prompting (default: on, opt-out via config)
+    // Skip if user explicitly opted out via interactive_skip flag
+    if (!skippedInteractive && isInteractive()) {
+        const prompt = checkMetadataCompleteness(metadata, type);
+        if (prompt) {
+            return { status: 'confirm', message: prompt };
+        }
+    }
+    // Clean up the skip flag before saving
+    delete metadata.interactive_skip;
+    // Naming enforcement (opt-in via config)
+    if (isNamingEnforced()) {
+        const namingError = validateNaming(upsertKey || '', type, description);
+        if (namingError) {
+            return { status: 'error', message: `Naming violation: ${namingError}` };
+        }
+    }
+    // Auto-derive local_file from upsert_key for persona notes
+    if (upsertKey && !metadata.local_file) {
+        const delivery = metadata.delivery || inferDelivery(type);
+        if (delivery === 'persona') {
+            metadata.local_file = deriveLocalFile(upsertKey);
+        }
+    }
+    const fullMetadata = { ...metadata, type, agent, content_hash: contentHash(content) };
     // Duplicate guard: if no upsert_key and not forced, check for similar notes
     if (!upsertKey && !force) {
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aperdomoll90/ledger-ai",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "AI identity and memory system — portable persona, knowledge sync, semantic search across agents and devices",
   "type": "module",
   "bin": {
@@ -18,7 +18,10 @@
     "prepublishOnly": "npm run build && npm test",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "preversion": "npm run typecheck && npm test",
+    "ship": "bash scripts/ship.sh",
+    "release": "npm version patch && npm publish --access public"
   },
   "keywords": [
     "ai",