Append a new event to the project's timeline.

Args: task: Short imperative title (e.g. "Add activation engine"). summary: One or two sentences describing what was done. reason: Why this change was made. Strongly encouraged — this is what turns NWT from a log into a history. files: Project-relative file paths this event touched. tags: Free-form labels (e.g. ["memory", "optimization"]). parent: Id of the preceding event in the linear chain, or null to start a new branch.

Returns: The persisted event as a dict (including its allocated id and timestamp).

Search the timeline.

Args: query: Substring to search for (case-insensitive). Matched against task, summary, reason, file paths, and tags. limit: Cap on the number of results. search_files: Include file paths in the search. search_tags: Include tags in the search.

Returns: A list of matching events, ordered by id ascending. Each event is a dict; see create_event for the field set.

Return a compressed project story.

The story contains: * project name and first/last event timestamps * up to max_milestones milestone events * the file that changed most often (the "spine file") * all decision events (those with a non-empty reason)

Returns: A dict mirroring the structure of :class:ProjectStory, plus a human-readable text rendering for direct LLM consumption.

Explain why a file exists.

Args: file_path: Project-relative path to the file (e.g. activation.py).

Returns: A dict with keys file, created_in, modified_in, events, reason and a human-readable text rendering.

Example: >>> explain_file("activation.py") { "file": "activation.py", "created_in": 23, "modified_in": [45, 67], "reason": "Improve graph retrieval performance.", "text": "activation.py\n created in event 23\n ..." }