@janga/norna 0.7.17 → 0.7.22

package/docs/design/command-organization.md

@@ -1,414 +0,0 @@
-# Command Organization
-
-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 Norna site, an app, tests,
-and a publishing workflow that should not accidentally share ambiguous command
-names.
-
-## Situations
-
-`norna` commands must be understandable in three situations:
-
-- Standalone site project: the repository exists only to publish one
-  `norna` site.
-- 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.
-
-## Namespaces
-
-Use these namespaces consistently.
-
-### `norna:*`
-
-Use `norna:*` npm scripts in repositories that consume `norna`.
-
-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`.
-
-Examples:
-
-```sh
-npm run norna:dev
-npm run norna:check
-npm run norna:sync
-npm run norna: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.
-
-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`.
-
-### 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
-such as `build`, `test`, and `deploy` belong to the project that consumes the
-Norna engine.
-
-Examples:
-
-```sh
-npm run build
-npm run test
-npm run deploy
-```
-
-When those project commands need the Norna site, they should call `norna:*`
-scripts instead of calling `norna` directly. That keeps the selected
-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 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 standalone site project, project commands may be aliases to `norna:*`
-commands because the Norna site is the whole project.
-
-### `release:*`
-
-Use `release:*` only in the engine repository.
-
-Examples:
-
-```sh
-npm run release:patch
-npm run release:minor
-npm run release:major
-```
-
-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.
-
-Examples:
-
-```sh
-norna content:check
-norna content:sync
-norna build
-norna deploy
-```
-
-Npm scripts in site repositories are convenience wrappers around this binary.
-Documentation for ordinary site work should prefer the npm scripts because they
-can set the correct site directory for the repository.
-
-## Functional Groups
-
-### Install Norna Software
-
-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-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 Norna dependency should be installed as
-part of the existing project setup:
-
-```sh
-npm install --save-exact @janga/norna
-```
-
-The mixed project should then add `norna:*` scripts that point at the chosen
-site source directory.
-
-Engine development uses ordinary package installation in the engine repository:
-
-```sh
-npm install
-```
-
-### Upgrade Or Inspect Norna Software
-
-In a consuming repository, upgrading or inspecting the installed Norna engine
-is norna maintenance, so the preferred namespace is `norna:*`:
-
-```sh
-npm run norna:engine:version
-npm run norna:engine:update
-npm run norna:engine:update -- 0.2.0
-```
-
-These commands update the `@janga/norna` dependency and lockfile used by
-the repository. They do not release the engine package.
-
-In the engine repository, version changes belong to `release:*`:
-
-```sh
-npm run release:minor
-```
-
-### 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-site
-```
-
-The initializer should support two setup modes that share the same `norna:*`
-command vocabulary.
-
-#### Standalone Setup
-
-Standalone setup creates a new project where the Norna site is the whole repository:
-
-```sh
-npx @janga/norna@latest init my-site --type standalone
-```
-
-This should be the default when the target is a new or empty directory.
-
-Standalone setup should create:
-
-- 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 site.
-
-#### Embedded Setup
-
-Embedded setup adds a Norna site to an existing project without taking ownership
-of that project's root commands:
-
-```sh
-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 Norna-owned parts:
-
-- 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`;
-- no project publishing workflow unless the caller explicitly asks for one.
-
-Embedded setup must not overwrite existing npm scripts without explicit user
-confirmation. If a needed `norna:*` script already exists, the initializer
-should report the conflict and let the user decide whether to replace it.
-
-### Control The Dev Server
-
-Norna dev-server commands belong under `norna:dev:*` in consuming
-repositories:
-
-```sh
-npm run norna:dev
-npm run norna:dev:lan
-npm run norna:dev:restart
-npm run norna:dev:status
-npm run norna:dev:logs
-npm run norna:dev:stop
-```
-
-The shorter `norna:dev` starts the normal local server. Subcommands manage
-the same server.
-
-In the engine repository, engine and example development may use the engine's own
-unprefixed commands:
-
-```sh
-npm run dev:local
-npm run dev:lan
-```
-
-### Test Configuration And Content
-
-Norna validation should use `norna:check` for the normal full check and
-more specific commands when a caller needs one part:
-
-```sh
-npm run norna:check
-npm run norna:config:check
-npm run norna:content:check
-```
-
-`norna:check` should run configuration and content checks in the order needed
-by the engine.
-
-Project-level tests remain project-owned commands:
-
-```sh
-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
-Norna validation.
-
-### Inspect Site Presentation
-
-Commands that inspect site presentation without changing source files use
-`norna:*` in consuming repositories:
-
-```sh
-npm run norna:typography:profiles
-npm run norna:typography:show
-```
-
-`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 profiles, rhythms, and overrides have
-been applied.
-
-### Correct Content And Configuration
-
-Commands that modify Norna-owned source files use `norna:*`:
-
-```sh
-npm run norna:sync
-npm run norna:public
-npm run norna:images
-```
-
-`norna:sync` is the preferred npm wrapper for `norna content:sync`.
-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.yaml`, followed by:
-
-```sh
-npm run norna:config:check
-```
-
-### Build
-
-In a standalone site project:
-
-```sh
-npm run norna:build
-npm run norna:build:local
-npm run build
-```
-
-`norna:build:local` builds and restarts the local dev server. `build` may
-alias `norna:build` because the Norna site is the whole project.
-
-In a mixed project:
-
-```sh
-npm run norna:build
-npm run norna:build:local
-npm run build
-```
-
-`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 Norna site with an app. It may call
-`norna:build` internally.
-
-In the engine repository:
-
-```sh
-npm run build
-npm run demo:build
-npm run test:fixture:build
-```
-
-Engine build commands verify the reusable package, fixtures, or demo site.
-
-### Publish
-
-Norna deploy helpers belong under `norna:deploy*` in consuming
-repositories:
-
-```sh
-npm run norna:deploy
-npm run norna:deploy:commit
-```
-
-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:
-
-```sh
-npm run deploy
-```
-
-Those commands should publish the complete project artifact. If they need the
-Norna site, they should call `norna:*` scripts internally.
-
-Engine publishing uses `release:*`, not `norna:*`:
-
-```sh
-npm run release:patch
-npm run release:minor
-npm run release:major
-```
-
-### Monitor Publishing
-
-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 Norna site:
-
-```sh
-npm run deploy:watch
-```
-
-That command should monitor the whole project's publishing workflow. If it needs
-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 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 Norna behavior, they should call `norna:*`
-  scripts.
-- In standalone site projects, unprefixed project commands may alias `norna:*`
-  commands.
-- In mixed projects, unprefixed project commands must not be aliases for only
-  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 Norna dependency in a consuming repository, keep it
-  under `norna:*`.

package/docs/design/navigation-and-theme-plan.md

@@ -1,115 +0,0 @@
-# Navigation And Theme Plan
-
-This document records the intended order of work for page hierarchy,
-navigation, and theme presets. It is an implementation plan, not a description
-of released behavior.
-
-## Goal
-
-Norna should support sites with limited global navigation and a larger local
-page hierarchy without making mobile navigation harder to understand. Theme
-presets should provide a coherent visual system without changing the site's
-information architecture.
-
-## Working Principles
-
-- The file structure defines the page hierarchy and presentation order.
-- Navigation behavior and navigation styling are separate concerns.
-- Global site navigation, local page navigation, and headings on the current
-  page have distinct roles.
-- Changing a theme preset must not change which pages are available or how the
-  page hierarchy is interpreted.
-- Site-wide visual identity should remain coherent while individual pages may
-  vary where that does not disrupt navigation or orientation.
-- Documentation and broad example migration should follow implementation and
-  manual evaluation, not precede them.
-
-## Order Of Work
-
-### 1. Stabilize The Page Tree
-
-Finish and test nested page discovery independently of final navigation
-presentation. Establish deterministic rules for:
-
-- directory parsing, page ids, URL paths, and presentation order;
-- parent and ancestor relationships;
-- collisions and invalid nesting;
-- page-local content, images, and themes;
-- breadcrumbs and current-branch discovery.
-
-Commit this foundation separately before broad theme or preset changes.
-
-### 2. Define The Navigation Contract
-
-The intended information architecture is:
-
-- a small global navigation for the site's top-level areas;
-- a larger local page tree for the selected area;
-- a separate `On this page` list for headings on the current page;
-- breadcrumbs for location and ancestry;
-- one unified mobile navigation containing the whole page hierarchy, with the
-  current branch expanded and current page marked.
-
-The exact contract is potentially difficult to evaluate at an abstract level.
-The maintainer therefore expects this phase to use executable test sites,
-focused automated tests, or clear illustrative examples. These artifacts
-should demonstrate short single-page sites, ordinary two-level sites, and
-deeper documentation-style hierarchies on both desktop and mobile before the
-contract is considered stable.
-
-The contract should also define the fallback and override behavior for the
-supported navigation modes. Structural behavior belongs to site-level engine
-configuration or deterministic automatic selection, not to presentation
-presets.
-
-### 3. Implement Navigation In Layers
-
-Implement and verify the navigation model in this order:
-
-1. page-tree data and validation;
-2. desktop global navigation, local tree, breadcrumbs, and `On this page`;
-3. unified mobile navigation;
-4. keyboard, focus, current-page, and progressive-enhancement behavior;
-5. visual evaluation at representative viewport sizes.
-
-Keep real links as the foundation. Client-side JavaScript should only enhance
-interaction that cannot be expressed adequately with HTML and CSS.
-
-### 4. Refine Theme And Preset Responsibilities
-
-Presets should control visual presentation, including:
-
-- color system;
-- typography;
-- spacing and density;
-- page and content widths;
-- the visual treatment of global navigation, local navigation, breadcrumbs,
-  and `On this page`.
-
-Presets must not determine page hierarchy, link membership, or semantic
-navigation structure. Those must remain stable when a preset changes.
-
-Site-wide color, typography, and navigation treatment should normally remain
-consistent. Page-local theme variation should be limited to properties such as
-content width, density, and media presentation when variation does not weaken
-site identity or navigation clarity.
-
-### 5. Migrate After Evaluation
-
-After the page tree, navigation contract, and preset boundaries have been
-manually evaluated:
-
-- migrate fixtures and examples;
-- update schemas and editor assistance;
-- update Markdown reference documentation;
-- update the rendered documentation site;
-- remove obsolete navigation and preset behavior rather than retaining
-  compatibility layers.
-
-Keep foundation, navigation, preset, migration, and documentation changes in
-separate commits where practical.
-
-## Immediate Checkpoint
-
-The current nested-page implementation should be reviewed, tested, and secured
-before work continues on the final navigation contract or preset model.

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

@@ -1,159 +0,0 @@
-# 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 page 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, page-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.
-- `sitewide-content.yaml` contains shared logo settings, banners, and footer
-  content.
-- Additional pages are page directories with `content.md`.
-- Page folder prefixes control navigation order.
-- Page ids become URL segments.
-- Images belong under the image root for their page, usually grouped by
-  section id.
-- Markdown remains the primary writing format.
-- Norna blocks cover fixed site patterns such as image stacks,
-  carousels, and card lists.
-- `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.
-
-## 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/pages/<NNN-page-id>/images/<diagram-name>.svg
-```
-
-Reference them with a Norna image 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, page, 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?