# Phase 21C - Story Intelligence Illustration Library and Generation Studio

## Summary

Phase 21C adds an admin-only Illustration Library for reusable Story Intelligence visual identifiers. Library illustrations are representative visual identifiers for categories such as characters, locations and assets. They are not canonical manuscript-specific artwork and must not include private manuscript text, names or excerpts in provider prompts.

## Architecture

- `IllustrationLibraryItems` stores durable library records, generation history, approval state, prompt audit data, provider metadata and file metadata.
- `IllustrationGenerationSpecification` is the structured request model. Admins work from planned specs rather than writing raw prompts.
- `IllustrationPromptBuilder` converts a spec into the versioned template `21C.1`, preserving both the prompt and original spec for audit.
- `IIllustrationImageProvider` abstracts image generation. `OpenAIIllustrationImageProvider` uses server-side configuration only.
- `IllustrationGenerationWorker` processes queued items in the background, one item at a time, so browser sessions do not need to remain open.
- `IIllustrationLibraryStorageService` writes generated WebP images and thumbnails under the persistent uploads root.

## Database

The SQL script is `PlotLine/Sql/135_Phase21C_IllustrationLibrary.sql`.

The primary table is `dbo.IllustrationLibraryItems`. It records category, stable code, display title, description, metadata JSON, generation spec JSON, file paths, dimensions, file size, MIME type, lifecycle status, approval details, provider/model/request IDs, prompt text, prompt template version, attempts, parent lineage, rejection/admin notes, usage count and timestamps.

Statuses are:

- `Planned`
- `Queued`
- `Generating`
- `Generated`
- `Approved`
- `Rejected`
- `Failed`
- `Disabled`

Stored procedures support list, summary, get, upsert planned spec, queue, claim next queued item, mark generated, mark failed, approve, reject, disable, update metadata and list approved items.

## Storage

Generated files are stored below:

`/uploads/story-intelligence-library/{characters|locations|assets}/{stable-code}/`

The service writes WebP standard images and 256px thumbnail crops. Existing character, asset, floor-plan and cover uploads are unchanged.

## Provider And Configuration

Image generation uses the existing OpenAI/Story Intelligence options pattern:

- `OpenAI:ApiKey`
- `StoryIntelligence:ImageGenerationModel`
- `StoryIntelligence:ImageGenerationSize` optional, defaulting to `1024x1024`

If configuration is missing, the app starts normally and the Studio shows a clear not-configured message. Queue items will fail individually with a stored error instead of breaking startup.

## Admin Studio

The Studio route is:

`/admin/story-intelligence/illustration-library`

It is protected by the existing `AdminOnly` policy. The page shows counts, filters, grid cards, preview image, prompt/metadata audit data, provider/model/date state, and actions for starter planning, queuing, approval, rejection, disabling and metadata notes.

Costly generation actions require confirmation in the UI. Normal Story Intelligence imports do not trigger image generation.

## Starter Definitions

The starter batch contains 28 generic reusable specs:

- 12 character identifiers
- 6 location identifiers
- 10 asset identifiers

The specs are intentionally generic. They include representative subjects such as a young observer, witness, weathered man, estate house exterior, small flat interior, folded letter, worn notebook and red classic car.

## Prototype Integration

`/Development/StoryIntelligenceExperience` now carries stable library codes for prototype characters, locations and assets. The prototype keeps its existing SVG mock imagery as fallback. If an approved library item exists for a matching code, the approved uploaded illustration is used instead.

No real Story Intelligence pipeline data is connected to the library in this phase.

## Approval And Regeneration

Approval is explicit. Generated images do not become visible to the prototype until an admin approves them.

Regeneration is represented by re-queueing eligible planned, rejected or failed records and retaining previous generation metadata. Parent lineage fields are present for fuller future regeneration history.

## Security And Privacy

- Admin route only.
- Provider calls are server-side only.
- Secrets are not stored in source, JavaScript, SQL or docs.
- Prompt template forbids text, logos, watermarks, manuscript excerpts, real names and private manuscript details.
- Tests do not make paid provider calls.

## Deferred CRUD Integration

The library is prepared for future links to real character, location and asset CRUD through stable codes and usage counts. This phase does not alter existing entity upload workflows or Story Intelligence import behaviour.

## How To Run The Starter Batch

1. Apply `PlotLine/Sql/135_Phase21C_IllustrationLibrary.sql`.
2. Open `/admin/story-intelligence/illustration-library`.
3. Choose `Create starter plan`.
4. Confirm `Queue planned items` only after image generation configuration is present and cost is expected.
5. Review generated images and approve only the reusable identifiers that meet the style and privacy requirements.