Entities & Mentions

Track characters, locations, and any named element in your book — and link them to the prose that references them.

What it does

Entities are named elements in your story world: characters, locations, factions, artefacts, or any type your book defines. Each entity has a file that records its name, type, aliases, relationships to other entities, and a free-form notes area. When you type an @-mention in the editor, Skribex resolves it to an entity automatically — creating one if it doesn't exist yet — and tracks every element of your manuscript where that entity appears.

How to use it

Create an entity:

• Use the entity panel or API to add a character, location, or any configured type.
• Provide a name (required), type (required), and optional aliases.
• A stub entity file is created immediately with status "active".

@-mention in the editor:

• Type @ followed by a name or alias in the manuscript.
• The editor autocomplete suggests matching entities. Select one to link it.
• If no match exists, selecting "create" resolves the mention and creates a stub entity in one step.

Alias a mention:

• If a mention text (e.g. "The Raven") refers to an existing entity (e.g. "Aria Voss"), use the alias action to link them.
• Future mentions of "The Raven" will resolve to Aria Voss automatically.

Entity assist — automatic entity linking:

Skribex can automatically link entity names in your prose without needing to type @. Configure the mode from the status bar (@ button, click to cycle) or from the dashboard settings.

• Discover mode (@↵): When you press Enter, the previous paragraph is scanned for known entity names and aliases. Matches are automatically converted to @-mentions with a brief highlight flash. Handles possessives ("Jane's") and simple plurals.
• Suggest mode (@…): As you type, after 2+ characters, a faded ghost-text completion appears inline. Press Tab to accept and convert to an @-mention. Any other key dismisses the suggestion.
• Both mode (@✦): Discover and suggest active simultaneously.
• Off (@): No automatic entity linking.

Entity assist can be set globally (applies to all books) or overridden per book. The status bar button sets the per-book override; the dashboard has both global and per-book dropdowns.

Relationships:

• Add a relationship between two entities using the connection form on the entity page: search for a target entity, then pick a relationship type from the dropdown.
• 53 built-in relationship types across 7 categories (kinship, social, spatial, possession, epistemic, participatory, taxonomic). Each has a human-readable description shown in the dropdown.
• The type list filters by domain/range: on a character page, you see kinship and social types first; on a location page, spatial types.
• Relationships are stored in .skribex/relationships.json (one direction per edge). The inverse is derived automatically from the type registry — creating "parent of (Kael → Mira)" automatically shows "child of (Mira → Kael)" on Mira's page.
• Inferred relationships: Some relationship types trigger automatic inference. For example, creating "leader of" also creates "member of" with an "(inferred)" badge. You can confirm or dismiss inferred relationships on the entity page.
• Status badges: Relationships can be active, ended, potential, or contested — shown as subtle badges next to each connection.
• Temporal markers on relationships: Optionally link a relationship to a point in the narrative timeline. Click "link to timeline…" below the relationship type picker to reveal "Starting from" and "Ending at" dropdowns. These suggest existing timeline markers, events, and chapter headings. When set, the relationship displays "since [marker]" or "until [marker]" badges. Functional relationships (e.g. "based in") auto-terminate the previous edge when a new one is created — if you provide a "Starting from" marker, the old edge's "Ending at" is set automatically.
• Inline relationship creation: In the editor, type ~begins:(Entity · relType · Target) to create a relationship directly from the prose. A multi-step dropdown guides you: first pick an entity, then a relationship type, then the target. Similarly, ~ends:(Entity · relType · Target) terminates an active relationship. These appear as coloured chips in the text (green ▸ for begins, red ◂ for ends).

Backlinks:

• An entity's page lists every manuscript element that @-mentions it, with a count per element.
• Backlinks are updated whenever mentions are resolved or chapter content changes.

Entity page:

• Click an @-mention badge in the editor or the "view page" link in the sidebar panel to open the entity's full page.
• The page shows: name, type, mention count, aliases, custom profile properties, relationships, backlinks, link references, notes, and a markdown description.
• The markdown description is editable — click "edit" to write in a textarea, then save.
• Archive or delete an entity from the bottom of the page (with confirmation).

Entities overview:

• Navigate to /books/{slug}/entities to see all entities with search, type filters, and sort controls.
• Search by name or alias. Filter by entity type. Sort by name or mention count.
• Unresolved stub entities appear in a highlighted section at the top with quick actions: assign type, merge into another entity, or delete.

Entity panel (sidebar):

• When your cursor is on an @-mention, the right sidebar shows a compact entity card with name, type, mention count, aliases, and a link to the full entity page.
• Expanded cards have a subtle highlight to distinguish them from collapsed cards.

Autocomplete suggest:

• The editor suggest endpoint matches on names and aliases by prefix.
• Results are returned in under 100ms via a SQLite index.

Notes

• Entity types (character, location, …) and their colours are defined in your book's types.json.
• Aliases are case-insensitive for matching but stored as provided.
• Deleting an entity does not remove existing @-mentions in the manuscript; their backlinks simply no longer resolve.
• Entity files live in entities/ inside your book directory and are versioned in git.