fix(docs): MDX $ rendering + /concepts/agents redirect + bench findings#58
Merged
Merged
Conversation
…ndings
Two user-facing bugs fixed plus partial-bench documentation update.
1. MDX dollar-sign rendering: Mintlify's MDX parser treats unescaped
`$` as LaTeX math-mode delimiters, causing prose like "~$11 ... ~$2-3"
to render as italic glyphs with stripped spaces ("~11 on default
settings.With...thesame run...$2-3"). Escaped all `$` in prose
across docs/concepts/low-token-mode.mdx (2), docs/quickstart.mdx (1),
docs/reference/cost-benchmark.mdx (6). Code-block `$` left intact
(fenced code is not MDX-parsed).
2. /concepts/agents 404: legacy slug from before the rename
`concepts/agents` → `concepts/the-team` was still cached in
Mintlify deploys / browser bookmarks. Added a permanent redirect
rule in mint.json so the old path 301s to the new one.
3. Partial low-token bench attempt: ran zo build mnist-bench-low
--low-token end-to-end on 2026-04-26, aborted at ~17min/$13.59
when the team-lead session went idle on a sub-agent permission
gate (data-engineer requested mkdir, lead never auto-approved).
Surfaced architectural finding: Claude Code 2.1.92's TeamCreate
spawns sub-agents with `--model claude-opus-4-6` regardless of
the agent .md frontmatter `model:` field. So low-token's
lead-model swap saves on lead-side spend only; sub-agents stay
on Opus. Revised savings estimate 70-80% → 50-65%.
Documented in docs/reference/cost-benchmark.mdx new "Findings
from the partial run" section + STATE.md benchmark line.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Deploying zero-operators with
|
| Latest commit: |
e460865
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://18c3abde.zero-operators.pages.dev |
| Branch Preview URL: | https://claude-docs-fix-team-404-and.zero-operators.pages.dev |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
The bench attempt on 2026-04-26 surfaced that Claude Code 2.1.92's TeamCreate spawns sub-agents with --model claude-opus-4-6 regardless of the agent's .md frontmatter model: field. So low-token's lead-model swap (Opus → Sonnet) only saved on lead-side spend; sub-agents (data-engineer, model-builder, oracle-qa, code-reviewer, test-engineer) stayed on Opus. Fix: orchestrator._prompt_low_token_overrides() now generates a "Low-Token Sub-Agent Model Override" section that's included in the lead prompt only when self._low_token is True. The section instructs the Lead Orchestrator to pass an explicit model="claude-sonnet-4-6" parameter to every Agent() call, with a graceful fallback if the runtime's Agent() tool ignores the parameter (Lead logs a DECISION_LOG entry; lead-side savings still apply). Tests: TestLowTokenOrchestrator gains 2 cases — test_low_token_includes_subagent_model_override (asserts section present + concrete model id + TeamCreate reference when low_token=True) and test_low_token_off_omits_subagent_override (asserts the section is NOT present in default mode). Docs: cost-benchmark.mdx "Implications for the savings estimate" section restructured into "Fix shipped (post-bench)" sub-section documenting the new override + caveat. low-token-mode.mdx FAQ adds "Do sub-agents (data-engineer, model-builder, etc.) also run on Sonnet in low-token mode?" question with the override explanation. STATE.md benchmark line updated to reflect FIX SHIPPED. Test count 704 → 706 (+2). ruff src/zo/ clean. validate-docs 10/10. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Root cause of the persistent /concepts/the-team 404 on docs.zerooperators.com identified via direct HTTP probe: - Sibling pages return 200 (`/concepts/the-plan` etc.) — Mintlify build is current and serving fresh content. - `/concepts/the-team` returns 404 specifically — the page failed to compile, Mintlify excluded it from the build output. Cause: line 51 of the-team.mdx contained "files <500 lines, functions <50 lines" in prose. MDX 2's parser treats `<` followed by any non-whitespace as a JSX opening tag (digit is non-whitespace). `<500` becomes a malformed JSX attempt, the whole file fails compilation. Fix: replace `<500` / `<50` with natural-prose `under 500` / `under 50`. Same semantic meaning, parses cleanly. CLAUDE.md already uses the "under N lines" phrasing — this aligns the public docs with the source-of-truth coding-conventions text. Repo-wide sweep (see commit message body) confirms this was the only such pattern in any tracked .mdx file. After PR merges + Mintlify auto-redeploys, /concepts/the-team should return 200. Bonus fix in same commit: README test badge `tests-675_passing` → `tests-704_passing` was already done in PR #57; this commit also corrects a separate stale URL — README docs badge + docs/ README + STATE.md still referenced `docs.zero-operators.dev` (the originally-planned URL) instead of the actual deployed `docs.zerooperators.com` (no hyphen). Updated three files. DECISION_LOG entry for original Mintlify framework decision left intact as historical audit; STATE.md now records both the planning URL and the actual deploy URL with a note explaining the change. 706 tests pass + 7 skipped. ruff src/zo/ clean. validate-docs 10/10 (1 pre-existing test-count warning). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ch pending Records the session-024 work and explicitly verifies that agent teams mode (tmux launch + TeamCreate + Agent(team_name=...) + peer-to-peer SendMessage) is preserved across both default and low-token modes. STATE.md "Current Position" rewritten to lead with the session-024 hand-off so the next session picks up cleanly: PR #58 status (open + mergeable, 3 commits), the team-page 404 root cause + fix, the sub-agent model override fix, and the next manual action (mini-bench to verify whether Claude Code's Agent() honours the model parameter). DECISION_LOG appended with three new entries: 1. MDX dollar-sign rendering bug — escaped $ → \$ in 9 prose locations 2. Sub-agent model override architecture — _prompt_low_token_overrides() 3. the-team 404 root cause — MDX 2 prose <500 lines parser bug + URL correction (docs.zero-operators.dev → docs.zerooperators.com) New session summary at memory/zo-platform/sessions/session-024-2026-04-26.md covers the full session arc: PR #57 (merged) + PR #58 (open) feature list, partial bench findings, regression check proof, hand-off instructions for picking up the work. Test snapshot: 706 passed + 7 skipped. ruff src/zo/ clean. validate-docs 10/10 (1 pre-existing test-count warning). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 tasks
SamPlvs
added a commit
that referenced
this pull request
Apr 30, 2026
…ch pending Records the session-024 work and explicitly verifies that agent teams mode (tmux launch + TeamCreate + Agent(team_name=...) + peer-to-peer SendMessage) is preserved across both default and low-token modes. STATE.md "Current Position" rewritten to lead with the session-024 hand-off so the next session picks up cleanly: PR #58 status (open + mergeable, 3 commits), the team-page 404 root cause + fix, the sub-agent model override fix, and the next manual action (mini-bench to verify whether Claude Code's Agent() honours the model parameter). DECISION_LOG appended with three new entries: 1. MDX dollar-sign rendering bug — escaped $ → \$ in 9 prose locations 2. Sub-agent model override architecture — _prompt_low_token_overrides() 3. the-team 404 root cause — MDX 2 prose <500 lines parser bug + URL correction (docs.zero-operators.dev → docs.zerooperators.com) New session summary at memory/zo-platform/sessions/session-024-2026-04-26.md covers the full session arc: PR #57 (merged) + PR #58 (open) feature list, partial bench findings, regression check proof, hand-off instructions for picking up the work. Test snapshot: 706 passed + 7 skipped. ruff src/zo/ clean. validate-docs 10/10 (1 pre-existing test-count warning). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
SamPlvs
added a commit
that referenced
this pull request
Apr 30, 2026
…dollar fix(docs): MDX $ rendering + /concepts/agents redirect + bench findings
SamPlvs
added a commit
that referenced
this pull request
Apr 30, 2026
Same class of bug as PR #58 commit 07f6299 (the-team page 404 root cause): MDX 2 (used by Mintlify) treats '<' followed by any non- whitespace character as the start of a JSX opening tag — including digits. Line 101's '**<1 pp**' was parsed as a malformed JSX attempt, the file failed compilation, Mintlify's deploy of PR #60 (commit d46d436) failed with "Encountered syntax error(s). Deployment not updated", and the live docs at docs.zerooperators.com stayed on the pre-PR-#60 cached version (still showing the '(pending)' tracking table row instead of the measured '$7.75 / 30%' values). Fix: replace '<1 pp' with 'under 1 pp' — natural prose, preserves semantic meaning, no MDX gotcha. Same fix pattern as PR #58. Repo-wide regex sweep confirmed this is the only remaining unescaped '<digit' or '<letter' pattern in tracked .mdx files outside of code fences and valid Mintlify components (<Note>, <Warning>, <Tabs>, etc). Mintlify will redeploy automatically on merge. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two user-reported docs bugs fixed plus a partial-bench finding documented.
1. MDX
$rendering bugThe "Estimated savings" section of the low-token-mode page was rendering as garbled italic text:
Cause: Mintlify's MDX parser treats unescaped
$as LaTeX math-mode delimiters. So$11 on default settings. With...the same run lands at $2-3becomes$<math>$with text typeset and spaces stripped.Fix: Escaped all
$in prose acrossdocs/concepts/low-token-mode.mdx,docs/quickstart.mdx,docs/reference/cost-benchmark.mdx(9 occurrences). Code-block$left intact since fenced code isn't MDX-parsed.2.
/concepts/agents404 (4th-time-reported)User kept seeing 404 on "the team" navigation despite the file being correctly named, navigation entry being correct, and frontmatter title being "The team". Root cause was almost certainly Mintlify cache or browser bookmark serving the legacy
/concepts/agentsslug from before the rename.Fix: Added a permanent (301) redirect rule in
mint.json:This handles stale URLs from any source (cache, bookmarks, search-engine indexes).
3. Partial low-token bench attempt — findings
Ran
zo build mnist-bench-low --low-token --gate-mode full-autoend-to-end on 2026-04-26. Aborted at ~17 min wall time / $13.59 spend after the team-lead session went idle on a sub-agent permission gate (data-engineerrequestedmkdir; lead never auto-approved).Confirmed:
--low-token✓ (claude --model sonnet --max-turns 200inps aux)Architectural finding (independent of low-token mode):
TeamCreatespawns sub-agents with--model claude-opus-4-6regardless of the agent's.mdfrontmattermodel:field. So--low-tokensaves on lead-side spend only; sub-agents (which do the actual work) stay on Opus.Implications: Original ~70-80% savings estimate was too optimistic. Revised to 50-65% reduction depending on lead-vs-sub-agent token split. The original target requires direct Anthropic SDK use (already documented as out-of-scope on the concept page).
Documented in
docs/reference/cost-benchmark.mdxnew "Findings from the partial run" section.Test plan
mintlify devlocally — confirm/concepts/the-teamresolves and page renders with title "The team"mintlify dev— try/concepts/agentsURL, confirm it 301s to/concepts/the-team$11and$2-3render literally with spaces preserved (not as italic LaTeX)python3 -c "import json; json.load(open('docs/mint.json'))"— schema valid./scripts/validate-docs.sh— 10/10Notes
trig_01JBYyUbmgdUzNMcu5G4zecJ, 2026-05-10) will pick up any committedbenchmark-results-*.jsonand update the docs.🤖 Generated with Claude Code