@janga/norna 0.7.13 → 0.7.15

package/docs/design/command-organization.md

@@ -49,6 +49,13 @@ interface. They may provide unprefixed aliases when the alias means the same
 thing for the whole repository, for example `npm run build` as an alias for
 `npm run norna:build`.
 
+### Direct CLI Shortcut
+
+Users may install `@janga/norna` globally as a cross-platform launcher and use
+`norna dev`, `norna check`, or `norna build`. The launcher must delegate to the
+current project's installed Norna version, so this shortcut does not replace
+the project dependency or its lockfile.
+
 ### Project Commands That Call Norna Commands
 
 `norna` does not define a consuming project's unprefixed commands. Names
@@ -174,17 +181,17 @@ npx @janga/norna@latest init my-site
 The initializer should support two setup modes that share the same `norna:*`
 command vocabulary.
 
-#### Pure Setup
+#### Standalone Setup
 
-Pure setup creates a new project where the Norna site is the whole repository:
+Standalone setup creates a new project where the Norna site is the whole repository:
 
 ```sh
-npx @janga/norna@latest init my-site --type pure
+npx @janga/norna@latest init my-site --type standalone
 ```
 
 This should be the default when the target is a new or empty directory.
 
-Pure setup should create:
+Standalone setup should create:
 
 - a normal site source directory, normally `site/`;
 - a `package.json` with `norna:*` scripts;
@@ -271,13 +278,13 @@ Commands that inspect site presentation without changing source files use
 `norna:*` in consuming repositories:
 
 ```sh
-npm run norna:typography:presets
+npm run norna:typography:profiles
 npm run norna:typography:show
 ```
 
-`norna:typography:presets` shows the built-in typography presets and rhythms
+`norna:typography:profiles` shows the built-in typography profiles and rhythms
 from the installed engine. `norna:typography:show` shows the effective
-typography for the selected site after presets, rhythms, and overrides have
+typography for the selected site after profiles, rhythms, and overrides have
 been applied.
 
 ### Correct Content And Configuration
@@ -295,7 +302,7 @@ Messages emitted by the engine should mention the direct CLI command and the
 starter-style npm wrapper when suggesting a fix.
 
 Configuration edits are normally manual edits to the selected site
-`config.md`, followed by:
+`config.yaml`, followed by:
 
 ```sh
 npm run norna:config:check

package/docs/design/norna-diagram-design.md

@@ -67,18 +67,18 @@ Diagrams must match the current Norna model:
 
 - A Norna site is described with site files, not arbitrary project structure.
 - `content.md` is the homepage content file.
-- `sitewide-content.md` contains shared site identity, banners, and footer
+- `sitewide-content.yaml` contains shared site identity, banners, and footer
   content.
-- Additional pages are route directories with `route-content.md`.
+- Additional pages are route directories with `content.md`.
 - Route folder prefixes control route presentation order.
 - Route ids become default URL slugs.
 - Images belong under the image root for the page or route, usually grouped by
   section id.
 - Markdown remains the primary writing format.
-- Norna managed media blocks cover fixed site patterns such as image stacks,
+- Norna blocks cover fixed site patterns such as image stacks,
   carousels, and card lists.
-- `theme.md` controls visual presentation.
-- `config.md` controls the public URL and optional language and smooth
+- `theme.yaml` controls visual presentation.
+- `config.yaml` controls the public URL and optional language and smooth
   scrolling.
 - `dist/` is generated static output.
 - GitHub Pages is the integrated publishing target today.
@@ -111,7 +111,7 @@ Store diagram SVG files as normal Norna managed image assets:
 site/routes/<NNN-route-id>/images/<section-id>/<diagram-name>.svg
 ```
 
-Reference them with a Norna managed media block:
+Reference them with a Norna image block:
 
 ````md
 <!-- norna-image-provenance:

package/docs/design/site-examples-structure.md

@@ -81,7 +81,7 @@ together in a realistic project:
 
 - `theme-presets/`: one route per complete built-in theme preset, without
   overrides.
-- `media-and-surfaces/`: managed media blocks, notes, palettes and section
+- `media-and-surfaces/`: image and card blocks, notes, palettes and section
   surfaces. This is also the broad demo-build and navigation-test target.
 - `sitewide-content/`: convention-based identity, navigation, banner stacks,
   dismissal and footer content shared across routes.

package/docs/engine-development.md

@@ -7,7 +7,7 @@ This document is for work on the reusable `norna` package itself.
 - `bin/norna.mjs`: public CLI launcher and local-version resolver.
 - `bin/norna-cli.mjs`: public CLI command dispatcher.
 - `scripts/lib/site-paths.mjs`: engine/site path resolution.
-- `scripts/lib/project-config.mjs`: frontmatter-only `site/config.md`
+- `scripts/lib/project-config.mjs`: plain YAML `site/config.yaml`
   validation, defaults and derived URL path.
 - `scripts/sync-content-sections.mjs`: content validation and sync behavior.
 - `scripts/generate-images.mjs`: managed image pipeline and manifest.
@@ -62,6 +62,12 @@ npm run dev:local
 npm run build
 ```
 
+Inside the engine repository, use npm scripts or explicitly run
+`node bin/norna.mjs ...`. Do not rely on a bare `norna ...` command there: a
+globally installed launcher deliberately does not delegate to another package
+whose own name is `@janga/norna`, so it may continue with the published global
+implementation instead of the working tree.
+
 The media-and-surfaces feature demo is the broad visual and navigation
 diagnostic target:
 
@@ -130,17 +136,18 @@ The installed `norna` command is created from the package `bin` field. The
 launcher first looks for the nearest project `package.json`. If that project
 declares `@janga/norna` and Node can resolve an installed copy from that project
 root, the launcher delegates to that local entrypoint. The engine repository
-itself is excluded from delegation so local engine development keeps using the
-working tree entrypoint.
+itself is excluded from delegation to prevent recursion; its working tree is
+selected explicitly through npm scripts or `node bin/norna.mjs`.
 
 ## npm Release
 
 The npm package is published under the `@janga` scope. Choose the release type
 when starting a release; the command requires a clean working tree, verifies npm
 registry authentication for the same registry/cache used by the publish step,
-runs `npm test`, requires a clean working tree after the checks, updates
-`package.json` and `package-lock.json`, creates the release commit and Git tag,
-publishes to npm, then pushes the commit and tag.
+updates `package.json` and `package-lock.json` without creating a commit, and
+regenerates schemas with documentation links pinned to the new `v<version>` Git
+tag. It then runs `npm test`, verifies that only release files changed, creates
+the release commit and Git tag, publishes to npm, and pushes the commit and tag.
 
 ```sh
 npm run release:patch
@@ -155,8 +162,14 @@ npm run release:major
 ```
 
 The release command deliberately does not run GitHub Pages deployment monitoring.
+If version preparation, schema generation, or testing fails before the release
+commit, the script restores the previous package version and generated schemas.
+
 If npm publication fails, it stops before pushing; the local version commit and
-tag remain available for inspection or recovery.
+tag remain available for inspection or recovery. Retry publication with
+`npm run release:publish`, then push the existing commit and tag with
+`git push --follow-tags`. Do not start a new version bump merely to retry these
+steps.
 
 If the npm authentication preflight fails, no version commit or tag has been
 created yet. Run the printed login command:
@@ -173,7 +186,7 @@ and commit their updated `package-lock.json`.
 ## Rendering Notes
 
 The renderer builds the homepage at `/` and optional first-level routes from
-`site/routes/<NNN-route-id>/route-content.md`.
+`site/routes/<NNN-route-id>/content.md`.
 
 Navigation has two separate levels:
 
@@ -201,5 +214,5 @@ anchor movement; Norna does not run a separate scroll animation or retry anchor
 positions after later layout shifts.
 
 The shared layout selects Norna's built-in UI labels from the optional
-`language` in `site/config.md`. Keep editorial content in page Markdown and
+`language` in `site/config.yaml`. Keep editorial content in page Markdown and
 non-editorial engine UI labels in the engine language packs.

package/docs/getting-started.md

@@ -35,13 +35,30 @@ Run these commands from the directory where you keep projects:
 npx @janga/norna@latest init my-site
 cd my-site
 npm install
-npm run dev
+npm run norna:dev
 ```
 
 `init` creates the project before `npm install` runs. The generated
 `package.json` pins the Norna engine version so this project keeps using the
 same version until you update it deliberately.
 
+The tutorial uses the `norna:*` npm scripts because they work in both
+standalone and embedded projects. A standalone project also includes the
+shorter `npm run dev` and `npm run build` aliases.
+
+### Optional: Shorter CLI Commands
+
+Install the Norna launcher globally when you prefer direct commands:
+
+```sh
+npm install --global @janga/norna@latest
+```
+
+You can then run `norna dev`, `norna check`, and `norna build`. Inside a
+project, the launcher automatically delegates to that project's locally
+installed and pinned Norna version. The global installation is only the
+launcher; keep the local dependency and lockfile.
+
 ### Checkpoint: The Starter Is Visible
 
 Open the URL printed by the development server. It is normally
@@ -78,35 +95,31 @@ Return to the browser. The page should now contain `Welcome` and `Next`, and
 the single-page navigation should link to those two sections. You should not
 need to restart the server.
 
-## 3. Set The Shared Brand
+## 3. Set The Shared Identity
 
-Replace `site/sitewide-content.md` with:
+Replace `site/sitewide-content.yaml` with:
 
 ```yaml
----
 navigation:
-  brand: My first Norna site
+  label: My first Norna site
 footer:
   copyrightMessage: My first Norna site.
----
 ```
 
-The brand and footer are site-wide content rather than page sections. If you
-add routes later, they inherit these values.
+The navigation label and footer are site-wide content rather than page
+sections. If you add routes later, they inherit these values.
 
-### Checkpoint: The Brand Is Shared
+### Checkpoint: The Identity Is Shared
 
 The navigation should now display `My first Norna site`. The footer should show
 the new message.
 
 ## 4. Choose A Complete Theme
 
-Replace `site/theme.md` with:
+Replace `site/theme.yaml` with:
 
 ```yaml
----
 preset: project
----
 ```
 
 The preset supplies coordinated layout, typography, spacing, image sizing,
@@ -116,7 +129,7 @@ differ from the preset.
 ### Checkpoint: The Preset Is Active
 
 The browser should refresh with the `project` presentation. Your content files
-remain unchanged because presentation belongs in `theme.md`.
+remain unchanged because presentation belongs in `theme.yaml`.
 
 ## 5. Check And Build
 
@@ -124,7 +137,7 @@ Open another terminal in `my-site` and run:
 
 ```sh
 npm run norna:check
-npm run build
+npm run norna:build
 ```
 
 The check should complete without errors. The build should create:
@@ -144,7 +157,7 @@ build.
 
 ## What To Do Next
 
-- [Add and manage images](content.md#managed-media-blocks)
+- [Add and manage images](content.md#norna-blocks)
 - [Add another page](routes.md)
 - [Inspect and adjust the theme](theme.md)
 - [Configure the public URL](configuration.md)
@@ -164,7 +177,7 @@ reference so you can continue from the kind of question you have.
 Start the development server with:
 
 ```sh
-npm run dev -- --kill
+npm run norna:dev -- --kill
 ```
 
 This tells Norna to stop the process occupying its standard port before

package/docs/how-to/embedded-site.md

@@ -32,4 +32,4 @@ npm run norna:build
 ```
 
 See [Commands](../commands.md) for the complete script list and
-[Site Structure](../site-structure.md) for source and generated files.
+[Site Files](../site-files.md) for source and generated files.

package/docs/images-and-metadata.md

@@ -7,7 +7,7 @@ source images and any copyright or licensing policy for those images.
 
 Norna-managed local images are referenced from Markdown with
 `norna-image-stack`, `norna-image-carousel`, or `norna-card-list` blocks. See
-[Content](content.md#managed-media-blocks) for the block syntax.
+[Content](content.md#norna-blocks) for the block syntax.
 
 Homepage source images live under:
 
@@ -28,7 +28,7 @@ Supported source extensions:
 - `.png`
 - `.svg`
 
-Managed media block references use only the filename:
+Managed image block references use only the filename:
 
 ````md
 ```norna-image-stack
@@ -100,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 media blocks, validation and sync
+SVG files are managed by the same Markdown image blocks, validation and sync
 model, but they are not rasterized and do not get WebP variants. Norna copies
 the SVG source to:
 

package/docs/local-development.md

@@ -5,7 +5,7 @@ Use the local preview commands when editing a site or the engine demo.
 ## Start Preview
 
 ```sh
-npm run dev
+npm run norna:dev
 ```
 
 The wrapper:
@@ -28,15 +28,23 @@ To stop any process that is blocking the standard port before starting, pass
 `--kill`:
 
 ```sh
-npm run dev -- --kill
+npm run norna:dev -- --kill
 ```
 
-For the pure starter's `dev` alias, use:
+The standalone starter also provides this shorter alias:
 
 ```sh
 npm run dev -- --kill
 ```
 
+With the optional global launcher installed, the direct form is:
+
+```sh
+norna dev --kill
+```
+
+The launcher selects the current project's locally installed Norna version.
+
 ## Test On A Phone
 
 To make the local dev server available to devices on the same Wi-Fi network:

package/docs/public-files.md

@@ -0,0 +1,105 @@
+# Public Files
+
+`site/public/` contains static files that Norna copies into the published site
+without managed-image processing. Use it for browser icons, verification files,
+`robots.txt`, a custom-domain `CNAME`, downloadable files, and other assets that
+must keep their original format.
+
+Most files and subdirectories under `public/` are site-owned. Logos and browser
+icons are exceptions: Norna discovers a small set of exact filenames by
+convention.
+
+## Navigation Logo
+
+Put exactly one navigation logo directly in `site/public/`. Its filename must
+be exactly one of:
+
+- `logo.svg`
+- `logo.png`
+- `logo.jpg`
+- `logo.jpeg`
+
+Use lowercase letters and match the complete filename exactly. This is required
+for portability between case-sensitive and case-insensitive file systems.
+
+Norna discovers and displays the file automatically. No configuration path or
+enable switch is needed. Only one supported logo file may exist.
+
+The shared navigation label is configured separately:
+
+```yaml
+navigation:
+  label: Example Site
+```
+
+Without a logo, `label` is shown as navigation text. With a logo, it becomes the
+image alternative text. If `label` is omitted, Norna uses the homepage title.
+
+Add the optional `logo` object only to override the displayed height:
+
+```yaml
+navigation:
+  label: Example Site
+  logo:
+    height: 2rem
+```
+
+The width follows the logo's intrinsic aspect ratio. `navigation.logo` does not
+enable the logo or select a file.
+
+`norna config:check` fails when it finds multiple supported logo files, or when
+`navigation.logo` is configured but no logo file exists. A site without a logo
+uses its text label; the check reports this fallback as a warning.
+
+## Logos And Favicons
+
+A navigation logo is visible inside the website. A favicon identifies the site
+in browser tabs, bookmarks, and similar browser UI. They are independent and
+may coexist.
+
+Norna recognizes these browser-icon filenames directly under `site/public/`:
+
+- `favicon.svg`
+- `favicon.ico`
+- `favicon.png`
+- `apple-touch-icon.png`
+
+These filenames must also match exactly and use lowercase letters. More than
+one format may be present. Norna emits links for every supported file and lets
+the browser choose the appropriate one.
+
+## Other Static Files
+
+Other names are not restricted. For example:
+
+```text
+site/public/
+|-- robots.txt
+|-- CNAME
+|-- verification.html
+`-- downloads/
+    `-- project-overview.pdf
+```
+
+Norna preserves subdirectories while copying these files. A source file such
+as `site/public/downloads/project-overview.pdf` is published at
+`/downloads/project-overview.pdf`, prefixed with the site's configured base path
+when the site is published below a path such as `/repository-name/`.
+
+Ordinary Markdown image syntax may reference a public asset with a root-relative
+URL:
+
+```md
+![Public diagram](/diagrams/overview.svg)
+```
+
+Use Norna image blocks instead for local editorial images that should be
+validated, synced, processed, and captioned. See
+[Images and Metadata](images-and-metadata.md).
+
+## Generated Copy
+
+`norna site:public` copies source files from `site/public/` to
+`site/.norna/public/`. The latter directory is generated build-preparation
+output and must not be edited or versioned.
+

package/docs/publishing.md

@@ -1,7 +1,7 @@
 # Publishing
 
 Norna includes a GitHub Pages workflow and deploy helpers. The public URL is
-declared in `site/config.md`; repository and default branch are discovered from
+declared in `site/config.yaml`; repository and default branch are discovered from
 GitHub when a deploy command runs.
 
 Do not run deploy commands from the engine repository unless you deliberately
@@ -15,7 +15,7 @@ Each site repository owns `.github/workflows/deploy.yml`. The starter workflow:
 2. checks out the site repository,
 3. sets up Node and image tools,
 4. restores the generated image cache,
-5. runs `npm ci` and `npm run build`,
+5. runs `npm ci` and `npm run norna:build`,
 6. uploads `dist/`,
 7. deploys the artifact to GitHub Pages.
 
@@ -24,20 +24,16 @@ Site-specific public files such as `site/public/CNAME`, `robots.txt` and
 `sitemap.xml` belong in the site repository.
 
 For a project site without a custom domain, include the repository path in
-`site/config.md`:
+`site/config.yaml`:
 
 ```yaml
----
 url: https://owner.github.io/repository-name/
----
 ```
 
 For a custom domain or root-hosted site:
 
 ```yaml
----
 url: https://example.com/
----
 ```
 
 Norna derives the base path from the URL pathname and applies it to generated
@@ -98,7 +94,7 @@ npm run norna:deploy:watch -- --repo owner/name --branch main
 
 The default poll interval is 10 seconds, timeout is 15 minutes and recent-run
 limit is 10. `--workflow`, `--site-url` and `--limit` provide further one-run
-overrides; these operational values do not belong in `config.md`.
+overrides; these operational values do not belong in `config.yaml`.
 
 The monitor prints the run id, run URL, Actions URL, branch, commit SHA, status
 and public site URL. On failures it fetches failed job details and a log

package/docs/routes.md

@@ -1,19 +1,18 @@
 # Routes
 
 `site/content.md` is the homepage and builds to `/`. Optional route pages live
-under `site/routes/<NNN-route-id>/route-content.md` and build to first-level
+under `site/routes/<NNN-route-id>/content.md` and build to first-level
 URLs.
 
 Routes use the same page frontmatter, optional section metadata, Norna-managed
-media blocks, and Markdown section model as the homepage. See [Content](content.md)
+Norna 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
-an optional route-local `theme.md`. The route theme replaces the root visual
+an optional route-local `theme.yaml`. The route theme replaces the root visual
 theme for that route and can select any complete top-level theme preset. Route
-directories cannot contain technical site
-configuration; technical configuration stays in the selected site directory's
-top-level `config.md`.
+directories cannot contain `config.yaml` or `sitewide-content.yaml`; technical
+configuration and shared identity remain at the selected site's top level.
 
 ## Route Directory Format
 
@@ -57,7 +56,7 @@ the route id `contact` and URL `/contact/`.
 Add a first-level route by creating:
 
 ```text
-site/routes/010-about/route-content.md
+site/routes/010-about/content.md
 ```
 
 Minimal route page: