@janga/norna 0.7.13 → 0.7.15

package/README.md

@@ -30,7 +30,7 @@ You need Node.js 22.12 or later.
 npx @janga/norna@latest init my-site
 cd my-site
 npm install
-npm run dev
+npm run norna:dev
 ```
 
 Open the URL printed by the development server, then edit the files under
@@ -40,13 +40,18 @@ scripts and GitHub Pages workflow needed to check, build, and publish it.
 Follow the [five-minute tutorial](docs/getting-started.md) for a first edit and
 verified build.
 
+For shorter commands, install the launcher globally with
+`npm install --global @janga/norna@latest`. You can then use `norna dev`,
+`norna check`, and `norna build`; inside a project, the launcher selects its
+locally installed and pinned Norna version.
+
 ## The Site Model
 
 ```text
 site/
-|-- config.md
-|-- theme.md
-|-- sitewide-content.md
+|-- config.yaml
+|-- theme.yaml
+|-- sitewide-content.yaml
 |-- content.md
 |-- images/
 |-- routes/
@@ -56,9 +61,9 @@ site/
 - `content.md` holds the homepage and its sections.
 - `images/` holds managed source images beside the content they belong to.
 - `routes/` adds pages, each with content and optional local images and theme.
-- `theme.md` normally selects one complete visual preset.
-- `sitewide-content.md` holds shared identity, banners, and footer content.
-- `config.md` holds the public URL and optional language and scroll behavior.
+- `theme.yaml` normally selects one complete visual preset.
+- `sitewide-content.yaml` holds shared identity, banners, and footer content.
+- `config.yaml` holds the public URL and optional language and scroll behavior.
 - `public/` holds static files copied without processing.
 
 Norna validates this structure, processes managed images when needed, and
@@ -119,10 +124,11 @@ engine diagnostics, not for ordinary editing and local preview. See
 ## Documentation
 
 - [Five-minute tutorial](docs/getting-started.md)
+- [Site files](docs/site-files.md)
 - [Task-oriented documentation map](docs/README.md)
-- [How-to guides](docs/README.md#how-to-guides)
+- [Common workflows](docs/README.md#common-workflows)
 - [Concepts and explanation](docs/README.md#concepts-and-explanation)
-- [Technical reference](docs/README.md#reference)
+- [Command and platform reference](docs/README.md#command-and-platform-reference)
 - [Troubleshooting](docs/README.md#troubleshooting)
 - [AI-readable documentation index](https://janga.github.io/norna/llms.txt)
 

package/bin/norna-cli.mjs

@@ -14,11 +14,13 @@ Commands:
   dev:status             Show local dev server status
   dev:logs               Show local dev server logs
   dev:stop               Stop local dev server
-  config:check           Validate site/config.md
+  check                  Validate configuration and content
+  config:check           Validate site/config.yaml
   content:check          Validate site/content.md and image references
   content:sync           Move misplaced Norna-managed images and refresh generated images
+  theme:presets          List available theme presets and their intended uses
   theme:export           Export a commented theme preset reference
-  typography presets     Show built-in typography preset values
+  typography profiles    Show built-in typography profile values
   typography show        Show resolved typography for the selected site
   site:public            Sync site/public/ to public/
   images                 Generate optimized image variants
@@ -125,6 +127,9 @@ try {
 		await runScript('scripts/dev-local.mjs', ['logs', ...rest]);
 	} else if (command === 'dev:stop') {
 		await runScript('scripts/dev-local.mjs', ['stop', ...rest]);
+	} else if (command === 'check') {
+		await runScript('scripts/check-config.mjs', rest);
+		await runScript('scripts/sync-content-sections.mjs', ['--check', ...rest]);
 	} else if (command === 'config:check') {
 		await runScript('scripts/check-config.mjs', rest);
 	} else if (command === 'content:check') {
@@ -132,11 +137,13 @@ try {
 	} else if (command === 'content:sync') {
 		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
 		await runScript('scripts/generate-images.mjs', rest);
+	} else if (command === 'theme:presets') {
+		await runScript('scripts/list-theme-presets.mjs', rest);
 	} else if (command === 'theme:export') {
 		await runScript('scripts/export-theme-preset.mjs', rest);
-	} else if (command === 'typography:presets' || (command === 'typography' && subcommand === 'presets')) {
+	} else if (command === 'typography:profiles' || (command === 'typography' && subcommand === 'profiles')) {
 		const scriptArgs = command === 'typography' ? subcommandRest : rest;
-		await runScript('scripts/show-typography.mjs', ['presets', ...scriptArgs]);
+		await runScript('scripts/show-typography.mjs', ['profiles', ...scriptArgs]);
 	} else if (command === 'typography:show' || (command === 'typography' && subcommand === 'show')) {
 		const scriptArgs = command === 'typography' ? subcommandRest : rest;
 		await runScript('scripts/show-typography.mjs', ['show', ...scriptArgs]);

package/docs/README.md

@@ -1,23 +1,59 @@
 # Norna Documentation
 
-Use this page to choose documentation by what you are trying to accomplish.
-The [Norna introduction site](https://janga.github.io/norna/) explains the
-product; these Markdown files provide the tutorial, task guides, explanation,
-and exact reference.
+The [Norna introduction site](https://janga.github.io/norna/) explains what the
+tool is for. These Markdown files are the authoritative tutorial, workflow
+guides, and reference.
 
 ## Start Here
 
 1. [Build your first Norna site](getting-started.md) follows one short path from
    an empty directory to a checked build.
-2. [Requirements and limitations](requirements.md) states what must be
-   installed and what Norna does and does not support today.
-3. [Examples](../examples/README.md) pairs complete and focused source projects
-   with their rendered sites.
+2. [Site Files](site-files.md) is the canonical map of every source file,
+   convention-based directory, and generated location.
+3. [Requirements and limitations](requirements.md) lists required software and
+   current product boundaries.
+4. [Examples](../examples/README.md) pairs complete and focused source projects
+   with rendered sites.
 
 Do not read the reference from beginning to end before trying Norna. Complete
-the tutorial, then use the task links below when a real site needs them.
-
-## How-To Guides
+the tutorial, then open the reference for the file or workflow you are changing.
+
+## Site File Reference
+
+Norna expects this top-level source model:
+
+```text
+site/
+|-- config.yaml
+|-- theme.yaml
+|-- sitewide-content.yaml
+|-- content.md
+|-- images/
+|-- routes/
+`-- public/
+```
+
+- [`config.yaml`](configuration.md): public URL, language, and native browser
+  scroll behavior.
+- [`theme.yaml`](theme.md): complete visual presets and focused presentation
+  overrides.
+- [`sitewide-content.yaml`](sitewide-content.md): shared navigation identity,
+  banners, and footer.
+- [`content.md`](content.md): page metadata, sections, prose, notes, and Norna
+  blocks.
+- [`images/`](images-and-metadata.md): managed source formats, variants, sync,
+  and generated image state.
+- [`routes/`](routes.md): additional pages, ordering, URLs, route themes, and
+  route-local images.
+- [`public/`](public-files.md): navigation logos, favicons, and other static
+  files copied without managed-image processing.
+- [Generated files](site-files.md#generated-files): `site/.norna/public/`,
+  `dist/`, and `.astro/`.
+
+The [complete Site Files reference](site-files.md) explains which paths are
+required, optional, convention-discovered, versioned, or generated.
+
+## Common Workflows
 
 ### Create And Run A Site
 
@@ -26,22 +62,23 @@ the tutorial, then use the task links below when a real site needs them.
 - [Start and manage local preview](local-development.md)
 - [Inspect or update the installed engine](commands.md#command-summary)
 
-### Write And Organise Content
+### Write Content
 
 - [Write page sections](content.md#sections)
-- [Use image stacks, carousels, and cards](content.md#managed-media-blocks)
+- [Use image stacks, carousels, and cards](content.md#norna-blocks)
 - [Add notes to prose](content.md#markdown-text)
 - [Add another page](routes.md)
-- [Add shared identity, banners, and a footer](sitewide-content.md)
+- [Add shared banners or footer content](sitewide-content.md)
 
-### Work With Images
+### Work With Images And Public Assets
 
 - [Add managed source images](images-and-metadata.md#managed-source-images)
-- [Place image blocks in Markdown](content.md#managed-media-blocks)
 - [Check and sync moved image references](content.md#validation-and-sync)
-- [Understand generated variants and SVG handling](images-and-metadata.md#generated-variants-and-static-svg)
+- [Add a navigation logo](public-files.md#navigation-logo)
+- [Add favicons](public-files.md#logos-and-favicons)
+- [Add other static files](public-files.md#other-static-files)
 
-### Change The Presentation
+### Change Presentation
 
 - [Choose a complete theme preset](theme.md#theme-presets)
 - [Inspect and override a preset](theme.md#overrides)
@@ -50,37 +87,28 @@ the tutorial, then use the task links below when a real site needs them.
 
 ### Check, Build, And Publish
 
-- [Run content and configuration checks](commands.md#starter-npm-scripts)
-- [Build and inspect generated output](site-structure.md#generated-files)
-- [Publish through the included GitHub Pages workflow](publishing.md#github-pages-workflow)
-- [Monitor or troubleshoot a deployment](publishing.md)
+- [Run configuration and content checks](commands.md#starter-npm-scripts)
+- [Build and inspect generated output](site-files.md#generated-files)
+- [Publish through GitHub Pages](publishing.md#github-pages-workflow)
+- [Monitor or troubleshoot deployment](publishing.md)
 
 ## Concepts And Explanation
 
 - [Norna's site model](https://janga.github.io/norna/concepts/) explains how
   files, sections, images, and routes become a website.
-- [Site Structure](site-structure.md) separates source files, generated files,
-  examples, fixtures, and engine code.
-- [Images and Metadata](images-and-metadata.md) explains why Norna manages image
-  variants and published URLs.
-- [Command Organization](design/command-organization.md) explains the command
-  model for standalone sites, embedded sites, and engine development.
-- [Site Examples Structure](design/site-examples-structure.md) explains the
-  difference between starters, examples, documentation sites, and fixtures.
-
-## Reference
-
-- [Configuration](configuration.md): `site/config.md` fields and defaults.
-- [Sitewide Content](sitewide-content.md): shared identity, banners, and footer.
-- [Content](content.md): page frontmatter, sections, blocks, notes, and checks.
-- [Theme](theme.md): presets, overrides, layout, image sizing, and surfaces.
-- [Typography](typography.md): typography roles, rhythms, and inspection.
-- [Routes](routes.md): directory names, route IDs, URLs, and route images.
-- [Images and Metadata](images-and-metadata.md): source formats, variants, and
-  generated manifests.
-- [Commands](commands.md): CLI commands, npm scripts, options, and exit behavior.
+- [Images and Metadata](images-and-metadata.md) explains managed variants and
+  published URLs.
+- [Command Organization](design/command-organization.md) explains standalone,
+  embedded, and engine-development command models.
+- [Site Examples Structure](design/site-examples-structure.md) distinguishes
+  starters, examples, documentation sites, and fixtures.
+
+## Command And Platform Reference
+
+- [Commands](commands.md): CLI commands, npm scripts, and options.
 - [Requirements and limitations](requirements.md): runtime dependencies,
-  optional tools, and current product boundaries.
+  optional tools, and current boundaries.
+- [Publishing](publishing.md): GitHub Pages workflow and deploy helpers.
 
 ## Troubleshooting
 

package/docs/commands.md

@@ -10,8 +10,17 @@ inside a project that declares and has installed its own `@janga/norna`
 dependency, the launcher delegates to that project-local version. If no
 project-local install is found, the version that was started continues running.
 
-Use direct `norna ...` commands only when the binary is on your shell `PATH`,
-inside an npm script, or through `npm exec -- norna ...`.
+The project-owned `norna:*` npm scripts are the portable default for both
+standalone and embedded sites. To use direct commands from an ordinary shell,
+install the launcher once:
+
+```sh
+npm install --global @janga/norna@latest
+```
+
+You can then use commands such as `norna dev`, `norna check`, and
+`norna build`. The launcher still delegates to the current project's locally
+installed and pinned Norna version.
 
 ## CLI Commands
 
@@ -22,17 +31,19 @@ norna dev:restart
 norna dev:status
 norna dev:logs
 norna dev:stop
+norna check
 norna config:check
 norna content:check
 norna content:sync
+norna theme:presets
 norna theme:export <preset>
-norna typography presets
+norna typography profiles
 norna typography show
 norna site:public
 norna images
 norna engine:update [version|latest]
 norna engine:version [--latest]
-norna init <target-dir> [--type pure|embedded] [--site-dir <path>]
+norna init <target-dir> [--type standalone|embedded] [--site-dir <path>]
 norna build
 norna build:local
 norna deploy
@@ -50,8 +61,9 @@ norna --site-dir <path> <command>
 norna --help
 ```
 
-`norna dev` is accepted as an alias for `dev:local`. `help`, `-h`, and
-`--help` print usage.
+`norna dev` is accepted as an alias for `dev:local`. `norna check` runs the
+configuration and content checks in sequence. `help`, `-h`, and `--help` print
+usage.
 
 ## Starter npm Scripts
 
@@ -59,10 +71,9 @@ The starter uses `norna:*` for norna-specific work. This avoids collisions
 when a Norna site is embedded inside a larger GitHub project
 whose own `build`, `test`, or deploy scripts mean something different.
 
-The starter defines:
+The stable project scripts are:
 
 ```sh
-npm run dev
 npm run norna:dev
 npm run norna:dev:lan
 npm run norna:dev:restart
@@ -73,8 +84,9 @@ npm run norna:check
 npm run norna:config:check
 npm run norna:content:check
 npm run norna:sync
+npm run norna:theme:presets
 npm run norna:theme:export -- <preset>
-npm run norna:typography:presets
+npm run norna:typography:profiles
 npm run norna:typography:show
 npm run norna:public
 npm run norna:images
@@ -87,11 +99,10 @@ npm run norna:doctor
 npm run norna:preview
 npm run norna:engine:update
 npm run norna:engine:version
-npm run build
 ```
 
-`npm run dev` calls `npm run norna:dev`. In the pure starter,
-`npm run build` aliases `npm run norna:build`. In mixed repositories, such as
+The standalone starter also provides `npm run dev` and `npm run build` as
+convenience aliases. In mixed repositories, such as
 a GitHub project that embeds a Norna site next to an app, `build`
 should normally mean the repository's complete publishable artifact, while
 `norna:build` builds only the `norna` part.
@@ -101,19 +112,22 @@ should normally mean the repository's complete publishable artifact, while
 - `doctor`: prints resolved engine root, site project root, site directory,
   content/config/image/public paths, generated manifest, Astro output paths, and
   cache path.
-- `config:check`: validates `site/config.md` against the runtime config
+- `config:check`: validates `site/config.yaml` against the runtime config
   reader.
-- `content:check`: validates section structure, managed media references,
+- `check`: runs `config:check` followed by `content:check`.
+- `content:check`: validates section structure, Norna block references,
   inline styles, and common content mistakes.
 - `content:sync` / `norna:sync`: moves misplaced referenced image files after
   confirmation when the intended move is unambiguous. Moving files between the
   homepage and routes, or between routes, requires a clean Git working tree.
+- `theme:presets`: lists the available complete theme presets and explains the
+  intended use of each one.
 - `theme:export <preset>`: writes a protected, commented
-  `orig-<preset>-theme.md` reference under the selected site directory. The
+  `orig-<preset>-theme.yaml` reference under the selected site directory. The
   available complete theme presets are `portfolio`, `documentation`,
-  `project`, and `statement`. Norna continues to load only `theme.md`.
-- `typography presets`: prints the exact built-in values for typography
-  presets and rhythms.
+  `project`, and `statement`. Norna continues to load only `theme.yaml`.
+- `typography profiles`: prints the exact built-in values for typography
+  profiles and rhythms.
 - `typography show`: prints the selected site's resolved typography for the
   theme, every page route, and every section. Each value includes its source,
   and inherited page or section values are marked with `inherited: true`.
@@ -131,10 +145,10 @@ should normally mean the repository's complete publishable artifact, while
 - `engine:version [--latest]`: prints the declared site dependency, installed
   engine version, engine root, Astro dependency, and installed Astro version.
   With `--latest`, it also asks npm for the latest published engine version.
-- `init <target-dir> [--type pure|embedded] [--site-dir <path>]`: creates a
+- `init <target-dir> [--type standalone|embedded] [--site-dir <path>]`: creates a
   standalone site project from the packaged starter, or adds a Norna site
   directory plus `norna:*` scripts to an existing project in embedded mode.
-  Pure setup pins `@janga/norna` to the version that created it.
+  Standalone setup pins `@janga/norna` to the version that created it.
 - `build`: runs config check, content check, public sync, image generation, and
   Astro build.
 - `build:local`: runs `build` and restarts `dev:local`.

package/docs/configuration.md

@@ -1,138 +1,119 @@
-# Configuration
+# `config.yaml`
 
-Technical site configuration lives in the selected site's `config.md`; by
-default that is `site/config.md`. The file contains YAML frontmatter only.
+Technical site configuration lives in the selected site's `config.yaml`; by
+default that is `site/config.yaml`. The file is required and contains plain
+YAML without Markdown frontmatter delimiters.
 
 A normal configuration needs only the public URL:
 
 ```yaml
----
 url: https://example.com/
----
 ```
 
 Norna deliberately keeps this file small. Visual choices belong in
-`theme.md`; shared identity, banners and footer content belong in
-`sitewide-content.md`.
+[`theme.yaml`](theme.md), shared editorial content belongs in
+[`sitewide-content.yaml`](sitewide-content.md), and page content belongs in
+[`content.md`](content.md).
 
 ## `url`
 
-- Purpose: canonical public URL and the source of the site's deployment path.
+- Purpose: canonical public URL and source of the site's deployment path.
 - Type: absolute `http` or `https` URL.
 - Required: yes.
 - Default: none.
 - Restrictions: no query string or fragment.
 
-Norna adds a trailing slash when it is omitted. The URL pathname becomes the
-base path for generated links, favicons and managed images, so there is no
+Norna adds a trailing slash when omitted. The URL pathname becomes the base
+path for generated links, browser icons, and managed images, so there is no
 separate `basePath` setting.
 
 Root-hosted site or custom domain:
 
 ```yaml
----
 url: https://example.com/
----
 ```
 
 GitHub Pages project site:
 
 ```yaml
----
 url: https://owner.github.io/repository-name/
----
 ```
 
 In the second example, Norna derives `/repository-name/` as the base path.
-Root-relative links written in Markdown are prefixed when rendered.
+Root-relative Markdown links are prefixed when rendered.
 
 ## `language`
 
-- Purpose: language tag rendered on the root `<html lang="...">` element and
-  selection of Norna's built-in interface text.
-- Type: language tag such as `en`, `en-GB`, `sv` or `sv-SE`.
+- Purpose: language tag on the root `<html lang="...">` element and selection
+  of Norna's built-in interface text.
+- Type: `en`, `sv`, or a regional tag such as `en-GB` or `sv-SE`.
 - Required: no.
 - Default: `en`.
 
-Norna currently includes interface text for English and Swedish. Regional tags
-use the language identified by their primary subtag. An unsupported language is
-an error because silently rendering English controls on another-language pages
+Norna includes interface text for English and Swedish. Regional tags use the
+language identified by their primary subtag. An unsupported language is an
+error because silently rendering English controls on another-language page
 would be misleading.
 
 Interface labels are part of the engine and are not configured individually.
-Editorial text remains in `content.md`, route content files and
-`sitewide-content.md`.
+Editorial text remains in page content and `sitewide-content.yaml`.
 
-## `smoothScroll`
+## `scrollBehavior`
 
-- Purpose: enables smooth same-page anchor movement.
-- Type: boolean.
+- Purpose: select native same-page anchor movement.
+- Type: `instant` or `smooth`.
 - Required: no.
-- Default: `false`.
+- Default: `instant`.
 
-Example:
+Example using the browser's native smooth scrolling:
 
 ```yaml
----
 url: https://example.com/
-smoothScroll: true
----
+scrollBehavior: smooth
 ```
 
-Norna uses the browser's native CSS scrolling behavior rather than a scripted
-animation. Visitors whose system requests reduced motion always get immediate
-anchor movement.
+Norna does not add a scripted scrolling implementation. Visitors whose system
+requests reduced motion always get immediate anchor movement.
 
 ## Complete Example
 
 ```yaml
----
 url: https://example.com/
-language: en
-smoothScroll: false
----
+language: en-GB
+scrollBehavior: instant
 ```
 
-Do not add Markdown below the closing `---`; `config.md` is frontmatter-only.
-Run `npm run norna:config:check` after changing it.
-
-## Related Files
-
-- [`theme.md`](theme.md) selects a complete presentation preset and optional
-  focused overrides.
-- [`sitewide-content.md`](sitewide-content.md) contains shared identity,
-  banners and footer content.
-- [`content.md`](content.md) and route content files contain page content.
+Run `norna config:check` after changing the file.
 
 ## Publishing Discovery
 
-GitHub repository, default branch and deploy workflow are not site
-configuration fields.
+GitHub repository, default branch, and deploy workflow are not fields in
+`config.yaml`.
 
-`norna deploy` discovers the current GitHub repository and its default branch
+`norna deploy` discovers the current GitHub repository and default branch
 through the authenticated GitHub CLI. Norna's included workflow file is
 `.github/workflows/deploy.yml`. `deploy:watch` accepts command-line overrides
-such as `--repo`, `--branch`, `--workflow`, `--interval`, `--timeout` and
-`--limit` when a one-off run needs different values.
+when a one-off run needs different operational values.
 
 See [Publishing](publishing.md) for the complete workflow.
 
 ## Site Directory Selection
 
-The site directory is not configured in `config.md`.
+The site directory is not configured in `config.yaml`.
 
 Use one of:
 
 ```sh
-NORNA_SITE_DIR=my-site npm run norna:build
-norna --site-dir my-site build
+NORNA_SITE_DIR=presentation norna build
+norna --site-dir presentation build
 ```
 
 If `NORNA_SITE_DIR` is set to an empty value, commands fail. Relative site
-directories are resolved by walking upward from the invocation root until the
-selected directory contains `config.md` and `content.md`. Absolute site
-directories are accepted and make their parent the site project root.
+directories are resolved by walking upward from the invocation directory until
+the selected directory contains `config.yaml` and `content.md`.
+
+Without an explicit selection, the current directory itself can be the site
+directory when it contains those two files. Otherwise Norna walks upward for a
+default `site/` directory containing them.
 
-When no site directory is explicitly selected, the current directory itself
-can be the site directory if it contains `config.md` and `content.md`. If not,
-Norna walks upward looking for a default `site/` directory with those files.
+See [Site Files](site-files.md) for the complete source and generated layout.

package/docs/content.md

@@ -4,10 +4,10 @@
 metadata in frontmatter and the homepage content in Markdown.
 
 Route pages use the same page model in
-`site/routes/<NNN-route-id>/route-content.md`. See [Routes](routes.md) for the
+`site/routes/<NNN-route-id>/content.md`. See [Routes](routes.md) for the
 route-specific rules.
 
-Site-wide visual defaults belong in [Theme](theme.md). Typography presets and
+Site-wide visual defaults belong in [Theme](theme.md). Typography profiles and
 overrides are described in [Typography](typography.md). Technical site settings
 belong in [Configuration](configuration.md).
 
@@ -90,7 +90,7 @@ page file:
 Do not list sections in frontmatter just to define order. Section order comes
 from the Markdown heading order.
 
-## Managed Media Blocks
+## Norna Blocks
 
 Norna-managed local images and cards are written in Markdown fenced blocks at
 the point where they should appear in the section. Markdown determines
@@ -207,7 +207,7 @@ Route images live under:
 site/routes/<NNN-route-id>/images/<section-id>/
 ```
 
-Image references in Norna managed media blocks use only the filename:
+Image references in Norna managed image blocks use only the filename:
 
 ````md
 ```norna-image-stack
@@ -277,9 +277,36 @@ This sentence contains **important text** and *emphasised text*.
 
 Norna intentionally does not support arbitrary inline color or style classes.
 Deprecated syntax such as `[highlighted text]{.yellow}` is rejected by
-`content:check`. Keep the route visually coherent through its `theme.md`
+`content:check`. Keep the route visually coherent through its `theme.yaml`
 instead of styling individual phrases.
 
+### Side Notes
+
+Add one numbered side note to a paragraph by placing `{note-ref}` where its
+reference number should appear, then write the matching note on its own line
+immediately after the paragraph:
+
+```md
+Norna keeps the page source readable.{note-ref}
+
+{note: The note appears in the margin when enough horizontal space is available.}
+```
+
+Longer notes may wrap across lines and end with `}` on its own line:
+
+```md
+Norna keeps the page source readable.{note-ref}
+
+{note:
+The note may contain a longer explanation when the extra context is useful.
+}
+```
+
+On wide screens Norna places the note in the reading margin. On narrower
+screens it remains in the normal reading flow. A paragraph may contain one
+note pair; both `{note-ref}` and `{note: ...}` are required. `content:check`
+reports missing, repeated, nested, or unpaired note syntax.
+
 ## Validation And Sync
 
 Run:
@@ -290,7 +317,7 @@ 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 managed media blocks, unreferenced images, removed inline style syntax,
+invalid Norna blocks, unreferenced images, removed inline style syntax,
 Markdown image references to unmanaged local files, and common frontmatter
 indentation and structure mistakes.
 
@@ -308,7 +335,7 @@ sections:
 
 Top-level page frontmatter may contain only `title`, `description`,
 `navigation`, and `sections`. Visual settings belong in the root or route-local
-`theme.md`.
+`theme.yaml`.
 
 Run: