# Pack Format

Context packs are YAML files stored in the `packs/` directory.

## Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique pack identifier |
| `label` | string | Yes | Human-readable name |
| `description` | string | No | What this pack provides |
| `query` | string | No | Selector expression defining pack membership dynamically |
| `includes` | string[] | No | Explicit list of document paths or `contextnest://` URIs |
| `excludes` | string[] | No | Documents to exclude from query results |
| `agent_instructions` | string | No | Prose guidance for agents on how to use the pack contents |
| `version` | integer | No | Pack version number |

## Static vs dynamic packs

**Static packs** use `includes` to list specific documents:

```yaml
id: onboarding-basics
label: Onboarding Basics
includes:
  - nodes/team-handbook
  - nodes/onboarding-guide
  - nodes/development-setup
```

**Dynamic packs** use `query` to define membership via a selector:

```yaml
id: all-published-engineering
label: All Published Engineering Docs
query: "tag:#engineering & status:published"
excludes:
  - nodes/internal-notes
```

## Agent instructions

The `agent_instructions` field is free-form prose that tells the agent how to interpret and use the pack contents:

```yaml
agent_instructions: >
  These documents describe the onboarding process. When helping
  a new team member, walk through them in order: handbook first,
  then the onboarding guide, then dev setup. Flag any steps that
  look outdated.
```