Timeline, sheets, maps & media

add_media

Imports an on-disk file into the project's assets/ folder and creates a media asset (portrait, map base image, reference art, gallery image). Optionally attaches it to an entity's gallery. The kind is inferred from the file extension when omitted.

Example call

{
  "name": "add_media",
  "arguments": {
    "path": "<path>"
  }
}

create_chart

Creates a chart of tabular data. "kind" is bar (default), line, area, or pie; "categories" are the shared x-axis labels; "series" is an array of {name, values:[numbers]} (a pie uses the first series). Charts embed in prose by title with ![[Chart Title]].

Example call

{
  "name": "create_chart",
  "arguments": {
    "title": "<title>"
  }
}

create_continuity_rule

Adds a continuity rule the validator checks: entity E's field F, compared against a value V. "comparison" is equals (default), not_equals, contains / not_contains (case-insensitive substring -- good for prose so a wording tweak does not false-alarm), less_than / less_or_equal / greater_than / greater_or_equal (numeric), is_empty / is_non_empty (no value needed), or one_of (V is a set: pass "values" or a '|'-joined "value"). With "when" (a project-calendar date) the field is checked as of that story moment (state-over-time); without it, the base value. get_conflicts reports any violation. "applies_to" scopes the rule to a whole set -- every Item, everything tagged act-one -- so "every Item has a price" is written once rather than per entity, and the reply says how many objects it reaches. For anything one field against one value cannot say, pass "expression" instead of "field"/"comparison"/"value".

Example call

{
  "name": "create_continuity_rule",
  "arguments": {
    "name": "<name>"
  }
}

create_map

Creates a map. Optionally imports a "base_image" file (an absolute path or one relative to the project folder) into assets/ as the backdrop, sets the measurement scale ("width_distance" spanning the image in "distance_unit" units, plus "travel_speed" per hour for the timeline's journey checks), and overlays a battle "grid" (none/square/hex, "grid_columns" wide). get_map/update_map then operate on it (add pins, tokens, reveal regions).

Example call

{
  "name": "create_map",
  "arguments": {
    "title": "<title>"
  }
}

create_spreadsheet

Creates a spreadsheet, optionally pre-filled with a header row and data rows. Cell values may be formulas ("=SUM(B2:B9)").

Example call

{
  "name": "create_spreadsheet",
  "arguments": {
    "title": "<title>"
  }
}

create_timeline_event

Creates a timeline event dated in the project calendar. Participants and the location are entity names (or aliases); an unknown name fails rather than being dropped -- unless "create_missing_entities" is true, which creates an uncategorized stub entity for any name that matches nothing (so an out-of-order build need not create every character first). An ambiguous or AI-excluded name still fails. "timeline" picks (or creates) a named timeline; omitted, the project's first timeline is used.

Example call

{
  "name": "create_timeline_event",
  "arguments": {
    "title": "<title>",
    "when": "<when>"
  }
}

delete_continuity_rule

Removes a continuity rule from the project by its name.

Example call

{
  "name": "delete_continuity_rule",
  "arguments": {
    "rule": "<rule>"
  }
}

get_calendar

Reads the project's calendar: its months (with lengths), weekday names, era label, and any named eras (a multi-reckoning epoch like Before/After Fall) -- the reckoning every timeline date is written in.

No parameters.

Example call

{
  "name": "get_calendar",
  "arguments": {}
}

get_chart

Reads a chart's data: its kind (bar/line/area/pie), category labels, each named data series' values, and axis titles.

Example call

{
  "name": "get_chart",
  "arguments": {
    "chart": "<chart>"
  }
}

get_conflicts

Runs the validating timeline and the user-authored continuity rules and reports every conflict found: an entity in two places at once, events outside a lifespan, impossible travel, dangling references, broken relative constraints, and violated continuity assertions.

No parameters.

Example call

{
  "name": "get_conflicts",
  "arguments": {}
}

get_map

Reads a map: its regions (with layers, reveal state, linked entities, and sub-maps), pins, tokens, travel routes, scale, and grid.

Example call

{
  "name": "get_map",
  "arguments": {
    "map": "<map>"
  }
}

get_spreadsheet

Reads a spreadsheet as a Markdown table of evaluated values (formula cells show the formula beside the value). Very large sheets are capped honestly.

Example call

{
  "name": "get_spreadsheet",
  "arguments": {
    "spreadsheet": "<spreadsheet>"
  }
}

get_timeline

Reads the project's timeline(s): every event with its date(s) in the project calendar, participants and location by name, plus the named eras. Pass "timeline" to read one timeline; omit it for all.

Example call

{
  "name": "get_timeline",
  "arguments": {
    "timeline": "<timeline>"
  }
}

list_continuity_rules

Lists the writer-authored continuity rules the validator checks: for each, what it applies to, and either the field, whether it must or must not equal a value, and when (a story date or at any time), or the expression it asserts.

No parameters.

Example call

{
  "name": "list_continuity_rules",
  "arguments": {}
}

list_media

Lists the project's media assets: caption, kind (image/audio/video/pdf/other), and asset path.

No parameters.

Example call

{
  "name": "list_media",
  "arguments": {}
}

manage_eras

Adds, removes, or renames a named era (the labelled background bands of story time). "add" needs "start" and "end" dates in the project calendar; "rename" needs "new_name".

Example call

{
  "name": "manage_eras",
  "arguments": {
    "action": "<action>",
    "name": "<name>"
  }
}

set_media_caption

Recaptions a media asset, addressed by its current caption.

Example call

{
  "name": "set_media_caption",
  "arguments": {
    "media": "<media>",
    "new_caption": "<new_caption>"
  }
}

update_calendar

Updates the project calendar. Sparse: only the provided keys change. Note that story time is stored as absolute instants, so changing month lengths re-reads every existing date under the new calendar.

Example call

{
  "name": "update_calendar",
  "arguments": {
    "era_name": "<era_name>",
    "eras": []
  }
}

update_chart

Sparse update of a chart: only the provided keys change. "new_title" renames it; "kind", "categories", "series", "value_axis_title", and "category_axis_title" replace those parts. One undo step.

Example call

{
  "name": "update_chart",
  "arguments": {
    "chart": "<chart>"
  }
}

update_map

Edits a map with one action: add_pin (label, x, y, optional note), move_pin (pin, x, y), add_token (label, x, y, optional color and entity), reveal_region (region, optional revealed=false to hide), or rename (new_title). Coordinates are normalized [0, 1] relative to the base image.

Example call

{
  "name": "update_map",
  "arguments": {
    "map": "<map>",
    "action": "<action>"
  }
}

update_spreadsheet

Renames a spreadsheet ("new_title") and/or sets individual cells by A1 address. "cells" maps addresses to raw text -- a literal, a formula starting with '=' (evaluated by the real engine; the result is reported back), or "" to clear the cell. Provide at least one of new_title / cells.

Example call

{
  "name": "update_spreadsheet",
  "arguments": {
    "spreadsheet": "<spreadsheet>"
  }
}

update_timeline

Renames a timeline container. (Add or edit its events with create/update_timeline_event; remove a whole timeline with delete_object.)

Example call

{
  "name": "update_timeline",
  "arguments": {
    "timeline": "<timeline>",
    "new_title": "<new_title>"
  }
}

update_timeline_event

Updates an existing timeline event, addressed by its title. Sparse: only the keys you provide change (new_title, when, until, description, participants, location); an empty "until"/"location"/"description" clears that field.

Example call

{
  "name": "update_timeline_event",
  "arguments": {
    "event": "<event>"
  }
}