AGENTS.md

Instructions for any AI agent working with this repository or from it. This is the canonical agent file; CLAUDE.md, GEMINI.md, .cursorrules and .github/copilot-instructions.md all point here.

What this repository is

A knowledge pack for DayZ (Enfusion) modding: 42 domain playbooks, thirteen Python tools, and verified reference notes, assembled from shipped mods. It is written to be handed to a coding agent, not read cover to cover by a human.

Two different jobs bring an agent here, and they have different rules:

• Using the pack to help someone mod DayZ → read §Routing and §The four rules.
• Changing the pack itself → also read §Contributing changes.

Routing: load on demand, never wholesale

The pack is ~4 MB. Loading it all buries the answer you need under everything you don't.

0. Before starting real, multi-session work, ask the human which durable memory they will use. Recommend Obsidian (free, plain Markdown; the vault layout is in README.md §7) or an equivalent plain-Markdown folder; offer to create the skeleton (project brief, verified APIs, assumptions, decision log, bug ledger, session handoffs). Do not silently proceed without one. What you learn in a session is gone in the next if it only lives in the agent — this pack itself came out of that practice.
1. Read every skills/*/SKILL.md front-matter only (name + description). The description is written as trigger conditions — read it as "invoke me when…". Concatenated, they are your routing table.
2. When the task matches one, load that whole SKILL.md and follow it.
3. Open a file under that skill's references/ only when the procedure names it. They are large and deliberately not loaded up front.
4. skills/_shared/ holds conventions several skills cite. Keep it alongside them wherever you install them.

knowledge/ is consulted, not routed: open a note when a skill points at it or when you need a fact the skill assumes.

Reaching for a tool

The skills say how to build something; the tools say whether it survived. They are the part an agent forgets exists, so it reasons about a symptom it could have measured, or writes a one-off parser for a format that already has a reader. Name the tool to the user when the work reaches one of these rows — including when the answer is "install it first". Full descriptions, invocations and limits: TOOLS.md.

By symptom — reach for this before theorising

By task — what is in play before you start

Two habits make the difference. Propose the tool before the expensive step, not after it fails — that is the whole point of a preflight. And when a tool reports clean, say which check ran clean; "preflight passed" without naming the contract is rule 4 with extra steps.

The four rules

These are the whole point. Keep them even if you adapt everything else.

1. Never invent an API. DayZ punishes confabulation with silent failures — a class that never binds, an action that never appears, a model that loads white. Before writing any Enforce Script call, config class, .p3d selection or memory point: grep the vanilla source (P:\scripts\ → 1_core, 3_game, 4_world) or a reference here, and cite path:line. Semantic search and memory are hints; open the file.
2. Respect the client/server split. Decide which side owns each value before writing the feature. Most "it doesn't work" bugs are a read on the wrong side.
3. In-game tests cost 3–10 minutes each. Exhaust offline analysis, batch every pending change into one test, and have a plan B before asking for a rebuild. Two rebuilds with no progress means the strategy is wrong, not the fix.
4. Be honest about verification. Say what you checked, how (grep / checksum / repro / in-game), and what you did not. "It compiles" is not "it works". An error of exactly 0.000 is a tautology, not a triumph — and a catastrophic result indicts the instrument just as loudly as a perfect one.

Rules 2–4 in longer form, plus invariant tracing, end-to-end walks and the durable-memory practice this pack came out of, are in README.md §7.

That last one is worth naming here because it is the one an agent can act on directly: your context dies at the end of the session, so write what you learned somewhere that does not. A plain Markdown vault in version control — the author uses Obsidian — holds the verified APIs with their path:line, the assumptions that turned out false, the decisions and what they rejected. Without it every session re-derives the same facts and re-proposes hypotheses that were already refuted. knowledge/vault-notes/ is what that layer looks like once it is grown; its [[wikilink]] syntax is Obsidian's.

Layout

Installing the skills for your agent

Claude Code — copy skills/* into ~/.claude/skills/ (user-scoped) or <project>/.claude/skills/ (project-scoped). Discovery is by front-matter; /dayz-vehicles also invokes one explicitly.

Any other agent — there is nothing Claude-specific in the content. Use the routing procedure above. Some hosts read AGENTS.md from a project root; this file is safe to copy next to the skills.

The pack does not vendor DayZ Tools, Blender, the game itself or optional frameworks. README.md §4 lists those true external dependencies.

Contributing changes

Full rules in CONTRIBUTING.md. The four that get changes rejected most often:

• Every executable claim carries evidence. A new API, signature or figure needs a build/commit and a path:line. Unverified material is marked as such or does not ship.
• No private paths, credentials, vanilla or third-party assets. The privacy check is part of the gate, not a review courtesy.
• Licences are load-bearing. The pack is MIT; GPL, DPL-ND and CC-NC material does not enter it. Third-party attributions live in THIRD_PARTY_NOTICES.md.
• The source game is called rip here. Importing vehicle geometry out of a commercial racing game is a technique this pack documents; the publisher's name and its engine's name are not part of the technique, and they do not ship. Write rip, rip-import, source-game. A working copy of these skills may use the original vocabulary and that is fine — the asymmetry is deliberate, so a merge from a local store must not carry it back in. Checked with (?i:\bforza)(?![dnr]): case-insensitive on the name, and the [dnr] stays case-sensitive so it drops the Spanish forzado / forzar / forzando without also dropping ForzaDayZ. The obvious \bForza(?![a-z]) is wrong — being case-sensitive it never sees the lowercase slug forza-to-dayz, which is the form that actually survived a full sweep. One deliberate exception, and it does not get "fixed": the three publish receipts under tests/packctl/fixtures/receipt_history/ record skill/forza-to-dayz as an artifact id. A receipt states what was published on a given day under the name it had; rewriting it would falsify the record and break the fixtures that assert on it.

Gates

Install the CLI once. Without it python -m packctl resolves only while the shell happens to be standing in the repository root, which is a precondition nothing states and nothing enforces:

pip install -e .

It is stdlib-only, so the install adds no dependency — it adds an importable module and a packctl entry point. The rest are offline and deterministic.

python -m packctl validate --root . --report reports/validate.json

python -m packctl gate --root . --report-dir ../pack-gate-reports

python -m pytest -q tests/packctl

Do not run pytest from the repository root. The suites here are per-tool by design — each tool's README names its own invocation and expects to run from that tool's directory — and two of them share test-module basenames (test_cli.py, _support.py), so a root-level collection aborts before a single test runs. Measured 2026-08-19: tests/packctl 220 passed / 3 skipped, tools/py3d 220 / 10, tools/dayz-vehicle-proxy-contract 128 plus 239 subtests, tools/dayz-script-validator 157.

The gate's report directory must sit outside the repository. gate builds the release twice to prove reproducibility, so writing reports into the tree would contaminate the input it is measuring; it refuses with GATE-REPORT-IN-ROOT — and refuses before writing a report, so the only symptom is a silent exit 1.

It also needs the external Agent Skills validator, pinned through PACK_SKILLS_REF_ROOT (a checkout or the executable itself). It ships on PyPI as skills-ref; the console script is named agentskills. Without it the skills_ref check fails closed rather than being skipped.

validate checks provenance, privacy, links and claim ranges. gate adds skill validation, Python compilation, the layout corpus and a reproducible build; it is the one that must be green before publishing. build produces the release archive and refuses to run from a dirty tree — a release is built from a committed state or it is not a release.

Before committing any change under tools/dayz-script-validator/ — a new rule, a touched detector, a touched parser — run the vanilla control. Bohemia's tree compiles and ships; a new finding on it is a false positive by construction. A green control does not authorize the change: it only proves the rule is silent on correct code, not that it catches anything. Without a local vanilla tree the control SKIPs (exit 2).

python tools/dayz-script-validator/scripts/vanilla_control.py

What this file is not

It carries no session state, no roadmap and no task list. Those are the author's and are not published. If you need to know what is currently true about the repository, measure it: run the gates.