Make a Package
A Package is one folder. Only SKILL.md is required; everything else is a layer you can add later.
What the folder looks like#
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 PageThe 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#
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.
Add a manifest when you need one#
living-surface.manifest.jsonis 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 ofSKILL.md. If you include it,surface_idmust equal the folder name,local_firstmust betrue, andraw_retentionmust belocal-only. Keep it under 64 KB.Add Package data#
Put your content in
data.json, and describe its shape indata.schema.json. A missingdata.jsonis treated as an empty object; your Agent can generate both files on its first run.Add a Page#
service.htmlis 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.Handle the five states#
Make the Page show ready, empty, loading, error, and degraded states honestly. See Principles for what each state means.
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.jsonor 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:
- The validator checks the folder against one contract and one set of error codes.
- Review checks privacy boundaries, identity, and whether it can render. Only errors block; warnings do not.
- The Package is placed in your Vault.
- 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.