Author a Blocklet

Authoring a Blocklet joins several contracts. Keep them separate so changes stay reviewable.

Three authoring faces

Face	Question	Page
Manifest and capabilities	What does the package declare?	Manifest and capabilities
Data and AFS	How does the package use paths, mounts, seed, and collections?	Data and AFS
Web surfaces	Is this AUP UI, Web Device site content, or both?	Web surfaces

Recommended order

Start from a recipe that matches the surface you need (basic for empty package, minimal-app for web+AUP+agent, or hand-authored Web Device files as in Build a first site).
Fill identity metadata (name, description, logo, …) before treating the package as shareable.
Add only the AFS mounts, sites/bindings, or replicated collections the app actually uses.
Re-run arc dsl validate, arc blocklet check, and a local run after each meaningful change.

What not to mix

Do not	Do instead
Treat AUP page trees as "the Blocklet"	Blocklet = package boundary; AUP is one possible surface
Bind product language to a specific database	Use AFS paths and capabilities; see AFS
Copy entire CLI man pages into the app	Link arc blocklet for flags
Invent manifest fields from wishlists	Only document fields the parser/checker accept today

Entry points in a package directory

Path / file	Role
`blocklet.yaml`	Package manifest (required for most workflows)
`.aup/`	AUP app and pages
`pages/` + `.web/`	Web Device layouts, site components, SEO atoms
`.route/`	Route declarations (web vs app handlers)
`agents/`	Agent definitions
`seed/`	First-run seed material for instance data
`skills/`	Packaged skills (when used)
`dist/`	Build output only

Convention-only packages without blocklet.yaml still exist as teaching samples (hello-html, hello-declarative). Prefer an explicit blocklet.yaml for new third-party work — create always writes one.