@gspothq/cli 0.1.1 → 0.2.0

package/configurations/language/bash/rules/OPERATIONS.md

@@ -1,14 +1,16 @@
 # Bash Operations
 
+Read this rule when you write a deployment, publishing, or remote shell script.
+
 ## Module ownership and visibility
 
 <!-- level: all -->
 
-Each file owns one cohesive responsibility, and the directory supplies the family name.
+Each file owns one cohesive responsibility, and the folder supplies the family name.
 
 - A sourced public function carries its family name, such as `release_prepare` or
   `cache_read_state`.
-- A function with one caller lives in the caller's file.
+- Keep a function with one caller in the same file as the call.
 
 ## Deployment and publishing pipelines
 
@@ -16,11 +18,11 @@ Deployment, publishing, and long-running scripts separate validation, planning,
 execution, readiness checks, and cleanup.
 
 - Fail before any work when the script lacks a required input, command, file, host, or secret.
-- Name the target explicitly: never infer production, a remote, a host, or an artifact from a
+- State the target explicitly: never infer production, a remote, a host, or an artifact from a
   branch name without a confirmation or a CI contract.
 - A destructive or remote action asks for confirmation unless CI owns the guard.
 - Use idempotent commands and stop at the first failed required step.
-- Check readiness after deploying or publishing, and print diagnostics a person can act on.
+- Check readiness after deploying or publishing, and print messages a person can act on.
 - Keep rollback and cleanup explicit, and delete no artifact or result as a side effect.
 - Log enough to reconstruct what happened, without secrets.
 
@@ -44,9 +46,9 @@ confirm_exact() {
 ## Remote commands
 
 Copy a reviewed script to the remote host and invoke it with arguments. SSH joins its arguments
-into one remote shell string, so local quoting does not keep remote argument boundaries. Validate
-host, user, service, and path values before using them, never build a remote command from user
-input, and give every remote call that can hang a timeout.
+into one remote shell string, so local quoting does not keep their boundaries. Validate host,
+user, service, and path values before you use them. Never build a remote command from user
+input. Give every remote call that can hang a timeout.
 
 Good, for a remote Bash login shell:
 
@@ -58,7 +60,7 @@ ssh -- "${host}" "${remote_command}"
 ## Persisted state
 
 Never `source` generated state or pass it to `bash -c`. Write state in a fixed data format with an
-exact key schema to a restricted file in the destination folder, and replace the previous state
+exact key schema to a restricted file in the destination folder. Replace the previous version
 with an atomic `mv`. A reader treats a malformed, duplicate, or unknown key as an error.
 
 ## Retries

package/configurations/language/bash/rules/SAFETY.md

@@ -1,11 +1,12 @@
 # Bash Safety
 
+Read this rule when a shell script runs commands, handles paths, downloads files, or deletes files.
+
 ## Calling commands
 
-Use fixed command names with argument arrays, never strings built from input, and a script
-never passes untrusted input to a shell. Never use `bash -lc` in repository scripts, and a
-function that runs a caller-supplied command takes the command and its arguments after
-`shift` and invokes `"$@"`.
+Use fixed command names with argument arrays, never strings built from input. Never pass
+untrusted input to a shell. Never use `bash -lc` in repository scripts. A function that runs a
+caller-supplied command takes it and its arguments after `shift` and invokes `"$@"`.
 
 Check uncommon commands with `command -v` before a long-running, destructive, publishing, or
 error-handling path depends on them. Prefer builtins and parameter expansion to external
@@ -28,14 +29,14 @@ require_command() {
 
 ## Processes and privilege
 
-Treat process names as advisory information, never authorization. Stop and restart paths stop only
-process ids recorded by the owning script family, found through the service manager, a `PID` file, or
-`pgrep -x`, never `ps | grep`. A script that starts background jobs saves each `PID`, waits for
-each, captures each status, and writes per-job output to separate files. It bounds its
+Treat process names as advisory information, never authorization. Stop and restart paths kill only
+process ids that the owning script family recorded, found through the service manager, a `PID` file, or
+`pgrep -x`, never `ps | grep`. A script that starts background jobs saves every `PID`, waits for
+each job, captures its status, and writes its output to a separate file. It bounds its
 fan-out and kills owned children on `INT`, `TERM`, and `EXIT`. `sudo command > file` redirects
 as the current user, and a glob in `sudo command /path/*` expands before `sudo` runs.
-Privileged writes go through `sudo tee`, and keep a privileged shell string as a fixed literal
-with no input.
+Send privileged writes through `sudo tee`, and keep the shell string you pass to `sudo` a fixed
+literal with no input.
 
 ```bash
 generate_config | sudo tee /etc/service/config >/dev/null
@@ -74,7 +75,7 @@ with ad hoc `grep | sed | awk` unless the script controls the input and the form
 Prefer machine output modes such as JSON, `NUL`, or explicit format flags and never parse process lists,
 pretty tables, progress bars, or localized text by fixed field numbers. Quote `tr` character
 classes and pin `LC_ALL=C` when converting case. macOS and GNU `sed -i` differ; a committed
-script rewrites through a temporary file unless its documentation restricts it to one platform.
+script rewrites through a temporary file unless its documentation restricts it to one system.
 
 ```bash
 # get_service_url: Prints a required nonempty service URL from JSON configuration.
@@ -89,9 +90,9 @@ get_service_url() {
 
 ## Network
 
-Downloads use `curl --fail --show-error --silent --location` into an explicit file, with
-tool-native timeouts such as `--connect-timeout` plus `--max-time`, or SSH `ConnectTimeout`, rather
-than GNU `timeout`, which macOS lacks. Download executable content, verify it against an
+Download with `curl --fail --show-error --silent --location` into an explicit file. Set timeouts
+with the options of the tool, such as `--connect-timeout` plus `--max-time`, or SSH `ConnectTimeout`.
+Do not use GNU `timeout`, which macOS lacks. Download executable content, verify it against an
 independently obtained checksum or signature, and only then run it.
 
 ```bash
@@ -132,19 +133,19 @@ require_env() {
 
 ## Temporary files, locks, and cleanup
 
-Temporary paths come from `mktemp` or `mktemp -d` under the system or an explicit project
-temp directory, never from predictable names. Register cleanup immediately after creation.
+Create temporary paths with `mktemp` or `mktemp -d` under the system location or a dedicated
+project folder, never with predictable names. Register cleanup immediately after creation.
 Put downloaded, copied, or generated content in a temporary file, validate it with the real
 parser, and replace the destination with `mv`. The file keeps the restrictive permissions
 `mktemp` gave it unless deployment needs others. Remove failed artifacts unless the script
-documents keeping them. Acquire locks atomically with a `mkdir` lock directory holding
-the owner `PID` or with `noclobber` redirection, never with a `test` followed by a create.
+documents keeping them. Acquire a lock atomically with `mkdir` on a folder that stores the holder
+`PID`, or with `noclobber` redirection, never with a `test` followed by a create.
 
 Stop commands remove only what the script created. Validate a cleanup path from
 input or persistent state against its permitted root. Reject empty values, `/`,
-the repository root, `$HOME`, symlinks, and anything outside the owner. Keep a `mktemp -d` result
+the repository root, `$HOME`, symlinks, and anything outside the folder the script created. Keep a `mktemp -d` result
 exactly. Never widen the path to its neighbors. `|| true` never follows a destructive
-command or a required installation, publishing, build, or runtime command.
+step or a required installation, publishing, build, or runtime command.
 
 ```bash
 downloaded_file="$(mktemp "${config_file}.XXXXXX")" || exit 1
@@ -165,11 +166,12 @@ printf '%s\n' "$$" >"${lock_dir}/pid" || {
 trap 'rm -f -- "${lock_dir}/pid"; rmdir -- "${lock_dir}"' EXIT
 ```
 
-Put recursive deletes in one script, and accept that script with an `[[ignore]]` record for `bash/safety`.
-Validate its cleanup path against the owner root:
+Put recursive deletes in one script. To accept the `bash/safety` finding for that script, follow the suppression
+rules.
+Validate its cleanup path against the approved root folder:
 
 ```bash
-# remove_build_dir: Removes the build child of the approved owner directory.
+# remove_build_dir: Removes the build child of the approved root folder.
 remove_build_dir() {
   local owner_root build_dir
 
@@ -186,10 +188,9 @@ remove_build_dir() {
 
 macOS and BSD
 differ from GNU in `sed`, `date`, `readlink`, `mktemp`, `stat`, `xargs`, and `grep`; keep a
-platform-specific branch with the operation that owns it. Handle `realpath` and `date`
-parsing differences. macOS `/bin/bash` uses an old Bash version,
-Linux-only utilities need checks in macOS-compatible scripts, and CI does not share the
-developer's `PATH`. Symlink-aware absolute paths come from `pwd -P` after `cd`, or from
+system-specific branch with the operation that owns it. Handle `realpath` and `date`
+parsing differences. macOS `/bin/bash` runs an old Bash version. Linux-only utilities need
+checks in scripts that also run on macOS. CI does not share the `PATH` of the developer. Symlink-aware absolute paths come from `pwd -P` after `cd`, or from
 product-owned application code.
 
 ## Verification and debugging
@@ -198,13 +199,15 @@ Run the configured syntax, ShellCheck, and shfmt commands. Run destructive or pr
 only in a throwaway environment.
 
 Production scripts gain no test-only flags, branches, or command replacements. When
-debugging, start from the exact error and line Bash reports, run `bash -n` and ShellCheck,
+debugging, start from the exact error and line Bash reports. Run `bash -n` and ShellCheck,
 reduce to the smallest reproducing block, and expose invisible characters with
-`printf '%q\n'`. Trace with `bash -x` or a local `set -x` block with a `PS4` naming file, line, and function,
-only while diagnosing, never around secrets, and never commit broad tracing, `trap DEBUG`, or stepping
+`printf '%q\n'`.
+
+Trace with `bash -x` or a local `set -x` block whose `PS4` names file, line, and function,
+only while you debug. Never commit broad tracing, `trap DEBUG`, or stepping
 code. Bash 4.4 supports `BASH_XTRACEFD`. A debug helper preserves the status it diagnoses.
 
-Common causes follow. `unexpected EOF` indicates an unmatched quote, an unterminated here document,
+`unexpected EOF` indicates an unmatched quote, an unterminated here document,
 a missing `fi`, `done`, or `esac`, or a CRLF ending hiding the delimiter.
 
 `too many arguments` indicates an unquoted expansion inside `[ ... ]`. `event not found` indicates interactive history expansion
@@ -213,10 +216,11 @@ Failure before the shebang indicates a byte order mark (BOM) or CRLF.
 
 ## Refactoring existing scripts
 
-Read the whole script and its sourced libraries, identify the caller interface: local, CI,
-remote host, or package script, and preserve behavior before changing style. Fix quoting and
-argument arrays near the touched logic, and add explicit checks around dangerous commands.
-Share a helper across the script family only when it has a real shared contract. Do not
+Read the whole script and its sourced libraries. Identify the caller interface: local, CI,
+remote host, or package script. Preserve behavior before you change style.
+
+Fix quoting and argument arrays near the touched logic, and add explicit checks around dangerous commands.
+Share a helper across the script family only when it has a real common contract. Do not
 convert a large script in one pass or change shebangs across a family without verifying the
 runtime. Run the narrow shell lint and format command before the broader checks. Move complex script
 logic into application code and call it directly.

package/configurations/language/css/manifest.toml

@@ -1,7 +1,8 @@
 allowed_words = ["CSS"]
+
 [configuration]
+description = "CSS files and style blocks in Vue and Svelte components: Stylelint with the standard rules, Prettier for layout, and module classes both defined and used. SCSS gets formatting only."
 title = "CSS"
-description = "CSS files and the style blocks of Vue and Svelte components: Stylelint with the standard rules, Prettier for layout, and CSS module classes that are both defined and used. SCSS receives formatting only."
 
 [detect]
 extensions = [".css", ".vue", ".svelte"]
@@ -9,90 +10,50 @@ extensions = [".css", ".vue", ".svelte"]
 [files]
 extensions = [".css"]
 
+[rules]
+"TAILWIND.md" = { dependencies = ["tailwindcss"] }
+
 [[tool]]
 name = "stylelint"
+npm = "stylelint"
+replace = [".stylelintrc", ".stylelintrc.json", ".stylelintrc.js", ".stylelintrc.cjs", ".stylelintrc.mjs", ".stylelintrc.yml", ".stylelintrc.yaml", "stylelint.config.js", "stylelint.config.cjs", "stylelint.config.mjs"]
 suppression = { marker = "^(?:/\\*|//)\\s*stylelint-disable(?:-next-line|-line)?(?=\\s|$)", reason = " -- (?<reason>\\S(?:[\\s\\S]*?\\S)?)\\s*(?:\\*/)?$" }
 version = "16.23.1"
-npm = "stylelint"
-[[tool.replace]]
-file = ".stylelintrc"
-shared = false
-
-[[tool.replace]]
-file = ".stylelintrc.json"
-shared = false
-
-[[tool.replace]]
-file = ".stylelintrc.js"
-shared = false
-
-[[tool.replace]]
-file = ".stylelintrc.cjs"
-shared = false
-
-[[tool.replace]]
-file = ".stylelintrc.mjs"
-shared = false
 
-[[tool.replace]]
-file = ".stylelintrc.yml"
-shared = false
-
-[[tool.replace]]
-file = ".stylelintrc.yaml"
-shared = false
-
-[[tool.replace]]
-file = "stylelint.config.js"
-shared = false
-
-[[tool.replace]]
-file = "stylelint.config.cjs"
-shared = false
-
-[[tool.replace]]
-file = "stylelint.config.mjs"
-shared = false
-
-[[tool.replace]]
+[[tool.replace_key]]
 file = "package.json"
 key = "stylelint"
 redirect = true
-shared = true
 
 [[tool]]
-name = "stylelint-config-standard"
 kind = "library"
-version = "39.0.0"
+name = "stylelint-config-standard"
 npm = "stylelint-config-standard"
+version = "39.0.0"
 
 [[tool]]
-name = "postcss-html"
 kind = "library"
-version = "2.0.0"
+name = "postcss-html"
 npm = "postcss-html"
+version = "2.0.0"
 
 [[tool_file]]
-target = ".gspot/config/stylelint.json"
-tool = "stylelint"
-rule_keys = ["rules"]
 per_scope = true
 pointer = { path = ".stylelintrc.json", body = "{\n    \"extends\": \"{target}\"\n}\n" }
+target = ".gspot/config/stylelint.json"
+tool = "stylelint"
 
 [[check]]
-name = "stylelint"
-tool = ["stylelint", "stylelint-config-standard"]
-example = "The declaration `color: #ggg` uses an invalid hexadecimal color and reports a Stylelint finding. Replace it with a valid intended color such as `#abc`."
-level = "recommended"
-stage = "commit"
 command = ["stylelint", "--config", "{tool_file:stylelint}", "--config-basedir", "{root}/.gspot", "--formatter", "unix", "--allow-empty-input", "{files}"]
-fix = ["stylelint", "--config", "{tool_file:stylelint}", "--config-basedir", "{root}/.gspot", "--fix", "--allow-empty-input", "{files}"]
+example = "The declaration `color: #ggg` holds an invalid hex value and reports a finding. Replace it with a valid one such as `#abc`."
 exit_codes = [2]
 files = { extensions = [".css", ".vue", ".svelte"] }
+fix = ["stylelint", "--config", "{tool_file:stylelint}", "--config-basedir", "{root}/.gspot", "--fix", "--allow-empty-input", "{files}"]
+help = "Run `gspot check --fix` for the rules that fix themselves. Turn one rule off with `gspot ignore css/stylelint --rule <name> --reason \"<why>\"`."
+level = "recommended"
+name = "stylelint"
 output = { format = "regex", pattern = "^(?<file>.+?):(?<line>\\d+):(?<column>\\d+): (?<message>.*) \\((?<rule>[\\w/@-]+)\\) \\[\\w+\\]$" }
+stage = "commit"
 summary = "Lints every stylesheet with the standard stylelint rules: unknown properties, overridden selectors, and invalid values."
-why = "A browser skips a declaration it cannot read without a word, so a typo in a property ships as a missing style."
-help = "Run gspot check --fix for the rules that fix themselves. Turn one rule off with gspot ignore css/stylelint --rule `<name>` --reason \"`<why>`\"."
-
-[rules]
-"TAILWIND.md" = { dependencies = ["tailwindcss"] }
+tool = ["stylelint", "stylelint-config-standard"]
+why = "A browser silently skips a declaration it cannot parse, so a typo in a property ships as a missing style."

package/configurations/language/css/rules/CSS.md

@@ -1,5 +1,7 @@
 # CSS
 
+Read this rule when you change a stylesheet.
+
 ## Correctness and accessibility
 
 - Use logical properties where layout follows the writing direction.
@@ -9,7 +11,7 @@
 
 <!-- level: all -->
 
-- Keep shared color, spacing, type, radius, and motion tokens in one owner.
+- Keep shared color, spacing, type, radius, and motion tokens in one file.
 - Keep feature styles with their component or import them through the stylesheet entry.
 - Order rules from general styles to component states.
 
@@ -18,7 +20,7 @@
 <!-- level: all -->
 
 - Prefer class selectors with low specificity.
-- Prefer grid and flexbox for layout. Keep flow content in normal document flow.
+- Prefer grid and flexbox for layout. Keep content in normal document flow.
 
 ## Files
 
@@ -26,3 +28,20 @@
 
 - Keep presentation in stylesheets or framework-owned component style blocks.
 - Let the framework own style scoping rather than duplicating selectors manually.
+
+## Naming
+
+### Selector and file names
+
+<!-- level: all -->
+
+- Name classes for the component or state, such as `order-card`, `order-card-title`, `is-active`, or `has-error`.
+- A state class starts with `is-` or `has-`. A script toggles it. Never style it alone.
+- Custom properties name the role of the value, not its appearance:
+  `--color-surface`, `--space-2`, `--font-size-body`, never `--blue` or `--big-margin`.
+- Theme overrides reuse the same property names under their selector and add no new ones.
+- Keyframe names describe the motion, such as `fade-in` or `slide-from-start`.
+- Name stylesheet files for what they hold, such as `order-card.css`,
+  `tokens.css`, or `layout.css`.
+- When the project uses a utility system, keep its class names. Do not write your own utility classes
+  beside it.

package/configurations/language/css/rules/TAILWIND.md

@@ -1,13 +1,15 @@
 # Tailwind CSS
 
+Read this rule when you change Tailwind CSS classes or configuration.
+
 ## Generated styles
 
 - Verify that source detection covers templates and content containing class names. Tailwind CSS 4
-  detects sources automatically; register excluded sources with `@source`. Tailwind CSS 3 uses
+  detects sources automatically; register excluded ones with `@source`. Tailwind CSS 3 uses
   `content` configuration.
 - Keep complete class names in source so the scanner can find them.
 - Preserve the application's configured dark-mode strategy.
-- When the project configures a class-ordering formatter plugin, let that formatter own ordering.
+- When the project configures a formatter plugin that sorts classes, let it own the order.
 
 Use the [source detection documentation](https://tailwindcss.com/docs/detecting-classes-in-source-files)
 for the installed major version.
@@ -17,10 +19,10 @@ for the installed major version.
 <!-- level: all -->
 
 - Use theme tokens for colors, spacing, radii, fonts, and breakpoints. Explain deliberate values
-  outside those tokens at their owner.
+  outside those tokens where the code uses them.
 - Compose component styles with utility classes. Keep reusable theme and utility declarations
-  in their configured style owner.
+  in the configured stylesheet.
 - Use the project's adopted class-merging function when conditional utilities conflict.
   Do not introduce a separate merging implementation.
 - Avoid handwritten CSS that duplicates an existing utility without a component requirement.
-- Follow the installed Tailwind version's syntax for custom utilities, variants, and plugins.
+- Follow the syntax of the installed Tailwind version for custom utilities, variants, and plugins.

package/configurations/language/html/manifest.toml

@@ -1,59 +1,40 @@
 allowed_words = ["HTML"]
+
 [configuration]
+description = "HTML files: html-validate for structure and accessibility, and no inline script or handler."
 title = "HTML"
-description = "HTML files: html-validate for structure and accessibility, no inline script or handler, and templates that hold placeholders in place of copy."
 
 [files]
 extensions = [".html", ".htm"]
 
 [[tool]]
 name = "html-validate"
+npm = "html-validate"
+replace = [".htmlvalidate.json", ".htmlvalidate.js", ".htmlvalidate.cjs"]
 suppression = { marker = "^<!--\\s*\\[?html-validate-disable(?:-next|-block)?(?=\\s|\\]|$)", reason = "(?: -- |: )(?<reason>\\S(?:[\\s\\S]*?\\S)?)\\s*\\]?\\s*(?:--!?>)?$" }
 version = "11.6.1"
-npm = "html-validate"
-[[tool.replace]]
-file = ".htmlvalidate.json"
-shared = false
-
-[[tool.replace]]
-file = ".htmlvalidate.js"
-shared = false
-
-[[tool.replace]]
-file = ".htmlvalidate.cjs"
-shared = false
 
 [[tool_file]]
+check = "html/html-validate"
 target = ".gspot/config/html-validate-source.json"
 tool = "html-validate"
-check = "html/validate"
-rule_keys = ["rules"]
 
 [[check]]
-name = "validate"
-example = "An `<img src=\"logo.png\">` element without alternative text reports an accessibility finding under the configured rules. Add meaningful `alt` text, or an empty `alt` value for a decorative image."
-level = "recommended"
-stage = "commit"
 command = ["html-validate", "--config", "{tool_file:html-validate-source}", "--formatter", "json", "{files}"]
+example = "An `<img src=\"logo.png\">` without alternative text reports a finding. Add `alt` text, or leave it empty for a decorative image."
+help = "Change the markup the way the rule page says. Turn one rule off with `gspot ignore html/html-validate --rule <name> --reason \"<why>\"`."
+level = "recommended"
+name = "html-validate"
 output = { format = "json", children = "messages", fields = { file = "filePath", line = "line", column = "column", rule = "ruleId", message = "message" } }
-summary = "Validates every HTML file: elements where they may sit, required attributes, text alternatives, and one style for void elements."
-why = "A browser repairs broken markup in its own way, and a screen reader reads what the repair left."
-help = "Change the markup the way the rule page says. Turn one rule off with gspot ignore html/validate --rule `<name>` --reason \"`<why>`\"."
-
-[[check]]
-name = "scripts"
-example = "A button using an inline `onclick` attribute reports embedded executable code. Remove the attribute and attach the event listener from a separate script file."
-level = "all"
 stage = "commit"
-summary = "Refuses executable inline script, event handler attributes, and executable script or data URLs in HTML files."
-why = "A content security policy that allows inline script allows an injected one too, so the policy only holds when the pages hold none."
-help = "Move the script into a file, and attach the handler from that file. Structured data of type application/ld+json stays inline."
+summary = "Validates HTML files for nesting, required attributes, text alternatives, and one style for void elements."
+why = "Each browser repairs broken markup differently, and a screen reader announces only what remains."
 
 [[check]]
-name = "template-text"
-example = "Text written into a file listed in html.templates reports a literal. Move the text to its content file and use a placeholder in the template."
+example = "A button with an inline `onclick` attribute reports a finding. Remove it, and attach the listener from a script file."
+help = "Move the script into its own file, and attach the handler there. Structured data of type `application/ld+json` stays inline."
 level = "all"
+name = "scripts"
 stage = "commit"
-summary = "In the template files named by html.templates, checks that text a person reads is a placeholder and never a literal."
-why = "Copy written into a template is copy no translator and no content file ever sees."
-help = "Replace the text with a placeholder and put the words in the content file. Remove files that are not templates from html.templates."
+summary = "Reports inline scripts, event handler attributes, and executable URLs in HTML files."
+why = "A content security policy can block injected code only when the pages carry no inline script."

package/configurations/language/html/rules/HTML.md

@@ -1,18 +1,19 @@
 # HTML
 
+Read this rule when you change HTML or an HTML template.
+
 ## Document
 
-- `<html lang="...">` names the page language; set `dir` for a right-to-left language.
+- `<html lang="...">` names the page language; set `dir` for right-to-left text.
 - One `<title>` that names the page, a `<meta name="viewport">`, and a `<meta charset="utf-8">`
   first in `<head>`.
 - Landmarks such as `header`, `nav`, `main`, `footer`, and `aside` structure the page. One `main`.
 
 ## Elements
 
-- Use the element that means the thing: `button` for actions, `a` for navigation with a real
-  `href`, `nav` for navigation, `ul` and `ol` for lists, `table` for data, `time` with `datetime`
-  for dates, `figure` and `figcaption` for captioned media.
-- Never a `div` or `span` with a click handler standing in for a button or link.
+- Use the element that means the thing: `button` for actions, `a` with a real `href` for links,
+  and `nav` for navigation. Use `ul` and `ol` for lists, `table` for data, `time` with `datetime`
+  for dates, and `figure` and `figcaption` for captioned media.
 - `target="_blank"` links carry `rel="noopener"`.
 
 ## Script safety
@@ -25,3 +26,20 @@
 
 - A template stays declarative: no logic beyond conditionals and loops the engine provides.
 - Generate deterministic HTML: the same inputs produce byte-identical output.
+
+## Naming
+
+### Route and attribute names
+
+<!-- level: all -->
+
+- Use kebab-case file names that match the public route: `about-us.html`, `pricing/index.html`.
+  Folder routes end in `index.html` in generated output.
+- Name public route segments in lowercase kebab-case with no trailing slash ambiguity: one
+  canonical form, with the other redirected.
+- Use `id` attributes for anchors, labels, and descriptions, not for styling.
+- Name `data-*` attributes in kebab-case for their value, such as `data-device-class`.
+- Placeholders follow the engine's convention and name the value.
+- Name content files for the route or topic they serve, such as `content/legal/privacy.md`.
+- Name asset files in kebab-case for their subject and role, such as `hero-phone-dark.webp`. Never use
+  `image1.png` or `final-v2.svg`. Generate hashed names rather than writing them by hand.