Repository navigation
docs: repair the index and add subsystem guides - #1008
vernonstinebaker wants to merge 4 commits into
Conversation
The beginner's-guide landing pages shipped with two-letter prefixes on heading and list lines, so the public docs index did not render. Strip those prefixes and collapse the blank lines they left behind.
Publish English and Chinese pages for MCP, subagents, skills, voice, and hardware, and point the indexes at them. Move the stale integration planning notes into docs/archive. Slim CONTRIBUTING.md to the Zig 0.16.0 quick start; the validation matrix and hook steps stay in the development guides. The MCP page describes current main: with no tool_filter_groups, every tool is included. It does not document a lexical narrowing pass.
The skills page is introduced with the symlink fix. This index lists MCP, subagents, voice, and hardware.
DonPrus
left a comment
DonPrus
left a comment
There was a problem hiding this comment.
Reviewed all changed pages in both languages, local link targets, the archived-document references, the contributor-guide destination pages, and the relevant current implementation. Also read #776/#777 and their discussions: this intentionally ports and corrects that work rather than duplicating an already merged solution. The mangled index prefixes are gone, relative links in changed pages resolve, Zig remains 0.16.0, and the branch merges cleanly with current main. The MCP object maps and no-groups behavior now match the parser/agent implementation.
I am leaving this without approval because the new user-facing guides still advertise unavailable behavior:
-
Hardware commands/tools do not match the shipped surface (
docs/en/hardware.mdanddocs/zh/hardware.md).src/main.zig:runHardwareimplements scan, but flash and monitor only print “not yet implemented”; monitor does not invoke udevadm. Please label these as placeholders, rather than presenting working copy-paste commands/hotplug monitoring. The actual board-info tool name ishardware_board_info, nothardware_info(src/tools/hardware_info.zig). Also,allToolsregisters board-info, hardware-memory and I2C whenhardware_boardsis present, but does not register SPI. It would be great to distinguish available tools from standalone implementations and keep both translations aligned. -
The subagent guide conflates background execution with delegation and exposes internal APIs as user commands (
docs/en/subagents.md).src/tools/delegate.zigcallscompleteAgentPromptsynchronously; it does not spawn a SubagentManager task with a background tool loop. The spawn tool's JSON schema only accepts task/label/agent;getTaskStatus,getTaskResultandgetRunningCountare internal Zig methods, not operations users can invoke through that tool. Please describe delegate separately and replace the query examples with the supported/subagentscommands fromhandleSubagentsCommand(list/status/info; document the existing kill limitations accurately). The Chinese guide should retain the same distinction when expanded.
A smaller clarification: dynamic MCP groups are exposed through native tool schemas when keywords match; filterToolsForPromptText deliberately includes only built-ins and always groups. The guide currently reads as if dynamic tools are also injected into the text prompt for every backend.
Validation was source/config/workflow comparison, relative-link and leftover-prefix checks, and git diff --check; no application tests were needed for these documentation-only changes. The index repair and archive/contributor cleanup are useful and should be retained while correcting the new guides.
Addresses the accuracy findings on nullclaw#1008. Every claim below was verified against source rather than adjusted from the review text. ## hardware (en + zh) - `nullclaw hardware flash` and `nullclaw hardware monitor` are accepted but are placeholders. Both live in `runHardware` (`src/main.zig`) and only print a message; `monitor` does not invoke `udevadm` or watch for hotplug. The page presented both as working copy-paste commands and described real-time hotplug monitoring that does not exist. Now listed under an explicit "Not yet implemented" section with the current behavior and source location, and the intro no longer claims flashing works. - Agent tool name is `hardware_board_info`, not `hardware_info` (`src/tools/hardware_info.zig` sets `tool_name`; the filename is the source of the confusion). - `spi` was listed as an available agent tool. `allTools` registers `hardware_board_info`, `hardware_memory`, and `i2c` when `hardware_boards` is set (`src/tools/root.zig`); `src/tools/spi.zig` is importable but never registered, so it is documented as a library capability, not a shipped tool. ## subagents (en + zh) - The guide claimed `delegate` "spawns subagents internally". It does not: `src/tools/delegate.zig` calls `completeAgentPrompt` synchronously in the calling thread, creates no `SubagentManager` task, and issues no task ID. Documented as a separate synchronous path. - The Query section presented `getTaskStatus`, `getTaskResult`, and `getRunningCount` as callable "via the spawn tool or agent commands". They are internal methods on `SubagentManager` (`src/subagent.zig`) and are not invokable from a prompt, tool call, or slash command. Replaced with the supported `/subagents` surface (list/status/info/kill/help) and the `spawn` schema, which accepts only `task`, `label`, and `agent`. - The Chinese page is abbreviated and did not carry the false claims, but also lacked the distinction, so it gains the same `delegate` and query sections. ## mcp (en + zh) - `always` and `dynamic` groups were described as behaving the same way at different turn times. They are applied at two different stages: keyword matching for `dynamic` happens in `filterToolSpecsForTurn` (the native tool-schema path), while `filterToolsForPromptText` admits only built-ins and `always`-group tools. `dynamic` tools are never written into the prompt text. Added a table showing the split, plus the consequence that `dynamic` silently does nothing on providers without native tool schemas. Docs only. No code reference introduced here is unverified.
|
Both blocking findings are addressed in 1. Hardware commands vs. shipped surface
2. Subagents: delegation vs. background execution
3. MCP dynamic groups (the smaller clarification)Your read was right, and the split is sharper than the guide implied. Keyword matching for Unchanged
Docs only, no code touched. All anchors added resolve to headings on the same page. Ready for re-review. |
This branch has not been deployed
2 participants
Summary
docs/archive. SlimsCONTRIBUTING.mdto the Zig 0.16.0 quick start. The validation matrix and hook steps stay in the development guides.SECURITY.mdpoints at the security docs.tool_filter_groups, every tool is included. It does not describe a lexical narrowing pass.#776 and #777 are the older docs rewrites. This keeps Zig 0.16.0 and the filter behavior on main. Those pull requests can stay open until their author refreshes them.
Test plan
zig build test --summary allpassed on push (pre-push hook)docs/README.md,docs/en/README.md, anddocs/zh/README.mdrender headings and lists without the two-letter prefixesMade with Cursor