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.
- 513symbols
- 50modules
- 41devices
- 33sample apps read as 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
Compatibility as an axis
Which symbol runs at which minimum API_LEVEL, joined to the devices that state one.
Runtime attribution
Which of the five runtimes a symbol is valid in, taken from the source path, never from page text.
Contradiction between sources
Where the docs and the shipped samples disagree, stated rather than silently resolved.
Reverse lookup
Symbols, members, enum values and shape properties keyed by what you would type, not by where they sit.
How it works
fetchclone or update the official repos into a local cacheparseten fronts, each reading one shape of sourceenrichmerge the fronts into one record per symbolstorewrite the JSON source of truth, one file per modulerendergenerate the Markdown an agent reads
And three things that consume it:
verifyask the rendered base real questions and check the answerscheckscore an app directory against the basemcpserve the base over MCP, so an agent queries it instead of reading 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.
-
Query it by name
npm run mcpSixteen 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.
-
Score an app against it
npm run check -- path/to/an/appChecks a directory under four rules — runtime, permission, API_LEVEL and manifest — and returns a verdict per line rather than a pass or a fail.
-
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
| Status | Meaning |
|---|---|
VOUCHED | This base can point at the record that backs it |
UNVERIFIABLE | Not covered here. Never evidence that the symbol does not exist |
VIOLATION | This 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.
| What | Count |
|---|---|
| Symbols | 513 |
| Modules | 50 |
OFFICIAL / OBSERVED | 496 / 17 |
Symbols stating a minimum API_LEVEL | 353 |
| Symbols with a description | 435 |
| Symbols with a call signature | 234 |
| Symbols with a property table, and properties in them | 184, 1300 |
| Types declared under a heading with no name column | 142, 232 |
| Value sets, and members in them | 55, 388 |
| Instance members | 257 |
| By runtime | device-app 375, watchface 105, settings 21, side-service 20, workout-extension 12 |
| Devices, of which run Zepp OS with a stated level | 41, 29 |
| Best-practice patterns | 11 |
| Sample apps read as code | 33 |
What keeps it honest
A reproducible render
data/ and the rendered pages are both committed, so CI re-renders from a plain checkout and fails on a diff — the “JSON is the source of truth” rule, made enforceable.
Questions, not coverage
verify asks the rendered pages a fixed set of questions a developer would actually ask, and fails naming the one that stopped being answerable. Every question carries why it is in the set.
A weekly sync that opens a PR
Every parser bug here has been an upstream format change that made an extraction silently smaller. A count that went down is the thing to look at, and a reviewable diff is the only form in which those have ever been caught.