new.md

estado	Completed

Document Scaffolding

rootline new creates a Markdown file with frontmatter and required body sections generated from the effective .stem schema of the target directory.

CLI Usage

rootline new docs/api/new-endpoint.md             # Create file
rootline new --dry-run docs/api/new-endpoint.md   # Preview content
rootline new --force docs/api/existing.md         # Overwrite existing

Flags

Flag	Description
--dry-run	Show generated content without writing file
--force	Overwrite existing file

Output Example

---
estado:
---
# New Endpoint

The title is auto-generated from the filename: dashes and underscores become spaces, with title case applied.

Enum Fields

Enum fields are scaffolded only when Rootline has a value to write or the schema requires the field:

• Fields with an explicit default: in the schema use that default as the initial value.
• Required enum fields without a default are not written as a successful scaffold. new renders no invented first value, then prospective validation refuses the command before dry-run output or disk write so the schema author must add an explicit default: or make the field optional.
• optional enum fields with no default are omitted. This prevents wrong defaults from being written silently.

The internal prospective renderer may represent a required defaultless enum as an empty value with a values comment while validating:

tipo:  # [outcome, task]

That preview is not published by rootline new when validation fails.

Sequence Fields

Sequence fields (type: sequence) are not auto-populated by rootline new. Use rootline describe <dir> to find the next available ID before choosing a filename or frontmatter value:

rootline describe docs/epics/ --field schema.id.next

Required Body Sections

A required source-backed field is scaffolded in the body, not as an empty frontmatter key:

summary:
  type: string
  source: body.section["## Summary"]
  required: true

new adds a missing simple section with its non-empty default: or <!-- TODO -->. Multiple missing simple sections use lexical heading order. A frontmatter override or an empty-present section already satisfies presence. More than one selector match is ambiguous and stops the command before a file is written.

Each selector component contains one to six # characters, one space, and the exact parsed heading text. The # characters encode the heading level, not the original Markdown form. Rootline materializes a simple selector with ATX or Setext syntax that preserves the level and text. Setext syntax is available only for levels 1 and 2. If neither form preserves the selector, new fails before it writes the affected file.

A qualified selector can use body.section["## Parent"]["### Notes"]. The components must be contiguous, and the selector matches a contiguous suffix of the heading path. new does not invent ancestor headings. If a required qualified section is absent, new stops before it writes the affected file. Generated bytes are prospectively validated against the same effective schema.