[kittimzhe]

Fixes #1115

What

A team toolPaths entry replaces that tool's default whole, so naming a tool while omitting a key the default provides silently disables the surface behind the key — hooks skip the tool, no skills arrive — and nothing surfaced the drop. This adds one doctor note per affected tool naming every dropped key with its default path and what its absence does, plus the guide FAQ one-liner (keys you omit are gone, not inherited).

Why a note, not a finding

Omission is a documented opt-out (a team can disable a tool's rules by leaving the path out), so the surfaced information must not fail doctor for teams that opt out on purpose. The note names the mechanism and the exact keys; a failing check would make the opt-out permanently red.

Only keys the default table provides for that tool can be dropped — codex has no rules by design, so a codex entry without rules produces no note. Custom tools (no default entry) produce none. Nested userScope is skipped: the #938 finding already covers its observable case.

Verification

Real-CLI record on the seeded fixture (zcode entry with skills/rules but no settings/agents/mcp):

ℹ toolPaths.zcode replaces the tool's default entry whole and drops keys the default provides: `agents` (.zcode/agents — no agents are delivered to it), `settings` (.zcode/cli/config.json — hook reconciliation silently skips the tool), `mcp` (.agents/mcp.json — team MCP servers are not written to its user config). Add a key back to restore its surface, or leave it out on purpose.

Six red-first unit tests (naming + defaults + consequence, non-applicable keys, kept keys, custom tools, full restatement, no team config); full suite unchanged (the eight known local-env failures aside).

[github-actions]

• [P2 non-blocking] docs/guide/faq.md:85 — The new user-facing FAQ has no corresponding update in docs/guide/zh-CN/faq.md. The repository requires behavior documentation in both languages; add the equivalent Chinese entry.

The PR description includes a representative real-CLI verification record, satisfying the testing requirement. No confident runtime bugs found in the scoped diff.

[SaulMoro]

This was generated by AI during triage.

@kittimzhe Thanks. The zcode case works, but the note also fires for tools the team never named. We built this head and main (d60e68f5) and ran init, pull and doctor against a local team repo in an isolated HOME.

• Workspace scope, team toolPaths.zcode with only skills and rules: this head prints the zcode note from the PR body, word for word, and doctor keeps its exit code. main prints nothing.
• User scope, --agent claude,joycode, team teamai.yaml with no toolPaths at all: this head prints toolPaths.joycode replaces the tool's default entry whole and drops keys the default provides: `rules` (.joycode/rules — no rules are delivered to it). main prints nothing.

[P1 blocking] src/doctor-delivery.ts:260-287 compares ctx.toolPaths with DEFAULT_TOOL_PATHS. ctx.toolPaths is the scoped result from scopedToolPaths (src/doctor.ts:443-448): defaults merged in, then userScope applied in user scope, where joycode's rules: null (src/types.ts:2747-2748) removes rules. So every user-scope member with joycode enabled, or with no enabledAgents, gets a note blaming a team entry that does not exist. The note also tells them to add back a rules path joycode does not read in user scope. That contradicts the PR's "nested userScope is skipped". The unit tests don't catch it because ctxWith passes the team's toolPaths before scoping. Reading the declared entry, ctx.teamConfig?.toolPaths[tool], and skipping tools whose entry is still the default object would fix it. A user-scope test case would cover it.

[P2 non-blocking] The new FAQ entry has no counterpart in docs/guide/zh-CN/faq.md. The doc layout rule in AGENTS.md wants both. The note is self-explanatory, so dropping the FAQ entry also works.

[P3 nit] The two as unknown as casts in the new function go away with typed keys.

#1252 adds a line to the same notes list in src/doctor.ts. Expect a trivial rebase, nothing more. This PR owns the dropped-key note.

[kittimzhe]

P2 taken — the zh-CN counterpart is in (same Q, same placement before the Hooks entry). Pushed.

[github-actions]

No new findings in the scoped diff.

• Resolved: The earlier bilingual FAQ finding is fixed by the corresponding entry in docs/guide/zh-CN/faq.md:81.
• Testing: The PR description includes a representative real-CLI verification record, satisfying the testing requirement.
• No confident runtime bugs found. I only read the diff; I did not run, build, or install PR code.

[SaulMoro]

This was generated by AI during triage.

@kittimzhe This re-reviews cf52f755 against our comment at 515a18b3 (#1274 (review)). The Request changes stays.

Resolved

• [P2 non-blocking] zh-CN FAQ. docs/guide/zh-CN/faq.md now has the entry, and it matches the English one.

Still open

• [P1 blocking] User-scope false note. This commit only changes docs, so src/doctor-delivery.ts still compares the scoped ctx.toolPaths with DEFAULT_TOOL_PATHS. A user-scope member with joycode still gets a dropped-rules note for a team entry that doesn't exist. The fix suggested last time still applies: read the declared entry, ctx.teamConfig?.toolPaths[tool], and add a user-scope test case.
• The branch also conflicts with main in src/doctor.ts, after the #1221 locate changes. Please rebase onto current main.

[SaulMoro]

@kittimzhe To get this in sooner, we pushed two commits to your branch:

• 5cf71ff merges current main. The conflict in src/doctor.ts was the notes list that the [feat] One descriptor per tool, and one resolver for where teamai writes and where the tool reads #1221 locate work also extended, and both lines are kept.
• f512e85 fixes the user-scope false note from our review. toolPathsDroppedKeyNotes now reads the team's own teamConfig.toolPaths instead of the scoped toolPaths. A tool the team never names holds its default after parsing, so it drops nothing, and joycode's deliberate rules: null in user scope no longer shows up as a dropped key. A new test covers that case.

With the built CLI, your zcode case still prints its note, and a user-scope member with joycode and no team toolPaths gets none. We'll approve and merge once CI is green, so there's nothing left for you to do. Thanks a lot for the feature and for the quick zh-CN follow-up.

[SaulMoro]

This was generated by AI during triage.

Approving f512e85. The [P1 blocking] user-scope false note is fixed. A new unit test failed before the fix and passes after it, and with the built CLI a user-scope member with joycode and no team toolPaths gets no note, while the zcode case still prints it. The merge of main keeps both lines in src/doctor.ts. tsc, lint and the unit suite pass locally. We'll merge once CI is green.

[github-actions]

No new findings in the scoped diff.

• Resolved: The bilingual FAQ issue is fixed by the corresponding Chinese entry in docs/guide/zh-CN/faq.md:87.
• Testing: The PR description includes a representative real-CLI verification record, satisfying the testing requirement.
• No confident runtime bugs found. I only read the specified diff; I did not run, build, or install PR code.