Manifest Reference

The sync protocol uses JSON manifest uploads, not ZIP files.

1{2  "version": 1,3  "source": {4    "id": "main-docs",5    "commit": "abc123",6    "branch": "main",7    "repository": "valkyrianlabs/payload-markdown-docs"8  },9  "mode": "sync",10  "deleteBehavior": "archive",11  "publish": false,12  "project": {13    "title": "Payload Markdown Docs",14    "stack": [{ "category": "languages", "items": [{ "name": "TypeScript" }] }]15  },16  "files": [17    {18      "path": "getting-started/installation.md",19      "sha256": "...",20      "content": "# Installation\n\n..."21    }22  ],23  "assets": [24    {25      "kind": "skill",26      "path": "skills/main-docs/codex/SKILL.md",27      "route": "/plugins/main-docs/skills/codex/SKILL.md",28      "contentType": "text/markdown; charset=utf-8",29      "sha256": "...",30      "content": "# Skill\n\n..."31    }32  ]33}

Validation Rules

• version must be 1
• source.id is required
• only .md files are accepted
• paths must be relative and cannot contain traversal
• duplicate normalized paths are rejected
• declared SHA-256 must match content
• frontmatter must use the supported subset
• derived route segments must not contain ?, #, or control characters
• file count and size limits are enforced; the binding size limit is the byte length of the JSON request body (maxBodyBytes, 5,000,000 by default)
• two files or assets that derive the same route are rejected by the sync endpoint as a route collision
• client-supplied asset route values are confined: skill routes are always derived from the docs set, llms/llms-full routes must be /llms.txt / /llms-full.txt (or that file under the docs set route), and static routes must stay under the docs set route without ./.., %, ?, or #

Project Metadata

project is optional. pmdocs builds it from docs/stack.toml and omits it when the file does not exist. The server validates it with the same rules: issue paths name stack.toml keys, and unknown fields only warn. When project is present, the sync response reports what it did:

1"project": { "applied": true, "stack": "updated", "title": "manual", "description": "not_provided" }

stack is updated, unchanged, cleared or not_provided. title and description are updated, unchanged, manual (the admin manages them) or not_provided. applied is false for dry runs. Servers older than 1.3 ignore project and send no such key.

Static Assets

files are docs records and use frontmatter, title resolution, and route derivation. assets are native skill artifacts and optional static fallback artifacts stored separately. They do not require frontmatter and are not parsed as docs pages.

pmdocs emits only these asset content types, chosen by file extension: text/markdown; charset=utf-8 (.md), application/json; charset=utf-8 (.json), application/yaml; charset=utf-8 (.yaml, .yml), and text/plain; charset=utf-8 (everything else, such as llms.txt).

Supported asset kinds:

• llms
• llms-full
• skill
• static

llms and llms-full assets are optional custom static fallback files. By default, /llms.txt, /llms-full.txt, and docs-set llms files are generated by the plugin from synced docs, docs set metadata, dependencies, and skills. Skill routes are always derived from the computed docs set route (a route sent for a skill asset is ignored with a warning), so skills/main-docs/codex/SKILL.md serves under a public route such as /plugins/main-docs/skills/codex/SKILL.md. The agent root route, for example /plugins/main-docs/skills/codex, is generated as a Markdown directory index, and /plugins/main-docs/skills/codex.zip is generated from the synced text artifacts rather than stored as a static ZIP asset.

See frontmatter.

Agent Artifacts

The sync manifest is not the AI workflow artifact. AI-first support is delivered through native skill directories under skills/payload-markdown-docs/<agent>/. Those files can be installed by pmdocs, included in the plugin package, or served by a docs website for direct download.

Keep /docs focused on human documentation and /skills focused on agent-native workflow instructions.