Traceable

Soft-delete one block (recoverable in the app). Deleting a table or ID header cascades to its children, and links to deleted trace targets are marked broken — the same semantics as deleting the row in the editor. atOrder must come from a read issued after the last insert (inserts renumber later rows); the response echoes the deleted row's itemId — verify it hit the intended row. Prefer itemId anchoring.

Replace one block. Identify it by its TraceID (itemId, e.g. FR-003) or by its [[row N]] anchor (atOrder — must come from a read issued after the last insert; inserts renumber later rows). trmContent must parse to exactly one block; page/section breaks in it replace the row's break flags. TraceID renames are not supported — use traceable_trace_id_rename.

Insert one or more body blocks at an anchor: after a TraceID (afterItemId), after a [[row N]] anchor (afterOrder, from a document read), or at the start/end of the body (position; default end). The anchor must be a body row: title-page content is written with traceable_segment_write. Returns the created rows with their new row orders, plus a renumbered marker when the insert shifted existing rows (by: rows inserted, rowsShifted: visible body rows that moved; footer rows below are renumbered too but not counted). IMPORTANT: an insert renumbers every row after the anchor, so row orders from earlier reads/responses go stale — re-read before further order-based calls, or anchor by TraceID (immune to renumbering).

Plan a document not yet written as a placeholder card on a project's board (a Design Phases cell, or a cell of the quality system diagram). Pass projectId, title, optionally documentType, and placement (a cell's phaseId and workstreamId from traceable_board_read, optionally a position, 0 being the top). Calling it twice plans the document twice. To write the planned document, pass the placeholder's cardId as placeholderId to traceable_doc_create. A card that holds a document is not a placeholder: move it with the document's placement instead.

Remove a placeholder card from a project's board. Pass its cardId (from traceable_board_read). It removes only the plan: a card that holds a document is not a placeholder, and no document is deleted.

Change a placeholder card on a project's board: its title or documentType, or move it to another cell with placement. Pass its cardId (from traceable_board_read) and only what changes. To write the planned document, pass the placeholder's cardId as placeholderId to traceable_doc_create. A card that holds a document is not a placeholder: move it with the document's placement instead.

Read a project's board: the Design Phases board of a product or process project, or the quality system diagram of a Quality project. Returns every cell with its phaseId and workstreamId (the cell's address), a label naming where it sits ("Phase × Workstream" on the Design Phases board, "Workstream › Phase › Cell" on the diagram), the cards in it in order (documents and placeholders, each with its cardId), and the documents on no cell. Pass a cell's phaseId and workstreamId as placement to traceable_doc_create or traceable_doc_update_meta to put a document in it, or to traceable_board_placeholder_create to plan a document not yet written there.

The Traceable Markdown (TrMD) format spec and capabilities manifest: row types, block directives, layout directives, segments, property tokens, and paper sizes. Read this before reading or authoring documents.

Archive a document: move it to the project's Archive group, as the app's Archive action does. Its trace links are marked broken so the trace views show the gap, and restoring it in the app heals them. A document under review is refused (finish or withdraw the review first). Archiving an archived document changes nothing. Agents cannot delete documents: a person deletes an archived document in the app, and restores one there too. Use it to retire a superseded document after replacing it.

Create a document in a project. Start from a template: pass templateId to clone an org/system template (header/footer bands, title page, revision + signature scaffolding come along — discover templates with traceable_workspace_templates); trmContent is then APPENDED after the template's body, so read the template first (traceable_doc_read) and do not repeat its headings or scaffold rows; change template rows afterwards with traceable_block_update or traceable_block_delete. To put content under one of the template's own headings (for example an ID grid under "Functional Requirements"), create the document first, read it, then traceable_block_write with afterOrder set to that heading's [[row N]]. Without a template, only default header/footer bands are seeded for any segment trmContent does not provide. A controlled document should end up with a Revision Table, a Reference Table, a Glossary (add its terms with traceable_glossary_add_term) and ID rows for everything that must be linked: see documentComposition in traceable_capabilities. Test records are [[test-plan protocols=""]], [[test-report from=""]] and [[test-summary from=""]], one of each per document; publish the sources before recording results. To put the new document on its project's board (a Design Phases cell, or a cell of the quality system diagram), pass placement with a cell's phaseId and workstreamId from traceable_board_read. To write the document a placeholder card planned, pass placeholderId (a placeholder's cardId from traceable_board_read) instead: the document takes the placeholder's card, in its cell and position. Returns the new documentId and the created rows with their row orders.

Read a document or a template. Both modes return meta.revision (on a full read, revision= on the [[document]] line): pass it as baseRevision on your next content write so it is refused if the document changes in between. mode=outline returns metadata + the body heading outline + titlePageHeadings + landmarks (the row order and kind of the revision table, references, glossary, Test Plan and similar rows, and of each diagram and image row with its caption; a diagram also gives its status) + item counts + the document's references with the referenceId a citation uses (cheap; default when exploring). mode=full returns the content as Traceable Markdown (TrMD): segments as [[segment …]], each block prefixed with its [[row N]] anchor annotation, including ID-grid structure ([[id-header types=…]]). When other documents in the project trace INTO this one, a second text block lists those incoming links, grouped under each source document (its number, name and id) as " -> "; a bounded read lists only the links into the rows it returns. Link cells in the TrMD list a row's outgoing links only. Bound a full read with fromOrder/toOrder (row orders from the outline or a prior read) to load only a section; a range that holds no rows says so and gives the row orders the document spans. Accepts a template id (from traceable_workspace_templates) so you can inspect a template body and its column structure before cloning it with traceable_doc_create.

Rename a document's TraceID prefix in place, rewriting every TraceID (traceable rows, native-table trace cells, and ID-grid id cells). Plain text and other rows without a TraceID are not changed, and the old prefix written as prose inside text is not rewritten. Trace links are preserved — only the human-readable ids change — so you do NOT need to recreate the document to re-prefix it. The document must be an editable draft (published documents are read-only).

Update a document's metadata: name, document number, document type, group, the numberedHeadings toggle, and its placement on the project's board (a cell's phaseId and workstreamId from traceable_board_read, or null to take it off the board). Placement changes no document content and opens no new draft. Turn numberedHeadings on so the app auto-numbers headings — then author heading text WITHOUT section numbers (see the headingNumbering note in traceable_capabilities). Only the fields you pass are changed. To change the TraceID prefix use traceable_doc_rename_prefix (it re-derives existing ids); it is not settable here.

Add a term to this document's Glossary, creating the Glossary row at the end of the body if the document has none (to put it elsewhere, write [[glossary]] there first). Name the term by termId (from traceable_glossary_search) or by its text in term. A term the organisation glossary does not have yet is created from term, description (required then), kind and categories (existing category names). Idempotent: adding a term the Glossary already shows changes nothing. In an organisation under controlled releases this works once an admin turns on Agents can fill a Glossary.

List the organisation glossary a document draws on, or the terms whose term or description contains query (case-insensitive). Returns each term's id, term, kind (definition | acronym), description and categories. Use an id with traceable_glossary_add_term or in [[glossary terms=...]]. In an organisation under controlled releases this works once an admin turns on Agents can fill a Glossary.

Set one ID-grid cell's value, identified by the id-ROW (row.itemId or row.atOrder) and the 0-based colIdx. NON-DESTRUCTIVE: the cell keeps its identity and the row's trace links survive — setting the id column changes the visible TraceID without breaking links (unlike traceable_segment_write). id/text columns take the raw value, and a text column also takes an image as {width=60%} (upload it with traceable_image_upload); test-result normalises PASS/FAIL; checkbox normalises to true/false (true/yes/1/✓ vs false/no/0/✗); dropdown takes one of the column's options (matched ignoring case; any other value is refused). Link cells are NOT settable here — use traceable_link_create instead.

Add a column to an ID grid. Every id-row gets a fresh empty cell. Pass type, optionally insertAt (0-based position; omit to append) and label (omit for the type default ID / Link / Column). Only one id column is allowed per grid. Calling it twice adds two columns. Existing cells and trace links are preserved (unlike traceable_segment_write, which replaces the whole grid and breaks links). Identify the grid by its HEADER row (header.itemId or header.atOrder). To set a CELL's value use traceable_grid_cell.

Rename an ID-grid column: change its header text in place, leaving its type and cells alone. Pass colIdx and label. Use it to correct a mislabeled header (e.g. a default "Column"). Existing cells and trace links are preserved (unlike traceable_segment_write, which replaces the whole grid and breaks links). Identify the grid by its HEADER row (header.itemId or header.atOrder). To set a CELL's value use traceable_grid_cell.

Change an ID-grid column's type, converting each id-row cell to it. Pass colIdx, type, and for typed columns config: { "options": ["Open","Closed"] } for a dropdown, { "op": "product", "sources": [1,2] } for a calculation. Only one id column is allowed per grid. Existing cells and trace links are preserved (unlike traceable_segment_write, which replaces the whole grid and breaks links). Identify the grid by its HEADER row (header.itemId or header.atOrder). To set a CELL's value use traceable_grid_cell.

Upload an image to a document and get back the src to place it with. Pass the image as base64 in content with its name. PNG, JPEG, GIF, WebP or AVIF, detected from the bytes, not the name; SVG is not accepted. At most 3 MB. The result's trmd is : write it in a text row, a table cell or an ID row's text cell with traceable_block_write, traceable_block_update, traceable_segment_write or traceable_grid_cell, adding {width=60%,align=center} after it to size it. Uploading places nothing by itself. A write may only place an image the application holds: a src on another site or a data: URI is refused. Calling it twice uploads twice. In an organisation under controlled releases this tool works once an admin turns it on in Org settings > Releases.

Look at an image in a document you can read. Pass its src exactly as a read of the document shows it (). Returns a reduced copy, at most 512 pixels on its longer side with its metadata removed, not the stored file, together with its name, size and full dimensions (crop percentages are of those). Only an image the document holds can be viewed. Every view is recorded with the document's agent changes, so a reviewer sees what you looked at as well as what you changed. In an organisation under controlled releases this tool works once an admin turns it on in Org settings > Releases.

Attach a Reference Library item — or another document — to this document's reference list, and ensure a Reference Table row exists to display it (created at the end of the body if absent). To put the table somewhere else, write [[reference-table]] there first (e.g. with traceable_segment_write); this tool then uses that row rather than adding a second one. Pass code_or_id (a library item's REF code e.g. REF-00001A, or its id — from traceable_library_search) OR targetDocumentId (a document to cite) — exactly one. The referenced version defaults to the target's current/published version; override with referencedVersion. Idempotent: re-adding an existing reference succeeds without duplicating it. Returns the referenceId, which a citation uses: label in any text (see inlineSyntax.citation in traceable_capabilities).

Extract and persist the plain text of a Reference Library item (identified by its REF code or id) so it becomes searchable via traceable_library_search and cheap to read. Text extraction runs locally (docx, spreadsheets, CSV, and text/markup formats; webpage items are fetched). Returns the number of characters indexed, unsupported=true for types this slice cannot extract (PDF, PowerPoint, images), or noContent=true with a note for a reference that has no file or link (it records a document by its details only).

Return the extracted plain text of a Reference Library item, identified by its REF code (e.g. REF-00001A) or its id. Returns the stored indexed text when available, otherwise extracts on the fly without persisting. Unsupported types (PDF, PowerPoint, images) return empty text with an explanatory note — call traceable_library_index to persist supported text for search.

Find Reference Library items you can access (org-scoped items plus items in projects you are a member of). With query: keyword search across each item's name, REF code, and locally-extracted text (case-insensitive substring — no semantic/embedding search), returning matches with a short snippet around the first hit. WITHOUT query: lists every accessible item — REF code, name, kind (file | webpage), file type, scope (org | project), and whether its text has been indexed. Search only finds text that has been indexed, so if a search comes back empty, list first and check the indexed flag: an unindexed item is invisible to search until traceable_library_index runs on it.

Upload a file (a standard, a manual, a report: any type) to the Reference Library of the document's project, and by default add it to the document's references in the same call. Pass the file as base64 in content with its name; title sets the name shown in the library (defaults to the file name) and number its designation, e.g. "ISO 13485:2016". At most 3 MB; upload a larger file in the app. Returns the REF code, and the referenceId a citation uses: label. Its text is indexed straight away where the type has text, so traceable_library_search finds it. Calling it twice files the file twice; to reference a file already in the library, use traceable_library_add_reference. In an organisation under controlled releases this tool works once an admin turns it on in Org settings > Releases.

Create a trace link between two TraceIDs (traceable rows, ID rows, or table trace rows), resolved server-side within one project, addressed by the pair of TraceIDs: link columns render as TraceID names. It is idempotent on the PAIR, not the direction: if an edge already exists between the two rows in EITHER direction, the existing edge is returned and nothing is written. existingDirection says "same" or "opposite", and on "opposite" a warning explains that no chip was placed because a second edge would be a cycle. When the source row is an ID Row, the link is also written into its link column so the chip SHOWS on the page; placedInColumn says which column took it. The column chosen is the row's first OUTPUT link column, since the target is downstream of the source. If the grid has no output link column it falls back to the first link column, an input column, and a warning says so; pass toColumnIndex to place it elsewhere. If the row has no link column the edge is still created and pinned, and a warning explains why nothing is shown. To remove a link, use traceable_link_delete.

Delete a trace link between two TraceIDs, addressed by the pair as traceable_link_create addresses it. Removes the edge AND the chip from the source row's link cell. Direction is not guessed: if the pair exists only the other way round, nothing is deleted and the error says so, because in a traceability chain the direction carries meaning.

Replace a whole segment with the given TrMD — the primary bulk-authoring tool. Existing rows in the segment are soft-deleted (links to them are marked broken), so use traceable_block_write/traceable_block_update for incremental edits. Author multi-column bands with [[column-start count=N]] … [[column-break]] … [[column-end]] (one rich-text cell per column), and ID grids with [[id-header types=id,text,link]] + a label row followed by [[id-row id=…]] rows (link cells take whitespace-separated TraceID names). The title_* segments are the optional title page; writing to them on a document whose title page is switched off stores the content but it will not render until the page is enabled in the app.

Your organisation's skills: reusable instructions for agents, written and published in Traceable documents. Call this when you connect, and follow the published skill whose description matches the task. Returns each skill's skillId, name, description (when to use it), tags (which name the document types it applies to), the version it comes from and its source document, from the latest PUBLISHED version of each document in the projects you belong to. Load one with traceable_skill_read. includeDrafts adds the skills of open drafts, marked status "draft": those are work in progress, not official. To change a skill, edit its [[skill]] row in the source document with the block tools. When a skill shapes a change you write, name it in that write tool's usedSkills, so the change records which method it followed. Where your organisation allows agents published skills only, drafts are left out. In an organisation under controlled releases this works once an admin turns on Agents read skills.

One skill as a SKILL.md file: YAML front-matter (name, description, and Traceable metadata: title, tags, status, version and source document) followed by the instructions in Markdown. Serves the skill as it stands in its document's latest published version; status "draft" serves the open draft instead, which is not yet official, and is refused where your organisation allows agents published skills only. In an organisation under controlled releases this works once an admin turns on Agents read skills.

Record data in one entry of a Test Plan, Test Report or Test Summary: pass fields as {column: value}. Each record writes its own stage: a Test Plan the decision and rationale, a Test Report the test columns, a Test Summary the baseline (its result and tester come from the report). Entry columns: decision (include | exclude), rationale, result_text, test_notes, samples, location, equipment (one dated register label per line), result (pass | fail | "" to clear; derived from the steps when the protocol has steps), assessment, baseline_notes, resolution (passed | failed | passed_with_deviation | failure_accepted | "" for the derived default). With step (numbered from 1) the fields are that test step's: result_text, notes, result. Same validation and limits as the editor. Evidence is traceable_test_plan_evidence_add. Tester is an electronic signature and cannot be applied by an agent. The row goes to review.

Attach file evidence to a Test Report entry (or one of its test steps). The evidence must be a Reference Library item THIS document references, named by REF code or item id: add the reference first with traceable_library_add_reference. It shows as a chip labelled in the document's citation format. Attaching evidence the entry already holds changes nothing. To upload a new image or file, use traceable_test_plan_evidence_upload. Evidence is a Test Report's: the entries are this document's own record. The row goes to review.

Remove file evidence from a Test Report entry (or one of its test steps). Any item of the project that is on the entry can be named, by REF code or item id, whichever document attached it. The Reference Library item itself is not deleted. Evidence is a Test Report's: the entries are this document's own record. The row goes to review.

Upload a file as evidence on a Test Report entry (or one of its test steps). Pass the file as base64 in content with its name. An image (PNG, JPEG, GIF, WebP, detected from the bytes, not the name) is shown inline in the Evidence column, exactly as an editor upload is. Any other file type is added to the project's Reference Library, referenced by this document, and attached as a file chip labelled in the document's citation format; its text is indexed for traceable_library_search where the type allows (the result says indexed). Evidence is a Test Report's: the entries are this document's own record. At most 3 MB per file. Calling it twice uploads twice. The row goes to review.

Read a Test Plan, Test Report or Test Summary row: the record (its kind, source documents and, for a report or summary, the published version each source is locked to; lockedVersion null means the source is a draft or not locked yet, so results recorded now are not frozen to it), the columns the row shows, and every entry with its protocol TraceID, protocol cells, all column values (decision, rationale, result_text, test_notes, samples, location, equipment, result, assessment, baseline_notes, resolution), its evidence (a file carries its REF code as reference, which traceable_test_plan_evidence_add takes), the tester signature (if signed) and, for a protocol with test steps, each step (numbered from 1) with its text, acceptance criteria and recorded result. Entries are listed in the order their protocols joined the record, the order the row shows; a protocol added or moved later stays where it joined. Use it before traceable_test_plan_entry.

Your threads: the document Discussions in your projects (documentId, name, unread count, last activity) and your direct and group conversations in one organisation (conversationId, kind, name, members, unread count, last message). Conversations are those of your active organisation unless you pass organisationId (from traceable_workspace_projects). Pass an id to traceable_thread_read. Reading never marks anything read for you.

Post a message in a document's Discussion (documentId) or a conversation (conversationId), give exactly one, as you, marked as posted via this agent. Pass replyTo (a top-level message id from traceable_thread_read) to reply under it. To mention someone, write @ and their full name as the people list gives it (for example @Aaron Dowling) in content; that alone mentions them, and mentions (user ids from the same list) may be passed as well. Everyone in the thread sees the message and is notified as for any message, so do not post without being asked to. Not idempotent: calling it twice posts twice. Refused where you could not post yourself (a Discussion needs a reviewer role or above).

Read one thread: a document's Discussion (documentId) or a conversation (conversationId), give exactly one. Returns every message oldest first with its replies (id, author, the agent it was posted via if any, time, text, reactions, the tasks assigned from it, and system lines recording task events), whether you can post, and the people you can mention with their ids. It reads the same messages you see in the Chat panel, including direct and group messages, and leaves them unread for you.

Rename a row's visible TraceID in place (a traceable row or an ID-grid row). The row keeps its database identity, so every trace link into or out of it survives; an ID-grid row's id cell is kept in sync and cached link labels that reference the old id are refreshed project-wide. Use this instead of delete-and-reinsert, which would break links. To renumber a whole grid, call this once per row (re-read afterwards is not needed — anchor by TraceID).

Survey a project before opening any document. include=structure (default) returns the group/document/outline tree: each document's number, ID prefix, type, status, version, item counts and H1-H6 headings — use it to decide what to read. include=links returns the document-to-document trace graph instead: which documents link to which, how many trace links each edge carries and how many distinct source rows they leave from, including one-to-many relationships and links to external documents. include=both returns the two together. Returns Markdown by default (token-efficient, readable); pass format=json for the structured object.

Your workspace: every organisation you belong to (id, name, org number, your role), each with the active projects in it you are a member of (id, name, project number, your role, document count, last-updated time). Start here — a projectId from this listing is the input to traceable_workspace_map. Organisations you belong to but have no project in are listed with an empty projects array: their organisationId is what traceable_library_search and traceable_workspace_templates take. Projects with no organisation come back under projectsWithoutOrganisation. Pass organisationId to narrow to one organisation, which is how you disambiguate same-named projects across organisations.

List the document templates available to you (system templates plus your organisations'): id, name, TraceID prefix, document type, band previews, body outline, and the owning organisation (organisationId + organisationName; null for a system template). Pass a template's id as templateId to traceable_doc_create to clone its styled header/footer bands and body scaffold.