feat: add /docs site, restructure README, align skill with protocol#1
feat: add /docs site, restructure README, align skill with protocol#1
Conversation
- Add 9 docs under /docs/ (signal format, architecture, quick-start, build-a-sensor, multi-sensor, sensorhub, why-w2a, rfc-graph, CONTRIBUTING) so the README can stay focused on the landing-page experience and link out for depth. - Restructure the README quick-start around the Claude Code plugin path; demote SensorHub and "Missing a sensor?" to H3 subsections under Sensors; thin the hero-area horizontal rules. - Remove all `w2a` CLI pseudo-commands across docs and README — only capabilities that work today are described. - Align build-w2a-sensor skill with the protocol: mandatory npm keywords for `npm search w2a-sensor` / SensorHub discovery, `source_event.schema` property descriptions as best practice, `event.type` `domain` is the abstract source space (not the platform name), action verbs in past tense. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
sami-mp-ai
changed the title
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| <!-- Concept Video --> | ||
| <p align="center"> | ||
| <a href="[YOUTUBE_VIDEO_LINK]"> |
There was a problem hiding this comment.
Unfilled placeholder links and missing asset — [YOUTUBE_VIDEO_LINK] is a raw placeholder that will render as a broken link on GitHub. The image at ./assets/video-thumbnail.png (line 24) also references a directory that does not exist in the repo, so it will display as a broken image. Either fill in the URL and add the asset before merging, or comment the entire block out (like the Star History chart below it) until both are ready.
未填占位符与缺失资源 — [YOUTUBE_VIDEO_LINK] 是未替换的占位符，在 GitHub 上会显示为失效链接。第 24 行的图片路径 ./assets/video-thumbnail.png 引用了仓库中不存在的目录，会显示为损坏图片。请在合并前填入真实 URL 并添加对应资源，或像下方 Star History 图表一样将整个块注释掉，待两者就绪后再启用。
| <a href="https://machinepulse.ai">Website</a> · | ||
| <a href="#quick-start">Quick Start</a> · | ||
| <a href="#sensors">Sensors</a> · | ||
| <a href="#sensorhub">SensorHub</a> · |
There was a problem hiding this comment.
Nav anchor targets an H3, not the section heading — #sensorhub resolves to the H3 ### SensorHub nested under ## Sensors. The nav bar likely intends to jump users to ## Sensors; if so, change this to <a href="#sensors">SensorHub</a>.
导航锚点指向 H3 而非节标题 — #sensorhub 解析到的是嵌套在 ## Sensors 下的三级标题 ### SensorHub。导航栏的本意可能是跳转到 ## Sensors 节，若如此，应改为 <a href="#sensors">SensorHub</a>。
|
|
||
| ## Community | ||
|
|
||
| [Website](https://machinepulse.ai/) · [Discord]([DISCORD_LINK]) · [X / Twitter](https://x.com/machinepulse) · [YouTube]([YOUTUBE_LINK]) |
There was a problem hiding this comment.
Unfilled placeholder links — [DISCORD_LINK] and [YOUTUBE_LINK] are raw bracket placeholders that will render as broken href attributes. Fill these in or remove them before merging.
未填占位符链接 — [DISCORD_LINK] 和 [YOUTUBE_LINK] 是未替换的原始占位符，会渲染为含有失效 href 属性的字面文本。请在合并前填入真实链接或将其删除。
| // Your agent logic here | ||
| }); | ||
|
|
||
| handler.on("repo.repo.starred", async (signal) => { |
There was a problem hiding this comment.
repo.repo.starred violates the domain.entity.action schema — the domain (repo) is repeated as the entity, yielding a nonsensical triple. The entity slot should name the thing that changed, not the domain again. A more correct form would be repo.star.added (entity = star, action = past-tense verb) or repo.stargazer.added. The same error appears in docs/signal-format.md line 116.
repo.repo.starred 违反了 domain.entity.action 规范 — domain (repo) 在 entity 位置被重复使用，产生了无意义的三元组。entity 槽应填写发生变化的事物，而非重复 domain。更正确的形式应为 repo.star.added（entity = star，action = 过去式动词）或 repo.stargazer.added。同样的错误出现在 docs/signal-format.md 第 116 行。
| // 2. Register listeners for each event type you care about | ||
| // `domain` is the abstract source space (`repo`), not the platform name — | ||
| // the platform identity is in `signal.source.source_type`. | ||
| handler.on("repo.trending.entered", async (signal) => { |
There was a problem hiding this comment.
repo.trending.entered is inconsistent with the skill's own convention — SKILL.md line 49 gives trending -> trending_entered as the recommended fix (underscore-joined compound). The docs use trending.entered (dot-separated), placing entered in the action slot with trending as entity. The entity trending is also a gerund, not a clear noun. The skill and docs should agree on the same convention.
repo.trending.entered 与技能自身的规范不一致 — SKILL.md 第 49 行给出的推荐修正是 trending -> trending_entered（下划线连接的复合形式）。但文档使用 trending.entered（点分隔形式），将 entered 放在 action 槽、trending 作为 entity。entity 槽的 trending 也是动名词，不是清晰的名词实体。技能文件与文档应就同一规范达成一致。
|
|
||
| Open namespace — sensors coin their own triples. Consumers pattern-match on this string, so the triples a sensor emits are part of its public contract; treat them as you would a public API. | ||
|
|
||
| `domain` is the **abstract source space** (`messaging`, `repo`, `market`, `calendar`), not the platform name. The platform identity already lives in `source.source_type` — keeping the two orthogonal is what lets one handler match the same semantic event across platforms: `handler.on("messaging.message.mentioned")` catches Slack, Discord, Lark, and Teams alike. A sensor for GitHub stars emits `repo.repo.starred` (with `source.source_type: "github"`), not `github.repo.starred`. |
There was a problem hiding this comment.
repo.repo.starred used as a canonical example but violates the schema — this sentence gives repo.repo.starred as the example for a GitHub stars sensor, but that repeats repo as both domain and entity, directly contradicting the domain.entity.action rule. Consider replacing with repo.star.added (entity = the star object, action = past-tense verb).
repo.repo.starred 作为典型示例但违反了规范 — 此处以 repo.repo.starred 为例说明 GitHub stars 传感器的事件类型，但 repo 同时出现在 domain 和 entity 位置，与 domain.entity.action 规则直接矛盾。建议替换为格式正确的三元组，例如 repo.star.added（entity = star 对象，action = 过去式动词）。
| - ✅ `"llm-agents/perception gained 523 stars in 24h and hit #3 on Trending; relevant to your active research thread"` | ||
| - ❌ `"new event"` / `"PR update"` / `"price moved"` — vague, reject and rewrite. | ||
|
|
||
| `event.type` follows `domain.entity.action`: |
There was a problem hiding this comment.
The action past-tense rule is not documented here — the schema TypeScript and SKILL.md both specify that action must be a past-tense verb (created, updated, not create, creating, or trending). This rule is absent from this document, the primary reference for sensor authors. Please add a note such as: action must be a past-tense verb (e.g. created, threshold_crossed).
action 过去式规则在此处未作说明 — schema TypeScript 和 SKILL.md 均明确规定 action 必须是过去式动词（如 created、updated，而非 create、creating 或 trending）。但该规则在本文档（传感器作者的首要参考）中并未提及。请在此处补充说明：action 必须是过去式动词（如 created、threshold_crossed）。
| Install any sensor by package name: | ||
|
|
||
| ```bash | ||
| npm install {PackageName} |
There was a problem hiding this comment.
{PackageName} is an unfilled template placeholder — users who copy-paste this command will get an npm error. Replace with a concrete example (e.g. npm install @world2agent/sensor-hackernews) or use the conventional angle-bracket style (npm install <package-name>) to signal substitution clearly.
{PackageName} 是未填写的模板占位符 — 用户复制粘贴此命令后会遇到 npm 报错。请替换为具体示例（如 npm install @world2agent/sensor-hackernews），或采用惯用的尖括号占位符风格（npm install <package-name>）以明确提示该处需要替换。
|
|
||
| | Field | Source | | ||
| |-------|--------| | ||
| | npm package name | Developer submits | |
There was a problem hiding this comment.
Developer submits rows lack a submission mechanism — these rows claim fields are developer-submitted, but nowhere in this document is there a link, form, or API explaining how to submit them. If SensorHub auto-indexes from npm keywords, the label is wrong. If there is a manual step, describe it or link to it. This also conflicts with line 6's claim that there is no separate publish step.
Developer submits 行缺少提交机制说明 — 这些表格行声称相关字段由开发者提交，但文档中没有任何链接、表单或 API 说明如何提交。若 SensorHub 从 npm 关键字自动索引，则该标注有误；若存在手动步骤，则需补充说明或提供链接。这与第 6 行所说的无需单独发布步骤也存在矛盾。
| SensorHub is a discovery layer on top of npm. Every sensor is a standard npm package — SensorHub makes them easier to find. | ||
|
|
||
| ``` | ||
| Developer builds sensor → npm publish → submit to SensorHub |
There was a problem hiding this comment.
Diagram contradicts sensorhub.md and the README — this shows npm publish -> submit to SensorHub implying a separate manual submission step. But sensorhub.md line 6 says there is no separate publish step, and the README says SensorHub auto-indexes after npm publish. The two documents should agree on whether a manual SensorHub submission is required.
此图与 sensorhub.md 及 README 存在矛盾 — 图中显示 npm publish -> submit to SensorHub，暗示需要单独的手动提交步骤。但 sensorhub.md 第 6 行写道无需单独发布步骤，README 也说 npm publish 后 SensorHub 会自动索引。两份文档应就是否需要手动提交 SensorHub 达成一致。
This comment has been minimized.
This comment has been minimized.
…flow
- README: point Website to world2agent.ai and SensorHub to /hub
- sensorhub.md: replace `{PackageName}` with `<package-name>`, document
the manual SensorHub submission step (no auto-crawl from npm today)
- quick-start.md, signal-format.md: rename `repo.repo.starred` to
`repo.star.added` to satisfy `domain.entity.action`
- signal-format.md: surface the past-tense `action` rule from schema.ts
- SKILL.md: drop the `trending` example to align with quick-start's
`repo.trending.entered`
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
| <a href="https://world2agent.ai/assets/promo-w2a.mp4"> | ||
| Watch the W2A Concept Video | ||
| </p> |
There was a problem hiding this comment.
Unclosed <a> tag — missing </a> before </p>.
</a> 标签未关闭 — 在 </p> 之前缺少 </a>。
The <a> opened on line 23 is never closed. While browsers may forgive this, it is invalid HTML and can cause rendering issues downstream (e.g. the entire rest of the page becoming a link).
第 23 行打开的 <a> 标签始终未关闭。虽然浏览器可能容忍此问题，但这是无效 HTML，可能导致后续渲染异常（例如页面其余内容全部变为链接）。
| <a href="https://world2agent.ai/assets/promo-w2a.mp4"> | |
| Watch the W2A Concept Video | |
| </p> | |
| <a href="https://world2agent.ai/assets/promo-w2a.mp4"> | |
| Watch the W2A Concept Video | |
| </a> | |
| </p> |
Code Review — Incremental Push1 new issue found; several prior issues fixed in this push. Fixed in this push (previously open threads):
New issue (introduced in this push):
Still open (unchanged in this push):
|
Drop the Discord placeholder, set Twitter to @Karpo_AI, and point YouTube at the actual channel URL. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 participants
Summary
/docs/(signal format, architecture, quick-start, build-a-sensor, multi-sensor, sensorhub, why-w2a, rfc-graph, CONTRIBUTING) so the README can stay focused on the landing-page experience and link out for depth.w2aCLI pseudo-commands from docs and README — only capabilities that work today (npm publish,npm search w2a-sensor, plugin commands) are documented.build-w2a-sensorskill with the protocol:keywordsblock in the generatedpackage.json(world2agent,w2a,w2a-sensor,sensor,agent,<source_type>) sonpm search w2a-sensoractually surfaces sensors built with the skill.source_event.schemaproperty descriptions promoted to a SHOULD best practice; example payloads now carrydescriptionon every property.event.typedomainis documented as the abstract source space (messaging,repo,market,news,tasks), not the platform name — the platform identity already lives insource.source_type. All examples across docs and skill are updated accordingly (github.repo.trending→repo.trending.entered,slack.message.mentioned→messaging.message.mentioned, etc.).actionmust be a verb in past tense, not a gerund.Test plan
/docs/*.mdandREADME.mdresolve on GitHubbuild-w2a-sensorskill and confirm the generatedpackage.jsoncarries the expected keywordsevent.typeexample across docs and skill uses an abstract domain (no platform names)w2aCLI pseudo-commands (w2a publish,w2a search,w2a add,npm init w2a-sensor)🤖 Generated with Claude Code