docs - when to modify package-lock.json (#510)

CONTRIBUTING.md

@@ -31,9 +31,11 @@ When proposing solutions or reviewing code, we reference these principles to gui
    ```bash
    git clone https://github.com/strands-agents/sdk-typescript.git
    cd sdk-typescript
-   npm install
+   npm ci
    ```
 
+   > **Note**: Use `npm ci` for installing dependencies. Use `npm install` only when intentionally adding or updating dependencies. See [Dependency Guidelines](docs/DEPENDENCIES.md) for details.
+
 2. Install Playwright browsers for browser testing:
 
    ```bash

docs/DEPENDENCIES.md

@@ -31,3 +31,25 @@ const agent = new Agent({ model, tools: [calculator] })
 ```
 
 Mark peer dependencies as **optional** when not all users need them (e.g., model provider SDKs). Optional peer dependencies must also be added to `devDependencies` for SDK development and testing.
+
+## Package Lock File
+
+The `package-lock.json` file ensures reproducible builds by locking exact dependency versions.
+
+| Command | When to Use |
+|---------|-------------|
+| `npm ci` | Installing dependencies without changes (fresh clone, after pulling, CI pipelines) |
+| `npm install` | Adding, removing, or updating dependencies |
+
+`npm ci` installs exactly what's in the lock file without modifying it, failing if there's a mismatch. This prevents accidental lock file changes.
+
+**When to modify:**
+
+- Adding, removing, or updating dependencies in `package.json`
+- Running `npm audit fix` to patch security vulnerabilities
+
+**Rules:**
+
+1. Never manually edit `package-lock.json` - always use `npm install` or `npm update`
+2. Commit `package-lock.json` changes in the same commit as the corresponding `package.json` changes
+3. If `package-lock.json` has merge conflicts, delete it and run `npm install` to regenerate