antigravity-ai-kit 3.2.0 → 3.3.1

package/.agent/skills/plan-writing/domain-enhancers.md

@@ -12,11 +12,14 @@
 
 Include in plan:
 
-- **Accessibility (WCAG 2.1 AA)**: Identify components requiring ARIA labels, keyboard navigation, screen reader support, color contrast compliance
-- **Responsive Design**: Specify breakpoints to test (mobile 375px, tablet 768px, desktop 1280px), identify layout changes per breakpoint
-- **Bundle Size Impact**: Estimate size of new dependencies, identify tree-shaking opportunities, consider code splitting for new routes
-- **Core Web Vitals**: Assess impact on LCP (largest contentful paint), CLS (cumulative layout shift), INP (interaction to next paint)
-- **Component Composition**: Specify component hierarchy, prop interfaces, state management approach (local vs. global)
+- **Accessibility (WCAG 2.1 AA)**: Identify components requiring ARIA labels, keyboard navigation, screen reader support, color contrast compliance (minimum 4.5:1 normal text, 3:1 large text)
+- **Responsive Design**: Specify breakpoints to test (mobile 375px, tablet 768px, desktop 1280px), identify layout changes per breakpoint, verify touch targets (minimum 44x44px)
+- **Bundle Size Impact**: Estimate size of new dependencies, identify tree-shaking opportunities, consider code splitting for new routes, set bundle budget (initial JS < 200KB gzipped)
+- **Core Web Vitals**: Assess impact on LCP (< 2.5s), CLS (< 0.1), INP (< 200ms), identify render-blocking resources
+- **Component Composition**: Specify component hierarchy, prop interfaces, state management approach (local vs. global), identify shared components for extraction
+- **Rendering Strategy**: SSR vs CSR vs ISR decision for each route, hydration impact assessment, streaming SSR opportunities
+- **Design System Compliance**: Verify alignment with existing design tokens (colors, spacing, typography), identify new tokens required
+- **Error Boundaries**: Define error boundary placement, fallback UI for each failure mode, error reporting integration
 
 ---
 
@@ -26,11 +29,14 @@ Include in plan:
 
 Include in plan:
 
-- **API Contract**: Define request/response schemas (Zod validation), HTTP methods, status codes, error response format
-- **Error Handling**: Specify error response structure, error codes, client-facing messages vs. internal logging
-- **Rate Limiting**: Identify endpoints requiring rate limits, specify limits (requests/minute/user), throttling strategy
-- **Middleware Chain**: Document new middleware additions, execution order, impact on existing middleware stack
-- **Database Interaction**: Query patterns (parameterized), transaction boundaries, connection pooling impact
+- **API Contract**: Define request/response schemas (Zod validation), HTTP methods, status codes, error response format (RFC 7807 Problem Details), versioning strategy
+- **Error Handling**: Specify error response structure, error codes, client-facing messages vs. internal logging, error correlation IDs for tracing
+- **Rate Limiting**: Identify endpoints requiring rate limits, specify limits (requests/minute/user), throttling strategy (sliding window vs. token bucket), response headers (X-RateLimit-*)
+- **Middleware Chain**: Document new middleware additions, execution order, impact on existing middleware stack, short-circuit conditions
+- **Database Interaction**: Query patterns (parameterized), transaction boundaries, connection pooling impact, N+1 query prevention
+- **Input Validation**: Validation layer placement (controller vs. middleware), sanitization strategy, content-type enforcement, request size limits
+- **Idempotency**: Identify non-idempotent operations, implement idempotency keys for critical mutations, retry safety assessment
+- **Observability**: Structured logging format (JSON), request tracing headers (X-Request-ID propagation), health check endpoint specification
 
 ---
 
@@ -40,11 +46,14 @@ Include in plan:
 
 Include in plan:
 
-- **Migration Rollback**: Write both up and down migrations, test rollback procedure before deploying
-- **Index Impact Analysis**: Identify queries affected by schema changes, recommend index additions/removals, estimate query performance impact
-- **Data Integrity**: Define constraints (foreign keys, unique, not null, check), cascade behavior for deletions
-- **Backup Verification**: Verify backup exists before destructive migrations, test restore procedure for critical tables
-- **Query Performance**: Benchmark key queries before and after changes, set acceptable latency thresholds
+- **Migration Rollback**: Write both up and down migrations, test rollback procedure before deploying, zero-downtime migration pattern (expand-contract for schema changes)
+- **Index Impact Analysis**: Identify queries affected by schema changes, recommend index additions/removals, estimate query performance impact, verify composite index column order matches query patterns
+- **Data Integrity**: Define constraints (foreign keys, unique, not null, check), cascade behavior for deletions, domain invariant enforcement at database level
+- **Backup Verification**: Verify backup exists before destructive migrations, test restore procedure for critical tables, point-in-time recovery validation
+- **Query Performance**: Benchmark key queries before and after changes (EXPLAIN ANALYZE), set acceptable latency thresholds (p50 < 10ms, p99 < 100ms for OLTP), identify sequential scan risks
+- **Consistency Model**: Specify required consistency level (strong/eventual), transaction isolation level selection (Read Committed default, Serializable for financial), optimistic vs. pessimistic locking strategy
+- **Data Classification**: Identify PII columns requiring encryption at rest, data retention policy compliance, audit trail requirements for sensitive data mutations
+- **Connection Management**: Connection pool sizing for workload (pool_size = num_cores * 2 + disk_spindles), statement timeout configuration, idle connection cleanup
 
 ---
 
@@ -54,11 +63,14 @@ Include in plan:
 
 Include in plan:
 
-- **Infrastructure Changes**: Specify IaC modifications (Dockerfile, docker-compose, CI config), environment variable additions
-- **Monitoring & Alerting**: Define new metrics to track, alerting thresholds, dashboard updates
-- **Progressive Rollout**: Strategy for deployment (canary → staged → full), rollback triggers, health check endpoints
-- **Runbook Updates**: Document operational procedures for the new functionality, incident response steps
-- **Environment Parity**: Verify changes work across dev, staging, and production environments
+- **Infrastructure Changes**: Specify IaC modifications (Dockerfile, docker-compose, CI config), environment variable additions, 12-Factor App compliance check
+- **Monitoring & Alerting**: Define new metrics to track, alerting thresholds (SLO-derived), dashboard updates, golden signals coverage (latency, traffic, errors, saturation)
+- **Progressive Rollout**: Strategy for deployment (canary → staged → full), rollback triggers (error rate > 1%, latency p99 > 2x baseline), automated rollback criteria, health check endpoints
+- **Runbook Updates**: Document operational procedures for the new functionality, incident response steps, escalation paths
+- **Environment Parity**: Verify changes work across dev, staging, and production environments, configuration drift detection
+- **GitOps Compliance**: Infrastructure changes committed to version control, declarative configuration (desired state, not imperative scripts), automated drift reconciliation
+- **Container Security**: Base image selection (distroless/alpine preferred), multi-stage build optimization, no secrets in image layers, vulnerability scanning in CI
+- **Observability Pipeline**: Log aggregation configuration, trace sampling strategy, metric cardinality assessment, correlation between logs/traces/metrics
 
 ---
 
@@ -68,11 +80,14 @@ Include in plan:
 
 Include in plan (in addition to mandatory security considerations):
 
-- **Threat Model (STRIDE)**: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege — assess each for the change
-- **Authentication Flow Impact**: How the change affects login, session management, token lifecycle
-- **Data Classification**: Identify data sensitivity levels (public, internal, confidential, restricted), storage and transmission requirements
-- **Compliance Requirements**: GDPR/CCPA implications (data minimization, consent, right to erasure)
-- **Secret Management**: New secrets required, rotation policy, storage mechanism (environment variables only)
+- **Threat Model (STRIDE)**: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege — assess each for the change with severity rating
+- **Authentication Flow Impact**: How the change affects login, session management, token lifecycle, OAuth 2.0 flow selection (Authorization Code + PKCE for SPAs, Client Credentials for M2M)
+- **Data Classification**: Identify data sensitivity levels (public, internal, confidential, restricted), storage and transmission requirements per level
+- **Compliance Requirements**: GDPR/CCPA implications (data minimization, consent, right to erasure, breach notification within 72 hours)
+- **Secret Management**: New secrets required, rotation policy, storage mechanism (environment variables only), zero hardcoded credentials enforcement
+- **Zero Trust Assessment**: Authentication at every boundary (never trust, always verify), least privilege access for new endpoints/services, micro-segmentation for new network paths
+- **Supply Chain Security**: New dependency audit (license, maintainer, vulnerability scan), lockfile integrity verification, SRI hashes for CDN resources
+- **Input Boundary Defense**: All external inputs validated and sanitized, output encoding for context (HTML/URL/JS), parameterized queries only (no string concatenation)
 
 ---
 
@@ -82,11 +97,14 @@ Include in plan (in addition to mandatory security considerations):
 
 Include in plan:
 
-- **Performance Budget**: Define acceptable thresholds (page load time, API response time, memory usage)
-- **Profiling Strategy**: Tools and methods to measure before/after (Lighthouse, Chrome DevTools, load testing)
-- **Caching Strategy**: Cache layers (browser, CDN, application, database), TTL values, invalidation approach
-- **Lazy Loading**: Identify resources for deferred loading, intersection observer patterns, dynamic imports
-- **Benchmarking**: Define benchmark suite, baseline measurements, regression detection
+- **Performance Budget**: Define acceptable thresholds (LCP < 2.5s, FID < 100ms, page load < 3s, API p99 < 500ms, memory < 512MB per process)
+- **Profiling Strategy**: Tools and methods to measure before/after (Lighthouse, Chrome DevTools, load testing with k6/Artillery), baseline measurement requirements
+- **Caching Architecture**: Cache layers (browser → CDN → application → database), TTL values per layer, invalidation strategy (time-based, event-driven, version-key), cache stampede prevention (stale-while-revalidate, locking)
+- **Lazy Loading**: Identify resources for deferred loading, intersection observer patterns, dynamic imports for route-level code splitting, image loading strategy (responsive images, next-gen formats)
+- **Benchmarking**: Define benchmark suite, baseline measurements, regression detection thresholds, automated performance gates in CI
+- **Database Query Optimization**: EXPLAIN ANALYZE for new/modified queries, index coverage verification, N+1 detection, read replica routing for heavy reads
+- **Concurrency Model**: Event loop impact assessment, worker thread candidates for CPU-intensive operations, connection pool saturation risk
+- **CDN Strategy**: Edge caching rules for static assets, cache-control header specification, origin shield configuration, geographic distribution assessment
 
 ---
 
@@ -96,11 +114,61 @@ Include in plan:
 
 Include in plan:
 
-- **Platform Parity**: Identify iOS vs. Android differences in behavior, UI, or API access
-- **Offline Support**: Define offline behavior, data sync strategy, conflict resolution
-- **App Store Guidelines**: Compliance with Apple/Google review guidelines for the feature
-- **Native Modules**: Bridge requirements, native module dependencies, build configuration changes
-- **Device Testing**: Target device matrix, screen size variations, OS version compatibility
+- **Platform Parity**: Identify iOS vs. Android differences in behavior, UI, or API access, platform-specific code paths (#ifdef equivalent)
+- **Offline Support**: Define offline behavior, data sync strategy (optimistic vs. pessimistic), conflict resolution (last-write-wins, CRDT, manual merge), network-aware queries
+- **App Store Guidelines**: Compliance with Apple HIG and Material Design 3, review guideline risks, in-app purchase requirements
+- **Native Modules**: Bridge requirements, native module dependencies, build configuration changes (Podfile/build.gradle)
+- **Device Testing**: Target device matrix, screen size variations, OS version compatibility (minimum iOS 15 / Android API 26)
+- **Navigation Architecture**: Navigation pattern selection (stack, tab, drawer), deep linking support, back navigation handling per platform
+- **Mobile Performance Budget**: App startup time < 2s, frame rate 60fps minimum, memory usage < 150MB, APK/IPA size budget
+- **State Persistence**: Local storage strategy (AsyncStorage, SQLite, MMKV), state rehydration on app resume, background task handling
+
+---
+
+## Reliability Domain
+
+**Triggered when**: `reliability` domain matched (keywords: reliability, uptime, monitoring, sre, sla, slo, sli, etc.)
+
+Include in plan:
+
+- **SLO Definition**: Define Service Level Objectives for affected services (availability target, latency targets at p50/p95/p99, error rate budget)
+- **SLI Instrumentation**: Specify Service Level Indicators to measure (request success rate, request latency, system throughput), measurement method and data source
+- **Error Budget Impact**: Assess how the change affects existing error budgets, define acceptable error budget consumption for rollout
+- **Golden Signals**: Monitoring for all four golden signals (latency, traffic, errors, saturation) for new/modified services
+- **Resilience Patterns**: Circuit breaker placement, retry policy (exponential backoff with jitter), timeout configuration, bulkhead isolation for critical paths
+- **Incident Preparedness**: Runbook for new failure modes, alerting rules (page vs. ticket), escalation matrix, blast radius assessment
+- **Chaos Engineering**: Identify failure injection points for validation, steady-state hypothesis, abort conditions for chaos experiments
+- **Capacity Planning**: Resource requirements (CPU, memory, network, storage), scaling triggers (auto-scale thresholds), load testing validation for expected traffic growth
+
+---
+
+## Observability Domain
+
+**Triggered when**: `observability` domain matched (keywords: logging, tracing, metrics, monitoring, alerting, opentelemetry, etc.)
+
+Include in plan:
+
+- **Three Pillars Coverage**: Specify logging additions (structured JSON), metrics (counters, histograms, gauges), traces (span creation, context propagation)
+- **OpenTelemetry Integration**: SDK initialization, auto-instrumentation scope, manual span creation for business-critical paths, sampling strategy (head-based vs. tail-based)
+- **Log Architecture**: Log levels and when to use each (ERROR: actionable failures, WARN: degradation, INFO: business events, DEBUG: development only), structured fields, correlation ID propagation
+- **Alerting Strategy**: Alert conditions derived from SLOs, notification channels (PagerDuty/Slack), alert fatigue prevention (multi-window burn rate), silence/snooze policies
+- **Dashboard Design**: Key metrics visualization, RED method (Rate, Errors, Duration) per service, drill-down capability from overview to detail
+- **Cost Management**: Metric cardinality assessment, log volume projection, trace sampling rate optimization, retention policy per signal type
+
+---
+
+## Distributed Systems Domain
+
+**Triggered when**: `architecture` domain matched AND task involves multiple services, message queues, or event-driven patterns
+
+Include in plan:
+
+- **Consistency Strategy**: CAP theorem trade-off for the specific use case, consistency model selection (strong, eventual, causal), Saga pattern for distributed transactions (choreography vs. orchestration)
+- **Communication Pattern**: Synchronous (REST/gRPC) vs. asynchronous (message queue/event stream) decision per interaction, protocol selection criteria
+- **Fault Tolerance**: Failure mode analysis for each service interaction, fallback behavior, partial failure handling, data loss prevention
+- **Event-Driven Design**: Event schema definition (CloudEvents format), event ordering guarantees, idempotent consumers, dead letter queue strategy
+- **Service Discovery**: Registration mechanism, health check protocol, load balancing strategy (client-side vs. server-side), circuit breaker integration
+- **Data Sovereignty**: Which service owns which data, cross-service data access patterns (API calls, not shared databases), eventual consistency reconciliation
 
 ---
 
@@ -112,3 +180,5 @@ The planner reads this file when domain-specific sections are needed:
 2. For each matched domain, include the corresponding enhancer section
 3. Domain sections are added AFTER the base plan schema sections
 4. Multiple domains can be active simultaneously (e.g., frontend + backend for a full-stack feature)
+5. Each domain section contributes to the plan quality score (+2 bonus per matched domain section present, -2 penalty per missing)
+6. Domain enhancers leverage the specialized knowledge of their corresponding elevated agents (e.g., reliability domain draws from reliability-engineer's SRE Golden Signals framework)

package/.agent/skills/security-practices/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-practices
-description: Application security best practices and vulnerability prevention
+description: Application security best practices including Zero Trust principles, OAuth 2.0 / OpenID Connect flows, API security, supply chain security, and vulnerability prevention
 triggers: [context, security, auth, vulnerability]
 ---
 
@@ -21,7 +21,7 @@ This skill provides security guidelines following OWASP standards and industry b
 ### Password Security
 
 ```typescript
-// ✅ Use bcrypt with cost factor 12
+// Use bcrypt with cost factor 12
 import bcrypt from "bcrypt";
 
 const SALT_ROUNDS = 12;
@@ -55,20 +55,20 @@ const refreshToken = jwt.sign({ userId }, REFRESH_SECRET, { expiresIn: "7d" });
 ### Never Trust User Input
 
 ```typescript
-// ❌ SQL Injection vulnerable
+// SQL Injection vulnerable
 const query = `SELECT * FROM users WHERE id = ${userId}`;
 
-// ✅ Parameterized query
+// Parameterized query
 const user = await prisma.user.findUnique({ where: { id: userId } });
 ```
 
 ### Sanitize Output
 
 ```typescript
-// ❌ XSS vulnerable
+// XSS vulnerable
 element.innerHTML = userInput;
 
-// ✅ Escape HTML
+// Escape HTML
 import DOMPurify from "dompurify";
 element.innerHTML = DOMPurify.sanitize(userInput);
 ```
@@ -114,18 +114,194 @@ res.setHeader("Content-Security-Policy", "default-src 'self'");
 ## Secrets Management
 
 ```bash
-# ❌ Never commit secrets
+# Never commit secrets
 # .env file with API_KEY=sk-1234...
 
-# ✅ Use environment variables
+# Use environment variables
 export API_KEY=$(vault read secret/api-key)
 
-# ✅ Use secret managers
+# Use secret managers
 # AWS Secrets Manager, HashiCorp Vault, etc.
 ```
 
 ---
 
+## Zero Trust Principles
+
+Zero Trust assumes no implicit trust for any entity inside or outside the network perimeter. Every access request is fully authenticated, authorized, and encrypted before granting access.
+
+| Principle | Implementation | Verification |
+| :--- | :--- | :--- |
+| **Never trust, always verify** | Authenticate every request regardless of origin; treat internal traffic the same as external | Audit logs confirm no unauthenticated requests reach protected resources |
+| **Least privilege** | Grant minimum permissions required; use role-based and attribute-based access control | Periodic access reviews; automated permission drift detection |
+| **Assume breach** | Encrypt data at rest and in transit; segment blast radius; implement intrusion detection | Red team exercises; incident response drills validate containment |
+| **Micro-segmentation** | Isolate workloads with network policies; service mesh mTLS between microservices | Verify lateral movement is blocked between segments with penetration testing |
+| **Continuous validation** | Re-evaluate trust on every request; session tokens with short TTL; step-up auth for sensitive ops | Monitor for session hijacking; alert on anomalous access patterns |
+| **Device trust** | Require managed/compliant devices; verify device posture before granting access | Device compliance checks run at connection time and periodically |
+
+---
+
+## OAuth 2.0 / OpenID Connect Flows
+
+### Flow Selection Matrix
+
+| Client Type | Recommended Flow | Reason |
+| :--- | :--- | :--- |
+| **Web app (SPA)** | Authorization Code + PKCE | No client secret in browser; PKCE prevents interception |
+| **Web app (server)** | Authorization Code | Client secret stored server-side securely |
+| **Mobile / Desktop** | Authorization Code + PKCE | Public client; PKCE mandatory |
+| **Machine-to-Machine** | Client Credentials | No user interaction; service identity via client secret |
+| **Legacy (avoid)** | Implicit | Deprecated; tokens exposed in URL fragment |
+
+### Token Storage Requirements
+
+```typescript
+// NEVER store access tokens in localStorage (XSS-accessible)
+// NEVER store tokens in sessionStorage for long-lived sessions
+
+// Use httpOnly, Secure, SameSite cookies for refresh tokens
+res.cookie("refresh_token", token, {
+  httpOnly: true,
+  secure: true,
+  sameSite: "strict",
+  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
+  path: "/api/auth/refresh",
+});
+
+// Keep access tokens in memory only (JS variable)
+// They are short-lived (15 min) and re-obtained via refresh
+```
+
+### PKCE Implementation
+
+```typescript
+import crypto from "crypto";
+
+// Generate code verifier (43-128 chars, unreserved URI characters)
+function generateCodeVerifier(): string {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+// Derive code challenge from verifier
+function generateCodeChallenge(verifier: string): string {
+  return crypto.createHash("sha256").update(verifier).digest("base64url");
+}
+
+// All public clients MUST use PKCE (RFC 7636)
+// Send code_challenge with authorization request
+// Send code_verifier with token exchange request
+```
+
+---
+
+## API Security
+
+### Rate Limiting Patterns
+
+| Strategy | Use Case | Example |
+| :--- | :--- | :--- |
+| **Per-endpoint** | Protect expensive operations | `/api/search`: 10 req/min |
+| **Per-user** | Fair usage enforcement | Authenticated: 1000 req/hr |
+| **Sliding window** | Smooth traffic spikes | Rolling 60s window, max 100 |
+| **Token bucket** | Burst tolerance | 10 tokens, refill 1/sec |
+| **IP-based** | Unauthenticated endpoints | Login: 5 attempts/15 min |
+
+```typescript
+import rateLimit from "express-rate-limit";
+
+const apiLimiter = rateLimit({
+  windowMs: 15 * 60 * 1000, // 15 minutes
+  max: 100,
+  standardHeaders: true,
+  legacyHeaders: false,
+  keyGenerator: (req) => req.user?.id ?? req.ip,
+});
+
+app.use("/api/", apiLimiter);
+```
+
+### API Key Management
+
+- **Rotate keys** on a regular schedule (90 days max) and immediately on suspected compromise
+- **Scope keys** to specific endpoints, methods, and IP ranges
+- **Never embed keys** in client-side code or version control
+- **Use separate keys** for each environment (dev, staging, production)
+- **Log key usage** to detect anomalous patterns
+
+### Request Signing
+
+```typescript
+// Sign requests with HMAC to prevent tampering
+import crypto from "crypto";
+
+function signRequest(payload: string, secret: string): string {
+  return crypto.createHmac("sha256", secret).update(payload).digest("hex");
+}
+
+// Verify on server side; reject requests with invalid or expired signatures
+// Include timestamp in signed payload to prevent replay attacks
+```
+
+### API Versioning Security
+
+- Deprecate and remove old API versions that lack current security controls
+- Apply the same authentication and authorization to all active versions
+- Monitor traffic to deprecated versions for potential abuse
+- Never maintain insecure legacy endpoints for backward compatibility
+
+---
+
+## Supply Chain Security
+
+### Dependency Auditing
+
+```bash
+# Run audit on every CI build
+npm audit --audit-level=high
+
+# Fix known vulnerabilities
+npm audit fix
+
+# Use lockfile-only installs in CI to prevent supply chain attacks
+npm ci
+```
+
+### Lockfile Integrity
+
+- **Always commit** `package-lock.json` to version control
+- **Use `npm ci`** in CI/CD pipelines (installs from lockfile exactly)
+- **Review lockfile diffs** in pull requests for unexpected changes
+- **Enable lockfile-lint** to enforce registry and integrity hash policies
+
+### Dependency Pinning
+
+```json
+{
+  "dependencies": {
+    "express": "4.18.2",
+    "prisma": "5.10.0"
+  }
+}
+```
+
+- Pin exact versions in production applications (no `^` or `~`)
+- Use Dependabot or Renovate for controlled, reviewed updates
+- Separate security patches from feature updates in dependency PRs
+
+### Typosquatting Detection
+
+| Technique | Example |
+| :--- | :--- |
+| **Character swap** | `expresss` instead of `express` |
+| **Hyphen confusion** | `lodash-utils` mimicking `lodash` |
+| **Scope squatting** | `@myorg/config` vs `@my-org/config` |
+
+- Verify package publisher and download counts before installing
+- Use `npm config set ignore-scripts true` for initial installs, then review scripts
+- Consider using Socket.dev or Snyk to detect malicious packages automatically
+
+---
+
 ## Quick Reference
 
 | Practice     | Implementation        |
@@ -138,3 +314,7 @@ export API_KEY=$(vault read secret/api-key)
 | Secrets      | Environment, vaults   |
 | Dependencies | npm audit, Snyk       |
 | Logging      | Audit trail, no PII   |
+| Zero Trust   | Verify every request  |
+| OAuth 2.0    | Auth Code + PKCE      |
+| API Keys     | Scoped, rotated       |
+| Supply Chain | Lockfile, pin deps    |

package/README.md

@@ -1,6 +1,6 @@
 # 🚀 Antigravity AI Kit
 
-![version](https://img.shields.io/badge/version-3.2.0-blue)
+![version](https://img.shields.io/badge/version-3.3.1-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 ![AI Agents](https://img.shields.io/badge/AI%20Agents-19-purple)
 ![Skills](https://img.shields.io/badge/Skills-32-orange)
@@ -100,22 +100,14 @@ Creates a new project with `.agent/` pre-configured. Templates: `minimal`, `node
 npx antigravity-ai-kit init
 ```
 
-This automatically copies the `.agent/` folder to your project.
-
-### Option 3: Manual Installation
+### 🔄 Updating
 
 ```bash
-# 1. Clone the repository
-git clone https://github.com/besync-labs/antigravity-ai-kit.git
-
-# 2. Copy .agent/ to your project
-cp -r antigravity-ai-kit/.agent/ your-project/.agent/
-
-# 3. Start your session
-/status
+ag-kit update             # Non-destructive — preserves your customizations
+ag-kit update --dry-run   # Preview changes without applying
 ```
 
-That's it! The kit is now active and ready to accelerate your development.
+> **Prefer `ag-kit update` over `ag-kit init --force`**. The update command preserves your session data, ADRs, learning contexts, and customizations. Use `init --force` only for clean reinstalls.
 
 ### ✅ Verify Installation
 
@@ -124,6 +116,31 @@ ag-kit verify     # Manifest integrity check
 ag-kit scan       # Security scan
 ```
 
+### 🛡️ Safety Guarantees
+
+Antigravity AI Kit is designed to **never touch your project files**. All operations are scoped to the `.agent/` directory.
+
+| Your Project Files | Safe? | Details |
+|:---|:---|:---|
+| Source code (`src/`, `lib/`, `app/`) | ✅ Never touched | Init/update only operates on `.agent/` |
+| Config files (`.env`, `package.json`) | ✅ Never touched | No project config is read or written |
+| Documentation (`docs/`, `README.md`) | ✅ Never touched | Only `.agent/` docs are managed |
+| Tests (`tests/`, `__tests__/`) | ✅ Never touched | Kit tests are internal to the package |
+| Platform files (`android/`, `ios/`) | ✅ Never touched | No platform-specific operations |
+
+**`init --force` safety features (v3.3.1+):**
+- 🔒 **Auto-backup**: Creates timestamped backup of existing `.agent/` before overwriting
+- ⚛️ **Atomic copy**: Uses temp directory + rename to prevent corruption on failure
+- 🔗 **Symlink guard**: Skips symbolic links to prevent path traversal attacks
+- ⚠️ **Session warning**: Alerts if active work-in-progress would be destroyed
+- 🔍 **Dry-run preview**: `--dry-run --force` shows exactly which user files would be overwritten
+
+**`update` preserved files:**
+- `session-context.md` — Your active session notes
+- `session-state.json` — Your session metadata
+- `decisions/` — Your Architecture Decision Records
+- `contexts/` — Your learning data and plan quality logs
+
 ---
 
 ## 🏗️ Architecture Overview

package/bin/ag-kit.js

@@ -16,6 +16,7 @@ const path = require('path');
 
 const VERSION = require('../package.json').version;
 const AGENT_FOLDER = '.agent';
+const { safeCopyDirSync, readJsonSafe } = require('../lib/io');
 
 // ANSI colors
 const colors = {
@@ -49,7 +50,7 @@ ${colors.reset}
 ${colors.green}🚀 Antigravity AI Kit v${VERSION}${colors.reset}
 ${colors.yellow}   Transform Your IDE into an Autonomous Engineering Team${colors.reset}
 
-   • 19 AI Agents    • 31 Skills
+   • 19 AI Agents    • 32 Skills
    • 31 Commands     • 14 Workflows
    • Runtime Engine  • Error Budget
 `);
@@ -95,23 +96,28 @@ ${colors.bright}IDE Reference:${colors.reset}
 `);
 }
 
-function copyFolderSync(src, dest) {
-  if (!fs.existsSync(dest)) {
-    fs.mkdirSync(dest, { recursive: true });
-  }
-  
-  const entries = fs.readdirSync(src, { withFileTypes: true });
-  
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    
-    if (entry.isDirectory()) {
-      copyFolderSync(srcPath, destPath);
-    } else {
-      fs.copyFileSync(srcPath, destPath);
-    }
-  }
+/**
+ * Creates a timestamped backup of a directory.
+ * @param {string} dirPath - Directory to back up
+ * @returns {string} Path to the backup directory
+ */
+function backupDirectory(dirPath) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${dirPath}.backup-${timestamp}`;
+  safeCopyDirSync(dirPath, backupPath);
+  return backupPath;
+}
+
+/**
+ * Checks if there is an active session with in-progress work.
+ * @param {string} agentPath - Path to existing .agent directory
+ * @returns {boolean} True if session-state indicates active work
+ */
+function hasActiveSession(agentPath) {
+  const statePath = path.join(agentPath, 'session-state.json');
+  const state = readJsonSafe(statePath, null);
+  if (!state) return false;
+  return state.currentTask || state.inProgress || state.activeWorkflow;
 }
 
 function countItems(dir, type = 'dir') {
@@ -146,24 +152,76 @@ function initCommand(options) {
   // Check if already exists
   if (fs.existsSync(agentPath) && !options.force) {
     log(`\n⚠️  ${AGENT_FOLDER} folder already exists!`, 'yellow');
-    log('   Use --force to overwrite\n', 'yellow');
+    log('   Use --force to overwrite', 'yellow');
+    log('   Use ag-kit update for non-destructive updates\n', 'yellow');
     process.exit(1);
   }
   
+  // M-3: Active session warning for --force
+  if (options.force && fs.existsSync(agentPath) && hasActiveSession(agentPath)) {
+    log('\n⚠️  Active session detected! Force-overwrite will destroy in-progress work.', 'yellow');
+    log('   Consider using ag-kit update instead.\n', 'yellow');
+  }
+
   if (options.dryRun) {
     log('\n🔍 Dry run mode - no changes will be made\n', 'cyan');
     log(`   Would copy: ${sourcePath}`, 'cyan');
     log(`   To: ${agentPath}\n`, 'cyan');
+    // M-2: Show force damage preview
+    if (options.force && fs.existsSync(agentPath)) {
+      log('   ⚠️  --force would overwrite these user files:', 'yellow');
+      const userFiles = ['session-context.md', 'session-state.json'];
+      const userDirs = ['decisions', 'contexts'];
+      for (const f of userFiles) {
+        if (fs.existsSync(path.join(agentPath, f))) {
+          log(`      • ${f}`, 'yellow');
+        }
+      }
+      for (const d of userDirs) {
+        if (fs.existsSync(path.join(agentPath, d))) {
+          log(`      • ${d}/ (directory)`, 'yellow');
+        }
+      }
+      log('', 'reset');
+    }
     return;
   }
   
-  // Copy .agent folder
-  logStep('1/3', 'Copying .agent folder...');
+  // C-2: Auto-backup before force-overwrite
+  if (options.force && fs.existsSync(agentPath)) {
+    logStep('1/4', 'Backing up existing .agent folder...');
+    try {
+      const backupPath = backupDirectory(agentPath);
+      log(`   ✓ Backup created: ${path.basename(backupPath)}`, 'green');
+    } catch (err) {
+      log(`   ⚠️  Backup failed: ${err.message}`, 'yellow');
+      log('   Proceeding without backup...', 'yellow');
+    }
+  }
+
+  // C-3: Atomic copy via temp directory
+  const stepPrefix = options.force && fs.existsSync(agentPath) ? '2/4' : '1/3';
+  logStep(stepPrefix, 'Copying .agent folder...');
   
+  const tempPath = `${agentPath}.tmp-${Date.now()}`;
   try {
-    copyFolderSync(sourcePath, agentPath);
+    safeCopyDirSync(sourcePath, tempPath);
+    // Remove old directory if force-overwriting
+    if (fs.existsSync(agentPath)) {
+      fs.rmSync(agentPath, { recursive: true, force: true });
+    }
+    // Atomic rename: move temp to final
+    fs.renameSync(tempPath, agentPath);
     log('   ✓ Copied successfully', 'green');
   } catch (err) {
+    // Cleanup temp directory on failure
+    try {
+      if (fs.existsSync(tempPath)) {
+        fs.rmSync(tempPath, { recursive: true, force: true });
+      }
+    } catch {
+      // Cleanup failure is non-critical
+    }
     log(`   ✗ Failed to copy: ${err.message}`, 'red');
     process.exit(1);
   }
@@ -366,6 +424,13 @@ function updateCommand(updateOptions) {
     const updater = require('../lib/updater');
     const isDryRun = updateOptions.dryRun;
 
+    // M-1: Show version transition
+    const currentManifest = readJsonSafe(path.join(agentPath, 'manifest.json'), {});
+    const currentVersion = currentManifest.kitVersion || 'unknown';
+    if (currentVersion !== VERSION) {
+      log(`\n   📦 Upgrading from v${currentVersion} → v${VERSION}`, 'cyan');
+    }
+
     if (isDryRun) {
       log('\n🔍 Dry run mode — no changes will be made\n', 'cyan');
     }