Check an OKF knowledge pack before an agent uses it

Run this report from the CLI, an MCP client, or application code. Every surface uses the same report definition and returns the same evidence. JSON is the source of truth; Markdown makes it readable without hiding dates, limits, warnings, or skipped work.

What this report helps you decide

Does this OKF file set satisfy the expected local contract?

• Files were generated or edited and need validation.
• An automation depends on predictable paths and metadata.

Command facts

Report id

okf-validate

Execution

Local process

Outputs

JSON and Markdown

Example parameters

files

Agent discovery

seo reports describe okf-validate --json

Interactive prompts

Human CLI commands only

When this report is not the right tool

These cases need a different report, more evidence, or a human decision. Do not force this report to answer a question its data cannot support.

• You need to rebuild the knowledge pack from a current saved crawl. Recommended report: Build site knowledge for agents. Run OKF build with the current crawl and explicit file limits. It regenerates the manifest, concepts, source references, and optional Markdown files before validation.
• You need to know whether the content inside valid files is accurate, complete, or still current. No automated report can establish factual accuracy from file structure. Follow the citations to the current source pages and review the claims manually; this validator can still identify broken references that would prevent that review.

Data sources and inputs

• OKF Markdown files. Supplies the limited paths and file contents that need structural validation.

What this report checks

• Parses supported frontmatter, headings, links, citations, paths, and manifest references.
• Returns repeatable errors and warnings without fetching pages or judging the truth of their content.

How it works

• Parses the limited file set and returns repeatable errors and warnings for the supported format.

The JSON result keeps dates, thresholds, limits, skipped work, and source completeness beside the finding. Missing, partial, capped, filtered, and complete data remain different states.

Run the report from the CLI

Check an OKF knowledge pack before an agent uses it. Agents and CI should inspect the live schema before their first run.

seo okf validate ./okf

seo reports describe okf-validate --json

seo reports run okf-validate --params '{"files":[{"path":"index.md","content":"# Example knowledge"},{"path":"caveats.md","content":"# Caveats"}]}' --json

Project profiles can fill supported property and analytics inputs for the human-facing commands. The catalog form shown here is explicit by design, so agents and CI jobs do not prompt or guess.

How an MCP agent should use it

Call seo_describe_report first so the agent sees when this report is useful and gets the current input schema. Then callseo_run_report with the validated parameters. Read the status, warnings, source limits, and skipped sections before acting on a finding.

{
  "id": "okf-validate"
}

{
  "id": "okf-validate",
  "params": {
    "files": [
      {
        "path": "index.md",
        "content": "# Example knowledge"
      },
      {
        "path": "caveats.md",
        "content": "# Caveats"
      }
    ]
  }
}

Use a follow-up report returned by the result instead of guessing the next tool. The local MCP server and CLI use the same report definition and evidence. Their outer transport envelopes differ.

Use the report in a TypeScript app

Install seo as a project dependency, then call the same report catalog used by the CLI and MCP. executeReportrejects an unknown report id or invalid parameters. Provider and runtime failures come back as structured results withisError set.

npm install seo

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'okf-validate',
  {
  "files": [
    {
      "path": "index.md",
      "content": "# Example knowledge"
    },
    {
      "path": "caveats.md",
      "content": "# Caveats"
    }
  ]
},
)

console.log(result)

The TypeScript library guide also covers direct core functions, schema discovery, and the difference betweenexecuteReport and runReport.

What comes back and how to read it

• A pass or fail result with structured validation errors and warnings for each affected file.
• Plain-language guidance for fixing supported format and reference problems.
• Fix errors before use. Review warnings in context, then check cited live pages for factual accuracy.

Start with dataStatus, source details, warnings, and caveats. Then inspect the observed evidence before derived findings or suggested actions.

What this report cannot tell you

• A valid file set can still contain stale, incomplete, or incorrect content.

What to do next

1. Correct invalid files and rerun validation.
2. Rebuild from a current crawl when source details is unclear.

Related reports

• Build site knowledge for agents. Turn a saved crawl into a compact OKF knowledge pack with source pages an agent can inspect and verify locally.
• Open a saved crawl report. Retrieve one local crawl snapshot in compact form and request its page or issue inventory only when you need it.

Browse all reports in Crawling and technical checks.