Skip to content

Commit 4ade852

Browse files
committed
docs: Improve QUICK_START for active developers
Key improvements: - Added prominent 'Developer Workflow' section right after setup - Shows hot-reload commands (make local-reload-*) early in guide - Emphasizes ~30 second reload time vs full restart - Removed all emojis for cleaner professional appearance The hot-reload workflow is the most important daily operation for developers testing changes, so it should be front and center rather than buried in a command reference section. Addresses feedback that developers need to quickly find commands for testing changes without restarting everything.
1 parent ccbf902 commit 4ade852

File tree

1 file changed

+45
-22
lines changed

1 file changed

+45
-22
lines changed

QUICK_START.md

Lines changed: 45 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Quick Start Guide
22

3-
Get vTeam running locally in **under 5 minutes**! 🚀
3+
Get Ambient Code Platform running locally in **under 5 minutes**!
44

55
## Prerequisites
66

@@ -130,16 +130,39 @@ make local-up
130130
```
131131

132132
That's it! The command will:
133-
- Start minikube (if not running)
134-
- Build all container images
135-
- **Auto-detect Vertex AI** from environment variables
136-
- Deploy backend, frontend, and operator
137-
- Set up ingress and networking
138-
- **On macOS**: Automatically start port forwarding in background
133+
- Start minikube (if not running)
134+
- Build all container images
135+
- **Auto-detect Vertex AI** from environment variables
136+
- Deploy backend, frontend, and operator
137+
- Set up ingress and networking
138+
- **On macOS**: Automatically start port forwarding in background
139139

140140
**What you'll see:**
141-
- ✅ "Found Vertex AI config in environment" → Using company Vertex AI
142-
- ⚠️ "Vertex AI not configured" → Using direct Anthropic API (workspace settings)
141+
- "Found Vertex AI config in environment" → Using company Vertex AI
142+
- "Vertex AI not configured" → Using direct Anthropic API (workspace settings)
143+
144+
## Developer Workflow
145+
146+
**Made a code change?** Reload just that component (takes ~30 seconds, keeps everything else running):
147+
148+
```bash
149+
# After changing backend code
150+
make local-reload-backend
151+
152+
# After changing frontend code
153+
make local-reload-frontend
154+
155+
# After changing operator code
156+
make local-reload-operator
157+
```
158+
159+
**These commands automatically:**
160+
- Rebuild only the changed component
161+
- Load the new image into minikube
162+
- Restart only that deployment
163+
- On macOS: Restart port forwarding for that component
164+
165+
**No need to restart everything!** Your other components keep running.
143166

144167
## Access the Application
145168

@@ -190,20 +213,20 @@ make local-status
190213
./tests/local-dev-test.sh
191214
```
192215

193-
## Quick Commands
216+
## Quick Commands Reference
194217

195218
```bash
219+
# Component reload (see "Developer Workflow" above for details)
220+
make local-reload-backend # Rebuild and reload backend only
221+
make local-reload-frontend # Rebuild and reload frontend only
222+
make local-reload-operator # Rebuild and reload operator only
223+
196224
# View logs
197225
make local-logs # All component logs
198226
make local-logs-backend # Backend logs only
199227
make local-logs-frontend # Frontend logs only
200228
make local-logs-operator # Operator logs only
201229

202-
# Rebuild and reload a component
203-
make local-reload-backend # After changing backend code
204-
make local-reload-frontend # After changing frontend code
205-
make local-reload-operator # After changing operator code
206-
207230
# Port forwarding management (macOS)
208231
make local-stop-port-forward # Stop background port forwarding
209232
make local-port-forward # Restart port forwarding (foreground)
@@ -374,7 +397,7 @@ By default, authentication is **disabled** for local development:
374397
- Automatic user: "developer"
375398
- Full access to all features
376399

377-
⚠️ **Security Note**: This is for local development only. Production deployments require proper OAuth.
400+
**Security Note**: This is for local development only. Production deployments require proper OAuth.
378401

379402
### Environment Variables
380403
Local development uses these environment variables:
@@ -388,14 +411,14 @@ These are set automatically in `components/manifests/minikube/` deployment files
388411
### AI Access Configuration
389412

390413
**Vertex AI** (Recommended for company work):
391-
- Set via environment variables (see setup above)
392-
- Automatically detected by `make local-up`
393-
- Company-issued service accounts
394-
- Approved for confidential/proprietary code
414+
- Set via environment variables (see setup above)
415+
- Automatically detected by `make local-up`
416+
- Company-issued service accounts
417+
- Approved for confidential/proprietary code
395418
- See [README.md](README.md) for advanced configuration
396419

397420
**Direct Anthropic API** (Non-confidential data only):
398-
- ⚠️ Only for public repos or non-sensitive work
421+
- Only for public repos or non-sensitive work
399422
- No environment variables needed
400423
- Provide `ANTHROPIC_API_KEY` in workspace settings when creating a project
401424
- Platform automatically uses this mode if Vertex AI env vars not set
@@ -435,5 +458,5 @@ These are set automatically in `components/manifests/minikube/` deployment files
435458

436459
**Want to contribute?** See [CONTRIBUTING.md](CONTRIBUTING.md)
437460

438-
**Having issues?** Open an issue on [GitHub](https://github.com/ambient-code/vTeam/issues)
461+
**Having issues?** Open an issue on [GitHub](https://github.com/ambient-code/platform/issues)
439462

0 commit comments

Comments
 (0)