From 364f23612b9dc48684e2a8b7c1ba8722bf20b94b Mon Sep 17 00:00:00 2001 From: Cory Rylan Date: Sun, 17 May 2026 21:40:52 -0500 Subject: [PATCH 1/2] chore(docs): add agent tooling guidelines - Introduced a new internal author documentation page for 'Agent Tooling' detailing best practices for designing metadata, static checks, CLI tools, skills, apps, and MCP servers for agents. Signed-off-by: Cory Rylan --- projects/site/src/_11ty/layouts/common.js | 1 + .../docs/internal/guidelines/agent-tooling.md | 275 ++++++++++++++++++ 2 files changed, 276 insertions(+) create mode 100644 projects/site/src/docs/internal/guidelines/agent-tooling.md diff --git a/projects/site/src/_11ty/layouts/common.js b/projects/site/src/_11ty/layouts/common.js index f0bd68a83..f56f4594d 100644 --- a/projects/site/src/_11ty/layouts/common.js +++ b/projects/site/src/_11ty/layouts/common.js @@ -343,6 +343,7 @@ export const renderDocsNav = data => /* html */ ` Internal Guidelines Agent Harness + Agent Tooling Documentation Examples TypeScript diff --git a/projects/site/src/docs/internal/guidelines/agent-tooling.md b/projects/site/src/docs/internal/guidelines/agent-tooling.md new file mode 100644 index 000000000..905e6c3fc --- /dev/null +++ b/projects/site/src/docs/internal/guidelines/agent-tooling.md @@ -0,0 +1,275 @@ +--- +{ + title: 'Agent Tooling', + description: 'Internal guidelines: best practices for designing metadata, static checks, CLI tools, skills, apps, and MCP servers for agents.', + layout: 'docs.11ty.js' +} +--- + +# {{title}} + +Agent tooling is not a separate product surface. It adds progressively higher-level adapters over the same metadata, validation rules, and package APIs that humans use. Build the slow deterministic layer first. Add model-facing tools only after the lower layer can answer the question or reject the invalid state. + +## Policy Compiler + +Turn repeated guidance into facts, gates, commands, and agent tools. + +
+ + + + + + + + + + + + + + + + most effort / durable + fast / contextual + + + + + + + Metadata + Source Of Truth + + + + Static Tools + Lint, Types, Tests + + + + CLI / Skills + Commands, Context + + + + MCP / Apps + Agent Interfaces + + + + + + + facts + gates + paths + tools + +
+
+

+

+
+
+

+
    + +
    +
    +
    + + + +## Build Inside Out + +- **Metadata** is the durable contract. Generate facts once, then let docs, lint, CLI, skills, apps, and MCP consume them. If a fact exists only in a prompt, README, or tool description, the harness does not own it. +- **Static tools** for when agents repeat a mistake: type or schema, lint rule, test, CLI validation, MCP tool. If CI cannot enforce a rule that a parser can see, the harness is incomplete. +- **CLI and skills** to adapt the deterministic layer for humans and agent workflows. The CLI proves a capability without chat context. Skills should carry workflow order and project policy, not duplicate API catalogs. +- **MCP and MCP Apps** expose existing services to agents through narrow schemas, structured outputs, and explicit side-effect annotations. They should mirror the service layer, not own domain logic. + +## Layering Rules + +{% dodont %} + +
    + +- **Start with metadata.** Add or fix the generated fact before building consumers. +- **Fail statically.** Prefer lint, types, and tests for any rule a parser can verify. +- **Prove with CLI.** Make the command usable by humans before agents call it. +- **Guide with skills.** Put workflow order, repository policy, and validation habits in skills. +- **Expose through MCP last.** Mirror existing services with focused schemas and annotations. + +
    +
    + +- **Do not hide facts in prompts.** Prompts are runtime hints, not durable data. +- **Do not make MCP the source of truth.** Treat it as an adapter over services. +- **Do not ship model-only validation.** If CI cannot enforce it, the harness is incomplete. +- **Do not return raw dumps.** Distill context before it reaches the agent. + +
    + +{% enddodont %} + +## Decision Checklist + +Before creating a new agent-facing tool, answer these questions: + +- What metadata does this tool need, and where is that metadata generated? +- Which invalid states can type checking, JSON Schema, linting, or tests reject first? +- Can a human use the same capability through the CLI without chat context? +- Does the tool have a bounded input schema and a structured output schema? +- Is the result distilled for the task, or does it push context cleanup onto the model? +- Is this capability general enough for MCP, or is it only workflow context for a skill? +- What test fails if the tool disappears, changes shape, or starts returning stale data? + +If the answer starts with "tell the model to remember," stop. Build the harness layer that makes remembering unnecessary. + +## Related Docs + +- [Agent Harness](/docs/internal/guidelines/agent-harness/) +- [Documentation Guidelines](/docs/internal/guidelines/documentation/) +- [Examples Guidelines](/docs/internal/guidelines/examples/) +- [CLI](/docs/cli/) +- [MCP](/docs/mcp/) +- [Lint](/docs/lint/) From b4ae6c4c8e6881b0737246c1dff253a300a5abf9 Mon Sep 17 00:00:00 2001 From: Cory Rylan Date: Mon, 18 May 2026 21:51:27 -0500 Subject: [PATCH 2/2] chore(docs): metadata structure fixes Signed-off-by: Cory Rylan --- projects/site/package.json | 10 +- projects/site/src/_11ty/layouts/common.js | 1 + projects/site/src/_11ty/layouts/metadata.js | 227 ++++++++++++-- .../site/src/_11ty/layouts/metadata.test.ts | 211 ++++++++++++- .../internal/guidelines/agent-ownership.md | 284 ++++++++++++++++++ .../docs/internal/guidelines/agent-tooling.md | 2 +- 6 files changed, 700 insertions(+), 35 deletions(-) create mode 100644 projects/site/src/docs/internal/guidelines/agent-ownership.md diff --git a/projects/site/package.json b/projects/site/package.json index d6a980b99..0dd094411 100644 --- a/projects/site/package.json +++ b/projects/site/package.json @@ -49,6 +49,7 @@ "command": "rm -rf dist .11ty-vite && pnpm exec eleventy", "files": [ "src", + "!src/**/*.test.js", "!src/**/*.test.lighthouse.ts", "public", "!public/llms.txt", @@ -196,16 +197,13 @@ ] }, "test": { - "command": "vitest run --config=vitest.config.ts", + "command": "vitest run src/_11ty/layouts/metadata.test.ts", "files": [ - "src/**/*.test.ts", "src/_11ty/layouts/metadata.js", + "src/_11ty/layouts/metadata.test.ts", "vitest.config.ts" ], - "output": [], - "dependencies": [ - "../internals/vite:ci" - ] + "output": [] }, "test:lighthouse": { "command": "playwright-lock 'vitest run --config=vitest.lighthouse.ts'", diff --git a/projects/site/src/_11ty/layouts/common.js b/projects/site/src/_11ty/layouts/common.js index f56f4594d..9eec16956 100644 --- a/projects/site/src/_11ty/layouts/common.js +++ b/projects/site/src/_11ty/layouts/common.js @@ -344,6 +344,7 @@ export const renderDocsNav = data => /* html */ ` Internal Guidelines Agent Harness Agent Tooling + Agent Ownership Documentation Examples TypeScript diff --git a/projects/site/src/_11ty/layouts/metadata.js b/projects/site/src/_11ty/layouts/metadata.js index 75f550326..7eb306742 100644 --- a/projects/site/src/_11ty/layouts/metadata.js +++ b/projects/site/src/_11ty/layouts/metadata.js @@ -1,11 +1,35 @@ import { join } from 'node:path'; -import { ELEMENTS_SITE_URL } from '../utils/env.js'; import { siteData } from '../../index.11tydata.js'; export const BASE_URL = join('/', process.env.PAGES_BASE_URL ?? '', '/'); -const SITE_ORIGIN = ELEMENTS_SITE_URL.replace(/\/$/, ''); -const PATH_PREFIX = BASE_URL.replace(/\/$/, ''); +const SITE_URL = 'https://nvidia.github.io/elements'; +export const SOFTWARE_ID = `${SITE_URL}/#software`; +const SOFTWARE_URL = `${SITE_URL}/`; +const CODE_SAMPLE_ROUTES = ['/docs/cli/', '/docs/code/', '/docs/integrations/', '/docs/lint/', '/docs/mcp/']; + +const LANGUAGE_NAMES = { + bash: 'Shell', + css: 'CSS', + go: 'Go', + html: 'HTML', + javascript: 'JavaScript', + js: 'JavaScript', + json: 'JSON', + markdown: 'Markdown', + md: 'Markdown', + python: 'Python', + shell: 'Shell', + sh: 'Shell', + toml: 'TOML', + ts: 'TypeScript', + tsx: 'TypeScript', + typescript: 'TypeScript', + xml: 'XML', + yaml: 'YAML', + yml: 'YAML', + zsh: 'Shell' +}; const BREADCRUMB_TERMS = { api: 'API', @@ -108,8 +132,8 @@ export function resolvePageMeta(data) { description = `Documentation for ${rawTitle} in NVIDIA Elements, the framework-agnostic design system for AI/ML factories.`; } - const canonicalUrl = `${SITE_ORIGIN}${PATH_PREFIX}${url}`; - const ogImage = `${SITE_ORIGIN}${PATH_PREFIX}/favicon.svg`; + const canonicalUrl = `${SITE_URL}${url}`; + const ogImage = `${SITE_URL}/favicon.svg`; return { title, description, canonicalUrl, ogImage, url }; } @@ -117,34 +141,78 @@ function jsonLdEncode(value) { return JSON.stringify(value).replace(/<\//g, '<\\/'); } -export function renderJsonLd(data, meta) { - const isDocs = meta.url.startsWith('/docs/'); - const articleType = isDocs ? 'TechArticle' : 'WebPage'; - const date = data.page?.date instanceof Date ? data.page.date.toISOString() : new Date().toISOString(); - const generatedUrls = new Set(data.collections?.all?.map(entry => entry.url).filter(Boolean)); +function isApiReferencePage(data, meta) { + return Boolean( + data.tag || + data.isApiTab || + meta.url.startsWith('/docs/api-design/') || + meta.url.startsWith('/docs/cli/') || + meta.url.startsWith('/docs/integrations/') || + meta.url.startsWith('/docs/lint/') || + meta.url.startsWith('/docs/mcp/') + ); +} + +function normalizeDate(value) { + if (value instanceof Date) return value.toISOString(); + if (typeof value !== 'string') return null; + + const date = new Date(value); + return Number.isNaN(date.getTime()) ? null : date.toISOString(); +} + +function getContentDates(data) { + return { + datePublished: normalizeDate(data.datePublished ?? data.published ?? data.git?.created ?? data.git?.createdTime), + dateModified: normalizeDate(data.dateModified ?? data.modified ?? data.git?.modified ?? data.git?.modifiedTime) + }; +} +function getArticle(data, meta) { + const isDocs = meta.url.startsWith('/docs/'); + const isApiReference = isApiReferencePage(data, meta); + const element = findElementByTag(data.tag ?? data.component?.data?.tag); + const dates = getContentDates(data); const article = { - '@context': 'https://schema.org', - '@type': articleType, + '@id': meta.canonicalUrl, + '@type': isApiReference ? 'APIReference' : isDocs ? 'TechArticle' : 'WebPage', headline: meta.title, description: meta.description, url: meta.canonicalUrl, mainEntityOfPage: meta.canonicalUrl, inLanguage: 'en', image: meta.ogImage, - datePublished: date, - dateModified: date, - publisher: { '@type': 'Organization', name: 'NVIDIA', url: SITE_ORIGIN }, + publisher: { '@type': 'Organization', name: 'NVIDIA', url: SITE_URL }, author: { '@type': 'Organization', name: 'NVIDIA' } }; + if (isDocs || meta.url === '/') { + article.about = { '@id': SOFTWARE_ID }; + } + + if (isApiReference && element?.manifest?.tagName) { + article.programmingModel = 'Web Components'; + article.targetPlatform = 'Web'; + + if (element?.version) { + article.assemblyVersion = element.version; + } + } + + if (dates.datePublished) article.datePublished = dates.datePublished; + if (dates.dateModified) article.dateModified = dates.dateModified; + + return article; +} + +function getBreadcrumb(data, meta) { + const generatedUrls = new Set(data.collections?.all?.map(entry => entry.url).filter(Boolean)); const segments = meta.url.split('/').filter(Boolean); - const articleScript = ``; if (segments.length === 0) { - return articleScript; + return null; } - const itemListElement = [{ '@type': 'ListItem', position: 1, name: 'Home', item: `${SITE_ORIGIN}${PATH_PREFIX}/` }]; + const itemListElement = [{ '@type': 'ListItem', position: 1, name: 'Home', item: `${SITE_URL}/` }]; let cumulative = ''; segments.forEach((seg, i) => { cumulative += `/${seg}`; @@ -155,14 +223,129 @@ export function renderJsonLd(data, meta) { '@type': 'ListItem', position: itemListElement.length + 1, name: titleCaseSegment(seg), - item: `${SITE_ORIGIN}${PATH_PREFIX}${item}` + item: `${SITE_URL}${item}` }); }); - const breadcrumb = { - '@context': 'https://schema.org', + return { + '@id': `${meta.canonicalUrl}#breadcrumb`, '@type': 'BreadcrumbList', itemListElement }; - return `${articleScript}\n `; +} + +function getSoftwareApplication(description) { + return { + '@id': SOFTWARE_ID, + '@type': 'SoftwareApplication', + name: 'NVIDIA Elements', + description, + url: SOFTWARE_URL, + applicationCategory: 'DeveloperApplication', + operatingSystem: 'Any', + runtimePlatform: 'Web', + softwareHelp: SOFTWARE_URL + }; +} + +function getPageText(data) { + return [data.content, data.rawInput, data.templateContent].filter(value => typeof value === 'string').join('\n'); +} + +function normalizeLanguage(language) { + if (typeof language !== 'string') return null; + return LANGUAGE_NAMES[language.toLowerCase()] ?? null; +} + +function getProgrammingLanguages(data) { + const languages = new Set(); + const declared = data.programmingLanguage ?? data.programmingLanguages; + const declaredLanguages = Array.isArray(declared) ? declared : [declared].filter(Boolean); + declaredLanguages + .map(String) + .map(normalizeLanguage) + .filter(Boolean) + .forEach(language => languages.add(language)); + + if (data.isExamplesTab) { + languages.add('HTML'); + } + + const pageText = getPageText(data); + [...pageText.matchAll(/(?:language|lang)=["']([^"']+)["']/g)].forEach(match => { + const language = normalizeLanguage(match[1]); + if (language) languages.add(language); + }); + + [...pageText.matchAll(/class=["'][^"']*language-([a-z0-9+-]+)[^"']*["']/gi)].forEach(match => { + const language = normalizeLanguage(match[1]); + if (language) languages.add(language); + }); + + [...pageText.matchAll(/```([a-z0-9+-]+)/gi)].forEach(match => { + const language = normalizeLanguage(match[1]); + if (language) languages.add(language); + }); + + return [...languages]; +} + +function hasVisibleCode(data) { + return getProgrammingLanguages(data).length > 0; +} + +function shouldEmitSoftwareSourceCode(data, meta) { + if (data.structuredData?.sourceCode === false) return false; + if (data.structuredData?.sourceCode === true) return true; + if (data.isExamplesTab) return true; + if (!hasVisibleCode(data)) return false; + return CODE_SAMPLE_ROUTES.some(route => meta.url.startsWith(route)); +} + +function getCodeSampleType(data, meta) { + if (data.structuredData?.codeSampleType) return data.structuredData.codeSampleType; + if (meta.url.startsWith('/starters/')) return 'template'; + if (data.isExamplesTab || meta.url.includes('/examples/')) return 'full solution'; + return 'code snippet'; +} + +function getRuntimePlatform(meta) { + return meta.url.startsWith('/docs/cli/') || meta.url.startsWith('/docs/mcp/') ? 'Native binary' : 'Web'; +} + +function getSoftwareSourceCode(data, meta) { + if (!shouldEmitSoftwareSourceCode(data, meta)) return null; + + const programmingLanguage = getProgrammingLanguages(data); + if (!programmingLanguage.length) return null; + + return { + '@id': `${meta.canonicalUrl}#source-code`, + '@type': 'SoftwareSourceCode', + name: meta.title, + description: meta.description, + url: meta.canonicalUrl, + codeSampleType: getCodeSampleType(data, meta), + programmingLanguage: programmingLanguage.length === 1 ? programmingLanguage[0] : programmingLanguage, + runtimePlatform: getRuntimePlatform(meta), + targetProduct: { '@id': SOFTWARE_ID, '@type': 'SoftwareApplication' } + }; +} + +export function renderJsonLd(data, meta) { + const article = getArticle(data, meta); + const breadcrumb = getBreadcrumb(data, meta); + const sourceCode = getSoftwareSourceCode(data, meta); + const graph = [ + article, + ...(breadcrumb ? [breadcrumb] : []), + ...(meta.url === '/' ? [getSoftwareApplication(meta.description)] : []), + ...(sourceCode ? [sourceCode] : []) + ]; + + if (sourceCode) { + article.hasPart = { '@id': sourceCode['@id'] }; + } + + return ``; } diff --git a/projects/site/src/_11ty/layouts/metadata.test.ts b/projects/site/src/_11ty/layouts/metadata.test.ts index f986aa608..b9c053dc6 100644 --- a/projects/site/src/_11ty/layouts/metadata.test.ts +++ b/projects/site/src/_11ty/layouts/metadata.test.ts @@ -7,9 +7,28 @@ afterAll(() => { vi.unstubAllEnvs(); }); -vi.mock('../../index.11tydata.js', () => ({ siteData: { elements: [] } })); +vi.mock('../../index.11tydata.js', () => ({ + siteData: { + elements: [ + { + name: 'nve-button', + version: '1.2.3', + manifest: { + tagName: 'nve-button' + } + }, + { + name: 'nve-codeblock', + version: '1.2.3', + manifest: { + tagName: 'nve-codeblock' + } + } + ] + } +})); -const { renderJsonLd } = await import('./metadata.js'); +const { renderJsonLd, SOFTWARE_ID } = await import('./metadata.js'); interface JsonLdListItem { '@type': 'ListItem'; @@ -23,6 +42,51 @@ interface BreadcrumbList { itemListElement: JsonLdListItem[]; } +type JsonLdNode = Record; + +interface JsonLdGraph { + '@graph': JsonLdNode[]; +} + +interface MetadataInput { + title: string; + description: string; + canonicalUrl: string; + ogImage: string; + url: string; +} + +interface PageData { + page: { + url: string; + date?: Date; + }; + collections: { + all: { url: string }[]; + }; + content?: string; + tag?: string; +} + +function createMeta(url: string, overrides: Partial = {}): MetadataInput { + return { + title: 'Test Page | NVIDIA Elements', + description: 'Test description.', + canonicalUrl: `https://nvidia.github.io/elements${url}`, + ogImage: 'https://nvidia.github.io/elements/favicon.svg', + url, + ...overrides + }; +} + +function createData(overrides: Partial = {}): PageData { + return { + page: { url: '/' }, + collections: { all: [] }, + ...overrides + }; +} + function isBreadcrumbList(value: unknown): value is BreadcrumbList { if (typeof value !== 'object' || value === null) return false; @@ -31,18 +95,153 @@ function isBreadcrumbList(value: unknown): value is BreadcrumbList { return candidate['@type'] === 'BreadcrumbList' && Array.isArray(candidate.itemListElement); } +function isJsonLdGraph(value: unknown): value is JsonLdGraph { + if (typeof value !== 'object' || value === null) return false; + + return Array.isArray((value as Record)['@graph']); +} + function getBreadcrumbJsonLd(html: string): BreadcrumbList { - const scripts = [...html.matchAll(/ + +## Ownership Means + +Owning an agent-assisted change means you can defend the implementation from first principles. + +- **Intent:** You know why the change exists and which user, API, or system behavior it serves. +- **Design:** You chose the public API, boundaries, state model, and failure behavior deliberately. +- **Correctness:** You tested happy paths, invalid states, edge cases, and integration behavior that can regress. +- **Maintainability:** You removed incidental complexity, dead code, speculative abstraction, and unexplained patterns. +- **Review:** You kept the diff small enough for another engineer to reason about the risk. +- **Automation:** You strengthened the harness when the same failure can recur. + +The prompt is not evidence. Passing tests are not evidence if the tests do not assert the risk. Review approval is not evidence if nobody can explain the behavior. The evidence is the code, the tests, the static gates, and the engineer's command of the system. + +## Professional Use Of AI Agents + +Use agents to speed up the loop. Do not use them to outsource judgment. + +{% dodont %} + +
    + +- **Start with the invariant.** Decide what must stay true before generating code. +- **Constrain the task.** Ask for the smallest useful change, then inspect the result. +- **Read the diff.** Review generated code with the same care as hand-written code. +- **Delete aggressively.** Keep the solution small, local, and aligned with existing patterns. +- **Test the risk.** Add the test that would fail for the mistake that concerns you. +- **Strengthen the harness.** Turn repeated guidance into lint, types, tests, metadata, or CLI validation. + +
    +
    + +- **Do not ship prompts.** Prompts are not governance, documentation, or a validation strategy. +- **Do not accept generated architecture blindly.** The agent does not know the long-term cost. +- **Do not hide behind the model.** The engineer owns the change, not the tool. +- **Do not merge code nobody can explain.** Plausible code is not the same as correct code. +- **Do not rely on style review.** Review the behavioral and architectural risk first. +- **Do not normalize flakes.** A flaky gate is a missing gate. + +
    + +{% enddodont %} + +Do not make review discover basic ownership. Professional software engineering means taking responsibility for consequences, not producing code-shaped output. + +Agents are most useful when the repository has a strong harness: strict types, lint rules, deterministic tests, clear package boundaries, generated metadata, reviewable diffs, and engineers who understand the systems they change. Without that harness, agents only increase the rate at which weak process reaches production. + +## Related Docs + +- [Agent Harness](/docs/internal/guidelines/agent-harness/) +- [Agent Tooling](/docs/internal/guidelines/agent-tooling/) +- [Documentation Guidelines](/docs/internal/guidelines/documentation/) diff --git a/projects/site/src/docs/internal/guidelines/agent-tooling.md b/projects/site/src/docs/internal/guidelines/agent-tooling.md index 905e6c3fc..82bd459d0 100644 --- a/projects/site/src/docs/internal/guidelines/agent-tooling.md +++ b/projects/site/src/docs/internal/guidelines/agent-tooling.md @@ -237,7 +237,7 @@ if (toolingRoot) { - **Fail statically.** Prefer lint, types, and tests for any rule a parser can verify. - **Prove with CLI.** Make the command usable by humans before agents call it. - **Guide with skills.** Put workflow order, repository policy, and validation habits in skills. -- **Expose through MCP last.** Mirror existing services with focused schemas and annotations. +- **Expose through MCP last.** Use MCP as a focused access point over existing services and standardized functionality.