cognova 0.1.0

package/Claude/skills/project/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: project
+description: Manage Cognova projects - create, list, update projects. ALWAYS searches for existing projects before creating new ones. ALWAYS confirms with user before creating, showing potential matches.
+allowed-tools: Bash, Read
+---
+
+# Project Management Skill
+
+Manage projects in Cognova. Projects organize related tasks.
+
+## CRITICAL: Duplicate Prevention
+
+**ALWAYS search for existing projects before creating:**
+1. Run `python3 ~/.claude/skills/project/project.py search <name>` first
+2. Show user any matches found
+3. Only create if user confirms no existing project fits
+
+## Commands
+
+### Search for projects
+
+```bash
+python3 ~/.claude/skills/project/project.py search <query>
+```
+
+Example:
+```bash
+python3 ~/.claude/skills/project/project.py search "home"
+# Output: Found 2 projects matching "home":
+#   - homelab (#3b82f6) - ID: abc12345
+#   - home-automation (#22c55e) - ID: def67890
+```
+
+### List all projects
+
+```bash
+python3 ~/.claude/skills/project/project.py list
+```
+
+### Create a project
+
+```bash
+python3 ~/.claude/skills/project/project.py create <name> --color <hex> [--description <text>]
+```
+
+**Required:** `--color` must be a valid hex color (e.g., #3b82f6)
+
+Example:
+```bash
+python3 ~/.claude/skills/project/project.py create "Cognova" --color "#8b5cf6" --description "Personal knowledge management app"
+```
+
+### Update a project
+
+```bash
+python3 ~/.claude/skills/project/project.py update <id> [options]
+```
+
+Options:
+- `--name <name>` - New project name
+- `--color <hex>` - New color
+- `--description <text>` - New description
+
+### Delete a project
+
+```bash
+python3 ~/.claude/skills/project/project.py delete <id>
+```
+
+## Workflow: Creating a Project
+
+When user asks to create a project:
+
+1. **Search first:**
+   ```bash
+   python3 ~/.claude/skills/project/project.py search "project name"
+   ```
+
+2. **If matches found, ask user:**
+   "I found these existing projects that might match:
+   - existing-project-1
+   - existing-project-2
+
+   Would you like to use one of these, or create a new project?"
+
+3. **If user confirms new project:**
+   - Ask for color preference (suggest one if not provided)
+   - Create with: `python3 ~/.claude/skills/project/project.py create "name" --color "#hexcolor"`
+
+## Color Suggestions
+
+When user doesn't specify a color, suggest based on project type:
+- Development/Tech: Blue (#3b82f6)
+- Personal: Purple (#8b5cf6)
+- Health: Green (#22c55e)
+- Finance: Yellow (#eab308)
+- Home: Orange (#f97316)
+- Work: Red (#ef4444)
+
+## Natural Language Patterns
+
+- "Create a project for..." -> Search first, then create with confirmation
+- "List my projects" -> Use `list`
+- "Find projects about..." -> Use `search`
+- "Show project colors" -> Use `list` and display colors

package/Claude/skills/project/project.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+Project Management Skill for Cognova
+
+Usage:
+    python project.py search <query>
+    python project.py list
+    python project.py create <name> --color <hex> [--description <text>]
+    python project.py update <id> [options]
+    python project.py delete <id>
+"""
+
+import argparse
+import re
+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, info, warn, format_project
+
+
+def validate_color(color: str) -> bool:
+    """Validate hex color format."""
+    return bool(re.match(r'^#[0-9A-Fa-f]{6}$', color))
+
+
+def find_project_by_id(id_prefix: str) -> str | None:
+    """Find a project by ID prefix."""
+    ok, projects = get('/projects')
+    if not ok:
+        return None
+
+    for project in projects:
+        if project['id'].startswith(id_prefix):
+            return project['id']
+
+    return None
+
+
+def cmd_search(args):
+    """Search for projects by name."""
+    ok, projects = get('/projects')
+    if not ok:
+        error(f"Failed to fetch projects: {projects}")
+        sys.exit(1)
+
+    query = args.query.lower()
+    matches = [p for p in projects if query in p['name'].lower()]
+
+    if not matches:
+        print(f"No projects found matching '{args.query}'")
+        return
+
+    print(f"Found {len(matches)} project(s) matching '{args.query}':\n")
+    for p in matches:
+        print(format_project(p))
+        print()
+
+
+def cmd_list(args):
+    """List all projects."""
+    ok, projects = get('/projects')
+    if not ok:
+        error(f"Failed to fetch projects: {projects}")
+        sys.exit(1)
+
+    if not projects:
+        print("No projects found.")
+        return
+
+    print(f"Found {len(projects)} project(s):\n")
+    for p in projects:
+        print(format_project(p))
+        print()
+
+
+def cmd_create(args):
+    """Create a new project."""
+    if not validate_color(args.color):
+        error(f"Invalid color format: {args.color}. Use hex format like #3b82f6")
+        sys.exit(1)
+
+    # Check for existing projects with similar names
+    ok, projects = get('/projects')
+    if ok:
+        name_lower = args.name.lower()
+        similar = [p for p in projects if
+                   name_lower in p['name'].lower() or
+                   p['name'].lower() in name_lower]
+        if similar:
+            warn("Similar projects already exist:")
+            for p in similar:
+                print(f"  - {p['name']} ({p['color']}) ID: {p['id'][:8]}", file=sys.stderr)
+            print("\nConsider using an existing project instead.", file=sys.stderr)
+
+    data = {
+        'name': args.name,
+        'color': args.color,
+    }
+
+    if args.description:
+        data['description'] = args.description
+
+    ok, result = post('/projects', data)
+    if ok:
+        success(f"Created project: {result['name']}", result)
+    else:
+        error(f"Failed to create project: {result}")
+        sys.exit(1)
+
+
+def cmd_update(args):
+    """Update a project."""
+    data = {}
+
+    if args.name:
+        data['name'] = args.name
+    if args.color:
+        if not validate_color(args.color):
+            error(f"Invalid color format: {args.color}")
+            sys.exit(1)
+        data['color'] = args.color
+    if args.description:
+        data['description'] = args.description
+
+    if not data:
+        error("No updates specified")
+        sys.exit(1)
+
+    project_id = find_project_by_id(args.id)
+    if not project_id:
+        error(f"Project not found: {args.id}")
+        sys.exit(1)
+
+    ok, result = put(f'/projects/{project_id}', data)
+    if ok:
+        success(f"Updated project: {result['name']}", result)
+    else:
+        error(f"Failed to update project: {result}")
+        sys.exit(1)
+
+
+def cmd_delete(args):
+    """Delete a project (soft delete)."""
+    project_id = find_project_by_id(args.id)
+    if not project_id:
+        error(f"Project not found: {args.id}")
+        sys.exit(1)
+
+    ok, result = delete(f'/projects/{project_id}')
+    if ok:
+        success(f"Deleted project: {args.id}")
+    else:
+        error(f"Failed to delete project: {result}")
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Project Management Skill')
+    subparsers = parser.add_subparsers(dest='command', required=True)
+
+    # Search
+    search_p = subparsers.add_parser('search', help='Search for projects')
+    search_p.add_argument('query', help='Search query')
+
+    # List
+    subparsers.add_parser('list', help='List all projects')
+
+    # Create
+    create_p = subparsers.add_parser('create', help='Create a new project')
+    create_p.add_argument('name', help='Project name')
+    create_p.add_argument('--color', '-c', required=True,
+                          help='Hex color (e.g., #3b82f6)')
+    create_p.add_argument('--description', '-d', help='Project description')
+
+    # Update
+    update_p = subparsers.add_parser('update', help='Update a project')
+    update_p.add_argument('id', help='Project ID (prefix)')
+    update_p.add_argument('--name', help='New name')
+    update_p.add_argument('--color', help='New color')
+    update_p.add_argument('--description', help='New description')
+
+    # Delete
+    delete_p = subparsers.add_parser('delete', help='Delete a project')
+    delete_p.add_argument('id', help='Project ID (prefix)')
+
+    args = parser.parse_args()
+
+    commands = {
+        'search': cmd_search,
+        'list': cmd_list,
+        'create': cmd_create,
+        'update': cmd_update,
+        'delete': cmd_delete,
+    }
+
+    commands[args.command](args)
+
+
+if __name__ == '__main__':
+    main()

package/Claude/skills/skill-creator/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: skill-creator
+description: Assists users in creating new Claude Code skills. Uses web search to find latest conventions and suggests alternative approaches (existing MCPs, plugins) when appropriate.
+allowed-tools: Bash, Read, Write, WebSearch, WebFetch
+disable-model-invocation: true
+---
+
+# Skill Creator
+
+Assists in creating new Claude Code skills for Cognova or personal use.
+
+## Process
+
+When a user asks to create a new skill:
+
+### 1. Understand the Requirement
+
+Ask clarifying questions:
+- What should the skill do?
+- Should it be invokable by user, Claude, or both?
+- Does it need to call external APIs?
+- Should it run in a subagent (forked context)?
+
+### 2. Check for Existing Solutions
+
+**ALWAYS search before implementing:**
+
+```
+WebSearch: "Claude Code MCP <functionality>"
+WebSearch: "Claude Code plugin <functionality>"
+WebSearch: "anthropic MCP server <functionality>"
+```
+
+If an MCP or plugin exists:
+- Explain what it does
+- Show how to install/configure it
+- Ask if user still wants a custom skill
+
+### 3. Determine Skill Type
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| **Pure Instruction** | Claude can handle with existing tools | `/capture` - save note to inbox |
+| **Python Script** | Needs API calls, complex logic | `/task` - manage tasks via API |
+| **Subagent** | Long-running, exploratory | `/research` - deep dive on topic |
+
+### 4. Create the Skill
+
+#### For Pure Instruction Skills
+
+Create only `SKILL.md` in the appropriate location:
+
+- Personal: `~/.claude/skills/<skill-name>/SKILL.md`
+- Project: `.claude/skills/<skill-name>/SKILL.md`
+
+```yaml
+---
+name: skill-name
+description: When to use this skill
+allowed-tools: Bash, Read, Write, etc.
+---
+
+# Skill Name
+
+Instructions for Claude to follow...
+
+## Usage
+
+/skill-name <args>
+
+## Process
+
+1. Step one
+2. Step two
+...
+```
+
+#### For Python Script Skills
+
+Create `SKILL.md` + `script.py`:
+
+**SKILL.md Template:**
+```yaml
+---
+name: skill-name
+description: Description for Claude's auto-invocation
+allowed-tools: Bash, Read
+---
+
+# Skill Name
+
+## Commands
+
+\`\`\`bash
+python3 ~/.claude/skills/<name>/<name>.py <command> [options]
+\`\`\`
+
+## Examples
+...
+```
+
+**Python Template:**
+```python
+#!/usr/bin/env python3
+"""Skill description."""
+
+import argparse
+import sys
+from pathlib import Path
+
+def main():
+    parser = argparse.ArgumentParser(description='Skill Name')
+    # Add subparsers for commands
+    args = parser.parse_args()
+    # Execute command
+
+if __name__ == '__main__':
+    main()
+```
+
+### 5. Accessing Secrets & API Keys
+
+**NEVER hardcode API keys, tokens, or sensitive values in skills.**
+
+Cognova provides an encrypted secrets store. Use the shared API client:
+
+```python
+#!/usr/bin/env python3
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))  # Add parent for _lib
+from _lib.api import get_secret, get, post
+
+# Fetch a secret by key
+success, api_key = get_secret("GOOGLE_API_KEY")
+if not success:
+    print(f"Error: {api_key}")
+    print("Add this secret at Settings > Secrets in the dashboard")
+    sys.exit(1)
+
+# Now use api_key safely
+```
+
+**Key naming convention:** `SCREAMING_SNAKE_CASE` (e.g., `DISCORD_WEBHOOK_URL`, `OPENAI_API_KEY`)
+
+**Managing secrets:**
+- Dashboard: Settings > Secrets tab
+- Create: Add key + value (value is encrypted at rest)
+- Skills fetch decrypted values via `get_secret()`
+
+**When to use secrets vs environment variables:**
+| Use Case | Approach |
+|----------|----------|
+| API keys for external services | Secrets store (`get_secret()`) |
+| Webhook URLs, tokens | Secrets store |
+| Cognova API URL | Environment variable (pre-configured) |
+| Database URLs | Environment variables (system config) |
+
+#### Environment Variables
+
+The `_lib/api.py` module automatically handles these environment variables:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `COGNOVA_API_URL` | `http://localhost:3000` | API base URL |
+| `COGNOVA_API_TOKEN` | Auto-generated | Auth token (auto-read from `.api-token`) |
+
+**For Docker deployments**, these are pre-configured in `docker-compose.yml`. Skills don't need to set them.
+
+**For local development**, the API token is auto-generated on server startup and written to `.api-token` in the project root. The `_lib/api.py` module reads it automatically.
+
+**Custom environment variables** can be added to `.env` (local) or `docker-compose.yml` (Docker):
+
+```bash
+# .env
+MY_CUSTOM_VAR=value
+```
+
+```python
+# In skill
+import os
+my_var = os.environ.get('MY_CUSTOM_VAR', 'default')
+```
+
+### 6. Skill Frontmatter Options
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `name` | string | Command name (becomes `/name`) |
+| `description` | string | When Claude should use this skill |
+| `allowed-tools` | Bash, Read, Write, Edit, WebSearch, WebFetch, Grep, Glob | Tools Claude can use |
+| `disable-model-invocation` | true | User-only, Claude won't auto-invoke |
+| `user-invocable` | false | Claude-only, hidden from user menu |
+| `context` | fork | Run in subagent |
+| `agent` | Explore, Plan, general-purpose | Agent type for subagent |
+
+### 7. Skill Locations
+
+| Location | Use Case |
+|----------|----------|
+| `~/.claude/skills/` | Personal + Cognova bundled skills |
+| `.claude/skills/` | Project-specific skills |
+
+### 8. Testing
+
+```bash
+# Test Python script directly
+python3 ~/.claude/skills/<name>/<name>.py --help
+
+# Test via Claude Code
+claude
+> /skill-name test
+```
+
+## Example: Creating a Simple Skill
+
+User: "I want a skill to quickly add notes to my inbox"
+
+Response:
+"This is perfect for a pure instruction skill. Let me create it:
+
+**File: `~/.claude/skills/capture/SKILL.md`**
+```yaml
+---
+name: capture
+description: Quickly capture a note to the inbox folder
+allowed-tools: Write
+---
+
+# Quick Capture
+
+Save a quick note to the inbox.
+
+## Usage
+
+/capture <note content>
+
+## Process
+
+1. Generate filename: `inbox/YYYY-MM-DD-<slugified-title>.md`
+2. Create file with frontmatter:
+   \`\`\`markdown
+   ---
+   created: <ISO timestamp>
+   status: inbox
+   ---
+
+   <note content>
+   \`\`\`
+3. Confirm creation to user
+```
+
+This skill needs no Python script - Claude will use the Write tool directly."
+
+## Web Search Patterns
+
+For finding existing solutions:
+- MCPs: `"MCP server" <functionality> site:github.com`
+- Claude plugins: `"claude code" plugin <functionality>`
+- Best practices: `"claude code" skill best practices`
+- Latest conventions: `site:code.claude.com skills`

package/Claude/skills/task/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: task
+description: Manage Cognova tasks - create, list, update, complete tasks. Use when the user wants to track work items, todos, or action items. Can search for and associate tasks with projects.
+allowed-tools: Bash, Read
+---
+
+# Task Management Skill
+
+Manage tasks in Cognova through natural language commands.
+
+## Commands
+
+### Create a task
+
+```bash
+python3 ~/.claude/skills/task/task.py create "Task title" [options]
+```
+
+Options:
+- `--project <name>` - Associate with project (searches for match)
+- `--priority <1|2|3>` - Set priority (1=Low, 2=Medium, 3=High)
+- `--due <date>` - Set due date (YYYY-MM-DD or natural: "tomorrow", "next monday")
+- `--tags <tag1,tag2>` - Add comma-separated tags
+- `--description <text>` - Add description
+
+Examples:
+```bash
+python3 ~/.claude/skills/task/task.py create "Review PR for auth feature" --project "cognova" --priority 3
+python3 ~/.claude/skills/task/task.py create "Call dentist" --due tomorrow
+python3 ~/.claude/skills/task/task.py create "Write documentation" --tags "docs,urgent"
+```
+
+### List tasks
+
+```bash
+python3 ~/.claude/skills/task/task.py list [filters]
+```
+
+Filters:
+- `--status <todo|in_progress|done|blocked>` - Filter by status
+- `--project <name>` - Filter by project (partial match)
+- `--search <query>` - Search title/description
+- `--due <today|week|overdue>` - Filter by due date
+
+Examples:
+```bash
+python3 ~/.claude/skills/task/task.py list
+python3 ~/.claude/skills/task/task.py list --project homelab --status todo
+python3 ~/.claude/skills/task/task.py list --due overdue
+```
+
+### Update a task
+
+```bash
+python3 ~/.claude/skills/task/task.py update <id> [options]
+```
+
+Options: Same as create, plus `--status`
+
+Example:
+```bash
+python3 ~/.claude/skills/task/task.py update abc123 --status in_progress --priority 3
+```
+
+### Complete a task
+
+```bash
+python3 ~/.claude/skills/task/task.py done <id_or_search>
+```
+
+Examples:
+```bash
+python3 ~/.claude/skills/task/task.py done abc123
+python3 ~/.claude/skills/task/task.py done "PR review"
+```
+
+### Delete a task
+
+```bash
+python3 ~/.claude/skills/task/task.py delete <id>
+```
+
+## Natural Language Patterns
+
+When users say things like:
+- "Create a task to..." -> Use `create`
+- "What tasks do I have..." -> Use `list`
+- "Mark X as done" -> Use `done`
+- "I finished the..." -> Use `done` with search
+- "Show my todos" -> Use `list --status todo`
+
+## Project Association
+
+When creating tasks with `--project`:
+1. The skill searches for matching projects
+2. If one match found, associates automatically
+3. If multiple matches, lists them for user to choose
+4. If no match, creates task without project and suggests creating one
+
+## Frontmatter Standards
+
+All markdown documents in the vault use YAML frontmatter for metadata. When new documents are created or discovered without frontmatter, defaults are automatically added:
+
+```yaml
+---
+tags: []
+shared: false
+---
+```
+
+### Frontmatter Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `tags` | string[] | `[]` | Array of tag strings for categorization |
+| `shared` | boolean | `false` | Visibility: `false` = hidden (auth required) |
+| `shareType` | string | - | When `shared: true`: `'private'` (link only) or `'public'` (indexed) |
+| `title` | string | - | Optional override; extracted from H1 or filename if not set |
+| `project` | string | - | Project ID for document association |
+
+### Visibility Modes
+
+Documents support three visibility levels:
+
+1. **Hidden** (default) - `shared: false`
+   - Requires authentication
+   - Never publicly accessible
+
+2. **Private** - `shared: true, shareType: 'private'`
+   - Accessible via direct link
+   - Not indexed by search engines
+
+3. **Public** - `shared: true, shareType: 'public'`
+   - Publicly accessible
+   - Indexed by search engines