Conventions at a Glance

This chapter is the portable copy of the engine's standing conventions. Assistant instructions live outside the cloneable tree and may not carry over when this project is cloned; this chapter ships with the Builder's Manual and always does. A session working in a clone should treat this chapter — plus the Startup Contract and Startup Checklist — as the authority when /assistant-instructions/ is absent.

The standing conventions

This engine is a system-agnostic ontology-based knowledge engine for narrative and dice-driven games. Every piece of content serves retrieval-first knowledge work.

• Naming — title-level recall tags. File names carry a tag suffix after the subject, so recall never conflates concepts sharing a name: Thornhollow-place, Thornhollow-lore, Thornhollow-state; by extension -person, -rule, -spell, -event, -memory. Soft convention: apply the tag where it adds recall value — especially places, named things, and anything that could collide with a same-named sibling.
• Chunking — one file, one fact cluster. Each file holds a single focused cluster of meaning, small enough to embed and retrieve as a unit. Atomize the cluster into keyFacts and give it a token-efficient summary — the recall surface.
• Ontology linking. Prefer references over prose: link location, characters, relatedLore instead of restating facts. Always set canonLevel (canon / established / rumor / myth / theory / retconned) and anchor with era so retrieval is truth- and time-aware.
• Folder nesting. Organize by ontology domain, deeply: /Lore/Geography/, /Lore/History/, /Lore/Culture/. Nest subfolders for regions or civilizations when content grows. Never flatten a large knowledge base.
• Memory model. Any Memory or Event content carries location, characters involved, and a timestamp from the start — never recall memories by pure similarity alone; that recycles concepts and mixes sessions.

Startup behavior

The Startup Contract and Startup Checklist chapters are the authoritative description. The shape in brief:

1. Vision pass first — scope, intent, themes, narratives, flavor, genres in the user's own words, written as-you-go into the World Vision scaffold (/World Visions/). The scaffold is the writable, resumable recovery point; an interrupted setup loses nothing.
2. Core questions — genre, magic level, world name, setting, era, tone — then branch follow-ups only as the answers warrant. The questionnaire stops when the world is playable.
3. Concept opt-in from the Startup Checklist; unpicked domains are declared absent and recorded on the World Profile (conceptsIncluded, plus no-* tags).
4. Create the profile and lore. World Profile written; lore tree scaffolded for the genre; one starter file per selected domain; founding lore chunk generated and linked both ways.
5. Examples stay. New content is built in the new world's namespace alongside the tagged example templates — the templates' shape is reused with the new world's themes, content, and flavors.

Truth and time

• canonLevel — canon and established are fact; rumor and myth are hearsay and legend, recalled only as such; retracted marks overturned claims — never silently deleted, always noted with the replacement.
• era — anchors every claim in time; current truth lives in -state files, historical truth in history files.

Merging an existing project — the package overlay

The engine is a module meant to be loaded on top of a world or campaign that already exists — a live campaign built in another system, a wiki, a doc set, or another engine. When this engine layers onto an existing project, its own work must stay differentiable from the base systems, and that differentiation is what makes the rework callable:

• Every file the engine creates or rebuilds in the merge carries the provenance tag source-ontology-project. This includes World Profile, World Vision, each typed entity, each lore chunk, and each stat block migrated from a foreign format. The tag marks the engine's footprint: engine-reworked content can be told apart from the base project's untouched native files, and the merge's progress is measurable by counting it.
• The merge runs on demand, never automatically. The source-ontology-project tag exists to be called: a user (or a later session) says "rework this world under the engine" or "merge this campaign in," and the ingestion rules in Ingesting External Content run — each produced file tagged source-ontology-project as it goes. No sentinel or session-start trigger re-works the world on its own; the tag is a question, not a switch.

The merged base world stays the authority: the World Profile's era, genre, and truth defaults rule, and base-format files are rebuilt into engine format rather than silently overwritten.

The acquisition ladder

Deletions require explicit user approval, and reuse is the default — example content is retained and repurposed with new themes, content, and flavors, not cleaned up. When a file's future is in question, work in this order, stopping at the first step that fits:

1. Reuse / retain — keep the file as a living style reference or repurpose it into the new world.
2. Rename / rewrite — the repurposing path: rename the file into the new world's namespace and replace its contents (drop the example tag).
3. Retire — only when a file can neither be reused nor deleted: move it to /Legacy/ (preserving folder nesting underneath) as a holding state, not an endpoint.
4. Delete — only with explicit approval.

Retrieval

Navigate the knowledge base through its index, never by enumerating files into context:

• Index first — read or line-up /Ontology-Engine/OE-Index/OE-Knowledge-Index.index.md with the query's key terms before touching content files.
• Score by relevance — folder domains first, then per-file tag overlap, then proper names, then canon/era fit.
• Read only the top 2–5 candidates in one batch; stop when tag overlap drops below the query's core terms.
• Keep the index current — update the entry the same session a file is added, renamed, or re-tagged; an index that disagrees with ls is poison for retrieval.

Migration and editing

The operational counterpart to the standing conventions. Full detail in the chapter Migration and Lifecycle Conventions.

• Retire-then-relocate — after a type is retired, move its files out of live folders to /Retired/<domain>/; never leave two files in the same folder resolving to the same slug.
• Slug verification — list the target folder before writing a reference; slugs derive from file names.
• No-draft-refs rule — never reference an empty domain; record known-empty domains in the index registry in place of a fake reference.
• Single-writer documents — the knowledge index and the handbook chapter lists are serial-write: one edit pass per phase, never in parallel.
• Sub-agents draft; the main agent commits handbooks, project settings, the index, and file-type configs.

Import / merge

Content from outside is raw material, not finished content, until rebuilt into the engine's format. Full detail in the chapter Ingesting External Content.

• Lists are signals, not chunks. An aggregate list of vehicles, vehicles, NPCs, or monsters generates one typed file per entity.
• Maps generate locations. Named pins and labels on an imported map become Location/Region files (terrain-tagged), with the pins linked to those files.
• Pins outlive files. Removing, retiring, or renaming a location file does not remove its pins from the maps — sweep the maps before closing the merge and relink, repurpose, or remove every pinned reference. A pin left pointing at a retired file is a draft reference in map form.
• Prose becomes chunks. Long setting prose is separated into /Lore/<domain>/ fact clusters, each with summary + keyFacts.
• Foreign schemas are migrated, never carried. The source system's shape is data, not rules.
• Anchor everything. Default era to the World Profile's era; default canonLevel to established, downgrade to rumor/myth when the source is hearsay or legend. Ingested claims are never automatically canon.
• No silent overwrites. Same-named concepts get recall tags or renames; the base's example content follows the legacy ladder.
• On existing projects, tag the package. When the engine layers onto a campaign built elsewhere, every engine-created or reworked file carries the provenance tag source-ontology-project, so engine work is differentiable from base-system files — and merges are called on demand (never automatic; the tag is a query, not a switch).

Where the detail lives

• Naming, chunking, and folders — chapter Naming, Chunking, and Folders
• Lore fields — chapter Anatomy of a Lore File
• Linking and retrieval discipline — chapter Relational Linkage and Retrieval Discipline
• The type graph and relational rules — chapter The Ontology Map
• What startup promises — chapter The Startup Contract
• The full coverage checklist — chapter The Startup Checklist
• Geographic classification — chapter Terrain Taxonomy and Geographic Tags
• System migration and type lifecycle — chapter Migration and Lifecycle Conventions
• Merging existing projects and package provenance — chapter Ingesting External Content