Core concepts

Six ideas explain how ASTra behaves. Once you know them, every tool and command makes sense.

Documents, sessions and saving

A .docx file is a zip archive of XML parts. ASTra reads it entirely in memory and never unpacks it to disk.

Through the MCP server you work in a session. open_document returns a session ID; every later call uses it. Your edits live in the session until you call save_document, which validates the result and writes the file. close_document ends the session. The server keeps a limited number of open documents and closes idle ones, so reopen a document if a call reports that the session has expired (E_SESSION).

The command-line tool has no sessions. Each command opens the file, does its work and, for editing commands, saves the result.

Node IDs

Every paragraph, table, cell and image gets an ID such as 3FC95CAC. You edit by naming the node, not by counting lines or characters, so an edit cannot land in the wrong place just because text above it changed.

• Get IDs from inspect (all nodes) or search (nodes that contain some text).
• IDs can go stale after you reopen or edit a document. Take them from a fresh inspect or search.
• Nodes you create during a session get IDs that start with _bk_new_, and the batch result lists them in createdNodeIds.

The outline (TOON)

Reading raw Word XML is slow and wasteful, especially for an AI model. ASTra instead gives you a compact table, called TOON (Token-Optimized Outline Notation), with one row per node: its ID, style and text.

You choose how much detail to read with --fidelity: compact (smallest), standard (the default) or full (everything about a section; it requires a section to be named). You can also read one section at a time, which keeps the amount of text small even for long documents.

Batches are all-or-nothing

You change a document by sending a batch of typed operations. ASTra applies them in order. If any one fails, every earlier operation in the batch is undone and the document is exactly as it was. A single edit is just a batch of one.

This is what makes it safe to let an AI agent make several related changes at once: it never leaves a half-finished edit behind.

Validation before saving

Before any file is written, ASTra checks every changed XML part against the Office Open XML (ECMA-376) schema. A document that fails is refused with E_VALIDATION and a remedy that says how to fix it, and the original file is left alone. You can run the same check at any time with validate.

Validation proves the file is well-formed and schema-valid. It cannot judge whether an edit is the right one, so review important documents.

Revision history

ASTra keeps a revision history in a hidden .astra folder beside the document. The MCP server records a revision every time save_document succeeds. The command-line tool never creates a history on its own: you opt in once with astra history report.docx --init, which records the current file as the starting point.

With a history in place you can list revisions (history), preview going back (preview-revert), go back (revert) and re-apply what you reverted (redo). A revert is recorded as a new revision, so nothing is erased.

Where files can be touched

The MCP server only reads and writes inside the folders you pass with --allowed-dir. A path outside them, including one reached through a symbolic link, is refused with E_SANDBOX. See Security and privacy.