@janga/norna 0.7.1 → 0.7.3

package/docs/{command-organization.md → design/command-organization.md}

@@ -1,10 +1,10 @@
 # Command Organization
 
-This document defines the naming principles for commands in `norna`,
-gallery site repositories, and GitHub projects that embed a gallery.
+This document defines the naming principles for commands in `norna`, site
+repositories, and GitHub projects that embed a Norna site.
 
 The goal is that command names reveal both the action and the scope they affect.
-This matters because the same repository can contain a gallery, an app, tests,
+This matters because the same repository can contain a Norna site, an app, tests,
 and a publishing workflow that should not accidentally share ambiguous command
 names.
 
@@ -12,10 +12,10 @@ names.
 
 `norna` commands must be understandable in three situations:
 
-- Pure gallery project: the repository exists only to publish one
+- Standalone site project: the repository exists only to publish one
   `norna` site.
-- Mixed gallery project: the repository contains another project, such as an
-  app or library, and includes a `norna` presentation as one part of its
+- Mixed project: the repository contains another project, such as an app or
+  library, and includes a Norna site as one part of its
   GitHub Pages output.
 - Engine development: the repository is `norna` itself.
 
@@ -27,7 +27,7 @@ Use these namespaces consistently.
 
 Use `norna:*` npm scripts in repositories that consume `norna`.
 
-These scripts operate on a selected gallery source directory. In a pure gallery
+These scripts operate on a selected site source directory. In a standalone site
 project that directory is normally `site/`. In a mixed project it may be a more
 specific directory such as `presentation/`, with the script setting
 `NORNA_SITE_DIR` or passing `norna --site-dir`.
@@ -41,19 +41,19 @@ npm run norna:sync
 npm run norna:build
 ```
 
-Mixed projects must use `norna:*` for gallery work so names such as `build`,
+Mixed projects must use `norna:*` for Norna work so names such as `build`,
 `test`, and `deploy` can remain under the containing project's control.
 
-Pure gallery projects should also use `norna:*` as the primary documented
+Standalone site projects should also use `norna:*` as the primary documented
 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`.
 
-### Project Commands That Call Gallery Commands
+### Project Commands That Call Norna Commands
 
 `norna` does not define a consuming project's unprefixed commands. Names
 such as `build`, `test`, and `deploy` belong to the project that consumes the
-gallery engine.
+Norna engine.
 
 Examples:
 
@@ -63,18 +63,18 @@ npm run test
 npm run deploy
 ```
 
-When those project commands need the gallery, they should call `norna:*`
+When those project commands need the Norna site, they should call `norna:*`
 scripts instead of calling `norna` directly. That keeps the selected
-gallery source directory and other project-specific wrapper behavior in one
+site source directory and other project-specific wrapper behavior in one
 place.
 
 In a mixed project, if `npm run build` exists, it should build the project's
-complete publishable artifact, not only the gallery. If the project publishes a
-GitHub Pages artifact containing both a gallery and an app, `build` should
+complete publishable artifact, not only the Norna site. If the project publishes a
+GitHub Pages artifact containing both a Norna site and an app, `build` should
 produce that full artifact and may call `npm run norna:build` internally.
 
-In a pure gallery project, project commands may be aliases to `norna:*`
-commands because the gallery is the whole project.
+In a standalone site project, project commands may be aliases to `norna:*`
+commands because the Norna site is the whole project.
 
 ### `release:*`
 
@@ -86,12 +86,15 @@ Examples:
 npm run release:patch
 npm run release:minor
 npm run release:major
-npm run release:publish
 ```
 
-These commands change or publish the reusable `@janga/norna` package.
+These commands change and publish the reusable `@janga/norna` package.
 They must not be part of ordinary site repositories.
 
+`npm run release:publish` is a low-level script used by the release command
+after the version has already been bumped. It is not the normal release entry
+point.
+
 ### Direct CLI Commands
 
 The `norna` binary is the stable low-level command surface.
@@ -111,19 +114,19 @@ can set the correct site directory for the repository.
 
 ## Functional Groups
 
-### Install Gallery Software
+### Install Norna Software
 
-Creating a new pure gallery project starts outside the target project because
+Creating a new standalone site project starts outside the target project because
 the target does not have a `package.json` yet:
 
 ```sh
-npx @janga/norna@latest init my-gallery
-cd my-gallery
+npx @janga/norna@latest init my-site
+cd my-site
 npm install
 ```
 
 A mixed project already has its own repository and may have its own
-`package.json`. In that situation the gallery dependency should be installed as
+`package.json`. In that situation the Norna dependency should be installed as
 part of the existing project setup:
 
 ```sh
@@ -131,7 +134,7 @@ npm install --save-exact @janga/norna
 ```
 
 The mixed project should then add `norna:*` scripts that point at the chosen
-gallery source directory.
+site source directory.
 
 Engine development uses ordinary package installation in the engine repository:
 
@@ -139,9 +142,9 @@ Engine development uses ordinary package installation in the engine repository:
 npm install
 ```
 
-### Upgrade Or Inspect Gallery Software
+### Upgrade Or Inspect Norna Software
 
-In a consuming repository, upgrading or inspecting the installed gallery engine
+In a consuming repository, upgrading or inspecting the installed Norna engine
 is norna maintenance, so the preferred namespace is `norna:*`:
 
 ```sh
@@ -157,16 +160,15 @@ In the engine repository, version changes belong to `release:*`:
 
 ```sh
 npm run release:minor
-npm run release:publish
 ```
 
-### Initialize A Gallery Project Directory
+### Initialize A Site Project Directory
 
 Initialization is a direct CLI operation because it usually happens before a
 project has npm scripts:
 
 ```sh
-npx @janga/norna@latest init my-gallery
+npx @janga/norna@latest init my-site
 ```
 
 The initializer should support two setup modes that share the same `norna:*`
@@ -174,25 +176,25 @@ command vocabulary.
 
 #### Pure Setup
 
-Pure setup creates a new project where the gallery is the whole repository:
+Pure setup creates a new project where the Norna site is the whole repository:
 
 ```sh
-npx @janga/norna@latest init my-gallery --type pure
+npx @janga/norna@latest init my-site --type pure
 ```
 
 This should be the default when the target is a new or empty directory.
 
 Pure setup should create:
 
-- a normal gallery source directory, normally `site/`;
+- a normal site source directory, normally `site/`;
 - a `package.json` with `norna:*` scripts;
 - unprefixed convenience aliases only when they mean the same thing as the
   whole project, for example `build` as an alias for `norna:build`;
-- the standard GitHub Pages workflow for publishing the gallery.
+- the standard GitHub Pages workflow for publishing the site.
 
 #### Embedded Setup
 
-Embedded setup adds a gallery to an existing project without taking ownership
+Embedded setup adds a Norna site to an existing project without taking ownership
 of that project's root commands:
 
 ```sh
@@ -202,9 +204,9 @@ npx @janga/norna@latest init . --type embedded --site-dir presentation
 Embedded setup should be selected explicitly, or suggested when the target
 already contains a `package.json`.
 
-Embedded setup should create or update only the gallery-owned parts:
+Embedded setup should create or update only the Norna-owned parts:
 
-- the chosen gallery source directory, for example `presentation/`;
+- the chosen site source directory, for example `presentation/`;
 - `@janga/norna` as a project dependency;
 - `norna:*` scripts that set the selected site directory;
 - no unprefixed aliases such as `build`, `test`, `dev`, or `deploy`;
@@ -231,7 +233,7 @@ npm run norna:dev:stop
 The shorter `norna:dev` starts the normal local server. Subcommands manage
 the same server.
 
-In the engine repository, engine/demo development may use the engine's own
+In the engine repository, engine and example development may use the engine's own
 unprefixed commands:
 
 ```sh
@@ -261,11 +263,11 @@ npm run test
 
 If a mixed project defines `test`, that command should cover the whole project.
 It may call `norna:check`, but it should not be a hidden synonym for only
-gallery validation.
+Norna validation.
 
-### Inspect Gallery Presentation
+### Inspect Site Presentation
 
-Commands that inspect gallery presentation without changing source files use
+Commands that inspect site presentation without changing source files use
 `norna:*` in consuming repositories:
 
 ```sh
@@ -275,11 +277,11 @@ npm run norna:typography:show
 
 `norna:typography:presets` shows the built-in typography presets from the
 installed engine. `norna:typography:show` shows the effective typography for
-the selected gallery after presets and overrides have been applied.
+the selected site after presets and overrides have been applied.
 
 ### Correct Content And Configuration
 
-Commands that modify gallery-owned source files use `norna:*`:
+Commands that modify Norna-owned source files use `norna:*`:
 
 ```sh
 npm run norna:sync
@@ -291,7 +293,7 @@ npm run norna:images
 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 gallery
+Configuration edits are normally manual edits to the selected site
 `config.mjs`, followed by:
 
 ```sh
@@ -300,7 +302,7 @@ npm run norna:config:check
 
 ### Build
 
-In a pure gallery project:
+In a standalone site project:
 
 ```sh
 npm run norna:build
@@ -309,7 +311,7 @@ npm run build
 ```
 
 `norna:build:local` builds and restarts the local dev server. `build` may
-alias `norna:build` because the gallery is the whole project.
+alias `norna:build` because the Norna site is the whole project.
 
 In a mixed project:
 
@@ -319,10 +321,10 @@ npm run norna:build:local
 npm run build
 ```
 
-`norna:build` builds only the gallery. `norna:build:local` builds the
-gallery and restarts the local gallery dev server. If the mixed project defines
+`norna:build` builds only the Norna site. `norna:build:local` builds the
+site and restarts the local Norna dev server. If the mixed project defines
 `build`, that project command should build the complete publishable artifact,
-such as a GitHub Pages output that combines the gallery with an app. It may call
+such as a GitHub Pages output that combines the Norna site with an app. It may call
 `norna:build` internally.
 
 In the engine repository:
@@ -345,8 +347,8 @@ npm run norna:deploy
 npm run norna:deploy:commit
 ```
 
-Use these only when the gallery is the deployable site or when the containing
-project deliberately delegates deployment to the gallery engine.
+Use these only when the Norna site is the deployable site or when the containing
+project deliberately delegates deployment to the Norna engine.
 
 Mixed projects may instead have project-owned deploy commands:
 
@@ -355,24 +357,26 @@ npm run deploy
 ```
 
 Those commands should publish the complete project artifact. If they need the
-gallery, they should call `norna:*` scripts internally.
+Norna site, they should call `norna:*` scripts internally.
 
 Engine publishing uses `release:*`, not `norna:*`:
 
 ```sh
-npm run release:publish
+npm run release:patch
+npm run release:minor
+npm run release:major
 ```
 
 ### Monitor Publishing
 
-Gallery Pages monitoring belongs under:
+GitHub Pages monitoring for a Norna site belongs under:
 
 ```sh
 npm run norna:deploy:watch
 ```
 
 Mixed projects may provide a project-owned monitoring command when monitoring
-is not specific to the gallery:
+is not specific to the Norna site:
 
 ```sh
 npm run deploy:watch
@@ -384,19 +388,19 @@ norna-specific deploy settings, it should call `norna:deploy:watch`.
 ## Naming Rules
 
 - Use `norna:*` for every npm script in a consuming repository whose direct
-  object is the gallery, its source files, its generated images, its dev server,
+  object is the Norna site, its source files, its generated images, its dev server,
   or its engine dependency.
 - `norna` does not define unprefixed project commands such as `build`,
   `test`, and `deploy` in consuming repositories.
-- If project commands need gallery behavior, they should call `norna:*`
+- If project commands need Norna behavior, they should call `norna:*`
   scripts.
-- In pure gallery projects, unprefixed project commands may alias `norna:*`
+- In standalone site projects, unprefixed project commands may alias `norna:*`
   commands.
 - In mixed projects, unprefixed project commands must not be aliases for only
-  the gallery unless the command name makes that scope explicit.
+  the Norna site unless the command name makes that scope explicit.
 - Use `release:*` only for publishing the reusable engine package.
 - Prefer direct `norna ...` commands in engine docs and diagnostics;
   prefer npm scripts in site-repository docs.
 - Do not create separate namespaces for every internal concept. If a command is
-  about maintaining the gallery dependency in a consuming repository, keep it
+  about maintaining the Norna dependency in a consuming repository, keep it
   under `norna:*`.

package/docs/{site-examples-structure-note.md → design/site-examples-structure.md}

@@ -1,8 +1,7 @@
-# Site Examples Structure Note
+# Site Examples Structure
 
-This note defines the intended repository vocabulary before reorganizing
-starter files, demo sites, fixtures, and documentation sites. It is a design
-note, not an implementation record.
+This document defines the repository vocabulary for starter files, example
+sites, fixtures, and documentation sites.
 
 ## Goal
 
@@ -10,8 +9,8 @@ note, not an implementation record.
 files are product documentation, which files are examples, and which files are
 test fixtures.
 
-The current repository grew from one local demo, one starter, and a set of
-tests. A future structure should keep those roles separate.
+The repository grew from one local demo, one starter, and a set of tests. The
+current structure keeps those roles separate.
 
 ## Terms
 
@@ -57,30 +56,31 @@ for human reading or visual appeal.
 
 ## Intended Direction
 
-A future structure should collect runnable site examples in one place, for
-example:
+Runnable site examples are collected under `examples/`:
 
 ```text
-sites/
-  starter-basic/
+examples/
   dog-gallery/
   routes-demo/
   typography-demo/
-  docs-site/
 ```
 
-The exact names can change, but the roles should remain clear:
+Only `dog-gallery/` exists today. Additional examples should be added when
+they demonstrate a distinct feature or workflow.
 
-- `starter-basic/`: copied by `norna init`.
-- `dog-gallery/`: local visual demo and manual inspection site.
-- `routes-demo/`: focused route/navigation example if dog-gallery becomes too
-  broad.
+- `dog-gallery/`: current local visual demo, manual inspection site, and
+  navigation diagnostic target.
+- `routes-demo/`: focused route/navigation example if the dog example becomes
+  too broad.
 - `typography-demo/`: focused typography preset and override example if needed.
-- `docs-site/`: visual documentation built with `norna`.
 
+The repository-local `site/` directory is reserved for the documentation site.
 `docs/` should remain for reference documentation. It should link to the
 documentation site when visual explanation is more useful than reference text.
 
+`starters/basic/` stays separate from examples because it is copied by
+`norna init`. It should stay small and conservative.
+
 Fixtures may either stay under `fixtures/` or move under a clearly named test
 area later. They should not be confused with examples.
 
@@ -94,12 +94,7 @@ area later. They should not be confused with examples.
 
 ## Open Decisions
 
-- Exact top-level directory name: `sites/`, `examples/`, or another name.
-- Whether `starter-basic/` belongs beside examples or in a separate template
-  area.
-- Whether the current dog-gallery remains the primary manual test site or
-  becomes one example among several.
 - Whether the documentation site should be published anywhere, or exist only as
   a local/example build.
-- How demo selection should work in npm scripts, for example
-  `npm run demo:dev -- dog-gallery`.
+- How local example selection should work when there are multiple runnable
+  examples.

package/docs/engine-development.md

@@ -4,7 +4,8 @@ This document is for work on the reusable `norna` package itself.
 
 ## Main Areas
 
-- `bin/norna.mjs`: public CLI dispatcher.
+- `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`: `site/config.mjs` validation and defaults.
 - `scripts/sync-content-sections.mjs`: content validation and sync behavior.
@@ -13,14 +14,17 @@ This document is for work on the reusable `norna` package itself.
 - `scripts/deploy-site.mjs`: deploy and deploy:commit behavior.
 - `scripts/watch-pages-deploy.mjs`: GitHub Pages workflow monitor.
 - `src/content.config.ts`: Astro content schema.
-- `src/components/` and `src/layouts/`: rendered page, navigation, gallery, and
-  layout.
+- `src/components/` and `src/layouts/`: rendered page, navigation, image rows,
+  and layout.
 - `tests/`: Playwright navigation diagnostics.
 - `fixtures/basic/site/`: minimal site used for engine checks.
 - `starters/basic/`: copyable site starter.
+- `examples/dog-gallery/site/`: visual dog example used by demo builds and
+  navigation diagnostics.
 
-The repository-local `site/` directory is a dog-gallery demo. It is useful for
-manual engine checks, but it is not a published site.
+The repository-local `site/` directory is reserved for a local documentation
+site. It is useful for dogfooding `norna` documentation, but it is not the
+primary visual regression demo.
 
 ## Common Checks
 
@@ -34,7 +38,24 @@ npm run demo:build
 npm run package:check
 ```
 
-`npm run test` runs the same set in sequence.
+`npm run test` runs the standard non-demo check sequence.
+
+The root `site/` directory is the documentation site. Use the ordinary local
+commands for it:
+
+```sh
+npm run dev:local
+npm run build
+```
+
+The dog example remains the visual demo and navigation diagnostic target:
+
+```sh
+cd examples/dog-gallery/site
+node ../../../bin/norna.mjs dev:local
+cd ../../..
+npm run demo:build
+```
 
 Navigation diagnostics are separate because they use Playwright:
 
@@ -92,11 +113,18 @@ npm run norna:engine:update -- <version>
 Commit the resulting `package.json` and `package-lock.json` changes in the
 site repository after the site's normal checks pass.
 
+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.
+
 ## 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 `release:publish`,
+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.

package/docs/getting-started.md

@@ -23,12 +23,17 @@ new site directory:
 
 ```sh
 cd path/to/your/projects
-npx @janga/norna@latest init my-gallery
-cd my-gallery
+npx @janga/norna@latest init my-site
+cd my-site
 npm install
-npm run norna:dev
+npm run dev
 ```
 
+After `npm install`, the project's npm scripts use the project-local `norna`
+binary from `node_modules/.bin`. A globally installed `norna` can also be used
+as a convenience launcher; inside a project with an installed `@janga/norna`
+dependency, it delegates to the project's local version.
+
 A freshly created empty directory is not a `norna` site yet. It becomes a
 site when `init` copies the starter files, including `package.json`. If you run
 `npm install` in an empty directory, npm may walk up to a parent directory and
@@ -40,7 +45,7 @@ engine repository. For example:
 ```text
 Projects/
   norna/
-  my-gallery/
+  my-site/
 ```
 
 The starter contains:
@@ -57,12 +62,13 @@ Commit the generated `package-lock.json` after the first install.
 
 ## First Edits
 
-1. Edit `site/config.mjs` for the site's URL, layout, font, language labels,
-   GitHub repository, footer, and deploy settings.
-2. Edit `site/theme.md` for site-wide colors, typography preset, inline styles,
-   and frame colors, or omit it to use engine defaults.
+1. Edit `site/config.mjs` for the site's URL, language labels, GitHub
+   repository, footer, and deploy settings.
+2. Edit `site/theme.md` for site-wide layout, vertical spacing, 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, sections, text,
-   gallery rows, page/section presentation overrides, alt text, and captions.
+   image rows, page/section presentation overrides, alt text, and captions.
 4. Put source images under `site/images/<section-id>/`.
 5. Add optional route pages under
    `site/routes/<route-folder>/route-content.md`.
@@ -75,22 +81,45 @@ npm run norna:check
 npm run build
 ```
 
-Read [Site Structure](site-structure.md), [Content](content.md), and
+## Configure The Public URL
+
+For a custom domain or any site published at the web root, use:
+
+```js
+site: {
+	url: 'https://example.com/',
+	basePath: '/',
+}
+```
+
+For a GitHub Pages project site without a custom domain, the site is served
+under the repository name. Configure both values:
+
+```js
+site: {
+	url: 'https://owner.github.io/repository-name/',
+	basePath: '/repository-name/',
+}
+```
+
+After that, content files may still use root-style internal links such as
+`/getting-started/` and `/workflow.svg`. Norna applies `site.basePath` during
+rendering so the built links work under the GitHub Pages project path.
+
+The starter includes a GitHub Pages workflow in `.github/workflows/deploy.yml`.
+In the GitHub repository settings, configure Pages to build from GitHub
+Actions.
+
+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.
 
-To change the site's maximum page width, set `layout.pageWidth` in
-`site/config.mjs`. To change side margins, set `layout.gutter`. To change the
-maximum gallery width inside that page area, set `gallery.width`. To keep
-images within a comfortable viewport height, set
-`gallery.maxAvailableHeightPercent`. See [Configuration](configuration.md) for
-the accepted formats and default values.
-
-To change the site's font, set `typography.fontFamily` in `site/config.mjs`.
-See [`typography.fontFamily`](configuration.md#typographyfontfamily) for the
-accepted format and default value.
-
-To change the site-wide typography preset, edit `site/theme.md`. To change one
-page or section, add a focused `presentation.typography` override in
-`site/content.md`. Use `npm run norna:typography:presets` to inspect the
-installed preset values and `npm run norna:typography:show` to inspect the
-resolved typography for the selected site.
+To change the site's maximum page width, side gutters, vertical spacing, image
+width, image height limits, font, colors, or site-wide typography preset, edit
+`site/theme.md`. See [Theme](theme.md) for the accepted shape.
+
+To change one page or section, add a focused `presentation.typography`
+override in `site/content.md`. See [Typography](typography.md). Use
+`norna typography presets` to inspect the installed preset values and
+`norna typography show` to inspect the resolved typography for the selected
+site.

package/docs/images-and-metadata.md

@@ -15,7 +15,7 @@ Supported source extensions:
 - `.png`
 
 Image filenames must be globally unique under `site/images/`. The content and
-image scripts reject duplicate filenames because gallery rows identify images by
+image scripts reject duplicate filenames because image rows identify images by
 filename only.
 
 ## Generated Variants

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 norna:dev
+npm run dev
 ```
 
 The wrapper:
@@ -24,6 +24,19 @@ localhost:4321
 If the port is already in use, the command fails and asks you to stop the
 process using it.
 
+To stop any process that is blocking the standard port before starting, pass
+`--kill`:
+
+```sh
+npm run dev -- --kill
+```
+
+For the pure starter's `dev` alias, use:
+
+```sh
+npm run dev -- --kill
+```
+
 ## Test On A Phone
 
 To make the local dev server available to devices on the same Wi-Fi network: