stillmade-sdk 0.1.4 → 0.1.6

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.0.0)
+## Block builder contract (stillmade.block-builder@1.3.0)
 
-Contract `stillmade.block-builder@1.0.0`. 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.3.0`. 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
 
@@ -14,13 +14,27 @@ Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` con
 
 Before building, check what already exists (`find_existing_blocks` over MCP, or the Marketplace and your library) by the inputs, results and operations the goal needs. Use an installed or reviewed Block that already does it; remix a close one so its license, notices and creator credit stay attached; chain existing Blocks and build only the missing step. Never republish another creator's source without remix lineage: public copies are refused. Build a new Block when nothing fits or the person asks for their own version, and say which similar Blocks you considered.
 
+### One job per Step
+
+A Step is one job: the work between two moments where a person or the outside world must see the result. Start a new Step only at one of three points; everything else is a part of the neighboring Step.
+
+1. **A person works with the result**: reads, edits, picks or approves it (a workspace Block such as a script, a Canvas or an Editor, or an approval). That is why Chat, Bible, Canvas and Editor are four Steps.
+2. **Finding new things turns into handling each one**: the trigger (a schedule or an app event), the app read, its filter and "only new" are the first job; what is done with each item is the next job. A trigger is a setting of the first job, never a Step of its own.
+3. **The result leaves StillMade**: it is sent, posted, published, paid or written into another app. Consecutive writes to the same app, with the glue that shapes data for them, are one job.
+
+A part that only runs in the desktop app cannot share a Step with cloud parts. Before adding a Step, name which of the three reasons makes it separate; if none applies, make it a part of a neighbor. A Step nobody would ever open must not exist on its own. Prefer an app task's own filter (a Gmail query such as `has:attachment filename:png`) to an AI check, and use AI decide only for judgement.
+
+Inside one job, each capability stays its own part: a capability Block performs exactly one hosted operation and a connector one app task, so every part keeps its own permission, approval and credit rules, and StillMade groups the parts of one job into one Step (`groups` in the Project Type). Never invent a combined runtime. When one Block can do the whole job with documented primitives (a JavaScript Block doing several local transforms, a workspace owning its whole document), build it as one Block.
+
+Examples: "every new email with an image becomes a generated image" is two Steps, "Gmail · New emails with images" (When, fetch with an image filter, only new) and "Image from email" (AI write, Generate image); listing When, Fetch, Only new, AI decide, Continue only if, AI write and Generate image as seven Steps splits one job into its parts. "A new Meta lead goes to HubSpot" is three Steps: "Meta Ads · New leads", "Qualify lead" and "HubSpot · Add contact".
+
 ### Define the capability first
 
-Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible and keep implementation details out of it.
+Translate the request into an explicit capability contract before implementation: what the Block does; each input with its type, meaning and whether it is required (prefer optional settings with safe defaults over extra required questions); each output with its type and meaning; persistent state; project context it reads; permissions; UI; long-running behavior; expected failures; cancellation; determinism; and whether it needs hosted models, media, desktop tools or shared editing. Keep the public interface as small and general as possible (few required inputs, one primary output) and keep implementation details out of it; small means a small interface, never a fragment of a job. A Block that generates images, video or speech declares only its prompt and output: every Step that runs it gets the host’s generation settings (model, quality, length and resolution, voice, speed, how many), saved with the Step, changed on its page or by Chat, and shown with their cost before each run.
 
 ### Blocks compose
 
-A Block is not a mini-app. 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`.
+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`.
 
 ### Use platform primitives
 
@@ -30,9 +44,13 @@ Prefer, in order: an SDK capability; a documented host capability (the hosted op
 
 Never make a Block look functional through hard-coded local paths, developer-machine dependencies, undocumented environment variables, admin or database access, hidden core modifications, direct database writes, fake or mocked production results, hand-prepared test assets that hide incompatibilities, credentials in code, or assumptions about one user's machine. The finished Block must work through the same interfaces available to any installed Block; `permissions.network`, `permissions.filesystem` and `permissions.secrets` must be empty arrays.
 
+### Name it briefly
+
+Give the Block a short, plain name of 40 characters or fewer that says what it does ("Captioned Clip", not "Captioned Business Clip Generator With Review"). The name appears in step bars, Project Type cards and pickers, so put the detail in the description instead. New releases with a longer name do not pass readiness.
+
 ### Interface
 
-If the capability needs UI, use the Block UI SDK: generated `manifest.ui` controls first; a sandboxed custom view (`view.html`/`view.css`/`view.js`) only when the core interaction genuinely needs one. Expose the capability, not the implementation: meaningful controls, sensible defaults, preview, direct manipulation, progress, clear errors and visible outputs. Do not show raw JSON, internal IDs, filesystem details, provider terminology or developer settings unless the Block is itself a developer tool. Follow the host appearance (Light, Dark and White) and the mobile layout contract: one interface for every screen size that fits a 320 CSS-pixel phone without horizontal scrolling.
+If the capability needs UI, use the Block UI SDK: generated `manifest.ui` controls first; a sandboxed custom view (`view.html`/`view.css`/`view.js`) only when the core interaction genuinely needs one. Expose the capability, not the implementation: meaningful controls, sensible defaults, preview, direct manipulation, progress, clear errors and visible outputs. Do not show raw JSON, internal IDs, filesystem details, provider terminology or developer settings unless the Block is itself a developer tool. When a person chooses among options they need to hear or see (voices, music, sounds, fonts, looks, colors, templates or images), let them preview each option before choosing: a sample to play or a thumbnail, from the Block's own files or the host's free samples, never a paid generation. Leave previews out only when the builder states there is nothing to preview. Choices StillMade owns, such as voices and models in the run review, already show their samples. Follow the host appearance (Light, Dark and White) and the mobile layout contract: one interface for every screen size that fits a 320 CSS-pixel phone without horizontal scrolling.
 
 ### Shared editing
 
@@ -68,11 +86,11 @@ StillMade runs the readiness check on every Block it admits: manifest and contra
 
 ### Project Types
 
-A Project Type is an ordered production workflow. Each Step's primary output must be a compatible input for the next Step, secondary values come from permitted project context, and every member Block obeys this contract. Install Blocks into a realistic Project Type: project chat must understand each Step, inputs must resolve intuitively, outputs and execution state must be visible, failures must be diagnosable, and the user must be able to continue through the workflow.
+A Project Type is an ordered production workflow. Each Step's primary output must be a compatible input for the next Step, secondary values come from permitted project context, and every member Block obeys this contract. Install Blocks into a realistic Project Type: project chat must understand each Step, inputs must resolve intuitively, outputs and execution state must be visible, failures must be diagnosable, and the user must be able to continue through the workflow. Group the parts of one job into one Step instead of listing helper parts as Steps; most automations are two to four Steps.
 
 ### Readiness report
 
-Finish with a Block Readiness Report: capability, contract (inputs, outputs, permissions, dependencies), platform APIs used, tests actually performed and their results, the composition test (upstream, Block, downstream), known limitations, unsupported requirements and any platform gap with its smallest general primitive. Choose exactly one status: PRODUCTION READY (every applicable check passed), READY WITH DOCUMENTED LIMITATIONS (works reliably within stated boundaries), BLOCKED BY PLATFORM CAPABILITY (needs a missing generic primitive) or FAILED. Never label a Block production ready to satisfy a request, and never claim a check ran when it did not.
+Finish with a Block Readiness Report: capability, contract (inputs, outputs, permissions, dependencies), platform APIs used, tests actually performed and their results, the composition test (upstream, Block, downstream), known limitations, unsupported requirements and any platform gap with its smallest general primitive. Report exactly one status, the one StillMade's readiness check returned (`ready` in the SDK CLI, `check_block_readiness` over MCP), never one you chose: PRODUCTION READY (every applicable check passed), READY WITH DOCUMENTED LIMITATIONS (works reliably within stated boundaries), BLOCKED BY PLATFORM CAPABILITY (needs a missing generic primitive) or FAILED. Never label a Block production ready to satisfy a request, and never claim a check ran when it did not.
 
 ### Definition of done
 
@@ -348,9 +366,10 @@ of the SDK URL the user supplied, not a guessed production hostname or localhost
 - Search `/api/public-listings/discover?kind=block&search=<encoded-query>` for
   Blocks, or use `kind=type` for Project Types. Follow `nextCursor` with `after`
   when more results are relevant; a single page is not the complete catalog.
-- Use returned listing identities and versions to inspect
-  `/api/public-listings/<kind>/<id>/<version>/source.json` where source inspection
-  is permitted. Read the real manifest and any declared dependency packages.
+- Use returned listing identities and versions to read
+  `/api/public-listings/<kind>/<id>/<version>/metadata.json`: its name, description
+  and typed inputs and outputs. A Block's code is private to its creator, so build
+  on what it takes and makes, never on its source.
 - In an offline SDK checkout, `packages/block-platform/catalog.js` provides bundled
   first-party examples. It is a snapshot, not the complete live Marketplace.
 

package/PORTABLE.md

@@ -1,4 +1,4 @@
-Every finished Block must support automatic remixing through the standard SDK contract. Include complete editable runtime source/configuration, typed inputs/outputs, UI controls, fixtures, and a supported permissive manifest.license with its complete real copyright/license notice in manifest.provenance.notice (or verified portable evidence). Do not disable remixing or source inspection. No custom remix endpoint or host callback is needed. Preserve inherited source, notices and lineage. Never invent ownership, copyright holders or permission, or apply a new license to unresolved third-party source; return unsupported with a clear licensing reason instead. The shared SDK admission validator enforces this requirement.
+Every finished Block must support automatic remixing through the standard SDK contract. Include complete editable runtime source/configuration, typed inputs/outputs, UI controls, fixtures, and a supported permissive manifest.license with its complete real copyright/license notice in manifest.provenance.notice (or verified portable evidence). Do not disable remixing. The code stays private to its creator; others remix only through StillMade’s AI builder. No custom remix endpoint or host callback is needed. Preserve inherited source, notices and lineage. Never invent ownership, copyright holders or permission, or apply a new license to unresolved third-party source; return unsupported with a clear licensing reason instead. The shared SDK admission validator enforces this requirement.
 ## Understand StillMade and its Block ecosystem
 
 StillMade AI is an AI-assisted platform where people make things by using and
@@ -216,9 +216,10 @@ of the SDK URL the user supplied, not a guessed production hostname or localhost
 - Search `/api/public-listings/discover?kind=block&search=<encoded-query>` for
   Blocks, or use `kind=type` for Project Types. Follow `nextCursor` with `after`
   when more results are relevant; a single page is not the complete catalog.
-- Use returned listing identities and versions to inspect
-  `/api/public-listings/<kind>/<id>/<version>/source.json` where source inspection
-  is permitted. Read the real manifest and any declared dependency packages.
+- Use returned listing identities and versions to read
+  `/api/public-listings/<kind>/<id>/<version>/metadata.json`: its name, description
+  and typed inputs and outputs. A Block's code is private to its creator, so build
+  on what it takes and makes, never on its source.
 - In an offline SDK checkout, `packages/block-platform/catalog.js` provides bundled
   first-party examples. It is a snapshot, not the complete live Marketplace.
 

package/REMIX.md

@@ -34,7 +34,9 @@ copyright holders, repository commits or permission. Unresolved rights produce a
 blocked result. Never silently license someone else's source.
 
 Remixing is enabled by default. An explicit `remixPolicy` must permit remixing
-and must not set `sourceInspection: "no"`. Omit optional settings when defaults
+and must not set `sourceInspection: "no"`. A Block's code is private to its creator: no one else views or downloads it,
+and others change it only by describing changes to StillMade's AI builder.
+Omit optional settings when defaults
 are sufficient. The host creates the new identity, preserves the parent digest,
 source and notices, and presents the ordinary builder. Creators need no extra
 StillMade instructions. Project Edit retains compatible inputs and saved state;
@@ -56,8 +58,9 @@ remixable merely by adding metadata: they need an independent SDK implementation
 ## In StillMade
 
 Choose **Remix Block** on an exact public Block version, or **Remix this version**
-in Marketplace. Sign in, review its source, license and declared permissions,
-then confirm **Remix Block**. StillMade saves an account draft and opens Create.
+in Marketplace. Sign in, review its license and declared permissions, then
+confirm **Remix Block**. The code is never shown or downloadable; describe the
+change you want and StillMade's AI builder makes it. StillMade saves an account draft and opens Create.
 Nothing is installed, published, executed or charged by creating the draft.
 AI refinement edits the implementation, controls and fixtures while the host
 retains and restores immutable source evidence and ancestry. Evidence is not
@@ -65,7 +68,10 @@ charged against the editable-source prompt limit; the package size limit still
 applies. The resulting local Block receives the same admission checks as a
 portable artifact.
 The Versions tab shows ancestry and retained notices. Publishing the edited
-Block requires the normal validation, visibility choice and rights confirmation.
+Block requires the normal validation and rights confirmation. A remix of someone
+else's Block is released as a Block owned by the original creator, who keeps its
+code and earns from it; the remixer is credited and can use it right away. A
+remix is always available by link, never private.
 Public Block pages link to paginated newest and top remixes of that exact version.
 Top uses qualified production account counts for a 30-day window, hidden below
 ten accounts and rounded down to tens. Both views fall back to newest when
@@ -184,13 +190,13 @@ host-coupled workspaces retain their existing restrictions.
 - No payments, ancestor revenue allocation or provider dispatch during remix.
 
 
-## Public source inspection
+## Code stays private
 
-Source inspection settings on existing releases remain subject to their original
-access controls. For new Block admission, `sourceInspection: "no"` is rejected.
-Use `yes`, a supported `license-controlled` setting, or omit the field. Account
-and team visibility still determine who may retrieve a private package; remix
-support does not make private source public.
+A Block's code is private to its creator. Nobody else can view or download it:
+public pages, Marketplace and remixes never show it, and the source download
+works only for its creator and StillMade admins. An older `sourceInspection: "no"`
+still keeps that Block's releases private and its remix action off. Account and team visibility still determine who may use a
+private package.
 
 A source-access choice cannot replace legal evidence or revoke upstream rights.
 Existing immutable releases keep their established pins and access. Newly finished