cognova 0.1.0

package/Claude/rules/markdown.md

@@ -0,0 +1,43 @@
+# Markdown Formatting
+
+## Headers
+
+Use headers hierarchically:
+- `#` for document title (one per file)
+- `##` for major sections
+- `###` for subsections
+
+## Lists
+
+- Use `-` for unordered lists
+- Use `1.` for ordered/sequential steps
+- Use `- [ ]` for action items within notes
+
+## Links
+
+Prefer wiki-style links for internal references:
+```markdown
+See [[project-name]] for details
+Related: [[topic/subtopic]]
+```
+
+Use standard markdown for external links:
+```markdown
+[Display Text](https://example.com)
+```
+
+## Code
+
+Use fenced code blocks with language identifiers:
+```markdown
+```python
+def example():
+    pass
+```
+```
+
+## Emphasis
+
+- `**bold**` for important terms
+- `*italic*` for emphasis or book/article titles
+- `==highlight==` for key takeaways (if supported)

package/Claude/rules/note-organization.md

@@ -0,0 +1,33 @@
+# Note Organization
+
+## File Naming
+
+Use lowercase with hyphens:
+- `project-ideas.md` not `Project Ideas.md`
+- `meeting-notes-2024-01.md` for dated content
+
+## Folder Structure
+
+Organize by topic or area of responsibility:
+```
+vault/
+├── projects/       # Active projects
+├── areas/          # Ongoing responsibilities
+├── resources/      # Reference material
+├── archive/        # Completed/inactive
+└── inbox/          # Uncategorized captures
+```
+
+## When Creating Notes
+
+1. Check if a related note already exists
+2. Place in appropriate folder
+3. Add frontmatter with required fields
+4. Link to related notes
+
+## When to Split Notes
+
+Split a note when:
+- It exceeds ~500 lines
+- It covers multiple distinct topics
+- Sections could be referenced independently

package/Claude/settings.json

@@ -0,0 +1,54 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {"type": "command", "command": "python3 ~/.claude/hooks/session-start.py"}
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {"type": "command", "command": "python3 ~/.claude/hooks/pre-compact.py"}
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {"type": "command", "command": "python3 ~/.claude/hooks/stop-extract.py", "timeout": 60000}
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {"type": "command", "command": "python3 ~/.claude/hooks/session-end.py"}
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|NotebookEdit",
+        "hooks": [
+          {"type": "command", "command": "python3 ~/.claude/hooks/log-event.py PreToolUse"}
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {"type": "command", "command": "python3 ~/.claude/hooks/log-event.py PreToolUse"}
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {"type": "command", "command": "python3 ~/.claude/hooks/log-event.py PostToolUse"}
+        ]
+      }
+    ]
+  }
+}

package/Claude/skills/README.md

@@ -0,0 +1,136 @@
+# Cognova Skills
+
+Built-in Claude Code skills for Cognova task and project management.
+
+## Available Skills
+
+| Skill | Command | Description |
+|-------|---------|-------------|
+| Task | `/task` | Create, list, update, complete tasks |
+| Project | `/project` | Manage projects with duplicate prevention |
+| Skill Creator | `/skill-creator` | Assists in creating new Claude Code skills |
+
+## Usage
+
+### In Container (Production)
+
+Skills are automatically available when running Cognova in Docker:
+
+```bash
+docker compose up -d
+docker exec -it cognova claude
+
+# Inside Claude Code:
+> /task list
+> /project search homelab
+```
+
+### Local Development
+
+Run skills directly with Python:
+
+```bash
+# Ensure dev server is running
+pnpm dev
+
+# Test task skill (from project root)
+python3 Claude/skills/task/task.py list
+python3 Claude/skills/task/task.py create "Test task" --priority 2
+
+# Test project skill
+python3 Claude/skills/project/project.py list
+python3 Claude/skills/project/project.py search "home"
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `COGNOVA_API_URL` | `http://localhost:3000` | API base URL |
+
+## Directory Structure
+
+```
+Claude/
+├── CLAUDE.md              # Default project instructions
+├── rules/                 # Documentation standards
+│   ├── markdown.md        # Formatting conventions
+│   ├── note-organization.md  # File/folder structure
+│   └── frontmatter.md     # Required metadata
+└── skills/
+    ├── _lib/              # Shared Python utilities
+    │   ├── api.py         # HTTP client
+    │   └── output.py      # Output formatting
+    ├── task/              # Task management skill
+    ├── project/           # Project management skill
+    └── skill-creator/     # Skill authoring assistant
+```
+
+## Creating New Skills
+
+Use the Skill Creator skill or follow these patterns:
+
+### Pure Instruction Skill
+
+For simple workflows where Claude uses existing tools:
+
+```
+skills/my-skill/
+└── SKILL.md
+```
+
+### Python Script Skill
+
+For complex operations requiring API calls:
+
+```
+skills/my-skill/
+├── SKILL.md
+└── my_skill.py
+```
+
+### SKILL.md Template
+
+```yaml
+---
+name: my-skill
+description: When Claude should use this skill
+allowed-tools: Bash, Read
+---
+
+# My Skill
+
+Instructions for Claude to follow...
+
+## Commands
+
+\`\`\`bash
+python3 .claude/skills/my-skill/my_skill.py <command> [options]
+\`\`\`
+```
+
+## Shared Library
+
+Skills can import from `_lib/`:
+
+```python
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent / '_lib'))
+
+from api import get, post, put, delete
+from output import success, error, format_task
+```
+
+## Docker Integration
+
+The `Claude/` folder is copied to `/home/node/.claude/` during Docker build:
+
+```dockerfile
+# From Dockerfile
+RUN mkdir -p /home/node/.claude && \
+    cp -r /app/Claude/* /home/node/.claude/ && \
+    chown -R node:node /home/node/.claude
+```
+
+This makes skills available as `/task`, `/project`, etc. when running Claude Code inside the container.

package/Claude/skills/_lib/__init__.py

@@ -0,0 +1 @@
+# Cognova Skills Library

package/Claude/skills/_lib/api.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+Cognova API Client
+
+Provides consistent API access for all built-in skills.
+Uses curl subprocess to avoid pip dependencies.
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+API_BASE = os.environ.get('COGNOVA_API_URL', 'http://localhost:3000')
+
+
+def _get_api_token() -> str:
+    """Get API token from environment or .api-token file."""
+    # Check environment variable first
+    token = os.environ.get('COGNOVA_API_TOKEN', '')
+    if token:
+        return token
+
+    # Try to read from .api-token file - check multiple locations
+    # to handle bare-metal, Docker, and local dev environments
+    possible_paths = [
+        # Bare-metal: project dir from environment (set by PM2/settings.json)
+        Path(os.environ.get('COGNOVA_PROJECT_DIR', '')) / '.api-token',
+        # Docker: app is at /home/node/app, skills at /home/node/.claude/skills
+        Path('/home/node/app/.api-token'),
+        # Local dev: navigate from _lib -> skills -> Claude -> project root
+        Path(__file__).parent.parent.parent.parent / '.api-token',
+        # Current working directory
+        Path.cwd() / '.api-token',
+    ]
+
+    for token_file in possible_paths:
+        if token_file.exists():
+            try:
+                return token_file.read_text().strip()
+            except Exception:
+                pass
+
+    return ''
+
+
+# Get token at module load time
+API_TOKEN = _get_api_token()
+
+# Debug: warn if no token found
+if not API_TOKEN and os.environ.get('DEBUG'):
+    print(f"[api.py] Warning: No API token found", file=sys.stderr)
+    print(f"[api.py] Env COGNOVA_API_TOKEN: {bool(os.environ.get('COGNOVA_API_TOKEN'))}", file=sys.stderr)
+    print(f"[api.py] Checked paths: {[str(p) for p in [Path('/home/node/app/.api-token'), Path(__file__).parent.parent.parent.parent / '.api-token', Path.cwd() / '.api-token']]}", file=sys.stderr)
+
+
+def api_request(
+    method: str,
+    endpoint: str,
+    data: dict | None = None,
+    params: dict | None = None
+) -> tuple[bool, Any]:
+    """
+    Make an API request to Cognova.
+
+    Args:
+        method: HTTP method (GET, POST, PUT, DELETE)
+        endpoint: API endpoint (e.g., '/tasks')
+        data: Request body for POST/PUT
+        params: Query parameters
+
+    Returns:
+        Tuple of (success: bool, data | error_message)
+    """
+    url = f"{API_BASE}/api{endpoint}"
+
+    cmd = ["curl", "-sL", "-X", method]
+    cmd.extend(["-H", "Content-Type: application/json"])
+
+    # Add API token for authentication if available
+    if API_TOKEN:
+        cmd.extend(["-H", f"X-API-Token: {API_TOKEN}"])
+
+    if params:
+        query_parts = []
+        for k, v in params.items():
+            if v is not None:
+                if isinstance(v, list):
+                    for item in v:
+                        query_parts.append(f"{k}={item}")
+                else:
+                    query_parts.append(f"{k}={v}")
+        if query_parts:
+            url = f"{url}?{'&'.join(query_parts)}"
+
+    if data and method in ("POST", "PUT"):
+        cmd.extend(["-d", json.dumps(data)])
+
+    cmd.append(url)
+
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+        if result.returncode != 0:
+            return False, f"Request failed: {result.stderr}"
+
+        if not result.stdout.strip():
+            return False, "Empty response from server"
+
+        response = json.loads(result.stdout)
+        if response.get("error"):
+            # API returns {error: true, message: "..."} on error
+            return False, response.get("message", response.get("statusMessage", "Unknown error"))
+
+        return True, response.get("data", response)
+    except json.JSONDecodeError:
+        return False, f"Invalid JSON response: {result.stdout[:100]}"
+    except subprocess.TimeoutExpired:
+        return False, "Request timed out"
+    except Exception as e:
+        return False, str(e)
+
+
+def get(endpoint: str, params: dict | None = None) -> tuple[bool, Any]:
+    """GET request helper."""
+    return api_request("GET", endpoint, params=params)
+
+
+def post(endpoint: str, data: dict) -> tuple[bool, Any]:
+    """POST request helper."""
+    return api_request("POST", endpoint, data=data)
+
+
+def put(endpoint: str, data: dict) -> tuple[bool, Any]:
+    """PUT request helper."""
+    return api_request("PUT", endpoint, data=data)
+
+
+def delete(endpoint: str) -> tuple[bool, Any]:
+    """DELETE request helper."""
+    return api_request("DELETE", endpoint)
+
+
+def get_secret(key: str) -> tuple[bool, str]:
+    """
+    Fetch a decrypted secret by key.
+
+    Args:
+        key: The secret key (e.g., "GOOGLE_API_KEY")
+
+    Returns:
+        Tuple of (success: bool, value | error_message)
+
+    Example:
+        success, api_key = get_secret("GOOGLE_API_KEY")
+        if not success:
+            print(f"Error: {api_key}")
+            sys.exit(1)
+    """
+    success, data = get(f"/secrets/{key}")
+    if success and isinstance(data, dict):
+        return True, data.get("value", "")
+    return False, data if isinstance(data, str) else "Secret not found"

package/Claude/skills/_lib/output.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""
+Output formatting for Claude Code skills.
+
+Provides consistent, Claude-friendly output formatting.
+"""
+
+import sys
+from typing import Any
+
+
+def success(message: str, data: Any = None) -> None:
+    """Print success message with optional data."""
+    print(f"SUCCESS: {message}")
+    if data:
+        print(f"\n{format_data(data)}")
+
+
+def error(message: str) -> None:
+    """Print error message to stderr."""
+    print(f"ERROR: {message}", file=sys.stderr)
+
+
+def info(message: str) -> None:
+    """Print info message to stderr (not captured in output)."""
+    print(f"INFO: {message}", file=sys.stderr)
+
+
+def warn(message: str) -> None:
+    """Print warning message to stderr."""
+    print(f"WARNING: {message}", file=sys.stderr)
+
+
+def format_task(task: dict) -> str:
+    """Format a task for display."""
+    status_icons = {
+        'todo': '[ ]',
+        'in_progress': '[~]',
+        'done': '[x]',
+        'blocked': '[!]'
+    }
+    priority_markers = {1: '', 2: '!', 3: '!!'}
+
+    status = status_icons.get(task.get('status', 'todo'), '[ ]')
+    priority = priority_markers.get(task.get('priority', 2), '!')
+
+    parts = [status]
+    if priority:
+        parts.append(priority)
+    parts.append(task['title'])
+
+    if task.get('project'):
+        parts.append(f"[{task['project']['name']}]")
+
+    if task.get('dueDate'):
+        due_str = task['dueDate']
+        if isinstance(due_str, str):
+            due_str = due_str[:10]
+        parts.append(f"(due: {due_str})")
+
+    line1 = ' '.join(parts)
+    line2 = f"    ID: {task['id'][:8]}"
+
+    if task.get('tags'):
+        line2 += f" | Tags: {', '.join(task['tags'])}"
+
+    return f"{line1}\n{line2}"
+
+
+def format_project(project: dict) -> str:
+    """Format a project for display."""
+    desc = ""
+    if project.get('description'):
+        desc = f"\n  {project['description'][:60]}..."
+
+    return f"- {project['name']} ({project['color']})\n  ID: {project['id'][:8]}{desc}"
+
+
+def format_data(data: Any) -> str:
+    """Format arbitrary data for display."""
+    if isinstance(data, list):
+        if not data:
+            return "(empty)"
+        if 'title' in data[0]:
+            return "\n\n".join(format_task(t) for t in data)
+        elif 'name' in data[0]:
+            return "\n\n".join(format_project(p) for p in data)
+        return str(data)
+    elif isinstance(data, dict):
+        if 'title' in data:
+            return format_task(data)
+        elif 'name' in data:
+            return format_project(data)
+        return str(data)
+    return str(data)

package/Claude/skills/environment/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: environment
+description: Check system status, view configuration, troubleshoot issues with the Cognova installation. Use when diagnosing problems, checking health, or understanding the current setup.
+allowed-tools: Bash, Read
+---
+
+# Environment Skill
+
+Check and manage the Cognova installation environment.
+
+## Commands
+
+### System info
+
+```bash
+python3 ~/.claude/skills/environment/environment.py info
+```
+
+Shows install directory, vault path, API URL, OS info, disk usage, vault file counts.
+
+### Service status
+
+```bash
+python3 ~/.claude/skills/environment/environment.py status
+```
+
+Shows PM2 process status (memory, CPU, restarts), API health, and database connectivity.
+
+### Recent logs
+
+```bash
+python3 ~/.claude/skills/environment/environment.py logs [--lines N]
+```
+
+Shows recent PM2 logs (default: 30 lines).
+
+### API health check
+
+```bash
+python3 ~/.claude/skills/environment/environment.py health
+```
+
+Checks multiple API endpoints and reports response times.
+
+## Natural Language Patterns
+
+- "Is everything running?" → Use `status`
+- "Check the system" → Use `status`
+- "Show me the logs" → Use `logs`
+- "What's the setup?" → Use `info`
+- "Is the API working?" → Use `health`
+- "How much disk space?" → Use `info`
+
+## Key Paths
+
+| Resource | How to Find |
+|----------|-------------|
+| Install dir | `$COGNOVA_PROJECT_DIR` or check `~/.cognova` metadata file |
+| Vault | `$VAULT_PATH` |
+| PM2 config | `$COGNOVA_PROJECT_DIR/ecosystem.config.cjs` |
+| App logs | `$COGNOVA_PROJECT_DIR/logs/` |
+| Environment | `$COGNOVA_PROJECT_DIR/.env` |
+| Database migrations | `$COGNOVA_PROJECT_DIR/server/drizzle/migrations/` |
+
+## Common Troubleshooting
+
+| Symptom | Check |
+|---------|-------|
+| 503 errors | `status` — DB might not have initialized; check logs |
+| API unreachable | `pm2 status` — process may have crashed; `pm2 restart cognova` |
+| Skills not working | Verify `~/.claude/skills/` has skill directories; re-run `cognova update` |
+| Out of memory | Check `info` for disk/memory; PM2 config has `--max-old-space-size=4096` |
+| Build failures | `NODE_OPTIONS='--max-old-space-size=4096' pnpm build` |