Harden initial framework skeleton

README.md

@@ -2,29 +2,58 @@
 
 `narratio` is a Go-based orchestration application for processing D&D session audio into transcripts and downstream artifacts.
 
-This repository is currently an **initial scaffold** that establishes:
+This repository currently contains a **working scaffold** with strict config loading, local workdir/manifest handling, resumable stage control, and placeholder adapters/stages.
 
-- Go module and package boundaries
-- Placeholder CLI commands: `run`, `plan`, `status`, `resume`, `run-stage`
-- Basic structured logging setup via `log/slog`
-- Stub adapter, stage, config, manifest, artifact, and contract packages
+## Expected Config Files
 
-## Current State
+`narratio` expects two YAML files:
 
-The CLI commands are intentionally placeholders and print `not yet implemented` messages.
+- `pipeline.yml`: pipeline/workspace settings (`workspace`, `storage`, `whisperx`, `seriatim`, `audita`, `analyzer`, `notification`)
+- `session.yml`: per-session settings (`session_id`, `inputs`, optional metadata)
 
-Example:
+Decoding is strict (`KnownFields(true)`), so unknown YAML fields fail fast.
+
+Example minimal files are available under `examples/`:
+
+- `examples/pipeline.minimal.yml`
+- `examples/session.minimal.yml`
+
+## Current Scaffold Status
+
+Implemented in scaffold form:
+
+- strict config load + validation
+- local artifact/workdir creation and locking
+- manifest create/load/save and stage status tracking
+- stage framework with real `prepare` stage and placeholder downstream stages
+- resumable run control (`run`, `resume`, `run-stage`, `plan` with run/skip decisions)
+- fake/no-op adapters for external tool boundaries
+
+Not implemented yet:
+
+- real WhisperX HTTP integration
+- real Seriatim execution
+- real Audita execution
+- real analyzer integration
+- real remote archive/storage backend
+- real notification backend
+
+## Run Tests
 
 ```bash
-go run ./cmd/narratio plan
+go test ./...
 ```
 
-## Non-Goals (Current Pass)
+## Run Plan
 
-This scaffold does not yet implement:
+```bash
+go run ./cmd/narratio plan --config examples/pipeline.minimal.yml --session examples/session.minimal.yml
+```
 
-- real config loading/validation behavior
-- manifest persistence behavior
-- stage execution behavior
-- real WhisperX/seriatim/audita/analyzer integrations
-- real S3 or notification integrations
+## Run Placeholder Pipeline
+
+The current `run` command executes available scaffold behavior (`prepare` + placeholder stages) and records progress in `manifest.json`.
+
+```bash
+go run ./cmd/narratio run --config examples/pipeline.minimal.yml --session examples/session.minimal.yml
+```