diff --git a/AGENTS.md b/AGENTS.md
index 108093fe..ba2cfaa4 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,5 +1,61 @@
 # Development Rules
 
+## Build & Test
+- `npm run build` - Build (tsup, ESM)
+- `npm run test` - Unit/integration tests (Vitest)
+- `npm run test:smoke` - Smoke tests (builds first, serial execution)
+- `npm run lint` / `npm run lint:fix` - ESLint
+- `npm run format` - Prettier
+- `npm run typecheck` - TypeScript type checking (`tsc --noEmit`)
+- `npm run docs:update` - Regenerate `docs/TOOLS.md` from manifests
+- `npm run docs:check` - Validate docs match CLI surface
+
+## Architecture
+ESM TypeScript project (`type: module`). Key layers:
+
+- `src/cli/` - CLI entrypoint, yargs wiring, daemon routing
+- `src/server/` - MCP stdio server, lifecycle, workflow/resource registration
+- `src/runtime/` - Config bootstrap, session state, tool catalog assembly
+- `src/core/manifest/` - YAML manifest loading, validation, tool module imports
+- `src/mcp/tools/` - Tool implementations grouped by workflow (mirrors `manifests/workflows/`)
+- `src/mcp/resources/` - MCP resource implementations
+- `src/integrations/` - External integrations (Xcode mcpbridge proxy)
+- `src/utils/` - Shared helpers (execution, logging, validation, responses)
+- `src/visibility/` - Tool/workflow exposure predicates
+- `src/daemon/` - Background daemon for persistent sessions
+- `src/types/` - Shared type definitions
+
+See `docs/` for detailed documentation (architecture, configuration, tools, troubleshooting).
+
+## Developer Documentation
+- `docs/dev/CONTRIBUTING.md` - Full contributing guide (setup, debugging, PR submission)
+- `docs/dev/ARCHITECTURE.md` - Detailed architectural overview and component design
+- `docs/dev/TESTING.md` - Testing guidelines, dependency injection patterns, coverage standards
+- `docs/dev/MANIFEST_FORMAT.md` - YAML manifest schema reference for tools and workflows
+- `docs/dev/MANUAL_TESTING.md` - Manual testing procedures
+- `docs/dev/RELEASE_PROCESS.md` - Release workflow
+- `docs/dev/CODE_QUALITY.md` - Code quality standards and ESLint rules
+
+## Contributing Workflow
+1. Create a branch from `main`
+2. Make changes following the conventions in this file
+3. Run the pre-commit checklist before committing:
+   ```bash
+   npm run lint:fix
+   npm run typecheck
+   npm run format
+   npm run build
+   npm run docs:check
+   npm test
+   ```
+4. Update `CHANGELOG.md` under `## [Unreleased]`
+5. Update documentation if adding or modifying features
+6. Clone and test against example projects (e.g., `XcodeBuildMCP-iOS-Template`) when changes affect runtime behavior
+7. Push and create a pull request with a clear description
+8. Link any related issues
+
+For full setup, debugging with Reloaderoo, and plugin development details, see `docs/dev/CONTRIBUTING.md`.
+
 ## Code Quality
 - No `any` types unless absolutely necessary
 - Check node_modules for external API type definitions instead of guessing
@@ -8,19 +64,38 @@
 - Always ask before removing functionality or code that appears to be intentional
 - Follow TypeScript best practices
 
+## Import Conventions
+- ESM with explicit `.ts` extensions in `src/` (tsup rewrites to `.js` at build)
+- No `.js` imports in `src/` (enforced by ESLint)
+- No barrel imports from `utils/index` - import from specific submodules (e.g., `src/utils/execution/index.ts`, `src/utils/logging/index.ts`)
+
+## Test Conventions
+- Vitest with colocated `__tests__/` directories using `*.test.ts`
+- Smoke tests in `src/smoke-tests/__tests__/` (separate Vitest config, serial execution)
+- Use `vi.mock`/`vi.hoisted` for isolation; inject executors and mock file systems
+- MCP integration tests use `McpServer`, `InMemoryTransport`, and `Client`
+- External dependencies (command execution, file system) must use dependency injection via `createMockExecutor()` / `createMockFileSystemExecutor()`
+- See `docs/dev/TESTING.md` for full testing guidelines
+
+## Tool Development
+- Tool manifests in `manifests/tools/*.yaml` define `id`, `module`, `names.mcp` (snake_case), optional `names.cli` (kebab-case), predicates, and annotations
+- Workflow manifests in `manifests/workflows/*.yaml` group tools and define exposure rules
+- Tool modules export a Zod schema, a pure `*Logic` function, and a `handler` via `createTypedTool` or `createSessionAwareTool`
+- Resources export `{ uri, name, description, mimeType, handler }`
+
 ## Commands
 - NEVER commit unless user asks
 
 ## GitHub
 When reading issues:
 - Always read all comments on the issue
--
+
 ## Tools
 - GitHub CLI for issues/PRs
 - CLI design note: do not rely on CLI session-default writes. CLI is intentionally deterministic for CI/scripting and should use explicit command arguments as the primary input surface.
 - When working on skill sources in `skills/`, use the `skill-creator` skill workflow.
 - After modifying any skill source, run `npx skill-check <skill-directory>` and address all errors/warnings before handoff.
--
+
 ## Style
 - Keep answers short and concise
 - No emojis in commits, issues, PR comments, or code
@@ -29,7 +104,7 @@ When reading issues:
 
 ## Docs
 - If modifying or adding/removing tools run `npm run docs:update` to update the TOOLS.md file, never edit this file directly.
--
+
 ### Changelog
 Location: `CHANGELOG.md`
 
@@ -39,17 +114,17 @@ Use these sections under `## [Unreleased]`:
 - `### Changed` - Changes to existing functionality
 - `### Fixed` - Bug fixes
 - `### Removed` - Removed features
--
+
 #### Rules
 - Before adding entries, read the full `[Unreleased]` section to see which subsections already exist
 - New entries ALWAYS go under `## [Unreleased]` section
 - Append to existing subsections (e.g., `### Fixed`), do not create duplicates
 - NEVER modify already-released version sections (e.g., `## [0.12.2]`)
 - Each version section is immutable once released
--
+
 #### Attribution
-- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/cameroncook/XcodeBuildMCP/issues/123))`
-- **External contributions**: `Added feature X ([#456](https://github.com/cameroncook/XcodeBuildMCP/pull/456) by [@username](https://github.com/username))`
+- **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/getsentry/XcodeBuildMCP/issues/123))`
+- **External contributions**: `Added feature X ([#456](https://github.com/getsentry/XcodeBuildMCP/pull/456) by [@username](https://github.com/username))`
 
 ## **CRITICAL** Tool Usage Rules **CRITICAL**
 - NEVER use sed/cat to read a file or a range of a file. Always use the native read tool.