# Guide Schema — Layer 3 Specialized Document Type # KNO Schema Version: 0.12.0 # CHANGELOG: # 0.12.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18. # Guides are public reference knowledge consumed via the # four-surface contract. # # Layer 3 schema that extends document-schema.kno for how-to guides. # Guides are instructional documents with steps, prerequisites, and outcomes. # # EXTENDS: document-schema.kno (which composes identity, history, quality) # ENABLES: Guide instances (how-to documents, tutorials, runbooks) # # INSTANCE CONVENTION (required): # $schema: kno@0.0.9 # type: guide # conforms_to: kno://specs/guide-schema # id: # RFC-013 immutable birth identity (26 chars, Crockford Base32) # slug: # human-readable alias, mutable # # Developer Guides & Tutorials (M38) — extends schema per spec §4.3 and # bedrock conformance audit (CONFORMANCE-01, -02, -04, -07, -09). # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY (composed from identity-schema.kno) # ============================================================================= id: 01KGK3V73G7EWGR6AZ26Y8MQDK slug: guide-schema type: spec version: 0.12.0 # ============================================================================= # VISIBILITY DECLARATION (REQ-18) — collection default # ============================================================================= # Guide entities (content/guides/*.kno) are public reference knowledge by default. # 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 (inherited from document-schema.kno) # ============================================================================= title: "Guide Schema" purpose: | Define the schema for how-to guides — instructional documents. **What is a Guide?** A guide is a document that teaches the reader how to accomplish a specific task or goal. Guides have: - Prerequisites (what you need before starting) - Steps (ordered actions to take) - Outcomes (what success looks like) **Guide Types**: | Type | Purpose | Example | |------|---------|---------| | `how-to` | Task-oriented | "How to deploy Possibility" | | `tutorial` | Learning-oriented | "Building your first .kno file" | | `runbook` | Operations-oriented | "Database migration procedure" | | `quickstart` | Getting started | "5-minute Possibility setup" | | `pattern` | Reusable solutions | "API versioning pattern" | | `checklist` | Verification lists | "Production deployment checklist" | | `reference` | Reference documentation | "API endpoint reference" | **Layer 3 Position**: Guide extends document (Layer 2), which composes identity, history, and quality (Layer 1). # ============================================================================= # RICH TIER — Relationships (Edge Maximization) # ============================================================================= provenance: origin: id: 01KGK3V73G7EWGR6AZ26Y8MQDK timestamp: "2026-02-04T01:47:56Z" tool: manual-migration taxonomy: topics: - documentation - tutorials - how-to - runbooks - instructions keywords: - guide - how-to - tutorial - steps - procedure - runbook - quickstart relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type" depends_on: - xri: "kno://specs/kno-spec" reason: "RFC-001 defines kno@0.0.9 schema" composes: # Inherited through document-schema.kno: - xri: "kno://specs/identity-schema" reason: "Layer 1: id, canonical_id, local_ids, equiv_ids" - xri: "kno://specs/history-schema" reason: "Layer 1: _history, changelog" - xri: "kno://specs/quality-schema" reason: "Layer 1: quality, validation, confidence" enables: - xri: "kno://docs/getting-started" reason: "Getting started guide" - xri: "kno://docs/deployment-guide" reason: "Deployment guide" - xri: "kno://docs/runbooks/database-migrations" reason: "Database migrations runbook" related_to: - xri: "kno://specs/spec-schema" reason: "Sibling Layer 3 type" - xri: "kno://specs/rfc-schema" reason: "Sibling Layer 3 type" - xri: "kno://specs/glossary-schema" reason: "Sibling Layer 3 type" - xri: "kno://specs/llms-txt-format" reason: "Aggregate-corpus format produced from guide collection" # ============================================================================= # AGGREGATE CORPUS PRODUCTION (per kno-system_architecture v1.13.0) # ============================================================================= # This schema \u2014 or a guide-index (collection-level) entity that references it \u2014 # may declare `produces: [llms-txt-format]`. A thin transformation reads the # forward `documents` edges across guide entities and concatenates markdown # blocks into `/docs/llms.txt`. No conversion spec is required; the production # rule is the schema-graph edge itself. produces: - xri: "kno://specs/llms-txt-format" reason: "Aggregate corpus (llms.txt) materialized via thin transformation" quality: completeness: 0.85 last_reviewed: "2026-01-06" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY (P9 Temporal) # ============================================================================= _history: retention: full format: snapshot versions: - version: "0.11.0" date: "2026-04-22" author: "sprint-3-design-patterns-adoption" summary: "Add entity-level inline diagrams (R14 / #1641)" changes: - "Added optional entity-level `diagrams:` array. Each diagram declares `id`, `d2` source, required `alt` text, and optional `caption`. Rendered via the new `` component which reuses the existing `renderD2ToSvgApi` helper — same runtime-render pattern as ``, no new rendering path or build-time cache introduced." - "`alt` is required to enforce the WCAG accessibility contract: every rendered `` carries a non-empty accessible name derived from this field." - "Follows the entity-level (Option A) schema shape per the Sprint 3 kickoff retrospective — step-level diagrams would require restructuring quickstart `setup_steps` from `array` to `array`, deferred as out-of-scope." - "Build-time SVG caching deferred to a follow-up optimisation issue in milestone #43 (Developer Experience Features v1); current runtime HTTP render is the established site pattern." - version: "0.10.0" date: "2026-04-22" author: "sprint-2-design-patterns-adoption" summary: "Add structured semantic callouts on steps (R5 / #1632)" changes: - "Added optional `callouts:` array to step schema — each callout declares `type` (note / success / caution / warning) and `body`. Rendered via the shared `` component with colour + icon + severity-word label; meets WCAG 1.4.1 by not relying on colour alone." - "Existing `warning:` and `tip:` step fields remain supported and now render via the same `` component. No migration required for the 36 guides using them; `warning:` resolves to `caution` severity, `tip:` resolves to `note`." - "Style-guide and forks-style-guide.kno updated with callout type definitions, icons, and usage guidance." - version: "0.9.0" date: "2026-04-20" author: "claude" summary: "Add getting-started specialization (M38 Phase 9.4, #1546)" changes: - "Added `getting-started` to the `guide_type` enum. Per the Three-Gate Test (kno-foundational-principles.md § 0.6) extending guide-schema beats creating a separate getting-started-schema: a getting-started flow IS a guide with extra optional fields." - "Added optional `persona` field with enum [public, creator, admin] for the 3-persona axis of the getting-started matrix." - "Added optional `stage` field with enum [learn, start, use] for the 3-stage axis of the getting-started matrix." - "Extended `steps[]` with optional `tool_call` ({ surface, target, params }) describing the REST/MCP/CLI invocation a step performs. Declarative authoring; runner is out of scope for this version." - "Extended `steps[]` with optional `success_check` ({ type, expression }) describing how a step verifies success programmatically. Complements existing string `verification` field." - "Extended `steps[]` with optional `troubleshoot` (array of XRIs) referencing M37 integration-guide reference docs. Distinct from the existing `troubleshooting` string (per-step prose)." - "All new fields are optional and only meaningful when guide_type is `getting-started` — no breaking changes for any existing guide." - "The 3×3 matrix is exposed by the integration manifest as `getting_started: { public: {…}, creator: {…}, admin: {…} }`, generated from `content/guides/*.kno` files tagged with `guide_type: getting-started`. No hardcoded list." - version: "0.8.2" date: "2026-04-17" author: "claude" summary: "Mark `learning_paths` as derived (P7 forward-only); audit punch-list PL-008 (#1485)" changes: - "Marked `learning_paths` as `derived: true` with explicit \"DO NOT POPULATE ON INSTANCES\" guidance. Path membership is declared forward-only by the `guides-page` collection; guides must not reverse-declare per P7." - "Updated the 'Learning Paths' narrative block in `purpose` to match." - "No breaking changes — field was already unpopulated by all 7 migrated guides; change only codifies the correct pattern." - version: "0.8.1" date: "2026-04-17" author: "maxispossible" summary: "Add `vendor-integration` and `vendor-comparison` to guide_type enum (M38 Phase 4, issue #1440)" changes: - "Added `vendor-integration` and `vendor-comparison` to the `guide_type` enum. These values mark documents that are exempt from the provider-opacity lint per content/knowledge-base/provider-opacity.kno § 3 — necessary for the DNS setup walkthrough (#1440) and future vendor-specific guides." - "No breaking changes — purely additive enum expansion." - version: "0.8.0" date: "2026-04-17" author: "maxispossible" summary: "Promote code_samples[] to canonical; deprecate singular code/code_language; add step-level troubleshooting (M38 Phase 4, ADR-001)" changes: - "Added `steps[].code_samples[]` as canonical code-block shape (array of { language, code, description }). Supports multiple samples per step (e.g., shell + YAML + verification output)." - "Marked `steps[].code` and `steps[].code_language` as DEPRECATED (still accepted for backward-compat through v0.x; removed in v1.0). New guides MUST use `code_samples[]`." - "Added `steps[].troubleshooting` (optional string) to surface per-step diagnostic notes — closes the renderer gap flagged in Phase 3 mini retro." - "Clarified top-level `troubleshooting[]` field shape: canonical items use `{ problem, solution, cause }`; renderer also accepts `{ issue, solution }` as a deprecated alias during migration." - "No breaking changes — all v0.7.1 guides remain valid." - version: "0.7.1" date: "2026-04-16" author: "claude" summary: "Relax required list for narrative guide types (M38 Phase 2 migration)" changes: - "Moved `outcomes`, `prerequisites`, `steps`, `next_steps` from REQUIRED to STRONGLY RECOMMENDED" - "Rationale: imperative fields fit how-to/tutorial/quickstart/runbook/checklist but not overview/fundamental/reference/best-practice/pattern guide types" - "Required core (12 fields): id, slug, type, title, conforms_to, purpose, domain, guide_type, provenance, relationships, quality (+ type='guide' const)" - "No field removed — only required → optional reclassification" - version: "0.7.0" date: "2026-04-16" author: "claude" summary: "Developer Guides & Tutorials (M38) Phase 2 schema extension" changes: - "Reconciled version mismatch (was root 0.0.2 / header 0.6.0; now coherent 0.7.0)" - "Required id is ULID (RFC-013 / foundational-principles §0.7); added slug property for kebab-case alias" - "Required conforms_to = kno://specs/guide-schema (instance convention)" - "Extended guide_type enum: added `fundamental`, `overview`, `best-practice`" - "Added `domain` (required): fundamentals | auth | email | storage | capabilities | best-practices" - "Added `learning_paths` (optional): array of curated-sequence slugs" - "Added `time_estimate` (optional, canonical); retained `estimated_time` as deprecated alias" - "Added `difficulty`, `audience`, `effort` as OPTIONAL author-hints only (per DC-2 Edge Inference)" - "Added top-level `verification`, `what_youll_build`, `skip_manual_setup`" - "Required `provenance.origin.{id, timestamp}` (REQ-16 / §0.8)" - "Required `relationships.documents` (P7 predicate vocabulary v1.20.0)" - "Added optional typed reference predicates: related_specs, related_api, related_rfcs, examples" - "Added `produces: [llms-txt-format]` at schema level (aggregate-corpus production)" - "Added instance-convention note in file header" - version: "0.6.0" date: "2026-02-02" author: "claude" summary: "Extended guide_type enum for playbook components (Issue #51)" changes: - "Added guide_type values: pattern, checklist" - "Updated documentation tables with new types" - "Backwards-compatible: all new values are optional additions" - version: "0.5.0" date: "2026-01-06" author: "claude" summary: "Initial Layer 3 guide schema" changes: - "Created as Layer 3 schema extending document-schema.kno" - "Defined steps, prerequisites, outcomes structure" - "Added guide_type enum" # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Draft description: | ## What is a Guide? A **guide** is an instructional document that teaches the reader how to accomplish a specific task or goal. ## Guide Structure Guides follow a consistent structure: 1. **Prerequisites** — What you need before starting 2. **Steps** — Ordered actions to take 3. **Outcomes** — What success looks like 4. **Troubleshooting** — Common problems and solutions ## Guide Types | Type | Focus | Structure | |------|-------|-----------| | `how-to` | Task completion | Steps focused | | `tutorial` | Learning | Explanatory | | `runbook` | Operations | Checklist-style | | `quickstart` | Fast start | Minimal steps | | `pattern` | Reusable solutions | Context/problem/solution | | `checklist` | Verification | Items to verify | | `reference` | Lookup | Structured reference | | `fundamental` | Foundational concept | Explanatory, minimal steps | | `overview` | Orientation / umbrella | Narrative, cross-links | | `best-practice` | Recommended pattern | Narrative, examples | ## Domains Every guide declares a `domain` locating it in the IA: | Domain | Content | |--------|---------| | `fundamentals` | .kno, KAML, entity model, XRI | | `auth` | OIDC, realms, branded login | | `email` | SMTP, DNS, deliverability | | `storage` | Blob (MinIO), entity (Hive), access control | | `capabilities` | Authoring, publishing, composition | | `best-practices` | Platform patterns, dog-fooding, federation | ## Learning Paths Learning-path membership is DERIVED from the `guides-page` collection (`content/guides-page.kno`), which declares each path and lists its member guide slugs in order. Guide instances MUST NOT populate a `learning_paths` field — doing so would violate P7 (forward-only edge storage) and create bidirectional maintenance drift. Learning paths are a domain-level construct (not a bedrock primitive — see ADAPT-06). The field is retained in the schema definition below as `derived: true` documentation only; authoring tools should reject attempts to set it on instances. ## Subjective Hints (Edge Inference) `difficulty`, `audience`, and `effort` are OPTIONAL author-hint fields. Per foundational-principles DC-2 (Edge Inference Over Declarative Judgments) these are SUBJECTIVE and SHOULD be inferred by consumers from content (prereq count, step count, code volume). UIs MUST NOT render them as authoritative categorization. ## Layer 3 Inheritance ``` guide-schema.kno └── extends: document-schema.kno └── composes: identity-schema.kno, history-schema.kno, quality-schema.kno ``` # =========================================================================== # SCHEMA DEFINITION # =========================================================================== schema: # ------------------------------------------------------------------------- # Required Fields # ------------------------------------------------------------------------- required: - id # ULID birth identity (RFC-013) - slug # kebab-case alias - type # const 'guide' - title - conforms_to # kno://specs/guide-schema - purpose - domain # fundamentals | auth | email | storage | capabilities | best-practices - guide_type - provenance # provenance.origin.{id, timestamp} required - relationships # must include `documents` edge(s) - quality # NOTE: outcomes, prerequisites, steps, next_steps are STRONGLY RECOMMENDED # for imperative guide_types (how-to, tutorial, quickstart, runbook, checklist) # but are OPTIONAL for narrative/reference types (overview, fundamental, # reference, best-practice, pattern). Producers SHOULD provide them when # meaningful; the schema does not gate acceptance on their presence. # ------------------------------------------------------------------------- # Field Definitions # ------------------------------------------------------------------------- properties: # --- INHERITED FROM IDENTITY.KNO (Layer 1) --- id: type: string description: | ULID birth identity (RFC-013 / foundational-principles §0.7). Immutable. 26 characters, Crockford Base32. pattern: "^[0-9A-HJKMNP-TV-Z]{26}$" examples: - "01KGK3V73G7EWGR6AZ26Y8MQDK" slug: type: string description: | Human-readable kebab-case alias. Mutable. Exposed via alias-resolution surfaces only (e.g. /guides/by-slug/:slug); canonical routes anchor on `id`. pattern: "^[a-z][a-z0-9-]*$" examples: - "getting-started" - "login-with-possibility-quickstart" conforms_to: type: string const: "kno://specs/guide-schema" description: "Schema anchor (Layer 3 reference)" # --- INHERITED FROM DOCUMENT.KNO (Layer 2) --- type: type: string const: guide description: "Entity type, always 'guide'" version: type: string description: "Semantic version" pattern: "^\\d+\\.\\d+\\.\\d+$" title: type: string description: "Human-readable title" examples: - "Getting Started with Possibility" - "Database Migration Runbook" purpose: type: string description: "What this guide teaches" # REMOVED (prior version): audience required, facets, difficulty required. # REINSTATED v0.7.0 as OPTIONAL hints only (per DC-2 Edge Inference): # difficulty, audience, effort — see below. # --- GUIDE-SPECIFIC FIELDS --- guide_type: type: string enum: [ how-to, tutorial, runbook, quickstart, reference, pattern, checklist, fundamental, overview, best-practice, vendor-integration, vendor-comparison, getting-started, ] description: | Type of guide. The `vendor-integration` and `vendor-comparison` values exempt the document from the provider-opacity lint per `content/knowledge-base/provider-opacity.kno` § 3 — use them only when vendor-specific UI detail is the point of the guide. The `getting-started` value (v0.9.0+, #1546) marks guides that participate in the manifest's 3-persona × 3-stage matrix. Such guides MUST also declare `persona` and `stage` (see below). default: how-to domain: type: string enum: [ fundamentals, auth, email, storage, capabilities, collaboration, best-practices ] description: | IA domain the guide belongs to. Drives /docs/guides/[domain]/[slug] routing and the domain-card grid on the Guides hub. learning_paths: type: array derived: true description: | DERIVED — DO NOT POPULATE ON INSTANCES. Learning-path membership is declared forward-only by the `guides-page` collection (`content/guides-page.kno`), which lists each path's member guide slugs in order. Per P7 (forward-only edge storage), guides do not reverse-declare their paths. Retained in the schema for documentation; authoring tools should reject instances that set this field. items: type: string pattern: "^[a-z][a-z0-9-]*$" time_estimate: type: string description: "Canonical v0.7.0 field for estimated completion time" examples: - "5 minutes" - "30-60 minutes" estimated_time: type: string description: | DEPRECATED v0.7.0 — use `time_estimate` instead. Retained for back-compatibility with v0.5.x and v0.6.x guide instances. examples: - "5 minutes" # --- OPTIONAL SUBJECTIVE HINTS (DC-2 Edge Inference) --- difficulty: type: string enum: [ beginner, intermediate, advanced ] description: | OPTIONAL author hint. Subjective per DC-2. Consumers MAY infer from content. UIs MUST NOT render as authoritative categorization. audience: type: string description: | OPTIONAL author hint describing the intended reader (e.g. "web developer", "tenant organizer"). Subjective per DC-2. effort: type: string description: | OPTIONAL author hint describing relative effort. Subjective per DC-2. # --- GETTING-STARTED MATRIX FIELDS (v0.9.0+, #1546) --- # Only meaningful when `guide_type: getting-started`. Drives the manifest's # `getting_started` block (3-persona × 3-stage matrix). No new schema — # extends guide-schema per the Three-Gate Test outcome documented in # changelog v0.9.0. persona: type: string enum: [ public, creator, admin ] description: | OPTIONAL. Required when `guide_type: getting-started`. Identifies the audience axis of the manifest matrix: - `public` — anonymous learners, sample explorers - `creator` — builders shipping their own possibility - `admin` — operators provisioning / running the platform stage: type: string enum: [ learn, start, use ] description: | OPTIONAL. Required when `guide_type: getting-started`. Identifies the journey axis of the manifest matrix: - `learn` — understand what's possible - `start` — take a first concrete action - `use` — ongoing operation / extension what_youll_build: type: string description: | OPTIONAL. For tutorials: one-paragraph description of the artifact the reader will produce. prerequisites: type: array description: "What you need before starting" items: type: object properties: item: type: string description: "Prerequisite item" required: type: boolean default: true link: type: string format: uri description: "Link to prerequisite resource" outcomes: type: array description: "What you'll achieve" items: type: string diagrams: type: array description: | OPTIONAL (v0.11.0+, R14 / #1641). Entity-level inline diagrams rendered between sections of the guide. Each diagram declares its D2 source + required alt text + optional caption. Rendered via `` which wraps the existing `renderD2ToSvgApi` helper used elsewhere on the site — no new rendering path is introduced. SVG is produced by pspace-api's `/kno/render/svg` endpoint at page render time (runtime HTTP roundtrip, aligned with `` precedent). Accessibility contract: `alt:` is required; it becomes the `aria-label` on the emitted ``. Never commit a diagram with an empty alt — the renderer will refuse it. items: type: object required: [id, d2, alt] properties: id: type: string description: | Stable slug for the diagram. Used as anchor + fallback content-addressing key. Pattern: `[a-z0-9-]+`. d2: type: string description: | D2 source. May use styling conventions from `specs/d2-forks-style-template.kno`. Multi-line via `|`. alt: type: string description: | Short description of the diagram's meaning for assistive tech. Not the same as a caption — the alt should convey *what the diagram shows* so a non-sighted reader gets equivalent information. Required. caption: type: string description: | OPTIONAL caption rendered below the SVG as `
`. Visible to all readers; complements but doesn't replace the alt text. steps: type: array description: "Ordered steps to follow" items: type: object required: - title properties: number: type: integer description: "Step number (auto-generated if omitted)" title: type: string description: "Step title" description: type: string description: "Detailed instructions" code_samples: type: array description: | CANONICAL (v0.8.0+). Zero or more code blocks attached to this step. Supports multiple samples per step — e.g., shell command + YAML config + expected output. Renderer at `services/pspace-site/src/pages/docs/guides/[slug].astro` consumes this shape. New guides MUST use `code_samples[]` rather than the deprecated singular `code`/`code_language`. See ADR-001 (`docs/planning/developer-guides/adr/001-code-sample-validation.md`) for Tier 1/2/3 sample strategy. items: type: object required: - code properties: language: type: string description: "Language identifier for syntax highlighting (e.g. 'bash', 'typescript', 'yaml', 'http', 'dns')." code: type: string description: "The code block contents (verbatim)." description: type: string description: "Optional caption rendered above the code block (e.g. 'Create the domain:', 'Expected response:')." code: type: string deprecated: true description: | DEPRECATED in v0.8.0 — use `code_samples[]` instead. Retained for backward-compat with v0.5.x–0.7.x guides. Removed in v1.0.0. code_language: type: string deprecated: true description: | DEPRECATED in v0.8.0 — use `code_samples[].language` instead. Retained for backward-compat. Removed in v1.0.0. warning: type: string description: | Warning or caution for this step. Rendered as a `caution`-severity callout (orange) via the shared `` component (v0.10.0+, R5 / #1632). Prefer the newer `callouts:` array for new content — it supports all four severities explicitly. tip: type: string description: | Helpful tip for this step. Rendered as a `note`-severity callout with a "Tip:" label via the shared `` component (v0.10.0+, R5 / #1632). Prefer `callouts:` for new content. callouts: type: array description: | OPTIONAL (v0.10.0+, R5 / #1632). Structured semantic callouts attached to this step. Each callout must declare a severity `type` (note / success / caution / warning) and a `body` (markdown-capable string). Renders via the shared `` component with colour + icon + severity-word label — meets WCAG 1.4.1 (not colour alone). Severities: - `note` (blue) — neutral info the reader might miss - `success` (green) — confirms something positive - `caution` (orange) — be careful; not dangerous - `warning` (red) — will break if ignored items: type: object required: [type, body] properties: type: type: string enum: [note, success, caution, warning] body: type: string description: "Callout body (markdown-capable)." verification: type: string description: "How to verify step completed correctly" troubleshooting: type: string description: | OPTIONAL (v0.8.0+). Per-step troubleshooting note — brief markdown text describing common problems and fixes specific to this step. Distinct from the top-level `troubleshooting[]` array, which captures guide-wide issues. tool_call: type: object description: | OPTIONAL (v0.9.0+, #1546). Declarative description of the REST/MCP/CLI invocation this step performs. Used by the getting-started matrix to advertise concrete next actions without prose parsing. Authoring-only — no executable runner is implied. properties: surface: type: string enum: [ rest, mcp, cli, a2a ] description: "Which surface the step calls." target: type: string description: | Endpoint, tool name, or command. Examples: `POST /possibilities`, `mcp:tool/list_possibilities`, `pspace possibility create`. params: type: object description: "Free-form parameter sketch. Not validated." success_check: type: object description: | OPTIONAL (v0.9.0+, #1546). Declarative success predicate complementing the prose `verification` field. Used by the getting-started matrix; authoring-only. properties: type: type: string enum: [ api-response, file-exists, status-equals, manual ] description: "Predicate type." expression: type: string description: | Free-form expression — a status code, JSON path, file path, etc. Interpretation depends on `type`. troubleshoot: type: array description: | OPTIONAL (v0.9.0+, #1546). XRIs of M37 integration-guide reference sections that explain failures specific to this step. Distinct from the prose `troubleshooting` field. items: type: string pattern: "^kno://" troubleshooting: type: array description: | Guide-wide troubleshooting entries. Canonical item shape uses `{ problem, solution, cause }`. The `{ issue, solution }` shape is accepted as a deprecated alias during v0.8.x — renderer coerces `issue` → `problem` on load. items: type: object properties: problem: type: string description: "Canonical field name for the issue encountered." issue: type: string deprecated: true description: "DEPRECATED alias for `problem` (v0.8.x back-compat)." solution: type: string cause: type: string next_steps: type: array description: | XRI-linked follow-ups. REQUIRED. Every guide must point somewhere. items: type: object required: - title properties: title: type: string link: type: string description: "URL or XRI (preferred)" xri: type: string description: "Identity XRI of the target entity" pattern: "^kno://" description: type: string reason: type: string description: "Why the reader should follow this next step" verification: type: string description: | OPTIONAL top-level success check (complementary to per-step verification). "If X is true, the guide succeeded." skip_manual_setup: type: object description: | OPTIONAL. Describes a one-command CLI invocation or an MCP-aware handoff prompt that short-circuits the manual steps for agentic or bulk-deploy consumers. properties: command: type: string description: "Copy-paste shell command" prompt_template: type: string description: | Text template suitable for 'Copy prompt for AI agent' affordance. Presentation-layer only per DC-1 (v1.20.0); not persisted. description: type: string provenance: type: object description: | REQUIRED per REQ-16 and foundational-principles §0.8. `emerged_from` absent for ab-initio authored guides; populated when synthesized from playbooks or prior corpora. required: - origin properties: origin: type: object required: - id - timestamp properties: id: type: string pattern: "^[0-9A-HJKMNP-TV-Z]{26}$" description: "Authoring-event ULID" timestamp: type: string format: date-time tool: type: string description: "Authoring tool (e.g. 'manual-authoring', 'playbook-synthesis')" emerged_from: type: array description: "XRIs of source entities (absent for axiomatic guides)" items: type: string pattern: "^(kno|pspace)://" # --- INHERITED FROM HISTORY.KNO (Layer 1) --- _history: type: object description: "Version history" # --- INHERITED FROM QUALITY.KNO (Layer 1) --- quality: type: object # --- RELATIONSHIPS --- relationships: type: object description: | REQUIRED. Must include at least one `documents` edge pointing at the capability / spec / API / RFC the guide teaches. Reverse edge (`documented_by`) is computed at render time per P7 "Forward vs Reverse Edge Storage" (v1.20.0) \u2014 NO write-back. properties: documents: type: array description: | REQUIRED. The capability/spec/api/rfc/capability-page XRIs this guide teaches. Bidirectional predicate (P7 v1.20.0). items: type: object required: - xri properties: xri: type: string pattern: "^kno://" reason: type: string related_to: type: array description: "OPTIONAL sibling guides" related_specs: type: array description: "OPTIONAL typed reference predicate" related_api: type: array description: "OPTIONAL typed reference predicate" related_rfcs: type: array description: "OPTIONAL typed reference predicate" examples: type: array description: "OPTIONAL links to runnable sample repos / /examples entries" taxonomy: type: object # =========================================================================== # EXAMPLES # =========================================================================== examples: - title: "Minimal Guide (v0.7.0 convention)" description: "Smallest valid guide with the refined convention" code: | $schema: kno@0.0.9 conforms_to: kno://specs/guide-schema id: 01KM00000000000000000001 # ULID (example) slug: minimal-guide type: guide version: 0.1.0 title: "Minimal Guide" purpose: "Demonstrate the smallest valid guide." domain: fundamentals guide_type: how-to prerequisites: [] outcomes: - "Reader understands the minimal shape of a guide" steps: - title: "Do the thing" description: "Just do it." next_steps: - title: "Read the full guide schema" xri: "kno://specs/guide-schema" provenance: origin: id: 01KM00000000000000000002 timestamp: "2026-04-16T00:00:00Z" tool: manual-authoring relationships: documents: - xri: "kno://specs/kno-spec" reason: "Demonstrates minimal .kno guide shape" quality: completeness: 0.5 last_reviewed: "2026-04-16" review_status: draft reviewed_by: "claude" - title: "Full Guide (v0.8.0 convention — code_samples[])" description: "Guide with all recommended fields and canonical code_samples shape" code: | $schema: kno@0.0.9 conforms_to: kno://specs/guide-schema id: 01KM00000000000000000010 slug: deploy-pspace type: guide version: 1.0.0 title: "Deploying Possibility to Production" purpose: "Ship a Possibility deployment end-to-end." domain: best-practices guide_type: runbook learning_paths: - customize-your-tenant time_estimate: "30-60 minutes" difficulty: intermediate # OPTIONAL hint prerequisites: - item: "Docker installed" required: true link: "https://docs.docker.com/install/" - item: "Azure CLI configured" required: true outcomes: - "Possibility running on production VM" - "HTTPS configured with Caddy" - "Database initialized" steps: - title: "SSH to Production VM" description: "Connect via SSH or the platform VPN helper" code_samples: - language: bash description: "Open a shell on the production VM:" code: "ssh pspaceadmin@prod-vm.example" verification: "You see the bash prompt" - title: "Pull Latest Code" description: "Run from dev container — fetches token from the platform secret store and SSHes into VM" code_samples: - language: bash code: "scripts/pspace-github-clone.sh" warning: "This will overwrite local changes on the VM" - title: "Start Services" description: "Run the startup script" code_samples: - language: bash code: "./scripts/start-pspace.sh" - language: text description: "Expected output (abbreviated):" code: | [OK] postgres healthy [OK] openbao healthy [OK] api healthy verification: "All containers show 'healthy'" troubleshooting: | If a container is marked `unhealthy`, run `docker logs pspace--1 --tail 50` to inspect the startup error before retrying. verification: "`curl https://api.possibility.space/health` returns 200" troubleshooting: - problem: "Container fails to start" cause: "Missing environment variables" solution: "Check .env.bootstrap has all required secrets" next_steps: - title: "Configure custom domain" xri: "kno://guides/dns-setup-cloudflare" reason: "After base deploy, wire your tenant domain" provenance: origin: id: 01KM00000000000000000011 timestamp: "2026-04-16T00:00:00Z" tool: manual-authoring relationships: documents: - xri: "kno://capabilities/platform-deploy" reason: "Teaches the deploy surface" related_rfcs: - xri: "kno://rfcs/020-oauth-agent-auth" quality: completeness: 0.9 last_reviewed: "2026-04-16" review_status: published reviewed_by: "claude" # =========================================================================== # NOTES # =========================================================================== notes: | ## Design Decisions 1. **Steps as Objects**: Steps are objects (not strings) to support rich metadata like code snippets, warnings, and verification. 2. **Guide Types**: Different guide types serve different purposes. Runbooks are checklist-style for operations; tutorials are explanatory for learning. `fundamental`, `overview`, `best-practice` (v0.7.0) allow non-step-heavy formats \u2014 for these, `steps` MAY be omitted and the content lives in `purpose` / `what_youll_build` / narrative prose. 3. **Prerequisites vs Dependencies**: Prerequisites are human-facing ("Docker installed"), while `depends_on` in relationships is for machine-readable entity dependencies. 4. **Verification Steps**: Each step can have a `verification` field so readers know when they've completed the step correctly. A top-level `verification` field captures the overall success check. 5. **Identity Separation (v0.7.0)**: `id` is the ULID birth identity (immutable per RFC-013 / \u00a70.7); `slug` carries the mutable human-readable alias. Canonical routes anchor on `id`; slug-based routes are alias surfaces only. 6. **Forward-only edge storage (v0.7.0)**: `relationships.documents` is the authoritative forward edge. Reverse `documented_by` blocks on targets (spec / API / RFC / capability pages) are computed at render time per foundational-principles \u00a7 "Forward vs Reverse Edge Storage" (v1.20.0). No write-back. 7. **Aggregate Corpus**: The schema declares `produces: [llms-txt-format]` so a thin transformation can materialize `/docs/llms.txt` by reading the guide graph. contains: - xri: "#identity" role: section title: "Schema Metadata" keywords: [ id, type, version ] - xri: "#spec" role: section title: "Guide Schema" keywords: [ steps, prerequisites, verification ] - xri: "#notes" role: section title: "Design Notes" keywords: [ prerequisites, verification ] # ============================================================================= # CONTAINER TIER — Navigation Index # ============================================================================= _index: - path: "identity" line: 18 keywords: [ id, type, version, guide-schema ] - path: "spec/fields" line: 100 keywords: [ title, purpose, prerequisites, steps, outcomes ] - path: "spec/steps" line: 180 keywords: [ step, action, verification, duration, optional ] - path: "spec/examples" line: 300 keywords: [ minimal, full, multi-step ] - path: "notes" line: 380 keywords: [ prerequisites, verification, duration ]