novelly/README.md

# Novelly

Software for planning and writing a novel. You outline the book, keep character
dossiers, break chapters into scenes, and draft prose — with a Claude-powered agent
embedded in the app that can read and edit the same data you can, and an MCP server that
exposes that data to Claude Code, Claude Desktop, or any other MCP client.

The point of the three-way arrangement is that there is exactly one source of truth. The
React UI, the embedded agent, and the MCP server all go through the same REST API, so an
edit made from a chat in Claude Code and an edit made by typing in the browser are the
same edit.

## Stack

| Piece | Built with |
|---|---|
| `Novelly.Api` | ASP.NET Core 10 minimal APIs, EF Core 10 + SQLite, Anthropic SDK, OpenAPI |
| `Novelly.AppHost` | .NET Aspire orchestration for the API and the web client |
| `Novelly.ServiceDefaults` | Shared OpenTelemetry, health checks and service discovery |
| `Novelly.Mcp` | MCP stdio server (`ModelContextProtocol`) |
| `Novelly.Web` | React 19, TypeScript, Vite, TanStack Query, Tailwind v4 |

The back end is one project organised by feature, not by layer. Each feature folder —
`Projects/`, `Characters/`, `Chapters/`, `Beats/`, `Scenes/`, `Tags/`, `Agent/` — holds its
entity, DTOs, service and endpoints together, so adding a capability means touching one
folder rather than four. `Common/` holds what genuinely crosses features and `Data/` holds
the `DbContext` and migrations.

## Running it

Prerequisites: .NET 10 SDK and Node 20+.

Everything at once, through Aspire:

```bash
cd src/Novelly.Web && npm install && cd -
dotnet run --project src/Novelly.AppHost
```

That starts the API on :5080 and the Vite dev server on :5173, and opens the Aspire
dashboard for logs, traces and metrics across both.

Or run the two halves separately:

```bash
# 1. API — creates and migrates novel.db on first run, listens on :5080
ASPNETCORE_URLS=http://localhost:5080 dotnet run --project src/Novelly.Api

# 2. Web — dev server on :5173, proxies /api to :5080
cd src/Novelly.Web && npm install && npm run dev
```

Open http://localhost:5173.

The app is fully usable without an Anthropic key — only the Agent tab needs one. To turn
the agent on:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
```

Without it, agent endpoints return `503 Agent unavailable` with an explanatory message
and everything else keeps working.

### Tests

```bash
dotnet test                             # 73 tests
cd src/Novelly.Web && npm run build     # typecheck + bundle
```

`git push` runs both through a Husky pre-push hook (`scripts/ci/prepush.sh`). Install the
hook once with `npm install` at the repo root.

Tests run against real in-memory SQLite rather than the EF in-memory provider, so they
exercise the cascade deletes and query translation the app actually ships with.

## Configuration

`src/Novelly.Api/appsettings.json`:

```jsonc
{
  "ConnectionStrings": { "Novel": "Data Source=novel.db" },
  "Cors": { "Origins": [ "http://localhost:5173" ] },
  "Agent": {
    "Model": "claude-opus-5",
    "MaxTokens": 16000,
    "Effort": "high",        // low | medium | high | max
    "MaxIterations": 12      // tool-call ceiling per user turn
  }
}
```

The API key is read from `ANTHROPIC_API_KEY` or, if you prefer, `Agent:ApiKey` — keep it
out of `appsettings.json` and use user-secrets or the environment.

## The data model

```
Project ──┬── Character ──┬── CharacterRelationship
          │               └── CharacterArcStage  (the arc: flat, ordered)
          ├── Chapter ──┬── Beat   (the outline: flat, ordered)
          │             └── Scene  (the prose)
          ├── Tag  (applied to characters, chapters and beats)
          ├── OpenQuestion  (attached to a chapter and/or a character)
          └── AgentConversation ── AgentMessage
```

**A chapter outline is a paragraph plus a table.** The paragraph is the chapter's
`Summary`; the table is its beats. Each beat is one row:

| Column | What goes in it |
|---|---|
| Beat | A three-to-five word handle — "she burns the atlas", not a sentence |
| Character | Whose beat it is. Optional; not every beat belongs to one person |
| What happened | The event itself |
| What's next | What it sets in motion — the hook into the following beat |
| Scene | Optional grouping: which scene will carry this beat's prose |

Beats are flat and ordered by `SortOrder` within their chapter. There is no nesting and
no tree — reordering is one call that takes the beat ids in the order wanted.

**Beats plan; scenes carry prose.** The two layers are deliberately separate: an outline
is for working out what happens, and a scene is where you write it. A beat's `SceneId` is
the optional link between them, and it is nullable in both directions — deleting a scene
ungroups its beats rather than deleting the plan.

**Main characters carry the book; supporting characters hold it up.** A character's
`Importance` (`Main` or `Supporting`) is separate from their `Role` — role is the part they
play in the story, importance is how much of it they take, and a mentor can be either.
Characters start supporting and get promoted. The two together drive the ordering, so the
protagonist is always the first name on the list.

**A main character's arc is a table, not a paragraph.** `ArcSummary` still holds the
sentence version; `CharacterArcStage` breaks the same change into ordered steps, each
optionally pinned to the chapter it lands in. It is the same flat-and-ordered shape as the
beat table, for the same reason. Nothing refuses an arc on a supporting character —
demoting someone should not delete their work.

**The character page reads the outlines back.** `GET /api/characters/{id}/beats` returns
every beat a character appears in, in manuscript order, each carrying its chapter so the
page links straight into that chapter's outline. It is the dossier's reality check: what
they actually do on the page, as against what the sheet claims about them.

**Open questions are what you have not decided.** A question hangs off a chapter outline, a
character, both, or neither. It can be resolved, reopened or deleted, and resolving can
append the decision to the notes of whatever it was attached to — so a settled question ends
up where you re-read it rather than in a list you have stopped looking at. Resolved
questions drop off the list unless you ask for them.

**Tags cross-reference the book.** A tag is scoped to one project, unique by name
(case-insensitively), and can be attached to any character, chapter or beat. Applying an
unknown tag by name creates it, so tagging is one action rather than two. `GET
/api/tags/{id}/references` returns everything carrying a tag, which is how you trace a
motif or a thread across all three kinds at once.

## The embedded agent

`NovelAgentService` runs the tool-use loop: it calls the Messages API, executes any tools
Claude asks for, feeds every result back in a single user turn, and repeats until Claude
stops asking. It has 29 tools covering the brief, characters and their arcs, chapter outlines
(beats), scenes, tags and open questions — all of them going through the same application
services the REST API uses.

A few deliberate choices worth knowing about:

- **Conversation history replays as text only.** Tool calls are not replayed into the
  transcript. The agent re-reads current state through its tools instead, which is more
  reliable than trusting a record of edits that may since have changed in the UI.
- **The user's turn is persisted before the loop runs**, so a question is recorded even if
  the model call fails.
- **Tool failures come back as `is_error` results**, not exceptions — the model reads the
  message and corrects itself.
- **`MaxIterations` caps tool calls per turn.** On hitting it the agent says so rather
  than silently truncating.
- **The system prompt is cached** (`cache_control: ephemeral`), so every turn after the
  first reads it back at a fraction of the input price.

## The MCP server

A stdio MCP server exposing 38 tools over the same REST API. It holds no domain logic of
its own — it is a second front end, not a second implementation.

Build it, then point your MCP client at the produced binary:

```bash
./scripts/publish-mcp.sh
```

Aspire does not run or manage this process — it's a separate stdio subprocess your MCP
client spawns directly, so nothing rebuilds it automatically. Re-run the script (and
reconnect your MCP client) after pulling changes that touch `src/Novelly.Mcp`, or it keeps
serving whatever was published last, including against a stale auth contract.

Copy `.mcp.json.example` to `.mcp.json` (gitignored, since it carries your API key) and
fill in the key:

```jsonc
{
  "mcpServers": {
    "novelly": {
      "command": "/absolute/path/to/mcp-server/Novelly.Mcp",
      "env": {
        "NOVELLY_API_URL": "http://localhost:5080",
        "NOVELLY_API_KEY": "<matches the API's Auth:ServiceApiKey user secret>"
      }
    }
  }
}
```

The API must be running, with `Auth:ServiceApiKey` set (e.g. via
`dotnet user-secrets set Auth:ServiceApiKey <key> -p src/Novelly.Api`) to the same value
as `NOVELLY_API_KEY` above. If the API is not running, or the key is missing or mismatched,
the tools say so in a message the model can act on rather than failing opaquely.

### Importing an existing outline

`.claude/agents/outline-importer.md` is a Claude Code subagent that reads an author's outline
already on disk — chapter files and character dossiers in the folder shape described in that
file — and writes it into a new Novelly project over the MCP server above. It's read-only against
the source files and keeps a resumable ledger (`.novelly-import.json`) next to them, since a full
book is more tool calls than fit in one turn. Invoke it with the source folder path once the API is
running and `.mcp.json` is set up.

## API surface

`GET /api/health`, plus:

| Resource | Routes |
|---|---|
| Projects | `GET\|POST /api/projects`, `GET\|PATCH\|DELETE /api/projects/{id}` |
| Characters | `GET\|POST /api/projects/{id}/characters`, `GET\|PATCH\|DELETE /api/characters/{id}`, `POST /api/characters/{id}/relationships` |
| Chapters | `GET\|POST /api/projects/{id}/chapters`, `GET\|PATCH\|DELETE /api/chapters/{id}` |
| Beats | `GET\|POST /api/chapters/{id}/beats`, `POST /api/chapters/{id}/beats/reorder`, `GET\|PATCH\|DELETE /api/beats/{id}` |
| Scenes | `GET\|POST /api/chapters/{id}/scenes`, `GET\|PATCH\|DELETE /api/scenes/{id}` |
| Tags | `GET\|POST /api/projects/{id}/tags`, `GET /api/tags/{id}/references`, `PATCH\|DELETE /api/tags/{id}` |
| Arcs | `GET\|POST /api/characters/{id}/arc`, `POST /api/characters/{id}/arc/reorder`, `GET\|PATCH\|DELETE /api/arc-stages/{id}` |
| Questions | `GET\|POST /api/projects/{id}/questions`, `GET\|PATCH\|DELETE /api/questions/{id}`, `POST /api/questions/{id}/resolve`, `POST /api/questions/{id}/reopen` |
| Agent | `GET /api/projects/{id}/agent/conversations`, `POST /api/projects/{id}/agent/messages`, `GET\|DELETE /api/conversations/{id}` |

`PATCH` bodies are partial: an omitted field is left alone, an empty string clears it. A
`tags` array replaces that item's tags outright and creates any names the project has not
seen; omitting it leaves tags untouched.
Enums travel as names (`"Protagonist"`, `"Drafted"`), never ordinals. In development the
OpenAPI document is at `/openapi/v1.json`.

## Known issues

- `react-router-dom` 7.18.2 carries [GHSA-qwww-vcr4-c8h2](https://github.com/advisories/GHSA-qwww-vcr4-c8h2)
  (CSRF bypass in RSC mode). No patched release exists yet, and every version below the
  affected range carries 14 worse advisories. This app is a client-only SPA and does not
  use RSC mode, so the advisory does not apply — but `npm audit` will flag it until a fix
  ships. Upgrade when one does.

## Where this could go next

The vertical slice is complete but thin in places. The obvious next steps:

- Stream agent responses over SSE instead of returning the finished turn.
- Drag-and-drop beat reordering (the reorder endpoint is already there; the UI uses
  up/down buttons).
- Filter chapters and characters by tag from the list views, not just the Tags tab.
- A manuscript export (Markdown, DOCX) built from chapters and scenes in order.
- Revision history for scene prose.
- Authentication, if this is ever going to run anywhere but localhost.