# 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.

## Project boundaries

- 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.

## Validation

- 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.
- 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.

## Deployment and infrastructure

- 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.

## Security and documentation

- 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.