WebTools/AGENTS.md

Web Tools Agent Guide

Before changing this project, read README.zh-CN.md in full. Its architecture constraints, extension procedure, validation checklist, and release steps are authoritative.

Project identity

• This is a self-hosted Vue 3 + TypeScript browser-local tools application with a zero-dependency Node.js static/configuration server.
• package.json is the authoritative application version. The default production port is 9000.
• shared/tool-catalog.json is the authoritative tool catalog; shared/default-navigation.json defines first-run ordering.
• README.zh-CN.md is the complete product, architecture, deployment, extension, and AI handoff document. README.md is only the universal entry point.
• Windows Server uses web-tools.ps1; containers use Dockerfile and docker-compose.yml.

First actions in a new session

1. Read README.zh-CN.md, then inspect git status --short --branch and preserve all existing worktree changes.
2. Read the closest existing tool, its src/lib/ logic, and related tests before adding or changing behavior.
3. Keep default production port references synchronized in server/index.mjs, web-tools.ps1, Dockerfile, docker-compose.yml, .env.example, and deployment documentation.
4. Run npm run check; for deployment changes also validate PowerShell syntax and Docker Compose configuration when those tools are available.

Key rules:

• Preserve the anonymous, no-login, no-database design. Tool calculations are isolated in each browser tab; only navigation order is shared globally.
• Never send tool input, keys, text, or images to the server or a third party.
• Keep each tool independently lazy-loaded through src/tools/registry.ts.
• Put testable computation in src/lib/ and cover it in tests/.
• Preserve the documented file, record, image, random-output, syntax-rendering, and request-size limits. Update the limits table and tests when any limit changes.
• Preserve the firmware Hash byte stream contract: sorted effective blocks without gap filling, or an 8-byte binary uint32 address/length header per block; lengths exclude headers and Big Endian is the default.
• Treat every Intel HEX address and length operation as checked uint32 arithmetic. Reject overflow, conflicting overlap, malformed control records, excessive records and excessive blocks before allocating result buffers.
• Treat asynchronous replacement and clearing as race-sensitive: stale Worker, file, image, or key-generation results must never replace current state.
• Keep IDs synchronized across shared/tool-catalog.json, shared/default-navigation.json, and src/tools/registry.ts.
• Use the shared UI components and existing responsive styles.
• Do not edit generated dist/ directly; rebuild it from source.
• Do not overwrite or delete data/navigation.json.
• Run npm run check after every change. Run npm audit --audit-level=low before a release.
• For UI changes, verify desktop and mobile portrait layouts in a real browser.
• A release must update all version references and CHANGELOG.md, rebuild the delivery ZIP, and regenerate SHA-256.