Initial commit from agent

.env.example

@@ -0,0 +1,20 @@
+# ─── Anthropic ─────────────────────────────────────
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+
+# ─── Fish Audio TTS ─────────────────────────────────
+FISH_AUDIO_API_KEY=your_fish_audio_api_key_here
+# Optional: specific voice model ID
+FISH_AUDIO_VOICE_ID=
+
+# ─── Whisper ────────────────────────────────────────
+# Options: tiny, base, small, medium, large
+WHISPER_MODEL=base
+
+# ─── Server ─────────────────────────────────────────
+HOST=0.0.0.0
+PORT=8000
+
+# ─── Google Keep (gkeepapi) ─────────────────────────
+# Master token from Android device or Google account
+GOOGLE_KEEP_EMAIL=
+GOOGLE_KEEP_MASTER_TOKEN=

.gitignore

@@ -0,0 +1,34 @@
+# Google OAuth — NEVER commit
+credentials.json
+token.json
+*.pickle
+
+# Environment
+.env
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/

AGENTS.md

@@ -0,0 +1,68 @@
+# Agent Operating Guide
+
+Use this file as the first entrypoint for work in this repository.
+
+If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) exists and contains filled-in defaults, read it immediately after this file and treat it as the source of preloaded project preferences unless the destination repository provides stronger instructions.
+
+## Default Behavior
+
+- Inspect the repository before making assumptions.
+- Prefer implementing and verifying work over giving abstract advice unless the user explicitly asks for planning only.
+- Read only the skill files needed for the current task.
+- Reuse existing project patterns, naming, architecture, and conventions.
+- Test or validate changes when feasible, then summarize outcomes and any remaining risks.
+- Update or create documentation when the change affects usage, onboarding, behavior, or developer workflow.
+- If repository-specific instructions conflict with this suite, follow the repository-specific instructions.
+
+## How To Load Skills
+
+1. Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in for this deployment.
+2. Read [SKILLS.md](./SKILLS.md).
+3. Identify the task category and open the matching hub file.
+4. Open only the specialized skill files relevant to the request.
+5. Combine skills when the task spans multiple areas.
+6. Avoid loading unrelated skills just because they exist.
+
+## Context Economy Rules
+
+- Default to reading one hub and two to four specialized skills for a normal task.
+- Add more skills only when they materially change the approach, output, or quality bar.
+- Prefer depth in the relevant skills over shallow loading across many categories.
+- If two skills overlap heavily, choose the one that best matches the main risk or deliverable.
+- Re-open the index when the task shifts, but do not reload the entire library reflexively.
+- Treat the deployment profile as the early context layer and avoid re-reading it unless the task changes the relevant preference area.
+
+## Instruction Precedence
+
+Apply guidance in this order:
+
+1. Destination repository instructions
+2. [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md)
+3. Generic routing and skill guidance from this suite
+
+## Routing Table
+
+| Task type | Start here |
+| --- | --- |
+| Feature work, refactors, reviews, tests, backend, frontend | [hubs/software-development.md](./hubs/software-development.md) |
+| Failing tests, bugs, incident-style analysis, root-cause work | [hubs/debugging.md](./hubs/debugging.md) |
+| Technical docs, onboarding, release notes, change communication | [hubs/documentation.md](./hubs/documentation.md) |
+| UX evaluation, UI polish, interaction quality, content design | [hubs/ui-ux.md](./hubs/ui-ux.md) |
+| Product copy, launch messaging, marketing content | [hubs/marketing.md](./hubs/marketing.md) |
+| Ideation, option generation, structured brainstorming | [hubs/brainstorming.md](./hubs/brainstorming.md) |
+
+## Combination Rules
+
+- For new features, combine implementation + test strategy + relevant docs.
+- For UI work, combine frontend implementation + UX review + product copy when text matters.
+- For broken behavior, combine bug triage + debugging workflow + change summary when a fix lands.
+- For launch or release tasks, combine technical docs or release notes with messaging or marketing skills as needed.
+- For high-risk changes, add security review, observability, or performance optimization as appropriate.
+- For long-lived system changes, add architecture and system design, dependency lifecycle, or database migration planning when relevant.
+
+## Output Expectations
+
+- Deliver concrete work products, not just observations.
+- State key assumptions when the repository does not answer them.
+- Call out blockers, tradeoffs, risks, and unverified areas clearly.
+- Keep explanations concise and action-oriented.

DEPLOYMENT-PROFILE.md

@@ -0,0 +1,99 @@
+# Deployment Profile
+
+Use this file to stage prefilled defaults before deploying the suite into other repositories.
+
+This file is the canonical source of preloaded build, tool, environment, workflow, and quality preferences for the deployed bundle. Keep it concise enough to be read early in a session.
+
+## Precedence
+
+1. Destination repository instructions
+2. This deployment profile
+3. Generic `AGENTS.md`, hubs, and skill files
+
+## How To Maintain This File
+
+- Fill out [PROJECT-PROFILE-WORKBOOK.md](./PROJECT-PROFILE-WORKBOOK.md) first.
+- Rewrite the answers here as agent-facing defaults, not as questions.
+- Prefer short, durable defaults over long policy prose.
+- Update this file when your preferred build, tool, or workflow defaults change materially.
+
+## Global Defaults
+
+- Optimize first for full-stack web application repositories.
+- Assume Windows and PowerShell for local development, but keep Docker and Linux deployment realities in mind.
+- Prefer compatibility-first tooling and standard stack defaults when multiple valid tools exist.
+- Favor Node and TypeScript for application work, while using Python when it is the best fit for tooling or automation.
+- Run the most relevant local tests for the changed area by default, and broaden verification for risky changes.
+- Ask clarifying questions before meaningful changes when product intent or risk is unclear.
+- Update documentation for meaningful changes, especially README content, Unraid install docs, roadmaps, and shipped or release-oriented summaries.
+- Hold user-facing work to a high polish bar by default.
+- Provide concise change summaries after meaningful work and call out rollout or migration impact when relevant.
+- Optimize hardest against regressions and broken behavior.
+
+## Software Development Defaults
+
+- Favor modular boundaries and cleaner separation early rather than waiting for severe pain.
+- Operate as a full-stack agent by default and work comfortably across frontend and backend.
+- Prefer mainstream modern patterns for the stack when multiple valid options exist.
+- Assume relational databases first unless the repository clearly indicates otherwise.
+- Be careful with schema and migration work, but do not overengineer small changes.
+- Prefer small, safe, frequent dependency upgrades with focused validation.
+- Treat performance as important early, especially on critical paths.
+- Apply a basic secure-defaults baseline: validate input, handle secrets safely, and respect auth boundaries.
+- Maintain good operational hygiene with meaningful logs and diagnostics on important paths, and add more for risky systems.
+- Use feature work as an opportunity for meaningful surrounding cleanup when the added refactoring clearly improves the change.
+
+## Debugging Defaults
+
+- Start with the fastest trustworthy signal rather than forcing a single debugging order.
+- Lean on logs and traces heavily before guessing.
+- During live or user-impacting incidents, stabilize first and diagnose more deeply after impact is reduced.
+- Prefer reversible mitigations such as rollbacks, flags, or partial disablement when risk is high.
+- Add regression tests for higher-risk or recurring bugs rather than treating every fix as a mandatory test addition.
+- Explain root cause clearly by connecting symptom, cause, and why the fix works.
+- Avoid temporary compromises unless there is no safer path.
+- Bundle observability improvements with medium or high-risk bug fixes when they would make future diagnosis easier.
+
+## Documentation Defaults
+
+- Treat documentation as part of most meaningful implementation work unless it is clearly unnecessary.
+- Default to practical onboarding that includes prerequisites, setup steps, validation, and common gotchas.
+- Create or update ADRs for major technical decisions and meaningful pattern shifts.
+- Write concise, audience-aware change summaries that call out user impact when relevant.
+- Maintain strong API and integration documentation by default for meaningful backend or interface work.
+- Prefer examples, snippets, and commands in places where they reduce ambiguity and improve adoption.
+- Update docs for any meaningful user-facing, setup, or team workflow change.
+- Bias toward concise documentation for reference material and more complete guidance for onboarding and operational content.
+
+## UI/UX Defaults
+
+- Prefer reuse of existing design-system components and patterns, but allow custom patterns when they clearly improve the experience.
+- Do not assume extra accessibility work by default beyond the repository or task requirements unless the task calls for it.
+- Design responsively for both desktop and mobile by default.
+- Reuse components when they fit well, and create new abstractions when they are likely to matter again.
+- Hold interface copy to a highly polished product-copy standard by default.
+- Use motion and visual flourish actively enough to make interfaces feel premium.
+- Bias toward bold, distinctive UI within reason rather than purely conservative continuity.
+- Treat UI work as incomplete until important states, copy quality, polish, and edge cases are addressed.
+
+## Marketing Defaults
+
+- Prioritize a mixed audience with a lean toward technical and product-savvy readers.
+- Use a premium, distinctive, and persuasive voice.
+- Keep marketing claims persuasive but grounded in real features and outcomes.
+- Default to a fuller launch kit when marketing work is requested: release notes, launch copy, landing page sections, and social or email variants as appropriate.
+- Balance launch messaging with evergreen discoverability, but do not let SEO weaken clarity.
+- Favor sharp, polished product copy with strong differentiation and clear calls to action.
+- Frame positioning conservatively around real value rather than aggressive comparative claims.
+- Prefer clear, action-oriented CTAs without heavy urgency.
+
+## Brainstorming Defaults
+
+- Favor breadth first when generating ideas.
+- Generate three options by default before recommending one.
+- Compare ideas primarily through user value, differentiation, and implementation realism.
+- Prioritize roadmap or opportunity choices through strategic fit, user value, and implementation cost.
+- Balance innovation with execution realism and require a believable path to implementation.
+- Use a short-to-medium horizon with practical sequencing for roadmap framing.
+- Turn brainstorming into a scoped implementation plan once a preferred option is selected.
+- Do not filter ideas out too early; raise concerns and explore alternatives that may offer more value before narrowing.

JARVIS.md

@@ -0,0 +1,71 @@
+# JARVIS — Just A Rather Very Intelligent System
+**Windows Port | Google Workspace Edition**
+
+A voice-activated AI assistant powered by FastAPI, Anthropic Claude, Fish Audio TTS, and OpenAI Whisper — integrated with the full Google Workspace suite.
+
+## Quick Start
+
+### 1. Prerequisites
+- Python 3.11+
+- Google Cloud project with OAuth credentials (`credentials.json`)
+- Anthropic API key
+- Fish Audio API key
+
+### 2. Install dependencies
+```bash
+python -m venv .venv
+.venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### 3. Configure environment
+```bash
+cp .env.example .env
+# Edit .env with your API keys
+```
+
+### 4. Google OAuth setup
+- Place your `credentials.json` from Google Cloud Console in the project root
+- On first run, a browser window will open for authorization
+- Token is saved to `token.json` automatically
+
+### 5. Run
+```bash
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### 6. Open dashboard
+Navigate to `http://localhost:8000` in Chrome.
+
+## Project Structure
+```
+jarvis-windows/
+├── main.py                    # FastAPI entrypoint
+├── requirements.txt
+├── .env.example
+├── .gitignore
+├── core/
+│   ├── google_auth.py         # Shared Google OAuth handler
+│   ├── voice_input.py         # Whisper STT
+│   ├── voice_output.py        # Fish Audio TTS
+│   ├── claude_agent.py        # Claude API + tool use
+│   └── websocket_manager.py   # WebSocket connection manager
+├── capabilities/
+│   ├── screen_vision.py       # mss + win32gui screen capture
+│   ├── calendar_access.py     # Google Calendar API
+│   ├── email_access.py        # Gmail API (read-only)
+│   ├── notes_manager.py       # Google Keep / gkeepapi
+│   ├── task_manager.py        # Google Tasks API
+│   ├── file_system.py         # os/pathlib file operations
+│   ├── terminal_control.py    # subprocess PowerShell/CMD
+│   ├── browser_control.py     # Selenium Chrome automation
+│   └── git_manager.py         # Git via subprocess
+├── utils/
+│   ├── audio_utils.py         # PyAudio helpers
+│   └── window_utils.py        # win32gui active window
+└── client/
+    └── jarvis-dashboard.html  # Animated Three.js frontend
+```
+
+## Roadmap
+See `ROADMAP.md`

PROJECT-PROFILE-WORKBOOK.md

@@ -0,0 +1,207 @@
+# Project Profile Workbook
+
+Fill out this workbook once before deployment when you want the suite to ship with pre-staged defaults for build, tools, environment, workflow, and quality preferences.
+
+This version has been completed and should act as the human-readable source behind [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md).
+
+## How To Use This Workbook
+
+- Keep answers concise and specific.
+- Prefer durable defaults over task-specific preferences.
+- If a question does not matter for your projects, write `No strong preference`.
+- If your answer depends on project type, note the default and the main exception.
+- Treat this workbook as the source for pre-deployment staging, not a runtime questionnaire.
+
+## Global Defaults
+
+### 1. What repository types should this suite optimize for by default?
+Answer: Full-stack web apps.
+
+### 2. What operating systems, shells, and local environments should the agent assume first?
+Answer: Windows and PowerShell for local development. Keep Linux, Docker, and Unraid deployment realities in mind.
+
+### 3. What package managers, build tools, and task runners should the agent prefer when multiple options exist?
+Answer: Compatibility-first defaults and standard stack tooling.
+
+### 4. Which languages, runtimes, or frameworks should get first-class preference across deployments?
+Answer: Node and TypeScript first for application work, with Python acceptable for tooling and automation.
+
+### 5. What is your default testing philosophy before considering work complete?
+Answer: Run the most relevant local tests for the changed area by default, and broaden verification for risky changes.
+
+### 6. How cautious should the agent be about asking questions versus making reasonable assumptions?
+Answer: Ask-first when product intent or change risk is unclear.
+
+### 7. What documentation should usually be updated when behavior, setup, or workflows change?
+Answer: Readmes, Unraid install docs, roadmaps, and shipped summaries are all important and should usually be updated when changes matter.
+
+### 8. What UX and polish bar should the suite assume for user-facing changes?
+Answer: High polish by default.
+
+### 9. What release, rollout, and communication expectations should be standard?
+Answer: Provide a concise change summary by default and note rollout or migration impact when relevant.
+
+### 10. What kinds of risk should the suite optimize hardest against?
+Answer: Regressions and broken behavior.
+
+## Software Development Defaults
+
+### 1. What architecture style or system design bias should be the default?
+Answer: Favor modular boundaries and cleaner separation early.
+
+### 2. How should the suite balance frontend, backend, and full-stack execution by default?
+Answer: Full-stack by default.
+
+### 3. Which frameworks, libraries, or implementation patterns should be preferred first?
+Answer: Prefer mainstream modern patterns for the stack.
+
+### 4. What database and persistence assumptions should the agent make?
+Answer: Relational database first.
+
+### 5. How conservative should migration and schema-change work be?
+Answer: Be careful, but do not overengineer small schema changes.
+
+### 6. What dependency upgrade strategy should be assumed?
+Answer: Prefer small, safe, frequent upgrades with focused validation.
+
+### 7. What performance bar should the suite assume by default?
+Answer: Be proactive about performance on critical paths.
+
+### 8. What minimum security baseline should be applied to code changes?
+Answer: Basic secure defaults only: validate input, handle secrets safely, and respect auth boundaries.
+
+### 9. What observability and operability expectations should be normal?
+Answer: Good operational hygiene with meaningful logs and diagnostics for important paths.
+
+### 10. How aggressive should the agent be about refactoring and technical debt reduction while doing feature work?
+Answer: Use feature work as an opportunity to improve surrounding structure meaningfully when it helps the change.
+
+## Debugging Defaults
+
+### 1. Should debugging start with reproduction first, code inspection first, or whichever is fastest to verify?
+Answer: Use whichever path gives the fastest trustworthy signal.
+
+### 2. What logs, traces, or diagnostics should the agent expect to consult before guessing?
+Answer: Lean on logs and traces first.
+
+### 3. How should the agent behave during live or user-impacting incidents?
+Answer: Stabilize first, then diagnose more deeply.
+
+### 4. What is the preferred rollback, mitigation, or feature-flag strategy when risk is high?
+Answer: Prefer reversible mitigations such as flags, rollbacks, or partial disablement.
+
+### 5. How strongly should the agent try to add or update tests when fixing bugs?
+Answer: Add tests for higher-risk or recurring bugs.
+
+### 6. What level of root-cause explanation should be standard after a fix?
+Answer: Clearly explain cause, symptom, and why the fix works.
+
+### 7. What tradeoffs are acceptable when stabilizing an issue quickly?
+Answer: Avoid temporary compromises unless there is no safer path.
+
+### 8. When should observability improvements be bundled with a bug fix?
+Answer: For most medium or high-risk bugs, add enough signal to help next time.
+
+## Documentation Defaults
+
+### 1. How strongly should the suite treat documentation as part of normal implementation work?
+Answer: Docs are part of most meaningful changes unless clearly unnecessary.
+
+### 2. What onboarding depth should be the default for new repos or contributor workflows?
+Answer: Practical onboarding with prerequisites, setup steps, validation, and common gotchas.
+
+### 3. When should architecture decision records be created or updated?
+Answer: For major decisions and meaningful pattern shifts.
+
+### 4. What release-note or change-summary style should be standard?
+Answer: Concise, audience-aware summaries with user impact called out when relevant.
+
+### 5. What level of API or integration documentation is expected by default?
+Answer: Strong API and integration documentation by default.
+
+### 6. How much should examples, snippets, or command samples be favored in docs?
+Answer: Prefer examples for setup, APIs, and workflows where ambiguity hurts adoption.
+
+### 7. What documentation updates should be mandatory after behavior or workflow changes?
+Answer: Update docs for any meaningful user-facing, setup, or team workflow change.
+
+### 8. What types of documentation should be concise versus comprehensive?
+Answer: Balanced. Keep reference content concise and onboarding or operational content more complete.
+
+## UI/UX Defaults
+
+### 1. How strict should design-system adherence be by default?
+Answer: Strong preference for reuse, but custom patterns are acceptable when they clearly improve the experience.
+
+### 2. What accessibility baseline should every user-facing change meet?
+Answer: Do not assume extra accessibility work by default unless requested.
+
+### 3. What responsive behavior should be assumed for new or updated UI?
+Answer: Responsive by default for desktop and mobile.
+
+### 4. How strongly should the agent favor component reuse over local implementation?
+Answer: Reuse when it fits well, and create new abstractions only when they are likely to matter again.
+
+### 5. What clarity and copy standards should be assumed for interface text?
+Answer: Highly polished product-copy quality by default.
+
+### 6. How much motion, animation, or visual flourish is appropriate by default?
+Answer: Use motion and flourish actively enough to make the interface feel premium.
+
+### 7. Should the suite bias toward bold, distinctive UI or conservative continuity with existing patterns?
+Answer: Bold and distinctive by default, within reason.
+
+### 8. How detailed should UI work be before it is considered ready?
+Answer: High completeness with strong state coverage, copy quality, polish, and edge-case handling.
+
+## Marketing Defaults
+
+### 1. Which audience should marketing and messaging defaults prioritize first?
+Answer: Mixed audience, leaning technical and product-savvy.
+
+### 2. What voice and tone should be the baseline?
+Answer: Premium, distinctive, and persuasive.
+
+### 3. What level of proof, specificity, or technical grounding should marketing claims include?
+Answer: Claims should be persuasive but grounded in real features and outcomes.
+
+### 4. What launch-content formats should be standard by default?
+Answer: Broader launch kit: release notes, launch copy, landing page sections, and social or email variants.
+
+### 5. How important is SEO and evergreen discoverability relative to launch messaging?
+Answer: Balance both, but do not let SEO weaken clarity.
+
+### 6. What product-copy style should be the default?
+Answer: Strong product-copy polish with sharper differentiation and CTA energy.
+
+### 7. How should the suite frame differentiation and positioning?
+Answer: Conservative positioning that focuses on real value rather than aggressive comparison.
+
+### 8. What types of calls to action should be preferred?
+Answer: Clear, action-oriented CTAs without heavy urgency.
+
+## Brainstorming Defaults
+
+### 1. Should idea generation favor breadth, speed, novelty, practicality, or a specific balance?
+Answer: Favor breadth first.
+
+### 2. How many options should the agent generate by default before recommending one?
+Answer: Three options by default.
+
+### 3. What criteria should be used most often to score or compare ideas?
+Answer: User value, differentiation, and implementation realism.
+
+### 4. What prioritization method should be the default for roadmap or opportunity choices?
+Answer: Strategic fit, user value, and implementation cost.
+
+### 5. How should innovation be balanced against implementation realism?
+Answer: Balanced, but require a believable path to execution.
+
+### 6. What kind of roadmap framing should be standard?
+Answer: Short-to-medium horizon with practical sequencing.
+
+### 7. When should brainstorming output turn into a scoped implementation plan?
+Answer: Usually after a preferred option is selected.
+
+### 8. What types of ideas should usually be filtered out early?
+Answer: Do not filter too early. Raise concerns and explore alternatives with more value before narrowing.

README.md

@@ -0,0 +1,47 @@
+# Drop-In Agent Instruction Suite
+
+This repository is a portable markdown instruction pack for coding agents.
+
+Copy these files into another repository to give the agent:
+- a root `AGENTS.md` entrypoint,
+- a central skill index,
+- category hubs for routing,
+- specialized skill files for common software, docs, UX, marketing, and ideation tasks.
+
+## Structure
+
+- `AGENTS.md` - base instructions and routing rules
+- `DEPLOYMENT-PROFILE.md` - agent-readable prefilled deployment defaults
+- `INSTALL.md` - copy and customization guide for other repositories
+- `PROJECT-PROFILE-WORKBOOK.md` - one-time questionnaire for staging defaults
+- `SKILLS.md` - canonical skill index
+- `ROUTING-EXAMPLES.md` - representative prompt-to-skill routing examples
+- `hubs/` - category-level routing guides
+- `skills/` - specialized reusable skill files
+
+## Design Goals
+
+- Plain markdown only
+- Cross-agent portability
+- Implementation-first defaults
+- On-demand skill loading instead of loading everything every session
+- Context-efficient routing for large skill libraries
+- Prefilled deployment defaults without per-install questioning
+- Repo-local instructions take precedence over this bundle
+
+## Intended Workflow
+
+1. The agent reads `AGENTS.md`.
+2. The agent reads `DEPLOYMENT-PROFILE.md` when it is filled in.
+3. The agent checks `SKILLS.md`.
+4. The agent opens only the relevant hub and skill files for the task.
+5. The agent combines multiple skills when the task spans several domains.
+
+## Core Categories
+
+- Software development
+- Debugging
+- Documentation
+- UI/UX
+- Marketing
+- Brainstorming

ROADMAP.md

@@ -0,0 +1,47 @@
+# JARVIS Windows — Project Roadmap
+
+## Phase 1 — Core Stack ✅ (Week 1)
+- [ ] FastAPI server with WebSocket endpoint
+- [ ] Whisper STT (base model, local)
+- [ ] Fish Audio TTS integration
+- [ ] Claude API connection
+- [ ] WebSocket manager (connect/disconnect/broadcast)
+- [ ] Basic end-to-end voice loop (speak → transcribe → Claude → respond)
+
+## Phase 2 — Google Workspace Integrations (Weeks 2–3)
+### 2a — Auth + Core Services
+- [ ] Google OAuth 2.0 setup (credentials.json → token.json)
+- [ ] Google Calendar: read today's events, upcoming schedule
+- [ ] Gmail: unread messages, search by sender/subject
+- [ ] Google Tasks: list pending, create, complete
+
+### 2b — Notes + Screen
+- [ ] Google Keep via gkeepapi (or Markdown fallback)
+- [ ] Screen vision: mss screenshot + win32gui active window
+- [ ] Window list enumeration
+
+### 2c — System Capabilities
+- [ ] Terminal control via subprocess (PowerShell + CMD)
+- [ ] File system: create projects, manage folders
+- [ ] Git status/operations via subprocess
+- [ ] Chrome automation via Selenium
+
+## Phase 3 — Claude Tool Use (Week 4)
+- [ ] Define tools manifest (all capabilities as function specs)
+- [ ] Tool dispatch router (route Claude tool_use to capability modules)
+- [ ] Multi-turn conversation with tool results
+- [ ] Error handling + tool fallbacks
+
+## Phase 4 — Dashboard + Packaging (Week 5)
+- [ ] Wire WebSocket to Three.js dashboard frontend
+- [ ] Live transcript display
+- [ ] State: idle / listening / processing / speaking
+- [ ] Windows startup registration (Task Scheduler)
+- [ ] .env validation on startup
+
+## Phase 5 — Optional Enhancements
+- [ ] Docker containerization (for Unraid or headless server)
+- [ ] Wake word detection ("Hey JARVIS")
+- [ ] Conversation history / memory across sessions
+- [ ] Google Drive file access
+- [ ] React/Electron desktop wrapper

ROUTING-EXAMPLES.md

@@ -0,0 +1,84 @@
+# Routing Examples
+
+Use these examples to validate that the suite routes clearly from `AGENTS.md` to the right hub files and specialized skills.
+
+In deployments with a filled-in [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md), the agent should read that file after `AGENTS.md` and before opening hubs or skills.
+
+## Representative Prompts
+
+### Fix a failing backend test and explain the root cause
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Debugging Hub](./hubs/debugging.md)
+- Use [Bug Triage](./skills/debugging/bug-triage.md)
+- Use [Debugging Workflow](./skills/debugging/debugging-workflow.md)
+- Add [API and Backend Work](./skills/software/api-backend.md)
+- Add [Test Strategy](./skills/software/test-strategy.md)
+
+### Build a new UI settings page with good UX and copy
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Software Development Hub](./hubs/software-development.md)
+- Use [Feature Implementation](./skills/software/feature-implementation.md)
+- Use [Frontend UI Implementation](./skills/software/frontend-ui-implementation.md)
+- Add [UI/UX Hub](./hubs/ui-ux.md)
+- Use [UX Review](./skills/ui-ux/ux-review.md)
+- Add [Product Copy](./skills/marketing/product-copy.md)
+
+### Write release notes and update onboarding docs for this feature
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Documentation Hub](./hubs/documentation.md)
+- Use [Release and Change Summary](./skills/software/release-change-summary.md)
+- Use [Onboarding Documentation](./skills/documentation/onboarding-docs.md)
+- Add [Technical Documentation](./skills/documentation/technical-docs.md) if setup or behavior changed
+
+### Brainstorm three product directions and turn the best one into a scoped implementation plan
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Brainstorming Hub](./hubs/brainstorming.md)
+- Use [Ideation](./skills/brainstorming/ideation.md)
+- Use [Structured Brainstorming](./skills/brainstorming/structured-brainstorming.md)
+- Add [Repository Exploration](./skills/software/repo-exploration.md) if the plan must align to an existing codebase
+- Add [Feature Implementation](./skills/software/feature-implementation.md) for implementation-ready shaping
+
+### Review this PR for bugs, regressions, and missing tests
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Software Development Hub](./hubs/software-development.md)
+- Use [Code Review](./skills/software/code-review.md)
+- Add [Test Strategy](./skills/software/test-strategy.md)
+
+### Draft launch messaging for a developer tool feature
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Marketing Hub](./hubs/marketing.md)
+- Use [Messaging and Positioning](./skills/marketing/messaging-positioning.md)
+- Use [Marketing Content](./skills/marketing/marketing-content.md)
+- Add [Technical Documentation](./skills/documentation/technical-docs.md) if claims need implementation-grounded detail
+
+### Plan a risky framework upgrade without derailing feature delivery
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Software Development Hub](./hubs/software-development.md)
+- Use [Dependency Lifecycle Management](./skills/software/dependency-lifecycle.md)
+- Add [Test Strategy](./skills/software/test-strategy.md)
+- Add [Maintenance and Technical Debt Planning](./skills/software/maintenance-technical-debt.md)
+- Add [Release and Change Summary](./skills/software/release-change-summary.md) if rollout communication matters
+
+### Respond to a live production issue and leave the system easier to diagnose next time
+
+- Start at [AGENTS.md](./AGENTS.md)
+- Read [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) if it is filled in
+- Open [Debugging Hub](./hubs/debugging.md)
+- Use [Incident Response and Stabilization](./skills/debugging/incident-response-stabilization.md)
+- Use [Debugging Workflow](./skills/debugging/debugging-workflow.md)
+- Add [Observability and Operability](./skills/software/observability-operability.md)
+- Add [Bug Triage](./skills/debugging/bug-triage.md) if reproduction or impact framing is still loose

SKILLS.md

@@ -0,0 +1,91 @@
+# Skill Index
+
+This file is the canonical registry for the instruction suite. Read this index after `AGENTS.md` and the deployment profile, then open only the hub and skill files needed for the current task.
+
+## Skill Contract
+
+Every skill file follows the same structure:
+- `Purpose`
+- `When to use`
+- `Inputs to gather`
+- `How to work`
+- `Output expectations`
+- `Quality checklist`
+- `Handoff notes`
+
+## Loading Guidance
+
+- If [DEPLOYMENT-PROFILE.md](./DEPLOYMENT-PROFILE.md) is filled in, treat it as the default preference layer before applying generic skill guidance.
+- Start narrow: one hub plus the smallest set of specialized skills that covers the task.
+- Typical task size: two to four skills.
+- Larger, cross-functional tasks may need four to six skills, but only when each one adds a distinct concern.
+- Prefer high-leverage skills that shape implementation quality over collecting adjacent but redundant guidance.
+- When in doubt, prioritize repository exploration, implementation/debugging, testing, and one domain-specific skill.
+
+## Category Hubs
+
+- [Software Development](./hubs/software-development.md)
+- [Debugging](./hubs/debugging.md)
+- [Documentation](./hubs/documentation.md)
+- [UI/UX](./hubs/ui-ux.md)
+- [Marketing](./hubs/marketing.md)
+- [Brainstorming](./hubs/brainstorming.md)
+
+## Specialized Skills
+
+### Software Development
+
+- [Architecture and System Design](./skills/software/architecture-system-design.md)
+- [Feature Implementation](./skills/software/feature-implementation.md)
+- [Refactoring](./skills/software/refactoring.md)
+- [Code Review](./skills/software/code-review.md)
+- [Test Strategy](./skills/software/test-strategy.md)
+- [API and Backend Work](./skills/software/api-backend.md)
+- [Database Migrations and Data Evolution](./skills/software/database-migrations.md)
+- [Dependency Lifecycle Management](./skills/software/dependency-lifecycle.md)
+- [Performance Optimization](./skills/software/performance-optimization.md)
+- [Security Review and Hardening](./skills/software/security-review-hardening.md)
+- [Observability and Operability](./skills/software/observability-operability.md)
+- [Maintenance and Technical Debt Planning](./skills/software/maintenance-technical-debt.md)
+- [Frontend UI Implementation](./skills/software/frontend-ui-implementation.md)
+- [Repository Exploration](./skills/software/repo-exploration.md)
+- [Release and Change Summary](./skills/software/release-change-summary.md)
+
+### Debugging
+
+- [Bug Triage](./skills/debugging/bug-triage.md)
+- [Debugging Workflow](./skills/debugging/debugging-workflow.md)
+- [Incident Response and Stabilization](./skills/debugging/incident-response-stabilization.md)
+
+### Documentation
+
+- [Architecture Decision Records](./skills/documentation/architecture-decision-records.md)
+- [Technical Documentation](./skills/documentation/technical-docs.md)
+- [Onboarding Documentation](./skills/documentation/onboarding-docs.md)
+
+### UI/UX
+
+- [UX Review](./skills/ui-ux/ux-review.md)
+- [Accessibility Review](./skills/ui-ux/accessibility-review.md)
+- [Design System and UI Consistency](./skills/ui-ux/design-system-consistency.md)
+
+### Marketing
+
+- [Product Copy](./skills/marketing/product-copy.md)
+- [Marketing Content](./skills/marketing/marketing-content.md)
+- [Messaging and Positioning](./skills/marketing/messaging-positioning.md)
+- [Content Strategy and SEO](./skills/marketing/content-strategy-seo.md)
+
+### Brainstorming
+
+- [Ideation](./skills/brainstorming/ideation.md)
+- [Structured Brainstorming](./skills/brainstorming/structured-brainstorming.md)
+- [Roadmap and Opportunity Prioritization](./skills/brainstorming/roadmap-opportunity-prioritization.md)
+
+## Quick Routing Hints
+
+- If the task changes code, start with the software development hub.
+- If the task starts from a defect, regression, failing test, or unclear breakage, add debugging skills.
+- If the task changes how people use, adopt, or understand the product, add documentation and possibly UX or marketing skills.
+- If the task asks for options, concepts, or strategic directions before execution, use brainstorming skills.
+- If the task affects long-term system health, look for architecture, security, performance, observability, dependency, or maintenance skills before loading more tactical ones.

capabilities/browser_control.py

@@ -0,0 +1,48 @@
+"""
+Chrome browser automation via Selenium.
+Selenium 4+ handles ChromeDriver automatically — no manual install needed.
+"""
+from selenium import webdriver
+from selenium.webdriver.chrome.options import Options
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support.ui import WebDriverWait
+from selenium.webdriver.support import expected_conditions as EC
+import urllib.parse
+
+_driver = None
+
+def _get_driver(headless: bool = False) -> webdriver.Chrome:
+    global _driver
+    if _driver is None:
+        options = Options()
+        if headless:
+            options.add_argument("--headless=new")
+        options.add_argument("--no-sandbox")
+        options.add_argument("--disable-dev-shm-usage")
+        _driver = webdriver.Chrome(options=options)
+    return _driver
+
+def navigate_to(url: str):
+    """Navigate Chrome to a URL."""
+    driver = _get_driver()
+    driver.get(url)
+    return driver.title
+
+def search_web(query: str):
+    """Perform a Google search in Chrome."""
+    encoded = urllib.parse.quote_plus(query)
+    return navigate_to(f"https://www.google.com/search?q={encoded}")
+
+def get_page_title() -> str:
+    driver = _get_driver()
+    return driver.title
+
+def get_page_url() -> str:
+    driver = _get_driver()
+    return driver.current_url
+
+def close_browser():
+    global _driver
+    if _driver:
+        _driver.quit()
+        _driver = None

capabilities/calendar_access.py

@@ -0,0 +1,61 @@
+"""
+Google Calendar API integration.
+Reads today's events and upcoming schedule.
+"""
+import datetime
+from googleapiclient.discovery import build
+from core.google_auth import get_credentials
+
+def _service():
+    return build('calendar', 'v3', credentials=get_credentials())
+
+def get_todays_events() -> list[dict]:
+    """Return all events happening today."""
+    now = datetime.datetime.now(tz=datetime.timezone.utc)
+    end = now.replace(hour=23, minute=59, second=59)
+    result = _service().events().list(
+        calendarId='primary',
+        timeMin=now.isoformat(),
+        timeMax=end.isoformat(),
+        singleEvents=True,
+        orderBy='startTime'
+    ).execute()
+    return [
+        {
+            'summary': e.get('summary', '(No title)'),
+            'start': e['start'].get('dateTime', e['start'].get('date')),
+            'end': e['end'].get('dateTime', e['end'].get('date')),
+            'location': e.get('location', ''),
+        }
+        for e in result.get('items', [])
+    ]
+
+def get_upcoming_events(days: int = 7) -> list[dict]:
+    """Return events in the next N days."""
+    now = datetime.datetime.now(tz=datetime.timezone.utc)
+    end = now + datetime.timedelta(days=days)
+    result = _service().events().list(
+        calendarId='primary',
+        timeMin=now.isoformat(),
+        timeMax=end.isoformat(),
+        maxResults=20,
+        singleEvents=True,
+        orderBy='startTime'
+    ).execute()
+    return [
+        {
+            'summary': e.get('summary', '(No title)'),
+            'start': e['start'].get('dateTime', e['start'].get('date')),
+        }
+        for e in result.get('items', [])
+    ]
+
+def create_event(summary: str, start_dt: str, end_dt: str, description: str = "") -> dict:
+    """Create a new calendar event. Dates in ISO 8601 format."""
+    event = {
+        'summary': summary,
+        'description': description,
+        'start': {'dateTime': start_dt, 'timeZone': 'America/Chicago'},
+        'end': {'dateTime': end_dt, 'timeZone': 'America/Chicago'},
+    }
+    return _service().events().insert(calendarId='primary', body=event).execute()

capabilities/email_access.py

@@ -0,0 +1,54 @@
+"""
+Gmail API integration — read-only access.
+Fetches unread messages and supports search queries.
+"""
+from googleapiclient.discovery import build
+from core.google_auth import get_credentials
+
+def _service():
+    return build('gmail', 'v1', credentials=get_credentials())
+
+def get_unread_emails(count: int = 10) -> list[dict]:
+    """Fetch the most recent unread emails."""
+    svc = _service()
+    result = svc.users().messages().list(
+        userId='me', q='is:unread', maxResults=count
+    ).execute()
+    messages = result.get('messages', [])
+    emails = []
+    for msg in messages:
+        detail = svc.users().messages().get(
+            userId='me', id=msg['id'], format='metadata',
+            metadataHeaders=['Subject', 'From', 'Date']
+        ).execute()
+        headers = {h['name']: h['value'] for h in detail['payload']['headers']}
+        emails.append({
+            'id': msg['id'],
+            'subject': headers.get('Subject', '(No subject)'),
+            'from': headers.get('From', ''),
+            'date': headers.get('Date', ''),
+            'snippet': detail.get('snippet', ''),
+        })
+    return emails
+
+def search_emails(query: str, count: int = 20) -> list[dict]:
+    """Search Gmail using standard Gmail search syntax."""
+    svc = _service()
+    result = svc.users().messages().list(
+        userId='me', q=query, maxResults=count
+    ).execute()
+    messages = result.get('messages', [])
+    emails = []
+    for msg in messages:
+        detail = svc.users().messages().get(
+            userId='me', id=msg['id'], format='metadata',
+            metadataHeaders=['Subject', 'From', 'Date']
+        ).execute()
+        headers = {h['name']: h['value'] for h in detail['payload']['headers']}
+        emails.append({
+            'id': msg['id'],
+            'subject': headers.get('Subject', '(No subject)'),
+            'from': headers.get('From', ''),
+            'snippet': detail.get('snippet', ''),
+        })
+    return emails

capabilities/file_system.py

@@ -0,0 +1,43 @@
+"""
+File system operations — create projects, manage folders, list files.
+Cross-platform: uses pathlib and os only.
+"""
+import os
+import subprocess
+from pathlib import Path
+
+def create_project(name: str, base_path: str = "C:/Projects") -> str:
+    """Create a new project folder with README and .gitignore."""
+    path = Path(base_path) / name
+    path.mkdir(parents=True, exist_ok=True)
+    (path / "README.md").write_text(f"# {name}\n\nProject created by JARVIS.\n")
+    (path / ".gitignore").write_text("__pycache__/\n.env\n*.pyc\n")
+    return str(path)
+
+def list_directory(path: str) -> list[dict]:
+    """List files and folders in a directory."""
+    p = Path(path)
+    if not p.exists():
+        return []
+    return [
+        {'name': item.name, 'type': 'dir' if item.is_dir() else 'file', 'size': item.stat().st_size if item.is_file() else None}
+        for item in sorted(p.iterdir())
+    ]
+
+def read_file(path: str) -> str:
+    """Read the contents of a text file."""
+    return Path(path).read_text(encoding='utf-8')
+
+def write_file(path: str, content: str):
+    """Write content to a file, creating parent directories if needed."""
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(content, encoding='utf-8')
+
+def delete_file(path: str):
+    """Delete a file."""
+    Path(path).unlink(missing_ok=True)
+
+def open_folder(path: str):
+    """Open a folder in Windows Explorer."""
+    os.startfile(path)

capabilities/git_manager.py

@@ -0,0 +1,39 @@
+"""
+Git operations via subprocess.
+Wraps common git commands for use by JARVIS.
+"""
+import subprocess
+from pathlib import Path
+
+def _git(path: str, *args) -> dict:
+    result = subprocess.run(
+        ["git", *args], cwd=path, capture_output=True, text=True
+    )
+    return {
+        "stdout": result.stdout.strip(),
+        "stderr": result.stderr.strip(),
+        "returncode": result.returncode
+    }
+
+def get_git_status(path: str) -> str:
+    return _git(path, "status")["stdout"]
+
+def get_git_log(path: str, count: int = 5) -> str:
+    return _git(path, "log", f"--oneline", f"-{count}")["stdout"]
+
+def git_diff(path: str) -> str:
+    return _git(path, "diff")["stdout"]
+
+def git_pull(path: str) -> dict:
+    return _git(path, "pull")
+
+def git_add_commit(path: str, message: str) -> dict:
+    _git(path, "add", "-A")
+    return _git(path, "commit", "-m", message)
+
+def git_push(path: str) -> dict:
+    return _git(path, "push")
+
+def list_branches(path: str) -> list[str]:
+    result = _git(path, "branch", "-a")
+    return [b.strip().lstrip("* ") for b in result["stdout"].splitlines() if b.strip()]

capabilities/notes_manager.py

@@ -0,0 +1,68 @@
+"""
+Google Keep notes via gkeepapi (unofficial).
+Falls back to local Markdown files if Keep is unavailable.
+
+NOTE: The official Google Keep API requires Google Workspace Enterprise.
+For personal/standard accounts use gkeepapi or the Markdown fallback below.
+"""
+import os
+from pathlib import Path
+
+# ─── gkeepapi backend ──────────────────────────
+try:
+    import gkeepapi
+    _keep = None
+
+    def _init():
+        global _keep
+        if _keep is None:
+            email = os.getenv("GOOGLE_KEEP_EMAIL")
+            token = os.getenv("GOOGLE_KEEP_MASTER_TOKEN")
+            if not email or not token:
+                raise ValueError("Set GOOGLE_KEEP_EMAIL and GOOGLE_KEEP_MASTER_TOKEN in .env")
+            _keep = gkeepapi.Keep()
+            _keep.authenticate(email, token)
+        return _keep
+
+    def create_note(title: str, content: str) -> str:
+        keep = _init()
+        note = keep.createNote(title, content)
+        note.pinned = True
+        keep.sync()
+        return note.id
+
+    def get_all_notes() -> list[dict]:
+        keep = _init()
+        return [{'id': n.id, 'title': n.title, 'text': n.text} for n in keep.all()]
+
+    def search_notes(query: str) -> list[dict]:
+        keep = _init()
+        return [{'id': n.id, 'title': n.title, 'text': n.text} for n in keep.find(query=query)]
+
+    NOTES_BACKEND = "gkeepapi"
+
+except ImportError:
+    # ─── Markdown fallback ──────────────────────
+    NOTES_DIR = Path.home() / "JARVIS_Notes"
+    NOTES_DIR.mkdir(exist_ok=True)
+    NOTES_BACKEND = "markdown"
+
+    def create_note(title: str, content: str) -> str:
+        safe_title = "".join(c for c in title if c.isalnum() or c in " _-").strip()
+        path = NOTES_DIR / f"{safe_title}.md"
+        path.write_text(f"# {title}\n\n{content}\n")
+        return str(path)
+
+    def get_all_notes() -> list[dict]:
+        return [
+            {'title': p.stem, 'text': p.read_text()}
+            for p in NOTES_DIR.glob("*.md")
+        ]
+
+    def search_notes(query: str) -> list[dict]:
+        results = []
+        for p in NOTES_DIR.glob("*.md"):
+            text = p.read_text()
+            if query.lower() in text.lower():
+                results.append({'title': p.stem, 'text': text})
+        return results

capabilities/screen_vision.py

@@ -0,0 +1,48 @@
+"""
+Screen vision — captures screenshots and identifies active/open windows.
+Uses mss for fast capture and win32gui for window enumeration.
+"""
+import mss
+import base64
+import io
+from PIL import Image
+
+try:
+    import win32gui
+    WIN32_AVAILABLE = True
+except ImportError:
+    WIN32_AVAILABLE = False
+    print("[JARVIS] pywin32 not available — window detection disabled")
+
+def get_active_window_title() -> str:
+    if WIN32_AVAILABLE:
+        return win32gui.GetWindowText(win32gui.GetForegroundWindow())
+    return "Unknown"
+
+def list_open_windows() -> list[str]:
+    if not WIN32_AVAILABLE:
+        return []
+    windows = []
+    def _enum(hwnd, _):
+        if win32gui.IsWindowVisible(hwnd):
+            title = win32gui.GetWindowText(hwnd)
+            if title:
+                windows.append(title)
+    win32gui.EnumWindows(_enum, None)
+    return windows
+
+def capture_screen() -> str:
+    """Returns base64-encoded PNG of the primary monitor."""
+    with mss.mss() as sct:
+        monitor = sct.monitors[1]
+        img = sct.grab(monitor)
+        pil_img = Image.frombytes("RGB", img.size, img.bgra, "raw", "BGRX")
+        buffer = io.BytesIO()
+        pil_img.save(buffer, format="PNG")
+        return base64.b64encode(buffer.getvalue()).decode()
+
+def capture_screen_file(path: str = "screenshot.png") -> str:
+    """Saves screenshot to file and returns the path."""
+    with mss.mss() as sct:
+        sct.shot(mon=1, output=path)
+    return path

capabilities/task_manager.py

@@ -0,0 +1,56 @@
+"""
+Google Tasks API integration.
+List, create, and complete tasks across all task lists.
+"""
+from googleapiclient.discovery import build
+from core.google_auth import get_credentials
+
+def _service():
+    return build('tasks', 'v1', credentials=get_credentials())
+
+def _get_default_list_id() -> str:
+    svc = _service()
+    lists = svc.tasklists().list(maxResults=1).execute()
+    return lists['items'][0]['id']
+
+def get_pending_tasks() -> list[dict]:
+    """Return all incomplete tasks across all task lists."""
+    svc = _service()
+    tasklists = svc.tasklists().list(maxResults=10).execute()
+    all_tasks = []
+    for tl in tasklists.get('items', []):
+        tasks = svc.tasks().list(
+            tasklist=tl['id'], showCompleted=False, maxResults=50
+        ).execute()
+        for t in tasks.get('items', []):
+            all_tasks.append({
+                'id': t['id'],
+                'tasklist_id': tl['id'],
+                'title': t.get('title', ''),
+                'due': t.get('due', ''),
+                'notes': t.get('notes', ''),
+                'list': tl['title'],
+            })
+    return all_tasks
+
+def create_task(title: str, notes: str = None, due: str = None) -> dict:
+    """Create a new task in the default task list."""
+    svc = _service()
+    list_id = _get_default_list_id()
+    body = {'title': title}
+    if notes:
+        body['notes'] = notes
+    if due:
+        body['due'] = due
+    return svc.tasks().insert(tasklist=list_id, body=body).execute()
+
+def complete_task(tasklist_id: str, task_id: str) -> dict:
+    """Mark a task as completed."""
+    svc = _service()
+    task = svc.tasks().get(tasklist=tasklist_id, task=task_id).execute()
+    task['status'] = 'completed'
+    return svc.tasks().update(tasklist=tasklist_id, task=task_id, body=task).execute()
+
+def delete_task(tasklist_id: str, task_id: str):
+    """Delete a task permanently."""
+    _service().tasks().delete(tasklist=tasklist_id, task=task_id).execute()

capabilities/terminal_control.py

@@ -0,0 +1,41 @@
+"""
+Terminal control — runs PowerShell and CMD commands via subprocess.
+Opens Windows Terminal at a given path.
+"""
+import subprocess
+import os
+
+def run_powershell(command: str, timeout: int = 30) -> dict:
+    """Execute a PowerShell command and return stdout/stderr."""
+    result = subprocess.run(
+        ["powershell", "-ExecutionPolicy", "Bypass", "-NonInteractive", "-Command", command],
+        capture_output=True, text=True, timeout=timeout
+    )
+    return {
+        "stdout": result.stdout.strip(),
+        "stderr": result.stderr.strip(),
+        "returncode": result.returncode
+    }
+
+def run_cmd(command: str, timeout: int = 30) -> dict:
+    """Execute a CMD command."""
+    result = subprocess.run(
+        ["cmd", "/c", command],
+        capture_output=True, text=True, timeout=timeout
+    )
+    return {
+        "stdout": result.stdout.strip(),
+        "stderr": result.stderr.strip(),
+        "returncode": result.returncode
+    }
+
+def open_terminal(path: str = None):
+    """Open Windows Terminal at the given directory."""
+    cmd = ["wt"]
+    if path:
+        cmd += ["-d", path]
+    subprocess.Popen(cmd)
+
+def open_vscode(path: str):
+    """Open VS Code at a given path."""
+    subprocess.Popen(["code", path])

client/jarvis-dashboard.html

@@ -0,0 +1,902 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="dark">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>JARVIS</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Orbitron:wght@400;700;900&family=Inter:wght@300;400;500&display=swap" rel="stylesheet">
+<script src="https://cdnjs.cloudflare.com/ajax/libs/three.js/r134/three.min.js"></script>
+<style>
+:root {
+  --font-display: 'Orbitron', monospace;
+  --font-body: 'Inter', sans-serif;
+  --text-xs: clamp(0.65rem, 0.6rem + 0.2vw, 0.75rem);
+  --text-sm: clamp(0.75rem, 0.7rem + 0.25vw, 0.875rem);
+  --text-base: clamp(0.875rem, 0.8rem + 0.3vw, 1rem);
+  --text-lg: clamp(1rem, 0.9rem + 0.5vw, 1.25rem);
+  --text-xl: clamp(1.25rem, 1rem + 1vw, 1.75rem);
+  --space-1: 0.25rem; --space-2: 0.5rem; --space-3: 0.75rem;
+  --space-4: 1rem; --space-5: 1.25rem; --space-6: 1.5rem;
+  --space-8: 2rem; --space-10: 2.5rem; --space-12: 3rem;
+  --radius-sm: 4px; --radius-md: 8px; --radius-lg: 12px; --radius-xl: 16px; --radius-full: 9999px;
+  --transition: 200ms cubic-bezier(0.16, 1, 0.3, 1);
+
+  --color-bg: #0a0a0c;
+  --color-surface: #0f0f14;
+  --color-surface-2: #14141a;
+  --color-border: rgba(120,180,255,0.08);
+  --color-text: #c8d4e8;
+  --color-text-muted: #6a7a94;
+  --color-text-faint: #3a4a5e;
+  --color-accent: #4f9eff;
+  --color-accent-2: #a78bfa;
+  --color-accent-gold: #f5c842;
+  --color-accent-green: #34d399;
+  --color-accent-orange: #fb923c;
+  --glow-blue: rgba(79,158,255,0.15);
+  --glow-purple: rgba(167,139,250,0.12);
+}
+
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+html { -webkit-font-smoothing: antialiased; scroll-behavior: smooth; }
+
+body {
+  font-family: var(--font-body);
+  background: var(--color-bg);
+  color: var(--color-text);
+  min-height: 100dvh;
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+}
+
+/* ─── Canvas ─────────────────────────────── */
+#orb-canvas {
+  position: fixed;
+  inset: 0;
+  z-index: 0;
+  pointer-events: none;
+}
+
+/* ─── Layout ─────────────────────────────── */
+.app {
+  position: relative;
+  z-index: 10;
+  display: grid;
+  grid-template-rows: auto 1fr auto;
+  height: 100dvh;
+  padding: var(--space-4);
+  gap: var(--space-4);
+}
+
+/* ─── Header ─────────────────────────────── */
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--space-3) var(--space-5);
+  background: rgba(15,15,20,0.6);
+  backdrop-filter: blur(20px);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-xl);
+}
+
+.logo {
+  font-family: var(--font-display);
+  font-size: var(--text-lg);
+  font-weight: 700;
+  letter-spacing: 0.2em;
+  color: var(--color-accent);
+  text-shadow: 0 0 20px rgba(79,158,255,0.5);
+}
+
+.logo span {
+  font-size: var(--text-xs);
+  display: block;
+  color: var(--color-text-muted);
+  letter-spacing: 0.3em;
+  font-weight: 400;
+  margin-top: 1px;
+}
+
+.header-status {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+.status-dot {
+  width: 8px; height: 8px;
+  border-radius: var(--radius-full);
+  background: var(--color-accent-green);
+  box-shadow: 0 0 8px var(--color-accent-green);
+  animation: pulse-dot 2s ease-in-out infinite;
+}
+
+@keyframes pulse-dot {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50% { opacity: 0.6; transform: scale(0.85); }
+}
+
+.status-label {
+  font-size: var(--text-xs);
+  color: var(--color-text-muted);
+  font-family: var(--font-display);
+  letter-spacing: 0.15em;
+  text-transform: uppercase;
+}
+
+.header-time {
+  font-family: var(--font-display);
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+  letter-spacing: 0.1em;
+  text-align: right;
+}
+.header-time .date {
+  font-size: var(--text-xs);
+  color: var(--color-text-faint);
+  margin-top: 2px;
+}
+
+/* ─── Main body ────────────────────────────── */
+.main {
+  display: grid;
+  grid-template-columns: 200px 1fr 200px;
+  gap: var(--space-4);
+  align-items: stretch;
+}
+
+/* ─── Side panels ─────────────────────────── */
+.panel {
+  background: rgba(15,15,20,0.55);
+  backdrop-filter: blur(20px);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-xl);
+  padding: var(--space-4);
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
+
+.panel-title {
+  font-family: var(--font-display);
+  font-size: var(--text-xs);
+  letter-spacing: 0.2em;
+  text-transform: uppercase;
+  color: var(--color-accent);
+  padding-bottom: var(--space-2);
+  border-bottom: 1px solid var(--color-border);
+  opacity: 0.8;
+}
+
+.panel-item {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.panel-item-label {
+  font-size: var(--text-xs);
+  color: var(--color-text-faint);
+  letter-spacing: 0.1em;
+}
+
+.panel-item-value {
+  font-family: var(--font-display);
+  font-size: var(--text-sm);
+  color: var(--color-text);
+}
+
+.panel-item-value.accent { color: var(--color-accent); }
+.panel-item-value.green { color: var(--color-accent-green); }
+.panel-item-value.gold { color: var(--color-accent-gold); }
+.panel-item-value.purple { color: var(--color-accent-2); }
+
+.capability-chip {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1) var(--space-2);
+  border-radius: var(--radius-full);
+  background: rgba(79,158,255,0.06);
+  border: 1px solid rgba(79,158,255,0.12);
+  font-size: var(--text-xs);
+  color: var(--color-text-muted);
+  letter-spacing: 0.05em;
+  transition: all var(--transition);
+}
+
+.capability-chip .dot {
+  width: 5px; height: 5px;
+  border-radius: var(--radius-full);
+  background: var(--color-text-faint);
+  flex-shrink: 0;
+}
+
+.capability-chip.active .dot { background: var(--color-accent-green); box-shadow: 0 0 6px var(--color-accent-green); }
+.capability-chip.active { color: var(--color-text); border-color: rgba(52,211,153,0.2); background: rgba(52,211,153,0.04); }
+
+/* ─── Orb Center ──────────────────────────── */
+.orb-center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-4);
+  position: relative;
+}
+
+.orb-status-text {
+  font-family: var(--font-display);
+  font-size: var(--text-base);
+  letter-spacing: 0.3em;
+  text-transform: uppercase;
+  color: var(--color-accent);
+  text-shadow: 0 0 20px rgba(79,158,255,0.4);
+  text-align: center;
+  min-height: 1.5em;
+  transition: opacity 0.4s ease;
+}
+
+.orb-subtitle {
+  font-size: var(--text-xs);
+  color: var(--color-text-faint);
+  letter-spacing: 0.25em;
+  text-transform: uppercase;
+  text-align: center;
+}
+
+/* Audio waveform bars (idle animation) */
+.waveform {
+  display: flex;
+  align-items: center;
+  gap: 3px;
+  height: 40px;
+  opacity: 0;
+  transition: opacity 0.4s ease;
+}
+.waveform.active { opacity: 1; }
+.waveform .bar {
+  width: 3px;
+  border-radius: var(--radius-full);
+  background: var(--color-accent);
+  box-shadow: 0 0 6px var(--color-accent);
+  animation: wave-bar 1.2s ease-in-out infinite;
+}
+.waveform .bar:nth-child(1) { animation-delay: 0ms; }
+.waveform .bar:nth-child(2) { animation-delay: 80ms; }
+.waveform .bar:nth-child(3) { animation-delay: 160ms; }
+.waveform .bar:nth-child(4) { animation-delay: 240ms; }
+.waveform .bar:nth-child(5) { animation-delay: 320ms; }
+.waveform .bar:nth-child(6) { animation-delay: 400ms; }
+.waveform .bar:nth-child(7) { animation-delay: 320ms; }
+.waveform .bar:nth-child(8) { animation-delay: 240ms; }
+.waveform .bar:nth-child(9) { animation-delay: 160ms; }
+.waveform .bar:nth-child(10) { animation-delay: 80ms; }
+.waveform .bar:nth-child(11) { animation-delay: 0ms; }
+
+@keyframes wave-bar {
+  0%, 100% { height: 6px; opacity: 0.3; }
+  50% { height: 32px; opacity: 1; }
+}
+
+/* ─── Footer / Input Bar ─────────────────── */
+.footer {
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  padding: var(--space-3) var(--space-5);
+  background: rgba(15,15,20,0.6);
+  backdrop-filter: blur(20px);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-xl);
+}
+
+.transcript-display {
+  flex: 1;
+  font-family: var(--font-display);
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+  letter-spacing: 0.05em;
+  min-height: 1.4em;
+  transition: color 0.3s ease;
+}
+
+.transcript-display.speaking { color: var(--color-text); }
+
+.mic-btn {
+  width: 48px; height: 48px;
+  border-radius: var(--radius-full);
+  border: 1px solid rgba(79,158,255,0.3);
+  background: rgba(79,158,255,0.08);
+  cursor: pointer;
+  display: flex; align-items: center; justify-content: center;
+  transition: all var(--transition);
+  position: relative;
+  flex-shrink: 0;
+}
+
+.mic-btn:hover {
+  background: rgba(79,158,255,0.15);
+  border-color: rgba(79,158,255,0.5);
+  box-shadow: 0 0 20px rgba(79,158,255,0.2);
+}
+
+.mic-btn.recording {
+  background: rgba(251,146,60,0.15);
+  border-color: rgba(251,146,60,0.5);
+  box-shadow: 0 0 24px rgba(251,146,60,0.3);
+  animation: mic-pulse 1s ease-in-out infinite;
+}
+
+@keyframes mic-pulse {
+  0%, 100% { box-shadow: 0 0 20px rgba(251,146,60,0.3); }
+  50% { box-shadow: 0 0 40px rgba(251,146,60,0.5); }
+}
+
+.mic-btn svg { pointer-events: none; }
+
+.close-btn {
+  width: 40px; height: 40px;
+  border-radius: var(--radius-full);
+  border: 1px solid var(--color-border);
+  background: transparent;
+  cursor: pointer;
+  display: flex; align-items: center; justify-content: center;
+  color: var(--color-text-faint);
+  transition: all var(--transition);
+  flex-shrink: 0;
+}
+.close-btn:hover { color: var(--color-text-muted); border-color: rgba(255,255,255,0.15); }
+
+/* ─── Response output ─────────────────────── */
+.response-panel {
+  position: fixed;
+  bottom: 100px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: min(600px, calc(100vw - 2rem));
+  background: rgba(15,15,20,0.85);
+  backdrop-filter: blur(24px);
+  border: 1px solid rgba(79,158,255,0.15);
+  border-radius: var(--radius-xl);
+  padding: var(--space-5);
+  z-index: 50;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.4s ease, transform 0.4s cubic-bezier(0.16,1,0.3,1);
+  transform: translateX(-50%) translateY(10px);
+}
+
+.response-panel.visible {
+  opacity: 1;
+  pointer-events: auto;
+  transform: translateX(-50%) translateY(0);
+}
+
+.response-label {
+  font-family: var(--font-display);
+  font-size: var(--text-xs);
+  color: var(--color-accent);
+  letter-spacing: 0.2em;
+  margin-bottom: var(--space-3);
+  text-transform: uppercase;
+}
+
+.response-text {
+  font-size: var(--text-base);
+  color: var(--color-text);
+  line-height: 1.7;
+}
+
+/* ─── Scrollable transcript log ──────────── */
+.log-panel {
+  position: fixed;
+  right: var(--space-4);
+  top: 50%;
+  transform: translateY(-50%);
+  width: 220px;
+  max-height: 60vh;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  z-index: 30;
+  padding: var(--space-3);
+  background: rgba(15,15,20,0.5);
+  backdrop-filter: blur(16px);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-xl);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.3s;
+}
+
+.log-entry {
+  font-size: var(--text-xs);
+  padding: var(--space-2) var(--space-3);
+  border-radius: var(--radius-md);
+  line-height: 1.5;
+}
+
+.log-entry.user { background: rgba(79,158,255,0.08); color: var(--color-accent); }
+.log-entry.assistant { background: rgba(167,139,250,0.08); color: var(--color-accent-2); }
+
+/* ─── Background grid ─────────────────────── */
+.bg-grid {
+  position: fixed;
+  inset: 0;
+  z-index: 1;
+  pointer-events: none;
+  background-image:
+    linear-gradient(rgba(79,158,255,0.025) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(79,158,255,0.025) 1px, transparent 1px);
+  background-size: 60px 60px;
+  mask-image: radial-gradient(ellipse 70% 70% at 50% 50%, black, transparent);
+}
+
+/* ─── Horizon glow ─────────────────────────── */
+.horizon-glow {
+  position: fixed;
+  bottom: -80px;
+  left: 50%;
+  transform: translateX(-50%);
+  width: 80vw;
+  height: 200px;
+  background: radial-gradient(ellipse at 50% 100%, rgba(79,158,255,0.06), transparent 70%);
+  pointer-events: none;
+  z-index: 2;
+}
+
+/* ─── Scanning ring ────────────────────────── */
+.scan-ring {
+  position: absolute;
+  width: 320px; height: 320px;
+  border-radius: var(--radius-full);
+  border: 1px solid rgba(79,158,255,0.06);
+  animation: scan-rotate 20s linear infinite;
+  pointer-events: none;
+}
+.scan-ring::after {
+  content: '';
+  position: absolute;
+  top: -1px; left: 20%;
+  width: 30%; height: 1px;
+  background: linear-gradient(90deg, transparent, rgba(79,158,255,0.4), transparent);
+}
+.scan-ring-2 {
+  width: 280px; height: 280px;
+  animation-duration: 15s;
+  animation-direction: reverse;
+  border-color: rgba(167,139,250,0.05);
+}
+
+@keyframes scan-rotate { to { transform: rotate(360deg); } }
+
+/* ─── Scrollbar ────────────────────────────── */
+::-webkit-scrollbar { width: 4px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: var(--color-border); border-radius: var(--radius-full); }
+</style>
+</head>
+<body>
+<canvas id="orb-canvas"></canvas>
+<div class="bg-grid"></div>
+<div class="horizon-glow"></div>
+
+<div class="app">
+  <!-- Header -->
+  <header class="header">
+    <div class="logo">
+      JARVIS
+      <span>Just A Rather Very Intelligent System</span>
+    </div>
+    <div class="header-status">
+      <div class="status-dot"></div>
+      <div class="status-label" id="sys-status">Online</div>
+    </div>
+    <div class="header-time">
+      <div id="clock">--:--:--</div>
+      <div class="date" id="date-label">---</div>
+    </div>
+  </header>
+
+  <!-- Main -->
+  <main class="main">
+    <!-- Left panel -->
+    <aside class="panel">
+      <div class="panel-title">System</div>
+      <div class="panel-item">
+        <div class="panel-item-label">Backend</div>
+        <div class="panel-item-value accent">FastAPI</div>
+      </div>
+      <div class="panel-item">
+        <div class="panel-item-label">Voice Engine</div>
+        <div class="panel-item-value green">Fish Audio TTS</div>
+      </div>
+      <div class="panel-item">
+        <div class="panel-item-label">Intelligence</div>
+        <div class="panel-item-value purple">Claude API</div>
+      </div>
+      <div class="panel-item">
+        <div class="panel-item-label">STT Model</div>
+        <div class="panel-item-value">Whisper Base</div>
+      </div>
+      <div class="panel-item">
+        <div class="panel-item-label">Transport</div>
+        <div class="panel-item-value">WebSocket</div>
+      </div>
+      <div class="panel-item">
+        <div class="panel-item-label">Workspace</div>
+        <div class="panel-item-value gold">Google Suite</div>
+      </div>
+    </aside>
+
+    <!-- Center orb -->
+    <div class="orb-center">
+      <div class="scan-ring"></div>
+      <div class="scan-ring scan-ring-2"></div>
+      <div class="orb-status-text" id="orb-text">STANDBY</div>
+      <div class="waveform" id="waveform">
+        <div class="bar"></div><div class="bar"></div><div class="bar"></div>
+        <div class="bar"></div><div class="bar"></div><div class="bar"></div>
+        <div class="bar"></div><div class="bar"></div><div class="bar"></div>
+        <div class="bar"></div><div class="bar"></div>
+      </div>
+      <div class="orb-subtitle" id="orb-subtitle">Tap microphone to speak</div>
+    </div>
+
+    <!-- Right panel -->
+    <aside class="panel">
+      <div class="panel-title">Capabilities</div>
+      <div class="capability-chip active"><div class="dot"></div>Screen Vision</div>
+      <div class="capability-chip active"><div class="dot"></div>Gmail</div>
+      <div class="capability-chip active"><div class="dot"></div>Calendar</div>
+      <div class="capability-chip active"><div class="dot"></div>G. Tasks</div>
+      <div class="capability-chip active"><div class="dot"></div>G. Keep</div>
+      <div class="capability-chip active"><div class="dot"></div>Google Drive</div>
+      <div class="capability-chip active"><div class="dot"></div>Terminal</div>
+      <div class="capability-chip active"><div class="dot"></div>Chrome</div>
+      <div class="capability-chip active"><div class="dot"></div>VS Code</div>
+      <div class="capability-chip active"><div class="dot"></div>Git</div>
+    </aside>
+  </main>
+
+  <!-- Footer input bar -->
+  <footer class="footer">
+    <button class="close-btn" title="Clear" onclick="clearSession()">
+      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>
+    </button>
+    <div class="transcript-display" id="transcript">Say something&hellip;</div>
+    <button class="mic-btn" id="mic-btn" title="Hold to speak" onclick="toggleMic()">
+      <svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <path d="M12 2a3 3 0 0 1 3 3v7a3 3 0 0 1-6 0V5a3 3 0 0 1 3-3z"/>
+        <path d="M19 10v2a7 7 0 0 1-14 0v-2"/>
+        <line x1="12" y1="19" x2="12" y2="22"/>
+        <line x1="8" y1="22" x2="16" y2="22"/>
+      </svg>
+    </button>
+  </footer>
+</div>
+
+<!-- Response panel -->
+<div class="response-panel" id="response-panel">
+  <div class="response-label">JARVIS Response</div>
+  <div class="response-text" id="response-text"></div>
+</div>
+
+<script type="module">
+// ─── Clock ────────────────────────────────────────
+function updateClock() {
+  const now = new Date();
+  document.getElementById('clock').textContent = now.toLocaleTimeString('en-US', { hour12: false });
+  document.getElementById('date-label').textContent = now.toLocaleDateString('en-US', { weekday: 'short', month: 'short', day: 'numeric' });
+}
+updateClock();
+setInterval(updateClock, 1000);
+
+// ─── Three.js Particle Orb ─────────────────────────
+const canvas = document.getElementById('orb-canvas');
+const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true });
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+renderer.setSize(window.innerWidth, window.innerHeight);
+renderer.setClearColor(0x000000, 0);
+
+const scene = new THREE.Scene();
+const camera = new THREE.PerspectiveCamera(60, window.innerWidth / window.innerHeight, 0.1, 100);
+camera.position.z = 3.2;
+
+const PARTICLE_COUNT = 4000;
+const geometry = new THREE.BufferGeometry();
+const positions = new Float32Array(PARTICLE_COUNT * 3);
+const colors = new Float32Array(PARTICLE_COUNT * 3);
+const sizes = new Float32Array(PARTICLE_COUNT);
+const originalPositions = new Float32Array(PARTICLE_COUNT * 3);
+const velocities = new Float32Array(PARTICLE_COUNT * 3);
+
+// Distribute particles on sphere surface using Fibonacci sphere
+for (let i = 0; i < PARTICLE_COUNT; i++) {
+  const goldenAngle = Math.PI * (3 - Math.sqrt(5));
+  const theta = goldenAngle * i;
+  const y = 1 - (i / (PARTICLE_COUNT - 1)) * 2;
+  const radius = Math.sqrt(1 - y * y);
+  const r = 1.0 + (Math.random() - 0.5) * 0.25;
+
+  const x = Math.cos(theta) * radius * r;
+  const z = Math.sin(theta) * radius * r;
+  const yr = y * r;
+
+  positions[i * 3] = x;
+  positions[i * 3 + 1] = yr;
+  positions[i * 3 + 2] = z;
+  originalPositions[i * 3] = x;
+  originalPositions[i * 3 + 1] = yr;
+  originalPositions[i * 3 + 2] = z;
+
+  velocities[i * 3] = (Math.random() - 0.5) * 0.002;
+  velocities[i * 3 + 1] = (Math.random() - 0.5) * 0.002;
+  velocities[i * 3 + 2] = (Math.random() - 0.5) * 0.002;
+
+  // Warm amber-to-gold color scheme matching attachment
+  const t = Math.random();
+  colors[i * 3] = 0.85 + t * 0.15;       // R - warm
+  colors[i * 3 + 1] = 0.45 + t * 0.35;   // G - amber
+  colors[i * 3 + 2] = 0.05 + t * 0.1;    // B - minimal
+
+  sizes[i] = Math.random() * 1.5 + 0.4;
+}
+
+geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+geometry.setAttribute('size', new THREE.BufferAttribute(sizes, 1));
+
+const material = new THREE.ShaderMaterial({
+  uniforms: {
+    uTime: { value: 0 },
+    uAudioLevel: { value: 0 },
+    uState: { value: 0 }, // 0=idle, 1=listening, 2=speaking
+    uPixelRatio: { value: renderer.getPixelRatio() }
+  },
+  vertexShader: `
+    attribute float size;
+    attribute vec3 color;
+    varying vec3 vColor;
+    uniform float uTime;
+    uniform float uAudioLevel;
+    uniform float uState;
+    uniform float uPixelRatio;
+
+    float noise(vec3 p) {
+      return fract(sin(dot(p, vec3(127.1, 311.7, 74.7))) * 43758.5453);
+    }
+
+    void main() {
+      vColor = color;
+      vec3 pos = position;
+      float n = noise(pos * 2.0 + uTime * 0.3);
+      float dist = length(pos);
+      float breathe = 1.0 + sin(uTime * 0.8 + n * 6.28) * 0.03;
+      float audio = uAudioLevel * 0.3;
+      float stateMod = mix(0.0, 0.08, step(0.5, uState));
+      pos *= breathe + audio + stateMod * n;
+
+      // Listening: particles scatter slightly outward
+      if (uState > 0.5 && uState < 1.5) {
+        pos += normalize(pos) * sin(uTime * 3.0 + n * 10.0) * 0.04 * uAudioLevel;
+      }
+      // Speaking: pulsating ring
+      if (uState > 1.5) {
+        float ring = abs(pos.y) < 0.3 ? 1.0 : 0.0;
+        pos += normalize(pos) * ring * sin(uTime * 6.0 + n * 8.0) * 0.06;
+      }
+
+      vec4 mvPosition = modelViewMatrix * vec4(pos, 1.0);
+      gl_PointSize = size * uPixelRatio * (280.0 / -mvPosition.z);
+      gl_Position = projectionMatrix * mvPosition;
+    }
+  `,
+  fragmentShader: `
+    varying vec3 vColor;
+    uniform float uState;
+    void main() {
+      vec2 uv = gl_PointCoord - 0.5;
+      float dist = length(uv);
+      if (dist > 0.5) discard;
+      float alpha = 1.0 - smoothstep(0.2, 0.5, dist);
+
+      // Tint color per state
+      vec3 col = vColor;
+      if (uState > 0.5 && uState < 1.5) {
+        col = mix(col, vec3(0.3, 0.6, 1.0), 0.4); // Blue-listening
+      } else if (uState > 1.5) {
+        col = mix(col, vec3(0.6, 1.0, 0.7), 0.35); // Green-speaking
+      }
+
+      gl_FragColor = vec4(col, alpha * 0.85);
+    }
+  `,
+  transparent: true,
+  vertexColors: true,
+  depthWrite: false,
+  blending: THREE.AdditiveBlending
+});
+
+const particles = new THREE.Points(geometry, material);
+scene.add(particles);
+
+// State
+let state = 0; // 0=idle, 1=listening, 2=speaking
+let targetAudioLevel = 0;
+let currentAudioLevel = 0;
+let speaking = false;
+let rotSpeed = 0.001;
+
+function setOrbState(s) {
+  state = s;
+  material.uniforms.uState.value = s;
+}
+
+// Simulate speaking audio pulses
+function simulateAudio(duration = 3000) {
+  const interval = setInterval(() => {
+    targetAudioLevel = Math.random() * 0.8 + 0.2;
+  }, 80);
+  setTimeout(() => {
+    clearInterval(interval);
+    targetAudioLevel = 0;
+  }, duration);
+}
+
+// Animation loop
+let clock = { t: 0, last: performance.now() };
+function animate() {
+  requestAnimationFrame(animate);
+  const now = performance.now();
+  const delta = (now - clock.last) / 1000;
+  clock.last = now;
+  clock.t += delta;
+
+  material.uniforms.uTime.value = clock.t;
+  currentAudioLevel += (targetAudioLevel - currentAudioLevel) * 0.1;
+  material.uniforms.uAudioLevel.value = currentAudioLevel;
+
+  particles.rotation.y += rotSpeed + currentAudioLevel * 0.002;
+  particles.rotation.x += rotSpeed * 0.3;
+
+  renderer.render(scene, camera);
+}
+animate();
+
+window.addEventListener('resize', () => {
+  camera.aspect = window.innerWidth / window.innerHeight;
+  camera.updateProjectionMatrix();
+  renderer.setSize(window.innerWidth, window.innerHeight);
+  material.uniforms.uPixelRatio.value = renderer.getPixelRatio();
+});
+
+// ─── Mic & State Machine ──────────────────────────
+let recording = false;
+const micBtn = document.getElementById('mic-btn');
+const orbText = document.getElementById('orb-text');
+const orbSubtitle = document.getElementById('orb-subtitle');
+const waveform = document.getElementById('waveform');
+const transcript = document.getElementById('transcript');
+const responsePanel = document.getElementById('response-panel');
+const responseText = document.getElementById('response-text');
+
+const DEMO_RESPONSES = [
+  "I've checked your Google Calendar. You have 3 meetings today — a standup at 9 AM, a design review at 2 PM, and a 1:1 at 4:30 PM.",
+  "I pulled up your Gmail. You have 7 unread messages, 2 of which appear to be marked high priority from Jason.Doe@company.com.",
+  "I found 4 open tasks in Google Tasks. The highest priority item is 'Deploy JARVIS backend' due tomorrow.",
+  "Running git status on your current project — 3 modified files, 1 untracked. Want me to open VS Code for a diff view?",
+  "I've taken a screenshot of your current screen and identified Chrome, VS Code, and Windows Terminal as your open applications.",
+  "I've created a new note in Google Keep titled 'JARVIS Ideas' with your content. It's been synced to your account."
+];
+
+const DEMO_QUERIES = [
+  "What's on my calendar today?",
+  "Check my Gmail for unread messages",
+  "Show me my pending tasks",
+  "Check git status on current project",
+  "What apps do I have open?",
+  "Create a note in Google Keep"
+];
+
+let demoIndex = 0;
+
+window.toggleMic = function() {
+  if (recording) {
+    stopRecording();
+  } else {
+    startRecording();
+  }
+};
+
+window.clearSession = function() {
+  responsePanel.classList.remove('visible');
+  transcript.textContent = 'Say something\u2026';
+  transcript.classList.remove('speaking');
+  orbText.textContent = 'STANDBY';
+  orbSubtitle.textContent = 'Tap microphone to speak';
+  waveform.classList.remove('active');
+  setOrbState(0);
+  targetAudioLevel = 0;
+  rotSpeed = 0.001;
+};
+
+function startRecording() {
+  recording = true;
+  micBtn.classList.add('recording');
+  setOrbState(1);
+  rotSpeed = 0.003;
+
+  const query = DEMO_QUERIES[demoIndex % DEMO_QUERIES.length];
+  transcript.textContent = 'Listening…';
+  transcript.classList.add('speaking');
+  orbText.textContent = 'LISTENING';
+  orbSubtitle.textContent = 'Processing audio input';
+  waveform.classList.add('active');
+  targetAudioLevel = 0.5;
+
+  // Simulate live transcription
+  let charIdx = 0;
+  const typeInterval = setInterval(() => {
+    if (charIdx <= query.length) {
+      transcript.textContent = query.slice(0, charIdx) + (charIdx < query.length ? '|' : '');
+      charIdx++;
+    } else {
+      clearInterval(typeInterval);
+      setTimeout(stopRecording, 400);
+    }
+  }, 60);
+}
+
+function stopRecording() {
+  recording = false;
+  micBtn.classList.remove('recording');
+  setOrbState(2);
+  rotSpeed = 0.002;
+
+  const query = DEMO_QUERIES[demoIndex % DEMO_QUERIES.length];
+  transcript.textContent = query;
+  orbText.textContent = 'PROCESSING';
+  orbSubtitle.textContent = 'Querying Claude API';
+  targetAudioLevel = 0.3;
+
+  setTimeout(() => {
+    const response = DEMO_RESPONSES[demoIndex % DEMO_RESPONSES.length];
+    demoIndex++;
+
+    orbText.textContent = 'SPEAKING';
+    orbSubtitle.textContent = 'Synthesizing response';
+    simulateAudio(response.length * 25);
+
+    responseText.textContent = '';
+    responsePanel.classList.add('visible');
+
+    // Typewriter effect
+    let i = 0;
+    const typeRes = setInterval(() => {
+      if (i <= response.length) {
+        responseText.textContent = response.slice(0, i);
+        i++;
+      } else {
+        clearInterval(typeRes);
+        setTimeout(() => {
+          orbText.textContent = 'STANDBY';
+          orbSubtitle.textContent = 'Tap microphone to speak';
+          waveform.classList.remove('active');
+          setOrbState(0);
+          targetAudioLevel = 0;
+          rotSpeed = 0.001;
+        }, 4000);
+      }
+    }, 18);
+  }, 1200);
+}
+</script>
+</body>
+</html>

core/claude_agent.py

@@ -0,0 +1,234 @@
+"""
+Claude API agent with tool use.
+All JARVIS capabilities are registered as tools that Claude can invoke.
+"""
+import os
+import json
+import anthropic
+from capabilities import (
+    screen_vision,
+    calendar_access,
+    email_access,
+    notes_manager,
+    task_manager,
+    file_system,
+    terminal_control,
+    browser_control,
+    git_manager,
+)
+
+client = anthropic.Anthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))
+
+SYSTEM_PROMPT = """You are JARVIS (Just A Rather Very Intelligent System), a Windows-based AI assistant.
+You have access to the following capabilities: screen vision, Google Calendar, Gmail, Google Tasks,
+Google Keep notes, file system management, PowerShell terminal, Chrome browser automation, and Git.
+Be concise, direct, and helpful. When using tools, always explain what you found."""
+
+TOOLS = [
+    {
+        "name": "capture_screen",
+        "description": "Take a screenshot and identify active windows and open applications",
+        "input_schema": {"type": "object", "properties": {}, "required": []}
+    },
+    {
+        "name": "get_calendar_events",
+        "description": "Get today's events or upcoming events from Google Calendar",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "days_ahead": {"type": "integer", "description": "Number of days ahead to fetch (default 0 = today only)", "default": 0}
+            },
+            "required": []
+        }
+    },
+    {
+        "name": "get_emails",
+        "description": "Get unread emails from Gmail or search by query",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Gmail search query (e.g. 'from:boss@company.com' or 'subject:invoice')"},
+                "count": {"type": "integer", "description": "Max number of emails to return", "default": 10}
+            },
+            "required": []
+        }
+    },
+    {
+        "name": "get_tasks",
+        "description": "Get pending tasks from Google Tasks",
+        "input_schema": {"type": "object", "properties": {}, "required": []}
+    },
+    {
+        "name": "create_task",
+        "description": "Create a new task in Google Tasks",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string", "description": "Task title"},
+                "notes": {"type": "string", "description": "Optional task notes"},
+                "due": {"type": "string", "description": "Optional due date in RFC 3339 format"}
+            },
+            "required": ["title"]
+        }
+    },
+    {
+        "name": "create_note",
+        "description": "Create a note in Google Keep",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "title": {"type": "string", "description": "Note title"},
+                "content": {"type": "string", "description": "Note body text"}
+            },
+            "required": ["title", "content"]
+        }
+    },
+    {
+        "name": "run_powershell",
+        "description": "Execute a PowerShell command and return the output",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string", "description": "PowerShell command to run"}
+            },
+            "required": ["command"]
+        }
+    },
+    {
+        "name": "get_git_status",
+        "description": "Get git status of a project directory",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Absolute path to the git repository"}
+            },
+            "required": ["path"]
+        }
+    },
+    {
+        "name": "open_browser",
+        "description": "Open Chrome and navigate to a URL or perform a Google search",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "url": {"type": "string", "description": "URL to navigate to"},
+                "search": {"type": "string", "description": "Search query (alternative to url)"}
+            },
+            "required": []
+        }
+    },
+    {
+        "name": "create_project_folder",
+        "description": "Create a new project folder with a README",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Project name"},
+                "base_path": {"type": "string", "description": "Base directory path", "default": "C:/Projects"}
+            },
+            "required": ["name"]
+        }
+    }
+]
+
+def _dispatch_tool(name: str, inputs: dict) -> str:
+    """Route a Claude tool_use call to the appropriate capability module."""
+    try:
+        if name == "capture_screen":
+            windows = screen_vision.list_open_windows()
+            active = screen_vision.get_active_window_title()
+            return json.dumps({"active_window": active, "open_windows": windows[:10]})
+
+        elif name == "get_calendar_events":
+            days = inputs.get("days_ahead", 0)
+            if days == 0:
+                events = calendar_access.get_todays_events()
+            else:
+                events = calendar_access.get_upcoming_events(days=days)
+            return json.dumps(events)
+
+        elif name == "get_emails":
+            query = inputs.get("query")
+            count = inputs.get("count", 10)
+            if query:
+                emails = email_access.search_emails(query)
+            else:
+                emails = email_access.get_unread_emails(count=count)
+            return json.dumps(emails)
+
+        elif name == "get_tasks":
+            return json.dumps(task_manager.get_pending_tasks())
+
+        elif name == "create_task":
+            result = task_manager.create_task(
+                title=inputs["title"],
+                notes=inputs.get("notes"),
+                due=inputs.get("due")
+            )
+            return json.dumps({"created": True, "id": result.get("id")})
+
+        elif name == "create_note":
+            note_id = notes_manager.create_note(inputs["title"], inputs["content"])
+            return json.dumps({"created": True, "id": note_id})
+
+        elif name == "run_powershell":
+            result = terminal_control.run_powershell(inputs["command"])
+            return json.dumps(result)
+
+        elif name == "get_git_status":
+            status = git_manager.get_git_status(inputs["path"])
+            return json.dumps({"status": status})
+
+        elif name == "open_browser":
+            if inputs.get("url"):
+                browser_control.navigate_to(inputs["url"])
+                return json.dumps({"opened": inputs["url"]})
+            elif inputs.get("search"):
+                browser_control.search_web(inputs["search"])
+                return json.dumps({"searching": inputs["search"]})
+
+        elif name == "create_project_folder":
+            path = file_system.create_project(
+                inputs["name"],
+                inputs.get("base_path", "C:/Projects")
+            )
+            return json.dumps({"created": path})
+
+        return json.dumps({"error": f"Unknown tool: {name}"})
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+async def get_response(user_text: str) -> str:
+    """Send user text to Claude with tool use enabled. Returns final text response."""
+    messages = [{"role": "user", "content": user_text}]
+
+    while True:
+        response = client.messages.create(
+            model="claude-opus-4-5",
+            max_tokens=1024,
+            system=SYSTEM_PROMPT,
+            tools=TOOLS,
+            messages=messages
+        )
+
+        # If Claude wants to use a tool, dispatch and continue
+        if response.stop_reason == "tool_use":
+            tool_results = []
+            for block in response.content:
+                if block.type == "tool_use":
+                    result = _dispatch_tool(block.name, block.input)
+                    tool_results.append({
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": result
+                    })
+
+            messages.append({"role": "assistant", "content": response.content})
+            messages.append({"role": "user", "content": tool_results})
+
+        else:
+            # Final text response
+            for block in response.content:
+                if hasattr(block, "text"):
+                    return block.text
+            return "I couldn't generate a response."

core/google_auth.py

@@ -0,0 +1,34 @@
+"""
+Shared Google OAuth 2.0 handler.
+Covers: Gmail, Google Calendar, Google Tasks, Google Keep.
+Place credentials.json (downloaded from Google Cloud Console) in project root.
+"""
+import os
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+SCOPES = [
+    'https://www.googleapis.com/auth/gmail.readonly',
+    'https://www.googleapis.com/auth/calendar',
+    'https://www.googleapis.com/auth/tasks',
+    # 'https://www.googleapis.com/auth/keep',  # Uncomment if Workspace Enterprise
+]
+
+def get_credentials() -> Credentials:
+    """
+    Returns valid Google OAuth credentials.
+    Opens browser on first run. Saves/refreshes token.json automatically.
+    """
+    creds = None
+    if os.path.exists('token.json'):
+        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
+            creds = flow.run_local_server(port=0)
+        with open('token.json', 'w') as token:
+            token.write(creds.to_json())
+    return creds

core/voice_input.py

@@ -0,0 +1,35 @@
+"""
+Voice input — transcribes raw audio bytes using OpenAI Whisper (local).
+Model size set via WHISPER_MODEL env var (default: base).
+"""
+import os
+import tempfile
+import asyncio
+import whisper
+
+_model = None
+
+def _get_model():
+    global _model
+    if _model is None:
+        model_size = os.getenv("WHISPER_MODEL", "base")
+        print(f"[JARVIS] Loading Whisper model: {model_size}")
+        _model = whisper.load_model(model_size)
+    return _model
+
+async def transcribe_audio(audio_bytes: bytes) -> str:
+    """Transcribe raw WAV audio bytes to text using Whisper."""
+    model = _get_model()
+    loop = asyncio.get_event_loop()
+
+    def _transcribe():
+        with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+            f.write(audio_bytes)
+            tmp_path = f.name
+        try:
+            result = model.transcribe(tmp_path, fp16=False)
+            return result["text"].strip()
+        finally:
+            os.unlink(tmp_path)
+
+    return await loop.run_in_executor(None, _transcribe)

core/voice_output.py

@@ -0,0 +1,27 @@
+"""
+Voice output — converts text to speech using Fish Audio TTS API.
+"""
+import os
+import asyncio
+from fish_audio_sdk import Session, TTSRequest
+
+async def speak(text: str) -> bytes:
+    """
+    Convert text to speech audio bytes using Fish Audio TTS.
+    Returns raw audio bytes (MP3).
+    """
+    api_key = os.getenv("FISH_AUDIO_API_KEY")
+    voice_id = os.getenv("FISH_AUDIO_VOICE_ID", None)
+    loop = asyncio.get_event_loop()
+
+    def _tts():
+        with Session(apikey=api_key) as session:
+            audio_chunks = []
+            for chunk in session.tts(TTSRequest(
+                text=text,
+                reference_id=voice_id
+            )):
+                audio_chunks.append(chunk)
+            return b"".join(audio_chunks)
+
+    return await loop.run_in_executor(None, _tts)

core/websocket_manager.py

@@ -0,0 +1,24 @@
+"""
+WebSocket connection manager — handles multiple simultaneous clients.
+"""
+from fastapi import WebSocket
+from typing import List
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: List[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket):
+        await websocket.accept()
+        self.active_connections.append(websocket)
+
+    def disconnect(self, websocket: WebSocket):
+        self.active_connections.remove(websocket)
+
+    async def broadcast_json(self, data: dict):
+        for connection in self.active_connections:
+            await connection.send_json(data)
+
+    async def broadcast_bytes(self, data: bytes):
+        for connection in self.active_connections:
+            await connection.send_bytes(data)

hubs/brainstorming.md

@@ -0,0 +1,25 @@
+# Brainstorming Hub
+
+Use this hub when the task is to generate options, explore solution space, compare directions, or turn rough ideas into structured next steps.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains brainstorming defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- The user wants concepts, options, or strategic directions
+- Requirements are early-stage and need shaping
+- A promising idea needs to become a scoped plan
+- The team wants alternatives before implementation
+
+## Skill Routing
+
+- [Ideation](../skills/brainstorming/ideation.md) for broad option generation and concept creation
+- [Structured Brainstorming](../skills/brainstorming/structured-brainstorming.md) for narrowing, comparing, scoring, and turning ideas into action
+- [Roadmap and Opportunity Prioritization](../skills/brainstorming/roadmap-opportunity-prioritization.md) for sequencing initiatives, balancing impact versus effort, and choosing what should happen next
+
+## Common Combinations
+
+- Product concepting: ideation + messaging/positioning
+- Solution design: ideation + structured brainstorming + repository exploration
+- From ideas to build plan: structured brainstorming + feature implementation + test strategy
+- Long-range planning: roadmap and opportunity prioritization + maintenance and technical debt planning + architecture and system design

hubs/debugging.md

@@ -0,0 +1,27 @@
+# Debugging Hub
+
+Use this hub for work that begins with a defect, regression, failing test, production issue, or confusing system behavior.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains debugging defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- A test is failing and the cause is unclear
+- A user-reported bug needs reproduction and triage
+- The system behaves inconsistently across environments or inputs
+- A suspected regression needs careful isolation
+
+## Start With
+
+- [Bug Triage](../skills/debugging/bug-triage.md) to define the problem, impact, environment, and reproduction path
+- [Debugging Workflow](../skills/debugging/debugging-workflow.md) to isolate root cause and verify a fix
+
+## Combine With
+
+- [API and Backend Work](../skills/software/api-backend.md) when the issue is server-side or data-related
+- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) when the issue is client-side or interaction-related
+- [Test Strategy](../skills/software/test-strategy.md) when the fix needs coverage
+- [Release and Change Summary](../skills/software/release-change-summary.md) when the resolution should be communicated clearly
+- [Incident Response and Stabilization](../skills/debugging/incident-response-stabilization.md) when the issue is live, user-impacting, or needs temporary containment before a full fix
+- [Observability and Operability](../skills/software/observability-operability.md) when logs, metrics, traces, or alerting gaps block diagnosis
+- [Performance Optimization](../skills/software/performance-optimization.md) when the problem is latency, throughput, memory, or rendering related

hubs/documentation.md

@@ -0,0 +1,26 @@
+# Documentation Hub
+
+Use this hub when the task changes how people understand, adopt, operate, or maintain the product.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains documentation defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- Write or update technical documentation
+- Improve onboarding or contributor guidance
+- Create release notes or change summaries
+- Align docs with code or product changes
+
+## Skill Routing
+
+- [Architecture Decision Records](../skills/documentation/architecture-decision-records.md) for capturing meaningful technical choices, tradeoffs, and why a direction was selected
+- [Technical Documentation](../skills/documentation/technical-docs.md) for architecture, APIs, workflows, operational guidance, and usage docs
+- [Onboarding Documentation](../skills/documentation/onboarding-docs.md) for setup guides, contributor onboarding, first-run experience, and internal enablement
+- [Release and Change Summary](../skills/software/release-change-summary.md) for release notes, changelog writing, and rollout explanations
+
+## Common Combinations
+
+- New feature: technical docs + release/change summary
+- Developer experience improvement: onboarding docs + technical docs
+- Product launch: release/change summary + messaging/positioning + marketing content
+- Long-lived architecture change: architecture and system design + architecture decision records + technical docs

hubs/marketing.md

@@ -0,0 +1,26 @@
+# Marketing Hub
+
+Use this hub for external-facing product language, launch assets, positioning, and persuasive communication.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains marketing defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- Draft launch messaging or feature announcements
+- Improve website or product marketing copy
+- Clarify product differentiation and audience fit
+- Create marketing assets tied to engineering or product changes
+
+## Skill Routing
+
+- [Product Copy](../skills/marketing/product-copy.md) for UI-adjacent language, concise product text, and conversion-oriented wording
+- [Marketing Content](../skills/marketing/marketing-content.md) for launch posts, feature pages, emails, social copy, and content drafts
+- [Messaging and Positioning](../skills/marketing/messaging-positioning.md) for audience, value proposition, differentiation, and narrative framing
+- [Content Strategy and SEO](../skills/marketing/content-strategy-seo.md) for durable organic content, search intent alignment, and content planning
+
+## Common Combinations
+
+- Feature launch: messaging/positioning + marketing content + release/change summary
+- Landing page refresh: product copy + messaging/positioning + UX review
+- Developer tool announcement: marketing content + technical docs + messaging/positioning
+- Evergreen growth work: content strategy and SEO + messaging/positioning + technical docs

hubs/software-development.md

@@ -0,0 +1,44 @@
+# Software Development Hub
+
+Use this hub for implementation-focused software work: features, refactors, code review, tests, backend changes, frontend changes, and release communication tied to engineering output.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains software defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- Build or modify product functionality
+- Improve maintainability or architecture
+- Review existing code for bugs, regressions, or missing tests
+- Plan or add verification coverage
+- Explore an unfamiliar codebase before changing it
+
+## Start With
+
+- [Repository Exploration](../skills/software/repo-exploration.md) for unfamiliar codebases or vague requests
+- [Feature Implementation](../skills/software/feature-implementation.md) for net-new behavior or substantial changes
+
+## Skill Routing
+
+- [Architecture and System Design](../skills/software/architecture-system-design.md) for major system changes, design tradeoffs, and long-lived technical direction
+- [Refactoring](../skills/software/refactoring.md) for structure improvements without intended behavior changes
+- [Code Review](../skills/software/code-review.md) for finding bugs, regressions, risky assumptions, and missing coverage
+- [Test Strategy](../skills/software/test-strategy.md) for designing, expanding, or evaluating verification
+- [API and Backend Work](../skills/software/api-backend.md) for services, storage, schema, integration, and server-side logic
+- [Database Migrations and Data Evolution](../skills/software/database-migrations.md) for schema changes, backfills, compatibility windows, and rollout-safe data transitions
+- [Dependency Lifecycle Management](../skills/software/dependency-lifecycle.md) for upgrades, dependency risk reduction, and ecosystem maintenance
+- [Performance Optimization](../skills/software/performance-optimization.md) for latency, throughput, rendering, and resource-efficiency work
+- [Security Review and Hardening](../skills/software/security-review-hardening.md) for auth, validation, secrets, exposure, and abuse resistance concerns
+- [Observability and Operability](../skills/software/observability-operability.md) for logging, metrics, traces, alerts, and operational readiness
+- [Maintenance and Technical Debt Planning](../skills/software/maintenance-technical-debt.md) for long-horizon cleanup, risk reduction, and sequencing work
+- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) for interfaces, interaction logic, and client-side UX execution
+- [Release and Change Summary](../skills/software/release-change-summary.md) for release notes, summaries, migration notes, and rollout communication
+
+## Common Combinations
+
+- New feature: repository exploration + feature implementation + test strategy + technical docs
+- Backend bug fix: bug triage + debugging workflow + API and backend work + release/change summary
+- UI feature: feature implementation + frontend UI implementation + UX review + product copy
+- PR review: code review + test strategy
+- Platform change: architecture and system design + API/backend work + observability and operability + technical docs
+- Risky upgrade: dependency lifecycle management + test strategy + release/change summary
+- Data model change: architecture and system design + database migrations and data evolution + API/backend work

hubs/ui-ux.md

@@ -0,0 +1,26 @@
+# UI/UX Hub
+
+Use this hub when the task depends on interface quality, interaction flow, usability, clarity, or user-facing content design.
+
+If [DEPLOYMENT-PROFILE.md](../DEPLOYMENT-PROFILE.md) contains UI/UX defaults, apply those preferences before falling back to the generic routing in this hub.
+
+## When To Use
+
+- Review a screen, flow, or feature for UX weaknesses
+- Improve copy, hierarchy, clarity, or task completion
+- Implement or revise UI behavior with usability in mind
+
+## Skill Routing
+
+- [UX Review](../skills/ui-ux/ux-review.md) for critique, heuristics, friction detection, and recommendations
+- [Accessibility Review](../skills/ui-ux/accessibility-review.md) for inclusive interaction quality, keyboard support, semantics, contrast, and assistive-technology readiness
+- [Design System and UI Consistency](../skills/ui-ux/design-system-consistency.md) for component reuse, visual consistency, and scalable UI patterns
+- [Frontend UI Implementation](../skills/software/frontend-ui-implementation.md) for shipping the UI changes
+- [Product Copy](../skills/marketing/product-copy.md) when labels, empty states, CTAs, or in-product messaging matter
+
+## Common Combinations
+
+- New settings page: frontend UI implementation + UX review + product copy
+- Navigation cleanup: UX review + frontend UI implementation
+- Conversion-focused UI change: UX review + product copy + messaging/positioning
+- UI platform work: design system and UI consistency + frontend UI implementation + accessibility review

main.py

@@ -0,0 +1,70 @@
+"""
+JARVIS — main FastAPI entrypoint
+"""
+import os
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+from dotenv import load_dotenv
+
+from core.websocket_manager import ConnectionManager
+from core.voice_input import transcribe_audio
+from core.claude_agent import get_response
+from core.voice_output import speak
+
+load_dotenv()
+
+app = FastAPI(title="JARVIS", version="1.0.0")
+manager = ConnectionManager()
+
+# Serve the dashboard frontend
+app.mount("/static", StaticFiles(directory="client"), name="static")
+
+@app.get("/")
+async def root():
+    return FileResponse("client/jarvis-dashboard.html")
+
+@app.get("/health")
+async def health():
+    return {"status": "online", "version": "1.0.0"}
+
+@app.websocket("/ws/voice")
+async def voice_endpoint(websocket: WebSocket):
+    """
+    Main voice WebSocket endpoint.
+    Client sends raw audio bytes → server transcribes → Claude → TTS → sends audio bytes back.
+    """
+    await manager.connect(websocket)
+    try:
+        while True:
+            # Receive audio chunk from client
+            audio_chunk = await websocket.receive_bytes()
+
+            # 1. Transcribe with Whisper
+            await websocket.send_json({"type": "status", "state": "processing"})
+            text = await transcribe_audio(audio_chunk)
+            await websocket.send_json({"type": "transcript", "text": text})
+
+            # 2. Get Claude response (with tool use)
+            await websocket.send_json({"type": "status", "state": "thinking"})
+            response_text = await get_response(text)
+            await websocket.send_json({"type": "response", "text": response_text})
+
+            # 3. Synthesize speech with Fish Audio
+            await websocket.send_json({"type": "status", "state": "speaking"})
+            audio_response = await speak(response_text)
+            await websocket.send_bytes(audio_response)
+
+            await websocket.send_json({"type": "status", "state": "idle"})
+
+    except WebSocketDisconnect:
+        manager.disconnect(websocket)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "main:app",
+        host=os.getenv("HOST", "0.0.0.0"),
+        port=int(os.getenv("PORT", 8000)),
+        reload=True
+    )

requirements.txt

@@ -0,0 +1,36 @@
+# ─── Core ─────────────────────────────────────────
+fastapi
+uvicorn[standard]
+websockets
+python-dotenv
+
+# ─── AI / Voice ───────────────────────────────────
+anthropic
+openai-whisper
+SpeechRecognition
+pyaudio
+# NOTE: On Windows, if pyaudio fails:
+# pip install pipwin && pipwin install pyaudio
+
+# ─── Fish Audio TTS ───────────────────────────────
+fish-audio-sdk
+
+# ─── Google Workspace ─────────────────────────────
+google-api-python-client
+google-auth-httplib2
+google-auth-oauthlib
+gkeepapi
+
+# ─── Windows Screen / Automation ─────────────────
+mss
+pyautogui
+Pillow
+pywin32
+
+# ─── Browser Automation ───────────────────────────
+selenium
+# Selenium 4+ auto-downloads ChromeDriver — no manual install needed
+
+# ─── Utilities ────────────────────────────────────
+aiofiles
+httpx

skills/brainstorming/ideation.md

@@ -0,0 +1,45 @@
+# Ideation
+
+## Purpose
+
+Generate strong options quickly without locking too early onto the first plausible idea.
+
+## When to use
+
+- The user wants multiple concepts, approaches, or product directions
+- Requirements are early and the solution space is still wide
+- A team needs creative alternatives before choosing a path
+- You want to escape local maxima in product or technical thinking
+
+## Inputs to gather
+
+- Goal, audience, constraints, and success criteria
+- What is already known, tried, or ruled out
+- Time, complexity, and implementation constraints
+- The desired balance of novelty versus practicality
+
+## How to work
+
+- Produce several meaningfully different options, not minor variations of one idea.
+- Cover a range from safer to bolder approaches when useful.
+- Make tradeoffs explicit so ideas are easy to compare.
+- Keep ideas concrete enough that someone can imagine implementation or execution.
+- Narrow only after the option space is genuinely explored.
+
+## Output expectations
+
+- Distinct options with concise descriptions
+- Tradeoffs, strengths, and risks for each option
+- A recommended direction when appropriate
+
+## Quality checklist
+
+- Options are genuinely different in mechanism or strategy.
+- Ideas respect the stated constraints.
+- Tradeoffs are visible rather than implied.
+- Recommendations, if given, follow from the comparison.
+
+## Handoff notes
+
+- Note whether the ideas are exploratory, implementation-ready, or need structured narrowing next.
+- Pair with structured brainstorming when the next step is selecting and shaping one path.

skills/brainstorming/roadmap-opportunity-prioritization.md

@@ -0,0 +1,45 @@
+# Roadmap and Opportunity Prioritization
+
+## Purpose
+
+Choose what to do next by comparing opportunities, maintenance work, and strategic bets against explicit decision criteria.
+
+## When to use
+
+- Too many plausible initiatives compete for limited time
+- Feature work and maintenance work need to be balanced
+- A team needs a more defensible roadmap discussion
+- Promising ideas need sequencing rather than more generation
+
+## Inputs to gather
+
+- Candidate initiatives or workstreams
+- Decision criteria such as impact, urgency, effort, risk reduction, or strategic fit
+- Dependencies, timing constraints, and team capacity
+- Evidence for expected payoff or avoided risk
+
+## How to work
+
+- Make prioritization criteria explicit before ranking work.
+- Compare user value, strategic value, and risk reduction together.
+- Treat maintenance and enabling work as first-class opportunities when they materially improve future delivery.
+- Distinguish what is urgent, what is high leverage, and what is merely attractive.
+- Produce a sequence that a team can actually act on.
+
+## Output expectations
+
+- Prioritized list or roadmap recommendation
+- Clear rationale for order and tradeoffs
+- Notes on what to defer, revisit, or validate next
+
+## Quality checklist
+
+- Priorities reflect stated criteria rather than intuition alone.
+- Sequencing respects dependencies and capacity.
+- Lower-priority items are deferred for a reason, not forgotten accidentally.
+- Maintenance work is evaluated on outcomes, not optics.
+
+## Handoff notes
+
+- Note what new evidence would most change the ranking.
+- Pair with maintenance and technical debt planning or structured brainstorming when the decision needs deeper shaping.

skills/brainstorming/structured-brainstorming.md

@@ -0,0 +1,45 @@
+# Structured Brainstorming
+
+## Purpose
+
+Turn rough ideas into decision-ready options by comparing them systematically, narrowing intelligently, and shaping the chosen direction into actionable next steps.
+
+## When to use
+
+- Many ideas exist and the team needs a clear recommendation
+- A promising concept needs scoping before implementation
+- Tradeoffs need to be surfaced explicitly
+- The next step is choosing, sequencing, or planning rather than generating more ideas
+
+## Inputs to gather
+
+- Candidate ideas or possible approaches
+- Decision criteria such as impact, effort, risk, speed, or strategic fit
+- Constraints on time, team, technical feasibility, or audience needs
+- Any assumptions that materially change the choice
+
+## How to work
+
+- Define the decision criteria before ranking options.
+- Compare options on the criteria that actually matter for the request.
+- Remove weak options quickly once the reason is clear.
+- Turn the selected direction into a scoped set of next steps or a buildable outline.
+- Keep the analysis proportional; do not over-formalize simple decisions.
+
+## Output expectations
+
+- Clear comparison of options
+- Recommended direction with reasoning
+- A scoped next-step plan or action outline
+
+## Quality checklist
+
+- Decision criteria are explicit and relevant.
+- The recommendation follows from the comparison rather than preference alone.
+- The chosen path is actionable, not just inspirational.
+- Key assumptions are visible.
+
+## Handoff notes
+
+- Note what would most likely change the recommendation.
+- Pair with feature implementation, repo exploration, or messaging skills when moving from choice to execution.

skills/debugging/bug-triage.md

@@ -0,0 +1,46 @@
+# Bug Triage
+
+## Purpose
+
+Frame a defect clearly before or during debugging so the team understands impact, reproduction, suspected scope, and next actions.
+
+## When to use
+
+- A bug report arrives with incomplete detail
+- A failing test or regression needs initial framing
+- Multiple issues compete for attention and severity matters
+- You need a reliable reproduction path before deeper debugging
+
+## Inputs to gather
+
+- Reported symptoms, expected behavior, and actual behavior
+- Reproduction steps, environment, and frequency
+- User impact, severity, and likely affected surfaces
+- Recent changes, logs, or tests that may be related
+
+## How to work
+
+- Turn vague symptoms into a concrete problem statement.
+- Reproduce the issue when possible and tighten the reproduction steps.
+- Separate confirmed facts from assumptions.
+- Estimate impact and likely blast radius before diving into fixes.
+- Identify the next best debugging step if root cause is not yet known.
+
+## Output expectations
+
+- Clear bug statement and reproduction status
+- Impact and severity assessment
+- Suspected scope or likely component area
+- Recommended next debugging or fix step
+
+## Quality checklist
+
+- The issue is described in observable terms rather than guesses.
+- Reproduction details are specific enough to be reused.
+- Impact is clear enough to prioritize intelligently.
+- Unknowns are named instead of hidden.
+
+## Handoff notes
+
+- Record environment details and whether the issue is deterministic, intermittent, or unconfirmed.
+- Pair with debugging workflow once the problem is framed well enough to investigate deeply.

skills/debugging/debugging-workflow.md

@@ -0,0 +1,46 @@
+# Debugging Workflow
+
+## Purpose
+
+Find root cause efficiently and verify fixes with a disciplined workflow that avoids premature assumptions and shallow symptom treatment.
+
+## When to use
+
+- The defect is real but the cause is unclear
+- A failing test needs investigation
+- The system has inconsistent or environment-specific behavior
+- A regression may have multiple plausible causes
+
+## Inputs to gather
+
+- Reproduction path or failing signal
+- Relevant code paths, logs, traces, state transitions, and recent changes
+- Existing tests or ways to validate a hypothesis
+- Environment details that may influence behavior
+
+## How to work
+
+- Reproduce first when possible, then narrow scope by isolating the smallest failing path.
+- Form hypotheses from evidence, not instinct alone, and invalidate them aggressively.
+- Inspect boundaries: inputs, outputs, state mutations, async timing, external dependencies, and configuration.
+- Fix the root cause rather than only masking symptoms when feasible.
+- Re-run the original failing signal and add regression protection if appropriate.
+
+## Output expectations
+
+- Root cause explanation tied to evidence
+- Fix or recommended fix approach
+- Verification that the original issue is resolved
+- Remaining uncertainty, if any
+
+## Quality checklist
+
+- The explanation connects cause to symptom clearly.
+- The chosen fix addresses the real failure mechanism.
+- Verification includes the original failing path.
+- Regression protection is considered when the bug is likely to recur.
+
+## Handoff notes
+
+- Note whether the issue was fully reproduced, partially inferred, or fixed based on a probable cause.
+- Mention monitoring or follow-up checks if confidence is limited by environment or observability.

skills/debugging/incident-response-stabilization.md

@@ -0,0 +1,45 @@
+# Incident Response and Stabilization
+
+## Purpose
+
+Guide high-pressure response to live or high-impact issues by separating immediate stabilization from deeper root-cause correction.
+
+## When to use
+
+- A production issue is actively impacting users or operators
+- A regression needs containment before a complete fix is ready
+- The team needs a calm sequence for triage, mitigation, and follow-up
+- Communication and operational clarity matter as much as code changes
+
+## Inputs to gather
+
+- Current symptoms, severity, affected users, and timing
+- Available logs, metrics, alerts, dashboards, and recent changes
+- Safe rollback, feature flag, degrade, or traffic-shaping options
+- Stakeholders who need updates and what they need to know
+
+## How to work
+
+- Stabilize user impact first if a safe containment path exists.
+- Keep mitigation, diagnosis, and communication distinct but coordinated.
+- Prefer reversible steps under uncertainty.
+- Record what is confirmed versus assumed while the incident is active.
+- After stabilization, convert the incident into structured debugging and prevention work.
+
+## Output expectations
+
+- Stabilization plan or incident response summary
+- Clear mitigation status and next actions
+- Follow-up work for root cause, observability, and prevention
+
+## Quality checklist
+
+- User impact reduction is prioritized appropriately.
+- Risky irreversible changes are avoided under pressure.
+- Communication is clear enough for collaborators to act.
+- Post-incident follow-up is not lost after immediate recovery.
+
+## Handoff notes
+
+- Note what was mitigated versus actually fixed.
+- Pair with debugging workflow and observability once the system is stable enough for deeper work.

skills/documentation/architecture-decision-records.md

@@ -0,0 +1,45 @@
+# Architecture Decision Records
+
+## Purpose
+
+Capture significant technical decisions so future contributors understand what was chosen, why it was chosen, and what tradeoffs were accepted.
+
+## When to use
+
+- A meaningful architectural or platform choice has been made
+- Multiple alternatives were considered and context would otherwise be lost
+- A decision will affect future implementation, migration, or team habits
+- You want to prevent repeated re-litigation of the same tradeoff
+
+## Inputs to gather
+
+- The decision being made
+- Alternatives considered
+- Relevant constraints, drivers, and consequences
+- Current status: proposed, accepted, superseded, or rejected
+
+## How to work
+
+- Record the decision close to when it is made.
+- Keep the record concise but concrete enough to survive future context loss.
+- Explain why the selected option won, not just what it is.
+- Include consequences so future readers understand the cost of the choice.
+- Update or supersede older records rather than leaving conflicting guidance unresolved.
+
+## Output expectations
+
+- A crisp decision record with context, choice, alternatives, and consequences
+- Status that reflects whether the decision is still tentative or settled
+- Links to implementation or follow-up docs when useful
+
+## Quality checklist
+
+- The decision is clear and specific.
+- Alternatives and tradeoffs are visible.
+- Future readers can understand the reasoning without redoing the whole discussion.
+- The record stays short enough to remain useful.
+
+## Handoff notes
+
+- Reference the implementation, technical docs, or migration plan that operationalizes the decision.
+- Pair with architecture and system design for major system changes.

skills/documentation/onboarding-docs.md

@@ -0,0 +1,45 @@
+# Onboarding Documentation
+
+## Purpose
+
+Help new contributors or users become productive quickly by reducing ambiguity, setup friction, and missing context.
+
+## When to use
+
+- Improving setup or first-run guidance
+- Writing contributor onboarding docs
+- Creating "start here" guides for internal or external users
+- Simplifying confusing developer or product entry points
+
+## Inputs to gather
+
+- Current setup steps and prerequisites
+- Common failure points, hidden assumptions, and missing context
+- Existing onboarding flow and repository conventions
+- Intended audience: contributor, operator, customer, or teammate
+
+## How to work
+
+- Optimize for first success, not exhaustiveness.
+- Put prerequisites, setup order, and validation steps in the order a new person needs them.
+- Surface gotchas early rather than burying them after failures occur.
+- Use concrete commands, examples, and expected outcomes when they reduce confusion.
+- Trim insider jargon unless it is explained.
+
+## Output expectations
+
+- A cleaner onboarding path with clear first steps
+- Documentation that reduces setup ambiguity and dead ends
+- Helpful validation or troubleshooting guidance where needed
+
+## Quality checklist
+
+- A new person can tell where to start.
+- Steps are ordered logically and are easy to verify.
+- Prerequisites and common failures are not hidden.
+- The doc avoids assuming too much existing context.
+
+## Handoff notes
+
+- Note any setup steps you could not verify directly.
+- Pair with technical docs when onboarding depends on deeper conceptual explanation.

skills/documentation/technical-docs.md

@@ -0,0 +1,45 @@
+# Technical Documentation
+
+## Purpose
+
+Create or update documentation that helps developers, operators, or advanced users understand how the system works and how to use it correctly.
+
+## When to use
+
+- Updating docs after engineering changes
+- Writing usage guides, architecture notes, or operational docs
+- Explaining APIs, workflows, configuration, or system behavior
+- Improving stale or incomplete technical documentation
+
+## Inputs to gather
+
+- The current implementation and the user-visible workflow
+- Existing docs, terminology, and structure in the repo
+- Intended audience and their technical depth
+- Any setup steps, caveats, or common failure points
+
+## How to work
+
+- Document the real behavior of the system, not the hoped-for design.
+- Prefer task-oriented structure when users need to get something done.
+- Use precise terminology that matches the code and UI.
+- Include examples, prerequisites, and pitfalls when they materially improve clarity.
+- Keep docs aligned with adjacent pages and avoid fragmenting the source of truth.
+
+## Output expectations
+
+- Clear, accurate documentation update or new draft
+- Audience-appropriate level of technical detail
+- Explicit caveats, prerequisites, and compatibility notes when relevant
+
+## Quality checklist
+
+- Instructions are accurate against the current implementation.
+- The document helps someone complete a real task or understand a real concept.
+- Terms and examples are consistent with the product and codebase.
+- Important caveats are easy to find.
+
+## Handoff notes
+
+- Mention what was verified directly in code versus inferred from context.
+- Note any related docs that should be updated later to stay consistent.

skills/marketing/content-strategy-seo.md

@@ -0,0 +1,45 @@
+# Content Strategy and SEO
+
+## Purpose
+
+Create durable content plans and search-aligned messaging that compound over time instead of only supporting one launch moment.
+
+## When to use
+
+- Planning evergreen content around a product area
+- Improving discoverability for technical or product topics
+- Aligning content to audience intent and search behavior
+- Deciding which topics deserve durable written assets
+
+## Inputs to gather
+
+- Audience segments and their recurring questions
+- Product strengths, proof points, and topic authority
+- Existing content library and content gaps
+- Desired business outcome: discovery, education, conversion, or retention
+
+## How to work
+
+- Start from audience intent and recurring problems, not isolated keywords alone.
+- Organize content into durable themes that the product can support credibly.
+- Align titles, structure, and calls to action with user intent.
+- Avoid search-driven copy that weakens clarity or trust.
+- Prefer content that stays useful as the product evolves.
+
+## Output expectations
+
+- Content strategy, topic map, or SEO-aware draft direction
+- Prioritized content opportunities with rationale
+- Notes on how content connects to product positioning and documentation
+
+## Quality checklist
+
+- Recommendations reflect real audience needs.
+- Content ideas support durable value, not shallow traffic grabs.
+- Search alignment does not distort message clarity.
+- The strategy can inform multiple future assets.
+
+## Handoff notes
+
+- Note which assumptions are based on audience reasoning versus actual search data.
+- Pair with messaging/positioning and technical docs for strong, credible long-tail content.

skills/marketing/marketing-content.md

@@ -0,0 +1,45 @@
+# Marketing Content
+
+## Purpose
+
+Create external-facing content that explains, promotes, or launches product capabilities in a way that is accurate, audience-aware, and compelling.
+
+## When to use
+
+- Drafting launch posts, emails, feature pages, announcements, or social content
+- Turning product or engineering work into outward-facing communication
+- Adapting one core message into multiple channels
+- Creating content tied to a release or campaign
+
+## Inputs to gather
+
+- Audience, channel, and desired action
+- The actual product change or offer being communicated
+- Supporting proof points, examples, and differentiators
+- Voice, tone, and length constraints
+
+## How to work
+
+- Lead with why the audience should care.
+- Ground claims in the real product and its benefits.
+- Structure content so it is easy to scan and repurpose.
+- Tailor tone and density to the channel instead of reusing the same draft everywhere.
+- Keep technical explanations accurate while translating them into audience-relevant outcomes.
+
+## Output expectations
+
+- A polished draft for the requested channel
+- Supporting variations or headline options when useful
+- Clear call to action where appropriate
+
+## Quality checklist
+
+- The content is audience-centered, not feature-dump centered.
+- Claims are specific and defensible.
+- The narrative is easy to scan and follow.
+- The output matches the requested medium and length.
+
+## Handoff notes
+
+- State which audience and channel the draft targets.
+- Pair with messaging/positioning when the strategic framing is not yet settled.

skills/marketing/messaging-positioning.md

@@ -0,0 +1,45 @@
+# Messaging and Positioning
+
+## Purpose
+
+Clarify who the product or feature is for, what value it provides, why it matters now, and how it differs from alternatives.
+
+## When to use
+
+- Defining or refining product narrative
+- Preparing launches, landing pages, or feature announcements
+- Choosing how to frame a new capability for a target audience
+- Aligning product, UX, and marketing language around one story
+
+## Inputs to gather
+
+- Target audience and their pain points
+- Product capability, strengths, and evidence
+- Competitive or alternative solutions
+- Business goal of the messaging effort
+
+## How to work
+
+- Start with audience pain or desired outcome, then connect the product to that need.
+- Distinguish core value, supporting proof, and differentiators.
+- Avoid vague slogans unless they are backed by a concrete explanation.
+- Stress-test the message against realistic alternatives and skeptical readers.
+- Produce a tight core narrative that other copy can inherit.
+
+## Output expectations
+
+- Clear positioning statement or message framework
+- Defined audience, value proposition, and differentiators
+- Candidate headlines, pillars, or narrative directions when useful
+
+## Quality checklist
+
+- The message is specific about audience and value.
+- Differentiation is real, not generic category language.
+- Claims are supportable by the product.
+- The narrative can guide product copy and campaign content consistently.
+
+## Handoff notes
+
+- Note open questions about audience, market, or product maturity if they limit confidence.
+- Pair with product copy or marketing content to turn the narrative into shipped assets.

skills/marketing/product-copy.md

@@ -0,0 +1,45 @@
+# Product Copy
+
+## Purpose
+
+Write concise, user-facing product language that is clear, useful, on-brand, and matched to the immediate interface or conversion context.
+
+## When to use
+
+- Naming buttons, labels, helper text, empty states, and error messages
+- Tightening landing page or feature page copy
+- Improving clarity and persuasion in product-adjacent text
+- Rewriting awkward or confusing interface wording
+
+## Inputs to gather
+
+- Audience, goal, and context of the text
+- Current product voice and terminology
+- UI constraints such as length, hierarchy, and surrounding elements
+- Desired action or decision the copy should support
+
+## How to work
+
+- Optimize for clarity first, persuasion second, cleverness last.
+- Use the words users expect based on the product and task.
+- Match the level of confidence and urgency to the action being requested.
+- Keep text tight and scannable, especially in UI contexts.
+- Offer alternatives when tone or positioning is uncertain.
+
+## Output expectations
+
+- Final copy or strong candidate options
+- Brief rationale when choosing between meaningful directions
+- Notes on character, tone, or placement constraints when relevant
+
+## Quality checklist
+
+- Copy is clear on first read.
+- The wording fits the user's moment and intent.
+- Claims are credible and specific.
+- Text length is appropriate to the surface.
+
+## Handoff notes
+
+- Note if final selection depends on brand voice or product strategy not yet defined.
+- Pair with UX review for interface clarity and with messaging/positioning for strategic alignment.

skills/software/api-backend.md

@@ -0,0 +1,45 @@
+# API and Backend Work
+
+## Purpose
+
+Guide server-side, service, API, data, and integration changes with attention to contracts, compatibility, failure handling, and operational impact.
+
+## When to use
+
+- Modifying endpoints, handlers, services, jobs, or data flows
+- Adding or changing schemas, persistence, or integration behavior
+- Working on backend business logic or infrastructure-facing code
+- Investigating performance, reliability, or contract issues on the server side
+
+## Inputs to gather
+
+- API contracts, schema, storage models, and service boundaries
+- Existing validation, auth, error handling, and observability patterns
+- Compatibility constraints for clients, data, and deployments
+- Current tests and representative request or event flows
+
+## How to work
+
+- Trace the full request or job lifecycle before changing a boundary.
+- Preserve compatibility intentionally or document the break clearly.
+- Handle validation, authorization, error responses, and retries in line with existing system behavior.
+- Consider migration, rollout, and operational visibility when data or contracts change.
+- Add or update tests at the right layer for the change.
+
+## Output expectations
+
+- Working backend change with contract implications made explicit
+- Notes on schema, config, data, or rollout impact
+- Verification results covering the critical paths
+
+## Quality checklist
+
+- Inputs and outputs are validated appropriately.
+- Failure handling is explicit and consistent.
+- Compatibility and migration impact are understood.
+- Logging, metrics, or observability concerns are addressed when relevant.
+
+## Handoff notes
+
+- Call out any required coordination with frontend, data migration, configuration, or deployment steps.
+- Note backwards-incompatible changes clearly and early.

skills/software/architecture-system-design.md

@@ -0,0 +1,45 @@
+# Architecture and System Design
+
+## Purpose
+
+Shape meaningful technical direction so systems stay understandable, evolvable, and aligned with product needs over time.
+
+## When to use
+
+- Designing a major feature or subsystem
+- Changing service boundaries, module boundaries, or core data flow
+- Evaluating multiple implementation approaches with long-term consequences
+- Preparing work that will influence maintainability, scale, or team velocity
+
+## Inputs to gather
+
+- Current architecture, boundaries, and pain points
+- Product goals, scale expectations, and reliability constraints
+- Existing patterns, platform constraints, and team operating model
+- Compatibility, migration, and rollout concerns
+
+## How to work
+
+- Start from the user or system outcome, then identify the simplest architecture that supports it well.
+- Make tradeoffs explicit: complexity, performance, reliability, maintainability, and delivery speed.
+- Preserve useful existing boundaries unless there is a clear reason to change them.
+- Prefer designs that are easy to operate and easy for the team to understand.
+- Document why the chosen path is better than the main alternatives.
+
+## Output expectations
+
+- Clear recommended design or architecture direction
+- Explicit tradeoffs and constraints
+- Interfaces, boundaries, and rollout considerations that matter for implementation
+
+## Quality checklist
+
+- The design solves the actual problem, not a hypothetical future one.
+- Tradeoffs are named clearly enough to guide later decisions.
+- Complexity is justified by concrete needs.
+- Operational and migration consequences are not ignored.
+
+## Handoff notes
+
+- Pair with architecture decision records when the choice should be preserved for future contributors.
+- Call out which parts are decided versus intentionally deferred.

skills/software/code-review.md

@@ -0,0 +1,45 @@
+# Code Review
+
+## Purpose
+
+Review code with a bug-finding mindset that prioritizes correctness, regressions, risky assumptions, edge cases, and missing tests over style commentary.
+
+## When to use
+
+- Reviewing a pull request or patch
+- Auditing a risky change before merge
+- Evaluating whether a change is safe to ship
+- Checking for test and documentation gaps
+
+## Inputs to gather
+
+- The diff or changed files
+- Nearby code paths and contracts affected by the change
+- Existing tests, especially those intended to cover the modified behavior
+- Context on expected behavior, rollout risk, and compatibility requirements
+
+## How to work
+
+- Start with correctness, then move to regressions, then test gaps, then maintainability risks.
+- Trace changed code through call sites, error paths, and data flow rather than reading only the edited lines in isolation.
+- Focus comments on issues that materially affect behavior, safety, or maintainability.
+- Be explicit about severity and the concrete consequence of each issue.
+- Keep summary brief after listing the findings.
+
+## Output expectations
+
+- A prioritized list of findings with clear reasoning
+- Open questions or assumptions that affect confidence
+- Brief summary of overall risk after the findings
+
+## Quality checklist
+
+- Findings identify real behavior or verification risk, not cosmetic preferences.
+- Severity is proportional to user impact and likelihood.
+- Missing tests are called out where they reduce confidence materially.
+- If no issues are found, residual risk and coverage gaps are still noted.
+
+## Handoff notes
+
+- Include file references and tight line references when available.
+- Distinguish confirmed issues from lower-confidence concerns.

skills/software/database-migrations.md

@@ -0,0 +1,45 @@
+# Database Migrations and Data Evolution
+
+## Purpose
+
+Change schemas and data safely while protecting compatibility, correctness, rollout reliability, and recovery options.
+
+## When to use
+
+- Adding, removing, or changing database schema
+- Backfilling or transforming data
+- Introducing compatibility windows between old and new code
+- Planning rollout for data-sensitive changes
+
+## Inputs to gather
+
+- Current schema, access patterns, and data volume
+- Migration tooling and deployment model
+- Compatibility requirements across services, jobs, or clients
+- Rollback constraints and data recovery options
+
+## How to work
+
+- Prefer staged migrations when compatibility matters: expand, backfill, switch reads or writes, then contract.
+- Minimize lock risk, data loss risk, and long-running migration risk.
+- Consider how old and new code will coexist during rollout.
+- Define verification steps for schema state and critical data correctness.
+- Document irreversible steps and operator actions clearly.
+
+## Output expectations
+
+- Safe migration plan or implementation
+- Compatibility and rollout notes
+- Verification and rollback considerations
+
+## Quality checklist
+
+- The migration is safe for the repository's deployment model.
+- Data correctness is protected during and after rollout.
+- Backwards and forwards compatibility are considered when needed.
+- Irreversible or risky steps are made explicit.
+
+## Handoff notes
+
+- Call out sequencing requirements across application code, migrations, and background jobs.
+- Pair with release/change summary and technical docs when operators or teammates need a clear rollout path.

skills/software/dependency-lifecycle.md

@@ -0,0 +1,45 @@
+# Dependency Lifecycle Management
+
+## Purpose
+
+Keep dependencies healthy over time by balancing security, compatibility, maintainability, and upgrade cost.
+
+## When to use
+
+- Upgrading libraries, frameworks, runtimes, or tooling
+- Auditing dependency risk or staleness
+- Reducing upgrade backlog and ecosystem drift
+- Planning how to adopt breaking changes safely
+
+## Inputs to gather
+
+- Current dependency versions and their role in the system
+- Changelogs, upgrade guides, and breaking changes
+- Existing test coverage and high-risk integration points
+- Security, support-window, or maintenance concerns
+
+## How to work
+
+- Prefer focused upgrade batches that are easy to validate and revert.
+- Separate mechanical version bumps from behavior-changing adaptation when possible.
+- Read authoritative release notes before changing usage patterns.
+- Verify the highest-risk integration paths, not just installation success.
+- Capture follow-up work when a safe incremental upgrade leaves known deprecated patterns behind.
+
+## Output expectations
+
+- Upgrade plan or completed upgrade with adaptation notes
+- Risk summary for changed dependencies
+- Verification results and known remaining debt
+
+## Quality checklist
+
+- The upgrade reduces risk or maintenance burden meaningfully.
+- Breaking changes are understood before implementation.
+- Validation covers the most likely failure surfaces.
+- Residual deprecations or postponed steps are documented clearly.
+
+## Handoff notes
+
+- Note whether the work is a full upgrade, a safe intermediate step, or a reconnaissance pass.
+- Pair with test strategy and release/change summary when adoption affects developer workflow or runtime behavior.

skills/software/feature-implementation.md

@@ -0,0 +1,48 @@
+# Feature Implementation
+
+## Purpose
+
+Guide implementation of new behavior or meaningful changes to existing behavior with a bias toward working software, repository alignment, and practical verification.
+
+## When to use
+
+- Building a new feature
+- Expanding an existing workflow
+- Making a multi-file change that affects user or developer behavior
+- Turning a scoped request into implemented code
+
+## Inputs to gather
+
+- Relevant entrypoints, modules, and surrounding patterns
+- Existing interfaces, types, schema, and tests
+- User goal, success criteria, constraints, and impacted surfaces
+- Any repository instructions that override generic defaults
+
+## How to work
+
+- Inspect the codebase before editing and identify the smallest coherent change set.
+- Prefer existing patterns over introducing novel structure unless the current patterns are clearly limiting.
+- Implement end-to-end behavior, not just partial scaffolding, when feasible.
+- Keep logic changes close to the relevant module boundaries and avoid unrelated cleanup unless it materially helps the task.
+- Validate with targeted tests, builds, or manual checks appropriate to the repository.
+- Update docs, examples, or change notes when the feature alters usage or expectations.
+
+## Output expectations
+
+- A working implementation or a clearly explained blocker
+- Concise summary of what changed and why
+- Validation results and any gaps that remain
+- Notes on follow-up work only when it is genuinely important
+
+## Quality checklist
+
+- The change matches the stated goal and avoids unrelated churn.
+- Naming, structure, and style fit the existing codebase.
+- Errors, edge cases, and obvious failure paths are handled.
+- Verification is appropriate for the size and risk of the change.
+- User-facing or developer-facing behavior changes are documented when needed.
+
+## Handoff notes
+
+- Mention touched subsystems and any assumptions made because the repo did not answer them.
+- Call out migration or rollout concerns if the feature affects data, config, or compatibility.

skills/software/frontend-ui-implementation.md

@@ -0,0 +1,45 @@
+# Frontend UI Implementation
+
+## Purpose
+
+Guide interface implementation that balances correctness, usability, clarity, performance, and consistency with the existing product experience.
+
+## When to use
+
+- Building or updating pages, components, and interactions
+- Implementing client-side state or view logic
+- Adjusting layout, form flows, states, and visual feedback
+- Shipping UI changes tied to product behavior
+
+## Inputs to gather
+
+- Existing design system, component patterns, and styling conventions
+- User flow, content requirements, and responsive constraints
+- State, API, and error/loading behavior tied to the UI
+- Current tests, stories, screenshots, or acceptance criteria if available
+
+## How to work
+
+- Preserve the established visual language unless the task explicitly calls for a new direction.
+- Design for the full experience: loading, empty, error, success, and edge states.
+- Keep interaction logic understandable and avoid overengineering small UI behavior.
+- Use content, hierarchy, and spacing intentionally so the UI communicates clearly.
+- Validate on the most important screen sizes or states that the repository can reasonably support.
+
+## Output expectations
+
+- A functional UI change that is coherent visually and behaviorally
+- Clear notes on user-facing behavior and state handling
+- Verification appropriate to the stack, such as tests, stories, or manual checks
+
+## Quality checklist
+
+- The UI is understandable without hidden assumptions.
+- Important states are handled, not just the happy path.
+- Visual and code patterns fit the existing app.
+- Accessibility, responsiveness, and copy quality are considered.
+
+## Handoff notes
+
+- Mention any UX debts, unresolved visual questions, or browser/device gaps that remain.
+- Pair with UX review or product copy when usability or wording is central to the task.

skills/software/maintenance-technical-debt.md

@@ -0,0 +1,45 @@
+# Maintenance and Technical Debt Planning
+
+## Purpose
+
+Turn vague maintenance needs into a practical, sequenced plan that improves delivery speed, reliability, and future change safety over time.
+
+## When to use
+
+- The codebase has accumulated risky or slowing debt
+- A team needs to prioritize cleanup against feature work
+- Repeated friction suggests structural maintenance investment is overdue
+- You need to explain why maintenance work matters in product terms
+
+## Inputs to gather
+
+- Known pain points, repeated failures, and slow areas in delivery
+- Architectural hotspots, obsolete patterns, and fragile dependencies
+- Team constraints, roadmap pressure, and acceptable disruption
+- Evidence of cost: incidents, churn, slowed feature work, or support burden
+
+## How to work
+
+- Focus on debt that materially changes future delivery, reliability, or risk.
+- Group issues into themes rather than a flat list of annoyances.
+- Prioritize by impact, urgency, and dependency relationships.
+- Prefer incremental sequences that can ship safely between feature work.
+- Translate maintenance value into outcomes the team can defend.
+
+## Output expectations
+
+- Prioritized maintenance plan or backlog proposal
+- Clear rationale for what should happen now versus later
+- Sequencing guidance and expected payoff
+
+## Quality checklist
+
+- Recommendations are tied to real delivery or reliability pain.
+- Prioritization is explicit and defensible.
+- The plan is incremental enough to execute.
+- Work is framed in terms of reduced risk or increased velocity, not vague cleanliness.
+
+## Handoff notes
+
+- Note what evidence would strengthen or change the prioritization.
+- Pair with roadmap and opportunity prioritization when balancing debt against new initiatives.

skills/software/observability-operability.md

@@ -0,0 +1,45 @@
+# Observability and Operability
+
+## Purpose
+
+Make systems easier to understand, debug, and run by improving signals, diagnostics, and operational readiness around important behavior.
+
+## When to use
+
+- A system is hard to diagnose in production or staging
+- New functionality needs useful logs, metrics, traces, or alerts
+- Operational ownership is unclear during failures or rollout
+- Reliability work needs better visibility before deeper changes
+
+## Inputs to gather
+
+- Critical workflows, failure modes, and current diagnostic signals
+- Existing logging, metrics, tracing, dashboards, and alerts
+- Operator needs during rollout, incident response, and debugging
+- Noise constraints and performance or cost considerations
+
+## How to work
+
+- Instrument the questions a responder will need answered during failure.
+- Prefer signals tied to user-impacting behavior over vanity metrics.
+- Make logs structured and actionable when possible.
+- Add observability close to important boundaries and state transitions.
+- Keep signal quality high by avoiding low-value noise.
+
+## Output expectations
+
+- Improved observability or an operability plan for the target area
+- Clear explanation of what new signals reveal
+- Notes on alerting, dashboard, or rollout support when relevant
+
+## Quality checklist
+
+- Signals help detect and diagnose meaningful failures.
+- Instrumentation is focused and not excessively noisy.
+- Operational usage is considered, not just implementation convenience.
+- Added visibility maps to critical user or system outcomes.
+
+## Handoff notes
+
+- Mention what incidents or debugging tasks the new observability should make easier.
+- Pair with debugging workflow, incident response, or performance optimization when diagnosis is the main bottleneck.

skills/software/performance-optimization.md

@@ -0,0 +1,45 @@
+# Performance Optimization
+
+## Purpose
+
+Improve responsiveness and efficiency by focusing on the bottlenecks that matter most to users, systems, or operating cost.
+
+## When to use
+
+- Investigating slow pages, endpoints, jobs, or queries
+- Reducing memory, CPU, network, or rendering overhead
+- Preventing regressions in critical paths
+- Prioritizing optimization work with limited time
+
+## Inputs to gather
+
+- Performance symptoms, target metrics, and critical user or system paths
+- Existing measurements, profiles, logs, traces, or benchmarks
+- Current architecture and known hot spots
+- Acceptable tradeoffs in complexity, cost, and feature scope
+
+## How to work
+
+- Measure or inspect evidence before optimizing.
+- Focus on the dominant bottleneck rather than broad cleanup.
+- Prefer changes that improve the critical path without making the system harder to maintain.
+- Re-measure after changes when possible.
+- Capture the conditions under which the optimization matters so future work does not cargo-cult it.
+
+## Output expectations
+
+- Bottleneck diagnosis and recommended or implemented improvement
+- Before-and-after evidence when available
+- Notes on tradeoffs, limits, and remaining hot spots
+
+## Quality checklist
+
+- Optimization targets a real bottleneck.
+- Claimed gains are grounded in evidence, not assumption alone.
+- Complexity added by the optimization is justified.
+- Regression risk is considered for correctness and maintainability.
+
+## Handoff notes
+
+- Note whether the result is measured, estimated, or hypothesis-driven.
+- Pair with observability and operability when instrumentation is weak.

skills/software/refactoring.md

@@ -0,0 +1,45 @@
+# Refactoring
+
+## Purpose
+
+Improve code structure, readability, maintainability, or modularity without intentionally changing externally observable behavior.
+
+## When to use
+
+- Simplifying complex logic
+- Extracting clearer abstractions
+- Reducing duplication or coupling
+- Preparing code for future work while preserving behavior
+
+## Inputs to gather
+
+- Current behavior and tests that define expected outcomes
+- Structural pain points in the relevant modules
+- Constraints around public APIs, compatibility, or performance
+- Existing patterns for abstraction and module boundaries
+
+## How to work
+
+- Preserve behavior intentionally and define what must remain unchanged before editing.
+- Favor small, reviewable moves over sweeping rewrites unless the code is already unsafe to work in incrementally.
+- Keep interface changes minimal and justified.
+- Add or strengthen tests when behavior preservation is important and current coverage is weak.
+- Separate cleanup that supports the refactor from unrelated aesthetic changes.
+
+## Output expectations
+
+- Cleaner code with behavior preserved
+- Clear explanation of the structural improvement
+- Verification evidence that the refactor did not break expected behavior
+
+## Quality checklist
+
+- Intended behavior is unchanged unless explicitly documented otherwise.
+- The resulting structure is easier to understand or extend.
+- Interface changes are minimal, justified, and documented.
+- Added complexity is avoided unless it buys meaningful maintainability.
+
+## Handoff notes
+
+- Call out any areas where behavior preservation is inferred rather than strongly verified.
+- Note future cleanup opportunities only if they naturally follow from the refactor.

skills/software/release-change-summary.md

@@ -0,0 +1,45 @@
+# Release and Change Summary
+
+## Purpose
+
+Explain shipped or proposed changes clearly for developers, operators, collaborators, or end users, with emphasis on what changed, why it matters, and what action is required.
+
+## When to use
+
+- Writing release notes or changelog entries
+- Summarizing completed engineering work
+- Explaining migration or rollout impact
+- Turning technical changes into clear stakeholder communication
+
+## Inputs to gather
+
+- The actual code or product changes
+- Intended audience and their level of technical depth
+- Any rollout, migration, compatibility, or operational considerations
+- Linked docs, issues, or feature context that explains why the change exists
+
+## How to work
+
+- Lead with the user-meaningful change, not internal implementation trivia.
+- Group related changes into a few clear themes rather than a raw diff dump.
+- Call out required actions, migrations, or risks explicitly.
+- Tailor the level of detail to the audience.
+- Keep the summary accurate to the implementation that actually landed.
+
+## Output expectations
+
+- Clear release notes, summary, or change communication draft
+- Audience-appropriate explanation of impact and required action
+- Explicit mention of follow-up items only when relevant
+
+## Quality checklist
+
+- The summary matches the real change, not the original intent alone.
+- Important caveats, migrations, and compatibility notes are visible.
+- Wording is concise and easy to scan.
+- Audience knowledge level is respected.
+
+## Handoff notes
+
+- Say who the summary is for and what medium it targets if that is not obvious.
+- Pair with technical docs or marketing skills when the output needs deeper explanation or stronger positioning.

skills/software/repo-exploration.md

@@ -0,0 +1,44 @@
+# Repository Exploration
+
+## Purpose
+
+Rapidly build accurate context before implementation, debugging, or planning by identifying the right files, flows, conventions, and constraints in the repository.
+
+## When to use
+
+- Starting in an unfamiliar repository
+- Locating the right implementation area for a request
+- Understanding current architecture before proposing changes
+- Reducing ambiguity in a vague task
+
+## Inputs to gather
+
+- Repository layout, entrypoints, and key modules
+- Build, test, and dependency configuration
+- Existing patterns for similar features or workflows
+- Any local instructions, docs, or conventions already in the repo
+
+## How to work
+
+- Start broad, then narrow quickly to the files and flows relevant to the task.
+- Favor authoritative sources in the repo such as configs, types, interfaces, docs, and existing implementations.
+- Identify where decisions are already made by the codebase so you do not reinvent them.
+- Summarize findings in terms of how they affect the next action.
+- Stop exploring once the path to execution is clear enough.
+
+## Output expectations
+
+- Concise map of the relevant code paths and conventions
+- Recommended starting points for changes or further investigation
+- Key unknowns that still require validation
+
+## Quality checklist
+
+- Exploration answers practical implementation questions rather than producing generic architecture prose.
+- Findings are tied to concrete files, modules, or workflows.
+- Enough context is gathered to act confidently without over-reading the entire repo.
+
+## Handoff notes
+
+- Mention the most relevant files, commands, and repo conventions discovered.
+- Flag ambiguous areas where multiple plausible implementation paths exist.

skills/software/security-review-hardening.md

@@ -0,0 +1,45 @@
+# Security Review and Hardening
+
+## Purpose
+
+Reduce avoidable security risk by reviewing trust boundaries, sensitive data handling, exposure paths, and abuse opportunities in the relevant system area.
+
+## When to use
+
+- Shipping authentication, authorization, input handling, or sensitive workflows
+- Reviewing an externally exposed feature or API
+- Auditing risky changes for common security failures
+- Hardening an existing system area with known gaps
+
+## Inputs to gather
+
+- Trust boundaries, user roles, and entry points
+- Sensitive data flows, secrets, tokens, or privileged operations
+- Existing auth, validation, logging, and rate limiting patterns
+- Relevant compliance or threat concerns if known
+
+## How to work
+
+- Start with who can do what, from where, and with which inputs.
+- Check validation, authorization, data exposure, secret handling, and abuse resistance.
+- Prefer concrete mitigations over vague warnings.
+- Align with existing security controls unless they are clearly insufficient.
+- Call out unverified areas when the environment or tooling limits confidence.
+
+## Output expectations
+
+- Concrete risks found or a scoped hardening plan
+- Recommended mitigations tied to the actual threat surface
+- Clear statement of confidence and any blind spots
+
+## Quality checklist
+
+- Review covers the real trust boundaries and attack surface.
+- Findings describe exploit consequence, not just theoretical concern.
+- Mitigations are practical for the system and team.
+- Residual risk is visible where hardening is incomplete.
+
+## Handoff notes
+
+- Separate must-fix risks from defense-in-depth improvements.
+- Pair with code review, API/backend work, and observability when the issue spans implementation and detection.

skills/software/test-strategy.md

@@ -0,0 +1,45 @@
+# Test Strategy
+
+## Purpose
+
+Choose and evaluate the right level of verification so changes are covered proportionally to their risk, behavior, and maintenance cost.
+
+## When to use
+
+- Adding or updating tests for a feature or bug fix
+- Deciding what verification is necessary before shipping
+- Auditing coverage gaps in existing code
+- Designing regression protection for risky areas
+
+## Inputs to gather
+
+- The behavior being changed or protected
+- Current test layout, tooling, and conventions
+- Known failure modes, regressions, or edge cases
+- Constraints on test speed, environment, and confidence needs
+
+## How to work
+
+- Match test level to risk: unit for logic, integration for boundaries, end-to-end for critical workflows.
+- Prefer the smallest test that meaningfully protects the behavior.
+- Cover success paths, likely failure paths, and regressions suggested by the change.
+- Reuse existing fixtures and patterns where possible.
+- If tests are not feasible, define alternate validation steps and explain the gap.
+
+## Output expectations
+
+- Specific recommended or implemented tests
+- Clear rationale for test level and scope
+- Any remaining uncovered risks or follow-up test ideas
+
+## Quality checklist
+
+- Tests target behavior, not implementation trivia.
+- Coverage includes the change's highest-risk paths.
+- Test design fits repository conventions and runtime cost expectations.
+- Non-tested areas are called out explicitly when important.
+
+## Handoff notes
+
+- Note flaky, expensive, or environment-dependent checks separately from fast local confidence checks.
+- Mention whether the test plan is implemented, recommended, or partially blocked.

skills/ui-ux/accessibility-review.md

@@ -0,0 +1,45 @@
+# Accessibility Review
+
+## Purpose
+
+Improve inclusive usability by checking whether interfaces are operable, understandable, and robust for people using different devices, input methods, and assistive technologies.
+
+## When to use
+
+- Reviewing or implementing user-facing UI
+- Checking forms, dialogs, navigation, or interactive states
+- Improving keyboard support, semantics, contrast, or feedback
+- Raising the quality bar for long-lived interface patterns
+
+## Inputs to gather
+
+- Relevant screens, components, and interaction flows
+- Existing design system, semantic patterns, and accessibility goals
+- Keyboard, screen reader, focus, contrast, and motion considerations
+- Known constraints in the stack or component library
+
+## How to work
+
+- Check the main user path with keyboard and semantics in mind first.
+- Review labels, focus order, state announcements, contrast, and error clarity.
+- Prioritize issues that block task completion or create major confusion.
+- Recommend changes that fit the current implementation model and team capacity.
+- Treat accessibility as product quality, not a final polish pass.
+
+## Output expectations
+
+- Clear accessibility findings or implementation guidance
+- Prioritized fixes by impact on usability and inclusion
+- Notes on what was inspected directly versus inferred
+
+## Quality checklist
+
+- Findings focus on real interaction barriers.
+- Recommendations are specific enough to implement.
+- The review covers both semantics and user experience.
+- High-impact accessibility gaps are surfaced early.
+
+## Handoff notes
+
+- Mention whether checks were code-based, visual, or manually reasoned.
+- Pair with frontend UI implementation and design system consistency when shipping durable fixes.

skills/ui-ux/design-system-consistency.md

@@ -0,0 +1,45 @@
+# Design System and UI Consistency
+
+## Purpose
+
+Promote reusable, scalable UI patterns so the interface stays coherent as the product grows.
+
+## When to use
+
+- A UI area is drifting from existing patterns
+- Reusable components or patterns should replace one-off implementations
+- A feature adds new patterns that may affect future screens
+- You want to improve consistency without a full redesign
+
+## Inputs to gather
+
+- Existing components, tokens, layout patterns, and style conventions
+- The new or changed UI requirements
+- Current inconsistencies, duplication, or local hacks
+- Constraints from the stack, theme system, or design resources
+
+## How to work
+
+- Reuse existing components and conventions before inventing new ones.
+- Introduce new patterns only when the current system cannot express the need cleanly.
+- Optimize for maintainability and consistency, not just a one-screen outcome.
+- Keep component APIs and styling patterns understandable.
+- Document new reusable patterns when they materially expand the design system.
+
+## Output expectations
+
+- More consistent UI implementation or a clear plan for pattern consolidation
+- Notes on reused versus newly introduced patterns
+- Guidance on where the system should expand carefully
+
+## Quality checklist
+
+- The UI becomes more coherent, not more fragmented.
+- Reuse is meaningful and does not force a poor fit.
+- New abstractions are justified by repeated or durable need.
+- The solution helps future features move faster.
+
+## Handoff notes
+
+- Note whether the work is local cleanup, reusable component work, or system-level direction.
+- Pair with UX review and frontend implementation when consistency changes affect behavior and clarity.

skills/ui-ux/ux-review.md

@@ -0,0 +1,45 @@
+# UX Review
+
+## Purpose
+
+Evaluate an interface or flow for clarity, usability, friction, trust, and task completion quality, then turn those observations into actionable improvements.
+
+## When to use
+
+- Reviewing a screen or flow before or after implementation
+- Looking for usability issues in forms, navigation, settings, or onboarding
+- Improving hierarchy, copy clarity, state handling, or feedback
+- Assessing whether an interface supports the intended user goal well
+
+## Inputs to gather
+
+- Screens, flows, components, or descriptions of the experience
+- Target user goal and success criteria
+- Existing design system or product patterns
+- Constraints such as device, context, accessibility, or content requirements
+
+## How to work
+
+- Review from the user's task perspective rather than from the component tree outward.
+- Check whether the next action is obvious at each step.
+- Evaluate hierarchy, wording, spacing, feedback, and state transitions together.
+- Prioritize issues by how much they block comprehension, confidence, or completion.
+- Suggest improvements that fit the current product language unless redesign is requested.
+
+## Output expectations
+
+- Clear list of UX issues or strengths
+- Prioritized recommendations with rationale
+- Notes on where UI changes, copy changes, or research would help most
+
+## Quality checklist
+
+- Feedback is tied to user outcomes, not vague aesthetic preference.
+- Important states such as empty, loading, error, and success are considered.
+- Recommendations are specific enough to act on.
+- Suggestions fit the product's current level of complexity and style.
+
+## Handoff notes
+
+- Distinguish between usability issues, visual polish issues, and copy issues.
+- Pair with frontend implementation or product copy when turning review into shipped changes.

utils/audio_utils.py

@@ -0,0 +1,49 @@
+"""
+Audio utilities — microphone capture helpers using PyAudio.
+Captures audio from the default input device and returns WAV bytes.
+"""
+import io
+import wave
+import pyaudio
+
+CHUNK = 1024
+FORMAT = pyaudio.paInt16
+CHANNELS = 1
+RATE = 16000
+
+def record_audio(duration: float = 5.0) -> bytes:
+    """
+    Record audio from default microphone for the given duration.
+    Returns raw WAV bytes compatible with Whisper.
+    """
+    p = pyaudio.PyAudio()
+    stream = p.open(
+        format=FORMAT, channels=CHANNELS,
+        rate=RATE, input=True, frames_per_buffer=CHUNK
+    )
+    frames = []
+    for _ in range(int(RATE / CHUNK * duration)):
+        data = stream.read(CHUNK, exception_on_overflow=False)
+        frames.append(data)
+    stream.stop_stream()
+    stream.close()
+    p.terminate()
+
+    buf = io.BytesIO()
+    with wave.open(buf, 'wb') as wf:
+        wf.setnchannels(CHANNELS)
+        wf.setsampwidth(p.get_sample_size(FORMAT))
+        wf.setframerate(RATE)
+        wf.writeframes(b''.join(frames))
+    return buf.getvalue()
+
+def list_audio_devices() -> list[dict]:
+    """List all available audio input devices."""
+    p = pyaudio.PyAudio()
+    devices = []
+    for i in range(p.get_device_count()):
+        info = p.get_device_info_by_index(i)
+        if info['maxInputChannels'] > 0:
+            devices.append({'index': i, 'name': info['name']})
+    p.terminate()
+    return devices

utils/window_utils.py

@@ -0,0 +1,43 @@
+"""
+Windows window utilities using win32gui.
+Enumerate and manage application windows.
+"""
+try:
+    import win32gui
+    import win32con
+
+    def get_active_window() -> dict:
+        hwnd = win32gui.GetForegroundWindow()
+        return {
+            'hwnd': hwnd,
+            'title': win32gui.GetWindowText(hwnd)
+        }
+
+    def list_windows() -> list[dict]:
+        windows = []
+        def _enum(hwnd, _):
+            if win32gui.IsWindowVisible(hwnd):
+                title = win32gui.GetWindowText(hwnd)
+                if title:
+                    windows.append({'hwnd': hwnd, 'title': title})
+        win32gui.EnumWindows(_enum, None)
+        return windows
+
+    def focus_window(title_substring: str) -> bool:
+        """Bring a window to foreground by partial title match."""
+        def _enum(hwnd, _):
+            if title_substring.lower() in win32gui.GetWindowText(hwnd).lower():
+                win32gui.SetForegroundWindow(hwnd)
+                return False
+        win32gui.EnumWindows(_enum, None)
+        return True
+
+except ImportError:
+    def get_active_window():
+        return {'hwnd': None, 'title': 'Unknown (pywin32 not installed)'}
+
+    def list_windows():
+        return []
+
+    def focus_window(title_substring: str):
+        return False