@janga/norna 0.7.1 → 0.7.2

package/README.md

@@ -22,7 +22,8 @@ A `norna` site is file-driven:
 
 1. A site repository depends on this package.
 2. The site keeps technical settings, including page width, gallery width, and
-   the global font family, in `site/config.mjs`.
+   the global font family, public URL, and optional URL base path in
+   `site/config.mjs`.
 3. The site can keep site-wide visual theme defaults in `site/theme.md`.
 4. The site keeps homepage content, section order, gallery rows, alt text, and
    captions in `site/content.md`.
@@ -35,7 +36,10 @@ A `norna` site is file-driven:
    Astro pages, and can help publish the committed branch through GitHub Pages.
 
 The default site directory is `site/`. Commands can also use another directory
-with `NORNA_SITE_DIR` or `norna --site-dir <path>`.
+with `NORNA_SITE_DIR` or `norna --site-dir <path>`. Without an explicit site
+directory, commands first accept the current directory when it contains
+`config.mjs` and `content.md`; otherwise they walk upward looking for a
+`site/` directory with those files.
 
 ## Quick Start
 
@@ -73,14 +77,17 @@ Actions use the same engine version.
 - Understand required site files: [Site Structure](docs/site-structure.md)
 - Edit sections and galleries: [Content](docs/content.md)
 - Configure a site: [Configuration](docs/configuration.md)
-- Configure site-wide theme: [Content](docs/content.md#site-theme)
+- Publish under a GitHub Pages project path:
+  [`site.basePath`](docs/configuration.md#sitebasepath)
+- Configure site-wide theme: [Theme](docs/theme.md)
+- Add route pages: [Routes](docs/routes.md)
 - Set page width: [`layout.pageWidth`](docs/configuration.md#layoutpagewidth)
 - Set side gutters: [`layout.gutter`](docs/configuration.md#layoutgutter)
 - Set gallery width: [`gallery.width`](docs/configuration.md#gallerywidth)
 - Keep images within viewport height:
   [`gallery.maxAvailableHeightPercent`](docs/configuration.md#gallerymaxavailableheightpercent)
 - Set the site font: [`typography.fontFamily`](docs/configuration.md#typographyfontfamily)
-- Choose typography presets and overrides: [Content](docs/content.md#typography-presets)
+- Choose typography presets and overrides: [Typography](docs/typography.md)
 - Look up CLI and npm scripts: [Commands](docs/commands.md)
 - Understand generated images: [Images And Metadata](docs/images-and-metadata.md)
 - Run local preview: [Local Development](docs/local-development.md)
@@ -98,8 +105,15 @@ Actions use the same engine version.
 GitHub Pages workflows created from the starter install the image tools during
 deployment.
 
+## License
+
+`norna` is licensed under [GNU GPL v3](LICENSE).
+
 ## Documentation
 
+The Norna-built introduction site lives in [`site/`](site/) and is configured
+for GitHub Pages at <https://janga.github.io/norna/>.
+
 Start with [docs/README.md](docs/README.md) for the documentation map and
 recommended reading order.
 

package/astro.config.mjs

@@ -7,9 +7,11 @@ import {
 	astroPublicDir,
 	engineRoot,
 } from './scripts/lib/site-paths.mjs';
+import projectConfig from './scripts/lib/project-config.mjs';
 
 // https://astro.build/config
 export default defineConfig({
+	base: projectConfig.site.basePath,
 	cacheDir: astroCacheDir,
 	outDir: astroDistDir,
 	publicDir: astroPublicDir,

package/bin/norna-cli.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+import path from 'node:path';
+
+const args = process.argv.slice(2);
+process.env.NORNA_INVOCATION_ROOT ??= process.cwd();
+
+const usage = `
+Usage: norna <command> [options]
+
+Commands:
+  dev:local              Start local Astro dev server
+  dev:lan                Start dev server for this local network
+  dev:restart            Restart local Astro dev server
+  dev:status             Show local dev server status
+  dev:logs               Show local dev server logs
+  dev:stop               Stop local dev server
+  config:check           Validate site/config.mjs
+  content:check          Validate site/content.md and gallery references
+  content:sync           Rewrite section order and move misplaced images
+  typography:presets     Show built-in typography preset values
+  typography:show        Show resolved typography for the selected site
+  site:public            Sync site/public/ to public/
+  images                 Generate optimized image variants
+  engine:update          Update @janga/norna in a site repository
+  engine:version         Show installed engine and Astro versions
+  init                   Create a new site project from the starter
+  build                  Build the selected site
+  build:local            Build and restart local dev server
+  deploy                 Build and deploy committed branch
+  deploy:commit          Build, commit allowed changes, push, and check Pages
+  deploy:watch           Watch GitHub Pages workflow
+  preview                Preview dist/
+  astro                  Run Astro with norna config
+  doctor                 Print resolved paths
+
+Global options:
+  --site-dir <path>      Use a specific site source directory
+  -h, --help             Show this help
+`.trim();
+
+const parseArgs = (rawArgs) => {
+	const commandArgs = [];
+	let siteDir = null;
+
+	for (let index = 0; index < rawArgs.length; index += 1) {
+		const arg = rawArgs[index];
+
+		if (arg === '--site-dir') {
+			const value = rawArgs[index + 1];
+			if (!value || value.startsWith('-')) {
+				throw new Error('--site-dir requires a path.');
+			}
+
+			siteDir = value;
+			index += 1;
+			continue;
+		}
+
+		if (arg.startsWith('--site-dir=')) {
+			siteDir = arg.slice('--site-dir='.length);
+			if (!siteDir) {
+				throw new Error('--site-dir requires a path.');
+			}
+			continue;
+		}
+
+		commandArgs.push(arg);
+	}
+
+	return { commandArgs, siteDir };
+};
+
+let parsedArgs;
+
+try {
+	parsedArgs = parseArgs(args);
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}
+
+const { commandArgs, siteDir } = parsedArgs;
+
+if (siteDir) {
+	process.env.NORNA_SITE_DIR = siteDir;
+}
+
+const [command = 'help', ...rest] = commandArgs;
+
+if (command === '-h' || command === '--help' || command === 'help') {
+	console.log(usage);
+	process.exit(0);
+}
+
+const [
+	{ runAstroInherit },
+	{ engineRoot, siteProjectRoot },
+	{ runInherit },
+] = await Promise.all([
+	import('../scripts/lib/astro-command.mjs'),
+	import('../scripts/lib/site-paths.mjs'),
+	import('../scripts/lib/run-command.mjs'),
+]);
+
+const runScript = (relativePath, scriptArgs = []) => runInherit(
+	process.execPath,
+	[path.join(engineRoot, relativePath), ...scriptArgs],
+	{ cwd: siteProjectRoot },
+);
+
+const runBuild = () => runScript('scripts/build-site.mjs');
+
+try {
+	if (command === 'dev' || command === 'dev:local') {
+		await runScript('scripts/dev-local.mjs', rest);
+	} else if (command === 'dev:lan') {
+		await runScript('scripts/dev-local.mjs', ['lan', ...rest]);
+	} else if (command === 'dev:restart') {
+		await runScript('scripts/dev-local.mjs', ['restart', ...rest]);
+	} else if (command === 'dev:status') {
+		await runScript('scripts/dev-local.mjs', ['status', ...rest]);
+	} else if (command === 'dev:logs') {
+		await runScript('scripts/dev-local.mjs', ['logs', ...rest]);
+	} else if (command === 'dev:stop') {
+		await runScript('scripts/dev-local.mjs', ['stop', ...rest]);
+	} else if (command === 'config:check') {
+		await runScript('scripts/check-config.mjs', rest);
+	} else if (command === 'content:check') {
+		await runScript('scripts/sync-content-sections.mjs', ['--check', ...rest]);
+		await runAstroInherit(['sync']);
+	} else if (command === 'content:sync') {
+		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
+	} else if (command === 'typography:presets') {
+		await runScript('scripts/show-typography.mjs', ['presets', ...rest]);
+	} else if (command === 'typography:show') {
+		await runScript('scripts/show-typography.mjs', ['show', ...rest]);
+	} else if (command === 'site:public') {
+		await runScript('scripts/sync-site-public.mjs', rest);
+	} else if (command === 'images') {
+		await runScript('scripts/generate-images.mjs', rest);
+	} else if (command === 'engine:update') {
+		await runScript('scripts/update-engine.mjs', rest);
+	} else if (command === 'engine:version') {
+		await runScript('scripts/engine-version.mjs', rest);
+	} else if (command === 'init') {
+		await runScript('scripts/init-site.mjs', rest);
+	} else if (command === 'build') {
+		await runBuild();
+	} else if (command === 'build:local') {
+		await runBuild();
+		await runScript('scripts/dev-local.mjs', ['restart']);
+	} else if (command === 'deploy') {
+		await runScript('scripts/deploy-site.mjs', rest);
+	} else if (command === 'deploy:commit') {
+		await runScript('scripts/deploy-site.mjs', ['commit', ...rest]);
+	} else if (command === 'deploy:watch') {
+		await runScript('scripts/watch-pages-deploy.mjs', rest);
+	} else if (command === 'doctor') {
+		await runScript('scripts/doctor.mjs', rest);
+	} else if (command === 'astro') {
+		await runAstroInherit(rest);
+	} else if (command === 'preview') {
+		await runAstroInherit(['preview', ...rest]);
+	} else {
+		throw new Error(`Unknown command: ${command}\n${usage}`);
+	}
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}

package/bin/norna.mjs

@@ -1,170 +1,169 @@
 #!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile, realpath } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-const args = process.argv.slice(2);
-process.env.NORNA_INVOCATION_ROOT ??= process.cwd();
-
-const usage = `
-Usage: norna <command> [options]
-
-Commands:
-  dev:local              Start local Astro dev server
-  dev:lan                Start dev server for this local network
-  dev:restart            Restart local Astro dev server
-  dev:status             Show local dev server status
-  dev:logs               Show local dev server logs
-  dev:stop               Stop local dev server
-  config:check           Validate site/config.mjs
-  content:check          Validate site/content.md and gallery references
-  content:sync           Rewrite section order and move misplaced images
-  typography:presets     Show built-in typography preset values
-  typography:show        Show resolved typography for the selected site
-  site:public            Sync site/public/ to public/
-  images                 Generate optimized image variants
-  engine:update          Update @janga/norna in a site repository
-  engine:version         Show installed engine and Astro versions
-  init                   Create a new site project from the starter
-  build                  Build the selected site
-  build:local            Build and restart local dev server
-  deploy                 Build and deploy committed branch
-  deploy:commit          Build, commit allowed changes, push, and check Pages
-  deploy:watch           Watch GitHub Pages workflow
-  preview                Preview dist/
-  astro                  Run Astro with norna config
-  doctor                 Print resolved paths
-
-Global options:
-  --site-dir <path>      Use a specific site source directory
-  -h, --help             Show this help
-`.trim();
-
-const parseArgs = (rawArgs) => {
-	const commandArgs = [];
-	let siteDir = null;
-
-	for (let index = 0; index < rawArgs.length; index += 1) {
-		const arg = rawArgs[index];
-
-		if (arg === '--site-dir') {
-			const value = rawArgs[index + 1];
-			if (!value || value.startsWith('-')) {
-				throw new Error('--site-dir requires a path.');
-			}
-
-			siteDir = value;
-			index += 1;
-			continue;
+const packageName = '@janga/norna';
+const currentEntrypoint = fileURLToPath(import.meta.url);
+const implementationEntrypoint = new URL('./norna-cli.mjs', import.meta.url);
+
+const readJson = async (filePath) => JSON.parse(await readFile(filePath, 'utf8'));
+
+const readJsonOptional = async (filePath) => {
+	try {
+		return await readJson(filePath);
+	} catch (error) {
+		if (error.code === 'ENOENT') {
+			return null;
 		}
 
-		if (arg.startsWith('--site-dir=')) {
-			siteDir = arg.slice('--site-dir='.length);
-			if (!siteDir) {
-				throw new Error('--site-dir requires a path.');
-			}
-			continue;
+		throw error;
+	}
+};
+
+const realpathOptional = async (filePath) => {
+	try {
+		return await realpath(filePath);
+	} catch (error) {
+		if (error.code === 'ENOENT') {
+			return null;
 		}
 
-		commandArgs.push(arg);
+		throw error;
 	}
+};
+
+const findNearestProjectRoot = (startDirectory) => {
+	let current = path.resolve(startDirectory);
+
+	while (true) {
+		if (existsSync(path.join(current, 'package.json'))) {
+			return current;
+		}
+
+		const parent = path.dirname(current);
+		if (parent === current) {
+			return null;
+		}
 
-	return { commandArgs, siteDir };
+		current = parent;
+	}
 };
 
-let parsedArgs;
+const isWithinDirectory = (parentDirectory, childDirectory) => {
+	const relativePath = path.relative(parentDirectory, childDirectory);
+	return relativePath === '' || (!relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+};
 
-try {
-	parsedArgs = parseArgs(args);
-} catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(1);
-}
+const declaresNornaDependency = (packageJson) => [
+	'dependencies',
+	'devDependencies',
+	'optionalDependencies',
+	'peerDependencies',
+].some((field) => Object.hasOwn(packageJson[field] ?? {}, packageName));
 
-const { commandArgs, siteDir } = parsedArgs;
+const getPackageBinEntrypoint = (packageRoot, packageJson) => {
+	const bin = packageJson.bin;
+	const binPath = typeof bin === 'string' ? bin : bin?.norna;
 
-if (siteDir) {
-	process.env.NORNA_SITE_DIR = siteDir;
-}
+	if (!binPath) {
+		throw new Error(`${packageName} does not define a norna bin entrypoint.`);
+	}
 
-const [command = 'help', ...rest] = commandArgs;
+	return path.resolve(packageRoot, binPath);
+};
 
-if (command === '-h' || command === '--help' || command === 'help') {
-	console.log(usage);
-	process.exit(0);
-}
+const resolveLocalEntrypoint = async () => {
+	const currentPackageRoot = findNearestProjectRoot(path.dirname(currentEntrypoint));
+	const currentPackageJson = currentPackageRoot
+		? await readJsonOptional(path.join(currentPackageRoot, 'package.json'))
+		: null;
+
+	if (
+		currentPackageJson?.name === packageName
+		&& isWithinDirectory(currentPackageRoot, process.cwd())
+	) {
+		return null;
+	}
+
+	const projectRoot = findNearestProjectRoot(process.cwd());
+	if (!projectRoot) {
+		return null;
+	}
+
+	const projectPackageJson = await readJsonOptional(path.join(projectRoot, 'package.json'));
+	if (!projectPackageJson || projectPackageJson.name === packageName || !declaresNornaDependency(projectPackageJson)) {
+		return null;
+	}
+
+	let localPackageJsonPath;
+	try {
+		const requireFromProject = createRequire(path.join(projectRoot, 'package.json'));
+		localPackageJsonPath = requireFromProject.resolve(`${packageName}/package.json`);
+	} catch (error) {
+		if (error.code === 'MODULE_NOT_FOUND') {
+			return null;
+		}
+
+		throw error;
+	}
+
+	const localPackageJson = await readJson(localPackageJsonPath);
+	const localPackageRoot = path.dirname(localPackageJsonPath);
+	return getPackageBinEntrypoint(localPackageRoot, localPackageJson);
+};
+
+const runLocalEntrypoint = (entrypoint) => {
+	const child = spawn(process.execPath, [entrypoint, ...process.argv.slice(2)], {
+		cwd: process.cwd(),
+		env: process.env,
+		stdio: 'inherit',
+	});
+
+	const forwardSignal = (signal) => {
+		if (!child.killed) {
+			child.kill(signal);
+		}
+	};
+	const signals = ['SIGINT', 'SIGTERM'];
+	for (const signal of signals) {
+		process.once(signal, forwardSignal);
+	}
+
+	child.once('exit', (code, signal) => {
+		for (const forwardedSignal of signals) {
+			process.removeListener(forwardedSignal, forwardSignal);
+		}
+
+		if (signal) {
+			process.kill(process.pid, signal);
+			return;
+		}
+
+		process.exit(code ?? 1);
+	});
+
+	child.once('error', (error) => {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+};
+
+const localEntrypoint = await resolveLocalEntrypoint();
+if (localEntrypoint) {
+	const [currentRealpath, localRealpath] = await Promise.all([
+		realpathOptional(currentEntrypoint),
+		realpathOptional(localEntrypoint),
+	]);
 
-const [
-	{ runAstroInherit },
-	{ engineRoot, siteProjectRoot },
-	{ runInherit },
-] = await Promise.all([
-	import('../scripts/lib/astro-command.mjs'),
-	import('../scripts/lib/site-paths.mjs'),
-	import('../scripts/lib/run-command.mjs'),
-]);
-
-const runScript = (relativePath, scriptArgs = []) => runInherit(
-	process.execPath,
-	[path.join(engineRoot, relativePath), ...scriptArgs],
-	{ cwd: siteProjectRoot },
-);
-
-const runBuild = () => runScript('scripts/build-site.mjs');
-
-try {
-	if (command === 'dev' || command === 'dev:local') {
-		await runScript('scripts/dev-local.mjs', rest);
-	} else if (command === 'dev:lan') {
-		await runScript('scripts/dev-local.mjs', ['lan', ...rest]);
-	} else if (command === 'dev:restart') {
-		await runScript('scripts/dev-local.mjs', ['restart', ...rest]);
-	} else if (command === 'dev:status') {
-		await runScript('scripts/dev-local.mjs', ['status', ...rest]);
-	} else if (command === 'dev:logs') {
-		await runScript('scripts/dev-local.mjs', ['logs', ...rest]);
-	} else if (command === 'dev:stop') {
-		await runScript('scripts/dev-local.mjs', ['stop', ...rest]);
-	} else if (command === 'config:check') {
-		await runScript('scripts/check-config.mjs', rest);
-	} else if (command === 'content:check') {
-		await runScript('scripts/sync-content-sections.mjs', ['--check', ...rest]);
-		await runAstroInherit(['sync']);
-	} else if (command === 'content:sync') {
-		await runScript('scripts/sync-content-sections.mjs', ['--write', ...rest]);
-	} else if (command === 'typography:presets') {
-		await runScript('scripts/show-typography.mjs', ['presets', ...rest]);
-	} else if (command === 'typography:show') {
-		await runScript('scripts/show-typography.mjs', ['show', ...rest]);
-	} else if (command === 'site:public') {
-		await runScript('scripts/sync-site-public.mjs', rest);
-	} else if (command === 'images') {
-		await runScript('scripts/generate-images.mjs', rest);
-	} else if (command === 'engine:update') {
-		await runScript('scripts/update-engine.mjs', rest);
-	} else if (command === 'engine:version') {
-		await runScript('scripts/engine-version.mjs', rest);
-	} else if (command === 'init') {
-		await runScript('scripts/init-site.mjs', rest);
-	} else if (command === 'build') {
-		await runBuild();
-	} else if (command === 'build:local') {
-		await runBuild();
-		await runScript('scripts/dev-local.mjs', ['restart']);
-	} else if (command === 'deploy') {
-		await runScript('scripts/deploy-site.mjs', rest);
-	} else if (command === 'deploy:commit') {
-		await runScript('scripts/deploy-site.mjs', ['commit', ...rest]);
-	} else if (command === 'deploy:watch') {
-		await runScript('scripts/watch-pages-deploy.mjs', rest);
-	} else if (command === 'doctor') {
-		await runScript('scripts/doctor.mjs', rest);
-	} else if (command === 'astro') {
-		await runAstroInherit(rest);
-	} else if (command === 'preview') {
-		await runAstroInherit(['preview', ...rest]);
+	if (localRealpath && currentRealpath !== localRealpath) {
+		runLocalEntrypoint(localEntrypoint);
 	} else {
-		throw new Error(`Unknown command: ${command}\n${usage}`);
+		await import(implementationEntrypoint.href);
 	}
-} catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
-	process.exit(1);
+} else {
+	await import(implementationEntrypoint.href);
 }

package/docs/README.md

@@ -11,18 +11,27 @@ For a site maintainer:
 2. [Site Structure](site-structure.md)
 3. [Configuration](configuration.md)
 4. [Content](content.md)
-5. [Images And Metadata](images-and-metadata.md)
-6. [Local Development](local-development.md)
-7. [Publishing](publishing.md)
+5. [Theme](theme.md)
+6. [Typography](typography.md)
+7. [Routes](routes.md)
+8. [Images And Metadata](images-and-metadata.md)
+9. [Local Development](local-development.md)
+10. [Publishing](publishing.md)
 
 For a developer integrating or updating the engine:
 
 1. [Commands](commands.md)
-2. [Command Organization](command-organization.md)
-3. [Site Examples Structure Note](site-examples-structure-note.md)
-4. [Configuration](configuration.md)
-5. [Content](content.md)
-6. [Engine Development](engine-development.md)
+2. [Configuration](configuration.md)
+3. [Content](content.md)
+4. [Theme](theme.md)
+5. [Typography](typography.md)
+6. [Routes](routes.md)
+7. [Engine Development](engine-development.md)
+
+For design and naming principles:
+
+1. [Command Organization](design/command-organization.md)
+2. [Site Examples Structure](design/site-examples-structure.md)
 
 For a quick reference:
 
@@ -30,19 +39,30 @@ For a quick reference:
   `site/config.mjs` field, including `layout.pageWidth`, `layout.gutter`,
   gallery viewport limits, `typography.fontFamily`, validation rule, and
   default.
-- [Content](content.md) describes page and route frontmatter, section
-  frontmatter, typography presets, site themes, inline styles, temporary
-  sections, Markdown section matching, and content validation.
+- [Content](content.md) describes page frontmatter, section frontmatter,
+  galleries, carousels, temporary sections, Markdown section matching, and
+  content validation.
+- [Theme](theme.md) describes site-wide presentation, page and section
+  presentation overrides, frame colors, and inline styles.
+- [Typography](typography.md) describes presets, roles, overrides,
+  inheritance, and inspection commands.
+- [Routes](routes.md) describes route files, slugs, route navigation, and
+  route image directories.
 - [Commands](commands.md) lists the public CLI surface and starter npm scripts.
-- [Command Organization](command-organization.md) defines command namespaces
-  for pure gallery projects, mixed projects, and engine development.
 - [Site Structure](site-structure.md) separates versioned source files from
   generated build output.
-- [Site Examples Structure Note](site-examples-structure-note.md) defines the
-  intended vocabulary for starters, examples, docs sites, reference docs, and
-  fixtures before any repository reorganization.
+
+Design documents are intentionally separate from the user reference:
+
+- [Command Organization](design/command-organization.md) defines command
+  namespaces for pure gallery projects, mixed projects, and engine development.
+- [Site Examples Structure](design/site-examples-structure.md) defines the
+  intended vocabulary for starters, examples, documentation sites, reference
+  docs, and fixtures.
 
 Site repositories should document only their site-specific choices and link here
 for generic `norna` behavior.
 
+`norna` is licensed under [GNU GPL v3](../LICENSE).
+
 Planning and future work are tracked in [../BACKLOG.md](../BACKLOG.md).

package/docs/commands.md

@@ -1,7 +1,17 @@
 # Commands
 
-The `norna` binary is the stable command surface. The starter's npm
-scripts are thin aliases around these commands.
+The `norna` binary is the stable command surface. Site repositories normally
+use starter npm scripts such as `npm run norna:content:check`; those scripts
+call the local `norna` binary from `node_modules/.bin`.
+
+Npm installation exposes the command as `norna` on macOS, Linux, and Windows
+through the package `bin` field. When a globally installed `norna` is started
+inside a project that declares and has installed its own `@janga/norna`
+dependency, the launcher delegates to that project-local version. If no
+project-local install is found, the version that was started continues running.
+
+Use direct `norna ...` commands only when the binary is on your shell `PATH`,
+inside an npm script, or through `npm exec -- norna ...`.
 
 ## CLI Commands
 
@@ -97,8 +107,9 @@ should normally mean the repository's complete publishable artifact, while
   image files after confirmation.
 - `typography:presets`: prints the exact built-in values for every typography
   preset.
-- `typography:show`: prints the selected site's resolved typography after
-  applying theme, page, and section presentation.
+- `typography:show`: prints the selected site's resolved typography for the
+  theme, every page route, and every section. Each value includes its source,
+  and inherited page or section values are marked with `inherited: true`.
 - `site:public`: copies `site/public/` into `site/.norna/public/` and
   removes stale copied static files.
 - `images`: generates WebP variants and writes
@@ -120,7 +131,9 @@ should normally mean the repository's complete publishable artifact, while
 - `build`: runs config check, content check, public sync, image generation, and
   Astro build.
 - `build:local`: runs `build` and restarts `dev:local`.
-- `dev:local`: starts Astro dev in background mode on `localhost:4321`.
+- `dev:local`: starts Astro dev in background mode on `localhost:4321`. Pass
+  `--kill` to stop processes that are blocking the standard port before
+  starting.
 - `dev:lan`: starts the same server on all local network interfaces and prints
   the IPv4 URL to open from another device on the same network. Stop it after
   testing because it is accessible to that local network.