# Blueprint Schema — Layer 3 Domain Entity Type # KNO Schema Version: 0.1.0 # # A Blueprint is a composable, parameterized, agent-executable build # manual. It describes HOW to combine Platform Capabilities (atoms) into a # running system, with exact API calls, acceptance criteria, and visual # specifications. If a Platform Capability is a finished LEGO model, a # Blueprint is the instruction manual that tells you which bricks to use # and the order to click them together. # # EXTENDS: document-schema.kno (which composes identity, history, quality) # # RELATIONSHIP TO EXISTING SCHEMAS: # - platform-capability-schema.kno: The atoms a Blueprint assembles. # Blueprints REFERENCE platform Capabilities via `atoms[].ref`. # - guide-schema.kno: Human-readable narrative instructions. Blueprints # are the machine-readable counterpart; each Blueprint step may link # to a guide via `relationships.documented_by` for prose context. # - workflow-schema.kno: Automated execution sequences. Blueprints are # higher-level than workflows — a Blueprint may ORCHESTRATE workflow # invocations across multiple Capabilities. # - diagram-schema.kno: Visual specifications. Blueprints REFERENCE D2 # diagrams via `diagrams{}` for architecture, user flow, and build- # state visualization; diagrams serve as acceptance contracts. # - possibility-schema.kno: The container a Blueprint builds into. # A Blueprint is EXECUTED against a Possibility. # # THREE-GATE TEST (validated in capabilities-v2-spec.md § Blueprint rationale): # Gate 1 (Distinctness): YES — no existing schema covers parameterized, # agent-executable build specifications with visual acceptance contracts. # Closest schemas (guide narrative, playbook methodology, workflow # automation) each cover one dimension; Blueprint composes all three. # Gate 2 (Reusability): YES — 15+ Blueprints identified across three # difficulty tiers (simple/intermediate/advanced), reusable across # target stacks via `target_stacks[]`. # Gate 3 (Clarity): YES — gives the "how do I use this platform?" # question a concrete, browsable, reproducible answer. Separates the # WHAT (Capability) from the HOW (Blueprint) from the NARRATIVE # (Guide). # # DESIGN DECISIONS: # DD-BP-01: Blueprint is the source of truth for agent-driven rebuild; # guides and playbooks are derived narrative views (P10). # DD-BP-02: Every Blueprint step has both `human` (prose) and `machine` # (executable API call + expectations) sides. Agents execute # `machine`; humans read `human`. Parity is enforced via # acceptance criteria that must verify both drive to the same # state. # DD-BP-03: D2 diagrams serve quadruple duty (documentation + # acceptance criteria + onboarding + agent instruction). # Diagrams are REFERENCED, not embedded, so they remain # single-source-of-truth under the project's diagram # convention. # DD-BP-04: Parameters are template variables using `{{var_name}}` # syntax. Same Blueprint + different parameters = consistent # result. The template substitution layer is defined by the # compiler, not this schema. # DD-BP-05: Blueprints are multi-target via `target_stacks[]`. The # Possibility-native stack (Astro + TypeScript + Hono + `.kno`) # is the v1 compiler target. Additional targets land as # separate compiler passes per #1135 research § IR migration. # DD-BP-06: `generator_version` pins the compiler semver a Blueprint # was produced by or is compatible with. Enables round-trip # regeneration checks and compiler-drift detection. # DD-BP-07: Publisher tier mirrors platform-capability-schema.kno's # three-tier model (platform / verified / community) so trust # signalling is uniform across Capability and Blueprint # surfaces. # DD-BP-08: `composes_with[]` declares known stack-on-top relationships # to other Blueprints. Explicit composition contracts prevent # the ad-hoc "this works together somehow" drift that # historically plagues build-manual collections. # DD-BP-09: Blueprint instances live under `content/blueprints/*.kno` # (per #1135 research § File structure). The first sample # Blueprint (`white-label-saas-backend`) lands in P6 Task 4 # (#1858); this schema is purely the contract — no instances # ship in P1. # DD-BP-10: Status starts at Experimental. Stabilizes once the first # round-trip compile passes (P6). The status header moves to # Stable with the first Major=1 bump; breaking changes after # that require a MAJOR schema version bump. # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY (Layer 1) # ============================================================================= id: 01KPZWR79HY78EQT93A39PCC9K # pragma: allowlist secret slug: blueprint-schema type: spec version: 1.1.0 # ============================================================================= # VISIBILITY DECLARATION (REQ-18) — collection default # ============================================================================= # Blueprint entities (content/blueprints/*.kno) are public reference knowledge # by default — they are portable, agent-executable build manuals meant for # discovery and consumption by humans, agents (MCP/A2A), and the REST API. # Per REQ-18, individual entities MAY override with their own `visibility:` # field (last-write-wins at the entity level). Drives the four-surface # contract per kno-system_architecture.md § Agent Surface Integration and # public-surface-parity.instructions.md. visibility: public # ============================================================================= # STANDARD TIER # ============================================================================= title: "Blueprint Schema" purpose: | Define the schema for Blueprints — composable, parameterized, agent- executable build manuals that assemble Platform Capabilities into running systems. **What is a Blueprint?** A Blueprint is a structured .kno manifest that describes: - The outcome it produces (the box cover) - The atoms it uses (the bill of materials) - The parameters that customize it (template variables) - The visual specifications it satisfies (referenced D2 diagrams) - The steps to build it (both human-readable and machine-executable) - The acceptance criteria that verify success - The variations that build alternate outcomes from the same atoms - The other Blueprints it composes with (stack-on-top contracts) **The Agent Rebuild Guarantee:** A sufficiently capable agent, given a Blueprint + access to the target platform's APIs, can rebuild the entire outcome from scratch, verify it passes acceptance criteria, and produce an identical result every time. This works because: 1. Every step has a `machine` block with exact API calls 2. Every step has a `state_after` that can be verified 3. Every acceptance criterion maps to an executable assertion 4. Parameters are templated — same Blueprint, different values, same result 5. D2 diagrams anchor the visual spec; diagram annotations become test selectors **Derived Views (P10 Thin Transformations):** The Blueprint .kno is the source of truth. Narrative documentation and quickstart guides are projections: | Derived View | Source Fields | Endpoint | |------------------------|---------------------------------------------|------------------------------| | Library Listing | title + purpose + `outcome.summary` | Blueprint catalog API | | Human Guide | `steps[].human` + `purpose` | Rendered Blueprint page | | Executable Plan | `steps[].machine` + `parameters[]` | Agent-driven build runner | | Acceptance Harness | `acceptance[]` + `diagrams{}` | Pre/post-build verification | **Relationship to Existing Schemas:** | Schema | Relationship | How Referenced | |------------------------------|--------------------|--------------------------------------------| | platform-capability-schema | references | `atoms[].ref` points at Capability manifests | | guide-schema | documented_by | Prose guides link to Blueprints (optional) | | workflow-schema | orchestrates | Blueprint steps may invoke workflows | | diagram-schema | references | `diagrams{}` resolves to `.d2` source files | | possibility-schema | executes_against | Blueprints build into Possibilities | **Layer 3 Position:** Blueprint extends document (Layer 2), which composes identity, history, and quality (Layer 1). # ============================================================================= # RICH TIER — Provenance & Taxonomy # ============================================================================= provenance: origin: id: 01KPZWR79HY78EQT93A39PCC9K # pragma: allowlist secret timestamp: "2026-04-24T00:00:00Z" tool: manual taxonomy: topics: - blueprint - build-manual - composition - agent-execution - codegen - platform-capability keywords: - blueprint - atom - bill-of-materials - parameter - acceptance-criteria - composability - target-stack - agent-rebuild # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type for all documents" depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to KNO format specification v0.0.9" - xri: "kno://specs/platform-capability-schema" reason: "Blueprints assemble platform Capabilities; depends on the Capability contract for atom referencing" composes: - xri: "kno://specs/identity-schema" reason: "Layer 1: id, slug" - xri: "kno://specs/history-schema" reason: "Layer 1: _history, changelog" - xri: "kno://specs/quality-schema" reason: "Layer 1: quality, validation" related_to: - xri: "kno://specs/platform-capability-schema" reason: "Capabilities are the atoms Blueprints assemble" - xri: "kno://specs/guide-schema" reason: "Narrative counterpart — human-readable instructions derived from step[].human fields" - xri: "kno://specs/workflow-schema" reason: "Workflows may be invoked from Blueprint steps" - xri: "kno://specs/diagram-schema" reason: "Visual specifications referenced via diagrams{}" - xri: "kno://specs/possibility-schema" reason: "Blueprints execute against Possibility containers" enables: - xri: "kno://content/blueprints/*" reason: "All Blueprint instances conform to this schema" # ============================================================================= # RICH TIER — Quality # ============================================================================= quality: completeness: 0.80 last_reviewed: "2026-04-24" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY (P9 Temporal) # ============================================================================= _history: retention: full format: changelog changelog: - version: "1.1.0" date: "2026-04-29" author: "copilot" summary: "Declare visibility:public for four-surface contract parity with M32" changes: - "Added top-level `visibility: public` per REQ-18 so the `blueprints` collection is auto-projected onto REST (`/v1/blueprints/*`), llms.txt outline, the generic MCP collection server, and the A2A agent-card enumeration via the `PUBLIC_COLLECTIONS` registry in `services/pspace-api/src/lib/public-collections.ts` and the mirror in `services/pspace-site/src/lib/public-collections.ts`." - "Brings M33 documentation up to the same four-surface rigor M32 (Capabilities v1) shipped with — humans (`/docs/blueprints`), agents via MCP (the generic collection MCP server), agents via A2A (agent-card skills enumeration), and direct API consumers (`/v1/blueprints` REST handlers)." - "No instance changes required: existing `content/blueprints/white-label-saas-backend.kno` inherits the new collection default. Individual entities can still opt out with an entity-level `visibility:` override." - version: "1.0.0" date: "2026-04-24" author: "claude" summary: "Initial Blueprint schema for Capabilities v2 Phase 1 (#1835)" changes: - "Created for M33 Capabilities v2 Phase 1 Task 3 (#1835) as the contract for `content/blueprints/*.kno` instances that P6 codegen (#1855-#1858) will consume." - "Extends `docs/research/capabilities/blueprints/blueprint-concept.md` with codegen-specific fields: `target_stacks[]` (which compiler targets a Blueprint supports), `generator_version` (compiler semver pin), `publisher{}` (tier model matching platform- capability-schema 1.2.0)." - "Adopts the same `compatibility{}`, `categories[]`, `keywords[]`, `featured` shape as platform-capability-schema 1.2.0 so Library browse, filter, and deprecation surfaces treat Capabilities and Blueprints uniformly." - "Status: Experimental. Graduates to Stable once the first round-trip compile passes (P6 Task 5, #1858)." - "Worked example (the `white-label-saas-backend` Blueprint from `blueprint-concept.md § The Blueprint .kno Shape`) will land in P6 Task 4 under `content/blueprints/white-label-saas-backend.kno` — not in this P1 commit. No Blueprint instances ship in P1; this schema is the contract only." - "Self-pin convention (`$schema: blueprint@1.0.0` on instance files) activates with the first instance in P6, matching the platform-capability convention." - "Three-gate test validated: distinct from guide/playbook/ workflow (composes visual + executable + narrative); reusable (15+ Blueprints identified across difficulty tiers); clarifies the WHAT vs HOW vs NARRATIVE separation that collapsed under the older single-document model." # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Experimental description: | ## Blueprint Structure A Blueprint is a Layer 3 entity that extends document-schema. It adds domain-specific sections for outcome, atoms, parameters, diagrams, steps, acceptance, variations, and composability. ### Architecture Pattern ``` blueprint-schema.kno (source of truth) ┌──────────┼──────────┐ │ │ │ ▼ ▼ ▼ Library listing Guide Executable plan (derived) (derived) (derived by agent) ├─ references → platform Capabilities via atoms[].ref ├─ references → D2 diagrams via diagrams{} ├─ composes with → other Blueprints via composes_with[] └─ variations → alternate atom subsets + step subsets ``` ### Naming Convention The entity type is `blueprint` (singular). Instance filenames follow `{slug}.kno` under `content/blueprints/`. Slugs are kebab-case and descriptive of the OUTCOME, not the atom mix — e.g. `white-label-saas-backend`, not `auth-realm-plus-bucket`. ### Status lifecycle - **Experimental**: shape may still change; instances are expected to re-validate against each minor version. - **Stable**: breaking changes require MAJOR bump; round-trip compile passes the three-tier fidelity harness. - **Deprecated**: marked via `compatibility.deprecated: true` on affected instances; schema itself is deprecated only when superseded. # =========================================================================== # SCHEMA DEFINITION # =========================================================================== schema: type: object required: - id - slug - type - version - title - purpose - outcome - atoms - steps - acceptance properties: # ----------------------------------------------------------------------- # BASIC TIER (inherited from kno-spec) # ----------------------------------------------------------------------- $schema: type: string const: "blueprint@1.0.0" description: "Schema declaration" id: type: string format: ulid description: "Unique identifier (ULID). Immutable birth identity." examples: - "01KP4AB7XYZ9MNQRT2EFJDGCWA" # pragma: allowlist secret slug: type: string format: kebab-case description: "Outcome-descriptive identifier for URLs and references." examples: - "white-label-saas-backend" - "ai-agent-toolkit" - "starter-kit" type: type: string const: "blueprint" description: "Entity type — always 'blueprint'" version: type: string format: semver description: "Blueprint version (semver). Required — Blueprints are themselves versioned per #1136 research." examples: - "1.0.0" - "1.2.3-beta.1" # ----------------------------------------------------------------------- # STANDARD TIER (inherited from document-schema) # ----------------------------------------------------------------------- title: type: string description: "Human-readable display name" examples: - "White-Label SaaS Backend" - "AI Agent Toolkit" purpose: type: string description: | What this Blueprint produces and why it exists. CommonMark supported. # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: outcome{} # The "box cover" — what you get when the Blueprint finishes building # ----------------------------------------------------------------------- outcome: type: object required: - summary - difficulty description: | What the finished Blueprint produces. Summary is for Library cards; personas + difficulty drive discovery filters. properties: summary: type: string description: "Short summary (≤400 chars) of the finished outcome" personas: type: array description: "Which personas this Blueprint serves (from the persona-library if one exists)" items: type: string examples: - [ "serial-launcher", "sludge-hater" ] difficulty: type: string enum: - simple - intermediate - advanced description: "Difficulty tier for Library filtering" estimated_duration: type: string description: | Human-readable estimate (e.g. "15 minutes manual, <60 seconds agent-driven"). Prefer concrete numbers; avoid vague "quick" or "easy". # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: atoms[] # Bill of materials — which platform Capabilities this Blueprint assembles # ----------------------------------------------------------------------- atoms: type: array minItems: 1 description: | The platform Capabilities this Blueprint assembles. Each entry references a Capability manifest via canonical XRI. The order of entries is not execution order (that lives in `steps[]`); it's a bill of materials for the consent + install-plan surfaces. items: type: object required: - ref - purpose properties: ref: type: string description: | Canonical XRI referencing a platform Capability manifest. Both unqualified (`pspace://capability/{slug}`) and version-qualified (`pspace://capability/{slug}@{range}`) forms are accepted — see capability-validation.ts for the authoritative pattern. pattern: "^pspace://capability/[a-z][a-z0-9-]*(?:@\\S(?:[^/@]*\\S)?)?$" examples: - "pspace://capability/auth-realm" - "pspace://capability/storage-bucket@^1.0.0" purpose: type: string description: | One-sentence explanation of why this atom is in the BOM. Consumed by the consent summary UI. optional: type: boolean default: false description: | True if this atom is skippable (e.g. omitted in some `variations[]`). Default false — the atom is required for the base outcome. # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: parameters[] # Template variables — what the Blueprint asks from the builder # ----------------------------------------------------------------------- parameters: type: array description: | Template variables the Blueprint substitutes at build time. Referenced as `{{name}}` in step bodies, endpoint URLs, and acceptance assertions. The compiler defines the substitution grammar; this schema only declares which variables exist. items: type: object required: - name - type properties: name: type: string format: snake-case description: "Parameter name (snake_case for template readability)" examples: - "project_name" - "project_slug" - "custom_domain" - "brand_color" type: type: string enum: - string - integer - boolean - url - email - color - enum description: "Parameter type. `enum` values must also populate `enum_values[]`." required: type: boolean default: false description: "True if the parameter has no default and must be provided by the builder" description: type: string description: "One-sentence description for the prompt UI" example: type: string description: "Example value shown as placeholder" default: description: "Default value used when parameter is not provided" enum_values: type: array items: type: string description: "Permitted values when `type` is `enum`" validation_pattern: type: string description: | Optional regex the value must satisfy. Applied by the compiler pre-substitution; authoritative source for validation-error messages. # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: diagrams{} # Referenced D2 diagrams — the visual specification # ----------------------------------------------------------------------- diagrams: type: object description: | Visual specifications referenced by the Blueprint. Each key is a well-known diagram role (architecture, user_flow, etc.); each value points at a `.d2` file via a project-relative path. Diagrams serve quadruple duty per DD-BP-03: documentation, acceptance contract, onboarding, and agent instruction. properties: architecture: type: object description: "Component topology the Blueprint produces" properties: ref: type: string description: "Path to `.d2` source (project-relative)" purpose: type: string user_flow: type: object description: "End-user journey through the built capability" properties: ref: type: string purpose: type: string build_states: type: object description: "What exists after each build step" properties: ref: type: string purpose: type: string layout: type: object description: "UI layout specification at key states (optional)" properties: ref: type: string purpose: type: string # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: steps[] # Build instructions — both human-readable and machine-executable # ----------------------------------------------------------------------- steps: type: array minItems: 1 description: | Ordered build steps. Each step has a human side (prose for people) and a machine side (executable API call + expected result + state capture). Per DD-BP-02, both sides must drive to the same `state_after`. items: type: object required: - step - title - human - machine - state_after properties: step: type: integer minimum: 1 description: "Step number — 1-indexed, monotonically increasing" title: type: string description: "Short imperative title (e.g. 'Provision Authentication')" human: type: string description: | Prose instruction (CommonMark). Written for a human builder. Consumed by the rendered guide view. machine: type: object required: - method description: | Executable side of the step. Agents read this block and issue the API call with parameter substitution. properties: method: type: string enum: [ GET, POST, PUT, PATCH, DELETE ] description: "HTTP method for API invocation" endpoint: type: string description: | Endpoint path template. May include `{{parameter}}` substitutions AND captured-state substitutions (e.g. `{{possibility_id}}` from an earlier step's captures). body: description: | Request body template. May be a YAML object with nested parameter substitutions. headers: type: object description: "Additional headers beyond authentication" mcp_tool: type: string description: | Optional MCP tool name as an alternative invocation path. When present, agents with MCP access MAY use this instead of the raw HTTP call. params: type: object description: "Parameters for the MCP tool invocation" expect: type: object description: | Success criteria for the call. Agents verify these before proceeding to the next step. properties: status: type: integer description: "Expected HTTP status code" captures: type: object description: | JSONPath expressions extracting values from the response body. Captured values are addressable as `{{capture_name}}` in subsequent steps. additionalProperties: type: string description: "JSONPath expression (e.g. `$.id`)" state_after: type: string description: | Prose description of the state the system is in after this step succeeds. Consumed by the build-state diagram and by post-step verification. diagram_ref: type: string description: | Optional fragment reference to the build-states diagram (e.g. `state-foo.d2#step-2`). Links the written `state_after` to its visual counterpart. rollback: type: object description: | Optional compensating-action block for failed builds. Mirrors the `machine` block shape. properties: method: type: string enum: [ GET, POST, PUT, PATCH, DELETE ] endpoint: type: string body: description: "Request body" # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: acceptance[] # Verification checklist — how we know the build worked # ----------------------------------------------------------------------- acceptance: type: array minItems: 1 description: | Executable acceptance criteria that verify the Blueprint produced the promised outcome. Each criterion maps to a type (unit / integration / e2e) and an assertion that can be compiled into an automated test. Per DD-BP-02, acceptance criteria verify BOTH sides (human and machine) drove to the same state. items: type: object required: - criterion - type - assertion properties: criterion: type: string description: "Human-readable statement of what's being verified" type: type: string enum: - unit - integration - e2e - visual description: "Test classification — determines where the assertion runs in the harness" assertion: type: string description: | Executable assertion body. The exact syntax depends on the target stack's test runner; parameter substitution applies. # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: variations[] # Alternate builds from the same (or reduced) atom set # ----------------------------------------------------------------------- variations: type: array description: | Named alternate builds that reuse the base Blueprint's atoms and steps with overrides. Variations let a single Blueprint serve multiple "difficulty modes" or "feature subsets" without duplicating the entire manifest. items: type: object required: - name - description properties: name: type: string description: "Short variation name (displayed in selectors)" description: type: string description: "What the variation changes" skip_atoms: type: array items: type: string description: "Atom slugs to OMIT from the base BOM" skip_steps: type: array items: type: integer description: "Step numbers to SKIP from the base steps[]" include_atoms: type: array items: type: string description: | When specified, the ONLY atoms built (whitelist mode). Mutually exclusive with skip_atoms. include_steps: type: array items: type: integer description: | When specified, the ONLY steps executed (whitelist mode). Mutually exclusive with skip_steps. parameter_overrides: type: object description: "Parameter values that override the builder's supplied values when this variation is selected" # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: composes_with[] # Stacking contracts — what this Blueprint is designed to build UP from # ----------------------------------------------------------------------- composes_with: type: array description: | Other Blueprints this one composes with — the "stack on top" relationship. Each entry declares the composition is known- good; the compiler may reject composition attempts that aren't declared here. items: type: object required: - xri - description properties: xri: type: string description: "Canonical XRI of the composed Blueprint" pattern: "^pspace://blueprint/[a-z][a-z0-9-]*(?:@\\S(?:[^/@]*\\S)?)?$" examples: - "pspace://blueprint/ai-agent-toolkit" - "pspace://blueprint/repository-intelligence@^1.0.0" description: type: string description: "What composing adds to the base outcome" adds_atoms: type: array items: type: string description: "New atoms introduced by the composition" # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: target_stacks[] # Which compiler targets a Blueprint supports (P1 Task 3 codegen field) # ----------------------------------------------------------------------- target_stacks: type: array minItems: 1 description: | Compiler target stack identifiers this Blueprint supports. The first target is the Possibility-native stack (`astro-hono-kno`); additional targets land as separate compiler passes per #1135 research § IR migration. A Blueprint may support multiple targets; the compiler selects one at build time. items: type: string enum: - astro-hono-kno - next-express - sveltekit-hono - remix-express - fastify-react examples: - [ "astro-hono-kno" ] - [ "astro-hono-kno", "next-express" ] # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: generator_version (P1 Task 3 codegen field) # ----------------------------------------------------------------------- generator_version: type: string format: semver description: | Compiler semver pin. Either the version of the compiler that produced this Blueprint (when generated from source) or the minimum compiler version required to consume it. Enables round-trip regeneration checks and compiler-drift detection. examples: - "0.1.0" - "1.0.0" # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: publisher{} # Publisher identity + trust tier (matches platform-capability 1.2.0) # ----------------------------------------------------------------------- publisher: type: object required: - id - tier description: | Publisher metadata. Three tiers mirror platform-capability- schema 1.2.0's publisher{} shape: - `platform` auto-verified at publish time (repo commit path = proof) - `verified` requires a signed publisher key (gated on Auth 7) - `community` is self-declared; no signature verification properties: id: type: string description: | Publisher identifier. For `platform` tier: ULID or the canonical slug `possibility-space`. For `verified` / `community` tiers: ULID referencing a publisher entity. tier: type: string enum: - platform - verified - community # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: compatibility{} # Platform version + deprecation (matches platform-capability 1.2.0) # ----------------------------------------------------------------------- compatibility: type: object description: | Declares platform version range + deprecation state. Mirrors platform-capability-schema 1.2.0 so Library surfaces treat Capability and Blueprint compatibility/deprecation uniformly. properties: requires_pspace_version: type: string description: "node-semver range for platform compatibility" examples: - "^1.0.0" - ">=2.0.0" deprecated: type: boolean default: false deprecation_notice: type: string deprecated_from: type: string format: semver end_of_life: type: string format: date # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: categories[] # Closed-enum classification (matches platform-capability 1.2.0) # ----------------------------------------------------------------------- categories: type: array maxItems: 5 description: | Closed-enum categories. Drives Library browse + filter UX. A Blueprint may belong to multiple categories. items: type: string enum: - ai - analytics - authentication - authorization - cms - commerce - communication - developer-tools - identity - integration - messaging - monitoring - search - security - storage - workflow # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: keywords[] # Open free-form keywords for fine-grained search (matches platform-cap 1.2.0) # ----------------------------------------------------------------------- keywords: type: array maxItems: 12 description: | Open-ended searchable keywords. Complements `categories[]`. items: type: string # ----------------------------------------------------------------------- # DOMAIN-SPECIFIC: featured # Editorial promotion flag (matches platform-capability 1.2.0) # ----------------------------------------------------------------------- featured: type: boolean default: false description: | Editorial featured flag. Set by `platform` publishers only. # ============================================================================= # EXAMPLES # ============================================================================= examples: - title: "Minimal Blueprint (single-atom, two-step)" description: "The smallest shape a Blueprint can take — one atom, two steps (create container, provision atom), one acceptance criterion." content: | $schema: blueprint@1.0.0 id: 01KPZWR9AB12CDEFGHIJKLMNOP # pragma: allowlist secret slug: simple-auth-starter type: blueprint version: 1.0.0 title: "Simple Auth Starter" purpose: | Provision a single auth realm inside a fresh Possibility. The smallest useful Blueprint — useful for testing the compiler round-trip. outcome: summary: "A Possibility with a working auth realm." difficulty: simple estimated_duration: "2 minutes manual, <10 seconds agent-driven" atoms: - ref: "pspace://capability/auth-realm@^1.0.0" purpose: "OIDC identity provider scoped to this Possibility" parameters: - name: project_name type: string required: true description: "Human-readable project name" example: "Acme Consulting" - name: project_slug type: string required: true description: "URL-safe identifier" example: "acme-consulting" steps: - step: 1 title: "Create the Possibility" human: "Create a new Possibility to hold your auth realm." machine: method: POST endpoint: /admin/possibilities body: name: "{{project_name}}" slug: "{{project_slug}}" expect: status: 201 captures: possibility_id: "$.id" state_after: "A Possibility entity exists. No infrastructure yet." - step: 2 title: "Provision Authentication" human: "Install the auth-realm Capability into your Possibility." machine: method: POST endpoint: /admin/possibilities/{{possibility_id}}/capabilities/install body: capability_slug: auth-realm expect: status: 200 state_after: "Auth realm exists. Login page available." acceptance: - criterion: "Login page loads for the new realm" type: e2e assertion: | navigate("https://auth.possibility.space/realms/pspace-{{project_slug}}") expect(page).toContainText("Sign in") target_stacks: - astro-hono-kno generator_version: "0.1.0" publisher: id: "possibility-space" tier: platform categories: - authentication keywords: - starter - auth - minimal