WorkBuddyGuide: the community bluebook for WorkBuddy, and what it actually contains

What WorkBuddyGuide is, and what it is not

The repository is a knowledge base, not software you run against WorkBuddy. The README describes it as a community-maintained practical knowledge base for WorkBuddy, and the opening line explicitly says it is not a rewrite of an official feature manual. That distinction matters. If you arrive expecting a CLI wrapper, an SDK, or a client that logs into WorkBuddy for you, you will find a VitePress site instead: Markdown chapters, a sidebar, full-text search, dark mode, flow diagrams and mobile layout.

The audience is narrow and specific. It is for someone who has WorkBuddy in front of them and does not know what to do with it. The README's stated path is to finish installation and a first task, then move through mobile work, knowledge management, professional diagnosis, content automation and multi-agent teams, and finally turn one success into a reusable team workflow. The table of contents splits into four parts plus an appendix: a usage manual covering download, install, interface, first task, Skill, connectors, API and automation; a case section covering office work, files, remote work, news, knowledge, meetings, investment, video, self-media and GEO; an advanced section on building Skills, multi-agent system design and automation reliability; and a roles-and-industries part with per-role routes and industry workflows.

One structural point worth noticing: the repository is bilingual. The README links to README_en.md, and there is a CONTRIBUTING_en.md alongside CONTRIBUTING.md. The primary language recorded for the repository is Python, which does not match the visible stack (VitePress, Vue, Wrangler, Vitest). Treat the language label as unreliable metadata rather than a description of the codebase.

The mechanism: VitePress content plus a Cloudflare traffic collector

The reading experience is VitePress. The package.json scripts point at docs as the source root, and the build output lands in docs/.vitepress/dist. Content lives under docs/bluebook for finished chapters and docs/cases/submissions for community cases, with docs/community holding the contribution guides, docs/help holding the scenario questionnaire page, and docs/public holding static assets such as images and QR codes.

There is more machinery here than a docs site usually needs. The top level contains functions/, migrations/, workers/, wrangler.jsonc and wrangler.collector.jsonc, and package.json exposes D1 migration and seed commands for a database named TRAFFIC_DB. That suggests a page-view or traffic collector running as a Cloudflare Worker with a D1 database, separate from the static site. The README does not describe this collector, so its exact behaviour cannot be confirmed from the documentation; the repository layout and the script names are the evidence. If you fork this project for your own content, that collector is the part most likely to need rethinking, because the seed script and migrations are built around this site's own schema.

Deployment is stated plainly: VitePress, Cloudflare Pages and GitHub. Cloudflare Pages connects to the main branch, and each push triggers an automatic build and deploy. Configuration is said to be in DEPLOYMENT.md. That is a low-friction setup for a documentation project, and it also means the live site and the repository can drift: a merged chapter appears on the site before anyone reads it in the GitHub tree.

Installing the site locally and reading the first chapter

You are installing the documentation site, not WorkBuddy itself. The README specifies Node.js 20 to 24, with Node.js 22 recommended. There is also a .nvmrc file at the top level, so if you use nvm, read that file rather than guessing. The install and dev commands are the standard VitePress pair:

npm install
npm run dev

The dev script is defined as vitepress dev docs --host 127.0.0.1, so the server binds to localhost, not to your network. To check that the site builds the way Cloudflare Pages will build it, run the build and preview scripts:

npm run docs:build
npm run docs:preview

These are aliases for the build and preview scripts in package.json, and the build writes to docs/.vitepress/dist. If you want to serve that output the way the Pages deployment does, package.json also defines a wrangler-based path:

npm run pages:dev

That command runs wrangler pages dev against docs/.vitepress/dist on port 8788. For a first real use, follow the README's own recommendation rather than browsing the tree: start at chapter 1 of the first part and work through the usage manual in order. The README is direct that GitHub is for understanding the project and contributing, while the website at workbuddy.homes is the better reading experience. Do the local install when you want to preview your own edits or submit a case.

Submitting a case: the contribution contract is the real product

The most concrete part of this repository is the contribution specification. The README says cases are prioritized when they are real and reproducible, and it asks contributors to search the community case collection and the bluebook table of contents first to confirm the scenario is not a duplicate. If the goal is the same but the Skill, method or deliverable differs, the pull request should explain the difference.

Each case must document six things: the scenario and problem (who hit what difficulty in what task), the Skill used (its function, source, installation and required configuration), the task description (the prompt, steps or automation settings entered in WorkBuddy), the execution process (key operations, permission requirements, input material and safety boundaries), the actual result (screenshots or other evidence of the final output), and acceptance criteria (how to judge that the task was completed correctly). That list is stricter than most documentation projects, and it is the reason the guide can be useful: a case that omits the Skill source or the permission boundary is not reproducible.

Mechanically, you create a directory under docs/cases/submissions/, write the case using the template at .github/CASE_TEMPLATE.md, and submit through the case pull request template in .github/PULL_REQUEST_TEMPLATE/case.md. After review and merge, the README states the case appears automatically in the site's left sidebar. Representative cases may be reproduced and edited further before entering a formal bluebook chapter. The README does not document a rollback or removal process for a merged case, and it does not state review timelines.

Where the guide stops being the right tool

The README's own disclaimer is the main limitation, and it is unusually clear: this is a community knowledge base, and for time-sensitive information about product features, interface, pricing, availability and security policy, official WorkBuddy channels take precedence. That is a real constraint, not boilerplate. A chapter describing a Skill installation or an API call can be correct on the day it was written and wrong after a product update, and nothing in the repository enforces that chapters get re-verified.

There is a second boundary around what the repository is. It contains no WorkBuddy client code, no SDK and no server. Searching the tree for something to run against WorkBuddy will produce only the VitePress site, the Cloudflare Worker collector and the scripts directory. If your goal is to automate WorkBuddy from a CI pipeline, this project will not do it; it will only tell you, in prose and screenshots, how someone else did something similar.

The maintenance signal is also weak. The repository is not archived, but no last-push date was retrieved, and there are no releases. For a documentation project that is less alarming than for a library, because there is nothing to upgrade, but it does mean you cannot infer freshness from a version number. Check the chapter's own content against the official channels the README points to. Finally, the docs site depends on a Cloudflare Worker and a D1 database for its traffic collector. Self-hosting the whole thing is not a simple static deploy; the wrangler.collector.jsonc and migrations/ paths are part of the surface area.

Compared with a general-purpose static docs generator

The natural alternative is to skip this repository and build your own VitePress site, or use another static documentation generator, and write your own notes. The difference in approach is the point. A general generator gives you a theme and a build; it says nothing about what a useful WorkBuddy case looks like. WorkBuddyGuide ships an opinionated content contract instead: the six required case fields, the duplicate check against the community collection and bluebook index, the case template and pull request template, and the promotion path from a submission to a formal chapter.

That contract is why the project is more than a blog. It also explains the site's extra machinery: the help questionnaire page at docs/help is a funnel for real scenarios, and the community case collection is where accepted ones land. A generic generator would leave you to invent all of that. The trade-off is coupling. You inherit VitePress 1.6.4, Mermaid 11.16.0 for diagrams, the Cloudflare Pages deployment assumption, and the D1 collector if you want the same analytics. If you only want to publish notes, a plain generator is less to maintain. If you want a structure that other people can contribute to without renegotiating the format every time, this repository already has one.

Editorial conclusion

Adopt WorkBuddyGuide if you are starting with WorkBuddy and want a task-first path from installation through Skills and MCP to multi-agent setups, or if you want to submit a reproducible case. Do not treat it as product documentation: the README states that time-sensitive details such as features, interface, pricing, availability and security policy should be checked against official WorkBuddy channels. Before relying on it, verify the Node.js version against .nvmrc, run npm run docs:build locally, and confirm that the chapter you need is a finished bluebook chapter rather than a submission under docs/cases/submissions/.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository