Standardize database naming and fix environment configuration

- Renamed database from 'decision_tree' to 'apoklisis' for consistency - Updated docker-compose.yml: container renamed to 'apoklisis_postgres' - Updated .env file with correct database URL - Verified backend authentication flow working correctly - Added postgres MCP server to Claude Code configuration
2026-01-27 18:28:10 -05:00
parent a3efe68282
commit 6a0f9cfc4a
4 changed files with 418 additions and 4 deletions
--- a/CLAUDE-SETUP.md
+++ b/CLAUDE-SETUP.md
@@ -0,0 +1,404 @@
+# Claude Code Setup Reference for Apoklisis
+
+This document catalogs all tools, plugins, and MCP servers available to Claude Code when developing Apoklisis, along with guidelines for their effective use.
+
+**Last Updated**: 2026-01-27
+**Project**: Apoklisis
+**Working Directory**: `c:\Dev\Projects\Apoklisis`
+**Platform**: Windows (win32)
+**IDE**: VSCode with Claude Code extension
+
+---
+
+## Core Built-In Tools
+
+### File Operations
+
+#### Read
+- **Purpose**: Read file contents from the filesystem
+- **Capabilities**:
+  - Reads up to 2000 lines by default
+  - Supports offset/limit for large files
+  - Can read images (PNG, JPG), PDFs, and Jupyter notebooks
+  - Returns content with line numbers
+- **When to use**: Always read files before editing them; use for examining code, configs, or documentation
+
+#### Edit
+- **Purpose**: Perform exact string replacements in files
+- **Capabilities**:
+  - Replaces `old_string` with `new_string`
+  - Supports `replace_all` for renaming variables
+  - Preserves indentation
+- **When to use**: Prefer editing over writing new files; ideal for targeted changes
+- **Requirements**: Must read file first before editing
+
+#### Write
+- **Purpose**: Create new files or overwrite existing ones
+- **Capabilities**: Writes complete file content
+- **When to use**: Only for creating genuinely new files; avoid for existing files (use Edit instead)
+- **Requirements**: Must read file first if it exists
+
+#### NotebookEdit
+- **Purpose**: Edit Jupyter notebook (.ipynb) cells
+- **Capabilities**:
+  - Replace, insert, or delete cells
+  - Supports code and markdown cells
+- **When to use**: Working with Jupyter notebooks in the project
+
+### Search & Discovery
+
+#### Glob
+- **Purpose**: Fast file pattern matching
+- **Capabilities**:
+  - Supports glob patterns like `**/*.js`, `src/**/*.ts`
+  - Returns files sorted by modification time
+- **When to use**: Finding files by name patterns; use for specific needle queries
+- **Example**: `**/*.py` to find all Python files
+
+#### Grep
+- **Purpose**: Powerful content search (built on ripgrep)
+- **Capabilities**:
+  - Full regex support
+  - Filter by glob or file type
+  - Output modes: content, files_with_matches, count
+  - Context lines (-A, -B, -C)
+  - Multiline matching support
+- **When to use**: Searching for code patterns, function definitions, or specific strings
+- **Important**: Use Task with Explore agent for open-ended exploratory searches
+
+### Execution & System
+
+#### Bash
+- **Purpose**: Execute bash commands
+- **Capabilities**:
+  - Git operations
+  - Package management (npm, pip, etc.)
+  - Build commands
+  - Testing
+  - System operations
+- **When to use**: Terminal operations, git, npm, docker, but NOT for file reading/searching (use specialized tools)
+- **Best practices**:
+  - Use `&&` for sequential dependent commands
+  - Quote paths with spaces
+  - Avoid `cd`; use absolute paths instead
+  - Never skip git hooks unless explicitly requested
+
+#### TaskOutput
+- **Purpose**: Retrieve output from running/completed background tasks
+- **When to use**: Check status of background shells or agents
+
+#### TaskStop
+- **Purpose**: Stop running background tasks
+- **When to use**: Terminate long-running processes
+
+### Planning & Task Management
+
+#### TodoWrite
+- **Purpose**: Create and manage structured task lists
+- **Capabilities**:
+  - Track tasks with states: pending, in_progress, completed
+  - Organize complex multi-step work
+- **When to use**:
+  - Complex tasks with 3+ steps
+  - Multi-file changes
+  - User provides multiple tasks
+  - Before starting work on each task
+- **Best practice**: Mark todos completed immediately after finishing; maintain exactly ONE in_progress task at a time
+
+#### EnterPlanMode / ExitPlanMode
+- **Purpose**: Enter planning mode for implementation design
+- **When to use**:
+  - New feature implementation
+  - Multiple valid approaches exist
+  - Architectural decisions needed
+  - Multi-file changes
+  - Unclear requirements
+- **When NOT to use**: Simple one-line fixes, trivial tasks, pure research
+
+#### AskUserQuestion
+- **Purpose**: Ask user questions during execution
+- **Capabilities**:
+  - Multiple choice questions (2-4 options)
+  - Multi-select support
+  - Collects user preferences and clarifications
+- **When to use**: Need clarification on requirements, implementation choices, or ambiguous instructions
+
+### Web & Information
+
+#### WebFetch
+- **Purpose**: Fetch and analyze web content
+- **Capabilities**:
+  - Converts HTML to markdown
+  - 15-minute cache
+- **Limitations**: WILL FAIL for authenticated/private URLs
+- **When to use**: Public documentation, articles, reference materials
+- **Note**: For GitHub URLs, prefer `gh` CLI via Bash
+
+#### WebSearch
+- **Purpose**: Search the web for current information
+- **Capabilities**:
+  - Access to up-to-date information beyond knowledge cutoff
+  - Domain filtering (allowed/blocked)
+- **Requirements**: MUST include "Sources:" section with markdown links in response
+- **When to use**: Current events, recent documentation, external references
+
+#### ToolSearch
+- **Purpose**: Load deferred MCP tools before use
+- **Capabilities**:
+  - Keyword search mode (e.g., "slack", "notebook")
+  - Direct selection mode (e.g., "select:NotebookEdit")
+  - Required keyword mode (e.g., "+linear create issue")
+- **When to use**: MANDATORY before calling any deferred/MCP tool
+- **Important**: This is a BLOCKING requirement - must load tools before calling them
+
+---
+
+## Specialized Agents (via Task Tool)
+
+The Task tool launches specialized agents for complex work. Each agent type has specific capabilities:
+
+### Bash Agent
+- **Specialty**: Command execution
+- **Tools**: Bash only
+- **When to use**: Git operations, complex command sequences
+
+### general-purpose Agent
+- **Specialty**: Complex research and multi-step tasks
+- **Tools**: All tools
+- **When to use**: Complex questions, keyword searches requiring multiple attempts
+
+### Explore Agent
+- **Specialty**: Fast codebase exploration
+- **Tools**: Read-only tools (Glob, Grep, Read, etc.)
+- **Thoroughness levels**: quick, medium, very thorough
+- **When to use**:
+  - "Where are errors handled?"
+  - "How do API endpoints work?"
+  - "What is the codebase structure?"
+- **Critical**: Use this instead of manual Glob/Grep for exploratory searches
+
+### Plan Agent
+- **Specialty**: Implementation planning and architecture design
+- **Tools**: Read-only tools
+- **When to use**: Design implementation strategy, identify critical files, consider architectural trade-offs
+
+### feature-dev Agents
+- **code-architect**: Design feature architectures
+- **code-explorer**: Analyze existing features and patterns
+- **code-reviewer**: Review code for bugs and quality issues
+
+---
+
+## Available Skills (via Skill Tool)
+
+Skills are invoked when users reference slash commands (e.g., `/commit`).
+
+### feature-dev:feature-dev
+- **Purpose**: Guided feature development with architecture focus
+- **When to use**: Building new features from scratch
+
+### frontend-design:frontend-design
+- **Purpose**: Create production-grade frontend interfaces
+- **When to use**: Building web components, pages, or applications
+- **Goal**: Avoid generic AI aesthetics; create polished, distinctive designs
+
+### Figma Integration Skills
+- **figma:code-connect-components**: Map Figma designs to code components
+- **figma:create-design-system-rules**: Generate custom design system rules
+- **figma:implement-design**: Translate Figma designs to production code
+- **Requirement**: Figma MCP server connection
+
+---
+
+## MCP Servers (Deferred Tools)
+
+These tools must be loaded via ToolSearch before use.
+
+### GitHub MCP Server
+**Prefix**: `mcp__github__*`
+
+**Available Operations**:
+- **Repository**: create, fork, search repositories
+- **Files**: get contents, create/update files, push files
+- **Branches**: create, list commits
+- **Issues**: create, list, update, get, add comments, search
+- **Pull Requests**: create, list, get, merge, review, get files/status/comments
+- **Search**: code, issues, users
+
+**When to use**: GitHub operations beyond what `gh` CLI provides
+
+### Filesystem MCP Server
+**Prefix**: `mcp__filesystem__*`
+
+**Available Operations**:
+- **Read**: read_file, read_text_file, read_media_file, read_multiple_files
+- **Write**: write_file, edit_file
+- **Directory**: create, list, tree, list_with_sizes
+- **Operations**: move, search files, get file info
+- **Management**: list_allowed_directories
+
+**When to use**: Complex filesystem operations; prefer built-in Read/Write/Edit for simple operations
+
+### MS365 MCP Server
+**Prefix**: `mcp__ms365__*`
+
+**Available Operations**:
+- **Authentication**: login, logout, verify, list/select/remove accounts
+- **Teams**: chat operations, channel messages, team management
+- **OneDrive**: file operations, Excel operations (worksheets, charts, ranges)
+- **Outlook**: mail operations, calendar events, contacts
+- **SharePoint**: site operations, lists, items
+- **Planner**: tasks and plans
+- **OneNote**: notebooks, sections, pages
+- **Todo**: task lists and tasks
+
+**When to use**: Integration with Microsoft 365 services
+
+---
+
+## Project-Specific Context: Apoklisis
+
+### Environment
+- **Repository**: Git repository on main branch
+- **Platform**: Windows (win32)
+- **IDE**: VSCode with native Claude Code extension
+- **Recent Activity**:
+  - Backend fixes: passlib/bcrypt integration (pinned bcrypt to 4.1.2)
+  - DateTime timezone issue fixes
+  - Clean working tree (as of last snapshot)
+
+### Recent Commits
+```
+a3efe68 Committing before moving to local disk
+a6fc86c Pin bcrypt version to 4.1.2 for passlib compatibility
+fa632da Fix backend: add passlib/bcrypt, fix datetime timezone issues
+```
+
+### Technology Stack (Inferred)
+- **Backend**: Python (passlib, bcrypt for authentication)
+- **Key Considerations**:
+  - Password hashing with passlib
+  - Timezone handling for datetime operations
+  - Dependency version compatibility (bcrypt pinned)
+
+### File Reference Format
+When referencing code in VSCode, use markdown links:
+- Files: `[filename.ts](src/filename.ts)`
+- Specific lines: `[filename.ts:42](src/filename.ts#L42)`
+- Line ranges: `[filename.ts:42-51](src/filename.ts#L42-L51)`
+- Folders: `[src/utils/](src/utils/)`
+
+---
+
+## Development Guidelines
+
+### General Workflow
+1. **Read First**: Always read files before editing
+2. **Plan Complex Tasks**: Use TodoWrite for multi-step work
+3. **Use Specialized Tools**: Prefer dedicated tools over bash commands for file operations
+4. **Explore Efficiently**: Use Task with Explore agent for codebase exploration
+5. **Parallel Execution**: Make independent tool calls in parallel when possible
+
+### Code Modification Principles
+- **Avoid Over-Engineering**: Only make requested changes
+- **No Premature Abstraction**: Don't create utilities for one-time operations
+- **Security First**: Watch for command injection, XSS, SQL injection, OWASP Top 10
+- **Simplicity**: Keep solutions focused and minimal
+- **No Unnecessary Additions**: Don't add error handling for impossible scenarios
+
+### Git Best Practices
+- **Never** update git config
+- **Never** run destructive commands (push --force, reset --hard) without explicit request
+- **Never** skip hooks (--no-verify, --no-gpg-sign)
+- **Always** create NEW commits (don't amend unless requested)
+- **Prefer** staging specific files over `git add -A` or `git add .`
+- **Only commit** when explicitly requested
+- **Include** co-author tag: `Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>`
+
+### Pull Request Workflow
+1. Run `git status`, `git diff`, check branch state
+2. Analyze ALL commits from branch divergence (not just latest)
+3. Keep PR title under 70 characters
+4. Use HEREDOC for PR body with format:
+   ```
+   ## Summary
+   <1-3 bullet points>
+
+   ## Test plan
+   [Checklist of testing TODOs]
+
+   🤖 Generated with [Claude Code](https://claude.com/claude-code)
+   ```
+
+### Communication Style
+- **Concise**: Short, focused responses for CLI display
+- **No Emojis**: Unless explicitly requested
+- **No Time Estimates**: Never predict how long tasks will take
+- **Objective**: Technical accuracy over validation
+- **Direct**: Use markdown formatting, output text directly (not via echo/bash)
+
+### When to Ask for Help
+- **User Questions**: Use AskUserQuestion for clarifications
+- **Planning**: Use EnterPlanMode for complex implementation decisions
+- **Feedback**: Direct users to https://github.com/anthropics/claude-code/issues
+
+---
+
+## Quick Reference: Tool Selection Decision Tree
+
+```
+Need to find files by name pattern?
+  → Use Glob
+
+Need to search for code content?
+  → Specific query? → Use Grep
+  → Exploratory search? → Use Task (Explore agent)
+
+Need to read a file?
+  → Use Read (not cat)
+
+Need to modify existing file?
+  → Use Edit (not sed/awk)
+
+Need to create new file?
+  → Use Write (not echo/heredoc)
+
+Need to execute command/git/npm?
+  → Use Bash
+
+Need to plan complex implementation?
+  → Use EnterPlanMode
+
+Need to track multi-step task?
+  → Use TodoWrite
+
+Need GitHub/MS365/filesystem MCP operations?
+  → First: ToolSearch to load tool
+  → Then: Call the loaded MCP tool
+
+Need to ask user a question?
+  → Use AskUserQuestion
+```
+
+---
+
+## Notes for Future Sessions
+
+- **Context Persistence**: Conversations have unlimited context through automatic summarization
+- **Tool Results**: May include `<system-reminder>` tags with useful information
+- **Model**: Powered by Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
+- **Knowledge Cutoff**: January 2025
+- **Current Date**: Always use 2026 in current date calculations
+
+---
+
+## Security Policy
+
+**Defensive Security Only**
+- Assist with security analysis, detection rules, vulnerability explanations
+- Create defensive tools and security documentation
+- **Refuse**: Code for malicious use, credential harvesting, bulk SSH key/cookie/wallet crawling
+
+---
+
+*This reference guide should be consulted at the start of each session to ensure effective use of all available tools and maintain consistency with project conventions.*
--- a/PROGRESS.md
+++ b/PROGRESS.md
@@ -17,6 +17,11 @@ Building a troubleshooting decision tree web application for MSP engineers. The

 ---

+# Apoklisis Development Progress
+
+> 📚 **Reference**: See [CLAUDE-SETUP.md](./CLAUDE-SETUP.md) for available
+> development tools and usage guidelines
+
 ## Completed Work

 ### Phase 1a: Backend API (COMPLETE)
--- a/backend/.claude/settings.local.json
+++ b/backend/.claude/settings.local.json
@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(test:*)"
+    ]
+  }
+}
--- a/backend/docker-compose.yml
+++ b/backend/docker-compose.yml
@@ -1,13 +1,11 @@
-version: '3.8'
-
 services:
  db:
    image: postgres:16-alpine
-    container_name: decision_tree_db
+    container_name: apoklisis_postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
-      POSTGRES_DB: decision_tree
+      POSTGRES_DB: apoklisis
    ports:
      - "5432:5432"
    volumes: