OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

Example Specifications

ExampleSpec defines complete, demonstrable ContractSpec applications.

field.key.label
Example Specifications
field.version.label
field.type.label
field.title.label
Example Specifications
field.description.label

ExampleSpec defines complete, demonstrable ContractSpec applications.

field.tags.label
tech,contracts,examples,templates
field.owners.label
field.stability.label
public

Example Specifications

ExampleSpec is a contract for defining complete, demonstrable ContractSpec applications. Examples integrate with AppBlueprintSpec and FeatureModuleSpec to provide a full application specification.

Overview

An `ExampleSpec` captures:

•

**Metadata** (via `ExampleMeta` extending `OwnerShipMeta`): key, version, title, description, ownership, tags, stability

•

**Example-specific fields**: kind, visibility, summary

•

**Surfaces**: where the example can be used (templates, sandbox, studio, MCP)

•

**Entrypoints**: package exports mapping

•

**Blueprint**: optional AppBlueprintSpec or reference

•

**Features**: optional FeatureModuleSpec array or references

Usage


const example: ExampleSpec = {
  meta: {
    key: 'saas-boilerplate',
    version: '1.0.0',
    title: 'SaaS Boilerplate',
    description: 'Multi-tenant SaaS foundation with billing and RBAC.',
    kind: 'template',
    visibility: 'public',
    stability: 'experimental',
    owners: ['@saas-team'],
    tags: ['saas', 'multi-tenant', 'billing'],
    summary: 'Complete SaaS starter.',
  },
  surfaces: {
    templates: true,
    sandbox: { enabled: true, modes: ['playground', 'specs', 'builder'] },
    studio: { enabled: true, installable: true },
    mcp: { enabled: true },
  },
  entrypoints: {
    packageName: '@lssm-tech/example.saas-boilerplate',
    feature: './saas-boilerplate.feature',
    contracts: './contracts',
  },
  features: [SaasBoilerplateFeature],
};

ExampleRegistry

Use `ExampleRegistry` to manage examples:

const registry = new ExampleRegistry();
registry.register(example);

// Query examples
registry.listByKind('template');
registry.listByVisibility('public');
registry.listBySurface('studio');
registry.listInstallable();
registry.search('billing');

ExampleMeta

`ExampleMeta` extends `OwnerShipMeta` with example-specific fields:

| Field | Type | Description | |-------|------|-------------| | key | string | Unique identifier | | version | number | Spec version | | title | string? | Human-readable title | | description | string | Technical description | | kind | ExampleKind | template, workflow, integration, etc. | | visibility | ExampleVisibility | public, internal, experimental | | stability | Stability | idea, experimental, beta, stable, deprecated | | owners | string[] | Owner identifiers | | tags | string[] | Discovery tags | | summary | string? | Marketing summary |

ExampleKind

| Kind | Use Case | |------|----------| | template | Full application template | | workflow | Workflow automation example | | integration | Integration showcase | | knowledge | Knowledge base example | | blueprint | App blueprint example | | ui | UI component showcase | | script | CLI/script example | | library | Library/SDK example |

Surfaces

| Surface | Purpose | |---------|---------| | templates | Available as new project template | | sandbox | Interactive playground support | | studio | ContractSpec Studio support | | mcp | Model Context Protocol support |

Validation


const result = validateExample(example);
if (!result.valid) {
  console.error(result.errors);
}

// Batch validation with duplicate detection
const batchResult = validateExamples([example1, example2]);

Integration with Blueprints and Features

Examples can reference or embed blueprints and features:

const example: ExampleSpec = {
  // ... meta, surfaces, entrypoints
  
  // Inline blueprint
  blueprint: myAppBlueprint,
  
  // Or reference by pointer
  blueprint: { key: 'core.app', version: '1.0.0' },
  
  // Inline features
  features: [MyFeature],
  
  // Or reference
  features: [{ key: 'my-feature' }],
};

Related

•

[App Configuration](file:///docs/tech/contracts/app-config) - AppBlueprintSpec

•

[Features](file:///docs/tech/contracts/features) - FeatureModuleSpec