transformer-cross-attention-page

[AndreasAbdi]

{
"project": "Model Atlas — Transformer Cross-Attention Canonical Page",
"branchName": "transformer-cross-attention-page",
"description": "Publish one canonical English cross-attention concept page, backed by registry data and localized messages, so readers can discover a broad cross-attention explainer through search, tags, and related docs and then branch into nearby transformer, encoder-decoder, multimodal, and self-attention pages.",
"context": {
"customerAsk": "Add one canonical English docs page for cross-attention as a missing core transformer concept. Implement the page as a single-page content slice on top of current main, not as a broad attention-family refactor. Scope: create the canonical page, colocated messages/en.json, any required assets.json, and the matching registry record; classify it correctly per docs/documentation-site-pages-needed.md; add tags/groupings/aliases that make it discoverable from attention and multimodal/encoder-decoder reader paths; and update only the focused validation/tests needed for registry integrity, related links, and page discoverability. The prose should explain in plain language when cross-attention is used, how it differs from self-attention, and where readers will encounter it in encoder-decoder or multimodal systems. Link to nearby canonical pages such as transformer-architecture, self-attention, encoder-decoder, and representative model or system pages where appropriate. Keep the slice English-only and avoid unrelated localization churn.",
"problem": "The site is missing a dedicated canonical page for cross-attention even though it is a core concept readers encounter in encoder-decoder systems and multimodal models. Without a first-class page, readers searching for cross-attention do not have a stable explainer that distinguishes it from self-attention, explains when it is used, or connects it to surrounding architecture and model pages through registry-backed discovery surfaces.",
"solution": "Publish a registry-backed cross-attention concept page at its canonical docs route, written in the existing message-key-driven style with English-only localized content. Update the surrounding registry and discovery metadata so search, tags, aliases, and related-doc surfaces treat cross-attention as a first-class attention concept and guide readers outward to transformer-architecture, self-attention, encoder-decoder, multimodal model concepts, and representative model or system pages where those links meaningfully deepen the explanation."
},
"acceptanceCriteria": [
"A published canonical docs page exists for cross-attention with a matching concept registry record, English messages, and any required local assets.",
"The page follows the canonical docs writing standards with one folded openingSummary, layperson-friendly tone, acronym expansion, and no process or template leakage in customer-facing prose.",
"The page explains when cross-attention is used, how it differs from self-attention, and where readers encounter it in encoder-decoder and multimodal systems.",
"Registry metadata, aliases, tags, and related-doc derivation make the page discoverable from attention and multimodal or encoder-decoder reader paths without broad taxonomy churn.",
"The canonical route renders through the normal docs shell and exposes usable related links, tags, and search-visible metadata for the new page.",
"Typecheck, lint, and focused tests for touched registry, routing, related-doc, and discovery surfaces pass."
],
"userStories": [
{
"id": "transformer-cross-attention-page-001",
"title": "Create the canonical page contract",
"description": "As a reader, I want a dedicated cross-attention docs route so I can open a stable explainer page instead of inferring the concept from unrelated pages.",
"acceptanceCriteria": [
"A canonical docs page exists for cross-attention using the concept-page pattern with page.mdx, messages/en.json, and assets.json only if the page actually needs local assets.",
"The page is wired to a matching concept.cross-attention registry record and uses the standard docs shell, section structure, and message-key-driven rendering contract.",
"The route renders successfully on current main without missing-message, missing-asset, or missing-registry placeholders.",
"Typecheck passes"
],
"priority": 1,
"passes": true,
"notes": ""
},
{
"id": "transformer-cross-attention-page-002",
"title": "Add registry-backed discovery metadata",
"description": "As a reader, I want cross-attention to appear in the right topic and search pathways so I can find it from attention, encoder-decoder, and multimodal exploration flows.",
"acceptanceCriteria": [
"The new registry record is classified as a concept under the controlled attention browsing path described in docs/documentation-site-pages-needed.md.",
"Aliases, tags, and related IDs support direct discovery for queries such as cross attention and browsing paths centered on attention, encoder-decoder, or multimodal systems.",
"Discovery wiring stays narrowly scoped to the new page and immediately adjacent records instead of refactoring the whole attention taxonomy.",
"Typecheck passes",
"Tests pass"
],
"priority": 2,
"passes": true,
"notes": ""
},
{
"id": "transformer-cross-attention-page-003",
"title": "Teach the concept and connect nearby pages",
"description": "As a first-time reader, I want the page to explain cross-attention in plain language and link me to the next relevant pages so I can continue learning without getting stranded.",
"acceptanceCriteria": [
"The opening summary and primary sections explain what cross-attention is, when it is used, and how it differs from self-attention in plain language.",
"The page describes where readers will encounter cross-attention in encoder-decoder systems and multimodal architectures, including at least one representative nearby model or system page when such a link is already available.",
"Related-doc or in-body links include nearby canonical pages such as transformer-architecture, self-attention, and encoder-decoder, plus other immediately relevant pages only when they genuinely help the reader continue.",
"Browser-visible rendering shows the title, summary, tags, and related-doc links without broken links or missing-content placeholders.",
"Typecheck passes",
"Tests pass",
"Verify in browser using the Browser plugin"
],
"priority": 3,
"passes": true,
"notes": ""
},
{
"id": "transformer-cross-attention-page-004",
"title": "Add focused validation for registry and discoverability",
"description": "As a maintainer, I want targeted automated proof for the cross-attention slice so registry, route, related-link, and discovery regressions are caught without broad unrelated test expansion.",
"acceptanceCriteria": [
"Validation or test coverage confirms the cross-attention page route, registry record, and default English messages resolve together.",
"Coverage asserts at least one page-specific discoverability or related-doc expectation for cross-attention.",
"Coverage stays focused on observable behavior for this page slice and does not require unrelated inventory snapshots or meta-test scaffolding.",
"Typecheck passes",
"Tests pass"
],
"priority": 4,
"passes": true,
"notes": ""
}
]
}

[AndreasAbdi]

Addressed mergeability follow-up after CI reported lint failures on the current PR head.

Changes in the latest push:

• removed the unused isHeadBox local in RegistryGraphFlow.tsx
• cleared Biome import-order/format drift in the files CI flagged
• updated glossary-architecture-index.test.ts so the architecture inventory explicitly includes the newly published /docs/concepts/cross-attention route

Validation run locally on the updated head:

• bun run lint
• bun run typecheck
• bun test src/lib/content/cross-attention-concept.test.ts src/features/models/components/RegistryGraphFlow.test.tsx src/lib/content/content-reconciliation-sidebar-meta.test.ts src/lib/content/glossary-architecture-index.test.ts
• earlier focused cross-attention validation: bun test src/lib/content/content-reconciliation-attention-tag.test.ts src/lib/content/content-reconciliation-search-queries.test.tsx src/lib/content/validate-registry.test.ts

[AndreasAbdi]

Addressed the remaining mergeability follow-up on the current PR head.

Changes in the latest push:

• anchored content-paths to the checked-out repository instead of process.cwd() so verifier CLI fixtures still load the real docs/search content when they execute from temporary working directories
• made docs page discovery fail closed when a fixture root has no src/content/docs tree instead of throwing an ENOENT before verifier startup checks can run
• updated the attention tag landing expectation to include the published cross-attention concept group
• updated the raw static-search expectation so the low-level Orama client accepts the new cross-attention discoverability result for the generic attention query

Validation run locally on the updated head:

• bun run lint
• bun run typecheck
• bun run coverage
• bun run test

[AndreasAbdi]

Checked the current PR state on commit 099756ab4b3a0446f9522d141f181611e49d8716.

No new external PR conversation feedback was present, and all PRD stories were already marked complete, so this pass focused on mergeability only.

Actions taken:

• verified the expected cross-attention files are present in the PR diff
• confirmed the prior CI attempt on this same head was stale after hanging in Install Playwright Chromium
• cancelled that stale run and started a fresh rerun attempt on the same workflow run

No code changes were required in this iteration; the branch is now waiting on the fresh CI attempt for the existing head.

[AndreasAbdi]

Addressed the failing test-build-contract mergeability blocker on head 1f92fd91d106bf0bf3080031da16263a360cf702.

Changes in the latest push:

• added a shared locked build helper so plain bun run build and bun run build:export cannot race each other on shared .next and out artifacts inside build-contract tests
• switched next-build-tracing-warning.test.ts to use that shared lock and added focused helper coverage for the plain-build path
• made content-paths.getProjectRoot() resolve from the current module file path in a bundler-safe way so the production /api/search build path no longer crashes during page-data collection

Validation run locally on the updated head:

• make build
• make test-build-contract
• bun test src/lib/content/content-paths.test.ts src/lib/build/run-static-export-build.test.ts
• bun test src/tests/build/next-build-tracing-warning.test.ts
• bun run typecheck
• bun run lint

[AndreasAbdi]

Addressed the failing test mergeability blocker on head f29bbad407f2d84a82e41791ae0302f23b1a906b.

Changes in the latest push:

• narrowed the raw oramaStaticClient assertion in src/tests/search/search-api.test.ts to direct cross attention and encoder-decoder attention queries
• stopped requiring the broad pre-rerank attention query to surface cross-attention, which was unstable because raw static results can be dominated by unrelated high-frequency docs before app-level reranking

Validation run locally on the updated head:

• bun test src/tests/search/search-api.test.ts
• bun run lint
• bun run typecheck
• bun run test