StoryCADAPI

Documentation and samples for the StoryCADLib API.

What is StoryCADLib?

StoryCADLib is the core library that powers StoryCAD, a free outlining tool for fiction writers. The library is available as a NuGet package for developers who want to:

• Build tools that create or manipulate story outlines (.stbx files)
• Integrate story structure into AI agents via Semantic Kernel
• Automate story analysis and validation
• Create custom writing assistants

Documentation

View Full Documentation (coming soon)

• Getting Started - Installation and first API call
• Quick Start Tutorial - Build an outline in 5 minutes
• API Reference - Complete method documentation

Repository Setup

Samples reference StoryCADLib via ProjectReference, so you need both repos as siblings:

dev/src/
  StoryCAD/          # Main application + StoryCADLib
  StoryCADAPI/       # This repo (docs + samples)

cd your-dev-directory
git clone https://github.com/storybuilder-org/StoryCAD.git
git clone https://github.com/storybuilder-org/StoryCADAPI.git

Prerequisites

• .NET 10.0 SDK
• OpenAI API key (for Semantic Kernel samples only)

Quick Start

Installation (NuGet)

dotnet add package StoryCADLib

Minimal Example

using StoryCADLib.Services.IoC;
using StoryCADLib.Services.API;
using CommunityToolkit.Mvvm.DependencyInjection;

// Initialize (once at startup)
BootStrapper.Initialise(headless: true);

// Get the API
var api = Ioc.Default.GetRequiredService<SemanticKernelApi>();

// Create a new outline
var result = await api.CreateEmptyOutline("My Story", "Author Name", "0");
if (result.IsSuccess)
{
    Console.WriteLine($"Created outline with {result.Payload.Count} elements");
}

// Add a character
var charResult = api.AddElement(
    StoryItemType.Character,
    result.Payload[0].ToString(),  // Parent GUID (story overview)
    "Alex",
    "The protagonist");

// Save to file
await api.WriteOutline("my-story.stbx");

Samples

Core Samples (no API key required)

Sample	Description
StoryGraphBasics	Create, populate, link, save and reload an outline (10 API methods)
StoryMetrics	Analytics dashboard: element counts, character appearances, setting usage
ConsistencyValidation	6 validation checks detecting story issues (orphan characters, unused settings, etc.)

Semantic Kernel Samples (require OPENAI_API_KEY)

Sample	Description
StoryDiagnosticAgent	LLM-powered diagnosis of pacing, passive protagonist, plot holes
StoryCADCritter	LLM scores an outline against 5 craft criteria with rubric

Other

Sample	Description
StoryCADChat	Console app for natural language interaction with outlines via LLM
HeadlessTest	Verification harness: 7-step round-trip test of headless API

Building and Running Samples

All samples target net10.0-desktop and use Uno SDK:

cd samples/StoryGraphBasics
dotnet build -f net10.0-desktop
dotnet run -f net10.0-desktop

For Semantic Kernel samples, set your API key first:

# Windows (PowerShell)
$env:OPENAI_API_KEY="your_key_here"

# Linux/Mac
export OPENAI_API_KEY=your_key_here

See .env.example for all environment variables.

Key Concepts

OperationResult Pattern

All API methods return OperationResult<T> - always check IsSuccess before using Payload:

var result = api.GetStoryElement(guid);
if (result.IsSuccess)
{
    var element = result.Payload;
    // Use element...
}
else
{
    Console.WriteLine($"Error: {result.ErrorMessage}");
}

Headless Mode

BootStrapper.Initialise(headless: true) configures the library for use without a UI:

• Console applications
• Web APIs
• Background services
• AI agent integrations

Element Types

Type	Description
StoryOverview	Root element with story metadata
Problem	Conflicts, themes, story questions
Character	Characters in the story
Scene	Individual scenes
Setting	Locations and places
Folder	Organizational containers

Building the Documentation Locally

The documentation site lives in docs/ and is a Jekyll site using the Just the Docs theme. Pages are plain Markdown with YAML front matter that drives the navigation (title, parent, nav_order).

Prerequisites

• Ruby 3.x and Bundler (gem install bundler)

Workflow

# From the repo root — installs gems into docs/ and serves with live reload
cd docs
bundle install
bundle exec jekyll serve --livereload
# → http://localhost:4000/StoryCADAPI/

On Windows you can use the helper script instead:

pwsh serve-docs.ps1        # serves at http://localhost:4000

To produce the static site without serving:

cd docs
bundle exec jekyll build   # output in docs/_site/ (git-ignored)

API Reference

The pages under docs/api/ are hand-curated Markdown. The per-namespace model reference (docs/api/models*.md) was converted from the StoryCADLib XML docs; regenerate it if the public model surface changes.

CI / Deployment

The GitHub Actions workflow (.github/workflows/deploy-docs.yml) builds the site with Bundler/Jekyll and deploys it to GitHub Pages on every push to main that touches docs/.

One-time setup: in repo Settings → Pages, set Source to GitHub Actions. The site then publishes to https://storybuilder-org.github.io/StoryCADAPI/.

Related Projects

• StoryCAD - The main application
• Collaborator - AI plugin for StoryCAD
• StoryCAD Manual - User documentation

License

GNU GPL v3 - See LICENSE for details.

Contributing

Contributions welcome! Please read the contribution guidelines in the main StoryCAD repository.