Creating documents

The three ways to start a document in Alchex — from scratch, from a marketplace template, or by uploading a file you already have.

There are three ways to get a new document into Governance: start from a blank one, download a template from the Marketplace, or upload a file you already have. All three land in the same place and follow the same lifecycle.

Who can create

Creating a document needs author access in the team the document will belong to. Owners and workspace admins qualify too. A Reader who tries is refused with "You do not have permission to create documents", and the New button is hidden from them rather than failing after the fact.

From scratch

Go to Governance → New. One popup opens, and it asks what the record is called and what kind it is — plus which team it belongs to, on the one occasion that is genuinely an open question.

The type is a dropdown, and it holds six: Policy, Procedure, Instruction, Manual, Control and List. It opens on the whole list — there is no "more types" behind it — and it starts on Policy, so a policy takes no click at all. Every one of them mints a code — PLC-, PRC-, INS-, MAN-, CTL-, LIST- — so whatever you create is citable the same way. (Every one of them counts per team, so a code names both the kind of record and the team that answers for it: PLC-HR-003, LIST-HR-001.) The names are the whole explanation — nothing is printed underneath the field, and the record shows the code it was actually given as soon as it opens. The first four create a normal document with that type already set. Control creates a document that is audited — it opens in the same editor and follows the same approval flow, and carries an audit rail on its page. A control is the one type that is not blank on arrival: Alchex drafts its plan from the name you typed, so it opens with numbered checks, benchmarks, scope and the evidence it will ask for. That takes a few seconds, and the button says Drafting this control's plan… while it does; if the draft cannot be written, the control is still created with the same four-part skeleton. See Controls and evidence. List creates a register, a table of records instead of an editor. To point a document at something in a connected system you do not create a record at all — you cite the source, from the picker's Connectors row. See Connectors as references.

The team is only asked when it is a real question. If you are working inside a team, the popup says nothing about the team at all: it creates the record in the team you are standing in, which the sidebar and the address bar already name — confirming a pre-filled dropdown, or reading the team back to you as a sentence, is a step that asks you to agree with yourself. If you are on All teams, there is nothing to derive, so the field appears: it lists only the teams you belong to and can create in, starts empty, and Create stays greyed out until you say which team the record is for. That is the case where the team used to be decided for you, out of sight, and it is the reason the field exists at all.

Where the field is shown, you can change it before you create. Afterwards the record can still be moved — see Moving one to another team — but the code it was minted with is already based on the team you chose, so it is worth a glance.

Nothing is saved when you open the popup. The record is created only when you click Create, and Create stays greyed out until the record has everything it needs — a name, and a team when you were asked for one. Opening it and cancelling leaves no trace in the list — and nothing you chose is remembered the next time you open it.
The name is required and capped at 120 characters — the same limit every record in the workspace has; you can rename later from the record's own page.
Bringing in a file you already have is not part of this popup. Drop it anywhere on the Governance page instead — that route names the record from the filename, so there is nothing to type. See below.

Once you click Create, Alchex opens the new record and sets the following for you:

Field	Value on creation
Status	Active — every record is Active from the moment it exists; Archived is the only other state
Version	v1 (nothing is published yet)
Owner	You — your name from your signed-in account, not from anything you type. The same for every kind, controls included
Type	The type you chose
Code	Minted automatically from the type and team. The popup does not show it in advance: the code is assigned when the record is created, and the record itself is where you read it
Team	The team stated in the popup — the one you were working in, or the one you chose on All teams. Your choice is re-checked when the record is created: a team you are not a member of is refused and the record lands in one of yours instead, so it can never end up somewhere you cannot open it

You cannot set the status, version or owner yourself at creation time. The server decides all three. A version is always one plain number — v1, v2, v3 — on every kind of record, everywhere in Alchex; a document that arrives with a version written any other way (an older 1.0 form from an import, say) is read as its whole number and stored as that, so a list never shows two ways of counting side by side.

Every type in the popup creates the same thing. A control is not a different kind of object that happens to look like a document — it is created by the same act, so it arrives with the same code, the same owner, the same v1, the same first draft and the same version history as a policy does. The audit rail is what a control has in addition, never instead. That is why the table above needs no per-type column, and why a change to what a new record starts with reaches controls at the same moment it reaches everything else.

Naming, type and code

A name is at most 120 characters, and that is the same limit everywhere: a document or a register, typed into the create popup or into the title on the record's own page. It is not an arbitrary ceiling — it is roughly what the document's title bar can show in full, so a record's name is something you read rather than something you hover to find out. Longer text belongs in the document, not in what the document is called. An uploaded file whose filename runs past the limit is trimmed to fit rather than refused; rename it on arrival.

The type is chosen at creation, and it drives the document code, which is assigned automatically and follows a per-team scheme — a prefix for the type, your team's code, and a running number. The type can still be changed later in the document's side panel, which re-mints the code.

Every type has a code of its own, and no two types share one. That is what makes a code a usable identifier: PLC- policy, PRC- procedure, INS- instruction, MAN- manual, FRM- form, REC- record, DOC- the catch-all, CTL- control, EXT- an uploaded file, LIST- a register. Whatever a row's Type column says, its code carries that type's prefix — the two are read off the same fact, so one can never contradict the other. Codes are unique inside a workspace: quote one to an auditor and it names exactly one record.

Why six and not more. Three older types — Form, Record and the catch-all Document — are no longer offered when you create something. A form and a record are what a register is for: a form is a blank you fill in each time, and a record is the filled-in result, and both are better kept as rows you can count and filter than as prose. The catch-all was a way of not deciding.

Nothing you already have was changed by that. Documents typed Form, Record or Document keep their type and their code, still appear in the list and its filters, are still referenceable from other documents, and can still be set to any of those types from the document's own side panel. The narrowing is on the create popup only.

Three limits to plan around:

Once a document is published, the type and code are fixed. The panel says so: to reclassify it, supersede the document with a new one.
While a document is in review, the type is locked until the review closes — other records cite the document by its type and code. The document's text and its name stay editable; a rename applies from the version after the one under review.
A Control's type never changes: the document is the control's definition, so converting it to or from another type is refused while the control exists.

From a Marketplace template

Marketplace holds prepared documents and agents mapped to the clauses of the standards in your catalog. Go to Marketplace, use the Documents tab or search by clause, topic or name, and open the item. You can read the outline and preview the body before committing.

Click Download v… to copy it into your workspace. Before it is created you can:

Choose the destination team. You must have author access in that team; picking a team you do not belong to is refused, never quietly redirected.
Rename the copy. The rename applies to your copy only; the catalog item is untouched.
Answer the template's questions. Templates carry their own fill-in questions, and a conversation gathers them as it drafts: your answers are substituted before the document is created, so the copy arrives already personalised. A question you skip leaves the original placeholder in the text exactly as the author wrote it, to fill later by editing that sentence. Adopting straight from the marketplace asks only for a name and a team — see Templates and the marketplace.

A question that asks where you record something — where completed training is written down, where exceptions are logged — is answered by pointing at one of your registers rather than by typing its name, so the document cites a record instead of describing one. You can still type an answer, import a table as a new register, or leave it for later. See Templates and the marketplace.

Pointing at the register loses you nothing in return: the citation is indexed with the rest of the body under the register's name, so the finished document is still found by searching for it, and the assistant reading the document can see what it rests on. See References.

The copy arrives Active at v1 with an unpublished working draft, owned by you, and remembers which catalog item and version it came from. Its body starts with the content itself — the title is the document's name, never repeated as a first heading, and the template's own note about being a template is not carried over either (see Templates and the marketplace). Downloading the same item again creates a second, separate copy — it does not update the first one.

The copy arrives already typed. Every template declares what it is — a Policy, a Procedure, a Record or a Manual — and the copy is created with that type rather than the catch-all Document. So it carries the code prefix for its type (PLC-, PRC-, REC-, MAN-) and files itself under the right heading in the Governance list's Type filter without you setting anything. The marketplace card shows the same word before you download, so what you browsed and what lands agree. You can still change the type afterwards in the document's side panel, under the same rules as any other document — see Naming, type and code.

Some templates arrive with their processes built in. A procedure template that ships its processes installs them with the copy in the same step — the recurring work its sentences describe, already written as processes with their own on/off switches, no AI involved. The cadence and "who decides" answers set the schedule and the decider of those processes; an unanswered question leaves its process installed but switched off, naming the sentence it waits on, until you fill that bracket. See Templates and the marketplace for the rules.

If the template was linked to clauses, those clauses also come into scope for the owning team, so the new document shows up in readiness views straight away instead of sitting unlinked. See Controls and evidence.

A document can also be born from the compliance record: the attach picker's Write a new document creates a draft with the clause you were on already in its audit scope, then opens it in the editor — and any change to a document's declared scope, wherever it is made, is logged on the record's activity ledger with who made it. A scope declared against a standard that is certified as an extension of another is filed under the base framework's clause, which is the one record both standards read — so a document written for the extension counts for its base framework too, and is never asked for twice. See The compliance record.

By uploading an existing file

If the record already exists outside Alchex, drag it onto the Governance page. You can drop Word (.docx), Markdown, PDF, Excel (.xlsx) and CSV files — up to 20 files at a time, 25 MB each. An import queue appears where you confirm before anything is created, and you can cancel or retry an individual file.

Word and Markdown files are converted into editable Alchex documents. PDFs stay as the original file, readable in the app but not editable. Importing needs the same author access as any other create.

A spreadsheet does not become a document — it becomes a register. Alchex reads the file's first sheet that has rows in it (so a cover page is skipped), treats the top row as column headings when it looks like headings rather than data, and works out each column's type from the values underneath it: dates become date columns, numbers become number columns, a short repeating set of words becomes a list of choices. The rows come in already confirmed, because you chose the file — and each one remembers which file it came from.

Two limits, and the queue tells you when it hits either rather than trimming quietly: 1,000 rows and 50 columns per file. If your spreadsheet is bigger, the queue says how many rows came in out of how many the file held, and names the columns it left out. A .xls file — the format Excel used before 2007 — is not read; re-save it as .xlsx first.

A PDF is the exception to the type picker: the import queue labels it Becomes an External document and offers no choice, because a file you did not author has exactly one type.

Full behaviour, including what happens to formatting, how uploaded files are stored, and how to replace one with a newer edition, is in External documents.

What happens next

Whichever route you took, the new document is live in your team from the moment it exists — active at v1, readable by everyone on the team, including Readers. It is not hidden pending a first approval; approval is what mints v2. Write it in the editor, then hand it over through Submit and approve.

It is citable straight away: from that moment another document can reference it by name, and the reference is resolved against this document itself rather than against a list — so it keeps working however many documents your workspace grows to hold. See References.

It is also writable straight away. A new document is prepared for editing as it is created, so opening it puts you in the editor with no waiting step — and a document made before this, or one whose preparation did not finish, is prepared the first time somebody opens it instead. Either way there is nothing to run and nothing to wait for.

Removing one you did not need

Retiring a document means archiving it. Choose Archive document from the … menu, or right-click its row in the Governance list — where the action reads Archive too. It needs author rights on the document's team, the same rung as editing it.

The document leaves the working list and everything is kept: every version, every approval, every stored file. It opens read-only behind a banner, and Restore — on that banner, or on the archived row's menu in the list — brings it back.

A draft that never became a record can also be deleted from its row in the Governance list: permanent, Owner-only, behind its own confirmation. Published and control-backed documents refuse — nothing can destroy a record. See Activity and archive.

One thing stops it going through, and one thing no longer does:

Being a control's definition still refuses. A control's document is retired with its control, not on its own, and the refusal says so and points at the control.
Anything that cites it does not. Another document's text, or a control's instructions, pointing at this one used to make the confirmation list what depended on it and refuse. That is gone: the removal succeeds, and every chip citing the document picks up a red dot where it is written, keeping the document's name, with Rebind on the chip for pointing the sentence at a live record. Restoring the document clears those dots. See References.

Removing several rows at once is settled row by row. When the batch finishes the selection clears and the outcome line says how many went, how many could not, and the reason the server gave — with Select the N skipped to tick the refused rows again.

Deleting a control is the one place a document is still destroyed rather than retired, because the control, its agent and its definition document are torn down as one unit. When that happens, anything attached to the document as proof is detached in the same act — the sources themselves survive, and nothing is left pointing at a record that is gone. See Controls and evidence.

Moving one to another team

The team is chosen for you at creation, but it is not fixed. Select rows in the Governance list and choose Move to team… to hand them to another team you belong to.

The record does not travel alone. A move carries everything whose owner is that record: if the document is a control's definition, the control and its agent go with it. That matters because access is decided by team on every one of them separately — anything left behind would be invisible to the team that now owns the document and still visible to the team that no longer does.

Two things a move deliberately leaves where they are:

Proof that merely points at the document. A connected-system snapshot cited by three documents belongs to whoever created it, not to whichever of the three moved last.
A duplicate the destination already holds. If the target team somehow already keeps its own proof of this document, the move still goes through and that one row stays put, rather than the whole move failing on a collision.

Everything else follows the ordinary rules: people on the old team lose sight of the record, people on the new team gain it, and the activity log keeps the history either way.