XZBT-NGN/AGENTS.md

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 Exhibit Contract Specification v5.2

• XZBT-NGN Exhibit Engine Implementation Plan v5.2

• XZBT Exhibit Authoring Guide v5.2

• Step 3.7 reference exhibit report

• Do not infer XZBT-NGN behavior from SciFi-XZBT source code.

• SciFi-XZBT is an external exhibit implementation, not the NGN architecture.