From 4802828bdbb4eb0f9f4082cb2a5250b05810a272 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 16 Jan 2026 21:04:10 +0000
Subject: [PATCH] Document setup.ts script in agent instructions

Co-authored-by: toolate28 <105518313+toolate28@users.noreply.github.com>
---
 docs/instructions.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/instructions.md b/docs/instructions.md
index f852e25..c79e6e0 100644
--- a/docs/instructions.md
+++ b/docs/instructions.md
@@ -9,6 +9,32 @@ Emergent quality is maintained at >60% via isomorphic Fibonacci patterns:
 
 ## Agent Setup
 
+### Automated Setup Script
+
+The repository includes an automated setup script (`scripts/setup.ts`) that streamlines onboarding for new users and agents. This script automatically configures the development environment, installs dependencies, and sets up the ATOM provenance trail.
+
+**Usage**:
+```bash
+# Run full setup (recommended for first-time setup)
+bun run scripts/setup.ts
+
+# Check environment without making changes
+bun run scripts/setup.ts --check
+
+# Force reinstall dependencies
+bun run scripts/setup.ts --force
+```
+
+**What the setup script does**:
+- Verifies Bun installation (requires v1.0.0+)
+- Installs or updates project dependencies
+- Creates ATOM trail directories for provenance tracking
+- Validates TypeScript configuration
+- Runs test suite to verify setup
+- Records setup in ATOM trail for provenance
+
+### Manual Setup
+
 1. **Install Dependencies**:
    ```bash
    # Clone repo and install