docs(agents): record W&B product and platform facts for style passes

[johndmulhausen]

Summary

The style-guide skill now reads AGENTS.md as a Pass 0 pre-flight for the product and platform facts it can't infer — product and package names, what a directory's content actually is, UI surface names, and which paths hold generated content. Across 27 style PRs, reviewers enforced these facts about ~400 times in line comments, but none of them were written down anywhere, so every style pass guessed, got corrected, and the next pass guessed again. This records the ones that are settled and substantiated.

Prose and style rules were deliberately not added here. Voice, grammar, punctuation, list and heading form, link form, placeholder form, section naming, and word choice are universal — they must read the same in every docs repo, and they live in the skill. A per-repo prose override would make successive runs oscillate. The Deliberately not added section below lists the candidates rejected on that basis, so you can see the boundary was applied on purpose. This PR also respects the delegation-shell architecture from #2735: no inline style rules come back.

What's recorded

All seven additions go into the existing W&B-specific conventions not in the skill list.

Fact	Evidence
W&B Python SDK — wandb is the W&B Python SDK; full form "the W&B Python SDK (wandb)", short form "the wandb library"	#2673 (@ngrayluna): "Would prefer if, on the first mention, call out that wandb is the W&B Python SDK." Applied.
Weave UI labels — 17 names keep UI casing when they label a tab, view, page, table, or panel; lowercase as ordinary nouns	#2739 theme A (@dbrian57, @anastasiaguspan independently, applied verbatim) established that these are capitalized as UI labels. Scoped to label position by corpus census — see Verification.
Project navigation — the project sidebar (Weave project sidebar in Weave docs), not "left sidebar" / "sidebar menu" / "left navigation"	#2739 theme J (@anastasiaguspan: "In the Weave project sidebar, select Threads"); #2668 — four suggestions replacing "left sidebar" with "project sidebar", all committed by the reviewer.
Sweeps — W&B Sweeps is the product, an individual one is "a sweep"	#2727 (@mdlinville, models/sweeps/initialize-sweeps.mdx): "I don't think 'a W&B sweep' is a thing. W&B Sweeps is the product and a sweep is what it manages." Author applied it across all reviewed files.
Generated content — pointer to README.md's table, plus snippets/_includes/code-examples/, snippets/CodeSnippet.jsx, and takeru-marked tables; weave/cookbooks/ notebook sources	Pass 0 asks AGENTS.md which directories hold generated content. It recorded none, and AGENTS.md doesn't reference README.md — so a pre-flight that reads "AGENTS.md plus any convention docs it references" never saw that table.

Note on a sibling file

I only edited AGENTS.md, per scope. Two things belong in files I didn't touch:

• README.md's "What files do I edit?" table lists /ref/python/ and /weave/api-reference/, neither of which exists in the tree — that row set looks stale. I added a cross-reference to the table rather than copying it, so the two files can't drift apart, but the table itself needs an owner's pass.
• .github/CODEOWNERS is a single catch-all line (* @wandb/docs-team). That's relevant to the first open question below.

Deliberately not added (universal prose rules)

Each of these was enforced by a wandb reviewer, and each reads identically in any docs repo with different nouns — so it belongs in the skill, not here. Several are already there verbatim.

Rejected candidate	Where it lives
W&B is the actor, not wandb (product performs actions, package doesn't)	3-language-pass.md — which already uses wandb as its own example — and 4-terminology-pass.md
Keep product-noun casing in headings, frontmatter description, and alt text; leave code identifiers alone	4-terminology-pass.md; 7-polish-pass.md
Don't normalize a convention the corpus contradicts itself on	SKILL.md "When to stop and ask"
Don't introduce a callout component the docset doesn't already use	SKILL.md, 1-context-pass.md, 2-structure-pass.md, 8-audit-pass.md (four places)
Don't add keywords as a side effect of another change	0-guardrails.md: "Never add or remove frontmatter fields."
Stop and ask before restyling security, compliance, data-handling, or legal-sensitive wording	SKILL.md "When to stop and ask"
Don't hand-edit generated files; fix them upstream	0-guardrails.md "Hard exclusion zones"
"Jupyter Notebooks" on first mention, short form after	3-language-pass.md (first-use expansion). Also unsubstantiated: corpus prefers lowercase "Jupyter notebook" 35 to 18.
"previous", not "preceding"	4-terminology-pass.md word list. Cited as a team decision by two reviewers (#2673, #2684) — still a universal word-choice rule.
No semicolons in prose	6-formatting-pass.md. Raised on #2724.
"might" for possibility, "may" for permission	4-terminology-pass.md. #2739 theme M.
Avoid "via" and other Latinisms for an ESL audience	4-terminology-pass.md. Raised on #2673.
Bold **Term**: lead-ins on definition lists	6-formatting-pass.md. 10 instances in #2739 theme D.
Absolute internal links, no trailing slash	7-polish-pass.md. #2687: "I wonder if the docs skill can be augmented to fix this" — exactly right, and that's where it went.
Link text names the destination; one link per destination per page	7-polish-pass.md. #2739 theme I, #2727 P1/P2.
Avoid gerund-subject preambles	1-context-pass.md, 3-language-pass.md. Named twice on #2679.
Recommendation voice	SKILL.md: "One voice for recommendations: 'we recommend.'" See open questions.
Placeholder token form	6-formatting-pass.md. See open questions — genuinely contested here.
Keyword selection guidance	Owned by the separate keywords skill.

Open questions for the team

Nothing below is recorded in AGENTS.md. A wrong rule in that file is worse than a missing one, since every agent session reads it.

1. What is the web app called? Highest-value question here.

• "W&B": docs: refer to the web app as "W&B" instead of "W&B App" #2737 (open, 85 files) proposes retiring "W&B App", opened as follow-up to style: apply /style-guide pass to models/integrations #2673 where @ngrayluna wrote "Did Matt say something about no longer refer to the W&B App as 'W&B App'? I think it has a formal name now."
• "W&B App": @mdlinville on style: apply /style-guide pass to models/reports #2723 — "I believe we used to just say 'W&B App' without 'UI'. Did we change our minds?" — and the skill's "W&B App UI" was reverted on that basis. Separately @mdlinville noted "W&B UI" was in use to avoid confusion with the iOS app.
• Heads-up: docs: refer to the web app as "W&B" instead of "W&B App" #2737's premise is inaccurate. It cites AGENTS.md as saying the platform is "W&B"; the file says no such thing, before or after this PR. Its only mentions are incidental lowercase "the W&B app".
• Corpus today: "W&B App" 266, "App UI" 72, "W&B App UI" 48, "the W&B app" 21. Meanwhile style: apply /style-guide pass to weave #2739 unified 12 <Tab title> labels to "App UI" and that merged.
• Recommendation: rule before docs: refer to the web app as "W&B" instead of "W&B App" #2737 or any further style pass touches these strings, then record the winner here.

2. keywords: — keep or remove? Nothing about keywords is recorded in this PR.

• Remove: @ngrayluna, style: apply /style-guide pass to models/integrations #2673 ("The ones purposed are random", 52 pages), then backed out of style: apply /style-guide pass to models/sweeps #2722 and style: apply /style-guide pass to models/reports #2723 with commit messages about "restoring the description/title-only frontmatter".
• Keep: @mdlinville 👍'd a keywords hunk on style: apply /style-guide pass to models/automations #2684; merged style: add frontmatter keywords to platform pages #2680 (83 platform pages) and WEAVE: Adds keywords frontmatter to prompt versioning doc #2774 add them on purpose; style: apply /style-guide pass to weave #2739 added them to 103 of 141 files with zero objections.
• Note: an earlier draft recorded "don't add keywords as a side effect" as agreed by both camps. It isn't — style: apply /style-guide pass to models/automations #2684's 👍 was on an add, and style: apply /style-guide pass to weave #2739's 103-file add merged unopposed. That narrow rule is in any case covered universally by the skill's guardrail against adding frontmatter fields, so nothing is lost by leaving the question open here.
• Recommendation: one ruling, then either delete the field repo-wide or give it an owner.

3. Recommendation voice: "we recommend" vs "W&B recommends"?

• The skill sets this universally to "we recommend", and style: apply /style-guide pass to weave #2739 shows two independent Weave reviewers reverting the skill's "W&B recommends" back (@anastasiaguspan on view-agent-signals.mdx, @dbrian57 on evaluation_logger.mdx).
• But @ngrayluna raised the opposite preference on style: apply /style-guide pass to models/registry #2721 (open), and this corpus runs the other way: "W&B recommends" 72 vs "we recommend" 16.
• Recommendation: confirm or change the skill's cross-repo setting. Please don't ask for a local AGENTS.md override — that's what makes successive runs oscillate.

4. "This page shows you how to…"

• Against: @ngrayluna on style: apply /style-guide pass to models/integrations #2673 (twice) and style: apply /style-guide pass to sandboxes #2668 — "I was taught to avoid using 'This page shows you...'".
• For: @mdlinville authored it in a style: apply /style-guide pass to models/sweeps #2722 suggestion and reused it in style: apply /style-guide pass to models/runs #2724; defended in style: apply /style-guide pass to models/track #2728.
• This is a prose question, so whichever way it lands, the decision belongs in the skill's context pass, not in AGENTS.md.

5. Casing of Weave domain objects in prose — Call, Op, Scorer, Model, Dataset, Evaluation, Thread, Signal, Agent, Trace.

• I recorded the UI-label rule only. The candidate list asked for these as proper nouns everywhere in prose, and the corpus won't carry it.
• Capitalize: style: apply /style-guide pass to weave #2739 theme A — 12 items, @dbrian57 and @anastasiaguspan independently, applied verbatim, including in frontmatter description (view-call.mdx:3) and alt text (view-call.mdx:138).
• Lowercase, per the docset: in weave/**/*.mdx prose with code, headings, links, and bold stripped — traces 33 cap / 432 low, calls 69/380, spans 7/127, prompts 4/113, models 29/195, datasets 4/57, evaluations 19/99, scorers 27/73, agents 45/114. Recording the candidate as written would have licensed a ~1,700-instance recapitalization on the strength of 12 comments.
• The docset already models the distinction, in weave/guides/tracking/view-agent-activity.mdx:18: "a row of tabs across the top: Dashboard, Agents, Conversations, Spans, and Signals. … the other tabs let you drill into individual agents, conversations, spans, and signals." Capitalized as labels, lowercase as nouns, one sentence apart.
• Recommendation: if you do want the object nouns capitalized, say so explicitly and scope the list — it's a large sweep and reviewers weren't self-consistent (@dbrian57 wrote "Weave Ops" then "Weave ops" one clause later in the same suggestion block).
• I excluded Evaluations and Ops from the recorded label list: "Compare evaluations view" is a distinct lowercase surface label (10 lowercase vs 4 capitalized in label position), and "Ops" has a single bold attestation.

6. Placeholder syntax: <your_api_key> or [YOUR-API-KEY]?

• Angle brackets: @ngrayluna, style: apply /style-guide pass to models/integrations #2673 — "For consistency, remove brackets. (Elsewhere in the docs we use open and close < and >)" — the skill's square brackets were reverted across every login block. Their objection on style: apply /style-guide pass to models/runs #2724 is substantive, not aesthetic: "Don't use square brackets since it looks like we expect a list as an input."
• Square brackets: @mdlinville, style: apply /style-guide pass to snippets/_includes #2736 — "I believe we are using square brackets for placeholders" — reverting <password> to [PASSWORD] hours after the author cited an angle-bracket convention in the same PR.
• Contested even within one reviewer: style: apply /style-guide pass to weave #2739 has @dbrian57 asking for [TEAM_NAME]/[PROJECT_NAME] on one page and [YOUR-TEAM]/[YOUR-PROJECT] on another, while @anastasiaguspan wants [YOUR-TEAM] uniformly. All three forms are in main.
• Placeholder form is a universal-domain rule, so the ruling belongs in the skill. Nothing recorded locally.

7. May weave/cookbooks/*.mdx be hand-edited, and what do those pages call themselves?

• README.md lists /weave/cookbooks/ as generated from wandb/weave ("Edit the code in the source repo, not in wandb/docs"), but the .ipynb sources are tracked in this repo at weave/cookbooks/source/, the Colab links point at wandb/docs, and no script in scripts/ or workflow in .github/workflows/ regenerates the .mdx. Practice contradicts the table: style: apply /style-guide pass to weave #2739 hand-edited 19 cookbook pages and @dbrian57 committed suggestions straight into them.
• The candidate asked to record that these pages call themselves "notebooks" and never "cookbook", "guide", "tutorial", or "demo" — 13 corrections by @dbrian57, the highest-frequency correction in style: apply /style-guide pass to weave #2739. I did not record it, because the merged corpus is split: self-references across those 19 pages run tutorial 21, notebook 20, guide 11, cookbook 5, demo 1. Intro_to_Weave_Hello_Trace.mdx:13 has both, reviewer-approved, in adjacent sentences: "This notebook shows you how to capture your first trace… This tutorial targets developers who are new to Weave."
• Recommendation: settle the generated question first. If the directory really is generated, the naming fix belongs upstream and style passes should skip it entirely; if not, fix README.md and then the "notebook" rule can be recorded here. "Cookbook" and "demo" look safe to retire either way.

8. Which pages are actually Eng/Legal-vetted? The candidate asked for a path list of vetted areas. I did not record one, because I couldn't substantiate it and a wrong no-touch zone over ~20 pages is exactly the kind of error that compounds.

• The only evidence is one hedged comment from @ngrayluna on style: apply /style-guide pass to models/runs #2724 (still open), on models/runs/delete-runs.mdx: "Future: don't touch docs that revolve around data, security, and/or other sensitive info since in all likelihood they … went under careful scrutiny from the Eng Team or Legal." No path list, and the one page it names is one the reviewer flagged as unvalidated ("Someone would need to verify this/approve the wording") and deleted.
• Any path list I could produce would come from a filename grep, not from a reviewer. platform/hosting/iam/sso.mdx — the largest candidate — is mostly third-party Azure and Okta click-through steps, not vetted compliance prose.
• The instruction to get "a reviewer from the owning team" also points at a mechanism that doesn't exist: .github/CODEOWNERS is one catch-all line.
• The general principle (stop and ask before restyling legally-sensitive wording) is already universal in the skill, so nothing is unprotected today.
• Recommendation: if specific areas are genuinely vetted, name them and name their reviewers — ideally in CODEOWNERS, where it's enforceable, and I'll mirror the list here.

9. Six live <Important> blocks probably aren't rendering. Same bug class as #2886. <Important> has no local definition in snippets/*.jsx and isn't registered in docs.json, so these bodies may be reaching nobody:

• platform/hosting/self-managed/operator.mdx:1833
• platform/hosting/iam/access-management/restricted-projects.mdx:69
• weave/guides/evaluation/scorers.mdx:403
• weave/guides/tracking/create-call.mdx:175
• weave/guides/tracking/update-call.mdx:131
• snippets/_includes/self-managed-mysql-eol-upgrade.mdx:1 (plus its ja/ko/fr copies)

Worth a screenshot check the way #2886 did. Not fixed here — this PR only touches AGENTS.md, and callout guidance has been removed from it at the maintainer's request.

Verification

Every recorded claim was checked against the tree at dfba8d0. Counts exclude localized content (ja/, ko/, fr/, and snippets/{ja,ko,fr}/); 1,533 English .mdx pages.

• Weave UI labels. Counted each name in three positions across weave/**/*.mdx: as a bold UI label, in surface-label position (name followed by tab/view/page/table/panel/column/button/section), and in generic prose with frontmatter, headings, fenced and inline code, links, and bold spans stripped. Bold-label usage is capitalized 100% of the time — lowercase count is 0 for all 19 names tested. That's the settled fact, and it's what the bullet records. Generic prose runs lowercase for 17 of 19, which is why the bullet explicitly says not to recapitalize there. Playground (50 cap / 3 low) is the one name capitalized in prose too; it's in the list either way.
• Project navigation. "project sidebar" 100 uses across 47 files vs. 41 for all competing forms ("left sidebar" 18, "left navigation"/"left nav" 12, "sidebar menu" 8, "navigation sidebar" 2, "left-hand sidebar" 1) — a clear majority, not a split. Per directory: models 67/6, weave 24/13, inference 4/0, platform 3/16. I then read all 16 platform hits individually, which is where the earlier draft went wrong: 6 of them are third-party consoles, not W&B team/org chrome — platform/hosting/iam/sso.mdx:144,158,176,190,194 are Microsoft Entra ID steps and platform/hosting/monitoring-usage/slack-alerts.mdx:33 is the Slack app config UI. A directory-scoped carve-out would have renamed those, and would have missed W&B non-project surfaces outside platform/ (models/runs/tags.mdx:93 "left sidebar of the Run page", models/track/project-page.mdx:378 org nav). So the exclusions are scoped by what the surface is, not by path. release-notes/ is excluded as dated historical content (4 competing hits).
• W&B Python SDK. "W&B Python SDK" 110 uses; the full form "the W&B Python SDK (wandb)" 11; "the wandb library" 47; "wandb SDK" 4. The short form in the bullet follows the corpus (47), not the skill's guess.
• Sweeps. "a W&B sweep" 4 uses, all in support/, 0 in the main docset, vs. "a sweep" 204 and "W&B Sweeps" 47 — roughly 50:1. The comment was pinned to fix: relocate Automations snippet includes and fix localized imports #2727 via the review-comments API. The anti-generalization clause is also counted: "a W&B run" 67, "a W&B artifact" 9, "a W&B report" 7 are live usage, so the rule is scoped to sweeps rather than swept across all three.
• Generated content. weave/cookbooks/: all 19 .mdx pages have a matching .ipynb under weave/cookbooks/source/ (29 tracked files there) and all 19 open with an interactive-notebook <Note> linking Colab and GitHub. takeru markers confirmed at inference/models.mdx:15,48,56, inference/lora.mdx:116, inference/lifecycle.mdx:36,49, inference/response-settings/reasoning.mdx:21, serverless-training/available-models.mdx:11. snippets/code-examples/README.md documents the wandb/docs-code-eval sync and calls snippets/CodeSnippet.jsx auto-generated; scripts/sync_code_examples.sh and the sync-code-examples workflow back it up. README.md's anchor #what-files-do-i-edit verified.
• Claims I dropped for lack of substantiation: the Eng/Legal path list (open question 8), the cookbooks self-naming rule (open question 7), the keywords no-add process claim (open question 2), and prose-wide Weave capitalization (open question 5).

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wandb	🟢 Ready	View Preview	Jul 29, 2026, 8:17 PM

[github-actions]

📚 Mintlify Preview Links

🔗 View Full Preview

📝 Changed (1 total)

⚙️ Other (1)

File
AGENTS.md

---

🤖 Generated automatically when Mintlify deployment succeeds
📍 Deployment: 95c7712 at 2026-07-29 20:18:25 UTC