Instructions for coding assistants

These instructions apply to the entire repository. Read README.md before making changes; it is the authoritative operations and deployment runbook.

Communication and authorization

Do not assume the user's desired behavior, architecture, infrastructure, or content structure when the answer would materially affect the result.
When the user says discussion only, do not edit files, run mutating commands, commit, push, deploy, or change external systems.
An implementation request authorizes work only within its clearly stated scope. Proceed with routine steps inside that scope, but ask before expanding it or making a consequential choice the user has not made.
Before implementation, state the intended files and systems to be changed.
Ask before adding dependencies, plugins, services, scheduled jobs, network listeners, credentials, or new deployment mechanisms.
Do not commit or push unless the user explicitly asks. A push to main automatically deploys production, so call out that consequence beforehand.
Preserve unrelated edits and uncommitted work. Never discard or overwrite changes merely to obtain a clean worktree.

This is a native Lektor site. Prefer built-in Lektor behavior and the repository's existing models, templates, and assets.
Do not introduce custom plugins or additional software unless explicitly approved.
Keep Lektor content in its normal record layout: a content directory for each record containing contents.lr. Do not replace this with a flat Markdown workflow unless the user explicitly approves that architectural change.
Treat the Git repository as the source of truth. Never edit generated files in /srv/labyricorn/current, /srv/labyricorn/releases, build/, or dist/.
Keep generated output and local caches out of Git.
Make focused changes. Avoid opportunistic refactors, design changes, or content rewrites outside the requested task.

Treat the child records under content/tags/ as the single controlled tag vocabulary. Their lowercase, hyphenated directory names are the canonical slugs stored in entry tags fields and used in public tag URLs.
Keep the entry model's checkbox choices dynamically sourced from content/tags/; do not duplicate the vocabulary in model configuration or introduce free-form spelling and capitalization variants.
Add a tag record before assigning its slug to an entry. When renaming or retiring a tag, update all references deliberately and verify that no orphan slug or broken tag URL remains.
Preserve normal links to dedicated tag pages as the no-JavaScript baseline. Client-side filtering must remain a progressive enhancement with semantic buttons, keyboard support, and an announced result count.
Tag-directory counts and dedicated tag pages must include both blog entries and articles, but not project records unless the documented product scope is explicitly changed.
When README.md changes, keep the README-derived example blog entry aligned with the runbook content it demonstrates.

Inspect the existing implementation before editing; do not infer that a file, model, template, service, or repository exists.
Run lektor build --output-path build after changes that can affect generated output. Treat build warnings and errors as results to report.
For template or CSS work, check the affected page at desktop and narrow viewport sizes and preserve accessible, semantic markup.
When template changes rely on updated CSS or other static assets, increment the relevant cache-busting version in the template and verify that generated pages reference the new asset URL.
For taxonomy changes, verify every entry tag has a matching content/tags/ record, tag counts match rendered blog/article usage, dedicated tag URLs build, and listing filters work with valid, absent, and unknown query values.
Run git diff --check and review the exact diff before committing.
If a push was requested, verify the Gitea Action result, deployed revision, and site health instead of treating a successful git push as completion.

Pushes to main run .gitea/workflows/deploy.yml and deploy production using /usr/local/bin/deploy-labyricorn.
Do not alter the workflow, deployment scripts, runner, nginx, systemd units, firewall, TLS or Cloudflare settings, permissions, Git authentication, or Lektor admin exposure without explicit approval for that specific area.
Never bypass the deployment script by copying generated files directly into the active site.
Preserve the least-privilege separation between gitea-runner, labyricorn-deploy, and root.
Never expose an unauthenticated deployment or administration endpoint.

Never commit, print, or reproduce passwords, access tokens, registration tokens, .netrc contents, runner state, private keys, or other credentials.
Do not place credentials in Git remotes, workflow files, command examples, or generated site output.
Update README.md whenever an approved change alters installation, operations, deployment, recovery, credentials handling, or administrator procedures.
At handoff, summarize files changed, validation performed, commit and push status, automation result, and deployed revision as applicable.