# Quickstart Schema — Layer 3 Entity Type # KNO Schema Version: 0.4.0 # CHANGELOG: # 0.4.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18. # Quickstarts are public reference knowledge consumed via # the four-surface contract. # # A Quickstart describes a single agent-integration recipe: how a specific # client surface (Claude Code, VS Code Copilot, A2A agent, etc.) connects # to Possibility — its prerequisites, transport, config snippet, setup # steps, verification steps, and troubleshooting. # # EXTENDS: document-schema.kno (which composes identity, history, quality) # # DESIGN DECISIONS: # - DD-QS-01: Quickstarts are .kno entities; the manifest's `quickstarts` # block is derived (#1610). Mirrors the mcp-server-schema → manifest # projection introduced by #1543. # - DD-QS-02: Strings may contain placeholder tokens that the projection # function substitutes at manifest generation: `{API_URL}`, `{SITE_URL}`, # `{ALL_MCP_SCOPES_STRING}`. This keeps each .kno file environment- # portable across staging, production, and developer overrides. # - DD-QS-03: When a quickstart's config snippet enumerates the live MCP # server list, it uses a `derived_config_snippet` directive (rather than # a hardcoded snippet) so adding a new MCP server propagates without # touching the quickstart .kno. Static snippets stay literal. # - DD-QS-04: `surface_id` is the manifest key (claude_code, claude_desktop, # vscode_copilot, etc.). The drift-guard test enforces uniqueness across # the catalog. # # USE CASES: # - Agent client integrations (Claude Code, Claude Desktop, VS Code Copilot, # GitHub Copilot CLI, Google AI Studio) # - Generic transport recipes (CLI / curl, custom agent, A2A agent) # - Authoring recipes (capability submission) # # MAPS TO: QuickstartConfig interface in services/pspace-api/src/portico/types.ts # ============================================================================= # SCHEMA DECLARATION # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY # ============================================================================= id: 01KPP7C5N6YQX9R7MGFKQ0QSCH slug: quickstart-schema type: spec version: 0.4.0 # ============================================================================= # VISIBILITY DECLARATION (REQ-18) — collection default # ============================================================================= # Quickstart entities (content/quickstarts/*.kno) are public reference knowledge # by default — they describe agent-integration recipes for client surfaces. # 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: "Quickstart Schema" purpose: | Define the schema for Quickstart entities — machine-readable agent integration recipes projected into the integration manifest's `quickstarts` block. **What is a Quickstart entity?** A .kno file declaring a single client/surface integration recipe: its prerequisites, transport, config snippet (literal or derived), setup steps, verification steps, and troubleshooting list. **Why a separate schema (not document-schema with purpose: quickstart)?** Per kno-foundational-principles § 0.6 (Schema Minimization), this passes the three-gate test: - Gate 1 (Distinctness): Quickstarts are structured agent-integration recipes (transport + config_snippet + setup_steps + troubleshooting), not narrative documents. They share shape with mcp-server-schema and agent-card-schema, not with prose documents or guides. - Gate 2 (Reusability): 9+ instances at introduction (Claude Code, Claude Desktop, VS Code Copilot, Copilot CLI, Google AI Studio, CLI, custom agent, A2A agent, capability authoring); growable as new agent surfaces emerge (Cursor, Continue, Cline, Zed). - Gate 3 (Clarity): Separating quickstart configs from documents and guides keeps the projection logic type-driven and matches the existing `service-config/mcp-server` and `service-config/agent-card` pattern. **Derived view:** The integration manifest at /.well-known/integration projects all `content/quickstarts/*.kno` files into `quickstarts.` via `scanBundles()` in services/pspace-api/src/portico/manifest.ts. # ============================================================================= # RICH TIER — Taxonomy # ============================================================================= provenance: origin: id: 01KPP7C5N6YQX9R7MGFKQ0QSCH timestamp: "2026-04-20T00:00:00Z" tool: manual taxonomy: topics: - quickstart - agent-integration - integration-manifest - protocol-discovery keywords: - quickstart - mcp-client - a2a-client - device-flow - bootstrap # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: extends: - xri: "kno://specs/document-schema" reason: "Quickstart entities inherit identity, history, and quality fields" related_to: - xri: "kno://specs/mcp-server-schema" reason: "Quickstarts often reference MCP servers via the derived_config_snippet directive" - xri: "kno://specs/agent-card-schema" reason: "Quickstarts may reference A2A agents (e.g., the a2a_agent quickstart)" # ============================================================================= # REQUIRED FIELDS # ============================================================================= fields: # --------------------------------------------------------------------------- # IDENTITY (inherited from document-schema, restated for clarity) # --------------------------------------------------------------------------- id: type: string format: ulid required: true description: "ULID of this Quickstart entity (immutable birth identity)" slug: type: string required: true pattern: "^pspace-quickstart-[a-z0-9-]+$" description: | Human-readable identifier. MUST follow the `pspace-quickstart-{surface}` pattern. Examples: `pspace-quickstart-claude-code`, `pspace-quickstart-vscode-copilot`. type: type: string enum: - service-config required: true description: | Top-level kind. Reuses `service-config` (validated by the kno-spec type registry) with the `subtype` discriminator. Mirrors the mcp-server-schema and agent-card-schema convention. subtype: type: string enum: - quickstart required: true description: | Discriminator that identifies this entity as a quickstart recipe among other service-config subtypes. version: type: string format: semver required: true # --------------------------------------------------------------------------- # QUICKSTART-SPECIFIC FIELDS # --------------------------------------------------------------------------- surface_id: type: string required: true pattern: "^[a-z][a-z0-9_]*$" description: | Manifest key for this quickstart (snake_case). Examples: `claude_code`, `claude_desktop`, `vscode_copilot`, `copilot_cli`, `google_ai_studio`, `cli`, `custom_agent`, `a2a_agent`, `capability_authoring`. The drift-guard test enforces uniqueness. description: type: string required: true description: "One-sentence human-readable description of the quickstart" time_estimate: type: string required: false description: | Optional honest estimate of how long the quickstart takes a first-time reader to complete (setup through verification). Per the "honest estimates" discipline: measurements backed by ≥3 first-time users are preferred over author guesses. When publishing an author estimate, mark with an inline comment (`# author-estimate, not measured`) so the measurement backlog is traceable. Mirrors `guide-schema.kno`'s field so a shared `` component can render both surfaces uniformly (see #1636). examples: - "5 minutes" - "10-15 minutes" - "30 minutes" config_file: type: string required: false description: "Path of the config file the user must edit, if any (e.g., `~/.claude/settings.json`)" transport: type: string enum: - streamable_http - stdio_bridge required: false description: "Transport protocol the client uses to reach Possibility" bridge_needed: type: boolean required: false description: "Whether a bridge binary/script is required (clients that don't support remote MCP)" prerequisites: type: array items: type: string required: false description: "What the user must have installed before starting. Strings may contain `{API_URL}`, `{SITE_URL}`, and `{ALL_MCP_SCOPES_STRING}` placeholders." config_snippet: type: object required: false description: | Literal config snippet emitted verbatim into the manifest. Use this for surfaces with static config (e.g., the illustrative two-server bridge example for Claude Desktop). For surfaces that should enumerate the live MCP server list, use `derived_config_snippet` instead. derived_config_snippet: type: object required: false description: | Projection directive for surfaces that enumerate the live MCP server list. Required keys: - `root_key`: outer key (e.g., `mcpServers`, `servers`) - `key_format`: how server slugs map to entry keys (`keep-pspace-prefix`, `strip-pspace-prefix`) - `entry`: object with the per-server entry shape; `url` field is auto-substituted with the endpoint URL - `exclude_admin`: bool; when true, skips `pspace-admin-*-mcp` Mutually exclusive with `config_snippet`. setup_steps: type: array items: type: string required: true description: "Ordered steps the user follows to complete setup. Strings may contain `{API_URL}`, `{SITE_URL}`, and `{ALL_MCP_SCOPES_STRING}` placeholders." example_curl: type: string required: false description: "Example curl invocation block (multi-line). May contain `{API_URL}`, `{SITE_URL}`, and `{ALL_MCP_SCOPES_STRING}` placeholders." protocol_recommendation: type: string required: false description: "Recommendation about which protocol (MCP / A2A / REST) to use. May contain placeholders." auth_recommendation: type: string required: false description: "Recommendation about which auth flow (Device / Client Credentials) to use. May contain placeholders." a2a_sdk_example: type: object required: false description: | A2A SDK code example. Required keys: `description`, `code`. Both may contain placeholders. verification_steps: type: array items: type: string required: false description: "Steps to verify the integration is working. May contain placeholders." troubleshooting: type: array items: type: object required: false description: | Array of `{problem, solution}` objects covering common failure modes. Both fields may contain placeholders. alternative_setup: type: object required: false description: | Alternative setup path (e.g., Claude Desktop's Streamable HTTP route). Required keys: `description`, `steps`. Optional: `config_snippet` or `derived_config_snippet`. All strings may contain placeholders. diagrams: type: array required: false description: | OPTIONAL (v0.3.0+, R14 / #1641). Entity-level inline diagrams rendered alongside the quickstart's setup steps when the quickstart is consumed through an HTML surface. Each diagram declares its D2 source + required alt text + optional caption. Mirrors the `guide-schema.kno` `diagrams:` field so the shared `` component consumes both surfaces uniformly. Rendered via `renderD2ToSvgApi` at page render time (runtime HTTP roundtrip to pspace-api `/kno/render/svg`) — aligned with the existing `` pattern. Markdown / agent consumers receive the D2 source as a fenced ` ```d2 ` block in the markdown output (R11 coupling). Accessibility contract: `alt` is required — it becomes the `aria-label` on the emitted ``. items: type: object required: [id, d2, alt] properties: id: type: string description: "Stable slug for the diagram. Pattern: `[a-z0-9-]+`." d2: type: string description: | D2 source (multi-line via `|`). May use styling conventions from `specs/d2-forks-style-template.kno`. alt: type: string description: | Short description of what the diagram shows, for assistive tech. Required. caption: type: string description: | OPTIONAL caption rendered below the SVG as `
`. # ============================================================================= # QUALITY # ============================================================================= quality: completeness: 1.0 last_reviewed: "2026-04-20" review_status: stable # ============================================================================= # HISTORY # ============================================================================= _history: version: 3 created: "2026-04-20T00:00:00Z" created_by: "pspace-core-team" changes: - "v0.1.0: Initial schema introduced for #1610 (quickstarts generative-from-.kno)" - "v0.2.0 (2026-04-22): Added optional `time_estimate` field for R9 (#1636); mirrors `guide-schema.kno` to enable a shared `` render component across guides and quickstarts." - "v0.3.0 (2026-04-22): Added optional `diagrams:` array for R14 (#1641); mirrors `guide-schema.kno` v0.11.0 for a shared `` render component. D2 source + required alt text enforce the accessibility contract. Runtime render via `renderD2ToSvgApi` (existing pattern); no build-time cache introduced in this sprint."