docs: agent-facing guides and README inventories cite ~20 symbols, files and workflows that no longer exist

[christian-byrne]

Audited every symbol, file path, API name, pnpm script and relative link cited by docs/ (excluding docs/architecture/ecs/, audited separately), AGENTS.md and every nested AGENTS.md, README.md files, and .agents/. 129 docs, read at origin/main @ 28bd73af29.

Most of the corpus is clean — the ADRs, the ECS architecture set, docs/guidance/*, the release process, the root AGENTS.md. The rot is concentrated in two shapes: agent-facing guides that quote helper APIs, and tables that claim to be an exhaustive inventory. Batched into one issue because it is one class with one root cause.

1. browser_tests/README.md — three dead APIs in the canonical E2E guide

This file is @-imported by browser_tests/AGENTS.md, so it auto-loads into every agent session working in that directory. All three of these are copy-pasteable snippets that do not compile.

browser_tests/README.md:539-540

`comfyPage.debugAddMarker(pos)`, `debugAttachScreenshot(testInfo, name)`,
`debugShowCanvasOverlay()`, `debugGetCanvasDataURL()` are for local debugging only.

None of the four exist. grep -rn 'debugAddMarker\|debugAttachScreenshot\|debugShowCanvasOverlay\|debugGetCanvasDataURL' browser_tests --include=*.ts → 0 hits. They were removed by #8510 (2026-02-03); this text was written 2026-07-22 in #13968.

browser_tests/README.md:557-559

import { createMockNodeDefinitions } from '@e2e/fixtures/data/nodeDefinitions'
const nodeDefs = createMockNodeDefinitions({ MyCustomNode: {/* ... */} })

Neither the module nor the export exists — there is no browser_tests/fixtures/data/nodeDefinitions.ts. Removed by #12496 (2026-06-01). Also cited at :183 as the example of what fixtures/data/ holds.

browser_tests/README.md:526

comfyPage.deleteFileAfterTest({ filename: 'image.png' })

0 hits. Added by #11523 (2026-04-22) and since removed. There is currently no file-cleanup helper in browser_tests/ at all, so the "clean up files" guidance one line above has no supported way to be followed.

Knock-on: .agents/checks/playwright-e2e.md:66 is review rule 15 — "Debug helpers left in committed code — debugAddMarker, debugAttachScreenshot, debugShowCanvasOverlay, debugGetCanvasDataURL". The rule can never fire.

2. src/composables/README.md — five composables that do not exist

src/composables/README.md:88 states: "The following tables list ALL composables in the system as of 2026-01-30."

Zero occurrences anywhere in src/, packages/ or browser_tests/:

Line	Listed	Reality
97	useFirebaseAuthActions	renamed → useAuthActions (src/composables/auth/useAuthActions.ts)
106	useTerminalBuffer	gone
118	useResponsiveCollapse	gone
230	useCivitaiModel	gone
235	useDownload	gone

Four more name a module that exists but an export that does not:

Line	Listed	Actual export
107	useTerminalTabs	useLogsTerminalTab, useCommandTerminalTab
175	useWatchWidget	useComputedWithWidgetWatch
217	useProgressTextWidget	useTextPreviewWidget
241	usePragmaticDragAndDrop	usePragmaticDroppable, usePragmaticDraggable

And the "ALL" claim: the tables hold 76 rows; src/composables/ alone has 171 files, 135 of them unlisted (useAppMode, useCanvasHistory, useFeatureFlags, useMaskEditor, …).

3. src/stores/README.md — two dead stores, one dead file, wrong count

src/stores/README.md:105: "The following table lists ALL 46 store instances in the system as of 2026-01-29." Actual: 79 non-test defineStore( call sites under src/.

• :121 firebaseAuthStore.ts / useFirebaseAuthStore — 0 occurrences of the file or the symbol.
• :126 maintenanceTaskStore.ts / useMaintenanceTaskStore — 0 occurrences of either.
• :122-123 graphStore.ts → useTitleEditorStore, useCanvasStore. No graphStore.ts exists; both live in src/renderer/core/canvas/canvasStore.ts.

4. docs/extensions/core.md — three subsections describing deleted directories

docs/extensions/core.md:57-84 documents three subdirectories and seven .js files. None of the directories and none of the files exist.

• "Located in extensions/core/load3d/conditional-lines/": ColoredShadowMaterial.js, ConditionalEdgesGeometry.js, ConditionalEdgesShader.js, OutsideEdgesGeometry.js
• "Located in extensions/core/load3d/conditional-lines/Lines2/": ConditionalLineMaterial.js, ConditionalLineSegmentsGeometry.js
• "Located in extensions/core/load3d/threejsOverride/": OverrideMTLLoader.js

src/extensions/core/load3d/ contains only loader/ and TypeScript managers.

:30 also claims "lists ALL core extensions in the system as of 2025-01-30" — 22 rows vs 41 non-test top-level .ts; imageCompositor.ts, layerEditor.ts, painter.ts, cloudBadges.ts and 15 others are unlisted.

5. .github/AGENTS.md:21 — points at two workflows and one action that are not wired up

See ci-size-data → pr-size-report or ci-perf-report → pr-perf-report. Use .github/actions/post-pr-report-comment for the comment step.

• pr-size-report.yaml and pr-perf-report.yaml do not exist. Both were consolidated into pr-report.yaml ("PR: Unified Report"), which triggers on workflow_run of CI: Size Data, CI: Performance Report and CI: E2E Coverage.
• .github/actions/post-pr-report-comment exists as a directory but has zero users — grep -rn 'post-pr-report-comment' .github/ returns only this AGENTS.md line. pr-report.yaml:175 uses ./.github/actions/upsert-comment-section.

An agent following this to add a new PR-comment workflow would build the two-workflow split around a dead action and look for two nonexistent examples.

6. src/lib/litegraph/src/subgraph/__fixtures__/README.md — a whole fixture family that never shipped

• :79-83 an "Edge Case Fixtures (edgeCaseTest)" section documenting circularSubgraph, deeplyNestedSubgraph, maxIOSubgraph. edgeCaseTest, circularSubgraph and deeplyNestedSubgraph have 0 occurrences repo-wide. subgraphFixtures.ts exports only subgraphTest.
• :58 and :320 logSubgraphStructure(subgraph, label?) — 0 occurrences.
• :63 createComplexSubgraphData(nodeCount?) — 0 occurrences.

7. Smaller, same class

• .github/workflows/README.md:14 — the api- prefix example is api-update-registry-api-types.yaml, deleted by chore: remove pull-model registry type gen workflow #9957 (2026-04-06). The table also documents 5 prefixes where 13 are in use; publish-, cloud-, version-, weekly-, update-, model-, coverage- and backport- are undocumented, which makes the "consistent naming pattern" claim misleading for anyone adding a workflow.
• .agents/checks/adr-compliance.md:79 — "Identify changed files in the entity/litegraph layer: src/lib/litegraph/, src/ecs/, src/platform/". src/ecs/ does not exist.
• .storybook/README.md:131 — the worked example is PackActionButton.vue; no such component exists.
• src/services/README.md:77 — newUserService.ts; the file is src/services/useNewUserService.ts.
• browser_tests/tests/propertiesPanel/AGENTS.md:7-17 — the "Structure" table lists 9 specs; the directory holds 18. Missing: errorsTabExecution, errorsTabMissingModels, errorsTabMissingNodes, errorsTabModeAware, errorsTabMissingMedia, errorsTabMissingMediaRuntime, errorsTabCloudMissingModels, promotedInputReorder, widgetActionsMenu.
• apps/website/src/pages/cloud/supported-nodes/AGENTS.md:21 — the link ./supported-nodes.astro resolves to .../supported-nodes/supported-nodes.astro; the file is one level up.

Root cause

.github/workflows/weekly-docs-check.yaml is a Monday-cron Claude job whose whole prompt is "Is all documentation still 100% accurate?", scoped to docs/**/*.md, CLAUDE.md and "README files throughout the repository" — exactly the surface above. It has failed 6 of its last 8 runs (2026-07-06, 07-13, 07-20, 07-27, 08-03, 08-17 failed; 08-07 and 08-10 succeeded), always at the Run Claude Documentation Review step, and nothing alerts on the failures.

Two things fall out of that:

1. The guard needs fixing and needs to page someone when it goes red, or it is decoration.
2. Even when green it is unlikely to catch these, because the load-bearing claims are inventory claims. "Lists ALL X as of DATE" is a promise no prose review keeps. These three tables (src/composables/README.md, src/stores/README.md, docs/extensions/core.md) would be better as a generated file or deleted outright in favour of a pointer at the directory — a stale inventory is worse than no inventory, because a reader treats absence from the list as evidence a thing does not exist.

Reproduction

Read at origin/main (git show origin/main:<path> — a working tree can be on any branch):

git -C ComfyUI_frontend archive origin/main | tar -x -C /tmp/fe && cd /tmp/fe

# 1
grep -rn 'debugAddMarker\|debugAttachScreenshot\|debugShowCanvasOverlay\|debugGetCanvasDataURL\|createMockNodeDefinitions\|deleteFileAfterTest' browser_tests --include=*.ts   # 0
ls browser_tests/fixtures/data/nodeDefinitions.ts                                   # ENOENT

# 2
for s in useFirebaseAuthActions useTerminalBuffer useResponsiveCollapse useCivitaiModel useDownload; do
  echo "$s $(grep -rn "$s" --include=*.ts --include=*.vue src packages browser_tests | wc -l)"; done   # all 0

# 3
grep -rn 'useFirebaseAuthStore\|maintenanceTask' --include=*.ts --include=*.vue src   # 0
ls src/stores/graphStore.ts                                                          # ENOENT
grep -rn 'defineStore(' --include=*.ts src | grep -v '\.test\.ts' | wc -l            # 79, not 46

# 4
ls src/extensions/core/load3d/conditional-lines src/extensions/core/load3d/threejsOverride   # ENOENT

# 5
ls .github/workflows/pr-size-report.yaml .github/workflows/pr-perf-report.yaml       # ENOENT
grep -rn 'post-pr-report-comment' .github/                                           # only .github/AGENTS.md:21

# 6
grep -rn 'edgeCaseTest\|circularSubgraph\|deeplyNestedSubgraph\|logSubgraphStructure\|createComplexSubgraphData' --include=*.ts src   # 0

What is clean

Recording this so the issue is not read as "the docs are bad". They are mostly good, and the ECS architecture set is a model for the rest:

• All 53 pnpm script citations resolve against the 70 scripts in the 10 workspace package.json files (only ADR 0010's literal <script> placeholders miss).
• 165 relative markdown links, 13 non-resolving: 7 are the NNNN-title.md ADR template placeholder, 5 are the deliberately-historical src/world/ links in appendix-ecs-pattern-survey.md, 1 is item 7 above.
• docs/adr/README.md and docs/adr/*.md agree exactly in both directions.
• Root AGENTS.md is clean — every config path, every command, the CONTRIBUTING.md#comment-resolution anchor, and all six ECS stores plus src/types/widgetId.ts in the "Entity Architecture Constraints" block.
• docs/architecture/* is clean and tombstoned: subgraph-boundaries-and-promotion.md:305 and proto-ecs-stores.md:110 explicitly mark PromotionStore / PromotedWidgetViewManager / PromotedWidgetView as removed by ADR 0009 and retained for archival context, and appendix-critical-analysis.md:16 pins its verification snapshot to a commit. That is the pattern the tables above should adopt.
• All 8 docs/guidance/* files clean; comfy/no-duplicate-ingest-type is real (.oxlintrc.json:31) and the 5s/10s timeouts in vitest.md:76 match Vitest defaults.
• All other nested AGENTS.md clean; CLAUDE.md files are @AGENTS.md stubs.
• 22 of 24 .agents/checks/* clean.

Filed from the cross-repo value queue (entry x01, repo-doc-audit lens).