stillmade-sdk 0.1.42 → 0.1.44

package/docs/build/tutorial.md

@@ -0,0 +1,52 @@
+# Tutorial: a React Block in 30 minutes
+
+You need Node.js 22 or newer and npm. Every step runs on your machine without
+an account until you import the Block.
+
+1. **Create the Block (3 minutes).** The SDK is one npm package on StillMade's
+   site; nothing else to download.
+
+   ```sh
+   npx --yes --package=https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.tgz stillmade-block create title-cards view-react
+   cd title-cards
+   npm install --save-dev https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.tgz   # the stillmade-block command
+   npm install                                                                       # React and esbuild
+   ```
+
+2. **Look around (1 minute).** The folder has the manifest
+   (`stillmade.block.json`), the logic (`module/main.js`, a module Block), the
+   interface (`src/view.jsx`, `src/view.css`, `src/view.html`, and
+   `src/view.config.json`, which makes it a frame view), fixtures and
+   TypeScript types.
+3. **Preview it (3 minutes).** `npm run build`, then `npm run dev`, and open
+   `http://127.0.0.1:4800`. Type two titles and choose **Make cards**: the cards
+   appear, and the console on the right shows the run.
+4. **Change it (8 minutes).** Add a prefix for every card.
+   - In `stillmade.block.json`, add an input:
+     `"prefix": {"type": "text", "required": false, "default": "", "semantic": "card_prefix", "description": "Text before each title."}`.
+   - In `module/main.js`, use it: `title: (input.prefix + title).slice(0, 120)`.
+   - In `src/view.jsx`, add a text field for the prefix (its own `useState`) and
+     send it: `StillMade.run({lines, prefix})`.
+   - Run `npx stillmade-block types .` so your editor knows the new input.
+
+   Each save rebuilds and reloads the preview.
+5. **Use a hosted operation and test it offline (5 minutes).** Ask a model for a
+   tagline.
+   - In `stillmade.block.json`, add `"capabilities": ["text.generate"]` to
+     `permissions` and an output:
+     `"tagline": {"type": "text", "semantic": "tagline", "description": "A short tagline."}`.
+   - In `module/main.js`:
+     `const tagline = await stillmade.hosted.run('text.generate', {prompt: 'Write a six-word tagline for: ' + titles.join(', '), maxTokens: 40});`
+     and return `tagline` with the cards.
+   - Record a reply in `tests/mocks.json`:
+     `{"hosted": {"text.generate": "Three scenes, one long road"}}`, and add
+     `"tagline": "Three scenes, one long road"` to each fixture's expected outputs.
+   - `npm test` passes offline and lists the stand-in that answered; the preview
+     uses it too. In StillMade, each call is priced and approved first.
+6. **Package and import (5 minutes).** Change the `id` in the manifest to your
+   own, then `npm run pack`, which writes
+   `<id>-1.0.0.stillmade-module.json`. In StillMade, open **Create**, choose
+   **Import**, select the file, review the checks and the preview, and confirm.
+7. **Publish (5 minutes).** Open the Block in Create, choose **Publish**, pick
+   who can use it, confirm you have the rights to its content and publish. See
+   [publishing](../distribute/publishing.md).

package/docs/build/typescript.md

@@ -0,0 +1,34 @@
+# TypeScript
+
+`stillmade-block types <folder>` writes `stillmade-env.d.ts` beside the
+manifest (`create` writes it too, with a `jsconfig.json`, and running `types`
+again replaces it after you change ports). It is self-contained and declares:
+
+- `BlockInputs` and `BlockOutputs`, one property per port, typed by port type:
+  `text`, `url`, `date` and `color` are strings, `number` and `integer` are
+  numbers, media ports are saved references, `file`, `document`, `table` and
+  `transcript` have their value shapes, a `json` or `object` port with a compact
+  schema (`{"points": "number[]"}`) gets that shape, and lists are arrays.
+  Optional inputs (`required: false` or a default) are optional properties.
+- The global `StillMade` in your interface, typed from the
+  [view bridge reference](../reference/view-bridge.md):
+  `StillMade.run(values: BlockInputs): Promise<BlockOutputs>`,
+  `StillMade.onInput(callback)` and the rest.
+- The global `input` in `src/run.js` (JavaScript Blocks).
+- `StillMadeModule` and `BlockRun` for a module entry:
+
+```ts
+import type {BlockRun} from '../stillmade-env';
+const run: BlockRun = async (input, stillmade) => {
+  stillmade.progress(0.5, 'Working');
+  return {summary: input.text.toUpperCase()};
+};
+export default run;
+```
+
+Bundle TypeScript with your bundler as usual (esbuild handles `.ts` and
+`.tsx`); StillMade runs the bundled JavaScript. The SDK's own declarations are
+in `packages/block-sdk/*.d.ts`; `blockTypeDeclarations(manifest)`,
+`portValueType(port)`, `schemaType(schema)` and `PORT_VALUE_TYPES` generate the
+file, and `VIEW_BRIDGE` (with `VIEW_BRIDGE_MEMBERS` and
+`viewBridgeReference()`) is the list of interface bridge members it types.

package/docs/build/video-generation.md

@@ -0,0 +1,61 @@
+# Hosted video generation
+
+Use `runtime: "capability"` and `permissions.capabilities: ["video.generate"]`. Declare one text, script or brief prompt input, up to two `image` inputs for the first and last frame, and one video output. Every video model the app's own Blocks use is available — Seedance 2.0 (and Fast, Mini), Kling 3.0 Turbo, Wan 2.6 Flash, Veo 3.1 Lite, Vidu Q3 Turbo and Wan 2.7 — with their durations, resolutions, aspect ratios, image-to-video and first-and-last-frame modes (see [generation models](../reference/generation-models.md)). Users pay with StillMade credits at StillMade's per-second price. The capability file is:
+
+```json
+{"schemaVersion":1,"operation":"video.generate","prompt":{"$input":"prompt"},
+ "firstFrame":{"$input":"start"},"lastFrame":{"$input":"end"},
+ "settings":{"model":"veo-3.1-lite","duration":6,"resolution":"720p","aspectRatio":"16:9","generateAudio":true},
+ "negativePrompt":"blur","seed":7,"output":"video"}
+```
+
+`settings`, `firstFrame`, `lastFrame`, `negativePrompt` and `seed` are optional; each setting must be one the model accepts (Veo locks 1080p to 8 seconds; Wan 2.7 needs a first frame). Never include provider endpoints, keys, prices or payment. The run dialog preselects the Block's defaults and the user may change them before seeing the exact price. The invocation is `{operation:"video.generate",prompt}` plus `firstFrame`, `lastFrame`, `negativePrompt` and `seed` when declared; frames must be the user's own saved images. Public trials use their separately reviewed acquisition policy and never account BYOK.
+
+The canonical output has `kind:"video"`, bounded `assetId`/`versionId`, a stored HTTPS or host media `url`, `mimeType:"video/mp4"`, measured `width`, `height`, `duration` in seconds and `bytes`. The host keeps the provider's MP4 byte-for-byte after measuring its container. SDK limits are 60 seconds, 256 MiB, at most 3,840 pixels on either axis and 8,294,400 pixels per frame. Validating this shape does not verify ownership or real video bytes; the host must inspect, store and verify them.
+
+Fixtures use `kind:"video"`, `format:"mp4"` and explicit `minDuration`, `maxDuration`, `minBytes`, `maxBytes`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` bounds. See `packages/block-sdk/video-generation-example.js`. Provider fixtures require approval; they are not deterministic equality tests. `validateGeneratedVideoReference`, `defaultCapabilityExpectations` and `validateCapabilityResult` are available through the SDK. Media receipts bind the owner, run, invocation, storage key and SHA-256 digest to the complete output reference. Guest code cannot issue those receipts.
+
+A host advertises only enabled operations. A valid package does not imply every deployment has video generation configured; unavailable hosts must reject it before billing or dispatch. Public video results use the same private media/claim lifecycle as other trial outputs and are retained when continuing in an account.
+
+
+### Authored state migration routes
+
+A new JavaScript Block release can optionally declare `manifest.state.migrations`
+for explicit upgrades of its Step memory. A route's `fromVersion` is an older
+positive state schema version; its destination is the enclosing `state.version`.
+For example, a declaration for state version 2 can contain:
+
+```json
+"migrations": [{
+  "fromVersion": 1,
+  "operations": [
+    { "op": "rename", "from": "count", "to": "completed" },
+    { "op": "default", "key": "labels", "value": [] },
+    { "op": "remove", "key": "temporary" }
+  ]
+}]
+```
+
+Operations run in order on safe ASCII top-level field names. Rename requires an
+existing source and absent destination; default writes only if absent; remove
+requires the field to exist. Nested values remain intact. There are at most 16
+distinct older-version routes and 64 operations per route. Combined declarations
+and every intermediate state each fit within 64 KiB. An empty operation list
+explicitly advances only the schema version. There is no implicit chaining,
+downgrade, deep-path transformation, expression evaluation or code execution.
+
+The portable SDK exports `validateStateMigrations(stateDeclaration)`,
+`stateMigrationRoute(manifest, fromVersion)`, and
+`migrateBlockState(previousManifest, nextManifest, savedState)`. The last returns
+`{state, operations, fromVersion, toVersion}` without modifying its inputs. Both
+manifests must describe the same JavaScript Block identity, with valid state
+contracts. Matching state versions use an identity transfer; changed versions
+require an exact direct route. Runtime execution does not invoke migrations.
+
+Migration declarations change package source: publish a new immutable Block
+release and keep its fixtures on the target schema. Do not guess existing state
+fields or reset user memory. In StillMade, owners review exact archived/current
+source pins, operations and before/after memory, then explicitly apply. The host
+rechecks account/project/source/state, retains rollback history and invalidates
+downstream results. External hosts must provide equivalent ownership, source
+verification, approval and rollback boundaries before accepting the result.

package/docs/build/web-reading.md

@@ -0,0 +1,37 @@
+# Hosted web reading
+
+Two operations let a Block use the web without network permissions, cookies or
+keys. StillMade does the reading; the person running the Block pays with
+StillMade credits at the app's research prices, shown in the quote first.
+
+**`web.fetch`** reads one public page and answers the Block's instruction from
+it with StillMade's fast model. Declare one `text` input holding the URL, one
+`text` output and `permissions.capabilities: ["web.fetch"]`:
+
+```json
+{"schemaVersion":1,"operation":"web.fetch","url":{"$input":"url"},"instruction":"Summarize the page in five bullet points.","output":"summary"}
+```
+
+The URL must be a public `http` or `https` address of at most 2,048
+characters. StillMade refuses private, local and credentialed addresses,
+follows at most three redirects, reads HTML or plain text up to 5 MB, removes
+scripts and markup, and treats the page as untrusted data, never as
+instructions. A page that cannot be read is refunded. The instruction is 1 to
+4,000 characters.
+
+**`web.research`** searches the web for a topic and returns a cited summary.
+Declare one `text` or `brief` topic input (1 to 500 characters) and one `text`
+or `json` output with `permissions.capabilities: ["web.research"]`:
+
+```json
+{"schemaVersion":1,"operation":"web.research","topic":{"$input":"topic"},"output":"findings"}
+```
+
+A `json` output receives `{"schemaVersion":1,"summary":"...","sources":[{"url":"https://...","title":"..."}]}`
+(up to 12 sources); a `text` output receives the summary followed by a
+numbered source list. Fixture expectations are the usual text bounds, or
+`{"kind":"json"}` with optional `includes`.
+
+The offline SDK includes `packages/block-sdk/web-example.js`, exporting
+`webFetch` and `webResearch`. Pair either with `text.generate` (as a `context`
+input) to write from what was read.

package/docs/build/with-your-ai.md

@@ -0,0 +1,27 @@
+# Build a Block with your AI
+
+## For you
+Give your coding agent (Claude Code, Cursor, Codex, Gemini CLI or similar) a link to this page and say what the Block should do, for example: “Build a StillMade Block that turns a script into a shot list. Follow https://stillmade.shop/docs/build/with-your-ai.md”. It sets up the SDK, builds the Block and checks it on its own; you only answer questions about what the Block should do. A chat assistant without a terminal cannot download or run anything, so use a coding agent, or connect StillMade's [MCP server](/docs/native-mcp.md). Either way, StillMade refuses to install a Block that fails its readiness check.
+
+## For the coding agent
+Do every step yourself. Do not ask the person to download, unzip, open a folder or run a command; only ask about what the Block should do.
+
+1. **Get the SDK.** With Node.js 22 or later and npm, install it in your working folder:
+```sh
+npm install --save-dev stillmade-sdk
+```
+Then read `node_modules/stillmade-sdk/AGENTS.md` in full and run every command below as `npx stillmade-block`. Without npm, download the SDK archive instead. It is `/block-sdk/stillmade-sdk-0.1.0.zip` on the same site as this page: replace this page's path with that one (for example `https://stillmade.shop/block-sdk/stillmade-sdk-0.1.0.zip`, or `http://localhost:3000/block-sdk/stillmade-sdk-0.1.0.zip` when this page came from localhost). If `stillmade-blocks/AGENTS.md` already exists in your working folder, reuse that folder. Otherwise download and extract it into `stillmade-blocks`:
+```sh
+curl -fsSL "<SDK URL>" -o stillmade-sdk.zip && unzip -q stillmade-sdk.zip -d stillmade-blocks && rm stillmade-sdk.zip
+```
+On Windows PowerShell:
+```powershell
+Invoke-WebRequest "<SDK URL>" -OutFile stillmade-sdk.zip; Expand-Archive stillmade-sdk.zip stillmade-blocks; Remove-Item stillmade-sdk.zip
+```
+The archive needs Node.js 22 or later and nothing else; its runtime is bundled, so never run `npm install` in it. From the archive, run commands from `stillmade-blocks` as `node packages/block-cli/cli.js` where the steps below say `npx stillmade-block`.
+2. **Read `AGENTS.md` in full** before writing code (`node_modules/stillmade-sdk/AGENTS.md` from npm, `stillmade-blocks/AGENTS.md` from the archive). It is the contract StillMade checks every Block against.
+3. **Build the Block.** Scaffold with `npx stillmade-block create <name> javascript` (`npx stillmade-block create --list` shows every template, including `text`, `image-generate` and `speech` for hosted generation), then iterate with `npx stillmade-block validate <name>` and `npx stillmade-block test <name>`. Hosted operations need `test <name> --mock`, which uses recorded stand-ins and spends no credits.
+4. **Run the readiness gate before you call anything ready:** `npx stillmade-block gate <name>` on the Block's own folder (`gate .` in a folder that also holds the extracted SDK checks the SDK's examples too). Report the exact status it prints. If it fails, fix the listed checks and run it again. If you cannot fix them, tell the person plainly that the Block is not ready and list the failing checks. A browser application reports NEEDS STILLMADE REVIEW: tell the person to import it so StillMade can run its isolated review.
+5. **Hand it over.** Give the person the full path of the `<name>` folder. In StillMade they choose **Import folder** and select that folder.
+
+`stillmade-blocks` contains hooks that run the gate automatically when a Claude Code or Cursor session started in that folder finishes a turn. In the session that downloaded the SDK those hooks are not active yet, so run the gate yourself as in step 4.

package/docs/changelog.md

@@ -0,0 +1,9 @@
+# SDK changelog
+
+## 0.1.0
+The current SDK provides typed recipe and isolated JavaScript Blocks, semantic roles, schema controls, fixtures, admission scans, immutable release digests, context snapshots, conditional Steps, ordered workflow construction, connected rehearsal, and the documented host batch behavior.
+
+## Documentation updates
+The developer site separates tutorials, conceptual guides, reference, examples, and SDK downloads. The runtime contract remains 0.1.0; documentation and navigation changes do not silently advance the SDK or package release version.
+
+See the [capability matrix](reference/capabilities.md) for the exact implementation boundary.

package/docs/creators.md

@@ -0,0 +1,21 @@
+# Creator Program
+
+Everything needed to build for StillMade is free and works offline: the SDK,
+the CLI with its templates, preview and stand-ins, these docs and the
+examples. An account is needed only to import, publish and run with real
+hosted operations.
+
+- **Request a primitive.** When a Block cannot do something you need, tell us
+  from **Create → Creator tools → Request a primitive**, or
+  [open the form](/create?request=primitive). Name the missing capability and
+  what you are building. Requests are ranked together with the gaps StillMade
+  AI records when it cannot build a Block, and the most requested primitives
+  are built first.
+- **Publish.** Community releases are free to install, use and remix (see
+  [pricing and access](distribute/selling.md)); curated releases go through
+  [marketplace review](distribute/publishing.md).
+- **Track your work.** The Creator dashboard in Create → Creator tools shows how
+  your Blocks and Project Types are used.
+- **Build what StillMade builds.** [StillMade Blocks and the SDK](reference/parity.md)
+  lists every service StillMade's own Blocks use and the public SDK features that
+  do the same, with any remaining gap.

package/docs/distribute/discovery.md

@@ -0,0 +1,43 @@
+# Make your listing useful and discoverable
+
+## Start with the result
+A useful listing lets someone decide whether the capability fits their work before installing it. Name the actual task. Explain what they start with, what they can change, and what they get. Keep requirements and limits next to the relevant claim.
+
+A Block is a reusable capability or workspace. Inside a Project Type, its placement is a Step. A Project Type describes the ordered production workflow. Do not describe a full workspace as a single file converter just because its contract declares an input and an output.
+
+## Write a description someone can use
+Use a short summary for the listing card and a fuller explanation for the listing page. Base both on the released source and behavior you have tested. An AI-generated explanation needs the same review as one you write yourself.
+
+For an image-processing Block, a useful description might explain that it takes an image, changes line thickness, and returns an image, then identify which controls and limitations the implementation actually supports. Only use that description if the released code performs those operations. Avoid untested claims about quality, speed, model support, or guaranteed results.
+
+For a Project Type, explain the order of work and what the user will still need to provide or review. Include its real Blocks and a representative finished result. A long list of keywords does not help someone choose a workflow.
+
+## Show a representative demonstration
+Creators can edit the presentation of their own published Block or Project Type. In the listing presentation controls, upload an image or a short MP4 you have permission to publish. Current limits are 8 MB for images and 12 MB for MP4 previews. The upload belongs to the selected release; check the preview again after releasing a new version.
+
+Show the starting material, the relevant controls, and the result from that release. For a Project Type, show how the workflow reaches the finished output. A demo should make the capability easier to assess. Do not publish private project material or include credentials in a recording.
+
+The interactive preview and an uploaded demonstration serve different purposes: the preview lets someone try the capability with sample content; the recording can explain how you used it. Hosted actions and runtime constraints still apply. Read [Test and preview a Block](../build/testing.md) before describing what a preview proves.
+
+## Give it useful context
+- Add or choose a recommended workflow for a Block so people can see where it fits.
+- Keep the released inputs, outputs, semantic roles, and requested permissions accurate.
+- Use the version history when the behavior changes, and preserve source attribution and licensing when remixing.
+- Link a tutorial to the specific Block or Project Type it actually uses.
+- Use your public creator username. Keep email addresses and private customer feedback out of public package metadata.
+
+Read [Versions, checkpoints, and remixes](versioning.md) and [Publish and share](publishing.md).
+
+## Share the public listing
+Open the listing and use its normal page URL when sharing a tutorial or demonstration. The main listing follows the current public release. A version URL is appropriate when a tutorial depends on that exact version. Private drafts are not public listing pages.
+
+Public Community visibility and curated Marketplace approval are separate. Publishing a Community release does not imply that StillMade has selected or endorsed it for the curated Marketplace.
+
+Reviews currently contain one rating and one comment and are visible to the listing creator and administrators. They do not appear in public search snippets or public rating totals. Do not claim a public star rating on the strength of private feedback.
+
+## Search visibility has limits
+Public pages include readable descriptions, creator attribution, related links, and search metadata. Search engines choose which pages to index and show. Uploading a video or adding markup does not guarantee higher rankings or stars in search results.
+
+Google and AI search need accessible, useful content. There is no special phrase to repeat or hidden instruction to put in a package. The downloadable [documentation for an LLM](/docs/llms-full.txt) is an authoring resource, not a ranking switch.
+
+If you sponsor a tutorial or provide compensation for coverage, disclose it and ask the publisher to qualify paid links appropriately. Do not buy links intended to pass ranking credit. See [Google's link spam policies](https://developers.google.com/search/docs/essentials/spam-policies#link-spam), [AI search guidance](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide), and [video guidance](https://developers.google.com/search/docs/appearance/video).

package/docs/distribute/imports.md

@@ -0,0 +1,58 @@
+# Import and adapt source
+
+JSON and ZIP packages enter a review screen before account installation. ZIP
+imports accept one build, prefer `stillmade.block.json` plus edited `src/run.js`
+or `src/recipe.json` or `src/comfyui.json`, and `tests/fixtures.json`, and reject unsafe/duplicate paths,
+ambiguous builds and excessive expanded source. Included development dependencies
+are not installed or executed by the app.
+
+`scanPackage(package)` parses standalone JavaScript and screens unsupported ambient
+APIs/modules and dynamic constructor access. `admitPackage(package, {test, run})`
+adds fixture tests and a sample through supplied sandbox runners. A passing scan
+is not proof of safety; the sandbox remains mandatory. Import confirmation repeats
+admission on the server and creates an owner-scoped account copy. It does not create
+a public release. The original license and provenance remain intact.
+
+Raw-code adaptation accepts a purpose description, source name, source code and
+license/permission terms. AI creates a new SDK package; it never executes the
+original code. `manifest.provenance.adaptedFrom` records its digest, name and
+license and the original source text (retaining its attribution). Unsupported capabilities return an explanation or a failed editable
+draft, not a working-runtime claim. GitHub JSON imports retain the selected
+branch/tag/commit and verified Git blob identity.
+
+## GitHub repositories
+**Adapt a GitHub repository** resolves a public branch/tag/ref to a full commit
+SHA. The in-app adapter selects up to six implementation, README, test, or
+dependency-metadata files and then retains every applicable ancestor
+LICENSE/COPYING/NOTICE file, up to sixteen regular UTF-8 files and 45 KB combined.
+Inspectable source includes JavaScript/TypeScript, Svelte/Vue, HTML/CSS, SVG,
+GLSL/WGSL, Python, Rust, Go, shell, and common C/C++/Qt text files. These files
+remain untrusted evidence: StillMade does not install dependencies or execute the
+repository. A recognized native application may instead produce an independently
+authored desktop-only Block using a versioned, allowlisted host adapter. The Block
+still has no shell, arbitrary executable, unrestricted filesystem, Qt/OpenFX
+plugin, or dependency-install authority. Unrecognized native repositories remain
+source evidence only and do not become Blocks merely because they are public.
+The app reads a complete bounded Git tree, excludes symlinks, submodules and
+unsupported/secret paths, and verifies each blob against its Git SHA-1 identity.
+Review the original code and applicable license before requesting adaptation.
+No repository dependencies, hooks, scripts, or original source are executed.
+
+The adaptation request refetches the same commit and selected blobs. An LLM rewrites
+the relevant behavior into supported SDK recipes/isolated JavaScript; unavailable
+capabilities remain unsupported. `manifest.provenance.adaptedFrom` retains the
+original selected source, license, source digest, and `origin` with repository,
+commit and per-file blob digests. This metadata records origin, not verification
+of legal rights or authorship. The final package still requires normal import
+admission and user confirmation. Importing does not publish third-party source.
+
+The approved Natron route pins the requested GitHub commit without copying or
+executing its GPL application source, generates an MIT SDK integration Block,
+and declares one `video` input and output for Project Type composition. Its
+desktop adapter can import/open a `.ntp` project and render an authorized local
+video through fixed Reader/Writer node names and a bounded frame range. It does
+not expose Natron's Python/interpreter flags. Private repositories, arbitrary
+large native codebases, dependency installation and Python/ComfyUI execution
+remain outside this adaptation runtime. Public GitHub API
+rate limits apply; downloaded SDK packages and pasted-source adaptation remain
+available alternatives.

package/docs/distribute/publishing.md

@@ -0,0 +1,29 @@
+# Publish and share
+
+Use **Publish version** from the existing builder. One review dialog covers Community, Marketplace review, or private access where the account permits it, plus runtime, license, preview and redistribution consent. Marketplace selection publishes a Community release and requests review; it does not grant curated status. If review submission fails, the successful Community release is kept and can be submitted again.
+
+The same publishing panel controls public cover media, full description, category, tags, use cases and version notes. These change presentation only. The released title, short description, typed contracts, source and license remain tied to the immutable package version.
+
+My builds includes original and forked drafts, imports, installed versions, every own release and private releases. A version can be marked deprecated or delisted, with a public notice and an optional replacement version. It stops appearing in discovery and becomes ineligible for indexing; direct version URLs, source downloads and existing pinned projects remain available unless a separate security revocation applies.
+
+A Block published publicly from StillMade is listed in the Marketplace as soon as
+its automatic checks pass: tests for its exact source, a supported license, its
+runtime, and no exact duplicate. No one reviews it by hand. A Project Type waits
+for an admin review. Set the source license in `manifest.license` (or top-level
+`license` for a project type), save/test/sync, and publish an immutable Community
+version; track the result in My builds. Supported SPDX
+identifiers for the initial review flow are exported as `MARKETPLACE_LICENSES` and
+listed in `api-index.json`; custom/unknown licensing needs a later review workflow.
+Changing a published version's license requires a new immutable version.
+
+The existing protected admin console inspects exact package source, permissions,
+licensing and attribution, then reruns fixtures before approval. Type approval also
+requires available host adapters. Review decisions use revision preconditions and
+an audit journal. Approved listings may be featured; publisher withdrawal and
+admin rejection remove promotion without deleting the Community release or
+installed project pins. Marketplace listings are free and creators cannot charge
+for them. Reputation scoring and package signing are separate future work.
+
+
+## Public pages
+Blocks, Project Types, and creators have their own page URLs. Public pages link to related workflows, versions, and source ancestry. Project references remain filtered by project access. Never place an email address, credential, or private fixture in public package metadata.

package/docs/distribute/sdk-versions.md

@@ -0,0 +1,36 @@
+# SDK versions and deprecation
+
+What is versioned:
+
+- **The SDK**, named by `sdkVersion` in each manifest (now `0.1.0`), with its
+  packages, CLI and documentation.
+- **Contracts inside a package**, each with its own `schemaVersion`: the
+  manifest, capability descriptors, module descriptors, portable packages and
+  conversions.
+- **Each Block release**, with its own semantic version. A published release is
+  immutable: StillMade keeps its exact source and the contract it was built for.
+
+What stays true:
+
+- A published release keeps working. Installed pins never move to a newer
+  version on their own, and saved projects reopen with the pinned version.
+- New capabilities are additive: new optional manifest fields, port types,
+  hosted operations, host API methods and templates do not change how existing
+  packages behave.
+- A change that would alter existing behavior ships under a new name or a new
+  `schemaVersion`, and the old one keeps working for releases that use it.
+
+Before 1.0 (`0.x`), the SDK may still change between minor versions; every
+change is listed in the [changelog](../changelog.md), and published releases
+keep working regardless. From 1.0 the SDK follows semantic versioning: a major
+version only for removals, and a deprecated API keeps working for at least 12
+months after its replacement ships. Deprecations are marked in these docs, in
+`stillmade-block validate` warnings and in the changelog, and removing an API
+never changes a release that was already published with it.
+
+**Licence.** The SDK (its packages, CLI, guides and examples) is licensed under
+the [PolyForm Shield License 1.0.0](https://stillmade.shop/block-sdk/LICENSE.txt). You may use and change
+it, and build, publish and sell Blocks with it; you may not use it to provide a
+product that competes with StillMade. Your Blocks are yours: each Block carries
+the licence its creator names in its manifest, and StillMade's own Blocks use
+MIT.

package/docs/distribute/selling.md

@@ -0,0 +1,14 @@
+# Pricing and access
+
+Every Block and Project Type in the Marketplace is free to install, use and
+remix. Creators cannot set a price, sell a license or charge for access, and
+listings never show a license price.
+
+Running a Block can still use StillMade credits when it makes a paid AI request,
+such as hosted text, speech, image or video generation. Those requests keep their
+normal model and payment confirmation, and the credits go to StillMade, not to
+the Block's creator. BYOK connections bill the connected provider account.
+
+Source remains downloadable and previews remain sandboxed. Free access does not
+grant permission to relicense third-party code; each Block keeps its own license
+and attribution.

package/docs/distribute/teams.md

@@ -0,0 +1,60 @@
+# Share private versions with teams
+
+An owner can share an existing **private released version** of a Block or Project
+Type with active teammates. This is a host library permission, not a manifest
+permission. Do not put team IDs, credentials or sharing grants in a portable
+package. The sandbox and typed input/output contract are unchanged.
+
+### Share a version
+
+1. Open the released version from **My builds → Installed versions → Open source**.
+2. Choose **Share with teams**, select your teams, and confirm that you have
+   permission to share the source. Save team access.
+3. Teammates find the version under **Shared with your teams** in the Block library
+   or Project Types library. **Preview and install** opens the real import review
+   dialog, including the sandbox, tests, permissions and sample execution.
+4. After review, choose **Install this version**. The account keeps an installation
+   and this device keeps a source checkpoint. Installed Blocks also appear when
+   adding a Block to a project's workflow.
+
+Sharing covers one exact entity, version and source digest. Editing a draft,
+releasing a later version or changing a Project Type does not extend the grant.
+The release stays private: it receives no public listing, public source link,
+search entry or sitemap entry. Existing private work stays private after Max ends.
+Sharing an existing private release does not require buying Max again. Shared
+draft editing and automatic updates of installed copies are separate features.
+
+Both the source owner and recipient must be active members of a granted team
+when fetching source or confirming a new installation. StillMade rechecks access
+after the package review. Removing a grant or leaving/suspending team membership
+removes future cloud library access and downloads. Previously downloaded source,
+local checkpoints and embedded project copies remain with their recipients;
+revocation cannot retract source already delivered. Team access does not grant
+access to the creator's other projects, media, secrets, or payment account.
+
+Imported third-party source keeps its original license and attribution. A private
+grant is still source distribution: share only where your license permits it.
+Hosted capabilities retain the recipient's normal model, payment, cost and review
+confirmations. A team grant never authorizes a provider call or bypasses runtime
+tests. Project Type imports remain subject to the current whole-workflow admission
+rules; sharing does not enable an unsupported runtime combination.
+
+### Authenticated host API
+
+These are account APIs for StillMade's UI. They are unavailable inside guest code.
+All paths below are relative to `/api/blocks` and require the current account's
+bearer token. Use the cloud entity UUID, not the manifest's `namespace.name` ID.
+
+| Request | Behavior |
+| --- | --- |
+| `GET /releases/:entityId/:version/team-access` | Owner reads `{entityId, version, digest, teams:[{id,name,shared,canShare}]}` for a private version. Previously granted inactive teams remain available for removal; `canShare:false` prevents adding them. |
+| `PUT /releases/:entityId/:version/team-access` | Owner sends `{teamId, shared, sourceDigest, rightsConfirmed:true}` to grant access; `rightsConfirmed` is unnecessary when `shared:false`. |
+| `GET /library?collection=teams` | Returns authorized private releases as `{items,nextCursor}`; pass the returned opaque `cursor` for the next page. |
+| `GET /library?collection=installs` | Lists installed releases the account can currently retrieve from the cloud. |
+| `GET /releases/:entityId/:version` | Fetches authorized source and its digest through authenticated storage. |
+| `POST /install` | Confirms `{entityId,version,sourceDigest,confirmed:true}` after review; include the existing `comfyuiReview` or `capabilityReview` receipt when the runtime requires one. |
+
+A denied or removed release returns `404`; a changed digest returns `409`.
+When team sharing is not set up on a StillMade server, team-sharing endpoints return `503`
+with `TEAM_ACCESS_SETUP_REQUIRED`. Existing owner/public source access continues;
+unavailable team storage never grants access to a private release.

package/docs/distribute/versioning.md

@@ -0,0 +1,28 @@
+# Versions, checkpoints, and remixes
+
+Fixtures are `{name,input,expected}` for recipe and JavaScript Blocks, `{name,input,expected,mocks}`
+(`mocks` optional) for module Blocks and `{name,input,expectations}` for capability and
+ComfyUI Blocks; expected equals the full output object.
+Include 1–50 tests. `testPackage()` returns a SHA-256 content digest, pass/fail and
+structured results. Changing source, manifest or fixtures invalidates that report.
+CLI `pack` requires passing tests. Releases are immutable and require tests against
+the exact digest. Restoring a checkpoint creates a new history entry.
+
+Use **Remix as new build** for an independent identity and initial `0.1.0`
+version. `provenance.remixedFrom` records the source identity, version, and SHA-256
+digest. **Next patch version** increments the release version; checkpoints remain
+independent of release numbers. The digest identifies content, not a verified
+publisher signature.
+
+**Download source + history + SDK** exports a ZIP with `my-block/stillmade.block.json`,
+`my-block/src/recipe.json`, `my-block/tests/fixtures.json`, `history.json`, a working
+package snapshot, the SDK implementation, CLI, documentation, and instructions for
+your own LLM. Run `node packages/block-cli/cli.js pack my-block rebuilt.stillmade.json`
+from the extracted folder (Node.js 22+; no dependency installation required).
+Open the original build in StillMade and import the rebuilt file to append an
+external-revision checkpoint. A different package identity opens as a new draft.
+
+Built-in catalog blocks have **Download source + SDK** too. These archives contain
+their client implementation and local source dependencies. They are host source
+snapshots for external editing/review, not independently installable recipe
+packages. Server implementation, credentials, and project data are not included.

package/docs/examples.md

@@ -0,0 +1,23 @@
+# Working examples
+
+## Choose an example
+| Example | Runtime | Demonstrates |
+| --- | --- | --- |
+| [Clean text](https://stillmade.shop/block-sdk/examples/clean-text.stillmade.json) | Recipe | Literal text operations and typed output |
+| [Thicken lines](https://stillmade.shop/block-sdk/examples/thicken-lines.stillmade.json) | Recipe | RGBA input, controls, and deterministic pixel output |
+| [Word count](https://stillmade.shop/block-sdk/examples/word-count.stillmade.json) | JavaScript | Isolated source and multiple outputs |
+| [Grayscale](https://stillmade.shop/block-sdk/examples/grayscale.stillmade.json) | JavaScript | Independent LLM authoring, current resolver contract, and alpha preservation |
+| [Screen recorder](https://stillmade.shop/block-sdk/examples/screen-recorder.stillmade.json) | Desktop UI + JavaScript | Permission-gated screen capture; typed video output |
+| [Camera recorder](https://stillmade.shop/block-sdk/examples/camera-recorder.stillmade.json) | Desktop UI + JavaScript | Camera capture with explicit start, stop, and cancel |
+| [Microphone recorder](https://stillmade.shop/block-sdk/examples/microphone-recorder.stillmade.json) | Desktop UI + JavaScript | Microphone capture; typed audio output |
+| [Text workflow](https://stillmade.shop/block-sdk/examples/text-workflow.stillmade.json) | Project Type | Embedded Blocks and connected fixture rehearsal |
+| [Script draft](https://stillmade.shop/block-sdk/examples/script-draft.stillmade.json) | Hosted capability | Typed script output; live review with account BYOK or credits |
+| [Generate an image](https://stillmade.shop/block-sdk/examples/generate-image.stillmade.json) | Hosted capability | Typed PNG output with host-selected quality/payment; actual image review required |
+| [Narrate a script](https://stillmade.shop/block-sdk/examples/narrate-script.stillmade.json) | Hosted capability | Bounded script-to-audio declaration and WAV expectations; reviewed project recordings can be added to Editor audio |
+
+## Run an offline Block example
+```sh
+node packages/block-cli/cli.js test examples/word-count.stillmade.json
+node packages/block-cli/cli.js preview examples/word-count.stillmade.json
+```
+Hosted text and speech require their separate [text review](build/hosted-text.md) or [speech review](build/hosted-speech.md) in StillMade. The speech example has no completed live provider test; schema and mock tests are not proof of generated audio. Deterministic examples run offline. Examples are complete packages. Use them as a starting point, choose your own namespace, and update the fixtures when behavior changes.

package/docs/gallery.md

@@ -0,0 +1,26 @@
+# What you can build
+
+Start from a template (`stillmade-block create my-block <template>`) or a
+complete example in the SDK download's `examples/` folder.
+
+| Area | Start from | What it does |
+| --- | --- | --- |
+| Video | `examples/module-silence-trimmer` | Cuts the pauses out of a recording on the device |
+| Video | `trigger-media` | Captions each new upload automatically, inside an approved budget |
+| Video | `timeline-proposal`, `video-generate` | Proposes Editor edits people review; generates clips |
+| Images | `examples/module-opencv`, `image-generate`, `describe-image` | Computer vision with OpenCV; generation; description |
+| Images | `examples/module-brand-kit` | Keeps a brand kit in project storage and makes brand cards |
+| Audio and music | `examples/module-tempo`, `music`, `sfx`, `speech`, `transcribe` | Tempo detection; music, sound effects, voices and transcripts |
+| Audio and music | `examples/module-audio-extract` | Extracts and normalises a video's audio |
+| Data and spreadsheets | `examples/module-csv-summary` | Summarizes every column of a CSV file |
+| Data and spreadsheets | `examples/view-react-chart` | A shared, draggable chart in React |
+| Documents | `examples/module-pdf-shot-list`, `examples/module-action-items` | PDF to shot list; meeting notes to action items |
+| Integrations | `examples/module-notion-to-airtable`, `outside-api`, `connection` | Outside APIs with each person's own keys and sign-ins |
+| Integrations | `trigger-webhook` | Runs when another service sends an event |
+| Education | `examples/javascript-cloze-quiz` | Fill-in-the-blank quizzes with an answer key |
+| E-commerce | `examples/javascript-invoice` | Invoices from order lines, with tax and totals |
+| Research | `web-fetch`, `web-research` | Answers from a page; research with sources |
+| Anything else | `module`, `module-wasm` | Modern JavaScript, npm packages and WebAssembly |
+
+If something you want to build is missing a capability,
+[request a primitive](/create?request=primitive).