# Knowledge Base Domain Schema — Layer 3 Specialized Entity Type
# KNO Schema Version: 0.1.0
# CHANGELOG:
#   0.1.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18.
#
# A knowledge base is a structured collection of interconnected knowledge
# articles, similar to a wiki. It represents complex, multi-article content
# like RFCs, specifications, or imported wiki repositories.
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
# USE CASES:
# - Imported GitHub wikis (from corpus sources)
# - RFC collections (KNO, KAML specifications)
# - Technical documentation sets
# - Organizational knowledge repositories

# =============================================================================
# SCHEMA DECLARATION (RFC-007)
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# IDENTITY (composed from identity-schema.kno)
# =============================================================================
id: 01KGK3V73FKJSETZC5PHB0368Q
slug: knowledge-base-schema
type: spec
version: 0.3.0

# =============================================================================
# VISIBILITY DECLARATION (REQ-18) — collection default
# =============================================================================
# Knowledge-base entities (content/knowledge-base/*.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
# =============================================================================
title: "Knowledge Base Domain Schema"
purpose: |
  Define the schema for Knowledge Base entities — structured wiki-like
  collections of interconnected knowledge articles.

  **What is a Knowledge Base?**
  A knowledge base is a collection of articles that:
  - Cover a coherent domain or topic area
  - Link to each other via cross-references
  - Have a navigable structure (table of contents, sections)
  - May be authored by humans or generated from analysis

  **Key Use Cases:**

  | Source | Example | Notes |
  |--------|---------|-------|
  | GitHub Wiki | howl-app/howl.wiki | Imported during corpus transfer |
  | RFC Collection | KNO Format Spec | Multi-section specification |
  | Documentation | API Reference | Structured technical docs |
  | Generated | Playbook Dimension Output | Analysis results as wiki |

  **Layer 3 Position**: Knowledge Base extends document (Layer 2), which
  composes identity, history, and quality (Layer 1).

  **UX Inspiration:**

  | Product | Key Pattern | Possibility Adaptation |
  |---------|-------------|----------------|
  | **Obsidian** | Graph view, links, local-first | Graph visualization of article relationships |
  | **Nuclino** | List/Board/Graph views, instant search | Multiple view modes, fast filtering |
  | Both | Clean, minimal, fast | No clutter, focus on content |

  **View Modes (inspired by Nuclino):**
  - **List View** — Table of contents with hierarchical nesting
  - **Graph View** — Visual map of article connections (like Obsidian)
  - **Search View** — Instant search with filtering by tags/type

  **Relationship to Corpus**: A corpus may contain knowledge bases (wikis).
  Knowledge bases are the structured representation of wiki content.

# =============================================================================
# RICH TIER — Relationships (Edge Maximization)
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73FKJSETZC5PHB0368Q
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - knowledge-management
    - wiki
    - documentation
    - specification
  keywords:
    - knowledge-base
    - wiki
    - article
    - documentation
    - rfc
    - specification
    - cross-reference

relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type for structured entities"

  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://concepts/knowledge-navigation"
      reason: "Browse articles via table of contents"
    - xri: "kno://concepts/cross-referencing"
      reason: "Articles link to each other"
    - xri: "kno://concepts/search"
      reason: "Full-text search across articles"

  related_to:
    - xri: "kno://specs/corpus-schema"
      reason: "Corpora may contain knowledge bases (wikis)"
    - xri: "kno://specs/playbook-schema"
      reason: "Playbooks may reference knowledge bases"
    - xri: "kno://specs/user-schema"
      reason: "Users own knowledge bases"

quality:
  completeness: 0.85
  last_reviewed: "2026-01-25"
  review_status: draft

# =============================================================================
# HISTORY (P9 Temporal — composed from history-schema.kno)
# =============================================================================
_history:
  version: 1
  created: "2026-01-25T00:00:00Z"
  created_by: "pspace-core-team"
  modified: "2026-01-25T12:00:00Z"
  modified_by: "claude"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Draft

  changelog:
    - version: "0.2.0"
      date: "2026-03-03"
      changes:
        - "Added required subtype enum field (architecture-doc, workflow, integration-guide, policy)"
        - "Supports RFC-to-KB reclassification workflow (Milestone 19, Phase 1)"
    - version: "0.1.0"
      date: "2026-01-25"
      changes:
        - "Initial creation as Layer 3 domain schema"
        - "Designed for wiki imports and RFC collections"
        - "Aligned with bedrock principles (no facets, edge inference)"
        - "Added article structure with sections and cross-references"

  description: |
    ## Knowledge Base Structure

    A knowledge base consists of:

    ```
    ┌─────────────────────────────────────────────────────────────────────────┐
    │                     KNOWLEDGE BASE STRUCTURE                            │
    ├─────────────────────────────────────────────────────────────────────────┤
    │                                                                         │
    │   Knowledge Base                                                        │
    │   ├─ Metadata (title, description, domain)                              │
    │   ├─ Table of Contents (hierarchical navigation)                        │
    │   │   ├─ Section: Getting Started                                       │
    │   │   │   ├─ Article: Installation                                      │
    │   │   │   └─ Article: Quick Start                                       │
    │   │   └─ Section: Reference                                             │
    │   │       ├─ Article: API Overview                                      │
    │   │       └─ Article: Configuration                                     │
    │   └─ Articles[] (the actual content)                                    │
    │       ├─ Article 1: { id, title, content, related_articles }            │
    │       ├─ Article 2: { id, title, content, related_articles }            │
    │       └─ ...                                                            │
    │                                                                         │
    └─────────────────────────────────────────────────────────────────────────┘
    ```

    ## Import from GitHub Wiki

    When a corpus includes `include_wiki: true`, the wiki repository is
    cloned and its pages become articles in a knowledge base:

    | Wiki File | Article ID | Notes |
    |-----------|------------|-------|
    | `Home.md` | `home` | Entry point, often becomes index |
    | `Getting-Started.md` | `getting-started` | Kebab-case from filename |
    | `API/Overview.md` | `api-overview` | Subdirs become prefixes |
    | `_Sidebar.md` | (toc source) | Used to build table of contents |
    | `_Footer.md` | (metadata) | Common footer, extracted as metadata |

    ## Article Types

    | Type | Description | Example |
    |------|-------------|---------|
    | `index` | Entry point / home page | Home.md, README.md |
    | `guide` | Step-by-step instructions | Getting-Started.md |
    | `reference` | Lookup information | API-Reference.md |
    | `concept` | Explanatory content | Architecture.md |
    | `tutorial` | Learning-oriented | Tutorial-Build-App.md |
    | `faq` | Questions and answers | FAQ.md |
    | `changelog` | Version history | Changelog.md, RELEASES.md |

  # ===========================================================================
  # SCHEMA
  # ===========================================================================
  schema:
    type: object
    required:
      - id
      - type
      - version
      - name
      - articles
    properties:
      # -----------------------------------------------------------------------
      # BASIC TIER (from kno-spec)
      # -----------------------------------------------------------------------
      id:
        type: string
        pattern: "^kb_[a-zA-Z0-9]+$"
        description: |
          Unique identifier for this knowledge base.
          Convention: kb_{ulid}
        examples:
          - "kb_01HXYZ123"
          - "kb_01KNORFC"

      type:
        const: knowledge-base
        description: "Always 'knowledge-base' for this schema"

      version:
        type: string
        pattern: "^\\d+\\.\\d+\\.\\d+$"
        description: "Version of this knowledge base entity"
        default: "0.1.0"

      # -----------------------------------------------------------------------
      # STANDARD TIER
      # -----------------------------------------------------------------------
      subtype:
        type: string
        description: |
          Classification subtype for this knowledge base.
          Follows the established subtype pattern used by knowledge-source,
          role, and config schemas.
        enum:
          - architecture-doc
          - workflow
          - integration-guide
          - policy
        examples:
          - "architecture-doc"
          - "workflow"
          - "integration-guide"
          - "policy"

      name:
        type: string
        pattern: "^[a-z][a-z0-9-]*$"
        description: "Lowercase, hyphenated name for this knowledge base"
        examples:
          - "howl-wiki"
          - "kno-specification"
          - "pongogo-knowledge"

      title:
        type: string
        description: "Human-readable title"
        examples:
          - "Howl Application Wiki"
          - "KNO Format Specification"

      description:
        type: string
        description: "What this knowledge base contains and its purpose"

      domain:
        type: string
        description: "Primary domain or topic area"
        examples:
          - "mobile-development"
          - "knowledge-management"
          - "specification"

      # -----------------------------------------------------------------------
      # SOURCE PROVENANCE
      # -----------------------------------------------------------------------
      source:
        type: object
        description: "Where this knowledge base came from"
        properties:
          type:
            type: string
            description: "Source type"
            examples:
              - "github-wiki"
              - "authored"
              - "generated"
              - "imported"
          repo:
            type: string
            description: "Source repository (for GitHub wikis)"
            examples:
              - "howl-app/howl.wiki"
          commit:
            type: string
            description: "Commit SHA at import time"
          corpus_id:
            type: string
            description: "Corpus this was imported from (if applicable)"
          imported_at:
            type: string
            format: date-time
            description: "When this was imported"

      # -----------------------------------------------------------------------
      # TABLE OF CONTENTS
      # -----------------------------------------------------------------------
      toc:
        type: array
        description: "Hierarchical table of contents for navigation"
        items:
          type: object
          required:
            - id
            - title
          properties:
            id:
              type: string
              description: "Section or article ID"
            title:
              type: string
              description: "Display title"
            children:
              type: array
              description: "Nested items (for sections)"
              items:
                type: object
                properties:
                  id:
                    type: string
                  title:
                    type: string

      # -----------------------------------------------------------------------
      # ARTICLES (The Content)
      # -----------------------------------------------------------------------
      articles:
        type: array
        description: "The knowledge articles in this base"
        items:
          type: object
          required:
            - id
            - title
            - content
          properties:
            id:
              type: string
              pattern: "^[a-z][a-z0-9-]*$"
              description: "Article identifier (kebab-case)"
              examples:
                - "getting-started"
                - "api-overview"
            title:
              type: string
              description: "Article title"
            article_type:
              type: string
              description: "Type of article"
              examples:
                - "index"
                - "guide"
                - "reference"
                - "concept"
                - "tutorial"
                - "faq"
            content:
              type: string
              description: "Article content (markdown)"
            summary:
              type: string
              description: "Brief summary (1-2 sentences)"
            source_file:
              type: string
              description: "Original file path (for imports)"
            related_articles:
              type: array
              items:
                type: string
              description: "IDs of related articles in this knowledge base"
            external_links:
              type: array
              items:
                type: object
                properties:
                  url:
                    type: string
                  title:
                    type: string
              description: "Links to external resources"
            tags:
              type: array
              items:
                type: string
              description: "Article tags for filtering"
            last_modified:
              type: string
              format: date-time
              description: "When this article was last modified"

      # -----------------------------------------------------------------------
      # METADATA
      # -----------------------------------------------------------------------
      stats:
        type: object
        description: "Statistics about this knowledge base"
        properties:
          article_count:
            type: integer
            description: "Total number of articles"
          total_words:
            type: integer
            description: "Approximate word count across all articles"
          section_count:
            type: integer
            description: "Number of top-level sections in TOC"
          internal_links:
            type: integer
            description: "Number of cross-references between articles"
          external_links:
            type: integer
            description: "Number of links to external resources"

      owner_id:
        type: string
        description: "User ID who owns this knowledge base"

      visibility:
        type: string
        description: "Access control"
        examples:
          - "private"
          - "organization"
          - "public"

      tags:
        type: array
        items:
          type: string
        description: "Knowledge base-level tags"

# =============================================================================
# EXAMPLES
# =============================================================================
examples:
  - name: "Minimal Knowledge Base"
    description: "Simplest valid knowledge base"
    value:
      $schema: "kno://specs/knowledge-base-schema@0.1"
      id: "kb_01MINIMAL"
      type: "knowledge-base"
      version: "0.1.0"
      name: "example-kb"
      title: "Example Knowledge Base"
      articles:
        - id: "home"
          title: "Home"
          content: |
            # Welcome

            This is the home page of the knowledge base.

  - name: "GitHub Wiki Import"
    description: "Knowledge base imported from GitHub wiki"
    value:
      $schema: "kno://specs/knowledge-base-schema@0.1"
      id: "kb_01HOWLWIKI"
      type: "knowledge-base"
      version: "0.1.0"
      name: "howl-wiki"
      title: "Howl Application Wiki"
      description: |
        Documentation wiki for the Howl mobile application,
        imported from the howl-app/howl.wiki repository.
      domain: "mobile-development"
      source:
        type: "github-wiki"
        repo: "howl-app/howl.wiki"
        commit: "80e7c4aa42cdad7ef03a4c04ce0619dd7e62161c" # pragma: allowlist secret
        corpus_id: "corpus_01HOWL456"
        imported_at: "2026-01-25T10:00:00Z"
      toc:
        - id: "home"
          title: "Home"
        - id: "getting-started"
          title: "Getting Started"
          children:
            - id: "installation"
              title: "Installation"
            - id: "quick-start"
              title: "Quick Start"
        - id: "architecture"
          title: "Architecture"
          children:
            - id: "overview"
              title: "Overview"
            - id: "data-model"
              title: "Data Model"
      articles:
        - id: "home"
          title: "Home"
          article_type: "index"
          content: |
            # Howl Wiki

            Welcome to the Howl application documentation.

            ## Quick Links
            - [Getting Started](getting-started)
            - [Architecture](architecture)
          summary: "Entry point for the Howl wiki"
          source_file: "Home.md"
          related_articles:
            - "getting-started"
            - "architecture"
        - id: "getting-started"
          title: "Getting Started"
          article_type: "guide"
          content: |
            # Getting Started with Howl

            This guide walks you through setting up Howl...
          summary: "Initial setup guide for new users"
          source_file: "Getting-Started.md"
          related_articles:
            - "installation"
            - "quick-start"
          tags:
            - "onboarding"
            - "setup"
      stats:
        article_count: 98
        total_words: 45000
        section_count: 12
        internal_links: 234
        external_links: 45
      owner_id: "usr_01ADMIN"
      visibility: "private"
      tags:
        - "mobile"
        - "flutter"
        - "documentation"

  - name: "RFC Specification"
    description: "Knowledge base representing a multi-part specification"
    value:
      $schema: "kno://specs/knowledge-base-schema@0.1"
      id: "kb_01KNORFC"
      type: "knowledge-base"
      version: "0.1.0"
      name: "kno-specification"
      title: "KNO Format Specification"
      description: |
        The complete specification for the .kno knowledge object format,
        including foundational principles, format requirements, and
        system architecture.
      domain: "specification"
      source:
        type: "authored"
      toc:
        - id: "overview"
          title: "Overview"
        - id: "foundational-principles"
          title: "Foundational Principles"
          children:
            - id: "p1-containers"
              title: "P1: Containers"
            - id: "p2-yaml-kaml"
              title: "P2: YAML/KAML"
            - id: "p3-layers"
              title: "P3: Layers"
        - id: "format-requirements"
          title: "Format Requirements"
        - id: "system-architecture"
          title: "System Architecture"
      articles:
        - id: "overview"
          title: "KNO Format Overview"
          article_type: "index"
          content: |
            # KNO Format Specification

            The .kno format is a container format for knowledge objects...
          summary: "Introduction to the KNO format specification"
          related_articles:
            - "foundational-principles"
            - "format-requirements"
        - id: "foundational-principles"
          title: "Foundational Principles"
          article_type: "concept"
          content: |
            # Foundational Principles

            The KNO format is built on 10 foundational principles...
          summary: "The 10 principles that guide KNO format design"
          related_articles:
            - "p1-containers"
            - "format-requirements"
      stats:
        article_count: 15
        total_words: 12000
        section_count: 4
        internal_links: 45
        external_links: 10
      visibility: "public"
      tags:
        - "specification"
        - "rfc"
        - "kno-format"