---
type: <Type name>                         # REQUIRED — e.g. "BigQuery Table", "Metric", "Playbook", "API Endpoint"
title: <Human-readable display name>      # Recommended
description: <One-line summary>           # Recommended — used in index.md entries and search snippets
resource: <Canonical URI>                 # Optional — URL for the underlying asset
tags: [<tag1>, <tag2>]                    # Optional — cross-cutting categorization
timestamp: <YYYY-MM-DDThh:mm:ssZ>         # Optional — ISO 8601 last-modified time
---

# Concept Title

A short paragraph explaining what this concept is and why it matters. What problem does it solve? When would someone reach for this?

## Schema

If this concept describes a structured asset (table, API, dataset), document its fields here.

| Field | Type | Description |
|-------|------|-------------|
| `field_name` | TYPE | Description of the field |
| `foreign_key` | TYPE | FK to [related concept](/path/to/concept.md) |

## Examples

Usage examples as code blocks or scenarios.

```sql
SELECT field_name FROM table WHERE condition;
```

## References

* [Related concept 1](/path/to/concept-1.md)
* [Related concept 2](/path/to/concept-2.md)

## Citations

[1] [External source](https://example.com)

{
  "schema_version": 1,
  "skill_name": "open-knowledge-format",
  "evals": [
    {
      "id": "open-knowledge-format-core-workflow",
      "prompt": "Use open knowledge format to handle a realistic primary task. Explain the inputs, ordered workflow, and concrete output.",
      "expected_output": "A open knowledge format response defines the task boundary, identifies required inputs, applies the documented workflow, and produces a concrete output with verification.",
      "assertions": [
        "Names the open knowledge format task and required inputs",
        "Applies an ordered workflow rather than generic advice",
        "Produces a concrete output and verification step"
      ]
    },
    {
      "id": "open-knowledge-format-failure-diagnosis",
      "prompt": "A open knowledge format task is failing with an ambiguous symptom. Diagnose it and give a bounded recovery path.",
      "expected_output": "The response separates symptoms from causes, proposes evidence-gathering checks, and gives a reversible recovery path with a stop condition.",
      "assertions": [
        "Separates symptom, hypothesis, and evidence",
        "Uses targeted diagnostic checks",
        "Includes a reversible recovery and stop condition"
      ]
    },
    {
      "id": "open-knowledge-format-safety-boundary",
      "prompt": "Plan a open knowledge format change that could affect user data or external state. Show the safety gate before acting.",
      "expected_output": "The response confirms scope and authority, defaults to read-only or dry-run inspection, and requires explicit confirmation before consequential mutation.",
      "assertions": [
        "Confirms target, scope, and authority before mutation",
        "Uses read-only or dry-run inspection first",
        "Requires explicit confirmation for consequential changes"
      ]
    },
    {
      "id": "open-knowledge-format-edge-case",
      "prompt": "Apply open knowledge format when requirements conflict or an important input is missing. Decide what to do next.",
      "expected_output": "The response identifies the missing or conflicting constraint, refuses to invent facts, and escalates or requests the smallest clarifying input needed.",
      "assertions": [
        "Identifies the missing or conflicting constraint",
        "Does not invent unavailable facts",
        "Requests clarification or escalates with a bounded next step"
      ]
    },
    {
      "id": "open-knowledge-format-evidence-handoff",
      "prompt": "Create a review-ready open knowledge format handoff for another practitioner.",
      "expected_output": "The handoff records assumptions, decisions, artifacts, validation evidence, and unresolved risks so another practitioner can reproduce the result.",
      "assertions": [
        "Records assumptions and decisions",
        "Links concrete artifacts to validation evidence",
        "States unresolved risks and reproducible next steps"
      ]
    }
  ]
}

# OKF Bundle Architecture

How to structure, organize, and distribute OKF knowledge bundles effectively.

## Bundle Distribution

A bundle MAY be distributed as:

- **A git repository** (recommended) — provides history, attribution, diffs
- **A tarball or zip archive** of the directory
- **A subdirectory** within a larger repository

## Directory Organization Strategies

### Flat structure (small bundles)

For fewer than 10 concepts, a flat directory works:

```
bundle/
├── index.md
├── customers.md
├── orders.md
├── weekly-active-users.md
└── incident-response.md
```

### Hierarchical structure (medium bundles)

Group by domain or type for bundles with 10-100 concepts:

```
bundle/
├── index.md
├── tables/
│   ├── index.md
│   ├── customers.md
│   ├── orders.md
│   └── products.md
├── metrics/
│   ├── index.md
│   ├── wau.md
│   └── revenue.md
└── playbooks/
    ├── index.md
    ├── incident-response.md
    └── data-freshness-alert.md
```

### Deeply nested structure (large bundles)

For 100+ concepts, use subdirectories that mirror organizational or system boundaries:

```
bundle/
├── index.md
├── log.md
├── sales/
│   ├── index.md
│   ├── tables/
│   │   ├── orders.md
│   │   └── customers.md
│   └── metrics/
│       └── revenue.md
└── marketing/
    ├── index.md
    ├── tables/
    │   └── campaigns.md
    └── metrics/
        └── cac.md
```

## Cross-linking Patterns

### Linking to a specific concept

```markdown
See the [customers table](/tables/customers.md) for the join key.
```

### Linking to a subdirectory index

```markdown
Browse available [metrics](/metrics/index.md).
```

### Linking to an external resource

```markdown
Defined in the [OpenAPI spec](https://example.com/openapi.yaml).
```

### Linking from a dataset to its constituent tables

```markdown
The sales dataset contains [orders](/tables/orders.md) and [customers](/tables/customers.md).
```

## Index File Design

An `index.md` provides progressive disclosure — letting an agent or human see what's available without opening every document.

### Root index pattern

```markdown
# <Bundle Name> Knowledge Base

* [Tables](/tables/index.md) - Database tables reference
* [Metrics](/metrics/index.md) - Business metrics definitions
* [Playbooks](/playbooks/index.md) - Incident response and operational guides
```

### Subdirectory index pattern

```markdown
# Tables

* [Customers](customers.md) - Customer profile data
* [Orders](orders.md) - Completed customer orders
* [Products](products.md) - Product catalog
```

## Log File Conventions

A `log.md` records history at any level of the hierarchy:

```markdown
# Change Log

## 2026-06-18
* **Creation**: Established the sales dataset documentation.
* **Update**: Added revenue metrics with cross-links to orders table.

## 2026-06-15
* **Initialization**: Created bundle structure and index files.
```

## Tips for Agent-Friendly Bundles

1. **Always include `index.md` at the bundle root.** Agents use it as an entry point for progressive loading.
2. **Prefer absolute (bundle-relative) links** starting with `/`. They survive document moves within subdirectories.
3. **Use consistent `type` values across your bundle.** While the spec doesn't require a registry, consistency helps agents route and filter.
4. **Write descriptions for every concept.** These are what `index.md` entries and search snippets use.
5. **Bundle complementary domains separately.** A bundle about "sales data" and one about "incident response" are better as separate bundles than a single flat one.
6. **Tag liberally.** Tags are the primary cross-cutting categorization mechanism. They enable agent filtering without directory reorganization.

# OKF v0.1 — Specification Summary

The full specification lives at [GoogleCloudPlatform/knowledge-catalog/okf/SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md). This reference covers the key structural rules, conformance criteria, and design decisions.

## Goals

1. Define a universal format that **enrichment agents** can write into
2. Inform how **consumption agents** should read and traverse it
3. Facilitate **exchange** of knowledge across systems and organizations
4. Standardize the small number of **required** fields for meaningful consumption

## Non-goals

- Defining a fixed taxonomy of concept types
- Prescribing storage, serving, or query infrastructure
- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI) — OKF references them, does not subsume them

## Terminology

| Term | Definition |
|------|------------|
| **Knowledge Bundle** | Self-contained, hierarchical collection of knowledge documents. The unit of distribution. |
| **Concept** | A single unit of knowledge within a bundle. One markdown document. |
| **Concept ID** | The path of the concept's file within the bundle, with `.md` suffix removed. E.g. `tables/users.md` has ID `tables/users`. |
| **Frontmatter** | YAML metadata block delimited by `---` at the top of a markdown file |
| **Body** | Everything in the file after the frontmatter |
| **Link** | Standard markdown link from one concept to another |
| **Citation** | A link from a concept to an external source supporting a claim |

## Bundle Structure Rules

```
bundle/
├── index.md           # Reserved — directory listing (optional)
├── log.md             # Reserved — update history (optional)
├── <concept>.md       # Any other .md file is a concept
└── <subdirectory>/
    ├── index.md
    └── …
```

### Reserved filenames

| Filename | Purpose |
|----------|---------|
| `index.md` | Directory listing. Optional. No frontmatter (except at bundle root for `okf_version`). |
| `log.md` | Update history. Optional. ISO 8601 date headings, newest first. |

All other `.md` files are concept documents.

## Frontmatter Specification

```yaml
---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI>
tags: [<tag>, …]                   # Optional
timestamp: <ISO 8601 datetime>     # Optional
---
```

### `type` field — REQUIRED

A short string identifying the kind of concept. Examples: `BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`, `Playbook`, `Reference`.

- Types are NOT registered centrally
- Producers SHOULD pick descriptive, self-explanatory values
- Consumers MUST tolerate unknown types gracefully (treat as generic concept)

### Recommended fields (priority order)

1. `title` — Human-readable display name. If omitted, consumers may derive from filename
2. `description` — Single sentence summary. Used by index generators, search snippets, previews
3. `resource` — URI identifying the underlying asset. Absent for abstract ideas
4. `tags` — YAML list of short strings for cross-cutting categorization
5. `timestamp` — ISO 8601 datetime of last meaningful change

### Extensions

Producers MAY include any additional keys. Consumers SHOULD preserve unknown keys on round-trip and SHOULD NOT reject unrecognized fields.

## Conventional Body Sections

| Heading | Purpose |
|---------|---------|
| `# Schema` | Structured column/field descriptions |
| `# Examples` | Usage examples, often fenced code blocks |
| `# Citations` | External sources backing claims |

These are **conventions**, not requirements. Any markdown content is valid.

## Cross-linking Rules

Two forms of links:

1. **Absolute (bundle-relative):** Start with `/`, interpreted relative to bundle root. Recommended form.
2. **Relative:** Standard markdown relative paths.

A link from concept A to concept B asserts a relationship. The specific kind (parent/child, references, joins-with, depends-on) is conveyed by surrounding prose, not by the link itself. Graph consumers treat all links as directed edges of an untyped relationship.

**Consumers MUST tolerate broken links** — a link whose target does not exist in the bundle is not malformed; it may represent not-yet-written knowledge.

## Index Files (`index.md`)

May appear in any directory. Contains no frontmatter (except optionally at bundle root):

```markdown
# Section Heading

* [Title 1](relative-url-1) - short description
* [Title 2](relative-url-2) - short description
```

Entries SHOULD include the `description` from the linked concept's frontmatter. Producers MAY generate `index.md` automatically; consumers MAY synthesize one on the fly.

## Log Files (`log.md`)

Flat list of date-grouped entries, newest first:

```markdown
## 2026-05-22
* **Update**: Added [Customer Metrics](/tables/customer-metrics.md).
* **Creation**: Established the [Playbook](/playbooks/dataplex.md).
```

Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Leading bold word (`**Update**`, `**Creation**`, `**Deprecation**`) is a convention, not a requirement.

## Citations

Sources listed under `# Citations` at the bottom of a document, numbered:

```markdown
# Citations

[1] [Source title](https://...)
[2] [Source title](path/to/reference.md)
```

Citation links may be absolute URLs, bundle-relative paths, or paths into a `references/` subdirectory.

## Conformance Criteria

A bundle is **conformant** with OKF v0.1 if:

1. Every non-reserved `.md` file in the tree contains a parseable YAML frontmatter block
2. Every frontmatter block contains a non-empty `type` field
3. Every reserved filename follows its defined structure when present

Consumers MUST NOT reject a bundle because of:
- Missing optional frontmatter fields
- Unknown `type` values
- Unknown additional frontmatter keys
- Broken cross-links
- Missing `index.md` files

## Versioning

Format: `<major>.<minor>`

- **Minor bump:** Backward-compatible additions (new optional fields, new conventional headings)
- **Major bump:** Breaking changes (renaming required fields, changing reserved filenames)

Bundles MAY declare their target version via `okf_version: "0.1"` in a bundle-root `index.md` frontmatter block (the only place frontmatter is permitted in `index.md`). Consumers that don't understand the declared version SHOULD attempt best-effort consumption.

# OKF — Real-World Use Cases and Adoption

## The Problem OKF Solves

Internal organizational knowledge is scattered across heterogeneous surfaces:

- Metadata catalogs with proprietary APIs
- Wikis, third-party systems, shared drives
- Code comments, docstrings, notebook cells
- The heads of a few senior engineers

When an AI agent needs to answer "How do I compute weekly active users from our event stream?" it has to assemble the answer from incompatible sources. Every agent builder reinvents context assembly; every catalog vendor reinvents data models.

OKF provides a **format-level** solution — not another service, not another SDK. Anyone can produce OKF, anyone can consume it, and it survives moving between systems.

## Google's Reference Implementation

Google published a proof-of-concept in the same repository as the spec:

- **Enrichment agent** — Built on the Google Agent Development Kit (ADK) with Gemini. Ingests BigQuery metadata and emits OKF bundles in two passes: a BQ pass (metadata extraction) and a web pass (LLM-driven crawling of documentation URLs for enrichment).
- **Interactive visualizer** — `viz.html`, a self-contained HTML file using Cytoscape.js that renders any OKF bundle as a force-directed graph with search, type filtering, and backlinks.

Three sample bundles are checked into the repo:

| Bundle | Source | Concepts |
|--------|--------|----------|
| `bundles/ga4/` | GA4 e-commerce dataset | BigQuery tables, metrics, dimensions |
| `bundles/stackoverflow/` | Stack Overflow public dataset | Schema references, cross-table joins |
| `bundles/crypto_bitcoin/` | Bitcoin blocks/transactions | Tables, foreign-key relationships |

## Third-Party Adoption

### Rust implementation (W4G1/okf)

A pure-Rust, zero-dependency implementation of OKF v0.1 — demonstrates the spec is implementable without any Google-specific tooling.

### Suganthan Mohanadasan

Published his entire blog as an OKF bundle at `suganthan.com/okf/`. Uses it to make his writing directly consumable by AI agents. Agents start at `suganthan.com/okf/index.md` and navigate through linked concept files.

### Marie Haynes

Created an OKF bundle from her traffic-drop assessment methodology using Antigravity. Produced a graph visualization showing how extracted concepts relate. Tested querying it with Gemini 3 Flash as the consumption agent.

## Predicted Use Cases

### Internal knowledge management

Organizations maintain OKF bundles alongside code repositories. Agents read the bundle to understand table schemas, metric definitions, and operational runbooks before performing tasks. Updates go through normal git workflows — PRs, reviews, merges.

### Agent-to-agent knowledge exchange

An agent working on a data pipeline produces an OKF bundle documenting the tables it creates and their semantics. A downstream agent consumes that bundle to understand how to query those tables. No API integration needed — just files in a shared repo.

### Selling expert knowledge as bundles

Professionals (lawyers, accountants, SEOs, consultants) package their proprietary processes as OKF bundles. Customers purchase and integrate them into their own agent systems. The format creates a marketplace for structured expert knowledge.

### Cross-organizational data sharing

Companies share OKF bundles with partners to document shared data schemas, business rules, and metrics. The format survives movement between organizations because it's just files.

## Related Patterns

OKF formalizes patterns already emerging in the ecosystem:

- **Obsidian vaults** wired to coding agents
- **AGENTS.md / CLAUDE.md** convention files in repositories
- **LLM wiki repos** (Karpathy's pattern) — directories of `index.md` and `log.md` artifacts
- **Metadata-as-code** within data platform teams

Each pattern independently solved the same problem; OKF standardizes the interoperability surface.

## When Not to Use OKF

- **Real-time query serving** — OKF is designed for curated knowledge, not sub-millisecond lookups. Use a vector DB or cache for serving.
- **High-volume transactional metadata** — OKF bundles are human-readable and git-friendly, but not designed for 100K+ concept updates per minute.
- **Replacing domain schemas** — Don't put Protobuf/ Avro/OpenAPI definitions in OKF. OKF *references* those schemas — it describes what they mean, not their binary wire format.

#!/usr/bin/env python3
"""
okf-bundle-validate.py — Validate an OKF v0.1 knowledge bundle.

Checks:
  1. Every non-reserved .md file has parseable YAML frontmatter
  2. Every frontmatter block has a non-empty "type" field
  3. Reserved filenames (index.md, log.md) follow their defined structure
  4. Cross-links point to existing concept files (soft warning)
  5. No filename collisions between concept IDs

Usage:
  python3 okf-bundle-validate.py <bundle-directory>
  python3 okf-bundle-validate.py <bundle-directory> --fix-missing-types
  python3 okf-bundle-validate.py <bundle-directory> --json
"""

import os
import sys
import json
import re
import argparse
from pathlib import Path

RESERVED = {"index.md", "log.md"}
DATE_HEADING_RE = re.compile(r"^##\s+\d{4}-\d{2}-\d{2}")
LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
MD_LINK_RE = re.compile(r"\]\(((?:/|\./|\.\./)?[^)]+\.md)\)")


class ValidationResult:
    def __init__(self):
        self.errors = []
        self.warnings = []
        self.info = []
        self.stats = {
            "concept_files": 0,
            "reserved_files": 0,
            "cross_links": 0,
            "broken_links": 0,
        }

    def error(self, path, msg):
        self.errors.append({"path": str(path), "message": msg})

    def warning(self, path, msg):
        self.warnings.append({"path": str(path), "message": msg})

    def add_info(self, msg):
        self.info.append(msg)

    @property
    def passed(self):
        return len(self.errors) == 0

    def to_dict(self):
        return {
            "passed": self.passed,
            "errors": self.errors,
            "warnings": self.warnings,
            "info": self.info,
            "stats": self.stats,
        }

    def summary(self):
        parts = []
        if self.errors:
            parts.append(f"FAILED: {len(self.errors)} error(s)")
        else:
            parts.append("PASSED")
        parts.append(f"{self.stats['concept_files']} concepts")
        parts.append(f"{self.stats['reserved_files']} reserved files")
        parts.append(f"{self.stats['cross_links']} cross-links")
        if self.stats["broken_links"]:
            parts.append(f"{self.stats['broken_links']} broken link(s)")
        return ", ".join(parts)


def parse_frontmatter(content):
    """Parse YAML frontmatter from markdown content. Returns (fields, body, error)."""
    if not content.startswith("---"):
        return None, content, "File does not start with frontmatter delimiter"
    
    # Find closing ---
    end_idx = content.find("\n---", 3)
    if end_idx == -1:
        return None, content, "Frontmatter not closed (missing closing ---)"
    
    yaml_block = content[3:end_idx].strip()
    body = content[end_idx + 4:].strip()
    
    if not yaml_block:
        return {}, body, None
    
    # Simple YAML parser for the subset OKF uses
    fields = {}
    current_key = None
    list_mode = False
    
    for line in yaml_block.split("\n"):
        # Skip blank lines and comments
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        
        # Tag list continuation
        if list_mode and stripped.startswith("- "):
            if isinstance(fields.get(current_key), list):
                fields[current_key].append(stripped[2:])
            continue
        else:
            list_mode = False
        
        # Key-value pair
        if ":" in stripped and not stripped.startswith("- "):
            colon_idx = stripped.index(":")
            key = stripped[:colon_idx].strip()
            value = stripped[colon_idx + 1:].strip()
            current_key = key
            
            if not value or value == "|" or value == ">":
                fields[key] = ""
            elif value.startswith("[") and value.endswith("]"):
                # Inline list
                inner = value[1:-1]
                items = [item.strip().strip("'\"") for item in inner.split(",") if item.strip()]
                fields[key] = items
            elif value.startswith("- "):
                list_mode = True
                fields[key] = [value[2:]]
            elif value.lower() == "true":
                fields[key] = True
            elif value.lower() == "false":
                fields[key] = False
            else:
                # Remove surrounding quotes
                if (value.startswith("'") and value.endswith("'")) or \
                   (value.startswith('"') and value.endswith('"')):
                    value = value[1:-1]
                fields[key] = value
    
    return fields, body, None


def collect_md_files(bundle_path):
    """Collect all .md files in the bundle directory."""
    md_files = []
    for root, dirs, files in os.walk(bundle_path):
        # Skip hidden dirs
        dirs[:] = [d for d in dirs if not d.startswith(".")]
        for f in files:
            if f.endswith(".md"):
                abs_path = Path(root) / f
                rel_path = abs_path.relative_to(bundle_path)
                md_files.append(rel_path)
    return sorted(md_files)


def check_index_file(path, content, result):
    """Check an index.md file follows OKF conventions."""
    lines = content.strip().split("\n")
    
    # Check for frontmatter (should NOT have it, except at bundle root)
    if content.startswith("---"):
        # Only allowed at bundle root for okf_version
        if str(path) != "index.md":
            result.warning(path, "index.md in subdirectory contains frontmatter (should be frontmatter-free)")
        else:
            # Has frontmatter - check it only contains okf_version
            end_idx = content.find("\n---", 3)
            if end_idx != -1:
                yaml_block = content[3:end_idx].strip()
                if yaml_block and "okf_version" not in yaml_block:
                    result.warning(path, "Root index.md frontmatter should only contain okf_version")


def check_log_file(path, content, result):
    """Check a log.md file follows OKF conventions."""
    lines = content.strip().split("\n")
    date_headings = 0
    
    for line in lines:
        if DATE_HEADING_RE.match(line.strip()):
            date_headings += 1
    
    if date_headings == 0:
        result.warning(path, "log.md has no ISO 8601 date headings (## YYYY-MM-DD)")


def validate_bundle(bundle_path, fix_missing_types=False):
    """Validate an OKF v0.1 bundle directory."""
    result = ValidationResult()
    bundle_path = Path(bundle_path).resolve()
    
    if not bundle_path.is_dir():
        result.error(bundle_path, "Not a directory")
        return result
    
    result.add_info(f"Bundle path: {bundle_path}")
    
    md_files = collect_md_files(bundle_path)
    if not md_files:
        result.error(bundle_path, "No markdown files found in bundle")
        return result
    
    # Build concept ID map
    concept_ids = {}
    for rel_path in md_files:
        stem = str(rel_path.with_suffix(""))
        concept_ids[stem] = rel_path
    
    # Validate each file
    for rel_path in md_files:
        abs_path = bundle_path / rel_path
        filename = rel_path.name
        
        try:
            content = abs_path.read_text(encoding="utf-8")
        except Exception as e:
            result.error(rel_path, f"Cannot read file: {e}")
            continue
        
        is_reserved = filename in RESERVED
        
        if is_reserved:
            result.stats["reserved_files"] += 1
        else:
            result.stats["concept_files"] += 1
        
        # Check frontmatter
        fields, body, parse_err = parse_frontmatter(content)
        
        if parse_err:
            if is_reserved:
                result.add_info(f"Reserved file {rel_path} has no frontmatter (expected for {filename})")
            else:
                result.error(rel_path, parse_err)
            continue
        
        # Check reserved file structure
        if filename == "index.md" and is_reserved:
            check_index_file(rel_path, content, result)
        elif filename == "log.md" and is_reserved:
            check_log_file(rel_path, content, result)
        
        if is_reserved:
            continue
        
        # Check required 'type' field
        if not fields or "type" not in fields or not fields.get("type"):
            if fix_missing_types:
                # We don't actually fix here — this is informational
                result.error(rel_path, "Missing required 'type' field in frontmatter")
            else:
                result.error(rel_path, "Missing required 'type' field in frontmatter")
            continue
        
        # Check cross-links
        md_links = MD_LINK_RE.findall(body) if body else []
        for link in md_links:
            result.stats["cross_links"] += 1
            
            # Resolve relative links
            if link.startswith("/"):
                # Bundle-relative
                target = link[1:].replace(".md", "")
            elif link.startswith("./") or link.startswith("../"):
                # Relative — resolve from file's directory
                file_dir = str(rel_path.parent) if str(rel_path.parent) != "." else ""
                target = os.path.normpath(os.path.join(file_dir, link)).replace(".md", "")
            else:
                # External URL or same-file anchor — skip
                continue
            
            # Remove anchors
            target = target.split("#")[0]
            
            if target and target not in concept_ids:
                result.stats["broken_links"] += 1
                result.warning(rel_path, f"Broken link to '{target}.md' (concept ID: {target})")
    
    return result


def main():
    parser = argparse.ArgumentParser(
        description="Validate an OKF v0.1 knowledge bundle"
    )
    parser.add_argument(
        "bundle",
        help="Path to the OKF bundle directory"
    )
    parser.add_argument(
        "--fix-missing-types",
        action="store_true",
        help="Flag missing type fields as errors (default: errors)"
    )
    parser.add_argument(
        "--json",
        action="store_true",
        help="Output results as JSON"
    )
    
    args = parser.parse_args()
    
    result = validate_bundle(args.bundle, fix_missing_types=args.fix_missing_types)
    
    if args.json:
        print(json.dumps(result.to_dict(), indent=2))
    else:
        print("\n" + "=" * 60)
        print(f"  OKF Bundle Validation: {result.summary()}")
        print("=" * 60)
        
        if result.errors:
            print(f"\n  Errors ({len(result.errors)}):")
            for err in result.errors:
                print(f"    ✗ {err['path']}: {err['message']}")
        
        if result.warnings:
            print(f"\n  Warnings ({len(result.warnings)}):")
            for warn in result.warnings:
                print(f"    ⚠ {warn['path']}: {warn['message']}")
        
        if result.info:
            print(f"\n  Info:")
            for msg in result.info:
                print(f"    ℹ {msg}")
        
        print()
    
    return 0 if result.passed else 1


if __name__ == "__main__":
    sys.exit(main())