Docs

Make a Package

A Package is one folder. Only SKILL.md is required; everything else is a layer you can add later.

Last updated 2026-11-03

What the folder looks like#

Files
my-package/├── SKILL.md  # required: what this is and where the data lives├── living-surface.manifest.json  # optional: identity and file map├── data.json  # optional: your content, never uploaded├── data.schema.json  # optional: the shape of data.json└── service.html  # optional: the Page

The folder name is the Package's id. It uses lowercase letters, digits, and hyphens, starts with a letter or digit, and is at most 60 characters.

Build it step by step#

  1. Write SKILL.md#

    In plain words, say what the Package is for and where its data lives. This file alone is enough for Lorevik to open the Package. Without it, the folder is not a Package.

  2. Add a manifest when you need one#

    living-surface.manifest.json is the Package's identity: id, title, a one-line description, the file map, and its privacy boundaries. If you leave it out, Lorevik builds one in memory from the folder name and the first heading of SKILL.md. If you include it, surface_id must equal the folder name, local_first must be true, and raw_retention must be local-only. Keep it under 64 KB.

  3. Add Package data#

    Put your content in data.json, and describe its shape in data.schema.json. A missing data.json is treated as an empty object; your Agent can generate both files on its first run.

  4. Add a Page#

    service.html is one self-contained HTML file that renders the Package data. It runs in a sandboxed frame, so keep every asset inline, stay under 2 MB, read the data the host injects instead of fetching files, and use a fluid width that works from 640 pixels without horizontal scroll. Without a Page, Lorevik shows a placeholder until one is generated.

  5. Handle the five states#

    Make the Page show ready, empty, loading, error, and degraded states honestly. See Principles for what each state means.

  6. Check it before you publish#

    Open the Package in the app and clear as many warnings as you can. Warnings never block rendering; errors do.

What never goes in a Package#

  • Files the app generates while running: lorevik-intake.html, lorevik-service.html, and anything under .lorevik/.
  • Real accounts, keys, or absolute paths on your computer, in data.json or anywhere else.
  • Media you do not have the right to share.
  • Placeholder text such as "replace me" in place of real content.

Warning: Raw data stays on your machine. Lorevik's cloud receives metadata only, and the manifest has to say so. A Package whose manifest breaks this boundary fails validation.

How Lorevik checks it#

Every Package goes through the same path, whether you downloaded it from Explore or wrote it yourself:

  1. The validator checks the folder against one contract and one set of error codes.
  2. Review checks privacy boundaries, identity, and whether it can render. Only errors block; warnings do not.
  3. The Package is placed in your Vault.
  4. Lorevik renders the Page, or a placeholder if there is none, or an honest empty state for any missing layer.

Every warning and error comes with a fix hint, so your Agent can work through them one by one.