Develop the site from its source files. Preserve the calm reading experience. Keep the content equally usable for people and agents. This guide defines development practices. It does not authorize deployment or changes to external services.
Read the repository files AGENTS.md and README.md first. Use
Content standards for writing. Use
Maintenance and upgrades for checks and updates.
For technical model pages, also read the Model Deep Dive guide
and adapt its starter template.
Source map
| Location | Purpose |
|---|---|
src/content/docs/ |
Published learning pages and guidance |
src/content/docs/about/content-guidance/ |
Writing standards, study guides, and templates |
src/content/docs/about/ |
Site purpose, framework, development, and maintenance |
src/content/partials/ |
Reusable Markdown or MDX content |
src/content.config.ts |
Content collections and schemas |
src/components.ts |
Components available globally in MDX |
src/components/ |
Shared interface and local components |
src/components/ui/ |
Components copied from the Nimbus registry |
src/layouts/ |
Page shell, navigation, and reading layout |
src/styles/ |
Shared styles and Latent Light additions |
src/pages/ |
HTML routes, text exports, agent indexes, and social images |
astro.config.ts |
Sidebar, integrations, rendering, and canonical origin |
nimbus.json |
Nimbus provenance and reviewed upgrade baseline |
.node-version |
Shared Node version for local development and automated builds |
.github/workflows/validate.yml |
GitHub validation without deployment credentials |
wrangler.jsonc |
Production Worker, domain, and static asset configuration |
scripts/verify-deployment.mjs |
Public checks after deployment |
public/ |
Assets included in the published build |
docs/branding/ |
Asset references and generation records |
docs/research/ |
Public-safe evidence, provenance, and review records |
.agents/skills/latent-light-deep-research/ |
Versioned research skill, schemas, tools, and tests |
Do not edit files in these directories:
dist/contains build output..astro/contains generated Astro files.node_modules/contains installed dependency files..wrangler/contains local Cloudflare state.
Build and development tools manage these files.
Add or update a page
Create a Markdown or MDX source in src/content/docs/. Set title,
description, and lastUpdated in frontmatter, the metadata block at the top
of the file. The content schema requires title. The layout uses title as
the page heading.
Add each new page to the explicit sidebar in astro.config.ts. Link related
explanations. Preserve established URLs. Use a redirect when replacing a route.
Organize learning collections under broader domains. AI Technology contains LLM & VLM, Document AI, Knowledge Distillation, Agents, Local & Cloud AI, Hardware 101 and Edge AI. Products & Markets contains AI Landscapes. Human Capabilities contains High agency and Taste. Do not add empty navigation groups. A sidebar grouping change does not require moving source files or changing page URLs.
Use <Render file="partial-name" /> for reusable content from
src/content/partials/. Do not import MDX files directly into other pages.
Register shared MDX components in src/components.ts. Alternatively, import
a component explicitly in the page that uses it.
Work with Nimbus components
Use PascalCase component names. Use the Nimbus installer for existing registry components. Do not recreate those components manually. Review dependencies and changed files before retaining the result.
npx --no-install @cloudflare/nimbus-docs list
npx --no-install @cloudflare/nimbus-docs add COMPONENT_SLUG
npx --no-install @cloudflare/nimbus-docs add FEATURE_SLUG --printReplace each uppercase placeholder with a reviewed registry slug. A slug is the
registry identifier for a component or feature. add can copy files and install
dependencies. Feature recipes describe changes for the developer to adapt.
Review the exact replacement before using --overwrite on customized files.
See the Nimbus CLI documentation.
Use Nimbus’s Icon component with Phosphor icons. The import path is
@cloudflare/nimbus-docs/components/Icon.astro. Icon names use the ph: prefix.
Preserve reading and editing behavior
Keep the left navigation, central article, and right outline on desktop. Preserve independent sidebar collapse, focus view, and reading preferences across navigation. Mobile uses a drawer and section selector. Keep the browser title as Latent Light. Keep the Astro developer toolbar disabled.
Put project styling in src/styles/latent-light.css where practical. Avoid
rewriting Nimbus components solely for a small feature specific to this site.
Initialize client handlers after page navigation. Remove obsolete listeners.
For wide visuals, import src/components/FocusCanvas.astro in the page.
Use its label and size props. Available sizes are figure, diagram,
and wide. Only the visual should expand in focus view, not the reading column.
Keep a meaningful text equivalent in the exported content.
Follow the figure numbering and caption standards.
SourceFigure and FoundationDiagram accept an id for figure anchors.
Keep caption labels in the page source so the text export retains them.
Import SourceFigure and ModelFlow explicitly in pages that use them.
They are not globally registered.
Keep sourceFigureAsMarkdown from plugins/source-figure.mjs registered in
astro.config.ts. It preserves the image, numbered anchor, meaningful
description, complete caption and citations while removing the image-slot
presentation wrapper. Its regression tests run with npm run test:content.
For dense report figures, set SourceFigure’s optional minWidth to a readable
width in pixels. Desktop shows the complete image; smaller screens preserve
that readable width and pan within the figure frame. The frame supports keyboard scrolling and has a
full size link. Check both normal and focus view; do not let a wide image
expand the whole page. Extract a high resolution source crop that retains
every label, legend, axis and arrow. Record its page, figure number, crop,
source version and reuse basis in the research records. Follow the
paper figure reuse standard.
For an overview poster, add zoomable fitInitially with minWidth. The full
image fits the frame on every screen until the reader selects Enlarge labels.
The enlarged image pans within its frame, including with the keyboard. Keep a
text equivalent beside the figure and retain the full size link.
For generated figures with light and dark artwork, keep the primary image in
the Markdown image slot of SourceFigure and pass the matching asset as
darkSrc. The figure and full size link follow the page theme without a
client script. Print uses the light version. Keep the same content and text
equivalent in both images; do not convey meaning through color alone.
For an animated figure, give SourceFigure an id, the still src and an
optional motionSrc. Keep the still in its Markdown image slot; the Markdown
exporter also links to the animation. In the page, the image opens the full-size
still, without a toolbar or playback buttons. Omit minWidth and zoomable
for this presentation. Hardware 101 uses a continuous loop, as requested by the
user, without visible playback controls. Playback runs with JavaScript while
the image is in view, the tab is visible and reduced motion is not requested.
Reduced motion, no JavaScript and printing use the still. Keep all essential
labels stable and preserve the complete meaning without playback. Animated
figures currently use one artwork variant rather than darkSrc.
The local source editor exists only in development mode. The Edit source button opens a full height pane below the header while keeping desktop navigation available. The pane follows sidebar collapse and focus view. It opens at the section currently being read, with a cursor positioned at the matching source heading. Generated References opens at the footnote definitions.
The header identifies the page and source path. Save page writes to the local working tree and refreshes the page; it does not commit, push, or deploy. Use Ctrl+S or Cmd+S to save and Escape to close. Reload source and closing the pane require confirmation before discarding edits. Navigation and refresh warn about unsaved changes. Preserve these protections:
- Loopback binding restricts the server to the local computer.
- Same origin checks restrict requests to the editor’s origin.
- Path checks restrict the files that the editor can access.
- Revision conflict protection prevents edits from silently replacing newer changes.
Keep the editor absent from production builds and preview. Edit only trusted MDX because MDX can execute code during rendering.
Development and validation use separate Vite caches. Preserve this separation. A build must not invalidate dependencies in a running local server.
Keep agent exports complete
Preserve these parts of the export system:
<AgentDirective />inBaseLayout.astro- The alternate Markdown link in the page head
/llms.txtand/llms-full.txt- The Markdown and MDX page routes
Do not edit generated exports separately from the page source.
Check custom components in HTML and Markdown. Preserve essential examples, citations, captions, assumptions, and media explanations. Extend Markdown processing through the Nimbus plugin configuration. Review compatibility before replacing the processor.
For model flow diagrams, use ModelFlow.astro with a static lanesJson
attribute containing JSON. Use a single quoted attribute; encode apostrophes
and angle brackets inside JSON strings as Unicode escapes. Do not use nested
JavaScript expressions for exported diagram data. The modelFlowAsMarkdown
transform emits ordered steps, lane notes, feedback descriptions, and the
cited caption. Its regression tests run with npm run test:content. Desktop
flows read left to right; narrow reading widths stack the same steps vertically.
For company explorers, import ResearchTable from
src/components/landscapes/ResearchTable.astro and place a native Markdown
table inside it. Wrap the component in FocusCanvas when the comparison is wide.
The category column is zero-indexed and defaults to the second column. Search,
filter and reset enhance reading only; the table stays visible without JavaScript.
The researchTableAsMarkdown transform in plugins/research-table.mjs preserves
all rows and citations without the controls. Test filters, keyboard scrolling,
print output and full text exports when changing the component.
Company explorer icons are an HTML reading aid. plugins/company-icons.mjs
adds a reviewed local 24 px mark beside the first company link, without changing
the native table source or Markdown export. The shared registry is
src/data/company-icons.json; sources, checksums and reuse assessments are in
docs/branding/company-icons.json. Match the company or product actually named
in the row, never an accelerator, hosting provider or unrelated namesake.
Use initials when identity or reuse is unresolved. Keep marks unchanged in color,
preserve text names and links, hide redundant images from assistive reading,
and check both themes, mobile panning, no JavaScript and failed-image fallback.
Use local files, not a third party logo service or runtime hotlinks.
For product and industry maps, use LandscapeMap.astro with a static cardsJson
attribute. Each card has label, role, examples, and question text.
Its Markdown exporter retains every field, the figure anchor, notes and cited
caption. The responsive cards use words as well as color to identify their
roles. Keep ranking, measured outcomes and proposed questions distinct.
Regression tests run with npm run test:content.
For shared architecture mechanisms, use ArchitectureAtlas.astro. Supply a
static kind from plugins/architecture-atlas.mjs and a stable figure id.
Each panel has a native SVG and a complete visible text explanation. Keep the
explanation, assumptions and figure caption meaningful without the SVG.
The architectureAtlasAsMarkdown transform exports that same text. Add tests
when you add a mechanism. Check small reading widths, dark mode and focus view;
do not make labels readable only in an expanded view.
Model studies begin with ModelResources cards. Use static reportHref,
modelHref, and modelName attributes. modelHref points to the Hugging Face
repository root, not a file or revision. The resource exporter preserves both
links and their labels in Markdown. Keep exact artifact versions in research
records and immutable reference URLs rather than displayed hashes.
Use native Markdown footnotes as specified in the
citation standards. The local plugin
plugins/reference-heading.mjs makes the generated References heading visible
without replacing Nimbus’s processor. It preserves citation anchors and return
links. Renderer regression tests run through npm run test:content and are part
of npm run validate.
Comparison tables
Use src/components/ComparisonTable.astro for general comparisons.
Keep the content in a native Markdown table inside the component.
Set id, title and an accessible label.
Use itemLabel for the row count, such as models or products.
Add the optional search attribute only when a catalog benefits from search.
The component adds column headers and pinned row headers without changing cell content.
It supports keyboard scrolling, result counts, reset and an empty state.
All rows remain available without JavaScript, in print and in Markdown exports.
Use ResearchTable for company directories that need category or base filters.
Wrap wide comparisons in FocusCanvas with size="wide".
Keep comparisonTableAsMarkdown registered in astro.config.ts.
Its implementation lives in plugins/comparison-table.mjs.
Check search, pinned labels, keyboard scrolling, print and complete exports after changes.
Hardware foundation figures and budgets
src/components/hardware/HardwareFigure.astro renders the system, circuit, sampling, chip,
memory and timing figures on Hardware 101. Pass a static kind and numbered
figure id. Its shared content and complete text equivalent live in
plugins/hardware-foundations.mjs; keep hardwareFigureAsMarkdown registered
in astro.config.ts. The signal plot uses original mathematical samples,
not measured sensor data. The circuit is an ideal DC example; the timing plot
uses explicitly assumed stage durations and dedicated resources. Chip, memory and timing
diagrams pan at narrow widths, including with the keyboard. The board map emphasizes
containment; the memory diagram shows one staging path with access exceptions,
and timing brackets distinguish per-frame latency from completion intervals.
The figures inherit the site’s Inter font and theme tokens, with one amber focal
category and neutral supporting marks. Keep circuit symbols and plotted data
faithful when applying diagram-design’s layout guidance. Preserve every
label, duration, boundary and assumption in their shared text exports.
HardwareBudget.astro uses plugins/hardware-budgets.mjs for shared input
definitions, unit calculations, initial results and Markdown exports.
Keep hardwareBudgetAsMarkdown registered. Inputs enhance the static examples;
invalid or empty values must produce an understandable error, not a result.
Check keyboard calculation selection, editing and reset, both themes, Focus view, narrow screens,
the no-JavaScript examples, print and complete exports after changes.
Calculator and export checks run with npm run test:content.
The Document AI system map
src/components/DocumentSystem.astro renders the fixed overview on the Document AI page.
Its five functional layers are Documents, Perception, Representation, Understanding and Action.
The figure also shows preserved artifacts, reliability checks and reviewed feedback.
It describes a proposed system, not five required model calls.
Edit the shared documentSystem data in plugins/document-system.mjs when the figure’s meaning changes.
The component and documentSystemAsMarkdown use that same data.
Keep its numbered caption in the page source.
Use FocusCanvas with size="diagram" for the complete horizontal view.
Narrow layouts must retain the path through all five layers and readable text.
Use ModelFlow for other flows rather than copying this fixed system map.
Document model family atlas
DocumentModelAtlas.astro renders the dated family map on Document AI.
Import it explicitly, supply a numbered figure id, and wrap it in FocusCanvas.
Keep the caption in the page source. The milestone data, typed relationships and
complete Markdown equivalent share plugins/document-model-atlas.mjs.
A milestone identifies its report revision, release log, announcement or explicitly labelled benchmark snapshot; it does not silently establish first weight availability. Keep family/design updates separate from explicit checkpoint initialization. Lanes are overlapping themes. Date and relationship evidence lives with the Document AI research records.
Keep documentModelAtlasAsMarkdown registered in astro.config.ts.
Check native keyboard selection, model/study/source links, both themes,
responsive reflow, the no-JavaScript map and complete text exports after changes.
The expanded timeline uses measured node positions; narrow layouts retain dates
and explicit text connections without shrinking a poster.
Agent maps and navigation cards
Use the components in src/components/agents/ for the Agents collection.
Their shared data parsers and Markdown renderers live in plugins/agent-presentation.mjs.
Supply static JSON text rather than JavaScript expressions.
AgentCards.astroprovides navigation cards. GivecardsJsonan array withtitle,descriptionand an Agents pagehref. An optionaleyebrowadds a short label.AgentArchitecture.astropresents system layers. GivelayersJsonan array withlabel,detailandparts. Each part contains atitleandbody. Optionalsubtitleandfootertext must survive the export.AgentLandscape.astropresents the collection overview. ItsmapJsonincludes human intent, the work loop, capabilities, controls, system families and frontier questions. Follow the schema thatreadAgentLandscapechecks rather than inventing new fields.
The two figure components require a numbered figure-N anchor and an authored caption.
Wrap wide figures in FocusCanvas.
Preserve all descriptions, assumptions, feedback, links and citations in Markdown.
Keep agentCardsAsMarkdown, agentArchitectureAsMarkdown and agentLandscapeAsMarkdown registered in astro.config.ts.
The regression checks run in scripts/agents-content.test.mjs.
Present short videos
Use src/components/media/VideoGallery.astro for a small collection of related
clips. It presents one large portrait player and a list of clips beside it,
with a stacked layout on narrow screens. Import it explicitly in the page.
Provide stable IDs, YouTube IDs, titles, durations, descriptions, local WebP
posters and transcript anchors in a static videosJson attribute.
Keep the AI generation disclosure, attribution and complete transcripts in the
component’s content slot. Native details elements can keep transcripts compact.
The player loads after a reader selects Play or a clip; switching or closing
removes the previous iframe. Links to YouTube remain usable without JavaScript.
The iframe uses the Nimbus registry Embed component.
Keep videoGalleryAsMarkdown from plugins/video-gallery.mjs registered in
astro.config.ts. Check that exports retain every clip’s link, duration,
description and transcript. Store media provenance with the topic’s research
records and keep full audio and video files outside the public source assets.
Jensen’s edited clips
The standalone Jensen collection uses JensenClips.astro for square MP4
excerpts. Keep one native player beside a compact directory, with search,
theme selection and six entries per page. Stack the player above the directory
on phones. Do not turn a growing clip collection into an unbounded card grid
or an infinite feed. Selection and directory filtering are independent; changing
a directory page must not interrupt the active clip. Pause short clips when a
full conversation starts, and close the conversation player when a short clip
starts. Load video only after a reader chooses to play.
Maintain clip titles, source timestamps and release metadata in
src/data/jensen-clips.json. HTML and the Jensen Markdown export use the same
catalog and preserve complete caption transcripts. An X post is not a reuse
clearance record. A release needs a documented reuse basis, reviewed media on
media.latentlit.com, captions and a complete transcript before it appears in
a production build.
The developer preview prefers the catalog’s named files from ignored
output/jensen-clips/, then falls back to published release URLs. Unreleased
clips with missing local media are skipped so a fresh checkout remains usable.
Use anonymous CORS on the native player so external caption tracks can load.
Keep the original contextual note beside each transcript and in Markdown exports. The development-only media middleware accepts
loopback hosts, same-origin requests and read-only byte ranges. It must not
be installed in production or expose arbitrary files. Keep unreleased MP4s,
posters and captions outside public/ and Git. Test range handling, publication
gating and directory pagination with npm run test:content.
Present a podcast
Import src/components/media/PodcastPlayer.astro for hosted audio. Supply a
stable ID, title, published MP3 URL, duration and transcript anchor. Keep the
generation disclosure and attribution in its content slot. Use native audio
controls; playback starts on the reader’s choice. JavaScript adds speed selection
and pauses overlapping media. Native controls and source links work without it.
Keep the full transcript in authored content. Label automatic transcriptions
accurately and record their method with the media provenance. Hosting settings
and delivery checks live in docs/media/; recording originals stay outside Git.
Register podcastPlayerAsMarkdown from plugins/podcast-player.mjs in
astro.config.ts. Exports must retain the source link, duration, disclosure
and transcript. Verify real playback, seeking and speed controls, along with
keyboard use and narrow-screen rendering.
Render mathematics
Author math using the equation standards.
astro.config.ts selects Astro’s native Sätteri processor with math: true.
Nimbus still supplies its admonitions and normal Astro rendering passes.
The existing table and reference plugins remain in the same pipeline.
plugins/math-typesetting.mjs typesets native Markdown math nodes with KaTeX
at build time. MDX pages use the globally registered MathExpression component
because Nimbus’s source scanner does not recognize math delimiters. Pass LaTeX
in a static tex attribute and add display and number="1" for a standalone
equation. The component adds \tag{1}; do not also put a tag in its tex value.
Numeric tags produce an equation-1 anchor and an accessible equation label.
Both paths produce visual HTML and accessible MathML with a TeX annotation.
Invalid LaTeX fails the build. Trusted HTML commands are disabled, and macros
do not carry between expressions. Code examples and quotations remain literal.
BaseLayout.astro imports KaTeX CSS. Its fonts are bundled locally; no CDN or
client side renderer is used. Equation styles in src/styles/prose.css keep
display formulas centered, with right aligned numbers and symmetric space to
prevent overlap. Wide formulas and their numbers stay in a keyboard accessible
scrolling region. Keep those styles
scoped to article content. Do not apply code or quotation styles to equations.
KaTeX and the Sätteri processor are explicit dependencies. The rendering tests
in scripts/math-typesetting.test.mjs run through npm run test:content.
Check actual pages in both themes and at narrow widths. Confirm that Markdown
exports retain the standard dollar delimiters, notation, equation tags, and citations.
The mathAsMarkdown component transform in astro.config.ts supplies this
conversion. MDX exports retain the original component and LaTeX attributes.
Neither export should contain rendered spans or stripped equations. KaTeX documents its
rendering options.
If replacing Sätteri, set admonitions: false. Preserve the existing callout
behavior. See the Nimbus endpoint documentation.
Research workflow and tools
Use the Research workflow for
substantial investigations. The repo-local latent-light-deep-research skill
coordinates that workflow. Read its SKILL.md and applicable references before
using its tools. It needs Python 3.10 or newer and no third-party Python packages.
For new site research, the MD or MDX page is the canonical narrative. Keep
evidence and actual review results in docs/research/<domain>/<topic>/; do not
maintain a second article in report.md. A requested standalone report can
be the canonical output instead. Preserve existing schema 2 reports and
records without automatic migration.
The skill initializer creates records, not page content. Its validator reads
records without modifying them. Neither tool establishes scientific truth,
visual quality, or reuse rights. When changing the tools, run
npm run test:research as well as the relevant site checks.
Retain source and asset records
A canonical link is enough for an ordinary citation. Keep a concise record in
docs/research/<topic>/ for a closely studied paper or a source that supplies
a visual. Use docs/branding/ for identity assets. These records support the
Content standards. They do not duplicate the editorial guidance.
Record these details for each source:
- Title and author or organization
- Canonical URL
- Exact version or publication date
- Retrieval date
For changing information, distinguish the source date from the date you checked the claim.
For a reproduced or adapted visual, also record these details:
- Figure number or location in the source
- Copyright holder and applicable usage terms, including third party exclusions
- Reuse basis: license, direct permission, or a documented applicable exception
- For an exception: purpose, distribution, amount, alternatives, nature, likely effect and remaining uncertainty; do not label it as a license grant
- Extraction or adaptation method
- Resulting asset path
Retain prompts and reference provenance for AI generated assets. Keep a useful caption and source link on the page, not only in the repository record.
If a local paper copy helps study, preserve the original version unchanged. Record its filename and checksum to distinguish it from later versions. Do not commit or deploy complete downloaded papers merely because selected figures can be reused. Assess each excerpt for its intended public distribution under the reuse standard. Local study archives can remain outside the public repository.
Use src/assets/ for page visuals that Astro processes. Use public/ for assets
that need stable paths. Prefer SVG or HTML for original technical diagrams when
practical. Include accessible descriptions. Preserve the meaning of visuals at
narrow widths and in text exports. Keep large media outside the source repository.
Repository records are also intended for public sharing. Do not place private research notes, confidential sources, or restricted files in these records. The absence of a permissive artwork license is not an automatic rejection. If neither a license, permission nor a defensible exception supports the intended use, link to the source or write an independent explanation.
Visual identity and provenance
The identity uses Echo, two offset lightning bolts in gold and orange.
Preserve the complete silhouettes and transparent gap between the bolts.
Keep the established public/brand/logo-dark.png and
public/brand/logo-light.png paths. Both currently contain the same transparent
1254 by 1254 pixel artwork, which works in either theme. The header switches
between these complete images with the theme. The selection, exact generation
prompts and asset checksums are recorded in docs/branding/identity.md and its
linked concept records. The PNGs are raster artwork, not vector masters.
public/favicon.ico contains 16, 32, 48, 64, and 256 pixel versions of Echo.
Its source is public/brand/favicon-master.png, the same transparent artwork
used for the theme logos. Generate the icon sizes from that master without
changing the mark’s proportions.
The homepage uses public/brand/galaxy-line-art.png as original AI generated
decorative artwork. This artwork is not an astronomical diagram.
Keep the artwork static. Adapt it to the theme. Hide it when printing. Do not add a large logo to the homepage body.
The small author introduction uses public/brand/avatar-bingyuan-cartoon.png.
This AI generated cartoon uses the author’s public portrait as a loose reference.
Its source link and generation prompt remain in docs/branding/avatar-cartoon.md.
Keep license records in THIRD_PARTY_NOTICES.md and public/licenses/.
Before completing a change, follow the validation checklist.
Landscape overviews and collection accents
Use LandscapeOverview.astro for a numbered opening overview image. It reuses
SourceFigure for full-resolution access and mobile panning. Register its Markdown
renderer so the figure anchor, image, alt text and cited caption survive exports.
Keep an equivalent explanation or comparison table in the page; the image must not
be the only source of essential information. Save generation prompts and review
notes with the research records.
LandscapeCards.astro adds local, restrained accents to the landscape hub’s Nimbus
cards. Keep the change scoped to that collection and preserve semantic links,
keyboard focus, theme contrast, responsive layout and text exports.