@tonycasey/lisa 0.5.13

package/dist/templates/agents/docs/STORAGE_SETUP.md

@@ -0,0 +1,161 @@
+# Storage Setup Guide
+
+## Overview
+
+Lisa uses a graph database (Neo4j) to store persistent memory. This enables Lisa to remember context across sessions, track project history, and provide intelligent assistance based on past interactions.
+
+There are three storage options available:
+
+| Option | Best For | Requirements |
+|--------|----------|--------------|
+| **Local Docker** | Development, testing | Docker Desktop |
+| **Zep Cloud** | Managed service, easiest setup | Zep Cloud account |
+
+---
+
+## Option 1: Local Docker (Recommended for Development)
+
+Run Neo4j and the Zep (Graphiti) MCP server locally using Docker.
+
+### Prerequisites
+- Docker Desktop installed and running
+- At least 4GB RAM available for containers
+
+### Setup Steps
+
+1. **Initialize with local mode:**
+   ```bash
+   lisa init --mode local
+   ```
+
+2. **Start the services:**
+   ```bash
+   lisa up
+   ```
+
+3. **Verify the connection:**
+   ```bash
+   lisa doctor
+   ```
+
+### What Gets Started
+- **Neo4j** - Graph database on port 7474 (browser) and 7687 (bolt)
+- **MCP Server** - Memory API on port 8010
+
+### Stopping Services
+```bash
+lisa down
+```
+---
+
+## Option 2: Zep Cloud (Fully Managed)
+
+Use Zep's managed service for production.
+
+### Prerequisites
+- Zep Cloud account (sign up at [getzep.com](https://getzep.com))
+
+### Setup Steps
+
+1. **Create a Zep project:**
+   - Go to [cloud.getzep.com](https://cloud.getzep.com)
+   - Create a new project
+   - Copy your API key (starts with `z_`)
+
+2. **Initialize with zep-cloud mode:**
+   ```bash
+   lisa init --mode zep-cloud
+   ```
+
+3. **Enter Zep API key when prompted**
+
+4. **Verify the connection:**
+   ```bash
+   lisa doctor
+   ```
+
+### How It Works
+- **No Docker required** - Lisa connects directly to Zep's REST API
+- **No MCP server** - Uses Zep's native `/api/v2` endpoints
+- **Free tier** - 1,000 episodes/month, unlimited storage
+
+---
+
+## Manual Configuration
+
+If you chose "Set up later" during initialization, follow these steps:
+
+1. **Edit the environment file:**
+   ```bash
+   nano .agents/.env
+   ```
+
+2. **Uncomment and configure your chosen option:**
+
+   **For Local Docker:**
+   ```env
+   STORAGE_MODE=local
+   GRAPHITI_ENDPOINT=http://localhost:8010/mcp/
+   GRAPHITI_GROUP_ID=your-project-name
+   ```
+
+    **For Zep Cloud:**
+   ```env
+   STORAGE_MODE=zep-cloud
+   GRAPHITI_GROUP_ID=your-project-name
+   ZEP_API_KEY=z_xxxxx
+   ```
+   Note: No endpoint needed - Lisa uses Zep's native REST API directly.
+
+3. **Start a new terminal session** (to load new environment variables)
+
+4. **Run `lisa doctor`** to verify the connection
+
+---
+
+## Environment Variables Reference
+
+| Variable | Mode | Description |
+|----------|------|-------------|
+| `STORAGE_MODE` | all | Storage mode: `local`, `zep-cloud`, or `skip` |
+| `GRAPHITI_ENDPOINT` | local | MCP server endpoint URL (not needed for zep-cloud) |
+| `GRAPHITI_GROUP_ID` | all | Memory group identifier (usually project name) |
+| `ZEP_API_KEY` | zep-cloud | Zep Cloud API key (starts with `z_`) |
+
+---
+
+## Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `lisa init` | Initialize Lisa in a project |
+| `lisa up` | Start local Docker services |
+| `lisa down` | Stop local Docker services |
+| `lisa doctor` | Check storage connection status |
+
+---
+
+## Troubleshooting
+
+### `lisa doctor` shows "Docker missing or not running"
+- Ensure Docker Desktop is installed and running
+- On macOS: Check the Docker icon in the menu bar
+- On Linux: Run `sudo systemctl start docker`
+
+### "MCP check failed" error
+- Verify the endpoint URL is correct
+- For local mode: Ensure `lisa up` has been run
+- Check that port 8010 is not blocked by firewall
+
+### "Invalid API key" (Zep Cloud)
+- Verify the API key is correct
+- Check the project ID matches your Zep project
+- Ensure your Zep account is active
+
+---
+
+## Getting Help
+
+- Run `lisa --help` for command options
+- Check [github.com/TonyCasey/lisa](https://github.com/TonyCasey/lisa) for updates
+- Report issues at the GitHub repository

package/dist/templates/agents/skills/common/group-id.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Group ID Utilities
+ *
+ * Shared functions for normalizing paths to Graphiti group IDs.
+ * Used by memory, tasks, prompt, and other skills.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFIX_MAP = exports.TYPE_MAP = exports.MAX_GROUP_ID_LENGTH = void 0;
+exports.normalizePathToGroupId = normalizePathToGroupId;
+exports.getCurrentGroupId = getCurrentGroupId;
+exports.isWindows = isWindows;
+exports.getRootBoundary = getRootBoundary;
+exports.getHierarchicalGroupIds = getHierarchicalGroupIds;
+exports.detectPrefixTag = detectPrefixTag;
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+exports.MAX_GROUP_ID_LENGTH = 128;
+/**
+ * Normalize a path to a valid group ID string.
+ * Works cross-platform (Windows and Unix).
+ *
+ * @example
+ * normalizePathToGroupId('/Users/tony.casey/Repos/api') // 'users-tony_casey-repos-api'
+ * normalizePathToGroupId('C:\\dev\\lisa') // 'c-dev-lisa'
+ */
+function normalizePathToGroupId(absolutePath) {
+    let normalized = absolutePath
+        .toLowerCase()
+        .replace(/^[a-z]:/i, (match) => match.charAt(0)) // C: -> c
+        .replace(/^\//, '') // Remove leading slash (Unix)
+        .replace(/\\/g, '-') // Backslash to dash (Windows)
+        .replace(/\//g, '-') // Forward slash to dash (Unix)
+        .replace(/\./g, '_') // Dots to underscores
+        .replace(/^-+/, '') // Remove leading dashes
+        .replace(/-+/g, '-'); // Collapse multiple dashes
+    if (normalized.length > exports.MAX_GROUP_ID_LENGTH) {
+        normalized = normalized.slice(-exports.MAX_GROUP_ID_LENGTH);
+    }
+    return normalized;
+}
+/**
+ * Get the current folder's group ID.
+ */
+function getCurrentGroupId(cwd = process.cwd()) {
+    return normalizePathToGroupId(cwd);
+}
+/**
+ * Check if we're on Windows
+ */
+function isWindows() {
+    return os.platform() === 'win32';
+}
+/**
+ * Get the root boundary for hierarchical traversal.
+ * - Windows: drive root (e.g., C:\) or home directory, whichever is deeper
+ * - Unix: home directory or /
+ */
+function getRootBoundary(cwd = process.cwd()) {
+    const homeDir = os.homedir();
+    if (isWindows()) {
+        // On Windows, check if cwd is under home directory
+        const cwdLower = cwd.toLowerCase();
+        const homeLower = homeDir.toLowerCase();
+        if (cwdLower.startsWith(homeLower)) {
+            return homeDir; // Under home, use home as boundary
+        }
+        // Not under home (e.g., C:\dev\), use drive root as boundary
+        const driveRoot = path.parse(cwd).root; // e.g., "C:\"
+        return driveRoot;
+    }
+    // Unix: use home directory if under it, otherwise use /
+    if (cwd.startsWith(homeDir)) {
+        return homeDir;
+    }
+    return '/';
+}
+/**
+ * Get hierarchical group IDs from current folder up to root boundary.
+ * Returns array ordered from most specific (current) to least specific (root).
+ * Works cross-platform (Windows and Unix).
+ */
+function getHierarchicalGroupIds(cwd = process.cwd()) {
+    const rootBoundary = getRootBoundary(cwd);
+    const groups = [];
+    let currentPath = path.resolve(cwd);
+    const maxDepth = 10; // Safety limit
+    let depth = 0;
+    while (depth < maxDepth) {
+        groups.push(normalizePathToGroupId(currentPath));
+        // Stop if we've reached the root boundary
+        if (currentPath.toLowerCase() === rootBoundary.toLowerCase()) {
+            break;
+        }
+        const parentPath = path.dirname(currentPath);
+        // Stop if we can't go up anymore (reached filesystem root)
+        if (parentPath === currentPath) {
+            break;
+        }
+        currentPath = parentPath;
+        depth++;
+    }
+    return groups;
+}
+/**
+ * Entity type to tag mapping for memory classification.
+ */
+exports.TYPE_MAP = {
+    // Code & Architecture
+    'decision': 'code:decision',
+    'pattern': 'code:pattern',
+    'dependency': 'code:dependency',
+    'tech-debt': 'code:tech-debt',
+    // Context & History
+    'bug': 'context:bug',
+    'rationale': 'context:rationale',
+    'failed': 'context:failed',
+    'quirk': 'context:quirk',
+    // External
+    'feedback': 'external:feedback',
+    'incident': 'external:incident',
+    'contract': 'external:contract',
+    // People & Process
+    'contributor': 'people:contributor',
+    'review': 'people:review',
+    'blocker': 'people:blocker',
+    'estimate': 'people:estimate',
+    // Project
+    'scope-in': 'project:scope-in',
+    'scope-out': 'project:scope-out',
+    'milestone': 'project:milestone',
+    'init-review': 'type:init-review',
+};
+/**
+ * Auto-detect prefixes in text for automatic tagging.
+ */
+exports.PREFIX_MAP = {
+    'DECISION:': 'code:decision',
+    'PATTERN:': 'code:pattern',
+    'TECH-DEBT:': 'code:tech-debt',
+    'BUG:': 'context:bug',
+    'RATIONALE:': 'context:rationale',
+    'FAILED:': 'context:failed',
+    'INCIDENT:': 'external:incident',
+    'BLOCKER:': 'people:blocker',
+    'SCOPE-IN:': 'project:scope-in',
+    'SCOPE-OUT:': 'project:scope-out',
+    'INIT-REVIEW:': 'type:init-review',
+};
+/**
+ * Detect tag from text prefix.
+ */
+function detectPrefixTag(text) {
+    for (const [prefix, tag] of Object.entries(exports.PREFIX_MAP)) {
+        if (text.toUpperCase().startsWith(prefix)) {
+            return tag;
+        }
+    }
+    return null;
+}

package/dist/templates/agents/skills/init-review/SKILL.md

@@ -0,0 +1,119 @@
+# Init Review Skill
+
+## Purpose
+Automatically analyzes a codebase when Lisa is installed, creating a foundational memory of the project structure, technologies, and patterns. This init review serves as context for all future Claude sessions.
+
+## Triggers
+Use when the user says things like:
+- "run init review"
+- "analyze this codebase"
+- "scan the project"
+- "what is this project about"
+- "refresh codebase summary"
+
+## How to use
+
+### Automatic (during npm install)
+The init review runs automatically when Lisa is installed via `npm install @tonycasey/lisa`. It:
+1. Detects if the folder is a codebase
+2. Runs static analysis (language, framework, structure)
+3. Stores result as first memory
+4. Queues background AI enrichment
+
+### Manual commands
+```bash
+# Run init review (or re-run with --force)
+node scripts/init-review.js run [--force]
+
+# Show current init review
+node scripts/init-review.js show
+
+# Check status (done, enriched, etc.)
+node scripts/init-review.js status
+```
+
+## I/O contract
+
+### Static analysis output
+```json
+{
+  "status": "ok",
+  "action": "run",
+  "result": {
+    "version": "1.0",
+    "project": { "name": "lisa", "path": "/dev/lisa", "groupId": "dev-lisa" },
+    "codebase": {
+      "language": "TypeScript",
+      "languages": ["TypeScript", "JavaScript"],
+      "framework": null,
+      "buildTools": ["npm", "tsc"]
+    },
+    "structure": {
+      "entryPoints": ["src/cli.ts", "src/index.ts"],
+      "mainModules": ["src/domain/", "src/infrastructure/"],
+      "testDirs": ["tests/"]
+    },
+    "dependencies": {
+      "count": 12,
+      "noteworthy": ["commander", "fs-extra", "@anthropic-ai/claude-code"]
+    },
+    "patterns": {
+      "architecture": "clean-architecture",
+      "testing": "node-test"
+    },
+    "metrics": {
+      "fileCount": 45,
+      "hasTests": true,
+      "hasDocumentation": true
+    }
+  },
+  "summary": "TypeScript CLI project with clean-architecture pattern..."
+}
+```
+
+### Show output
+```json
+{
+  "status": "ok",
+  "action": "show",
+  "review": "TypeScript CLI project with clean-architecture pattern...",
+  "enriched": true,
+  "timestamp": "2026-01-11T15:30:00Z"
+}
+```
+
+### Status output
+```json
+{
+  "status": "ok",
+  "action": "status",
+  "done": true,
+  "enriched": true,
+  "timestamp": "2026-01-11T15:30:00Z",
+  "groupId": "dev-lisa"
+}
+```
+
+## Memory storage
+
+Init reviews are stored with these tags:
+- `type:init-review` - Identifies as init review memory
+- `scope:codebase` - Full codebase analysis
+- `ai:enriched` - Present if AI enrichment completed
+
+## Marker file
+
+Location: `.agents/.init-review-done`
+
+Prevents re-running on subsequent installs. Delete to force re-run, or use `--force` flag.
+
+## Cross-model checklist
+- Codex: Use explicit script paths; verify triggers match
+- Claude: Keep output concise; shown in session-start context
+- Gemini: Explicit commands; avoid model-specific tokens
+
+## Notes
+- Static analysis targets <2 seconds execution
+- AI enrichment runs in background (30-60 seconds)
+- Logs written to `.agents/.init-review.log`
+- Never blocks npm install - errors are caught and logged