authoring-system/AUTHORING_SYSTEM_SPEC.md

# Authoring System Specification

**Version:** 0.1-prototype-draft  
**Status:** DRAFT  
**Companion contract:** `SPEC.md` defines the exact drafting-engine package. This document defines the authoring system that helps an author create, review, archive, and project that package from a Scrivener project.

---

## 1. Purpose

The authoring system is a local, interactive assistant for fiction drafting. It keeps the author focused on the `BRIEF`, maintains project continuity, builds a valid package for `SPEC.md`, and manages the draft-to-canon workflow.

The first implementation is a quick local prototype for one author on one Mac. It uses a frontier-model API as a temporary stand-in for the eventual dedicated drafting engine.

## 2. Scope and non-goals

### In scope for the prototype

- Read one configured Scrivener project.
- Assemble and display a package before generation.
- Call a configurable frontier-model provider with a temporary adapter instruction.
- Support reject, retry, accept-for-editing, collaborative revision, and accept-into-book.
- Preserve package snapshots and accepted-for-editing drafts.
- Propose continuity updates after a scene becomes canonical.
- Write accepted canonical prose back into Scrivener.

### Explicitly out of scope

- Training, serving, or evaluating the dedicated drafting engine.
- Multi-user collaboration, synchronization, accounts, or cloud storage.
- A general database schema for all future authoring-system implementations.
- Replacing Scrivener's compilation, editor, or manuscript-management features.
- Automatic canon changes without the author's selected approval policy.

## 3. Design principles and invariants

1. **Author owns creative intent.** `BRIEF` is author-authored. The system may propose context, never silently substitute plot intent.
2. **Committed canon only.** Only text accepted into the book supplies continuity context for later packages.
3. **Canonical text location.** Active canonical prose exists only at `Manuscript → Chapter → Scene X`.
4. **Stable scene identity.** A scene has a durable structural ID and a user-facing label such as `Scene 1`. Moving it between chapters or reordering it does not break its BRIEF or history linkage.
5. **Chapter is presentation; scene is the unit.** A chapter may contain any number of scenes. Scene order and thread order may differ.
6. **No destructive history.** Superseded scenes and abandoned continuations are preserved outside the active manuscript. Rejected drafts are discarded unless the author had accepted them for editing.
7. **Visible autonomy.** The author chooses review or blanket-approval behavior by category. Every system-generated proposal retains provenance and status.
8. **Local-first.** Book content remains on the Mac. The only external transmission is an author-authorized package sent to the configured model provider.

## 4. Prototype architecture

The prototype is a local web application:

- **Browser UI:** runs at `http://127.0.0.1:<port>`; no public listener.
- **Local service:** Python/FastAPI process that owns project access, workflow logic, package construction, and model calls.
- **Scrivener adapter:** reads and writes the `.scriv` bundle only while Scrivener is closed.
- **Operational sidecar:** a local SQLite database or equivalent adjacent to the project. It records stable bindings, package snapshots, draft history, model-call metadata, and derived-proposal provenance. It is not the source of canonical prose.
- **Frontier-model adapter:** takes a versioned temporary system instruction plus the exact package as the request content. It is replaceable by the dedicated drafting-engine adapter.

The adapter boundary is deliberate: the UI and continuity workflow must not depend on a particular model vendor or API.

## 5. Scrivener project contract

The system supports a project with the following author-visible Binder structure. Extra author folders are allowed; the named system locations are reserved.

```text
Manuscript/
  Chapter 1/
    Scene 1                 # active canonical prose or planned placeholder

Authoring System/
  Book Setup/
    STYLE
    Frontier-Model Instructions
  Scene Briefs/
    Scene 1                 # paired author-authored BRIEF
  Continuity/
    Master Lexicon
    Scene Summaries/
      Scene 1               # approved dense event summary
    Narrative Threads/
    World Notes
  Drafting Archive/
    Accepted for Editing/
    Package Snapshots/
    Superseded & Branches/

Characters/                 # one text file per character
Places/                     # one text file per place
```

### 5.1 Pairing scenes and briefs

For the prototype, `Scene X` in `Scene Briefs` pairs with `Scene X` in `Manuscript` by an application-maintained binding of their Scrivener Binder UUIDs. Matching labels make the pairing visible to the author but are not the sole key.

The system creates a corresponding brief whenever it creates a scene. It flags, rather than guesses at, unmatched or duplicate labels.

### 5.2 Planned versus canonical scenes

A blank Manuscript scene paired with a brief is a **planned** scene. It has no continuity effect and produces no compiled prose. Once the author accepts its completed text into the book, it becomes **canonical**.

### 5.3 Author-facing source records

- `STYLE`: default book voice and any declared Part-level alternatives.
- `Scene Briefs`: author-owned plot and character-direction instructions.
- `Characters`: initial character descriptions and maintained character records.
- `Places` and `World Notes`: reusable setting and physical-continuity information.
- `Master Lexicon`: complete book-level controlled vocabulary; the package receives an author-selected rolling subset.
- `Scene Summaries`: one approved dense event sentence per canonical scene.
- `Narrative Threads`: records the author-selected thread identity and active order for each scene.

Detailed document templates and fields remain to be specified as the prototype exposes the real authoring workflow.

## 6. Project access and safety

1. Before every write, the service checks for Scrivener's active project lock. If present, it refuses the operation and tells the author to close Scrivener.
2. The prototype treats Scrivener as closed for all write operations. It may later support cautious read-only inspection while open, but this is not a v0.1 requirement.
3. Every Scrivener mutation is non-destructive: create a new document, revise the intended active scene, or move a prior version to `Superseded & Branches`.
4. The service creates a recoverable project backup before a structural Binder write.
5. Package snapshots and model-call records are immutable once a request has been made.

## 7. Scene lifecycle

```text
planned scene + BRIEF
  → package preparation
  → generated draft
  → reject / retry
  → accept for editing
  → collaborative revision
  → abandon / accept into book
  → proposed continuity updates
  → author review or configured auto-accept
```

### 7.1 Draft outcomes

- **Reject:** discard the draft; it creates no archive record or canonical facts.
- **Retry:** discard the current candidate and generate again from the same or revised package.
- **Accept for editing:** immediately preserve an immutable first-draft snapshot in `Accepted for Editing` and record its package and model metadata. The draft remains non-canonical.
- **Abandon after editing acceptance:** retain the preserved snapshot as uncommitted/abandoned; it never affects package context.
- **Accept into book:** write final edited prose to the paired Manuscript scene and mark it canonical.

### 7.2 Branches and restoration

If the author replaces a canonical scene or abandons a continuation, preserve the old text and its bindings in `Superseded & Branches`. The app chooses exactly one active canonical path for package construction. Restoring an earlier path marks dependent derived context stale and reprojects it from the selected point.

## 8. Package preparation

The app builds the exact nine-section package defined by `SPEC.md`. The author may inspect and edit the assembled package before sending it.

| Section | Prototype source and control |
|---|---|
| STYLE | Book setup record; declared Part-level alternate when applicable. |
| LEXICON | Author-selected rolling subset of Master Lexicon; the app may suggest terms found in BRIEF. |
| STORY | Up to five approved summaries on the selected thread, excluding PREVIOUS. |
| CHARACTERS | Author-selected rolling roster with proposed current-state snapshots. |
| RECALL | Author-selected committed scenes from any thread or prior series book, as full text or an editable summary. |
| PREVIOUS | Author-adjustable, paragraph-boundary verbatim tail from the preceding selected-thread scene. |
| NOTES | Author-selected world constraints and explicitly marked required verbatim text. |
| BRIEF | Paired author-owned brief. |
| DIRECTIVE | Author-selected word maximum, ending instruction, and local handling. |

The author selects the narrative thread freely; the default is continuation of the preceding canonical scene's thread. Selecting an existing older thread resumes it. Marking a new thread makes STORY and PREVIOUS empty.

## 9. Frontier-model stand-in

For the prototype, a model call contains two distinct inputs:

1. **Frontier-model instructions:** a versioned, project-level adapter prompt stored in `Book Setup → Frontier-Model Instructions`. It explains the temporary provider's role and requires prose-only output.
2. **Drafting package:** the exact text defined by `SPEC.md`, ending at `### SCENE`.

The adapter records provider, model identifier, instruction-version ID, sampler settings, request time, response, and package snapshot. The temporary instruction is never part of the SFT training pairs or the eventual dedicated-engine package.

## 10. Initial browser workflows

### Project dashboard

- Choose/configure one Scrivener project.
- Display lock status, active manuscript path, planned scenes, canonical scenes, and stale derived context.

### Prepare scene

- Select a planned or existing scene/BRIEF pair.
- Choose or create a narrative thread.
- Select characters, lexicon entries, recall material, notes, PREVIOUS tail length, and DIRECTIVE.
- View system-generated suggestions separately from author-approved data.
- Review the complete package and generate.

### Draft and revise

- Display the generated draft alongside the BRIEF and package.
- Reject, retry, accept for editing, directly edit, or request a frontier-model edit.
- Preserve the first accepted-for-editing draft before any edits.
- Accept final prose into the paired Manuscript scene.

### Continuity review

- After acceptance, display proposed summary, character updates, lexicon additions, world notes, and thread-state updates.
- Approve, edit, reject, or apply configured blanket approval per category.
- Show provenance: source scene, method/model, time, and approval status.

## 11. Implementation phases

### Phase 1 — project reader and package preview

- Load the test Scrivener project and validate the reserved Binder structure.
- Bind existing `Scene X` briefs, manuscript placeholders, characters, and places.
- Display them locally; make no Scrivener writes.
- Assemble a manually selected package and export/display it.

### Phase 2 — frontier generation and draft archive

- Add provider configuration and the temporary instruction adapter.
- Generate, reject, retry, and accept-for-editing drafts.
- Write immutable draft and package snapshots to the archive/sidecar.

### Phase 3 — commit to Manuscript

- Add direct editing and accept-into-book.
- Safely write final prose to the paired Scrivener scene.
- Create backups and enforce lock checks.

### Phase 4 — continuity assistance

- Propose dense scene summaries, character updates, lexicon additions, notes, and thread updates after acceptance.
- Add author approval and re-projection for reordered/restored scenes.

## 12. Prototype acceptance criteria

The prototype is successful if an author can use the Hapa Girls test project to:

1. Select one of the prepared scene briefs and its planned scene.
2. Assemble a visible package from the relevant Scrivener records.
3. Send it to the temporary frontier-model adapter.
4. Reject/retry drafts and preserve the first draft accepted for editing.
5. Edit a selected draft and accept the result into its paired Manuscript scene.
6. Review and approve a proposed dense summary without the system silently changing canon.
7. Reopen the Scrivener project and see the accepted scene and archive records intact.

## 13. Open design decisions

- Exact text templates for Characters, Places, Narrative Threads, and archive records.
- Whether the first prototype stores every archive artifact in Scrivener, the sidecar, or both.
- SQLite schema and backup/restore mechanics.
- Frontier-model provider and API credentials/configuration approach.
- Detailed permissions for per-category blanket approval.
- How the app creates and tracks Part boundaries and style assignments.
- The freeze decisions listed in `SPEC.md` §9.