Audit and Slim Down a Bloated AGENTS.md

Problem/Feature Description

The Vaultly engineering team has maintained an AGENTS.md file at the root of their Node.js monorepo for over a year. It started as a useful reference but grew as contributors kept adding entries without ever removing old ones. The file now has a reputation for being more noise than signal — new team members read it, can't tell what matters, and end up ignoring it entirely.

A senior engineer did a quick review and feels the file needs a serious trim — too much of it isn't pulling its weight. At the same time, she knows there are a few real gotchas buried in there that have burned people before and must be preserved.

Your job is to audit the existing AGENTS.md and produce a leaner version. Think carefully about which lines genuinely belong in a file like this and which do not.

Output Specification

Produce a revised AGENTS.md at the root of the workspace. The revised file should be noticeably shorter than the original and contain only high-signal entries. Do not create any other output files.

Input Files

The following files are provided as inputs. Extract them before beginning.

=============== FILE: AGENTS.md ===============

AGENTS.md — Vaultly Repo

This file provides guidance to AI agents working in this repository.

About this project

Vaultly is a Node.js/TypeScript monorepo built with pnpm workspaces. The backend uses Fastify for HTTP routing, PostgreSQL for persistence (via Drizzle ORM), and Redis for caching. The frontend is a React SPA. Testing uses Vitest for unit tests and Playwright for end-to-end tests.

Repository layout

apps/
  api/       # Fastify backend
  web/       # React frontend
packages/
  db/        # Drizzle schema and migrations
  shared/    # Shared utilities

General coding principles

• Write clear, descriptive commit messages
• Follow the DRY principle — do not repeat yourself
• Keep functions small and focused on a single responsibility
• Prefer readability over cleverness
• Always handle errors explicitly

JavaScript style

• Do not use var — use const or let (enforced by ESLint)
• Use async/await over raw promise chains (enforced by ESLint)
• Destructure function parameters where it improves clarity

Architecture overview

Requests come in through the Fastify API layer, pass through validation middleware, hit service classes that coordinate DB and cache access, and return structured responses. The frontend calls the REST API using React Query for data fetching.

Critical workflow notes

• Always use pnpm instead of npm or yarn for any package install or script commands — the repo uses pnpm workspaces and mixing package managers corrupts the lockfile
• Do NOT run npm test directly without first setting NODE_ENV=test. The migration runner reads this env var to choose which DB to target; without it, it defaults to the dev database and will wipe it on each test run
• When running integration tests, always pass the --forceExit flag (e.g. pnpm test:integration --forceExit) — Fastify's keep-alive connections prevent the process from exiting cleanly and the test suite hangs indefinitely

Security reminders

• Validate all user input
• Never log sensitive data like passwords or tokens
• Keep dependencies up to date

Deployment

The deploy pipeline is documented in docs/deployment.md. Follow that document when releasing. =============== END FILE ===============