docs: add AGENTS.md for agent orientation and package details

[daithihearn]

Introduce AGENTS.md to provide a comprehensive guide for agents interacting with the VeChain dev-stack. The document outlines the package's purpose, repository layout, public API, conventions, testing procedures, and common surprises, ensuring agents have the necessary context before making changes.

[Copilot]

Pull request overview

Adds an AGENTS.md orientation guide intended to give coding agents (and contributors) the repository context needed to make safe changes to @vechain/dev-stack, including architecture, public API contracts, conventions, and operational workflow.

Changes:

• Introduces AGENTS.md describing the stack’s purpose, shared vs per-project state, and repo layout.
• Documents the public surface area (registerAddresses + vechain-dev CLI) and key invariants/conventions.
• Adds notes on testing and common “gotchas” for day-to-day development.

Comments suppressed due to low confidence (3)

AGENTS.md:41

• This claims genesis/solo.default.json is used by both thor-solo and the indexer, but compose/base.yaml doesn’t mount or reference VECHAIN_DEV_GENESIS for thor-solo (only the indexer compose uses it). Update the wording to avoid implying thor-solo is pinned to this genesis file, or document how to configure thor-solo to use it if that’s intended.

compose/                   base.yaml, indexer.yaml, explorer.yaml (Compose files)
genesis/solo.default.json  Default genesis used by thor-solo + indexer

**AGENTS.md:48**
* `registerAddresses(...)` is documented here as writing to `~/.vechain-dev/config/<project>.json`, which matches `lib/register.mjs`, but `lib/register.d.ts` currently says it writes to `~/.vechain-dev/addresses/<project>.json`. Please align the docs (prefer updating `lib/register.d.ts`) so consumers don’t get conflicting information.

Two things consumers depend on. Any change here is a breaking change for every downstream project.

1. registerAddresses({ project, profiles, addresses }) — exported from package main. Signature defined in lib/register.d.ts. Validates and atomically writes ~/.vechain-dev/config/<project>.json.
2. vechain-dev CLI — commands up, down, reset, sync, status. The up flow is load-config → ensure network → start thor+mongo → run consumer deploy → merge address book → recreate indexer+explorer → exec consumer dev (the dev process becomes the foreground; signals are forwarded).

**AGENTS.md:61**
* This states images are pinned via env var with a default tag in each compose file, but `compose/base.yaml` hardcodes `ghcr.io/vechain/thor:latest` (not pinned and not env-var overridable). Either adjust the statement to exclude thor-solo or update the compose file to follow the documented pinning pattern.

• Spring profile names live in consumer projects. When adding a new profile-keyed start-block env var to the indexer, append it to SOLO_START_BLOCKS in lib/addressBook.mjs so its cursor defaults to 0 for solo.
• Container/service names are stable identifiers (thor-solo, mongo-node1, vechain-indexer, vechain-indexer-api, block-explorer). The CLI references them by name; don't rename without updating every callsite.
• Images are pinned via env var with a default tag in each compose file (e.g. ${VECHAIN_DEV_INDEXER_IMAGE:-ghcr.io/vechain/vechain-indexer/indexer:6.28}). Bump the default tag when intentionally upgrading.

</details>



---

💡 <a href="/vechain/dev-stack/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 2 comments.