Using the editor

The editor is where you do the day-to-day work: browsing, reading, and editing needs, and understanding how your change moves toward "built." It is the same editor in both flavors.

The editor tour

The editor has three regions: a tree/filter on the left to navigate documents and needs, the content in the center, and per-need detail inline. A read/edit toggle switches between reading the rendered document and editing it in place (WYSIWYG). Use find/filter to jump to a need by id, title, type, or status.

Editing preserves your place: every action keeps your scroll position and cursor/selection, so you never lose context when you save or switch modes.

Writing and editing needs

Add a document, then add needs to it. Each need has a type, an id, a status, and the fields your schema defines. Edit a field or the body and save — TheoWorks writes a minimal RST diff back to the file. Only authored needs are editable; generated/imported needs are shown read-only (see Provenance in Core concepts).

Linking and traceability

Connect needs with typed links (for example satisfies or verifies). The editor renders the resulting traceability graph, and flags links whose target does not exist (dangling targets) so you can fix them.

Validation and workflows

As you edit, TheoWorks checks each need against the schema and shows findings — a missing required field or link, or an illegal status transition. Status changes follow the workflow your schema declares (for example draft → review → published). Resolve findings inline; a CI build can gate on the same rules.

The Git lifecycle

Your edit is Saved to the working file first. To share it, commit it to Git history and push to your remote; CI then builds it (validating and rendering the needs graph). If you saved a change but validation or the rendered graph looks stale, it is almost always because the change has not been built yet. This is the change lifecycle from Core concepts, made concrete in the UI.