# Novelcrafter-like System in Kirby CMS

## Overview
Replicate core Novelcrafter functionality in Kirby CMS: writing novels with chapters (using blocks), managing codex (characters, locations), and AI-assisted writing via OpenRouter API.

## Goals
- Chapters as subpages with block-based editing
- Codex as page with subpages for characters/locations
- AI integration: Generate text directly in Kirby using context from chapters and codex
- Seamless workflow for novel writing

## Current State Analysis
- Chapter template/blueprint exists with blocks (prose, pull, note, texture, pinned-text, pinned-image)
- Default blueprint has basic blocks (heading, text, image, quote)
- Kirby 5 with languages, debug enabled
- No existing AI plugins
- Home template serves as novel overview

## Proposed Structure

### Page Hierarchy
```
/ (novel overview page)
├── chapter-1/
├── chapter-2/
│   └── ... (flat chapters, not in folder)
└── codex/
    ├── characters/
    │   ├── alice/
    │   └── bob/
    └── locations/
        ├── forest/
        └── castle/
```

### Templates
- `home.php`: Existing, functions as novel overview (title, chapter list, codex link)
- `codex.php`: Display codex overview, lists of characters/locations
- `character.php`: Character details (name, description, traits)
- `location.php`: Location details (name, description, history)
- `chapter.php`: Existing, enhance with AI features

### Blueprints
- `home.yml`: Title, description, author (if needed, or use default)
- `codex.yml`: Title, description
- `character.yml`: Name, description, traits, relationships
- `location.yml`: Name, description, history, significance
- `chapter.yml`: Existing, add new AI tab with:
  - Context selection: Toggle for whole novel (if false, multi-select chapter pages), multi-select codex entries (characters/locations)
  - Prompt textarea
  - Chat structure field (entries with prompt, response, timestamp)

### Plugin: novelcrafter-ai
- Handle OpenRouter API integration
- Add config for OpenRouter API key and default model
- Context building logic (aggregate selected chapter/codex content)
- Add button in AI tab to send prompt and store response in chat structure

## Implementation Steps

### 0. Setup
- Create new git branch for this feature (e.g., `feature/novelcrafter-ai`)

### 1. Define Page Structure and Blueprints
- Create blueprints for novel, codex, character, location
- Update chapter blueprint to include AI-related fields (context sources, system prompt)

### 2. Create Templates
- Implement novel template with chapter navigation
- Implement codex template with subpage lists
- Implement character/location templates
- Enhance chapter template if needed

### 3. Develop AI Plugin
- Create plugin structure
- Add config options (OpenRouter API key, default model)
- Implement API client class for OpenRouter requests
- Build context aggregation function
- Add panel integration (button to generate text)
- Handle response insertion into blocks

### 4. AI Features
- Prompt construction: Aggregate selected context (chapters/codex pages) + user prompt
- Plain text responses stored in chat structure
- Manual copy-paste from chat to chapter blocks
- Error handling and rate limiting

### 5. UI Enhancements
- AI tab in chapter panel with context selectors and chat history
- Generate button to call OpenRouter and add chat entry
- Simple progress indicator during API call

## Technical Considerations
- OpenRouter API: Use chat/completions endpoint, similar to OpenAI
- Security: Store API key securely, validate inputs
- Performance: Aggregate context on demand, handle large content
- Context aggregation: Collect text from selected pages (chapters use blocks, codex use fields)

## Potential Challenges
- Aggregating context from mixed sources (block content vs field content)
- Implementing multi-select page fields in blueprint
- Handling API errors and rate limits in panel
- Ensuring chat structure is user-friendly

## Next Steps
- Confirm blueprint fields (page multi-select, structure for chat)
- Decide on plugin approach (custom panel button or AJAX route)
- Test OpenRouter API integration</content>
<parameter name="filePath">.kilo/plans/1778746362668-crisp-forest.md