ZoaK

ZoaK

Zepp OS Agent Knowledge Base

A compatibility-aware layer between the official Zepp OS sources and the AI agents that write Zepp OS code.

Computed from data/ on every render, never typed by hand.

The question it exists to answer

This is not a documentation mirror. The official docs exist, but they are not in a shape an agent can consume reliably when the question is “can I call this API, in this runtime, at this API_LEVEL?” This project extracts those sources into a structured layer where that question has a checkable answer.

The specific failure it prevents is an agent producing plausible Zepp OS code it cannot justify. Every evaluation run so far finished its task and none was blocked — they failed on vouching, delivering code the base could not back with a citation. That is the problem being solved, not ignorance.

What the sources do not carry

How it works

  1. fetchclone or update the official repos into a local cache
  2. parseten fronts, each reading one shape of source
  3. enrichmerge the fronts into one record per symbol
  4. storewrite the JSON source of truth, one file per module
  5. rendergenerate the Markdown an agent reads

And three things that consume it:

JSON in data/ is the source of truth; the Markdown tree is derived and reproducible. CI re-renders and fails on any diff, so a hand-edited page cannot survive.

How to use it

Everything runs locally. Clone the repo and install — there is nothing to sync first, because data/ and the rendered pages are committed:

git clone https://github.com/FelipeRicardo5/zeppos-agent-knowledge-base.git
cd zeppos-agent-knowledge-base
npm install

npm run sync is only needed to move the base forward against upstream; a fresh clone is already readable. It clones the official repos into .cache/ and rewrites data/.

Three ways in, in order of how much the consumer has to read.

  1. Query it by name

    npm run mcp

    Sixteen read-only tools over stdio. Call get_freshness first: a report that cannot name the version it read cannot be compared with another. Nothing to authenticate, and no request leaves the host.

  2. Score an app against it

    npm run check -- path/to/an/app

    Checks a directory under four rules — runtime, permission, API_LEVEL and manifest — and returns a verdict per line rather than a pass or a fail.

  3. Read the rendered Markdown

    api/  compatibility/  runtimes/  patterns/  …

    Committed, so cloning is enough. This is what the Agent Skill in skills/zepp-os/SKILL.md reads: it carries no documentation of its own, only how to use this base.

What check answers

StatusMeaning
VOUCHEDThis base can point at the record that backs it
UNVERIFIABLENot covered here. Never evidence that the symbol does not exist
VIOLATIONThis base contradicts it

No violation is not approval. Every report ships a notChecked list, because a checker that listed only what it found would teach a reader that silence is approval — the exact reading this project exists to prevent.

What is in it

Generated from data/ on every render. What each number means is the part worth reading; how big it is today is in the table.

WhatCount
Symbols513
Modules50
OFFICIAL / OBSERVED496 / 17
Symbols stating a minimum API_LEVEL353
Symbols with a description435
Symbols with a call signature234
Symbols with a property table, and properties in them184, 1300
Types declared under a heading with no name column142, 232
Value sets, and members in them55, 388
Instance members257
By runtimedevice-app 375, watchface 105, settings 21, side-service 20, workout-extension 12
Devices, of which run Zepp OS with a stated level41, 29
Best-practice patterns11
Sample apps read as code33

What keeps it honest

Read the source on GitHub