Skip to the content.

In-app gallery and technical docs

The Nuxt app exposes two browse hubs that share the same URL state (useBrowseQuery): a root page, a grid, and filter / group controls. Docs (and /code) use the browse toolbar; the gallery folds its controls into one floating menu.

Route Role Chrome
/gallery Full-screen social-style gallery (reels, stills, code, diagrams) Primary nav label Gallery; own full-bleed gallery layout
/docs Technical documentation sourced from the repo docs/ markdown tree Work sub-nav (AppWorkSubNav) — not in AppPrimaryNav
/docs/... Individual spec / runbook rendered from that markdown Linked from the docs catalog; Work sub-nav stays on Work pages only

Public primary rail is About / Work / Gallery / Code / Writing. Docs, AI Lab (/ai-lab), and Process (/process) live under Work — see portfolio-august-launch.md.

Browse toolbar (AppBrowseToolbar)

Docs and /code share one toolbar (the gallery’s controls live in its menu; see Gallery):

Page fit: /docs uses the prose fit (data-fit="prose"); /code uses the fluid fit (data-fit="fluid", the viewport width inside the page padding) with the toolbar’s Package facet plus item for the selected snippet. The gallery is full bleed in its own layout (below).

/gallery should feel like a social media app: edge-to-edge pieces at their real shape, and one tap to a full-screen view that is also the feed. Spec: docs/superpowers/specs/2026-10-19-gallery-redesign-design.md.

Content lives in core/web/content/gallery.json (Nuxt Content gallery collection). Posts are flattened from categories (flattenGalleryPosts); each may carry date (ISO), caseStudy (a site path) and source (a public-repo link built with core/web/shared/public-repo.ts).

When adding posts, run node scripts/gallery-dates.js --write. It fills each missing date with the first git commit date of the post’s media file (exhibit.src, else exhibit.poster, else image) under core/web/public, or with a placeholder (2026-01-01 minus category index x 30 + item index days) when there is no tracked file, so builds on Lambda / S3 never read files. Replace any date by editing the JSON.

Performance (100+ posts)

Built for a hundred or more posts without virtualization or pagination (revisit past ~300 posts; see the TODO):

Helpers: core/web/shared/gallery-types.ts (flattenGalleryPosts, filterGalleryPosts, sortGalleryPosts, GALLERY_SORTS, resolveGalleryAspect, resolveGalleryPlatform, galleryRatio, GALLERY_PLATFORM_LABEL), core/web/shared/gallery-justify.ts and core/web/shared/gallery-viewer.ts. Components: app/components/gallery/ (GalleryMenu, GalleryGrid, GalleryViewer, GalleryInfoPanel, GalleryExhibit); composables useGalleryPreview and useGalleryViewerRoute. Tests: core/web/tests/gallery-*.spec.ts; e2e: core/web-e2e/src/e2e/gallery-viewer.cy.ts.

SSR / script-setup contract: Pug templates must not call those helpers on _ctx. Bind them in <script setup> (e.g. GalleryGrid’s tiles computed, which maps posts to { ratio, tags, name, style }) so Nuxt SSR does not warn about missing instance properties.

Technical documentation

Markdown under repo docs/ is ingested in place by the docs collection (REPO_DOCS_DIR in core/web/shared/docs-source.ts). Do not copy or move those files into core/web/content/. Editing a file under docs/ updates both GitHub/Pages sources and the next Nuxt Content build for in-app /docs.

Whenever those pages change, follow the documentation sync checklist (catalogs, related hubs, and matching inline comments).

At build time Nuxt Content parses the tree into the Content SQLite dump. Lambda (SYS_ENV=test / production) and Docker local/dev images restore that dump from host .output/<sysEnv> — the original .md files are not required on the runtime image. Dockerfile.app copies that output tree; it does not COPY docs or rebuild Nuxt.

Excludes: Jekyll index.md / _*.md, design-history superpowers/ and plans/. The in-app catalog groups by path prefix (App, Agents, Packages, Developer tooling, Ops & delivery).

Links: write them for GitHub (relative to the .md file). Nuxt Content keeps them relative and drops .md, so on /docs/** the global ProseA (app/components/ProseA.global.vue → docsLinkHref in core/web/shared/docs-links.ts) resolves each against the page’s route (which mirrors the file tree) and maps it:

core/web/tests/docs-links.spec.ts pins the mapping and keeps UNPUBLISHED_DOC_DIRS in step with DOCS_COLLECTION_EXCLUDE.

UML-style diagrams:

See architecture.md for the diagram hub (C4, API UML, wireframes, sequences).

Fetch path: fetchContentCollection('docs', { mode: 'all' | 'first', path }) — same Nitro API as other collections. Do not call client queryCollection().