74 lines
3.8 KiB
Markdown
74 lines
3.8 KiB
Markdown
# 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.
|