@janga/norna 0.7.7 → 0.7.8

package/README.md

@@ -25,12 +25,13 @@ A `norna` site is file-driven:
    base path, in `site/config.mjs`.
 3. The site keeps site-wide visual theme defaults, including layout, image
    sizing, font, typography, colors, and frame colors, in `site/theme.md`.
-4. The site keeps homepage content, Markdown section order, image blocks, alt
-   text, captions, and optional section metadata in `site/content.md`.
+4. The site keeps homepage content, Markdown section order, managed media
+   blocks, alt text, captions, and optional section metadata in
+   `site/content.md`.
 5. Optional route pages live under
-   `site/routes/<route-folder>/route-content.md`.
+   `site/routes/<NNN-route-id>/route-content.md`.
 6. Source images live under `site/images/<section-id>/` for the homepage, or
-   under `site/routes/<route-folder>/images/<section-id>/` for a route.
+   under `site/routes/<NNN-route-id>/images/<section-id>/` for a route.
 7. Static public files live under `site/public/`.
 8. `norna` validates the files, prepares managed images, builds static Astro
    pages, and can help publish the committed branch through GitHub Pages.
@@ -75,7 +76,7 @@ Actions use the same engine version.
 
 - Create a site: [Getting Started](docs/getting-started.md)
 - Understand required site files: [Site Structure](docs/site-structure.md)
-- Edit sections and image blocks: [Content](docs/content.md)
+- Edit sections and managed media blocks: [Content](docs/content.md)
 - Configure a site: [Configuration](docs/configuration.md)
 - Publish under a GitHub Pages project path:
   [`site.basePath`](docs/configuration.md#sitebasepath)

package/docs/README.md

@@ -39,7 +39,7 @@ For a quick reference:
   fields such as URL, base path, locale labels, footer, GitHub, and deploy
   settings.
 - [Content](content.md) describes page frontmatter, Markdown-authored
-  sections, optional section metadata, image stacks, carousels, temporary
+  sections, optional section metadata, managed media blocks, temporary
   sections, and content validation.
 - [Theme](theme.md) describes site-wide layout, layout density, image sizing,
   font, typography rhythm, presentation colors, frame colors, and inline styles.

package/docs/commands.md

@@ -101,10 +101,11 @@ should normally mean the repository's complete publishable artifact, while
   cache path.
 - `config:check`: validates `site/config.mjs` against the runtime config
   reader.
-- `content:check`: validates section structure, image references, inline
-  styles, and common content mistakes.
+- `content:check`: validates section structure, managed media references,
+  inline styles, and common content mistakes.
 - `content:sync` / `norna:sync`: moves misplaced referenced image files after
-  confirmation.
+  confirmation when the intended move is unambiguous. Moving files between the
+  homepage and routes, or between routes, requires a clean Git working tree.
 - `typography presets`: prints the exact built-in values for typography
   presets and rhythms.
 - `typography show`: prints the selected site's resolved typography for the

package/docs/configuration.md

@@ -141,7 +141,7 @@ Fields:
   `Sections`.
 - `locale.labels.menu`: mobile menu summary text, default `Menu`.
 - `locale.labels.closeMenu`: reserved close-menu label, default `Close menu`.
-- `locale.labels.gallery`: Norna image block ARIA label prefix, default
+- `locale.labels.gallery`: Norna managed media ARIA label prefix, default
   `Images`.
 
 Example:

package/docs/content.md

@@ -91,10 +91,12 @@ page file:
 Do not list sections in frontmatter just to define order. Section order comes
 from the Markdown heading order.
 
-## Image Blocks
+## Managed Media Blocks
 
-Norna-managed local images are written in Markdown fenced blocks at the point
-where they should appear in the section.
+Norna-managed local images and cards are written in Markdown fenced blocks at
+the point where they should appear in the section. Markdown determines
+placement: move the fenced block in the page file to move the rendered image,
+carousel, or card list.
 
 Use `norna-image-stack` for one or more stacked images:
 
@@ -119,6 +121,38 @@ Use `norna-image-carousel` for a carousel:
 ```
 ````
 
+Use `norna-card-list` for a list of compact cards. Cards can include text,
+managed images, links, and optional badge text:
+
+````md
+```norna-card-list
+layout: image-top
+flow: grid
+size: m
+width: normal
+
+- title: Adopt
+  text: Give a dog a new home.
+  image: adopt.svg
+  link: /adopt/
+  badge-text: Recommended
+- title: Foster
+  text: Help for a shorter period.
+  image: foster.svg
+```
+````
+
+Card-list options:
+
+- `layout`: `image-top`, `image-left`, or `image-right`.
+- `flow`: `grid` or `stack`.
+- `size`: `s`, `m`, `l`, or `xl`.
+- `width`: `text`, `narrow`, `normal`, or `wide`.
+
+Each card starts with `- title: Card title`. Card fields use two spaces of
+indentation. Supported fields are `text`, `image`, `link`, and `badge-text`.
+Each card must include at least one of `text`, `image`, or `link`.
+
 Each image entry supports:
 
 - `image`: required filename matching
@@ -127,8 +161,8 @@ Each image entry supports:
 - `alt`: optional alt text. If omitted, Norna renders an empty alt attribute.
 - `caption`: optional caption.
 
-Start every image entry with `- image: filename.jpg`. Optional fields use two
-spaces of indentation:
+Start every image entry in image stacks and carousels with
+`- image: filename.jpg`. Optional fields use two spaces of indentation:
 
 ````md
 ```norna-image-stack
@@ -174,7 +208,7 @@ Route images live under:
 site/routes/<NNN-route-id>/images/<section-id>/
 ```
 
-Image references in Norna image blocks use only the filename:
+Image references in Norna managed media blocks use only the filename:
 
 ````md
 ```norna-image-stack
@@ -187,7 +221,8 @@ location is `site/images/team/portrait.jpg`.
 
 Filenames do not have to be globally unique for the site to be valid. Automatic
 sync only moves files when the filename identifies exactly one source candidate
-within the current page or route.
+across the site's page and route image roots. If more than one candidate
+exists, Norna reports the ambiguity instead of guessing.
 
 ## Markdown Images
 
@@ -199,8 +234,9 @@ Markdown image syntax is allowed for external images and public static assets:
 ```
 
 Relative local Markdown images such as `![Portrait](portrait.jpg)` are not
-managed by Norna. Use `norna-image-stack` or `norna-image-carousel` for local
-site images that should be validated, processed and synced.
+managed by Norna. Use `norna-image-stack`, `norna-image-carousel`, or
+`norna-card-list` for local site images that should be validated, processed and
+synced.
 
 ## Temporary Sections
 
@@ -253,9 +289,9 @@ npm run norna:content:check
 
 This checks section heading ids, section metadata, duplicate image names,
 missing image files, misplaced referenced images, duplicate image references,
-invalid image blocks, unreferenced images, undefined inline styles, Markdown
-image references to unmanaged local files, and common frontmatter indentation
-and structure mistakes.
+invalid managed media blocks, unreferenced images, undefined inline styles,
+Markdown image references to unmanaged local files, and common frontmatter
+indentation and structure mistakes.
 
 Frontmatter uses YAML indentation. Use ordinary spaces, not tabs or
 non-breaking spaces. `content:check` reports a focused error when indentation is
@@ -282,5 +318,19 @@ npm run norna:sync
 ```
 
 This moves referenced image files into the section directory shown by the
-Markdown placement. It prompts before writing unless `--yes` is passed. Sync is
-currently page- or route-local: it does not move images across routes.
+Markdown placement. It prompts before writing unless `--yes` is passed.
+
+`content:sync` is intentionally conservative. It only moves a file when the
+filename identifies exactly one matching source candidate across the site's
+page and route image roots, and when the move will not break another reference.
+If the intended move is ambiguous, rename or move the file manually and run
+`content:check` again.
+
+Duplicate filenames are allowed when files already live where their Markdown
+references expect them. Automatic relocation only requires site-wide filename
+uniqueness for the file being moved.
+
+When `content:sync` needs to move an image between the homepage and a route, or
+between two routes, the Git working tree must be clean before the write. This
+keeps cross-route sync easy to roll back. `content:check` only reports issues
+and does not require a clean working tree.

package/docs/getting-started.md

@@ -16,10 +16,13 @@ Install Playwright Chromium only when you plan to run navigation diagnostics:
 npx playwright install chromium
 ```
 
-## Create A Site Repository
+## Create A Site
 
-Create the site from the starter first, then install dependencies inside the
-new site directory:
+### Standalone Site
+
+Use a standalone setup when the website is its own project. Create the site
+from the starter first, then install dependencies inside the new site
+directory:
 
 ```sh
 cd path/to/your/projects
@@ -55,11 +58,33 @@ The starter contains:
 - `site/config.mjs`
 - `site/theme.md`
 - `site/content.md`
-- `site/images/work/.gitkeep`
 - `site/public/robots.txt`
 
 Commit the generated `package-lock.json` after the first install.
 
+### Embedded Site
+
+Use an embedded setup when a Norna site should live inside an existing Node or
+GitHub project:
+
+```sh
+cd existing-project
+npx @janga/norna@latest init . --type embedded --site-dir presentation
+npm install
+npm run norna:dev
+```
+
+The command looks different because the target is different. `.` means "add
+Norna to the current project" instead of creating a new directory.
+`--site-dir presentation` tells Norna to manage `presentation/` as the site
+directory instead of the default `site/`.
+
+Embedded setup keeps the surrounding project structure. It adds namespaced
+`norna:*` scripts so Norna does not take over the project's normal `build`,
+`test`, or deploy scripts.
+
+Relevant documentation: [Commands](commands.md), [Site Structure](site-structure.md).
+
 ## First Edits
 
 1. Edit `site/config.mjs` for the site's URL, language labels, GitHub
@@ -68,9 +93,10 @@ Commit the generated `package-lock.json` after the first install.
    rhythm, image sizing, font, typography preset, colors, inline styles, and
    frame colors, or omit it to use engine defaults.
 3. Edit `site/content.md` for homepage title, description, Markdown sections,
-   text, Norna image blocks, page/section presentation overrides, alt text, and
-   captions.
-4. Put source images under `site/images/<section-id>/`.
+   text, Norna managed media blocks, page/section presentation overrides, alt
+   text, and captions.
+4. Put source images under `site/images/<section-id>/`, where `<section-id>`
+   matches a `## Section {#section-id}` heading in `site/content.md`.
 5. Add optional route pages under
    `site/routes/<NNN-route-id>/route-content.md`, for example
    `site/routes/010-about/route-content.md`.
@@ -79,10 +105,23 @@ Commit the generated `package-lock.json` after the first install.
 7. Run:
 
 ```sh
+npm run norna:config:check
+npm run norna:content:check
+npm run norna:sync
 npm run norna:check
 npm run build
 ```
 
+`norna:sync` moves misplaced referenced image files when the intended move is
+unambiguous. It can move images between sections and routes, but cross-route
+writes require a clean Git working tree so the operation is easy to roll back.
+Publishing is normally done by committing the site files and pushing them with
+Git; the starter GitHub Pages workflow runs the required checks before
+publishing.
+
+Relevant documentation: [Content](content.md), [Theme](theme.md),
+[Typography](typography.md), [Routes](routes.md), [Images And Metadata](images-and-metadata.md).
+
 ## Configure The Public URL
 
 For a custom domain or any site published at the web root, use:
@@ -112,6 +151,8 @@ The starter includes a GitHub Pages workflow in `.github/workflows/deploy.yml`.
 In the GitHub repository settings, configure Pages to build from GitHub
 Actions.
 
+Relevant documentation: [Configuration](configuration.md), [Publishing](publishing.md).
+
 Read [Site Structure](site-structure.md), [Content](content.md),
 [Theme](theme.md), [Typography](typography.md), [Routes](routes.md), and
 [Configuration](configuration.md) before publishing a real site.

package/docs/images-and-metadata.md

@@ -6,8 +6,8 @@ source images and any copyright or licensing policy for those images.
 ## Managed Source Images
 
 Norna-managed local images are referenced from Markdown with
-`norna-image-stack` or `norna-image-carousel` blocks. See
-[Content](content.md#image-blocks) for the block syntax.
+`norna-image-stack`, `norna-image-carousel`, or `norna-card-list` blocks. See
+[Content](content.md#managed-media-blocks) for the block syntax.
 
 Homepage source images live under:
 
@@ -28,7 +28,7 @@ Supported source extensions:
 - `.png`
 - `.svg`
 
-Image block references use only the filename:
+Managed media block references use only the filename:
 
 ````md
 ```norna-image-stack
@@ -53,8 +53,10 @@ prompt: Short prompt or editing note.
 ```
 
 Filenames do not have to be globally unique for the site to be valid.
-Automatic sync only moves files when the filename identifies exactly one source
-candidate within the current page or route.
+Automatic sync only moves misplaced files when the filename identifies exactly
+one source candidate across the site's page and route image roots, and when the
+move will not break another reference. If the move crosses page or route image
+roots, `content:sync` requires a clean Git working tree before writing.
 
 ## Markdown Images
 
@@ -98,7 +100,7 @@ example-work-1a2b3c4d-1440.webp
 When a source image changes, the generated URL changes too. This avoids stale
 browser, CDN, and GitHub Actions cache entries at the old URL.
 
-SVG files are managed by the same Markdown image blocks, validation and sync
+SVG files are managed by the same Markdown media blocks, validation and sync
 model, but they are not rasterized and do not get WebP variants. Norna copies
 the SVG source to:
 
@@ -164,6 +166,9 @@ static website, restrained colors, readable composition, no text in the image.
 ```
 ````
 
+The same provenance comment style can be used next to a `norna-image-carousel`
+or `norna-card-list` block when generated images are referenced there.
+
 This is a maintenance rule for real editorial images. It is not necessary for
 throwaway test fixtures or examples where the prompt has no practical value.
 

package/docs/routes.md

@@ -4,9 +4,14 @@
 under `site/routes/<NNN-route-id>/route-content.md` and build to first-level
 URLs.
 
-Routes use the same page frontmatter, optional section metadata, Norna image
-blocks, and Markdown section model as the homepage. See [Content](content.md)
-for the page and section model.
+Routes use the same page frontmatter, optional section metadata, Norna managed
+media blocks, and Markdown section model as the homepage. See
+[Content](content.md) for the page and section model.
+
+Route directories can contain route content, route-local images, and
+route-local presentation overrides in `route-content.md`. They cannot contain
+technical site configuration; technical configuration stays at the selected
+site directory's top-level `config.mjs`.
 
 ## Route Directory Format
 
@@ -107,3 +112,9 @@ Image references in route content still use only the filename:
 ````
 
 The image directory segment after `images/` should match the section id.
+If the section id or route folder changes, run `norna content:check` to find
+misplaced images and `norna content:sync` to move unambiguous files into the
+expected section folder. `content:sync` can move images between route image
+roots when the filename is unambiguous across the site and the move will not
+break another reference; these cross-route writes require a clean Git working
+tree.

package/docs/site-structure.md

@@ -42,7 +42,8 @@ Version these files in a site repository:
   colors.
   See [Theme](theme.md).
 - `site/content.md`: homepage page file with editable content, Markdown
-  sections, optional section metadata, image blocks, alt text, and captions.
+  sections, optional section metadata, managed media blocks, alt text, and
+  captions.
   See [Content](content.md).
 - `site/images/<section-id>/`: original source images.
 - `site/routes/<NNN-route-id>/route-content.md`: optional route page files.
@@ -82,8 +83,10 @@ In this repository:
 - `bin/norna-cli.mjs` dispatches public CLI commands.
 - `scripts/` contains validation, image, local preview, deploy, and test tools.
 - `src/` contains the Astro renderer, components, styles, and content schema.
-- `starters/basic/` is copied by `norna init <target-dir>` to create a
-  site repository.
+- `starters/basic/` is the default compact starter copied by
+  `norna init <target-dir>`.
+- `starters/project/` is a project-site starter used as a maintained example
+  for small project and developer-tool sites.
 - `fixtures/basic/site/` is used by engine regression tests.
 - `examples/dog-gallery/site/` is the local visual dog example used by demo
   builds and navigation diagnostics.

package/docs/theme.md

@@ -6,7 +6,8 @@ missing, built-in engine defaults are used.
 
 Page-level presentation in `site/content.md` and route page files is always an
 override on top of `site/theme.md`. Section-level presentation is an override
-on top of the resolved page presentation.
+on top of the resolved page presentation. Use those overrides for focused
+exceptions; the normal place for shared visual choices is `site/theme.md`.
 
 ## Minimal Theme
 
@@ -74,7 +75,7 @@ navigation:
 - `density`: default structural spacing profile. Allowed values are `compact`,
   `normal`, and `airy`.
 - `spacing`: optional structural spacing overrides for sections and Norna
-  image blocks. Every spacing value accepts either one CSS length for all
+  managed media blocks. Every spacing value accepts either one CSS length for all
   viewports or `desktop` / `mobile` values.
 
 Example:
@@ -104,7 +105,7 @@ Spacing keys:
 - `firstSectionTop`: space above the first section heading.
 - `sectionGap`: space above each following section.
 - `finalSectionBottom`: space below the final section.
-- `bodyToImages`: space from section body text to Norna image blocks.
+- `bodyToImages`: space from section body text to Norna managed media blocks.
 - `imageGap`: space between stacked images or carousel blocks.
 
 Text-near spacing, such as spacing after headings, spacing before Markdown
@@ -207,7 +208,9 @@ presentation:
 ```
 
 Section-specific presentation belongs under
-`sections.<section-id>.presentation`:
+`sections.<section-id>.presentation`. Use it when one section genuinely needs
+different presentation; do not use `sections` to define section order or normal
+Markdown structure.
 
 ```yaml
 sections:

package/docs/typography.md

@@ -5,8 +5,8 @@ presets, text rhythm, and optional overrides.
 
 The normal place to choose a site-wide typography preset and rhythm is the
 top-level `typography` block in `site/theme.md`.
-Page and section files may override the theme when a page or section needs a
-different presentation.
+Page and section files may override the theme when a focused exception is
+needed, but the normal workflow is to keep typography in `theme.md`.
 
 ## Presets
 
@@ -18,9 +18,8 @@ Available presets:
   short information blocks.
 - `text-forward`: more generous body text for pages where longer text carries
   more of the experience.
-- `statement`: tighter, more declarative line-height for introductions, first
-  sections, and short programmatic statements. Use it sparingly, usually as a
-  section override.
+- `statement`: tighter, more declarative line-height for short programmatic
+  statements. Use it sparingly, usually as a page or section exception.
 
 If theme typography is omitted, `quiet-gallery` is used.
 

package/examples/dog-gallery/site/content.md

@@ -4,44 +4,10 @@ description: A small norna example with free dog images.
 navigation:
   label: Dog site!
 sections:
-  black-dogs:
-    presentation:
-      typography:
-        preset: statement
-        overrides:
-          headings:
-            h2:
-              size: xlarge
   summer-dogs:
     visible:
       from: "2026-08-01"
       until: "2026-09-01"
-    presentation:
-      backgroundColor: "#181818"
-      typography:
-        preset: compact-gallery
-  brown-dogs:
-    presentation:
-      typography:
-        preset: text-forward
-  golden-dogs:
-    presentation:
-      typography:
-        overrides:
-          headings:
-            h2:
-              size: large
-            h3:
-              size: medium
-          body:
-            lineHeight: 1.58
-            paragraphSpacing: 1em
-  white-dogs:
-    presentation:
-      typography:
-        overrides:
-          caption:
-            spacingBefore: 0.35em
 ---
 
 ## Black Dogs {#black-dogs}
@@ -112,8 +78,7 @@ Cras justo odio, dapibus ac facilisis in, egestas eget quam.
 
 ### Training note
 
-This section overrides `headings.h2` and `headings.h3`, while keeping the
-site-wide `headings.h4` style.
+This `###` heading follows the site-wide `headings.h3` style.
 
 Nulla vitae elit libero, a pharetra augue. Integer posuere erat a ante venenatis
 dapibus posuere velit aliquet. Aenean eu leo quam. Pellentesque ornare sem

package/examples/dog-gallery/site/routes/010-dog-care/route-content.md

@@ -3,14 +3,6 @@ title: Dog care
 description: A small route for testing multi-page norna navigation.
 navigation:
   label: Dog care
-sections:
-  daily-rhythm:
-    presentation:
-      typography:
-        overrides:
-          headings:
-            h2:
-              size: large
 ---
 
 ## Daily rhythm {#daily-rhythm}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@janga/norna",
   "description": "A command-line publishing workflow for simple static sites.",
   "type": "module",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "license": "GPL-3.0-only",
   "repository": {
     "type": "git",

package/scripts/sync-content-sections.mjs

@@ -1,7 +1,9 @@
+import { execFile } from 'node:child_process';
 import { mkdir, rename, stat } from 'node:fs/promises';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import path from 'node:path';
+import { promisify } from 'node:util';
 import {
 	extractMarkdownImageReferences,
 	extractNornaMarkdownBlockDiagnostics,
@@ -25,8 +27,11 @@ import { readImageDimensions } from './lib/image-dimensions.mjs';
 import {
 	siteThemeLabel,
 	siteThemePath,
+	siteProjectRoot,
 } from './lib/site-paths.mjs';
 
+const execFileAsync = promisify(execFile);
+
 const args = new Set(process.argv.slice(2));
 const shouldWrite = args.has('--write');
 const shouldCheck = args.has('--check') || !shouldWrite;
@@ -60,7 +65,7 @@ const promptForWrite = async () => {
 	if (!process.stdin.isTTY) return false;
 
 	const rl = createInterface({ input, output });
-	const answer = await rl.question('This will move image files inside their current page or route image root if needed. Continue? [y/N] ');
+	const answer = await rl.question('This will move image files into the page or route image roots where Norna references them. Continue? [y/N] ');
 	rl.close();
 
 	return answer.trim().toLowerCase() === 'y';
@@ -172,16 +177,110 @@ const getExpectedImagePath = (contentFile, sectionId, imageName) =>
 const getExpectedImageLabel = (contentFile, sectionId, imageName) =>
 	`${contentFile.imagesLabel}/${sectionId}/${imageName}`;
 
-const getImageCandidates = (imageCandidatesByName, imageName, expectedPath) =>
-	(imageCandidatesByName.get(imageName) ?? []).filter((candidate) => candidate !== expectedPath);
+const getGlobalImageCandidates = (globalImageCandidatesByName, imageName, expectedPath) =>
+	(globalImageCandidatesByName.get(imageName) ?? []).filter(({ imagePath }) => imagePath !== expectedPath);
 
 const getReferenceLabel = (contentFile, section) => `${contentFile.contentLabel} [${section.id}]`;
 
+const getRootLabel = (contentFile) => contentFile.isHome
+	? contentFile.imagesLabel
+	: contentFile.imagesLabel.replace(/\/images$/, '');
+
+const getCandidateLabel = ({ contentFile, imagePath }) =>
+	`${contentFile.imagesLabel}/${toPosixPath(path.relative(contentFile.imagesDir, imagePath))}`;
+
+const addExpectedReference = (expectedReferencesByPath, expectedPath, expectedReference) => {
+	if (!expectedReferencesByPath.has(expectedPath)) {
+		expectedReferencesByPath.set(expectedPath, []);
+	}
+
+	expectedReferencesByPath.get(expectedPath).push(expectedReference);
+};
+
+const addGlobalImageCandidate = (globalImageCandidatesByName, imageName, candidate) => {
+	if (!globalImageCandidatesByName.has(imageName)) {
+		globalImageCandidatesByName.set(imageName, []);
+	}
+
+	globalImageCandidatesByName.get(imageName).push(candidate);
+};
+
+const assertCleanGitForCrossRootSync = async (moves) => {
+	if (!moves.some((move) => move.crossRoot)) return;
+
+	let stdout = '';
+	try {
+		({ stdout } = await execFileAsync('git', ['status', '--short'], {
+			cwd: siteProjectRoot,
+			maxBuffer: 1024 * 1024,
+		}));
+	} catch (error) {
+		addIssue({
+			severity: 'error',
+			message: 'Cross-route content sync requires a clean git working tree, but git status could not be checked.',
+			fix: 'Run content:sync inside a Git worktree, or move cross-route image files manually.',
+		});
+		return;
+	}
+
+	if (!stdout.trim()) return;
+
+	addIssue({
+		severity: 'error',
+		message: 'Cross-route content sync requires a clean git working tree before moving files between page or route image roots.',
+		fix: `Commit or stash your current changes, then run content:sync again. Current changes:\n${stdout.trim()}`,
+	});
+};
+
+const addConflictingMoveIssues = () => {
+	const movesBySource = new Map();
+	const movesByDestination = new Map();
+
+	for (const move of imageMoves) {
+		const sourceKey = move.from;
+		const destinationKey = move.to;
+
+		if (!movesBySource.has(sourceKey)) {
+			movesBySource.set(sourceKey, []);
+		}
+		movesBySource.get(sourceKey).push(move);
+
+		if (!movesByDestination.has(destinationKey)) {
+			movesByDestination.set(destinationKey, []);
+		}
+		movesByDestination.get(destinationKey).push(move);
+	}
+
+	for (const moves of movesBySource.values()) {
+		const destinations = new Set(moves.map((move) => move.to));
+		if (destinations.size <= 1) continue;
+
+		const firstMove = moves[0];
+		addSectionIssue(firstMove.contentFile, { id: firstMove.sectionId, heading: firstMove.sectionId }, {
+			severity: 'error',
+			message: `Cannot relocate "${firstMove.imageName}" because the same source file is referenced from multiple destinations: ${moves.map((move) => getExpectedImageLabel(move.contentFile, move.sectionId, move.imageName)).join(', ')}.`,
+			fix: 'Duplicate the image manually or rename one of the image files so each move has a single destination.',
+		});
+	}
+
+	for (const moves of movesByDestination.values()) {
+		const sources = new Set(moves.map((move) => move.from));
+		if (sources.size <= 1) continue;
+
+		const firstMove = moves[0];
+		addSectionIssue(firstMove.contentFile, { id: firstMove.sectionId, heading: firstMove.sectionId }, {
+			severity: 'error',
+			message: `Cannot relocate "${firstMove.imageName}" because multiple source files would move to ${getExpectedImageLabel(firstMove.contentFile, firstMove.sectionId, firstMove.imageName)}: ${moves.map((move) => getCandidateLabel(move.sourceContentFile ? { contentFile: move.sourceContentFile, imagePath: move.from } : move)).join(', ')}.`,
+			fix: 'Move the intended file manually or rename files so the destination is unambiguous.',
+		});
+	}
+};
+
 const validateImageReference = async (
 	contentFile,
 	section,
 	reference,
-	imageCandidatesByName,
+	globalImageCandidatesByName,
 	expectedReferencesByPath,
 ) => {
 	const imageName = reference.image;
@@ -194,11 +293,11 @@ const validateImageReference = async (
 		return expectedPath;
 	}
 
-	const candidates = getImageCandidates(imageCandidatesByName, imageName, expectedPath);
+	const candidates = getGlobalImageCandidates(globalImageCandidatesByName, imageName, expectedPath);
 	if (candidates.length === 0) {
 		addSectionIssue(contentFile, section, {
 			severity: 'error',
-			message: `Image "${imageName}" does not exist at ${expectedLabel} or anywhere under ${contentFile.imagesLabel}/.`,
+			message: `Image "${imageName}" does not exist at ${expectedLabel} or anywhere under any page or route image root.`,
 			fix: `Add the source image to ${contentFile.imagesLabel}/${section.id}/ or remove the Norna-managed image reference.`,
 		});
 		return null;
@@ -207,20 +306,21 @@ const validateImageReference = async (
 	if (candidates.length > 1) {
 		addSectionIssue(contentFile, section, {
 			severity: 'error',
-			message: `Cannot relocate "${imageName}". Multiple files with this filename were found: ${candidates.map((candidate) => `${contentFile.imagesLabel}/${toPosixPath(path.relative(contentFile.imagesDir, candidate))}`).join(', ')}.`,
-			fix: 'Move the intended file manually or rename files so the local move is unambiguous.',
+			message: `Cannot relocate "${imageName}". Multiple files with this filename were found: ${candidates.map(getCandidateLabel).join(', ')}.`,
+			fix: 'Move the intended file manually or rename files so the move is unambiguous.',
 		});
 		return null;
 	}
 
-	const sourcePath = candidates[0];
+	const sourceCandidate = candidates[0];
+	const sourcePath = sourceCandidate.imagePath;
 	const referencesAtCurrentLocation = (expectedReferencesByPath.get(sourcePath) ?? [])
-		.filter((expectedReference) => expectedReference.section.id !== section.id);
+		.filter((expectedReference) => expectedReference.contentFile !== contentFile || expectedReference.section.id !== section.id);
 
 	if (referencesAtCurrentLocation.length > 0) {
 		addSectionIssue(contentFile, section, {
 			severity: 'error',
-			message: `Cannot relocate "${imageName}" from ${contentFile.imagesLabel}/${toPosixPath(path.relative(contentFile.imagesDir, sourcePath))} because it is still referenced from ${referencesAtCurrentLocation.map((expectedReference) => getReferenceLabel(contentFile, expectedReference.section)).join(', ')}.`,
+			message: `Cannot relocate "${imageName}" from ${getCandidateLabel(sourceCandidate)} because it is still referenced from ${referencesAtCurrentLocation.map((expectedReference) => getReferenceLabel(expectedReference.contentFile, expectedReference.section)).join(', ')}.`,
 			fix: 'Remove the extra reference, duplicate the image file manually, or rename one of the image files so the intended move is unambiguous.',
 		});
 		return null;
@@ -231,15 +331,19 @@ const validateImageReference = async (
 		from: sourcePath,
 		to: expectedPath,
 		contentFile,
+		sourceContentFile: sourceCandidate.contentFile,
 		sectionId: section.id,
+		crossRoot: sourceCandidate.contentFile !== contentFile,
 	});
 	referencedImagePaths.add(sourcePath);
 
 	if (!shouldWrite) {
 		addSectionIssue(contentFile, section, {
 			severity: 'error',
-			message: `Image "${imageName}" is used here but is located in ${contentFile.imagesLabel}/${toPosixPath(path.relative(contentFile.imagesDir, sourcePath))}.`,
-			fix: 'Run norna content:sync to move it inside the current page or route image root.',
+			message: `Image "${imageName}" is used here but is located in ${getCandidateLabel(sourceCandidate)}.`,
+			fix: sourceCandidate.contentFile === contentFile
+				? 'Run norna content:sync to move it inside the current page or route image root.'
+				: `Run norna content:sync to move it from ${getRootLabel(sourceCandidate.contentFile)} to ${getRootLabel(contentFile)}. Cross-route sync requires a clean git working tree when files are moved.`,
 		});
 	}
 
@@ -302,6 +406,9 @@ const themeInlineStyleNames = themeFrontmatter
 
 const contentFiles = await getContentFiles();
 const allImageFiles = [];
+const contentFileContexts = [];
+const globalImageCandidatesByName = new Map();
+const globalExpectedReferencesByPath = new Map();
 
 for (const contentFile of contentFiles) {
 	const { frontmatter, body } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
@@ -314,11 +421,14 @@ for (const contentFile of contentFiles) {
 	const { sections } = getBodySections(body);
 	const sectionsById = new Map();
 	const blockResultsBySectionId = new Map();
-	const expectedReferencesByPath = new Map();
 	const imageCandidatesByName = await getImageCandidatesByName(contentFile.imagesDir);
 
-	for (const candidates of imageCandidatesByName.values()) {
-		allImageFiles.push(...candidates.map((imagePath) => ({ contentFile, imagePath })));
+	for (const [imageName, candidates] of imageCandidatesByName) {
+		for (const imagePath of candidates) {
+			const candidate = { contentFile, imagePath };
+			allImageFiles.push(candidate);
+			addGlobalImageCandidate(globalImageCandidatesByName, imageName, candidate);
+		}
 	}
 
 	for (const section of sections) {
@@ -354,13 +464,30 @@ for (const contentFile of contentFiles) {
 
 		for (const reference of getNornaBlockImageReferences(blockResults.blocks)) {
 			const expectedPath = getExpectedImagePath(contentFile, section.id, reference.image);
-			if (!expectedReferencesByPath.has(expectedPath)) {
-				expectedReferencesByPath.set(expectedPath, []);
-			}
-			expectedReferencesByPath.get(expectedPath).push({ section, reference });
+			addExpectedReference(globalExpectedReferencesByPath, expectedPath, { contentFile, section, reference });
 		}
 	}
 
+	contentFileContexts.push({
+		contentFile,
+		frontmatterIds,
+		sections,
+		sectionsById,
+		blockResultsBySectionId,
+		body,
+	});
+}
+
+for (const context of contentFileContexts) {
+	const {
+		contentFile,
+		frontmatterIds,
+		sections,
+		sectionsById,
+		blockResultsBySectionId,
+		body,
+	} = context;
+
 	for (const id of frontmatterIds) {
 		if (!sectionsById.has(id)) {
 			addContentIssue(contentFile, {
@@ -417,8 +544,8 @@ for (const contentFile of contentFiles) {
 				contentFile,
 				section,
 				reference,
-				imageCandidatesByName,
-				expectedReferencesByPath,
+				globalImageCandidatesByName,
+				globalExpectedReferencesByPath,
 			);
 			if (sourcePath) {
 				sourcePathsByImage.set(reference.image, sourcePath);
@@ -436,6 +563,12 @@ const unreferencedImages = allImageFiles
 	.map(({ contentFile, imagePath }) => `${contentFile.imagesLabel}/${toPosixPath(path.relative(contentFile.imagesDir, imagePath))}`)
 	.sort((left, right) => left.localeCompare(right, 'sv'));
 
+addConflictingMoveIssues();
+
+if (shouldWrite) {
+	await assertCleanGitForCrossRootSync(imageMoves);
+}
+
 if (hasErrors()) {
 	printReport(shouldWrite ? 'Content sync failed.' : 'Content check failed.', unreferencedImages);
 	process.exit(1);

package/scripts/test-content-check.mjs

@@ -129,7 +129,7 @@ test('content:check groups section issues, global issues, and unreferenced image
 		assert.match(output, /^Content check failed\./m);
 		assert.match(output, /Content Issues\n\n\[site\/content\.md \[min-konst\]\]\n  Errors:/);
 		assert.match(output, /Image "vav\.jpeg" is used here but is located in site\/images\/mitt-hem\/vav\.jpeg\./);
-		assert.match(output, /Image "missing\.jpeg" does not exist at site\/images\/min-konst\/missing\.jpeg or anywhere under site\/images\/\./);
+		assert.match(output, /Image "missing\.jpeg" does not exist at site\/images\/min-konst\/missing\.jpeg or anywhere under any page or route image root\./);
 		assert.match(output, /Unreferenced Images\nThese files are kept under page or route image roots but are not referenced by Norna-managed image references:/);
 		assert.match(output, /site\/images\/karin-walde\/unreferenced\.jpg/);
 	});

package/scripts/test-content-model-v2.mjs

@@ -73,6 +73,26 @@ typography:
 
 const fileExists = async (filePath) => access(filePath).then(() => true, () => false);
 
+const runGit = async (cwd, args) => execFileAsync('git', args, {
+	cwd,
+	env: {
+		...process.env,
+		GIT_AUTHOR_NAME: 'Norna Test',
+		GIT_AUTHOR_EMAIL: 'norna@example.test',
+		GIT_COMMITTER_NAME: 'Norna Test',
+		GIT_COMMITTER_EMAIL: 'norna@example.test',
+	},
+	maxBuffer: 1024 * 1024,
+});
+
+const initCleanGitWorktree = async (root) => {
+	await runGit(root, ['init']);
+	await runGit(root, ['config', 'user.email', 'norna@example.test']);
+	await runGit(root, ['config', 'user.name', 'Norna Test']);
+	await runGit(root, ['add', '.']);
+	await runGit(root, ['commit', '-m', 'initial']);
+};
+
 const createTempFixtureCopy = async () => {
 	const tempParent = path.join(repoRoot, 'node_modules', '.cache');
 	await mkdir(tempParent, { recursive: true });
@@ -310,7 +330,7 @@ description: Fixture
 		await assert.rejects(
 			() => runContentScript(siteDir, ['--check']),
 			(error) => {
-				assert.match(error.output, /Image "missing\.svg" does not exist at .*site\/images\/help\/missing\.svg or anywhere under .*site\/images\//);
+				assert.match(error.output, /Image "missing\.svg" does not exist at .*site\/images\/help\/missing\.svg or anywhere under any page or route image root\./);
 				return true;
 			},
 		);
@@ -493,6 +513,218 @@ description: Fixture
 	}
 });
 
+test('content:sync moves Norna-managed images across route image roots when git is clean', async () => {
+	const { root, siteDir } = await createTempSite();
+	try {
+		const sourceRouteDir = path.join(siteDir, 'routes', '010-source');
+		const targetRouteDir = path.join(siteDir, 'routes', '020-target');
+		await mkdir(path.join(sourceRouteDir, 'images', 'old'), { recursive: true });
+		await mkdir(targetRouteDir, { recursive: true });
+		await writeFile(path.join(siteDir, 'content.md'), `---
+title: Cross Route Sync
+description: Fixture
+---
+
+## Home {#home}
+
+Text.
+`);
+		await writeFile(path.join(sourceRouteDir, 'route-content.md'), `---
+title: Source
+description: Fixture
+---
+
+## Old {#old}
+
+Text.
+`);
+		await writeFile(path.join(targetRouteDir, 'route-content.md'), `---
+title: Target
+description: Fixture
+---
+
+## Work {#work}
+
+\`\`\`norna-image-stack
+- image: moved.jpg
+\`\`\`
+`);
+		await writeFile(path.join(sourceRouteDir, 'images', 'old', 'moved.jpg'), 'route image');
+		await initCleanGitWorktree(root);
+
+		await runContentScript(siteDir, ['--write', '--yes']);
+
+		assert.equal(await fileExists(path.join(targetRouteDir, 'images', 'work', 'moved.jpg')), true);
+		assert.equal(await fileExists(path.join(sourceRouteDir, 'images', 'old', 'moved.jpg')), false);
+	} finally {
+		await rm(root, { recursive: true, force: true });
+	}
+});
+
+test('content:sync refuses cross-route image moves when git status is dirty', async () => {
+	const { root, siteDir } = await createTempSite();
+	try {
+		const sourceRouteDir = path.join(siteDir, 'routes', '010-source');
+		const targetRouteDir = path.join(siteDir, 'routes', '020-target');
+		await mkdir(path.join(sourceRouteDir, 'images', 'old'), { recursive: true });
+		await mkdir(targetRouteDir, { recursive: true });
+		await writeFile(path.join(siteDir, 'content.md'), `---
+title: Dirty Cross Route Sync
+description: Fixture
+---
+
+## Home {#home}
+
+Text.
+`);
+		await writeFile(path.join(sourceRouteDir, 'route-content.md'), `---
+title: Source
+description: Fixture
+---
+
+## Old {#old}
+
+Text.
+`);
+		await writeFile(path.join(targetRouteDir, 'route-content.md'), `---
+title: Target
+description: Fixture
+---
+
+## Work {#work}
+
+\`\`\`norna-image-stack
+- image: moved.jpg
+\`\`\`
+`);
+		await writeFile(path.join(sourceRouteDir, 'images', 'old', 'moved.jpg'), 'route image');
+		await initCleanGitWorktree(root);
+		await writeFile(path.join(root, 'dirty.txt'), 'dirty');
+
+		await assert.rejects(
+			() => runContentScript(siteDir, ['--write', '--yes']),
+			(error) => {
+				assert.match(error.output, /Cross-route content sync requires a clean git working tree before moving files between page or route image roots\./);
+				assert.match(error.output, /dirty\.txt/);
+				return true;
+			},
+		);
+
+		assert.equal(await fileExists(path.join(targetRouteDir, 'images', 'work', 'moved.jpg')), false);
+		assert.equal(await fileExists(path.join(sourceRouteDir, 'images', 'old', 'moved.jpg')), true);
+	} finally {
+		await rm(root, { recursive: true, force: true });
+	}
+});
+
+test('content:check reports cross-route image moves without requiring clean git status', async () => {
+	const { root, siteDir } = await createTempSite();
+	try {
+		const sourceRouteDir = path.join(siteDir, 'routes', '010-source');
+		const targetRouteDir = path.join(siteDir, 'routes', '020-target');
+		await mkdir(path.join(sourceRouteDir, 'images', 'old'), { recursive: true });
+		await mkdir(targetRouteDir, { recursive: true });
+		await writeFile(path.join(siteDir, 'content.md'), `---
+title: Cross Route Check
+description: Fixture
+---
+
+## Home {#home}
+
+Text.
+`);
+		await writeFile(path.join(sourceRouteDir, 'route-content.md'), `---
+title: Source
+description: Fixture
+---
+
+## Old {#old}
+
+Text.
+`);
+		await writeFile(path.join(targetRouteDir, 'route-content.md'), `---
+title: Target
+description: Fixture
+---
+
+## Work {#work}
+
+\`\`\`norna-image-stack
+- image: moved.jpg
+\`\`\`
+`);
+		await writeFile(path.join(sourceRouteDir, 'images', 'old', 'moved.jpg'), 'route image');
+		await writeFile(path.join(root, 'dirty.txt'), 'dirty');
+
+		await assert.rejects(
+			() => runContentScript(siteDir, ['--check']),
+			(error) => {
+				assert.match(error.output, /Image "moved\.jpg" is used here but is located in .*site\/routes\/010-source\/images\/old\/moved\.jpg\./);
+				assert.match(error.output, /Run norna content:sync to move it from .*site\/routes\/010-source to .*site\/routes\/020-target\./);
+				assert.doesNotMatch(error.output, /requires a clean git working tree before moving files/);
+				return true;
+			},
+		);
+	} finally {
+		await rm(root, { recursive: true, force: true });
+	}
+});
+
+test('content:sync refuses to move a cross-route image still referenced by its current section', async () => {
+	const { root, siteDir } = await createTempSite();
+	try {
+		const sourceRouteDir = path.join(siteDir, 'routes', '010-source');
+		const targetRouteDir = path.join(siteDir, 'routes', '020-target');
+		await mkdir(path.join(sourceRouteDir, 'images', 'old'), { recursive: true });
+		await mkdir(targetRouteDir, { recursive: true });
+		await writeFile(path.join(siteDir, 'content.md'), `---
+title: Cross Route Copy
+description: Fixture
+---
+
+## Home {#home}
+
+Text.
+`);
+		await writeFile(path.join(sourceRouteDir, 'route-content.md'), `---
+title: Source
+description: Fixture
+---
+
+## Old {#old}
+
+\`\`\`norna-image-stack
+- image: shared.jpg
+\`\`\`
+`);
+		await writeFile(path.join(targetRouteDir, 'route-content.md'), `---
+title: Target
+description: Fixture
+---
+
+## Work {#work}
+
+\`\`\`norna-image-stack
+- image: shared.jpg
+\`\`\`
+`);
+		await writeFile(path.join(sourceRouteDir, 'images', 'old', 'shared.jpg'), 'route image');
+
+		await assert.rejects(
+			() => runContentScript(siteDir, ['--write', '--yes']),
+			(error) => {
+				assert.match(error.output, /Cannot relocate "shared\.jpg" from .*site\/routes\/010-source\/images\/old\/shared\.jpg because it is still referenced from .*site\/routes\/010-source\/route-content\.md \[old\]\./);
+				return true;
+			},
+		);
+
+		assert.equal(await fileExists(path.join(targetRouteDir, 'images', 'work', 'shared.jpg')), false);
+		assert.equal(await fileExists(path.join(sourceRouteDir, 'images', 'old', 'shared.jpg')), true);
+	} finally {
+		await rm(root, { recursive: true, force: true });
+	}
+});
+
 test('CLI content:sync refreshes generated images after moving a carousel image', async () => {
 	const { root, siteDir } = await createTempSite();
 	try {
@@ -773,8 +1005,8 @@ image broken.jpg
 			() => runContentScript(siteDir, ['--check']),
 			(error) => {
 				assert.match(error.output, /Invalid norna-image-stack entry "image broken\.jpg"\. Start each image with "- image: filename\.jpg"\./);
-				assert.match(error.output, /Image "missing-intro\.jpg" does not exist at .*site\/images\/intro\/missing-intro\.jpg or anywhere under .*site\/images\//);
-				assert.match(error.output, /Image "missing-more\.jpg" does not exist at .*site\/images\/more\/missing-more\.jpg or anywhere under .*site\/images\//);
+				assert.match(error.output, /Image "missing-intro\.jpg" does not exist at .*site\/images\/intro\/missing-intro\.jpg or anywhere under any page or route image root\./);
+				assert.match(error.output, /Image "missing-more\.jpg" does not exist at .*site\/images\/more\/missing-more\.jpg or anywhere under any page or route image root\./);
 				return true;
 			},
 		);
@@ -826,7 +1058,7 @@ description: Fixture
 			() => runContentScript(siteDir, ['--check']),
 			(error) => {
 				assert.match(error.output, /norna-image-carousel on line \d+ contains 1 image\. A carousel needs at least two images\./);
-				assert.match(error.output, /Image "foo\.jpg" does not exist at .*site\/images\/plain\/foo\.jpg or anywhere under .*site\/images\//);
+				assert.match(error.output, /Image "foo\.jpg" does not exist at .*site\/images\/plain\/foo\.jpg or anywhere under any page or route image root\./);
 				return true;
 			},
 		);
@@ -854,7 +1086,7 @@ description: Fixture
 		await assert.rejects(
 			() => runContentScript(siteDir, ['--check']),
 			(error) => {
-				assert.match(error.output, /Image "missing\.jpg" does not exist at .*site\/images\/intro\/missing\.jpg or anywhere under .*site\/images\//);
+				assert.match(error.output, /Image "missing\.jpg" does not exist at .*site\/images\/intro\/missing\.jpg or anywhere under any page or route image root\./);
 				return true;
 			},
 		);
@@ -919,7 +1151,7 @@ Text.
 	}
 });
 
-test('content:sync refuses ambiguous page-local image relocation', async () => {
+test('content:sync refuses ambiguous image relocation', async () => {
 	const { root, siteDir } = await createTempSite();
 	try {
 		await writeFile(path.join(siteDir, 'content.md'), `---

package/starters/basic/README.md

@@ -17,8 +17,10 @@ npm run dev -- --kill
 
 Edit site-wide visual defaults in `site/theme.md`, homepage content and section
 overrides in `site/content.md`, technical settings such as URL and locale
-labels in `site/config.mjs`, source images under
-`site/images/<section-id>/`, and static public files under `site/public/`.
+labels in `site/config.mjs`, source images under `site/images/<section-id>/`,
+and static public files under `site/public/`. The image folder name should
+match the section id in Markdown, for example `## Work {#work}` uses
+`site/images/work/`.
 
 Use `site.basePath: '/'` for a custom domain or root-hosted site. For a GitHub
 Pages project site without a custom domain, set both values:

package/starters/basic/site/content.md

@@ -1,12 +1,6 @@
 ---
 title: Example Site
 description: Minimal norna starter site.
-sections:
-  intro:
-    presentation:
-      typography:
-        preset: statement
-
 ---
 
 ## Intro {#intro}
@@ -15,8 +9,8 @@ routes defined, the navigation menu will be a sticky bar with anchor links for
 ease of use on phones etc. [Highlighted inline text]{.highlight} when a short
 phrase needs emphasis
 ## Work {#work}
-Add Norna image blocks in Markdown and matching source images under
-`images/work/`.
+Add Norna managed media blocks in Markdown where the media should appear. Put
+matching source images under `images/work/`.
 
 ````
 ```norna-image-stack

package/starters/project/README.md

@@ -23,7 +23,8 @@ npm run dev -- --kill
 - `site/theme.md`: site-wide visual settings such as brand text, layout
   density, typography rhythm, colors, frame colors, and inline text styles.
 - `site/content.md`: homepage title, sections, placeholders, project summary,
-  links, install command, example usage, benefits, next steps, and license.
+  links, install command, example usage, benefits, next steps, managed media
+  blocks, and license.
 - `site/routes/010-guide/route-content.md`: short secondary page with realistic
   project guide content.
 - `site/public/robots.txt`: static public file copied into the built site.
@@ -40,15 +41,18 @@ GitHub Pages workflow uses `npm ci`.
    delete the route if the homepage is enough.
 3. Edit `site/theme.md` for brand name, layout density, typography rhythm,
    colors, frame colors, and inline text styles.
-4. Edit `site/config.mjs` for public URL, GitHub repository, footer text, and
+4. Put any local source images in the image folder for the Markdown section
+   that references them, for example `site/images/intro/`.
+5. Edit `site/config.mjs` for public URL, GitHub repository, footer text, and
    deploy workflow name.
-5. Update `package.json` with the site's package name and keep
+6. Update `package.json` with the site's package name and keep
    `package-lock.json` committed.
 
 ## Common Commands
 
 ```sh
 npm run norna:check
+npm run norna:sync
 npm run norna:typography:show
 npm run build
 ```