authoring-system/AUTHORING_SYSTEM_SPEC.md

Authoring System Specification

Version: 0.2-prototype-validated Status: VALIDATED REFERENCE PROTOTYPE; FUTURE ARCHITECTURE OPEN Companion contract: SPEC.md defines the exact drafting-engine package. This document defines the authoring-system invariants for creating, reviewing, archiving, and projecting that package from authoring records; the validated prototype used a Scrivener project.

---

1. Purpose

The authoring system is an 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 was a quick local prototype for one author on one Mac. It used a frontier-model API as a temporary stand-in for the eventual dedicated drafting engine. It successfully demonstrated the complete authoring loop against a live Scrivener project; that success validates the workflow and package design, not this particular implementation form.

2. Scope and non-goals

Validated by the prototype

• Read one configured Scrivener project.
• Create a planned Manuscript scene and its paired blank BRIEF.
• 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.
• Restore a selected canonical scene’s saved package context, approved summary, and any accepted working copy for later review.
• Display scene state and explicit narrative-thread links as an author-readable continuity dashboard.
• Select a rolling package subset from a complete project lexicon.

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. Validated reference prototype — not a future architecture requirement

The validated prototype was a local web application:

• Browser UI: runs at http://127.0.0.1:<port>; no public listener.
• Local service: dependency-light Python process that owned project access, workflow logic, package construction, and model calls.
• Scrivener adapter: reads and writes the .scriv bundle only while Scrivener is closed.
• Prototype records: stable scene/BRIEF and narrative-thread bindings were stored in a project-local JSON file; accepted drafts and package snapshots were stored in the Scrivener project. No SQL sidecar was required for the proof of concept.
• 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. A future authoring system may be a native Mac application, a local or hosted web application, or another interface; it may use Scrivener, a database, or both as storage. It must preserve the invariants in this document and the package contract in SPEC.md, rather than reproduce this prototype’s technology choices.

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.

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: author-visible home for thread material. The prototype stored the actual UUID predecessor links in its project-local binding record; a later implementation may choose a different representation.

The prototype confirmed that one term — definition lexicon entry per paragraph is a workable author-facing convention and that summaries, characters, places, BRIEFs, and scenes can remain ordinary Scrivener text records. Detailed future record templates remain open.

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 preserve a prior version outside active Manuscript. The prototype created archive records; full branch restoration remains future work.
4. The service creates a recoverable project backup before a structural Binder write.
5. Package snapshots and the first accepted-for-editing draft are immutable once saved. The prototype also retained an editable working-copy record that can be restored after restarting the app.

7. Scene lifecycle

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 Future: branches and restoration

If the author replaces a canonical scene or abandons a continuation, a future implementation should preserve the old text and its bindings in Superseded & Branches (or equivalent durable history). It should choose exactly one active canonical path for package construction. Restoring an earlier path should mark dependent derived context stale and reproject it from the selected point. The prototype created the reserved location but did not implement full branch restoration.

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 validated prototype exposed term — definition entries as checkboxes, loaded the selected entries into an editable package field, and carried the subset forward until changed.
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 any selected canonical 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 narrative-thread membership freely; the default is continuation of the preceding canonical scene's thread. Selecting an existing older thread resumes it. Thread membership is distinct from package context: a new thread may still draw STORY, PREVIOUS, or RECALL from any author-selected canonical scene, and a continuation may omit any of them.

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 prototype preserved an immutable package snapshot and accepted draft records in Scrivener, and displayed the exact package before generation. A production implementation should additionally retain provider, model identifier, instruction version, sampler settings, request time, and response provenance in whichever durable storage it adopts. The temporary instruction is never part of the SFT training pairs or the eventual dedicated-engine package.

10. Validated prototype workflows

Project dashboard

• Choose/configure one Scrivener project.
• Display lock status, planned and canonical scene counts, scene/BRIEF binding health, and a continuity dashboard of explicit thread links and approved summaries.

Prepare scene

• Select a planned or existing scene/BRIEF pair, or create a planned scene and its paired BRIEF directly.
• 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; restore a selected scene’s saved package context and working copy when available.
• Reject, retry, accept for editing, and directly edit the accepted working copy.
• 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, and world notes; thread membership remains an explicit author choice.
• Approve, edit, reject, or apply configured blanket approval per category.
• Show provenance: source scene, method/model, time, and approval status.

11. Prototype delivery record

Completed: 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.

Completed: 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 Scrivener archive.

Completed: 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.

Completed: continuity assistance

• Propose dense scene summaries, character updates, lexicon additions, and world-note additions after acceptance.
• Add author approval for summaries and continuity updates; full re-projection for reordered/restored branches remains future work.

12. Prototype acceptance evidence

The prototype met these criteria in the Hapa Girls test project:

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 and continuity updates without the system silently changing canon.
7. Create a new scene and paired BRIEF in the app, then use it in the same workflow.
8. Reopen the Scrivener project and see accepted scenes, package snapshots, working copies, summaries, and continuity records intact.
9. Represent separate and branching narrative threads independently from STORY, PREVIOUS, and RECALL package selections.

13. What the prototype proved—and what it did not

Proven

• The SPEC.md package is practical for interactive, scene-by-scene book drafting.
• Scrivener can hold the author-facing source records, canonical prose, accepted drafts, package snapshots, summaries, and continuity updates required for a useful workflow.
• The author can retain complete control while receiving model-generated drafts and proposed continuity updates.
• Stable IDs, not scene labels or chapter placement, can preserve scene/BRIEF and narrative-thread relationships through reorganization.
• A small local interface is sufficient to make package assembly, review, and restoration manageable for an author.

Not implied

• Scrivener need not be the sole or eventual storage system.
• A browser UI, Python service, JSON binding file, OpenRouter, or a Mac-only deployment is not mandated for the next implementation.
• The frontier-model stand-in is not evidence that the eventual dedicated drafting engine will have identical behaviors or API requirements.
• Prototype success does not freeze package syntax or resolve the corpus/training decisions in SPEC.md.

14. Open design decisions for future implementations

• Exact text templates for Characters, Places, Narrative Threads, and archive records.
• Durable storage and synchronization design when Scrivener is not the only store.
• Database or sidecar schema and backup/restore mechanics, if a future implementation needs one.
• 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.