chore: refresh coverage badge [skip ci]

The prior commit's git add silently dropped these five files because
one path in the same invocation didn't exist. Docs, solution file, and
example config still needed the paired update: Novelly.slnx drops the
Novelly.Mcp project entry, README and CLAUDE.md describe MCP as an
in-API HTTP endpoint instead of a stdio binary, .mcp.json.example uses
the type: http shape, and outline-importer.md's tool references are
fixed to real tool names.

.claude/agents/outline-importer.md

@@ -1,7 +1,7 @@
 ---
 name: outline-importer
 description: Imports an author's existing novel outline (chapters + character dossiers, in the Kingdom Sleeps folder format) into a Novelly project over the MCP server. Invoke explicitly with a source folder path — this agent does not run proactively.
-tools: Read, Glob, Grep, Write, mcp__novelly__list_projects, mcp__novelly__get_project_brief, mcp__novelly__create_project, mcp__novelly__update_project_brief, mcp__novelly__list_chapters, mcp__novelly__get_chapter, mcp__novelly__create_chapter, mcp__novelly__update_chapter, mcp__novelly__get_chapter_outline, mcp__novelly__create_beat, mcp__novelly__update_beat, mcp__novelly__list_characters, mcp__novelly__get_character, mcp__novelly__create_character, mcp__novelly__update_character, mcp__novelly__get_character_arc, mcp__novelly__add_arc_stage, mcp__novelly__list_tags
+tools: Read, Glob, Grep, Write, mcp__novelly__list_novels, mcp__novelly__get_novel_brief, mcp__novelly__create_novel, mcp__novelly__update_novel_brief, mcp__novelly__list_chapters, mcp__novelly__get_chapter, mcp__novelly__create_chapter, mcp__novelly__update_chapter, mcp__novelly__get_chapter_outline, mcp__novelly__create_beat, mcp__novelly__update_beat, mcp__novelly__list_characters, mcp__novelly__get_character, mcp__novelly__create_character, mcp__novelly__update_character, mcp__novelly__get_character_arc, mcp__novelly__add_arc_stage, mcp__novelly__list_tags
 model: inherit
 ---
 
@@ -101,9 +101,9 @@ in your final report.
 Do not skip ahead — each pass depends on ids the previous one minted. If you're picking up a
 resumed run, jump straight to the first incomplete pass.
 
-**0. Preflight.** Call `list_projects` to confirm the API is reachable at all — if this fails, stop
-and tell the user to start the API (`ASPNETCORE_URLS=http://localhost:5080 dotnet run --project src/Novelly.Api`)
-and that `.mcp.json` must point at a published `Novelly.Mcp` binary. Glob the source root for
+**0. Preflight.** Call `list_novels` to confirm the API is reachable at all — if this fails, stop
+and tell the user to start the API (`ASPNETCORE_URLS=http://localhost:5080 dotnet run --project src/Novelly.Api`).
+Glob the source root for
 `outline.md`, `outlines/*.md` or `chapters/*.md`, and `characters/*.md`. If `outline.md` is
 missing, stop — that's the one file every pass depends on. Report the file counts found before
 proceeding.
@@ -111,7 +111,7 @@ proceeding.
 **1. Project.** Skip if `completedPasses` already has `"project"`. Read `outline.md`. Its heading is
 `# Outline — <Title> (<Author>)` or similar — parse title and author out of it; if there's no
 author, leave it null. The paragraph(s) before the chapter table are the blurb — pass as `notes`
-argument to `create_project` (there's no dedicated blurb field; `synopsis` may be filled in later
+argument to `create_novel` (there's no dedicated blurb field; `synopsis` may be filled in later
 by the author). Record `projectId` in the ledger, mark `"project"` complete.
 
 **2. Characters — dossier fields only, not arcs yet.** Skip files whose name (matched

.github/workflows/ci.yml

@@ -60,6 +60,8 @@ jobs:
       REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
       ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
       WEB_PORT: ${{ vars.WEB_PORT }}
+      API_PORT: ${{ vars.API_PORT }}
+      MCP_API_KEY: ${{ secrets.MCP_API_KEY }}
     steps:
       # actions/checkout@v4 is a Node-based action; this runner has no node in PATH, so
       # checkout plain git instead of via marketplace action.

.mcp.json.example

@@ -1,10 +1,10 @@
 {
   "mcpServers": {
     "novelly": {
-      "command": "./mcp-server/Novelly.Mcp",
-      "env": {
-        "NOVELLY_API_URL": "http://localhost:5080",
-        "NOVELLY_API_KEY": "<matches the API's Auth:ServiceApiKey user secret>"
+      "type": "http",
+      "url": "http://localhost:5080/mcp",
+      "headers": {
+        "X-Novelly-Api-Key": "<matches the API's Auth:ServiceApiKey user secret>"
       }
     }
   }

CLAUDE.md

@@ -8,13 +8,12 @@ Novelly: software plan + write novel. ASP.NET Core 10, C#, TypeScript, React, .N
 
 ## Structure
 
-- `src/Novelly.Api/` — whole back end, organised by feature. One folder per feature holds
-  entity, DTOs, service, endpoints together: `Novels/`, `Characters/`, `Chapters/`, `Beats/`,
-  `Scenes/`, `Tags/`, `Agent/`. `Common/` holds what crosses features; `Data/` holds
-  `DbContext` + EF migrations.
+- `src/Novelly.Api/` — whole back end, organised by feature, plus the MCP endpoint. One folder
+  per feature holds entity, DTOs, service, endpoints together: `Novels/`, `Characters/`,
+  `Chapters/`, `Beats/`, `Scenes/`, `Tags/`, `Agent/`, `Mcp/`. `Common/` holds what crosses
+  features; `Data/` holds `DbContext` + EF migrations.
 - `src/Novelly.AppHost/` — .NET Aspire orchestration; run this to bring up API + web client
 - `src/Novelly.ServiceDefaults/` — shared Aspire wiring: OpenTelemetry, health checks, service discovery
-- `src/Novelly.Mcp/` — MCP stdio server
 - `src/Novelly.Web/` — React + Vite client
 - `tests/` — test suite
 - `docs/` — documentation
@@ -59,6 +58,7 @@ Serilog console via `AddSerilog` (not `UseSerilog` — keeps OTel provider for A
 - `PATCH` requests partial: null field = leave alone, empty string = clear. Keep new update endpoints consistent with `Patch.Apply`.
 - Enums cross wire as names, never ordinals
 - All frontend components should have an id attribute that identifies them uniquely.
+- Web client is keyboard-first: read `docs/keyboard.md` before adding any interactive UI (forms, editable rows, create flows).
 
 ## Testing
 
@@ -85,7 +85,7 @@ Build + tests passing ≠ working. Anything touching endpoint, agent loop, or MC
   Vite dev server on :5173, dashboard for logs + traces
 - API alone: `ASPNETCORE_URLS=http://localhost:5080 dotnet run --project src/Novelly.Api`, then exercise route with curl
 - Web alone: `cd src/Novelly.Web && npm run dev` — proxies `/api` to :5080
-- MCP: build it, then drive over stdio JSON-RPC (`initialize` → `notifications/initialized` → `tools/list` → `tools/call`)
+- MCP: with the API running, drive `/mcp` over HTTP (`initialize` → `notifications/initialized` → `tools/list` → `tools/call`) — Streamable HTTP, so responses are SSE-framed and requests need `Accept: application/json, text/event-stream`
 
 Several real bugs here — SQLite refusing ORDER BY DateTimeOffset, agent's model client throwing at construction + taking read-only endpoints down with it — passed build + test suite, only showed up when app actually ran.
 

Novelly.slnx

@@ -8,7 +8,6 @@
   <Folder Name="/src/">
     <Project Path="src/Novelly.Api/Novelly.Api.csproj" />
     <Project Path="src/Novelly.AppHost/Novelly.AppHost.csproj" />
-    <Project Path="src/Novelly.Mcp/Novelly.Mcp.csproj" />
     <Project Path="src/Novelly.ServiceDefaults/Novelly.ServiceDefaults.csproj" />
     <Project Path="src/Novelly.Web/Novelly.Web.esproj">
       <Build />

README.md

@@ -6,22 +6,21 @@
 
 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.
+embedded in the app that can read and edit the same data you can, and an MCP endpoint that
+exposes that same 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.
+React UI's REST calls, the embedded agent, and MCP clients all resolve to the same
+application services in-process, 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.Api` | ASP.NET Core 10 minimal APIs, EF Core 10 + SQLite, Anthropic SDK, OpenAPI, MCP over Streamable HTTP (`ModelContextProtocol.AspNetCore`) |
 | `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 —
@@ -192,19 +191,10 @@ A few deliberate choices worth knowing about:
 
 ## The MCP server
 
-A stdio MCP server exposing 45 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.
+The API itself serves MCP over Streamable HTTP at `POST /mcp`, exposing 45 tools that call
+the same application services the REST endpoints and the embedded web agent call — it holds
+no domain logic of its own, and there's nothing to build or publish separately. The API
+process just needs to be running; there's no separate subprocess to keep in sync with it.
 
 Copy `.mcp.json.example` to `.mcp.json` (gitignored, since it carries your API key) and
 fill in the key:
@@ -213,10 +203,10 @@ fill in the key:
 {
   "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>"
+      "type": "http",
+      "url": "http://localhost:5080/mcp",
+      "headers": {
+        "X-Novelly-Api-Key": "<matches the API's Auth:ServiceApiKey user secret>"
       }
     }
   }
@@ -225,8 +215,12 @@ fill in the key:
 
 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.
+as the `X-Novelly-Api-Key` header above. If the API is not running, or the key is missing or
+mismatched, the request 401s.
+
+Tool argument names are camelCase, matching the REST API and every other MCP argument name
+this project has ever used. `create_novel` called over MCP is owned by the seeded service
+user (an Admin), not whichever person is signed into the web app.
 
 ### Importing an existing outline
 

badges/coverage.svg

@@ -123,7 +123,7 @@
 
         <text x="53" y="15" fill="#010101" fill-opacity=".3">Coverage</text>
         <text x="53" y="14" fill="#fff">Coverage</text>
-        <text class="" x="132.5" y="15" fill="#010101" fill-opacity=".3">61.9%</text><text class="" x="132.5" y="14">61.9%</text>
+        <text class="" x="132.5" y="15" fill="#010101" fill-opacity=".3">66.5%</text><text class="" x="132.5" y="14">66.5%</text>
         
         
         

deploy/qa/docker-compose.qa.yml

@@ -8,6 +8,7 @@ services:
 
   api:
     image: ${API_IMAGE}:latest
+    container_name: novelly-api
     restart: unless-stopped
     environment:
       ConnectionStrings__Novel: "Data Source=/data/novel.db"
@@ -16,10 +17,13 @@ services:
       Agent__Model: claude-sonnet-5
       Agent__Effort: high
       Imports__RootPath: /data/imports
+      Auth__ServiceApiKey: ${MCP_API_KEY:-}
     volumes:
       - /mnt/storage/apps/novelly/data:/data
     networks:
       - novelly
+    ports:
+      - "${API_PORT:-5080}:8080"
     healthcheck:
       test: ["CMD-SHELL", "curl -fsS http://localhost:8080/api/health || exit 1"]
       interval: 10s
@@ -29,6 +33,7 @@ services:
 
   web:
     image: ${WEB_IMAGE}:latest
+    container_name: novelly-web
     restart: unless-stopped
     depends_on:
       api:

docs/keyboard.md

@@ -0,0 +1,60 @@
+# Keyboard conventions
+
+Novelly's web client is built to be driven entirely from the keyboard. New interactive
+components should follow these rules so the app stays consistent as it grows.
+
+## Escape cancels or closes — it never destroys already-saved work
+
+In an editor that commits per field (a beat row, a chapter's title), Escape reverts only the
+field you're currently in and then closes the editor. Fields you already tabbed past and
+committed stay saved — Escape is honest about this, not a full undo. Anywhere a component *can*
+offer a true "discard everything" cancel (a create form that hasn't saved anything yet), do
+that instead.
+
+## Enter commits a single-line field and advances
+
+Pressing Enter in a single-line field is equivalent to Tab: it commits the field's value and
+moves focus to the next field. Shift+Enter moves to the previous field. This is what
+`AutoField` (`src/components/ui.tsx`) does by default — reuse it rather than hand-rolling a
+text input's key handling.
+
+## mod+Enter commits a multiline field or completes a record
+
+A `<textarea>` needs plain Enter to insert a newline, so multiline fields commit on
+`mod+Enter` (Cmd or Ctrl) instead. The same combo, handled at the row/form level, means "I'm
+done with this record" — closing a beat row, submitting a question. This mirrors the app's
+original convention in `AgentPanel.tsx` (`mod+Enter` sends a message).
+
+## Bare single letters create the primary thing on the page
+
+`n` is the default create-hotkey across the app (new character, new chapter, new location). A
+page with a second creatable thing uses a mnemonic instead (`b` for beat, `q` for question, `a`
+for arc stage). Register these with `useHotkey` from the component that owns the create action,
+so the shortcut is scoped to that page/section and unregisters when it unmounts — never
+register a bare letter globally.
+
+## Creating something puts focus in its first editable field
+
+A create action that leaves the user hunting for the thing they just made is a bug. Land focus
+in the new item's first field (or, when a mutation's response id isn't the field's DOM node
+yet, request focus for that id and let it land once the row/page actually renders — see the
+`focusRequestId`/`onAutoFocused` pattern used for beats and arc stages).
+
+## Chip inputs commit on Enter, comma, or blur
+
+`TagEditor`, `LocationEditor`, `CharacterMultiSelect`, and `AliasEditor` all add their draft
+value to the list on Enter, comma, or losing focus. Follow the same shape for any new
+chip-style input.
+
+## Destructive confirmations use `ConfirmModal`
+
+Never use the native `confirm()`/`alert()` dialogs — they're not stylable, not consistent with
+the rest of the app, and (depending on browser) can be genuinely awkward to dismiss from the
+keyboard. Use `ConfirmModal` (`src/components/ConfirmModal.tsx`), which wraps `Modal` and gets
+focus-trapping and Escape-to-close for free.
+
+## The exception, not the rule: `allowInInputs`
+
+`useHotkey` shortcuts don't fire while a text field is focused, unless registered with
+`allowInInputs: true`. Reserve that for shortcuts that make sense mid-typing (`mod+Enter` to
+submit, `Escape` to close) — never a bare letter.

docs/plans/api/mcp_http_merge_plan.md

@@ -0,0 +1,180 @@
+# Merge the MCP server into Novelly.Api as Streamable HTTP `/mcp`
+
+## Context
+
+Novelly has two duplicate tool surfaces that must be kept in sync by hand:
+
+- **`src/Novelly.Mcp/`** — 45 tools as `[McpServerTool]` static methods, stdio-only, each calling the REST API back over HTTP via `NovelApiClient`. Built by no CI job, in no container, unknown to the AppHost. It only works if someone remembers to run `scripts/publish-mcp.sh` and re-point `.mcp.json` at the published binary. Zero tests.
+- **`src/Novelly.Api/Agent/NovelAgentToolset.cs`** — 33 tools for the embedded web agent, calling application services directly in-process.
+
+The 33 are a **strict subset** of the 45, matching name-for-name. The gap is pure capability loss for the web agent, not a design distinction.
+
+Two problems follow. The MCP server is unreachable from anything but a local stdio subprocess, so the QA deploy can't serve it without shipping a binary around. And every new capability has to be written twice, in two idioms, with nothing enforcing that they agree.
+
+**Outcome:** one tool registry, called directly by both surfaces. The API serves MCP over Streamable HTTP at `/mcp`, so any MCP client reaches it over the network with an API key and no binary to distribute. The stdio project is deleted. The web agent gains all 12 tools it was missing.
+
+## Decisions taken
+
+- **Delete `src/Novelly.Mcp` entirely.** No stdio proxy is kept.
+- **The web agent gets all 45 tools**, including cross-novel `list_novels` and `create_novel`. Full parity, one list, no filtering.
+- **camelCase argument names** everywhere. MCP specifies nothing about argument naming — `inputSchema` is plain JSON Schema — so this is a free choice, and camelCase matches .NET convention, the REST API's `JsonSerializerDefaults.Web` output, and the current MCP surface. Existing MCP clients keep working unchanged. The cost lands on `NovelAgentToolset`'s 33 hand-built schemas, which are today the only snake_case thing in the repo and must be rewritten.
+- **Tool names stay snake_case** (`list_novels`, `get_novel_brief`) — that part *is* genuine MCP convention, and both surfaces already agree on it.
+
+## Design
+
+A single registry — the existing `AgentTool` shape in `NovelAgentToolset`, extended to all 45 tools — with two thin adapters over it.
+
+**MCP adapter.** Register the SDK's dynamic-tools handlers rather than 45 attribute-decorated methods:
+
+```csharp
+services.AddMcpServer(o => o.ServerInfo = new Implementation { Name = "novelly", Version = "1.0.0" })
+    .WithHttpTransport()
+    .WithListToolsHandler((request, ct) => ...)
+    .WithCallToolHandler((request, ct) => ...);
+```
+
+Both handlers resolve `request.Services!.GetRequiredService<NovelAgentToolset>()` per request and delegate to a pure adapter class. This avoids fighting the SDK's schema inference (`McpServerToolCreateOptions` has no `InputSchema` property) and avoids hoisting the scoped, nine-dependency toolset into a static catalog, which `WithTools(IEnumerable<McpServerTool>)` would force.
+
+**Agent adapter.** Unchanged — `NovelAgentService.SendMessageAsync` → `toolset.ExecuteAsync(name, novelId, input, ct)`, with `novelId` still ambient from the route and never shown to the model.
+
+**Novel scoping, one entry / two shapes.** `AgentTool` and `AgentToolDefinition` each gain a trailing `bool RequiresNovelId = false`, so the 33 existing construction sites keep compiling. The MCP adapter injects a required `novelId` property into the advertised schema for those tools and extracts it at call time; the agent adapter supplies it from the route. `list_novels` / `create_novel` need no scope at all.
+
+The 11 currently novel-scoped tools are identifiable mechanically — `grep -n 'async (novelId' src/Novelly.Api/Agent/NovelAgentToolset.cs`: `get_novel_brief`, `update_novel_brief`, `list_characters`, `create_character`, `list_tags`, `list_locations`, `list_chapters`, `create_chapter`, `get_character_beats`, `list_open_questions`, `raise_open_question`. Of the 12 new tools, `create_tag` and `create_location` are novel-scoped; the other ten are child-id-scoped or unscoped.
+
+### Verified before planning
+
+The design rests on SDK behaviour that build-and-test would not catch, so it was checked against a running probe app rather than inferred from docs:
+
+- `WithListToolsHandler` / `WithCallToolHandler` exist in `ModelContextProtocol` 2.1.0; `Tool.InputSchema` is a settable `JsonElement` whose setter validates exactly what `JsonSchemaBuilder.Build()` already emits.
+- **`capabilities.tools` *is* advertised** on `initialize` with handlers and no `ToolCollection` — this was the main open risk and it is closed.
+- **`request.Services` is non-null and yields a fresh DI scope per request** (three calls returned three distinct scope ids). This is what makes the scoped `NovelDbContext` and `NovelAgentToolset` correct here. `HttpServerTransportOptions.Stateless` defaults to `true` and `PerSessionExecutionContext` to `false` in 2.1.0, so no options need restating.
+- A hand-built `JsonElement` schema survives verbatim onto `tools/list` output, and `IsError` maps to `result.isError` rather than a JSON-RPC error object.
+- `GET /mcp` returns 405 in stateless mode. Harmless; clients only POST.
+
+## Chunks
+
+Each builds, tests and commits independently.
+
+### Chunk 0 — Fix the cross-novel conversation leak
+
+Independent; do it first to keep it out of the main diff.
+
+`NovelAgentService.FindConversationAsync(Guid conversationId, ...)` matches on id alone, so a conversation belonging to novel X can be continued under novel Y's route, after which every tool call runs against Y with X's transcript. Add an optional novel filter, passed from `SendMessageAsync` only — `GetConversationAsync`/`DeleteConversationAsync` are reached via `/api/conversations/{id}`, which has no novel in the route, and keep passing `null`. Log the miss at Warning with `{ConversationId}`/`{NovelId}`.
+
+**Files:** `src/Novelly.Api/Agent/NovelAgentService.cs`, `tests/Novelly.Api.Tests/NovelAgentServiceTests.cs`
+
+**Tests:** `Continuing_a_conversation_under_a_different_novel_is_rejected`, plus `Continuing_a_conversation_under_its_own_novel_still_works` as the guard against over-tightening.
+
+### Chunk 1 — One registry, all 45 tools (no MCP wiring yet)
+
+Delivers the parity decision on its own, verifiable through the existing web agent.
+
+- `src/Novelly.Api/Agent/AgentContracts.cs` — add `RequiresNovelId` to `AgentToolDefinition`. Safe: `AnthropicAgentModelClient.ToSdkTool` maps `Name`/`Description`/`InputSchema` explicitly, so the flag never reaches the model.
+- `src/Novelly.Api/Agent/NovelAgentToolset.cs` — add `RequiresNovelId` to `AgentTool`, set it on the 11 tools above, flow it into `Definitions`, and add the 12 new tools reusing the existing `OrNotFound` / `DeletedOrNotFound` / `ToolNotFound` idioms and the descriptions from the corresponding `src/Novelly.Mcp/Tools/*.cs` methods.
+- **Rename the 33 existing schemas to camelCase** in the same file — both the `JsonSchemaBuilder` property keys and the matching `JsonInput` lookup strings, which must stay in lockstep (`.Str("character_id", …)` / `JsonInput.RequiredGuid(input, "character_id")` → `"characterId"`). Mechanical and contained to this one file, but it is the bulk of the chunk's diff and a mismatched pair fails silently as a missing argument rather than a compile error — so the per-tool tests below are what actually catch it. The 12 new tools are written camelCase from the start, matching the names their `src/Novelly.Mcp/Tools/*.cs` equivalents already used.
+
+The 12 new tools and their existing service calls — no service-layer work is needed:
+
+| tool | scope | service call |
+|---|---|---|
+| `list_novels` | none | `novels.ListAsync` |
+| `create_novel` | none | `novels.CreateAsync` |
+| `get_character` | child | `characters.GetAsync` |
+| `relate_characters` | child | `characters.AddRelationshipAsync` — note `CreateRelationshipRequest`'s parameter order differs from the old MCP method's |
+| `set_arc_stage_beats` | child | `arcs.SetBeatsAsync` |
+| `create_tag` | **novel** | `tags.CreateAsync` |
+| `update_tag` / `delete_tag` | child | `tags.UpdateAsync` / `DeleteAsync` |
+| `create_location` | **novel** | `locations.CreateAsync` |
+| `update_location` / `delete_location` | child | `locations.UpdateAsync` / `DeleteAsync` |
+| `update_open_question` | child | `questions.UpdateAsync` |
+
+Guid-list arguments follow the existing `JsonInput.Guids` idiom used by `reorder_beats`.
+
+**Tests:** new `tests/Novelly.Api.Tests/NovelAgentToolsetTests.cs`, driving `ExecuteAsync` directly in the style of `ImportAgentToolsetTests.cs` (`ServiceTestFixture` already wires every service the toolset needs). BDD names, one per new capability — e.g. `Relating_two_characters_shows_the_pair_on_both_dossiers`, `Deleting_a_tag_leaves_the_characters_that_carried_it_alone`, `Updating_an_open_question_can_detach_it_from_its_chapter`. Two structural tests carry the most weight:
+
+- `The_toolset_offers_every_tool_the_stdio_server_offered` — assert the 45 names against a hard-coded array. This is the anti-drift test.
+- Assert no `RequiresNovelId` tool's schema already declares `novelId`, since the MCP adapter injects it and a duplicate would be silent.
+
+**Runtime verify:** AppHost up, open a novel's agent panel, ask it to create a tag and list tags; confirm in the Aspire trace.
+
+### Chunk 2 — Serve the registry at `/mcp`
+
+- `src/Novelly.Api/Novelly.Api.csproj` — add `ModelContextProtocol.AspNetCore` 2.1.0 (brings Core transitively; don't reference it directly). **Not in the local NuGet cache — first restore needs network.** Pin 2.1.0 to match the verified surface.
+- New feature folder `src/Novelly.Api/Mcp/`:
+  - `NovelMcpTools.cs` — the adapter, as pure static methods: `Describe(definitions)` maps to `Tool` records, injecting `novelId` where `RequiresNovelId`; `CallAsync(toolset, parameters, ct)` serializes arguments to a `JsonElement`, extracts `novelId` when required (`Guid.Empty` otherwise), calls `ExecuteAsync`, and maps `AgentToolResult` → `CallToolResult`. Catch the `ArgumentException` from a missing/malformed `novelId` and return it as `IsError` rather than letting it escape as a JSON-RPC error. **Log `{Tool}` and `{NovelId}` only — never the arguments, which carry prose (`what_happened`, `synopsis`, `notes`).**
+  - `McpEndpoints.cs` — `MapNovelMcp()` calling `app.MapMcp("/mcp")`, matching the repo's `Map*Endpoints` convention.
+- `src/Novelly.Api/Common/NovellyServiceRegistration.cs` — the `AddMcpServer(...)` registration shown above.
+- `src/Novelly.Api/Program.cs` — `.MapNovelMcp()` after `UseAuthentication()`/`UseAuthorization()`.
+
+**Auth — the trap.** Do **not** chain `.RequireAuthorization()` onto `MapMcp`. The parameterless overload applies the *default* policy, which authenticates `IdentityConstants.ApplicationScheme` only and would reject the API key. The fallback policy already registered in `NovellyServiceRegistration` lists both that scheme *and* `ServiceApiKeyAuthenticationHandler.SchemeName`, and applies to any endpoint carrying no authorization metadata — which `MapMcp` adds none of. `/mcp` inherits the right protection by doing nothing. If explicitness is wanted, register a named policy listing both schemes; never the parameterless call.
+
+External clients send `X-Novelly-Api-Key: <Auth:ServiceApiKey>`, resolving to `ServiceUser` (Admin), which sees every novel. If `Auth:ServiceApiKey` is unset the service user is never seeded and every call 401s.
+
+CORS needs no change — the origin-restricted default policy is irrelevant to non-browser clients, and stateless mode exposes no `Mcp-Session-Id` header to read.
+
+**Tests:** new `tests/Novelly.Api.Tests/NovelMcpToolsTests.cs`, against the pure adapter methods — no live session, no `WebApplicationFactory`. Cover: all 45 advertised with unique names; novel-scoped tools declare a required `novelId` and child-id tools don't; `list_novels` needs none; every advertised schema is a valid `type: object` (what `Tool.InputSchema`'s setter enforces, worth asserting before the SDK throws at startup); a missing `novelId` and a not-found id both come back as `IsError` results.
+
+**Deliberately not adding a `WebApplicationFactory` harness.** None exists in the repo; adding one means an MVC.Testing reference, overriding the connection string, working around `Program.cs`'s boot-time `MigrateAsync` + `Environment.Exit(1)`, seeding the key, and parsing SSE. Its main payoff — proving the SDK wires up — is delivered more honestly by the curl walkthrough below, which exercises real Kestrel including auth, Serilog and the exception handler. Worth a separate chunk later if a regression harness is wanted.
+
+### Chunk 3 — Delete the stdio server
+
+Only after Chunk 2 is verified, so there's never a window with no MCP surface.
+
+Remove `src/Novelly.Mcp/`, `scripts/publish-mcp.sh`, the `mcp-server/` publish output (gitignored; working-tree cleanup only), and the project line in `Novelly.slnx`. Verified as *not* referencing it: `scripts/ci/build.sh` (publishes the API by path), `prepush.sh`, `test.sh`, both Dockerfiles, the AppHost.
+
+Docs to update:
+- `README.md` — fold the `Novelly.Mcp` stack-table row into the API's; rewrite "The MCP server" section (same 45 tools, now in-process at `POST /mcp`, no build step, `X-Novelly-Api-Key` auth). Note that MCP argument names are unchanged (camelCase), so existing clients need no edits, and that `create_novel` is owned by the signed-in user over the web agent but by the service user over MCP.
+- `.mcp.json` / `.mcp.json.example` — switch to `type: "http"`, `url: http://localhost:5080/mcp`, with the key in `headers`.
+- `.claude/agents/outline-importer.md` — drop the published-binary requirement. Its `tools:` frontmatter is **already stale** (`mcp__novelly__list_projects`, `get_project_brief`, `create_project` exist in neither surface); fix to real names while here.
+- `CLAUDE.md` — the Structure list still calls `src/Novelly.Mcp/` the "MCP stdio server" and Verifying still says "drive over stdio JSON-RPC". Propose these edits rather than slipping them in; CLAUDE.md is user-owned.
+
+Leave `docs/plans/api/users_and_roles_plan.md` alone — historical.
+
+**Verify:** `dotnet build Novelly.slnx` and `./scripts/ci/prepush.sh` both pass.
+
+## Verification
+
+Streamable HTTP needs `Accept: application/json, text/event-stream` and replies SSE-framed, so pipe through `sed -n 's/^data: //p'`.
+
+```bash
+dotnet user-secrets set Auth:ServiceApiKey devkey -p src/Novelly.Api
+ASPNETCORE_URLS=http://localhost:5080 dotnet run --project src/Novelly.Api
+
+MCP=http://localhost:5080/mcp
+H=(-H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "X-Novelly-Api-Key: devkey")
+
+# handshake — expect capabilities.tools present
+curl -sS "${H[@]}" "$MCP" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' | sed -n 's/^data: //p' | jq .
+curl -sS "${H[@]}" -o /dev/null -w '%{http_code}\n' "$MCP" -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
+
+# expect exactly 45
+curl -sS "${H[@]}" "$MCP" -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | sed -n 's/^data: //p' | jq '.result.tools | length'
+
+# novelId injection: present on list_tags, absent on delete_tag and list_novels
+curl -sS "${H[@]}" "$MCP" -d '{"jsonrpc":"2.0","id":3,"method":"tools/list","params":{}}' | sed -n 's/^data: //p' \
+  | jq '.result.tools[] | select(.name=="list_tags" or .name=="delete_tag" or .name=="list_novels") | {name, props:(.inputSchema.properties|keys), required:.inputSchema.required}'
+
+# unscoped call, then a novel-scoped one (proves NovelUserContext resolved the service user in-handler)
+curl -sS "${H[@]}" "$MCP" -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_novels","arguments":{}}}' | sed -n 's/^data: //p' | jq .
+curl -sS "${H[@]}" "$MCP" -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_novel_brief","arguments":{"novelId":"<id from above>"}}}' | sed -n 's/^data: //p' | jq .
+
+# error mapping — expect result.isError true, not a JSON-RPC error
+curl -sS "${H[@]}" "$MCP" -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"list_tags","arguments":{}}}' | sed -n 's/^data: //p' | jq .
+
+# auth — expect 401 with no key
+curl -sS -o /dev/null -w '%{http_code}\n' -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
+  "$MCP" -d '{"jsonrpc":"2.0","id":7,"method":"tools/list","params":{}}'
+
+# one write, end to end
+curl -sS "${H[@]}" "$MCP" -d '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"create_tag","arguments":{"novelId":"<id>","name":"Salt","color":"#9a4a2f"}}}' | sed -n 's/^data: //p' | jq .
+```
+
+Then reconnect a real client: rewrite `.mcp.json` to the `type: "http"` form and run `/mcp` in Claude Code to confirm 45 tools. Finally confirm the web agent still drives the same registry (Aspire up, agent panel, exercise one of the 12 new tools) and that the dashboard shows `/mcp` requests with no prose in the log lines.
+
+## Risks
+
+- **`ModelContextProtocol.AspNetCore` is not cached locally.** First restore needs network.
+- **The web agent's argument names change** (snake_case → camelCase) across all 33 existing tools. Nothing external consumes those schemas — they are built fresh per request and handed to the model each turn — so there is no compatibility surface, but a `JsonSchemaBuilder` key left out of step with its `JsonInput` lookup fails silently as a missing argument rather than a compile error. External MCP clients are unaffected: their argument names were already camelCase.
+- **`create_novel` ownership differs by surface** — signed-in user vs service user. Not a bug, but surprising; document it.
+- **Not fixed here:** child-id-scoped tools carry no novel context in *either* surface, so a caller holding a foreign beat/tag/question id can reach across novels, subject only to `NovelAccessService`. Pre-existing for 20+ tools and unchanged by this work. Worth a follow-up.
+- **QA deploy:** once merged, `/mcp` rides the existing API container and its already-exposed port. `MCP_API_KEY` must be set in Gitea for `Auth__ServiceApiKey`, or every MCP call 401s.

scripts/ci/deploy.sh

@@ -13,6 +13,8 @@ registry_login
 export API_IMAGE WEB_IMAGE
 export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
 export WEB_PORT="${WEB_PORT:-6173}"
+export API_PORT="${API_PORT:-5080}"
+export MCP_API_KEY="${MCP_API_KEY:-}"
 
 COMPOSE="docker compose -f deploy/qa/docker-compose.qa.yml"
 

scripts/publish-mcp.sh

@@ -1,15 +0,0 @@
-#!/usr/bin/env bash
-# Rebuilds the standalone Novelly.Mcp binary that Claude Code (or Claude Desktop) spawns
-# per .mcp.json. Aspire does not run or manage this process, so nothing else rebuilds it —
-# run this after pulling changes that touch src/Novelly.Mcp, or the MCP server silently
-# keeps serving whatever was published last.
-set -euo pipefail
-cd "$(dirname "${BASH_SOURCE[0]}")/.." && source ./scripts/ci/lib.sh
-cd "$CI_ROOT"
-
-ensure_dotnet
-
-log "Publishing Novelly.Mcp to ./mcp-server"
-dotnet publish src/Novelly.Mcp -c Release -o ./mcp-server
-
-log "Done. Reconnect the MCP server (e.g. /mcp in Claude Code) to pick up the new build."

src/Novelly.Api/Activity/ActivityEvent.cs

@@ -21,7 +21,8 @@ public enum ActivityAction
 {
     Created,
     Updated,
-    Deleted
+    Deleted,
+    Restored
 }
 
 public class ActivityEvent

src/Novelly.Api/Agent/AgentContracts.cs

@@ -2,7 +2,7 @@ using System.Text.Json;
 
 namespace Novelly.Api.Agent;
 
-public record AgentToolDefinition(string Name, string Description, JsonElement InputSchema);
+public record AgentToolDefinition(string Name, string Description, JsonElement InputSchema, bool RequiresNovelId = false);
 
 public abstract record AgentContentBlock;
 

src/Novelly.Api/Agent/NovelAgentService.cs

@@ -43,7 +43,7 @@ public class NovelAgentService(
 
         logger.LogInformation("Getting agent conversation {ConversationId}", conversationId);
 
-        return await FindConversationAsync(conversationId, ct);
+        return await FindConversationAsync(conversationId, null, ct);
     }
 
     public async Task<bool> DeleteConversationAsync(Guid conversationId, CancellationToken ct = default)
@@ -52,7 +52,7 @@ public class NovelAgentService(
 
         logger.LogInformation("Deleting agent conversation {ConversationId}", conversationId);
 
-        var conversation = await FindConversationAsync(conversationId, ct);
+        var conversation = await FindConversationAsync(conversationId, null, ct);
         if (conversation is null)
         {
             return false;
@@ -81,7 +81,7 @@ public class NovelAgentService(
         }
 
         var conversation = request.ConversationId is { } id
-            ? await FindConversationAsync(id, ct)
+            ? await FindConversationAsync(id, novelId, ct)
             : StartConversation(novelId, request.Message);
 
         if (conversation is null) return null;
@@ -181,7 +181,7 @@ public class NovelAgentService(
         return conversation;
     }
 
-    private async Task<AgentConversation?> FindConversationAsync(Guid conversationId, CancellationToken ct)
+    private async Task<AgentConversation?> FindConversationAsync(Guid conversationId, Guid? novelId, CancellationToken ct)
     {
         logger.LogDebug("Finding agent conversation {ConversationId}", conversationId);
 
@@ -195,6 +195,14 @@ public class NovelAgentService(
             return conversation;
         }
 
+        if (novelId is { } expectedNovelId && conversation.NovelId != expectedNovelId)
+        {
+            logger.LogWarning(
+                "AgentConversation {ConversationId} belongs to novel {ActualNovelId}, not requested novel {NovelId}",
+                conversationId, conversation.NovelId, expectedNovelId);
+            return null;
+        }
+
         logger.LogDebug("Found agent conversation {ConversationId}", conversationId);
         return conversation;
     }

src/Novelly.Api/Agent/NovelAgentToolset.cs

@@ -21,7 +21,8 @@ public record AgentTool(
     string Name,
     string Description,
     JsonElement InputSchema,
-    Func<Guid, JsonElement, CancellationToken, Task<object?>> Handler);
+    Func<Guid, JsonElement, CancellationToken, Task<object?>> Handler,
+    bool RequiresNovelId = false);
 
 public class NovelAgentToolset(
     NovelService novels,
@@ -46,7 +47,7 @@ public class NovelAgentToolset(
     private IReadOnlyList<AgentTool> Tools => [.. ByName.Values];
 
     public IReadOnlyList<AgentToolDefinition> Definitions =>
-        [.. Tools.Select(t => new AgentToolDefinition(t.Name, t.Description, t.InputSchema))];
+        [.. Tools.Select(t => new AgentToolDefinition(t.Name, t.Description, t.InputSchema, t.RequiresNovelId))];
 
     public async Task<AgentToolResult> ExecuteAsync(string name, Guid novelId, JsonElement input, CancellationToken ct = default)
     {
@@ -97,12 +98,45 @@ public class NovelAgentToolset(
 
     private IEnumerable<AgentTool> Build()
     {
+        yield return new AgentTool(
+            "list_novels",
+            "List every novel, with counts of characters, chapters and drafted words. "
+            + "Start here to find the novel id everything else needs.",
+            new JsonSchemaBuilder().Build(),
+            async (_, _, ct) => await novels.ListAsync(ct));
+
+        yield return new AgentTool(
+            "create_novel",
+            "Create a new novel.",
+            new JsonSchemaBuilder()
+                .Str("title", "Working title.", required: true)
+                .Str("author", "Author name.")
+                .Str("genre", "Genre or category.")
+                .Str("logline", "One-sentence pitch.")
+                .Str("synopsis", "Paragraph-length summary of the whole book.")
+                .Str("notes", "Free-form notes on theme, tone, comparable titles.")
+                .Int("targetWordCount", "Target manuscript length in words.")
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var novel = await novels.CreateAsync(new CreateNovelRequest(
+                    JsonInput.RequiredString(input, "title"),
+                    JsonInput.String(input, "author"),
+                    JsonInput.String(input, "genre"),
+                    JsonInput.String(input, "logline"),
+                    JsonInput.String(input, "synopsis"),
+                    JsonInput.String(input, "notes"),
+                    JsonInput.Int(input, "targetWordCount")), ct);
+                return novel.ToResponse(null);
+            });
+
         yield return new AgentTool(
             "get_novel_brief",
             "Read the novel's title, logline, synopsis, genre, notes and word-count target. "
             + "Call this first in a conversation to ground yourself in what the book is.",
             new JsonSchemaBuilder().Build(),
-            async (novelId, _, ct) => await OrNotFound(novels.GetAsync(novelId, ct), p => p.ToResponse(null), "Novel", novelId));
+            async (novelId, _, ct) => await OrNotFound(novels.GetAsync(novelId, ct), p => p.ToResponse(null), "Novel", novelId),
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "update_novel_brief",
@@ -115,7 +149,7 @@ public class NovelAgentToolset(
                 .Str("logline", "One-sentence pitch.")
                 .Str("synopsis", "Paragraph-length summary of the whole book.")
                 .Str("notes", "Free-form notes on theme, tone, comparable titles.")
-                .Int("target_word_count", "Target manuscript length in words.")
+                .Int("targetWordCount", "Target manuscript length in words.")
                 .Build(),
             async (novelId, input, ct) => await OrNotFound(novels.UpdateAsync(novelId, new UpdateNovelRequest(
                 JsonInput.String(input, "title"),
@@ -124,13 +158,27 @@ public class NovelAgentToolset(
                 JsonInput.String(input, "logline"),
                 JsonInput.String(input, "synopsis"),
                 JsonInput.String(input, "notes"),
-                JsonInput.Int(input, "target_word_count")), ct), p => p.ToResponse(null), "Novel", novelId));
+                JsonInput.Int(input, "targetWordCount")), ct), p => p.ToResponse(null), "Novel", novelId),
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "list_characters",
             "List every character in the novel with their full dossiers.",
             new JsonSchemaBuilder().Build(),
-            async (novelId, _, ct) => (await characters.ListAsync(novelId, ct)).Select(c => c.ToResponse()));
+            async (novelId, _, ct) => (await characters.ListAsync(novelId, ct)).Select(c => c.ToResponse()),
+            RequiresNovelId: true);
+
+        yield return new AgentTool(
+            "get_character",
+            "Read one character's dossier.",
+            new JsonSchemaBuilder()
+                .Str("characterId", "Id of the character to read.", required: true)
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var characterId = JsonInput.RequiredGuid(input, "characterId");
+                return await OrNotFound(characters.GetAsync(characterId, ct), c => c.ToResponse(), "Character", characterId);
+            });
 
         yield return new AgentTool(
             "create_character",
@@ -152,17 +200,18 @@ public class NovelAgentToolset(
                 JsonInput.String(input, "voice"),
                 JsonInput.String(input, "notes"),
                 JsonInput.Strings(input, "tags"),
-                JsonInput.Strings(input, "aliases")), ct), c => c.ToResponse(), "Novel", novelId));
+                JsonInput.Strings(input, "aliases")), ct), c => c.ToResponse(), "Novel", novelId),
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "update_character",
             "Revise an existing character dossier. Only the fields you supply change.",
             CharacterSchema(includeName: true, nameRequired: false)
-                .Str("character_id", "Id of the character to update.", required: true)
+                .Str("characterId", "Id of the character to update.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var characterId = JsonInput.RequiredGuid(input, "character_id");
+                var characterId = JsonInput.RequiredGuid(input, "characterId");
                 return await OrNotFound(characters.UpdateAsync(
                     characterId,
                     new UpdateCharacterRequest(
@@ -183,25 +232,49 @@ public class NovelAgentToolset(
                         JsonInput.Strings(input, "aliases")), ct), c => c.ToResponse(), "Character", characterId);
             });
 
+        yield return new AgentTool(
+            "relate_characters",
+            "Record a relationship between two characters in the same novel. Creates both directions "
+            + "at once — characterId's side and relatedCharacterId's side — so the pair always shows up "
+            + "on both dossiers.",
+            new JsonSchemaBuilder()
+                .Str("characterId", "Id of the character the relationship belongs to.", required: true)
+                .Str("relatedCharacterId", "Id of the character they are related to.", required: true)
+                .Str("relationshipType", "How characterId is related to relatedCharacterId, e.g. 'sister', 'rival', 'former mentor'.", required: true)
+                .Str("reciprocalRelationshipType", "How relatedCharacterId is related back to characterId, if different. Defaults to relationshipType when the relation is symmetric, like 'rival'.")
+                .Str("description", "What the relationship is like, and where it is headed.")
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var characterId = JsonInput.RequiredGuid(input, "characterId");
+                return await OrNotFound(characters.AddRelationshipAsync(
+                    characterId,
+                    new CreateRelationshipRequest(
+                        JsonInput.RequiredGuid(input, "relatedCharacterId"),
+                        JsonInput.RequiredString(input, "relationshipType"),
+                        JsonInput.String(input, "description"),
+                        JsonInput.String(input, "reciprocalRelationshipType")), ct), c => c.ToResponse(), "Character", characterId);
+            });
+
         yield return new AgentTool(
             "link_character_identity",
             "Record that a character is really another character — e.g. one introduced under one name "
             + "who is later revealed to be a character already in the novel under another name. Both "
             + "keep their own dossier and beats; the canonical identity is whichever character you link to.",
             new JsonSchemaBuilder()
-                .Str("character_id", "Id of the character being revealed as someone else.", required: true)
-                .Str("same_character_as_id", "Id of the character this one really is.", required: true)
-                .Str("revealed_in_chapter_id", "Id of the chapter where the reveal happens, if any.")
+                .Str("characterId", "Id of the character being revealed as someone else.", required: true)
+                .Str("sameCharacterAsId", "Id of the character this one really is.", required: true)
+                .Str("revealedInChapterId", "Id of the chapter where the reveal happens, if any.")
                 .Str("note", "Context on the reveal, e.g. how and why the disguise held.")
                 .Build(),
             async (_, input, ct) =>
             {
-                var characterId = JsonInput.RequiredGuid(input, "character_id");
+                var characterId = JsonInput.RequiredGuid(input, "characterId");
                 return await OrNotFound(characters.LinkIdentityAsync(
                     characterId,
                     new LinkCharacterIdentityRequest(
-                        JsonInput.RequiredGuid(input, "same_character_as_id"),
-                        JsonInput.Guid(input, "revealed_in_chapter_id"),
+                        JsonInput.RequiredGuid(input, "sameCharacterAsId"),
+                        JsonInput.Guid(input, "revealedInChapterId"),
                         JsonInput.String(input, "note")), ct), c => c.ToResponse(), "Character", characterId);
             });
 
@@ -209,11 +282,11 @@ public class NovelAgentToolset(
             "unlink_character_identity",
             "Remove a character's identity link, restoring it to its own separate identity.",
             new JsonSchemaBuilder()
-                .Str("character_id", "Id of the character to unlink.", required: true)
+                .Str("characterId", "Id of the character to unlink.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var characterId = JsonInput.RequiredGuid(input, "character_id");
+                var characterId = JsonInput.RequiredGuid(input, "characterId");
                 return await DeletedOrNotFound(characters.UnlinkIdentityAsync(characterId, ct), "Character", characterId);
             });
 
@@ -222,29 +295,29 @@ public class NovelAgentToolset(
             "Read a chapter's outline: its summary paragraph and its beat table, in order. "
             + "A beat is one row — a short title, whose beat it is, what happened, and what it sets up.",
             new JsonSchemaBuilder()
-                .Str("chapter_id", "Id of the chapter whose outline to read.", required: true)
+                .Str("chapterId", "Id of the chapter whose outline to read.", required: true)
                 .Build(),
-            async (_, input, ct) => (await beats.ListAsync(JsonInput.RequiredGuid(input, "chapter_id"), ct)).Select(b => b.ToResponse()));
+            async (_, input, ct) => (await beats.ListAsync(JsonInput.RequiredGuid(input, "chapterId"), ct)).Select(b => b.ToResponse()));
 
         yield return new AgentTool(
             "create_beat",
             "Add a beat to a chapter's outline. Keep the title to three to five words — it is a "
-            + "handle, not a sentence; the detail belongs in what_happened and whats_next.",
+            + "handle, not a sentence; the detail belongs in whatHappened and whatsNext.",
             BeatSchema()
-                .Str("chapter_id", "Id of the chapter the beat belongs to.", required: true)
+                .Str("chapterId", "Id of the chapter the beat belongs to.", required: true)
                 .Str("title", "Three to five words naming the beat.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var chapterId = JsonInput.RequiredGuid(input, "chapter_id");
+                var chapterId = JsonInput.RequiredGuid(input, "chapterId");
                 return await OrNotFound(beats.CreateAsync(
                     chapterId,
                     new CreateBeatRequest(
                         JsonInput.RequiredString(input, "title"),
-                        JsonInput.Int(input, "sort_order"),
-                        JsonInput.Guids(input, "character_ids"),
-                        JsonInput.String(input, "what_happened"),
-                        JsonInput.String(input, "whats_next"),
+                        JsonInput.Int(input, "sortOrder"),
+                        JsonInput.Guids(input, "characterIds"),
+                        JsonInput.String(input, "whatHappened"),
+                        JsonInput.String(input, "whatsNext"),
                         JsonInput.Strings(input, "tags")), ct), b => b.ToResponse(), "Chapter", chapterId);
             });
 
@@ -253,20 +326,20 @@ public class NovelAgentToolset(
             "Revise a beat. Only the fields you supply change. Supplying a tag list replaces "
             + "the beat's tags outright, so include the ones you want to keep.",
             BeatSchema()
-                .Str("beat_id", "Id of the beat to update.", required: true)
+                .Str("beatId", "Id of the beat to update.", required: true)
                 .Str("title", "Three to five words naming the beat.")
                 .Build(),
             async (_, input, ct) =>
             {
-                var beatId = JsonInput.RequiredGuid(input, "beat_id");
+                var beatId = JsonInput.RequiredGuid(input, "beatId");
                 return await OrNotFound(beats.UpdateAsync(
                     beatId,
                     new UpdateBeatRequest(
                         JsonInput.String(input, "title"),
-                        JsonInput.Int(input, "sort_order"),
-                        JsonInput.Guids(input, "character_ids"),
-                        JsonInput.String(input, "what_happened"),
-                        JsonInput.String(input, "whats_next"),
+                        JsonInput.Int(input, "sortOrder"),
+                        JsonInput.Guids(input, "characterIds"),
+                        JsonInput.String(input, "whatHappened"),
+                        JsonInput.String(input, "whatsNext"),
                         JsonInput.Strings(input, "tags")), ct), b => b.ToResponse(), "Beat", beatId);
             });
 
@@ -274,11 +347,11 @@ public class NovelAgentToolset(
             "delete_beat",
             "Remove a beat from a chapter's outline. Confirm with the writer before calling it.",
             new JsonSchemaBuilder()
-                .Str("beat_id", "Id of the beat to delete.", required: true)
+                .Str("beatId", "Id of the beat to delete.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var beatId = JsonInput.RequiredGuid(input, "beat_id");
+                var beatId = JsonInput.RequiredGuid(input, "beatId");
                 return await DeletedOrNotFound(beats.DeleteAsync(beatId, ct), "Beat", beatId);
             });
 
@@ -287,16 +360,16 @@ public class NovelAgentToolset(
             "Renumber a chapter's beats to match the order given. List every beat id in the "
             + "order you want; any you leave out keep their relative position at the end.",
             new JsonSchemaBuilder()
-                .Str("chapter_id", "Id of the chapter whose beats to reorder.", required: true)
-                .StringArray("beat_ids", "Beat ids in their new order.", required: true)
+                .Str("chapterId", "Id of the chapter whose beats to reorder.", required: true)
+                .StringArray("beatIds", "Beat ids in their new order.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var chapterId = JsonInput.RequiredGuid(input, "chapter_id");
+                var chapterId = JsonInput.RequiredGuid(input, "chapterId");
                 return await OrNotFound(beats.ReorderAsync(
                     chapterId,
                     new ReorderBeatsRequest(
-                        [.. (JsonInput.Strings(input, "beat_ids") ?? [])
+                        [.. (JsonInput.Strings(input, "beatIds") ?? [])
                             .Select(id => Guid.TryParse(id, out var g) ? g : Guid.Empty)
                             .Where(g => g != Guid.Empty)]), ct), list => list.Select(b => b.ToResponse()), "Chapter", chapterId);
             });
@@ -306,18 +379,18 @@ public class NovelAgentToolset(
             "Add a character to several beats at once. Leaves each beat's existing characters and "
             + "other fields alone — this only adds, it never removes.",
             new JsonSchemaBuilder()
-                .Str("chapter_id", "Id of the chapter the beats belong to.", required: true)
-                .Str("character_id", "Id of the character to add.", required: true)
-                .StringArray("beat_ids", "Ids of the beats to add the character to.", required: true)
+                .Str("chapterId", "Id of the chapter the beats belong to.", required: true)
+                .Str("characterId", "Id of the character to add.", required: true)
+                .StringArray("beatIds", "Ids of the beats to add the character to.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var chapterId = JsonInput.RequiredGuid(input, "chapter_id");
+                var chapterId = JsonInput.RequiredGuid(input, "chapterId");
                 return await OrNotFound(beats.AssignCharacterAsync(
                     chapterId,
                     new AssignCharacterToBeatsRequest(
-                        JsonInput.RequiredGuid(input, "character_id"),
-                        [.. (JsonInput.Strings(input, "beat_ids") ?? [])
+                        JsonInput.RequiredGuid(input, "characterId"),
+                        [.. (JsonInput.Strings(input, "beatIds") ?? [])
                             .Select(id => Guid.TryParse(id, out var g) ? g : Guid.Empty)
                             .Where(g => g != Guid.Empty)]), ct), list => list.Select(b => b.ToResponse()), "Chapter", chapterId);
             });
@@ -327,18 +400,18 @@ public class NovelAgentToolset(
             "Move one or more beats from one chapter to another, appending them to the target "
             + "chapter's end in the order given.",
             new JsonSchemaBuilder()
-                .Str("chapter_id", "Id of the beats' current chapter.", required: true)
-                .Str("target_chapter_id", "Id of the chapter to move the beats into.", required: true)
-                .StringArray("beat_ids", "Ids of the beats to move.", required: true)
+                .Str("chapterId", "Id of the beats' current chapter.", required: true)
+                .Str("targetChapterId", "Id of the chapter to move the beats into.", required: true)
+                .StringArray("beatIds", "Ids of the beats to move.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var chapterId = JsonInput.RequiredGuid(input, "chapter_id");
+                var chapterId = JsonInput.RequiredGuid(input, "chapterId");
                 return await OrNotFound(beats.MoveAsync(
                     chapterId,
                     new MoveBeatsRequest(
-                        JsonInput.RequiredGuid(input, "target_chapter_id"),
-                        [.. (JsonInput.Strings(input, "beat_ids") ?? [])
+                        JsonInput.RequiredGuid(input, "targetChapterId"),
+                        [.. (JsonInput.Strings(input, "beatIds") ?? [])
                             .Select(id => Guid.TryParse(id, out var g) ? g : Guid.Empty)
                             .Where(g => g != Guid.Empty)]), ct), list => list.Select(b => b.ToResponse()), "Chapter", chapterId);
             });
@@ -348,18 +421,19 @@ public class NovelAgentToolset(
             "List the novel's tags with how many characters, chapters and beats carry each. "
             + "Read this before inventing a new tag so you reuse the writer's vocabulary.",
             new JsonSchemaBuilder().Build(),
-            async (novelId, _, ct) => await tags.ListAsync(novelId, ct));
+            async (novelId, _, ct) => await tags.ListAsync(novelId, ct),
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "get_tag_references",
             "Cross-reference a tag: every character, chapter and beat carrying it. Use this to "
             + "trace a motif or a thread through the book.",
             new JsonSchemaBuilder()
-                .Str("tag_id", "Id of the tag to trace.", required: true)
+                .Str("tagId", "Id of the tag to trace.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var tagId = JsonInput.RequiredGuid(input, "tag_id");
+                var tagId = JsonInput.RequiredGuid(input, "tagId");
                 var tag = await tags.GetReferencesAsync(tagId, ct);
                 if (tag is null)
                 {
@@ -370,22 +444,68 @@ public class NovelAgentToolset(
                 return tag.ToReferencesResponse(displayNumbers);
             });
 
+        yield return new AgentTool(
+            "create_tag",
+            "Create a tag explicitly. Applying an unknown tag by name to a character, chapter or "
+            + "beat also creates it, so this is only needed to set a colour up front.",
+            new JsonSchemaBuilder()
+                .Str("name", "The tag's name. Unique within the novel, matched case-insensitively.", required: true)
+                .Str("color", "Optional hex colour for the UI, e.g. \"#9a4a2f\".")
+                .Build(),
+            async (novelId, input, ct) => await OrNotFound(tags.CreateAsync(
+                novelId,
+                new CreateTagRequest(
+                    JsonInput.RequiredString(input, "name"),
+                    JsonInput.String(input, "color")), ct), t => t.ToResponse(), "Novel", novelId),
+            RequiresNovelId: true);
+
+        yield return new AgentTool(
+            "update_tag",
+            "Rename or recolour a tag. Renaming updates it everywhere it is applied.",
+            new JsonSchemaBuilder()
+                .Str("tagId", "Id of the tag to update.", required: true)
+                .Str("name", "New name.")
+                .Str("color", "Hex colour, e.g. \"#9a4a2f\".")
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var tagId = JsonInput.RequiredGuid(input, "tagId");
+                return await OrNotFound(tags.UpdateAsync(
+                    tagId,
+                    new UpdateTagRequest(
+                        JsonInput.String(input, "name"),
+                        JsonInput.String(input, "color")), ct), t => t.ToResponse(), "Tag", tagId);
+            });
+
+        yield return new AgentTool(
+            "delete_tag",
+            "Delete a tag. Whatever carried it is left alone — only the label goes.",
+            new JsonSchemaBuilder()
+                .Str("tagId", "Id of the tag to delete.", required: true)
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var tagId = JsonInput.RequiredGuid(input, "tagId");
+                return await DeletedOrNotFound(tags.DeleteAsync(tagId, ct), "Tag", tagId);
+            });
+
         yield return new AgentTool(
             "list_locations",
             "List the novel's locations with how many chapters are set there. "
             + "Read this before inventing a new location so you reuse the writer's vocabulary.",
             new JsonSchemaBuilder().Build(),
-            async (novelId, _, ct) => await locations.ListAsync(novelId, ct));
+            async (novelId, _, ct) => await locations.ListAsync(novelId, ct),
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "get_location_references",
             "Cross-reference a location: every chapter set there.",
             new JsonSchemaBuilder()
-                .Str("location_id", "Id of the location to trace.", required: true)
+                .Str("locationId", "Id of the location to trace.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var locationId = JsonInput.RequiredGuid(input, "location_id");
+                var locationId = JsonInput.RequiredGuid(input, "locationId");
                 var location = await locations.GetReferencesAsync(locationId, ct);
                 if (location is null)
                 {
@@ -396,6 +516,45 @@ public class NovelAgentToolset(
                 return location.ToReferencesResponse(displayNumbers);
             });
 
+        yield return new AgentTool(
+            "create_location",
+            "Create a location explicitly. Applying an unknown location by name to a chapter also "
+            + "creates it, so this is only needed to set one up ahead of time.",
+            new JsonSchemaBuilder()
+                .Str("name", "The location's name. Unique within the novel, matched case-insensitively.", required: true)
+                .Build(),
+            async (novelId, input, ct) => await OrNotFound(locations.CreateAsync(
+                novelId,
+                new CreateLocationRequest(JsonInput.RequiredString(input, "name")), ct), l => l.ToResponse(), "Novel", novelId),
+            RequiresNovelId: true);
+
+        yield return new AgentTool(
+            "update_location",
+            "Rename a location. Renaming updates it everywhere it is applied.",
+            new JsonSchemaBuilder()
+                .Str("locationId", "Id of the location to update.", required: true)
+                .Str("name", "New name.", required: true)
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var locationId = JsonInput.RequiredGuid(input, "locationId");
+                return await OrNotFound(locations.UpdateAsync(
+                    locationId,
+                    new UpdateLocationRequest(JsonInput.RequiredString(input, "name")), ct), l => l.ToResponse(), "Location", locationId);
+            });
+
+        yield return new AgentTool(
+            "delete_location",
+            "Delete a location. Whatever carried it is left alone — only the label goes.",
+            new JsonSchemaBuilder()
+                .Str("locationId", "Id of the location to delete.", required: true)
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var locationId = JsonInput.RequiredGuid(input, "locationId");
+                return await DeletedOrNotFound(locations.DeleteAsync(locationId, ct), "Location", locationId);
+            });
+
         yield return new AgentTool(
             "list_chapters",
             "List the novel's chapters in manuscript order with beat and word counts.",
@@ -405,17 +564,18 @@ public class NovelAgentToolset(
                 var list = await chapters.ListAsync(novelId, ct);
                 var displayNumbers = ChapterNumbering.DisplayNumbers(list);
                 return list.Select(c => c.ToSummaryResponse(displayNumbers.TryGetValue(c.Id, out var n) ? n : null));
-            });
+            },
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "get_chapter",
             "Read one chapter in full: its outline (beats) and its drafted prose.",
             new JsonSchemaBuilder()
-                .Str("chapter_id", "Id of the chapter to read.", required: true)
+                .Str("chapterId", "Id of the chapter to read.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var chapterId = JsonInput.RequiredGuid(input, "chapter_id");
+                var chapterId = JsonInput.RequiredGuid(input, "chapterId");
                 var chapter = await chapters.GetAsync(chapterId, ct);
                 if (chapter is null)
                 {
@@ -439,7 +599,7 @@ public class NovelAgentToolset(
                 .StringArray("locations", "Where and when the chapter takes place. Unknown locations are created.")
                 .Str("notes", "Anything else worth recording.")
                 .Enum("status", "Drafting status.", System.Enum.GetNames<DraftStatus>())
-                .Int("target_word_count", "Target length in words.")
+                .Int("targetWordCount", "Target length in words.")
                 .Str("prose", "The chapter's drafted text, in markdown, if you are writing it now.")
                 .StringArray("tags", "Tags for cross-referencing. Replaces the existing tags.")
                 .Build(),
@@ -453,7 +613,7 @@ public class NovelAgentToolset(
                     JsonInput.Strings(input, "locations"),
                     JsonInput.String(input, "notes"),
                     JsonInput.Enum<DraftStatus>(input, "status") ?? DraftStatus.Planned,
-                    JsonInput.Int(input, "target_word_count"),
+                    JsonInput.Int(input, "targetWordCount"),
                     JsonInput.String(input, "prose"),
                     JsonInput.Strings(input, "tags")), ct);
 
@@ -464,7 +624,8 @@ public class NovelAgentToolset(
 
                 var displayNumber = await chapters.DisplayNumberAsync(chapter, ct);
                 return chapter.ToResponse(displayNumber);
-            });
+            },
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "update_chapter",
@@ -472,7 +633,7 @@ public class NovelAgentToolset(
             + "prose. Use 'prose' to write or replace the chapter's draft text in markdown; the "
             + "word count is recomputed automatically.",
             new JsonSchemaBuilder()
-                .Str("chapter_id", "Id of the chapter to update.", required: true)
+                .Str("chapterId", "Id of the chapter to update.", required: true)
                 .Str("title", "New title.")
                 .Int("number", "Manuscript position, 1-based, counting front and back matter.")
                 .Enum("kind", "Front matter, a numbered body chapter, or back matter.", System.Enum.GetNames<ChapterKind>())
@@ -480,13 +641,13 @@ public class NovelAgentToolset(
                 .StringArray("locations", "Where and when the chapter takes place. Replaces the existing locations. Unknown locations are created.")
                 .Str("notes", "Anything else worth recording.")
                 .Enum("status", "Drafting status.", System.Enum.GetNames<DraftStatus>())
-                .Int("target_word_count", "Target length in words.")
+                .Int("targetWordCount", "Target length in words.")
                 .Str("prose", "The chapter's drafted text, in markdown.")
                 .StringArray("tags", "Tags for cross-referencing. Replaces the existing tags.")
                 .Build(),
             async (_, input, ct) =>
             {
-                var chapterId = JsonInput.RequiredGuid(input, "chapter_id");
+                var chapterId = JsonInput.RequiredGuid(input, "chapterId");
                 var chapter = await chapters.UpdateAsync(
                     chapterId,
                     new UpdateChapterRequest(
@@ -497,7 +658,7 @@ public class NovelAgentToolset(
                         JsonInput.Strings(input, "locations"),
                         JsonInput.String(input, "notes"),
                         JsonInput.Enum<DraftStatus>(input, "status"),
-                        JsonInput.Int(input, "target_word_count"),
+                        JsonInput.Int(input, "targetWordCount"),
                         JsonInput.String(input, "prose"),
                         JsonInput.Strings(input, "tags")), ct);
 
@@ -516,11 +677,11 @@ public class NovelAgentToolset(
             + "Read this before revising a character — it is what they actually do on the page, "
             + "as opposed to what the dossier claims about them.",
             new JsonSchemaBuilder()
-                .Str("character_id", "Id of the character.", required: true)
+                .Str("characterId", "Id of the character.", required: true)
                 .Build(),
             async (novelId, input, ct) =>
             {
-                var characterId = JsonInput.RequiredGuid(input, "character_id");
+                var characterId = JsonInput.RequiredGuid(input, "characterId");
                 var characterBeats = await beats.ListForCharacterAsync(characterId, ct);
                 if (characterBeats is null)
                 {
@@ -530,66 +691,67 @@ public class NovelAgentToolset(
                 var displayNumbers = await chapterLabels.ForNovelAsync(novelId, ct);
                 return characterBeats.Select(b =>
                     b.ToCharacterBeatResponse(characterId, b.Chapter is null ? null : chapterLabels.LabelFor(b.Chapter, displayNumbers)));
-            });
+            },
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "get_character_arc",
             "Read a main character's arc: the ordered stages of how they change. Each stage may "
             + "be pinned to the chapter where it lands.",
             new JsonSchemaBuilder()
-                .Str("character_id", "Id of the character.", required: true)
+                .Str("characterId", "Id of the character.", required: true)
                 .Build(),
             async (_, input, ct) => (await arcs.ListAsync(
-                JsonInput.RequiredGuid(input, "character_id"), ct)).Select(s => s.ToResponse()));
+                JsonInput.RequiredGuid(input, "characterId"), ct)).Select(s => s.ToResponse()));
 
         yield return new AgentTool(
             "add_arc_stage",
             "Add a stage to a character's arc. Arcs are for main characters — promote the "
             + "character first with update_character if they are still Supporting.",
             ArcStageSchema()
-                .Str("character_id", "Id of the character whose arc to add to.", required: true)
+                .Str("characterId", "Id of the character whose arc to add to.", required: true)
                 .Str("title", "A short handle for the change, three to five words.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var characterId = JsonInput.RequiredGuid(input, "character_id");
+                var characterId = JsonInput.RequiredGuid(input, "characterId");
                 return await OrNotFound(arcs.CreateAsync(
                     characterId,
                     new CreateArcStageRequest(
                         JsonInput.RequiredString(input, "title"),
-                        JsonInput.Int(input, "sort_order"),
+                        JsonInput.Int(input, "sortOrder"),
                         JsonInput.String(input, "description"),
-                        JsonInput.Guid(input, "chapter_id")), ct), s => s.ToResponse(), "Character", characterId);
+                        JsonInput.Guid(input, "chapterId")), ct), s => s.ToResponse(), "Character", characterId);
             });
 
         yield return new AgentTool(
             "update_arc_stage",
             "Revise a stage of a character's arc. Only the fields you supply change.",
             ArcStageSchema()
-                .Str("arc_stage_id", "Id of the arc stage to update.", required: true)
+                .Str("arcStageId", "Id of the arc stage to update.", required: true)
                 .Str("title", "New title for the stage.")
                 .Build(),
             async (_, input, ct) =>
             {
-                var arcStageId = JsonInput.RequiredGuid(input, "arc_stage_id");
+                var arcStageId = JsonInput.RequiredGuid(input, "arcStageId");
                 return await OrNotFound(arcs.UpdateAsync(
                     arcStageId,
                     new UpdateArcStageRequest(
                         JsonInput.String(input, "title"),
-                        JsonInput.Int(input, "sort_order"),
+                        JsonInput.Int(input, "sortOrder"),
                         JsonInput.String(input, "description"),
-                        JsonInput.Guid(input, "chapter_id")), ct), s => s.ToResponse(), "CharacterArcStage", arcStageId);
+                        JsonInput.Guid(input, "chapterId")), ct), s => s.ToResponse(), "CharacterArcStage", arcStageId);
             });
 
         yield return new AgentTool(
             "delete_arc_stage",
             "Remove a stage from a character's arc.",
             new JsonSchemaBuilder()
-                .Str("arc_stage_id", "Id of the arc stage to delete.", required: true)
+                .Str("arcStageId", "Id of the arc stage to delete.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var arcStageId = JsonInput.RequiredGuid(input, "arc_stage_id");
+                var arcStageId = JsonInput.RequiredGuid(input, "arcStageId");
                 return await DeletedOrNotFound(arcs.DeleteAsync(arcStageId, ct), "CharacterArcStage", arcStageId);
             });
 
@@ -598,16 +760,35 @@ public class NovelAgentToolset(
             "Renumber a character's arc to match the order given. Stages left out keep their "
             + "relative position after the ones listed.",
             new JsonSchemaBuilder()
-                .Str("character_id", "Id of the character whose arc to reorder.", required: true)
-                .StringArray("stage_ids", "Arc stage ids in the order wanted.", required: true)
+                .Str("characterId", "Id of the character whose arc to reorder.", required: true)
+                .StringArray("stageIds", "Arc stage ids in the order wanted.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var characterId = JsonInput.RequiredGuid(input, "character_id");
+                var characterId = JsonInput.RequiredGuid(input, "characterId");
                 return await OrNotFound(arcs.ReorderAsync(
                     characterId,
                     new ReorderArcStagesRequest(
-                        [.. JsonInput.Strings(input, "stage_ids")?.Select(Guid.Parse) ?? []]), ct), list => list.Select(s => s.ToResponse()), "Character", characterId);
+                        [.. JsonInput.Strings(input, "stageIds")?.Select(Guid.Parse) ?? []]), ct), list => list.Select(s => s.ToResponse()), "Character", characterId);
+            });
+
+        yield return new AgentTool(
+            "set_arc_stage_beats",
+            "Set which beats belong to an arc stage, replacing its current set. This groups the "
+            + "chapter-level beats that establish or pay off this stage of the character's arc. A "
+            + "beat moved into this stage leaves any other stage of the same character it was in. "
+            + "Each beat must already include this character.",
+            new JsonSchemaBuilder()
+                .Str("arcStageId", "Id of the arc stage.", required: true)
+                .StringArray("beatIds", "Beat ids that belong to this stage, replacing whatever was there before.", required: true)
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var arcStageId = JsonInput.RequiredGuid(input, "arcStageId");
+                return await OrNotFound(arcs.SetBeatsAsync(
+                    arcStageId,
+                    new SetArcStageBeatsRequest(
+                        [.. JsonInput.Strings(input, "beatIds")?.Select(Guid.Parse) ?? []]), ct), s => s.ToResponse(), "CharacterArcStage", arcStageId);
             });
 
         yield return new AgentTool(
@@ -615,22 +796,23 @@ public class NovelAgentToolset(
             "The decisions the writer has not made yet. Read this before proposing changes — an "
             + "open question is a place the writer is still thinking, not a gap to fill in for them.",
             new JsonSchemaBuilder()
-                .Str("chapter_id", "Narrow to questions about one chapter outline.")
-                .Str("character_id", "Narrow to questions about one character.")
-                .Bool("include_resolved", "Include questions already settled. Defaults to false.")
+                .Str("chapterId", "Narrow to questions about one chapter outline.")
+                .Str("characterId", "Narrow to questions about one character.")
+                .Bool("includeResolved", "Include questions already settled. Defaults to false.")
                 .Build(),
             async (novelId, input, ct) =>
             {
                 var list = await questions.ListAsync(
                     novelId,
-                    JsonInput.Guid(input, "chapter_id"),
-                    JsonInput.Guid(input, "character_id"),
-                    JsonInput.Bool(input, "include_resolved") ?? false,
+                    JsonInput.Guid(input, "chapterId"),
+                    JsonInput.Guid(input, "characterId"),
+                    JsonInput.Bool(input, "includeResolved") ?? false,
                     ct);
 
                 var displayNumbers = await chapterLabels.ForNovelAsync(novelId, ct);
                 return list.Select(q => q.ToResponse(displayNumbers));
-            });
+            },
+            RequiresNovelId: true);
 
         yield return new AgentTool(
             "raise_open_question",
@@ -640,8 +822,8 @@ public class NovelAgentToolset(
             new JsonSchemaBuilder()
                 .Str("question", "The question, in one line.", required: true)
                 .Str("detail", "The thinking around it — options, and what each costs.")
-                .Str("chapter_id", "The chapter outline this is about, if any.")
-                .Str("character_id", "The character this is about, if any.")
+                .Str("chapterId", "The chapter outline this is about, if any.")
+                .Str("characterId", "The character this is about, if any.")
                 .Build(),
             async (novelId, input, ct) =>
             {
@@ -650,8 +832,8 @@ public class NovelAgentToolset(
                     new CreateOpenQuestionRequest(
                         JsonInput.RequiredString(input, "question"),
                         JsonInput.String(input, "detail"),
-                        JsonInput.Guid(input, "chapter_id"),
-                        JsonInput.Guid(input, "character_id")), ct);
+                        JsonInput.Guid(input, "chapterId"),
+                        JsonInput.Guid(input, "characterId")), ct);
 
                 if (question is null)
                 {
@@ -660,25 +842,60 @@ public class NovelAgentToolset(
 
                 var displayNumbers = await chapterLabels.ForNovelAsync(novelId, ct);
                 return question.ToResponse(displayNumbers);
+            },
+            RequiresNovelId: true);
+
+        yield return new AgentTool(
+            "update_open_question",
+            "Revise a question or change what it is attached to. Only the fields you supply change.",
+            new JsonSchemaBuilder()
+                .Str("questionId", "Id of the question to update.", required: true)
+                .Str("question", "New wording for the question.")
+                .Str("detail", "New detail. Pass an empty string to clear it.")
+                .Str("chapterId", "Attach to this chapter outline.")
+                .Str("characterId", "Attach to this character.")
+                .Bool("clearChapter", "Detach from its chapter.")
+                .Bool("clearCharacter", "Detach from its character.")
+                .Build(),
+            async (_, input, ct) =>
+            {
+                var questionId = JsonInput.RequiredGuid(input, "questionId");
+                var question = await questions.UpdateAsync(
+                    questionId,
+                    new UpdateOpenQuestionRequest(
+                        JsonInput.String(input, "question"),
+                        JsonInput.String(input, "detail"),
+                        JsonInput.Guid(input, "chapterId"),
+                        JsonInput.Guid(input, "characterId"),
+                        JsonInput.Bool(input, "clearChapter") ?? false,
+                        JsonInput.Bool(input, "clearCharacter") ?? false), ct);
+
+                if (question is null)
+                {
+                    return new ToolNotFound("OpenQuestion", questionId);
+                }
+
+                var displayNumbers = await chapterLabels.ForNovelAsync(question.NovelId, ct);
+                return question.ToResponse(displayNumbers);
             });
 
         yield return new AgentTool(
             "resolve_open_question",
-            "Settle a question with what the writer decided. Set append_to_notes to also write "
+            "Settle a question with what the writer decided. Set appendToNotes to also write "
             + "the resolution into the notes of the chapter and character it hangs off.",
             new JsonSchemaBuilder()
-                .Str("question_id", "Id of the question to resolve.", required: true)
+                .Str("questionId", "Id of the question to resolve.", required: true)
                 .Str("resolution", "What was decided.", required: true)
-                .Bool("append_to_notes", "Also append the resolution to the associated notes.")
+                .Bool("appendToNotes", "Also append the resolution to the associated notes.")
                 .Build(),
             async (_, input, ct) =>
             {
-                var questionId = JsonInput.RequiredGuid(input, "question_id");
+                var questionId = JsonInput.RequiredGuid(input, "questionId");
                 var question = await questions.ResolveAsync(
                     questionId,
                     new ResolveOpenQuestionRequest(
                         JsonInput.RequiredString(input, "resolution"),
-                        JsonInput.Bool(input, "append_to_notes") ?? false), ct);
+                        JsonInput.Bool(input, "appendToNotes") ?? false), ct);
 
                 if (question is null)
                 {
@@ -693,11 +910,11 @@ public class NovelAgentToolset(
             "reopen_question",
             "Put a resolved question back on the list. Anything already appended to notes stays.",
             new JsonSchemaBuilder()
-                .Str("question_id", "Id of the question to reopen.", required: true)
+                .Str("questionId", "Id of the question to reopen.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var questionId = JsonInput.RequiredGuid(input, "question_id");
+                var questionId = JsonInput.RequiredGuid(input, "questionId");
                 var question = await questions.ReopenAsync(questionId, ct);
                 if (question is null)
                 {
@@ -712,20 +929,20 @@ public class NovelAgentToolset(
             "delete_open_question",
             "Delete a question outright. Resolving is usually better — it keeps the decision.",
             new JsonSchemaBuilder()
-                .Str("question_id", "Id of the question to delete.", required: true)
+                .Str("questionId", "Id of the question to delete.", required: true)
                 .Build(),
             async (_, input, ct) =>
             {
-                var questionId = JsonInput.RequiredGuid(input, "question_id");
+                var questionId = JsonInput.RequiredGuid(input, "questionId");
                 return await DeletedOrNotFound(questions.DeleteAsync(questionId, ct), "OpenQuestion", questionId);
             });
     }
 
     private static JsonSchemaBuilder ArcStageSchema() =>
         new JsonSchemaBuilder()
-            .Int("sort_order", "Position in the arc. Appended to the end when omitted.")
+            .Int("sortOrder", "Position in the arc. Appended to the end when omitted.")
             .Str("description", "What shifts in the character here, and what it costs them.")
-            .Str("chapter_id", "The chapter where this stage lands, if it is pinned to one.");
+            .Str("chapterId", "The chapter where this stage lands, if it is pinned to one.");
 
     private static JsonSchemaBuilder CharacterSchema(bool includeName, bool nameRequired)
     {
@@ -759,9 +976,9 @@ public class NovelAgentToolset(
 
     private static JsonSchemaBuilder BeatSchema() =>
         new JsonSchemaBuilder()
-            .Int("sort_order", "Position in the chapter. Appended to the end when omitted.")
-            .StringArray("character_ids", "Ids of the characters whose beat this is. Replaces the existing list.")
-            .Str("what_happened", "The event itself.")
-            .Str("whats_next", "What it sets in motion — the hook into the next beat.")
+            .Int("sortOrder", "Position in the chapter. Appended to the end when omitted.")
+            .StringArray("characterIds", "Ids of the characters whose beat this is. Replaces the existing list.")
+            .Str("whatHappened", "The event itself.")
+            .Str("whatsNext", "What it sets in motion — the hook into the next beat.")
             .StringArray("tags", "Tags for cross-referencing. Replaces the existing tags.");
 }

src/Novelly.Api/Beats/Beat.cs

@@ -37,6 +37,7 @@ public class BeatEntityTypeConfiguration : IEntityTypeConfiguration<Beat>
     {
         entity.Property(b => b.Title).IsRequired().HasMaxLength(200);
         entity.HasIndex(b => new { b.ChapterId, b.SortOrder });
+        entity.HasQueryFilter(b => b.Chapter!.DeletedAt == null);
 
         entity.HasOne(b => b.Chapter).WithMany(c => c.Beats)
             .HasForeignKey(b => b.ChapterId).OnDelete(DeleteBehavior.Cascade);

src/Novelly.Api/Beats/BeatContracts.cs

@@ -146,7 +146,7 @@ public static class BeatMapping
         b.ChapterId,
         b.SortOrder,
         b.Title,
-        [.. b.Characters.OrderBy(c => c.Name).Select(c => new BeatCharacterResponse(c.Id, c.Name))],
+        [.. b.Characters.Where(c => c.DeletedAt is null).OrderBy(c => c.Name).Select(c => new BeatCharacterResponse(c.Id, c.Name))],
         b.WhatHappened,
         b.WhatsNext,
         [.. b.Tags.OrderBy(t => t.Name).Select(t => t.ToResponse())],

src/Novelly.Api/Beats/BeatService.cs

@@ -70,7 +70,7 @@ public class BeatService(
 
         var beats = await db.Beats
             .Include(b => b.Chapter)
-            .Include(b => b.ArcStages)
+            .Include(b => b.ArcStages.Where(s => s.Character!.DeletedAt == null))
             .Where(b => b.Characters.Any(c => c.Id == characterId))
             .ToListAsync(ct);
 
@@ -395,7 +395,7 @@ public class BeatService(
 
     private IQueryable<Beat> Query() =>
         db.Beats
-            .Include(b => b.Characters)
+            .Include(b => b.Characters.Where(c => c.DeletedAt == null))
             .Include(b => b.Tags);
 
     private async Task<Beat?> FindAsync(Guid id, CancellationToken ct)

src/Novelly.Api/Chapters/Chapter.cs

@@ -8,7 +8,7 @@ using Novelly.Api.Tags;
 
 namespace Novelly.Api.Chapters;
 
-public class Chapter
+public class Chapter : ISoftDeletable
 {
     public Guid Id { get; set; } = Guid.NewGuid();
     public Guid NovelId { get; set; }
@@ -33,6 +33,7 @@ public class Chapter
 
     public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
     public DateTimeOffset UpdatedAt { get; set; } = DateTimeOffset.UtcNow;
+    public DateTimeOffset? DeletedAt { get; set; }
 
     public List<Beat> Beats { get; set; } = [];
 
@@ -48,5 +49,6 @@ public class ChapterEntityTypeConfiguration : IEntityTypeConfiguration<Chapter>
         entity.Property(c => c.Status).HasConversion<string>().HasMaxLength(32);
         entity.Property(c => c.Kind).HasConversion<string>().HasMaxLength(32);
         entity.HasIndex(c => new { c.NovelId, c.Number });
+        entity.HasQueryFilter(c => c.DeletedAt == null);
     }
 }

src/Novelly.Api/Chapters/ChapterContracts.cs

@@ -123,7 +123,7 @@ public static class ChapterMapping
 {
     public static ChapterResponse ToResponse(this Chapter c, int? displayNumber = null) => new(
         c.Id, c.NovelId, c.Number, c.Kind, displayNumber, c.Title, c.Summary,
-        [.. c.Locations.OrderBy(l => l.Name).Select(l => l.ToResponse())],
+        [.. c.Locations.Where(l => l.DeletedAt is null).OrderBy(l => l.Name).Select(l => l.ToResponse())],
         c.Notes,
         c.Status, c.TargetWordCount,
         [.. c.Beats.OrderBy(b => b.SortOrder).Select(b => b.ToResponse())],
@@ -133,7 +133,7 @@ public static class ChapterMapping
 
     public static ChapterSummaryResponse ToSummaryResponse(this Chapter c, int? displayNumber = null) => new(
         c.Id, c.NovelId, c.Number, c.Kind, displayNumber, c.Title, c.Summary,
-        [.. c.Locations.OrderBy(l => l.Name).Select(l => l.ToResponse())],
+        [.. c.Locations.Where(l => l.DeletedAt is null).OrderBy(l => l.Name).Select(l => l.ToResponse())],
         c.Status, c.TargetWordCount,
         c.Beats.Count, c.WordCount,
         [.. c.Tags.OrderBy(t => t.Name).Select(t => t.ToResponse())],

src/Novelly.Api/Chapters/ChapterEndpoints.cs

@@ -68,7 +68,7 @@ public static class ChapterEndpoints
 
         chapters.MapDelete("/{id:guid}", async (Guid id, ChapterService service, CancellationToken ct) =>
                 await service.DeleteAsync(id, ct) ? Results.NoContent() : Results.NotFound())
-            .WithSummary("Delete a chapter.");
+            .WithSummary("Move a chapter to the trash.");
 
         return app;
     }

src/Novelly.Api/Chapters/ChapterService.cs

@@ -31,7 +31,7 @@ public class ChapterService(
         return await db.Chapters
             .Include(c => c.Beats)
             .Include(c => c.Tags)
-            .Include(c => c.Locations)
+            .Include(c => c.Locations.Where(l => l.DeletedAt == null))
             .Where(c => c.NovelId == novelId)
             .OrderBy(c => c.Number)
             .ToListAsync(ct);
@@ -153,17 +153,18 @@ public class ChapterService(
     {
         Guard.Default(id, nameof(id));
 
-        logger.LogInformation("Deleting chapter {ChapterId}", id);
+        logger.LogInformation("Moving chapter {ChapterId} to trash", id);
 
-        var chapter = await FindAsync(id, ct);
+        var chapter = await db.Chapters.FirstOrDefaultAsync(c => c.Id == id, ct);
         if (chapter is null)
         {
+            logger.LogWarning("Chapter {ChapterId} not found", id);
             return false;
         }
 
         await access.RequireAsync(chapter.NovelId, NovelPermission.DeleteContent, ct);
 
-        db.Chapters.Remove(chapter);
+        chapter.DeletedAt = DateTimeOffset.UtcNow;
         activity.Record(chapter.NovelId, ActivityEntityKind.Chapter, ActivityAction.Deleted, chapter.Id, -chapter.WordCount);
         await db.SaveChangesAsync(ct);
         return true;
@@ -177,6 +178,7 @@ public class ChapterService(
         logger.LogDebug("Computing next chapter number for novel {NovelId}", novelId);
 
         var max = await db.Chapters
+            .IgnoreQueryFilters()
             .Where(c => c.NovelId == novelId)
             .MaxAsync(c => (int?)c.Number, ct);
 
@@ -190,10 +192,10 @@ public class ChapterService(
         logger.LogDebug("Finding chapter {ChapterId}", id);
 
         var chapter = await db.Chapters
-            .Include(c => c.Beats).ThenInclude(b => b.Characters)
+            .Include(c => c.Beats).ThenInclude(b => b.Characters.Where(ch => ch.DeletedAt == null))
             .Include(c => c.Beats).ThenInclude(b => b.Tags)
             .Include(c => c.Tags)
-            .Include(c => c.Locations)
+            .Include(c => c.Locations.Where(l => l.DeletedAt == null))
             .FirstOrDefaultAsync(c => c.Id == id, ct);
 
         if (chapter is null)

src/Novelly.Api/Characters/Character.cs

@@ -2,12 +2,13 @@ using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Metadata.Builders;
 using Novelly.Api.Beats;
 using Novelly.Api.Chapters;
+using Novelly.Api.Common;
 using Novelly.Api.Novels;
 using Novelly.Api.Tags;
 
 namespace Novelly.Api.Characters;
 
-public class Character
+public class Character : ISoftDeletable
 {
     public Guid Id { get; set; } = Guid.NewGuid();
     public Guid NovelId { get; set; }
@@ -46,6 +47,7 @@ public class Character
 
     public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
     public DateTimeOffset UpdatedAt { get; set; } = DateTimeOffset.UtcNow;
+    public DateTimeOffset? DeletedAt { get; set; }
 
     public List<CharacterRelationship> Relationships { get; set; } = [];
     public List<Tag> Tags { get; set; } = [];
@@ -79,6 +81,7 @@ public class CharacterEntityTypeConfiguration : IEntityTypeConfiguration<Charact
         entity.Property(c => c.Importance).HasConversion<string>().HasMaxLength(32);
         entity.HasIndex(c => c.NovelId);
         entity.HasIndex(c => c.SameCharacterAsId);
+        entity.HasQueryFilter(c => c.DeletedAt == null);
 
         entity.HasMany(c => c.Relationships).WithOne(r => r.Character!)
             .HasForeignKey(r => r.CharacterId).OnDelete(DeleteBehavior.Cascade);
@@ -102,5 +105,7 @@ public class CharacterRelationshipEntityTypeConfiguration : IEntityTypeConfigura
 
         entity.HasOne(r => r.RelatedCharacter).WithMany()
             .HasForeignKey(r => r.RelatedCharacterId).OnDelete(DeleteBehavior.Restrict);
+
+        entity.HasQueryFilter(r => r.Character!.DeletedAt == null && r.RelatedCharacter!.DeletedAt == null);
     }
 }

src/Novelly.Api/Characters/CharacterArcService.cs

@@ -283,7 +283,7 @@ public class CharacterArcService(
     private IQueryable<CharacterArcStage> Query() =>
         db.CharacterArcStages
             .Include(s => s.Chapter)
-            .Include(s => s.Beats).ThenInclude(b => b.Chapter);
+            .Include(s => s.Beats.Where(b => b.Chapter!.DeletedAt == null)).ThenInclude(b => b.Chapter);
 
     private async Task<CharacterArcStage?> FindAsync(Guid id, CancellationToken ct)
     {

src/Novelly.Api/Characters/CharacterArcStage.cs

@@ -33,6 +33,7 @@ public class CharacterArcStageEntityTypeConfiguration : IEntityTypeConfiguration
     {
         entity.Property(s => s.Title).IsRequired().HasMaxLength(200);
         entity.HasIndex(s => new { s.CharacterId, s.SortOrder });
+        entity.HasQueryFilter(s => s.Character!.DeletedAt == null);
 
         entity.HasOne(s => s.Chapter).WithMany()
             .HasForeignKey(s => s.ChapterId).OnDelete(DeleteBehavior.SetNull);

src/Novelly.Api/Characters/CharacterContracts.cs

@@ -294,37 +294,45 @@ public static class CharacterMapping
         c.Appearance, c.Personality, c.Backstory, c.Motivation, c.Conflict, c.Voice, c.Notes,
         [.. c.Aliases],
         c.SameCharacterAsId,
-        c.SameCharacterAs?.Name,
+        c.SameCharacterAs is { DeletedAt: null } canonical ? canonical.Name : null,
         c.RevealedInChapterId,
-        c.RevealedInChapter?.Number,
-        c.RevealedInChapter is { } revealedInChapter ? ChapterLabel(revealedInChapter, displayNumbers) : null,
+        c.RevealedInChapter is { DeletedAt: null } revealedInChapter ? revealedInChapter.Number : null,
+        c.RevealedInChapter is { DeletedAt: null } revealedInChapter2 ? ChapterLabel(revealedInChapter2, displayNumbers) : null,
         c.IdentityNote,
-        [.. c.OtherIdentities.OrderBy(o => o.Name).Select(o => new CharacterIdentityResponse(o.Id, o.Name))],
-        [.. c.Relationships.Select(r => new RelationshipResponse(
+        [.. c.OtherIdentities.Where(o => o.DeletedAt is null).OrderBy(o => o.Name).Select(o => new CharacterIdentityResponse(o.Id, o.Name))],
+        [.. c.Relationships
+            .Where(r => r.RelatedCharacter is { DeletedAt: null })
+            .Select(r => new RelationshipResponse(
                 r.Id,
                 r.RelatedCharacterId,
-            r.RelatedCharacter?.Name ?? "(unknown)",
+                r.RelatedCharacter!.Name,
                 r.RelationshipType,
                 r.Description))],
         [.. c.Tags.OrderBy(t => t.Name).Select(t => t.ToResponse())],
         [.. c.ArcStages.OrderBy(s => s.SortOrder).Select(s => s.ToResponse(displayNumbers))],
         c.UpdatedAt);
 
-    public static ArcStageResponse ToResponse(this CharacterArcStage s, IReadOnlyDictionary<Guid, int>? displayNumbers = null) => new(
+    public static ArcStageResponse ToResponse(this CharacterArcStage s, IReadOnlyDictionary<Guid, int>? displayNumbers = null)
+    {
+        var chapter = s.Chapter is { DeletedAt: null } ? s.Chapter : null;
+
+        return new(
             s.Id,
             s.CharacterId,
             s.SortOrder,
             s.Title,
             s.Result,
             s.ChapterId,
-        s.Chapter?.Number,
-        s.Chapter?.Title,
-        s.Chapter is { } chapter ? ChapterLabel(chapter, displayNumbers) : null,
+            chapter?.Number,
+            chapter?.Title,
+            chapter is not null ? ChapterLabel(chapter, displayNumbers) : null,
             [.. s.Beats
-            .OrderBy(b => b.Chapter?.Number ?? 0)
+                .Where(b => b.Chapter is { DeletedAt: null })
+                .OrderBy(b => b.Chapter!.Number)
                 .ThenBy(b => b.SortOrder)
-            .Select(b => b.ToCharacterBeatResponse(s.CharacterId, b.Chapter is { } beatChapter ? ChapterLabel(beatChapter, displayNumbers) : null))],
+                .Select(b => b.ToCharacterBeatResponse(s.CharacterId, ChapterLabel(b.Chapter!, displayNumbers)))],
             s.UpdatedAt);
+    }
 
     private static string ChapterLabel(Chapter chapter, IReadOnlyDictionary<Guid, int>? displayNumbers) =>
         ChapterNumbering.Label(chapter.Kind, displayNumbers is not null && displayNumbers.TryGetValue(chapter.Id, out var n) ? n : null, chapter.Title);

src/Novelly.Api/Characters/CharacterEndpoints.cs

@@ -103,7 +103,7 @@ public static class CharacterEndpoints
 
         characters.MapDelete("/{id:guid}", async (Guid id, CharacterService service, CancellationToken ct) =>
                 await service.DeleteAsync(id, ct) ? Results.NoContent() : Results.NotFound())
-            .WithSummary("Delete a character.");
+            .WithSummary("Move a character to the trash.");
 
         characters.MapPost("/{id:guid}/relationships", async (
                 Guid id, CreateRelationshipRequest request, CharacterService service, ChapterDisplayNumberLookup chapterLabels, CancellationToken ct) =>

src/Novelly.Api/Characters/CharacterService.cs

@@ -159,7 +159,7 @@ public class CharacterService(
     {
         Guard.Default(id, nameof(id));
 
-        logger.LogInformation("Deleting character {CharacterId}", id);
+        logger.LogInformation("Moving character {CharacterId} to trash", id);
 
         var character = await FindAsync(id, ct);
         if (character is null)
@@ -169,7 +169,7 @@ public class CharacterService(
 
         await access.RequireAsync(character.NovelId, NovelPermission.DeleteContent, ct);
 
-        db.Characters.Remove(character);
+        character.DeletedAt = DateTimeOffset.UtcNow;
         activity.Record(character.NovelId, ActivityEntityKind.Character, ActivityAction.Deleted, character.Id);
         await db.SaveChangesAsync(ct);
         return true;
@@ -351,7 +351,7 @@ public class CharacterService(
             .Include(c => c.ArcStages)
             .ThenInclude(s => s.Chapter)
             .Include(c => c.ArcStages)
-            .ThenInclude(s => s.Beats)
+            .ThenInclude(s => s.Beats.Where(b => b.Chapter!.DeletedAt == null))
             .ThenInclude(b => b.Chapter)
             .Include(c => c.SameCharacterAs)
             .Include(c => c.OtherIdentities)

src/Novelly.Api/Common/NovellyServiceRegistration.cs

@@ -15,10 +15,13 @@ using Novelly.Api.Data;
 using Novelly.Api.Genres;
 using Novelly.Api.Imports;
 using Novelly.Api.Locations;
+using Novelly.Api.Mcp;
 using Novelly.Api.Novels;
 using Novelly.Api.Questions;
 using Novelly.Api.Tags;
+using Novelly.Api.Trash;
 using Novelly.Api.Users;
+using ModelContextProtocol.Protocol;
 
 namespace Novelly.Api.Common;
 
@@ -103,8 +106,26 @@ public static class NovellyServiceRegistration
         services.AddScoped<ImportAgentService>();
         services.AddHostedService<ImportJobRunner>();
 
+        services.Configure<TrashOptions>(configuration.GetSection(TrashOptions.SectionName));
+        services.AddScoped<TrashService>();
+        services.AddSingleton(TimeProvider.System);
+        services.AddHostedService<TrashPurgeRunner>();
+
         services.AddModelValidatorsFromAssemblyContaining<Program>();
 
+        services.AddMcpServer(options => options.ServerInfo = new Implementation { Name = "novelly", Version = "1.0.0" })
+            .WithHttpTransport()
+            .WithListToolsHandler((request, ct) =>
+            {
+                var toolset = request.Services!.GetRequiredService<NovelAgentToolset>();
+                return ValueTask.FromResult(new ListToolsResult { Tools = [.. NovelMcpTools.Describe(toolset.Definitions)] });
+            })
+            .WithCallToolHandler((request, ct) =>
+            {
+                var toolset = request.Services!.GetRequiredService<NovelAgentToolset>();
+                return new ValueTask<CallToolResult>(NovelMcpTools.CallAsync(toolset, toolset.Definitions, request.Params!, ct));
+            });
+
         return services;
     }
 }

src/Novelly.Api/Common/SoftDelete.cs

@@ -0,0 +1,6 @@
+namespace Novelly.Api.Common;
+
+public interface ISoftDeletable
+{
+    DateTimeOffset? DeletedAt { get; set; }
+}

src/Novelly.Api/Data/Migrations/20260820214543_AddSoftDelete.cs

@@ -0,0 +1,69 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Novelly.Api.Data.Migrations
+{
+    /// <inheritdoc />
+    public partial class AddSoftDelete : Migration
+    {
+        /// <inheritdoc />
+        protected override void Up(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropIndex(
+                name: "IX_Locations_NovelId_Name",
+                table: "Locations");
+
+            migrationBuilder.AddColumn<long>(
+                name: "DeletedAt",
+                table: "Locations",
+                type: "INTEGER",
+                nullable: true);
+
+            migrationBuilder.AddColumn<long>(
+                name: "DeletedAt",
+                table: "Characters",
+                type: "INTEGER",
+                nullable: true);
+
+            migrationBuilder.AddColumn<long>(
+                name: "DeletedAt",
+                table: "Chapters",
+                type: "INTEGER",
+                nullable: true);
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Locations_NovelId_Name",
+                table: "Locations",
+                columns: new[] { "NovelId", "Name" },
+                unique: true,
+                filter: "\"DeletedAt\" IS NULL");
+        }
+
+        /// <inheritdoc />
+        protected override void Down(MigrationBuilder migrationBuilder)
+        {
+            migrationBuilder.DropIndex(
+                name: "IX_Locations_NovelId_Name",
+                table: "Locations");
+
+            migrationBuilder.DropColumn(
+                name: "DeletedAt",
+                table: "Locations");
+
+            migrationBuilder.DropColumn(
+                name: "DeletedAt",
+                table: "Characters");
+
+            migrationBuilder.DropColumn(
+                name: "DeletedAt",
+                table: "Chapters");
+
+            migrationBuilder.CreateIndex(
+                name: "IX_Locations_NovelId_Name",
+                table: "Locations",
+                columns: new[] { "NovelId", "Name" },
+                unique: true);
+        }
+    }
+}

src/Novelly.Api/Data/Migrations/NovelDbContextModelSnapshot.cs

@@ -319,6 +319,9 @@ namespace Novelly.Api.Data.Migrations
                     b.Property<long>("CreatedAt")
                         .HasColumnType("INTEGER");
 
+                    b.Property<long?>("DeletedAt")
+                        .HasColumnType("INTEGER");
+
                     b.Property<string>("Kind")
                         .IsRequired()
                         .HasMaxLength(32)
@@ -390,6 +393,9 @@ namespace Novelly.Api.Data.Migrations
                     b.Property<long>("CreatedAt")
                         .HasColumnType("INTEGER");
 
+                    b.Property<long?>("DeletedAt")
+                        .HasColumnType("INTEGER");
+
                     b.Property<string>("IdentityNote")
                         .HasColumnType("TEXT");
 
@@ -680,6 +686,9 @@ namespace Novelly.Api.Data.Migrations
                     b.Property<long>("CreatedAt")
                         .HasColumnType("INTEGER");
 
+                    b.Property<long?>("DeletedAt")
+                        .HasColumnType("INTEGER");
+
                     b.Property<string>("Name")
                         .IsRequired()
                         .HasMaxLength(120)
@@ -691,7 +700,8 @@ namespace Novelly.Api.Data.Migrations
                     b.HasKey("Id");
 
                     b.HasIndex("NovelId", "Name")
-                        .IsUnique();
+                        .IsUnique()
+                        .HasFilter("\"DeletedAt\" IS NULL");
 
                     b.ToTable("Locations");
                 });

src/Novelly.Api/Locations/Location.cs

@@ -1,11 +1,12 @@
 using Microsoft.EntityFrameworkCore;
 using Microsoft.EntityFrameworkCore.Metadata.Builders;
 using Novelly.Api.Chapters;
+using Novelly.Api.Common;
 using Novelly.Api.Novels;
 
 namespace Novelly.Api.Locations;
 
-public class Location
+public class Location : ISoftDeletable
 {
     public Guid Id { get; set; } = Guid.NewGuid();
 
@@ -17,6 +18,7 @@ public class Location
     public List<Chapter> Chapters { get; set; } = [];
 
     public DateTimeOffset CreatedAt { get; set; } = DateTimeOffset.UtcNow;
+    public DateTimeOffset? DeletedAt { get; set; }
 }
 
 public class LocationEntityTypeConfiguration : IEntityTypeConfiguration<Location>
@@ -25,7 +27,8 @@ public class LocationEntityTypeConfiguration : IEntityTypeConfiguration<Location
     {
         entity.Property(l => l.Name).IsRequired().HasMaxLength(120);
 
-        entity.HasIndex(l => new { l.NovelId, l.Name }).IsUnique();
+        entity.HasIndex(l => new { l.NovelId, l.Name }).IsUnique().HasFilter("\"DeletedAt\" IS NULL");
+        entity.HasQueryFilter(l => l.DeletedAt == null);
 
         entity.HasMany(l => l.Chapters).WithMany(c => c.Locations)
             .UsingEntity(join => join.ToTable("ChapterLocations"));

src/Novelly.Api/Locations/LocationEndpoints.cs

@@ -54,7 +54,7 @@ public static class LocationEndpoints
 
         locations.MapDelete("/{id:guid}", async (Guid id, LocationService service, CancellationToken ct) =>
                 await service.DeleteAsync(id, ct) ? Results.NoContent() : Results.NotFound())
-            .WithSummary("Delete a location. Whatever carried it is left alone.");
+            .WithSummary("Move a location to the trash. Whatever carried it is left alone.");
 
         return app;
     }

src/Novelly.Api/Locations/LocationService.cs

@@ -122,7 +122,7 @@ public class LocationService(
     {
         Guard.Default(locationId, nameof(locationId));
 
-        logger.LogInformation("Deleting location {LocationId}", locationId);
+        logger.LogInformation("Moving location {LocationId} to trash", locationId);
 
         var location = await db.Locations.FirstOrDefaultAsync(l => l.Id == locationId, ct);
         if (location is null)
@@ -133,7 +133,7 @@ public class LocationService(
 
         await access.RequireAsync(location.NovelId, NovelPermission.DeleteContent, ct);
 
-        db.Locations.Remove(location);
+        location.DeletedAt = DateTimeOffset.UtcNow;
         activity.Record(location.NovelId, ActivityEntityKind.Location, ActivityAction.Deleted, location.Id);
         await db.SaveChangesAsync(ct);
         return true;

src/Novelly.Api/Mcp/McpEndpoints.cs

@@ -0,0 +1,10 @@
+namespace Novelly.Api.Mcp;
+
+public static class McpEndpoints
+{
+    public static IEndpointRouteBuilder MapNovelMcp(this IEndpointRouteBuilder app)
+    {
+        app.MapMcp("/mcp");
+        return app;
+    }
+}

src/Novelly.Api/Mcp/NovelMcpTools.cs

@@ -0,0 +1,109 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+using ModelContextProtocol.Protocol;
+using Novelly.Api.Agent;
+
+namespace Novelly.Api.Mcp;
+
+public static class NovelMcpTools
+{
+    private const string NovelIdProperty = "novelId";
+
+    public static IReadOnlyList<Tool> Describe(IReadOnlyList<AgentToolDefinition> definitions) =>
+        [.. definitions.Select(definition => new Tool
+        {
+            Name = definition.Name,
+            Description = definition.Description,
+            InputSchema = definition.RequiresNovelId ? WithNovelId(definition.InputSchema) : definition.InputSchema
+        })];
+
+    public static async Task<CallToolResult> CallAsync(
+        NovelAgentToolset toolset,
+        IReadOnlyList<AgentToolDefinition> definitions,
+        CallToolRequestParams parameters,
+        CancellationToken ct)
+    {
+        var definition = definitions.FirstOrDefault(d => d.Name == parameters.Name);
+        if (definition is null)
+        {
+            return new CallToolResult
+            {
+                IsError = true,
+                Content = [new TextContentBlock { Text = $"No such tool: '{parameters.Name}'." }]
+            };
+        }
+
+        var arguments = ToJsonElement(parameters.Arguments);
+
+        Guid novelId;
+        if (definition.RequiresNovelId)
+        {
+            try
+            {
+                novelId = JsonInput.RequiredGuid(arguments, NovelIdProperty);
+            }
+            catch (ArgumentException ex)
+            {
+                return new CallToolResult { IsError = true, Content = [new TextContentBlock { Text = ex.Message }] };
+            }
+        }
+        else
+        {
+            novelId = Guid.Empty;
+        }
+
+        var result = await toolset.ExecuteAsync(parameters.Name, novelId, arguments, ct);
+
+        return new CallToolResult
+        {
+            IsError = result.IsError,
+            Content = [new TextContentBlock { Text = result.Content }]
+        };
+    }
+
+    private static JsonElement ToJsonElement(IDictionary<string, JsonElement>? arguments)
+    {
+        if (arguments is null)
+        {
+            return JsonSerializer.Deserialize<JsonElement>("{}");
+        }
+
+        var obj = new JsonObject();
+        foreach (var (key, value) in arguments)
+        {
+            obj[key] = JsonNode.Parse(value.GetRawText());
+        }
+
+        return JsonSerializer.Deserialize<JsonElement>(obj.ToJsonString());
+    }
+
+    private static JsonElement WithNovelId(JsonElement schema)
+    {
+        var node = JsonNode.Parse(schema.GetRawText())!.AsObject();
+        var properties = new JsonObject
+        {
+            [NovelIdProperty] = new JsonObject
+            {
+                ["type"] = "string",
+                ["description"] = "The novel's id."
+            }
+        };
+
+        if (node["properties"] is JsonObject existingProperties)
+        {
+            foreach (var (key, value) in existingProperties.ToList())
+            {
+                existingProperties.Remove(key);
+                properties[key] = value;
+            }
+        }
+
+        node["properties"] = properties;
+
+        var required = node["required"] as JsonArray ?? [];
+        required.Insert(0, NovelIdProperty);
+        node["required"] = required;
+
+        return JsonSerializer.Deserialize<JsonElement>(node.ToJsonString());
+    }
+}

src/Novelly.Api/Novelly.Api.csproj

@@ -14,6 +14,7 @@
     </PackageReference>
     <PackageReference Include="Microsoft.EntityFrameworkCore.Sqlite" Version="10.0.10" />
     <PackageReference Include="Microsoft.OpenApi" Version="2.11.0" />
+    <PackageReference Include="ModelContextProtocol.AspNetCore" Version="2.1.0" />
     <PackageReference Include="Serilog.AspNetCore" Version="10.0.0" />
     <PackageReference Include="Serilog.Settings.Configuration" Version="10.0.1" />
     <PackageReference Include="SQLitePCLRaw.bundle_e_sqlite3" Version="3.0.5" />

src/Novelly.Api/Program.cs

@@ -12,9 +12,11 @@ using Novelly.Api.Data;
 using Novelly.Api.Genres;
 using Novelly.Api.Imports;
 using Novelly.Api.Locations;
+using Novelly.Api.Mcp;
 using Novelly.Api.Novels;
 using Novelly.Api.Questions;
 using Novelly.Api.Tags;
+using Novelly.Api.Trash;
 using Novelly.Api.Users;
 using Serilog;
 
@@ -111,6 +113,7 @@ if (app.Environment.IsDevelopment())
 }
 
 app.MapDefaultEndpoints();
+app.MapNovelMcp();
 
 app.MapGet("/api/health", () => Results.Ok(new { status = "ok" })).WithTags("Health").AllowAnonymous();
 app.MapUiSettingsEndpoints();
@@ -128,7 +131,8 @@ app.MapNovelEndpoints()
    .MapOpenQuestionEndpoints()
    .MapAgentEndpoints()
    .MapImportEndpoints()
-   .MapActivityEndpoints();
+   .MapActivityEndpoints()
+   .MapTrashEndpoints();
 
 app.Run();
 

src/Novelly.Api/Questions/OpenQuestionContracts.cs

@@ -76,22 +76,28 @@ public class ResolveOpenQuestionRequestValidator : IModelValidator<ResolveOpenQu
 
 public static class OpenQuestionMapping
 {
-    public static OpenQuestionResponse ToResponse(this OpenQuestion q, IReadOnlyDictionary<Guid, int>? displayNumbers = null) => new(
+    public static OpenQuestionResponse ToResponse(this OpenQuestion q, IReadOnlyDictionary<Guid, int>? displayNumbers = null)
+    {
+        var chapter = q.Chapter is { DeletedAt: null } ? q.Chapter : null;
+        var character = q.Character is { DeletedAt: null } ? q.Character : null;
+
+        return new(
             q.Id,
             q.NovelId,
             q.Question,
             q.Detail,
             q.ChapterId,
-        q.Chapter?.Number,
-        q.Chapter?.Title,
-        q.Chapter is { } chapter
+            chapter?.Number,
+            chapter?.Title,
+            chapter is not null
                 ? ChapterNumbering.Label(chapter.Kind, displayNumbers is not null && displayNumbers.TryGetValue(chapter.Id, out var n) ? n : null, chapter.Title)
                 : null,
             q.CharacterId,
-        q.Character?.Name,
+            character?.Name,
             q.Resolution,
             q.IsResolved,
             q.ResolvedAt,
             q.CreatedAt,
             q.UpdatedAt);
     }
+}

src/Novelly.Api/Trash/TrashContracts.cs

@@ -0,0 +1,9 @@
+namespace Novelly.Api.Trash;
+
+public record TrashedItemResponse(
+    Guid Id,
+    TrashEntityKind Kind,
+    string Label,
+    string? Detail,
+    DateTimeOffset DeletedAt,
+    DateTimeOffset PurgeAfter);

src/Novelly.Api/Trash/TrashEndpoints.cs

@@ -0,0 +1,38 @@
+using Novelly.Api.Common;
+using Novelly.Api.Common.Validation;
+
+namespace Novelly.Api.Trash;
+
+public static class TrashEndpoints
+{
+    public static IEndpointRouteBuilder MapTrashEndpoints(this IEndpointRouteBuilder app)
+    {
+        var novelScoped = app.MapGroup("/api/novels/{novelId:guid}/trash").WithTags("Trash")
+            .AddEndpointFilter<RequestLoggingEndpointFilter>()
+            .AddEndpointFilter<ValidationEndpointFilter>();
+
+        novelScoped.MapGet("/", async (Guid novelId, TrashService service, CancellationToken ct) =>
+                Results.Ok(await service.ListAsync(novelId, ct)))
+            .WithSummary("List everything in a novel's trash.");
+
+        novelScoped.MapDelete("/", async (Guid novelId, TrashService service, CancellationToken ct) =>
+                Results.Ok(new { purged = await service.EmptyAsync(novelId, ct) }))
+            .WithSummary("Empty a novel's trash, permanently deleting everything in it.");
+
+        var trash = app.MapGroup("/api/trash").WithTags("Trash")
+            .AddEndpointFilter<RequestLoggingEndpointFilter>()
+            .AddEndpointFilter<ValidationEndpointFilter>();
+
+        trash.MapPost("/{kind}/{id:guid}/restore", async (
+                TrashEntityKind kind, Guid id, TrashService service, CancellationToken ct) =>
+                await service.RestoreAsync(kind, id, ct) ? Results.NoContent() : Results.NotFound())
+            .WithSummary("Restore a trashed item.");
+
+        trash.MapDelete("/{kind}/{id:guid}", async (
+                TrashEntityKind kind, Guid id, TrashService service, CancellationToken ct) =>
+                await service.PurgeAsync(kind, id, ct) ? Results.NoContent() : Results.NotFound())
+            .WithSummary("Permanently delete a trashed item.");
+
+        return app;
+    }
+}

src/Novelly.Api/Trash/TrashEntityKind.cs

@@ -0,0 +1,8 @@
+namespace Novelly.Api.Trash;
+
+public enum TrashEntityKind
+{
+    Character,
+    Chapter,
+    Location
+}

src/Novelly.Api/Trash/TrashOptions.cs

@@ -0,0 +1,10 @@
+namespace Novelly.Api.Trash;
+
+public class TrashOptions
+{
+    public const string SectionName = "Trash";
+
+    public bool Enabled { get; set; } = true;
+    public int RetentionDays { get; set; } = 30;
+    public TimeOnly PurgeAtLocalTime { get; set; } = new(2, 0);
+}

src/Novelly.Api/Trash/TrashPurge.cs

@@ -0,0 +1,57 @@
+using Microsoft.EntityFrameworkCore;
+using Novelly.Api.Data;
+
+namespace Novelly.Api.Trash;
+
+internal static class TrashPurge
+{
+    public static async Task<bool> RemoveAsync(INovelDbContext db, TrashEntityKind kind, Guid id, CancellationToken ct) => kind switch
+    {
+        TrashEntityKind.Character => await RemoveCharacterAsync(db, id, ct),
+        TrashEntityKind.Chapter => await RemoveChapterAsync(db, id, ct),
+        TrashEntityKind.Location => await RemoveLocationAsync(db, id, ct),
+        _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, null)
+    };
+
+    private static async Task<bool> RemoveCharacterAsync(INovelDbContext db, Guid id, CancellationToken ct)
+    {
+        var character = await db.Characters.IgnoreQueryFilters().FirstOrDefaultAsync(c => c.Id == id, ct);
+        if (character is null)
+        {
+            return false;
+        }
+
+        var inboundRelationships = await db.CharacterRelationships
+            .IgnoreQueryFilters()
+            .Where(r => r.RelatedCharacterId == id)
+            .ToListAsync(ct);
+
+        db.CharacterRelationships.RemoveRange(inboundRelationships);
+        db.Characters.Remove(character);
+        return true;
+    }
+
+    private static async Task<bool> RemoveChapterAsync(INovelDbContext db, Guid id, CancellationToken ct)
+    {
+        var chapter = await db.Chapters.IgnoreQueryFilters().FirstOrDefaultAsync(c => c.Id == id, ct);
+        if (chapter is null)
+        {
+            return false;
+        }
+
+        db.Chapters.Remove(chapter);
+        return true;
+    }
+
+    private static async Task<bool> RemoveLocationAsync(INovelDbContext db, Guid id, CancellationToken ct)
+    {
+        var location = await db.Locations.IgnoreQueryFilters().FirstOrDefaultAsync(l => l.Id == id, ct);
+        if (location is null)
+        {
+            return false;
+        }
+
+        db.Locations.Remove(location);
+        return true;
+    }
+}

src/Novelly.Api/Trash/TrashPurgeRunner.cs

@@ -0,0 +1,84 @@
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Options;
+using Novelly.Api.Data;
+
+namespace Novelly.Api.Trash;
+
+public class TrashPurgeRunner(
+    IServiceScopeFactory scopeFactory,
+    IOptions<TrashOptions> options,
+    TimeProvider clock,
+    ILogger<TrashPurgeRunner> logger) : BackgroundService
+{
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        if (!options.Value.Enabled)
+        {
+            logger.LogInformation("Trash purge is disabled");
+            return;
+        }
+
+        await RunPurgePassAsync(stoppingToken);
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            var now = clock.GetLocalNow();
+            var delay = TrashPurgeSchedule.NextRunAfter(now, options.Value.PurgeAtLocalTime) - now;
+
+            try
+            {
+                await Task.Delay(delay, clock, stoppingToken);
+            }
+            catch (OperationCanceledException)
+            {
+                break;
+            }
+
+            await RunPurgePassAsync(stoppingToken);
+        }
+    }
+
+    private async Task RunPurgePassAsync(CancellationToken ct)
+    {
+        try
+        {
+            using var scope = scopeFactory.CreateScope();
+            var db = scope.ServiceProvider.GetRequiredService<INovelDbContext>();
+
+            var cutoff = clock.GetUtcNow().AddDays(-options.Value.RetentionDays);
+            var (characterCount, chapterCount, locationCount) = await SweepAsync(db, cutoff, ct);
+
+            logger.LogInformation(
+                "Trash purge removed {CharacterCount} characters, {ChapterCount} chapters, {LocationCount} locations",
+                characterCount, chapterCount, locationCount);
+        }
+        catch (Exception ex) when (ex is not OperationCanceledException)
+        {
+            logger.LogError(ex, "Trash purge pass failed");
+        }
+    }
+
+    public static async Task<(int Characters, int Chapters, int Locations)> SweepAsync(
+        INovelDbContext db, DateTimeOffset cutoff, CancellationToken ct)
+    {
+        var characterIds = await db.Characters.IgnoreQueryFilters()
+            .Where(c => c.DeletedAt != null && c.DeletedAt < cutoff).Select(c => c.Id).ToListAsync(ct);
+        var chapterIds = await db.Chapters.IgnoreQueryFilters()
+            .Where(c => c.DeletedAt != null && c.DeletedAt < cutoff).Select(c => c.Id).ToListAsync(ct);
+        var locationIds = await db.Locations.IgnoreQueryFilters()
+            .Where(l => l.DeletedAt != null && l.DeletedAt < cutoff).Select(l => l.Id).ToListAsync(ct);
+
+        foreach (var id in characterIds)
+            await TrashPurge.RemoveAsync(db, TrashEntityKind.Character, id, ct);
+
+        foreach (var id in chapterIds)
+            await TrashPurge.RemoveAsync(db, TrashEntityKind.Chapter, id, ct);
+
+        foreach (var id in locationIds)
+            await TrashPurge.RemoveAsync(db, TrashEntityKind.Location, id, ct);
+
+        await db.SaveChangesAsync(ct);
+
+        return (characterIds.Count, chapterIds.Count, locationIds.Count);
+    }
+}

src/Novelly.Api/Trash/TrashPurgeSchedule.cs

@@ -0,0 +1,11 @@
+namespace Novelly.Api.Trash;
+
+public static class TrashPurgeSchedule
+{
+    public static DateTimeOffset NextRunAfter(DateTimeOffset now, TimeOnly runAt)
+    {
+        var candidate = new DateTimeOffset(now.Year, now.Month, now.Day, runAt.Hour, runAt.Minute, runAt.Second, now.Offset);
+
+        return candidate > now ? candidate : candidate.AddDays(1);
+    }
+}

src/Novelly.Api/Trash/TrashService.cs

@@ -0,0 +1,186 @@
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.Options;
+using Novelly.Api.Activity;
+using Novelly.Api.Common;
+using Novelly.Api.Data;
+using Novelly.Api.Users;
+
+namespace Novelly.Api.Trash;
+
+public class TrashService(
+    INovelDbContext db,
+    NovelAccessService access,
+    ActivityLog activity,
+    IOptions<TrashOptions> options,
+    ILogger<TrashService> logger)
+{
+    public async Task<IReadOnlyList<TrashedItemResponse>> ListAsync(Guid novelId, CancellationToken ct = default)
+    {
+        Guard.Default(novelId, nameof(novelId));
+
+        logger.LogInformation("Listing trash for novel {NovelId}", novelId);
+
+        await access.RequireAsync(novelId, NovelPermission.Read, ct);
+
+        var retentionDays = options.Value.RetentionDays;
+
+        var characters = await db.Characters
+            .IgnoreQueryFilters()
+            .Where(c => c.NovelId == novelId && c.DeletedAt != null)
+            .Select(c => new TrashedItemResponse(
+                c.Id, TrashEntityKind.Character, c.Name,
+                c.ArcStages.Count > 0 ? $"{c.ArcStages.Count} arc stages" : null,
+                c.DeletedAt!.Value, c.DeletedAt!.Value.AddDays(retentionDays)))
+            .ToListAsync(ct);
+
+        var chapters = await db.Chapters
+            .IgnoreQueryFilters()
+            .Where(c => c.NovelId == novelId && c.DeletedAt != null)
+            .Select(c => new TrashedItemResponse(
+                c.Id, TrashEntityKind.Chapter, c.Title,
+                c.Beats.Count > 0 ? $"{c.Beats.Count} beats" : null,
+                c.DeletedAt!.Value, c.DeletedAt!.Value.AddDays(retentionDays)))
+            .ToListAsync(ct);
+
+        var locations = await db.Locations
+            .IgnoreQueryFilters()
+            .Where(l => l.NovelId == novelId && l.DeletedAt != null)
+            .Select(l => new TrashedItemResponse(
+                l.Id, TrashEntityKind.Location, l.Name,
+                l.Chapters.Count > 0 ? $"used by {l.Chapters.Count} chapters" : null,
+                l.DeletedAt!.Value, l.DeletedAt!.Value.AddDays(retentionDays)))
+            .ToListAsync(ct);
+
+        return [.. characters.Concat(chapters).Concat(locations).OrderByDescending(i => i.DeletedAt)];
+    }
+
+    public async Task<bool> RestoreAsync(TrashEntityKind kind, Guid id, CancellationToken ct = default)
+    {
+        Guard.Default(id, nameof(id));
+
+        logger.LogInformation("Restoring {Kind} {ItemId} from trash", kind, id);
+
+        return kind switch
+        {
+            TrashEntityKind.Character => await RestoreCharacterAsync(id, ct),
+            TrashEntityKind.Chapter => await RestoreChapterAsync(id, ct),
+            TrashEntityKind.Location => await RestoreLocationAsync(id, ct),
+            _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, null)
+        };
+    }
+
+    public async Task<bool> PurgeAsync(TrashEntityKind kind, Guid id, CancellationToken ct = default)
+    {
+        Guard.Default(id, nameof(id));
+
+        logger.LogInformation("Purging {Kind} {ItemId} from trash", kind, id);
+
+        var novelId = await NovelIdOfTrashedAsync(kind, id, ct);
+        if (novelId is null)
+        {
+            return false;
+        }
+
+        await access.RequireAsync(novelId.Value, NovelPermission.DeleteContent, ct);
+
+        var removed = await TrashPurge.RemoveAsync(db, kind, id, ct);
+        if (!removed)
+        {
+            return false;
+        }
+
+        await db.SaveChangesAsync(ct);
+        return true;
+    }
+
+    public async Task<int> EmptyAsync(Guid novelId, CancellationToken ct = default)
+    {
+        Guard.Default(novelId, nameof(novelId));
+
+        logger.LogInformation("Emptying trash for novel {NovelId}", novelId);
+
+        await access.RequireAsync(novelId, NovelPermission.DeleteContent, ct);
+
+        var items = await ListAsync(novelId, ct);
+
+        var purged = 0;
+        foreach (var item in items)
+        {
+            if (await TrashPurge.RemoveAsync(db, item.Kind, item.Id, ct))
+            {
+                purged++;
+            }
+        }
+
+        await db.SaveChangesAsync(ct);
+        logger.LogInformation("Emptied {Count} items from trash for novel {NovelId}", purged, novelId);
+        return purged;
+    }
+
+    private async Task<bool> RestoreCharacterAsync(Guid id, CancellationToken ct)
+    {
+        var character = await db.Characters.IgnoreQueryFilters().FirstOrDefaultAsync(c => c.Id == id && c.DeletedAt != null, ct);
+        if (character is null)
+        {
+            logger.LogWarning("Trashed character {CharacterId} not found", id);
+            return false;
+        }
+
+        await access.RequireAsync(character.NovelId, NovelPermission.DeleteContent, ct);
+
+        character.DeletedAt = null;
+        activity.Record(character.NovelId, ActivityEntityKind.Character, ActivityAction.Restored, character.Id);
+        await db.SaveChangesAsync(ct);
+        return true;
+    }
+
+    private async Task<bool> RestoreChapterAsync(Guid id, CancellationToken ct)
+    {
+        var chapter = await db.Chapters.IgnoreQueryFilters().FirstOrDefaultAsync(c => c.Id == id && c.DeletedAt != null, ct);
+        if (chapter is null)
+        {
+            logger.LogWarning("Trashed chapter {ChapterId} not found", id);
+            return false;
+        }
+
+        await access.RequireAsync(chapter.NovelId, NovelPermission.DeleteContent, ct);
+
+        chapter.DeletedAt = null;
+        activity.Record(chapter.NovelId, ActivityEntityKind.Chapter, ActivityAction.Restored, chapter.Id, chapter.WordCount);
+        await db.SaveChangesAsync(ct);
+        return true;
+    }
+
+    private async Task<bool> RestoreLocationAsync(Guid id, CancellationToken ct)
+    {
+        var location = await db.Locations.IgnoreQueryFilters().FirstOrDefaultAsync(l => l.Id == id && l.DeletedAt != null, ct);
+        if (location is null)
+        {
+            logger.LogWarning("Trashed location {LocationId} not found", id);
+            return false;
+        }
+
+        await access.RequireAsync(location.NovelId, NovelPermission.DeleteContent, ct);
+
+        var clash = await db.Locations.FirstOrDefaultAsync(
+            l => l.NovelId == location.NovelId && EF.Functions.Like(l.Name, location.Name), ct);
+        if (clash is not null)
+        {
+            logger.LogWarning("Rejected restore of location {LocationId}: '{Name}' already exists as {ClashLocationId}", id, location.Name, clash.Id);
+            throw new InvalidOperationException($"The novel already has a location called '{clash.Name}'.");
+        }
+
+        location.DeletedAt = null;
+        activity.Record(location.NovelId, ActivityEntityKind.Location, ActivityAction.Restored, location.Id);
+        await db.SaveChangesAsync(ct);
+        return true;
+    }
+
+    private async Task<Guid?> NovelIdOfTrashedAsync(TrashEntityKind kind, Guid id, CancellationToken ct) => kind switch
+    {
+        TrashEntityKind.Character => (await db.Characters.IgnoreQueryFilters().Where(c => c.Id == id && c.DeletedAt != null).Select(c => (Guid?)c.NovelId).FirstOrDefaultAsync(ct)),
+        TrashEntityKind.Chapter => (await db.Chapters.IgnoreQueryFilters().Where(c => c.Id == id && c.DeletedAt != null).Select(c => (Guid?)c.NovelId).FirstOrDefaultAsync(ct)),
+        TrashEntityKind.Location => (await db.Locations.IgnoreQueryFilters().Where(l => l.Id == id && l.DeletedAt != null).Select(l => (Guid?)l.NovelId).FirstOrDefaultAsync(ct)),
+        _ => throw new ArgumentOutOfRangeException(nameof(kind), kind, null)
+    };
+}

src/Novelly.Api/appsettings.json

@@ -38,5 +38,10 @@
   },
   "Imports": {
     "RootPath": null
+  },
+  "Trash": {
+    "Enabled": true,
+    "RetentionDays": 30,
+    "PurgeAtLocalTime": "02:00"
   }
 }

src/Novelly.Mcp/NovelApiClient.cs

@@ -1,101 +0,0 @@
-using System.Net;
-using System.Net.Http.Json;
-using System.Text.Json;
-using Microsoft.Extensions.Logging;
-using ModelContextProtocol.Protocol;
-
-namespace Novelly.Mcp;
-
-public class NovelApiClient(HttpClient http, ILogger<NovelApiClient> logger)
-{
-    private static readonly JsonSerializerOptions Options = new(JsonSerializerDefaults.Web)
-    {
-        WriteIndented = true
-    };
-
-    public Task<CallToolResult> GetAsync(string path, CancellationToken ct = default) => SendAsync(new HttpRequestMessage(HttpMethod.Get, path), ct);
-
-    public Task<CallToolResult> PostAsync(string path, object body, CancellationToken ct = default) =>
-        SendAsync(new HttpRequestMessage(HttpMethod.Post, path)
-        {
-            Content = JsonContent.Create(body, options: Options)
-        }, ct);
-
-    public Task<CallToolResult> PatchAsync(string path, object body, CancellationToken ct = default) =>
-        SendAsync(new HttpRequestMessage(HttpMethod.Patch, path)
-        {
-            Content = JsonContent.Create(body, options: Options)
-        }, ct);
-
-    public Task<CallToolResult> PutAsync(string path, object body, CancellationToken ct = default) =>
-        SendAsync(new HttpRequestMessage(HttpMethod.Put, path)
-        {
-            Content = JsonContent.Create(body, options: Options)
-        }, ct);
-
-    public Task<CallToolResult> DeleteAsync(string path, CancellationToken ct = default) => SendAsync(new HttpRequestMessage(HttpMethod.Delete, path), ct);
-
-    private async Task<CallToolResult> SendAsync(HttpRequestMessage request, CancellationToken ct)
-    {
-        HttpResponseMessage response;
-        try
-        {
-            response = await http.SendAsync(request, ct);
-        }
-        catch (HttpRequestException ex)
-        {
-            logger.LogError(ex, "Could not reach the Novelly API at {BaseAddress}", http.BaseAddress);
-            return Error($"Could not reach the Novelly API at {http.BaseAddress}. Is it running? ({ex.Message})");
-        }
-
-        var body = await response.Content.ReadAsStringAsync(ct);
-
-        if (response.IsSuccessStatusCode)
-        {
-            return Ok(string.IsNullOrWhiteSpace(body) ? "{\"ok\":true}" : Prettify(body));
-        }
-
-        var detail = TryReadProblemDetail(body) ?? body;
-        return Error(response.StatusCode switch
-        {
-            HttpStatusCode.Unauthorized => $"Not permitted: the Novelly API rejected the service api key. Set NOVELLY_API_KEY to match the API's Auth:ServiceApiKey. ({detail})",
-            HttpStatusCode.Forbidden => $"Not permitted: {detail}",
-            HttpStatusCode.NotFound => $"Not found: {detail}",
-            HttpStatusCode.BadRequest => $"Rejected: {detail}",
-            _ => $"API returned {(int)response.StatusCode}: {detail}"
-        });
-    }
-
-    private static CallToolResult Ok(string text) =>
-        new() { Content = [new TextContentBlock { Text = text }] };
-
-    private static CallToolResult Error(string message) =>
-        new() { Content = [new TextContentBlock { Text = message }], IsError = true };
-
-    private string Prettify(string json)
-    {
-        try
-        {
-            return JsonSerializer.Serialize(JsonSerializer.Deserialize<JsonElement>(json), Options);
-        }
-        catch (JsonException ex)
-        {
-            logger.LogWarning(ex, "Response body was not valid JSON; returning it unformatted");
-            return json;
-        }
-    }
-
-    private string? TryReadProblemDetail(string body)
-    {
-        try
-        {
-            var problem = JsonSerializer.Deserialize<JsonElement>(body);
-            return problem.TryGetProperty("detail", out var detail) ? detail.GetString() : null;
-        }
-        catch (JsonException ex)
-        {
-            logger.LogWarning(ex, "Error response body was not valid JSON problem details");
-            return null;
-        }
-    }
-}

src/Novelly.Mcp/Novelly.Mcp.csproj

@@ -1,17 +0,0 @@
-<Project Sdk="Microsoft.NET.Sdk">
-
-  <PropertyGroup>
-    <OutputType>Exe</OutputType>
-    <TargetFramework>net10.0</TargetFramework>
-    <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <LangVersion>latest</LangVersion>
-  </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Microsoft.Extensions.Hosting" Version="10.0.10" />
-    <PackageReference Include="Microsoft.Extensions.Http" Version="10.0.10" />
-    <PackageReference Include="ModelContextProtocol" Version="2.1.0" />
-  </ItemGroup>
-
-</Project>

src/Novelly.Mcp/Program.cs

@@ -1,31 +0,0 @@
-using Microsoft.Extensions.DependencyInjection;
-using Microsoft.Extensions.Hosting;
-using Microsoft.Extensions.Logging;
-using Novelly.Mcp;
-
-var builder = Host.CreateApplicationBuilder(args);
-
-builder.Logging.ClearProviders();
-builder.Logging.AddConsole(options => options.LogToStandardErrorThreshold = LogLevel.Trace);
-builder.Logging.SetMinimumLevel(LogLevel.Warning);
-
-var apiBaseUrl = builder.Configuration["NOVELLY_API_URL"] ?? "http://localhost:5080";
-var apiKey = builder.Configuration["NOVELLY_API_KEY"];
-
-builder.Services.AddHttpClient<NovelApiClient>(client =>
-{
-    client.BaseAddress = new Uri(apiBaseUrl);
-    client.Timeout = TimeSpan.FromSeconds(30);
-
-    if (!string.IsNullOrWhiteSpace(apiKey))
-    {
-        client.DefaultRequestHeaders.Add("X-Novelly-Api-Key", apiKey);
-    }
-});
-
-builder.Services
-    .AddMcpServer()
-    .WithStdioServerTransport()
-    .WithToolsFromAssembly();
-
-await builder.Build().RunAsync();

src/Novelly.Mcp/Tools/BeatTools.cs

@@ -1,92 +0,0 @@
-using System.ComponentModel;
-using ModelContextProtocol.Protocol;
-using ModelContextProtocol.Server;
-
-namespace Novelly.Mcp.Tools;
-
-[McpServerToolType]
-public static class BeatTools
-{
-    [McpServerTool(Name = "get_chapter_outline")]
-    [Description("Read a chapter's outline: its beats in order. Each beat is one row — a short "
-                 + "title, who it belongs to, what happened, and what it sets up. The chapter's "
-                 + "summary paragraph and drafted prose sit on the chapter itself, via get_chapter.")]
-    public static Task<CallToolResult> GetChapterOutline(
-        NovelApiClient api,
-        [Description("The chapter's id.")] Guid chapterId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/chapters/{chapterId}/beats", ct);
-
-    [McpServerTool(Name = "create_beat")]
-    [Description("Add a beat to a chapter's outline. Keep the title to three to five words — it "
-                 + "is a handle, not a sentence; detail belongs in whatHappened and whatsNext.")]
-    public static Task<CallToolResult> CreateBeat(
-        NovelApiClient api,
-        [Description("The chapter's id.")] Guid chapterId,
-        [Description("Three to five words naming the beat.")] string title,
-        CancellationToken ct,
-        [Description("Position in the chapter. Appended to the end when omitted.")] int? sortOrder = null,
-        [Description("Ids of the characters whose beat this is.")] Guid[]? characterIds = null,
-        [Description("The event itself.")] string? whatHappened = null,
-        [Description("What it sets in motion — the hook into the next beat.")] string? whatsNext = null,
-        [Description("Tags for cross-referencing. Unknown tags are created.")] string[]? tags = null) =>
-        api.PostAsync($"/api/chapters/{chapterId}/beats",
-            new { title, sortOrder, characterIds, whatHappened, whatsNext, tags }, ct);
-
-    [McpServerTool(Name = "update_beat")]
-    [Description("Revise a beat. Only the fields you supply change. Supplying a characterIds or "
-                 + "tag list replaces the beat's characters or tags outright — pass an empty list "
-                 + "to clear one, and include everything you want to keep.")]
-    public static Task<CallToolResult> UpdateBeat(
-        NovelApiClient api,
-        [Description("The beat's id.")] Guid beatId,
-        CancellationToken ct,
-        [Description("Three to five words naming the beat.")] string? title = null,
-        [Description("Position in the chapter.")] int? sortOrder = null,
-        [Description("Ids of the characters whose beat this is. Replaces the existing list.")] Guid[]? characterIds = null,
-        [Description("The event itself.")] string? whatHappened = null,
-        [Description("What it sets in motion.")] string? whatsNext = null,
-        [Description("Tags for cross-referencing. Replaces the existing tags.")] string[]? tags = null) =>
-        api.PatchAsync($"/api/beats/{beatId}",
-            new { title, sortOrder, characterIds, whatHappened, whatsNext, tags }, ct);
-
-    [McpServerTool(Name = "delete_beat")]
-    [Description("Remove a beat from a chapter's outline. Confirm with the writer first.")]
-    public static Task<CallToolResult> DeleteBeat(
-        NovelApiClient api,
-        [Description("The beat's id.")] Guid beatId,
-        CancellationToken ct) =>
-        api.DeleteAsync($"/api/beats/{beatId}", ct);
-
-    [McpServerTool(Name = "assign_character_to_beats")]
-    [Description("Add a character to several beats at once. Leaves each beat's existing characters "
-                 + "and other fields alone — this only adds, it never removes.")]
-    public static Task<CallToolResult> AssignCharacterToBeats(
-        NovelApiClient api,
-        [Description("The chapter's id.")] Guid chapterId,
-        [Description("Id of the character to add.")] Guid characterId,
-        [Description("Ids of the beats to add the character to.")] Guid[] beatIds,
-        CancellationToken ct) =>
-        api.PostAsync($"/api/chapters/{chapterId}/beats/assign-character", new { characterId, beatIds }, ct);
-
-    [McpServerTool(Name = "reorder_beats")]
-    [Description("Renumber a chapter's beats to match the order given. List every beat id in the "
-                 + "order wanted; any left out keep their relative position at the end.")]
-    public static Task<CallToolResult> ReorderBeats(
-        NovelApiClient api,
-        [Description("The chapter's id.")] Guid chapterId,
-        [Description("Beat ids in their new order.")] Guid[] beatIds,
-        CancellationToken ct) =>
-        api.PostAsync($"/api/chapters/{chapterId}/beats/reorder", new { beatIds }, ct);
-
-    [McpServerTool(Name = "move_beats")]
-    [Description("Move one or more beats from one chapter to another, appending them to the "
-                 + "target chapter's end in the order given.")]
-    public static Task<CallToolResult> MoveBeats(
-        NovelApiClient api,
-        [Description("The beats' current chapter id.")] Guid chapterId,
-        [Description("Id of the chapter to move the beats into.")] Guid targetChapterId,
-        [Description("Ids of the beats to move.")] Guid[] beatIds,
-        CancellationToken ct) =>
-        api.PostAsync($"/api/chapters/{chapterId}/beats/move", new { targetChapterId, beatIds }, ct);
-}

src/Novelly.Mcp/Tools/CharacterTools.cs

@@ -1,226 +0,0 @@
-using System.ComponentModel;
-using ModelContextProtocol.Protocol;
-using ModelContextProtocol.Server;
-
-namespace Novelly.Mcp.Tools;
-
-[McpServerToolType]
-public static class CharacterTools
-{
-    [McpServerTool(Name = "list_characters")]
-    [Description("List a novel's character dossiers in full, including their relationships.")]
-    public static Task<CallToolResult> ListCharacters(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/novels/{novelId}/characters", ct);
-
-    [McpServerTool(Name = "get_character")]
-    [Description("Read one character's dossier.")]
-    public static Task<CallToolResult> GetCharacter(
-        NovelApiClient api,
-        [Description("The character's id.")] Guid characterId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/characters/{characterId}", ct);
-
-    [McpServerTool(Name = "create_character")]
-    [Description("Add a character dossier to a novel. Name is the only requirement — leave a field "
-                 + "blank when the writer has not decided it yet rather than inventing detail.")]
-    public static Task<CallToolResult> CreateCharacter(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        [Description("The character's name.")] string name,
-        CancellationToken ct,
-        [Description("Protagonist, Antagonist, Deuteragonist, Supporting, Minor, Mentor, LoveInterest or Foil.")]
-        string? role = null,
-        [Description("Main or Supporting. Main characters are the few the story is about and are worth tracking an arc for.")]
-        string? importance = null,
-        [Description("Age, exact or approximate.")] string? age = null,
-        [Description("The pronouns this character uses.")] string? pronouns = null,
-        [Description("What they do.")] string? occupation = null,
-        [Description("How they look.")] string? appearance = null,
-        [Description("Temperament, habits, how they treat people.")] string? personality = null,
-        [Description("History that shapes who they are now.")] string? backstory = null,
-        [Description("What they consciously pursue, weighed against what they actually need.")] string? motivation = null,
-        [Description("The war inside them and what in the world opposes them.")] string? conflict = null,
-        [Description("Speech patterns and register that make their dialogue theirs.")] string? voice = null,
-        [Description("Anything else worth recording.")] string? notes = null,
-        [Description("Tags for cross-referencing. Unknown tags are created.")] string[]? tags = null,
-        [Description("Other names this character is known by.")] string[]? aliases = null) =>
-        api.PostAsync($"/api/novels/{novelId}/characters", new
-        {
-            name,
-            role = role ?? "Supporting",
-            importance = importance ?? "Supporting",
-            age,
-            pronouns,
-            occupation,
-            appearance,
-            personality,
-            backstory,
-            motivation,
-            conflict,
-            voice,
-            notes,
-            tags,
-            aliases
-        }, ct);
-
-    [McpServerTool(Name = "update_character")]
-    [Description("Revise an existing character dossier. Only the fields you supply change.")]
-    public static Task<CallToolResult> UpdateCharacter(
-        NovelApiClient api,
-        [Description("The character's id.")] Guid characterId,
-        CancellationToken ct,
-        [Description("New name.")] string? name = null,
-        [Description("Protagonist, Antagonist, Deuteragonist, Supporting, Minor, Mentor, LoveInterest or Foil.")]
-        string? role = null,
-        [Description("Main or Supporting. Main characters are the few the story is about and are worth tracking an arc for.")]
-        string? importance = null,
-        [Description("Age, exact or approximate.")] string? age = null,
-        [Description("The pronouns this character uses.")] string? pronouns = null,
-        [Description("What they do.")] string? occupation = null,
-        [Description("How they look.")] string? appearance = null,
-        [Description("Temperament, habits, how they treat people.")] string? personality = null,
-        [Description("History that shapes who they are now.")] string? backstory = null,
-        [Description("What they consciously pursue, weighed against what they actually need.")] string? motivation = null,
-        [Description("The war inside them and what in the world opposes them.")] string? conflict = null,
-        [Description("Speech patterns and register.")] string? voice = null,
-        [Description("Anything else worth recording.")] string? notes = null,
-        [Description("Tags for cross-referencing. Replaces the existing tags.")] string[]? tags = null,
-        [Description("Other names this character is known by. Replaces the existing aliases.")] string[]? aliases = null) =>
-        api.PatchAsync($"/api/characters/{characterId}", new
-        {
-            name,
-            role,
-            importance,
-            age,
-            pronouns,
-            occupation,
-            appearance,
-            personality,
-            backstory,
-            motivation,
-            conflict,
-            voice,
-            notes,
-            tags,
-            aliases
-        }, ct);
-
-    [McpServerTool(Name = "get_character_beats")]
-    [Description("Every beat this character appears in, across the whole book, in manuscript order. "
-                 + "This is what the character actually does on the page, as opposed to what the "
-                 + "dossier claims about them — read it before revising a character.")]
-    public static Task<CallToolResult> GetCharacterBeats(
-        NovelApiClient api,
-        [Description("The character's id.")] Guid characterId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/characters/{characterId}/beats", ct);
-
-    [McpServerTool(Name = "get_character_arc")]
-    [Description("Read a main character's arc: the ordered stages of how they change, each "
-                 + "optionally pinned to the chapter where it lands.")]
-    public static Task<CallToolResult> GetCharacterArc(
-        NovelApiClient api,
-        [Description("The character's id.")] Guid characterId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/characters/{characterId}/arc", ct);
-
-    [McpServerTool(Name = "add_arc_stage")]
-    [Description("Add a stage to a character's arc. Arcs are kept for main characters — promote "
-                 + "the character with update_character first if they are still Supporting.")]
-    public static Task<CallToolResult> AddArcStage(
-        NovelApiClient api,
-        [Description("Id of the character whose arc to add to.")] Guid characterId,
-        [Description("A short handle for the change, three to five words.")] string title,
-        CancellationToken ct,
-        [Description("What this stage of the arc results in for the character — what shifts, and what it costs them.")] string? result = null,
-        [Description("Id of the chapter where this stage lands, if it is pinned to one.")] Guid? chapterId = null,
-        [Description("Position in the arc. Appended to the end when omitted.")] int? sortOrder = null) =>
-        api.PostAsync($"/api/characters/{characterId}/arc",
-            new { title, sortOrder, result, chapterId }, ct);
-
-    [McpServerTool(Name = "update_arc_stage")]
-    [Description("Revise a stage of a character's arc. Only the fields you supply change.")]
-    public static Task<CallToolResult> UpdateArcStage(
-        NovelApiClient api,
-        [Description("The arc stage's id.")] Guid arcStageId,
-        CancellationToken ct,
-        [Description("New title for the stage.")] string? title = null,
-        [Description("What this stage of the arc results in for the character.")] string? result = null,
-        [Description("Id of the chapter where this stage lands.")] Guid? chapterId = null,
-        [Description("Position in the arc.")] int? sortOrder = null) =>
-        api.PatchAsync($"/api/arc-stages/{arcStageId}",
-            new { title, sortOrder, result, chapterId }, ct);
-
-    [McpServerTool(Name = "delete_arc_stage")]
-    [Description("Remove a stage from a character's arc.")]
-    public static Task<CallToolResult> DeleteArcStage(
-        NovelApiClient api,
-        [Description("The arc stage's id.")] Guid arcStageId,
-        CancellationToken ct) =>
-        api.DeleteAsync($"/api/arc-stages/{arcStageId}", ct);
-
-    [McpServerTool(Name = "reorder_arc_stages")]
-    [Description("Renumber a character's arc to match the order given. Stages left out keep their "
-                 + "relative position after the ones listed.")]
-    public static Task<CallToolResult> ReorderArcStages(
-        NovelApiClient api,
-        [Description("Id of the character whose arc to reorder.")] Guid characterId,
-        [Description("Arc stage ids in the order wanted.")] string[] stageIds,
-        CancellationToken ct) =>
-        api.PostAsync($"/api/characters/{characterId}/arc/reorder", new { stageIds }, ct);
-
-    [McpServerTool(Name = "set_arc_stage_beats")]
-    [Description("Set which beats belong to an arc stage, replacing its current set. This groups the "
-                 + "chapter-level beats that establish or pay off this stage of the character's arc. A "
-                 + "beat moved into this stage leaves any other stage of the same character it was in. "
-                 + "Each beat must already include this character.")]
-    public static Task<CallToolResult> SetArcStageBeats(
-        NovelApiClient api,
-        [Description("The arc stage's id.")] Guid arcStageId,
-        [Description("Beat ids that belong to this stage, replacing whatever was there before.")] string[] beatIds,
-        CancellationToken ct) =>
-        api.PostAsync($"/api/arc-stages/{arcStageId}/beats", new { beatIds }, ct);
-
-    [McpServerTool(Name = "relate_characters")]
-    [Description("Record a relationship between two characters in the same novel. Creates both directions "
-                 + "at once — characterId's side and relatedCharacterId's side — so the pair always shows up "
-                 + "on both dossiers.")]
-    public static Task<CallToolResult> RelateCharacters(
-        NovelApiClient api,
-        [Description("Id of the character the relationship belongs to.")] Guid characterId,
-        [Description("Id of the character they are related to.")] Guid relatedCharacterId,
-        [Description("How characterId is related to relatedCharacterId, e.g. 'sister', 'rival', 'former mentor'.")] string relationshipType,
-        CancellationToken ct,
-        [Description("How relatedCharacterId is related back to characterId, if different — e.g. 'brother' for "
-                     + "'sister'. Defaults to relationshipType when the relation is symmetric, like 'rival'.")]
-        string? reciprocalRelationshipType = null,
-        [Description("What the relationship is like, and where it is headed.")] string? description = null) =>
-        api.PostAsync($"/api/characters/{characterId}/relationships",
-            new { relatedCharacterId, relationshipType, reciprocalRelationshipType, description }, ct);
-
-    [McpServerTool(Name = "link_character_identity")]
-    [Description("Record that this character is really another character — e.g. a character introduced "
-                 + "under one name who is later revealed to be a character already in the novel under "
-                 + "another name. Both characters keep their own dossier and beats; the canonical identity "
-                 + "is whichever character you link to.")]
-    public static Task<CallToolResult> LinkCharacterIdentity(
-        NovelApiClient api,
-        [Description("Id of the character being revealed as someone else.")] Guid characterId,
-        [Description("Id of the character this one really is.")] Guid sameCharacterAsId,
-        CancellationToken ct,
-        [Description("Id of the chapter where the reveal happens, if any.")] Guid? revealedInChapterId = null,
-        [Description("Context on the reveal, e.g. how and why the disguise held.")] string? note = null) =>
-        api.PutAsync($"/api/characters/{characterId}/identity",
-            new { sameCharacterAsId, revealedInChapterId, note }, ct);
-
-    [McpServerTool(Name = "unlink_character_identity")]
-    [Description("Remove a character's identity link, restoring it to its own separate identity.")]
-    public static Task<CallToolResult> UnlinkCharacterIdentity(
-        NovelApiClient api,
-        [Description("The character's id.")] Guid characterId,
-        CancellationToken ct) =>
-        api.DeleteAsync($"/api/characters/{characterId}/identity", ct);
-}

src/Novelly.Mcp/Tools/LocationTools.cs

@@ -1,53 +0,0 @@
-using System.ComponentModel;
-using ModelContextProtocol.Protocol;
-using ModelContextProtocol.Server;
-
-namespace Novelly.Mcp.Tools;
-
-[McpServerToolType]
-public static class LocationTools
-{
-    [McpServerTool(Name = "list_locations")]
-    [Description("List a novel's locations with how many chapters are set there. "
-                 + "Read this before inventing a new location so you reuse the writer's vocabulary.")]
-    public static Task<CallToolResult> ListLocations(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/novels/{novelId}/locations", ct);
-
-    [McpServerTool(Name = "get_location_references")]
-    [Description("Cross-reference a location: every chapter set there.")]
-    public static Task<CallToolResult> GetLocationReferences(
-        NovelApiClient api,
-        [Description("The location's id.")] Guid locationId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/locations/{locationId}/references", ct);
-
-    [McpServerTool(Name = "create_location")]
-    [Description("Create a location explicitly. Applying an unknown location by name to a chapter "
-                 + "also creates it, so this is only needed to set one up ahead of time.")]
-    public static Task<CallToolResult> CreateLocation(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        [Description("The location's name. Unique within the novel, matched case-insensitively.")] string name,
-        CancellationToken ct) =>
-        api.PostAsync($"/api/novels/{novelId}/locations", new { name }, ct);
-
-    [McpServerTool(Name = "update_location")]
-    [Description("Rename a location. Renaming updates it everywhere it is applied.")]
-    public static Task<CallToolResult> UpdateLocation(
-        NovelApiClient api,
-        [Description("The location's id.")] Guid locationId,
-        [Description("New name.")] string name,
-        CancellationToken ct) =>
-        api.PatchAsync($"/api/locations/{locationId}", new { name }, ct);
-
-    [McpServerTool(Name = "delete_location")]
-    [Description("Delete a location. Whatever carried it is left alone — only the label goes.")]
-    public static Task<CallToolResult> DeleteLocation(
-        NovelApiClient api,
-        [Description("The location's id.")] Guid locationId,
-        CancellationToken ct) =>
-        api.DeleteAsync($"/api/locations/{locationId}", ct);
-}

src/Novelly.Mcp/Tools/ManuscriptTools.cs

@@ -1,75 +0,0 @@
-using System.ComponentModel;
-using ModelContextProtocol.Protocol;
-using ModelContextProtocol.Server;
-
-namespace Novelly.Mcp.Tools;
-
-[McpServerToolType]
-public static class ManuscriptTools
-{
-    [McpServerTool(Name = "list_chapters")]
-    [Description("List a novel's chapters in manuscript order, with beat and word counts.")]
-    public static Task<CallToolResult> ListChapters(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/novels/{novelId}/chapters", ct);
-
-    [McpServerTool(Name = "get_chapter")]
-    [Description("Read one chapter in full: its outline (beats) and its drafted prose.")]
-    public static Task<CallToolResult> GetChapter(
-        NovelApiClient api,
-        [Description("The chapter's id.")] Guid chapterId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/chapters/{chapterId}", ct);
-
-    [McpServerTool(Name = "create_chapter")]
-    [Description("Add a chapter to a novel. It goes at the end of the manuscript unless you supply a number. "
-                 + "Use 'kind' for a foreword, prologue, afterword, or other unnumbered front/back matter.")]
-    public static Task<CallToolResult> CreateChapter(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        [Description("Chapter title.")] string title,
-        CancellationToken ct,
-        [Description("Manuscript position, 1-based, counting front and back matter.")] int? number = null,
-        [Description("FrontMatter, Body, or BackMatter. Defaults to Body.")] string? kind = null,
-        [Description("The chapter's outline summary paragraph.")] string? summary = null,
-        [Description("Where and when the chapter takes place. Unknown locations are created.")] string[]? locations = null,
-        [Description("Planned, Outlined, Drafted, Revised or Final.")] string? status = null,
-        [Description("Target length in words.")] int? targetWordCount = null,
-        [Description("The chapter's drafted text, in markdown, if you are writing it now.")] string? prose = null,
-        [Description("Tags for cross-referencing. Unknown tags are created.")] string[]? tags = null) =>
-        api.PostAsync($"/api/novels/{novelId}/chapters", new
-        {
-            title,
-            number,
-            kind = kind ?? "Body",
-            summary,
-            locations,
-            status = status ?? "Planned",
-            targetWordCount,
-            prose,
-            tags
-        }, ct);
-
-    [McpServerTool(Name = "update_chapter")]
-    [Description("Revise a chapter's title, number, kind, summary, locations, notes, status "
-                 + "or drafted prose. Use 'prose' to write or replace the chapter's draft text in "
-                 + "markdown; the word count is recomputed automatically.")]
-    public static Task<CallToolResult> UpdateChapter(
-        NovelApiClient api,
-        [Description("The chapter's id.")] Guid chapterId,
-        CancellationToken ct,
-        [Description("New title.")] string? title = null,
-        [Description("Manuscript position, 1-based, counting front and back matter.")] int? number = null,
-        [Description("FrontMatter, Body, or BackMatter.")] string? kind = null,
-        [Description("The chapter's outline summary paragraph.")] string? summary = null,
-        [Description("Where and when the chapter takes place. Replaces the existing locations. Unknown locations are created.")] string[]? locations = null,
-        [Description("Anything else worth recording.")] string? notes = null,
-        [Description("Planned, Outlined, Drafted, Revised or Final.")] string? status = null,
-        [Description("Target length in words.")] int? targetWordCount = null,
-        [Description("The chapter's drafted text, in markdown.")] string? prose = null,
-        [Description("Tags for cross-referencing. Replaces the existing tags.")] string[]? tags = null) =>
-        api.PatchAsync($"/api/chapters/{chapterId}",
-            new { title, number, kind, summary, locations, notes, status, targetWordCount, prose, tags }, ct);
-}

src/Novelly.Mcp/Tools/NovelTools.cs

@@ -1,54 +0,0 @@
-using System.ComponentModel;
-using ModelContextProtocol.Protocol;
-using ModelContextProtocol.Server;
-
-namespace Novelly.Mcp.Tools;
-
-[McpServerToolType]
-public static class NovelTools
-{
-    [McpServerTool(Name = "list_novels")]
-    [Description("List every novel, with counts of characters, chapters and drafted words. "
-                 + "Start here to find the novel id everything else needs.")]
-    public static Task<CallToolResult> ListNovels(NovelApiClient api, CancellationToken ct) =>
-        api.GetAsync("/api/novels", ct);
-
-    [McpServerTool(Name = "get_novel_brief")]
-    [Description("Read a novel's title, author, genre, logline, synopsis, notes and word-count target.")]
-    public static Task<CallToolResult> GetNovel(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/novels/{novelId}", ct);
-
-    [McpServerTool(Name = "create_novel")]
-    [Description("Create a new novel.")]
-    public static Task<CallToolResult> CreateNovel(
-        NovelApiClient api,
-        [Description("Working title.")] string title,
-        CancellationToken ct,
-        [Description("Author name.")] string? author = null,
-        [Description("Genre or category.")] string? genre = null,
-        [Description("One-sentence pitch.")] string? logline = null,
-        [Description("Paragraph-length summary of the whole book.")] string? synopsis = null,
-        [Description("Free-form notes on theme, tone, comparable titles.")] string? notes = null,
-        [Description("Target manuscript length in words.")] int? targetWordCount = null) =>
-        api.PostAsync("/api/novels", new { title, author, genre, logline, synopsis, notes, targetWordCount }, ct);
-
-    [McpServerTool(Name = "update_novel_brief")]
-    [Description("Revise a novel's top-level fields. Only the fields you supply change; "
-                 + "pass an empty string to clear one.")]
-    public static Task<CallToolResult> UpdateNovel(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        CancellationToken ct,
-        [Description("New title.")] string? title = null,
-        [Description("Author name.")] string? author = null,
-        [Description("Genre or category.")] string? genre = null,
-        [Description("One-sentence pitch.")] string? logline = null,
-        [Description("Paragraph-length summary of the whole book.")] string? synopsis = null,
-        [Description("Free-form notes on theme, tone, comparable titles.")] string? notes = null,
-        [Description("Target manuscript length in words.")] int? targetWordCount = null) =>
-        api.PatchAsync($"/api/novels/{novelId}",
-            new { title, author, genre, logline, synopsis, notes, targetWordCount }, ct);
-}

src/Novelly.Mcp/Tools/QuestionTools.cs

@@ -1,92 +0,0 @@
-using System.ComponentModel;
-using ModelContextProtocol.Protocol;
-using ModelContextProtocol.Server;
-
-namespace Novelly.Mcp.Tools;
-
-[McpServerToolType]
-public static class QuestionTools
-{
-    [McpServerTool(Name = "list_open_questions")]
-    [Description("The decisions the writer has not made yet, newest first. Read this before "
-                 + "proposing changes — an open question marks somewhere the writer is still "
-                 + "thinking, not a gap to fill in for them.")]
-    public static Task<CallToolResult> ListOpenQuestions(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        CancellationToken ct,
-        [Description("Narrow to questions about one chapter outline.")] Guid? chapterId = null,
-        [Description("Narrow to questions about one character.")] Guid? characterId = null,
-        [Description("Include questions already settled. Defaults to false.")] bool includeResolved = false)
-    {
-        var query = new List<string> { $"includeResolved={includeResolved.ToString().ToLowerInvariant()}" };
-
-        if (chapterId is { } chapter)
-        {
-            query.Add($"chapterId={chapter}");
-        }
-
-        if (characterId is { } character)
-        {
-            query.Add($"characterId={character}");
-        }
-
-        return api.GetAsync($"/api/novels/{novelId}/questions?{string.Join('&', query)}", ct);
-    }
-
-    [McpServerTool(Name = "raise_open_question")]
-    [Description("Record a question the writer has not settled, attached to the chapter outline "
-                 + "and/or the character it is about. Prefer raising a question over guessing.")]
-    public static Task<CallToolResult> RaiseOpenQuestion(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        [Description("The question, in one line.")] string question,
-        CancellationToken ct,
-        [Description("The thinking around it — options considered, and what each costs.")] string? detail = null,
-        [Description("Id of the chapter outline this is about, if any.")] Guid? chapterId = null,
-        [Description("Id of the character this is about, if any.")] Guid? characterId = null) =>
-        api.PostAsync($"/api/novels/{novelId}/questions",
-            new { question, detail, chapterId, characterId }, ct);
-
-    [McpServerTool(Name = "update_open_question")]
-    [Description("Revise a question or change what it is attached to. Only the fields you supply change.")]
-    public static Task<CallToolResult> UpdateOpenQuestion(
-        NovelApiClient api,
-        [Description("The question's id.")] Guid questionId,
-        CancellationToken ct,
-        [Description("New wording for the question.")] string? question = null,
-        [Description("New detail. Pass an empty string to clear it.")] string? detail = null,
-        [Description("Attach to this chapter outline.")] Guid? chapterId = null,
-        [Description("Attach to this character.")] Guid? characterId = null,
-        [Description("Detach from its chapter.")] bool clearChapter = false,
-        [Description("Detach from its character.")] bool clearCharacter = false) =>
-        api.PatchAsync($"/api/questions/{questionId}",
-            new { question, detail, chapterId, characterId, clearChapter, clearCharacter }, ct);
-
-    [McpServerTool(Name = "resolve_open_question")]
-    [Description("Settle a question with what the writer decided. Set appendToNotes to also write "
-                 + "the resolution into the notes of the chapter and character it hangs off.")]
-    public static Task<CallToolResult> ResolveOpenQuestion(
-        NovelApiClient api,
-        [Description("The question's id.")] Guid questionId,
-        [Description("What was decided.")] string resolution,
-        CancellationToken ct,
-        [Description("Also append the resolution to the associated notes.")] bool appendToNotes = false) =>
-        api.PostAsync($"/api/questions/{questionId}/resolve", new { resolution, appendToNotes }, ct);
-
-    [McpServerTool(Name = "reopen_question")]
-    [Description("Put a resolved question back on the list. Anything already appended to notes stays.")]
-    public static Task<CallToolResult> ReopenQuestion(
-        NovelApiClient api,
-        [Description("The question's id.")] Guid questionId,
-        CancellationToken ct) =>
-        api.PostAsync($"/api/questions/{questionId}/reopen", new { }, ct);
-
-    [McpServerTool(Name = "delete_open_question")]
-    [Description("Delete a question outright. Resolving is usually better — it keeps the decision.")]
-    public static Task<CallToolResult> DeleteOpenQuestion(
-        NovelApiClient api,
-        [Description("The question's id.")] Guid questionId,
-        CancellationToken ct) =>
-        api.DeleteAsync($"/api/questions/{questionId}", ct);
-}

src/Novelly.Mcp/Tools/TagTools.cs

@@ -1,56 +0,0 @@
-using System.ComponentModel;
-using ModelContextProtocol.Protocol;
-using ModelContextProtocol.Server;
-
-namespace Novelly.Mcp.Tools;
-
-[McpServerToolType]
-public static class TagTools
-{
-    [McpServerTool(Name = "list_tags")]
-    [Description("List a novel's tags with how many characters, chapters and beats carry each. "
-                 + "Read this before inventing a new tag so you reuse the writer's vocabulary.")]
-    public static Task<CallToolResult> ListTags(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/novels/{novelId}/tags", ct);
-
-    [McpServerTool(Name = "get_tag_references")]
-    [Description("Cross-reference a tag: every character, chapter and beat carrying it. Use this "
-                 + "to trace a motif, a thread, or a piece of setup through the book.")]
-    public static Task<CallToolResult> GetTagReferences(
-        NovelApiClient api,
-        [Description("The tag's id.")] Guid tagId,
-        CancellationToken ct) =>
-        api.GetAsync($"/api/tags/{tagId}/references", ct);
-
-    [McpServerTool(Name = "create_tag")]
-    [Description("Create a tag explicitly. Applying an unknown tag by name to a character, "
-                 + "chapter or beat also creates it, so this is only needed to set a colour up front.")]
-    public static Task<CallToolResult> CreateTag(
-        NovelApiClient api,
-        [Description("The novel's id.")] Guid novelId,
-        [Description("The tag's name. Unique within the novel, matched case-insensitively.")] string name,
-        CancellationToken ct,
-        [Description("Optional hex colour for the UI, e.g. \"#9a4a2f\".")] string? color = null) =>
-        api.PostAsync($"/api/novels/{novelId}/tags", new { name, color }, ct);
-
-    [McpServerTool(Name = "update_tag")]
-    [Description("Rename or recolour a tag. Renaming updates it everywhere it is applied.")]
-    public static Task<CallToolResult> UpdateTag(
-        NovelApiClient api,
-        [Description("The tag's id.")] Guid tagId,
-        CancellationToken ct,
-        [Description("New name.")] string? name = null,
-        [Description("Hex colour, e.g. \"#9a4a2f\".")] string? color = null) =>
-        api.PatchAsync($"/api/tags/{tagId}", new { name, color }, ct);
-
-    [McpServerTool(Name = "delete_tag")]
-    [Description("Delete a tag. Whatever carried it is left alone — only the label goes.")]
-    public static Task<CallToolResult> DeleteTag(
-        NovelApiClient api,
-        [Description("The tag's id.")] Guid tagId,
-        CancellationToken ct) =>
-        api.DeleteAsync($"/api/tags/{tagId}", ct);
-}

src/Novelly.ServiceDefaults/Extensions.cs

@@ -21,17 +21,12 @@ public static class Extensions
     public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder
     {
         builder.ConfigureOpenTelemetry();
-
         builder.AddDefaultHealthChecks();
-
         builder.Services.AddServiceDiscovery();
 
         builder.Services.ConfigureHttpClientDefaults(http =>
         {
-            // Turn on resilience by default
             http.AddStandardResilienceHandler();
-
-            // Turn on service discovery by default
             http.AddServiceDiscovery();
         });
 

src/Novelly.Web/src/App.tsx

@@ -8,6 +8,7 @@ import TagsPage from './pages/TagsPage'
 import LocationsPage from './pages/LocationsPage'
 import ChaptersPage from './pages/ChaptersPage'
 import ChapterPage from './pages/ChapterPage'
+import TrashPage from './pages/TrashPage'
 import SettingsPage from './pages/SettingsPage'
 import LoginPage from './pages/LoginPage'
 import { AuthProvider, useAuth } from './auth/AuthContext'
@@ -43,6 +44,7 @@ export default function App() {
                 <Route path="chapters/:chapterId" element={<ChapterPage />} />
                 <Route path="tags" element={<TagsPage />} />
                 <Route path="locations" element={<LocationsPage />} />
+                <Route path="trash" element={<TrashPage />} />
                 <Route path="settings" element={<SettingsPage />} />
               </Route>
               <Route path="*" element={<NovelsPage />} />

src/Novelly.Web/src/api/hooks.ts

@@ -18,6 +18,7 @@ import type {
   ImportJobStatus,
   ImportUpload,
   OpenQuestion,
+  Location,
   LocationReferences,
   LocationSummary,
   Novel,
@@ -26,6 +27,8 @@ import type {
   NovelSummary,
   TagReferences,
   TagSummary,
+  TrashedItem,
+  TrashEntityKind,
   UiSettings,
   User,
 } from './types'
@@ -52,6 +55,7 @@ export const keys = {
   importBrowse: (path: string) => ['imports', 'browse', path] as const,
   novelActivity: (novelId: string) => ['novels', novelId, 'activity'] as const,
   myActivity: ['activity'] as const,
+  trash: (novelId: string) => ['novels', novelId, 'trash'] as const,
 }
 
 export const useUiSettings = () =>
@@ -202,6 +206,7 @@ export function useDeleteCharacter(novelId: string) {
       qc.invalidateQueries({ queryKey: keys.characters(novelId) })
       qc.invalidateQueries({ queryKey: keys.novelActivity(novelId) })
       qc.invalidateQueries({ queryKey: keys.myActivity })
+      qc.invalidateQueries({ queryKey: keys.trash(novelId) })
     },
   })
 }
@@ -433,6 +438,14 @@ export const useLocationReferences = (locationId: string | undefined) =>
     enabled: Boolean(locationId),
   })
 
+export function useCreateLocation(novelId: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: (name: string) => api.post<Location>(`/api/novels/${novelId}/locations`, { name }),
+    onSuccess: () => qc.invalidateQueries({ queryKey: keys.locations(novelId) }),
+  })
+}
+
 export function useUpdateLocation(novelId: string) {
   const qc = useQueryClient()
   return useMutation({
@@ -579,6 +592,7 @@ export function useDeleteChapter(novelId: string) {
       qc.invalidateQueries({ queryKey: keys.chapters(novelId) })
       qc.invalidateQueries({ queryKey: keys.novelActivity(novelId) })
       qc.invalidateQueries({ queryKey: keys.myActivity })
+      qc.invalidateQueries({ queryKey: keys.trash(novelId) })
     },
   })
 }
@@ -625,6 +639,46 @@ export const useMyActivity = () =>
     queryFn: () => api.get<ActivityCalendar>('/api/activity'),
   })
 
+export const useTrash = (novelId: string) =>
+  useQuery({
+    queryKey: keys.trash(novelId),
+    queryFn: () => api.get<TrashedItem[]>(`/api/novels/${novelId}/trash`),
+  })
+
+function invalidateAfterTrashChange(qc: ReturnType<typeof useQueryClient>, novelId: string) {
+  qc.invalidateQueries({ queryKey: keys.trash(novelId) })
+  qc.invalidateQueries({ queryKey: keys.characters(novelId) })
+  qc.invalidateQueries({ queryKey: keys.chapters(novelId) })
+  qc.invalidateQueries({ queryKey: keys.locations(novelId) })
+  qc.invalidateQueries({ queryKey: keys.novelActivity(novelId) })
+  qc.invalidateQueries({ queryKey: keys.myActivity })
+}
+
+export function useRestoreTrashed(novelId: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({ kind, id }: { kind: TrashEntityKind; id: string }) =>
+      api.post(`/api/trash/${kind}/${id}/restore`, {}),
+    onSuccess: () => invalidateAfterTrashChange(qc, novelId),
+  })
+}
+
+export function usePurgeTrashed(novelId: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: ({ kind, id }: { kind: TrashEntityKind; id: string }) => api.delete(`/api/trash/${kind}/${id}`),
+    onSuccess: () => invalidateAfterTrashChange(qc, novelId),
+  })
+}
+
+export function useEmptyTrash(novelId: string) {
+  const qc = useQueryClient()
+  return useMutation({
+    mutationFn: () => api.delete(`/api/novels/${novelId}/trash`),
+    onSuccess: () => invalidateAfterTrashChange(qc, novelId),
+  })
+}
+
 export function useInspectImport() {
   return useMutation({
     mutationFn: (sourceRoot: string) => api.post<ImportInspection>('/api/imports/inspect', { sourceRoot }),

src/Novelly.Web/src/api/types.ts

@@ -350,6 +350,19 @@ export interface ImportUpload {
   markdownFileCount: number
 }
 
+export type TrashEntityKind = 'Character' | 'Chapter' | 'Location'
+
+export const trashEntityKinds: TrashEntityKind[] = ['Character', 'Chapter', 'Location']
+
+export interface TrashedItem {
+  id: string
+  kind: TrashEntityKind
+  label: string
+  detail: string | null
+  deletedAt: string
+  purgeAfter: string
+}
+
 export interface ActivityDay {
   date: string
   words: number

src/Novelly.Web/src/components/CharacterArc.tsx

@@ -1,4 +1,4 @@
-import { useState } from 'react'
+import { useRef, useState } from 'react'
 import { Link } from 'react-router-dom'
 import {
   useCharacterBeats,
@@ -12,6 +12,8 @@ import {
 import { chapterLabel } from '../api/chapterLabel'
 import type { ArcStage, Character, ChapterKind } from '../api/types'
 import { AutoField, ErrorNote } from './ui'
+import { ConfirmModal } from './ConfirmModal'
+import { useHotkey } from '../keyboard/HotkeysContext'
 
 export function CharacterArc({
   novelId,
@@ -32,6 +34,8 @@ export function CharacterArc({
   const reorder = useReorderArcStages(novelId)
 
   const [title, setTitle] = useState('')
+  const [pendingStageId, setPendingStageId] = useState<string | null>(null)
+  const titleInputRef = useRef<HTMLInputElement>(null)
 
   const stages = character.arcStages
   const unassignedBeats = (beats ?? []).filter((b) => b.arcStageId === null)
@@ -41,10 +45,15 @@ export function CharacterArc({
     if (!title.trim()) return
     create.mutate(
       { characterId: character.id, title: title.trim() },
-      { onSuccess: () => setTitle('') },
+      { onSuccess: (stage) => { setTitle(''); setPendingStageId(stage.id) } },
     )
   }
 
+  useHotkey('a', 'Add arc stage', () => titleInputRef.current?.focus(), {
+    group: 'Character',
+    enabled: canCreate,
+  })
+
   const move = (index: number, delta: number) => {
     const next = [...stages]
     const [moved] = next.splice(index, 1)
@@ -80,6 +89,8 @@ export function CharacterArc({
               onMove={(delta) => move(index, delta)}
               canWrite={canWrite}
               canDelete={canDelete}
+              autoFocusTitle={pendingStageId === stage.id}
+              onTitleAutoFocused={() => setPendingStageId(null)}
             />
           ))}
         </ol>
@@ -95,10 +106,14 @@ export function CharacterArc({
       {canCreate && (
         <form onSubmit={submit} className="mt-3 flex gap-2">
           <input
+            ref={titleInputRef}
             className="input flex-1"
             placeholder="Add a section — a short title, e.g. “spoiled noble”"
             value={title}
             onChange={(e) => setTitle(e.target.value)}
+            onKeyDown={(e) => {
+              if (e.key === 'Escape') setTitle('')
+            }}
           />
           <button className="btn btn-primary shrink-0" disabled={!title.trim() || create.isPending}>
             Add
@@ -125,6 +140,8 @@ function ArcStageRow({
   onMove,
   canWrite,
   canDelete,
+  autoFocusTitle,
+  onTitleAutoFocused,
 }: {
   novelId: string
   stage: ArcStage
@@ -135,10 +152,13 @@ function ArcStageRow({
   onMove: (delta: number) => void
   canWrite: boolean
   canDelete: boolean
+  autoFocusTitle: boolean
+  onTitleAutoFocused: () => void
 }) {
   const update = useUpdateArcStage(novelId)
   const remove = useDeleteArcStage(novelId)
   const setBeats = useSetArcStageBeats(novelId, stage.characterId)
+  const [confirmingDelete, setConfirmingDelete] = useState(false)
 
   const addBeat = (beatId: string) => {
     if (!beatId) return
@@ -162,6 +182,9 @@ function ArcStageRow({
             value={stage.title}
             onCommit={(title) => title.trim() && update.mutate({ id: stage.id, title })}
             readOnly={!canWrite}
+            autoFocus={autoFocusTitle}
+            selectOnFocus
+            onAutoFocused={onTitleAutoFocused}
           />
           <AutoField
             value={stage.result}
@@ -266,9 +289,7 @@ function ArcStageRow({
               <button
                 className="btn px-2 py-0.5 text-xs"
                 style={{ color: 'var(--accent)' }}
-                onClick={() => {
-                  if (confirm(`Delete “${stage.title}” from the arc?`)) remove.mutate(stage.id)
-                }}
+                onClick={() => setConfirmingDelete(true)}
                 aria-label="Delete stage"
               >
                 ✕
@@ -277,6 +298,15 @@ function ArcStageRow({
           </div>
         )}
       </div>
+
+      {confirmingDelete && (
+        <ConfirmModal
+          title="Delete stage"
+          message={`Delete "${stage.title}" from the arc?`}
+          onConfirm={() => remove.mutate(stage.id)}
+          onClose={() => setConfirmingDelete(false)}
+        />
+      )}
     </li>
   )
 }

src/Novelly.Web/src/components/OpenQuestions.tsx

@@ -1,4 +1,4 @@
-import { useState } from 'react'
+import { useState, type KeyboardEvent } from 'react'
 import {
   useDeleteQuestion,
   useOpenQuestions,
@@ -8,6 +8,10 @@ import {
 } from '../api/hooks'
 import type { OpenQuestion } from '../api/types'
 import { ErrorNote, Spinner } from './ui'
+import { ConfirmModal } from './ConfirmModal'
+import { useHotkey } from '../keyboard/HotkeysContext'
+
+const isSubmitCombo = (e: KeyboardEvent) => (e.metaKey || e.ctrlKey) && e.key === 'Enter'
 
 export function OpenQuestions({
   novelId,
@@ -34,8 +38,7 @@ export function OpenQuestions({
   const [question, setQuestion] = useState('')
   const [detail, setDetail] = useState('')
 
-  const submit = (e: React.FormEvent) => {
-    e.preventDefault()
+  const raiseQuestion = () => {
     if (!question.trim()) return
     raise.mutate(
       { question: question.trim(), detail: detail.trim() || undefined, ...scope },
@@ -49,6 +52,14 @@ export function OpenQuestions({
     )
   }
 
+  useHotkey('q', 'Raise a question', () => setAsking(true), { group: 'Questions', enabled: canCreate })
+
+  const cancelAsking = () => {
+    setAsking(false)
+    setQuestion('')
+    setDetail('')
+  }
+
   const openCount = questions?.filter((q) => !q.isResolved).length ?? 0
 
   return (
@@ -68,7 +79,7 @@ export function OpenQuestions({
             Show resolved
           </label>
           {canCreate && (
-            <button className="btn" onClick={() => setAsking((open) => !open)}>
+            <button className="btn" onClick={() => (asking ? cancelAsking() : setAsking(true))}>
               {asking ? 'Cancel' : 'Ask'}
             </button>
           )}
@@ -76,7 +87,23 @@ export function OpenQuestions({
       </div>
 
       {asking && (
-        <form onSubmit={submit} className="mb-4 grid gap-2">
+        <form
+          onSubmit={(e) => {
+            e.preventDefault()
+            raiseQuestion()
+          }}
+          className="mb-4 grid gap-2"
+          onKeyDown={(e) => {
+            if (e.key === 'Escape') {
+              cancelAsking()
+              return
+            }
+            if (isSubmitCombo(e)) {
+              e.preventDefault()
+              raiseQuestion()
+            }
+          }}
+        >
           <input
             className="input"
             autoFocus
@@ -147,9 +174,14 @@ function QuestionRow({
   const [resolving, setResolving] = useState(false)
   const [resolution, setResolution] = useState('')
   const [appendToNotes, setAppendToNotes] = useState(true)
+  const [confirmingDelete, setConfirmingDelete] = useState(false)
 
-  const submit = (e: React.FormEvent) => {
-    e.preventDefault()
+  const cancelResolving = () => {
+    setResolving(false)
+    setResolution('')
+  }
+
+  const submitResolution = () => {
     if (!resolution.trim()) return
     resolve.mutate(
       { id: question.id, resolution: resolution.trim(), appendToNotes },
@@ -204,7 +236,7 @@ function QuestionRow({
             ) : (
               <button
                 className="btn px-2 py-1 text-xs"
-                onClick={() => setResolving((open) => !open)}
+                onClick={() => (resolving ? cancelResolving() : setResolving(true))}
               >
                 {resolving ? 'Cancel' : 'Resolve'}
               </button>
@@ -214,11 +246,7 @@ function QuestionRow({
             <button
               className="btn px-2 py-1 text-xs"
               style={{ color: 'var(--accent)' }}
-              onClick={() => {
-                if (confirm('Delete this question? Resolving keeps the decision; deleting does not.')) {
-                  remove.mutate(question.id)
-                }
-              }}
+              onClick={() => setConfirmingDelete(true)}
             >
               Delete
             </button>
@@ -227,7 +255,23 @@ function QuestionRow({
       </div>
 
       {resolving && (
-        <form onSubmit={submit} className="mt-2 grid gap-2">
+        <form
+          onSubmit={(e) => {
+            e.preventDefault()
+            submitResolution()
+          }}
+          className="mt-2 grid gap-2"
+          onKeyDown={(e) => {
+            if (e.key === 'Escape') {
+              cancelResolving()
+              return
+            }
+            if (isSubmitCombo(e)) {
+              e.preventDefault()
+              submitResolution()
+            }
+          }}
+        >
           <textarea
             className="input"
             rows={2}
@@ -252,6 +296,15 @@ function QuestionRow({
           {resolve.error && <ErrorNote error={resolve.error} />}
         </form>
       )}
+
+      {confirmingDelete && (
+        <ConfirmModal
+          title="Delete question"
+          message="Delete this question? Resolving keeps the decision; deleting does not."
+          onConfirm={() => remove.mutate(question.id)}
+          onClose={() => setConfirmingDelete(false)}
+        />
+      )}
     </li>
   )
 }

src/Novelly.Web/src/components/icons.tsx

@@ -75,6 +75,17 @@ export function IconAgent(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+export function IconTrash(props: SVGProps<SVGSVGElement>) {
+  return (
+    <Icon {...props}>
+      <path d="M4.5 7h15" />
+      <path d="M9.5 7V4.8a1 1 0 0 1 1-1h3a1 1 0 0 1 1 1V7" />
+      <path d="M6.5 7l1 12.2a1 1 0 0 0 1 .8h7a1 1 0 0 0 1-.8L17.5 7" />
+      <path d="M10 11v6M14 11v6" />
+    </Icon>
+  )
+}
+
 export function IconSettings(props: SVGProps<SVGSVGElement>) {
   return (
     <Icon {...props}>

src/Novelly.Web/src/components/ui.tsx

@@ -1,6 +1,7 @@
-import { useEffect, useId, useRef, useState, type MouseEvent, type ReactNode } from 'react'
+import { useEffect, useId, useRef, useState, type KeyboardEvent as ReactKeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import { draftStatusColor } from '../api/stage'
 import type { DraftStatus } from '../api/types'
+import { focusNextTabbable } from '../keyboard/focus'
 
 export function Spinner({ label = 'Loading' }: { label?: string }) {
   return (
@@ -59,6 +60,9 @@ export function AutoField({
   suggestions,
   onContextMenu,
   readOnly,
+  autoFocus,
+  selectOnFocus,
+  onAutoFocused,
 }: {
   label?: string
   value: string | null | undefined
@@ -70,10 +74,17 @@ export function AutoField({
   suggestions?: readonly string[]
   onContextMenu?: (e: MouseEvent<HTMLTextAreaElement>) => void
   readOnly?: boolean
+  autoFocus?: boolean
+  selectOnFocus?: boolean
+  onAutoFocused?: () => void
 }) {
   const [draft, setDraft] = useState(value ?? '')
   const committed = useRef(value ?? '')
   const suggestionsId = useId()
+  const inputRef = useRef<HTMLInputElement>(null)
+  const textareaRef = useRef<HTMLTextAreaElement>(null)
+  const onAutoFocusedRef = useRef(onAutoFocused)
+  onAutoFocusedRef.current = onAutoFocused
 
   useEffect(() => {
     const incoming = value ?? ''
@@ -83,6 +94,14 @@ export function AutoField({
     }
   }, [value])
 
+  useEffect(() => {
+    if (!autoFocus) return
+    const field = multiline ? textareaRef.current : inputRef.current
+    field?.focus()
+    if (selectOnFocus) field?.select()
+    onAutoFocusedRef.current?.()
+  }, [autoFocus, multiline, selectOnFocus])
+
   const commit = () => {
     if (draft !== committed.current) {
       committed.current = draft
@@ -90,6 +109,31 @@ export function AutoField({
     }
   }
 
+  const revert = () => setDraft(committed.current)
+
+  const onSingleLineKeyDown = (e: ReactKeyboardEvent<HTMLInputElement>) => {
+    if (e.key === 'Escape') {
+      revert()
+      return
+    }
+    if (e.key !== 'Enter') return
+    e.preventDefault()
+    commit()
+    if (e.metaKey || e.ctrlKey) return
+    focusNextTabbable(e.currentTarget, e.shiftKey ? -1 : 1)
+  }
+
+  const onMultilineKeyDown = (e: ReactKeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === 'Escape') {
+      revert()
+      return
+    }
+    if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+      e.preventDefault()
+      commit()
+    }
+  }
+
   const className = `input ${serif ? 'prose-serif' : ''}`
 
   return (
@@ -97,25 +141,28 @@ export function AutoField({
       {label && <span className="label">{label}</span>}
       {multiline ? (
         <textarea
+          ref={textareaRef}
           className={className}
           rows={rows}
           value={draft}
           placeholder={placeholder}
           onChange={(e) => setDraft(e.target.value)}
           onBlur={commit}
+          onKeyDown={onMultilineKeyDown}
           onContextMenu={onContextMenu}
           readOnly={readOnly}
         />
       ) : (
         <>
           <input
+            ref={inputRef}
             className={className}
             value={draft}
             placeholder={placeholder}
             list={suggestions?.length ? suggestionsId : undefined}
             onChange={(e) => setDraft(e.target.value)}
             onBlur={commit}
-            onKeyDown={(e) => e.key === 'Enter' && e.currentTarget.blur()}
+            onKeyDown={onSingleLineKeyDown}
             readOnly={readOnly}
           />
           {suggestions?.length ? (
@@ -137,17 +184,25 @@ export function Select<T extends string>({
   value,
   options,
   onChange,
+  autoFocus,
 }: {
   id?: string
   label?: string
   value: T
   options: readonly T[]
   onChange: (next: T) => void
+  autoFocus?: boolean
 }) {
+  const selectRef = useRef<HTMLSelectElement>(null)
+
+  useEffect(() => {
+    if (autoFocus) selectRef.current?.focus()
+  }, [autoFocus])
+
   return (
     <label className="block">
       {label && <span className="label">{label}</span>}
-      <select id={id} className="input" value={value} onChange={(e) => onChange(e.target.value as T)}>
+      <select ref={selectRef} id={id} className="input" value={value} onChange={(e) => onChange(e.target.value as T)}>
         {options.map((option) => (
           <option key={option} value={option}>
             {option}

src/Novelly.Web/src/keyboard/HelpOverlay.tsx

@@ -1,6 +1,13 @@
 import { useHelpOverlay } from './HelpOverlayContext'
 import { useHotkeysList } from './HotkeysContext'
 
+const CONVENTIONS = [
+  'Escape cancels or closes. It reverts the field you’re in; fields you already tabbed past stay saved.',
+  'Enter commits a single-line field and moves to the next one, like Tab.',
+  'mod+Enter commits a multiline field, or finishes the record you’re editing.',
+  'Destructive actions always confirm through a dialog you can dismiss with Escape — never a browser popup.',
+]
+
 const formatToken = (token: string) => {
   if (token === 'mod') return '⌘/Ctrl'
   if (token.length === 1) return token.toUpperCase()
@@ -80,13 +87,25 @@ export function HelpOverlay() {
               <ul className="grid gap-2">
                 {groupShortcuts.map((shortcut) => (
                   <li key={shortcut.id} className="flex items-center justify-between gap-3 text-sm">
-                    <span>{shortcut.description}</span>
+                    <span>
+                      {shortcut.description}
+                      {shortcut.allowInInputs && <span className="muted"> · works while typing</span>}
+                    </span>
                     <KeySequence keys={shortcut.keys} />
                   </li>
                 ))}
               </ul>
             </div>
           ))}
+
+          <div>
+            <h3 className="label mb-2">Conventions</h3>
+            <ul className="grid gap-2 text-sm muted">
+              {CONVENTIONS.map((convention) => (
+                <li key={convention}>{convention}</li>
+              ))}
+            </ul>
+          </div>
         </div>
       </aside>
     </div>

src/Novelly.Web/src/keyboard/focus.ts

@@ -0,0 +1,21 @@
+const TABBABLE_SELECTOR = 'a[href], button:not([disabled]), textarea, input, select, [tabindex]:not([tabindex="-1"])'
+
+export function focusNextTabbable(from: HTMLElement, direction: 1 | -1, within?: HTMLElement | null) {
+  const scope = within ?? document.body
+  const candidates = [...scope.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR)]
+  const index = candidates.indexOf(from)
+  if (index === -1) return
+
+  const target = candidates[index + direction]
+  if (!target) return
+
+  target.focus()
+  if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) {
+    target.select()
+  }
+}
+
+export function isWithin(container: HTMLElement | null, node: Node | null): boolean {
+  if (!container || !node) return false
+  return container.contains(node)
+}

src/Novelly.Web/src/pages/ChapterPage.tsx

@@ -1,5 +1,5 @@
-import { useState, type MouseEvent } from 'react'
-import { Link, useNavigate, useParams } from 'react-router-dom'
+import { useEffect, useRef, useState, type MouseEvent } from 'react'
+import { Link, useLocation, useNavigate, useParams } from 'react-router-dom'
 import {
   useAssignCharacterToBeats,
   useChapter,
@@ -29,12 +29,14 @@ import { useCharacterContextMenu } from '../components/CharacterContextMenu'
 import { MarkdownEditor } from '../components/MarkdownEditor'
 import { OpenQuestions } from '../components/OpenQuestions'
 import { useHotkey } from '../keyboard/HotkeysContext'
+import { isWithin } from '../keyboard/focus'
 
 type ChapterTab = 'outline' | 'prose'
 
 export default function ChapterPage() {
   const { novelId = '', chapterId = '' } = useParams()
   const navigate = useNavigate()
+  const location = useLocation()
   const { data: chapter, isPending, error } = useChapter(chapterId)
   const { data: novel } = useNovel(novelId)
   const { data: characters } = useCharacters(novelId)
@@ -47,13 +49,32 @@ export default function ChapterPage() {
   const createBeat = useCreateBeat(chapterId, novelId)
   const [tab, setTab] = useState<ChapterTab>('outline')
   const [confirmingDelete, setConfirmingDelete] = useState(false)
+  const [editingBeatId, setEditingBeatId] = useState<string | null>(null)
+  const [focusBeatId, setFocusBeatId] = useState<string | null>(null)
   const { handleContextMenu, menuElement } = useCharacterContextMenu(novelId)
   const { can } = useAuth()
   const canWrite = can('Write', novel)
   const canCreate = can('CreateContent', novel)
   const canDelete = can('DeleteContent', novel)
 
-  useHotkey('b', 'Add beat', () => canCreate && createBeat.mutate({ title: 'New beat' }), { group: 'Chapter' })
+  const focusTitleOnArrival = Boolean((location.state as { focusTitle?: boolean } | null)?.focusTitle)
+
+  const clearFocusTitleState = () => navigate(location.pathname, { replace: true, state: null })
+
+  const addBeat = () => {
+    if (!canCreate) return
+    createBeat.mutate(
+      { title: 'New beat' },
+      {
+        onSuccess: (beat) => {
+          setEditingBeatId(beat.id)
+          setFocusBeatId(beat.id)
+        },
+      },
+    )
+  }
+
+  useHotkey('b', 'Add beat', addBeat, { group: 'Chapter' })
 
   const currentIndex = chapters?.findIndex((c) => c.id === chapterId) ?? -1
   const prevChapter = currentIndex > 0 ? chapters?.[currentIndex - 1] : undefined
@@ -168,6 +189,9 @@ export default function ChapterPage() {
               value={chapter.title}
               onCommit={(title) => title.trim() && patch({ title })}
               readOnly={!canWrite}
+              autoFocus={focusTitleOnArrival}
+              selectOnFocus
+              onAutoFocused={clearFocusTitleState}
             />
             <Select
               id="chapter-kind-select"
@@ -197,22 +221,13 @@ export default function ChapterPage() {
             />
           </div>
 
-          <div className="mt-4">
-            <TagEditor
-              label="Tags"
-              tags={chapter.tags}
-              suggestions={suggestions}
-              onChange={(tags) => canWrite && patch({ tags })}
-            />
-          </div>
-
           <div className="mt-4 flex items-end justify-between gap-4">
             <div className="text-sm muted">
               {chapter.beats.length} beats · {chapter.wordCount.toLocaleString()} words
             </div>
             {canDelete && (
               <button className="btn btn-danger" onClick={() => setConfirmingDelete(true)}>
-                Delete chapter
+                Move to trash
               </button>
             )}
           </div>
@@ -235,8 +250,9 @@ export default function ChapterPage() {
 
       {confirmingDelete && (
         <ConfirmModal
-          title="Delete chapter"
-          message={`Delete chapter "${chapter.title}" and everything in it? This cannot be undone.`}
+          title="Move to trash"
+          message={`Move chapter "${chapter.title}" and its beats to the trash? You can restore it from the Trash page.`}
+          confirmLabel="Move to trash"
           onConfirm={() =>
             remove.mutate(chapter.id, {
               onSuccess: () => navigate(`/novels/${novelId}/chapters`),
@@ -274,14 +290,14 @@ export default function ChapterPage() {
             onCharacterContextMenu={handleContextMenu}
             canWrite={canWrite}
             canDelete={canDelete}
+            editingId={editingBeatId}
+            setEditingId={setEditingBeatId}
+            focusBeatId={focusBeatId}
+            setFocusBeatId={setFocusBeatId}
           />
 
           {canCreate && (
-            <button
-              className="btn btn-primary mt-3"
-              onClick={() => createBeat.mutate({ title: 'New beat' })}
-              disabled={createBeat.isPending}
-            >
+            <button className="btn btn-primary mt-3" onClick={addBeat} disabled={createBeat.isPending}>
               Add beat
             </button>
           )}
@@ -328,6 +344,15 @@ export default function ChapterPage() {
         </section>
       )}
 
+      <section id="chapter-tags" className="card mt-6 p-5">
+        <TagEditor
+          label="Tags"
+          tags={chapter.tags}
+          suggestions={suggestions}
+          onChange={(tags) => canWrite && patch({ tags })}
+        />
+      </section>
+
       {menuElement}
     </div>
   )
@@ -345,6 +370,10 @@ function BeatTable({
   onCharacterContextMenu,
   canWrite,
   canDelete,
+  editingId,
+  setEditingId,
+  focusBeatId,
+  setFocusBeatId,
 }: {
   chapter: Chapter
   novelId: string
@@ -358,13 +387,16 @@ function BeatTable({
   ) => void
   canWrite: boolean
   canDelete: boolean
+  editingId: string | null
+  setEditingId: (id: string | null) => void
+  focusBeatId: string | null
+  setFocusBeatId: (id: string | null) => void
 }) {
   const update = useUpdateBeat(chapter.id, novelId)
   const remove = useDeleteBeat(chapter.id, novelId)
   const reorder = useReorderBeats(chapter.id)
   const assignCharacter = useAssignCharacterToBeats(chapter.id)
   const moveBeats = useMoveBeats(chapter.id)
-  const [editingId, setEditingId] = useState<string | null>(null)
   const [deletingBeat, setDeletingBeat] = useState<Beat | null>(null)
   const [selectedIds, setSelectedIds] = useState<string[]>([])
   const [assignCharacterId, setAssignCharacterId] = useState('')
@@ -372,6 +404,25 @@ function BeatTable({
   const [focusedBeatId, setFocusedBeatId] = useState<string | null>(null)
   const [dragBeatId, setDragBeatId] = useState<string | null>(null)
   const [dragOverBeatId, setDragOverBeatId] = useState<string | null>(null)
+  const [returnFocusBeatId, setReturnFocusBeatId] = useState<string | null>(null)
+  const rowRefs = useRef(new Map<string, HTMLTableRowElement>())
+
+  useEffect(() => {
+    if (!returnFocusBeatId) return
+    document.getElementById(`beat-${returnFocusBeatId}`)?.focus()
+    setReturnFocusBeatId(null)
+  }, [returnFocusBeatId])
+
+  const openEdit = (beatId: string) => {
+    if (!canWrite) return
+    setEditingId(beatId)
+    setFocusBeatId(beatId)
+  }
+
+  const closeEdit = (beatId: string) => {
+    setEditingId(null)
+    setReturnFocusBeatId(beatId)
+  }
 
   const toggleSelected = (id: string) =>
     setSelectedIds((ids) => (ids.includes(id) ? ids.filter((i) => i !== id) : [...ids, id]))
@@ -449,7 +500,7 @@ function BeatTable({
   const moveButtonClass =
     'flex h-6 w-6 items-center justify-center rounded text-base leading-none transition hover:bg-[var(--accent-soft)] disabled:opacity-25 disabled:hover:bg-transparent'
 
-  const renderMoveButtons = (beat: Beat, index: number) => (
+  const renderMoveButtons = (beat: Beat, index: number, focusable: boolean) => (
     <div className="flex items-center gap-1">
       <span
         className={canWrite ? 'cursor-grab text-base muted' : 'text-base muted'}
@@ -463,6 +514,7 @@ function BeatTable({
         <button
           id={`move-beat-up-${beat.id}`}
           className={moveButtonClass}
+          tabIndex={focusable ? undefined : -1}
           onClick={(e) => {
             e.stopPropagation()
             move(index, -1)
@@ -476,6 +528,7 @@ function BeatTable({
         <button
           id={`move-beat-down-${beat.id}`}
           className={moveButtonClass}
+          tabIndex={focusable ? undefined : -1}
           onClick={(e) => {
             e.stopPropagation()
             move(index, 1)
@@ -575,28 +628,48 @@ function BeatTable({
               <tr
                 key={beat.id}
                 id={`beat-${beat.id}`}
+                ref={(el) => {
+                  if (el) rowRefs.current.set(beat.id, el)
+                  else rowRefs.current.delete(beat.id)
+                }}
                 style={{ borderBottom: '1px solid var(--line)', background: 'var(--accent-soft)' }}
-                onBlur={(e) => {
-                  if (!e.currentTarget.contains(e.relatedTarget as Node | null)) setEditingId(null)
+                onBlur={() => {
+                  window.setTimeout(() => {
+                    if (!isWithin(rowRefs.current.get(beat.id) ?? null, document.activeElement)) {
+                      setEditingId(null)
+                    }
+                  }, 0)
+                }}
+                onKeyDown={(e) => {
+                  if (e.key === 'Escape') {
+                    closeEdit(beat.id)
+                    return
+                  }
+                  if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') {
+                    closeEdit(beat.id)
+                  }
                 }}
-                onKeyDown={(e) => e.key === 'Escape' && setEditingId(null)}
               >
                 <td className="px-2 py-2 align-top">
                   <input
                     type="checkbox"
+                    tabIndex={-1}
                     aria-label={`Select beat ${beat.title}`}
                     checked={selectedIds.includes(beat.id)}
                     onChange={() => toggleSelected(beat.id)}
                     onClick={(e) => e.stopPropagation()}
                   />
                 </td>
-                <td className="px-2 py-2 align-top">{renderMoveButtons(beat, index)}</td>
+                <td className="px-2 py-2 align-top">{renderMoveButtons(beat, index, false)}</td>
 
                 <td className="px-2 py-2 align-top">
                   <AutoField
                     value={beat.title}
                     placeholder="Three to five words"
                     onCommit={(title) => title.trim() && patch(beat.id, { title })}
+                    autoFocus={focusBeatId === beat.id}
+                    selectOnFocus
+                    onAutoFocused={() => setFocusBeatId(null)}
                   />
                   <div className="mt-1.5">
                     <TagEditor
@@ -651,8 +724,9 @@ function BeatTable({
                     <button
                       className="text-xs leading-none"
                       style={{ color: 'var(--accent)' }}
-                      onClick={() => setEditingId(null)}
+                      onClick={() => closeEdit(beat.id)}
                       aria-label="Done editing beat"
+                      title="Done (mod+Enter)"
                     >
                       ✓
                     </button>
@@ -687,14 +761,14 @@ function BeatTable({
                   opacity: dragBeatId === beat.id ? 0.4 : 1,
                   boxShadow: dragOverBeatId === beat.id && dragBeatId !== beat.id ? 'inset 0 2px 0 0 var(--accent)' : undefined,
                 }}
-                onClick={canWrite ? () => setEditingId(beat.id) : undefined}
+                onClick={canWrite ? () => openEdit(beat.id) : undefined}
                 onFocus={canWrite ? () => setFocusedBeatId(beat.id) : undefined}
                 onKeyDown={
                   canWrite
                     ? (e) => {
                         if (e.key === 'Enter' || e.key === ' ') {
                           e.preventDefault()
-                          setEditingId(beat.id)
+                          openEdit(beat.id)
                         }
                       }
                     : undefined
@@ -737,7 +811,7 @@ function BeatTable({
                     onClick={(e) => e.stopPropagation()}
                   />
                 </td>
-                <td className="px-2 py-2 align-top">{renderMoveButtons(beat, index)}</td>
+                <td className="px-2 py-2 align-top">{renderMoveButtons(beat, index, true)}</td>
 
                 <td className="px-2 py-2 align-top">
                   <div className="font-medium">{beat.title}</div>

src/Novelly.Web/src/pages/ChaptersPage.tsx

@@ -1,4 +1,4 @@
-import { Link, useParams } from 'react-router-dom'
+import { Link, useNavigate, useParams } from 'react-router-dom'
 import { useChapters, useCreateChapter, useNovel } from '../api/hooks'
 import { EmptyState, ErrorNote, Spinner, StatusBadge } from '../components/ui'
 import { TagChip } from '../components/TagEditor'
@@ -7,13 +7,25 @@ import { useHotkey } from '../keyboard/HotkeysContext'
 
 export default function ChaptersPage() {
   const { novelId = '' } = useParams()
+  const navigate = useNavigate()
   const { data: chapters, isPending, error } = useChapters(novelId)
   const { data: novel } = useNovel(novelId)
   const { can } = useAuth()
   const canCreate = can('CreateContent', novel)
   const create = useCreateChapter(novelId)
 
-  useHotkey('n', 'Add chapter', () => canCreate && create.mutate({ title: 'Untitled chapter' }), { group: 'Chapters' })
+  const addChapter = () => {
+    if (!canCreate) return
+    create.mutate(
+      { title: 'Untitled chapter' },
+      {
+        onSuccess: (chapter) =>
+          navigate(`/novels/${novelId}/chapters/${chapter.id}`, { state: { focusTitle: true } }),
+      },
+    )
+  }
+
+  useHotkey('n', 'Add chapter', addChapter, { group: 'Chapters' })
 
   if (isPending) return <Spinner label="Loading chapters" />
   if (error) return <ErrorNote error={error} />
@@ -23,11 +35,7 @@ export default function ChaptersPage() {
       <div className="mb-5 flex items-center justify-between gap-4">
         <h2 className="text-xl font-semibold">Chapters</h2>
         {canCreate && (
-          <button
-            className="btn btn-primary"
-            onClick={() => create.mutate({ title: 'Untitled chapter' })}
-            disabled={create.isPending}
-          >
+          <button className="btn btn-primary" onClick={addChapter} disabled={create.isPending}>
             Add chapter
           </button>
         )}

src/Novelly.Web/src/pages/CharacterDetailPage.tsx

@@ -292,8 +292,9 @@ function CharacterSheet({
 
     {confirmingDelete && (
       <ConfirmModal
-        title="Delete character"
-        message={`Delete ${character.name}? This cannot be undone.`}
+        title="Move to trash"
+        message={`Move ${character.name} to the trash? You can restore it from the Trash page.`}
+        confirmLabel="Move to trash"
         onConfirm={() =>
           remove.mutate(character.id, { onSuccess: () => navigate(`/novels/${novelId}/characters`) })
         }

src/Novelly.Web/src/pages/LocationsPage.tsx

@@ -1,10 +1,18 @@
-import { useState } from 'react'
+import { useRef, useState } from 'react'
 import { Link, useParams, useSearchParams } from 'react-router-dom'
-import { useDeleteLocation, useLocationReferences, useLocations, useNovel, useUpdateLocation } from '../api/hooks'
+import {
+  useCreateLocation,
+  useDeleteLocation,
+  useLocationReferences,
+  useLocations,
+  useNovel,
+  useUpdateLocation,
+} from '../api/hooks'
 import { chapterLabel } from '../api/chapterLabel'
 import { useAuth } from '../auth/AuthContext'
-import { EmptyState, ErrorNote, Spinner } from '../components/ui'
+import { AutoField, EmptyState, ErrorNote, Spinner } from '../components/ui'
 import { ConfirmModal } from '../components/ConfirmModal'
+import { useHotkey } from '../keyboard/HotkeysContext'
 
 export default function LocationsPage() {
   const { novelId = '' } = useParams()
@@ -12,9 +20,16 @@ export default function LocationsPage() {
   const { data: novel } = useNovel(novelId)
   const { can } = useAuth()
   const canWrite = can('Write', novel)
+  const canCreate = can('CreateContent', novel)
   const canDelete = can('DeleteContent', novel)
   const [searchParams, setSearchParams] = useSearchParams()
   const selectedId = searchParams.get('location') ?? undefined
+  const [name, setName] = useState('')
+  const [justCreatedId, setJustCreatedId] = useState<string | null>(null)
+  const nameInputRef = useRef<HTMLInputElement>(null)
+  const create = useCreateLocation(novelId)
+
+  useHotkey('n', 'Add location', () => canCreate && nameInputRef.current?.focus(), { group: 'Locations' })
 
   if (isPending) return <Spinner label="Loading locations" />
   if (error) return <ErrorNote error={error} />
@@ -27,20 +42,48 @@ export default function LocationsPage() {
       return params
     })
 
+  const submit = (e: React.FormEvent) => {
+    e.preventDefault()
+    if (!name.trim()) return
+    create.mutate(name.trim(), {
+      onSuccess: (location) => {
+        setName('')
+        setJustCreatedId(location.id)
+        select(location.id)
+      },
+    })
+  }
+
   return (
     <div id="locations-page" className="grid gap-6 lg:grid-cols-[18rem_1fr]">
       <aside className="grid content-start gap-2">
         <div>
           <h2 className="text-lg font-semibold">Locations</h2>
-          <p className="text-sm muted">
-            Applied from a chapter. Pick one to see every chapter set there.
-          </p>
+          <p className="text-sm muted">Pick one to see every chapter set there.</p>
         </div>
 
+        {canCreate && (
+          <form id="location-create-form" onSubmit={submit} className="flex gap-2">
+            <input
+              id="location-create-input"
+              ref={nameInputRef}
+              className="input flex-1"
+              placeholder="Add a location…"
+              value={name}
+              onChange={(e) => setName(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === 'Escape') setName('')
+              }}
+            />
+            <button className="btn btn-primary shrink-0" disabled={!name.trim() || create.isPending}>
+              Add
+            </button>
+          </form>
+        )}
+        {create.error && <ErrorNote error={create.error} />}
+
         {locations?.length === 0 && (
-          <p className="mt-2 text-sm muted">
-            No locations yet. Add one from a chapter and it will appear here.
-          </p>
+          <p className="mt-2 text-sm muted">No locations yet.</p>
         )}
 
         {locations?.map((location) => (
@@ -64,7 +107,7 @@ export default function LocationsPage() {
         {!selected ? (
           <EmptyState
             title="No locations yet"
-            hint="Locations cross-reference the book: attach one to a chapter, then trace it from here."
+            hint="Add one on the left, or apply a new name to a chapter and it will appear here."
           />
         ) : (
           <LocationReferencePanel
@@ -73,6 +116,8 @@ export default function LocationsPage() {
             locationId={selected.id}
             canWrite={canWrite}
             canDelete={canDelete}
+            autoFocusName={justCreatedId === selected.id}
+            onNameAutoFocused={() => setJustCreatedId(null)}
           />
         )}
       </section>
@@ -85,11 +130,15 @@ function LocationReferencePanel({
   locationId,
   canWrite,
   canDelete,
+  autoFocusName,
+  onNameAutoFocused,
 }: {
   novelId: string
   locationId: string
   canWrite: boolean
   canDelete: boolean
+  autoFocusName: boolean
+  onNameAutoFocused: () => void
 }) {
   const { data, isPending, error } = useLocationReferences(locationId)
   const update = useUpdateLocation(novelId)
@@ -105,21 +154,20 @@ function LocationReferencePanel({
   return (
     <div className="grid gap-4">
       <div className="card flex flex-wrap items-end justify-between gap-3 p-4">
-        <label className="block">
-          <span className="label">Location name</span>
-          <input
-            className="input w-64"
-            defaultValue={data.location.name}
+        <div className="w-64">
+          <AutoField
+            label="Location name"
+            value={data.location.name}
             readOnly={!canWrite}
-            onBlur={(e) => {
-              const name = e.target.value.trim()
-              if (name && name !== data.location.name) update.mutate({ id: locationId, name })
-            }}
+            onCommit={(name) => name.trim() && update.mutate({ id: locationId, name: name.trim() })}
+            autoFocus={autoFocusName}
+            selectOnFocus
+            onAutoFocused={onNameAutoFocused}
           />
-        </label>
+        </div>
         {canDelete && (
           <button className="btn btn-danger" onClick={() => setConfirmingDelete(true)}>
-            Delete location
+            Move to trash
           </button>
         )}
       </div>
@@ -128,8 +176,9 @@ function LocationReferencePanel({
 
       {confirmingDelete && (
         <ConfirmModal
-          title="Delete location"
-          message={`Delete the location "${data.location.name}"? What carries it is left alone.`}
+          title="Move to trash"
+          message={`Move the location "${data.location.name}" to the trash? What carries it is left alone. You can restore it from the Trash page.`}
+          confirmLabel="Move to trash"
           onConfirm={() => remove.mutate(locationId)}
           onClose={() => setConfirmingDelete(false)}
         />

src/Novelly.Web/src/pages/NovelLayout.tsx

@@ -13,6 +13,7 @@ import {
   IconLocations,
   IconSettings,
   IconTags,
+  IconTrash,
 } from '../components/icons'
 import { AgentPanel, type AgentContext } from '../components/AgentPanel'
 import { HelpButton } from '../keyboard/HelpButton'
@@ -23,9 +24,10 @@ const sections: { to: string; label: string; end?: boolean; icon: ComponentType<
   { to: '', label: 'Dashboard', end: true, icon: IconDashboard },
   { to: 'chapters', label: 'Chapters', icon: IconChapters },
   { to: 'characters', label: 'Characters', icon: IconCharacters },
-  { to: 'tags', label: 'Tags', icon: IconTags },
   { to: 'locations', label: 'Locations', icon: IconLocations },
+  { to: 'tags', label: 'Tags', icon: IconTags },
   { to: 'settings', label: 'Settings', icon: IconSettings },
+  { to: 'trash', label: 'Trash', icon: IconTrash },
 ]
 
 export default function NovelLayout() {
@@ -46,6 +48,7 @@ export default function NovelLayout() {
   useHotkey('g c', 'Go to characters', () => goTo('characters'), { group: 'Navigate' })
   useHotkey('g t', 'Go to tags', () => goTo('tags'), { group: 'Navigate' })
   useHotkey('g l', 'Go to locations', () => goTo('locations'), { group: 'Navigate' })
+  useHotkey('g r', 'Go to trash', () => goTo('trash'), { group: 'Navigate' })
   useHotkey('g a', 'Toggle agent', () => setAgentOpen((o) => !o), { group: 'Navigate' })
   useHotkey('g s', 'Go to settings', () => goTo('settings'), { group: 'Navigate' })
 

src/Novelly.Web/src/pages/TrashPage.tsx

@@ -0,0 +1,127 @@
+import { useState } from 'react'
+import { useParams } from 'react-router-dom'
+import { useEmptyTrash, useNovel, usePurgeTrashed, useRestoreTrashed, useTrash } from '../api/hooks'
+import type { TrashedItem } from '../api/types'
+import { useAuth } from '../auth/AuthContext'
+import { ConfirmModal } from '../components/ConfirmModal'
+import { EmptyState, ErrorNote, Spinner } from '../components/ui'
+
+export default function TrashPage() {
+  const { novelId = '' } = useParams()
+  const { data: items, isPending, error } = useTrash(novelId)
+  const { data: novel } = useNovel(novelId)
+  const { can } = useAuth()
+  const canDelete = can('DeleteContent', novel)
+
+  const restore = useRestoreTrashed(novelId)
+  const purge = usePurgeTrashed(novelId)
+  const emptyTrash = useEmptyTrash(novelId)
+
+  const [purging, setPurging] = useState<TrashedItem | null>(null)
+  const [emptying, setEmptying] = useState(false)
+
+  if (isPending) return <Spinner label="Loading trash" />
+  if (error) return <ErrorNote error={error} />
+
+  return (
+    <div id="trash-page" className="grid gap-6">
+      <div className="flex items-center justify-between gap-3">
+        <div>
+          <h1 className="text-lg font-semibold">Trash</h1>
+          <p className="text-sm muted">
+            Trashed characters, chapters, and locations. Restore them or delete them for good.
+          </p>
+        </div>
+        {canDelete && items && items.length > 0 && (
+          <button id="trash-empty" className="btn btn-danger" onClick={() => setEmptying(true)}>
+            Empty trash
+          </button>
+        )}
+      </div>
+
+      {(restore.error || purge.error || emptyTrash.error) && (
+        <ErrorNote error={restore.error ?? purge.error ?? emptyTrash.error} />
+      )}
+
+      {!items || items.length === 0 ? (
+        <EmptyState title="Trash is empty" hint="Deleted characters, chapters, and locations show up here." />
+      ) : (
+        <div className="card overflow-x-auto" id="trash-table">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="text-left text-xs uppercase muted">
+                <th className="py-2 px-3 font-semibold">Item</th>
+                <th className="py-2 px-3 font-semibold">Kind</th>
+                <th className="py-2 px-3 font-semibold">Deleted</th>
+                <th className="py-2 px-3 font-semibold">Purges in</th>
+                {canDelete && <th className="py-2 px-3 font-semibold" />}
+              </tr>
+            </thead>
+            <tbody>
+              {items.map((item) => (
+                <tr key={`${item.kind}-${item.id}`} className="align-top" style={{ borderTop: '1px solid var(--line)' }}>
+                  <td className="py-2 px-3">
+                    <div className="font-medium">{item.label}</div>
+                    {item.detail && <div className="text-xs muted">{item.detail}</div>}
+                  </td>
+                  <td className="py-2 px-3">{item.kind}</td>
+                  <td className="py-2 px-3 muted">{new Date(item.deletedAt).toLocaleDateString()}</td>
+                  <td className="py-2 px-3 muted">{daysUntil(item.purgeAfter)}</td>
+                  {canDelete && (
+                    <td className="py-2 px-3">
+                      <div className="flex justify-end gap-2">
+                        <button
+                          id={`trash-restore-${item.id}`}
+                          className="btn"
+                          disabled={restore.isPending}
+                          onClick={() => restore.mutate({ kind: item.kind, id: item.id })}
+                        >
+                          Restore
+                        </button>
+                        <button
+                          id={`trash-purge-${item.id}`}
+                          className="btn btn-danger"
+                          onClick={() => setPurging(item)}
+                        >
+                          Delete forever
+                        </button>
+                      </div>
+                    </td>
+                  )}
+                </tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+
+      {purging && (
+        <ConfirmModal
+          title="Delete forever"
+          message={`Permanently delete "${purging.label}"? This cannot be undone.`}
+          confirmLabel="Delete forever"
+          onConfirm={() => purge.mutate({ kind: purging.kind, id: purging.id })}
+          onClose={() => setPurging(null)}
+        />
+      )}
+
+      {emptying && (
+        <ConfirmModal
+          title="Empty trash"
+          message="Permanently delete everything in the trash? This cannot be undone."
+          confirmLabel="Empty trash"
+          onConfirm={() => emptyTrash.mutate()}
+          onClose={() => setEmptying(false)}
+        />
+      )}
+    </div>
+  )
+}
+
+function daysUntil(isoDate: string): string {
+  const ms = new Date(isoDate).getTime() - Date.now()
+  const days = Math.ceil(ms / (1000 * 60 * 60 * 24))
+  if (days <= 0) return 'any time now'
+  if (days === 1) return '1 day'
+  return `${days} days`
+}

tests/Novelly.Api.Tests/CharacterArcTests.cs

@@ -152,7 +152,7 @@ public class CharacterArcTests : ServiceTestFixture
     }
 
     [Test]
-    public async Task Deleting_a_chapter_unpins_an_arc_stage_rather_than_deleting_it()
+    public async Task Trashing_a_chapter_hides_it_from_an_arc_stage_without_unpinning_it()
     {
         var chapter = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Landfall"));
         var stage = await Arcs.CreateAsync(
@@ -161,11 +161,14 @@ public class CharacterArcTests : ServiceTestFixture
         await Chapters.DeleteAsync(chapter.Id);
 
         var survivor = (await Arcs.GetAsync(stage.Id))!;
+        var response = survivor.ToResponse();
 
         Assert.Multiple(() =>
         {
-            Assert.That(survivor.ChapterId, Is.Null);
-            Assert.That(survivor.Title, Is.EqualTo("The map is wrong"));
+            Assert.That(survivor.ChapterId, Is.EqualTo(chapter.Id), "the pin survives so restoring the chapter restores the link");
+            Assert.That(response.ChapterNumber, Is.Null);
+            Assert.That(response.ChapterTitle, Is.Null);
+            Assert.That(response.Title, Is.EqualTo("The map is wrong"));
         });
     }
 

tests/Novelly.Api.Tests/CharacterServiceTests.cs

@@ -258,7 +258,7 @@ public class CharacterServiceTests : ServiceTestFixture
     }
 
     [Test]
-    public async Task Deleting_the_canonical_character_leaves_its_other_identities_alive()
+    public async Task Trashing_the_canonical_character_keeps_the_link_so_restoring_brings_it_back()
     {
         var kael = await Characters.CreateAsync(_novelId, new CreateCharacterRequest("Kael"));
         var stranger = await Characters.CreateAsync(_novelId, new CreateCharacterRequest("The Stranger"));
@@ -268,7 +268,13 @@ public class CharacterServiceTests : ServiceTestFixture
 
         using var verification = Db.CreateContext();
         var survivor = await verification.Characters.FirstAsync(c => c.Id == stranger.Id);
-        Assert.That(survivor.SameCharacterAsId, Is.Null);
+        var response = (await Characters.GetAsync(stranger.Id))!.ToResponse();
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(survivor.SameCharacterAsId, Is.EqualTo(kael.Id), "the pin survives so restoring Kael restores the identity link");
+            Assert.That(response.SameCharacterAsName, Is.Null, "a trashed canonical identity does not show up while it's in the trash");
+        });
     }
 
     [Test]

tests/Novelly.Api.Tests/LocationServiceTests.cs

@@ -151,7 +151,7 @@ public class LocationServiceTests : ServiceTestFixture
         Assert.Multiple(() =>
         {
             Assert.That(survivor.Title, Is.EqualTo("Landfall"));
-            Assert.That(survivor.Locations, Is.Empty);
+            Assert.That(survivor.ToResponse().Locations, Is.Empty);
         });
     }
 

tests/Novelly.Api.Tests/NovelAgentServiceTests.cs

@@ -100,7 +100,7 @@ public class NovelAgentServiceTests : ServiceTestFixture
         var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
 
         var model = new ScriptedModelClient([
-            [ToolUse("t1", "update_character", new { character_id = Guid.NewGuid().ToString(), name = "Ines" })],
+            [ToolUse("t1", "update_character", new { characterId = Guid.NewGuid().ToString(), name = "Ines" })],
             [new AgentTextBlock("That character does not exist yet — shall I create her?")]
         ]);
 
@@ -185,6 +185,42 @@ public class NovelAgentServiceTests : ServiceTestFixture
         });
     }
 
+    [Test]
+    public async Task Continuing_a_conversation_under_a_different_novel_is_rejected()
+    {
+        var novelAId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+        var novelBId = (await Novels.CreateAsync(new CreateNovelRequest("A Different Book"))).Id;
+        var model = new ScriptedModelClient([
+            [new AgentTextBlock("First answer.")]
+        ]);
+        var agent = BuildAgent(model);
+
+        var first = await agent.SendMessageAsync(novelAId, new SendAgentMessageRequest("Question one."));
+
+        var second = await agent.SendMessageAsync(
+            novelBId, new SendAgentMessageRequest("Question two.", first.ConversationId));
+
+        Assert.That(second, Is.Null);
+    }
+
+    [Test]
+    public async Task Continuing_a_conversation_under_its_own_novel_still_works()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+        var model = new ScriptedModelClient([
+            [new AgentTextBlock("First answer.")],
+            [new AgentTextBlock("Second answer.")]
+        ]);
+        var agent = BuildAgent(model);
+
+        var first = await agent.SendMessageAsync(novelId, new SendAgentMessageRequest("Question one."));
+        var second = await agent.SendMessageAsync(
+            novelId, new SendAgentMessageRequest("Question two.", first.ConversationId));
+
+        Assert.That(second, Is.Not.Null);
+        Assert.That(second.ConversationId, Is.EqualTo(first.ConversationId));
+    }
+
     [Test]
     public void Every_tool_declares_an_object_schema_and_a_description()
     {

tests/Novelly.Api.Tests/NovelAgentToolsetTests.cs

@@ -0,0 +1,226 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging.Abstractions;
+using Novelly.Api.Agent;
+using Novelly.Api.Beats;
+using Novelly.Api.Characters;
+using Novelly.Api.Novels;
+
+namespace Novelly.Api.Tests;
+
+[TestFixture]
+public class NovelAgentToolsetTests : ServiceTestFixture
+{
+    private NovelAgentToolset _toolset = null!;
+
+    protected override void OnSetUp() =>
+        _toolset = new NovelAgentToolset(Novels, Characters, Arcs, Chapters, ChapterLabels, Beats, Tags, Locations, Questions, NullLogger<NovelAgentToolset>.Instance);
+
+    private static JsonElement Input(object value) => JsonSerializer.SerializeToElement(value);
+
+    [Test]
+    public void The_toolset_offers_every_tool_the_stdio_server_offered()
+    {
+        var expected = new[]
+        {
+            "list_novels", "create_novel", "get_novel_brief", "update_novel_brief",
+            "list_characters", "get_character", "create_character", "update_character",
+            "get_character_beats", "get_character_arc", "add_arc_stage", "update_arc_stage",
+            "delete_arc_stage", "reorder_arc_stages", "set_arc_stage_beats", "relate_characters",
+            "link_character_identity", "unlink_character_identity",
+            "get_chapter_outline", "create_beat", "update_beat", "delete_beat",
+            "assign_character_to_beats", "reorder_beats", "move_beats",
+            "list_chapters", "get_chapter", "create_chapter", "update_chapter",
+            "list_tags", "get_tag_references", "create_tag", "update_tag", "delete_tag",
+            "list_locations", "get_location_references", "create_location", "update_location", "delete_location",
+            "list_open_questions", "raise_open_question", "update_open_question",
+            "resolve_open_question", "reopen_question", "delete_open_question"
+        };
+
+        Assert.That(_toolset.Definitions.Select(t => t.Name), Is.EquivalentTo(expected));
+    }
+
+    [Test]
+    public void No_novel_scoped_tools_schema_already_declares_a_novel_id()
+    {
+        Assert.Multiple(() =>
+        {
+            foreach (var tool in _toolset.Definitions.Where(t => t.RequiresNovelId))
+            {
+                Assert.That(tool.InputSchema.TryGetProperty("novelId", out _), Is.False, tool.Name);
+            }
+        });
+    }
+
+    [Test]
+    public async Task Creating_a_novel_through_a_tool_makes_it_appear_in_the_novel_list()
+    {
+        var result = await _toolset.ExecuteAsync(
+            "create_novel", Guid.Empty, Input(new { title = "The Ash Ledger" }));
+
+        var novels = await Novels.ListAsync();
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result.IsError, Is.False);
+            Assert.That(novels.Select(n => n.Title), Has.Member("The Ash Ledger"));
+        });
+    }
+
+    [Test]
+    public async Task Reading_a_character_by_id_returns_its_dossier()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+        var characterId = (await Characters.CreateAsync(novelId, new CreateCharacterRequest("Ines"))).Id;
+
+        var result = await _toolset.ExecuteAsync(
+            "get_character", novelId, Input(new { characterId }));
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result.IsError, Is.False);
+            Assert.That(result.Content, Does.Contain("Ines"));
+        });
+    }
+
+    [Test]
+    public async Task Relating_two_characters_shows_the_pair_on_both_dossiers()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+        var inesId = (await Characters.CreateAsync(novelId, new CreateCharacterRequest("Ines"))).Id;
+        var marcoId = (await Characters.CreateAsync(novelId, new CreateCharacterRequest("Marco"))).Id;
+
+        var result = await _toolset.ExecuteAsync(
+            "relate_characters", novelId,
+            Input(new { characterId = inesId, relatedCharacterId = marcoId, relationshipType = "sister" }));
+
+        var ines = await Characters.GetAsync(inesId);
+        var marco = await Characters.GetAsync(marcoId);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result.IsError, Is.False);
+            Assert.That(ines!.Relationships.Select(r => r.RelatedCharacterId), Has.Member(marcoId));
+            Assert.That(marco!.Relationships.Select(r => r.RelatedCharacterId), Has.Member(inesId));
+        });
+    }
+
+    [Test]
+    public async Task Setting_an_arc_stages_beats_replaces_whatever_was_there()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+        var characterId = (await Characters.CreateAsync(novelId, new CreateCharacterRequest("Ines", Importance: CharacterImportance.Main))).Id;
+        var chapterId = (await Chapters.CreateAsync(novelId, new Novelly.Api.Chapters.CreateChapterRequest("Chapter One"))).Id;
+        var beatId = (await Beats.CreateAsync(chapterId, new CreateBeatRequest("Arrival", CharacterIds: [characterId]))).Id;
+        var stageId = (await Arcs.CreateAsync(characterId, new CreateArcStageRequest("Doubt"))).Id;
+
+        var result = await _toolset.ExecuteAsync(
+            "set_arc_stage_beats", novelId, Input(new { arcStageId = stageId, beatIds = new[] { beatId.ToString() } }));
+
+        Assert.That(result.IsError, Is.False);
+    }
+
+    [Test]
+    public async Task Creating_a_tag_with_a_colour_then_renaming_it_keeps_it_on_what_carried_it()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+
+        var created = await _toolset.ExecuteAsync(
+            "create_tag", novelId, Input(new { name = "Foreshadowing", color = "#9a4a2f" }));
+        var tagsAfterCreate = await Tags.ListAsync(novelId);
+        var tagId = tagsAfterCreate.Single(t => t.Name == "Foreshadowing").Id;
+
+        var renamed = await _toolset.ExecuteAsync(
+            "update_tag", novelId, Input(new { tagId, name = "Setup" }));
+        var tagsAfterRename = await Tags.ListAsync(novelId);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(created.IsError, Is.False);
+            Assert.That(renamed.IsError, Is.False);
+            Assert.That(tagsAfterRename.Select(t => t.Name), Has.Member("Setup"));
+            Assert.That(tagsAfterRename.Select(t => t.Name), Has.No.Member("Foreshadowing"));
+        });
+    }
+
+    [Test]
+    public async Task Deleting_a_tag_leaves_the_characters_that_carried_it_alone()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+        var characterId = (await Characters.CreateAsync(
+            novelId, new CreateCharacterRequest("Ines", Tags: ["Foreshadowing"]))).Id;
+        var tagId = (await Tags.ListAsync(novelId)).Single(t => t.Name == "Foreshadowing").Id;
+
+        var result = await _toolset.ExecuteAsync("delete_tag", novelId, Input(new { tagId }));
+
+        var character = await Characters.GetAsync(characterId);
+        var tagsAfter = await Tags.ListAsync(novelId);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result.IsError, Is.False);
+            Assert.That(tagsAfter, Is.Empty);
+            Assert.That(character, Is.Not.Null);
+        });
+    }
+
+    [Test]
+    public async Task Creating_and_renaming_a_location_updates_it_everywhere()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+
+        await _toolset.ExecuteAsync("create_location", novelId, Input(new { name = "The Salt Flats" }));
+        var locationId = (await Locations.ListAsync(novelId)).Single(l => l.Name == "The Salt Flats").Id;
+
+        var renamed = await _toolset.ExecuteAsync(
+            "update_location", novelId, Input(new { locationId, name = "The Great Salt Flats" }));
+        var locationsAfter = await Locations.ListAsync(novelId);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(renamed.IsError, Is.False);
+            Assert.That(locationsAfter.Select(l => l.Name), Has.Member("The Great Salt Flats"));
+        });
+    }
+
+    [Test]
+    public async Task Updating_an_open_question_can_detach_it_from_its_chapter()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+        var chapterId = (await Chapters.CreateAsync(novelId, new Novelly.Api.Chapters.CreateChapterRequest("Chapter One"))).Id;
+        var questionId = (await Questions.CreateAsync(
+            novelId, new Novelly.Api.Questions.CreateOpenQuestionRequest("Who sent the letter?", ChapterId: chapterId)))!.Id;
+
+        var result = await _toolset.ExecuteAsync(
+            "update_open_question", novelId, Input(new { questionId, clearChapter = true }));
+
+        var question = await Questions.GetAsync(questionId);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result.IsError, Is.False);
+            Assert.That(question!.ChapterId, Is.Null);
+        });
+    }
+
+    [Test]
+    public async Task Asking_for_an_unknown_id_comes_back_as_an_error_result()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+        var missingId = Guid.NewGuid();
+
+        Assert.Multiple(async () =>
+        {
+            var character = await _toolset.ExecuteAsync("get_character", novelId, Input(new { characterId = missingId }));
+            Assert.That(character.IsError, Is.True);
+
+            var tag = await _toolset.ExecuteAsync("update_tag", novelId, Input(new { tagId = missingId, name = "x" }));
+            Assert.That(tag.IsError, Is.True);
+
+            var location = await _toolset.ExecuteAsync("delete_location", novelId, Input(new { locationId = missingId }));
+            Assert.That(location.IsError, Is.True);
+
+            var question = await _toolset.ExecuteAsync("update_open_question", novelId, Input(new { questionId = missingId }));
+            Assert.That(question.IsError, Is.True);
+        });
+    }
+}

tests/Novelly.Api.Tests/NovelMcpToolsTests.cs

@@ -0,0 +1,121 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging.Abstractions;
+using ModelContextProtocol.Protocol;
+using Novelly.Api.Agent;
+using Novelly.Api.Mcp;
+using Novelly.Api.Novels;
+
+namespace Novelly.Api.Tests;
+
+[TestFixture]
+public class NovelMcpToolsTests : ServiceTestFixture
+{
+    private NovelAgentToolset _toolset = null!;
+
+    protected override void OnSetUp() =>
+        _toolset = new NovelAgentToolset(Novels, Characters, Arcs, Chapters, ChapterLabels, Beats, Tags, Locations, Questions, NullLogger<NovelAgentToolset>.Instance);
+
+    private static CallToolRequestParams Params(string name, object? arguments = null) => new()
+    {
+        Name = name,
+        Arguments = arguments is null
+            ? null
+            : JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(JsonSerializer.Serialize(arguments))
+    };
+
+    [Test]
+    public void Every_agent_tool_is_advertised_over_mcp()
+    {
+        var tools = NovelMcpTools.Describe(_toolset.Definitions);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(tools, Has.Count.EqualTo(45));
+            Assert.That(tools.Select(t => t.Name), Is.Unique);
+            Assert.That(tools, Has.All.Matches<Tool>(t => !string.IsNullOrWhiteSpace(t.Description)));
+        });
+    }
+
+    [Test]
+    public void Tools_that_work_on_a_whole_novel_advertise_a_required_novel_id()
+    {
+        var tool = NovelMcpTools.Describe(_toolset.Definitions).Single(t => t.Name == "list_tags");
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(tool.InputSchema.GetProperty("properties").TryGetProperty("novelId", out _), Is.True);
+            Assert.That(
+                tool.InputSchema.GetProperty("required").EnumerateArray().Select(e => e.GetString()),
+                Has.Member("novelId"));
+        });
+    }
+
+    [Test]
+    public void Tools_addressed_by_child_id_do_not_advertise_a_novel_id()
+    {
+        var tool = NovelMcpTools.Describe(_toolset.Definitions).Single(t => t.Name == "delete_tag");
+
+        Assert.That(tool.InputSchema.GetProperty("properties").TryGetProperty("novelId", out _), Is.False);
+    }
+
+    [Test]
+    public void Listing_novels_over_mcp_needs_no_novel_id()
+    {
+        var tool = NovelMcpTools.Describe(_toolset.Definitions).Single(t => t.Name == "list_novels");
+
+        Assert.That(tool.InputSchema.GetProperty("properties").TryGetProperty("novelId", out _), Is.False);
+    }
+
+    [Test]
+    public void Advertised_schemas_stay_valid_json_schema_objects()
+    {
+        Assert.Multiple(() =>
+        {
+            foreach (var tool in NovelMcpTools.Describe(_toolset.Definitions))
+            {
+                Assert.That(tool.InputSchema.GetProperty("type").GetString(), Is.EqualTo("object"), tool.Name);
+                Assert.That(tool.InputSchema.TryGetProperty("properties", out _), Is.True, tool.Name);
+            }
+        });
+    }
+
+    [Test]
+    public async Task Calling_a_novel_scoped_tool_without_a_novel_id_comes_back_as_an_error_result()
+    {
+        var result = await NovelMcpTools.CallAsync(_toolset, _toolset.Definitions, Params("list_tags"), CancellationToken.None);
+
+        Assert.That(result.IsError, Is.True);
+    }
+
+    [Test]
+    public async Task Calling_a_tool_over_mcp_runs_it_against_the_novel_in_the_arguments()
+    {
+        var novelId = (await Novels.CreateAsync(new CreateNovelRequest("The Salt Road"))).Id;
+
+        var result = await NovelMcpTools.CallAsync(
+            _toolset, _toolset.Definitions, Params("get_novel_brief", new { novelId }), CancellationToken.None);
+
+        var text = ((TextContentBlock)result.Content![0]).Text;
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result.IsError, Is.False);
+            Assert.That(text, Does.Contain("The Salt Road"));
+        });
+    }
+
+    [Test]
+    public async Task A_tool_that_finds_nothing_comes_back_as_an_error_result()
+    {
+        var result = await NovelMcpTools.CallAsync(
+            _toolset, _toolset.Definitions, Params("get_character", new { characterId = Guid.NewGuid() }), CancellationToken.None);
+
+        var text = ((TextContentBlock)result.Content![0]).Text;
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(result.IsError, Is.True);
+            Assert.That(text, Does.Contain("was not found"));
+        });
+    }
+}

tests/Novelly.Api.Tests/OpenQuestionTests.cs

@@ -182,7 +182,7 @@ public class OpenQuestionTests : ServiceTestFixture
     }
 
     [Test]
-    public async Task Deleting_a_chapter_leaves_its_questions_open_rather_than_taking_them()
+    public async Task Trashing_a_chapter_leaves_its_questions_open_and_pinned_but_hides_the_chapter()
     {
         var question = await Questions.CreateAsync(_novelId, new CreateOpenQuestionRequest(
             "Does she know about the letter?", ChapterId: _chapterId));
@@ -190,10 +190,12 @@ public class OpenQuestionTests : ServiceTestFixture
         await Chapters.DeleteAsync(_chapterId);
 
         var survivor = (await Questions.GetAsync(question.Id))!;
+        var response = survivor.ToResponse();
 
         Assert.Multiple(() =>
         {
-            Assert.That(survivor.ChapterId, Is.Null);
+            Assert.That(survivor.ChapterId, Is.EqualTo(_chapterId), "the pin survives so restoring the chapter restores the link");
+            Assert.That(response.ChapterTitle, Is.Null);
             Assert.That(survivor.Question, Is.EqualTo("Does she know about the letter?"));
         });
     }

tests/Novelly.Api.Tests/ServiceTestFixture.cs

@@ -1,3 +1,4 @@
+using Microsoft.Extensions.Options;
 using Novelly.Api.Activity;
 using Novelly.Api.Beats;
 using Novelly.Api.Chapters;
@@ -7,6 +8,7 @@ using Novelly.Api.Locations;
 using Novelly.Api.Novels;
 using Novelly.Api.Questions;
 using Novelly.Api.Tags;
+using Novelly.Api.Trash;
 using Novelly.Api.Users;
 
 namespace Novelly.Api.Tests;
@@ -28,6 +30,8 @@ public abstract class ServiceTestFixture
     protected CharacterArcService Arcs { get; private set; } = null!;
     protected OpenQuestionService Questions { get; private set; } = null!;
     protected GenreService Genres { get; private set; } = null!;
+    protected TrashService Trash { get; private set; } = null!;
+    protected TrashOptions TrashOptions { get; private set; } = null!;
 
     protected CapturingLogger<NovelService> NovelLogs { get; private set; } = null!;
     protected CapturingLogger<CharacterService> CharacterLogs { get; private set; } = null!;
@@ -38,6 +42,7 @@ public abstract class ServiceTestFixture
     protected CapturingLogger<CharacterArcService> ArcLogs { get; private set; } = null!;
     protected CapturingLogger<OpenQuestionService> QuestionLogs { get; private set; } = null!;
     protected CapturingLogger<GenreService> GenreLogs { get; private set; } = null!;
+    protected CapturingLogger<TrashService> TrashLogs { get; private set; } = null!;
 
     [SetUp]
     public void SetUpFixture()
@@ -67,6 +72,7 @@ public abstract class ServiceTestFixture
         ArcLogs = new CapturingLogger<CharacterArcService>();
         QuestionLogs = new CapturingLogger<OpenQuestionService>();
         GenreLogs = new CapturingLogger<GenreService>();
+        TrashLogs = new CapturingLogger<TrashService>();
 
         Tags = new TagService(Db.Context, Access, ActivityLog, TagLogs, new CreateTagRequestValidator(), new UpdateTagRequestValidator());
         Locations = new LocationService(Db.Context, Access, ActivityLog, LocationLogs, new CreateLocationRequestValidator(), new UpdateLocationRequestValidator());
@@ -90,6 +96,8 @@ public abstract class ServiceTestFixture
             Db.Context, Access, ActivityLog, QuestionLogs,
             new CreateOpenQuestionRequestValidator(), new UpdateOpenQuestionRequestValidator(), new ResolveOpenQuestionRequestValidator());
         Genres = new GenreService(Db.Context, GenreLogs);
+        TrashOptions = new TrashOptions();
+        Trash = new TrashService(Db.Context, Access, ActivityLog, Options.Create(TrashOptions), TrashLogs);
 
         OnSetUp();
     }

tests/Novelly.Api.Tests/TrashPurgeTests.cs

@@ -0,0 +1,69 @@
+using Microsoft.EntityFrameworkCore;
+using Novelly.Api.Chapters;
+using Novelly.Api.Novels;
+using Novelly.Api.Trash;
+
+namespace Novelly.Api.Tests;
+
+[TestFixture]
+public class TrashPurgeScheduleTests
+{
+    [Test]
+    public void Before_the_run_time_the_next_run_is_today() =>
+        Assert.That(
+            TrashPurgeSchedule.NextRunAfter(new DateTimeOffset(2026, 8, 20, 1, 0, 0, TimeSpan.Zero), new TimeOnly(2, 0)),
+            Is.EqualTo(new DateTimeOffset(2026, 8, 20, 2, 0, 0, TimeSpan.Zero)));
+
+    [Test]
+    public void After_the_run_time_the_next_run_is_tomorrow() =>
+        Assert.That(
+            TrashPurgeSchedule.NextRunAfter(new DateTimeOffset(2026, 8, 20, 3, 0, 0, TimeSpan.Zero), new TimeOnly(2, 0)),
+            Is.EqualTo(new DateTimeOffset(2026, 8, 21, 2, 0, 0, TimeSpan.Zero)));
+
+    [Test]
+    public void Exactly_at_the_run_time_the_next_run_is_tomorrow() =>
+        Assert.That(
+            TrashPurgeSchedule.NextRunAfter(new DateTimeOffset(2026, 8, 20, 2, 0, 0, TimeSpan.Zero), new TimeOnly(2, 0)),
+            Is.EqualTo(new DateTimeOffset(2026, 8, 21, 2, 0, 0, TimeSpan.Zero)));
+}
+
+[TestFixture]
+public class TrashPurgeSweepTests : ServiceTestFixture
+{
+    private Guid _novelId;
+
+    protected override void OnSetUp() =>
+        _novelId = Novels.CreateAsync(new CreateNovelRequest("The Salt Road")).Result.Id;
+
+    [Test]
+    public async Task A_sweep_removes_only_items_older_than_the_retention_window()
+    {
+        var old = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Old News"));
+        var recent = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Fresh Off The Press"));
+
+        await Chapters.DeleteAsync(old!.Id);
+        await Chapters.DeleteAsync(recent!.Id);
+
+        using (var context = Db.CreateContext())
+        {
+            var oldRow = await context.Chapters.IgnoreQueryFilters().SingleAsync(c => c.Id == old.Id);
+            oldRow.DeletedAt = DateTimeOffset.UtcNow.AddDays(-31);
+            await context.SaveChangesAsync();
+        }
+
+        var cutoff = DateTimeOffset.UtcNow.AddDays(-30);
+        var (characters, chapters, locations) = await TrashPurgeRunner.SweepAsync(Db.Context, cutoff, CancellationToken.None);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That((characters, chapters, locations), Is.EqualTo((0, 1, 0)));
+        });
+
+        using var verification = Db.CreateContext();
+        Assert.Multiple(async () =>
+        {
+            Assert.That(await verification.Chapters.IgnoreQueryFilters().AnyAsync(c => c.Id == old.Id), Is.False);
+            Assert.That(await verification.Chapters.IgnoreQueryFilters().AnyAsync(c => c.Id == recent.Id), Is.True);
+        });
+    }
+}

tests/Novelly.Api.Tests/TrashServiceTests.cs

@@ -0,0 +1,249 @@
+using Microsoft.EntityFrameworkCore;
+using Novelly.Api.Beats;
+using Novelly.Api.Chapters;
+using Novelly.Api.Characters;
+using Novelly.Api.Common;
+using Novelly.Api.Locations;
+using Novelly.Api.Novels;
+using Novelly.Api.Trash;
+using Novelly.Api.Users;
+
+namespace Novelly.Api.Tests;
+
+[TestFixture]
+public class TrashServiceTests : ServiceTestFixture
+{
+    private Guid _novelId;
+
+    protected override void OnSetUp() =>
+        _novelId = Novels.CreateAsync(new CreateNovelRequest("The Salt Road")).Result.Id;
+
+    [Test]
+    public async Task Trashing_a_chapter_hides_it_from_the_chapter_list_but_keeps_its_beats()
+    {
+        var chapter = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Landfall"));
+        await Beats.CreateAsync(chapter!.Id, new CreateBeatRequest("They spot the wreck"));
+
+        await Chapters.DeleteAsync(chapter.Id);
+
+        var listed = await Chapters.ListAsync(_novelId);
+        Assert.That(listed, Is.Empty);
+
+        using var verification = Db.CreateContext();
+        var survivingBeats = await verification.Beats.IgnoreQueryFilters().Where(b => b.ChapterId == chapter.Id).ToListAsync();
+        Assert.That(survivingBeats, Has.Count.EqualTo(1));
+    }
+
+    [Test]
+    public async Task Restoring_a_chapter_brings_its_beats_back()
+    {
+        var chapter = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Landfall"));
+        await Beats.CreateAsync(chapter!.Id, new CreateBeatRequest("They spot the wreck"));
+
+        await Chapters.DeleteAsync(chapter.Id);
+        var trashedId = (await Trash.ListAsync(_novelId)).Single(i => i.Kind == TrashEntityKind.Chapter).Id;
+
+        var restored = await Trash.RestoreAsync(TrashEntityKind.Chapter, trashedId);
+        Assert.That(restored, Is.True);
+
+        var survivor = (await Chapters.GetAsync(chapter.Id))!;
+        Assert.That(survivor.Beats.Select(b => b.Title), Is.EquivalentTo(new[] { "They spot the wreck" }));
+    }
+
+    [Test]
+    public async Task Restoring_a_chapter_restores_its_word_count_to_the_activity_feed()
+    {
+        var chapter = await Chapters.CreateAsync(
+            _novelId, new CreateChapterRequest("Landfall", Prose: "The tide came in slow and cold."));
+
+        await Chapters.DeleteAsync(chapter!.Id);
+        var afterDelete = await Activity.GetForNovelAsync(_novelId, days: 1);
+
+        var trashedId = (await Trash.ListAsync(_novelId)).Single(i => i.Kind == TrashEntityKind.Chapter).Id;
+        await Trash.RestoreAsync(TrashEntityKind.Chapter, trashedId);
+        var afterRestore = await Activity.GetForNovelAsync(_novelId, days: 1);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(afterDelete.TotalWords, Is.EqualTo(0), "the create and the trash deltas cancel out");
+            Assert.That(afterRestore.TotalWords, Is.EqualTo(chapter.WordCount), "restoring adds the word count back");
+        });
+    }
+
+    [Test]
+    public async Task A_trashed_location_name_can_be_used_by_a_new_location()
+    {
+        var chapter = await Chapters.CreateAsync(
+            _novelId, new CreateChapterRequest("Landfall", Locations: ["the harbour"]));
+        var locationId = (await Locations.ListAsync(_novelId)).Single().Id;
+
+        await Locations.DeleteAsync(locationId);
+
+        var recreated = await Locations.CreateAsync(_novelId, new CreateLocationRequest("the harbour"));
+
+        Assert.That(recreated, Is.Not.Null);
+        Assert.That(chapter, Is.Not.Null);
+    }
+
+    [Test]
+    public async Task Restoring_a_location_whose_name_was_taken_reports_a_clash()
+    {
+        var locationId = (await Locations.CreateAsync(_novelId, new CreateLocationRequest("the harbour")))!.Id;
+        await Locations.DeleteAsync(locationId);
+        await Locations.CreateAsync(_novelId, new CreateLocationRequest("the harbour"));
+
+        var trashedId = (await Trash.ListAsync(_novelId)).Single(i => i.Kind == TrashEntityKind.Location).Id;
+
+        Assert.That(
+            () => Trash.RestoreAsync(TrashEntityKind.Location, trashedId),
+            Throws.TypeOf<InvalidOperationException>().With.Message.Contains("already has a location"));
+    }
+
+    [Test]
+    public async Task Trashed_characters_disappear_from_beat_listings()
+    {
+        var chapter = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Landfall"));
+        var character = await Characters.CreateAsync(_novelId, new CreateCharacterRequest("Kael"));
+        var beat = await Beats.CreateAsync(
+            chapter!.Id, new CreateBeatRequest("Kael spots the wreck", CharacterIds: [character!.Id]));
+
+        await Characters.DeleteAsync(character.Id);
+
+        var survivor = (await Beats.GetAsync(beat!.Id))!;
+        Assert.That(survivor.ToResponse().Characters, Is.Empty);
+    }
+
+    [Test]
+    public async Task Restoring_a_trashed_character_brings_it_back()
+    {
+        var character = await Characters.CreateAsync(_novelId, new CreateCharacterRequest("Kael"));
+        await Characters.DeleteAsync(character!.Id);
+        var trashedId = (await Trash.ListAsync(_novelId)).Single(i => i.Kind == TrashEntityKind.Character).Id;
+
+        var restored = await Trash.RestoreAsync(TrashEntityKind.Character, trashedId);
+
+        Assert.Multiple(async () =>
+        {
+            Assert.That(restored, Is.True);
+            Assert.That(await Characters.GetAsync(character.Id), Is.Not.Null);
+            Assert.That(await Trash.ListAsync(_novelId), Is.Empty);
+        });
+    }
+
+    [Test]
+    public async Task Emptying_trash_purges_everything_in_the_novel_but_leaves_other_novels_alone()
+    {
+        var otherNovelId = (await Novels.CreateAsync(new CreateNovelRequest("Elsewhere"))).Id;
+        var elsewhereChapter = await Chapters.CreateAsync(otherNovelId, new CreateChapterRequest("A Different Book"));
+        await Chapters.DeleteAsync(elsewhereChapter!.Id);
+
+        var chapter = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Landfall"));
+        var character = await Characters.CreateAsync(_novelId, new CreateCharacterRequest("Kael"));
+        await Chapters.DeleteAsync(chapter!.Id);
+        await Characters.DeleteAsync(character!.Id);
+
+        var purged = await Trash.EmptyAsync(_novelId);
+
+        Assert.Multiple(async () =>
+        {
+            Assert.That(purged, Is.EqualTo(2));
+            Assert.That(await Trash.ListAsync(_novelId), Is.Empty);
+            Assert.That((await Trash.ListAsync(otherNovelId)).Select(i => i.Id), Is.EquivalentTo(new[] { elsewhereChapter.Id }));
+        });
+
+        using var verification = Db.CreateContext();
+        Assert.Multiple(async () =>
+        {
+            Assert.That(await verification.Chapters.IgnoreQueryFilters().AnyAsync(c => c.Id == chapter.Id), Is.False);
+            Assert.That(await verification.Characters.IgnoreQueryFilters().AnyAsync(c => c.Id == character.Id), Is.False);
+        });
+    }
+
+    [Test]
+    public async Task Purging_a_character_that_others_relate_to_succeeds()
+    {
+        var kael = await Characters.CreateAsync(_novelId, new CreateCharacterRequest("Kael"));
+        var mira = await Characters.CreateAsync(_novelId, new CreateCharacterRequest("Mira"));
+        await Characters.AddRelationshipAsync(mira!.Id, new CreateRelationshipRequest(kael!.Id, "sibling"));
+
+        await Characters.DeleteAsync(kael.Id);
+        var trashedId = (await Trash.ListAsync(_novelId)).Single(i => i.Kind == TrashEntityKind.Character).Id;
+
+        var purged = await Trash.PurgeAsync(TrashEntityKind.Character, trashedId);
+        Assert.That(purged, Is.True);
+
+        using var verification = Db.CreateContext();
+        Assert.That(await verification.Characters.IgnoreQueryFilters().AnyAsync(c => c.Id == kael.Id), Is.False);
+    }
+
+    [Test]
+    public async Task Purging_a_chapter_deletes_its_beats_for_good()
+    {
+        var chapter = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Landfall"));
+        await Beats.CreateAsync(chapter!.Id, new CreateBeatRequest("They spot the wreck"));
+
+        await Chapters.DeleteAsync(chapter.Id);
+        var trashedId = (await Trash.ListAsync(_novelId)).Single(i => i.Kind == TrashEntityKind.Chapter).Id;
+
+        await Trash.PurgeAsync(TrashEntityKind.Chapter, trashedId);
+
+        using var verification = Db.CreateContext();
+        Assert.That(await verification.Beats.IgnoreQueryFilters().AnyAsync(b => b.ChapterId == chapter.Id), Is.False);
+    }
+
+    [Test]
+    public async Task An_editor_cannot_restore_or_purge()
+    {
+        var chapter = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Landfall"));
+        await Chapters.DeleteAsync(chapter!.Id);
+        var trashedId = (await Trash.ListAsync(_novelId)).Single().Id;
+
+        var editorId = AsNewUser(GlobalRole.Reviewer);
+        GrantNovelRole(_novelId, editorId, NovelRole.Editor);
+
+        Assert.Multiple(() =>
+        {
+            Assert.That(() => Trash.RestoreAsync(TrashEntityKind.Chapter, trashedId), Throws.TypeOf<NotAuthorizedException>());
+            Assert.That(() => Trash.PurgeAsync(TrashEntityKind.Chapter, trashedId), Throws.TypeOf<NotAuthorizedException>());
+        });
+    }
+
+    [Test]
+    public async Task Trash_lists_only_the_novels_own_items()
+    {
+        var otherNovelId = (await Novels.CreateAsync(new CreateNovelRequest("Elsewhere"))).Id;
+        var otherChapter = await Chapters.CreateAsync(otherNovelId, new CreateChapterRequest("A Different Book"));
+        await Chapters.DeleteAsync(otherChapter!.Id);
+
+        var chapter = await Chapters.CreateAsync(_novelId, new CreateChapterRequest("Landfall"));
+        await Chapters.DeleteAsync(chapter!.Id);
+
+        var listed = await Trash.ListAsync(_novelId);
+
+        Assert.That(listed.Select(i => i.Id), Is.EquivalentTo(new[] { chapter.Id }));
+    }
+
+    private Guid AsNewUser(GlobalRole globalRole)
+    {
+        var user = new NovellyUser
+        {
+            Id = Guid.NewGuid(),
+            UserName = $"{Guid.NewGuid()}@novelly.test",
+            Email = $"{Guid.NewGuid()}@novelly.test",
+            DisplayName = "Test User",
+            GlobalRole = globalRole
+        };
+        Db.Context.Users.Add(user);
+        Db.Context.SaveChanges();
+
+        UserContext.UserId = user.Id;
+        UserContext.GlobalRole = globalRole;
+        return user.Id;
+    }
+
+    private void GrantNovelRole(Guid novelId, Guid userId, NovelRole role)
+    {
+        Db.Context.NovelMembers.Add(new NovelMember { NovelId = novelId, UserId = userId, NovelRole = role, GrantedByUserId = userId });
+        Db.Context.SaveChanges();
+    }
+}