Manifest and capabilities

blocklet.yaml is the declared boundary of a Blocklet package. Authority for field acceptance is the current parser (packages/core/src/blocklet/parse-manifest.ts / BlockletManifest in types.ts) and the CLI checker — not historical product docs.

Verified baseline: arc 2.0.0-beta.28.

Minimum package (scaffold)

arc blocklet create ./demo-basic --recipe basic --name demo-basic writes:

specVersion: 2
id: demo-basic
name: demo-basic
did: did:blocklet:demo-basic
version: 0.1.0
description: ""

That is enough for arc blocklet check (profile basic) and arc blocklet build.

Identity fields

Field	Type	Notes
`specVersion`	number	`2` for packaging-oriented manifests
`id`	string	Stable package id (scaffold uses kebab name)
`name`	string	Human-readable display name (not forced to kebab)
`did`	string	`did:blocklet:<id>` from scaffold
`version`	string	SemVer string, e.g. `0.1.0`
`description`	string	One-line purpose

Publishable metadata (optional but recommended)

Field	Type	Notes
`logo`	string	Relative path or URL (SVG preferred)
`keywords`	string[]	Discovery
`tags`	string[]	UI categories
`author`	`{ name, email?, url? }`	Primary author
`contributors` / `maintainers`	author[]	Optional
`copyright`	`{ owner?, year? }`	Optional
`license`	string	SPDX / `UNLICENSED` / etc.
`homepage`, `documentation`, `community`, `support`	string	URLs or support contact
`repository`	string or `{ type, url, directory? }`	Source pointer
`screenshots`	string[]	Paths or URLs
`hidden`	boolean	`true` hides from catalogue UIs; still activatable via `?blocklet=`

Runtime declaration fields

These are not cosmetic metadata. Only use what the package needs.

Field	Meaning
`scope`	`app` (default), `user`, `root`, or `agent` — AFS namespace visibility
`mounts`	Provider mount declarations (`uri` or `module` + `target` + `required`, optional `ops`, `aup`, `seed`, …)
`system`	System service dependencies (e.g. `users`)
`sites`	Named sites: `name`, `domains`, optional `port`, `bindings`
`surfaces`	Externally accessible paths
`instance`	`{ required?, mount?, seed? }` — whether a real `/instance` DID Space is required
`cron`	Declarative scheduled tasks registered on activation
`replicated`	Replicated collection contracts (incompatible with `scope: root`)
`networkRead`	Allow network-origin reads of selected `/instance/**` base paths
`redistributable`	Redistribution terms for selected `/instance/**` subtrees
`index`	Index domain declarations for search
`blocklets`	Sub-blocklet composition list
`io`	IO surface / binding declarations
`arc` / `engines`	Compatibility ranges
`entrypoint`	Script path (specVersion 1 style; optional in v2)
`save`	Bookmark + selection-note capability. Omit = on, floating chrome. `false` / `{ enabled: false }` opts out. `chrome: buttons` binds `[data-arc-save]`. Hidden until login. See Bookmark and note.

Mount entry shape (code-backed)

mounts:
  - uri: "ash://"          # or module: "./providers/…"
    target: /ash           # absolute AFS path
    required: true
    ops: [list, read]      # optional whitelist

uri and module are mutually exclusive. See MountDeclaration in core types for aup, seed, shared, options.

Sites and bindings (example pattern)

Production packages such as Discuss Kit declare domains and URL→AFS→page bindings under sites. Use bindings when pretty URLs map onto instance content. Route files under .route/ remain the handler-level declaration for web vs app entry.

Scope reminder

Scope	Typical use
`app`	Default application package; supports replicated collections
`user`	Caller-scoped overlays (e.g. personal storage UIs)
`root`	Full host AFS visibility — not combined with `replicated`
`agent`	Agent-oriented packaging

Capabilities implied by recipes

Recipes report capabilities when listed:

arc blocklet recipe explain minimal-app

Recipe capability label	Typical files
`manifest`	`blocklet.yaml` only
`web`	`pages/`, `.web/`
`aup`	`.aup/`
`agent`	`agents/`
`settings`	`seed/settings/…`

Profile checks for complete apps (minimal-app, agent-workspace, support-community) enforce the recipe contract, not only the presence of blocklet.yaml.

Checker profiles

arc blocklet check . --profile basic
arc blocklet check . --profile minimal-app

Profile	Expectation (summary)
`basic`	Valid package directory / minimal contract
`minimal-app`	AUP pages, web section, agent, settings counts per recipe
`agent-workspace`	Workspace-oriented complete app contract
`support-community`	Support-community complete app contract

What not to invent

Do not document fields that exist only in planning docs or unmerged designs.
Do not claim store marketplace publication from metadata alone.
Do not treat hidden: true as a security boundary — it only affects catalogue visibility.

Full CLI surface: arc blocklet. Data path details: Data and AFS.