# skald

Long-form story-writer with canon-keeping, sequel continuity, and
(future) self-hosted audiobook narration. Database is the source of
truth — the writer is the tooling.

Named for the Old Norse poets who composed and memorized kings'
sagas across generations.

## Status: v0.1 — scaffold

What's wired:

- Rust workspace (`skald-core` + `skald`)
- Postgres schema for stories, characters, canon facts, chapters,
  passages, generation runs, audit findings, tags
- pgvector extension installed for future similarity search
- `skald import-markdown` ingests a story file (chapters + bible)
  into the schema
- `skald serve` exposes `/health` and runs migrations on boot
- Single-container deploy: postgres + skald in one image

Wired (this commit):

- clawdforge Rust SDK vendored at `vendor/clawdforge/` (upstream:
  `Sulkta-Coop/clawdforge` `clients/rust/`)
- `skald-core::forge` — three-pass orchestration shell (gen / cleanup /
  audit). Prompts are TODO stubs; pipeline plumbing is in place.

Not yet wired:

- Web UI (the inbox + browse + queue surface)
- Prompt templates for the three passes (heavy prompt-engineering
  work — own session)
- `skald-core::context` — assemble the LLM context blob from DB rows
  (bible + characters + parent prose summaries + similarity-matched
  passages)
- Embeddings backfill + ivfflat index
- TTS sidecar container + post-render audit chain (see
  `docs/tts-pipeline.md`)

## v0.1 smoke

```bash
docker compose -p skald up -d
docker exec skald skald import-markdown \
    --path /seed/coast-down.md \
    --title "The Coast-Down"

curl http://lucy:7780/health
# → { ok: true, db_ok: true, story_count: 1, ... }
```

## Schema (cheat sheet)

```
stories         → meta + status + parent/root for series
characters      → real or fictional, story-scoped
canon_facts     → setting, mystery, theme, rule, historical_anchor, hook
chapters        → full prose body
chapter_summaries → short summaries for cheap context loading
passages        → paragraph-level + embedding vector(1536)
generation_runs → every LLM call logged
audit_findings  → canon audit output (severity + area)
tags            → arbitrary labels
```

## Architecture (v0.1 + the plan)

```
┌─────────────────────────────────┐
│  skald container                │
│  ┌───────────┐  ┌────────────┐  │
│  │ postgres  │  │ skald-rust │  │
│  │ pgvector  │←─│ axum + cli │  │
│  │ localhost │  │ :7780      │  │
│  └───────────┘  └─────┬──────┘  │
└─────────────────────────┼────────┘
                          │ HTTP (future)
                          ↓
                    ┌──────────┐
                    │clawdforge│
                    └─────┬────┘
                          ↓
                     opus calls
```

v1.0+: extract postgres to its own container on db-net. skald
becomes pure stateless rust, connects via `DATABASE_URL`. Migration
is a connection-string change + a network move; the binary doesn't
care where the DB lives.

## License

MIT.