cfsa-antigravity 2.19.0 → 2.19.2

package/template/.claude/skills/deployment-procedures/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: deployment-procedures
+description: Production deployment principles and decision-making. Safe deployment workflows, rollback strategies, and verification. Teaches thinking, not scripts.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Deployment Procedures
+
+> Deployment principles and decision-making for safe production releases.
+> **Learn to THINK, not memorize scripts.**
+
+---
+
+## ⚠️ How to Use This Skill
+
+This skill teaches **deployment principles**, not bash scripts to copy.
+
+- Every deployment is unique
+- Understand the WHY behind each step
+- Adapt procedures to your platform
+
+---
+
+## 1. Platform Selection
+
+### Decision Tree
+
+```
+What are you deploying?
+│
+├── Static site / JAMstack
+│   └── Vercel, Netlify, Cloudflare Pages
+│
+├── Simple web app
+│   ├── Managed → Railway, Render, Fly.io
+│   └── Control → VPS + PM2/Docker
+│
+├── Microservices
+│   └── Container orchestration
+│
+└── Serverless
+    └── Edge functions, Lambda
+```
+
+### Each Platform Has Different Procedures
+
+| Platform | Deployment Method |
+|----------|------------------|
+| **Vercel/Netlify** | Git push, auto-deploy |
+| **Railway/Render** | Git push or CLI |
+| **VPS + PM2** | SSH + manual steps |
+| **Docker** | Image push + orchestration |
+| **Kubernetes** | kubectl apply |
+
+---
+
+## 2. Pre-Deployment Principles
+
+### The 4 Verification Categories
+
+| Category | What to Check |
+|----------|--------------|
+| **Code Quality** | Tests passing, linting clean, reviewed |
+| **Build** | Production build works, no warnings |
+| **Environment** | Env vars set, secrets current |
+| **Safety** | Backup done, rollback plan ready |
+
+### Pre-Deployment Checklist
+
+- [ ] All tests passing
+- [ ] Code reviewed and approved
+- [ ] Production build successful
+- [ ] Environment variables verified
+- [ ] Database migrations ready (if any)
+- [ ] Rollback plan documented
+- [ ] Team notified
+- [ ] Monitoring ready
+
+---
+
+## 3. Deployment Workflow Principles
+
+### The 5-Phase Process
+
+```
+1. PREPARE
+   └── Verify code, build, env vars
+
+2. BACKUP
+   └── Save current state before changing
+
+3. DEPLOY
+   └── Execute with monitoring open
+
+4. VERIFY
+   └── Health check, logs, key flows
+
+5. CONFIRM or ROLLBACK
+   └── All good? Confirm. Issues? Rollback.
+```
+
+### Phase Principles
+
+| Phase | Principle |
+|-------|-----------|
+| **Prepare** | Never deploy untested code |
+| **Backup** | Can't rollback without backup |
+| **Deploy** | Watch it happen, don't walk away |
+| **Verify** | Trust but verify |
+| **Confirm** | Have rollback trigger ready |
+
+---
+
+## 4. Post-Deployment Verification
+
+### What to Verify
+
+| Check | Why |
+|-------|-----|
+| **Health endpoint** | Service is running |
+| **Error logs** | No new errors |
+| **Key user flows** | Critical features work |
+| **Performance** | Response times acceptable |
+
+### Verification Window
+
+- **First 5 minutes**: Active monitoring
+- **15 minutes**: Confirm stable
+- **1 hour**: Final verification
+- **Next day**: Review metrics
+
+---
+
+## 5. Rollback Principles
+
+### When to Rollback
+
+| Symptom | Action |
+|---------|--------|
+| Service down | Rollback immediately |
+| Critical errors | Rollback |
+| Performance >50% degraded | Consider rollback |
+| Minor issues | Fix forward if quick |
+
+### Rollback Strategy by Platform
+
+| Platform | Rollback Method |
+|----------|----------------|
+| **Vercel/Netlify** | Redeploy previous commit |
+| **Railway/Render** | Rollback in dashboard |
+| **VPS + PM2** | Restore backup, restart |
+| **Docker** | Previous image tag |
+| **K8s** | kubectl rollout undo |
+
+### Rollback Principles
+
+1. **Speed over perfection**: Rollback first, debug later
+2. **Don't compound errors**: One rollback, not multiple changes
+3. **Communicate**: Tell team what happened
+4. **Post-mortem**: Understand why after stable
+
+---
+
+## 6. Zero-Downtime Deployment
+
+### Strategies
+
+| Strategy | How It Works |
+|----------|--------------|
+| **Rolling** | Replace instances one by one |
+| **Blue-Green** | Switch traffic between environments |
+| **Canary** | Gradual traffic shift |
+
+### Selection Principles
+
+| Scenario | Strategy |
+|----------|----------|
+| Standard release | Rolling |
+| High-risk change | Blue-green (easy rollback) |
+| Need validation | Canary (test with real traffic) |
+
+---
+
+## 7. Emergency Procedures
+
+### Service Down Priority
+
+1. **Assess**: What's the symptom?
+2. **Quick fix**: Restart if unclear
+3. **Rollback**: If restart doesn't help
+4. **Investigate**: After stable
+
+### Investigation Order
+
+| Check | Common Issues |
+|-------|--------------|
+| **Logs** | Errors, exceptions |
+| **Resources** | Disk full, memory |
+| **Network** | DNS, firewall |
+| **Dependencies** | Database, APIs |
+
+---
+
+## 8. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Deploy on Friday | Deploy early in week |
+| Rush deployment | Follow the process |
+| Skip staging | Always test first |
+| Deploy without backup | Backup before deploy |
+| Walk away after deploy | Monitor for 15+ min |
+| Multiple changes at once | One change at a time |
+
+---
+
+## 9. Decision Checklist
+
+Before deploying:
+
+- [ ] **Platform-appropriate procedure?**
+- [ ] **Backup strategy ready?**
+- [ ] **Rollback plan documented?**
+- [ ] **Monitoring configured?**
+- [ ] **Team notified?**
+- [ ] **Time to monitor after?**
+
+---
+
+## 10. Best Practices
+
+1. **Small, frequent deploys** over big releases
+2. **Feature flags** for risky changes
+3. **Automate** repetitive steps
+4. **Document** every deployment
+5. **Review** what went wrong after issues
+6. **Test rollback** before you need it
+
+---
+
+> **Remember:** Every deployment is a risk. Minimize risk through preparation, not speed.

package/template/.claude/skills/design-anti-cliche/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: design-anti-cliche
+description: "Universal AI design correction rules. Always active. Prevents the agent from falling into common AI-generated design patterns that produce generic, indistinguishable output. Project-specific brand-guidelines can override any rule here."
+---
+
+# Design Anti-Cliché Rules
+
+> **Scope**: These rules apply to ALL design work — ideation, spec writing, design system creation, and implementation. They correct universal AI tendencies, not project-specific preferences.
+
+> **Override**: The `brand-guidelines` skill can override ANY rule below. If the user's confirmed brand direction contradicts a rule here (e.g., purple IS the brand color), `brand-guidelines` takes precedence.
+
+---
+
+## 1. Safe Harbor Forbidden Defaults
+
+AI agents retreat to "safe" patterns from training data. These are **forbidden as defaults** — you may use them only if the user explicitly requests them or the design direction specifically calls for them.
+
+| # | Forbidden Default | Why It's Banned | Use Only When |
+|---|---|---|---|
+| 1 | **Standard Hero Split** (left text / right image) | Most overused layout in AI output. Every SaaS site looks identical. | User explicitly requests split layout |
+| 2 | **Bento Grids** as default landing page layout | Overused since Apple adopted it. Not every page is a dashboard. | Genuinely complex data that benefits from card-based organization |
+| 3 | **Mesh / Aurora Gradients** as background decoration | Floating colored blobs scream "AI-generated." | Used purposefully as part of a confirmed design direction |
+| 4 | **Glassmorphism** as "premium" indicator | Blur + thin border is the AI's go-to for "modern." It's a cliché. | Confirmed Glass design direction in brand-guidelines |
+| 5 | **Fintech Blue / Deep Cyan** default palette | The "safe escape" color for any professional app. Zero personality. | User's industry genuinely warrants trust-signaling blue |
+| 6 | **Generic Marketing Copy** | Buzzwords make every product indistinguishable | Never — always write specific, concrete copy |
+
+### Banned Copy Words
+
+Never use these in headlines, hero text, or primary CTAs unless the user's actual product documentation uses them:
+
+`Orchestrate` · `Empower` · `Elevate` · `Seamless` · `Leverage` · `Synergize` · `Unlock` · `Supercharge` · `Game-changing` · `Next-generation` · `Cutting-edge` · `Revolutionary`
+
+**Instead:** Describe what the product actually does in concrete terms. "Send invoices in 30 seconds" beats "Elevate your billing experience."
+
+---
+
+## 2. Purple Ban
+
+Purple, violet, indigo, and magenta are the #1 AI design cliché. They are **banned as primary or brand colors** unless the user explicitly requests them.
+
+### Banned Values
+
+- **Hex codes**: `#8B5CF6`, `#A855F7`, `#9333EA`, `#7C3AED`, `#6D28D9`, `#A78BFA`, `#C4B5FD`, `#DDD6FE`, `#EDE9FE`
+- **Tailwind classes**: `purple-*`, `violet-*`, `indigo-*`, `fuchsia-*` as primary/brand colors
+- **CSS keywords**: `purple`, `violet`, `indigo`, `fuchsia`, `magenta`, `lavender` as primary/brand colors
+- **Purple gradients** of any kind as hero or background treatment
+
+### When Purple IS Allowed
+
+- User explicitly says "I want purple" or "our brand is purple"
+- `brand-guidelines` has purple in the confirmed color palette
+- Used as a minor accent (not primary, not brand-defining)
+- Data visualization where purple is part of a sequential/categorical scale
+
+### Recommended Alternatives
+
+When you'd reflexively reach for purple, try: **Teal**, **Emerald**, **Amber**, **Rose**, **Slate** — or ask the user what palette fits their brand.
+
+---
+
+## 3. Layout Diversification
+
+Break the "Standard Split" habit. When designing hero sections or landing pages, choose from these alternative structures:
+
+| Layout | Description | Best For |
+|---|---|---|
+| **Massive Typographic Hero** | Headline at 300px+, visual behind or inside the letters | Bold brands, creative agencies |
+| **Center-Staggered** | Each element (H1, P, CTA) has different horizontal alignment | Modern, editorial feel |
+| **Layered Depth (Z-axis)** | Visuals overlap text, creating depth | Immersive, premium products |
+| **Vertical Narrative** | No "above the fold" hero — story starts immediately with flowing fragments | Story-driven, content-first |
+| **Extreme Asymmetry (90/10)** | Everything compressed to one edge, 90% negative space | Luxury, high-end, artistic |
+| **Full-Bleed Media** | Image/video fills the entire viewport, text overlaid | Photography, portfolio, lifestyle |
+
+> **Rule:** If you're about to use "left text / right image," stop. Pick one of the above or invent something new.
+
+---
+
+## 4. UI Library Default Ban
+
+Never automatically use a component library without asking the user. These are AI favorites from training data, not the user's choice:
+
+- ❌ shadcn/ui (overused AI default)
+- ❌ Radix UI (AI favorite for "accessible" claim)
+- ❌ Chakra UI (common AI fallback)
+- ❌ Material UI / MUI (generic corporate look)
+
+**Always ask:** "Which UI approach do you prefer?" and offer options:
+1. Pure CSS / Tailwind — custom components, no library
+2. shadcn/ui — if the user explicitly wants it
+3. Headless UI — unstyled, accessible primitives
+4. Radix — if the user explicitly wants it
+5. Custom components — maximum control
+6. Other — the user's choice
+
+---
+
+## 5. Corner Radius Rule
+
+The "safe boredom zone" of `4px–8px` (`rounded-md`) is the AI default for everything. It produces visually indistinct interfaces.
+
+**Rule:** Make a deliberate choice. Don't sit in the middle.
+
+| Intent | Radius | Examples |
+|---|---|---|
+| **Sharp / Technical / Luxury** | `0px–2px` | Brutalist, minimalist, professional |
+| **Balanced / Modern** | `8px–12px` | SaaS dashboards, productivity tools |
+| **Soft / Friendly / Playful** | `16px–32px` | Social apps, lifestyle, consumer |
+| **Pill / Expressive** | `9999px` / `full` | Tags, badges, feature cards |
+
+> The chosen radius should be consistent across the design system — don't mix sharp cards with pill buttons unless the design direction explicitly calls for contrast.
+
+---
+
+## 6. Maestro Self-Check
+
+Before delivering any design work (specs, mockups, or implementations), answer these questions internally. If any answer is "yes" to the bad pattern, revise before presenting.
+
+| # | Question | Bad Answer |
+|---|---|---|
+| 1 | Does this look like something an AI would generate? | Yes → revise |
+| 2 | Could I swap the brand name and this would fit any other product? | Yes → not specific enough |
+| 3 | Am I using purple/indigo because it "feels modern"? | Yes → Purple Ban violation |
+| 4 | Is the layout "left text / right image" or a bento grid? | Yes without explicit request → Safe Harbor violation |
+| 5 | Would a designer at a top agency present this to a client? | No → raise the bar |
+| 6 | Is every animation serving a purpose, or just decoration? | Decoration → remove it |
+
+---
+
+## 7. Modern Cliché Scan
+
+Run this scan before committing to any design approach:
+
+```
+🔍 CLICHÉ SCAN:
+├── Am I defaulting to "Left Text / Right Visual"? → BETRAY IT
+├── Am I using Bento Grids to organize content safely? → BREAK THE GRID
+├── Am I using "safe" SaaS fonts and color pairs? → DISRUPT THE PALETTE
+├── Am I using purple/indigo because it "feels techy"? → REPLACE IT
+├── Am I writing "Empower your team" copy? → WRITE SOMETHING REAL
+└── Will I remember this design in a year? → If no, push harder
+```
+
+---
+
+## 8. Override Protocol
+
+These rules are **universal defaults**. They can be overridden by:
+
+1. **`brand-guidelines` skill** — If the confirmed design direction uses a forbidden element (purple brand, glassmorphism direction, etc.), the brand guideline takes precedence
+2. **Explicit user request** — If the user says "I want a bento grid layout," use it
+3. **Design reference data** — If the searchable design database returns a style that uses a forbidden element and the user confirms it, use it
+
+**Override hierarchy:** User request > brand-guidelines > design-anti-cliche defaults
+
+When overriding, acknowledge the override:
+```
+Using glassmorphism per confirmed "Glass" design direction — 
+anti-cliché default overridden by brand-guidelines.
+```

package/template/.claude/skills/design-direction/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: design-direction
+description: >
+  Design direction interview methodology — constraint-first discovery of visual
+  direction for web, desktop, and mobile surfaces. Covers 5 constraint questions,
+  6 direction options, and CLI-surface variant.
+triggers:
+  - /create-prd-stack (Design Direction axis)
+---
+
+# Design Direction
+
+Constraint-first discovery of visual direction for all visual surfaces (web, desktop, mobile). For CLI-only projects, use the CLI variant at the end.
+
+## Constraint Questions
+
+Ask these five questions first:
+
+1. What is the emotional tone of the product? (professional/trustworthy, playful/approachable, premium/luxury, raw/technical, editorial/content-first)
+2. Who is the primary audience? (developers, consumers, enterprise, creatives, general public)
+3. Are there existing brand assets? (logo, colors, fonts — if yes, the direction must work within them)
+4. What are the top 2–3 competitors' visual styles?
+5. Are there hard constraints? (WCAG AA required, white-label needs, dark mode required, existing brand guidelines)
+
+## Option Table
+
+Present 5 options + Hybrid:
+
+| Direction | What It Is | Pros | Cons | Best For |
+|---|---|---|---|---|
+| Minimal/Functional | Clean, whitespace-heavy, typography-led | Timeless, fast, accessible | Can feel cold or generic | SaaS tools, developer products |
+| Editorial/Magazine | Strong typographic hierarchy, content-first | Distinctive, great for content-heavy products | Complex to maintain | Media, blogs, knowledge platforms |
+| Luxury/Refined | Restrained palette, premium materials feel, subtle motion | High perceived value | Can feel inaccessible | Premium SaaS, fintech, professional services |
+| Playful/Expressive | Bold color, personality, illustration, animation | Memorable, high engagement | Can age quickly | Consumer apps, gaming, social |
+| Technical/Brutalist | Raw, grid-exposed, monospace, data-dense | Authentic for technical audiences | Polarizing | Dev tools, dashboards, data products |
+| Hybrid | Combine elements from two directions | Best of both | Requires design discipline | When constraints pull in two directions |
+
+## Per-Axis Flow
+
+1. Ask constraint questions
+2. Present filtered option table with recommendation based on constraints
+3. Wait for user confirmation
+4. Fire bootstrap with `DESIGN_DIRECTION=[confirmed direction]`
+
+> **CLI surfaces**: For CLI-only projects, replace the visual direction options with CLI-appropriate ones: output verbosity philosophy (terse vs. informative), color usage (minimal/semantic vs. rich), information density (compact vs. spacious), personality (friendly vs. utilitarian).

package/template/.claude/skills/error-handling-patterns/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: error-handling-patterns
+description: Master error handling patterns across languages including exceptions, Result types, error propagation, and graceful degradation to build resilient applications. Use when implementing error handling, designing APIs, or improving application reliability.
+---
+
+# Error Handling Patterns
+
+Build resilient applications with robust error handling strategies that gracefully handle failures and provide excellent debugging experiences.
+
+## When to Use This Skill
+
+- Implementing error handling in new features
+- Designing error-resilient APIs
+- Debugging production issues
+- Improving application reliability
+- Creating better error messages for users and developers
+- Implementing retry and circuit breaker patterns
+- Handling async/concurrent errors
+- Building fault-tolerant distributed systems
+
+## Stack-Specific References
+
+After reading the methodology below, read the reference matching your surface's Languages column in the surface stack map (`.agent/instructions/tech-stack.md`):
+
+| Language | Reference |
+|----------|-----------|
+| TypeScript / JavaScript | `references/typescript.md` |
+| Python | `references/python.md` |
+| Go | `references/go.md` |
+| Rust | `references/rust.md` |
+
+## Core Concepts
+
+### 1. Error Handling Philosophies
+
+Every language takes a different approach to error handling. Know which philosophy your language uses and follow its idioms:
+
+| Philosophy | Description | Languages |
+|-----------|-------------|-----------|
+| **Exceptions** | Traditional try-catch, disrupts control flow | Python, TypeScript/JS, Java, C# |
+| **Result Types** | Explicit success/failure, functional approach | Rust, Haskell, modern TypeScript |
+| **Error Returns** | Explicit error as return value, requires discipline | Go |
+| **Option/Maybe Types** | For nullable values without exceptions | Rust, Haskell, Swift |
+| **Panics/Crashes** | Unrecoverable errors, programming bugs | Rust (panic), Go (panic), Python (SystemExit) |
+
+**When to Use Each:**
+
+- Exceptions: Unexpected errors, exceptional conditions
+- Result Types: Expected errors, validation failures
+- Panics/Crashes: Unrecoverable errors, programming bugs
+
+### 2. Error Categories
+
+**Recoverable Errors** — the application can handle and continue:
+
+- Network timeouts
+- Missing files
+- Invalid user input
+- API rate limits
+
+**Unrecoverable Errors** — the application should crash and restart:
+
+- Out of memory
+- Stack overflow
+- Programming bugs (null pointer, etc.)
+
+## Universal Patterns
+
+### Pattern 1: Circuit Breaker
+
+Prevent cascading failures in distributed systems. When a downstream service fails repeatedly, stop calling it temporarily to let it recover.
+
+**State machine:**
+
+```
+CLOSED  →  (failures ≥ threshold)  →  OPEN
+OPEN    →  (timeout elapsed)       →  HALF_OPEN
+HALF_OPEN → (success ≥ threshold)  →  CLOSED
+HALF_OPEN → (any failure)          →  OPEN
+```
+
+**Parameters:**
+- `failure_threshold` — how many failures before opening the circuit (e.g., 5)
+- `timeout` — how long to stay open before trying again (e.g., 60s)
+- `success_threshold` — how many successes in HALF_OPEN before closing (e.g., 2)
+
+See language-specific references for implementation examples.
+
+### Pattern 2: Error Aggregation
+
+Collect multiple errors instead of failing on first error. Essential for form validation, batch processing, and multi-field input.
+
+**The pattern:**
+1. Create an error collector
+2. Validate each field/item independently, adding errors to the collector
+3. After all validations, check if errors exist
+4. If yes, throw/return all errors at once
+
+See language-specific references for implementation examples.
+
+### Pattern 3: Graceful Degradation
+
+Provide fallback functionality when errors occur. The system continues operating with reduced capability rather than failing completely.
+
+**Strategies:**
+- **Primary/fallback chain** — try cache, fall back to database, fall back to default
+- **Multiple provider fallback** — try provider A, then B, then C
+- **Feature degradation** — disable non-essential features when dependencies fail
+- **Default values** — return safe defaults when data is temporarily unavailable
+
+See language-specific references for implementation examples.
+
+### Pattern 4: Retry with Exponential Backoff
+
+Automatically retry failed operations with increasing delays between attempts.
+
+**Parameters:**
+- `max_attempts` — maximum retry count (e.g., 3)
+- `backoff_factor` — multiplier for delay between attempts (e.g., 2.0)
+- `retryable_exceptions` — which errors are worth retrying (network, timeout — NOT validation)
+
+**Delay formula:** `delay = backoff_factor ^ attempt` (1s, 2s, 4s, 8s, ...)
+
+See language-specific references for implementation examples.
+
+## Best Practices
+
+1. **Fail Fast**: Validate input early, fail quickly
+2. **Preserve Context**: Include stack traces, metadata, timestamps
+3. **Meaningful Messages**: Explain what happened and how to fix it
+4. **Log Appropriately**: Error = log, expected failure = don't spam logs
+5. **Handle at Right Level**: Catch where you can meaningfully handle
+6. **Clean Up Resources**: Use try-finally, context managers, defer, RAII
+7. **Don't Swallow Errors**: Log or re-throw, don't silently ignore
+8. **Type-Safe Errors**: Use typed errors when possible
+
+## Common Pitfalls
+
+- **Catching Too Broadly**: `except Exception` / `catch (e)` hides bugs
+- **Empty Catch Blocks**: Silently swallowing errors
+- **Logging and Re-throwing**: Creates duplicate log entries
+- **Not Cleaning Up**: Forgetting to close files, connections
+- **Poor Error Messages**: "Error occurred" is not helpful
+- **Ignoring Async Errors**: Unhandled promise rejections, goroutine panics
+
+---
+
+## Error Architecture Interview
+
+This interview is mandatory for every project. All 5 decisions below must be confirmed before proceeding to Data Strategy. Do not skip or defer any decision — this is a hard gate.
+
+### Decision 1 — Global Error Envelope
+
+Every error response from any surface must conform to this canonical 4-field structure:
+
+| Field | Description |
+|-------|-------------|
+| `code` | Machine-readable error code (e.g., `VALIDATION_FAILED`, `NOT_FOUND`). Clients switch on this field. |
+| `message` | Human-readable explanation of what went wrong. Safe to display to end users. |
+| `requestId` | Unique identifier for the request that caused the error. Used for support and debugging. |
+| `details` | `object \| null`. Structured additional context (e.g., field-level validation errors) or `null` when no extra detail applies. |
+
+**Locked JSON example:**
+
+```json
+{
+  "code": "VALIDATION_FAILED",
+  "message": "Email address is not valid.",
+  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "details": { "field": "email", "reason": "must contain @" }
+}
+```
+
+All four top-level fields are always present in every error response.
+
+**Rule:** No other top-level fields (`status`, `error`, `timestamp`) may appear in the error envelope. HTTP status codes are conveyed via the HTTP response status line, not inside the body.
+
+### Decision 2 — Error Propagation Chain
+
+For each layer in the stack (database → service layer → API handler → transport → client), define: what errors are caught, what is logged (and at what level), and what is exposed to the next layer.
+
+**Rule:** No layer may expose raw upstream errors to the client. Every layer must catch, wrap, and translate errors before passing them upward.
+
+### Decision 3 — Unhandled Exception Strategy
+
+Define the process-level catch mechanism:
+
+- **Mechanism name** — the specific runtime feature or library used to catch unhandled exceptions (e.g., `process.on('uncaughtException')`, global error middleware, panic recovery).
+- **Logged fields** — what information is captured when an unhandled exception occurs (stack trace, request context, environment, timestamp).
+- **Client response** — must conform to the global error envelope defined in Decision 1.
+- **Alerting timeline** — how quickly the team is notified after an unhandled exception (e.g., "PagerDuty within 5 minutes for >10 unhandled exceptions/minute").
+
+### Decision 4 — Client Fallback Contract
+
+Define per-surface behavior when the backend is unreachable or returns an error:
+
+- **Offline mode support** — does the surface support offline operation? If yes, what subset of features remains available?
+- **UI on network failure** — what does the user see when the network is down or the API is unreachable (toast, full-page error, inline message)?
+- **Retry strategy** — automatic retry with backoff, manual retry button, or no retry?
+- **Timeout thresholds** — how long the surface waits before declaring a request failed (e.g., 10s for API calls, 30s for file uploads).
+
+### Decision 5 — Error Boundary Strategy
+
+Define per-surface error boundary placement and behavior:
+
+- **Boundary placement** — where error boundaries are placed in the component tree (page-level, section-level, component-level).
+- **Fallback UI** — what the user sees when a boundary catches an error (generic error message, contextual fallback, partial degradation).
+- **Telemetry reporting** — how caught errors are reported to the observability stack (error tracking service name, severity classification, PII scrubbing before reporting).
+
+### User Presentation Prompts
+
+Present these three questions to the user for confirmation:
+
+1. "Does the global error envelope cover every field your clients need?"
+2. "Are there surfaces where the fallback contract needs to differ?"
+3. "Is the alerting timeline appropriate for your operational maturity?"
+
+### Output
+
+Write completed decisions to `architecture-draft.md` under `## Error Architecture` with five sub-sections matching the five decisions above:
+
+1. `### Global Error Envelope`
+2. `### Error Propagation Chain`
+3. `### Unhandled Exception Strategy`
+4. `### Client Fallback Contract`
+5. `### Error Boundary Strategy`