@janga/norna 0.7.17 → 0.7.22

package/docs/images-and-metadata.md

@@ -1,186 +0,0 @@
-# Images And Metadata
-
-This document describes Norna's image pipeline. Site repositories own their
-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`, `norna-image-carousel`, or `norna-card-list` blocks. See
-[Content](content.md#norna-blocks) for the block syntax.
-
-Homepage source images live under:
-
-```text
-site/images/
-```
-
-Page source images live under:
-
-```text
-site/pages/<NNN-page-id>/images/
-```
-
-Supported source extensions:
-
-- `.jpg`
-- `.jpeg`
-- `.png`
-- `.svg`
-
-Managed image block references use only the filename:
-
-````md
-```norna-image-stack
-- image: portrait.jpg
-  alt: Optional alt text.
-  caption: Optional caption.
-```
-````
-
-`alt` and `caption` are optional. If `alt` is omitted, Norna renders an empty
-alt attribute.
-
-For generated or edited images, keep provenance near the image in a source-only
-comment. Norna removes these comments from rendered HTML:
-
-```md
-<!-- norna-image-provenance:
-image: portrait.jpg
-source: generated
-prompt: Short prompt or editing note.
--->
-```
-
-Each filename identifies one managed source image within its page. The same
-filename may be used by another page. Automatic sync only moves misplaced
-files when the filename identifies exactly one source candidate across all
-page image roots, and when the move will not break another reference. If the
-move crosses page image roots, `content:sync` requires a clean Git working tree
-before writing.
-
-## Markdown Images
-
-Use ordinary Markdown images for external images or static public assets:
-
-```md
-![External image](https://example.com/image.jpg)
-![Public asset](/favicon.svg)
-```
-
-Relative local Markdown images such as `![Portrait](portrait.jpg)` are not
-managed by Norna. `content:check` warns about them because Norna cannot
-validate, process, or sync those files through the image pipeline.
-
-## Generated Variants And Static SVG
-
-For raster images, `npm run norna:images` and `npm run norna:build` generate
-WebP files in:
-
-```text
-site/.norna/public/images/generated/
-```
-
-The normal display widths are:
-
-```text
-480, 768, 1080, 1440, 1920
-```
-
-Widths larger than the source image are skipped. If the source image is wider
-than all normal display widths, the pipeline also creates one variant at the
-source width.
-
-Generated filenames include the first eight characters of the source SHA-256
-hash:
-
-```text
-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
-model, but they are not rasterized and do not get WebP variants. Norna copies
-the SVG source to:
-
-```text
-site/.norna/public/images/original/
-```
-
-The copied SVG filename includes the source hash. If the SVG has a `viewBox` or
-numeric `width` and `height`, Norna stores that ratio in the image manifest so
-the existing image layout can size it like other images. If no intrinsic aspect
-ratio can be read, the SVG is still rendered directly.
-
-## Manifest
-
-The generated image manifest is:
-
-```text
-site/.norna/generated-images.json
-```
-
-It is versioned site state. For raster images, it stores source hashes,
-original dimensions, output version, and generated variant paths. For static
-SVG images, it stores the source hash, copied public path, output version, and
-intrinsic dimensions when they can be read. The image pipeline reuses generated
-or copied files only when the manifest entry matches the current source hash
-and output version, and all expected output files exist.
-
-Generated files under `site/.norna/public/` are build-preparation output and
-should not be versioned.
-
-## Metadata Behavior
-
-The current engine does not inspect, require, warn about, or write source image
-copyright metadata.
-
-Generated WebP files are created with ImageMagick using `-strip`, so embedded
-metadata is not a publication mechanism for generated variants. Keep licensing,
-credits, copyright notices, alt text, and captions in site-owned files such as
-`site/content.md`, page content files, `COPYRIGHT.md`, or other site
-documentation.
-
-If a site wants embedded metadata in original source files, that process is
-outside the current Norna command surface.
-
-## AI-Generated Images
-
-For AI-generated images, keep provenance and the generation prompt in a
-Markdown comment near the image block. This makes the image maintainable as
-content: future editors can understand where it came from and regenerate or
-revise it without reverse-engineering the asset.
-
-````md
-<!--
-AI image prompt for workflow.png:
-A clean editorial illustration of ordinary project files becoming a small
-static website, restrained colors, readable composition, no text in the image.
--->
-
-```norna-image-stack
-- image: workflow.png
-  alt: Abstract illustration of project files becoming a website.
-  caption: Generated illustration.
-```
-````
-
-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.
-
-## GitHub Actions Cache
-
-The starter workflow caches:
-
-```text
-site/.norna/public/images/generated
-```
-
-The cache key should include `site/.norna/generated-images.json` so unchanged
-generated variants can be restored during deploy. With a cache miss or a
-changed source hash, variants are rebuilt from source images.

package/docs/local-development.md

@@ -1,82 +0,0 @@
-# Local Development
-
-Use the local preview commands when editing a site or the engine demo.
-
-## Start Preview
-
-```sh
-npm run norna:dev
-```
-
-The wrapper:
-
-1. syncs `site/public/` into `site/.norna/public/`,
-2. starts Astro in background mode,
-3. waits until the site responds,
-4. opens `http://localhost:4321/` unless `WALDE_NO_OPEN=1` is set.
-
-The host and port are currently fixed in the script:
-
-```text
-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 norna:dev -- --kill
-```
-
-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:
-
-```sh
-npm run norna:dev:lan
-```
-
-The command prints one or more local IPv4 URLs. Open one of them on the phone.
-The phone and computer must use the same network, and macOS may ask to allow
-incoming connections for Node. Stop the server after testing with
-`npm run norna:dev:stop` because it is accessible from the local network.
-
-## Manage Preview
-
-```sh
-npm run norna:dev:status
-npm run norna:dev:logs
-npm run norna:dev:logs -- --follow
-npm run norna:dev:restart
-npm run norna:dev:stop
-```
-
-The local server state and logs live under `.astro/`.
-
-## Rebuild Stale Preview
-
-Use this when generated content or image state looks stale:
-
-```sh
-npm run norna:build:local
-```
-
-It runs the full build and restarts the local dev server without opening a new
-browser window.

package/docs/pages.md

@@ -1,134 +0,0 @@
-# Pages
-
-`site/content.md` is the homepage and builds to `/`. Optional additional pages live
-under `site/pages/<NNN-page-id>/content.md` and build to first-level
-URLs.
-
-Pages use the same H1 title, optional frontmatter, Norna-managed blocks, and
-Markdown section model as the homepage. See [Content](content.md) for the page
-and section model.
-
-Page directories can contain page content, page-local images, and
-an optional page-local `theme.yaml`. The page theme replaces the root visual
-theme for that page and can select any complete top-level theme preset. Page
-directories cannot contain `config.yaml` or `sitewide-content.yaml`; technical
-configuration and shared logo, banner, and footer settings remain at the
-selected site's top level.
-
-## Page Directory Format
-
-Page directories must use:
-
-```text
-NNN-page-id
-```
-
-`NNN` is a three-digit presentation order from `001` through `999`.
-`page-id` becomes the page id and URL segment.
-
-Valid examples:
-
-```text
-010-getting-started
-020-concepts
-120-api-reference
-```
-
-Invalid examples:
-
-```text
-10-about
-000-home
-010_About
-010-About
-010-about-
-010-about--team
-```
-
-The page id may contain only lowercase `a-z`, numbers, and single hyphens
-between alphanumeric groups. The numeric prefix is not part of the page id or
-URL.
-
-Renaming `030-contact/` to `015-contact/` changes navigation order but keeps
-the page id `contact` and URL `/contact/`.
-
-## Page File
-
-Add a first-level page by creating:
-
-```text
-site/pages/010-about/content.md
-```
-
-Minimal additional page:
-
-```md
----
-page:
-  description: About this site.
----
-
-# About
-
-Introductory text.
-
-## Team {#team}
-
-Text...
-```
-
-The example above builds to `/about/`.
-
-## Navigation
-
-Site navigation uses each page's Markdown H1 as its visible label and the
-page-directory prefix as its order. In a multi-page site, the homepage is the
-first navigation item and uses its own H1. An optional logo is a separate home
-link; it does not replace the homepage item or own a section menu.
-
-`navigation` has one optional field:
-
-- `listed`: boolean. Defaults to `true`. Set it to `false` to keep the page
-  public while excluding it from site navigation.
-
-```yaml
-navigation:
-  listed: false
-```
-
-Page order comes from the directory prefix.
-The homepage is always listed before additional pages.
-
-Current site navigation is intended for small sites. This guidance may change
-as navigation support matures, but the present model is:
-
-- A single-page site should normally use only section navigation.
-- A small multi-page site may use site navigation between pages plus section
-  navigation on the current page.
-- If a site needs many pages, deeply nested pages, or several navigation
-  levels, it has probably outgrown the current sticky-navigation model and may
-  need a different site structure or navigation system.
-
-## Page Images
-
-Page images live under the physical page directory:
-
-```text
-site/pages/010-about/images/image.jpg
-```
-
-Image references in page content still use only the filename:
-
-````md
-```norna-image-stack
-- image: image.jpg
-  alt: Intro image.
-```
-````
-
-All managed images used by the page share this one `images/` directory. Run
-`norna content:check` to find missing or misplaced images and
-`norna content:sync` to move unambiguous files into the expected page image
-root. `content:sync` can move images between page image roots when the filename
-is unambiguous across the site and the move will not break another reference;
-these cross-page writes require a clean Git working tree.

package/docs/public-files.md

@@ -1,118 +0,0 @@
-# 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
-
-To add a navigation logo, place exactly one supported logo file directly in
-`site/public/`:
-
-- `logo.svg`
-- `logo.png`
-- `logo.jpg`
-- `logo.jpeg`
-
-Norna discovers the logo from its filename, so you do not configure a path or
-enable it separately. Use the exact lowercase filename to keep the site
-portable between case-sensitive and case-insensitive file systems.
-
-The logo links to the homepage. Its alternative text comes from the homepage
-Markdown H1 in `site/content.md`; no separate site name or logo alt text is
-configured.
-
-Configure top-level `logo` in `site/sitewide-content.yaml` only when you need
-to override the displayed height:
-
-```yaml
-logo:
-  height: 2rem
-```
-
-The width follows the image's intrinsic aspect ratio. `logo` does
-not enable the logo or select a file.
-
-`norna config:check` fails when it finds multiple supported logo files, or when
-`logo` is configured but no logo file exists. A site without a logo uses its
-ordinary page-title navigation; the check reports the missing logo as a
-warning.
-
-## Browser Icons
-
-To add browser icons, place one or more supported files directly in
-`site/public/`:
-
-- `favicon.svg`
-- `favicon.ico`
-- `favicon.png`
-- `apple-touch-icon.png`
-
-Norna discovers these files from their filenames, so you do not configure paths
-or enable them separately. Use the exact lowercase filenames to keep the site
-portable between case-sensitive and case-insensitive file systems.
-
-You may include several supported browser-icon files. Norna links every file it
-finds and lets the browser select the appropriate format.
-
-Browser icons are separate from the navigation logo. The logo appears inside
-the website, while browser icons identify it in tabs, bookmarks, and similar
-browser interfaces.
-
-## GitHub Pages Custom Domain
-
-To use a custom domain with GitHub Pages, place a file named exactly `CNAME`
-directly in `site/public/`. Write the domain name in the file without a protocol
-or path:
-
-```text
-www.example.com
-```
-
-Norna does not discover or interpret `CNAME`; it copies the file to the root of
-the generated website. GitHub Pages gives the filename its meaning. The public
-`url` in `site/config.yaml` should use the same domain.
-
-## Other Static Files
-
-Other names are not restricted. For example:
-
-```text
-site/public/
-|-- robots.txt
-|-- verification.html
-`-- downloads/
-    `-- project-overview.pdf
-```
-
-Except for the navigation logo and browser icons documented above, Norna does
-not attach meaning to filenames or inspect their contents. It copies them
-unchanged. Browsers, crawlers, hosting services, and verification providers may
-still require their own exact filenames and locations.
-
-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,117 +0,0 @@
-# Publishing
-
-Norna includes a GitHub Pages workflow and deploy helpers. The public URL is
-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
-want to deploy the documentation site.
-
-## GitHub Pages Workflow
-
-`norna init` creates the GitHub Pages workflow at exactly:
-
-```text
-.github/workflows/deploy.yml
-```
-
-The file belongs to the site repository. GitHub Actions runs its contents, while
-Norna's deploy helpers use the filename to find and monitor the workflow. Keep
-the default filename when using `norna deploy`.
-
-GitHub Actions itself permits other workflow filenames. If the file is renamed,
-`norna deploy:watch` can monitor it with `--workflow <name-or-file>`, but the
-normal `norna deploy` command still expects `deploy.yml`.
-
-The starter workflow:
-
-1. runs for the repository's default branch,
-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 norna:build`,
-6. uploads `dist/`,
-7. deploys the artifact to GitHub Pages.
-
-In the GitHub repository settings, set Pages to build from GitHub Actions.
-Site-specific public files such as `site/public/CNAME`, `robots.txt`, and
-`sitemap.xml` belong in the site repository. Norna copies them, while GitHub
-Pages, crawlers, and other external consumers give those filenames their
-meaning. See [Public Files](public-files.md).
-
-For a project site without a custom domain, include the repository path in
-`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
-internal links, favicons, managed images and root-relative Markdown links.
-
-## Deploy An Already Committed Branch
-
-Use:
-
-```sh
-npm run norna:deploy
-```
-
-The command requires an authenticated GitHub CLI. It asks GitHub for the
-current repository and its default branch, then:
-
-- requires the current branch to be that default branch,
-- requires a clean worktree before the build,
-- fetches `origin`,
-- refuses to proceed when the branch is behind or diverged,
-- runs the full build,
-- requires the build to leave the worktree clean,
-- pushes only when local `HEAD` is ahead of the remote branch,
-- checks the included `deploy.yml` GitHub Pages workflow.
-
-It does not create commits or push uncommitted changes.
-
-## Deploy With A Generated Commit
-
-The older convenience flow remains available:
-
-```sh
-npm run norna:deploy:commit -- "Commit message"
-```
-
-It discovers the same repository/default branch, builds, stages only allowed
-site changes, commits, pushes and checks Pages. The allowlist is implemented in
-`scripts/deploy-site.mjs` and includes site content and configuration, expected
-managed images and generated image state, public files, package files and
-renderer source changes.
-
-## Watch A Deploy
-
-Use:
-
-```sh
-npm run norna:deploy:watch
-```
-
-By default it monitors `deploy.yml` for the current `HEAD` in the discovered
-repository and default branch. Useful one-run overrides include:
-
-```sh
-npm run norna:deploy:watch -- --timeout 20m --interval 5s
-npm run norna:deploy:watch -- --sha <commit-sha>
-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.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
-excerpt.

package/docs/requirements.md

@@ -1,54 +0,0 @@
-# Requirements And Limitations
-
-This page separates requirements for ordinary site work from optional tooling
-and current product boundaries.
-
-## Required For Every Site
-
-- Node.js `22.12.0` or later.
-- npm or another package manager capable of installing the project-local
-  `@janga/norna` dependency. Generated standalone sites use npm scripts and a
-  committed `package-lock.json` by default.
-- A terminal and a text editor.
-
-## Required For Managed Raster Images
-
-ImageMagick is required when Norna reads raster image dimensions or generates
-responsive raster variants. Norna accepts either the current `magick` command
-or the older `identify` and `convert` commands.
-
-Static SVG images with an intrinsic aspect ratio are rendered directly and do
-not need raster variants. See [Images and Metadata](images-and-metadata.md) for
-the supported managed-image behavior.
-
-## Optional Tools
-
-- Git is strongly recommended for reviewing and restoring site changes. It is
-  used by the normal commit-and-push publishing workflow.
-- GitHub CLI (`gh`) is needed only for Norna's deploy status and monitoring
-  helpers.
-- Playwright Chromium is needed only for navigation diagnostics used while
-  developing the Norna engine.
-
-Neither GitHub CLI nor Playwright is required to edit, preview, check, or build
-an ordinary Norna site.
-
-## Current Product Boundaries
-
-- Norna builds generated static output into `dist/`.
-- GitHub Pages is the only publishing provider with an included integration.
-  Other static hosts can serve the generated files, but Norna does not
-  currently configure or publish to them.
-- Norna provides its own site model and presentation layer. A project does not
-  supply custom page templates, component trees, or rendering logic through
-  the normal site interface.
-- Norna is intended for content-driven websites. Dynamic applications,
-  database-backed publishing, and visual CMS editing are outside its current
-  scope.
-- Norna is pre-1.0. Breaking changes to files, configuration, and commands may
-  occur between releases and should be reviewed before updating a project.
-
-These constraints are part of the product's current scope, not hidden setup
-steps. Start with [the tutorial](getting-started.md), and use
-[`norna engine:version`](commands.md#command-summary) to inspect the version
-installed by an existing project.