# Scene Management Scripts

Automate the creation and linking of planning and draft files.

---

## Scripts Available

### `create_scene.py`

Creates linked planning and draft files for new scenes.

---

## Quick Start

### 1. Create a New Scene Pair

```bash
# Navigate to your project root
cd /path/to/your/project

# Create a new scene (act 1, chapter 1, scene 2)
python scripts/create_scene.py --act 1 --chapter 1 --scene 2 --title "Chapter Two: The Journey"
```

This creates:
- `05-Plot/act_1/scene_02.md` (planning template)
- `06-First Draft/Act 1/scene02.md` (draft file)
- Both files are automatically linked to each other

### 2. Create Draft from Existing Planning

```bash
# If you have an existing planning file but no draft
python scripts/create_scene.py --from-planning 05-Plot/act_1/scene_01.md
```

This creates the corresponding draft file and links it.

### 3. Create Planning from Existing Draft

```bash
# If you have an existing draft file but no planning
python scripts/create_scene.py --from-draft "06-First Draft/Act 1/scene01.md"
```

This creates the corresponding planning file and links it.

---

## Usage Examples

### Minimal (auto-generates title)
```bash
python scripts/create_scene.py --scene 3
```
Creates scene 3 in act 1, chapter 1 with title "Chapter 1: Scene 3"

### Full specification
```bash
python scripts/create_scene.py \
    --act 2 \
    --chapter 3 \
    --scene 5 \
    --title "Chapter Three: The Revelation" \
    --type chapter
```

### Batch create multiple scenes
```bash
for scene in {2..10}; do
    python scripts/create_scene.py --chapter 1 --scene $scene
Done
```

---

## File Structure

### Planning Files (`05-Plot/`)
```
05-Plot/
├── _template.md              # Template for new planning files
├── act_1/
│   ├── scene_01.md           # Planning for act 1, scene 1
│   ├── scene_02.md           # Planning for act 1, scene 2
│   └── ...
├── act_2/
│   ├── scene_01.md
│   └── ...
└── act_3/
    └── ...
```

Each planning file contains:
- YAML frontmatter with metadata (act, chapter, scene, word count targets, etc.)
- `draft_file` field pointing to the corresponding draft file
- Scene planning sections (setup, reveal, notes)

### Draft Files (`06-First Draft/`)
```
06-First Draft/
├── _template.md              # Template for new draft files
├── Act 1/
│   ├── scene01.md           # Draft for act 1, scene 1
│   ├── scene02.md           # Draft for act 1, scene 2
│   └── ...
├── Act 2/
│   ├── scene01.md
│   └── ...
└── Act 3/
    └── ...
```

Each draft file contains:
- YAML frontmatter with metadata
- `planning_template` field pointing to the corresponding planning file
- Word count tracking (current, session, target from planning)
- Actual scene content

---

## Linking System

The two files are linked via relative paths in their frontmatter:

**Planning file (`05-Plot/act_1/scene_01.md`):**
```yaml
---
draft_file: "../../06-First Draft/Act 1/scene01.md"
---
```

**Draft file (`06-First Draft/Act 1/scene01.md`):**
```yaml
---
planning_template: "../../05-Plot/act_1/scene_01.md"
---
```

This bidirectional linking allows:
- Navigating from planning to draft and vice versa
- Sharing metadata between files
- Tracking progress across both

---

## Metadata Reference

### Planning File Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier (e.g., `scene_01_01_01`) |
| `title` | string | Scene/chapter title |
| `slug` | string | URL-friendly identifier |
| `act` | int | Act number |
| `chapter` | int | Chapter number |
| `scene` | int | Scene number |
| `type` | string | `scene` \| `chapter` \| `interlude` |
| `status` | string | `planning` \| `ready` \| `blocked` |
| `word_count_target` | int | Target word count |
| `word_count_min` | int | Minimum acceptable words |
| `word_count_max` | int | Maximum acceptable words |
| `pov` | string | Point of view character |
| `characters` | list | Characters in this scene |
| `setting` | string | Primary location |
| `date` | string | Date in story timeline |
| `time` | string | Time of day |
| `conflict` | string | Central conflict |
| `theme` | string | Thematic focus |
| `tone` | string | Emotional tone |
| `draft_file` | string | Path to linked draft file |
| `order` | int | Sort order |

### Draft File Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique identifier (e.g., `draft_scene_01_01_01`) |
| `title` | string | Scene/chapter title |
| `slug` | string | URL-friendly identifier |
| `act` | int | Act number |
| `chapter` | int | Chapter number |
| `scene` | int | Scene number |
| `type` | string | `draft` |
| `status` | string | `not_started` \| `in_progress` \| `completed` \| `needs_revision` |
| `word_count` | int | Current word count |
| `word_count_updated` | string | Last word count update date |
| `session_word_count` | int | Words written in current session |
| `last_session` | string | Date of last writing session |
| `total_sessions` | int | Number of writing sessions |
| `pov` | string | Point of view character |
| `version` | int | Draft version |
| `planning_template` | string | Path to linked planning file |

---

## Integration with Your Workflow

### With Drag-and-Drop Reordering

If your editor supports drag-and-drop chapter reordering, the `order` field in the frontmatter is available for sorting. Update this field when reordering scenes.

### With File Watchers

To automatically create corresponding files when a new file is created:

1. **Option A: Use the script manually** (recommended)
   ```bash
   # After creating a planning file manually, run:
   python scripts/create_scene.py --from-planning 05-Plot/act_1/scene_05.md
   ```

2. **Option B: Set up a file watcher**
   Create a watcher script that triggers `create_scene.py` when new files are detected.

3. **Option C: Editor integration**
   If your editor supports custom commands, add a command that calls:
   ```bash
   python scripts/create_scene.py --from-draft "${file}"
   ```

---

## Tips

1. **Naming Convention**
   - Planning: `scene_{number:02d}.md` (e.g., `scene_01.md`, `scene_02.md`)
   - Draft: `scene{number:02d}.md` (e.g., `scene01.md`, `scene02.md`)
   - Note the slight difference (underscore vs. no underscore)

2. **Folder Structure**
   - Planning: `05-Plot/act_{N}/`
   - Draft: `06-First Draft/Act N/`
   - Note the difference in folder naming (act_1 vs. Act 1)

3. **ID Generation**
   - Planning IDs: `scene_{act:02d}_{chapter:02d}_{scene:02d}`
   - Draft IDs: `draft_scene_{act:02d}_{chapter:02d}_{scene:02d}`

4. **Word Count Targets**
   - Set in planning file
   - Displayed in draft file
   - Not automatically synced (manual update or via script)

---

## Troubleshooting

### "Module not found: yaml"
```bash
pip install pyyaml
```

### File paths not working
- Ensure you're running the script from the project root
- Check that the `scripts/` directory is in your project
- Verify relative paths are correct for your folder structure

### Frontmatter not parsing
- Ensure your files start with `---` on the first line
- Ensure there's a closing `---` after the frontmatter
- YAML is sensitive to indentation (use spaces, not tabs)

---

## Advanced Usage

### Custom Metadata

Add any additional fields to the frontmatter:

```bash
python scripts/create_scene.py --scene 1 --custom_field "value"
```

### Bulk Operations

Create multiple scenes at once:

```bash
# Create scenes 1-10 for chapter 1
for i in {1..10}; do
    python scripts/create_scene.py --chapter 1 --scene $i
done
```

### Sync Existing Files

If you have existing files without links, you can manually add the frontmatter:

**Planning file:**
```yaml
---
draft_file: "../../06-First Draft/Act 1/scene01.md"
---
```

**Draft file:**
```yaml
---
planning_template: "../../05-Plot/act_1/scene_01.md"
---
```

---

## Related Files

- `05-Plot/_template.md` - Planning file template
- `06-First Draft/_template.md` - Draft file template
- `03-Story-Bible/` - Story Bible for character/location/lore tracking