Add step 2 detailed implementation plan

docs/step1.md

@@ -1,7 +1,3 @@
-I now have a complete understanding of all the constraints. Here is the detailed implementation plan for Step 1:
-
----
-
 # Step 1 Implementation Plan: `config.py` + `models.py` + `db.py`
 
 ## Purpose
@@ -573,4 +569,4 @@ Explicitly out of scope to prevent scope creep:
 
 ---
 
-This plan produces a fully tested, importable data foundation. Every subsequent step imports from `transcription.config`, `transcription.models`, and `transcription.db` without modification. When you're ready, switch to **Agent mode** and I'll implement it.
+This plan produces a fully tested, importable data foundation. Every subsequent step imports from `transcription.config`, `transcription.models`, and `transcription.db` without modification.

docs/step2.md

@@ -0,0 +1,155 @@
+Great—here’s a **detailed implementation plan for Step 2** based on your docs and current project state.
+
+## Step 2 Goal
+
+Implement the MVP prompt artifact system by creating a curated transcription prompt file:
+
+- `prompts/transcribe_document.md`
+
+This step primarily satisfies:
+
+- **REQ-12**: prompts stored as individual Markdown artifacts
+- MVP Feature 3: prompt-driven verbatim transcription behavior grounded in `docs/Intent.md`
+
+---
+
+## Scope for Step 2
+
+### In scope
+1. Create prompt artifact directory and first prompt file.
+2. Encode transcription rules from `docs/Intent.md` into a model-facing prompt.
+3. Define stable prompt structure so future revisions are easy to diff/review.
+4. Add lightweight tests that validate artifact presence and baseline quality constraints.
+5. Update docs/README references so Step 3 can consume prompt file directly.
+
+### Out of scope
+- Provider integration logic (Step 3)
+- Worker/job orchestration (Step 4)
+- UI behavior (Step 5)
+
+---
+
+## Proposed Deliverables
+
+1. **`prompts/transcribe_document.md`**
+   - production prompt text for historical document transcription
+
+2. **`prompts/README.md`** (recommended)
+   - conventions for prompt files, revision policy, naming
+
+3. **`tests/test_prompts.py`** (recommended)
+   - artifact existence + structure checks
+
+4. **Small docs update** (README or docs reference)
+   - indicate that prompts are file-based and loaded from `PROMPT_DIR`
+
+---
+
+## Detailed Work Breakdown
+
+### 1) Create prompt artifact folder and canonical file
+- Add `prompts/` at repo root.
+- Add `transcribe_document.md` as the first curated artifact.
+- Keep filename stable; this becomes the default in Step 3 unless overridden.
+
+### 2) Author prompt content using a strict, sectioned format
+Use section headers so future diffs are clean and policy changes are isolated.
+
+Suggested sections:
+
+1. **Purpose**
+   - verbatim scholarly transcription of historical documents
+
+2. **Output requirements**
+   - plain text only
+   - no summaries, no paraphrasing
+   - preserve reading order and meaningful structure
+
+3. **Core fidelity rules**
+   - preserve original wording and punctuation
+   - don’t silently normalize grammar/spelling
+   - no invented content
+
+4. **Issue-handling rules (mapped from Intent table)**
+   - misspellings with `[sic]`
+   - missing words with `[word]`
+   - uncertainty with `[guess?]`
+   - illegible with `[illegible]` / reason tags
+   - crossed-out text as `[deleted: ...]`
+   - inserted text as `[inserted: ...]`
+   - superscripts handling guidance
+   - non-text elements as `[description]`
+   - marginalia format `[written in left margin: ...]`
+   - line-break hyphen rejoin behavior
+   - capitalization policy
+   - hierarchical outline preservation (including unusual numbering)
+
+5. **Confidence/ambiguity policy**
+   - prefer explicit uncertainty markers over hallucination
+
+6. **Final self-checklist for model**
+   - did I preserve structure?
+   - did I mark uncertain text?
+   - did I avoid silent corrections?
+
+### 3) Add prompt-library conventions (`prompts/README.md`)
+Recommended conventions:
+- one prompt per file
+- snake_case names
+- each file starts with purpose + behavior contract
+- iterative edits, one prompt per PR where possible
+- no secrets in prompt files
+
+### 4) Add tests for prompt assets (`tests/test_prompts.py`)
+Keep tests robust but not brittle.
+
+Recommended tests:
+1. `test_prompt_file_exists`
+2. `test_prompt_file_is_not_empty`
+3. `test_prompt_mentions_verbatim_behavior`
+4. `test_prompt_includes_uncertainty_and_illegible_markers`
+5. `test_prompt_includes_deleted_and_inserted_conventions`
+
+Avoid exact full-text matching; verify key semantic anchors only.
+
+### 5) Optional config alignment check
+Current config already has:
+- `prompt_dir: Path = Path("./prompts")`
+
+In Step 2, ensure docs reflect this and that Step 3 will resolve:
+- `PROMPT_DIR / "transcribe_document.md"`
+
+---
+
+## Acceptance Criteria (Definition of Done)
+
+Step 2 is complete when all are true:
+
+1. `prompts/transcribe_document.md` exists and is committed.
+2. Prompt includes all critical handling rules from `docs/Intent.md`.
+3. Prompt is structured with stable section headings for future curation.
+4. Prompt tests pass under `uv run pytest -q`.
+5. Existing tests remain green (total suite still passes).
+6. Docs indicate prompt artifact location and curation policy.
+
+---
+
+## Risks and Mitigations
+
+1. **Risk: prompt too vague → hallucinated reconstructions**
+   - Mitigation: explicit uncertainty/illegible conventions and “no invention” rule.
+
+2. **Risk: prompt too rigid for mixed document types**
+   - Mitigation: include neutral defaults + clear annotation formats.
+
+3. **Risk: brittle tests block iterative prompt tuning**
+   - Mitigation: test semantic anchors, not exact wording.
+
+---
+
+## Handoff to Step 3
+
+After Step 2, Step 3 can immediately:
+1. Load `transcribe_document.md` from `PROMPT_DIR`
+2. Inject prompt into OpenRouter request
+3. Start validating real transcription behavior with minimal glue code