Rendered from docs/interfaces/headwater-new.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

headwater new

Synopsis

headwater new <kind> --title <text> [--summary <text>] [--relates <relation=identifier>] [--facet <facet=value>] [--directory <path>] [--now <date>] [--root <path>]

The command proposes and writes one document whose kind, shelf, facets, sections and identifier come from the resolved taxonomy.

Description

The command decides the complete artifact before it writes any file. It derives engine-owned fields, accepts a title and declared facet values, and can add scaffold-created relation edges.

The command writes provenance: {warrant: asserted} into each document, because nobody has accepted the document yet. It writes no other member of the provenance block. A person who accepts the document sets warrant: accepted and adds their name in accepted_by.

A relation that declares reciprocal: required needs one half on each of its two documents. When the new document opens at a state whose role is initial, such as draft, the command writes nothing into the target document. The target document owes its half only when the new document leaves that state (HW-DR-0086). For each owed half, the report prints one line in this form:

the far half `<relation>` is owed by <target path> once this document leaves `<state>`, and `headwater check --fix` writes it then

While the new document stays at its initial state, headwater check reports no finding for the owed half. When you move the new document to a state whose role is not initial, the check reports relation.reciprocity.missing on it. Then headwater check --fix writes the far half into the target document.

When the new document does not open at an initial state, the command writes the far half into the target document at once. The report then names the path that it wrote.

The command writes no far half of a reciprocal: symmetric relation, at any opening state (HW-DR-0101). A symmetric relation is its own inverse, so the half in the new document states the edge. A far half in a live target would make lifecycle.dependency.on_initial report a live document that rests on a draft. The report prints one line in this form:

the relation is symmetric, so this half states the edge from both ends and <target path> is not edited

The command sets no state on the target of a relation that declares on_target.set_state, such as supersedes, at any opening state (HW-DR-0101). When the new document leaves its initial state, lifecycle.state.not_set_by_edge reports a live target that is not at the state the relation sets. Then headwater check --fix writes the state and its stamp. The report prints one line in this form:

the relation sets `<state>` on <target path>, and this run does not: `lifecycle.state.not_set_by_edge` reports it once this document has left its initial state, and `headwater check --fix` writes it

Where the kind binds a language regime that holds prose to something, the report states the regime. It also states whether headwater check has a mechanical rule for its controlled-language and profile pair. It states the count of retired terms that regime names, and any construction a voice regime forbids for the kind. It never names a skill or a file outside the corpus. The engine reads no harness layout.

It never overwrites a document, and it never overwrites a claim. A kind whose scheme allocates reconcile-first gets one file of the identifier claim store, written before the document and holding the path of the document. That file records what the run minted, so an allocator on another branch reads a value this tree does not yet hold. The command writes the document and appends one capture-cost reading. If the document lands but the reading does not, the command reports the line to append and exits non-zero.

A relation can name a kind that has no identifier scheme. For such a kind, the command refuses and prints two lines to add under add: in .headwater/overlay.yml. The first line declares a minted-once scheme with the pattern {namespace}-<KIND>-{slug}. The second line is kinds.<kind>.identifier. The scheme takes the namespace of the first scheme in the lock that has one. When no scheme has one, the lines show ACME, and the message tells you to replace it. The command changes the name and the pattern until they do not clash with a scheme in the lock. When every candidate clashes, the command prints no lines and tells you to declare a scheme yourself. It never writes the overlay.

Preconditions

The repository must have a readable consumer declaration, resolved taxonomy lock, corpus and configuration. The requested kind must exist in the resolved taxonomy.

The title is required. A supplied relation must be declared as scaffold-created, connect permitted kinds and resolve at its target. A supplied facet must be required by the kind, must not be one that a declaration decides, and must use a permitted value. The identifier the run mints must be claimed by no document and by no file of the claim store.

A shelf whose path puts a glob before a fixed file name, such as docs/modules/*/README.md, does not decide the directory. For a kind on such a shelf, --directory is required. The directory must be relative, must contain no ., .. or empty segment, and must make a path that the shelf claims. No segment can hold *, ? or [, because the command reads the directory as a literal path and not as a glob. On every other shelf, --directory is refused. A shelf whose path is one file, such as docs/INDEX.md, takes that path, and the command refuses when the file is already there.

Options

Option	What it does
<kind>	Selects the document kind.
--title <text>	Supplies the document title and name facet.
--relates <relation=identifier>	Adds a repeatable scaffold-created relation.
--summary <text>	Supplies the value of the facet in the scent role.
--facet <facet=value>	Supplies a repeatable hand-entered facet value.
--directory <path>	Names the directory for a shelf that fixes the file name after a glob.
--now <date>	Sets the document date in YYYY-MM-DD form.
--root <path>	Selects the repository to load.
--no-color	Force plain text on both streams: bold and dim weight plus glyphs, no escape sequence. The default already senses whether each stream is a terminal, and renders color only there.
--no-banner	Suppress the masthead: the line naming this binary and its version, that the root help screen alone prints. It is accepted here and does nothing, since only the root screen prints one.

Exit status

0 means that the document and its capture-cost reading were written.

1 means that the command line, taxonomy, requested values or write failed. A failed run can leave a document when its reading failed to append. A run whose claim could not be made writes nothing at all, because the claim is made before the document.

1, and never 101, when standard output or standard error cannot be written, and one sentence on standard error names a failed standard output.

Environment

The command reads the system date when --now is absent. It reads no other environment variable.

Files

Path	How this verb treats it
.headwater/taxonomy.lock and corpus configuration	Read to derive the artifact.
Documents and graph indexes	Read to validate identifiers and relations.
.headwater/imports/	Read where .headwater/taxonomy.yml declares an import, for the anchors that an imported snapshot supplies. An imports entry that does not read stops the verb with exit 1, and so does an at path outside the repository root.
the path each harvests.<name>.at names	Read where .headwater/taxonomy.yml declares a pinned corpus export, for the anchors that export supplies. A harvests entry that does not read stops the verb with exit 1, and so does an at path outside the repository root. A pin with no digest binds no anchor. An absent file binds no anchor, and neither does a file that fails the pinned digest or is not an export.
The selected document path	Written when it does not already exist.
The target document of a scaffold-created relation	Written with the far half of a required relation when the new document does not open at an initial state. Not written while the far half is owed, not written for a symmetric relation, and never written with a state.
.headwater/ids/<scheme>/<identifier>	Written before the document, for a scheme that allocates reconcile-first. It holds the path of the document, it is never written twice, and it is never modified.
.headwater/capture-cost.jsonl	Appended with one reading after the document write.
.headwater/overlay.yml	Never read or written. A refusal for a kind with no identifier scheme names it as the file to edit.

See also

headwater infer reports adoption debt. headwater check checks the document after it lands.