PlotDirector/docs/phases/Phase-21C-Story-Intelligence-Illustration-Library.md

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.