# Relationship Vocabulary Schema
# Formalizes all relationship types used across the .kno ecosystem.
#
# This schema is SEPARATE from kno-spec.kno by design (Option B):
#   - kno-spec defines the FORMAT (how relationships are structured)
#   - This schema defines the VOCABULARY (what relationships mean)
#   - Separation keeps each spec focused on its concern (DC-2)
#
# Three-Gate Test:
#   Gate 1 (Distinctness): Vocabulary semantics ≠ format structure.
#          kno-spec says "relationships is an object with predicate keys";
#          this schema says "depends_on means X, its inverse is Y."
#   Gate 2 (Reusability): Every .kno entity with relationships references
#          this vocabulary. 100+ entity instances use these predicates.
#   Gate 3 (Clarity): A dedicated vocabulary document is clearer than
#          embedding 32 definitions inside the format spec.
#
# The vocabulary is organized in three tiers:
#   Tier 1 — Kernel:    Universal predicates (any entity type)
#   Tier 2 — Container: Predicates for intra-container relationships (P7)
#   Tier 3 — Domain:    Entity-type-specific predicates
#
# User-facing terminology: "relationship vocabulary" (not "predicates")
# per DC-1 triple-audience principle. Technical docs may use "predicate"
# where precision is needed.

$schema: kno@0.0.9

# --- BASIC (kernel) ---
id: 01KJEKJH40WRH3QBPEXCKM6960
slug: relationship-vocabulary-schema
type: spec
version: 0.2.0

# --- STANDARD ---
title: "Relationship Vocabulary Schema"
purpose: |
  Canonical registry of all relationship types in the .kno ecosystem.

  Every `relationships:` block in a .kno entity uses predicate keys
  drawn from this vocabulary. This schema provides:

  - **Semantic definitions** — what each relationship means
  - **Inverse mappings** — bidirectional relationship pairs
  - **Tier classification** — kernel, container, or domain scope
  - **Domain constraints** — which entity types can use each relationship
  - **Usage examples** — concrete .kno snippets showing each relationship

  **Tier model:**

  | Tier      | Scope               | Governed by          | Count |
  |-----------|---------------------|----------------------|-------|
  | Kernel    | Any entity          | kno-spec.kno         | 19    |
  | Container | Intra-container     | Bedrock P7           | 5     |
  | Domain    | Entity-type-specific| Domain schemas       | 9     |

  **Relationship vs predicate:**
  User-facing text uses "relationship" — it's friendlier and already
  established in bedrock documentation. Code and schemas use "predicate"
  where technical precision is needed. Both terms refer to the same concept.

  **Deprecation:**
  The `related` flat-array form is deprecated. Use `related_to` with
  typed objects instead (per P7: relationships carry semantic meaning).

# --- RICH ---
provenance:
  origin:
    id: 01KJEKJH40WRH3QBPEXCKM6960
    timestamp: "2026-02-26T00:00:00Z"
    tool: ai-assisted-authoring

taxonomy:
  topics:
    - ontology
    - relationships
    - vocabulary
    - graph-theory
  keywords:
    - predicate
    - relationship
    - edge
    - vocabulary
    - inverse
    - semantic

relationships:
  depends_on:
    - xri: "pspace://spec:kno-spec"
      reason: "Kernel predicates are defined in the format spec"
  related_to:
    - xri: "pspace://spec:graph-response-schema"
      reason: "Graph edges use predicates from this vocabulary"
  documents:
    - xri: "pspace://spec:kno-spec"
      reason: "Formalizes the predicate vocabulary referenced by kno-spec"

quality:
  completeness: 0.85
  last_reviewed: "2026-02-26"
  review_status: draft

# --- HISTORY ---
_history:
  version: 2
  created: "2026-02-26"
  created_by: "claude"
  modified: "2026-04-26"
  modified_by: "phase-3-partner-unblocking"

# --- SPECIFICATION ---
spec:
  status: Draft
  changelog:
    - version: "0.2.0"
      date: "2026-04-26"
      changes:
        - "Added kernel predicate pair `applies_to` ↔ `affected_by` for the
          `notice` entity (M52 Phase 3.1.6 / #2052). Mirrors the `documents` ↔
          `documented_by` precedent. CI lint (`lint-api-contract-honesty.ts`)
          enforces bidirectional backlink consistency."
        - "Bumped kernel count 17 → 19 in tier table."
    - version: "0.1.0"
      date: "2026-02-26"
      changes:
        - "Initial relationship vocabulary — Phase 0, Milestone 14"
        - "32 relationships across 3 tiers + 1 deprecated"
        - "Full inverse mappings and semantic definitions"
        - "Source reconciliation across 5 codebase locations"

  # ════════════════════════════════════════════════════════════════
  # VOCABULARY DEFINITION
  # ════════════════════════════════════════════════════════════════
  #
  # Each relationship entry has:
  #   name        — snake_case identifier used in relationships: blocks
  #   tier        — kernel | container | domain
  #   meaning     — what this relationship semantically expresses
  #   inverse     — the reverse relationship (null if self-inverse or none)
  #   constraints — which entity types can use this (null = unrestricted)
  #   example     — concrete .kno snippet
  #   sources     — where this predicate is currently defined/used in code
  #   notes       — additional context, caveats, or evolution notes

  vocabulary:
    # ──────────────────────────────────────────────────────────────
    # TIER 1: KERNEL RELATIONSHIPS (universal — any entity type)
    # Defined in kno-spec.kno. Used across all tiers and contexts.
    # ──────────────────────────────────────────────────────────────

    - name: depends_on
      tier: kernel
      meaning: |
        Prerequisites — the source entity requires the target entity
        to function correctly. Reading/understanding the target is
        necessary before the source makes sense.
      inverse: null
      constraints: null
      sources:
        [
          kno-spec,
          kno.ts,
          synthesis-types,
          kaml-renderer,
          PlaybookPreview,
          validate-kno,
        ]
      example: |
        relationships:
          depends_on:
            - xri: "pspace://spec:identity-schema"
              reason: "Requires identity tier for user resolution"

    - name: related_to
      tier: kernel
      meaning: |
        See also — the source and target are thematically connected
        but neither depends on the other. The weakest formal relationship;
        use a more specific predicate when one fits.
      inverse: related_to
      constraints: null
      sources: [ kno-spec, kno.ts, kaml-renderer, validate-kno ]
      example: |
        relationships:
          related_to:
            - xri: "pspace://spec:document-schema"
              reason: "Documents are a foundational entity type"

    - name: supersedes
      tier: kernel
      meaning: |
        Replaces — the source entity is the successor of the target.
        The target is obsolete and should not be used for new work.
        Consumers should migrate to the source entity.
      inverse: null
      constraints: null
      sources: [ kno-spec, kno.ts, synthesis-types, PlaybookPreview, validate-kno ]
      example: |
        relationships:
          supersedes:
            - xri: "pspace://rfc:rfc-001-v1"
              reason: "RFC-001 v2 replaces v1 with expanded scope"

    - name: amends
      tier: kernel
      meaning: |
        Refines or extends — the source modifies the target without
        fully replacing it. The target remains valid but is now
        qualified by the source's additions.
      inverse: null
      constraints: null
      sources: [ kno-spec, validate-kno ]
      example: |
        relationships:
          amends:
            - xri: "pspace://rfc:rfc-001"
              reason: "Adds section on container architecture"

    - name: enables
      tier: kernel
      meaning: |
        Makes possible — the source entity unlocks capabilities or
        makes the target entity feasible. Directional: A enables B
        means A is a prerequisite for B's capability.
      inverse: null
      constraints: null
      sources:
        [
          kno-spec,
          kno.ts,
          synthesis-types,
          kaml-renderer,
          PlaybookPreview,
          validate-kno,
        ]
      example: |
        relationships:
          enables:
            - xri: "#entries/tbd-resolution-workflow"
              reason: "Explicitness guides how TBDs are surfaced"

    - name: part_of
      tier: kernel
      meaning: |
        Parent — the source entity belongs to the target as a member
        or component. Expresses containment or membership without
        implying the full container architecture (_contains).
      inverse: null
      constraints: null
      sources: [ kno-spec, kno.ts, validate-kno ]
      example: |
        relationships:
          part_of:
            - xri: "pspace://playbook/engineering-playbook"
              reason: "This principle is part of the engineering playbook"

    - name: conforms_to
      tier: kernel
      meaning: |
        Schema conformance — the source entity declares that it
        follows the structure defined by the target schema.
        Primary mechanism for schema-driven validation (P5).
      inverse: null
      constraints: null
      sources: [ kno-spec, kno.ts, kaml-renderer, validate-kno ]
      example: |
        relationships:
          conforms_to:
            - xri: "pspace://spec:role-schema"
              reason: "This role entity conforms to role@0.1"

    - name: extends
      tier: kernel
      meaning: |
        Builds upon — the source entity extends the target by adding
        fields, capabilities, or scope. The target's structure is
        a subset of the source's. Common in schema hierarchies.
      inverse: null
      constraints: null
      sources: [ kno-spec, kno.ts, synthesis-types, PlaybookPreview, validate-kno ]
      example: |
        relationships:
          extends:
            - xri: "pspace://spec:document-schema"
              reason: "Playbook extends document with _contains"

    - name: composes
      tier: kernel
      meaning: |
        Composed of — the source entity is built from multiple
        target entities. Unlike part_of (child→parent), composes
        is parent→child: "A composes B, C, D."
      inverse: part_of
      constraints: null
      sources: [ kno.ts, validate-kno ]
      notes: |
        Present in code but not yet listed in kno-spec.kno predicates
        table. Should be added in next kno-spec minor version.
      example: |
        relationships:
          composes:
            - xri: "pspace://spec:identity-schema"
              reason: "User schema composes identity tier fields"

    - name: implements
      tier: kernel
      meaning: |
        Realizes — the source entity provides a concrete implementation
        of the target. The target is abstract (principle, interface,
        spec); the source is concrete (procedure, adapter, code).
      inverse: null
      constraints: null
      sources: [ kno.ts, synthesis-types, PlaybookPreview, validate-kno ]
      notes: |
        Present in code but not yet listed in kno-spec.kno predicates
        table. Should be added in next kno-spec minor version.
      example: |
        relationships:
          implements:
            - xri: "#entries/dry-principle"
              reason: "Extract Method procedure implements the DRY principle"

    - name: instance_of
      tier: kernel
      meaning: |
        Schema instantiation — semantic alias for conforms_to.
        Preferred when emphasizing the type relationship:
        "this user IS AN instance_of user-schema."
      inverse: null
      constraints: null
      sources: [ kno-spec, validate-kno ]
      example: |
        relationships:
          instance_of:
            - xri: "pspace://spec:user-schema"
              reason: "This entity is a user instance"

    - name: format
      tier: kernel
      meaning: |
        Format specification — declares what format specification
        governs the source entity's content. Distinct from conforms_to
        (which is about schema/type) — format is about serialization.
      inverse: null
      constraints: null
      sources: [ kno-spec, kaml-renderer, validate-kno ]
      example: |
        relationships:
          format:
            - xri: "pspace://spec:markdown-format"
              reason: "Content sections use Markdown formatting"

    - name: documents
      tier: kernel
      meaning: |
        Documentation — the source entity documents or explains the
        target entity. The source provides context, reference, or
        explanation for understanding the target.
      inverse: documented_by
      constraints: null
      sources: [ kno-spec, kaml-renderer, validate-kno ]
      example: |
        relationships:
          documents:
            - xri: "pspace://spec:kno-spec"
              reason: "This guide documents the .kno format"

    - name: documented_by
      tier: kernel
      meaning: |
        Inverse of documents — the source entity is documented or
        explained by the target entity.
      inverse: documents
      constraints: null
      sources: [ kno-spec, kaml-renderer, validate-kno ]
      example: |
        relationships:
          documented_by:
            - xri: "pspace://guide/kno-getting-started"
              reason: "Getting started guide explains this schema"

    - name: applies_to
      tier: kernel
      meaning: |
        Scope — the source entity applies to, targets, or governs the
        target entity. Used by notice entities to declare which
        endpoints, capabilities, possibilities, or platform anchors
        a notice scopes; by capability entities to declare the
        possibilities they install into; and by any future entity
        whose meaning is "this thing pertains to that thing."

        Per P10 (Derivable Structure), the SCOPE of an entity (e.g.,
        platform-wide vs. endpoint-scoped vs. possibility-scoped) is
        emergent from its `applies_to` targets — it is NOT a
        declarative subtype field on the source entity.

        Per P7 (Cooperative / Codependent), every `applies_to` link
        MUST have a reverse `affected_by` link from the target back
        to the source. CI lint (`lint-api-contract-honesty.ts`)
        enforces this bidirectional consistency.
      inverse: affected_by
      constraints: null
      sources: [ notice-schema, lint-api-contract-honesty, kno-spec ]
      notes: |
        Introduced by M52 Phase 3.1.6 (#2052) for the `notice` entity.
        Mirrors the `documents` ↔ `documented_by` precedent.

        Well-known XRI targets:
          - `pspace://platform` — Platform-wide scope (reserved-XRI
            registry anchor)
          - `pspace://api-endpoint/<slug>` — Endpoint-scoped
          - `pspace://capability/<slug>` — Capability-scoped
          - `pspace://possibility/<id>` — Possibility-scoped
      example: |
        relationships:
          applies_to:
            - xri: "pspace://api-endpoint/oauth-authorize"
              reason: "Notice signals 409 precondition on this endpoint"

    - name: affected_by
      tier: kernel
      meaning: |
        Inverse of applies_to — the source entity is the target of,
        affected by, or scoped by the target entity. An API endpoint
        declares `affected_by` links pointing back at the notices that
        scope it; a possibility declares `affected_by` links pointing
        back at the notices targeting it.

        Required by P7 (Cooperative / Codependent) to keep the
        relationship graph navigable in both directions; absence of a
        reverse `affected_by` link from a target named in `applies_to`
        is a lint failure.
      inverse: applies_to
      constraints: null
      sources: [ notice-schema, lint-api-contract-honesty, kno-spec ]
      notes: |
        Backlinks may be authored manually OR materialized by a thin
        transformation that walks all `notice` entities and projects
        their `applies_to` edges back onto target entities. The
        transformation is preferred for endpoint and platform anchors
        (frequently updated reference data).
      example: |
        relationships:
          affected_by:
            - xri: "pspace://notice/2026-04-25-custom-auth-domain-required"
              reason: "Endpoint returns 409 when no custom auth domain
                is configured for the requesting OIDC client"

    - name: inferred_from
      tier: kernel
      meaning: |
        Source material — the source entity's structure was derived
        from the target (typically unstructured content). Used for
        schema-less conversions where structure is created rather
        than transformed.
      inverse: null
      constraints: null
      sources: [ kno-spec, kaml-renderer, validate-kno ]
      notes: |
        Supports schema_affinity to document WHY inference was attempted.
        For text: source=embedded with location pointing to content field.
        For binary: source=external with CID for content-addressed reference.
      example: |
        relationships:
          inferred_from:
            - xri: "pspace://document/raw-transcript-2025"
              reason: "Playbook structure inferred from transcript analysis"

    - name: produces
      tier: kernel
      meaning: |
        Output — the source entity produces or generates the target
        as output. Used for pipeline relationships where one entity's
        processing creates another.
      inverse: produced_by
      constraints: null
      sources: [ validate-kno ]
      notes: |
        Present in validate-kno.ts but not in kno-spec.kno predicates
        table. Should be added in next kno-spec minor version.
      example: |
        relationships:
          produces:
            - xri: "pspace://playbook/extracted-playbook"
              reason: "Import pipeline produces a playbook from raw sources"

    - name: produced_by
      tier: kernel
      meaning: |
        Inverse of produces — the source entity was produced or
        generated by the target entity or process.
      inverse: produces
      constraints: null
      sources: [ kaml-renderer, validate-kno ]
      example: |
        relationships:
          produced_by:
            - xri: "pspace://workflow/import-pipeline"
              reason: "This playbook was produced by the import pipeline"

    # ──────────────────────────────────────────────────────────────
    # TIER 2: CONTAINER RELATIONSHIPS (intra-container — P7)
    # Defined in bedrock P7 (kno-foundational-principles.md).
    # Used within _contains blocks with fragment XRI (#entries/slug).
    # Also valid at top-level between containers.
    # ──────────────────────────────────────────────────────────────

    - name: supports
      tier: container
      meaning: |
        Reinforces — the source entity provides evidence, backing,
        or reinforcement for the target. Weaker than enables:
        A supports B means A strengthens B's case, but B can
        exist without A.
      inverse: null
      constraints: null
      sources: [ synthesis-types, PlaybookPreview ]
      notes: |
        Common in playbook containers where patterns support principles.
        May be promoted to kernel tier if usage extends beyond containers.
      example: |
        relationships:
          supports:
            - xri: "#entries/code-review-pattern"
              reason: "Code review pattern supports quality principles"

    - name: contradicts
      tier: container
      meaning: |
        In tension with — the source entity conflicts with or is
        in opposition to the target. Does not mean "invalid" — both
        entities may be correct in different contexts. Surfaces
        productive tensions within a knowledge graph.
      inverse: contradicts
      constraints: null
      sources: [ synthesis-types, PlaybookPreview ]
      example: |
        relationships:
          contradicts:
            - xri: "#entries/move-fast-principle"
              reason: "Thoroughness principle is in tension with speed"

    - name: specializes
      tier: container
      meaning: |
        Narrows scope — the source entity is a more specific version
        of the target. The target is general; the source applies to
        a particular context or domain.
      inverse: null
      constraints: null
      sources: [ synthesis-types, PlaybookPreview ]
      example: |
        relationships:
          specializes:
            - xri: "#entries/testing-principle"
              reason: "Unit testing specializes the general testing principle"

    - name: exemplifies
      tier: container
      meaning: |
        Concrete instance of — the source entity is a concrete
        example or manifestation of the target (which is abstract).
        The source demonstrates the target in practice.
      inverse: exemplified_by
      constraints: null
      sources: [ synthesis-types, PlaybookPreview ]
      example: |
        relationships:
          exemplifies:
            - xri: "#entries/dry-principle"
              reason: "Extract Method pattern exemplifies the DRY principle"

    - name: exemplified_by
      tier: container
      meaning: |
        Has concrete instances — inverse of exemplifies. The source
        entity (abstract) is demonstrated by the target (concrete).
      inverse: exemplifies
      constraints: null
      sources: [ synthesis-types, PlaybookPreview ]
      example: |
        relationships:
          exemplified_by:
            - xri: "#entries/extract-method-pattern"
              reason: "DRY principle is exemplified by Extract Method"

    # ──────────────────────────────────────────────────────────────
    # TIER 3: DOMAIN RELATIONSHIPS (entity-type-specific)
    # Defined by domain schemas. These predicates have clear semantics
    # but apply only to specific entity types or domains.
    # ──────────────────────────────────────────────────────────────

    - name: styled_by
      tier: domain
      meaning: |
        Visual styling source — the source entity's visual rendering
        is governed by the target (typically a style template or
        style guide entity).
      inverse: null
      constraints:
        source_types: [ diagram, page, document ]
        target_types: [ style-guide, style-template ]
      sources: [ validate-kno ]
      example: |
        relationships:
          styled_by:
            - xri: "pspace://spec:d2-forks-style-template"
              reason: "Diagram uses the Forks style template"

    - name: has_member
      tier: domain
      meaning: |
        Membership — the source entity (typically an organization)
        contains the target as a member. Expresses organizational
        or group membership.
      inverse: member_of
      constraints:
        source_types: [ organization ]
        target_types: [ user ]
      sources: [ validate-kno ]
      example: |
        relationships:
          has_member:
            - xri: "pspace://user/01HXYZ..."
              reason: "User is a member of this organization"

    - name: member_of
      tier: domain
      meaning: |
        Inverse of has_member — the source entity (typically a user)
        is a member of the target organization.
      inverse: has_member
      constraints:
        source_types: [ user ]
        target_types: [ organization ]
      sources: [ validate-kno ]
      example: |
        relationships:
          member_of:
            - xri: "pspace://organization/acme-corp"
              reason: "This user is a member of Acme Corp"

    - name: owns
      tier: domain
      meaning: |
        Ownership — the source entity has ownership over the target.
        Typically used for organization → possibility relationships
        where the org has governance authority.
      inverse: owned_by
      constraints:
        source_types: [ organization, user ]
        target_types: [ possibility ]
      sources: [ validate-kno ]
      example: |
        relationships:
          owns:
            - xri: "pspace://possibility/my-venture"
              reason: "Organization owns this possibility"

    - name: owned_by
      tier: domain
      meaning: |
        Inverse of owns — the source entity is owned by the target.
      inverse: owns
      constraints:
        source_types: [ possibility ]
        target_types: [ organization, user ]
      sources: [ validate-kno ]
      example: |
        relationships:
          owned_by:
            - xri: "pspace://organization/acme-corp"
              reason: "This possibility is owned by Acme Corp"

    - name: founder_of
      tier: domain
      meaning: |
        Founding — the source entity (user) created or founded the
        target entity (organization or possibility). Historical
        relationship: founder status persists even if the founder
        is no longer involved.
      inverse: founded_by
      constraints:
        source_types: [ user ]
        target_types: [ organization, possibility ]
      sources: [ validate-kno ]
      example: |
        relationships:
          founder_of:
            - xri: "pspace://organization/acme-corp"
              reason: "User founded this organization in 2024"

    - name: founded_by
      tier: domain
      meaning: |
        Inverse of founder_of — the source entity was founded or
        created by the target user.
      inverse: founder_of
      constraints:
        source_types: [ organization, possibility ]
        target_types: [ user ]
      sources: [ validate-kno ]
      example: |
        relationships:
          founded_by:
            - xri: "pspace://user/01HXYZ..."
              reason: "Acme Corp was founded by this user"

    - name: illustrates
      tier: domain
      meaning: |
        Visual representation — the source entity (typically a diagram)
        provides a visual illustration of the target concept or entity.
      inverse: illustrated_by
      constraints:
        source_types: [ diagram ]
        target_types: null
      sources: [ validate-kno ]
      example: |
        relationships:
          illustrates:
            - xri: "pspace://spec:kno-spec"
              reason: "This diagram illustrates the .kno tier model"

    - name: illustrated_by
      tier: domain
      meaning: |
        Inverse of illustrates — the source entity has a visual
        representation provided by the target diagram.
      inverse: illustrates
      constraints:
        source_types: null
        target_types: [ diagram ]
      sources: [ validate-kno ]
      example: |
        relationships:
          illustrated_by:
            - xri: "pspace://diagram/tier-model"
              reason: "Tier model is illustrated by this diagram"

    # ──────────────────────────────────────────────────────────────
    # DEPRECATED
    # ──────────────────────────────────────────────────────────────

    - name: related
      tier: deprecated
      meaning: |
        DEPRECATED — flat array of related entity slugs. Violates P7
        (relationships must carry semantic meaning via typed predicates).
        Retained for backward compatibility in PlaybookPreview.
      inverse: null
      constraints: null
      sources: [ PlaybookPreview ]
      migration: |
        Replace with `related_to` using typed objects:

        # Before (deprecated):
        related: ["other-entity-slug"]

        # After (correct):
        relationships:
          related_to:
            - xri: "#entries/other-entity-slug"
              reason: "Explain why this relationship exists"
      notes: |
        PlaybookPreview computes `related` arrays from `relationships`
        blocks for legacy consumers. The `related` array is never
        the source of truth — it is derived from typed relationships.

  # ════════════════════════════════════════════════════════════════
  # INVERSE MAPPING (quick reference)
  # ════════════════════════════════════════════════════════════════

  inverse_pairs:
    - [ documents, documented_by ]
    - [ applies_to, affected_by ]
    - [ produces, produced_by ]
    - [ exemplifies, exemplified_by ]
    - [ illustrates, illustrated_by ]
    - [ has_member, member_of ]
    - [ owns, owned_by ]
    - [ founder_of, founded_by ]
    - [ composes, part_of ]
    - [ contradicts, contradicts ]
    - [ related_to, related_to ]

  # ════════════════════════════════════════════════════════════════
  # SOURCE RECONCILIATION
  # ════════════════════════════════════════════════════════════════
  #
  # This section documents which codebase locations define each
  # predicate and whether there are gaps or inconsistencies.
  #
  # Canonical source hierarchy (highest authority first):
  #   1. kno-spec.kno — kernel specification (13 listed)
  #   2. bedrock P7 — container vocabulary (8 listed)
  #   3. validate-kno.ts — validation (26 = 17 kernel + 9 domain)
  #   4. kno.ts — API route helpers (9 predicates)
  #   5. synthesis-types.ts — S3 pipeline (10 predicates)
  #   6. kaml-renderer.ts — KAML rendering (9 predicates)
  #   7. PlaybookPreview.astro — client visualization (11 predicates)
  #
  # Known gaps to address:
  #   - kno-spec.kno is missing: composes, implements, produces
  #     (present in code, should be added in kno-spec minor bump)
  #   - kno.ts is missing 8 kernel predicates (instance_of, format,
  #     documents, documented_by, inferred_from, produces, produced_by,
  #     amends) — should be updated when kno route is refactored
  #   - Container tier (supports, contradicts, specializes, exemplifies,
  #     exemplified_by) not in kno-spec.kno predicates table — by design,
  #     since they are P7 container vocabulary, not format-level

  source_locations:
    kno_spec: "specs/kno-spec.kno L696-L726"
    kno_ts: "services/pspace-api/src/routes/kno.ts L119-129"
    synthesis_types: "services/pspace-api/src/lib/synthesis-types.ts L478-530"
    kaml_renderer: "services/pspace-api/src/lib/kno/kaml-renderer.ts L38-57"
    playbook_preview: "services/pspace-site/src/components/previews/PlaybookPreview\
      .astro L678-690"
    validate_kno: "scripts/validate-kno.ts L161-197"

# --- EXAMPLES ---
examples:
  - title: "Entity with kernel relationships"
    description: |
      A document schema using kernel-tier predicates.
    content: |
      relationships:
        extends:
          - xri: "pspace://spec:kno-spec"
            reason: "Document extends the kernel format"
        depends_on:
          - xri: "pspace://spec:identity-schema"
            reason: "Requires identity tier for authorship"
        related_to:
          - xri: "pspace://spec:page-schema"
            reason: "Pages are a related content type"

  - title: "Container entries with P7 relationships"
    description: |
      Playbook entries using container-tier predicates with fragment XRI.
    content: |
      _contains:
        entries:
          dry-principle:
            relationships:
              enables:
                - xri: "#entries/extract-method"
                  reason: "DRY motivates Extract Method"
              exemplified_by:
                - xri: "#entries/shared-util-pattern"
                  reason: "Shared utilities exemplify DRY"
              contradicts:
                - xri: "#entries/premature-abstraction"
                  reason: "Over-abstracting can harm DRY's intent"

  - title: "Organization with domain relationships"
    description: |
      An organization entity using domain-tier predicates.
    content: |
      relationships:
        has_member:
          - xri: "pspace://user/01HXYZ..."
            reason: "Founding team member"
        owns:
          - xri: "pspace://possibility/venture-alpha"
            reason: "Organization's primary venture"
        founded_by:
          - xri: "pspace://user/01HABC..."
            reason: "Founded by this user in 2024"