Repository navigation
docs/diagnostics: a named toolPaths entry replaces that tool's defaults whole, and nothing surfaces the dropped keys #1115
Description
Summary
A team teamai.yaml that sets toolPaths replaces the default table whole (the zod .default(...) on toolPaths in src/types.ts:399 only applies when the key is absent). Two consequences surprised me while verifying #1054, and neither surfaces anywhere a user would look:
- Customizing one tool drops the defaults for every other tool. A
toolPaths:section that only mentionszcoderemoves the built-inclaude,codex,cursor, … entries with it — skills/rules/settings resolution for those tools silently changes behavior. - Omitting one field of a customized tool silently disables that surface. Concretely: our verification teamai.yaml set
toolPaths.zcodewithskills/rulesbut nosettings, and the defaultsettings: .zcode/cli/config.jsonvanished with the table.teamai hooksthen reports the tool asno settings configuredand hook reconciliation silently skips it — no warning at pull time, nodoctorfinding (below).
Why this is discoverability, not a semantics bug
The code comments establish that whole-entry replacement is deliberate: doctor-delivery.ts:645 — "A team toolPaths entry replaces the default one whole" — and "One with no rules path delivers no rules to it on purpose". Omission-as-opt-out is a real feature (a team can disable a tool's rules/settings by leaving the path out), so changing to per-key merge would break teams that rely on it. The gap is that the trap end of that trade is invisible:
docs/guide/never documents the replace-whole rule —toolPathsappears only in FAQ asides (custom agents) and the team-culture path tables. Nothing tells a team writing a custom entry that they are now maintaining the whole table.teamai doctordiagnoses exactly one missing-path shape: the codex-familyclaudemd(doctor-delivery.ts:645-654). A customized tool missingsettings(hooks silently skipped) or missingskills/rules(delivery silently disabled) produces no finding.
Suggestions (any subset; happy to PR once a direction is picked)
- doctor finding: when a
toolPathsentry exists for a built-in tool and lacks a key the default table provides (settings,skills,rules, as applicable to that tool), report it with the replace-whole explanation and the exact key to add — mirroring the tone of the existing claudemd check. - One-line docs: a note in the guide where
toolPathsis first mentioned: a custom section replaces the defaults whole; to keep a built-in tool's other paths, copy them from the default table (src/types.ts) or list the paths you want teamai to manage. - Optionally, a pull-time hint (not a warning) the first time a partial table is detected, pointing at
teamai doctor.
Environment: teamai-cli@0.28.0-beta.0, git-backed team repo, toolPaths.zcode with skills/rules but no settings.
Activity
hongchuwudi commentedon Oct 14, 2026
Hi — first-time contributor here; this writeup is impressively precise.
I'd like to take the documentation slice: add a
toolPathssubsection todocs/guide/reference.md(under teamai.yaml) covering the replace-whole rule and the omission-as-opt-out behavior, plus a cross-link infaq.md— EN + zh-CN, docs-only diff. I'll leave thedoctorfinding for a follow-up PR unless someone picks it up first.If Kit or a maintainer is already on it, happy to stand down — otherwise I'll open the PR after a short nod here.
kittimzhe commentedon Oct 14, 2026
Go for it @hongchuwudi — the documentation slice is all yours. A few pointers from the verification sandbox that may save you a round-trip:
src/types.ts:399—toolPathsis az.record(...).default({...}), so the default table applies only when the key is absent entirely; anytoolPaths:section replaces the whole table (entries for every other tool included).doctor-delivery.ts"A teamtoolPathsentry replaces the default one whole" and "One with norulespath delivers no rules to it on purpose" — worth citing in the doc so readers see omission-as-opt-out is a feature, not a trap.settingskey surfaces inteamai hooksasno settings configured(hooks-cmd.ts) — a one-line cross-link from the FAQ's hooks entry may be the highest-value sentence.I'm not on the docs myself; the
doctorfinding stays open in this issue for whoever picks it up (happy to take it once the direction is blessed, or to review yours).akushonkamen commentedon Oct 14, 2026
Hi — picking up the doctor finding slice (suggestion 1) only. @hongchuwudi has the docs slice (suggestion 2), so no overlap there.
Re-confirmed the root cause on
origin/main@435b9f2:toolPathsisz.record(z.string(), ToolPathsSchema).default({ ... })(src/types.ts:433), so the default table applies only when the section is absent entirely, and every field ofToolPathsSchemais.optional()(src/types.ts:13-57) — a custom entry silently drops the surfaces it omits.Plan: a
teamai doctorcheck that fires when a built-in tool'stoolPathsentry is missing keys the default table provides (settings/skills/rules/claudemd/agents/mcp/mcpProject/userScope.*as applicable to that tool), carrying the replace-whole explanation and the exact keys to add — mirroring the tone of the existing codex-familyclaudemdfinding (src/doctor-delivery.ts:725). No merge-semantics change: omission stays the documented opt-out, the finding just makes the trade visible. Suggestion 3 (pull-time hint) stays untouched to keep the diff small.Transparency note: I'm using an AI coding assistant for this contribution.
jeff-r2026 commentedon Oct 14, 2026
Skip the docs. Don't change the replace-whole behavior.
When the team yaml sets
toolPathsand drops a built-in tool or key (for examplezcode.settings),teamai doctorandteamai pullshould say that surface is off, and to add it back only if they still want it. Informational only — don't fail the check.@hongchuwudi no docs change. @akushonkamen this covers doctor and the pull hint.
akushonkamen commentedon Oct 14, 2026
PR is up: #1119 — doctor-only completeness finding for partial
toolPathsentries (top-level +userScopesub-keys), no merge-semantics change. Full suite, typecheck and lint are green modulo the 3 known pre-existingmainfailures; details in the PR description.[-]docs/diagnostics: a custom toolPaths section replaces the default table whole, and nothing surfaces the dropped keys[/-][+]docs/diagnostics: a named toolPaths entry replaces that tool's defaults whole, and nothing surfaces the dropped keys[/+]SaulMoro commentedon Oct 21, 2026
Triage: still open. #1204 fixed the cross-tool half. The dropped-key half is ready for a contributor. Labels:
enhancement,help wanted.#1204 (merged) makes a
toolPathssection merge tool by tool (src/types.ts:734-736). A section that only nameszcodeno longer dropsclaude,codex, and the rest.Naming one tool still replaces that tool's entry whole. A
toolPaths.zcodewithskillsandrulesbut nosettingsstill drops.zcode/cli/config.json.teamai hookscan reportno settings configured, and pull does not say why.doctoronly reports a missingclaudemd(src/doctor-delivery.ts:793).Leaving a field out is still the opt-out. Do not switch that entry to a per-field merge.
What is left:
toolPathsis first explained: naming a tool replaces that tool's defaults, and other tools keep theirs.The title now describes that remaining gap. The old title said the whole table was replaced.
AGENTS.md ("Testing before a PR") requires one real-CLI record after
npm run buildfor the doctor finding. Use a team yaml that customizes one tool and omitssettings, then show thatteamai doctorreports that key.kittimzhe commentedon Oct 22, 2026
Claiming the dropped-key half — I filed this one during #1054 verification, and the triage direction is clear. Plan: a
doctorfinding that mirrors the claudemd check — when a teamtoolPathsentry exists for a built-in tool and omits a key the default table provides for it (settings/skills/rules, as applicable), report it with the replace-whole explanation and the exact key to add — plus the one-line docs note in the guide. Omission-as-opt-out stays untouched: the finding only fires when the default table provides the key and the entry drops it silently.docs(faq): add the zh-CN entry for dropped toolPaths keys (Tencent#1115)
feat(doctor): surface toolPaths keys a team entry drops (#1115) (#1274)