6.9 Resource packaging and distribution

This page explains file organization shared by the four resource types. Finish an employee, team, app or SKILL example first, then update and distribute it here.

Two file layers

File	Purpose
employee.json, team.json, app.json or skill.json	Importable share containing actual file bodies
sources/teloa.json	Internal manifest listing resources, versions, paths and relationships
sources/roles/, skills/ and other files	Editable sources incorporated when repackaged

Download the four examples. Each ZIP includes complete JSON, sources/ and pack.mjs. The share and internal manifest are different JSON documents.

A complete internal manifest

The app example's sources/teloa.json declares one skill:

{
  "format": "teloa.business-package/v2",
  "id": "example-app-brief",
  "version": "1.0.1",
  "title": "Evidence brief app",
  "description": "A local authoring example with no account connection or automatic execution.",
  "domain": "general",
  "scope": "general",
  "resources": [
    {
      "id": "evidence-brief",
      "kind": "skill",
      "title": "evidence-brief",
      "version": "1.0.1",
      "required": true,
      "source": {
        "kind": "local",
        "path": "skills/evidence-brief/SKILL.md"
      }
    }
  ],
  "relations": [],
  "entrypoints": [
    "evidence-brief"
  ]
}

Its body is sources/skills/evidence-brief/SKILL.md. Employees and teams additionally declare roles and connect methods through role-skill. See the format reference for other resources and fields.

teloa.business-package is the internal manifest name, not a fifth product type. The outer subject identifies employee, team, app or SKILL: exactly one employee, at least two team members, no employees in an app, or exactly one skill for a standalone SKILL.

Repackage edited sources

After changing an employee definition, run from the extracted directory:

node pack.mjs employee.json

Use app.json, team.json or skill.json for the other subjects. The helper refreshes bodies of files already listed in the share:

import {readFile, writeFile, realpath} from 'node:fs/promises'
import {resolve, sep} from 'node:path'
const file = process.argv[2]
if (!file) throw Error('Usage: node pack.mjs employee.json')
const share = JSON.parse(await readFile(file, 'utf8'))
const sourceRoot = await realpath('sources')
for (const item of share.files) {
  if (typeof item.path !== 'string' || item.path.includes('\\') ||
      /[\x00-\x1f\x7f]/.test(item.path) ||
      item.path.split('/').some(part => !part || part === '.' || part === '..')) {
    throw Error('Unsafe source path')
  }
  const source = await realpath(resolve(sourceRoot, item.path))
  if (!source.startsWith(sourceRoot + sep)) throw Error('Source escapes the package')
  item.text = await readFile(source, 'utf8')
}
const manifest = JSON.parse(share.files.find(f => f.path === 'teloa.json').text)
share.id = manifest.id
share.version = manifest.version
await writeFile(file, JSON.stringify(share, null, 2) + '\n')

When adding a resource, update inner resources and relations, the outer files list and the actual source files. Increase the package version after changing content; also update changed resource versions and pinned references. The helper synchronizes package identity/version, not every resource's version.

Format validation

From a dependency-prepared Teloa source root, copy share JSON files into the current directory. List just one subject to check one file; this example checks all four:

node --input-type=module <<'JS'
import {readFileSync} from 'node:fs'
import {readTemplateShare} from './packages/contract/src/template-share.mjs'
for (const subject of ['employee', 'team', 'app', 'skill']) {
  const value = JSON.parse(readFileSync(`${subject}.json`, 'utf8'))
  console.log(readTemplateShare(value).subject)
}
JS

Expect employee, team, app, skill. This validates the format without adding or executing it. Without a source environment, choose a share JSON in Employees > Import template to inspect its preview.

Receive and distribute

Inspect members, methods, material and provenance, then explicitly add to a test business area. Employees start paused. Follow readiness states to configure models, install capabilities, connect accounts and grant permissions. Complete the tutorial's small task before distributing through offline files or online links.

A share is limited to 8 MiB serialized JSON and 2 MiB per file body. Exclude passwords, model keys, account sessions and execution grants; check distribution rights for the included text and materials.

Complete business configuration

Internal v2 organizes ordinary resources, v3 adds pinned model dependencies and v4 adds complete business configuration. Choose the required capabilities rather than incrementing format numbers as a publishing ritual. Complete configuration includes objects, views, pages and dashboards, without real records, sync accounts or action grants. See format reference.

For an inner resource directory or ZIP, use Marketplace > Create > Import template and include its manifest and files. For the share JSON used here, use Employees > Import template. These entrypoints read different file structures.