@aladac/hu 0.1.0-a1

package/plans/jaunty-sprouting-marble.md

@@ -0,0 +1,171 @@
+# Plan: Convert Python Helper Scripts to Rust
+
+## Overview
+
+Convert 6 Python analysis scripts (~1,800 lines total) to Rust. These scripts analyze a Rails codebase for code quality issues, unused code, and test infrastructure problems.
+
+**Difficulty Assessment: MEDIUM**
+- No external APIs or HTTP calls
+- All standard library dependencies (no pip packages)
+- Main challenges: Ruby code parsing and regex patterns
+
+## Scripts to Convert
+
+| Script | Lines | Complexity | Effort |
+|--------|-------|------------|--------|
+| rspec-extraction-candidates.py | ~160 | Low | 1-2 days |
+| vcr-cassettes-check.py | ~290 | Medium | 2-3 days |
+| routes-check.py | ~320 | Medium-High | 2-3 days |
+| n-plus-one-finder.py | ~280 | Medium | 2-3 days |
+| dead-code-check.py | ~300 | Medium-High | 3-4 days |
+| factories-analysis.py | ~450 | High | 4-5 days |
+
+**Total Estimated Effort: 14-20 days**
+
+## Recommended Approach
+
+### Phase 1: Shared Library Foundation
+
+Create a shared Rust library with common functionality used across all scripts:
+
+```
+helper-scripts-rs/
+├── Cargo.toml
+├── src/
+│   ├── lib.rs           # Re-exports
+│   ├── cli.rs           # Common CLI patterns
+│   ├── table.rs         # ANSI table formatting (box-drawing chars)
+│   ├── colors.rs        # ANSI color constants
+│   ├── files.rs         # File discovery, reading
+│   ├── grep.rs          # Grep-like search functionality
+│   └── ruby_parser.rs   # Ruby syntax parsing utilities
+└── bin/
+    ├── dead_code_check.rs
+    ├── factories_analysis.rs
+    ├── n_plus_one_finder.rs
+    ├── routes_check.rs
+    ├── rspec_extraction.rs
+    └── vcr_cassettes_check.rs
+```
+
+### Phase 2: Implement in Order of Complexity
+
+**Order: Simplest first to build up shared utilities**
+
+1. **rspec-extraction-candidates** (simplest)
+   - Grep for VCR tags
+   - Count lines and context blocks
+   - Format table output
+
+2. **vcr-cassettes-check**
+   - Multi-format file discovery
+   - Cassette name matching (fuzzy)
+   - Size calculations
+
+3. **n-plus-one-finder**
+   - 11 regex patterns (6 multiline, 5 single-line)
+   - Pattern matching and extraction
+   - Severity classification
+
+4. **routes-check**
+   - Subprocess call to `bundle exec rails routes`
+   - Controller action parsing
+   - Route-action matching
+
+5. **dead-code-check**
+   - Ruby method/class definition parsing
+   - Usage indexing via grep
+   - Nesting and indentation tracking
+
+6. **factories-analysis** (most complex)
+   - FactoryBot syntax parsing
+   - Module/factory/trait stack tracking
+   - Dual analysis (methods + traits)
+
+## Key Dependencies
+
+```toml
+[dependencies]
+clap = { version = "4", features = ["derive"] }  # CLI argument parsing
+walkdir = "2"                                     # Recursive file discovery
+regex = "1"                                       # Pattern matching
+anyhow = "1"                                      # Error handling
+colored = "2"                                     # ANSI colors (optional)
+rayon = "1"                                       # Parallel processing (optional)
+```
+
+## Technical Challenges & Solutions
+
+### 1. Grep Functionality
+**Problem:** Python scripts use `subprocess.run(['grep', ...])` heavily
+
+**Solutions:**
+- Option A: Continue using subprocess (easy, same behavior)
+- Option B: Use Rust `regex` crate with ripgrep-style implementation (faster, no subprocess)
+
+**Recommendation:** Option B for performance; build a reusable `grep.rs` module
+
+### 2. Ruby Code Parsing
+**Problem:** Several scripts parse Ruby syntax (methods, classes, modules)
+
+**Current approach:** Regex-based pattern matching with indentation tracking
+
+**Rust solution:** 
+- Port regex patterns carefully (Rust regex crate is compatible)
+- Use `nom` crate if more robust parsing needed
+- Handle Ruby's `end` keyword counting for block tracking
+
+### 3. ANSI Table Formatting
+**Problem:** All scripts output formatted tables with box-drawing characters
+
+**Rust solution:** Create a generic `Table` struct:
+```rust
+struct Table {
+    headers: Vec<String>,
+    rows: Vec<Vec<String>>,
+    column_widths: Vec<usize>,
+}
+
+impl Table {
+    fn print(&self) { /* box-drawing output */ }
+}
+```
+
+### 4. Multiline Regex
+**Problem:** n-plus-one-finder uses multiline patterns
+
+**Rust solution:** Enable `(?m)` flag or use `regex::RegexBuilder::multi_line(true)`
+
+## Benefits of Rust Conversion
+
+1. **Performance**: 10-100x faster execution, especially for large codebases
+2. **Single binary**: No Python runtime dependency
+3. **Parallelization**: Easy to add with Rayon for file processing
+4. **Type safety**: Catch errors at compile time
+5. **Cross-platform**: Easy distribution as static binaries
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| Ruby parsing edge cases | Medium | Keep Python versions for comparison testing |
+| Regex behavior differences | Low | Test extensively with same inputs |
+| Development time | Medium | Start with simplest script, build incrementally |
+
+## Success Criteria
+
+- All 6 binaries produce identical output to Python versions
+- Test with actual Rails codebase
+- No external runtime dependencies (single binary)
+- Performance improvement measurable
+
+## Files to Create
+
+1. `helper-scripts-rs/Cargo.toml` - Workspace configuration
+2. `helper-scripts-rs/src/lib.rs` - Shared library
+3. `helper-scripts-rs/src/table.rs` - Table formatting
+4. `helper-scripts-rs/src/colors.rs` - ANSI colors
+5. `helper-scripts-rs/src/files.rs` - File operations
+6. `helper-scripts-rs/src/grep.rs` - Search functionality
+7. `helper-scripts-rs/src/ruby_parser.rs` - Ruby parsing utilities
+8. `helper-scripts-rs/bin/*.rs` - 6 binary entry points

package/plans/jiggly-discovering-lake.md

@@ -0,0 +1,68 @@
+# Plan: API Model Inventory
+
+## Objective
+
+Query all three OpenAI-compatible API servers and produce a concise inventory table of all models.
+
+## Servers
+
+| Server | Host | Service |
+|--------|------|---------|
+| junkpile | `192.168.0.26:11434` | Ollama |
+| fuji (Ollama) | `127.0.0.1:11434` | Ollama |
+| fuji (LMS) | `127.0.0.1:1234` | LM Studio |
+
+## Output Format
+
+```
+| Model                  | Host      | Type    | Service   | Size   | Params |
+|------------------------|-----------|---------|-----------|--------|--------|
+| minicpm-v:8b           | junkpile  | vision  | ollama    | 5.5 GB | 8B     |
+| hermes3:latest         | junkpile  | text    | ollama    | 4.7 GB | 8B     |
+| qwen2-vl-7b-...        | fuji      | vision  | lmstudio  | 4.2 GB | 7B     |
+```
+
+## Implementation
+
+### Step 1: Add CLI Command
+
+**File**: `src/prompts/ai/cli.py`
+
+Add `prompts ai inventory` command that:
+1. Queries all three endpoints via `/v1/models` (OpenAI API)
+2. For Ollama servers, also query `/api/tags` for detailed model info (size, params)
+3. For LM Studio, parse `lms ls` output for additional details
+4. Outputs a markdown table
+
+### Step 2: Implementation Details
+
+```python
+@ai.command()
+def inventory():
+    """List all models across all API servers."""
+
+    SERVERS = [
+        ("junkpile", "192.168.0.26:11434", "ollama"),
+        ("fuji", "127.0.0.1:11434", "ollama"),
+        ("fuji", "127.0.0.1:1234", "lmstudio"),
+    ]
+
+    for name, host, service in SERVERS:
+        client = VisionClient(host=host, backend=service)
+        models = client.list_models_detailed()
+        # Format and print table rows
+```
+
+### Step 3: Model Type Detection
+
+Detect vision vs text models by:
+- Check if model name contains vision keywords: `vision`, `-v`, `vl`, `llava`, `minicpm-v`
+- Default to "text" if no match
+
+## Verification
+
+```bash
+uv run prompts ai inventory
+```
+
+Expected: Table with all models from all three servers, showing host, type, service, size.

package/plans/magical-nibbling-spark.md

@@ -0,0 +1,144 @@
+# Implementation Plan: Claude Code Context Detection
+
+## Summary
+
+Implement two deferred features from TODO.md:
+1. **Auto-detect project_id for memory storage** - Automatically scope memories, decisions, knowledge to the current project
+2. **Claude Code session ID detection** - Detect the active Claude Code session from `~/.claude/session-env/`
+
+## Critical Files to Modify
+
+| File | Changes |
+|------|---------|
+| `src/personality/utils/claude_context.py` | **NEW** - Claude Code environment detection utilities |
+| `src/personality/mcp/server.py` | Add project detection to lifespan, expand AppContext |
+| `src/personality/mcp/tools.py` | Pass project_id when storing memory/knowledge/decisions/sessions |
+
+## Implementation Details
+
+### 1. Create `src/personality/utils/claude_context.py`
+
+New utility module for Claude Code environment detection:
+
+```python
+def get_claude_session_id() -> str | None:
+    """Get current Claude Code session ID from ~/.claude/session-env/"""
+    # Find most recently modified directory by mtime
+    # Returns UUID string or None
+
+def get_claude_project_dir() -> Path | None:
+    """Get Claude Code project directory for current working directory."""
+    # Maps cwd /Users/chi/Projects/foo -> ~/.claude/projects/-Users-chi-Projects-foo
+
+def detect_claude_context() -> ClaudeContext:
+    """Detect full Claude Code context (session_id, project_dir)."""
+```
+
+### 2. Update `src/personality/mcp/server.py`
+
+**Expand AppContext dataclass:**
+```python
+@dataclass
+class AppContext:
+    db: AsyncSession
+    settings: Settings
+    persona: str
+    project_id: UUID | None = None  # NEW: auto-detected project
+    claude_session_id: str | None = None  # NEW: Claude Code session
+```
+
+**Update `app_lifespan()`:**
+```python
+async def app_lifespan(...):
+    # ... existing code ...
+
+    # Auto-detect project context
+    from personality.utils.project_context import detect_project_context
+    from personality.utils.claude_context import get_claude_session_id
+
+    project_ctx = detect_project_context()
+    project_id = await _get_or_create_project_id(db, project_ctx)
+    claude_session_id = get_claude_session_id()
+
+    yield AppContext(
+        db=db,
+        settings=settings,
+        persona=persona,
+        project_id=project_id,
+        claude_session_id=claude_session_id,
+    )
+```
+
+**Add helper function:**
+```python
+async def _get_or_create_project_id(db: AsyncSession, ctx: ProjectContext) -> UUID | None:
+    """Look up project by git_url or name, create if not exists."""
+    if not ctx["is_git_repo"]:
+        return None  # Only scope git repos
+
+    # Query by git_url first (most reliable), then by name
+    # Create if not found
+    # Return project.id
+```
+
+### 3. Update `src/personality/mcp/tools.py`
+
+**Memory store:**
+```python
+async def _memory_store(...):
+    new_memory = Memory(
+        persona=persona,
+        project_id=app.project_id,  # ADD THIS
+        category=cat,
+        content=content,
+        embedding=embedding,
+    )
+```
+
+**Knowledge link:**
+```python
+async def _knowledge_link(...):
+    new_rel = Knowledge(
+        persona=persona,
+        project_id=app.project_id,  # ADD THIS
+        # ...
+    )
+```
+
+**Decision record:**
+```python
+async def _decision_record(...):
+    new_decision = Decision(
+        persona=persona,
+        project_id=app.project_id,  # ADD THIS
+        # ...
+    )
+```
+
+**Session start:**
+```python
+async def _session_start(...):
+    new_session = SessionModel(
+        persona=persona,
+        project_id=app.project_id,  # ADD THIS
+        name=name,
+        state="active",
+    )
+```
+
+## Verification Plan
+
+1. **Type checking:** `just types`
+2. **Lint:** `just lint`
+3. **Unit tests:** `just test -k "claude" or test -k "project"`
+4. **Manual verification:**
+   - Start Claude Code in the personality project directory
+   - Use `memory store` tool and verify project_id is populated in DB
+   - Use `project` tool to confirm project context is detected
+   - Check that the session MCP tool creates sessions with project_id
+
+## Notes
+
+- The Session model already has a `project_id` field (FK to projects.id)
+- All models (Memory, Knowledge, Decision, Session) already support project_id - we just need to populate it
+- Claude session detection is informational for now; could be used later to correlate sessions

package/plans/mellow-kindling-acorn.md

@@ -0,0 +1,110 @@
+# Documentation Indexing Implementation Plan
+
+## Objective
+Add support for indexing documentation files (Markdown, RST, AsciiDoc, plain text) to the personality project's indexer with header-based chunking.
+
+## Files to Modify
+
+### 1. Schema Updates
+**`src/personality/schemas/project_index.py`**
+
+Add to `Language` enum:
+```python
+MARKDOWN = "markdown"
+RST = "rst"
+ASCIIDOC = "asciidoc"
+PLAINTEXT = "plaintext"
+```
+
+Add to `SymbolType` enum:
+```python
+SECTION = "section"
+HEADING = "heading"
+SUBHEADING = "subheading"
+PARAGRAPH = "paragraph"
+```
+
+### 2. New DocumentParser Service
+**`src/personality/services/doc_parser.py`** (NEW FILE)
+
+Create `DocumentParser` class with:
+- `DOC_EXTENSION_MAP`: Maps `.md`, `.rst`, `.txt`, `.adoc` to Language enums
+- `parse_file()`: Dispatches to format-specific parser
+- `_parse_markdown()`: Header-based parsing (ATX `#` and setext underlines)
+- `_parse_rst()`: Underline-based header parsing
+- `_parse_asciidoc()`: `=` prefix header parsing
+- `_parse_plaintext()`: Paragraph-based chunking (fallback)
+- `_sections_to_symbols()`: Converts DocSection to Symbol with parent hierarchy
+
+Key design: Each section stores parent heading context (e.g., "Installation > Prerequisites") for better semantic search.
+
+### 3. Extension Map Update
+**`src/personality/services/ast_parser.py`**
+
+Add to `EXTENSION_MAP` (after line 141):
+```python
+# Documentation extensions
+".md": LangEnum.MARKDOWN,
+".markdown": LangEnum.MARKDOWN,
+".rst": LangEnum.RST,
+".txt": LangEnum.PLAINTEXT,
+".text": LangEnum.PLAINTEXT,
+".adoc": LangEnum.ASCIIDOC,
+".asciidoc": LangEnum.ASCIIDOC,
+```
+
+Add helper:
+```python
+DOC_LANGUAGES = {LangEnum.MARKDOWN, LangEnum.RST, LangEnum.ASCIIDOC, LangEnum.PLAINTEXT}
+
+def is_doc_language(lang: LangEnum) -> bool:
+    return lang in DOC_LANGUAGES
+```
+
+### 4. ProjectIndexer Updates
+**`src/personality/services/project_indexer.py`**
+
+| Method | Change |
+|--------|--------|
+| `__init__` | Add `self._doc_parser = DocumentParser()` |
+| `_index_file` | Check `is_doc_language()`, use DocumentParser for docs |
+| `_store_symbol` | Add `is_doc` param, use `doc.{type}.{path}` category prefix |
+| `_delete_file_data` | Add `category_type` param ("code" or "doc") |
+| `search` | Add `search_type` param ("all", "code", "doc") |
+| `remove_project_index` | Delete both `code.*` and `doc.*` categories |
+
+### 5. Service Exports
+**`src/personality/services/__init__.py`**
+
+Add `DocumentParser` to exports.
+
+### 6. Tests
+**`tests/test_services/test_doc_parser.py`** (NEW FILE)
+
+Test cases:
+- Markdown ATX headers (`#`, `##`, `###`)
+- Markdown setext headers (underlines)
+- RST underline headers
+- AsciiDoc `=` prefix headers
+- Plain text paragraph splitting
+- Parent hierarchy preservation
+- Empty file handling
+- Language detection
+
+## Category Structure
+
+| Type | Category Pattern | Example |
+|------|-----------------|---------|
+| Code | `code.{symbol}.{path}` | `code.function.src/utils.py` |
+| Docs | `doc.{section}.{path}` | `doc.heading.docs/README.md` |
+
+## Verification
+
+1. Run type check: `just types`
+2. Run tests: `just test -k "doc_parser"`
+3. Manual test:
+   ```bash
+   personality project index /path/to/project --force
+   personality project search "installation instructions"
+   ```
+4. Verify memories are stored with `doc.*` categories in database

package/plans/recursive-questing-engelbart.md

@@ -0,0 +1,65 @@
+# Plan: Remove Explicit CivitAI Command Naming - Use Provider Pattern
+
+## Summary
+
+Refactor CLI to remove explicit `civitai` command naming. All CivitAI functionality should be accessed through generic commands with `--provider civitai` option (which is already the default).
+
+## Current State
+
+- **Main CLI (`src/prompts/cli.py`)**: Already has provider-aware commands (`search`, `tags`, `identify`) with `--provider` option
+- **CivitAI CLI (`src/prompts/civitai/cli.py`)**: Has `civitai` command group with subcommands
+- **Problem**: Both paths work, creating duplication:
+  - `prompts search illustrious` → provider pattern ✓
+  - `prompts civitai search illustrious` → explicit naming (to remove)
+- **Slash command** `civitai/identify.md` uses explicit `prompts civitai identify`
+
+## Changes Required
+
+### 1. Remove civitai subcommand registration from main CLI
+
+**File:** `src/prompts/cli.py:185`
+
+Remove line:
+```python
+main.add_command(civitai)
+```
+
+This stops exposing `prompts civitai` as a command group. The underlying functions remain available internally.
+
+### 2. Update slash command to use provider pattern
+
+**File:** `.claude/commands/civitai/identify.md`
+
+Change from:
+```bash
+uv run prompts civitai identify $ARGUMENTS
+```
+
+To:
+```bash
+uv run prompts identify $ARGUMENTS
+```
+
+Also update examples to use `prompts identify` instead of `prompts civitai identify`.
+
+### 3. Move slash command out of civitai directory
+
+Rename/move:
+- `.claude/commands/civitai/identify.md` → `.claude/commands/models/identify.md`
+
+This groups it with other model-related commands and removes the civitai-specific directory.
+
+## Files to Modify
+
+| File | Change |
+|------|--------|
+| `src/prompts/cli.py` | Remove `main.add_command(civitai)` |
+| `.claude/commands/civitai/identify.md` | Delete after creating new file |
+| `.claude/commands/models/identify.md` | Create with updated content |
+
+## Verification
+
+1. Test that `prompts civitai search` no longer works (removed)
+2. Test that `prompts search` still works (provider pattern)
+3. Test that `prompts identify` still works
+4. Test `/models:identify` slash command