@janga/norna 0.7.7 → 0.7.9

package/README.md

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

package/docs/README.md

@@ -32,6 +32,7 @@ For design and naming principles:
 
 1. [Command Organization](design/command-organization.md)
 2. [Site Examples Structure](design/site-examples-structure.md)
+3. [Norna Diagram Design](design/norna-diagram-design.md)
 
 For a quick reference:
 
@@ -39,7 +40,7 @@ For a quick reference:
   fields such as URL, base path, locale labels, footer, GitHub, and deploy
   settings.
 - [Content](content.md) describes page frontmatter, Markdown-authored
-  sections, optional section metadata, image stacks, carousels, temporary
+  sections, optional section metadata, managed media blocks, temporary
   sections, and content validation.
 - [Theme](theme.md) describes site-wide layout, layout density, image sizing,
   font, typography rhythm, presentation colors, frame colors, and inline styles.
@@ -58,6 +59,9 @@ Design documents are intentionally separate from the user reference:
 - [Site Examples Structure](design/site-examples-structure.md) defines the
   intended vocabulary for starters, examples, documentation sites, reference
   docs, and fixtures.
+- [Norna Diagram Design](design/norna-diagram-design.md) defines the first
+  experiment for technical and pedagogical diagrams without adding external
+  diagram tooling to the build pipeline.
 
 Site repositories should document only their site-specific choices and link here
 for generic `norna` behavior.

package/docs/commands.md

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

package/docs/configuration.md

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

package/docs/content.md

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

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

@@ -0,0 +1,156 @@
+# Norna Diagram Design
+
+This document defines a repository-local workflow for creating technical and
+pedagogical diagrams for Norna.
+
+It is intentionally not a vendored copy of any external skill, MCP server, or
+diagram tool. The first experiment should use hand-authored SVG assets managed
+by Norna's existing image model.
+
+## Goal
+
+Norna diagrams should help a new reader understand the site model faster than
+text alone.
+
+A diagram should explain one idea clearly, not show every related feature. If a
+topic needs several ideas, split it into several diagrams.
+
+## Current Scope
+
+Use this workflow for diagrams in the Norna documentation site under `site/`.
+
+Do not add diagram generation to the Norna build pipeline yet. Diagram creation
+is an authoring workflow for now, not product functionality.
+
+Do not require Excalidraw, MCP servers, browser plugins, or external layout
+tools for the first experiment.
+
+## Diagram Brief
+
+Before creating or replacing a diagram, write a short brief:
+
+```md
+Purpose:
+Audience:
+Main message:
+Concepts to show:
+Concepts to avoid:
+Norna features that must not be implied:
+Suggested layout:
+Mobile/readability requirement:
+Where the SVG will live:
+Markdown block and alt text:
+```
+
+The brief can live in the discussion, in a source-only Markdown comment near
+the image, or in `docs/design/` when it is useful for future maintenance.
+
+## Design Principles
+
+- Show one primary flow or relationship.
+- Prefer two to five main objects.
+- Use short labels.
+- Use one clear visual hierarchy.
+- Keep arrows few and directional.
+- Avoid diagrams where every object connects to every other object.
+- Prefer multiple simple diagrams over one dense diagram.
+- Make route order, URL slugs, section ids, image folders, source files, and
+  generated output visually distinct when those ideas matter.
+- Do not show templates, components, custom rendering logic, route-level
+  technical configuration, or hosting integrations that Norna does not support.
+- Do not show page layouts that Norna cannot actually render unless the diagram
+  is clearly abstract and not a product capability example.
+
+## Norna-Specific Accuracy
+
+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.
+- Additional pages are route directories with `route-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,
+  carousels, and card lists.
+- `theme.md` controls visual presentation.
+- `config.mjs` controls technical site configuration.
+- `dist/` is generated static output.
+- GitHub Pages is the integrated publishing target today.
+
+## SVG Requirements
+
+Use hand-authored SVG for the first experiment.
+
+SVG assets should:
+
+- have a `viewBox`;
+- include `<title>` and `<desc>`;
+- use real text, not outlined text;
+- avoid external fonts and external image files;
+- remain readable at the size used on the site;
+- work when scaled down on a phone;
+- use restrained colors that fit the surrounding page;
+- avoid decorative effects that compete with the explanation;
+- keep text inside boxes with visible margins;
+- be maintainable by editing the SVG source.
+
+If a diagram is too wide for mobile, prefer splitting it into smaller diagrams
+over relying on horizontal scrolling.
+
+## Source Placement
+
+Store diagram SVG files as normal Norna managed image assets:
+
+```text
+site/routes/<NNN-route-id>/images/<section-id>/<diagram-name>.svg
+```
+
+Reference them with a Norna managed media block:
+
+````md
+<!-- norna-image-provenance:
+image: diagram-name.svg
+source: hand-authored
+Short maintenance note explaining why the diagram exists.
+-->
+
+```norna-image-stack
+- image: diagram-name.svg
+  alt: Concise explanation of what the diagram shows.
+```
+````
+
+## Review Checklist
+
+Before accepting a diagram:
+
+- The main message is obvious without reading the surrounding section.
+- The diagram does not imply unsupported Norna functionality.
+- URL, route, section, image, theme, config, and output terminology is
+  consistent with documentation.
+- Text fits inside boxes at desktop and mobile widths.
+- Arrows clarify the relationship instead of adding noise.
+- The SVG has title, description, and useful alt text in Markdown.
+- `norna content:check` passes.
+- A desktop and mobile visual check has been done when layout changed.
+
+## Relationship To Excalidraw
+
+Excalidraw can be useful as a sketching style or inspiration for box-and-arrow
+clarity, but the first Norna experiment should not depend on Excalidraw files,
+exports, or MCP tooling.
+
+If future experiments show that diagram generation should be automated, evaluate
+that as a separate authoring tool or CLI. Do not make it part of the site build
+engine unless there is a clear product reason.
+
+## Future Questions
+
+- Should diagram briefs become tracked files next to SVG assets?
+- Should Norna have a separate authoring helper for diagrams?
+- Should generated diagrams store both a source format and exported SVG?
+- Should a later tool create Excalidraw-compatible files, plain SVG, or both?
+- What review rules are needed before diagrams are used in starters or examples?

package/docs/getting-started.md

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

package/docs/images-and-metadata.md

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

package/docs/routes.md

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

package/docs/site-structure.md

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

package/docs/theme.md

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

package/docs/typography.md

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