# Instructions for coding assistants

These instructions apply to this repository. Read `README.md` and the relevant
scoped `AGENTS.md` files before making changes.

## Communication and authorization

- Do not assume the user's desired behavior, architecture, or content structure
  when the answer would materially affect the result.
- When the user requests discussion or review, do not edit files, run mutating
  commands, commit, or push.
- An implementation request authorizes work only within its clearly stated
  scope. Routine steps within that scope may proceed, but confirm before
  expanding scope or making irreversible choices.
- Before implementation, state the intended files and systems to be changed.
- Do not commit or push unless the user explicitly requests it.
- Preserve unrelated edits and uncommitted work. Never discard changes merely
  to obtain a clean working tree.

## Project and publishing boundaries

- Application and project source code lives at the repository root and normal
  subdirectories.
- The `.labyricorn/` directory is the repository-owned source for project
  exhibition records and development logs published on Labyricorn.
- Keep publishing records in `.labyricorn/` aligned with actual repository
  implementation and history.
- Read `.labyricorn/AGENTS.md`, `.labyricorn/project/AGENTS.md`, and
  `.labyricorn/devlog/AGENTS.md` when modifying publishing records.

## Content contract and devlog practices

- Use native Lektor records named `contents.lr` with `schema_version: 1`.
- Keep attachments inside the record subtree that owns them (PNG, JPEG, WebP).
- Do not introduce raw HTML, scripts, executable files, builds, or credentials
  below `.labyricorn/`.
- For devlog entries, base records on verifiable repository commits and history.
  Set `source_commit` to the full 40-character commit ID on the branch.
- Devlog dates should reflect the commit's calendar date (`YYYY-MM-DD`).

## Validation and review

- Run `python devlog_editor.py --validate` to verify that `.labyricorn/` records,
  project identity, devlog index, and devlog entries adhere to the schema.
- Alternatively, launch the graphical editor with `python devlog_editor.py` for
  interactive management of devlog entries and publishing status.
- Run `git diff --check` and review diffs carefully before staging or committing.
- At handoff, summarize files changed, validation performed, and any next steps.

##  Authoritative project documents, in priority order:

This repository is the canonical home of the shared Contract Specification and
Authoring Guide, and owns the NGN Implementation Plan. Documents in
`docs/reference/` describe external implementations, not NGN architecture.
Reference exhibits under `test-fixtures/` are test/reference fixtures, not product
code. Keep exhibit-specific names and paths in test configuration or documentation.

XZBT-NGN and its maintained reference exhibits move forward with the contract.
Contract 5.3 is the current maintained contract; it supersedes 5.2 additively
(no 5.2 normative requirement was removed, weakened, or reinterpreted). The
`xzbt` envelope field is advisory metadata only (Contract §6.5) and MUST NOT be
used as an exact-string compatibility gate anywhere in this repository --
real compatibility is negotiated by the handshake and contract fields.
Backward compatibility with a genuine 5.2 exhibit remains a protocol-level
requirement of the contract itself (Section 28.2), but that is a different
thing from keeping a *currently maintained* reference exhibit or its test
coverage frozen on 5.2: there is no such requirement, and maintained exhibits
are expected to advance with the contract instead.

- XZBT Exhibit Contract Specification v5.3 (current; supersedes v5.2 below)
- XZBT-NGN Exhibit Engine Implementation Plan v5.2
- XZBT Exhibit Authoring Guide v5.2
- Step 3.7 reference exhibit report
- XZBT Exhibit Contract Specification v5.2 (historical predecessor, retained for context)

- Do not infer XZBT-NGN behavior from SciFi-XZBT source code.
- SciFi-XZBT is an external exhibit implementation, not the NGN architecture.