Generated Documents
Generate a business requirements document or a software requirements specification from the project's own record, edit the opening page Heimdall drafts, render it again, put it to the project manager, and share the final copy with the client.
By the end of this page you will know how a document is generated from the project's record, what it reads and what it leaves out, how the opening page is drafted and edited, how a draft is rendered again, how the project manager's approval makes a copy final and what that does to the earlier copy, what the client sees, and how a document is superseded or deleted.
A generated document is a file the project writes from its own record. You choose a kind (the business requirements document the client signs, or the software requirements specification the team builds against), a title, a file (PDF or HTML) and a scope: the record as it stands, approved records only or drafts included, or a frozen baseline so the document prints exactly what the client signed. The render runs in the background as the person who asked, reading every module through the same services and permissions that person has, so a module they may not see is left out rather than leaked. When nobody wrote the opening page, Heimdall drafts it from an outline of what the document prints. The result is a draft with a file you download or open in the browser. You edit the title, the scope or the opening page and render again as often as you like; each save keeps the version before it. The Document approval moves a draft to final, and a final copy supersedes the kind's earlier final copy on the project. A client guest sees the final copies and nothing else.
Before you begin
| To | You need |
|---|---|
| See the documents and open one | document:view-any and document:view; a client guest sees the final copies |
| Generate a document | document:create |
| Edit a draft's title, scope or opening page | document:update |
| Render a draft or a failed document again | document:render |
| Put a draft to the project manager | document:finalise |
| Approve a document | To be named by the project's Document approval policy; the project manager role by default |
| Supersede a final copy | document:update |
| Delete a document | document:delete |
| Have Heimdall draft the opening page | The project's AI assists on, and room left in the team's AI budget |
A document prints what the record holds the moment it renders. A record still in draft is left out unless the document asked for drafts, so approve the epics, requirements, rules and use cases through their own approval first if the document is for the client.
Open the page
Documents in the project's sidebar opens the page; the badge on the entry counts the documents you may see. The list shows each document's title with its reference (BRD #2, SRS #1: documents are numbered within their kind on the project) and who asked for it, the kind, the status, the file format with its size once rendered, when it was rendered and when it became final. Sort by title, kind, status, file, the rendered date or the final date; narrow the list by kind or status, or search by title; Clear Filters drops every filter. While a document is rendering the list refreshes itself every few seconds, so the file appears without a reload.
An empty project reads No Documents Yet and, to someone who may generate: Generate the first one with the button above: Bragi lays the BRD or the SRS out from the record as it stands, Heimdall drafts the opening page, and the file is ready to read in a moment. Ask Heimdall in conversation and it generates one for you.
Generate a document
Press Generate and pick the kind from the menu; each kind says in a line what it prints and for whom. The editor opens with the kind's name as the Title, which you may change (the client reads it on the cover and on the file they receive), and the File set to PDF; choose HTML for a page you will paste into a wiki or read on a phone. Under What it reads, pick a Baseline to print exactly the records a frozen baseline holds, or leave it on The record as it stands; the picker appears only once the project has a frozen baseline. Tick Include records still in draft for a working copy inside the team; leave it off for anything the client reads, so only approved records are printed. The last fieldset is the opening page, named after the kind (Executive summary for a BRD, Introduction for an SRS): leave it empty and Heimdall drafts it when the document renders, or write it yourself and it is kept as written.
Press Generate. The document is written as Rendering, numbered within its kind, the toast reads Document queued and names it, and the render starts in the background as you. A few seconds later (longer when Heimdall writes the opening page) the status turns Draft and the file is there to read. A render that could not finish turns the document Failed and keeps the reason; see Render again.
Rendered as you, from what you may see
The render reads the project through the same services your own screen reads, under your permissions on the project. A module your role may not open is left out of the document rather than printed; a module nobody filled prints a line saying nothing is recorded yet.
Read a document
Open a row for the flyout: the reference, kind, status, file format and, once approved, the version as badges; the title; a line on where it stands; Download and Open (the same file, saved or shown in a browser tab) once there is a file; the approval bar; the opening page as written or drafted, or Not written yet; What it reads (the baseline or The record as it stands, and whether drafts are included); when it was rendered, by whom and the file's size; when it became final; when it was created; the Versions of the document itself; Activity; and Delete. Download in the row menu serves the same file. The file downloads under the document's title.
A Rendering document shows Bragi is writing the file; it appears here in a moment without a reload. in place of the buttons; a Failed one shows the reason the render stopped.
Edit the opening page and the scope
Edit Document in the row menu or Edit in the flyout reopens the editor on a draft or a failed document. Change the title, the file format, the baseline, whether drafts are included or the opening page; the kind never changes, generate another document for the other kind. Save & Render Again writes the change as a version, renders the document again with it and replaces the file; the toast reads Document updated. Heimdall drafts the opening page again only when you emptied it; a page you wrote or edited is kept exactly as it reads.
A document that is in review, final or superseded does not change: the editor refuses with A document that is Final does not change; generate a new one instead. Generate a new one of the same kind; when it is approved it supersedes the old copy.
Render a draft again
Render Again in the row menu or the flyout renders a draft or a failed document once more with exactly what it holds. Use it when the record changed since the file was written, when a render failed, or when the opening page was emptied so Heimdall writes a fresh one. The document reads Rendering until the new file replaces the old; nothing else about it changes.
A render fails when the person who asked for the document is no longer on the project, when the
file could not be written, or when Heimdall could not be reached or answered with nothing readable;
the reason is kept on the document and document.failed goes out. Rendering again clears it.
Put a draft to the project manager
Open a rendered draft's flyout. The Approval bar offers Submit for review once the document has a file; a document still rendering or failed cannot be submitted. Write a few lines for the approvers under Summary and confirm. The document moves to In review, the approvers of the project's Document approval policy are told (the project manager role by default, under the Any one approver rule, with seventy-two hours to answer and a reminder after a day), and the draft stops changing until they answer.
What the approval does when it carries:
- The document becomes Final at version 1, stamped with when it was approved and the revision that was reviewed, and with the date it became final.
- The kind's earlier final copy on the project, if there is one, becomes Superseded and points at the new copy; a client who opens it sees it is no longer current.
document.finalisedgoes out besidedocument.status_changed, with the approval that carried it and the version reached.- The copy appears to the project's client guests, under Documents in their own sidebar.
A rejection returns the document to Draft; the approver's reason is on the request, and you edit the draft, render again and resubmit. A request for changes holds the request until you resubmit; the next round asks the same approvers again. Withdrawing the request from the bar returns the document to draft as well.
The approval pins the page, not the record
The approval writes a version of the document's title, scope and opening page and marks the file final. It does not freeze the record the document printed: a requirement approved after the render is not in the file. Print the client's copy from a frozen baseline when the scope must be exactly what they signed.
Supersede or keep a final copy
A final document is never edited and never rendered again; it is what the client received. When a newer copy of the kind is approved, the earlier one is superseded by itself. To retire a final copy by hand, without a successor, choose Move to → Superseded in the row menu or the flyout; the toast reads Document moved. A superseded document stays readable, to the team and to the client, with every stamp it carried. The moves through Rendering, In review and Final belong to the render and the approval engine, and the menu does not offer them.
Delete a document
Delete Document in the row menu or Delete in the flyout opens the confirmation, naming the document and what goes with it: the file, every version it kept and its activity history; the records it printed stay as they are. A document that is with its approvers is not deleted until they decide or the request is withdrawn. A final copy a client received is better superseded than deleted, and the confirmation says so.
All the fields
What happens next
- Generating a document emits
document.createdat once; the render that follows emitsdocument.renderedwith the file's format and size, ordocument.failedwith the reason. - Editing a draft emits
document.updatedwith the columns that changed and renders the document again; rendering again emitsdocument.renderedordocument.failedonce more. - The approval engine emits
approval.requested, the verdicts anddocument.status_changedon every move; the approval that carries addsdocument.finalisedwith the approval and the version. - Superseding emits
document.status_changed; deleting emitsdocument.deleted; putting an earlier version of a draft back emitsdocument.restored. - A final copy is listed to the project's client guests and served to them on request; the sidebar badge counts it for them from that moment.
- Every save of a draft writes a version; the history flyout compares them and puts one back, which does not render the document until you ask.
Heimdall on this page
Heimdall has two parts here. In conversation, "Generate the BRD for the Customer Portal from the signed scope" asks for a document the way the Generate menu does, and "What does SRS #1 say about password reset?" reads a rendered document back to you; the document is listed as asked for by you and rendered under your permissions.
The second part is the opening page. When a document renders with that page empty and the project's AI assists are on, Heimdall is given the project, the client and an outline of what the document prints (the sections, their counts and the first names in each) and asked for two to four paragraphs of plain text: what the client is and needs, what the project builds and for whom, what the document covers and how it is organised, and what the reader is asked to do with it. It is told to rest on the outline alone, to invent no number, name or date that is not in it, and to name no technology the record does not. The call is filed in the team's AI ledger as Document draft, and a team whose budget is spent gets a failed render that says so rather than a silent blank page. A document whose opening page is already written costs no model call at all, so write it yourself to keep Heimdall out. The draft is kept on the document as text you edit like your own words; nothing Heimdall writes reaches the file without a person able to change it first.
From the API and MCP
Documents API
A project's documents with their filters, one with its scope and prose, the file, generate, change, render again, supersede, delete, the versions, and the submit door.
list_documents and get_document
An agent reads which copy is final before it answers a client, and reads a rendered document as plain words without downloading it.
generate_document
Ask for a BRD or an SRS as the token's holder; the document renders under their permissions and the person reviews it.
document.* events
Created, updated, status changed, rendered, failed, finalised, restored and deleted.
Permissions
| Action | Permission |
|---|---|
| See the documents and open one, download it | document:view-any, document:view; a client guest sees the final copies only |
| Generate a document | document:create |
| Edit a draft, supersede a final copy | document:update |
| Render a draft or a failed document again | document:render |
| Submit a draft for approval | document:finalise, as staff |
| Approve | Named by the Document approval policy; approval:decide over the API |
| Delete a document | document:delete |
| Read and restore the document's own versions | document:view, document:update; staff only, and only on a draft or a failed copy |
Frequently asked
The record changed after the client got the final copy. Does the document update? No. A final copy is what the client received and never changes. Generate the kind again, edit the opening page if it needs new words, and submit it; its approval supersedes the earlier copy and the client sees both, the current one marked as such.
Why is a module missing from my document? The document reads the record as you may read it. A module your role does not open on the project is left out; a module nobody filled prints that nothing is recorded yet. A record still in draft is left out unless you ticked Include records still in draft.
Can I write the opening page in another tool and paste it? Yes. The field takes plain text with paragraphs separated by a blank line; markup is printed as written. Keep it under the limit of the field and Heimdall never touches it.
The render failed with a message about the budget. The team's monthly AI budget is spent, so Heimdall could not draft the opening page. Write the page yourself and render again, which costs nothing, or ask whoever manages the budget to raise the cap under AI settings.
A guest says they cannot see the document I sent them. A client guest sees final and superseded copies only. A draft, a failed document or one in review is the team's working copy until the approval carries; check the status in the list.
Related
- Business requirements document: what the BRD prints and who signs it.
- Software requirements specification: what the SRS prints and how the team uses it.
- Approvals: the Document approval policy, the inbox and the verdicts.
- Baselines: the frozen scope a client copy is rendered from.
- Revisions and versions: every save of a draft, compared and put back.
- Documents shared with you: the client's side of the page.
How is this guide?
Last updated on
Documents
The documents a project generates from the record its team wrote once: the business requirements document the client signs and the software requirements specification the team builds against, each rendered, reviewed, approved and shared from one page.
Business Requirements Document
What the BRD a project generates prints, section by section, where each section is read from, what the executive summary and the sign-off page ask of the client, and how to render the copy the sponsor signs.