> ## Documentation Index
> Fetch the complete documentation index at: https://agentapplications.io/llms.txt
> Use this file to discover all available pages before exploring further.

# APP.md Reference

> Complete reference for the APP.md manifest file — the root entrypoint and contract for every Agent Application package.

`APP.md` is the root manifest of an Agent Application package. It tells a runtime how to discover, activate, and operate the application. Every compliant package must have one.

The file has two parts:

* **YAML frontmatter** — machine-readable fields between `---` delimiters at the top of the file.
* **Markdown body** — human-readable documentation sections that follow the frontmatter.

## Frontmatter field reference

### Common fields

<ParamField path="schema" type="string">
  The schema identifier for this manifest. Set to `agentapplications/v1` to declare compliance with this specification. Optional — the filename already implies the kind — but recommended for tooling.
</ParamField>

<ParamField path="kind" type="string">
  The package kind. For `APP.md` files the value is `app`. Optional when the filename already makes the kind unambiguous.
</ParamField>

<ParamField path="slug" type="string">
  A stable, portable identifier for the package. Use kebab-case. Recommended — runtimes and catalogs use it to reference the package consistently across environments.
</ParamField>

<ParamField path="name" type="string" required>
  The human-readable name of the application. Displayed in catalogs and runtime UIs.
</ParamField>

<ParamField path="description" type="string" required>
  A short description used for discovery and cataloging. Keep it to one sentence.
</ParamField>

<ParamField path="version" type="string" required>
  The package version. Used by runtimes and catalogs to track releases and changes.
</ParamField>

<ParamField path="license" type="string">
  A license identifier or reference. Optional.
</ParamField>

<ParamField path="authors" type="array">
  Attribution metadata. Optional.
</ParamField>

<ParamField path="tags" type="array">
  Search and classification metadata. Optional. Runtimes MAY use tags for filtering or grouping packages.
</ParamField>

<ParamField path="metadata" type="object">
  Tool-specific extensions. Optional. Use this for any fields a specific runtime or host tool needs that are not covered by the standard fields.
</ParamField>

### Application-specific fields

<ParamField path="entry.command" type="string" required>
  The callable CLI entrypoint for the application. The spec does not constrain whether it is a binary, shell command, script, wrapper, or other callable entry — as long as a compatible client can invoke it and receive structured JSON output.

  ```yaml theme={null}
  entry:
    command: node app/cli.js
  ```
</ParamField>

<ParamField path="commands" type="array" required>
  A list of documented command names or command paths that the CLI exposes. In v1 this is a simple list, not a command-definition DSL.

  ```yaml theme={null}
  commands:
    - add
    - list
    - get
    - update
    - complete
    - remove
  ```
</ParamField>

<ParamField path="skills" type="array" required>
  A list of local skill shortnames. By convention, a shortname like `agentic-to-do-usage` resolves to `skills/agentic-to-do-usage/SKILL.md`. A runtime loads these files when it activates the package.

  ```yaml theme={null}
  skills:
    - agentic-to-do-usage
  ```
</ParamField>

<ParamField path="scheduling" type="string">
  Indicates whether the application exposes scheduling-related CLI commands. Allowed values are `supported` and `notSupported`. Optional — omit if scheduling is not relevant to your application.

  If you set this to `supported`, document the relevant scheduling commands in the body of `APP.md`.
</ParamField>

<ParamField path="confirmationRequired" type="array">
  A list of command names that require explicit user confirmation before execution. Use this for destructive operations such as `remove` or `delete`. Optional.

  ```yaml theme={null}
  confirmationRequired:
    - remove
  ```
</ParamField>

## Recommended body sections

Write the body of `APP.md` in plain Markdown after the frontmatter. Include these sections in order:

1. **Purpose** — what the application does and why it exists.
2. **CLI** — the entrypoint, default output mode, and any environment variables that affect behavior.
3. **Commands** — one subsection per command with signature, flags, and a brief description.
4. **Output** — the JSON shape for success and failure responses.
5. **State** — where and how the application stores data.
6. **Scheduling** — which commands support scheduling and how to invoke them.
7. **Confirmations** — which commands require `--confirm` or equivalent and why.
8. **Skills** — which skill files to load and what each one covers.

<Note>
  These sections are recommendations, not requirements. A minimal `APP.md` body can be as short as needed — the frontmatter carries the machine-readable contract.
</Note>

## JSON output format

Every CLI command must return JSON by default.

**Success shape** (exit code `0`):

```json theme={null}
{
  "ok": true,
  "command": "list",
  "count": 1,
  "items": [
    {
      "id": "td_0001",
      "title": "Write docs",
      "description": "",
      "status": "open",
      "dueAt": "2026-04-05",
      "createdAt": "2026-04-01T00:00:00.000Z",
      "updatedAt": "2026-04-01T00:00:00.000Z",
      "completedAt": null
    }
  ]
}
```

**Failure shape** (non-zero exit code):

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "remove requires --confirm."
  }
}
```

<Note>
  The exact output shape is application-defined. The spec requires that successful commands write parseable JSON to stdout and that failing commands return a non-zero exit code. Structured JSON errors on failure are strongly recommended but not strictly required.
</Note>

## Full example: Agentic To-Do

The following is the complete `APP.md` from the Agentic To-Do reference application.

```markdown theme={null}
---
schema: agentapplications/v1
kind: app
slug: agentic-to-do
name: Agentic To-Do
description: Self-contained persistent to-do list operated through a JSON-first CLI
version: 0.1.0
entry:
  command: node app/cli.js
commands:
  - add
  - list
  - get
  - update
  - complete
  - remove
skills:
  - agentic-to-do-usage
scheduling: supported
confirmationRequired:
  - remove
---

# Agentic To-Do

## Purpose

Agentic To-Do is a minimal Agent Applications v1 example that gives agents a stable CLI
for managing a persistent to-do list. The application owns its own JSON state under
`app/state/todos.json` and does not depend on chat history or prompt memory.

## CLI

- Entrypoint: `node app/cli.js`
- Default output: JSON on stdout for both success and failure cases
- State override for tests or isolated runs: `AGENTIC_TODO_STATE_FILE=/tmp/todos.json`

## Commands

### `add <title> [--description <text>] [--due-at <iso-date>]`
Create an open to-do item.

### `list [--status all|open|completed]`
List items filtered by status. Defaults to `all`.

### `get <id>`
Fetch a single to-do item.

### `update <id> [--title <text>] [--description <text>] [--due-at <iso-date>] [--clear-due-at]`
Update one or more mutable fields.

### `complete <id>`
Mark an item as completed.

### `remove <id> --confirm`
Delete an item. The `--confirm` flag is required because the operation is destructive.

## Output

Successful commands return structured JSON. Failures return structured JSON with a
non-zero exit code.

## State

The application stores data in `app/state/todos.json`. IDs are stable and increment
as `td_0001`, `td_0002`, and so on.

## Scheduling

Scheduling is supported through the optional `--due-at` field on `add` and `update`.

## Confirmations

`remove` requires explicit confirmation via `--confirm`.

## Skills

Load `skills/agentic-to-do-usage/SKILL.md` when an agent needs concise operating
guidance for the CLI.
```