stillmade-sdk 0.1.1 → 0.1.3

package/AGENTS.md

@@ -8,6 +8,10 @@ Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source
 
 Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
 
+## Reuse first
+
+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.
+
 ## 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.

package/NATIVE_MCP.md

@@ -105,10 +105,10 @@ Use the backend origin, without a path. HTTP is accepted only for localhost. Red
 
 ## Available user actions
 
-- `list_catalog`, `search_marketplace`
+- `list_catalog`, `search_marketplace`, `find_existing_blocks`
 - `search_github_candidates`, `inspect_github_repository`, `read_github_source`, `inspect_github_sdk_package`
 - `get_block_authoring_guide`, `search_documentation`, `validate_block_source`, `test_block_source`
-- `list_creations`, `get_creation`, `save_creation`
+- `list_creations`, `get_creation`, `save_creation`, `begin_block_remix`
 - `list_projects`, `get_project_context`
 - `get_run`, `list_recent_runs`
 - With `analytics:read`: `get_creator_analytics`, `get_creator_retention`, `get_creator_dotplot`, `get_my_listing_reviews`
@@ -119,11 +119,30 @@ Live-tab inspection and control are no longer exposed in the app connection UI.
 External MCP clients continue to use the saved catalog, creation, project-context,
 and run-inspection tools listed above.
 
+## Reuse first
+
+Before authoring, the client calls `find_existing_blocks` with the goal and, when
+known, the inputs it starts from and the results it must produce. It searches
+reviewed Marketplace listings, tested Community Blocks, built-ins and the
+person's own Blocks by function and name, with no model, provider or credit
+cost, and returns one outcome:
+
+- `use` or `use-own`: an existing Block already does it; offer it instead of building.
+- `remix`: a close Block allows an attributed remix. `begin_block_remix` creates a
+  private draft from that exact version, with its license, notices and creator
+  credit; retrying the same `requestId` returns the same draft.
+- `compose` or `build-gap`: existing Blocks chain together; build only the missing step.
+- `build`: nothing close exists, or the person wants their own version.
+
+`validate_block_source` and `save_creation` also list up to three similar existing
+Blocks (`similarExisting`). Publishing an exact copy of another creator's public
+Block without remix lineage is refused.
+
 ## Block authoring uses the connected model
 
 When a user asks Claude, GPT, or another MCP client to create or refine a Block,
 the connected client model writes the complete SDK package itself. The default
-sequence is `get_block_authoring_guide`, targeted `search_documentation` calls,
+sequence is `find_existing_blocks`, `get_block_authoring_guide`, targeted `search_documentation` calls,
 local source composition by that model, `validate_block_source`, repair of every
 reported failure, optional offline `test_block_source` for an eligible package,
 and `save_creation` with `kind: "block"` and the observed

package/PASTE_TO_LLM.md

@@ -10,6 +10,10 @@ Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source
 
 Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
 
+### Reuse first
+
+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.
+
 ### 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.

package/REMIX.md

@@ -5,6 +5,20 @@ The original release, installed pins and saved projects remain intact. Remixes
 use the ordinary Block Builder, validator, package format and release pipeline.
 Project Types, projects and generated outputs are outside this workflow.
 
+## Find before you build
+
+Check what already exists before writing a new Block. Create runs a free check
+before every new build, and MCP clients call `find_existing_blocks`. Both search
+reviewed Marketplace listings, tested Community Blocks, built-ins and your own
+Blocks by what they take in, produce and call, and by name. The answer is one of:
+use an existing Block, open your own, remix a close one, chain existing Blocks
+and build only the missing step, or build new. Over MCP, `begin_block_remix`
+starts a remix from an exact public version.
+
+Publishing a renamed copy of another creator's public Block is refused; remix it
+so its license, notices and creator credit stay attached. Max accounts can keep
+such a copy private.
+
 ## Required for every finished Block
 
 Automatic remixing is a minimum admission requirement, including private Blocks.

package/SDK.md

@@ -160,6 +160,10 @@ Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source
 
 Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
 
+### Reuse first
+
+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.
+
 ### 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.
@@ -7052,6 +7056,10 @@ Contract `stillmade.block-builder@1.0.0`. Humans, coding agents, imported source
 
 Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.
 
+### Reuse first
+
+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.
+
 ### 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.
@@ -10350,6 +10358,20 @@ The original release, installed pins and saved projects remain intact. Remixes
 use the ordinary Block Builder, validator, package format and release pipeline.
 Project Types, projects and generated outputs are outside this workflow.
 
+### Find before you build
+
+Check what already exists before writing a new Block. Create runs a free check
+before every new build, and MCP clients call `find_existing_blocks`. Both search
+reviewed Marketplace listings, tested Community Blocks, built-ins and your own
+Blocks by what they take in, produce and call, and by name. The answer is one of:
+use an existing Block, open your own, remix a close one, chain existing Blocks
+and build only the missing step, or build new. Over MCP, `begin_block_remix`
+starts a remix from an exact public version.
+
+Publishing a renamed copy of another creator's public Block is refused; remix it
+so its license, notices and creator credit stay attached. Max accounts can keep
+such a copy private.
+
 ### Required for every finished Block
 
 Automatic remixing is a minimum admission requirement, including private Blocks.

package/package.json

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

package/packages/block-platform/project-type-recommendations.js

@@ -39,6 +39,12 @@ function bestRequirementMatch(manifest,requirement,semantics) {
   return matches.find(match=>match.exact) || matches[0] || null;
 }
 
+/** The best result slot (an output, or a planned terminal action) that meets
+ * a required {type, semantic}: {compatible, exact, reason}, or null. */
+export function requirementMatch(manifest,requirement,semantics) {
+  return bestRequirementMatch(manifest,requirement,semantics);
+}
+
 export function blockProvidesRequirement(manifest,requirement,semantics) {
   return !!bestRequirementMatch(manifest,requirement,semantics);
 }
@@ -70,7 +76,7 @@ export function missingCapabilityPlacements(requirements,combination,candidates)
   });
 }
 
-export function recommendProjectTypeCombinations({goal,requirements,handoffRequirements=[],sourceMaterials, resultPins={},candidates,semantics,trustedUsage=[],trustedExecution=[],trustedCosts=[],trustedCreators=[],executionPreference='any',executionDevices=[],maxSteps=8,beamWidth=12,maxEvaluations=1200}) {
+export function recommendProjectTypeCombinations({goal,requirements,handoffRequirements=[],sourceMaterials, resultPins={},candidates,semantics,trustedUsage=[],trustedExecution=[],trustedCosts=[],trustedCreators=[],trustedQuality=[],executionPreference='any',executionDevices=[],maxSteps=8,beamWidth=12,maxEvaluations=1200}) {
   assert(RECOMMENDATION_EXECUTION_PREFERENCES.includes(executionPreference),'RECOMMENDATION','Choose an available execution preference.');
   assert(Array.isArray(executionDevices)&&executionDevices.length<=3&&new Set(executionDevices).size===executionDevices.length&&executionDevices.every(device=>RECOMMENDATION_EXECUTION_DEVICES.includes(device)),'RECOMMENDATION','Choose only phone, browser, or desktop execution devices.');
   assert(typeof goal==='string' && goal.trim() && goal.length<=4000,'RECOMMENDATION','Describe what the software should do.');
@@ -103,6 +109,9 @@ export function recommendProjectTypeCombinations({goal,requirements,handoffRequi
   const available=[...catalog.values()];
   const usage=new Map(trustedUsage.filter(row=>Number.isSafeInteger(row.completedProjects) && row.completedProjects>=0 && Number.isSafeInteger(row.repeatUsers) && row.repeatUsers>=0).map(row=>[`${row.entityId}@${row.version}:${row.digest}`,row]));
   const usageFor=candidate=>candidate.release?usage.get(`${candidate.release.entityId}@${candidate.release.version}:${candidate.release.digest}`):undefined;
+  // Distinct people other than the creator who installed each Block. A tie-break only.
+  const installs=new Map(trustedQuality.filter(row=>typeof row?.entityId==='string'&&Number.isSafeInteger(row.installs)&&row.installs>=0).map(row=>[row.entityId,row.installs]));
+  const installsFor=candidate=>candidate.release?installs.get(candidate.release.entityId):undefined;
   const execution=new Map(trustedExecution.filter(row=>Number.isSafeInteger(row.terminalRuns) && row.terminalRuns>=5 && Number.isSafeInteger(row.completedRuns) && row.completedRuns>=0 && row.completedRuns<=row.terminalRuns && Number.isSafeInteger(row.observedUsers) && row.observedUsers>=3 && row.observedUsers<=row.terminalRuns).map(row=>[`${row.entityId}@${row.version}:${row.digest}`,row]));
   const executionFor=candidate=>candidate.release?execution.get(`${candidate.release.entityId}@${candidate.release.version}:${candidate.release.digest}`):undefined;
   const costs=new Map(trustedCosts.filter(row=>Number.isSafeInteger(row.costRuns) && row.costRuns>=5 && Number.isSafeInteger(row.costUsers) && row.costUsers>=3 && row.costUsers<=row.costRuns && Number.isFinite(row.medianNetCredits) && row.medianNetCredits>=0 && row.medianNetCredits<=Number.MAX_SAFE_INTEGER).map(row=>[`${row.entityId}@${row.version}:${row.digest}`,row]));
@@ -226,7 +235,10 @@ export function recommendProjectTypeCombinations({goal,requirements,handoffRequi
     const exactResults=resultMatches.filter(result=>result?.match.exact).length,semanticFitBonus=exactResults*2;
     const creatorHistory=selected.map(creatorFor).filter(Boolean);
     const creatorBonus=selected.length?creatorHistory.reduce((total,row)=>total+(row.completedRuns+1)/(row.terminalRuns+2)-0.5,0)/selected.length:0;
-    const score=(coverage+handoffs.length-missingHandoffs.length)*1000-broken*300-missingSourceInputs.length*600-deviceIssues.length*300-audit.counts.questions*30-keys.length*10-approvals+usageBonus+preferenceBonus+semanticFitBonus+completionBonus+latencyBonus+costBonus+creatorBonus;
+    // Reviewed Blocks win ties over Community ones; widely installed Blocks win ties over new ones.
+    const installBonus=selected.length?selected.reduce((total,candidate)=>total+Math.min(1,Math.log1p(installsFor(candidate)||0)/Math.log1p(50)),0)/selected.length:0;
+    const communityPenalty=selected.filter(candidate=>candidate.origin==='community').length*0.5;
+    const score=(coverage+handoffs.length-missingHandoffs.length)*1000-broken*300-missingSourceInputs.length*600-deviceIssues.length*300-audit.counts.questions*30-keys.length*10-approvals+usageBonus+preferenceBonus+semanticFitBonus+completionBonus+latencyBonus+costBonus+creatorBonus+installBonus-communityPenalty;
     const resultAllocations=resultMatches.map((result,index)=>result?{requirement:wanted[index].key,stageId:connected.stages[result.candidateIndex].id,port:result.port,exact:result.match.exact,...(result.viaAction?{viaAction:result.viaAction,requestType:result.requestType}:{})}:null);
     return {keys,pinnedConnections,definition:connected,audit,missing,missingHandoffs,sourceInputs,missingSourceInputs,handoffPlan,resultAllocations,deviceSupport,deviceIssues,score,coverage,assemblyReady:broken===0&&missing.length===0&&missingHandoffs.length===0&&unavailableSourceInputs.length===0&&deviceIssues.length===0,compatible:broken===0 && missing.length===0 && missingHandoffs.length===0 && missingSourceInputs.length===0 && deviceIssues.length===0,explanation:{requiredResults:wanted.length,coveredResults:coverage,requiredHandoffs:handoffs.length,connectedHandoffs:handoffs.length-missingHandoffs.length,missingSourceInputs:missingSourceInputs.length,plannedActionResults:resultAllocations.filter(item=>item?.viaAction).length,exactResults,compatibleResults:coverage-exactResults,semanticFitBonus,connectionIssues:broken,questions:audit.counts.questions,permissionDeclarations:approvals,blockCount:keys.length,requestedExecutionDevices:executionDevices,declaredSupportedDeviceChecks:deviceSupport.length-deviceIssues.length,unknownDeviceChecks:deviceIssues.filter(item=>item.status==='undeclared').length,unsupportedDeviceChecks:deviceIssues.filter(item=>item.status==='declared-unsupported').length,observedUsageBlocks:observed.length,usageBonus,observedExecutionBlocks:measured.length,completionBonus,observedLatencyBlocks:timed.length,latencyBonus,latencyMetric:'hosted-created-to-completed-median',observedCostBlocks:priced.length,costBonus,costMetric:'verified-single-call-net-credits-median',observedCreatorBlocks:creatorHistory.length,creatorBonus,creatorMetric:'other-block-hosted-completion-history',localBlocks,executionPreference,preferenceBonus}};
   }

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

@@ -29,6 +29,9 @@ const SECTIONS=Object.freeze([
  rule('source-of-truth','both',
   'Use only documented SDK runtimes, types, operations, permissions and host APIs; never invent one.',
   'Treat the current SDK (`stillmade.block.json` manifest, `packages/block-sdk` contracts, validators, examples and published docs) as the source of truth. Before writing code, read the manifest contract, at least two working first-party Blocks closest to the request, the runtime you will use, the typed port and resolver contracts, and the shared-interface contract when you need a custom view. Do not invent runtimes, operations, permissions, ports, host services or bridge calls. If the documentation and the validator disagree, the validator wins and the mismatch should be reported.'),
+ rule('reuse-first','both',
+  'Reuse before building: use, remix or chain an existing Block when one fits; build only what is missing.',
+  '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.'),
  rule('capability-contract','block',
   'Define the contract first: typed inputs (optional with safe defaults where possible), outputs, state, permissions, UI, failures and cancellation. Keep it small.',
   '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.'),
@@ -113,7 +116,7 @@ export const BUILDER_CONTRACT=Object.freeze({
  gapClasses:GAP_CLASSES,
 });
 
-const SECTION_TITLES=Object.freeze({'source-of-truth':'Source of truth','capability-contract':'Define the capability first','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','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({'source-of-truth':'Source of truth','reuse-first':'Reuse first','capability-contract':'Define the capability first','compose':'Blocks compose','platform-primitives':'Use platform primitives','no-workarounds':'No hidden workarounds','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'). */