# AGENTS.md

## Project scope

VG-Environment is a local evidence and runtime observation environment for technically reconstructing consent-related browser activity.

The project is focused on:
- runtime observation
- consent-state capture
- request observation
- GVL/version tracking
- evidence preservation
- technically reproducible reconstruction

The project is NOT focused on:
- AI-generated interpretations
- speculative conclusions
- marketing-style analytics
- legal automation
- risk scoring
- black-box analysis

Observe shows:
"What was technically observed?"

Analysis answers:
"What could this mean?"

These responsibilities must remain separated.

---

## Development principles

- Runtime stability is more important than feature count.
- Small incremental changes are preferred over large refactors.
- Avoid monster files.
- Avoid architecture expansion without concrete user value.
- Human-understandable evidence visibility is more important than technical complexity.
- Existing runtime/evidence data should be used before adding new capture pipelines.
- Do not turn Observe into a hidden analysis engine.

---

## Database rules

- IndexedDB migrations must remain additive.
- No destructive schema operations without explicit approval.
- No DROP/TRUNCATE-style logic.
- No automatic cleanup of evidence data.
- Avoid DB full scans whenever possible.
- Evidence data must not be silently modified.

---

## Git and workflow rules

- Git control remains with the user.
- Do not automate git operations.
- Do not create commits automatically.
- Do not rewrite git history.
- Workspaces are intentional architectural boundaries.
- Respect module and workspace responsibilities.

---

## Node.js / npm policy

Node.js and npm are allowed only as local development and testing tools.

Allowed examples:
- web-ext
- eslint
- prettier
- local syntax checks
- local test scripts
- development automation

Strict rules:
- Do not add npm runtime dependencies.
- Do not import npm packages from src/.
- Do not introduce bundlers unless explicitly requested.
- Do not require a build step for the extension.
- Do not commit node_modules/.
- package.json is allowed only for devDependencies and local scripts.
- Productive extension code must remain Vanilla JavaScript using WebExtension APIs.
- The extension must run in Firefox without Node.js installed.

Node.js may assist development tooling.
It must never become part of the productive runtime architecture.