stillmade-sdk 0.1.22 → 0.1.23

package/AGENTS.md

@@ -6,7 +6,7 @@ This folder is the StillMade Block SDK. Read this file before writing code; it i
 
 Do not tell the user a Block is ready, done or working until `node packages/block-cli/cli.js gate .` passes after your last edit, and report the exact status it prints. In this folder Claude Code (`.claude/settings.json`) and Cursor (`.cursor/hooks.json`) run the gate when you finish a turn and send any failures back to you, but only in a session started in this folder: if you downloaded the SDK during the current session, run the gate yourself. Other agents must also run it themselves. If you cannot fix a failure, say plainly that the Block is not ready and list the failing checks.
 
-Contract `stillmade.block-builder@1.5.4`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.6.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ## Source of truth
 
@@ -40,6 +40,10 @@ Translate the request into an explicit capability contract before implementation
 
 A Block is one job: not a mini-app of many jobs and not a fragment of one. Its outputs become other Blocks' inputs and its inputs come from other Blocks, project context or the user. Use the typed port system: shared StillMade types (`image`, `video`, `audio`, `asset`, `script`, `shot[]`, ...), a `semantic` meaning on every port, `required` and a short `description`. Mark exactly one primary input and one primary output so Project Type Steps connect automatically, and use `kind: "task"`: a `workspace` Block owns a project document and is never connected automatically. Inputs marked `context` read the project and cannot receive a connection from another Step. Output reusable StillMade values: media references (`{kind,assetId,versionId,url}`) and structured production values with `schemaVersion: 1`, preserving provenance, versions and relationships downstream Blocks need. Never make ordinary users wire JSON, copy IDs, understand internal paths or translate one Block's output into another: `createUniversalResolver()` (the same engine as the Project Type composer) resolves inputs from compatible upstream outputs, permitted project context and, for optional non-context inputs, `StillMade.requestFromUser`.
 
+## Feature map
+
+Every Block carries a feature map in `manifest.features`, written by whoever builds it while they build, so the person never writes it. Add one entry for each separate thing a person could ask for: a tool, a mode, a preset family or a kind of result (an editor's reaction GIFs, its motion presets, a recorder's screen recording), not one entry covering several tools. Each entry has a lowercase `id`, a `label` of 40 characters or fewer, `does` (what it does, 160 characters or fewer) and `asks`: 1–8 short requests in a customer's own words that this feature answers ("add a fire gif over my car"). `operation` names an id in the Block's own `manifest.operations` (omit it when there are none); `inputs`/`outputs` name declared ports. The gate fails a Block without one. Add or update the entry in the same change that adds or alters a tool, and remove it when the tool goes. List only what the code really does; listings are generated from this map, nobody can edit them, and StillMade matches requests to features. Features are not tested at publish: each shows as new until real use proves it.
+
 ## Use platform primitives
 
 Prefer, in order: an SDK capability; a documented host capability (the hosted operations are text.generate, audio.speech, audio.transcribe, audio.music, audio.sfx, image.generate, video.generate, image.describe, media.analyze, web.fetch, web.research, timeline.propose, workspace.propose, connection.execute; connected third-party apps go through `connection.execute`); an approved dependency the SDK already bundles; small Block-local code. Do not duplicate what StillMade provides. A Block never contains its own asset system, file picker, authentication, project-context system, input resolver, Block connection system, credit system, secrets store, permission system, progress system, multiplayer system, persistence system, model-provider abstraction or execution protocol.

package/PASTE_TO_LLM.md

@@ -2,9 +2,9 @@
 
 <!-- builder-contract:start (generated by npm run build:sdk; do not edit) -->
 
-## Block builder contract (stillmade.block-builder@1.5.4)
+## Block builder contract (stillmade.block-builder@1.6.1)
 
-Contract `stillmade.block-builder@1.5.4`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.6.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ### Source of truth
 
@@ -38,6 +38,10 @@ Translate the request into an explicit capability contract before implementation
 
 A Block is one job: not a mini-app of many jobs and not a fragment of one. Its outputs become other Blocks' inputs and its inputs come from other Blocks, project context or the user. Use the typed port system: shared StillMade types (`image`, `video`, `audio`, `asset`, `script`, `shot[]`, ...), a `semantic` meaning on every port, `required` and a short `description`. Mark exactly one primary input and one primary output so Project Type Steps connect automatically, and use `kind: "task"`: a `workspace` Block owns a project document and is never connected automatically. Inputs marked `context` read the project and cannot receive a connection from another Step. Output reusable StillMade values: media references (`{kind,assetId,versionId,url}`) and structured production values with `schemaVersion: 1`, preserving provenance, versions and relationships downstream Blocks need. Never make ordinary users wire JSON, copy IDs, understand internal paths or translate one Block's output into another: `createUniversalResolver()` (the same engine as the Project Type composer) resolves inputs from compatible upstream outputs, permitted project context and, for optional non-context inputs, `StillMade.requestFromUser`.
 
+### Feature map
+
+Every Block carries a feature map in `manifest.features`, written by whoever builds it while they build, so the person never writes it. Add one entry for each separate thing a person could ask for: a tool, a mode, a preset family or a kind of result (an editor's reaction GIFs, its motion presets, a recorder's screen recording), not one entry covering several tools. Each entry has a lowercase `id`, a `label` of 40 characters or fewer, `does` (what it does, 160 characters or fewer) and `asks`: 1–8 short requests in a customer's own words that this feature answers ("add a fire gif over my car"). `operation` names an id in the Block's own `manifest.operations` (omit it when there are none); `inputs`/`outputs` name declared ports. The gate fails a Block without one. Add or update the entry in the same change that adds or alters a tool, and remove it when the tool goes. List only what the code really does; listings are generated from this map, nobody can edit them, and StillMade matches requests to features. Features are not tested at publish: each shows as new until real use proves it.
+
 ### Use platform primitives
 
 Prefer, in order: an SDK capability; a documented host capability (the hosted operations are text.generate, audio.speech, audio.transcribe, audio.music, audio.sfx, image.generate, video.generate, image.describe, media.analyze, web.fetch, web.research, timeline.propose, workspace.propose, connection.execute; connected third-party apps go through `connection.execute`); an approved dependency the SDK already bundles; small Block-local code. Do not duplicate what StillMade provides. A Block never contains its own asset system, file picker, authentication, project-context system, input resolver, Block connection system, credit system, secrets store, permission system, progress system, multiplayer system, persistence system, model-provider abstraction or execution protocol.
@@ -148,6 +152,10 @@ Every finished Block must support automatic remixing through the standard SDK co
 
 A Block package is StillMade SDK 0.1.0 JSON. Prefer {manifest,recipe,tests} for supported operations. Otherwise use {manifest,code,tests} with runtime:"javascript": code is a synchronous function body receiving input and returning declared output bindings, e.g. return {text:input.text.toUpperCase()}. JavaScript runs in isolated QuickJS: no fetch, DOM, Node APIs, modules, dependencies, timers, or host services; no promises, imports, require, eval or Function. Limits: 500 ms execution, 16 MiB heap, 256 KiB code, 4 MiB JSON I/O. Include concrete passing fixtures that reflect the requested behavior, including an edge case; never approximate a hosted model call with fabricated deterministic output. Manifest fields: schemaVersion:1,sdkVersion:"0.1.0",id:"creator.name",version:"1.0.0",name,description,kind:"task",runtime:"recipe", "javascript", "comfyui", or "capability",inputs/outputs as named {type,default?,min?,max?,role?,primary?}. Usually mark one primary input and output with primary:true. Semantic roles such as source_image and character_reference are distinct and must never be guessed,permissions:{project:[],network:[],filesystem:[],secrets:[]},ui:[{control,port}]. Recipe: {schemaVersion:1,steps:[{id,op,args}],outputs}. References: {"$input":"port"}, {"$step":"step-id"}. Supported operations: {"value.copy":{"description":"Copy a JSON value without changing it.","args":["value"]},"text.trim":{"description":"Remove leading and trailing whitespace.","args":["text"]},"text.replace":{"description":"Replace literal text; no regular expressions.","args":["text","find","replacement"]},"text.join":{"description":"Join an array of text values.","args":["items","separator"]},"image.thicken-lines":{"description":"Expand dark outlines while preserving other colors.","args":["image","thickness","threshold"]}}. Types include text,number,integer,boolean,json,image,audio,video,script,text[]. Include test {name,input,expected} where expected is output bindings.
 
+### Feature map
+
+Every Block lists its separate tools in manifest.features, one entry per tool or mode a person could ask for: {"id":"reaction-gifs","label":"Reaction GIFs","does":"Search GIFs and drop one over a clip.","asks":["add a fire gif over my car","reaction gif when he laughs"]}. Use 1–24 entries; id is lowercase with hyphens, label at most 40 characters, does at most 160, asks 1–8 short requests in a customer's words. A Block that really does one job has one entry. Rewrite the starting entry create writes (it copies the description), or the gate fails. When refining or remixing, add, change or remove entries in the same change as the tool, and keep the ids of tools that stay.
+
 ### Port meanings
 
 For each newly created Block, declare the meaning of every input and output in its manifest contract, not just a physical type. Each input needs semantic, required:boolean and a short plain-language description. Each output needs semantic and a short description. Use lowercase snake_case or dotted semantic names, such as company_profile or email_subject; different meanings are not interchangeable merely because both are text. If an existing role is present, semantic must equal that role. Reuse an exact existing meaning only when the information actually has that meaning. Describe structured fields with schema when their shape matters: for example {name:"string",website:"string",industry:"string?"}. Supported schema fields are string/text, number, integer, boolean, object, json, arrays of those types, and optional fields with ?. Declare sources only when a requirement restricts where its answer may come from: upstream, project, adapter, chat, default, user or external. Do not mark a credential as ordinary text or put secrets in defaults. Contracts describe information; they never authorize network access, model calls, project edits, credit spending or new runtime APIs. Keep existing imported, installed and base Block contracts unchanged; do not silently relabel old published contracts to make a connection appear compatible. New contracts must match actual code and fixtures.

package/SDK.md

@@ -182,7 +182,7 @@ The archive needs Node.js 22 or later and nothing else; its runtime is bundled,
 
 ## Block builder contract
 
-Contract `stillmade.block-builder@1.5.4`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.6.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ### Source of truth
 
@@ -216,6 +216,10 @@ Translate the request into an explicit capability contract before implementation
 
 A Block is one job: not a mini-app of many jobs and not a fragment of one. Its outputs become other Blocks' inputs and its inputs come from other Blocks, project context or the user. Use the typed port system: shared StillMade types (`image`, `video`, `audio`, `asset`, `script`, `shot[]`, ...), a `semantic` meaning on every port, `required` and a short `description`. Mark exactly one primary input and one primary output so Project Type Steps connect automatically, and use `kind: "task"`: a `workspace` Block owns a project document and is never connected automatically. Inputs marked `context` read the project and cannot receive a connection from another Step. Output reusable StillMade values: media references (`{kind,assetId,versionId,url}`) and structured production values with `schemaVersion: 1`, preserving provenance, versions and relationships downstream Blocks need. Never make ordinary users wire JSON, copy IDs, understand internal paths or translate one Block's output into another: `createUniversalResolver()` (the same engine as the Project Type composer) resolves inputs from compatible upstream outputs, permitted project context and, for optional non-context inputs, `StillMade.requestFromUser`.
 
+### Feature map
+
+Every Block carries a feature map in `manifest.features`, written by whoever builds it while they build, so the person never writes it. Add one entry for each separate thing a person could ask for: a tool, a mode, a preset family or a kind of result (an editor's reaction GIFs, its motion presets, a recorder's screen recording), not one entry covering several tools. Each entry has a lowercase `id`, a `label` of 40 characters or fewer, `does` (what it does, 160 characters or fewer) and `asks`: 1–8 short requests in a customer's own words that this feature answers ("add a fire gif over my car"). `operation` names an id in the Block's own `manifest.operations` (omit it when there are none); `inputs`/`outputs` name declared ports. The gate fails a Block without one. Add or update the entry in the same change that adds or alters a tool, and remove it when the tool goes. List only what the code really does; listings are generated from this map, nobody can edit them, and StillMade matches requests to features. Features are not tested at publish: each shows as new until real use proves it.
+
 ### Use platform primitives
 
 Prefer, in order: an SDK capability; a documented host capability (the hosted operations are text.generate, audio.speech, audio.transcribe, audio.music, audio.sfx, image.generate, video.generate, image.describe, media.analyze, web.fetch, web.research, timeline.propose, workspace.propose, connection.execute; connected third-party apps go through `connection.execute`); an approved dependency the SDK already bundles; small Block-local code. Do not duplicate what StillMade provides. A Block never contains its own asset system, file picker, authentication, project-context system, input resolver, Block connection system, credit system, secrets store, permission system, progress system, multiplayer system, persistence system, model-provider abstraction or execution protocol.
@@ -5914,8 +5918,17 @@ export interface FrameView { runtime: 'frame'; html: string; css?: string; theme
 export interface BlockPackage { portable?: PortableMetadata; manifest: Manifest; view?: BlockView|FrameView; code?: string; module?: ModuleDescriptor; comfyui?: ComfyWorkflow; capability?: ConnectedCapability|TextGenerationCapability|SpeechCapability|TranscriptionCapability|ImageGenerationCapability|VideoGenerationCapability|ImageDescriptionCapability|TimelineProposalCapability; recipe?: { schemaVersion: 1; steps: { id: string; op: string; args: Record<string, unknown> }[]; outputs: Record<string, unknown> }; tests: { name: string; input: Record<string, unknown>; expected?: Record<string, unknown>; state?: BlockState; expectedState?: BlockState; expectations?: Record<string, ConnectedResultExpectation|ComfyImageExpectation|CapabilityTextExpectation|CapabilityAudioExpectation|CapabilityTranscriptExpectation|CapabilityImageExpectation|CapabilityVideoExpectation|CapabilityTimelineExpectation> }[]; }
 /** Named sandbox action with fixed declared input settings and produced ports. */
 export interface BlockOperation {id:string;label:string;description:string;inputs:Record<string,string|number|boolean>;outputs:string[]}
+/** One entry of a Block's feature map: a separate thing the Block can do and the requests it answers. */
+export interface BlockFeature {id:string;label:string;does:string;asks:string[];operation?:string;inputs?:string[];outputs?:string[]}
+export const FEATURE_MAP_LIMITS: Readonly<{features:24;id:48;label:40;does:160;asks:8;ask:80}>;
+/** Validation messages for `manifest.features`; [] when valid or absent. */
+export function featureMapErrors(manifest:unknown):string[];
+/** The declared feature map, or one derived from operations or the Block itself. */
+export function blockFeatures(manifest:unknown):(BlockFeature&{source:'declared'|'derived'})[];
 export interface Manifest {
   operations?: BlockOperation[];
+  /** Feature map: what the Block can do, tool by tool. Written by the builder; listings are generated from it. */
+  features?: BlockFeature[];
   storage?: import('./block-storage.js').BlockStorageDeclaration;
   /** Events the Block can run on by itself, once the project owner turns them on. */
   triggers?: import('./triggers.js').BlockTrigger[];
@@ -7224,9 +7237,9 @@ Ask the assistant to return source files or one `.stillmade.json` package. Run t
 
 <!-- builder-contract:start (generated by npm run build:sdk; do not edit) -->
 
-### Block builder contract (stillmade.block-builder@1.5.4)
+### Block builder contract (stillmade.block-builder@1.6.1)
 
-Contract `stillmade.block-builder@1.5.4`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
+Contract `stillmade.block-builder@1.6.1`. Humans, coding agents, imported source, GitHub repositories and generated code all adapt to the Block platform; anything that becomes a StillMade Block obeys this contract.
 
 ### Source of truth
 
@@ -7260,6 +7273,10 @@ Translate the request into an explicit capability contract before implementation
 
 A Block is one job: not a mini-app of many jobs and not a fragment of one. Its outputs become other Blocks' inputs and its inputs come from other Blocks, project context or the user. Use the typed port system: shared StillMade types (`image`, `video`, `audio`, `asset`, `script`, `shot[]`, ...), a `semantic` meaning on every port, `required` and a short `description`. Mark exactly one primary input and one primary output so Project Type Steps connect automatically, and use `kind: "task"`: a `workspace` Block owns a project document and is never connected automatically. Inputs marked `context` read the project and cannot receive a connection from another Step. Output reusable StillMade values: media references (`{kind,assetId,versionId,url}`) and structured production values with `schemaVersion: 1`, preserving provenance, versions and relationships downstream Blocks need. Never make ordinary users wire JSON, copy IDs, understand internal paths or translate one Block's output into another: `createUniversalResolver()` (the same engine as the Project Type composer) resolves inputs from compatible upstream outputs, permitted project context and, for optional non-context inputs, `StillMade.requestFromUser`.
 
+### Feature map
+
+Every Block carries a feature map in `manifest.features`, written by whoever builds it while they build, so the person never writes it. Add one entry for each separate thing a person could ask for: a tool, a mode, a preset family or a kind of result (an editor's reaction GIFs, its motion presets, a recorder's screen recording), not one entry covering several tools. Each entry has a lowercase `id`, a `label` of 40 characters or fewer, `does` (what it does, 160 characters or fewer) and `asks`: 1–8 short requests in a customer's own words that this feature answers ("add a fire gif over my car"). `operation` names an id in the Block's own `manifest.operations` (omit it when there are none); `inputs`/`outputs` name declared ports. The gate fails a Block without one. Add or update the entry in the same change that adds or alters a tool, and remove it when the tool goes. List only what the code really does; listings are generated from this map, nobody can edit them, and StillMade matches requests to features. Features are not tested at publish: each shows as new until real use proves it.
+
 ### Use platform primitives
 
 Prefer, in order: an SDK capability; a documented host capability (the hosted operations are text.generate, audio.speech, audio.transcribe, audio.music, audio.sfx, image.generate, video.generate, image.describe, media.analyze, web.fetch, web.research, timeline.propose, workspace.propose, connection.execute; connected third-party apps go through `connection.execute`); an approved dependency the SDK already bundles; small Block-local code. Do not duplicate what StillMade provides. A Block never contains its own asset system, file picker, authentication, project-context system, input resolver, Block connection system, credit system, secrets store, permission system, progress system, multiplayer system, persistence system, model-provider abstraction or execution protocol.
@@ -7370,6 +7387,10 @@ Every finished Block must support automatic remixing through the standard SDK co
 
 A Block package is StillMade SDK 0.1.0 JSON. Prefer {manifest,recipe,tests} for supported operations. Otherwise use {manifest,code,tests} with runtime:"javascript": code is a synchronous function body receiving input and returning declared output bindings, e.g. return {text:input.text.toUpperCase()}. JavaScript runs in isolated QuickJS: no fetch, DOM, Node APIs, modules, dependencies, timers, or host services; no promises, imports, require, eval or Function. Limits: 500 ms execution, 16 MiB heap, 256 KiB code, 4 MiB JSON I/O. Include concrete passing fixtures that reflect the requested behavior, including an edge case; never approximate a hosted model call with fabricated deterministic output. Manifest fields: schemaVersion:1,sdkVersion:"0.1.0",id:"creator.name",version:"1.0.0",name,description,kind:"task",runtime:"recipe", "javascript", "comfyui", or "capability",inputs/outputs as named {type,default?,min?,max?,role?,primary?}. Usually mark one primary input and output with primary:true. Semantic roles such as source_image and character_reference are distinct and must never be guessed,permissions:{project:[],network:[],filesystem:[],secrets:[]},ui:[{control,port}]. Recipe: {schemaVersion:1,steps:[{id,op,args}],outputs}. References: {"$input":"port"}, {"$step":"step-id"}. Supported operations: {"value.copy":{"description":"Copy a JSON value without changing it.","args":["value"]},"text.trim":{"description":"Remove leading and trailing whitespace.","args":["text"]},"text.replace":{"description":"Replace literal text; no regular expressions.","args":["text","find","replacement"]},"text.join":{"description":"Join an array of text values.","args":["items","separator"]},"image.thicken-lines":{"description":"Expand dark outlines while preserving other colors.","args":["image","thickness","threshold"]}}. Types include text,number,integer,boolean,json,image,audio,video,script,text[]. Include test {name,input,expected} where expected is output bindings.
 
+### Feature map
+
+Every Block lists its separate tools in manifest.features, one entry per tool or mode a person could ask for: {"id":"reaction-gifs","label":"Reaction GIFs","does":"Search GIFs and drop one over a clip.","asks":["add a fire gif over my car","reaction gif when he laughs"]}. Use 1–24 entries; id is lowercase with hyphens, label at most 40 characters, does at most 160, asks 1–8 short requests in a customer's words. A Block that really does one job has one entry. Rewrite the starting entry create writes (it copies the description), or the gate fails. When refining or remixing, add, change or remove entries in the same change as the tool, and keep the ids of tools that stay.
+
 ### Port meanings
 
 For each newly created Block, declare the meaning of every input and output in its manifest contract, not just a physical type. Each input needs semantic, required:boolean and a short plain-language description. Each output needs semantic and a short description. Use lowercase snake_case or dotted semantic names, such as company_profile or email_subject; different meanings are not interchangeable merely because both are text. If an existing role is present, semantic must equal that role. Reuse an exact existing meaning only when the information actually has that meaning. Describe structured fields with schema when their shape matters: for example {name:"string",website:"string",industry:"string?"}. Supported schema fields are string/text, number, integer, boolean, object, json, arrays of those types, and optional fields with ?. Declare sources only when a requirement restricts where its answer may come from: upstream, project, adapter, chat, default, user or external. Do not mark a credential as ordinary text or put secrets in defaults. Contracts describe information; they never authorize network access, model calls, project edits, credit spending or new runtime APIs. Keep existing imported, installed and base Block contracts unchanged; do not silently relabel old published contracts to make a connection appear compatible. New contracts must match actual code and fixtures.
@@ -12288,6 +12309,10 @@ Every finished Block must support automatic remixing through the standard SDK co
 
 A Block package is StillMade SDK 0.1.0 JSON. Prefer {manifest,recipe,tests} for supported operations. Otherwise use {manifest,code,tests} with runtime:"javascript": code is a synchronous function body receiving input and returning declared output bindings, e.g. return {text:input.text.toUpperCase()}. JavaScript runs in isolated QuickJS: no fetch, DOM, Node APIs, modules, dependencies, timers, or host services; no promises, imports, require, eval or Function. Limits: 500 ms execution, 16 MiB heap, 256 KiB code, 4 MiB JSON I/O. Include concrete passing fixtures that reflect the requested behavior, including an edge case; never approximate a hosted model call with fabricated deterministic output. Manifest fields: schemaVersion:1,sdkVersion:"0.1.0",id:"creator.name",version:"1.0.0",name,description,kind:"task",runtime:"recipe", "javascript", "comfyui", or "capability",inputs/outputs as named {type,default?,min?,max?,role?,primary?}. Usually mark one primary input and output with primary:true. Semantic roles such as source_image and character_reference are distinct and must never be guessed,permissions:{project:[],network:[],filesystem:[],secrets:[]},ui:[{control,port}]. Recipe: {schemaVersion:1,steps:[{id,op,args}],outputs}. References: {"$input":"port"}, {"$step":"step-id"}. Supported operations: {"value.copy":{"description":"Copy a JSON value without changing it.","args":["value"]},"text.trim":{"description":"Remove leading and trailing whitespace.","args":["text"]},"text.replace":{"description":"Replace literal text; no regular expressions.","args":["text","find","replacement"]},"text.join":{"description":"Join an array of text values.","args":["items","separator"]},"image.thicken-lines":{"description":"Expand dark outlines while preserving other colors.","args":["image","thickness","threshold"]}}. Types include text,number,integer,boolean,json,image,audio,video,script,text[]. Include test {name,input,expected} where expected is output bindings.
 
+### Feature map
+
+Every Block lists its separate tools in manifest.features, one entry per tool or mode a person could ask for: {"id":"reaction-gifs","label":"Reaction GIFs","does":"Search GIFs and drop one over a clip.","asks":["add a fire gif over my car","reaction gif when he laughs"]}. Use 1–24 entries; id is lowercase with hyphens, label at most 40 characters, does at most 160, asks 1–8 short requests in a customer's words. A Block that really does one job has one entry. Rewrite the starting entry create writes (it copies the description), or the gate fails. When refining or remixing, add, change or remove entries in the same change as the tool, and keep the ids of tools that stay.
+
 ### Port meanings
 
 For each newly created Block, declare the meaning of every input and output in its manifest contract, not just a physical type. Each input needs semantic, required:boolean and a short plain-language description. Each output needs semantic and a short description. Use lowercase snake_case or dotted semantic names, such as company_profile or email_subject; different meanings are not interchangeable merely because both are text. If an existing role is present, semantic must equal that role. Reuse an exact existing meaning only when the information actually has that meaning. Describe structured fields with schema when their shape matters: for example {name:"string",website:"string",industry:"string?"}. Supported schema fields are string/text, number, integer, boolean, object, json, arrays of those types, and optional fields with ?. Declare sources only when a requirement restricts where its answer may come from: upstream, project, adapter, chat, default, user or external. Do not mark a credential as ordinary text or put secrets in defaults. Contracts describe information; they never authorize network access, model calls, project edits, credit spending or new runtime APIs. Keep existing imported, installed and base Block contracts unchanged; do not silently relabel old published contracts to make a connection appear compatible. New contracts must match actual code and fixtures.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stillmade-sdk",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "StillMade Block SDK, CLI and examples",
   "license": "PolyForm-Shield-1.0.0",
   "type": "module",

package/packages/block-cli/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import {blockFeatures} from '../block-sdk/feature-map.js';
 import {assertRemixReady} from '../block-sdk/remix-policy.js';
 import {remixBlock,bundledRemixSource,assertRemixAttribution} from '../block-platform/block-remix.js';
 import {verifyPortableSources} from '../block-sdk/portable-github.js';
@@ -200,6 +201,8 @@ export async function main(rawArgs) {
   if (command === 'create') {
     if(args.length<2)throw Object.assign(new Error('Name the folder to create: stillmade-block create my-block [template]'),{code:'USAGE'});
     const template=templateNamed(extra),files=await template.files();
+    // Every new Block starts with a feature map (one entry from its name and description) for the builder to rewrite as it grows.
+    {const created=JSON.parse(files['stillmade.block.json']);if(!created.features&&!created.stages){created.features=blockFeatures(created).map(({source,...feature})=>feature);files['stillmade.block.json']=`${JSON.stringify(created,null,2)}\n`;}}
     // Editors pick up the generated types for the view, src/run.js and module code.
     files['stillmade-env.d.ts']=blockTypeDeclarations(JSON.parse(files['stillmade.block.json']));
     files['jsconfig.json']=`${JSON.stringify({compilerOptions:{target:'ES2022',module:'ESNext',moduleResolution:'Bundler',lib:['ES2022','DOM'],jsx:'react-jsx',checkJs:false},include:['src','module','stillmade-env.d.ts']},null,2)}\n`;
@@ -208,7 +211,7 @@ export async function main(rawArgs) {
     const names=['stillmade.block.json',...Object.keys(files).filter(name=>name!=='stillmade.block.json')];
     for(const name of names){await mkdir(dirname(join(path,name)),{recursive:true});await writeFile(join(path,name),files[name],{flag:'wx'});}
     // Coding agents read command output: restate the readiness rule where they will see it.
-    return { created: path, sdkVersion: '0.1.0', template:template.name, runtime:template.runtime, files:names, next: 'Build the Block, then run `stillmade-block gate .`. Do not call the Block ready until the gate passes; report the status it prints.' };
+    return { created: path, sdkVersion: '0.1.0', template:template.name, runtime:template.runtime, files:names, next: 'Build the Block and write its feature map (`manifest.features`: one entry per thing it can do), then run `stillmade-block gate .`. Do not call the Block ready until the gate passes; report the status it prints.' };
   }
   if (command === 'gate') {
     // Every new or edited Block in a folder must pass readiness before anyone calls it ready.

package/packages/block-cli/ready-gate.js

@@ -84,6 +84,12 @@ const summarize=readiness=>(readiness?.items||[]).filter(item=>['failed','blocke
 async function judge(path,main){
  try{
   const readiness=await main(['ready',path]);
+  // Every new or edited Block carries its feature map (builder-contract); search, matching and its listing read it.
+  const manifest=(await main(['inspect',path]).catch(()=>null))?.manifest;
+  // The starting map create writes (one entry copied from the description) does not count until it is rewritten.
+  const placeholder=features=>features.length===1&&features[0].id==='main'&&features[0].asks?.length===1&&features[0].asks[0]===features[0].does;
+  if(PASSING.has(readiness.status)&&manifest&&!(Array.isArray(manifest.features)&&manifest.features.length&&!placeholder(manifest.features)))
+   return {ok:false,status:'NO FEATURE MAP',failures:['Add manifest.features: one entry per separate thing the Block can do, each with id, label, does and asks (requests in a customer\'s words). StillMade search, matching and the listing read it.'],limitations:(readiness.limitations||[]).length};
   return {ok:PASSING.has(readiness.status),status:readiness.status,failures:summarize(readiness),limitations:(readiness.limitations||[]).length};
  }catch(error){
   if(/^ready checks one Block package/.test(error.message)){
@@ -119,7 +125,7 @@ export async function runReadyGate({root=process.cwd(),main}={}){
 
 export function gateMessage(verdict){
  const lines=verdict.failing.map(result=>`- ${result.package} (${result.status}):\n${result.failures.map(failure=>`    ${failure}`).join('\n')||'    readiness check failed'}`);
- return `StillMade readiness gate: ${verdict.failing.length} Block${verdict.failing.length===1?'':'s'} you changed ${verdict.failing.length===1?'is':'are'} not ready.\n${lines.join('\n')}\nFix these and re-run \`node packages/block-cli/cli.js ready <folder>\`. Do not tell the user a Block is ready, done or working while this gate fails. If you cannot fix it, say plainly that the Block is NOT ready and list these failures.`;
+ return `StillMade readiness gate: ${verdict.failing.length} Block${verdict.failing.length===1?'':'s'} you changed ${verdict.failing.length===1?'is':'are'} not ready.\n${lines.join('\n')}\nFix these and re-run \`stillmade-block ready <folder>\` (\`npx stillmade-block ready <folder>\` in an npm project). Do not tell the user a Block is ready, done or working while this gate fails. If you cannot fix it, say plainly that the Block is NOT ready and list these failures.`;
 }
 
 /** Hook entry. `agent` is claude, cursor or plain. Returns {exitCode, stdout}. */

package/packages/block-sdk/builder-contract.js

@@ -9,7 +9,7 @@
 import {HOSTED_OPERATION_NAMES} from './contracts.js';
 
 export const BUILDER_CONTRACT_ID='stillmade.block-builder';
-export const BUILDER_CONTRACT_VERSION='1.5.4';
+export const BUILDER_CONTRACT_VERSION='1.6.1';
 export const BUILDER_CONTRACT_STAMP=`${BUILDER_CONTRACT_ID}@${BUILDER_CONTRACT_VERSION}`;
 export const BUILDER_CONTRACT_DOCS_PATH='/docs/build/block-builder-contract';
 // Block names appear in step bars, cards and pickers; new releases keep them short.
@@ -46,6 +46,9 @@ const SECTIONS=Object.freeze([
  rule('compose','both',
   'Blocks compose: give every port a type, `semantic` and description (a `video` input with semantic `source_video`, never `inputPath: text`), one primary input and output, and outputs that are reusable StillMade values. The resolver fills inputs; users never wire JSON, IDs or paths.',
   'A Block is one job: not a mini-app of many jobs and not a fragment of one. Its outputs become other Blocks\' inputs and its inputs come from other Blocks, project context or the user. Use the typed port system: shared StillMade types (`image`, `video`, `audio`, `asset`, `script`, `shot[]`, ...), a `semantic` meaning on every port, `required` and a short `description`. Mark exactly one primary input and one primary output so Project Type Steps connect automatically, and use `kind: "task"`: a `workspace` Block owns a project document and is never connected automatically. Inputs marked `context` read the project and cannot receive a connection from another Step. Output reusable StillMade values: media references (`{kind,assetId,versionId,url}`) and structured production values with `schemaVersion: 1`, preserving provenance, versions and relationships downstream Blocks need. Never make ordinary users wire JSON, copy IDs, understand internal paths or translate one Block\'s output into another: `createUniversalResolver()` (the same engine as the Project Type composer) resolves inputs from compatible upstream outputs, permitted project context and, for optional non-context inputs, `StillMade.requestFromUser`.'),
+ rule('feature-map','block',
+  'Keep `manifest.features` current: one {id,label,does,asks} per separate tool or mode, with requests it answers; never one the code lacks.',
+  'Every Block carries a feature map in `manifest.features`, written by whoever builds it while they build, so the person never writes it. Add one entry for each separate thing a person could ask for: a tool, a mode, a preset family or a kind of result (an editor\'s reaction GIFs, its motion presets, a recorder\'s screen recording), not one entry covering several tools. Each entry has a lowercase `id`, a `label` of 40 characters or fewer, `does` (what it does, 160 characters or fewer) and `asks`: 1–8 short requests in a customer\'s own words that this feature answers ("add a fire gif over my car"). `operation` names an id in the Block\'s own `manifest.operations` (omit it when there are none); `inputs`/`outputs` name declared ports. The gate fails a Block without one. Add or update the entry in the same change that adds or alters a tool, and remove it when the tool goes. List only what the code really does; listings are generated from this map, nobody can edit them, and StillMade matches requests to features. Features are not tested at publish: each shows as new until real use proves it.'),
  rule('platform-primitives','block',
   `Use SDK and host capabilities (hosted operations: ${hostedOperations}) before Block-local code; never rebuild assets, pickers, auth, credits, secrets, permissions, progress, sharing, persistence or providers inside a Block.`,
   `Prefer, in order: an SDK capability; a documented host capability (the hosted operations are ${hostedOperations}; connected third-party apps go through \`connection.execute\`); an approved dependency the SDK already bundles; small Block-local code. Do not duplicate what StillMade provides. A Block never contains its own asset system, file picker, authentication, project-context system, input resolver, Block connection system, credit system, secrets store, permission system, progress system, multiplayer system, persistence system, model-provider abstraction or execution protocol.`),
@@ -130,7 +133,7 @@ export const BUILDER_CONTRACT=Object.freeze({
  gapClasses:GAP_CLASSES,
 });
 
-const SECTION_TITLES=Object.freeze({'grounded-text':'Only supplied facts','source-of-truth':'Source of truth','reuse-first':'Reuse first','block-scope':'One job per Step','capability-contract':'Define the capability first','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','naming':'Name it briefly','ui':'Interface','multiplayer':'Shared editing','external-services':'External services','dependencies':'Dependencies','security':'Security','lifecycle':'Execution lifecycle','errors':'Useful failures','adapt-to-platform':'Adapt to the platform','verification':'What StillMade verifies','project-types':'Project Types','readiness-report':'Readiness report'});
+const SECTION_TITLES=Object.freeze({'grounded-text':'Only supplied facts','source-of-truth':'Source of truth','reuse-first':'Reuse first','block-scope':'One job per Step','capability-contract':'Define the capability first','feature-map':'Feature map','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','naming':'Name it briefly','ui':'Interface','multiplayer':'Shared editing','external-services':'External services','dependencies':'Dependencies','security':'Security','lifecycle':'Execution lifecycle','errors':'Useful failures','adapt-to-platform':'Adapt to the platform','verification':'What StillMade verifies','project-types':'Project Types','readiness-report':'Readiness report'});
 const inScope=(scope,wanted)=>wanted==='all'||scope==='both'||scope===wanted;
 
 /** Render the contract for a model prompt ('compact'), a guide ('full') or an SDK folder ('agents-md'). */

package/packages/block-sdk/contracts.js

@@ -25,6 +25,7 @@ import {validateDesktopTools} from './desktop-tools.js';
 import {isFileValue,isDocumentValue,isTableValue,isUrlValue,isDateValue,isColorValue} from './data-values.js';
 import {networkDeclarations,connectionDeclarations} from './network.js';
 import {triggerProblems} from './triggers.js';
+import {featureMapErrors} from './feature-map.js';
 const connectionsValid=entries=>{try{connectionDeclarations(entries);return true;}catch{return false;}};
 const networkProblem=entries=>{try{networkDeclarations(entries);return '';}catch(error){return error.message;}};
 const networkValid=entries=>!networkProblem(entries);
@@ -112,8 +113,9 @@ export function validateManifest(manifest, { builtIn = false } = {}) {
   const check = (ok, path, message) => { if (!ok) errors.push({ path, message }); };
   try { safeDocument(manifest); } catch (e) { return { valid: false, errors: [{ path: '$', message: e.message }] }; }
   if (!plain(manifest)) return { valid: false, errors: [{ path: '$', message: 'Manifest must be an object' }] };
-  const allowed = ['schemaVersion', 'id', 'name', 'version', 'sdkVersion', 'description', 'kind', 'inputs', 'outputs', 'permissions', 'runtime', 'jobs', 'ui', 'uiLayout', 'entry', 'license', 'provenance', 'summary', 'category', 'platforms', 'state', 'storage', 'semantics', 'desktopTools', 'operations', 'sharedWork', 'triggers'];
+  const allowed = ['schemaVersion', 'id', 'name', 'version', 'sdkVersion', 'description', 'kind', 'inputs', 'outputs', 'permissions', 'runtime', 'jobs', 'ui', 'uiLayout', 'entry', 'license', 'provenance', 'summary', 'category', 'platforms', 'state', 'storage', 'semantics', 'desktopTools', 'operations', 'sharedWork', 'triggers', 'features'];
   for (const key of Object.keys(manifest)) check(allowed.includes(key), key, 'Unknown manifest field');
+  for (const message of featureMapErrors(manifest)) check(false, 'features', message);
   if(manifest.sharedWork!==undefined){try{validateSharedWorkContract(manifest.sharedWork);}catch(error){check(false,'sharedWork',error.message);}check(manifest.permissions?.project?.includes('work.shared'),'sharedWork','Declare the work.shared permission');}
   if(manifest.permissions?.project?.includes('work.shared'))check(manifest.sharedWork!==undefined,'permissions.project','Declare the shared-work contract');
   if(manifest.semantics!==undefined)for(const message of semanticDeclarationErrors(manifest.semantics))check(false,'semantics',message);

package/packages/block-sdk/feature-map.js

@@ -0,0 +1,58 @@
+// A Block's feature map: the separate things it can do (an Editor's reaction
+// GIFs, motion presets, screen recording), each with the requests it answers.
+// The builder AI writes `manifest.features` while it builds; creators never
+// write it by hand. Blocks without one get a map derived from their operations
+// and outputs, so every Block can be matched feature by feature. Listings are
+// generated from this map and are not editable. Trust comes from real use (see
+// block-platform/feature-usage.js), never from a publish-time test run.
+import {plain} from './contracts-core.js';
+
+export const FEATURE_MAP_LIMITS=Object.freeze({features:24,id:48,label:40,does:160,asks:8,ask:80});
+const FEATURE_ID=/^[a-z][a-z0-9-]{0,47}$/;
+const FEATURE_KEYS=['id','label','does','asks','operation','inputs','outputs'];
+
+/** Validation messages for `manifest.features` ([] when valid or absent). */
+export function featureMapErrors(manifest){
+ const features=manifest?.features;
+ if(features===undefined)return [];
+ if(!Array.isArray(features)||features.length===0||features.length>FEATURE_MAP_LIMITS.features)return [`Declare 1–${FEATURE_MAP_LIMITS.features} features`];
+ const errors=[],ids=new Set(),operations=new Set((Array.isArray(manifest.operations)?manifest.operations:[]).map(operation=>operation?.id));
+ const text=(value,max)=>typeof value==='string'&&value.trim().length>0&&value.length<=max;
+ for(const [index,feature] of features.entries()){
+  const at=`features.${plain(feature)&&typeof feature.id==='string'?feature.id:index}`;
+  if(!plain(feature)){errors.push(`${at}: Expected an object`);continue;}
+  const unknown=Object.keys(feature).filter(key=>!FEATURE_KEYS.includes(key));
+  if(unknown.length)errors.push(`${at}: Unknown feature field ${unknown.join(', ')}`);
+  if(!FEATURE_ID.test(feature.id||'')||ids.has(feature.id))errors.push(`${at}.id: Use a unique lowercase id such as "reaction-gifs"`);
+  ids.add(feature.id);
+  if(!text(feature.label,FEATURE_MAP_LIMITS.label))errors.push(`${at}.label: Name the feature in ${FEATURE_MAP_LIMITS.label} characters or fewer`);
+  if(!text(feature.does,FEATURE_MAP_LIMITS.does))errors.push(`${at}.does: Say what it does in ${FEATURE_MAP_LIMITS.does} characters or fewer`);
+  if(!Array.isArray(feature.asks)||feature.asks.length===0||feature.asks.length>FEATURE_MAP_LIMITS.asks||!feature.asks.every(ask=>text(ask,FEATURE_MAP_LIMITS.ask)))errors.push(`${at}.asks: Give 1–${FEATURE_MAP_LIMITS.asks} example requests of up to ${FEATURE_MAP_LIMITS.ask} characters`);
+  if(feature.operation!==undefined&&!operations.has(feature.operation))errors.push(`${at}.operation: Name a declared operation`);
+  for(const direction of ['inputs','outputs']){
+   if(feature[direction]===undefined)continue;
+   const ports=feature[direction];
+   if(!Array.isArray(ports)||ports.length>16||!ports.every(port=>typeof port==='string'&&Object.hasOwn(manifest[direction]||{},port)))errors.push(`${at}.${direction}: Name declared ${direction} only`);
+  }
+ }
+ return errors;
+}
+
+const slug=value=>String(value||'').toLowerCase().replace(/[^a-z0-9]+/g,'-').replace(/^-|-$/g,'').slice(0,FEATURE_MAP_LIMITS.id).replace(/^[^a-z]+/,'')||'main';
+const clip=(value,max)=>{const text=String(value||'').replace(/\s+/g,' ').trim();return text.length<=max?text:text.slice(0,max-1).trimEnd()+'…';};
+
+/**
+ * The Block's feature map, always non-empty for a valid manifest. Declared
+ * features are used as written; otherwise each operation becomes a feature,
+ * and a Block with no operations is one feature named after the Block.
+ * Every entry carries `source`: 'declared' or 'derived'.
+ */
+export function blockFeatures(manifest){
+ if(!plain(manifest))return [];
+ if(Array.isArray(manifest.features)&&manifest.features.length&&featureMapErrors(manifest).length===0)
+  return manifest.features.map(feature=>({...feature,asks:[...feature.asks],source:'declared'}));
+ const operations=Array.isArray(manifest.operations)?manifest.operations.filter(plain):[];
+ if(operations.length)return operations.map(operation=>({id:slug(operation.id),label:clip(operation.label,FEATURE_MAP_LIMITS.label),does:clip(operation.description||operation.label,FEATURE_MAP_LIMITS.does),asks:[clip(operation.label,FEATURE_MAP_LIMITS.ask)],operation:operation.id,source:'derived'}));
+ const outputs=Object.keys(plain(manifest.outputs)?manifest.outputs:{});
+ return [{id:'main',label:clip(manifest.name||manifest.id,FEATURE_MAP_LIMITS.label),does:clip(manifest.description||manifest.name,FEATURE_MAP_LIMITS.does),asks:[clip(manifest.description||manifest.name,FEATURE_MAP_LIMITS.ask)],...(outputs.length?{outputs:outputs.slice(0,16)}:{}),source:'derived'}];
+}

package/packages/block-sdk/index.d.ts

@@ -21,8 +21,17 @@ export interface FrameView { runtime: 'frame'; html: string; css?: string; theme
 export interface BlockPackage { portable?: PortableMetadata; manifest: Manifest; view?: BlockView|FrameView; code?: string; module?: ModuleDescriptor; comfyui?: ComfyWorkflow; capability?: ConnectedCapability|TextGenerationCapability|SpeechCapability|TranscriptionCapability|ImageGenerationCapability|VideoGenerationCapability|ImageDescriptionCapability|TimelineProposalCapability; recipe?: { schemaVersion: 1; steps: { id: string; op: string; args: Record<string, unknown> }[]; outputs: Record<string, unknown> }; tests: { name: string; input: Record<string, unknown>; expected?: Record<string, unknown>; state?: BlockState; expectedState?: BlockState; expectations?: Record<string, ConnectedResultExpectation|ComfyImageExpectation|CapabilityTextExpectation|CapabilityAudioExpectation|CapabilityTranscriptExpectation|CapabilityImageExpectation|CapabilityVideoExpectation|CapabilityTimelineExpectation> }[]; }
 /** Named sandbox action with fixed declared input settings and produced ports. */
 export interface BlockOperation {id:string;label:string;description:string;inputs:Record<string,string|number|boolean>;outputs:string[]}
+/** One entry of a Block's feature map: a separate thing the Block can do and the requests it answers. */
+export interface BlockFeature {id:string;label:string;does:string;asks:string[];operation?:string;inputs?:string[];outputs?:string[]}
+export const FEATURE_MAP_LIMITS: Readonly<{features:24;id:48;label:40;does:160;asks:8;ask:80}>;
+/** Validation messages for `manifest.features`; [] when valid or absent. */
+export function featureMapErrors(manifest:unknown):string[];
+/** The declared feature map, or one derived from operations or the Block itself. */
+export function blockFeatures(manifest:unknown):(BlockFeature&{source:'declared'|'derived'})[];
 export interface Manifest {
   operations?: BlockOperation[];
+  /** Feature map: what the Block can do, tool by tool. Written by the builder; listings are generated from it. */
+  features?: BlockFeature[];
   storage?: import('./block-storage.js').BlockStorageDeclaration;
   /** Events the Block can run on by itself, once the project owner turns them on. */
   triggers?: import('./triggers.js').BlockTrigger[];

package/packages/block-sdk/index.js

@@ -6,6 +6,7 @@ export * from './workflow-events.js';
 export * from './workflow-approvals.js';
 export * from './package-semantics.js';
 export {defineBlock} from './define-block.js';
+export {blockFeatures,featureMapErrors,FEATURE_MAP_LIMITS} from './feature-map.js';
 export * from './adapter-registry.js';
 export * from './desktop-permissions.js';
 export * from './desktop-tools.js';