# Frontmatter

Every Context Nest document begins with a YAML frontmatter block delimited by `---`. The frontmatter contains structured metadata that the resolver, validator, and index generator use.

## Required fields

| Field | Type | Description |
|-------|------|-------------|
| `title` | string | Human-readable title (1–200 characters) |

## Standard fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `type` | string | `document` | Node type (see [Node Types](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/node-types)) |
| `tags` | string[] | `[]` | Tags prefixed with `#` (e.g. `["#engineering", "#api"]`) |
| `status` | string | `draft` | Lifecycle state — see [Status Lifecycle](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/status-lifecycle) |
| `version` | integer | `1` | Current version number (auto-incremented on publish) |
| `author` | string | — | Author identifier |
| `description` | string | — | Brief description used by the generated index and listings |
| `created_at` | ISO 8601 | — | Creation timestamp |
| `updated_at` | ISO 8601 | — | Last update timestamp |
| `derived_from` | string | — | `contextnest://` URI of the source document |

### `description`

The `description` field is a one-line summary of the node. It is consumed by the **index generator** — it appears alongside the title in generated index/listing pages, so agents and humans can scan a folder without opening each node. Keep it short and specific.

## Status lifecycle

`status` is no longer a simple `draft` / `published` toggle. It is a **five-state governed lifecycle**:

```
draft → pending_review → approved → published
                    ↘ rejected
```

| State | Meaning |
|-------|---------|
| `draft` | Being authored; not yet submitted |
| `pending_review` | Submitted for review; awaiting a steward's decision |
| `approved` | Passed review; cleared to publish |
| `published` | Live and resolvable by consumers |
| `rejected` | Reviewed and sent back; not published |

See [Status Lifecycle](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/status-lifecycle) for transitions, who can move a node between states, and the operations behind each transition.

## Source node fields

Source nodes include an additional `source` block:

```yaml
source:
  transport: mcp          # mcp, rest, cli, or file
  server: jira             # Server name from the config registry
  tools:                   # Tools used by this source
    - jira_get_sprint_issues
  depends_on:              # Other sources this depends on
    - contextnest://sources/project-config
  cache_ttl: 300           # Cache lifetime in seconds
```

`source` is a first-class node type, so the `source:` block is written, edited, and versioned through the standard governed write path like any other node. See [Source Nodes](https://nest.promptowl.ai/d/promptowl-documents/protocol/source-nodes/overview) for the full source frontmatter reference.

## Skill node fields

`skill` nodes carry additional frontmatter describing the procedure and its guard-rails:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `trigger` | string (min length 1) | **yes** | The condition/phrase that invokes the skill |
| `inputs` | array of input objects | no | Declared inputs the skill expects |
| `tools_required` | string[] | no | Tools that must be available for the skill to run |
| `output_format` | enum | no | Declared shape of the skill's output |
| `guard_rails` | string[] | no | Constraints the skill must respect while executing |

```yaml
---
title: "Escalate Incident"
type: skill
trigger: "when a P1 incident is declared"
inputs:
  - incident_id
  - severity
tools_required:
  - pagerduty_create
  - slack_send_message
guard_rails:
  - "Never page outside business hours without on-call confirmation"
---
```

*Confirmed against the engine's `skillMetaSchema`: `trigger` is a required non-empty string; `inputs` is an array of input objects; `tools_required` and `guard_rails` are arrays of strings; `output_format` is an optional enum. A skill node is invalid without a skill block, so if `trigger` is omitted the engine/CLI/MCP default it from the title (e.g. `"when asked to <title>"`).*

## Example

```yaml
---
title: "Architecture Overview"
type: document
tags: ["#engineering", "#architecture"]
status: published
version: 4
author: "alice@example.com"
description: "High-level system architecture and key decisions"
created_at: "2026-01-15T10:00:00Z"
updated_at: "2026-03-10T14:30:00Z"
---
```