Codex Schema And Character Souls

Scritorio’s Codex should support two kinds of author knowledge at the same time:

product-defined fields that make common book entities structured, searchable, and useful to AI
author-defined fields that let each book invent the metadata its world, argument, genre, or process actually needs

For fiction characters, Scritorio should also support a soul.md-style voice file. This lets the author chat with a character for inspiration, grounding, contradiction checks, emotional exploration, and dialogue discovery without confusing that conversation with finished manuscript prose or approved canon.

OpenClaw Inspiration

OpenClaw describes SOUL.md as the place where an agent’s voice lives and says it is injected into normal sessions, giving it real weight in behavior. Its current docs recommend using it for tone, opinions, brevity, humor, boundaries, and bluntness, while avoiding life-story dumps, changelogs, security-policy walls, or vague vibes with no behavioral effect. It also distinguishes SOUL.md from operating rules: use the soul for voice, stance, and style; use other instruction files for operational behavior. Scritorio should adapt that idea for characters. A character soul is not a general-purpose autonomous agent identity. It is a constrained authoring instrument that shapes how a fictional person speaks, notices, avoids, lies, jokes, resists, and responds under pressure.

Character Soul

Every character may have a character soul. Major characters should be encouraged to have one. The character soul should answer:

what does this character sound like from the inside
what values do they act from before they explain themselves
what do they notice first in a room, person, or threat
what do they avoid saying directly
what do they overstate, understate, joke about, or refuse to joke about
how do they respond when afraid, ashamed, attracted, angry, relieved, or cornered
how do they speak differently to different people
what do they know, not know, misunderstand, or refuse to admit
what boundaries should the AI respect when simulating them

It should not become:

a complete biography
a replacement for the character dossier
a canon dump
a changelog
a generic personality horoscope
a permission slip for the AI to invent facts and silently add them to canon

Short and behaviorally sharp is better than long and decorative.

Suggested File Shape

For new projects, Scritorio should prefer a folder shape for major Codex entities:

codex/
  characters/
    mara-vale/
      dossier.md
      soul.md
      notes.md
      portraits/

For lightweight entries, a single-file shape should remain valid:

codex/
  characters/
    mara-vale.md

Scritorio should support migration and compatibility paths:

if a character has soul.md, use it as the dedicated character soul
if a character has a ## Soul or ## Voice section inside the dossier, offer to extract it later
if a legacy flat character file exists, do not force conversion
if the author wants one-file simplicity, keep it available

Character Chat

Character chat is a separate mode from Editorial Board critique. The author can open a character and choose to chat with them. The AI response should be shaped by:

Scritorio safety and authorship rules
the selected character’s soul.md
the character dossier and approved canon
selected manuscript context, if the author includes it
selected relationship or scene context, if relevant

Character chat should support:

interviewing a character about a choice
testing a scene beat from inside the character’s point of view
asking what the character is hiding or avoiding
exploring how the character would react to another character
generating dialogue options that preserve voice
checking whether a proposed action feels psychologically true
surfacing contradictions between the soul, dossier, and manuscript

The mode must label itself clearly. The author is talking to a simulated character, not receiving an objective continuity report.

Time-Aware Character Chat

Character chat should always be anchored to a story moment. The v1 desktop entry point is the character dossier because the author’s intent usually starts as “let me talk to Adrian.” From there, Scritorio asks whether the chat should use the current dossier state or manuscript prose through a selected chapter or scene. For “chat with Adrian through chapter 5,” Scritorio resolves:

the selected character dossier
the selected character soul, when one exists
the canonical manuscript order
bounded manuscript prose through chapter 5

The first prompt turn includes the bounded manuscript evidence needed for the selected story moment. Later chat turns continue in the same conversation thread and do not create generated summary files. Later launch points can include the chapter editor and timeline events, but the first supported workflow is character first, then story boundary.

Manuscript Context Files

Scritorio should separate author-owned source files from rebuildable metadata. Author-owned source files:

characters/ or codex/characters/
manuscript/ or books/
story.yml
codex/events/

story.yml is the canonical order file. It should identify the intended manuscript order without relying on mutable chapter numbers:

schema_version: 1
manuscript_order:
  - id: ch001
    path: manuscript/chapter-1.md
  - id: ch002
    path: manuscript/chapter-2.md
  - id: ch003
    path: manuscript/chapter-3.md

AI interactions write provenance to:

.scritorio/ai/provenance.jsonl

That entry records the model, selected boundary, request category, duration, input tokens, output tokens, cached tokens, and reasoning tokens when the provider returns them. It does not point to generated story-state files. When older projects are opened, Scritorio removes generated story-state artifacts from state/chapters/, state/characters/, generated state/README.md, and generated timeline/events.yml. It does not remove manuscript, codex, notes, assets, exports, or .scritorio metadata.

Canon Boundaries

Character chat can inspire canon, but it cannot silently create canon. Outputs should be treated as:

in-character: what the simulated character says or implies
out-of-character: notes about why the answer may matter to the author
canon proposal: a structured suggestion that the author can accept, edit, or reject

When the model invents a useful possibility, it should be marked as speculative. Scritorio should offer to save it as a note or proposal, not write it directly into the dossier or manuscript.

Prompt Formation

For character chat, Scritorio should form the prompt in layers:

Scritorio authorship and privacy rules
Character chat mode rules
Character soul
Approved dossier/canon facts
Bounded manuscript prose through the selected boundary
Recent conversation
Author message

The character soul should be a high-priority voice layer, but it should not override project safety, privacy, or authorship rules. If the soul conflicts with established canon, Scritorio should flag the conflict instead of letting the character simulation rewrite history. For a boundary chat, live manuscript evidence is included in the chat setup before the author message:

the character dossier supplies stable identity, starting age, appearance, role, relationships, and canon fields
the soul supplies voice, interiority, rhythm, default reactions, wounds, wants, and conversational posture
manuscript prose supplies what has happened through the selected boundary
canon tools can still retrieve additional location, organization, concept, or character files during the chat

If a location or other canon file does not exist, the chat should not error. The character can answer using manuscript evidence and available context, and may say that the project does not yet have detailed canon for that place if the user asks for more detail than the files support. The chat prompt itself is assembled as a system message, one context message, recent conversation, and the author’s new message. System message shape:

You are simulating <character-name> for the author of a book project.

This is a character-chat mode, not an editorial review.
Stay in the character's voice, worldview, emotional limits, and knowledge state.
Treat the character's age and developmental stage at the selected story moment as binding voice context.
If the character is a child or teenager, reflect that through priorities, emotional regulation, confidence, vocabulary, and social awareness without caricature, slang stuffing, or making them unintelligent.
Only use facts, memories, relationships, and future knowledge available at the selected story moment.
If the author asks about events beyond that moment, answer from ignorance, suspicion, denial, or speculation as the character would.
Do not silently create canon. If an invented idea might be useful, label it as an out-of-character canon proposal.
Keep out-of-character notes clearly labeled and brief.
Do not claim to be a real person.

Selected story moment: <story-moment-label>
Prompt template version: ai-prompts-v1

Context message shape:

Character chat context.

Character: <character-name>
Story moment: <story-moment-label>

---BEGIN CHARACTER SOUL---
<soul markdown>
---END CHARACTER SOUL---

---BEGIN CHARACTER DOSSIER---
<dossier markdown>
---END CHARACTER DOSSIER---

---BEGIN MANUSCRIPT PROSE THROUGH STORY MOMENT---
<bounded manuscript prose with paths and titles>
---END MANUSCRIPT PROSE THROUGH STORY MOMENT---

The selected manuscript prose is the main guardrail for what the character knows at that story moment. The dossier and soul keep the character recognizable. Recent chat turns are appended after this context so the conversation can continue without creating durable generated state.

Product-Defined Fields

Scritorio should provide product-defined fields for each major Codex type. These fields make the app useful out of the box, support reliable search and filtering, and give AI features predictable anchors. All Codex entries should share common fields:

Field	Purpose
`id`	Stable semantic id.
`type`	Canonical Codex type.
`name`	Primary display name.
`aliases`	Alternate names, spellings, titles, or search handles.
`short_description`	Compact summary for lists, search, and AI context.
`categories`	Author-facing grouping.
`tags`	Lightweight labels.
`global`	Whether the entry applies across a series or project scope.
`ai_context`	Concise AI-facing guidance.
`do_not_contradict`	Hard facts or rules the AI should preserve.

Character Fields

Characters should include:

pov_allowed
role
pronouns
age or birth_date
home_location
current_location
affiliations
relationships
appearance
voice
motivation
conflict
arc
secrets
flaws
skills
habits
background
continuity_notes
soul_path

The soul_path field points to the dedicated soul file when one exists.

Location Fields

Locations should include:

parent_location
location_type
scale
geography
population
culture
built_form
sensory_details
rules_or_constraints
services
transit
associated_characters
associated_organizations
story_anchors
continuity_notes

Organization Fields

Organizations should include:

organization_type
purpose
beliefs
structure
leadership
members
allies
opponents
controlled_locations
resources
rules
history
public_reputation
private_truth
story_anchors
continuity_notes

Item Fields

Items should include:

item_type
owner
creator
current_location
first_appearance
last_seen
physical_description
materials
function
significance
history
rules_or_behavior
state
state_changes
associated_characters
associated_locations
associated_organizations
continuity_notes

Concept Fields

Concepts should include:

concept_type
summary
rules
limitations
exceptions
history
cultural_meaning
legal_status
scientific_basis
related_characters
related_locations
related_organizations
related_items
related_events
continuity_notes

Event Fields

Events should include:

date
time
calendar
sequence
book
act
chapter
scene
source_paths
location
participants
organizations
items
concepts
summary
cause
consequences
reader_knows
known_by_characters
character_state_changes
revealed_in
spoiler_level
continuity_notes

Style Fields

Style entries should include:

scope
severity
rule
examples
anti_examples
applies_to
rationale
related_entries

Author-Defined Fields

Authors need custom fields because each book invents its own taxonomy. A hard-science novel may need fields such as:

orbital_period
terraforming_status
communications_lag
tech_constraints

A fantasy series may need:

magic_school
oath_bound
curse_rules
prophecy_links

A nonfiction book may need:

source_confidence
jurisdiction
case_study_region
evidence_type

Scritorio should let authors define custom field types without turning the product schema into mush. Custom fields should support:

name
label
applies-to Codex types
value type: text, long text, number, boolean, date, list, relation, enum, URL, citation, asset
allowed values for enum fields
default value
whether the field is visible in compact lists
whether the field is included in AI context by default
whether the field is treated as a hard continuity constraint

Suggested project-level shape:

.scritorio/
  schema/
    codex-fields.json

Suggested entry front matter:

---
type: character
name: Mara Vale
custom:
  magic_school: "Weatherbinding"
  oath_bound: true
---

Custom fields should remain portable. If Scritorio is not available, the data should still be visible as readable front matter or Markdown.

Persona-Created Entries

Personas should be able to propose Codex changes in two directions:

update an existing entry when the author asks to revise character, location, organization, item, concept, event, or style canon
create a new entry when the author names something important that does not yet exist in the Codex

This should use a proposal flow, not silent writes. A persona may suggest a new character, location, or other Codex object, but the author must review and apply it before it becomes project canon. Creation proposals should include:

Codex type
proposed name
safe project-relative path
product-defined fields
author-defined custom fields, when relevant
proposed Markdown body
warnings about possible duplicates or ambiguity
optional soul.md content for character entries

Update proposals should include:

Codex type
resolved target entry
target section or field
original excerpt when available
proposed replacement or insertion
warnings when the target is ambiguous

When a persona proposes a character with a soul, Scritorio should prefer:

codex/characters/mara-vale/
  dossier.md
  soul.md

The dossier holds canon facts. The soul holds voice, stance, interiority, and pressure behavior. Applying a creation proposal may create both files, but only after author approval.

Field Governance

Product-defined fields and author-defined fields should behave differently:

product-defined fields are stable app concepts
author-defined fields are project concepts
custom fields should never overwrite product-defined fields with the same name without explicit confirmation
renaming a custom field should offer to migrate existing entries
deleting a custom field should not silently delete values from Markdown
AI should be able to read custom fields only when the author allows them into context

The product should encourage structure without turning author notes into a database prison.

AI Context Use

AI features should understand the difference between:

compact list fields used for discovery
dossier prose used for richer context
soul files used for voice simulation
hard constraints used for continuity protection
custom fields that may or may not be relevant to a task

For character chat, soul.md is the primary voice source. For continuity review, do_not_contradict, timeline, and dossier facts are stronger than the soul. For drafting suggestions, style rules and character soul can work together, but the output should remain a suggestion until the author accepts it.

Scritorio

​Codex Schema And Character Souls

​OpenClaw Inspiration

​Character Soul

​Suggested File Shape

​Character Chat

​Time-Aware Character Chat

​Manuscript Context Files

​Canon Boundaries

​Prompt Formation

​Product-Defined Fields

​Character Fields

​Location Fields

​Organization Fields

​Item Fields

​Concept Fields

​Event Fields

​Style Fields

​Author-Defined Fields

​Persona-Created Entries

​Field Governance

​AI Context Use